feat(cli): top-level search command (PR-5)

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).
This commit is contained in:
nullkey
2026-05-06 14:24:11 +08:00
committed by lyingbug
parent 811802485e
commit fc5d16e331
3 changed files with 346 additions and 0 deletions
+2
View File
@@ -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
}
+153
View File
@@ -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 "<query>" --kb <id>`.
func NewCmdSearch(f *cmdutil.Factory) *cobra.Command {
opts := &Options{}
cmd := &cobra.Command{
Use: `search "<query>"`,
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")
}
+191
View File
@@ -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
}