2ee9741fa1
Post-review polish on the v0.7 wire / surface contract. Bundles five
follow-ups that landed after the main BREAKING feat commit:
1. Complete context→profile cascade (internal API + YAML schema)
The prior commit renamed only the user-visible surface (commands /
flags / env / project link / envelope field). The internal Go API
and on-disk config schema were still half-renamed — an L-25
self-consistency violation flagged by post-merge review. Closed here:
Internal Go API:
- config.Context → config.Profile
- config.Config.CurrentContext → CurrentProfile
- config.Config.Contexts → Profiles
- LoginOptions.Context → LoginOptions.Profile
- clearContextSecrets() → clearProfileSecrets()
- saveContextRef() → saveProfileRef()
- secrets.Store: param name `context` → `profile` (interface +
FileStore + KeyringStore + MemStore)
- cmdutil.LoadSecret(store, context, key) → LoadSecret(store, profile, key)
- cmdutil.RefreshAndPersist's ctxName → profileName
- Local var `ctx := &config.Profile{...}` → `prof := &config.Profile{...}`
in auth/login.go to eliminate the visual collision with Go stdlib
context.Context that motivated the whole rename in the first place.
On-disk config.yaml schema:
- current_context: → current_profile:
- contexts: → profiles:
- Pre-1.0 break, no compat alias. Users on v0.6 dogfooded configs
must delete ~/.config/weknora/config.yaml or hand-rename the two
keys (CHANGELOG migration note added).
Tests / fixtures / golden files:
- factory_test.go YAML fixture + assertion updated.
- acceptance/e2e/e2e_test.go writeContextYAML → writeProfileYAML,
fixture YAML keys updated.
- acceptance/testdata/wire/doctor.error_network.json golden updated
("active context" → "active profile" in hint string).
User-visible prose sweep:
- cmd/mcp/serve.go --help Long: "active context (or --context)" →
"active profile (or --profile)" — most-visible miss.
- cmd/{kb/list, search/kb, session/list, api/api} Short/Long help.
- cmd/auth/login.go stdout: `(context=%s)` → `(profile=%s)`.
- cmd/auth/logout.go error: `"no current context"` → `"no current profile"`.
- cmd/doctor/doctor.go hint string (also the wire golden above).
- cmd/auth/refresh.go error: `"refresh token missing for context"` →
`"refresh token missing for profile"`.
- README.md: `## Multi-context` H2 → `## Multi-profile`; code-block
comment `# current context` → `# current profile`.
Code-comment / docstring sweep across cli/cmd/auth/ and
cli/internal/cmdutil/. Comments referencing Go stdlib context.Context,
the RAG / LLM "context window" concept, and historical CHANGELOG
entries for v0.4 / v0.5 were left alone.
CHANGELOG v0.7 BREAKING entry gains the on-disk-schema bullet under
the existing "context → profile" item.
2. Profile name validation (shell-injection guard)
`envelope.error.retry_command` is a single shell-string field. An
AI agent that exec()s it via `sh -c <retry_command>` was injectable
through a maliciously-named profile:
weknora auth logout --name 'x; rm -rf ~'
# would produce: retry_command = "weknora auth logout --name x; rm -rf ~ -y"
`cmd/profile/add.go` already enforced an alphanumeric + `-_.`
allowlist via `validateName`. The `auth login` and `auth logout`
paths bypassed it.
- Moved validation from `cmd/profile/add.go` to
`cli/internal/cmdutil/profilename.go` as exported
`ValidateProfileName` (cmdutil is the import-cycle-safe home;
internal/config can't depend on cmdutil).
- `auth login` runs the validator before any persist call.
- `auth logout` runs the validator on `opts.Name` before
constructing `retry_command`.
- Unit tests (`profilename_test.go`) cover the allowlist, empty
rejection, path-traversal, shell metacharacters (`;`, `&`, `|`,
`$()`, backticks, quotes, whitespace, glob, redirects), and the
user-facing hint text. The shell-metachar test exists as a
regression guard.
Wire shape (`retry_command` string → `retry_command_argv []string`)
remains a v0.8 additive change per ROADMAP — this fix removes the
practical exploit path without touching the wire contract.
3. AI-agent terminology disambiguation
"agent" has three referents in this codebase: (a) WeKnora's
server-side Custom Agent resource, (b) the removed `agent invoke`
verb, (c) external LLM/automation consumers. Per project memory
feedback_no_meta_disambiguation_in_docs, the fix is full-term
naming, not "X has N meanings" prose. Surgical changes at section
headers + ambiguous prose:
- AGENTS.md: "Agent decision shortcuts" → "AI agent decision
shortcuts"; "agent-callable surface" → "AI-agent-callable
surface".
- README.md: "Designed to be agent-first" → "AI-agent-first";
"Other agent ergonomics" → "Other AI-agent ergonomics"; "in
agent contexts" → "in AI-agent contexts"; "for CI / agents" →
"for CI / AI agents".
Anaphoric "agents" inside paragraphs that already established
"AI agents" was left alone — full substitution everywhere would
have been prose noise without clarity gain.
4. Wire-contract review follow-ups
Real findings from a second-pass review of the v0.7 envelope /
streaming / surface design. Per project memory
feedback_check_in_domain_anchor_first, candidate findings were
first verified against the in-domain peer CLI explicitly cited as
the envelope anchor; two earlier-flagged issues turned out to be
in-pattern and were withdrawn.
Surviving fixes:
- AGENTS.md success-envelope example rewritten. The prior example
showed `has_more: false` / `_notice: {}` as if they were always
present, but both fields are `omitempty` and never serialize
when zero / nil. Replaced with three realistic shapes (list /
single resource / mutation with no payload) and added a note
that optional fields are omitted when empty.
- cmd/chat/chat.go Args: MinimumNArgs(1) → ExactArgs(1).
v0.6 silently joined `weknora chat hello world` into
`"hello world"`. v0.7 now rejects multi-arg with exit 2,
matching `weknora session ask`. BREAKING; CHANGELOG entry
added under v0.7 BREAKING.
- internal/output/envelope.go extracts NewEnvelope(data, meta,
profile) constructor. The jq-filter path in
cmdutil.FormatOptions.Emit was manually rebuilding the
envelope literal alongside the canonical WriteEnvelope path —
drift risk when fields are added. Single construction point now.
- internal/cmdutil/factory.go adds AddKBFlag(cmd) helper.
Five files (chat, doc/list, doc/upload, doc/create, doc/fetch)
had verbatim-identical `cmd.Flags().String("kb", ...)`
declarations. Centralised so flag name + help text stay
in sync with Factory.ResolveKB. Docstring reordering + gofmt
fixup landed in the same edit to keep ResolveKB's own godoc
attached to its function.
5. OSS-readiness comment / doc sweep
Pre-publication scrub of code, comments, and shipped Markdown to
remove references that only make sense in the development repo:
- AGENTS.md "Deliberate deviations + mainstream alignments"
section: removed peer-project name-drops from the comparison
table; rewrote as five flagged design decisions with rationale
but no specific competitor named. The four rows that previously
contrasted against a named peer CLI now state WeKnora's choice
+ rationale directly. Section header renamed to "Design
decisions worth flagging" since it is no longer a
deviation/alignment matrix.
- CHANGELOG v0.7 BREAKING rationales: three references to a
named peer CLI removed; the context→profile rationale now
cites only mainstream multi-credential CLIs by category (AWS /
Stripe / OpenAI / Anthropic), and the `api -d/--data` removal
rationale cites only `gh api` / `curl`. `chat` BREAKING entry
rationale similarly simplified.
- 35 cross-references to design-spec section numbers (§4.1 /
§4.5 / §5.3 etc.) removed from Go doc comments and test
comments across 13 files. The referenced spec lives outside
the shipped tree; readers of the public repo cannot resolve
them. Each reference replaced with a self-contained semantic
description (e.g. "the batch envelope" / "AGENTS.md section
on the success path").
- Mixed-language strings translated to English:
- Four Go comments: internal/cmdutil/exit.go:213,215,
internal/cmdutil/errors.go:156,
internal/output/batch_test.go:90,
internal/output/envelope_test.go:27.
- One CHANGELOG section title:
`v0.7 — Agent-first wire contract + 命令面集中清理` →
`... + command-surface cleanup`.
- CJK test fixtures (internal/text/truncate_test.go CJK
truncation cases, cmd/session/list_test.go Chinese session
title, acceptance/e2e/e2e_test.go Chinese RAG corpus)
retained — they are intentional test inputs, not stray prose.
- Makefile help comment: `golangci-lint added in PR-9` →
`golangci-lint planned`. Internal PR numbering should not
surface in shipped Makefile prose.
Build green, 28/28 packages, +5 new ValidateProfileName tests.
go vet / gofmt / go mod verify / go mod tidy all clean.
Rationale for the cascade: pre-1.0 is the cheapest moment to close
L-25 self-consistency (L-26). The half-finished internal rename
would have perpetuated the very `context` vs `context.Context`
ambiguity that motivated v0.7's user-visible rename in the first
place.
27 KiB
27 KiB
Changelog — weknora CLI
All notable changes to the weknora CLI (the binary under cli/ in this
repository) will be documented in this file.
The format follows Keep a Changelog and the CLI follows Semantic Versioning independently of the WeKnora server / frontend release cadence.
CLI history before v0.3 is recorded in the project root CHANGELOG.md under the release that introduced the CLI.
[Unreleased]
v0.7 — Agent-first wire contract + command-surface cleanup
BREAKING (v0.6 → v0.7)
- All JSON output now wrapped in symmetric envelope.
- Success on stdout:
{ok:true, data?:<T>, meta?, _notice?, profile?}(dataomitted on mutation-only success). - Error on stderr (json mode):
{ok:false, error:{type, message, hint?, retry_command?, retry_after_seconds?, risk?, detail?}, _notice?}. meta.count/meta.has_moresurface list totals and server-side pagination state.meta.next_cursor/meta.total_count/meta.request_idare reserved — populated when the SDK exposes them (planned for v0.8).- Migration: replace
jq '.[]'withjq '.data[]';.id→.data.id; list-count consumers read.meta.count.
- Success on stdout:
--formatdefault flips tojsonregardless of TTY.- v0.6: smart default (text on TTY, json on pipe).
- v0.7: always json; TTY only affects indent (compact in pipe). Enum
text | json | ndjsonunchanged. - Migration: humans on a TTY pass
--format text(or setWEKNORA_FORMAT=textenv) for the prior auto-text behavior.
chat/session askdefault to NDJSON event-stream (SDK passthrough).- v0.6: TTY rendered a live SSE animation;
--format jsonproduced a buffered object; NDJSON was opt-in. - v0.7:
--format jsonand--format ndjsonboth emit one JSON event per line (no envelope wrapping). CLI injects exactly oneinitevent at stream head; all subsequent events pass through verbatim from the SDK (answer/tool_call/tool_result/references/thinking/reflection/error/completefor chat; agent vocab is a subset). - For prose rendering:
--format text.
- v0.6: TTY rendered a live SSE animation;
weknora contextcommand group renamed toweknora profile.- Subcommands
context list/add/remove/use→profile list/add/remove/use. - Global flag
--context→--profile. - On-disk config
~/.config/weknora/config.yamlkeyscurrent_context:/contexts:→current_profile:/profiles:(no backwards-compat alias; delete the file or rename the keys by hand to migrate). - Binding file
.weknora/project.yamlfieldcontext:→profile:(re-runweknora linkto regenerate). profile useJSON fieldscurrent_context/previous_context→current_profile/previous_profile.weknora linkJSON fieldcontext→profile.- Rationale:
contextcollided with LLM "context window" / RAG "context" / Gocontext.Context. Mainstream multi-credential CLIs (AWS, Stripe, OpenAI, Anthropic) settle onprofileas the term of art.
- Subcommands
weknora agent invokeremoved; useweknora session ask --agent <id>.- Server route is
POST /sessions/{session_id}/agent-qa— session-anchored. weknora agentkeeps CRUD only (list / view / create / edit / delete / status / check).- Migration:
weknora agent invoke ag_x "Q"→weknora session ask --agent ag_x "Q"(auto-creates session if none given).
- Server route is
weknora doc uploadsplit into three commands.weknora doc upload <file>— local file only.weknora doc fetch <url>— server-side remote fetch (wasupload --from-url).weknora doc create --text "..."— direct text knowledge.- URL-only flags (
--title,--file-type,--tag-id) moved todoc fetch. - Rationale:
upload --from-urlmixed semantics ("send out" vs "pull in"); split matches the server's three endpoints + gh CLI conventions.
weknora kb emptyremoved; useweknora doc delete --all --kb=<id>.- Atomic server
ClearKnowledgeBaseContents(no list-then-delete race). - Same exit-10
-y/--yesguard askb delete. - Migration:
weknora kb empty kb_x -y→weknora doc delete --all --kb=kb_x -y.
- Atomic server
weknora api -d/--dataflag removed; use--input <file>or--input -(stdin).weknora apinow accepts any non-empty HTTP method (whitelist removed; matchesgh api/curlbehaviour).- Migration:
weknora api -d '{"foo":1}' /endpoint→echo '{"foo":1}' | weknora api --input - /endpoint.
- Batch operations envelope shape — per-item
okpattern.weknora doc delete id1,id2,id3and similar multi-id mutations now emit:{ok, data:[{id, ok, result?|error?}, ...], meta:{count, successes, failures}}.- Top-level
ok= AND-aggregate of per-itemok(false on partial failure). - All-fail stays in batch shape (not error envelope) — agents can iterate detail per id.
- jq pattern:
jq '.data[] | select(.ok == false) | .id'.
- MCP server tool errors now return
StructuredContent.CallToolResult{IsError: true, Content:[text-fallback], StructuredContent:{type, message, hint?, retry_command?, risk?, detail?}}.- Shape mirrors stderr
envelope.errorsub-object — one parser handles both.
- Unknown subcommand emits typed envelope.
input.unknown_subcommandwithdetail.{unknown, command_path, available[]}retry_command: "<parent> --help". Replaces v0.6's free-form"unknown command \"x\" for \"weknora\""prose.
weknora chatrequires the query as a single quoted argument.- v0.6:
MinimumNArgs(1)silently joinedweknora chat hello worldinto"hello world". - v0.7:
ExactArgs(1)rejects multi-arg with exit 2; matchesweknora session ask. Quote the query:weknora chat "hello world".
- v0.6:
Added
WEKNORA_PROFILEenv var selects the active profile for a single invocation (equivalent to--profile <name>global flag). Overridden by explicit--profile. Useful for CI scripts that cannot pass global flags.WEKNORA_FORMATenv var sets the default--format. Values:text | json | ndjson. Overridden by explicit--format. Invalid values ignored.error.retry_command— directly-executable retry argv, distinct from prosehint. Agents readretry_commandwithout regex-parsinghint.error.retry_after_seconds—server.rate_limited/server.timeoutsurface serverRetry-Afterheader verbatim. CLI-direct (weknora api) parses HTTPRetry-Afterheaders; SDK-mediated paths will gain coverage as the SDK exposes typed transport errors.error.risk.{level, action}— destructive writes carry{level:"destructive", action:"<noun.verb>"}(e.g.doc.delete_all,kb.delete). Reserved levels"read"/"write"not yet emitted._noticeenvelope channel reserved — open-map infrastructure in place for deprecation / version_skew / security notices. Producer wiring planned for v0.8 when the SDK exposes version metadata. Additive non-breaking; unknown keys must be ignored.meta.count/meta.has_moreon list commands.meta.next_cursor/meta.total_count/meta.request_idreserved — populated when the SDK exposes them (planned for v0.8).weknora doc fetch <url>— new command (see split above).weknora doc create --text "..."— new command (see split above).weknora session ask --agent <id> "..."— new command (replacesagent invoke).weknora doc delete --all --kb=<id>— new mode ofdoc delete(replaceskb empty).- NDJSON
initevent at stream head forchat/session ask— carriessession_id+ optionalkb_id/agent_id/model/profile.request_idfield is reserved (not currently populated; planned for v0.8 when the SDK exposes response headers). AgentHelp.Warnings— destructive commands (kb delete,doc delete,agent delete,session delete,chunk delete,profile remove,kb edit,agent edit,auth logout) render an "AI agents:" warnings block in--helpto set explicit expectations around-y/--yes.
Changed
AGENTS.mdadds## Wire contract for AI agents, `## Deliberate deviations- mainstream alignments
,## Pre-1.0 breaking policy,## Exit-10 anti-patterns` sections.
- mainstream alignments
README.mdadds### Agent quick startunder## Wire contract.chunkcommand group help: disambiguation prose vssearch chunksremoved in favour of plain verb descriptions.
Deprecated (will remove in v0.8+)
- (none — pre-release breaking release; no deprecation alias period.)
v0.6 — agent runtime hardening: --format, doc wait, --log-level, status, multi-id delete, paginate
BREAKING (v0.5 → v0.6)
--jsonflag removed → use--format json(with optional--jq '<expr>'for projection / filtering). The v0.5--json=fields,...per-field projection drops entirely; rewrite as--format json --jq '.[] | {id, name}'(jq is the canonical projection mechanism going forward).--no-streamflag removed onchat/agent invoke→ use--format jsonto buffer the full answer before printing. The bare text-accumulate use case (TTY but no streaming) is dropped.WEKNORA_SDK_DEBUG=1env removed → useWEKNORA_LOG_LEVEL=debug.kb create --name <name>flag removed → use positionalkb create <name>(consistent withagent create <name>).
Added
--format text|json|ndjsonflag selecting the stdout serialization. Registered per-command (only commands that honor--formatregister it; others reject it withunknown flag/ exit 2). Output mode auto-resolved totexton a TTY andjsonwhen stdout was piped (v0.7 promoted the flag to a persistent global and made the default alwaysjson).--jq '<expr>'flag pairs with--format json|ndjsonto filter or project the JSON output via a jq expression.weknora doc wait <id> [<id>...]— block until every document reaches a terminalparse_status. Always wait-all — use shell composition (wait id1 && wait id2) for fail-fast.--timeout DURATION(default 10m; exit 124 on hit)--interval DURATION(default 2s; exponential backoff to 15s + jitter)- Multi-id concurrent (max 5 parallel); exit code priority 1 > 124 > 0
--log-level error|warn|info|debugpersistent flag +WEKNORA_LOG_LEVELenv. Wires into the SDK's debug logger via the additiveclient.SetDebugLevel(level string)function.kb create --storage-provider <local|minio|cos|tos|s3|oss|ks3>— sets the new KB'sstorage_provider_config.providerat creation time (server only accepts it on create, not update). Required on self-hosted deployments where the server-side default doesn't pre-populate a provider — without it, subsequentdoc uploadreturnskb not found.weknora kb status <id>— fast health snapshot (1 HTTP). Returns reachable / counts / is_processing.weknora kb check <id>— deep verification: status fields +failed_countaggregated via doc list page-walk (1 + N HTTP). The verb split betweenstatus(read state cheaply) andcheck(actively verify) communicates cost to the caller.weknora agent status <id>— fast health snapshot (1 HTTP): reachable / model_id.weknora agent check <id>— deep verification: status fields +kb_scope_all_reachablefrom probing each KB in scope (1 + N HTTP). Same status/check verb split as kb status/check.weknora doc delete <doc-id> [<doc-id>...]— positional multi-id. Default keep-going on failure. Single-y/--yesconfirms the entire batch; non-TTY without-ystill exits 10.weknora session delete <session-id> [<session-id>...]— positional multi-id with the same keep-going semantics asdoc delete.weknora chunk delete <chunk-id> [<chunk-id>...] --doc <doc-id>— positional multi-id, all chunks share the same--docparent (server route requires it).weknora api <path> --paginate— follows weknora's offset-based pagination (?page=N&page_size=M) and merges all pages into a single{data, total}JSON response.- MCP
chatandagent_invoketools output schemas extended withthinking/tool_calls/assistant_message_id. Tool descriptions callout "server-side accumulated, NOT streaming" (MCP tools/call has no standard partial-response). SetAgentHelppattern —cmdutil.SetAgentHelp(cmd, AgentHelp{...})exposes a stable JSON used_for / required_flags / examples / output shape, activated byWEKNORA_AGENT_HELP=1at--helptime. Applied tochatandkb listas proof-of-pattern; extending to another command requires touching only that command'sNewCmd.cli/AGENTS.mdgains an "Error code reference" section (35 typed codes + exit codes + retryable / hint), with<!-- ERROR_REFERENCE_START -->markers and CI parity test (errors_doc_test.go) — every new typed code inAllCodes()must be documented or CI fails.- New
operation.*typed error namespace for CLI-level wait/poll outcomes:operation.timeout→ exit 124 (distinct fromserver.timeout→ exit 7; matches the convention from GNUtimeout(1)). Used bydoc waitand any future CLI-level wait/poll surfaces.operation.failed→ exit 1. Emitted when one or more wait targets reach a terminal failure (doc waitfindsparse_status=failed) or when multi-iddeleterolls up partial failures. Distinct fromserver.errorbecause the failure is the target's own terminal state, not a transient transport issue —server.error's "retry with backoff" hint would be misleading.operation.cancelled→ exit 1, raised to 130 bymain.gowhen the root context was signal-cancelled. Surfaced by chat / agent invoke / doc wait on Ctrl-C or SIGTERM. Carries a hint pointing at the signal, not at-y/--yes(which would have been the misleadinglocal.user_abortedhint).
- Signal-aware root context —
main.gowiressignal.NotifyContextfor SIGINT and SIGTERM so long-running commands observectx.Done()and run their cancellation cleanup (re-emit auto-created session id, returnoperation.cancelled); the process exits 130 whenever the context was signal-cancelled, matching Unix signal convention. - MCP tool input renames for consistency:
doc_viewanddoc_downloadnow acceptdoc_id(wasknowledge_id) so every MCP tool that references a document uses the same parameter name aschunk_listand the CLI's<doc-id>positional. WriteNDJSONhelper ininternal/format/(per http://ndjson.org: arrays split per-line, single records emit one line).
Changed
cli/README.md"Exit codes" subsection extended with124(operation.timeout); rows for1and130now nameoperation.failedandoperation.cancelledalongside the existing groupings.cli/README.mdgains a "Status / check verb pair" subtable under "Health check" and adoc waitparagraph with full exit-code list (0/1/124/130).cli/AGENTS.mdgains design SOPs for Status / check verb pair pattern and Long-poll wait commands, plus a note on the SetAgentHelp pattern and current coverage (chat / kb list).- Multi-id delete partial-failure exit code:
doc delete/session delete/chunk delete(multi-id mode) now exit1(operation.failed) when some targets fail, rather than exit7(server.error). The retry-with-backoff hint for server.* would have misled callers when the actual cause is a target's terminal state. doc uploadwith no path / no--from-urlnow exits2(FlagError, matching cobra'sMinimumNArgsconvention for commands that need a positional), rather than5(input.invalid_argument).--log-levelinvalid value exits2(FlagError) for consistency with--formatinvalid-value behaviour. Env values still fall through silently (env is best-effort).- Multi-id delete stdout contract: pre-flight failures (e.g. missing
-yconfirmation) no longer emit the empty{ok, failed}envelope to stdout — stdout stays empty per the wire contract in README.md, the typed error goes to stderr only. - Positional id help strings now namespaced for clarity in both human
help and agent
--helpparsing:<id>→<kb-id>/<doc-id>/<session-id>on kb / doc / session subtrees.agentandchunksubtrees were already namespaced. Pure help-text change — argument parsing is unchanged. chat "<text>"Use string now shows quotes — matchesagent invokeandsearch chunksquoting hint for queries that contain spaces.
SDK additions (strictly additive)
client.SetDebugLevel(level string)— programmatic control over the SDK's internal slog debug logger.
v0.5 — agent CRUD, chunk subtree, MCP chunk_list, audit-driven cleanup
Added
weknora agent create <name> --model <id>/agent edit <id>/agent delete <id>— hybrid surface (hot-path flags for the common fields +--config-fileYAML/JSON for the long tail +--generate-skeletontemplate emit).--from <agent-id>copies from an existing agent.weknora chunk list --doc <doc-id>/chunk view <chunk-id>/chunk delete <chunk-id> --doc <doc-id>— new subtree for RAG retrieval debug. Paginated with v0.4--limit/--page-size/--all-pagescanon.weknora mcp serveaddschunk_listas the 10th curated tool.weknora agent view <id>human output now renders all 34 AgentConfig fields (previously 7), grouped into 10 presentation sections.--all-pages/--page-sizeonsearch docsandsearch sessions(catching up withsession list/doc listcanon from v0.3+v0.4).weknora doc listgains--keyword/--file-type/--source/--tag-id/--start-time/--end-time(RFC3339) — matches the SDK'sKnowledgeListFiltersurface. Time flags reject malformed input withinput.invalid_argument.- MCP
doc_listtool gains the same 6 filter fields (keyword,file_type,source,tag_id,start_time,end_time) so agents have parity with the CLI. weknora session view --full(with--limit, default 50, bounds 1..1000) loads chat history viaLoadMessagesand renders messages inline after session metadata. JSON mode projects messages into amessagesarray.--limitwithout--fullerrors withinput.invalid_argument.weknora kb viewhuman render now includesTYPE,PINNED(badge, only when set),TEMPORARY(badge),PROCESSING(with doc count, only when active),SUMMARY MODEL, andCREATED. Nested config structs stay JSON-only.weknora doc viewhuman render expands to includeTITLE(when distinct from filename),DESC,SOURCE,CHANNEL,TAG,STORAGE(human-readable bytes),SUMMARY,ENABLED, andHASH(12-char prefix). All omit-empty.weknora doc uploadgains--enable-multimodel(tri-state: unset/true/false), repeatable--metadata key=value, and--channelflags.--enable-multimodeland--channelapply to file /--recursive/--from-url;--metadatais file /--recursiveonly (the URL-ingest request carries no metadata field server-side, so passing it with--from-urlis rejected up-front asinput.invalid_argument). URL mode additionally accepts--title,--file-type, and--tag-id. Threads through to the SDK'sCreateKnowledgeFromFile/CreateKnowledgeFromURLsignatures (previously hardcoded to nil/"api" and dropped URL extras).
Fixed
- MCP
search_chunkstool:limitarg now correctly threads intoSearchParams.MatchCount. Previously the server's default cap won, silently capping below the requested limit. search sessionshuman time format: now renders a relative duration ("2 hours ago") matchingsession list, instead of raw RFC3339.doc upload(file path): re-uploading a file already ingested into the KB now surfaces asresource.already_exists(exit 1) instead of the misleadingnetwork.error("check base URL reachability"). The SDK returns itsErrDuplicateFilesentinel with noHTTP error <n>:prefix because the duplicate is detected via file-hash short-circuit, not by HTTP status; the previous fall-through toWrapHTTPtherefore misclassified it. The--from-urlbranch already handled the symmetricErrDuplicateURLcorrectly.
Breaking changes
weknora search docsnow applies the keyword filter server-side viaListKnowledgeWithFilter(was: page through every doc and substring-match client-side). Smaller wire payload on large KBs. The match is now case-sensitive (server usesLIKE %keyword%), whereas the previous client-side path lowered both sides. Callers that relied on case-insensitive matching (e.g.search docs Q3findingq3 retro) must lower-case the query themselves, or fall back toweknora apiwith a custom filter.
Changed
cli/AGENTS.mdMCP curation rationale rewritten: curated read-only is a deliberate product call gated on the absence of server-side per-token scope. When server-side scope ships, mutation tools can land in the MCP surface.cli/AGENTS.mdadds "Command surface design SOP" and "CRUD command flag canon" sections for future contributors. The design-SOP section includes a step reminding contributors to decide flag-vs-escape-hatch per field rather than trying to flag-mirror every SDK capability.cli/README.mdnow documents theweknora apiraw HTTP passthrough as the canonical escape hatch for deep KB config, per-requestchat/agent invokeoverrides, and operations without a CLI verb.
v0.4 — output contract hardening and mainstream alignment
Breaking changes
- Dropped the JSON envelope.
stdoutnow emits bare typed data ({...}or[...]); errors are written tostderrascode: msgwith an actionablehint:line. Pipelines using--json | jqno longer have to filter out an envelope wrapper. - Dropped
--dry-run. Destructive writes still require-y/--yes; non-TTY callers that omit-yexit with code 10 andinput.confirmation_requiredso an agent must surface the prompt to a human before retrying. - Dropped the per-command AI footer that rendered when AI-coding-agent
env detection fired. The same machine-readable guidance now lives in
the standard
--help(visible to all callers) and inmcp 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 tostdoutfor scripting (raw secret by default;--jsonemits{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.--limitand--all-pageson 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-tokenvalidates the supplied key against/auth/mebefore 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
context add/context list/context remove— first-class CRUD over connection targets (previously implicit viaauth login --name). Removing the current context requires explicit-y(exit-10 protocol) because subsequent commands have no default target.auth refresh— exchanges the stored refresh token for a new access + refresh pair (OAuth refresh-token grant). Transparent 401 → refresh → retry is also wired into the SDK transport with singleflight de-dup, so most callers never need to invoke this explicitly.kb edit— partial-update edit with only-sent-fields semantics (*stringoptions so unset fields stay unset in the PUT body).kb pin/kb unpin— idempotent pin/unpin toggle; no-op when already in the target state (emits_meta.warnings, no server call).kb empty— bulk-delete documents while preserving the KB record and its config. High-risk-write; exit-10 confirmation in non-TTY /--jsonpaths.doc view <id>— show one document's metadata (title, file name, type, size, parse status, embedding model, processed-at, error message). Counterpart tokb viewandsession view.doc download— stream a knowledge file to disk (-O FILE/-O -for stdout) with--clobbercontrolling overwrite. Rejects server-supplied path-like filenames; partial writes on error are cleaned up.doc upload --recursive --glob '*.md'— walk a directory and upload every match. Per-fileOK/FAILprogress lines on the human path; aggregateduploaded[]/failed[]envelope on--json. Exit code typed to the first failure's class on partial failure.search chunks/search kb/search docs/search sessions— verb-noun subtree (ghsearch code/repos/issues/…shape).search chunksis hybrid (vector + keyword) retrieval; the other three are client-side substring filters useful for discovering identifiers. All four take--limit N/-L N(1..1000) to cap returned rows.session list/session view/session delete— chat session management.api --input FILE/api --input -— body source for raw HTTP passthrough (file or stdin); mutually exclusive with--data.unlink— remove the cwd's.weknora/project.yamlso subsequent commands stop auto-resolving--kbfrom it. Walks up from cwd so a user in a subdirectory can unlink without cd-ing to the project root.- Completion smoke test guards against cobra bumps silently breaking bash / zsh / fish / powershell completion.
SDK additions (Go client at client/, strictly additive)
OpenKnowledgeFile(ctx, id) (filename, body io.ReadCloser, err)— new primitive returning the body as a stream plus the server-suggested Content-Disposition filename.DownloadKnowledgeFileis now a thin wrapper (signature unchanged, gained partial-file-on-error cleanup).WithTransport(http.RoundTripper) ClientOption— lets the CLI install the 401-retry transport.PathAuthLogin/PathAuthRefreshconstants — so HTTP middleware doesn't re-hardcode the literals.IsPinned boolfield onKnowledgeBase(server already returned it; SDK just hadn't modeled it).