feat(cli): search --all-pages canon catch-up + AGENTS.md SOP / CRUD canon

Brings search docs and search sessions to v0.4 pagination canon
(--limit / --page-size / --all-pages, matching session list / doc list).
Both default --all-pages=true to preserve prior silent walk-all
behavior; explicit knobs added for users who want one-page fetch.

cli/AGENTS.md gains two new sections:
- Command surface design SOP — a 5-step SDK-schema-first pre-design
  checklist for future contributors. Earlier spec drafts produced
  schema-error classes (missing/mismatched fields, missing pagination
  flags) when commands were designed from convention rather than from
  the SDK; the SOP makes the SDK the ground truth.
- CRUD command flag canon — Mode A (hard-required + flag error, no
  interactive prompts), the established pattern for non-auth CRUD.

Also fixes the agent invoke rationale source: the CLI-layer precedent
for invoke being a separate verb (not a chat mode) is documented
inline rather than referencing other vendor CLI behavior.
This commit is contained in:
nullkey
2026-05-16 01:23:11 +08:00
committed by lyingbug
parent 26fa43e2cc
commit 7bccd72ba3
6 changed files with 233 additions and 22 deletions
+37 -8
View File
@@ -15,11 +15,15 @@ import (
sdk "github.com/Tencent/WeKnora/client"
)
// docsPageSize is how many entries we pull per ListKnowledge round-trip
// when paging through a KB to filter client-side. Server caps page_size at
// 1000 (per the doc/list bound this branch already added).
// docsPageSize is the default --page-size on `search docs`: how many
// entries to pull per ListKnowledge round-trip when paging through a KB
// to filter client-side. Server caps page_size at 1000 (per the doc/list
// bound this branch already added). Tunable via --page-size in 1..1000.
const docsPageSize = 200
// docsMaxPageSize bounds the --page-size flag, matching session/doc list canon.
const docsMaxPageSize = 1000
// docsFields enumerates the fields surfaced for `--json` discovery on
// `search docs`. Mirrors sdk.Knowledge json tags.
var docsFields = []string{
@@ -35,6 +39,15 @@ type DocsSearchOptions struct {
KB string // raw --kb (UUID or name)
KBID string // resolved id; populated before listing
Limit int
// PageSize is the server batch size per ListKnowledge call (1..1000,
// default 200). Tunable so a caller searching a small KB can fetch
// everything in one round-trip, or a caller on flaky network can
// shorten the batch.
PageSize int
// AllPages walks server pages internally until total exhausted or
// --limit accumulated. Default true preserves v0.4 behavior; setting
// false stops after the first page (useful for cheap previews).
AllPages bool
}
// DocsSearchService is the narrow SDK surface this command depends on.
@@ -55,9 +68,14 @@ func NewCmdDocs(f *cmdutil.Factory) *cobra.Command {
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.`,
specific upload to download or delete by id.
By default, --all-pages=true walks every server page until --limit is
reached or the KB is exhausted (matching v0.4 behavior). Pass
--all-pages=false to stop after one page.`,
Example: ` weknora search docs "Q3 forecast" --kb finance
weknora search docs "spec" --kb engineering --limit 5`,
weknora search docs "spec" --kb engineering --limit 5
weknora search docs "spec" --kb engineering --all-pages=false`,
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
opts.Query = strings.TrimSpace(args[0])
@@ -85,19 +103,27 @@ specific upload to download or delete by id.`,
}
cmd.Flags().StringVar(&opts.KB, "kb", "", "Knowledge base UUID or name (required)")
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return")
cmd.Flags().IntVar(&opts.PageSize, "page-size", docsPageSize, "Items per server batch (1..1000)")
cmd.Flags().BoolVar(&opts.AllPages, "all-pages", true, "Walk every server page until exhausted or --limit hit")
cmdutil.AddJSONFlags(cmd, docsFields)
_ = cmd.MarkFlagRequired("kb")
return cmd
}
func runDocsSearch(ctx context.Context, opts *DocsSearchOptions, jopts *cmdutil.JSONOptions, svc DocsSearchService) error {
if opts.PageSize < 1 || opts.PageSize > docsMaxPageSize {
return cmdutil.NewError(cmdutil.CodeInputInvalidArgument,
fmt.Sprintf("--page-size must be in 1..%d, got %d", docsMaxPageSize, opts.PageSize))
}
needle := strings.ToLower(opts.Query)
var matches []sdk.Knowledge
// Page through the KB until limit matches found or pagination exhausted.
// The server returns total; stop when (page-1)*pageSize >= total.
// --all-pages=true (default) walks every server page; --all-pages=false
// stops after the first page. The server returns total; stop when
// page*pageSize >= total.
for page := 1; ; page++ {
items, total, err := svc.ListKnowledge(ctx, opts.KBID, page, docsPageSize, "")
items, total, err := svc.ListKnowledge(ctx, opts.KBID, page, opts.PageSize, "")
if err != nil {
return cmdutil.WrapHTTP(err, "list documents")
}
@@ -109,7 +135,10 @@ func runDocsSearch(ctx context.Context, opts *DocsSearchOptions, jopts *cmdutil.
}
}
}
if int64(page*docsPageSize) >= total || len(items) == 0 {
if !opts.AllPages {
break
}
if int64(page*opts.PageSize) >= total || len(items) == 0 {
break
}
}