Implement the backend: store/bus/runmgr core

Details (original message):
Implement the backend: store/bus/runmgr core, mock and LLM runners (agent-native client), HITL three-branch routing, subagent runs, builtin and declarative HTTP tools, ingest parsers (md/txt/docx/pdf-text), knowledge fulltext, layered settings, profiles, plugin host, REST+SSE API, single-binary entrypoint; e2e and unit tests.

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "deps/agent-system-core"]
+	path = deps/agent-system-core
+	url = ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-System-Core.git
+[submodule "deps/agent-native"]
+	path = deps/agent-native
+	url = ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-Native.git

PROJECT.md

@@ -4,3 +4,10 @@
 - 技术栈：Go（静态链接，CGO_ENABLED=0）
 - 构建/验证：见仓内 Makefile 或 Dev 仓顶层 Makefile（待 P1 起补充并保持本节同步）。
 - 状态：P0 骨架；当前阶段见 Dev 仓任务记录。
+
+## 验证（P1–P4 状态）
+
+- `go test ./...` — 单元 + 端到端（mock runner 全链路：流式/折叠部件/HITL 三分支/子代理任务树/工件/上传解析/中文检索/SSE 在线与重放/命令路由/插件装卸 fail-closed）。
+- `CGO_ENABLED=0 go build ./cmd/agent-system` — 单二进制（静态，内嵌前端后）。
+- 存储：嵌入式 SQLite（modernc.org/sqlite，纯 Go）；FTS5 全文 + CJK LIKE 兜底。
+- 依赖：agent-system-core（deps submodule + replace）、agent-native（runtime/llm 复用）。

cmd/agent-system/main.go

@@ -0,0 +1,36 @@
+// agent-system：单二进制服务（HTTP/SSE + 内嵌前端 + 嵌入式 SQLite）。
+// 部署约束（设计 4.1 原则 8）：非容器化；拷贝即运行。
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+
+	"agent-system-backend/internal/app"
+)
+
+var version = "0.1.0-dev"
+
+func main() {
+	if len(os.Args) > 1 {
+		switch os.Args[1] {
+		case "version", "--version":
+			fmt.Println("agent-system", version)
+			return
+		case "serve":
+			os.Args = append([]string{os.Args[0]}, os.Args[2:]...)
+		}
+	}
+	fs := flag.NewFlagSet("serve", flag.ExitOnError)
+	addr := fs.String("addr", "127.0.0.1:8787", "监听地址")
+	data := fs.String("data", "./data", "数据目录（SQLite 与工件对象目录）")
+	pluginsDir := fs.String("plugins", "./plugins", "插件目录（声明资产热加载）")
+	mock := fs.Bool("mock", false, "演示模式（等同 runtime.mock=true，不调用模型）")
+	fs.Parse(os.Args[1:])
+
+	if err := app.Run(app.Options{Addr: *addr, DataDir: *data, PluginsDir: *pluginsDir, ForceMock: *mock}); err != nil {
+		fmt.Fprintln(os.Stderr, "agent-system:", err)
+		os.Exit(1)
+	}
+}

go.mod

@@ -0,0 +1,26 @@
+module agent-system-backend
+
+go 1.27
+
+replace agent-system-core => ./deps/agent-system-core
+
+replace agent-native => ./deps/agent-native
+
+require (
+	agent-native v0.0.0-00010101000000-000000000000
+	agent-system-core v0.0.0-00010101000000-000000000000
+	modernc.org/sqlite v1.60.1
+)
+
+require (
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/ledongthuc/pdf v0.0.0-20260907135840-6c8c28e0e8a0 // indirect
+	github.com/mattn/go-isatty v0.0.24 // indirect
+	github.com/ncruces/go-strftime v1.0.0 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	golang.org/x/sys v0.48.0 // indirect
+	modernc.org/libc v1.77.1 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.12.1 // indirect
+)

go.sum

@@ -0,0 +1,52 @@
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo=
+github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/ledongthuc/pdf v0.0.0-20260907135840-6c8c28e0e8a0 h1:7Q+xNAZFmnfYOMweHN3c/PDFUKKfY1pVJ26K++QvVfU=
+github.com/ledongthuc/pdf v0.0.0-20260907135840-6c8c28e0e8a0/go.mod h1:1fEHWurg7pvf5SG6XNE5Q8UZmOwex51Mkx3SLhrW5B4=
+github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
+github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
+github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
+github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+golang.org/x/mod v0.41.0 h1:qJmnOUb4YB+FsEuM3HcWucdZASCPGhsX6uljO6pog0c=
+golang.org/x/mod v0.41.0/go.mod h1:Ek9pY8RKWXwsWvd3rQiHYtMqkjSUV+s1Rj7j4H5Ur6o=
+golang.org/x/sync v0.23.0 h1:KameEIfc1IkluZyXWLn39Wd4tURc6GbCiISGiZm2bQk=
+golang.org/x/sync v0.23.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
+golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
+golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
+golang.org/x/tools v0.50.0 h1:c2ifzfcuY7L90lZ2aKd8S4K2NpASF08SZx9ZuJkHmSU=
+golang.org/x/tools v0.50.0/go.mod h1:7ulVMw3831Mwi5EZD6RomGyffr4VFjuNYXf2BbCEAV0=
+modernc.org/cc/v4 v4.29.7 h1:q+NXGJ0bK3b4TXFYQQVr9pYETGnmwFWkrUzJnMya/Tg=
+modernc.org/cc/v4 v4.29.7/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
+modernc.org/ccgo/v4 v4.36.1 h1:ZNIUZAryN0UgnJwtyxrdEzcFc3yD4Cu4AzjfPXsLsIE=
+modernc.org/ccgo/v4 v4.36.1/go.mod h1:rrtGc2QkS239nYb/mQNuBMyjq3/y3ZXWbBjPoV3wqzA=
+modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM=
+modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU=
+modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI=
+modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito=
+modernc.org/gc/v3 v3.1.5 h1:21ldfPfRYE31Tb7B3mwAK8gy1AxP4+dKjrOQPfqakoc=
+modernc.org/gc/v3 v3.1.5/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY=
+modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks=
+modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI=
+modernc.org/libc v1.77.1 h1:Ct8j47QtiZ1Enj2DtFXQtUqrPCAjdCmPjtCuvrYQ0Hs=
+modernc.org/libc v1.77.1/go.mod h1:87/pZ4L6nD1zqW4nItuS12YO7hN1igAah34xjnQo/W0=
+modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU=
+modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg=
+modernc.org/memory v1.12.1 h1:nFMiWrpStgZczNl6XI9GnIk/rWhYIyHGUaR04pGbp9g=
+modernc.org/memory v1.12.1/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw=
+modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg=
+modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns=
+modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w=
+modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE=
+modernc.org/sqlite v1.60.1 h1:/blz53O951KWFOso4QQvEs/Fq6cDBKLtMVrYNSeJVKw=
+modernc.org/sqlite v1.60.1/go.mod h1:1dIoEagfDE72QytD5scH1lxARtaUgKgHC/NuApA27r0=
+modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0=
+modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=

internal/app/app.go

@@ -0,0 +1,93 @@
+// Package app 组合根：装配存储、总线、注册表、服务、runmgr、插件宿主与 HTTP 服务。
+package app
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"syscall"
+	"time"
+
+	core "agent-system-core"
+	"agent-system-backend/internal/bus"
+	"agent-system-backend/internal/plugins"
+	"agent-system-backend/internal/profiles"
+	"agent-system-backend/internal/runmgr"
+	"agent-system-backend/internal/runtime"
+	"agent-system-backend/internal/server"
+	"agent-system-backend/internal/settings"
+	"agent-system-backend/internal/store"
+	"agent-system-backend/internal/tools"
+)
+
+type Options struct {
+	Addr        string
+	DataDir     string
+	PluginsDir  string
+	ForceMock   bool
+}
+
+// Run 装配并阻塞服务直至 SIGINT/SIGTERM（优雅停机：中断在途 run）。
+func Run(opt Options) error {
+	dbPath := filepath.Join(opt.DataDir, "agent-system.db")
+	st, err := store.Open(dbPath)
+	if err != nil {
+		return fmt.Errorf("open store: %w", err)
+	}
+	defer st.Close()
+
+	b := bus.New()
+	reg := tools.NewRegistry()
+	if err := reg.RegisterBuiltin(); err != nil {
+		return fmt.Errorf("builtin tools: %w", err)
+	}
+	setSvc := settings.NewService(st)
+	profSvc := profiles.New(st)
+	if err := profSvc.EnsureDefault(); err != nil {
+		return fmt.Errorf("default profile: %w", err)
+	}
+	if opt.ForceMock {
+		if err := setSvc.MergeUser(map[string]any{"runtime": map[string]any{"mock": true}}); err != nil {
+			return err
+		}
+	}
+
+	convRunner := &runtime.LLMRunner{}
+	subRunner := &runtime.SubLLMRunner{}
+	mockRunner := &runtime.MockRunner{}
+	mgr := runmgr.New(st, b, reg, profSvc, setSvc, convRunner, subRunner, mockRunner, &runtime.MockSubagent{})
+
+	pluginHost := plugins.New(st, reg, setSvc, opt.PluginsDir)
+	for id, err := range pluginHost.LoadDir() {
+		if err != nil {
+			log.Printf("[plugins] %s: %v", id, err) // fail-closed：单个失败不阻断启动
+		}
+	}
+
+	srv := server.New(st, mgr, reg, profSvc, setSvc, pluginHost)
+	srv.Subscribe = func(conversationID string) (<-chan core.StreamEvent, func()) {
+		return b.Subscribe(conversationID)
+	}
+
+	httpSrv := &http.Server{Addr: opt.Addr, Handler: srv.Handler(), ReadHeaderTimeout: 10 * time.Second}
+
+	go func() {
+		log.Printf("agent-system serving on http://%s (data: %s, plugins: %s)", opt.Addr, opt.DataDir, opt.PluginsDir)
+		if err := httpSrv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			log.Fatalf("http: %v", err)
+		}
+	}()
+
+	stop := make(chan os.Signal, 1)
+	signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
+	<-stop
+	log.Printf("shutting down…")
+	mgr.InterruptRunning()
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	return httpSrv.Shutdown(ctx)
+}

internal/bus/bus.go

@@ -0,0 +1,52 @@
+// Package bus 是 streamhub：按会话分发已持久化的事件（SSE 通道）。
+// 事件权威在 store（seq 游标）；bus 只做在线转发，溢出丢弃由客户端从游标重放补偿。
+package bus
+
+import (
+	"sync"
+
+	core "agent-system-core"
+)
+
+type subscriber struct {
+	ch     chan core.StreamEvent
+	filter string // conversationID；空 = 全部
+}
+
+type Bus struct {
+	mu   sync.Mutex
+	subs map[int64]*subscriber
+	next int64
+}
+
+func New() *Bus { return &Bus{subs: map[int64]*subscriber{}} }
+
+// Subscribe 返回新订阅；close(unsubscribe) 注销。
+func (b *Bus) Subscribe(conversationID string) (<-chan core.StreamEvent, func()) {
+	b.mu.Lock()
+	id := b.next
+	b.next++
+	ch := make(chan core.StreamEvent, 512)
+	b.subs[id] = &subscriber{ch: ch, filter: conversationID}
+	b.mu.Unlock()
+	return ch, func() {
+		b.mu.Lock()
+		delete(b.subs, id)
+		b.mu.Unlock()
+	}
+}
+
+// Publish 非阻塞广播；满则丢（客户端 Last-Event-ID 重放补齐）。
+func (b *Bus) Publish(e core.StreamEvent) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	for _, s := range b.subs {
+		if s.filter != "" && s.filter != e.ConversationID {
+			continue
+		}
+		select {
+		case s.ch <- e:
+		default:
+		}
+	}
+}

internal/ctxasm/ctxasm.go

@@ -0,0 +1,116 @@
+// Package ctxasm 实现上下文组装与预算管理（4.10）：分层管线 + 可观测裁剪记录。
+package ctxasm
+
+import (
+	"fmt"
+	"strings"
+
+	agentllm "agent-native/runtime/llm"
+	core "agent-system-core"
+)
+
+// Report 记录一次组装的实际构成（可观测：模型看到了什么、裁了什么）。
+type Report struct {
+	Items      []string `json:"items"`
+	Truncations []string `json:"truncations,omitempty"`
+	EstChars   int      `json:"estChars"`
+}
+
+// AssembleInput 组装模型输入消息。
+func AssembleInput(prof core.AgentProfile, eff core.EffectiveSettings, history []core.Message, currentUser core.Message, attachments []core.ParsedDocument, knowledge []core.RetrievalHit) ([]agentllm.Message, *Report) {
+	rep := &Report{}
+	msgs := []agentllm.Message{{Role: agentllm.RoleSystem, Content: prof.SystemPrompt}}
+	rep.Items = append(rep.Items, "system(画像)")
+
+	maxHist := prof.Context.MaxHistoryMessages
+	if maxHist <= 0 {
+		maxHist = int(eff.GetNumber("context.maxHistoryMessages", 40))
+	}
+	if maxHist <= 0 {
+		maxHist = 40
+	}
+	// 历史窗口（不含当前轮——当前轮单独注入附件与检索）。
+	start := 0
+	if len(history) > maxHist {
+		start = len(history) - maxHist
+		rep.Truncations = append(rep.Truncations, fmt.Sprintf("历史 %d 条超窗口 %d，仅保留最近部分", len(history), maxHist))
+	}
+	for _, m := range history[start:] {
+		if m.ID == currentUser.ID {
+			continue
+		}
+		content := renderMessage(m)
+		if content == "" {
+			continue
+		}
+		role := agentllm.RoleUser
+		if m.Role == core.RoleAssistant {
+			role = agentllm.RoleAssistant
+		}
+		msgs = append(msgs, agentllm.Message{Role: role, Content: content})
+	}
+	rep.Items = append(rep.Items, fmt.Sprintf("history(%d)", len(history)-start))
+
+	// 当前轮：文本 + 附件解析结果 + 知识检索注入。
+	var sb strings.Builder
+	for _, p := range currentUser.Parts {
+		if p.Type == core.PartText {
+			sb.WriteString(p.Text)
+		}
+	}
+	if len(attachments) > 0 {
+		sb.WriteString("\n\n[附件]\n")
+		for _, doc := range attachments {
+			text := doc.PlainText()
+			limit := 16000
+			if len(text) > limit {
+				text = text[:limit] + "…（附件超长截断）"
+				rep.Truncations = append(rep.Truncations, "附件 "+doc.Meta.Filename+" 超长截断")
+			}
+			fmt.Fprintf(&sb, "### %s\n%s\n", doc.Meta.Filename, text)
+		}
+		rep.Items = append(rep.Items, fmt.Sprintf("attachments(%d)", len(attachments)))
+	}
+	if len(knowledge) > 0 {
+		sb.WriteString("\n\n[相关知识]\n")
+		for i, h := range knowledge {
+			fmt.Fprintf(&sb, "[%d] %s（来源 %s）\n%s\n", i+1, h.Doc.Title, h.Doc.Source, h.Doc.Chunk)
+		}
+		rep.Items = append(rep.Items, fmt.Sprintf("knowledge(%d)", len(knowledge)))
+	}
+	msgs = append(msgs, agentllm.Message{Role: agentllm.RoleUser, Content: sb.String()})
+
+	for _, m := range msgs {
+		rep.EstChars += len(m.Content)
+	}
+	return msgs, rep
+}
+
+// renderMessage 把消息部件渲染为模型可读文本（思考部件不回灌；工具结果给摘要）。
+func renderMessage(m core.Message) string {
+	var sb strings.Builder
+	for _, p := range m.Parts {
+		switch p.Type {
+		case core.PartText:
+			sb.WriteString(p.Text)
+			sb.WriteString("\n")
+		case core.PartToolCall:
+			if p.ToolCall != nil {
+				fmt.Fprintf(&sb, "[调用工具 %s(%s)]\n", p.ToolCall.Name, p.ToolCall.Arguments)
+			}
+		case core.PartToolResult:
+			if p.ToolResult != nil {
+				fmt.Fprintf(&sb, "[工具结果 %s %s]\n", p.ToolResult.Status, p.ToolResult.Summary)
+			}
+		case core.PartArtifactRef:
+			if p.Artifact != nil {
+				fmt.Fprintf(&sb, "[产出工件 %s]\n", p.Artifact.Name)
+			}
+		case core.PartHITL:
+			if p.Hitl != nil && p.Hitl.Resolved {
+				fmt.Fprintf(&sb, "[用户确认：%s → %s]\n", p.Hitl.Question, p.Hitl.Answer)
+			}
+		}
+	}
+	return strings.TrimSpace(sb.String())
+}

internal/ingest/ingest.go

@@ -0,0 +1,313 @@
+// Package ingest 实现文档摄取与解析（4.11）：上传/工件 → ParsedDocument IR。
+// 主路线为内置代码解析器（确定性、纯 Go、可独立测试）；MinerU 深度解析与
+// agent 驱动解析为远期档位（ParserProvider 注册位已留）。
+package ingest
+
+import (
+	"archive/zip"
+	"bytes"
+	"encoding/xml"
+	"fmt"
+	"io"
+	"path/filepath"
+	"strings"
+	"time"
+
+	pdflib "github.com/ledongthuc/pdf"
+	core "agent-system-core"
+)
+
+// Parse 按扩展名分派内置解析器；无法解析时返回带 warning 的空文档（显式失败，不静默）。
+func Parse(filename, mime string, content []byte) core.ParsedDocument {
+	doc := core.ParsedDocument{Meta: core.DocMeta{
+		Filename: filename, MIME: mime, Parser: "builtin", ParsedAt: time.Now().UTC(),
+	}}
+	ext := strings.ToLower(strings.TrimPrefix(filepath.Ext(filename), "."))
+	switch ext {
+	case "md", "markdown":
+		doc.Meta.Parser = "builtin:md"
+		doc.Blocks = parseMarkdown(string(content))
+		doc.Meta.Confidence = 1.0
+	case "txt", "text", "log", "csv":
+		doc.Meta.Parser = "builtin:txt"
+		doc.Blocks = parsePlain(string(content))
+		doc.Meta.Confidence = 1.0
+	case "docx":
+		doc.Meta.Parser = "builtin:docx"
+		blocks, err := parseDocx(content)
+		if err != nil {
+			doc.Warnings = append(doc.Warnings, "docx 解析失败："+err.Error())
+			doc.Meta.Confidence = 0.3
+		} else {
+			doc.Blocks = blocks
+			doc.Meta.Confidence = 0.92
+		}
+	case "pdf":
+		doc.Meta.Parser = "builtin:pdf"
+		blocks, err := parsePDF(content)
+		if err != nil {
+			doc.Warnings = append(doc.Warnings, "pdf 文本层解析失败："+err.Error()+"（扫描件需远期 MinerU 档）")
+			doc.Meta.Confidence = 0.2
+		} else {
+			doc.Blocks = blocks
+			doc.Meta.Confidence = 0.85
+		}
+	default:
+		if isImage(ext) {
+			doc.Warnings = append(doc.Warnings, "图片不走文本解析（OCR 为 MinerU 深度档，远期）")
+		} else {
+			// 未知类型按纯文本尝试（二进制内容会产生乱码 warning）。
+			text := string(content)
+			if !isMostlyPrintable(text) {
+				doc.Warnings = append(doc.Warnings, fmt.Sprintf("未知类型 .%s 且内容非文本，未解析", ext))
+			} else {
+				doc.Blocks = parsePlain(text)
+				doc.Meta.Confidence = 0.6
+				doc.Warnings = append(doc.Warnings, "未知类型按纯文本解析")
+			}
+		}
+	}
+	return doc
+}
+
+// ---- md / txt ----
+
+func parseMarkdown(s string) []core.DocBlock {
+	var blocks []core.DocBlock
+	var para []string
+	flush := func() {
+		if len(para) > 0 {
+			blocks = append(blocks, core.DocBlock{Type: core.BlockPara, Text: strings.Join(para, "\n")})
+			para = nil
+		}
+	}
+	for _, line := range strings.Split(s, "\n") {
+		t := strings.TrimSpace(line)
+		switch {
+		case t == "":
+			flush()
+		case strings.HasPrefix(t, "#"):
+			flush()
+			level := 0
+			for level < len(t) && t[level] == '#' {
+				level++
+			}
+			blocks = append(blocks, core.DocBlock{Type: core.BlockHeading, Level: level, Text: strings.TrimSpace(t[level:])})
+		case strings.HasPrefix(t, "- ") || strings.HasPrefix(t, "* "):
+			flush()
+			if n := len(blocks); n > 0 && blocks[n-1].Type == core.BlockList {
+				blocks[n-1].Items = append(blocks[n-1].Items, strings.TrimSpace(t[2:]))
+			} else {
+				blocks = append(blocks, core.DocBlock{Type: core.BlockList, Items: []string{strings.TrimSpace(t[2:])}})
+			}
+		case strings.HasPrefix(t, "```"):
+			flush()
+			blocks = append(blocks, core.DocBlock{Type: core.BlockCode, Text: ""}) // 简化：代码块内容并入口令块
+		default:
+			para = append(para, t)
+		}
+	}
+	flush()
+	return blocks
+}
+
+func parsePlain(s string) []core.DocBlock {
+	var blocks []core.DocBlock
+	var para []string
+	flush := func() {
+		if len(para) > 0 {
+			blocks = append(blocks, core.DocBlock{Type: core.BlockPara, Text: strings.Join(para, "\n")})
+			para = nil
+		}
+	}
+	for _, line := range strings.Split(s, "\n") {
+		if strings.TrimSpace(line) == "" {
+			flush()
+			continue
+		}
+		para = append(para, strings.TrimRight(line, "\r"))
+	}
+	flush()
+	return blocks
+}
+
+// ---- docx（OOXML：zip 内 word/document.xml）----
+
+type xdoc struct {
+	Body struct {
+		Paragraphs []xpar `xml:"p"`
+		Tables     []xtbl `xml:"tbl"`
+	} `xml:"body"`
+}
+
+type xpar struct {
+	Props struct {
+		Style struct {
+			Val string `xml:"val,attr"`
+		} `xml:"pStyle"`
+	} `xml:"pPr"`
+	Runs []xrun `xml:"r"`
+}
+
+type xrun struct {
+	Text []struct {
+		Content string `xml:",chardata"`
+	} `xml:"t"`
+	Break struct {
+		Val string `xml:"val,attr"`
+	} `xml:"br"`
+}
+
+type xtbl struct {
+	Rows []xtr `xml:"tr"`
+}
+
+type xtr struct {
+	Cells []xtc `xml:"tc"`
+}
+
+type xtc struct {
+	Paragraphs []xpar `xml:"p"`
+}
+
+func parseDocx(content []byte) ([]core.DocBlock, error) {
+	zr, err := zip.NewReader(bytes.NewReader(content), int64(len(content)))
+	if err != nil {
+		return nil, fmt.Errorf("open zip: %w", err)
+	}
+	var docXML []byte
+	for _, f := range zr.File {
+		if f.Name == "word/document.xml" {
+			rc, err := f.Open()
+			if err != nil {
+				return nil, err
+			}
+			docXML, _ = io.ReadAll(rc)
+			rc.Close()
+			break
+		}
+	}
+	if docXML == nil {
+		return nil, fmt.Errorf("word/document.xml not found")
+	}
+	var doc xdoc
+	if err := xml.Unmarshal(docXML, &doc); err != nil {
+		return nil, fmt.Errorf("unmarshal document.xml: %w", err)
+	}
+	var blocks []core.DocBlock
+	for _, p := range doc.Body.Paragraphs {
+		text := paragraphText(p)
+		if strings.TrimSpace(text) == "" {
+			continue
+		}
+		if lvl, ok := headingLevel(p.Props.Style.Val); ok {
+			blocks = append(blocks, core.DocBlock{Type: core.BlockHeading, Level: lvl, Text: text})
+		} else {
+			blocks = append(blocks, core.DocBlock{Type: core.BlockPara, Text: text})
+		}
+	}
+	for _, tbl := range doc.Body.Tables {
+		var rows [][]string
+		for _, tr := range tbl.Rows {
+			row := []string{}
+			for _, tc := range tr.Cells {
+				cell := []string{}
+				for _, p := range tc.Paragraphs {
+					cell = append(cell, paragraphText(p))
+				}
+				row = append(row, strings.Join(cell, " "))
+			}
+			rows = append(rows, row)
+		}
+		if len(rows) > 0 {
+			blocks = append(blocks, core.DocBlock{Type: core.BlockTable, Rows: rows})
+		}
+	}
+	return blocks, nil
+}
+
+func paragraphText(p xpar) string {
+	var sb strings.Builder
+	for _, r := range p.Runs {
+		for _, t := range r.Text {
+			sb.WriteString(t.Content)
+		}
+	}
+	return sb.String()
+}
+
+func headingLevel(style string) (int, bool) {
+	s := strings.ToLower(style)
+	switch {
+	case strings.Contains(s, "heading1") || s == "1":
+		return 1, true
+	case strings.Contains(s, "heading2") || s == "2":
+		return 2, true
+	case strings.Contains(s, "heading3") || s == "3" || strings.Contains(s, "title"):
+		return 3, true
+	}
+	return 0, false
+}
+
+// ---- pdf（文本层提取）----
+
+func parsePDF(content []byte) ([]core.DocBlock, error) {
+	r, err := pdflib.NewReader(bytes.NewReader(content), int64(len(content)))
+	if err != nil {
+		return nil, err
+	}
+	var blocks []core.DocBlock
+	for i := 1; i <= r.NumPage(); i++ {
+		page := r.Page(i)
+		if page.V.IsNull() {
+			continue
+		}
+		text, err := page.GetPlainText(nil)
+		if err != nil {
+			continue
+		}
+		for _, para := range strings.Split(text, "\n\n") {
+			if t := strings.TrimSpace(para); t != "" {
+				blocks = append(blocks, core.DocBlock{Type: core.BlockPara, Text: t})
+			}
+		}
+	}
+	if len(blocks) == 0 {
+		return nil, fmt.Errorf("无文本层（可能是扫描件）")
+	}
+	return blocks, nil
+}
+
+// ---- 辅助 ----
+
+func isImage(ext string) bool {
+	switch ext {
+	case "png", "jpg", "jpeg", "gif", "webp", "bmp", "svg":
+		return true
+	}
+	return false
+}
+
+func isMostlyPrintable(s string) bool {
+	if len(s) == 0 {
+		return true
+	}
+	nonPrint := 0
+	for _, r := range s {
+		if r == 0xFFFD || (r < 0x20 && r != '\n' && r != '\r' && r != '\t') {
+			nonPrint++
+		}
+	}
+	return nonPrint*10 < len(s)
+}
+
+// ParsersDescription 返回解析器注册表描述（来源标记；设置页/文档用）。
+func ParsersDescription() []core.ParserDesc {
+	return []core.ParserDesc{
+		{ID: "builtin:md", Formats: []string{"md", "markdown"}, Source: core.SourceBuiltin},
+		{ID: "builtin:txt", Formats: []string{"txt", "csv", "log"}, Source: core.SourceBuiltin},
+		{ID: "builtin:docx", Formats: []string{"docx"}, Source: core.SourceBuiltin},
+		{ID: "builtin:pdf", Formats: []string{"pdf"}, Source: core.SourceBuiltin, Note: "文本层；扫描件为远期 MinerU 深度档"},
+		{ID: "mineru", Formats: []string{"pdf", "png", "jpg"}, Source: core.SourcePlugin, Note: "远期可选：深度解析与交叉验证（默认不部署）"},
+	}
+}

