feat(cli)!: v0.10 reliability, agent-UX, and command-surface hardening

A hardening + finalization pass over the agent-first CLI: correctness fixes,
richer machine-readable signals, flag/naming consistency, and a symmetric
config surface. Pre-1.0, so it includes breaking renames.

Correctness:
- agent update: resolve/validate --model/--rerank-model (was storing a bogus
  name verbatim, corrupting config.model_id).
- doctor: honor WEKNORA_HOST / WEKNORA_API_KEY (headless path no longer reports
  "no host configured").
- session ask / MCP session_ask: text answer was empty on non-TTY — the agent
  stream sets Done=true on an intermediate agent_query frame before the answer,
  and AgentAccumulator treated the first Done as terminal. Terminate on the
  `complete` event (new sdk.AgentResponseTypeComplete), not a per-frame Done.
- batch exit codes: any per-item failure collapses to operation.failed (exit 1),
  including `doc upload --recursive` partial failures — a permanent per-file
  failure (e.g. a duplicate) no longer surfaces as a retryable exit 7 an agent
  would loop on; per-item typed errors stay in the envelope.

Agent-first signals & discovery:
- error.exit_code in the envelope (type + exit_code disambiguate the
  input.invalid_argument exit-2-vs-5 split in one JSON read).
- meta.hint on empty content search and on draft doc create; doc wait fails fast
  on a never-parsing draft instead of hanging to --timeout.
- retrieval-readiness is visible in the natural flow: kb status / kb check emit
  retrieval_ready, and kb create hints the fix when no embedding model is bound
  — an unconfigured KB no longer looks silently healthy.
- schema contract completeness: every leaf declares output + >=1 example
  (drift-guarded); output strings match the meta actually emitted; chunk list
  and search docs now emit meta.total_count (both previously dropped it).
- schema tolerates a quoted multi-word command label; zero-state auth — and
  `link` with no profile — point at profile setup / the headless WEKNORA_KB_ID
  path instead of looping on `auth login`.
- id-addressed reads tolerate a redundant --kb (doc view/wait, chunk list/view
  accept and ignore it, declared in schema) so a carried-over --kb doesn't
  exit 2; streaming commands warn that --jq does not apply to an NDJSON stream.
- keep JSON-always as the default; --jq hints spell out the .data path.

Consistency & gating:
- doc create: drop the deprecated --name alias (--title only; pre-1.0 break).
- chunk list --limit aligned to 1..10000; model list --limit/-L with
  has_more/total_count; api write-gates -X PUT/PATCH (exit 10); skills install
  expands a leading ~.
- docs corrected: search docs / doc list --keyword help is case-insensitive
  (server does LOWER LIKE); AGENTS.md risk-action list (no phantom kb.init; add
  model.update / kb.config.set) and batch example (failed item carries `error`);
  session resume --message id comes from `message list`, not the stream.
- auth/profile ergonomics: env credentials are now first-class — `auth token`
  prints the active WEKNORA_API_KEY / WEKNORA_TOKEN, and auth login/logout/refresh
  give an env-aware message instead of looping on "run auth login". `auth logout`
  clears credentials but keeps the profile registered (host preserved for
  re-login); deleting a profile is `profile remove`'s job (clean logout/remove
  separation, matching gh / lark).

Config surface (symmetric read/write, in-place model edits):
- kb config now returns a secret-free KBModelConfigView (was {}); `kb config`
  reads, new `kb config set` writes; `kb init` removed (misnomer).
- kb create --chat-model: retrieval-ready in one step.
- model update: edit a model in place (id preserved, references survive) —
  rotate --api-key-stdin, change base-url / display-name / etc.
- session continue-stream renamed to session resume.

