catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-14 02:42:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: Implement CCW Coordinator for interactive command orchestration

Browse Source 
- Add action files for session management, command selection, building, execution, and completion.
- Introduce orchestrator logic to drive state transitions and action selection.
- Create state schema to define session state structure.
- Develop command registry and validation tools for command metadata extraction and chain validation.
- Establish skill configuration and specifications for command library and validation rules.
- Implement tools for command registry and chain validation with CLI support.
This commit is contained in:
catlog22
2026-01-23 23:39:16 +08:00
parent 8179472e56
commit e727a07fc5
15 changed files with 1728 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

320
.claude/skills/ccw-coordinator/SKILL.md Normal file
View File

@@ -0,0 +1,320 @@
---
name: ccw-coordinator
description: Interactive command orchestration tool for building and executing Claude CLI command chains. Triggers on "coordinator", "ccw-coordinator", "命令编排", "command chain", "orchestrate commands", "编排CLI命令".
allowed-tools: Task, AskUserQuestion, Read, Write, Bash, Glob, Grep
---
# CCW Coordinator
交互式命令编排工具：允许用户依次选择命令，形成命令串，然后依次调用claude cli执行整个命令串。
支持灵活的工作流组合，提供交互式界面用于命令选择、编排和执行管理。
## Architecture Overview
```
┌─────────────────────────────────────────────────────────────────┐
│ Orchestrator (状态驱动决策) │
│ 根据用户选择编排命令和执行流程 │
└───────────────┬─────────────────────────────────────────────────┘
│
┌───────────┼───────────┬───────────────┐
↓ ↓ ↓ ↓
┌─────────┐ ┌──────────────┐ ┌────────────┐ ┌──────────┐
│ Init │ │ Command │ │ Command │ │ Execute │
│ │ │ Selection │ │ Build │ │ │
│ │ │ │ │ │ │ │
│ 初始化 │ │ 选择命令 │ │ 编排调整 │ │ 执行链 │
└─────────┘ └──────────────┘ └────────────┘ └──────────┘
│ │ │ │
└───────────────┼──────────────┴────────────┘
│
↓
┌──────────────┐
│ Complete │
│ 生成报告 │
└──────────────┘
```
## Key Design Principles
1. **智能推荐**: Claude 根据用户任务描述，自动推荐最优命令链
2. **交互式编排**: 用户通过交互式界面选择和编排命令，实时反馈
3. **无状态动作**: 每个动作独立执行，通过共享状态进行通信
4. **灵活的命令库**: 支持ccw workflow命令和标准claude cli命令
5. **执行透明性**: 展示执行进度、结果和可能的错误
6. **会话持久化**: 保存编排会话，支持中途暂停和恢复
7. **智能提示词生成**: 根据任务上下文和前序产物自动生成 ccw cli 提示词
## Intelligent Prompt Generation
执行命令时，系统根据以下信息智能生成 `ccw cli -p` 提示词：
### 提示词构成
```javascript
// 集成命令注册表 (~/.claude/tools/command-registry.js)
const registry = new CommandRegistry();
registry.buildRegistry();
function generatePrompt(cmd, state) {
const cmdMeta = registry.getCommand(cmd.command);
let prompt = `任务: ${state.task_description}\n`;
if (state.execution_results.length > 0) {
const previousOutputs = state.execution_results
.filter(r => r.status === 'success')
.map(r => {
if (r.summary?.session) {
return `- ${r.command}: ${r.summary.session} (${r.summary.files?.join(', ')})`;
}
return `- ${r.command}: 已完成`;
})
.join('\n');
prompt += `\n前序完成:\n${previousOutputs}\n`;
}
// 从 YAML 头提取命令元数据
if (cmdMeta) {
prompt += `\n命令: ${cmd.command}`;
if (cmdMeta.argumentHint) {
prompt += ` ${cmdMeta.argumentHint}`;
}
}
return prompt;
}
```
### 产物追踪
每个命令执行后自动提取关键产物：
```javascript
{
command: "/workflow:lite-plan",
status: "success",
output: "...",
summary: {
session: "WFS-plan-20250123", // 会话ID
files: [".workflow/IMPL_PLAN.md"], // 产物文件
timestamp: "2025-01-23T10:30:00Z"
}
}
```
### 命令调用示例
```bash
# 自动生成的智能提示词
ccw cli -p "任务: 实现用户认证功能
前序完成:
- /workflow:lite-plan: WFS-plan-20250123 (.workflow/IMPL_PLAN.md)
命令: /workflow:lite-execute [--resume-session=\"session-id\"]" /workflow:lite-execute
```
### 命令注册表集成
- **位置**: `tools/command-registry.js` (skill 内置)
- **工作模式**: 按需提取（只提取用户任务链中的命令）
- **功能**: 自动查找全局 `.claude/commands/workflow` 目录，解析命令 YAML 头元数据
- **作用**: 确保提示词包含准确的命令参数和上下文
详见 `tools/README.md`
---
## Execution Flow
### Orchestrator Execution Loop
```javascript
1. 初始化会话
↓
2. 循环执行直到完成
├─ 读取当前状态
├─ 选择下一个动作（根据状态和用户意图）
├─ 执行动作，更新状态
└─ 检查终止条件
↓
3. 生成最终报告
```
### Action Sequence (Typical)
```
action-init
↓ (status: pending → running)
action-command-selection (可重复)
↓ (添加命令到链)
action-command-build (可选)
↓ (调整命令顺序)
action-command-execute
↓ (依次执行所有命令)
action-complete
↓ (status: running → completed)
```
## State Management
### Initial State
```json
{
"status": "pending",
"task_description": "",
"command_chain": [],
"confirmed": false,
"error_count": 0,
"execution_results": [],
"current_command_index": 0,
"started_at": null
}
```
### State Transitions
```
pending → running (init) → running → completed (execute)
↓
aborted (error or user exit)
```
## Directory Setup
```javascript
const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
const workDir = `.workflow/.ccw-coordinator/${timestamp}`;
Bash(`mkdir -p "${workDir}"`);
Bash(`mkdir -p "${workDir}/commands"`);
Bash(`mkdir -p "${workDir}/logs"`);
```
## Output Structure
```
.workflow/.ccw-coordinator/{timestamp}/
├── state.json # 当前会话状态
├── command-chain.json # 编排的完整命令链
├── execution-log.md # 执行日志
├── final-summary.md # 最终报告
├── commands/ # 各命令执行详情
│ ├── 01-command.log
│ ├── 02-command.log
│ └── ...
└── logs/ # 错误和警告日志
├── errors.log
└── warnings.log
```
## Reference Documents
| Document | Purpose |
|----------|---------|
| [phases/orchestrator.md](phases/orchestrator.md) | 编排器实现 |
| [phases/state-schema.md](phases/state-schema.md) | 状态结构定义 |
| [phases/actions/action-init.md](phases/actions/action-init.md) | 初始化动作 |
| [phases/actions/action-command-selection.md](phases/actions/action-command-selection.md) | 命令选择动作 |
| [phases/actions/action-command-build.md](phases/actions/action-command-build.md) | 命令编排动作 |
| [phases/actions/action-command-execute.md](phases/actions/action-command-execute.md) | 命令执行动作 |
| [phases/actions/action-complete.md](phases/actions/action-complete.md) | 完成动作 |
| [phases/actions/action-abort.md](phases/actions/action-abort.md) | 中止动作 |
| [specs/command-library.md](specs/command-library.md) | 命令库 |
| [specs/chain-registry.json](specs/chain-registry.json) | 命令元数据 |
| [specs/chain-validation-rules.md](specs/chain-validation-rules.md) | 验证规则 |
| [tools/chain-validate.js](tools/chain-validate.js) | 验证工具 |
---
## Usage Examples
### 快速命令链
用户想要执行：规划 → 执行 → 测试
```
1. 触发 /ccw-coordinator
2. 描述任务："实现用户注册功能"
3. Claude推荐: plan → execute → test-cycle-execute
4. 用户确认
5. 执行命令链
```
### 复杂工作流
用户想要执行：规划 → 执行 → 审查 → 修复
```
1. 触发 /ccw-coordinator
2. 描述任务："重构认证模块"
3. Claude推荐: plan → execute → review-session-cycle → review-fix
4. 用户可调整命令顺序
5. 确认执行
6. 实时查看执行进度
```
### 紧急修复
用户想要快速修复bug
```
1. 触发 /ccw-coordinator
2. 描述任务："修复生产环境登录bug"
3. Claude推荐: lite-fix --hotfix → test-cycle-execute
4. 用户确认
5. 快速执行修复
```
## Constraints and Rules
### 1. 命令推荐约束
- **智能推荐优先**: 必须先基于用户任务描述进行智能推荐，而非直接展示命令库
- **不使用静态映射**: 禁止使用查表或硬编码的推荐逻辑（如 `if task=bug则推荐lite-fix`）
- **推荐必须说明理由**: Claude 推荐命令链时必须解释为什么这样推荐
- **用户保留选择权**: 推荐后，用户可选择：使用推荐/调整/手动选择
### 2. 验证约束
- **执行前必须验证**: 使用 `chain-validate.js` 验证命令链合法性
- **不合法必须提示**: 如果验证失败，必须明确告知用户错误原因和修复方法
- **允许用户覆盖**: 验证失败时，询问用户是否仍要执行（警告模式）
### 3. 执行约束
- **顺序执行**: 命令必须严格按照 command_chain 中的 order 顺序执行
- **错误处理**: 单个命令失败时，询问用户：重试/跳过/中止
- **错误上限**: 连续 3 次错误自动中止会话
- **实时反馈**: 每个命令执行时显示进度（如 `[2/5] 执行: lite-execute`）
### 4. 状态管理约束
- **状态持久化**: 每次状态更新必须立即写入磁盘
- **单一数据源**: 状态只保存在 `state.json`，禁止多个状态文件
- **原子操作**: 状态更新必须使用 read-modify-write 模式，避免并发冲突
### 5. 用户体验约束
- **最小交互**: 默认使用智能推荐 + 一次确认，避免多次询问
- **清晰输出**: 每个步骤输出必须包含：当前状态、可用选项、建议操作
- **可恢复性**: 会话中断后，用户可从上次状态恢复
### 6. 禁止行为
- ❌ **禁止跳过推荐步骤**: 不能直接进入手动选择，必须先尝试推荐
- ❌ **禁止静态推荐**: 不能使用 recommended-chains.json 查表
- ❌ **禁止无验证执行**: 不能跳过链条验证直接执行
- ❌ **禁止静默失败**: 错误必须明确报告，不能静默跳过
## Notes
- 编排器使用状态机模式，确保执行流程的可靠性
- 所有命令链和执行结果都被持久化保存，支持后续查询和调试
- 支持用户中途修改命令链（在执行前）
- 执行错误会自动记录，支持重试机制
- Claude 智能推荐基于任务分析，非查表静态推荐