Claude-Code-Workflow · 智能体框架与编排

想象这样一个场景：你正在开发一个复杂的多智能体 AI 应用，需要同时协调 Claude Code、Codex、Qwen 等多个 CLI 工具，让它们在同一个工作流中分工协作——一个负责代码生成，一个负责架构设计，一个负责代码审查。你会怎么做？是用管道符简单串联，还是写一堆复杂的 shell 脚本？catlog22/Claude-Code-Workflow（以下简称 CCW）给出了一套更优雅的答案：把这一切交给 JSON 驱动的多智能体编排框架。

CCW 作者头像

图1：CCW 项目作者 catlog22 的 GitHub 头像

项目起源：从个人工具到社区框架

CCW 并非出自某个商业公司或知名开源组织，而是一位独立开发者 catlog22（GitHub ID: 28037070）在日常使用 Claude Code、Codex 等 AI 编程工具的过程中，逐渐沉淀下来的工作流框架。项目的核心理念是"JSON 驱动 + 上下文优先"：将复杂的 AI 协作流程抽象为结构化的 JSON 配置，再通过语义化的 CLI 编排引擎来执行。

这套框架的灵感来源非常实际——当开发者同时使用多个 AI CLI 工具时，每个工具都有各自的上下文管理方式、命令接口和交互模式。如果不做统一编排，工具之间很容易出现上下文割裂、重复生成、任务分配混乱等问题。CCW 的出现，就是为了解决"多 AI CLI 工具协同工作"这个真实痛点。

项目的版本演进也印证了这一点：从早期的单 CLI 调用模式，逐步演进到 Team 架构 v2（基于角色的多智能体），再到 v7.0+ 的 JSON 驱动工作流，工作流的粒度越来越细，支持的场景也越来越复杂。截至 2026 年 6 月，项目已发布至 v7.3.14，拥有超过 2100 颗 GitHub Stars，在 Node.js CLI 工具领域属于相当活跃的项目。

类比解释：AI 开发者的"指挥中心"

如果把 AI 编程工具比作不同特长的程序员，那么 CCW 就是把他们组织起来的项目经理。它不替代任何一个 AI 工具，而是站在更高层，用统一的"工作流语言"来协调它们的行动。

就好比一个建筑团队中，有人擅长画图纸（Architect），有人擅长施工（Builder），有人擅长质量检查（Reviewer）。CCW 的工作就是：根据 JSON 配置文件的内容，自动把任务分配给最合适的"队员"，并确保每个人的上下文信息不打架、交接记录有据可查。

这种设计的好处是显而易见的：工作流可以被版本化管理（就是那个 JSON 文件本身），可以被分享（Git 仓库里的 .ccw/workflows/ 目录），可以被审计和回放（Session 生命周期管理）。

核心功能：Skill 工作流与多 CLI 编排

CCW 的功能体系可以分为以下几个核心模块：

1. Skill 工作流系统

CCW 提供了从 lite-plan（轻量级规划）到 brainstorm（多角色头脑风暴）的多种预设工作流模板。用户也可以基于 templates/role-templates/system-architect-template.md 创建自定义角色模板。每个工作流本质上是一组有序的 Skill（技能节点），每个节点定义了要调用哪个 AI CLI、执行什么任务、如何处理输出。

工作流文件存储在 .ccw/workflows/ 目录下，支持 Markdown 和 JSON 两种格式。团队可以将工作流文件 commit 到 Git 仓库，实现版本控制和协作共享。

2. 多 CLI 智能编排引擎

CCW 支持同时编排 Gemini CLI、Qwen Code、OpenCode、Claude Code 等多个 AI CLI 工具。编排引擎会根据任务类型自动选择最合适的 CLI，也支持用户手动指定。核心的调度逻辑在 ccw/src/core/ 目录下，其中 lite-scanner.ts 和 lite-scanner-complete.ts 负责轻量级任务扫描，memory-consolidation-pipeline.ts 负责多轮对话的上下文记忆整合。

3. Team 架构 v2（多角色智能体）

v2 版本的 Team 架构引入了"角色"（Role）概念。每个角色有独立的系统提示词（来自 templates/role-templates/）、工具集和执行策略。角色之间通过 A2UI（Agent-to-User Interactive Interface，ccw/src/core/a2ui/）进行通信，支持实时交互和状态同步。

4. 终端仪表板（Terminal Dashboard）

CCW 提供了一个基于 Web 的可视化终端仪表板（ccw/frontend/），运行在 Vite + Playwright 栈上。用户可以在浏览器中查看多个终端的并行执行状态、监控任务进度。仪表板与 CLI 核心之间通过 WebSocket（A2UIWebSocketHandler.ts）保持实时通信。

5. MCP 服务器（Model Context Protocol）

