架构总览

平台由五个能力层、三类 Agent、三种接入方式组成。这一页给出全局视图，后续页面逐层展开。
三类 Agent：平台内部编排 Agent（需求翻译、结果综合）、平台托管门面 Agent（企业的 AI 前台，由内置 AgentRuntime 执行）、企业自有交付 Agent（运行时在企业侧，通过 A2A 接入）。

五层架构

┌──────────────────────────────────────────────────────────────┐
│ 接入层                                                        │
│   HTTP API · WebSocket · A2A · SSE 对话                       │
├──────────────────────────────────────────────────────────────┤
│ 编排层                                                        │
│   Run · Task · Workflow(投影) · Execution · Result Synthesis  │
├──────────────────────────────────────────────────────────────┤
│ 能力层                                                        │
│   Skill Catalog · Agent Profile · Matching · Dialogue         │
├──────────────────────────────────────────────────────────────┤
│ 信任层                                                        │
│   Verification · Fulfillment · Escrow · State                 │
├──────────────────────────────────────────────────────────────┤
│ 基础设施层                                                    │
│   MySQL · MongoDB · Redis · Bull · COS · LLM · 支付            │
└──────────────────────────────────────────────────────────────┘

层	回答的问题	主要模块
接入层	谁能调用、怎么调用	`apps/hushwork`、`a2a`、`agent-gateway`、`dialog`
编排层	一件事怎么拆、按什么顺序做	`run`、`task`、`workflow`、`chat-execute`、`agent-runtime`、`reporter`
能力层	有什么能力、谁能提供、选谁	`agent`、`agent-profile`、`agent-matching`、`demand-translation`
信任层	做得对不对、出了问题怎么办	`verification`、`fulfillment`、`escrow`、`state`
基础设施层	数据放哪、消息怎么传、模型怎么调	TypeORM / Mongoose / ioredis / Bull / COS / OpenAI

双模式

平台同时支持两种供给形态，共用同一套契约：

	共享 Agent（Public）	私有 Agent（Private）
提供方	第三方服务商	需求方自己
运行位置	服务商环境	企业内网 / 私有云
数据边界	经平台沙箱流转	不出企业边界
适用	标准化、低频、公共知识	高频、敏感、核心壁垒
计费	按次 / 按月	自建成本
参与编排	✅	✅（可与共享 Agent 混排）

两种模式在代码上没有分叉：都是 AgentProfile + skillIds + a2aEndpoint，由匹配引擎统一评分。

模块全景

apps/hushwork
  ├── task/                 任务生命周期、执行、摘要、反馈
  ├── workflow/             DAG 定义、模板、执行器、数据流
  ├── agent/                Skill Catalog
  ├── agent-profile/        Agent 注册与上架
  ├── agent-matching/       四维评分匹配
  ├── agent-gateway/        WebSocket / 离线任务 / 心跳 / 对话
  ├── a2a/                  A2A 客户端与平台端点
  ├── demand-translation/   自然语言 → 子任务
  ├── chat-execute/         Chat 主链路的 prepare → execute 桥接
  ├── dialog/               多轮对话与消息持久化
  ├── compliance-engine/    合规定向能力
  ├── verification/         输出验证
  ├── reporter/             结构化报告
  ├── fulfillment/          交付 / 验收 / 争议 / 处置
  ├── escrow/               托管 / 结算指令 / 赔付策略
  ├── state/                状态层（事件溯源）
  ├── policy-settings/      运行时商业参数
  ├── dispute-timeout/      争议超时扫描
  └── reference-case/       端到端参考业务

完整清单与逐模块说明见模块参考。

依赖方向

demand-translation ──▶ agent(Skill) · agent-matching · agent-gateway · workflow
agent-matching     ──▶ agent-profile
agent-gateway      ──▶ agent-profile · a2a
workflow           ──▶ agent-gateway · agent · a2a
chat-execute       ──▶ task · demand-translation · agent-matching · workflow · dialog
task               ──▶ workflow · agent-gateway · engine
fulfillment        ──▶ state
escrow             ──▶ state
state              ──▶ (仅 mongoose，叶子模块)

设计约束：

state 是叶子模块，只依赖 mongoose，避免循环依赖
fulfillment 不依赖 fulfillment 之外的业务模块，只接裁定输入
escrow 不依赖 fulfillment，可独立测试
信任层旁挂在执行链路之外，不替换既有路径

运行时拓扑

                    ┌─────────────┐
   浏览器 / 客户端 ──▶│   Nginx     │──▶ 静态前端（Vite 构建产物）
                    │   :443      │──▶ /api/*  → NestJS :3000
                    └─────────────┘──▶ /socket.io → NestJS :3000
                                              │
                    ┌─────────────────────────┼─────────────────────────┐
                    ▼                         ▼                         ▼
              MySQL (TypeORM)          MongoDB (Mongoose)          Redis
              任务 / 订单 / 账户        工作流 / Agent / 状态       缓存 / 队列
                                              │
                                              ▼
                                    外部 Agent（A2A over HTTP）

外部 Agent 由谁运行、用什么框架，平台不关心；平台只要求一个可访问的 HTTP 端点。

门面的运行时在平台进程内：delivery=local-skill 的门面不接外部端点，由 agent-runtime 模块在同一进程里执行（预算 + 工具白名单 + 结构化校验），跑完即释放。前台展示页、对话入口与 Agent Card 都由平台提供，企业只提供业务说明与契约。

关键设计决策

决策	理由	代价
门面运行时自建，业务 Agent 运行时不自建	门面是平台产品，必须可审计、可计量、可限流；业务交付的责任在企业，用他们自己的框架更合适	门面受平台模型与预算约束；业务 Agent 的内部实现仍不可审计
A2A 作为标准协议	与框架无关，任何 HTTP Agent 可接入	需要 Agent 自行实现协议端点
Schema 驱动的确定性匹配	B 端容错率低，语义相似度不够	新能力必须先定义 Skill
状态层旁挂	不改变既有执行路径，风险可控	两套写入需要事务保证一致
金额用整数最小单位	浮点误差会破坏金额守恒	所有金额转换需显式处理
信任层只产出指令	真实资金涉及牌照与合规	结算仍是半自动
MySQL + MongoDB 双库	交易数据用关系型，文档型数据用 Mongo	跨库一致性需要显式设计

一次请求经过哪些模块

以"用户提交一个合规需求"为例：

HTTP POST /api/chat/prepare
  → chat-execute.prepare
      → dialog          取最近对话
      → demand-translation  拆解子任务
      → agent-matching  为每个子任务选 Agent
      → workflow        构建并发布 DAG
      → agent-gateway   推送任务
  → 返回 workflowId / taskId / nodes

HTTP POST /api/chat/execute
  → task.startExecution
      → workflow.executeAgentNode
          → 内部 Agent：engine.directPrompt
          → 外部 Agent：a2a.executeTask（失败降级 gateway）
      → 节点结果写回 Task
      → reporter 汇总
      → fulfillment / state 旁挂留痕

细节见一次需求的完整生命周期。

下一步

逐段拆解主链路 → 一次需求的完整生命周期
理解外部 Agent 如何接入 → 外部 Agent 接入
理解状态与证据 → 状态层
查模块细节 → 模块参考

架构总览 ​

五层架构 ​

双模式 ​

模块全景 ​

依赖方向 ​

运行时拓扑 ​

关键设计决策 ​

一次请求经过哪些模块 ​

下一步 ​