weichen
09d968cb2f
Why: 系统缺少面向新人与新任务的现状导览；把结构/意图识别/任务执行/小队 四条主线的架构、模型与调用链整理成五篇参考文档，降低跨仓定位成本。 Evidence: 锚点核验于 Dev 组合 218fc4b1ba00b0a03b5bb79f292b3eba6c987a58 （2026-10-08，引用的函数入口行号逐一 grep 定位）；git diff --check 通过； 五篇互链相对路径全部可解析。SRC=SELF（本地核验，任务卡有记录）。 Impact: 纯文档新增（docs/guides 五篇），无代码/契约/配置影响。 Refs: Dev 任务分支 feature/architecture-guides（R0 218fc4b1）。
214 lines
14 KiB
Markdown
214 lines
14 KiB
Markdown
# 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` |
|