角色编排箱 EricMoin/rolebox

rolebox

把单个编码智能体变成一支配置好的工程团队。
专家角色用 YAML 定义，各自拥有提示词、模型、技能和权限——按显式图运行，记忆跨会话保留。

一个插件，同时支持 opencode、pi、dsh 和 Codex。

角色选择器，从输入框打开：Filter roles 搜索已加载的 18 个角色，每行一个显示名和一句简介，顶部标出当前选择 Base agent。

它是什么 ·实际效果 ·安装 ·角色 ·你能得到什么 ·引擎 ·命令行 ·文档

它是什么

通用编码智能体只有一个智能体、一条提示词。rolebox 把它变成你的配置团队：专家角色用 YAML 定义，各自拥有提示词、模型、技能和权限，一起处理同一个任务。学到的东西跨会话保留——决策、约定和经验存进记忆，下次会话启动时再带回来。
在 DSH 上，角色之间可以通过持久对等团队协作：邀请互补的专家、交换事件、认领任务，并跨轮次继续工作。其他主机上的团队执行暂缓支持。结构化工作流使用声明式图：graph_declare 指定每个节点的智能体、任务简报和允许的结果；主机派发入口节点，工作节点用 graph_submit_outcome 提交结果。图节点只通过被接受的结果推进，循环次数有上限，状态可检查。

速览

- 角色 — 公开的 oh-my-role 注册表上有 18 个专家，你也可以用一个 YAML 文件写自己的角色。
- 运行时 — 图 v3 结果协议：声明式节点与边、被接受的结果、有界修复循环。
- 记忆 — SQLite + FTS5，会话开始时自动注入，可从命令行搜索。
- 工具 — 32 个 lsp_ 语言服务器工具，hashline_ 编辑锚定到内容哈希，还有技能、引用、自定义函数和钩子。
- 桌面 — 12 个工具的 computer_ 家族：computer_screenshot、computer_windows、computer_displays、computer_focus、computer_click、computer_move、computer_scroll、computer_drag、computer_type、computer_key、computer_status、computer_permissions。
- 浏览器 — 23 个工具的 browse_ 家族，用于语义化网页自动化：browse_status、browse_open、browse_snapshot、browse_read、browse_click、browse_drag、browse_type、browse_press、browse_select、browse_hover、browse_scroll、browse_wait、browse_eval、browse_screenshot、browse_upload、browse_downloads、browse_dialog、browse_tabs、browse_history、browse_console、browse_network、browse_cookies、browse_close。由 browseUse 控制开关；执行动作需要可选的 Playwright 对等依赖（npm install playwright，然后 npx playwright install chromium）。
- 可见性 — dsh Rolebox 监控面板、rolebox monitor TUI，以及按通道过滤的日志。

实际效果

本 README 中的每张截图都来自演示工作区上的实时 dsh 会话。每段说明只描述该截图展示的内容。

1 · 所有已加载角色，一页看全

设置 → Rolebox：已加载的 18 个角色，每个都带有 slug、描述和声明的工具策略。

每张卡片都带显示名、右侧的 slug（截图里是 ai-designer、apk-reverse-engineer、comment-writer）、一段描述，然后是三行标签/值——Model、Mode、Max steps——以及页脚 Tool policy:。这张截图里，每张可见卡片的 Model 都读作 default，Mode 读作 primary，Max steps 读作 not set，Tool policy: none declared；没有一张卡片写明来源或原始路径。页头带 18 roles 徽标、Refresh、Reload roles 和 Open monitor 按钮，还有一行右对齐的 Loaded 18 roles · ，记录加载发生的时间。

2 · 工作以图的形式声明，而不是逐个节点提示

The TypeScript Engineer loads its own skill, reads the protocol reference, and declares the work with graph_declare.

角色并不直接动手做事。它先检查仓库，在编辑前记录基线——示例项目的测试命令 → 4 pass / 0 fail，tsc --noEmit → exit 0——然后点出一个真正的设计点：Task 完全没有完成状态，所以 removeCompleted() 需要补一个。它采用最小、向后兼容的读法——在 Task 上加可选的 completed?: boolean，再加 removeCompleted(): number 返回移除的数量——并把这个决定明确交给 worker。

接着它声明 graph_declare · taskstore-remove-completed，并让出这一轮，好让引擎调度它。计划正好点名两个节点和一轮有界修复：

- change（change-applier）——在 src/store.ts 里实现 removeCompleted(): number，在 src/task.ts 里给 Task 加上可选的 completed?: boolean 字段，在 tests/task.test.ts 里加一个聚焦测试，并运行示例项目的测试命令和 tsc --noEmit。
- review（verification，独立）——读实际文件，对同一基线重跑两项检查。

