feat(cli)!: v0.10 reliability, agent-UX, and command-surface hardening

A hardening + finalization pass over the agent-first CLI: correctness fixes,
richer machine-readable signals, flag/naming consistency, and a symmetric
config surface. Pre-1.0, so it includes breaking renames.

Correctness:
- agent update: resolve/validate --model/--rerank-model (was storing a bogus
  name verbatim, corrupting config.model_id).
- doctor: honor WEKNORA_HOST / WEKNORA_API_KEY (headless path no longer reports
  "no host configured").
- session ask / MCP session_ask: text answer was empty on non-TTY — the agent
  stream sets Done=true on an intermediate agent_query frame before the answer,
  and AgentAccumulator treated the first Done as terminal. Terminate on the
  `complete` event (new sdk.AgentResponseTypeComplete), not a per-frame Done.
- batch exit codes: any per-item failure collapses to operation.failed (exit 1),
  including `doc upload --recursive` partial failures — a permanent per-file
  failure (e.g. a duplicate) no longer surfaces as a retryable exit 7 an agent
  would loop on; per-item typed errors stay in the envelope.

Agent-first signals & discovery:
- error.exit_code in the envelope (type + exit_code disambiguate the
  input.invalid_argument exit-2-vs-5 split in one JSON read).
- meta.hint on empty content search and on draft doc create; doc wait fails fast
  on a never-parsing draft instead of hanging to --timeout.
- retrieval-readiness is visible in the natural flow: kb status / kb check emit
  retrieval_ready, and kb create hints the fix when no embedding model is bound
  — an unconfigured KB no longer looks silently healthy.
- schema contract completeness: every leaf declares output + >=1 example
  (drift-guarded); output strings match the meta actually emitted; chunk list
  and search docs now emit meta.total_count (both previously dropped it).
- schema tolerates a quoted multi-word command label; zero-state auth — and
  `link` with no profile — point at profile setup / the headless WEKNORA_KB_ID
  path instead of looping on `auth login`.
- id-addressed reads tolerate a redundant --kb (doc view/wait, chunk list/view
  accept and ignore it, declared in schema) so a carried-over --kb doesn't
  exit 2; streaming commands warn that --jq does not apply to an NDJSON stream.
- keep JSON-always as the default; --jq hints spell out the .data path.

Consistency & gating:
- doc create: drop the deprecated --name alias (--title only; pre-1.0 break).
- chunk list --limit aligned to 1..10000; model list --limit/-L with
  has_more/total_count; api write-gates -X PUT/PATCH (exit 10); skills install
  expands a leading ~.
- docs corrected: search docs / doc list --keyword help is case-insensitive
  (server does LOWER LIKE); AGENTS.md risk-action list (no phantom kb.init; add
  model.update / kb.config.set) and batch example (failed item carries `error`);
  session resume --message id comes from `message list`, not the stream.
- auth/profile ergonomics: env credentials are now first-class — `auth token`
  prints the active WEKNORA_API_KEY / WEKNORA_TOKEN, and auth login/logout/refresh
  give an env-aware message instead of looping on "run auth login". `auth logout`
  clears credentials but keeps the profile registered (host preserved for
  re-login); deleting a profile is `profile remove`'s job (clean logout/remove
  separation, matching gh / lark).

Config surface (symmetric read/write, in-place model edits):
- kb config now returns a secret-free KBModelConfigView (was {}); `kb config`
  reads, new `kb config set` writes; `kb init` removed (misnomer).
- kb create --chat-model: retrieval-ready in one step.
- model update: edit a model in place (id preserved, references survive) —
  rotate --api-key-stdin, change base-url / display-name / etc.
- session continue-stream renamed to session resume.