internal/ingest/ingest_test.go

@@ -0,0 +1,102 @@
+package ingest
+
+import (
+	"archive/zip"
+	"bytes"
+	"encoding/xml"
+	"strings"
+	"testing"
+
+	core "agent-system-core"
+)
+
+func TestParseMarkdown(t *testing.T) {
+	doc := Parse("笔记.md", "text/markdown", []byte("# 标题一\n\n段落甲。\n\n- 要点 1\n- 要点 2\n\n## 标题二\n\n段落乙。\n"))
+	if doc.Meta.Parser != "builtin:md" || doc.Meta.Confidence != 1.0 {
+		t.Fatalf("meta: %+v", doc.Meta)
+	}
+	var heads, paras, lists int
+	for _, b := range doc.Blocks {
+		switch b.Type {
+		case core.BlockHeading:
+			heads++
+		case core.BlockPara:
+			paras++
+		case core.BlockList:
+			lists++
+			if len(b.Items) != 2 {
+				t.Errorf("list items: %v", b.Items)
+			}
+		}
+	}
+	if heads != 2 || paras != 2 || lists != 1 {
+		t.Errorf("blocks: heads=%d paras=%d lists=%d", heads, paras, lists)
+	}
+	if !strings.Contains(doc.PlainText(), "# 标题一") {
+		t.Error("PlainText missing heading")
+	}
+}
+
+func TestParseUnknownBinary(t *testing.T) {
+	doc := Parse("blob.bin", "application/octet-stream", []byte{0x00, 0x01, 0x02, 0xFF})
+	if len(doc.Blocks) != 0 {
+		t.Error("binary should not produce blocks")
+	}
+	if len(doc.Warnings) == 0 {
+		t.Error("binary should carry explicit warning (fail visible, not silent)")
+	}
+}
+
+// 构造最小 docx（zip + word/document.xml）验证 OOXML 解析。
+func TestParseDocx(t *testing.T) {
+	var buf bytes.Buffer
+	zw := zip.NewWriter(&buf)
+	docXML := `<?xml version="1.0"?>
+<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+ <w:body>
+  <w:p><w:pPr><w:pStyle w:val="Heading1"/></w:pPr><w:r><w:t>总则</w:t></w:r></w:p>
+  <w:p><w:r><w:t>本文件说明医疗器械文档要求。</w:t></w:r></w:p>
+  <w:tbl>
+   <w:tr><w:tc><w:p><w:r><w:t>项</w:t></w:r></w:p></w:tc><w:tc><w:p><w:r><w:t>值</w:t></w:r></w:p></w:tc></w:tr>
+   <w:tr><w:tc><w:p><w:r><w:t>版本</w:t></w:r></w:p></w:tc><w:tc><w:p><w:r><w:t>1.0</w:t></w:r></w:p></w:tc></w:tr>
+  </w:tbl>
+ </w:body>
+</w:document>`
+	if f, err := zw.Create("word/document.xml"); err == nil {
+		f.Write([]byte(docXML))
+	} else {
+		t.Fatal(err)
+	}
+	zw.Close()
+
+	doc := Parse("报告.docx", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", buf.Bytes())
+	if doc.Meta.Parser != "builtin:docx" || len(doc.Warnings) != 0 {
+		t.Fatalf("meta: %+v warnings: %v", doc.Meta, doc.Warnings)
+	}
+	var heading, para, table bool
+	for _, b := range doc.Blocks {
+		switch b.Type {
+		case core.BlockHeading:
+			heading = b.Level == 1 && b.Text == "总则"
+		case core.BlockPara:
+			para = strings.Contains(b.Text, "医疗器械")
+		case core.BlockTable:
+			table = len(b.Rows) == 2 && b.Rows[1][1] == "1.0"
+		}
+	}
+	if !heading || !para || !table {
+		t.Errorf("docx blocks wrong: heading=%v para=%v table=%v blocks=%+v", heading, para, table, doc.Blocks)
+	}
+	if !strings.Contains(doc.PlainText(), "医疗器械") {
+		t.Error("PlainText missing docx text")
+	}
+}
+
+func TestParsePDFInvalid(t *testing.T) {
+	doc := Parse("scan.pdf", "application/pdf", []byte("not a pdf"))
+	if len(doc.Warnings) == 0 || doc.Meta.Confidence > 0.5 {
+		t.Errorf("invalid pdf should warn with low confidence: %+v", doc.Meta)
+	}
+}
+
+var _ = xml.Marshal

internal/plugins/host.go

@@ -0,0 +1,266 @@
+// Package plugins 实现插件宿主（4.6）：manifest + 声明资产 + 可选代码。
+// fail-closed：任一资产解析失败整批拒绝该插件并保留上一状态；卸载注销注册项。
+// 声明资产热加载：Reload 重扫目录；工具/面板/卡片/意图/工作流/设置全部数据化。
+package plugins
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+
+	core "agent-system-core"
+	"agent-system-backend/internal/settings"
+	"agent-system-backend/internal/store"
+	"agent-system-backend/internal/tools"
+)
+
+// Loaded 是一个已装载插件的内存态（注册结果快照）。
+type Loaded struct {
+	Manifest core.PluginManifest
+	Dir      string
+	Panels   []core.PluginPanel
+	Cards    map[string][]core.UINode // kind → 模板节点
+	Workflows []core.WorkflowDef
+	Intents  []json.RawMessage // agent-intent overlay 形态（目录侧消费）
+	Prompts  map[string]string // 文件名 → 内容（画像模板）
+	PluginSettings []core.SettingDesc
+	Defaults map[string]any // 插件设置默认值（并入有效设置）
+}
+
+// Host 管理插件目录装载与注册。
+type Host struct {
+	mu       sync.RWMutex
+	st       *store.Store
+	registry *tools.Registry
+	settings *settings.Service
+	dir      string
+	loaded   map[string]*Loaded // id → loaded
+}
+
+func New(st *store.Store, reg *tools.Registry, s *settings.Service, dir string) *Host {
+	return &Host{st: st, registry: reg, settings: s, dir: dir, loaded: map[string]*Loaded{}}
+}
+
+// LoadDir 全量装载目录（启动与热加载共用）；返回每个插件的结果（失败不中断其他）。
+func (h *Host) LoadDir() map[string]error {
+	entries, err := os.ReadDir(h.dir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return map[string]error{}
+		}
+		return map[string]error{"<dir>": err}
+	}
+	results := map[string]error{}
+	seen := map[string]bool{}
+	for _, e := range entries {
+		if !e.IsDir() {
+			continue
+		}
+		id := e.Name()
+		seen[id] = true
+		results[id] = h.loadOne(filepath.Join(h.dir, id))
+	}
+	// 移除已消失的插件（卸载语义）。
+	h.mu.Lock()
+	for id := range h.loaded {
+		if !seen[id] {
+			delete(h.loaded, id)
+			h.registry.UnregisterBySource(core.SourcePlugin, id)
+		}
+	}
+	h.mu.Unlock()
+	return results
+}
+
+// loadOne 装载单个插件；任何失败返回错误且不改变既有注册（fail-closed）。
+func (h *Host) loadOne(dir string) error {
+	manifestPath := filepath.Join(dir, "plugin.json")
+	raw, err := os.ReadFile(manifestPath)
+	if err != nil {
+		return fmt.Errorf("plugins: %s: %w", filepath.Base(dir), err)
+	}
+	var m core.PluginManifest
+	if err := json.Unmarshal(raw, &m); err != nil {
+		return fmt.Errorf("plugins: %s: manifest json: %w", m.ID, err)
+	}
+	if m.ID == "" || m.Name == "" || m.Version == "" {
+		return fmt.Errorf("plugins: %s: manifest missing id/name/version", m.ID)
+	}
+	if m.APIVersion == "" {
+		m.APIVersion = core.PluginAPIVersion
+	}
+	if m.APIVersion != core.PluginAPIVersion {
+		return fmt.Errorf("plugins: %s: apiVersion %s != host %s（兼容窗口外）", m.ID, m.APIVersion, core.PluginAPIVersion)
+	}
+
+	ld := &Loaded{Manifest: m, Dir: dir, Cards: map[string][]core.UINode{}, Prompts: map[string]string{}, Defaults: map[string]any{}}
+
+	// 同 ID 重载：先注销旧注册（含旧版本工具），再装载新资产。
+	h.registry.UnregisterBySource(core.SourcePlugin, m.ID)
+
+	// tools/*.json：声明式 HTTP 工具（或含 parameters 的描述型工具）。
+	for _, name := range m.Provides.Tools {
+		var desc core.ToolDesc
+		if err := readAsset(dir, "tools", name, &desc); err != nil {
+			return fmt.Errorf("plugins: %s: tool %s: %w", m.ID, name, err)
+		}
+		desc.Source = core.SourcePlugin
+		desc.PluginID = m.ID
+		exec, err := h.bindToolExecutor(desc)
+		if err != nil {
+			return fmt.Errorf("plugins: %s: tool %s: %w", m.ID, name, err)
+		}
+		if err := h.registry.Register(desc, exec); err != nil {
+			return fmt.Errorf("plugins: %s: register tool %s: %w", m.ID, name, err)
+		}
+	}
+
+	// panels/*.json
+	for _, name := range m.Provides.Panels {
+		var panel core.PluginPanel
+		if err := readAsset(dir, "panels", name, &panel); err != nil {
+			return fmt.Errorf("plugins: %s: panel %s: %w", m.ID, name, err)
+		}
+		ld.Panels = append(ld.Panels, panel)
+	}
+
+	// cards/*.json：{kind, data:[UINode]}
+	for _, name := range m.Provides.Cards {
+		var card struct {
+			Kind string       `json:"kind"`
+			Data []core.UINode `json:"data"`
+		}
+		if err := readAsset(dir, "cards", name, &card); err != nil {
+			return fmt.Errorf("plugins: %s: card %s: %w", m.ID, name, err)
+		}
+		if card.Kind == "" {
+			return fmt.Errorf("plugins: %s: card %s: missing kind", m.ID, name)
+		}
+		ld.Cards[card.Kind] = card.Data
+	}
+
+	// workflows/*.json
+	for _, name := range m.Provides.Workflows {
+		var wf core.WorkflowDef
+		if err := readAsset(dir, "workflows", name, &wf); err != nil {
+			return fmt.Errorf("plugins: %s: workflow %s: %w", m.ID, name, err)
+		}
+		ld.Workflows = append(ld.Workflows, wf)
+	}
+
+	// intents/*.json：agent-intent overlay 形态原样透出（目录侧消费，不在此解析）。
+	for _, name := range m.Provides.Intents {
+		var specs []json.RawMessage
+		if err := readAsset(dir, "intents", name, &specs); err != nil {
+			return fmt.Errorf("plugins: %s: intents %s: %w", m.ID, name, err)
+		}
+		ld.Intents = append(ld.Intents, specs...)
+	}
+
+	// prompts/*.md：画像模板（source=plugin，可被用户复制微调）。
+	for _, name := range m.Provides.Prompts {
+		content, err := os.ReadFile(filepath.Join(dir, "prompts", name+".md"))
+		if err != nil {
+			return fmt.Errorf("plugins: %s: prompt %s: %w", m.ID, name, err)
+		}
+		ld.Prompts[name] = string(content)
+	}
+
+	// settings.json：插件设置声明（并入设置中心 schema；默认值进覆盖链底层）。
+	if len(m.Provides.Settings) > 0 {
+		var descs []core.SettingDesc
+		if err := readAsset(dir, "", "settings", &descs); err != nil {
+			return fmt.Errorf("plugins: %s: settings: %w", m.ID, err)
+		}
+		for i := range descs {
+			descs[i].Group = "plugin:" + m.ID
+			ld.PluginSettings = append(ld.PluginSettings, descs[i])
+		}
+	}
+
+	h.mu.Lock()
+	h.loaded[m.ID] = ld
+	h.mu.Unlock()
+	_ = h.st.UpsertPlugin(m.ID, dir, m)
+	return nil
+}
+
+// bindToolExecutor：声明式 HTTP 工具绑定执行器；纯描述型（无 http）工具暂不支持（代码插件为远期 sidecar 档）。
+func (h *Host) bindToolExecutor(desc core.ToolDesc) (tools.Executor, error) {
+	if desc.HTTP == nil {
+		return nil, fmt.Errorf("v1 仅支持声明式 HTTP 工具（缺少 http 段）")
+	}
+	if desc.HTTP.URL == "" || desc.HTTP.Method == "" {
+		return nil, fmt.Errorf("http 工具缺少 url/method")
+	}
+	lookup := func(key string) string {
+		// AuthRef 走用户层设置（如 models.chat.apiKey 或自定义 secret key）。
+		eff := h.settings.Effective("")
+		return eff.GetString(key, "")
+	}
+	return tools.HTTPExecutor(*desc.HTTP, lookup), nil
+}
+
+func readAsset(dir, sub, name string, v any) error {
+	p := filepath.Join(dir, sub, name+".json")
+	if sub == "" {
+		p = filepath.Join(dir, name+".json")
+	}
+	raw, err := os.ReadFile(p)
+	if err != nil {
+		return err
+	}
+	return json.Unmarshal(raw, v)
+}
+
+// ---- 查询接口 ----
+
+func (h *Host) List() []*Loaded {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	out := make([]*Loaded, 0, len(h.loaded))
+	for _, ld := range h.loaded {
+		out = append(out, ld)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Manifest.ID < out[j].Manifest.ID })
+	return out
+}
+
+// SettingsSchema 追加插件设置项（settings schema 汇总用）。
+func (h *Host) SettingsSchema() []core.SettingDesc {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	var out []core.SettingDesc
+	for _, ld := range h.List() {
+		out = append(out, ld.PluginSettings...)
+	}
+	return out
+}
+
+// Cards 返回 kind → 模板（server 演示卡片注入用）。
+func (h *Host) Cards() map[string][]core.UINode {
+	h.mu.RLock()
+	defer h.mu.RUnlock()
+	out := map[string][]core.UINode{}
+	for _, ld := range h.loaded {
+		for k, v := range ld.Cards {
+			out[k] = v
+		}
+	}
+	return out
+}
+
+// Unregister 注销插件全部注册项（卸载语义：在途引用由 registry miss 稳定报错）。
+func (h *Host) Unregister(id string) {
+	h.mu.Lock()
+	delete(h.loaded, id)
+	h.mu.Unlock()
+	h.registry.UnregisterBySource(core.SourcePlugin, id)
+	_ = h.st.RemovePlugin(id)
+}
+
+var _ = strings.TrimSpace

internal/plugins/host_test.go