这一轮以声明被启动收尾（start.kind: started，阶段 executing，节点 change 已派发）。截图没有说明执行预算。

3 · 独立验证，然后对账

Accepted results come back; the parent reconciles them, re-runs the checks itself, and states what was verified and what remains uncertain.

两个节点都在各自的会话中运行，负责验证的节点并不是写代码的那个节点。收尾综合报告把测试覆盖情况记为两项行为测试——tests/task.test.ts:35-61，第 4 行导入 TaskStore：一项是混合存储，只删除已完成的那条记录并返回 1，同时未完成的记录以及 get/count/all 保持一致；另一项是空操作路径，返回 0，且存储与调用前快照深度相等。

Checks 表把每项检查与基线对照：示例项目的测试命令从 4 pass / 0 fail 变为 6 pass / 0 fail, 17 expect() calls, exit 0，tsc --noEmit 保持 exit 0（TypeScript 6.0.3）。两者都是项目自带的脚本；评审者另外跑了一次独立临时探测，覆盖空存储、全部完成和混合存储，以及 add / get / remove / count，父节点在评审者结束后重跑了两条必需命令，输出相同。

Risk and gaps 列表有意保留三项未决：一项待确认的判断（completed 是否应设为必填，还是返回 Task[]）；工作区里没有 git 仓库，因此范围是根据文件清单加上变更前基线确认的，而不是机器 diff；证据属于记录的示例工具链，不能证明当前运行时兼容性；当前验证命令见 Node runtime。

4 · 一份简报进，一个结果出

一份简报进，一个结果出：worker 完成限定范围内的编辑，跑完两项检查，用 done 结果结算节点 change。

录像显示一个 dsh worker 完成分配的简报，并用 graph_submit_outcome 结算自己的节点。当前 worker 使用宿主原生命令和文件工具。worker 默认继承父节点授权的任务工具，原生 schema 直接暴露。节点工具列表不限制它们；发现和代码呈现仍为可选；见 Worker tools。worker 不能读取或操纵图状态。这里 worker 的完整记录是：cat 宿主交接文件、限定范围内的编辑、对编辑后文件执行 cat -n 验证、示例项目的测试命令和 tsc --noEmit。它注明这不是修复轮（没有收到 revise 输入），完成三处限定范围内的编辑，报告 6 pass / 0 fail, tsc exit 0，最后以 Outcome done accepted (verdict committed, no refusals) — node change is settled 收尾。底部横幅是一次性契约：记录不接受后续追问。

5 · 引擎运行时观察

监控面板：实时会话及其当前角色，引擎图及各节点的智能体与耗时，修复计数器与本次运行的预算展开区。

dsh 右侧边栏里的 Rolebox 面板是实时引擎视图。截图里它显示 Sessions 4，其中只有一个活跃角色——正在查看的会话运行 typescript-engineer，另外三个运行 base——以及 Engine graphs 1：taskstore-remove-completed，标记为 complete 和 Done，带一个展开区，可查看尝试、结果、审批和预算，还有一条进度条，显示本次运行的各项计数，以及 repair 0/2。Nodes 2 下面，每个节点都标出智能体、工作会话和耗时：change 运行 typescript-engineer--change-applier，耗时 28s；review 运行 typescript-engineer--verification，耗时 38s。Metrics 0 显示 No samples recorded，并说明只有在设置 ROLEBOX_METRICS 时，面板才会采集核心调度计数器之外的数据。这个面板里没有循环区。

6 · 从终端看同一次运行

同一次运行，从终端看：rolebox monitor 分为 System Pulse、Graphs 和 Tasks 三个面板。

rolebox monitor 把项目持久化的调度状态渲染成一组带边框的面板，顶部标题写明命令名和它读取的工作区。截图时 System Pulse 显示 IDLE；Graphs 列出 taskstore-remove-completed completed: 2，下面一行是 sess 2 tok 0 cost $0.00；Tasks 显示 no dispatch activity。

7 · 日志：按通道和会话过滤

插件启动、角色加载和提示词组装，每个事件一条记录，可按通道或会话过滤。

