feat(cli): agent CRUD + view full config rendering

Adds the three management verbs missing from v0.4's agent subtree
(create / edit / delete) and expands v0.4-shipped agent view to render
all 34 AgentConfig fields in human output (was 7).

Surface: hot-path flags (--model required + 7 optional) +
--config-file YAML/JSON tail + --generate-skeleton template emit.
Flag > file > server-default precedence for hybrid invocation.

- agent create <name> --model <id> [flags] + --from <agent-id> for
  copy-then-overlay (CopyAgent + UpdateAgent); preserves source
  config except for fields explicitly overridden
- agent edit <id> with --add-kb / --remove-kb idempotent pair,
  L-2 fetch-then-update, at-least-one-flag validation,
  --description "" clearing via Flags().Changed(). --config-file
  fully replaces the AgentConfig baseline (use surgical flags for
  partial edits; the Long help spells this out + a test pins the
  contract).
- agent delete <id> with ConfirmDestructive + exit-10 protocol;
  404 propagates resource.not_found (not idempotent)
- agent view: 10 grouped sections (Identity / LLM / KB attachment /
  Retrieval / Query rewrite / Tools / FAQ / Web search / Multi-turn /
  Fallback / Templates); --json field discovery includes all
  config.* keys

Shared helper cli/internal/cmdutil/agentconfig.go handles YAML/JSON
parsing, flag-overlay-file fusion, and skeleton emission.
This commit is contained in:
nullkey
2026-05-16 02:35:30 +08:00
committed by lyingbug
parent b7f9f155b3
commit 59132a56f6
11 changed files with 1924 additions and 44 deletions
+183
View File
@@ -0,0 +1,183 @@
package cmdutil
import (
"encoding/json"
"fmt"
"io"
"strings"
"gopkg.in/yaml.v3"
sdk "github.com/Tencent/WeKnora/client"
)
// AgentConfigFlags carries hot-path flag values plus per-flag "was set"
// bits so the merge step can distinguish "user did not pass --foo" from
// "user passed --foo zero-value". Mirrors the canonical CLI pattern of
// keeping presence-tracking out-of-band from the value itself, which
// pflag's Changed() facility supplies at the cobra layer.
type AgentConfigFlags struct {
AgentMode string
AgentModeSet bool
SystemPrompt string
SystemPromptSet bool
ModelID string
ModelIDSet bool
RerankModelID string
RerankModelIDSet bool
Temperature float64
TemperatureSet bool
KBSelectionMode string
KBSelectionModeSet bool
KnowledgeBases []string
KnowledgeBasesSet bool
}
// LoadAgentConfig parses YAML or JSON from r into an AgentConfig. kind is
// "yaml" or "json" (typically inferred from file extension by the caller).
// Returned errors carry no typed code — callers should wrap with
// CodeInputInvalidArgument as the user-facing context.
//
// YAML route round-trips through JSON so the SDK's existing `json:` field
// tags (snake_case) are the single source of truth for key names. yaml.v3
// alone would lowercase field names (KnowledgeBases → knowledgebases),
// which doesn't match the JSON schema users see elsewhere.
func LoadAgentConfig(r io.Reader, kind string) (*sdk.AgentConfig, error) {
body, err := io.ReadAll(r)
if err != nil {
return nil, fmt.Errorf("read config: %w", err)
}
var cfg sdk.AgentConfig
switch strings.ToLower(kind) {
case "yaml", "yml":
var raw map[string]any
if err := yaml.Unmarshal(body, &raw); err != nil {
return nil, fmt.Errorf("parse YAML config: %w", err)
}
jsBody, err := json.Marshal(raw)
if err != nil {
return nil, fmt.Errorf("re-encode YAML as JSON: %w", err)
}
if err := json.Unmarshal(jsBody, &cfg); err != nil {
return nil, fmt.Errorf("parse YAML config (via JSON): %w", err)
}
case "json":
if err := json.Unmarshal(body, &cfg); err != nil {
return nil, fmt.Errorf("parse JSON config: %w", err)
}
default:
return nil, fmt.Errorf("unknown config format %q (want yaml or json)", kind)
}
return &cfg, nil
}
// MergeAgentConfig returns base with hot-path flag overrides applied. Only
// fields whose corresponding *Set bit is true are overridden; the rest of
// base passes through unchanged. The returned pointer is a fresh copy so
// callers can mutate it without aliasing base.
func MergeAgentConfig(base *sdk.AgentConfig, ov AgentConfigFlags) *sdk.AgentConfig {
out := *base // shallow copy
if ov.AgentModeSet {
out.AgentMode = ov.AgentMode
}
if ov.SystemPromptSet {
out.SystemPrompt = ov.SystemPrompt
}
if ov.ModelIDSet {
out.ModelID = ov.ModelID
}
if ov.RerankModelIDSet {
out.RerankModelID = ov.RerankModelID
}
if ov.TemperatureSet {
out.Temperature = ov.Temperature
}
if ov.KBSelectionModeSet {
out.KBSelectionMode = ov.KBSelectionMode
}
if ov.KnowledgeBasesSet {
out.KnowledgeBases = ov.KnowledgeBases
}
return &out
}
// skeletonCommentVersion is embedded in the skeleton header so users
// regenerating an outdated template after a schema bump can spot the
// version mismatch.
const skeletonCommentVersion = "v0.5 / 34 fields"
// GenerateAgentSkeleton writes a commented YAML template with every
// AgentConfig field at its zero value to w. Used by
// `agent create --generate-skeleton` so users get a ready-to-edit
// starting point without authoring the 34-field schema from memory.
func GenerateAgentSkeleton(w io.Writer) error {
const skeleton = `# WeKnora AgentConfig skeleton (` + skeletonCommentVersion + `)
# Edit this file and pass it to:
# weknora agent create "My Agent" --model <id> --config-file <this-file>
# Hot-path flags on the create command override values set here.
# Operating mode: "quick-answer" or "smart-reasoning"
agent_mode: ""
# System prompt for the agent (also settable via --system-prompt[-file])
system_prompt: ""
# Optional template applied to retrieved context before model input
context_template: ""
# REQUIRED: LLM model id (server-side managed); also settable via --model
model_id: ""
# Optional rerank model id (server-side managed); also settable via --rerank-model
rerank_model_id: ""
# Generation tuning
temperature: 0.0
max_completion_tokens: 0
max_iterations: 0
# Tools / MCP integration
allowed_tools: []
mcp_selection_mode: "" # "all" / "selected" / "none"
mcp_services: []
# Knowledge base attachment
kb_selection_mode: "" # "all" / "selected" / "none"; also settable via --kb-selection-mode
knowledge_bases: [] # KB ids; also settable via repeated --kb
supported_file_types: []
# FAQ
faq_priority_enabled: false
faq_direct_answer_threshold: 0.0
faq_score_boost: 0.0
# Web search
web_search_enabled: false
web_search_max_results: 0
# Multi-turn
multi_turn_enabled: false
history_turns: 0
# Retrieval thresholds
embedding_top_k: 0
keyword_threshold: 0.0
vector_threshold: 0.0
rerank_top_k: 0
rerank_threshold: 0.0
# Query understanding / rewrite
enable_query_expansion: false
enable_rewrite: false
rewrite_prompt_system: ""
rewrite_prompt_user: ""
query_understand_model_id: ""
# Fallback when retrieval / generation fails
fallback_strategy: "" # "fixed" or "model"
fallback_response: ""
fallback_prompt: ""
`
_, err := io.WriteString(w, skeleton)
return err
}
+114
View File
@@ -0,0 +1,114 @@
package cmdutil
import (
"strings"
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
sdk "github.com/Tencent/WeKnora/client"
)
func TestLoadConfigFile_YAML(t *testing.T) {
yaml := strings.NewReader(`
agent_mode: smart-reasoning
model_id: gpt-4
temperature: 0.7
knowledge_bases:
- kb_abc
- kb_def
`)
cfg, err := LoadAgentConfig(yaml, "yaml")
require.NoError(t, err)
assert.Equal(t, "smart-reasoning", cfg.AgentMode)
assert.Equal(t, "gpt-4", cfg.ModelID)
assert.InDelta(t, 0.7, cfg.Temperature, 0.001)
assert.Equal(t, []string{"kb_abc", "kb_def"}, cfg.KnowledgeBases)
}
func TestLoadConfigFile_JSON(t *testing.T) {
js := strings.NewReader(`{"agent_mode":"quick-answer","model_id":"gpt-3.5"}`)
cfg, err := LoadAgentConfig(js, "json")
require.NoError(t, err)
assert.Equal(t, "quick-answer", cfg.AgentMode)
assert.Equal(t, "gpt-3.5", cfg.ModelID)
}
func TestLoadConfigFile_UnknownKind(t *testing.T) {
_, err := LoadAgentConfig(strings.NewReader(""), "xml")
require.Error(t, err)
assert.Contains(t, err.Error(), "unknown config format")
}
func TestLoadConfigFile_BadYAML(t *testing.T) {
_, err := LoadAgentConfig(strings.NewReader("not: : yaml"), "yaml")
require.Error(t, err)
}
func TestLoadConfigFile_BadJSON(t *testing.T) {
_, err := LoadAgentConfig(strings.NewReader("{not json"), "json")
require.Error(t, err)
}
func TestMergeAgentConfig_FlagsOverrideFile(t *testing.T) {
base := &sdk.AgentConfig{ModelID: "gpt-3.5"}
overrides := AgentConfigFlags{ModelIDSet: true, ModelID: "gpt-4"}
merged := MergeAgentConfig(base, overrides)
assert.Equal(t, "gpt-4", merged.ModelID)
}
func TestMergeAgentConfig_UnsetFlagsPreserveBase(t *testing.T) {
base := &sdk.AgentConfig{ModelID: "gpt-3.5", Temperature: 0.5}
overrides := AgentConfigFlags{} // nothing set
merged := MergeAgentConfig(base, overrides)
assert.Equal(t, "gpt-3.5", merged.ModelID)
assert.InDelta(t, 0.5, merged.Temperature, 0.001)
}
func TestMergeAgentConfig_EveryFieldOverlay(t *testing.T) {
base := &sdk.AgentConfig{
AgentMode: "quick-answer",
SystemPrompt: "old",
ModelID: "gpt-3.5",
RerankModelID: "rerank-old",
Temperature: 0.1,
KBSelectionMode: "all",
KnowledgeBases: []string{"kb_old"},
}
overrides := AgentConfigFlags{
AgentMode: "smart-reasoning", AgentModeSet: true,
SystemPrompt: "new", SystemPromptSet: true,
ModelID: "gpt-4", ModelIDSet: true,
RerankModelID: "rerank-new", RerankModelIDSet: true,
Temperature: 0.9, TemperatureSet: true,
KBSelectionMode: "selected", KBSelectionModeSet: true,
KnowledgeBases: []string{"kb_new"}, KnowledgeBasesSet: true,
}
merged := MergeAgentConfig(base, overrides)
assert.Equal(t, "smart-reasoning", merged.AgentMode)
assert.Equal(t, "new", merged.SystemPrompt)
assert.Equal(t, "gpt-4", merged.ModelID)
assert.Equal(t, "rerank-new", merged.RerankModelID)
assert.InDelta(t, 0.9, merged.Temperature, 0.001)
assert.Equal(t, "selected", merged.KBSelectionMode)
assert.Equal(t, []string{"kb_new"}, merged.KnowledgeBases)
}
func TestGenerateSkeleton_EmitsAllFields(t *testing.T) {
var out strings.Builder
require.NoError(t, GenerateAgentSkeleton(&out))
body := out.String()
for _, field := range []string{
"agent_mode:",
"model_id:",
"system_prompt:",
"knowledge_bases:",
"fallback_strategy:",
"context_template:",
"max_completion_tokens:",
"embedding_top_k:",
} {
assert.Contains(t, body, field, "skeleton missing field %s", field)
}
}