27 KiB
多业务系统智能体平台 · 架构设计
来源：飞书文档（原文，A0-G 评审快照，2026-09-23 导入） 权威版本：本仓库。导入后飞书副本停止更新，改动走仓库提交与 ADR 流程。
**一句话：**用户在前台说需求，Pi 这个大脑把它翻译成工具调用，Core 门禁决定能不能做，Provider 翻译成各系统自己的接口，最后由业务系统执行。
本文覆盖四件事：客户端与服务端的边界、项目代码结构、控制面与智能体运行时的实现、Provider 的接入方式。文中的目录与能力名称为设计示例。
**与现有项目的关系：**本次是对现有 APS 项目的重构。现有代码不保留，只作借鉴；新系统从零实现。项目仍在开发阶段，没有客户试用数据，因此不考虑与既有数据、表结构、接口版本的兼容与迁移——旧的一切随旧代码一起退役。
落地细节（Provider 套件怎么装、多 Sub-agent 怎么协作、数据与界面、文档规范与测试）见配套文档：多系统智能体平台 · 实施设计
1 客户端与服务端
flowchart TB
subgraph CLIENT[客户端]
DESK["Electron 桌面端"]
WEBUI["Web 浏览器"]
end
subgraph SERVER["Agent Platform Server"]
ENTRY["HTTP / SSE 入口"]
APP["应用服务
会话 · 任务 · 事件发布
平台持有会话与业务记录"]
ENGINE["统一 AgentEngine 契约
开发 / 部署启动时注入一个实现"]
subgraph RUNTIME["引擎实现二选一 · 每个部署实例只运行一种"]
PIAD["PiAdapter"]
CDAD["CodexAdapter"]
PI["Pi agent-core
原生状态由适配器管理"]
CODEX["Codex app-server
原生状态由适配器管理"]
PIAD --> PI
CDAD --> CODEX
end
CORE["平台 Core
可信身份 · 代码策略 · 持久审批
幂等执行 · 审计"]
SUITE["Provider 接入
契约 · 路由 · 适配"]
end
S1["APS"]
S2["ERP"]
S3["EMS"]
DESK --> ENTRY
WEBUI --> ENTRY
ENTRY --> APP
APP --> ENGINE
ENGINE --> PIAD
ENGINE --> CDAD
PI -->|工具桥接| CORE
CODEX -->|工具桥接| CORE
APP -->|能力查询 · 审批决策 · 执行状态| CORE
CORE --> SUITE
SUITE --> S1
SUITE --> S2
SUITE --> S3
classDef default fill:#ffffff,stroke:#8a96a3,stroke-width:1.2px,color:#243247;
classDef selected fill:#fff3e8,stroke:#d78842,stroke-width:1.5px,color:#563418;
classDef ext fill:#fafafa,stroke:#8a96a3,color:#243247,stroke-dasharray:5 4;
class ENGINE selected;
class S1,S2,S3 ext;
style CLIENT fill:#f8fafc,stroke:#b7c0c9,color:#243247
style SERVER fill:#f8fafc,stroke:#b7c0c9,color:#243247
style RUNTIME fill:#ffffff,stroke:#b7c0c9,stroke-dasharray:5 4,color:#526174
linkStyle default stroke:#8a96a3,stroke-width:1.3px;
整体分两段：客户端只做界面与本地能力；服务端是引擎中立的平台服务，内部再分入口与应用服务、引擎适配、控制面、适配器四块。Pi 与 Codex 二选一，在开发或部署期选定，整段链路对客户端透明。APS、ERP、EMS 始终是平台外部的独立系统。
| 段 / 层 | 打个比方 | 负责 | 不负责 |
|---|---|---|---|
| 客户端 | 前台 | 界面、工作区、本地能力（文件、打印、设备）、断网缓存 | 业务判断、权限判断、持有业务凭据 |
| 应用服务 | 传达室 + 调度员 | HTTP / SSE、会话与任务、能力查询、审批流转、事件推送 | 业务规则、直接调业务系统 |
| Agent 引擎 | 大脑 | 理解目标、挑工具、把结果讲成人话；Pi 或 Codex 二选一 | 碰凭据、判断权限、直连业务库 |
| 平台 Core | 门禁 + 调度台 | 决定能用哪些能力、以谁的身份、要不要审批，并留痕 | 业务规则、业务数据 |
| Provider 接入 | 翻译官 | 把统一调用翻译成某个系统的 API，再翻译回统一回执 | 业务决策、持有模型上下文 |
| 业务系统 | 车间 | 自己的数据、权限、规则和状态，最终执行 | 因为平台放行就执行 |
2 项目结构
一个 monorepo，按客户端与服务端两段组织。服务端是引擎中立的平台服务：应用服务、引擎适配、控制面、Provider 接口各归其位，引擎在适配层内部选定；客户端只通过一套接口与其通信。业务系统的代码不在这个仓库里。（开发期例外：APS 暂放本仓库 aps/ 目录，形态见 ADR-0010；迁出条件也写在里面。）
agent-platform/
├── client/ # 客户端：桌面与浏览器共用
│ ├── app/ # React 界面：对话、工作区、审批
│ └── desktop/ # Electron 壳：窗口、本地守护、离线升级
├── server/ # 服务端：引擎中立的平台服务
│ ├── entry/ # HTTP / SSE 入口、会话、鉴权
│ ├── app/ # 应用服务：请求编排、能力查询、审批流转、事件推送
│ ├── agent/ # 引擎适配：统一接口 + Pi / Codex 两个实现
│ ├── core/ # 控制面
│ │ ├── registry/ # 能力目录、实例与路由
│ │ ├── identity/ # 平台用户 ↔ 各系统账号
│ │ ├── policy/ # 允许 / 拒绝 / 需审批
│ │ ├── credentials/ # 凭据托管与取用
│ │ ├── execution/ # 授权、幂等、调用网关
│ │ └── audit/ # 证据链
│ ├── provider-sdk/ # Provider 契约与契约测试
│ └── workflows/ # 跨系统顺序流程
├── providers/ # aps / erp / ems，只放适配器
├── contracts/ # 客户端与服务端共享的接口类型
├── deploy/ # 部署与实例配置
└── docs/ # 架构与接入文档
| 目录 | 职责 | 不该出现什么 |
|---|---|---|
| client/app | 对话、工作区、审批界面（React） | 业务判断、直接调 Provider |
| client/desktop | Electron 壳：窗口、本地守护、离线升级 | 业务逻辑、绕开服务端直连 Provider |
| server/entry | HTTP / SSE 入口、会话与鉴权、装配各模块 | 业务规则、直接调业务系统 |
| server/agent | 引擎适配层：统一接口，以及 Pi / Codex 两个实现；唯一允许 import 引擎 SDK 的地方 | 业务逻辑、直接 HTTP 调业务系统 |
| server/core | 能力目录、身份、策略、凭据、执行、审计 | import 任何具体 Provider |
| server/provider-sdk | Provider 接口、Schema、契约测试、跨进程调用 | 具体系统的业务语义 |
| server/workflows | 跨系统顺序流程定义 | 协议与字段细节 |
| providers/aps | APS 适配器：manifest、adapter、字段映射 | 排产算法、业务数据 |
| contracts | 客户端与服务端共享的类型与接口定义 | 任何运行时实现细节 |
**依赖方向：**client → server/entry → server/app → server/agent → server/core → provider-sdk ← providers。反向依赖用 dependency-cruiser 或 eslint 的 no-restricted-imports 卡在 CI 里，避免几个月后又缠成一团。
3 一次调用怎么走
用户说：“把下周的排产计划往后推一天。”
sequenceDiagram
participant C as 客户端
participant A as 应用服务
participant E as Agent
participant K as 平台 Core
participant P as Provider
participant B as 业务系统
Note over A,E: Agent 通过统一接口接入，Pi / Codex 在开发或部署期选定
C->>A: 消息与身份令牌
A->>A: API 鉴权、会话管理
A->>K: 按身份与会话请求可用工具
K-->>A: 工具清单与授权作用域
A->>E: 消息、上下文与受限工具集
E->>K: 受限工具桥：结构化调用
K->>K: 校验身份、作用域与策略
Note over E,K: 业务审批由 Core 管理，与引擎命令权限分开
opt 策略要求业务审批（通过后继续）
K->>K: 持久化审批单 approvalId
K-->>A: 待审批事件与影响范围
A-->>C: 业务审批卡：参数与资源版本
C->>A: 审批决定与身份凭据
A->>K: approvalId、决定与审批人
K->>K: 校验审批人及授权 grant
end
K->>K: 复核权限与资源版本
K->>K: 持久化 executionId 与幂等键
K->>P: 受控执行与短期凭据
P->>B: 业务 API 调用
B->>B: 校验自身业务规则
B-->>P: 执行回执
P-->>K: 结构化回执
K->>K: 持久化执行结果与审计
K-->>E: 工具结果与证据引用
E-->>A: 统一格式的 Agent 事件
A-->>C: 流式呈现结果与状态
| 边界 | 传什么 | 谁决定 |
|---|---|---|
| 客户端 → 服务端 | 消息与身份令牌；不含业务凭据 | 客户端发起，服务端受理 |
| 应用服务 → 引擎 | 用户目标、上下文、本会话可见的能力清单 | 应用服务装配，引擎不决定权限 |
| 引擎 → Core | capabilityId 与参数；不含凭据，不自报身份 | 引擎提议，Core 裁决 |
| Core → Provider | 主体、实例、连接、executionId、deadline、参数、幂等键、授权引用 | Core |
| Provider → 业务系统 | 原生 API 调用 | Provider |
| Provider → Core | 状态、结果引用、jobId 或 errorKind | 以业务系统的事实为准 |
| Core → 客户端 | 结果与证据引用，经 SSE 流式下发，不回灌凭据 | Core |
记住一句就够：引擎只能提议，Core 决定能不能做，业务系统最终说了算。所以换引擎或换模型都不影响安全，加系统也不用动引擎。
4 控制面 Core 怎么实现
Core 不是所有请求的中转站，而是一组被多方调用的确定性后端模块：应用服务在运行前查能力、在审批时落决定、在事后查执行；Agent 在运行中提出工具调用。这些调用都是普通代码调用，不需要再放几个 Agent 来判断。
五个服务，首版放在同一个进程里，共用 PostgreSQL：
| 服务 | 具体做什么 | 正确性的关键 |
|---|---|---|
| 身份 Identity | 验证登录身份，查用户所属租户、项目角色，以及对应业务系统的账号映射 | 身份来自可信登录链路；不接受模型自报的 userId |
| 策略 Policy | 用代码判断角色、能力、目标资源与操作类型，返回允许 / 拒绝 / 需审批 | 默认拒绝；每次真正执行前都检查，不能只在展示工具列表时过滤 |
| 审批 Approval | 把待确认动作与状态落库，界面提交确认或拒绝，校验确认者是会话发起人 | 确认绑定具体动作、参数、目标与版本；不能变成通用通行证 |
| 执行 Execution | 建执行记录，管幂等、并发、超时，调用 Provider，跟踪异步任务 | 防重复执行；超时不等于失败，结果未知时先查询 |
| 审计 Audit | 记录请求人、批准人、操作、参数摘要、结果与证据引用 | 记录完整且关联一致，并限制修改权限；普通日志文件不够 |
**以「发布排产计划」为例：**Agent 提出「发布计划 P，版本 V」→ Core 确认身份 → 判断策略 → 需要则建审批单并推送确认卡 → 批准后复核权限与资源版本 → 用唯一执行编号与幂等键调 Provider → 保存回执与审计记录。成功记回执，异步受理跟踪 jobId，结果未知进待核实。
三个容易被低估的地方：
| 常见误解 | 实际情况 |
|---|---|
| 审批就是一个弹窗 | 弹窗只是界面。真正的审批是数据库里的状态与授权记录，进程重启、Agent 退出后依然存在；聊天里说一句「同意」不能批准任意操作 |
| 执行就是发请求，失败就重试 | 对方可能已经执行成功而回执丢失。只有业务系统支持可靠幂等或状态查询时才能安全重试，否则必须保留「结果未知」 |
| Core 放行就代表能执行 | Core 查的是平台权限与授权条件；业务系统仍要校验自己的规则。审批后计划被改，应由版本校验阻止发布旧方案 |
**为什么要这么做：**业务操作是否被允许、是否已执行、是否需要审批，由这套代码决定，不随所选引擎变化。前提是每个引擎的业务调用都必须经过 Core，不能存在绕开的路径。
4.1 协作与权限以业务系统为准
平台不做协作模型：没有审批转派、委托、多人计数、角色策略、双人分离。这些是业务系统（APS、ERP）本来就有的能力，平台重复实现一遍必然和它们的权限模型对不上。人的协作发生在业务系统里，平台只负责把人映射进去、把动作调出去、把过程记下来。
| 职责 | 谁负责 | 说明 |
|---|---|---|
| 能否做（权限、角色、多级审批） | 业务系统 | 用该用户在业务系统里的身份判定；平台不复制这套规则 |
| 用什么身份做（账号映射） | 平台 | 把登录用户映射到各系统账号，调用时使用用户自己的身份，业务系统的权限随之生效 |
| 是不是想这么做（意图确认） | 平台 | 确认卡防的是 Agent 误解意图，不是防越权；答的只是发起人本人 |
| 做过什么（审计与执行记录） | 平台 | 业务系统只知道账号改了数据，不知道经由 Agent、模型建议了什么、用户确认了什么 |
**一句话：**权限归业务系统，映射与确认归平台。动作在业务系统里已有审批流的，交给它审；只有跨系统编排这类没人能替你决定意图的动作，才由平台出确认卡。
**登录态从哪来（ADR-0012）：**用户在每个系统上各自绑定一次——首选跳转该系统的授权登录（OAuth2 / OIDC），拿回来的 token 只以密文存在平台的凭据代理里；老系统没有标准登录时退化为「账号密码一次性换 token」，密码用完即弃、绝不落盘。平台不实现业务系统的登录页，也不把业务 token 下发给客户端。
4.2 确认与执行记录只存一张表
现有实现用三张表（审批请求、一次性凭据、审批事件）承载一件事。单用户场景下可以合并成一张待确认动作表：请求参数摘要、状态（待确认 / 已确认 / 已执行 / 已拒绝）、执行回执、幂等键、有效期。
**为什么能合：**批准与执行由同一个人、同一个进程完成，不需要把"批准"与"执行"拆成两个可独立消费的凭据；审批事件与审计记录重复，只保留审计。**不能省的两件事：**待确认状态必须跨进程重启存活（用户可能过一会儿才回来点确认），执行只能生效一次（幂等键加执行记录）。
4.3 代码落地（A4 已实现）
| 服务 | 代码位置 | 一句话契约 |
|---|---|---|
| 身份 | server/core/identity/context.ts |
平台用户 → 各系统账号；未绑定默认拒绝，一个系统停用不影响另一个 |
| 策略 | server/core/policy/engine.ts |
只返回允许 / 拒绝 / 需审批；顺序固定（可见性 → 身份 → 会话范围 → 动作分级），可换成 OPA 一类引擎 |
| 凭据 | server/core/credentials/broker.ts |
库里只有 AES-256-GCM 密文；按 execution 签发一次性句柄，用完即废 |
| 确认 | server/core/approval/store.ts |
确认与执行记录同表；绑定参数摘要、目标版本与有效期，重启后仍在 |
| 审计 | server/core/audit/log.ts |
只追加的哈希链，verify() 能定位被改过的那一条 |
五个模块由 server/core/control-plane/control-plane.ts 绑在一起注入 Core.invoke——引擎可以不认识它们，但绕不过它们。
**平台不覆盖业务系统的拒绝：**Provider 回 forbidden 就是最终结果，平台不改写成成功、不自动重试；审计里记的是「业务系统拒绝」。平台能加限制，不能替业务系统放行。
**开发期例外：**Provider 在 manifest 里声明 requiresIdentity: false 表示该系统没有账号概念（假 Provider 与联调桩），真实系统默认需要绑定。
5 引擎适配
5.1 适配层的边界规则
Pi 以 npm 包形式发布（MIT），装进 monorepo 当依赖，不需要 git submodule。首版把 Pi 作为长驻子进程运行：用官方 RpcClient 驱动（它负责拉起进程、按 id 关联响应、把事件推给监听者），协议是标准输入输出的 JSONL。这样与 Codex 的进程模型一致，也把智能体循环从平台的事件循环里隔离出去。
**硬前提：**Node ≥ 22.19.0，部署镜像要跟上。具体接入方式、代码示例与推进顺序见实施设计。
| 边界规则 | 说明 |
|---|---|
| 只有一个入口 | 只有 server/agent 允许 import Pi，其它模块必须通过这一层 |
| 工具只来自能力目录 | 不注册文件、shell、网络类工具，避免绕开 Core |
| 每次都过 Core | 工具的 execute 内部只调 core.invoke，不允许自己发 HTTP 请求到业务系统 |
| 按身份给工具 | 工具列表按用户身份过滤；切换用户要重建会话，不能复用工具集 |
| 凭据不进工具 | 凭据在 server/core/execution 注入，工具参数与模型上下文里出现凭据即视为缺陷 |
| 会话落库 | 消息与执行记录存 PostgreSQL；Pi 只负责内存态与事件流 |
5.2 两个引擎与切换方式
两个引擎都以长驻子进程运行，循环模型一致：平台拉起进程、发提示、收事件、发取消，互不理解对方的内部协议。差异集中在工具面——Codex 可通过 MCP 或实验性动态工具接收平台能力，Pi 需要在 pi 侧写一个扩展，把工具调用以本地 HTTP 回调平台，平台再走 Core.invoke。所以适配层要抹平的是工具面，不是事件循环。
目标是可替换，不是行为一致：三个固定点不动，两个实现可换。
**切换发生在开发或部署期，不是用户使用中。**一个部署实例只运行一种引擎，整段链路对客户端透明；这省掉了跨引擎会话交接、双引擎并行和审批跨引擎延续等一大堆复杂度。同一会话不中途换引擎。
| 固定点 | 内容 | 为什么 |
|---|---|---|
| 领域类型 | 会话、消息、事件、回执都是我们自己的类型 | 一旦运行时的类型渗出来，换的时候就是全平台改造 |
| 工具出口 | 任何运行时的工具调用都落到 Core.invoke | 这是门禁，也是唯一能统一两个运行时的地方 |
| 状态 | 会话与执行记录由平台保存 | 运行时只借循环、不借状态，换的时候不用迁数据 |
接口只描述「怎么驱动一个循环」，不描述「允许做什么」：
interface AgentRuntime {
createSession(input: {
subject: Subject;
system?: string;
tools: ToolDescriptor[]; // 能力目录投影
history?: Message[]; // 平台保存的历史，可恢复
}): Promise<RuntimeSession>;
}
interface RuntimeSession {
send(text: string, opts?: { signal?: AbortSignal }): AsyncIterable<RuntimeEvent>;
abort(): void;
}
type RuntimeEvent =
| { type: "text"; delta: string }
| { type: "tool_call"; callId: string; name: string; args: unknown }
| { type: "tool_result"; callId: string; receipt: ExecutionReceipt }
| { type: "approval_required"; request: ApprovalRequest }
| { type: "turn_end"; usage: Usage }
| { type: "error"; kind: ErrorKind };
| 部件 | Pi | Codex | 共同契约 |
|---|---|---|---|
| 驱动 | 长驻子进程（RpcClient 驱动，JSONL 协议） | 子进程 app-server | AgentRuntime 接口 |
| 工具面 | RPC 无注册工具通道，靠 Pi 侧扩展桥回调平台 | MCP 服务，并关掉它自带的 shell 与文件工具 | 两边都落到 Core.invoke |
| 事件 | subscribe 回调 | 协议事件流 | 统一的 RuntimeEvent |
| 审批 | 不内置，由 Core 出确认卡 | 自带审批，需映射到 Core 确认卡 | 统一的审批请求与响应 |
| 会话 | 平台存 | 平台存，镜像它的事件 | 平台自己的会话格式 |
**难点只有一个，而且是已知的：**工具面的接法两边不同——Codex 有现成的 MCP 通道，Pi 要靠扩展桥。所以「兼容」的实质是两个工具面都要实现，且都必须汇到 Core.invoke。这也是为什么切换成本集中在工具面，而不是事件循环。进程管理那部分反而是共用的：启停、超时、崩溃重启、日志轮转、父进程看门狗只写一套。
**不实现别人的协议。**Codex 的协议只活在它的适配器内部，客户端与 Core 都不感知；服务端与客户端之间只认我们自己的一套接口（HTTP / SSE）。协议的所有权比协议的兼容性重要。
**推进方式：**现在只做四件事——定义引擎接口、守住三条纪律、写引擎进程管理与 Pi 扩展桥、写一个假引擎跑一致性测试；Codex 驱动等到真要切换时再写。
**验收方式就是一套一致性测试：**两个驱动跑同一套用例——多轮对话、工具调用与回执、事件顺序、取消、错误分类、会话恢复。过不了就不算兼容。
**做不到的部分要说清楚：**运行时独有的能力（Pi 的插话与追问、Codex 的沙箱）用能力声明暴露，界面按开关走，不做统一封装；审批粒度不可能完全对等，Codex 审批命令与补丁，我们审批业务动作，只能近似映射；提示词与工具描述格式不同，要各调一份。
6 Provider 契约
Provider 是能力适配器，不是业务系统，也不承载模型上下文。接口只三个方法：
interface Provider {
describe(): Promise<ProviderManifest>; // 声明能力
invoke(ctx: ExecutionContext, call: CapabilityCall): Promise<ExecutionReceipt>;
health(): Promise<HealthStatus>;
}
interface Capability {
id: string; // 如 aps.schedule.publish
description: string; // 给模型看的用途说明
effect: "read" | "draft" | "write"; // draft：只写隔离草稿
mode: "sync" | "async";
inputSchema: JsonSchema;
outputSchema: JsonSchema;
idempotency: "none" | "key" | "natural";
errors: ErrorKind[];
}
Provider 还要声明登录方式（ADR-0012），平台按声明走同一条绑定流程，不自己实现业务系统的登录页：
auth.kind |
用于 | 平台做什么 |
|---|---|---|
oauth |
有标准授权登录的系统（首选） | 发起跳转 → 收回调 code → 用 exchange() 换 token |
password-exchange |
老系统，没有标准登录 | 收一次账号密码 → exchange() 换 token，密码用完即弃 |
apikey |
系统级集成、无人值守 | 管理员配置，密钥挂在租户或实例上 |
| 不声明 | 没有账号概念的自建系统（联调桩） | 视为 requiresIdentity: false |
Provider 的开发步骤、运行机制与契约测试见实施设计。
**能力声明的取舍：**read 不改变状态；draft 只写隔离草稿，不走审批但必须声明清理方式；write 必须绑定唯一目标、幂等键与授权引用。sync 直接返回结果，async 先返回 jobId。
7 桌面端怎么选
桌面端在客户端这一侧，只做界面与本地能力；引擎与 Core 都在服务端。服务端可以集中部署在内网、与客户端同机部署，或混合部署（本地只保留设备与文件能力）。桌面壳的选择不影响智能体架构，真正决定选型的是“服务端部署在哪、工厂有没有网”。
| 方案 | 体积 | Node 支持 | 工厂离线环境 | 结论 |
|---|---|---|---|---|
| Electron | 150MB 起 | 内置，Pi 可直接跑 | 自带 Chromium，不依赖系统组件 | 首版推荐 |
| Tauri v2 | 10-20MB，另加 Node sidecar | 需自带 sidecar 二进制 | 依赖系统 WebView2，老机器可能缺失 | 包体或内存成为硬指标时再评估 |
| 纯浏览器 / PWA | 0 | 无 | 依赖现场浏览器版本 | 不需要本地设备能力时最省 |
**首版选 Electron：**工厂离线 PC 不用赌 WebView2，离线升级、进程守护、单实例都有成熟做法。Tauri 包体小，但没有 Node 运行时，主进程逻辑要用 Rust 重写且依赖系统 WebView2；等包体或内存成为硬指标时再评估。
| 桌面端边界 | 说明 |
|---|---|
| 不直连 Provider | 所有业务调用走平台 API，桌面端只是入口 |
| 不持有业务凭据 | 凭据只存在平台凭据代理，本地不落长期密钥；设备证书加用户登录双重身份，换设备或换人都可追溯 |
| 本地 runner 只做本地事 | 打印、扫码、文件、设备采集可以本地做，业务写操作仍要过 Core |
| 离线只缓存不越权 | 断网时排队与重试，恢复后仍要过策略与审批，不能本地放行 |
8 首版范围
| 先做 | 暂不做 |
|---|---|
| 一个 TypeScript / Node 平台服务 + Pi 运行库 + PostgreSQL | OPA、消息总线、Temporal / Camunda |
| Electron 桌面壳，复用同一套 Web 界面 | Tauri 迁移 |
| Provider 跑在平台侧，进程内或边车 | 可视化编排 |
| 代码内声明的顺序流程 + 每步结果落库 | 配置化 DAG 引擎 |
| APS 三个能力跑通，外加 ERP 或 EMS 一个只读能力 | 一次接入全部系统 |
| 验收项 | 标准 |
|---|---|
| 身份 | 不同系统的登录态可独立失效；桌面端能定位到设备与用户 |
| 权限 | 业务拒绝不会被 Core 放行 |
| 幂等 | 同一写请求重试不重复生效，或明确返回结果未知 |
| 停用 | 停用 Provider 后不再接收新调用 |
| 可观测 | 一个系统失败时能看清各步骤的实际结果 |
9 附录：ChatGPT 客户端的架构
记录另一个真实产品的做法，供参考，不是本项目采用的方案。一句话概括：宿主负责策略与界面，独立进程负责循环与执行，能力以 MCP 子进程接入，审批用 RPC 回流。证据来自本机进程实测与开源仓库源码，官方文档站在当前环境访问不到。
| 部件 | 形态 | 职责 |
|---|---|---|
| 外壳 | ChatGPT.exe（Electron），9 个进程 | 窗口与交互，以及宿主能力：文件、浏览器、电脑操作、插件 |
| agent 后端 | codex app-server（Rust），1 个进程 | 模型调用、智能体循环、工具编排、沙箱执行、审批策略 |
| 能力进程 | MCP 服务器（Node），22 个进程 | 每个启用的插件一个，作为工具接入后端 |
| 状态 | ~/.codex | 会话与回放记录、会话索引、历史文件，以及线程历史、状态、日志等数据库 |
| 通信 | 标准输入输出；源码还支持本地 socket 与 WebSocket | 自有 app-server 协议（v1 / v2），RPC 风格；审批请求从 agent 回流到宿主 |
| 结论 | 做法 | 说明 |
|---|---|---|
| 可借鉴 | 后端长驻，不随请求起进程 | 模型与工具状态可以复用，冷启动只发生一次 |
| 可借鉴 | 能力独立进程或独立服务 | 插件崩溃不拖垮 agent；与本项目 Provider 独立部署是同一个思路 |
| 可借鉴 | 审批从 agent 回流到宿主 | 策略留在宿主，agent 不自己放行；与 Core 做唯一裁决者一致 |
| 不照搬 | 直接采用它的 app-server 协议 | 内部演进的协议，两代并存，跟着走会被绑住 |
| 不照搬 | 把会话状态交给它 | 状态归它所有，我们拿不到控制权，还会出现两份真相 |
| 不照搬 | 按它的规模铺进程 | 实测整棵树 54 个进程、约 3.25 GB，工厂现场需要评估 |
形态可学，实现自建：Core 是唯一裁决者，Provider 独立部署且只暴露契约，客户端只做界面与本地守护。要切换引擎的做法见 5.2。