日志面板轮询工作区的 .rolebox/logs 目录（在 capture records 125、skipped 0 中），每条记录渲染一行：时间戳、级别、标题、通道和详情。显示的记录包括 dsh-plugin 启动行和 computer-use 门禁判定结果、dsh-agent-registrar 报告未接入 onSpawn 委托、role-loader 警告某个角色声明了 graph.orchestration: graph_v2 且该键已被识别但尚未接入图解析，还有一串 prompt-builder 的 Prompt assembled 行及其字符数。显示的级别是 INFO 和 WARN，控件有 All channels 下拉框、This session 过滤器、Pause 和 Refresh。日志面板和 rolebox logs 读取同一批日志文件，所以 UI 里跑过什么，都能从 shell 里排查。

循环模式

循环模式把同一任务跑 N 轮，每轮派发到各自全新的会话。|loop:3| 让每轮继承上一轮的摘要（inherit，默认值）；|loop:3,fresh| 让每轮从干净状态开始。解析器（src/loop/params.ts）还接受 on/true 表示继承、no-inherit/off/false 表示全新，并把 N 硬性限制在 50。适合做精修轮次、批量修复和自我纠正的工作流。

同会话里还能用到：持久记忆（rolebox memory）、技能与引用、LINE#HASH 锚定的 hashline_ 编辑、MCP 服务器、自定义钩子、回合结束时的 copilot 函数，以及 rolebox 自带的 computer-use 家族。

安装

Rolebox 的命令行和开发工具需要 Node.js 26.4+ 和 npm。从源码检出时，运行 npm ci、npm run build，再用 npm test -- tests/<module>/ 跑模块级测试。见 Node 运行时与开发。TUI 还需要 Node 的 --experimental-ffi 标志；测试命令会自动带上。

rolebox 可运行在四种 harness 上。当前工作目录下的 rolebox/ 目录优先于全局角色目录；注册表里的角色用 rolebox install <name> 安装，用 rolebox sync <opencode|pi|dsh|codex> 部署。每种 harness 都有最低版本要求——Harness 版本列出了具体版本和原因。

| Harness | 配置目录 | 角色目录 | 全局技能 | 环境变量覆盖 |
| opencode | ~/.config/opencode | ~/.config/opencode/rolebox | ~/.config/opencode/skills | XDG_CONFIG_HOME |
| pi | ~/.pi/agent | ~/.pi/agent/rolebox | ~/.pi/agent/skills | PI_CODING_AGENT_DIR |
| dsh | ~/.dsh | ~/.dsh/rolebox | ~/.dsh/skills | DSH_HOME |
| Codex | ~/.codex | ~/.codex/rolebox | ~/.codex/skills | CODEX_HOME |

opencode

cd ~/.config/opencode && npm install roleboxbash
mkdir -p ~/.config/opencode/rolebox && cd ~/.config/opencode/rolebox && rolebox init my-agent -y
jsonc
// ~/.config/opencode/opencode.jsonc
{ "plugin": ["rolebox"] }

opencode 1.x 加载包根入口（{ id, server }）；opencode v2 则通过插件入口 rolebox/server（{ id, setup }，src/entries/opencode2.ts）解析同一个已安装的包，因此不需要第二个包，也不需要额外安装步骤。v2 注册了什么、哪些地方会降级，都列在 compatibility.md 里。

pi
bash
pi install npm:rolebox # project-local instead: pi install -l npm:rolebox
mkdir -p ~/.pi/agent/rolebox && cd ~/.pi/agent/rolebox && rolebox init my-agent -y

from a checkout instead: add "extensions": ["/path/to/rolebox/dist/entries/pi.js"] to ~/.pi/agent/settings.json

dsh
bash
dsh plugin --profile <name> add rolebox # installs the bundle into that profile
dsh plugin --profile web add rolebox # installs the bundle into the web profile
mkdir -p ~/.dsh/rolebox && cd ~/.dsh/rolebox && rolebox init my-agent -y # $DSH_HOME/rolebox if set

重启 harness。如果 dsh 安装的不是 bundle，则需要在配置档的 cordis.patch.yml 里加一行 - insert:，指向配置档相对路径 ./node_modules/rolebox/dist/entries/dsh.js——见 examples/dsh/cordis.patch.yml。配置档补丁的语义、web 角色切换面板，以及 /rolebox REST 接口，都记录在 docs/dsh-plugin-contract.md。

Codex
bash
npm install -g rolebox # or run from a checkout built with npm run build
rolebox sync codex

rolebox sync codex 会把本地插件 bundle 写到 $CODEX_HOME/rolebox-marketplace（默认 ~/.codex/rolebox-marketplace），在 Codex 的 config.toml 里注册它，并把已安装的角色部署到 $CODEX_HOME/rolebox。bundle 会启动 rolebox MCP 服务器（rolebox mcp），由它通过 stdio 暴露 rolebox 的标准工具。之后重启 Codex。详情见 docs/codex.md。

