Agent-System-Documents/docs/guides/architecture-overview.md

Agent-System 系统结构与架构

基准：Agent-System-Dev 组合 218fc4b1ba00b0a03b5bb79f292b3eba6c987a58（R0，2026-10-08 锚点核验）。 行号为该提交下的函数入口位置（个别内部区段为约略范围），随代码演进漂移；文件与函数名是稳定锚点。 文中路径均为 Dev 组合仓内相对路径。

---

1. 总体形态：一个父仓 + 12 个子模块仓的组合系统

Agent-System 是**多仓组合（gitlink 固定指针）**的开发集成父仓，不是单一代码库。 .gitmodules 定义了 12 个子仓，分两类：

modules/（5 个产品模块仓）

仓	目录	定位	技术栈
Agent-System-Core	modules/core	核心契约库：纯数据类型 + 线格式权威，零第三方依赖	Go（附 ts/types.ts TS 镜像）
Agent-System-Backend	modules/backend	后端模块化单体，默认单二进制（内嵌前端 + 嵌入式 SQLite）	Go
Agent-System-Frontend	modules/frontend	Web 前端	React 19 + Vite + TypeScript
Agent-System-UI	modules/ui	纯展示组件库：props 进 events 出，不持状态不调 API	React + CSS 令牌
Agent-System-Documents	modules/documents	文档过程仓（设计提案/记录/报告），无代码	Markdown

deps/（7 个基础库仓）

仓	go module 名	一句话职责
agent-native	agent-native	Agent 执行内核：ReAct 循环、LLM 客户端、工具注册表、会话转录、MCP、技能
agent-squad	agent-squad	小队编排底座：规划器、Leader 委派、黑板、HITL 挂起恢复、调度
agent-intent	agent-intent	确定性意图识别：四级漏斗（Guard→Expectation→Rules→Adjudicate）
agent-command	agent-command	命令总线基础库：命令 spec、危险分级、审计信封（零依赖）
error-code-system	error-code-system	跨系统错误码目录 + HTTP 错误信封 + 查询服务
logging-system	logging-system	结构化日志库 + 采集服务
development-guidelines	—（非 Go）	人与 Agent 共用的开发规范文档基线

依赖方向铁律（README.md）：

frontend → core ← backend → { agent-native, agent-squad, agent-intent, agent-command }
                                        ↘ error-code-system / logging-system

core 与各生态仓互不依赖；backend 对 8 个库的引用经自己仓内 deps/ 子模块 + modules/backend/go.mod 的 replace 收敛（父仓顶层 deps/ 与 modules/backend/deps/ 是同一批仓的两份 gitlink，scripts/check-pins.sh 核对一致）。仓库不使用 go.work （避免工作区最小版本选择抬高 backend 单独构建的依赖版本，见 PROJECT.md）。

