refactor(cli): drop aiclient package; align AGENTS.md with mainstream

Survey of 10 mainstream CLIs (gh, lark, stripe, vercel, supabase, aws,
azure, gcloud, openai/codex, github-copilot-cli) showed env-gated
per-command --help blurbs are a Stripe-only pattern; gh uses env detect
for telemetry only, and lark relies on installed agent Skills + MCP.
Our cmd/mcp/serve already covers the dominant 2025/26 path, so
internal/aiclient/ (136 LOC + 38 callsites) is net maintenance burden
without precedent.

- Drop internal/aiclient/ entirely (annotations + detect + tests)
- Remove 38 SetAgentHelp callsites + agentAwareHelpFunc / SetHelpFunc
  wiring in cmd/root.go
- Migrate 4 command-level rules to standard Long help (visible to all,
  not env-gated): doc upload mode mutex, kb edit at-least-one,
  kb pin idempotent, search chunks channel mutex
- Rewrite AGENTS.md as a developer guide (gh-style 6 H2 / 167 lines):
  audience preamble + Build / Architecture / Command Structure /
  Testing / Code Style / Error Handling. Drops sections absent in
  surveyed projects (Commit & PR Conventions, Who Uses This CLI)
- Clean 14 internal doc refs (ADR-N, spec §X, v0.X) in source comments
  and docs that pointed at docs/superpowers/ — that directory is
  local-only / uncommitted, so refs are dead for outside readers