CCW 包含一个 MCP 服务器实现（bin/ccw-mcp.js），基于 @modelcontextprotocol/sdk 构建，允许 CCW 作为 MCP 工具被其他 AI 应用（如 Claude Desktop）调用。这意味着 CCW 的工作流能力可以无缝接入更广泛的 AI 工具生态。

技术架构：TypeScript + 插件化设计

从代码结构来看，CCW 是一个典型的 TypeScript monorepo：

核心 CLI：ccw/src/cli.ts 负责命令行入口，使用 commander 库处理子命令（ccw/src/commands/）
工作流引擎：ccw/src/core/ 下包含 manifest 解析、缓存管理、历史导入器等模块
类型系统：ccw/src/types/ 定义了完整的数据模型，包括 Chain、Session、Skill、Queue 等核心类型
前端：ccw/frontend/ 是一个独立的 Vite + TypeScript Web 应用，用于可视化仪表板
MCP 集成：ccw/src/mcp-server/ 实现了 MCP 协议的服务端

关键依赖包括：

better-sqlite3（本地数据库，存储 session 和 memory）
node-pty（伪终端，支持真实 TTY 交互）
web-tree-sitter + tree-sitter-wasms（代码解析，用于上下文分析）
inquirer（交互式命令行 prompt）
zod（v4.1.13，数据校验）
jsonwebtoken（认证令牌管理）
@modelcontextprotocol/sdk（MCP 协议实现）

值得注意的是，CCW 使用了 npm workspaces 管理 monorepo（根 package.json + ccw/ 和 ccw/frontend/ 两个 workspace），构建产物通过 tsc 编译为 JavaScript 后输出到 ccw/dist/。

上手门槛与部署

CCW 的安装非常简洁：

npm install -g claude-code-workflow
ccw install -m Global

最低要求 Node.js >= 18，无需 GPU，属于纯 CPU 运行的标准 CLI 工具。安装后，native 模块（better-sqlite3、node-pty）会根据平台自动 rebuild，确保伪终端和数据库功能正常工作。

Web 前端仪表板是可选组件，需要单独运行 npm run frontend（开发模式）或 npm run frontend:build（构建生产版本）。前端通过 Vite 开发服务器提供，默认不随 CLI 安装自动启动。

项目没有提供 Dockerfile 或 docker-compose 配置，不支持容器化部署。对于习惯 Docker 环境的用户来说，这是一个遗憾——如果需要标准化部署或 CI/CD 集成，需要自己编写 Dockerfile。

局限与争议

CCW 并非没有短板，以下几点值得关注：

第一，平台锁定效应。CCW 深度绑定了 Node.js 生态，对于 Python 开发者或纯 Shell 用户来说，上手成本较高。此外，native 模块（node-pty、better-sqlite3）的跨平台编译有时会遇到问题，尤其在 ARM 架构（Apple Silicon）和 Windows 环境下。

第二，调试成本。多智能体协作的问题排查本身就有一定难度，CCW 虽然提供了 Session 生命周期管理（start/resume/complete/sync），但在真实出错时，理解"哪个 Agent 在哪一步失败、上下文丢失了多少"仍然需要一定的经验积累。

第三，文档碎片化。README 和工作流指南虽然覆盖了主要功能，但中文文档（README_CN.md、WORKFLOW_GUIDE_CN.md）与英文文档之间存在内容同步问题，部分新功能的说明只在英文文档中出现。

第四，无官方容器支持。对于企业级部署场景，缺少 Dockerfile 意味着无法直接纳入容器化 CI/CD 流水线，用户需要自行维护打包方案。

行业意义与增长态势

CCW 的出现在一定程度上反映了 2025-2026 年 AI 编程工具生态的一个趋势：从"单一工具效率提升"向"多工具协作编排"演进。随着 Claude Code、Codex、Qwen Code、Gemini CLI 等工具的成熟，开发者越来越需要在同一个项目中组合使用多个 AI 助手——每个工具各有优势，联合使用才能最大化效率。

CCW 提出的 JSON 驱动工作流 + 语义化 CLI 编排的模式，为这一方向提供了一套可复用的技术方案。其 monorepo 架构、TypeScript 类型安全、以及 MCP 协议的接入，都体现了较高的工程水准。

从社区反响来看，2100+ Stars 和活跃的版本迭代（v7.x 仍在持续更新）说明确实有真实用户群体在依赖这个工具。如果你是一个需要频繁在多个 AI CLI 之间切换的开发者，CCW 值得一试；但如果你的团队已经有一套成熟的多 Agent 编排方案（如 LangGraph、Docker Compose 多服务架构），CCW 的价值就相对有限了。

CCW 微信交流群

图2：CCW 项目微信交流群二维码，欢迎对多智能体工作流感兴趣的开发者加入交流

本报告由 PIFS 自动分析系统生成，分析时间：2026-06-11。数据来源：GitHub API（仓库信息、文件结构）、项目 README 及源码。