Add files via upload

internal/handler/agent_progress_callback_test.go

@@ -0,0 +1,242 @@
+package handler
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/openai"
+
+	"go.uber.org/zap"
+)
+
+// TestCreateProgressCallback_ConcurrentToolEvents 回归 issue #142：并行 tool 回调不得 concurrent map panic。
+func TestCreateProgressCallback_ConcurrentToolEvents(t *testing.T) {
+	logger := zap.NewNop()
+	h := &AgentHandler{
+		logger: logger,
+		config: &config.Config{},
+	}
+	cb := h.createProgressCallback(context.Background(), nil, "conv-race-test", "", nil)
+
+	const workers = 64
+	var wg sync.WaitGroup
+	wg.Add(workers * 2)
+	for i := 0; i < workers; i++ {
+		i := i
+		go func() {
+			defer wg.Done()
+			toolCallID := fmt.Sprintf("tc-%d", i)
+			cb("tool_call", "calling skill", map[string]interface{}{
+				"toolCallId":   toolCallID,
+				"toolName":     "skill",
+				"argumentsObj": map[string]interface{}{"skill_name": "demo-skill"},
+			})
+		}()
+		go func() {
+			defer wg.Done()
+			toolCallID := fmt.Sprintf("tc-%d", i)
+			cb("tool_result", "skill done", map[string]interface{}{
+				"toolCallId": toolCallID,
+				"toolName":   "skill",
+				"success":    true,
+			})
+		}()
+	}
+	wg.Wait()
+}
+
+// TestCreateProgressCallback_MirrorsWebStreamEvents 页面刷新后 task-events 订阅必须
+// 继续收到原 Web SSE 任务的后续事件，不能只等数据库最终结果。
+func TestCreateProgressCallback_MirrorsWebStreamEvents(t *testing.T) {
+	bus := NewTaskEventBus()
+	h := &AgentHandler{logger: zap.NewNop(), config: &config.Config{}, taskEventBus: bus}
+	_, events := bus.Subscribe("conv-refresh-stream")
+	primaryCalls := 0
+	cb := h.createProgressCallback(
+		context.Background(), nil, "conv-refresh-stream", "",
+		func(eventType, message string, data interface{}) { primaryCalls++ },
+	)
+
+	cb("progress", "第 3 轮", map[string]interface{}{"iteration": 3})
+	if primaryCalls != 1 {
+		t.Fatalf("expected primary SSE callback once, got %d", primaryCalls)
+	}
+	select {
+	case payload := <-events:
+		body := string(payload)
+		if !strings.Contains(body, `"type":"progress"`) || !strings.Contains(body, `"conversationId":"conv-refresh-stream"`) {
+			t.Fatalf("unexpected mirrored event: %s", body)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("expected progress event mirrored to task event bus")
+	}
+}
+
+func TestCreateProgressCallback_HidesInternalEinoDiagnostics(t *testing.T) {
+	tmp := t.TempDir()
+	db, err := database.NewDB(filepath.Join(tmp, "test.sqlite"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewDB: %v", err)
+	}
+	conv, err := db.CreateConversation("diag-hidden", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("CreateConversation: %v", err)
+	}
+	asst, err := db.AddMessage(conv.ID, "assistant", "处理中...", nil)
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+	bus := NewTaskEventBus()
+	h := &AgentHandler{logger: zap.NewNop(), db: db, taskEventBus: bus}
+	_, events := bus.Subscribe(conv.ID)
+	primaryCalls := 0
+	cb := h.createProgressCallback(
+		context.Background(), nil, conv.ID, asst.ID,
+		func(string, string, interface{}) { primaryCalls++ },
+	)
+
+	cb("model_output_rejected", "模型工具调用不完整或参数不安全，已阻止执行并要求重写。", map[string]interface{}{
+		"reason": "invalid_tool_arguments_json",
+	})
+	cb("progress", "Eino TurnLoop 常驻多轮 runtime 已接管本轮会话。", map[string]interface{}{
+		"kind": "turn_loop_takeover",
+	})
+
+	if primaryCalls != 0 {
+		t.Fatalf("primary SSE calls = %d, want hidden diagnostics", primaryCalls)
+	}
+	select {
+	case payload := <-events:
+		t.Fatalf("unexpected mirrored diagnostic event: %s", string(payload))
+	default:
+	}
+	details, err := db.GetProcessDetails(asst.ID)
+	if err != nil {
+		t.Fatalf("GetProcessDetails: %v", err)
+	}
+	if len(details) != 0 {
+		t.Fatalf("process details = %+v, want no diagnostics persisted", details)
+	}
+}
+
+func TestCreateProgressCallback_PersistsRunningResponseBeforeDone(t *testing.T) {
+	tmp := t.TempDir()
+	db, err := database.NewDB(filepath.Join(tmp, "test.sqlite"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewDB: %v", err)
+	}
+	conv, err := db.CreateConversation("refresh-running", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("CreateConversation: %v", err)
+	}
+	asst, err := db.AddMessage(conv.ID, "assistant", "处理中...", nil)
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+
+	h := &AgentHandler{logger: zap.NewNop(), db: db}
+	cb := h.createProgressCallback(context.Background(), nil, conv.ID, asst.ID, nil)
+	meta := map[string]interface{}{
+		"streamId":      "response-refresh-1",
+		"einoAgent":     "cyberstrike-eino-single",
+		"orchestration": "eino_single",
+	}
+	cb("response_start", "", meta)
+	cb("response_delta", "刷新前已生成的第一部分", openai.WithSSEAccumulated(meta, "刷新前已生成的第一部分"))
+
+	details, err := db.GetProcessDetails(asst.ID)
+	if err != nil {
+		t.Fatalf("GetProcessDetails: %v", err)
+	}
+	if len(details) != 1 || details[0].EventType != "planning" || details[0].Message != "刷新前已生成的第一部分" {
+		t.Fatalf("expected one running planning snapshot, got %+v", details)
+	}
+
+	longer := "刷新前已生成的第一部分" + strings.Repeat("继续迭代", 300)
+	cb("response_delta", "继续迭代", openai.WithSSEAccumulated(meta, longer))
+	details, err = db.GetProcessDetails(asst.ID)
+	if err != nil {
+		t.Fatalf("GetProcessDetails after update: %v", err)
+	}
+	if len(details) != 1 || details[0].Message != longer {
+		t.Fatalf("running snapshot should update in-place, rows=%d len=%d", len(details), len(details[0].Message))
+	}
+}
+
+// TestCreateProgressCallback_FlushesReasoningOnDone 流式推理聚合须在 done/response 时落库，刷新后可回放。
+func TestCreateProgressCallback_FlushesReasoningOnDone(t *testing.T) {
+	tmp := t.TempDir()
+	db, err := database.NewDB(filepath.Join(tmp, "test.sqlite"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewDB: %v", err)
+	}
+	defer os.RemoveAll(tmp)
+
+	conv, err := db.CreateConversation("test", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("CreateConversation: %v", err)
+	}
+	asst, err := db.AddMessage(conv.ID, "assistant", "处理中...", nil)
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+
+	h := &AgentHandler{logger: zap.NewNop(), db: db}
+	cb := h.createProgressCallback(context.Background(), nil, conv.ID, asst.ID, nil)
+
+	streamID := "eino-reasoning-test-1"
+	cb("reasoning_chain_stream_start", " ", map[string]interface{}{
+		"streamId": streamID,
+		"source":   "eino",
+	})
+	cb("reasoning_chain_stream_delta", "step one", openai.WithSSEAccumulated(map[string]interface{}{
+		"streamId": streamID,
+	}, "step one"))
+	cb("done", "", map[string]interface{}{"conversationId": conv.ID})
+
+	details, err := db.GetProcessDetails(asst.ID)
+	if err != nil {
+		t.Fatalf("GetProcessDetails: %v", err)
+	}
+	found := false
+	for _, d := range details {
+		if d.EventType == "reasoning_chain" && d.Message == "step one" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatalf("expected reasoning_chain persisted on done, got %+v", details)
+	}
+}
+
+func TestEnrichProgressEventData(t *testing.T) {
+	t.Run("fills ids", func(t *testing.T) {
+		out := enrichProgressEventData(map[string]interface{}{"source": "eino"}, "conv-1", "msg-1")
+		m, ok := out.(map[string]interface{})
+		if !ok {
+			t.Fatalf("expected map, got %T", out)
+		}
+		if m["conversationId"] != "conv-1" || m["messageId"] != "msg-1" {
+			t.Fatalf("unexpected enrichment: %+v", m)
+		}
+	})
+	t.Run("preserves existing ids", func(t *testing.T) {
+		out := enrichProgressEventData(map[string]interface{}{
+			"conversationId": "keep-conv",
+			"messageId":      "keep-msg",
+		}, "conv-1", "msg-1")
+		m := out.(map[string]interface{})
+		if m["conversationId"] != "keep-conv" || m["messageId"] != "keep-msg" {
+			t.Fatalf("should not overwrite existing ids: %+v", m)
+		}
+	})
+}

internal/handler/asset.go

@@ -0,0 +1,540 @@
+package handler
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+type AssetHandler struct {
+	db     *database.DB
+	logger *zap.Logger
+}
+
+const (
+	maxAssetImportBatch    = 100000
+	maxAssetOperationBatch = 10000
+)
+
+func NewAssetHandler(db *database.DB, logger *zap.Logger) *AssetHandler {
+	return &AssetHandler{db: db, logger: logger}
+}
+
+func assetAccess(c *gin.Context) database.RBACListAccess {
+	if session, ok := security.CurrentSession(c); ok {
+		return database.RBACListAccess{UserID: session.UserID, Scope: session.Scope}
+	}
+	return database.RBACListAccess{}
+}
+
+func assetAccessForPermission(c *gin.Context, permission string) database.RBACListAccess {
+	if session, ok := security.CurrentSession(c); ok {
+		return database.RBACListAccess{UserID: session.UserID, Scope: session.ScopeFor(permission)}
+	}
+	return database.RBACListAccess{}
+}
+
+type importAssetsRequest struct {
+	Assets      []*database.Asset `json:"assets" binding:"required"`
+	Source      string            `json:"source"`
+	SourceQuery string            `json:"source_query"`
+}
+
+type assetScanLink struct {
+	AssetID        string `json:"asset_id" binding:"required"`
+	ConversationID string `json:"conversation_id"`
+	QueueID        string `json:"queue_id"`
+	TaskID         string `json:"task_id"`
+}
+
+type recordAssetScansRequest struct {
+	Scans []assetScanLink `json:"scans" binding:"required"`
+}
+
+type updateAssetsProjectRequest struct {
+	AssetIDs  []string `json:"asset_ids" binding:"required"`
+	ProjectID string   `json:"project_id"`
+}
+
+type bulkUpdateAssetsRequest struct {
+	AssetIDs          []string `json:"asset_ids" binding:"required"`
+	Status            *string  `json:"status"`
+	ResponsiblePerson *string  `json:"responsible_person"`
+	Department        *string  `json:"department"`
+	BusinessSystem    *string  `json:"business_system"`
+	Environment       *string  `json:"environment"`
+	Criticality       *string  `json:"criticality"`
+	AddTags           []string `json:"add_tags"`
+	RemoveTags        []string `json:"remove_tags"`
+}
+
+type assetIDsRequest struct {
+	AssetIDs []string `json:"asset_ids" binding:"required"`
+}
+
+type mergeAssetsRequest struct {
+	AssetIDs  []string `json:"asset_ids" binding:"required"`
+	PrimaryID string   `json:"primary_id"`
+}
+
+func (h *AssetHandler) Import(c *gin.Context) {
+	var req importAssetsRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if len(req.Assets) == 0 || len(req.Assets) > maxAssetImportBatch {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "assets 数量必须在 1-100000 之间"})
+		return
+	}
+	owner := ""
+	allowGlobal := false
+	if session, ok := security.CurrentSession(c); ok {
+		owner = session.UserID
+		allowGlobal = session.Scope == database.RBACScopeAll
+	}
+	for _, asset := range req.Assets {
+		if asset == nil {
+			continue
+		}
+		if strings.TrimSpace(asset.ProjectID) != "" {
+			if session, ok := security.CurrentSession(c); ok && !h.db.UserCanAccessResource(session.UserID, session.Scope, "project", strings.TrimSpace(asset.ProjectID)) {
+				c.JSON(http.StatusForbidden, gin.H{"error": "无权绑定该项目"})
+				return
+			}
+		}
+		if strings.TrimSpace(asset.Source) == "" {
+			asset.Source = strings.TrimSpace(req.Source)
+		}
+		if strings.TrimSpace(asset.SourceQuery) == "" {
+			asset.SourceQuery = strings.TrimSpace(req.SourceQuery)
+		}
+	}
+	result, err := h.db.UpsertAssets(req.Assets, owner, allowGlobal)
+	if err != nil {
+		var validationErr *database.AssetValidationError
+		if errors.As(err, &validationErr) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		h.logger.Error("导入资产失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, result)
+}
+
+func (h *AssetHandler) List(c *gin.Context) {
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	pageSize, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
+	if page < 1 {
+		page = 1
+	}
+	if pageSize < 1 || pageSize > 100 {
+		pageSize = 20
+	}
+	filter, err := assetListFilterFromQuery(c)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	assets, total, err := h.db.ListAssets(pageSize, (page-1)*pageSize, filter, assetAccess(c))
+	if err != nil {
+		h.logger.Error("加载资产失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	totalPages := (total + pageSize - 1) / pageSize
+	if totalPages < 1 {
+		totalPages = 1
+	}
+	c.JSON(http.StatusOK, gin.H{"assets": assets, "total": total, "page": page, "page_size": pageSize, "total_pages": totalPages})
+}
+
+func assetListFilterFromQuery(c *gin.Context) (database.AssetListFilter, error) {
+	filter := database.AssetListFilter{
+		Search: strings.TrimSpace(c.Query("q")), Status: strings.ToLower(strings.TrimSpace(c.Query("status"))),
+		Protocol: strings.ToLower(strings.TrimSpace(c.Query("protocol"))), ProjectID: strings.TrimSpace(c.Query("project_id")),
+		Source: strings.TrimSpace(c.Query("source")), Tag: strings.TrimSpace(c.Query("tag")), Host: strings.TrimSpace(c.Query("host")),
+		IP: strings.TrimSpace(c.Query("ip")), Domain: strings.TrimSpace(c.Query("domain")), ScanState: strings.ToLower(strings.TrimSpace(c.Query("scan_state"))),
+		SortBy: strings.ToLower(strings.TrimSpace(c.Query("sort_by"))), SortOrder: strings.ToLower(strings.TrimSpace(c.Query("sort_order"))),
+		RiskLevel: strings.ToLower(strings.TrimSpace(c.Query("risk_level"))),
+		Country:   strings.TrimSpace(c.Query("country")), Province: strings.TrimSpace(c.Query("province")), City: strings.TrimSpace(c.Query("city")),
+		ResponsiblePerson: strings.TrimSpace(c.Query("responsible_person")), Department: strings.TrimSpace(c.Query("department")),
+		BusinessSystem: strings.TrimSpace(c.Query("business_system")), Environment: strings.ToLower(strings.TrimSpace(c.Query("environment"))),
+		Criticality: strings.ToLower(strings.TrimSpace(c.Query("criticality"))),
+	}
+	if raw := strings.TrimSpace(c.Query("port")); raw != "" {
+		port, err := strconv.Atoi(raw)
+		if err != nil || port < 0 || port > 65535 {
+			return filter, &assetQueryError{field: "port", value: raw}
+		}
+		filter.Port = &port
+	}
+	for field, target := range map[string]**int{
+		"min_vulnerabilities": &filter.MinVulnerabilities,
+		"max_vulnerabilities": &filter.MaxVulnerabilities,
+		"scan_overdue_days":   &filter.ScanOverdueDays,
+	} {
+		raw := strings.TrimSpace(c.Query(field))
+		if raw == "" {
+			continue
+		}
+		value, err := strconv.Atoi(raw)
+		if err != nil || value < 0 || (field == "scan_overdue_days" && value == 0) {
+			return filter, &assetQueryError{field: field, value: raw}
+		}
+		*target = &value
+	}
+	var err error
+	if filter.LastScanBefore, err = parseAssetQueryTime("last_scan_before", c.Query("last_scan_before")); err != nil {
+		return filter, err
+	}
+	if filter.LastScanAfter, err = parseAssetQueryTime("last_scan_after", c.Query("last_scan_after")); err != nil {
+		return filter, err
+	}
+	if filter.FirstSeenBefore, err = parseAssetQueryTime("first_seen_before", c.Query("first_seen_before")); err != nil {
+		return filter, err
+	}
+	if filter.FirstSeenAfter, err = parseAssetQueryTime("first_seen_after", c.Query("first_seen_after")); err != nil {
+		return filter, err
+	}
+	if filter.LastSeenBefore, err = parseAssetQueryTime("last_seen_before", c.Query("last_seen_before")); err != nil {
+		return filter, err
+	}
+	if filter.LastSeenAfter, err = parseAssetQueryTime("last_seen_after", c.Query("last_seen_after")); err != nil {
+		return filter, err
+	}
+	return filter, nil
+}
+
+// Selection resolves all assets matching the current filter for cross-page actions.
+func (h *AssetHandler) Selection(c *gin.Context) {
+	filter, err := assetListFilterFromQuery(c)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	assets, total, err := h.db.ListAssetsForOperation(maxAssetOperationBatch, filter, assetAccess(c))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error(), "total": total})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"assets": assets, "total": total})
+}
+
+type assetQueryError struct{ field, value string }
+
+func (e *assetQueryError) Error() string {
+	return e.field + " 参数无效: " + e.value
+}
+
+func parseAssetQueryTime(field, value string) (*time.Time, error) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return nil, nil
+	}
+	for _, layout := range []string{time.RFC3339, "2006-01-02"} {
+		if parsed, err := time.Parse(layout, value); err == nil {
+			return &parsed, nil
+		}
+	}
+	return nil, &assetQueryError{field: field, value: value}
+}
+
+func (h *AssetHandler) Stats(c *gin.Context) {
+	days := 30
+	if raw := strings.TrimSpace(c.Query("days")); raw != "" {
+		parsed, err := strconv.Atoi(raw)
+		if err != nil || (parsed != 7 && parsed != 30 && parsed != 90) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "days 仅支持 7、30 或 90"})
+			return
+		}
+		days = parsed
+	}
+	stats, err := h.db.GetAssetStats(assetAccess(c), days)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, stats)
+}
+
+// RecordScans stores the execution link created by the asset-library scan action.
+func (h *AssetHandler) RecordScans(c *gin.Context) {
+	var req recordAssetScansRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if len(req.Scans) == 0 || len(req.Scans) > maxAssetOperationBatch {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "scans 数量必须在 1-10000 之间"})
+		return
+	}
+	access := assetAccess(c)
+	for _, scan := range req.Scans {
+		conversationID := strings.TrimSpace(scan.ConversationID)
+		queueID := strings.TrimSpace(scan.QueueID)
+		taskID := strings.TrimSpace(scan.TaskID)
+		if conversationID == "" && taskID == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "conversation_id 或 task_id 至少需要一个"})
+			return
+		}
+		if taskID != "" && (queueID == "" || !h.db.BatchTaskBelongsToQueue(taskID, queueID)) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "任务不属于指定队列"})
+			return
+		}
+		if _, err := h.db.GetAsset(strings.TrimSpace(scan.AssetID), access); err != nil {
+			c.JSON(http.StatusForbidden, gin.H{"error": "资产不存在或无权扫描"})
+			return
+		}
+		if session, ok := security.CurrentSession(c); ok {
+			if id := conversationID; id != "" && !h.db.UserCanAccessResource(session.UserID, session.Scope, "conversation", id) {
+				c.JSON(http.StatusForbidden, gin.H{"error": "无权关联该对话"})
+				return
+			}
+			if id := queueID; id != "" && !h.db.UserCanAccessResource(session.UserID, session.Scope, "batch_task", id) {
+				c.JSON(http.StatusForbidden, gin.H{"error": "无权关联该任务队列"})
+				return
+			}
+		}
+	}
+	for _, scan := range req.Scans {
+		if err := h.db.MarkAssetScanned(scan.AssetID, scan.ConversationID, scan.QueueID, scan.TaskID, access); err != nil {
+			h.logger.Error("记录资产扫描失败", zap.String("asset_id", scan.AssetID), zap.Error(err))
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+	}
+	c.JSON(http.StatusOK, gin.H{"updated": len(req.Scans)})
+}
+
+func (h *AssetHandler) Update(c *gin.Context) {
+	var asset database.Asset
+	if err := c.ShouldBindJSON(&asset); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if asset.ProjectID != "" {
+		if session, ok := security.CurrentSession(c); ok && !h.db.UserCanAccessResource(session.UserID, session.Scope, "project", asset.ProjectID) {
+			c.JSON(http.StatusForbidden, gin.H{"error": "无权绑定该项目"})
+			return
+		}
+	}
+	if err := h.db.UpdateAsset(c.Param("id"), &asset, assetAccess(c)); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	updated, err := h.db.GetAsset(c.Param("id"), assetAccess(c))
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "资产不存在"})
+		return
+	}
+	c.JSON(http.StatusOK, updated)
+}
+
+// UpdateProjectBinding replaces the project binding for a selected asset set.
+func (h *AssetHandler) UpdateProjectBinding(c *gin.Context) {
+	var req updateAssetsProjectRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if len(req.AssetIDs) == 0 || len(req.AssetIDs) > maxAssetOperationBatch {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "asset_ids 数量必须在 1-10000 之间"})
+		return
+	}
+	req.ProjectID = strings.TrimSpace(req.ProjectID)
+	if req.ProjectID != "" {
+		if _, err := h.db.GetProject(req.ProjectID); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "项目不存在"})
+			return
+		}
+		if session, ok := security.CurrentSession(c); ok && !h.db.UserCanAccessResource(session.UserID, session.Scope, "project", req.ProjectID) {
+			c.JSON(http.StatusForbidden, gin.H{"error": "无权绑定该项目"})
+			return
+		}
+	}
+	updated, err := h.db.UpdateAssetsProject(req.AssetIDs, req.ProjectID, assetAccess(c))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"updated": updated, "project_id": req.ProjectID})
+}
+
+func (h *AssetHandler) BulkUpdate(c *gin.Context) {
+	var req bulkUpdateAssetsRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if len(req.AssetIDs) == 0 || len(req.AssetIDs) > maxAssetOperationBatch {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "asset_ids 数量必须在 1-10000 之间"})
+		return
+	}
+	updated, err := h.db.UpdateAssetsBulk(req.AssetIDs, database.AssetBulkPatch{
+		Status: req.Status, ResponsiblePerson: req.ResponsiblePerson, Department: req.Department,
+		BusinessSystem: req.BusinessSystem, Environment: req.Environment, Criticality: req.Criticality,
+		AddTags: req.AddTags, RemoveTags: req.RemoveTags,
+	}, assetAccess(c))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"updated": updated})
+}
+
+func (h *AssetHandler) BatchDelete(c *gin.Context) {
+	var req assetIDsRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if len(req.AssetIDs) == 0 || len(req.AssetIDs) > maxAssetOperationBatch {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "asset_ids 数量必须在 1-10000 之间"})
+		return
+	}
+	deleted, err := h.db.DeleteAssets(req.AssetIDs, assetAccess(c))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"deleted": deleted})
+}
+
+func assetIdentityKeys(asset *database.Asset) map[string]struct{} {
+	keys := map[string]struct{}{}
+	if value := strings.ToLower(strings.TrimSpace(asset.Domain)); value != "" {
+		keys["domain:"+value] = struct{}{}
+	}
+	if value := strings.ToLower(strings.Trim(strings.TrimSpace(asset.IP), "[]")); value != "" {
+		keys["ip:"+value] = struct{}{}
+	}
+	if value := strings.ToLower(strings.TrimSpace(asset.Host)); value != "" {
+		keys["host:"+value] = struct{}{}
+	}
+	return keys
+}
+
+func shareAssetIdentity(left, right *database.Asset) bool {
+	for key := range assetIdentityKeys(left) {
+		if _, ok := assetIdentityKeys(right)[key]; ok {
+			return true
+		}
+	}
+	return false
+}
+
+// Merge keeps the selected primary asset and safely combines compatible duplicate metadata.
+func (h *AssetHandler) Merge(c *gin.Context) {
+	var req mergeAssetsRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if len(req.AssetIDs) < 2 || len(req.AssetIDs) > 100 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "合并资产数量必须在 2-100 之间"})
+		return
+	}
+	writeAccess := assetAccessForPermission(c, "asset:write")
+	deleteAccess := assetAccessForPermission(c, "asset:delete")
+	primaryID := strings.TrimSpace(req.PrimaryID)
+	if primaryID == "" {
+		primaryID = strings.TrimSpace(req.AssetIDs[0])
+	}
+	primary, err := h.db.GetAsset(primaryID, writeAccess)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "主资产不存在或无权访问"})
+		return
+	}
+	others := make([]*database.Asset, 0, len(req.AssetIDs)-1)
+	seen := map[string]struct{}{primaryID: {}}
+	for _, id := range req.AssetIDs {
+		id = strings.TrimSpace(id)
+		if id == "" || id == primaryID {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		item, err := h.db.GetAsset(id, writeAccess)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "部分资产不存在或无权访问"})
+			return
+		}
+		if !shareAssetIdentity(primary, item) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "所选资产没有共同域名、IP 或 Host，不能判定为重复资产"})
+			return
+		}
+		others = append(others, item)
+	}
+	if len(others) == 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "至少需要两个不同资产"})
+		return
+	}
+	mergeText := func(dst *string, src string) {
+		if strings.TrimSpace(*dst) == "" && strings.TrimSpace(src) != "" {
+			*dst = src
+		}
+	}
+	tagSet := map[string]struct{}{}
+	for _, tag := range primary.Tags {
+		tagSet[tag] = struct{}{}
+	}
+	for _, item := range others {
+		mergeText(&primary.ProjectID, item.ProjectID)
+		mergeText(&primary.Host, item.Host)
+		mergeText(&primary.IP, item.IP)
+		mergeText(&primary.Domain, item.Domain)
+		mergeText(&primary.Protocol, item.Protocol)
+		mergeText(&primary.Title, item.Title)
+		mergeText(&primary.Server, item.Server)
+		mergeText(&primary.Country, item.Country)
+		mergeText(&primary.Province, item.Province)
+		mergeText(&primary.City, item.City)
+		mergeText(&primary.ResponsiblePerson, item.ResponsiblePerson)
+		mergeText(&primary.Department, item.Department)
+		mergeText(&primary.BusinessSystem, item.BusinessSystem)
+		mergeText(&primary.Environment, item.Environment)
+		mergeText(&primary.Criticality, item.Criticality)
+		for _, tag := range item.Tags {
+			tagSet[tag] = struct{}{}
+		}
+	}
+	primary.Tags = primary.Tags[:0]
+	for tag := range tagSet {
+		primary.Tags = append(primary.Tags, tag)
+	}
+	if len(primary.Tags) > 30 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "合并后标签超过 30 个"})
+		return
+	}
+	ids := make([]string, 0, len(others))
+	for _, item := range others {
+		ids = append(ids, item.ID)
+	}
+	merged, err := h.db.MergeAssets(primary, ids, writeAccess, deleteAccess)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	updated, _ := h.db.GetAsset(primary.ID, writeAccess)
+	c.JSON(http.StatusOK, gin.H{"merged": merged, "asset": updated})
+}
+
+func (h *AssetHandler) Delete(c *gin.Context) {
+	if err := h.db.DeleteAsset(c.Param("id"), assetAccess(c)); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "资产不存在或无权删除"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true})
+}

internal/handler/asset_test.go

@@ -0,0 +1,83 @@
+package handler
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"cyberstrike-ai/internal/database"
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func TestAssetListPaginatesWithinProject(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "asset-list-pagination.db"), zap.NewNop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+
+	project, err := db.CreateProject(&database.Project{Name: "Paged Project", Status: "active"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	otherProject, err := db.CreateProject(&database.Project{Name: "Other Project", Status: "active"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	assets := make([]*database.Asset, 0, 8)
+	for i := 1; i <= 7; i++ {
+		assets = append(assets, &database.Asset{
+			ProjectID: project.ID,
+			IP:        fmt.Sprintf("192.0.2.%d", i),
+			Port:      80,
+			Protocol:  "http",
+		})
+	}
+	assets = append(assets, &database.Asset{
+		ProjectID: otherProject.ID,
+		IP:        "198.51.100.1",
+		Port:      443,
+		Protocol:  "https",
+	})
+	if _, err := db.UpsertAssets(assets, "", true); err != nil {
+		t.Fatal(err)
+	}
+
+	router := gin.New()
+	router.GET("/api/assets", NewAssetHandler(db, zap.NewNop()).List)
+	request := httptest.NewRequest(http.MethodGet, "/api/assets?project_id="+project.ID+"&page=2&page_size=3", nil)
+	response := httptest.NewRecorder()
+	router.ServeHTTP(response, request)
+
+	if response.Code != http.StatusOK {
+		t.Fatalf("unexpected status %d: %s", response.Code, response.Body.String())
+	}
+	var payload struct {
+		Assets     []*database.Asset `json:"assets"`
+		Total      int               `json:"total"`
+		Page       int               `json:"page"`
+		PageSize   int               `json:"page_size"`
+		TotalPages int               `json:"total_pages"`
+	}
+	if err := json.Unmarshal(response.Body.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload.Total != 7 || payload.Page != 2 || payload.PageSize != 3 || payload.TotalPages != 3 {
+		t.Fatalf("unexpected pagination: total=%d page=%d page_size=%d total_pages=%d",
+			payload.Total, payload.Page, payload.PageSize, payload.TotalPages)
+	}
+	if len(payload.Assets) != 3 {
+		t.Fatalf("expected 3 assets on page 2, got %d", len(payload.Assets))
+	}
+	for _, asset := range payload.Assets {
+		if asset.ProjectID != project.ID {
+			t.Fatalf("asset from another project leaked into page: %#v", asset)
+		}
+	}
+}

internal/handler/attackchain.go

@@ -0,0 +1,172 @@
+package handler
+
+import (
+	"context"
+	"net/http"
+	"sync"
+	"time"
+
+	"cyberstrike-ai/internal/attackchain"
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/database"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// AttackChainHandler 攻击链处理器
+type AttackChainHandler struct {
+	db           *database.DB
+	logger       *zap.Logger
+	openAIConfig *config.OpenAIConfig
+	mu           sync.RWMutex // 保护 openAIConfig 的并发访问
+	// 用于防止同一对话的并发生成
+	generatingLocks sync.Map // map[string]*sync.Mutex
+}
+
+// NewAttackChainHandler 创建新的攻击链处理器
+func NewAttackChainHandler(db *database.DB, openAIConfig *config.OpenAIConfig, logger *zap.Logger) *AttackChainHandler {
+	return &AttackChainHandler{
+		db:           db,
+		logger:       logger,
+		openAIConfig: openAIConfig,
+	}
+}
+
+// UpdateConfig 更新OpenAI配置
+func (h *AttackChainHandler) UpdateConfig(cfg *config.OpenAIConfig) {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	h.openAIConfig = cfg
+	h.logger.Info("AttackChainHandler配置已更新",
+		zap.String("base_url", cfg.BaseURL),
+		zap.String("model", cfg.Model),
+	)
+}
+
+// getOpenAIConfig 获取OpenAI配置（线程安全）
+func (h *AttackChainHandler) getOpenAIConfig() *config.OpenAIConfig {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	return h.openAIConfig
+}
+
+// GetAttackChain 获取攻击链（按需生成）
+// GET /api/attack-chain/:conversationId
+func (h *AttackChainHandler) GetAttackChain(c *gin.Context) {
+	conversationID := c.Param("conversationId")
+	if conversationID == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "conversationId is required"})
+		return
+	}
+
+	// 检查对话是否存在
+	_, err := h.db.GetConversation(conversationID)
+	if err != nil {
+		h.logger.Warn("对话不存在", zap.String("conversationId", conversationID), zap.Error(err))
+		c.JSON(http.StatusNotFound, gin.H{"error": "对话不存在"})
+		return
+	}
+
+	// 先尝试从数据库加载（如果已生成过）
+	openAIConfig := h.getOpenAIConfig()
+	builder := attackchain.NewBuilder(h.db, openAIConfig, h.logger)
+	chain, err := builder.LoadChainFromDatabase(conversationID)
+	if err == nil && len(chain.Nodes) > 0 {
+		// 如果已存在，直接返回
+		h.logger.Info("返回已存在的攻击链", zap.String("conversationId", conversationID))
+		c.JSON(http.StatusOK, chain)
+		return
+	}
+
+	// 如果不存在，则生成新的攻击链（按需生成）
+	// 使用锁机制防止同一对话的并发生成
+	lockInterface, _ := h.generatingLocks.LoadOrStore(conversationID, &sync.Mutex{})
+	lock := lockInterface.(*sync.Mutex)
+
+	// 尝试获取锁，如果正在生成则返回错误
+	acquired := lock.TryLock()
+	if !acquired {
+		h.logger.Info("攻击链正在生成中，请稍后再试", zap.String("conversationId", conversationID))
+		c.JSON(http.StatusConflict, gin.H{"error": "攻击链正在生成中，请稍后再试"})
+		return
+	}
+	defer lock.Unlock()
+
+	// 再次检查是否已生成（可能在等待锁的过程中已经生成完成）
+	chain, err = builder.LoadChainFromDatabase(conversationID)
+	if err == nil && len(chain.Nodes) > 0 {
+		h.logger.Info("返回已存在的攻击链（在锁等待期间已生成）", zap.String("conversationId", conversationID))
+		c.JSON(http.StatusOK, chain)
+		return
+	}
+
+	h.logger.Info("开始生成攻击链", zap.String("conversationId", conversationID))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+	defer cancel()
+
+	chain, err = builder.BuildChainFromConversation(ctx, conversationID)
+	if err != nil {
+		h.logger.Error("生成攻击链失败", zap.String("conversationId", conversationID), zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "生成攻击链失败: " + err.Error()})
+		return
+	}
+
+	// 生成完成后，从锁映射中删除（可选，保留也可以用于防止短时间内重复生成）
+	// h.generatingLocks.Delete(conversationID)
+
+	c.JSON(http.StatusOK, chain)
+}
+
+// RegenerateAttackChain 重新生成攻击链
+// POST /api/attack-chain/:conversationId/regenerate
+func (h *AttackChainHandler) RegenerateAttackChain(c *gin.Context) {
+	conversationID := c.Param("conversationId")
+	if conversationID == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "conversationId is required"})
+		return
+	}
+
+	// 检查对话是否存在
+	_, err := h.db.GetConversation(conversationID)
+	if err != nil {
+		h.logger.Warn("对话不存在", zap.String("conversationId", conversationID), zap.Error(err))
+		c.JSON(http.StatusNotFound, gin.H{"error": "对话不存在"})
+		return
+	}
+
+	// 删除旧的攻击链
+	if err := h.db.DeleteAttackChain(conversationID); err != nil {
+		h.logger.Warn("删除旧攻击链失败", zap.Error(err))
+	}
+
+	// 使用锁机制防止并发生成
+	lockInterface, _ := h.generatingLocks.LoadOrStore(conversationID, &sync.Mutex{})
+	lock := lockInterface.(*sync.Mutex)
+
+	acquired := lock.TryLock()
+	if !acquired {
+		h.logger.Info("攻击链正在生成中，请稍后再试", zap.String("conversationId", conversationID))
+		c.JSON(http.StatusConflict, gin.H{"error": "攻击链正在生成中，请稍后再试"})
+		return
+	}
+	defer lock.Unlock()
+
+	// 生成新的攻击链
+	h.logger.Info("重新生成攻击链", zap.String("conversationId", conversationID))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+	defer cancel()
+
+	openAIConfig := h.getOpenAIConfig()
+	builder := attackchain.NewBuilder(h.db, openAIConfig, h.logger)
+	chain, err := builder.BuildChainFromConversation(ctx, conversationID)
+	if err != nil {
+		h.logger.Error("生成攻击链失败", zap.String("conversationId", conversationID), zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "生成攻击链失败: " + err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, chain)
+}

internal/handler/audit.go

@@ -0,0 +1,159 @@
+package handler
+
+import (
+	"net/http"
+	"time"
+
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// AuditHandler serves platform audit log APIs.
+type AuditHandler struct {
+	db     *database.DB
+	audit  *audit.Service
+	logger *zap.Logger
+}
+
+// NewAuditHandler creates an audit log handler.
+func NewAuditHandler(db *database.DB, auditSvc *audit.Service, logger *zap.Logger) *AuditHandler {
+	return &AuditHandler{db: db, audit: auditSvc, logger: logger}
+}
+
+// Meta GET /api/audit/meta
+func (h *AuditHandler) Meta(c *gin.Context) {
+	enabled := false
+	retentionDays := 0
+	if h.audit != nil {
+		enabled = h.audit.Enabled()
+		retentionDays = h.audit.RetentionDays()
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"enabled":           enabled,
+		"retention_days":    retentionDays,
+		"default_page_size": 20,
+		"max_page_size":     100,
+		"max_export":        5000,
+	})
+}
+
+// Summary GET /api/audit/summary
+func (h *AuditHandler) Summary(c *gin.Context) {
+	if h.db == nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "database unavailable"})
+		return
+	}
+	base := auditFilterForAccess(c, auditFilterFromQuery(c))
+	total, err := h.db.CountAuditLogs(base)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	failFilter := base
+	failFilter.Result = "failure"
+	failures, err := h.db.CountAuditLogs(failFilter)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	since := time.Now().AddDate(0, 0, -7)
+	recentFilter := base
+	recentFilter.Since = &since
+	recent7d, err := h.db.CountAuditLogs(recentFilter)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"total":     total,
+		"failures":  failures,
+		"recent_7d": recent7d,
+		"has_filters": c.Query("category") != "" || c.Query("action") != "" || c.Query("result") != "" ||
+			c.Query("q") != "" || c.Query("since") != "" || c.Query("until") != "",
+	})
+}
+
+// ListLogs GET /api/audit/logs
+func (h *AuditHandler) ListLogs(c *gin.Context) {
+	if h.db == nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "database unavailable"})
+		return
+	}
+	filter := auditFilterForAccess(c, auditFilterFromQuery(c))
+	page, pageSize := auditPaginationFromQuery(c)
+	filter.Limit = pageSize
+	filter.Offset = (page - 1) * pageSize
+
+	logs, err := h.db.ListAuditLogs(filter)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	total, err := h.db.CountAuditLogs(filter)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"logs":      logs,
+		"total":     total,
+		"page":      page,
+		"page_size": pageSize,
+	})
+}
+
+// GetLog GET /api/audit/logs/:id
+func (h *AuditHandler) GetLog(c *gin.Context) {
+	if h.db == nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "database unavailable"})
+		return
+	}
+	row, err := h.db.GetAuditLogByID(c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "审计记录不存在"})
+		return
+	}
+	if session, ok := security.CurrentSession(c); !ok || (session.Scope != database.RBACScopeAll && row.Actor != session.Username) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+	audit.ApplyResourceAvailability(h.db, row)
+	c.JSON(http.StatusOK, gin.H{"log": row})
+}
+
+// ExportLogs GET /api/audit/logs/export — JSON or CSV (?format=csv), max 5000 rows.
+func (h *AuditHandler) ExportLogs(c *gin.Context) {
+	if h.db == nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "database unavailable"})
+		return
+	}
+	filter := auditFilterForAccess(c, auditFilterFromQuery(c))
+	filter.Limit = 5000
+	filter.Offset = 0
+
+	logs, err := h.db.ListAuditLogs(filter)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if c.Query("format") == "csv" {
+		writeAuditLogsCSV(c, logs)
+		return
+	}
+	c.Header("Content-Disposition", `attachment; filename="audit-logs.json"`)
+	c.JSON(http.StatusOK, gin.H{
+		"exported_at": time.Now().UTC().Format(time.RFC3339),
+		"logs":        logs,
+	})
+}
+
+func auditFilterForAccess(c *gin.Context, filter database.ListAuditLogsFilter) database.ListAuditLogsFilter {
+	if session, ok := security.CurrentSession(c); ok && session.Scope != database.RBACScopeAll {
+		filter.Actor = session.Username
+	}
+	return filter
+}

internal/handler/audit_export_csv.go

@@ -0,0 +1,42 @@
+package handler
+
+import (
+	"encoding/csv"
+	"fmt"
+	"time"
+
+	"cyberstrike-ai/internal/database"
+
+	"github.com/gin-gonic/gin"
+)
+
+func writeAuditLogsCSV(c *gin.Context, logs []*database.AuditLog) {
+	c.Header("Content-Type", "text/csv; charset=utf-8")
+	c.Header("Content-Disposition", fmt.Sprintf(`attachment; filename="audit-logs-%s.csv"`, time.Now().Format("20060102")))
+
+	w := csv.NewWriter(c.Writer)
+	_ = w.Write([]string{
+		"id", "created_at", "level", "category", "action", "result", "actor",
+		"session_hint", "client_ip", "resource_type", "resource_id", "message",
+	})
+	for _, row := range logs {
+		if row == nil {
+			continue
+		}
+		_ = w.Write([]string{
+			row.ID,
+			row.CreatedAt.UTC().Format(time.RFC3339),
+			row.Level,
+			row.Category,
+			row.Action,
+			row.Result,
+			row.Actor,
+			row.SessionHint,
+			row.ClientIP,
+			row.ResourceType,
+			row.ResourceID,
+			row.Message,
+		})
+	}
+	w.Flush()
+}

internal/handler/audit_query.go

@@ -0,0 +1,49 @@
+package handler
+
+import (
+	"strconv"
+
+	"cyberstrike-ai/internal/database"
+
+	"github.com/gin-gonic/gin"
+)
+
+func auditFilterFromQuery(c *gin.Context) database.ListAuditLogsFilter {
+	filter := database.ListAuditLogsFilter{
+		Actor:         c.Query("actor"),
+		Level:         c.Query("level"),
+		Category:      c.Query("category"),
+		Action:        c.Query("action"),
+		Result:        c.Query("result"),
+		Query:         c.Query("q"),
+		ResourceType:  c.Query("resource_type"),
+		ResourceID:    c.Query("resource_id"),
+		RelatedUserID: c.Query("related_user_id"),
+	}
+	if since := c.Query("since"); since != "" {
+		if t, err := database.ParseRFC3339Time(since); err == nil {
+			filter.Since = &t
+		}
+	}
+	if until := c.Query("until"); until != "" {
+		if t, err := database.ParseRFC3339Time(until); err == nil {
+			filter.Until = &t
+		}
+	}
+	return filter
+}
+
+func auditPaginationFromQuery(c *gin.Context) (page, pageSize int) {
+	page = 1
+	pageSize = 20
+	if p, err := strconv.Atoi(c.DefaultQuery("page", "1")); err == nil && p > 0 {
+		page = p
+	}
+	if ps, err := strconv.Atoi(c.DefaultQuery("page_size", "20")); err == nil && ps > 0 {
+		pageSize = ps
+		if pageSize > 100 {
+			pageSize = 100
+		}
+	}
+	return page, pageSize
+}

internal/handler/audit_query_test.go

@@ -0,0 +1,19 @@
+package handler
+
+import (
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestAuditFilterFromQueryIncludesActorAndMemberFilters(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	context, _ := gin.CreateTestContext(httptest.NewRecorder())
+	context.Request = httptest.NewRequest("GET", "/api/audit/logs?actor=operator-user&action=assign_resource&resource_type=conversation&related_user_id=user-1", nil)
+
+	filter := auditFilterFromQuery(context)
+	if filter.Actor != "operator-user" || filter.Action != "assign_resource" || filter.ResourceType != "conversation" || filter.RelatedUserID != "user-1" {
+		t.Fatalf("filter = %#v", filter)
+	}
+}

internal/handler/auth.go

@@ -0,0 +1,237 @@
+package handler
+
+import (
+	"net/http"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// AuthHandler handles authentication-related endpoints.
+type AuthHandler struct {
+	manager    *security.AuthManager
+	config     *config.Config
+	configPath string
+	logger     *zap.Logger
+	audit      *audit.Service
+}
+
+// SetAudit wires platform audit logging.
+func (h *AuthHandler) SetAudit(s *audit.Service) {
+	h.audit = s
+}
+
+// NewAuthHandler creates a new AuthHandler.
+func NewAuthHandler(manager *security.AuthManager, cfg *config.Config, configPath string, logger *zap.Logger) *AuthHandler {
+	return &AuthHandler{
+		manager:    manager,
+		config:     cfg,
+		configPath: configPath,
+		logger:     logger,
+	}
+}
+
+type loginRequest struct {
+	Username string `json:"username"`
+	Password string `json:"password" binding:"required"`
+}
+
+type changePasswordRequest struct {
+	OldPassword string `json:"oldPassword"`
+	NewPassword string `json:"newPassword"`
+}
+
+// Login verifies password and returns a session token.
+func (h *AuthHandler) Login(c *gin.Context) {
+	var req loginRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "密码不能为空"})
+		return
+	}
+
+	token, expiresAt, err := h.manager.Authenticate(req.Username, req.Password)
+	if err != nil {
+		if h.audit != nil {
+			h.audit.Record(c, audit.Entry{
+				Level:    "warn",
+				Category: "auth",
+				Action:   "login",
+				Result:   "failure",
+				Message:  "登录失败：密码错误",
+				Actor:    strings.TrimSpace(req.Username),
+			})
+		}
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "密码错误"})
+		return
+	}
+	session, _ := h.manager.ValidateToken(token)
+
+	if h.audit != nil {
+		h.audit.Record(c, audit.Entry{
+			Category:    "auth",
+			Action:      "login",
+			Result:      "success",
+			SessionHint: audit.HintFromToken(token),
+			Message:     "登录成功",
+			Actor:       session.Username,
+			Detail: map[string]interface{}{
+				"expires_at": expiresAt.UTC().Format(time.RFC3339),
+			},
+		})
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"token":               token,
+		"expires_at":          expiresAt.UTC().Format(time.RFC3339),
+		"session_duration_hr": h.manager.SessionDurationHours(),
+		"user": gin.H{
+			"id":           session.UserID,
+			"username":     session.Username,
+			"display_name": session.DisplayName,
+		},
+		"roles":             session.Roles,
+		"permissions":       permissionKeys(session.Permissions),
+		"permission_scopes": session.PermissionScopes,
+		"scope":             session.Scope,
+	})
+}
+
+// Logout revokes the current session token.
+func (h *AuthHandler) Logout(c *gin.Context) {
+	token := c.GetString(security.ContextAuthTokenKey)
+	if token == "" {
+		authHeader := c.GetHeader("Authorization")
+		if len(authHeader) > 7 && strings.EqualFold(authHeader[:7], "Bearer ") {
+			token = strings.TrimSpace(authHeader[7:])
+		} else {
+			token = strings.TrimSpace(authHeader)
+		}
+	}
+
+	h.manager.RevokeToken(token)
+	if h.audit != nil {
+		h.audit.Record(c, audit.Entry{
+			Category: "auth",
+			Action:   "logout",
+			Result:   "success",
+			Message:  "退出登录",
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "已退出登录"})
+}
+
+// ChangePassword updates the login password.
+func (h *AuthHandler) ChangePassword(c *gin.Context) {
+	var req changePasswordRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "参数无效"})
+		return
+	}
+
+	oldPassword := strings.TrimSpace(req.OldPassword)
+	newPassword := strings.TrimSpace(req.NewPassword)
+
+	if oldPassword == "" || newPassword == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "当前密码和新密码均不能为空"})
+		return
+	}
+
+	if len(newPassword) < 8 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "新密码长度至少需要 8 位"})
+		return
+	}
+
+	if oldPassword == newPassword {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "新密码不能与旧密码相同"})
+		return
+	}
+
+	session, _ := security.CurrentSession(c)
+	if session.Username == "" {
+		session.Username = "admin"
+	}
+	if !h.manager.CheckUserPassword(session.Username, oldPassword) {
+		if h.audit != nil {
+			h.audit.Record(c, audit.Entry{
+				Level:    "warn",
+				Category: "auth",
+				Action:   "change_password",
+				Result:   "failure",
+				Message:  "修改密码失败：当前密码不正确",
+			})
+		}
+		c.JSON(http.StatusBadRequest, gin.H{"error": "当前密码不正确"})
+		return
+	}
+
+	if session.UserID == "" {
+		session.UserID = "admin"
+	}
+	if err := h.manager.UpdateUserPassword(session.UserID, newPassword); err != nil {
+		if h.logger != nil {
+			h.logger.Error("更新用户密码失败", zap.Error(err))
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "更新用户密码失败"})
+		return
+	}
+
+	if h.logger != nil {
+		h.logger.Info("登录密码已更新，所有会话已失效")
+	}
+
+	if h.audit != nil {
+		h.audit.Record(c, audit.Entry{
+			Category: "auth",
+			Action:   "change_password",
+			Result:   "success",
+			Message:  "登录密码已修改",
+		})
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "密码已更新，请使用新密码重新登录"})
+}
+
+// Validate returns the current session status.
+func (h *AuthHandler) Validate(c *gin.Context) {
+	token := c.GetString(security.ContextAuthTokenKey)
+	if token == "" {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "会话无效"})
+		return
+	}
+
+	session, ok := h.manager.ValidateToken(token)
+	if !ok {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "会话已过期"})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"token":      session.Token,
+		"expires_at": session.ExpiresAt.UTC().Format(time.RFC3339),
+		"user": gin.H{
+			"id":           session.UserID,
+			"username":     session.Username,
+			"display_name": session.DisplayName,
+		},
+		"roles":             session.Roles,
+		"permissions":       permissionKeys(session.Permissions),
+		"permission_scopes": session.PermissionScopes,
+		"scope":             session.Scope,
+	})
+}
+
+func permissionKeys(perms map[string]bool) []string {
+	keys := make([]string, 0, len(perms))
+	for key, ok := range perms {
+		if ok {
+			keys = append(keys, key)
+		}
+	}
+	return keys
+}

internal/handler/batch_queue_executor.go

@@ -0,0 +1,402 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	"cyberstrike-ai/internal/agent"
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/authctx"
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/mcp"
+	"cyberstrike-ai/internal/multiagent"
+
+	"go.uber.org/zap"
+)
+
+const batchQueueWorkerIdlePoll = 200 * time.Millisecond
+
+// executeBatchQueue 使用并发 worker 池执行批量任务队列。
+func (h *AgentHandler) executeBatchQueue(queueID string) {
+	defer h.batchTaskManager.UnmarkQueueExecutor(queueID)
+
+	queue, exists := h.batchTaskManager.GetBatchQueue(queueID)
+	if !exists {
+		return
+	}
+	concurrency := normalizeBatchQueueConcurrency(queue.Concurrency)
+	h.logger.Info("开始执行批量任务队列", zap.String("queueId", queueID), zap.Int("concurrency", concurrency))
+
+	var wg sync.WaitGroup
+	for i := 0; i < concurrency; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			h.runBatchQueueWorker(queueID)
+		}()
+	}
+	wg.Wait()
+
+	h.tryFinalizeBatchQueue(queueID)
+}
+
+func (h *AgentHandler) runBatchQueueWorker(queueID string) {
+	for {
+		queue, exists := h.batchTaskManager.GetBatchQueue(queueID)
+		if batchQueueExecutionShouldStop(queue, exists) {
+			return
+		}
+
+		task, ok := h.batchTaskManager.ClaimNextPendingTask(queueID)
+		if !ok {
+			if !h.batchTaskManager.HasRunningTasks(queueID) {
+				return
+			}
+			time.Sleep(batchQueueWorkerIdlePoll)
+			continue
+		}
+
+		queue, _ = h.batchTaskManager.GetBatchQueue(queueID)
+		if queue == nil {
+			return
+		}
+
+		h.batchTaskManager.UpdateTaskStatus(queueID, task.ID, BatchTaskStatusRunning, "", "")
+		h.executeOneBatchSubTask(queueID, queue, task)
+
+		if h.batchTaskManager.TakeSingleRunTaskIfMatch(queueID, task.ID) {
+			h.batchTaskManager.UpdateQueueStatus(queueID, BatchQueueStatusPaused)
+			h.logger.Info("单条执行完成，队列已暂停", zap.String("queueId", queueID), zap.String("taskId", task.ID))
+			return
+		}
+
+		queue, exists = h.batchTaskManager.GetBatchQueue(queueID)
+		if batchQueueExecutionShouldStop(queue, exists) {
+			if !exists {
+				h.logger.Warn("批量队列在执行收尾时已不存在，安全退出", zap.String("queueId", queueID))
+			}
+			return
+		}
+	}
+}
+
+func (h *AgentHandler) tryFinalizeBatchQueue(queueID string) {
+	queue, exists := h.batchTaskManager.GetBatchQueue(queueID)
+	if !exists || queue == nil {
+		return
+	}
+	if queue.Status != BatchQueueStatusRunning {
+		return
+	}
+	if h.batchTaskManager.HasPendingOrRunningTasks(queueID) {
+		return
+	}
+
+	lastRunErr := ""
+	for _, t := range queue.Tasks {
+		if t != nil && t.Status == BatchTaskStatusFailed && t.Error != "" {
+			lastRunErr = t.Error
+		}
+	}
+	h.batchTaskManager.SetLastRunError(queueID, lastRunErr)
+	h.batchTaskManager.UpdateQueueStatus(queueID, BatchQueueStatusCompleted)
+	h.logger.Info("批量任务队列执行完成", zap.String("queueId", queueID))
+}
+
+// executeOneBatchSubTask 执行单条批量子任务（各自独立会话）。
+func (h *AgentHandler) executeOneBatchSubTask(queueID string, queue *BatchTaskQueue, task *BatchTask) {
+	ownerUserID := h.db.GetResourceOwner("batch_task", queueID)
+	access, accessErr := h.db.ResolveRBACAccess(ownerUserID)
+	if accessErr != nil || access == nil || !access.User.Enabled {
+		h.batchTaskManager.UpdateTaskStatus(queueID, task.ID, BatchTaskStatusFailed, "", "队列所有者不存在或已禁用")
+		return
+	}
+	principal := authctx.NewPrincipalWithScopes(access.User.ID, access.User.Username, access.Scope, access.Permissions, access.PermissionScopes)
+	title := safeTruncateString(task.Message, 50)
+	batchMeta := batchSubTaskConversationMeta(h.config, queue)
+	conv, err := h.db.CreateConversation(title, batchMeta)
+	if err != nil {
+		h.logger.Error("创建对话失败", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.Error(err))
+		h.batchTaskManager.UpdateTaskStatus(queueID, task.ID, BatchTaskStatusFailed, "", "创建对话失败: "+err.Error())
+		return
+	}
+	conversationID := conv.ID
+	_ = h.db.SetResourceOwner("conversation", conversationID, access.User.ID)
+	_ = h.db.AssignResourceToUser(access.User.ID, "conversation", conversationID)
+
+	h.batchTaskManager.UpdateTaskStatusWithConversationID(queueID, task.ID, BatchTaskStatusRunning, "", "", conversationID)
+
+	finalMessage := task.Message
+	var roleTools []string
+	if queue.Role != "" && queue.Role != "默认" {
+		if h.config.Roles != nil {
+			if role, exists := h.config.Roles[queue.Role]; exists && role.Enabled {
+				if role.UserPrompt != "" {
+					finalMessage = role.UserPrompt + "\n\n" + task.Message
+					h.logger.Info("应用角色用户提示词", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.String("role", queue.Role))
+				}
+				if len(role.Tools) > 0 {
+					roleTools = role.Tools
+					h.logger.Info("使用角色配置的工具列表", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.String("role", queue.Role), zap.Int("toolCount", len(roleTools)))
+				}
+			}
+		}
+	}
+
+	if _, err = h.db.AddMessage(conversationID, "user", task.Message, nil); err != nil {
+		h.logger.Error("保存用户消息失败", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.String("conversationId", conversationID), zap.Error(err))
+	}
+
+	assistantMsg, err := h.db.AddMessage(conversationID, "assistant", "处理中...", nil)
+	if err != nil {
+		h.logger.Error("创建助手消息失败", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.String("conversationId", conversationID), zap.Error(err))
+		assistantMsg = nil
+	}
+
+	var assistantMessageID string
+	if assistantMsg != nil {
+		assistantMessageID = assistantMsg.ID
+	}
+
+	h.logger.Info("执行批量任务", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.String("message", task.Message), zap.String("role", queue.Role), zap.String("conversationId", conversationID))
+
+	principalCtx := authctx.WithPrincipal(context.Background(), principal)
+	baseCtx, cancelWithCause := context.WithCancelCause(principalCtx)
+	taskCtx, timeoutCancel := context.WithTimeout(baseCtx, 6*time.Hour)
+
+	registered := false
+	finishStatus := "completed"
+
+	defer func() {
+		h.batchTaskManager.SetTaskCancel(queueID, task.ID, nil)
+		timeoutCancel()
+		if registered {
+			if h.taskEventBus != nil {
+				ev := StreamEvent{Type: "done", Message: "", Data: map[string]interface{}{"conversationId": conversationID}}
+				if b, err := json.Marshal(ev); err == nil {
+					h.taskEventBus.Publish(conversationID, append(append([]byte("data: "), b...), '\n', '\n'))
+				}
+			}
+			h.tasks.FinishTask(conversationID, finishStatus)
+		}
+		cancelWithCause(nil)
+	}()
+
+	sendEvent := func(eventType, message string, data interface{}) {
+		if h.taskEventBus == nil {
+			return
+		}
+		ev := StreamEvent{Type: eventType, Message: message, Data: data}
+		b, err := json.Marshal(ev)
+		if err != nil {
+			b = []byte(`{"type":"error","message":"marshal failed"}`)
+		}
+		line := make([]byte, 0, len(b)+8)
+		line = append(line, []byte("data: ")...)
+		line = append(line, b...)
+		line = append(line, '\n', '\n')
+		h.taskEventBus.Publish(conversationID, line)
+	}
+
+	if _, err := h.tasks.StartTask(conversationID, task.Message, cancelWithCause); err != nil {
+		h.logger.Warn("批量队列子任务注册会话运行状态失败",
+			zap.String("queueId", queueID),
+			zap.String("taskId", task.ID),
+			zap.String("conversationId", conversationID),
+			zap.Error(err))
+		failMsg := err.Error()
+		if errors.Is(err, ErrTaskAlreadyRunning) {
+			failMsg = "会话已有任务正在执行，无法在该会话上并行启动批量子任务"
+		}
+		h.batchTaskManager.UpdateTaskStatus(queueID, task.ID, BatchTaskStatusFailed, "", failMsg)
+		return
+	}
+	registered = true
+	h.batchTaskManager.SetTaskCancel(queueID, task.ID, timeoutCancel)
+
+	progressCallback := h.createProgressCallback(taskCtx, cancelWithCause, conversationID, assistantMessageID, sendEvent)
+	taskCtx = mcp.WithMCPConversationID(taskCtx, conversationID)
+	taskCtx = mcp.WithToolRunRegistry(taskCtx, h.tasks)
+	taskCtx = mcp.WithEinoExecuteRunRegistry(taskCtx, h.tasks)
+
+	useBatchMulti := false
+	batchOrch := "deep"
+	am := strings.TrimSpace(strings.ToLower(queue.AgentMode))
+	if am == "multi" {
+		am = "deep"
+	}
+	if batchQueueWantsEino(queue.AgentMode) && h.config != nil && h.config.MultiAgent.Enabled {
+		useBatchMulti = true
+		batchOrch = config.NormalizeMultiAgentOrchestration(am)
+	} else if queue.AgentMode == "" && h.config != nil && h.config.MultiAgent.Enabled && h.config.MultiAgent.BatchUseMultiAgent {
+		useBatchMulti = true
+		batchOrch = "deep"
+	}
+	if useBatchMulti {
+		_ = h.db.SetConversationAgentMode(conversationID, batchOrch)
+	} else {
+		_ = h.db.SetConversationAgentMode(conversationID, "eino_single")
+	}
+
+	var resultMA *multiagent.RunResult
+	var runErr error
+	switch {
+	case useBatchMulti:
+		resultMA, runErr = multiagent.RunDeepAgent(taskCtx, h.config, &h.config.MultiAgent, h.agent, h.db, h.logger, conversationID, h.conversationProjectID(conversationID), finalMessage, []agent.ChatMessage{}, roleTools, progressCallback, h.agentsMarkdownDir, batchOrch, nil, h.agentSessionContextBlock(conversationID))
+	default:
+		if h.config == nil {
+			runErr = fmt.Errorf("服务器配置未加载")
+		} else {
+			resultMA, runErr = multiagent.RunEinoSingleChatModelAgent(taskCtx, h.config, &h.config.MultiAgent, h.agent, h.db, h.logger, conversationID, h.conversationProjectID(conversationID), finalMessage, []agent.ChatMessage{}, roleTools, progressCallback, nil, h.agentSessionContextBlock(conversationID))
+		}
+	}
+
+	if runErr != nil {
+		h.handleBatchSubTaskRunError(queueID, task, conversationID, assistantMessageID, baseCtx, taskCtx, resultMA, runErr, &finishStatus)
+		return
+	}
+
+	if resultMA == nil {
+		h.logger.Error("批量任务执行成功但无结果对象",
+			zap.String("queueId", queueID),
+			zap.String("taskId", task.ID),
+			zap.String("conversationId", conversationID))
+		h.batchTaskManager.UpdateTaskStatus(queueID, task.ID, BatchTaskStatusFailed, "", "内部错误：无执行结果")
+		return
+	}
+
+	h.logger.Info("批量任务执行成功", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.String("conversationId", conversationID))
+
+	mcpIDs := resultMA.MCPExecutionIDs
+	lastIn := resultMA.LastAgentTraceInput
+	lastOut := resultMA.LastAgentTraceOutput
+	reasoningContent := multiagent.AggregatedReasoningFromTraceJSON(lastIn)
+	agentMode := "batch_eino_single"
+	if useBatchMulti {
+		agentMode = "batch_eino_" + batchOrch
+	}
+	decision := h.finalizeAgentRunForDeliveryWithPolicy(conversationID, assistantMessageID, agentMode, resultMA, mcpIDs, reasoningContent, true)
+	resText := decision.FinalText
+	if !decision.Finalizable {
+		resText = finalizationBlockedMessage(decision)
+		finishStatus = decision.Status
+		sendEvent("finalization_check", resText, decision)
+	}
+	sendEvent("response", resText, finalizationResponsePayload(decision, map[string]interface{}{
+		"conversationId":   conversationID,
+		"messageId":        assistantMessageID,
+		"agentMode":        agentMode,
+		"mcpExecutionIds":  mcpIDs,
+		"batchQueueId":     queueID,
+		"batchTaskId":      task.ID,
+		"batchTaskStatus":  map[bool]string{true: string(BatchTaskStatusCompleted), false: string(BatchTaskStatusFailed)}[decision.Finalizable],
+		"candidatePreview": safeTruncateString(resultMA.Response, 500),
+	}))
+
+	if assistantMessageID == "" {
+		_, err = h.db.AddMessage(conversationID, "assistant", resText, mcpIDs)
+	} else if !decision.Finalizable {
+		err = nil
+	}
+	if err != nil {
+		h.logger.Error("保存助手消息失败", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.String("conversationId", conversationID), zap.Error(err))
+	}
+
+	if lastIn != "" || lastOut != "" {
+		if err := h.db.SaveAgentTrace(conversationID, lastIn, lastOut); err != nil {
+			h.logger.Warn("保存代理轨迹失败", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.Error(err))
+		}
+	}
+
+	if !decision.Finalizable {
+		h.batchTaskManager.UpdateTaskStatusWithConversationID(queueID, task.ID, BatchTaskStatusFailed, resText, finalizationCheckMessage(decision), conversationID)
+		return
+	}
+	h.batchTaskManager.UpdateTaskStatusWithConversationID(queueID, task.ID, BatchTaskStatusCompleted, resText, "", conversationID)
+}
+
+func batchSubTaskConversationMeta(cfg *config.Config, queue *BatchTaskQueue) database.ConversationCreateMeta {
+	meta := audit.ConversationCreateMeta("batch_task")
+	if queue == nil {
+		meta.ProjectID = effectiveProjectID(cfg, "")
+		return meta
+	}
+	meta.ProjectID = effectiveProjectID(cfg, queue.ProjectID)
+	meta.RoleName = strings.TrimSpace(queue.Role)
+	return meta
+}
+
+func (h *AgentHandler) handleBatchSubTaskRunError(
+	queueID string,
+	task *BatchTask,
+	conversationID, assistantMessageID string,
+	baseCtx, taskCtx context.Context,
+	resultMA *multiagent.RunResult,
+	runErr error,
+	finishStatus *string,
+) {
+	if shouldPersistEinoAgentTraceAfterRunError(baseCtx) {
+		h.persistEinoAgentTraceForResume(conversationID, resultMA)
+	}
+	errStr := runErr.Error()
+	partialResp := ""
+	if resultMA != nil {
+		partialResp = resultMA.Response
+	}
+	isCancelled := errors.Is(context.Cause(baseCtx), ErrTaskCancelled) ||
+		errors.Is(runErr, context.Canceled) ||
+		strings.Contains(strings.ToLower(errStr), "context canceled") ||
+		strings.Contains(strings.ToLower(errStr), "context cancelled") ||
+		(partialResp != "" && (strings.Contains(partialResp, "任务已被取消") || strings.Contains(partialResp, "任务执行中断")))
+	isTimeout := errors.Is(runErr, context.DeadlineExceeded) || errors.Is(context.Cause(taskCtx), context.DeadlineExceeded)
+
+	if isTimeout {
+		*finishStatus = "timeout"
+	} else if isCancelled {
+		*finishStatus = "cancelled"
+	} else {
+		*finishStatus = "failed"
+	}
+
+	if isCancelled {
+		h.logger.Info("批量任务被取消", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.String("conversationId", conversationID))
+		cancelMsg := "任务已被用户取消，后续操作已停止。"
+		if partialResp != "" && (strings.Contains(partialResp, "任务已被取消") || strings.Contains(partialResp, "任务执行中断")) {
+			cancelMsg = partialResp
+		}
+		if assistantMessageID != "" {
+			if updateErr := h.appendAssistantMessageNotice(assistantMessageID, cancelMsg); updateErr != nil {
+				h.logger.Warn("更新取消后的助手消息失败", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.Error(updateErr))
+			}
+			if err := h.db.AddProcessDetail(assistantMessageID, conversationID, "cancelled", cancelMsg, nil); err != nil {
+				h.logger.Warn("保存取消详情失败", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.Error(err))
+			}
+		} else if _, errMsg := h.db.AddMessage(conversationID, "assistant", cancelMsg, nil); errMsg != nil {
+			h.logger.Warn("保存取消消息失败", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.Error(errMsg))
+		}
+		h.batchTaskManager.UpdateTaskStatusWithConversationID(queueID, task.ID, BatchTaskStatusCancelled, cancelMsg, "", conversationID)
+		return
+	}
+
+	h.logger.Error("批量任务执行失败", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.String("conversationId", conversationID), zap.Error(runErr))
+	errorMsg := "执行失败: " + runErr.Error()
+	if assistantMessageID != "" {
+		if _, updateErr := h.db.Exec(
+			"UPDATE messages SET content = ?, updated_at = ? WHERE id = ?",
+			errorMsg,
+			time.Now(), assistantMessageID,
+		); updateErr != nil {
+			h.logger.Warn("更新失败后的助手消息失败", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.Error(updateErr))
+		}
+		if err := h.db.AddProcessDetail(assistantMessageID, conversationID, "error", errorMsg, nil); err != nil {
+			h.logger.Warn("保存错误详情失败", zap.String("queueId", queueID), zap.String("taskId", task.ID), zap.Error(err))
+		}
+	}
+	h.batchTaskManager.UpdateTaskStatus(queueID, task.ID, BatchTaskStatusFailed, "", runErr.Error())
+}

internal/handler/batch_task_manager_test.go

@@ -0,0 +1,133 @@
+package handler
+
+import (
+	"errors"
+	"testing"
+
+	"go.uber.org/zap"
+)
+
+func TestNormalizeBatchQueueConcurrency(t *testing.T) {
+	if got := normalizeBatchQueueConcurrency(0); got != DefaultBatchQueueConcurrency {
+		t.Fatalf("expected default %d, got %d", DefaultBatchQueueConcurrency, got)
+	}
+	if got := normalizeBatchQueueConcurrency(99); got != MaxBatchQueueConcurrency {
+		t.Fatalf("expected max %d, got %d", MaxBatchQueueConcurrency, got)
+	}
+}
+
+func TestClaimNextPendingTaskParallel(t *testing.T) {
+	m := NewBatchTaskManager(zap.NewNop())
+	queue, err := m.CreateBatchQueue("test", "", "eino_single", "manual", "", "", nil, 3, []string{"a", "b", "c"})
+	if err != nil {
+		t.Fatalf("CreateBatchQueue: %v", err)
+	}
+	m.UpdateQueueStatus(queue.ID, BatchQueueStatusRunning)
+
+	t1, ok1 := m.ClaimNextPendingTask(queue.ID)
+	t2, ok2 := m.ClaimNextPendingTask(queue.ID)
+	if !ok1 || !ok2 || t1.ID == t2.ID {
+		t.Fatalf("expected two distinct claims, got ok1=%v ok2=%v t1=%v t2=%v", ok1, ok2, t1, t2)
+	}
+	if t1.Status != BatchTaskStatusRunning || t2.Status != BatchTaskStatusRunning {
+		t.Fatalf("claimed tasks should be running")
+	}
+	t3, ok3 := m.ClaimNextPendingTask(queue.ID)
+	if !ok3 {
+		t.Fatal("expected third claim")
+	}
+	_, ok4 := m.ClaimNextPendingTask(queue.ID)
+	if ok4 {
+		t.Fatal("expected no fourth pending task")
+	}
+	_ = t3
+}
+
+func TestBatchQueueExecutionShouldStop(t *testing.T) {
+	t.Parallel()
+	if !batchQueueExecutionShouldStop(nil, false) {
+		t.Fatal("expected stop when queue missing")
+	}
+	if !batchQueueExecutionShouldStop(nil, true) {
+		t.Fatal("expected stop when queue is nil but exists=true")
+	}
+	q := &BatchTaskQueue{Status: BatchQueueStatusRunning}
+	if batchQueueExecutionShouldStop(q, true) {
+		t.Fatal("expected continue when running")
+	}
+	q.Status = BatchQueueStatusCancelled
+	if !batchQueueExecutionShouldStop(q, true) {
+		t.Fatal("expected stop when cancelled")
+	}
+}
+
+func TestBatchSubTaskConversationMetaKeepsQueueRole(t *testing.T) {
+	t.Parallel()
+
+	meta := batchSubTaskConversationMeta(nil, &BatchTaskQueue{Role: " 渗透测试 "})
+	if meta.Source != "batch_task" {
+		t.Fatalf("expected batch_task source, got %q", meta.Source)
+	}
+	if meta.RoleName != "渗透测试" {
+		t.Fatalf("expected queue role to be stored on child conversation, got %q", meta.RoleName)
+	}
+}
+
+func TestDeleteQueueBlockedWhileExecutorActive(t *testing.T) {
+	t.Parallel()
+	m := NewBatchTaskManager(zap.NewNop())
+	queue, err := m.CreateBatchQueue("test", "", "eino_single", "manual", "", "", nil, 1, []string{"hello"})
+	if err != nil {
+		t.Fatalf("CreateBatchQueue: %v", err)
+	}
+	if !m.TryMarkQueueExecutor(queue.ID) {
+		t.Fatal("expected to mark executor")
+	}
+	m.UpdateQueueStatus(queue.ID, BatchQueueStatusCancelled)
+
+	err = m.DeleteQueue(queue.ID)
+	if !errors.Is(err, ErrBatchQueueExecutorActive) {
+		t.Fatalf("expected ErrBatchQueueExecutorActive, got %v", err)
+	}
+	if _, ok := m.GetBatchQueue(queue.ID); !ok {
+		t.Fatal("queue should still exist while executor active")
+	}
+
+	m.UnmarkQueueExecutor(queue.ID)
+	if err := m.DeleteQueue(queue.ID); err != nil {
+		t.Fatalf("expected delete after executor unmarked, got %v", err)
+	}
+	if _, ok := m.GetBatchQueue(queue.ID); ok {
+		t.Fatal("queue should be deleted")
+	}
+}
+
+func TestDeleteQueueBlockedWhileRunning(t *testing.T) {
+	t.Parallel()
+	m := NewBatchTaskManager(zap.NewNop())
+	queue, err := m.CreateBatchQueue("test", "", "eino_single", "manual", "", "", nil, 1, []string{"hello"})
+	if err != nil {
+		t.Fatalf("CreateBatchQueue: %v", err)
+	}
+	m.UpdateQueueStatus(queue.ID, BatchQueueStatusRunning)
+
+	err = m.DeleteQueue(queue.ID)
+	if !errors.Is(err, ErrBatchQueueStillRunning) {
+		t.Fatalf("expected ErrBatchQueueStillRunning, got %v", err)
+	}
+}
+
+func TestTryMarkQueueExecutorDedupes(t *testing.T) {
+	t.Parallel()
+	m := NewBatchTaskManager(zap.NewNop())
+	if !m.TryMarkQueueExecutor("q-1") {
+		t.Fatal("first mark should succeed")
+	}
+	if m.TryMarkQueueExecutor("q-1") {
+		t.Fatal("second mark should fail")
+	}
+	m.UnmarkQueueExecutor("q-1")
+	if !m.TryMarkQueueExecutor("q-1") {
+		t.Fatal("mark after unmark should succeed")
+	}
+}

internal/handler/batch_task_mcp.go

@@ -0,0 +1,875 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/authctx"
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/mcp"
+	"cyberstrike-ai/internal/mcp/builtin"
+
+	"go.uber.org/zap"
+)
+
+// RegisterBatchTaskMCPTools 注册批量任务队列相关 MCP 工具（需传入已初始化 DB 的 AgentHandler）
+func RegisterBatchTaskMCPTools(mcpServer *mcp.Server, h *AgentHandler, logger *zap.Logger) {
+	if mcpServer == nil || h == nil || logger == nil {
+		return
+	}
+
+	reg := func(tool mcp.Tool, fn func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error)) {
+		mcpServer.RegisterTool(tool, fn)
+	}
+
+	// --- list ---
+	reg(mcp.Tool{
+		Name:             builtin.ToolBatchTaskList,
+		Description:      "列出批量任务队列（精简摘要，省上下文）。含队列元数据、子任务 id/status/截断后的 message、各状态计数。完整子任务（含 result/error/conversationId/时间等）请用 batch_task_get(queue_id)。\n\n⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确提及查看/管理批量任务、任务队列时才可调用。不要在用户未要求时自行调用。",
+		ShortDescription: "列出批量任务队列",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"status": map[string]interface{}{
+					"type":        "string",
+					"description": "筛选状态：all（默认）、pending、running、paused、completed、cancelled",
+					"enum":        []string{"all", "pending", "running", "paused", "completed", "cancelled"},
+				},
+				"keyword": map[string]interface{}{
+					"type":        "string",
+					"description": "按队列 ID 或标题模糊搜索",
+				},
+				"page": map[string]interface{}{
+					"type":        "integer",
+					"description": "页码，从 1 开始，默认 1",
+				},
+				"page_size": map[string]interface{}{
+					"type":        "integer",
+					"description": "每页条数，默认 20，最大 100",
+				},
+			},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		status := mcpArgString(args, "status")
+		if status == "" {
+			status = "all"
+		}
+		keyword := mcpArgString(args, "keyword")
+		page := int(mcpArgFloat(args, "page"))
+		if page <= 0 {
+			page = 1
+		}
+		pageSize := int(mcpArgFloat(args, "page_size"))
+		if pageSize <= 0 {
+			pageSize = 20
+		}
+		if pageSize > 100 {
+			pageSize = 100
+		}
+		offset := (page - 1) * pageSize
+		if offset > 100000 {
+			offset = 100000
+		}
+		queues := []*BatchTaskQueue{}
+		total := 0
+		var err error
+		if principal, ok := authctx.PrincipalFromContext(ctx); ok {
+			queues, total, err = h.batchTaskManager.ListQueuesForAccess(pageSize, offset, status, keyword, principal.UserID, principal.ScopeFor("tasks:read"))
+		} else {
+			return batchMCPTextResult("缺少认证身份", true), nil
+		}
+		if err != nil {
+			return batchMCPTextResult(fmt.Sprintf("列出队列失败: %v", err), true), nil
+		}
+		totalPages := (total + pageSize - 1) / pageSize
+		if totalPages == 0 {
+			totalPages = 1
+		}
+		slim := make([]batchTaskQueueMCPListItem, 0, len(queues))
+		for _, q := range queues {
+			if q == nil {
+				continue
+			}
+			slim = append(slim, toBatchTaskQueueMCPListItem(q))
+		}
+		payload := map[string]interface{}{
+			"queues":      slim,
+			"total":       total,
+			"page":        page,
+			"page_size":   pageSize,
+			"total_pages": totalPages,
+		}
+		logger.Info("MCP batch_task_list", zap.String("status", status), zap.Int("total", total))
+		return batchMCPJSONResult(payload)
+	})
+
+	// --- get ---
+	reg(mcp.Tool{
+		Name:             builtin.ToolBatchTaskGet,
+		Description:      "根据 queue_id 获取单个批量任务队列详情（含子任务列表、Cron、调度开关与最近错误信息）。\n\n⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确提及查看/管理批量任务、任务队列时才可调用。不要在用户未要求时自行调用。",
+		ShortDescription: "获取批量任务队列详情",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"queue_id": map[string]interface{}{
+					"type":        "string",
+					"description": "队列 ID",
+				},
+			},
+			"required": []string{"queue_id"},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		qid := mcpArgString(args, "queue_id")
+		if qid == "" {
+			return batchMCPTextResult("queue_id 不能为空", true), nil
+		}
+		queue, ok := h.batchTaskManager.GetBatchQueue(qid)
+		if !ok {
+			return batchMCPTextResult("队列不存在: "+qid, true), nil
+		}
+		return batchMCPJSONResult(queue)
+	})
+
+	// --- create ---
+	reg(mcp.Tool{
+		Name: builtin.ToolBatchTaskCreate,
+		Description: `⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确要求创建批量任务、任务队列时才可调用。禁止在用户未提及”批量任务””任务队列””定时任务”等关键词时自行调用。如果用户只是让你做某件事，请在当前对话中直接完成，不要自作主张创建任务队列。
+
+【用途】应用内「任务管理 / 批量任务队列」：把多条彼此独立的用户指令登记成一条队列，便于在界面里查看进度、暂停/继续、定时重跑等。这是队列数据与调度入口，不是再开一个”子代理会话”替你探索当前问题。
+
+【何时用】用户明确要批量排队执行、Cron 周期跑同一批指令、或需要与任务管理页面对齐时调用。需要即时追问、强依赖当前对话上下文的分析/编码，应在本对话内直接完成，不要为了”委派”而创建队列。
+
+【参数】tasks（字符串数组）或 tasks_text（多行，每行一条）二选一；每项是一条将来由系统按队列顺序执行的指令文案。agent_mode：eino_single（Eino ADK 单代理，默认）、deep / plan_execute / supervisor（需系统启用多代理）。非”把主对话拆给子代理”。schedule_mode：manual（默认）或 cron；cron 须填 cron_expr（5 段，如 “0 */6 * * *”）。
+
+【执行】默认创建后为 pending，不自动跑。execute_now=true 可创建后立即跑；否则之后调用 batch_task_start。Cron 自动下一轮需 schedule_enabled 为 true（可用 batch_task_schedule_enabled）。`,
+		ShortDescription: "任务管理：创建批量任务队列（登记多条指令，可选立即或 Cron）",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"title": map[string]interface{}{
+					"type":        "string",
+					"description": "可选队列标题，便于在任务管理中识别",
+				},
+				"role": map[string]interface{}{
+					"type":        "string",
+					"description": "队列使用的角色名，空表示默认",
+				},
+				"tasks": map[string]interface{}{
+					"type":        "array",
+					"description": "队列中的子任务指令，每项一条独立待执行文案（与 tasks_text 二选一）",
+					"items":       map[string]interface{}{"type": "string"},
+				},
+				"tasks_text": map[string]interface{}{
+					"type":        "string",
+					"description": "多行文本，每行一条子任务指令（与 tasks 二选一）",
+				},
+				"agent_mode": map[string]interface{}{
+					"type":        "string",
+					"description": "执行模式：eino_single（Eino ADK，默认）、deep/plan_execute/supervisor（Eino 编排，需启用多代理）",
+					"enum":        []string{"eino_single", "deep", "plan_execute", "supervisor"},
+				},
+				"schedule_mode": map[string]interface{}{
+					"type":        "string",
+					"description": "manual（仅手工/启动后跑）或 cron（按表达式触发）",
+					"enum":        []string{"manual", "cron"},
+				},
+				"cron_expr": map[string]interface{}{
+					"type":        "string",
+					"description": "schedule_mode 为 cron 时必填。标准 5 段：分钟 小时 日 月 星期，例如 \"0 */6 * * *\"、\"30 2 * * 1-5\"",
+				},
+				"execute_now": map[string]interface{}{
+					"type":        "boolean",
+					"description": "创建后是否立即开始执行队列，默认 false（pending，需 batch_task_start）",
+				},
+				"project_id": map[string]interface{}{
+					"type":        "string",
+					"description": "队列内子对话绑定的项目 ID（可选，未指定时使用 config.project.default_project_id）",
+				},
+				"concurrency": map[string]interface{}{
+					"type":        "integer",
+					"description": "同时执行的子任务数，默认 1（串行），最大 8。含扫描类工具时建议 1-2。",
+				},
+			},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		tasks, errMsg := batchMCPTasksFromArgs(args)
+		if errMsg != "" {
+			return batchMCPTextResult(errMsg, true), nil
+		}
+		title := mcpArgString(args, "title")
+		role := mcpArgString(args, "role")
+		agentMode := config.NormalizeAgentMode(mcpArgString(args, "agent_mode"))
+		scheduleMode := normalizeBatchQueueScheduleMode(mcpArgString(args, "schedule_mode"))
+		cronExpr := strings.TrimSpace(mcpArgString(args, "cron_expr"))
+		var nextRunAt *time.Time
+		if scheduleMode == "cron" {
+			if cronExpr == "" {
+				return batchMCPTextResult("Cron 调度模式下 cron_expr 不能为空", true), nil
+			}
+			sch, err := h.batchCronParser.Parse(cronExpr)
+			if err != nil {
+				return batchMCPTextResult("无效的 Cron 表达式: "+err.Error(), true), nil
+			}
+			n := sch.Next(time.Now())
+			nextRunAt = &n
+		}
+		executeNow, ok := mcpArgBool(args, "execute_now")
+		if !ok {
+			executeNow = false
+		}
+		projectID := strings.TrimSpace(mcpArgString(args, "project_id"))
+		if principal, ok := authctx.PrincipalFromContext(ctx); ok && projectID != "" && principal.ScopeFor("tasks:write") != database.RBACScopeAll {
+			if h.db == nil || !h.db.UserCanAccessResource(principal.UserID, principal.ScopeFor("tasks:write"), "project", projectID) {
+				return batchMCPTextResult("无权访问目标项目", true), nil
+			}
+		}
+		concurrency := int(mcpArgFloat(args, "concurrency"))
+		queue, createErr := h.batchTaskManager.CreateBatchQueue(title, role, agentMode, scheduleMode, cronExpr, projectID, nextRunAt, concurrency, tasks)
+		if createErr != nil {
+			return batchMCPTextResult("创建队列失败: "+createErr.Error(), true), nil
+		}
+		if principal, ok := authctx.PrincipalFromContext(ctx); ok && h.db != nil {
+			_ = h.db.SetResourceOwner("batch_task", queue.ID, principal.UserID)
+			_ = h.db.AssignResourceToUser(principal.UserID, "batch_task", queue.ID)
+		}
+		started := false
+		if executeNow {
+			ok, err := h.startBatchQueueExecution(queue.ID, false)
+			if !ok {
+				return batchMCPTextResult("队列不存在: "+queue.ID, true), nil
+			}
+			if err != nil {
+				return batchMCPTextResult("创建成功但启动失败: "+err.Error(), true), nil
+			}
+			started = true
+			if refreshed, exists := h.batchTaskManager.GetBatchQueue(queue.ID); exists {
+				queue = refreshed
+			}
+		}
+		logger.Info("MCP batch_task_create", zap.String("queueId", queue.ID), zap.Int("taskCount", len(tasks)))
+		return batchMCPJSONResult(map[string]interface{}{
+			"queue_id":    queue.ID,
+			"queue":       queue,
+			"started":     started,
+			"execute_now": executeNow,
+			"reminder": func() string {
+				if started {
+					return "队列已创建并立即启动。"
+				}
+				return "队列已创建，当前为 pending。需要开始执行时请调用 MCP 工具 batch_task_start（queue_id 同上）。Cron 自动调度需 schedule_enabled 为 true，可用 batch_task_schedule_enabled。"
+			}(),
+		})
+	})
+
+	// --- start ---
+	reg(mcp.Tool{
+		Name: builtin.ToolBatchTaskStart,
+		Description: `启动或继续执行批量任务队列（pending / paused）。
+与 batch_task_create 配合使用：仅创建队列不会自动执行，需调用本工具才会开始跑子任务。
+
+⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确要求启动/继续批量任务时才可调用。不要在用户未要求时自行调用。`,
+		ShortDescription: "启动/继续批量任务队列（创建后需调用才会执行）",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"queue_id": map[string]interface{}{
+					"type":        "string",
+					"description": "队列 ID",
+				},
+			},
+			"required": []string{"queue_id"},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		qid := mcpArgString(args, "queue_id")
+		if qid == "" {
+			return batchMCPTextResult("queue_id 不能为空", true), nil
+		}
+		ok, err := h.startBatchQueueExecution(qid, false)
+		if !ok {
+			return batchMCPTextResult("队列不存在: "+qid, true), nil
+		}
+		if err != nil {
+			return batchMCPTextResult("启动失败: "+err.Error(), true), nil
+		}
+		logger.Info("MCP batch_task_start", zap.String("queueId", qid))
+		return batchMCPTextResult("已提交启动，队列将开始执行。", false), nil
+	})
+
+	// --- rerun (reset + start for completed/cancelled queues) ---
+	reg(mcp.Tool{
+		Name:             builtin.ToolBatchTaskRerun,
+		Description:      "重跑已完成或已取消的批量任务队列。会重置所有子任务状态后重新执行一轮。\n\n⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确要求重跑批量任务时才可调用。不要在用户未要求时自行调用。",
+		ShortDescription: "重跑批量任务队列",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"queue_id": map[string]interface{}{
+					"type":        "string",
+					"description": "队列 ID",
+				},
+			},
+			"required": []string{"queue_id"},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		qid := mcpArgString(args, "queue_id")
+		if qid == "" {
+			return batchMCPTextResult("queue_id 不能为空", true), nil
+		}
+		queue, exists := h.batchTaskManager.GetBatchQueue(qid)
+		if !exists {
+			return batchMCPTextResult("队列不存在: "+qid, true), nil
+		}
+		if queue.Status != "completed" && queue.Status != "cancelled" {
+			return batchMCPTextResult("仅已完成或已取消的队列可以重跑，当前状态: "+queue.Status, true), nil
+		}
+		if !h.batchTaskManager.ResetQueueForRerun(qid) {
+			return batchMCPTextResult("重置队列失败", true), nil
+		}
+		ok, err := h.startBatchQueueExecution(qid, false)
+		if !ok {
+			return batchMCPTextResult("启动失败", true), nil
+		}
+		if err != nil {
+			return batchMCPTextResult("启动失败: "+err.Error(), true), nil
+		}
+		logger.Info("MCP batch_task_rerun", zap.String("queueId", qid))
+		return batchMCPTextResult("已重置并重新启动队列。", false), nil
+	})
+
+	// --- pause ---
+	reg(mcp.Tool{
+		Name:             builtin.ToolBatchTaskPause,
+		Description:      "暂停正在运行的批量任务队列（当前子任务会被取消）。\n\n⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确要求暂停批量任务时才可调用。不要在用户未要求时自行调用。",
+		ShortDescription: "暂停批量任务队列",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"queue_id": map[string]interface{}{
+					"type":        "string",
+					"description": "队列 ID",
+				},
+			},
+			"required": []string{"queue_id"},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		qid := mcpArgString(args, "queue_id")
+		if qid == "" {
+			return batchMCPTextResult("queue_id 不能为空", true), nil
+		}
+		if !h.batchTaskManager.PauseQueue(qid) {
+			return batchMCPTextResult("无法暂停：队列不存在或当前非 running 状态", true), nil
+		}
+		logger.Info("MCP batch_task_pause", zap.String("queueId", qid))
+		return batchMCPTextResult("队列已暂停。", false), nil
+	})
+
+	// --- delete queue ---
+	reg(mcp.Tool{
+		Name:             builtin.ToolBatchTaskDelete,
+		Description:      "删除批量任务队列及其子任务记录。\n\n⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确要求删除批量任务队列时才可调用。不要在用户未要求时自行调用。",
+		ShortDescription: "删除批量任务队列",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"queue_id": map[string]interface{}{
+					"type":        "string",
+					"description": "队列 ID",
+				},
+			},
+			"required": []string{"queue_id"},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		qid := mcpArgString(args, "queue_id")
+		if qid == "" {
+			return batchMCPTextResult("queue_id 不能为空", true), nil
+		}
+		if err := h.batchTaskManager.DeleteQueue(qid); err != nil {
+			switch {
+			case errors.Is(err, ErrBatchQueueNotFound):
+				return batchMCPTextResult("删除失败：队列不存在", true), nil
+			case errors.Is(err, ErrBatchQueueExecutorActive):
+				return batchMCPTextResult("删除失败：队列执行器仍在运行，请稍后再试", true), nil
+			case errors.Is(err, ErrBatchQueueStillRunning):
+				return batchMCPTextResult("删除失败：队列正在运行中", true), nil
+			default:
+				return batchMCPTextResult("删除失败："+err.Error(), true), nil
+			}
+		}
+		logger.Info("MCP batch_task_delete", zap.String("queueId", qid))
+		return batchMCPTextResult("队列已删除。", false), nil
+	})
+
+	// --- update metadata (title/role/agentMode) ---
+	reg(mcp.Tool{
+		Name:             builtin.ToolBatchTaskUpdateMetadata,
+		Description:      "修改批量任务队列的标题、角色和代理模式。仅在队列非 running 状态下可修改。\n\n⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确要求修改批量任务队列属性时才可调用。不要在用户未要求时自行调用。",
+		ShortDescription: "修改批量任务队列标题/角色/代理模式",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"queue_id": map[string]interface{}{
+					"type":        "string",
+					"description": "队列 ID",
+				},
+				"title": map[string]interface{}{
+					"type":        "string",
+					"description": "新标题（空字符串清除标题）",
+				},
+				"role": map[string]interface{}{
+					"type":        "string",
+					"description": "新角色名（空字符串使用默认角色）",
+				},
+				"agent_mode": map[string]interface{}{
+					"type":        "string",
+					"description": "代理模式：eino_single、deep、plan_execute、supervisor",
+					"enum":        []string{"eino_single", "deep", "plan_execute", "supervisor"},
+				},
+				"concurrency": map[string]interface{}{
+					"type":        "integer",
+					"description": "同时执行的子任务数，默认 1，最大 8",
+				},
+			},
+			"required": []string{"queue_id"},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		qid := mcpArgString(args, "queue_id")
+		if qid == "" {
+			return batchMCPTextResult("queue_id 不能为空", true), nil
+		}
+		title := mcpArgString(args, "title")
+		role := mcpArgString(args, "role")
+		agentMode := mcpArgString(args, "agent_mode")
+		var concurrency *int
+		if raw, ok := args["concurrency"]; ok && raw != nil {
+			v := int(mcpArgFloat(args, "concurrency"))
+			concurrency = &v
+		}
+		if err := h.batchTaskManager.UpdateQueueMetadata(qid, title, role, agentMode, concurrency); err != nil {
+			return batchMCPTextResult(err.Error(), true), nil
+		}
+		updated, _ := h.batchTaskManager.GetBatchQueue(qid)
+		logger.Info("MCP batch_task_update_metadata", zap.String("queueId", qid))
+		return batchMCPJSONResult(updated)
+	})
+
+	// --- update schedule ---
+	reg(mcp.Tool{
+		Name: builtin.ToolBatchTaskUpdateSchedule,
+		Description: `修改批量任务队列的调度方式和 Cron 表达式。仅在队列非 running 状态下可修改。
+schedule_mode 为 cron 时必须提供有效 cron_expr；为 manual 时会清除 Cron 配置。
+
+⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确要求修改批量任务调度配置时才可调用。不要在用户未要求时自行调用。`,
+		ShortDescription: "修改批量任务调度配置（Cron 表达式）",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"queue_id": map[string]interface{}{
+					"type":        "string",
+					"description": "队列 ID",
+				},
+				"schedule_mode": map[string]interface{}{
+					"type":        "string",
+					"description": "manual 或 cron",
+					"enum":        []string{"manual", "cron"},
+				},
+				"cron_expr": map[string]interface{}{
+					"type":        "string",
+					"description": "Cron 表达式（schedule_mode 为 cron 时必填）。标准 5 段格式：分钟 小时 日 月 星期，如 \"0 */6 * * *\"（每6小时）、\"30 2 * * 1-5\"（工作日凌晨2:30）",
+				},
+			},
+			"required": []string{"queue_id", "schedule_mode"},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		qid := mcpArgString(args, "queue_id")
+		if qid == "" {
+			return batchMCPTextResult("queue_id 不能为空", true), nil
+		}
+		queue, exists := h.batchTaskManager.GetBatchQueue(qid)
+		if !exists {
+			return batchMCPTextResult("队列不存在: "+qid, true), nil
+		}
+		if queue.Status == "running" {
+			return batchMCPTextResult("队列正在运行中，无法修改调度配置", true), nil
+		}
+		scheduleMode := normalizeBatchQueueScheduleMode(mcpArgString(args, "schedule_mode"))
+		cronExpr := strings.TrimSpace(mcpArgString(args, "cron_expr"))
+		var nextRunAt *time.Time
+		if scheduleMode == "cron" {
+			if cronExpr == "" {
+				return batchMCPTextResult("Cron 调度模式下 cron_expr 不能为空", true), nil
+			}
+			sch, err := h.batchCronParser.Parse(cronExpr)
+			if err != nil {
+				return batchMCPTextResult("无效的 Cron 表达式: "+err.Error(), true), nil
+			}
+			n := sch.Next(time.Now())
+			nextRunAt = &n
+		}
+		h.batchTaskManager.UpdateQueueSchedule(qid, scheduleMode, cronExpr, nextRunAt)
+		updated, _ := h.batchTaskManager.GetBatchQueue(qid)
+		logger.Info("MCP batch_task_update_schedule", zap.String("queueId", qid), zap.String("scheduleMode", scheduleMode), zap.String("cronExpr", cronExpr))
+		return batchMCPJSONResult(updated)
+	})
+
+	// --- schedule enabled ---
+	reg(mcp.Tool{
+		Name: builtin.ToolBatchTaskScheduleEnabled,
+		Description: `设置是否允许 Cron 自动触发该队列。关闭后仍保留 Cron 表达式，仅停止定时自动跑；可用手工「启动」执行。
+仅对 schedule_mode 为 cron 的队列有意义。
+
+⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确要求开关批量任务自动调度时才可调用。不要在用户未要求时自行调用。`,
+		ShortDescription: "开关批量任务 Cron 自动调度",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"queue_id": map[string]interface{}{
+					"type":        "string",
+					"description": "队列 ID",
+				},
+				"schedule_enabled": map[string]interface{}{
+					"type":        "boolean",
+					"description": "true 允许定时触发，false 仅手工执行",
+				},
+			},
+			"required": []string{"queue_id", "schedule_enabled"},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		qid := mcpArgString(args, "queue_id")
+		if qid == "" {
+			return batchMCPTextResult("queue_id 不能为空", true), nil
+		}
+		en, ok := mcpArgBool(args, "schedule_enabled")
+		if !ok {
+			return batchMCPTextResult("schedule_enabled 必须为布尔值", true), nil
+		}
+		if _, exists := h.batchTaskManager.GetBatchQueue(qid); !exists {
+			return batchMCPTextResult("队列不存在", true), nil
+		}
+		if !h.batchTaskManager.SetScheduleEnabled(qid, en) {
+			return batchMCPTextResult("更新失败", true), nil
+		}
+		queue, _ := h.batchTaskManager.GetBatchQueue(qid)
+		logger.Info("MCP batch_task_schedule_enabled", zap.String("queueId", qid), zap.Bool("enabled", en))
+		return batchMCPJSONResult(queue)
+	})
+
+	// --- add task ---
+	reg(mcp.Tool{
+		Name:             builtin.ToolBatchTaskAdd,
+		Description:      "向处于 pending 状态的队列追加一条子任务。\n\n⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确要求向批量任务队列添加子任务时才可调用。不要在用户未要求时自行调用。",
+		ShortDescription: "批量队列添加子任务",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"queue_id": map[string]interface{}{
+					"type":        "string",
+					"description": "队列 ID",
+				},
+				"message": map[string]interface{}{
+					"type":        "string",
+					"description": "任务指令内容",
+				},
+			},
+			"required": []string{"queue_id", "message"},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		qid := mcpArgString(args, "queue_id")
+		msg := strings.TrimSpace(mcpArgString(args, "message"))
+		if qid == "" || msg == "" {
+			return batchMCPTextResult("queue_id 与 message 均不能为空", true), nil
+		}
+		task, err := h.batchTaskManager.AddTaskToQueue(qid, msg)
+		if err != nil {
+			return batchMCPTextResult(err.Error(), true), nil
+		}
+		queue, _ := h.batchTaskManager.GetBatchQueue(qid)
+		logger.Info("MCP batch_task_add_task", zap.String("queueId", qid), zap.String("taskId", task.ID))
+		return batchMCPJSONResult(map[string]interface{}{"task": task, "queue": queue})
+	})
+
+	// --- update task ---
+	reg(mcp.Tool{
+		Name:             builtin.ToolBatchTaskUpdate,
+		Description:      "修改 pending 队列中仍为 pending 的子任务文案。\n\n⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确要求修改批量子任务内容时才可调用。不要在用户未要求时自行调用。",
+		ShortDescription: "更新批量子任务内容",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"queue_id": map[string]interface{}{
+					"type":        "string",
+					"description": "队列 ID",
+				},
+				"task_id": map[string]interface{}{
+					"type":        "string",
+					"description": "子任务 ID",
+				},
+				"message": map[string]interface{}{
+					"type":        "string",
+					"description": "新的任务指令",
+				},
+			},
+			"required": []string{"queue_id", "task_id", "message"},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		qid := mcpArgString(args, "queue_id")
+		tid := mcpArgString(args, "task_id")
+		msg := strings.TrimSpace(mcpArgString(args, "message"))
+		if qid == "" || tid == "" || msg == "" {
+			return batchMCPTextResult("queue_id、task_id、message 均不能为空", true), nil
+		}
+		if err := h.batchTaskManager.UpdateTaskMessage(qid, tid, msg); err != nil {
+			return batchMCPTextResult(err.Error(), true), nil
+		}
+		queue, _ := h.batchTaskManager.GetBatchQueue(qid)
+		logger.Info("MCP batch_task_update_task", zap.String("queueId", qid), zap.String("taskId", tid))
+		return batchMCPJSONResult(queue)
+	})
+
+	// --- remove task ---
+	reg(mcp.Tool{
+		Name:             builtin.ToolBatchTaskRemove,
+		Description:      "从 pending 队列中删除仍为 pending 的子任务。\n\n⚠️ 调用约束：本工具属于「任务管理」模块，仅当用户明确要求删除批量子任务时才可调用。不要在用户未要求时自行调用。",
+		ShortDescription: "删除批量子任务",
+		InputSchema: map[string]interface{}{
+			"type": "object",
+			"properties": map[string]interface{}{
+				"queue_id": map[string]interface{}{
+					"type":        "string",
+					"description": "队列 ID",
+				},
+				"task_id": map[string]interface{}{
+					"type":        "string",
+					"description": "子任务 ID",
+				},
+			},
+			"required": []string{"queue_id", "task_id"},
+		},
+	}, func(ctx context.Context, args map[string]interface{}) (*mcp.ToolResult, error) {
+		qid := mcpArgString(args, "queue_id")
+		tid := mcpArgString(args, "task_id")
+		if qid == "" || tid == "" {
+			return batchMCPTextResult("queue_id 与 task_id 均不能为空", true), nil
+		}
+		if err := h.batchTaskManager.DeleteTask(qid, tid); err != nil {
+			return batchMCPTextResult(err.Error(), true), nil
+		}
+		queue, _ := h.batchTaskManager.GetBatchQueue(qid)
+		logger.Info("MCP batch_task_remove_task", zap.String("queueId", qid), zap.String("taskId", tid))
+		return batchMCPJSONResult(queue)
+	})
+
+	logger.Debug("批量任务 MCP 工具已注册", zap.Int("count", 12))
+}
+
+// --- batch_task_list 精简结构（避免把每条子任务的 result 等大段文本塞进列表上下文） ---
+
+const mcpBatchListTaskMessageMaxRunes = 160
+
+// batchTaskMCPListSummary 列表中的子任务摘要（完整字段用 batch_task_get）
+type batchTaskMCPListSummary struct {
+	ID      string `json:"id"`
+	Status  string `json:"status"`
+	Message string `json:"message,omitempty"`
+}
+
+// batchTaskQueueMCPListItem 列表中的队列摘要
+type batchTaskQueueMCPListItem struct {
+	ID                    string                    `json:"id"`
+	Title                 string                    `json:"title,omitempty"`
+	Role                  string                    `json:"role,omitempty"`
+	AgentMode             string                    `json:"agentMode"`
+	ScheduleMode          string                    `json:"scheduleMode"`
+	CronExpr              string                    `json:"cronExpr,omitempty"`
+	NextRunAt             *time.Time                `json:"nextRunAt,omitempty"`
+	ScheduleEnabled       bool                      `json:"scheduleEnabled"`
+	LastScheduleTriggerAt *time.Time                `json:"lastScheduleTriggerAt,omitempty"`
+	Status                string                    `json:"status"`
+	CreatedAt             time.Time                 `json:"createdAt"`
+	StartedAt             *time.Time                `json:"startedAt,omitempty"`
+	CompletedAt           *time.Time                `json:"completedAt,omitempty"`
+	CurrentIndex          int                       `json:"currentIndex"`
+	Concurrency           int                       `json:"concurrency"`
+	TaskTotal             int                       `json:"task_total"`
+	TaskCounts            map[string]int            `json:"task_counts"`
+	Tasks                 []batchTaskMCPListSummary `json:"tasks"`
+}
+
+func truncateStringRunes(s string, maxRunes int) string {
+	if maxRunes <= 0 {
+		return ""
+	}
+	n := 0
+	for i := range s {
+		if n == maxRunes {
+			out := strings.TrimSpace(s[:i])
+			if out == "" {
+				return "…"
+			}
+			return out + "…"
+		}
+		n++
+	}
+	return s
+}
+
+const mcpBatchListMaxTasksPerQueue = 200 // 列表中每个队列最多返回的子任务摘要数
+
+func toBatchTaskQueueMCPListItem(q *BatchTaskQueue) batchTaskQueueMCPListItem {
+	counts := map[string]int{
+		"pending":   0,
+		"running":   0,
+		"completed": 0,
+		"failed":    0,
+		"cancelled": 0,
+	}
+	tasks := make([]batchTaskMCPListSummary, 0, len(q.Tasks))
+	for _, t := range q.Tasks {
+		if t == nil {
+			continue
+		}
+		counts[t.Status]++
+		// 列表视图限制子任务摘要数量，完整列表通过 batch_task_get 查看
+		if len(tasks) < mcpBatchListMaxTasksPerQueue {
+			tasks = append(tasks, batchTaskMCPListSummary{
+				ID:      t.ID,
+				Status:  t.Status,
+				Message: truncateStringRunes(t.Message, mcpBatchListTaskMessageMaxRunes),
+			})
+		}
+	}
+	return batchTaskQueueMCPListItem{
+		ID:                    q.ID,
+		Title:                 q.Title,
+		Role:                  q.Role,
+		AgentMode:             q.AgentMode,
+		ScheduleMode:          q.ScheduleMode,
+		CronExpr:              q.CronExpr,
+		NextRunAt:             q.NextRunAt,
+		ScheduleEnabled:       q.ScheduleEnabled,
+		LastScheduleTriggerAt: q.LastScheduleTriggerAt,
+		Status:                q.Status,
+		CreatedAt:             q.CreatedAt,
+		StartedAt:             q.StartedAt,
+		CompletedAt:           q.CompletedAt,
+		CurrentIndex:          q.CurrentIndex,
+		Concurrency:           q.Concurrency,
+		TaskTotal:             len(tasks),
+		TaskCounts:            counts,
+		Tasks:                 tasks,
+	}
+}
+
+func batchMCPTextResult(text string, isErr bool) *mcp.ToolResult {
+	return &mcp.ToolResult{
+		Content: []mcp.Content{{Type: "text", Text: text}},
+		IsError: isErr,
+	}
+}
+
+func batchMCPJSONResult(v interface{}) (*mcp.ToolResult, error) {
+	b, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		return batchMCPTextResult(fmt.Sprintf("JSON 编码失败: %v", err), true), nil
+	}
+	return &mcp.ToolResult{Content: []mcp.Content{{Type: "text", Text: string(b)}}}, nil
+}
+
+func batchMCPTasksFromArgs(args map[string]interface{}) ([]string, string) {
+	if raw, ok := args["tasks"]; ok && raw != nil {
+		switch t := raw.(type) {
+		case []interface{}:
+			out := make([]string, 0, len(t))
+			for _, x := range t {
+				if s, ok := x.(string); ok {
+					if tr := strings.TrimSpace(s); tr != "" {
+						out = append(out, tr)
+					}
+				}
+			}
+			if len(out) > 0 {
+				return out, ""
+			}
+		}
+	}
+	if txt := mcpArgString(args, "tasks_text"); txt != "" {
+		lines := strings.Split(txt, "\n")
+		out := make([]string, 0, len(lines))
+		for _, line := range lines {
+			if tr := strings.TrimSpace(line); tr != "" {
+				out = append(out, tr)
+			}
+		}
+		if len(out) > 0 {
+			return out, ""
+		}
+	}
+	return nil, "需要提供 tasks（字符串数组）或 tasks_text（多行文本，每行一条任务）"
+}
+
+func mcpArgString(args map[string]interface{}, key string) string {
+	v, ok := args[key]
+	if !ok || v == nil {
+		return ""
+	}
+	switch t := v.(type) {
+	case string:
+		return strings.TrimSpace(t)
+	case float64:
+		return strings.TrimSpace(strconv.FormatFloat(t, 'f', -1, 64))
+	case json.Number:
+		return strings.TrimSpace(t.String())
+	default:
+		return strings.TrimSpace(fmt.Sprint(t))
+	}
+}
+
+func mcpArgFloat(args map[string]interface{}, key string) float64 {
+	v, ok := args[key]
+	if !ok || v == nil {
+		return 0
+	}
+	switch t := v.(type) {
+	case float64:
+		return t
+	case int:
+		return float64(t)
+	case int64:
+		return float64(t)
+	case json.Number:
+		f, _ := t.Float64()
+		return f
+	case string:
+		f, _ := strconv.ParseFloat(strings.TrimSpace(t), 64)
+		return f
+	default:
+		return 0
+	}
+}
+
+func mcpArgBool(args map[string]interface{}, key string) (val bool, ok bool) {
+	v, exists := args[key]
+	if !exists {
+		return false, false
+	}
+	switch t := v.(type) {
+	case bool:
+		return t, true
+	case string:
+		s := strings.ToLower(strings.TrimSpace(t))
+		if s == "true" || s == "1" || s == "yes" {
+			return true, true
+		}
+		if s == "false" || s == "0" || s == "no" {
+			return false, true
+		}
+	case float64:
+		return t != 0, true
+	}
+	return false, false
+}

internal/handler/config_eino_resilience_test.go

@@ -0,0 +1,64 @@
+package handler
+
+import (
+	"testing"
+
+	"cyberstrike-ai/internal/config"
+	"gopkg.in/yaml.v3"
+)
+
+func TestUpdateMultiAgentConfigWritesEinoModelResilience(t *testing.T) {
+	doc := &yaml.Node{
+		Kind: yaml.DocumentNode,
+		Content: []*yaml.Node{{
+			Kind: yaml.MappingNode,
+			Tag:  "!!map",
+		}},
+	}
+
+	updateMultiAgentConfig(doc, config.MultiAgentConfig{
+		Enabled:                      true,
+		RobotDefaultAgentMode:        "deep",
+		PlanExecuteLoopMaxIterations: 3,
+		EinoMiddleware: config.MultiAgentEinoMiddlewareConfig{
+			ModelRetryMaxRetries:    5,
+			ModelRetryMaxBackoffSec: 45,
+			ModelFailoverChannels:   []string{"backup-openai", "backup-claude", "backup-openai"},
+			ModelFailoverMaxRetries: 2,
+		},
+	})
+
+	var got struct {
+		MultiAgent struct {
+			EinoMiddleware struct {
+				ModelRetryMaxRetries    int      `yaml:"model_retry_max_retries"`
+				ModelRetryMaxBackoffSec int      `yaml:"model_retry_max_backoff_sec"`
+				ModelFailoverChannels   []string `yaml:"model_failover_channels"`
+				ModelFailoverMaxRetries int      `yaml:"model_failover_max_retries"`
+			} `yaml:"eino_middleware"`
+		} `yaml:"multi_agent"`
+	}
+	if err := doc.Decode(&got); err != nil {
+		t.Fatalf("decode config yaml: %v", err)
+	}
+
+	mw := got.MultiAgent.EinoMiddleware
+	if mw.ModelRetryMaxRetries != 5 {
+		t.Fatalf("model_retry_max_retries = %d, want 5", mw.ModelRetryMaxRetries)
+	}
+	if mw.ModelRetryMaxBackoffSec != 45 {
+		t.Fatalf("model_retry_max_backoff_sec = %d, want 45", mw.ModelRetryMaxBackoffSec)
+	}
+	if mw.ModelFailoverMaxRetries != 2 {
+		t.Fatalf("model_failover_max_retries = %d, want 2", mw.ModelFailoverMaxRetries)
+	}
+	wantChannels := []string{"backup-openai", "backup-claude"}
+	if len(mw.ModelFailoverChannels) != len(wantChannels) {
+		t.Fatalf("model_failover_channels = %#v, want %#v", mw.ModelFailoverChannels, wantChannels)
+	}
+	for i, want := range wantChannels {
+		if mw.ModelFailoverChannels[i] != want {
+			t.Fatalf("model_failover_channels[%d] = %q, want %q", i, mw.ModelFailoverChannels[i], want)
+		}
+	}
+}

internal/handler/conversation.go

@@ -0,0 +1,625 @@
+package handler
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// ConversationTaskStopper cancels in-flight agent work when a conversation is removed.
+type ConversationTaskStopper interface {
+	CancelRunningTaskForConversation(conversationID string)
+}
+
+// ConversationTaskStateProvider reports whether the in-memory agent task for
+// a conversation is still genuinely running. Plan files may survive a service
+// restart or cancellation, so their status alone is not authoritative.
+type ConversationTaskStateProvider interface {
+	ConversationTaskRuntimeState(conversationID string) (running bool, startedAt time.Time)
+}
+
+// ConversationHandler 对话处理器
+type ConversationHandler struct {
+	db          *database.DB
+	logger      *zap.Logger
+	audit       *audit.Service
+	taskStopper ConversationTaskStopper
+	taskState   ConversationTaskStateProvider
+}
+
+// SetAudit wires platform audit logging.
+func (h *ConversationHandler) SetAudit(s *audit.Service) {
+	h.audit = s
+}
+
+// SetTaskStopper wires cancellation of in-flight agent tasks on conversation delete.
+func (h *ConversationHandler) SetTaskStopper(stopper ConversationTaskStopper) {
+	h.taskStopper = stopper
+}
+
+// SetTaskStateProvider wires the live agent task registry used by supplemental
+// conversation UI such as the agent-maintained plan list.
+func (h *ConversationHandler) SetTaskStateProvider(provider ConversationTaskStateProvider) {
+	h.taskState = provider
+}
+
+// NewConversationHandler 创建新的对话处理器
+func NewConversationHandler(db *database.DB, logger *zap.Logger) *ConversationHandler {
+	return &ConversationHandler{
+		db:     db,
+		logger: logger,
+	}
+}
+
+// CreateConversationRequest 创建对话请求
+type CreateConversationRequest struct {
+	Title     string `json:"title"`
+	ProjectID string `json:"projectId,omitempty"`
+}
+
+// SetConversationProjectRequest 设置对话所属项目
+type SetConversationProjectRequest struct {
+	ProjectID string `json:"projectId"` // 空字符串表示解除绑定
+}
+
+// CreateConversation 创建新对话
+func (h *ConversationHandler) CreateConversation(c *gin.Context) {
+	var req CreateConversationRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	title := req.Title
+	if title == "" {
+		title = "新对话"
+	}
+
+	meta := audit.ConversationCreateMetaFromGin(c, "api")
+	meta.ProjectID = strings.TrimSpace(req.ProjectID)
+	if !h.conversationProjectAllowed(c, meta.ProjectID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问目标项目"})
+		return
+	}
+	conv, err := h.db.CreateConversation(title, meta)
+	if err != nil {
+		h.logger.Error("创建对话失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if session, ok := security.CurrentSession(c); ok {
+		_ = h.db.SetResourceOwner("conversation", conv.ID, session.UserID)
+		_ = h.db.AssignResourceToUser(session.UserID, "conversation", conv.ID)
+		if conv.ProjectID != "" {
+			_ = h.db.AssignResourceToUser(session.UserID, "project", conv.ProjectID)
+		}
+	}
+
+	c.JSON(http.StatusOK, conv)
+}
+
+// SetConversationProject 设置或清除对话绑定的项目
+func (h *ConversationHandler) SetConversationProject(c *gin.Context) {
+	id := c.Param("id")
+	var req SetConversationProjectRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if _, err := h.db.GetConversation(id); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "对话不存在"})
+		return
+	}
+	projectID := strings.TrimSpace(req.ProjectID)
+	if !h.conversationProjectAllowed(c, projectID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问目标项目"})
+		return
+	}
+	if err := h.db.SetConversationProjectID(id, projectID); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true, "projectId": projectID})
+}
+
+func (h *ConversationHandler) conversationProjectAllowed(c *gin.Context, projectID string) bool {
+	projectID = strings.TrimSpace(projectID)
+	if projectID == "" {
+		return true
+	}
+	session, ok := security.CurrentSession(c)
+	if !ok {
+		return false
+	}
+	return h.db.UserCanAccessResource(session.UserID, session.Scope, "project", projectID)
+}
+
+// ListConversations 列出对话
+func (h *ConversationHandler) ListConversations(c *gin.Context) {
+	limitStr := c.DefaultQuery("limit", "50")
+	offsetStr := c.DefaultQuery("offset", "0")
+	search := c.Query("search") // 获取搜索参数
+	projectID := strings.TrimSpace(c.Query("project_id"))
+
+	limit, _ := strconv.Atoi(limitStr)
+	offset, _ := strconv.Atoi(offsetStr)
+
+	if limit <= 0 {
+		limit = 50
+	}
+	if limit > 1000 {
+		limit = 1000
+	}
+
+	excludeGrouped := strings.TrimSpace(search) == "" && projectID == "" &&
+		(c.Query("exclude_grouped") == "true" || c.Query("exclude_grouped") == "1")
+	sortBy := strings.TrimSpace(c.Query("sort_by"))
+	session, _ := security.CurrentSession(c)
+
+	var conversations []*database.Conversation
+	var total int
+	var err error
+	if excludeGrouped {
+		conversations, err = h.db.ListUngroupedConversationsForAccess(limit, offset, sortBy, projectID, session.UserID, session.Scope)
+		if err == nil {
+			total, err = h.db.CountUngroupedConversationsForAccess(projectID, session.UserID, session.Scope)
+		}
+	} else {
+		conversations, err = h.db.ListConversationsForAccess(limit, offset, search, sortBy, projectID, session.UserID, session.Scope)
+		if err == nil {
+			total, err = h.db.CountConversationsForAccess(search, projectID, session.UserID, session.Scope)
+		}
+	}
+	if err != nil {
+		h.logger.Error("获取对话列表失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if conversations == nil {
+		conversations = []*database.Conversation{}
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"conversations": conversations,
+		"total":         total,
+		"limit":         limit,
+		"offset":        offset,
+	})
+}
+
+// GetConversation 获取对话
+func (h *ConversationHandler) GetConversation(c *gin.Context) {
+	id := c.Param("id")
+
+	// 默认轻量加载，只有用户需要展开详情时再按需拉取
+	// include_process_details=1/true 时返回全量 processDetails（兼容旧行为）
+	includeStr := c.DefaultQuery("include_process_details", "0")
+	include := includeStr == "1" || includeStr == "true" || includeStr == "yes"
+
+	var (
+		conv *database.Conversation
+		err  error
+	)
+	if include {
+		conv, err = h.db.GetConversation(id)
+	} else {
+		conv, err = h.db.GetConversationLite(id)
+	}
+	if err != nil {
+		h.logger.Error("获取对话失败", zap.Error(err))
+		c.JSON(http.StatusNotFound, gin.H{"error": "对话不存在"})
+		return
+	}
+
+	c.JSON(http.StatusOK, conv)
+}
+
+// GetConversationPlanTasks returns the task list maintained by the agent's
+// TaskCreate/TaskUpdate tools for this conversation.
+func (h *ConversationHandler) GetConversationPlanTasks(c *gin.Context) {
+	id := strings.TrimSpace(c.Param("id"))
+	session, ok := security.CurrentSession(c)
+	if !ok || !h.db.UserCanAccessResource(session.UserID, session.Scope, "conversation", id) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该对话"})
+		return
+	}
+	if _, err := h.db.GetConversationLite(id); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "对话不存在"})
+		return
+	}
+	running := false
+	startedAt := time.Time{}
+	if h.taskState != nil {
+		running, startedAt = h.taskState.ConversationTaskRuntimeState(id)
+	}
+	if !running {
+		c.JSON(http.StatusOK, gin.H{
+			"tasks": []database.ConversationPlanTask{}, "total": 0,
+			"completed": 0, "activeStep": 0, "running": false,
+		})
+		return
+	}
+	tasks, err := h.db.ListConversationPlanTasksSince(id, startedAt)
+	if err != nil {
+		h.logger.Error("获取对话任务列表失败", zap.String("conversationId", id), zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "获取任务列表失败"})
+		return
+	}
+
+	completed := 0
+	activeStep := 0
+	for i, task := range tasks {
+		status := strings.ToLower(strings.TrimSpace(task.Status))
+		if status == "completed" {
+			completed++
+		}
+		if activeStep == 0 && status == "in_progress" {
+			activeStep = i + 1
+		}
+	}
+	if activeStep == 0 {
+		for i, task := range tasks {
+			if strings.ToLower(strings.TrimSpace(task.Status)) != "completed" {
+				activeStep = i + 1
+				break
+			}
+		}
+	}
+	if activeStep == 0 && len(tasks) > 0 {
+		activeStep = len(tasks)
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"tasks":      tasks,
+		"total":      len(tasks),
+		"completed":  completed,
+		"activeStep": activeStep,
+		"running":    true,
+	})
+}
+
+const (
+	defaultProcessDetailsPageLimit = 50
+	maxProcessDetailsPageLimit     = 500
+)
+
+// GetMessageProcessDetails 获取指定消息的过程详情（按需加载）
+// 查询参数：
+//   - summary=1：仅返回摘要（total / iterationCount / maxIteration）
+//   - limit + offset：分页返回 processDetails（未指定 limit 时默认 50 条）
+//   - anchorId：返回包含该过程详情锚点的一页，适合从工具按钮精准定位
+//   - full=1：显式返回全量 processDetails（用于导出/兼容旧集成，不建议 UI 展开时使用）
+func (h *ConversationHandler) GetMessageProcessDetails(c *gin.Context) {
+	messageID := c.Param("id")
+	if messageID == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "message id required"})
+		return
+	}
+
+	summaryStr := strings.TrimSpace(c.Query("summary"))
+	if summaryStr == "1" || strings.EqualFold(summaryStr, "true") || strings.EqualFold(summaryStr, "yes") {
+		summary, err := h.db.GetProcessDetailsSummary(messageID)
+		if err != nil {
+			h.logger.Error("获取过程详情摘要失败", zap.Error(err))
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"summary": summary})
+		return
+	}
+
+	fullStr := strings.TrimSpace(c.Query("full"))
+	if fullStr == "1" || strings.EqualFold(fullStr, "true") || strings.EqualFold(fullStr, "yes") {
+		details, err := h.db.GetProcessDetails(messageID)
+		if err != nil {
+			h.logger.Error("获取过程详情失败", zap.Error(err))
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+
+		details = database.DedupeConsecutiveProcessDetails(details)
+		out := processDetailsToJSON(h.logger, h.db, details, true)
+		c.JSON(http.StatusOK, gin.H{
+			"processDetails": out,
+			"total":          len(out),
+			"offset":         0,
+			"limit":          len(out),
+			"hasMore":        false,
+		})
+		return
+	}
+
+	limitStr := strings.TrimSpace(c.Query("limit"))
+	limit := defaultProcessDetailsPageLimit
+	if limitStr != "" {
+		parsedLimit, err := strconv.Atoi(limitStr)
+		if err != nil || parsedLimit <= 0 {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid limit"})
+			return
+		}
+		limit = parsedLimit
+	}
+	if limit > maxProcessDetailsPageLimit {
+		limit = maxProcessDetailsPageLimit
+	}
+	offset, _ := strconv.Atoi(strings.TrimSpace(c.Query("offset")))
+	if offset < 0 {
+		offset = 0
+	}
+	anchorID := strings.TrimSpace(c.Query("anchorId"))
+	if anchorID != "" {
+		anchorOffset, err := h.db.GetProcessDetailOffset(messageID, anchorID)
+		if err != nil {
+			h.logger.Warn("获取过程详情锚点位置失败", zap.Error(err), zap.String("messageID", messageID), zap.String("anchorID", anchorID))
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+			return
+		}
+		offset = anchorOffset - limit/3
+		if offset < 0 {
+			offset = 0
+		}
+	}
+
+	details, total, err := h.db.GetProcessDetailsPage(messageID, limit, offset)
+	if err != nil {
+		h.logger.Error("分页获取过程详情失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	details = database.DedupeConsecutiveProcessDetails(details)
+	out := processDetailsToJSON(h.logger, h.db, details, false)
+	// A page may end between tool_call and tool_result. Return the full-history
+	// execution summary so the UI can render terminal status without pretending
+	// that an unloaded result is still running.
+	summary, summaryErr := h.db.GetProcessDetailsSummary(messageID)
+	if summaryErr != nil {
+		h.logger.Warn("获取分页工具执行状态失败", zap.Error(summaryErr), zap.String("messageID", messageID))
+	}
+	var toolExecutions []database.ProcessDetailsToolExecution
+	if summary != nil {
+		toolExecutions = summary.ToolExecutions
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"processDetails": out,
+		"toolExecutions": toolExecutions,
+		"total":          total,
+		"offset":         offset,
+		"limit":          limit,
+		"hasMore":        offset+len(out) < total,
+	})
+}
+
+// GetProcessDetail 获取单条完整过程详情。列表接口默认不给工具 payload，用户点开单条工具时再拉这里。
+func (h *ConversationHandler) GetProcessDetail(c *gin.Context) {
+	id := strings.TrimSpace(c.Param("id"))
+	if id == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "process detail id required"})
+		return
+	}
+	detail, err := h.db.GetProcessDetailByID(id)
+	if err != nil {
+		h.logger.Error("获取过程详情失败", zap.Error(err))
+		c.JSON(http.StatusNotFound, gin.H{"error": "过程详情不存在"})
+		return
+	}
+	out := processDetailsToJSON(h.logger, h.db, []database.ProcessDetail{*detail}, true)
+	if len(out) == 0 {
+		c.JSON(http.StatusNotFound, gin.H{"error": "过程详情不存在"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"processDetail": out[0]})
+}
+
+func processDetailsToJSON(logger *zap.Logger, db *database.DB, details []database.ProcessDetail, includeToolPayload bool) []map[string]interface{} {
+	out := make([]map[string]interface{}, 0, len(details))
+	for _, d := range details {
+		var data interface{}
+		if d.Data != "" {
+			if err := json.Unmarshal([]byte(d.Data), &data); err != nil {
+				logger.Warn("解析过程详情数据失败", zap.Error(err))
+			}
+		}
+		if m, ok := data.(map[string]interface{}); ok {
+			enrichEmptyToolCallArgumentsFromExecution(logger, db, d, m)
+		}
+		if !includeToolPayload {
+			data = summarizeProcessDetailData(d.EventType, data)
+		}
+		out = append(out, map[string]interface{}{
+			"id":             d.ID,
+			"messageId":      d.MessageID,
+			"conversationId": d.ConversationID,
+			"eventType":      d.EventType,
+			"message":        d.Message,
+			"data":           data,
+			"createdAt":      d.CreatedAt,
+		})
+	}
+	return out
+}
+
+func enrichEmptyToolCallArgumentsFromExecution(logger *zap.Logger, db *database.DB, detail database.ProcessDetail, data map[string]interface{}) {
+	if db == nil || detail.EventType != "tool_call" || !toolCallArgumentsEmpty(data) {
+		return
+	}
+	toolName := strings.TrimSpace(fmt.Sprint(data["toolName"]))
+	if toolName == "" || detail.ConversationID == "" || detail.CreatedAt.IsZero() {
+		return
+	}
+	execID, args, err := db.FindNearestToolExecutionArguments(detail.ConversationID, toolName, detail.CreatedAt, 5*time.Second)
+	if err != nil {
+		if logger != nil {
+			logger.Debug("未能从工具执行记录补全过程详情参数",
+				zap.Error(err),
+				zap.String("processDetailId", detail.ID),
+				zap.String("toolName", toolName))
+		}
+		return
+	}
+	if len(args) == 0 {
+		return
+	}
+	data["argumentsObj"] = args
+	if b, err := json.Marshal(args); err == nil {
+		data["arguments"] = string(b)
+	}
+	if strings.TrimSpace(execID) != "" {
+		data["executionId"] = strings.TrimSpace(execID)
+	}
+}
+
+func toolCallArgumentsEmpty(data map[string]interface{}) bool {
+	if data == nil {
+		return true
+	}
+	if args, ok := data["argumentsObj"].(map[string]interface{}); ok && len(args) > 0 {
+		return false
+	}
+	if raw, ok := data["arguments"]; ok {
+		s := strings.TrimSpace(fmt.Sprint(raw))
+		return s == "" || s == "{}" || s == "null"
+	}
+	return true
+}
+
+func summarizeProcessDetailData(eventType string, data interface{}) interface{} {
+	m, ok := data.(map[string]interface{})
+	if !ok || (eventType != "tool_call" && eventType != "tool_result") {
+		return data
+	}
+	allow := map[string]bool{
+		"toolName": true, "toolCallId": true, "index": true, "total": true,
+		"success": true, "isError": true, "executionId": true,
+		"einoAgent": true, "einoRole": true, "einoScope": true, "orchestration": true,
+		"agentFacing": true,
+		"status":      true, "modelFacingIsError": true, "resultPreview": true,
+	}
+	out := make(map[string]interface{}, len(allow)+1)
+	for k, v := range m {
+		if allow[k] {
+			out[k] = v
+		}
+	}
+	out["_payloadDeferred"] = true
+	return out
+}
+
+// UpdateConversationRequest 更新对话请求
+type UpdateConversationRequest struct {
+	Title string `json:"title"`
+}
+
+// UpdateConversation 更新对话
+func (h *ConversationHandler) UpdateConversation(c *gin.Context) {
+	id := c.Param("id")
+
+	var req UpdateConversationRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if req.Title == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "标题不能为空"})
+		return
+	}
+
+	if err := h.db.UpdateConversationTitle(id, req.Title); err != nil {
+		h.logger.Error("更新对话失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// 返回更新后的对话
+	conv, err := h.db.GetConversation(id)
+	if err != nil {
+		h.logger.Error("获取更新后的对话失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, conv)
+}
+
+// DeleteConversation 删除对话
+func (h *ConversationHandler) DeleteConversation(c *gin.Context) {
+	id := c.Param("id")
+
+	if h.taskStopper != nil {
+		h.taskStopper.CancelRunningTaskForConversation(id)
+	}
+
+	if err := h.db.DeleteConversation(id); err != nil {
+		h.logger.Error("删除对话失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	if h.audit != nil {
+		h.audit.Record(c, audit.Entry{
+			Category:     "conversation",
+			Action:       "delete",
+			Result:       "success",
+			ResourceType: "conversation",
+			ResourceID:   id,
+			Message:      "删除对话",
+		})
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "删除成功"})
+}
+
+// DeleteTurnRequest 删除一轮对话（POST /api/conversations/:id/delete-turn）
+type DeleteTurnRequest struct {
+	MessageID string `json:"messageId"`
+}
+
+// DeleteConversationTurn 删除锚点消息所在轮次（从该轮 user 到下一轮 user 之前），并清空 last_react_*。
+func (h *ConversationHandler) DeleteConversationTurn(c *gin.Context) {
+	conversationID := c.Param("id")
+	if conversationID == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "conversation id required"})
+		return
+	}
+
+	var req DeleteTurnRequest
+	if err := c.ShouldBindJSON(&req); err != nil || req.MessageID == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "messageId required"})
+		return
+	}
+
+	if _, err := h.db.GetConversation(conversationID); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "对话不存在"})
+		return
+	}
+
+	deletedIDs, err := h.db.DeleteConversationTurn(conversationID, req.MessageID)
+	if err != nil {
+		h.logger.Warn("删除对话轮次失败",
+			zap.String("conversationId", conversationID),
+			zap.String("messageId", req.MessageID),
+			zap.Error(err),
+		)
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if h.audit != nil {
+		h.audit.RecordOK(c, "conversation", "delete_turn", "删除对话轮次", "conversation", conversationID, map[string]interface{}{
+			"message_id": req.MessageID,
+			"deleted":    len(deletedIDs),
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"deletedMessageIds": deletedIDs,
+		"message":           "ok",
+	})
+}

internal/handler/conversation_delete_task_test.go

@@ -0,0 +1,30 @@
+package handler
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"go.uber.org/zap"
+)
+
+func TestConversationHandlerDeleteConversationCancelsRunningTask(t *testing.T) {
+	tm := NewAgentTaskManager()
+	ctx, cancel := context.WithCancelCause(context.Background())
+	_, err := tm.StartTask("conv-1", "hello", cancel)
+	if err != nil {
+		t.Fatalf("StartTask: %v", err)
+	}
+
+	h := &AgentHandler{tasks: tm, logger: zap.NewNop()}
+	h.CancelRunningTaskForConversation("conv-1")
+
+	select {
+	case <-ctx.Done():
+	case <-time.After(2 * time.Second):
+		t.Fatal("task context was not cancelled")
+	}
+	if cause := context.Cause(ctx); cause != ErrTaskCancelled {
+		t.Fatalf("expected ErrTaskCancelled, got %v", cause)
+	}
+}

internal/handler/conversation_plantask_test.go

@@ -0,0 +1,151 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+type staticConversationTaskState struct {
+	running   bool
+	startedAt time.Time
+}
+
+func (s staticConversationTaskState) ConversationTaskRuntimeState(string) (bool, time.Time) {
+	return s.running, s.startedAt
+}
+
+func TestGetConversationPlanTasksRequiresAccessAndReportsProgress(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	tmp := t.TempDir()
+	db, err := database.NewDB(filepath.Join(tmp, "conversation-plantask.db"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewDB: %v", err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	conversation, err := db.CreateConversation("plan", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("CreateConversation: %v", err)
+	}
+	user, err := db.CreateRBACUser("plan-user", "Plan User", "hash", true, nil)
+	if err != nil {
+		t.Fatalf("CreateRBACUser: %v", err)
+	}
+	base := filepath.Join(tmp, "plantask")
+	db.SetEinoConversationDirs(base, "", "", "")
+	dir := filepath.Join(base, conversation.ID)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	for name, content := range map[string]string{
+		"1.json": `{"id":"1","subject":"完成项","status":"completed"}`,
+		"2.json": `{"id":"2","subject":"当前项","status":"in_progress"}`,
+		"3.json": `{"id":"3","subject":"等待项","status":"pending"}`,
+	} {
+		if err := os.WriteFile(filepath.Join(dir, name), []byte(content), 0o644); err != nil {
+			t.Fatalf("WriteFile: %v", err)
+		}
+	}
+
+	handler := NewConversationHandler(db, zap.NewNop())
+	handler.SetTaskStateProvider(staticConversationTaskState{running: true})
+	request := func() *httptest.ResponseRecorder {
+		w := httptest.NewRecorder()
+		c, _ := gin.CreateTestContext(w)
+		c.Request = httptest.NewRequest(http.MethodGet, "/api/conversations/"+conversation.ID+"/plan-tasks", nil)
+		c.Params = gin.Params{{Key: "id", Value: conversation.ID}}
+		c.Set(security.ContextSessionKey, security.Session{
+			UserID: user.ID,
+			Scope:  database.RBACScopeAssigned,
+		})
+		handler.GetConversationPlanTasks(c)
+		return w
+	}
+
+	w := request()
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("unassigned status = %d, want %d", w.Code, http.StatusForbidden)
+	}
+	if err := db.AssignResourceToUser(user.ID, "conversation", conversation.ID); err != nil {
+		t.Fatalf("AssignResourceToUser: %v", err)
+	}
+	w = request()
+	if w.Code != http.StatusOK {
+		t.Fatalf("assigned status = %d: %s", w.Code, w.Body.String())
+	}
+	var response struct {
+		Total      int                             `json:"total"`
+		Completed  int                             `json:"completed"`
+		ActiveStep int                             `json:"activeStep"`
+		Tasks      []database.ConversationPlanTask `json:"tasks"`
+		Running    bool                            `json:"running"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if response.Total != 3 || response.Completed != 1 || response.ActiveStep != 2 || !response.Running {
+		t.Fatalf("progress = %#v", response)
+	}
+}
+
+func TestGetConversationPlanTasksReportsStoppedLiveTask(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	tmp := t.TempDir()
+	db, err := database.NewDB(filepath.Join(tmp, "conversation-plantask-stopped.db"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewDB: %v", err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	conversation, err := db.CreateConversation("stopped plan", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("CreateConversation: %v", err)
+	}
+	user, err := db.CreateRBACUser("stopped-plan-user", "Stopped Plan User", "hash", true, nil)
+	if err != nil {
+		t.Fatalf("CreateRBACUser: %v", err)
+	}
+	if err := db.AssignResourceToUser(user.ID, "conversation", conversation.ID); err != nil {
+		t.Fatalf("AssignResourceToUser: %v", err)
+	}
+	base := filepath.Join(tmp, "plantask")
+	db.SetEinoConversationDirs(base, "", "", "")
+	dir := filepath.Join(base, conversation.ID)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "1.json"), []byte(`{"id":"1","subject":"残留项","status":"in_progress"}`), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	handler := NewConversationHandler(db, zap.NewNop())
+	handler.SetTaskStateProvider(staticConversationTaskState{running: false})
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/api/conversations/"+conversation.ID+"/plan-tasks", nil)
+	c.Params = gin.Params{{Key: "id", Value: conversation.ID}}
+	c.Set(security.ContextSessionKey, security.Session{UserID: user.ID, Scope: database.RBACScopeAssigned})
+	handler.GetConversationPlanTasks(c)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d: %s", w.Code, w.Body.String())
+	}
+	var response struct {
+		Running bool `json:"running"`
+		Total   int  `json:"total"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if response.Running || response.Total != 0 {
+		t.Fatalf("response = %#v", response)
+	}
+}

internal/handler/conversation_process_details_test.go

@@ -0,0 +1,141 @@
+package handler
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/mcp"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func TestProcessDetailsPageIncludesTerminalToolStatusAcrossPageBoundary(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "process-details-page.db"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewDB: %v", err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	conversation, err := db.CreateConversation("page boundary", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("CreateConversation: %v", err)
+	}
+	message, err := db.AddMessage(conversation.ID, "assistant", "done", nil)
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+	for i := 1; i <= 4; i++ {
+		id := fmt.Sprintf("call-%d", i)
+		if err := db.AddProcessDetail(message.ID, conversation.ID, "tool_call", "call", map[string]interface{}{
+			"toolName": "http-framework-test", "toolCallId": id, "index": i, "total": 4,
+		}); err != nil {
+			t.Fatalf("AddProcessDetail(tool_call): %v", err)
+		}
+	}
+	for i := 1; i <= 4; i++ {
+		id := fmt.Sprintf("call-%d", i)
+		if err := db.AddProcessDetail(message.ID, conversation.ID, "tool_result", "result", map[string]interface{}{
+			"toolName": "http-framework-test", "toolCallId": id, "success": true,
+		}); err != nil {
+			t.Fatalf("AddProcessDetail(tool_result): %v", err)
+		}
+	}
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("GET", "/api/messages/"+message.ID+"/process-details?limit=6&offset=0", nil)
+	c.Params = gin.Params{{Key: "id", Value: message.ID}}
+	NewConversationHandler(db, zap.NewNop()).GetMessageProcessDetails(c)
+	if w.Code != 200 {
+		t.Fatalf("status = %d: %s", w.Code, w.Body.String())
+	}
+	var response struct {
+		HasMore        bool                                   `json:"hasMore"`
+		ProcessDetails []map[string]interface{}               `json:"processDetails"`
+		ToolExecutions []database.ProcessDetailsToolExecution `json:"toolExecutions"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if !response.HasMore || len(response.ProcessDetails) != 6 {
+		t.Fatalf("page hasMore=%v details=%d, want true/6", response.HasMore, len(response.ProcessDetails))
+	}
+	if len(response.ToolExecutions) != 4 {
+		t.Fatalf("tool executions = %d, want 4", len(response.ToolExecutions))
+	}
+	for i, execution := range response.ToolExecutions {
+		if execution.Status != "completed" {
+			t.Fatalf("execution %d status = %q, want completed", i, execution.Status)
+		}
+	}
+}
+
+func TestProcessDetailsFullBackfillsEmptyToolCallArgumentsFromExecution(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "process-details-args.db"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewDB: %v", err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	conversation, err := db.CreateConversation("empty args", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("CreateConversation: %v", err)
+	}
+	message, err := db.AddMessage(conversation.ID, "assistant", "done", nil)
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+	if err := db.AddProcessDetail(message.ID, conversation.ID, "tool_call", "calling exec", map[string]interface{}{
+		"toolName": "exec", "toolCallId": "call-empty", "arguments": "", "argumentsObj": nil,
+	}); err != nil {
+		t.Fatalf("AddProcessDetail(tool_call): %v", err)
+	}
+	if err := db.SaveToolExecution(&mcp.ToolExecution{
+		ID:             "exec-whoami",
+		ToolName:       "exec",
+		Arguments:      map[string]interface{}{"command": "whoami"},
+		Status:         "completed",
+		StartTime:      time.Now(),
+		ConversationID: conversation.ID,
+	}); err != nil {
+		t.Fatalf("SaveToolExecution: %v", err)
+	}
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("GET", "/api/messages/"+message.ID+"/process-details?full=1", nil)
+	c.Params = gin.Params{{Key: "id", Value: message.ID}}
+	NewConversationHandler(db, zap.NewNop()).GetMessageProcessDetails(c)
+	if w.Code != 200 {
+		t.Fatalf("status = %d: %s", w.Code, w.Body.String())
+	}
+	var response struct {
+		ProcessDetails []map[string]interface{} `json:"processDetails"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if len(response.ProcessDetails) != 1 {
+		t.Fatalf("process details = %d, want 1", len(response.ProcessDetails))
+	}
+	data, ok := response.ProcessDetails[0]["data"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("data = %#v", response.ProcessDetails[0]["data"])
+	}
+	args, ok := data["argumentsObj"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("argumentsObj = %#v", data["argumentsObj"])
+	}
+	if args["command"] != "whoami" {
+		t.Fatalf("command = %#v, want whoami", args["command"])
+	}
+	if data["executionId"] != "exec-whoami" {
+		t.Fatalf("executionId = %#v, want exec-whoami", data["executionId"])
+	}
+}

internal/handler/conversation_rbac_test.go

@@ -0,0 +1,118 @@
+package handler
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func TestCreateConversationRequiresProjectAccess(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, user := setupConversationRBACTest(t)
+	project, err := db.CreateProject(&database.Project{Name: "hidden"})
+	if err != nil {
+		t.Fatalf("CreateProject: %v", err)
+	}
+	handler := NewConversationHandler(db, zap.NewNop())
+
+	w := performConversationRequest(user, http.MethodPost, "/api/conversations", map[string]string{
+		"title":     "blocked",
+		"projectId": project.ID,
+	}, handler.CreateConversation)
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want %d: %s", w.Code, http.StatusForbidden, w.Body.String())
+	}
+
+	if err := db.AssignResourceToUser(user.ID, "project", project.ID); err != nil {
+		t.Fatalf("AssignResourceToUser: %v", err)
+	}
+	w = performConversationRequest(user, http.MethodPost, "/api/conversations", map[string]string{
+		"title":     "allowed",
+		"projectId": project.ID,
+	}, handler.CreateConversation)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d: %s", w.Code, http.StatusOK, w.Body.String())
+	}
+}
+
+func TestSetConversationProjectRequiresProjectAccess(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, user := setupConversationRBACTest(t)
+	project, err := db.CreateProject(&database.Project{Name: "hidden"})
+	if err != nil {
+		t.Fatalf("CreateProject: %v", err)
+	}
+	conv, err := db.CreateConversation("owned", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("CreateConversation: %v", err)
+	}
+	if err := db.SetResourceOwner("conversation", conv.ID, user.ID); err != nil {
+		t.Fatalf("SetResourceOwner: %v", err)
+	}
+	if err := db.AssignResourceToUser(user.ID, "conversation", conv.ID); err != nil {
+		t.Fatalf("AssignResourceToUser conversation: %v", err)
+	}
+	handler := NewConversationHandler(db, zap.NewNop())
+
+	w := performConversationRequest(user, http.MethodPut, "/api/conversations/"+conv.ID+"/project", map[string]string{
+		"projectId": project.ID,
+	}, func(c *gin.Context) {
+		c.Params = gin.Params{{Key: "id", Value: conv.ID}}
+		handler.SetConversationProject(c)
+	})
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want %d: %s", w.Code, http.StatusForbidden, w.Body.String())
+	}
+
+	if err := db.AssignResourceToUser(user.ID, "project", project.ID); err != nil {
+		t.Fatalf("AssignResourceToUser project: %v", err)
+	}
+	w = performConversationRequest(user, http.MethodPut, "/api/conversations/"+conv.ID+"/project", map[string]string{
+		"projectId": project.ID,
+	}, func(c *gin.Context) {
+		c.Params = gin.Params{{Key: "id", Value: conv.ID}}
+		handler.SetConversationProject(c)
+	})
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d: %s", w.Code, http.StatusOK, w.Body.String())
+	}
+}
+
+func setupConversationRBACTest(t *testing.T) (*database.DB, *database.RBACUser) {
+	t.Helper()
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "conversation-rbac.db"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewDB: %v", err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	user, err := db.CreateRBACUser("operator1", "Operator One", "hash", true, nil)
+	if err != nil {
+		t.Fatalf("CreateRBACUser: %v", err)
+	}
+	return db, user
+}
+
+func performConversationRequest(user *database.RBACUser, method, path string, body map[string]string, handler gin.HandlerFunc) *httptest.ResponseRecorder {
+	payload, _ := json.Marshal(body)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(method, path, bytes.NewReader(payload))
+	c.Request.Header.Set("Content-Type", "application/json")
+	c.Set(security.ContextSessionKey, security.Session{
+		UserID:      user.ID,
+		Username:    user.Username,
+		Permissions: map[string]bool{"chat:write": true},
+		Scope:       database.RBACScopeAssigned,
+	})
+	handler(c)
+	return w
+}

internal/handler/eino_empty_response_continue.go

@@ -0,0 +1,83 @@
+package handler
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"cyberstrike-ai/internal/agent"
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/multiagent"
+
+	"go.uber.org/zap"
+)
+
+// rebindEinoRunningTask 中断并继续 / 空正文续跑：重建 cancel 链与超时 ctx，保持任务 running。
+func (h *AgentHandler) rebindEinoRunningTask(parent context.Context, conversationID string, timeoutCancel context.CancelFunc) (context.Context, context.CancelCauseFunc, context.Context, context.CancelFunc) {
+	if timeoutCancel != nil {
+		timeoutCancel()
+	}
+	baseCtx, cancelWithCause := context.WithCancelCause(detachedAgentContext(parent))
+	h.tasks.BindTaskCancel(conversationID, cancelWithCause)
+	taskCtx, newTimeoutCancel := context.WithTimeout(baseCtx, 600*time.Minute)
+	h.tasks.UpdateTaskStatus(conversationID, "running")
+	return baseCtx, cancelWithCause, taskCtx, newTimeoutCancel
+}
+
+// tryContinueOnEinoEmptyResponse Run 成功但 Response 为 emptyHint 时退避续跑；true 表示已准备下一段 Run。
+func (h *AgentHandler) tryContinueOnEinoEmptyResponse(
+	taskCtx context.Context,
+	mw *config.MultiAgentEinoMiddlewareConfig,
+	conversationID string,
+	result *multiagent.RunResult,
+	attempt *int,
+	curHistory *[]agent.ChatMessage,
+	curFinalMessage *string,
+	progressCallback func(eventType, message string, data interface{}),
+) bool {
+	if result == nil || !multiagent.IsEinoEmptyResponseResult(result) || !multiagent.HasEinoResumeTrace(result) {
+		return false
+	}
+	maxAttempts := multiagent.EmptyResponseContinueMaxAttemptsFromConfig(mw)
+	if *attempt >= maxAttempts {
+		if h.logger != nil {
+			h.logger.Warn("eino empty response continue exhausted",
+				zap.String("conversationId", conversationID),
+				zap.Int("maxAttempts", maxAttempts))
+		}
+		return false
+	}
+	*attempt++
+	h.persistEinoAgentTraceForResume(conversationID, result)
+
+	backoff := multiagent.EmptyResponseContinueBackoff(*attempt-1, mw)
+	waitMsg := fmt.Sprintf("会话已结束但未捕获到助手正文，%d 秒后第 %d/%d 次自动续跑…",
+		int(backoff.Seconds()), *attempt, maxAttempts)
+	if progressCallback != nil {
+		progressCallback("eino_empty_response_continue", waitMsg, map[string]interface{}{
+			"conversationId": conversationID,
+			"source":         "eino",
+			"attempt":        *attempt,
+			"maxAttempts":    maxAttempts,
+			"backoffSec":     int(backoff.Seconds()),
+		})
+	}
+	select {
+	case <-taskCtx.Done():
+		return false
+	case <-time.After(backoff):
+	}
+
+	h.applyEinoTraceResumeSegment(conversationID, result, curHistory, curFinalMessage, "")
+	if progressCallback != nil {
+		progressCallback("eino_empty_response_continue", "已恢复上下文，正在续跑…", map[string]interface{}{
+			"conversationId":   conversationID,
+			"source":           "eino",
+			"attempt":          *attempt,
+			"maxAttempts":      maxAttempts,
+			"contextSource":    "empty_response_continue",
+			"contextInjection": false,
+		})
+	}
+	return true
+}

internal/handler/eino_resume_segment.go

@@ -0,0 +1,27 @@
+package handler
+
+import (
+	"context"
+
+	"cyberstrike-ai/internal/agent"
+	"cyberstrike-ai/internal/multiagent"
+)
+
+// applyEinoTraceResumeSegment 中断并继续：persist last_react_* → loadHistory，可选替换下一段 user 文案。
+func (h *AgentHandler) applyEinoTraceResumeSegment(
+	conversationID string,
+	result *multiagent.RunResult,
+	curHistory *[]agent.ChatMessage,
+	curFinalMessage *string,
+	segmentUserMessage string,
+) {
+	if shouldPersistEinoAgentTraceAfterRunError(context.Background()) {
+		h.persistEinoAgentTraceForResume(conversationID, result)
+	}
+	if hist, err := h.loadHistoryFromAgentTrace(conversationID); err == nil && len(hist) > 0 {
+		*curHistory = hist
+	}
+	if segmentUserMessage != "" {
+		*curFinalMessage = segmentUserMessage
+	}
+}

internal/handler/eino_single_agent.go

@@ -0,0 +1,526 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"cyberstrike-ai/internal/agentfinalizer"
+	"cyberstrike-ai/internal/mcp"
+	"cyberstrike-ai/internal/multiagent"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// EinoSingleAgentLoopStream Eino ADK 单代理（ChatModelAgent + Runner）流式对话；不依赖 multi_agent.enabled。
+func (h *AgentHandler) EinoSingleAgentLoopStream(c *gin.Context) {
+	c.Header("Content-Type", "text/event-stream; charset=utf-8")
+	c.Header("Cache-Control", "no-cache")
+	c.Header("Connection", "keep-alive")
+
+	var req ChatRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		ev := StreamEvent{Type: "error", Message: "请求参数错误: " + err.Error()}
+		b, _ := json.Marshal(ev)
+		fmt.Fprintf(c.Writer, "data: %s\n\n", b)
+		done := StreamEvent{Type: "done", Message: ""}
+		db, _ := json.Marshal(done)
+		fmt.Fprintf(c.Writer, "data: %s\n\n", db)
+		if flusher, ok := c.Writer.(http.Flusher); ok {
+			flusher.Flush()
+		}
+		return
+	}
+
+	c.Header("X-Accel-Buffering", "no")
+
+	var baseCtx context.Context
+	clientDisconnected := false
+	var sseWriteMu sync.Mutex
+	var ssePublishConversationID string
+	sendEvent := func(eventType, message string, data interface{}) {
+		if eventType == "error" && baseCtx != nil {
+			cause := context.Cause(baseCtx)
+			if errors.Is(cause, ErrTaskCancelled) || errors.Is(cause, multiagent.ErrInterruptContinue) {
+				return
+			}
+		}
+		ev := StreamEvent{Type: eventType, Message: message, Data: data}
+		b, errMarshal := json.Marshal(ev)
+		if errMarshal != nil {
+			b = []byte(`{"type":"error","message":"marshal failed"}`)
+		}
+		sseLine := make([]byte, 0, len(b)+8)
+		sseLine = append(sseLine, []byte("data: ")...)
+		sseLine = append(sseLine, b...)
+		sseLine = append(sseLine, '\n', '\n')
+		if ssePublishConversationID != "" && h.taskEventBus != nil {
+			h.taskEventBus.Publish(ssePublishConversationID, sseLine)
+		}
+		if clientDisconnected {
+			return
+		}
+		select {
+		case <-c.Request.Context().Done():
+			clientDisconnected = true
+			return
+		default:
+		}
+		sseWriteMu.Lock()
+		_, err := c.Writer.Write(sseLine)
+		if err != nil {
+			sseWriteMu.Unlock()
+			clientDisconnected = true
+			return
+		}
+		if flusher, ok := c.Writer.(http.Flusher); ok {
+			flusher.Flush()
+		} else {
+			c.Writer.Flush()
+		}
+		sseWriteMu.Unlock()
+	}
+
+	h.logger.Info("收到 Eino ADK 单代理流式请求",
+		zap.String("conversationId", req.ConversationID),
+	)
+
+	prep, err := h.prepareMultiAgentSession(&req, c, "eino_agent_stream")
+	if err != nil {
+		sendEvent("error", err.Error(), nil)
+		sendEvent("done", "", nil)
+		return
+	}
+	ssePublishConversationID = prep.ConversationID
+	if prep.CreatedNew {
+		sendEvent("conversation", "会话已创建", map[string]interface{}{
+			"conversationId": prep.ConversationID,
+		})
+	}
+
+	conversationID := prep.ConversationID
+	assistantMessageID := prep.AssistantMessageID
+	h.activateHITLForConversation(conversationID, req.Hitl)
+	if h.hitlManager != nil {
+		defer h.hitlManager.DeactivateConversation(conversationID)
+	}
+
+	if prep.UserMessageID != "" {
+		sendEvent("message_saved", "", map[string]interface{}{
+			"conversationId": conversationID,
+			"userMessageId":  prep.UserMessageID,
+		})
+	}
+	if h.runRoleWorkflowStreamIfBound(c, &req, prep, sendEvent) {
+		return
+	}
+
+	var cancelWithCause context.CancelCauseFunc
+	curFinalMessage := prep.FinalMessage
+	curHistory := prep.History
+	roleTools := prep.RoleTools
+
+	taskStatus := "completed"
+	// 仅在成功 StartTask 后再 FinishTask。若 StartTask 因 ErrTaskAlreadyRunning 失败仍 defer FinishTask，
+	// 会误删其他连接上正在运行的同会话任务，导致「第一次拦截、第二次却放行」。
+	taskOwned := false
+	defer func() {
+		if taskOwned {
+			h.tasks.FinishTask(conversationID, taskStatus)
+		}
+	}()
+
+	sendEvent("progress", "正在启动 Eino ADK 单代理（ChatModelAgent）...", map[string]interface{}{
+		"conversationId": conversationID,
+	})
+
+	stopKeepalive := runSSEKeepalive(c, &sseWriteMu)
+	defer stopKeepalive()
+
+	if h.config == nil {
+		taskStatus = "failed"
+		h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+		sendEvent("error", "服务器配置未加载", nil)
+		sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+		return
+	}
+	runCfg, resolvedAIChannelID, err := h.configForAIChannel(req.AIChannelID)
+	if err != nil {
+		taskStatus = "failed"
+		h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+		sendEvent("error", err.Error(), nil)
+		sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+		return
+	}
+
+	var result *multiagent.RunResult
+	var runErr error
+
+	baseCtx, cancelWithCause = context.WithCancelCause(detachedAgentContext(c.Request.Context()))
+	taskCtx, timeoutCancel := context.WithTimeout(baseCtx, 600*time.Minute)
+
+	if _, err := h.tasks.StartTask(conversationID, req.Message, cancelWithCause); err != nil {
+		var errorMsg string
+		if errors.Is(err, ErrTaskAlreadyRunning) {
+			errorMsg = "⚠️ 当前会话已有任务正在执行中，请等待当前任务完成或点击「停止任务」后再尝试。"
+			sendEvent("error", errorMsg, map[string]interface{}{
+				"conversationId": conversationID,
+				"errorType":      "task_already_running",
+			})
+		} else {
+			errorMsg = "❌ 无法启动任务: " + err.Error()
+			sendEvent("error", errorMsg, nil)
+		}
+		if assistantMessageID != "" {
+			_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", errorMsg, time.Now(), assistantMessageID)
+		}
+		sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+		timeoutCancel()
+		return
+	}
+	taskOwned = true
+
+	var cumulativeMCPExecutionIDs []string
+	// 同一请求内分段续跑时，主代理 iteration 事件按偏移累计，避免 UI 出现「第3轮 → 第1轮」回跳。
+	var mainIterationOffset int
+	var emptyResponseContinueAttempt int
+	var finalizationAutoContinueAttempt int
+	var decision agentfinalizer.Decision
+
+	for {
+		segmentMainIterationMax := 0
+		rawProgressCallback := h.createProgressCallback(taskCtx, cancelWithCause, conversationID, assistantMessageID, sendEvent)
+		progressCallback := func(eventType, message string, data interface{}) {
+			if eventType == "iteration" {
+				if m, ok := data.(map[string]interface{}); ok {
+					if scope, _ := m["einoScope"].(string); scope == "main" {
+						raw := 0
+						switch v := m["iteration"].(type) {
+						case int:
+							raw = v
+						case int32:
+							raw = int(v)
+						case int64:
+							raw = int(v)
+						case float64:
+							raw = int(v)
+						case float32:
+							raw = int(v)
+						}
+						if raw > 0 {
+							if raw > segmentMainIterationMax {
+								segmentMainIterationMax = raw
+							}
+							m["iteration"] = raw + mainIterationOffset
+						}
+					}
+				}
+			}
+			rawProgressCallback(eventType, message, data)
+		}
+		taskCtxLoop := mcp.WithMCPConversationID(taskCtx, conversationID)
+		taskCtxLoop = mcp.WithToolRunRegistry(taskCtxLoop, h.tasks)
+		taskCtxLoop = mcp.WithEinoExecuteRunRegistry(taskCtxLoop, h.tasks)
+		taskCtxLoop = multiagent.WithAgentRuntimeCancelRegistrar(taskCtxLoop, func(cancel func(error) bool) func() {
+			return h.tasks.BindAgentRuntimeCancel(conversationID, cancel)
+		})
+		taskCtxLoop = multiagent.WithAgentTurnLoopInterruptRegistrar(taskCtxLoop, func(push func(string) bool) func() {
+			return h.tasks.BindAgentTurnLoopInterrupt(conversationID, push)
+		})
+		taskCtxLoop = multiagent.WithHITLToolInterceptor(taskCtxLoop, func(ctx context.Context, toolName, arguments string) (string, error) {
+			return h.interceptHITLForEinoTool(ctx, cancelWithCause, conversationID, assistantMessageID, sendEvent, toolName, arguments)
+		})
+
+		result, runErr = multiagent.RunEinoSingleChatModelAgent(
+			taskCtxLoop,
+			runCfg,
+			&runCfg.MultiAgent,
+			h.agent,
+			h.db,
+			h.logger,
+			conversationID,
+			h.conversationProjectID(conversationID),
+			curFinalMessage,
+			curHistory,
+			roleTools,
+			progressCallback,
+			chatReasoningToClientIntent(req.Reasoning),
+			h.agentSessionContextBlock(conversationID),
+		)
+		_ = resolvedAIChannelID
+
+		if result != nil && len(result.MCPExecutionIDs) > 0 {
+			cumulativeMCPExecutionIDs = mergeMCPExecutionIDLists(cumulativeMCPExecutionIDs, result.MCPExecutionIDs)
+		}
+
+		if runErr == nil {
+			mw := &h.config.MultiAgent.EinoMiddleware
+			if h.tryContinueOnEinoEmptyResponse(taskCtx, mw, conversationID, result, &emptyResponseContinueAttempt, &curHistory, &curFinalMessage, progressCallback) {
+				mainIterationOffset += segmentMainIterationMax
+				timeoutCancel()
+				baseCtx, cancelWithCause, taskCtx, timeoutCancel = h.rebindEinoRunningTask(taskCtx, conversationID, timeoutCancel)
+				continue
+			}
+			decision = h.decideAgentRunForDeliveryWithPolicy(conversationID, assistantMessageID, "eino_single", result, cumulativeMCPExecutionIDs, requestRequiresExecutionEvidence(&req))
+			if h.tryAutoContinueAfterFinalization(taskCtx, conversationID, result, decision, &finalizationAutoContinueAttempt, &curHistory, &curFinalMessage, progressCallback) {
+				mainIterationOffset += segmentMainIterationMax
+				timeoutCancel()
+				baseCtx, cancelWithCause, taskCtx, timeoutCancel = h.rebindEinoRunningTask(taskCtx, conversationID, timeoutCancel)
+				continue
+			}
+			timeoutCancel()
+			break
+		}
+
+		cause := context.Cause(baseCtx)
+		if cause == nil {
+			switch {
+			case errors.Is(runErr, multiagent.ErrInterruptContinue):
+				cause = multiagent.ErrInterruptContinue
+			case errors.Is(runErr, ErrTaskCancelled):
+				cause = ErrTaskCancelled
+			}
+		}
+		if errors.Is(cause, multiagent.ErrInterruptContinue) {
+			if shouldPersistEinoAgentTraceAfterRunError(baseCtx) {
+				h.persistEinoAgentTraceForResume(conversationID, result)
+			}
+			note := h.tasks.TakeInterruptContinueNote(conversationID)
+			icSummary := interruptContinueTimelineSummary(note)
+			progressCallback("user_interrupt_continue", icSummary, map[string]interface{}{
+				"conversationId": conversationID,
+				"rawReason":      strings.TrimSpace(note),
+				"emptyReason":    strings.TrimSpace(note) == "",
+				"kind":           "no_active_mcp_tool",
+			})
+			inject := formatInterruptContinueUserMessage(note)
+			// 不写入 messages 表为 user 气泡：避免主对话流出现大段模板；说明已由 user_interrupt_continue 记入助手 process_details（迭代详情）。
+			if hist, err := h.loadHistoryFromAgentTrace(conversationID); err == nil && len(hist) > 0 {
+				curHistory = hist
+			}
+			curFinalMessage = inject
+			sendEvent("progress", "已合并用户补充与最新轨迹，正在继续推理…", map[string]interface{}{
+				"conversationId": conversationID,
+				"source":         "interrupt_continue",
+			})
+			mainIterationOffset += segmentMainIterationMax
+			timeoutCancel()
+			baseCtx, cancelWithCause = context.WithCancelCause(detachedAgentContext(baseCtx))
+			h.tasks.BindTaskCancel(conversationID, cancelWithCause)
+			taskCtx, timeoutCancel = context.WithTimeout(baseCtx, 600*time.Minute)
+			h.tasks.UpdateTaskStatus(conversationID, "running")
+			continue
+		}
+
+		if shouldPersistEinoAgentTraceAfterRunError(baseCtx) {
+			h.persistEinoAgentTraceForResume(conversationID, result)
+		}
+		if errors.Is(cause, ErrTaskCancelled) {
+			taskStatus = "cancelled"
+			h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+			cancelMsg := "任务已被用户取消，后续操作已停止。"
+			if assistantMessageID != "" {
+				if result != nil {
+					if err := h.mergeAssistantMessagePartialOnCancel(assistantMessageID, result.Response); err != nil {
+						h.logger.Warn("合并取消前的部分回复失败", zap.Error(err))
+					}
+				}
+				if err := h.appendAssistantMessageNotice(assistantMessageID, cancelMsg); err != nil {
+					h.logger.Warn("更新取消后的助手消息失败", zap.Error(err))
+				}
+				_ = h.db.AddProcessDetail(assistantMessageID, conversationID, "cancelled", cancelMsg, nil)
+			}
+			sendEvent("cancelled", cancelMsg, map[string]interface{}{
+				"conversationId": conversationID,
+				"messageId":      assistantMessageID,
+			})
+			sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+			timeoutCancel()
+			return
+		}
+
+		if errors.Is(runErr, context.DeadlineExceeded) || errors.Is(context.Cause(taskCtx), context.DeadlineExceeded) {
+			taskStatus = "timeout"
+			h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+			timeoutMsg := "任务执行超时，已自动终止。"
+			if assistantMessageID != "" {
+				_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", timeoutMsg, time.Now(), assistantMessageID)
+				_ = h.db.AddProcessDetail(assistantMessageID, conversationID, "timeout", timeoutMsg, nil)
+			}
+			sendEvent("error", timeoutMsg, map[string]interface{}{
+				"conversationId": conversationID,
+				"messageId":      assistantMessageID,
+				"errorType":      "timeout",
+			})
+			sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+			timeoutCancel()
+			return
+		}
+
+		h.logger.Error("Eino ADK 单代理执行失败", zap.Error(runErr))
+		taskStatus = "failed"
+		h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+		errMsg := "执行失败: " + runErr.Error()
+		if assistantMessageID != "" {
+			_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", errMsg, time.Now(), assistantMessageID)
+			_ = h.db.AddProcessDetail(assistantMessageID, conversationID, "error", errMsg, nil)
+		}
+		sendEvent("error", errMsg, map[string]interface{}{
+			"conversationId": conversationID,
+			"messageId":      assistantMessageID,
+		})
+		sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+		timeoutCancel()
+		return
+	}
+
+	timeoutCancel()
+
+	if decision.CompletionReason == "" {
+		decision = h.decideAgentRunForDeliveryWithPolicy(conversationID, assistantMessageID, "eino_single", result, cumulativeMCPExecutionIDs, requestRequiresExecutionEvidence(&req))
+	}
+	h.persistFinalizationDecision(conversationID, assistantMessageID, "eino_single", cumulativeMCPExecutionIDs, multiagent.AggregatedReasoningFromTraceJSON(result.LastAgentTraceInput), decision)
+
+	if result.LastAgentTraceInput != "" || result.LastAgentTraceOutput != "" {
+		if err := h.db.SaveAgentTrace(conversationID, result.LastAgentTraceInput, result.LastAgentTraceOutput); err != nil {
+			h.logger.Warn("保存代理轨迹失败", zap.Error(err))
+		}
+	}
+
+	responseText := decision.FinalText
+	if !decision.Finalizable {
+		responseText = finalizationBlockedMessage(decision)
+		sendEvent("finalization_check", responseText, decision)
+		taskStatus = decision.Status
+		h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+	}
+	sendEvent("response", responseText, finalizationResponsePayload(decision, map[string]interface{}{
+		"mcpExecutionIds": cumulativeMCPExecutionIDs,
+		"conversationId":  conversationID,
+		"messageId":       assistantMessageID,
+		"agentMode":       "eino_single",
+	}))
+	sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+}
+
+// EinoSingleAgentLoop Eino ADK 单代理非流式对话。
+func (h *AgentHandler) EinoSingleAgentLoop(c *gin.Context) {
+	var req ChatRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	h.logger.Info("收到 Eino ADK 单代理非流式请求", zap.String("conversationId", req.ConversationID))
+
+	prep, err := h.prepareMultiAgentSession(&req, c, "eino_agent")
+	if err != nil {
+		status, msg := multiAgentHTTPErrorStatus(err)
+		c.JSON(status, gin.H{"error": msg})
+		return
+	}
+	h.activateHITLForConversation(prep.ConversationID, req.Hitl)
+	if h.hitlManager != nil {
+		defer h.hitlManager.DeactivateConversation(prep.ConversationID)
+	}
+	if h.runRoleWorkflowJSONIfBound(c, &req, prep) {
+		return
+	}
+
+	var progressBuf strings.Builder
+	progressCallbackRaw := func(eventType, message string, data interface{}) {
+		progressBuf.WriteString(eventType)
+		progressBuf.WriteByte('\n')
+	}
+	baseCtx, cancelWithCause := context.WithCancelCause(c.Request.Context())
+	defer cancelWithCause(nil)
+	taskCtx, timeoutCancel := context.WithTimeout(baseCtx, 600*time.Minute)
+	defer timeoutCancel()
+	progressCallback := h.createProgressCallback(taskCtx, cancelWithCause, prep.ConversationID, prep.AssistantMessageID, progressCallbackRaw)
+	taskCtx = multiagent.WithHITLToolInterceptor(taskCtx, func(ctx context.Context, toolName, arguments string) (string, error) {
+		return h.interceptHITLForEinoTool(ctx, cancelWithCause, prep.ConversationID, prep.AssistantMessageID, nil, toolName, arguments)
+	})
+
+	if h.config == nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "服务器配置未加载"})
+		return
+	}
+	runCfg, _, err := h.configForAIChannel(req.AIChannelID)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	curHist := prep.History
+	curMsg := prep.FinalMessage
+	var result *multiagent.RunResult
+	var runErr error
+	var emptyResponseContinueAttempt int
+	var finalizationAutoContinueAttempt int
+	var decision agentfinalizer.Decision
+	for {
+		result, runErr = multiagent.RunEinoSingleChatModelAgent(
+			taskCtx,
+			runCfg,
+			&runCfg.MultiAgent,
+			h.agent,
+			h.db,
+			h.logger,
+			prep.ConversationID,
+			h.conversationProjectID(prep.ConversationID),
+			curMsg,
+			curHist,
+			prep.RoleTools,
+			progressCallback,
+			chatReasoningToClientIntent(req.Reasoning),
+			h.agentSessionContextBlock(prep.ConversationID),
+		)
+		if runErr != nil {
+			if shouldPersistEinoAgentTraceAfterRunError(baseCtx) {
+				h.persistEinoAgentTraceForResume(prep.ConversationID, result)
+			}
+			c.JSON(http.StatusInternalServerError, gin.H{"error": runErr.Error()})
+			return
+		}
+		mw := &h.config.MultiAgent.EinoMiddleware
+		if h.tryContinueOnEinoEmptyResponse(taskCtx, mw, prep.ConversationID, result, &emptyResponseContinueAttempt, &curHist, &curMsg, progressCallback) {
+			continue
+		}
+		decision = h.decideAgentRunForDeliveryWithPolicy(prep.ConversationID, prep.AssistantMessageID, "eino_single", result, result.MCPExecutionIDs, requestRequiresExecutionEvidence(&req))
+		if h.tryAutoContinueAfterFinalization(taskCtx, prep.ConversationID, result, decision, &finalizationAutoContinueAttempt, &curHist, &curMsg, progressCallback) {
+			continue
+		}
+		break
+	}
+
+	h.persistFinalizationDecision(prep.ConversationID, prep.AssistantMessageID, "eino_single", result.MCPExecutionIDs, multiagent.AggregatedReasoningFromTraceJSON(result.LastAgentTraceInput), decision)
+	if result.LastAgentTraceInput != "" || result.LastAgentTraceOutput != "" {
+		_ = h.db.SaveAgentTrace(prep.ConversationID, result.LastAgentTraceInput, result.LastAgentTraceOutput)
+	}
+
+	responseText := decision.FinalText
+	if !decision.Finalizable {
+		responseText = finalizationBlockedMessage(decision)
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"response":            responseText,
+		"conversationId":      prep.ConversationID,
+		"mcpExecutionIds":     result.MCPExecutionIDs,
+		"assistantMessageId":  prep.AssistantMessageID,
+		"agentMode":           "eino_single",
+		"finalized":           decision.Finalized,
+		"finalizable":         decision.Finalizable,
+		"status":              decision.Status,
+		"completionReason":    decision.CompletionReason,
+		"evidenceVerified":    decision.EvidenceVerified,
+		"evidenceRefs":        decision.EvidenceRefs,
+		"pendingExecutionIds": decision.PendingExecutionIDs,
+		"missingChecks":       decision.MissingChecks,
+	})
+}

internal/handler/external_mcp.go

@@ -0,0 +1,506 @@
+package handler
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"sync"
+
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/mcp"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+	"gopkg.in/yaml.v3"
+)
+
+// ExternalMCPHandler 外部MCP处理器
+type ExternalMCPHandler struct {
+	manager    *mcp.ExternalMCPManager
+	config     *config.Config
+	configPath string
+	logger     *zap.Logger
+	audit      *audit.Service
+	mu         sync.RWMutex
+}
+
+// SetAudit wires platform audit logging.
+func (h *ExternalMCPHandler) SetAudit(s *audit.Service) {
+	h.audit = s
+}
+
+// NewExternalMCPHandler 创建外部MCP处理器
+func NewExternalMCPHandler(manager *mcp.ExternalMCPManager, cfg *config.Config, configPath string, logger *zap.Logger) *ExternalMCPHandler {
+	return &ExternalMCPHandler{
+		manager:    manager,
+		config:     cfg,
+		configPath: configPath,
+		logger:     logger,
+	}
+}
+
+// GetExternalMCPs 获取所有外部MCP配置
+func (h *ExternalMCPHandler) GetExternalMCPs(c *gin.Context) {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+
+	configs := h.manager.GetConfigs()
+
+	// 获取所有外部MCP的工具数量
+	toolCounts := h.manager.GetToolCounts()
+
+	// 转换为响应格式
+	result := make(map[string]ExternalMCPResponse)
+	for name, cfg := range configs {
+		client, exists := h.manager.GetClient(name)
+		status := "disconnected"
+		if exists {
+			status = client.GetStatus()
+		} else if h.isEnabled(cfg) {
+			status = "disconnected"
+		} else {
+			status = "disabled"
+		}
+
+		toolCount := toolCounts[name]
+		errorMsg := externalMCPStatusError(h.manager, name, status)
+
+		result[name] = ExternalMCPResponse{
+			Config:    externalMCPConfigForResponse(c, cfg),
+			Status:    status,
+			ToolCount: toolCount,
+			Error:     errorMsg,
+		}
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"servers": result,
+		"stats":   h.manager.GetStats(),
+	})
+}
+
+// GetExternalMCP 获取单个外部MCP配置
+func (h *ExternalMCPHandler) GetExternalMCP(c *gin.Context) {
+	name := c.Param("name")
+
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+
+	configs := h.manager.GetConfigs()
+	cfg, exists := configs[name]
+	if !exists {
+		c.JSON(http.StatusNotFound, gin.H{"error": "外部MCP配置不存在"})
+		return
+	}
+
+	client, clientExists := h.manager.GetClient(name)
+	status := "disconnected"
+	if clientExists {
+		status = client.GetStatus()
+	} else if h.isEnabled(cfg) {
+		status = "disconnected"
+	} else {
+		status = "disabled"
+	}
+
+	// 获取工具数量
+	toolCount := 0
+	if clientExists && client.IsConnected() {
+		if count, err := h.manager.GetToolCount(name); err == nil {
+			toolCount = count
+		}
+	}
+
+	c.JSON(http.StatusOK, ExternalMCPResponse{
+		Config:    externalMCPConfigForResponse(c, cfg),
+		Status:    status,
+		ToolCount: toolCount,
+		Error:     externalMCPStatusError(h.manager, name, status),
+	})
+}
+
+func externalMCPConfigForResponse(c *gin.Context, cfg config.ExternalMCPServerConfig) config.ExternalMCPServerConfig {
+	if security.SessionHasPermission(c, "mcp:write") {
+		return cfg
+	}
+	copyCfg := cfg
+	if len(cfg.Env) > 0 {
+		copyCfg.Env = make(map[string]string, len(cfg.Env))
+		for key := range cfg.Env {
+			copyCfg.Env[key] = "***"
+		}
+	}
+	if len(cfg.Headers) > 0 {
+		copyCfg.Headers = make(map[string]string, len(cfg.Headers))
+		for key := range cfg.Headers {
+			copyCfg.Headers[key] = "***"
+		}
+	}
+	return copyCfg
+}
+
+// externalMCPStatusError 在 error/disconnected 状态下返回最近错误（含断连原因）。
+func externalMCPStatusError(manager *mcp.ExternalMCPManager, name, status string) string {
+	if status != "error" && status != "disconnected" {
+		return ""
+	}
+	return manager.GetError(name)
+}
+
+// AddOrUpdateExternalMCP 添加或更新外部MCP配置
+func (h *ExternalMCPHandler) AddOrUpdateExternalMCP(c *gin.Context) {
+	var req AddOrUpdateExternalMCPRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的请求参数: " + err.Error()})
+		return
+	}
+
+	name := c.Param("name")
+	if name == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "名称不能为空"})
+		return
+	}
+
+	// 验证配置
+	if err := h.validateConfig(req.Config); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	// 添加或更新配置
+	if err := h.manager.AddOrUpdateConfig(name, req.Config); err != nil {
+		h.logger.Error("添加或更新外部MCP配置失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "添加或更新配置失败: " + err.Error()})
+		return
+	}
+
+	// 更新内存中的配置
+	if h.config.ExternalMCP.Servers == nil {
+		h.config.ExternalMCP.Servers = make(map[string]config.ExternalMCPServerConfig)
+	}
+
+	cfg := req.Config
+
+	// 官方 disabled 字段 → ExternalMCPEnable 取反
+	if cfg.Disabled {
+		cfg.ExternalMCPEnable = false
+	} else if !cfg.ExternalMCPEnable {
+		// 用户未显式设置 external_mcp_enable，官方配置默认就是启用的
+		cfg.ExternalMCPEnable = true
+	}
+
+	// 展开 ${VAR} 环境变量
+	config.ExpandConfigEnv(&cfg)
+
+	h.config.ExternalMCP.Servers[name] = cfg
+
+	// 保存到配置文件
+	if err := h.saveConfig(); err != nil {
+		h.logger.Error("保存配置失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "保存配置失败: " + err.Error()})
+		return
+	}
+
+	h.logger.Info("外部MCP配置已更新", zap.String("name", name))
+	if h.audit != nil {
+		h.audit.Record(c, audit.Entry{
+			Category:     "external_mcp",
+			Action:       "upsert",
+			Result:       "success",
+			ResourceType: "external_mcp",
+			ResourceID:   name,
+			Message:      "更新外部 MCP 配置",
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "配置已更新"})
+}
+
+// DeleteExternalMCP 删除外部MCP配置
+func (h *ExternalMCPHandler) DeleteExternalMCP(c *gin.Context) {
+	name := c.Param("name")
+
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	// 移除配置
+	if err := h.manager.RemoveConfig(name); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "配置不存在"})
+		return
+	}
+
+	// 从内存配置中删除
+	if h.config.ExternalMCP.Servers != nil {
+		delete(h.config.ExternalMCP.Servers, name)
+	}
+
+	// 保存到配置文件
+	if err := h.saveConfig(); err != nil {
+		h.logger.Error("保存配置失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "保存配置失败: " + err.Error()})
+		return
+	}
+
+	h.logger.Info("外部MCP配置已删除", zap.String("name", name))
+	if h.audit != nil {
+		h.audit.Record(c, audit.Entry{
+			Category:     "external_mcp",
+			Action:       "delete",
+			Result:       "success",
+			ResourceType: "external_mcp",
+			ResourceID:   name,
+			Message:      "删除外部 MCP 配置",
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "配置已删除"})
+}
+
+// StartExternalMCP 启动外部MCP
+func (h *ExternalMCPHandler) StartExternalMCP(c *gin.Context) {
+	name := c.Param("name")
+
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	// 更新配置为启用
+	if h.config.ExternalMCP.Servers == nil {
+		h.config.ExternalMCP.Servers = make(map[string]config.ExternalMCPServerConfig)
+	}
+	cfg := h.config.ExternalMCP.Servers[name]
+	cfg.ExternalMCPEnable = true
+	h.config.ExternalMCP.Servers[name] = cfg
+
+	// 保存到配置文件
+	if err := h.saveConfig(); err != nil {
+		h.logger.Error("保存配置失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "保存配置失败: " + err.Error()})
+		return
+	}
+
+	// 启动客户端（立即创建客户端并设置状态为connecting，实际连接在后台进行）
+	h.logger.Info("开始启动外部MCP", zap.String("name", name))
+	if err := h.manager.StartClient(name); err != nil {
+		h.logger.Error("启动外部MCP失败", zap.String("name", name), zap.Error(err))
+		c.JSON(http.StatusBadRequest, gin.H{
+			"error":  err.Error(),
+			"status": "error",
+		})
+		return
+	}
+
+	// 获取客户端状态（应该是connecting）
+	client, exists := h.manager.GetClient(name)
+	status := "connecting"
+	if exists {
+		status = client.GetStatus()
+	}
+
+	// 立即返回，不等待连接完成
+	// 客户端会在后台异步连接，用户可以通过状态查询接口查看连接状态
+	c.JSON(http.StatusOK, gin.H{
+		"message": "外部MCP启动请求已提交，正在后台连接中",
+		"status":  status,
+	})
+}
+
+// StopExternalMCP 停止外部MCP
+func (h *ExternalMCPHandler) StopExternalMCP(c *gin.Context) {
+	name := c.Param("name")
+
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	// 停止客户端
+	if err := h.manager.StopClient(name); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	// 更新配置
+	if h.config.ExternalMCP.Servers == nil {
+		h.config.ExternalMCP.Servers = make(map[string]config.ExternalMCPServerConfig)
+	}
+	cfg := h.config.ExternalMCP.Servers[name]
+	cfg.ExternalMCPEnable = false
+	h.config.ExternalMCP.Servers[name] = cfg
+
+	// 保存到配置文件
+	if err := h.saveConfig(); err != nil {
+		h.logger.Error("保存配置失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "保存配置失败: " + err.Error()})
+		return
+	}
+
+	h.logger.Info("外部MCP已停止", zap.String("name", name))
+	c.JSON(http.StatusOK, gin.H{"message": "外部MCP已停止"})
+}
+
+// GetExternalMCPStats 获取统计信息
+func (h *ExternalMCPHandler) GetExternalMCPStats(c *gin.Context) {
+	stats := h.manager.GetStats()
+	c.JSON(http.StatusOK, stats)
+}
+
+// validateConfig 验证配置（同时支持官方 type 字段和旧版 transport 字段）
+func (h *ExternalMCPHandler) validateConfig(cfg config.ExternalMCPServerConfig) error {
+	transport := cfg.GetTransportType()
+	if transport == "" {
+		return fmt.Errorf("需要指定 command（stdio模式）或 url + type（http/sse模式）")
+	}
+
+	switch transport {
+	case "http":
+		if cfg.URL == "" {
+			return fmt.Errorf("HTTP模式需要 url")
+		}
+	case "stdio":
+		if cfg.Command == "" {
+			return fmt.Errorf("stdio模式需要 command")
+		}
+	case "sse":
+		if cfg.URL == "" {
+			return fmt.Errorf("SSE模式需要 url")
+		}
+	default:
+		return fmt.Errorf("不支持的传输模式: %s，支持的模式: http, stdio, sse", transport)
+	}
+
+	return nil
+}
+
+// isEnabled 检查是否启用
+func (h *ExternalMCPHandler) isEnabled(cfg config.ExternalMCPServerConfig) bool {
+	return cfg.ExternalMCPEnable
+}
+
+// saveConfig 保存配置到文件
+func (h *ExternalMCPHandler) saveConfig() error {
+	data, err := os.ReadFile(h.configPath)
+	if err != nil {
+		return fmt.Errorf("读取配置文件失败: %w", err)
+	}
+
+	if err := os.WriteFile(h.configPath+".backup", data, 0644); err != nil {
+		h.logger.Warn("创建配置备份失败", zap.Error(err))
+	}
+
+	root, err := loadYAMLDocument(h.configPath)
+	if err != nil {
+		return fmt.Errorf("解析配置文件失败: %w", err)
+	}
+
+	updateExternalMCPConfig(root, h.config.ExternalMCP)
+
+	if err := writeYAMLDocument(h.configPath, root); err != nil {
+		return fmt.Errorf("保存配置文件失败: %w", err)
+	}
+
+	h.logger.Info("配置已保存", zap.String("path", h.configPath))
+	return nil
+}
+
+// updateExternalMCPConfig 更新外部MCP配置
+func updateExternalMCPConfig(doc *yaml.Node, cfg config.ExternalMCPConfig) {
+	root := doc.Content[0]
+	externalMCPNode := ensureMap(root, "external_mcp")
+	serversNode := ensureMap(externalMCPNode, "servers")
+
+	// 清空现有服务器配置
+	serversNode.Content = nil
+
+	// 添加新的服务器配置
+	for name, serverCfg := range cfg.Servers {
+		nameNode := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: name}
+		serverNode := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}
+		serversNode.Content = append(serversNode.Content, nameNode, serverNode)
+
+		// type（官方 MCP 传输类型）
+		effectiveType := serverCfg.GetTransportType()
+		if effectiveType != "" && effectiveType != "stdio" {
+			// stdio 可省略（有 command 时自动推断）
+			setStringInMap(serverNode, "type", effectiveType)
+		}
+		if serverCfg.Command != "" {
+			setStringInMap(serverNode, "command", serverCfg.Command)
+		}
+		if len(serverCfg.Args) > 0 {
+			setStringArrayInMap(serverNode, "args", serverCfg.Args)
+		}
+		if serverCfg.Env != nil && len(serverCfg.Env) > 0 {
+			envNode := ensureMap(serverNode, "env")
+			for envKey, envValue := range serverCfg.Env {
+				setStringInMap(envNode, envKey, envValue)
+			}
+		}
+		if serverCfg.URL != "" {
+			setStringInMap(serverNode, "url", serverCfg.URL)
+		}
+		if serverCfg.Headers != nil && len(serverCfg.Headers) > 0 {
+			headersNode := ensureMap(serverNode, "headers")
+			for k, v := range serverCfg.Headers {
+				setStringInMap(headersNode, k, v)
+			}
+		}
+		if serverCfg.Description != "" {
+			setStringInMap(serverNode, "description", serverCfg.Description)
+		}
+		if serverCfg.Timeout > 0 {
+			setIntInMap(serverNode, "timeout", serverCfg.Timeout)
+		}
+		// 官方标准字段
+		if serverCfg.Disabled {
+			setBoolInMap(serverNode, "disabled", true)
+		}
+		if len(serverCfg.AutoApprove) > 0 {
+			setStringArrayInMap(serverNode, "autoApprove", serverCfg.AutoApprove)
+		}
+
+		// SDK 高级配置
+		if serverCfg.MaxRetries > 0 {
+			setIntInMap(serverNode, "max_retries", serverCfg.MaxRetries)
+		}
+		if serverCfg.TerminateDuration > 0 {
+			setIntInMap(serverNode, "terminate_duration", serverCfg.TerminateDuration)
+		}
+		if serverCfg.KeepAlive > 0 {
+			setIntInMap(serverNode, "keep_alive", serverCfg.KeepAlive)
+		}
+
+		setBoolInMap(serverNode, "external_mcp_enable", serverCfg.ExternalMCPEnable)
+		if serverCfg.ToolEnabled != nil && len(serverCfg.ToolEnabled) > 0 {
+			toolEnabledNode := ensureMap(serverNode, "tool_enabled")
+			for toolName, enabled := range serverCfg.ToolEnabled {
+				setBoolInMap(toolEnabledNode, toolName, enabled)
+			}
+		}
+	}
+}
+
+// setStringArrayInMap 设置字符串数组
+func setStringArrayInMap(mapNode *yaml.Node, key string, values []string) {
+	_, valueNode := ensureKeyValue(mapNode, key)
+	valueNode.Kind = yaml.SequenceNode
+	valueNode.Tag = "!!seq"
+	valueNode.Content = nil
+	for _, v := range values {
+		itemNode := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: v}
+		valueNode.Content = append(valueNode.Content, itemNode)
+	}
+}
+
+// AddOrUpdateExternalMCPRequest 添加或更新外部MCP请求
+type AddOrUpdateExternalMCPRequest struct {
+	Config config.ExternalMCPServerConfig `json:"config"`
+}
+
+// ExternalMCPResponse 外部MCP响应
+type ExternalMCPResponse struct {
+	Config    config.ExternalMCPServerConfig `json:"config"`
+	Status    string                         `json:"status"`          // "connected", "disconnected", "disabled", "error", "connecting"
+	ToolCount int                            `json:"tool_count"`      // 工具数量
+	Error     string                         `json:"error,omitempty"` // 错误信息（仅在status为error时存在）
+}

internal/handler/external_mcp_test.go

@@ -0,0 +1,518 @@
+package handler
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/mcp"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func setupTestRouter() (*gin.Engine, *ExternalMCPHandler, string) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+
+	// 创建临时配置文件
+	tmpFile, err := os.CreateTemp("", "test-config-*.yaml")
+	if err != nil {
+		panic(err)
+	}
+	tmpFile.WriteString("server:\n  host: 0.0.0.0\n  port: 8080\n")
+	tmpFile.Close()
+	configPath := tmpFile.Name()
+
+	logger := zap.NewNop()
+	manager := mcp.NewExternalMCPManager(logger)
+	cfg := &config.Config{
+		ExternalMCP: config.ExternalMCPConfig{
+			Servers: make(map[string]config.ExternalMCPServerConfig),
+		},
+	}
+
+	handler := NewExternalMCPHandler(manager, cfg, configPath, logger)
+
+	api := router.Group("/api")
+	api.GET("/external-mcp", handler.GetExternalMCPs)
+	api.GET("/external-mcp/stats", handler.GetExternalMCPStats)
+	api.GET("/external-mcp/:name", handler.GetExternalMCP)
+	api.PUT("/external-mcp/:name", handler.AddOrUpdateExternalMCP)
+	api.DELETE("/external-mcp/:name", handler.DeleteExternalMCP)
+	api.POST("/external-mcp/:name/start", handler.StartExternalMCP)
+	api.POST("/external-mcp/:name/stop", handler.StopExternalMCP)
+
+	return router, handler, configPath
+}
+
+func cleanupTestConfig(configPath string) {
+	os.Remove(configPath)
+	os.Remove(configPath + ".backup")
+}
+
+func TestExternalMCPHandler_AddOrUpdateExternalMCP_Stdio(t *testing.T) {
+	router, _, configPath := setupTestRouter()
+	defer cleanupTestConfig(configPath)
+
+	// 测试添加stdio模式的配置（官方格式：有 command 时 type 可省略）
+	configJSON := `{
+		"command": "python3",
+		"args": ["/path/to/script.py", "--server", "http://example.com"],
+		"description": "Test stdio MCP",
+		"timeout": 300,
+		"external_mcp_enable": true
+	}`
+
+	var configObj config.ExternalMCPServerConfig
+	if err := json.Unmarshal([]byte(configJSON), &configObj); err != nil {
+		t.Fatalf("解析配置JSON失败: %v", err)
+	}
+
+	reqBody := AddOrUpdateExternalMCPRequest{
+		Config: configObj,
+	}
+
+	body, _ := json.Marshal(reqBody)
+	req := httptest.NewRequest("PUT", "/api/external-mcp/test-stdio", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("期望状态码200，实际%d: %s", w.Code, w.Body.String())
+	}
+
+	// 验证配置已添加
+	req2 := httptest.NewRequest("GET", "/api/external-mcp/test-stdio", nil)
+	w2 := httptest.NewRecorder()
+	router.ServeHTTP(w2, req2)
+
+	if w2.Code != http.StatusOK {
+		t.Fatalf("期望状态码200，实际%d: %s", w2.Code, w2.Body.String())
+	}
+
+	var response ExternalMCPResponse
+	if err := json.Unmarshal(w2.Body.Bytes(), &response); err != nil {
+		t.Fatalf("解析响应失败: %v", err)
+	}
+
+	if response.Config.Command != "python3" {
+		t.Errorf("期望command为python3，实际%s", response.Config.Command)
+	}
+	if len(response.Config.Args) != 3 {
+		t.Errorf("期望args长度为3，实际%d", len(response.Config.Args))
+	}
+	if response.Config.Description != "Test stdio MCP" {
+		t.Errorf("期望description为'Test stdio MCP'，实际%s", response.Config.Description)
+	}
+	if response.Config.Timeout != 300 {
+		t.Errorf("期望timeout为300，实际%d", response.Config.Timeout)
+	}
+}
+
+func TestExternalMCPHandler_AddOrUpdateExternalMCP_HTTP(t *testing.T) {
+	router, _, configPath := setupTestRouter()
+	defer cleanupTestConfig(configPath)
+
+	// 测试添加HTTP模式的配置（使用官方 type 字段）
+	configJSON := `{
+		"type": "http",
+		"url": "http://127.0.0.1:8081/mcp",
+		"external_mcp_enable": true
+	}`
+
+	var configObj config.ExternalMCPServerConfig
+	if err := json.Unmarshal([]byte(configJSON), &configObj); err != nil {
+		t.Fatalf("解析配置JSON失败: %v", err)
+	}
+
+	reqBody := AddOrUpdateExternalMCPRequest{
+		Config: configObj,
+	}
+
+	body, _ := json.Marshal(reqBody)
+	req := httptest.NewRequest("PUT", "/api/external-mcp/test-http", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("期望状态码200，实际%d: %s", w.Code, w.Body.String())
+	}
+
+	// 验证配置已添加
+	req2 := httptest.NewRequest("GET", "/api/external-mcp/test-http", nil)
+	w2 := httptest.NewRecorder()
+	router.ServeHTTP(w2, req2)
+
+	if w2.Code != http.StatusOK {
+		t.Fatalf("期望状态码200，实际%d: %s", w2.Code, w2.Body.String())
+	}
+
+	var response ExternalMCPResponse
+	if err := json.Unmarshal(w2.Body.Bytes(), &response); err != nil {
+		t.Fatalf("解析响应失败: %v", err)
+	}
+
+	if response.Config.Type != "http" {
+		t.Errorf("期望type为http，实际%s", response.Config.Type)
+	}
+	if response.Config.URL != "http://127.0.0.1:8081/mcp" {
+		t.Errorf("期望url为'http://127.0.0.1:8081/mcp'，实际%s", response.Config.URL)
+	}
+}
+
+func TestExternalMCPHandler_AddOrUpdateExternalMCP_InvalidConfig(t *testing.T) {
+	router, _, configPath := setupTestRouter()
+	defer cleanupTestConfig(configPath)
+
+	testCases := []struct {
+		name        string
+		configJSON  string
+		expectedErr string
+	}{
+		{
+			name:        "缺少command和url",
+			configJSON:  `{"external_mcp_enable": true}`,
+			expectedErr: "需要指定 command（stdio模式）或 url + type（http/sse模式）",
+		},
+		{
+			name:        "stdio模式缺少command",
+			configJSON:  `{"args": ["test"], "external_mcp_enable": true}`,
+			expectedErr: "stdio模式需要command",
+		},
+		{
+			name:        "http模式缺少url",
+			configJSON:  `{"type": "http", "external_mcp_enable": true}`,
+			expectedErr: "HTTP模式需要 url",
+		},
+		{
+			name:        "无效的type",
+			configJSON:  `{"type": "invalid", "external_mcp_enable": true}`,
+			expectedErr: "不支持的传输模式",
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			var configObj config.ExternalMCPServerConfig
+			if err := json.Unmarshal([]byte(tc.configJSON), &configObj); err != nil {
+				t.Fatalf("解析配置JSON失败: %v", err)
+			}
+
+			reqBody := AddOrUpdateExternalMCPRequest{
+				Config: configObj,
+			}
+
+			body, _ := json.Marshal(reqBody)
+			req := httptest.NewRequest("PUT", "/api/external-mcp/test-invalid", bytes.NewBuffer(body))
+			req.Header.Set("Content-Type", "application/json")
+			w := httptest.NewRecorder()
+
+			router.ServeHTTP(w, req)
+
+			if w.Code != http.StatusBadRequest {
+				t.Errorf("期望状态码400，实际%d: %s", w.Code, w.Body.String())
+			}
+
+			var response map[string]interface{}
+			if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {
+				t.Fatalf("解析响应失败: %v", err)
+			}
+
+			errorMsg := response["error"].(string)
+			// 对于stdio模式缺少command的情况，错误信息可能略有不同
+			if tc.name == "stdio模式缺少command" {
+				if !strings.Contains(errorMsg, "stdio") && !strings.Contains(errorMsg, "command") {
+					t.Errorf("期望错误信息包含'stdio'或'command'，实际'%s'", errorMsg)
+				}
+			} else if !strings.Contains(errorMsg, tc.expectedErr) {
+				t.Errorf("期望错误信息包含'%s'，实际'%s'", tc.expectedErr, errorMsg)
+			}
+		})
+	}
+}
+
+func TestExternalMCPHandler_DeleteExternalMCP(t *testing.T) {
+	router, handler, configPath := setupTestRouter()
+	defer cleanupTestConfig(configPath)
+
+	// 先添加一个配置
+	configObj := config.ExternalMCPServerConfig{
+		Command:           "python3",
+		ExternalMCPEnable: true,
+	}
+	handler.manager.AddOrUpdateConfig("test-delete", configObj)
+
+	// 删除配置
+	req := httptest.NewRequest("DELETE", "/api/external-mcp/test-delete", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("期望状态码200，实际%d: %s", w.Code, w.Body.String())
+	}
+
+	// 验证配置已删除
+	req2 := httptest.NewRequest("GET", "/api/external-mcp/test-delete", nil)
+	w2 := httptest.NewRecorder()
+	router.ServeHTTP(w2, req2)
+
+	if w2.Code != http.StatusNotFound {
+		t.Errorf("期望状态码404，实际%d: %s", w2.Code, w2.Body.String())
+	}
+}
+
+func TestExternalMCPStatusError(t *testing.T) {
+	manager := mcp.NewExternalMCPManager(zap.NewNop())
+	if got := externalMCPStatusError(manager, "x", "connected"); got != "" {
+		t.Fatalf("connected status should not return error, got %q", got)
+	}
+	if got := externalMCPStatusError(manager, "x", "connecting"); got != "" {
+		t.Fatalf("connecting status should not return error, got %q", got)
+	}
+}
+
+func TestExternalMCPHandler_GetExternalMCPs(t *testing.T) {
+	router, handler, _ := setupTestRouter()
+
+	// 添加多个配置
+	handler.manager.AddOrUpdateConfig("test1", config.ExternalMCPServerConfig{
+		Command:           "python3",
+		ExternalMCPEnable: true,
+	})
+	handler.manager.AddOrUpdateConfig("test2", config.ExternalMCPServerConfig{
+		URL:               "http://127.0.0.1:8081/mcp",
+		ExternalMCPEnable: false,
+	})
+
+	req := httptest.NewRequest("GET", "/api/external-mcp", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("期望状态码200，实际%d: %s", w.Code, w.Body.String())
+	}
+
+	var response map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {
+		t.Fatalf("解析响应失败: %v", err)
+	}
+
+	servers := response["servers"].(map[string]interface{})
+	if len(servers) != 2 {
+		t.Errorf("期望2个服务器，实际%d", len(servers))
+	}
+	if _, ok := servers["test1"]; !ok {
+		t.Error("期望包含test1")
+	}
+	if _, ok := servers["test2"]; !ok {
+		t.Error("期望包含test2")
+	}
+
+	stats := response["stats"].(map[string]interface{})
+	if int(stats["total"].(float64)) != 2 {
+		t.Errorf("期望总数为2，实际%d", int(stats["total"].(float64)))
+	}
+}
+
+func TestExternalMCPHandler_GetExternalMCPStats(t *testing.T) {
+	router, handler, _ := setupTestRouter()
+
+	// 添加配置
+	handler.manager.AddOrUpdateConfig("enabled1", config.ExternalMCPServerConfig{
+		Command:           "python3",
+		ExternalMCPEnable: true,
+	})
+	handler.manager.AddOrUpdateConfig("enabled2", config.ExternalMCPServerConfig{
+		URL:               "http://127.0.0.1:8081/mcp",
+		ExternalMCPEnable: true,
+	})
+	handler.manager.AddOrUpdateConfig("disabled1", config.ExternalMCPServerConfig{
+		Command: "python3",
+	})
+
+	req := httptest.NewRequest("GET", "/api/external-mcp/stats", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("期望状态码200，实际%d: %s", w.Code, w.Body.String())
+	}
+
+	var stats map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &stats); err != nil {
+		t.Fatalf("解析响应失败: %v", err)
+	}
+
+	if int(stats["total"].(float64)) != 3 {
+		t.Errorf("期望总数为3，实际%d", int(stats["total"].(float64)))
+	}
+	if int(stats["enabled"].(float64)) != 2 {
+		t.Errorf("期望启用数为2，实际%d", int(stats["enabled"].(float64)))
+	}
+	if int(stats["disabled"].(float64)) != 1 {
+		t.Errorf("期望停用数为1，实际%d", int(stats["disabled"].(float64)))
+	}
+}
+
+func TestExternalMCPHandler_StartStopExternalMCP(t *testing.T) {
+	router, handler, configPath := setupTestRouter()
+	defer cleanupTestConfig(configPath)
+
+	// 添加一个禁用的配置
+	handler.manager.AddOrUpdateConfig("test-start-stop", config.ExternalMCPServerConfig{
+		Command: "python3",
+	})
+
+	// 测试启动（可能会失败，因为没有真实的服务器）
+	req := httptest.NewRequest("POST", "/api/external-mcp/test-start-stop/start", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	// 启动可能会失败，但应该返回合理的状态码
+	if w.Code != http.StatusOK {
+		// 如果启动失败，应该是400或500
+		if w.Code != http.StatusBadRequest && w.Code != http.StatusInternalServerError {
+			t.Errorf("期望状态码200/400/500，实际%d: %s", w.Code, w.Body.String())
+		}
+	}
+
+	// 测试停止
+	req2 := httptest.NewRequest("POST", "/api/external-mcp/test-start-stop/stop", nil)
+	w2 := httptest.NewRecorder()
+	router.ServeHTTP(w2, req2)
+
+	if w2.Code != http.StatusOK {
+		t.Errorf("期望状态码200，实际%d: %s", w2.Code, w2.Body.String())
+	}
+}
+
+func TestExternalMCPHandler_GetExternalMCP_NotFound(t *testing.T) {
+	router, _, _ := setupTestRouter()
+
+	req := httptest.NewRequest("GET", "/api/external-mcp/nonexistent", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusNotFound {
+		t.Errorf("期望状态码404，实际%d: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestExternalMCPHandler_DeleteExternalMCP_NotFound(t *testing.T) {
+	router, _, configPath := setupTestRouter()
+	defer cleanupTestConfig(configPath)
+
+	req := httptest.NewRequest("DELETE", "/api/external-mcp/nonexistent", nil)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	// 删除不存在的配置可能返回200（幂等操作）或404，都是合理的
+	if w.Code != http.StatusNotFound && w.Code != http.StatusOK {
+		t.Errorf("期望状态码404或200，实际%d: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestExternalMCPHandler_AddOrUpdateExternalMCP_EmptyName(t *testing.T) {
+	router, _, _ := setupTestRouter()
+
+	configObj := config.ExternalMCPServerConfig{
+		Command:           "python3",
+		ExternalMCPEnable: true,
+	}
+
+	reqBody := AddOrUpdateExternalMCPRequest{
+		Config: configObj,
+	}
+
+	body, _ := json.Marshal(reqBody)
+	req := httptest.NewRequest("PUT", "/api/external-mcp/", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	router.ServeHTTP(w, req)
+
+	// 空名称应该返回404或400
+	if w.Code != http.StatusNotFound && w.Code != http.StatusBadRequest {
+		t.Errorf("期望状态码404或400，实际%d: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestExternalMCPHandler_AddOrUpdateExternalMCP_InvalidJSON(t *testing.T) {
+	router, _, _ := setupTestRouter()
+
+	// 发送无效的JSON
+	body := []byte(`{"config": invalid json}`)
+	req := httptest.NewRequest("PUT", "/api/external-mcp/test", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("期望状态码400，实际%d: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestExternalMCPHandler_UpdateExistingConfig(t *testing.T) {
+	router, handler, configPath := setupTestRouter()
+	defer cleanupTestConfig(configPath)
+
+	// 先添加配置
+	config1 := config.ExternalMCPServerConfig{
+		Command:           "python3",
+		ExternalMCPEnable: true,
+	}
+	handler.manager.AddOrUpdateConfig("test-update", config1)
+
+	// 更新配置
+	config2 := config.ExternalMCPServerConfig{
+		URL:               "http://127.0.0.1:8081/mcp",
+		ExternalMCPEnable: true,
+	}
+
+	reqBody := AddOrUpdateExternalMCPRequest{
+		Config: config2,
+	}
+
+	body, _ := json.Marshal(reqBody)
+	req := httptest.NewRequest("PUT", "/api/external-mcp/test-update", bytes.NewBuffer(body))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+
+	router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("期望状态码200，实际%d: %s", w.Code, w.Body.String())
+	}
+
+	// 验证配置已更新
+	req2 := httptest.NewRequest("GET", "/api/external-mcp/test-update", nil)
+	w2 := httptest.NewRecorder()
+	router.ServeHTTP(w2, req2)
+
+	if w2.Code != http.StatusOK {
+		t.Fatalf("期望状态码200，实际%d: %s", w2.Code, w2.Body.String())
+	}
+
+	var response ExternalMCPResponse
+	if err := json.Unmarshal(w2.Body.Bytes(), &response); err != nil {
+		t.Fatalf("解析响应失败: %v", err)
+	}
+
+	if response.Config.URL != "http://127.0.0.1:8081/mcp" {
+		t.Errorf("期望url为'http://127.0.0.1:8081/mcp'，实际%s", response.Config.URL)
+	}
+	if response.Config.Command != "" {
+		t.Errorf("期望command为空，实际%s", response.Config.Command)
+	}
+}

internal/handler/finalization_auto_continue.go

@@ -0,0 +1,77 @@
+package handler
+
+import (
+	"context"
+	"time"
+
+	"cyberstrike-ai/internal/agent"
+	"cyberstrike-ai/internal/agentfinalizer"
+	"cyberstrike-ai/internal/multiagent"
+
+	"go.uber.org/zap"
+)
+
+const finalizationAutoContinueMaxAttempts = 2
+
+func shouldAutoContinueAfterFinalization(d agentfinalizer.Decision, attempt int) bool {
+	if d.Finalizable || d.Finalized {
+		return false
+	}
+	if attempt >= finalizationAutoContinueMaxAttempts {
+		return false
+	}
+	return d.CompletionReason == agentfinalizer.ReasonMissingEvidence
+}
+
+func (h *AgentHandler) tryAutoContinueAfterFinalization(
+	taskCtx context.Context,
+	conversationID string,
+	result *multiagent.RunResult,
+	decision agentfinalizer.Decision,
+	attempt *int,
+	curHistory *[]agent.ChatMessage,
+	curFinalMessage *string,
+	progressCallback func(eventType, message string, data interface{}),
+) bool {
+	if !shouldAutoContinueAfterFinalization(decision, *attempt) || result == nil || !multiagent.HasEinoResumeTrace(result) {
+		return false
+	}
+	*attempt++
+	h.persistEinoAgentTraceForResume(conversationID, result)
+	if hist, err := h.loadHistoryFromAgentTrace(conversationID); err == nil && len(hist) > 0 {
+		*curHistory = hist
+	} else if h.logger != nil {
+		h.logger.Warn("finalization auto-continue could not restore trace",
+			zap.String("conversationId", conversationID),
+			zap.Error(err))
+		return false
+	}
+	// Agent 无感续跑：不追加新的 user/system 文案，只使用上一段模型可见轨迹继续 Runner。
+	*curFinalMessage = ""
+	if progressCallback != nil {
+		progressCallback("finalization_auto_continue", "最终回复检查尚未收敛，正在基于已有轨迹继续执行…", map[string]interface{}{
+			"conversationId":      conversationID,
+			"source":              "finalizer",
+			"attempt":             *attempt,
+			"maxAttempts":         finalizationAutoContinueMaxAttempts,
+			"status":              decision.Status,
+			"completionReason":    decision.CompletionReason,
+			"missingChecks":       decision.MissingChecks,
+			"pendingExecutionIds": decision.PendingExecutionIDs,
+			"contextInjection":    false,
+		})
+	}
+	select {
+	case <-taskCtx.Done():
+		return false
+	case <-time.After(finalizationAutoContinueBackoff(*attempt)):
+		return true
+	}
+}
+
+func finalizationAutoContinueBackoff(attempt int) time.Duration {
+	if attempt <= 1 {
+		return 500 * time.Millisecond
+	}
+	return time.Duration(attempt) * time.Second
+}

internal/handler/finalization_auto_continue_test.go

@@ -0,0 +1,59 @@
+package handler
+
+import (
+	"testing"
+
+	"cyberstrike-ai/internal/agentfinalizer"
+)
+
+func TestShouldAutoContinueAfterFinalization(t *testing.T) {
+	missingEvidence := agentfinalizer.Decision{
+		Status:           agentfinalizer.StatusBlocked,
+		CompletionReason: agentfinalizer.ReasonMissingEvidence,
+	}
+	if !shouldAutoContinueAfterFinalization(missingEvidence, 0) {
+		t.Fatal("missing execution evidence should trigger auto-continue")
+	}
+	if shouldAutoContinueAfterFinalization(missingEvidence, finalizationAutoContinueMaxAttempts) {
+		t.Fatal("auto-continue should stop at max attempts")
+	}
+
+	finalized := agentfinalizer.Decision{
+		Status:           agentfinalizer.StatusCompleted,
+		CompletionReason: agentfinalizer.ReasonVerified,
+		Finalizable:      true,
+		Finalized:        true,
+	}
+	if shouldAutoContinueAfterFinalization(finalized, 0) {
+		t.Fatal("finalized decision should not auto-continue")
+	}
+
+	awaitingHITL := agentfinalizer.Decision{
+		Status:           agentfinalizer.StatusAwaitingHITL,
+		CompletionReason: agentfinalizer.ReasonAwaitingHITL,
+	}
+	if shouldAutoContinueAfterFinalization(awaitingHITL, 0) {
+		t.Fatal("awaiting HITL should not auto-continue without approval")
+	}
+}
+
+func TestRequestRequiresExecutionEvidenceUsesExplicitPolicyOnly(t *testing.T) {
+	if requestRequiresExecutionEvidence(nil) {
+		t.Fatal("nil request should not require execution evidence")
+	}
+	if requestRequiresExecutionEvidence(&ChatRequest{}) {
+		t.Fatal("missing finalization policy should not require execution evidence")
+	}
+	require := true
+	if !requestRequiresExecutionEvidence(&ChatRequest{
+		Finalization: ChatFinalizationRequest{RequireExecutionEvidence: &require},
+	}) {
+		t.Fatal("explicit true policy should require execution evidence")
+	}
+	require = false
+	if requestRequiresExecutionEvidence(&ChatRequest{
+		Finalization: ChatFinalizationRequest{RequireExecutionEvidence: &require},
+	}) {
+		t.Fatal("explicit false policy should not require execution evidence")
+	}
+}

internal/handler/finalization_helpers.go

@@ -0,0 +1,171 @@
+package handler
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/agentfinalizer"
+	"cyberstrike-ai/internal/multiagent"
+
+	"go.uber.org/zap"
+)
+
+func (h *AgentHandler) finalizeAgentRunForDelivery(
+	conversationID string,
+	assistantMessageID string,
+	agentMode string,
+	result *multiagent.RunResult,
+	mcpExecutionIDs []string,
+	reasoningContent string,
+) agentfinalizer.Decision {
+	return h.finalizeAgentRunForDeliveryWithPolicy(conversationID, assistantMessageID, agentMode, result, mcpExecutionIDs, reasoningContent, false)
+}
+
+func (h *AgentHandler) finalizeAgentRunForDeliveryWithPolicy(
+	conversationID string,
+	assistantMessageID string,
+	agentMode string,
+	result *multiagent.RunResult,
+	mcpExecutionIDs []string,
+	reasoningContent string,
+	requireExecutionEvidence bool,
+) agentfinalizer.Decision {
+	decision := agentfinalizer.FromRunResult(h.db, result, agentfinalizer.Input{
+		ConversationID:           conversationID,
+		AssistantMessageID:       assistantMessageID,
+		AgentMode:                agentMode,
+		MCPExecutionIDs:          mcpExecutionIDs,
+		RequireExecutionEvidence: requireExecutionEvidence,
+	})
+	h.persistFinalizationDecision(conversationID, assistantMessageID, agentMode, mcpExecutionIDs, reasoningContent, decision)
+	return decision
+}
+
+func (h *AgentHandler) decideAgentRunForDeliveryWithPolicy(
+	conversationID string,
+	assistantMessageID string,
+	agentMode string,
+	result *multiagent.RunResult,
+	mcpExecutionIDs []string,
+	requireExecutionEvidence bool,
+) agentfinalizer.Decision {
+	return agentfinalizer.FromRunResult(h.db, result, agentfinalizer.Input{
+		ConversationID:           conversationID,
+		AssistantMessageID:       assistantMessageID,
+		AgentMode:                agentMode,
+		MCPExecutionIDs:          mcpExecutionIDs,
+		RequireExecutionEvidence: requireExecutionEvidence,
+	})
+}
+
+func (h *AgentHandler) decideAgentRunForDelivery(
+	conversationID string,
+	assistantMessageID string,
+	agentMode string,
+	result *multiagent.RunResult,
+	mcpExecutionIDs []string,
+) agentfinalizer.Decision {
+	return agentfinalizer.FromRunResult(h.db, result, agentfinalizer.Input{
+		ConversationID:           conversationID,
+		AssistantMessageID:       assistantMessageID,
+		AgentMode:                agentMode,
+		MCPExecutionIDs:          mcpExecutionIDs,
+		RequireExecutionEvidence: false,
+	})
+}
+
+func (h *AgentHandler) persistFinalizationDecision(
+	conversationID string,
+	assistantMessageID string,
+	agentMode string,
+	mcpExecutionIDs []string,
+	reasoningContent string,
+	decision agentfinalizer.Decision,
+) {
+	if assistantMessageID == "" || h.db == nil {
+		return
+	}
+	_ = h.db.AddProcessDetail(assistantMessageID, conversationID, "finalization_check", finalizationCheckMessage(decision), decision)
+	if decision.Finalizable {
+		if err := h.db.UpdateAssistantMessageFinalize(assistantMessageID, decision.FinalText, mcpExecutionIDs, reasoningContent); err != nil && h.logger != nil {
+			h.logger.Warn("更新最终助手消息失败", zap.Error(err), zap.String("conversationId", conversationID), zap.String("agentMode", agentMode))
+		}
+		return
+	}
+	_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", finalizationBlockedMessage(decision), time.Now(), assistantMessageID)
+}
+
+func (h *AgentHandler) finalizeCandidateForDelivery(
+	conversationID string,
+	assistantMessageID string,
+	agentMode string,
+	response string,
+	mcpExecutionIDs []string,
+	awaitingHITL bool,
+	reasoningContent string,
+) agentfinalizer.Decision {
+	return h.finalizeCandidateForDeliveryWithPolicy(conversationID, assistantMessageID, agentMode, response, mcpExecutionIDs, awaitingHITL, reasoningContent, false)
+}
+
+func (h *AgentHandler) finalizeCandidateForDeliveryWithPolicy(
+	conversationID string,
+	assistantMessageID string,
+	agentMode string,
+	response string,
+	mcpExecutionIDs []string,
+	awaitingHITL bool,
+	reasoningContent string,
+	requireExecutionEvidence bool,
+) agentfinalizer.Decision {
+	decision := agentfinalizer.Decide(h.db, agentfinalizer.Input{
+		Response:                 response,
+		ConversationID:           conversationID,
+		AssistantMessageID:       assistantMessageID,
+		AgentMode:                agentMode,
+		MCPExecutionIDs:          mcpExecutionIDs,
+		AwaitingHITL:             awaitingHITL,
+		RequireExecutionEvidence: requireExecutionEvidence,
+	})
+	if assistantMessageID == "" || h.db == nil {
+		return decision
+	}
+	_ = h.db.AddProcessDetail(assistantMessageID, conversationID, "finalization_check", finalizationCheckMessage(decision), decision)
+	if decision.Finalizable {
+		if err := h.db.UpdateAssistantMessageFinalize(assistantMessageID, decision.FinalText, mcpExecutionIDs, reasoningContent); err != nil && h.logger != nil {
+			h.logger.Warn("更新最终助手消息失败", zap.Error(err), zap.String("conversationId", conversationID), zap.String("agentMode", agentMode))
+		}
+		return decision
+	}
+	_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", finalizationBlockedMessage(decision), time.Now(), assistantMessageID)
+	return decision
+}
+
+func finalizationCheckMessage(d agentfinalizer.Decision) string {
+	if d.Finalizable {
+		return "最终回复检查通过。"
+	}
+	return finalizationBlockedMessage(d)
+}
+
+func finalizationBlockedMessage(d agentfinalizer.Decision) string {
+	parts := []string{"任务尚未达到最终回复条件，暂不生成成功结论。"}
+	if d.CompletionReason != "" {
+		parts = append(parts, "原因: "+d.CompletionReason)
+	}
+	if len(d.PendingExecutionIDs) > 0 {
+		parts = append(parts, fmt.Sprintf("仍有 %d 个工具执行未结束: %s", len(d.PendingExecutionIDs), strings.Join(d.PendingExecutionIDs, ", ")))
+	}
+	if len(d.MissingChecks) > 0 {
+		parts = append(parts, "缺失检查: "+strings.Join(d.MissingChecks, "; "))
+	}
+	return strings.Join(parts, "\n")
+}
+
+func finalizationResponsePayload(d agentfinalizer.Decision, extra map[string]interface{}) map[string]interface{} {
+	return agentfinalizer.ResponsePayload(d, extra)
+}
+
+func requestRequiresExecutionEvidence(req *ChatRequest) bool {
+	return req != nil && req.Finalization.RequireExecutionEvidence != nil && *req.Finalization.RequireExecutionEvidence
+}

internal/handler/fofa_test.go

@@ -0,0 +1,239 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"cyberstrike-ai/internal/config"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func TestFofaSearchUsesAPIKeyWithoutEmail(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	t.Setenv("FOFA_API_KEY", "")
+	t.Setenv("FOFA_EMAIL", "legacy@example.com")
+
+	var receivedEmail string
+	var receivedKey string
+	fofaServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		receivedEmail = r.URL.Query().Get("email")
+		receivedKey = r.URL.Query().Get("key")
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"error":false,"size":1,"page":1,"results":[["https://example.com"]]}`))
+	}))
+	defer fofaServer.Close()
+
+	h := NewFofaHandler(&config.Config{
+		FOFA: config.FofaConfig{
+			BaseURL: fofaServer.URL,
+			APIKey:  "test-api-key",
+		},
+	}, zap.NewNop())
+
+	recorder := httptest.NewRecorder()
+	ctx, _ := gin.CreateTestContext(recorder)
+	body := `{"query":"domain=\"example.com\"","fields":"host"}`
+	ctx.Request = httptest.NewRequest(http.MethodPost, "/api/fofa/search", strings.NewReader(body))
+	ctx.Request.Header.Set("Content-Type", "application/json")
+
+	h.Search(ctx)
+
+	if recorder.Code != http.StatusOK {
+		t.Fatalf("Search() status = %d, body = %s", recorder.Code, recorder.Body.String())
+	}
+	if receivedEmail != "" {
+		t.Fatalf("FOFA request unexpectedly included email = %q", receivedEmail)
+	}
+	if receivedKey != "test-api-key" {
+		t.Fatalf("FOFA request key = %q, want %q", receivedKey, "test-api-key")
+	}
+
+	var response fofaSearchResponse
+	if err := json.Unmarshal(recorder.Body.Bytes(), &response); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if response.ResultsCount != 1 {
+		t.Fatalf("results_count = %d, want 1", response.ResultsCount)
+	}
+}
+
+func TestSafeFofaRequestErrorDoesNotExposeURLOrAPIKey(t *testing.T) {
+	const secretURL = "https://fofa.info/api/v1/search/all?key=secret-api-key"
+	err := &url.Error{
+		Op:  http.MethodGet,
+		URL: secretURL,
+		Err: context.DeadlineExceeded,
+	}
+
+	status, message, timeout := safeFofaRequestError(err)
+
+	if status != http.StatusGatewayTimeout {
+		t.Fatalf("status = %d, want %d", status, http.StatusGatewayTimeout)
+	}
+	if !timeout {
+		t.Fatal("timeout = false, want true")
+	}
+	if strings.Contains(message, "secret-api-key") || strings.Contains(message, secretURL) {
+		t.Fatalf("safe error exposed request URL or API key: %q", message)
+	}
+}
+
+func TestShodanSearchReportsShortfallWhenTotalExceedsMatches(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	t.Setenv("SHODAN_API_KEY", "")
+
+	shodanServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/shodan/host/search" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+		if got := r.URL.Query().Get("key"); got != "test-shodan-key" {
+			t.Fatalf("Shodan key = %q, want test-shodan-key", got)
+		}
+		page := r.URL.Query().Get("page")
+		count := 0
+		switch page {
+		case "1":
+			count = 100
+		case "2":
+			count = 3
+		default:
+			count = 0
+		}
+		matches := make([]map[string]interface{}, 0, count)
+		for i := 0; i < count; i++ {
+			matches = append(matches, map[string]interface{}{
+				"ip_str": fmt.Sprintf("192.0.2.%d", i+1),
+				"port":   80,
+			})
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]interface{}{
+			"total":   104,
+			"matches": matches,
+		})
+	}))
+	defer shodanServer.Close()
+
+	h := NewFofaHandler(&config.Config{
+		Shodan: config.SpaceSearchConfig{
+			BaseURL: shodanServer.URL,
+			APIKey:  "test-shodan-key",
+		},
+	}, zap.NewNop())
+
+	recorder := httptest.NewRecorder()
+	ctx, _ := gin.CreateTestContext(recorder)
+	body := `{"provider":"shodan","query":"product:nginx","fields":"ip_str,port","size":1000,"page":1}`
+	ctx.Request = httptest.NewRequest(http.MethodPost, "/api/fofa/search", strings.NewReader(body))
+	ctx.Request.Header.Set("Content-Type", "application/json")
+
+	h.Search(ctx)
+
+	if recorder.Code != http.StatusOK {
+		t.Fatalf("Search() status = %d, body = %s", recorder.Code, recorder.Body.String())
+	}
+	var response fofaSearchResponse
+	if err := json.Unmarshal(recorder.Body.Bytes(), &response); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if response.Total != 104 || response.ResultsCount != 103 {
+		t.Fatalf("counts: total=%d results_count=%d, want 104/103", response.Total, response.ResultsCount)
+	}
+	if response.ExpectedCount != 104 || response.Shortfall != 1 {
+		t.Fatalf("shortfall: expected=%d shortfall=%d, want 104/1", response.ExpectedCount, response.Shortfall)
+	}
+	if response.Warning == "" {
+		t.Fatal("warning should explain shortfall")
+	}
+}
+
+func TestQuakeSearchHandlesStringErrorCode(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	t.Setenv("QUAKE_API_KEY", "")
+
+	quakeServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("X-QuakeToken"); got != "test-quake-key" {
+			t.Fatalf("Quake token = %q, want test-quake-key", got)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"code":"q5000","message":"查询语法错误"}`))
+	}))
+	defer quakeServer.Close()
+
+	h := NewFofaHandler(&config.Config{
+		Quake: config.SpaceSearchConfig{
+			BaseURL: quakeServer.URL,
+			APIKey:  "test-quake-key",
+		},
+	}, zap.NewNop())
+
+	recorder := httptest.NewRecorder()
+	ctx, _ := gin.CreateTestContext(recorder)
+	body := `{"provider":"quake","query":"bad query","fields":"ip,port","size":10,"page":1}`
+	ctx.Request = httptest.NewRequest(http.MethodPost, "/api/fofa/search", strings.NewReader(body))
+	ctx.Request.Header.Set("Content-Type", "application/json")
+
+	h.Search(ctx)
+
+	if recorder.Code != http.StatusBadGateway {
+		t.Fatalf("Search() status = %d, want %d, body = %s", recorder.Code, http.StatusBadGateway, recorder.Body.String())
+	}
+	bodyText := recorder.Body.String()
+	if !strings.Contains(bodyText, "查询语法错误") {
+		t.Fatalf("response should include Quake error message, got %s", bodyText)
+	}
+	if strings.Contains(bodyText, "cannot unmarshal") {
+		t.Fatalf("response exposed JSON type decoding failure: %s", bodyText)
+	}
+}
+
+func TestExtractInfoCollectJSONObject(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{
+			name: "plain json",
+			in:   `{"query":"title:\"CyberStrikeAI\"","warnings":[]}`,
+			want: `{"query":"title:\"CyberStrikeAI\"","warnings":[]}`,
+		},
+		{
+			name: "fenced json",
+			in:   "```json\n{\"query\":\"product:nginx\"}\n```",
+			want: `{"query":"product:nginx"}`,
+		},
+		{
+			name: "prefixed explanation",
+			in:   "解析结果如下：\n{\"query\":\"ssl.cert.subject.cn:example.com\",\"explanation\":\"ok\"}\n请确认。",
+			want: `{"query":"ssl.cert.subject.cn:example.com","explanation":"ok"}`,
+		},
+		{
+			name: "braces inside string",
+			in:   "结果：{\"query\":\"title:\\\"{admin}\\\"\",\"warnings\":[\"check\"]}",
+			want: `{"query":"title:\"{admin}\"","warnings":["check"]}`,
+		},
+	}
+	for _, tc := range cases {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			got, err := extractInfoCollectJSONObject(tc.in)
+			if err != nil {
+				t.Fatalf("extractInfoCollectJSONObject() error = %v", err)
+			}
+			if got != tc.want {
+				t.Fatalf("extractInfoCollectJSONObject() = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}

internal/handler/group.go

@@ -0,0 +1,438 @@
+package handler
+
+import (
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// GroupHandler 分组处理器
+type GroupHandler struct {
+	db     *database.DB
+	logger *zap.Logger
+}
+
+const (
+	maxGroupNameRunes = 64
+	maxGroupIconRunes = 16
+)
+
+// NewGroupHandler 创建新的分组处理器
+func NewGroupHandler(db *database.DB, logger *zap.Logger) *GroupHandler {
+	return &GroupHandler{
+		db:     db,
+		logger: logger,
+	}
+}
+
+func validateGroupTextField(field, value string, maxRunes int, required bool) (string, error) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		if required {
+			return "", errors.New(field + "不能为空")
+		}
+		return "", nil
+	}
+	if utf8.RuneCountInString(value) > maxRunes {
+		return "", errors.New(field + "过长")
+	}
+	for _, r := range value {
+		switch r {
+		case '<', '>', '"', '\'', '`':
+			return "", errors.New(field + "包含非法字符")
+		}
+		if r < 0x20 || r == 0x7f {
+			return "", errors.New(field + "包含非法控制字符")
+		}
+	}
+	return value, nil
+}
+
+func validateGroupFields(name, icon string) (string, string, error) {
+	validName, err := validateGroupTextField("分组名称", name, maxGroupNameRunes, true)
+	if err != nil {
+		return "", "", err
+	}
+	validIcon, err := validateGroupTextField("分组图标", icon, maxGroupIconRunes, false)
+	if err != nil {
+		return "", "", err
+	}
+	return validName, validIcon, nil
+}
+
+// CreateGroupRequest 创建分组请求
+type CreateGroupRequest struct {
+	Name string `json:"name"`
+	Icon string `json:"icon"`
+}
+
+// CreateGroup 创建分组
+func (h *GroupHandler) CreateGroup(c *gin.Context) {
+	var req CreateGroupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	name, icon, err := validateGroupFields(req.Name, req.Icon)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	session, _ := security.CurrentSession(c)
+	group, err := h.db.CreateGroup(name, icon, session.UserID)
+	if err != nil {
+		h.logger.Error("创建分组失败", zap.Error(err))
+		// 如果是名称重复错误，返回400状态码
+		if err.Error() == "分组名称已存在" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "分组名称已存在"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, group)
+}
+
+// ListGroups 列出所有分组
+func (h *GroupHandler) ListGroups(c *gin.Context) {
+	session, _ := security.CurrentSession(c)
+	groups, err := h.db.ListGroupsForAccess(session.UserID, session.Scope)
+	if err != nil {
+		h.logger.Error("获取分组列表失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, groups)
+}
+
+// GetGroup 获取分组
+func (h *GroupHandler) GetGroup(c *gin.Context) {
+	id := c.Param("id")
+	if !h.groupAllowed(c, id) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+
+	group, err := h.db.GetGroup(id)
+	if err != nil {
+		h.logger.Error("获取分组失败", zap.Error(err))
+		c.JSON(http.StatusNotFound, gin.H{"error": "分组不存在"})
+		return
+	}
+
+	c.JSON(http.StatusOK, group)
+}
+
+// UpdateGroupRequest 更新分组请求
+type UpdateGroupRequest struct {
+	Name string `json:"name"`
+	Icon string `json:"icon"`
+}
+
+// UpdateGroup 更新分组
+func (h *GroupHandler) UpdateGroup(c *gin.Context) {
+	id := c.Param("id")
+	if !h.groupAllowed(c, id) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+
+	var req UpdateGroupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	name, icon, err := validateGroupFields(req.Name, req.Icon)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if err := h.db.UpdateGroup(id, name, icon); err != nil {
+		h.logger.Error("更新分组失败", zap.Error(err))
+		// 如果是名称重复错误，返回400状态码
+		if err.Error() == "分组名称已存在" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "分组名称已存在"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	group, err := h.db.GetGroup(id)
+	if err != nil {
+		h.logger.Error("获取更新后的分组失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, group)
+}
+
+// DeleteGroup 删除分组
+func (h *GroupHandler) DeleteGroup(c *gin.Context) {
+	id := c.Param("id")
+	if !h.groupAllowed(c, id) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+
+	if err := h.db.DeleteGroup(id); err != nil {
+		h.logger.Error("删除分组失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "删除成功"})
+}
+
+// AddConversationToGroupRequest 添加对话到分组请求
+type AddConversationToGroupRequest struct {
+	ConversationID string `json:"conversationId"`
+	GroupID        string `json:"groupId"`
+}
+
+// AddConversationToGroup 将对话添加到分组
+func (h *GroupHandler) AddConversationToGroup(c *gin.Context) {
+	var req AddConversationToGroupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if !h.groupConversationAllowed(c, req.ConversationID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+	if !h.groupAllowed(c, req.GroupID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该分组"})
+		return
+	}
+
+	if err := h.db.AddConversationToGroup(req.ConversationID, req.GroupID); err != nil {
+		h.logger.Error("添加对话到分组失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "添加成功"})
+}
+
+// RemoveConversationFromGroup 从分组中移除对话
+func (h *GroupHandler) RemoveConversationFromGroup(c *gin.Context) {
+	conversationID := c.Param("conversationId")
+	groupID := c.Param("id")
+	if !h.groupAllowed(c, groupID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该分组"})
+		return
+	}
+	if !h.groupConversationAllowed(c, conversationID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+
+	if err := h.db.RemoveConversationFromGroup(conversationID, groupID); err != nil {
+		h.logger.Error("从分组中移除对话失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "移除成功"})
+}
+
+// GroupConversation 分组对话响应结构
+type GroupConversation struct {
+	ID          string    `json:"id"`
+	Title       string    `json:"title"`
+	Pinned      bool      `json:"pinned"`
+	GroupPinned bool      `json:"groupPinned"`
+	CreatedAt   time.Time `json:"createdAt"`
+	UpdatedAt   time.Time `json:"updatedAt"`
+}
+
+// GetGroupConversations 获取分组中的所有对话
+func (h *GroupHandler) GetGroupConversations(c *gin.Context) {
+	groupID := c.Param("id")
+	if !h.groupAllowed(c, groupID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该分组"})
+		return
+	}
+	searchQuery := c.Query("search") // 获取搜索参数
+
+	var conversations []*database.Conversation
+	var err error
+
+	// 如果有搜索关键词，使用搜索方法；否则使用普通方法
+	if searchQuery != "" {
+		conversations, err = h.db.SearchConversationsByGroup(groupID, searchQuery)
+	} else {
+		conversations, err = h.db.GetConversationsByGroup(groupID)
+	}
+
+	if err != nil {
+		h.logger.Error("获取分组对话失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// 获取每个对话在分组中的置顶状态
+	groupConvs := make([]GroupConversation, 0, len(conversations))
+	for _, conv := range conversations {
+		if conv == nil || !h.groupConversationAllowed(c, conv.ID) {
+			continue
+		}
+		// 查询分组内置顶状态
+		var groupPinned int
+		err := h.db.QueryRow(
+			"SELECT COALESCE(pinned, 0) FROM conversation_group_mappings WHERE conversation_id = ? AND group_id = ?",
+			conv.ID, groupID,
+		).Scan(&groupPinned)
+		if err != nil {
+			h.logger.Warn("查询分组内置顶状态失败", zap.String("conversationId", conv.ID), zap.Error(err))
+			groupPinned = 0
+		}
+
+		groupConvs = append(groupConvs, GroupConversation{
+			ID:          conv.ID,
+			Title:       conv.Title,
+			Pinned:      conv.Pinned,
+			GroupPinned: groupPinned != 0,
+			CreatedAt:   conv.CreatedAt,
+			UpdatedAt:   conv.UpdatedAt,
+		})
+	}
+
+	c.JSON(http.StatusOK, groupConvs)
+}
+
+// GetAllMappings 批量获取所有分组映射（消除前端 N+1 请求）
+func (h *GroupHandler) GetAllMappings(c *gin.Context) {
+	mappings, err := h.db.GetAllGroupMappings()
+	if err != nil {
+		h.logger.Error("获取分组映射失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	filtered := mappings[:0]
+	for _, mapping := range mappings {
+		if h.groupConversationAllowed(c, mapping.ConversationID) && h.groupAllowed(c, mapping.GroupID) {
+			filtered = append(filtered, mapping)
+		}
+	}
+
+	c.JSON(http.StatusOK, filtered)
+}
+
+// UpdateConversationPinnedRequest 更新对话置顶状态请求
+type UpdateConversationPinnedRequest struct {
+	Pinned bool `json:"pinned"`
+}
+
+// UpdateConversationPinned 更新对话置顶状态
+func (h *GroupHandler) UpdateConversationPinned(c *gin.Context) {
+	conversationID := c.Param("id")
+	if !h.groupConversationAllowed(c, conversationID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+
+	var req UpdateConversationPinnedRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if err := h.db.UpdateConversationPinned(conversationID, req.Pinned); err != nil {
+		h.logger.Error("更新对话置顶状态失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "更新成功"})
+}
+
+// UpdateGroupPinnedRequest 更新分组置顶状态请求
+type UpdateGroupPinnedRequest struct {
+	Pinned bool `json:"pinned"`
+}
+
+// UpdateGroupPinned 更新分组置顶状态
+func (h *GroupHandler) UpdateGroupPinned(c *gin.Context) {
+	groupID := c.Param("id")
+	if !h.groupAllowed(c, groupID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该分组"})
+		return
+	}
+
+	var req UpdateGroupPinnedRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if err := h.db.UpdateGroupPinned(groupID, req.Pinned); err != nil {
+		h.logger.Error("更新分组置顶状态失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "更新成功"})
+}
+
+// UpdateConversationPinnedInGroupRequest 更新分组对话置顶状态请求
+type UpdateConversationPinnedInGroupRequest struct {
+	Pinned bool `json:"pinned"`
+}
+
+// UpdateConversationPinnedInGroup 更新对话在分组中的置顶状态
+func (h *GroupHandler) UpdateConversationPinnedInGroup(c *gin.Context) {
+	groupID := c.Param("id")
+	conversationID := c.Param("conversationId")
+	if !h.groupAllowed(c, groupID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该分组"})
+		return
+	}
+	if !h.groupConversationAllowed(c, conversationID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+
+	var req UpdateConversationPinnedInGroupRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	if err := h.db.UpdateConversationPinnedInGroup(conversationID, groupID, req.Pinned); err != nil {
+		h.logger.Error("更新分组对话置顶状态失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "更新成功"})
+}
+
+func (h *GroupHandler) groupConversationAllowed(c *gin.Context, conversationID string) bool {
+	session, ok := security.CurrentSession(c)
+	if !ok {
+		return false
+	}
+	return h.db.UserCanAccessResource(session.UserID, session.Scope, "conversation", conversationID)
+}
+
+func (h *GroupHandler) groupAllowed(c *gin.Context, groupID string) bool {
+	session, ok := security.CurrentSession(c)
+	return ok && h.db.UserCanAccessGroup(session.UserID, session.Scope, groupID)
+}

internal/handler/group_test.go

@@ -0,0 +1,41 @@
+package handler
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestValidateGroupFieldsAllowsNormalNamesAndIcons(t *testing.T) {
+	name, icon, err := validateGroupFields("  日常安全巡检  ", " 📁 ")
+	if err != nil {
+		t.Fatalf("validateGroupFields returned error: %v", err)
+	}
+	if name != "日常安全巡检" {
+		t.Fatalf("name = %q, want trimmed normal name", name)
+	}
+	if icon != "📁" {
+		t.Fatalf("icon = %q, want trimmed icon", icon)
+	}
+}
+
+func TestValidateGroupFieldsRejectsStoredXSSPayloads(t *testing.T) {
+	tests := []struct {
+		name string
+		icon string
+	}{
+		{name: `<img src=x onerror="alert(1)">`, icon: "📁"},
+		{name: "日常安全巡检", icon: `<svg onload=alert(1)>`},
+		{name: "日常安全巡检`onmouseover=alert(1)", icon: "📁"},
+		{name: "日常安全巡检\x00", icon: "📁"},
+		{name: strings.Repeat("分", maxGroupNameRunes+1), icon: "📁"},
+		{name: "日常安全巡检", icon: strings.Repeat("📁", maxGroupIconRunes+1)},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name+"/"+tt.icon, func(t *testing.T) {
+			if _, _, err := validateGroupFields(tt.name, tt.icon); err == nil {
+				t.Fatal("validateGroupFields returned nil error for unsafe input")
+			}
+		})
+	}
+}

internal/handler/hitl_audit_agent.go

@@ -0,0 +1,360 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/openai"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// auditAgentReview 在 reviewer=audit_agent 时由 LLM 代行审批。
+// 白名单工具在 shouldInterrupt 阶段已跳过，到达此处的一律需要裁决。
+func (h *AgentHandler) auditAgentReview(ctx context.Context, hitlMode, toolName string, payload map[string]interface{}) hitlDecision {
+	if h == nil {
+		return hitlDecision{Decision: "reject", Comment: "audit agent: handler unavailable"}
+	}
+	mode := normalizeHitlMode(hitlMode)
+	prompt := config.DefaultHitlAuditAgentPrompt()
+	if h.config != nil {
+		prompt = h.config.Hitl.EffectiveAuditAgentPromptForMode(mode)
+	}
+	llmCfg := h.auditLLMConfig()
+	if strings.TrimSpace(llmCfg.APIKey) == "" || strings.TrimSpace(llmCfg.Model) == "" {
+		return hitlDecision{Decision: "reject", Comment: "audit agent: LLM 未配置"}
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	callCtx, cancel := context.WithTimeout(ctx, 90*time.Second)
+	defer cancel()
+
+	userContent := buildAuditAgentReviewInput(mode, toolName, payload)
+	requestBody := map[string]interface{}{
+		"model": strings.TrimSpace(llmCfg.Model),
+		"messages": []map[string]interface{}{
+			{"role": "system", "content": prompt},
+			{"role": "user", "content": userContent},
+		},
+		"temperature":           0.1,
+		"max_completion_tokens": 1024,
+		// 审计裁决需要结构化 JSON；关闭 thinking 避免 Qwen 等把正文放进 reasoning_content 导致解析失败。
+		"thinking": map[string]interface{}{"type": "disabled"},
+	}
+
+	var apiResponse struct {
+		Choices []struct {
+			Message struct {
+				Content          string `json:"content"`
+				ReasoningContent string `json:"reasoning_content"`
+			} `json:"message"`
+		} `json:"choices"`
+	}
+	client := openai.NewClient(&llmCfg, nil, h.logger)
+	if err := client.ChatCompletion(callCtx, requestBody, &apiResponse); err != nil {
+		h.logger.Warn("审计 Agent LLM 调用失败", zap.Error(err), zap.String("tool", toolName))
+		return hitlDecision{
+			Decision: "reject",
+			Comment:  "audit agent: LLM 调用失败，保守拒绝",
+		}
+	}
+	if len(apiResponse.Choices) == 0 {
+		return hitlDecision{Decision: "reject", Comment: "audit agent: LLM 无有效响应，保守拒绝"}
+	}
+	msg := apiResponse.Choices[0].Message
+	raw := strings.TrimSpace(msg.Content)
+	if raw == "" {
+		raw = strings.TrimSpace(msg.ReasoningContent)
+	}
+	dec, err := parseAuditAgentLLMContent(raw)
+	if err != nil {
+		snippet := raw
+		if len(snippet) > 240 {
+			snippet = snippet[:240] + "..."
+		}
+		h.logger.Warn("审计 Agent 响应解析失败",
+			zap.Error(err),
+			zap.String("tool", toolName),
+			zap.String("mode", mode),
+			zap.String("snippet", snippet),
+		)
+		return hitlDecision{Decision: "reject", Comment: "audit agent: 响应无法解析，保守拒绝"}
+	}
+	if mode != "review_edit" && len(dec.EditedArguments) > 0 {
+		h.logger.Warn("审计 Agent 在审批模式下返回 editedArguments，已忽略",
+			zap.String("tool", toolName),
+		)
+		dec.EditedArguments = nil
+	}
+	if dec.Comment == "" {
+		dec.Comment = "audit agent: " + dec.Decision
+	} else if !strings.HasPrefix(strings.ToLower(dec.Comment), "audit agent") {
+		dec.Comment = "audit agent: " + dec.Comment
+	}
+	return dec
+}
+
+func (h *AgentHandler) auditLLMConfig() config.OpenAIConfig {
+	if h != nil && h.config != nil {
+		return h.config.Hitl.AuditModelEffective(h.config.OpenAI)
+	}
+	return config.OpenAIConfig{}
+}
+
+func buildAuditAgentReviewInput(hitlMode, toolName string, payload map[string]interface{}) string {
+	review := map[string]interface{}{
+		"hitlMode": normalizeHitlMode(hitlMode),
+		"toolName": strings.TrimSpace(toolName),
+	}
+	if payload != nil {
+		for _, k := range []string{"arguments", "argumentsObj", "command", hitlPayloadUserMessage, hitlPayloadThinking, hitlPayloadReasoningChain, hitlPayloadPlanning} {
+			if v, ok := payload[k]; ok && v != nil && fmt.Sprint(v) != "" {
+				review[k] = v
+			}
+		}
+	}
+	b, err := json.MarshalIndent(review, "", "  ")
+	if err != nil {
+		return fmt.Sprintf(`{"hitlMode":%q,"toolName":%q}`, normalizeHitlMode(hitlMode), toolName)
+	}
+	return string(b)
+}
+
+func parseAuditAgentLLMContent(content string) (hitlDecision, error) {
+	s := strings.TrimSpace(content)
+	if s == "" {
+		return hitlDecision{}, errors.New("empty content")
+	}
+	for _, candidate := range auditAgentJSONCandidates(s) {
+		dec, comment, editedArgs, err := parseAuditAgentDecisionObject(candidate)
+		if err == nil {
+			return hitlDecision{
+				Decision:        dec,
+				Comment:         comment,
+				EditedArguments: editedArgs,
+			}, nil
+		}
+	}
+	return hitlDecision{}, fmt.Errorf("no valid decision json in response")
+}
+
+func auditAgentJSONCandidates(s string) []string {
+	out := make([]string, 0, 4)
+	seen := make(map[string]struct{})
+	add := func(c string) {
+		c = strings.TrimSpace(c)
+		if c == "" {
+			return
+		}
+		if _, ok := seen[c]; ok {
+			return
+		}
+		seen[c] = struct{}{}
+		out = append(out, c)
+	}
+	add(s)
+	add(stripMarkdownCodeFence(s))
+	if obj := extractFirstJSONObject(s); obj != "" {
+		add(obj)
+	}
+	if obj := extractFirstJSONObject(stripMarkdownCodeFence(s)); obj != "" {
+		add(obj)
+	}
+	return out
+}
+
+func stripMarkdownCodeFence(s string) string {
+	s = strings.TrimSpace(s)
+	for _, fence := range []string{"```json", "```JSON", "```"} {
+		if strings.HasPrefix(s, fence) {
+			s = strings.TrimPrefix(s, fence)
+		}
+	}
+	s = strings.TrimSuffix(s, "```")
+	return strings.TrimSpace(s)
+}
+
+func extractFirstJSONObject(s string) string {
+	start := strings.Index(s, "{")
+	if start < 0 {
+		return ""
+	}
+	depth := 0
+	inStr := false
+	esc := false
+	for i := start; i < len(s); i++ {
+		ch := s[i]
+		if inStr {
+			if esc {
+				esc = false
+				continue
+			}
+			if ch == '\\' {
+				esc = true
+				continue
+			}
+			if ch == '"' {
+				inStr = false
+			}
+			continue
+		}
+		switch ch {
+		case '"':
+			inStr = true
+		case '{':
+			depth++
+		case '}':
+			depth--
+			if depth == 0 {
+				return s[start : i+1]
+			}
+		}
+	}
+	return ""
+}
+
+func parseAuditAgentDecisionObject(jsonText string) (decision, comment string, editedArgs map[string]interface{}, err error) {
+	var parsed map[string]interface{}
+	if err := json.Unmarshal([]byte(jsonText), &parsed); err != nil {
+		return "", "", nil, err
+	}
+	rawDecision := auditAgentPickString(parsed, "decision", "Decision", "result", "action", "verdict", "决策", "决定")
+	decision = normalizeAuditAgentDecision(rawDecision)
+	if decision == "" {
+		return "", "", nil, fmt.Errorf("missing decision")
+	}
+	comment = auditAgentPickString(parsed, "comment", "Comment", "reason", "message", "rationale", "备注", "理由", "说明")
+	editedArgs = auditAgentPickObject(parsed, "editedArguments", "edited_arguments", "editedArgs")
+	return decision, strings.TrimSpace(comment), editedArgs, nil
+}
+
+func auditAgentPickString(m map[string]interface{}, keys ...string) string {
+	for _, k := range keys {
+		if v, ok := m[k]; ok && v != nil {
+			s := strings.TrimSpace(fmt.Sprint(v))
+			if s != "" {
+				return s
+			}
+		}
+	}
+	return ""
+}
+
+func auditAgentPickObject(m map[string]interface{}, keys ...string) map[string]interface{} {
+	for _, k := range keys {
+		v, ok := m[k]
+		if !ok || v == nil {
+			continue
+		}
+		switch t := v.(type) {
+		case map[string]interface{}:
+			if len(t) > 0 {
+				return t
+			}
+		case string:
+			s := strings.TrimSpace(t)
+			if s == "" || s == "{}" {
+				continue
+			}
+			var obj map[string]interface{}
+			if err := json.Unmarshal([]byte(s), &obj); err == nil && len(obj) > 0 {
+				return obj
+			}
+		}
+	}
+	return nil
+}
+
+func normalizeAuditAgentDecision(v string) string {
+	d := strings.ToLower(strings.TrimSpace(v))
+	switch d {
+	case "approve", "approved", "pass", "passed", "allow", "allowed", "yes", "ok", "accept", "accepted":
+		return "approve"
+	case "reject", "rejected", "deny", "denied", "no", "block", "blocked", "refuse", "refused":
+		return "reject"
+	}
+	switch strings.TrimSpace(v) {
+	case "通过", "批准", "允许", "同意", "放行":
+		return "approve"
+	case "拒绝", "驳回", "禁止", "否决":
+		return "reject"
+	}
+	return ""
+}
+
+type hitlAuditStrategyReq struct {
+	AuditAgentPrompt           string `json:"auditAgentPrompt"`
+	AuditAgentPromptReviewEdit string `json:"auditAgentPromptReviewEdit"`
+}
+
+func (h *AgentHandler) GetHITLAuditStrategy(c *gin.Context) {
+	approvalPrompt := config.DefaultHitlAuditAgentPrompt()
+	reviewEditPrompt := config.DefaultHitlAuditAgentPromptReviewEdit()
+	approvalCustom := false
+	reviewEditCustom := false
+	if h.config != nil {
+		approvalPrompt = h.config.Hitl.EffectiveAuditAgentPromptForMode("approval")
+		reviewEditPrompt = h.config.Hitl.EffectiveAuditAgentPromptForMode("review_edit")
+		approvalCustom = strings.TrimSpace(h.config.Hitl.AuditAgentPrompt) != ""
+		reviewEditCustom = strings.TrimSpace(h.config.Hitl.AuditAgentPromptReviewEdit) != ""
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"auditAgentPrompt":                  approvalPrompt,
+		"auditAgentPromptCustom":            approvalCustom,
+		"auditAgentPromptReviewEdit":        reviewEditPrompt,
+		"auditAgentPromptReviewEditCustom":  reviewEditCustom,
+		"defaultAuditAgentPrompt":           config.DefaultHitlAuditAgentPrompt(),
+		"defaultAuditAgentPromptReviewEdit": config.DefaultHitlAuditAgentPromptReviewEdit(),
+	})
+}
+
+func (h *AgentHandler) UpdateHITLAuditStrategy(c *gin.Context) {
+	if h.hitlStrategySaver == nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "HITL 策略持久化不可用"})
+		return
+	}
+	var req hitlAuditStrategyReq
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	approvalPrompt := strings.TrimSpace(req.AuditAgentPrompt)
+	reviewEditPrompt := strings.TrimSpace(req.AuditAgentPromptReviewEdit)
+	if err := h.hitlStrategySaver.UpdateHitlAuditAgentStrategy(approvalPrompt, reviewEditPrompt); err != nil {
+		h.logger.Warn("保存审计 Agent 提示词失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "hitl", "audit_strategy_update", "HITL 审计策略更新", "hitl_config", "audit_agent_prompt", nil)
+	}
+	if h.config != nil {
+		h.config.Hitl.AuditAgentPrompt = approvalPrompt
+		h.config.Hitl.AuditAgentPromptReviewEdit = reviewEditPrompt
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"ok":                               true,
+		"auditAgentPrompt":                 config.HitlConfig{AuditAgentPrompt: approvalPrompt}.EffectiveAuditAgentPromptForMode("approval"),
+		"auditAgentPromptCustom":           approvalPrompt != "",
+		"auditAgentPromptReviewEdit":       config.HitlConfig{AuditAgentPromptReviewEdit: reviewEditPrompt}.EffectiveAuditAgentPromptForMode("review_edit"),
+		"auditAgentPromptReviewEditCustom": reviewEditPrompt != "",
+	})
+}
+
+// HitlAuditStrategySaver 持久化审计 Agent 提示词到 config.yaml。
+type HitlAuditStrategySaver interface {
+	UpdateHitlAuditAgentStrategy(approvalPrompt, reviewEditPrompt string) error
+}
+
+// SetHitlAuditStrategySaver 设置审计策略落盘。
+func (h *AgentHandler) SetHitlAuditStrategySaver(s HitlAuditStrategySaver) {
+	h.hitlStrategySaver = s
+}

internal/handler/hitl_audit_agent_test.go

@@ -0,0 +1,88 @@
+package handler
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestParseAuditAgentLLMContentApprove(t *testing.T) {
+	d, err := parseAuditAgentLLMContent(`{"decision":"approve","comment":"与任务一致"}`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if d.Decision != "approve" || d.Comment != "与任务一致" {
+		t.Fatalf("unexpected %+v", d)
+	}
+}
+
+func TestParseAuditAgentLLMContentReject(t *testing.T) {
+	d, err := parseAuditAgentLLMContent("```json\n{\"decision\":\"reject\",\"comment\":\"风险过高\"}\n```")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if d.Decision != "reject" {
+		t.Fatalf("expected reject, got %s", d.Decision)
+	}
+}
+
+func TestParseAuditAgentLLMContentInvalid(t *testing.T) {
+	_, err := parseAuditAgentLLMContent(`{"decision":"maybe"}`)
+	if err == nil {
+		t.Fatal("expected error for invalid decision")
+	}
+}
+
+func TestParseAuditAgentLLMContentProseWrapped(t *testing.T) {
+	d, err := parseAuditAgentLLMContent("好的，裁决如下：\n```json\n{\"decision\":\"approve\",\"comment\":\"只读 ls\"}\n```\n以上。")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if d.Decision != "approve" {
+		t.Fatalf("expected approve, got %s", d.Decision)
+	}
+}
+
+func TestParseAuditAgentLLMContentChineseDecision(t *testing.T) {
+	d, err := parseAuditAgentLLMContent(`{"decision":"通过","comment":"风险低"}`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if d.Decision != "approve" {
+		t.Fatalf("expected approve, got %s", d.Decision)
+	}
+}
+
+func TestParseAuditAgentLLMContentWithEditedArguments(t *testing.T) {
+	d, err := parseAuditAgentLLMContent(`{"decision":"approve","comment":"收窄路径","editedArguments":{"path":"/safe"}}`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if d.Decision != "approve" {
+		t.Fatalf("expected approve, got %s", d.Decision)
+	}
+	if d.EditedArguments == nil || d.EditedArguments["path"] != "/safe" {
+		t.Fatalf("unexpected edited args: %+v", d.EditedArguments)
+	}
+}
+
+func TestBuildAuditAgentReviewInputIncludesMode(t *testing.T) {
+	s := buildAuditAgentReviewInput("review_edit", "execute", map[string]interface{}{
+		"arguments": `{"command":"pwd"}`,
+	})
+	if !strings.Contains(s, "review_edit") || !strings.Contains(s, "execute") {
+		t.Fatalf("unexpected input: %s", s)
+	}
+}
+
+func TestBuildAuditAgentReviewInput(t *testing.T) {
+	s := buildAuditAgentReviewInput("approval", "nmap", map[string]interface{}{
+		"arguments":   `{"target":"10.0.0.1"}`,
+		"userMessage": "扫描内网",
+	})
+	if s == "" {
+		t.Fatal("expected non-empty input")
+	}
+	if !strings.Contains(s, "nmap") || !strings.Contains(s, "10.0.0.1") || !strings.Contains(s, "扫描内网") {
+		t.Fatalf("unexpected input: %s", s)
+	}
+}

internal/handler/hitl_cognition.go

@@ -0,0 +1,97 @@
+package handler
+
+import (
+	"strings"
+)
+
+type hitlCognitionState struct {
+	AssistantMessageID string
+	UserMessage        string
+	Thinking           string
+	ReasoningChain     string
+	Planning           string
+}
+
+// GetHitlCognition 返回当前运行任务上缓存的本轮 HITL 上下文（不含会话历史）。
+func (m *AgentTaskManager) GetHitlCognition(conversationID string) hitlCognitionFields {
+	conversationID = strings.TrimSpace(conversationID)
+	if m == nil || conversationID == "" {
+		return hitlCognitionFields{}
+	}
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	t, ok := m.tasks[conversationID]
+	if !ok || t == nil || t.hitlCognition == nil {
+		return hitlCognitionFields{}
+	}
+	c := t.hitlCognition
+	return hitlCognitionFields{
+		UserMessage:    c.UserMessage,
+		Thinking:       c.Thinking,
+		ReasoningChain: c.ReasoningChain,
+		Planning:       c.Planning,
+	}
+}
+
+// ResetHitlCognition 新任务开始时重置本轮 HITL 上下文。
+func (m *AgentTaskManager) ResetHitlCognition(conversationID, userMessage string) {
+	conversationID = strings.TrimSpace(conversationID)
+	if m == nil || conversationID == "" {
+		return
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	t, ok := m.tasks[conversationID]
+	if !ok || t == nil {
+		return
+	}
+	t.hitlCognition = &hitlCognitionState{UserMessage: strings.TrimSpace(userMessage)}
+}
+
+// SetHitlAssistantMessageID 记录当前助手消息 ID，供 HITL 与 DB 回退对齐。
+func (m *AgentTaskManager) SetHitlAssistantMessageID(conversationID, assistantMessageID string) {
+	conversationID = strings.TrimSpace(conversationID)
+	assistantMessageID = strings.TrimSpace(assistantMessageID)
+	if m == nil || conversationID == "" || assistantMessageID == "" {
+		return
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	t, ok := m.tasks[conversationID]
+	if !ok || t == nil {
+		return
+	}
+	if t.hitlCognition == nil {
+		t.hitlCognition = &hitlCognitionState{}
+	}
+	t.hitlCognition.AssistantMessageID = assistantMessageID
+}
+
+// UpdateHitlCognitionSnapshot 从进行中的进度流快照更新 thinking / reasoning / planning。
+func (m *AgentTaskManager) UpdateHitlCognitionSnapshot(conversationID, assistantMessageID, thinking, reasoningChain, planning string) {
+	conversationID = strings.TrimSpace(conversationID)
+	if m == nil || conversationID == "" {
+		return
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	t, ok := m.tasks[conversationID]
+	if !ok || t == nil {
+		return
+	}
+	if t.hitlCognition == nil {
+		t.hitlCognition = &hitlCognitionState{}
+	}
+	if id := strings.TrimSpace(assistantMessageID); id != "" {
+		t.hitlCognition.AssistantMessageID = id
+	}
+	if s := strings.TrimSpace(thinking); s != "" {
+		t.hitlCognition.Thinking = s
+	}
+	if s := strings.TrimSpace(reasoningChain); s != "" {
+		t.hitlCognition.ReasoningChain = s
+	}
+	if s := strings.TrimSpace(planning); s != "" {
+		t.hitlCognition.Planning = s
+	}
+}

internal/handler/hitl_context.go

@@ -0,0 +1,102 @@
+package handler
+
+import (
+	"strings"
+)
+
+const (
+	hitlPayloadUserMessage    = "userMessage"
+	hitlPayloadThinking       = "thinking"
+	hitlPayloadReasoningChain = "reasoningChain"
+	hitlPayloadPlanning       = "planning"
+)
+
+type hitlCognitionFields struct {
+	UserMessage    string
+	Thinking       string
+	ReasoningChain string
+	Planning       string
+}
+
+func (h *AgentHandler) enrichHitlApprovalPayload(conversationID, assistantMessageID string, payload map[string]interface{}) {
+	if h == nil || payload == nil {
+		return
+	}
+	cog := h.collectHitlCognition(conversationID, assistantMessageID)
+	if s := strings.TrimSpace(cog.UserMessage); s != "" {
+		payload[hitlPayloadUserMessage] = s
+	}
+	if s := strings.TrimSpace(cog.Thinking); s != "" {
+		payload[hitlPayloadThinking] = s
+	}
+	if s := strings.TrimSpace(cog.ReasoningChain); s != "" {
+		payload[hitlPayloadReasoningChain] = s
+	}
+	if s := strings.TrimSpace(cog.Planning); s != "" {
+		payload[hitlPayloadPlanning] = s
+	}
+}
+
+func (h *AgentHandler) collectHitlCognition(conversationID, assistantMessageID string) hitlCognitionFields {
+	var out hitlCognitionFields
+	if h.tasks != nil {
+		out = h.tasks.GetHitlCognition(conversationID)
+	}
+	if strings.TrimSpace(out.UserMessage) == "" && h.db != nil {
+		if msg, err := h.db.GetTurnUserMessage(conversationID, assistantMessageID); err == nil {
+			out.UserMessage = msg
+		}
+	}
+	if h.db != nil && assistantMessageID != "" {
+		dbCog, err := h.db.GetAssistantCognitionTexts(assistantMessageID)
+		if err == nil {
+			if strings.TrimSpace(out.Thinking) == "" {
+				out.Thinking = dbCog.Thinking
+			}
+			if strings.TrimSpace(out.ReasoningChain) == "" {
+				out.ReasoningChain = dbCog.ReasoningChain
+			}
+			if strings.TrimSpace(out.Planning) == "" {
+				out.Planning = dbCog.Planning
+			}
+		}
+	}
+	return out
+}
+
+func snapshotHitlCognitionFromStreams(thinkingStreams map[string]*thinkingBuf, respPlan *responsePlanAgg) (thinking, reasoningChain, planning string) {
+	if len(thinkingStreams) > 0 {
+		var thinkingParts, reasoningParts []string
+		for _, tb := range thinkingStreams {
+			if tb == nil {
+				continue
+			}
+			content := strings.TrimSpace(tb.b.String())
+			if content == "" {
+				continue
+			}
+			if tb.persistAs == "reasoning_chain" {
+				reasoningParts = append(reasoningParts, content)
+			} else {
+				thinkingParts = append(thinkingParts, content)
+			}
+		}
+		thinking = strings.Join(thinkingParts, "\n\n")
+		reasoningChain = strings.Join(reasoningParts, "\n\n")
+	}
+	if respPlan != nil {
+		planning = strings.TrimSpace(respPlan.b.String())
+	}
+	return thinking, reasoningChain, planning
+}
+
+func (h *AgentHandler) syncHitlCognitionFromProgress(conversationID, assistantMessageID string, thinkingStreams map[string]*thinkingBuf, respPlan *responsePlanAgg) {
+	if h == nil || h.tasks == nil {
+		return
+	}
+	thinking, reasoning, planning := snapshotHitlCognitionFromStreams(thinkingStreams, respPlan)
+	if thinking == "" && reasoning == "" && planning == "" {
+		return
+	}
+	h.tasks.UpdateHitlCognitionSnapshot(conversationID, assistantMessageID, thinking, reasoning, planning)
+}

internal/handler/hitl_context_test.go

@@ -0,0 +1,46 @@
+package handler
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"cyberstrike-ai/internal/database"
+
+	"go.uber.org/zap"
+)
+
+func TestEnrichHitlApprovalPayload(t *testing.T) {
+	tmp := t.TempDir()
+	db, err := database.NewDB(filepath.Join(tmp, "test.sqlite"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("db: %v", err)
+	}
+	defer os.RemoveAll(tmp)
+
+	conv, err := db.CreateConversation("hitl ctx", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("conv: %v", err)
+	}
+	if _, err := db.AddMessage(conv.ID, "user", "scan 10.0.0.1 please", nil); err != nil {
+		t.Fatalf("user msg: %v", err)
+	}
+	asst, err := db.AddMessage(conv.ID, "assistant", "", nil)
+	if err != nil {
+		t.Fatalf("asst msg: %v", err)
+	}
+	if err := db.AddProcessDetail(asst.ID, conv.ID, "thinking", "need port scan first", nil); err != nil {
+		t.Fatalf("detail: %v", err)
+	}
+
+	h := &AgentHandler{db: db, tasks: NewAgentTaskManager()}
+	payload := map[string]interface{}{"toolName": "nmap", "arguments": "{}"}
+	h.enrichHitlApprovalPayload(conv.ID, asst.ID, payload)
+
+	if got := payload["userMessage"]; got != "scan 10.0.0.1 please" {
+		t.Fatalf("userMessage=%v", got)
+	}
+	if got := payload["thinking"]; got != "need port scan first" {
+		t.Fatalf("thinking=%v", got)
+	}
+}

internal/handler/hitl_execution.go

@@ -0,0 +1,132 @@
+package handler
+
+import (
+	"encoding/json"
+	"strings"
+	"time"
+)
+
+const hitlPayloadExecutionResult = "executionResult"
+
+type hitlExecutionResult struct {
+	Success    bool      `json:"success"`
+	Result     string    `json:"result,omitempty"`
+	ToolName   string    `json:"toolName,omitempty"`
+	ToolCallID string    `json:"toolCallId,omitempty"`
+	RecordedAt time.Time `json:"recordedAt"`
+}
+
+type hitlApprovedExecTrack struct {
+	InterruptID    string
+	ConversationID string
+	ToolName       string
+	ToolCallID     string
+}
+
+// TrackApprovedHitlExecution 审批通过后登记，待 tool_result 回写执行结果。
+func (m *HITLManager) TrackApprovedHitlExecution(interruptID, conversationID, toolName, toolCallID string) {
+	if m == nil {
+		return
+	}
+	interruptID = strings.TrimSpace(interruptID)
+	conversationID = strings.TrimSpace(conversationID)
+	if interruptID == "" || conversationID == "" {
+		return
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.approvedExec == nil {
+		m.approvedExec = make(map[string][]hitlApprovedExecTrack)
+	}
+	m.approvedExec[conversationID] = append(m.approvedExec[conversationID], hitlApprovedExecTrack{
+		InterruptID:    interruptID,
+		ConversationID: conversationID,
+		ToolName:       strings.TrimSpace(toolName),
+		ToolCallID:     strings.TrimSpace(toolCallID),
+	})
+}
+
+func (m *HITLManager) popApprovedInterruptForTool(conversationID, toolCallID, toolName string) string {
+	if m == nil {
+		return ""
+	}
+	conversationID = strings.TrimSpace(conversationID)
+	toolCallID = strings.TrimSpace(toolCallID)
+	toolName = strings.TrimSpace(toolName)
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	queue := m.approvedExec[conversationID]
+	if len(queue) == 0 {
+		return ""
+	}
+	idx := -1
+	if toolCallID != "" {
+		for i, t := range queue {
+			if t.ToolCallID == toolCallID {
+				idx = i
+				break
+			}
+		}
+	}
+	if idx < 0 && toolName != "" {
+		for i, t := range queue {
+			if strings.EqualFold(t.ToolName, toolName) {
+				idx = i
+				break
+			}
+		}
+	}
+	if idx < 0 {
+		return ""
+	}
+	id := queue[idx].InterruptID
+	queue = append(queue[:idx], queue[idx+1:]...)
+	if len(queue) == 0 {
+		delete(m.approvedExec, conversationID)
+	} else {
+		m.approvedExec[conversationID] = queue
+	}
+	return id
+}
+
+func mergeHitlPayloadExecutionResult(payloadJSON string, exec hitlExecutionResult) (string, error) {
+	root := make(map[string]interface{})
+	if strings.TrimSpace(payloadJSON) != "" {
+		_ = json.Unmarshal([]byte(payloadJSON), &root)
+	}
+	if root == nil {
+		root = make(map[string]interface{})
+	}
+	root[hitlPayloadExecutionResult] = exec
+	out, err := json.Marshal(root)
+	if err != nil {
+		return payloadJSON, err
+	}
+	return string(out), nil
+}
+
+func (h *AgentHandler) recordHitlToolExecutionResult(conversationID, toolCallID, toolName string, success bool, result string) {
+	if h == nil || h.hitlManager == nil || h.db == nil {
+		return
+	}
+	interruptID := h.hitlManager.popApprovedInterruptForTool(conversationID, toolCallID, toolName)
+	if interruptID == "" {
+		return
+	}
+	var payloadJSON string
+	err := h.db.QueryRow(`SELECT payload FROM hitl_interrupts WHERE id = ?`, interruptID).Scan(&payloadJSON)
+	if err != nil {
+		return
+	}
+	merged, err := mergeHitlPayloadExecutionResult(payloadJSON, hitlExecutionResult{
+		Success:    success,
+		Result:     strings.TrimSpace(result),
+		ToolName:   strings.TrimSpace(toolName),
+		ToolCallID: strings.TrimSpace(toolCallID),
+		RecordedAt: time.Now(),
+	})
+	if err != nil {
+		return
+	}
+	_, _ = h.db.Exec(`UPDATE hitl_interrupts SET payload = ? WHERE id = ?`, merged, interruptID)
+}

internal/handler/hitl_execution_test.go

@@ -0,0 +1,39 @@
+package handler
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestMergeHitlPayloadExecutionResult(t *testing.T) {
+	merged, err := mergeHitlPayloadExecutionResult(`{"userMessage":"hi","toolName":"nmap"}`, hitlExecutionResult{
+		Success: true,
+		Result:  "open ports: 80",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var root map[string]interface{}
+	if err := json.Unmarshal([]byte(merged), &root); err != nil {
+		t.Fatal(err)
+	}
+	if root["userMessage"] != "hi" {
+		t.Fatalf("userMessage lost: %v", root["userMessage"])
+	}
+	exec, ok := root["executionResult"].(map[string]interface{})
+	if !ok || exec["success"] != true {
+		t.Fatalf("executionResult missing: %v", root["executionResult"])
+	}
+}
+
+func TestPopApprovedInterruptForTool(t *testing.T) {
+	m := NewHITLManager(nil, nil)
+	m.TrackApprovedHitlExecution("hitl_a", "conv1", "nmap", "tc1")
+	m.TrackApprovedHitlExecution("hitl_b", "conv1", "exec", "")
+	if id := m.popApprovedInterruptForTool("conv1", "tc1", "nmap"); id != "hitl_a" {
+		t.Fatalf("tc1 match=%q", id)
+	}
+	if id := m.popApprovedInterruptForTool("conv1", "", "exec"); id != "hitl_b" {
+		t.Fatalf("tool name match=%q", id)
+	}
+}

internal/handler/hitl_logs.go

@@ -0,0 +1,337 @@
+package handler
+
+import (
+	"database/sql"
+	"errors"
+	"math"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+)
+
+func normalizeHitlReviewer(v string) string {
+	switch strings.ToLower(strings.TrimSpace(v)) {
+	case "audit_agent", "agent", "ai":
+		return "audit_agent"
+	default:
+		return "human"
+	}
+}
+
+func normalizeHitlDecidedBy(v string) string {
+	switch strings.ToLower(strings.TrimSpace(v)) {
+	case "audit_agent", "agent", "ai":
+		return "audit_agent"
+	case "system", "timeout":
+		return "system"
+	case "manual":
+		return "manual"
+	default:
+		return "human"
+	}
+}
+
+func (m *HITLManager) migrateHitlSchemaColumns() {
+	_, _ = m.db.Exec(`ALTER TABLE hitl_interrupts ADD COLUMN decided_by TEXT NOT NULL DEFAULT 'human'`)
+	_, _ = m.db.Exec(`ALTER TABLE hitl_interrupts ADD COLUMN reviewer TEXT NOT NULL DEFAULT 'human'`)
+	_, _ = m.db.Exec(`UPDATE hitl_interrupts SET reviewer='audit_agent'
+		WHERE COALESCE(decided_by, '') IN ('audit_agent', 'agent', 'ai')`)
+	_, _ = m.db.Exec(`ALTER TABLE hitl_conversation_configs ADD COLUMN reviewer TEXT NOT NULL DEFAULT 'human'`)
+}
+
+func hitlInterruptRowToMap(
+	id, cid, mode, toolName, toolCallID, payload, rowStatus, reviewer, decidedBy string,
+	messageID sql.NullString,
+	decision, comment sql.NullString,
+	createdAt time.Time,
+	decidedAt sql.NullTime,
+) map[string]interface{} {
+	msgID := ""
+	if messageID.Valid {
+		msgID = messageID.String
+	}
+	return map[string]interface{}{
+		"id":             id,
+		"conversationId": cid,
+		"messageId":      msgID,
+		"mode":           mode,
+		"toolName":       toolName,
+		"toolCallId":     toolCallID,
+		"payload":        payload,
+		"status":         rowStatus,
+		"reviewer":       reviewer,
+		"decision":       decision.String,
+		"comment":        comment.String,
+		"decidedBy":      decidedBy,
+		"createdAt":      createdAt,
+		"decidedAt": func() interface{} {
+			if decidedAt.Valid {
+				return decidedAt.Time
+			}
+			return nil
+		}(),
+	}
+}
+
+func (h *AgentHandler) buildHitlListQuery(logs bool) (string, []interface{}) {
+	where, args := h.buildHitlLogsWhere(logs)
+	q := `SELECT id, conversation_id, message_id, mode, tool_name, tool_call_id, payload, status, COALESCE(reviewer,'human'), decision, decision_comment, COALESCE(decided_by,'human'), created_at, decided_at FROM hitl_interrupts` + where
+	return q, args
+}
+
+func (h *AgentHandler) buildHitlLogsWhere(logs bool) (string, []interface{}) {
+	q := " WHERE 1=1"
+	args := []interface{}{}
+	if logs {
+		q += " AND status != 'pending'"
+	} else {
+		// 该接口只返回真正等待用户操作的人工审批。Agent 审查即使正在运行，
+		// 也不应触发弹窗、倒计时或项目待审批计数。
+		q += " AND status = 'pending' AND COALESCE(reviewer,'human') = 'human'"
+	}
+	return q, args
+}
+
+func (h *AgentHandler) appendHitlListFilters(q string, args []interface{}, c *gin.Context) (string, []interface{}) {
+	conversationID := strings.TrimSpace(c.Query("conversationId"))
+	toolName := strings.TrimSpace(c.Query("toolName"))
+	decision := strings.TrimSpace(c.Query("decision"))
+	decidedBy := strings.TrimSpace(c.Query("decidedBy"))
+	status := strings.TrimSpace(c.Query("status"))
+	search := strings.TrimSpace(c.Query("q"))
+
+	if conversationID != "" {
+		q += " AND conversation_id = ?"
+		args = append(args, conversationID)
+	}
+	if toolName != "" {
+		q += " AND tool_name LIKE ?"
+		args = append(args, "%"+toolName+"%")
+	}
+	if decision != "" && decision != "all" {
+		q += " AND decision = ?"
+		args = append(args, decision)
+	}
+	if decidedBy != "" && decidedBy != "all" {
+		q += " AND COALESCE(decided_by,'human') = ?"
+		args = append(args, normalizeHitlDecidedBy(decidedBy))
+	}
+	if status != "" && status != "all" {
+		q += " AND status = ?"
+		args = append(args, status)
+	}
+	if search != "" {
+		like := "%" + search + "%"
+		q += " AND (id LIKE ? OR conversation_id LIKE ? OR tool_name LIKE ? OR payload LIKE ? OR COALESCE(decision_comment,'') LIKE ?)"
+		args = append(args, like, like, like, like, like)
+	}
+	return q, args
+}
+
+func (h *AgentHandler) scanHitlInterruptRows(rows *sql.Rows) ([]map[string]interface{}, error) {
+	items := make([]map[string]interface{}, 0)
+	for rows.Next() {
+		var id, cid, mode, toolName, toolCallID, payload, rowStatus, reviewer, decidedBy string
+		var messageID sql.NullString
+		var decision, comment sql.NullString
+		var createdAt time.Time
+		var decidedAt sql.NullTime
+		if err := rows.Scan(&id, &cid, &messageID, &mode, &toolName, &toolCallID, &payload, &rowStatus, &reviewer, &decision, &comment, &decidedBy, &createdAt, &decidedAt); err != nil {
+			continue
+		}
+		items = append(items, hitlInterruptRowToMap(id, cid, mode, toolName, toolCallID, payload, rowStatus, reviewer, decidedBy, messageID, decision, comment, createdAt, decidedAt))
+	}
+	return items, nil
+}
+
+func (h *AgentHandler) countHitlQuery(baseQ string, args []interface{}) (int, error) {
+	countQ := "SELECT COUNT(*) FROM (" + baseQ + ") AS hitl_cnt"
+	var total int
+	if err := h.db.QueryRow(countQ, args...).Scan(&total); err != nil {
+		return 0, err
+	}
+	return total, nil
+}
+
+func (h *AgentHandler) ListHITLLogs(c *gin.Context) {
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	if page < 1 {
+		page = 1
+	}
+	pageSize, _ := strconv.Atoi(c.DefaultQuery("pageSize", "20"))
+	pageSize = int(math.Max(1, math.Min(float64(pageSize), 200)))
+	offset := (page - 1) * pageSize
+
+	q, args := h.buildHitlListQuery(true)
+	q, args = h.appendHitlListFilters(q, args, c)
+	q, args = appendConversationAccessSQL(q, args, "conversation_id", notificationAccessFromContext(c))
+	total, err := h.countHitlQuery(q, args)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	q += " ORDER BY COALESCE(decided_at, created_at) DESC LIMIT ? OFFSET ?"
+	args = append(args, pageSize, offset)
+	rows, err := h.db.Query(q, args...)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	defer rows.Close()
+	items, err := h.scanHitlInterruptRows(rows)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"items": items, "page": page, "pageSize": pageSize, "total": total, "retentionDays": h.hitlRetentionDays()})
+}
+
+func (h *AgentHandler) hitlRetentionDays() int {
+	if h.config != nil {
+		return h.config.Hitl.RetentionDaysEffective()
+	}
+	return config.HitlConfig{}.RetentionDaysEffective()
+}
+
+// DeleteHITLLogs 批量删除或按筛选清空已决策的人机协同审计日志（不删除 pending）。
+func (h *AgentHandler) DeleteHITLLogs(c *gin.Context) {
+	var request struct {
+		IDs []string `json:"ids"`
+		All bool     `json:"all"`
+	}
+	if err := c.ShouldBindJSON(&request); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "请求参数无效: " + err.Error()})
+		return
+	}
+
+	var deleted int64
+	var err error
+	if request.All {
+		where, args := h.buildHitlLogsWhere(true)
+		where, args = h.appendHitlListFilters(where, args, c)
+		where, args = appendConversationAccessSQL(where, args, "conversation_id", notificationAccessFromContext(c))
+		deleted, err = h.db.DeleteHitlInterruptLogsMatching(where, args)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if h.audit != nil {
+			h.audit.RecordOK(c, "hitl", "logs_clear", "清空人机协同审计日志", "hitl_interrupt", "", map[string]interface{}{
+				"deleted": deleted,
+			})
+		}
+	} else {
+		if len(request.IDs) == 0 {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "审计日志 ID 列表不能为空"})
+			return
+		}
+		ids, filterErr := h.filterAllowedHitlInterruptIDs(c, request.IDs)
+		if filterErr != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": filterErr.Error()})
+			return
+		}
+		deleted, err = h.db.DeleteHitlInterruptLogsByIDs(ids)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if h.audit != nil {
+			h.audit.RecordOK(c, "hitl", "logs_delete_batch", "批量删除人机协同审计日志", "hitl_interrupt", "", map[string]interface{}{
+				"count":   len(request.IDs),
+				"deleted": deleted,
+			})
+		}
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "删除成功", "deleted": deleted})
+}
+
+func (h *AgentHandler) GetHITLLog(c *gin.Context) {
+	id := strings.TrimSpace(c.Param("id"))
+	if id == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "id is required"})
+		return
+	}
+	q := `SELECT id, conversation_id, message_id, mode, tool_name, tool_call_id, payload, status, COALESCE(reviewer,'human'), decision, decision_comment, COALESCE(decided_by,'human'), created_at, decided_at FROM hitl_interrupts WHERE id = ?`
+	var rowID, cid, mode, toolName, toolCallID, payload, rowStatus, reviewer, decidedBy string
+	var messageID sql.NullString
+	var decision, comment sql.NullString
+	var createdAt time.Time
+	var decidedAt sql.NullTime
+	err := h.db.QueryRow(q, id).Scan(&rowID, &cid, &messageID, &mode, &toolName, &toolCallID, &payload, &rowStatus, &reviewer, &decision, &comment, &decidedBy, &createdAt, &decidedAt)
+	if errors.Is(err, sql.ErrNoRows) {
+		c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
+		return
+	}
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if !h.hitlConversationAllowed(c, cid) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+	c.JSON(http.StatusOK, hitlInterruptRowToMap(rowID, cid, mode, toolName, toolCallID, payload, rowStatus, reviewer, decidedBy, messageID, decision, comment, createdAt, decidedAt))
+}
+
+func (h *AgentHandler) filterAllowedHitlInterruptIDs(c *gin.Context, ids []string) ([]string, error) {
+	clean := make([]string, 0, len(ids))
+	seen := map[string]struct{}{}
+	for _, id := range ids {
+		id = strings.TrimSpace(id)
+		if id == "" {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		clean = append(clean, id)
+	}
+	if len(clean) == 0 {
+		return clean, nil
+	}
+	query := `SELECT id, conversation_id FROM hitl_interrupts WHERE id IN (` + buildPlaceholders(len(clean)) + `)`
+	args := make([]interface{}, 0, len(clean))
+	for _, id := range clean {
+		args = append(args, id)
+	}
+	rows, err := h.db.Query(query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	allowed := make([]string, 0, len(clean))
+	for rows.Next() {
+		var id, conversationID string
+		if err := rows.Scan(&id, &conversationID); err != nil {
+			continue
+		}
+		if h.hitlConversationAllowed(c, conversationID) {
+			allowed = append(allowed, id)
+		}
+	}
+	return allowed, rows.Err()
+}
+
+func (h *AgentHandler) hitlInterruptAllowed(c *gin.Context, interruptID string) bool {
+	var conversationID string
+	if err := h.db.QueryRow(`SELECT conversation_id FROM hitl_interrupts WHERE id = ?`, strings.TrimSpace(interruptID)).Scan(&conversationID); err != nil {
+		return false
+	}
+	return h.hitlConversationAllowed(c, conversationID)
+}
+
+func (h *AgentHandler) hitlConversationAllowed(c *gin.Context, conversationID string) bool {
+	session, ok := security.CurrentSession(c)
+	if !ok {
+		return false
+	}
+	return h.db.UserCanAccessResource(session.UserID, session.Scope, "conversation", conversationID)
+}

internal/handler/hitl_restart_test.go

@@ -0,0 +1,236 @@
+package handler
+
+import (
+	"database/sql"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"cyberstrike-ai/internal/database"
+
+	"go.uber.org/zap"
+)
+
+func TestEnsureSchemaCancelsPendingInterruptsAfterRestart(t *testing.T) {
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "hitl-restart.db"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+	manager := NewHITLManager(db, zap.NewNop())
+	if err := manager.EnsureSchema(); err != nil {
+		t.Fatalf("ensure schema: %v", err)
+	}
+	conversation, err := db.CreateConversation("restart interrupted", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("create conversation: %v", err)
+	}
+	message, err := db.AddMessage(conversation.ID, "assistant", "处理中...", nil)
+	if err != nil {
+		t.Fatalf("create assistant placeholder: %v", err)
+	}
+	if _, err := db.Exec(`INSERT INTO hitl_interrupts
+		(id, conversation_id, message_id, mode, tool_name, tool_call_id, payload, status, created_at)
+		VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', CURRENT_TIMESTAMP)`,
+		"restart-pending", conversation.ID, message.ID, "approval", "browser", "tool-call-1", `{}`); err != nil {
+		t.Fatalf("insert pending interrupt: %v", err)
+	}
+
+	if err := manager.EnsureSchema(); err != nil {
+		t.Fatalf("reconcile restart: %v", err)
+	}
+
+	var status, decision, comment, decidedBy string
+	var decidedAt sql.NullTime
+	if err := db.QueryRow(`SELECT status, decision, decision_comment, decided_by, decided_at
+		FROM hitl_interrupts WHERE id = ?`, "restart-pending").
+		Scan(&status, &decision, &comment, &decidedBy, &decidedAt); err != nil {
+		t.Fatalf("query reconciled interrupt: %v", err)
+	}
+	if status != "cancelled" || decision != "reject" || comment != "process restarted" {
+		t.Fatalf("unexpected restart decision: status=%q decision=%q comment=%q", status, decision, comment)
+	}
+	if decidedBy != "system" {
+		t.Fatalf("decided_by=%q, want system", decidedBy)
+	}
+	if !decidedAt.Valid {
+		t.Fatal("decided_at should be set after restart reconciliation")
+	}
+
+	var content string
+	var updatedAt sql.NullTime
+	if err := db.QueryRow(`SELECT content, updated_at FROM messages WHERE id = ?`, message.ID).
+		Scan(&content, &updatedAt); err != nil {
+		t.Fatalf("query reconciled assistant message: %v", err)
+	}
+	if content != "任务因服务重启已中断，审批已取消。" {
+		t.Fatalf("assistant content=%q, want restart interruption notice", content)
+	}
+	if !updatedAt.Valid {
+		t.Fatal("assistant updated_at should be set to the interruption time")
+	}
+	var eventType, eventMessage string
+	if err := db.QueryRow(`SELECT event_type, message FROM process_details WHERE message_id = ?`, message.ID).
+		Scan(&eventType, &eventMessage); err != nil {
+		t.Fatalf("query restart cancellation process detail: %v", err)
+	}
+	if eventType != "cancelled" || eventMessage != content {
+		t.Fatalf("unexpected terminal detail: type=%q message=%q", eventType, eventMessage)
+	}
+}
+
+func TestEnsureSchemaFinalizesOnlyHistoricalPlaceholdersWithTerminalEvidence(t *testing.T) {
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "hitl-history.db"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+	manager := NewHITLManager(db, zap.NewNop())
+	if err := manager.EnsureSchema(); err != nil {
+		t.Fatalf("ensure schema: %v", err)
+	}
+
+	supersededConversation, err := db.CreateConversation("superseded placeholder", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("create superseded conversation: %v", err)
+	}
+	superseded, err := db.AddMessage(supersededConversation.ID, "assistant", "处理中...", nil)
+	if err != nil {
+		t.Fatalf("create superseded placeholder: %v", err)
+	}
+	if _, err := db.AddMessage(supersededConversation.ID, "user", "继续", nil); err != nil {
+		t.Fatalf("create later message: %v", err)
+	}
+
+	timeoutConversation, err := db.CreateConversation("timeout placeholder", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("create timeout conversation: %v", err)
+	}
+	timedOut, err := db.AddMessage(timeoutConversation.ID, "assistant", "处理中...", nil)
+	if err != nil {
+		t.Fatalf("create timeout placeholder: %v", err)
+	}
+	if _, err := db.Exec(`INSERT INTO hitl_interrupts
+		(id, conversation_id, message_id, mode, tool_name, status, decision, decision_comment, created_at, decided_at)
+		VALUES (?, ?, ?, 'approval', 'browser', 'timeout', 'reject', 'HITL timeout auto-reject for safety', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`,
+		"timeout-interrupt", timeoutConversation.ID, timedOut.ID); err != nil {
+		t.Fatalf("insert timeout interrupt: %v", err)
+	}
+
+	rejectedConversation, err := db.CreateConversation("rejected placeholder", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("create rejected conversation: %v", err)
+	}
+	rejected, err := db.AddMessage(rejectedConversation.ID, "assistant", "处理中...", nil)
+	if err != nil {
+		t.Fatalf("create rejected placeholder: %v", err)
+	}
+	if _, err := db.Exec(`INSERT INTO hitl_interrupts
+		(id, conversation_id, message_id, mode, tool_name, status, decision, decision_comment, created_at, decided_at)
+		VALUES (?, ?, ?, 'approval', 'exec', 'decided', 'reject', 'user rejected', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`,
+		"rejected-interrupt", rejectedConversation.ID, rejected.ID); err != nil {
+		t.Fatalf("insert rejected interrupt: %v", err)
+	}
+
+	activeConversation, err := db.CreateConversation("potentially active placeholder", database.ConversationCreateMeta{})
+	if err != nil {
+		t.Fatalf("create active conversation: %v", err)
+	}
+	potentiallyActive, err := db.AddMessage(activeConversation.ID, "assistant", "处理中...", nil)
+	if err != nil {
+		t.Fatalf("create potentially active placeholder: %v", err)
+	}
+
+	if err := manager.EnsureSchema(); err != nil {
+		t.Fatalf("reconcile historical placeholders: %v", err)
+	}
+
+	assertTerminal := func(messageID, wantContent, wantEvent string) {
+		t.Helper()
+		var content, eventType string
+		if err := db.QueryRow(`SELECT content FROM messages WHERE id = ?`, messageID).Scan(&content); err != nil {
+			t.Fatalf("query message %s: %v", messageID, err)
+		}
+		if content != wantContent {
+			t.Fatalf("message %s content=%q, want %q", messageID, content, wantContent)
+		}
+		if err := db.QueryRow(`SELECT event_type FROM process_details WHERE message_id = ?
+			AND event_type IN ('cancelled', 'timeout', 'error')`, messageID).Scan(&eventType); err != nil {
+			t.Fatalf("query terminal detail %s: %v", messageID, err)
+		}
+		if eventType != wantEvent {
+			t.Fatalf("message %s event=%q, want %q", messageID, eventType, wantEvent)
+		}
+	}
+	assertTerminal(superseded.ID, "任务因服务重启已中断。", "cancelled")
+	assertTerminal(timedOut.ID, "任务等待审批超时，已自动拒绝。", "timeout")
+	assertTerminal(rejected.ID, "任务审批已拒绝，执行已停止。", "cancelled")
+
+	var activeContent string
+	if err := db.QueryRow(`SELECT content FROM messages WHERE id = ?`, potentiallyActive.ID).Scan(&activeContent); err != nil {
+		t.Fatalf("query potentially active message: %v", err)
+	}
+	if activeContent != "处理中..." {
+		t.Fatalf("potentially active message was rewritten to %q", activeContent)
+	}
+	var terminalCount int
+	if err := db.QueryRow(`SELECT COUNT(*) FROM process_details WHERE message_id = ?
+		AND event_type IN ('cancelled', 'timeout', 'error')`, potentiallyActive.ID).Scan(&terminalCount); err != nil {
+		t.Fatalf("count active terminal details: %v", err)
+	}
+	if terminalCount != 0 {
+		t.Fatalf("potentially active message got %d terminal details", terminalCount)
+	}
+}
+
+func TestAuditAgentInterruptIsNotHumanPendingWork(t *testing.T) {
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "hitl-reviewer.db"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("open db: %v", err)
+	}
+	defer func() { _ = db.Close() }()
+	manager := NewHITLManager(db, zap.NewNop())
+	if err := manager.EnsureSchema(); err != nil {
+		t.Fatalf("ensure schema: %v", err)
+	}
+
+	audit, err := manager.CreatePendingInterrupt("conversation-audit", "message-audit", "review_edit", "exec", "call-audit", `{}`, "audit_agent")
+	if err != nil {
+		t.Fatalf("create audit interrupt: %v", err)
+	}
+	human, err := manager.CreatePendingInterrupt("conversation-human", "message-human", "approval", "exec", "call-human", `{}`, "human")
+	if err != nil {
+		t.Fatalf("create human interrupt: %v", err)
+	}
+
+	manager.mu.RLock()
+	_, auditWaitsForHuman := manager.pending[audit.InterruptID]
+	_, humanWaitsForHuman := manager.pending[human.InterruptID]
+	manager.mu.RUnlock()
+	if auditWaitsForHuman {
+		t.Fatal("audit-agent interrupt must not enter the human pending queue")
+	}
+	if !humanWaitsForHuman {
+		t.Fatal("human interrupt should enter the human pending queue")
+	}
+
+	query, args := (&AgentHandler{}).buildHitlListQuery(false)
+	if len(args) != 0 {
+		t.Fatalf("unexpected pending query args: %v", args)
+	}
+	if !strings.Contains(query, "COALESCE(reviewer,'human') = 'human'") {
+		t.Fatalf("pending query must filter out audit-agent work: %s", query)
+	}
+	rows, err := db.Query(query)
+	if err != nil {
+		t.Fatalf("query human pending interrupts: %v", err)
+	}
+	defer rows.Close()
+	items, err := (&AgentHandler{}).scanHitlInterruptRows(rows)
+	if err != nil {
+		t.Fatalf("scan human pending interrupts: %v", err)
+	}
+	if len(items) != 1 || items[0]["id"] != human.InterruptID || items[0]["reviewer"] != "human" {
+		t.Fatalf("unexpected human pending result: %#v", items)
+	}
+}

internal/handler/hitl_whitelist_test.go

@@ -0,0 +1,21 @@
+package handler
+
+import "testing"
+
+func TestHITLBuiltInWhitelistExemptsWriteFile(t *testing.T) {
+	h := &AgentHandler{}
+	req := h.hitlRequestWithMergedConfigWhitelist(&HITLRequest{
+		Enabled: true,
+		Mode:    "approval",
+	})
+
+	manager := NewHITLManager(nil, nil)
+	manager.ActivateConversation("conversation-1", req)
+
+	if manager.NeedsToolApproval("conversation-1", "write_file") {
+		t.Fatal("write_file should use the built-in HITL exemption")
+	}
+	if !manager.NeedsToolApproval("conversation-1", "exec") {
+		t.Fatal("non-exempt tools should still require approval")
+	}
+}

internal/handler/knowledge.go

@@ -0,0 +1,566 @@
+package handler
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/knowledge"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// KnowledgeHandler 知识库处理器
+type KnowledgeHandler struct {
+	manager   *knowledge.Manager
+	retriever *knowledge.Retriever
+	indexer   *knowledge.Indexer
+	db        *database.DB
+	logger    *zap.Logger
+	audit     *audit.Service
+}
+
+// SetAudit wires platform audit logging.
+func (h *KnowledgeHandler) SetAudit(s *audit.Service) {
+	h.audit = s
+}
+
+// NewKnowledgeHandler 创建新的知识库处理器
+func NewKnowledgeHandler(
+	manager *knowledge.Manager,
+	retriever *knowledge.Retriever,
+	indexer *knowledge.Indexer,
+	db *database.DB,
+	logger *zap.Logger,
+) *KnowledgeHandler {
+	return &KnowledgeHandler{
+		manager:   manager,
+		retriever: retriever,
+		indexer:   indexer,
+		db:        db,
+		logger:    logger,
+	}
+}
+
+// GetCategories 获取所有分类
+func (h *KnowledgeHandler) GetCategories(c *gin.Context) {
+	categories, err := h.manager.GetCategories()
+	if err != nil {
+		h.logger.Error("获取分类失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"categories": categories})
+}
+
+// GetItems 获取知识项列表（支持按分类分页和关键字搜索，默认不返回完整内容）
+func (h *KnowledgeHandler) GetItems(c *gin.Context) {
+	category := c.Query("category")
+	searchKeyword := c.Query("search") // 搜索关键字
+
+	// 如果提供了搜索关键字，执行关键字搜索（在所有数据中搜索）
+	if searchKeyword != "" {
+		items, err := h.manager.SearchItemsByKeyword(searchKeyword, category)
+		if err != nil {
+			h.logger.Error("搜索知识项失败", zap.Error(err))
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+
+		// 按分类分组结果
+		groupedByCategory := make(map[string][]*knowledge.KnowledgeItemSummary)
+		for _, item := range items {
+			cat := item.Category
+			if cat == "" {
+				cat = "未分类"
+			}
+			groupedByCategory[cat] = append(groupedByCategory[cat], item)
+		}
+
+		// 转换为 CategoryWithItems 格式
+		categoriesWithItems := make([]*knowledge.CategoryWithItems, 0, len(groupedByCategory))
+		for cat, catItems := range groupedByCategory {
+			categoriesWithItems = append(categoriesWithItems, &knowledge.CategoryWithItems{
+				Category:  cat,
+				ItemCount: len(catItems),
+				Items:     catItems,
+			})
+		}
+
+		// 按分类名称排序
+		for i := 0; i < len(categoriesWithItems)-1; i++ {
+			for j := i + 1; j < len(categoriesWithItems); j++ {
+				if categoriesWithItems[i].Category > categoriesWithItems[j].Category {
+					categoriesWithItems[i], categoriesWithItems[j] = categoriesWithItems[j], categoriesWithItems[i]
+				}
+			}
+		}
+
+		c.JSON(http.StatusOK, gin.H{
+			"categories": categoriesWithItems,
+			"total":      len(categoriesWithItems),
+			"search":     searchKeyword,
+			"is_search":  true,
+		})
+		return
+	}
+
+	// 分页模式：categoryPage=true 表示按分类分页，否则按项分页（向后兼容）
+	categoryPageMode := c.Query("categoryPage") != "false" // 默认使用分类分页
+
+	// 分页参数
+	limit := 50 // 默认每页 50 条（分类分页时为分类数，项分页时为项数）
+	offset := 0
+	if limitStr := c.Query("limit"); limitStr != "" {
+		if parsed, err := parseInt(limitStr); err == nil && parsed > 0 && parsed <= 500 {
+			limit = parsed
+		}
+	}
+	if offsetStr := c.Query("offset"); offsetStr != "" {
+		if parsed, err := parseInt(offsetStr); err == nil && parsed >= 0 {
+			offset = parsed
+		}
+	}
+
+	// 如果指定了 category 参数，且使用分类分页模式，则只返回该分类
+	if category != "" && categoryPageMode {
+		// 单分类模式：返回该分类的所有知识项（不分页）
+		items, total, err := h.manager.GetItemsSummary(category, 0, 0)
+		if err != nil {
+			h.logger.Error("获取知识项失败", zap.Error(err))
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+
+		// 包装成分类结构
+		categoriesWithItems := []*knowledge.CategoryWithItems{
+			{
+				Category:  category,
+				ItemCount: total,
+				Items:     items,
+			},
+		}
+
+		c.JSON(http.StatusOK, gin.H{
+			"categories": categoriesWithItems,
+			"total":      1, // 只有一个分类
+			"limit":      limit,
+			"offset":     offset,
+		})
+		return
+	}
+
+	if categoryPageMode {
+		// 按分类分页模式（默认）
+		// limit 表示每页分类数，推荐 5-10 个分类
+		if limit <= 0 || limit > 100 {
+			limit = 10 // 默认每页 10 个分类
+		}
+
+		categoriesWithItems, totalCategories, err := h.manager.GetCategoriesWithItems(limit, offset)
+		if err != nil {
+			h.logger.Error("获取分类知识项失败", zap.Error(err))
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+
+		c.JSON(http.StatusOK, gin.H{
+			"categories": categoriesWithItems,
+			"total":      totalCategories,
+			"limit":      limit,
+			"offset":     offset,
+		})
+		return
+	}
+
+	// 按项分页模式（向后兼容）
+	// 是否包含完整内容（默认 false，只返回摘要）
+	includeContent := c.Query("includeContent") == "true"
+
+	if includeContent {
+		// 返回完整内容（向后兼容）
+		items, err := h.manager.GetItemsWithOptions(category, limit, offset, true)
+		if err != nil {
+			h.logger.Error("获取知识项失败", zap.Error(err))
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+
+		// 获取总数
+		total, err := h.manager.GetItemsCount(category)
+		if err != nil {
+			h.logger.Warn("获取知识项总数失败", zap.Error(err))
+			total = len(items)
+		}
+
+		c.JSON(http.StatusOK, gin.H{
+			"items":  items,
+			"total":  total,
+			"limit":  limit,
+			"offset": offset,
+		})
+	} else {
+		// 返回摘要（不包含完整内容，推荐方式）
+		items, total, err := h.manager.GetItemsSummary(category, limit, offset)
+		if err != nil {
+			h.logger.Error("获取知识项失败", zap.Error(err))
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+
+		c.JSON(http.StatusOK, gin.H{
+			"items":  items,
+			"total":  total,
+			"limit":  limit,
+			"offset": offset,
+		})
+	}
+}
+
+// GetItem 获取单个知识项
+func (h *KnowledgeHandler) GetItem(c *gin.Context) {
+	id := c.Param("id")
+
+	item, err := h.manager.GetItem(id)
+	if err != nil {
+		h.logger.Error("获取知识项失败", zap.Error(err))
+		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, item)
+}
+
+// CreateItem 创建知识项
+func (h *KnowledgeHandler) CreateItem(c *gin.Context) {
+	var req struct {
+		Category string `json:"category" binding:"required"`
+		Title    string `json:"title" binding:"required"`
+		Content  string `json:"content" binding:"required"`
+	}
+
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	item, err := h.manager.CreateItem(req.Category, req.Title, req.Content)
+	if err != nil {
+		h.logger.Error("创建知识项失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// 异步索引
+	go func() {
+		ctx := context.Background()
+		if err := h.indexer.IndexItem(ctx, item.ID); err != nil {
+			h.logger.Warn("索引知识项失败", zap.String("itemId", item.ID), zap.Error(err))
+		}
+	}()
+
+	c.JSON(http.StatusOK, item)
+}
+
+// UpdateItem 更新知识项
+func (h *KnowledgeHandler) UpdateItem(c *gin.Context) {
+	id := c.Param("id")
+
+	var req struct {
+		Category string `json:"category" binding:"required"`
+		Title    string `json:"title" binding:"required"`
+		Content  string `json:"content" binding:"required"`
+	}
+
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	item, err := h.manager.UpdateItem(id, req.Category, req.Title, req.Content)
+	if err != nil {
+		h.logger.Error("更新知识项失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// 异步重新索引
+	go func() {
+		ctx := context.Background()
+		if err := h.indexer.IndexItem(ctx, item.ID); err != nil {
+			h.logger.Warn("重新索引知识项失败", zap.String("itemId", item.ID), zap.Error(err))
+		}
+	}()
+
+	c.JSON(http.StatusOK, item)
+}
+
+// DeleteItem 删除知识项
+func (h *KnowledgeHandler) DeleteItem(c *gin.Context) {
+	id := c.Param("id")
+
+	if err := h.manager.DeleteItem(id); err != nil {
+		h.logger.Error("删除知识项失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	if h.audit != nil {
+		h.audit.RecordOK(c, "knowledge", "item_delete", "删除知识项", "knowledge_item", id, nil)
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "删除成功"})
+}
+
+// StartIndex 构建知识库向量索引。默认仅补齐尚无向量的知识项；mode=full 时全量重建。
+func (h *KnowledgeHandler) StartIndex(c *gin.Context) {
+	if err := h.indexer.TryBeginIndexRun(); err != nil {
+		c.JSON(http.StatusConflict, gin.H{"error": "已有索引任务正在进行，请等待完成"})
+		return
+	}
+
+	mode := strings.TrimSpace(c.Query("mode"))
+	if mode == "" {
+		mode = "missing"
+	}
+	if mode != "full" && mode != "missing" {
+		h.indexer.FinishIndexRun()
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的 mode 参数，可选值：missing、full"})
+		return
+	}
+
+	fullRebuild := mode == "full"
+	message := "索引构建已开始，将在后台进行"
+	auditAction := "index_build"
+	auditDetail := "构建知识库索引"
+	if fullRebuild {
+		message = "全量索引重建已开始，将在后台进行"
+		auditAction = "index_rebuild_full"
+		auditDetail = "全量重建知识库索引"
+	}
+
+	go func() {
+		defer h.indexer.FinishIndexRun()
+		ctx := context.Background()
+		var err error
+		if fullRebuild {
+			err = h.indexer.RunRebuildIndex(ctx)
+		} else {
+			err = h.indexer.RunIndexMissing(ctx)
+		}
+		if err != nil {
+			if fullRebuild {
+				h.logger.Error("全量重建索引失败", zap.Error(err))
+			} else {
+				h.logger.Error("构建知识库索引失败", zap.Error(err))
+			}
+		}
+	}()
+
+	if h.audit != nil {
+		h.audit.RecordOK(c, "knowledge", auditAction, auditDetail, "knowledge", "", nil)
+	}
+	c.JSON(http.StatusOK, gin.H{"message": message, "mode": mode})
+}
+
+// ScanKnowledgeBase 扫描知识库
+func (h *KnowledgeHandler) ScanKnowledgeBase(c *gin.Context) {
+	itemsToIndex, err := h.manager.ScanKnowledgeBase()
+	if err != nil {
+		h.logger.Error("扫描知识库失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	if len(itemsToIndex) == 0 {
+		c.JSON(http.StatusOK, gin.H{"message": "扫描完成，没有需要索引的新项或更新项"})
+		return
+	}
+
+	// 异步索引新添加或更新的项（增量索引）
+	go func() {
+		ctx := context.Background()
+		h.logger.Info("开始增量索引", zap.Int("count", len(itemsToIndex)))
+		failedCount := 0
+		consecutiveFailures := 0
+		var firstFailureItemID string
+		var firstFailureError error
+
+		for i, itemID := range itemsToIndex {
+			if err := h.indexer.IndexItem(ctx, itemID); err != nil {
+				failedCount++
+				consecutiveFailures++
+
+				// 只在第一个失败时记录详细日志
+				if consecutiveFailures == 1 {
+					firstFailureItemID = itemID
+					firstFailureError = err
+					h.logger.Warn("索引知识项失败",
+						zap.String("itemId", itemID),
+						zap.Int("totalItems", len(itemsToIndex)),
+						zap.Error(err),
+					)
+				}
+
+				// 如果连续失败 2 次，立即停止增量索引
+				if consecutiveFailures >= 2 {
+					h.logger.Error("连续索引失败次数过多，立即停止增量索引",
+						zap.Int("consecutiveFailures", consecutiveFailures),
+						zap.Int("totalItems", len(itemsToIndex)),
+						zap.Int("processedItems", i+1),
+						zap.String("firstFailureItemId", firstFailureItemID),
+						zap.Error(firstFailureError),
+					)
+					break
+				}
+				continue
+			}
+
+			// 成功时重置连续失败计数
+			if consecutiveFailures > 0 {
+				consecutiveFailures = 0
+				firstFailureItemID = ""
+				firstFailureError = nil
+			}
+
+			// 减少进度日志频率
+			if (i+1)%10 == 0 || i+1 == len(itemsToIndex) {
+				h.logger.Info("索引进度", zap.Int("current", i+1), zap.Int("total", len(itemsToIndex)), zap.Int("failed", failedCount))
+			}
+		}
+		h.logger.Info("增量索引完成", zap.Int("totalItems", len(itemsToIndex)), zap.Int("failedCount", failedCount))
+	}()
+
+	c.JSON(http.StatusOK, gin.H{
+		"message":        fmt.Sprintf("扫描完成，开始索引 %d 个新添加或更新的知识项", len(itemsToIndex)),
+		"items_to_index": len(itemsToIndex),
+	})
+}
+
+// GetRetrievalLogs 获取检索日志
+func (h *KnowledgeHandler) GetRetrievalLogs(c *gin.Context) {
+	conversationID := c.Query("conversationId")
+	messageID := c.Query("messageId")
+	limit := 50 // 默认 50 条
+
+	if limitStr := c.Query("limit"); limitStr != "" {
+		if parsed, err := parseInt(limitStr); err == nil && parsed > 0 {
+			limit = parsed
+		}
+	}
+
+	logs, err := h.manager.GetRetrievalLogs(conversationID, messageID, limit)
+	if err != nil {
+		h.logger.Error("获取检索日志失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"logs": logs})
+}
+
+// DeleteRetrievalLog 删除检索日志
+func (h *KnowledgeHandler) DeleteRetrievalLog(c *gin.Context) {
+	id := c.Param("id")
+
+	if err := h.manager.DeleteRetrievalLog(id); err != nil {
+		h.logger.Error("删除检索日志失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "删除成功"})
+}
+
+// GetIndexStatus 获取索引状态
+func (h *KnowledgeHandler) GetIndexStatus(c *gin.Context) {
+	status, err := h.manager.GetIndexStatus()
+	if err != nil {
+		h.logger.Error("获取索引状态失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// 获取索引器的错误信息
+	if h.indexer != nil {
+		lastError, lastErrorTime := h.indexer.GetLastError()
+		if lastError != "" {
+			// 如果错误是最近发生的（5 分钟内），则返回错误信息
+			if time.Since(lastErrorTime) < 5*time.Minute {
+				status["last_error"] = lastError
+				status["last_error_time"] = lastErrorTime.Format(time.RFC3339)
+			}
+		}
+
+		// 获取重建索引状态
+		isRebuilding, totalItems, current, failed, lastItemID, lastChunks, startTime := h.indexer.GetRebuildStatus()
+		if isRebuilding {
+			status["is_rebuilding"] = true
+			status["rebuild_total"] = totalItems
+			status["rebuild_current"] = current
+			status["rebuild_failed"] = failed
+			status["rebuild_start_time"] = startTime.Format(time.RFC3339)
+			if lastItemID != "" {
+				status["rebuild_last_item_id"] = lastItemID
+			}
+			if lastChunks > 0 {
+				status["rebuild_last_chunks"] = lastChunks
+			}
+			// 重建中时，is_complete 为 false
+			status["is_complete"] = false
+			// 计算重建进度百分比
+			if totalItems > 0 {
+				status["progress_percent"] = float64(current) / float64(totalItems) * 100
+			}
+		}
+	}
+
+	c.JSON(http.StatusOK, status)
+}
+
+// Search 搜索知识库（用于 API 调用，Agent 内部使用 Retriever）
+func (h *KnowledgeHandler) Search(c *gin.Context) {
+	var req knowledge.SearchRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	// Retriever.Search 经 Eino VectorEinoRetriever，与 MCP 工具链一致。
+	results, err := h.retriever.Search(c.Request.Context(), &req)
+	if err != nil {
+		h.logger.Error("搜索知识库失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"results": results})
+}
+
+// GetStats 获取知识库统计信息
+func (h *KnowledgeHandler) GetStats(c *gin.Context) {
+	totalCategories, totalItems, err := h.manager.GetStats()
+	if err != nil {
+		h.logger.Error("获取知识库统计信息失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"enabled":          true,
+		"total_categories": totalCategories,
+		"total_items":      totalItems,
+	})
+}
+
+// 辅助函数：解析整数
+func parseInt(s string) (int, error) {
+	var result int
+	_, err := fmt.Sscanf(s, "%d", &result)
+	return result, err
+}

internal/handler/markdown_agents.go

@@ -0,0 +1,333 @@
+package handler
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"cyberstrike-ai/internal/agents"
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/config"
+
+	"github.com/gin-gonic/gin"
+)
+
+var markdownAgentFilenameRe = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9_.-]*\.md$`)
+
+// MarkdownAgentsHandler 管理 agents 目录下子代理 Markdown（增删改查）。
+type MarkdownAgentsHandler struct {
+	dir   string
+	audit *audit.Service
+}
+
+// NewMarkdownAgentsHandler dir 须为已解析的绝对路径。
+func NewMarkdownAgentsHandler(dir string) *MarkdownAgentsHandler {
+	return &MarkdownAgentsHandler{dir: strings.TrimSpace(dir)}
+}
+
+// SetAudit wires platform audit logging.
+func (h *MarkdownAgentsHandler) SetAudit(s *audit.Service) {
+	h.audit = s
+}
+
+func (h *MarkdownAgentsHandler) safeJoin(filename string) (string, error) {
+	filename = strings.TrimSpace(filename)
+	if filename == "" || !markdownAgentFilenameRe.MatchString(filename) {
+		return "", fmt.Errorf("非法文件名")
+	}
+	clean := filepath.Clean(filename)
+	if clean != filename || strings.Contains(clean, "..") {
+		return "", fmt.Errorf("非法文件名")
+	}
+	return filepath.Join(h.dir, clean), nil
+}
+
+// existingOtherOrchestrator 若目录中已有同槽位的其他主代理文件，返回其文件名；writingBasename 为当前正在写入的文件名时不冲突。
+func existingOtherOrchestrator(dir, writingBasename string) (other string, err error) {
+	load, err := agents.LoadMarkdownAgentsDir(dir)
+	if err != nil {
+		return "", err
+	}
+	wb := filepath.Base(strings.TrimSpace(writingBasename))
+	switch agents.OrchestratorMarkdownKind(wb) {
+	case "plan_execute":
+		if load.OrchestratorPlanExecute != nil && !strings.EqualFold(load.OrchestratorPlanExecute.Filename, wb) {
+			return load.OrchestratorPlanExecute.Filename, nil
+		}
+	case "supervisor":
+		if load.OrchestratorSupervisor != nil && !strings.EqualFold(load.OrchestratorSupervisor.Filename, wb) {
+			return load.OrchestratorSupervisor.Filename, nil
+		}
+	case "deep":
+		if load.Orchestrator != nil && !strings.EqualFold(load.Orchestrator.Filename, wb) {
+			return load.Orchestrator.Filename, nil
+		}
+	default:
+		if load.Orchestrator != nil && !strings.EqualFold(load.Orchestrator.Filename, wb) {
+			return load.Orchestrator.Filename, nil
+		}
+	}
+	return "", nil
+}
+
+// ListMarkdownAgents GET /api/multi-agent/markdown-agents
+func (h *MarkdownAgentsHandler) ListMarkdownAgents(c *gin.Context) {
+	if h.dir == "" {
+		c.JSON(http.StatusOK, gin.H{"agents": []any{}, "dir": "", "error": "未配置 agents 目录"})
+		return
+	}
+	files, err := agents.LoadMarkdownAgentFiles(h.dir)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	out := make([]gin.H, 0, len(files))
+	for _, fa := range files {
+		sub := fa.Config
+		out = append(out, gin.H{
+			"filename":        fa.Filename,
+			"id":              sub.ID,
+			"name":            sub.Name,
+			"description":     sub.Description,
+			"is_orchestrator": fa.IsOrchestrator,
+			"kind":            sub.Kind,
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{"agents": out, "dir": h.dir})
+}
+
+// GetMarkdownAgent GET /api/multi-agent/markdown-agents/:filename
+func (h *MarkdownAgentsHandler) GetMarkdownAgent(c *gin.Context) {
+	filename := c.Param("filename")
+	path, err := h.safeJoin(filename)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	b, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			c.JSON(http.StatusNotFound, gin.H{"error": "文件不存在"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	sub, err := agents.ParseMarkdownSubAgent(filename, string(b))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	isOrch := agents.IsOrchestratorLikeMarkdown(filename, sub.Kind)
+	c.JSON(http.StatusOK, gin.H{
+		"filename":        filename,
+		"raw":             string(b),
+		"id":              sub.ID,
+		"name":            sub.Name,
+		"description":     sub.Description,
+		"tools":           sub.RoleTools,
+		"instruction":     sub.Instruction,
+		"bind_role":       sub.BindRole,
+		"max_iterations":  sub.MaxIterations,
+		"kind":            sub.Kind,
+		"is_orchestrator": isOrch,
+	})
+}
+
+type markdownAgentBody struct {
+	Filename      string   `json:"filename"`
+	ID            string   `json:"id"`
+	Name          string   `json:"name"`
+	Description   string   `json:"description"`
+	Tools         []string `json:"tools"`
+	Instruction   string   `json:"instruction"`
+	BindRole      string   `json:"bind_role"`
+	MaxIterations int      `json:"max_iterations"`
+	Kind          string   `json:"kind"`
+	Raw           string   `json:"raw"`
+}
+
+// CreateMarkdownAgent POST /api/multi-agent/markdown-agents
+func (h *MarkdownAgentsHandler) CreateMarkdownAgent(c *gin.Context) {
+	if h.dir == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "未配置 agents 目录"})
+		return
+	}
+	var body markdownAgentBody
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	filename := strings.TrimSpace(body.Filename)
+	if filename == "" {
+		if strings.EqualFold(strings.TrimSpace(body.Kind), "orchestrator") {
+			filename = agents.OrchestratorMarkdownFilename
+		} else {
+			base := agents.SlugID(body.Name)
+			if base == "" {
+				base = "agent"
+			}
+			filename = base + ".md"
+		}
+	}
+	path, err := h.safeJoin(filename)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if _, err := os.Stat(path); err == nil {
+		c.JSON(http.StatusConflict, gin.H{"error": "文件已存在"})
+		return
+	}
+	sub := config.MultiAgentSubConfig{
+		ID:            strings.TrimSpace(body.ID),
+		Name:          strings.TrimSpace(body.Name),
+		Description:   strings.TrimSpace(body.Description),
+		Instruction:   strings.TrimSpace(body.Instruction),
+		RoleTools:     body.Tools,
+		BindRole:      strings.TrimSpace(body.BindRole),
+		MaxIterations: body.MaxIterations,
+		Kind:          strings.TrimSpace(body.Kind),
+	}
+	base := filepath.Base(path)
+	if (strings.EqualFold(base, agents.OrchestratorMarkdownFilename) ||
+		strings.EqualFold(base, agents.OrchestratorPlanExecuteMarkdownFilename) ||
+		strings.EqualFold(base, agents.OrchestratorSupervisorMarkdownFilename)) && sub.Kind == "" {
+		sub.Kind = "orchestrator"
+	}
+	if sub.ID == "" {
+		sub.ID = agents.SlugID(sub.Name)
+	}
+	if sub.Name == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name 必填"})
+		return
+	}
+	var out []byte
+	if strings.TrimSpace(body.Raw) != "" {
+		out = []byte(body.Raw)
+	} else {
+		out, err = agents.BuildMarkdownFile(sub)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+	}
+	if want := agents.WantsMarkdownOrchestrator(filepath.Base(path), body.Kind, string(out)); want {
+		other, oerr := existingOtherOrchestrator(h.dir, filepath.Base(path))
+		if oerr != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": oerr.Error()})
+			return
+		}
+		if other != "" {
+			c.JSON(http.StatusConflict, gin.H{"error": fmt.Sprintf("已存在主代理定义：%s，请先删除或取消其主代理标记", other)})
+			return
+		}
+	}
+	if err := os.MkdirAll(h.dir, 0755); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if err := os.WriteFile(path, out, 0644); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "agent", "markdown_create", "创建 Markdown 子代理", "markdown_agent", filepath.Base(path), nil)
+	}
+	c.JSON(http.StatusOK, gin.H{"filename": filepath.Base(path), "message": "已创建"})
+}
+
+// UpdateMarkdownAgent PUT /api/multi-agent/markdown-agents/:filename
+func (h *MarkdownAgentsHandler) UpdateMarkdownAgent(c *gin.Context) {
+	filename := c.Param("filename")
+	path, err := h.safeJoin(filename)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	var body markdownAgentBody
+	if err := c.ShouldBindJSON(&body); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	sub := config.MultiAgentSubConfig{
+		ID:            strings.TrimSpace(body.ID),
+		Name:          strings.TrimSpace(body.Name),
+		Description:   strings.TrimSpace(body.Description),
+		Instruction:   strings.TrimSpace(body.Instruction),
+		RoleTools:     body.Tools,
+		BindRole:      strings.TrimSpace(body.BindRole),
+		MaxIterations: body.MaxIterations,
+		Kind:          strings.TrimSpace(body.Kind),
+	}
+	if (strings.EqualFold(filename, agents.OrchestratorMarkdownFilename) ||
+		strings.EqualFold(filename, agents.OrchestratorPlanExecuteMarkdownFilename) ||
+		strings.EqualFold(filename, agents.OrchestratorSupervisorMarkdownFilename)) && sub.Kind == "" {
+		sub.Kind = "orchestrator"
+	}
+	if sub.Name == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "name 必填"})
+		return
+	}
+	if sub.ID == "" {
+		sub.ID = agents.SlugID(sub.Name)
+	}
+	var out []byte
+	if strings.TrimSpace(body.Raw) != "" {
+		out = []byte(body.Raw)
+	} else {
+		out, err = agents.BuildMarkdownFile(sub)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+	}
+	if want := agents.WantsMarkdownOrchestrator(filename, body.Kind, string(out)); want {
+		other, oerr := existingOtherOrchestrator(h.dir, filename)
+		if oerr != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": oerr.Error()})
+			return
+		}
+		if other != "" {
+			c.JSON(http.StatusConflict, gin.H{"error": fmt.Sprintf("已存在主代理定义：%s，请先删除或取消其主代理标记", other)})
+			return
+		}
+	}
+	if err := os.WriteFile(path, out, 0644); err != nil {
+		if os.IsNotExist(err) {
+			c.JSON(http.StatusNotFound, gin.H{"error": "文件不存在"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "agent", "markdown_update", "更新 Markdown 子代理", "markdown_agent", filename, nil)
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "已保存"})
+}
+
+// DeleteMarkdownAgent DELETE /api/multi-agent/markdown-agents/:filename
+func (h *MarkdownAgentsHandler) DeleteMarkdownAgent(c *gin.Context) {
+	filename := c.Param("filename")
+	path, err := h.safeJoin(filename)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if err := os.Remove(path); err != nil {
+		if os.IsNotExist(err) {
+			c.JSON(http.StatusNotFound, gin.H{"error": "文件不存在"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "agent", "markdown_delete", "删除 Markdown 子代理", "markdown_agent", filename, nil)
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "已删除"})
+}

internal/handler/multi_agent.go

@@ -0,0 +1,628 @@
+package handler
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"cyberstrike-ai/internal/agentfinalizer"
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/mcp"
+	"cyberstrike-ai/internal/multiagent"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// MultiAgentLoopStream Eino DeepAgent 流式对话（需 config.multi_agent.enabled）。
+func (h *AgentHandler) MultiAgentLoopStream(c *gin.Context) {
+	c.Header("Content-Type", "text/event-stream; charset=utf-8")
+	c.Header("Cache-Control", "no-cache")
+	c.Header("Connection", "keep-alive")
+	if h.config == nil || !h.config.MultiAgent.Enabled {
+		ev := StreamEvent{Type: "error", Message: "多代理未启用，请在设置或 config.yaml 中开启 multi_agent.enabled"}
+		b, _ := json.Marshal(ev)
+		fmt.Fprintf(c.Writer, "data: %s\n\n", b)
+		done := StreamEvent{Type: "done", Message: ""}
+		db, _ := json.Marshal(done)
+		fmt.Fprintf(c.Writer, "data: %s\n\n", db)
+		if flusher, ok := c.Writer.(http.Flusher); ok {
+			flusher.Flush()
+		}
+		return
+	}
+
+	var req ChatRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		event := StreamEvent{Type: "error", Message: "请求参数错误: " + err.Error()}
+		b, _ := json.Marshal(event)
+		fmt.Fprintf(c.Writer, "data: %s\n\n", b)
+		done := StreamEvent{Type: "done", Message: ""}
+		db, _ := json.Marshal(done)
+		fmt.Fprintf(c.Writer, "data: %s\n\n", db)
+		c.Writer.Flush()
+		return
+	}
+
+	c.Header("X-Accel-Buffering", "no")
+
+	// 用于在 sendEvent 中判断是否为用户主动停止导致的取消。
+	// 注意：baseCtx 会在后面创建；该变量用于闭包提前捕获引用。
+	var baseCtx context.Context
+
+	clientDisconnected := false
+	// 与 sseKeepalive 共用：禁止并发写 ResponseWriter，否则会破坏 chunked 编码（ERR_INVALID_CHUNKED_ENCODING）。
+	var sseWriteMu sync.Mutex
+	var ssePublishConversationID string
+	sendEvent := func(eventType, message string, data interface{}) {
+		// 用户主动停止时，Eino 可能仍会并发上报 eventType=="error"。
+		// 为避免 UI 看到“取消错误 + cancelled 文案”两条回复，这里直接丢弃取消对应的 error。
+		if eventType == "error" && baseCtx != nil {
+			cause := context.Cause(baseCtx)
+			if errors.Is(cause, ErrTaskCancelled) || errors.Is(cause, multiagent.ErrInterruptContinue) {
+				return
+			}
+		}
+		ev := StreamEvent{Type: eventType, Message: message, Data: data}
+		b, errMarshal := json.Marshal(ev)
+		if errMarshal != nil {
+			b = []byte(`{"type":"error","message":"marshal failed"}`)
+		}
+		sseLine := make([]byte, 0, len(b)+8)
+		sseLine = append(sseLine, []byte("data: ")...)
+		sseLine = append(sseLine, b...)
+		sseLine = append(sseLine, '\n', '\n')
+		if ssePublishConversationID != "" && h.taskEventBus != nil {
+			h.taskEventBus.Publish(ssePublishConversationID, sseLine)
+		}
+		if clientDisconnected {
+			return
+		}
+		select {
+		case <-c.Request.Context().Done():
+			clientDisconnected = true
+			return
+		default:
+		}
+		sseWriteMu.Lock()
+		_, err := c.Writer.Write(sseLine)
+		if err != nil {
+			sseWriteMu.Unlock()
+			clientDisconnected = true
+			return
+		}
+		if flusher, ok := c.Writer.(http.Flusher); ok {
+			flusher.Flush()
+		} else {
+			c.Writer.Flush()
+		}
+		sseWriteMu.Unlock()
+	}
+
+	h.logger.Info("收到 Eino DeepAgent 流式请求",
+		zap.String("conversationId", req.ConversationID),
+	)
+
+	prep, err := h.prepareMultiAgentSession(&req, c, "multi_agent_stream")
+	if err != nil {
+		sendEvent("error", err.Error(), nil)
+		sendEvent("done", "", nil)
+		return
+	}
+	ssePublishConversationID = prep.ConversationID
+	if prep.CreatedNew {
+		sendEvent("conversation", "会话已创建", map[string]interface{}{
+			"conversationId": prep.ConversationID,
+		})
+	}
+
+	conversationID := prep.ConversationID
+	assistantMessageID := prep.AssistantMessageID
+	h.activateHITLForConversation(conversationID, req.Hitl)
+	if h.hitlManager != nil {
+		defer h.hitlManager.DeactivateConversation(conversationID)
+	}
+
+	if prep.UserMessageID != "" {
+		sendEvent("message_saved", "", map[string]interface{}{
+			"conversationId": conversationID,
+			"userMessageId":  prep.UserMessageID,
+		})
+	}
+	if h.runRoleWorkflowStreamIfBound(c, &req, prep, sendEvent) {
+		return
+	}
+
+	var cancelWithCause context.CancelCauseFunc
+	curFinalMessage := prep.FinalMessage
+	curHistory := prep.History
+	roleTools := prep.RoleTools
+	orch := strings.TrimSpace(req.Orchestration)
+
+	taskStatus := "completed"
+	// 仅在成功 StartTask 后再 FinishTask；避免「任务已存在」分支 return 时误删正在运行的同会话任务。
+	taskOwned := false
+	defer func() {
+		if taskOwned {
+			h.tasks.FinishTask(conversationID, taskStatus)
+		}
+	}()
+
+	sendEvent("progress", "正在启动 Eino 多代理...", map[string]interface{}{
+		"conversationId": conversationID,
+	})
+
+	stopKeepalive := runSSEKeepalive(c, &sseWriteMu)
+	defer stopKeepalive()
+	runCfg, _, err := h.configForAIChannel(req.AIChannelID)
+	if err != nil {
+		sendEvent("error", err.Error(), nil)
+		sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+		return
+	}
+
+	var result *multiagent.RunResult
+	var runErr error
+
+	baseCtx, cancelWithCause = context.WithCancelCause(detachedAgentContext(c.Request.Context()))
+	taskCtx, timeoutCancel := context.WithTimeout(baseCtx, 600*time.Minute)
+
+	if _, err := h.tasks.StartTask(conversationID, req.Message, cancelWithCause); err != nil {
+		var errorMsg string
+		if errors.Is(err, ErrTaskAlreadyRunning) {
+			errorMsg = "⚠️ 当前会话已有任务正在执行中，请等待当前任务完成或点击「停止任务」后再尝试。"
+			sendEvent("error", errorMsg, map[string]interface{}{
+				"conversationId": conversationID,
+				"errorType":      "task_already_running",
+			})
+		} else {
+			errorMsg = "❌ 无法启动任务: " + err.Error()
+			sendEvent("error", errorMsg, nil)
+		}
+		if assistantMessageID != "" {
+			_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", errorMsg, time.Now(), assistantMessageID)
+		}
+		sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+		timeoutCancel()
+		return
+	}
+	taskOwned = true
+
+	// 同一 HTTP 流内多段 Run（如中断并继续）合并 MCP execution id，供最终 response / 库表与工具芯片展示完整列表
+	var cumulativeMCPExecutionIDs []string
+	// 同一请求内分段续跑时，主代理 iteration 事件按偏移累计，避免 UI 出现「第3轮 → 第1轮」回跳。
+	var mainIterationOffset int
+	var emptyResponseContinueAttempt int
+	var finalizationAutoContinueAttempt int
+	effectiveOrch := config.NormalizeMultiAgentOrchestration(h.config.MultiAgent.Orchestration)
+	if o := strings.TrimSpace(req.Orchestration); o != "" {
+		effectiveOrch = config.NormalizeMultiAgentOrchestration(o)
+	}
+	agentMode := "eino_" + effectiveOrch
+	var decision agentfinalizer.Decision
+
+	for {
+		segmentMainIterationMax := 0
+		rawProgressCallback := h.createProgressCallback(taskCtx, cancelWithCause, conversationID, assistantMessageID, sendEvent)
+		progressCallback := func(eventType, message string, data interface{}) {
+			if eventType == "iteration" {
+				if m, ok := data.(map[string]interface{}); ok {
+					if scope, _ := m["einoScope"].(string); scope == "main" {
+						raw := 0
+						switch v := m["iteration"].(type) {
+						case int:
+							raw = v
+						case int32:
+							raw = int(v)
+						case int64:
+							raw = int(v)
+						case float64:
+							raw = int(v)
+						case float32:
+							raw = int(v)
+						}
+						if raw > 0 {
+							if raw > segmentMainIterationMax {
+								segmentMainIterationMax = raw
+							}
+							m["iteration"] = raw + mainIterationOffset
+						}
+					}
+				}
+			}
+			rawProgressCallback(eventType, message, data)
+		}
+		taskCtxLoop := mcp.WithMCPConversationID(taskCtx, conversationID)
+		taskCtxLoop = mcp.WithToolRunRegistry(taskCtxLoop, h.tasks)
+		taskCtxLoop = mcp.WithEinoExecuteRunRegistry(taskCtxLoop, h.tasks)
+		taskCtxLoop = multiagent.WithAgentRuntimeCancelRegistrar(taskCtxLoop, func(cancel func(error) bool) func() {
+			return h.tasks.BindAgentRuntimeCancel(conversationID, cancel)
+		})
+		taskCtxLoop = multiagent.WithAgentTurnLoopInterruptRegistrar(taskCtxLoop, func(push func(string) bool) func() {
+			return h.tasks.BindAgentTurnLoopInterrupt(conversationID, push)
+		})
+		taskCtxLoop = multiagent.WithHITLToolInterceptor(taskCtxLoop, func(ctx context.Context, toolName, arguments string) (string, error) {
+			return h.interceptHITLForEinoTool(ctx, cancelWithCause, conversationID, assistantMessageID, sendEvent, toolName, arguments)
+		})
+
+		result, runErr = multiagent.RunDeepAgent(
+			taskCtxLoop,
+			runCfg,
+			&runCfg.MultiAgent,
+			h.agent,
+			h.db,
+			h.logger,
+			conversationID,
+			h.conversationProjectID(conversationID),
+			curFinalMessage,
+			curHistory,
+			roleTools,
+			progressCallback,
+			h.agentsMarkdownDir,
+			orch,
+			chatReasoningToClientIntent(req.Reasoning),
+			h.agentSessionContextBlock(conversationID),
+		)
+
+		if result != nil && len(result.MCPExecutionIDs) > 0 {
+			cumulativeMCPExecutionIDs = mergeMCPExecutionIDLists(cumulativeMCPExecutionIDs, result.MCPExecutionIDs)
+		}
+
+		if runErr == nil {
+			mw := &h.config.MultiAgent.EinoMiddleware
+			if h.tryContinueOnEinoEmptyResponse(taskCtx, mw, conversationID, result, &emptyResponseContinueAttempt, &curHistory, &curFinalMessage, progressCallback) {
+				mainIterationOffset += segmentMainIterationMax
+				timeoutCancel()
+				baseCtx, cancelWithCause, taskCtx, timeoutCancel = h.rebindEinoRunningTask(taskCtx, conversationID, timeoutCancel)
+				continue
+			}
+			decision = h.decideAgentRunForDeliveryWithPolicy(conversationID, assistantMessageID, agentMode, result, cumulativeMCPExecutionIDs, requestRequiresExecutionEvidence(&req))
+			if h.tryAutoContinueAfterFinalization(taskCtx, conversationID, result, decision, &finalizationAutoContinueAttempt, &curHistory, &curFinalMessage, progressCallback) {
+				mainIterationOffset += segmentMainIterationMax
+				timeoutCancel()
+				baseCtx, cancelWithCause, taskCtx, timeoutCancel = h.rebindEinoRunningTask(taskCtx, conversationID, timeoutCancel)
+				continue
+			}
+			timeoutCancel()
+			break
+		}
+
+		cause := context.Cause(baseCtx)
+		if cause == nil {
+			switch {
+			case errors.Is(runErr, multiagent.ErrInterruptContinue):
+				cause = multiagent.ErrInterruptContinue
+			case errors.Is(runErr, ErrTaskCancelled):
+				cause = ErrTaskCancelled
+			}
+		}
+		if errors.Is(cause, multiagent.ErrInterruptContinue) {
+			if shouldPersistEinoAgentTraceAfterRunError(baseCtx) {
+				h.persistEinoAgentTraceForResume(conversationID, result)
+			}
+			note := h.tasks.TakeInterruptContinueNote(conversationID)
+			icSummary := interruptContinueTimelineSummary(note)
+			progressCallback("user_interrupt_continue", icSummary, map[string]interface{}{
+				"conversationId": conversationID,
+				"rawReason":      strings.TrimSpace(note),
+				"emptyReason":    strings.TrimSpace(note) == "",
+				"kind":           "no_active_mcp_tool",
+			})
+			inject := formatInterruptContinueUserMessage(note)
+			// 不写入 messages 表为 user 气泡：避免主对话流出现大段模板；说明已由 user_interrupt_continue 记入助手 process_details（迭代详情）。
+			if hist, err := h.loadHistoryFromAgentTrace(conversationID); err == nil && len(hist) > 0 {
+				curHistory = hist
+			}
+			curFinalMessage = inject
+			sendEvent("progress", "已合并用户补充与最新轨迹，正在继续推理…", map[string]interface{}{
+				"conversationId": conversationID,
+				"source":         "interrupt_continue",
+			})
+			mainIterationOffset += segmentMainIterationMax
+			timeoutCancel()
+			baseCtx, cancelWithCause = context.WithCancelCause(detachedAgentContext(baseCtx))
+			h.tasks.BindTaskCancel(conversationID, cancelWithCause)
+			taskCtx, timeoutCancel = context.WithTimeout(baseCtx, 600*time.Minute)
+			h.tasks.UpdateTaskStatus(conversationID, "running")
+			continue
+		}
+
+		if shouldPersistEinoAgentTraceAfterRunError(baseCtx) {
+			h.persistEinoAgentTraceForResume(conversationID, result)
+		}
+		if errors.Is(cause, ErrTaskCancelled) {
+			taskStatus = "cancelled"
+			h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+			cancelMsg := "任务已被用户取消，后续操作已停止。"
+			if assistantMessageID != "" {
+				if result != nil {
+					if err := h.mergeAssistantMessagePartialOnCancel(assistantMessageID, result.Response); err != nil {
+						h.logger.Warn("合并取消前的部分回复失败", zap.Error(err))
+					}
+				}
+				if err := h.appendAssistantMessageNotice(assistantMessageID, cancelMsg); err != nil {
+					h.logger.Warn("更新取消后的助手消息失败", zap.Error(err))
+				}
+				_ = h.db.AddProcessDetail(assistantMessageID, conversationID, "cancelled", cancelMsg, nil)
+			}
+			sendEvent("cancelled", cancelMsg, map[string]interface{}{
+				"conversationId": conversationID,
+				"messageId":      assistantMessageID,
+			})
+			sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+			timeoutCancel()
+			return
+		}
+
+		if errors.Is(runErr, context.DeadlineExceeded) || errors.Is(context.Cause(taskCtx), context.DeadlineExceeded) {
+			taskStatus = "timeout"
+			h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+			timeoutMsg := "任务执行超时，已自动终止。"
+			if assistantMessageID != "" {
+				_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", timeoutMsg, time.Now(), assistantMessageID)
+				_ = h.db.AddProcessDetail(assistantMessageID, conversationID, "timeout", timeoutMsg, nil)
+			}
+			sendEvent("error", timeoutMsg, map[string]interface{}{
+				"conversationId": conversationID,
+				"messageId":      assistantMessageID,
+				"errorType":      "timeout",
+			})
+			sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+			timeoutCancel()
+			return
+		}
+
+		h.logger.Error("Eino DeepAgent 执行失败", zap.Error(runErr))
+		taskStatus = "failed"
+		h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+		errMsg := "执行失败: " + runErr.Error()
+		if assistantMessageID != "" {
+			_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", errMsg, time.Now(), assistantMessageID)
+			_ = h.db.AddProcessDetail(assistantMessageID, conversationID, "error", errMsg, nil)
+		}
+		sendEvent("error", errMsg, map[string]interface{}{
+			"conversationId": conversationID,
+			"messageId":      assistantMessageID,
+		})
+		sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+		timeoutCancel()
+		return
+	}
+
+	timeoutCancel()
+
+	if decision.CompletionReason == "" {
+		decision = h.decideAgentRunForDeliveryWithPolicy(conversationID, assistantMessageID, agentMode, result, cumulativeMCPExecutionIDs, requestRequiresExecutionEvidence(&req))
+	}
+	h.persistFinalizationDecision(conversationID, assistantMessageID, agentMode, cumulativeMCPExecutionIDs, multiagent.AggregatedReasoningFromTraceJSON(result.LastAgentTraceInput), decision)
+
+	if result.LastAgentTraceInput != "" || result.LastAgentTraceOutput != "" {
+		if err := h.db.SaveAgentTrace(conversationID, result.LastAgentTraceInput, result.LastAgentTraceOutput); err != nil {
+			h.logger.Warn("保存代理轨迹失败", zap.Error(err))
+		}
+	}
+
+	responseText := decision.FinalText
+	if !decision.Finalizable {
+		responseText = finalizationBlockedMessage(decision)
+		sendEvent("finalization_check", responseText, decision)
+		taskStatus = decision.Status
+		h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+	}
+	sendEvent("response", responseText, finalizationResponsePayload(decision, map[string]interface{}{
+		"mcpExecutionIds": cumulativeMCPExecutionIDs,
+		"conversationId":  conversationID,
+		"messageId":       assistantMessageID,
+		"agentMode":       agentMode,
+	}))
+	sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+}
+
+// MultiAgentLoop Eino DeepAgent 非流式对话（需 multi_agent.enabled）。
+func (h *AgentHandler) MultiAgentLoop(c *gin.Context) {
+	if h.config == nil || !h.config.MultiAgent.Enabled {
+		c.JSON(http.StatusNotFound, gin.H{"error": "多代理未启用，请在 config.yaml 中设置 multi_agent.enabled: true"})
+		return
+	}
+
+	var req ChatRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	h.logger.Info("收到 Eino DeepAgent 非流式请求", zap.String("conversationId", req.ConversationID))
+
+	prep, err := h.prepareMultiAgentSession(&req, c, "multi_agent")
+	if err != nil {
+		status, msg := multiAgentHTTPErrorStatus(err)
+		c.JSON(status, gin.H{"error": msg})
+		return
+	}
+	h.activateHITLForConversation(prep.ConversationID, req.Hitl)
+	if h.hitlManager != nil {
+		defer h.hitlManager.DeactivateConversation(prep.ConversationID)
+	}
+	if h.runRoleWorkflowJSONIfBound(c, &req, prep) {
+		return
+	}
+
+	baseCtx, cancelWithCause := context.WithCancelCause(c.Request.Context())
+	defer cancelWithCause(nil)
+	taskCtx, timeoutCancel := context.WithTimeout(baseCtx, 600*time.Minute)
+	defer timeoutCancel()
+	progressCallback := h.createProgressCallback(taskCtx, cancelWithCause, prep.ConversationID, prep.AssistantMessageID, nil)
+	taskCtx = multiagent.WithHITLToolInterceptor(taskCtx, func(ctx context.Context, toolName, arguments string) (string, error) {
+		return h.interceptHITLForEinoTool(ctx, cancelWithCause, prep.ConversationID, prep.AssistantMessageID, nil, toolName, arguments)
+	})
+	runCfg, _, err := h.configForAIChannel(req.AIChannelID)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	curHist := prep.History
+	curMsg := prep.FinalMessage
+	var result *multiagent.RunResult
+	var runErr error
+	var emptyResponseContinueAttempt int
+	var finalizationAutoContinueAttempt int
+	effectiveOrch := config.NormalizeMultiAgentOrchestration(h.config.MultiAgent.Orchestration)
+	if o := strings.TrimSpace(req.Orchestration); o != "" {
+		effectiveOrch = config.NormalizeMultiAgentOrchestration(o)
+	}
+	agentMode := "eino_" + effectiveOrch
+	var decision agentfinalizer.Decision
+	for {
+		result, runErr = multiagent.RunDeepAgent(
+			taskCtx,
+			runCfg,
+			&runCfg.MultiAgent,
+			h.agent,
+			h.db,
+			h.logger,
+			prep.ConversationID,
+			h.conversationProjectID(prep.ConversationID),
+			curMsg,
+			curHist,
+			prep.RoleTools,
+			progressCallback,
+			h.agentsMarkdownDir,
+			strings.TrimSpace(req.Orchestration),
+			chatReasoningToClientIntent(req.Reasoning),
+			h.agentSessionContextBlock(prep.ConversationID),
+		)
+		if runErr != nil {
+			if shouldPersistEinoAgentTraceAfterRunError(baseCtx) {
+				h.persistEinoAgentTraceForResume(prep.ConversationID, result)
+			}
+			h.logger.Error("Eino DeepAgent 执行失败", zap.Error(runErr))
+			errMsg := "执行失败: " + runErr.Error()
+			if prep.AssistantMessageID != "" {
+				_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", errMsg, time.Now(), prep.AssistantMessageID)
+			}
+			c.JSON(http.StatusInternalServerError, gin.H{"error": errMsg})
+			return
+		}
+		mw := &h.config.MultiAgent.EinoMiddleware
+		if h.tryContinueOnEinoEmptyResponse(taskCtx, mw, prep.ConversationID, result, &emptyResponseContinueAttempt, &curHist, &curMsg, progressCallback) {
+			continue
+		}
+		decision = h.decideAgentRunForDeliveryWithPolicy(prep.ConversationID, prep.AssistantMessageID, agentMode, result, result.MCPExecutionIDs, requestRequiresExecutionEvidence(&req))
+		if h.tryAutoContinueAfterFinalization(taskCtx, prep.ConversationID, result, decision, &finalizationAutoContinueAttempt, &curHist, &curMsg, progressCallback) {
+			continue
+		}
+		break
+	}
+
+	h.persistFinalizationDecision(prep.ConversationID, prep.AssistantMessageID, agentMode, result.MCPExecutionIDs, multiagent.AggregatedReasoningFromTraceJSON(result.LastAgentTraceInput), decision)
+
+	if result.LastAgentTraceInput != "" || result.LastAgentTraceOutput != "" {
+		if err := h.db.SaveAgentTrace(prep.ConversationID, result.LastAgentTraceInput, result.LastAgentTraceOutput); err != nil {
+			h.logger.Warn("保存代理轨迹失败", zap.Error(err))
+		}
+	}
+
+	responseText := decision.FinalText
+	if !decision.Finalizable {
+		responseText = finalizationBlockedMessage(decision)
+	}
+	c.JSON(http.StatusOK, ChatResponse{
+		Response:            responseText,
+		MCPExecutionIDs:     result.MCPExecutionIDs,
+		ConversationID:      prep.ConversationID,
+		Time:                time.Now(),
+		Finalizable:         decision.Finalizable,
+		Finalized:           decision.Finalized,
+		Status:              decision.Status,
+		CompletionReason:    decision.CompletionReason,
+		EvidenceVerified:    decision.EvidenceVerified,
+		EvidenceRefs:        decision.EvidenceRefs,
+		PendingExecutionIDs: decision.PendingExecutionIDs,
+		MissingChecks:       decision.MissingChecks,
+	})
+}
+
+// persistEinoAgentTraceForResume 在 Eino 运行异常结束时写入代理轨迹（库列 last_react_*），供下一请求 loadHistoryFromAgentTrace 软续跑。
+func (h *AgentHandler) persistEinoAgentTraceForResume(conversationID string, result *multiagent.RunResult) {
+	if h == nil || result == nil {
+		return
+	}
+	if result.LastAgentTraceInput == "" && result.LastAgentTraceOutput == "" {
+		return
+	}
+	if err := h.db.SaveAgentTrace(conversationID, result.LastAgentTraceInput, result.LastAgentTraceOutput); err != nil {
+		h.logger.Warn("保存 Eino 续跑上下文失败", zap.String("conversationId", conversationID), zap.Error(err))
+	}
+}
+
+// mergeMCPExecutionIDLists 去重合并多段 Run 的 MCP execution id（顺序：先 dst 后 more）。
+func mergeMCPExecutionIDLists(dst []string, more []string) []string {
+	seen := make(map[string]struct{}, len(dst)+len(more))
+	out := make([]string, 0, len(dst)+len(more))
+	add := func(ids []string) {
+		for _, id := range ids {
+			id = strings.TrimSpace(id)
+			if id == "" {
+				continue
+			}
+			if _, ok := seen[id]; ok {
+				continue
+			}
+			seen[id] = struct{}{}
+			out = append(out, id)
+		}
+	}
+	add(dst)
+	add(more)
+	return out
+}
+
+// interruptContinueTimelineSummary 时间线 / process_details 中展示的简短正文（完整模板已写入另一条用户消息）。
+func interruptContinueTimelineSummary(note string) string {
+	note = strings.TrimSpace(note)
+	if note == "" {
+		return "用户选择「中断并继续」，未填写说明；已按默认渗透补充模板合并上下文并续跑。"
+	}
+	return "用户中断说明（原文）：\n\n" + note
+}
+
+// formatInterruptContinueUserMessage 将「中断并继续」弹窗中的说明格式化为新一轮 user 消息（渗透场景下强调路径补充与端口复扫）。
+func formatInterruptContinueUserMessage(note string) string {
+	var b strings.Builder
+	b.WriteString("【用户补充 / 中断后继续】\n")
+	if s := strings.TrimSpace(note); s != "" {
+		b.WriteString(s)
+		b.WriteString("\n\n")
+	}
+	b.WriteString("【请在本轮落实】\n")
+	b.WriteString("- 将用户提供的接口路径、参数、业务变化纳入后续测试与推理。\n")
+	b.WriteString("- 若资产或目标信息有更新，请对目标重新执行端口/服务探测，再基于新结果规划下一步。\n")
+	b.WriteString("- 在已有轨迹基础上推进，避免无意义重复已完成的步骤。\n")
+	return strings.TrimSpace(b.String())
+}
+
+func multiAgentHTTPErrorStatus(err error) (int, string) {
+	msg := err.Error()
+	switch {
+	case strings.Contains(msg, "无权访问"):
+		return http.StatusForbidden, msg
+	case strings.Contains(msg, "对话不存在"):
+		return http.StatusNotFound, msg
+	case strings.Contains(msg, "未找到该 WebShell"):
+		return http.StatusBadRequest, msg
+	case strings.Contains(msg, "附件最多"):
+		return http.StatusBadRequest, msg
+	case strings.Contains(msg, "保存用户消息失败"), strings.Contains(msg, "创建对话失败"):
+		return http.StatusInternalServerError, msg
+	case strings.Contains(msg, "保存上传文件失败"):
+		return http.StatusInternalServerError, msg
+	default:
+		return http.StatusBadRequest, msg
+	}
+}

internal/handler/multi_agent_prepare.go

@@ -0,0 +1,194 @@
+package handler
+
+import (
+	"fmt"
+	"strings"
+
+	"cyberstrike-ai/internal/agent"
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/mcp/builtin"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// multiAgentPrepared 多代理请求在调用 Eino 前的会话与消息准备结果。
+type multiAgentPrepared struct {
+	ConversationID     string
+	CreatedNew         bool
+	History            []agent.ChatMessage
+	FinalMessage       string
+	RoleTools          []string
+	AssistantMessageID string
+	UserMessageID      string
+}
+
+func chatRequestAgentMode(req *ChatRequest, source string) string {
+	if strings.HasPrefix(strings.TrimSpace(source), "multi_agent") {
+		return config.NormalizeMultiAgentOrchestration(req.Orchestration)
+	}
+	return "eino_single"
+}
+
+func (h *AgentHandler) prepareMultiAgentSession(req *ChatRequest, c *gin.Context, source string) (*multiAgentPrepared, error) {
+	if len(req.Attachments) > maxAttachments {
+		return nil, fmt.Errorf("附件最多 %d 个", maxAttachments)
+	}
+
+	conversationID := strings.TrimSpace(req.ConversationID)
+	projectID := strings.TrimSpace(effectiveProjectID(h.config, req.ProjectID))
+	webshellID := strings.TrimSpace(req.WebShellConnectionID)
+	session, hasSession := security.CurrentSession(c)
+	if !hasSession || !session.Permissions["chat:write"] {
+		return nil, fmt.Errorf("无权写入对话")
+	}
+	canAccess := func(resourceType, resourceID string) bool {
+		if !hasSession || h.db == nil || strings.TrimSpace(resourceID) == "" {
+			return false
+		}
+		return h.db.UserCanAccessResource(session.UserID, session.Scope, resourceType, resourceID)
+	}
+	if projectID != "" && (!session.Permissions["project:read"] || !canAccess("project", projectID)) {
+		return nil, fmt.Errorf("无权访问目标项目")
+	}
+	if webshellID != "" && (!session.Permissions["webshell:write"] || !canAccess("webshell", webshellID)) {
+		return nil, fmt.Errorf("无权访问该 WebShell 连接")
+	}
+	createdNew := false
+	if conversationID == "" {
+		title := safeTruncateString(req.Message, 50)
+		var conv *database.Conversation
+		var err error
+		meta := audit.ConversationCreateMetaFromGin(c, source)
+		meta.ProjectID = projectID
+		meta.RoleName = req.Role
+		meta.AgentMode = chatRequestAgentMode(req, source)
+		if webshellID != "" {
+			meta.Source = source + "_webshell"
+			meta.WebShellConnectionID = webshellID
+			conv, err = h.db.CreateConversationWithWebshell(meta.WebShellConnectionID, title, meta)
+		} else {
+			conv, err = h.db.CreateConversation(title, meta)
+		}
+		if err != nil {
+			return nil, fmt.Errorf("创建对话失败: %w", err)
+		}
+		conversationID = conv.ID
+		createdNew = true
+		if hasSession {
+			_ = h.db.SetResourceOwner("conversation", conversationID, session.UserID)
+			_ = h.db.AssignResourceToUser(session.UserID, "conversation", conversationID)
+		}
+	} else {
+		if _, err := h.db.GetConversation(conversationID); err != nil {
+			return nil, fmt.Errorf("对话不存在")
+		}
+		if !canAccess("conversation", conversationID) {
+			return nil, fmt.Errorf("无权访问该对话")
+		}
+	}
+	if err := h.db.SetConversationRoleName(conversationID, req.Role); err != nil {
+		h.logger.Warn("更新对话角色失败", zap.String("conversationId", conversationID), zap.String("role", req.Role), zap.Error(err))
+	}
+	if err := h.db.SetConversationAgentMode(conversationID, chatRequestAgentMode(req, source)); err != nil {
+		h.logger.Warn("更新对话模式失败", zap.String("conversationId", conversationID), zap.String("source", source), zap.String("orchestration", req.Orchestration), zap.Error(err))
+	}
+
+	agentHistoryMessages, err := h.loadHistoryFromAgentTrace(conversationID)
+	if err != nil {
+		historyMessages, getErr := h.db.GetMessages(conversationID)
+		if getErr != nil {
+			agentHistoryMessages = []agent.ChatMessage{}
+		} else {
+			agentHistoryMessages = dbMessagesToAgentChatMessages(historyMessages)
+		}
+	}
+
+	finalMessage := req.Message
+	var roleTools []string
+	if webshellID != "" {
+		conn, errConn := h.db.GetWebshellConnection(webshellID)
+		if errConn != nil || conn == nil {
+			h.logger.Warn("WebShell AI 助手：未找到连接", zap.String("id", req.WebShellConnectionID), zap.Error(errConn))
+			return nil, fmt.Errorf("未找到该 WebShell 连接")
+		}
+		webshellContext := BuildWebshellAssistantContext(conn, WebshellSkillHintMultiAgent, req.Message)
+		// WebShell 模式下如果同时指定了角色，追加角色 user_prompt（工具集仍仅限 webshell 专用工具）
+		if req.Role != "" && req.Role != "默认" && h.config != nil && h.config.Roles != nil {
+			if role, exists := h.config.Roles[req.Role]; exists && role.Enabled && role.UserPrompt != "" {
+				finalMessage = role.UserPrompt + "\n\n" + webshellContext
+				h.logger.Info("WebShell + 角色: 应用角色提示词（多代理）", zap.String("role", req.Role))
+			} else {
+				finalMessage = webshellContext
+			}
+		} else {
+			finalMessage = webshellContext
+		}
+		roleTools = []string{
+			builtin.ToolWebshellExec,
+			builtin.ToolWebshellFileList,
+			builtin.ToolWebshellFileRead,
+			builtin.ToolWebshellFileWrite,
+			builtin.ToolRecordVulnerability,
+			builtin.ToolListVulnerabilities,
+			builtin.ToolGetVulnerability,
+			builtin.ToolUpsertProjectFact,
+			builtin.ToolGetProjectFact,
+			builtin.ToolListProjectFacts,
+			builtin.ToolSearchProjectFacts,
+			builtin.ToolDeprecateProjectFact,
+			builtin.ToolRestoreProjectFact,
+			builtin.ToolListKnowledgeRiskTypes,
+			builtin.ToolSearchKnowledgeBase,
+		}
+	} else if req.Role != "" && req.Role != "默认" && h.config != nil && h.config.Roles != nil {
+		if role, exists := h.config.Roles[req.Role]; exists && role.Enabled {
+			if role.UserPrompt != "" {
+				finalMessage = role.UserPrompt + "\n\n" + req.Message
+			}
+			roleTools = role.Tools
+		}
+	}
+
+	var savedPaths []string
+	if len(req.Attachments) > 0 {
+		var aerr error
+		savedPaths, aerr = saveAttachmentsToDateAndConversationDir(req.Attachments, conversationID, h.logger)
+		if aerr != nil {
+			return nil, fmt.Errorf("保存上传文件失败: %w", aerr)
+		}
+	}
+	finalMessage = appendAttachmentsToMessage(finalMessage, req.Attachments, savedPaths)
+
+	userContent := userMessageContentForStorage(req.Message, req.Attachments, savedPaths)
+	userMsgRow, uerr := h.db.AddMessage(conversationID, "user", userContent, nil)
+	if uerr != nil {
+		h.logger.Error("保存用户消息失败", zap.Error(uerr))
+		return nil, fmt.Errorf("保存用户消息失败: %w", uerr)
+	}
+	userMessageID := ""
+	if userMsgRow != nil {
+		userMessageID = userMsgRow.ID
+	}
+
+	assistantMsg, aerr := h.db.AddMessage(conversationID, "assistant", "处理中...", nil)
+	var assistantMessageID string
+	if aerr != nil {
+		h.logger.Warn("创建助手消息占位失败", zap.Error(aerr))
+	} else if assistantMsg != nil {
+		assistantMessageID = assistantMsg.ID
+	}
+
+	return &multiAgentPrepared{
+		ConversationID:     conversationID,
+		CreatedNew:         createdNew,
+		History:            agentHistoryMessages,
+		FinalMessage:       finalMessage,
+		RoleTools:          roleTools,
+		AssistantMessageID: assistantMessageID,
+		UserMessageID:      userMessageID,
+	}, nil
+}

internal/handler/notification.go

@@ -0,0 +1,837 @@
+package handler
+
+import (
+	"fmt"
+	"net/http"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// NotificationHandler 聚合通知（Phase 2：服务端统一计算）
+type NotificationHandler struct {
+	db           *database.DB
+	agentHandler *AgentHandler
+	logger       *zap.Logger
+}
+
+const notificationReadMaxRows = 150
+
+// NotificationSummaryItem 通知项
+type NotificationSummaryItem struct {
+	ID         string `json:"id"`
+	Level      string `json:"level"` // p0/p1/p2
+	Type       string `json:"type"`
+	Title      string `json:"title"`
+	Desc       string `json:"desc"`
+	Ts         string `json:"ts"` // RFC3339
+	Count      int    `json:"count,omitempty"`
+	Actionable bool   `json:"actionable"`
+	Read       bool   `json:"read"`
+	// 以下字段用于前端深链跳转（通知即入口）
+	ConversationID  string `json:"conversationId,omitempty"`
+	VulnerabilityID string `json:"vulnerabilityId,omitempty"`
+	ExecutionID     string `json:"executionId,omitempty"`
+	InterruptID     string `json:"interruptId,omitempty"`
+	SessionID       string `json:"sessionId,omitempty"` // C2 会话（如新会话上线）
+}
+
+// NotificationSummaryResponse 聚合响应
+type NotificationSummaryResponse struct {
+	SinceMs     int64                     `json:"sinceMs"`
+	GeneratedAt string                    `json:"generatedAt"`
+	P0Count     int                       `json:"p0Count"`
+	UnreadCount int                       `json:"unreadCount"`
+	Counts      map[string]int            `json:"counts"`
+	Items       []NotificationSummaryItem `json:"items"`
+}
+
+func NewNotificationHandler(db *database.DB, agentHandler *AgentHandler, logger *zap.Logger) *NotificationHandler {
+	return &NotificationHandler{
+		db:           db,
+		agentHandler: agentHandler,
+		logger:       logger,
+	}
+}
+
+func parseSinceMs(raw string) int64 {
+	v := strings.TrimSpace(raw)
+	if v == "" {
+		return 0
+	}
+	if ms, err := strconv.ParseInt(v, 10, 64); err == nil && ms > 0 {
+		return ms
+	}
+	if t, err := time.Parse(time.RFC3339, v); err == nil {
+		return t.UnixMilli()
+	}
+	return 0
+}
+
+func unixSecToRFC3339(sec int64) string {
+	if sec <= 0 {
+		return time.Now().UTC().Format(time.RFC3339)
+	}
+	return time.Unix(sec, 0).UTC().Format(time.RFC3339)
+}
+
+func normalizedSinceSec(sinceMs int64) int64 {
+	sec := sinceMs / 1000
+	// SQLite 默认时间精度到秒；给 1s 回看窗口，避免“同秒内新增”被漏算。
+	if sec > 0 {
+		return sec - 1
+	}
+	return 0
+}
+
+func ptrTime(t time.Time) *time.Time {
+	return &t
+}
+
+func normalizeSinceMs(raw int64) int64 {
+	if raw > 0 {
+		return raw
+	}
+	// 默认仅看最近 24 小时，避免首次打开拉全量历史噪音。
+	return time.Now().Add(-24 * time.Hour).UnixMilli()
+}
+
+func levelBySeverity(sev string) string {
+	switch strings.ToLower(strings.TrimSpace(sev)) {
+	case "critical", "high":
+		return "p0"
+	case "medium":
+		return "p1"
+	default:
+		return "p2"
+	}
+}
+
+func requestWantsEnglish(c *gin.Context) bool {
+	if c == nil {
+		return false
+	}
+	lang := strings.ToLower(strings.TrimSpace(c.Query("lang")))
+	if lang == "" {
+		lang = strings.ToLower(strings.TrimSpace(c.GetHeader("Accept-Language")))
+	}
+	return strings.HasPrefix(lang, "en")
+}
+
+func i18nText(english bool, zh string, en string) string {
+	if english {
+		return en
+	}
+	return zh
+}
+
+func notificationAccessFromContext(c *gin.Context) database.RBACListAccess {
+	session, ok := security.CurrentSession(c)
+	if !ok {
+		return database.RBACListAccess{}
+	}
+	return database.RBACListAccess{UserID: session.UserID, Scope: session.Scope}
+}
+
+func appendConversationAccessSQL(query string, args []interface{}, column string, access database.RBACListAccess) (string, []interface{}) {
+	userID := strings.TrimSpace(access.UserID)
+	if access.Scope == database.RBACScopeAll {
+		return query, args
+	}
+	if userID == "" {
+		return query + ` AND 1=0`, args
+	}
+	query += ` AND ` + column + ` IS NOT NULL AND ` + column + ` <> '' AND (
+		EXISTS (SELECT 1 FROM conversations c WHERE c.id = ` + column + ` AND c.owner_user_id = ?)
+		OR EXISTS (
+			SELECT 1 FROM rbac_resource_assignments ra
+			WHERE ra.user_id = ? AND ra.resource_type = 'conversation' AND ra.resource_id = ` + column + `
+		)
+		OR EXISTS (
+			SELECT 1 FROM conversations c
+			JOIN projects p ON p.id = c.project_id
+			WHERE c.id = ` + column + ` AND p.owner_user_id = ?
+		)
+		OR EXISTS (
+			SELECT 1 FROM conversations c
+			JOIN rbac_resource_assignments pra ON pra.resource_id = c.project_id
+			WHERE c.id = ` + column + ` AND pra.user_id = ? AND pra.resource_type = 'project'
+		)
+	)`
+	args = append(args, userID, userID, userID, userID)
+	return query, args
+}
+
+func appendVulnerabilityNotificationAccessSQL(query string, args []interface{}, access database.RBACListAccess) (string, []interface{}) {
+	userID := strings.TrimSpace(access.UserID)
+	if access.Scope == database.RBACScopeAll {
+		return query, args
+	}
+	if userID == "" {
+		return query + ` AND 1=0`, args
+	}
+	query += ` AND (
+		owner_user_id = ?
+		OR EXISTS (
+			SELECT 1 FROM rbac_resource_assignments ra
+			WHERE ra.user_id = ? AND ra.resource_type = 'vulnerability' AND ra.resource_id = vulnerabilities.id
+		)
+		OR (
+			project_id IS NOT NULL AND project_id <> '' AND (
+				EXISTS (SELECT 1 FROM projects p WHERE p.id = vulnerabilities.project_id AND p.owner_user_id = ?)
+				OR EXISTS (
+					SELECT 1 FROM rbac_resource_assignments pra
+					WHERE pra.user_id = ? AND pra.resource_type = 'project' AND pra.resource_id = vulnerabilities.project_id
+				)
+			)
+		)
+		OR (
+			conversation_id IS NOT NULL AND conversation_id <> '' AND (
+				EXISTS (SELECT 1 FROM conversations c WHERE c.id = vulnerabilities.conversation_id AND c.owner_user_id = ?)
+				OR EXISTS (
+					SELECT 1 FROM rbac_resource_assignments cra
+					WHERE cra.user_id = ? AND cra.resource_type = 'conversation' AND cra.resource_id = vulnerabilities.conversation_id
+				)
+			)
+		)
+	)`
+	args = append(args, userID, userID, userID, userID, userID, userID)
+	return query, args
+}
+
+func (h *NotificationHandler) loadPendingHITLItems(limit int, english bool, access database.RBACListAccess) ([]NotificationSummaryItem, error) {
+	query := `
+		SELECT
+			id,
+			conversation_id,
+			tool_name,
+			COALESCE(CAST(strftime('%s', created_at) AS INTEGER), 0)
+		FROM hitl_interrupts
+		WHERE status = 'pending'
+	`
+	args := []interface{}{}
+	query, args = appendConversationAccessSQL(query, args, "conversation_id", access)
+	query += ` ORDER BY created_at DESC
+		LIMIT ?
+	`
+	args = append(args, limit)
+	rows, err := h.db.Query(query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	items := make([]NotificationSummaryItem, 0, limit)
+	for rows.Next() {
+		var id, conversationID, toolName string
+		var createdSec int64
+		if err := rows.Scan(&id, &conversationID, &toolName, &createdSec); err != nil {
+			continue
+		}
+		desc := i18nText(english, "会话 "+conversationID+" 的审批中断待处理", "Conversation "+conversationID+" has pending HITL approval")
+		if strings.TrimSpace(toolName) != "" {
+			desc = i18nText(english, "工具 "+toolName+" 等待审批", "Tool "+toolName+" is waiting for approval")
+		}
+		items = append(items, NotificationSummaryItem{
+			ID:             "hitl:" + id,
+			Level:          "p0",
+			Type:           "hitl_pending",
+			Title:          i18nText(english, "HITL 待审批", "HITL Pending Approval"),
+			Desc:           desc,
+			Ts:             unixSecToRFC3339(createdSec),
+			Count:          1,
+			Actionable:     true,
+			Read:           false,
+			ConversationID: conversationID,
+			InterruptID:    id,
+		})
+	}
+	return items, nil
+}
+
+func (h *NotificationHandler) loadVulnerabilityItems(sinceMs int64, limit int, english bool, access database.RBACListAccess) ([]NotificationSummaryItem, map[string]int, error) {
+	sinceSec := normalizedSinceSec(sinceMs)
+	query := `
+		SELECT
+			id,
+			title,
+			severity,
+			conversation_id,
+			COALESCE(CAST(strftime('%s', created_at) AS INTEGER), 0)
+		FROM vulnerabilities
+		WHERE CAST(strftime('%s', created_at) AS INTEGER) > ?
+	`
+	args := []interface{}{sinceSec}
+	query, args = appendVulnerabilityNotificationAccessSQL(query, args, access)
+	query += `
+		ORDER BY created_at DESC
+		LIMIT ?
+	`
+	args = append(args, limit)
+	rows, err := h.db.Query(query, args...)
+	if err != nil {
+		return nil, nil, err
+	}
+	defer rows.Close()
+	items := make([]NotificationSummaryItem, 0, limit)
+	counts := map[string]int{
+		"newCriticalVulns": 0,
+		"newHighVulns":     0,
+		"newMediumVulns":   0,
+		"newLowVulns":      0,
+		"newInfoVulns":     0,
+	}
+	for rows.Next() {
+		var id, title, severity, conversationID string
+		var createdSec int64
+		if err := rows.Scan(&id, &title, &severity, &conversationID, &createdSec); err != nil {
+			continue
+		}
+		switch strings.ToLower(strings.TrimSpace(severity)) {
+		case "critical":
+			counts["newCriticalVulns"]++
+		case "high":
+			counts["newHighVulns"]++
+		case "medium":
+			counts["newMediumVulns"]++
+		case "low":
+			counts["newLowVulns"]++
+		default:
+			counts["newInfoVulns"]++
+		}
+		sevUpper := strings.ToUpper(strings.TrimSpace(severity))
+		if sevUpper == "" {
+			sevUpper = "INFO"
+		}
+		finalTitle := i18nText(english, "新漏洞（"+sevUpper+"）", "New Vulnerability ("+sevUpper+")")
+		finalDesc := strings.TrimSpace(title)
+		if finalDesc == "" {
+			finalDesc = i18nText(english, "（无标题）", "(Untitled)")
+		}
+		items = append(items, NotificationSummaryItem{
+			ID:              "vuln:" + id,
+			Level:           levelBySeverity(severity),
+			Type:            "vulnerability_created",
+			Title:           finalTitle,
+			Desc:            finalDesc,
+			Ts:              unixSecToRFC3339(createdSec),
+			Count:           1,
+			Actionable:      false,
+			Read:            false,
+			ConversationID:  conversationID,
+			VulnerabilityID: id,
+		})
+	}
+	return items, counts, nil
+}
+
+// loadC2SessionOnlineEvents 新会话上线（c2_events：session + critical，与 Manager.IngestCheckIn 一致）
+func (h *NotificationHandler) loadC2SessionOnlineEvents(sinceMs int64, limit int, english bool, access database.RBACListAccess) ([]NotificationSummaryItem, int, error) {
+	sinceSec := normalizedSinceSec(sinceMs)
+	events, err := h.db.ListC2EventsForAccess(database.ListC2EventsFilter{
+		Category: "session",
+		Level:    "critical",
+		Since:    ptrTime(time.Unix(sinceSec, 0)),
+		Limit:    limit,
+	}, access)
+	if err != nil {
+		return nil, 0, err
+	}
+	items := make([]NotificationSummaryItem, 0, limit)
+	for _, e := range events {
+		if e == nil {
+			continue
+		}
+		desc := strings.TrimSpace(e.Message)
+		if len(desc) > 220 {
+			desc = desc[:200] + "…"
+		}
+		if desc == "" {
+			desc = i18nText(english, "新会话已建立", "A new session was created")
+		}
+		items = append(items, NotificationSummaryItem{
+			ID:         "c2evt:" + e.ID,
+			Level:      "p0",
+			Type:       "c2_session_online",
+			Title:      i18nText(english, "C2 新会话上线", "C2 new session online"),
+			Desc:       desc,
+			Ts:         e.CreatedAt.UTC().Format(time.RFC3339),
+			Count:      1,
+			Actionable: false,
+			Read:       false,
+			SessionID:  e.SessionID,
+		})
+	}
+	return items, len(items), nil
+}
+
+func (h *NotificationHandler) loadFailedExecutionItems(sinceMs int64, limit int, english bool) ([]NotificationSummaryItem, int, error) {
+	sinceSec := normalizedSinceSec(sinceMs)
+	rows, err := h.db.Query(`
+		SELECT
+			id,
+			tool_name,
+			COALESCE(CAST(strftime('%s', start_time) AS INTEGER), 0)
+		FROM tool_executions
+		WHERE status = 'failed'
+		  AND CAST(strftime('%s', start_time) AS INTEGER) > ?
+		ORDER BY start_time DESC
+		LIMIT ?
+	`, sinceSec, limit)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer rows.Close()
+	items := make([]NotificationSummaryItem, 0, limit)
+	count := 0
+	for rows.Next() {
+		var id, toolName string
+		var startSec int64
+		if err := rows.Scan(&id, &toolName, &startSec); err != nil {
+			continue
+		}
+		count++
+		if strings.TrimSpace(toolName) == "" {
+			toolName = i18nText(english, "未知工具", "unknown")
+		}
+		items = append(items, NotificationSummaryItem{
+			ID:          "exec_failed:" + id,
+			Level:       "p0",
+			Type:        "task_failed",
+			Title:       i18nText(english, "任务执行失败", "Task Execution Failed"),
+			Desc:        i18nText(english, "工具 "+toolName+" 执行失败", "Tool "+toolName+" execution failed"),
+			Ts:          unixSecToRFC3339(startSec),
+			Count:       1,
+			Actionable:  false,
+			Read:        false,
+			ExecutionID: id,
+		})
+	}
+	return items, count, nil
+}
+
+func (h *NotificationHandler) summarizeLongRunningTasks(threshold time.Duration, english bool, access database.RBACListAccess) ([]NotificationSummaryItem, int) {
+	if h.agentHandler == nil || h.agentHandler.tasks == nil {
+		return nil, 0
+	}
+	tasks := h.agentHandler.tasks.GetActiveTasks()
+	now := time.Now()
+	items := make([]NotificationSummaryItem, 0, len(tasks))
+	for _, t := range tasks {
+		if t == nil {
+			continue
+		}
+		if !h.notificationConversationAllowed(access, t.ConversationID) {
+			continue
+		}
+		if now.Sub(t.StartedAt) >= threshold {
+			items = append(items, NotificationSummaryItem{
+				ID:             "task_long:" + t.ConversationID,
+				Level:          "p1",
+				Type:           "long_running_tasks",
+				Title:          i18nText(english, "长时间运行任务", "Long Running Task"),
+				Desc:           i18nText(english, "会话 "+t.ConversationID+" 运行超过 15 分钟", "Conversation "+t.ConversationID+" has been running over 15 minutes"),
+				Ts:             t.StartedAt.UTC().Format(time.RFC3339),
+				Count:          1,
+				Actionable:     true,
+				Read:           false,
+				ConversationID: t.ConversationID,
+			})
+		}
+	}
+	return items, len(items)
+}
+
+func (h *NotificationHandler) summarizeCompletedTasksSince(sinceMs int64, limit int, english bool, access database.RBACListAccess) ([]NotificationSummaryItem, int) {
+	if h.agentHandler == nil || h.agentHandler.tasks == nil {
+		return nil, 0
+	}
+	since := time.UnixMilli(sinceMs)
+	completed := h.agentHandler.tasks.GetCompletedTasks()
+	items := make([]NotificationSummaryItem, 0, limit)
+	for _, t := range completed {
+		if t == nil {
+			continue
+		}
+		if !h.notificationConversationAllowed(access, t.ConversationID) {
+			continue
+		}
+		if t.CompletedAt.After(since) {
+			items = append(items, NotificationSummaryItem{
+				ID:             "task_completed:" + t.ConversationID + ":" + strconv.FormatInt(t.CompletedAt.Unix(), 10),
+				Level:          "p2",
+				Type:           "task_completed",
+				Title:          i18nText(english, "任务完成", "Task Completed"),
+				Desc:           i18nText(english, "会话 "+t.ConversationID+" 已完成", "Conversation "+t.ConversationID+" completed"),
+				Ts:             t.CompletedAt.UTC().Format(time.RFC3339),
+				Count:          1,
+				Actionable:     false,
+				Read:           false,
+				ConversationID: t.ConversationID,
+			})
+			if len(items) >= limit {
+				break
+			}
+		}
+	}
+	return items, len(items)
+}
+
+func buildPlaceholders(n int) string {
+	if n <= 0 {
+		return ""
+	}
+	out := make([]string, 0, n)
+	for i := 0; i < n; i++ {
+		out = append(out, "?")
+	}
+	return strings.Join(out, ",")
+}
+
+func (h *NotificationHandler) readStatesByIDs(userID string, ids []string) (map[string]bool, error) {
+	result := make(map[string]bool, len(ids))
+	userID = strings.TrimSpace(userID)
+	if len(ids) == 0 || userID == "" {
+		return result, nil
+	}
+	holders := buildPlaceholders(len(ids))
+	query := "SELECT event_id FROM notification_reads_by_user WHERE user_id = ? AND event_id IN (" + holders + ")"
+	args := make([]interface{}, 0, len(ids)+1)
+	args = append(args, userID)
+	for _, id := range ids {
+		args = append(args, id)
+	}
+	rows, err := h.db.Query(query, args...)
+	if err != nil {
+		return result, err
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var id string
+		if err := rows.Scan(&id); err != nil {
+			continue
+		}
+		result[id] = true
+	}
+	return result, nil
+}
+
+func (h *NotificationHandler) applyReadStates(userID string, items []NotificationSummaryItem) ([]NotificationSummaryItem, error) {
+	markableIDs := make([]string, 0, len(items))
+	for _, item := range items {
+		if item.Actionable {
+			continue
+		}
+		markableIDs = append(markableIDs, item.ID)
+	}
+	readMap, err := h.readStatesByIDs(userID, markableIDs)
+	if err != nil {
+		return items, err
+	}
+	for i := range items {
+		if items[i].Actionable {
+			items[i].Read = false
+			continue
+		}
+		items[i].Read = readMap[items[i].ID]
+	}
+	return items, nil
+}
+
+func filterVisibleItems(items []NotificationSummaryItem) []NotificationSummaryItem {
+	out := make([]NotificationSummaryItem, 0, len(items))
+	for _, item := range items {
+		if item.Actionable || !item.Read {
+			out = append(out, item)
+		}
+	}
+	return out
+}
+
+func countP0(items []NotificationSummaryItem) int {
+	total := 0
+	for _, item := range items {
+		if item.Level == "p0" {
+			if item.Count > 0 {
+				total += item.Count
+			} else {
+				total++
+			}
+		}
+	}
+	return total
+}
+
+func countUnread(items []NotificationSummaryItem) int {
+	total := 0
+	for _, item := range items {
+		if item.Actionable || !item.Read {
+			if item.Count > 0 {
+				total += item.Count
+			} else {
+				total++
+			}
+		}
+	}
+	return total
+}
+
+func createNotificationReadTableIfNeeded(db *database.DB) error {
+	if db == nil {
+		return fmt.Errorf("db is nil")
+	}
+	_, err := db.Exec(`
+		CREATE TABLE IF NOT EXISTS notification_reads_by_user (
+			user_id TEXT NOT NULL,
+			event_id TEXT NOT NULL,
+			read_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+			PRIMARY KEY(user_id, event_id)
+		);
+	`)
+	if err != nil {
+		return err
+	}
+	_, idxErr := db.Exec(`CREATE INDEX IF NOT EXISTS idx_notification_reads_user_read_at ON notification_reads_by_user(user_id, read_at DESC);`)
+	return idxErr
+}
+
+func pruneNotificationReads(db *database.DB, userID string, maxRows int) error {
+	if db == nil {
+		return fmt.Errorf("db is nil")
+	}
+	userID = strings.TrimSpace(userID)
+	if maxRows <= 0 || userID == "" {
+		return nil
+	}
+	_, err := db.Exec(`
+		DELETE FROM notification_reads_by_user
+		WHERE user_id = ? AND event_id NOT IN (
+			SELECT event_id
+			FROM notification_reads_by_user
+			WHERE user_id = ?
+			ORDER BY read_at DESC, rowid DESC
+			LIMIT ?
+		)
+	`, userID, userID, maxRows)
+	return err
+}
+
+type markReadRequest struct {
+	EventIDs []string `json:"eventIds"`
+}
+
+func normalizeMarkableEventID(id string) (string, bool) {
+	v := strings.TrimSpace(id)
+	if v == "" {
+		return "", false
+	}
+	// 仅允许“可读后隐藏”的信息类事件；Actionable 事件不参与 read 标记。
+	allowedPrefixes := []string{
+		"vuln:",
+		"exec_failed:",
+		"task_completed:",
+		"c2evt:",
+	}
+	for _, prefix := range allowedPrefixes {
+		if strings.HasPrefix(v, prefix) {
+			return v, true
+		}
+	}
+	return "", false
+}
+
+// MarkRead 按事件 ID 标记已读
+func (h *NotificationHandler) MarkRead(c *gin.Context) {
+	if err := createNotificationReadTableIfNeeded(h.db); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to prepare notification read table"})
+		return
+	}
+	var req markReadRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"})
+		return
+	}
+	if len(req.EventIDs) == 0 {
+		c.JSON(http.StatusOK, gin.H{"ok": true, "marked": 0})
+		return
+	}
+	session, ok := security.CurrentSession(c)
+	if !ok || strings.TrimSpace(session.UserID) == "" {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "missing authenticated user"})
+		return
+	}
+	tx, err := h.db.Begin()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to begin transaction"})
+		return
+	}
+	defer func() {
+		_ = tx.Rollback()
+	}()
+	stmt, err := tx.Prepare(`
+		INSERT INTO notification_reads_by_user(user_id, event_id, read_at)
+		VALUES(?, ?, CURRENT_TIMESTAMP)
+		ON CONFLICT(user_id, event_id) DO UPDATE SET read_at = CURRENT_TIMESTAMP
+	`)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to prepare statement"})
+		return
+	}
+	defer stmt.Close()
+	marked := 0
+	for _, raw := range req.EventIDs {
+		id, ok := normalizeMarkableEventID(raw)
+		if !ok {
+			continue
+		}
+		if _, err := stmt.Exec(session.UserID, id); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to mark read"})
+			return
+		}
+		marked++
+	}
+	if err := tx.Commit(); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to commit read marks"})
+		return
+	}
+	if err := pruneNotificationReads(h.db, session.UserID, notificationReadMaxRows); err != nil {
+		h.logger.Warn("裁剪通知已读记录失败", zap.Error(err))
+	}
+	c.JSON(http.StatusOK, gin.H{"ok": true, "marked": marked})
+}
+
+// GetSummary 返回通知聚合视图（用于头部铃铛）
+func (h *NotificationHandler) GetSummary(c *gin.Context) {
+	if h.db == nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "database unavailable"})
+		return
+	}
+
+	if err := createNotificationReadTableIfNeeded(h.db); err != nil {
+		h.logger.Warn("初始化通知已读表失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to initialize notification read table"})
+		return
+	}
+
+	english := requestWantsEnglish(c)
+	sinceMs := normalizeSinceMs(parseSinceMs(c.Query("since")))
+	limit, _ := strconv.Atoi(strings.TrimSpace(c.DefaultQuery("limit", "50")))
+	if limit <= 0 {
+		limit = 50
+	}
+	if limit > 200 {
+		limit = 200
+	}
+	access := notificationAccessFromContext(c)
+
+	hitlItems := []NotificationSummaryItem{}
+	if security.SessionHasPermission(c, "hitl:read") {
+		var err error
+		hitlItems, err = h.loadPendingHITLItems(limit, english, access)
+		if err != nil {
+			h.logger.Warn("加载 HITL 通知失败", zap.Error(err))
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to summarize hitl notifications"})
+			return
+		}
+	}
+
+	vulnItems := []NotificationSummaryItem{}
+	vulnCounts := map[string]int{
+		"newCriticalVulns": 0,
+		"newHighVulns":     0,
+		"newMediumVulns":   0,
+		"newLowVulns":      0,
+		"newInfoVulns":     0,
+	}
+	if security.SessionHasPermission(c, "vulnerability:read") {
+		var err error
+		vulnItems, vulnCounts, err = h.loadVulnerabilityItems(sinceMs, limit, english, access)
+		if err != nil {
+			h.logger.Warn("加载漏洞通知失败", zap.Error(err))
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to summarize vulnerabilities"})
+			return
+		}
+	}
+
+	c2OnlineItems := []NotificationSummaryItem{}
+	c2OnlineCount := 0
+	if security.SessionHasPermission(c, "c2:read") {
+		var err error
+		c2OnlineItems, c2OnlineCount, err = h.loadC2SessionOnlineEvents(sinceMs, limit, english, access)
+		if err != nil {
+			h.logger.Warn("加载 C2 会话上线通知失败", zap.Error(err))
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to summarize c2 session events"})
+			return
+		}
+	}
+
+	longRunningItems := []NotificationSummaryItem{}
+	completedItems := []NotificationSummaryItem{}
+	longRunningCount := 0
+	completedCount := 0
+	if security.SessionHasPermission(c, "tasks:read") || security.SessionHasPermission(c, "chat:read") {
+		longRunningItems, longRunningCount = h.summarizeLongRunningTasks(15*time.Minute, english, access)
+		completedItems, completedCount = h.summarizeCompletedTasksSince(sinceMs, limit, english, access)
+	}
+
+	items := make([]NotificationSummaryItem, 0, len(hitlItems)+len(vulnItems)+len(c2OnlineItems)+len(longRunningItems)+len(completedItems))
+	items = append(items, hitlItems...)
+	items = append(items, vulnItems...)
+	items = append(items, c2OnlineItems...)
+	items = append(items, longRunningItems...)
+	items = append(items, completedItems...)
+
+	session, _ := security.CurrentSession(c)
+	items, err := h.applyReadStates(session.UserID, items)
+	if err != nil {
+		h.logger.Warn("加载通知已读状态失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to load notification read states"})
+		return
+	}
+	items = filterVisibleItems(items)
+
+	sort.Slice(items, func(i, j int) bool {
+		ti, errI := time.Parse(time.RFC3339, items[i].Ts)
+		tj, errJ := time.Parse(time.RFC3339, items[j].Ts)
+		if errI != nil || errJ != nil {
+			return i < j
+		}
+		return ti.After(tj)
+	})
+
+	p0Count := countP0(items)
+	unreadCount := countUnread(items)
+	c.JSON(http.StatusOK, NotificationSummaryResponse{
+		SinceMs:     sinceMs,
+		GeneratedAt: time.Now().UTC().Format(time.RFC3339),
+		P0Count:     p0Count,
+		UnreadCount: unreadCount,
+		Counts: map[string]int{
+			"hitlPending":      len(hitlItems),
+			"newCriticalVulns": vulnCounts["newCriticalVulns"],
+			"newHighVulns":     vulnCounts["newHighVulns"],
+			"newMediumVulns":   vulnCounts["newMediumVulns"],
+			"newLowVulns":      vulnCounts["newLowVulns"],
+			"newInfoVulns":     vulnCounts["newInfoVulns"],
+			"failedExecutions": 0,
+			"longRunningTasks": longRunningCount,
+			"completedTasks":   completedCount,
+			"c2SessionOnline":  c2OnlineCount,
+		},
+		Items: items,
+	})
+}
+
+func (h *NotificationHandler) notificationConversationAllowed(access database.RBACListAccess, conversationID string) bool {
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" {
+		return access.Scope == database.RBACScopeAll
+	}
+	return h.db.UserCanAccessResource(access.UserID, access.Scope, "conversation", conversationID)
+}

internal/handler/notification_rbac_test.go

@@ -0,0 +1,45 @@
+package handler
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func TestNotificationReadStateIsPerUser(t *testing.T) {
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "notification-rbac.db"), zap.NewNop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	h := NewNotificationHandler(db, nil, zap.NewNop())
+	router := gin.New()
+	router.Use(func(c *gin.Context) {
+		c.Set(security.ContextSessionKey, security.Session{UserID: "u1", Scope: database.RBACScopeAssigned})
+		c.Next()
+	})
+	router.POST("/notifications/read", h.MarkRead)
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/notifications/read", bytes.NewBufferString(`{"eventIds":["vuln:v1"]}`))
+	req.Header.Set("Content-Type", "application/json")
+	router.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("mark read status = %d: %s", w.Code, w.Body.String())
+	}
+	u1, err := h.readStatesByIDs("u1", []string{"vuln:v1"})
+	if err != nil || !u1["vuln:v1"] {
+		t.Fatalf("u1 read state = %#v, err=%v", u1, err)
+	}
+	u2, err := h.readStatesByIDs("u2", []string{"vuln:v1"})
+	if err != nil || u2["vuln:v1"] {
+		t.Fatalf("u2 inherited u1 read state = %#v, err=%v", u2, err)
+	}
+}

internal/handler/openapi_i18n.go

@@ -0,0 +1,190 @@
+package handler
+
+// apiDocI18n 为 OpenAPI 文档提供 x-i18n-* 扩展键，供前端 apiDocs 国际化使用。
+// 前端通过 apiDocs.tags.* / apiDocs.summary.* / apiDocs.response.* 翻译。
+
+var apiDocI18nTagToKey = map[string]string{
+	"认证": "auth", "对话管理": "conversationManagement", "对话交互": "conversationInteraction",
+	"批量任务": "batchTasks", "对话分组": "conversationGroups", "漏洞管理": "vulnerabilityManagement",
+	"角色管理": "roleManagement", "Skills管理": "skillsManagement", "监控": "monitoring",
+	"配置管理": "configManagement", "外部MCP管理": "externalMCPManagement", "攻击链": "attackChain",
+	"知识库": "knowledgeBase", "MCP": "mcp",
+	"FOFA信息收集": "fofaRecon", "终端": "terminal", "WebShell管理": "webshellManagement",
+	"对话附件": "chatUploads", "机器人集成": "robotIntegration", "多代理Markdown": "markdownAgents",
+	"项目管理": "projectManagement", "资产管理": "assetManagement",
+}
+
+var apiDocI18nSummaryToKey = map[string]string{
+	"用户登录": "login", "用户登出": "logout", "修改密码": "changePassword", "验证Token": "validateToken",
+	"创建对话": "createConversation", "列出对话": "listConversations", "查看对话详情": "getConversationDetail",
+	"更新对话": "updateConversation", "删除对话": "deleteConversation", "获取对话结果": "getConversationResult",
+	"发送消息并获取AI回复（非流式）": "sendMessageNonStream", "发送消息并获取AI回复（流式）": "sendMessageStream",
+	"取消任务": "cancelTask", "列出运行中的任务": "listRunningTasks", "列出已完成的任务": "listCompletedTasks",
+	"创建批量任务队列": "createBatchQueue", "列出批量任务队列": "listBatchQueues", "获取批量任务队列": "getBatchQueue",
+	"删除批量任务队列": "deleteBatchQueue", "启动批量任务队列": "startBatchQueue", "暂停批量任务队列": "pauseBatchQueue",
+	"添加任务到队列": "addTaskToQueue", "SQL注入扫描": "sqlInjectionScan", "端口扫描": "portScan",
+	"更新批量任务": "updateBatchTask", "删除批量任务": "deleteBatchTask",
+	"创建分组": "createGroup", "列出分组": "listGroups", "获取分组": "getGroup", "更新分组": "updateGroup",
+	"删除分组": "deleteGroup", "获取分组中的对话": "getGroupConversations", "添加对话到分组": "addConversationToGroup",
+	"从分组移除对话": "removeConversationFromGroup",
+	"列出漏洞":    "listVulnerabilities", "创建漏洞": "createVulnerability", "获取漏洞统计": "getVulnerabilityStats",
+	"获取漏洞": "getVulnerability", "更新漏洞": "updateVulnerability", "删除漏洞": "deleteVulnerability",
+	"列出角色": "listRoles", "创建角色": "createRole", "获取角色": "getRole", "更新角色": "updateRole", "删除角色": "deleteRole",
+	"获取可用Skills列表": "getAvailableSkills", "列出Skills": "listSkills", "创建Skill": "createSkill",
+	"获取Skill统计": "getSkillStats", "清空Skill统计": "clearSkillStats", "获取Skill": "getSkill",
+	"更新Skill": "updateSkill", "删除Skill": "deleteSkill", "获取绑定角色": "getBoundRoles",
+	"获取监控信息": "getMonitorInfo", "获取执行记录": "getExecutionRecords", "删除执行记录": "deleteExecutionRecord",
+	"批量删除执行记录": "batchDeleteExecutionRecords", "获取统计信息": "getStats",
+	"获取配置": "getConfig", "更新配置": "updateConfig", "获取工具配置": "getToolConfig", "应用配置": "applyConfig",
+	"列出外部MCP": "listExternalMCP", "获取外部MCP统计": "getExternalMCPStats", "获取外部MCP": "getExternalMCP",
+	"添加或更新外部MCP": "addOrUpdateExternalMCP", "stdio模式配置": "stdioModeConfig", "SSE模式配置": "sseModeConfig",
+	"删除外部MCP": "deleteExternalMCP", "启动外部MCP": "startExternalMCP", "停止外部MCP": "stopExternalMCP",
+	"获取攻击链": "getAttackChain", "重新生成攻击链": "regenerateAttackChain",
+	"设置对话置顶": "pinConversation", "设置分组置顶": "pinGroup", "设置分组中对话的置顶": "pinGroupConversation",
+	"获取分类": "getCategories", "列出知识项": "listKnowledgeItems", "创建知识项": "createKnowledgeItem",
+	"获取知识项": "getKnowledgeItem", "更新知识项": "updateKnowledgeItem", "删除知识项": "deleteKnowledgeItem",
+	"获取索引状态": "getIndexStatus", "构建索引": "startKnowledgeIndex", "扫描知识库": "scanKnowledgeBase",
+	"搜索知识库": "searchKnowledgeBase", "基础搜索": "basicSearch", "按风险类型搜索": "searchByRiskType",
+	"获取检索日志": "getRetrievalLogs", "删除检索日志": "deleteRetrievalLog",
+	"MCP端点": "mcpEndpoint", "列出所有工具": "listAllTools", "调用工具": "invokeTool", "初始化连接": "initConnection",
+	"成功响应": "successResponse", "错误响应": "errorResponse",
+	// 新增缺失端点
+	"删除对话轮次": "deleteConversationTurn", "获取消息过程详情": "getMessageProcessDetails",
+	"重跑批量任务队列": "rerunBatchQueue", "修改队列元数据": "updateBatchQueueMetadata",
+	"修改队列调度配置": "updateBatchQueueSchedule", "开关Cron自动调度": "setBatchQueueScheduleEnabled",
+	"获取所有分组映射": "getAllGroupMappings",
+	"FOFA搜索":   "fofaSearch", "自然语言解析为FOFA语法": "fofaParse",
+	"测试OpenAI API连接": "testOpenAI",
+	"执行终端命令":         "terminalRun", "流式执行终端命令": "terminalRunStream", "WebSocket终端": "terminalWS",
+	"列出WebShell连接": "listWebshellConnections", "创建WebShell连接": "createWebshellConnection",
+	"更新WebShell连接": "updateWebshellConnection", "删除WebShell连接": "deleteWebshellConnection",
+	"获取连接状态": "getWebshellConnectionState", "保存连接状态": "saveWebshellConnectionState",
+	"获取AI对话历史": "getWebshellAIHistory", "列出AI对话": "listWebshellAIConversations",
+	"执行WebShell命令": "webshellExec", "WebShell文件操作": "webshellFileOp",
+	"列出附件": "listChatUploads", "导出附件": "exportChatUploads", "上传附件": "uploadChatFile", "删除附件": "deleteChatUpload",
+	"下载附件": "downloadChatUpload", "获取附件文本内容": "getChatUploadContent",
+	"写入附件文本内容": "putChatUploadContent", "创建附件目录": "mkdirChatUpload", "重命名附件": "renameChatUpload",
+	"企业微信回调验证": "wecomCallbackVerify", "企业微信消息回调": "wecomCallbackMessage",
+	"钉钉消息回调": "dingtalkCallback", "飞书消息回调": "larkCallback", "测试机器人消息处理": "testRobot",
+	"列出Markdown代理": "listMarkdownAgents", "创建Markdown代理": "createMarkdownAgent",
+	"获取Markdown代理详情": "getMarkdownAgent", "更新Markdown代理": "updateMarkdownAgent", "删除Markdown代理": "deleteMarkdownAgent",
+	"列出技能包文件": "listSkillPackageFiles", "获取技能包文件内容": "getSkillPackageFile", "写入技能包文件": "putSkillPackageFile",
+	"批量获取工具名称": "batchGetToolNames",
+	"获取知识库统计":  "getKnowledgeStats",
+	"列出项目":     "listProjects", "创建项目": "createProject", "获取项目": "getProject",
+	"更新项目": "updateProject", "删除项目": "deleteProject",
+	"批量导入资产":        "importAssets",
+	"列出或按 key 获取事实": "listProjectFacts", "创建/更新事实": "upsertProjectFact",
+	"获取项目事实攻击路径图": "getProjectFactGraph", "列出项目全部事实边": "listProjectFactEdges",
+	"添加事实边": "createProjectFactEdge", "删除事实边": "deleteProjectFactEdge",
+	"将对话攻击链沉淀到项目事实图": "promoteAttackChainToProject",
+}
+
+var apiDocI18nResponseDescToKey = map[string]string{
+	"获取成功": "getSuccess", "未授权": "unauthorized", "未授权，需要有效的Token": "unauthorizedToken",
+	"创建成功": "createSuccess", "请求参数错误": "badRequest", "对话不存在": "conversationNotFound",
+	"对话不存在或结果不存在": "conversationOrResultNotFound", "请求参数错误（如task为空）": "badRequestTaskEmpty",
+	"请求参数错误或分组名称已存在": "badRequestGroupNameExists", "分组不存在": "groupNotFound",
+	"请求参数错误（如配置格式不正确、缺少必需字段等）": "badRequestConfig",
+	"请求参数错误（如query为空）":         "badRequestQueryEmpty", "方法不允许（仅支持POST请求）": "methodNotAllowed",
+	"登录成功": "loginSuccess", "密码错误": "invalidPassword", "登出成功": "logoutSuccess",
+	"密码修改成功": "passwordChanged", "Token有效": "tokenValid", "Token无效或已过期": "tokenInvalid",
+	"对话创建成功": "conversationCreated", "服务器内部错误": "internalError", "更新成功": "updateSuccess",
+	"删除成功": "deleteSuccess", "队列不存在": "queueNotFound", "启动成功": "startSuccess",
+	"暂停成功": "pauseSuccess", "添加成功": "addSuccess",
+	"任务不存在": "taskNotFound", "对话或分组不存在": "conversationOrGroupNotFound",
+	"取消请求已提交": "cancelSubmitted", "未找到正在执行的任务": "noRunningTask",
+	"消息发送成功，返回AI回复": "messageSent", "流式响应（Server-Sent Events）": "streamResponse",
+	// 新增缺失端点响应
+	"参数错误或删除失败": "badRequestOrDeleteFailed",
+	"参数错误":      "paramError", "仅已完成或已取消的队列可以重跑": "onlyCompletedOrCancelledCanRerun",
+	"参数错误或队列正在运行中": "badRequestOrQueueRunning", "设置成功": "setSuccess",
+	"搜索成功": "searchSuccess", "解析成功": "parseSuccess", "测试结果": "testResult",
+	"执行完成": "executionDone", "SSE事件流": "sseEventStream", "WebSocket连接已建立": "wsEstablished",
+	"文件下载": "fileDownload", "文件不存在": "fileNotFound", "写入成功": "writeSuccess",
+	"重命名成功": "renameSuccess", "验证成功，返回解密后的echostr": "wecomVerifySuccess",
+	"处理成功": "processSuccess", "代理不存在": "agentNotFound", "保存成功": "saveSuccess",
+	"操作结果": "operationResult", "执行结果": "executionResult", "连接不存在": "connectionNotFound",
+	"项目列表": "projectList", "项目详情": "projectDetail",
+	"事实列表或单条（可含 link_counts / outgoing_links）": "projectFactList",
+	"成功": "success", "nodes + edges": "factGraphNodesEdges",
+	"边列表": "edgeList", "边已创建": "edgeCreated",
+	"沉淀结果（facts/edges/graph）": "promoteAttackChainResult",
+	"导入完成":                    "assetImportCompleted", "数量或资产字段校验失败": "assetImportValidationFailed",
+	"缺少 asset:write 权限或无权访问指定项目": "assetImportForbidden",
+	"导入事务失败": "assetImportTransactionFailed",
+}
+
+// enrichSpecWithI18nKeys 在 spec 的每个 operation 上写入 x-i18n-tags、x-i18n-summary，
+// 在每个 response 上写入 x-i18n-description，供前端按 key 做国际化。
+func enrichSpecWithI18nKeys(spec map[string]interface{}) {
+	paths, _ := spec["paths"].(map[string]interface{})
+	if paths == nil {
+		return
+	}
+	for _, pathItem := range paths {
+		pm, _ := pathItem.(map[string]interface{})
+		if pm == nil {
+			continue
+		}
+		for _, method := range []string{"get", "post", "put", "delete", "patch"} {
+			opVal, ok := pm[method]
+			if !ok {
+				continue
+			}
+			op, _ := opVal.(map[string]interface{})
+			if op == nil {
+				continue
+			}
+			// x-i18n-tags: 与 tags 一一对应的 i18n 键数组（spec 中 tags 为 []string）
+			switch tags := op["tags"].(type) {
+			case []string:
+				if len(tags) > 0 {
+					keys := make([]string, 0, len(tags))
+					for _, s := range tags {
+						if k := apiDocI18nTagToKey[s]; k != "" {
+							keys = append(keys, k)
+						} else {
+							keys = append(keys, s)
+						}
+					}
+					op["x-i18n-tags"] = keys
+				}
+			case []interface{}:
+				if len(tags) > 0 {
+					keys := make([]interface{}, 0, len(tags))
+					for _, t := range tags {
+						if s, ok := t.(string); ok {
+							if k := apiDocI18nTagToKey[s]; k != "" {
+								keys = append(keys, k)
+							} else {
+								keys = append(keys, s)
+							}
+						}
+					}
+					if len(keys) > 0 {
+						op["x-i18n-tags"] = keys
+					}
+				}
+			}
+			// x-i18n-summary
+			if summary, _ := op["summary"].(string); summary != "" {
+				if k := apiDocI18nSummaryToKey[summary]; k != "" {
+					op["x-i18n-summary"] = k
+				}
+			}
+			// responses -> 每个 status -> x-i18n-description
+			if respMap, _ := op["responses"].(map[string]interface{}); respMap != nil {
+				for _, rv := range respMap {
+					if r, _ := rv.(map[string]interface{}); r != nil {
+						if desc, _ := r["description"].(string); desc != "" {
+							if k := apiDocI18nResponseDescToKey[desc]; k != "" {
+								r["x-i18n-description"] = k
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

internal/handler/openapi_i18n_test.go

@@ -0,0 +1,46 @@
+package handler
+
+import "testing"
+
+func TestEnrichSpecWithI18nKeysForAssetImport(t *testing.T) {
+	responses := map[string]interface{}{
+		"200": map[string]interface{}{"description": "导入完成"},
+		"400": map[string]interface{}{"description": "数量或资产字段校验失败"},
+		"403": map[string]interface{}{"description": "缺少 asset:write 权限或无权访问指定项目"},
+		"500": map[string]interface{}{"description": "导入事务失败"},
+	}
+	operation := map[string]interface{}{
+		"tags":      []string{"资产管理"},
+		"summary":   "批量导入资产",
+		"responses": responses,
+	}
+	spec := map[string]interface{}{
+		"paths": map[string]interface{}{
+			"/api/assets/import": map[string]interface{}{
+				"post": operation,
+			},
+		},
+	}
+
+	enrichSpecWithI18nKeys(spec)
+
+	tagKeys, ok := operation["x-i18n-tags"].([]string)
+	if !ok || len(tagKeys) != 1 || tagKeys[0] != "assetManagement" {
+		t.Fatalf("unexpected asset tag i18n keys: %#v", operation["x-i18n-tags"])
+	}
+	if got := operation["x-i18n-summary"]; got != "importAssets" {
+		t.Fatalf("unexpected asset summary i18n key: %#v", got)
+	}
+	expectedResponseKeys := map[string]string{
+		"200": "assetImportCompleted",
+		"400": "assetImportValidationFailed",
+		"403": "assetImportForbidden",
+		"500": "assetImportTransactionFailed",
+	}
+	for status, want := range expectedResponseKeys {
+		response := responses[status].(map[string]interface{})
+		if got := response["x-i18n-description"]; got != want {
+			t.Errorf("unexpected asset response i18n key for %s: got %#v, want %q", status, got, want)
+		}
+	}
+}

internal/handler/project.go

@@ -0,0 +1,657 @@
+package handler
+
+import (
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"cyberstrike-ai/internal/attackchain"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/project"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+const maxProjectDescriptionRunes = 4000
+
+func clampProjectDescription(s string) string {
+	r := []rune(s)
+	if len(r) <= maxProjectDescriptionRunes {
+		return s
+	}
+	return string(r[:maxProjectDescriptionRunes])
+}
+
+// ProjectHandler 项目管理处理器。
+type ProjectHandler struct {
+	db     *database.DB
+	logger *zap.Logger
+}
+
+// NewProjectHandler 创建项目管理处理器。
+func NewProjectHandler(db *database.DB, logger *zap.Logger) *ProjectHandler {
+	return &ProjectHandler{db: db, logger: logger}
+}
+
+type createProjectRequest struct {
+	Name        string `json:"name" binding:"required"`
+	Description string `json:"description"`
+	ScopeJSON   string `json:"scope_json"`
+	Status      string `json:"status"`
+}
+
+// updateProjectRequest 部分更新：字段省略表示不修改；传 null 或 "" 可清空字符串字段。
+type updateProjectRequest struct {
+	Name        *string `json:"name"`
+	Description *string `json:"description"`
+	ScopeJSON   *string `json:"scope_json"`
+	Status      *string `json:"status"`
+	Pinned      *bool   `json:"pinned"`
+}
+
+// CreateProject POST /api/projects
+func (h *ProjectHandler) CreateProject(c *gin.Context) {
+	var req createProjectRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	p := &database.Project{
+		Name:        strings.TrimSpace(req.Name),
+		Description: clampProjectDescription(req.Description),
+		ScopeJSON:   req.ScopeJSON,
+		Status:      strings.TrimSpace(req.Status),
+	}
+	created, err := h.db.CreateProject(p)
+	if err != nil {
+		h.logger.Error("创建项目失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if session, ok := security.CurrentSession(c); ok {
+		_ = h.db.SetResourceOwner("project", created.ID, session.UserID)
+		_ = h.db.AssignResourceToUser(session.UserID, "project", created.ID)
+	}
+	c.JSON(http.StatusOK, created)
+}
+
+// GetDashboardSummary GET /api/projects/dashboard-summary
+func (h *ProjectHandler) GetDashboardSummary(c *gin.Context) {
+	limit, _ := strconv.Atoi(strings.TrimSpace(c.DefaultQuery("fact_limit", "5")))
+	if limit <= 0 {
+		limit = 5
+	}
+	if limit > 50 {
+		limit = 50
+	}
+	session, _ := security.CurrentSession(c)
+	summary, err := h.db.GetProjectDashboardSummaryForAccess(limit, session.UserID, session.Scope)
+	if err != nil {
+		h.logger.Error("获取项目仪表盘摘要失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if summary.RecentFacts == nil {
+		summary.RecentFacts = []database.ProjectDashboardFact{}
+	}
+	c.JSON(http.StatusOK, summary)
+}
+
+// ListProjects GET /api/projects
+func (h *ProjectHandler) ListProjects(c *gin.Context) {
+	status := c.Query("status")
+	search := c.Query("search")
+	limit, _ := strconv.Atoi(c.DefaultQuery("limit", "50"))
+	offset, _ := strconv.Atoi(c.Query("offset"))
+	if limit <= 0 {
+		limit = 50
+	}
+	if limit > 500 {
+		limit = 500
+	}
+	session, _ := security.CurrentSession(c)
+	list, err := h.db.ListProjectsForAccess(status, search, limit, offset, session.UserID, session.Scope)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if list == nil {
+		list = []*database.Project{}
+	}
+	total, err := h.db.CountProjectsForAccess(status, search, session.UserID, session.Scope)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"projects": list,
+		"total":    total,
+		"limit":    limit,
+		"offset":   offset,
+	})
+}
+
+// GetProjectStats GET /api/projects/:id/stats
+func (h *ProjectHandler) GetProjectStats(c *gin.Context) {
+	stats, err := project.GetProjectStats(h.db, c.Param("id"))
+	if err != nil {
+		if strings.Contains(err.Error(), "不存在") {
+			c.JSON(http.StatusNotFound, gin.H{"error": "项目不存在"})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, stats)
+}
+
+// ListProjectConversations GET /api/projects/:id/conversations
+func (h *ProjectHandler) ListProjectConversations(c *gin.Context) {
+	projectID := c.Param("id")
+	if _, err := h.db.GetProject(projectID); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "项目不存在"})
+		return
+	}
+	limit, _ := strconv.Atoi(c.DefaultQuery("limit", "100"))
+	offset, _ := strconv.Atoi(c.Query("offset"))
+	list, err := h.db.ListConversationsByProjectID(projectID, limit, offset)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if list == nil {
+		list = []*database.Conversation{}
+	}
+	total, _ := h.db.CountConversationsByProjectID(projectID)
+	c.JSON(http.StatusOK, gin.H{
+		"conversations": list,
+		"total":         total,
+		"limit":         limit,
+		"offset":        offset,
+	})
+}
+
+// GetProject GET /api/projects/:id
+func (h *ProjectHandler) GetProject(c *gin.Context) {
+	p, err := h.db.GetProject(c.Param("id"))
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "项目不存在"})
+		return
+	}
+	c.JSON(http.StatusOK, p)
+}
+
+// UpdateProject PUT /api/projects/:id
+func (h *ProjectHandler) UpdateProject(c *gin.Context) {
+	id := c.Param("id")
+	p, err := h.db.GetProject(id)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "项目不存在"})
+		return
+	}
+	var req updateProjectRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if req.Name != nil {
+		if s := strings.TrimSpace(*req.Name); s != "" {
+			p.Name = s
+		}
+	}
+	if req.Description != nil {
+		p.Description = clampProjectDescription(*req.Description)
+	}
+	if req.ScopeJSON != nil {
+		p.ScopeJSON = *req.ScopeJSON
+	}
+	if req.Status != nil {
+		if s := strings.TrimSpace(*req.Status); s != "" {
+			p.Status = s
+		}
+	}
+	if req.Pinned != nil {
+		p.Pinned = *req.Pinned
+	}
+	if err := h.db.UpdateProject(p); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, p)
+}
+
+// DeleteProject DELETE /api/projects/:id
+func (h *ProjectHandler) DeleteProject(c *gin.Context) {
+	if err := h.db.DeleteProject(c.Param("id")); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true})
+}
+
+type factLinkRequest struct {
+	From       string `json:"from"`
+	Type       string `json:"type"`
+	Confidence string `json:"confidence,omitempty"`
+}
+
+type upsertFactRequest struct {
+	FactKey                string            `json:"fact_key" binding:"required"`
+	Category               string            `json:"category"`
+	Summary                string            `json:"summary" binding:"required"`
+	Body                   string            `json:"body"`
+	Confidence             string            `json:"confidence"`
+	Pinned                 bool              `json:"pinned"`
+	RelatedVulnerabilityID string            `json:"related_vulnerability_id"`
+	Links                  []factLinkRequest `json:"links"`
+	LinksText              *string           `json:"links_text"`
+}
+
+// updateFactRequest 部分更新事实；指针字段省略=不修改，body 传 "" 可清空（仍走 merge 逻辑见 Upsert）。
+type updateFactRequest struct {
+	FactKey                *string            `json:"fact_key"`
+	Category               *string            `json:"category"`
+	Summary                *string            `json:"summary"`
+	Body                   *string            `json:"body"`
+	Confidence             *string            `json:"confidence"`
+	Pinned                 *bool              `json:"pinned"`
+	RelatedVulnerabilityID *string            `json:"related_vulnerability_id"`
+	ClearBody              bool               `json:"clear_body"`
+	Links                  *[]factLinkRequest `json:"links"`
+	LinksText              *string            `json:"links_text"`
+}
+
+func factLinksFromRequest(links []factLinkRequest, linksText *string) (*project.ParsedFactLinks, error) {
+	if len(links) > 0 {
+		parsed := &project.ParsedFactLinks{}
+		for i, l := range links {
+			from := strings.TrimSpace(l.From)
+			edgeType := strings.TrimSpace(l.Type)
+			if from == "" {
+				return nil, fmt.Errorf("links[%d] 须含 from", i)
+			}
+			if edgeType == "" {
+				return nil, fmt.Errorf("links[%d] 须含 type", i)
+			}
+			parsed.Incoming = append(parsed.Incoming, database.ProjectFactEdgeFromInput{
+				From: from, Type: edgeType, Confidence: strings.TrimSpace(l.Confidence),
+			})
+		}
+		return parsed, nil
+	}
+	if linksText != nil {
+		in, err := project.ParseFactLinksText(*linksText)
+		if err != nil {
+			return nil, err
+		}
+		return &project.ParsedFactLinks{Incoming: in}, nil
+	}
+	return &project.ParsedFactLinks{Incoming: []database.ProjectFactEdgeFromInput{}}, nil
+}
+
+type factWithLinksResponse struct {
+	*database.ProjectFact
+	OutgoingLinks []*database.ProjectFactEdge `json:"outgoing_links,omitempty"`
+	IncomingLinks []*database.ProjectFactEdge `json:"incoming_links,omitempty"`
+	LinkCounts    *project.LinkCounts         `json:"link_counts,omitempty"`
+}
+
+func (h *ProjectHandler) applyFactLinksAfterUpsert(projectID string, fact *database.ProjectFact, links []factLinkRequest, linksText *string, explicitLinks, parseBody bool) error {
+	if explicitLinks {
+		parsed, err := factLinksFromRequest(links, linksText)
+		if err != nil {
+			return err
+		}
+		return project.PersistFactLinksFromParsed(h.db, projectID, fact.FactKey, fact.SourceConversationID, parsed, true)
+	}
+	if parseBody {
+		inputs := project.ParseLinksFromBody(fact.Body)
+		if inputs == nil {
+			return nil
+		}
+		return project.PersistFactIncomingLinks(h.db, projectID, fact.FactKey, inputs, true)
+	}
+	return nil
+}
+
+func (h *ProjectHandler) factResponseWithLinks(projectID string, f *database.ProjectFact, includeLinks bool) interface{} {
+	if !includeLinks || f == nil {
+		return f
+	}
+	out, _ := h.db.ListOutgoingProjectFactEdges(projectID, f.FactKey)
+	in, _ := h.db.ListIncomingProjectFactEdges(projectID, f.FactKey)
+	return &factWithLinksResponse{
+		ProjectFact:   f,
+		OutgoingLinks: out,
+		IncomingLinks: in,
+	}
+}
+
+// ListFacts GET /api/projects/:id/facts （fact_key 查询参数可获取单条详情）
+func (h *ProjectHandler) ListFacts(c *gin.Context) {
+	projectID := c.Param("id")
+	if key := strings.TrimSpace(c.Query("fact_key")); key != "" {
+		f, err := h.db.GetProjectFactByKey(projectID, key)
+		if err != nil {
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+			return
+		}
+		includeLinks := c.Query("include_links") == "1" || c.Query("include_links") == "true"
+		c.JSON(http.StatusOK, h.factResponseWithLinks(projectID, f, includeLinks))
+		return
+	}
+	limit, _ := strconv.Atoi(c.DefaultQuery("limit", "100"))
+	offset, _ := strconv.Atoi(c.Query("offset"))
+	filter := database.ProjectFactListFilter{
+		Category:               c.Query("category"),
+		Confidence:             c.Query("confidence"),
+		Search:                 c.Query("search"),
+		RelatedVulnerabilityID: c.Query("related_vulnerability_id"),
+	}
+	if c.Query("exclude_deprecated") == "1" || c.Query("exclude_deprecated") == "true" {
+		filter.ExcludeDeprecated = true
+	}
+	list, err := h.db.ListProjectFacts(projectID, filter, limit, offset)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if list == nil {
+		list = []*database.ProjectFact{}
+	}
+	if sparseOnly := c.Query("sparse_only"); sparseOnly == "1" || sparseOnly == "true" {
+		filtered := make([]*database.ProjectFact, 0, len(list))
+		for _, f := range list {
+			if project.IsSparseFactBody(f.Category, f.FactKey, f.Body) {
+				filtered = append(filtered, f)
+			}
+		}
+		list = filtered
+	}
+	includeLinkCounts := c.Query("include_link_counts") == "1" || c.Query("include_link_counts") == "true"
+	if !includeLinkCounts {
+		c.JSON(http.StatusOK, list)
+		return
+	}
+	counts, err := project.LoadProjectFactLinkCounts(h.db, projectID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	out := make([]factWithLinksResponse, 0, len(list))
+	for _, f := range list {
+		item := factWithLinksResponse{ProjectFact: f}
+		if c, ok := counts[f.FactKey]; ok {
+			cc := c
+			item.LinkCounts = &cc
+		}
+		out = append(out, item)
+	}
+	c.JSON(http.StatusOK, out)
+}
+
+// GetFactGraph GET /api/projects/:id/fact-graph?view=path|full
+func (h *ProjectHandler) GetFactGraph(c *gin.Context) {
+	projectID := c.Param("id")
+	if _, err := h.db.GetProject(projectID); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "项目不存在"})
+		return
+	}
+	view := c.DefaultQuery("view", "path")
+	excludeDeprecated := true
+	if v := c.Query("exclude_deprecated"); v == "0" || v == "false" {
+		excludeDeprecated = false
+	}
+	graph, err := project.BuildProjectFactGraph(h.db, projectID, view, excludeDeprecated)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if graph.Nodes == nil {
+		graph.Nodes = []database.ProjectFactGraphNode{}
+	}
+	if graph.Edges == nil {
+		graph.Edges = []database.ProjectFactGraphEdge{}
+	}
+	c.JSON(http.StatusOK, graph)
+}
+
+// CreateFact POST /api/projects/:id/facts
+func (h *ProjectHandler) CreateFact(c *gin.Context) {
+	var req upsertFactRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	projectID := c.Param("id")
+	f := &database.ProjectFact{
+		ProjectID:              projectID,
+		FactKey:                req.FactKey,
+		Category:               req.Category,
+		Summary:                req.Summary,
+		Body:                   req.Body,
+		Confidence:             req.Confidence,
+		Pinned:                 req.Pinned,
+		RelatedVulnerabilityID: req.RelatedVulnerabilityID,
+	}
+	created, err := h.db.UpsertProjectFact(f)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	explicitLinks := req.Links != nil || req.LinksText != nil
+	if err := h.applyFactLinksAfterUpsert(projectID, created, req.Links, req.LinksText, explicitLinks, !explicitLinks); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	created, _ = h.db.GetProjectFactByKey(projectID, created.FactKey)
+	c.JSON(http.StatusOK, h.factResponseWithLinks(projectID, created, true))
+}
+
+// UpdateFact PUT /api/projects/:id/facts/:factId
+func (h *ProjectHandler) UpdateFact(c *gin.Context) {
+	projectID := c.Param("id")
+	existing, err := h.db.GetProjectFact(c.Param("factId"))
+	if err != nil || existing.ProjectID != projectID {
+		c.JSON(http.StatusNotFound, gin.H{"error": "事实不存在"})
+		return
+	}
+	oldFactKey := existing.FactKey
+	var req updateFactRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if req.FactKey != nil {
+		if k := strings.TrimSpace(*req.FactKey); k != "" {
+			existing.FactKey = k
+		}
+	}
+	if req.Category != nil && strings.TrimSpace(*req.Category) != "" {
+		existing.Category = *req.Category
+	}
+	if req.Summary != nil && strings.TrimSpace(*req.Summary) != "" {
+		existing.Summary = *req.Summary
+	}
+	if req.ClearBody {
+		existing.Body = ""
+	} else if req.Body != nil {
+		existing.Body = *req.Body
+	}
+	if req.Confidence != nil && strings.TrimSpace(*req.Confidence) != "" {
+		existing.Confidence = *req.Confidence
+	}
+	if req.Pinned != nil {
+		existing.Pinned = *req.Pinned
+	}
+	if req.RelatedVulnerabilityID != nil {
+		existing.RelatedVulnerabilityID = *req.RelatedVulnerabilityID
+	}
+	updated, err := h.db.UpsertProjectFact(existing)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if oldFactKey != updated.FactKey {
+		if err := h.db.RenameProjectFactKeyEdges(projectID, oldFactKey, updated.FactKey); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+	}
+	if req.Links != nil || req.LinksText != nil {
+		var links []factLinkRequest
+		if req.Links != nil {
+			links = *req.Links
+		}
+		if err := h.applyFactLinksAfterUpsert(projectID, updated, links, req.LinksText, true, false); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+	} else if req.ClearBody || req.Body != nil {
+		if err := h.applyFactLinksAfterUpsert(projectID, updated, nil, nil, false, true); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+	}
+	updated, _ = h.db.GetProjectFactByKey(projectID, updated.FactKey)
+	c.JSON(http.StatusOK, h.factResponseWithLinks(projectID, updated, true))
+}
+
+// DeleteFact DELETE /api/projects/:id/facts/:factId
+func (h *ProjectHandler) DeleteFact(c *gin.Context) {
+	existing, err := h.db.GetProjectFact(c.Param("factId"))
+	if err != nil || existing.ProjectID != c.Param("id") {
+		c.JSON(http.StatusNotFound, gin.H{"error": "事实不存在"})
+		return
+	}
+	if err := h.db.DeleteProjectFact(existing.ID); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true})
+}
+
+type deprecateFactRequest struct {
+	FactKey string `json:"fact_key" binding:"required"`
+}
+
+// DeprecateFact POST /api/projects/:id/facts/deprecate
+func (h *ProjectHandler) DeprecateFact(c *gin.Context) {
+	var req deprecateFactRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if err := h.db.DeprecateProjectFact(c.Param("id"), req.FactKey); err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true})
+}
+
+type restoreFactRequest struct {
+	FactKey    string `json:"fact_key" binding:"required"`
+	Confidence string `json:"confidence"` // 可选：confirmed | tentative，默认 tentative
+}
+
+// RestoreFact POST /api/projects/:id/facts/restore
+func (h *ProjectHandler) RestoreFact(c *gin.Context) {
+	var req restoreFactRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if err := h.db.RestoreProjectFact(c.Param("id"), req.FactKey, req.Confidence); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true})
+}
+
+type createFactEdgeRequest struct {
+	SourceFactKey string `json:"source_fact_key" binding:"required"`
+	TargetFactKey string `json:"target_fact_key" binding:"required"`
+	EdgeType      string `json:"edge_type" binding:"required"`
+	Confidence    string `json:"confidence"`
+}
+
+// ListFactEdges GET /api/projects/:id/fact-edges
+func (h *ProjectHandler) ListFactEdges(c *gin.Context) {
+	projectID := c.Param("id")
+	edges, err := h.db.ListProjectFactEdgesByProject(projectID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if edges == nil {
+		edges = []*database.ProjectFactEdge{}
+	}
+	c.JSON(http.StatusOK, edges)
+}
+
+// CreateFactEdge POST /api/projects/:id/fact-edges
+func (h *ProjectHandler) CreateFactEdge(c *gin.Context) {
+	projectID := c.Param("id")
+	var req createFactEdgeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	edge, err := h.db.AddProjectFactEdge(projectID, database.ProjectFactEdgeInput{
+		To:         req.TargetFactKey,
+		Type:       req.EdgeType,
+		Confidence: req.Confidence,
+	}, req.SourceFactKey, "")
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if f, err := h.db.GetProjectFactByKey(projectID, req.TargetFactKey); err == nil {
+		in, _ := h.db.ListIncomingProjectFactEdges(projectID, req.TargetFactKey)
+		f.Body = project.SyncBodyLinksSection(f.Body, in)
+		_, _ = h.db.UpsertProjectFact(f)
+	}
+	c.JSON(http.StatusOK, edge)
+}
+
+// DeleteFactEdge DELETE /api/projects/:id/fact-edges/:edgeId
+func (h *ProjectHandler) DeleteFactEdge(c *gin.Context) {
+	projectID := c.Param("id")
+	edgeID := c.Param("edgeId")
+	edge, err := h.db.GetProjectFactEdge(edgeID)
+	if err != nil || edge.ProjectID != projectID {
+		c.JSON(http.StatusNotFound, gin.H{"error": "边不存在"})
+		return
+	}
+	if err := h.db.DeleteProjectFactEdge(edgeID); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if f, err := h.db.GetProjectFactByKey(projectID, edge.TargetFactKey); err == nil {
+		in, _ := h.db.ListIncomingProjectFactEdges(projectID, edge.TargetFactKey)
+		f.Body = project.SyncBodyLinksSection(f.Body, in)
+		_, _ = h.db.UpsertProjectFact(f)
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true})
+}
+
+// PromoteAttackChain POST /api/projects/:id/promote-attack-chain/:conversationId
+func (h *ProjectHandler) PromoteAttackChain(c *gin.Context) {
+	projectID := c.Param("id")
+	conversationID := c.Param("conversationId")
+	session, ok := security.CurrentSession(c)
+	if !ok || !h.db.UserCanAccessResource(session.UserID, session.Scope, "project", projectID) ||
+		!h.db.UserCanAccessResource(session.UserID, session.Scope, "conversation", conversationID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问目标项目或来源对话"})
+		return
+	}
+	result, err := attackchain.PromoteToProject(h.db, projectID, conversationID)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, result)
+}

internal/handler/project_context.go

@@ -0,0 +1,85 @@
+package handler
+
+import (
+	"strings"
+
+	"cyberstrike-ai/internal/project"
+	"go.uber.org/zap"
+)
+
+// agentSessionContextBlock 注入会话工作目录与项目黑板（用于 system prompt 追加块）。
+// 用户输入由 message history 承载；压缩后由 summarization 摘要指令保留关键约束。
+func (h *AgentHandler) agentSessionContextBlock(conversationID string) string {
+	var parts []string
+	if ws := h.buildWorkspaceBlock(conversationID); ws != "" {
+		parts = append(parts, ws)
+	}
+	if bb := h.projectBlackboardBlock(conversationID); bb != "" {
+		parts = append(parts, bb)
+	}
+	return strings.Join(parts, "\n\n")
+}
+
+func (h *AgentHandler) buildWorkspaceBlock(conversationID string) string {
+	if h == nil || h.config == nil {
+		return ""
+	}
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" {
+		return ""
+	}
+	projectID := h.conversationProjectID(conversationID)
+	rel := project.WorkspaceRootDir(h.config.Agent.WorkspaceRootDir, projectID, conversationID)
+	abs, err := project.EnsureWorkspace(rel)
+	if err != nil {
+		if h.logger != nil {
+			h.logger.Warn("创建会话工作目录失败",
+				zap.String("conversationId", conversationID),
+				zap.String("projectId", projectID),
+				zap.String("path", rel),
+				zap.Error(err))
+		}
+		return ""
+	}
+	return project.BuildWorkspaceBlock(abs)
+}
+
+// projectBlackboardBlock 根据对话 ID 构建项目事实索引块（用于注入 system prompt）。
+func (h *AgentHandler) projectBlackboardBlock(conversationID string) string {
+	if h == nil || h.db == nil || h.config == nil {
+		return ""
+	}
+	if !h.config.Project.Enabled {
+		return ""
+	}
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" {
+		return ""
+	}
+	projectID, err := h.db.GetConversationProjectID(conversationID)
+	if err != nil || projectID == "" {
+		return ""
+	}
+	block, err := project.BuildProjectBlackboardBlock(h.db, projectID, h.config.Project)
+	if err != nil {
+		h.logger.Warn("构建项目黑板索引失败", zap.String("conversationId", conversationID), zap.Error(err))
+		return ""
+	}
+	return strings.TrimSpace(block)
+}
+
+// conversationProjectID 返回对话绑定的项目 ID；未绑定或查询失败时返回空字符串。
+func (h *AgentHandler) conversationProjectID(conversationID string) string {
+	if h == nil || h.db == nil {
+		return ""
+	}
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" {
+		return ""
+	}
+	projectID, err := h.db.GetConversationProjectID(conversationID)
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(projectID)
+}

internal/handler/project_resolve.go

@@ -0,0 +1,18 @@
+package handler
+
+import (
+	"strings"
+
+	"cyberstrike-ai/internal/config"
+)
+
+// effectiveProjectID 请求/队列显式项目优先，否则使用 config.project.default_project_id。
+func effectiveProjectID(cfg *config.Config, explicit string) string {
+	if pid := strings.TrimSpace(explicit); pid != "" {
+		return pid
+	}
+	if cfg != nil {
+		return strings.TrimSpace(cfg.Project.DefaultProjectID)
+	}
+	return ""
+}

internal/handler/rbac.go

@@ -0,0 +1,429 @@
+package handler
+
+import (
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/authctx"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+type RBACHandler struct {
+	db     *database.DB
+	logger *zap.Logger
+	audit  *audit.Service
+	auth   *security.AuthManager
+}
+
+func NewRBACHandler(db *database.DB, logger *zap.Logger) *RBACHandler {
+	return &RBACHandler{db: db, logger: logger}
+}
+
+func (h *RBACHandler) SetAudit(s *audit.Service) {
+	h.audit = s
+}
+
+func (h *RBACHandler) SetAuthManager(m *security.AuthManager) {
+	h.auth = m
+}
+
+func (h *RBACHandler) Me(c *gin.Context) {
+	session, _ := security.CurrentSession(c)
+	resolvedScope := session.Scope
+	permissionScopes := session.PermissionScopes
+	if principal, ok := authctx.PrincipalFromContext(c.Request.Context()); ok {
+		resolvedScope = principal.Scope
+		permissionScopes = principal.PermissionScopes
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"user": gin.H{
+			"id":           session.UserID,
+			"username":     session.Username,
+			"display_name": session.DisplayName,
+		},
+		"roles":             session.Roles,
+		"permissions":       permissionKeys(session.Permissions),
+		"scope":             resolvedScope,
+		"permission_scopes": permissionScopes,
+	})
+}
+
+func (h *RBACHandler) Metadata(c *gin.Context) {
+	roles, err := h.db.ListRBACRoles()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	rolePermissions := map[string][]string{}
+	for _, role := range roles {
+		keys, _ := h.db.ListRBACRolePermissionKeys(role.ID)
+		rolePermissions[role.ID] = keys
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"permissions":      security.PermissionCatalog,
+		"roles":            roles,
+		"role_permissions": rolePermissions,
+		"scopes":           []string{database.RBACScopeAll, database.RBACScopeAssigned, database.RBACScopeOwn},
+	})
+}
+
+func (h *RBACHandler) ListRoles(c *gin.Context) {
+	roles, err := h.db.ListRBACRoles()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	out := make([]gin.H, 0, len(roles))
+	for _, role := range roles {
+		keys, _ := h.db.ListRBACRolePermissionKeys(role.ID)
+		out = append(out, gin.H{
+			"id":          role.ID,
+			"name":        role.Name,
+			"description": role.Description,
+			"scope":       role.Scope,
+			"is_system":   role.IsSystem,
+			"permissions": keys,
+			"created_at":  role.CreatedAt,
+			"updated_at":  role.UpdatedAt,
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{"roles": out})
+}
+
+type upsertRBACRoleRequest struct {
+	ID          string   `json:"id"`
+	Name        string   `json:"name" binding:"required"`
+	Description string   `json:"description"`
+	Scope       string   `json:"scope"`
+	Permissions []string `json:"permissions"`
+}
+
+func validateRBACPermissionKeys(keys []string) error {
+	for _, key := range keys {
+		key = strings.TrimSpace(key)
+		if key == "" {
+			continue
+		}
+		if _, ok := security.PermissionCatalog[key]; !ok {
+			return fmt.Errorf("未知权限: %s", key)
+		}
+	}
+	return nil
+}
+
+func (h *RBACHandler) CreateRole(c *gin.Context) {
+	var req upsertRBACRoleRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if err := validateRBACPermissionKeys(req.Permissions); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	role, err := h.db.UpsertRBACRole("", req.Name, req.Description, req.Scope, req.Permissions)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "rbac", "create_role", "创建平台角色", "role", role.ID, nil)
+	}
+	c.JSON(http.StatusOK, gin.H{"role": role})
+}
+
+func (h *RBACHandler) UpdateRole(c *gin.Context) {
+	id := strings.TrimSpace(c.Param("id"))
+	existing, err := h.db.GetRBACRoleByID(id)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "角色不存在"})
+		return
+	}
+	if existing.IsSystem {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "系统内置角色不可修改，请创建自定义角色"})
+		return
+	}
+	var req upsertRBACRoleRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if err := validateRBACPermissionKeys(req.Permissions); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	role, err := h.db.UpsertRBACRole(id, req.Name, req.Description, req.Scope, req.Permissions)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if existing.IsSystem {
+		role.IsSystem = true
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "rbac", "update_role", "更新平台角色", "role", id, nil)
+	}
+	if h.auth != nil {
+		h.auth.RevokeAllSessions()
+	}
+	c.JSON(http.StatusOK, gin.H{"role": role})
+}
+
+func (h *RBACHandler) DeleteRole(c *gin.Context) {
+	id := strings.TrimSpace(c.Param("id"))
+	if err := h.db.DeleteRBACRole(id); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "rbac", "delete_role", "删除平台角色", "role", id, nil)
+	}
+	if h.auth != nil {
+		h.auth.RevokeAllSessions()
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true})
+}
+
+func (h *RBACHandler) ListUsers(c *gin.Context) {
+	users, err := h.db.ListRBACUsers()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	out := make([]gin.H, 0, len(users))
+	for _, user := range users {
+		roleIDs, _ := h.db.ListRBACUserRoleIDs(user.ID)
+		out = append(out, gin.H{
+			"id":           user.ID,
+			"username":     user.Username,
+			"display_name": user.DisplayName,
+			"enabled":      user.Enabled,
+			"is_builtin":   user.IsBuiltin,
+			"roles":        roleIDs,
+			"created_at":   user.CreatedAt,
+			"updated_at":   user.UpdatedAt,
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{"users": out})
+}
+
+type createRBACUserRequest struct {
+	Username    string   `json:"username" binding:"required"`
+	DisplayName string   `json:"display_name"`
+	Password    string   `json:"password" binding:"required"`
+	Enabled     *bool    `json:"enabled"`
+	Roles       []string `json:"roles"`
+}
+
+func (h *RBACHandler) CreateUser(c *gin.Context) {
+	var req createRBACUserRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if len(strings.TrimSpace(req.Password)) < 8 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "密码长度至少需要 8 位"})
+		return
+	}
+	hash, err := security.HashPassword(req.Password)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	enabled := true
+	if req.Enabled != nil {
+		enabled = *req.Enabled
+	}
+	user, err := h.db.CreateRBACUser(req.Username, req.DisplayName, hash, enabled, req.Roles)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "rbac", "create_user", "创建平台用户", "user", user.ID, map[string]interface{}{"username": user.Username})
+	}
+	c.JSON(http.StatusOK, gin.H{"user": user})
+}
+
+type updateRBACUserRequest struct {
+	DisplayName *string   `json:"display_name"`
+	Password    *string   `json:"password"`
+	Enabled     *bool     `json:"enabled"`
+	Roles       *[]string `json:"roles"`
+}
+
+func (h *RBACHandler) UpdateUser(c *gin.Context) {
+	id := strings.TrimSpace(c.Param("id"))
+	user, err := h.db.GetRBACUserByID(id)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "用户不存在"})
+		return
+	}
+	var req updateRBACUserRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	displayName := user.DisplayName
+	if req.DisplayName != nil {
+		displayName = *req.DisplayName
+	}
+	if err := h.db.UpdateRBACUser(id, displayName, req.Enabled, req.Roles); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if req.Password != nil && strings.TrimSpace(*req.Password) != "" {
+		if len(strings.TrimSpace(*req.Password)) < 8 {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "密码长度至少需要 8 位"})
+			return
+		}
+		hash, err := security.HashPassword(*req.Password)
+		if err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+		if err := h.db.UpdateRBACUserPassword(id, hash); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+			return
+		}
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "rbac", "update_user", "更新平台用户", "user", id, nil)
+	}
+	if h.auth != nil {
+		h.auth.RevokeUserSessions(id)
+	}
+	updated, _ := h.db.GetRBACUserByID(id)
+	c.JSON(http.StatusOK, gin.H{"user": updated})
+}
+
+func (h *RBACHandler) DeleteUser(c *gin.Context) {
+	id := strings.TrimSpace(c.Param("id"))
+	if err := h.db.DeleteRBACUser(id); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "rbac", "delete_user", "删除平台用户", "user", id, nil)
+	}
+	if h.auth != nil {
+		h.auth.RevokeUserSessions(id)
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true})
+}
+
+type assignResourceRequest struct {
+	UserID       string   `json:"user_id" binding:"required"`
+	ResourceType string   `json:"resource_type" binding:"required"`
+	ResourceID   string   `json:"resource_id"`
+	ResourceIDs  []string `json:"resource_ids"`
+	AutoDetect   bool     `json:"auto_detect"`
+}
+
+func (h *RBACHandler) AssignResource(c *gin.Context) {
+	var req assignResourceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	resourceIDs := append([]string(nil), req.ResourceIDs...)
+	if strings.TrimSpace(req.ResourceID) != "" {
+		resourceIDs = append(resourceIDs, req.ResourceID)
+	}
+	if len(resourceIDs) == 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "至少需要一个资源 ID"})
+		return
+	}
+	var created int64
+	var detectedTypes map[string]string
+	var err error
+	if req.AutoDetect {
+		created, detectedTypes, err = h.db.AssignResourcesToUserAuto(req.UserID, resourceIDs)
+	} else {
+		created, err = h.db.AssignResourcesToUser(req.UserID, req.ResourceType, resourceIDs)
+	}
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if h.audit != nil {
+		for _, resourceID := range resourceIDs {
+			resourceType := req.ResourceType
+			if detectedTypes != nil {
+				resourceType = detectedTypes[strings.TrimSpace(resourceID)]
+			}
+			h.audit.RecordOK(c, "rbac", "assign_resource", "授权资源访问", resourceType, strings.TrimSpace(resourceID), map[string]interface{}{"user_id": req.UserID})
+		}
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"success":        true,
+		"requested":      len(resourceIDs),
+		"created":        created,
+		"skipped":        int64(len(resourceIDs)) - created,
+		"detected_types": detectedTypes,
+	})
+}
+
+func (h *RBACHandler) ListResourceAssignments(c *gin.Context) {
+	rows, err := h.db.ListRBACResourceAssignments(c.Query("user_id"))
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"assignments": rows})
+}
+
+func (h *RBACHandler) ListAssignableResources(c *gin.Context) {
+	limit, _ := strconv.Atoi(c.DefaultQuery("limit", "50"))
+	if limit <= 0 || limit > 50 {
+		limit = 50
+	}
+	offset, _ := strconv.Atoi(c.DefaultQuery("offset", "0"))
+	if offset < 0 {
+		offset = 0
+	}
+	resources, err := h.db.ListAssignableRBACResourcesPage(c.Query("type"), c.Query("q"), limit+1, offset)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	hasMore := len(resources) > limit
+	if hasMore {
+		resources = resources[:limit]
+	}
+	total, err := h.db.CountAssignableRBACResources(c.Query("type"), c.Query("q"))
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"resources": resources,
+		"has_more":  hasMore,
+		"limit":     limit,
+		"offset":    offset,
+		"total":     total,
+	})
+}
+
+func (h *RBACHandler) DeleteResourceAssignment(c *gin.Context) {
+	id := strings.TrimSpace(c.Param("id"))
+	assignment, err := h.db.DeleteRBACResourceAssignmentWithDetails(id)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "rbac", "delete_resource_assignment", "撤销资源授权", assignment.ResourceType, assignment.ResourceID, map[string]interface{}{
+			"user_id":       assignment.UserID,
+			"assignment_id": assignment.ID,
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true})
+}

internal/handler/rbac_boundary_test.go

@@ -0,0 +1,350 @@
+package handler
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"cyberstrike-ai/internal/authctx"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/mcp"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func withTempWorkingDir(t *testing.T) string {
+	t.Helper()
+	old, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	dir := t.TempDir()
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		_ = os.Chdir(old)
+	})
+	return dir
+}
+
+func TestDetachedAgentContextRetainsPrincipalWithoutParentCancellation(t *testing.T) {
+	parent, cancel := context.WithCancel(context.Background())
+	parent = authctx.WithPrincipal(parent, authctx.NewPrincipal("u1", "user", database.RBACScopeAssigned, map[string]bool{"agent:execute": true}))
+	detached := detachedAgentContext(parent)
+	cancel()
+	if err := detached.Err(); err != nil {
+		t.Fatalf("detached context inherited cancellation: %v", err)
+	}
+	principal, ok := authctx.PrincipalFromContext(detached)
+	if !ok || principal.UserID != "u1" || !principal.HasPermission("agent:execute") {
+		t.Fatalf("detached context lost principal: %#v, ok=%v", principal, ok)
+	}
+}
+
+func TestPromoteAttackChainRequiresSourceConversationAccess(t *testing.T) {
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "promote-rbac.db"), zap.NewNop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	project, _ := db.CreateProject(&database.Project{Name: "owned"})
+	conversation, _ := db.CreateConversation("foreign", database.ConversationCreateMeta{})
+	_ = db.SetResourceOwner("project", project.ID, "u1")
+	_ = db.SetResourceOwner("conversation", conversation.ID, "u2")
+	h := NewProjectHandler(db, zap.NewNop())
+	router := gin.New()
+	router.Use(func(c *gin.Context) {
+		c.Set(security.ContextSessionKey, security.Session{UserID: "u1", Scope: database.RBACScopeOwn})
+		c.Next()
+	})
+	router.POST("/api/projects/:id/promote-attack-chain/:conversationId", h.PromoteAttackChain)
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/api/projects/"+project.ID+"/promote-attack-chain/"+conversation.ID, nil))
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want 403: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestVulnerabilityCannotBeReparentedToForeignProject(t *testing.T) {
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "vuln-reparent-rbac.db"), zap.NewNop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	owned, _ := db.CreateProject(&database.Project{Name: "owned"})
+	foreign, _ := db.CreateProject(&database.Project{Name: "foreign"})
+	_ = db.SetResourceOwner("project", owned.ID, "u1")
+	_ = db.SetResourceOwner("project", foreign.ID, "u2")
+	vulnerability, err := db.CreateVulnerability(&database.Vulnerability{Title: "v", Severity: "high", ProjectID: owned.ID})
+	if err != nil {
+		t.Fatal(err)
+	}
+	_ = db.SetResourceOwner("vulnerability", vulnerability.ID, "u1")
+	h := NewVulnerabilityHandler(db, zap.NewNop())
+	router := gin.New()
+	router.Use(func(c *gin.Context) {
+		c.Set(security.ContextSessionKey, security.Session{UserID: "u1", Scope: database.RBACScopeOwn})
+		c.Next()
+	})
+	router.PUT("/api/vulnerabilities/:id", h.UpdateVulnerability)
+	body, _ := json.Marshal(map[string]interface{}{"project_id": foreign.ID})
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, httptest.NewRequest(http.MethodPut, "/api/vulnerabilities/"+vulnerability.ID, bytes.NewReader(body)))
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want 403: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestAgentTaskEndpointsFilterAndRejectForeignConversations(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, user := setupConversationRBACTest(t)
+	allowed, _ := db.CreateConversation("allowed", database.ConversationCreateMeta{})
+	hidden, _ := db.CreateConversation("hidden", database.ConversationCreateMeta{})
+	if err := db.AssignResourceToUser(user.ID, "conversation", allowed.ID); err != nil {
+		t.Fatal(err)
+	}
+	tasks := NewAgentTaskManager()
+	if _, err := tasks.StartTask(allowed.ID, "visible", func(error) {}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := tasks.StartTask(hidden.ID, "secret", func(error) {}); err != nil {
+		t.Fatal(err)
+	}
+	h := &AgentHandler{db: db, tasks: tasks, logger: zap.NewNop()}
+
+	w := performAssignedHandler(user, http.MethodGet, "/api/agent-loop/tasks", nil, h.ListAgentTasks)
+	if w.Code != http.StatusOK {
+		t.Fatalf("list status = %d: %s", w.Code, w.Body.String())
+	}
+	var response struct {
+		Tasks []*AgentTask `json:"tasks"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {
+		t.Fatal(err)
+	}
+	if len(response.Tasks) != 1 || response.Tasks[0].ConversationID != allowed.ID {
+		t.Fatalf("tasks = %#v, want only %s", response.Tasks, allowed.ID)
+	}
+
+	w = performAssignedHandler(user, http.MethodPost, "/api/agent-loop/cancel", map[string]string{"conversationId": hidden.ID}, h.CancelAgentLoop)
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("cancel status = %d, want %d: %s", w.Code, http.StatusForbidden, w.Body.String())
+	}
+}
+
+func TestChatUploadPathAuthorizationFollowsConversationAccess(t *testing.T) {
+	db, user := setupConversationRBACTest(t)
+	allowed, _ := db.CreateConversation("allowed", database.ConversationCreateMeta{})
+	hidden, _ := db.CreateConversation("hidden", database.ConversationCreateMeta{})
+	if err := db.AssignResourceToUser(user.ID, "conversation", allowed.ID); err != nil {
+		t.Fatal(err)
+	}
+	h := NewChatUploadsHandler(zap.NewNop(), db)
+	c, _ := gin.CreateTestContext(httptest.NewRecorder())
+	c.Set(security.ContextSessionKey, security.Session{UserID: user.ID, Scope: database.RBACScopeAssigned, Permissions: map[string]bool{"chat:write": true}})
+
+	if !h.pathAllowed(c, filepath.ToSlash(filepath.Join("2026-07-10", allowed.ID, "a.txt"))) {
+		t.Fatal("assigned conversation attachment should be accessible")
+	}
+	if h.pathAllowed(c, filepath.ToSlash(filepath.Join("2026-07-10", hidden.ID, "secret.txt"))) {
+		t.Fatal("foreign conversation attachment should be denied")
+	}
+	if h.pathAllowed(c, "2026-07-10/_manual/secret.txt") {
+		t.Fatal("unowned manual attachment should fail closed")
+	}
+}
+
+func TestChatUploadsListIncludesAuthorizedProjectWorkspaceFiles(t *testing.T) {
+	withTempWorkingDir(t)
+	db, user := setupConversationRBACTest(t)
+	fsBase := t.TempDir()
+	workspaceBase := filepath.Join(fsBase, "workspace")
+	reductionBase := filepath.Join(fsBase, "reduction")
+	db.SetEinoConversationDirs("", "", reductionBase, workspaceBase)
+	allowedProject, _ := db.CreateProject(&database.Project{Name: "allowed"})
+	hiddenProject, _ := db.CreateProject(&database.Project{Name: "hidden"})
+	conversation, _ := db.CreateConversation("project conversation", database.ConversationCreateMeta{ProjectID: allowedProject.ID})
+	if err := db.AssignResourceToUser(user.ID, "project", allowedProject.ID); err != nil {
+		t.Fatal(err)
+	}
+	allowedFile := filepath.Join(workspaceBase, "projects", allowedProject.ID, "csv", "assets.csv")
+	hiddenFile := filepath.Join(workspaceBase, "projects", hiddenProject.ID, "csv", "secret.csv")
+	for _, path := range []string{allowedFile, hiddenFile} {
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(path, []byte("name\nexample\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	h := NewChatUploadsHandler(zap.NewNop(), db)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/api/chat-uploads?source=workspace&pageSize=all&conversation="+conversation.ID, nil)
+	c.Set(security.ContextSessionKey, security.Session{UserID: user.ID, Scope: database.RBACScopeAssigned})
+	h.List(c)
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	var response struct {
+		Files []ChatUploadFileItem `json:"files"`
+		Total int                  `json:"total"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {
+		t.Fatal(err)
+	}
+	if response.Total != 1 || len(response.Files) != 1 {
+		t.Fatalf("files = %#v, total = %d, want only authorized workspace file", response.Files, response.Total)
+	}
+	got := response.Files[0]
+	if got.Source != chatUploadSourceWorkspace || got.Name != "assets.csv" || got.ProjectID != allowedProject.ID {
+		t.Fatalf("workspace file = %#v", got)
+	}
+	if got.ProjectName != allowedProject.Name {
+		t.Fatalf("projectName = %q, want %q", got.ProjectName, allowedProject.Name)
+	}
+	if got.ConversationID != conversation.ID {
+		t.Fatalf("conversationId = %q, want %q", got.ConversationID, conversation.ID)
+	}
+	if got.ConversationTitle != conversation.Title {
+		t.Fatalf("conversationTitle = %q, want %q", got.ConversationTitle, conversation.Title)
+	}
+	if got.AbsolutePath != allowedFile {
+		t.Fatalf("absolutePath = %q, want %q", got.AbsolutePath, allowedFile)
+	}
+
+	w = httptest.NewRecorder()
+	c, _ = gin.CreateTestContext(w)
+	resolveURL := "/api/chat-uploads/path?kind=directory&path=__workspace__%2Fprojects%2F" + allowedProject.ID
+	c.Request = httptest.NewRequest(http.MethodGet, resolveURL, nil)
+	c.Set(security.ContextSessionKey, security.Session{UserID: user.ID, Scope: database.RBACScopeAssigned})
+	h.ResolvePath(c)
+	if w.Code != http.StatusOK {
+		t.Fatalf("resolve status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	var resolved struct {
+		AbsolutePath string `json:"absolutePath"`
+		IsDir        bool   `json:"isDir"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resolved); err != nil {
+		t.Fatal(err)
+	}
+	wantDir := filepath.Join(workspaceBase, "projects", allowedProject.ID)
+	if !resolved.IsDir || resolved.AbsolutePath != wantDir {
+		t.Fatalf("resolved = %#v, want dir %q", resolved, wantDir)
+	}
+
+	w = httptest.NewRecorder()
+	c, _ = gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/api/chat-uploads/path?kind=directory&path=__workspace__%2Fprojects", nil)
+	c.Set(security.ContextSessionKey, security.Session{UserID: user.ID, Scope: database.RBACScopeAssigned})
+	h.ResolvePath(c)
+	if w.Code != http.StatusOK {
+		t.Fatalf("resolve projects container status = %d, want 200: %s", w.Code, w.Body.String())
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resolved); err != nil {
+		t.Fatal(err)
+	}
+	wantContainer := filepath.Join(workspaceBase, "projects")
+	if !resolved.IsDir || resolved.AbsolutePath != wantContainer {
+		t.Fatalf("resolved container = %#v, want dir %q", resolved, wantContainer)
+	}
+
+	for _, tc := range []struct {
+		path string
+		want string
+	}{
+		{"__workspace__/", workspaceBase},
+		{"__reduction__/", reductionBase},
+		{"__conversation_artifact__/", db.ConversationArtifactsBaseDir()},
+	} {
+		if err := os.MkdirAll(tc.want, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		w = httptest.NewRecorder()
+		c, _ = gin.CreateTestContext(w)
+		c.Request = httptest.NewRequest(http.MethodGet, "/api/chat-uploads/path?kind=directory&path="+url.QueryEscape(tc.path), nil)
+		c.Set(security.ContextSessionKey, security.Session{UserID: user.ID, Scope: database.RBACScopeAssigned})
+		h.ResolvePath(c)
+		if w.Code != http.StatusOK {
+			t.Fatalf("resolve root %q status = %d, want 200: %s", tc.path, w.Code, w.Body.String())
+		}
+		if err := json.Unmarshal(w.Body.Bytes(), &resolved); err != nil {
+			t.Fatal(err)
+		}
+		wantAbs, _ := filepath.Abs(tc.want)
+		if !resolved.IsDir || resolved.AbsolutePath != wantAbs {
+			t.Fatalf("resolved root %q = %#v, want dir %q", tc.path, resolved, wantAbs)
+		}
+	}
+}
+
+func TestPrepareMultiAgentSessionRejectsForeignConversation(t *testing.T) {
+	db, user := setupConversationRBACTest(t)
+	hidden, _ := db.CreateConversation("hidden", database.ConversationCreateMeta{})
+	h := &AgentHandler{db: db, logger: zap.NewNop()}
+	c, _ := gin.CreateTestContext(httptest.NewRecorder())
+	c.Set(security.ContextSessionKey, security.Session{UserID: user.ID, Scope: database.RBACScopeAssigned, Permissions: map[string]bool{"chat:write": true}})
+
+	_, err := h.prepareMultiAgentSession(&ChatRequest{ConversationID: hidden.ID, Message: "write"}, c, "test")
+	if err == nil || err.Error() != "无权访问该对话" {
+		t.Fatalf("err = %v, want unauthorized conversation", err)
+	}
+}
+
+func TestMonitorExecutionDetailRejectsForeignOwner(t *testing.T) {
+	db, user := setupConversationRBACTest(t)
+	for _, exec := range []*mcp.ToolExecution{
+		{ID: "exec-allowed", ToolName: "allowed", Status: "completed", StartTime: time.Now(), OwnerUserID: user.ID},
+		{ID: "exec-hidden", ToolName: "hidden", Status: "completed", StartTime: time.Now(), OwnerUserID: "another-user"},
+	} {
+		if err := db.SaveToolExecution(exec); err != nil {
+			t.Fatal(err)
+		}
+	}
+	h := NewMonitorHandler(mcp.NewServerWithStorage(zap.NewNop(), db), nil, db, zap.NewNop())
+
+	request := func(id string) *httptest.ResponseRecorder {
+		w := httptest.NewRecorder()
+		c, _ := gin.CreateTestContext(w)
+		c.Request = httptest.NewRequest(http.MethodGet, "/api/monitor/execution/"+id, nil)
+		c.Params = gin.Params{{Key: "id", Value: id}}
+		c.Set(security.ContextSessionKey, security.Session{UserID: user.ID, Scope: database.RBACScopeAssigned})
+		h.GetExecution(c)
+		return w
+	}
+	if w := request("exec-hidden"); w.Code != http.StatusForbidden {
+		t.Fatalf("hidden status = %d, want %d: %s", w.Code, http.StatusForbidden, w.Body.String())
+	}
+	if w := request("exec-allowed"); w.Code != http.StatusOK {
+		t.Fatalf("allowed status = %d, want %d: %s", w.Code, http.StatusOK, w.Body.String())
+	}
+}
+
+func performAssignedHandler(user *database.RBACUser, method, path string, body interface{}, handler gin.HandlerFunc) *httptest.ResponseRecorder {
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	var req *http.Request
+	if body == nil {
+		req = httptest.NewRequest(method, path, nil)
+	} else {
+		payload, _ := json.Marshal(body)
+		req = httptest.NewRequest(method, path, bytes.NewReader(payload))
+		req.Header.Set("Content-Type", "application/json")
+	}
+	c.Request = req
+	c.Set(security.ContextSessionKey, security.Session{UserID: user.ID, Scope: database.RBACScopeAssigned})
+	handler(c)
+	return w
+}

internal/handler/rbac_context.go

@@ -0,0 +1,12 @@
+package handler
+
+import "context"
+
+// detachedAgentContext lets a long-running Agent survive an SSE disconnect
+// while retaining immutable request values such as the authenticated Principal.
+func detachedAgentContext(parent context.Context) context.Context {
+	if parent == nil {
+		parent = context.Background()
+	}
+	return context.WithoutCancel(parent)
+}

internal/handler/rbac_test.go

@@ -0,0 +1,209 @@
+package handler
+
+import (
+	"bytes"
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func TestRBACAssignResourceBatchIsAtomicAndLegacyCompatible(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "rbac-handler.db"), zap.NewNop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+
+	user, err := db.CreateRBACUser("api-member", "API Member", "hash", true, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	p1, _ := db.CreateProject(&database.Project{Name: "p1"})
+	p2, _ := db.CreateProject(&database.Project{Name: "p2"})
+	p3, _ := db.CreateProject(&database.Project{Name: "p3"})
+
+	h := NewRBACHandler(db, zap.NewNop())
+	router := gin.New()
+	router.POST("/api/rbac/resource-assignments", h.AssignResource)
+
+	batch := performRBACJSONRequest(t, router, map[string]interface{}{
+		"user_id": user.ID, "resource_type": "project", "resource_ids": []string{p1.ID, p2.ID},
+	})
+	if batch.Code != http.StatusOK {
+		t.Fatalf("batch status = %d, body = %s", batch.Code, batch.Body.String())
+	}
+	var batchBody map[string]interface{}
+	if err := json.Unmarshal(batch.Body.Bytes(), &batchBody); err != nil {
+		t.Fatal(err)
+	}
+	if batchBody["created"] != float64(2) {
+		t.Fatalf("batch response = %#v, want created=2", batchBody)
+	}
+
+	invalid := performRBACJSONRequest(t, router, map[string]interface{}{
+		"user_id": user.ID, "resource_type": "project", "resource_ids": []string{p3.ID, "missing"},
+	})
+	if invalid.Code != http.StatusBadRequest {
+		t.Fatalf("invalid status = %d, body = %s", invalid.Code, invalid.Body.String())
+	}
+	rows, err := db.ListRBACResourceAssignments(user.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 2 {
+		t.Fatalf("failed batch persisted partial data: %#v", rows)
+	}
+
+	legacy := performRBACJSONRequest(t, router, map[string]interface{}{
+		"user_id": user.ID, "resource_type": "project", "resource_id": p3.ID,
+	})
+	if legacy.Code != http.StatusOK {
+		t.Fatalf("legacy status = %d, body = %s", legacy.Code, legacy.Body.String())
+	}
+}
+
+func TestRBACAssignResourceAutoDetectsActualType(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "rbac-auto-detect.db"), zap.NewNop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+	user, err := db.CreateRBACUser("auto-member", "Auto Member", "hash", true, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	project, err := db.CreateProject(&database.Project{Name: "auto-project"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	h := NewRBACHandler(db, zap.NewNop())
+	router := gin.New()
+	router.POST("/api/rbac/resource-assignments", h.AssignResource)
+
+	response := performRBACJSONRequest(t, router, map[string]interface{}{
+		"user_id": user.ID, "resource_type": "conversation", "resource_ids": []string{project.ID}, "auto_detect": true,
+	})
+	if response.Code != http.StatusOK {
+		t.Fatalf("auto-detect status = %d, body = %s", response.Code, response.Body.String())
+	}
+	rows, err := db.ListRBACResourceAssignments(user.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rows) != 1 || rows[0].ResourceType != "project" || rows[0].ResourceID != project.ID {
+		t.Fatalf("auto-detected assignments = %#v, want project/%s", rows, project.ID)
+	}
+}
+
+func TestRBACAssignableResourcesArePaged(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "rbac-picker.db"), zap.NewNop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+
+	for _, name := range []string{"p1", "p2", "p3"} {
+		if _, err := db.CreateProject(&database.Project{Name: name}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	h := NewRBACHandler(db, zap.NewNop())
+	router := gin.New()
+	router.GET("/api/rbac/resources", h.ListAssignableResources)
+
+	request := httptest.NewRequest(http.MethodGet, "/api/rbac/resources?type=project&limit=2&offset=0", nil)
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, request)
+	if recorder.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", recorder.Code, recorder.Body.String())
+	}
+	var body struct {
+		Resources []database.RBACResourceOption `json:"resources"`
+		HasMore   bool                          `json:"has_more"`
+	}
+	if err := json.Unmarshal(recorder.Body.Bytes(), &body); err != nil {
+		t.Fatal(err)
+	}
+	if len(body.Resources) != 2 || !body.HasMore {
+		t.Fatalf("page = %#v, has_more = %v; want two rows and another page", body.Resources, body.HasMore)
+	}
+}
+
+func TestRBACDeleteResourceAssignmentAuditsTargetResource(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "rbac-revoke-audit.db"), zap.NewNop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+	user, err := db.CreateRBACUser("audit-member", "Audit Member", "hash", true, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	project, err := db.CreateProject(&database.Project{Name: "audit-project"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := db.AssignResourcesToUser(user.ID, "project", []string{project.ID}); err != nil {
+		t.Fatal(err)
+	}
+	assignments, err := db.ListRBACResourceAssignments(user.ID)
+	if err != nil || len(assignments) != 1 {
+		t.Fatalf("assignments = %#v, err = %v", assignments, err)
+	}
+
+	h := NewRBACHandler(db, zap.NewNop())
+	h.SetAudit(audit.NewService(db, &config.Config{}, zap.NewNop()))
+	router := gin.New()
+	router.Use(func(c *gin.Context) {
+		c.Set(security.ContextUsernameKey, "operator-user")
+		c.Next()
+	})
+	router.DELETE("/api/rbac/resource-assignments/:id", h.DeleteResourceAssignment)
+	request := httptest.NewRequest(http.MethodDelete, "/api/rbac/resource-assignments/"+assignments[0].ID, nil)
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, request)
+	if recorder.Code != http.StatusOK {
+		t.Fatalf("status = %d, body = %s", recorder.Code, recorder.Body.String())
+	}
+
+	logs, err := db.ListAuditLogs(database.ListAuditLogsFilter{Category: "rbac", RelatedUserID: user.ID, Limit: 10})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(logs) != 1 {
+		t.Fatalf("audit logs = %#v, want one member-related revoke", logs)
+	}
+	log := logs[0]
+	if log.Action != "delete_resource_assignment" || log.Actor != "operator-user" || log.ResourceType != "project" || log.ResourceID != project.ID {
+		t.Fatalf("audit log = %#v", log)
+	}
+	if log.Detail["user_id"] != user.ID || log.Detail["assignment_id"] != assignments[0].ID {
+		t.Fatalf("audit detail = %#v", log.Detail)
+	}
+}
+
+func performRBACJSONRequest(t *testing.T, router http.Handler, payload map[string]interface{}) *httptest.ResponseRecorder {
+	t.Helper()
+	body, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req := httptest.NewRequest(http.MethodPost, "/api/rbac/resource-assignments", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	recorder := httptest.NewRecorder()
+	router.ServeHTTP(recorder, req)
+	return recorder
+}

internal/handler/robot_mode_test.go

@@ -0,0 +1,101 @@
+package handler
+
+import (
+	"strings"
+	"testing"
+
+	"cyberstrike-ai/internal/config"
+
+	"go.uber.org/zap"
+)
+
+func TestRobotModeSwitch(t *testing.T) {
+	h := NewRobotHandler(&config.Config{MultiAgent: config.MultiAgentConfig{Enabled: true}}, nil, nil, zap.NewNop())
+
+	if got := h.cmdSwitchMode("lark", "user-1", "plan-execute"); !strings.Contains(got, "Plan-Execute") {
+		t.Fatalf("unexpected switch response: %s", got)
+	}
+	if got := h.getAgentMode("lark", "user-1"); got != "plan_execute" {
+		t.Fatalf("mode = %q, want plan_execute", got)
+	}
+	if got := h.cmdModes("lark", "user-1"); !strings.Contains(got, "当前模式: Plan-Execute") {
+		t.Fatalf("unexpected modes response: %s", got)
+	}
+}
+
+func TestRobotModeRejectsUnavailableMultiAgent(t *testing.T) {
+	h := NewRobotHandler(&config.Config{}, nil, nil, zap.NewNop())
+
+	if got := h.cmdSwitchMode("lark", "user-1", "deep"); !strings.Contains(got, "启用 Eino 多代理") {
+		t.Fatalf("unexpected rejection: %s", got)
+	}
+	if got := h.getAgentMode("lark", "user-1"); got != "eino_single" {
+		t.Fatalf("mode changed after rejection: %q", got)
+	}
+}
+
+func TestParseRobotAgentModeRejectsUnknownMode(t *testing.T) {
+	if mode, ok := parseRobotAgentMode("unknown"); ok || mode != "" {
+		t.Fatalf("parseRobotAgentMode returned (%q, %v), want empty,false", mode, ok)
+	}
+}
+
+func TestRobotStatusCommandPermission(t *testing.T) {
+	for _, command := range []string{"状态", "status"} {
+		permission, recognized := robotCommandPermission(command)
+		if !recognized || permission != "chat:read" {
+			t.Fatalf("command %q returned permission=%q recognized=%v", command, permission, recognized)
+		}
+	}
+	for _, removed := range []string{"当前", "current"} {
+		if _, recognized := robotCommandPermission(removed); recognized {
+			t.Fatalf("removed command %q is still recognized", removed)
+		}
+	}
+}
+
+func TestRobotBestPracticeCommandPermissions(t *testing.T) {
+	cases := map[string]string{
+		"任务":       "chat:read",
+		"task":     "chat:read",
+		"重命名 新标题":  "chat:write",
+		"rename x": "chat:write",
+		"诊断":       "config:read",
+		"doctor":   "config:read",
+	}
+	for command, want := range cases {
+		permission, recognized := robotCommandPermission(command)
+		if !recognized || permission != want {
+			t.Fatalf("command %q returned permission=%q recognized=%v, want %q,true", command, permission, recognized, want)
+		}
+	}
+}
+
+func TestRobotConfirmationCanBeCancelled(t *testing.T) {
+	h := NewRobotHandler(&config.Config{}, nil, nil, zap.NewNop())
+	h.setPendingConfirmation("lark", "user-1", "delete_conversation", "conv-1")
+	if got := h.cmdCancelConfirmation("lark", "user-1"); got != "已取消待确认操作。" {
+		t.Fatalf("unexpected cancel response: %s", got)
+	}
+	if got := h.cmdConfirm("lark", "user-1"); !strings.Contains(got, "没有待确认操作") {
+		t.Fatalf("confirmation survived cancellation: %s", got)
+	}
+}
+
+func TestRobotDoctorSeparatesInternalToolsFromHTTPMCP(t *testing.T) {
+	h := NewRobotHandler(&config.Config{
+		Security: config.SecurityConfig{Tools: []config.ToolConfig{
+			{Name: "enabled-tool", Enabled: true},
+			{Name: "disabled-tool", Enabled: false},
+		}},
+		MCP: config.MCPConfig{Enabled: false},
+	}, nil, nil, zap.NewNop())
+
+	got := h.cmdDoctor()
+	if !strings.Contains(got, "内置 MCP 工具: 1/2 个已启用") {
+		t.Fatalf("internal tool status missing: %s", got)
+	}
+	if !strings.Contains(got, "HTTP MCP 服务: 已关闭") {
+		t.Fatalf("HTTP MCP status missing: %s", got)
+	}
+}

internal/handler/robot_rbac_test.go

@@ -0,0 +1,138 @@
+package handler
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+
+	"go.uber.org/zap"
+)
+
+func TestRobotUsersAreResourceIsolated(t *testing.T) {
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "robot-rbac.db"), zap.NewNop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	cfg := &config.Config{}
+	cfg.Project.Enabled = true
+	h := NewRobotHandler(cfg, db, nil, zap.NewNop())
+	if err := db.BootstrapRBAC("hash", security.PermissionCatalog); err != nil {
+		t.Fatal(err)
+	}
+	alice, err := db.CreateRBACUser("robot-alice", "Robot Alice", "hash", true, []string{database.RBACSystemRoleOperator})
+	if err != nil {
+		t.Fatal(err)
+	}
+	bob, err := db.CreateRBACUser("robot-bob", "Robot Bob", "hash", true, []string{database.RBACSystemRoleOperator})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for externalID, user := range map[string]*database.RBACUser{"alice": alice, "bob": bob} {
+		code := "TEST-" + strings.ToUpper(externalID)
+		if err := db.CreateRobotBindingCode(user.ID, hashRobotBindingCode(code), time.Now().Add(time.Minute)); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := db.ConsumeRobotBindingCode("wecom", externalID, hashRobotBindingCode(code)); err != nil {
+			t.Fatal(err)
+		}
+	}
+	aliceAccess, err := db.ResolveRobotRBACAccess("wecom", "alice")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := h.HandleMessage("wecom", "alice", "身份"); !strings.Contains(got, "Robot Alice") || !strings.Contains(got, alice.ID) || !strings.Contains(got, "user_binding") {
+		t.Fatalf("bound identity output is incomplete: %s", got)
+	}
+
+	conversationID, _ := h.getOrCreateConversation("wecom", "alice", "alice conversation", aliceAccess)
+	if conversationID == "" {
+		t.Fatal("alice conversation was not created")
+	}
+	if got := h.cmdList("wecom", "bob"); strings.Contains(got, conversationID) {
+		t.Fatalf("bob listed alice conversation: %s", got)
+	}
+	if got := h.cmdSwitch("wecom", "bob", conversationID); !strings.Contains(got, "不存在") && !strings.Contains(got, "无权访问") {
+		t.Fatalf("bob switched to alice conversation: %s", got)
+	}
+	if got := h.cmdDelete("wecom", "bob", conversationID); !strings.Contains(got, "无权访问") {
+		t.Fatalf("bob deleted alice conversation: %s", got)
+	}
+	if _, err := db.GetConversation(conversationID); err != nil {
+		t.Fatalf("alice conversation was deleted: %v", err)
+	}
+
+	createReply := h.cmdNewProject("wecom", "alice", "alice project")
+	if !strings.Contains(createReply, "已创建项目") {
+		t.Fatalf("create project reply: %s", createReply)
+	}
+	if got := h.cmdProjects("wecom", "bob"); strings.Contains(got, "alice project") {
+		t.Fatalf("bob listed alice project: %s", got)
+	}
+}
+
+func TestWecomReplayGuardRequiresFreshUniqueRequest(t *testing.T) {
+	h := NewRobotHandler(&config.Config{}, nil, nil, zap.NewNop())
+	timestamp := time.Now().Unix()
+	if !h.acceptFreshWecomRequest(fmt.Sprintf("%d", timestamp), "nonce", "signature") {
+		t.Fatal("fresh request was rejected")
+	}
+	if h.acceptFreshWecomRequest(fmt.Sprintf("%d", timestamp), "nonce", "signature") {
+		t.Fatal("duplicate request was accepted")
+	}
+	if h.acceptFreshWecomRequest(fmt.Sprintf("%d", timestamp-600), "old", "signature") {
+		t.Fatal("stale request was accepted")
+	}
+}
+
+func TestRobotServiceAccountRequiresExactSenderAllowlist(t *testing.T) {
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "robot-service.db"), zap.NewNop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	if err := db.BootstrapRBAC("hash", security.PermissionCatalog); err != nil {
+		t.Fatal(err)
+	}
+	serviceUser, err := db.CreateRBACUser("robot-service-user", "Robot Service", "hash", true, []string{database.RBACSystemRoleOperator})
+	if err != nil {
+		t.Fatal(err)
+	}
+	cfg := &config.Config{}
+	cfg.Robots.Lark.Auth = config.RobotAuthorizationConfig{
+		Mode: config.RobotAuthModeServiceAccount, ServiceUserID: serviceUser.ID,
+		AllowedExternalUsers: []string{"t:tenant|u:allowed"},
+	}
+	h := NewRobotHandler(cfg, db, nil, zap.NewNop())
+	if got := h.HandleMessage("lark", "t:tenant|u:allowed", "列表"); strings.Contains(got, "白名单") || strings.Contains(got, "尚未绑定") {
+		t.Fatalf("allowed service account sender was denied: %s", got)
+	}
+	if got := h.HandleMessage("lark", "t:tenant|u:denied", "列表"); !strings.Contains(got, "白名单") {
+		t.Fatalf("non-allowlisted sender was not denied: %s", got)
+	}
+	if got := h.HandleMessage("lark", "t:tenant|u:allowed", "绑定 ABCD-1234"); !strings.Contains(got, "服务账号模式") {
+		t.Fatalf("service-account robot accepted user binding: %s", got)
+	}
+	if got := h.HandleMessage("lark", "t:tenant|u:allowed", "whoami"); !strings.Contains(got, "Robot Service") || !strings.Contains(got, serviceUser.ID) || !strings.Contains(got, "service_account") {
+		t.Fatalf("service-account identity output is incomplete: %s", got)
+	}
+	if got := h.HandleMessage("lark", "t:tenant|u:denied", "whoami"); !strings.Contains(got, "鉴权状态：拒绝") || strings.Contains(got, serviceUser.ID) {
+		t.Fatalf("denied identity output leaked or omitted status: %s", got)
+	}
+
+	adminCfg := &config.Config{}
+	adminCfg.Robots.Lark.Auth = config.RobotAuthorizationConfig{
+		Mode: config.RobotAuthModeServiceAccount, ServiceUserID: "admin",
+		AllowedExternalUsers: []string{"t:tenant|u:owner"},
+	}
+	adminHandler := NewRobotHandler(adminCfg, db, nil, zap.NewNop())
+	if got := adminHandler.HandleMessage("lark", "t:tenant|u:owner", "身份"); !strings.Contains(got, "admin") || !strings.Contains(got, "鉴权状态：已授权") {
+		t.Fatalf("allowlisted admin service account was denied: %s", got)
+	}
+}

internal/handler/robot_wecom_test.go

@@ -0,0 +1,78 @@
+package handler
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"cyberstrike-ai/internal/config"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func newWecomTestHandler(token string, aesKey string) *RobotHandler {
+	return &RobotHandler{
+		config: &config.Config{
+			Robots: config.RobotsConfig{
+				Wecom: config.RobotWecomConfig{
+					Enabled:        true,
+					Token:          token,
+					EncodingAESKey: aesKey,
+				},
+			},
+		},
+		logger: zap.NewNop(),
+	}
+}
+
+func TestHandleWecomPOST_rejectsWhenTokenEmpty(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	h := newWecomTestHandler("", "")
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	body := `<?xml version="1.0"?><xml><FromUserName>attacker</FromUserName><MsgType>text</MsgType><Content>hi</Content></xml>`
+	c.Request = httptest.NewRequest(http.MethodPost, "/api/robot/wecom", strings.NewReader(body))
+
+	h.HandleWecomPOST(c)
+
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want %d", w.Code, http.StatusForbidden)
+	}
+	if w.Body.String() == "success" {
+		t.Fatal("expected rejection, got success")
+	}
+}
+
+func TestHandleWecomPOST_rejectsPlaintextWhenEncryptionConfigured(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	h := newWecomTestHandler("secret-token", "abcdefghijklmnopqrstuvwxyz0123456789ABCD")
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	body := `<?xml version="1.0"?><xml><FromUserName>attacker</FromUserName><MsgType>text</MsgType><Content>hi</Content></xml>`
+	c.Request = httptest.NewRequest(http.MethodPost, "/api/robot/wecom?timestamp=1&nonce=2&msg_signature=fake", strings.NewReader(body))
+
+	h.HandleWecomPOST(c)
+
+	if w.Body.String() == "success" {
+		t.Fatal("expected rejection for plaintext in encryption mode, got success")
+	}
+}
+
+func TestHandleWecomGET_rejectsWhenTokenEmpty(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	h := newWecomTestHandler("", "")
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/api/robot/wecom?msg_signature=x&timestamp=1&nonce=2&echostr=abc", nil)
+
+	h.HandleWecomGET(c)
+
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want %d", w.Code, http.StatusForbidden)
+	}
+}

internal/handler/role.go

@@ -0,0 +1,469 @@
+package handler
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/config"
+
+	"gopkg.in/yaml.v3"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// RoleHandler 角色处理器
+type RoleHandler struct {
+	config     *config.Config
+	configPath string
+	logger     *zap.Logger
+	audit      *audit.Service
+}
+
+// SetAudit wires platform audit logging.
+func (h *RoleHandler) SetAudit(s *audit.Service) {
+	h.audit = s
+}
+
+// NewRoleHandler 创建新的角色处理器
+func NewRoleHandler(cfg *config.Config, configPath string, logger *zap.Logger) *RoleHandler {
+	return &RoleHandler{
+		config:     cfg,
+		configPath: configPath,
+		logger:     logger,
+	}
+}
+
+// GetRoles 获取所有角色
+func (h *RoleHandler) GetRoles(c *gin.Context) {
+	if h.config.Roles == nil {
+		h.config.Roles = make(map[string]config.RoleConfig)
+	}
+
+	roles := make([]config.RoleConfig, 0, len(h.config.Roles))
+	for key, role := range h.config.Roles {
+		// 确保角色的key与name一致
+		if role.Name == "" {
+			role.Name = key
+		}
+		roles = append(roles, role)
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"roles": roles,
+	})
+}
+
+// GetRole 获取单个角色
+func (h *RoleHandler) GetRole(c *gin.Context) {
+	roleName := c.Param("name")
+	if roleName == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "角色名称不能为空"})
+		return
+	}
+
+	if h.config.Roles == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "角色不存在"})
+		return
+	}
+
+	role, exists := h.config.Roles[roleName]
+	if !exists {
+		c.JSON(http.StatusNotFound, gin.H{"error": "角色不存在"})
+		return
+	}
+
+	// 确保角色的name与key一致
+	if role.Name == "" {
+		role.Name = roleName
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"role": role,
+	})
+}
+
+// UpdateRole 更新角色
+func (h *RoleHandler) UpdateRole(c *gin.Context) {
+	roleName := c.Param("name")
+	if roleName == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "角色名称不能为空"})
+		return
+	}
+
+	var req config.RoleConfig
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的请求参数: " + err.Error()})
+		return
+	}
+
+	// 确保角色名称与请求中的name一致
+	if req.Name == "" {
+		req.Name = roleName
+	}
+
+	// 初始化Roles map
+	if h.config.Roles == nil {
+		h.config.Roles = make(map[string]config.RoleConfig)
+	}
+
+	// 删除所有与角色name相同但key不同的旧角色（避免重复）
+	// 使用角色name作为key，确保唯一性
+	finalKey := req.Name
+	keysToDelete := make([]string, 0)
+	for key := range h.config.Roles {
+		// 如果key与最终的key不同，但name相同，则标记为删除
+		if key != finalKey {
+			role := h.config.Roles[key]
+			// 确保角色的name字段正确设置
+			if role.Name == "" {
+				role.Name = key
+			}
+			if role.Name == req.Name {
+				keysToDelete = append(keysToDelete, key)
+			}
+		}
+	}
+	// 删除旧的角色
+	for _, key := range keysToDelete {
+		delete(h.config.Roles, key)
+		h.logger.Info("删除重复的角色", zap.String("oldKey", key), zap.String("name", req.Name))
+	}
+
+	// 如果当前更新的key与最终key不同，也需要删除旧的
+	if roleName != finalKey {
+		delete(h.config.Roles, roleName)
+	}
+
+	// 如果角色名称改变，需要删除旧文件
+	if roleName != finalKey {
+		configDir := filepath.Dir(h.configPath)
+		rolesDir := h.config.RolesDir
+		if rolesDir == "" {
+			rolesDir = "roles" // 默认目录
+		}
+
+		// 如果是相对路径，相对于配置文件所在目录
+		if !filepath.IsAbs(rolesDir) {
+			rolesDir = filepath.Join(configDir, rolesDir)
+		}
+
+		// 删除旧的角色文件
+		oldSafeFileName := sanitizeFileName(roleName)
+		oldRoleFileYaml := filepath.Join(rolesDir, oldSafeFileName+".yaml")
+		oldRoleFileYml := filepath.Join(rolesDir, oldSafeFileName+".yml")
+
+		if _, err := os.Stat(oldRoleFileYaml); err == nil {
+			if err := os.Remove(oldRoleFileYaml); err != nil {
+				h.logger.Warn("删除旧角色配置文件失败", zap.String("file", oldRoleFileYaml), zap.Error(err))
+			}
+		}
+		if _, err := os.Stat(oldRoleFileYml); err == nil {
+			if err := os.Remove(oldRoleFileYml); err != nil {
+				h.logger.Warn("删除旧角色配置文件失败", zap.String("file", oldRoleFileYml), zap.Error(err))
+			}
+		}
+	}
+
+	// 使用角色name作为key来保存（确保唯一性）
+	h.config.Roles[finalKey] = req
+
+	// 保存配置到文件
+	if err := h.saveConfig(); err != nil {
+		h.logger.Error("保存配置失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "保存配置失败: " + err.Error()})
+		return
+	}
+
+	h.logger.Info("更新角色", zap.String("oldKey", roleName), zap.String("newKey", finalKey), zap.String("name", req.Name))
+	if h.audit != nil {
+		h.audit.RecordOK(c, "role", "update", "更新角色", "role", finalKey, map[string]interface{}{"name": req.Name})
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"message": "角色已更新",
+		"role":    req,
+	})
+}
+
+// CreateRole 创建新角色
+func (h *RoleHandler) CreateRole(c *gin.Context) {
+	var req config.RoleConfig
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的请求参数: " + err.Error()})
+		return
+	}
+
+	if req.Name == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "角色名称不能为空"})
+		return
+	}
+
+	// 初始化Roles map
+	if h.config.Roles == nil {
+		h.config.Roles = make(map[string]config.RoleConfig)
+	}
+
+	// 检查角色是否已存在
+	if _, exists := h.config.Roles[req.Name]; exists {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "角色已存在"})
+		return
+	}
+
+	// 创建角色（默认启用）
+	if !req.Enabled {
+		req.Enabled = true
+	}
+
+	h.config.Roles[req.Name] = req
+
+	// 保存配置到文件
+	if err := h.saveConfig(); err != nil {
+		h.logger.Error("保存配置失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "保存配置失败: " + err.Error()})
+		return
+	}
+
+	h.logger.Info("创建角色", zap.String("roleName", req.Name))
+	if h.audit != nil {
+		h.audit.RecordOK(c, "role", "create", "创建角色", "role", req.Name, nil)
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"message": "角色已创建",
+		"role":    req,
+	})
+}
+
+// DeleteRole 删除角色
+func (h *RoleHandler) DeleteRole(c *gin.Context) {
+	roleName := c.Param("name")
+	if roleName == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "角色名称不能为空"})
+		return
+	}
+
+	if h.config.Roles == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "角色不存在"})
+		return
+	}
+
+	if _, exists := h.config.Roles[roleName]; !exists {
+		c.JSON(http.StatusNotFound, gin.H{"error": "角色不存在"})
+		return
+	}
+
+	// 不允许删除"默认"角色
+	if roleName == "默认" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "不能删除默认角色"})
+		return
+	}
+
+	delete(h.config.Roles, roleName)
+
+	// 删除对应的角色文件
+	configDir := filepath.Dir(h.configPath)
+	rolesDir := h.config.RolesDir
+	if rolesDir == "" {
+		rolesDir = "roles" // 默认目录
+	}
+
+	// 如果是相对路径，相对于配置文件所在目录
+	if !filepath.IsAbs(rolesDir) {
+		rolesDir = filepath.Join(configDir, rolesDir)
+	}
+
+	// 尝试删除角色文件（.yaml 和 .yml）
+	safeFileName := sanitizeFileName(roleName)
+	roleFileYaml := filepath.Join(rolesDir, safeFileName+".yaml")
+	roleFileYml := filepath.Join(rolesDir, safeFileName+".yml")
+
+	// 删除 .yaml 文件（如果存在）
+	if _, err := os.Stat(roleFileYaml); err == nil {
+		if err := os.Remove(roleFileYaml); err != nil {
+			h.logger.Warn("删除角色配置文件失败", zap.String("file", roleFileYaml), zap.Error(err))
+		} else {
+			h.logger.Info("已删除角色配置文件", zap.String("file", roleFileYaml))
+		}
+	}
+
+	// 删除 .yml 文件（如果存在）
+	if _, err := os.Stat(roleFileYml); err == nil {
+		if err := os.Remove(roleFileYml); err != nil {
+			h.logger.Warn("删除角色配置文件失败", zap.String("file", roleFileYml), zap.Error(err))
+		} else {
+			h.logger.Info("已删除角色配置文件", zap.String("file", roleFileYml))
+		}
+	}
+
+	h.logger.Info("删除角色", zap.String("roleName", roleName))
+	if h.audit != nil {
+		h.audit.RecordOK(c, "role", "delete", "删除角色", "role", roleName, nil)
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"message": "角色已删除",
+	})
+}
+
+// saveConfig 保存配置到目录中的文件
+func (h *RoleHandler) saveConfig() error {
+	configDir := filepath.Dir(h.configPath)
+	rolesDir := h.config.RolesDir
+	if rolesDir == "" {
+		rolesDir = "roles" // 默认目录
+	}
+
+	// 如果是相对路径，相对于配置文件所在目录
+	if !filepath.IsAbs(rolesDir) {
+		rolesDir = filepath.Join(configDir, rolesDir)
+	}
+
+	// 确保目录存在
+	if err := os.MkdirAll(rolesDir, 0755); err != nil {
+		return fmt.Errorf("创建角色目录失败: %w", err)
+	}
+
+	// 保存每个角色到独立的文件
+	if h.config.Roles != nil {
+		for roleName, role := range h.config.Roles {
+			// 确保角色名称正确设置
+			if role.Name == "" {
+				role.Name = roleName
+			}
+
+			// 使用角色名称作为文件名（安全化文件名，避免特殊字符）
+			safeFileName := sanitizeFileName(role.Name)
+			roleFile := filepath.Join(rolesDir, safeFileName+".yaml")
+
+			// 将角色配置序列化为YAML
+			roleData, err := yaml.Marshal(&role)
+			if err != nil {
+				h.logger.Error("序列化角色配置失败", zap.String("role", roleName), zap.Error(err))
+				continue
+			}
+
+			// 处理icon字段：确保包含\U的icon值被引号包围（YAML需要引号才能正确解析Unicode转义）
+			roleDataStr := string(roleData)
+			if role.Icon != "" && strings.HasPrefix(role.Icon, "\\U") {
+				// 匹配 icon: \UXXXXXXXX 格式（没有引号），排除已经有引号的情况
+				// 使用负向前瞻确保后面没有引号，或者直接匹配没有引号的情况
+				re := regexp.MustCompile(`(?m)^(icon:\s+)(\\U[0-9A-F]{8})(\s*)$`)
+				roleDataStr = re.ReplaceAllString(roleDataStr, `${1}"${2}"${3}`)
+				roleData = []byte(roleDataStr)
+			}
+
+			// 写入文件
+			if err := os.WriteFile(roleFile, roleData, 0644); err != nil {
+				h.logger.Error("保存角色配置文件失败", zap.String("role", roleName), zap.String("file", roleFile), zap.Error(err))
+				continue
+			}
+
+			h.logger.Info("角色配置已保存到文件", zap.String("role", roleName), zap.String("file", roleFile))
+		}
+	}
+
+	return nil
+}
+
+// sanitizeFileName 将角色名称转换为安全的文件名
+func sanitizeFileName(name string) string {
+	// 替换可能不安全的字符
+	replacer := map[rune]string{
+		'/':  "_",
+		'\\': "_",
+		':':  "_",
+		'*':  "_",
+		'?':  "_",
+		'"':  "_",
+		'<':  "_",
+		'>':  "_",
+		'|':  "_",
+		' ':  "_",
+	}
+
+	var result []rune
+	for _, r := range name {
+		if replacement, ok := replacer[r]; ok {
+			result = append(result, []rune(replacement)...)
+		} else {
+			result = append(result, r)
+		}
+	}
+
+	fileName := string(result)
+	// 如果文件名为空，使用默认名称
+	if fileName == "" {
+		fileName = "role"
+	}
+
+	return fileName
+}
+
+// updateRolesConfig 更新角色配置
+func updateRolesConfig(doc *yaml.Node, cfg config.RolesConfig) {
+	root := doc.Content[0]
+	rolesNode := ensureMap(root, "roles")
+
+	// 清空现有角色
+	if rolesNode.Kind == yaml.MappingNode {
+		rolesNode.Content = nil
+	}
+
+	// 添加新角色（使用name作为key，确保唯一性）
+	if cfg.Roles != nil {
+		// 先建立一个以name为key的map，去重（保留最后一个）
+		rolesByName := make(map[string]config.RoleConfig)
+		for roleKey, role := range cfg.Roles {
+			// 确保角色的name字段正确设置
+			if role.Name == "" {
+				role.Name = roleKey
+			}
+			// 使用name作为最终key，如果有多个key对应相同的name，只保留最后一个
+			rolesByName[role.Name] = role
+		}
+
+		// 将去重后的角色写入YAML
+		for roleName, role := range rolesByName {
+			roleNode := ensureMap(rolesNode, roleName)
+			setStringInMap(roleNode, "name", role.Name)
+			setStringInMap(roleNode, "description", role.Description)
+			setStringInMap(roleNode, "user_prompt", role.UserPrompt)
+			if role.Icon != "" {
+				setStringInMap(roleNode, "icon", role.Icon)
+			}
+			setBoolInMap(roleNode, "enabled", role.Enabled)
+
+			// 添加工具列表（优先使用tools字段）
+			if len(role.Tools) > 0 {
+				toolsNode := ensureArray(roleNode, "tools")
+				toolsNode.Content = nil
+				for _, toolKey := range role.Tools {
+					toolNode := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: toolKey}
+					toolsNode.Content = append(toolsNode.Content, toolNode)
+				}
+			} else if len(role.MCPs) > 0 {
+				// 向后兼容：如果没有tools但有mcps，保存mcps
+				mcpsNode := ensureArray(roleNode, "mcps")
+				mcpsNode.Content = nil
+				for _, mcpName := range role.MCPs {
+					mcpNode := &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: mcpName}
+					mcpsNode.Content = append(mcpsNode.Content, mcpNode)
+				}
+			}
+		}
+	}
+}
+
+// ensureArray 确保数组中存在指定key的数组节点
+func ensureArray(parent *yaml.Node, key string) *yaml.Node {
+	_, valueNode := ensureKeyValue(parent, key)
+	if valueNode.Kind != yaml.SequenceNode {
+		valueNode.Kind = yaml.SequenceNode
+		valueNode.Tag = "!!seq"
+		valueNode.Content = nil
+	}
+	return valueNode
+}

internal/handler/skills.go

@@ -0,0 +1,710 @@
+package handler
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/skillpackage"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+	"gopkg.in/yaml.v3"
+)
+
+// SkillsHandler Skills处理器（磁盘 + Eino 规范；运行时由 Eino ADK skill 中间件加载）
+type SkillsHandler struct {
+	config     *config.Config
+	configPath string
+	logger     *zap.Logger
+	db         *database.DB // 数据库连接（遗留统计；MCP list/read 已移除）
+	audit      *audit.Service
+}
+
+// SetAudit wires platform audit logging.
+func (h *SkillsHandler) SetAudit(s *audit.Service) {
+	h.audit = s
+}
+
+// NewSkillsHandler 创建新的Skills处理器
+func NewSkillsHandler(cfg *config.Config, configPath string, logger *zap.Logger) *SkillsHandler {
+	return &SkillsHandler{
+		config:     cfg,
+		configPath: configPath,
+		logger:     logger,
+	}
+}
+
+func (h *SkillsHandler) skillsRootAbs() string {
+	skillsDir := h.config.SkillsDir
+	if skillsDir == "" {
+		skillsDir = "skills"
+	}
+	configDir := filepath.Dir(h.configPath)
+	if !filepath.IsAbs(skillsDir) {
+		skillsDir = filepath.Join(configDir, skillsDir)
+	}
+	return skillsDir
+}
+
+// SetDB 设置数据库连接（用于获取调用统计）
+func (h *SkillsHandler) SetDB(db *database.DB) {
+	h.db = db
+}
+
+// GetSkills 获取所有skills列表（支持分页和搜索）
+func (h *SkillsHandler) GetSkills(c *gin.Context) {
+	allSummaries, err := skillpackage.ListSkillSummaries(h.skillsRootAbs())
+	if err != nil {
+		h.logger.Error("获取skills列表失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	searchKeyword := strings.TrimSpace(c.Query("search"))
+
+	allSkillsInfo := make([]map[string]interface{}, 0, len(allSummaries))
+	for _, s := range allSummaries {
+		skillInfo := map[string]interface{}{
+			"id":           s.ID,
+			"name":         s.Name,
+			"dir_name":     s.DirName,
+			"description":  s.Description,
+			"version":      s.Version,
+			"path":         s.Path,
+			"tags":         s.Tags,
+			"triggers":     s.Triggers,
+			"script_count": s.ScriptCount,
+			"file_count":   s.FileCount,
+			"progressive":  s.Progressive,
+			"file_size":    s.FileSize,
+			"mod_time":     s.ModTime,
+		}
+		allSkillsInfo = append(allSkillsInfo, skillInfo)
+	}
+
+	filteredSkillsInfo := allSkillsInfo
+	if searchKeyword != "" {
+		keywordLower := strings.ToLower(searchKeyword)
+		filteredSkillsInfo = make([]map[string]interface{}, 0)
+		for _, skillInfo := range allSkillsInfo {
+			id := strings.ToLower(fmt.Sprintf("%v", skillInfo["id"]))
+			name := strings.ToLower(fmt.Sprintf("%v", skillInfo["name"]))
+			description := strings.ToLower(fmt.Sprintf("%v", skillInfo["description"]))
+			path := strings.ToLower(fmt.Sprintf("%v", skillInfo["path"]))
+			version := strings.ToLower(fmt.Sprintf("%v", skillInfo["version"]))
+			tagsJoined := ""
+			if tags, ok := skillInfo["tags"].([]string); ok {
+				tagsJoined = strings.ToLower(strings.Join(tags, " "))
+			}
+			trigJoined := ""
+			if tr, ok := skillInfo["triggers"].([]string); ok {
+				trigJoined = strings.ToLower(strings.Join(tr, " "))
+			}
+			if strings.Contains(id, keywordLower) ||
+				strings.Contains(name, keywordLower) ||
+				strings.Contains(description, keywordLower) ||
+				strings.Contains(path, keywordLower) ||
+				strings.Contains(version, keywordLower) ||
+				strings.Contains(tagsJoined, keywordLower) ||
+				strings.Contains(trigJoined, keywordLower) {
+				filteredSkillsInfo = append(filteredSkillsInfo, skillInfo)
+			}
+		}
+	}
+
+	// 分页参数
+	limit := 20 // 默认每页20条
+	offset := 0
+	if limitStr := c.Query("limit"); limitStr != "" {
+		if parsed, err := parseInt(limitStr); err == nil && parsed > 0 {
+			// 允许更大的limit用于搜索场景，但设置一个合理的上限（10000）
+			if parsed <= 10000 {
+				limit = parsed
+			} else {
+				limit = 10000
+			}
+		}
+	}
+	if offsetStr := c.Query("offset"); offsetStr != "" {
+		if parsed, err := parseInt(offsetStr); err == nil && parsed >= 0 {
+			offset = parsed
+		}
+	}
+
+	// 计算分页范围
+	total := len(filteredSkillsInfo)
+	start := offset
+	end := offset + limit
+	if start > total {
+		start = total
+	}
+	if end > total {
+		end = total
+	}
+
+	// 获取当前页的skill列表
+	var paginatedSkillsInfo []map[string]interface{}
+	if start < end {
+		paginatedSkillsInfo = filteredSkillsInfo[start:end]
+	} else {
+		paginatedSkillsInfo = []map[string]interface{}{}
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"skills": paginatedSkillsInfo,
+		"total":  total,
+		"limit":  limit,
+		"offset": offset,
+	})
+}
+
+// GetSkill 获取单个skill的详细信息
+func (h *SkillsHandler) GetSkill(c *gin.Context) {
+	skillName := c.Param("name")
+	if skillName == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "skill名称不能为空"})
+		return
+	}
+
+	resPath := strings.TrimSpace(c.Query("resource_path"))
+	if resPath == "" {
+		resPath = strings.TrimSpace(c.Query("skill_script_path"))
+	}
+	if resPath != "" {
+		content, err := skillpackage.ReadScriptText(h.skillsRootAbs(), skillName, resPath, 0)
+		if err != nil {
+			h.logger.Warn("读取skill资源失败", zap.String("skill", skillName), zap.String("path", resPath), zap.Error(err))
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{
+			"skill": map[string]interface{}{
+				"id": skillName,
+			},
+			"resource": map[string]interface{}{
+				"path":    resPath,
+				"content": content,
+			},
+		})
+		return
+	}
+
+	depthStr := strings.ToLower(strings.TrimSpace(c.DefaultQuery("depth", "full")))
+	section := strings.TrimSpace(c.Query("section"))
+	opt := skillpackage.LoadOptions{Section: section}
+	switch depthStr {
+	case "summary":
+		opt.Depth = "summary"
+	case "full", "":
+		opt.Depth = "full"
+	default:
+		c.JSON(http.StatusBadRequest, gin.H{"error": "depth 仅支持 summary 或 full"})
+		return
+	}
+
+	skill, err := skillpackage.LoadSkill(h.skillsRootAbs(), skillName, opt)
+	if err != nil {
+		h.logger.Warn("加载skill失败", zap.String("skill", skillName), zap.Error(err))
+		c.JSON(http.StatusNotFound, gin.H{"error": "skill不存在: " + err.Error()})
+		return
+	}
+
+	skillPath := skill.Path
+	skillFile := filepath.Join(skillPath, "SKILL.md")
+
+	fileInfo, _ := os.Stat(skillFile)
+	var fileSize int64
+	var modTime string
+	if fileInfo != nil {
+		fileSize = fileInfo.Size()
+		modTime = fileInfo.ModTime().Format("2006-01-02 15:04:05")
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"skill": map[string]interface{}{
+			"id":            skill.DirName,
+			"name":          skill.Name,
+			"description":   skill.Description,
+			"content":       skill.Content,
+			"path":          skill.Path,
+			"version":       skill.Version,
+			"tags":          skill.Tags,
+			"scripts":       skill.Scripts,
+			"sections":      skill.Sections,
+			"package_files": skill.PackageFiles,
+			"file_size":     fileSize,
+			"mod_time":      modTime,
+			"depth":         depthStr,
+			"section":       section,
+		},
+	})
+}
+
+// ListSkillPackageFiles lists all files in a skill directory (Agent Skills layout).
+func (h *SkillsHandler) ListSkillPackageFiles(c *gin.Context) {
+	skillID := c.Param("name")
+	files, err := skillpackage.ListPackageFiles(h.skillsRootAbs(), skillID)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"files": files})
+}
+
+// GetSkillPackageFile returns one file by relative path (?path=).
+func (h *SkillsHandler) GetSkillPackageFile(c *gin.Context) {
+	skillID := c.Param("name")
+	rel := strings.TrimSpace(c.Query("path"))
+	if rel == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "query path is required"})
+		return
+	}
+	b, err := skillpackage.ReadPackageFile(h.skillsRootAbs(), skillID, rel, 0)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"path": rel, "content": string(b)})
+}
+
+// PutSkillPackageFile writes a file inside the skill package.
+func (h *SkillsHandler) PutSkillPackageFile(c *gin.Context) {
+	skillID := c.Param("name")
+	var req struct {
+		Path    string `json:"path" binding:"required"`
+		Content string `json:"content"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的请求参数: " + err.Error()})
+		return
+	}
+	if req.Path == "SKILL.md" {
+		if err := skillpackage.ValidateSkillMDPackage([]byte(req.Content), skillID); err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+	}
+	if err := skillpackage.WritePackageFile(h.skillsRootAbs(), skillID, req.Path, []byte(req.Content)); err != nil {
+		h.logger.Error("写入 skill 文件失败", zap.String("skill", skillID), zap.String("path", req.Path), zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "saved", "path": req.Path})
+}
+
+// GetSkillBoundRoles 获取绑定指定skill的角色列表
+func (h *SkillsHandler) GetSkillBoundRoles(c *gin.Context) {
+	skillName := c.Param("name")
+	if skillName == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "skill名称不能为空"})
+		return
+	}
+
+	boundRoles := h.getRolesBoundToSkill(skillName)
+	c.JSON(http.StatusOK, gin.H{
+		"skill":       skillName,
+		"bound_roles": boundRoles,
+		"bound_count": len(boundRoles),
+	})
+}
+
+// getRolesBoundToSkill 预留：角色不再配置 skill 绑定，始终返回空列表。
+func (h *SkillsHandler) getRolesBoundToSkill(skillName string) []string {
+	_ = skillName
+	return nil
+}
+
+// CreateSkill 创建新 skill（标准 Agent Skills：生成 SKILL.md + YAML front matter）
+func (h *SkillsHandler) CreateSkill(c *gin.Context) {
+	var req struct {
+		Name        string `json:"name" binding:"required"`
+		Description string `json:"description" binding:"required"`
+		Content     string `json:"content" binding:"required"`
+	}
+
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的请求参数: " + err.Error()})
+		return
+	}
+
+	if !isValidSkillName(req.Name) {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "skill 目录名须为小写字母、数字、连字符（与 Agent Skills name 一致）"})
+		return
+	}
+
+	manifest := &skillpackage.SkillManifest{
+		Name:        req.Name,
+		Description: strings.TrimSpace(req.Description),
+	}
+	skillMD, err := skillpackage.BuildSkillMD(manifest, req.Content)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if err := skillpackage.ValidateSkillMDPackage(skillMD, req.Name); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	skillDir := filepath.Join(h.skillsRootAbs(), req.Name)
+	if err := os.MkdirAll(skillDir, 0755); err != nil {
+		h.logger.Error("创建skill目录失败", zap.String("skill", req.Name), zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "创建skill目录失败: " + err.Error()})
+		return
+	}
+
+	if _, err := os.Stat(filepath.Join(skillDir, "SKILL.md")); err == nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "skill已存在"})
+		return
+	}
+
+	if err := os.WriteFile(filepath.Join(skillDir, "SKILL.md"), skillMD, 0644); err != nil {
+		h.logger.Error("创建 SKILL.md 失败", zap.String("skill", req.Name), zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "创建 SKILL.md 失败: " + err.Error()})
+		return
+	}
+
+	h.logger.Info("创建skill成功", zap.String("skill", req.Name))
+	if h.audit != nil {
+		h.audit.RecordOK(c, "skill", "create", "创建 Skill", "skill", req.Name, nil)
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"message": "skill已创建",
+		"skill": map[string]interface{}{
+			"name": req.Name,
+			"path": skillDir,
+		},
+	})
+}
+
+// UpdateSkill 更新 SKILL.md（保留 front matter 中除 description 外的字段；可选覆盖 description）
+func (h *SkillsHandler) UpdateSkill(c *gin.Context) {
+	skillName := c.Param("name")
+	if skillName == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "skill名称不能为空"})
+		return
+	}
+
+	var req struct {
+		Description string `json:"description"`
+		Content     string `json:"content" binding:"required"`
+	}
+
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的请求参数: " + err.Error()})
+		return
+	}
+
+	mdPath := filepath.Join(h.skillsRootAbs(), skillName, "SKILL.md")
+	raw, err := os.ReadFile(mdPath)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "skill不存在: " + err.Error()})
+		return
+	}
+	m, _, err := skillpackage.ParseSkillMD(raw)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if req.Description != "" {
+		m.Description = strings.TrimSpace(req.Description)
+	}
+	skillMD, err := skillpackage.BuildSkillMD(m, req.Content)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if err := skillpackage.ValidateSkillMDPackage(skillMD, skillName); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	skillDir := filepath.Join(h.skillsRootAbs(), skillName)
+
+	if err := os.WriteFile(filepath.Join(skillDir, "SKILL.md"), skillMD, 0644); err != nil {
+		h.logger.Error("更新 SKILL.md 失败", zap.String("skill", skillName), zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "更新 SKILL.md 失败: " + err.Error()})
+		return
+	}
+
+	h.logger.Info("更新skill成功", zap.String("skill", skillName))
+	if h.audit != nil {
+		h.audit.RecordOK(c, "skill", "update", "更新 Skill", "skill", skillName, nil)
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"message": "skill已更新",
+	})
+}
+
+// DeleteSkill 删除skill
+func (h *SkillsHandler) DeleteSkill(c *gin.Context) {
+	skillName := c.Param("name")
+	if skillName == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "skill名称不能为空"})
+		return
+	}
+
+	// 检查是否有角色绑定了该skill，如果有则自动移除绑定
+	affectedRoles := h.removeSkillFromRoles(skillName)
+	if len(affectedRoles) > 0 {
+		h.logger.Info("从角色中移除skill绑定",
+			zap.String("skill", skillName),
+			zap.Strings("roles", affectedRoles))
+	}
+
+	skillDir := filepath.Join(h.skillsRootAbs(), skillName)
+	if err := os.RemoveAll(skillDir); err != nil {
+		h.logger.Error("删除skill失败", zap.String("skill", skillName), zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "删除skill失败: " + err.Error()})
+		return
+	}
+	responseMsg := "skill已删除"
+	if len(affectedRoles) > 0 {
+		responseMsg = fmt.Sprintf("skill已删除，已自动从 %d 个角色中移除绑定: %s",
+			len(affectedRoles), strings.Join(affectedRoles, ", "))
+	}
+
+	h.logger.Info("删除skill成功", zap.String("skill", skillName))
+	if h.audit != nil {
+		h.audit.RecordOK(c, "skill", "delete", "删除 Skill", "skill", skillName, map[string]interface{}{
+			"affected_roles": affectedRoles,
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"message":        responseMsg,
+		"affected_roles": affectedRoles,
+	})
+}
+
+// GetSkillStats 获取skills调用统计信息
+func (h *SkillsHandler) GetSkillStats(c *gin.Context) {
+	skillList, err := skillpackage.ListSkillDirNames(h.skillsRootAbs())
+	if err != nil {
+		h.logger.Error("获取skills列表失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	skillsDir := h.skillsRootAbs()
+
+	// 从数据库加载调用统计
+	var skillStatsMap map[string]*database.SkillStats
+	if h.db != nil {
+		dbStats, err := h.db.LoadSkillStats()
+		if err != nil {
+			h.logger.Warn("从数据库加载Skills统计信息失败", zap.Error(err))
+			skillStatsMap = make(map[string]*database.SkillStats)
+		} else {
+			skillStatsMap = dbStats
+		}
+	} else {
+		skillStatsMap = make(map[string]*database.SkillStats)
+	}
+
+	// 构建统计信息（包含所有skills，即使没有调用记录）
+	statsList := make([]map[string]interface{}, 0, len(skillList))
+	totalCalls := 0
+	totalSuccess := 0
+	totalFailed := 0
+
+	for _, skillName := range skillList {
+		stat, exists := skillStatsMap[skillName]
+		if !exists {
+			stat = &database.SkillStats{
+				SkillName:    skillName,
+				TotalCalls:   0,
+				SuccessCalls: 0,
+				FailedCalls:  0,
+			}
+		}
+
+		totalCalls += stat.TotalCalls
+		totalSuccess += stat.SuccessCalls
+		totalFailed += stat.FailedCalls
+
+		lastCallTimeStr := ""
+		if stat.LastCallTime != nil {
+			lastCallTimeStr = stat.LastCallTime.Format("2006-01-02 15:04:05")
+		}
+
+		statsList = append(statsList, map[string]interface{}{
+			"skill_name":     stat.SkillName,
+			"total_calls":    stat.TotalCalls,
+			"success_calls":  stat.SuccessCalls,
+			"failed_calls":   stat.FailedCalls,
+			"last_call_time": lastCallTimeStr,
+		})
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"total_skills":  len(skillList),
+		"total_calls":   totalCalls,
+		"total_success": totalSuccess,
+		"total_failed":  totalFailed,
+		"skills_dir":    skillsDir,
+		"stats":         statsList,
+	})
+}
+
+// ClearSkillStats 清空所有Skills统计信息
+func (h *SkillsHandler) ClearSkillStats(c *gin.Context) {
+	if h.db == nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "数据库连接未配置"})
+		return
+	}
+
+	if err := h.db.ClearSkillStats(); err != nil {
+		h.logger.Error("清空Skills统计信息失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "清空统计信息失败: " + err.Error()})
+		return
+	}
+
+	h.logger.Info("已清空所有Skills统计信息")
+	c.JSON(http.StatusOK, gin.H{
+		"message": "已清空所有Skills统计信息",
+	})
+}
+
+// ClearSkillStatsByName 清空指定skill的统计信息
+func (h *SkillsHandler) ClearSkillStatsByName(c *gin.Context) {
+	skillName := c.Param("name")
+	if skillName == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "skill名称不能为空"})
+		return
+	}
+
+	if h.db == nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "数据库连接未配置"})
+		return
+	}
+
+	if err := h.db.ClearSkillStatsByName(skillName); err != nil {
+		h.logger.Error("清空指定skill统计信息失败", zap.String("skill", skillName), zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "清空统计信息失败: " + err.Error()})
+		return
+	}
+
+	h.logger.Info("已清空指定skill统计信息", zap.String("skill", skillName))
+	c.JSON(http.StatusOK, gin.H{
+		"message": fmt.Sprintf("已清空skill '%s' 的统计信息", skillName),
+	})
+}
+
+// removeSkillFromRoles 预留：角色不再存储 skill 绑定，无操作。
+func (h *SkillsHandler) removeSkillFromRoles(skillName string) []string {
+	_ = skillName
+	return nil
+}
+
+// saveRolesConfig 保存角色配置到文件（从SkillsHandler调用）
+func (h *SkillsHandler) saveRolesConfig() error {
+	configDir := filepath.Dir(h.configPath)
+	rolesDir := h.config.RolesDir
+	if rolesDir == "" {
+		rolesDir = "roles" // 默认目录
+	}
+
+	// 如果是相对路径，相对于配置文件所在目录
+	if !filepath.IsAbs(rolesDir) {
+		rolesDir = filepath.Join(configDir, rolesDir)
+	}
+
+	// 确保目录存在
+	if err := os.MkdirAll(rolesDir, 0755); err != nil {
+		return fmt.Errorf("创建角色目录失败: %w", err)
+	}
+
+	// 保存每个角色到独立的文件
+	if h.config.Roles != nil {
+		for roleName, role := range h.config.Roles {
+			// 确保角色名称正确设置
+			if role.Name == "" {
+				role.Name = roleName
+			}
+
+			// 使用角色名称作为文件名（安全化文件名，避免特殊字符）
+			safeFileName := sanitizeRoleFileName(role.Name)
+			roleFile := filepath.Join(rolesDir, safeFileName+".yaml")
+
+			// 将角色配置序列化为YAML
+			roleData, err := yaml.Marshal(&role)
+			if err != nil {
+				h.logger.Error("序列化角色配置失败", zap.String("role", roleName), zap.Error(err))
+				continue
+			}
+
+			// 处理icon字段：确保包含\U的icon值被引号包围（YAML需要引号才能正确解析Unicode转义）
+			roleDataStr := string(roleData)
+			if role.Icon != "" && strings.HasPrefix(role.Icon, "\\U") {
+				// 匹配 icon: \UXXXXXXXX 格式（没有引号），排除已经有引号的情况
+				re := regexp.MustCompile(`(?m)^(icon:\s+)(\\U[0-9A-F]{8})(\s*)$`)
+				roleDataStr = re.ReplaceAllString(roleDataStr, `${1}"${2}"${3}`)
+				roleData = []byte(roleDataStr)
+			}
+
+			// 写入文件
+			if err := os.WriteFile(roleFile, roleData, 0644); err != nil {
+				h.logger.Error("保存角色配置文件失败", zap.String("role", roleName), zap.String("file", roleFile), zap.Error(err))
+				continue
+			}
+
+			h.logger.Info("角色配置已保存到文件", zap.String("role", roleName), zap.String("file", roleFile))
+		}
+	}
+
+	return nil
+}
+
+// sanitizeRoleFileName 将角色名称转换为安全的文件名
+func sanitizeRoleFileName(name string) string {
+	// 替换可能不安全的字符
+	replacer := map[rune]string{
+		'/':  "_",
+		'\\': "_",
+		':':  "_",
+		'*':  "_",
+		'?':  "_",
+		'"':  "_",
+		'<':  "_",
+		'>':  "_",
+		'|':  "_",
+		' ':  "_",
+	}
+
+	var result []rune
+	for _, r := range name {
+		if replacement, ok := replacer[r]; ok {
+			result = append(result, []rune(replacement)...)
+		} else {
+			result = append(result, r)
+		}
+	}
+
+	fileName := string(result)
+	// 如果文件名为空，使用默认名称
+	if fileName == "" {
+		fileName = "role"
+	}
+
+	return fileName
+}
+
+// isValidSkillName 验证 skill 目录名（与 Agent Skills 的 name 字段一致：小写、数字、连字符）
+func isValidSkillName(name string) bool {
+	if name == "" || len(name) > 100 {
+		return false
+	}
+	for _, r := range name {
+		if !((r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-') {
+			return false
+		}
+	}
+	return true
+}

internal/handler/sse_keepalive.go

@@ -0,0 +1,88 @@
+package handler
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+// sseInterval is how often we write on long SSE streams. Shorter intervals help NATs and
+// some proxies that treat connections as idle; 10s is a reasonable balance with traffic.
+const sseKeepaliveInterval = 10 * time.Second
+
+// runSSEKeepalive starts periodic SSE heartbeats in a background goroutine.
+// The returned stop function must be deferred (or called) before the handler returns so the
+// goroutine exits before Gin finalizes the ResponseWriter (avoids "Write called after Handler finished").
+//
+// writeMu must be the same mutex used by the handler's event writes for this request: concurrent
+// writes to http.ResponseWriter break chunked transfer encoding (browser: net::ERR_INVALID_CHUNKED_ENCODING).
+func runSSEKeepalive(c *gin.Context, writeMu *sync.Mutex) func() {
+	if writeMu == nil {
+		return func() {}
+	}
+	stop := make(chan struct{})
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		sseKeepaliveLoop(c, stop, writeMu)
+	}()
+	var once sync.Once
+	return func() {
+		once.Do(func() {
+			close(stop)
+			wg.Wait()
+		})
+	}
+}
+
+// sseKeepaliveLoop sends periodic SSE traffic so proxies (e.g. nginx proxy_read_timeout), NATs,
+// and load balancers do not close long-running streams. Some intermediaries ignore comment-only
+// lines, so we send both a comment and a minimal data frame (type heartbeat) per tick.
+func sseKeepaliveLoop(c *gin.Context, stop <-chan struct{}, writeMu *sync.Mutex) {
+	ticker := time.NewTicker(sseKeepaliveInterval)
+	defer ticker.Stop()
+	ctx := c.Request.Context()
+	for {
+		select {
+		case <-stop:
+			return
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			writeMu.Lock()
+			if sseShuttingDown(stop, ctx) {
+				writeMu.Unlock()
+				return
+			}
+			if _, err := fmt.Fprintf(c.Writer, ": keepalive\n\n"); err != nil {
+				writeMu.Unlock()
+				return
+			}
+			// data: frame so strict proxies still see downstream bytes (comments alone may not reset timers)
+			if _, err := fmt.Fprintf(c.Writer, `data: {"type":"heartbeat"}`+"\n\n"); err != nil {
+				writeMu.Unlock()
+				return
+			}
+			if flusher, ok := c.Writer.(http.Flusher); ok {
+				flusher.Flush()
+			}
+			writeMu.Unlock()
+		}
+	}
+}
+
+func sseShuttingDown(stop <-chan struct{}, ctx context.Context) bool {
+	select {
+	case <-stop:
+		return true
+	case <-ctx.Done():
+		return true
+	default:
+		return false
+	}
+}

internal/handler/sse_keepalive_test.go

@@ -0,0 +1,61 @@
+package handler
+
+import (
+	"context"
+	"net/http/httptest"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestRunSSEKeepaliveStopsBeforeHandlerReturns(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("GET", "/events", nil)
+
+	var writeMu sync.Mutex
+	stop := runSSEKeepalive(c, &writeMu)
+	stop()
+
+	// A second stop must be safe (channel already closed, goroutine already exited).
+	stop()
+}
+
+func TestRunSSEKeepaliveExitsOnClientDisconnect(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	ctx, cancel := context.WithCancel(context.Background())
+	c.Request = httptest.NewRequest("GET", "/events", nil).WithContext(ctx)
+
+	var writeMu sync.Mutex
+	stop := runSSEKeepalive(c, &writeMu)
+	cancel()
+
+	done := make(chan struct{})
+	go func() {
+		stop()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("keepalive stop did not complete after client disconnect")
+	}
+}
+
+func TestRunSSEKeepaliveNilMutexIsNoop(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("GET", "/events", nil)
+
+	stop := runSSEKeepalive(c, nil)
+	stop()
+}

internal/handler/task_event_bus.go

@@ -0,0 +1,116 @@
+package handler
+
+import "sync"
+
+// TaskEventBus 将主 SSE 连接上的事件镜像给后订阅的客户端（例如刷新页面后、HITL 审批通过需继续收事件）。
+// 每个 payload 为完整 SSE 行： "data: {...}\n\n"
+type TaskEventBus struct {
+	mu   sync.RWMutex
+	subs map[string]map[*taskEventSub]struct{}
+}
+
+type taskEventSub struct {
+	mu     sync.Mutex
+	ch     chan []byte
+	closed bool
+}
+
+func (s *taskEventSub) sendNonBlocking(line []byte) bool {
+	if s == nil {
+		return false
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.closed {
+		return false
+	}
+	select {
+	case s.ch <- line:
+		return true
+	default:
+		return false
+	}
+}
+
+func (s *taskEventSub) closeOnce() {
+	if s == nil {
+		return
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.closed {
+		return
+	}
+	s.closed = true
+	close(s.ch)
+}
+
+func NewTaskEventBus() *TaskEventBus {
+	return &TaskEventBus{
+		subs: make(map[string]map[*taskEventSub]struct{}),
+	}
+}
+
+// Subscribe 注册订阅；cancel 时需调用 Unsubscribe。
+func (b *TaskEventBus) Subscribe(conversationID string) (sub *taskEventSub, ch <-chan []byte) {
+	chBuf := make(chan []byte, 256)
+	sub = &taskEventSub{ch: chBuf}
+	b.mu.Lock()
+	if b.subs[conversationID] == nil {
+		b.subs[conversationID] = make(map[*taskEventSub]struct{})
+	}
+	b.subs[conversationID][sub] = struct{}{}
+	b.mu.Unlock()
+	return sub, chBuf
+}
+
+func (b *TaskEventBus) Unsubscribe(conversationID string, sub *taskEventSub) {
+	if sub == nil {
+		return
+	}
+	b.mu.Lock()
+	m, ok := b.subs[conversationID]
+	if !ok {
+		b.mu.Unlock()
+		return
+	}
+	delete(m, sub)
+	if len(m) == 0 {
+		delete(b.subs, conversationID)
+	}
+	b.mu.Unlock()
+	sub.closeOnce()
+}
+
+// Publish 非阻塞投递；慢消费者丢帧（HITL 场景以最新状态为准，丢帧可接受）。
+func (b *TaskEventBus) Publish(conversationID string, line []byte) {
+	if b == nil || conversationID == "" || len(line) == 0 {
+		return
+	}
+	b.mu.RLock()
+	m := b.subs[conversationID]
+	subs := make([]*taskEventSub, 0, len(m))
+	for s := range m {
+		subs = append(subs, s)
+	}
+	b.mu.RUnlock()
+
+	cp := append([]byte(nil), line...)
+	for _, s := range subs {
+		s.sendNonBlocking(cp)
+	}
+}
+
+// CloseConversation 任务结束时关闭该会话所有订阅 channel。
+func (b *TaskEventBus) CloseConversation(conversationID string) {
+	if b == nil || conversationID == "" {
+		return
+	}
+	b.mu.Lock()
+	m := b.subs[conversationID]
+	delete(b.subs, conversationID)
+	b.mu.Unlock()
+	for sub := range m {
+		sub.closeOnce()
+	}
+}

internal/handler/task_manager.go

@@ -0,0 +1,627 @@
+package handler
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"sync"
+	"time"
+
+	"cyberstrike-ai/internal/multiagent"
+)
+
+// ErrTaskCancelled 用户取消任务的错误
+var ErrTaskCancelled = errors.New("agent task cancelled by user")
+
+// ErrTaskAlreadyRunning 会话已有任务正在执行
+var ErrTaskAlreadyRunning = errors.New("agent task already running for conversation")
+
+// shouldPersistEinoAgentTraceAfterRunError：Eino 相关 Run 非成功返回时，是否仍写入 last_react_* 供下轮 loadHistoryFromAgentTrace。
+// 当前策略：无论正常结束、异常结束或用户主动停止，都尽量保留最后可用轨迹，
+// 以便在同一会话继续时可基于原始上下文续跑，而不是回退到仅消息文本历史。
+func shouldPersistEinoAgentTraceAfterRunError(baseCtx context.Context) bool {
+	return true
+}
+
+// AgentTask 描述正在运行的Agent任务
+type AgentTask struct {
+	ConversationID string    `json:"conversationId"`
+	Title          string    `json:"title,omitempty"`
+	Message        string    `json:"message,omitempty"`
+	StartedAt      time.Time `json:"startedAt"`
+	Status         string    `json:"status"`
+	CancellingAt   time.Time `json:"-"` // 进入 cancelling 状态的时间，用于清理长时间卡住的任务
+
+	// ActiveMCPExecutionID 当前正在执行的 MCP 工具 executionId（仅内存，供「中断并继续」= 仅掐当前工具）
+	ActiveMCPExecutionID string `json:"-"`
+
+	// InterruptContinueNote 无 MCP 时「中断并继续」由用户在弹窗中填写的补充说明（Cancel 前写入，续跑轮次读取后清空）
+	InterruptContinueNote string `json:"-"`
+
+	// activeEinoExecuteCancel 当前进行中的 Eino filesystem execute 取消函数（与 MCP 工具并行，供中断并继续）
+	activeEinoExecuteCancel context.CancelFunc
+	// activeEinoExecuteAbortNote AbortActiveEinoExecute 写入的用户说明，由 execute 收尾时合并进工具结果
+	activeEinoExecuteAbortNote string
+
+	// hitlCognition 本轮运行中供 HITL/审计 Agent 读取的上下文（用户原话 + 思考，不含会话历史）
+	hitlCognition *hitlCognitionState
+
+	// agentRuntimeCancel 当前 Eino ADK 原生 AgentCancelFunc 包装；取消任务时先触发它，再走 context 兜底。
+	agentRuntimeCancel        func(error) bool
+	agentRuntimeCancelVersion uint64
+
+	// agentTurnLoopInterrupt 当前 Eino TurnLoop 用户补充 push hook；中断并继续时优先将补充作为新 turn item 入队。
+	agentTurnLoopInterrupt        func(string) bool
+	agentTurnLoopInterruptVersion uint64
+
+	cancel func(error)
+}
+
+// RegisterRunningTool 实现 mcp.ToolRunRegistry：工具开始时登记本会话当前 executionId。
+func (m *AgentTaskManager) RegisterRunningTool(conversationID, executionID string) {
+	conversationID = strings.TrimSpace(conversationID)
+	executionID = strings.TrimSpace(executionID)
+	if conversationID == "" || executionID == "" {
+		return
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if t, ok := m.tasks[conversationID]; ok && t != nil {
+		t.ActiveMCPExecutionID = executionID
+	}
+}
+
+// UnregisterRunningTool 工具结束时清除登记（仅当 id 仍匹配时清除，避免并发串单）。
+func (m *AgentTaskManager) UnregisterRunningTool(conversationID, executionID string) {
+	conversationID = strings.TrimSpace(conversationID)
+	executionID = strings.TrimSpace(executionID)
+	if conversationID == "" || executionID == "" {
+		return
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if t, ok := m.tasks[conversationID]; ok && t != nil {
+		if t.ActiveMCPExecutionID == executionID {
+			t.ActiveMCPExecutionID = ""
+		}
+	}
+}
+
+// RegisterActiveEinoExecute 登记进行中的 Eino filesystem execute（每会话同时仅一条）。
+func (m *AgentTaskManager) RegisterActiveEinoExecute(conversationID string, cancel context.CancelFunc) {
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" || cancel == nil {
+		return
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if t, ok := m.tasks[conversationID]; ok && t != nil {
+		t.activeEinoExecuteCancel = cancel
+		t.activeEinoExecuteAbortNote = ""
+	}
+}
+
+// UnregisterActiveEinoExecute execute 正常结束或已取消后清除登记。
+func (m *AgentTaskManager) UnregisterActiveEinoExecute(conversationID string) {
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" {
+		return
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if t, ok := m.tasks[conversationID]; ok && t != nil {
+		t.activeEinoExecuteCancel = nil
+		t.activeEinoExecuteAbortNote = ""
+	}
+}
+
+// ConversationIDForActiveMCPExecution 根据当前登记的工具 executionId 反查会话 ID（供 MCP 监控页按 executionId 终止）。
+func (m *AgentTaskManager) ConversationIDForActiveMCPExecution(executionID string) string {
+	executionID = strings.TrimSpace(executionID)
+	if executionID == "" {
+		return ""
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	for convID, t := range m.tasks {
+		if t != nil && t.ActiveMCPExecutionID == executionID {
+			return convID
+		}
+	}
+	return ""
+}
+
+// ConversationIDForActiveEinoExecute 返回当前唯一进行 Eino execute 的会话 ID；多会话并行时返回空。
+func (m *AgentTaskManager) ConversationIDForActiveEinoExecute() (string, bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	var found string
+	count := 0
+	for convID, t := range m.tasks {
+		if t != nil && t.activeEinoExecuteCancel != nil {
+			found = convID
+			count++
+		}
+	}
+	if count == 1 {
+		return found, true
+	}
+	return "", false
+}
+
+// AbortActiveEinoExecute 终止当前 Eino execute 并暂存用户说明（与 MCP 工具终止一致）。
+func (m *AgentTaskManager) AbortActiveEinoExecute(conversationID, note string) bool {
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" {
+		return false
+	}
+	m.mu.Lock()
+	t, ok := m.tasks[conversationID]
+	if !ok || t == nil || t.activeEinoExecuteCancel == nil {
+		m.mu.Unlock()
+		return false
+	}
+	t.activeEinoExecuteAbortNote = strings.TrimSpace(note)
+	cancel := t.activeEinoExecuteCancel
+	m.mu.Unlock()
+	cancel()
+	return true
+}
+
+// TakeEinoExecuteAbortNote 读取并清空 execute 终止说明（execute 收尾时调用一次）。
+func (m *AgentTaskManager) TakeEinoExecuteAbortNote(conversationID string) string {
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" {
+		return ""
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if t, ok := m.tasks[conversationID]; ok && t != nil {
+		n := t.activeEinoExecuteAbortNote
+		t.activeEinoExecuteAbortNote = ""
+		return n
+	}
+	return ""
+}
+
+// SetInterruptContinueNote 在发起 ErrInterruptContinue 取消前写入用户补充说明（仅内存）。
+func (m *AgentTaskManager) SetInterruptContinueNote(conversationID, note string) {
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" {
+		return
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if t, ok := m.tasks[conversationID]; ok && t != nil {
+		t.InterruptContinueNote = note
+	}
+}
+
+// TakeInterruptContinueNote 读取并清空补充说明（续跑开始时调用一次）。
+func (m *AgentTaskManager) TakeInterruptContinueNote(conversationID string) string {
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" {
+		return ""
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if t, ok := m.tasks[conversationID]; ok && t != nil {
+		n := t.InterruptContinueNote
+		t.InterruptContinueNote = ""
+		return n
+	}
+	return ""
+}
+
+// BindTaskCancel 在同一运行任务内替换与 context 绑定的 cancel 函数（用于中断后继续时换新 baseCtx）。
+func (m *AgentTaskManager) BindTaskCancel(conversationID string, cancel context.CancelCauseFunc) {
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" || cancel == nil {
+		return
+	}
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if t, ok := m.tasks[conversationID]; ok && t != nil {
+		t.cancel = func(err error) {
+			cancel(err)
+		}
+	}
+}
+
+// BindAgentRuntimeCancel 登记当前运行段的 Eino 原生 cancel hook。
+func (m *AgentTaskManager) BindAgentRuntimeCancel(conversationID string, cancel func(error) bool) func() {
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" || cancel == nil {
+		return func() {}
+	}
+	m.mu.Lock()
+	t, ok := m.tasks[conversationID]
+	if !ok || t == nil {
+		m.mu.Unlock()
+		return func() {}
+	}
+	t.agentRuntimeCancelVersion++
+	version := t.agentRuntimeCancelVersion
+	t.agentRuntimeCancel = cancel
+	m.mu.Unlock()
+
+	return func() {
+		m.mu.Lock()
+		defer m.mu.Unlock()
+		if cur, exists := m.tasks[conversationID]; exists && cur != nil && cur.agentRuntimeCancelVersion == version {
+			cur.agentRuntimeCancel = nil
+		}
+	}
+}
+
+// BindAgentTurnLoopInterrupt 登记当前运行任务的 Eino TurnLoop 用户补充入队 hook。
+func (m *AgentTaskManager) BindAgentTurnLoopInterrupt(conversationID string, push func(string) bool) func() {
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" || push == nil {
+		return func() {}
+	}
+	m.mu.Lock()
+	t, ok := m.tasks[conversationID]
+	if !ok || t == nil {
+		m.mu.Unlock()
+		return func() {}
+	}
+	t.agentTurnLoopInterruptVersion++
+	version := t.agentTurnLoopInterruptVersion
+	t.agentTurnLoopInterrupt = push
+	m.mu.Unlock()
+
+	return func() {
+		m.mu.Lock()
+		defer m.mu.Unlock()
+		if cur, exists := m.tasks[conversationID]; exists && cur != nil && cur.agentTurnLoopInterruptVersion == version {
+			cur.agentTurnLoopInterrupt = nil
+		}
+	}
+}
+
+// ActiveMCPExecutionID 返回当前会话进行中的工具 executionId，无则空串。
+func (m *AgentTaskManager) ActiveMCPExecutionID(conversationID string) string {
+	conversationID = strings.TrimSpace(conversationID)
+	if conversationID == "" {
+		return ""
+	}
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	if t, ok := m.tasks[conversationID]; ok && t != nil {
+		return strings.TrimSpace(t.ActiveMCPExecutionID)
+	}
+	return ""
+}
+
+// CompletedTask 已完成的任务（用于历史记录）
+type CompletedTask struct {
+	ConversationID string    `json:"conversationId"`
+	Title          string    `json:"title,omitempty"`
+	Message        string    `json:"message,omitempty"`
+	StartedAt      time.Time `json:"startedAt"`
+	CompletedAt    time.Time `json:"completedAt"`
+	Status         string    `json:"status"`
+}
+
+// AgentTaskManager 管理正在运行的Agent任务
+type AgentTaskManager struct {
+	mu               sync.RWMutex
+	tasks            map[string]*AgentTask
+	completedTasks   []*CompletedTask // 最近完成的任务历史
+	maxHistorySize   int              // 最大历史记录数
+	historyRetention time.Duration    // 历史记录保留时间
+	eventBus         *TaskEventBus    // 可选：任务结束时关闭镜像 SSE 订阅
+	// toolCanceler 在用户整轮停止任务或会话结束时终止该会话仍在运行的 MCP 工具（非「中断并继续」）。
+	toolCanceler func(conversationID string)
+}
+
+const (
+	// cancellingStuckThreshold 处于「取消中」超过此时长则强制从运行列表移除。正常取消会在当前步骤内返回，
+	// 超过则视为卡住，尽快释放会话。常见做法多为 30–60s 内释放。
+	cancellingStuckThreshold = 45 * time.Second
+	// cancellingStuckThresholdLegacy 未记录 CancellingAt 时用 StartedAt 判断的兜底时长
+	cancellingStuckThresholdLegacy = 2 * time.Minute
+	cleanupInterval                = 15 * time.Second // 与上面阈值配合，最长约 60s 内移除
+)
+
+// NewAgentTaskManager 创建任务管理器
+func NewAgentTaskManager() *AgentTaskManager {
+	m := &AgentTaskManager{
+		tasks:            make(map[string]*AgentTask),
+		completedTasks:   make([]*CompletedTask, 0),
+		maxHistorySize:   50,             // 最多保留50条历史记录
+		historyRetention: 24 * time.Hour, // 保留24小时
+	}
+	go m.runStuckCancellingCleanup()
+	return m
+}
+
+// SetTaskEventBus 设置任务事件总线（与 AgentHandler 共用同一实例）。
+func (m *AgentTaskManager) SetTaskEventBus(b *TaskEventBus) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.eventBus = b
+}
+
+// SetToolCanceler 设置整轮停止任务/会话结束时终止仍在运行 MCP 工具的回调（由 AgentHandler 注入）。
+func (m *AgentTaskManager) SetToolCanceler(fn func(conversationID string)) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.toolCanceler = fn
+}
+
+// GetTask 返回运行中任务（无则 nil）。
+func (m *AgentTaskManager) GetTask(conversationID string) *AgentTask {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	return m.tasks[conversationID]
+}
+
+// GetTaskSnapshot 返回运行任务的只读副本，供状态展示使用，避免锁外读取可变任务字段。
+func (m *AgentTaskManager) GetTaskSnapshot(conversationID string) *AgentTask {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	task := m.tasks[conversationID]
+	if task == nil {
+		return nil
+	}
+	snapshot := *task
+	return &snapshot
+}
+
+// runStuckCancellingCleanup 定期将长时间处于「取消中」的任务强制结束，避免卡住无法发新消息
+func (m *AgentTaskManager) runStuckCancellingCleanup() {
+	ticker := time.NewTicker(cleanupInterval)
+	defer ticker.Stop()
+	for range ticker.C {
+		m.cleanupStuckCancelling()
+	}
+}
+
+func (m *AgentTaskManager) cleanupStuckCancelling() {
+	m.mu.Lock()
+	var toFinish []string
+	now := time.Now()
+	for id, task := range m.tasks {
+		if task.Status != "cancelling" {
+			continue
+		}
+		var elapsed time.Duration
+		if !task.CancellingAt.IsZero() {
+			elapsed = now.Sub(task.CancellingAt)
+			if elapsed < cancellingStuckThreshold {
+				continue
+			}
+		} else {
+			elapsed = now.Sub(task.StartedAt)
+			if elapsed < cancellingStuckThresholdLegacy {
+				continue
+			}
+		}
+		toFinish = append(toFinish, id)
+	}
+	m.mu.Unlock()
+	for _, id := range toFinish {
+		m.FinishTask(id, "cancelled")
+	}
+}
+
+// StartTask 注册并开始一个新的任务
+func (m *AgentTaskManager) StartTask(conversationID, message string, cancel context.CancelCauseFunc) (*AgentTask, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	if _, exists := m.tasks[conversationID]; exists {
+		return nil, ErrTaskAlreadyRunning
+	}
+
+	task := &AgentTask{
+		ConversationID: conversationID,
+		Message:        message,
+		StartedAt:      time.Now(),
+		Status:         "running",
+		cancel: func(err error) {
+			if cancel != nil {
+				cancel(err)
+			}
+		},
+	}
+
+	m.tasks[conversationID] = task
+	task.hitlCognition = &hitlCognitionState{UserMessage: strings.TrimSpace(message)}
+	return task, nil
+}
+
+// CancelTask 取消指定会话的任务。若任务已在取消中，仍返回 (true, nil) 以便接口幂等、前端不报错。
+func (m *AgentTaskManager) CancelTask(conversationID string, cause error) (bool, error) {
+	m.mu.Lock()
+	task, exists := m.tasks[conversationID]
+	if !exists {
+		m.mu.Unlock()
+		return false, nil
+	}
+
+	// 如果已经处于取消流程，视为成功（幂等），避免前端重复点击报「未找到任务」
+	if task.Status == "cancelling" {
+		m.mu.Unlock()
+		return true, nil
+	}
+
+	// ErrInterruptContinue：仅掐断当前推理步骤，随后由处理器续跑，不进入长时间「取消中」态。
+	if cause != nil && errors.Is(cause, multiagent.ErrInterruptContinue) {
+		task.Status = "running"
+	} else {
+		task.Status = "cancelling"
+		task.CancellingAt = time.Now()
+	}
+	if cause != nil && errors.Is(cause, ErrTaskCancelled) {
+		task.InterruptContinueNote = ""
+	}
+	cancel := task.cancel
+	if cause == nil {
+		cause = ErrTaskCancelled
+	}
+	interruptPush := task.agentTurnLoopInterrupt
+	interruptNote := task.InterruptContinueNote
+	runtimeCancel := task.agentRuntimeCancel
+	var toolCanceler func(string)
+	if errors.Is(cause, ErrTaskCancelled) {
+		toolCanceler = m.toolCanceler
+	}
+	m.mu.Unlock()
+
+	if errors.Is(cause, multiagent.ErrInterruptContinue) && interruptPush != nil && interruptPush(interruptNote) {
+		m.mu.Lock()
+		if cur, exists := m.tasks[conversationID]; exists && cur != nil {
+			cur.InterruptContinueNote = ""
+		}
+		m.mu.Unlock()
+		return true, nil
+	}
+
+	runtimeHandled := false
+	if runtimeCancel != nil {
+		runtimeHandled = runtimeCancel(cause)
+	}
+	if cancel != nil && !runtimeHandled {
+		cancel(cause)
+	}
+	if toolCanceler != nil {
+		toolCanceler(conversationID)
+	}
+	return true, nil
+}
+
+// UpdateTaskStatus 更新任务状态但不删除任务（用于在发送事件前更新状态）
+func (m *AgentTaskManager) UpdateTaskStatus(conversationID string, status string) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	task, exists := m.tasks[conversationID]
+	if !exists {
+		return
+	}
+
+	if status != "" {
+		task.Status = status
+	}
+}
+
+// FinishTask 完成任务并从管理器中移除
+func (m *AgentTaskManager) FinishTask(conversationID string, finalStatus string) {
+	m.mu.Lock()
+	task, exists := m.tasks[conversationID]
+	if !exists {
+		m.mu.Unlock()
+		return
+	}
+
+	if finalStatus != "" {
+		task.Status = finalStatus
+	}
+	toolCanceler := m.toolCanceler
+	activeEinoExecuteCancel := task.activeEinoExecuteCancel
+
+	// 保存到历史记录
+	completedTask := &CompletedTask{
+		ConversationID: task.ConversationID,
+		Message:        task.Message,
+		StartedAt:      task.StartedAt,
+		CompletedAt:    time.Now(),
+		Status:         finalStatus,
+	}
+
+	// 添加到历史记录
+	m.completedTasks = append(m.completedTasks, completedTask)
+
+	// 清理过期和过多的历史记录
+	m.cleanupHistory()
+
+	// 从运行任务中移除
+	delete(m.tasks, conversationID)
+	bus := m.eventBus
+	m.mu.Unlock()
+	if toolCanceler != nil {
+		toolCanceler(conversationID)
+	}
+	if activeEinoExecuteCancel != nil {
+		activeEinoExecuteCancel()
+	}
+	if bus != nil {
+		bus.CloseConversation(conversationID)
+	}
+}
+
+// cleanupHistory 清理过期的历史记录
+func (m *AgentTaskManager) cleanupHistory() {
+	now := time.Now()
+	cutoffTime := now.Add(-m.historyRetention)
+
+	// 过滤掉过期的记录
+	validTasks := make([]*CompletedTask, 0, len(m.completedTasks))
+	for _, task := range m.completedTasks {
+		if task.CompletedAt.After(cutoffTime) {
+			validTasks = append(validTasks, task)
+		}
+	}
+
+	// 如果仍然超过最大数量，只保留最新的
+	if len(validTasks) > m.maxHistorySize {
+		// 按完成时间排序，保留最新的
+		// 由于是追加的，最新的在最后，所以直接取最后N个
+		start := len(validTasks) - m.maxHistorySize
+		validTasks = validTasks[start:]
+	}
+
+	m.completedTasks = validTasks
+}
+
+// GetActiveTasks 返回所有正在运行的任务
+func (m *AgentTaskManager) GetActiveTasks() []*AgentTask {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	result := make([]*AgentTask, 0, len(m.tasks))
+	for _, task := range m.tasks {
+		result = append(result, &AgentTask{
+			ConversationID: task.ConversationID,
+			Message:        task.Message,
+			StartedAt:      task.StartedAt,
+			Status:         task.Status,
+		})
+	}
+	return result
+}
+
+// GetCompletedTasks 返回最近完成的任务历史
+func (m *AgentTaskManager) GetCompletedTasks() []*CompletedTask {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	// 清理过期记录（只读锁，不影响其他操作）
+	// 注意：这里不能直接调用cleanupHistory，因为需要写锁
+	// 所以返回时过滤过期记录
+	now := time.Now()
+	cutoffTime := now.Add(-m.historyRetention)
+
+	result := make([]*CompletedTask, 0, len(m.completedTasks))
+	for _, task := range m.completedTasks {
+		if task.CompletedAt.After(cutoffTime) {
+			result = append(result, task)
+		}
+	}
+
+	// 按完成时间倒序排序（最新的在前）
+	// 由于是追加的，最新的在最后，需要反转
+	for i, j := 0, len(result)-1; i < j; i, j = i+1, j-1 {
+		result[i], result[j] = result[j], result[i]
+	}
+
+	// 限制返回数量
+	if len(result) > m.maxHistorySize {
+		result = result[:m.maxHistorySize]
+	}
+
+	return result
+}

internal/handler/task_manager_eino_execute_test.go

@@ -0,0 +1,56 @@
+package handler
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestAbortActiveEinoExecute(t *testing.T) {
+	m := NewAgentTaskManager()
+	conv := "conv-eino-exec-abort"
+	ctx, cancel := context.WithCancel(context.Background())
+	_, err := m.StartTask(conv, "test", func(error) {})
+	if err != nil {
+		t.Fatalf("StartTask: %v", err)
+	}
+	m.RegisterActiveEinoExecute(conv, cancel)
+
+	done := make(chan struct{})
+	go func() {
+		<-ctx.Done()
+		close(done)
+	}()
+
+	if !m.AbortActiveEinoExecute(conv, "跳过域名收集") {
+		t.Fatal("expected abort to succeed")
+	}
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("execute cancel did not propagate")
+	}
+	if got := m.TakeEinoExecuteAbortNote(conv); got != "跳过域名收集" {
+		t.Fatalf("abort note = %q, want 跳过域名收集", got)
+	}
+	m.UnregisterActiveEinoExecute(conv)
+	if m.AbortActiveEinoExecute(conv, "") {
+		t.Fatal("second abort should fail when no active execute")
+	}
+}
+
+func TestConversationIDForActiveMCPExecution(t *testing.T) {
+	m := NewAgentTaskManager()
+	conv := "conv-mcp-exec"
+	_, err := m.StartTask(conv, "test", func(error) {})
+	if err != nil {
+		t.Fatalf("StartTask: %v", err)
+	}
+	m.RegisterRunningTool(conv, "exec-123")
+	if got := m.ConversationIDForActiveMCPExecution("exec-123"); got != conv {
+		t.Fatalf("got %q, want %q", got, conv)
+	}
+	if got := m.ConversationIDForActiveMCPExecution("missing"); got != "" {
+		t.Fatalf("missing should be empty, got %q", got)
+	}
+}

internal/handler/task_manager_tool_cancel_test.go

@@ -0,0 +1,246 @@
+package handler
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"cyberstrike-ai/internal/multiagent"
+)
+
+func TestCancelTaskInvokesToolCancelerOnFullStop(t *testing.T) {
+	tm := NewAgentTaskManager()
+	called := false
+	tm.SetToolCanceler(func(conversationID string) {
+		if conversationID == "conv-1" {
+			called = true
+		}
+	})
+
+	_, cancel := context.WithCancelCause(context.Background())
+	_, err := tm.StartTask("conv-1", "hello", cancel)
+	if err != nil {
+		t.Fatalf("StartTask: %v", err)
+	}
+
+	ok, err := tm.CancelTask("conv-1", ErrTaskCancelled)
+	if err != nil || !ok {
+		t.Fatalf("CancelTask: ok=%v err=%v", ok, err)
+	}
+	if !called {
+		t.Fatal("expected tool canceler to be invoked on full task cancel")
+	}
+}
+
+func TestCancelTaskUsesAgentRuntimeCancelAsPrimaryPath(t *testing.T) {
+	tm := NewAgentTaskManager()
+	var order []string
+	tm.SetToolCanceler(func(conversationID string) {
+		if conversationID == "conv-native" {
+			order = append(order, "tool")
+		}
+	})
+
+	_, cancel := context.WithCancelCause(context.Background())
+	if _, err := tm.StartTask("conv-native", "hello", func(err error) {
+		order = append(order, "context")
+		cancel(err)
+	}); err != nil {
+		t.Fatalf("StartTask: %v", err)
+	}
+	unregister := tm.BindAgentRuntimeCancel("conv-native", func(err error) bool {
+		if !errors.Is(err, ErrTaskCancelled) {
+			t.Fatalf("runtime cancel got %v", err)
+		}
+		order = append(order, "runtime")
+		return true
+	})
+	defer unregister()
+
+	ok, err := tm.CancelTask("conv-native", ErrTaskCancelled)
+	if err != nil || !ok {
+		t.Fatalf("CancelTask: ok=%v err=%v", ok, err)
+	}
+	want := []string{"runtime", "tool"}
+	if len(order) != len(want) {
+		t.Fatalf("order length got %d want %d: %#v", len(order), len(want), order)
+	}
+	for i := range want {
+		if order[i] != want[i] {
+			t.Fatalf("order[%d] got %q want %q; full=%#v", i, order[i], want[i], order)
+		}
+	}
+}
+
+func TestCancelTaskFallsBackToContextWhenAgentRuntimeCancelMisses(t *testing.T) {
+	tm := NewAgentTaskManager()
+	var order []string
+
+	_, cancel := context.WithCancelCause(context.Background())
+	if _, err := tm.StartTask("conv-fallback", "hello", func(err error) {
+		order = append(order, "context")
+		cancel(err)
+	}); err != nil {
+		t.Fatalf("StartTask: %v", err)
+	}
+	unregister := tm.BindAgentRuntimeCancel("conv-fallback", func(err error) bool {
+		order = append(order, "runtime")
+		return false
+	})
+	defer unregister()
+
+	ok, err := tm.CancelTask("conv-fallback", ErrTaskCancelled)
+	if err != nil || !ok {
+		t.Fatalf("CancelTask: ok=%v err=%v", ok, err)
+	}
+	want := []string{"runtime", "context"}
+	if len(order) != len(want) {
+		t.Fatalf("order length got %d want %d: %#v", len(order), len(want), order)
+	}
+	for i := range want {
+		if order[i] != want[i] {
+			t.Fatalf("order[%d] got %q want %q; full=%#v", i, order[i], want[i], order)
+		}
+	}
+}
+
+func TestCancelTaskSkipsToolCancelerOnInterruptContinue(t *testing.T) {
+	tm := NewAgentTaskManager()
+	called := false
+	tm.SetToolCanceler(func(conversationID string) {
+		called = true
+	})
+
+	_, cancel := context.WithCancelCause(context.Background())
+	_, err := tm.StartTask("conv-1", "hello", cancel)
+	if err != nil {
+		t.Fatalf("StartTask: %v", err)
+	}
+
+	ok, err := tm.CancelTask("conv-1", multiagent.ErrInterruptContinue)
+	if err != nil || !ok {
+		t.Fatalf("CancelTask: ok=%v err=%v", ok, err)
+	}
+	if called {
+		t.Fatal("tool canceler must not run for interrupt-continue")
+	}
+}
+
+func TestCancelTaskPushesInterruptContinueToTurnLoopFirst(t *testing.T) {
+	tm := NewAgentTaskManager()
+	ctx, cancel := context.WithCancelCause(context.Background())
+	if _, err := tm.StartTask("conv-turn", "hello", cancel); err != nil {
+		t.Fatalf("StartTask: %v", err)
+	}
+	tm.SetInterruptContinueNote("conv-turn", "focus ssh")
+
+	var gotNote string
+	unregister := tm.BindAgentTurnLoopInterrupt("conv-turn", func(note string) bool {
+		gotNote = note
+		return true
+	})
+	defer unregister()
+
+	ok, err := tm.CancelTask("conv-turn", multiagent.ErrInterruptContinue)
+	if err != nil || !ok {
+		t.Fatalf("CancelTask: ok=%v err=%v", ok, err)
+	}
+	if gotNote != "focus ssh" {
+		t.Fatalf("turn loop note = %q, want focus ssh", gotNote)
+	}
+	if cause := context.Cause(ctx); cause != nil {
+		t.Fatalf("context should not be cancelled when turn loop accepted interrupt, got %v", cause)
+	}
+	if note := tm.TakeInterruptContinueNote("conv-turn"); note != "" {
+		t.Fatalf("interrupt note should be consumed after turn loop push, got %q", note)
+	}
+}
+
+func TestCancelTaskFallsBackWhenTurnLoopInterruptRejects(t *testing.T) {
+	tm := NewAgentTaskManager()
+	var order []string
+
+	_, cancel := context.WithCancelCause(context.Background())
+	if _, err := tm.StartTask("conv-turn-fallback", "hello", func(err error) {
+		order = append(order, "context")
+		cancel(err)
+	}); err != nil {
+		t.Fatalf("StartTask: %v", err)
+	}
+	tm.SetInterruptContinueNote("conv-turn-fallback", "fallback note")
+	unregisterTurn := tm.BindAgentTurnLoopInterrupt("conv-turn-fallback", func(note string) bool {
+		order = append(order, "turn")
+		if note != "fallback note" {
+			t.Fatalf("turn loop note = %q, want fallback note", note)
+		}
+		return false
+	})
+	defer unregisterTurn()
+	unregisterRuntime := tm.BindAgentRuntimeCancel("conv-turn-fallback", func(err error) bool {
+		order = append(order, "runtime")
+		return false
+	})
+	defer unregisterRuntime()
+
+	ok, err := tm.CancelTask("conv-turn-fallback", multiagent.ErrInterruptContinue)
+	if err != nil || !ok {
+		t.Fatalf("CancelTask: ok=%v err=%v", ok, err)
+	}
+	want := []string{"turn", "runtime", "context"}
+	if len(order) != len(want) {
+		t.Fatalf("order length got %d want %d: %#v", len(order), len(want), order)
+	}
+	for i := range want {
+		if order[i] != want[i] {
+			t.Fatalf("order[%d] got %q want %q; full=%#v", i, order[i], want[i], order)
+		}
+	}
+	if note := tm.TakeInterruptContinueNote("conv-turn-fallback"); note != "fallback note" {
+		t.Fatalf("interrupt note should remain for fallback rerun, got %q", note)
+	}
+}
+
+func TestCancelTaskDefaultCauseIsTaskCancelled(t *testing.T) {
+	tm := NewAgentTaskManager()
+	var gotCause error
+	tm.SetToolCanceler(func(conversationID string) {
+		if conversationID == "conv-2" {
+			gotCause = ErrTaskCancelled
+		}
+	})
+
+	ctx, cancel := context.WithCancelCause(context.Background())
+	if _, err := tm.StartTask("conv-2", "hello", cancel); err != nil {
+		t.Fatalf("StartTask: %v", err)
+	}
+
+	if _, err := tm.CancelTask("conv-2", nil); err != nil {
+		t.Fatalf("CancelTask: %v", err)
+	}
+	if !errors.Is(context.Cause(ctx), ErrTaskCancelled) {
+		t.Fatalf("expected ErrTaskCancelled cause, got %v", context.Cause(ctx))
+	}
+	if gotCause != ErrTaskCancelled {
+		t.Fatalf("expected tool canceler path for default cancel cause")
+	}
+}
+
+func TestFinishTaskInvokesToolCancelerOnSessionEnd(t *testing.T) {
+	tm := NewAgentTaskManager()
+	calls := 0
+	tm.SetToolCanceler(func(conversationID string) {
+		if conversationID == "conv-3" {
+			calls++
+		}
+	})
+
+	_, cancel := context.WithCancelCause(context.Background())
+	if _, err := tm.StartTask("conv-3", "hello", cancel); err != nil {
+		t.Fatalf("StartTask: %v", err)
+	}
+
+	tm.FinishTask("conv-3", "completed")
+	if calls != 1 {
+		t.Fatalf("expected one tool cleanup on FinishTask, got %d", calls)
+	}
+}

internal/handler/terminal.go

@@ -0,0 +1,257 @@
+package handler
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+const (
+	terminalMaxCommandLen = 4096
+	terminalMaxOutputLen  = 256 * 1024 // 256KB
+	terminalTimeout       = 30 * time.Minute
+)
+
+// TerminalHandler 处理系统设置中的终端命令执行
+type TerminalHandler struct {
+	logger *zap.Logger
+}
+
+// maskTerminalCommand 对可能包含敏感信息的终端命令做脱敏，避免在日志中直接记录密码等内容
+func maskTerminalCommand(cmd string) string {
+	trimmed := strings.TrimSpace(cmd)
+	lower := strings.ToLower(trimmed)
+	if strings.Contains(lower, "sudo") || strings.Contains(lower, "password") {
+		return "[masked sensitive terminal command]"
+	}
+	if len(trimmed) > 256 {
+		return trimmed[:256] + "..."
+	}
+	return trimmed
+}
+
+// NewTerminalHandler 创建终端处理器
+func NewTerminalHandler(logger *zap.Logger) *TerminalHandler {
+	return &TerminalHandler{logger: logger}
+}
+
+// RunCommandRequest 执行命令请求
+type RunCommandRequest struct {
+	Command string `json:"command"`
+	Shell   string `json:"shell,omitempty"`
+	Cwd     string `json:"cwd,omitempty"`
+}
+
+// RunCommandResponse 执行命令响应
+type RunCommandResponse struct {
+	Stdout   string `json:"stdout"`
+	Stderr   string `json:"stderr"`
+	ExitCode int    `json:"exit_code"`
+	Error    string `json:"error,omitempty"`
+}
+
+// RunCommand 执行终端命令（需登录）
+func (h *TerminalHandler) RunCommand(c *gin.Context) {
+	var req RunCommandRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "请求体无效，需要 command 字段"})
+		return
+	}
+
+	cmdStr := strings.TrimSpace(req.Command)
+	if cmdStr == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "command 不能为空"})
+		return
+	}
+	if len(cmdStr) > terminalMaxCommandLen {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "命令过长"})
+		return
+	}
+
+	shell := req.Shell
+	if shell == "" {
+		if runtime.GOOS == "windows" {
+			shell = "cmd"
+		} else {
+			shell = "sh"
+		}
+	}
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), terminalTimeout)
+	defer cancel()
+
+	var cmd *exec.Cmd
+	if runtime.GOOS == "windows" {
+		cmd = exec.CommandContext(ctx, "cmd", "/c", cmdStr)
+	} else {
+		cmd = exec.CommandContext(ctx, shell, "-c", cmdStr)
+		// 无 TTY 时设置 COLUMNS/TERM，使 ping 等工具的 usage 排版与真实终端一致
+		cmd.Env = append(os.Environ(), "COLUMNS=256", "LINES=40", "TERM=xterm-256color")
+	}
+
+	if req.Cwd != "" {
+		absCwd, err := filepath.Abs(req.Cwd)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "工作目录无效"})
+			return
+		}
+		cur, _ := os.Getwd()
+		curAbs, _ := filepath.Abs(cur)
+		rel, err := filepath.Rel(curAbs, absCwd)
+		if err != nil || strings.HasPrefix(rel, "..") || rel == ".." {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "工作目录必须在当前进程目录下"})
+			return
+		}
+		cmd.Dir = absCwd
+	}
+
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+
+	err := cmd.Run()
+	stdoutBytes := stdout.Bytes()
+	stderrBytes := stderr.Bytes()
+
+	// 限制输出长度，防止内存占用过大（复制后截断，避免修改原 buffer）
+	truncSuffix := []byte("\n...(输出已截断)\n")
+	if len(stdoutBytes) > terminalMaxOutputLen {
+		tmp := make([]byte, terminalMaxOutputLen+len(truncSuffix))
+		n := copy(tmp, stdoutBytes[:terminalMaxOutputLen])
+		copy(tmp[n:], truncSuffix)
+		stdoutBytes = tmp
+	}
+	if len(stderrBytes) > terminalMaxOutputLen {
+		tmp := make([]byte, terminalMaxOutputLen+len(truncSuffix))
+		n := copy(tmp, stderrBytes[:terminalMaxOutputLen])
+		copy(tmp[n:], truncSuffix)
+		stderrBytes = tmp
+	}
+
+	exitCode := 0
+	if err != nil {
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			exitCode = exitErr.ExitCode()
+		} else {
+			exitCode = -1
+		}
+		if ctx.Err() == context.DeadlineExceeded {
+			so := strings.ReplaceAll(string(stdoutBytes), "\r\n", "\n")
+			so = strings.ReplaceAll(so, "\r", "\n")
+			se := strings.ReplaceAll(string(stderrBytes), "\r\n", "\n")
+			se = strings.ReplaceAll(se, "\r", "\n")
+			resp := RunCommandResponse{
+				Stdout:   so,
+				Stderr:   se,
+				ExitCode: -1,
+				Error:    "命令执行超时（" + terminalTimeout.String() + "）",
+			}
+			c.JSON(http.StatusOK, resp)
+			return
+		}
+		h.logger.Debug("终端命令执行异常", zap.String("command", maskTerminalCommand(cmdStr)), zap.Error(err))
+	}
+
+	// 统一为 \n，避免前端因 \r 出现错位/对角线排版
+	stdoutStr := strings.ReplaceAll(string(stdoutBytes), "\r\n", "\n")
+	stdoutStr = strings.ReplaceAll(stdoutStr, "\r", "\n")
+	stderrStr := strings.ReplaceAll(string(stderrBytes), "\r\n", "\n")
+	stderrStr = strings.ReplaceAll(stderrStr, "\r", "\n")
+
+	resp := RunCommandResponse{
+		Stdout:   stdoutStr,
+		Stderr:   stderrStr,
+		ExitCode: exitCode,
+	}
+	if err != nil && exitCode != 0 {
+		resp.Error = err.Error()
+	}
+	c.JSON(http.StatusOK, resp)
+}
+
+// streamEvent SSE 事件
+type streamEvent struct {
+	T string `json:"t"` // "out" | "err" | "exit"
+	D string `json:"d,omitempty"`
+	C int    `json:"c"` // exit code（不用 omitempty，否则 0 不序列化导致前端显示 [exit undefined]）
+}
+
+// RunCommandStream 流式执行命令，输出实时推送到前端（SSE）
+func (h *TerminalHandler) RunCommandStream(c *gin.Context) {
+	var req RunCommandRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "请求体无效，需要 command 字段"})
+		return
+	}
+	cmdStr := strings.TrimSpace(req.Command)
+	if cmdStr == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "command 不能为空"})
+		return
+	}
+	if len(cmdStr) > terminalMaxCommandLen {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "命令过长"})
+		return
+	}
+	shell := req.Shell
+	if shell == "" {
+		if runtime.GOOS == "windows" {
+			shell = "cmd"
+		} else {
+			shell = "sh"
+		}
+	}
+	ctx, cancel := context.WithTimeout(c.Request.Context(), terminalTimeout)
+	defer cancel()
+
+	var cmd *exec.Cmd
+	if runtime.GOOS == "windows" {
+		cmd = exec.CommandContext(ctx, "cmd", "/c", cmdStr)
+	} else {
+		cmd = exec.CommandContext(ctx, shell, "-c", cmdStr)
+		cmd.Env = append(os.Environ(), "COLUMNS=256", "LINES=40", "TERM=xterm-256color")
+	}
+	if req.Cwd != "" {
+		absCwd, err := filepath.Abs(req.Cwd)
+		if err != nil {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "工作目录无效"})
+			return
+		}
+		cur, _ := os.Getwd()
+		curAbs, _ := filepath.Abs(cur)
+		rel, err := filepath.Rel(curAbs, absCwd)
+		if err != nil || strings.HasPrefix(rel, "..") || rel == ".." {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "工作目录必须在当前进程目录下"})
+			return
+		}
+		cmd.Dir = absCwd
+	}
+
+	c.Header("Content-Type", "text/event-stream")
+	c.Header("Cache-Control", "no-cache")
+	c.Header("Connection", "keep-alive")
+	c.Header("X-Accel-Buffering", "no")
+	c.Writer.WriteHeader(http.StatusOK)
+	flusher, ok := c.Writer.(http.Flusher)
+	if !ok {
+		cancel()
+		return
+	}
+
+	sendEvent := func(ev streamEvent) {
+		body, _ := json.Marshal(ev)
+		c.SSEvent("", string(body))
+		flusher.Flush()
+	}
+
+	_ = runCommandStreamImpl(cmd, sendEvent, ctx)
+}

internal/handler/terminal_stream_unix.go

@@ -0,0 +1,47 @@
+//go:build !windows
+
+package handler
+
+import (
+	"bufio"
+	"context"
+	"os/exec"
+	"strings"
+
+	"github.com/creack/pty"
+)
+
+const ptyCols = 256
+const ptyRows = 40
+
+// runCommandStreamImpl 在 Unix 下用 PTY 执行，使 ping 等命令按终端宽度排版（isatty 为真）
+func runCommandStreamImpl(cmd *exec.Cmd, sendEvent func(streamEvent), ctx context.Context) int {
+	ptmx, err := pty.StartWithSize(cmd, &pty.Winsize{Cols: ptyCols, Rows: ptyRows})
+	if err != nil {
+		sendEvent(streamEvent{T: "exit", C: -1})
+		return -1
+	}
+	defer ptmx.Close()
+
+	normalize := func(s string) string {
+		s = strings.ReplaceAll(s, "\r\n", "\n")
+		return strings.ReplaceAll(s, "\r", "\n")
+	}
+	sc := bufio.NewScanner(ptmx)
+	for sc.Scan() {
+		sendEvent(streamEvent{T: "out", D: normalize(sc.Text())})
+	}
+	exitCode := 0
+	if err := cmd.Wait(); err != nil {
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			exitCode = exitErr.ExitCode()
+		} else {
+			exitCode = -1
+		}
+	}
+	if ctx.Err() == context.DeadlineExceeded {
+		exitCode = -1
+	}
+	sendEvent(streamEvent{T: "exit", C: exitCode})
+	return exitCode
+}

internal/handler/terminal_stream_windows.go

@@ -0,0 +1,66 @@
+//go:build windows
+
+package handler
+
+import (
+	"bufio"
+	"context"
+	"os/exec"
+	"strings"
+	"sync"
+)
+
+// runCommandStreamImpl 在 Windows 下用 stdout/stderr 管道执行
+func runCommandStreamImpl(cmd *exec.Cmd, sendEvent func(streamEvent), ctx context.Context) int {
+	stdoutPipe, err := cmd.StdoutPipe()
+	if err != nil {
+		sendEvent(streamEvent{T: "exit", C: -1})
+		return -1
+	}
+	stderrPipe, err := cmd.StderrPipe()
+	if err != nil {
+		sendEvent(streamEvent{T: "exit", C: -1})
+		return -1
+	}
+	if err := cmd.Start(); err != nil {
+		sendEvent(streamEvent{T: "exit", C: -1})
+		return -1
+	}
+
+	normalize := func(s string) string {
+		s = strings.ReplaceAll(s, "\r\n", "\n")
+		return strings.ReplaceAll(s, "\r", "\n")
+	}
+
+	var wg sync.WaitGroup
+	wg.Add(2)
+	go func() {
+		defer wg.Done()
+		sc := bufio.NewScanner(stdoutPipe)
+		for sc.Scan() {
+			sendEvent(streamEvent{T: "out", D: normalize(sc.Text())})
+		}
+	}()
+	go func() {
+		defer wg.Done()
+		sc := bufio.NewScanner(stderrPipe)
+		for sc.Scan() {
+			sendEvent(streamEvent{T: "err", D: normalize(sc.Text())})
+		}
+	}()
+
+	wg.Wait()
+	exitCode := 0
+	if err := cmd.Wait(); err != nil {
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			exitCode = exitErr.ExitCode()
+		} else {
+			exitCode = -1
+		}
+	}
+	if ctx.Err() == context.DeadlineExceeded {
+		exitCode = -1
+	}
+	sendEvent(streamEvent{T: "exit", C: exitCode})
+	return exitCode
+}

internal/handler/terminal_ws_unix.go

@@ -0,0 +1,111 @@
+//go:build !windows
+
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"os"
+	"os/exec"
+	"time"
+
+	"github.com/creack/pty"
+	"github.com/gin-gonic/gin"
+	"github.com/gorilla/websocket"
+)
+
+// terminalResize is sent by the frontend when the xterm.js terminal is resized.
+type terminalResize struct {
+	Type string `json:"type"`
+	Cols uint16 `json:"cols"`
+	Rows uint16 `json:"rows"`
+}
+
+// wsUpgrader 仅用于系统设置中的终端 WebSocket，会复用已有的登录保护（JWT 中间件在上层路由组）
+var wsUpgrader = websocket.Upgrader{
+	CheckOrigin: func(r *http.Request) bool {
+		// 由于已在 Gin 路由层做了认证，这里放宽 Origin，方便在同一域名下通过 HTTPS/WSS 访问
+		return true
+	},
+}
+
+// RunCommandWS 提供真正交互式 Shell：基于 WebSocket + PTY 的长会话
+// 前端建立 WebSocket 连接后，所有键盘输入都会透传到 Shell，Shell 的输出也会实时写回前端。
+func (h *TerminalHandler) RunCommandWS(c *gin.Context) {
+	conn, err := wsUpgrader.Upgrade(c.Writer, c.Request, nil)
+	if err != nil {
+		return
+	}
+	defer conn.Close()
+
+	// 启动交互式 Shell，这里优先使用 bash，找不到则退回 sh
+	shell := "bash"
+	if _, err := exec.LookPath(shell); err != nil {
+		shell = "sh"
+	}
+	cmd := exec.Command(shell)
+	cmd.Env = append(os.Environ(),
+		"COLUMNS=80",
+		"LINES=24",
+		"TERM=xterm-256color",
+	)
+
+	// Use 80x24 as a safe default; the frontend will send the actual size immediately after connecting.
+	ptmx, err := pty.StartWithSize(cmd, &pty.Winsize{Cols: 80, Rows: 24})
+	if err != nil {
+		return
+	}
+	defer ptmx.Close()
+
+	// Shell -> WebSocket：将 PTY 输出实时发给前端
+	doneChan := make(chan struct{})
+	go func() {
+		buf := make([]byte, 4096)
+		for {
+			n, err := ptmx.Read(buf)
+			if n > 0 {
+				_ = conn.WriteMessage(websocket.BinaryMessage, buf[:n])
+			}
+			if err != nil {
+				break
+			}
+		}
+		close(doneChan)
+	}()
+
+	// WebSocket -> Shell：将前端输入写入 PTY（包括 sudo 密码、Ctrl+C 等）
+	conn.SetReadLimit(64 * 1024)
+	_ = conn.SetReadDeadline(time.Now().Add(terminalTimeout))
+	conn.SetPongHandler(func(string) error {
+		_ = conn.SetReadDeadline(time.Now().Add(terminalTimeout))
+		return nil
+	})
+
+	for {
+		msgType, data, err := conn.ReadMessage()
+		if err != nil {
+			_ = cmd.Process.Kill()
+			break
+		}
+		if msgType != websocket.TextMessage && msgType != websocket.BinaryMessage {
+			continue
+		}
+		if len(data) == 0 {
+			continue
+		}
+		// Check if this is a resize message (JSON with type:"resize")
+		if msgType == websocket.TextMessage && len(data) > 0 && data[0] == '{' {
+			var resize terminalResize
+			if json.Unmarshal(data, &resize) == nil && resize.Type == "resize" && resize.Cols > 0 && resize.Rows > 0 {
+				_ = pty.Setsize(ptmx, &pty.Winsize{Cols: resize.Cols, Rows: resize.Rows})
+				continue
+			}
+		}
+		if _, err := ptmx.Write(data); err != nil {
+			_ = cmd.Process.Kill()
+			break
+		}
+	}
+
+	<-doneChan
+}

internal/handler/terminal_ws_windows.go

@@ -0,0 +1,16 @@
+//go:build windows
+
+package handler
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// RunCommandWS 交互式 PTY 终端依赖 Unix PTY（见 terminal_ws_unix.go）；Windows 暂不支持。
+func (h *TerminalHandler) RunCommandWS(c *gin.Context) {
+	c.JSON(http.StatusNotImplemented, gin.H{
+		"error": "Interactive WebSocket terminal is not supported on Windows; use POST /terminal/run or /terminal/run/stream instead.",
+	})
+}

internal/handler/vulnerability.go

@@ -0,0 +1,602 @@
+package handler
+
+import (
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+// VulnerabilityHandler 漏洞处理器
+type VulnerabilityHandler struct {
+	db     *database.DB
+	logger *zap.Logger
+	audit  *audit.Service
+}
+
+// SetAudit wires platform audit logging.
+func (h *VulnerabilityHandler) SetAudit(s *audit.Service) {
+	h.audit = s
+}
+
+// NewVulnerabilityHandler 创建新的漏洞处理器
+func NewVulnerabilityHandler(db *database.DB, logger *zap.Logger) *VulnerabilityHandler {
+	return &VulnerabilityHandler{
+		db:     db,
+		logger: logger,
+	}
+}
+
+// CreateVulnerabilityRequest 创建漏洞请求
+type CreateVulnerabilityRequest struct {
+	ConversationID  string `json:"conversation_id" binding:"required"`
+	ProjectID       string `json:"project_id"`
+	ConversationTag string `json:"conversation_tag"`
+	TaskTag         string `json:"task_tag"`
+	Title           string `json:"title" binding:"required"`
+	Description     string `json:"description"`
+	Severity        string `json:"severity" binding:"required"`
+	Status          string `json:"status"`
+	Type            string `json:"type"`
+	Target          string `json:"target"`
+	Preconditions   string `json:"preconditions"`
+	ReproSteps      string `json:"reproduction_steps"`
+	Evidence        string `json:"evidence"`
+	Impact          string `json:"impact"`
+	Recommendation  string `json:"recommendation"`
+	RetestNotes     string `json:"retest_notes"`
+}
+
+// CreateVulnerability 创建漏洞
+func (h *VulnerabilityHandler) CreateVulnerability(c *gin.Context) {
+	var req CreateVulnerabilityRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if session, ok := security.CurrentSession(c); ok && session.Scope != database.RBACScopeAll {
+		if strings.TrimSpace(req.ConversationID) != "" && !h.db.UserCanAccessResource(session.UserID, session.Scope, "conversation", strings.TrimSpace(req.ConversationID)) {
+			c.JSON(http.StatusForbidden, gin.H{"error": "无权在该对话下创建漏洞"})
+			return
+		}
+		if strings.TrimSpace(req.ProjectID) != "" && !h.db.UserCanAccessResource(session.UserID, session.Scope, "project", strings.TrimSpace(req.ProjectID)) {
+			c.JSON(http.StatusForbidden, gin.H{"error": "无权在该项目下创建漏洞"})
+			return
+		}
+	}
+
+	vuln := &database.Vulnerability{
+		ConversationID:  req.ConversationID,
+		ProjectID:       strings.TrimSpace(req.ProjectID),
+		ConversationTag: req.ConversationTag,
+		TaskTag:         req.TaskTag,
+		Title:           req.Title,
+		Description:     req.Description,
+		Severity:        req.Severity,
+		Status:          req.Status,
+		Type:            req.Type,
+		Target:          req.Target,
+		Preconditions:   req.Preconditions,
+		ReproSteps:      req.ReproSteps,
+		Evidence:        req.Evidence,
+		Impact:          req.Impact,
+		Recommendation:  req.Recommendation,
+		RetestNotes:     req.RetestNotes,
+	}
+
+	created, err := h.db.CreateVulnerability(vuln)
+	if err != nil {
+		h.logger.Error("创建漏洞失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if session, ok := security.CurrentSession(c); ok {
+		_ = h.db.SetResourceOwner("vulnerability", created.ID, session.UserID)
+		_ = h.db.AssignResourceToUser(session.UserID, "vulnerability", created.ID)
+	}
+	h.db.NotifyVulnerabilityCreated(created)
+
+	if h.audit != nil {
+		h.audit.RecordOK(c, "vulnerability", "create", "创建漏洞记录", "vulnerability", created.ID, map[string]interface{}{
+			"severity": created.Severity, "title": created.Title,
+		})
+	}
+	c.JSON(http.StatusOK, created)
+}
+
+// GetVulnerability 获取漏洞
+func (h *VulnerabilityHandler) GetVulnerability(c *gin.Context) {
+	id := c.Param("id")
+
+	vuln, err := h.db.GetVulnerability(id)
+	if err != nil {
+		h.logger.Error("获取漏洞失败", zap.Error(err))
+		c.JSON(http.StatusNotFound, gin.H{"error": "漏洞不存在"})
+		return
+	}
+
+	c.JSON(http.StatusOK, vuln)
+}
+
+// ListVulnerabilitiesResponse 漏洞列表响应
+type ListVulnerabilitiesResponse struct {
+	Vulnerabilities []*database.Vulnerability `json:"vulnerabilities"`
+	Total           int                       `json:"total"`
+	Page            int                       `json:"page"`
+	PageSize        int                       `json:"page_size"`
+	TotalPages      int                       `json:"total_pages"`
+}
+
+func parseVulnerabilityListFilter(c *gin.Context) database.VulnerabilityListFilter {
+	q := strings.TrimSpace(c.Query("q"))
+	if q == "" {
+		q = strings.TrimSpace(c.Query("search"))
+	}
+	return database.VulnerabilityListFilter{
+		ProjectID:       c.Query("project_id"),
+		ID:              c.Query("id"),
+		Search:          q,
+		ConversationID:  c.Query("conversation_id"),
+		Severity:        c.Query("severity"),
+		Status:          c.Query("status"),
+		TaskID:          c.Query("task_id"),
+		ConversationTag: c.Query("conversation_tag"),
+		TaskTag:         c.Query("task_tag"),
+	}
+}
+
+// ListVulnerabilities 列出漏洞
+func (h *VulnerabilityHandler) ListVulnerabilities(c *gin.Context) {
+	limitStr := c.DefaultQuery("limit", "20")
+	offsetStr := c.DefaultQuery("offset", "0")
+	pageStr := c.Query("page")
+	filter := parseVulnerabilityListFilter(c)
+	access := vulnerabilityAccessFromContext(c)
+
+	limit, _ := strconv.Atoi(limitStr)
+	offset, _ := strconv.Atoi(offsetStr)
+	page := 1
+
+	// 如果提供了page参数，优先使用page计算offset
+	if pageStr != "" {
+		if p, err := strconv.Atoi(pageStr); err == nil && p > 0 {
+			page = p
+			offset = (page - 1) * limit
+		}
+	}
+
+	if limit <= 0 || limit > 100 {
+		limit = 20
+	}
+	if offset < 0 {
+		offset = 0
+	}
+
+	// 获取总数
+	total, err := h.db.CountVulnerabilitiesForAccess(filter, access)
+	if err != nil {
+		h.logger.Error("获取漏洞总数失败", zap.Error(err))
+		// 继续执行，使用0作为总数
+		total = 0
+	}
+
+	// 获取漏洞列表
+	vulnerabilities, err := h.db.ListVulnerabilitiesForAccess(limit, offset, filter, access)
+	if err != nil {
+		h.logger.Error("获取漏洞列表失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// 计算总页数
+	totalPages := (total + limit - 1) / limit
+	if totalPages == 0 {
+		totalPages = 1
+	}
+
+	// 如果使用offset计算page，需要重新计算
+	if pageStr == "" {
+		page = (offset / limit) + 1
+	}
+
+	response := ListVulnerabilitiesResponse{
+		Vulnerabilities: vulnerabilities,
+		Total:           total,
+		Page:            page,
+		PageSize:        limit,
+		TotalPages:      totalPages,
+	}
+
+	c.JSON(http.StatusOK, response)
+}
+
+// UpdateVulnerabilityRequest 更新漏洞请求
+type UpdateVulnerabilityRequest struct {
+	ProjectID       *string `json:"project_id"`
+	ConversationTag *string `json:"conversation_tag"`
+	TaskTag         *string `json:"task_tag"`
+	Title           *string `json:"title"`
+	Description     *string `json:"description"`
+	Severity        *string `json:"severity"`
+	Status          *string `json:"status"`
+	Type            *string `json:"type"`
+	Target          *string `json:"target"`
+	Preconditions   *string `json:"preconditions"`
+	ReproSteps      *string `json:"reproduction_steps"`
+	Evidence        *string `json:"evidence"`
+	Impact          *string `json:"impact"`
+	Recommendation  *string `json:"recommendation"`
+	RetestNotes     *string `json:"retest_notes"`
+}
+
+// UpdateVulnerability 更新漏洞
+func (h *VulnerabilityHandler) UpdateVulnerability(c *gin.Context) {
+	id := c.Param("id")
+
+	var req UpdateVulnerabilityRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	// 获取现有漏洞
+	existing, err := h.db.GetVulnerability(id)
+	if err != nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "漏洞不存在"})
+		return
+	}
+
+	// 更新字段
+	if req.ProjectID != nil {
+		targetProjectID := strings.TrimSpace(*req.ProjectID)
+		if targetProjectID != "" {
+			session, ok := security.CurrentSession(c)
+			if !ok || !h.db.UserCanAccessResource(session.UserID, session.Scope, "project", targetProjectID) {
+				c.JSON(http.StatusForbidden, gin.H{"error": "无权关联目标项目"})
+				return
+			}
+		}
+		existing.ProjectID = targetProjectID
+	}
+	if req.ConversationTag != nil {
+		existing.ConversationTag = *req.ConversationTag
+	}
+	if req.TaskTag != nil {
+		existing.TaskTag = *req.TaskTag
+	}
+	if req.Title != nil {
+		existing.Title = *req.Title
+	}
+	if req.Description != nil {
+		existing.Description = *req.Description
+	}
+	if req.Severity != nil {
+		existing.Severity = *req.Severity
+	}
+	if req.Status != nil {
+		existing.Status = *req.Status
+	}
+	if req.Type != nil {
+		existing.Type = *req.Type
+	}
+	if req.Target != nil {
+		existing.Target = *req.Target
+	}
+	if req.Preconditions != nil {
+		existing.Preconditions = *req.Preconditions
+	}
+	if req.ReproSteps != nil {
+		existing.ReproSteps = *req.ReproSteps
+	}
+	if req.Evidence != nil {
+		existing.Evidence = *req.Evidence
+	}
+	if req.Impact != nil {
+		existing.Impact = *req.Impact
+	}
+	if req.Recommendation != nil {
+		existing.Recommendation = *req.Recommendation
+	}
+	if req.RetestNotes != nil {
+		existing.RetestNotes = *req.RetestNotes
+	}
+
+	if err := h.db.UpdateVulnerability(id, existing); err != nil {
+		h.logger.Error("更新漏洞失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	// 返回更新后的漏洞
+	updated, err := h.db.GetVulnerability(id)
+	if err != nil {
+		h.logger.Error("获取更新后的漏洞失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	if h.audit != nil {
+		h.audit.RecordOK(c, "vulnerability", "update", "更新漏洞记录", "vulnerability", id, map[string]interface{}{
+			"severity": updated.Severity, "status": updated.Status, "project_id": updated.ProjectID,
+		})
+	}
+	c.JSON(http.StatusOK, updated)
+}
+
+// DeleteVulnerability 删除漏洞
+func (h *VulnerabilityHandler) DeleteVulnerability(c *gin.Context) {
+	id := c.Param("id")
+
+	if err := h.db.DeleteVulnerability(id); err != nil {
+		h.logger.Error("删除漏洞失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	if h.audit != nil {
+		h.audit.Record(c, audit.Entry{
+			Category:     "vulnerability",
+			Action:       "delete",
+			Result:       "success",
+			ResourceType: "vulnerability",
+			ResourceID:   id,
+			Message:      "删除漏洞记录",
+		})
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "删除成功"})
+}
+
+// BatchDeleteVulnerabilities 按当前筛选条件批量删除漏洞
+func (h *VulnerabilityHandler) BatchDeleteVulnerabilities(c *gin.Context) {
+	filter := parseVulnerabilityListFilter(c)
+	access := vulnerabilityAccessFromContext(c)
+
+	total, err := h.db.CountVulnerabilitiesForAccess(filter, access)
+	if err != nil {
+		h.logger.Error("统计待删除漏洞失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if total == 0 {
+		c.JSON(http.StatusOK, gin.H{"message": "当前筛选条件下没有可删除的漏洞", "deleted": 0})
+		return
+	}
+
+	deleted, err := h.db.DeleteVulnerabilitiesByFilterForAccess(filter, access)
+	if err != nil {
+		h.logger.Error("批量删除漏洞失败", zap.Error(err), zap.Int("count", total))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	if h.audit != nil {
+		h.audit.RecordOK(c, "vulnerability", "delete_batch", "批量删除漏洞记录", "vulnerability", "", map[string]interface{}{
+			"deleted": deleted,
+			"filter":  filter,
+		})
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "批量删除成功", "deleted": deleted})
+}
+
+// GetVulnerabilityStats 获取漏洞统计
+func (h *VulnerabilityHandler) GetVulnerabilityStats(c *gin.Context) {
+	filter := parseVulnerabilityListFilter(c)
+	access := vulnerabilityAccessFromContext(c)
+
+	stats, err := h.db.GetVulnerabilityStatsForAccess(filter, access)
+	if err != nil {
+		h.logger.Error("获取漏洞统计失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, stats)
+}
+
+// GetVulnerabilityFilterOptions 获取漏洞筛选建议项
+func (h *VulnerabilityHandler) GetVulnerabilityFilterOptions(c *gin.Context) {
+	options, err := h.db.GetVulnerabilityFilterOptionsForAccess(vulnerabilityAccessFromContext(c))
+	if err != nil {
+		h.logger.Error("获取漏洞筛选建议失败", zap.Error(err))
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, options)
+}
+
+// ExportVulnerabilities 导出漏洞（支持按对话/任务分组，汇总或拆分）
+func (h *VulnerabilityHandler) ExportVulnerabilities(c *gin.Context) {
+	groupBy := c.DefaultQuery("group_by", "conversation")
+	mode := c.DefaultQuery("mode", "summary")
+	if groupBy != "conversation" && groupBy != "task" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "group_by 仅支持 conversation 或 task"})
+		return
+	}
+	if mode != "summary" && mode != "split" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "mode 仅支持 summary 或 split"})
+		return
+	}
+
+	filter := parseVulnerabilityListFilter(c)
+	access := vulnerabilityAccessFromContext(c)
+
+	total, err := h.db.CountVulnerabilitiesForAccess(filter, access)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if total == 0 {
+		c.JSON(http.StatusOK, gin.H{"mode": mode, "group_by": groupBy, "total": 0, "files": []any{}})
+		return
+	}
+
+	items, err := h.db.ListVulnerabilitiesForAccess(total, 0, filter, access)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	type exportFile struct {
+		FileName string `json:"filename"`
+		Content  string `json:"content"`
+	}
+	grouped := map[string][]*database.Vulnerability{}
+	for _, v := range items {
+		key := v.ConversationID
+		if groupBy == "conversation" {
+			if strings.TrimSpace(v.ConversationTag) != "" {
+				key = strings.TrimSpace(v.ConversationTag)
+			}
+		} else {
+			key = firstNonEmpty(v.TaskTag, v.TaskID, v.TaskQueueID, "unassigned-task")
+		}
+		grouped[key] = append(grouped[key], v)
+	}
+
+	files := make([]exportFile, 0)
+	nowStr := time.Now().Format("20060102-150405")
+	if mode == "summary" {
+		var b strings.Builder
+		b.WriteString("# 漏洞批量导出报告\n\n")
+		b.WriteString(fmt.Sprintf("- 导出时间: %s\n", time.Now().Format("2006-01-02 15:04:05")))
+		b.WriteString(fmt.Sprintf("- 分组维度: %s\n", groupBy))
+		b.WriteString(fmt.Sprintf("- 漏洞总数: %d\n", len(items)))
+		b.WriteString(fmt.Sprintf("- 分组数: %d\n\n", len(grouped)))
+		for group, list := range grouped {
+			b.WriteString(fmt.Sprintf("## %s (%d)\n\n", group, len(list)))
+			for _, v := range list {
+				appendVulnerabilityMarkdown(&b, v, "###")
+			}
+		}
+		files = append(files, exportFile{
+			FileName: fmt.Sprintf("vulnerability-report-%s-%s.md", groupBy, nowStr),
+			Content:  b.String(),
+		})
+	} else {
+		for group, list := range grouped {
+			var b strings.Builder
+			b.WriteString(fmt.Sprintf("# 漏洞报告 - %s\n\n", group))
+			b.WriteString(fmt.Sprintf("- 导出时间: %s\n", time.Now().Format("2006-01-02 15:04:05")))
+			b.WriteString(fmt.Sprintf("- 漏洞数量: %d\n\n", len(list)))
+			for _, v := range list {
+				appendVulnerabilityMarkdown(&b, v, "##")
+			}
+			files = append(files, exportFile{
+				FileName: fmt.Sprintf("vulnerability-%s-%s.md", sanitizeExportName(group), nowStr),
+				Content:  b.String(),
+			})
+		}
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"mode":     mode,
+		"group_by": groupBy,
+		"total":    len(items),
+		"files":    files,
+	})
+}
+
+func vulnerabilityAccessFromContext(c *gin.Context) database.RBACListAccess {
+	session, ok := security.CurrentSession(c)
+	if !ok {
+		return database.RBACListAccess{}
+	}
+	return database.RBACListAccess{UserID: session.UserID, Scope: session.Scope}
+}
+
+// appendVulnerabilityMarkdown 单条漏洞的 Markdown 片段（与单文件下载字段对齐，缺省字段不写）
+func appendVulnerabilityMarkdown(b *strings.Builder, v *database.Vulnerability, titleHeading string) {
+	b.WriteString(fmt.Sprintf("%s %s\n\n", titleHeading, v.Title))
+	b.WriteString(fmt.Sprintf("- 漏洞ID: `%s`\n", v.ID))
+	b.WriteString(fmt.Sprintf("- 严重程度: %s\n", v.Severity))
+	b.WriteString(fmt.Sprintf("- 状态: %s\n", v.Status))
+	if v.Type != "" {
+		b.WriteString(fmt.Sprintf("- 类型: %s\n", v.Type))
+	}
+	if v.Target != "" {
+		b.WriteString(fmt.Sprintf("- 目标: %s\n", v.Target))
+	}
+	b.WriteString(fmt.Sprintf("- 对话ID: `%s`\n", v.ConversationID))
+	if v.ConversationTag != "" {
+		b.WriteString(fmt.Sprintf("- 对话标签: %s\n", v.ConversationTag))
+	}
+	if v.TaskTag != "" {
+		b.WriteString(fmt.Sprintf("- 任务标签: %s\n", v.TaskTag))
+	}
+	if v.TaskID != "" {
+		b.WriteString(fmt.Sprintf("- 任务ID: `%s`\n", v.TaskID))
+	}
+	if v.TaskQueueID != "" {
+		b.WriteString(fmt.Sprintf("- 任务队列ID: `%s`\n", v.TaskQueueID))
+	}
+	if !v.CreatedAt.IsZero() {
+		b.WriteString(fmt.Sprintf("- 创建时间: %s\n", v.CreatedAt.Format("2006-01-02 15:04:05")))
+	}
+	if !v.UpdatedAt.IsZero() {
+		b.WriteString(fmt.Sprintf("- 更新时间: %s\n", v.UpdatedAt.Format("2006-01-02 15:04:05")))
+	}
+	if v.Description != "" {
+		b.WriteString("\n#### 描述\n\n")
+		b.WriteString(v.Description)
+		b.WriteString("\n")
+	}
+	if v.Preconditions != "" {
+		b.WriteString("\n#### 前置条件\n\n")
+		b.WriteString(v.Preconditions)
+		b.WriteString("\n")
+	}
+	if v.ReproSteps != "" {
+		b.WriteString("\n#### 复现步骤\n\n")
+		b.WriteString(v.ReproSteps)
+		b.WriteString("\n")
+	}
+	if v.Evidence != "" {
+		b.WriteString("\n#### 证据 / POC\n\n```\n")
+		b.WriteString(v.Evidence)
+		b.WriteString("\n```\n")
+	}
+	if v.Impact != "" {
+		b.WriteString("\n#### 影响\n\n")
+		b.WriteString(v.Impact)
+		b.WriteString("\n")
+	}
+	if v.Recommendation != "" {
+		b.WriteString("\n#### 修复建议\n\n")
+		b.WriteString(v.Recommendation)
+		b.WriteString("\n")
+	}
+	if v.RetestNotes != "" {
+		b.WriteString("\n#### 复测方式\n\n")
+		b.WriteString(v.RetestNotes)
+		b.WriteString("\n")
+	}
+	b.WriteString("\n")
+}
+
+func firstNonEmpty(values ...string) string {
+	for _, v := range values {
+		trimmed := strings.TrimSpace(v)
+		if trimmed != "" {
+			return trimmed
+		}
+	}
+	return ""
+}
+
+func sanitizeExportName(raw string) string {
+	name := strings.TrimSpace(raw)
+	if name == "" {
+		return "unknown"
+	}
+	replacer := strings.NewReplacer("/", "-", "\\", "-", ":", "-", "*", "-", "?", "-", "\"", "-", "<", "-", ">", "-", "|", "-")
+	return replacer.Replace(name)
+}

internal/handler/vulnerability_alert.go

@@ -0,0 +1,227 @@
+package handler
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/robot"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+type updateVulnerabilityAlertRequest struct {
+	Enabled     bool   `json:"enabled"`
+	MinSeverity string `json:"min_severity"`
+}
+
+func (h *VulnerabilityHandler) GetMyAlertSubscription(c *gin.Context) {
+	session, ok := security.CurrentSession(c)
+	if !ok {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
+		return
+	}
+	sub, err := h.db.GetVulnerabilityAlertSubscription(session.UserID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	bindings, _ := h.db.ListRobotUserBindings(session.UserID)
+	deliveryReady := false
+	for _, binding := range bindings {
+		if binding.Enabled && robot.SupportsProactive(binding.Platform) {
+			deliveryReady = true
+			break
+		}
+	}
+	c.JSON(http.StatusOK, gin.H{"subscription": sub, "bindings": bindings, "delivery_ready": deliveryReady})
+}
+
+func (h *VulnerabilityHandler) UpdateMyAlertSubscription(c *gin.Context) {
+	session, ok := security.CurrentSession(c)
+	if !ok {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
+		return
+	}
+	var req updateVulnerabilityAlertRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	sub, err := h.db.UpsertVulnerabilityAlertSubscription(session.UserID, req.Enabled, req.MinSeverity)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "vulnerability", "alert_subscription_update", "更新漏洞提醒订阅", "user", session.UserID, map[string]interface{}{
+			"enabled": sub.Enabled, "min_severity": sub.MinSeverity,
+		})
+	}
+	c.JSON(http.StatusOK, sub)
+}
+
+func vulnerabilityAlertSeverityLabel(value string) string {
+	switch value {
+	case "critical":
+		return "严重"
+	case "high":
+		return "高危"
+	case "medium":
+		return "中危"
+	case "low":
+		return "低危"
+	default:
+		return "信息"
+	}
+}
+
+func formatVulnerabilityRobotAlert(v *database.Vulnerability) string {
+	return fmt.Sprintf("🚨 新漏洞提醒\n\n标题：%s\n严重程度：%s（%s）\n目标：%s\n影响：%s\n修复建议：%s\n漏洞 ID：%s\n\n请核实目标版本与实际暴露情况。",
+		strings.TrimSpace(v.Title), vulnerabilityAlertSeverityLabel(v.Severity), v.Severity,
+		fallbackAlertText(v.Target), fallbackAlertText(v.Impact), fallbackAlertText(v.Recommendation), v.ID)
+}
+
+func fallbackAlertText(value string) string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return "未填写"
+	}
+	if len([]rune(value)) > 300 {
+		return string([]rune(value)[:300]) + "…"
+	}
+	return value
+}
+
+// NotifyNewVulnerability pushes an alert to every eligible bound robot identity.
+// A failure on one platform never blocks vulnerability creation or other recipients.
+func (h *RobotHandler) NotifyNewVulnerability(v *database.Vulnerability) {
+	if h == nil || h.db == nil || v == nil {
+		return
+	}
+	recipients, err := h.db.ListVulnerabilityAlertRecipients(v)
+	if err != nil {
+		h.logger.Warn("查询漏洞提醒接收人失败", zap.String("vulnerability_id", v.ID), zap.Error(err))
+		return
+	}
+	eligible := recipients[:0]
+	for _, recipient := range recipients {
+		if robot.SupportsProactive(recipient.Platform) {
+			eligible = append(eligible, recipient)
+		}
+	}
+	if err := h.db.EnqueueVulnerabilityAlertDeliveries(v.ID, eligible); err != nil {
+		h.logger.Warn("写入漏洞提醒投递队列失败", zap.String("vulnerability_id", v.ID), zap.Error(err))
+		return
+	}
+	select {
+	case h.alertWake <- struct{}{}:
+	default:
+	}
+}
+
+// RunVulnerabilityAlertWorker drains the durable outbox. Failed sends use
+// exponential backoff and remain retryable across application restarts.
+func (h *RobotHandler) RunVulnerabilityAlertWorker(ctx context.Context) {
+	if h == nil || h.db == nil {
+		return
+	}
+	ticker := time.NewTicker(30 * time.Second)
+	defer ticker.Stop()
+	for {
+		h.processVulnerabilityAlertDeliveries(ctx)
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+		case <-h.alertWake:
+		}
+	}
+}
+
+func (h *RobotHandler) processVulnerabilityAlertDeliveries(ctx context.Context) {
+	deliveries, err := h.db.ListDueVulnerabilityAlertDeliveries(50)
+	if err != nil {
+		h.logger.Warn("读取漏洞提醒投递队列失败", zap.Error(err))
+		return
+	}
+	for _, delivery := range deliveries {
+		sendCtx, cancel := context.WithTimeout(ctx, 15*time.Second)
+		err := robot.SendProactive(sendCtx, h.config.Robots, delivery.Platform, delivery.ExternalUserID, formatVulnerabilityRobotAlert(delivery.Vulnerability))
+		cancel()
+		if err != nil {
+			attempts := delivery.Attempts + 1
+			_ = h.db.MarkVulnerabilityAlertDeliveryFailed(delivery.ID, attempts, err)
+			h.logger.Warn("发送漏洞机器人提醒失败", zap.String("platform", delivery.Platform), zap.String("user_id", delivery.UserID), zap.String("vulnerability_id", delivery.Vulnerability.ID), zap.Int("attempt", attempts), zap.Error(err))
+			continue
+		}
+		_ = h.db.MarkVulnerabilityAlertDeliverySent(delivery.ID)
+		h.logger.Info("漏洞机器人提醒已发送", zap.String("platform", delivery.Platform), zap.String("user_id", delivery.UserID), zap.String("vulnerability_id", delivery.Vulnerability.ID))
+	}
+}
+
+func (h *RobotHandler) cmdVulnerabilityAlerts(platform, externalUserID, arg string) string {
+	access, err := h.resolveRobotAccess(platform, externalUserID)
+	if err != nil {
+		return h.robotAccessDeniedMessage(platform)
+	}
+	arg = strings.ToLower(strings.TrimSpace(arg))
+	if arg == "" || arg == "status" || arg == "状态" {
+		sub, err := h.db.GetVulnerabilityAlertSubscription(access.User.ID)
+		if err != nil {
+			return "读取漏洞提醒设置失败，请稍后重试。"
+		}
+		state := "已关闭"
+		if sub.Enabled {
+			state = "已开启"
+		}
+		return fmt.Sprintf("漏洞提醒%s；最低提醒级别：%s（%s）。\n可在 Web「漏洞管理」页面同步修改。", state, vulnerabilityAlertSeverityLabel(sub.MinSeverity), sub.MinSeverity)
+	}
+	enabled, severity := true, ""
+	switch arg {
+	case "开启", "开", "on", "enable":
+		severity = "high"
+	case "关闭", "关", "off", "disable":
+		enabled, severity = false, "high"
+	case "仅严重", "严重", "critical":
+		severity = "critical"
+	case "高危以上", "高危", "high":
+		severity = "high"
+	case "中危以上", "中危", "medium":
+		severity = "medium"
+	case "低危以上", "低危", "low":
+		severity = "low"
+	case "全部", "all", "info":
+		severity = "info"
+	default:
+		return "用法：漏洞提醒 开启｜关闭｜仅严重｜高危以上｜中危以上"
+	}
+	current, _ := h.db.GetVulnerabilityAlertSubscription(access.User.ID)
+	if (arg == "开启" || arg == "开" || arg == "on" || arg == "enable" || !enabled) && current != nil {
+		severity = current.MinSeverity
+	}
+	sub, err := h.db.UpsertVulnerabilityAlertSubscription(access.User.ID, enabled, severity)
+	if err != nil {
+		return "更新漏洞提醒失败，请稍后重试。"
+	}
+	if !sub.Enabled {
+		return "已关闭漏洞提醒。Web 端设置已同步。"
+	}
+	bindings, _ := h.db.ListRobotUserBindings(access.User.ID)
+	deliveryReady := false
+	for _, binding := range bindings {
+		if binding.Enabled && robot.SupportsProactive(binding.Platform) {
+			deliveryReady = true
+			break
+		}
+	}
+	if !deliveryReady {
+		return fmt.Sprintf("已保存漏洞提醒：%s及以上。当前没有支持主动推送的已绑定账号；请绑定企业微信、飞书、Telegram、Slack 或 Discord。", vulnerabilityAlertSeverityLabel(sub.MinSeverity))
+	}
+	return fmt.Sprintf("已开启漏洞提醒：%s及以上漏洞将通过已绑定机器人推送。Web 端设置已同步。", vulnerabilityAlertSeverityLabel(sub.MinSeverity))
+}

internal/handler/vulnerability_alert_test.go

@@ -0,0 +1,51 @@
+package handler
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+
+	"go.uber.org/zap"
+)
+
+func TestRobotVulnerabilityAlertCommandSharesSubscription(t *testing.T) {
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "alert-command.db"), zap.NewNop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	if err := db.BootstrapRBAC("hash", security.PermissionCatalog); err != nil {
+		t.Fatal(err)
+	}
+	user, err := db.CreateRBACUser("alert-user", "Alert User", "hash", true, []string{database.RBACSystemRoleOperator})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := db.CreateRobotBindingCode(user.ID, "alert-code", time.Now().Add(time.Minute)); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := db.ConsumeRobotBindingCode("wecom", "external-user", "alert-code"); err != nil {
+		t.Fatal(err)
+	}
+	h := NewRobotHandler(&config.Config{}, db, nil, zap.NewNop())
+
+	if got := h.HandleMessage("wecom", "external-user", "漏洞提醒 高危以上"); !strings.Contains(got, "已开启") {
+		t.Fatalf("enable reply: %s", got)
+	}
+	sub, err := db.GetVulnerabilityAlertSubscription(user.ID)
+	if err != nil || !sub.Enabled || sub.MinSeverity != "high" {
+		t.Fatalf("web subscription not updated: %#v %v", sub, err)
+	}
+	if got := h.HandleMessage("wecom", "external-user", "vuln alerts off"); !strings.Contains(got, "已关闭") {
+		t.Fatalf("disable reply: %s", got)
+	}
+	sub, _ = db.GetVulnerabilityAlertSubscription(user.ID)
+	if sub.Enabled {
+		t.Fatalf("subscription remained enabled: %#v", sub)
+	}
+}

internal/handler/webshell_context.go

@@ -0,0 +1,106 @@
+package handler
+
+import (
+	"strings"
+
+	"cyberstrike-ai/internal/database"
+)
+
+// WebshellSkillHintDefault 对话页 / Eino 单代理共用的 Skills 说明，放在 webshell 上下文末尾，
+// 供 AI 选择 skill 加载入口时参考。
+const WebshellSkillHintDefault = "Skills 包请使用「多代理 / Eino DeepAgent」会话中的内置 `skill` 工具渐进加载。"
+
+// WebshellSkillHintMultiAgent 多代理 / Eino 多代理准备阶段使用的 Skills 说明
+const WebshellSkillHintMultiAgent = "Skills 包请使用 Eino 多代理内置 `skill` 工具。"
+
+// webshellAssistantToolList AI 助手在 WebShell 上下文下允许使用的工具清单（展示给模型用）。
+// 注意：此处只是展示字符串，真正的权限限制是在调用方设置的 roleTools 切片里。
+const webshellAssistantToolList = "webshell_exec、webshell_file_list、webshell_file_read、webshell_file_write、record_vulnerability、list_vulnerabilities、get_vulnerability、upsert_project_fact、get_project_fact、list_project_facts、search_project_facts、deprecate_project_fact、restore_project_fact、list_knowledge_risk_types、search_knowledge_base"
+
+// BuildWebshellAssistantContext 根据连接信息与用户原始消息组装 AI 助手的上下文提示词。
+// 上下文包含：连接 ID、备注、目标系统（及对应命令集建议）、响应编码、可用工具清单、Skills 加载入口、
+// 以及最终的用户请求。调用方只需要决定 skillHint 的文案（默认使用 WebshellSkillHintDefault）。
+//
+// 之所以把这段逻辑抽到共享函数里，是为了避免 agent.go / multi_agent_prepare.go 等多处复制粘贴，
+// 并确保当我们升级 OS / Encoding 文案时只需要改一处、测一处、同步生效。
+func BuildWebshellAssistantContext(conn *database.WebShellConnection, skillHint, userMsg string) string {
+	if conn == nil {
+		// 兜底：调用方已保证 conn 非 nil，这里只是防御性返回原消息
+		return userMsg
+	}
+	remark := conn.Remark
+	if remark == "" {
+		remark = conn.URL
+	}
+
+	targetOS := resolveWebshellOS(conn.OS, conn.Type) // 归一为 "linux" / "windows"
+	encoding := normalizeWebshellEncoding(conn.Encoding)
+	if skillHint == "" {
+		skillHint = WebshellSkillHintDefault
+	}
+
+	var b strings.Builder
+	b.Grow(512 + len(userMsg))
+
+	b.WriteString("[WebShell 助手上下文] 连接 ID：")
+	b.WriteString(conn.ID)
+	b.WriteString("，备注：")
+	b.WriteString(remark)
+	b.WriteByte('\n')
+
+	// 目标系统：明确告诉 AI 能用/不能用的命令集，避免它对着 Windows 发 ls/cat/rm
+	b.WriteString("- 目标系统：")
+	b.WriteString(describeTargetOSForPrompt(targetOS))
+	b.WriteByte('\n')
+
+	// 响应编码：仅在非 auto 时显式告知，auto 模式由后端自适应，不打扰模型
+	if encHint := describeEncodingForPrompt(encoding); encHint != "" {
+		b.WriteString("- 响应编码：")
+		b.WriteString(encHint)
+		b.WriteByte('\n')
+	}
+
+	// 工具清单 & connection_id 约束：保持旧有表达，AI 已熟悉
+	b.WriteString("可用工具（仅在该连接上操作时使用，connection_id 填 \"")
+	b.WriteString(conn.ID)
+	b.WriteString("\"）：")
+	b.WriteString(webshellAssistantToolList)
+	b.WriteString("。边渗透边记录：每确认新认知即 upsert_project_fact，每验证漏洞即 record_vulnerability，勿等会话结束。")
+	b.WriteString(skillHint)
+	b.WriteString("\n\n用户请求：")
+	b.WriteString(userMsg)
+
+	return b.String()
+}
+
+// describeTargetOSForPrompt 返回某个 OS 对应的中文描述 + 推荐命令集 + 反例，
+// 命令列表覆盖文件管理最常用的 6 类动作（查看/读/删/改名/建目录/查找），让 AI 能直接照抄。
+func describeTargetOSForPrompt(targetOS string) string {
+	switch targetOS {
+	case "windows":
+		return "Windows（推荐 cmd/PowerShell：dir /a、type、del /q /f、move /y、md、ren；" +
+			"查找文件用 `dir /s /b 过滤词` 或 PowerShell `Get-ChildItem -Recurse`；" +
+			"避免 ls / cat / rm / mv / find 等 Unix 命令，否则将返回 `不是内部或外部命令`）"
+	case "linux":
+		return "Linux/Unix（推荐 sh/bash：ls -la、cat、rm -f、mv、mkdir -p；" +
+			"查找文件用 `find /path -name '*pattern*'`；" +
+			"避免 dir、type、del、move 等 Windows 命令）"
+	default:
+		// 理论上不会走到这里，resolveWebshellOS 已经兜底
+		return "未知（请先执行 `uname || ver` 探测再决定命令集）"
+	}
+}
+
+// describeEncodingForPrompt 返回响应编码的人类可读描述；auto 返回空串以减少 token。
+func describeEncodingForPrompt(encoding string) string {
+	switch encoding {
+	case "utf-8":
+		return "UTF-8（目标原生 UTF-8，无需额外解码）"
+	case "gbk":
+		return "GBK（中文 Windows；后端已自动转码为 UTF-8 返回，若仍出现大量 \\uFFFD 替换字符说明命令失败或编码识别错误）"
+	case "gb18030":
+		return "GB18030（后端已自动转码为 UTF-8 返回）"
+	default:
+		return ""
+	}
+}

internal/handler/webshell_context_test.go

@@ -0,0 +1,170 @@
+package handler
+
+import (
+	"strings"
+	"testing"
+
+	"cyberstrike-ai/internal/database"
+)
+
+func TestBuildWebshellAssistantContext_WindowsExplicit(t *testing.T) {
+	conn := &database.WebShellConnection{
+		ID:       "ws_win01",
+		Remark:   "IIS Windows 靶机",
+		URL:      "http://example.com/shell.php",
+		Type:     "php",
+		OS:       "windows",
+		Encoding: "gbk",
+	}
+	got := BuildWebshellAssistantContext(conn, WebshellSkillHintDefault, "列出当前目录并告诉我 flag 在哪")
+
+	mustContain(t, got,
+		"[WebShell 助手上下文]",
+		"ws_win01",
+		"IIS Windows 靶机",
+		"目标系统：Windows",
+		"dir /a",
+		"move /y",
+		"避免 ls / cat / rm",
+		"响应编码：GBK",
+		"后端已自动转码为 UTF-8",
+		"connection_id 填 \"ws_win01\"",
+		"webshell_exec、webshell_file_list",
+		WebshellSkillHintDefault,
+		"用户请求：列出当前目录并告诉我 flag 在哪",
+	)
+	// Windows 场景下不应出现 Linux 命令推荐
+	mustNotContain(t, got, "推荐 sh/bash")
+}
+
+func TestBuildWebshellAssistantContext_LinuxAutoFromPHP(t *testing.T) {
+	conn := &database.WebShellConnection{
+		ID:       "ws_lnx01",
+		Remark:   "", // 测试备注为空时 fallback URL
+		URL:      "http://example.com/a.php",
+		Type:     "php",
+		OS:       "auto", // auto + php → linux
+		Encoding: "",     // auto 编码不显式提示
+	}
+	got := BuildWebshellAssistantContext(conn, WebshellSkillHintDefault, "看看 /etc/passwd")
+
+	mustContain(t, got,
+		"连接 ID：ws_lnx01",
+		"备注：http://example.com/a.php", // 备注空时 fallback URL
+		"目标系统：Linux/Unix",
+		"ls -la",
+		"mkdir -p",
+		"避免 dir、type、del、move",
+		"用户请求：看看 /etc/passwd",
+	)
+	// encoding=auto 不应出现"响应编码："这一行
+	mustNotContain(t, got, "响应编码：")
+	// Linux 场景不应出现 Windows 命令
+	mustNotContain(t, got, "推荐 cmd/PowerShell")
+}
+
+func TestBuildWebshellAssistantContext_AutoFromASPDefaultsToWindows(t *testing.T) {
+	// 保留向后兼容：旧连接没配 os，shellType=asp 时应视为 Windows
+	conn := &database.WebShellConnection{
+		ID:       "ws_asp01",
+		Remark:   "老 ASP 靶机",
+		Type:     "asp",
+		OS:       "", // 空串等同 auto
+		Encoding: "gb18030",
+	}
+	got := BuildWebshellAssistantContext(conn, WebshellSkillHintMultiAgent, "查当前用户")
+
+	mustContain(t, got,
+		"目标系统：Windows",
+		"响应编码：GB18030",
+		"后端已自动转码为 UTF-8 返回",
+		WebshellSkillHintMultiAgent,
+	)
+	// 多代理 skill 文案里没有 DeepAgent，不应混入 default 文案
+	mustNotContain(t, got, "DeepAgent")
+}
+
+func TestBuildWebshellAssistantContext_MultiAgentSkillHint(t *testing.T) {
+	conn := &database.WebShellConnection{ID: "ws_m1", Remark: "x", Type: "php", OS: "linux"}
+	got := BuildWebshellAssistantContext(conn, WebshellSkillHintMultiAgent, "hi")
+	mustContain(t, got, WebshellSkillHintMultiAgent)
+	mustNotContain(t, got, "DeepAgent")
+}
+
+func TestBuildWebshellAssistantContext_DefaultSkillHintFallback(t *testing.T) {
+	conn := &database.WebShellConnection{ID: "ws_d1", Remark: "x", Type: "php", OS: "linux"}
+	// skillHint 传空字符串时应回退到 default
+	got := BuildWebshellAssistantContext(conn, "", "hi")
+	mustContain(t, got, WebshellSkillHintDefault)
+}
+
+func TestBuildWebshellAssistantContext_UTF8EncodingIsAnnotated(t *testing.T) {
+	conn := &database.WebShellConnection{
+		ID: "ws_u1", Remark: "u", Type: "jsp", OS: "linux", Encoding: "utf-8",
+	}
+	got := BuildWebshellAssistantContext(conn, WebshellSkillHintDefault, "hi")
+	mustContain(t, got, "响应编码：UTF-8", "目标原生 UTF-8")
+}
+
+func TestBuildWebshellAssistantContext_NilConnReturnsUserMsg(t *testing.T) {
+	// 防御性：conn == nil 时不 panic，直接返回原消息
+	got := BuildWebshellAssistantContext(nil, WebshellSkillHintDefault, "just the message")
+	if got != "just the message" {
+		t.Errorf("nil conn should return userMsg as-is, got %q", got)
+	}
+}
+
+func TestDescribeTargetOSForPrompt(t *testing.T) {
+	cases := map[string][]string{
+		"windows": {"Windows", "dir /a", "move /y", "PowerShell"},
+		"linux":   {"Linux/Unix", "ls -la", "mkdir -p"},
+		"":        {"未知", "uname"}, // 防御性分支
+	}
+	for in, wants := range cases {
+		got := describeTargetOSForPrompt(in)
+		for _, w := range wants {
+			if !strings.Contains(got, w) {
+				t.Errorf("describeTargetOSForPrompt(%q) should contain %q, got: %s", in, w, got)
+			}
+		}
+	}
+}
+
+func TestDescribeEncodingForPrompt(t *testing.T) {
+	cases := map[string]string{
+		"utf-8":   "UTF-8",
+		"gbk":     "GBK",
+		"gb18030": "GB18030",
+		"auto":    "",
+		"":        "",
+	}
+	for in, want := range cases {
+		got := describeEncodingForPrompt(in)
+		if want == "" && got != "" {
+			t.Errorf("describeEncodingForPrompt(%q) should return empty string, got: %s", in, got)
+		}
+		if want != "" && !strings.Contains(got, want) {
+			t.Errorf("describeEncodingForPrompt(%q) should contain %q, got: %s", in, want, got)
+		}
+	}
+}
+
+// ---- 小工具 ----
+
+func mustContain(t *testing.T, text string, substrings ...string) {
+	t.Helper()
+	for _, s := range substrings {
+		if !strings.Contains(text, s) {
+			t.Errorf("expected text to contain %q\n--- text ---\n%s", s, text)
+		}
+	}
+}
+
+func mustNotContain(t *testing.T, text string, substrings ...string) {
+	t.Helper()
+	for _, s := range substrings {
+		if strings.Contains(text, s) {
+			t.Errorf("text should not contain %q\n--- text ---\n%s", s, text)
+		}
+	}
+}

internal/handler/webshell_encoding_test.go

@@ -0,0 +1,103 @@
+package handler
+
+import (
+	"testing"
+
+	"golang.org/x/text/encoding/simplifiedchinese"
+	"golang.org/x/text/transform"
+)
+
+// mustEncode 使用指定编码对 UTF-8 字符串做编码，得到原始字节，用于构造测试输入
+func mustEncode(t *testing.T, s string, enc string) []byte {
+	t.Helper()
+	var tr transform.Transformer
+	switch enc {
+	case "gbk":
+		tr = simplifiedchinese.GBK.NewEncoder()
+	case "gb18030":
+		tr = simplifiedchinese.GB18030.NewEncoder()
+	default:
+		t.Fatalf("unsupported test encoding: %s", enc)
+	}
+	out, _, err := transform.Bytes(tr, []byte(s))
+	if err != nil {
+		t.Fatalf("mustEncode(%s) failed: %v", enc, err)
+	}
+	return out
+}
+
+func TestNormalizeWebshellEncoding(t *testing.T) {
+	cases := map[string]string{
+		"":         "auto",
+		"   ":      "auto",
+		"auto":     "auto",
+		"AUTO":     "auto",
+		"utf-8":    "utf-8",
+		"UTF-8":    "utf-8",
+		"utf8":     "utf-8",
+		"gbk":      "gbk",
+		"GBK":      "gbk",
+		"gb18030":  "gb18030",
+		"big5":     "auto", // 未支持的回退到 auto
+		"anything": "auto",
+	}
+	for in, want := range cases {
+		if got := normalizeWebshellEncoding(in); got != want {
+			t.Errorf("normalizeWebshellEncoding(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestDecodeWebshellOutput_AutoDetectsGBK(t *testing.T) {
+	// 模拟 Windows 中文 cmd 输出的 GBK 字节流
+	want := "用户名                        SID                                            类型"
+	raw := mustEncode(t, want, "gbk")
+
+	// auto 模式：UTF-8 校验失败后应当回退 GB18030 解码，得到原始中文
+	got := decodeWebshellOutput(raw, "auto")
+	if got != want {
+		t.Errorf("decodeWebshellOutput(auto) = %q, want %q", got, want)
+	}
+
+	// 显式 GBK 模式：同样应当正确解码
+	got = decodeWebshellOutput(raw, "gbk")
+	if got != want {
+		t.Errorf("decodeWebshellOutput(gbk) = %q, want %q", got, want)
+	}
+
+	// 显式 GB18030 模式：GBK 是 GB18030 子集，也应正确解码
+	got = decodeWebshellOutput(raw, "gb18030")
+	if got != want {
+		t.Errorf("decodeWebshellOutput(gb18030) = %q, want %q", got, want)
+	}
+}
+
+func TestDecodeWebshellOutput_PassthroughUTF8(t *testing.T) {
+	// 已经是 UTF-8 的中文字符串，各模式都应返回原串（不破坏）
+	want := "hello 世界"
+	for _, enc := range []string{"", "auto", "utf-8"} {
+		if got := decodeWebshellOutput([]byte(want), enc); got != want {
+			t.Errorf("decodeWebshellOutput(%q) passthrough = %q, want %q", enc, got, want)
+		}
+	}
+}
+
+func TestDecodeWebshellOutput_ASCIIStable(t *testing.T) {
+	// 纯 ASCII 在任何模式下都必须保持原样
+	want := "whoami\nAdministrator\n"
+	for _, enc := range []string{"", "auto", "utf-8", "gbk", "gb18030"} {
+		if got := decodeWebshellOutput([]byte(want), enc); got != want {
+			t.Errorf("decodeWebshellOutput(%q) ASCII = %q, want %q", enc, got, want)
+		}
+	}
+}
+
+func TestDecodeWebshellOutput_EmptyInput(t *testing.T) {
+	// 空输入直接返回空串，不做额外分配
+	if got := decodeWebshellOutput(nil, "gbk"); got != "" {
+		t.Errorf("decodeWebshellOutput(nil) = %q, want empty", got)
+	}
+	if got := decodeWebshellOutput([]byte{}, "auto"); got != "" {
+		t.Errorf("decodeWebshellOutput([]) = %q, want empty", got)
+	}
+}

internal/handler/webshell_os_test.go

@@ -0,0 +1,348 @@
+package handler
+
+import (
+	"encoding/base64"
+	"strings"
+	"testing"
+
+	"go.uber.org/zap"
+)
+
+func newTestWebShellHandler() *WebShellHandler {
+	return NewWebShellHandler(zap.NewNop(), nil)
+}
+
+func TestNormalizeWebshellOS(t *testing.T) {
+	cases := map[string]string{
+		"":        "auto",
+		"  ":      "auto",
+		"auto":    "auto",
+		"AUTO":    "auto",
+		"linux":   "linux",
+		"Linux":   "linux",
+		"windows": "windows",
+		"WINDOWS": "windows",
+		"macos":   "auto", // 未支持的回退 auto
+		"solaris": "auto",
+	}
+	for in, want := range cases {
+		if got := normalizeWebshellOS(in); got != want {
+			t.Errorf("normalizeWebshellOS(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestResolveWebshellOS(t *testing.T) {
+	type testCase struct {
+		osTag     string
+		shellType string
+		want      string
+	}
+	cases := []testCase{
+		// 显式 OS：按用户选择，忽略 shellType
+		{"linux", "asp", "linux"},
+		{"windows", "php", "windows"},
+		{"LINUX", "jsp", "linux"},
+
+		// auto + 各种 shellType：asp/aspx → windows，其他 → linux
+		{"auto", "asp", "windows"},
+		{"auto", "aspx", "windows"},
+		{"auto", "ASP", "windows"},
+		{"auto", "php", "linux"},
+		{"auto", "jsp", "linux"},
+		{"auto", "custom", "linux"},
+		{"auto", "", "linux"},
+
+		// 空/未知 OS 等价 auto
+		{"", "asp", "windows"},
+		{"", "php", "linux"},
+		{"unknown", "aspx", "windows"},
+	}
+	for _, c := range cases {
+		got := resolveWebshellOS(c.osTag, c.shellType)
+		if got != c.want {
+			t.Errorf("resolveWebshellOS(%q,%q) = %q, want %q", c.osTag, c.shellType, got, c.want)
+		}
+	}
+}
+
+func TestQuoteCmdPath(t *testing.T) {
+	cases := map[string]string{
+		"":                     `"."`,
+		`C:\Windows\Temp`:      `"C:\Windows\Temp"`,
+		`C:\Program Files\a`:   `"C:\Program Files\a"`,
+		`C:\weird"name\f.txt`:  `"C:\weird""name\f.txt"`,
+		`.`:                    `"."`,
+	}
+	for in, want := range cases {
+		if got := quoteCmdPath(in); got != want {
+			t.Errorf("quoteCmdPath(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestQuoteShellSinglePosix(t *testing.T) {
+	cases := map[string]string{
+		"":             ".",
+		"/tmp/a b":     "'/tmp/a b'",
+		"/tmp/it's.txt": `'/tmp/it'\''s.txt'`,
+	}
+	for in, want := range cases {
+		if got := quoteShellSinglePosix(in); got != want {
+			t.Errorf("quoteShellSinglePosix(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+// TestBuildFileCommand_LinuxBranch 覆盖 Linux 目标下每个 action 产出的命令
+func TestBuildFileCommand_LinuxBranch(t *testing.T) {
+	h := newTestWebShellHandler()
+	base := fileCommandInput{OS: "linux", ShellType: "php"}
+
+	mustContain := func(t *testing.T, cmd string, substrings ...string) {
+		t.Helper()
+		for _, s := range substrings {
+			if !strings.Contains(cmd, s) {
+				t.Errorf("expected command to contain %q, got: %s", s, cmd)
+			}
+		}
+	}
+	mustNotContain := func(t *testing.T, cmd string, substrings ...string) {
+		t.Helper()
+		for _, s := range substrings {
+			if strings.Contains(cmd, s) {
+				t.Errorf("command should not contain %q, got: %s", s, cmd)
+			}
+		}
+	}
+
+	// list with empty path defaults to '.'
+	in := base
+	in.Action = "list"
+	cmd, err := h.buildFileCommand(in)
+	if err != nil {
+		t.Fatalf("list linux: unexpected err: %v", err)
+	}
+	mustContain(t, cmd, "ls -la", "'.'")
+
+	// list with path containing spaces
+	in.Path = "/tmp/my files"
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "ls -la ", "'/tmp/my files'")
+
+	// read with path
+	in = base
+	in.Action = "read"
+	in.Path = "/etc/passwd"
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "cat ", "'/etc/passwd'")
+
+	// read without path → error
+	in.Path = ""
+	if _, err := h.buildFileCommand(in); err != errFileOpPathRequired {
+		t.Errorf("read empty path: want errFileOpPathRequired, got %v", err)
+	}
+
+	// delete
+	in = base
+	in.Action = "delete"
+	in.Path = "/tmp/a.txt"
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "rm -f ", "'/tmp/a.txt'")
+	mustNotContain(t, cmd, "del")
+
+	// mkdir
+	in.Action = "mkdir"
+	in.Path = "/tmp/new/sub"
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "mkdir -p ", "'/tmp/new/sub'")
+
+	// rename
+	in = base
+	in.Action = "rename"
+	in.Path = "/tmp/a"
+	in.TargetPath = "/tmp/b"
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "mv -f ", "'/tmp/a'", "'/tmp/b'")
+
+	// rename missing target → error
+	in.TargetPath = ""
+	if _, err := h.buildFileCommand(in); err != errFileOpRenameNeedsBothPaths {
+		t.Errorf("rename empty target: want errFileOpRenameNeedsBothPaths, got %v", err)
+	}
+
+	// write
+	in = base
+	in.Action = "write"
+	in.Path = "/tmp/w.txt"
+	in.Content = "hello 世界"
+	cmd, _ = h.buildFileCommand(in)
+	b64 := base64.StdEncoding.EncodeToString([]byte("hello 世界"))
+	mustContain(t, cmd, "echo '"+b64+"'", "| base64 -d", "> '/tmp/w.txt'")
+
+	// upload
+	in = base
+	in.Action = "upload"
+	in.Path = "/tmp/bin"
+	in.Content = "YWJjZA==" // base64 of "abcd"
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "echo 'YWJjZA=='", "| base64 -d", "> '/tmp/bin'")
+
+	// upload oversized content → error
+	in.Content = strings.Repeat("A", 513*1024)
+	if _, err := h.buildFileCommand(in); err != errFileOpUploadTooLarge {
+		t.Errorf("upload too large: want errFileOpUploadTooLarge, got %v", err)
+	}
+
+	// upload_chunk with chunk_index=0 uses single redirect
+	in = base
+	in.Action = "upload_chunk"
+	in.Path = "/tmp/bin"
+	in.Content = "YWJj"
+	in.ChunkIndex = 0
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "base64 -d > '/tmp/bin'")
+	mustNotContain(t, cmd, ">>")
+
+	// upload_chunk with chunk_index>0 uses append redirect
+	in.ChunkIndex = 1
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "base64 -d >> '/tmp/bin'")
+
+	// unsupported action
+	in = base
+	in.Action = "nope"
+	if _, err := h.buildFileCommand(in); err == nil || !strings.Contains(err.Error(), "unsupported action") {
+		t.Errorf("unknown action: want unsupported action error, got %v", err)
+	}
+}
+
+// TestBuildFileCommand_WindowsBranch 覆盖 Windows 目标下每个 action 产出的命令
+func TestBuildFileCommand_WindowsBranch(t *testing.T) {
+	h := newTestWebShellHandler()
+	base := fileCommandInput{OS: "windows", ShellType: "php"}
+
+	mustContain := func(t *testing.T, cmd string, substrings ...string) {
+		t.Helper()
+		for _, s := range substrings {
+			if !strings.Contains(cmd, s) {
+				t.Errorf("expected command to contain %q, got: %s", s, cmd)
+			}
+		}
+	}
+	mustNotContain := func(t *testing.T, cmd string, substrings ...string) {
+		t.Helper()
+		for _, s := range substrings {
+			if strings.Contains(cmd, s) {
+				t.Errorf("command should not contain %q, got: %s", s, cmd)
+			}
+		}
+	}
+
+	// list
+	in := base
+	in.Action = "list"
+	cmd, _ := h.buildFileCommand(in)
+	mustContain(t, cmd, "dir /a ", `"."`)
+	mustNotContain(t, cmd, "ls -la")
+
+	in.Path = `C:\Users\Public Docs`
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "dir /a ", `"C:\Users\Public Docs"`)
+
+	// read
+	in = base
+	in.Action = "read"
+	in.Path = `C:\flag.txt`
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "type ", `"C:\flag.txt"`)
+
+	// delete
+	in.Action = "delete"
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "del /q /f ", `"C:\flag.txt"`)
+	mustNotContain(t, cmd, "rm -f")
+
+	// mkdir
+	in.Action = "mkdir"
+	in.Path = `C:\a\b\c`
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "md ", `"C:\a\b\c"`)
+
+	// rename
+	in = base
+	in.Action = "rename"
+	in.Path = `C:\a.txt`
+	in.TargetPath = `C:\b.txt`
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "move /y ", `"C:\a.txt"`, `"C:\b.txt"`)
+
+	// write → PowerShell base64 one-liner
+	in = base
+	in.Action = "write"
+	in.Path = `C:\out.txt`
+	in.Content = "hello 世界"
+	cmd, _ = h.buildFileCommand(in)
+	wantB64 := base64.StdEncoding.EncodeToString([]byte("hello 世界"))
+	mustContain(t, cmd,
+		"powershell -NoProfile -NonInteractive -Command",
+		"[Convert]::FromBase64String('"+wantB64+"')",
+		"[IO.File]::WriteAllBytes('C:\\out.txt'",
+	)
+	mustNotContain(t, cmd, "echo ", "base64 -d")
+
+	// upload (chunk_index=0 equivalent) uses WriteAllBytes
+	in = base
+	in.Action = "upload"
+	in.Path = `C:\bin\f`
+	in.Content = "YWJjZA=="
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "WriteAllBytes('C:\\bin\\f'", "FromBase64String('YWJjZA==')")
+
+	// upload_chunk index=0 → WriteAllBytes
+	in.Action = "upload_chunk"
+	in.ChunkIndex = 0
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "WriteAllBytes(")
+	mustNotContain(t, cmd, "FileMode]::Append")
+
+	// upload_chunk index>0 → append (Open with Append mode)
+	in.ChunkIndex = 1
+	cmd, _ = h.buildFileCommand(in)
+	mustContain(t, cmd, "[IO.FileMode]::Append", "FromBase64String('YWJjZA==')")
+}
+
+// TestBuildFileCommand_AutoFallbackMatchesLegacyBehavior 确保 os=auto 时与旧版 shellType 判定行为完全一致
+// asp/aspx 视为 Windows（旧行为），其他视为 Linux。
+func TestBuildFileCommand_AutoFallbackMatchesLegacyBehavior(t *testing.T) {
+	h := newTestWebShellHandler()
+
+	// asp + auto → windows 命令
+	cmd, _ := h.buildFileCommand(fileCommandInput{Action: "list", OS: "auto", ShellType: "asp"})
+	if !strings.Contains(cmd, "dir /a") {
+		t.Errorf("auto + asp should use Windows cmd, got: %s", cmd)
+	}
+
+	cmd, _ = h.buildFileCommand(fileCommandInput{Action: "list", OS: "auto", ShellType: "aspx"})
+	if !strings.Contains(cmd, "dir /a") {
+		t.Errorf("auto + aspx should use Windows cmd, got: %s", cmd)
+	}
+
+	// php/jsp/custom + auto → linux 命令（与历史行为一致）
+	for _, st := range []string{"php", "jsp", "custom", ""} {
+		cmd, _ = h.buildFileCommand(fileCommandInput{Action: "list", OS: "auto", ShellType: st})
+		if !strings.Contains(cmd, "ls -la") {
+			t.Errorf("auto + %q should use Linux cmd, got: %s", st, cmd)
+		}
+	}
+
+	// 显式 OS 覆盖 shellType
+	cmd, _ = h.buildFileCommand(fileCommandInput{Action: "list", OS: "windows", ShellType: "php"})
+	if !strings.Contains(cmd, "dir /a") {
+		t.Errorf("explicit windows should override php shellType, got: %s", cmd)
+	}
+	cmd, _ = h.buildFileCommand(fileCommandInput{Action: "list", OS: "linux", ShellType: "asp"})
+	if !strings.Contains(cmd, "ls -la") {
+		t.Errorf("explicit linux should override asp shellType, got: %s", cmd)
+	}
+}

internal/handler/webshell_probe.go

@@ -0,0 +1,127 @@
+package handler
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"strings"
+
+	"go.uber.org/zap"
+)
+
+// webshellOSProbeCommand 探活命令：利用 Windows cmd 与 POSIX shell 对 `%OS%` 展开差异进行判定。
+//   - Windows cmd：`%OS%` 被展开为 `Windows_NT`，回显 `:OSPROBE_Windows_NT:END`
+//   - POSIX sh/bash：`%OS%` 不是变量语法，作为字面量原样保留，回显 `:OSPROBE_%OS%:END`
+//
+// 一条命令即可得到明确的、互斥的信号，避免探活成本（相比发两次命令）。
+// 冒号包裹是为了避免部分 shell 输出多余空白/BOM 时字符串匹配失效。
+const webshellOSProbeCommand = "echo :OSPROBE_%OS%:END"
+
+// probeWebshellOSViaExec 通过一次命令执行的回显推断目标操作系统。
+//
+// 返回值：
+//   - "windows" / "linux"：识别成功
+//   - ""：无法判定（调用方应保留既有 fallback 逻辑）
+//
+// 入参 execFn 是一个"发命令并拿到回显"的闭包；让 HTTP 入口和 MCP 入口可以共用同一套探活逻辑
+// 而不必关心底层是如何发包的。
+func probeWebshellOSViaExec(execFn func(cmd string) (output string, ok bool)) string {
+	if execFn == nil {
+		return ""
+	}
+	out, ok := execFn(webshellOSProbeCommand)
+	if !ok {
+		return ""
+	}
+	return classifyWebshellOSProbeOutput(out)
+}
+
+// classifyWebshellOSProbeOutput 纯函数：根据探活命令的回显判定 OS。
+// 抽出来是为了单测可直接覆盖所有分支，无需真实 HTTP 调用。
+func classifyWebshellOSProbeOutput(out string) string {
+	if out == "" {
+		return ""
+	}
+	lower := strings.ToLower(out)
+
+	// Windows 强信号：cmd.exe 成功展开了 %OS% 变量
+	if strings.Contains(out, "Windows_NT") {
+		return "windows"
+	}
+	// 容错：部分老版本 Windows 可能 `%OS%` 展开为其他字样（极少见），再看 PATH/OS 等次级线索
+	if strings.Contains(lower, "microsoft windows") {
+		return "windows"
+	}
+
+	// Linux/Unix 强信号：`%OS%` 字面量被原样回显，说明 shell 不是 cmd.exe
+	if strings.Contains(out, "%OS%") {
+		return "linux"
+	}
+
+	// 次级线索：部分 webshell 在 Linux 上可能走了其他外壳（如 zsh/ash），
+	// 但它们对 `%OS%` 同样不展开；若命中 OSPROBE 头部却没拿到 %OS% 字面量，
+	// 说明回显被中途截断或过滤，保守返回空让上层 fallback。
+	return ""
+}
+
+// newHTTPExecFn 为 HTTP FileOp 路径构造"发命令取回显"的闭包，供探活复用。
+// 参数来自 HTTP 请求，复用 buildExecURL / buildExecBody 两个已有的命令编排器，
+// 确保探活包与实际文件操作包走完全一致的 webshell 协议（GET/POST、参数名、编码）。
+func (h *WebShellHandler) newHTTPExecFn(targetURL, password, shellType, method, cmdParam, encoding string) func(string) (string, bool) {
+	useGET := strings.ToUpper(strings.TrimSpace(method)) == "GET"
+	if strings.TrimSpace(cmdParam) == "" {
+		cmdParam = "cmd"
+	}
+	return func(cmd string) (string, bool) {
+		var (
+			httpReq *http.Request
+			err     error
+		)
+		if useGET {
+			u := h.buildExecURL(targetURL, shellType, password, cmdParam, cmd)
+			httpReq, err = http.NewRequest(http.MethodGet, u, nil)
+		} else {
+			body := h.buildExecBody(shellType, password, cmdParam, cmd)
+			httpReq, err = http.NewRequest(http.MethodPost, targetURL, bytes.NewReader(body))
+			if err == nil {
+				httpReq.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+			}
+		}
+		if err != nil {
+			return "", false
+		}
+		httpReq.Header.Set("User-Agent", "Mozilla/5.0 (compatible; CyberStrikeAI-WebShell/1.0)")
+		resp, err := h.client.Do(httpReq)
+		if err != nil {
+			return "", false
+		}
+		defer resp.Body.Close()
+		raw, _ := io.ReadAll(resp.Body)
+		return decodeWebshellOutput(raw, encoding), resp.StatusCode == http.StatusOK
+	}
+}
+
+// persistDetectedOS 把探活结果回写到连接表；失败只记日志不阻断主流程。
+// 设计上故意只触发 UPDATE，不会新建记录，因此即便 connectionID 不存在也只是悄悄放弃。
+func (h *WebShellHandler) persistDetectedOS(connectionID, detected string) {
+	connectionID = strings.TrimSpace(connectionID)
+	detected = normalizeWebshellOS(detected)
+	if connectionID == "" || detected == "" || detected == "auto" {
+		return
+	}
+	conn, err := h.db.GetWebshellConnection(connectionID)
+	if err != nil || conn == nil {
+		// 不是所有调用方都能提供有效 ID（比如临时测试），这里静默返回
+		return
+	}
+	if normalizeWebshellOS(conn.OS) != "auto" {
+		// 用户已经显式选过 OS，尊重用户选择，不自动覆盖
+		return
+	}
+	conn.OS = detected
+	if err := h.db.UpdateWebshellConnection(conn); err != nil {
+		h.logger.Warn("webshell 探活结果持久化失败", zap.String("id", connectionID), zap.String("os", detected), zap.Error(err))
+		return
+	}
+	h.logger.Info("webshell auto OS 探活成功并持久化", zap.String("id", connectionID), zap.String("os", detected))
+}

internal/handler/webshell_probe_test.go

@@ -0,0 +1,68 @@
+package handler
+
+import "testing"
+
+func TestClassifyWebshellOSProbeOutput(t *testing.T) {
+	cases := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{"Windows cmd 回显完整", ":OSPROBE_Windows_NT:END\r\n", "windows"},
+		{"Windows cmd 回显带额外空行", "\r\n:OSPROBE_Windows_NT:END\r\n", "windows"},
+		{"Windows 次级线索 - ver banner", "Microsoft Windows [版本 10.0.19045]\r\n", "windows"},
+		{"Linux sh 字面量回显", ":OSPROBE_%OS%:END\n", "linux"},
+		{"Linux 紧凑输出（无换行）", ":OSPROBE_%OS%:END", "linux"},
+		{"空输出 - 无法判定", "", ""},
+		{"被过滤的输出 - 无法判定", "something weird", ""},
+		{"仅有 OSPROBE 前缀但被截断 - 保守返回空", ":OSPROBE_:END", ""},
+	}
+	for _, c := range cases {
+		if got := classifyWebshellOSProbeOutput(c.in); got != c.want {
+			t.Errorf("case %q: got %q, want %q", c.name, got, c.want)
+		}
+	}
+}
+
+func TestProbeWebshellOSViaExec_SendsOneCommandOnly(t *testing.T) {
+	var calls []string
+	fn := func(cmd string) (string, bool) {
+		calls = append(calls, cmd)
+		return ":OSPROBE_Windows_NT:END", true
+	}
+	got := probeWebshellOSViaExec(fn)
+	if got != "windows" {
+		t.Fatalf("want windows, got %q", got)
+	}
+	if len(calls) != 1 {
+		t.Fatalf("probe should issue exactly one exec call, got %d: %v", len(calls), calls)
+	}
+	if calls[0] != webshellOSProbeCommand {
+		t.Errorf("probe command mismatch: got %q", calls[0])
+	}
+}
+
+func TestProbeWebshellOSViaExec_NotOkReturnsEmpty(t *testing.T) {
+	// HTTP 非 200 的场景：execFn 返回 ok=false，探活应放弃
+	fn := func(cmd string) (string, bool) { return "whatever", false }
+	if got := probeWebshellOSViaExec(fn); got != "" {
+		t.Errorf("want empty when exec not ok, got %q", got)
+	}
+}
+
+func TestProbeWebshellOSViaExec_NilSafeguard(t *testing.T) {
+	if got := probeWebshellOSViaExec(nil); got != "" {
+		t.Errorf("nil execFn should return empty, got %q", got)
+	}
+}
+
+func TestProbeWebshellOSViaExec_LinuxUname(t *testing.T) {
+	// 某些 webshell 对 `%OS%` 字面量也会过滤（例如安全规则），
+	// 但主要路径是"%OS% 字面量被原样回显"。这里覆盖标准 Linux 场景。
+	fn := func(cmd string) (string, bool) {
+		return ":OSPROBE_%OS%:END\n", true
+	}
+	if got := probeWebshellOSViaExec(fn); got != "linux" {
+		t.Errorf("Linux case: want linux, got %q", got)
+	}
+}

internal/handler/webshell_rbac_test.go

@@ -0,0 +1,156 @@
+package handler
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func TestWebshellExecRequiresConnectionAccessWhenConnectionIDProvided(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, user, allowed, hidden := setupWebshellRBACTest(t)
+	handler := NewWebShellHandler(zap.NewNop(), db)
+
+	w := performWebshellJSON(user, http.MethodPost, "/api/webshell/exec", map[string]interface{}{
+		"url":           hidden.URL,
+		"connection_id": hidden.ID,
+		"command":       "id",
+	}, handler.Exec)
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("hidden connection status = %d, want %d: %s", w.Code, http.StatusForbidden, w.Body.String())
+	}
+
+	w = performWebshellJSON(user, http.MethodPost, "/api/webshell/exec", map[string]interface{}{
+		"url":           hidden.URL,
+		"connection_id": allowed.ID,
+		"command":       "id",
+	}, handler.Exec)
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("mismatched URL status = %d, want %d: %s", w.Code, http.StatusForbidden, w.Body.String())
+	}
+}
+
+func TestWebshellExecAllowsAdHocURLWithoutConnectionID(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	_, user, _, _ := setupWebshellRBACTest(t)
+	handler := NewWebShellHandler(zap.NewNop(), nil)
+	// Ad-hoc probe (connectivity test before save) must not be rejected as "无权访问".
+	// The target URL will fail to connect; we only assert auth allows the request through.
+	w := performWebshellJSON(user, http.MethodPost, "/api/webshell/exec", map[string]interface{}{
+		"url": "http://127.0.0.1:1/admin", "command": "id",
+	}, handler.Exec)
+	if w.Code == http.StatusForbidden {
+		t.Fatalf("ad-hoc URL status = %d, want non-403: %s", w.Code, w.Body.String())
+	}
+	var resp ExecResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode response: %v body=%s", err, w.Body.String())
+	}
+	if resp.OK {
+		t.Fatalf("expected connection failure for closed port, got ok=true")
+	}
+}
+
+func TestWebshellExecRejectsAdHocWithoutWritePermission(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	user := &database.RBACUser{ID: "u_ro", Username: "readonly"}
+	handler := NewWebShellHandler(zap.NewNop(), nil)
+	payload, _ := json.Marshal(map[string]interface{}{
+		"url": "http://127.0.0.1/admin", "command": "id",
+	})
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodPost, "/api/webshell/exec", bytes.NewReader(payload))
+	c.Request.Header.Set("Content-Type", "application/json")
+	c.Set(security.ContextSessionKey, security.Session{
+		UserID:      user.ID,
+		Username:    user.Username,
+		Permissions: map[string]bool{"webshell:read": true},
+		Scope:       database.RBACScopeAssigned,
+	})
+	handler.Exec(c)
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want %d: %s", w.Code, http.StatusForbidden, w.Body.String())
+	}
+}
+
+func TestWebshellFileOpRequiresConnectionAccessWhenConnectionIDProvided(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	db, user, _, hidden := setupWebshellRBACTest(t)
+	handler := NewWebShellHandler(zap.NewNop(), db)
+
+	w := performWebshellJSON(user, http.MethodPost, "/api/webshell/file", map[string]interface{}{
+		"url":           hidden.URL,
+		"connection_id": hidden.ID,
+		"action":        "list",
+		"path":          ".",
+	}, handler.FileOp)
+	if w.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want %d: %s", w.Code, http.StatusForbidden, w.Body.String())
+	}
+}
+
+func setupWebshellRBACTest(t *testing.T) (*database.DB, *database.RBACUser, *database.WebShellConnection, *database.WebShellConnection) {
+	t.Helper()
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "webshell-rbac.db"), zap.NewNop())
+	if err != nil {
+		t.Fatalf("NewDB: %v", err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	user, err := db.CreateRBACUser("operator1", "Operator One", "hash", true, nil)
+	if err != nil {
+		t.Fatalf("CreateRBACUser: %v", err)
+	}
+	allowed := &database.WebShellConnection{
+		ID:        "ws_allowed",
+		URL:       "http://127.0.0.1/allowed.php",
+		Type:      "php",
+		Method:    "post",
+		CmdParam:  "cmd",
+		CreatedAt: time.Now(),
+	}
+	hidden := &database.WebShellConnection{
+		ID:        "ws_hidden",
+		URL:       "http://127.0.0.1/hidden.php",
+		Type:      "php",
+		Method:    "post",
+		CmdParam:  "cmd",
+		CreatedAt: time.Now(),
+	}
+	if err := db.CreateWebshellConnection(allowed); err != nil {
+		t.Fatalf("CreateWebshellConnection allowed: %v", err)
+	}
+	if err := db.CreateWebshellConnection(hidden); err != nil {
+		t.Fatalf("CreateWebshellConnection hidden: %v", err)
+	}
+	if err := db.AssignResourceToUser(user.ID, "webshell", allowed.ID); err != nil {
+		t.Fatalf("AssignResourceToUser: %v", err)
+	}
+	return db, user, allowed, hidden
+}
+
+func performWebshellJSON(user *database.RBACUser, method, path string, body map[string]interface{}, handler gin.HandlerFunc) *httptest.ResponseRecorder {
+	payload, _ := json.Marshal(body)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(method, path, bytes.NewReader(payload))
+	c.Request.Header.Set("Content-Type", "application/json")
+	c.Set(security.ContextSessionKey, security.Session{
+		UserID:      user.ID,
+		Username:    user.Username,
+		Permissions: map[string]bool{"webshell:write": true},
+		Scope:       database.RBACScopeAssigned,
+	})
+	handler(c)
+	return w
+}

internal/handler/wechat_robot.go

@@ -0,0 +1,293 @@
+package handler
+
+import (
+	"context"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/robot/ilink"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"go.uber.org/zap"
+)
+
+const wechatLoginTTL = 5 * time.Minute
+
+// WechatConfigSaver 绑定成功后写入配置并重启机器人连接
+type WechatConfigSaver interface {
+	ApplyWechatRobotBinding(cfg config.RobotWechatConfig) error
+}
+
+type wechatLoginSession struct {
+	QRCode           string
+	QRCodeImgURL     string
+	PendingVerify    string
+	CurrentBaseURL   string
+	StartedAt        time.Time
+}
+
+// WechatRobotHandler 微信 iLink 机器人（扫码绑定 + 配置）
+type WechatRobotHandler struct {
+	config       *config.Config
+	configSaver  WechatConfigSaver
+	logger       *zap.Logger
+	mu           sync.Mutex
+	logins       map[string]*wechatLoginSession
+}
+
+// NewWechatRobotHandler 创建微信机器人处理器
+func NewWechatRobotHandler(cfg *config.Config, saver WechatConfigSaver, logger *zap.Logger) *WechatRobotHandler {
+	return &WechatRobotHandler{
+		config:      cfg,
+		configSaver: saver,
+		logger:      logger,
+		logins:      make(map[string]*wechatLoginSession),
+	}
+}
+
+func (h *WechatRobotHandler) purgeExpiredLogins() {
+	now := time.Now()
+	for k, v := range h.logins {
+		if now.Sub(v.StartedAt) > wechatLoginTTL {
+			delete(h.logins, k)
+		}
+	}
+}
+
+func (h *WechatRobotHandler) ilinkClient(baseURL string) *ilink.Client {
+	ver := h.config.Version
+	if ver == "" {
+		ver = "1.0.0"
+	}
+	ver = strings.TrimPrefix(strings.TrimSpace(ver), "v")
+	ver = strings.TrimPrefix(ver, "V")
+	wc := h.config.Robots.Wechat
+	return ilink.NewClient(baseURL, wc.BotToken, wc.BotAgent, ilink.BuildClientVersion(ver))
+}
+
+// HandleWechatQRCode POST /api/robot/wechat/qrcode — 生成绑定二维码
+func (h *WechatRobotHandler) HandleWechatQRCode(c *gin.Context) {
+	h.mu.Lock()
+	h.purgeExpiredLogins()
+	h.mu.Unlock()
+
+	var req struct {
+		BotType string `json:"bot_type"`
+	}
+	_ = c.ShouldBindJSON(&req)
+
+	botType := req.BotType
+	if botType == "" {
+		botType = h.config.Robots.Wechat.BotType
+	}
+	if botType == "" {
+		botType = ilink.DefaultBotType
+	}
+	baseURL := h.config.Robots.Wechat.BaseURL
+	if baseURL == "" {
+		baseURL = ilink.DefaultBaseURL
+	}
+
+	var localTokens []string
+	if t := h.config.Robots.Wechat.BotToken; t != "" {
+		localTokens = []string{t}
+	}
+
+	client := h.ilinkClient(baseURL)
+	ctx, cancel := context.WithTimeout(c.Request.Context(), 30*time.Second)
+	defer cancel()
+
+	qr, err := client.GetBotQRCode(ctx, botType, localTokens)
+	if err != nil {
+		h.logger.Warn("获取微信二维码失败", zap.Error(err))
+		c.JSON(http.StatusBadGateway, gin.H{"error": "获取二维码失败: " + err.Error()})
+		return
+	}
+	if qr.QRCode == "" || qr.QRCodeImgContent == "" {
+		c.JSON(http.StatusBadGateway, gin.H{"error": "微信服务器未返回有效二维码"})
+		return
+	}
+
+	sessionKey := uuid.New().String()
+	h.mu.Lock()
+	h.logins[sessionKey] = &wechatLoginSession{
+		QRCode:         qr.QRCode,
+		QRCodeImgURL:   qr.QRCodeImgContent,
+		CurrentBaseURL: baseURL,
+		StartedAt:      time.Now(),
+	}
+	h.mu.Unlock()
+
+	resp := gin.H{
+		"session_key":     sessionKey,
+		"qrcode":          qr.QRCode,
+		"qrcode_open_url": qr.QRCodeImgContent,
+		"message":         "请使用微信扫描二维码并确认绑定",
+	}
+	if dataURL, err := ilink.QRCodeDataURL(qr.QRCodeImgContent, 256); err != nil {
+		h.logger.Warn("生成二维码图片失败", zap.Error(err))
+	} else {
+		resp["qrcode_image_data_url"] = dataURL
+	}
+
+	c.JSON(http.StatusOK, resp)
+}
+
+// HandleWechatQRCodeStatus GET /api/robot/wechat/qrcode/status — 轮询扫码状态
+func (h *WechatRobotHandler) HandleWechatQRCodeStatus(c *gin.Context) {
+	sessionKey := c.Query("session_key")
+	verifyCode := c.Query("verify_code")
+	if sessionKey == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "缺少 session_key"})
+		return
+	}
+
+	h.mu.Lock()
+	sess, ok := h.logins[sessionKey]
+	h.mu.Unlock()
+	if !ok {
+		c.JSON(http.StatusNotFound, gin.H{"error": "登录会话不存在或已过期，请重新生成二维码"})
+		return
+	}
+	if time.Since(sess.StartedAt) > wechatLoginTTL {
+		h.mu.Lock()
+		delete(h.logins, sessionKey)
+		h.mu.Unlock()
+		c.JSON(http.StatusGone, gin.H{"error": "二维码已过期，请重新生成"})
+		return
+	}
+
+	baseURL := sess.CurrentBaseURL
+	if baseURL == "" {
+		baseURL = ilink.DefaultBaseURL
+	}
+	vc := verifyCode
+	if vc == "" {
+		vc = sess.PendingVerify
+	}
+
+	client := h.ilinkClient(baseURL)
+	ctx, cancel := context.WithTimeout(c.Request.Context(), 40*time.Second)
+	defer cancel()
+
+	st, err := client.GetQRCodeStatus(ctx, sess.QRCode, vc)
+	if err != nil {
+		h.logger.Warn("轮询微信二维码状态失败", zap.Error(err))
+		c.JSON(http.StatusBadGateway, gin.H{"error": err.Error()})
+		return
+	}
+
+	switch st.Status {
+	case "wait", "scaned":
+		c.JSON(http.StatusOK, gin.H{"status": st.Status})
+		return
+	case "need_verifycode":
+		c.JSON(http.StatusOK, gin.H{
+			"status":  st.Status,
+			"message": "请在手机微信查看配对数字，并在下方输入",
+		})
+		return
+	case "scaned_but_redirect":
+		if st.RedirectHost != "" {
+			h.mu.Lock()
+			if s, ok := h.logins[sessionKey]; ok {
+				s.CurrentBaseURL = "https://" + st.RedirectHost
+			}
+			h.mu.Unlock()
+		}
+		c.JSON(http.StatusOK, gin.H{"status": st.Status})
+		return
+	case "binded_redirect":
+		h.mu.Lock()
+		delete(h.logins, sessionKey)
+		h.mu.Unlock()
+		c.JSON(http.StatusOK, gin.H{
+			"status":            st.Status,
+			"already_connected": true,
+			"message":           "该微信已绑定过，无需重复绑定",
+		})
+		return
+	case "confirmed":
+		if st.BotToken == "" || st.ILinkBotID == "" {
+			c.JSON(http.StatusBadGateway, gin.H{"error": "绑定确认成功但缺少 bot_token"})
+			return
+		}
+		saveBase := st.BaseURL
+		if saveBase == "" {
+			saveBase = baseURL
+		}
+		wc := h.config.Robots.Wechat
+		wc.Enabled = true
+		wc.BotToken = st.BotToken
+		wc.ILinkBotID = st.ILinkBotID
+		wc.ILinkUserID = st.ILinkUserID
+		wc.BaseURL = saveBase
+		if wc.BotType == "" {
+			wc.BotType = ilink.DefaultBotType
+		}
+		if wc.BotAgent == "" {
+			wc.BotAgent = ilink.DefaultBotAgent
+		}
+		if h.configSaver != nil {
+			if err := h.configSaver.ApplyWechatRobotBinding(wc); err != nil {
+				h.logger.Warn("保存微信机器人配置失败", zap.Error(err))
+				c.JSON(http.StatusInternalServerError, gin.H{"error": "保存配置失败: " + err.Error()})
+				return
+			}
+		} else {
+			h.config.Robots.Wechat = wc
+		}
+		h.mu.Lock()
+		delete(h.logins, sessionKey)
+		h.mu.Unlock()
+		c.JSON(http.StatusOK, gin.H{
+			"status":        "confirmed",
+			"message":       "绑定成功，微信机器人已启用",
+			"ilink_bot_id":  st.ILinkBotID,
+			"ilink_user_id": st.ILinkUserID,
+		})
+		return
+	default:
+		c.JSON(http.StatusOK, gin.H{"status": st.Status})
+	}
+}
+
+// HandleWechatVerifyCode POST /api/robot/wechat/qrcode/verify — 提交手机配对数字
+func (h *WechatRobotHandler) HandleWechatVerifyCode(c *gin.Context) {
+	var req struct {
+		SessionKey string `json:"session_key"`
+		VerifyCode string `json:"verify_code"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil || req.SessionKey == "" || req.VerifyCode == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "需要 session_key 与 verify_code"})
+		return
+	}
+	h.mu.Lock()
+	sess, ok := h.logins[req.SessionKey]
+	if ok {
+		sess.PendingVerify = req.VerifyCode
+	}
+	h.mu.Unlock()
+	if !ok {
+		c.JSON(http.StatusNotFound, gin.H{"error": "登录会话不存在或已过期"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "已提交配对码，请继续等待绑定"})
+}
+
+// HandleWechatStatus GET /api/robot/wechat/status — 当前绑定状态（供前端展示）
+func (h *WechatRobotHandler) HandleWechatStatus(c *gin.Context) {
+	wc := h.config.Robots.Wechat
+	bound := wc.BotToken != "" && wc.ILinkBotID != ""
+	c.JSON(http.StatusOK, gin.H{
+		"enabled":       wc.Enabled,
+		"bound":         bound,
+		"ilink_bot_id":  wc.ILinkBotID,
+		"ilink_user_id": wc.ILinkUserID,
+		"base_url":      wc.BaseURL,
+	})
+}

internal/handler/workflow.go

@@ -0,0 +1,255 @@
+package handler
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+
+	"cyberstrike-ai/internal/agent"
+	"cyberstrike-ai/internal/audit"
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/database"
+	workflowrunner "cyberstrike-ai/internal/workflow"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+type WorkflowHandler struct {
+	db     *database.DB
+	logger *zap.Logger
+	audit  *audit.Service
+	agent  *agent.Agent
+	cfg    *config.Config
+}
+
+func NewWorkflowHandler(db *database.DB, logger *zap.Logger) *WorkflowHandler {
+	return &WorkflowHandler{db: db, logger: logger}
+}
+
+func (h *WorkflowHandler) SetAudit(s *audit.Service) {
+	h.audit = s
+}
+
+type workflowSaveRequest struct {
+	ID          string          `json:"id"`
+	Name        string          `json:"name"`
+	Description string          `json:"description,omitempty"`
+	Version     int             `json:"version,omitempty"`
+	Enabled     *bool           `json:"enabled,omitempty"`
+	Graph       json.RawMessage `json:"graph,omitempty"`
+	GraphJSON   json.RawMessage `json:"graph_json,omitempty"`
+}
+
+type workflowDryRunRequest struct {
+	Graph     json.RawMessage        `json:"graph,omitempty"`
+	GraphJSON json.RawMessage        `json:"graph_json,omitempty"`
+	Inputs    map[string]interface{} `json:"inputs,omitempty"`
+}
+
+type workflowGenerateDraftRequest struct {
+	Prompt         string                      `json:"prompt"`
+	Options        workflowrunner.DraftOptions `json:"options"`
+	AvailableTools []workflowrunner.DraftTool  `json:"available_tools,omitempty"`
+}
+
+func (h *WorkflowHandler) List(c *gin.Context) {
+	includeDisabled := strings.EqualFold(c.Query("includeDisabled"), "true") || c.Query("include_disabled") == "1"
+	items, err := h.db.ListWorkflowDefinitions(includeDisabled)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"workflows": items})
+}
+
+func (h *WorkflowHandler) Get(c *gin.Context) {
+	id := strings.TrimSpace(c.Param("id"))
+	wf, err := h.db.GetWorkflowDefinition(id)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if wf == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "工作流不存在"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"workflow": wf})
+}
+
+func (h *WorkflowHandler) Create(c *gin.Context) {
+	h.save(c, "")
+}
+
+func (h *WorkflowHandler) Validate(c *gin.Context) {
+	var req workflowSaveRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"ok": false, "error": "无效的请求参数: " + err.Error()})
+		return
+	}
+	graph := req.Graph
+	if len(graph) == 0 {
+		graph = req.GraphJSON
+	}
+	if len(graph) == 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"ok": false, "error": "graph 不能为空"})
+		return
+	}
+	if !json.Valid(graph) {
+		c.JSON(http.StatusBadRequest, gin.H{"ok": false, "error": "graph 必须是合法 JSON"})
+		return
+	}
+	if err := workflowrunner.ValidateGraphJSON(c.Request.Context(), string(graph)); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"ok": false, "error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"ok": true})
+}
+
+func (h *WorkflowHandler) DryRun(c *gin.Context) {
+	var req workflowDryRunRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的请求参数: " + err.Error()})
+		return
+	}
+	graph := req.Graph
+	if len(graph) == 0 {
+		graph = req.GraphJSON
+	}
+	if len(graph) == 0 || !json.Valid(graph) {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "graph 必须是合法 JSON"})
+		return
+	}
+	inputs := make(map[string]any, len(req.Inputs))
+	for k, v := range req.Inputs {
+		inputs[k] = v
+	}
+	result, err := workflowrunner.DryRunGraphJSON(c.Request.Context(), string(graph), inputs)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"result": result})
+}
+
+func (h *WorkflowHandler) GenerateDraft(c *gin.Context) {
+	var req workflowGenerateDraftRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的请求参数: " + err.Error()})
+		return
+	}
+	draftReq := workflowrunner.DraftRequest{
+		Prompt:         req.Prompt,
+		Options:        req.Options,
+		AvailableTools: req.AvailableTools,
+	}
+	var result *workflowrunner.DraftResult
+	var llmErr error
+	if h.cfg != nil {
+		if llmCfg, _, ok := h.cfg.ResolveAIChannel(""); ok && strings.TrimSpace(llmCfg.APIKey) != "" && strings.TrimSpace(llmCfg.Model) != "" {
+			result, llmErr = workflowrunner.GenerateDraftFromLLM(c.Request.Context(), draftReq, llmCfg, h.logger)
+		} else {
+			llmErr = errors.New("AI 通道未配置 api_key 或 model")
+		}
+	} else {
+		llmErr = errors.New("工作流生成器未加载平台 AI 配置")
+	}
+	if llmErr != nil {
+		c.JSON(http.StatusBadGateway, gin.H{"error": "大模型生成失败: " + llmErr.Error()})
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "workflow", "generate_draft", "自然语言生成工作流草稿", "", "", map[string]interface{}{
+			"generator": result.Generator,
+			"nodes":     result.Stats["nodes"],
+			"edges":     result.Stats["edges"],
+			"high_risk": result.Audit.HighRisk,
+			"savable":   result.Audit.Savable,
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{"result": result})
+}
+
+func (h *WorkflowHandler) Update(c *gin.Context) {
+	h.save(c, c.Param("id"))
+}
+
+func (h *WorkflowHandler) save(c *gin.Context, pathID string) {
+	var req workflowSaveRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的请求参数: " + err.Error()})
+		return
+	}
+	id := strings.TrimSpace(req.ID)
+	if strings.TrimSpace(pathID) != "" {
+		id = strings.TrimSpace(pathID)
+	}
+	name := strings.TrimSpace(req.Name)
+	if id == "" || name == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "工作流 id 和 name 不能为空"})
+		return
+	}
+	graph := req.Graph
+	if len(graph) == 0 {
+		graph = req.GraphJSON
+	}
+	if len(graph) == 0 {
+		graph = []byte(`{"nodes":[],"edges":[],"config":{}}`)
+	}
+	if !json.Valid(graph) {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "graph 必须是合法 JSON"})
+		return
+	}
+	if err := workflowrunner.ValidateGraphJSON(c.Request.Context(), string(graph)); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "工作流图无法编译: " + err.Error()})
+		return
+	}
+	var probe interface{}
+	if err := json.Unmarshal(graph, &probe); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "graph JSON 解析失败: " + err.Error()})
+		return
+	}
+	enabled := true
+	if req.Enabled != nil {
+		enabled = *req.Enabled
+	}
+	wf := &database.WorkflowDefinition{
+		ID:          id,
+		Name:        name,
+		Description: strings.TrimSpace(req.Description),
+		Version:     req.Version,
+		GraphJSON:   string(graph),
+		Enabled:     enabled,
+	}
+	if err := h.db.UpsertWorkflowDefinition(wf); err != nil {
+		if h.logger != nil {
+			h.logger.Warn("保存工作流失败", zap.String("id", id), zap.Error(err))
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	saved, _ := h.db.GetWorkflowDefinition(id)
+	workflowrunner.InvalidateCompiledCache(id)
+	if h.audit != nil {
+		h.audit.RecordOK(c, "workflow", "save", "保存工作流", "workflow", id, map[string]interface{}{"name": name})
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "工作流已保存", "workflow": saved})
+}
+
+func (h *WorkflowHandler) Delete(c *gin.Context) {
+	id := strings.TrimSpace(c.Param("id"))
+	if id == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "工作流 id 不能为空"})
+		return
+	}
+	if err := h.db.DeleteWorkflowDefinition(id); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	workflowrunner.InvalidateCompiledCache(id)
+	if h.audit != nil {
+		h.audit.RecordOK(c, "workflow", "delete", "删除工作流", "workflow", id, nil)
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "工作流已删除"})
+}

internal/handler/workflow_integration.go

@@ -0,0 +1,304 @@
+package handler
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/config"
+	workflowrunner "cyberstrike-ai/internal/workflow"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+)
+
+func (h *AgentHandler) roleForWorkflow(req *ChatRequest) (config.RoleConfig, bool) {
+	if h == nil || h.config == nil || h.config.Roles == nil || req == nil {
+		return config.RoleConfig{}, false
+	}
+	roleName := strings.TrimSpace(req.Role)
+	if roleName == "" {
+		return config.RoleConfig{}, false
+	}
+	role, ok := h.config.Roles[roleName]
+	if !ok || !role.Enabled {
+		return config.RoleConfig{}, false
+	}
+	if role.Name == "" {
+		role.Name = roleName
+	}
+	if !workflowrunner.ShouldAutoRunRoleWorkflow(role) {
+		return config.RoleConfig{}, false
+	}
+	return role, true
+}
+
+func (h *AgentHandler) runRoleWorkflowStreamIfBound(
+	c *gin.Context,
+	req *ChatRequest,
+	prep *multiAgentPrepared,
+	sendEvent func(eventType, message string, data interface{}),
+) bool {
+	role, ok := h.roleForWorkflow(req)
+	if !ok || prep == nil {
+		return false
+	}
+
+	conversationID := prep.ConversationID
+	assistantMessageID := prep.AssistantMessageID
+	userMessage := ""
+	if req != nil {
+		userMessage = req.Message
+	}
+
+	taskStatus := "completed"
+	taskOwned := false
+	defer func() {
+		if taskOwned {
+			h.tasks.FinishTask(conversationID, taskStatus)
+		}
+	}()
+
+	if c == nil || c.Request == nil {
+		return false
+	}
+	baseCtx, cancelWithCause := context.WithCancelCause(detachedAgentContext(c.Request.Context()))
+	defer cancelWithCause(nil)
+	taskCtx, timeoutCancel := context.WithTimeout(baseCtx, 600*time.Minute)
+	defer timeoutCancel()
+
+	if _, err := h.tasks.StartTask(conversationID, userMessage, cancelWithCause); err != nil {
+		var errorMsg string
+		if errors.Is(err, ErrTaskAlreadyRunning) {
+			errorMsg = "⚠️ 当前会话已有任务正在执行中，请等待当前任务完成或点击「停止任务」后再尝试。"
+			sendEvent("error", errorMsg, map[string]interface{}{
+				"conversationId": conversationID,
+				"errorType":      "task_already_running",
+			})
+		} else {
+			errorMsg = "❌ 无法启动任务: " + err.Error()
+			sendEvent("error", errorMsg, nil)
+		}
+		if assistantMessageID != "" {
+			_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", errorMsg, time.Now(), assistantMessageID)
+		}
+		sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+		return true
+	}
+	taskOwned = true
+
+	progress := h.createProgressCallback(taskCtx, cancelWithCause, conversationID, assistantMessageID, sendEvent)
+	result, err := workflowrunner.RunRoleBoundWorkflow(taskCtx, workflowrunner.RunArgs{
+		DB:                 h.db,
+		Logger:             h.logger,
+		Role:               role,
+		AppCfg:             h.config,
+		Agent:              h.agent,
+		ConversationID:     conversationID,
+		ProjectID:          h.conversationProjectID(conversationID),
+		UserMessage:        prep.FinalMessage,
+		History:            prep.History,
+		RoleTools:          prep.RoleTools,
+		AgentsMarkdownDir:  h.agentsMarkdownDir,
+		SystemPromptExtra:  h.agentSessionContextBlock(conversationID),
+		AssistantMessageID: assistantMessageID,
+		Progress:           progress,
+	})
+	if err != nil {
+		cause := context.Cause(baseCtx)
+		if errors.Is(cause, ErrTaskCancelled) {
+			taskStatus = "cancelled"
+			h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+			cancelMsg := "任务已被用户取消，后续操作已停止。"
+			if assistantMessageID != "" {
+				if err := h.appendAssistantMessageNotice(assistantMessageID, cancelMsg); err != nil {
+					h.logger.Warn("更新取消后的助手消息失败", zap.Error(err))
+				}
+				_ = h.db.AddProcessDetail(assistantMessageID, conversationID, "cancelled", cancelMsg, nil)
+			}
+			sendEvent("cancelled", cancelMsg, map[string]interface{}{
+				"conversationId": conversationID,
+				"messageId":      assistantMessageID,
+			})
+			sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+			return true
+		}
+		if errors.Is(err, context.DeadlineExceeded) || errors.Is(context.Cause(taskCtx), context.DeadlineExceeded) {
+			taskStatus = "timeout"
+			h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+			timeoutMsg := "任务执行超时，已自动终止。"
+			if assistantMessageID != "" {
+				_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", timeoutMsg, time.Now(), assistantMessageID)
+				_ = h.db.AddProcessDetail(assistantMessageID, conversationID, "timeout", timeoutMsg, nil)
+			}
+			sendEvent("error", timeoutMsg, map[string]interface{}{
+				"conversationId": conversationID,
+				"messageId":      assistantMessageID,
+				"errorType":      "timeout",
+			})
+			sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+			return true
+		}
+		errMsg := "执行角色绑定流程失败: " + err.Error()
+		taskStatus = "failed"
+		h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+		if assistantMessageID != "" {
+			_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", errMsg, time.Now(), assistantMessageID)
+			_ = h.db.AddProcessDetail(assistantMessageID, conversationID, "error", errMsg, nil)
+		}
+		sendEvent("error", errMsg, map[string]interface{}{"conversationId": conversationID})
+		sendEvent("done", "", map[string]interface{}{"conversationId": conversationID})
+		return true
+	}
+	decision := h.finalizeCandidateForDeliveryWithPolicy(
+		prep.ConversationID,
+		prep.AssistantMessageID,
+		"workflow",
+		result.Response,
+		nil,
+		result.AwaitingHITL,
+		"",
+		true,
+	)
+	responseText := decision.FinalText
+	if !decision.Finalizable {
+		responseText = finalizationBlockedMessage(decision)
+		taskStatus = decision.Status
+		h.tasks.UpdateTaskStatus(conversationID, taskStatus)
+		sendEvent("finalization_check", responseText, decision)
+	}
+	payload := finalizationResponsePayload(decision, map[string]interface{}{
+		"conversationId": prep.ConversationID,
+		"messageId":      prep.AssistantMessageID,
+		"agentMode":      "workflow",
+		"workflowRunId":  result.RunID,
+	})
+	if result.AwaitingHITL {
+		payload["workflowStatus"] = "awaiting_hitl"
+		payload["awaitingHitl"] = true
+	} else {
+		payload["workflowStatus"] = result.Status
+		payload["awaitingHitl"] = false
+	}
+	sendEvent("response", responseText, payload)
+	sendEvent("done", "", map[string]interface{}{"conversationId": prep.ConversationID})
+	return true
+}
+
+func (h *AgentHandler) runRoleWorkflowJSONIfBound(c *gin.Context, req *ChatRequest, prep *multiAgentPrepared) bool {
+	role, ok := h.roleForWorkflow(req)
+	if !ok || prep == nil {
+		return false
+	}
+
+	conversationID := prep.ConversationID
+	assistantMessageID := prep.AssistantMessageID
+	userMessage := ""
+	if req != nil {
+		userMessage = req.Message
+	}
+
+	taskStatus := "completed"
+	taskOwned := false
+	defer func() {
+		if taskOwned {
+			h.tasks.FinishTask(conversationID, taskStatus)
+		}
+	}()
+
+	baseCtx, cancelWithCause := context.WithCancelCause(c.Request.Context())
+	defer cancelWithCause(nil)
+	taskCtx, timeoutCancel := context.WithTimeout(baseCtx, 600*time.Minute)
+	defer timeoutCancel()
+
+	if _, err := h.tasks.StartTask(conversationID, userMessage, cancelWithCause); err != nil {
+		if errors.Is(err, ErrTaskAlreadyRunning) {
+			c.JSON(http.StatusConflict, gin.H{
+				"error":          "⚠️ 当前会话已有任务正在执行中，请等待当前任务完成或点击「停止任务」后再尝试。",
+				"conversationId": conversationID,
+				"errorType":      "task_already_running",
+			})
+		} else {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "❌ 无法启动任务: " + err.Error()})
+		}
+		return true
+	}
+	taskOwned = true
+
+	progress := h.createProgressCallback(taskCtx, cancelWithCause, conversationID, assistantMessageID, nil)
+	result, err := workflowrunner.RunRoleBoundWorkflow(taskCtx, workflowrunner.RunArgs{
+		DB:                 h.db,
+		Logger:             h.logger,
+		Role:               role,
+		AppCfg:             h.config,
+		Agent:              h.agent,
+		ConversationID:     conversationID,
+		ProjectID:          h.conversationProjectID(conversationID),
+		UserMessage:        prep.FinalMessage,
+		History:            prep.History,
+		RoleTools:          prep.RoleTools,
+		AgentsMarkdownDir:  h.agentsMarkdownDir,
+		SystemPromptExtra:  h.agentSessionContextBlock(conversationID),
+		AssistantMessageID: assistantMessageID,
+		Progress:           progress,
+	})
+	if err != nil {
+		cause := context.Cause(baseCtx)
+		if errors.Is(cause, ErrTaskCancelled) {
+			taskStatus = "cancelled"
+			cancelMsg := "任务已被用户取消，后续操作已停止。"
+			if assistantMessageID != "" {
+				_ = h.appendAssistantMessageNotice(assistantMessageID, cancelMsg)
+				_ = h.db.AddProcessDetail(assistantMessageID, conversationID, "cancelled", cancelMsg, nil)
+			}
+			c.JSON(http.StatusOK, gin.H{
+				"status":         "cancelled",
+				"message":        cancelMsg,
+				"conversationId": conversationID,
+			})
+			return true
+		}
+		errMsg := "执行角色绑定流程失败: " + err.Error()
+		taskStatus = "failed"
+		if assistantMessageID != "" {
+			_, _ = h.db.Exec("UPDATE messages SET content = ?, updated_at = ? WHERE id = ?", errMsg, time.Now(), assistantMessageID)
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": errMsg, "conversationId": conversationID})
+		return true
+	}
+	decision := h.finalizeCandidateForDeliveryWithPolicy(
+		prep.ConversationID,
+		prep.AssistantMessageID,
+		"workflow",
+		result.Response,
+		nil,
+		result.AwaitingHITL,
+		"",
+		true,
+	)
+	responseText := decision.FinalText
+	if !decision.Finalizable {
+		responseText = finalizationBlockedMessage(decision)
+		taskStatus = decision.Status
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"response":            responseText,
+		"conversationId":      prep.ConversationID,
+		"assistantMessageId":  prep.AssistantMessageID,
+		"agentMode":           "workflow",
+		"workflowRunId":       result.RunID,
+		"workflowStatus":      result.Status,
+		"awaitingHitl":        result.AwaitingHITL,
+		"finalized":           decision.Finalized,
+		"finalizable":         decision.Finalizable,
+		"status":              decision.Status,
+		"completionReason":    decision.CompletionReason,
+		"evidenceVerified":    decision.EvidenceVerified,
+		"evidenceRefs":        decision.EvidenceRefs,
+		"pendingExecutionIds": decision.PendingExecutionIDs,
+		"missingChecks":       decision.MissingChecks,
+	})
+	return true
+}

internal/handler/workflow_package.go

@@ -0,0 +1,319 @@
+package handler
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"mime"
+	"net/http"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+	workflowrunner "cyberstrike-ai/internal/workflow"
+	workflowpkg "cyberstrike-ai/internal/workflow/package"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+type workflowPackageResolution struct {
+	Action        string `json:"action"`
+	NewWorkflowID string `json:"new_workflow_id"`
+}
+type workflowPackageImportRequest struct {
+	InspectionID     string                    `json:"inspection_id"`
+	Resolution       workflowPackageResolution `json:"resolution"`
+	ConfirmOverwrite bool                      `json:"confirm_overwrite"`
+}
+
+func (h *WorkflowHandler) ExportPackage(c *gin.Context) {
+	wf, err := h.db.GetWorkflowDefinition(c.Param("id"))
+	if err != nil {
+		writeWorkflowPackageError(c, http.StatusInternalServerError, "WFPKG_EXPORT_FAILED", "导出工作流包失败", nil)
+		return
+	}
+	if wf == nil {
+		writeWorkflowPackageError(c, http.StatusNotFound, "WFPKG_WORKFLOW_NOT_FOUND", "工作流不存在", nil)
+		return
+	}
+	pkg, meta, err := workflowpkg.Export(workflowPackageDocument(wf))
+	if err != nil {
+		writeWorkflowPackageError(c, http.StatusInternalServerError, "WFPKG_EXPORT_FAILED", "导出工作流包失败", nil)
+		return
+	}
+	c.Header("Content-Type", "application/zip")
+	c.Header("Content-Disposition", mime.FormatMediaType("attachment", map[string]string{"filename": meta.FileName}))
+	c.Header("ETag", `"`+meta.PackageHash+`"`)
+	c.Header("X-Workflow-Package-SHA256", meta.PackageHash)
+	if h.audit != nil {
+		h.audit.RecordOK(c, "workflow_package", "export", "导出工作流包", "workflow", wf.ID, map[string]interface{}{"package_hash": meta.PackageHash})
+	}
+	c.Data(http.StatusOK, "application/zip", pkg)
+}
+
+func (h *WorkflowHandler) CreatePackageInspection(c *gin.Context) {
+	session, ok := security.CurrentSession(c)
+	if !ok || strings.TrimSpace(session.UserID) == "" {
+		writeWorkflowPackageError(c, http.StatusUnauthorized, "WFPKG_INSPECTION_NOT_FOUND", "未授权访问", nil)
+		return
+	}
+	c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, workflowpkg.MaxArchiveBytes+1)
+	file, _, err := c.Request.FormFile("file")
+	if err != nil {
+		var maxErr *http.MaxBytesError
+		if errors.As(err, &maxErr) {
+			writeWorkflowPackageError(c, http.StatusUnprocessableEntity, "WFPKG_FILE_TOO_LARGE", "工作流包文件超过大小限制", nil)
+			return
+		}
+		writeWorkflowPackageError(c, http.StatusUnprocessableEntity, "WFPKG_FILE_REQUIRED", "必须上传工作流包文件", nil)
+		return
+	}
+	defer file.Close()
+	archive, err := io.ReadAll(io.LimitReader(file, workflowpkg.MaxArchiveBytes+1))
+	if err != nil || len(archive) > workflowpkg.MaxArchiveBytes {
+		writeWorkflowPackageError(c, http.StatusUnprocessableEntity, "WFPKG_FILE_TOO_LARGE", "工作流包文件超过大小限制", nil)
+		return
+	}
+	inspected, err := workflowpkg.InspectArchive(c.Request.Context(), archive, workflowrunner.ValidateGraphJSON)
+	if err != nil {
+		code := workflowpkg.ErrorCode(err)
+		if code == "" {
+			code = "WFPKG_INVALID_ARCHIVE"
+		}
+		if h.audit != nil {
+			h.audit.RecordFail(c, "workflow_package", "inspect", "工作流包预检失败", map[string]interface{}{"code": code, "package_hash": workflowPackageHash(archive)})
+		}
+		writeWorkflowPackageError(c, http.StatusUnprocessableEntity, code, "工作流包预检失败", nil)
+		return
+	}
+	state, local, err := h.workflowPackageConflict(inspected.Document.ID, inspected.ContentHash)
+	if err != nil {
+		writeWorkflowPackageError(c, http.StatusInternalServerError, "WFPKG_IMPORT_FAILED", "读取本地工作流失败", nil)
+		return
+	}
+	summary := workflowPackageInspectionSummary{ID: "wpi_" + strings.ReplaceAll(uuid.NewString(), "-", ""), Status: "ready", ExpiresAt: time.Now().UTC().Add(30 * time.Minute), Package: workflowPackagePackageSummary{PackageFormat: inspected.Manifest.PackageFormat, FormatVersion: inspected.Manifest.FormatVersion, PackageID: inspected.Manifest.PackageID, PackageHash: inspected.PackageHash}, Workflow: workflowPackageWorkflowSummary{SourceID: inspected.Document.ID, Name: inspected.Document.Name, Description: inspected.Document.Description, SourceRevision: inspected.Document.Version, Enabled: inspected.Document.Enabled, ContentHash: inspected.ContentHash, GraphHash: inspected.GraphHash, NodeCount: inspected.NodeCount, EdgeCount: inspected.EdgeCount}, Conflict: workflowPackageConflictSummary{State: state}, Warnings: []string{}}
+	if local != nil {
+		content, graph, _, _ := workflowpkg.DocumentHashes(workflowPackageDocument(local))
+		summary.Conflict.LocalWorkflow = &workflowPackageLocalWorkflow{ID: local.ID, Version: local.Version, ContentHash: content, GraphHash: graph}
+	}
+	manifestJSON, _ := json.Marshal(inspected.Manifest)
+	payloadJSON, err := json.Marshal(inspected.Document)
+	if err != nil {
+		writeWorkflowPackageError(c, http.StatusInternalServerError, "WFPKG_IMPORT_FAILED", "保存预检失败", nil)
+		return
+	}
+	inspectionJSON, _ := json.Marshal(summary)
+	record := &database.WorkflowPackageInspection{ID: summary.ID, PackageHash: inspected.PackageHash, ManifestJSON: string(manifestJSON), WorkflowPayloadJSON: string(payloadJSON), InspectionJSON: string(inspectionJSON), SourceWorkflowID: inspected.Document.ID, SourceRevision: inspected.Document.Version, SourceContentHash: inspected.ContentHash, SourceGraphHash: inspected.GraphHash, LocalConflictState: state, CreatedBy: session.UserID, CreatedAt: time.Now().UTC(), ExpiresAt: summary.ExpiresAt}
+	if local != nil {
+		content, graph, _, _ := workflowpkg.DocumentHashes(workflowPackageDocument(local))
+		record.LocalWorkflowID = local.ID
+		record.LocalContentHash = content
+		record.LocalGraphHash = graph
+	}
+	if err := h.db.CreateWorkflowPackageInspection(record); err != nil {
+		writeWorkflowPackageError(c, http.StatusInternalServerError, "WFPKG_IMPORT_FAILED", "保存预检失败", nil)
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordOK(c, "workflow_package", "inspect", "工作流包预检成功", "inspection", record.ID, map[string]interface{}{"package_hash": record.PackageHash, "workflow_id": record.SourceWorkflowID})
+	}
+	c.JSON(http.StatusCreated, gin.H{"inspection": summary})
+}
+
+func (h *WorkflowHandler) GetPackageInspection(c *gin.Context) {
+	session, ok := security.CurrentSession(c)
+	if !ok {
+		writeWorkflowPackageError(c, http.StatusUnauthorized, "WFPKG_INSPECTION_NOT_FOUND", "未授权访问", nil)
+		return
+	}
+	v, err := h.db.GetWorkflowPackageInspection(c.Param("inspectionId"), session.UserID)
+	if err != nil {
+		writeWorkflowPackageError(c, http.StatusInternalServerError, "WFPKG_IMPORT_FAILED", "读取预检失败", nil)
+		return
+	}
+	if v == nil {
+		writeWorkflowPackageError(c, http.StatusNotFound, "WFPKG_INSPECTION_NOT_FOUND", "预检不存在", nil)
+		return
+	}
+	if v.Status == "expired" {
+		writeWorkflowPackageError(c, http.StatusConflict, "WFPKG_INSPECTION_EXPIRED", "预检已过期", nil)
+		return
+	}
+	var summary any
+	_ = json.Unmarshal([]byte(v.InspectionJSON), &summary)
+	c.JSON(http.StatusOK, gin.H{"inspection": summary})
+}
+
+func (h *WorkflowHandler) ApplyPackageImport(c *gin.Context) {
+	session, ok := security.CurrentSession(c)
+	if !ok {
+		writeWorkflowPackageError(c, http.StatusUnauthorized, "WFPKG_INSPECTION_NOT_FOUND", "未授权访问", nil)
+		return
+	}
+	key := strings.TrimSpace(c.GetHeader("Idempotency-Key"))
+	if _, err := uuid.Parse(key); err != nil {
+		writeWorkflowPackageError(c, http.StatusBadRequest, "WFPKG_IDEMPOTENCY_KEY_REQUIRED", "必须提供 UUID 幂等键", nil)
+		return
+	}
+	var req workflowPackageImportRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		writeWorkflowPackageError(c, http.StatusUnprocessableEntity, "WFPKG_INVALID_ACTION", "导入请求无效", nil)
+		return
+	}
+	req.InspectionID = strings.TrimSpace(req.InspectionID)
+	req.Resolution.Action = strings.TrimSpace(req.Resolution.Action)
+	req.Resolution.NewWorkflowID = strings.TrimSpace(req.Resolution.NewWorkflowID)
+	if req.Resolution.Action != "rename" && req.Resolution.NewWorkflowID != "" {
+		writeWorkflowPackageError(c, http.StatusUnprocessableEntity, "WFPKG_INVALID_ACTION", "当前导入动作不接受新工作流 ID", nil)
+		return
+	}
+	requestHash := workflowPackageRequestHash(req)
+	imp, replayed, err := h.db.ApplyWorkflowPackageImport(c.Request.Context(), database.WorkflowPackageApplyRequest{InspectionID: req.InspectionID, RequestHash: requestHash, IdempotencyKey: key, ActorUserID: session.UserID, Action: req.Resolution.Action, NewWorkflowID: req.Resolution.NewWorkflowID, ConfirmOverwrite: req.ConfirmOverwrite})
+	if err != nil {
+		h.writeWorkflowPackageImportError(c, req.InspectionID, err)
+		return
+	}
+	wf, _ := h.db.GetWorkflowDefinition(imp.ResultingWorkflowID)
+	if !replayed && (imp.Result == "created" || imp.Result == "overwritten" || imp.Result == "renamed") {
+		workflowrunner.InvalidateCompiledCache(imp.ResultingWorkflowID)
+	}
+	response := h.workflowPackageImportResponse(imp, wf)
+	if !replayed && h.audit != nil {
+		h.audit.RecordOK(c, "workflow_package", "import", "工作流包导入成功", "workflow", imp.ResultingWorkflowID, map[string]interface{}{"inspection_id": imp.InspectionID, "action": imp.Action, "result": imp.Result})
+	}
+	status := http.StatusCreated
+	if replayed {
+		status = http.StatusOK
+	}
+	c.JSON(status, gin.H{"import": response})
+}
+
+func (h *WorkflowHandler) GetPackageImport(c *gin.Context) {
+	session, ok := security.CurrentSession(c)
+	if !ok {
+		writeWorkflowPackageError(c, http.StatusUnauthorized, "WFPKG_INSPECTION_NOT_FOUND", "未授权访问", nil)
+		return
+	}
+	imp, err := h.db.GetWorkflowPackageImport(c.Param("importId"), session.UserID)
+	if err != nil {
+		writeWorkflowPackageError(c, http.StatusInternalServerError, "WFPKG_IMPORT_FAILED", "读取导入结果失败", nil)
+		return
+	}
+	if imp == nil {
+		writeWorkflowPackageError(c, http.StatusNotFound, "WFPKG_INSPECTION_NOT_FOUND", "导入结果不存在", nil)
+		return
+	}
+	wf, _ := h.db.GetWorkflowDefinition(imp.ResultingWorkflowID)
+	c.JSON(http.StatusOK, gin.H{"import": h.workflowPackageImportResponse(imp, wf)})
+}
+
+func (h *WorkflowHandler) workflowPackageConflict(id, sourceHash string) (string, *database.WorkflowDefinition, error) {
+	local, err := h.db.GetWorkflowDefinition(id)
+	if err != nil {
+		return "", nil, err
+	}
+	if local == nil {
+		return "none", nil, nil
+	}
+	localHash, _, _, err := workflowpkg.DocumentHashes(workflowPackageDocument(local))
+	if err != nil {
+		return "", nil, err
+	}
+	if localHash == sourceHash {
+		return "identical", local, nil
+	}
+	return "id_conflict", local, nil
+}
+func workflowPackageDocument(w *database.WorkflowDefinition) workflowpkg.Document {
+	return workflowpkg.Document{ID: w.ID, Name: w.Name, Description: w.Description, Version: w.Version, GraphJSON: w.GraphJSON, Enabled: w.Enabled, UpdatedAt: w.UpdatedAt}
+}
+func workflowPackageRequestHash(req workflowPackageImportRequest) string {
+	value := struct {
+		ConfirmOverwrite bool                      `json:"confirm_overwrite"`
+		InspectionID     string                    `json:"inspection_id"`
+		Resolution       workflowPackageResolution `json:"resolution"`
+	}{req.ConfirmOverwrite, req.InspectionID, req.Resolution}
+	b, _ := json.Marshal(value)
+	sum := sha256.Sum256(b)
+	return "sha256:" + hex.EncodeToString(sum[:])
+}
+func workflowPackageHash(b []byte) string {
+	sum := sha256.Sum256(b)
+	return "sha256:" + hex.EncodeToString(sum[:])
+}
+
+func (h *WorkflowHandler) writeWorkflowPackageImportError(c *gin.Context, inspectionID string, err error) {
+	var e *database.WorkflowPackageStoreError
+	if errors.As(err, &e) {
+		status := http.StatusConflict
+		if e.Code == "WFPKG_INVALID_ACTION" || e.Code == "WFPKG_INVALID_RENAME_ID" {
+			status = http.StatusUnprocessableEntity
+		}
+		if h.audit != nil {
+			h.audit.RecordFail(c, "workflow_package", "import", "工作流包导入失败", map[string]interface{}{"code": e.Code, "inspection_id": inspectionID})
+		}
+		writeWorkflowPackageError(c, status, e.Code, e.Message, nil)
+		return
+	}
+	if h.audit != nil {
+		h.audit.RecordFail(c, "workflow_package", "import", "工作流包导入失败", map[string]interface{}{"code": "WFPKG_IMPORT_FAILED", "inspection_id": inspectionID})
+	}
+	writeWorkflowPackageError(c, http.StatusInternalServerError, "WFPKG_IMPORT_FAILED", "导入工作流包失败", nil)
+}
+func writeWorkflowPackageError(c *gin.Context, status int, code, message string, details map[string]any) {
+	body := gin.H{"code": code, "message": message}
+	if len(details) > 0 {
+		body["details"] = details
+	}
+	c.JSON(status, gin.H{"error": body})
+}
+
+type workflowPackageInspectionSummary struct {
+	ID        string                         `json:"id"`
+	Status    string                         `json:"status"`
+	ExpiresAt time.Time                      `json:"expires_at"`
+	Package   workflowPackagePackageSummary  `json:"package"`
+	Workflow  workflowPackageWorkflowSummary `json:"workflow"`
+	Conflict  workflowPackageConflictSummary `json:"conflict"`
+	Warnings  []string                       `json:"warnings"`
+}
+type workflowPackagePackageSummary struct {
+	PackageFormat string `json:"package_format"`
+	FormatVersion string `json:"format_version"`
+	PackageID     string `json:"package_id"`
+	PackageHash   string `json:"package_hash"`
+}
+type workflowPackageWorkflowSummary struct {
+	SourceID       string `json:"source_id"`
+	Name           string `json:"name"`
+	Description    string `json:"description"`
+	SourceRevision int    `json:"source_revision"`
+	Enabled        bool   `json:"enabled"`
+	ContentHash    string `json:"content_hash"`
+	GraphHash      string `json:"graph_hash"`
+	NodeCount      int    `json:"node_count"`
+	EdgeCount      int    `json:"edge_count"`
+}
+type workflowPackageConflictSummary struct {
+	State         string                        `json:"state"`
+	LocalWorkflow *workflowPackageLocalWorkflow `json:"local_workflow,omitempty"`
+}
+type workflowPackageLocalWorkflow struct {
+	ID          string `json:"id"`
+	Version     int    `json:"version"`
+	ContentHash string `json:"content_hash"`
+	GraphHash   string `json:"graph_hash"`
+}
+
+func (h *WorkflowHandler) workflowPackageImportResponse(imp *database.WorkflowPackageImport, wf *database.WorkflowDefinition) gin.H {
+	out := gin.H{"id": imp.ID, "inspection_id": imp.InspectionID, "status": "succeeded", "result": imp.Result, "action": imp.Action, "source_workflow_id": imp.SourceWorkflowID, "target_workflow_id": imp.TargetWorkflowID, "applied_at": imp.AppliedAt}
+	if wf != nil {
+		content, graph, _, _ := workflowpkg.DocumentHashes(workflowPackageDocument(wf))
+		out["workflow"] = gin.H{"id": wf.ID, "version": wf.Version, "content_hash": content, "graph_hash": graph}
+	}
+	return out
+}

internal/handler/workflow_package_test.go

@@ -0,0 +1,104 @@
+package handler
+
+import (
+	"bytes"
+	"encoding/json"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+	workflowrunner "cyberstrike-ai/internal/workflow"
+	workflowpkg "cyberstrike-ai/internal/workflow/package"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"go.uber.org/zap"
+)
+
+func TestWorkflowPackageHandlerInspectionAndCreateImport(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	workflowrunner.SetCheckpointDir(filepath.Join(t.TempDir(), "workflow-checkpoints"))
+	db, err := database.NewDB(filepath.Join(t.TempDir(), "workflow-package-handler.db"), zap.NewNop())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	h := NewWorkflowHandler(db, zap.NewNop())
+	pkg, _, err := workflowpkg.Export(workflowpkg.Document{ID: "wf-api", Name: "API workflow", Version: 4, Enabled: true, UpdatedAt: time.Now().UTC(), GraphJSON: `{"nodes":[{"id":"start-1","type":"start","label":"开始","position":{"x":0,"y":0},"config":{}},{"id":"out-1","type":"output","label":"输出","position":{"x":0,"y":120},"config":{"output_key":"result","source_binding":{"from":"inputs","field":"message"}}}],"edges":[{"id":"e1","source":"start-1","target":"out-1"}],"config":{"schema_version":1}}`})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var body bytes.Buffer
+	writer := multipart.NewWriter(&body)
+	part, err := writer.CreateFormFile("file", "wf-api.csapkg.zip")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := part.Write(pkg); err != nil {
+		t.Fatal(err)
+	}
+	if err := writer.Close(); err != nil {
+		t.Fatal(err)
+	}
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodPost, "/api/workflow-package-inspections", &body)
+	c.Request.Header.Set("Content-Type", writer.FormDataContentType())
+	c.Set(security.ContextSessionKey, security.Session{UserID: "user-1"})
+	h.CreatePackageInspection(c)
+	if w.Code != http.StatusCreated {
+		t.Fatalf("inspection status=%d body=%s", w.Code, w.Body.String())
+	}
+	var inspected struct {
+		Inspection struct {
+			ID string `json:"id"`
+		} `json:"inspection"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &inspected); err != nil {
+		t.Fatal(err)
+	}
+	applyBody := bytes.NewBufferString(`{"inspection_id":"` + inspected.Inspection.ID + `","resolution":{"action":"create","new_workflow_id":""},"confirm_overwrite":false}`)
+	w = httptest.NewRecorder()
+	c, _ = gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodPost, "/api/workflow-package-imports", applyBody)
+	c.Request.Header.Set("Content-Type", "application/json")
+	c.Request.Header.Set("Idempotency-Key", uuid.NewString())
+	c.Set(security.ContextSessionKey, security.Session{UserID: "user-1"})
+	h.ApplyPackageImport(c)
+	if w.Code != http.StatusCreated {
+		t.Fatalf("import status=%d body=%s", w.Code, w.Body.String())
+	}
+	saved, _ := db.GetWorkflowDefinition("wf-api")
+	if saved == nil || saved.Version != 1 {
+		t.Fatalf("saved=%#v", saved)
+	}
+}
+
+func TestWorkflowHandlerGenerateDraft(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	h := NewWorkflowHandler(nil, zap.NewNop())
+	body := bytes.NewBufferString(`{"prompt":"对目标资产做端口扫描，如果发现高危端口就执行加固脚本，最后输出报告","options":{"include_objective":true},"available_tools":[{"key":"nmap","name":"nmap","enabled":true}]}`)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodPost, "/api/workflows/generate-draft", body)
+	c.Request.Header.Set("Content-Type", "application/json")
+	h.GenerateDraft(c)
+	if w.Code != http.StatusBadGateway {
+		t.Fatalf("status=%d body=%s", w.Code, w.Body.String())
+	}
+	var resp struct {
+		Error string `json:"error"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(resp.Error, "大模型生成失败") {
+		t.Fatalf("unexpected error: %#v", resp.Error)
+	}
+}

internal/handler/workflow_run.go

@@ -0,0 +1,200 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+	"time"
+
+	"cyberstrike-ai/internal/agent"
+	"cyberstrike-ai/internal/config"
+	"cyberstrike-ai/internal/database"
+	"cyberstrike-ai/internal/security"
+	workflowrunner "cyberstrike-ai/internal/workflow"
+
+	"github.com/gin-gonic/gin"
+)
+
+func (h *WorkflowHandler) SetRuntime(agent *agent.Agent, cfg *config.Config) {
+	h.agent = agent
+	h.cfg = cfg
+}
+
+func (h *WorkflowHandler) GetRun(c *gin.Context) {
+	runID := strings.TrimSpace(c.Param("runId"))
+	if !h.workflowRunAllowed(c, runID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+	run, err := h.db.GetWorkflowRun(runID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if run == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "工作流运行不存在"})
+		return
+	}
+	nodeRuns, err := h.db.ListWorkflowNodeRuns(runID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"run": run, "nodeRuns": nodeRuns})
+}
+
+func (h *WorkflowHandler) ReplayRun(c *gin.Context) {
+	runID := strings.TrimSpace(c.Param("runId"))
+	if !h.workflowRunAllowed(c, runID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+	nodeRuns, err := h.db.ListWorkflowNodeRuns(runID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	steps := make([]gin.H, 0, len(nodeRuns))
+	for i, nodeRun := range nodeRuns {
+		var input any
+		var output any
+		_ = json.Unmarshal([]byte(nodeRun.InputJSON), &input)
+		_ = json.Unmarshal([]byte(nodeRun.OutputJSON), &output)
+		steps = append(steps, gin.H{
+			"step":       i + 1,
+			"nodeRunId":  nodeRun.ID,
+			"nodeId":     nodeRun.NodeID,
+			"status":     nodeRun.Status,
+			"input":      input,
+			"output":     output,
+			"error":      nodeRun.Error,
+			"startedAt":  nodeRun.StartedAt,
+			"finishedAt": nodeRun.FinishedAt,
+		})
+	}
+	c.JSON(http.StatusOK, gin.H{"workflowRunId": runID, "steps": steps})
+}
+
+func (h *WorkflowHandler) ListPendingRuns(c *gin.Context) {
+	conversationID := strings.TrimSpace(c.Query("conversationId"))
+	if conversationID != "" && !h.workflowConversationAllowed(c, conversationID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+	runs, err := h.db.ListWorkflowRunsAwaitingHITLFiltered(conversationID, 50)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	runs = filterSlice(runs, func(run *database.WorkflowRun) bool {
+		return run != nil && h.workflowConversationAllowed(c, run.ConversationID)
+	})
+	c.JSON(http.StatusOK, gin.H{"runs": runs})
+}
+
+type workflowResumeRequest struct {
+	Approved bool   `json:"approved"`
+	Comment  string `json:"comment,omitempty"`
+}
+
+func (h *WorkflowHandler) ResumeRun(c *gin.Context) {
+	if h.agent == nil || h.cfg == nil {
+		c.JSON(http.StatusServiceUnavailable, gin.H{"error": "工作流运行时未初始化"})
+		return
+	}
+	runID := strings.TrimSpace(c.Param("runId"))
+	if !h.workflowRunAllowed(c, runID) {
+		c.JSON(http.StatusForbidden, gin.H{"error": "无权访问该资源"})
+		return
+	}
+	var req workflowResumeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "无效的请求参数: " + err.Error()})
+		return
+	}
+	run, err := h.db.GetWorkflowRun(runID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	if run == nil {
+		c.JSON(http.StatusNotFound, gin.H{"error": "工作流运行不存在"})
+		return
+	}
+	role := config.RoleConfig{Name: strings.TrimSpace(run.RoleID)}
+	if role.Name != "" && h.cfg.Roles != nil {
+		if r, ok := h.cfg.Roles[role.Name]; ok {
+			role = r
+			if role.Name == "" {
+				role.Name = run.RoleID
+			}
+		}
+	}
+	if run.Status != "awaiting_hitl" {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "工作流运行不在等待审批状态: " + run.Status})
+		return
+	}
+	if err := h.db.RecordWorkflowRunHITLDecision(runID, req.Approved, req.Comment); err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	decision := workflowrunner.HITLDecision{
+		Approved: req.Approved,
+		Comment:  strings.TrimSpace(req.Comment),
+	}
+	delegated := workflowrunner.NotifyHITLDecision(runID, decision)
+	if !delegated {
+		for i := 0; i < 10; i++ {
+			time.Sleep(50 * time.Millisecond)
+			if workflowrunner.NotifyHITLDecision(runID, decision) {
+				delegated = true
+				break
+			}
+		}
+	}
+	if delegated {
+		c.JSON(http.StatusOK, gin.H{
+			"workflowRunId":  runID,
+			"status":         "delegated",
+			"streamResuming": true,
+			"approved":       req.Approved,
+		})
+		return
+	}
+	result, err := workflowrunner.ResumeWorkflowRun(c.Request.Context(), workflowrunner.RunArgs{
+		DB:             h.db,
+		Logger:         h.logger,
+		Role:           role,
+		AppCfg:         h.cfg,
+		Agent:          h.agent,
+		ConversationID: run.ConversationID,
+		ProjectID:      run.ProjectID,
+	}, runID, req.Approved, req.Comment)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{
+		"response":      result.Response,
+		"workflowRunId": result.RunID,
+		"status":        result.Status,
+		"awaitingHitl":  result.AwaitingHITL,
+	})
+}
+
+func (h *WorkflowHandler) workflowConversationAllowed(c *gin.Context, conversationID string) bool {
+	session, ok := security.CurrentSession(c)
+	return ok && h.db.UserCanAccessResource(session.UserID, session.Scope, "conversation", strings.TrimSpace(conversationID))
+}
+
+func (h *WorkflowHandler) workflowRunAllowed(c *gin.Context, runID string) bool {
+	session, ok := security.CurrentSession(c)
+	if !ok {
+		return false
+	}
+	if session.Scope == database.RBACScopeAll {
+		return true
+	}
+	run, err := h.db.GetWorkflowRun(strings.TrimSpace(runID))
+	return err == nil && run != nil && h.workflowConversationAllowed(c, run.ConversationID)
+}