feat: Enhance AI Agent and Channel Management

- Updated labels in the AI Agents dashboard for clarity, changing "流程状态" to "Playbook 状态" and "未发布流程" to "未发布 Playbook".
- Introduced AI Agent rollout percentage management in channel editing, allowing users to set and rollback rollout percentages.
- Added new API endpoints for rolling back AI Agent rollout and fetching agent run metrics.
- Implemented new UI components for displaying agent run details, including status, duration, and input/output tokens.
- Enhanced type definitions for AdminChannel and AIAgent to include rollout percentages and runtime modes.
- Updated navigation to include a section for agent runs.
- Added new translations for agent run features in both English and Chinese.
This commit is contained in:
mlogclub
2026-07-25 12:04:06 +08:00
parent 45741d4032
commit 34051a4631
101 changed files with 8377 additions and 340 deletions
+67
View File
@@ -0,0 +1,67 @@
package tooling
import (
"context"
"fmt"
"strings"
"time"
"agent-desk/internal/ai/mcps"
"agent-desk/internal/pkg/toolx"
)
// MCPExecutor is the single execution boundary for dynamically discovered
// MCP tools. Engine adapters supply the policy for the current Agent run.
type MCPExecutor struct {
registry *Registry
runtime *mcps.RuntimeService
}
var DefaultMCPExecutor = NewMCPExecutor(DefaultRegistry, mcps.Runtime)
func NewMCPExecutor(registry *Registry, runtime *mcps.RuntimeService) *MCPExecutor {
return &MCPExecutor{registry: registry, runtime: runtime}
}
func (e *MCPExecutor) Execute(ctx context.Context, toolCode string, arguments map[string]any, policy Policy) (Definition, *mcps.ToolCallResult, error) {
definition, err := e.registry.Resolve(toolCode)
if err != nil {
return Definition{}, nil, err
}
if err := DefaultPolicyGuard.Authorize(Invocation{Definition: definition, Arguments: arguments, Policy: policy}); err != nil {
return Definition{}, nil, err
}
serverCode, toolName := toolx.SplitMCPToolCode(strings.TrimSpace(definition.Code))
if serverCode == "" || toolName == "" {
return Definition{}, nil, &UnsupportedExecutionError{ToolCode: definition.Code}
}
if e.runtime == nil {
return Definition{}, nil, fmt.Errorf("MCP executor runtime is not configured")
}
if definition.TimeoutMS > 0 {
var cancel context.CancelFunc
ctx, cancel = context.WithTimeout(ctx, time.Duration(definition.TimeoutMS)*time.Millisecond)
defer cancel()
}
result, err := e.runtime.CallTool(ctx, serverCode, toolName, cloneArguments(arguments))
return definition, result, err
}
type UnsupportedExecutionError struct {
ToolCode string
}
func (e *UnsupportedExecutionError) Error() string {
return "tool is not executable through MCP: " + e.ToolCode
}
func cloneArguments(input map[string]any) map[string]any {
if len(input) == 0 {
return map[string]any{}
}
ret := make(map[string]any, len(input))
for key, value := range input {
ret[key] = value
}
return ret
}
+219
View File
@@ -0,0 +1,219 @@
// Package tooling provides the engine-independent tool governance boundary.
package tooling
import (
"encoding/json"
"fmt"
"strings"
"agent-desk/internal/pkg/enums"
"agent-desk/internal/pkg/toolx"
)
const (
RiskLevelRead = "read"
RiskLevelWrite = "write"
RiskLevelSensitive = "sensitive"
)
// Definition is the normalized, engine-independent description of a tool.
type Definition struct {
Code string
Name string
Description string
InputSchema map[string]any
SourceType enums.ToolSourceType
RiskLevel string
RequireConfirmation bool
MaxCallsPerRun int
TimeoutMS int
IdempotencyMode string
}
// Policy is supplied by the caller's agent/runtime context for one invocation.
// An empty AllowedToolCodes means the caller did not impose an allow-list.
type Policy struct {
AllowedToolCodes []string
SkillAllowedToolCodes []string
AllowedRiskLevels []string
CallCount int
TotalCallCount int
MaxTotalCalls int
MaxArgumentBytes int
Confirmed bool
}
type Invocation struct {
Definition Definition
Arguments map[string]any
Policy Policy
}
// PolicyGuard is the reusable enforcement point for every engine/tool adapter.
type PolicyGuard struct{}
var DefaultPolicyGuard = &PolicyGuard{}
type Registry struct{}
var DefaultRegistry = NewRegistry()
func NewRegistry() *Registry {
return &Registry{}
}
func (r *Registry) Resolve(toolCode string) (Definition, error) {
toolCode = toolx.NormalizeToolCodeAlias(strings.TrimSpace(toolCode))
if toolCode == "" {
return Definition{}, fmt.Errorf("tool code is required")
}
if spec, ok := toolx.GetRegisteredToolSpec(toolCode); ok {
return definitionFromSpec(spec), nil
}
serverCode, toolName := toolx.SplitMCPToolCode(toolCode)
if serverCode == "" || toolName == "" {
return Definition{}, fmt.Errorf("unsupported tool code: %s", toolCode)
}
// MCP metadata cannot reliably describe side effects. Treat it as sensitive
// until an administrator provides a more specific policy in a later phase.
return Definition{
Code: toolCode,
Name: toolName,
InputSchema: map[string]any{"type": "object", "additionalProperties": true},
SourceType: enums.ToolSourceTypeMCP,
RiskLevel: RiskLevelSensitive,
RequireConfirmation: true,
MaxCallsPerRun: 3,
TimeoutMS: 30000,
IdempotencyMode: "caller",
}, nil
}
func (r *Registry) Authorize(definition Definition, policy Policy) error {
return DefaultPolicyGuard.Authorize(Invocation{Definition: definition, Policy: policy})
}
func (g *PolicyGuard) Authorize(invocation Invocation) error {
definition := invocation.Definition
policy := invocation.Policy
if definition.Code == "" {
return fmt.Errorf("tool definition is required")
}
if len(policy.AllowedToolCodes) > 0 && !containsCanonicalToolCode(policy.AllowedToolCodes, definition.Code) {
return fmt.Errorf("tool is not allowed: %s", definition.Code)
}
if len(policy.SkillAllowedToolCodes) > 0 && !containsCanonicalToolCode(policy.SkillAllowedToolCodes, definition.Code) {
return fmt.Errorf("tool is not allowed by the selected skill: %s", definition.Code)
}
if len(policy.AllowedRiskLevels) > 0 && !containsString(policy.AllowedRiskLevels, definition.RiskLevel) {
return fmt.Errorf("tool risk level is not allowed: %s", definition.RiskLevel)
}
if definition.MaxCallsPerRun > 0 && policy.CallCount >= definition.MaxCallsPerRun {
return fmt.Errorf("tool call limit reached: %s", definition.Code)
}
if policy.MaxTotalCalls > 0 && policy.TotalCallCount >= policy.MaxTotalCalls {
return fmt.Errorf("total tool call limit reached")
}
if policy.MaxArgumentBytes > 0 {
encoded, err := json.Marshal(invocation.Arguments)
if err != nil {
return fmt.Errorf("tool arguments are not serializable: %w", err)
}
if len(encoded) > policy.MaxArgumentBytes {
return fmt.Errorf("tool arguments exceed size limit: %s", definition.Code)
}
}
if definition.RequireConfirmation && !policy.Confirmed {
return fmt.Errorf("tool confirmation is required: %s", definition.Code)
}
return nil
}
func definitionFromSpec(spec toolx.ToolSpec) Definition {
definition := Definition{
Code: spec.Code,
Name: spec.Name,
Description: spec.Description,
SourceType: spec.SourceType,
RiskLevel: RiskLevelRead,
MaxCallsPerRun: 8,
TimeoutMS: 15000,
IdempotencyMode: "none",
}
switch spec.Code {
case toolx.BuiltinConversationContext.Code:
definition.InputSchema = objectSchema(map[string]any{})
case toolx.BuiltinKnowledgeRetrieve.Code:
definition.InputSchema = requiredObjectSchema([]string{"query"}, map[string]any{"query": map[string]any{"type": "string"}})
case toolx.GraphTriageServiceRequest.Code:
definition.InputSchema = objectSchema(map[string]any{
"goal": map[string]any{"type": "string"},
"observedIssue": map[string]any{"type": "string"},
"needTicket": map[string]any{"type": "boolean"},
"needHumanHandoff": map[string]any{"type": "boolean"},
"additionalContext": map[string]any{"type": "string"},
})
case toolx.GraphAnalyzeConversation.Code:
definition.InputSchema = objectSchema(map[string]any{
"goal": map[string]any{"type": "string"},
"observedIssue": map[string]any{"type": "string"},
"needTicket": map[string]any{"type": "boolean"},
"needHumanHandoff": map[string]any{"type": "boolean"},
"needQualityCheck": map[string]any{"type": "boolean"},
"additionalContext": map[string]any{"type": "string"},
})
case toolx.GraphPrepareTicketDraft.Code:
definition.InputSchema = objectSchema(map[string]any{
"title": map[string]any{"type": "string"},
"description": map[string]any{"type": "string"},
"issue": map[string]any{"type": "string"},
"impact": map[string]any{"type": "string"},
"expectedOutcome": map[string]any{"type": "string"},
"currentAttempt": map[string]any{"type": "string"},
})
case toolx.GraphCreateTicketConfirm.Code:
definition.RiskLevel = RiskLevelWrite
definition.RequireConfirmation = true
definition.MaxCallsPerRun = 1
definition.IdempotencyMode = "business"
definition.InputSchema = requiredObjectSchema([]string{"title", "description"}, map[string]any{
"title": map[string]any{"type": "string"}, "description": map[string]any{"type": "string"},
})
case toolx.GraphHandoffConversation.Code:
definition.RiskLevel = RiskLevelWrite
definition.RequireConfirmation = true
definition.MaxCallsPerRun = 1
definition.IdempotencyMode = "business"
definition.InputSchema = objectSchema(map[string]any{"reason": map[string]any{"type": "string"}})
}
return definition
}
func objectSchema(properties map[string]any) map[string]any {
return map[string]any{"type": "object", "properties": properties}
}
func requiredObjectSchema(required []string, properties map[string]any) map[string]any {
schema := objectSchema(properties)
schema["required"] = required
return schema
}
func containsString(items []string, target string) bool {
for _, item := range items {
if strings.EqualFold(strings.TrimSpace(item), strings.TrimSpace(target)) {
return true
}
}
return false
}
func containsCanonicalToolCode(items []string, target string) bool {
target = toolx.NormalizeToolCodeAlias(strings.TrimSpace(target))
for _, item := range items {
if toolx.NormalizeToolCodeAlias(strings.TrimSpace(item)) == target {
return true
}
}
return false
}
+139
View File
@@ -0,0 +1,139 @@
package tooling
import (
"strings"
"testing"
"agent-desk/internal/pkg/toolx"
)
func TestRegistryResolvesRegisteredToolPolicy(t *testing.T) {
definition, err := DefaultRegistry.Resolve(toolx.GraphCreateTicketConfirm.Code)
if err != nil {
t.Fatalf("Resolve returned error: %v", err)
}
if definition.RiskLevel != RiskLevelWrite || !definition.RequireConfirmation || definition.MaxCallsPerRun != 1 {
t.Fatalf("unexpected definition: %#v", definition)
}
if err := DefaultRegistry.Authorize(definition, Policy{AllowedToolCodes: []string{toolx.GraphCreateTicketConfirm.Code}}); err == nil {
t.Fatal("expected confirmation requirement")
}
}
func TestRegistryIncludesGraphInputSchemaAndRiskPolicy(t *testing.T) {
definition, err := DefaultRegistry.Resolve(toolx.GraphCreateTicketConfirm.Code)
if err != nil {
t.Fatalf("Resolve returned error: %v", err)
}
if definition.InputSchema["type"] != "object" || len(definition.InputSchema["required"].([]string)) != 2 {
t.Fatalf("unexpected graph schema: %#v", definition.InputSchema)
}
if err := DefaultPolicyGuard.Authorize(Invocation{Definition: definition, Policy: Policy{
AllowedToolCodes: []string{definition.Code}, AllowedRiskLevels: []string{RiskLevelRead}, Confirmed: true,
}}); err == nil || !strings.Contains(err.Error(), "risk level") {
t.Fatalf("expected risk policy rejection, got %v", err)
}
}
func TestRegistryRequiresConfirmationForHandoff(t *testing.T) {
definition, err := DefaultRegistry.Resolve(toolx.GraphHandoffConversation.Code)
if err != nil {
t.Fatalf("Resolve returned error: %v", err)
}
if definition.RiskLevel != RiskLevelWrite || !definition.RequireConfirmation || definition.IdempotencyMode != "business" {
t.Fatalf("unexpected handoff policy: %#v", definition)
}
if err := DefaultRegistry.Authorize(definition, Policy{AllowedToolCodes: []string{definition.Code}, AllowedRiskLevels: []string{RiskLevelWrite}}); err == nil || !strings.Contains(err.Error(), "confirmation") {
t.Fatalf("expected handoff confirmation rejection, got %v", err)
}
}
func TestRegistryIncludesAllTicketDraftToolInputs(t *testing.T) {
definition, err := DefaultRegistry.Resolve(toolx.GraphPrepareTicketDraft.Code)
if err != nil {
t.Fatalf("Resolve returned error: %v", err)
}
properties, _ := definition.InputSchema["properties"].(map[string]any)
for _, key := range []string{"title", "description", "issue", "impact", "expectedOutcome", "currentAttempt"} {
if _, ok := properties[key]; !ok {
t.Fatalf("ticket draft schema missing %q: %#v", key, definition.InputSchema)
}
}
}
func TestRegistryTreatsMCPToolsAsSensitive(t *testing.T) {
definition, err := DefaultRegistry.Resolve("knowledge/search")
if err != nil {
t.Fatalf("Resolve returned error: %v", err)
}
if definition.RiskLevel != RiskLevelSensitive || !definition.RequireConfirmation {
t.Fatalf("unexpected MCP definition: %#v", definition)
}
if err := DefaultRegistry.Authorize(definition, Policy{AllowedToolCodes: []string{"knowledge/search"}, Confirmed: true}); err != nil {
t.Fatalf("Authorize returned error: %v", err)
}
}
func TestSanitizePreviewMasksAndBoundsSecrets(t *testing.T) {
preview := SanitizePreview(`authorization=Bearer-secret {"token":"abc123"}`)
if strings.Contains(preview, "Bearer-secret") || strings.Contains(preview, "abc123") {
t.Fatalf("secret leaked in preview: %q", preview)
}
}
func TestNormalizeCustomerReplyRejectsSecretAndNormalizesText(t *testing.T) {
if _, err := NormalizeCustomerReply("token=abc123"); err == nil {
t.Fatal("expected sensitive reply to be rejected")
}
reply, err := NormalizeCustomerReply(" first\x00\n\n\n\nsecond ")
if err != nil || reply != "first\n\nsecond" {
t.Fatalf("unexpected normalized reply: %q err=%v", reply, err)
}
}
func TestMCPExecutorRejectsUnconfirmedToolBeforeRuntimeCall(t *testing.T) {
executor := NewMCPExecutor(DefaultRegistry, nil)
_, _, err := executor.Execute(t.Context(), "knowledge/search", nil, Policy{
AllowedToolCodes: []string{"knowledge/search"},
})
if err == nil || !strings.Contains(err.Error(), "confirmation") {
t.Fatalf("expected confirmation rejection, got %v", err)
}
}
func TestPolicyGuardRejectsTotalCallsAndOversizedArguments(t *testing.T) {
definition, err := DefaultRegistry.Resolve("knowledge/search")
if err != nil {
t.Fatalf("Resolve returned error: %v", err)
}
if err := DefaultPolicyGuard.Authorize(Invocation{
Definition: definition,
Policy: Policy{AllowedToolCodes: []string{definition.Code}, Confirmed: true, TotalCallCount: 2, MaxTotalCalls: 2},
}); err == nil || !strings.Contains(err.Error(), "total") {
t.Fatalf("expected total call rejection, got %v", err)
}
if err := DefaultPolicyGuard.Authorize(Invocation{
Definition: definition, Arguments: map[string]any{"query": strings.Repeat("x", 40)},
Policy: Policy{AllowedToolCodes: []string{definition.Code}, Confirmed: true, MaxArgumentBytes: 16},
}); err == nil || !strings.Contains(err.Error(), "size") {
t.Fatalf("expected argument size rejection, got %v", err)
}
}
func TestPolicyGuardRejectsToolOutsideSelectedSkillWhitelist(t *testing.T) {
definition, err := DefaultRegistry.Resolve("knowledge/search")
if err != nil {
t.Fatalf("Resolve returned error: %v", err)
}
err = DefaultPolicyGuard.Authorize(Invocation{
Definition: definition,
Policy: Policy{
AllowedToolCodes: []string{"knowledge/search"},
SkillAllowedToolCodes: []string{"customer/profile"},
Confirmed: true,
},
})
if err == nil || !strings.Contains(err.Error(), "selected skill") {
t.Fatalf("expected skill whitelist rejection, got %v", err)
}
}
+41
View File
@@ -0,0 +1,41 @@
package tooling
import (
"fmt"
"strings"
"unicode"
)
const maxCustomerReplyRunes = 8000
// NormalizeCustomerReply applies the final plain-text boundary before an AI
// response enters a customer conversation. It rejects likely credential
// assignments instead of masking them, because a masked secret is not useful
// customer-facing content.
func NormalizeCustomerReply(value string) (string, error) {
value = strings.TrimSpace(value)
if value == "" {
return "", fmt.Errorf("ai reply is empty")
}
if secretAssignmentPattern.MatchString(value) {
return "", fmt.Errorf("ai reply contains sensitive credential data")
}
var builder strings.Builder
for _, r := range value {
if unicode.IsControl(r) && r != '\n' && r != '\t' {
continue
}
builder.WriteRune(r)
}
value = strings.TrimSpace(builder.String())
for strings.Contains(value, "\n\n\n") {
value = strings.ReplaceAll(value, "\n\n\n", "\n\n")
}
if value == "" {
return "", fmt.Errorf("ai reply is empty")
}
if len([]rune(value)) > maxCustomerReplyRunes {
return "", fmt.Errorf("ai reply exceeds maximum length")
}
return value, nil
}
+25
View File
@@ -0,0 +1,25 @@
package tooling
import (
"regexp"
"strings"
)
const maxPreviewChars = 4000
var secretAssignmentPattern = regexp.MustCompile(`(?i)(?:"|')?(api[_-]?key|authorization|password|secret|token|cookie)(?:"|')?\s*([:=])\s*(?:"[^"]*"|'[^']*'|[^\s,;}]+)`)
// SanitizePreview keeps audit/model previews bounded and masks common secrets.
// It intentionally operates on plain text so it also covers malformed JSON.
func SanitizePreview(value string) string {
value = strings.TrimSpace(value)
if value == "" {
return ""
}
value = secretAssignmentPattern.ReplaceAllString(value, "$1$2***")
runes := []rune(value)
if len(runes) <= maxPreviewChars {
return value
}
return strings.TrimSpace(string(runes[:maxPreviewChars])) + "\n[preview truncated]"
}