feat(cli): agent-first WeKnora CLI
The `weknora` command-line client for the WeKnora RAG server. Full command surface: kb / doc / chunk / session / message / agent / model / search / chat / auth / profile / link / api / mcp / skills / config / doctor / schema / exit-codes. Agent-first wire contract: JSON envelope by default, typed error codes mapped to stable exit codes, error.retry_argv / retryable / partial-failure status, global --dry-run preview, the exit-10 confirmation protocol for writes, and control/ANSI/Bidi input hygiene. Stateless env-credential auth (WEKNORA_API_KEY / WEKNORA_TOKEN + WEKNORA_HOST) for headless/CI/agent use. A curated read-only MCP tool surface (`mcp serve`) and embedded Agent Skills (`skills install`). Extensive unit + contract-golden tests and CI.
This commit is contained in:
+17
-39
@@ -3,10 +3,8 @@ package kb
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"strings"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
"github.com/spf13/pflag"
|
||||
|
||||
"github.com/Tencent/WeKnora/cli/internal/cmdutil"
|
||||
"github.com/Tencent/WeKnora/cli/internal/iostreams"
|
||||
@@ -14,7 +12,7 @@ import (
|
||||
)
|
||||
|
||||
// kbEditFields enumerates the fields surfaced for `--format json` discovery on
|
||||
// `kb edit`. The result is the updated KnowledgeBase; mirrors the kb
|
||||
// `kb update`. The result is the updated KnowledgeBase; mirrors the kb
|
||||
// top-level json tags.
|
||||
var kbEditFields = []string{
|
||||
"id", "name", "type", "description",
|
||||
@@ -47,14 +45,14 @@ type EditService interface {
|
||||
UpdateKnowledgeBase(ctx context.Context, id string, req *sdk.UpdateKnowledgeBaseRequest) (*sdk.KnowledgeBase, error)
|
||||
}
|
||||
|
||||
// NewCmdEdit builds `weknora kb edit <id>`. At least one of --name /
|
||||
// NewCmdEdit builds `weknora kb update <id>`. At least one of --name /
|
||||
// --description must be provided.
|
||||
func NewCmdEdit(f *cmdutil.Factory) *cobra.Command {
|
||||
opts := &EditOptions{}
|
||||
var name, desc string
|
||||
cmd := &cobra.Command{
|
||||
Use: "edit <kb-id>",
|
||||
Short: "Edit a knowledge base's name or description",
|
||||
Use: "update <kb-id>",
|
||||
Short: "Update a knowledge base's name or description",
|
||||
Long: `Update a knowledge base's name and/or description. At least one of
|
||||
--name / --description must be supplied; fields you omit are preserved
|
||||
server-side.
|
||||
@@ -78,14 +76,13 @@ to the user first.`,
|
||||
}
|
||||
id := args[0]
|
||||
// Validate pure-local "at least one mutation flag" before the
|
||||
// dry-run gate so --dry-run rejects identically to the live path
|
||||
// (industry standard: gh / kubectl / lark all validate before
|
||||
// preview). Same typed Error as runEdit so live behavior is
|
||||
// unchanged, just earlier.
|
||||
// dry-run gate so --dry-run rejects identically to the live path.
|
||||
// Same typed Error as runEdit so live behavior is unchanged, just
|
||||
// earlier.
|
||||
if opts.Name == nil && opts.Description == nil {
|
||||
return &cmdutil.Error{
|
||||
Code: cmdutil.CodeInputMissingFlag,
|
||||
Message: "kb edit requires at least one of --name or --description",
|
||||
Message: "kb update requires at least one of --name or --description",
|
||||
Hint: "pass --name <name> and/or --description <desc>",
|
||||
}
|
||||
}
|
||||
@@ -97,7 +94,7 @@ to the user first.`,
|
||||
planArgs["description"] = *opts.Description
|
||||
}
|
||||
if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{
|
||||
Action: "kb.edit",
|
||||
Action: "kb.update",
|
||||
Args: planArgs,
|
||||
}); handled {
|
||||
return err
|
||||
@@ -108,8 +105,8 @@ 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(), "edit", "knowledge base", id, "kb.edit", retryCmd); err != nil {
|
||||
retryCmd := cmdutil.BuildRetryArgv(c, []string{"weknora", "kb", "update", id}, "name", "description", "format")
|
||||
if err := cmdutil.ConfirmWrite(f.Prompter(), opts.Yes, fopts.WantsJSON(), "update", "knowledge base", id, "kb.update", retryCmd); err != nil {
|
||||
return err
|
||||
}
|
||||
return runEdit(c.Context(), opts, fopts, cli, id)
|
||||
@@ -119,46 +116,27 @@ to the user first.`,
|
||||
cmd.Flags().StringVar(&desc, "description", "", "New description (omit to leave unchanged)")
|
||||
cmdutil.AddFormatFlag(cmd, kbEditFields...)
|
||||
cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
|
||||
cmdutil.SetRisk(cmd, "kb.edit")
|
||||
cmdutil.SetWriteRisk(cmd, "kb.update")
|
||||
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)"},
|
||||
Examples: []string{
|
||||
"weknora kb edit kb_abc --name \"New Name\" -y",
|
||||
"weknora kb edit kb_abc --description \"Updated desc\" --format json -y",
|
||||
"weknora kb update kb_abc --name \"New Name\" -y",
|
||||
"weknora kb update kb_abc --description \"Updated desc\" --format json -y",
|
||||
},
|
||||
Warnings: []string{
|
||||
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
|
||||
"kb edit overwrites fields; SDK uses fetch-then-update to avoid clobbering, but malformed input can still corrupt config.",
|
||||
"kb update overwrites fields; SDK uses fetch-then-update to avoid clobbering, but malformed input can still corrupt config.",
|
||||
},
|
||||
})
|
||||
return cmd
|
||||
}
|
||||
|
||||
// buildKBEditRetryCmd constructs a directly-executable retry argv from the
|
||||
// flags the user actually set so agents can surface a precise re-run command.
|
||||
func buildKBEditRetryCmd(c *cobra.Command, id string) string {
|
||||
var parts []string
|
||||
parts = append(parts, "weknora", "kb", "edit", id)
|
||||
c.Flags().Visit(func(f *pflag.Flag) {
|
||||
switch f.Name {
|
||||
case "name":
|
||||
parts = append(parts, "--name", f.Value.String())
|
||||
case "description":
|
||||
parts = append(parts, "--description", f.Value.String())
|
||||
case "format":
|
||||
parts = append(parts, "--format", f.Value.String())
|
||||
}
|
||||
})
|
||||
parts = append(parts, "-y")
|
||||
return strings.Join(parts, " ")
|
||||
}
|
||||
|
||||
func runEdit(ctx context.Context, opts *EditOptions, fopts *cmdutil.FormatOptions, svc EditService, id string) error {
|
||||
if opts.Name == nil && opts.Description == nil {
|
||||
return &cmdutil.Error{
|
||||
Code: cmdutil.CodeInputMissingFlag,
|
||||
Message: "kb edit requires at least one of --name or --description",
|
||||
Message: "kb update requires at least one of --name or --description",
|
||||
Hint: "pass --name <name> and/or --description <desc>",
|
||||
}
|
||||
}
|
||||
@@ -183,7 +161,7 @@ func runEdit(ctx context.Context, opts *EditOptions, fopts *cmdutil.FormatOption
|
||||
|
||||
updated, err := svc.UpdateKnowledgeBase(ctx, id, req)
|
||||
if err != nil {
|
||||
return cmdutil.WrapHTTP(err, "edit knowledge base %s", id)
|
||||
return cmdutil.WrapHTTP(err, "update knowledge base %s", id)
|
||||
}
|
||||
if fopts.WantsJSON() {
|
||||
return fopts.Emit(iostreams.IO.Out, updated, nil)
|
||||
|
||||
Reference in New Issue
Block a user