docs: CLI operational contract, quickstart, and changelog

AGENTS.md wire contract for AI agents, README install + 5-minute quickstart,
CHANGELOG, and the root README CLI section.
This commit is contained in:
nullkey
2026-06-26 20:40:59 +08:00
committed by lyingbug
parent 6f8b825f5f
commit 040a734766
2 changed files with 79 additions and 31 deletions
+12 -9
View File
@@ -171,23 +171,26 @@ The [WeKnora Mini Program](./miniprogram/README.md) provides a lightweight mobil
## ⌨️ Command-Line Interface
`weknora` is the official CLI for driving the API from a terminal or AI agent.
The command surface mirrors `gh` CLI's `<noun> <verb>` convention; output is
human-readable by default and switches to a stable JSON envelope with `--json`.
v0.9 ships bundled Agent Skills (`weknora-rag-search`, `weknora-shared`), adds
`session stop`, and harmonizes auth/profile workflows (see [`cli/CHANGELOG.md`](./cli/CHANGELOG.md)).
`weknora` is the official CLI for driving the API from a terminal or an AI
agent. It is **agent-first**: every command emits a stable JSON envelope by
default (with typed error codes mapped to exit codes), and `--format text`
renders for humans. It also serves a curated MCP tool surface
(`weknora mcp serve`) and ships bundled Agent Skills.
```bash
weknora auth login --host https://kb.example.com
weknora profile add prod --host https://kb.example.com --use
weknora auth login
weknora kb list
weknora link --kb my-knowledge-base # bind the current directory
weknora doc upload notes.md
weknora chat "summarise the design doc"
```
See [`cli/README.md`](./cli/README.md) for install + 5-minute quickstart
and [`cli/AGENTS.md`](./cli/AGENTS.md) for the operational contract that
AI agents (Claude Code, Cursor, Aider, …) can rely on.
For headless / CI use, set `WEKNORA_API_KEY` + `WEKNORA_HOST` and skip
`auth login` entirely — no credentials written to disk.
See [`cli/README.md`](./cli/README.md) for install + 5-minute quickstart and
[`cli/AGENTS.md`](./cli/AGENTS.md) for the operational contract AI agents rely on.
## 🚀 Getting Started
+67 -22
View File
@@ -24,8 +24,9 @@ Available Commands:
kb Manage knowledge bases
link Bind the current directory to a knowledge base
mcp Run weknora as a Model Context Protocol server
message Inspect and manage messages inside chat sessions
search Search across chunks, knowledge bases, documents, or sessions
session Manage chat sessions
session Manage chat sessions (incl. tool-approval resolve)
unlink Remove the directory's knowledge-base binding
version Show CLI build metadata
```
@@ -50,8 +51,9 @@ sudo mv weknora /usr/local/bin/ # or anywhere on $PATH
### Pre-built binaries
Pre-built binaries for Linux / macOS / Windows are produced by CI on each
release. Grab the latest from the [Releases page](https://github.com/Tencent/WeKnora/releases).
Building from source is the supported install method today. Pre-built binaries,
`go install`, and a Homebrew formula are planned to accompany a tagged release;
until then, use the from-source build above.
---
@@ -76,6 +78,7 @@ weknora link --kb my-knowledge-base
# 5. Upload a document, then block until parsing finishes
weknora doc upload notes.md
weknora doc wait doc_abc # exit 0 completed, 1 failed, 124 --timeout, 130 ^C
weknora doc reparse doc_abc # re-trigger parsing if it failed, then wait again
# 6. Search
weknora search chunks "what is reciprocal rank fusion?"
@@ -84,13 +87,22 @@ weknora search chunks "what is reciprocal rank fusion?"
weknora chat "summarise the design doc"
# 8. Manage custom agents and run them (see `weknora agent --help` / `weknora session --help`)
weknora model list # discover a model id for --model
weknora agent list
weknora session ask --agent ag_abc "what's our q4 retention plan?"
# 9. Inspect a document's chunks for RAG retrieval debug
weknora chunk list --doc doc_xyz
# 10. Health & verification verbs
# 10. Inspect messages in a session / search across sessions
weknora message list --session sess_abc
weknora message search "retry policy" # cross-session Q&A retrieval
# 11. Resolve a pending tool approval (agent run blocked on approval event)
weknora session tool-approval resolve pend_xxx -y # approve (after user go-ahead)
weknora session continue-stream sess_abc --message msg_xyz # resume the blocked stream
# 12. Health & verification verbs
weknora kb status kb_abc # fast snapshot: reachable / counts / processing flag (1 HTTP)
weknora kb check kb_abc # deep verify: also aggregates failed_count via doc list (1+N HTTP)
weknora agent status ag_abc # fast: reachable / model_id
@@ -101,10 +113,17 @@ weknora agent check ag_abc # deep: probes every KB in the agent's scope
### Agent quick start
For AI agents (Claude Code, Cursor, Gemini CLI, etc.) integrating WeKnora:
For AI agents (any MCP-capable host) integrating WeKnora:
1. Install: `brew install weknora` or `go install github.com/Tencent/WeKnora/cli@latest`
2. Register a profile, then authenticate it (background; extract login URL for the user):
1. Install: build from source (see [Install](#install))
2. Authenticate. In a sandbox / CI, the **stateless** path needs no `auth login`
and writes nothing to disk — just set two env vars:
```bash
export WEKNORA_API_KEY="sk-…" # or WEKNORA_TOKEN for a bearer JWT
export WEKNORA_HOST="https://kb.example.com"
weknora kb list # already authenticated
```
Or, for a persisted local profile:
```bash
weknora profile add prod --host <server-url> --use
weknora auth login
@@ -127,17 +146,19 @@ under [`skills/`](skills/) that teach an agent to drive WeKnora without trial an
- [`weknora-rag-search`](skills/weknora-rag-search/SKILL.md) — when to use `chat`
vs `session ask` vs `search chunks`, plus retrieval gotchas.
MVP install: symlink them into your agent's skills directory (from a source checkout):
Install them with the CLI (the skills are embedded in the binary, no checkout
needed):
```bash
ln -s "$PWD/skills/weknora-shared" ~/.claude/skills/weknora-shared
ln -s "$PWD/skills/weknora-rag-search" ~/.claude/skills/weknora-rag-search
weknora skills install # writes to ~/.claude/skills
weknora skills install --dir <agent-skills-dir> --force # other agents / overwrite
weknora skills list --format json # what would be installed
```
Each skill's frontmatter records the CLI version it was `tested_against`; a CI
parity test (`internal/skillparity`) fails if a skill ever references a command,
flag, or MCP tool the CLI no longer has. (A `weknora skills install` command is
planned; for now, symlink or copy.)
Existing files are left untouched without `--force`; `--dry-run` previews the
file list. Each skill's frontmatter records the CLI version it was
`tested_against`; a CI parity test (`internal/skillparity`) fails if a skill
ever references a command, flag, or MCP tool the CLI no longer has.
---
@@ -188,15 +209,17 @@ changes announced in the changelog and the corresponding
### JSON output
Every command supports `--format json`, emitting bare JSON for the
resource it produces — an array for `list` / `search`, a single object
for `view` and write outcomes:
Every command supports `--format json`, wrapping the resource in the
symmetric envelope `{ok, data, meta?}` — `data` is an array for `list` /
`search`, a single object for `view` and write outcomes. `--jq` runs
against the whole envelope, so reach into list items with `.data[]`:
```bash
weknora kb list --format json # [{ "id": "kb_x", "name": "Eng" }, …]
weknora kb view kb_x --format json # { "id": "kb_x", "name": "Eng", … }
weknora kb list --format json --jq '.[] | {id, name}' # project to listed fields
weknora kb list --format json --jq '.[].id' # jq over the bare data
weknora kb list --format json # {"ok":true,"data":[{"id":"kb_x",…}],"meta":{"count":1,…}}
weknora kb view kb_x --format json # {"ok":true,"data":{"id":"kb_x","name":"Eng",…}}
weknora kb list --format json --jq '.data[] | {id, name}' # project listed fields out of each item
weknora kb list --format json --jq '.data[].id' # ids only
weknora kb list --format json --jq '.meta.count' # number returned
```
`--format ndjson` is also accepted for streaming list commands; each
@@ -240,7 +263,9 @@ wait/poll outcomes: `operation.timeout`, `operation.failed`, `operation.cancelle
| `7` | `server.*` / `network.*` | transient — retry with backoff |
| `10` | **`input.confirmation_required`** (high-risk write) | ask the human, retry with `-y` only after explicit approval |
| `124` | `operation.timeout` (e.g. `doc wait --timeout` reached) | raise `--timeout` or check the underlying job |
| `130` | `operation.cancelled` (SIGINT / SIGTERM) | stop, do not retry |
| `130` | cancelled by signal — typed `operation.cancelled` errors exit 1; `main.go` promotes the process exit to 130 when the root context was signal-cancelled (SIGINT / SIGTERM) | stop, do not retry |
Run `weknora exit-codes` for the machine-readable matrix (JSON); `weknora help exit-codes` for the human-readable table.
**Exit 10** is the wire-level signal for "destructive write needs
explicit confirmation". Pass `-y/--yes` on `kb delete` /
@@ -260,6 +285,11 @@ is the guard against unintended writes.
single-shot profile overrides without disk writes.
- `weknora mcp serve` exposes a curated read-only tool surface over
stdio MCP for any MCP-compatible client.
- `weknora schema` enumerates every command with its `used_for`, and
`weknora schema <cmd path>` (e.g. `weknora schema doc update`) prints that
command's full contract — `used_for`, `required_flags`, `examples`,
`output`, `warnings`, `risk`, and local `flags` — as the standard envelope,
so an agent can discover the surface without scraping `--help` prose.
---
@@ -346,6 +376,21 @@ weknora session continue-stream sess_abc --message msg_xyz
# Agent must dedupe (by message_id or event hash) to avoid double-processing.
```
### Tool-approval unlock chain
An agent run may pause the stream on a tool-approval event until a human approves or rejects the pending tool call. The unlock sequence:
```bash
# 1. Stream pauses with a tool-approval event carrying a pending_id.
# 2. Surface the pending tool call to the user; get explicit go-ahead.
weknora session tool-approval resolve pend_xxx -y # approve
# weknora session tool-approval resolve pend_xxx --reject --reason "..." -y # reject
# 3. Resume the stream — server replays + tails from where the run was blocked.
weknora session continue-stream sess_abc --message msg_xyz
```
Pass `--modified-args '{"key":"value"}'` to replace tool arguments on approve (must be a non-empty JSON object). Never auto-pass `-y` — the approval is the exit-10 human-in-the-loop gate.
Server-side buffer TTL: 1 hour for redis mode; process lifetime for memory mode (default). After TTL, expect `local.sse_stream_aborted` typed error.
See `cli/AGENTS.md` "Stream recovery" section for the full agent contract.