# Work OS MVP · Agent Runtime 系统架构与功能设计 v1.0 > 日期:2026-10-10。10 月 18 日前验收 PC,腾讯云随后验收。**现已实现 PC 单进程持久化 Runtime 与管理员画布;本文为完整目标设计,已实现范围和限制以 [实现与验收说明](../../AgentRuntime/README.md) 为准。分布式调度和真实下游尚未接入。**关联:[总体架构](../06_系统设计文档.md)、[公共工作流契约](../09_架构契约/workflow.json)、[API Gateway](../10_API_Gateway/README.md)、[Workspace Service](../11_Workspace_Service/README.md)。员工端留空数字员工时走直接模型对话,不创建 Agent Run。 ## 1. 模块定位和边界 Agent Runtime 是数字员工工作流的执行器:校验已发布的工作流,冻结运行输入,按依赖执行节点,记录步骤与事件,等待人工确认,恢复或取消任务。它不负责登录、事项所有权、知识库原文、模型协议、本机工具执行或通知实际投递。所有外部读写经类型化 Port,禁止跨模块查表。 | 上层 | 接口与数据 | 安全边界 | |---|---|---| | Portal Web 经 API Gateway | 开始、查状态、SSE 进度、取消、确认 | Gateway 验证 Bearer、幂等键;Runtime 再核验事项归属 | | Admin Web 经 API Gateway | 画布草稿、校验、发布、运行观察 | 管理员作用域、审计;已接入管理员鉴权和服务端配置;工作组等其他菜单仍为原型 | | Workspace 领域事件 | 附件与草稿状态提示 | 事件只触发检查,运行时须重新读取权威状态 | | 下层 Port | 调用内容 | PC 与云的接入 | |---|---|---| | WorkspacePort | 事项、消息、附件、草稿版本、确认前校验 | PC 同进程接口;云内部 HTTPS,DTO 不变 | | ContextPort | 事项上下文与会话摘要 | 桩 → 内部服务 | | KnowledgePort | 依据检索、引用、工作组权限过滤 | 桩 → 内部 HTTP | | LLMPort | 理解、起草、复核;超时与 token 预算 | LLM Gateway 桩 → 内部服务 | | ToolPort | 保存、导出、OA 适配器和回执 | 只经 Tool Gateway;带副作用幂等键 | | NotificationPort | 站内/企业微信应用消息请求 | outbox 异步投递 | | WorkflowRegistryPort | 已发布、不可变的流程及 Skill | PC 数据库/文件快照;云可换配置仓库 | 设计约束:身份由服务端派生并贯穿 Run/Step/工具调用;同一事项只允许一个活跃 Run;PC 最多同时执行 2 个任务;开始时固定流程/数字员工/Skill/模型策略版本及哈希;所有外部副作用有稳定 effect_key 与回执;直接聊天走 Gateway → LLM Gateway / Workspace,不经过 Runtime。 ## 2. 小模块、技术栈和国产化 Portal/Admin → API Gateway → Run Application API ↓ Workflow Registry → Run/Step/Event Repository ↓ Lease Dispatcher → Graph Executor / State Machine ↓ Node Handler Registry ↙ ↓ ↓ ↓ ↘ Workspace Context Knowledge LLM Tool ↓ Outbox → SSE / Notification | 小模块 | PC 技术和框架 | 扩展点 | |---|---|---| | API/DTO | Python 3.11+、FastAPI、Pydantic 2、OpenAPI 3.1 | Gateway 统一公网入口;内部 Port 可换 HTTP/gRPC 适配器 | | Registry/Graph | Python Protocol、JSON Schema、受控 DAG 编译器 | 节点类型经允许名单注册;不执行任意代码 | | Application/状态机 | 显式状态转移、依赖注入、可重放 Command | 处理器与 Gateway 路由解耦 | | Repository | SQLAlchemy 2、Alembic、PostgreSQL | SQLite 只用于单机功能演示,不能证明并发可靠性 | | Dispatcher | PostgreSQL FOR UPDATE SKIP LOCKED + 租约与 generation;单 Worker/2 槽 | 云可多 Worker;RabbitMQ/Kafka 仅负责唤醒 | | Event/SSE | 事务 outbox、run_event 顺序号、FastAPI StreamingResponse | Redis 可加速广播但不做唯一事实源 | | Observability | JSON 日志、trace/run/step ID、指标端口 | Prometheus/Grafana、集中日志 | | Deployment | uvicorn + Worker,受限文件目录 | systemd/OCI、内部网段、健康检查 | PostgreSQL [SELECT 文档](https://www.postgresql.org/docs/current/sql-select.html)描述 SKIP LOCKED 的锁语义,适合队列领取,不适合普通权限查询。若引入 RabbitMQ,须分别处理[消费者确认和发布确认](https://www.rabbitmq.com/docs/confirms),它们不替代业务幂等。SSE 使用 [FastAPI StreamingResponse](https://fastapi.tiangolo.com/advanced/custom-response/) 与持久游标。 目标为银河麒麟高级服务器操作系统 V10 SP3/海光。麒麟官方[产品说明](https://www.kylinos.cn/productPc/server/serverMain/additional)列出海光支持,但这不等于本项目 Python wheel、psycopg、OpenSSL、容器镜像已适配。运行时避免 Windows DLL、COM 和 x86 专属指令;依赖锁版本和哈希。迁移验收要在目标机核对架构与 Python 原生依赖、数据库迁移、双 Worker 抢占、宕机恢复、SSE 和 Tool Port。公网 Qwen 仍只由 LLM Gateway 接入。 ## 3. 流程定义与低代码扩展 以[现有线性公文流程](../09_架构契约/workflow.json)为起点。正式定义为受约束 DAG:节点字段 id、kind、input_mapping、timeout、retry_policy、on_error;边字段 source、target、condition。发布校验必须拒绝环、悬空边、未知 kind、无界循环、从未经确认节点直达副作用工具。PC 优先支持线性流程和人工暂停;管理画布产生草稿 JSON,草稿不能直接执行,需管理员校验发布不可变版本。 建议目录: AgentRuntime/ api/ # Gateway DTO 适配 application/ # start/get/cancel/approve domain/ # Run、Step、状态机、GraphCompiler handlers/ # validate/context/knowledge/llm/review/human/tool/notify ports/ # Workspace/Knowledge/LLM/Tool/Notification/Registry adapters/ # fixture、内部 HTTP、PostgreSQL、outbox migrations/ # run/step/event/approval/effect tests/ # 契约、隔离、故障恢复与幂等 NodeHandler 协议为异步 execute(RunContext, StepSpec) → StepResult。ToolPort 的 invoke(tool_id, args, principal, effect_key, approval_token) → ToolReceipt 是唯一工具路径。HandlerRegistry 从允许名单配置 kind → handler。增加节点只改 Schema、Handler、测试和管理节点目录,**不改 Gateway 公共 Run API 或 Executor**。更新 Handler 要保留旧版本至旧 Run 完结,或提供显式迁移器。Step 记录 handler/version 与输入哈希。 ## 4. 状态机、数据与事务 Run:queued → running → awaiting_confirmation → running → succeeded;非终态可转 failed/cancelled。Step:pending → leased → running → succeeded;也可转 retry_wait/failed/skipped/awaiting_confirmation。非法转移返回 409 RUN_STATE_CONFLICT。终态不可重新确认。取消后若工具已执行,必须记录真实结果,不假称回滚。 | 表 | 核心字段 | 必要约束 | |---|---|---| | agent_run | run_id、tenant/owner/workspace、workflow_id/version/hash、skill_snapshots、status、input_message_id、artifact_id、lease_owner/generation/expires_at | 活跃事项唯一;owner+workspace 索引 | | agent_step | step_id、run_id、node_id、handler_kind/version、status、attempt、input/output_ref、timeout_at、effect_key | run_id+node_id 唯一 | | run_event | run_id、sequence、event_type、step_id、payload、occurred_at | run_id+sequence 唯一;单调、不覆盖 | | run_approval | run_id、artifact_id、version、SHA-256、approver、decision | 每一草稿版本只接收一次有效确认 | | tool_effect | effect_key、run_id、step_id、tool_id、request_hash、receipt_id、status | effect_key 唯一;不同参数复用同键拒绝 | | runtime_outbox | event_id、aggregate_id、type、payload、publish_state、attempt | 与业务状态同事务写入 | start 在一次事务内验证事项/输入消息归属、已发布流程、Skill 快照和活跃 Run 限制,写 Run、初始 Step、task.queued 事件和 outbox;提交后才唤醒 Worker。Worker 按行锁领取 Run 并更新 generation;Step 提交前检查代数,租约过期的旧 Worker 不能覆盖新结果。纯计算和模型步骤可按策略重试;工具与通知先以稳定 effect_key 查询回执。网络超时但对方可能成功时须查回执或转人工核查,禁止盲目重发。 草稿由 Workspace 持久化并返回 artifact_id、version、content_hash。待确认时 Runtime 不调用 Tool。确认必须匹配当前草稿版本/哈希及审批权限,成功后封存批准快照,再允许 ToolPort 保存/导出。修改草稿使旧确认失效。取消标记 cancel_requested,阻止后续节点;不可取消的在途调用仍记录回执。 ## 5. 接口列表与示例 全部 HTTP 经 Gateway 前缀 /api/v1,使用 Bearer。写接口需 Idempotency-Key(8–128 字符)。客户端不得提供 owner/tenant 字段。前五个 Run 接口在现有演示桩部分实现;管理员接口待开发。 | 方法/路径 | 用途与输入 | 成功/关键错误 | |---|---|---| | POST /workspaces/{workspace_id}/runs | employee_id、input_message_id、skill_ids | 202 Run;401/403/404/409 活跃冲突/422 | | GET /runs/{run_id} | 状态、流程版本、成果 | 200 Run;404 对无权者不暴露存在性 | | GET /runs/{run_id}/events?after_sequence=n | SSE 增量;支持 Last-Event-ID | 200 text/event-stream;400 游标/429 连接上限 | | POST /runs/{run_id}/cancel | 幂等取消 | 202;终态 409 | | POST /runs/{run_id}/approval | artifact_id、expected_version、content_hash | 202;版本/状态冲突 409 | | GET /admin/workflows | 已发布/草稿流程分页 | 200;非管理员 403 | | POST /admin/workflows/validate | DAG JSON 校验 | 200 issues;422 | | POST /admin/workflows/{id}/versions | 发布冻结版本、备注、幂等键 | 201;冲突 409 | | GET /admin/runs | status/owner/time/cursor | 200 分页;403 | 开始请求示例: POST /api/v1/workspaces/ws_123/runs Authorization: Bearer Idempotency-Key: run-20261010-001 Content-Type: application/json {"employee_id":"official-document-writer","input_message_id":"msg_123","skill_ids":["skill_official_format"]} 响应示例: {"run_id":"run_123","workspace_id":"ws_123","status":"queued", "workflow_id":"official_document_v1","workflow_version":"0.1.0", "last_sequence":1,"effective_skills":[{"skill_id":"skill_official_format", "version":1,"content_hash":""}]} SSE 示例: id: run_123:7 event: step.completed data: {"run_id":"run_123","sequence":7,"event_type":"step.completed","step_id":"retrieve","payload":{"citation_ids":["citation_1"]}} 确认请求示例: POST /api/v1/runs/run_123/approval Authorization: Bearer Idempotency-Key: approval-20261010-001 {"artifact_id":"art_123","expected_version":2,"content_hash":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"} 统一错误体示例:{"code":"RUN_STATE_CONFLICT","message":"草稿版本已改变","trace_id":"...","details":{"current_version":3}}。SSE 事件带 schema_version、run_id、sequence、event_type、occurred_at、step_id、payload;浏览器按 sequence 去重。 ## 6. 办文工作流实例 1. 员工在 Workspace 输入办文要求并选择公文写作数字员工。Gateway 验证身份和幂等,Workspace 保存消息。 2. Gateway 调 Runtime start。Runtime 重新验证消息和事项归属,取已发布 Workflow/Agent 与 Skill 快照,创建 Run 和初始事件,返回 202。Gateway 不直接执行节点。 3. Worker 检查附件就绪,从 Context 取摘要,经 LLM Gateway 理解需求;Knowledge 检索格式、制度与历史文档,返回引用 ID。每步事件持久化并经 Gateway SSE 推送。 4. 起草节点送输入、Skill 快照与引用给 LLM Gateway;草稿写入 Workspace。复核节点检查格式、引用和缺项,未知日期标记待确认。 5. Run 转 awaiting_confirmation。员工编辑后 Workspace 产生新版本/哈希。Runtime 只接受当前版本确认。 6. 确认后通过 Tool Gateway 保存或导出,带批准凭据和 effect_key;记录回执。随后完成事件进入 outbox,Notification Service 可投企业微信应用消息;投递失败单列并重试。 7. 客户端断线按 Last-Event-ID 补发。Worker 崩溃时租约到期,继任 Worker 从已提交 checkpoint 继续;工具超时先查回执。 失败分支:知识依据不足时提示人工补件;LLM 超时在预算内重试;版本冲突 409;OA 工具不确定结果禁止自动重做;取消后不再发起新工具调用。trace/run/step ID 贯穿审计。 ## 7. 开发切片与估算(单人 + Vibe Coding) 人时为净开发和验证,AI Token 为输入加输出的粗估,不是费用承诺。PC 先做 RT01–RT08,云/国产化随后。每项都需要契约、实现、可证明的验收。 | 任务 | 小模块 | 前置依赖 | 人时 | AI Token | 完成性检验 | |---|---|---|---:|---:|---| | RT01 流程 Schema、发布校验 | Registry | 公共 workflow、管理身份 | 8 | 80k–130k | 环、未知节点、越权工具均拒绝;版本不可改 | | RT02 Run/Step/Event 迁移与索引 | Repository | RT01、Workspace Port | 10 | 100k–160k | 迁移、事项唯一活跃、跨用户隔离 | | RT03 start/get/cancel/approve | Application | RT02、Gateway、Workspace | 12 | 120k–190k | 幂等、并发、版本、权限矩阵 | | RT04 派工/租约/checkpoint | Executor | RT02 | 14 | 140k–220k | 双 Worker 不重复领取;杀进程后恢复 | | RT05 节点处理器与 Port | Handlers | RT01、RT04、各下层 Port | 16 | 160k–250k | 从输入到待确认;各桩可替换 | | RT06 工具副作用/人工确认 | Tool/Human | RT03、RT05、Tool Gateway | 10 | 100k–170k | 旧版确认失败;超时不盲重试 | | RT07 SSE/outbox/通知 | Events | RT02、RT04、Notification | 8 | 80k–130k | 事件有序、断线补发、重投安全 | | RT08 PC 集成与故障演示 | QA | RT01–RT07、Portal | 10 | 80k–140k | 2 用户隔离、2 并发、取消/恢复演示 | | RT09 腾讯云单机部署 | Deployment | RT08 | 8 | 60k–100k | 备份恢复、内网访问、日志指标 | | RT10 麒麟/海光实测 | Portability | RT09、目标硬件 | 12 | 80k–130k | 原生依赖、数据库/Worker/SSE 适配记录 | RT01–RT08 合计估计 88 人时,单人约一周不能默认全做完。10 月 18 日 PC 优先真实主链路:RT01–03 和 RT05 线性流程、RT07 基本进度。若 RT04 多 Worker 恢复或 RT06 完整副作用回执尚未实现,必须明确标识;不能把同步桩称正式 Runtime。 ## 8. 需求清单与完成性验收 P0 是 PC 主链路,P1 是云和运营,P2 是国产化/规模化。状态“已演示部分”仅表示现有桩与界面能展示相关行为;不代表真 Runtime。 | ID | 优先级 | 小模块 | 明确需求 | 验收证据 | 当前状态 | |---|---|---|---|---|---| | AR-01 | P0 | Registry | 流程稳定 ID/版本;发布校验节点、边、权限路径 | 错图返回节点位置;旧版本不可覆盖 | 待开发 | | AR-02 | P0 | Application | 数字员工与输入消息必须属于同一事项;只取服务端身份 | 跨用户/跨事项请求拒绝 | 已演示部分 | | AR-03 | P0 | Application | 同事项只允许 1 活跃 Run;写请求幂等 | 并发只成功 1 次;同键同结果 | 已演示部分 | | AR-04 | P0 | Snapshot | 固定 Workflow/Agent/Skill 版本和哈希 | 改 Skill 不影响已有 Run | 已演示部分 | | AR-05 | P0 | Executor | 按依赖执行理解、检索、起草、复核 | 步骤事件顺序一致;失败不跳过 | 已演示桩 | | AR-06 | P0 | Ports | 所有下层经类型化 Port;配置可换适配器 | 换适配器不改流程/Gateway 路由 | 待开发 | | AR-07 | P0 | Workspace | 草稿保存来源、版本和 SHA-256 | 同事项可读;他人不可读 | 已演示部分 | | AR-08 | P0 | Human | 待确认时不执行工具;确认需当前版本/哈希 | 修改后旧确认 409 | 已演示部分 | | AR-09 | P0 | Events | 事件有序、持久、按游标补发 | SSE 断线恢复无遗漏 | 已演示部分 | | AR-10 | P0 | Cancel | 取消阻止后续节点;终态拒绝再确认 | 取消后不再出现新工具调用 | 已演示部分 | | AR-11 | P0 | Failure | 超时与失败有错误码和建议 | LLM/检索异常注入后状态明确 | 待开发 | | AR-12 | P1 | Dispatcher | 租约、代数、checkpoint、多 Worker 接管 | 宕机后接管,旧 Worker 不覆写 | 待开发 | | AR-13 | P1 | Tool Effect | 每个副作用有稳定键与回执;超时先查询 | 重试不重复保存 | 待开发 | | AR-14 | P1 | Outbox | 状态和事件同事务;通知可重试 | 模拟队列故障后无丢失 | 待开发 | | AR-15 | P1 | Admin | 画布草稿校验、发布不可变版本、运行审计 | 仅管理员发布,草稿不执行 | 界面原型 | | AR-16 | P1 | Observability | trace/run/step 可追踪、正文密钥脱敏 | 按 run_id 查链路,日志无密钥 | 待开发 | | AR-17 | P2 | Portability | 麒麟 V10 SP3/海光原生部署 | 目标机端到端与重启恢复留证 | 待实测 | | AR-18 | P2 | Scalability | 工作组权限、队列隔离、配额限流 | 越权与负载测试达标 | 待开发 |