Docs: AGENTS.md is the single wire-contract source; CHANGELOG slimmed; stale
kb-init / continue-stream references removed; skill wire-vocab guard extended.
AGENTS.md / weknora-shared SKILL document retrieval_ready (a KB needs an
embedding model to be searchable), that --jq does not apply to NDJSON
streams, and the env-credential-first auth path; the KB quickstart example
now creates a retrieval-ready KB.
This commit is contained in:
nullkey
2026-07-02 15:53:51 +08:00
committed by lyingbug
parent 040a734766
commit d3c03b2f34
95 changed files with 1711 additions and 436 deletions
+1 -1
View File
@@ -52,7 +52,7 @@ one wastes turns or returns the wrong shape. Use the decision table.
connection; the server keeps generating + billing). Stop it server-side:
`weknora session stop <session-id> --message <message-id>` (session_id from
`data.session_id`, or from `init` under `--format ndjson`).
Re-attach to a stream with `weknora session continue-stream <session-id>
Re-attach to a stream with `weknora session resume <session-id>
--message <message-id>`.
- `search chunks --limit` defaults to **8** (tuned for an LLM context window);
the `search docs/kb/sessions` lists default to 30. Tune retrieval with
@@ -39,7 +39,7 @@ events through verbatim:
- Accumulate `response_type:"answer"` `content` pieces for the final answer.
- `knowledge_references` carry the grounding chunks (source attribution).
- **Keep `init.session_id`** to continue the chat (`--session`). The
`assistant_message_id` needed for `session stop` / `session continue-stream`
`assistant_message_id` needed for `session stop` / `session resume`
rides on the SDK's `agent_query` frame, not on `init` — scan for it.
- On failure mid-stream you get `response_type:"error"`; a transport/HTTP error
surfaces as the normal error envelope on stderr with a typed code.
@@ -49,7 +49,7 @@ events through verbatim:
- **Stop server-side generation:** `weknora session stop <session-id> --message
<message-id>`. Ctrl-C only closes your local connection — the server keeps
generating (and billing) until told to stop.
- **Re-attach after a dropped connection:** `weknora session continue-stream
- **Re-attach after a dropped connection:** `weknora session resume
<session-id> --message <message-id>`. The server replays the event log from
index 0 then tails new events, so **dedupe by message_id** if you already
consumed some events. Buffer TTL is ~1h (redis) or process-lifetime (memory).
+35 -12
View File
@@ -13,6 +13,12 @@ output, not prose. Read this skill before any task-specific `weknora-*` skill.
## 1. Authenticate (do this first — order matters)
**Agents usually skip profiles entirely:** set `WEKNORA_API_KEY` (or
`WEKNORA_TOKEN`) + `WEKNORA_HOST` and every command authenticates statelessly and
zero-disk — no `profile add` / `auth login` needed. `auth token` echoes that env
credential; `auth status` / `doctor` confirm it. The steps below set up a
**persistent named profile** instead (interactive / multi-environment use).
Authentication is a **two-step sequence**. `weknora auth login` operates on the
*active profile*, so the profile must exist first:
@@ -31,7 +37,11 @@ weknora auth status # verify: who am I, which tenant
(e.g. `weknora --profile staging auth refresh`). There is no per-command
`--name`/`--host` on auth commands.
- Get the raw token for scripting with `WEKNORA_TOKEN=$(weknora auth token)`
(raw token by default; `--format json` gives the `{token, mode, profile}` envelope).
(raw token by default; works with an env credential too; `--format json` gives
the `{token, mode, profile}` envelope).
- `weknora auth logout` clears a profile's stored credentials but **keeps the
profile registered** (re-auth later with `auth login`); use `profile remove`
to delete the profile entirely.
- `weknora doctor` runs 4 health checks (reachability, credential, version, storage).
## 2. Selecting a knowledge base (`--kb`)
@@ -42,6 +52,15 @@ the cwd) → error. Read/create commands that operate "inside a project" inherit
the link; **`search *` and destructive `--all` operations always require an
explicit `--kb`** (so an agent never silently hits the wrong corpus).
**A KB must have an embedding model bound to be searchable.** A freshly created
KB is `retrieval_ready:false` — uploaded docs stay unindexed and `search`/`chat`
return nothing until you bind models. Create it ready in one step
(`kb create --embedding-model <m> --chat-model <m>`, discover ids with
`weknora model list`) or bind after the fact
(`kb config set <kb> --embedding-model <m> --chat-model <m>`). `kb status` /
`kb check` report `retrieval_ready`, and `kb create` hints the fix when it is
false — so an unconfigured KB is never silently "healthy".
## 3. Output contract — every command
Default output is `--format json`: a single envelope.
@@ -60,18 +79,22 @@ Default output is `--format json`: a single envelope.
- `--format text` = a live human-readable projection. `chat` and `session ask`
buffer a bounded answer-event projection into one JSON envelope by default;
pass `--reference` for indexed citations, `--verbose` for execution detail,
or `--format ndjson` for raw event lines. `session continue-stream` remains
or `--format ndjson` for raw event lines. `session resume` remains
an NDJSON streaming command.
- `--jq '<expr>'` filters the envelope (e.g. `weknora kb list --jq '.data[].id'`).
- Exception: `weknora auth token` emits the **raw token** by default (it's a
scripting helper); pass `--format json` for the `{token, mode, profile}` envelope.
- **Batch / wait caveat:** for multi-item commands (`doc/chunk/session delete`
with several ids, `doc wait`), `ok:true` means *the command ran to completion*,
**not** that every item succeeded — per-item failures live in `data` and the
**exit code** carries the aggregate verdict (e.g. `doc wait` exits 1 if any doc
failed, 124 on timeout, while still printing the `{completed,failed,timeout}`
partition with `ok:true`). For these, branch on the **exit code**, then read
`data` for which items failed.
- **Batch / wait caveat:** multi-item commands come in two shapes, but for
**both you branch on the exit code, not `ok`**:
- `doc/chunk/session delete` with several ids → a **batch** envelope:
`status` is `success`/`partial`/`error`, `ok` is `true` *only* when every
item succeeded (**`ok:false` on any failure**), `data` is a per-item array
`[{id, ok, result|error}]`, and `meta.successes`/`failures` count the split.
Exit 1 if any item failed.
- `doc wait` → a normal `ok:true` envelope whose `data` partitions the ids
into `{completed, failed, timeout}`; `ok` stays `true` even with failures
(to avoid a contradictory envelope). Exit 1 if any doc failed, 124 on timeout.
Either way, read the **exit code** first, then `data` for which items failed.
## 4. Exit codes (branch on these)
@@ -138,7 +161,7 @@ An agent run pauses mid-stream on a tool-approval event when the server requires
1. The stream emits a tool-approval event; capture the `pending_id`.
2. **Surface the pending tool call to the user** (show tool name + proposed args). Do not auto-approve.
3. After explicit user go-ahead: `weknora session tool-approval resolve <pending-id> -y` to approve, or add `--reject --reason "..."` to reject.
4. Resume the answer: `weknora session continue-stream <sess-id> --message <msg-id>`.
4. Resume the answer: `weknora session resume <sess-id> --message <msg-id>`.
`--modified-args '{"key":"val"}'` replaces the tool arguments on approve (non-empty JSON object required). This is an exit-10 interaction — see §5.
@@ -148,10 +171,10 @@ An agent run pauses mid-stream on a tool-approval event when the server requires
kb knowledge bases list/view/create/update/delete/pin/unpin/status/check
doc documents in a KB list/view/create/upload/fetch/download/reparse/update/delete/wait
chunk retrieval units list/view/delete (RAG debug; not search)
session conversations list/view/delete/ask/stop/continue-stream/tool-approval resolve
session conversations list/view/delete/ask/stop/resume/tool-approval resolve
message session messages list/search/delete
agent custom agents list/view/create/update/delete/status/check
model configured models list/view (read-only; find the id for agent create --model)
model configured models list/view/create/update/delete (update rotates key / base-url in place, id preserved)
search retrieval chunks / docs / kb / sessions
chat one-shot KB RAG Q&A (streaming)
api raw HTTP passthrough to any server endpoint (escape hatch)