Files
Enterprise-Knowledge-Base/cli/CHANGELOG.md
T
nullkey f89d54362d feat(cli): doc/kb resource expansion — upload flags + list filters + view fields
Closes deep-tuning gaps in v0.4-shipped doc / kb / session commands.
Each command had multiple SDK fields the CLI silently hardcoded or
omitted; this commit threads them through.

doc upload:
- --enable-multimodel (tri-state via NoOptDefVal): toggle multimodal
  extraction (PDF/DOCX image-to-text) per upload. Empty explicit
  value (e.g. --enable-multimodel="" from uninterpolated shell var)
  rejected as input.invalid_argument rather than silently coerced.
- --metadata key=value (repeatable): attach arbitrary metadata
- --channel <name> (default api, override for browser / wechat ingests)
- URL mode gains --title / --file-type / --tag-id; URL-only flags
  rejected with input.invalid_argument when used without --from-url

doc list filter flags:
- --keyword (server-side LIKE — case-sensitive per PG)
- --file-type / --source / --tag-id
- --start-time / --end-time (RFC3339)

search docs switches from client-side substring to server-side Keyword
via ListKnowledgeWithFilter — smaller wire payload, but case-sensitivity
shifts (documented in CHANGELOG + help text + Long).

MCP doc_list schema gains the same 6 filter fields (parity with CLI).

session view --full + --limit: loads chat history via LoadMessages SDK
method.

kb view human KV expanded: type / pinned / temporary / processing
state + count / summary model / created timestamp. All omit-empty.

doc view human KV expanded: title (when distinct from filename) /
description / source / channel / summary_status / enable_status /
tag_id / storage (human bytes) / file_hash (12-char prefix).
2026-05-16 16:56:33 +08:00

171 lines
9.0 KiB
Markdown

