a0dd989c81
Compared the auth subtree (login/logout/list/status/refresh/token)
against gh CLI's auth implementation. Three gaps closed:
1. `auth login --with-token` validates the API key against `/auth/me`
before persisting (mirrors gh's pre-persist GetCurrentLogin probe).
A typo'd / expired / wrong-host key fails fast with
`auth.bad_credential` (exit 3) and nothing is written to the
keyring. Side benefit: api-key contexts now carry the resolved
`user` + `tenant_id` at rest, so `auth list` reflects who owns
the key — previously these columns were blank for `--with-token`
contexts because we never queried the server.
2. `auth login` prints a stderr advisory when the secrets store falls
back to the 0600 plaintext file (keychain unavailable — typical on
headless CI, WSL without DBus, agent containers). `weknora doctor`
carried the same info in its credential_storage check, but users
who go straight to `auth login` could miss it. gh has the same
silent-fallback gap; we're stricter here.
3. AGENTS.md adds an "Auth security contract" section documenting:
- Credential storage (keychain primary, 0600 file fallback)
- `--with-token` reads stdin (not flag value), pre-validated
- No env-var token bypass — by design, to avoid the
`/proc/<pid>/environ` / `ps -E` leak surface that
`GH_TOKEN`-style env vars expose
- `auth status` / `auth list` never emit token values
- `auth refresh --json` returns only `{context}` (never the
new tokens)
- `auth token` stdout has no trailing newline + TTY stderr hint
- `auth logout` is local-only (no server-side revocation)
Verified against gh CLI behavior (cli.github.com manual + cli/cli
trunk source):
| dimension | gh | weknora v0.4 |
|---------------------------------|----------------|--------------|
| pre-persist token validation | ✓ | ✓ (new) |
| OS keychain primary | go-keyring | go-keyring |
| stderr warning on file fallback | ✗ silent | ✓ (new) |
| `auth status` default token | masked prefix | not shown |
| `auth token` TTY warning | ✗ | ✓ |
| env-var token bypass | ✓ (GH_TOKEN) | ✗ by design |
| process-args / `ps` leak surface| ✗ stdin only | ✗ stdin only |
360 lines
16 KiB
Markdown
360 lines
16 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.
|
|
|
|
### Auth security contract
|
|
|
|
- **Credential storage**: OS keychain via `go-keyring` (macOS Keychain,
|
|
Windows Credential Manager, freedesktop Secret Service). Falls back to
|
|
a 0600 file under `$XDG_CONFIG_HOME/weknora/secrets/<context>/` only
|
|
when no keyring backend is available. `auth login` prints a stderr
|
|
warning at fallback time; `weknora doctor` flags it under
|
|
`credential_storage`.
|
|
- **`auth login --with-token`**: reads the API key from **stdin**, never
|
|
from a flag value (so it never appears in `ps` / shell history). The
|
|
key is validated against `/auth/me` **before** being persisted — a
|
|
typo / expired / wrong-host key fails fast with
|
|
`auth.bad_credential` and nothing is written.
|
|
- **No env-var token bypass**: WeKnora does NOT honor a `WEKNORA_TOKEN`
|
|
env var as an implicit credential source — by design, to avoid the
|
|
process-environment leak surface (`/proc/<pid>/environ`, `ps -E`,
|
|
multi-tenant CI runners). CI / scripts should pipe the key via
|
|
`weknora auth login --with-token` into the keyring (or the file
|
|
fallback under an isolated `$XDG_CONFIG_HOME`).
|
|
- **`auth status` / `auth list`**: never emit token values, in either
|
|
human or JSON modes. The `mode` field (`bearer` / `api-key`) signals
|
|
which credential class is stored, not the value.
|
|
- **`auth token`**: the only command that prints the stored credential.
|
|
Stdout has **no trailing newline** so `$(weknora auth token)` is
|
|
clean; when stdout is a TTY, a stderr advisory warns the user that
|
|
the secret just landed in scrollback, plus an extra note for api-key
|
|
mode (long-lived, rotate at the server).
|
|
- **`auth refresh` `--json`**: returns only `{context}` — never the new
|
|
access or refresh token. Agents that need to verify the new
|
|
credential should re-run `auth status` (live `/auth/me` probe).
|
|
- **`auth logout`**: local-only — deletes the keyring entry + file
|
|
fallback + the context entry in `config.yaml`. **Does NOT revoke
|
|
server-side.** For JWT, the issued token stays valid until expiry;
|
|
for API keys, rotate them in the server UI.
|
|
|
|
`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
|