Spaces:
Sleeping
Download docs/12_Agent_Runtime/README.md from dellweb3/workos-office: direct link, hf CLI and curl.
- Browser
- Download file 17.9 kB
-
https://huggingface.co/spaces/dellweb3/workos-office/resolve/main/docs/12_Agent_Runtime/README.md
- Command line
-
hf download hf://spaces/dellweb3/workos-office/docs/12_Agent_Runtime/README.md
-
curl -L -o README.md https://huggingface.co/spaces/dellweb3/workos-office/resolve/main/docs/12_Agent_Runtime/README.md
Work OS MVP · Agent Runtime 系统架构与功能设计 v1.0
日期:2026-10-10。10 月 18 日前验收 PC,腾讯云随后验收。现已实现 PC 单进程持久化 Runtime 与管理员画布;本文为完整目标设计,已实现范围和限制以 实现与验收说明 为准。分布式调度和真实下游尚未接入。关联:总体架构、公共工作流契约、API Gateway、Workspace Service。员工端留空数字员工时走直接模型对话,不创建 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 文档描述 SKIP LOCKED 的锁语义,适合队列领取,不适合普通权限查询。若引入 RabbitMQ,须分别处理消费者确认和发布确认,它们不替代业务幂等。SSE 使用 FastAPI StreamingResponse 与持久游标。
目标为银河麒麟高级服务器操作系统 V10 SP3/海光。麒麟官方产品说明列出海光支持,但这不等于本项目 Python wheel、psycopg、OpenSSL、容器镜像已适配。运行时避免 Windows DLL、COM 和 x86 专属指令;依赖锁版本和哈希。迁移验收要在目标机核对架构与 Python 原生依赖、数据库迁移、双 Worker 抢占、宕机恢复、SSE 和 Tool Port。公网 Qwen 仍只由 LLM Gateway 接入。
3. 流程定义与低代码扩展
以现有线性公文流程为起点。正式定义为受约束 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 <token>
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":"<sha256>"}]}
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 <token>
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. 办文工作流实例
- 员工在 Workspace 输入办文要求并选择公文写作数字员工。Gateway 验证身份和幂等,Workspace 保存消息。
- Gateway 调 Runtime start。Runtime 重新验证消息和事项归属,取已发布 Workflow/Agent 与 Skill 快照,创建 Run 和初始事件,返回 202。Gateway 不直接执行节点。
- Worker 检查附件就绪,从 Context 取摘要,经 LLM Gateway 理解需求;Knowledge 检索格式、制度与历史文档,返回引用 ID。每步事件持久化并经 Gateway SSE 推送。
- 起草节点送输入、Skill 快照与引用给 LLM Gateway;草稿写入 Workspace。复核节点检查格式、引用和缺项,未知日期标记待确认。
- Run 转 awaiting_confirmation。员工编辑后 Workspace 产生新版本/哈希。Runtime 只接受当前版本确认。
- 确认后通过 Tool Gateway 保存或导出,带批准凭据和 effect_key;记录回执。随后完成事件进入 outbox,Notification Service 可投企业微信应用消息;投递失败单列并重试。
- 客户端断线按 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 | 工作组权限、队列隔离、配额限流 | 越权与负载测试达标 | 待开发 |