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
+123 -315
View File
@@ -1,359 +1,167 @@
# Agent Integration Guide for `weknora` CLI
# AGENTS.md
> **Scope.** This file is an **operational reference** for LLM agents
> (Claude Code, Cursor, Codex, Aider, Gemini Coder, etc.) that **invoke
> `weknora` on a user's behalf**. It documents the wire shape, exit code,
> and behavioral conventions an agent integration relies on.
>
> This is **not** a contributor guide. If you are an AI coding agent
> editing weknora's source, see the repo root `README.md` (and, if added
> later, a separate contributor `AGENTS.md` at the repo root).
>
> **Naming note.** "Agent" appears in two distinct WeKnora contexts:
>
> - **This file (`AGENTS.md`) + the `agent_help` annotation on each
> command's `--help`**: documents the contract for AI coding agents
> (you, the LLM-driven CLI consumer).
> - **The `weknora agent` subtree** (`agent list / view / invoke`):
> manages WeKnora's first-class *Custom Agent* resources — server-side
> records (system prompt + model + allowed tools + KB scope) that the
> user authored in the web UI. `agent invoke` calls the agent's
> configured workflow against a query; it is **not** how you, the AI
> coding agent, drive WeKnora — that's `kb` / `doc` / `search` / `chat`
> / `mcp serve`.
WeKnora CLI (`weknora`) is a noun-verb wrapper around the WeKnora server API; module path `github.com/Tencent/WeKnora/cli`. This file is the developer guide for coding agents and human contributors editing the CLI. The user-facing wire contract (output shape, exit codes, error format) lives in [README.md](README.md).
`weknora` is designed to be agent-friendly: error messages, output
format, and flag design follow conventions agents can rely on.
Wire-contract breaking changes are flagged in their PR description and
the corresponding `weknora --version` bump — agents should pin a
known-good version and re-validate against `--help` output on upgrade.
The "Output contract" and "Behavioral rules" sections below are the
self-contained specification of the wire format; everything an integrator
needs is in this document.
---
## Output contract
### Streams
- **stdout** is the data channel: bare JSON (with `--json`) or
human-formatted output (without `--json`). Never carries error text.
- **stderr** is logs / progress / warnings / errors / agent guidance
footnotes. On failure, the error message + actionable hint go here.
A non-empty stderr does **not** mean failure — read the exit code instead.
### JSON output (bare data)
When `--json` is set on a successful command, stdout contains exactly
one JSON value matching the resource the command produces:
| Command shape | stdout JSON |
|---|---|
| `list` / `search` | `[ { …resource… }, … ]` (bare array; `[]` when empty) |
| `view` / `create` / `edit` | `{ …resource… }` (bare object) |
| `delete` / `pin` / write ops | `{ id, …action-result fields… }` (bare object) |
| `doctor` | `{ summary: { all_passed, passed, warned, failed, skipped }, checks: [ … ] }` |
There is no `ok` / `data` / `error` wrapper. Agents read the resource
shape directly. Successful runs always return exit 0; failures never
emit data JSON on stdout.
#### Field selection: `--json=field,field,…`
`--json` accepts a comma-separated field list (passed with `=`) to restrict
each top-level object (or each element of a top-level array) to the named
keys:
## Build, Test, and Lint
```bash
weknora kb list --json=id,name # [{ "id": "kb_x", "name": "Eng" }, …]
weknora kb view kb_x --json=id # { "id": "kb_x" }
go build -o weknora . # build (from cli/)
go test -count=1 ./... # unit + contract tests
go test -run TestFoo ./internal/format/ # single test
go test ./acceptance/contract/ -args -update # refresh wire goldens
go test -tags acceptance_e2e ./acceptance/e2e/... # live-server e2e (gated by env)
go vet ./...
```
Note the `=` form: 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` plus the positional `id,name`. Always use
`--json=field,...` for projection.
Both `go test -count=1 ./...` and `go vet ./...` must pass before committing.
Unknown field names are silently dropped so you can pass an aspirational
field set across heterogenous outputs.
## Architecture
#### jq pipeline: `--jq <expr>`
Entry point: `cmd/main.go` → `cmd.Execute()` → `cmd.NewRootCmd(cmdutil.New())`.
`--jq` applies a jq expression to the JSON before printing. The
expression sees the same bare shape the command produces (no envelope
indirection). String results render without quotes for shell-friendly
substitution; non-string results render as JSON.
Key packages:
```bash
weknora kb list --jq '.[].id' # one id per line
weknora kb view kb_x --jq .name # bare name
weknora search chunks "x" --kb e --jq '.[].score' # scores per line
- `cmd/<noun>/` — cobra command implementations, one subdir per noun
- `internal/cmdutil/` — `Factory`, `JSONOptions`, typed `Error`, exit-code mapping, destructive-write confirm, KB id-or-name resolve
- `internal/format/` — bare JSON emitter (`WriteJSON` / `WriteJSONFiltered`)
- `internal/iostreams/` — global IO singleton + TTY detection + `SetForTest` swap
- `internal/secrets/` — `Store` interface; `KeyringStore` primary, `FileStore` 0600 fallback, `MemStore` for tests
- `internal/prompt/` — `TTYPrompter` (huh-based, password no-echo) + `AgentPrompter` (non-TTY no-prompt sentinel)
- `internal/sse/` — `Accumulator` for chat / agent invoke SSE streams
- `internal/mcp/` — curated stdio MCP server (wired by `cmd/mcp/serve.go`)
- `client/` (parent module) — generated SDK
## Command Structure
A command `weknora foo bar` lives in `cmd/foo/bar.go` with `bar_test.go`.
### Canonical Examples
- **Command + tests**: `cmd/kb/list.go` and `list_test.go`
- **Destructive write + confirm protocol**: `cmd/kb/delete.go`
- **SSE streaming command**: `cmd/chat/chat.go`
- **Factory wiring**: `internal/cmdutil/factory.go`
### The Options + Narrow Service Pattern
Every command follows this structure (see `cmd/kb/list.go`):
1. `Options` struct with flag-bound fields
2. `Service` interface declaring only the SDK methods this command calls. `*sdk.Client` satisfies it implicitly via duck typing.
3. `NewCmd<Verb>(f *cmdutil.Factory) *cobra.Command` constructor — flag registration + `cmdutil.AddJSONFlags`
4. Separate `run<Verb>(ctx, opts, jopts, svc, args...)` with the business logic — the test injection point
Key rules:
- Each command owns its own `Service` interface; do NOT share interfaces across `cmd/*` packages. Per-file dependency graph is the goal.
- Lazy-init `f.Client()` / `f.Secrets()` / `f.Prompter()` inside `RunE`, not the constructor (else `--help` forces auth).
- Required flags: `_ = cmd.MarkFlagRequired("name")` — cobra returns the error only on registration-time typo.
- New subtrees register in `cmd/root.go NewRootCmd`. Verb subtrees register their leaves in the subtree's own `NewCmd`.
### Command Examples and Help Text
Use a Go raw string with `weknora` as the example prefix. Keep one-line `Short` ≤ 70 chars; `Long` may run multi-paragraph; `Example` always includes `weknora` so copy-paste works:
```go
Example: ` weknora kb view <id>
weknora kb view kb_abc --json
weknora kb view kb_abc --json=id,name`,
```
`--jq` requires `--json`. Combining with `--json=id,name` is fine — the
filter runs after the field projection.
### JSON Output
### Errors (stderr, exit code carries the class)
Add `--json` / `--jq` via `cmdutil.AddJSONFlags(cmd, fieldNames)`. In `RunE`:
On failure, stdout is empty (or holds the partial-success output the
command already wrote before the failure). The error message goes to
stderr in this format:
```
<error.code>: <message>[: <wrapped cause>]
hint: <actionable next-step>
```go
if jopts.Enabled() {
return jopts.Emit(iostreams.IO.Out, result)
}
```
- `<error.code>` is a `namespace.snake_case` string from a closed
registry in `cli/internal/cmdutil/errors.go` (`AllCodes()`).
An acceptance test enforces that every code referenced in `cli/cmd/`
is registered.
- `<message>` is the human-readable description.
- `<hint>` is the deterministic next-step hint (omitted when no hint
applies).
`Emit` is the single source for the bare-JSON contract — it honors `--json=fields,...` projection and `--jq <expr>` filtering. Never call `format.WriteJSON*` directly from a command. See `cmd/kb/list.go`.
Code namespaces: `auth.*` / `resource.*` / `input.*` / `server.*` /
`network.*` / `local.*` / `mcp.*`.
### Destructive Writes
To pattern-match programmatically: split on the first `:` to extract
the code, or branch on the exit code (see below).
Commands that delete / empty / overwrite call `cmdutil.ConfirmDestructive(p, opts.Yes, jopts.Enabled(), what, id)` before mutation. In non-TTY OR `--json` mode without `-y`, it returns `CodeInputConfirmationRequired` → exit 10. See `internal/cmdutil/confirm.go`.
### Exit codes
## Testing
| Code | Meaning | Agent action |
|---|---|---|
| `0` | Success | Continue |
| `1` | Typed `local.*` error or unclassified | Read stderr, decide retry/abort |
| `2` | Flag/argument validation error | Re-check `weknora <command> --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 and retry |
| `6` | `server.rate_limited` | Back off, then retry |
| `7` | `server.*` / `network.*` | Transient; retry with backoff |
| `10` | **`input.confirmation_required`** — high-risk write needs `-y` | Ask the human, retry with `-y` only after explicit approval |
| `130` | Cancelled (SIGINT / Ctrl-C) | Stop, do not retry |
### Narrow Service Fakes
Exit 10 is the wire-level signal for "high-risk write needs explicit
confirmation". **Never bypass exit 10 by auto-passing `-y` without
explicit user permission.**
Each command's `runX(ctx, opts, jopts, svc, ...)` takes its interface, not `*sdk.Client`. Tests inject plain-struct fakes:
---
## Command surface
Discover the command tree the same way human users do:
```bash
weknora --help # top-level
weknora kb --help # subtree
weknora kb delete --help # single command flags
```go
type fakeBarSvc struct {
gotID string
resp *sdk.Bar
err error
}
func (f *fakeBarSvc) GetBar(_ context.Context, id string) (*sdk.Bar, error) {
f.gotID = id
return f.resp, f.err
}
```
The command tree follows `<noun> <verb>`. Verbs are:
No mocking library; the narrow-interface design makes fakes 5 lines each.
| Verb | Semantics | Example |
|---|---|---|
| `list` | Multi-resource read | `kb list` |
| `view` | Single-resource read | `kb view <id>` |
| `create` | Create resource | `kb create --name X` |
| `edit` | Partial update (only sent fields change) | `kb edit <id> --description X` |
| `delete` | Destructive remove (KB itself) | `kb delete <id> -y` |
| `empty` | Bulk-delete contents, preserve container | `kb empty <id> -y` |
| `upload` | Bulk write content | `doc upload <file>` |
| `download` | Stream resource to disk | `doc download <id> -O file` |
| `pin` / `unpin` | Toggle "pinned" state (idempotent) | `kb pin <id>` |
| `use` | Switch active selection | `context use <name>` |
| `add` / `remove` | Manage local config entries | `context add staging --host ...` |
### IOStreams in Tests
`auth` subtree: `login` / `logout` / `list` / `status` / `refresh` /
`token`. Context-switching uses `context use <name>` (WeKnora contexts
bundle host + tenant + credentials, so they need a richer abstraction
than a single per-host token slot). `auth refresh` exchanges the stored
refresh token for a new access + refresh pair (OAuth refresh-token
grant); it errors with `input.invalid_argument` on API-key contexts
which have no refresh semantic. Transparent 401 → refresh → retry is
wired into the SDK transport (`cli/internal/cmdutil/authretry.go`)
with singleflight de-dup, so most callers never need to invoke `auth
refresh` explicitly.
```go
out, errBuf := iostreams.SetForTest(t) // bytes.Buffer sinks, non-TTY
ios, _ := iostreams.SetForTestWithTTY(t) // simulate terminal
```
### Auth security contract
### Confirm Prompts
- **Credential storage**: OS keychain via `go-keyring` (macOS Keychain,
Windows Credential Manager, freedesktop Secret Service). Falls back to
a 0600 file under `$XDG_CONFIG_HOME/weknora/secrets/<context>/` only
when no keyring backend is available. `auth login` prints a stderr
warning at fallback time; `weknora doctor` flags it under
`credential_storage`.
- **`auth login --with-token`**: reads the API key from **stdin**, never
from a flag value (so it never appears in `ps` / shell history). The
key is validated against `/auth/me` **before** being persisted — a
typo / expired / wrong-host key fails fast with
`auth.bad_credential` and nothing is written.
- **No env-var token bypass**: WeKnora does NOT honor a `WEKNORA_TOKEN`
env var as an implicit credential source — by design, to avoid the
process-environment leak surface (`/proc/<pid>/environ`, `ps -E`,
multi-tenant CI runners). CI / scripts should pipe the key via
`weknora auth login --with-token` into the keyring (or the file
fallback under an isolated `$XDG_CONFIG_HOME`).
- **`auth status` / `auth list`**: never emit token values, in either
human or JSON modes. The `mode` field (`bearer` / `api-key`) signals
which credential class is stored, not the value.
- **`auth token`**: the only command that prints the stored credential.
Stdout has **no trailing newline** so `$(weknora auth token)` is
clean; when stdout is a TTY, a stderr advisory warns the user that
the secret just landed in scrollback, plus an extra note for api-key
mode (long-lived, rotate at the server).
- **`auth refresh` `--json`**: returns only `{context}` — never the new
access or refresh token. Agents that need to verify the new
credential should re-run `auth status` (live `/auth/me` probe).
- **`auth logout`**: local-only — deletes the keyring entry + file
fallback + the context entry in `config.yaml`. **Does NOT revoke
server-side.** For JWT, the issued token stays valid until expiry;
for API keys, rotate them in the server UI.
Use `testutil.ConfirmPrompter{Answer: bool, Err: error}` from `internal/testutil/`. Single source for the prompt double — do NOT re-define `confirmPrompter` per package.
`search` subtree: `search chunks "<q>" --kb X` for hybrid retrieval;
`search kb "<q>"` / `search docs "<q>" --kb X` / `search sessions "<q>"`
for client-side substring filtering on the listing endpoints.
### Assertions
`session` subtree: `list` / `view` / `delete` for chat session
management. Sessions are the durable wrapper around `chat` invocations.
Use `testify`. Prefer `require` (not `assert`) for error checks so the test halts immediately, and `assert` for value comparisons:
Top-level RAG / connectivity verbs: `chat`, `search`, `api`, `link`,
`auth`, `context`, `session`, `doctor`, `version`.
```go
require.NoError(t, err)
require.ErrorAs(t, err, &typed)
assert.Equal(t, "expected", actual)
```
`doctor` is a deliberate WeKnora addition: RAG deployments routinely
break on misconfigured embeddings, storage backends, and credentials,
and the structured `{summary: {all_passed, passed, warned, failed,
skipped}, checks: [...]}` JSON shape is the cleanest agent-readable
surface for that.
### Acceptance: Wire-Shape Goldens
---
`acceptance/contract/wire_test.go` drives the in-process cobra tree against `httptest.Server` fixtures and compares stdout to `acceptance/testdata/wire/<case>.json`. Error-path cases also assert stderr contains the typed code substring (e.g. `auth.unauthenticated`). Update goldens with `go test ./acceptance/contract/ -args -update`.
## Behavioral rules
### Table-Driven Tests
Per-command guidance also appears in each command's `--help` output
(under "AI Agents:").
Use for flag validation, error classification, parser edge cases. See `internal/cmdutil/exit_test.go` and `cmd/kb/list_test.go`.
1. **Pass `-y/--yes`** on destructive writes (`kb delete` / `kb empty` /
`doc delete` / `session delete` / `context remove` when targeting
the current context) when running headless. Without it, you will
get exit 10. **Never auto-add `-y`** without the user's explicit
go-ahead — the exit-10 protocol is the one explicit guard against
unintended writes.
2. **Prefer typed commands over `weknora api`** for known endpoints.
Fallback to `weknora api` only when no typed command covers the
call.
3. **For chat, prefer `--no-stream --json`** in agent contexts.
Streaming tokens to stdout makes JSON parsing impossible.
4. **`link` writes to the user's working directory** — only run it
when the user invoked it, not as a side effect of unrelated
automation.
```go
tests := []struct{ name string; ...}{
{name: "descriptive case", ...},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) { /* arrange, act, assert */ })
}
```
(Additional safety guidance — e.g. "do not switch context unless the
user asked" — is documented in the affected command's own `--help`.)
## Code Style
---
- Add godoc to every exported function, type, and constant. Explain *why*, not *what* — the name already says *what*.
- Don't comment to restate the code. Delete comments that narrate the next line.
- Don't reference task numbers, commit SHAs, or version tags in inline comments — they belong in CHANGELOG or git log.
- Never paste em-dashes (—) into Go source; use ASCII `-` or rewrite. (Markdown docs may use em-dashes.)
- Don't add a helper for a single caller — inline.
## Auto-detection of agent environments
## Error Handling
`weknora` checks these environment variables (case-sensitive):
Typed error helpers in `internal/cmdutil/errors.go`:
| Env var | Detected agent name |
|---|---|
| `CLAUDECODE` | `claude-code` |
| `CURSOR_AGENT` | `cursor` |
- `cmdutil.NewError(code, msg)` — fresh typed error
- `cmdutil.WrapHTTP(err, format, args...)` — wrap an SDK error + classify from HTTP status (404 → `resource.not_found`, 401 → `auth.unauthenticated`, …). Use at every SDK call site.
- `cmdutil.Wrapf(code, err, format, args...)` — explicit wrap with a chosen code
- `cmdutil.NewFlagError(err)` — flag / argument problem → exit 2
- `cmdutil.SilentError` — exit 1 without printing (when output already emitted)
- `cmd.MarkFlagsMutuallyExclusive("a", "b")` — cobra-level mutex
When any is set, `weknora --help` appends the command's `agent_help`
annotation. **No behavior change** — this is help-text rendering only.
Errors print to STDERR via `cmdutil.PrintError(w, err)` as `code: msg\nhint: ...`. STDOUT stays bare JSON or empty on failure, so `--json | jq` pipelines never have to filter error shapes.
To suppress detection (e.g. running `weknora` interactively from inside
Claude Code without the agent footer): `WEKNORA_NO_AGENT_AUTODETECT=1`.
User-facing exit-code mapping lives in [README.md "Exit codes"](README.md#exit-codes). When adding a new `ErrorCode` constant, also append to `AllCodes()` so the acceptance contract picks it up.
Agent detection (`CLAUDECODE` / `CURSOR_AGENT` env) also tags the
User-Agent header for server-side telemetry — it never changes CLI
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 — bare-data JSON on stdout, errors on stderr.** Successful
commands emit the raw resource shape (`[]Item` for lists, `T` for views,
`{id, deleted: true}` for deletes) — no `ok` / `data` / `error`
wrapper. Errors are not data; they go to stderr in `code: message\nhint:
…` form, and the typed exit code carries the failure class for
programmatic branching. This separates "what the command produces" from
"how the run went", so `--json | jq` pipelines never have to filter
error shapes out of the success stream, and matches the contract of
gh / aws / stripe.
WeKnora-specific shape choices:
- `link` (project-binding) — `<cwd>/.weknora/project.yaml` walk-up
matches how RAG users scope work to a specific knowledge base. There
is no per-host config model competing with it; `context use` is the
separate mechanism for switching the credential set.
- `chat` / `search` are domain-specific verbs (LLM streaming +
retrieval) with no equivalent in pure-API CLIs.
- `context use` switches the active credential set; contexts bundle
host + tenant + credential, so a richer abstraction than a single
per-host token slot is required.
- `doctor` (4-status: ok / warn / fail / skip per check, plus a
summary object) is the agent-readable surface for RAG-deployment
misconfiguration (embeddings, storage, credentials) — failure modes
that the underlying SDK can't classify on its own. Agents short-
circuit on `summary.all_passed`; exit code is non-zero iff any
check is `fail`.
Verb canon: `list / view / create / edit / delete / upload / download
/ pin / unpin / use`. WeKnora-specific verbs for resource semantics
the common set lacks: `empty` (bulk-delete contents preserving the
container), `refresh` (token), `add` / `remove` (context CRUD),
`link` / `unlink` (project bind / unbind), `invoke` (run a custom
agent), `serve` (long-lived MCP transport).
**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"` with `context deadline exceeded` rather than a precise
typed code. A future release will introduce a `precondition.*`
namespace (server returns HTTP 412 with a typed remediation body before
opening the SSE / streaming response):
- `weknora chat` when no chat model is configured for the active tenant
- `weknora search chunks` when no retriever / vector store is configured
- `weknora doc upload` when no storage engine is selected for the KB
Workaround until then: if a chat / search / upload call times out
without producing a first-byte response, check the server's tenant
configuration (LLM / vector store / storage engine) before retrying. A
planned `weknora doctor --server-config` will probe these directly.
---
## Reporting issues
If the CLI's behavior contradicts this document, that is a bug. File at
https://github.com/Tencent/WeKnora/issues with:
- The exact command line
- `weknora --version` output
- The output (stdout + stderr) you got vs the output this document
promises
+43 -2
View File
@@ -7,11 +7,52 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
and the CLI follows [Semantic Versioning](https://semver.org/) independently
of the WeKnora server / frontend release cadence.
Earlier history (v0.0 through v0.2) is recorded in the project root
[CHANGELOG.md](../CHANGELOG.md) under the entries that introduced the CLI.
CLI history before v0.3 is recorded in the project root
[CHANGELOG.md](../CHANGELOG.md) under the release that introduced the CLI.
## [Unreleased]
### v0.4 — output contract hardening and mainstream alignment
#### Breaking changes
- Dropped the JSON envelope. `stdout` now emits bare typed data
(`{...}` or `[...]`); errors are written to `stderr` as `code: msg`
with an actionable `hint:` line. Pipelines using `--json | jq` no
longer have to filter out an envelope wrapper.
- Dropped `--dry-run`. Destructive writes still require `-y/--yes`;
non-TTY callers that omit `-y` exit with code 10 and
`input.confirmation_required` so an agent must surface the prompt
to a human before retrying.
- Dropped the per-command AI footer that rendered when `CLAUDECODE`
or `CURSOR_AGENT` was set. The same machine-readable guidance now
lives in the standard `--help` (visible to all callers) and in
`mcp serve`'s tool descriptions.
#### Added
- `weknora mcp serve` — curated read-only stdio MCP server exposing 9
tools (`kb_list`, `kb_view`, `doc_list`, `doc_view`, `doc_download`,
`search_chunks`, `chat`, `agent_list`, `agent_invoke`). Destructive
verbs are intentionally excluded.
- `weknora agent list` / `agent view` / `agent invoke` — manage and
call WeKnora's server-side Custom Agent resources.
- `weknora auth token` — print the active credential to `stdout` for
scripting (raw secret by default; `--json` emits `{token, mode, context}`).
- `weknora doc upload --from-url` — ingest a remote URL.
- `--json=fields,...` field projection and `--jq <expr>` filtering on
every command that emits JSON.
- `--limit` and `--all-pages` on list / search commands for bounded
output and explicit pagination control.
- Per-resource filter flags: `kb list --pinned`, `doc list --status`,
`session list --since`.
#### Changed
- Go toolchain bumped from 1.24 to 1.26.
- `auth login --with-token` validates the supplied key against
`/auth/me` before persisting, and prints an advisory if the keyring
is unavailable and credentials fall back to a 0600 file under
`$XDG_CONFIG_HOME/weknora/secrets/`.
- AGENTS.md rewritten as a developer guide (~170 lines, 6 H2 sections).
### v0.3 — extended management surface and a `session` subtree
#### Added
+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/`.
---
+7 -8
View File
@@ -17,23 +17,22 @@ import (
// cmdutil.NewError(codeXxx, ...) and cmdutil.Wrapf(codeXxx, ...) and verifies
// that codeXxx is registered in cmdutil.AllCodes().
//
// ClassifyHTTPError is dynamic — callers don't pass a literal CodeXxx
// ClassifyHTTPError is dynamic - callers don't pass a literal CodeXxx
// ident. Most SDK call sites go through cmdutil.WrapHTTP(err, ...) which
// the scanner skips entirely (it only inspects NewError / Wrapf selector
// names). A few sites still call ClassifyHTTPError directly to inspect
// or remap the code; those are call-expression args the scanner also
// skips. Either way, the codes those paths can yield are bridged via
// cmdutil.ClassifyHTTPErrorOutputs(), which enumerates every code the
// switch can return — added to the registered set so the AST scanner
// switch can return - added to the registered set so the AST scanner
// doesn't false-positive on them.
//
// Limitations (documented in spec §4.3):
// Limitations:
// - Only literal cmdutil.CodeXxx idents are detected; codes assigned to
// a local variable then passed are NOT scanned (rare pattern).
// - cmdutil.WrapHTTP(...) and cmdutil.ClassifyHTTPError(...) call
// expressions are skipped — the ClassifyHTTPErrorOutputs bridge
// expressions are skipped - the ClassifyHTTPErrorOutputs bridge
// covers their dynamic codes.
// - v0.x does not enforce a baseline diff (spec ADR-6b); v0.9 will.
func TestAllReferencedCodesAreRegistered(t *testing.T) {
registered := make(map[cmdutil.ErrorCode]struct{})
for _, c := range cmdutil.AllCodes() {
@@ -117,7 +116,7 @@ func collectErrorCodes(fset *token.FileSet, f *ast.File, out map[cmdutil.ErrorCo
}
// First arg should be cmdutil.CodeXxx (SelectorExpr ident).
// If it's a function call (e.g. cmdutil.ClassifyHTTPError(err)), skip
// — bridge handles those.
// - bridge handles those.
arg0Sel, ok := call.Args[0].(*ast.SelectorExpr)
if !ok {
return true
@@ -128,7 +127,7 @@ func collectErrorCodes(fset *token.FileSet, f *ast.File, out map[cmdutil.ErrorCo
}
code, ok := identToErrorCode(arg0Sel.Sel.Name)
if !ok {
// Unknown ident name — record as bogus so the test fails with
// Unknown ident name - record as bogus so the test fails with
// a clear "code referenced but not registered" message.
code = cmdutil.ErrorCode("UNKNOWN_REF:" + arg0Sel.Sel.Name)
}
@@ -140,7 +139,7 @@ func collectErrorCodes(fset *token.FileSet, f *ast.File, out map[cmdutil.ErrorCo
// identToErrorCode maps an ident name like "CodeAuthUnauthenticated" to its
// underlying ErrorCode value via a simple switch. Avoids reflect.
// Keep in sync with cmdutil.AllCodes() — adding a new const here is the same
// Keep in sync with cmdutil.AllCodes() - adding a new const here is the same
// bookkeeping as adding it to AllCodes().
func identToErrorCode(name string) (cmdutil.ErrorCode, bool) {
switch name {
+5 -6
View File
@@ -38,13 +38,12 @@ func TestMain(m *testing.M) {
var update = flag.Bool("update", false, "update golden files")
// newTestFactory builds a Factory whose Client returns mockClient.
// Caller must NOT use t.Parallel() — see iostreams.SetForTest contract.
// Caller must NOT use t.Parallel() - see iostreams.SetForTest contract.
//
// WEKNORA_BASE_URL is set when mockServer is non-nil. v0.0 buildClient does
// not currently honor this env var (it reads from config.Host); commands that
// need the mock URL must rely on the mockClient injection above. The env
// is set anyway as a forward-affordance for any direct net/http callers
// added in PR-7+ (e.g. doctor's PingBaseURL HEAD /health).
// WEKNORA_BASE_URL is set when mockServer is non-nil. buildClient does not
// currently honor this env var (it reads from config.Host); commands that
// need the mock URL rely on the mockClient injection above. The env is set
// anyway for any direct net/http callers (e.g. doctor's HEAD /health).
func newTestFactory(t *testing.T, mockServer *httptest.Server, mockClient *sdk.Client) *cmdutil.Factory {
t.Helper()
t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+16 -16
View File
@@ -12,7 +12,7 @@
// line on stderr.
//
// Cases intentionally omitted (with reason):
// - doctor.success — non-offline path emits
// - doctor.success - non-offline path emits
// unstable timing
// ("reachable in 2ms").
// Unit tests in cli/cmd/doctor
@@ -20,12 +20,12 @@
// doctor.success_offline is
// the deterministic sibling
// kept here.
// - auth_login.success — requires stdin pipe
// - auth_login.success - requires stdin pipe
// (--with-token) + keyring-
// aware Secrets store; the
// helper does not yet expose
// a stdin hook.
// - auth_login.error_auth_unauthenticated — same setup as above.
// - auth_login.error_auth_unauthenticated - same setup as above.
//
// All cases use leaf-positioned --json (e.g. `version --json`). --json is a
// per-leaf flag, not a global persistent flag.
@@ -45,13 +45,13 @@ import (
)
// wireCase declares one row in the contract matrix. Optional fields:
// server — mock /api/v1/* endpoints; nil means no network.
// preConfig — seed config.yaml under the per-test XDG_CONFIG_HOME
// server - mock /api/v1/* endpoints; nil means no network.
// preConfig - seed config.yaml under the per-test XDG_CONFIG_HOME
// (set by newTestFactory); use for cases like
// `context use` that read local state without an
// SDK round-trip.
// wantErr — non-zero exit expected.
// wantStderrSubstring — stderr must contain this substring (typically the
// wantErr - non-zero exit expected.
// wantStderrSubstring - stderr must contain this substring (typically the
// typed error code, e.g. "auth.unauthenticated").
// Only meaningful when wantErr=true.
type wireCase struct {
@@ -66,13 +66,13 @@ type wireCase struct {
// wireCases enumerates every contract scenario whose stdout is golden-pinned.
// Order is illustrative, not load-bearing.
var wireCases = []wireCase{
// 1. version.success — pure local; no client touched.
// 1. version.success - pure local; no client touched.
{
name: "version.success",
args: []string{"version", "--json"},
},
// 2. doctor.success_offline — only credential_storage runs; the three
// 2. doctor.success_offline - only credential_storage runs; the three
// network checks are skipped. Stable details + summary.
{
name: "doctor.success_offline",
@@ -80,7 +80,7 @@ var wireCases = []wireCase{
server: doctorReachable, // ensures buildServices succeeds even if probed
},
// 3. doctor.error_network — base_url returns 500 → ping fail → cascade
// 3. doctor.error_network - base_url returns 500 → ping fail → cascade
// skip on auth_credential + server_version. credential_storage still
// runs (independent). Contract: any check=fail bumps summary.failed
// and RunE returns SilentError → exit 1 with the data object
@@ -92,7 +92,7 @@ var wireCases = []wireCase{
wantErr: true,
},
// 4-7. kb list / get — SDK paths /api/v1/knowledge-bases[/<id>]
// 4-7. kb list / get - SDK paths /api/v1/knowledge-bases[/<id>]
{
name: "kb_list.success",
args: []string{"kb", "list", "--json"},
@@ -123,7 +123,7 @@ var wireCases = []wireCase{
wantStderrSubstring: "resource.not_found",
},
// 8. context use — pure local I/O against config.yaml.
// 8. context use - pure local I/O against config.yaml.
{
name: "context_use.success",
args: []string{"context", "use", "production", "--json"},
@@ -140,9 +140,9 @@ var wireCases = []wireCase{
}
},
},
// (context_use.error_local_context_not_found dropped — see file header.)
// (context_use.error_local_context_not_found dropped - see file header.)
// 9-10. auth status — SDK /api/v1/auth/me, plus config inspection.
// 9-10. auth status - SDK /api/v1/auth/me, plus config inspection.
{
name: "auth_status.success",
args: []string{"auth", "status", "--json"},
@@ -156,7 +156,7 @@ var wireCases = []wireCase{
wantStderrSubstring: "auth.unauthenticated",
},
// 11-13. search chunks — verb-noun shape (gh search parity), positional query, --kb required.
// 11-13. search chunks - verb-noun shape (gh search parity), positional query, --kb required.
// --kb accepts either kb_<id> (passed through) or a name (resolved via
// list); UUID-format detection happens client-side, mirroring gcloud
// --project's id-or-name auto-detection.
@@ -185,7 +185,7 @@ var wireCases = []wireCase{
// TestWireGolden is the matrix-runner. Cases are sequential (the
// iostreams singleton swap inside helpers.runCmd is package-global;
// t.Parallel is contractually forbidden — see helpers_test.go).
// t.Parallel is contractually forbidden - see helpers_test.go).
func TestWireGolden(t *testing.T) {
for _, tc := range wireCases {
t.Run(tc.name, func(t *testing.T) {
+3 -5
View File
@@ -2,11 +2,9 @@
//
// Package acceptance is the cli/ subtree top-level home for cross-cutting
// contract / integration tests. Lives outside cli/internal/ so a future
// reviewer immediately sees "this is the contract surface — change with care".
// reviewer immediately sees "this is the contract surface - change with care".
//
// Sub-packages:
// contract/ — envelope JSON shape golden + error.code registry consistency
// e2e/ — real WeKnora server blackbox tests (testscript-style)
//
// Layout convention follows spec §4.5.
// contract/ - envelope JSON shape golden + error.code registry consistency
// e2e/ - real WeKnora server blackbox tests (testscript-style)
package acceptance
+4 -4
View File
@@ -31,7 +31,7 @@ import (
// TestRAGFullLoop walks the demo MVP path: link a context, create a KB,
// upload a doc, wait for indexing, search it, then chat against it. Each
// step parses the CLI's bare JSON to extract IDs for the next step —
// step parses the CLI's bare JSON to extract IDs for the next step -
// validating both functional behavior and wire-contract stability.
func TestRAGFullLoop(t *testing.T) {
host := mustEnv(t, "WEKNORA_E2E_HOST")
@@ -45,7 +45,7 @@ func TestRAGFullLoop(t *testing.T) {
env := append(os.Environ(),
"XDG_CONFIG_HOME="+xdg,
"XDG_CACHE_HOME="+filepath.Join(xdg, "cache"),
// SDK debug off — explicit so the CI run isn't noisy.
// SDK debug off - explicit so the CI run isn't noisy.
"WEKNORA_SDK_DEBUG=",
)
@@ -102,7 +102,7 @@ func TestRAGFullLoop(t *testing.T) {
}
t.Logf("chat answer (%d chars), %d references", len(chat.Answer), len(chat.References))
if len(chat.References) == 0 {
// Soft warning — some servers may not surface references for every
// Soft warning - some servers may not surface references for every
// question, but the demo flow is supposed to.
t.Logf("warning: chat returned 0 references (server may have a different config)")
}
@@ -189,7 +189,7 @@ matching (lexical) to balance recall and precision.
// waitDocReady polls `doc list` until the uploaded document's status indicates
// indexing is complete. WeKnora server uses a few status values across versions
// ("ready", "completed", "ok") — accept any non-pending/non-processing/non-failed
// ("ready", "completed", "ok") - accept any non-pending/non-processing/non-failed
// state so we don't break on a server-side rename. Failed status fails the test
// fast.
func waitDocReady(t *testing.T, bin string, env []string, kbID, docID string, timeout time.Duration) {
+7 -17
View File
@@ -1,18 +1,13 @@
// Package agentcmd holds the `weknora agent` command tree:
// list / view / invoke. The directory is named `agent/` (matches cobra
// noun-verb convention) but the Go package is `agentcmd` to avoid
// shadowing cli/internal/agent (which owns SetAgentHelp + agent-aware
// help rendering for AI coding agents — a distinct concept from
// WeKnora's first-class custom-agent resources).
// colliding with cobra's *cobra.Command identifier.
//
// Disambiguation in cli/AGENTS.md: "agent" in this subtree refers to
// WeKnora's user-defined Custom Agents (server resource: GET/POST
// /agents/...). The CLI's `agent invoke` calls /agent-chat/:session_id
// which dispatches the agent's configured workflow (system prompt,
// allowed tools, KB scope, retrieval thresholds, etc.). This is
// orthogonal to AGENTS.md / SetAgentHelp, which exists so AI coding
// agents (Claude Code, Cursor) consuming the CLI can read structured
// hints from --help.
// "agent" in this subtree refers to WeKnora's user-defined Custom
// Agents (server resource: GET/POST /agents/...). The CLI's
// `agent invoke` calls /agent-chat/:session_id which dispatches the
// agent's configured workflow (system prompt, allowed tools, KB scope,
// retrieval thresholds).
package agentcmd
import (
@@ -29,12 +24,7 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
Short: "Manage and invoke custom agents",
Long: `Custom Agents bundle a system prompt, model, tool allow-list, and KB
scope into an addressable resource. List visible agents, view a single
agent's configuration, or invoke an agent against a query.
Distinct from the per-CLI ` + "`AGENTS.md`" + ` reference: that file documents the
contract for AI coding agents (Claude Code / Cursor) running ` + "`weknora`" + `
on a user's behalf. This subtree manages WeKnora's first-class custom-agent
resources stored on the server.`,
agent's configuration, or invoke an agent against a query.`,
Args: cobra.NoArgs,
Run: func(c *cobra.Command, _ []string) { _ = c.Help() },
}
+5 -7
View File
@@ -9,7 +9,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/format"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
@@ -18,7 +17,7 @@ import (
)
// agentInvokeFields enumerates fields surfaced for `--json` discovery on
// `agent invoke`. Matches invokeData below — the single-shot result
// `agent invoke`. Matches invokeData below - the single-shot result
// object with the agent's final answer plus the trace (references,
// tool events).
var agentInvokeFields = []string{
@@ -36,7 +35,7 @@ type InvokeOptions struct {
// InvokeService is the narrow SDK surface this command depends on.
//
// CreateSession is called when --session is omitted — sessions are
// CreateSession is called when --session is omitted - sessions are
// agent-agnostic at creation (verified against
// internal/handler/session/handler.go CreateSession, which only persists
// {title, description}). The agent ID is supplied per-request via
@@ -68,7 +67,7 @@ func NewCmdInvoke(f *cmdutil.Factory) *cobra.Command {
tools, KB scope, retrieval thresholds) over SSE. By default a fresh session
is auto-created; pass --session to continue an existing conversation. The
agent picks the model, retrieval params, and tool surface from its own
config — agent invoke is the thin shim that streams the result.
config - agent invoke is the thin shim that streams the result.
Modes:
TTY (default): live answer streaming + tool-trace footer
@@ -94,7 +93,6 @@ Modes:
cmd.Flags().StringVar(&opts.SessionID, "session", "", "Continue an existing chat session (skip auto-create)")
cmd.Flags().BoolVar(&opts.NoStream, "no-stream", false, "Buffer the full answer before printing (forces accumulate mode)")
cmdutil.AddJSONFlags(cmd, agentInvokeFields)
aiclient.SetAgentHelp(cmd, "Streams an agent's answer over SSE. Pass --json (or run non-TTY) to receive a single completed {answer, references, tool_events, …} JSON object instead of partial chunks. Errors: resource.not_found (unknown agent_id) / server.session_create_failed (auto-create) / local.sse_stream_aborted (mid-stream).")
return cmd
}
@@ -167,7 +165,7 @@ func runInvoke(ctx context.Context, opts *InvokeOptions, jopts *cmdutil.JSONOpti
return cmdutil.WrapHTTP(streamErr, "agent-chat stream")
}
// Server closed cleanly but never sent a Done event — treat as aborted
// Server closed cleanly but never sent a Done event - treat as aborted
// so agents don't silently emit a truncated answer as ok=true.
if !acc.Done() {
return cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")
@@ -204,7 +202,7 @@ func runInvoke(ctx context.Context, opts *InvokeOptions, jopts *cmdutil.JSONOpti
}
// renderToolTrace prints a compact tool-event footer in human mode.
// Skipped when the agent emitted no tool events — silent beats an empty
// Skipped when the agent emitted no tool events - silent beats an empty
// banner.
func renderToolTrace(w io.Writer, events []sse.AgentToolEvent) {
if len(events) == 0 {
+2 -4
View File
@@ -9,7 +9,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/text"
@@ -17,7 +16,7 @@ import (
)
// agentListFields enumerates the fields surfaced for `--json` discovery
// on `agent list`. Mirrors the json tags on sdk.Agent — nested Config is
// on `agent list`. Mirrors the json tags on sdk.Agent - nested Config is
// omitted because its sub-fields make filtering noisy (use `--jq` instead).
var agentListFields = []string{
"id", "name", "description", "avatar",
@@ -59,7 +58,6 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
}
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return (0 = no cap, 1..10000 = explicit)")
cmdutil.AddJSONFlags(cmd, agentListFields)
aiclient.SetAgentHelp(cmd, "Lists tenant-visible agents (built-in + custom) as a bare JSON array of Agent objects (empty `[]` when none). --limit caps the returned slice. Use `--json=id,name` to project fields, `--jq` for arbitrary reshape.")
return cmd
}
@@ -80,7 +78,7 @@ func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions,
if items == nil {
items = []sdk.Agent{} // ensure JSON [] not null
}
// Default sort: updated_at desc — most recently-edited agents surface
// Default sort: updated_at desc - most recently-edited agents surface
// first. Mirrors kb list / doc list behavior.
sort.Slice(items, func(i, j int) bool {
return items[i].UpdatedAt.After(items[j].UpdatedAt)
+2 -4
View File
@@ -7,7 +7,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
@@ -15,7 +14,7 @@ import (
// agentViewFields enumerates fields surfaced for `--json` discovery on
// `agent view`. Filter applies to the bare Agent object. Config sub-fields
// are intentionally omitted — too granular for naked projection; use
// are intentionally omitted - too granular for naked projection; use
// `--jq '.config'` to reach them.
var agentViewFields = []string{
"id", "name", "description", "avatar",
@@ -36,7 +35,7 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
Long: `Renders the agent's metadata (id / name / description / created-by /
timestamps) plus a compact config summary (mode, model, allowed tools, KB
scope). Pass --json for the full Agent object including the nested config
struct — or --jq '.config' to extract just the config.`,
struct - or --jq '.config' to extract just the config.`,
Example: ` weknora agent view ag_abc
weknora agent view ag_abc --json | jq '.config.allowed_tools'`,
Args: cobra.ExactArgs(1),
@@ -53,7 +52,6 @@ struct — or --jq '.config' to extract just the config.`,
},
}
cmdutil.AddJSONFlags(cmd, agentViewFields)
aiclient.SetAgentHelp(cmd, "Fetches an agent by ID. Returns the full sdk.Agent (with nested config) as a bare JSON object. Errors: resource.not_found when the agent ID does not exist or is not visible to the active tenant.")
return cmd
}
+2 -4
View File
@@ -18,14 +18,13 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/format"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
)
// apiFields is intentionally a marker — api wraps arbitrary HTTP responses
// apiFields is intentionally a marker - api wraps arbitrary HTTP responses
// whose schema the CLI doesn't know, so the `--json=id,name` field-filter
// is a no-op here. The marker shows up in --help so users can tell.
var apiFields = []string{"<response-shape-varies>"}
@@ -74,7 +73,7 @@ Examples:
}
method := resolveMethod(opts)
// Escape-hatch DELETE through `weknora api` is just as destructive
// as `weknora kb delete` — exit-10 protocol must apply (AGENTS.md).
// as `weknora kb delete` - exit-10 protocol must apply (cli/README.md).
if method == http.MethodDelete {
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, jopts.Enabled(), "endpoint", args[0]); err != nil {
return err
@@ -92,7 +91,6 @@ Examples:
cmd.Flags().StringVar(&opts.Input, "input", "", "Read request body from file (use `-` for stdin)")
cmdutil.AddJSONFlags(cmd, apiFields)
cmd.MarkFlagsMutuallyExclusive("data", "input")
aiclient.SetAgentHelp(cmd, "Raw HTTP passthrough. Auth / tenant / request-id headers injected from the active context. --json wraps as {status, headers, body}; --json field filtering is ignored here (response shape unknown to CLI) — use --jq for reshape. DELETE triggers exit-10 confirm. Non-2xx maps to typed errors via ClassifyHTTPStatus (4xx → input.invalid_argument / auth.* / resource.not_found; 5xx → server.error). --data and --input are mutually exclusive.")
return cmd
}
+2 -2
View File
@@ -201,7 +201,7 @@ func TestAPI_PathWithoutSlash(t *testing.T) {
// withRootHarness wraps `weknora api ...` under a synthetic root cmd that
// registers the global `-y/--yes` persistent flag (mirrors addGlobalFlags in
// cmd/root.go). Required because api's NewCmd doesn't register --yes itself
// — it inherits from root in production.
// - it inherits from root in production.
func withRootHarness(api *cobra.Command, args ...string) *cobra.Command {
root := &cobra.Command{Use: "weknora"}
root.PersistentFlags().BoolP("yes", "y", false, "")
@@ -260,7 +260,7 @@ func TestAPI_DELETE_WithYes_Proceeds(t *testing.T) {
t.Fatalf("execute: %v", err)
}
if !called {
t.Error("DELETE handler not called — confirmation may have blocked")
t.Error("DELETE handler not called - confirmation may have blocked")
}
}
+1 -1
View File
@@ -21,7 +21,7 @@ const (
)
// modeFromRefs maps the per-context TokenRef / APIKeyRef presence to a
// canonical credential-mode token. Bearer wins when both are present —
// canonical credential-mode token. Bearer wins when both are present -
// matches the precedence in cmdutil.buildClient.
func modeFromRefs(apiKeyRef, tokenRef string) string {
switch {
+2 -3
View File
@@ -7,7 +7,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/format"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
@@ -31,11 +30,12 @@ type listEntry struct {
// NewCmdList builds `weknora auth list`. Per-host enumeration: render one
// row per registered context, marking the active one. Reads only
// ~/.config/weknora/config.yaml — no network, no keyring touch.
// ~/.config/weknora/config.yaml - no network, no keyring touch.
func NewCmdList(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: "list",
Short: "List configured authentication contexts",
Long: `Show every configured context (name, host, user, mode, current). Read-only; no network or keyring access.`,
Args: cobra.NoArgs,
RunE: func(c *cobra.Command, _ []string) error {
jopts, err := cmdutil.CheckJSONFlags(c)
@@ -46,7 +46,6 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
},
}
cmdutil.AddJSONFlags(cmd, authListFields)
aiclient.SetAgentHelp(cmd, "Lists configured auth contexts (name/host/user/mode/current). Read-only, no network, no keyring access. Use to confirm context names before --context or `auth login --name`.")
return cmd
}
+2 -2
View File
@@ -37,7 +37,7 @@ func TestList_HumanRender(t *testing.T) {
// Mode column.
assert.Contains(t, got, ModeBearer)
assert.Contains(t, got, ModeAPIKey)
// Sorted alphabetically — prod after staging? No: "prod" < "staging".
// Sorted alphabetically - prod after staging? No: "prod" < "staging".
assert.Less(t, strings.Index(got, "prod"), strings.Index(got, "staging"),
"contexts should render sorted by name")
}
@@ -72,7 +72,7 @@ func TestList_JSON_BareArray(t *testing.T) {
}
func TestModeFromRefs(t *testing.T) {
// Hand-edited config with neither ref set — surface "unknown" rather
// Hand-edited config with neither ref set - surface "unknown" rather
// than pretending the context is a valid login.
assert.Equal(t, ModeUnknown, modeFromRefs("", ""))
assert.Equal(t, ModeBearer, modeFromRefs("", "tok"))
+4 -6
View File
@@ -8,7 +8,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/config"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
@@ -17,7 +16,7 @@ import (
)
// authLoginFields enumerates the fields surfaced for `--json` discovery on
// `auth login`. The post-login summary has no token values — they stay in the
// `auth login`. The post-login summary has no token values - they stay in the
// keyring; agents who need to verify the credential should re-run
// `auth status`.
var authLoginFields = []string{
@@ -97,7 +96,6 @@ the current_context in ~/.config/weknora/config.yaml.`,
cmd.Flags().BoolVar(&opts.WithToken, "with-token", false, "Read an API key from stdin instead of prompting for password")
cmdutil.AddJSONFlags(cmd, authLoginFields)
_ = cmd.MarkFlagRequired("host")
aiclient.SetAgentHelp(cmd, "Authenticates and stores credentials. --with-token reads an API key from stdin (no password prompt, agent-safe). Otherwise email/password prompts fire — non-TTY callers must pipe `--with-token` or pre-set --name. Errors: auth.bad_credential on wrong password; input.invalid_argument on bad --host; input.missing_flag when --with-token has empty stdin.")
return cmd
}
@@ -126,7 +124,7 @@ func runLogin(ctx context.Context, opts *LoginOptions, jopts *cmdutil.JSONOption
opts.APIKey = key
// Validate against the server before persisting so a typo'd /
// expired / wrong-host key fails fast (gh CLI parity). The probe
// is /auth/me — read-only, side-effect-free.
// is /auth/me - read-only, side-effect-free.
user, err := defaultAPIKeyValidator(ctx, opts.Host, key)
if err != nil {
return cmdutil.Wrapf(cmdutil.CodeAuthBadCredential, err, "validate API key")
@@ -268,7 +266,7 @@ func validateHost(host string) error {
// warnOnFileFallback prints a one-shot stderr advisory when the secrets
// store fell back to the plaintext 0600 file backend (keychain unavailable
// — typical on headless CI, WSL without DBus, agent containers). Helps
// - typical on headless CI, WSL without DBus, agent containers). Helps
// users notice that credentials are NOT in the OS keychain before they're
// surprised by it later. doctor's credential_storage check carries the
// same info but agents that bypass doctor would otherwise miss it.
@@ -276,7 +274,7 @@ func warnOnFileFallback(store secrets.Store) {
if _, isFile := store.(*secrets.FileStore); !isFile {
return
}
fmt.Fprintln(iostreams.IO.Err, "warning: OS keychain unavailable — credentials will be saved to a 0600 file under $XDG_CONFIG_HOME/weknora/secrets/.")
fmt.Fprintln(iostreams.IO.Err, "warning: OS keychain unavailable - credentials will be saved to a 0600 file under $XDG_CONFIG_HOME/weknora/secrets/.")
fmt.Fprintln(iostreams.IO.Err, " install / unlock the keyring (or use `weknora doctor` to inspect) for OS-backed storage.")
}
+1 -1
View File
@@ -124,7 +124,7 @@ func stubAPIKeyValidator(fn apiKeyValidator) func() {
func TestRunLogin_WithToken_Empty(t *testing.T) {
iostreams.SetForTest(t)
f, _ := newTestFactoryWithConfig(t, prompt.AgentPrompter{})
// Validator must NOT be called when stdin is empty — verify by setting
// Validator must NOT be called when stdin is empty - verify by setting
// a panic-on-call sentinel.
restore := stubAPIKeyValidator(func(_ context.Context, _, _ string) (*sdk.AuthUser, error) {
t.Fatal("validator should not be called on empty stdin")
+4 -6
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/config"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
@@ -30,7 +29,7 @@ type logoutResult struct {
// NewCmdLogout builds `weknora auth logout`. Clears stored credentials
// (keyring + file fallback) and removes the context entry from config.yaml.
// No server-side revocation — local-only credential clear.
// No server-side revocation - local-only credential clear.
func NewCmdLogout(f *cmdutil.Factory) *cobra.Command {
opts := &LogoutOptions{}
cmd := &cobra.Command{
@@ -39,7 +38,7 @@ func NewCmdLogout(f *cmdutil.Factory) *cobra.Command {
Long: `Clear keyring + file-fallback secrets for one context (or all of
them with --all) and drop the context entry from ~/.config/weknora/config.yaml.
Note: this does NOT revoke the credential server-side — for API keys, you
Note: this does NOT revoke the credential server-side - for API keys, you
must rotate them in the server UI; for JWT, the token will continue to be
accepted until it expires.`,
Example: ` weknora auth logout # current context
@@ -58,7 +57,6 @@ accepted until it expires.`,
cmd.Flags().BoolVar(&opts.All, "all", false, "Log out of every configured context")
cmdutil.AddJSONFlags(cmd, authLogoutFields)
cmd.MarkFlagsMutuallyExclusive("name", "all")
aiclient.SetAgentHelp(cmd, "Clears local credentials only; the server-side token / api-key continues to be valid until expired or rotated. Returns data.removed: [...names]. Errors: auth.unauthenticated when no contexts configured.")
return cmd
}
@@ -85,7 +83,7 @@ func runLogout(opts *LogoutOptions, jopts *cmdutil.JSONOptions, f *cmdutil.Facto
delete(cfg.Contexts, name)
}
// If we removed the active context, pick a remaining one (deterministic by
// map order would be flaky — leave CurrentContext empty so the next
// map order would be flaky - leave CurrentContext empty so the next
// invocation surfaces a clear "no current context" error rather than
// silently switching).
if _, stillExists := cfg.Contexts[cfg.CurrentContext]; !stillExists {
@@ -128,7 +126,7 @@ func pickLogoutTargets(opts *LogoutOptions, cfg *config.Config) ([]string, error
// clearContextSecrets best-effort deletes every secret slot the context
// references. Errors are swallowed because a missing secret is a no-op
// (tested in keyring_test.go) — we don't want a stale ref to block logout.
// (tested in keyring_test.go) - we don't want a stale ref to block logout.
func clearContextSecrets(store secrets.Store, c config.Context, name string) {
if c.TokenRef != "" {
_ = store.Delete(name, "access")
+1 -1
View File
@@ -14,7 +14,7 @@ import (
)
// newLogoutFactory builds a Factory whose Config closure mutates the supplied
// cfg in place — runLogout writes back via config.Save which touches disk, so
// cfg in place - runLogout writes back via config.Save which touches disk, so
// tests use t.Setenv("XDG_CONFIG_HOME", t.TempDir()) at the call site to
// isolate the on-disk file.
func newLogoutFactory(t *testing.T, cfg *config.Config, store secrets.Store) *cmdutil.Factory {
+8 -10
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
@@ -17,11 +16,11 @@ type RefreshOptions struct {
}
// authRefreshFields enumerates the fields surfaced for `--json` discovery
// on `auth refresh`. Token values are intentionally omitted — see refreshResult.
// on `auth refresh`. Token values are intentionally omitted - see refreshResult.
var authRefreshFields = []string{"context"}
// refreshResult is the typed payload emitted under data on success. Token
// values are intentionally NOT included — emitting them would leak secrets
// values are intentionally NOT included - emitting them would leak secrets
// into stdout / agent transcripts. Agents needing to verify the new token
// can re-run `weknora auth status` (live API check).
type refreshResult struct {
@@ -29,10 +28,10 @@ type refreshResult struct {
}
// NewCmdRefresh builds `weknora auth refresh`. Renews the JWT access
// token by spending the stored refresh_token via POST /auth/refresh —
// token by spending the stored refresh_token via POST /auth/refresh -
// the standard OAuth refresh-token grant.
//
// API-key contexts are rejected — they have no refresh semantic;
// API-key contexts are rejected - they have no refresh semantic;
// rotate the key via the server UI instead.
func NewCmdRefresh(f *cmdutil.Factory) *cobra.Command {
opts := &RefreshOptions{}
@@ -43,7 +42,7 @@ func NewCmdRefresh(f *cmdutil.Factory) *cobra.Command {
exchanges it for a new access + refresh token pair via POST /api/v1/auth/refresh.
Both new tokens replace the existing entries in the OS keyring.
API-key contexts are rejected with input.invalid_argument — they have no
API-key contexts are rejected with input.invalid_argument - they have no
refresh semantic. Rotate the key in the server UI instead.`,
Example: ` weknora auth refresh # refresh the current context
weknora auth refresh --name staging # refresh a specific context`,
@@ -58,12 +57,11 @@ refresh semantic. Rotate the key in the server UI instead.`,
}
cmd.Flags().StringVar(&opts.Name, "name", "", "Context to refresh (defaults to the current context)")
cmdutil.AddJSONFlags(cmd, authRefreshFields)
aiclient.SetAgentHelp(cmd, "Renews the access token using the stored refresh token. Errors with auth.token_expired when refresh itself is rejected — surface the hint to re-run auth login.")
return cmd
}
// defaultRefresher constructs a fresh, unauthenticated SDK client targeting
// host — the /auth/refresh endpoint reads the refresh token from the body,
// host - the /auth/refresh endpoint reads the refresh token from the body,
// so no bearer / api-key header is needed.
func defaultRefresher(host string) cmdutil.Refresher {
return sdk.NewClient(host)
@@ -92,9 +90,9 @@ func runRefresh(ctx context.Context, opts *RefreshOptions, jopts *cmdutil.JSONOp
fmt.Sprintf("context %q has no host", name))
}
if c.RefreshRef == "" {
hint := "api-key contexts can't be refreshed — rotate the key in the server UI and run `weknora auth login --with-token`"
hint := "api-key contexts can't be refreshed - rotate the key in the server UI and run `weknora auth login --with-token`"
if c.APIKeyRef == "" {
hint = "no refresh token stored — run `weknora auth login` to authenticate"
hint = "no refresh token stored - run `weknora auth login` to authenticate"
}
return &cmdutil.Error{
Code: cmdutil.CodeInputInvalidArgument,
+2 -2
View File
@@ -140,7 +140,7 @@ func TestRefresh_NoRefreshTokenStored(t *testing.T) {
"prod": {Host: "https://kb", TokenRef: "mem://prod/access", RefreshRef: "mem://prod/refresh"},
},
}
// MemStore is empty — RefreshRef points to a slot that doesn't exist.
// MemStore is empty - RefreshRef points to a slot that doesn't exist.
f := newRefreshFactory(t, cfg, secrets.NewMemStore())
err := runRefresh(context.Background(), &RefreshOptions{}, nil, f, stubSvc(&fakeRefreshService{}))
require.Error(t, err)
@@ -168,7 +168,7 @@ func TestRefresh_ServerRefused(t *testing.T) {
assert.Contains(t, typed.Hint, "auth login")
// stored access must NOT have been overwritten with empty
if v, _ := store.Get("prod", "access"); v == "" {
// Was never set in this test, that's fine — main thing is no panic.
// Was never set in this test, that's fine - main thing is no panic.
_ = v
}
}
+8 -3
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
@@ -37,7 +36,14 @@ func NewCmdStatus(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: "status",
Short: "Show the active context, principal, and token state",
Args: cobra.NoArgs,
Long: `Live-check the active credential by calling /auth/me. Reports the user
and tenant the server resolves the credential to.
Exits with auth.unauthenticated when the token is invalid or missing - run
` + "`weknora auth login`" + ` (or ` + "`auth refresh`" + ` for JWT contexts) to recover.
For JWT contexts the SDK transparently refreshes on 401, so this command
usually only surfaces a hard auth failure.`,
Args: cobra.NoArgs,
RunE: func(c *cobra.Command, args []string) error {
jopts, err := cmdutil.CheckJSONFlags(c)
if err != nil {
@@ -51,7 +57,6 @@ func NewCmdStatus(f *cmdutil.Factory) *cobra.Command {
},
}
cmdutil.AddJSONFlags(cmd, authStatusFields)
aiclient.SetAgentHelp(cmd, "Live-checks the active credential by calling /auth/me. Returns {context, user_id, email, tenant_id, tenant_name}. Errors: auth.unauthenticated when token is invalid or missing (run `auth login` / `auth refresh`).")
return cmd
}
+1 -1
View File
@@ -90,7 +90,7 @@ func TestRunStatus_SDKError_Transport(t *testing.T) {
f := &cmdutil.Factory{Config: func() (*config.Config, error) { return config.Load() }}
err := runStatus(context.Background(), nil, f, &fakeStatusService{err: assert.AnError})
require.Error(t, err)
// Non-HTTP errors (DNS / TCP) are transport problems, not auth problems —
// Non-HTTP errors (DNS / TCP) are transport problems, not auth problems -
// classify network.error so retry logic / exit code 7 / IsTransient apply.
assert.True(t, cmdutil.IsTransient(err), "expected transient/network classification, got %v", err)
}
+5 -7
View File
@@ -5,7 +5,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
)
@@ -27,7 +26,7 @@ type tokenResult struct {
// curl -H "Authorization: Bearer $WEKNORA_TOKEN" ... # JWT mode
// curl -H "X-API-Key: $WEKNORA_TOKEN" ... # api-key mode
//
// The user is responsible for constructing the appropriate header —
// The user is responsible for constructing the appropriate header -
// `auth list` shows which mode each context uses.
//
// Default output: raw token on stdout, no trailing newline (clean $(...)).
@@ -60,7 +59,6 @@ to see which mode each context uses, and construct the matching HTTP header:
},
}
cmdutil.AddJSONFlags(cmd, authTokenFields)
aiclient.SetAgentHelp(cmd, "Prints the active context's credential to stdout for scripting. Default: raw secret, no trailing newline. With --json: bare {token, mode, context} object. Errors: auth.unauthenticated when no active context or no stored credential (run `auth login`); local.keychain_denied when the keyring rejects the read.")
return cmd
}
@@ -89,7 +87,7 @@ func runToken(f *cmdutil.Factory, jopts *cmdutil.JSONOptions) error {
}
// Resolve the stored credential. Prefer bearer (JWT) when both refs
// are present — JWT is the more capable mode and what `buildClient`
// are present - JWT is the more capable mode and what `buildClient`
// uses for the Authorization header (see factory.go buildClient).
var token, mode string
switch {
@@ -119,18 +117,18 @@ func runToken(f *cmdutil.Factory, jopts *cmdutil.JSONOptions) error {
return jopts.Emit(iostreams.IO.Out, tokenResult{Token: token, Mode: mode, Context: ctxName})
}
// No trailing newline — clean $(weknora auth token) substitution.
// No trailing newline - clean $(weknora auth token) substitution.
fmt.Fprint(iostreams.IO.Out, token)
// Defensive hint to stderr when stdout is an interactive terminal:
// the user likely didn't mean to display the secret on screen.
// stderr-only so scripts (always non-TTY) are unaffected. Mode-specific
// because api-key tokens are long-lived and rotation is the only
// recourse on leak — bearer tokens self-expire via refresh.
// recourse on leak - bearer tokens self-expire via refresh.
if iostreams.IO.IsStdoutTTY() {
fmt.Fprintln(iostreams.IO.Err)
fmt.Fprintln(iostreams.IO.Err, "hint: pipe to $(weknora auth token) to capture; this terminal scrollback now contains the secret")
if mode == ModeAPIKey {
fmt.Fprintln(iostreams.IO.Err, "note: api-key credentials are long-lived — rotate via your auth provider if exposed (no `auth refresh` path)")
fmt.Fprintln(iostreams.IO.Err, "note: api-key credentials are long-lived - rotate via your auth provider if exposed (no `auth refresh` path)")
}
}
return nil
+3 -3
View File
@@ -165,7 +165,7 @@ func TestAuthToken_NoStoredCredential(t *testing.T) {
},
}
store := secrets.NewMemStore()
// no Set — keyring is empty
// no Set - keyring is empty
iostreams.SetForTest(t)
err := runToken(tokenTestFactory(t, cfg, store), nil)
if err == nil {
@@ -200,7 +200,7 @@ func TestAuthToken_ContextWithNoCredentialRefs(t *testing.T) {
// interactive terminal, it ALSO writes a stderr advisory ("you just put the
// secret in your scrollback") + a mode-specific rotation note for api-key
// credentials. The stdout half must stay clean under all modes so $(...)
// substitution is unaffected — tests assert both axes.
// substitution is unaffected - tests assert both axes.
func makeBearerCfg() (*config.Config, *secrets.MemStore) {
cfg := &config.Config{
@@ -278,7 +278,7 @@ func TestAuthToken_TTY_APIKeyMode_IncludesRotationNote(t *testing.T) {
func TestAuthToken_TTY_JSONMode_NoStderrHint(t *testing.T) {
// --json output mode targets script/agent consumers even when stdout
// happens to be a TTY (e.g. an IDE running the CLI on the user's
// behalf). Hint would pollute their parsing — suppress.
// behalf). Hint would pollute their parsing - suppress.
cfg, store := makeBearerCfg()
_, errBuf := iostreams.SetForTestWithTTY(t)
if err := runToken(tokenTestFactory(t, cfg, store), &cmdutil.JSONOptions{}); err != nil {
+6 -8
View File
@@ -1,4 +1,4 @@
// Package chat implements `weknora chat <text>` — the streaming RAG answer
// Package chat implements `weknora chat <text>` - the streaming RAG answer
// entry point.
//
// Two output modes share a single SDK call:
@@ -27,7 +27,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/format"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
@@ -116,7 +115,6 @@ Modes:
cmd.Flags().StringVar(&opts.SessionID, "session", "", "Continue an existing chat session (skip auto-create)")
cmd.Flags().BoolVar(&opts.NoStream, "no-stream", false, "Buffer the full answer before printing (forces accumulate mode)")
cmdutil.AddJSONFlags(cmd, chatFields)
aiclient.SetAgentHelp(cmd, "Streams an LLM answer over SSE. Agent / non-TTY callers should pass --json so the full {answer, references, session_id, assistant_message_id} object is emitted once at completion (no partial chunks). Pass --session to thread follow-ups. Errors: server.session_create_failed when auto-create fails; local.sse_stream_aborted on mid-stream disconnect.")
return cmd
}
@@ -161,7 +159,7 @@ func runChat(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, svc
streamMode := iostreams.IO.IsStdoutTTY() && !opts.NoStream && !jsonOut
// Surface the auto-created session ID up-front so a user who hits ^C
// mid-stream still has the pointer to resume — no need to scroll back
// mid-stream still has the pointer to resume - no need to scroll back
// past tokens. Skipped in JSON mode (it ends up in the data object) and
// when the caller already supplied --session.
if autoCreated && !jsonOut {
@@ -193,7 +191,7 @@ func runChat(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, svc
// Re-surface the auto-created session id on failure so a user who
// missed the start-of-stream notice (it scrolls past mid-stream
// tokens, especially on ^C) can still recover with --session.
// Skipped in JSON mode — the data object carries it in .session_id.
// Skipped in JSON mode - the data object carries it in .session_id.
if autoCreated && !jsonOut {
fmt.Fprintf(iostreams.IO.Err, "session: %s (resume with --session %s)\n", sessionID, sessionID)
}
@@ -212,11 +210,11 @@ func runChat(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, svc
return cmdutil.WrapHTTP(streamErr, "knowledge qa stream")
}
// SDK returned nil but we never saw a Done event — server closed the
// SDK returned nil but we never saw a Done event - server closed the
// connection cleanly mid-stream. Treat as aborted so the user sees the
// truncation rather than a silent partial answer. Includes the empty-body
// case (Done frame never arrived AND no content): better to surface the
// abort than emit ok=true with answer="" — agents can't distinguish the
// abort than emit ok=true with answer="" - agents can't distinguish the
// model genuinely had nothing to say from the stream getting cut.
if !acc.Done() {
return cmdutil.NewError(cmdutil.CodeSSEStreamAborted, "stream ended without a terminal event")
@@ -227,7 +225,7 @@ func runChat(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, svc
if jsonOut {
// Prefer the SDK-echoed session id (acc.SessionID) but fall back to
// our local sessionID — agents must always see a usable pointer.
// our local sessionID - agents must always see a usable pointer.
sid := acc.SessionID
if sid == "" {
sid = sessionID
+1 -3
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/config"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
@@ -32,7 +31,7 @@ type addResult struct {
}
// NewCmdAdd builds `weknora context add`. Registers a *credentialless*
// connection target — host + optional user only. Credentials for the new
// connection target - host + optional user only. Credentials for the new
// context are attached separately with `weknora auth login --name <n>`,
// separating "where" the CLI talks to (the host) and "how" it authenticates
// (the credential). If you want one command for both, run
@@ -64,7 +63,6 @@ adds leave the current context untouched.`,
cmd.Flags().StringVar(&opts.User, "user", "", "Account email shown in 'context list' (optional, cosmetic only)")
cmdutil.AddJSONFlags(cmd, contextAddFields)
_ = cmd.MarkFlagRequired("host")
aiclient.SetAgentHelp(cmd, "Adds a context. First context added auto-becomes current. Errors with resource.already_exists if name collides; input.invalid_argument if --host is not an absolute http(s) URL.")
return cmd
}
+1 -1
View File
@@ -3,7 +3,7 @@
// consistent with the rest of this CLI.
//
// Package name `contextcmd` (not `context`) to avoid shadowing stdlib context.
// The cobra Use: string is "context" — this is what users type.
// The cobra Use: string is "context" - this is what users type.
package contextcmd
import (
+2 -4
View File
@@ -7,7 +7,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/config"
"github.com/Tencent/WeKnora/cli/internal/format"
@@ -30,7 +29,7 @@ type listEntry struct {
}
// NewCmdList builds `weknora context list`. Per-host enumeration with an
// active marker. Reads only config.yaml — no network, no keyring touch.
// active marker. Reads only config.yaml - no network, no keyring touch.
func NewCmdList(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: "list",
@@ -39,7 +38,7 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
active context (used by subsequent commands when --context is unset) is
marked with a leading "*". No network requests are issued.
The credential mode (api-key vs password) is intentionally not shown here —
The credential mode (api-key vs password) is intentionally not shown here -
run "weknora auth list" for that. "context list" is the catalog of *where*
the CLI can talk to; "auth list" is the catalog of *how*.`,
Args: cobra.NoArgs,
@@ -52,7 +51,6 @@ the CLI can talk to; "auth list" is the catalog of *how*.`,
},
}
cmdutil.AddJSONFlags(cmd, contextListFields)
aiclient.SetAgentHelp(cmd, "Lists CLI contexts (name/host/user/current). Read-only, no network. Use this before context use to verify the target name exists.")
return cmd
}
+5 -7
View File
@@ -5,7 +5,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/config"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
@@ -43,11 +42,11 @@ func NewCmdRemove(f *cmdutil.Factory) *cobra.Command {
Long: `Deletes the named context from config.yaml and best-effort clears any
keyring references it owned (matches ` + "`weknora auth logout`" + `).
Removing the current context also clears CurrentContext — subsequent commands
Removing the current context also clears CurrentContext - subsequent commands
will error until you select another with ` + "`weknora context use <name>`" + ` or pick
one up via the global ` + "`--context`" + ` flag. Because that change is observable in
every later command, removing the current context requires explicit -y/--yes
in scripted / --json invocations (exit code 10; see cli/AGENTS.md).`,
in scripted / --json invocations (exit code 10; see cli/README.md).`,
Example: ` weknora context remove staging # remove non-current → no prompt
weknora context remove production -y # remove current → confirm`,
Args: cobra.ExactArgs(1),
@@ -65,7 +64,6 @@ in scripted / --json invocations (exit code 10; see cli/AGENTS.md).`,
},
}
cmdutil.AddJSONFlags(cmd, contextRemoveFields)
aiclient.SetAgentHelp(cmd, "Removes a context entry. Removing the current context requires -y in non-TTY/--json (exit-10). Always best-effort clears keyring refs.")
return cmd
}
@@ -81,7 +79,7 @@ func runRemove(opts *RemoveOptions, jopts *cmdutil.JSONOptions, name string, sto
wasCurrent := name == cfg.CurrentContext
jsonOut := jopts.Enabled()
// Confirmation only fires for removing the current context — non-current
// Confirmation only fires for removing the current context - non-current
// remove uses the same low-friction policy as `auth logout`.
if wasCurrent {
if err := cmdutil.ConfirmDestructive(p, opts.Yes, jsonOut, "current context", name); err != nil {
@@ -105,7 +103,7 @@ func runRemove(opts *RemoveOptions, jopts *cmdutil.JSONOptions, name string, sto
return jopts.Emit(iostreams.IO.Out, result)
}
if wasCurrent {
fmt.Fprintf(iostreams.IO.Out, "✓ Removed context %s (current context cleared — run `weknora context use <name>` to pick another)\n", name)
fmt.Fprintf(iostreams.IO.Out, "✓ Removed context %s (current context cleared - run `weknora context use <name>` to pick another)\n", name)
} else {
fmt.Fprintf(iostreams.IO.Out, "✓ Removed context %s\n", name)
}
@@ -114,7 +112,7 @@ func runRemove(opts *RemoveOptions, jopts *cmdutil.JSONOptions, name string, sto
// clearContextSecrets mirrors auth/logout.go: best-effort delete every secret
// slot the context references. Errors are swallowed so a missing keyring
// entry doesn't block remove (logout has had the same policy since v0.2).
// entry doesn't block remove (same policy as `auth logout`).
func clearContextSecrets(store secrets.Store, c config.Context, name string) {
if c.TokenRef != "" {
_ = store.Delete(name, "access")
+1 -3
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/config"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
@@ -43,7 +42,6 @@ the global --context flag instead, which writes nothing to disk.`,
},
}
cmdutil.AddJSONFlags(cmd, contextUseFields)
aiclient.SetAgentHelp(cmd, "Switches default CLI context. With --json: returns {current_context, previous_context}. Errors with local.context_not_found and a did-you-mean hint when name unknown.")
return cmd
}
@@ -82,7 +80,7 @@ func notFoundError(name string, cfg *config.Config) error {
return &cmdutil.Error{
Code: cmdutil.CodeLocalContextNotFound,
Message: fmt.Sprintf("context not found: %s", name),
Hint: "no contexts registered — run `weknora auth login` first",
Hint: "no contexts registered - run `weknora auth login` first",
}
}
keys := contextKeys(cfg.Contexts)
+2 -2
View File
@@ -118,12 +118,12 @@ func TestUse_CaseSensitive(t *testing.T) {
}}
_ = config.Save(cfg)
err := runUse("production", nil) // lowercase — must NOT match "Production"
err := runUse("production", nil) // lowercase - must NOT match "Production"
if err == nil {
t.Fatal("expected case-sensitive miss")
}
cm := err.(*cmdutil.Error)
// did-you-mean kicks in (distance 1 — "P"→"p")
// did-you-mean kicks in (distance 1 - "P"→"p")
if !strings.Contains(cm.Hint, "Production") {
t.Errorf("hint should suggest 'Production' (case-different), got %q", cm.Hint)
}
-2
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/prompt"
@@ -64,7 +63,6 @@ without the user's explicit go-ahead.`,
},
}
cmdutil.AddJSONFlags(cmd, docDeleteFields)
aiclient.SetAgentHelp(cmd, "Destructively deletes one document by id. ALWAYS pass -y/--yes in agent mode (no TTY ⇒ confirm prompt fails). Returns data: {id, deleted:true}.")
return cmd
}
+1 -1
View File
@@ -115,7 +115,7 @@ func TestDelete_AgentPrompterErrors(t *testing.T) {
// TestDelete_NoYes_NonTTY_RequiresConfirmation: when stdout isn't a TTY
// (typical agent pipe / CI), the destructive-write protocol requires
// explicit -y/--yes. The CLI exits 10 with input.confirmation_required,
// never silently proceeds. See cli/AGENTS.md "Exit codes".
// never silently proceeds. See cli/README.md "Exit codes".
func TestDelete_NoYes_NonTTY_RequiresConfirmation(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeDeleteSvc{}
+1 -1
View File
@@ -5,7 +5,7 @@
// "Doc" is the CLI noun; the underlying SDK type is `Knowledge`. The renaming
// is deliberate: end-users think of a knowledge entry as the document they
// uploaded, not as an abstract knowledge unit. Mapping happens in this package
// only — the SDK surface and server API keep the original spelling.
// only - the SDK surface and server API keep the original spelling.
package doc
import (
+1 -3
View File
@@ -10,7 +10,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
)
@@ -57,7 +56,6 @@ Existing files are NOT overwritten unless --clobber is passed.`,
}
cmd.Flags().StringVarP(&opts.Output, "output", "O", "", `Output path; "-" for stdout. Defaults to the server-suggested filename.`)
cmd.Flags().BoolVar(&opts.Clobber, "clobber", false, "Overwrite the output file if it already exists")
aiclient.SetAgentHelp(cmd, "Downloads a document. Agents that pipe the bytes should pass --output - (stdout). The exit code is 0 on success, 1 on resource.not_found, 5 on missing --output when the server didn't supply a filename.")
return cmd
}
@@ -85,7 +83,7 @@ func runDownload(ctx context.Context, opts *DownloadOptions, svc DownloadService
// resolveDownloadDest returns the final destination ("-" for stdout, an
// absolute or relative path otherwise) after applying the --output flag
// and sanitizing the server-suggested name. A server that returns a path-
// like filename (..\, /etc/foo) is rejected — only the basename is
// like filename (..\, /etc/foo) is rejected - only the basename is
// accepted.
func resolveDownloadDest(opts *DownloadOptions, suggested string) (string, error) {
if opts.Output == "-" {
+1 -1
View File
@@ -113,7 +113,7 @@ func TestDownload_RejectsServerPathTraversal(t *testing.T) {
require.NoError(t, os.Chdir(tmp))
defer os.Chdir(prevWD)
// The server sends "../../etc/shadow" — we accept only "shadow" and
// The server sends "../../etc/shadow" - we accept only "shadow" and
// write to cwd.
svc := &fakeDownloadSvc{content: "exfil", filename: "../../etc/shadow"}
require.NoError(t, runDownload(context.Background(), &DownloadOptions{}, svc, "doc_abc"))
+3 -5
View File
@@ -11,7 +11,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/text"
@@ -41,7 +40,7 @@ type ListOptions struct {
}
// docListStatusValues mirrors internal/types/knowledge.go ParseStatus*
// constants — these are the values the server accepts on the
// constants - these are the values the server accepts on the
// ?parse_status= query. Kept in sync manually since the SDK doesn't
// re-export the enum.
var docListStatusValues = []string{"pending", "processing", "completed", "failed"}
@@ -94,7 +93,6 @@ backend storage order is not guaranteed and varies between deployments.`,
cmd.Flags().BoolVar(&opts.AllPages, "all-pages", false, "Walk all server pages until exhausted (or --limit hit)")
cmd.Flags().StringVar(&opts.Status, "status", "", "Filter by parse status: pending | processing | completed | failed")
cmdutil.AddJSONFlags(cmd, docListFields)
aiclient.SetAgentHelp(cmd, "Lists docs in the resolved KB as a bare JSON array of Knowledge objects (empty `[]` when none). --status filters server-side; `failed` surfaces ingestion errors. --all-pages walks every server page until exhausted (capped by --limit), useful for one-shot exports.")
return cmd
}
@@ -114,7 +112,7 @@ func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions,
if opts.Status != "" && !validDocListStatus(opts.Status) {
return &cmdutil.Error{
Code: cmdutil.CodeInputInvalidArgument,
Message: fmt.Sprintf("--status must be one of: %s — got %q",
Message: fmt.Sprintf("--status must be one of: %s - got %q",
strings.Join(docListStatusValues, " | "), opts.Status),
}
}
@@ -189,7 +187,7 @@ func validDocListStatus(s string) bool {
}
// formatSize renders a byte count as a short human string (KB / MB).
// Kept tiny on purpose — go-humanize would pull a transitive dep just for one
// Kept tiny on purpose - go-humanize would pull a transitive dep just for one
// column. A "-" placeholder hides zero-size entries (URL / text).
func formatSize(bytes int64) string {
if bytes <= 0 {
+2 -5
View File
@@ -161,7 +161,7 @@ func TestList_KBFlagWiredToResolveKB(t *testing.T) {
}
// With --kb=kb_<id> supplied, ResolveKB short-circuits on the prefix
// match without consulting the client. The RunE then asks for the client
// to run the actual list — that call triggers the forced error.
// to run the actual list - that call triggers the forced error.
// Surfacing "forced-after-resolvekb" (rather than CodeKBIDRequired) is
// the proof point that --kb was honored.
cmd := NewCmdList(f)
@@ -292,7 +292,7 @@ func TestList_Limit_LessThanPageSize_SlicesToLimit(t *testing.T) {
opts := &ListOptions{PageSize: 20, Limit: 5}
require.NoError(t, runList(context.Background(), opts, &cmdutil.JSONOptions{}, svc, "kb_xxx"))
body := out.String()
// Count occurrences of "id":"doc_" — should be exactly 5.
// Count occurrences of "id":"doc_" - should be exactly 5.
got := strings.Count(body, `"id":"doc_`)
assert.Equal(t, 5, got, "--limit 5 must slice 20 returned items to 5; body=\n%s", body)
}
@@ -338,6 +338,3 @@ func TestList_AllPages_WithLimit_StopsAtLimit(t *testing.T) {
assert.LessOrEqual(t, len(svc.calls), 3, "should not walk past the page that fills --limit")
}
// (test removed: --page flag was dropped in v0.4 mainstream-alignment;
// --all-pages now walks unconditionally, no mutex case to test.)
+4 -4
View File
@@ -8,7 +8,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
@@ -69,6 +68,8 @@ Pass --name to override the recorded file name (useful when the local file
has a generic name like "report.pdf" but you want to surface it as e.g.
"Q3 Marketing Report.pdf" in the UI).
The three input modes (positional file / --recursive directory walk /
--from-url remote ingest) are mutually exclusive - pass exactly one.
Use --recursive --glob to upload a directory tree (see Examples).`,
Example: ` weknora doc upload report.pdf
weknora doc upload notes.md --kb a32a63ff-fb36-4874-bcaa-30f48570a694
@@ -114,7 +115,6 @@ Use --recursive --glob to upload a directory tree (see Examples).`,
cmd.Flags().StringVar(&opts.Glob, "glob", "*", "Filename pattern to filter when --recursive (e.g. '*.pdf')")
cmd.Flags().StringVar(&opts.FromURL, "from-url", "", "Ingest a remote `URL` (HTTP/HTTPS) instead of a local file")
cmdutil.AddJSONFlags(cmd, docUploadFields)
aiclient.SetAgentHelp(cmd, "Three modes (mutually exclusive): local file (positional), --recursive directory walk + --glob, or --from-url remote ingest. Returns data: Knowledge object (file/URL) or aggregate report (recursive). Errors: resource.already_exists (URL previously ingested) / local.upload_file_not_found.")
return cmd
}
@@ -156,7 +156,7 @@ func runUploadFromURL(ctx context.Context, opts *UploadOptions, jopts *cmdutil.J
if errors.Is(err, sdk.ErrDuplicateURL) {
// Server returns 409 with the existing knowledge entry's data.
// Surface as resource.already_exists; the data payload (if any)
// is observable via err's wrap chain — but the typed code is
// is observable via err's wrap chain - but the typed code is
// what agents branch on.
return cmdutil.Wrapf(cmdutil.CodeResourceAlreadyExists, err,
"URL already ingested into this knowledge base")
@@ -190,7 +190,7 @@ func renderUploadSuccess(k *sdk.Knowledge, jopts *cmdutil.JSONOptions, humanVerb
// validateUploadPath checks that path exists and refers to a regular file.
// Symlinks and directories are rejected up-front so users get a typed error
// instead of an opaque SDK failure mid-upload. os.Stat (not Lstat) is used
// here so a symlink to a regular file is accepted — that matches what
// here so a symlink to a regular file is accepted - that matches what
// `cp` / `git add` do, and the SDK opens the file via os.Open which follows
// symlinks anyway.
func validateUploadPath(path string) error {
+2 -2
View File
@@ -19,7 +19,7 @@ type uploadOutcome struct {
}
// runUploadRecursive walks dir, filters by Glob, and uploads each match
// sequentially. Per-file errors do NOT abort the walk — they accumulate
// sequentially. Per-file errors do NOT abort the walk - they accumulate
// and the final return aggregates them so the user sees the full picture
// in one run. Exit semantics: nil error on full success, a typed *cmdutil.Error
// when ≥1 file failed (the typed code mirrors the first failure's
@@ -48,7 +48,7 @@ func runUploadRecursive(ctx context.Context, opts *UploadOptions, jopts *cmdutil
// Sanity-check the pattern up front so a typo doesn't show up as "no
// files matched" per-file. Cobra populates --glob; tests pass it
// explicitly — no in-function default needed.
// explicitly - no in-function default needed.
if _, err := filepath.Match(opts.Glob, ""); err != nil {
return &cmdutil.Error{
Code: cmdutil.CodeInputInvalidArgument,
+1 -1
View File
@@ -109,7 +109,7 @@ func TestUploadRecursive_PartialFailure_Exits1(t *testing.T) {
var typed *cmdutil.Error
require.ErrorAs(t, err, &typed)
// CodeServerError preserves the 500 classification of the underlying
// SDK error — the recursive wrapper just aggregates.
// SDK error - the recursive wrapper just aggregates.
assert.Equal(t, cmdutil.CodeServerError, typed.Code)
got := out.String()
-2
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/text"
@@ -52,7 +51,6 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
},
}
cmdutil.AddJSONFlags(cmd, docViewFields)
aiclient.SetAgentHelp(cmd, "Returns the full Knowledge object for one document: id, kb_id, file metadata, parse_status, processed_at, error_message. Use this instead of paging through `doc list` when you have the doc id.")
return cmd
}
+2 -2
View File
@@ -54,7 +54,7 @@ func TestView_Human_RendersExpectedFields(t *testing.T) {
}
}
// A doc with no FileName falls back to Title for the NAME line — same
// A doc with no FileName falls back to Title for the NAME line - same
// ordering as `doc list` (KnowledgeDisplayName precedence).
func TestView_Human_TitleFallback(t *testing.T) {
out, _ := iostreams.SetForTest(t)
@@ -69,7 +69,7 @@ func TestView_Human_TitleFallback(t *testing.T) {
}
// Optional fields (ProcessedAt nil, ErrorMessage empty, EmbeddingModelID
// empty) must not produce empty KEY: lines — the formatter omits them
// empty) must not produce empty KEY: lines - the formatter omits them
// rather than printing "PROCESSED: -".
func TestView_Human_OmitsEmptyFields(t *testing.T) {
out, _ := iostreams.SetForTest(t)
+18 -20
View File
@@ -1,12 +1,12 @@
// Package doctor implements `weknora doctor` — 4-item self-check (spec §1.2).
// Package doctor implements `weknora doctor` - 4-item self-check.
//
// Status semantics (4-tier):
//
// ok — passed
// warn — soft problem; non-blocking (e.g. server minor older than CLI,
// ok - passed
// warn - soft problem; non-blocking (e.g. server minor older than CLI,
// keychain unavailable so falling back to file store)
// fail — failed; "hint" actionable
// skip — cascade-skipped (prereq failed) or --offline mode
// fail - failed; "hint" actionable
// skip - cascade-skipped (prereq failed) or --offline mode
//
// JSON output emits the Result object directly (bare data). Exit-code
// signal:
@@ -28,7 +28,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/build"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/compat"
@@ -66,7 +65,7 @@ type Check struct {
Hint string `json:"hint,omitempty"`
}
// Summary is the agent-friendly short-circuit payload (spec §1.2).
// Summary is the agent-friendly short-circuit payload.
//
// AllPassed is true only when there are zero warn/fail/skip rows; warn does
// not block exit-0 but it does flip AllPassed so agents reading just the
@@ -125,7 +124,6 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
cmd.Flags().BoolVar(&opts.NoCache, "no-cache", false, "Bypass server-info cache (located at $XDG_CACHE_HOME/weknora/server-info.yaml); force re-probe")
cmd.Flags().BoolVar(&opts.Offline, "offline", false, "Skip network checks; only verify local keyring/file storage (credential_storage check still runs)")
cmdutil.AddJSONFlags(cmd, doctorFields)
aiclient.SetAgentHelp(cmd, "Returns 4 health checks as a bare JSON object {summary, checks}. AGENT short-circuit: read summary.all_passed; if false, inspect checks[].status (ok/warn/fail/skip). exit 1 only when any status=fail; warn does not affect exit.")
return cmd
}
@@ -133,7 +131,7 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
// offline-mode skip and prereq-failed skip. Returns true when the check has
// been completed (Status set on c) and the caller should NOT run its body.
//
// A prereq is considered "passing" if its Status is OK or Warn — warn signals
// A prereq is considered "passing" if its Status is OK or Warn - warn signals
// a soft problem that does not block downstream functionality. Only fail/skip
// cascades into a downstream skip.
func cascade(c *Check, offline bool, prereqs ...*Check) bool {
@@ -160,7 +158,7 @@ func runChecks(ctx context.Context, opts *Options, svc Services, cliVer string)
{Name: "credential_storage"},
}
// 1. base_url_reachable — gated by offline only.
// 1. base_url_reachable - gated by offline only.
if !cascade(&checks[0], opts.Offline) {
t0 := time.Now()
if err := svc.PingBaseURL(ctx); err != nil {
@@ -173,7 +171,7 @@ func runChecks(ctx context.Context, opts *Options, svc Services, cliVer string)
}
}
// 2. auth_credential — needs base_url.
// 2. auth_credential - needs base_url.
if !cascade(&checks[1], opts.Offline, &checks[0]) {
if _, err := svc.GetCurrentUser(ctx); err != nil {
checks[1].Status = StatusFail
@@ -184,7 +182,7 @@ func runChecks(ctx context.Context, opts *Options, svc Services, cliVer string)
}
}
// 3. server_version — needs auth_credential.
// 3. server_version - needs auth_credential.
if !cascade(&checks[2], opts.Offline, &checks[1]) {
info, fromCache, err := loadOrProbeServerInfo(ctx, opts, svc)
if err != nil {
@@ -195,14 +193,14 @@ func runChecks(ctx context.Context, opts *Options, svc Services, cliVer string)
}
}
// 4. credential_storage — independent of network; never gated by offline.
// 4. credential_storage - independent of network; never gated by offline.
fillCredentialStorageCheck(&checks[3])
return Result{Summary: summarize(checks), Checks: checks}
}
// fillVersionCheck applies compat.Compat to (server, cli) version pair and
// sets Status/Details/Hint on c. fromCache toggles the "cached" suffix —
// sets Status/Details/Hint on c. fromCache toggles the "cached" suffix -
// the loader knows authoritatively which branch it took, time-based
// derivation from ProbedAt is unreliable since SaveCache uses time.Now().
//
@@ -239,8 +237,8 @@ func fillVersionCheck(c *Check, info *compat.Info, cliVer string, fromCache bool
}
}
// credStoreFactory is the seam tests use to inject a fake-store outcome —
// keyring success, file-store fallback, or hard failure — without touching
// credStoreFactory is the seam tests use to inject a fake-store outcome -
// keyring success, file-store fallback, or hard failure - without touching
// the lazy-resolve buildServices contract (round-4 fix). Production stays
// at secrets.NewBestEffortStore.
var credStoreFactory = func() (secrets.Store, error) { return secrets.NewBestEffortStore() }
@@ -248,7 +246,7 @@ var credStoreFactory = func() (secrets.Store, error) { return secrets.NewBestEff
// SetCredStoreFactoryForTest overrides the credential-storage factory used by
// runChecks and returns a cleanup function that restores the previous value.
// Exported so out-of-package tests (notably cli/acceptance/contract) can
// pin the credential_storage outcome — otherwise the check probes the real
// pin the credential_storage outcome - otherwise the check probes the real
// OS keyring, which is present on macOS dev machines but not on Linux CI
// runners without libsecret, producing host-dependent test flakes.
//
@@ -269,7 +267,7 @@ func SetCredStoreFactoryForTest(fn func() (secrets.Store, error)) (restore func(
//
// keyring usable → StatusOK (preferred path)
// file fallback → StatusWarn (keyring unavailable, secrets still persist
// with 0600 file perms — agent containers / WSL hit this)
// with 0600 file perms - agent containers / WSL hit this)
// construction fails → StatusFail
//
// Detection of "fallback to file store" relies on the type returned by
@@ -378,7 +376,7 @@ func marker(s Status) string {
// server, not localhost.
//
// Critically: this does NOT pre-resolve f.Client(). doctor's package promise
// (top comment) is that credential_storage runs even when no auth is set up —
// (top comment) is that credential_storage runs even when no auth is set up -
// e.g. first-time `weknora doctor` to diagnose setup. Pre-resolving Client
// here would early-exit with auth.unauthenticated before any check runs,
// contradicting the docs. Instead, GetCurrentUser / GetSystemInfo lazily
@@ -443,7 +441,7 @@ func (s *realServices) GetCurrentUser(ctx context.Context) (*sdk.CurrentUserResp
// GetSystemInfo lazily resolves the SDK client (same rationale as GetCurrentUser).
// In the cascade ordering, auth_credential gates server_version, so this only
// runs when auth_credential succeeded — but the lazy resolution keeps doctor
// runs when auth_credential succeeded - but the lazy resolution keeps doctor
// useful when only credential_storage is checkable (e.g., user not yet logged in).
func (s *realServices) GetSystemInfo(ctx context.Context) (*sdk.SystemInfo, error) {
cli, err := s.f.Client()
+8 -8
View File
@@ -21,7 +21,7 @@ import (
// and would make CI flake on macOS vs Linux vs WSL). Restored in t.Cleanup.
//
// The hook intentionally lives at package scope (rather than as a runChecks
// parameter) so the production call site stays a zero-arg function — keeping
// parameter) so the production call site stays a zero-arg function - keeping
// the lazy-resolve buildServices contract unchanged (round-4 fix).
func withCredStoreFactory(t *testing.T, fn func() (secrets.Store, error)) {
t.Helper()
@@ -58,7 +58,7 @@ func TestDoctor_AllOK(t *testing.T) {
t.Setenv("XDG_CACHE_HOME", t.TempDir())
out, _ := iostreams.SetForTest(t)
// Pin credential_storage to ok so this test doesn't probe the host OS
// keyring — macOS dev machines have Keychain, Linux CI without libsecret
// keyring - macOS dev machines have Keychain, Linux CI without libsecret
// would otherwise warn and break the AllPassed assertion.
withCredStoreFactory(t, func() (secrets.Store, error) {
return secrets.NewMemStore(), nil
@@ -107,7 +107,7 @@ func TestDoctor_BaseURLFails_DownstreamSkip(t *testing.T) {
if r.Checks[2].Status != StatusSkip {
t.Errorf("server_version status = %q, want skip", r.Checks[2].Status)
}
// credential_storage 与网络无关,应该独立运行(不受 base_url fail 影响)
// credential_storage is network-independent and runs regardless of base_url failures.
if r.Checks[3].Name != "credential_storage" {
t.Errorf("Checks[3] = %q, want credential_storage", r.Checks[3].Name)
}
@@ -245,7 +245,7 @@ func TestDoctor_NoCache_BypassesCache(t *testing.T) {
func TestDoctor_VersionSkewWarns(t *testing.T) {
t.Setenv("XDG_CACHE_HOME", t.TempDir())
_, _ = iostreams.SetForTest(t)
// Force keyring path to ok so credential_storage doesn't itself warn —
// Force keyring path to ok so credential_storage doesn't itself warn -
// we want this test to assert ONLY on server_version.
withCredStoreFactory(t, func() (secrets.Store, error) { return secrets.NewMemStore(), nil })
@@ -262,7 +262,7 @@ func TestDoctor_VersionSkewWarns(t *testing.T) {
if v.Status != StatusWarn {
t.Errorf("server_version status = %q, want warn (server older than CLI)", v.Status)
}
// compat.Compat hint contains "server is older" — that's the load-bearing
// compat.Compat hint contains "server is older" - that's the load-bearing
// substring agents may pattern-match. Not asserting full message text
// since compat.Compat owns the wording.
if !strings.Contains(v.Details, "older") {
@@ -318,7 +318,7 @@ func TestDoctor_HardErrorStillFails(t *testing.T) {
// TestDoctor_KeychainFallbackWarns covers credential_storage's third
// state: keyring unavailable, fell back to FileStore (agent containers,
// headless CI, WSL without DBus). The check should warn — secrets still
// headless CI, WSL without DBus). The check should warn - secrets still
// persist (0600 file perms) but the OS-backed path was unreachable.
func TestDoctor_KeychainFallbackWarns(t *testing.T) {
t.Setenv("XDG_CACHE_HOME", t.TempDir())
@@ -355,7 +355,7 @@ func TestDoctor_KeychainFallbackWarns(t *testing.T) {
}
// TestDoctor_CredStoreFactoryError surfaces the constructor failure path as
// fail (not warn) — distinguishes "cannot persist credentials at all" from
// fail (not warn) - distinguishes "cannot persist credentials at all" from
// "downgraded to file store".
func TestDoctor_CredStoreFactoryError(t *testing.T) {
t.Setenv("XDG_CACHE_HOME", t.TempDir())
@@ -487,7 +487,7 @@ func TestDoctor_RunE_FailReturnsSilentError(t *testing.T) {
}
}
// TestDoctor_RunE_WarnReturnsNil — soft skew path stays exit-0. Pairs with
// TestDoctor_RunE_WarnReturnsNil - soft skew path stays exit-0. Pairs with
// TestDoctor_RunE_FailReturnsSilentError: warn does NOT trigger SilentError.
func TestDoctor_RunE_WarnReturnsNil(t *testing.T) {
t.Setenv("XDG_CACHE_HOME", t.TempDir())
+2 -4
View File
@@ -7,7 +7,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
@@ -15,7 +14,7 @@ import (
// kbCreateFields enumerates the fields surfaced for `--json` discovery on
// `kb create`. The result is the full KnowledgeBase struct; these mirror its
// top-level json tags. Nested config objects are intentionally omitted —
// top-level json tags. Nested config objects are intentionally omitted -
// users wanting them can drop --json (no filter) or use --jq.
var kbCreateFields = []string{
"id", "name", "type", "description",
@@ -33,7 +32,7 @@ type CreateOptions struct {
}
// CreateService is the narrow SDK surface this command depends on.
// *sdk.Client satisfies it via duck typing (ADR-4).
// *sdk.Client satisfies it via duck typing.
type CreateService interface {
CreateKnowledgeBase(ctx context.Context, kb *sdk.KnowledgeBase) (*sdk.KnowledgeBase, error)
}
@@ -62,7 +61,6 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
cmd.Flags().StringVar(&opts.EmbeddingModel, "embedding-model", "", "Embedding model ID (optional; server picks default when unset)")
cmdutil.AddJSONFlags(cmd, kbCreateFields)
_ = cmd.MarkFlagRequired("name")
aiclient.SetAgentHelp(cmd, "Creates a knowledge base under the active context. --name is required; --description and --embedding-model are optional. Returns the full KnowledgeBase object including the new id.")
return cmd
}
+1 -3
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/prompt"
@@ -47,7 +46,7 @@ Pass -y/--yes (global flag) to skip the prompt (required in agent / CI / piped c
AI agents: This is a high-risk write. Without -y/--yes the CLI exits 10
and writes input.confirmation_required to stderr. NEVER auto-pass -y
without the user's explicit go-ahead — the exit-10 protocol exists
without the user's explicit go-ahead - the exit-10 protocol exists
exactly to guard against unintended deletes.`,
Example: ` weknora kb delete kb_abc # interactive confirm
weknora kb delete kb_abc -y # no prompt
@@ -67,7 +66,6 @@ exactly to guard against unintended deletes.`,
},
}
cmdutil.AddJSONFlags(cmd, kbDeleteFields)
aiclient.SetAgentHelp(cmd, "Destructively deletes a knowledge base by id. ALWAYS pass -y/--yes in agent mode (no TTY ⇒ confirm prompt fails). Returns data: {id, deleted:true}.")
return cmd
}
+3 -3
View File
@@ -55,8 +55,8 @@ func TestDelete_NotFound(t *testing.T) {
}
func TestDelete_NonTTY_NoYes_RequiresConfirmation(t *testing.T) {
// SetForTest uses bytes.Buffer for Out — IsStdoutTTY() = false. Without
// -y/--yes, exit-10 protocol fires (see AGENTS.md): the CLI must NOT
// SetForTest uses bytes.Buffer for Out - IsStdoutTTY() = false. Without
// -y/--yes, exit-10 protocol fires (see cli/README.md): the CLI must NOT
// silently proceed in scripted contexts.
iostreams.SetForTest(t)
svc := &fakeDeleteSvc{}
@@ -86,7 +86,7 @@ func TestDelete_JSONOutput(t *testing.T) {
}
// The remaining tests cover the interactive confirm path which only fires
// under IsStdoutTTY() && !JSONOut — exercised via SetForTestWithTTY.
// under IsStdoutTTY() && !JSONOut - exercised via SetForTestWithTTY.
func TestDelete_ConfirmYes(t *testing.T) {
_, _ = iostreams.SetForTestWithTTY(t)
+5 -4
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
@@ -26,7 +25,7 @@ var kbEditFields = []string{
type EditOptions struct {
// Name/Description are *string so we can distinguish "unset" from "set to
// empty". An unset field is omitted from the SDK request — only fields the
// empty". An unset field is omitted from the SDK request - only fields the
// user passed are sent. Server PUT semantics are "replace everything in the
// request"; if we always sent both, an `--name` invocation would silently
// clear the description.
@@ -52,7 +51,10 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: "edit <id>",
Short: "Edit a knowledge base's name or description",
Args: cobra.ExactArgs(1),
Long: `Update a knowledge base's name and/or description. At least one of
--name / --description must be supplied; fields you omit are preserved
server-side.`,
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
jopts, err := cmdutil.CheckJSONFlags(c)
if err != nil {
@@ -74,7 +76,6 @@ func NewCmdEdit(f *cmdutil.Factory) *cobra.Command {
cmd.Flags().StringVar(&name, "name", "", "New name (omit to leave unchanged)")
cmd.Flags().StringVar(&desc, "description", "", "New description (omit to leave unchanged)")
cmdutil.AddJSONFlags(cmd, kbEditFields)
aiclient.SetAgentHelp(cmd, "Edits a knowledge base. At least one of --name/--description is required. Fields not passed are preserved server-side. Returns the updated KnowledgeBase.")
return cmd
}
+1 -1
View File
@@ -104,7 +104,7 @@ func TestEdit_BothFlags(t *testing.T) {
func TestEdit_NotFound(t *testing.T) {
_, _ = iostreams.SetForTest(t)
// 404 must come from the GetKnowledgeBase pre-fetch in the fetch-then-
// update flow — that's the first server roundtrip when the id is bad.
// update flow - that's the first server roundtrip when the id is bad.
svc := &fakeEditSvc{currentErr: errors.New("HTTP error 404: not found")}
opts := &EditOptions{}
opts.Name = stringPtr("x")
-2
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/prompt"
@@ -63,7 +62,6 @@ piped contexts. Without -y the CLI exits 10 in non-interactive mode.`,
},
}
cmdutil.AddJSONFlags(cmd, kbEmptyFields)
aiclient.SetAgentHelp(cmd, "Destructively empties a knowledge base (deletes all documents, preserves the KB record + config). ALWAYS pass -y/--yes in agent mode (non-TTY ⇒ confirm fails). Returns data: {id, deleted_count}. Async — items may still be processing server-side after the call returns.")
return cmd
}
+3 -4
View File
@@ -9,7 +9,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/text"
@@ -18,7 +17,7 @@ import (
// kbListFields enumerates the fields surfaced for `--json` discovery on
// `kb list`. Nested config structs (chunking / image / FAQ / VLM / storage
// / extract) are intentionally omitted — users wanting those can use `--jq`
// / extract) are intentionally omitted - users wanting those can use `--jq`
// against the full object.
var kbListFields = []string{
"id", "name", "type", "description",
@@ -49,6 +48,7 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: "list",
Short: "List knowledge bases visible to the active context",
Long: `List knowledge bases visible to the active context, sorted by most recently updated. Pass --pinned to restrict to pinned KBs.`,
Args: cobra.NoArgs,
RunE: func(c *cobra.Command, _ []string) error {
jopts, err := cmdutil.CheckJSONFlags(c)
@@ -65,7 +65,6 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
cmd.Flags().BoolVar(&opts.Pinned, "pinned", false, "Only show pinned knowledge bases")
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return (0 = no cap, 1..10000 = explicit)")
cmdutil.AddJSONFlags(cmd, kbListFields)
aiclient.SetAgentHelp(cmd, "Lists all knowledge bases as a bare JSON array of {id, name, ...} objects (empty `[]` when none). --pinned restricts to pinned KBs (client-side filter). --limit caps the returned slice. Use `--json` (bare) for full objects, `--json=id,name` to project fields, or `--jq` for arbitrary reshape.")
return cmd
}
@@ -92,7 +91,7 @@ func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions,
}
items = filtered
}
// Spec §1.2: default sort by updated_at desc. Server return order is not
// Default sort by updated_at desc. Server return order is not
// guaranteed, so client-side sort makes output deterministic regardless
// of backend storage choices.
sort.Slice(items, func(i, j int) bool {
+2 -3
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
@@ -20,7 +19,7 @@ var kbPinFields = []string{"id", "is_pinned"}
type PinOptions struct{}
// PinService is the narrow SDK surface this command depends on. The CLI
// reads current state before toggling so `pin`/`unpin` are idempotent —
// reads current state before toggling so `pin`/`unpin` are idempotent -
// the server endpoint is only a non-idempotent toggle.
type PinService interface {
GetKnowledgeBase(ctx context.Context, id string) (*sdk.KnowledgeBase, error)
@@ -42,6 +41,7 @@ func newPinCmd(f *cmdutil.Factory, use string, want bool, short string) *cobra.C
cmd := &cobra.Command{
Use: use + " <id>",
Short: short,
Long: short + ". Idempotent: reads the current pin state and toggles only if different, so re-running on a KB already in the target state is a no-op.",
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
jopts, err := cmdutil.CheckJSONFlags(c)
@@ -56,7 +56,6 @@ func newPinCmd(f *cmdutil.Factory, use string, want bool, short string) *cobra.C
},
}
cmdutil.AddJSONFlags(cmd, kbPinFields)
aiclient.SetAgentHelp(cmd, fmt.Sprintf("Idempotent %s: reads current pin state, toggles only if different. No-op when already in the requested state.", use))
return cmd
}
+1 -2
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/text"
@@ -38,6 +37,7 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: "view <id>",
Short: "Show a knowledge base by ID",
Long: `Fetch a knowledge base's full configuration: chunking settings, embedding / summary model IDs, knowledge_count, chunk_count.`,
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
jopts, err := cmdutil.CheckJSONFlags(c)
@@ -52,7 +52,6 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
},
}
cmdutil.AddJSONFlags(cmd, kbViewFields)
aiclient.SetAgentHelp(cmd, "Returns details of one knowledge base by ID (config + counts).")
return cmd
}
+3 -5
View File
@@ -1,4 +1,4 @@
// Package linkcmd implements `weknora link` — binds the current working
// Package linkcmd implements `weknora link` - binds the current working
// directory to a knowledge base by writing .weknora/project.yaml. Always
// overwrites an existing link silently rather than refusing when one is
// already present. The cobra Long: text covers the user-facing modes
@@ -14,7 +14,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/projectlink"
@@ -49,7 +48,7 @@ overridden by the --kb flag or WEKNORA_KB_ID env var.
Pass --kb <id-or-name> for non-interactive use (scripts, CI). Run on a TTY
without --kb to be prompted from the list of available KBs. Always overwrites
any existing link — re-run to switch.
any existing link - re-run to switch.
AI agents: link writes to the user's working directory. Only run it when the
user explicitly asked to bind this directory; don't run it as a side effect.`,
@@ -67,7 +66,6 @@ user explicitly asked to bind this directory; don't run it as a side effect.`,
}
cmd.Flags().StringVar(&opts.KB, "kb", "", "Knowledge base UUID or name; omit on a TTY for interactive prompt")
cmdutil.AddJSONFlags(cmd, linkFields)
aiclient.SetAgentHelp(cmd, "Writes .weknora/project.yaml binding cwd to a KB. Pass --kb (id or name) for non-interactive use. Always overwrites.")
return cmd
}
@@ -115,7 +113,7 @@ func runLink(ctx context.Context, opts *Options, jopts *cmdutil.JSONOptions, f *
}
// resolveContext picks the auth context to record in the link. There is no
// per-invocation override flag on `weknora link` itself — to record under a
// per-invocation override flag on `weknora link` itself - to record under a
// different context, use the global persistent flag (`weknora --context
// staging link --kb my-kb`); the active context at link time is what gets
// written.
-2
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/projectlink"
@@ -49,7 +48,6 @@ is present anywhere in the parent chain.`,
},
}
cmdutil.AddJSONFlags(cmd, unlinkFields)
aiclient.SetAgentHelp(cmd, "Removes .weknora/project.yaml (the cwd → KB binding). Walks up from cwd. Errors with input.invalid_argument when no link is present in the parent chain.")
return cmd
}
+1 -1
View File
@@ -29,7 +29,7 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
Initial tool surface is read-only and curated: kb_list / kb_view /
doc_list / doc_view / doc_download / search_chunks / chat / agent_list /
agent_invoke. Destructive verbs (create / delete / upload) are deliberately
excluded — the agent should ask the user before mutating; the CLI's
excluded - the agent should ask the user before mutating; the CLI's
exit-10 protocol covers that path.`,
Args: cobra.NoArgs,
Run: func(c *cobra.Command, _ []string) { _ = c.Help() },
+12 -9
View File
@@ -3,13 +3,12 @@ package mcpcmd
import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
mcpserver "github.com/Tencent/WeKnora/cli/internal/mcp"
)
// NewCmdServe builds `weknora mcp serve`. Currently stdio-only; HTTP
// (streamable / SSE) is roadmap 5-7.
// (streamable / SSE) transports may be added later.
func NewCmdServe(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: "serve",
@@ -18,19 +17,24 @@ func NewCmdServe(f *cmdutil.Factory) *cobra.Command {
stderr; the data channel is reserved for protocol traffic.
Authentication is inherited from the active context (or --context). The
server eagerly resolves the SDK client at startup — if no context is
server eagerly resolves the SDK client at startup - if no context is
configured, the process exits with auth.unauthenticated before any MCP
handshake. This way an IDE-side agent sees a clear failure mode rather
than a server that handshakes successfully then errors on every tool.
To use with Claude Code, add to ~/.claude/mcp_servers.json:
To register with your MCP client (Claude Desktop / Code / Cursor / etc.),
add an entry pointing at this binary under "mcpServers":
{
"weknora": {
"command": "weknora",
"args": ["mcp", "serve"]
"mcpServers": {
"weknora": {
"command": "weknora",
"args": ["mcp", "serve"]
}
}
}`,
}
Consult your MCP client's documentation for the exact config-file location.`,
Args: cobra.NoArgs,
RunE: func(c *cobra.Command, _ []string) error {
// Eagerly construct the SDK client. Surfaces auth /
@@ -42,6 +46,5 @@ To use with Claude Code, add to ~/.claude/mcp_servers.json:
return mcpserver.RunStdio(c.Context(), cli)
},
}
aiclient.SetAgentHelp(cmd, "Long-lived stdio MCP server. stdin/stdout for JSON-RPC, stderr for logs. Exposes 9 read-only tools; destructive verbs intentionally excluded. Auth inherited from active context — exit and relaunch with --context to switch. chat / agent_invoke accumulate server-side and return a single result (MCP spec has no streaming-content extension).")
return cmd
}
+7 -29
View File
@@ -19,7 +19,6 @@ import (
mcpcmd "github.com/Tencent/WeKnora/cli/cmd/mcp"
"github.com/Tencent/WeKnora/cli/cmd/search"
sessioncmd "github.com/Tencent/WeKnora/cli/cmd/session"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/build"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/format"
@@ -35,8 +34,9 @@ func Execute() int {
// downstream `--json | jq` pipelines never filter error shapes
// out of the success stream. The typed exit code (3/4/5/6/7/10)
// carries the error class.
cmdutil.PrintError(iostreams.IO.Err, MapCobraError(err))
return cmdutil.ExitCode(MapCobraError(err))
mapped := MapCobraError(err)
cmdutil.PrintError(iostreams.IO.Err, mapped)
return cmdutil.ExitCode(mapped)
}
return 0
}
@@ -70,7 +70,7 @@ func MapCobraError(err error) error {
var cobraFlagErrorPrefixes = []string{
"unknown command ",
"required flag(s)",
"accepts ", // ExactArgs / RangeArgs / etc. — `accepts N arg(s), received M`
"accepts ", // ExactArgs / RangeArgs / etc. - `accepts N arg(s), received M`
"requires at least", // MinimumNArgs
"requires at most", // MaximumNArgs
"unknown flag",
@@ -84,7 +84,7 @@ func NewRootCmd(f *cmdutil.Factory) *cobra.Command {
v, commit, date := build.Info()
cmd := &cobra.Command{
Use: "weknora",
Short: "WeKnora CLI — RAG knowledge base from your terminal",
Short: "WeKnora CLI - RAG knowledge base from your terminal",
Long: `WeKnora CLI lets you authenticate, browse knowledge bases, and run
hybrid searches against a WeKnora server from your shell or an AI agent.`,
Example: ` weknora auth login --host=https://kb.example.com # one-time setup
@@ -101,7 +101,7 @@ hybrid searches against a WeKnora server from your shell or an AI agent.`,
Version: fmt.Sprintf("%s (commit %s, built %s)", v, commit, date),
PersistentPreRun: func(c *cobra.Command, args []string) {
// Propagate the global --context flag into the Factory for this
// invocation only. Spec §1.2: single-shot override, no disk write.
// invocation only - single-shot override, no disk write.
if v, _ := c.Flags().GetString("context"); v != "" {
f.ContextOverride = v
}
@@ -110,7 +110,6 @@ hybrid searches against a WeKnora server from your shell or an AI agent.`,
// Match `weknora version` line format so both forms output the same.
cmd.SetVersionTemplate("weknora {{.Version}}\n")
addGlobalFlags(cmd)
cmd.SetHelpFunc(agentAwareHelpFunc(cmd.HelpFunc()))
// Wrap cobra's flag-parsing errors as FlagError so cmdutil.ExitCode maps
// them to exit 2. "unknown command" errors are detected by message prefix
// in Execute() since cobra emits them as plain errors.
@@ -136,7 +135,7 @@ hybrid searches against a WeKnora server from your shell or an AI agent.`,
}
// addGlobalFlags registers persistent flags available on every subcommand.
// Only flags whose behavior is actually wired are listed — a flag that
// Only flags whose behavior is actually wired are listed - a flag that
// accepts values but does nothing is a worse contract than no flag.
func addGlobalFlags(cmd *cobra.Command) {
pf := cmd.PersistentFlags()
@@ -144,27 +143,6 @@ func addGlobalFlags(cmd *cobra.Command) {
pf.String("context", "", "Override the active context for this invocation (no disk write)")
}
// agentAwareHelpFunc wraps cobra's default help to append the AI agent
// guidance (Annotations[aiclient.AIAgentHelpKey]) only when an AI coding
// agent env var is detected (CLAUDECODE / CURSOR_AGENT). Help-only
// render — no behavior switch.
func agentAwareHelpFunc(orig func(*cobra.Command, []string)) func(*cobra.Command, []string) {
return func(c *cobra.Command, args []string) {
orig(c, args)
if aiclient.DetectAIAgent() == "" {
return
}
extra := aiclient.FormatAgentGuidance(c)
if extra == "" {
return
}
w := c.OutOrStdout()
fmt.Fprintln(w)
fmt.Fprintln(w, "AI Agent guidance:")
fmt.Fprintln(w, " "+extra)
}
}
// versionFields enumerates the fields surfaced for `--json` discovery on
// `version`. Mirrors the version object payload.
var versionFields = []string{"version", "commit", "date"}
+3 -3
View File
@@ -63,7 +63,7 @@ func TestMapCobraError_PinnedPrefixes(t *testing.T) {
})
t.Run("required flag(s)", func(t *testing.T) {
// Self-contained probe — the pin must hold even before resource commands
// Self-contained probe - the pin must hold even before resource commands
// register their own required flags. RunE is required: without it cobra
// treats the command as a parent and skips ValidateRequiredFlags.
probe := &cobra.Command{Use: "probe", RunE: func(*cobra.Command, []string) error { return nil }}
@@ -77,7 +77,7 @@ func TestMapCobraError_PinnedPrefixes(t *testing.T) {
"cobra required-flag prefix changed; update cobraFlagErrorPrefixes. got: %q", err.Error())
})
t.Run("accepts N arg(s) — ExactArgs", func(t *testing.T) {
t.Run("accepts N arg(s) - ExactArgs", func(t *testing.T) {
probe := &cobra.Command{
Use: "probe",
Args: cobra.ExactArgs(1),
@@ -115,7 +115,7 @@ func TestMapCobraError(t *testing.T) {
// TestRoot_ContextFlagPropagation guards the cobra → Factory wiring of the
// global --context flag. Without this, a future refactor that disconnects
// PersistentPreRun from f.ContextOverride would only fail e2e — the
// PersistentPreRun from f.ContextOverride would only fail e2e - the
// per-package TestFactory_ContextOverride only proves the Factory side.
func TestRoot_ContextFlagPropagation(t *testing.T) {
cases := []struct {
+7 -6
View File
@@ -7,7 +7,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
@@ -44,7 +43,7 @@ type ChunksService interface {
// Uses a positional query argument with the KB selected via flag.
//
// The `--kb` flag accepts either a KB UUID (passed through unchanged) or a
// name (resolved via ListKnowledgeBases — see cmdutil.ResolveKBFlag).
// name (resolved via ListKnowledgeBases - see cmdutil.ResolveKBFlag).
func NewCmdChunks(f *cmdutil.Factory) *cobra.Command {
opts := &ChunksOptions{}
cmd := &cobra.Command{
@@ -53,6 +52,9 @@ func NewCmdChunks(f *cmdutil.Factory) *cobra.Command {
Example: ` weknora search chunks "what is RAG?" --kb engineering
weknora search chunks "embedding model" --kb kb_abc --limit 20
weknora search chunks "k8s" --kb engineering --no-keyword # vector-only`,
Long: `Hybrid (vector + keyword) retrieval against the knowledge base. Pass
--no-vector or --no-keyword to disable one channel; you cannot disable both.
--limit caps the returned slice client-side.`,
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
opts.Query = strings.TrimSpace(args[0])
@@ -80,7 +82,6 @@ func NewCmdChunks(f *cmdutil.Factory) *cobra.Command {
}
bindChunksFlags(cmd, opts)
_ = cmd.MarkFlagRequired("kb")
aiclient.SetAgentHelp(cmd, "Hybrid retrieval; returns ranked chunk list. The server may include parent/nearby/relation chunks beyond match_count; --limit caps the returned slice client-side. Pass --no-vector or --no-keyword to disable a channel (mutually exclusive both-off).")
return cmd
}
@@ -88,7 +89,7 @@ func NewCmdChunks(f *cmdutil.Factory) *cobra.Command {
// the constructor readable; --kb is marked required by the caller.
func bindChunksFlags(cmd *cobra.Command, opts *ChunksOptions) {
cmd.Flags().StringVar(&opts.KB, "kb", "", "Knowledge base UUID or name")
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 8, "Maximum results to return (default 8 — tuned for RAG context window; list commands default to 30)")
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 8, "Maximum results to return (default 8 - tuned for RAG context window; list commands default to 30)")
cmd.Flags().Float64Var(&opts.VectorThreshold, "vector-threshold", 0, "Vector retrieval similarity floor (per-channel, pre-fusion); 0 = no filter")
cmd.Flags().Float64Var(&opts.KeywordThreshold, "keyword-threshold", 0, "Keyword retrieval score floor (per-channel, pre-fusion); 0 = no filter")
cmd.Flags().BoolVar(&opts.NoVector, "no-vector", false, "Disable the vector channel")
@@ -129,7 +130,7 @@ func runChunks(ctx context.Context, opts *ChunksOptions, jopts *cmdutil.JSONOpti
if err != nil {
return cmdutil.WrapHTTP(err, "hybrid search")
}
// match_count is the server's *primary-match* cap — after that, the
// match_count is the server's *primary-match* cap - after that, the
// service appends parent / nearby / relation chunks as context
// enrichment, so the wire response can exceed Limit. Treat --limit as
// a hard return-count cap by trimming on the client. Recall isn't
@@ -148,7 +149,7 @@ func runChunks(ctx context.Context, opts *ChunksOptions, jopts *cmdutil.JSONOpti
return renderChunkResults(results, opts.KBID)
}
// renderChunkResults prints a compact pretty list. Minimal stopgap — a
// renderChunkResults prints a compact pretty list. Minimal stopgap - a
// richer tabular renderer can replace this later without breaking the
// JSON contract.
func renderChunkResults(results []*sdk.SearchResult, kbID string) error {
+1 -1
View File
@@ -46,7 +46,7 @@ func TestRunSearch_HumanOutput(t *testing.T) {
// JSON output must surface match_type so machine consumers / agents can
// reason about retrieval channels without re-implementing the wire format.
// (Human renderer keeps default minimal — diagnostic info opt-in via --json.)
// (Human renderer keeps default minimal - diagnostic info opt-in via --json.)
func TestRunSearch_JSONIncludesMatchType(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeChunksSvc{results: []*sdk.SearchResult{
+3 -2
View File
@@ -9,7 +9,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/text"
@@ -54,6 +53,9 @@ func NewCmdDocs(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: `docs "<query>"`,
Short: "Find documents in a knowledge base by name (client-side substring match)",
Long: `Pages through the KB's documents and surfaces every entry whose title or
filename contains the query (case-insensitive). Useful for finding a
specific upload to download or delete by id.`,
Example: ` weknora search docs "Q3 forecast" --kb finance
weknora search docs "spec" --kb engineering --limit 5`,
Args: cobra.ExactArgs(1),
@@ -85,7 +87,6 @@ func NewCmdDocs(f *cmdutil.Factory) *cobra.Command {
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return")
cmdutil.AddJSONFlags(cmd, docsFields)
_ = cmd.MarkFlagRequired("kb")
aiclient.SetAgentHelp(cmd, "Lists documents in --kb whose title or file_name contains the query. Pages through the KB sequentially; stops once limit hits found. Returns the full Knowledge object so agents can derive id / file_size / processed_at without a second call.")
return cmd
}
+7 -3
View File
@@ -9,7 +9,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/text"
@@ -39,7 +38,7 @@ type KBSearchService interface {
ListKnowledgeBases(ctx context.Context) ([]sdk.KnowledgeBase, error)
}
// NewCmdKB builds `weknora search kb "<query>"` — substring + case-insensitive
// NewCmdKB builds `weknora search kb "<query>"` - substring + case-insensitive
// match across KB names and descriptions visible to the active context.
// Results are sorted by name length (shortest first; usually the closest
// hit) for deterministic output.
@@ -48,6 +47,12 @@ func NewCmdKB(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: `kb "<query>"`,
Short: "Find knowledge bases by name or description (client-side substring match)",
Long: `Substring + case-insensitive match across KB names and descriptions visible
to the active context. Results are sorted by name length (shortest first;
usually the closest hit) for deterministic output.
This is name-discovery only - for searching *inside* a knowledge base's
content, use ` + "`weknora search chunks`" + `.`,
Example: ` weknora search kb "marketing"
weknora search kb "team" --limit 5 --json`,
Args: cobra.ExactArgs(1),
@@ -72,7 +77,6 @@ func NewCmdKB(f *cmdutil.Factory) *cobra.Command {
}
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return")
cmdutil.AddJSONFlags(cmd, kbSearchFields)
aiclient.SetAgentHelp(cmd, "Lists KBs whose name or description contains the query (case-insensitive). Useful to discover --kb identifiers before running search chunks / doc list.")
return cmd
}
+1 -3
View File
@@ -5,12 +5,11 @@ package search
import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
)
// NewCmdSearch builds the `weknora search` parent. Pure dispatcher to the
// four subcommands — users must pick a verb (chunks / kb / docs / sessions).
// four subcommands - users must pick a verb (chunks / kb / docs / sessions).
func NewCmdSearch(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: "search",
@@ -28,7 +27,6 @@ func NewCmdSearch(f *cmdutil.Factory) *cobra.Command {
Args: cobra.NoArgs,
Run: func(c *cobra.Command, _ []string) { _ = c.Help() },
}
aiclient.SetAgentHelp(cmd, "Search parent. Use `search chunks/kb/docs/sessions <q>` — there is no bare-positional form.")
cmd.AddCommand(NewCmdChunks(f))
cmd.AddCommand(NewCmdKB(f))
+2 -3
View File
@@ -20,9 +20,8 @@ func TestSearch_NoArgs_ShowsHelp(t *testing.T) {
require.NoError(t, cmd.Execute())
}
// TestSearch_RejectsPositional: bare positional (e.g. the v0.0-style
// `weknora search "<q>" --kb X`) must error — the legacy alias was
// dropped, search is now pure dispatcher.
// TestSearch_RejectsPositional: bare positional `weknora search "<q>" --kb X`
// must error - search is a pure dispatcher with no shortcut form.
func TestSearch_RejectsPositional(t *testing.T) {
_, _ = iostreams.SetForTest(t)
cmd := NewCmdSearch(&cmdutil.Factory{})
+1 -3
View File
@@ -9,7 +9,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/text"
@@ -67,7 +66,6 @@ func NewCmdSessions(f *cmdutil.Factory) *cobra.Command {
}
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return")
cmdutil.AddJSONFlags(cmd, sessionsSearchFields)
aiclient.SetAgentHelp(cmd, "Lists chat sessions whose title or description contains the query. Pages through the tenant sequentially; stops once limit matches found. Returns full Session objects so agents can pivot to session view/delete by id.")
return cmd
}
@@ -124,7 +122,7 @@ func matchSession(s sdk.Session, needle string) bool {
}
// sortSessionsByRecency sorts in place by UpdatedAt desc. Server returns
// strings; we compare lexically — RFC3339 timestamps sort correctly that
// strings; we compare lexically - RFC3339 timestamps sort correctly that
// way, and a stable order is enough for output determinism even if a
// non-conforming string slips through.
func sortSessionsByRecency(items []sdk.Session) {
-2
View File
@@ -6,7 +6,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/prompt"
@@ -64,7 +63,6 @@ without the user's explicit go-ahead.`,
},
}
cmdutil.AddJSONFlags(cmd, sessionDeleteFields)
aiclient.SetAgentHelp(cmd, "Destructively deletes a chat session by id. ALWAYS pass -y/--yes in agent mode (no TTY ⇒ confirm prompt fails). Returns data: {id, deleted:true}.")
return cmd
}
+1 -3
View File
@@ -10,7 +10,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/text"
@@ -68,7 +67,6 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
cmd.Flags().BoolVar(&opts.AllPages, "all-pages", false, "Walk all server pages until exhausted (or --limit hit)")
cmd.Flags().StringVar(&opts.Since, "since", "", "Only show sessions updated within `duration` (e.g. 7d, 24h, 30m)")
cmdutil.AddJSONFlags(cmd, sessionListFields)
aiclient.SetAgentHelp(cmd, "Lists chat sessions as a bare JSON array of Session objects (empty `[]` when none). --all-pages drains every server page in one call (capped by --limit). --since filters client-side after fetch.")
return cmd
}
@@ -196,7 +194,7 @@ func parseSinceDuration(s string) (time.Duration, error) {
}
// fuzzyTime renders a server-provided timestamp string in "2d ago" form.
// Returns the raw input if parsing fails — better to surface the unknown
// Returns the raw input if parsing fails - better to surface the unknown
// format than to silently render "-".
func fuzzyTime(now time.Time, ts string) string {
if ts == "" {
-2
View File
@@ -262,5 +262,3 @@ func TestList_AllPages_WithLimit_StopsAtLimit(t *testing.T) {
assert.LessOrEqual(t, len(svc.calls), 3, "must not fetch beyond what fills --limit")
}
// (test removed: --page flag was dropped in v0.4 mainstream-alignment;
// --all-pages now walks unconditionally, no mutex case to test.)
+1 -1
View File
@@ -3,7 +3,7 @@
//
// Package name `sessioncmd` (not `session`) so callers can `import sdk
// "github.com/Tencent/WeKnora/client"` and use `sdk.Session` without
// shadowing — same hygiene as `contextcmd`.
// shadowing - same hygiene as `contextcmd`.
package sessioncmd
import (
-2
View File
@@ -7,7 +7,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
@@ -49,7 +48,6 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
},
}
cmdutil.AddJSONFlags(cmd, sessionViewFields)
aiclient.SetAgentHelp(cmd, "Shows a chat session's metadata (title, description, timestamps). Errors with resource.not_found if id is unknown.")
return cmd
}
-35
View File
@@ -1,35 +0,0 @@
package aiclient
import (
"strings"
"github.com/spf13/cobra"
)
// AIAgentHelpKey is the cobra Annotation key used to attach an AI-agent-specific
// help blurb to a command. The blurb is appended to --help output only when
// agent mode is active.
const AIAgentHelpKey = "ai_agent_help"
// FormatAgentGuidance returns the agent-targeted help text registered on cmd,
// or "" if none. Render it after the standard help when DetectAIAgent() != ""
// (an AI coding agent env var is set).
func FormatAgentGuidance(cmd *cobra.Command) string {
if cmd == nil {
return ""
}
v, ok := cmd.Annotations[AIAgentHelpKey]
if !ok {
return ""
}
return strings.TrimSpace(v)
}
// SetAgentHelp is a small helper that initializes Annotations and stores the
// blurb under AIAgentHelpKey. Use it in NewCmdX constructors before returning.
func SetAgentHelp(cmd *cobra.Command, blurb string) {
if cmd.Annotations == nil {
cmd.Annotations = map[string]string{}
}
cmd.Annotations[AIAgentHelpKey] = strings.TrimSpace(blurb)
}
-38
View File
@@ -1,38 +0,0 @@
// Package aiclient handles AI agent integration: env-based detection
// (used to trigger AGENT-targeted help text) and per-command help
// annotations. See cli/AGENTS.md for the full agent contract.
package aiclient
import "os"
// AIAgentName identifies the detected coding agent invoking the CLI. Empty
// string means no agent detected (or detection is disabled).
type AIAgentName string
// aiAgentEnvs maps environment variable presence to a coding agent name.
// The earlier 7-entry list (CODEX_*, AIDER_PROMPT, CONTINUE_GLOBAL_DIR,
// OPENCODE_RUNNING, GEMINICODER_PROFILE) did not have official agent docs
// backing those env names; removed in v0.2 to avoid maintaining an
// unverified hardcoded list. New entries should document the source URL.
var aiAgentEnvs = []struct {
env string
name AIAgentName
}{
{"CLAUDECODE", "claude-code"},
{"CURSOR_AGENT", "cursor"},
}
// DetectAIAgent returns the first known agent name whose env var is set to a
// non-empty value, or "" if none are present. Detection is suppressed when
// WEKNORA_NO_AGENT_AUTODETECT is truthy. Tests substitute via t.Setenv.
func DetectAIAgent() AIAgentName {
if v := os.Getenv("WEKNORA_NO_AGENT_AUTODETECT"); v != "" && v != "0" && v != "false" {
return ""
}
for _, a := range aiAgentEnvs {
if os.Getenv(a.env) != "" {
return a.name
}
}
return ""
}
-62
View File
@@ -1,62 +0,0 @@
package aiclient
import (
"testing"
"github.com/stretchr/testify/assert"
)
// clearAgentEnv unsets every env var DetectAIAgent inspects, so a developer
// running these tests from inside Claude Code / Cursor doesn't see false
// positives.
func clearAgentEnv(t *testing.T) {
t.Helper()
for _, a := range aiAgentEnvs {
t.Setenv(a.env, "")
}
t.Setenv("WEKNORA_NO_AGENT_AUTODETECT", "")
t.Setenv("WEKNORA_AGENT", "")
}
func TestDetectAIAgent(t *testing.T) {
cases := []struct {
name string
set map[string]string
want AIAgentName
}{
{name: "empty env", set: nil, want: ""},
{name: "unrelated env", set: map[string]string{"PATH": "/usr/bin"}, want: ""},
{name: "claude code", set: map[string]string{"CLAUDECODE": "1"}, want: "claude-code"},
{name: "cursor", set: map[string]string{"CURSOR_AGENT": "yes"}, want: "cursor"},
// Other entries (codex / aider / continue / opencode / gemini-coder)
// were dropped — those env names had no official agent docs.
// New entries should arrive with a documented source URL.
{
name: "first-match precedence",
set: map[string]string{"CLAUDECODE": "1", "CURSOR_AGENT": "1"},
want: "claude-code",
},
{name: "empty value treated as unset", set: map[string]string{"CLAUDECODE": ""}, want: ""},
{
name: "WEKNORA_NO_AGENT_AUTODETECT=1 suppresses detection",
set: map[string]string{"CLAUDECODE": "1", "WEKNORA_NO_AGENT_AUTODETECT": "1"},
want: "",
},
{
name: "WEKNORA_NO_AGENT_AUTODETECT=0 still allows detection",
set: map[string]string{"CLAUDECODE": "1", "WEKNORA_NO_AGENT_AUTODETECT": "0"},
want: "claude-code",
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
clearAgentEnv(t)
for k, v := range tc.set {
t.Setenv(k, v)
}
assert.Equal(t, tc.want, DetectAIAgent())
})
}
}
+1 -1
View File
@@ -21,7 +21,7 @@ type Refresher interface {
// retry the original request).
//
// Single canonical implementation shared by `weknora auth refresh` and the
// AuthRetryTransport's refresh closure — both used to inline the same
// AuthRetryTransport's refresh closure - both used to inline the same
// six-step sequence with subtly diverging error wording.
func RefreshAndPersist(ctx context.Context, store secrets.Store, refresher Refresher, ctxName string) (string, error) {
refresh, err := store.Get(ctxName, "refresh")
+3 -3
View File
@@ -21,7 +21,7 @@ import (
// - 401 on /api/v1/auth/login or /api/v1/auth/refresh: pass through
// (otherwise a stale refresh token causes infinite recursion).
// - 401 with no initial token configured (api-key contexts): pass through
// — api-key credentials have no refresh semantic.
// - api-key credentials have no refresh semantic.
// - 401 with non-replayable request body (req.GetBody == nil): pass
// through. The SDK always uses bytes.Buffer bodies; this is a safety
// net for hand-built requests.
@@ -31,7 +31,7 @@ import (
// the updated currentToken and replay without re-refreshing (singleflight).
//
// The transport intentionally shadows the SDK's bearerToken (set via
// WithBearerToken). After a refresh, the SDK is unaware of the new token —
// WithBearerToken). After a refresh, the SDK is unaware of the new token -
// the transport's per-request override is the single source of truth for
// the Authorization header. Tokens persisted to the secrets store happen
// inside refreshFn (see cmdutil.RefreshAndPersist).
@@ -49,7 +49,7 @@ type AuthRetryTransport struct {
//
// Pass an empty initialToken to indicate "no bearer credential configured"
// (e.g. an api-key context). In that mode the transport never invokes
// refreshFn — a 401 is propagated as-is.
// refreshFn - a 401 is propagated as-is.
func NewAuthRetryTransport(base http.RoundTripper, initialToken string, refreshFn func(context.Context) (string, error)) *AuthRetryTransport {
if base == nil {
base = http.DefaultTransport
+2 -2
View File
@@ -172,7 +172,7 @@ func TestAuthRetry_SkipAuthEndpoints(t *testing.T) {
func TestAuthRetry_NoTokenConfigured_DoesNotInjectAuthz(t *testing.T) {
// API-key contexts construct the transport with an empty initial token;
// authretry should pass through 401s untouched (no refresh callback exists
// for api-key — they're rejected at the auth-refresh layer).
// for api-key - they're rejected at the auth-refresh layer).
base := &stubTransport{t: t, resps: []*http.Response{resp(401, "")}}
refreshed := false
rt := NewAuthRetryTransport(base, "", func(context.Context) (string, error) {
@@ -192,7 +192,7 @@ func TestAuthRetry_NoTokenConfigured_DoesNotInjectAuthz(t *testing.T) {
func TestAuthRetry_ConcurrentRefresh_SingleFlight(t *testing.T) {
// 4 parallel 401s should trigger exactly 1 refresh; all 4 then retry with
// the new token. Use a server that 401s first request from each unique
// path then 200s on retry — except we use one shared transport with
// path then 200s on retry - except we use one shared transport with
// scripted responses, ordering matters. To keep determinism, build a
// transport that always returns 401 on first call per request, 200 on
// second, and gate the refresh callback.
+1 -1
View File
@@ -21,7 +21,7 @@ import (
//
// The non-TTY branch is the destructive-write protocol: high-risk writes
// always require explicit confirmation in scripted contexts, never silent
// proceed. See cli/AGENTS.md "Exit codes".
// proceed. See cli/README.md "Exit codes".
//
// `yes` should be sourced from the persistent global -y/--yes flag.
func ConfirmDestructive(p prompt.Prompter, yes, jsonOut bool, what, id string) error {
+8 -8
View File
@@ -15,7 +15,7 @@ import (
type ErrorCode string
const (
// auth.* — authentication / permission
// auth.* - authentication / permission
CodeAuthUnauthenticated ErrorCode = "auth.unauthenticated"
CodeAuthTokenExpired ErrorCode = "auth.token_expired"
CodeAuthBadCredential ErrorCode = "auth.bad_credential"
@@ -28,12 +28,12 @@ const (
CodeResourceAlreadyExists ErrorCode = "resource.already_exists"
CodeResourceLocked ErrorCode = "resource.locked"
// input.* — flag and argument validation
// input.* - flag and argument validation
CodeInputInvalidArgument ErrorCode = "input.invalid_argument"
CodeInputMissingFlag ErrorCode = "input.missing_flag"
// CodeInputConfirmationRequired marks a high-risk write that has no
// interactive UI (non-TTY or --json) and was invoked without -y/--yes.
// Mapped to exit code 10 (see cli/AGENTS.md). Agents must surface the
// Mapped to exit code 10 (see cli/README.md). Agents must surface the
// error to the user and only retry with -y after explicit human
// approval; never auto-retry.
CodeInputConfirmationRequired ErrorCode = "input.confirmation_required"
@@ -49,13 +49,13 @@ const (
// server.error so agents can retry with their own --session.
CodeSessionCreateFailed ErrorCode = "server.session_create_failed"
// local.* — config / file / keychain on the user's machine
// local.* - config / file / keychain on the user's machine
CodeLocalConfigCorrupt ErrorCode = "local.config_corrupt"
CodeLocalKeychainDenied ErrorCode = "local.keychain_denied"
CodeLocalFileIO ErrorCode = "local.file_io"
CodeLocalUnimplemented ErrorCode = "local.unimplemented"
CodeLocalContextNotFound ErrorCode = "local.context_not_found"
// v0.2 KB-resolution chain (spec §1.3) and project-link (spec §2.4) codes.
// KB-resolution chain and project-link codes.
CodeKBIDRequired ErrorCode = "local.kb_id_required"
CodeKBNotFound ErrorCode = "local.kb_not_found"
CodeProjectLinkCorrupt ErrorCode = "local.project_link_corrupt"
@@ -124,7 +124,7 @@ func Wrapf(code ErrorCode, cause error, format string, args ...any) *Error {
// from its HTTP shape (404 → resource.not_found, 401 → auth.unauthenticated,
// non-HTTP → network.error, …). Shortcut for the universal pattern
// `Wrapf(ClassifyHTTPError(err), err, format, args...)` used by every SDK
// call site — single source for the wrap-and-classify policy.
// call site - single source for the wrap-and-classify policy.
//
// Use this for any error returned from a wire call. Stays paired with
// ClassifyHTTPErrorOutputs() in the acceptance/contract test, which
@@ -150,7 +150,7 @@ var SilentError = errors.New("silent error (handled)")
// CancelError marks a user-cancelled operation (Ctrl-C / "no" at confirm).
var CancelError = errors.New("operation cancelled")
// Typed predicates — use these instead of comparing ErrorCode strings.
// Typed predicates - use these instead of comparing ErrorCode strings.
// They walk the error chain so wrapped errors still match.
// IsAuthError matches any auth.* code.
@@ -285,6 +285,6 @@ func ClassifyHTTPErrorOutputs() []ErrorCode {
CodeServerRateLimited, // 429
CodeServerError, // 5xx / parse-failure / default
CodeInputInvalidArgument, // 4xx (else)
CodeNetworkError, // 非 HTTP error
CodeNetworkError, // non-HTTP error
}
}
+1 -1
View File
@@ -11,7 +11,7 @@ func TestAllCodes_NonEmpty(t *testing.T) {
if len(codes) == 0 {
t.Fatal("AllCodes() should return registered codes")
}
// Sentinel: 至少包含这几个 v0.0 已知 code
// Sentinel: contains the baseline error codes the registry must always carry.
want := map[cmdutil.ErrorCode]bool{
cmdutil.CodeAuthUnauthenticated: false,
cmdutil.CodeResourceNotFound: false,
+6 -6
View File
@@ -6,9 +6,9 @@ import (
"io"
)
// ExitCode maps an error to the documented CLI exit code (spec §2.4 + ADR-3).
// ExitCode maps an error to the documented CLI exit code.
// - 0 success
// - 1 generic / unknown typed error — fallback for: resource.already_exists,
// - 1 generic / unknown typed error - fallback for: resource.already_exists,
// resource.locked, local.* (config_corrupt / keychain_denied / file_io /
// context_not_found / kb_id_required / kb_not_found / projectlink_corrupt /
// user_aborted / upload_file_not_found), mcp.*, server.session_create_failed,
@@ -19,8 +19,8 @@ import (
// - 5 input.* (other than confirmation_required)
// - 6 server.rate_limited
// - 7 server.* (other than rate_limited/session_create_failed) / network.*
// - 10 input.confirmation_required — high-risk write needs explicit -y
// (see cli/AGENTS.md)
// - 10 input.confirmation_required - high-risk write needs explicit -y
// (see cli/README.md)
// - 130 SIGINT (handled by Go runtime, not this function)
func ExitCode(err error) int {
if err == nil {
@@ -77,7 +77,7 @@ func PrintError(w io.Writer, err error) {
// defaultHint returns a canonical actionable hint for known error codes
// when the call site didn't set one. `auth.unauthenticated` always points
// at `weknora auth login` — covers the broad surface (auth status / kb
// at `weknora auth login` - covers the broad surface (auth status / kb
// list / kb view / search) without per-command hint plumbing.
//
// Empty string for codes without a stable canonical hint.
@@ -104,7 +104,7 @@ func defaultHint(code ErrorCode) string {
case CodeInputInvalidArgument, CodeInputMissingFlag:
return "see `weknora <command> --help` for valid usage"
case CodeInputConfirmationRequired:
return "high-risk write — re-run with -y/--yes after the user explicitly approves"
return "high-risk write - re-run with -y/--yes after the user explicitly approves"
case CodeLocalKeychainDenied:
return "verify keyring access; falls back to file storage"
case CodeLocalConfigCorrupt:
+11 -13
View File
@@ -22,7 +22,7 @@ import (
// closure is lazy: --help / completion / `weknora version` must NOT trigger
// HTTP, keyring access, or filesystem I/O beyond the bare minimum.
//
// Four closures (ADR-4):
// Four closures:
// - Config: parses ~/.config/weknora/config.yaml (no network)
// - Client: constructs the SDK client; only Secrets is sync.Once-cached,
// so callers should hold the returned *sdk.Client across
@@ -33,13 +33,13 @@ import (
// would fork+exec on macOS and DBus-touch on Linux,
// defeating the lazy contract above).
//
// IOStreams is intentionally NOT a Factory closure — it is the package singleton
// IOStreams is intentionally NOT a Factory closure - it is the package singleton
// iostreams.IO. The bar to add a new closure is at least 2 commands sharing the
// same dependency; resist factory bloat.
//
// Client returns a *sdk.Client (the WeKnora SDK). Commands that want narrow
// service interfaces (per ADR-4) declare them in their own files and let the
// real SDK satisfy them implicitly via duck typing.
// service interfaces declare them in their own files and let the real SDK
// satisfy them implicitly via duck typing.
type Factory struct {
Config func() (*config.Config, error)
Client func() (*sdk.Client, error)
@@ -47,9 +47,8 @@ type Factory struct {
Secrets func() (secrets.Store, error)
// ContextOverride, if non-empty, replaces config.CurrentContext for this
// invocation only — set by the global --context flag in PersistentPreRun.
// Buildable Config() / Client() honor it without writing to disk; matches
// spec §1.2 "weknora --context foo kb list = single-shot override".
// invocation only - set by the global --context flag in PersistentPreRun.
// Buildable Config() / Client() honor it without writing to disk.
ContextOverride string
}
@@ -59,7 +58,7 @@ type Factory struct {
// none of them. Client and Secrets closures memoize via sync.Once so the
// SDK client is built (and the keyring is probed) at most once per process,
// even when Factory.ResolveKB internally calls f.Client() before the
// command's RunE calls it again — without this, name-resolved --kb paths
// command's RunE calls it again - without this, name-resolved --kb paths
// would build two clients with two AuthRetryTransports holding independent
// token state.
func New() *Factory {
@@ -157,7 +156,7 @@ func buildClient(f *Factory) (*sdk.Client, error) {
// 401-retry transport: on the first 401 from a non-/auth/* endpoint, the
// transport reads the stored refresh token, calls /api/v1/auth/refresh,
// persists the new pair, and replays the original request with the new
// bearer. API-key contexts skip this (no refresh semantic) — a 401 from
// bearer. API-key contexts skip this (no refresh semantic) - a 401 from
// them propagates as auth.unauthenticated for the caller to handle.
if ctx.TokenRef != "" && ctx.RefreshRef != "" {
refreshFn := func(rctx context.Context) (string, error) {
@@ -171,9 +170,8 @@ func buildClient(f *Factory) (*sdk.Client, error) {
// tenant from the credential itself (JWT claim or API key prefix); the
// header is only meaningful for explicit cross-tenant switching by users
// with CanAccessAllTenants. Auto-mirroring the persisted tenant from config
// breaks that contract — explicit flags (`--tenant=N` is the planned v0.1
// entry point) are required before sending it. `tenant_id` stays in config
// for `auth status` display only.
// breaks that contract - explicit cross-tenant flags would be required
// before sending it. `tenant_id` stays in config for `auth status` display only.
return sdk.NewClient(ctx.Host, opts...), nil
}
@@ -231,7 +229,7 @@ func LoadSecret(store secrets.Store, context, key string) (string, error) {
// refreshAccessToken is the closure target injected into AuthRetryTransport's
// refreshFn. A fresh SDK Client is built here rather than reusing the one
// being constructed — that one is itself wrapped by the transport, which
// being constructed - that one is itself wrapped by the transport, which
// would recurse on refresh. The refresh endpoint is unauthenticated apart
// from the refresh token in the body, so no credential options are needed.
func refreshAccessToken(ctx context.Context, store secrets.Store, host, ctxName string) (string, error) {
+5 -5
View File
@@ -22,7 +22,7 @@ import (
)
// TestFactory_Lazy ensures none of the closures execute work at construction
// time — `--help` / `completion` must not trigger HTTP / keyring access.
// time - `--help` / `completion` must not trigger HTTP / keyring access.
func TestFactory_Lazy(t *testing.T) {
var configCalls, clientCalls, prompterCalls int
f := &Factory{
@@ -39,7 +39,7 @@ func TestFactory_Lazy(t *testing.T) {
return prompt.AgentPrompter{}
},
}
// Asserting on closure presence — none should have run yet.
// Asserting on closure presence - none should have run yet.
assert.Equal(t, 0, configCalls)
assert.Equal(t, 0, clientCalls)
assert.Equal(t, 0, prompterCalls)
@@ -74,7 +74,7 @@ func TestNew_FoundationDefaults(t *testing.T) {
// TestFactory_ContextOverride verifies the global --context flag mechanism:
// f.ContextOverride replaces config.CurrentContext for this invocation only,
// without writing to disk. Spec §1.2.
// without writing to disk.
func TestFactory_ContextOverride(t *testing.T) {
dir := t.TempDir()
t.Setenv("XDG_CONFIG_HOME", dir)
@@ -234,7 +234,7 @@ func TestBuildClient_HappyPath(t *testing.T) {
func TestBuildClient_SkipsUnreferencedSecrets(t *testing.T) {
// If the context doesn't list APIKeyRef, buildClient must not call
// Get(api_key) — a perf invariant: avoid keychain trips for unused creds.
// Get(api_key) - a perf invariant: avoid keychain trips for unused creds.
store := &countingSecrets{MemStore: secrets.NewMemStore()}
require.NoError(t, store.Set("p", "access", "jwt"))
f := &Factory{
@@ -310,7 +310,7 @@ func TestResolveKB_Chain(t *testing.T) {
t.Setenv("WEKNORA_KB_ID", "kb_env_should_lose")
dir := t.TempDir()
resolveKBChdir(t, dir)
// Drop a project link too — must be ignored.
// Drop a project link too - must be ignored.
require.NoError(t, projectlink.Save(filepath.Join(dir, ".weknora", "project.yaml"), &projectlink.Project{KBID: "kb_disk_should_lose"}))
clientCalls := 0
+2 -2
View File
@@ -7,7 +7,7 @@ import (
)
// NormalizeHost validates and canonicalizes a `--host` value. Trailing
// slashes are trimmed. Every failure path returns CodeInputInvalidArgument —
// slashes are trimmed. Every failure path returns CodeInputInvalidArgument -
// a present-but-empty flag is treated as a bad value, not as a missing flag
// (cobra's required-flag layer is what catches the absent case).
//
@@ -30,7 +30,7 @@ func NormalizeHost(host string) (string, error) {
// ValidateHTTPURL applies the same http/https URL rules NormalizeHost uses,
// but parameterized by flagLabel so error messages name the caller's flag
// (e.g. "--host", "--from-url"). Returns CodeInputInvalidArgument on any
// failure. Empty `value` is not pre-checked here — callers that distinguish
// failure. Empty `value` is not pre-checked here - callers that distinguish
// "missing" from "malformed" should test for empty before calling.
func ValidateHTTPURL(flagLabel, value string) error {
u, err := url.Parse(value)
+1 -1
View File
@@ -118,7 +118,7 @@ func TestAddJSONFlags_JQWithoutJSON(t *testing.T) {
if err.Error() != want {
t.Errorf("wrong message.\nwant: %q\ngot: %q", want, err.Error())
}
// Must NOT be a FlagError — gh emits this as a plain error so exit
// Must NOT be a FlagError - gh emits this as a plain error so exit
// code stays 1, not 2.
var fe *cmdutil.FlagError
if errors.As(err, &fe) {
+1 -1
View File
@@ -38,7 +38,7 @@ func ResolveKBFlag(ctx context.Context, lister KBLister, raw string) (string, er
}
// ResolveKBNameToID looks up a knowledge base by name and returns its ID.
// Used by `link` and `Factory.ResolveKB` — a single lookup so the match
// Used by `link` and `Factory.ResolveKB` - a single lookup so the match
// policy (currently exact case-sensitive) lives in one place.
func ResolveKBNameToID(ctx context.Context, lister KBLister, name string) (string, error) {
kbs, err := lister.ListKnowledgeBases(ctx)
+1 -1
View File
@@ -20,7 +20,7 @@ func cachePath() (string, error) {
// LoadCache reads the cached Info. Returns (info, fresh, err).
//
// info == nil when no cache exists (err == nil)
// fresh == false 当 cache 不存在 / TTL 过期
// fresh == false when the cache is missing or TTL-expired
func LoadCache() (*Info, bool, error) {
p, err := cachePath()
if err != nil {
+1 -1
View File
@@ -28,7 +28,7 @@ func TestCache_RoundTrip(t *testing.T) {
t.Errorf("ServerVersion = %v, want %q", got, want.ServerVersion)
}
// 文件应在 $XDG_CACHE_HOME/weknora/server-info.yaml
// File should live at $XDG_CACHE_HOME/weknora/server-info.yaml
p := filepath.Join(dir, "weknora", "server-info.yaml")
if _, err := filepath.Abs(p); err != nil {
t.Errorf("path resolution: %v", err)
+13 -13
View File
@@ -10,9 +10,9 @@ import (
type Level int
const (
OK Level = iota // 兼容
SoftWarn // 服务器旧, 部分新功能不可用
HardError // 不兼容, 需升级 CLI 或 server
OK Level = iota // compatible
SoftWarn // server outdated; some new features may be unavailable
HardError // incompatible; CLI or server must be upgraded
)
func (l Level) String() string {
@@ -27,13 +27,13 @@ func (l Level) String() string {
return "unknown"
}
// Compat compares client/server version. v0.x 阶段允许漂移:
// Compat compares client/server versions. Cross-minor drift is allowed:
//
// 同 major, client minor ≤ server minor → OK
// 同 major, client minor > server minor → SoftWarn (server 旧, 部分新功能不可用)
// 不同 major → HardError
// 字符串 unparseable → OK (容错, 不阻塞)
// "(unknown)" / "" → OK (dev build / server 字段缺失)
// same major, client minor <= server minor -> OK
// same major, client minor > server minor -> SoftWarn (some new features may be unavailable)
// different major -> HardError
// unparseable string -> OK (fail-open, do not block)
// "(unknown)" / "" -> OK (dev build / server field missing)
func Compat(serverVer, cliVer string) (Level, string) {
sMaj, sMin, ok := parseSemver(serverVer)
if !ok {
@@ -44,7 +44,7 @@ func Compat(serverVer, cliVer string) (Level, string) {
return OK, ""
}
if sMaj != cMaj {
return HardError, fmt.Sprintf("incompatible: client %s vs server %s — upgrade required", cliVer, serverVer)
return HardError, fmt.Sprintf("incompatible: client %s vs server %s - upgrade required", cliVer, serverVer)
}
if cMin > sMin {
return SoftWarn, fmt.Sprintf("server is older (server %s, client %s); some new features may be unavailable", serverVer, cliVer)
@@ -56,14 +56,14 @@ func Compat(serverVer, cliVer string) (Level, string) {
// Accepts the leading "v" common in `git describe` output and Tencent/WeKnora
// tag conventions ("v0.1.0"), since both server `/system/info.version` and
// the CLI's own ldflags-injected build.Version may carry it.
// Returns ok=false 当字符串无法识别 (空 / "(unknown)" / 非数字)。
// Returns ok=false when the string is unrecognizable (empty / "(unknown)" / non-numeric).
func parseSemver(s string) (major, minor int, ok bool) {
if s == "" || s == "(unknown)" {
return 0, 0, false
}
// 接受 "v" 前缀:git describe + Tencent tag 都带 v
// Accept the "v" prefix; both `git describe` output and Tencent/WeKnora tags carry it.
s = strings.TrimPrefix(s, "v")
// 去掉 prerelease/build metadata
// Strip prerelease/build metadata.
if i := strings.IndexAny(s, "-+"); i >= 0 {
s = s[:i]
}
+2 -2
View File
@@ -19,9 +19,9 @@ func TestCompat(t *testing.T) {
{"client minor lower", "1.5.0", "1.2.0", compat.OK, ""},
{"client minor higher", "1.2.0", "1.5.0", compat.SoftWarn, "server is older"},
{"different major", "1.9.9", "2.0.0", compat.HardError, "incompatible"},
{"client unset", "1.2.3", "(unknown)", compat.OK, ""}, // dev build, 不报警
{"client unset", "1.2.3", "(unknown)", compat.OK, ""}, // dev build; no warning
{"server unset", "", "1.2.3", compat.OK, ""},
{"malformed server", "garbage", "1.2.3", compat.OK, ""}, // 不阻塞
{"malformed server", "garbage", "1.2.3", compat.OK, ""}, // fail-open
// "v" prefix tolerance (git describe + Tencent tag convention)
{"v-prefix both", "v1.2.0", "v1.5.0", compat.SoftWarn, "server is older"},
+2 -3
View File
@@ -1,5 +1,5 @@
// Package compat probes server `/system/info` and decides client-server
// version skew level. Used by `weknora doctor` 的 server_version 检查项。
// version skew level. Used by `weknora doctor`'s server_version check.
//
// 24h TTL state file cache, three-tier compat semantics
// (major-mismatch=hard / minor-mismatch=soft / equal=ok).
@@ -20,8 +20,7 @@ type Info struct {
ProbedAt time.Time `yaml:"probed_at"`
}
// ProbeService is the narrow SDK surface compat depends on (testability via
// fake; mirrors v0.0 service interface pattern).
// ProbeService is the narrow SDK surface compat depends on; tests inject a fake.
type ProbeService interface {
GetSystemInfo(ctx context.Context) (*sdk.SystemInfo, error)
}
+2 -2
View File
@@ -1,8 +1,8 @@
// Package config reads and writes the user-level config at
// $XDG_CONFIG_HOME/weknora/config.yaml. yaml.v3 directly; viper is
// intentionally not used (see ADR-2). Multi-host context map lives here;
// intentionally not used. Multi-host context map lives here;
// the per-project link (.weknora/project.yaml) is handled by the
// projectlink package (see ADR-16).
// projectlink package.
package config
import (
+1 -1
View File
@@ -10,7 +10,7 @@ import (
// WriteReferences renders the compact references footer used by chat and
// agent invoke: a horizontal rule, one numbered line per reference,
// best-available title + optional score. Skipped entirely when refs is
// empty — agent-friendly silence beats an empty banner.
// empty - agent-friendly silence beats an empty banner.
func WriteReferences(w io.Writer, refs []*sdk.SearchResult) {
if len(refs) == 0 {
return
+1 -1
View File
@@ -8,7 +8,7 @@
// tree (which would expose auth/link/completion/destructive verbs that
// don't belong on an agent-callable surface).
// - Long-running tools (chat / agent_invoke) accumulate the LLM SSE
// stream server-side and return a single CallToolResult — MCP spec
// stream server-side and return a single CallToolResult - MCP spec
// 2025-06-18 does not define streamed tool-result content, so the
// accumulate-and-return pattern is the canonical path.
// - Handlers receive ctx for cancellation; mid-LLM-stream cancellation
+12 -12
View File
@@ -42,17 +42,17 @@ type agentService interface {
// agentInvokeService composes the two SDK methods agent_invoke needs
// (CreateSession for the auto-session path + AgentQAStreamWithRequest
// for the run itself). Declared here alongside the per-domain
// interfaces above so ServiceClient (server.go) — which embeds the
// four domain interfaces — also satisfies it.
// interfaces above so ServiceClient (server.go) - which embeds the
// four domain interfaces - also satisfies it.
type agentInvokeService interface {
CreateSession(ctx context.Context, req *sdk.CreateSessionRequest) (*sdk.Session, error)
AgentQAStreamWithRequest(ctx context.Context, sessionID string, req *sdk.AgentQARequest, cb sdk.AgentEventCallback) error
}
// registerTools wires the curated 9 tools onto server. Adding a tool here
// is a deliberate API expansion — the agent-callable surface is the
// is a deliberate API expansion - the agent-callable surface is the
// reason this CLI ships an MCP server, not its CLI command list, so this
// list must be maintained by hand (see also AGENTS.md mcp serve section).
// list must be maintained by hand.
func registerTools(server *mcpsdk.Server, svc ServiceClient) {
addKBList(server, svc)
addKBView(server, svc)
@@ -76,7 +76,7 @@ type kbListOutput struct {
func addKBList(server *mcpsdk.Server, svc knowledgeBaseService) {
mcpsdk.AddTool(server, &mcpsdk.Tool{
Name: "kb_list",
Description: "List all knowledge bases visible to the active WeKnora tenant. No arguments. Returns items[]: each item carries id, name, description, knowledge_count, is_pinned, updated_at — useful for selecting a kb_id to pass to other tools.",
Description: "List all knowledge bases visible to the active WeKnora tenant. No arguments. Returns items[]: each item carries id, name, description, knowledge_count, is_pinned, updated_at - useful for selecting a kb_id to pass to other tools.",
}, func(ctx context.Context, _ *mcpsdk.CallToolRequest, _ kbListInput) (*mcpsdk.CallToolResult, kbListOutput, error) {
items, err := svc.ListKnowledgeBases(ctx)
if err != nil {
@@ -130,7 +130,7 @@ type docListOutput struct {
func addDocList(server *mcpsdk.Server, svc knowledgeService) {
mcpsdk.AddTool(server, &mcpsdk.Tool{
Name: "doc_list",
Description: "List documents in a knowledge base, with pagination and optional parse-status filter. Returns items[] with id, file_name, title, parse_status, size, updated_at — plus the page/total metadata.",
Description: "List documents in a knowledge base, with pagination and optional parse-status filter. Returns items[] with id, file_name, title, parse_status, size, updated_at - plus the page/total metadata.",
}, func(ctx context.Context, _ *mcpsdk.CallToolRequest, in docListInput) (*mcpsdk.CallToolResult, docListOutput, error) {
if in.KBID == "" {
return nil, docListOutput{}, fmt.Errorf("kb_id is required")
@@ -206,7 +206,7 @@ const maxDocDownloadBytes = 1 << 20
func addDocDownload(server *mcpsdk.Server, svc knowledgeService) {
mcpsdk.AddTool(server, &mcpsdk.Tool{
Name: "doc_download",
Description: "Download a document's raw bytes by ID. Capped at 1 MiB per call — for larger documents, use search_chunks to find the relevant excerpts. is_base64 reports whether content was base64-encoded (heuristic: presence of NUL byte in the first 512 bytes).",
Description: "Download a document's raw bytes by ID. Capped at 1 MiB per call - for larger documents, use search_chunks to find the relevant excerpts. is_base64 reports whether content was base64-encoded (heuristic: presence of NUL byte in the first 512 bytes).",
}, func(ctx context.Context, _ *mcpsdk.CallToolRequest, in docDownloadInput) (*mcpsdk.CallToolResult, docDownloadOutput, error) {
if in.KnowledgeID == "" {
return nil, docDownloadOutput{}, fmt.Errorf("knowledge_id is required")
@@ -250,7 +250,7 @@ type searchChunksOutput struct {
func addSearchChunks(server *mcpsdk.Server, svc knowledgeService) {
// Out = any: SDK output schema would derive from searchChunksOutput,
// which embeds *sdk.SearchResult — and SearchResult.Metadata is a
// which embeds *sdk.SearchResult - and SearchResult.Metadata is a
// nilable map[string]any that violates the auto-generated
// type=object constraint when empty. Skipping derivation by using
// `any` keeps the structured JSON shape identical while bypassing
@@ -258,7 +258,7 @@ func addSearchChunks(server *mcpsdk.Server, svc knowledgeService) {
// below.
mcpsdk.AddTool(server, &mcpsdk.Tool{
Name: "search_chunks",
Description: "Hybrid (vector + keyword) retrieval against a knowledge base. Returns the top chunks ranked by RRF; use this before chat to ground an answer in cited context. Results include knowledge_id, content, score — feed back into chat as context or display directly.",
Description: "Hybrid (vector + keyword) retrieval against a knowledge base. Returns the top chunks ranked by RRF; use this before chat to ground an answer in cited context. Results include knowledge_id, content, score - feed back into chat as context or display directly.",
}, func(ctx context.Context, _ *mcpsdk.CallToolRequest, in searchChunksInput) (*mcpsdk.CallToolResult, any, error) {
if in.KBID == "" {
return nil, nil, fmt.Errorf("kb_id is required")
@@ -366,7 +366,7 @@ type agentListOutput struct {
func addAgentList(server *mcpsdk.Server, svc agentService) {
mcpsdk.AddTool(server, &mcpsdk.Tool{
Name: "agent_list",
Description: "List the tenant's custom agents. Returns items[] with id, name, description, is_builtin — use to discover an agent_id before agent_invoke.",
Description: "List the tenant's custom agents. Returns items[] with id, name, description, is_builtin - use to discover an agent_id before agent_invoke.",
}, func(ctx context.Context, _ *mcpsdk.CallToolRequest, _ agentListInput) (*mcpsdk.CallToolResult, agentListOutput, error) {
items, err := svc.ListAgents(ctx)
if err != nil {
@@ -415,7 +415,7 @@ func addAgentInvoke(server *mcpsdk.Server, svc agentInvokeService) {
Channel: "api",
}
// Auto-create session if not supplied. Sessions are agent-
// agnostic at creation (Q3 — verified against server source).
// agnostic at creation (Q3 - verified against server source).
sessionID := in.SessionID
if sessionID == "" {
sess, err := svc.CreateSession(ctx, &sdk.CreateSessionRequest{Title: "weknora mcp agent_invoke"})
@@ -447,7 +447,7 @@ func addAgentInvoke(server *mcpsdk.Server, svc agentInvokeService) {
// encodeDownload returns (content, isBase64). Heuristic: if the first 512
// bytes contain a NUL, treat as binary. Otherwise it's UTF-8-ish text.
// Matches what /usr/bin/file's "binary" heuristic does at a coarse level —
// Matches what /usr/bin/file's "binary" heuristic does at a coarse level -
// good enough to spare an agent from base64-decoding obvious text.
func encodeDownload(buf []byte) (string, bool) {
probe := buf
+4 -4
View File
@@ -5,8 +5,8 @@
// .weknora/project.yaml is found, (b) the filesystem root is reached, or
// (c) the walk exceeds a 64-level depth limit (cycle protection for
// pathological symlink setups). Pattern matches `cargo`, `npm`, and `git`
// — find-the-project's-root walks; mount-boundary crossing is allowed
// (npm/cargo behave the same — a project may straddle a bind-mount).
// - find-the-project's-root walks; mount-boundary crossing is allowed
// (npm/cargo behave the same - a project may straddle a bind-mount).
package projectlink
import (
@@ -50,7 +50,7 @@ func Discover(startDir string) (string, bool, error) {
return candidate, true, nil
}
if err != nil && !errors.Is(err, os.ErrNotExist) {
// Permission errors etc. — keep walking up; missing read access
// Permission errors etc. - keep walking up; missing read access
// to a parent dir doesn't necessarily mean the project starts
// here. Cargo/npm have the same behavior.
// Fall through to parent walk.
@@ -86,7 +86,7 @@ func Save(path string, p *Project) error {
// Remove deletes the project link at path. A missing file is reported as
// success so callers can stay idempotent under concurrent-removal races
// — the post-condition (no file at path) holds in either case.
// - the post-condition (no file at path) holds in either case.
func Remove(path string) error {
if err := os.Remove(path); err != nil && !errors.Is(err, os.ErrNotExist) {
return fmt.Errorf("remove project link: %w", err)

Some files were not shown because too many files have changed in this diff Show More