8bcbf5a154
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.
190 lines
7.5 KiB
Markdown
190 lines
7.5 KiB
Markdown
# 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:
|
|
|
|
```jsonc
|
|
{
|
|
"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](https://github.com/larksuite/cli/blob/main/skills/lark-shared/SKILL.md))
|
|
"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:
|
|
|
|
```bash
|
|
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
|