refactor(cli): resource-command refactors — --kb resolver, MCP session_ask, session stop (BREAKING)

Unify the --kb resolver (accepts name or UUID) across kb/doc/chunk/session/
search/chat/link; `agent create` attaches knowledge bases via --attach-kb
(no longer --kb). Rename the MCP tool agent_invoke → session_ask and drop dead
MCP error codes. Add `session stop` (StopSession), completing the
start / continue-stream / stop triad.

Across these commands, bring the agent contract up to par: --dry-run previews
on mutations (incl. kb pin/unpin, session stop), agent-help blobs on the
read/health surface, accurate destructive-confirmation verbs, and search
has_more truncation signalling so an agent can tell its results were capped.
This commit is contained in:
nullkey
2026-05-29 20:06:30 +08:00
committed by lyingbug
parent a68cc59310
commit c90f4e895e
54 changed files with 807 additions and 93 deletions
+6
View File
@@ -72,6 +72,12 @@ verification including failed-doc aggregation.`,
},
}
cmdutil.AddFormatFlag(cmd, kbCheckFields...)
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
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`",
})
return cmd
}
+5
View File
@@ -92,6 +92,11 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
"Storage provider for documents in this KB: "+strings.Join(storageProviderValues, " | ")+" (optional; server default when unset)")
cmdutil.AddFormatFlag(cmd, kbCreateFields...)
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: "Create a new knowledge base with the given name. Emits the created KB object with its id.",
RequiredFlags: []string{"<name> (positional)"},
Output: "envelope.data is the created KnowledgeBase object with id, name, type, embedding_model_id",
})
return cmd
}
+1 -1
View File
@@ -94,7 +94,7 @@ exactly to guard against unintended deletes.`,
}
func runDelete(ctx context.Context, opts *DeleteOptions, fopts *cmdutil.FormatOptions, svc DeleteService, p prompt.Prompter, id string) error {
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "knowledge base", id, "kb.delete", "weknora kb delete "+id+" -y"); err != nil {
if err := cmdutil.ConfirmDestructive(p, opts.Yes, fopts.WantsJSON(), "delete", "knowledge base", id, "kb.delete", "weknora kb delete "+id+" -y"); err != nil {
return err
}
+1 -1
View File
@@ -109,7 +109,7 @@ to the user first.`,
// Build a retry command from the flags the user actually passed so
// agents can re-invoke with -y after explicit human approval.
retryCmd := buildKBEditRetryCmd(c, id)
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, fopts.WantsJSON(), "knowledge base", id, "kb.edit", retryCmd); err != nil {
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, fopts.WantsJSON(), "edit", "knowledge base", id, "kb.edit", retryCmd); err != nil {
return err
}
return runEdit(c.Context(), opts, fopts, cli, id)
+20 -1
View File
@@ -16,7 +16,9 @@ import (
// relevant fields here are the id and the new pin state.
var kbPinFields = []string{"id", "is_pinned"}
type PinOptions struct{}
type PinOptions struct {
DryRun bool
}
// PinService is the narrow SDK surface this command depends on. The CLI
// reads current state before toggling so `pin`/`unpin` are idempotent -
@@ -49,6 +51,16 @@ func newPinCmd(f *cmdutil.Factory, use string, want bool, short string) *cobra.C
return err
}
fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
action := "kb.pin"
if !want {
action = "kb.unpin"
}
if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{
Action: action,
Args: map[string]any{"kb": args[0]},
}); handled {
return err
}
cli, err := f.Client()
if err != nil {
return err
@@ -57,6 +69,13 @@ func newPinCmd(f *cmdutil.Factory, use string, want bool, short string) *cobra.C
},
}
cmdutil.AddFormatFlag(cmd, kbPinFields...)
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: use + " a knowledge base (idempotent: a no-op if it is already in the target state)",
RequiredFlags: []string{"<kb-id> (positional)"},
Examples: []string{"weknora " + use + " kb_abc"},
Output: "envelope.data is the KnowledgeBase with is_pinned reflecting the new state",
})
return cmd
}
+32
View File
@@ -2,9 +2,11 @@ package kb
import (
"context"
"encoding/json"
"errors"
"testing"
"github.com/spf13/cobra"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
@@ -104,3 +106,33 @@ func TestPin_JSON(t *testing.T) {
assert.Contains(t, body, `"is_pinned":true`)
assert.Contains(t, body, `"id":"kb_abc"`)
}
// TestPin_DryRun_NoServerCall: --dry-run must emit a kb.pin plan (exit 0)
// without reaching the server, so pin/unpin honor the same mutation-preview
// contract as create/edit/delete. Regression for pin/unpin lacking --dry-run.
func TestPin_DryRun_NoServerCall(t *testing.T) {
for _, tc := range []struct {
name, want string
cmd func(*cmdutil.Factory) *cobra.Command
}{
{"pin", "kb.pin", NewCmdPin},
{"unpin", "kb.unpin", NewCmdUnpin},
} {
t.Run(tc.name, func(t *testing.T) {
out, _ := iostreams.SetForTest(t)
root := withRootHarness(tc.cmd(kbDryRunFactory(t)), "kb_x", "--dry-run", "--format", "json")
require.NoError(t, root.Execute(), "dry-run must succeed without a client")
var env struct {
OK bool `json:"ok"`
Meta struct {
DryRun bool `json:"dry_run"`
Plan map[string]any `json:"plan"`
} `json:"meta"`
}
require.NoError(t, json.Unmarshal(out.Bytes(), &env), "got %q", out.String())
assert.True(t, env.OK)
assert.True(t, env.Meta.DryRun)
assert.Equal(t, tc.want, env.Meta.Plan["action"])
})
}
}
+6
View File
@@ -69,6 +69,12 @@ For full metadata (config / pinned / tenant), use 'weknora kb view <id>'.`,
},
}
cmdutil.AddFormatFlag(cmd, kbStatusFields...)
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
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",
})
return cmd
}
+9
View File
@@ -53,6 +53,15 @@ func NewCmdView(f *cmdutil.Factory) *cobra.Command {
},
}
cmdutil.AddFormatFlag(cmd, kbViewFields...)
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: "fetch one knowledge base's full configuration by id",
RequiredFlags: []string{"<kb-id> (positional)"},
Examples: []string{
"weknora kb view kb_abc",
"weknora kb view kb_abc --jq .data.embedding_model_id",
},
Output: "envelope.data is the KnowledgeBase object (id, name, type, embedding/summary model ids, chunk_count, ...)",
})
return cmd
}