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:
@@ -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 {
|
||||
|
||||
@@ -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{
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -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))
|
||||
|
||||
@@ -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{})
|
||||
|
||||
@@ -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) {
|
||||
|
||||
Reference in New Issue
Block a user