核心设计哲学：通过纯净独立的上下文保持智能体的最高水准状态，通过混合文档（Hybrid Docs）实现优雅的自动化与半自动化无缝切换。单一文档写入者（orchestratorX）确保状态一致性，结构化 Payload 通信实现零上下文污染。

🌟 设计理念

• 零依赖部署，配置即运行 — 纯文件驱动，拷贝即用
• 单一写入者，状态一致 — orchestratorX 是唯一的文档写入者，杜绝多源冲突
• 降低幻觉成本，极限提升单步效率 — 纯净上下文 + 结构化 Payload 通信
• 单点切入，全局联动 — 需求变更自动传播，依赖自动排队重试

🏗 系统架构设计

当前大语言模型在处理超长且复杂的上下文时容易出现”记忆灾难”。WorkflowX 提出了一套模块化的解决方案：

1. 调度主智能体（Orchestrator Agent）：中枢大模型，负责拆解用户需求、规划路径，并在各个节点唤起对应能力的子智能体。orchestratorX 是唯一的文档写入者——所有混合文档的创建和更新都由它完成。
2. 纯净态子智能体（Specialized Sub-Agents）：通过 runSubAgent 协议挂载。每个子智能体被唤起时，都拥有独立且纯净的上下文。coderX 是纯读取+实现者（只读文档、写代码、输出 Payload），evaluatorX 是纯分析者（只读文档+代码、输出评估 Payload），两者均不写入任何文档。
3. ”混合文档”状态流转：摒弃传统对话中”长文不断累加”的隐性黑盒上下文，将任务进度、知识索引与工程架构输出并持久化为混合文档。采用 Hybrid Tree 结构（Parent 路由层 + Children 需求层），实现 MECE 分工。
4. 总线管道通信（Bus Pipeline）：智能体之间通过 3 种结构化 Payload 通信——Change Summary（coderX→orchestratorX→evaluatorX）、Evaluation Result（evaluatorX→orchestratorX）、Requirement Change（orchestratorX 内部）。orchestratorX 负责验证格式、转发 Payload，并执行文档更新。

✨ 核心能力

提示词优化引擎 (Prompt-Master)

内置 prompt-master 技能，为 20+ 种 AI 工具（Claude、GPT、Gemini、Cursor、Copilot 等）生成生产级提示词：

• 9维意图解析：静默分析任务、目标工具、输出格式、约束条件等维度
• 工具专属路由：根据目标模型自动匹配最优提示策略（如推理模型不追加 CoT）
• 6类故障扫描：自动检测并修复任务歧义、上下文缺失、格式偏差等常见问题
• 一键即用：输出可直接复制粘贴的提示词块，零二次修改

混合文档 × 索引 × 记忆图谱 —— 极致 Token 节省

WorkflowX 通过三层协同架构大幅削减上下文开销：

第一层：混合文档拓扑排序 (Prompt Caching)

• 将 Hybrid 文档严格划分为静态区（需求、范围、DoD — 极少变动）、增量区（功能验收、文件索引）、动态区（评估报告 — 每轮覆写）
• 静态区置于顶部，持续命中 LLM Prompt Cache；动态区置于底部，覆写时不会导致缓存失效
• 百轮对话后 Token 开销仍可保持极低水平

第二层：干叶分离索引 (Trunk-Leaf Index)

• Markdown 文档仅保留业务”树干”大纲，不堆积代码细节
• 实体关联、代码结构等”树叶”通过 MCP Knowledge Graph 独立维护
• 智能体按需动态检索，保持工程文档精瘦

第三层：记忆图谱快照 (Memory Snapshot)

• Hybrid 文档 §8.2 仅存储知识图谱的骨架指针（实体名称、关系概要）
• 完整的叶子节点详情由 MCP server-memory 持久化
• L3 深度压缩时自动同步图谱状态，确保文档与图谱一致
• 跨会话、跨智能体共享知识，无需重复传递上下文

三层协同效果：静态需求触发缓存 → 增量索引定向引用 → 记忆图谱按需加载，将每次 SubAgent 唤醒的输入 Token 压缩到最小。

🤖 自动化与半自动化随时切换

因为跨智能体状态通过清晰的 Markdown/混合文本持久化存储，人类开发者可以随时在某个环节介入，审查或修改文档，指导下一个智能体的方向。

🧹 拒绝上下文污染

严格控制每一个子 Agent 的信息输入口径，不向它灌输冗余的历史对话，大幅降低大模型的幻觉概率。

📊 工作流状态可视化 (/xstatus)

一条指令即可生成高保真 HTML 状态报告，实时展示当前所有工作流的进展：

