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

9.0 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 (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).