dmux-workflows

dmux 工作流程

使用 dmux（一個用於代理工具的 tmux 窗格管理器）來協調平行 AI 代理工作階段。

何時啟用

• 同時執行多個代理工作階段
• 協調跨 Claude Code、Codex 及其他工具的工作
• 需要分而治之平行處理的複雜任務
• 使用者說「平行執行」、「拆分工作」、「使用 dmux」或「多代理」

什麼是 dmux

dmux 是一個基於 tmux 的協調工具，用於管理 AI 代理窗格：

• 按 n 建立新窗格並輸入提示
• 按 m 將窗格輸出合併回主工作階段
• 支援：Claude Code、Codex、OpenCode、Cline、Gemini、Qwen

安裝： 在檢閱套件後，從其儲存庫安裝 dmux。請參閱 github.com/standardagents/dmux

快速開始

# 啟動 dmux 工作階段
dmux

# 建立代理窗格（在 dmux 中按 'n'，然後輸入提示）
# 窗格 1：「在 src/auth/ 中實作驗證中介層」
# 窗格 2：「為使用者服務撰寫測試」
# 窗格 3：「更新 API 文件」

# 每個窗格執行自己的代理工作階段
# 按 'm' 合併結果

工作流程模式

模式 1：研究 + 實作

將研究和實作拆分為平行軌道：

窗格 1（研究）：「研究 Node.js 中速率限制的最佳實務。
  檢查現有函式庫，比較方法，並將結果寫入
  /tmp/rate-limit-research.md」

窗格 2（實作）：「為我們的 Express API 實作速率限制中介層。
  先從基本的 token bucket 開始，等研究完成後再優化。」

# 窗格 1 完成後，將結果合併到窗格 2 的上下文中

模式 2：多檔案功能

將工作平行化到獨立檔案：

窗格 1：「為帳單功能建立資料庫綱要與遷移腳本」
窗格 2：「在 src/api/billing/ 中建立帳單 API 端點」
窗格 3：「建立帳單儀表板 UI 元件」

# 全部合併後，在主窗格中進行整合

模式 3：測試 + 修復迴圈

在一個窗格中執行測試，在另一個窗格中修復：

窗格 1（監視器）：「以監視模式執行測試套件。當測試失敗時，
  摘要失敗資訊。」

窗格 2（修復者）：「根據窗格 1 的錯誤輸出修復失敗的測試」

模式 4：跨工具協作

對不同任務使用不同的 AI 工具：

窗格 1（Claude Code）：「審查驗證模組的安全性」
窗格 2（Codex）：「重構工具函式以提升效能」
窗格 3（Claude Code）：「為結帳流程撰寫端對端測試」

模式 5：程式碼審查管線

平行審查觀點：

窗格 1：「審查 src/api/ 的安全性漏洞」
窗格 2：「審查 src/api/ 的效能問題」
窗格 3：「審查 src/api/ 的測試覆蓋率缺口」

# 將所有審查合併為單一報告

最佳實務

1. 僅限獨立任務。 不要平行化彼此輸出相依的任務。
2. 明確的邊界。 每個窗格應處理不同的檔案或關注點。
3. 策略性合併。 在合併前先檢閱窗格輸出，以避免衝突。
4. 使用 git worktrees。 對於容易發生檔案衝突的工作，每個窗格使用獨立的工作樹。
5. 資源意識。 每個窗格都會消耗 API 權杖 — 將總窗格數維持在 5-6 個以下。

Git Worktree 整合

對於會觸及重疊檔案的任務：

# 建立工作樹以隔離
git worktree add -b feat/auth ../feature-auth HEAD
git worktree add -b feat/billing ../feature-billing HEAD

# 在獨立工作樹中執行代理
# 窗格 1：cd ../feature-auth && claude
# 窗格 2：cd ../feature-billing && claude

# 完成後合併分支
git merge feat/auth
git merge feat/billing

輔助工具

工具	功能	使用時機
dmux	代理的 tmux 窗格管理	平行代理工作階段
Superset	支援 10+ 平行代理的終端機 IDE	大規模協調
Claude Code Task 工具	程序內子代理生成	工作階段內的程式化平行處理
Codex 多代理	內建代理角色	Codex 特定的平行工作

ECC 輔助工具

ECC 現在包含一個用於外部 tmux 窗格協調的輔助工具，支援獨立 git 工作樹：

node scripts/orchestrate-worktrees.js plan.json --execute

範例 plan.json：

{
  "sessionName": "skill-audit",
  "baseRef": "HEAD",
  "launcherCommand": "codex exec --cwd {worktree_path} --task-file {task_file}",
  "workers": [
    { "name": "docs-a", "task": "修復技能 1-4 並撰寫交接筆記。" },
    { "name": "docs-b", "task": "修復技能 5-8 並撰寫交接筆記。" }
  ]
}

輔助工具會：

• 為每個 worker 建立一個基於分支的 git 工作樹
• 可選擇性地將主檢出的 seedPaths 覆蓋到每個 worker 的工作樹中
• 在 .orchestration/<session>/ 下為每個 worker 寫入 task.md、handoff.md 和 status.md 檔案
• 啟動一個 tmux 工作階段，每個 worker 一個窗格
• 在各自的窗格中啟動每個 worker 指令
• 保留主窗格給協調者使用

當 worker 需要存取尚未包含在 HEAD 中的髒檔案或未追蹤的本地檔案（例如本地協調腳本、草稿計畫或文件）時，使用 seedPaths：

{
  "sessionName": "workflow-e2e",
  "seedPaths": [
    "scripts/orchestrate-worktrees.js",
    "scripts/lib/tmux-worktree-orchestrator.js",
    ".claude/plan/workflow-e2e-test.json"
  ],
  "launcherCommand": "bash {repo_root}/scripts/orchestrate-codex-worker.sh {task_file} {handoff_file} {status_file}",
  "workers": [
    { "name": "seed-check", "task": "在開始工作前確認種子檔案已存在。" }
  ]
}

疑難排解

• 窗格無回應： 直接切換到該窗格，或使用 tmux capture-pane -pt <session>:0.<pane-index> 檢查。
• 合併衝突： 使用 git 工作樹隔離每個窗格的檔案變更。
• 權杖用量過高： 減少平行窗格數量。每個窗格都是一個完整的代理工作階段。
• 找不到 tmux： 使用 brew install tmux（macOS）或 apt install tmux（Linux）安裝。