• 数据源：xwhole / xlocal / xwhole -parallel 从 .hybrid/ 解析 Parent + Child 文档；xunit 从 git log 推断（明确标注"no documents"）
• 风格：基于 huashu-design 设计语言——暖白底 + 衬线 display 字体 + rust 橙 accent，反 AI slop（避免紫渐变/emoji 装饰/圆角左 border）
• 差异化展示：4 个工作流模式各自独立的展示格式——Children 树状 / 进度条 / 迭代轮次 / Team 状态侧栏 / git 活动表
• 只读 + 幂等：不修改任何项目文件，每次执行覆盖 ./status-report.html，生成后自动在默认浏览器打开
• 可自定义输出：/xstatus --output <path> 指定输出路径，便于归档或分享

/xstatus                            # 输出到 ./status-report.html 并打开
/xstatus --output ./reports/today.html  # 输出到指定路径

环境准备 (Setup & Installation)

1. 确保安装了 Node.js (v18+) 与 Python 3.10+。
2. 安装工作流所需的 MCP 工具：

npm install -g @modelcontextprotocol/server-memory @modelcontextprotocol/server-sequential-thinking

1. 提供的配置文件模板 mcp.json.template,在您的 AI Client (如 VSCode Copilot / Claude) 中配置并挂载上述 MCP。

🚀 使用指南 (Workflow & Usage)

1. 平台接入

WorkflowX 本质上是一套轻量纯粹的配置文件与指令集系统。不绑定任何运行时，无需安装额外服务——将配置文件复制到项目目录即可完成部署。

本工程提供三套平台配置，按需选用：

💡 四套配置的工作流逻辑完全一致（相同的指令、模式、多个运行时模块），仅工具调用语法因平台而异。并行模式（/xwhole -parallel）仅 Claude Code 支持，依赖其 Agent Teams 实验性功能。OpenCode 通过 .claude/skills/ 自动发现机制复用已有技能定义，无需额外复制。所有模式均自动启用 Worktree 隔离（xunit 除外）。

快速部署步骤：

1. 将对应平台的配置目录（如 .claude/ 或 .opencode/）复制到您的项目根目录
2. 安装 MCP 依赖：npm install -g @modelcontextprotocol/server-memory @modelcontextprotocol/server-sequential-thinking
3. 在 AI 客户端中挂载 MCP 配置（参考 mcp.json.template；OpenCode 用户可直接使用项目根目录的 opencode.json，MCP 已内置配置）
4. 开始使用：在对话中呼叫 orchestratorX 并投递需求

OpenCode 专项配置说明：

OpenCode 用户需要关注以下配置文件：

OpenCode 的 opencode.json 已内置 MCP 配置，无需额外创建 mcp.json。如需调整 MCP 服务器路径（如 Node.js 安装位置不同），修改 opencode.json 中 command 字段的路径即可。

并行模式（/xwhole -parallel）依赖 Claude Code 的 Agent Teams 功能，OpenCode 不支持。如需并行效果，请手动拆分任务后分别使用 /xlocal 执行。

2. 指令速查

默认行为：所有开发类请求会自动路由经过 orchestratorX。纯文件读取、配置修改、Git 操作等例外场景可直接执行。

3. 工作流模式

orchestratorX 根据需求复杂度自动路由（基于文件范围、关键词、影响范围、是否需要 PRD 四个维度推断），也可通过指令手动指定：

/xwhole              → [orchestratorX 规划对话] → [promptMasterX 优化] → [coderX 实现] → [evaluatorX 评估] → 循环
/xwhole -parallel    → [orchestratorX 创建 Agent Team] → [多个 coder-teammate 并行实现] → [多个 evaluator-teammate 并行评估] → 循环
/xlocal              → [promptMasterX 优化] → [coderX 实现] → [evaluatorX 评估] → 循环
/xunit               → [promptMasterX 优化] → [coderX 实现] → 完成

⚠️ /xwhole -parallel 仅支持 Claude Code

并行模式依赖 Claude Code 的实验性 Agent Teams 功能（CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1），其他平台（Codex、Copilot、OpenCode）不支持此模式。如需在其他平台实现并行效果，请使用 /xwhole 手动拆分任务。

4. 实战示例：一次完整的 /xwhole 工作流

假设您要为项目添加一个"用户登录"功能：

① 发起请求
   /xwhole 实现用户登录功能，支持邮箱+密码和 OAuth 两种方式

② orchestratorX 自动路由到 whole 模式
   → 在当前会话中进行多轮需求规划对话
   → 生成 Hybrid Tree：[UserLogin]-hybrid.md（Parent）+ 子模块 Child 文档
   → 您审阅 hybrid 文档，确认需求无误后回复"确认"

