diff --git a/CHANGELOG.md b/CHANGELOG.md index b153c922..f9e45653 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file. ## [Unreleased] ### 🚀 New Features +- **NEW**: `weknora` CLI v0.2 — the official command-line client lives under `cli/`. Mirrors the `gh` CLI ` ` convention with 10 top-level commands (`api`, `auth`, `chat`, `context`, `doc`, `doctor`, `kb`, `link`, `search`, `version`). Highlights: + - Hybrid search and streaming RAG chat against any knowledge base. + - Project-level binding via `weknora link` writing `.weknora/project.yaml` (vercel/netlify pattern); subcommands auto-resolve `--kb` from the link. + - Stable JSON envelope (`{ok, data, error, _meta, dry_run, risk}`) on every `--json` invocation; closed error-code registry enforced by an AST scanner test. + - Agent affordance: `--dry-run` for write commands, exit-code 10 + `input.confirmation_required` for non-interactive destructive writes, per-command "AI agents:" guidance auto-shown when CLAUDECODE / CURSOR_AGENT is set. Operational contract in `cli/AGENTS.md`. + - Multi-context auth (`login` / `logout` / `list` / `status`), OS keyring + 0600 file fallback for credentials, both API-key and password (JWT) modes. + - Health check via `weknora doctor` (4 statuses: ok / warn / fail / skip). + - See `cli/README.md` for install + 5-minute quickstart. - **NEW**: Adaptive 3-tier chunking — documents are now profiled before splitting and routed to one of three strategies: heading-aware (Markdown structure), heuristic (form-feeds, multilingual chapter markers DE/EN/ZH, all-caps titles, visual separators), or recursive (the modernized legacy splitter as a fallback). Auto-strategy is the new default for fresh KBs; existing KBs keep their previous behavior until the user opts in. See `docs/CHUNKING.md`. - **NEW**: KB editor — chunking settings panel surfaces the new strategy selector (Automatic / Markdown-optimized / Smart structure detection / Classic) plus advanced options for token limit per chunk and language hints. Sharper inline help text on every setting explains when defaults apply and when to tune. - **NEW**: Chunking debug panel — embedded "Test with sample text" panel under the chunking settings. Paste a snippet, hit Run preview, see selected tier, rejected tiers + reasons, document profile, size distribution stats over the full chunk set, and per-chunk cards with breadcrumb + content preview. Read-only, no DB or embedding side effects, 5-second server-side timeout. diff --git a/README.md b/README.md index 0394d559..7c432db1 100644 --- a/README.md +++ b/README.md @@ -267,6 +267,24 @@ The [WeKnora Mini Program](./miniprogram/README.md) provides a lightweight mobil - **Hybrid Search** — Search within or across knowledge bases with vector + keyword retrieval - **Knowledge Management** — List, browse, edit, and delete knowledge entries programmatically +## ⌨️ 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 ` ` convention; output is +human-readable by default and switches to a stable JSON envelope with `--json`. + +```bash +weknora auth login --host https://kb.example.com +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. + ## 🚀 Getting Started ### 🛠 Prerequisites diff --git a/cli/AGENTS.md b/cli/AGENTS.md index 4f767385..16ea5466 100644 --- a/cli/AGENTS.md +++ b/cli/AGENTS.md @@ -167,6 +167,42 @@ inspiration) only tags User-Agent for telemetry, never flips 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 — `gh` CLI as the primary mainstream north star.** When weknora's +v0.0/v0.1 surface was audited against gh / kubectl / cargo / npm / git / +docker / flyctl / vercel / supabase / brew, gh emerged as the closest fit +for an opinionated noun-verb tool with a stable JSON envelope and an +agent-aware error model. Documented deviations: + +- `link` (project-binding) borrows from `vercel link` / `netlify link` + rather than gh's per-host config model — a `/.weknora/project.yaml` + walk-up matches how RAG users scope work to a specific knowledge base. +- `chat` / `search` are domain-specific verbs gh has no analog for. +- `context use` (kubectl idiom) instead of gh's `auth switch` — weknora's + context bundles host + tenant + credential, which is more than gh's + per-host account model. +- `doctor` (flutter / brew idiom) instead of gh's `status` (which is an + activity feed, different concept) — RAG deployments routinely break on + misconfigured embeddings / storage / credentials, so a structured + 4-status diagnostic is the agent-readable surface for that. + +Verb canon: `list / view / create / delete / upload / use` (all gh-canonical). + +**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"` diff --git a/cli/README.md b/cli/README.md new file mode 100644 index 00000000..3f14b4cc --- /dev/null +++ b/cli/README.md @@ -0,0 +1,184 @@ +# weknora — WeKnora CLI + +A command-line interface for the WeKnora RAG knowledge-base server. Lets you +authenticate, manage knowledge bases and documents, run hybrid search, and +ask streaming RAG questions from your terminal or from an AI agent. + +```bash +$ weknora --help +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: + 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 + 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 + kb Manage knowledge bases + link Bind the current directory to a knowledge base + search Hybrid (vector + keyword) chunk retrieval against a knowledge base + version Show CLI build metadata +``` + +The command surface mirrors `gh` CLI's ` ` convention. See +[AGENTS.md](AGENTS.md) for the operational contract that AI agents +(Claude Code, Cursor, Aider, …) can rely on: envelope schema, exit-code +protocol, error-code registry, and per-command guidance. + +--- + +## Install + +### From source + +Requires Go 1.24+. + +```bash +git clone https://github.com/Tencent/WeKnora.git +cd WeKnora/cli +go build -o weknora . +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. + +--- + +## 5-minute quickstart + +```bash +# 1. Log in to your WeKnora server (interactive password prompt) +weknora auth login --host https://kb.example.com + +# 2. Or pipe an API key from stdin (for CI / agents) +echo "sk-..." | weknora auth login --host https://kb.example.com --with-token + +# 3. List knowledge bases +weknora kb list + +# 4. Bind this directory to a knowledge base — subsequent commands auto-resolve --kb +weknora link --kb my-knowledge-base + +# 5. Upload a document +weknora doc upload notes.md + +# 6. Search +weknora search "what is reciprocal rank fusion?" + +# 7. Ask the LLM (streams to terminal) +weknora chat "summarise the design doc" +``` + +--- + +## Multi-context + +Switch between several WeKnora servers (or several tenants on the same server) +without re-logging in: + +```bash +weknora auth login --host https://prod.example.com --name prod +weknora auth login --host https://staging.example.com --name staging --with-token < .staging-key +weknora auth list +weknora context use prod +``` + +Credentials are persisted to your OS keyring (Keychain on macOS, libsecret on +Linux, Wincred on Windows) when available, otherwise to a 0600-mode file +under `$XDG_CONFIG_HOME/weknora/secrets/`. The active context lives in +`~/.config/weknora/config.yaml`. + +To remove a context's stored credentials: + +```bash +weknora auth logout # current context +weknora auth logout --name staging # specific +weknora auth logout --all +``` + +--- + +## JSON envelope output + +Every command supports `--json`, returning a stable envelope shape: + +```json +{ + "ok": true, + "data": { /* command-specific payload */ }, + "_meta": { "context": "prod", "kb_id": "kb_abc" } +} +``` + +On error: + +```json +{ + "ok": false, + "error": { + "code": "auth.unauthenticated", + "message": "...", + "hint": "run `weknora auth login`" + } +} +``` + +The full schema, error-code registry, and exit-code protocol (0 / 1 / 2 / 10 +/ 130) are documented in [AGENTS.md](AGENTS.md). + +--- + +## Agent / scripting integration + +Designed to be agent-first: + +- `--dry-run` previews any write command (kb create/delete, doc + upload/delete, api POST/PUT/PATCH/DELETE) without hitting the server, + emitting an envelope with `risk` classification and `dry_run: true`. +- `-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 ` for single-shot + context override. +- Set `CLAUDECODE` or `CURSOR_AGENT` environment variables to surface + per-command "AI agents:" guidance in `--help` output. + +--- + +## Health check + +Run `weknora doctor` for a 4-status diagnostic (OK / warn / fail / +skip) covering base URL reachability, authentication, server-CLI +version skew, and credential storage backend. Add `--json` for +machine-readable output, `--offline` to skip network checks. + +--- + +## Development + +```bash +# Run unit + contract tests +go test ./... + +# Run the real-server e2e suite (requires WEKNORA_E2E_HOST + token env vars) +go test -tags acceptance_e2e ./acceptance/e2e/... + +# Static analysis +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/`. + +--- + +## License + +MIT — see the repository [LICENSE](../LICENSE).