- Drop forward-looking "once v0.2 ships" from README
This commit is contained in:
nullkey
2026-05-15 02:16:45 +08:00
committed by lyingbug
parent a0dd989c81
commit f2e8e3f56c
111 changed files with 575 additions and 908 deletions
+7 -6
View File
@@ -7,7 +7,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
sdk "github.com/Tencent/WeKnora/client"
@@ -44,7 +43,7 @@ type ChunksService interface {
// Uses a positional query argument with the KB selected via flag.
//
// The `--kb` flag accepts either a KB UUID (passed through unchanged) or a
// name (resolved via ListKnowledgeBases — see cmdutil.ResolveKBFlag).
// name (resolved via ListKnowledgeBases - see cmdutil.ResolveKBFlag).
func NewCmdChunks(f *cmdutil.Factory) *cobra.Command {
opts := &ChunksOptions{}
cmd := &cobra.Command{
@@ -53,6 +52,9 @@ func NewCmdChunks(f *cmdutil.Factory) *cobra.Command {
Example: ` weknora search chunks "what is RAG?" --kb engineering
weknora search chunks "embedding model" --kb kb_abc --limit 20
weknora search chunks "k8s" --kb engineering --no-keyword # vector-only`,
Long: `Hybrid (vector + keyword) retrieval against the knowledge base. Pass
--no-vector or --no-keyword to disable one channel; you cannot disable both.
--limit caps the returned slice client-side.`,
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
opts.Query = strings.TrimSpace(args[0])
@@ -80,7 +82,6 @@ func NewCmdChunks(f *cmdutil.Factory) *cobra.Command {
}
bindChunksFlags(cmd, opts)
_ = cmd.MarkFlagRequired("kb")
aiclient.SetAgentHelp(cmd, "Hybrid retrieval; returns ranked chunk list. The server may include parent/nearby/relation chunks beyond match_count; --limit caps the returned slice client-side. Pass --no-vector or --no-keyword to disable a channel (mutually exclusive both-off).")
return cmd
}
@@ -88,7 +89,7 @@ func NewCmdChunks(f *cmdutil.Factory) *cobra.Command {
// the constructor readable; --kb is marked required by the caller.
func bindChunksFlags(cmd *cobra.Command, opts *ChunksOptions) {
cmd.Flags().StringVar(&opts.KB, "kb", "", "Knowledge base UUID or name")
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 8, "Maximum results to return (default 8 — tuned for RAG context window; list commands default to 30)")
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 8, "Maximum results to return (default 8 - tuned for RAG context window; list commands default to 30)")
cmd.Flags().Float64Var(&opts.VectorThreshold, "vector-threshold", 0, "Vector retrieval similarity floor (per-channel, pre-fusion); 0 = no filter")
cmd.Flags().Float64Var(&opts.KeywordThreshold, "keyword-threshold", 0, "Keyword retrieval score floor (per-channel, pre-fusion); 0 = no filter")
cmd.Flags().BoolVar(&opts.NoVector, "no-vector", false, "Disable the vector channel")
@@ -129,7 +130,7 @@ func runChunks(ctx context.Context, opts *ChunksOptions, jopts *cmdutil.JSONOpti
if err != nil {
return cmdutil.WrapHTTP(err, "hybrid search")
}
// match_count is the server's *primary-match* cap — after that, the
// match_count is the server's *primary-match* cap - after that, the
// service appends parent / nearby / relation chunks as context
// enrichment, so the wire response can exceed Limit. Treat --limit as
// a hard return-count cap by trimming on the client. Recall isn't
@@ -148,7 +149,7 @@ func runChunks(ctx context.Context, opts *ChunksOptions, jopts *cmdutil.JSONOpti
return renderChunkResults(results, opts.KBID)
}
// renderChunkResults prints a compact pretty list. Minimal stopgap — a
// renderChunkResults prints a compact pretty list. Minimal stopgap - a
// richer tabular renderer can replace this later without breaking the
// JSON contract.
func renderChunkResults(results []*sdk.SearchResult, kbID string) error {
+1 -1
View File
@@ -46,7 +46,7 @@ func TestRunSearch_HumanOutput(t *testing.T) {
// JSON output must surface match_type so machine consumers / agents can
// reason about retrieval channels without re-implementing the wire format.
// (Human renderer keeps default minimal — diagnostic info opt-in via --json.)
// (Human renderer keeps default minimal - diagnostic info opt-in via --json.)
func TestRunSearch_JSONIncludesMatchType(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeChunksSvc{results: []*sdk.SearchResult{
+3 -2
View File
@@ -9,7 +9,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/text"
@@ -54,6 +53,9 @@ func NewCmdDocs(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: `docs "<query>"`,
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.`,
Example: ` weknora search docs "Q3 forecast" --kb finance
weknora search docs "spec" --kb engineering --limit 5`,
Args: cobra.ExactArgs(1),
@@ -85,7 +87,6 @@ func NewCmdDocs(f *cmdutil.Factory) *cobra.Command {
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return")
cmdutil.AddJSONFlags(cmd, docsFields)
_ = cmd.MarkFlagRequired("kb")
aiclient.SetAgentHelp(cmd, "Lists documents in --kb whose title or file_name contains the query. Pages through the KB sequentially; stops once limit hits found. Returns the full Knowledge object so agents can derive id / file_size / processed_at without a second call.")
return cmd
}
+7 -3
View File
@@ -9,7 +9,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/text"
@@ -39,7 +38,7 @@ type KBSearchService interface {
ListKnowledgeBases(ctx context.Context) ([]sdk.KnowledgeBase, error)
}
// NewCmdKB builds `weknora search kb "<query>"` — substring + case-insensitive
// NewCmdKB builds `weknora search kb "<query>"` - substring + case-insensitive
// match across KB names and descriptions visible to the active context.
// Results are sorted by name length (shortest first; usually the closest
// hit) for deterministic output.
@@ -48,6 +47,12 @@ func NewCmdKB(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: `kb "<query>"`,
Short: "Find knowledge bases by name or description (client-side substring match)",
Long: `Substring + case-insensitive match across KB names and descriptions visible
to the active context. Results are sorted by name length (shortest first;
usually the closest hit) for deterministic output.
This is name-discovery only - for searching *inside* a knowledge base's
content, use ` + "`weknora search chunks`" + `.`,
Example: ` weknora search kb "marketing"
weknora search kb "team" --limit 5 --json`,
Args: cobra.ExactArgs(1),
@@ -72,7 +77,6 @@ func NewCmdKB(f *cmdutil.Factory) *cobra.Command {
}
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return")
cmdutil.AddJSONFlags(cmd, kbSearchFields)
aiclient.SetAgentHelp(cmd, "Lists KBs whose name or description contains the query (case-insensitive). Useful to discover --kb identifiers before running search chunks / doc list.")
return cmd
}
+1 -3
View File
@@ -5,12 +5,11 @@ package search
import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
)
// NewCmdSearch builds the `weknora search` parent. Pure dispatcher to the
// four subcommands — users must pick a verb (chunks / kb / docs / sessions).
// four subcommands - users must pick a verb (chunks / kb / docs / sessions).
func NewCmdSearch(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: "search",
@@ -28,7 +27,6 @@ func NewCmdSearch(f *cmdutil.Factory) *cobra.Command {
Args: cobra.NoArgs,
Run: func(c *cobra.Command, _ []string) { _ = c.Help() },
}
aiclient.SetAgentHelp(cmd, "Search parent. Use `search chunks/kb/docs/sessions <q>` — there is no bare-positional form.")
cmd.AddCommand(NewCmdChunks(f))
cmd.AddCommand(NewCmdKB(f))
+2 -3
View File
@@ -20,9 +20,8 @@ func TestSearch_NoArgs_ShowsHelp(t *testing.T) {
require.NoError(t, cmd.Execute())
}
// TestSearch_RejectsPositional: bare positional (e.g. the v0.0-style
// `weknora search "<q>" --kb X`) must error — the legacy alias was
// dropped, search is now pure dispatcher.
// TestSearch_RejectsPositional: bare positional `weknora search "<q>" --kb X`
// must error - search is a pure dispatcher with no shortcut form.
func TestSearch_RejectsPositional(t *testing.T) {
_, _ = iostreams.SetForTest(t)
cmd := NewCmdSearch(&cmdutil.Factory{})
+1 -3
View File
@@ -9,7 +9,6 @@ import (
"github.com/spf13/cobra"
"github.com/Tencent/WeKnora/cli/internal/aiclient"
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/text"
@@ -67,7 +66,6 @@ func NewCmdSessions(f *cmdutil.Factory) *cobra.Command {
}
cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return")
cmdutil.AddJSONFlags(cmd, sessionsSearchFields)
aiclient.SetAgentHelp(cmd, "Lists chat sessions whose title or description contains the query. Pages through the tenant sequentially; stops once limit matches found. Returns full Session objects so agents can pivot to session view/delete by id.")
return cmd
}
@@ -124,7 +122,7 @@ func matchSession(s sdk.Session, needle string) bool {
}
// sortSessionsByRecency sorts in place by UpdatedAt desc. Server returns
// strings; we compare lexically — RFC3339 timestamps sort correctly that
// strings; we compare lexically - RFC3339 timestamps sort correctly that
// way, and a stable order is enough for output determinism even if a
// non-conforming string slips through.
func sortSessionsByRecency(items []sdk.Session) {