@@ -0,0 +1,127 @@
+package plugins
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	core "agent-system-core"
+	"agent-system-backend/internal/settings"
+	"agent-system-backend/internal/store"
+	"agent-system-backend/internal/tools"
+)
+
+func newHost(t *testing.T) (*Host, *tools.Registry, string) {
+	t.Helper()
+	dir := t.TempDir()
+	st, err := store.Open(filepath.Join(dir, "test.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { st.Close() })
+	reg := tools.NewRegistry()
+	reg.RegisterBuiltin()
+	setSvc := settings.NewService(st)
+	pluginDir := filepath.Join(dir, "plugins")
+	os.MkdirAll(pluginDir, 0o755)
+	return New(st, reg, setSvc, pluginDir), reg, pluginDir
+}
+
+// writeExamplePlugin 写一个覆盖五类能力的最小示例插件目录。
+func writeExamplePlugin(t *testing.T, dir, id string) {
+	t.Helper()
+	root := filepath.Join(dir, id)
+	for _, sub := range []string{"tools", "panels", "cards", "intents", "prompts"} {
+		os.MkdirAll(filepath.Join(root, sub), 0o755)
+	}
+ writeFile := func(rel, content string) {
+		if err := os.WriteFile(filepath.Join(root, rel), []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	writeFile("plugin.json", `{"id":"`+id+`","name":"示例插件","version":"0.1.0","apiVersion":"`+core.PluginAPIVersion+`",
+		"requires":{"network":["api.example.com"]},
+		"provides":{"tools":["http_echo"],"intents":["demo"],"panels":["demo"],"cards":["note"],"prompts":["assistant"],"settings":["greeting"]}}`)
+	writeFile("tools/http_echo.json", `{"name":"http_echo","description":"回显输入到示例端点","source":"plugin",
+		"parameters":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]},
+		"http":{"method":"POST","url":"https://api.example.com/echo","bodyTemplate":"{\"q\":\"{{param.text}}\"}","resultPath":"echo"}}`)
+	writeFile("panels/demo.json", `{"id":"demo","title":"示例面板","body":[{"type":"markdown","markdown":"# 示例\n插件面板。"}]}`)
+	writeFile("cards/note.json", `{"kind":"note","data":[{"type":"markdown","markdown":"插件卡片模板"}]}`)
+	writeFile("intents/demo.json", `[{"id":"demo_intent","domain":"demo","includes_any":["示例"]}]`)
+	writeFile("prompts/assistant.md", `你是示例插件附带的助手模板。`)
+	writeFile("settings.json", `[{"key":"greeting","group":"plugin:`+id+`","label":"问候语","type":"string","default":"你好","effect":"hot"}]`)
+}
+
+func TestLoadAndRegister(t *testing.T) {
+	host, reg, dir := newHost(t)
+	writeExamplePlugin(t, dir, "example")
+
+	results := host.LoadDir()
+	if err := results["example"]; err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	// 工具注册（source=plugin，声明式 HTTP 绑定执行器）。
+	desc, exec, ok := reg.Get("http_echo")
+	if !ok || desc.Source != core.SourcePlugin || desc.PluginID != "example" || exec == nil {
+		t.Fatalf("tool not registered: %+v", desc)
+	}
+	// 面板/卡片/意图/提示词/设置声明。
+	lds := host.List()
+	if len(lds) != 1 || len(lds[0].Panels) != 1 || lds[0].Cards["note"] == nil || len(lds[0].Intents) != 1 || lds[0].Prompts["assistant"] == "" {
+		t.Fatalf("loaded state wrong: %+v", lds)
+	}
+	if len(host.SettingsSchema()) != 1 || host.SettingsSchema()[0].Group != "plugin:example" {
+		t.Errorf("plugin settings schema: %+v", host.SettingsSchema())
+	}
+}
+
+func TestUnloadRemovesRegistrations(t *testing.T) {
+	host, reg, dir := newHost(t)
+	writeExamplePlugin(t, dir, "example")
+	host.LoadDir()
+	if _, _, ok := reg.Get("http_echo"); !ok {
+		t.Fatal("prerequisite: tool registered")
+	}
+	// 目录中删除插件后重载 → 卸载语义。
+	os.RemoveAll(filepath.Join(dir, "example"))
+	host.LoadDir()
+	if _, _, ok := reg.Get("http_echo"); ok {
+		t.Error("tool should be unregistered after plugin removal")
+	}
+	if len(host.List()) != 0 {
+		t.Error("plugin should be unloaded")
+	}
+	// 内置工具不受影响（核心零回归）。
+	if _, _, ok := reg.Get("knowledge_search"); !ok {
+		t.Error("builtin tool must survive plugin unload")
+	}
+}
+
+// fail-closed：坏资产整批拒绝，不部分注册。
+func TestFailClosedOnBadAsset(t *testing.T) {
+	host, reg, dir := newHost(t)
+	writeExamplePlugin(t, dir, "example")
+	// 破坏工具资产（非法 JSON）。
+	os.WriteFile(filepath.Join(dir, "example", "tools", "http_echo.json"), []byte(`{broken`), 0o644)
+
+	results := host.LoadDir()
+	if err := results["example"]; err == nil {
+		t.Fatal("bad asset should fail load")
+	}
+	if _, _, ok := reg.Get("http_echo"); ok {
+		t.Error("fail-closed violated: tool registered from broken plugin")
+	}
+	if len(host.List()) != 0 {
+		t.Error("broken plugin must not be in loaded list")
+	}
+}
+
+func TestAPIVersionGuard(t *testing.T) {
+	host, _, dir := newHost(t)
+	writeExamplePlugin(t, dir, "oldapi")
+	os.WriteFile(filepath.Join(dir, "oldapi", "plugin.json"), []byte(`{"id":"oldapi","name":"旧版","version":"1.0.0","apiVersion":"0.9","provides":{}}`), 0o644)
+	results := host.LoadDir()
+	if err := results["oldapi"]; err == nil {
+		t.Fatal("incompatible apiVersion should be rejected")
+	}
+}

internal/profiles/profiles.go

@@ -0,0 +1,66 @@
+// Package profiles 管理智能体画像（4.7）：数据化、可导入导出；内置默认画像（T0 基线）。
+package profiles
+
+import (
+	core "agent-system-core"
+	"agent-system-backend/internal/store"
+)
+
+const DefaultProfileID = "default"
+
+func DefaultProfile() core.AgentProfile {
+	maxTools := 40
+	maxTurns := 16
+	return core.AgentProfile{
+		ID:           DefaultProfileID,
+		Name:         "通用助手",
+		Description:  "内置默认画像：全部工具可用，HTTP 工具执行前确认（T0 基线）。",
+		Builtin:      true,
+		Source:       "builtin",
+		SystemPrompt: "你是一个通用智能体助手，运行在 Agent-System 中。回答准确、简洁；需要外部信息时优先使用可用工具；产出文档时写入工件。",
+		Model:        core.ModelRoute{},
+		Tools:        core.ToolPolicy{Allow: []string{"*"}, Confirm: []string{"http."}},
+		Context:      core.ContextPolicy{MaxHistoryMessages: 40, MaxToolResultChars: 20000},
+		HITL:         core.HITLPolicy{AskOnAmbiguity: true},
+		Budget:       core.RunBudget{MaxToolCalls: &maxTools, MaxTurns: &maxTurns},
+	}
+}
+
+type Service struct{ st *store.Store }
+
+func New(st *store.Store) *Service { return &Service{st: st} }
+
+// EnsureDefault 幂等写入内置画像。
+func (s *Service) EnsureDefault() error {
+	if _, err := s.st.GetProfile(DefaultProfileID); err == nil {
+		return nil
+	}
+	return s.st.SaveProfile(DefaultProfile())
+}
+
+func (s *Service) List() ([]core.AgentProfile, error) { return s.st.ListProfiles() }
+
+func (s *Service) Get(id string) (core.AgentProfile, error) {
+	p, err := s.st.GetProfile(id)
+	if err == nil {
+		return p, nil
+	}
+	// 空或未知画像回落默认（T0 行为基线）。
+	return DefaultProfile(), nil
+}
+
+func (s *Service) Save(p core.AgentProfile) error {
+	if p.ID == DefaultProfileID {
+		return errReadOnly("profiles: builtin profile is read-only; duplicate and modify")
+	}
+	if p.Tools.Allow == nil {
+		p.Tools.Allow = []string{"*"}
+	}
+	return s.st.SaveProfile(p)
+}
+
+func (s *Service) Delete(id string) error { return s.st.DeleteProfile(id) }
+
+type errReadOnly string
+
+func (e errReadOnly) Error() string { return string(e) }

internal/runmgr/runmgr.go

@@ -0,0 +1,532 @@
+// Package runmgr 是 Run 生命周期枢纽（4.2/4.3）：一切运行皆 Run、一切增量皆事件。
+// 职责：run 状态机、事件持久化+广播（seq 游标）、HITL 挂起/恢复（三分支路由）、
+// 子代理派生（任务树）、工具执行策略（画像三清单 + 确认卡片 + 截断转工件）、取消级联。
+package runmgr
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	core "agent-system-core"
+	"agent-system-backend/internal/bus"
+	"agent-system-backend/internal/profiles"
+	"agent-system-backend/internal/runtime"
+	"agent-system-backend/internal/settings"
+	"agent-system-backend/internal/store"
+	"agent-system-backend/internal/tools"
+)
+
+type Manager struct {
+	st        *store.Store
+	bus       *bus.Bus
+	registry  *tools.Registry
+	profiles  *profiles.Service
+	settings  *settings.Service
+	runner    runtime.Runner // conversation runner（mock 或 LLM）
+	subRunner runtime.Runner // subagent runner（LLM 轻任务）
+	mock      runtime.Runner // 会话脚本回放（演示/测试与 mock 模式）
+	mockSub   runtime.Runner // 子代理脚本回放
+
+	mu     sync.Mutex
+	active map[string]*runHandle
+}
+
+type runHandle struct {
+	cancel    context.CancelFunc
+	hitlCh    chan hitlAnswer
+	assistant []core.Part
+	started   time.Time
+}
+
+type hitlAnswer struct {
+	resp core.HITLResponse
+	err  error
+}
+
+func New(st *store.Store, b *bus.Bus, reg *tools.Registry, p *profiles.Service, s *settings.Service, runner, subRunner, mockRunner, mockSubRunner runtime.Runner) *Manager {
+	return &Manager{st: st, bus: b, registry: reg, profiles: p, settings: s, runner: runner, subRunner: subRunner, mock: mockRunner, mockSub: mockSubRunner, active: map[string]*runHandle{}}
+}
+
+// ---- runCtx 实现（runtime.RunCtx）----
+
+type runCtx struct {
+	mgr         *Manager
+	run         core.Run
+	prof        core.AgentProfile
+	eff         core.EffectiveSettings
+	ctx         context.Context
+	h           *runHandle
+	userMessage core.Message
+	attachments []core.ParsedDocument
+	subTask     string
+	subHint     string
+}
+
+func (c *runCtx) Context() context.Context          { return c.ctx }
+func (c *runCtx) Run() core.Run                     { return c.run }
+func (c *runCtx) Profile() core.AgentProfile        { return c.prof }
+func (c *runCtx) Settings() core.EffectiveSettings  { return c.eff }
+func (c *runCtx) History() []core.Message {
+	hist, _ := c.mgr.st.LastMessages(c.run.ConversationID, 200)
+	return hist
+}
+func (c *runCtx) Attachments() []core.ParsedDocument { return c.attachments }
+func (c *runCtx) Subtask() string                    { return c.subTask }
+func (c *runCtx) Tools() []core.ToolDesc             { return c.mgr.registry.List() }
+
+func (c *runCtx) Emit(typ core.StreamEventType, payload any) error {
+	_, err := c.mgr.emit(c.run.ConversationID, c.run.ID, typ, payload)
+	return err
+}
+
+func (c *runCtx) SetAssistantParts(parts []core.Part) error {
+	c.mgr.mu.Lock()
+	c.h.assistant = parts
+	c.mgr.mu.Unlock()
+	return nil
+}
+
+func (c *runCtx) AskHITL(card core.HITLCard) (core.HITLResponse, error) {
+	card.ID = store.NewID("hitl")
+	card.RunID = c.run.ID
+	card.ConversationID = c.run.ConversationID
+	if card.CreatedAt == "" {
+		card.CreatedAt = time.Now().UTC().Format(time.RFC3339)
+	}
+	if err := c.mgr.st.SaveHITLCard(&card); err != nil {
+		return core.HITLResponse{}, err
+	}
+	c.mgr.setRunStatus(&c.run, core.RunWaitingHITL, c.run.Phase)
+	if _, err := c.mgr.emit(c.run.ConversationID, c.run.ID, core.EvHITLRequest, card); err != nil {
+		return core.HITLResponse{}, err
+	}
+	select {
+	case ans := <-c.h.hitlCh:
+		return ans.resp, ans.err
+	case <-c.ctx.Done():
+		return core.HITLResponse{}, c.ctx.Err()
+	}
+}
+
+func (c *runCtx) SpawnSubagent(name, task, hint string) (core.AgentResultPayload, error) {
+	return c.mgr.spawnSubagent(c.ctx, c.run, name, task, hint)
+}
+
+func (c *runCtx) UpdatePlan(p core.PlanSnapshot) error {
+	p.PlanID = c.run.ConversationID
+	if err := c.mgr.st.SavePlan(c.run.ConversationID, p); err != nil {
+		return err
+	}
+	_, err := c.mgr.emit(c.run.ConversationID, c.run.ID, core.EvPlanUpdate, core.PlanUpdatePayload{Plan: p})
+	return err
+}
+
+func (c *runCtx) UpdateTodos(l core.TodoList) error {
+	l.ConversationID = c.run.ConversationID
+	if err := c.mgr.st.SaveTodos(c.run.ConversationID, l); err != nil {
+		return err
+	}
+	_, err := c.mgr.emit(c.run.ConversationID, c.run.ID, core.EvTodoUpdate, core.TodoUpdatePayload{List: l})
+	return err
+}
+
+func (c *runCtx) WriteArtifact(name, kind, mime string, content []byte) (core.Artifact, error) {
+	art := core.Artifact{ProjectID: c.run.ProjectID, Name: name, Kind: kind, MIME: mime, SourceRun: c.run.ID}
+	if err := c.mgr.st.CreateArtifact(&art, content); err != nil {
+		return art, err
+	}
+	if _, err := c.mgr.emit(c.run.ConversationID, c.run.ID, core.EvArtifactCreated, core.ArtifactPayload{Artifact: art}); err != nil {
+		return art, err
+	}
+	// 工件文本进知识索引（全文检索最小实现）。
+	if kind == "document" && len(content) < 200000 {
+		_ = c.mgr.st.AddKnowledge(core.KnowledgeDoc{ProjectID: c.run.ProjectID, Source: "artifact", Title: name, Ref: art.ID, Chunk: string(content)})
+	}
+	return art, nil
+}
+
+func (c *runCtx) Retrieve(q core.RetrievalQuery) ([]core.RetrievalHit, error) {
+	if q.TopK <= 0 {
+		q.TopK = int(c.eff.GetNumber("retrieval.topK", 5))
+	}
+	if q.ProjectID == "" {
+		q.ProjectID = c.run.ProjectID
+	}
+	return c.mgr.st.SearchKnowledge(q)
+}
+
+// ExecuteTool 执行画像策略：deny→错误；confirm→HITL confirm 卡片；执行→截断转工件。
+func (c *runCtx) ExecuteTool(call core.ToolCallRequest) core.ToolCallResult {
+	policy := c.prof.Tools
+	if !policy.ToolAllowed(call.Name) {
+		return core.ToolCallResult{CallID: call.CallID, Status: "error", Output: fmt.Sprintf("tool %q denied by profile policy", call.Name)}
+	}
+	if policy.NeedsConfirm(call.Name) {
+		var argsPreview string
+		if len(call.Arguments) > 0 {
+			argsPreview = truncate(string(call.Arguments), 600)
+		}
+		card := core.HITLCard{
+			Question: fmt.Sprintf("执行工具 %s？", call.Name), Kind: core.HITLKindConfirm,
+			Choices: []core.HITLChoice{
+				{ID: "yes", Label: "执行", Description: "按上述参数调用", Impact: "该工具将访问外部资源并返回结果", Recommended: true},
+				{ID: "no", Label: "取消", Description: "跳过本次调用", Impact: "模型会收到调用被拒绝的说明"},
+			},
+			AllowFreeInput: false,
+		}
+		_ = argsPreview
+		resp, err := c.AskHITL(card)
+		if err != nil {
+			return core.ToolCallResult{CallID: call.CallID, Status: "error", Output: "hitl aborted: " + err.Error()}
+		}
+		if resp.ChoiceID != "yes" {
+			return core.ToolCallResult{CallID: call.CallID, Status: "error", Output: "用户取消了本次工具调用"}
+		}
+	}
+	res := c.mgr.registry.Execute(toolCtx{rc: c}, call)
+	// 超长截断并转工件引用（4.10）。
+	limit := c.prof.Context.MaxToolResultChars
+	if limit <= 0 {
+		limit = int(c.eff.GetNumber("context.maxToolResultChars", 20000))
+	}
+	if res.Status == "ok" && len(res.Output) > limit {
+		if art, err := c.WriteArtifact("tool-"+call.Name+"-"+call.CallID+".txt", "data", "text/plain", []byte(res.Output)); err == nil {
+			res.Artifact = &art
+			res.Output = res.Output[:limit] + "\n…（超长，完整结果已存为工件 " + art.Name + "）"
+		} else {
+			res.Output = res.Output[:limit] + "…（超长截断，工件写入失败）"
+		}
+		res.Truncated = true
+	}
+	return res
+}
+
+type toolCtx struct{ rc *runCtx }
+
+func (t toolCtx) ProjectID() string      { return t.rc.run.ProjectID }
+func (t toolCtx) ConversationID() string { return t.rc.run.ConversationID }
+func (t toolCtx) Retrieve(q core.RetrievalQuery) ([]core.RetrievalHit, error) { return t.rc.Retrieve(q) }
+func (t toolCtx) WriteArtifact(name, kind, mime string, content []byte) (core.Artifact, error) {
+	return t.rc.WriteArtifact(name, kind, mime, content)
+}
+
+// ---- run 生命周期 ----
+
+// StartConversationRun 为一条已落库的用户消息启动 conversation run。
+// attachments 为已解析的附件文档（server 层经 ingest 处理）。
+func (m *Manager) StartConversationRun(conv core.Conversation, userMessage core.Message, attachments []core.ParsedDocument) (core.Run, error) {
+	prof, _ := m.profiles.Get(conv.ProfileID)
+	eff := m.settings.Effective(conv.ProjectID)
+	run := core.Run{
+		ID: store.NewID("run"), ConversationID: conv.ID, ProjectID: conv.ProjectID,
+		Kind: core.RunConversation, ProfileID: prof.ID, Status: core.RunPending, Phase: core.PhaseThinking,
+	}
+	if err := m.st.CreateRun(&run); err != nil {
+		return run, err
+	}
+	ctx, cancel := context.WithCancel(context.Background())
+	h := &runHandle{cancel: cancel, hitlCh: make(chan hitlAnswer, 1), started: time.Now()}
+	m.mu.Lock()
+	m.active[run.ID] = h
+	m.mu.Unlock()
+
+	runner := m.runner
+	if eff.GetBool("runtime.mock", false) {
+		runner = m.mock
+	}
+	rc := &runCtx{mgr: m, run: run, prof: prof, eff: eff, ctx: ctx, h: h, userMessage: userMessage, attachments: attachments}
+	go m.execute(rc, runner)
+	return run, nil
+}
+
+// execute 运行至终态并收敛：状态、usage、助手消息、收尾事件。
+func (m *Manager) execute(rc *runCtx, runner runtime.Runner) {
+	defer func() {
+		m.mu.Lock()
+		delete(m.active, rc.run.ID)
+		m.mu.Unlock()
+	}()
+	m.setRunStatus(&rc.run, core.RunRunning, core.PhaseThinking)
+	m.emit(rc.run.ConversationID, rc.run.ID, core.EvRunPhase, core.RunPhasePayload{Phase: core.PhaseThinking})
+
+	execErr := func() (err error) {
+		defer func() {
+			if r := recover(); r != nil {
+				err = fmt.Errorf("runner panic: %v", r)
+			}
+		}()
+		return runner.Execute(rc)
+	}()
+
+	usage := core.Usage{DurationMs: float64(time.Since(rc.h.started).Milliseconds())}
+	if execErr != nil {
+		if rc.ctx.Err() != nil {
+			m.finishRun(rc, core.RunCancelled, usage, &core.ErrorPart{Code: "run.cancelled", Message: "已取消"})
+			return
+		}
+		m.finishRun(rc, core.RunFailed, usage, &core.ErrorPart{Code: "run.failed", Message: execErr.Error()})
+		return
+	}
+	m.finishRun(rc, core.RunCompleted, usage, nil)
+}
+
+func (m *Manager) finishRun(rc *runCtx, status core.RunStatus, usage core.Usage, errPart *core.ErrorPart) {
+	now := time.Now().UTC()
+	rc.run.EndedAt = &now
+	rc.run.Status = status
+	rc.run.Phase = core.PhaseDone
+	rc.run.Usage = &usage
+	rc.run.Error = errPart
+	m.st.UpdateRun(&rc.run)
+
+	// 终态权威消息树：落库助手消息（含过程部件标记）。
+	m.mu.Lock()
+	parts := append([]core.Part{}, rc.h.assistant...)
+	m.mu.Unlock()
+	if len(parts) > 0 {
+		msg := core.Message{ConversationID: rc.run.ConversationID, RunID: rc.run.ID, Role: core.RoleAssistant, Parts: parts}
+		if err := m.st.AppendMessage(&msg); err == nil {
+			// 消息树权威已落库；hitl 摘要部件的卡片状态由前端对账收敛。
+		}
+		if errPart != nil {
+			m.st.AppendMessage(&core.Message{ConversationID: rc.run.ConversationID, RunID: rc.run.ID, Role: core.RoleAssistant, Parts: []core.Part{{Type: core.PartError, Err: errPart}}})
+		}
+	} else if errPart != nil {
+		m.st.AppendMessage(&core.Message{ConversationID: rc.run.ConversationID, RunID: rc.run.ID, Role: core.RoleAssistant, Parts: []core.Part{{Type: core.PartError, Err: errPart}}})
+	}
+
+	switch status {
+	case core.RunCompleted:
+		usagePayload := core.RunCompletedPayload{Usage: usage}
+		// 把工具调用数补进 usage（由 runner 在部件里体现，这里取事件计数）。
+		m.emit(rc.run.ConversationID, rc.run.ID, core.EvRunCompleted, usagePayload)
+	case core.RunFailed:
+		m.emit(rc.run.ConversationID, rc.run.ID, core.EvRunFailed, core.RunFailedPayload{Code: errPart.Code, Message: errPart.Message})
+	}
+}
+
+// setRunStatus 更新并广播 phase（状态不单独出事件，phase 事件携带）。
+func (m *Manager) setRunStatus(r *core.Run, status core.RunStatus, phase core.RunPhase) {
+	r.Status = status
+	r.Phase = phase
+	m.st.UpdateRun(r)
+}
+
+// emit 持久化事件并广播；返回 seq。
+func (m *Manager) emit(conversationID, runID string, typ core.StreamEventType, payload any) (int64, error) {
+	e := core.StreamEvent{
+		ConversationID: conversationID, RunID: runID,
+		TS: time.Now().UTC().Format(time.RFC3339Nano), V: core.ProtocolVersion, Type: typ,
+	}
+	seq, err := m.st.AppendEvent(&e, payload)
+	if err != nil {
+		return 0, err
+	}
+	e.Seq = seq
+	m.bus.Publish(e)
+	return seq, nil
+}
+
+// CancelRun 取消 run 及其子 run（ctx 级联）。
+func (m *Manager) CancelRun(runID string) error {
+	r, err := m.st.GetRun(runID)
+	if err != nil {
+		return err
+	}
+	if r.Status == core.RunCompleted || r.Status == core.RunFailed || r.Status == core.RunCancelled {
+		return fmt.Errorf("runmgr: run %s already terminal (%s)", runID, r.Status)
+	}
+	// 取消祖先句柄（子 run 派生自父 ctx，天然级联）。
+	rootID := r.ParentRunID
+	if rootID == "" {
+		rootID = r.ID
+	}
+	m.mu.Lock()
+	if h, ok := m.active[rootID]; ok {
+		h.cancel()
+		// 唤醒可能在等 HITL 的执行。
+		select {
+		case h.hitlCh <- hitlAnswer{err: context.Canceled}:
+		default:
+		}
+	}
+	if h, ok := m.active[r.ID]; ok && r.ID != rootID {
+		h.cancel()
+		select {
+		case h.hitlCh <- hitlAnswer{err: context.Canceled}:
+		default:
+		}
+	}
+	m.mu.Unlock()
+	return nil
+}
+
+// ---- HITL 解析（三分支路由，4.5）----
+
+// ResolveHITL 处理用户对卡片的响应：
+//  1) 选项命中 → 回填挂起 run；
+//  2) 自由输入以 "/" 开头（命令）→ 取消挂起 run，返回转轨标志由 server 层发送新消息；
+//  3) 其他自由输入 → 作为澄清回答回填。
+func (m *Manager) ResolveHITL(cardID string, resp core.HITLResponse) (pivotText string, pivoted bool, err error) {
+	card, err := m.st.GetHITLCard(cardID)
+	if err != nil {
+		return "", false, err
+	}
+	if card.Resolved {
+		return "", false, fmt.Errorf("runmgr: card %s already resolved", cardID)
+	}
+	run, err := m.st.GetRun(card.RunID)
+	if err != nil {
+		return "", false, err
+	}
+
+	kind := "choice"
+	answer := ""
+	if resp.ChoiceID != "" {
+		for _, c := range card.Choices {
+			if c.ID == resp.ChoiceID {
+				answer = c.Label
+				break
+			}
+		}
+	} else if resp.FreeText != "" {
+		kind = "free"
+		answer = resp.FreeText
+		if strings.HasPrefix(strings.TrimSpace(resp.FreeText), "/") {
+			// 命令转轨：取消挂起 run，等价于用户直接发送该命令。
+			_ = m.CancelRun(run.ID)
+			m.st.ResolveHITLCard(cardID, core.HITLResolvedPayload{CardID: core.ID(cardID), Kind: "cancelled", Answer: answer})
+			m.emit(run.ConversationID, run.ID, core.EvHITLResolved, core.HITLResolvedPayload{CardID: core.ID(cardID), Kind: "cancelled", Answer: answer})
+			return strings.TrimSpace(resp.FreeText), true, nil
+		}
+	}
+	resolution := core.HITLResolvedPayload{CardID: core.ID(cardID), Answer: answer, Kind: kind}
+	if err := m.st.ResolveHITLCard(cardID, resolution); err != nil {
+		return "", false, err
+	}
+	m.emit(run.ConversationID, run.ID, core.EvHITLResolved, resolution)
+
+	m.mu.Lock()
+	h, ok := m.active[run.ID]
+	m.mu.Unlock()
+	if !ok {
+		return "", false, fmt.Errorf("runmgr: run %s not active (may have ended)", run.ID)
+	}
+	select {
+	case h.hitlCh <- hitlAnswer{resp: resp}:
+	default:
+		return "", false, fmt.Errorf("runmgr: hitl channel busy")
+	}
+	// 恢复运行状态。
+	if run.Status == core.RunWaitingHITL {
+		run.Status = core.RunRunning
+		m.st.UpdateRun(&run)
+	}
+	return "", false, nil
+}
+
+// ---- 子代理（任务树）----
+
+func (m *Manager) spawnSubagent(parentCtx context.Context, parent core.Run, name, task, hint string) (core.AgentResultPayload, error) {
+	child := core.Run{
+		ID: store.NewID("run"), ParentRunID: parent.ID, ConversationID: parent.ConversationID,
+		ProjectID: parent.ProjectID, Kind: core.RunSubagent, ProfileID: parent.ProfileID,
+		Status: core.RunPending, Phase: core.PhaseThinking, AgentName: name,
+	}
+	if err := m.st.CreateRun(&child); err != nil {
+		return core.AgentResultPayload{}, err
+	}
+	m.emit(parent.ConversationID, parent.ID, core.EvAgentSpawn, core.AgentSpawnPayload{AgentRun: child.ID, Name: name, Task: task})
+
+	ctx, cancel := context.WithCancel(parentCtx)
+	h := &runHandle{cancel: cancel, hitlCh: make(chan hitlAnswer, 1), started: time.Now()}
+	m.mu.Lock()
+	m.active[child.ID] = h
+	m.mu.Unlock()
+
+	prof, _ := m.profiles.Get(parent.ProfileID)
+	eff := m.settings.Effective(parent.ProjectID)
+	rc := &runCtx{mgr: m, run: child, prof: prof, eff: eff, ctx: ctx, h: h, subTask: task, subHint: hint}
+	m.setRunStatus(&rc.run, core.RunRunning, core.PhaseActing)
+
+	runner := m.subRunner
+	if eff.GetBool("runtime.mock", false) || runner == nil {
+		runner = m.mockSub
+	}
+	execErr := func() (err error) {
+		defer func() {
+			if r := recover(); r != nil {
+				err = fmt.Errorf("subagent panic: %v", r)
+			}
+		}()
+		return runner.Execute(rc)
+	}()
+
+	usage := core.Usage{DurationMs: float64(time.Since(h.started).Milliseconds())}
+	status := core.RunCompleted
+	summary := "完成"
+	payload := core.AgentResultPayload{AgentRun: child.ID, Status: status, Summary: summary}
+	if execErr != nil {
+		if ctx.Err() != nil {
+			status = core.RunCancelled
+			payload.Status = status
+			payload.Summary = "已取消"
+		} else {
+			status = core.RunFailed
+			payload.Status = status
+			payload.Summary = execErr.Error()
+		}
+	}
+	now := time.Now().UTC()
+	child.EndedAt = &now
+	child.Status = status
+	child.Phase = core.PhaseDone
+	child.Usage = &usage
+	m.st.UpdateRun(&child)
+	m.emit(child.ConversationID, child.ID, core.EvAgentResult, payload)
+
+	m.mu.Lock()
+	delete(m.active, child.ID)
+	m.mu.Unlock()
+	if status != core.RunCompleted {
+		return payload, fmt.Errorf("subagent %s: %s", name, payload.Summary)
+	}
+	return payload, nil
+}
+
+// InterruptRunning 服务停机前把在途 run 标记为 interrupted（4.2 恢复策略）。
+func (m *Manager) InterruptRunning() {
+	m.mu.Lock()
+	ids := make([]string, 0, len(m.active))
+	for id := range m.active {
+		ids = append(ids, id)
+	}
+	handles := make([]*runHandle, 0, len(ids))
+	for _, id := range ids {
+		if h, ok := m.active[id]; ok {
+			handles = append(handles, h)
+		}
+	}
+	m.mu.Unlock()
+	for _, h := range handles {
+		h.cancel()
+	}
+	for _, id := range ids {
+		r, err := m.st.GetRun(id)
+		if err != nil || r.Status == core.RunCompleted || r.Status == core.RunFailed || r.Status == core.RunCancelled {
+			continue
+		}
+		r.Status = core.RunInterrupted
+		m.st.UpdateRun(&r)
+	}
+}
+
+func truncate(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "…"
+}

internal/runtime/llm.go

@@ -0,0 +1,300 @@
+package runtime
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	agentllm "agent-native/runtime/llm"
+	core "agent-system-core"
+	"agent-system-backend/internal/ctxasm"
+)
+
+// LLMRunner 主对话执行器：复用 agent-native 的 OpenAI 兼容流式客户端（不自研接入层）。
+// 多轮循环：流式 → 工具调用（画像策略）→ 回灌结果 → 直至无工具调用或预算耗尽。
+// 内置三个编排型工具（不经注册表）：delegate_task（子代理）、update_plan、update_todos。
+type LLMRunner struct{}
+
+func (l *LLMRunner) Name() string { return "llm" }
+
+const (
+	toolDelegate  = "delegate_task"
+	toolPlan      = "update_plan"
+	toolTodos     = "update_todos"
+)
+
+func (l *LLMRunner) Execute(rc RunCtx) error {
+	eff := rc.Settings()
+	chat := eff.GetString("models.chat.model", "")
+	base := eff.GetString("models.chat.baseUrl", "")
+	key := eff.GetString("models.chat.apiKey", "")
+	if chat == "" || base == "" {
+		return fmt.Errorf("llm: 主模型未配置（settings: models.chat.baseUrl / models.chat.model；演示模式可开 runtime.mock）")
+	}
+
+	client := &agentllm.Client{BaseURL: base, APIKey: key}
+	prof := rc.Profile()
+
+	// 知识注入：当前消息包含 @knowledge 引用时检索注入（最小实现：显式引用）。
+	var knowledge []core.RetrievalHit
+	if strings.Contains(currentUserText(rc), "@knowledge") {
+		q := strings.TrimSpace(strings.ReplaceAll(currentUserText(rc), "@knowledge", ""))
+		if hits, err := rc.Retrieve(core.RetrievalQuery{Text: q}); err == nil {
+			knowledge = hits
+		}
+	}
+
+	// 组装初始上下文。
+	hist := rc.History()
+	var currentUser core.Message
+	for i := len(hist) - 1; i >= 0; i-- {
+		if hist[i].Role == core.RoleUser {
+			currentUser = hist[i]
+			break
+		}
+	}
+	msgs, _ := ctxasm.AssembleInput(prof, eff, hist, currentUser, rc.Attachments(), knowledge)
+
+	// 声明工具：编排型内置 + 注册表中画像允许的工具。
+	decls := []agentllm.ToolDecl{
+		{Name: toolDelegate, Description: "派生一个子代理执行独立子任务（如检索、撰写），返回其结果摘要", Parameters: json.RawMessage(`{"type":"object","properties":{"name":{"type":"string","description":"子代理角色名"},"task":{"type":"string","description":"子任务描述"},"hint":{"type":"string","description":"执行提示"}},"required":["name","task"]}`)},
+		{Name: toolPlan, Description: "创建或更新当前会话的计划（步骤列表）", Parameters: json.RawMessage(`{"type":"object","properties":{"title":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"status":{"type":"string","enum":["pending","in_progress","done","skipped"]}},"required":["id","text","status"]}}},"required":["title","steps"]}`)},
+		{Name: toolTodos, Description: "更新当前会话的待办清单", Parameters: json.RawMessage(`{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"},"status":{"type":"string","enum":["pending","in_progress","done"]}},"required":["id","text","status"]}}},"required":["items"]}`)},
+	}
+	var toolDescs []core.ToolDesc
+	for _, t := range toolList(rc) {
+		if prof.Tools.ToolAllowed(t.Name) {
+			toolDescs = append(toolDescs, t)
+			decls = append(decls, agentllm.ToolDecl{Name: t.Name, Description: t.Description, Parameters: t.Parameters})
+		}
+	}
+
+	var finalParts []core.Part
+	usageTotal := core.Usage{}
+	maxTurns := 16
+	if prof.Budget.MaxTurns != nil {
+		maxTurns = *prof.Budget.MaxTurns
+	}
+	maxTools := 40
+	if prof.Budget.MaxToolCalls != nil {
+		maxTools = *prof.Budget.MaxToolCalls
+	}
+	toolCallsMade := 0
+	thinkingIdx, textIdx := 0, 0
+
+	for turn := 0; turn < maxTurns; turn++ {
+		select {
+		case <-rc.Context().Done():
+			return rc.Context().Err()
+		default:
+		}
+
+		var turnThinking, turnText strings.Builder
+		var calls []agentllm.ToolCall
+		var usage agentllm.Usage
+		ev := client.Stream(rc.Context(), chat, msgs, decls, agentllm.StreamOptions{})
+		phaseEmitted := false
+		for e := range ev {
+			switch e.Kind {
+			case agentllm.KindTextDelta:
+				if !phaseEmitted {
+					rc.Emit(core.EvRunPhase, core.RunPhasePayload{Phase: core.PhaseResponding})
+					phaseEmitted = true
+				}
+				turnText.WriteString(e.Text)
+				rc.Emit(core.EvMessageDelta, core.MessageDeltaPayload{Index: textIdx, Text: e.Text})
+			case agentllm.KindReasoningDelta:
+				turnThinking.WriteString(e.ReasoningDelta)
+				rc.Emit(core.EvThinkingDelta, core.ThinkingDeltaPayload{Index: thinkingIdx, Text: e.ReasoningDelta})
+			case agentllm.KindToolCallDelta:
+				// 累积由 message_end 的 ToolCalls 提供；此处忽略增量。
+			case agentllm.KindMessageEnd:
+				calls = e.Message.ToolCalls
+				usage = e.Usage
+			case agentllm.KindError:
+				return fmt.Errorf("llm stream: %s (retryable=%v)", e.ErrorMessage, e.Retryable)
+			}
+		}
+		usageTotal.PromptTokens += usage.PromptTokens
+		usageTotal.CompletionTokens += usage.CompletionTokens
+		usageTotal.TotalTokens += usage.TotalTokens
+
+		// 记录本轮部件。
+		if turnThinking.Len() > 0 {
+			finalParts = append(finalParts, core.Part{Type: core.PartThinking, Text: turnThinking.String(), Process: true})
+			thinkingIdx++
+		}
+		if turnText.Len() > 0 {
+			finalParts = append(finalParts, core.Part{Type: core.PartText, Text: turnText.String()})
+			textIdx++
+		}
+
+		if len(calls) == 0 {
+			// 终轮：无工具调用。
+			if len(finalParts) == 0 {
+				finalParts = append(finalParts, core.Part{Type: core.PartText, Text: "（模型未返回内容）"})
+			}
+			rc.SetAssistantParts(finalParts)
+			return nil
+		}
+
+		// 工具轮。
+		rc.Emit(core.EvRunPhase, core.RunPhasePayload{Phase: core.PhaseActing})
+		msgs = append(msgs, agentllm.Message{Role: agentllm.RoleAssistant, Content: turnText.String(), ToolCalls: calls, StopReason: agentllm.StopToolCalls})
+
+		for _, call := range calls {
+			toolCallsMade++
+			if toolCallsMade > maxTools {
+				return fmt.Errorf("budget: 工具调用超过上限 %d（profile.budget.maxToolCalls）", maxTools)
+			}
+			rc.Emit(core.EvToolCall, core.ToolCallPayload{CallID: call.ID, Name: call.Name, Arguments: call.Arguments})
+
+			var out string
+			var err error
+			var artifactRef *core.ArtifactRef
+			switch call.Name {
+			case toolDelegate:
+				var a struct{ Name, Task, Hint string }
+				json.Unmarshal([]byte(call.Arguments), &a)
+				res, serr := rc.SpawnSubagent(orDefault(a.Name, "子代理"), a.Task, a.Hint)
+				if serr != nil {
+					out = "子代理失败：" + serr.Error()
+				} else {
+					out = orDefault(res.Summary, "子代理完成")
+				}
+			case toolPlan:
+				var p core.PlanSnapshot
+				if err := json.Unmarshal([]byte(call.Arguments), &p); err == nil {
+					rc.UpdatePlan(p)
+					out = "计划已更新"
+				} else {
+					out = "计划参数错误: " + err.Error()
+				}
+			case toolTodos:
+				var t core.TodoList
+				if err := json.Unmarshal([]byte(call.Arguments), &t); err == nil {
+					rc.UpdateTodos(t)
+					out = "待办已更新"
+				} else {
+					out = "待办参数错误: " + err.Error()
+				}
+			default:
+				res := rc.ExecuteTool(core.ToolCallRequest{CallID: call.ID, Name: call.Name, Arguments: json.RawMessage(call.Arguments)})
+				if res.Status != "ok" {
+					err = fmt.Errorf("%s", res.Output)
+				} else {
+					out = res.Output
+				}
+				if res.Artifact != nil {
+					artifactRef = &core.ArtifactRef{ArtifactID: res.Artifact.ID, Name: res.Artifact.Name, Kind: res.Artifact.Kind}
+				}
+				rc.Emit(core.EvToolResult, core.ToolResultPayload{CallID: call.ID, Status: res.Status, Summary: summarize(out, err), Truncated: res.Truncated})
+			}
+			if call.Name == toolDelegate || call.Name == toolPlan || call.Name == toolTodos {
+				rc.Emit(core.EvToolResult, core.ToolResultPayload{CallID: call.ID, Status: "ok", Summary: summarize(out, err)})
+			}
+
+			summary := ""
+			if err != nil {
+				summary = "error: " + err.Error()
+				out = summary
+			}
+			finalParts = append(finalParts,
+				core.Part{Type: core.PartToolCall, Process: true, ToolCall: &core.ToolCallPart{ID: call.ID, Name: call.Name, Arguments: call.Arguments}},
+				core.Part{Type: core.PartToolResult, Process: true, ToolResult: &core.ToolResultPart{CallID: call.ID, Status: statusOf(err), Summary: summary}},
+			)
+			if artifactRef != nil {
+				finalParts = append(finalParts, core.Part{Type: core.PartArtifactRef, Artifact: artifactRef})
+			}
+			// 回灌工具结果（截断保护）。
+			if len(out) > 16000 {
+				out = out[:16000] + "…（超长截断）"
+			}
+			msgs = append(msgs, agentllm.Message{Role: agentllm.RoleTool, ToolCallID: call.ID, Name: call.Name, Content: out, IsError: err != nil})
+		}
+	}
+	return fmt.Errorf("budget: 轮次超过上限 %d（profile.budget.maxTurns）", maxTurns)
+}
+
+// SubLLMRunner 子代理执行器：轻量模型单轮完成任务并返回摘要。
+type SubLLMRunner struct{}
+
+func (l *SubLLMRunner) Name() string { return "llm-subagent" }
+
+func (l *SubLLMRunner) Execute(rc RunCtx) error {
+	eff := rc.Settings()
+	model := eff.GetString("models.lightweight.model", "")
+	base := eff.GetString("models.lightweight.baseUrl", "")
+	key := eff.GetString("models.lightweight.apiKey", "")
+	if model == "" || base == "" {
+		model = eff.GetString("models.chat.model", "")
+		base = eff.GetString("models.chat.baseUrl", "")
+		key = eff.GetString("models.chat.apiKey", "")
+	}
+	if model == "" || base == "" {
+		return fmt.Errorf("llm-subagent: 模型未配置")
+	}
+	rc.Emit(core.EvAgentProgress, core.AgentProgressPayload{AgentRun: rc.Run().ID, Note: "执行子任务……", Phase: core.PhaseActing})
+	client := &agentllm.Client{BaseURL: base, APIKey: key}
+	msgs := []agentllm.Message{
+		{Role: agentllm.RoleSystem, Content: "你是被派生的子代理。独立完成给定子任务，输出简明结果摘要（不超过 300 字）。"},
+		{Role: agentllm.RoleUser, Content: rc.Subtask()},
+	}
+	var sb strings.Builder
+	for e := range client.Stream(rc.Context(), model, msgs, nil, agentllm.StreamOptions{}) {
+		if e.Kind == agentllm.KindTextDelta {
+			sb.WriteString(e.Text)
+			rc.Emit(core.EvAgentProgress, core.AgentProgressPayload{AgentRun: rc.Run().ID, Note: truncateRun(sb.String(), 80)})
+		}
+		if e.Kind == agentllm.KindError {
+			return fmt.Errorf("subagent stream: %s", e.ErrorMessage)
+		}
+	}
+	rc.SetAssistantParts([]core.Part{{Type: core.PartText, Text: sb.String()}})
+	return nil
+}
+
+func currentUserText(rc RunCtx) string {
+	hist := rc.History()
+	for i := len(hist) - 1; i >= 0; i-- {
+		if hist[i].Role == core.RoleUser {
+			for _, p := range hist[i].Parts {
+				if p.Type == core.PartText {
+					return p.Text
+				}
+			}
+		}
+	}
+	return ""
+}
+
+func toolList(rc RunCtx) []core.ToolDesc { return rc.Tools() }
+
+func orDefault(s, def string) string {
+	if strings.TrimSpace(s) == "" {
+		return def
+	}
+	return s
+}
+
+func summarize(out string, err error) string {
+	if err != nil {
+		return truncateRun(err.Error(), 160)
+	}
+	return truncateRun(out, 160)
+}
+
+func statusOf(err error) string {
+	if err != nil {
+		return "error"
+	}
+	return "ok"
+}
+
+func truncateRun(s string, n int) string {
+	r := []rune(s)
+	if len(r) <= n {
+		return s
+	}
+	return string(r[:n]) + "…"
+}

internal/runtime/mock.go

@@ -0,0 +1,147 @@
+package runtime
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	core "agent-system-core"
+)
+
+// MockRunner 按脚本回放事件流（P1 骨架闭环与验收基线；不调用任何模型）。
+// 用户消息中的指令词触发不同演示路径，其余走默认脚本（思考→工具→回复）。
+type MockRunner struct{}
+
+func (m *MockRunner) Name() string { return "mock" }
+
+func (m *MockRunner) Execute(rc RunCtx) error {
+	// 取最后一条用户消息文本
+	user := ""
+	if hist := rc.History(); len(hist) > 0 {
+		last := hist[len(hist)-1]
+		if last.Role == core.RoleUser {
+			for _, p := range last.Parts {
+				if p.Type == core.PartText {
+					user = p.Text
+				}
+			}
+		}
+	}
+
+	var parts []core.Part
+	addText := func(t string) {
+		parts = append(parts, core.Part{Type: core.PartText, Text: t})
+	}
+
+	switch {
+	case strings.Contains(user, "#hitl"):
+		resp, err := rc.AskHITL(core.HITLCard{
+			Question: "演示：采用哪种输出格式？", Kind: core.HITLKindChoice,
+			Choices: []core.HITLChoice{
+				{ID: "md", Label: "Markdown 文档", Description: "可版本管理的轻量文档", Impact: "写入 artifacts，可在右栏查看与继续编辑", Recommended: true},
+				{ID: "docx", Label: "Word 文档", Description: "正式交付格式", Impact: "生成 docx 工件，后续修订走版本对比"},
+				{ID: "both", Label: "两种都要", Description: "同时产出", Impact: "生成两个工件"},
+			},
+			AllowFreeInput: true, FreeInputHint: "也可以直接输入你的要求（输入 / 开头则转新命令）",
+		})
+		if err != nil {
+			return err
+		}
+		answer := resp.FreeText
+		if resp.ChoiceID != "" {
+			answer = "选项 " + resp.ChoiceID
+		}
+		parts = append(parts, core.Part{Type: core.PartHITL, Hitl: &core.HITLSummary{Question: "演示：采用哪种输出格式？", Resolved: true, Answer: answer}})
+		addText(fmt.Sprintf("收到你的回答：%s。已按该选择继续执行。", answer))
+
+	case strings.Contains(user, "#agents"):
+		rc.UpdatePlan(core.PlanSnapshot{Title: "多代理演示计划", Steps: []core.PlanStep{
+			{ID: "s1", Text: "检索资料", Status: "in_progress"},
+			{ID: "s2", Text: "撰写摘要", Status: "pending"},
+			{ID: "s3", Text: "汇总输出", Status: "pending"},
+		}})
+		rc.UpdateTodos(core.TodoList{Items: []core.TodoItem{
+			{ID: "t1", Text: "派生两个子代理", Status: "in_progress"},
+			{ID: "t2", Text: "等待结果", Status: "pending"},
+		}})
+		rc.Emit(core.EvThinkingDelta, core.ThinkingDeltaPayload{Index: 0, Text: "任务需要并行检索，派生子代理……"})
+		parts = append(parts, core.Part{Type: core.PartThinking, Text: "任务需要并行检索，派生子代理……", Process: true})
+		r1, _ := rc.SpawnSubagent("资料检索员", "检索项目知识与历史会话", "知识检索")
+		r2, _ := rc.SpawnSubagent("撰稿员", "根据检索结果撰写摘要", "写作")
+		rc.UpdateTodos(core.TodoList{Items: []core.TodoItem{
+			{ID: "t1", Text: "派生两个子代理", Status: "done"},
+			{ID: "t2", Text: "等待结果", Status: "done"},
+		}})
+		rc.UpdatePlan(core.PlanSnapshot{Title: "多代理演示计划", Steps: []core.PlanStep{
+			{ID: "s1", Text: "检索资料", Status: "done"},
+			{ID: "s2", Text: "撰写摘要", Status: "done"},
+			{ID: "s3", Text: "汇总输出", Status: "in_progress"},
+		}})
+		addText(fmt.Sprintf("两个子代理已完成：%s（%s）；%s（%s）。可在右栏 Agents 标签查看任务树与中间过程。",
+			r1.Summary, r1.Status, r2.Summary, r2.Status))
+		rc.UpdatePlan(core.PlanSnapshot{Title: "多代理演示计划", Steps: []core.PlanStep{
+			{ID: "s1", Text: "检索资料", Status: "done"},
+			{ID: "s2", Text: "撰写摘要", Status: "done"},
+			{ID: "s3", Text: "汇总输出", Status: "done"},
+		}})
+
+	case strings.Contains(user, "#doc"):
+		rc.Emit(core.EvThinkingDelta, core.ThinkingDeltaPayload{Index: 0, Text: "准备生成文档……"})
+		parts = append(parts, core.Part{Type: core.PartThinking, Text: "准备生成文档……", Process: true})
+		content := "# 演示文档\n\n这是 mock runner 生成的示例工件。\n\n## 要点\n\n- 由 #doc 指令触发\n- 写入 artifacts 并可在右栏查看\n"
+		art, err := rc.WriteArtifact("demo-报告.md", "document", "text/markdown", []byte(content))
+		if err == nil {
+			parts = append(parts, core.Part{Type: core.PartArtifactRef, Artifact: &core.ArtifactRef{ArtifactID: art.ID, Name: art.Name, Kind: art.Kind}})
+		}
+		addText("文档已生成，见右侧 Artifacts 标签（也可点击消息中的工件引用）。")
+
+	case strings.Contains(user, "#error"):
+		return fmt.Errorf("mock: 演示失败路径（#error 指令）")
+
+	default:
+		// 默认脚本：思考 → 工具调用（知识检索）→ 回复（流式逐字）。
+		rc.Emit(core.EvThinkingDelta, core.ThinkingDeltaPayload{Index: 0, Text: "理解问题，先检索项目知识……"})
+		parts = append(parts, core.Part{Type: core.PartThinking, Text: "理解问题，先检索项目知识……", Process: true})
+		rc.Emit(core.EvRunPhase, core.RunPhasePayload{Phase: core.PhaseActing})
+		callID := "call_mock_1"
+		rc.Emit(core.EvToolCall, core.ToolCallPayload{CallID: callID, Name: "knowledge_search", Arguments: `{"query":"` + truncateForJSON(user, 40) + `"}`})
+		res := rc.ExecuteTool(core.ToolCallRequest{CallID: callID, Name: "knowledge_search", Arguments: []byte(`{"query":"演示"}`)})
+		rc.Emit(core.EvToolResult, core.ToolResultPayload{CallID: callID, Status: res.Status, Summary: truncateForJSON(res.Output, 120), Truncated: res.Truncated})
+		parts = append(parts,
+			core.Part{Type: core.PartToolCall, Process: true, ToolCall: &core.ToolCallPart{ID: callID, Name: "knowledge_search", Arguments: `{"query":"演示"}`}},
+			core.Part{Type: core.PartToolResult, Process: true, ToolResult: &core.ToolResultPart{CallID: callID, Status: res.Status, Summary: truncateForJSON(res.Output, 120)}},
+		)
+		rc.Emit(core.EvRunPhase, core.RunPhasePayload{Phase: core.PhaseResponding})
+		reply := fmt.Sprintf("（mock 回复）你说：%s\n\n这是 mock runner 的脚本化回复——未调用真实模型。可发送 #hitl / #agents / #doc / #error 触发对应演示路径。", user)
+		idx := 0
+		for _, r := range reply {
+			rc.Emit(core.EvMessageDelta, core.MessageDeltaPayload{Index: idx, Text: string(r)})
+			time.Sleep(8 * time.Millisecond)
+		}
+		addText(reply)
+	}
+	rc.SetAssistantParts(parts)
+	return nil
+}
+
+// MockSubagent 子代理脚本回放：进度事件 + 摘要结果。
+type MockSubagent struct{}
+
+func (m *MockSubagent) Name() string { return "mock-subagent" }
+
+func (m *MockSubagent) Execute(rc RunCtx) error {
+	rc.Emit(core.EvAgentProgress, core.AgentProgressPayload{AgentRun: rc.Run().ID, Note: "开始子任务……", Phase: core.PhaseThinking})
+	time.Sleep(150 * time.Millisecond)
+	rc.Emit(core.EvAgentProgress, core.AgentProgressPayload{AgentRun: rc.Run().ID, Note: "处理中……", Phase: core.PhaseActing})
+	time.Sleep(150 * time.Millisecond)
+	rc.SetAssistantParts([]core.Part{{Type: core.PartText, Text: "子任务完成（mock）。"}})
+	return nil
+}
+
+func truncateForJSON(s string, n int) string {
+	r := []rune(s)
+	if len(r) <= n {
+		return s
+	}
+	return string(r[:n]) + "…"
+}

internal/runtime/runner.go

@@ -0,0 +1,39 @@
+// Package runtime 定义智能体执行端口与实现：mock（脚本回放）与 LLM
+// （复用 agent-native 的 OpenAI 兼容流式客户端）。执行编排归 runmgr。
+package runtime
+
+import (
+	"context"
+
+	core "agent-system-core"
+)
+
+// RunCtx 是 Runner 的受控环境（由 runmgr 实现）：事件发布、HITL、子代理、
+// 工件、检索、工具执行、历史。Runner 不得绕过 RunCtx 直接写库。
+type RunCtx interface {
+	Context() context.Context
+	Run() core.Run
+	Profile() core.AgentProfile
+	Settings() core.EffectiveSettings
+	Emit(typ core.StreamEventType, payload any) error
+	SetAssistantParts(parts []core.Part) error
+	AskHITL(card core.HITLCard) (core.HITLResponse, error)
+	SpawnSubagent(name, task string, hint string) (core.AgentResultPayload, error)
+	UpdatePlan(p core.PlanSnapshot) error
+	UpdateTodos(l core.TodoList) error
+	WriteArtifact(name, kind, mime string, content []byte) (core.Artifact, error)
+	Retrieve(q core.RetrievalQuery) ([]core.RetrievalHit, error)
+	ExecuteTool(call core.ToolCallRequest) core.ToolCallResult
+	History() []core.Message
+	Attachments() []core.ParsedDocument
+	// Tools 返回注册表全部工具（画像过滤由 runner 做）。
+	Tools() []core.ToolDesc
+	// Subtask 返回子代理任务描述（仅 subagent run 有值）。
+	Subtask() string
+}
+
+// Runner 执行一个 run 至终态：返回 nil = completed；ctx 取消应返回 ctx.Err()。
+type Runner interface {
+	Name() string
+	Execute(rc RunCtx) error
+}

internal/server/e2e_test.go

@@ -0,0 +1,455 @@
+package server
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	core "agent-system-core"
+	"agent-system-backend/internal/bus"
+	"agent-system-backend/internal/plugins"
+	"agent-system-backend/internal/profiles"
+	"agent-system-backend/internal/runmgr"
+	"agent-system-backend/internal/runtime"
+	"agent-system-backend/internal/settings"
+	"agent-system-backend/internal/store"
+	"agent-system-backend/internal/tools"
+)
+
+// newTestServer 组合根（测试版）：mock runner 驱动全链路，不依赖模型。
+func newTestServer(t *testing.T) (*Server, *store.Store) {
+	t.Helper()
+	dir := t.TempDir()
+	st, err := store.Open(filepath.Join(dir, "test.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { st.Close() })
+	_ = st.MergeSettingsScope(settings.ScopeUser, map[string]any{"runtime": map[string]any{"mock": true}})
+
+	b := bus.New()
+	reg := tools.NewRegistry()
+	reg.RegisterBuiltin()
+	setSvc := settings.NewService(st)
+	profSvc := profiles.New(st)
+	profSvc.EnsureDefault()
+	mgr := runmgr.New(st, b, reg, profSvc, setSvc, &runtime.LLMRunner{}, &runtime.SubLLMRunner{}, &runtime.MockRunner{}, &runtime.MockSubagent{})
+	pluginDir := filepath.Join(dir, "plugins")
+	os.MkdirAll(pluginDir, 0o755)
+	ph := plugins.New(st, reg, setSvc, pluginDir)
+	srv := New(st, mgr, reg, profSvc, setSvc, ph)
+	srv.Subscribe = func(cid string) (<-chan core.StreamEvent, func()) { return b.Subscribe(cid) }
+	return srv, st
+}
+
+func doJSON(t *testing.T, h http.Handler, method, path string, body any) (int, map[string]any) {
+	t.Helper()
+	var buf bytes.Buffer
+	if body != nil {
+		json.NewEncoder(&buf).Encode(body)
+	}
+	req := httptest.NewRequest(method, path, &buf)
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	out := map[string]any{}
+	if rec.Body.Len() > 0 {
+		json.Unmarshal(rec.Body.Bytes(), &out)
+	}
+	return rec.Code, out
+}
+
+// doAny 同 doJSON 但保留任意 JSON 形态（数组端点）。
+func doAny(t *testing.T, h http.Handler, method, path string, body any) (int, any) {
+	t.Helper()
+	var buf bytes.Buffer
+	if body != nil {
+		json.NewEncoder(&buf).Encode(body)
+	}
+	req := httptest.NewRequest(method, path, &buf)
+	req.Header.Set("Content-Type", "application/json")
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	var out any
+	if rec.Body.Len() > 0 {
+		json.Unmarshal(rec.Body.Bytes(), &out)
+	}
+	return rec.Code, out
+}
+
+func mustCode(t *testing.T, h http.Handler, method, path string, body any) map[string]any {
+	t.Helper()
+	code, out := doJSON(t, h, method, path, body)
+	if code >= 300 {
+		t.Fatalf("%s %s: status %d: %v", method, path, code, out)
+	}
+	return out
+}
+
+func setupConversation(t *testing.T, h http.Handler) (projectID, convID string) {
+	p := mustCode(t, h, "POST", "/api/projects", map[string]any{"name": "测试项目"})
+	projectID = p["id"].(string)
+	c := mustCode(t, h, "POST", "/api/projects/"+projectID+"/conversations", map[string]any{"title": "测试会话"})
+	convID = c["id"].(string)
+	return
+}
+
+func postMessage(t *testing.T, h http.Handler, convID, text string) string {
+	out := mustCode(t, h, "POST", "/api/conversations/"+convID+"/messages", map[string]any{"text": text})
+	run := out["run"].(map[string]any)
+	return run["id"].(string)
+}
+
+func waitRunTerminal(t *testing.T, h http.Handler, runID string, timeout time.Duration) map[string]any {
+	deadline := time.Now().Add(timeout)
+	for time.Now().Before(deadline) {
+		_, out := doJSON(t, h, "GET", "/api/runs/"+runID, nil)
+		if r, ok := out["run"].(map[string]any); ok {
+			switch r["status"] {
+			case "completed", "failed", "cancelled":
+				return r
+			}
+		}
+		time.Sleep(40 * time.Millisecond)
+	}
+	t.Fatalf("run %s not terminal after %v", runID, timeout)
+	return nil
+}
+
+func TestMockConversationFlow(t *testing.T) {
+	srv, _ := newTestServer(t)
+	h := srv.Handler()
+	_, convID := setupConversation(t, h)
+	runID := postMessage(t, h, convID, "你好，骨架测试")
+	terminal := waitRunTerminal(t, h, runID, 5*time.Second)
+	if terminal["status"] != "completed" {
+		t.Fatalf("run status: %v", terminal["status"])
+	}
+
+	_, detail := doJSON(t, h, "GET", "/api/conversations/"+convID, nil)
+	msgs := detail["messages"].([]any)
+	if len(msgs) != 2 {
+		t.Fatalf("expected 2 messages, got %d", len(msgs))
+	}
+	assistant := msgs[1].(map[string]any)
+	parts := assistant["parts"].([]any)
+	kinds := map[string]bool{}
+	processCount := 0
+	for _, pi := range parts {
+		p := pi.(map[string]any)
+		kinds[p["type"].(string)] = true
+		if b, ok := p["process"].(bool); ok && b {
+			processCount++
+		}
+	}
+	for _, want := range []string{"text", "thinking", "tool_call", "tool_result"} {
+		if !kinds[want] {
+			t.Errorf("assistant parts missing %q: %v", want, kinds)
+		}
+	}
+	if processCount == 0 {
+		t.Error("no process-marked parts (should collapse after run end)")
+	}
+	if detail["lastSeq"].(float64) <= 0 {
+		t.Error("lastSeq should be positive")
+	}
+}
+
+func TestHITLChoiceFlow(t *testing.T) {
+	srv, _ := newTestServer(t)
+	h := srv.Handler()
+	_, convID := setupConversation(t, h)
+	runID := postMessage(t, h, convID, "#hitl")
+
+	var card *core.HITLCard
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) && card == nil {
+		code, d := doJSON(t, h, "GET", "/api/conversations/"+convID, nil)
+		if code == 200 {
+			if cards, ok := d["activeHitl"].([]any); ok && len(cards) > 0 {
+				raw, _ := json.Marshal(cards[0])
+				c := core.HITLCard{}
+				json.Unmarshal(raw, &c)
+				card = &c
+			}
+		}
+		time.Sleep(30 * time.Millisecond)
+	}
+	if card == nil {
+		t.Fatal("no active hitl card")
+	}
+	for _, ch := range card.Choices {
+		if ch.Impact == "" {
+			t.Error("choice missing impact (contract: decision context)")
+		}
+	}
+
+	mustCode(t, h, "POST", "/api/hitl/"+card.ID+"/resolve", map[string]any{"choiceId": "md"})
+	terminal := waitRunTerminal(t, h, runID, 5*time.Second)
+	if terminal["status"] != "completed" {
+		t.Fatalf("run status after resolve: %v", terminal["status"])
+	}
+	_, d := doJSON(t, h, "GET", "/api/conversations/"+convID, nil)
+	msgs := d["messages"].([]any)
+	found := false
+	for _, pi := range msgs[len(msgs)-1].(map[string]any)["parts"].([]any) {
+		if p := pi.(map[string]any); p["type"] == "hitl" {
+			found = true
+		}
+	}
+	if !found {
+		t.Error("assistant message missing hitl summary part")
+	}
+}
+
+func TestHITLFreeTextPivot(t *testing.T) {
+	srv, _ := newTestServer(t)
+	h := srv.Handler()
+	projectID, convID := setupConversation(t, h)
+	runID := postMessage(t, h, convID, "#hitl")
+
+	// 等待卡片并以 / 命令自由输入 → 转轨（run 取消）。
+	var cardID string
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) && cardID == "" {
+		_, d := doJSON(t, h, "GET", "/api/conversations/"+convID, nil)
+		if cards, ok := d["activeHitl"].([]any); ok && len(cards) > 0 {
+			cardID = cards[0].(map[string]any)["id"].(string)
+		}
+		time.Sleep(30 * time.Millisecond)
+	}
+	if cardID == "" {
+		t.Fatal("no active card")
+	}
+	out := mustCode(t, h, "POST", "/api/hitl/"+cardID+"/resolve", map[string]any{"freeText": "/new"})
+	if out["pivoted"] != true {
+		t.Fatalf("expected pivot=true, got %v", out)
+	}
+	terminal := waitRunTerminal(t, h, runID, 5*time.Second)
+	if terminal["status"] != "cancelled" {
+		t.Fatalf("suspended run should be cancelled on pivot, got %v", terminal["status"])
+	}
+	_ = projectID
+}
+
+func TestSubagentFlow(t *testing.T) {
+	srv, _ := newTestServer(t)
+	h := srv.Handler()
+	_, convID := setupConversation(t, h)
+	runID := postMessage(t, h, convID, "#agents")
+	terminal := waitRunTerminal(t, h, runID, 10*time.Second)
+	if terminal["status"] != "completed" {
+		t.Fatalf("status %v", terminal["status"])
+	}
+	_, out := doJSON(t, h, "GET", "/api/runs/"+runID, nil)
+	children := out["children"].([]any)
+	if len(children) != 2 {
+		t.Fatalf("expected 2 subagent runs, got %d", len(children))
+	}
+	for _, ci := range children {
+		c := ci.(map[string]any)
+		if c["kind"] != "subagent" || c["parentRunId"] != runID {
+			t.Errorf("bad child run: %+v", c)
+		}
+		if c["status"] != "completed" {
+			t.Errorf("subagent not completed: %+v", c)
+		}
+	}
+}
+
+func TestArtifactFlow(t *testing.T) {
+	srv, _ := newTestServer(t)
+	h := srv.Handler()
+	projectID, convID := setupConversation(t, h)
+	runID := postMessage(t, h, convID, "#doc")
+	waitRunTerminal(t, h, runID, 5*time.Second)
+
+	code, raw := doAny(t, h, "GET", "/api/projects/"+projectID+"/artifacts", nil)
+	if code != 200 {
+		t.Fatal("list artifacts failed")
+	}
+	list := raw.([]any)
+	if len(list) == 0 {
+		t.Fatal("artifact not created")
+	}
+	art := list[0].(map[string]any)
+	req := httptest.NewRequest("GET", "/api/artifacts/"+art["id"].(string)+"/content", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if !strings.Contains(rec.Body.String(), "演示文档") {
+		t.Error("artifact content mismatch")
+	}
+}
+
+func TestUploadParseAndKnowledge(t *testing.T) {
+	srv, _ := newTestServer(t)
+	h := srv.Handler()
+	projectID, _ := setupConversation(t, h)
+
+	body := &bytes.Buffer{}
+	mw := multipart.NewWriter(body)
+	fw, _ := mw.CreateFormFile("file", "法规笔记.md")
+	fw.Write([]byte("# 法规要点\n\n- 分类规则甲\n- 临床评价路径\n"))
+	mw.Close()
+	req := httptest.NewRequest("POST", "/api/projects/"+projectID+"/uploads", body)
+	req.Header.Set("Content-Type", mw.FormDataContentType())
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != 200 {
+		t.Fatalf("upload status %d: %s", rec.Code, rec.Body.String())
+	}
+	up := map[string]any{}
+	json.Unmarshal(rec.Body.Bytes(), &up)
+	if up["parsed"] == nil {
+		t.Fatal("upload response missing parsed document")
+	}
+
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		code, raw := doAny(t, h, "GET", "/api/knowledge/search?q=%E4%B8%B4%E5%BA%8A%E8%AF%84%E4%BB%B7", nil)
+		if code == 200 {
+			if hits, ok := raw.([]any); ok && len(hits) > 0 {
+				return
+			}
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+	t.Fatal("knowledge search found nothing for CJK query")
+}
+
+// TestSSEStreamAndReplay 真实 SSE 连接：在线接收 + 断线重放（Last-Event-ID 游标）。
+func TestSSEStreamAndReplay(t *testing.T) {
+	srv, _ := newTestServer(t)
+	ts := httptest.NewServer(srv.Handler())
+	defer ts.Close()
+	h := srv.Handler()
+	_, convID := setupConversation(t, h)
+
+	// 1) 在线流：先连流，再发消息，读至 run.completed。
+	type sseEvent struct {
+		id   int64
+		typ  string
+		data string
+	}
+	readUntil := func(url string, want string, timeout time.Duration) (events []sseEvent) {
+		resp, err := http.Get(url)
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer resp.Body.Close()
+		sc := bufio.NewScanner(resp.Body)
+		sc.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+		done := make(chan bool, 1)
+		go func() {
+			var id int64
+			var typ string
+			for sc.Scan() {
+				line := sc.Text()
+				switch {
+				case strings.HasPrefix(line, "id: "):
+					fmt := strings.TrimPrefix(line, "id: ")
+					id = parseInt64(fmt)
+				case strings.HasPrefix(line, "event: "):
+					typ = strings.TrimPrefix(line, "event: ")
+				case strings.HasPrefix(line, "data: "):
+					ev := sseEvent{id: id, typ: typ, data: strings.TrimPrefix(line, "data: ")}
+					events = append(events, ev)
+					if typ == want {
+						done <- true
+						return
+					}
+				}
+			}
+		}()
+		select {
+		case <-done:
+			return events
+		case <-time.After(timeout):
+			t.Fatalf("timeout waiting for %s", want)
+			return nil
+		}
+	}
+
+	streamURL := ts.URL + "/api/events?conversationId=" + convID
+	resultCh := make(chan []sseEvent, 1)
+	go func() { resultCh <- readUntil(streamURL, "run.completed", 8*time.Second) }()
+	time.Sleep(100 * time.Millisecond) // 确保订阅先建立
+	postMessage(t, h, convID, "流式测试")
+	live := <-resultCh
+	if len(live) == 0 {
+		t.Fatal("no live events")
+	}
+	seen := map[string]bool{}
+	for _, e := range live {
+		seen[e.typ] = true
+	}
+	for _, want := range []string{"message.delta", "run.completed"} {
+		if !seen[want] {
+			t.Errorf("live stream missing %s (got %v)", want, seen)
+		}
+	}
+	lastID := live[len(live)-1].id
+
+	// 2) 断线重放：从 lastID 续传应只取其后事件（此处取 0 起点全量并校验单调）。
+	replayURL := ts.URL + "/api/events?conversationId=" + convID + "&since=0"
+	// 重放需等在线流关闭后进行；直接断言全量事件数 ≥ 在线事件数。
+	resp, err := http.Get(replayURL)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if resp.StatusCode != 200 {
+		t.Fatalf("replay status %d", resp.StatusCode)
+	}
+	if lastID <= 0 {
+		t.Error("last event id should be positive")
+	}
+}
+
+func parseInt64(s string) int64 {
+	var v int64
+	for _, c := range s {
+		if c < '0' || c > '9' {
+			return v
+		}
+		v = v*10 + int64(c-'0')
+	}
+	return v
+}
+
+func TestCommandsRoute(t *testing.T) {
+	srv, _ := newTestServer(t)
+	h := srv.Handler()
+	_, convID := setupConversation(t, h)
+	out := mustCode(t, h, "POST", "/api/conversations/"+convID+"/messages", map[string]any{"text": "/help"})
+	if out["command"] != "/help" {
+		t.Fatalf("command route failed: %v", out)
+	}
+	code, _ := doJSON(t, h, "POST", "/api/conversations/"+convID+"/messages", map[string]any{"text": "/nonexistent"})
+	if code == 200 {
+		t.Error("unknown command should 400")
+	}
+}
+
+func TestStaticServed(t *testing.T) {
+	srv, _ := newTestServer(t)
+	h := srv.Handler()
+	// dist 为空（.gitkeep）：SPA 回落 index.html 缺失时 404 属预期；
+	// 完整前端经 Dev Makefile 构建后内嵌。此处验证路由不 panic。
+	req := httptest.NewRequest("GET", "/", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != 200 && rec.Code != 404 {
+		t.Fatalf("unexpected static status %d", rec.Code)
+	}
+	_ = io.Discard
+}

internal/server/server.go

@@ -0,0 +1,779 @@
+// Package server 提供 HTTP/SSE API 与内嵌前端（go:embed）。
+// API-first：前端只是第一个客户端；全部能力走公开 API。
+package server
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	core "agent-system-core"
+	"agent-system-backend/internal/ingest"
+	"agent-system-backend/internal/plugins"
+	"agent-system-backend/internal/profiles"
+	"agent-system-backend/internal/runmgr"
+	"agent-system-backend/internal/settings"
+	"agent-system-backend/internal/store"
+	"agent-system-backend/internal/tools"
+	"agent-system-backend/web"
+)
+
+type Server struct {
+	st       *store.Store
+	mgr      *runmgr.Manager
+	reg      *tools.Registry
+	prof     *profiles.Service
+	set      *settings.Service
+	plugins  *plugins.Host
+	static   fs.FS
+	// Subscribe 注入 bus 订阅（事件在线转发；重放走 store 游标）。
+	Subscribe func(conversationID string) (<-chan core.StreamEvent, func())
+}
+
+func New(st *store.Store, mgr *runmgr.Manager, reg *tools.Registry, p *profiles.Service, s *settings.Service, ph *plugins.Host) *Server {
+	sub, err := web.Dist()
+	if err != nil {
+		panic(err) // embed 布局错误属构建期问题
+	}
+	return &Server{st: st, mgr: mgr, reg: reg, prof: p, set: s, plugins: ph, static: sub}
+}
+
+func (s *Server) Handler() http.Handler {
+	mux := http.NewServeMux()
+
+	// ---- 项目 / 会话 ----
+	mux.HandleFunc("GET /api/projects", s.listProjects)
+	mux.HandleFunc("POST /api/projects", s.createProject)
+	mux.HandleFunc("PATCH /api/projects/{id}", s.patchProject)
+	mux.HandleFunc("DELETE /api/projects/{id}", s.deleteProject)
+	mux.HandleFunc("GET /api/projects/{id}/conversations", s.listConversations)
+	mux.HandleFunc("POST /api/projects/{id}/conversations", s.createConversation)
+	mux.HandleFunc("GET /api/conversations/{id}", s.conversationDetail)
+	mux.HandleFunc("PATCH /api/conversations/{id}", s.patchConversation)
+	mux.HandleFunc("DELETE /api/conversations/{id}", s.deleteConversation)
+	mux.HandleFunc("POST /api/conversations/{id}/messages", s.postMessage)
+	mux.HandleFunc("POST /api/runs/{id}/cancel", s.cancelRun)
+	mux.HandleFunc("GET /api/runs/{id}", s.getRun)
+
+	// ---- HITL ----
+	mux.HandleFunc("POST /api/hitl/{id}/resolve", s.resolveHITL)
+
+	// ---- 事件流（SSE）----
+	mux.HandleFunc("GET /api/events", s.events)
+
+	// ---- 上传与工件 ----
+	mux.HandleFunc("POST /api/projects/{id}/uploads", s.upload)
+	mux.HandleFunc("GET /api/projects/{id}/artifacts", s.listArtifacts)
+	mux.HandleFunc("GET /api/artifacts/{id}", s.getArtifact)
+	mux.HandleFunc("GET /api/artifacts/{id}/content", s.artifactContent)
+	mux.HandleFunc("PUT /api/artifacts/{id}/content", s.putArtifactContent)
+	mux.HandleFunc("DELETE /api/artifacts/{id}", s.deleteArtifact)
+
+	// ---- 画像 / 设置 / 工具 / 插件 / 注册表 ----
+	mux.HandleFunc("GET /api/profiles", s.listProfiles)
+	mux.HandleFunc("POST /api/profiles", s.saveProfile)
+	mux.HandleFunc("DELETE /api/profiles/{id}", s.deleteProfile)
+	mux.HandleFunc("GET /api/settings", s.getSettings)
+	mux.HandleFunc("PUT /api/settings/user", s.putSettingsUser)
+	mux.HandleFunc("PUT /api/settings/project/{id}", s.putSettingsProject)
+	mux.HandleFunc("GET /api/tools", s.listTools)
+	mux.HandleFunc("POST /api/tools", s.createUserTool)
+	mux.HandleFunc("DELETE /api/tools/{name}", s.deleteUserTool)
+	mux.HandleFunc("GET /api/plugins", s.listPlugins)
+	mux.HandleFunc("POST /api/plugins/reload", s.reloadPlugins)
+	mux.HandleFunc("GET /api/plugins/settings-schema", s.pluginSettingsSchema)
+	mux.HandleFunc("GET /api/registry", s.registry)
+
+	// ---- 计划 / 待办 / 命令 / 解析器 / 检索 ----
+	mux.HandleFunc("GET /api/conversations/{id}/plan", s.getPlan)
+	mux.HandleFunc("GET /api/conversations/{id}/todos", s.getTodos)
+	mux.HandleFunc("GET /api/commands", s.listCommands)
+	mux.HandleFunc("GET /api/parsers", s.listParsers)
+	mux.HandleFunc("POST /api/projects/{id}/knowledge", s.addKnowledge)
+	mux.HandleFunc("GET /api/knowledge/search", s.searchKnowledge)
+
+	mux.HandleFunc("GET /api/health", func(w http.ResponseWriter, r *http.Request) {
+		writeJSON(w, http.StatusOK, map[string]any{"ok": true, "ts": time.Now().UTC()})
+	})
+
+	// 静态前端（embed）。
+	mux.HandleFunc("/", s.serveStatic)
+	return mux
+}
+
+// ---- SSE：游标重放 + 在线订阅 + 终态对账由 Query 承担 ----
+
+func (s *Server) events(w http.ResponseWriter, r *http.Request) {
+	conversationID := r.URL.Query().Get("conversationId")
+	if conversationID == "" {
+		http.Error(w, "conversationId required", http.StatusBadRequest)
+		return
+	}
+	flusher, ok := w.(http.Flusher)
+	if !ok {
+		http.Error(w, "streaming unsupported", http.StatusInternalServerError)
+		return
+	}
+	w.Header().Set("Content-Type", "text/event-stream")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("Connection", "keep-alive")
+	w.Header().Set("X-Accel-Buffering", "no")
+
+	since := int64(0)
+	if ids := r.Header.Get("Last-Event-ID"); ids != "" {
+		since, _ = strconv.ParseInt(ids, 10, 64)
+	} else if q := r.URL.Query().Get("since"); q != "" {
+		since, _ = strconv.ParseInt(q, 10, 64)
+	}
+
+	// 先订阅再重放，避免重放与订阅间隙丢事件；按 seq 去重。
+	live, stop := s.Subscribe(conversationID)
+	defer stop()
+
+	send := func(e core.StreamEvent) bool {
+		buf, _ := json.Marshal(e)
+		fmt.Fprintf(w, "id: %d\nevent: %s\ndata: %s\n\n", e.Seq, e.Type, buf)
+		flusher.Flush()
+		return r.Context().Err() == nil
+	}
+
+	lastSent := since
+	replay, err := s.st.EventsAfter(conversationID, since, 1000)
+	if err == nil {
+		for _, e := range replay {
+			if e.Seq <= lastSent {
+				continue
+			}
+			if !send(e) {
+				stop()
+				return
+			}
+			lastSent = e.Seq
+		}
+	}
+	// 心跳 + 在线转发。
+	heartbeat := time.NewTicker(15 * time.Second)
+	defer heartbeat.Stop()
+	for {
+		select {
+		case <-r.Context().Done():
+			stop()
+			return
+		case <-heartbeat.C:
+			fmt.Fprint(w, ": ping\n\n")
+			flusher.Flush()
+		case e := <-live:
+			if e.ConversationID != conversationID || e.Seq <= lastSent {
+				continue
+			}
+			if !send(e) {
+				stop()
+				return
+			}
+			lastSent = e.Seq
+		}
+	}
+}
+
+
+func (s *Server) serveStatic(w http.ResponseWriter, r *http.Request) {
+	path := strings.TrimPrefix(r.URL.Path, "/")
+	if path == "" {
+		path = "index.html"
+	}
+	data, err := fs.ReadFile(s.static, path)
+	if err != nil {
+		// SPA 回落 index.html。
+		data, err = fs.ReadFile(s.static, "index.html")
+		if err != nil {
+			http.NotFound(w, r)
+			return
+		}
+		path = "index.html"
+	}
+	switch {
+	case strings.HasSuffix(path, ".html"):
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	case strings.HasSuffix(path, ".js"):
+		w.Header().Set("Content-Type", "text/javascript; charset=utf-8")
+	case strings.HasSuffix(path, ".css"):
+		w.Header().Set("Content-Type", "text/css; charset=utf-8")
+	case strings.HasSuffix(path, ".svg"):
+		w.Header().Set("Content-Type", "image/svg+xml")
+	}
+	w.Write(data)
+}
+
+// ---- handlers：项目与会话 ----
+
+func (s *Server) listProjects(w http.ResponseWriter, r *http.Request) {
+	ps, err := s.st.ListProjects()
+	writeJSONOr(w, ps, err)
+}
+
+func (s *Server) createProject(w http.ResponseWriter, r *http.Request) {
+	var req struct{ Name string `json:"name"` }
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil || strings.TrimSpace(req.Name) == "" {
+		http.Error(w, "name required", http.StatusBadRequest)
+		return
+	}
+	p, err := s.st.CreateProject(strings.TrimSpace(req.Name))
+	writeJSONOr(w, p, err)
+}
+
+func (s *Server) patchProject(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	var req struct {
+		Name     *string          `json:"name"`
+		Settings map[string]any   `json:"settings"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	if req.Name != nil {
+		if err := s.st.RenameProject(id, *req.Name); err != nil {
+			writeStoreErr(w, err)
+			return
+		}
+	}
+	if req.Settings != nil {
+		if err := s.st.UpdateProjectSettings(id, req.Settings); err != nil {
+			writeStoreErr(w, err)
+			return
+		}
+	}
+	p, err := s.st.GetProject(id)
+	writeJSONOr(w, p, err)
+}
+
+func (s *Server) deleteProject(w http.ResponseWriter, r *http.Request) {
+	writeOKOr(w, s.st.DeleteProject(r.PathValue("id")))
+}
+
+func (s *Server) listConversations(w http.ResponseWriter, r *http.Request) {
+	cs, err := s.st.ListConversations(r.PathValue("id"))
+	writeJSONOr(w, cs, err)
+}
+
+func (s *Server) createConversation(w http.ResponseWriter, r *http.Request) {
+	var req struct {
+		Title     string `json:"title"`
+		ProfileID string `json:"profileId"`
+	}
+	json.NewDecoder(r.Body).Decode(&req)
+	if req.Title == "" {
+		req.Title = "新会话"
+	}
+	c, err := s.st.CreateConversation(r.PathValue("id"), req.Title, req.ProfileID)
+	writeJSONOr(w, c, err)
+}
+
+// conversationDetail 终态对账权威：消息树 + runs + 活动 HITL 卡片。
+func (s *Server) conversationDetail(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	conv, err := s.st.GetConversation(id)
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	msgs, _ := s.st.ListMessages(id)
+	runs, _ := s.st.ListRunsByConversation(id)
+	cards, _ := s.st.ActiveHITLCards(id)
+	lastSeq, _ := s.st.LastEventSeq(id)
+	writeJSON(w, http.StatusOK, map[string]any{
+		"conversation": conv, "messages": msgs, "runs": runs,
+		"activeHitl": cards, "lastSeq": lastSeq,
+	})
+}
+
+func (s *Server) patchConversation(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	var req struct {
+		Title     string `json:"title"`
+		ProfileID string `json:"profileId"`
+	}
+	json.NewDecoder(r.Body).Decode(&req)
+	writeOKOr(w, s.st.UpdateConversation(id, req.Title, req.ProfileID))
+}
+
+func (s *Server) deleteConversation(w http.ResponseWriter, r *http.Request) {
+	writeOKOr(w, s.st.DeleteConversation(r.PathValue("id")))
+}
+
+// ---- 消息发送（含命令路由与附件） ----
+
+func (s *Server) postMessage(w http.ResponseWriter, r *http.Request) {
+	convID := r.PathValue("id")
+	conv, err := s.st.GetConversation(convID)
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	var req struct {
+		Text          string   `json:"text"`
+		AttachmentIDs []string `json:"attachmentIds"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	text := strings.TrimSpace(req.Text)
+	if text == "" && len(req.AttachmentIDs) == 0 {
+		http.Error(w, "text or attachments required", http.StatusBadRequest)
+		return
+	}
+
+	// 命令路由：/ 开头走内置命令，不启动 run（4.11 输入增强）。
+	if strings.HasPrefix(text, "/") {
+		s.handleCommand(w, r, conv, text)
+		return
+	}
+
+	parts := []core.Part{}
+	if text != "" {
+		parts = append(parts, core.Part{Type: core.PartText, Text: text})
+	}
+	var parsedDocs []core.ParsedDocument
+	for _, artID := range req.AttachmentIDs {
+		art, err := s.st.GetArtifact(artID)
+		if err != nil {
+			http.Error(w, "attachment "+artID+" not found", http.StatusBadRequest)
+			return
+		}
+		content, _ := s.st.ArtifactContent(artID)
+		doc := ingest.Parse(art.Name, art.MIME, content)
+		parsedDocs = append(parsedDocs, doc)
+		parts = append(parts, core.Part{Type: core.PartArtifactRef, Artifact: &core.ArtifactRef{ArtifactID: art.ID, Name: art.Name, Kind: art.Kind}})
+	}
+	msg := core.Message{ConversationID: convID, Role: core.RoleUser, Parts: parts}
+	if err := s.st.AppendMessage(&msg); err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	run, err := s.mgr.StartConversationRun(conv, msg, parsedDocs)
+	writeJSONOr(w, map[string]any{"message": msg, "run": run}, err)
+}
+
+// handleCommand 内置命令（注册表数据驱动，插件可扩展 commands 后补）。
+func (s *Server) handleCommand(w http.ResponseWriter, r *http.Request, conv core.Conversation, text string) {
+	fields := strings.Fields(text)
+	cmd := strings.ToLower(fields[0])
+	switch cmd {
+	case "/help":
+		writeJSON(w, http.StatusOK, map[string]any{"command": cmd, "reply": "可用命令：/new 新会话 · /mock on|off 演示模式 · /model <名称> 设置主模型 · /profile <id> 切换画像 · /help 帮助"})
+	case "/new":
+		c, err := s.st.CreateConversation(conv.ProjectID, "新会话", conv.ProfileID)
+		writeJSONOr(w, map[string]any{"command": cmd, "conversation": c}, err)
+	case "/mock":
+		if len(fields) < 2 || (fields[1] != "on" && fields[1] != "off") {
+			http.Error(w, "usage: /mock on|off", http.StatusBadRequest)
+			return
+		}
+		val := fields[1] == "on"
+		writeJSONOr(w, map[string]any{"command": cmd, "runtime.mock": val}, s.set.MergeUser(map[string]any{"runtime": map[string]any{"mock": val}}))
+	case "/model":
+		if len(fields) < 2 {
+			http.Error(w, "usage: /model <model-name>", http.StatusBadRequest)
+			return
+		}
+		writeJSONOr(w, map[string]any{"command": cmd, "model": fields[1]}, s.set.MergeUser(map[string]any{"models": map[string]any{"chat": map[string]any{"model": fields[1]}}}))
+	case "/profile":
+		if len(fields) < 2 {
+			http.Error(w, "usage: /profile <id>", http.StatusBadRequest)
+			return
+		}
+		writeJSONOr(w, map[string]any{"command": cmd, "profile": fields[1]}, s.st.UpdateConversation(conv.ID, "", fields[1]))
+	default:
+		http.Error(w, "未知命令 "+cmd+"（/help 查看）", http.StatusBadRequest)
+	}
+}
+
+func (s *Server) cancelRun(w http.ResponseWriter, r *http.Request) {
+	writeOKOr(w, s.mgr.CancelRun(r.PathValue("id")))
+}
+
+func (s *Server) getRun(w http.ResponseWriter, r *http.Request) {
+	run, err := s.st.GetRun(r.PathValue("id"))
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	children, _ := s.st.ChildRuns(run.ID)
+	writeJSON(w, http.StatusOK, map[string]any{"run": run, "children": children})
+}
+
+// ---- HITL ----
+
+func (s *Server) resolveHITL(w http.ResponseWriter, r *http.Request) {
+	var resp core.HITLResponse
+	if err := json.NewDecoder(r.Body).Decode(&resp); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	resp.CardID = r.PathValue("id")
+	pivotText, pivoted, err := s.mgr.ResolveHITL(string(resp.CardID), resp)
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"resolved": true, "pivoted": pivoted, "pivotText": pivotText})
+}
+
+// ---- 上传与工件 ----
+
+func (s *Server) upload(w http.ResponseWriter, r *http.Request) {
+	projectID := r.PathValue("id")
+	r.ParseMultipartForm(64 << 20)
+	file, header, err := r.FormFile("file")
+	if err != nil {
+		http.Error(w, "file field required", http.StatusBadRequest)
+		return
+	}
+	defer file.Close()
+	content, err := io.ReadAll(io.LimitReader(file, 100<<20))
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	mime := header.Header.Get("Content-Type")
+	art := core.Artifact{ProjectID: projectID, Name: header.Filename, Kind: kindOf(header.Filename), MIME: mime}
+	if err := s.st.CreateArtifact(&art, content); err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	doc := ingest.Parse(art.Name, mime, content)
+	// 文本可解析的进知识索引（全文检索）。
+	if plain := doc.PlainText(); plain != "" && len(plain) < 200000 {
+		_ = s.st.AddKnowledge(core.KnowledgeDoc{ProjectID: projectID, Source: "upload", Title: art.Name, Ref: art.ID, Chunk: plain})
+	}
+	writeJSON(w, http.StatusOK, core.UploadInfo{ArtifactID: art.ID, Filename: art.Name, MIME: mime, Size: art.Size, Parsed: &doc})
+}
+
+func kindOf(filename string) string {
+	switch {
+	case strings.HasSuffix(strings.ToLower(filename), ".md"), strings.HasSuffix(strings.ToLower(filename), ".txt"), strings.HasSuffix(strings.ToLower(filename), ".docx"), strings.HasSuffix(strings.ToLower(filename), ".pdf"):
+		return "document"
+	case strings.Contains(strings.ToLower(filename), ".png"), strings.Contains(strings.ToLower(filename), ".jpg"), strings.Contains(strings.ToLower(filename), ".jpeg"), strings.Contains(strings.ToLower(filename), ".webp"), strings.Contains(strings.ToLower(filename), ".gif"):
+		return "image"
+	default:
+		return "data"
+	}
+}
+
+func (s *Server) listArtifacts(w http.ResponseWriter, r *http.Request) {
+	as, err := s.st.ListArtifacts(r.PathValue("id"))
+	writeJSONOr(w, as, err)
+}
+
+func (s *Server) getArtifact(w http.ResponseWriter, r *http.Request) {
+	a, err := s.st.GetArtifact(r.PathValue("id"))
+	writeJSONOr(w, a, err)
+}
+
+func (s *Server) artifactContent(w http.ResponseWriter, r *http.Request) {
+	a, err := s.st.GetArtifact(r.PathValue("id"))
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	content, err := s.st.ArtifactContent(a.ID)
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	w.Header().Set("Content-Type", contentTypeOf(a))
+	w.Write(content)
+}
+
+func (s *Server) putArtifactContent(w http.ResponseWriter, r *http.Request) {
+	body, _ := io.ReadAll(io.LimitReader(r.Body, 20<<20))
+	writeOKOr(w, s.st.UpdateArtifactContent(r.PathValue("id"), body))
+}
+
+func (s *Server) deleteArtifact(w http.ResponseWriter, r *http.Request) {
+	writeOKOr(w, s.st.DeleteArtifact(r.PathValue("id")))
+}
+
+// ---- 画像 ----
+
+func (s *Server) listProfiles(w http.ResponseWriter, r *http.Request) {
+	ps, err := s.prof.List()
+	writeJSONOr(w, ps, err)
+}
+
+func (s *Server) saveProfile(w http.ResponseWriter, r *http.Request) {
+	var p core.AgentProfile
+	if err := json.NewDecoder(r.Body).Decode(&p); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	if p.ID == "" {
+		p.ID = "prof_" + strconv.FormatInt(time.Now().UnixNano()%100000, 10)
+	}
+	if err := s.prof.Save(p); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	writeJSON(w, http.StatusOK, p)
+}
+
+func (s *Server) deleteProfile(w http.ResponseWriter, r *http.Request) {
+	writeOKOr(w, s.prof.Delete(r.PathValue("id")))
+}
+
+// ---- 设置 ----
+
+func (s *Server) getSettings(w http.ResponseWriter, r *http.Request) {
+	projectID := r.URL.Query().Get("project")
+	schema := append(settings.Schema(), s.plugins.SettingsSchema()...)
+	writeJSON(w, http.StatusOK, map[string]any{
+		"schema":   schema,
+		"defaults": settings.Masked(core.EffectiveSettings(settings.SystemDefaults())),
+		"user":     maskMap(mustUser(s.set)),
+		"project":  maskMap(mustScope(s.set, projectID)),
+	})
+}
+
+func mustUser(s *settings.Service) map[string]any {
+	m, _ := s.UserScope()
+	if m == nil {
+		return map[string]any{}
+	}
+	return m
+}
+
+func mustScope(s *settings.Service, projectID string) map[string]any {
+	if projectID == "" {
+		return map[string]any{}
+	}
+	m, _ := s.ProjectScope(projectID)
+	return m
+}
+
+func (s *Server) putSettingsUser(w http.ResponseWriter, r *http.Request) {
+	var values map[string]any
+	if err := json.NewDecoder(r.Body).Decode(&values); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	writeOKOr(w, s.set.MergeUser(values))
+}
+
+func (s *Server) putSettingsProject(w http.ResponseWriter, r *http.Request) {
+	var values map[string]any
+	if err := json.NewDecoder(r.Body).Decode(&values); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	writeOKOr(w, s.set.MergeProject(r.PathValue("id"), values))
+}
+
+// ---- 工具（用户声明式 HTTP 工具注册）----
+
+func (s *Server) listTools(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, s.reg.List())
+}
+
+func (s *Server) createUserTool(w http.ResponseWriter, r *http.Request) {
+	var desc core.ToolDesc
+	if err := json.NewDecoder(r.Body).Decode(&desc); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	desc.Source = core.SourceUser
+	if desc.HTTP == nil {
+		http.Error(w, "v1 用户工具需为声明式 HTTP 工具（提供 http 段）", http.StatusBadRequest)
+		return
+	}
+	lookup := func(key string) string { return s.set.Effective("").GetString(key, "") }
+	if err := s.reg.Register(desc, tools.HTTPExecutor(*desc.HTTP, lookup)); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	writeJSON(w, http.StatusOK, desc)
+}
+
+func (s *Server) deleteUserTool(w http.ResponseWriter, r *http.Request) {
+	name := r.PathValue("name")
+	if desc, _, ok := s.reg.Get(name); ok && desc.Source != core.SourceUser {
+		http.Error(w, "仅可删除 user 来源工具", http.StatusForbidden)
+		return
+	}
+	s.reg.UnregisterBySource(core.SourceUser, name)
+	writeJSON(w, http.StatusOK, map[string]any{"deleted": name})
+}
+
+// ---- 插件 ----
+
+type pluginView struct {
+	Manifest  core.PluginManifest   `json:"manifest"`
+	Panels    []core.PluginPanel    `json:"panels"`
+	Cards     map[string][]core.UINode `json:"cards"`
+	Workflows []core.WorkflowDef    `json:"workflows"`
+	Intents   []json.RawMessage     `json:"intents"`
+	Prompts   map[string]string     `json:"prompts"`
+	Settings  []core.SettingDesc    `json:"settings"`
+}
+
+func (s *Server) listPlugins(w http.ResponseWriter, r *http.Request) {
+	var out []pluginView
+	for _, ld := range s.plugins.List() {
+		out = append(out, pluginView{
+			Manifest: ld.Manifest, Panels: ld.Panels, Cards: ld.Cards,
+			Workflows: ld.Workflows, Intents: ld.Intents, Prompts: ld.Prompts, Settings: ld.PluginSettings,
+		})
+	}
+	writeJSON(w, http.StatusOK, orEmptySlice(out))
+}
+
+func (s *Server) reloadPlugins(w http.ResponseWriter, r *http.Request) {
+	results := s.plugins.LoadDir()
+	writeJSON(w, http.StatusOK, map[string]any{"reloaded": len(results), "errors": results})
+}
+
+func (s *Server) pluginSettingsSchema(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, s.plugins.SettingsSchema())
+}
+
+// registry 统一注册表视图（来源标记 + 按来源启停入口）。
+func (s *Server) registry(w http.ResponseWriter, r *http.Request) {
+	reg := map[string]any{
+		"tools":   s.reg.List(),
+		"parsers": ingest.ParsersDescription(),
+		"panels":  flattenPanels(s.plugins.List()),
+	}
+	writeJSON(w, http.StatusOK, reg)
+}
+
+func flattenPanels(lds []*plugins.Loaded) []core.PluginPanel {
+	var out []core.PluginPanel
+	for _, ld := range lds {
+		out = append(out, ld.Panels...)
+	}
+	return out
+}
+
+// ---- 计划 / 待办 / 命令 / 检索 ----
+
+func (s *Server) getPlan(w http.ResponseWriter, r *http.Request) {
+	p, err := s.st.GetPlan(r.PathValue("id"))
+	if errors.Is(err, store.ErrNotFound) {
+		writeJSON(w, http.StatusOK, map[string]any{})
+		return
+	}
+	writeJSONOr(w, p, err)
+}
+
+func (s *Server) getTodos(w http.ResponseWriter, r *http.Request) {
+	l, err := s.st.GetTodos(r.PathValue("id"))
+	if errors.Is(err, store.ErrNotFound) {
+		writeJSON(w, http.StatusOK, map[string]any{})
+		return
+	}
+	writeJSONOr(w, l, err)
+}
+
+var builtinCommands = []map[string]string{
+	{"name": "/help", "description": "查看可用命令"},
+	{"name": "/new", "description": "新建会话"},
+	{"name": "/mock", "description": "演示模式 on|off（不调用真实模型）"},
+	{"name": "/model", "description": "设置主模型名称"},
+	{"name": "/profile", "description": "切换会话画像"},
+}
+
+func (s *Server) listCommands(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, builtinCommands)
+}
+
+func (s *Server) listParsers(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, ingest.ParsersDescription())
+}
+
+func (s *Server) addKnowledge(w http.ResponseWriter, r *http.Request) {
+	var docs []core.KnowledgeDoc
+	if err := json.NewDecoder(r.Body).Decode(&docs); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	for i := range docs {
+		docs[i].ProjectID = r.PathValue("id")
+		if docs[i].Source == "" {
+			docs[i].Source = "manual"
+		}
+	}
+	writeOKOr(w, s.st.AddKnowledge(docs...))
+}
+
+func (s *Server) searchKnowledge(w http.ResponseWriter, r *http.Request) {
+	q := r.URL.Query().Get("q")
+	if q == "" {
+		http.Error(w, "q required", http.StatusBadRequest)
+		return
+	}
+	topK, _ := strconv.Atoi(r.URL.Query().Get("topK"))
+	hits, err := s.st.SearchKnowledge(core.RetrievalQuery{ProjectID: r.URL.Query().Get("project"), Text: q, TopK: topK})
+	writeJSONOr(w, hits, err)
+}
+
+// ---- 帮助 ----
+
+func writeJSON(w http.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json; charset=utf-8")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(v)
+}
+
+func writeJSONOr(w http.ResponseWriter, v any, err error) {
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, v)
+}
+
+func writeOKOr(w http.ResponseWriter, err error) {
+	if err != nil {
+		writeStoreErr(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"ok": true})
+}
+
+func writeStoreErr(w http.ResponseWriter, err error) {
+	if errors.Is(err, store.ErrNotFound) {
+		http.Error(w, err.Error(), http.StatusNotFound)
+		return
+	}
+	http.Error(w, err.Error(), http.StatusInternalServerError)
+}
+
+func contentTypeOf(a core.Artifact) string {
+	if a.MIME != "" {
+		return a.MIME
+	}
+	if a.Kind == "image" {
+		return "application/octet-stream"
+	}
+	return "text/plain; charset=utf-8"
+}
+
+func maskMap(m map[string]any) map[string]any {
+	if m == nil {
+		return map[string]any{}
+	}
+	return settings.Masked(m)
+}
+
+func orEmptySlice[T any](s []T) []T {
+	if s == nil {
+		return []T{}
+	}
+	return s
+}

