docs(cli): sweep stale wire vocab from AGENTS.md and close the CI gap that let it drift

The v0.9/v0.10 renames left `agent_invoke`, `session continue-stream`, and three
deleted `mcp.*` error codes documented as current, so agents integrating against
AGENTS.md branch on a surface the CLI no longer has.

Two gaps let this drift sit undetected:

- check-skill-wire-vocab.sh already banned every one of these terms, but only
  scanned skills/. The authoritative contract doc that skills are condensed from
  was never checked. Scan AGENTS.md and README.md too, and assert the scan
  targets exist so coverage cannot silently shrink again. CHANGELOG.md stays out
  of scope: recording a rename requires naming the legacy term.
- errors_doc_test.go only verified code -> doc, so a removed code could linger in
  the reference table forever. Add the reverse direction.

Also drops the matching `mcp.*` reference from the ExitCode doc comment.
main
drakezhang 2026-08-19 17:31:55 +08:00 committed by lyingbug
parent 8c0e634ee9
commit a788115ef3
5 changed files with 103 additions and 20 deletions

View File

@ -47,7 +47,7 @@ jobs:
run: go test -race -coverprofile=coverage.out ./...
- name: go vet
run: go vet ./...
- name: Check skill wire vocabulary
- name: Check agent-facing doc wire vocabulary
if: runner.os == 'Linux'
run: scripts/check-skill-wire-vocab.sh
- name: Check for committed credentials in docs

View File

