docs(cli): README / AGENTS.md / CHANGELOG + CI parity test

Wire-contract documentation and the CI check that keeps it honest.

* cli/README.md gains a verbatim --help block (top-level + subtrees),
  an Exit codes table covering 0/1/2/3/4/5/6/7/10/124/130, a "Status
  vs check" verb-pair subtable, and a "doc wait" paragraph spelling out
  the four exit codes (0 / 1 / 124 / 130). The api passthrough note
  trims storage provider out of the deep-config list now that
  kb create --storage-provider is a polished flag.
* cli/AGENTS.md becomes the contributor guide: build/test, CRUD flag
  conventions, the status/check verb pattern, long-poll wait commands,
  the SetAgentHelp pattern, and a full Error code reference with 35
  typed codes mapped to namespaces, exit codes, retryable / hint
  guidance. Reference section is bracketed by HTML markers so a CI
  parity test can keep it in sync with AllCodes().
* cli/internal/cmdutil/errors_doc_test.go enforces parity: every code
  in AllCodes() must appear in AGENTS.md inside the markers, and
  AGENTS.md must not reference codes that no longer exist. Fails CI
  if a new typed code is added without documentation.
* CHANGELOG.md gets the v0.6 entry: BREAKING (--json / --no-stream /
  WEKNORA_SDK_DEBUG / kb create --name), Added (--format / --jq /
  doc wait / --log-level / kb-and-agent status & check / multi-id
  delete / api --paginate / MCP schema extension / SetAgentHelp /
  signal-aware ctx / kb create --storage-provider / new operation.*
  namespace), Changed (multi-id partial-failure exit code, doc upload
  FlagError, --log-level FlagError, multi-id stdout cleanup, README /
  AGENTS.md changes), with a Migration from v0.5 section walking
  every BREAKING through its v0.6 replacement.
