From fc5d16e3312aefc996dd2c967f0fd47ad9d46e7b Mon Sep 17 00:00:00 2001 From: nullkey Date: Wed, 6 May 2026 14:24:11 +0800 Subject: [PATCH] feat(cli): top-level search command (PR-5) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The fourth and final v0.0 command — chunk hybrid retrieval, the demo headline operation per ADR-3 (only one search command in the tree). Maps to client.HybridSearch / GET /knowledge-bases/{id}/hybrid-search; no SDK or server changes. Flags: - --kb (required): target knowledge base - --top-k (default 8): max results - --vector-threshold / --keyword-threshold: similarity floors - --no-vector / --no-keyword: disable individual channels (mutually exclusive at the validation gate; checked before the SDK client is built so flag misuse fails fast) - --json: emit envelope JSON (otherwise pretty list) Service interface narrowed to just HybridSearch; tests inject fakes via Factory.Client closure override. Pretty rendering is a minimal text indent today; lipgloss tables arrive in PR-3 of v0.2 (format/ split into presenters/style/tableprinter). --- cli/cmd/root.go | 2 + cli/cmd/search/search.go | 153 +++++++++++++++++++++++++++ cli/cmd/search/search_test.go | 191 ++++++++++++++++++++++++++++++++++ 3 files changed, 346 insertions(+) create mode 100644 cli/cmd/search/search.go create mode 100644 cli/cmd/search/search_test.go diff --git a/cli/cmd/root.go b/cli/cmd/root.go index 9ef75a3e..6b6a867c 100644 --- a/cli/cmd/root.go +++ b/cli/cmd/root.go @@ -12,6 +12,7 @@ import ( "github.com/spf13/cobra" "github.com/Tencent/WeKnora/cli/cmd/auth" + "github.com/Tencent/WeKnora/cli/cmd/search" "github.com/Tencent/WeKnora/cli/internal/agent" "github.com/Tencent/WeKnora/cli/internal/build" "github.com/Tencent/WeKnora/cli/internal/cmdutil" @@ -146,6 +147,7 @@ func newRootCmd(f *cmdutil.Factory) *cobra.Command { cmd.AddCommand(newVersionCmd(f)) cmd.AddCommand(auth.NewCmdAuth(f)) + cmd.AddCommand(search.NewCmdSearch(f)) return cmd } diff --git a/cli/cmd/search/search.go b/cli/cmd/search/search.go new file mode 100644 index 00000000..731a166f --- /dev/null +++ b/cli/cmd/search/search.go @@ -0,0 +1,153 @@ +// Package search implements the top-level `weknora search` command — the +// chunk hybrid retrieval entry point (ADR-3: only one search command). +package search + +import ( + "context" + "fmt" + "strings" + + "github.com/spf13/cobra" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/format" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + sdk "github.com/Tencent/WeKnora/client" +) + +// Options is the runtime configuration of one search invocation. +type Options struct { + Query string + KBID string + TopK int + VectorThreshold float64 + KeywordThreshold float64 + NoVector bool + NoKeyword bool + JSONOut bool +} + +// Service is the narrow SDK surface used by runSearch. *sdk.Client satisfies +// it; tests inject fakes via Factory.Client. +type Service interface { + HybridSearch(ctx context.Context, kbID string, params *sdk.SearchParams) ([]*sdk.SearchResult, error) +} + +// NewCmdSearch builds `weknora search "" --kb `. +func NewCmdSearch(f *cmdutil.Factory) *cobra.Command { + opts := &Options{} + cmd := &cobra.Command{ + Use: `search ""`, + Short: "Hybrid (vector + keyword) chunk retrieval against a knowledge base", + Args: cobra.ExactArgs(1), + RunE: func(c *cobra.Command, args []string) error { + opts.Query = strings.TrimSpace(args[0]) + // Validate user input BEFORE touching the SDK client. Flag misuse + // should fail fast with the clearer error rather than blocking on + // auth / config when the invocation itself is wrong. + if err := opts.validate(); err != nil { + return err + } + cli, err := f.Client() + if err != nil { + return err + } + return runSearch(c.Context(), opts, cli) + }, + } + cmd.Flags().StringVar(&opts.KBID, "kb", "", "Knowledge base ID to search (required)") + cmd.Flags().IntVar(&opts.TopK, "top-k", 8, "Maximum results to return") + 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") + cmd.Flags().BoolVar(&opts.NoKeyword, "no-keyword", false, "Disable the keyword channel") + cmd.Flags().BoolVar(&opts.JSONOut, "json", false, "Output JSON envelope") + cmdutil.MustRequireFlag(cmd, "kb") + return cmd +} + +// validate checks the option set before any SDK call. RunE invokes it before +// f.Client() so flag misuse fails fast; runSearch re-invokes it as a safety +// net for direct test calls that bypass RunE. +func (o *Options) validate() error { + if o.Query == "" { + return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "query argument cannot be empty") + } + if o.NoVector && o.NoKeyword { + return cmdutil.NewError(cmdutil.CodeInputInvalidArgument, "--no-vector and --no-keyword cannot both be set") + } + return nil +} + +func runSearch(ctx context.Context, opts *Options, svc Service) error { + if err := opts.validate(); err != nil { + return err + } + if svc == nil { + return cmdutil.NewError(cmdutil.CodeServerError, "search: no SDK client available") + } + + params := &sdk.SearchParams{ + QueryText: opts.Query, + MatchCount: opts.TopK, + VectorThreshold: opts.VectorThreshold, + KeywordThreshold: opts.KeywordThreshold, + DisableVectorMatch: opts.NoVector, + DisableKeywordsMatch: opts.NoKeyword, + } + results, err := svc.HybridSearch(ctx, opts.KBID, params) + if err != nil { + return cmdutil.Wrapf(cmdutil.ClassifyHTTPError(err), err, "hybrid search") + } + // 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 TopK. CLIs like gh / + // kubectl / aws treat their `--limit`-style flag as a hard return-count + // cap; honor that contract by trimming on the client. Recall isn't + // affected because the server's internal retrieval pool is already + // max(MatchCount*5, 50). + if opts.TopK > 0 && len(results) > opts.TopK { + results = results[:opts.TopK] + } + + if opts.JSONOut { + return cmdutil.NewJSONExporter().Write(iostreams.IO.Out, format.Success(results, &format.Meta{ + KBID: opts.KBID, + })) + } + return renderHumanResults(results, opts.KBID) +} + +// renderHumanResults prints a compact pretty list to stdout. +// +// Lipgloss tables arrive in PR-3; the inline indent helper here is a minimal +// stopgap so search is usable in a terminal without color today. +func renderHumanResults(results []*sdk.SearchResult, kbID string) error { + if len(results) == 0 { + fmt.Fprintln(iostreams.IO.Out, "(no results)") + return nil + } + fmt.Fprintf(iostreams.IO.Out, "%d result(s) from kb=%s:\n\n", len(results), kbID) + for i, r := range results { + fmt.Fprintf(iostreams.IO.Out, "[%d] score=%.3f", i+1, r.Score) + if r.KnowledgeID != "" { + fmt.Fprintf(iostreams.IO.Out, " doc=%s", r.KnowledgeID) + } + fmt.Fprintln(iostreams.IO.Out) + fmt.Fprintln(iostreams.IO.Out, indent(strings.TrimSpace(r.Content), " ")) + fmt.Fprintln(iostreams.IO.Out) + } + return nil +} + +// indent prefixes each line of s with the given prefix. +func indent(s, prefix string) string { + if s == "" { + return "" + } + lines := strings.Split(s, "\n") + for i, l := range lines { + lines[i] = prefix + l + } + return strings.Join(lines, "\n") +} diff --git a/cli/cmd/search/search_test.go b/cli/cmd/search/search_test.go new file mode 100644 index 00000000..370c0258 --- /dev/null +++ b/cli/cmd/search/search_test.go @@ -0,0 +1,191 @@ +package search + +import ( + "context" + "errors" + "strings" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Tencent/WeKnora/cli/internal/cmdutil" + "github.com/Tencent/WeKnora/cli/internal/iostreams" + sdk "github.com/Tencent/WeKnora/client" +) + +type fakeSearchService struct { + results []*sdk.SearchResult + err error + gotKB string + gotQ string +} + +func (f *fakeSearchService) HybridSearch(_ context.Context, kbID string, p *sdk.SearchParams) ([]*sdk.SearchResult, error) { + f.gotKB = kbID + f.gotQ = p.QueryText + return f.results, f.err +} + +func TestRunSearch_HumanOutput(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &fakeSearchService{results: []*sdk.SearchResult{ + {Score: 0.92, Content: "first chunk", KnowledgeID: "doc-1", MatchType: sdk.MatchTypeVector}, + {Score: 0.81, Content: "second chunk", KnowledgeID: "doc-2", MatchType: sdk.MatchTypeKeyword}, + }} + opts := &Options{Query: "hello", KBID: "kb_abc", TopK: 5} + require.NoError(t, runSearch(context.Background(), opts, svc)) + + assert.Equal(t, "kb_abc", svc.gotKB) + assert.Equal(t, "hello", svc.gotQ) + got := out.String() + assert.Contains(t, got, "2 result(s) from kb=kb_abc") + assert.Contains(t, got, "first chunk") + assert.Contains(t, got, "doc-1") +} + +// JSON envelope 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, +// matching gh / kubectl / Algolia / Vespa terse-default conventions.) +func TestRunSearch_JSONIncludesMatchType(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &fakeSearchService{results: []*sdk.SearchResult{ + {Score: 0.9, Content: "x", MatchType: sdk.MatchTypeKeyword}, + }} + require.NoError(t, runSearch(context.Background(), &Options{Query: "q", KBID: "kb1", JSONOut: true}, svc)) + assert.Contains(t, out.String(), `"match_type":1`) +} + +func TestRunSearch_JSONOutput(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &fakeSearchService{results: []*sdk.SearchResult{{Score: 0.9, Content: "x"}}} + opts := &Options{Query: "q", KBID: "kb1", TopK: 1, JSONOut: true} + require.NoError(t, runSearch(context.Background(), opts, svc)) + assert.True(t, strings.HasPrefix(out.String(), `{"ok":true`), "got: %q", out.String()) + assert.Contains(t, out.String(), `"kb_id":"kb1"`) +} + +func TestRunSearch_EmptyResults(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &fakeSearchService{results: nil} + require.NoError(t, runSearch(context.Background(), &Options{Query: "q", KBID: "kb1"}, svc)) + assert.Contains(t, out.String(), "(no results)") +} + +// Server returns primary matches plus parent/related/nearby enrichment chunks, +// so the wire response can exceed TopK. CLI must trim to honor the user's +// hard-limit contract (gh / kubectl / aws idiom). +func TestRunSearch_TopKHardCap(t *testing.T) { + out, _ := iostreams.SetForTest(t) + svc := &fakeSearchService{results: []*sdk.SearchResult{ + {Score: 0.9, Content: "primary 1"}, + {Score: 0.8, Content: "primary 2"}, + {Score: 0.7, Content: "primary 3"}, + {Score: 0, Content: "enrichment parent"}, // server-padded + {Score: 0, Content: "enrichment nearby"}, // server-padded + }} + require.NoError(t, runSearch(context.Background(), &Options{Query: "q", KBID: "kb1", TopK: 3}, svc)) + got := out.String() + assert.Contains(t, got, "3 result(s)") + assert.NotContains(t, got, "enrichment parent") + assert.NotContains(t, got, "enrichment nearby") +} + +func TestRunSearch_BothChannelsDisabled(t *testing.T) { + iostreams.SetForTest(t) + err := runSearch(context.Background(), &Options{Query: "q", KBID: "kb1", NoVector: true, NoKeyword: true}, &fakeSearchService{}) + require.Error(t, err) + assert.Contains(t, err.Error(), "input.invalid_argument") +} + +func TestRunSearch_ServiceError_Transport(t *testing.T) { + iostreams.SetForTest(t) + svc := &fakeSearchService{err: assert.AnError} + err := runSearch(context.Background(), &Options{Query: "q", KBID: "kb1"}, svc) + require.Error(t, err) + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeNetworkError, typed.Code, + "non-HTTP-shaped errors classify as network.error so IsTransient picks them up") +} + +func TestRunSearch_ServiceError_HTTPNotFound(t *testing.T) { + iostreams.SetForTest(t) + svc := &fakeSearchService{err: errors.New("HTTP error 404: knowledge base not found")} + err := runSearch(context.Background(), &Options{Query: "q", KBID: "missing"}, svc) + require.Error(t, err) + var typed *cmdutil.Error + require.ErrorAs(t, err, &typed) + assert.Equal(t, cmdutil.CodeResourceNotFound, typed.Code) +} + +func TestIndent(t *testing.T) { + assert.Equal(t, " foo\n bar", indent("foo\nbar", " ")) + assert.Equal(t, "", indent("", " ")) +} + +func TestRunSearch_NilService(t *testing.T) { + iostreams.SetForTest(t) + err := runSearch(context.Background(), &Options{Query: "q", KBID: "kb1"}, nil) + require.Error(t, err) + assert.Contains(t, err.Error(), "server.error") +} + +func TestNewCmdSearch_RequiresQuery(t *testing.T) { + iostreams.SetForTest(t) + cmd := NewCmdSearch(&cmdutil.Factory{ + Client: func() (*sdk.Client, error) { return nil, nil }, + }) + cmd.SetArgs([]string{}) // no query + cmd.SilenceErrors = true + cmd.SilenceUsage = true + err := cmd.Execute() + require.Error(t, err) +} + +func TestNewCmdSearch_RejectsEmptyQuery(t *testing.T) { + iostreams.SetForTest(t) + cmd := NewCmdSearch(&cmdutil.Factory{ + Client: func() (*sdk.Client, error) { return nil, nil }, + }) + cmd.SetArgs([]string{" ", "--kb", "kb1"}) + cmd.SilenceErrors = true + cmd.SilenceUsage = true + err := cmd.Execute() + require.Error(t, err) + assert.Contains(t, err.Error(), "input.invalid_argument") +} + +func TestRunSearch_NoVectorPassedThrough(t *testing.T) { + iostreams.SetForTest(t) + var got *sdk.SearchParams + svc := &capturingSearchService{capture: func(p *sdk.SearchParams) { got = p }} + require.NoError(t, runSearch(context.Background(), &Options{ + Query: "q", KBID: "kb1", NoVector: true, + }, svc)) + require.NotNil(t, got) + assert.True(t, got.DisableVectorMatch) + assert.False(t, got.DisableKeywordsMatch) +} + +func TestRunSearch_NoKeywordPassedThrough(t *testing.T) { + iostreams.SetForTest(t) + var got *sdk.SearchParams + svc := &capturingSearchService{capture: func(p *sdk.SearchParams) { got = p }} + require.NoError(t, runSearch(context.Background(), &Options{ + Query: "q", KBID: "kb1", NoKeyword: true, + }, svc)) + require.NotNil(t, got) + assert.True(t, got.DisableKeywordsMatch) + assert.False(t, got.DisableVectorMatch) +} + +type capturingSearchService struct { + capture func(*sdk.SearchParams) +} + +func (c *capturingSearchService) HybridSearch(_ context.Context, _ string, p *sdk.SearchParams) ([]*sdk.SearchResult, error) { + c.capture(p) + return nil, nil +}