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 到工程團隊的構建能力。如果你需要精細控制工作流、角色分工以及持久化記憶，該插件提供了落地的解決方案。