feat(cli)!: v0.10 reliability, agent-UX, and command-surface hardening
A hardening + finalization pass over the agent-first CLI: correctness fixes,
richer machine-readable signals, flag/naming consistency, and a symmetric
config surface. Pre-1.0, so it includes breaking renames.
Correctness:
- agent update: resolve/validate --model/--rerank-model (was storing a bogus
name verbatim, corrupting config.model_id).
- doctor: honor WEKNORA_HOST / WEKNORA_API_KEY (headless path no longer reports
"no host configured").
- session ask / MCP session_ask: text answer was empty on non-TTY — the agent
stream sets Done=true on an intermediate agent_query frame before the answer,
and AgentAccumulator treated the first Done as terminal. Terminate on the
`complete` event (new sdk.AgentResponseTypeComplete), not a per-frame Done.
- batch exit codes: any per-item failure collapses to operation.failed (exit 1),
including `doc upload --recursive` partial failures — a permanent per-file
failure (e.g. a duplicate) no longer surfaces as a retryable exit 7 an agent
would loop on; per-item typed errors stay in the envelope.
Agent-first signals & discovery:
- error.exit_code in the envelope (type + exit_code disambiguate the
input.invalid_argument exit-2-vs-5 split in one JSON read).
- meta.hint on empty content search and on draft doc create; doc wait fails fast
on a never-parsing draft instead of hanging to --timeout.
- retrieval-readiness is visible in the natural flow: kb status / kb check emit
retrieval_ready, and kb create hints the fix when no embedding model is bound
— an unconfigured KB no longer looks silently healthy.
- schema contract completeness: every leaf declares output + >=1 example
(drift-guarded); output strings match the meta actually emitted; chunk list
and search docs now emit meta.total_count (both previously dropped it).
- schema tolerates a quoted multi-word command label; zero-state auth — and
`link` with no profile — point at profile setup / the headless WEKNORA_KB_ID
path instead of looping on `auth login`.
- id-addressed reads tolerate a redundant --kb (doc view/wait, chunk list/view
accept and ignore it, declared in schema) so a carried-over --kb doesn't
exit 2; streaming commands warn that --jq does not apply to an NDJSON stream.
- keep JSON-always as the default; --jq hints spell out the .data path.
Consistency & gating:
- doc create: drop the deprecated --name alias (--title only; pre-1.0 break).
- chunk list --limit aligned to 1..10000; model list --limit/-L with
has_more/total_count; api write-gates -X PUT/PATCH (exit 10); skills install
expands a leading ~.
- docs corrected: search docs / doc list --keyword help is case-insensitive
(server does LOWER LIKE); AGENTS.md risk-action list (no phantom kb.init; add
model.update / kb.config.set) and batch example (failed item carries `error`);
session resume --message id comes from `message list`, not the stream.
- auth/profile ergonomics: env credentials are now first-class — `auth token`
prints the active WEKNORA_API_KEY / WEKNORA_TOKEN, and auth login/logout/refresh
give an env-aware message instead of looping on "run auth login". `auth logout`
clears credentials but keeps the profile registered (host preserved for
re-login); deleting a profile is `profile remove`'s job (clean logout/remove
separation, matching gh / lark).
Config surface (symmetric read/write, in-place model edits):
- kb config now returns a secret-free KBModelConfigView (was {}); `kb config`
reads, new `kb config set` writes; `kb init` removed (misnomer).
- kb create --chat-model: retrieval-ready in one step.
- model update: edit a model in place (id preserved, references survive) —
rotate --api-key-stdin, change base-url / display-name / etc.
- session continue-stream renamed to session resume.
Docs: AGENTS.md is the single wire-contract source; CHANGELOG slimmed; stale
kb-init / continue-stream references removed; skill wire-vocab guard extended.
AGENTS.md / weknora-shared SKILL document retrieval_ready (a KB needs an
embedding model to be searchable), that --jq does not apply to NDJSON
streams, and the env-credential-first auth path; the KB quickstart example
now creates a retrieval-ready KB.
This commit is contained in:
@@ -158,7 +158,7 @@ func runChunks(ctx context.Context, opts *ChunksOptions, fopts *cmdutil.FormatOp
|
||||
if results == nil {
|
||||
results = []*sdk.SearchResult{}
|
||||
}
|
||||
meta := &output.Meta{Count: output.IntPtr(len(results)), HasMore: truncated}
|
||||
meta := &output.Meta{Count: output.IntPtr(len(results)), HasMore: truncated, Hint: emptyContentSearchHint(len(results))}
|
||||
return fopts.Emit(iostreams.IO.Out, results, meta)
|
||||
}
|
||||
return renderChunkResults(results, opts.KBID)
|
||||
|
||||
@@ -61,7 +61,7 @@ type DocsSearchService interface {
|
||||
|
||||
// NewCmdDocs builds `weknora search docs "<query>" --kb <id-or-name>`.
|
||||
// Pages through the KB's documents and surfaces every entry whose title
|
||||
// or file_name contains the query as a server-side case-sensitive LIKE
|
||||
// or file_name contains the query as a server-side case-insensitive LIKE
|
||||
// match. Useful for finding a specific upload to download or delete.
|
||||
func NewCmdDocs(f *cmdutil.Factory) *cobra.Command {
|
||||
opts := &DocsSearchOptions{}
|
||||
@@ -72,11 +72,9 @@ func NewCmdDocs(f *cmdutil.Factory) *cobra.Command {
|
||||
keyword filter (matched against title / file_name). Useful for finding a
|
||||
specific upload to download or delete by id.
|
||||
|
||||
The query is a case-sensitive server-side LIKE filter (the server runs
|
||||
` + "`LIKE %keyword%`" + ` against title and file_name). For case-insensitive
|
||||
matching, lower-case the query yourself, e.g.
|
||||
` + "`weknora search docs \"$(printf %s YOUR_QUERY | tr 'A-Z' 'a-z')\"`" + `, or
|
||||
fall back to ` + "`weknora api`" + ` with a custom filter.
|
||||
The query is a case-insensitive server-side LIKE filter (the server runs
|
||||
` + "`LOWER(...) LIKE LOWER('%keyword%')`" + ` against title and file_name), so
|
||||
` + "`FALCON`" + ` and ` + "`falcon`" + ` match the same documents.
|
||||
|
||||
By default, --all-pages=true walks every server page until --limit is
|
||||
reached or the KB is exhausted. Pass --all-pages=false to stop after one page.`,
|
||||
@@ -123,7 +121,7 @@ reached or the KB is exhausted. Pass --all-pages=false to stop after one page.`,
|
||||
UsedFor: "Find documents in a knowledge base by keyword (server-side LIKE filter on title/file_name). The KB comes from --kb (id or name), else WEKNORA_KB_ID, else the linked directory. Results come with meta.count; use --limit to cap and --all-pages=false to stop after one page.",
|
||||
RequiredFlags: []string{"<query> (positional)", "--kb (or WEKNORA_KB_ID / linked directory)"},
|
||||
Examples: []string{`weknora search docs "spec" --kb engineering --format json`},
|
||||
Output: "envelope.data is an array of Knowledge objects with id, title, file_name, parse_status; meta.count is the returned count; meta.has_more=true if more matched than --limit",
|
||||
Output: "envelope.data is an array of Knowledge objects with id, title, file_name, parse_status; meta.count is the returned count, meta.total_count the server's full match count, meta.has_more=true if more matched than --limit",
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
@@ -142,11 +140,13 @@ func runDocsSearch(ctx context.Context, opts *DocsSearchOptions, fopts *cmdutil.
|
||||
// --all-pages=true (default) walks every server page; --all-pages=false
|
||||
// stops after the first page. Termination counts records actually
|
||||
// received so server-capped page_size doesn't truncate.
|
||||
var serverTotal int64
|
||||
for page := 1; ; page++ {
|
||||
items, total, err := svc.ListKnowledgeWithFilter(ctx, opts.KBID, page, opts.PageSize, filter)
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "list documents")
|
||||
}
|
||||
serverTotal = total
|
||||
for _, k := range items {
|
||||
matches = append(matches, k)
|
||||
// Collect one past --limit so has_more is accurate; trimmed below.
|
||||
@@ -172,7 +172,7 @@ done:
|
||||
if matches == nil {
|
||||
matches = []sdk.Knowledge{}
|
||||
}
|
||||
meta := &output.Meta{Count: output.IntPtr(len(matches)), HasMore: truncated}
|
||||
meta := &output.Meta{Count: output.IntPtr(len(matches)), TotalCount: output.IntPtr(int(serverTotal)), HasMore: truncated, Hint: emptyContentSearchHint(len(matches))}
|
||||
return fopts.Emit(iostreams.IO.Out, matches, meta)
|
||||
}
|
||||
if len(matches) == 0 {
|
||||
|
||||
@@ -115,6 +115,29 @@ func TestDocsSearch_JSON(t *testing.T) {
|
||||
assert.Contains(t, got, `"id":"d1"`)
|
||||
}
|
||||
|
||||
// TestDocsSearch_JSON_EmitsTotalCount pins that search docs surfaces the
|
||||
// server's full match total as meta.total_count (server-side keyword filter, so
|
||||
// total is the real match count) — parity with doc/session/chunk list.
|
||||
func TestDocsSearch_JSON_EmitsTotalCount(t *testing.T) {
|
||||
out, _ := iostreams.SetForTest(t)
|
||||
svc := &fakeDocsSearchSvc{
|
||||
pages: map[int][]sdk.Knowledge{1: {{ID: "d1", Title: "match"}, {ID: "d2", Title: "match2"}}},
|
||||
total: 9, // server reports 9 total matches; we display the first page
|
||||
}
|
||||
require.NoError(t, runDocsSearch(context.Background(),
|
||||
&DocsSearchOptions{Query: "match", KBID: "kb1", Limit: 20, PageSize: docsPageSize, AllPages: false},
|
||||
&cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
|
||||
var env struct {
|
||||
Meta struct {
|
||||
Count *int `json:"count"`
|
||||
TotalCount *int `json:"total_count"`
|
||||
} `json:"meta"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
|
||||
require.NotNil(t, env.Meta.TotalCount, "search docs must emit meta.total_count")
|
||||
assert.Equal(t, 9, *env.Meta.TotalCount)
|
||||
}
|
||||
|
||||
func TestDocsSearch_NetworkError(t *testing.T) {
|
||||
_, _ = iostreams.SetForTest(t)
|
||||
svc := &fakeDocsSearchSvc{err: errors.New("HTTP error 404: kb not found")}
|
||||
|
||||
@@ -32,3 +32,16 @@ func NewCmdSearch(f *cmdutil.Factory) *cobra.Command {
|
||||
cmd.AddCommand(NewCmdSessions(f))
|
||||
return cmd
|
||||
}
|
||||
|
||||
// emptyContentSearchHint returns an actionable note when a KB-scoped content
|
||||
// search (chunks / docs) yields zero results, so an agent can distinguish
|
||||
// "no match" from "the KB has no indexed content". Empty when n > 0 so it
|
||||
// never adds noise to real results.
|
||||
func emptyContentSearchHint(n int) string {
|
||||
if n > 0 {
|
||||
return ""
|
||||
}
|
||||
return "0 results: this may be no match, OR the KB has no indexed chunks. " +
|
||||
"Check `weknora kb status <kb>` (chunk_count) and `weknora doc list --kb <kb>` (parse_status); " +
|
||||
"documents in parse_status=draft are not indexed — run `weknora doc reparse <doc-id>`."
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user