mirror of https://github.com/Tencent/WeKnora.git synced 2026-06-04 13:30:32 +08:00

Files

nullkey c9b837dfce docs(cli): sync README + AGENTS.md, add cli/CHANGELOG.md, clear stale e2e refs

v0.3 feature commits didn't update the docs alongside; this commit
syncs them and introduces a CLI-local changelog so v0.3+ release
notes stop crowding the project root file.

cli/CHANGELOG.md (new):
- Subsystem-local pattern, mirroring mcp-server/CHANGELOG.md. CLI
  versions independently from server / frontend cadence; reduces
  merge-conflict surface on the shared root file.
- Scope: Added + SDK additions only. v0.3-internal dev churn
  (--top-k → --limit, kb clear-contents → kb empty, link --context
  introduce-then-drop, internal Go type-name leaks) never reached a
  shipped release so it doesn't belong in Changed / Fixed sections.
  mcp-server's v1.0.0 changelog is Added-only for the same reason.
- v0.0–v0.2 history stays in the project root CHANGELOG.md;
  cross-referenced from the top of cli/CHANGELOG.md.

Stale --help / quickstart examples fixed in cli/cmd/root.go,
cli/README.md, and cli/AGENTS.md — all three showed the dropped bare
`weknora search "<q>" --kb=...` form; updated to `search chunks ...`.

AGENTS.md updates:
- Verb canon table gained edit / empty / download / pin / unpin /
  add / remove.
- `auth` subtree description gained `refresh` and the transparent
  401-retry transport (replacing the now-inverted "deferred to v0.3"
  sentence).
- `search` and `session` subtree paragraphs added; top-level
  verb list gained `context` and `session`.

cli/README.md top-level command list gained `session`; `search`
short retitled to the parent description ("Search across chunks,
knowledge bases, documents, or sessions") since search is now a
pure dispatcher.

Pre-existing stale e2e refs swept up while syncing:
- cli/acceptance/doc.go listed e2e/ under "Future v0.2+:" — moved
  into the present-tense Sub-packages block.
- envelope_test.go preamble "Deferred to v0.2 e2e" rephrased to
  "Deferred to the e2e harness" so it isn't pinned to a past version.

Not changed (out of scope, flagged for future PRs):
- envelope_test.go "Implemented count: 16" vs the actual 14 named
  entries — could be a different counting rule; verify with PR-8
  author before editing.
- envelope_test.go context_use deferred-cases narrative is loose
  (context_use.success IS golden-pinned today) but rewriting needs
  careful re-derivation of which error scenarios are still deferred.
- cli/README.md:50 "once v0.2 ships" — v0.2-PR-original wording;
  not load-bearing once a release tag exists.

No project-root CHANGELOG.md change in this commit.

2026-05-14 10:57:17 +08:00

3.4 KiB

Raw Blame History

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.

Earlier history (v0.0 through v0.2) is recorded in the project root CHANGELOG.md under the entries that introduced the CLI.

[Unreleased]

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; --dry-run emits risk + dry_run:true.
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.
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).

3.4 KiB Raw Blame History

Changelog — weknora CLI