work-by-roles Vibe 项目

work-by-roles：给 LLM 多角色协作装上契约、门禁与审计的 Python 库

项目简介

work-by-roles 是一个 MIT 开源的 Python 库，专门用来解决「把多个 LLM Agent 拼起来上生产」时反复撞到的三堵墙：输出不可控（职责漂移、格式乱飘、一本正经地编造）、结论不可查（模型说得自信但拿不出证据、说不清谁复核过）、变更不敢做（改一行提示词像拆盲盒，不知道会不会弄坏别的能力）。它的解法是给每个 LLM 角色建立一份可版本化的「角色契约」——职责 SOP、禁区、输出 Schema、证据规范、工具白名单、Token 配额全部事先声明——再用「协调者 → 专家并行 → 复核人」的会审范式组织协作，运行时强制执行边界，并为每次变更提供回归门禁。它不替代编排框架，而是补上编排与评测都覆盖不到的那一层治理。

核心功能

1. 角色契约 RoleContract：声明式 YAML 描述角色的职责步骤、禁区行为、输出 Schema、证据引用要求、工具白名单、记忆权限与 Token 配额，自动生成内容哈希定版。
2. 会审范式：Coordinator 拆解问题并分派，多位专家并行作答，Verifier 独立复核裁决；分歧保留不仲裁，结论与分歧一并交付使用方。
3. Harness 质量门禁：黄金用例加基线快照加一键回归，契约或模型变更后，能力退化会被自动检出。
4. 全链路审计：编译、调用、校验、裁决均产生 TraceID 关联的审计事件，可导出标准审计包用于合规复核。
5. 官方专家团模板：内置 arch_review_team（架构评审）、security_audit_team（安全审计）、content_review_team（内容合规）、content_creation_team（内容创作）等成套契约模板。
6. 画布与 REST API：浏览器里可视化搭建团队、编辑契约并实时校验、发起异步评审、分歧节点高亮、导出审计包。
7. 存量项目三行接入：用 WBRGuard 包装已编译的 LangGraph 图，不改变 State 语义，Checkpointer 与人工介入天然兼容。

技术实现

库以 Python 实现，核心围绕 RoleContract 契约模型、ReviewSession 会审编排与 WBRGuard 守卫三层展开。契约是 Pydantic 校验的声明式对象，每次保存产生新版本并附带内容哈希，历史版本可查可 Diff。模型调用统一走 OpenAI 兼容适配器，只要提供 /chat/completions 端点即可接入 OpenAI、DeepSeek、Kimi、Qwen、GLM、Ollama、vLLM 等任意服务，并支持按角色分配不同模型——协调者与复核人用强模型，专家用高性价比模型。输出经过 Schema 校验与证据引用强约束后才允许进入裁决环节，从而在运行时就把格式漂移和编造拦下来。审计层为每条事件生成 TraceID 串起完整调用序列，保证结论可追溯到证据、契约版本与操作步骤。

快速上手

1. 安装：README 给出 pip install "work-by-roles[server]"（含 SDK、CLI、API 服务与画布），最小安装可用 pip install work-by-roles；作者在社区说明该包当时尚未发布到 PyPI，也可克隆仓库后执行 pip install -e ".[server]"。
2. 查看模板：wbr list-teams 列出官方专家团模板。
3. 跑一次演示会审：wbr run-team arch_review_team "评审：订单系统微服务拆分方案"，输出完整会审 JSON，包含状态、最终结论、参与专家、分歧数与审计事件数；此步使用内置演示 Invoker，不调用任何外部模型。
4. 接入真实模型：设置 WBR_LLM_API_KEY、WBR_LLM_MODEL，其他厂商补 WBR_LLM_BASE_URL，然后给命令加上 --live。
5. 启动画布：uvicorn --factory wbr.app.api.main:create_app --port 8000，浏览器打开 http://127.0.0.1:8000/canvas 即可导入模板、编辑契约、发起评审。
6. 存量 LangGraph 接入：guard = WBRGuard(output_keys={"answer": contract}, audit=trail) 后 graph = guard.wrap(your_compiled_graph)，再正常 graph.invoke(...)。

适用人群

正在搭建多 Agent 生产流水线的 AI 工程师；需要严格管控模型输出格式与职责边界的技术团队；做架构评审、安全审计、内容合规发布的团队；需要在私有化环境保留完整审计与证据链的合规导向组织。

项目地址：https://github.com/puppyfront-web/work-by-roles