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

2026-10-11 更新:Knowledge 已接真实授权检索,Runtime 27 项回归通过;新记录见 ../KnowledgeService/validation.json。旧发布快照保留,不自动增加个人来文库。

Agent Runtime · 可配置工作流执行模块

本目录实现 Agent Runtime 系统设计 的 PC 单进程版本。运行链路为 AdminWeb / EmployeeWeb → API Gateway → Workspace 归属与流程绑定 → Agent Runtime。工作流、发布快照、任务、步骤、事件和幂等记录真实落库;Knowledge 已接持久化 BM25;Identity、Context、LLM、Tool、Notification 继续使用演示桩。

启动与演示

在 base1 执行 ./run.ps1 -Port 8768。依赖使用相邻 APIGateway/requirements.txt,Python 3.12。员工入口 /,管理入口 /admin,接口文档 /docs。管理员 admin / admin123;员工 lin / demo123、zhou / demo123。设置 WORKOS_ADMIN_PASSWORD 可覆盖管理员密码。身份仍为本机演示账号,服务端每个管理接口检查 admin 角色。

  1. 管理员登录 → Agent 编排 → 原子操作管理:新增、编辑、删除操作;可选开始、上下文、知识检索、生成文稿、复核、人工确认、工具、通知、文本处理、结束 10 类。
  2. 在画布中点击或拖入操作;移动节点,点击输出圆点再点击输入圆点连线;右侧编辑参数、提示词与知识库。支持删除连线/节点、复制节点、撤销重做、平移缩放、自动布局、JSON 导入导出。
  3. 保存草稿 → 校验 → 发布。校验拒绝环、孤立节点、无效操作/知识库,以及绕过人工确认的工具路径。草稿可暂时不完整,发布版本必须有效。
  4. Workspace 列表 → 绑定工作流与知识库:指定发布版本和允许检索的库。员工启动数字员工时由 Workspace 提供绑定,Runtime 复查知识库范围。绑定修改只影响后续 Run。
  5. 点击试运行,在管理员自己的 Workspace 中输入办文要求。查看执行步骤和事件;修改草稿、保存为新版本、确认当前版本后,工具与通知桩执行。工具调用前再次检查确认的版本和 hash。
  6. 工作流发布后修改原子操作不会改变旧版本。运行使用发布快照、Skill 内容快照。刷新后重新登录,画布和运行记录仍在;重启后的待确认任务可从“版本与运行”继续。

目录与职责

文件 职责
models.py 6 张 Runtime 表、领域错误、管理员检查
registry.py 原子操作 CRUD、工作流草稿、校验/发布、不可变快照、管理审计
graph.py 类型允许表、配置白名单、DAG 编译、连通性与审批路径检查
service.py 开始/取消/确认、执行器、checkpoint、事件序列、重启恢复
openapi.json 本版完整网关运行契约,包含管理接口;由实际服务导出
examples.http 登录、操作、绑定、运行请求示例
tests/test_runtime.py 配置执行、隔离、快照、幂等、重启等 27 项验收
tests/browser_admin.py 管理端 Edge 端到端验收
validation.json 本次验收记录与边界

管理 HTTP 路由在 ../APIGateway/app/admin_api.py;工作流绑定在 ../WorkspaceService/workspace_service/service.py;画布在 ../AdminWeb。PC 同进程 Port 调用,共用 SQLAlchemy 引擎,表分别以 ws_ / ar_ 命名,未拆为远程微服务。未来更换 HTTP Port 时应保留 DTO 与权限检查,新增处理器需注册允许表,不能仅上传任意 Python/JS 代码执行。

数据与执行约定

  • ws_runtime_binding:事项绑定的 workflow_id、发布版本、base_ids、乐观锁 revision;属于 Workspace。
  • ar_definition:tenant + kind + id 唯一,保存操作和工作流当前草稿。
  • ar_published:tenant + workflow + published_version 唯一,冻结图、解析后操作参数、hash。
  • ar_run:所属用户、事项、状态、游标、步骤、输入输出与快照;active_scope 唯一约束保证同事项最多一个活跃任务。
  • ar_event:run + sequence 主键,持久化且单调递增;员工以 Bearer fetch 接收 SSE,管理端按游标分页读取 JSON 事件。
  • ar_command:用户/作用域/幂等键 + 请求指纹;同键同内容返回原结果,不同内容 409。
  • ar_audit:管理员修改和发布记录。

