e623e8208f
Removes the entire envelope machinery now that every success path
emits bare JSON:
- cli/internal/format/envelope.go (Envelope, Success, Failure,
SuccessWithRisk, WriteEnvelope, Meta, Notice, UpdateNotice,
VersionSkewNotice, Risk, RiskLevel, ErrorBody) + tests.
- cli/internal/format/filter.go envelope-specific helpers
(WriteEnvelopeFiltered, marshalEnvelope, applyFieldFilter,
filterDataPayload, filterObjectData); the reusable
filterArrayItems / filterObjectKeys / writeJQ stay for bare.go.
- cli/internal/cmdutil/exporter.go + tests (envelope-only).
- cli/internal/cmdutil/PrintErrorEnvelope + ToErrorBody +
operationRiskOf + Error.OperationRisk field + OperationRisk struct.
Error path: all errors now go to stderr via cmdutil.PrintError in
`code: message\nhint: ...` form, regardless of --json. Stdout stays
empty (or holds the partial-success the command already wrote) so
downstream `--json | jq` pipelines never have to filter error shapes
out of the success stream. Typed exit codes (3 auth.* / 4
resource.not_found / 5 input.* / 6 server.rate_limited / 7 server.*
+ network.* / 10 input.confirmation_required) carry the failure
class for agents that branch on it.
Acceptance contract:
- envelope_test.go → wire_test.go (TestEnvelopeGolden → TestWireGolden).
- testdata/envelopes/ → testdata/wire/.
- Error-path cases assert the typed code substring on stderr.
- Orphan whoami.*.json goldens deleted.
AGENTS.md + README.md rewritten for the bare-data contract:
- Drop envelope schema section + dry-run rule.
- Document bare JSON on stdout + `code: msg\nhint: …` on stderr.
- ADR-3 reframed around bare data and why error separation matters
for `--json | jq` pipelines.
WriteJSONFiltered short-circuits to WriteJSON when both filters are
empty (skip the marshal-buffer round-trip for the common case).
Final review pass:
- Fix wire-contract bug: `--json id,name` (space form) is broken by
pflag's NoOptDefVal; AGENTS.md / README.md / SetAgentHelp + the
field-discovery help text all switched to `--json=id,name`.
- Fix `weknora api --jq` silently ignored: api.go now routes through
WriteJSONFiltered with jopts.JQ.
- AGENTS.md: drop the false claim that `auth logout` honors `-y`
(logout is local-only with no ConfirmDestructive guard); list the
actual destructive commands instead.
- Rewrite cli/acceptance/e2e/e2e_test.go for the bare-data wire shape
(was still parsing `out["data"]` / `env["ok"]`).
- Add `JSONOptions.Emit(w, v)` helper; collapse ~33 repeated
`format.WriteJSONFiltered(iostreams.IO.Out, X, jopts.Fields,
jopts.JQ)` sites to `jopts.Emit(iostreams.IO.Out, X)` — drops the
format import from 22 cmd/* files.
- Delete single-caller `cmdutil.MustRequireFlag`; inline as
`_ = cmd.MarkFlagRequired(...)` everywhere.
- Add `_ = cmd.MarkFlagRequired("name")` to `kb create`; it was the
only write command relying on runtime --name validation while
`context add` already used the cobra-level mark.
- `context use`: register `--json` / `--jq` (was always emitting JSON
unconditionally with no human path and no flag — diverged from
every other write command); human mode now prints
`✓ Switched context to X (was Y)`.
- Replace per-package `confirmPrompter` / `scriptedConfirm` /
`errPrompter` test doubles with `testutil.ConfirmPrompter`.
- Rename `chatService` → `ChatService` (export to match siblings
`ListService` / `ViewService`); rename `printUploadSuccess` →
`renderUploadSuccess` (siblings use `render*`).
- `defaultHint(CodeResourceNotFound)`: drop the hardcoded
"list available with `weknora kb list`" — misleading on agent /
doc / session 404. Replaced with "verify the resource ID and try
again".
- Strip stale `v0.2/v0.3` / "envelope" / "v0.0/v0.1 supports only"
historical tags from production comments and a few test
descriptions.
325 lines
14 KiB
Markdown
325 lines
14 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).
|
|
>
|
|
> **Naming note.** "Agent" appears in two distinct WeKnora contexts:
|
|
>
|
|
> - **This file (`AGENTS.md`) + the `agent_help` annotation on each
|
|
> command's `--help`**: documents the contract for AI coding agents
|
|
> (you, the LLM-driven CLI consumer).
|
|
> - **The `weknora agent` subtree** (`agent list / view / invoke`):
|
|
> manages WeKnora's first-class *Custom Agent* resources — server-side
|
|
> records (system prompt + model + allowed tools + KB scope) that the
|
|
> user authored in the web UI. `agent invoke` calls the agent's
|
|
> configured workflow against a query; it is **not** how you, the AI
|
|
> coding agent, drive WeKnora — that's `kb` / `doc` / `search` / `chat`
|
|
> / `mcp serve`.
|
|
|
|
`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 "Output contract" and "Behavioral rules" sections below are the
|
|
self-contained specification of the wire format; everything an integrator
|
|
needs is in this document.
|
|
|
|
---
|
|
|
|
## Output contract
|
|
|
|
### Streams
|
|
|
|
- **stdout** is the data channel: bare JSON (with `--json`) or
|
|
human-formatted output (without `--json`). Never carries error text.
|
|
- **stderr** is logs / progress / warnings / errors / agent guidance
|
|
footnotes. On failure, the error message + actionable hint go here.
|
|
|
|
A non-empty stderr does **not** mean failure — read the exit code instead.
|
|
|
|
### JSON output (bare data)
|
|
|
|
When `--json` is set on a successful command, stdout contains exactly
|
|
one JSON value matching the resource the command produces:
|
|
|
|
| Command shape | stdout JSON |
|
|
|---|---|
|
|
| `list` / `search` | `[ { …resource… }, … ]` (bare array; `[]` when empty) |
|
|
| `view` / `create` / `edit` | `{ …resource… }` (bare object) |
|
|
| `delete` / `pin` / write ops | `{ id, …action-result fields… }` (bare object) |
|
|
| `doctor` | `{ summary: { all_passed, passed, warned, failed, skipped }, checks: [ … ] }` |
|
|
|
|
There is no `ok` / `data` / `error` wrapper. Agents read the resource
|
|
shape directly. Successful runs always return exit 0; failures never
|
|
emit data JSON on stdout.
|
|
|
|
#### Field selection: `--json=field,field,…`
|
|
|
|
`--json` accepts a comma-separated field list (passed with `=`) to restrict
|
|
each top-level object (or each element of a top-level array) to the named
|
|
keys:
|
|
|
|
```bash
|
|
weknora kb list --json=id,name # [{ "id": "kb_x", "name": "Eng" }, …]
|
|
weknora kb view kb_x --json=id # { "id": "kb_x" }
|
|
```
|
|
|
|
Note the `=` form: 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` plus the positional `id,name`. Always use
|
|
`--json=field,...` for projection.
|
|
|
|
Unknown field names are silently dropped so you can pass an aspirational
|
|
field set across heterogenous outputs.
|
|
|
|
#### jq pipeline: `--jq <expr>`
|
|
|
|
`--jq` applies a jq expression to the JSON before printing. The
|
|
expression sees the same bare shape the command produces (no envelope
|
|
indirection). String results render without quotes for shell-friendly
|
|
substitution; non-string results render as JSON.
|
|
|
|
```bash
|
|
weknora kb list --jq '.[].id' # one id per line
|
|
weknora kb view kb_x --jq .name # bare name
|
|
weknora search chunks "x" --kb e --jq '.[].score' # scores per line
|
|
```
|
|
|
|
`--jq` requires `--json`. Combining with `--json=id,name` is fine — the
|
|
filter runs after the field projection.
|
|
|
|
### Errors (stderr, exit code carries the class)
|
|
|
|
On failure, stdout is empty (or holds the partial-success output the
|
|
command already wrote before the failure). The error message goes to
|
|
stderr in this format:
|
|
|
|
```
|
|
<error.code>: <message>[: <wrapped cause>]
|
|
hint: <actionable next-step>
|
|
```
|
|
|
|
- `<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.
|
|
- `<message>` is the human-readable description.
|
|
- `<hint>` is the deterministic next-step hint (omitted when no hint
|
|
applies).
|
|
|
|
Code namespaces: `auth.*` / `resource.*` / `input.*` / `server.*` /
|
|
`network.*` / `local.*` / `mcp.*`.
|
|
|
|
To pattern-match programmatically: split on the first `:` to extract
|
|
the code, or branch on the exit code (see below).
|
|
|
|
### Exit codes
|
|
|
|
| Code | Meaning | Agent action |
|
|
|---|---|---|
|
|
| `0` | Success | Continue |
|
|
| `1` | Typed `local.*` error or unclassified | Read stderr, decide retry/abort |
|
|
| `2` | Flag/argument validation error | Re-check `weknora <command> --help` |
|
|
| `3` | `auth.*` (token missing / expired / forbidden) | Re-auth then retry |
|
|
| `4` | `resource.not_found` | Verify the resource id |
|
|
| `5` | `input.*` (other than confirmation_required) | Adjust args and retry |
|
|
| `6` | `server.rate_limited` | Back off, then retry |
|
|
| `7` | `server.*` / `network.*` | Transient; retry with backoff |
|
|
| `10` | **`input.confirmation_required`** — high-risk write needs `-y` | Ask the human, retry with `-y` only after explicit approval |
|
|
| `130` | Cancelled (SIGINT / Ctrl-C) | Stop, do not retry |
|
|
|
|
Exit 10 is the wire-level signal for "high-risk write needs explicit
|
|
confirmation". **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>`. 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` /
|
|
`token`. Context-switching uses `context use <name>` (WeKnora contexts
|
|
bundle host + tenant + credentials, so they need a richer abstraction
|
|
than a single per-host token slot). `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: `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 WeKnora addition: RAG deployments routinely
|
|
break on misconfigured embeddings, storage backends, and credentials,
|
|
and the structured `{summary: {all_passed, passed, warned, failed,
|
|
skipped}, checks: [...]}` JSON shape is the cleanest agent-readable
|
|
surface for that.
|
|
|
|
---
|
|
|
|
## Behavioral rules
|
|
|
|
Per-command guidance also appears in each command's `--help` output
|
|
(under "AI Agents:").
|
|
|
|
1. **Pass `-y/--yes`** on destructive writes (`kb delete` / `kb empty` /
|
|
`doc delete` / `session delete` / `context remove` when targeting
|
|
the current context) 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 parsing impossible.
|
|
4. **`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`.
|
|
|
|
Agent detection (`CLAUDECODE` / `CURSOR_AGENT` env) also tags the
|
|
User-Agent header for server-side telemetry — it never changes CLI
|
|
behavior.
|
|
|
|
---
|
|
|
|
## 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 — bare-data JSON on stdout, errors on stderr.** Successful
|
|
commands emit the raw resource shape (`[]Item` for lists, `T` for views,
|
|
`{id, deleted: true}` for deletes) — no `ok` / `data` / `error`
|
|
wrapper. Errors are not data; they go to stderr in `code: message\nhint:
|
|
…` form, and the typed exit code carries the failure class for
|
|
programmatic branching. This separates "what the command produces" from
|
|
"how the run went", so `--json | jq` pipelines never have to filter
|
|
error shapes out of the success stream, and matches the contract of
|
|
gh / aws / stripe.
|
|
|
|
WeKnora-specific shape choices:
|
|
|
|
- `link` (project-binding) — `<cwd>/.weknora/project.yaml` walk-up
|
|
matches how RAG users scope work to a specific knowledge base. There
|
|
is no per-host config model competing with it; `context use` is the
|
|
separate mechanism for switching the credential set.
|
|
- `chat` / `search` are domain-specific verbs (LLM streaming +
|
|
retrieval) with no equivalent in pure-API CLIs.
|
|
- `context use` switches the active credential set; contexts bundle
|
|
host + tenant + credential, so a richer abstraction than a single
|
|
per-host token slot is required.
|
|
- `doctor` (4-status: ok / warn / fail / skip per check, plus a
|
|
summary object) is the agent-readable surface for RAG-deployment
|
|
misconfiguration (embeddings, storage, credentials) — failure modes
|
|
that the underlying SDK can't classify on its own. Agents short-
|
|
circuit on `summary.all_passed`; exit code is non-zero iff any
|
|
check is `fail`.
|
|
|
|
Verb canon: `list / view / create / edit / delete / upload / download
|
|
/ pin / unpin / use`. WeKnora-specific verbs for resource semantics
|
|
the common set lacks: `empty` (bulk-delete contents preserving the
|
|
container), `refresh` (token), `add` / `remove` (context CRUD),
|
|
`link` / `unlink` (project bind / unbind), `invoke` (run a custom
|
|
agent), `serve` (long-lived MCP transport).
|
|
|
|
**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 chat` when no chat model is configured for the active tenant
|
|
- `weknora search chunks` 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 output (stdout + stderr) you got vs the output this document
|
|
promises
|