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:
+71
-25
@@ -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/`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user