状态为 queued → running → awaiting_confirmation → queued → running → succeeded;运行中可 failed/cancelled。每个节点完成后提交输出和 checkpoint;单进程同时最多 2 个任务,每个任务按拓扑顺序逐节点执行。分叉的各分支都执行并在后继等待前置完成,不支持条件分支、循环或并行节点。本版一个流程最多一个 LLM 文稿节点和一个人工确认节点。

模板处理仅替换 {{request}}、{{text}},不会 eval。LLM 输入使用直接父节点第一个文本输出(没有则原始请求);引用收集已完成知识节点输出。当前演示只支持单文稿数据链,不具备任意变量映射。LLM 桩用固定模板模拟,提示词/Skill 会传入,但不是模型效果验证。

正常节点重启后按 checkpoint 续跑;待确认任务保留;若进程退出时正执行 tool/notification,恢复时标记 SIDE_EFFECT_UNCERTAIN,不盲目重复外部副作用。effect_key 已生成并记录,但外部网关尚未实现端到端去重,不能承诺 exactly-once。工具和通知桩回执目录仍在内存,其节点输出/事件中的回执快照落库。个人 Skill 定义目录仍是桩;已开始 Run 的 Skill 内容已冻结,不依赖重启后的个人目录。

管理 API 列表

以下路径均以 /api/v1 开头,除登录外必须 Bearer + admin 角色;未登录 401、普通员工 403、跨租户/事项越权 404。普通员工的 run API 仍只访问本人事项。

方法 / 路径 功能与关键请求 返回
POST /auth/login username / password access_token
GET /admin/operations 操作列表 items
POST /admin/operations name, kind, config 201,操作 v1
PUT /admin/operations/{id} 完整配置 + expected_version 新 revision;旧版本 409
DELETE /admin/operations/{id}?expected_version=1 删除未被草稿引用的操作 deleted;引用中 409
GET /admin/workflows 工作流列表 草稿版本和已发布版本
POST /admin/workflows name, graph.nodes/edges, base_ids 201,未发布草稿
GET /admin/workflows/{id} 获取可编辑草稿 图与参数
PUT /admin/workflows/{id} 全量图 + expected_version 保存草稿
POST /admin/workflows/{id}/validate 校验当前草稿 valid, issues, order
POST /admin/workflows/{id}/publish expected_version 201,发布版本
GET /admin/workspaces 本租户事项列表 owner_user_id
GET /admin/workspaces/{id}/runtime 查看绑定 工作流/版本/库/revision
PUT /admin/workspaces/{id}/runtime workflow_id, workflow_version, base_ids, expected_version 验证发布版/知识库后持久化
POST /admin/workflows/{id}/runs workspace_id, content + Idempotency-Key 202;仅管理员自己的事项;运行最新发布版
GET /admin/runs 本租户最近 100 个 Run 状态与步骤
GET /admin/runs/{id} 运行详情 当前状态/步骤/错误
GET /admin/runs/{id}/events?after_sequence=0 最多 100 条事件 items;以最后 sequence 续读
GET /admin/audit 最近 100 条变更 操作/操作者/资源/时间

试运行会将管理员测试事项绑定到当前流程最新发布版;相同幂等键重复请求不会再次修改绑定。管理员可查看租户运行状态,但试运行、草稿修改、审批仍须在自己的事项中进行。无工作流删除接口;原子操作删除不破坏已发布快照。

普通员工接口:POST /workspaces/{id}/runs(employee_id, input_message_id, skill_ids);GET /runs/{id};GET /runs/{id}/events(SSE,可 Last-Event-ID);POST /runs/{id}/cancel;POST /runs/{id}/approval(artifact_id, expected_version, content_hash);PATCH /artifacts/{id} 保存草稿。写入运行命令要求 Idempotency-Key 至少 8 字符。模式:run.mode=persistent,run.provider_mode=fixture;直接对话仍为 fixture。

