diff --git a/.claude/skills/skill-generator/SKILL.md b/.claude/skills/skill-generator/SKILL.md index 26da1afa..ad2b70ea 100644 --- a/.claude/skills/skill-generator/SKILL.md +++ b/.claude/skills/skill-generator/SKILL.md @@ -94,6 +94,7 @@ Phase 01 → Phase 02 → Phase 03 → ... → Phase N | Document | Purpose | Priority | |----------|---------|----------| | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | 通用设计规范 - 定义所有 Skill 的结构、命名、质量标准 | **P0 - 最高** | +| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | **参考文档生成规范** - 确保生成的skill中Reference Documents部分有正确的分阶段组织和使用时机指引 | **P0 - 最高** | ### 模板文件 (生成前必读) @@ -193,6 +194,7 @@ Phase 3: Phase/Action Generation Phase 4: Specs & Templates └─ Generate domain specifications and templates ├─ Input: skill-config.json (domain context) + ├─ ⚠️ 参考规范: [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 确保生成的参考文档有正确的分阶段组织 ├─ Tool: Write │ ├─ Generate: specs/{domain}-requirements.md │ ├─ Generate: specs/quality-standards.md @@ -273,105 +275,89 @@ Write(`${skillDir}/README.md`, generateReadme(config, validation)); --- -## Phase Reference Guide -Navigation and entry points for each execution phase: +## Reference Documents by Phase -### Phase 0: Specification Study (Mandatory) +> **重要**: 本部分展示skill-generator如何组织自己的参考文档，这是生成的skill应该模仿的示例。详见 [specs/reference-docs-spec.md](specs/reference-docs-spec.md) -**Document**: 🔗 [SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) +### 🔧 Phase 0: Specification Study (强制前置) -**Purpose**: Understand skill design standards before generating +所有生成操作前必须阅读的规范 -**What to Read**: -- Skill structure conventions -- Naming standards -- Quality criteria -- Output format specifications +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Skill设计通用规范 | 理解Skill结构和命名规范 ✅ **必读** | +| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档生成规范 | 确保Reference Documents有正确的组织方式 ✅ **必读** | + +### 📋 Phase 1: Requirements Discovery + +收集Skill需求和配置 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Phase 1执行指南 | 理解如何收集用户需求和生成配置 | +| [specs/skill-requirements.md](specs/skill-requirements.md) | Skill需求规范 | 理解Skill应包含哪些信息 | + +### 🔧 Phase 2: Structure Generation + +生成目录结构和入口文件 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Phase 2执行指南 | 理解如何生成目录结构 | +| [templates/skill-md.md](templates/skill-md.md) | SKILL.md模板 | 了解如何生成入口文件 | + +### ⚙️ Phase 3: Phase/Action Generation + +根据执行模式生成具体的phase或action文件 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Phase 3执行指南 | 理解Sequential vs Autonomous生成逻辑 | +| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase模板 | 生成Sequential模式的phase文件 | +| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator模板 | 生成Autonomous模式的编排器 | +| [templates/autonomous-action.md](templates/autonomous-action.md) | Action模板 | 生成Autonomous模式的action | + +### ✅ Phase 4: Specs & Templates + +生成领域特定的规范和模板 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Phase 4执行指南 | 理解如何生成domain-specific文档 | +| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档规范 | ⭐ 生成Specs时要遵循的规范 | + +### 🏁 Phase 5: Validation & Documentation + +验证生成结果并生成最终文档 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/05-validation.md](phases/05-validation.md) | Phase 5执行指南 | 理解如何验证生成的skill完整性 | + +### 🔍 Debugging & Troubleshooting + +遇到问题时查阅 + +| Issue | Solution Document | +|-------|------------------| +| 生成的Skill缺少Reference Documents | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 检查是否遵循分阶段组织 | +| 参考文档组织混乱 | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 核心原则部分 | +| 生成的文档不符合质量标准 | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | + +### 📚 Reference & Background + +用于深度学习和设计决策 + +| Document | Purpose | Notes | +|----------|---------|-------| +| [specs/execution-modes.md](specs/execution-modes.md) | 执行模式详细规范 | Sequential vs Autonomous的对比和适用场景 | +| [specs/cli-integration.md](specs/cli-integration.md) | CLI集成规范 | 生成的Skill如何与CLI集成 | +| [specs/scripting-integration.md](specs/scripting-integration.md) | 脚本集成规范 | Phase中如何使用脚本 | +| [templates/script-template.md](templates/script-template.md) | 脚本模板 | Bash + Python统一模板 | --- -### Phase 1: Requirements Discovery - -**Document**: 🔗 [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) - -| Attribute | Value | -|-----------|-------| -| **Purpose** | Gather configuration from user via interactive prompts | -| **Input** | User responses (Skill name, purpose, execution mode) | -| **Output** | `skill-config.json` (configuration file) | -| **Key Decision** | Execution mode: Sequential vs Autonomous vs Hybrid | - ---- - -### Phase 2: Structure Generation - -**Document**: 🔗 [phases/02-structure-generation.md](phases/02-structure-generation.md) - -| Attribute | Value | -|-----------|-------| -| **Purpose** | Create directory structure and entry file | -| **Input** | `skill-config.json` (from Phase 1) | -| **Output** | `.claude/skills/{skill-name}/` directory + `SKILL.md` | - ---- - -### Phase 3: Phase/Action Generation - -**Document**: 🔗 [phases/03-phase-generation.md](phases/03-phase-generation.md) - -| Attribute | Value | -|-----------|-------| -| **Purpose** | Generate execution phases or actions based on mode | -| **Input** | `skill-config.json` + Templates | -| **Output** | Sequential: `phases/01-*.md` ... OR Autonomous: `phases/orchestrator.md` + `actions/*.md` | - -**Decision Logic**: -``` -IF execution_mode === "sequential": - └─ Generate sequential phases with linear flow -ELSE IF execution_mode === "autonomous": - └─ Generate orchestrator + independent actions -``` - ---- - -### Phase 4: Specs & Templates - -**Document**: 🔗 [phases/04-specs-templates.md](phases/04-specs-templates.md) - -| Attribute | Value | -|-----------|-------| -| **Purpose** | Generate domain specifications and template files | -| **Input** | `skill-config.json` (domain context) | -| **Output** | `specs/{skill-name}-requirements.md`, `specs/quality-standards.md` | - ---- - -### Phase 5: Validation & Documentation - -**Document**: 🔗 [phases/05-validation.md](phases/05-validation.md) - -| Attribute | Value | -|-----------|-------| -| **Purpose** | Verify completeness and generate usage documentation | -| **Input** | All files from previous phases | -| **Output** | `README.md`, `validation-report.json` | - ---- - -## Template Reference - -| Template | Generated For | When Used | -|----------|--------------|-----------| -| [skill-md.md](templates/skill-md.md) | SKILL.md entry file | Phase 2 | -| [sequential-phase.md](templates/sequential-phase.md) | Sequential phase files | Phase 3 | -| [autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator (autonomous) | Phase 3 | -| [autonomous-action.md](templates/autonomous-action.md) | Action files | Phase 3 | -| [code-analysis-action.md](templates/code-analysis-action.md) | Code analysis actions | Phase 3 | -| [llm-action.md](templates/llm-action.md) | LLM-powered actions | Phase 3 | -| [script-template.md](templates/script-template.md) | Bash + Python scripts | Phase 3/4 | - ## Output Structure ### Sequential Mode @@ -415,4 +401,86 @@ ELSE IF execution_mode === "autonomous": │ └── action-base.md ├── scripts/ └── README.md -``` \ No newline at end of file +``` + +--- + +## Reference Documents by Phase + +> **重要**: 本部分展示skill-generator如何组织自己的参考文档，这是生成的skill应该模仿的示例。详见 [specs/reference-docs-spec.md](specs/reference-docs-spec.md) + +### 🔧 Phase 0: Specification Study (强制前置) + +所有生成操作前必须阅读的规范 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Skill设计通用规范 | 理解Skill结构和命名规范 ✅ **必读** | +| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档生成规范 | 确保Reference Documents有正确的组织方式 ✅ **必读** | + +### 📋 Phase 1: Requirements Discovery + +收集Skill需求和配置 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Phase 1执行指南 | 理解如何收集用户需求和生成配置 | +| [specs/skill-requirements.md](specs/skill-requirements.md) | Skill需求规范 | 理解Skill应包含哪些信息 | + +### 🔧 Phase 2: Structure Generation + +生成目录结构和入口文件 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Phase 2执行指南 | 理解如何生成目录结构 | +| [templates/skill-md.md](templates/skill-md.md) | SKILL.md模板 | 了解如何生成入口文件 | + +### ⚙️ Phase 3: Phase/Action Generation + +根据执行模式生成具体的phase或action文件 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Phase 3执行指南 | 理解Sequential vs Autonomous生成逻辑 | +| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase模板 | 生成Sequential模式的phase文件 | +| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator模板 | 生成Autonomous模式的编排器 | +| [templates/autonomous-action.md](templates/autonomous-action.md) | Action模板 | 生成Autonomous模式的action | + +### ✅ Phase 4: Specs & Templates + +生成领域特定的规范和模板 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Phase 4执行指南 | 理解如何生成domain-specific文档 | +| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | 参考文档规范 | ⭐ 生成Specs时要遵循的规范 | + +### 🏁 Phase 5: Validation & Documentation + +验证生成结果并生成最终文档 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/05-validation.md](phases/05-validation.md) | Phase 5执行指南 | 理解如何验证生成的skill完整性 | + +### 🔍 Debugging & Troubleshooting + +遇到问题时查阅 + +| Issue | Solution Document | +|-------|------------------| +| 生成的Skill缺少Reference Documents | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 检查是否遵循分阶段组织 | +| 参考文档组织混乱 | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - 核心原则部分 | +| 生成的文档不符合质量标准 | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | + +### 📚 Reference & Background + +用于深度学习和设计决策 + +| Document | Purpose | Notes | +|----------|---------|-------| +| [specs/execution-modes.md](specs/execution-modes.md) | 执行模式详细规范 | Sequential vs Autonomous的对比和适用场景 | +| [specs/cli-integration.md](specs/cli-integration.md) | CLI集成规范 | 生成的Skill如何与CLI集成 | +| [specs/scripting-integration.md](specs/scripting-integration.md) | 脚本集成规范 | Phase中如何使用脚本 | +| [templates/script-template.md](templates/script-template.md) | 脚本模板 | Bash + Python统一模板 | \ No newline at end of file diff --git a/.claude/skills/skill-generator/specs/reference-docs-spec.md b/.claude/skills/skill-generator/specs/reference-docs-spec.md new file mode 100644 index 00000000..148da76d --- /dev/null +++ b/.claude/skills/skill-generator/specs/reference-docs-spec.md @@ -0,0 +1,271 @@ +# Reference Documents Generation Specification + +> **重要**: 本规范定义如何在生成的skill中组织和展现参考文档，避免重复问题。 + +## 核心原则 + +### 1. 分阶段组织 (Phase-Based Organization) + +参考文档必须按照skill的执行阶段组织，而不是平铺列表。 + +**❌ 错误方式** (平铺列表): +```markdown +## Reference Documents + +| Document | Purpose | +|----------|---------| +| doc1.md | ... | +| doc2.md | ... | +| doc3.md | ... | +``` + +**✅ 正确方式** (分阶段导航): +```markdown +## Reference Documents by Phase + +### 📋 Phase 1: Analysis +执行Phase 1时查阅的文档 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| doc1.md | ... | 理解x概念 | + +### ⚙️ Phase 2: Implementation +执行Phase 2时查阅的文档 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| doc2.md | ... | 实现y功能 | +``` + +### 2. 四个标准分组 + +参考文档必须分为以下四个分组： + +| 分组 | 使用时机 | 内容 | +|-----|---------|------| +| **Phase N: [Name]** | 执行该Phase时 | 该阶段相关的所有文档 | +| **🔍 Debugging** | 遇到问题时 | 问题→文档映射表 | +| **📚 Reference** | 深度学习时 | 模板、原始实现、最佳实践 | +| (可选) **📌 Quick Links** | 快速导航 | 最常查阅的5-7个文档 | + +### 3. 每个文档条目必须包含 + +``` +| [path](path) | Purpose | When to Use | +``` + +**When to Use 列要求**: +- ✅ 清晰说明使用场景 +- ✅ 描述解决什么问题 +- ❌ 不要简单说 "参考" 或 "了解" + +**良好例子**: +- "理解issue数据结构" +- "学习Planning Agent的角色" +- "检查implementation是否达到质量标准" +- "快速定位状态异常的原因" + +**糟糕例子**: +- "参考文档" +- "更多信息" +- "背景知识" + +### 4. 执行流程中嵌入文档指引 + +在"Execution Flow"部分，每个Phase说明中应包含"查阅"提示： + +```markdown +### Phase 2: Planning Pipeline +→ **查阅**: action-plan.md, subagent-roles.md +→ 具体流程说明... +``` + +### 5. 问题排查快速查询表 + +应包含常见问题到文档的映射： + +```markdown +### 🔍 Debugging & Troubleshooting + +| Issue | Solution Document | +|-------|------------------| +| Phase执行失败 | 查阅相应Phase文档 | +| 输出格式不符 | specs/quality-standards.md | +| 数据验证失败 | specs/schema-validation.md | +``` + +--- + +## 生成规则 + +### 规则 1: 文档分类识别 + +根据skill的phases自动生成分组： + +```javascript +const phaseEmojis = { + 'discovery': '📋', // 收集、探索 + 'generation': '🔧', // 生成、创建 + 'analysis': '🔍', // 分析、审查 + 'implementation': '⚙️', // 实现、执行 + 'validation': '✅', // 验证、测试 + 'completion': '🏁', // 完成、收尾 +}; + +// 为每个phase生成一个章节 +phases.forEach((phase, index) => { + const emoji = phaseEmojis[phase.type] || '📌'; + const title = `### ${emoji} Phase ${index + 1}: ${phase.name}`; + // 列出该phase相关的所有文档 +}); +``` + +### 规则 2: 文档到Phase的映射 + +在config中，specs和templates应标注所属的phases： + +```json +{ + "specs": [ + { + "path": "specs/issue-handling.md", + "purpose": "Issue数据规范", + "phases": ["phase-2", "phase-3"], // 这个spec与哪些phase相关 + "context": "理解issue结构和验证规则" + } + ] +} +``` + +### 规则 3: 优先级和必读性 + +用视觉符号区分文档的重要性： + +```markdown +| Document | When | Notes | +|----------|------|-------| +| spec.md | **执行前必读** | ✅ 强制前置 | +| action.md | 执行时查阅 | 操作指南 | +| template.md | 参考学习 | 可选深入 | +``` + +### 规则 4: 避免重复 + +- **Mandatory Prerequisites** 部分：列出强制必读的P0规范 +- **Reference Documents by Phase** 部分：列出所有文档 (包括强制必读的) +- 两个部分的文档可以重叠，但目的不同： + - Prerequisites：强调"必须先读" + - Reference：提供"完整导航" + +--- + +## 实现示例 + +### Sequential Skill 示例 + +```markdown +## ⚠️ Mandatory Prerequisites (强制前置条件) + +| Document | Purpose | When | +|----------|---------|------| +| [specs/issue-handling.md](specs/issue-handling.md) | Issue数据规范 | **执行前必读** | +| [specs/solution-schema.md](specs/solution-schema.md) | 解决方案结构 | **执行前必读** | + +--- + +## Reference Documents by Phase + +### 📋 Phase 1: Issue Collection +执行Phase 1时查阅的文档 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/actions/action-list.md](phases/actions/action-list.md) | Issue加载逻辑 | 理解如何收集issues | +| [specs/issue-handling.md](specs/issue-handling.md) | Issue数据规范 | 验证issue格式 ✅ **必读** | + +### ⚙️ Phase 2: Planning +执行Phase 2时查阅的文档 + +| Document | Purpose | When to Use | +|----------|---------|-------------| +| [phases/actions/action-plan.md](phases/actions/action-plan.md) | Planning流程 | 理解issue→solution转换 | +| [specs/solution-schema.md](specs/solution-schema.md) | 解决方案结构 | 验证solution JSON格式 ✅ **必读** | + +### 🔍 Debugging & Troubleshooting + +| Issue | Solution Document | +|-------|------------------| +| Phase 1失败 | [phases/actions/action-list.md](phases/actions/action-list.md) | +| Planning输出不符 | [phases/actions/action-plan.md](phases/actions/action-plan.md) + [specs/solution-schema.md](specs/solution-schema.md) | +| 数据验证失败 | [specs/issue-handling.md](specs/issue-handling.md) | + +### 📚 Reference & Background + +| Document | Purpose | Notes | +|----------|---------|-------| +| [../issue-plan.md](../../.codex/prompts/issue-plan.md) | 原始实现 | Planning Agent system prompt | +``` + +--- + +## 生成算法 + +```javascript +function generateReferenceDocuments(config) { + let result = '## Reference Documents by Phase\n\n'; + + // 为每个phase生成一个章节 + const phases = config.phases || config.actions || []; + + phases.forEach((phase, index) => { + const phaseNum = index + 1; + const emoji = getPhaseEmoji(phase.type); + const title = phase.display_name || phase.name; + + result += `### ${emoji} Phase ${phaseNum}: ${title}\n`; + result += `执行Phase ${phaseNum}时查阅的文档\n\n`; + + // 找出该phase相关的所有文档 + const docs = config.specs.filter(spec => + (spec.phases || []).includes(`phase-${phaseNum}`) || + matchesByName(spec.path, phase.name) + ); + + if (docs.length > 0) { + result += '| Document | Purpose | When to Use |\n'; + result += '|----------|---------|-------------|\n'; + docs.forEach(doc => { + const required = doc.phases && doc.phases[0] === `phase-${phaseNum}` ? ' ✅ **必读**' : ''; + result += `| [${doc.path}](${doc.path}) | ${doc.purpose} | ${doc.context}${required} |\n`; + }); + result += '\n'; + } + }); + + // 问题排查部分 + result += '### 🔍 Debugging & Troubleshooting\n\n'; + result += generateDebuggingTable(config); + + // 深度学习参考 + result += '### 📚 Reference & Background\n\n'; + result += generateReferenceTable(config); + + return result; +} +``` + +--- + +## 检查清单 + +生成skill的SKILL.md时，参考文档部分应满足： + +- [ ] 有明确的"## Reference Documents by Phase"标题 +- [ ] 每个Phase都有对应的章节 (用emoji标识) +- [ ] 每个文档条目包含"When to Use"列 +- [ ] 包含"🔍 Debugging & Troubleshooting"部分 +- [ ] 包含"📚 Reference & Background"部分 +- [ ] 强制必读文档用✅和**粗体**标记 +- [ ] Execution Flow部分中有"→ **查阅**: ..."指引 +- [ ] 避免过长的文档列表 (一个Phase最多5-8个文档) diff --git a/.claude/skills/skill-generator/templates/skill-md.md b/.claude/skills/skill-generator/templates/skill-md.md index a76bc270..dbeaf9ac 100644 --- a/.claude/skills/skill-generator/templates/skill-md.md +++ b/.claude/skills/skill-generator/templates/skill-md.md @@ -80,7 +80,9 @@ Bash(\`mkdir -p "\${workDir}"\`); {{output_structure}} \`\`\` -## Reference Documents +## Reference Documents by Phase + +> **重要**: 参考文档应按执行阶段组织，清晰标注使用时机和场景。避免平铺文档列表。 {{reference_table}} @@ -132,12 +134,12 @@ function generatePrerequisites(config) { const templates = config.templates || []; let result = '### 规范文档 (必读)\n\n'; - result += '| Document | Purpose | Priority |\n'; - result += '|----------|---------|----------|\n'; + result += '| Document | Purpose | When |\n'; + result += '|----------|---------|------|\n'; specs.forEach((spec, index) => { - const priority = index === 0 ? '**P0 - 最高**' : 'P1'; - result += `| [${spec.path}](${spec.path}) | ${spec.purpose} | ${priority} |\n`; + const when = index === 0 ? '**执行前必读**' : '执行前推荐'; + result += `| [${spec.path}](${spec.path}) | ${spec.purpose} | ${when} |\n`; }); if (templates.length > 0) { @@ -151,6 +153,80 @@ function generatePrerequisites(config) { return result; } + +// ⭐ 新增：生成分阶段参考文档指南 +function generateReferenceTable(config) { + const phases = config.phases || config.actions || []; + const specs = config.specs || []; + const templates = config.templates || []; + + let result = ''; + + // 为每个执行阶段生成文档导航 + phases.forEach((phase, index) => { + const phaseNum = index + 1; + const phaseEmoji = getPhaseEmoji(phase.type || 'default'); + const phaseTitle = phase.display_name || phase.name; + + result += `### ${phaseEmoji} Phase ${phaseNum}: ${phaseTitle}\n`; + result += `执行Phase ${phaseNum}时查阅的文档\n\n`; + + // 列出该阶段相关的文档 + const relatedDocs = filterDocsByPhase(specs, phase, index); + if (relatedDocs.length > 0) { + result += '| Document | Purpose | When to Use |\n'; + result += '|----------|---------|-------------|\n'; + relatedDocs.forEach(doc => { + result += `| [${doc.path}](${doc.path}) | ${doc.purpose} | ${doc.context || '查阅内容'} |\n`; + }); + result += '\n'; + } + }); + + // 问题排查部分 + result += '### 🔍 Debugging & Troubleshooting (问题排查)\n'; + result += '遇到问题时查阅的文档\n\n'; + result += '| Issue | Solution Document |\n'; + result += '|-------|-------------------|\n'; + result += `| Phase执行失败 | 查阅相应Phase的文档 |\n`; + result += `| 输出不符合预期 | [specs/quality-standards.md](specs/quality-standards.md) - 验证质量标准 |\n`; + result += '\n'; + + // 深度学习参考 + result += '### 📚 Reference & Background (深度学习)\n'; + result += '用于理解原始实现和设计决策\n\n'; + result += '| Document | Purpose | Notes |\n'; + result += '|----------|---------|-------|\n'; + templates.forEach(tmpl => { + result += `| [${tmpl.path}](${tmpl.path}) | ${tmpl.purpose} | 生成时参考 |\n`; + }); + + return result; +} + +// 辅助函数：获取Phase表情符号 +function getPhaseEmoji(phaseType) { + const emojiMap = { + 'discovery': '📋', + 'generation': '🔧', + 'analysis': '🔍', + 'implementation': '⚙️', + 'validation': '✅', + 'completion': '🏁', + 'default': '📌' + }; + return emojiMap[phaseType] || emojiMap['default']; +} + +// 辅助函数：根据Phase过滤文档 +function filterDocsByPhase(specs, phase, phaseIndex) { + // 简单过滤逻辑：匹配phase名称关键词 + const keywords = phase.name.toLowerCase().split('-'); + return specs.filter(spec => { + const specName = spec.path.toLowerCase(); + return keywords.some(kw => specName.includes(kw)); + }); +} ``` ## Sequential 模式示例 diff --git a/.codex/skills/codex-issue-plan-execute/README.md b/.codex/skills/codex-issue-plan-execute/README.md deleted file mode 100644 index 9ad53887..00000000 --- a/.codex/skills/codex-issue-plan-execute/README.md +++ /dev/null @@ -1,255 +0,0 @@ -# Codex Issue Plan-Execute Skill - -简化的 Codex issue 规划-执行工作流 Skill。 - -## 快速开始 - -### 安装 - -该 Skill 已经在 `~/.claude/skills/codex-issue-plan-execute/` 中生成。 - -### 使用方式 - -#### 方式 1：执行单个 issue - -```bash -codex -p "@.codex/prompts/codex-issue-plan-execute --issue ISS-001" -``` - -#### 方式 2：批量执行多个 issues - -```bash -codex -p "@.codex/prompts/codex-issue-plan-execute --issues ISS-001,ISS-002,ISS-003" -``` - -#### 方式 3：交互式选择 - -```bash -codex -p "@.codex/prompts/codex-issue-plan-execute" -# 系统会显示 issues 列表，你可以交互式选择 -``` - -#### 方式 4：恢复之前的执行 - -```bash -codex -p "@.codex/prompts/codex-issue-plan-execute --resume .workflow/.scratchpad/codex-issue-20250129-120000" -``` - -## 工作流程 - -``` -Initialize - ↓ -List Issues (显示所有 pending/planned issues) - ↓ -Plan Solutions (为选中的 issues 生成解决方案) - ↓ -Execute Solutions (按顺序执行解决方案) - ↓ -Complete (生成报告并完成) -``` - -### 每个阶段做什么 - -**Phase 1: Initialize** -- 创建工作目录 -- 初始化状态 JSON -- 准备执行环境 - -**Phase 2: List Issues** -- 从 ccw issue 加载 issues -- 显示当前状态矩阵 -- 收集用户的规划/执行选择 - -**Phase 3: Plan Solutions** -- 为每个 issue 生成规划 subagent -- 分析代码并设计解决方案 -- 绑定 solution 到 issue -- 更新 issue 状态 → "planned" - -**Phase 4: Execute Solutions** -- 加载已规划的解决方案 -- 执行所有 tasks（implement → test → verify） -- 一次性提交所有更改 -- 更新 solution 状态 → "completed" - -**Phase 5: Complete** -- 生成执行报告 -- 保存最终状态和统计信息 -- 输出完成摘要 - -## 目录结构 - -``` -codex-issue-plan-execute/ -├── SKILL.md # 入口文件（你已读） -├── phases/ -│ ├── orchestrator.md # Orchestrator 编排逻辑 -│ ├── state-schema.md # 状态结构定义 -│ └── actions/ -│ ├── action-init.md # 初始化 -│ ├── action-list.md # 列表显示 -│ ├── action-plan.md # 规划 -│ ├── action-execute.md # 执行 -│ └── action-complete.md # 完成 -├── specs/ -│ ├── issue-handling.md # Issue 处理规范 -│ ├── solution-schema.md # Solution 数据结构 -│ ├── quality-standards.md # 质量标准 -│ └── subagent-roles.md # Subagent 角色定义 -└── templates/ - └── (可选的 prompt 模板) -``` - -## 配置选项 - -### 命令行参数 - -| 参数 | 值 | 说明 | -|------|-----|------| -| `--issue` | ISS-ID | 执行单个 issue | -| `--issues` | ID1,ID2,ID3 | 执行多个 issues | -| `--resume` | path | 从快照恢复 | -| `--skip-plan` | - | 跳过规划阶段，直接执行 | -| `--skip-execute` | - | 仅规划，不执行 | - -## 关键特性 - -### ✓ 已实现 - -- [x] Autonomous 状态驱动编排 -- [x] 双 Agent 规划-执行分离 -- [x] 最小化队列（仅保留待执行项） -- [x] 批量 issue 处理 -- [x] 完整状态持久化 -- [x] 快照恢复能力 -- [x] 详细执行报告 - -### ⌛ 可选增强 - -- [ ] 并行规划（当前串行） -- [ ] 冲突检测和优先级排序 -- [ ] 自动重试失败项 -- [ ] WebUI 显示进度 -- [ ] Slack 通知 - -## 输出文件 - -执行完成后会在 `.workflow/.scratchpad/codex-issue-{timestamp}/` 生成： - -``` -state.json # 最终状态快照 -state-history.json # 状态变更历史 -queue.json # 执行队列 -execution-results.json # 执行结果汇总 -final-report.md # 最终报告 -solutions/ - ├── ISS-001-plan.json - ├── ISS-001-execution.json - ├── ISS-002-plan.json - └── ... -snapshots/ - ├── snapshot-before-plan.json - ├── snapshot-before-execute.json - └── ... -``` - -## 故障排除 - -### Issue 无法加载 - -```bash -# 检查 issues 是否存在 -ccw issue list --status registered - -# 手动创建 issue -ccw issue init ISS-001 --title "My Issue" -``` - -### 规划失败 - -- 检查 `~/.codex/agents/issue-plan-agent.md` 是否存在 -- 查看错误日志中的具体原因 -- 从快照恢复后重试 - -### 执行失败 - -- 检查测试是否通过：`npm test` -- 查看 acceptance criteria 是否满足 -- 从快照恢复：`codex ... --resume {snapshot_path}` - -### 状态不一致 - -- 删除旧的 state.json 重新开始 -- 或从最后一个有效快照恢复 - -## 性能指标 - -| 指标 | 预期值 | -|------|--------| -| 初始化 | < 1s | -| 列表加载 | < 2s | -| 单 issue 规划 | 30-60s | -| 单 issue 执行 | 1-5 min | -| 总处理时间（3 issues） | 5-20 min | - -## 系统要求 - -- Codex CLI >= 2.0 -- Node.js >= 14 -- Git 仓库已初始化 -- ccw issue 命令可用 - -## 贡献指南 - -### 修改 Action - -编辑 `phases/actions/action-*.md` 文件 - -### 修改规范 - -编辑 `specs/*.md` 文件 - -### 测试 Skill - -```bash -# 测试单个 issue -ccw codex issue:plan-execute --issue ISS-001 - -# 测试批量处理 -ccw codex issue:plan-execute --issues ISS-001,ISS-002 - -# 检查输出 -cat .workflow/.scratchpad/codex-issue-*/final-report.md -``` - -## 版本历史 - -- **v1.0** (2025-01-29) - - 初始发布 - - Autonomous 编排模式 - - 双 Agent 规划-执行分离 - - 简化队列管理 - -## 许可证 - -与 Claude Code 相同 - -## 支持 - -遇到问题？ - -1. 查看 [SKILL.md](SKILL.md) 了解架构 -2. 查看 `specs/` 下的规范文档 -3. 检查执行日志和快照 -4. 查看最终报告 `final-report.md` - ---- - -**Ready to use!** 🚀 - -开始你的第一个 issue 规划-执行工作流： - -```bash -codex -p "@.codex/prompts/codex-issue-plan-execute" -```