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
+24 -3
View File
@@ -74,13 +74,19 @@ For fail-fast semantics, use shell composition:
return err
}
// The partition (completed/failed/timeout) is already on stdout via
// emitWaitResult. On aggregate failure we still need a non-zero exit,
// but the error is Silent so PrintError does NOT write a second,
// contradictory {ok:false} envelope to stderr — the agent reads the
// failure detail from the stdout partition + the exit code (1/124).
// Same contract as cmdutil.RunBatch.
switch res.ExitCode() {
case 0:
return nil
case 1:
return cmdutil.NewError(cmdutil.CodeOperationFailed, fmt.Sprintf("%d doc(s) failed", len(res.Failed)))
return cmdutil.NewError(cmdutil.CodeOperationFailed, fmt.Sprintf("%d doc(s) failed", len(res.Failed))).WithSilent()
case 124:
return cmdutil.NewError(cmdutil.CodeOperationTimeout, fmt.Sprintf("wait timed out (%d doc(s) still pending)", len(res.Timeout)))
return cmdutil.NewError(cmdutil.CodeOperationTimeout, fmt.Sprintf("wait timed out (%d doc(s) still pending)", len(res.Timeout))).WithSilent()
}
return nil
},
@@ -88,6 +94,19 @@ For fail-fast semantics, use shell composition:
cmd.Flags().DurationVar(&opts.Timeout, "timeout", 10*time.Minute, "Max wait time before exiting 124")
cmd.Flags().DurationVar(&opts.Interval, "interval", 2*time.Second, "Initial poll interval; exponential backoff capped at 15s + jitter")
cmdutil.AddFormatFlag(cmd)
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: "block until one or more documents reach a terminal parse state (completed or failed), or --timeout elapses",
RequiredFlags: []string{"<doc-id>... (one or more positionals)"},
Examples: []string{
"weknora doc wait doc_abc",
"weknora doc wait doc_a doc_b --timeout 5m",
},
Output: "envelope.data is {completed:[], failed:[{id,message}], timeout:[]}",
Warnings: []string{
"exit code carries the aggregate result: 0 all completed, 1 any failed, 124 timeout",
"ok:true means the wait ran to a terminal state — NOT that every doc succeeded; branch on the exit code or inspect data.failed",
},
})
return cmd
}
@@ -146,7 +165,9 @@ func waitForDocs(ctx context.Context, ids []string, svc WaitService, opts WaitOp
ctx, cancel := context.WithTimeout(ctx, opts.Timeout)
defer cancel()
result := &WaitResult{}
// Completed is non-omitempty (always present in the partition), so start it
// as an empty slice rather than nil — agents see `"completed":[]`, not null.
result := &WaitResult{Completed: []string{}}
var mu sync.Mutex
addCompleted := func(id string) {
mu.Lock()