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 系统设计](../docs/12_Agent_Runtime/README.md) 的 **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 工作流官方说明](https://docs.coze.cn/guides_workflow),使用本项目原生 SVG 实现,没有引入 Coze 服务或代码依赖。