refactor(cli): drop aiclient package; align AGENTS.md with mainstream

Survey of 10 mainstream CLIs (gh, lark, stripe, vercel, supabase, aws,
azure, gcloud, openai/codex, github-copilot-cli) showed env-gated
per-command --help blurbs are a Stripe-only pattern; gh uses env detect
for telemetry only, and lark relies on installed agent Skills + MCP.
Our cmd/mcp/serve already covers the dominant 2025/26 path, so
internal/aiclient/ (136 LOC + 38 callsites) is net maintenance burden
without precedent.

- Drop internal/aiclient/ entirely (annotations + detect + tests)
- Remove 38 SetAgentHelp callsites + agentAwareHelpFunc / SetHelpFunc
  wiring in cmd/root.go
- Migrate 4 command-level rules to standard Long help (visible to all,
  not env-gated): doc upload mode mutex, kb edit at-least-one,
  kb pin idempotent, search chunks channel mutex
- Rewrite AGENTS.md as a developer guide (gh-style 6 H2 / 167 lines):
  audience preamble + Build / Architecture / Command Structure /
  Testing / Code Style / Error Handling. Drops sections absent in
  surveyed projects (Commit & PR Conventions, Who Uses This CLI)
- Clean 14 internal doc refs (ADR-N, spec §X, v0.X) in source comments
  and docs that pointed at docs/superpowers/ — that directory is
  local-only / uncommitted, so refs are dead for outside readers
- Drop forward-looking "once v0.2 ships" from README
This commit is contained in:
nullkey
2026-05-15 02:16:45 +08:00
committed by lyingbug
parent a0dd989c81
commit f2e8e3f56c
111 changed files with 575 additions and 908 deletions
+71 -25
View File
@@ -10,24 +10,28 @@ WeKnora CLI lets you authenticate, browse knowledge bases, and run
hybrid searches against a WeKnora server from your shell or an AI agent.
Available Commands:
agent Manage and invoke custom agents
api Make a raw API request to the WeKnora server
auth Manage authentication credentials and contexts
chat Ask a streaming RAG question against a knowledge base
completion Generate the autocompletion script for the specified shell
context Manage CLI contexts (named connection targets)
doc Manage documents in a knowledge base
doctor Run 4 self-checks: base URL, auth, server version, credential storage
help Help about any command
kb Manage knowledge bases
link Bind the current directory to a knowledge base
mcp Run weknora as a Model Context Protocol server
search Search across chunks, knowledge bases, documents, or sessions
session Manage chat sessions
unlink Remove the directory's knowledge-base binding
version Show CLI build metadata
```
The command surface mirrors `gh` CLI's `<noun> <verb>` convention. See
[AGENTS.md](AGENTS.md) for the operational contract that AI agents
(Claude Code, Cursor, Aider, …) can rely on: bare-JSON output shape,
stderr error format, exit-code protocol, error-code registry, and
per-command guidance.
The command surface mirrors `gh` CLI's `<noun> <verb>` convention. The
wire contract for AI agents (Claude Code, Cursor, Aider, …) is documented
[below](#wire-contract). For contributing to the CLI source, see
[AGENTS.md](AGENTS.md).
---
@@ -35,7 +39,7 @@ per-command guidance.
### From source
Requires Go 1.24+.
Requires Go 1.26+.
```bash
git clone https://github.com/Tencent/WeKnora.git
@@ -47,8 +51,7 @@ 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)
once v0.2 ships.
release. Grab the latest from the [Releases page](https://github.com/Tencent/WeKnora/releases).
---
@@ -106,7 +109,20 @@ weknora auth logout --all
---
## JSON output
## Wire contract
Designed to be agent-first. Stable across minor releases; breaking
changes announced in the changelog and the corresponding
`weknora --version` bump.
### Streams
- **stdout** is the data channel: bare JSON with `--json`, or
human-formatted output. Never carries error text.
- **stderr** is logs, progress, warnings, and errors. A non-empty
stderr does **not** mean failure — read the exit code.
### JSON output
Every command supports `--json`, emitting bare JSON for the resource it
produces — an array for `list` / `search`, a single object for `view`
@@ -119,32 +135,62 @@ weknora kb list --json=id,name # project to listed fields
weknora kb list --json --jq '.[].id' # jq over the bare data
```
Note the `=` form for projection: 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` + the positional
`id,name`. Always use `--json=field,...`.
### Errors
On failure, stdout stays empty and the typed error goes to stderr in
`code: message\nhint: ...` form:
this format:
```
<code.namespace>: <message>[: <wrapped cause>]
hint: <actionable next-step>
```
Example:
```
auth.unauthenticated: fetch current user: HTTP error 401: ...
hint: run `weknora auth login`
```
The typed exit code (3 / 4 / 5 / 6 / 7 / 10) carries the failure
class for agents that branch on it. The full error-code registry and
exit-code protocol are documented in [AGENTS.md](AGENTS.md).
The full code registry is in `cli/internal/cmdutil/errors.go`
(`AllCodes()`). Code namespaces: `auth.*` / `resource.*` / `input.*` /
`server.*` / `network.*` / `local.*` / `mcp.*`.
---
### Exit codes
## Agent / scripting integration
| Code | Meaning | Agent action |
|---|---|---|
| `0` | success | continue |
| `1` | typed `local.*` or unclassified | read stderr, decide retry/abort |
| `2` | flag / argument validation error | re-check `weknora <cmd> --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, retry |
| `6` | `server.rate_limited` | back off, retry |
| `7` | `server.*` / `network.*` | transient — retry with backoff |
| `10` | **`input.confirmation_required`** (high-risk write) | ask the human, retry with `-y` only after explicit approval |
| `130` | cancelled (SIGINT / Ctrl-C) | stop, do not retry |
Designed to be agent-first:
**Exit 10** is the wire-level signal for "destructive write needs
explicit confirmation". Pass `-y/--yes` on `kb delete` / `kb empty` /
`doc delete` / `session delete` / `context remove` (on the current
context) when running headless. **Never auto-add `-y` without the
user's explicit go-ahead** — exit 10 is the guard against unintended
writes.
- `-y/--yes` skips confirmation prompts for high-risk writes. **Without
`-y` on a non-TTY/`--json` invocation, destructive commands return
`error.code: input.confirmation_required` and exit code 10** so an
agent can ask the user before retrying.
- `--json` coexists with the global `--context <name>` for single-shot
context override.
- Set `CLAUDECODE` or `CURSOR_AGENT` environment variables to surface
per-command "AI agents:" guidance in `--help` output.
### Other agent ergonomics
- For chat / agent invoke in agent contexts, prefer `--no-stream --json`
— streaming tokens to stdout makes JSON parsing impossible.
- `--json` composes with the global `--context <name>` for single-shot
context overrides without disk writes.
- `weknora mcp serve` exposes a curated readonly tool surface over
stdio MCP for Claude Desktop / Code / custom MCP clients.
---
@@ -171,7 +217,7 @@ go vet ./...
```
CI (`.github/workflows/cli.yml`) runs build + unit + contract tests on Linux /
macOS / Windows × Go 1.24, path-filtered to changes under `cli/`.
macOS / Windows × Go 1.26, path-filtered to changes under `cli/`.
---