dellweb3's picture
Work OS validated demo local-v0.8
99caad5 verified
|
Raw History Blame Contribute Delete
17.9 kB

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. 办文工作流实例

  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 工作组权限、队列隔离、配额限流 越权与负载测试达标 待开发