rolebox：将单一编码智能体配置为工程团队

前言¶

DeepSeek Harness (DSH) 支持插件化架构，但标准的智能体插件通常表现为单一提示词的 Agent。面对复杂工程任务，单一角色往往难以兼顾实施、审查与记忆。rolebox 插件通过角色定义与图协议，将单一的编码智能体转化为一个配置好的工程团队，每个角色拥有独立的提示词、模型、技能与权限。

这是什么¶

rolebox 是一个通用 Agent 插件，支持 DeepSeek Harness (DSH)、OpenCode、Pi 和 Codex。它基于 YAML 定义专业角色，并利用 Graph v3 协议实现声明式工作流。插件内置 18 个角色定义，支持持久化内存（SQLite + FTS5）以及多智能体编排。

核心功能¶

多角色定义：基于 YAML 定义自定义 AI 代理角色，每个角色可配置独立的提示词、模型、技能、权限和最大步数。
图 v3 协议：使用 graph_declare 声明工作流（节点与边），通过 graph_submit_outcome 提交结果。工作流是声明式的，非提示链。
持久化内存：使用 SQLite + FTS5 存储记忆，决策、约定和经验在会话重启后可检索。
工具生态：内置 32 个 LSP 工具、hashline 编辑工具以及 32 个桌面控制工具（如 computer_screenshot、computer_click 等）。
可视化监控：提供 Rolebox monitor pane 和 TUI 可视化界面，用于查看和过滤已加载的 18 个角色。

安装与启用¶

该插件通过 npm 安装。安装前请确保 DSH 版本满足要求。

确认 DSH 版本：dsh --version，需 >= 0.2.1-alpha.3。
安装 npm 包：npm install rolebox。
插件将自动加载内置的 18 个角色，可在 DSH 设置中查看和过滤。

典型用法¶

使用 graph_declare 声明工作流是核心操作。以下是典型步骤：

加载技能与阅读协议：Agent 加载所需技能，阅读 Graph v3 协议参考。
声明工作流：使用 graph_declare 命令定义节点。例如，定义一个 taskstore-remove-completed 任务，包含 change（实施修改）和 review（验证）两个节点，并声明循环次数。
运行基准检查：在声明前或声明中运行 bun test 和 tsc --noEmit 确立基准。
提交结果：通过 graph_submit_outcome 提交执行结果。只有被接受的结果才能推进工作流。
查看角色：在 DSH 设置中打开 Rolebox 面板，可查看当前选中的 18 个已加载角色。

适用场景与注意¶

适用场景：需要多角色协作（如实施者与审查者分离）、需要持久化上下文记忆、或需要严格定义工作流边界的复杂编码任务。
重要注意：
- 声明式执行：工作流通过 graph_declare 和 graph_submit_outcome 推进，Agent 无法仅通过自由文本报告来推进进度。
- 循环限制：循环是受限的且必须声明。
- 权限风险：插件以当前 DSH 进程权限运行。请检查源码与许可证（github/license/EricMoin/rolebox）后再安装使用。

结语¶

rolebox 通过 YAML 定义与 Graph v3 协议，为 DSH 提供了从单一 Agent 到工程团队的构建能力。如果你需要精细控制工作流、角色分工以及持久化记忆，该插件提供了落地的解决方案。