This commit is contained in:
nullkey
2026-05-18 01:38:42 +08:00
committed by lyingbug
parent 34bb0b5096
commit 7611d59d71
9 changed files with 388 additions and 68 deletions
+57 -30
View File
@@ -6,8 +6,9 @@ ask streaming RAG questions from your terminal or from an AI agent.
```bash
$ weknora --help
WeKnora CLI lets you authenticate, browse knowledge bases, and run
hybrid searches against a WeKnora server from your shell or an AI agent.
Command-line client for the WeKnora RAG server. Manage knowledge bases
and documents, run hybrid search, chat with grounded answers, or expose
a curated read-only MCP tool surface for AI agents.
Available Commands:
agent Manage and invoke custom agents
@@ -29,9 +30,8 @@ Available Commands:
version Show CLI build metadata
```
The command surface follows a `<noun> <verb>` convention. The wire
contract for AI agents is documented [below](#wire-contract). For
contributing to the CLI source, see [AGENTS.md](AGENTS.md).
The wire contract for AI agents is documented [below](#wire-contract).
For contributing to the CLI source, see [AGENTS.md](AGENTS.md).
---
@@ -70,8 +70,9 @@ weknora kb list
# 4. Bind this directory to a knowledge base — subsequent commands auto-resolve --kb
weknora link --kb my-knowledge-base
# 5. Upload a document
# 5. Upload a document, then block until parsing finishes
weknora doc upload notes.md
weknora doc wait doc_abc # exit 0 completed, 1 failed, 124 --timeout, 130 ^C
# 6. Search
weknora search chunks "what is reciprocal rank fusion?"
@@ -85,6 +86,12 @@ weknora agent invoke ag_abc "what's our q4 retention plan?"
# 9. Inspect a document's chunks for RAG retrieval debug
weknora chunk list --doc doc_xyz
# 10. Health & verification verbs
weknora kb status kb_abc # fast snapshot: reachable / counts / processing flag (1 HTTP)
weknora kb check kb_abc # deep verify: also aggregates failed_count via doc list (1+N HTTP)
weknora agent status ag_abc # fast: reachable / model_id
weknora agent check ag_abc # deep: probes every KB in the agent's scope
```
---
@@ -124,28 +131,28 @@ changes announced in the changelog and the corresponding
### Streams
- **stdout** is the data channel: bare JSON with `--json`, or
- **stdout** is the data channel: bare JSON with `--format json`, or
human-formatted output. Never carries error text.
- **stderr** is logs, progress, warnings, and errors. A non-empty
stderr does **not** mean failure — read the exit code.
### JSON output
Every command supports `--json`, emitting bare JSON for the resource it
produces — an array for `list` / `search`, a single object for `view`
and write outcomes:
Every command supports `--format json`, emitting bare JSON for the
resource it produces — an array for `list` / `search`, a single object
for `view` and write outcomes:
```bash
weknora kb list --json # [{ "id": "kb_x", "name": "Eng" }, …]
weknora kb view kb_x --json # { "id": "kb_x", "name": "Eng", … }
weknora kb list --json=id,name # project to listed fields
weknora kb list --json --jq '.[].id' # jq over the bare data
weknora kb list --format json # [{ "id": "kb_x", "name": "Eng" }, …]
weknora kb view kb_x --format json # { "id": "kb_x", "name": "Eng", … }
weknora kb list --format json --jq '.[] | {id, name}' # project to listed fields
weknora kb list --format json --jq '.[].id' # jq over the bare data
```
Note the `=` form for projection: pflag's optional-value parser treats
space-separated arguments after a bare `--json` as positionals, so
`--json id,name` would be interpreted as bare `--json` + the positional
`id,name`. Always use `--json=field,...`.
`--format ndjson` is also accepted for streaming list commands; each
element is emitted as its own JSON line. When stdout is not a TTY (pipe
or redirect), `--format json` is the default — running `weknora kb list
| jq` works without an explicit flag.
### Errors
@@ -166,14 +173,15 @@ hint: run `weknora auth login`
The full code registry is in `cli/internal/cmdutil/errors.go`
(`AllCodes()`). Code namespaces: `auth.*` / `resource.*` / `input.*` /
`server.*` / `network.*` / `local.*` / `mcp.*`.
`server.*` / `network.*` / `local.*` / `mcp.*` / `operation.*` (CLI-level
wait/poll outcomes: `operation.timeout`, `operation.failed`, `operation.cancelled`).
### Exit codes
| Code | Meaning | Agent action |
|---|---|---|
| `0` | success | continue |
| `1` | typed `local.*` or unclassified | read stderr, decide retry/abort |
| `1` | typed `local.*` / `operation.failed` / unclassified | read stderr, decide retry/abort |
| `2` | flag / argument validation error | re-check `weknora <cmd> --help` |
| `3` | `auth.*` (token missing / expired / forbidden) | re-auth, then retry |
| `4` | `resource.not_found` | verify the resource id |
@@ -181,7 +189,8 @@ The full code registry is in `cli/internal/cmdutil/errors.go`
| `6` | `server.rate_limited` | back off, retry |
| `7` | `server.*` / `network.*` | transient — retry with backoff |
| `10` | **`input.confirmation_required`** (high-risk write) | ask the human, retry with `-y` only after explicit approval |
| `130` | cancelled (SIGINT / Ctrl-C) | stop, do not retry |
| `124` | `operation.timeout` (e.g. `doc wait --timeout` reached) | raise `--timeout` or check the underlying job |
| `130` | `operation.cancelled` (SIGINT / SIGTERM) | stop, do not retry |
**Exit 10** is the wire-level signal for "destructive write needs
explicit confirmation". Pass `-y/--yes` on `kb delete` / `kb empty` /
@@ -192,10 +201,10 @@ is the guard against unintended writes.
### Other agent ergonomics
- For chat / agent invoke in agent contexts, prefer `--no-stream --json`
— streaming tokens to stdout makes JSON parsing impossible.
- `--json` composes with the global `--context <name>` for single-shot
context overrides without disk writes.
- For chat / agent invoke in agent contexts, pass `--format json` —
streaming tokens to stdout makes JSON parsing impossible.
- `--format json` composes with the global `--context <name>` for
single-shot context overrides without disk writes.
- `weknora mcp serve` exposes a curated read-only tool surface over
stdio MCP for any MCP-compatible client.
@@ -209,9 +218,11 @@ targets common workflows, not 1:1 API parity. Examples of deep
operations that intentionally go through `weknora api`:
- **Tuning a KB's nested config** — chunking strategy, summary model,
multimodal extraction defaults, FAQ thresholds, VLM model, storage
provider. Use `weknora api PUT /api/v1/knowledge-bases/<id> --input -`
with a JSON body matching the server's `UpdateKnowledgeBaseRequest`.
multimodal extraction defaults, FAQ thresholds, VLM model. Use
`weknora api PUT /api/v1/knowledge-bases/<id> --input -` with a JSON
body matching the server's `UpdateKnowledgeBaseRequest`. (Note: the
storage provider is set once at create time via
`kb create --storage-provider <name>` and is not updatable.)
- **Per-request `chat` parameters** — multi-KB scope, summary model
override, image attachments, web search toggle. Use `weknora api POST
/api/v1/knowledge-chat/<session-id> --input -`.
@@ -229,9 +240,25 @@ operations that intentionally go through `weknora api`:
Run `weknora doctor` for a 4-status diagnostic (OK / warn / fail /
skip) covering base URL reachability, authentication, server-CLI
version skew, and credential storage backend. Add `--json` for
version skew, and credential storage backend. Add `--format json` for
machine-readable output, `--offline` to skip network checks.
For per-resource verification, the `status` / `check` verb pair gives
a fast vs deep choice:
| Verb | Cost | Use |
|---|---|---|
| `weknora kb status <kb-id>` | 1 HTTP | live counts / processing flag |
| `weknora kb check <kb-id>` | 1+N HTTP | adds `failed_count` via doc-list page-walk |
| `weknora agent status <agent-id>` | 1 HTTP | reachable / model_id |
| `weknora agent check <agent-id>` | 1+N HTTP | also probes every KB in the agent's scope |
`weknora doc wait <doc-id> [<doc-id>...]` blocks until each document
reaches a terminal `parse_status` (completed or failed). Exit codes:
0 (all completed), 1 (any failed), 124 (`--timeout` reached), 130
(Ctrl-C / SIGTERM). Multi-target is polled concurrently (max 5 in
flight; pipe through `xargs -P` for more).
---
## Development
@@ -261,7 +288,7 @@ macOS / Windows × Go 1.26, path-filtered to changes under `cli/`.
security findings.
- **Pull requests**: the developer guide for editing the CLI lives in
[AGENTS.md](AGENTS.md) (build / test / command-surface design SOP /
CRUD flag canon). Run `go test ./... -race -count=1` and `go vet ./...`
CRUD flag conventions). Run `go test ./... -race -count=1` and `go vet ./...`
before submitting.
---