数据库升级与国产化边界

默认 SQLite 和附件放在 D:\codex\outputs\workos-workspace;测试使用独立缓存库。通过 WORKOS_WORKSPACE_DATA_DIR / DB_URL / FILE_ROOT 修改。SQL 迁移统一放在 WorkspaceService/migrations,0002 包含绑定和 Runtime 表;空库先 python -m alembic -c WorkspaceService/alembic.ini upgrade head,正式迁移时设置 WORKOS_WORKSPACE_AUTO_SCHEMA=0。已有自动建表库不可直接重复初始迁移,应备份后核对 schema,再选择导入新库或人工 stamp。

技术栈:Python 3.12、FastAPI/Pydantic、SQLAlchemy 2、Alembic、asyncio;前端原生 HTML/CSS/JS/SVG,无 Node 构建依赖。版本锁定见 APIGateway/requirements.txt。未使用 Windows 专有进程接口,应用层可迁移到 Linux;麒麟/海光需设置 Linux 可写数据路径,验证 Python/驱动 wheel、OpenSSL、SQLite/PostgreSQL和浏览器兼容性。本轮仅验证 Windows PC + SQLite,未验证腾讯云、麒麟、海光或 PostgreSQL 实机。

仅支持 一个 Uvicorn worker / 一个服务进程,不要使用 --workers > 1 或多副本。下一阶段需要分布式租约、独立队列、异步外部调用超时重试、服务身份、生产授权管理、生产认证和外部幂等回执。当前本地 JWT + admin 角色不是生产 IAM,工作组授权页仍是原型。

可执行验收清单

编号 需求 本版完成性检验 状态
AR-PC-01 管理员登录与隔离 匿名401,员工403;员工不能进入管理界面 已验证
AR-PC-02 原子操作增删改 新增/编辑生效,旧 revision409,引用中禁止删 已验证
AR-PC-03 可编辑完整画布 加节点/连线/参数/删除,保存后刷新一致 已验证
AR-PC-04 发布有效 DAG 环/孤立/审批绕过禁止发布 已验证
AR-PC-05 发布快照不可变 编辑操作后旧发布版仍使用原模板 已验证
AR-PC-06 Workspace 流程配置 管理员绑定后,员工 Run 使用指定流程和版本 已验证
AR-PC-07 关联知识库实际生效 指定 kb-rules,产物引用仅来自此库;不覆盖所需库拒绝 真实检索范围已验证
AR-PC-08 执行与进度 自定义文本节点实际改变写作输入;9/10节点有持久事件 已验证
AR-PC-09 人工确认与版本一致 未确认无工具回执;旧草稿hash拒绝;新版本审批后保存一次 已验证
AR-PC-10 幂等与归属 相同命令只启动一次,冲突409;他人运行404 已验证
AR-PC-11 重启与恢复 等待审批、发布配置、命令记录保留;正常节点继续 已验证
AR-PC-12 外部副作用不确定恢复 故障注入到工具调用中,恢复失败且不重放 已验证
AR-PC-13 审计 管理端变更、发布可查询操作者与资源 已验证
AR-NEXT-01 真模型/检索/工具/企业微信 接真实 Port 并验证超时、权限和幂等 未接入
AR-NEXT-02 分布式/条件/变量映射 多worker租约、条件图、变量选择器 未实现

运行测试:python AgentRuntime/tests/test_runtime.py;服务启动后 python AgentRuntime/tests/browser_admin.py(默认 8777,可 WORKOS_GATEWAY_URL 覆盖;需 APIGateway/requirements-browser.txt 与已安装 Edge)。截图输出到 D:\codex\outputs\workos-agent-runtime。

画布交互参考 Coze 工作流官方说明,使用本项目原生 SVG 实现,没有引入 Coze 服务或代码依赖。