已废弃的入口路径

原先的 dist/index.js、dist/pi-extension.js 和 dist/dsh-plugin.js 产物仍能解析，作为生成的再导出别名，但已废弃——新的 checkout 和配置档行应改用标准的 dist/entries/.js 路径。

角色

oh-my-role 注册表上发布了十八个角色。rolebox install <name> 拉取其中一个，rolebox sync <harness> 部署它，rolebox init 则为你自己的角色搭好骨架。

| 角色 | 做什么 |
| emperor | 顶层编排者——先对请求做分诊，再派发 planner/executor 子树，最后用闭环校验综合结果。自己从不写代码。 |
| software-architecture | 架构编排器 —— 负责设计、评审、ADR、迁移方案，并通过专家子代理落地影响架构的实现。 |
| ai-designer | 设计总监 —— 分层路由、产物优先输出、按严重程度分层的质量门禁。 |
| typescript-engineer | 图原生 TypeScript 工程师 —— 类型建模、运行时调试、API 设计、模块打包、工作区构建。 |
| react-frontend | React/Next.js 开发者 —— 组件架构、hooks、状态、Tailwind、数据获取、无障碍、TDD。 |
| dart-flutter | Dart 与 Flutter 工程负责人 —— 证据优先的调研、工程简报、基于风险的专家门禁。 |
| jetpack-compose | Jetpack Compose 与 Android 负责人 —— 不变量驱动设计、保持封装的测试、AOSP/AndroidX 源码追溯。 |
| rust-engineer | Rust 负责人 —— 按复杂度分层路由，配安全、异步、API、性能与平台门禁。 |
| tauri | Tauri 桌面开发者 —— IPC、插件、权限、系统托盘、窗口定制、测试。 |
| git-master | Git 操作专家 —— 工作区、提交、分支、合并/变基、暂存、标签、历史、撤销、工作树。默认安全。 |
| apk-reverse-engineer | Android 逆向工程 —— 反编译 APK/XAPK/AAB、提取 API、审计安全、运行 Frida 动态分析。以合法用途为前提。 |
| oss-finder | 开源调研 —— 查找、追溯源码、评估并推荐实现，附带证据。 |
| supersearch | 搜索专家 —— 交叉比对本地文件、代码、git 历史、Web、GitHub 与官方文档。 |
| teacher | 按需编程导师 —— 概念解答、惯用模式、代码点评、库内部原理。 |
| comment-writer | 注释专家 —— 编写、重写、评审注释；解释 WHY，而非 WHAT。 |
| role-creator | 元角色 —— 先访谈你，再搭建新角色，最后通过四层验证。 |
| rolebox-tester | rolebox 自身的功能测试员 —— 按需运行选定的测试模块，或跑完整套件。 |
| deepseek-whale-girl | 傲娇鲸鱼娘陪伴人格，同时仍是能力完整的编码助手。🐋 |

角色就是一个目录：role.yaml（名称、模型、模式、权限、子代理、技能）、它的提示词，以及它的资源。先从 create-a-role.md 和 role.yaml reference 看起。

你能得到什么

| | 默认单智能体 | 使用 rolebox |
| 谁来干活 | 所有任务共用一套提示词 | 各领域专家，各有自己的提示词、模型、技能与权限 |
| 记忆 | 会话从空白开始 | SQLite + FTS5 记忆，会话开始时自动注入 |
| 切换 | 改配置再重启 | 原地切换角色，对话记录不丢 |
| 并发 | 一次一个智能体 | 并行派发 worker，由引擎统一管理上限 |
| 自主性 | 自由聊天 | 声明式图，带可接受结果和有界修复循环 |
| 代码导航 | 文本搜索 | 32 个 lsp_ 工具——定义、引用、重命名、诊断、调用层级 |
| 编辑 | 会漂移的行号 | hashline_ 编辑，锚定到 LINE#HASH 内容哈希 |
| 可观测性 | 宿主记录什么就是什么 | 监控面板、rolebox monitor TUI、按通道过滤的日志 |
| 桌面 | 无 | 12 工具 computer-use 家族：截图、窗口、显示器、焦点、点击、移动、滚动、拖拽、输入、按键、状态、权限 |
| 迭代 | 重启才能拾取变更 | 编辑 YAML，热重载资产 |

团队如何运行

针对互补的专长，DSH 上的角色团队提供持久成员关系、有序事件流、独占任务认领和自动同伴唤醒。成员使用独立的智能体会话，各自带角色配置；私有子角色留在所属角色内部。OpenCode、Pi 和 Codex 上的团队执行暂缓。