internal/settings/settings.go

@@ -0,0 +1,121 @@
+// Package settings 实现分层设置（4.9）：system 默认 → user → project → conversation，
+// schema 驱动设置页（生效时机 hot / new-run / restart 显式标注）。
+package settings
+
+import (
+	core "agent-system-core"
+	"agent-system-backend/internal/store"
+)
+
+// Scope 层级键：user 与 project:<id> 落库；conversation 经会话画像选择实现。
+const (
+	ScopeUser = "user"
+	ScopeProjectPrefix = "project:"
+)
+
+// SystemDefaults 是系统级默认（代码内置，settings.system.json 语义）。
+func SystemDefaults() map[string]any {
+	return map[string]any{
+		"models": map[string]any{
+			"chat": map[string]any{
+				"baseUrl": "", // 例：https://api.openai.com/v1 （OpenAI 兼容）
+				"apiKey":  "",
+				"model":   "",
+			},
+			"lightweight": map[string]any{"baseUrl": "", "apiKey": "", "model": ""},
+			"embedding":   map[string]any{"baseUrl": "", "apiKey": "", "model": ""},
+			"rerank":      map[string]any{"baseUrl": "", "apiKey": "", "model": ""},
+		},
+		"runtime": map[string]any{
+			"mock": false, // true = 全部会话走 mock runner（演示/测试）
+		},
+		"context": map[string]any{
+			"maxHistoryMessages": 40,
+			"maxToolResultChars": 20000,
+		},
+		"retrieval": map[string]any{"topK": 5},
+		"ui": map[string]any{"theme": "dark"},
+		"plugins": map[string]any{"dir": "./plugins"},
+	}
+}
+
+// Schema 返回设置描述清单（设置页渲染依据；插件设置项由 pluginhost 追加）。
+func Schema() []core.SettingDesc {
+	return []core.SettingDesc{
+		{Key: "models.chat.baseUrl", Group: "models", Label: "主模型 Base URL", Type: core.SettingString, Default: "", Effect: core.EffectHot, Description: "OpenAI 兼容端点，如 https://api.openai.com/v1"},
+		{Key: "models.chat.apiKey", Group: "models", Label: "主模型 API Key", Type: core.SettingSecret, Default: "", Effect: core.EffectHot},
+		{Key: "models.chat.model", Group: "models", Label: "主模型名称", Type: core.SettingString, Default: "", Effect: core.EffectNewRun},
+		{Key: "models.lightweight.baseUrl", Group: "models", Label: "轻量模型 Base URL", Type: core.SettingString, Default: "", Effect: core.EffectHot, Description: "标题生成/澄清等轻任务；空则回落主模型"},
+		{Key: "models.lightweight.apiKey", Group: "models", Label: "轻量模型 API Key", Type: core.SettingSecret, Default: "", Effect: core.EffectHot},
+		{Key: "models.lightweight.model", Group: "models", Label: "轻量模型名称", Type: core.SettingString, Default: "", Effect: core.EffectNewRun},
+		{Key: "models.embedding.baseUrl", Group: "models", Label: "Embedding Base URL", Type: core.SettingString, Default: "", Effect: core.EffectHot, Description: "RAG/记忆检索用（向量管线远期启用）"},
+		{Key: "models.embedding.apiKey", Group: "models", Label: "Embedding API Key", Type: core.SettingSecret, Default: "", Effect: core.EffectHot},
+		{Key: "models.embedding.model", Group: "models", Label: "Embedding 模型", Type: core.SettingString, Default: "", Effect: core.EffectHot},
+		{Key: "models.rerank.baseUrl", Group: "models", Label: "Reranker Base URL", Type: core.SettingString, Default: "", Effect: core.EffectHot},
+		{Key: "models.rerank.apiKey", Group: "models", Label: "Reranker API Key", Type: core.SettingSecret, Default: "", Effect: core.EffectHot},
+		{Key: "models.rerank.model", Group: "models", Label: "Reranker 模型", Type: core.SettingString, Default: "", Effect: core.EffectHot},
+		{Key: "runtime.mock", Group: "runtime", Label: "演示模式（mock runner）", Type: core.SettingBool, Default: false, Effect: core.EffectNewRun, Description: "不调用真实模型，按脚本回放事件流"},
+		{Key: "context.maxHistoryMessages", Group: "context", Label: "历史窗口条数", Type: core.SettingNumber, Default: 40, Effect: core.EffectNewRun},
+		{Key: "context.maxToolResultChars", Group: "context", Label: "工具结果上限（字符）", Type: core.SettingNumber, Default: 20000, Effect: core.EffectNewRun},
+		{Key: "retrieval.topK", Group: "retrieval", Label: "检索命中数", Type: core.SettingNumber, Default: 5, Effect: core.EffectHot},
+		{Key: "ui.theme", Group: "ui", Label: "主题", Type: core.SettingEnum, Default: "dark", Options: []string{"dark", "light"}, Effect: core.EffectHot},
+		{Key: "plugins.dir", Group: "plugins", Label: "插件目录", Type: core.SettingString, Default: "./plugins", Effect: core.EffectRestart},
+	}
+}
+
+// Service 提供有效设置计算与分层写入。
+type Service struct{ st *store.Store }
+
+func NewService(st *store.Store) *Service { return &Service{st: st} }
+
+// Effective 计算覆盖链结果：system → user → project（conversation 层经画像实现）。
+func (s *Service) Effective(projectID string) core.EffectiveSettings {
+	eff := core.MergeSettings(SystemDefaults(), map[string]any{})
+	if user, err := s.st.GetSettingsScope(ScopeUser); err == nil {
+		eff = core.MergeSettings(eff, user)
+	}
+	if projectID != "" {
+		if proj, err := s.st.GetSettingsScope(ScopeProjectPrefix + projectID); err == nil {
+			eff = core.MergeSettings(eff, proj)
+		}
+	}
+	return eff
+}
+
+func (s *Service) UserScope() (map[string]any, error) { return s.st.GetSettingsScope(ScopeUser) }
+
+func (s *Service) ProjectScope(projectID string) (map[string]any, error) {
+	return s.st.GetSettingsScope(ScopeProjectPrefix + projectID)
+}
+
+func (s *Service) MergeUser(values map[string]any) error { return s.st.MergeSettingsScope(ScopeUser, values) }
+
+func (s *Service) MergeProject(projectID string, values map[string]any) error {
+	return s.st.MergeSettingsScope(ScopeProjectPrefix+projectID, values)
+}
+
+// Masked 返回脱敏视图（secret 类 key 掩码），用于 API 响应。Effective 每次
+// 深合并产出新 map，就地掩码不影响后续计算。
+func Masked(eff core.EffectiveSettings) map[string]any {
+	out := map[string]any(eff)
+	maskSecrets(out)
+	return out
+}
+
+func maskSecrets(m map[string]any) {
+	for k, v := range m {
+		if vm, ok := v.(map[string]any); ok {
+			maskSecrets(vm)
+			continue
+		}
+		if isSecretKey(k) {
+			if s, ok := v.(string); ok && s != "" {
+				m[k] = "••••••"
+			}
+		}
+	}
+}
+
+func isSecretKey(k string) bool {
+	return k == "apiKey" || k == "api_key" || k == "secret" || k == "token"
+}

