chore(cli): polish + docs sync + pre-PR audit fixes
Code-reuse polish (post-implementation review pass): - Extract text.OneLine(maxWidth, s) helper combining preview-row normalization (newline/CR/tab → space) with text.Truncate's UTF-8-safe truncation. Replaces agent/view.go truncate1Line (ASCII '...' + byte-slice CJK-unsafe) and chunk/list.go singleLine. - Lift cmdutil.OpenInput(path) for the '-' = stdin / else os.Open pattern shared across agent create/edit and the api command. Replaces agent/create.go's private openInput. - Strip inline doc-spec parentheticals from source comments — those belong in commit messages and project docs, not in source where they rot. Pre-PR audit fixes: - doc upload: reject `--metadata` paired with `--from-url` as input.invalid_argument up-front (the URL-ingest request type has no metadata field server-side, so the pair would otherwise silently drop). Long help and CHANGELOG updated to call out the asymmetry. - doc upload (file path): map sdk.ErrDuplicateFile sentinel to resource.already_exists. The sentinel arrives with no "HTTP error <n>:" prefix because the SDK short-circuits on file-hash before reading the HTTP status, so the previous WrapHTTP fall-through misclassified it as network.error with a misleading "check base URL reachability" hint. The --from-url branch already handled ErrDuplicateURL this way; this closes the asymmetry. Caught by e2e re-upload of an already-ingested file; regression test added. - README exit-10 enumeration adds `agent delete` and `chunk delete` (these were missing alongside the v0.5 destructive verbs they were meant to gate). Docs sync: - cli/README.md: command tree now includes the chunk subtree; adds agent / chunk lines to the 5-minute quickstart; adds a "Contributing / Reporting issues" section pointing at the repo's SECURITY.md and AGENTS.md; drops third-party CLI parallels from the surface description. - cli/AGENTS.md: "Command surface design SOP" gains the flag-vs-escape-hatch step. "CRUD command flag canon" renamed to the hard-required-flags pattern with the contrast (TTY-prompts-fill) defined inline rather than via opaque shorthand. - cli/CHANGELOG.md: search docs case-sensitivity shift promoted to its own #### Breaking changes subsection. MCP doc_list filter count corrected from 5 to 6. Drops the bogus go.mod yaml.v3 entry (yaml.v3 was already a dependency on main; v0.5 added zero go.mod lines). Replaces internal-Go identifiers (fuzzyTime, NoOptDefVal) with user-language and drops the § section-symbol jargon.
This commit is contained in:
+54
-9
@@ -14,6 +14,7 @@ Available Commands:
|
||||
api Make a raw API request to the WeKnora server
|
||||
auth Manage authentication credentials and contexts
|
||||
chat Ask a streaming RAG question against a knowledge base
|
||||
chunk Manage document chunks (RAG retrieval debug)
|
||||
completion Generate the autocompletion script for the specified shell
|
||||
context Manage CLI contexts (named connection targets)
|
||||
doc Manage documents in a knowledge base
|
||||
@@ -28,10 +29,9 @@ Available Commands:
|
||||
version Show CLI build metadata
|
||||
```
|
||||
|
||||
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).
|
||||
The command surface follows a `<noun> <verb>` convention. The wire
|
||||
contract for AI agents is documented [below](#wire-contract). For
|
||||
contributing to the CLI source, see [AGENTS.md](AGENTS.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -78,6 +78,13 @@ weknora search chunks "what is reciprocal rank fusion?"
|
||||
|
||||
# 7. Ask the LLM (streams to terminal)
|
||||
weknora chat "summarise the design doc"
|
||||
|
||||
# 8. Manage custom agents (full hybrid surface: see `weknora agent --help`)
|
||||
weknora agent list
|
||||
weknora agent invoke ag_abc "what's our q4 retention plan?"
|
||||
|
||||
# 9. Inspect a document's chunks for RAG retrieval debug
|
||||
weknora chunk list --doc doc_xyz
|
||||
```
|
||||
|
||||
---
|
||||
@@ -179,9 +186,9 @@ The full code registry is in `cli/internal/cmdutil/errors.go`
|
||||
**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.
|
||||
context) / `agent delete` / `chunk delete` when running headless.
|
||||
**Never auto-add `-y` without the user's explicit go-ahead** — exit 10
|
||||
is the guard against unintended writes.
|
||||
|
||||
### Other agent ergonomics
|
||||
|
||||
@@ -189,8 +196,32 @@ writes.
|
||||
— 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.
|
||||
- `weknora mcp serve` exposes a curated read-only tool surface over
|
||||
stdio MCP for any MCP-compatible client.
|
||||
|
||||
---
|
||||
|
||||
## Advanced operations not exposed as flags
|
||||
|
||||
WeKnora CLI exposes top use cases as polished commands; deep
|
||||
configuration goes through the raw HTTP passthrough. CLI flag coverage
|
||||
targets common workflows, not 1:1 API parity. Examples of deep
|
||||
operations that intentionally go through `weknora api`:
|
||||
|
||||
- **Tuning a KB's nested config** — chunking strategy, summary model,
|
||||
multimodal extraction defaults, FAQ thresholds, VLM model, storage
|
||||
provider. Use `weknora api PUT /api/v1/knowledge-bases/<id> --input -`
|
||||
with a JSON body matching the server's `UpdateKnowledgeBaseRequest`.
|
||||
- **Per-request `chat` parameters** — multi-KB scope, summary model
|
||||
override, image attachments, web search toggle. Use `weknora api POST
|
||||
/api/v1/knowledge-chat/<session-id> --input -`.
|
||||
- **Per-request `agent invoke` overrides** — same shape via
|
||||
`weknora api POST /api/v1/agent-chat/<session-id> --input -`.
|
||||
- **Operations without a CLI verb** — register / change-password /
|
||||
OIDC flows, organization / sharing endpoints, tenant management.
|
||||
|
||||
`weknora api --help` documents the raw passthrough. Run
|
||||
`weknora doctor` first to verify auth and base URL.
|
||||
|
||||
---
|
||||
|
||||
@@ -221,6 +252,20 @@ macOS / Windows × Go 1.26, path-filtered to changes under `cli/`.
|
||||
|
||||
---
|
||||
|
||||
## Contributing / Reporting issues
|
||||
|
||||
- **Bugs and feature requests**: file an issue at
|
||||
[github.com/Tencent/WeKnora/issues](https://github.com/Tencent/WeKnora/issues).
|
||||
- **Security disclosures**: see the repository-level
|
||||
[SECURITY.md](../SECURITY.md). Do not file public issues for
|
||||
security findings.
|
||||
- **Pull requests**: the developer guide for editing the CLI lives in
|
||||
[AGENTS.md](AGENTS.md) (build / test / command-surface design SOP /
|
||||
CRUD flag canon). Run `go test ./... -race -count=1` and `go vet ./...`
|
||||
before submitting.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT — see the repository [LICENSE](../LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user