Files
Enterprise-Knowledge-Base/cli/AGENTS.md
T
nullkey 8bcbf5a154 refactor(cli): align command surface with mainstream conventions
Empirical mainstream-CLI surveys (gh / kubectl / aws / gcloud / stripe /
flyctl / terraform / vercel / netlify / lark) drove five alignment
fixes — each replaces a weknora-only design choice that mainstream CLIs
do not share. No backwards-compat shims; the CLI has no v0.1 users yet.

1. Single --kb flag (was --kb-id + --kb mutually exclusive)

   Survey: 0/7 mainstream CLIs use two parallel flags for "by id" vs
   "by name". Single flag (gh -R, gcloud --project) or positional
   (kubectl, stripe, terraform). Closest analog — gcloud --project —
   collapses identifier types onto one flag.

   Now: every command exposes one --kb flag; client-side prefix
   detection (cmdutil.IsKBID looks for "kb_") routes id-form values
   through directly and name-form values through ListKnowledgeBases.
   Mirrors gcloud --project's id-or-name auto-detection.

   Touched: search, chat, doc list / upload / delete, link.
   Factory.ResolveKB chain trimmed from 5 levels to 4.

2. link supersedes init

   Survey: only vercel and netlify ship both `init` AND `link` as
   siblings, and they keep them semantically distinct. weknora's pair
   wrote the same .weknora/project.yaml file with the same meaning,
   differentiated only by interactivity — that's a flag concern, not
   a command concern.

   Now: cmd/init/ deleted. cmd/link absorbs the interactive flow:
     - link --kb <id-or-name>  → non-interactive write
     - link on a TTY            → interactive prompt (lists KBs)
     - link non-TTY without --kb → CodeKBIDRequired
   Always overwrites silently (matches vercel link / netlify link /
   kubectl apply rather than git init's refuse-if-exists).

   Dead code purged: --force flag, CodeProjectAlreadyLinked error code.

3. whoami dropped

   Survey: 7/7 mainstream CLIs ship exactly one identity command —
   never both a status and a whoami. gh / gcloud / stripe pick status
   (config + live API); aws / kubectl / flyctl pick whoami (live API).

   weknora's auth status was already a superset of whoami (host +
   context + user + email + tenant_id + tenant_name vs user_id +
   tenant_id), so dropping whoami preserves all functionality and
   aligns with the gh / gcloud / stripe form.

4. kb get alias dropped

   `view` was already primary (gh repo view / gh pr view convention);
   `get` was kept as a cobra alias for v0.0/v0.1 callers. With no
   v0.0/v0.1 users to break, the alias is just noise on the command
   surface. Acceptance contract envelope cases renamed kb_get.* →
   kb_view.*; goldens renamed in lockstep.

5. api refactored to gh shape (-X/--method, default GET, auto-POST)

   gh CLI's signature is `gh api <endpoint> [--method M]` — single
   positional path, method as a flag, default GET, auto-promoted to
   POST when a body is supplied. weknora's previous `api <method>
   <path>` inverted this and forced the method to be passed even for
   GET — a needless deviation from our declared north star.

   Now: `api <path> [-X METHOD] [--data ...]`. Exit-10 protocol
   on the DELETE escape-hatch is preserved; -X DELETE still hits
   ConfirmDestructive when -y absent.

Plus: AGENTS.md gains an explicit note that `doctor` is a deliberate
divergence from gh / lark — borrowed from `flutter doctor` / `brew
doctor` because RAG deployments routinely break on misconfigured
embeddings / storage / credentials and a 4-status structured envelope
is the cleanest surface for it.

Tests: 24 cli packages green (was 26 in PR-14; init + whoami packages
removed). Acceptance contract envelope cases for whoami removed,
kb_get → kb_view renamed, search args / mock path updated for the
kb_<id> form. e2e harness flag args updated. Factory.ResolveKB tests
rewritten for the single-flag shape. api_test driver updated for the
positional-path / -X-method shape.
2026-05-12 13:20:42 +08:00

7.5 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 weknora on 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 contributor AGENTS.md at 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
delete Destructive remove kb delete <id> -y
upload Bulk write content doc upload <file>
use Switch active selection context use <name>

Top-level RAG / connectivity verbs: chat, search, api, link, auth, 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:").

  1. Pass -y/--yes on kb delete / doc delete / auth logout when running headless. Without it, you will get exit 10. Never auto-add -y without the user's explicit go-ahead — the exit-10 protocol is the one explicit guard against unintended writes.
  2. Prefer typed commands over weknora api for known endpoints. Fallback to weknora api only when no typed command covers the call.
  3. For chat, prefer --no-stream --json in agent contexts. Streaming tokens to stdout makes JSON envelope parsing impossible.
  4. 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.
  5. link writes 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.


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 chat when no chat model is configured for the active tenant
  • weknora search when no retriever / vector store is configured
  • weknora doc upload when 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 --version output
  • The envelope you got vs the envelope this document promises