@ -412,9 +412,6 @@ Agents parse the first colon to extract the typed code. The exit code class (see
| `local.upload_file_not_found` | 1 | no | verify the path is correct and readable |
| `local.user_aborted` | 1 | no (user said no) | no action taken; pass `-y/--yes` to skip the confirmation prompt |
| `internal.error` | 1 | no | catch-all for an untyped error that reached the top (a bug or unmapped dependency error); a recurring one is a classification gap worth reporting |
| `mcp.readonly_mode` | 1 | no | MCP tool surface is read-only; mutations not exposed in this mode |
| `mcp.schema_unknown_command` | 1 | no | (no canonical hint) |
| `mcp.tool_not_allowed` | 1 | no | MCP tool not in the curated allowlist |
<!-- ERROR_REFERENCE_END -->
@ -460,7 +457,7 @@ auto-retry this exit code — every exit 10 is a user-in-the-loop decision.
## Stream recovery
The `weknora session continue-stream <session-id> --message <msg-id>` command resumes an SSE event stream for an existing assistant message. Use cases: network-blip recovery, long-running agent invocation polling, completed-stream inspection.
The `weknora session resume <session-id> --message <msg-id>` command resumes an SSE event stream for an existing assistant message. Use cases: network-blip recovery, long-running agent invocation polling, completed-stream inspection.
### Server semantics: replay-from-0, not cursor-resume
@ -479,7 +476,7 @@ The server **replays all stored events from the start** of the assistant message
| `STREAM_MANAGER_TYPE=redis` | **1 hour** (server-side; not configurable from the CLI) |
| `STREAM_MANAGER_TYPE=memory` (default) | **Process lifetime** (server restart = data loss; no explicit cleanup logic) |
After TTL, `weknora session continue-stream` returns the typed error `local.sse_stream_aborted`, which maps to exit code 1 per the Error code reference.
After TTL, `weknora session resume` returns the typed error `local.sse_stream_aborted`, which maps to exit code 1 per the Error code reference.
## Dry-run contract
@ -552,7 +549,7 @@ The curated 10 tools (`cli/internal/mcp/tools.go`):
| `search_chunks` | hybrid (vector + keyword) retrieval |
| `chat` | stream a RAG answer; auto-creates a session if absent |
| `agent_list` | list custom agents |
| `agent_invoke` | run a query through a custom agent |
| `session_ask` | run a query through a custom agent |
Adding a tool is a deliberate API expansion — the AI-agent-callable surface is the reason this CLI ships an MCP server, not its CLI command list, so the registration list in `registerTools` is maintained by hand.

View File

@ -7,13 +7,10 @@ import (
"testing"
)
// TestAllCodes_DocumentedInAGENTS verifies every typed code returned by
// AllCodes() surfaces in cli/AGENTS.md "Error code reference" section
// (delimited by ERROR_REFERENCE_START/END markers).
//
// Prevents drift: a contributor adding a new ErrorCode without updating
// the doc fails this test, forcing the doc to stay current.
func TestAllCodes_DocumentedInAGENTS(t *testing.T) {
// loadErrorReferenceSection returns the body of the cli/AGENTS.md "Error code
// reference" section, delimited by the ERROR_REFERENCE_START/END markers.
func loadErrorReferenceSection(t *testing.T) string {
t.Helper()
// From cli/internal/cmdutil/, go up two levels to find cli/AGENTS.md.
docPath, err := filepath.Abs("../../AGENTS.md")
if err != nil {
@ -32,7 +29,42 @@ func TestAllCodes_DocumentedInAGENTS(t *testing.T) {
if startIdx == -1 || endIdx == -1 || endIdx <= startIdx {
t.Fatalf("error-reference markers missing or malformed in %s:\n start=%d end=%d", docPath, startIdx, endIdx)
}
refSection := doc[startIdx:endIdx]
return doc[startIdx:endIdx]
}
// documentedCodes extracts the codes listed in the first column of the error
// reference table. Only the first column is read: hint cells also carry
// backticked flags, paths, and commands that are not error codes.
func documentedCodes(refSection string) []string {
var codes []string
for _, line := range strings.Split(refSection, "\n") {
line = strings.TrimSpace(line)
if !strings.HasPrefix(line, "|") {
continue
}
cells := strings.Split(strings.Trim(line, "|"), "|")
if len(cells) == 0 {
continue
}
// Skips the header ("Code") and separator ("---") rows, which carry no
// backticks in the first column.
first := strings.TrimSpace(cells[0])
if len(first) < 3 || !strings.HasPrefix(first, "`") || !strings.HasSuffix(first, "`") {
continue
}
codes = append(codes, strings.Trim(first, "`"))
}
return codes
}
// TestAllCodes_DocumentedInAGENTS verifies every typed code returned by
// AllCodes() surfaces in cli/AGENTS.md "Error code reference" section
// (delimited by ERROR_REFERENCE_START/END markers).
//
// Prevents drift: a contributor adding a new ErrorCode without updating
// the doc fails this test, forcing the doc to stay current.
func TestAllCodes_DocumentedInAGENTS(t *testing.T) {
refSection := loadErrorReferenceSection(t)
missing := []string{}
for _, c := range AllCodes() {
@ -46,3 +78,37 @@ func TestAllCodes_DocumentedInAGENTS(t *testing.T) {
strings.Join(missing, "\n - "))
}
}
// TestDocumentedCodes_RegisteredInAllCodes is the reverse of
// TestAllCodes_DocumentedInAGENTS: every code the doc advertises must still be
// a code the CLI can emit.
//
// Without this direction a removed code lingers in the doc forever, and agents
// branch on codes that will never arrive — the failure mode that left three
// `mcp.*` codes documented for two minor versions after they were deleted.
func TestDocumentedCodes_RegisteredInAllCodes(t *testing.T) {
refSection := loadErrorReferenceSection(t)
registered := make(map[string]bool, len(AllCodes()))
for _, c := range AllCodes() {
registered[string(c)] = true
}
documented := documentedCodes(refSection)
// Guards against the parser silently matching nothing, which would make this
// check pass vacuously if the table format ever changes.
if len(documented) == 0 {
t.Fatal("parsed zero error codes out of the reference table; the table format or the parser changed")
}
stale := []string{}
for _, c := range documented {
if !registered[c] {
stale = append(stale, c)
}
}
if len(stale) > 0 {
t.Errorf("the following error codes are documented in cli/AGENTS.md \"Error code reference\" but are not registered in AllCodes():\n - %s\n\nDrop the row if the code was removed, or register the code if the row is correct.",
strings.Join(stale, "\n - "))
}
}

View File

@ -35,7 +35,7 @@ func GetProfile() string { return globalProfile }
// ExitCode maps an error to the documented CLI exit code.
// - 0 success
// - 1 generic / unknown typed error - fallback bucket: resource.already_exists,
// resource.locked, local.*, mcp.*, operation.failed, server.session_create_failed
// resource.locked, local.*, operation.failed, server.session_create_failed
// (workflow-level, see special case below), and any code outside the named
// buckets below
// - 2 cobra-parse problem (unrecognised flag, arg-count violation) —

View File

@ -1,7 +1,7 @@
#!/usr/bin/env bash
# check-skill-wire-vocab.sh — fail if cli/skills/ still references wire
# vocabulary that the CLI has renamed or removed. Wire-shape changes must
# sweep skills in the same PR.
# check-skill-wire-vocab.sh — fail if the agent-facing docs still reference wire
# vocabulary that the CLI has renamed or removed. Wire-shape changes must sweep
# every agent-facing doc in the same PR.
set -euo pipefail
cd "$(dirname "$0")/.."
@ -18,13 +18,33 @@ BANNED=(
"agent create --kb:agent create --attach-kb (renamed in v0.9)"
"kb init:kb config set (renamed — kb init removed)"
"continue-stream:session resume (renamed)"
"retry_command:retry_argv (error envelope field renamed in v0.10)"
)
# Every doc an agent or integrator reads as current truth. AGENTS.md and
# README.md are in scope because they are the authoritative wire contract that
# skills are condensed from — a rename that lands in skills/ but not here leaves
# the source of truth wrong.
#
# CHANGELOG.md is deliberately NOT scanned: recording a rename requires naming
# the legacy term, so scanning it would guarantee a false positive.
SCAN_TARGETS=(skills/ AGENTS.md README.md)
# The v0.10 retry_command miss happened because the scan silently covered less
# than the docs that needed covering. Fail loudly if a target disappears rather
# than quietly shrinking coverage again.
for target in "${SCAN_TARGETS[@]}"; do
if [ ! -e "$target" ]; then
echo "scan target '$target' does not exist — update SCAN_TARGETS" >&2
exit 2
fi
done
fail=0
for entry in "${BANNED[@]}"; do
term="${entry%%:*}"
why="${entry#*:}"
if hits=$(grep -rn --include='*.md' -F "$term" skills/ 2>/dev/null); then
if hits=$(grep -rn --include='*.md' -F "$term" "${SCAN_TARGETS[@]}" 2>/dev/null); then
echo "BANNED wire vocab '$term' found (use: $why):"
echo "$hits"
fail=1