# Changelog — `weknora` CLI
All notable changes to the `weknora` CLI (the binary under `cli/` in this
repository) will be documented in this file.
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and the CLI follows [Semantic Versioning](https://semver.org/) independently
of the WeKnora server / frontend release cadence.
CLI history before v0.3 is recorded in the project root
[CHANGELOG.md](../CHANGELOG.md) under the release that introduced the CLI.
## [Unreleased]
### v0.5 — agent CRUD, chunk subtree, MCP chunk_list, audit-driven cleanup
#### Added
- `weknora agent create <name> --model <id>` / `agent edit <id>` /
`agent delete <id>` — hybrid surface (8 hot-path flags + `--config-file`
YAML/JSON tail + `--generate-skeleton` template emit). `--from <agent-id>`
copies from an existing agent.
- `weknora chunk list --doc <doc-id>` / `chunk view <chunk-id>` /
`chunk delete <chunk-id> --doc <doc-id>` — new subtree for RAG retrieval
debug. Paginated with v0.4 `--limit` / `--page-size` / `--all-pages` canon.
- `weknora mcp serve` adds `chunk_list` as the 10th curated tool.
- `weknora agent view <id>` human output now renders all 34 AgentConfig
fields (previously 7), grouped into 10 presentation sections.
- `--all-pages` / `--page-size` on `search docs` and `search sessions`
(catching up with `session list` / `doc list` canon from v0.3+v0.4).
- `weknora doc list` gains `--keyword` / `--file-type` / `--source` /
`--tag-id` / `--start-time` / `--end-time` (RFC3339) — matches the
SDK's `KnowledgeListFilter` surface. Time flags reject malformed
input with `input.invalid_argument`.
- MCP `doc_list` tool gains the same 5 filter fields (`keyword`,
`file_type`, `source`, `tag_id`, `start_time`, `end_time`) so agents
have parity with the CLI.
- `weknora session view --full` (with `--limit`, default 50, bounds
1..1000) loads chat history via `LoadMessages` and renders messages
inline after session metadata. JSON mode projects messages into a
`messages` array. `--limit` without `--full` errors with
`input.invalid_argument`.
- `weknora kb view` human render now includes `TYPE`, `PINNED` (badge,
only when set), `TEMPORARY` (badge), `PROCESSING` (with doc count,
only when active), `SUMMARY MODEL`, and `CREATED`. Nested config
structs stay JSON-only.
- `weknora doc view` human render expands to include `TITLE` (when
distinct from filename), `DESC`, `SOURCE`, `CHANNEL`, `TAG`,
`STORAGE` (human-readable bytes), `SUMMARY`, `ENABLED`, and `HASH`
(12-char prefix). All omit-empty.
#### Fixed
- MCP `search_chunks` tool: `limit` arg now correctly threads into
`SearchParams.MatchCount`. Previously the server's default cap won,
silently capping below the requested limit.
- `search sessions` human time format: now uses `fuzzyTime` like
`session list` instead of raw RFC3339.
#### Changed
- `cli/AGENTS.md` MCP curation rationale rewritten: curated read-only
is a deliberate product call gated on server-side token scope, not
MCP industry canon.
- `cli/AGENTS.md` adds §"Command surface design SOP" and
§"CRUD command flag canon" for v0.6+ contributors.
- `cli/go.mod`: adds `gopkg.in/yaml.v3` for `agent create --config-file`.
- `weknora search docs` now applies the keyword filter server-side via
`ListKnowledgeWithFilter` (was: page through every doc and substring-
match client-side). Smaller wire payload on large KBs. **Semantics
shift**: the match is now case-sensitive (server uses `LIKE %keyword%`),
whereas the previous client-side path lowered both sides. Callers that
relied on case-insensitive matching (e.g. `search docs Q3` finding
`q3 retro`) must lower-case the query, or fall back to `weknora api`
with a custom filter.
### v0.4 — output contract hardening and mainstream alignment
#### Breaking changes
- Dropped the JSON envelope. `stdout` now emits bare typed data
(`{...}` or `[...]`); errors are written to `stderr` as `code: msg`
with an actionable `hint:` line. Pipelines using `--json | jq` no
longer have to filter out an envelope wrapper.
- Dropped `--dry-run`. Destructive writes still require `-y/--yes`;
non-TTY callers that omit `-y` exit with code 10 and
`input.confirmation_required` so an agent must surface the prompt
to a human before retrying.
- Dropped the per-command AI footer that rendered when `CLAUDECODE`
or `CURSOR_AGENT` was set. The same machine-readable guidance now
lives in the standard `--help` (visible to all callers) and in
`mcp serve`'s tool descriptions.
#### Added
- `weknora mcp serve` — curated read-only stdio MCP server exposing 9
tools (`kb_list`, `kb_view`, `doc_list`, `doc_view`, `doc_download`,
`search_chunks`, `chat`, `agent_list`, `agent_invoke`). Destructive
verbs are intentionally excluded.
- `weknora agent list` / `agent view` / `agent invoke` — manage and
call WeKnora's server-side Custom Agent resources.
- `weknora auth token` — print the active credential to `stdout` for
scripting (raw secret by default; `--json` emits `{token, mode, context}`).
- `weknora doc upload --from-url` — ingest a remote URL.
- `--json=fields,...` field projection and `--jq <expr>` filtering on
every command that emits JSON.
- `--limit` and `--all-pages` on list / search commands for bounded
output and explicit pagination control.
- Per-resource filter flags: `kb list --pinned`, `doc list --status`,
`session list --since`.
#### Changed
- Go toolchain bumped from 1.24 to 1.26.
- `auth login --with-token` validates the supplied key against
`/auth/me` before persisting, and prints an advisory if the keyring
is unavailable and credentials fall back to a 0600 file under
`$XDG_CONFIG_HOME/weknora/secrets/`.
- AGENTS.md rewritten as a developer guide (~170 lines, 6 H2 sections).
### v0.3 — extended management surface and a `session` subtree
#### Added
- `context add` / `context list` / `context remove` — first-class CRUD over
connection targets (previously implicit via `auth login --name`).
Removing the *current* context requires explicit `-y` (exit-10 protocol)
because subsequent commands have no default target.
- `auth refresh` — exchanges the stored refresh token for a new access +
refresh pair (OAuth refresh-token grant). Transparent 401 → refresh →
retry is also wired into the SDK transport with singleflight de-dup, so
most callers never need to invoke this explicitly.
- `kb edit` — partial-update edit with only-sent-fields semantics
(`*string` options so unset fields stay unset in the PUT body).
- `kb pin` / `kb unpin` — idempotent pin/unpin toggle; no-op when already
in the target state (emits `_meta.warnings`, no server call).
- `kb empty` — bulk-delete documents while preserving the KB record and
its config. High-risk-write; exit-10 confirmation in non-TTY / `--json`
paths.
- `doc view <id>` — show one document's metadata (title, file name,
type, size, parse status, embedding model, processed-at, error
message). Counterpart to `kb view` and `session view`.
- `doc download` — stream a knowledge file to disk (`-O FILE` /
`-O -` for stdout) with `--clobber` controlling overwrite. Rejects
server-supplied path-like filenames; partial writes on error are
cleaned up.
- `doc upload --recursive --glob '*.md'` — walk a directory and upload
every match. Per-file `OK` / `FAIL` progress lines on the human path;
aggregated `uploaded[]` / `failed[]` envelope on `--json`. Exit code
typed to the first failure's class on partial failure.
- `search chunks` / `search kb` / `search docs` / `search sessions` —
verb-noun subtree (gh `search code/repos/issues/…` shape). `search
chunks` is hybrid (vector + keyword) retrieval; the other three are
client-side substring filters useful for discovering identifiers.
All four take `--limit N` / `-L N` (1..1000) to cap returned rows.
- `session list` / `session view` / `session delete` — chat session
management.
- `api --input FILE` / `api --input -` — body source for raw HTTP
passthrough (file or stdin); mutually exclusive with `--data`.
- `unlink` — remove the cwd's `.weknora/project.yaml` so subsequent
commands stop auto-resolving `--kb` from it. Walks up from cwd so a
user in a subdirectory can unlink without cd-ing to the project root
(mirrors `vercel unlink` / `netlify unlink`).
- Completion smoke test guards against cobra bumps silently breaking
bash / zsh / fish / powershell completion.
#### SDK additions (Go client at `client/`, strictly additive)
- `OpenKnowledgeFile(ctx, id) (filename, body io.ReadCloser, err)` — new
primitive returning the body as a stream plus the server-suggested
Content-Disposition filename. `DownloadKnowledgeFile` is now a thin
wrapper (signature unchanged, gained partial-file-on-error cleanup).
- `WithTransport(http.RoundTripper) ClientOption` — lets the CLI install
the 401-retry transport.
- `PathAuthLogin` / `PathAuthRefresh` constants — so HTTP middleware
doesn't re-hardcode the literals.
- `IsPinned bool` field on `KnowledgeBase` (server already returned it;
SDK just hadn't modeled it).