③ promptMasterX 优化执行指令
   → 将确认后的需求转化为精确的 coderX 执行提示词

④ coderX 根据提示词编码实现
   → 完成后输出 Change Summary Payload："完成了 auth 模块的登录逻辑，
     新增 oauth_callback 处理，请重点检查 token 刷新流程"

⑤ evaluatorX 根据 Payload 定向审查
   → 输出 Evaluation Result Payload（AC 状态表 + 问题列表 + 修复指令）
   → orchestratorX 更新文档并决定是否继续迭代（最多 N 轮）

⑥ 迭代完成
   → evaluatorX 确认通过，hybrid 文档收口为最终版本
   → 可手动呼叫 abstracterX 生成代码摘要（可选）

人工介入：在任意步骤之间，您可以直接编辑 hybrid 文档来调整需求、修改约束或纠正方向。由于 orchestratorX 是唯一的文档写入者，您的手动编辑不会被覆盖——下一个智能体启动时会自动读取您修改后的内容。迭代过程中如需变更需求，orchestratorX 会自动识别变更类型（调整/优化/扩缩/新增分支）并相应更新文档。

6. 并行模式配置（仅 Claude Code）

/xwhole -parallel 允许同时执行多个独立子任务，大幅提升开发效率。并行模式是 Mode A 的扩展参数，共享相同的规划流程，但使用 Agent Teams 进行并行执行。

前置条件：

1. Claude Code v2.1.32+
2. 设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
3. 在 settings.json 中配置 teammateMode: "in-process"

配置示例（.claude/settings.json）：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "in-process"
}

工作流程：

/xwhole -parallel 实现用户、订单、商品三个独立模块
  ↓
orchestratorX 进行规划对话（同 Mode A）
  ↓
创建 Agent Team，自动生成 Hybrid Tree，拆分为并行任务
  ↓
每个 teammate 自动获得独立 worktree（物理隔离）
  ↓
多个 coder-teammate 同时编码实现
  ↓
多个 evaluator-teammate 同时评估审查
  ↓
迭代修复 → 全部通过 → 合并 worktree 分支 → TeamDelete 清理

双层隔离（-parallel + -box）：

main 分支
  └── sandbox/feature-x (沙箱分支)        ← 第一层：保护 main
        ├── worktree/coder-1              ← 第二层：agent 间隔离
        ├── worktree/coder-2
        ├── worktree/evaluator-1
        └── worktree/evaluator-2

适用场景：

• 多个独立模块的并行开发（如用户模块、订单模块、商品模块）
• 批量功能实现（如多个 API 接口）
• 需要快速验证多个独立设计方案

不适用场景：

• 模块间有强依赖关系（需串行执行）
• 单文件修改（使用 /xunit）
• 需要深度规划对话（使用 /xwhole）

5. 多平台协作

由于配置目录互相独立，您可以在不同工具中使用同一套工作流：

• Claude Code CLI：.claude/agents/orchestratorX.md 定义智能体行为，唯一支持并行模式（/xwhole -parallel）的平台
• VS Code + Copilot：.github/agents/orchestratorX.agent.md 使用 VSCode 原生工具绑定
• OpenAI Codex CLI：.codex/agents/orchestratorX.toml 使用 TOML 格式配置
• OpenCode：.opencode/agents/orchestratorX.md + .opencode/commands/ 定义智能体与指令，通过 Task tool 委派子任务

四者共享相同的 skills 定义（位于各平台的 skills/ 目录），确保工作流行为一致。OpenCode 会自动从 .claude/skills/ 发现技能，因此无需重复配置。核心技能已精简为 6 个：orchestrator-playbook（编排手册 + 规划 + 需求路由）、evaluator-prd-audit、codex-spec-implementation、prompt-master、abstracter-code-summary、guidelines。

并行模式平台限制：/xwhole -parallel 依赖 Claude Code 的 Agent Teams 功能（CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 + teammateMode: "in-process"），其他平台无法使用。如需在 Codex/Copilot/OpenCode 中实现并行效果，建议手动拆分任务后分别使用 /xlocal 执行。

🌟 关于

这是真实投入各个社区使用的一个开源实验性项目，旨在探索多智能体协同开发的最佳实践与架构设计。

欢迎任何形式的讨论、建议与贡献！
如何贡献：Fork 本仓库，提交 Pull Request，或直接在 Issues 中提出你的想法。

公众号：[TreeX-AI]

如果开源对你有帮助，欢迎点亮⭐，让更多人加入一起探索 AI 开发的未来！

⭐星级历史