Seven bugs surfaced via two audit rounds — parallel reviewer agents
plus a real-server end-to-end demo. Each fix arrives with a
regression test.
1. doc upload --recursive --json corrupted the envelope stream.
Per-file FAIL/OK plain lines printed unconditionally to stdout,
then a Success envelope, then on partial failure a typed error
that the root handler turned into a SECOND Failure envelope —
three outputs where one was expected. Fix: gate the plain lines
behind !opts.JSONOut, and add cmdutil.Error.Silent so the JSON-
path partial-failure preserves its typed exit code without
triggering PrintErrorEnvelope's default Failure-envelope write.
2. auth refresh / AuthRetryTransport misclassified HTTP failures as
network.error. RefreshAndPersist wrapped every refresher error
with CodeNetworkError, but the SDK emits "HTTP error 401: ..."
for a rejected refresh token — which should surface as
auth.token_expired. Switched to WrapHTTP for proper status-
derived classification. Affects both `auth refresh` and the
transport's refresh closure.
3. doc download accepted ".." as a server-suggested filename. The
rejection list covered "" / "." / filepath.Separator but not
bare ".." — filepath.Base("..") is "..", which slipped through
to os.Create and produced a confusing local.file_io wrap. Added
to the rejection set.
4. search chunks / docs / kb / sessions had no lower bound on
--limit. `-L 0` / `-L -1` was forwarded to the server with
undefined behavior. Added a 1..1000 bound at the RunE boundary
across all four (matching doc list / session list page-size
bounds). Internal callers in tests can still pass Limit==0 for
the "no client-side cap" runChunks path — the bound only applies
at the user-input layer.
5. cli/AGENTS.md ADR-3 verb-canon summary listed only v0.2 verbs as
"gh-canonical" and missed v0.3 additions (edit, pin, unpin,
download — all gh-canonical) plus locally-introduced ones
(empty, refresh, add, remove, link). Rewritten as an explicit
gh-canonical / locally-introduced split.
6. kb pin returned 404. Server registers /knowledge-bases/{id}/pin
as PUT (router.go:292); SDK was using POST. gin's router silently
404s on method-mismatch (treats it as path-not-found, not 405),
so the CLI classified the response as resource.not_found and
masked the real failure mode. Switched the SDK to http.MethodPut.
The asymmetry that hid this past round 1: kb unpin on a freshly-
created KB hits the no-op branch in cmd/kb/pin.go that skips the
SDK call entirely, so unpin "worked" without ever exercising the
broken path. Only the real-server demo, where kb pin actually
fires, surfaced it.
7. kb edit clobbered current Name when only --description was
passed. EditOptions used *string to distinguish "unset" from
"set to empty", but sdk.UpdateKnowledgeBaseRequest declares both
fields as plain string (no omitempty), so the JSON body always
carried `"name": ""`. Server requires Name → 400. Fix: runEdit
does fetch-then-update — GetKnowledgeBase first, build the PUT
body with current values, then overlay user-set fields. Same
TOCTOU window as kb pin / unpin.
Audit-flagged items intentionally NOT changed:
- kb pin / unpin check-then-toggle TOCTOU: documented; the clean
fix would be a server-side setter and belongs in a separate API
change.
- AuthRetryTransport singleflight test gap for one concurrency
scenario; v0.4 polish.
- cli/README.md:50 "once v0.2 ships" and CHANGELOG.md:8
"10 top-level commands": v0.2-PR artifacts, not v0.3-introduced.
- kb edit / kb pin are v0.3-new commands, so neither bug needs a
cli/CHANGELOG.md Fixed entry — the v0.3 release ships them
working as the Added bullets advertise.
11 KiB
Agent Integration Guide for weknora CLI
Scope. This file is an operational reference for LLM agents (Claude Code, Cursor, Codex, Aider, Gemini Coder, etc.) that invoke
weknoraon a user's behalf. It documents the wire shape, exit code, and behavioral conventions an agent integration relies on.This is not a contributor guide. If you are an AI coding agent editing weknora's source, see the repo root
README.md(and, if added later, a separate contributorAGENTS.mdat the repo root).
weknora is designed to be agent-friendly: error messages, output format,
and flag design follow conventions agents can rely on. Wire-contract
breaking changes are flagged in their PR description and the corresponding
weknora --version bump — agents should pin a known-good version and
re-validate against --help output on upgrade.
The model: gh CLI as the human-side north star, lark-cli (larksuite) as the agent-affordance reference. The "Output contract" and "Behavioral rules" sections below are the self-contained specification of that decision; everything an integrator needs is in this document.
Output contract
Streams
- stdout is the data channel: JSON envelope (with
--json) or human-formatted output. - stderr is logs / progress / warnings / agent guidance footnotes. Never parse stderr for data.
A non-empty stderr does not mean failure — read the exit code instead.
JSON envelope
When --json is set, stdout contains exactly one envelope:
{
"ok": true, // false on failure; check this first
"data": { /* command-specific payload */ },
"error": { "code": "...", "message": "...", "hint": "..." }, // iff ok=false
"_meta": { "request_id": "...", "kb_id": "..." }, // optional
"risk": { "level": "high-risk-write", "action": "..." }, // write commands
"dry_run": false // true on --dry-run
}
This snippet is illustrative. Fields are added (never renamed or repurposed)
within a minor version, and agents must not error on unknown keys. The
authoritative envelope shape lives in cli/internal/format/envelope.go.
Error codes (closed registry)
error.code is a namespace.snake_case string from a closed registry in
cli/internal/cmdutil/errors.go AllCodes(). An acceptance test enforces
that every code referenced in cli/cmd/ is registered.
Categories: auth.* / resource.* / input.* / server.* / network.* /
local.* / mcp.*.
error.hint provides a deterministic next-step hint agents can follow
without natural-language parsing.
Exit codes
| Code | Meaning | Agent action |
|---|---|---|
0 |
Success | Continue |
1 |
Typed error (see envelope.error.code) | Read code, decide retry/abort |
2 |
Flag/argument validation error | Re-check weknora <command> --help |
10 |
Confirmation required for high-risk write | Ask the human, retry with -y only after explicit approval |
130 |
Cancelled (SIGINT / Ctrl-C) | Stop, do not retry |
The exit-10 protocol mirrors lark-cli's
(source)
"high-risk write requires confirmation" model. Never bypass exit 10 by
auto-passing -y without explicit user permission.
Command surface
Discover the command tree the same way human users do:
weknora --help # top-level
weknora kb --help # subtree
weknora kb delete --help # single command flags
The command tree follows <noun> <verb> (gh style). Verbs are:
| Verb | Semantics | Example |
|---|---|---|
list |
Multi-resource read | kb list |
view |
Single-resource read | kb view <id> |
create |
Create resource | kb create --name X |
edit |
Partial update (only sent fields change) | kb edit <id> --description X |
delete |
Destructive remove (KB itself) | kb delete <id> -y |
empty |
Bulk-delete contents, preserve container | kb empty <id> -y |
upload |
Bulk write content | doc upload <file> |
download |
Stream resource to disk | doc download <id> -O file |
pin / unpin |
Toggle "pinned" state (idempotent) | kb pin <id> |
use |
Switch active selection | context use <name> |
add / remove |
Manage local config entries | context add staging --host ... |
auth subtree: login / logout / list / status / refresh. Mirrors
gh's auth login / logout / status / switch / list-style surface; weknora
uses context use instead of auth switch because contexts carry host +
tenant on top of credentials. auth refresh exchanges the stored refresh
token for a new access + refresh pair (OAuth refresh-token grant); it
errors with input.invalid_argument on API-key contexts which have no
refresh semantic. Transparent 401 → refresh → retry is wired into the
SDK transport (cli/internal/cmdutil/authretry.go) with singleflight
de-dup, so most callers never need to invoke auth refresh explicitly.
search subtree: verb-noun (gh search code/repos/issues/... shape) —
search chunks "<q>" --kb X for hybrid retrieval, search kb "<q>" /
search docs "<q>" --kb X / search sessions "<q>" for client-side
substring filtering on the listing endpoints.
session subtree: list / view / delete for chat session
management. Sessions are the durable wrapper around chat invocations.
Top-level RAG / connectivity verbs: chat, search, api, link,
auth, context, session, doctor, version.
doctor is a deliberate divergence from gh / lark (neither ships a
health-check command); the precedent is flutter doctor / brew doctor.
Kept because RAG deployments routinely break on misconfigured embeddings,
storage backends, and credentials, and a structured 4-status envelope
(ok/warn/fail/skip) is the cleanest agent-readable surface for that.
Behavioral rules
These mirror lark-cli's per-command Tips. Per-command guidance also
appears in each command's --help output (under "AI agents:").
- Pass
-y/--yesonkb delete/doc delete/auth logoutwhen running headless. Without it, you will get exit 10. Never auto-add-ywithout the user's explicit go-ahead — the exit-10 protocol is the one explicit guard against unintended writes. - Prefer typed commands over
weknora apifor known endpoints. Fallback toweknora apionly when no typed command covers the call. - For chat, prefer
--no-stream --jsonin agent contexts. Streaming tokens to stdout makes JSON envelope parsing impossible. - Honor
--dry-run— when the user passes it, don't follow up with the real command unless explicitly asked. The dry-run envelope is the answer. linkwrites to the user's working directory — only run it when the user invoked it, not as a side effect of unrelated automation.
(Additional safety guidance — e.g. "do not switch context unless the
user asked" — is documented in the affected command's own --help.)
Auto-detection of agent environments
weknora checks these environment variables (case-sensitive):
| Env var | Detected agent name |
|---|---|
CLAUDECODE |
claude-code |
CURSOR_AGENT |
cursor |
When any is set, weknora --help appends the command's agent_help
annotation. No behavior change — this is help-text rendering only.
To suppress detection (e.g. running weknora interactively from inside
Claude Code without the agent footer): WEKNORA_NO_AGENT_AUTODETECT=1.
The omnibus --agent mode-switch flag that briefly existed in early v0.2
was removed: gh / kubectl / aws / docker / flyctl all decline this kind
of flag, since per-command --json + TTY auto-detect cover the same
ground without an extra global switch. Stripe's DetectAIAgent (the
inspiration) only tags User-Agent for telemetry, never flips behavior;
weknora now follows that narrower scope.
Architecture decisions
A handful of decisions are referenced inline in the source as ADR-N. They
live here, alongside the contract they shape.
ADR-3 — gh CLI as the primary mainstream north star. When weknora's
v0.0/v0.1 surface was audited against gh / kubectl / cargo / npm / git /
docker / flyctl / vercel / supabase / brew, gh emerged as the closest fit
for an opinionated noun-verb tool with a stable JSON envelope and an
agent-aware error model. Documented deviations:
link(project-binding) borrows fromvercel link/netlify linkrather than gh's per-host config model — a<cwd>/.weknora/project.yamlwalk-up matches how RAG users scope work to a specific knowledge base.chat/searchare domain-specific verbs gh has no analog for.context use(kubectl idiom) instead of gh'sauth switch— weknora's context bundles host + tenant + credential, which is more than gh's per-host account model.doctor(flutter / brew idiom) instead of gh'sstatus(which is an activity feed, different concept) — RAG deployments routinely break on misconfigured embeddings / storage / credentials, so a structured 4-status diagnostic is the agent-readable surface for that.
Verb canon (gh-canonical): list / view / create / edit / delete / upload / download / pin / unpin / use. Locally introduced for resource semantics gh lacks: empty (bulk-delete contents preserving the container), refresh (token), add / remove (context CRUD), link (project bind).
ADR-4 — Factory closures + narrow Service interfaces. cmdutil.Factory
exposes four lazy closures (Config / Client / Prompter / Secrets) that
commands may invoke, but each subcommand declares its own narrow Service
interface for the SDK calls it actually makes. The production *sdk.Client
satisfies these implicitly via duck typing; tests inject fakes. Splitting
the boundaries this way means a subcommand's test can stand up an
httptest.Server (or a hand-rolled struct) without standing up the full
SDK, and the dependency graph of any one command is visible in one file.
Known limitations
The following classes of failure currently surface as error.code = "network.error"
with context deadline exceeded rather than a precise typed code. A future
release will introduce a precondition.* namespace (server returns HTTP 412
with a typed remediation body before opening the SSE / streaming response):
weknora chatwhen no chat model is configured for the active tenantweknora search chunkswhen no retriever / vector store is configuredweknora doc uploadwhen no storage engine is selected for the KB
Workaround until then: if a chat / search / upload call times out without
producing a first-byte response, check the server's tenant configuration
(LLM / vector store / storage engine) before retrying. A planned
weknora doctor --server-config will probe these directly.
Reporting issues
If the CLI's behavior contradicts this document, that is a bug. File at https://github.com/Tencent/WeKnora/issues with:
- The exact command line
weknora --versionoutput- The envelope you got vs the envelope this document promises