三态一致的契约机制：core 的每个契约同时存在 ① Go 类型（camelCase JSON）、 ② modules/core/testdata/golden/*.json 黄金样本（线格式权威）、③ modules/core/ts/types.ts 手工 TS 镜像。父仓 make contracts 把 TS 镜像生成到 frontend 与 ui 的 src/contracts.ts。

---

2. Backend 功能分布（产品核心）

单二进制入口：modules/backend/cmd/agent-system/main.go（子命令 serve/version/apikey/user/config）。 组合根与装配顺序在 modules/backend/internal/app/app.go 的 Run()： 存储 → 总线 → 工具注册 → settings/prompts/skills/profiles → runmgr（三个 runner + SquadRunner 注入）→ intentgate → 插件宿主 + hostapi → workflow 注册表 → RAG → 可选 intentsem → cardsvc/cmdbus → server + 限流 + 认证 → HTTP 监听（默认 127.0.0.1:8787）。

internal 包职责一览（功能 → 代码分布）

包	主文件	职责
app	internal/app/app.go	组合根：装配一切组件
config	internal/config/config.go	启动配置单一管道：内置默认→--config JSON→环境变量→CLI
store	internal/store/store.go	持久化唯一入口；SQLite（默认，modernc 纯 Go）/ PostgreSQL 双档；dialect.go 方言收敛、migrate.go 版本化迁移
blobstore	internal/blobstore/blobstore.go	工件对象存储抽象，默认本地目录 <data>/artifacts/
bus	internal/bus/bus.go	进程内事件总线：按会话转发已持久化事件给 SSE 订阅者
pgbus	internal/pgbus/pgbus.go	PG 档跨实例扇出：NOTIFY/LISTEN agent_events
cmdbus	internal/cmdbus/cmdbus.go	命令总线宿主：button/card/slash/chat 四入口归一分发、危险命令确认卡、审计
cardsvc	internal/cardsvc/cardsvc.go	收件箱任务卡服务（card.* 事件投影）
runmgr	internal/runmgr/runmgr.go	Run 生命周期枢纽：状态机、事件持久化+广播、HITL、子代理任务树、工具执行策略、取消级联
route	internal/route/route.go	唯一意图 Router：命令总线 > 工作流 > 普通回合
intentgate	internal/intentgate/gate.go	意图闸门：接入 agent-intent 库，插件意图 overlay
intentsem	internal/intentsem/scorer.go generator.go	意图慢通道：embedding 语义重排 + 轻量模型命令生成（默认关）
runtime	internal/runtime/runner.go llm.go llm_direct.go sub_loop.go workflow_compiled.go squad_runner.go model.go	四类 Runner（LLM/Mock/Sub/Squad）+ 工作流执行入口 + 模型路由
wfcompile	internal/wfcompile/run.go compiler.go	工作流编译执行驱动：编译图 → 小队引擎装配 → 步进循环 → critic 终判
ctxasm	internal/ctxasm/ctxasm.go finish.go	上下文组装与预算裁剪
prompts	internal/prompts/service.go	提示词模块库：embed 内置 + DB 用户覆盖链
skills	internal/skills/skills.go	内置技能种子（go:embed recipes → <data>/skills/）
tools	internal/tools/registry.go	统一工具注册表：内置/声明式 HTTP/插件工具同形态
plugins	internal/plugins/host.go host_v2.go	插件宿主：fail-closed 热加载；sidecar 进程拉起
hostapi	internal/hostapi/server.go	sidecar 本机回调面 /host/v1（127.0.0.1 随机端口 + 随机 token）
workflow	internal/workflow/registry.go	工作流定义注册表（编译执行器在 wfcompile）
ingest / docgen / rag / quality	各主文件	文档摄取 → ParsedDocument IR；Markdown→docx；混合检索 rerank；交付物六维打分
profiles / settings / ratelimit	各主文件	画像；system→user→project 分层设置；租户限流（内存/Redis）

其他目录

• modules/backend/pkg/extension/：对下游仓的公开扩展面（下游只许依赖本包与 core， surface.txt 锁导出面）；link/ 把 extension.Main 接回组合根。
• modules/backend/web/embed.go：go:embed 内嵌前端构建产物。
• modules/backend/deps/：8 个库的 submodule 副本（replace 目标）。

---

3. 前端与 UI 分工

• frontend（modules/frontend/src/）：App.tsx 四栏布局 —— 左（项目/会话树 TaskSidebar.tsx）、中（流式对话 Conversation.tsx + ProcessTimeline.tsx）、 预览区（PreviewPane.tsx / ArtifactsPanel.tsx）、右（工作台卡流 Workbench.tsx）。 职能文件：api.ts（HTTP 客户端）、live.ts（SSE 到达序投影纯逻辑）、 store.ts、runstate.ts、pluginHost.ts、outbox.ts。
• ui（modules/ui/src/）：只渲染词汇有限的 UI schema —— UIRenderer.tsx、 InboxList.tsx、InlineConfirmCard.tsx（危险命令确认卡）、ToolBlock.tsx、 tokens.css（设计令牌唯一来源）。frontend 经 @ui 别名直接源码组合（vite.config.ts）。

---

4. 通信架构：HTTP + SSE，无 WebSocket

• 全部 HTTP 路由集中在 modules/backend/internal/server/server.go 的 Handler() （约 90 条 mux.HandleFunc）：auth/users、projects/conversations/messages、cards、 artifacts/uploads、profiles/prompts/settings、tools/plugins、commands/audit、 plan/todos、knowledge、hitl 等。
• SSE 是唯一增量通道：GET /api/events?conversationId=...（server.go:171 注册， server.go:275 处理器），带 Last-Event-ID/since 游标重放；项目级流用伪会话键 project:<id>（modules/core/events.go:30 ProjectChannelKey）。全仓 grep 无 websocket。
• 事件三层转发：
  1. runmgr/events.go 事件缓冲：高频 delta 合并（150ms/64 条，events.go:42-43），先落 store（会话内单调 seq）再 bus.Publish（events.go:83）；
  2. internal/bus 内存总线 → 在线 SSE 订阅者；
  3. internal/pgbus（仅 PG 多实例档）：事务提交后 NOTIFY，其他实例 LISTEN 后按 seq 从库 取回转发本地 bus。
• 事件词汇全部定义在 modules/core/events.go 的 StreamEvent 信封 （message.delta / thinking.delta / tool.* / run.phase / hitl.request / plan.update / agent.spawn / agent.progress / card.* / artifact.* 等 20+ 类型）。

---

5. 持久化与磁盘布局

• 主库：<data>/agent-system.db（SQLite，FTS5 全文 + CJK LIKE 兜底）或 PostgreSQL （--dsn，pgx 驱动）；迁移双方言可回滚；租户隔离靠 owner 列硬过滤。
• 工件：<data>/artifacts/（blobstore 本地档，Put 原子落盘）+ store 登记。
• 技能：<data>/skills/（内置种子 + 用户覆盖）。
• 工作区沙箱：<data>/workspaces/<owner>/<conversationID>/（fs 工具根）。
• 小队运行态：编排目录下 runs/<run_id>/*.json（磁盘即权威，见小队篇）。
• 本机服务实例（scripts/svc.sh 管理）：runtime/dev/（agent 后端 + SQLite）、 runtime/pg1/（PostgreSQL）；data/、data-test/ 为默认/测试数据目录。

---

6. 插件系统

• 契约：modules/core/plugin.go（manifest v1：tools/workflows/intents/prompts/panels/ cards/commands 等 provides）；modules/core/plugin_v2.go（2.0-experimental 窗口： PluginScope 可见性、PluginBackend{inproc|sidecar}、技能/MCP/知识集/解析器/代理声明）。
• 宿主：modules/backend/internal/plugins/host.go —— 「manifest + 声明资产 + 可选代码」， 任一资产解析失败整批拒绝（fail-closed），支持热加载 Reload；host_v2.go 拉起 sidecar 进程（注入 AGENT_HOST_API/AGENT_HOST_TOKEN 环境变量）。
• sidecar 回调经 internal/hostapi/server.go 的 /host/v1（kv/audit/commands/llm/search）； 进程内插件走 pkg/extension（EXT-1）+ link 包。
• 示例：父仓 plugins/example/、examples/sidecar-demo/、examples/downstream-rdm/。

---

7. 端到端数据流（用户输入 → 结果返回）

用户输入（中栏）
  │  POST /api/conversations/{id}/messages        server.go:574 postMessage
  ├─ "/" 前缀 → cmdbus 命令总线（不启 run，server.go:623）
  ├─ 附件   → ingest.Parse 文档摄取（并行，互不依赖，server.go:643）
  ├─ 意图识别 → intentgate（agent-intent 四级漏斗，server.go:655）
  ├─ 路由裁决 → route.Decide                      route.go:60
  │     ├─ KindCommand   → cmdbus.Dispatch（直接执行命令）
  │     ├─ KindWorkflow  → runmgr.StartClaimedWorkflowRun（:996）
  │     └─ KindTurn      → runmgr.StartClaimedConversationRun（:991）
  ├─ runmgr 建 Run（pending）落库 → 选 Runner（runmgr.go:918）→ go execute()
  │     ├─ LLMRunner             → agent-native 内核 ReAct 循环（默认）
  │     ├─ CompiledWorkflowRunner → wfcompile 编译执行（可由规划子代理生成）
  │     └─ SquadRunner           → squadadapter → agent-squad 引擎
  ├─ 一切增量皆事件 → runmgr 缓冲 → store（seq 权威）→ bus → SSE
  └─ 前端 live.ts 到达序投影 → 中栏对话 / 右栏卡流 / AgentTracker

• HITL：hitl.request 卡片（choice/input/confirm/form）→ 用户 POST /api/hitl/{id}/resolve → runmgr.ResolveHITL（runmgr.go:1261）恢复或转轨。
• 工件：产物落 blobstore + store → artifact.created 事件 → 预览区；quality 六维打分。

---

8. 设计文档索引

架构权威文档在 modules/documents/docs/proposals/：

• 整体：2026-09-29-system-skeleton-design-and-plan.md（骨架设计 + D1–D16 决策，主设计）、 2026-09-30-dual-tier-storage-and-multitenancy.md（双档存储/多租户）、 2026-10-01-base-extension-roadmap.md（基座不可改、下游二开）。
• Agent 栈：2026-10-01-agent-harness.md（回合循环、多代理编排）、 2026-10-02-agent-stack-completion.md（通用智能体/小队/意图）、 2026-10-07-agent-stack-n1q1i1-plans.md、n2-plan.md、n3-plan.md（N 系列阶段方案）。
• 其他：卡片流/收件箱/命令总线/工作区（2026-09-30 三篇）、插件契约 v2、UI 重构等。

---

9. 关键文件速查

想了解什么	看哪里
程序入口与装配	modules/backend/cmd/agent-system/main.go、internal/app/app.go
全部 HTTP 路由	modules/backend/internal/server/server.go（Handler()）
Run 状态机与事件	modules/core/model.go、modules/core/events.go、internal/runmgr/runmgr.go
Agent 执行循环	deps/agent-native/runtime/loop.go、internal/runtime/llm_direct.go
意图识别	deps/agent-intent/intent/、internal/intentgate/gate.go、internal/route/route.go
小队引擎	deps/agent-squad/squad/、internal/squadadapter/adapter.go、entry.go
工作流	internal/workflow/registry.go（定义）、internal/wfcompile/（编译执行）、internal/runtime/workflow_compiled.go（入口）
工具体系	modules/core/tools.go、internal/tools/registry.go、internal/runmgr/runmgr.go:740
提示词/技能	internal/prompts/service.go、internal/skills/skills.go
前端投影	modules/frontend/src/live.ts、src/store.ts