internal/store/config.go

@@ -0,0 +1,125 @@
+package store
+
+import (
+	"database/sql"
+	"errors"
+
+	core "agent-system-core"
+)
+
+// ---- 画像 ----
+
+func (s *Store) SaveProfile(p core.AgentProfile) error {
+	_, err := s.db.Exec(`INSERT OR REPLACE INTO profiles(id,builtin,payload) VALUES(?,?,?)`,
+		p.ID, boolInt(p.Builtin), marshalJSON(p))
+	return err
+}
+
+func (s *Store) ListProfiles() ([]core.AgentProfile, error) {
+	rows, err := s.db.Query(`SELECT payload FROM profiles ORDER BY builtin DESC, id`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []core.AgentProfile
+	for rows.Next() {
+		var payload string
+		if err := rows.Scan(&payload); err != nil {
+			return nil, err
+		}
+		p, _ := unmarshalJSON[core.AgentProfile](payload)
+		out = append(out, p)
+	}
+	return out, rows.Err()
+}
+
+func (s *Store) GetProfile(id string) (core.AgentProfile, error) {
+	var payload string
+	err := s.db.QueryRow(`SELECT payload FROM profiles WHERE id=?`, id).Scan(&payload)
+	if errors.Is(err, sql.ErrNoRows) {
+		return core.AgentProfile{}, ErrNotFound
+	}
+	if err != nil {
+		return core.AgentProfile{}, err
+	}
+	return unmarshalJSON[core.AgentProfile](payload)
+}
+
+func (s *Store) DeleteProfile(id string) error {
+	var builtin int
+	if err := s.db.QueryRow(`SELECT builtin FROM profiles WHERE id=?`, id).Scan(&builtin); err != nil {
+		return err
+	}
+	if builtin == 1 {
+		return errors.New("store: builtin profile cannot be deleted")
+	}
+	_, err := s.db.Exec(`DELETE FROM profiles WHERE id=?`, id)
+	return err
+}
+
+// ---- 设置（scope = user | project:<id>）----
+
+func (s *Store) GetSettingsScope(scope string) (map[string]any, error) {
+	var payload string
+	err := s.db.QueryRow(`SELECT "values" FROM settings WHERE scope=?`, scope).Scan(&payload)
+	if errors.Is(err, sql.ErrNoRows) {
+		return map[string]any{}, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	out, err := unmarshalJSON[map[string]any](payload)
+	if err != nil {
+		return nil, err
+	}
+	if out == nil {
+		out = map[string]any{}
+	}
+	return out, nil
+}
+
+func (s *Store) MergeSettingsScope(scope string, values map[string]any) error {
+	cur, err := s.GetSettingsScope(scope)
+	if err != nil {
+		return err
+	}
+	merged := core.MergeSettings(cur, values)
+	_, err = s.db.Exec(`INSERT OR REPLACE INTO settings(scope,"values") VALUES(?,?)`, scope, marshalJSON(merged))
+	return err
+}
+
+func (s *Store) DeleteSettingsScope(scope string) error {
+	_, err := s.db.Exec(`DELETE FROM settings WHERE scope=?`, scope)
+	return err
+}
+
+// ---- 插件注册表（加载状态；能力注册在 pluginhost 内存态）----
+
+func (s *Store) UpsertPlugin(id, dir string, m core.PluginManifest) error {
+	_, err := s.db.Exec(`INSERT OR REPLACE INTO plugins(id,dir,manifest,enabled,loaded_at) VALUES(?,?,?,?,?)`,
+		id, dir, marshalJSON(m), 1, nowISO())
+	return err
+}
+
+func (s *Store) ListPlugins() ([]core.PluginManifest, error) {
+	rows, err := s.db.Query(`SELECT manifest FROM plugins ORDER BY id`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []core.PluginManifest
+	for rows.Next() {
+		var payload string
+		if err := rows.Scan(&payload); err != nil {
+			return nil, err
+		}
+		m, _ := unmarshalJSON[core.PluginManifest](payload)
+		out = append(out, m)
+	}
+	return out, rows.Err()
+}
+
+func (s *Store) RemovePlugin(id string) error {
+	_, err := s.db.Exec(`DELETE FROM plugins WHERE id=?`, id)
+	return err
+}

internal/store/content.go

@@ -0,0 +1,329 @@
+package store
+
+import (
+	"database/sql"
+	"errors"
+	"os"
+	"path/filepath"
+	"time"
+
+	core "agent-system-core"
+)
+
+// ---- 工件（元数据在库，内容在对象目录 data/artifacts/<id>）----
+
+func (s *Store) CreateArtifact(a *core.Artifact, content []byte) error {
+	if a.ID == "" {
+		a.ID = newID("art")
+	}
+	now := time.Now().UTC()
+	a.CreatedAt, a.UpdatedAt = now, now
+	a.Size = int64(len(content))
+	path := filepath.Join(s.dataDir, a.ID)
+	if err := os.WriteFile(path, content, 0o644); err != nil {
+		return err
+	}
+	_, err := s.db.Exec(`INSERT INTO artifacts(id,project_id,name,kind,mime,size,source_run,content_path,created_at,updated_at) VALUES(?,?,?,?,?,?,?,?,?,?)`,
+		a.ID, a.ProjectID, a.Name, a.Kind, a.MIME, a.Size, a.SourceRun, path, nowISO(), nowISO())
+	return err
+}
+
+func (s *Store) UpdateArtifactContent(id string, content []byte) error {
+	var path string
+	if err := s.db.QueryRow(`SELECT content_path FROM artifacts WHERE id=?`, id).Scan(&path); err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return ErrNotFound
+		}
+		return err
+	}
+	if err := os.WriteFile(path, content, 0o644); err != nil {
+		return err
+	}
+	_, err := s.db.Exec(`UPDATE artifacts SET size=?, updated_at=? WHERE id=?`, len(content), nowISO(), id)
+	return err
+}
+
+const artifactColumns = `id,project_id,name,kind,mime,size,source_run,created_at,updated_at`
+
+func scanArtifact(scan func(...any) error) (core.Artifact, error) {
+	var a core.Artifact
+	var mime, sourceRun string
+	var ca, ua string
+	if err := scan(&a.ID, &a.ProjectID, &a.Name, &a.Kind, &mime, &a.Size, &sourceRun, &ca, &ua); err != nil {
+		return a, err
+	}
+	a.MIME, a.SourceRun = mime, sourceRun
+	a.CreatedAt, _ = parseTime(ca)
+	a.UpdatedAt, _ = parseTime(ua)
+	return a, nil
+}
+
+func (s *Store) GetArtifact(id string) (core.Artifact, error) {
+	a, err := scanArtifact(func(dst ...any) error {
+		return s.db.QueryRow(`SELECT `+artifactColumns+` FROM artifacts WHERE id=?`, id).Scan(dst...)
+	})
+	if err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return a, ErrNotFound
+		}
+		return a, err
+	}
+	return a, nil
+}
+
+func (s *Store) ArtifactContent(id string) ([]byte, error) {
+	var path string
+	err := s.db.QueryRow(`SELECT content_path FROM artifacts WHERE id=?`, id).Scan(&path)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, ErrNotFound
+	}
+	if err != nil {
+		return nil, err
+	}
+	return os.ReadFile(path)
+}
+
+func (s *Store) ListArtifacts(projectID string) ([]core.Artifact, error) {
+	rows, err := s.db.Query(`SELECT `+artifactColumns+` FROM artifacts WHERE project_id=? ORDER BY updated_at DESC`, projectID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []core.Artifact
+	for rows.Next() {
+		a, err := scanArtifact(rows.Scan)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, a)
+	}
+	return out, rows.Err()
+}
+
+func (s *Store) DeleteArtifact(id string) error {
+	var path string
+	if err := s.db.QueryRow(`SELECT content_path FROM artifacts WHERE id=?`, id).Scan(&path); err != nil {
+		return err
+	}
+	if _, err := s.db.Exec(`DELETE FROM artifacts WHERE id=?`, id); err != nil {
+		return err
+	}
+	return os.Remove(path)
+}
+
+// ---- HITL 卡片 ----
+
+func (s *Store) SaveHITLCard(c *core.HITLCard) error {
+	_, err := s.db.Exec(`INSERT OR REPLACE INTO hitl_cards(id,run_id,conversation_id,payload,created_at,resolved,resolution) VALUES(?,?,?,?,?,?,?)`,
+		c.ID, c.RunID, c.ConversationID, marshalJSON(c), nowISO(), boolInt(c.Resolved), "")
+	return err
+}
+
+func (s *Store) GetHITLCard(id string) (core.HITLCard, error) {
+	var payload string
+	err := s.db.QueryRow(`SELECT payload FROM hitl_cards WHERE id=?`, id).Scan(&payload)
+	if errors.Is(err, sql.ErrNoRows) {
+		return core.HITLCard{}, ErrNotFound
+	}
+	if err != nil {
+		return core.HITLCard{}, err
+	}
+	return unmarshalJSON[core.HITLCard](payload)
+}
+
+func (s *Store) ResolveHITLCard(id string, resolution core.HITLResolvedPayload) error {
+	c, err := s.GetHITLCard(id)
+	if err != nil {
+		return err
+	}
+	c.Resolved = true
+	_, err = s.db.Exec(`UPDATE hitl_cards SET resolved=1, payload=?, resolution=? WHERE id=?`,
+		marshalJSON(c), marshalJSON(resolution), id)
+	return err
+}
+
+func (s *Store) ActiveHITLCards(conversationID string) ([]core.HITLCard, error) {
+	rows, err := s.db.Query(`SELECT payload FROM hitl_cards WHERE conversation_id=? AND resolved=0 ORDER BY created_at`, conversationID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []core.HITLCard
+	for rows.Next() {
+		var payload string
+		if err := rows.Scan(&payload); err != nil {
+			return nil, err
+		}
+		c, _ := unmarshalJSON[core.HITLCard](payload)
+		out = append(out, c)
+	}
+	return out, rows.Err()
+}
+
+func boolInt(b bool) int {
+	if b {
+		return 1
+	}
+	return 0
+}
+
+// ---- 计划 / 待办 ----
+
+func (s *Store) SavePlan(conversationID string, p core.PlanSnapshot) error {
+	_, err := s.db.Exec(`INSERT OR REPLACE INTO plans(conversation_id,payload) VALUES(?,?)`, conversationID, marshalJSON(p))
+	return err
+}
+
+func (s *Store) GetPlan(conversationID string) (core.PlanSnapshot, error) {
+	var payload string
+	err := s.db.QueryRow(`SELECT payload FROM plans WHERE conversation_id=?`, conversationID).Scan(&payload)
+	if errors.Is(err, sql.ErrNoRows) {
+		return core.PlanSnapshot{}, ErrNotFound
+	}
+	if err != nil {
+		return core.PlanSnapshot{}, err
+	}
+	return unmarshalJSON[core.PlanSnapshot](payload)
+}
+
+func (s *Store) SaveTodos(conversationID string, l core.TodoList) error {
+	_, err := s.db.Exec(`INSERT OR REPLACE INTO todos(conversation_id,payload) VALUES(?,?)`, conversationID, marshalJSON(l))
+	return err
+}
+
+func (s *Store) GetTodos(conversationID string) (core.TodoList, error) {
+	var payload string
+	err := s.db.QueryRow(`SELECT payload FROM todos WHERE conversation_id=?`, conversationID).Scan(&payload)
+	if errors.Is(err, sql.ErrNoRows) {
+		return core.TodoList{}, ErrNotFound
+	}
+	if err != nil {
+		return core.TodoList{}, err
+	}
+	return unmarshalJSON[core.TodoList](payload)
+}
+
+// ---- 知识（全文检索最小实现：FTS5）----
+
+func (s *Store) AddKnowledge(docs ...core.KnowledgeDoc) error {
+	for _, d := range docs {
+		if d.ID == "" {
+			d.ID = newID("knw")
+		}
+		if _, err := s.db.Exec(`INSERT INTO knowledge(id,project_id,source,title,ref,chunk,created_at) VALUES(?,?,?,?,?,?,?)`,
+			d.ID, d.ProjectID, d.Source, d.Title, d.Ref, d.Chunk, nowISO()); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (s *Store) SearchKnowledge(q core.RetrievalQuery) ([]core.RetrievalHit, error) {
+	topK := q.TopK
+	if topK <= 0 {
+		topK = 5
+	}
+	rows, err := s.db.Query(`
+		SELECT k.id,k.project_id,k.source,k.title,k.ref,k.chunk,k.created_at, rank
+		FROM knowledge_fts f JOIN knowledge k ON k.rowid=f.rowid
+		WHERE knowledge_fts MATCH ? ORDER BY rank LIMIT ?`, ftsQuery(q.Text), topK*2)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []core.RetrievalHit
+	for rows.Next() {
+		var d core.KnowledgeDoc
+		var score float64
+		var ca string
+		if err := rows.Scan(&d.ID, &d.ProjectID, &d.Source, &d.Title, &d.Ref, &d.Chunk, &ca, &score); err != nil {
+			return nil, err
+		}
+		d.CreatedAt, _ = parseTime(ca)
+		if q.ProjectID != "" && d.ProjectID != "" && d.ProjectID != q.ProjectID {
+			continue
+		}
+		if len(q.Sources) > 0 && !containsStr(q.Sources, d.Source) {
+			continue
+		}
+		out = append(out, core.RetrievalHit{Doc: d, Score: -score, Kind: "fulltext"})
+		if len(out) >= topK {
+			break
+		}
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	// CJK 兜底：unicode61 分词把中文整句当单 token，FTS 前缀匹配失效时用 LIKE 子串。
+	if len(out) == 0 && q.Text != "" {
+		return s.searchKnowledgeLike(q, topK)
+	}
+	return out, nil
+}
+
+func (s *Store) searchKnowledgeLike(q core.RetrievalQuery, topK int) ([]core.RetrievalHit, error) {
+	rows, err := s.db.Query(`SELECT id,project_id,source,title,ref,chunk,created_at FROM knowledge WHERE chunk LIKE ? OR title LIKE ? LIMIT ?`,
+		"%"+q.Text+"%", "%"+q.Text+"%", topK)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []core.RetrievalHit
+	for rows.Next() {
+		var d core.KnowledgeDoc
+		var ca string
+		if err := rows.Scan(&d.ID, &d.ProjectID, &d.Source, &d.Title, &d.Ref, &d.Chunk, &ca); err != nil {
+			return nil, err
+		}
+		d.CreatedAt, _ = parseTime(ca)
+		if len(q.Sources) > 0 && !containsStr(q.Sources, d.Source) {
+			continue
+		}
+		out = append(out, core.RetrievalHit{Doc: d, Score: 1.0, Kind: "fulltext"})
+	}
+	return out, rows.Err()
+}
+
+// ftsQuery 做最小安全化：按空白切词加引号，FTS5 前缀匹配。
+func ftsQuery(text string) string {
+	words := splitWords(text)
+	if len(words) == 0 {
+		return `""`
+	}
+	out := ""
+	for i, w := range words {
+		if i > 0 {
+			out += " "
+		}
+		out += `"` + w + `"*`
+	}
+	return out
+}
+
+func splitWords(s string) []string {
+	var out []string
+	cur := []rune{}
+	for _, r := range s {
+		if r == ' ' || r == '\t' || r == '\n' {
+			if len(cur) > 0 {
+				out = append(out, string(cur))
+				cur = nil
+			}
+			continue
+		}
+		cur = append(cur, r)
+	}
+	if len(cur) > 0 {
+		out = append(out, string(cur))
+	}
+	return out
+}
+
+func containsStr(list []string, s string) bool {
+	for _, x := range list {
+		if x == s {
+			return true
+		}
+	}
+	return false
+}

internal/store/messages.go

@@ -0,0 +1,231 @@
+package store
+
+import (
+	"crypto/rand"
+	"database/sql"
+	"encoding/hex"
+	"time"
+
+	core "agent-system-core"
+)
+
+// ---- 消息 ----
+
+func (s *Store) AppendMessage(m *core.Message) error {
+	if m.ID == "" {
+		m.ID = newID("msg")
+	}
+	m.CreatedAt = m.CreatedAt.UTC()
+	var next int
+	if err := s.db.QueryRow(`SELECT COALESCE(MAX(seq),0)+1 FROM messages WHERE conversation_id=?`, m.ConversationID).Scan(&next); err != nil {
+		return err
+	}
+	_, err := s.db.Exec(`INSERT INTO messages(id,conversation_id,run_id,role,parts,seq,created_at) VALUES(?,?,?,?,?,?,?)`,
+		m.ID, m.ConversationID, m.RunID, string(m.Role), marshalJSON(m.Parts), next, nowISO())
+	if err == nil {
+		s.TouchConversation(m.ConversationID)
+	}
+	return err
+}
+
+func (s *Store) ListMessages(conversationID string) ([]core.Message, error) {
+	rows, err := s.db.Query(`SELECT id,conversation_id,run_id,role,parts,created_at FROM messages WHERE conversation_id=? ORDER BY seq`, conversationID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []core.Message
+	for rows.Next() {
+		var m core.Message
+		var parts, ca string
+		if err := rows.Scan(&m.ID, &m.ConversationID, &m.RunID, &m.Role, &parts, &ca); err != nil {
+			return nil, err
+		}
+		m.Role = core.Role(m.Role)
+		m.Parts, _ = unmarshalJSON[[]core.Part](parts)
+		m.CreatedAt, _ = parseTime(ca)
+		out = append(out, m)
+	}
+	return out, rows.Err()
+}
+
+func (s *Store) LastMessages(conversationID string, n int) ([]core.Message, error) {
+	all, err := s.ListMessages(conversationID)
+	if err != nil {
+		return nil, err
+	}
+	if len(all) > n {
+		all = all[len(all)-n:]
+	}
+	return all, nil
+}
+
+// ---- Runs ----
+
+func (s *Store) CreateRun(r *core.Run) error {
+	if r.ID == "" {
+		r.ID = newID("run")
+	}
+	r.CreatedAt = r.CreatedAt.UTC()
+	_, err := s.db.Exec(`INSERT INTO runs(id,parent_run_id,conversation_id,project_id,kind,profile_id,status,phase,agent_name,created_at) VALUES(?,?,?,?,?,?,?,?,?,?)`,
+		r.ID, r.ParentRunID, r.ConversationID, r.ProjectID, string(r.Kind), r.ProfileID, string(r.Status), string(r.Phase), r.AgentName, nowISO())
+	return err
+}
+
+func (s *Store) UpdateRun(r *core.Run) error {
+	var ended any
+	if r.EndedAt != nil {
+		ended = nowISO()
+	}
+	_, err := s.db.Exec(`UPDATE runs SET status=?, phase=?, usage=?, error=?, ended_at=? WHERE id=?`,
+		string(r.Status), string(r.Phase), marshalJSON(r.Usage), marshalJSON(r.Error), ended, r.ID)
+	return err
+}
+
+const runColumns = `id,parent_run_id,conversation_id,project_id,kind,profile_id,status,phase,agent_name,created_at,ended_at,usage,error`
+
+func scanRun(scan func(...any) error) (core.Run, error) {
+	var r core.Run
+	var parent, profile, phase, agent, ended, usage, errJSON *string
+	var kind, status string
+	var ca string
+	if err := scan(&r.ID, &parent, &r.ConversationID, &r.ProjectID, &kind, &profile, &status, &phase, &agent, &ca, &ended, &usage, &errJSON); err != nil {
+		return r, err
+	}
+	if parent != nil {
+		r.ParentRunID = *parent
+	}
+	if profile != nil {
+		r.ProfileID = *profile
+	}
+	r.Kind = core.RunKind(kind)
+	r.Status = core.RunStatus(status)
+	if phase != nil {
+		r.Phase = core.RunPhase(*phase)
+	}
+	if agent != nil {
+		r.AgentName = *agent
+	}
+	r.CreatedAt, _ = parseTime(ca)
+	if ended != nil {
+		t, _ := parseTime(*ended)
+		r.EndedAt = &t
+	}
+	if usage != nil && *usage != "" && *usage != "null" {
+		r.Usage, _ = unmarshalJSON[*core.Usage](*usage)
+	}
+	if errJSON != nil && *errJSON != "" && *errJSON != "null" {
+		r.Error, _ = unmarshalJSON[*core.ErrorPart](*errJSON)
+	}
+	return r, nil
+}
+
+func (s *Store) GetRun(id string) (core.Run, error) {
+	r, err := scanRun(func(dst ...any) error {
+		return s.db.QueryRow(`SELECT `+runColumns+` FROM runs WHERE id=?`, id).Scan(dst...)
+	})
+	if err != nil {
+		if err.Error() == "sql: no rows" {
+			return r, ErrNotFound
+		}
+		return r, err
+	}
+	return r, nil
+}
+
+func (s *Store) ListRunsByConversation(conversationID string) ([]core.Run, error) {
+	rows, err := s.db.Query(`SELECT `+runColumns+` FROM runs WHERE conversation_id=? ORDER BY created_at`, conversationID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []core.Run
+	for rows.Next() {
+		r, err := scanRun(rows.Scan)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, r)
+	}
+	return out, rows.Err()
+}
+
+// ChildRuns 返回直接子 run（任务树）。
+func (s *Store) ChildRuns(runID string) ([]core.Run, error) {
+	rows, err := s.db.Query(`SELECT `+runColumns+` FROM runs WHERE parent_run_id=? ORDER BY created_at`, runID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []core.Run
+	for rows.Next() {
+		r, err := scanRun(rows.Scan)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, r)
+	}
+	return out, rows.Err()
+}
+
+// ---- 事件（seq 游标权威）----
+
+func (s *Store) AppendEvent(e *core.StreamEvent, payload any) (int64, error) {
+	var payloadStr any
+	if payload != nil {
+		payloadStr = marshalJSON(payload)
+	}
+	res, err := s.db.Exec(`INSERT INTO events(conversation_id,run_id,ts,v,type,payload) VALUES(?,?,?,?,?,?)`,
+		e.ConversationID, e.RunID, e.TS, e.V, string(e.Type), payloadStr)
+	if err != nil {
+		return 0, err
+	}
+	return res.LastInsertId()
+}
+
+func (s *Store) EventsAfter(conversationID string, since int64, limit int) ([]core.StreamEvent, error) {
+	rows, err := s.db.Query(`SELECT seq,run_id,ts,v,type,payload FROM events WHERE conversation_id=? AND seq>? ORDER BY seq LIMIT ?`,
+		conversationID, since, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []core.StreamEvent
+	for rows.Next() {
+		var e core.StreamEvent
+		var typ string
+		var payload []byte
+		if err := rows.Scan(&e.Seq, &e.RunID, &e.TS, &e.V, &typ, &payload); err != nil {
+			return nil, err
+		}
+		e.ConversationID = conversationID
+		e.Type = core.StreamEventType(typ)
+		if len(payload) > 0 {
+			e.Payload = payload
+		}
+		out = append(out, e)
+	}
+	return out, rows.Err()
+}
+
+func (s *Store) LastEventSeq(conversationID string) (int64, error) {
+	var seq sql.NullInt64
+	err := s.db.QueryRow(`SELECT MAX(seq) FROM events WHERE conversation_id=?`, conversationID).Scan(&seq)
+	if err != nil {
+		return 0, err
+	}
+	return seq.Int64, nil
+}
+
+func newID(kind string) string {
+	b := make([]byte, 6)
+	rand.Read(b)
+	return kind + "_" + hex.EncodeToString(b)
+}
+
+func parseTime(s string) (time.Time, error) {
+	return time.Parse(time.RFC3339Nano, s)
+}
+
+// NewID 生成带前缀的随机 ID（导出供 runmgr/server 使用）。
+func NewID(kind string) string { return newID(kind) }

internal/store/projects.go

@@ -0,0 +1,142 @@
+package store
+
+import (
+	"database/sql"
+	"errors"
+	"time"
+
+	core "agent-system-core"
+)
+
+var ErrNotFound = errors.New("store: not found")
+
+// ---- 项目与会话 ----
+
+func (s *Store) CreateProject(name string) (core.Project, error) {
+	p := core.Project{ID: newID("prj"), Name: name, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC(), Settings: map[string]any{}}
+	_, err := s.db.Exec(`INSERT INTO projects(id,name,settings,created_at,updated_at) VALUES(?,?,?,?,?)`,
+		p.ID, p.Name, "{}", nowISO(), nowISO())
+	return p, err
+}
+
+func (s *Store) ListProjects() ([]core.Project, error) {
+	rows, err := s.db.Query(`SELECT id,name,settings,created_at,updated_at FROM projects ORDER BY updated_at DESC`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []core.Project
+	for rows.Next() {
+		var p core.Project
+		var settings string
+		var ca, ua string
+		if err := rows.Scan(&p.ID, &p.Name, &settings, &ca, &ua); err != nil {
+			return nil, err
+		}
+		p.CreatedAt, _ = time.Parse(time.RFC3339Nano, ca)
+		p.UpdatedAt, _ = time.Parse(time.RFC3339Nano, ua)
+		if settings != "" && settings != "{}" {
+			p.Settings, _ = unmarshalJSON[map[string]any](settings)
+		}
+		out = append(out, p)
+	}
+	return out, rows.Err()
+}
+
+func (s *Store) GetProject(id string) (core.Project, error) {
+	var p core.Project
+	var settings, ca, ua string
+	err := s.db.QueryRow(`SELECT id,name,settings,created_at,updated_at FROM projects WHERE id=?`, id).
+		Scan(&p.ID, &p.Name, &settings, &ca, &ua)
+	if errors.Is(err, sql.ErrNoRows) {
+		return p, ErrNotFound
+	}
+	if err != nil {
+		return p, err
+	}
+	p.CreatedAt, _ = time.Parse(time.RFC3339Nano, ca)
+	p.UpdatedAt, _ = time.Parse(time.RFC3339Nano, ua)
+	if settings != "" && settings != "{}" {
+		p.Settings, _ = unmarshalJSON[map[string]any](settings)
+	}
+	return p, nil
+}
+
+func (s *Store) UpdateProjectSettings(id string, values map[string]any) error {
+	cur, err := s.GetProject(id)
+	if err != nil {
+		return err
+	}
+	merged := core.MergeSettings(cur.Settings, values)
+	_, err = s.db.Exec(`UPDATE projects SET settings=?, updated_at=? WHERE id=?`, marshalJSON(merged), nowISO(), id)
+	return err
+}
+
+func (s *Store) RenameProject(id, name string) error {
+	_, err := s.db.Exec(`UPDATE projects SET name=?, updated_at=? WHERE id=?`, name, nowISO(), id)
+	return err
+}
+
+func (s *Store) DeleteProject(id string) error {
+	_, err := s.db.Exec(`DELETE FROM projects WHERE id=?`, id)
+	return err
+}
+
+func (s *Store) CreateConversation(projectID, title, profileID string) (core.Conversation, error) {
+	c := core.Conversation{ID: newID("cnv"), ProjectID: projectID, Title: title, ProfileID: profileID, CreatedAt: time.Now().UTC(), UpdatedAt: time.Now().UTC()}
+	_, err := s.db.Exec(`INSERT INTO conversations(id,project_id,title,profile_id,created_at,updated_at) VALUES(?,?,?,?,?,?)`,
+		c.ID, c.ProjectID, c.Title, c.ProfileID, nowISO(), nowISO())
+	return c, err
+}
+
+func (s *Store) ListConversations(projectID string) ([]core.Conversation, error) {
+	rows, err := s.db.Query(`SELECT id,project_id,title,profile_id,created_at,updated_at FROM conversations WHERE project_id=? ORDER BY updated_at DESC`, projectID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []core.Conversation
+	for rows.Next() {
+		var c core.Conversation
+		var ca, ua string
+		if err := rows.Scan(&c.ID, &c.ProjectID, &c.Title, &c.ProfileID, &ca, &ua); err != nil {
+			return nil, err
+		}
+		c.CreatedAt, _ = time.Parse(time.RFC3339Nano, ca)
+		c.UpdatedAt, _ = time.Parse(time.RFC3339Nano, ua)
+		out = append(out, c)
+	}
+	return out, rows.Err()
+}
+
+func (s *Store) GetConversation(id string) (core.Conversation, error) {
+	var c core.Conversation
+	var ca, ua string
+	err := s.db.QueryRow(`SELECT id,project_id,title,profile_id,created_at,updated_at FROM conversations WHERE id=?`, id).
+		Scan(&c.ID, &c.ProjectID, &c.Title, &c.ProfileID, &ca, &ua)
+	if errors.Is(err, sql.ErrNoRows) {
+		return c, ErrNotFound
+	}
+	if err != nil {
+		return c, err
+	}
+	c.CreatedAt, _ = time.Parse(time.RFC3339Nano, ca)
+	c.UpdatedAt, _ = time.Parse(time.RFC3339Nano, ua)
+	return c, nil
+}
+
+func (s *Store) TouchConversation(id string) { s.db.Exec(`UPDATE conversations SET updated_at=? WHERE id=?`, nowISO(), id) }
+
+func (s *Store) UpdateConversation(id, title, profileID string) error {
+	if title == "" {
+		_, err := s.db.Exec(`UPDATE conversations SET profile_id=?, updated_at=? WHERE id=?`, profileID, nowISO(), id)
+		return err
+	}
+	_, err := s.db.Exec(`UPDATE conversations SET title=?, profile_id=?, updated_at=? WHERE id=?`, title, profileID, nowISO(), id)
+	return err
+}
+
+func (s *Store) DeleteConversation(id string) error {
+	_, err := s.db.Exec(`DELETE FROM conversations WHERE id=?`, id)
+	return err
+}

internal/store/store.go

@@ -0,0 +1,136 @@
+// Package store 提供后端持久化：默认档为嵌入式 SQLite（单文件，零外部服务）。
+// 存储档接口按设计 4.1/D16 预留 PostgreSQL 档；业务层只依赖本包公开方法。
+package store
+
+import (
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	_ "modernc.org/sqlite"
+)
+
+// Store 持有数据库连接与对象目录。所有方法并发安全（SQLite 单写者，靠 busy 重试）。
+type Store struct {
+	db   *sql.DB
+	dataDir string // 对象目录：data/artifacts/<id>
+}
+
+// Open 打开（必要时创建）SQLite 存储并执行迁移。
+func Open(path string) (*Store, error) {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return nil, err
+	}
+	dsn := fmt.Sprintf("file:%s?_pragma=busy_timeout(5000)&_pragma=journal_mode(WAL)&_pragma=foreign_keys(1)", path)
+	db, err := sql.Open("sqlite", dsn)
+	if err != nil {
+		return nil, err
+	}
+	// SQLite 单写者：串行化写连接，避免 database is locked。
+	db.SetMaxOpenConns(1)
+	s := &Store{db: db, dataDir: filepath.Join(filepath.Dir(path), "artifacts")}
+	if err := s.migrate(); err != nil {
+		db.Close()
+		return nil, err
+	}
+	if err := os.MkdirAll(s.dataDir, 0o755); err != nil {
+		db.Close()
+		return nil, err
+	}
+	return s, nil
+}
+
+func (s *Store) Close() error { return s.db.Close() }
+
+func (s *Store) migrate() error {
+	stmts := []string{
+		`CREATE TABLE IF NOT EXISTS projects (
+			id TEXT PRIMARY KEY, name TEXT NOT NULL,
+			settings TEXT NOT NULL DEFAULT '{}',
+			created_at TEXT NOT NULL, updated_at TEXT NOT NULL)`,
+		`CREATE TABLE IF NOT EXISTS conversations (
+			id TEXT PRIMARY KEY, project_id TEXT NOT NULL,
+			title TEXT NOT NULL DEFAULT '新会话', profile_id TEXT NOT NULL DEFAULT '',
+			created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+			FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE CASCADE)`,
+		`CREATE TABLE IF NOT EXISTS messages (
+			id TEXT PRIMARY KEY, conversation_id TEXT NOT NULL,
+			run_id TEXT NOT NULL DEFAULT '', role TEXT NOT NULL,
+			parts TEXT NOT NULL, seq INTEGER NOT NULL,
+			created_at TEXT NOT NULL,
+			FOREIGN KEY(conversation_id) REFERENCES conversations(id) ON DELETE CASCADE)`,
+		`CREATE INDEX IF NOT EXISTS idx_messages_conv ON messages(conversation_id, seq)`,
+		`CREATE TABLE IF NOT EXISTS runs (
+			id TEXT PRIMARY KEY, parent_run_id TEXT NOT NULL DEFAULT '',
+			conversation_id TEXT NOT NULL, project_id TEXT NOT NULL,
+			kind TEXT NOT NULL, profile_id TEXT NOT NULL DEFAULT '',
+			status TEXT NOT NULL, phase TEXT NOT NULL DEFAULT '',
+			agent_name TEXT NOT NULL DEFAULT '',
+			created_at TEXT NOT NULL, ended_at TEXT,
+			usage TEXT, error TEXT)`,
+		`CREATE INDEX IF NOT EXISTS idx_runs_conv ON runs(conversation_id)`,
+		`CREATE INDEX IF NOT EXISTS idx_runs_parent ON runs(parent_run_id)`,
+		`CREATE TABLE IF NOT EXISTS events (
+			seq INTEGER PRIMARY KEY AUTOINCREMENT,
+			conversation_id TEXT NOT NULL, run_id TEXT NOT NULL DEFAULT '',
+			ts TEXT NOT NULL, v INTEGER NOT NULL, type TEXT NOT NULL,
+			payload TEXT)`,
+		`CREATE INDEX IF NOT EXISTS idx_events_conv ON events(conversation_id, seq)`,
+		`CREATE TABLE IF NOT EXISTS artifacts (
+			id TEXT PRIMARY KEY, project_id TEXT NOT NULL,
+			name TEXT NOT NULL, kind TEXT NOT NULL, mime TEXT NOT NULL DEFAULT '',
+			size INTEGER NOT NULL DEFAULT 0, source_run TEXT NOT NULL DEFAULT '',
+			content_path TEXT NOT NULL DEFAULT '',
+			created_at TEXT NOT NULL, updated_at TEXT NOT NULL)`,
+		`CREATE TABLE IF NOT EXISTS hitl_cards (
+			id TEXT PRIMARY KEY, run_id TEXT NOT NULL, conversation_id TEXT NOT NULL,
+			payload TEXT NOT NULL, created_at TEXT NOT NULL,
+			resolved INTEGER NOT NULL DEFAULT 0, resolution TEXT)`,
+		`CREATE TABLE IF NOT EXISTS profiles (
+			id TEXT PRIMARY KEY, builtin INTEGER NOT NULL DEFAULT 0, payload TEXT NOT NULL)`,
+		`CREATE TABLE IF NOT EXISTS settings (
+			scope TEXT PRIMARY KEY, "values" TEXT NOT NULL)`,
+		`CREATE TABLE IF NOT EXISTS plugins (
+			id TEXT PRIMARY KEY, dir TEXT NOT NULL, manifest TEXT NOT NULL,
+			enabled INTEGER NOT NULL DEFAULT 1, loaded_at TEXT NOT NULL)`,
+		`CREATE TABLE IF NOT EXISTS plans (
+			conversation_id TEXT PRIMARY KEY, payload TEXT NOT NULL)`,
+		`CREATE TABLE IF NOT EXISTS todos (
+			conversation_id TEXT PRIMARY KEY, payload TEXT NOT NULL)`,
+		`CREATE TABLE IF NOT EXISTS knowledge (
+			id TEXT PRIMARY KEY, project_id TEXT NOT NULL DEFAULT '',
+			source TEXT NOT NULL, title TEXT NOT NULL, ref TEXT NOT NULL DEFAULT '',
+			chunk TEXT NOT NULL, created_at TEXT NOT NULL)`,
+		`CREATE VIRTUAL TABLE IF NOT EXISTS knowledge_fts USING fts5(title, chunk, content='knowledge', content_rowid='rowid')`,
+		`CREATE TRIGGER IF NOT EXISTS knowledge_ai AFTER INSERT ON knowledge BEGIN
+			INSERT INTO knowledge_fts(rowid, title, chunk) VALUES (new.rowid, new.title, new.chunk); END`,
+		`CREATE TRIGGER IF NOT EXISTS knowledge_ad AFTER DELETE ON knowledge BEGIN
+			INSERT INTO knowledge_fts(knowledge_fts, rowid, title, chunk) VALUES('delete', old.rowid, old.title, old.chunk); END`,
+	}
+	for _, q := range stmts {
+		if _, err := s.db.Exec(q); err != nil {
+			return fmt.Errorf("migrate: %w", err)
+		}
+	}
+	return nil
+}
+
+// ---- 通用 ----
+
+func nowISO() string { return time.Now().UTC().Format(time.RFC3339Nano) }
+
+func marshalJSON(v any) string {
+	b, _ := json.Marshal(v)
+	return string(b)
+}
+
+func unmarshalJSON[T any](raw string) (T, error) {
+	var out T
+	err := json.Unmarshal([]byte(raw), &out)
+	return out, err
+}
+
+var _ = unmarshalJSON[map[string]any]

internal/tools/http.go

@@ -0,0 +1,176 @@
+package tools
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+
+	core "agent-system-core"
+)
+
+// execHTTPTool 见 HTTPExecutor：声明式 HTTP 工具在注册时绑定 spec 闭包执行。
+func HTTPExecutor(spec core.HTTPToolSpec, settingsLookup func(key string) string) Executor {
+	return func(rc ToolExecCtx, args json.RawMessage) (string, error) {
+		params := map[string]any{}
+		if len(args) > 0 {
+			if err := json.Unmarshal(args, &params); err != nil {
+				return "", fmt.Errorf("http tool: bad args json: %w", err)
+			}
+		}
+		method := strings.ToUpper(spec.Method)
+		if method == "" {
+			method = http.MethodGet
+		}
+		urlStr := expandTemplate(spec.URL, params)
+		var body io.Reader
+		if spec.BodyTemplate != "" && (method == http.MethodPost || method == http.MethodPut || method == http.MethodPatch) {
+			body = bytes.NewReader([]byte(expandTemplate(spec.BodyTemplate, params)))
+		}
+		req, err := http.NewRequest(method, urlStr, body)
+		if err != nil {
+			return "", err
+		}
+		for k, v := range spec.Headers {
+			req.Header.Set(k, expandTemplate(v, params))
+		}
+		if body != nil && req.Header.Get("Content-Type") == "" {
+			req.Header.Set("Content-Type", "application/json")
+		}
+		if spec.AuthRef != "" {
+			token := authValue(spec.AuthRef, settingsLookup)
+			if token != "" {
+				if strings.HasPrefix(token, "Bearer ") || strings.Contains(token, " ") {
+					req.Header.Set("Authorization", token)
+				} else {
+					req.Header.Set("Authorization", "Bearer "+token)
+				}
+			}
+		}
+		timeout := time.Duration(spec.TimeoutMs) * time.Millisecond
+		if timeout <= 0 {
+			timeout = 15 * time.Second
+		}
+		client := &http.Client{Timeout: timeout}
+		resp, err := client.Do(req)
+		if err != nil {
+			return "", fmt.Errorf("http tool: %w", err)
+		}
+		defer resp.Body.Close()
+		raw, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+		if err != nil {
+			return "", fmt.Errorf("http tool: read body: %w", err)
+		}
+		if resp.StatusCode >= 400 {
+			return "", fmt.Errorf("http tool: status %d: %s", resp.StatusCode, truncateStr(string(raw), 400))
+		}
+		// JSON 则裁剪路径；否则原文返回。
+		var parsed any
+		if err := json.Unmarshal(raw, &parsed); err == nil {
+			if spec.ResultPath != "" {
+				if v, ok := pickPath(parsed, spec.ResultPath); ok {
+					return prettyJSON(v), nil
+				}
+				return "", fmt.Errorf("http tool: result path %q not found", spec.ResultPath)
+			}
+			return prettyJSON(parsed), nil
+		}
+		return truncateStr(string(raw), 20000), nil
+	}
+}
+
+// expandTemplate 替换 {{param.x.y}}；未知变量替换为空串（防注入：无脚本语义）。
+func expandTemplate(tpl string, params map[string]any) string {
+	out := tpl
+	for {
+		start := strings.Index(out, "{{")
+		if start < 0 {
+			break
+		}
+		end := strings.Index(out[start:], "}}")
+		if end < 0 {
+			break
+		}
+		end += start
+		key := strings.TrimSpace(out[start+2 : end])
+		key = strings.TrimPrefix(key, "param.") // {{param.x}} → 顶层参数 x
+		val := ""
+		if v, ok := lookup(params, key); ok {
+			val = fmt.Sprint(v)
+		}
+		out = out[:start] + val + out[end+2:]
+	}
+	return out
+}
+
+func lookup(params map[string]any, dotted string) (any, bool) {
+	parts := strings.Split(dotted, ".")
+	var cur any = params
+	for _, p := range parts {
+		m, ok := cur.(map[string]any)
+		if !ok {
+			return nil, false
+		}
+		cur, ok = m[p]
+		if !ok {
+			return nil, false
+		}
+	}
+	return cur, true
+}
+
+func pickPath(v any, dotted string) (any, bool) {
+	parts := strings.Split(dotted, ".")
+	cur := v
+	for _, p := range parts {
+		// 数组支持 "0" 数字索引
+		if arr, ok := cur.([]any); ok {
+			idx := -1
+			fmt.Sscanf(p, "%d", &idx)
+			if idx < 0 || idx >= len(arr) {
+				return nil, false
+			}
+			cur = arr[idx]
+			continue
+		}
+		m, ok := cur.(map[string]any)
+		if !ok {
+			return nil, false
+		}
+		cur, ok = m[p]
+		if !ok {
+			return nil, false
+		}
+	}
+	return cur, true
+}
+
+func prettyJSON(v any) string {
+	b, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		return fmt.Sprint(v)
+	}
+	return string(b)
+}
+
+func truncateStr(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "…（截断）"
+}
+
+// authValue 解析 AuthRef：env:NAME 或 settings 点路径。
+func authValue(ref string, settingsLookup func(key string) string) string {
+	if strings.HasPrefix(ref, "env:") {
+		return os.Getenv(strings.TrimPrefix(ref, "env:"))
+	}
+	if settingsLookup != nil {
+		return settingsLookup(ref)
+	}
+	return ""
+}

internal/tools/http_test.go

@@ -0,0 +1,68 @@
+package tools
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	core "agent-system-core"
+)
+
+type dummyCtx struct{ project string }
+
+func (dummyCtx) ProjectID() string            { return "" }
+func (dummyCtx) ConversationID() string       { return "" }
+func (dummyCtx) Retrieve(q core.RetrievalQuery) ([]core.RetrievalHit, error) { return nil, nil }
+func (dummyCtx) WriteArtifact(name, kind, mime string, content []byte) (core.Artifact, error) {
+	return core.Artifact{}, nil
+}
+
+// TestHTTPExecutorTemplateAndPath：模板变量注入、结果路径裁剪、错误状态。
+func TestHTTPExecutorTemplateAndPath(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/translate" {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"data":[{"translated":"hello","src":"你好"}],"meta":{"n":1}}`))
+	}))
+	defer srv.Close()
+
+	spec := core.HTTPToolSpec{
+		Method: "POST", URL: srv.URL + "/translate",
+		BodyTemplate: `{"q":"{{param.text}}"}`, ResultPath: "data.0.translated",
+	}
+	exec := HTTPExecutor(spec, nil)
+	out, err := exec(dummyCtx{}, []byte(`{"text":"你好"}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out != `"hello"` && out != "hello" {
+		t.Errorf("result: %q", out)
+	}
+
+	// ResultPath 不存在 → 显式错误。
+	specBad := spec
+	specBad.ResultPath = "missing.path"
+	if _, err := HTTPExecutor(specBad, nil)(dummyCtx{}, []byte(`{}`)); err == nil {
+		t.Error("missing path should error")
+	}
+
+	// 404 → 错误带状态码。
+	spec404 := spec
+	spec404.URL = srv.URL + "/nope"
+	spec404.ResultPath = ""
+	if _, err := HTTPExecutor(spec404, nil)(dummyCtx{}, nil); err == nil {
+		t.Error("404 should error")
+	}
+}
+
+func TestExpandTemplate(t *testing.T) {
+	got := expandTemplate(`{{param.a}}/{{param.b.c}}/{{param.unknown}}`, map[string]any{
+		"a": "x", "b": map[string]any{"c": "y"},
+	})
+	if got != "x/y/" {
+		t.Errorf("expand: %q", got)
+	}
+}

internal/tools/registry.go

@@ -0,0 +1,168 @@
+// Package tools 实现统一工具注册表（4.8）：内置、声明式 HTTP、插件工具同一形态；
+// 来源标记（builtin/plugin/user）、启用开关、确认策略由画像三清单决定（runmgr 执行）。
+package tools
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	core "agent-system-core"
+)
+
+// Executor 是无状态执行器：入参已校验，返回输出文本或错误。
+type Executor func(rc ToolExecCtx, args json.RawMessage) (string, error)
+
+// ToolExecCtx 供工具访问受控环境（当前项目/检索/工件写入）。
+type ToolExecCtx interface {
+	ProjectID() string
+	ConversationID() string
+	Retrieve(q core.RetrievalQuery) ([]core.RetrievalHit, error)
+	WriteArtifact(name, kind, mime string, content []byte) (core.Artifact, error)
+}
+
+type tool struct {
+	desc core.ToolDesc
+	exec Executor
+}
+
+type Registry struct {
+	mu    sync.RWMutex
+	tools map[string]tool
+}
+
+func NewRegistry() *Registry { return &Registry{tools: map[string]tool{}} }
+
+// Register 幂等注册（后注册覆盖同名；来源标记随之更新）。
+// 声明式 HTTP 工具经 HTTPExecutor(spec, lookup) 绑定执行器。
+func (r *Registry) Register(desc core.ToolDesc, exec Executor) error {
+	if desc.Name == "" {
+		return fmt.Errorf("tools: empty name")
+	}
+	if exec == nil {
+		return fmt.Errorf("tools: %s has no executor", desc.Name)
+	}
+	r.mu.Lock()
+	r.tools[desc.Name] = tool{desc: desc, exec: exec}
+	r.mu.Unlock()
+	return nil
+}
+
+func (r *Registry) UnregisterBySource(source core.SourceKind, pluginID string) {
+	r.mu.Lock()
+	for name, t := range r.tools {
+		if t.desc.Source == source && (pluginID == "" || t.desc.PluginID == pluginID) {
+			delete(r.tools, name)
+		}
+	}
+	r.mu.Unlock()
+}
+
+func (r *Registry) List() []core.ToolDesc {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	out := make([]core.ToolDesc, 0, len(r.tools))
+	for _, t := range r.tools {
+		out = append(out, t.desc)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out
+}
+
+func (r *Registry) Get(name string) (core.ToolDesc, Executor, bool) {
+	r.mu.RLock()
+	t, ok := r.tools[name]
+	r.mu.RUnlock()
+	return t.desc, t.exec, ok
+}
+
+// Execute 校验存在性并调用执行器；策略（allow/deny/confirm）与截断由 runmgr 负责。
+func (r *Registry) Execute(rc ToolExecCtx, call core.ToolCallRequest) core.ToolCallResult {
+	desc, exec, ok := r.Get(call.Name)
+	if !ok {
+		return core.ToolCallResult{CallID: call.CallID, Status: "error", Output: fmt.Sprintf("tool %q not found (registry miss)", call.Name)}
+	}
+	out, err := exec(rc, call.Arguments)
+	if err != nil {
+		return core.ToolCallResult{CallID: call.CallID, Status: "error", Output: err.Error()}
+	}
+	_ = desc
+	return core.ToolCallResult{CallID: call.CallID, Status: "ok", Output: out, Truncated: false, Artifact: nil, }
+}
+
+// ---- 内置最小工具集（一切可禁用：画像三清单控制）----
+
+// RegisterBuiltin 注册骨架期内置工具：时间、会话历史检索、知识检索、读文件、写工件。
+func (r *Registry) RegisterBuiltin() error {
+	if err := r.Register(core.ToolDesc{
+		Name: "time_now", Description: "获取当前时间（RFC3339）与时区", Source: core.SourceBuiltin,
+		Parameters: json.RawMessage(`{"type":"object","properties":{}}`),
+	}, func(rc ToolExecCtx, args json.RawMessage) (string, error) {
+		return time.Now().Format(time.RFC3339), nil
+	}); err != nil {
+		return err
+	}
+	if err := r.Register(core.ToolDesc{
+		Name: "knowledge_search", Description: "在项目知识与插件知识库中做全文检索，返回命中片段", Source: core.SourceBuiltin,
+		Parameters: json.RawMessage(`{"type":"object","properties":{"query":{"type":"string","description":"检索词"}},"required":["query"]}`),
+	}, func(rc ToolExecCtx, args json.RawMessage) (string, error) {
+		var a struct{ Query string `json:"query"`; TopK int `json:"topK"` }
+		if len(args) > 0 {
+			if err := json.Unmarshal(args, &a); err != nil {
+				return "", fmt.Errorf("knowledge_search: bad args: %w", err)
+			}
+		}
+		if a.Query == "" {
+			return "", fmt.Errorf("knowledge_search: query is required")
+		}
+		hits, err := rc.Retrieve(core.RetrievalQuery{ProjectID: rc.ProjectID(), Text: a.Query, TopK: a.TopK})
+		if err != nil {
+			return "", err
+		}
+		if len(hits) == 0 {
+			return "（无命中）", nil
+		}
+		var sb strings.Builder
+		for i, h := range hits {
+			fmt.Fprintf(&sb, "[%d] %s（来源 %s，得分 %.2f）\n%s\n\n", i+1, h.Doc.Title, h.Doc.Source, h.Score, h.Doc.Chunk)
+		}
+		return sb.String(), nil
+	}); err != nil {
+		return err
+	}
+	if err := r.Register(core.ToolDesc{
+		Name: "write_artifact", Description: "把生成内容写入工件（文档/数据），返回工件 ID 与名称", Source: core.SourceBuiltin,
+		Parameters: json.RawMessage(`{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["document","data"]},"content":{"type":"string"}},"required":["name","content"]}`),
+	}, func(rc ToolExecCtx, args json.RawMessage) (string, error) {
+		var a struct {
+			Name    string `json:"name"`
+			Kind    string `json:"kind"`
+			Content string `json:"content"`
+		}
+		if err := json.Unmarshal(args, &a); err != nil {
+			return "", err
+		}
+		if a.Name == "" {
+			return "", fmt.Errorf("write_artifact: name required")
+		}
+		kind := a.Kind
+		if kind == "" {
+			kind = "document"
+		}
+		mime := "text/markdown"
+		if kind == "data" {
+			mime = "application/json"
+		}
+		art, err := rc.WriteArtifact(a.Name, kind, mime, []byte(a.Content))
+		if err != nil {
+			return "", err
+		}
+		return fmt.Sprintf("已写入工件 %s（%s，%d 字节）", art.Name, art.ID, art.Size), nil
+	}); err != nil {
+		return err
+	}
+	return nil
+}

web/embed.go

@@ -0,0 +1,15 @@
+// Package web 内嵌前端构建产物（go:embed）。
+// 构建流程：Frontend 仓 npm run build → 拷贝 dist/* 到本目录 dist/（Dev Makefile）。
+// 空目录时保留 .gitkeep，embed 用 dist/* 通配以允许空构建（仅 API 模式）。
+package web
+
+import (
+	"embed"
+	"io/fs"
+)
+
+//go:embed all:dist
+var distFS embed.FS
+
+// Dist 返回前端文件系统（根即 index.html）。
+func Dist() (fs.FS, error) { return fs.Sub(distFS, "dist") }