refactor(cli): --limit/--all-pages, Go 1.26, internal/agent → aiclient

Cross-cutting cleanup that lands alongside the new feature surface:

- `--limit / -L` and `--all-pages` on every list command. Default
  --limit 30 (gh-parity); --all-pages drains every server page
  client-side, capped by --limit. Closes the audit finding that the
  old "1000 max per call" implicit cap was undiscoverable.
- `auth token` emits a TTY-only stderr advisory when stdout is a
  terminal (the credential just got displayed in scrollback) plus an
  api-key-mode rotation hint.
- Comment + doc discipline pass: drop external project name
  references from in-code comments (we reference them in design notes,
  not inline).
- Bump `go` directive to 1.26.0 and CI matrix to 1.26.x to align with
  the main module's go.mod.
- Rename `cli/internal/agent` → `cli/internal/aiclient` to
  disambiguate from the new `cli/cmd/agent` resource subtree. The
  package handles AI coding-agent env detection + per-command --help
  annotations; the new name reflects that more precisely.
This commit is contained in:
nullkey
2026-05-14 23:28:14 +08:00
committed by lyingbug
parent 9bb83b47fd
commit bdc589e1c0
59 changed files with 837 additions and 275 deletions
+2 -2
View File
@@ -7,7 +7,7 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/agent"
"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"
@@ -67,7 +67,7 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
cmd.Flags().StringVar(&opts.Description, "description", "", "Knowledge base description (optional)")
cmd.Flags().StringVar(&opts.EmbeddingModel, "embedding-model", "", "Embedding model ID (optional; server picks default when unset)")
cmdutil.AddJSONFlags(cmd, kbCreateFields)
agent.SetAgentHelp(cmd, "Creates a knowledge base under the active context. --name is required; --description and --embedding-model are optional. Returns data: full KnowledgeBase object including the new id.")
aiclient.SetAgentHelp(cmd, "Creates a knowledge base under the active context. --name is required; --description and --embedding-model are optional. Returns data: full KnowledgeBase object including the new id.")
return cmd
}
+2 -2
View File
@@ -6,7 +6,7 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/agent"
"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"
@@ -73,7 +73,7 @@ guard against unintended deletes.`,
},
}
cmdutil.AddJSONFlags(cmd, kbDeleteFields)
agent.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}.")
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
}
+2 -2
View File
@@ -6,7 +6,7 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/agent"
"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"
@@ -80,7 +80,7 @@ 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)
agent.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.")
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
}
+2 -2
View File
@@ -6,7 +6,7 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/agent"
"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"
@@ -69,7 +69,7 @@ piped contexts. Without -y the CLI exits 10 in non-interactive mode.`,
},
}
cmdutil.AddJSONFlags(cmd, kbEmptyFields)
agent.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.")
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
}
+17 -2
View File
@@ -9,7 +9,7 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/agent"
"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"
@@ -33,6 +33,10 @@ var kbListFields = []string{
// ListOptions captures `kb list` filter flag state.
type ListOptions struct {
Pinned bool // --pinned: client-side filter to KBs with IsPinned == true
// Limit caps the returned slice client-side. 0 = no cap, 1..10000 = explicit.
// The KB list SDK is unpaginated; --all-pages is intentionally not exposed
// because it would be a no-op.
Limit int
}
// ListService is the narrow SDK surface this command depends on.
@@ -65,12 +69,19 @@ 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)
agent.SetAgentHelp(cmd, "Lists all knowledge bases. Returns data.items: [{id, name, ...}]; empty array when none. --pinned restricts to pinned KBs (client-side filter). Use `--json` (bare) for the field list, `--json id,name` to project, or `--jq` for arbitrary reshape.")
aiclient.SetAgentHelp(cmd, "Lists all knowledge bases. Returns data.items: [{id, name, ...}]; empty array when none. --pinned restricts to pinned KBs (client-side filter). --limit caps the returned slice. Use `--json` (bare) for the field list, `--json id,name` to project, or `--jq` for arbitrary reshape.")
return cmd
}
func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions, svc ListService) error {
if opts.Limit < 0 || opts.Limit > 10000 {
return &cmdutil.Error{
Code: cmdutil.CodeInputInvalidArgument,
Message: fmt.Sprintf("--limit must be in 0..10000 (0 = no cap), got %d", opts.Limit),
}
}
items, err := svc.ListKnowledgeBases(ctx)
if err != nil {
return cmdutil.WrapHTTP(err, "list knowledge bases")
@@ -93,6 +104,10 @@ func runList(ctx context.Context, opts *ListOptions, jopts *cmdutil.JSONOptions,
sort.Slice(items, func(i, j int) bool {
return items[i].UpdatedAt.After(items[j].UpdatedAt)
})
// --limit applies after sort so the cap returns the top-N most-recent.
if opts.Limit > 0 && len(items) > opts.Limit {
items = items[:opts.Limit]
}
if jopts.Enabled() {
return format.WriteEnvelopeFiltered(
+57
View File
@@ -3,6 +3,8 @@ package kb
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"testing"
"time"
@@ -143,3 +145,58 @@ func TestList_PinnedFilter_NoPinned_HumanMessage(t *testing.T) {
t.Errorf("expected pinned-specific empty message, got: %q", out.String())
}
}
// makeKBs returns N KBs with distinct IDs and descending UpdatedAt.
func makeKBs(n int) []sdk.KnowledgeBase {
base := time.Now()
out := make([]sdk.KnowledgeBase, n)
for i := 0; i < n; i++ {
out[i] = sdk.KnowledgeBase{
ID: fmt.Sprintf("kb_%02d", i),
Name: fmt.Sprintf("kb-%02d", i),
UpdatedAt: base.Add(-time.Duration(i) * time.Hour),
}
}
return out
}
func TestList_Limit_CapsResults(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeListSvc{items: makeKBs(20)}
jopts := &cmdutil.JSONOptions{}
if err := runList(context.Background(), &ListOptions{Limit: 5}, jopts, svc); err != nil {
t.Fatalf("runList: %v", err)
}
got := strings.Count(out.String(), `"id":"kb_`)
if got != 5 {
t.Errorf("--limit 5 should slice 20 items to 5; got %d in:\n%s", got, out.String())
}
}
func TestList_Limit_Zero_NoCap(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeListSvc{items: makeKBs(7)}
jopts := &cmdutil.JSONOptions{}
if err := runList(context.Background(), &ListOptions{Limit: 0}, jopts, svc); err != nil {
t.Fatalf("runList: %v", err)
}
got := strings.Count(out.String(), `"id":"kb_`)
if got != 7 {
t.Errorf("--limit 0 must not cap; got %d, want 7", got)
}
}
func TestList_Limit_Negative_Rejected(t *testing.T) {
_, _ = iostreams.SetForTest(t)
err := runList(context.Background(), &ListOptions{Limit: -1}, nil, &fakeListSvc{items: makeKBs(3)})
if err == nil {
t.Fatal("expected error for negative --limit")
}
var typed *cmdutil.Error
if !errors.As(err, &typed) {
t.Fatalf("expected *cmdutil.Error, got %T: %v", err, err)
}
if typed.Code != cmdutil.CodeInputInvalidArgument {
t.Errorf("expected CodeInputInvalidArgument, got %v", typed.Code)
}
}
+2 -2
View File
@@ -6,7 +6,7 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/agent"
"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"
@@ -63,7 +63,7 @@ func newPinCmd(f *cmdutil.Factory, use string, want bool, short string) *cobra.C
},
}
cmdutil.AddJSONFlags(cmd, kbPinFields)
agent.SetAgentHelp(cmd, fmt.Sprintf("Idempotent %s: reads current pin state, toggles only if different. No-op when already in the requested state.", use))
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
}
+2 -2
View File
@@ -6,7 +6,7 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/agent"
"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"
@@ -53,7 +53,7 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
},
}
cmdutil.AddJSONFlags(cmd, kbViewFields)
agent.SetAgentHelp(cmd, "Returns details of one knowledge base by ID (config + counts).")
aiclient.SetAgentHelp(cmd, "Returns details of one knowledge base by ID (config + counts).")
return cmd
}