Files
Enterprise-Knowledge-Base/cli/CHANGELOG.md
T
nullkey c87e35b34b chore(cli): polish + docs sync + pre-PR audit fixes
Code-reuse polish (post-implementation review pass):
- Extract text.OneLine(maxWidth, s) helper combining preview-row
  normalization (newline/CR/tab → space) with text.Truncate's
  UTF-8-safe truncation. Replaces agent/view.go truncate1Line (ASCII
  '...' + byte-slice CJK-unsafe) and chunk/list.go singleLine.
- Lift cmdutil.OpenInput(path) for the '-' = stdin / else os.Open
  pattern shared across agent create/edit and the api command.
  Replaces agent/create.go's private openInput.
- Strip inline doc-spec parentheticals from source comments — those
  belong in commit messages and project docs, not in source where
  they rot.

Pre-PR audit fixes:
- doc upload: reject `--metadata` paired with `--from-url` as
  input.invalid_argument up-front (the URL-ingest request type has
  no metadata field server-side, so the pair would otherwise silently
  drop). Long help and CHANGELOG updated to call out the asymmetry.
- doc upload (file path): map sdk.ErrDuplicateFile sentinel to
  resource.already_exists. The sentinel arrives with no "HTTP error <n>:"
  prefix because the SDK short-circuits on file-hash before reading the
  HTTP status, so the previous WrapHTTP fall-through misclassified it
  as network.error with a misleading "check base URL reachability" hint.
  The --from-url branch already handled ErrDuplicateURL this way; this
  closes the asymmetry. Caught by e2e re-upload of an already-ingested
  file; regression test added.
- README exit-10 enumeration adds `agent delete` and `chunk delete`
  (these were missing alongside the v0.5 destructive verbs they were
  meant to gate).

Docs sync:
- cli/README.md: command tree now includes the chunk subtree; adds
  agent / chunk lines to the 5-minute quickstart; adds a "Contributing
  / Reporting issues" section pointing at the repo's SECURITY.md and
  AGENTS.md; drops third-party CLI parallels from the surface
  description.
- cli/AGENTS.md: "Command surface design SOP" gains the
  flag-vs-escape-hatch step. "CRUD command flag canon" renamed to the
  hard-required-flags pattern with the contrast (TTY-prompts-fill)
  defined inline rather than via opaque shorthand.
- cli/CHANGELOG.md: search docs case-sensitivity shift promoted to its
  own #### Breaking changes subsection. MCP doc_list filter count
  corrected from 5 to 6. Drops the bogus go.mod yaml.v3 entry (yaml.v3
  was already a dependency on main; v0.5 added zero go.mod lines).
  Replaces internal-Go identifiers (fuzzyTime, NoOptDefVal) with
  user-language and drops the § section-symbol jargon.
2026-05-16 16:56:33 +08:00

10 KiB

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 and the CLI follows Semantic Versioning independently of the WeKnora server / frontend release cadence.

CLI history before v0.3 is recorded in the project root 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 (hot-path flags for the common fields + --config-file YAML/JSON for the long 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 6 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.
  • weknora doc upload gains --enable-multimodel (tri-state: unset/true/false), repeatable --metadata key=value, and --channel flags. --enable-multimodel and --channel apply to file / --recursive / --from-url; --metadata is file / --recursive only (the URL-ingest request carries no metadata field server-side, so passing it with --from-url is rejected up-front as input.invalid_argument). URL mode additionally accepts --title, --file-type, and --tag-id. Threads through to the SDK's CreateKnowledgeFromFile / CreateKnowledgeFromURL signatures (previously hardcoded to nil/"api" and dropped URL extras).

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 renders a relative duration ("2 hours ago") matching session list, instead of raw RFC3339.
  • doc upload (file path): re-uploading a file already ingested into the KB now surfaces as resource.already_exists (exit 1) instead of the misleading network.error ("check base URL reachability"). The SDK returns its ErrDuplicateFile sentinel with no HTTP error <n>: prefix because the duplicate is detected via file-hash short-circuit, not by HTTP status; the previous fall-through to WrapHTTP therefore misclassified it. The --from-url branch already handled the symmetric ErrDuplicateURL correctly.

Breaking changes

  • 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. 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 themselves, or fall back to weknora api with a custom filter.

Changed

  • cli/AGENTS.md MCP curation rationale rewritten: curated read-only is a deliberate product call gated on the absence of server-side per-token scope. When server-side scope ships, mutation tools can land in the MCP surface.
  • cli/AGENTS.md adds "Command surface design SOP" and "CRUD command flag canon" sections for future contributors. The design-SOP section includes a step reminding contributors to decide flag-vs-escape-hatch per field rather than trying to flag-mirror every SDK capability.
  • cli/README.md now documents the weknora api raw HTTP passthrough as the canonical escape hatch for deep KB config, per-request chat / agent invoke overrides, and operations without a CLI verb.

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 AI-coding-agent env detection fired. 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.
  • 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).