Docs: AGENTS.md is the single wire-contract source; CHANGELOG slimmed; stale
kb-init / continue-stream references removed; skill wire-vocab guard extended.
AGENTS.md / weknora-shared SKILL document retrieval_ready (a KB needs an
embedding model to be searchable), that --jq does not apply to NDJSON
streams, and the env-credential-first auth path; the KB quickstart example
now creates a retrieval-ready KB.
This commit is contained in:
nullkey
2026-07-02 15:53:51 +08:00
committed by lyingbug
parent 040a734766
commit d3c03b2f34
95 changed files with 1711 additions and 436 deletions
+15 -9
View File
@@ -17,13 +17,17 @@ import (
// aggregated by paging the doc list. Verb split with `kb status`:
// status reads existing state cheaply, check actively verifies.
type CheckResult struct {
ID string `json:"id"`
Reachable bool `json:"reachable"`
KnowledgeCount int64 `json:"knowledge_count,omitempty"`
ChunkCount int64 `json:"chunk_count,omitempty"`
IsProcessing bool `json:"is_processing,omitempty"`
ProcessingCount int64 `json:"processing_count,omitempty"`
FailedCount int64 `json:"failed_count"` // always populated (no omitempty)
ID string `json:"id"`
Reachable bool `json:"reachable"`
// RetrievalReady is false when no embedding model is bound — the KB can never
// index/retrieve regardless of failed_count. Always emitted (no omitempty) so
// an unconfigured KB is not reported as silently healthy.
RetrievalReady bool `json:"retrieval_ready"`
KnowledgeCount int64 `json:"knowledge_count,omitempty"`
ChunkCount int64 `json:"chunk_count,omitempty"`
IsProcessing bool `json:"is_processing,omitempty"`
ProcessingCount int64 `json:"processing_count,omitempty"`
FailedCount int64 `json:"failed_count"` // always populated (no omitempty)
}
// CheckService is the narrow SDK surface needed for kb check.
@@ -33,7 +37,7 @@ type CheckService interface {
}
var kbCheckFields = []string{
"id", "reachable", "knowledge_count", "chunk_count",
"id", "reachable", "retrieval_ready", "knowledge_count", "chunk_count",
"is_processing", "processing_count", "failed_count",
}
@@ -76,7 +80,7 @@ verification including failed-doc aggregation.`,
UsedFor: "verify a knowledge base end-to-end: status plus failed-doc aggregation",
RequiredFlags: []string{"<kb-id> (positional)"},
Examples: []string{"weknora kb check kb_abc"},
Output: "envelope.data is {id, reachable, failed_count, ...}; deeper than `kb status`",
Output: "envelope.data is {id, reachable, retrieval_ready, failed_count, ...}; retrieval_ready=false means no embedding model is bound (run `kb config set`); deeper than `kb status`",
})
return cmd
}
@@ -92,6 +96,7 @@ func runCheck(ctx context.Context, svc CheckService, id string) (*CheckResult, e
res := &CheckResult{
ID: kb.ID,
Reachable: true,
RetrievalReady: kb.EmbeddingModelID != "",
KnowledgeCount: kb.KnowledgeCount,
ChunkCount: kb.ChunkCount,
IsProcessing: kb.IsProcessing,
@@ -144,6 +149,7 @@ func writeCheckText(w io.Writer, res *CheckResult) error {
if !res.Reachable {
return nil
}
fmt.Fprintf(w, "Retrieval: %v%s\n", res.RetrievalReady, retrievalHint(res.RetrievalReady))
fmt.Fprintf(w, "Knowledge: %d\n", res.KnowledgeCount)
fmt.Fprintf(w, "Chunks: %d\n", res.ChunkCount)
fmt.Fprintf(w, "Processing: %v (%d active)\n", res.IsProcessing, res.ProcessingCount)
+4 -1
View File
@@ -39,7 +39,7 @@ func (f *fakeCheckSvc) ListKnowledgeWithFilter(_ context.Context, _ string, page
func TestRunCheck_AggregatesFailed(t *testing.T) {
svc := &fakeCheckSvc{
kb: &sdk.KnowledgeBase{ID: "kb_x", KnowledgeCount: 5, ChunkCount: 20},
kb: &sdk.KnowledgeBase{ID: "kb_x", KnowledgeCount: 5, ChunkCount: 20, EmbeddingModelID: "emb_1"},
failedDocs: []sdk.Knowledge{
{ID: "d1", ParseStatus: "failed"},
{ID: "d2", ParseStatus: "failed"},
@@ -55,6 +55,9 @@ func TestRunCheck_AggregatesFailed(t *testing.T) {
if !res.Reachable {
t.Error("Reachable=false, want true")
}
if !res.RetrievalReady {
t.Error("RetrievalReady=false, want true when an embedding model is bound")
}
if res.KnowledgeCount != 5 || res.ChunkCount != 20 {
t.Errorf("got %+v", res)
}
+42 -20
View File
@@ -12,25 +12,26 @@ import (
)
// kbConfigFields enumerates the fields surfaced for `--format json` discovery on
// `kb config`. Mirrors client.InitializationConfig.
// `kb config`. Mirrors client.KBModelConfigView (secret-free — no api keys).
var kbConfigFields = []string{
"chat_model_id", "embedding_model_id", "rerank_model_id", "multimodal_id",
"retrieval_ready", "embedding", "llm", "rerank", "multimodal",
}
// ConfigService is the narrow SDK surface this command depends on.
type ConfigService interface {
GetInitializationConfig(ctx context.Context, kbID string) (*sdk.InitializationConfig, error)
GetInitializationConfig(ctx context.Context, kbID string) (*sdk.KBModelConfigView, error)
}
// NewCmdConfig builds `weknora kb config <kb-id>` — read-only inspection of a
// knowledge base's model configuration (set it with `weknora kb init`).
// knowledge base's model configuration. Write it with `weknora kb config set`.
func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
cmd := &cobra.Command{
Use: "config <kb-id>",
Short: "Show a knowledge base's model configuration",
Long: `Show the model configuration bound to a knowledge base: chat, embedding,
rerank, and multimodal model ids. An empty embedding_model_id means the KB is
not yet usable for retrieval — configure it with 'weknora kb init'.`,
Short: "Show a knowledge base's model configuration (set it with `config set`)",
Long: `Show the model configuration bound to a knowledge base: embedding, llm
(chat), rerank, and multimodal model names + source. retrieval_ready is false
until an embedding model is bound — configure it with 'weknora kb config set'.
Provider API keys are never shown.`,
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
fopts, err := cmdutil.CheckFormatFlag(c)
@@ -45,12 +46,15 @@ not yet usable for retrieval — configure it with 'weknora kb init'.`,
return runConfig(c.Context(), fopts, cli, args[0])
},
}
// `kb config` reads (this command's RunE); `kb config set` writes. Same
// read/write pairing as mainstream config surfaces.
cmd.AddCommand(newKBModelWriteCmd(f, "set <kb-id>", []string{"weknora", "kb", "config", "set"}))
cmdutil.AddFormatFlag(cmd, kbConfigFields...)
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: "show a KB's model config (chat/embedding/rerank/multimodal model ids). Empty embedding_model_id => not retrieval-ready; run `weknora kb init`.",
UsedFor: "show a KB's model config (embedding/llm/rerank/multimodal by name, secret-free). retrieval_ready=false => run `weknora kb config set`. Write config with `weknora kb config set`.",
RequiredFlags: []string{"<kb-id> (positional)"},
Examples: []string{"weknora kb config kb_abc --jq .data.embedding_model_id"},
Output: "envelope.data is {chat_model_id, embedding_model_id, rerank_model_id, multimodal_id}",
Output: "envelope.data is {retrieval_ready, embedding{configured,model_name,source,dimension}, llm{...}, rerank{enabled,model_name}, multimodal{enabled}} — secret-free (no provider api keys)",
})
return cmd
}
@@ -61,27 +65,45 @@ func runConfig(ctx context.Context, fopts *cmdutil.FormatOptions, svc ConfigServ
return cmdutil.WrapHTTP(err, "get config for knowledge base %q", kbID)
}
if cfg == nil {
cfg = &sdk.InitializationConfig{}
cfg = &sdk.KBModelConfigView{}
}
if fopts.WantsJSON() {
return fopts.Emit(iostreams.IO.Out, cfg, nil)
}
w := iostreams.IO.Out
fmt.Fprintf(w, "%-11s %s\n", "EMBEDDING:", orNone(cfg.EmbeddingModelID))
fmt.Fprintf(w, "%-11s %s\n", "CHAT:", orNone(cfg.ChatModelID))
fmt.Fprintf(w, "%-11s %s\n", "RERANK:", orNone(cfg.RerankModelID))
fmt.Fprintf(w, "%-11s %s\n", "MULTIMODAL:", orNone(cfg.MultimodalID))
if cfg.EmbeddingModelID == "" {
fmt.Fprintln(w, "\n(no embedding model set — run `weknora kb init <kb-id> --embedding-model <id>`)")
fmt.Fprintf(w, "%-13s %v\n", "RETRIEVAL:", readyLabel(cfg.RetrievalReady))
fmt.Fprintf(w, "%-13s %s\n", "EMBEDDING:", slotLabel(cfg.Embedding))
fmt.Fprintf(w, "%-13s %s\n", "CHAT (LLM):", slotLabel(cfg.LLM))
fmt.Fprintf(w, "%-13s %s\n", "RERANK:", rerankLabel(cfg.Rerank))
fmt.Fprintf(w, "%-13s %v\n", "MULTIMODAL:", cfg.Multimodal.Enabled)
if !cfg.RetrievalReady {
fmt.Fprintln(w, "\n(not retrieval-ready — no embedding model; run `weknora kb config set <kb-id> --chat-model <id> --embedding-model <id>`)")
}
return nil
}
func orNone(s string) string {
if s == "" {
func readyLabel(ready bool) string {
if ready {
return "ready"
}
return "NOT ready (no embedding model)"
}
func slotLabel(s sdk.ModelSlotView) string {
if !s.Configured {
return "(unset)"
}
return s
if s.Source != "" {
return fmt.Sprintf("%s (%s)", s.ModelName, s.Source)
}
return s.ModelName
}
func rerankLabel(r sdk.RerankSlotView) string {
if !r.Enabled {
return "(disabled)"
}
return r.ModelName
}
// compile-time check: the production SDK client implements ConfigService.
+48 -40
View File
@@ -12,43 +12,40 @@ import (
sdk "github.com/Tencent/WeKnora/client"
)
// kbInitFields enumerates the fields surfaced for `--format json` discovery on
// `kb init`. The result is the resulting InitializationConfig (read back).
var kbInitFields = []string{
"chat_model_id", "embedding_model_id", "rerank_model_id", "multimodal_id",
}
type InitOptions struct {
type ConfigSetOptions struct {
ChatModel string
EmbeddingModel string
Yes bool
DryRun bool
}
// InitService is the narrow SDK surface this command depends on. SetKBModelConfig
// ConfigSetService is the narrow SDK surface this command depends on. SetKBModelConfig
// points the KB at already-registered models; GetInitializationConfig re-reads
// the server's resulting state so the success envelope reflects what stuck.
type InitService interface {
type ConfigSetService interface {
SetKBModelConfig(ctx context.Context, kbID string, cfg *sdk.KBModelConfig) error
GetInitializationConfig(ctx context.Context, kbID string) (*sdk.InitializationConfig, error)
GetInitializationConfig(ctx context.Context, kbID string) (*sdk.KBModelConfigView, error)
}
// NewCmdInit builds `weknora kb init <kb-id>` — bind models to a knowledge base
// so it becomes usable for retrieval and generation.
func NewCmdInit(f *cmdutil.Factory) *cobra.Command {
opts := &InitOptions{}
// newKBModelWriteCmd builds the `kb config set` model-binding write command.
// head is the argv prefix used for the risk action and retry_argv (weknora kb
// config set).
func newKBModelWriteCmd(f *cmdutil.Factory, use string, head []string) *cobra.Command {
opts := &ConfigSetOptions{}
action := strings.Join(head[1:], ".") // e.g. "kb.config.set"
cmd := &cobra.Command{
Use: "init <kb-id>",
Short: "Configure a knowledge base's models (make it usable)",
Use: use,
Short: "Bind embedding + chat models to a knowledge base (make it usable)",
Long: `Bind already-registered models to a knowledge base so it can embed, retrieve,
and generate. Both --chat-model (LLM, used for generation/summary) and
--embedding-model (used for retrieval) are required; register models first with
'weknora model create' and discover ids with 'weknora model list'.
High-risk write: changing a KB's embedding model affects how its content is
indexed and searched (and the server refuses once the KB has documents).
Without -y/--yes in a non-TTY / JSON context it exits 10
(input.confirmation_required) without applying the change.`,
indexed and searched (the server refuses to CHANGE it once the KB has
documents; setting it on an unconfigured KB is allowed). Without -y/--yes in a
non-TTY / JSON context it exits 10 (input.confirmation_required) without
applying the change.`,
Args: cobra.ExactArgs(1),
RunE: func(c *cobra.Command, args []string) error {
fopts, err := cmdutil.CheckFormatFlag(c)
@@ -60,11 +57,11 @@ Without -y/--yes in a non-TTY / JSON context it exits 10
kbID := args[0]
// Validate required flags before the dry-run gate so --dry-run rejects
// identically to the live path.
if err := validateInitFlags(opts); err != nil {
if err := validateConfigSetFlags(opts); err != nil {
return err
}
if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{
Action: "kb.init",
Action: action,
Args: map[string]any{"kb": kbID, "chat_model": opts.ChatModel, "embedding_model": opts.EmbeddingModel},
}); handled {
return err
@@ -74,8 +71,8 @@ Without -y/--yes in a non-TTY / JSON context it exits 10
return err
}
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, fopts.WantsJSON(),
"configure", "knowledge base", kbID, "kb.init",
cmdutil.BuildRetryArgv(c, []string{"weknora", "kb", "init", kbID}, "chat-model", "embedding-model", "format")); err != nil {
"configure", "knowledge base", kbID, action,
cmdutil.BuildRetryArgv(c, append(append([]string{}, head...), kbID), "chat-model", "embedding-model", "format")); err != nil {
return err
}
// Resolve name-or-id for the model flags (a UUID passes through; a
@@ -87,30 +84,30 @@ Without -y/--yes in a non-TTY / JSON context it exits 10
if opts.EmbeddingModel, err = cmdutil.ResolveModelRef(c.Context(), cli, opts.EmbeddingModel, "Embedding"); err != nil {
return err
}
return runInit(c.Context(), opts, fopts, cli, kbID)
return runConfigSet(c.Context(), opts, fopts, cli, kbID)
},
}
cmd.Flags().StringVar(&opts.ChatModel, "chat-model", "", "Chat / LLM model id or name for generation & summary (required) — see `weknora model list`")
cmd.Flags().StringVar(&opts.EmbeddingModel, "embedding-model", "", "Embedding model id or name for retrieval (required) — see `weknora model list`")
cmdutil.AddFormatFlag(cmd, kbInitFields...)
cmdutil.AddFormatFlag(cmd, kbConfigFields...)
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
cmdutil.SetRisk(cmd, "kb.init")
cmdutil.SetRisk(cmd, action)
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: "bind models to a KB so it becomes usable. --chat-model and --embedding-model are required and accept a model id or name; discover them with `weknora model list`.",
UsedFor: "bind models to a KB so it becomes retrieval-ready. --chat-model and --embedding-model are required and accept a model id or name; discover them with `weknora model list`. Read the result back with `weknora kb config`.",
RequiredFlags: []string{"<kb-id> (positional)", "--chat-model", "--embedding-model"},
Examples: []string{
"weknora kb init kb_abc --chat-model model_llm --embedding-model model_emb -y",
"weknora kb config set kb_abc --chat-model model_llm --embedding-model model_emb -y",
},
Output: "envelope.data is the resulting {chat_model_id, embedding_model_id, rerank_model_id, multimodal_id}",
Output: "envelope.data is the resulting secret-free config view {retrieval_ready, embedding, llm, rerank, multimodal}",
Warnings: []string{
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
"The server refuses to change the embedding model of a KB that already has documents.",
"The server refuses to CHANGE the embedding model of a KB that already has documents (setting it on an unconfigured KB is fine).",
},
})
return cmd
}
func validateInitFlags(opts *InitOptions) error {
func validateConfigSetFlags(opts *ConfigSetOptions) error {
var missing []string
if strings.TrimSpace(opts.ChatModel) == "" {
missing = append(missing, "--chat-model")
@@ -123,14 +120,13 @@ func validateInitFlags(opts *InitOptions) error {
}
return &cmdutil.Error{
Code: cmdutil.CodeInputMissingFlag,
Message: "kb init requires " + strings.Join(missing, " and "),
Message: "kb config set requires " + strings.Join(missing, " and "),
Hint: "discover model ids with `weknora model list` (or register one with `weknora model create`), then pass --chat-model <id> --embedding-model <id>",
}
}
func runInit(ctx context.Context, opts *InitOptions, fopts *cmdutil.FormatOptions, svc InitService, kbID string) error {
if err := validateInitFlags(opts); err != nil {
func runConfigSet(ctx context.Context, opts *ConfigSetOptions, fopts *cmdutil.FormatOptions, svc ConfigSetService, kbID string) error {
if err := validateConfigSetFlags(opts); err != nil {
return err
}
cfg := &sdk.KBModelConfig{
@@ -140,19 +136,31 @@ func runInit(ctx context.Context, opts *InitOptions, fopts *cmdutil.FormatOption
if err := svc.SetKBModelConfig(ctx, kbID, cfg); err != nil {
return cmdutil.WrapHTTP(err, "configure knowledge base %q", kbID)
}
// Re-read the server's resulting state so the envelope reflects what stuck.
// Re-read the server's resulting state (secret-free view) so the envelope
// reflects what stuck — the same shape `kb config` returns.
result, err := svc.GetInitializationConfig(ctx, kbID)
if err != nil || result == nil {
// The write succeeded; surface what we applied if the read-back failed.
result = &sdk.InitializationConfig{ChatModelID: opts.ChatModel, EmbeddingModelID: opts.EmbeddingModel}
result = &sdk.KBModelConfigView{
RetrievalReady: opts.EmbeddingModel != "",
Embedding: sdk.ModelSlotView{Configured: opts.EmbeddingModel != "", ModelName: opts.EmbeddingModel},
LLM: sdk.ModelSlotView{Configured: opts.ChatModel != "", ModelName: opts.ChatModel},
}
}
if fopts.WantsJSON() {
return fopts.Emit(iostreams.IO.Out, result, nil)
}
fmt.Fprintf(iostreams.IO.Out, "✓ Configured knowledge base %s (chat: %s, embedding: %s)\n",
kbID, result.ChatModelID, result.EmbeddingModelID)
kbID, orUnset(result.LLM.ModelName), orUnset(result.Embedding.ModelName))
return nil
}
// compile-time check: the production SDK client implements InitService.
var _ InitService = (*sdk.Client)(nil)
func orUnset(s string) string {
if s == "" {
return "(unset)"
}
return s
}
// compile-time check: the production SDK client implements ConfigSetService.
var _ ConfigSetService = (*sdk.Client)(nil)
@@ -19,7 +19,7 @@ import (
type fakeInitSvc struct {
gotKB string
gotCfg *sdk.KBModelConfig
result *sdk.InitializationConfig
result *sdk.KBModelConfigView
setErr error
}
@@ -29,24 +29,25 @@ func (f *fakeInitSvc) SetKBModelConfig(_ context.Context, kbID string, cfg *sdk.
return f.setErr
}
func (f *fakeInitSvc) GetInitializationConfig(_ context.Context, _ string) (*sdk.InitializationConfig, error) {
func (f *fakeInitSvc) GetInitializationConfig(_ context.Context, _ string) (*sdk.KBModelConfigView, error) {
if f.result != nil {
return f.result, nil
}
if f.gotCfg == nil {
return &sdk.InitializationConfig{}, nil
return &sdk.KBModelConfigView{}, nil
}
return &sdk.InitializationConfig{
ChatModelID: f.gotCfg.LLMModelID,
EmbeddingModelID: f.gotCfg.EmbeddingModelID,
return &sdk.KBModelConfigView{
RetrievalReady: f.gotCfg.EmbeddingModelID != "",
Embedding: sdk.ModelSlotView{Configured: f.gotCfg.EmbeddingModelID != "", ModelName: f.gotCfg.EmbeddingModelID},
LLM: sdk.ModelSlotView{Configured: f.gotCfg.LLMModelID != "", ModelName: f.gotCfg.LLMModelID},
}, nil
}
func TestKBInit_AppliesAndEmitsResult(t *testing.T) {
func TestKBConfigSet_AppliesAndEmitsResult(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeInitSvc{}
opts := &InitOptions{ChatModel: "model_llm", EmbeddingModel: "model_emb"}
require.NoError(t, runInit(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "kb_abc"))
opts := &ConfigSetOptions{ChatModel: "model_llm", EmbeddingModel: "model_emb"}
require.NoError(t, runConfigSet(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "kb_abc"))
assert.Equal(t, "kb_abc", svc.gotKB)
require.NotNil(t, svc.gotCfg)
@@ -54,46 +55,47 @@ func TestKBInit_AppliesAndEmitsResult(t *testing.T) {
assert.Equal(t, "model_emb", svc.gotCfg.EmbeddingModelID)
var env struct {
OK bool `json:"ok"`
Data sdk.InitializationConfig `json:"data"`
OK bool `json:"ok"`
Data sdk.KBModelConfigView `json:"data"`
}
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
assert.True(t, env.OK)
assert.Equal(t, "model_emb", env.Data.EmbeddingModelID)
assert.Equal(t, "model_llm", env.Data.ChatModelID)
assert.Equal(t, "model_emb", env.Data.Embedding.ModelName)
assert.Equal(t, "model_llm", env.Data.LLM.ModelName)
assert.True(t, env.Data.RetrievalReady)
}
func TestKBInit_RequiresBothModels(t *testing.T) {
func TestKBConfigSet_RequiresBothModels(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeInitSvc{}
// Missing both.
err := runInit(context.Background(), &InitOptions{}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "kb_abc")
err := runConfigSet(context.Background(), &ConfigSetOptions{}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "kb_abc")
var ce *cmdutil.Error
require.ErrorAs(t, err, &ce)
assert.Equal(t, cmdutil.CodeInputMissingFlag, ce.Code)
assert.Equal(t, "", svc.gotKB, "must not call SetKBModelConfig when flags are missing")
// Missing just embedding.
err = runInit(context.Background(), &InitOptions{ChatModel: "m"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "kb_abc")
err = runConfigSet(context.Background(), &ConfigSetOptions{ChatModel: "m"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc, "kb_abc")
require.ErrorAs(t, err, &ce)
assert.Contains(t, ce.Message, "--embedding-model")
}
func TestKBInit_WriteSucceedsReadbackFails(t *testing.T) {
func TestKBConfigSet_WriteSucceedsReadbackFails(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc2 := &readbackErrSvc{fakeInitSvc: &fakeInitSvc{}}
opts := &InitOptions{ChatModel: "model_llm", EmbeddingModel: "model_emb"}
require.NoError(t, runInit(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc2, "kb_abc"))
opts := &ConfigSetOptions{ChatModel: "model_llm", EmbeddingModel: "model_emb"}
require.NoError(t, runConfigSet(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc2, "kb_abc"))
var env struct {
Data sdk.InitializationConfig `json:"data"`
Data sdk.KBModelConfigView `json:"data"`
}
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
assert.Equal(t, "model_emb", env.Data.EmbeddingModelID, "falls back to applied config when read-back fails")
assert.Equal(t, "model_emb", env.Data.Embedding.ModelName, "falls back to applied config when read-back fails")
}
type readbackErrSvc struct{ *fakeInitSvc }
func (s *readbackErrSvc) GetInitializationConfig(_ context.Context, _ string) (*sdk.InitializationConfig, error) {
func (s *readbackErrSvc) GetInitializationConfig(_ context.Context, _ string) (*sdk.KBModelConfigView, error) {
return nil, errors.New("read-back boom")
}
@@ -116,13 +118,14 @@ func withRootKB(sub *cobra.Command, args ...string) *cobra.Command {
return root
}
func TestKBInit_RequiresConfirmation(t *testing.T) {
func TestKBConfigSet_RequiresConfirmation(t *testing.T) {
iostreams.SetForTest(t)
f := &cmdutil.Factory{
Client: func() (*sdk.Client, error) { return nil, nil },
Prompter: func() prompt.Prompter { return prompt.AgentPrompter{} },
}
root := withRootKB(NewCmdInit(f), "kb_abc", "--chat-model", "model_llm", "--embedding-model", "model_emb", "--format", "json")
// Drive `kb config set` (the config parent routes to its `set` subcommand).
root := withRootKB(NewCmdConfig(f), "set", "kb_abc", "--chat-model", "model_llm", "--embedding-model", "model_emb", "--format", "json")
err := root.Execute()
require.Error(t, err)
var ce *cmdutil.Error
@@ -131,4 +134,5 @@ func TestKBInit_RequiresConfirmation(t *testing.T) {
assert.Equal(t, 10, cmdutil.ExitCode(err))
assert.Contains(t, ce.RetryArgv, "-y")
assert.Contains(t, ce.RetryArgv, "model_emb")
assert.Contains(t, ce.RetryArgv, "set", "retry_argv should target `kb config set`")
}
+31 -11
View File
@@ -14,37 +14,57 @@ import (
)
type fakeConfigSvc struct {
cfg *sdk.InitializationConfig
cfg *sdk.KBModelConfigView
err error
}
func (f *fakeConfigSvc) GetInitializationConfig(_ context.Context, _ string) (*sdk.InitializationConfig, error) {
func (f *fakeConfigSvc) GetInitializationConfig(_ context.Context, _ string) (*sdk.KBModelConfigView, error) {
return f.cfg, f.err
}
func TestKBConfig_EmitsConfig(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeConfigSvc{cfg: &sdk.InitializationConfig{EmbeddingModelID: "model_emb", ChatModelID: "model_chat"}}
svc := &fakeConfigSvc{cfg: &sdk.KBModelConfigView{
RetrievalReady: true,
Embedding: sdk.ModelSlotView{Configured: true, ModelName: "model_emb", Source: "remote"},
LLM: sdk.ModelSlotView{Configured: true, ModelName: "model_chat"},
}}
require.NoError(t, runConfig(context.Background(), &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "kb_abc"))
var env struct {
OK bool `json:"ok"`
Data sdk.InitializationConfig `json:"data"`
OK bool `json:"ok"`
Data sdk.KBModelConfigView `json:"data"`
}
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
assert.True(t, env.OK)
assert.Equal(t, "model_emb", env.Data.EmbeddingModelID)
assert.Equal(t, "model_chat", env.Data.ChatModelID)
assert.Equal(t, "model_emb", env.Data.Embedding.ModelName)
assert.Equal(t, "model_chat", env.Data.LLM.ModelName)
assert.True(t, env.Data.RetrievalReady)
}
// TestKBConfig_NilConfig: a nil server config (KB not yet initialized) emits an
// empty object, not a crash.
// TestKBConfig_SecretFree: the view type has no apiKey/baseUrl field, so the
// JSON output can never carry provider credentials — the CLI never echoes the
// keys the server returns for the web config form.
func TestKBConfig_SecretFree(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeConfigSvc{cfg: &sdk.KBModelConfigView{
Embedding: sdk.ModelSlotView{Configured: true, ModelName: "e", Source: "remote"},
}}
require.NoError(t, runConfig(context.Background(), &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "kb_abc"))
assert.NotContains(t, out.String(), "apiKey")
assert.NotContains(t, out.String(), "api_key")
assert.NotContains(t, out.String(), "baseUrl")
}
// TestKBConfig_NilConfig: a nil server config (KB not yet initialized) emits
// retrieval_ready:false, not a crash.
func TestKBConfig_NilConfig(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeConfigSvc{cfg: nil}
require.NoError(t, runConfig(context.Background(), &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "kb_abc"))
var env struct {
Data sdk.InitializationConfig `json:"data"`
Data sdk.KBModelConfigView `json:"data"`
}
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
assert.Empty(t, env.Data.EmbeddingModelID)
assert.False(t, env.Data.RetrievalReady)
assert.Empty(t, env.Data.Embedding.ModelName)
}
+28 -5
View File
@@ -9,6 +9,7 @@ import (
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
"github.com/Tencent/WeKnora/cli/internal/iostreams"
"github.com/Tencent/WeKnora/cli/internal/output"
sdk "github.com/Tencent/WeKnora/client"
)
@@ -29,6 +30,7 @@ type CreateOptions struct {
Name string
Description string
EmbeddingModel string
ChatModel string
StorageProvider string
DryRun bool
}
@@ -84,16 +86,23 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
}
// --embedding-model accepts a model id or name (a UUID passes
// through; a name resolves among Embedding models). Configuring a
// KB's models fully is `weknora kb init`; this just pre-sets the
// KB's models fully is `weknora kb config set`; this just pre-sets the
// embedding model at creation.
if opts.EmbeddingModel, err = cmdutil.ResolveModelRef(c.Context(), cli, opts.EmbeddingModel, "Embedding"); err != nil {
return err
}
// --chat-model (id or name) pre-sets the KB's LLM at creation, so a
// KB can be born retrieval-ready in one step. Full model config
// (rerank / multimodal) is still `weknora kb config set`.
if opts.ChatModel, err = cmdutil.ResolveModelRef(c.Context(), cli, opts.ChatModel, "KnowledgeQA"); err != nil {
return err
}
return runCreate(c.Context(), opts, fopts, cli)
},
}
cmd.Flags().StringVar(&opts.Description, "description", "", "Knowledge base description (optional)")
cmd.Flags().StringVar(&opts.EmbeddingModel, "embedding-model", "", "Embedding model id or name (optional; configure models fully with `weknora kb init`)")
cmd.Flags().StringVar(&opts.EmbeddingModel, "embedding-model", "", "Embedding model id or name (optional; makes the KB retrieval-ready at creation)")
cmd.Flags().StringVar(&opts.ChatModel, "chat-model", "", "Chat/LLM model id or name (optional; pre-set the KB's answer model at creation)")
cmd.Flags().StringVar(&opts.StorageProvider, "storage-provider", "",
"Storage provider for documents in this KB: "+strings.Join(storageProviderValues, " | ")+" (optional; server default when unset)")
cmdutil.AddFormatFlag(cmd, kbCreateFields...)
@@ -103,10 +112,10 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
RequiredFlags: []string{"<name> (positional)"},
Examples: []string{
`weknora kb create "Eng Docs"`,
`weknora kb create "Eng Docs" --description "engineering knowledge base"`,
`weknora kb create "Eng Docs" --embedding-model text-embedding-3-small --chat-model gpt-4o-mini # retrieval-ready in one step`,
`weknora kb create "Eng Docs" --jq .data.id # capture id to chain into doc upload --kb`,
},
Output: "envelope.data is the created KnowledgeBase object with id, name, type, embedding_model_id",
Output: "envelope.data is the created KnowledgeBase object with id, name, type, embedding_model_id, summary_model_id",
})
return cmd
}
@@ -125,6 +134,9 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
if opts.EmbeddingModel != "" {
req.EmbeddingModelID = opts.EmbeddingModel
}
if opts.ChatModel != "" {
req.SummaryModelID = opts.ChatModel
}
if opts.StorageProvider != "" {
canonSP, err := cmdutil.ValidateEnum("storage-provider", opts.StorageProvider, storageProviderValues)
if err != nil {
@@ -138,9 +150,20 @@ func runCreate(ctx context.Context, opts *CreateOptions, fopts *cmdutil.FormatOp
return cmdutil.WrapHTTP(err, "create knowledge base")
}
// A KB with no embedding model can hold documents but never index/retrieve
// them — surface the next step at the point of creation instead of leaving
// the agent to discover a silent-draft KB via a later empty search.
var meta *output.Meta
if created.EmbeddingModelID == "" {
meta = &output.Meta{Hint: "retrieval_ready=false: no embedding model bound. Uploaded docs will not be searchable until you run `weknora kb config set " + created.ID + " --embedding-model <id> --chat-model <id>` (create the KB with --embedding-model/--chat-model to skip this step)."}
}
if fopts.WantsJSON() {
return fopts.Emit(iostreams.IO.Out, created, nil)
return fopts.Emit(iostreams.IO.Out, created, meta)
}
fmt.Fprintf(iostreams.IO.Out, "✓ Created knowledge base %q (id: %s)\n", created.Name, created.ID)
if meta != nil {
fmt.Fprintf(iostreams.IO.Out, "⚠ %s\n", meta.Hint)
}
return nil
}
+44
View File
@@ -66,6 +66,50 @@ func TestCreate_Success_OmitsEmbeddingModelWhenEmpty(t *testing.T) {
assert.Equal(t, "", svc.got.EmbeddingModelID, "embedding-model unset ⇒ empty in request")
}
// A KB created without an embedding model can never retrieve; the create result
// must hand the agent the fix (kb config set) instead of a silent unusable KB.
func TestCreate_HintsWhenNoEmbeddingModel(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeCreateSvc{resp: &sdk.KnowledgeBase{ID: "kb_x", Name: "n"}}
require.NoError(t, runCreate(context.Background(), &CreateOptions{Name: "n"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
var env struct {
Meta struct {
Hint string `json:"hint"`
} `json:"meta"`
}
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
assert.Contains(t, env.Meta.Hint, "kb config set", "unconfigured KB must hint the retrieval-readiness fix")
}
// A retrieval-ready KB (embedding model bound) carries no such hint — no noise.
func TestCreate_NoHintWhenEmbeddingModelBound(t *testing.T) {
out, _ := iostreams.SetForTest(t)
svc := &fakeCreateSvc{resp: &sdk.KnowledgeBase{ID: "kb_x", Name: "n", EmbeddingModelID: "emb_1"}}
require.NoError(t, runCreate(context.Background(), &CreateOptions{Name: "n", EmbeddingModel: "emb_1"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc))
var env struct {
Meta *struct {
Hint string `json:"hint"`
} `json:"meta"`
}
require.NoError(t, json.Unmarshal(out.Bytes(), &env))
if env.Meta != nil {
assert.Empty(t, env.Meta.Hint, "retrieval-ready KB must not emit a readiness hint")
}
}
// TestCreate_ChatModelSetsSummaryModelID: --chat-model rides the create request
// as summary_model_id, so a KB can be born retrieval-ready in one step.
func TestCreate_ChatModelSetsSummaryModelID(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeCreateSvc{resp: &sdk.KnowledgeBase{ID: "kb_x", Name: "n"}}
opts := &CreateOptions{Name: "n", EmbeddingModel: "emb_x", ChatModel: "chat_x"}
require.NoError(t, runCreate(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc))
require.NotNil(t, svc.got)
assert.Equal(t, "emb_x", svc.got.EmbeddingModelID)
assert.Equal(t, "chat_x", svc.got.SummaryModelID, "--chat-model must set summary_model_id on the create request")
}
func TestCreate_NameRequired(t *testing.T) {
_, _ = iostreams.SetForTest(t)
svc := &fakeCreateSvc{}
+1
View File
@@ -81,6 +81,7 @@ exactly to guard against unintended deletes.`,
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: "permanently delete a knowledge base and all its contents",
RequiredFlags: []string{"<kb-id> (positional)"},
Output: "envelope.data is {id, deleted:true}",
Examples: []string{
"weknora kb delete kb_abc -y",
"weknora kb delete kb_abc -y --format json",
+1
View File
@@ -120,6 +120,7 @@ to the user first.`,
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: "update a knowledge base's name or description",
RequiredFlags: []string{"<kb-id> (positional)", "--name or --description (at least one)"},
Output: "envelope.data is the updated KnowledgeBase object (id, name, description)",
Examples: []string{
"weknora kb update kb_abc --name \"New Name\" -y",
"weknora kb update kb_abc --description \"Updated desc\" --format json -y",
+1 -2
View File
@@ -25,7 +25,6 @@ func NewCmd(f *cmdutil.Factory) *cobra.Command {
cmd.AddCommand(NewCmdUnpin(f))
cmd.AddCommand(NewCmdStatus(f))
cmd.AddCommand(NewCmdCheck(f))
cmd.AddCommand(NewCmdConfig(f))
cmd.AddCommand(NewCmdInit(f))
cmd.AddCommand(NewCmdConfig(f)) // `config` also hosts the `config set` write subcommand
return cmd
}
+22 -8
View File
@@ -16,12 +16,16 @@ import (
// Shallow read only: 1 HTTP call, no failed-doc aggregation.
// For deep verification including failed_count, use `kb check <id>`.
type StatusResult struct {
ID string `json:"id"`
Reachable bool `json:"reachable"`
KnowledgeCount int64 `json:"knowledge_count,omitempty"`
ChunkCount int64 `json:"chunk_count,omitempty"`
IsProcessing bool `json:"is_processing,omitempty"`
ProcessingCount int64 `json:"processing_count,omitempty"`
ID string `json:"id"`
Reachable bool `json:"reachable"`
// RetrievalReady is false when the KB has no embedding model bound — it can
// never index or retrieve until `kb config set` runs. Always emitted (no
// omitempty) so a not-ready KB is visible, not silently green.
RetrievalReady bool `json:"retrieval_ready"`
KnowledgeCount int64 `json:"knowledge_count,omitempty"`
ChunkCount int64 `json:"chunk_count,omitempty"`
IsProcessing bool `json:"is_processing,omitempty"`
ProcessingCount int64 `json:"processing_count,omitempty"`
}
// StatusService is the narrow SDK surface needed for kb status.
@@ -30,7 +34,7 @@ type StatusService interface {
}
var kbStatusFields = []string{
"id", "reachable", "knowledge_count", "chunk_count",
"id", "reachable", "retrieval_ready", "knowledge_count", "chunk_count",
"is_processing", "processing_count",
}
@@ -73,7 +77,7 @@ For full metadata (config / pinned / tenant), use 'weknora kb view <id>'.`,
UsedFor: "shallow health probe of a knowledge base (one HTTP call): reachability, no failed-doc aggregation",
RequiredFlags: []string{"<kb-id> (positional)"},
Examples: []string{"weknora kb status kb_abc"},
Output: "envelope.data is {id, reachable, ...}; use `kb check` for deep failed-doc aggregation",
Output: "envelope.data is {id, reachable, retrieval_ready, ...}; retrieval_ready=false means no embedding model is bound (run `kb config set`), so the KB cannot index/retrieve; use `kb check` for deep failed-doc aggregation",
})
return cmd
}
@@ -89,6 +93,7 @@ func runStatus(ctx context.Context, svc StatusService, id string) (*StatusResult
return &StatusResult{
ID: kb.ID,
Reachable: true,
RetrievalReady: kb.EmbeddingModelID != "",
KnowledgeCount: kb.KnowledgeCount,
ChunkCount: kb.ChunkCount,
IsProcessing: kb.IsProcessing,
@@ -115,11 +120,20 @@ func writeStatusText(w io.Writer, res *StatusResult) error {
if !res.Reachable {
return nil
}
fmt.Fprintf(w, "Retrieval: %v%s\n", res.RetrievalReady, retrievalHint(res.RetrievalReady))
fmt.Fprintf(w, "Knowledge: %d\n", res.KnowledgeCount)
fmt.Fprintf(w, "Chunks: %d\n", res.ChunkCount)
fmt.Fprintf(w, "Processing: %v (%d active)\n", res.IsProcessing, res.ProcessingCount)
return nil
}
// retrievalHint annotates a not-ready KB in text output with the fix.
func retrievalHint(ready bool) string {
if ready {
return ""
}
return " ← no embedding model bound; run `weknora kb config set <id>`"
}
// compile-time check: SDK client satisfies StatusService.
var _ StatusService = (*sdk.Client)(nil)
+22 -5
View File
@@ -26,11 +26,12 @@ func (f *fakeStatusSvc) GetKnowledgeBase(_ context.Context, id string) (*sdk.Kno
func TestRunStatus_ShallowFields(t *testing.T) {
svc := &fakeStatusSvc{kb: &sdk.KnowledgeBase{
ID: "kb_x",
KnowledgeCount: 42,
ChunkCount: 100,
IsProcessing: true,
ProcessingCount: 3,
ID: "kb_x",
KnowledgeCount: 42,
ChunkCount: 100,
IsProcessing: true,
ProcessingCount: 3,
EmbeddingModelID: "emb_1",
}}
res, err := runStatus(context.Background(), svc, "kb_x")
if err != nil {
@@ -42,6 +43,22 @@ func TestRunStatus_ShallowFields(t *testing.T) {
if res.KnowledgeCount != 42 || res.ChunkCount != 100 || res.ProcessingCount != 3 || !res.IsProcessing {
t.Errorf("got %+v", res)
}
if !res.RetrievalReady {
t.Error("RetrievalReady=false, want true when an embedding model is bound")
}
}
// A KB with no embedding model can never retrieve — the health probe must say
// so (retrieval_ready=false), not report a silent all-green status.
func TestRunStatus_RetrievalNotReadyWithoutEmbeddingModel(t *testing.T) {
svc := &fakeStatusSvc{kb: &sdk.KnowledgeBase{ID: "kb_x", KnowledgeCount: 1}}
res, err := runStatus(context.Background(), svc, "kb_x")
if err != nil {
t.Fatalf("runStatus: %v", err)
}
if res.RetrievalReady {
t.Error("RetrievalReady=true, want false when no embedding model is bound")
}
}
func TestRunStatus_Unreachable(t *testing.T) {