# 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` |