针对结构化工作流，graph_declare 写入版本 3 声明——每个节点的智能体、简报和它可报告的结果，以及路由已接受结果的边——并把持久化与宿主的初始启动决策分开报告。宿主派发入口节点；工作节点用 graph_submit_outcome 结算自己的节点，该操作提交节点状态并武装下一个节点。

graph_control 应用受信的生命周期命令（失败、超时、取消、重试、budget-stop，以及带决策的审批请求）；graph_status 读回记录的状态；graph_audit 盘点持久化存储。循环位于声明的循环组中，带遍历上限，所以修复可以重复，但绝不会永远重复。

架构与完整工具集：graph-outcome-protocol.md · 运维：graph-v3-operations.md · 内部实现：graph-engine-architecture.md。

命令行

| 命令 | 描述 |
| rolebox init <name> | 搭建新角色目录 |
| rolebox install [name] | 从注册表安装角色（省略时弹出选择器） |
| rolebox uninstall [name] | 移除已安装角色 |
| rolebox update [name] | 把已安装角色更新到注册表版本 |
| rolebox list | 显示已安装角色 |
| rolebox search <query> | 搜索已配置的注册表 |
| rolebox registry | 已配置的角色源：add、remove、list、default |
| rolebox status | 整体健康状况与 harness 集成 |
| rolebox info [name] | 详细查看一个已安装角色（省略时弹出选择器） |
| rolebox sync <target> | 把已安装角色部署到 opencode / pi / dsh / codex |
| rolebox config [name] | 为角色及其子代理配置模型（--target 选择 harness） |
| rolebox bench <subcommand> | 本地 dsh 角色基准测试：init、validate、doctor、run、watch、report、baseline、compare |
| rolebox monitor | 项目持久化调度状态的运行时仪表盘（TUI、--json、Prometheus 导出） |
| rolebox logs | 查询、跟踪、清理 rolebox 日志文件（logs files、logs prune） |
| rolebox memory | 管理 rolebox 记忆存储（list、show、search、delete、export、clean、stats） |
| rolebox checkpoint | 管理调度检查点（list、clean） |
| rolebox mcp | 在 stdio 上运行 rolebox MCP 服务器（Codex 集成） |

完整参数与示例见 cli.md。用 Benchmarks on dsh 搭建测试套件：响应断言与文件断言、可信的本地命令检查、code-fix 模板、独立试验、角色改动后对照已保存基线的反馈，以及带文件变更证据的离线 JSON/HTML 结果。

模型别名

注册表里的角色自带占位模型名，因为角色不该硬编码到某个服务商。在 role_config.yaml 里映射一次即可 —— ~/.config/opencode/role_config.yaml、~/.pi/agent/role_config.yaml、~/.dsh/role_config.yaml 或 ~/.codex/role_config.yaml（harness 配置目录）： yaml model_aliases: provider/tier-1-flagship: your-provider/your-strongest-model provider/tier-2-reasoning: your-provider/your-reasoning-model provider/tier-3-fast: your-provider/your-fast-model

无法识别的值会原样透传，并给出警告。完整解析链、错误处理与热重载见 model-aliases.md。

文档

概念

| 图结果协议 | 图 v3 操作 | 图引擎架构 |
| 记忆用法 | 会话工具 | Copilot（回合结束） |
| 函数 | 钩子 | 扩展 |

构建角色

| 创建角色 | role.yaml 参考 | 目录结构 |
| 技能 | 引用 | 子代理 |
| 注册表 | 模型别名 | Benchmarks on dsh |

Harness

| 兼容性矩阵 | dsh 插件契约 | dsh 服务商说明 |
| Codex | 计算机操作 | 限制 |

运维

| 命令行 | 调度配置 | 错误处理 |
| 日志 | 日志架构 | 安装/更新审计 |
| 命令行输出审计 | | |

从 0.x 或 1.x 升级？ rolebox 2.x（package.json 当前为 2.2.0）通过图结果协议执行工作：graph_declare 持久化一份版本 3 声明，节点只能通过 worker 用 graph_submit_outcome 提交的结果向前推进。已有的（旧版）声明必须按版本 3 语法重写，并作为新运行启动。已持久化的旧版状态体仍可读取，但永远不会推进，而且该协议没有增量构建节点或边的工具。参见 docs/graph-outcome-protocol.md。

贡献

欢迎贡献 —— 参见 CONTRIBUTING.md。测试布局、各模块切片和仓库约定见 AGENTS.md。

许可证

MIT — 参见 LICENSE 文件。