ECC dmux Workflows 实战指南:基于 tmux 窗格的 AI Agent 多会话并行编排 ECC dmux Workflows 实战指南基于 tmux 窗格的 AI Agent 多会话并行编排【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC在 ECCagent harness performance optimization system中dmux-workflows 是负责多 Agent 并行编排的核心技能文档它教你用 dmux一个面向 AI Agent 的 tmux 窗格管理器把多个 Claude Code、Codex、OpenCode 等会话拆到不同 tmux 窗格中并行执行并在完成后把各窗格的产出合并回主会话。读完本篇你既能掌握 dmux 的快捷键操作、五种并行工作流模式、Git worktree 隔离方案和故障排查手段也能从 ECC 源码层面理解dmux-tmux会话适配器如何把这些窗格会话规范化为ecc.session.v1快照供状态检查与持久化消费。dmux 是什么何时启用dmux 是一个基于 tmux 的 Agent 编排工具把每个 AI Agent 会话放进独立的 tmux 窗格pane中统一管理。它的核心交互只有两个键位按n新建一个窗格并输入 prompt启动一个新的 Agent 会话按m把指定窗格的输出合并merge回主会话。dmux 支持多种 harnessClaude Code、Codex、OpenCode、Cline、Gemini、Qwen。安装方式为npm install -g dmux依赖本机已安装 tmux。根据 技能文档 中Activation一节以下场景应启用 dmux 工作流需要并行运行多个 Agent 会话需要在 Claude Code、Codex 等多个 harness 之间协调工作复杂任务适合分而治之的并行拆解用户明确说出 run in parallel、split this work、use dmux、multi-agent 等意图。在仓库中这份技能同时维护在 skills/dmux-workflows/SKILL.md旧命令入口说明 指出/orchestrate等旧斜杠命令已被弃用正式指引以技能文档为准。技能元信息声明允许隐式调用见 agents/openai.yaml 中allow_implicit_invocation: true即当任务匹配上述场景时Agent 可自动套用这套工作流。快速上手最小化的 dmux 使用流程如下完整继承自原文档的 Quick Start 示例# 启动 dmux 会话 dmux # 在 dmux 中按 n 创建 Agent 窗格然后输入 prompt # Pane 1: Implement the auth middleware in src/auth/ # Pane 2: Write tests for the user service # Pane 3: Update API documentation # 每个窗格运行各自的 Agent 会话 # 完成后按 m 把结果合并回主会话要点在于主会话main pane是合并结果的汇聚点所有并行窗格视为工人worker其产出在合并前彼此不可见。因此任务拆分的第一步永远是确认各窗格之间没有未声明的依赖关系。五种并行工作流模式原文档给出了五种经过验证的拆窗格模式下面完整保留其 prompt 写法并补充适用边界。模式 1研究 实现Research Implement把调研和落地拆成两条并行轨道调研结果先落盘成文件实现侧完成后并Pane 1 (Research): Research best practices for rate limiting in Node.js. Check current libraries, compare approaches, and write findings to /tmp/rate-limit-research.md Pane 2 (Implement): Implement rate limiting middleware for our Express API. Start with a basic token bucket, well refine after research completes. # Pane 1 完成后把调研结论合并进 Pane 2 的上下文关键技巧是要求研究窗格把结论写入约定路径的文件如/tmp/rate-limit-research.md这样合并阶段可以直接引用文件内容而不是靠人肉转述。实现窗格先按保守方案开工调研完成后做精化避免实现侧空等。模式 2多文件特性Multi-File Feature把一个特性拆到互不重叠的文件集合上并行推进Pane 1: Create the database schema and migrations for the billing feature Pane 2: Build the billing API endpoints in src/api/billing/ Pane 3: Create the billing dashboard UI components # 全部合并后在主窗格做集成这个模式的前提是三个窗格各自的文件边界清晰。若边界模糊例如 API 端点与 schema 强耦合应退回到 Git worktree 隔离模式见下文或者接受串行。模式 3测试 修复循环Test Fix Loop一个窗格专职跑测试并汇总失败另一个窗格专职修Pane 1 (Watcher): Run the test suite in watch mode. When tests fail, summarize the failures. Pane 2 (Fixer): Fix failing tests based on the error output from pane 1这是典型的生产者-消费者分工Watcher 输出结构化的失败摘要Fixer 只消费摘要去改代码避免两个窗格同时改同一批文件。模式 4跨 Harness 分工Cross-Harness不同窗格跑不同 AI 工具按任务性质选工具Pane 1 (Claude Code): Review the security of the auth module Pane 2 (Codex): Refactor the utility functions for performance Pane 3 (Claude Code): Write E2E tests for the checkout flowdmux 的价值正在于它把 harness 差异收敛到窗格里跑什么命令这一层主会话只关心各窗格的产出。ECC 中与此对应的能力还有 docs/architecture/cross-harness.md 所述的跨 harness 一致性约定。模式 5代码评审流水线Code Review Pipeline同一份代码并行跑多个评审视角最后汇总成一份报告Pane 1: Review src/api/ for security vulnerabilities Pane 2: Review src/api/ for performance issues Pane 3: Review src/api/ for test coverage gaps # 把三份评审合并为一份报告这是扇出-聚合fan-out / fan-in形态三个窗格只读不改合并零冲突风险是 dmux 中最安全的并行模式。ECC 仓库自身也提供了单会话内的对应物如 code-review 命令 与 security-review 技能可视为该模式在单 Agent 场景下的替代。最佳实践原文档的五条实践是并行窗格稳定运行的经验总结只并行独立任务。不要并行化存在输出依赖的任务有依赖时先落盘中间产物如模式 1 的/tmp/rate-limit-research.md。边界清晰。每个窗格负责不同的文件或关注点。审慎合并。合并前先审查窗格产出避免引入冲突。善用 git worktrees。文件冲突风险高的工作每个窗格用独立 worktree。资源意识。每个窗格都是完整的 Agent 会话、消耗 API token并行窗格总数建议控制在 56 个以内。第 4 条的 worktree 集成在原文档中有完整命令示例# 为隔离创建 worktrees git worktree add ../feature-auth feat/auth git worktree add ../feature-billing feat/billing # 在各自 worktree 中运行 Agent # Pane 1: cd ../feature-auth claude # Pane 2: cd ../feature-billing claude # 完成后合并分支 git merge feat/auth git merge feat/billing这个做法与 ECC 仓库自身的 worktree 编排脚本一致scripts/orchestrate-worktrees.js 负责创建/回收 worktree 及对应会话scripts/worktree-lifecycle.js 管理 worktree 生命周期legacy-command-shims/commands/claw.md 中的旧命令也指向同一套指引。互补工具选型原文档用一张表划清了 dmux 与其他编排手段的分工边界工具作用适用时机dmux面向 Agent 的 tmux 窗格管理并行 Agent 会话Superset支持 10 并行 Agent 的终端 IDE大规模编排Claude Code Task 工具进程内派生子 Agent单会话内的程序化并行Codex multi-agent内建 Agent 角色Codex 专属的并行工作选型逻辑窗格级、跨 harness、需要人在 tmux 里直接观察每个会话的用 dmux单会话内想程序化派活用 harness 内置子 Agent 机制超大规模10 以上并行再考虑专用终端 IDE。故障排查症状处理窗格无响应检查该 Agent 会话是否在等待输入用m读取其输出合并冲突用 git worktree 隔离每个窗格的文件改动token 消耗过高减少并行窗格数——每个窗格都是完整 Agent 会话找不到 tmuxmacOS 用brew install tmuxLinux 用apt install tmux源码纵深ECC 如何把 dmux 会话纳入统一会话契约以上模式解决人怎么用 dmux而 ECC 作为 Agent harness 性能优化系统还回答编排状态如何被机器读取。仓库中dmux-tmux是官方会话适配器之一其调用链为registry选适配器 →dmux-tmux适配器开目标 →orchestration-session采集原始快照 →canonical-session归一化并持久化。适配器注册与目标路由scripts/lib/session-adapters/registry.js 中的TARGET_TYPE_TO_ADAPTER_ID把目标类型静态映射到适配器 idplan与session两类目标都路由到dmux-tmux第 8-17 行与 Claude 历史会话claude-history、Codex worktree 会话codex-worktree、OpenCode 会话并列注册。select()方法的逻辑是若上下文中已显式指定adapterId则直接取用否则遍历各适配器的canOpen(target, context)找到第一个能打开该目标的适配器第 119-129 行。canOpen什么样的目标算 dmux 会话scripts/lib/session-adapters/dmux-tmux.js 的canOpen判据第 51-62 行有两类来源plan 文件目标目标是一个存在的.json文件isPlanFileTarget第 9-18 行会话名目标目标对应.claude/orchestration/sessionName/协调目录存在isSessionNameTarget第 20-27 行。也就是说ECC 的 dmux 编排会话状态落在.claude/orchestration/下的按会话名分目录的结构里open()返回的getSnapshot()会调用collectSessionSnapshot实现在 scripts/lib/orchestration-session.js内部通过tmux list-panes -t sessionName枚举窗格并把窗格信息与协调目录下的 worker 记录对齐再交给归一化函数。归一化从窗格原始数据到 ecc.session.v1scripts/lib/session-adapters/canonical-session.js 中的normalizeDmuxSnapshot第 426-470 行把原始数据映射成规范快照每个 worker 的runtime.kind固定为tmux-pane并携带窗格的currentCommand、pid、active、deadworker 的branch/worktree直接取自 worker 状态文件——这与上文每窗格一个 worktree的实战模式形成闭环并行改动被 worktree 隔离快照里能看到每个 worker 落在哪个分支和 worktree 上会话级state由deriveDmuxSessionState第 132-160 行按规则推导sessionActive为真 →active无 worker →missing存在 failed/error →failed全部 completed/succeeded/success/done →completed其余 →idle。worker 级health由deriveWorkerHealth第 77-96 行推导running 状态下若窗格已死记为degraded状态更新时间超过 5 分钟阈值STALE_THRESHOLD_MS 5 * 60 * 1000第 69 行记为stale——这为窗格无响应这类故障提供了机器可读的信号。字段约束由validateCanonicalSnapshot第 162-263 行强制校验包括aggregates.workerCount必须等于workers.length、各计数 map 必须与 worker 实际状态一致等。这份契约的权威说明见 docs/SESSION-ADAPTER-CONTRACT.md其中给出了完整的dmux-tmux快照示例、session.state/worker.state的取值语义以及版本策略schemaVersion是唯一兼容门槛破坏性变更必须升版。持久化state store 优先JSON 文件兜底persistCanonicalSnapshot第 388-424 行的落盘策略是先尝试scripts/lib/state-store的写接口state store 不可用时回退到 JSON 文件记录器路径为recordingDir/adapterId/sessionId.json其中 recordingDir 的解析顺序是显式参数 → 环境变量ECC_SESSION_RECORDING_DIR→ 系统临时目录下的ecc-session-recordingsresolveRecordingDir第 265-275 行。回退记录器最新快照原地替换、历史只追加有变化的快照避免轮询式读取撑爆历史契约文档Recording Fallback Behavior一节有同描述。CLI 侧入口为 scripts/session-inspect.js 与 scripts/orchestration-status.js。测试佐证上述行为的测试覆盖在 tests/lib/session-adapters.test.js它直接引入normalizeDmuxSnapshot、createDmuxTmuxAdapter、createAdapterRegistry与inspectSessionTarget构造规范快照做字段校验与聚合一致性断言tests/scripts/orchestration-status.test.js 则覆盖编排状态输出。若你要验证我按文档操作后的会话状态确实能被 ECC 读取运行这些测试文件是最直接的依据。适用前提与限制dmux 是外部 npm 包npm install -g dmux运行前提是本机装有 tmux它不属于本仓库的构建产物本文档只描述用法与 ECC 侧的集成点。dmux-tmux适配器读取的协调结构是.claude/orchestration/sessionName/目录与 tmux 会话名跨 harness 时窗格内命令可以不同claude/codex等但会话名与协调目录约定不变。并行窗格数是 token 成本的线性放大文档建议的 56 上限在长任务中尤需遵守。快照契约当前版本为ecc.session.v1消费者不应假设所有适配器都有 tmux 窗格或 markdown 协调文件契约文档Consumer Expectations的约束。小结dmux-workflows 技能的骨架是窗格 独立 Agent 会话主会话 合并汇聚点用n/m两个键位管理生命周期用五种模式研究实现、多文件特性、测试修复、跨 harness、评审流水线覆盖常见的并行拆解用最佳实践和 worktree 隔离控制冲突与成本。ECC 在此之上补了一层机器可观测性——dmux-tmux适配器把窗格与 worktree 状态归一化为ecc.session.v1快照并持久化使并行编排从人在 tmux 里盯升级为状态可查询、可校验、可回放。想继续深入建议按顺序阅读 技能文档 → 会话适配器契约 → dmux-tmux 适配器实现 → session-adapters 测试。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考