sillyspec 3.9.0 → 3.10.0

package/src/stages/plan.js

@@ -0,0 +1,354 @@
+import { existsSync, readFileSync } from 'fs'
+import path from 'path'
+
+export const definition = {
+  name: 'plan',
+  title: '实现计划',
+  description: '编写实现计划 — 按 Wave 分组，每个任务独立文档',
+  steps: null // 动态生成
+}
+
+// 固定前缀步骤
+export const fixedPrefix = [
+  {
+    name: '状态检查',
+    prompt: `检查当前状态，确认可以执行 plan。
+
+### 操作
+1. 运行 \`sillyspec progress show\`
+2. 确认 currentStage 为 "plan"
+
+### 输出
+当前状态摘要`,
+    outputHint: '状态摘要',
+    optional: false
+  },
+  {
+    name: '加载上下文',
+    prompt: `加载所有规范文件和代码库上下文。
+
+### 操作
+1. 读取 CODEBASE-OVERVIEW.md + 各子项目上下文
+2. 读取 proposal.md、design.md、requirements.md、tasks.md
+3. 读取 CONVENTIONS.md、ARCHITECTURE.md、STACK.md
+4. 读取 local.yaml 获取构建/测试命令
+
+### 输出
+已加载的文件清单`,
+    outputHint: '文件清单',
+    optional: false
+  },
+  {
+    name: '锚定确认',
+    prompt: `确认已读取的文件。
+
+### 操作
+列出已读取的文件，标注存在/不存在。
+
+### 输出
+文件加载确认清单`,
+    outputHint: '文件确认清单',
+    optional: false
+  },
+  {
+    name: '展开任务并分组',
+    prompt: `把 tasks.md 每个 checkbox 展开为任务描述，按 Wave 分组，产出 plan.md 总览。
+
+### plan.md 格式（轻量总览，PM 视角）
+\`\`\`markdown
+# 实现计划
+
+## Wave 1（并行，无依赖）
+- [ ] task-01: 添加用户创建接口
+- [ ] task-02: 添加角色创建接口
+
+## Wave 2（依赖 Wave 1）
+- [ ] task-03: 用户创建接口联调
+
+## 全局验收标准
+- [ ] 所有单元测试通过
+\`\`\`
+
+### 关键规则
+- plan.md 只放任务列表 + Wave 划分 + 全局验收标准，**不放实现细节**
+- 实现细节写到后续的 tasks/task-NN.md 中
+- 每个任务编号格式：task-01、task-02 ...
+
+### 批量模式指引
+如果 design.md 或需求中包含批量特征（关键词：批量/模板/引擎/N个相似），按以下原则规划：
+❌ 不要列出每个实例作为独立任务
+❌ 不要在文档中嵌入数据
+✅ 设计通用架构，Wave 1 聚焦架构
+✅ 数据转换用脚本完成，单独一个 Wave
+✅ 总任务数控制在 10 个以内
+
+### 操作
+1. 读取 tasks.md 获取任务列表
+2. 读取 design.md 获取文件变更清单
+3. 逐个展开为任务描述
+4. 分析依赖关系，按 Wave 分组
+5. 保存到 \`.sillyspec/changes/<变更名>/plan.md\`
+
+### 输出
+plan.md 总览内容`,
+    outputHint: 'plan.md 总览',
+    optional: false
+  },
+  {
+    name: '自检总览',
+    prompt: `自检 plan.md 总览质量。
+
+### 操作
+检查以下各项：
+- [ ] 每个 task 有编号（task-01、task-02 ...）
+- [ ] 每个 task 有 checkbox
+- [ ] 已标注 Wave 分组和依赖关系
+- [ ] 有全局验收标准
+- [ ] 没有实现细节（接口定义、代码示例等不应该在 plan.md 里）
+- [ ] plan.md 与 design.md 的文件变更清单一致
+
+### 输出
+自检通过/不通过`,
+    outputHint: '自检结果',
+    optional: false
+  }
+]
+
+// 固定后缀步骤
+export const fixedSuffix = [
+  {
+    name: '审查一致性',
+    prompt: `审查所有 task-N.md 的一致性。
+
+### 操作
+1. 读取所有 tasks/task-NN.md
+2. 检查：
+   - 文件路径有没有冲突（两个任务改同一个文件）
+   - 依赖关系和 plan.md 的 Wave 分组是否一致
+   - 验收标准和 plan.md 的全局标准是否矛盾
+   - 接口定义是否自洽
+3. 发现问题 → 列出问题清单，暂停等用户决定是否修复
+
+### 输出
+一致性审查结果`,
+    outputHint: '审查结果',
+    optional: false
+  },
+  {
+    name: '保存并更新进度',
+    prompt: `确认所有文件已保存，更新进度。
+
+### 操作
+1. 确认 plan.md 和所有 tasks/task-NN.md 已存在
+2. \`git add .sillyspec/\` — **不要 commit**
+
+### 输出
+文件列表 + 下一步命令`,
+    outputHint: '文件列表',
+    optional: false
+  }
+]
+
+/**
+ * 解析 plan.md 获取任务数量
+ */
+function parseTaskCount(planContent) {
+  if (!planContent || typeof planContent !== 'string') return 0
+  const matches = planContent.match(/^[-*]\s*\[[ x]\]\s*task-\d+/gm)
+  return matches ? matches.length : 0
+}
+
+/**
+ * 生成单个任务的蓝图写作 prompt
+ */
+function buildTaskPrompt(taskNum, taskName, changeDir) {
+  return `编写任务蓝图 tasks/task-${String(taskNum).padStart(2, '0')}.md
+
+### 任务
+${taskName}
+
+### 文件路径
+\`.sillyspec/changes/<变更名>/tasks/task-${String(taskNum).padStart(2, '0')}.md\`
+
+### 格式要求（必须严格遵守）
+\`\`\`markdown
+# task-${String(taskNum).padStart(2, '0')}: ${taskName}
+
+## 修改文件
+- 具体文件路径列表
+
+## 实现要求
+1. 具体做什么，写清楚
+2. ...
+
+## 接口定义
+（代码类任务必填，写方法签名、数据结构）
+
+## 边界处理
+- 异常场景列表
+
+## 参考
+- 已有代码可参考的模式
+- 相关的 CONVENTIONS.md 条目
+
+## TDD 步骤
+1. 写测试 ...
+2. 运行 <test-cmd> 确认失败
+3. 写代码 ...
+4. 运行 <test-cmd> 确认通过
+（纯配置/文档类任务简化为：1. 实现 2. 验证）
+
+## 验收标准
+- [ ] 具体可测试的验收条件
+\`\`\`
+
+### 关键规则
+- task-N.md 必须独立完整，execute 子代理只读这一个文件就能干活
+- 不要依赖其他 task-N.md 的内容
+- 接口定义写到"搬砖工照着做"的程度
+- 写完后保存到文件
+
+### 操作
+1. 读取 design.md 和 plan.md 了解上下文
+2. 读取相关源文件了解现有代码
+3. 编写任务蓝图
+4. 保存到 tasks/task-${String(taskNum).padStart(2, '0')}.md
+
+### 输出
+任务蓝图内容摘要`
+}
+
+/**
+ * 构建任务蓝图协调器步骤（单步，子代理并行写蓝图）
+ */
+export function buildCoordinatorStep(changeDir, taskNames) {
+  const taskList = taskNames.map((name, i) => {
+    const num = String(i + 1).padStart(2, '0')
+    return `- task-${num}: ${name}`
+  }).join('\n')
+
+  const subagentPrompts = taskNames.map((name, i) => {
+    const num = String(i + 1).padStart(2, '0')
+    return `\`\`\`
+任务编号：task-${num}
+任务名称：${name}
+文件路径：${changeDir}/tasks/task-${num}.md
+
+操作：
+1. 读取 ${changeDir}/design.md 和 ${changeDir}/plan.md 了解上下文
+2. 读取相关源文件了解现有代码
+3. 按以下格式编写任务蓝图并保存到 ${changeDir}/tasks/task-${num}.md：
+
+# task-${num}: ${name}
+
+## 修改文件
+- 文件路径列表
+
+## 实现要求
+1. 具体做什么
+
+## 接口定义
+（代码类任务必填）
+
+## 边界处理
+- 异常场景
+
+## 参考
+- 可参考的模式
+
+## TDD 步骤
+1. 写测试 → 2. 确认失败 → 3. 写代码 → 4. 确认通过
+
+## 验收标准
+- [ ] 具体可测试的条件
+
+关键规则：
+- 必须独立完整，execute 子代理只读这一个文件就能干活
+- 不要依赖其他 task-N.md 的内容
+- 接口定义写到"搬砖工照着做"的程度
+- 写完后用 Write tool 保存到文件
+\`\`\``
+  }).join('\n\n')
+
+  return {
+    name: '生成任务蓝图（子代理并行）',
+    prompt: `为 plan.md 中的每个任务生成独立蓝图文件。
+
+## 任务清单
+${taskList}
+
+## 执行方式（必须严格遵守）
+
+**你必须使用 Agent tool 启动子代理来写每个蓝图，不要自己写。**
+
+1. 确认 \`${changeDir}/tasks/\` 目录存在（不存在则创建）
+2. 为每个任务启动一个独立子代理（Agent tool），可并行启动多个
+3. 每个子代理使用对应的 prompt（见下方模板）
+4. 等待所有子代理完成
+5. 验证每个 task-N.md 文件已生成且非空
+
+### 子代理 prompt 模板
+为每个任务使用以下 prompt 启动子代理：
+
+${subagentPrompts}
+
+## 验收
+- 每个 task-N.md 文件存在且非空
+- 包含所有必要章节：修改文件、实现要求、接口定义、边界处理、TDD 步骤、验收标准`,
+    outputHint: '蓝图生成结果',
+    optional: false
+  }
+}
+
+/**
+ * 从 plan.md 解析任务名列表
+ */
+function parseTaskNames(planContent) {
+  const names = []
+  const lines = planContent.split('\n')
+  for (const line of lines) {
+    const m = line.match(/^[-*]\s*\[[ x]\]\s*task-\d+:\s*(.+)/i)
+    if (m) names.push(m[1].trim())
+  }
+  return names
+}
+
+/**
+ * 动态构建 plan 步骤列表
+ * @param {string|null} changeDir - 变更目录路径
+ * @param {string|null} planContent - plan.md 内容（可选，用于解析任务数）
+ * @returns {Array} 步骤列表
+ */
+export function buildPlanSteps(changeDir = null, planContent = null) {
+  let taskCount = 0
+
+  // 尝试从 plan.md 解析任务数
+  if (planContent) {
+    taskCount = parseTaskCount(planContent)
+  } else if (changeDir) {
+    const planFile = path.join(changeDir, 'plan.md')
+    if (existsSync(planFile)) {
+      taskCount = parseTaskCount(readFileSync(planFile, 'utf8'))
+    }
+  }
+
+  // 没有任务数则用固定步骤（兼容旧流程）
+  if (taskCount === 0) {
+    return [...fixedPrefix, ...fixedSuffix]
+  }
+
+  // 解析任务名
+  let taskNames = []
+  if (planContent) {
+    taskNames = parseTaskNames(planContent)
+  } else if (changeDir) {
+    const planFile = path.join(changeDir, 'plan.md')
+    if (existsSync(planFile)) {
+      taskNames = parseTaskNames(readFileSync(planFile, 'utf8'))
+    }
+  }
+
+  // 生成单个协调器步骤（子代理并行写蓝图）
+  const coordinatorStep = buildCoordinatorStep(changeDir, taskNames)
+  return [...fixedPrefix, coordinatorStep, ...fixedSuffix]
+}

package/src/stages/propose.js

@@ -0,0 +1,115 @@
+export const definition = {
+  name: 'propose',
+  title: '方案设计',
+  description: '生成结构化规范 — proposal + design + tasks',
+  steps: [
+    {
+      name: '状态检查',
+      prompt: `检查当前状态，确认可以执行 propose。
+
+### 操作
+1. 运行 \`sillyspec progress show\`
+2. 确认 currentStage 为 "propose"
+3. 如果没有设计文档 → 提示先运行 brainstorm
+
+### 输出
+当前状态摘要`,
+      outputHint: '状态摘要',
+      optional: false
+    },
+    {
+      name: '加载上下文',
+      prompt: `加载所有相关规范和代码库上下文。
+
+### 操作
+1. 加载 CODEBASE-OVERVIEW.md 和子项目上下文
+2. 读取最新设计文档、需求文档、代码库约定
+3. 如果是子阶段变更，读取 MASTER.md 和前序阶段设计
+
+### 输出
+已加载的文件列表`,
+      outputHint: '文件列表',
+      optional: false
+    },
+    {
+      name: '锚定确认',
+      prompt: `确认已读取的文件。
+
+### 操作
+1. 列出已读取的文件，标注存在/不存在
+2. 格式：\`[x] 文件名 — 说明\` 或 \`[ ] 文件名 — 不存在（正常）\`
+
+### 输出
+文件加载确认清单
+
+### 注意
+- 文件不存在不是错误，正常标注即可`,
+      outputHint: '文件确认清单',
+      optional: false
+    },
+    {
+      name: '探索现有代码',
+      prompt: `理解相关模块的当前实现，识别影响范围。
+
+### 操作
+1. 根据设计文档中的文件变更清单，读取相关源码
+2. 识别现有接口、方法签名、数据结构
+3. 记录可能受影响的模块
+
+### 输出
+影响范围分析（涉及模块、需修改的文件、风险点）`,
+      outputHint: '影响范围分析',
+      optional: false
+    },
+    {
+      name: '生成规范文件',
+      prompt: `在 \`.sillyspec/changes/<变更名>/\` 下生成四个文件。
+
+### 操作
+1. 生成 proposal.md：动机、变更范围、不在范围内、成功标准
+2. 生成 requirements.md：功能需求、用户场景（Given/When/Then）、非功能需求
+3. 生成 design.md：架构决策、文件变更清单、数据模型、API 设计、代码风格参照
+4. 生成 tasks.md：任务列表（只列名称，不展开步骤）
+
+### 输出
+四个文件路径
+
+### 注意
+- 表名/字段名必须来自真实 schema 或标注"新增"
+- 用户场景必须用 Given/When/Then 格式
+- tasks.md 只列任务名，细节在 plan 阶段展开`,
+      outputHint: '四个文件路径',
+      optional: false
+    },
+    {
+      name: '自检门控',
+      prompt: `自检生成的规范文件。
+
+### 操作
+检查以下各项：
+- [ ] proposal.md 有动机、变更范围、不在范围内、成功标准
+- [ ] design.md 有文件变更清单表格
+- [ ] requirements.md 有 Given/When/Then 用户场景
+- [ ] tasks.md 每个 task 有文件路径
+
+任何不通过 → 修正后重新检查。
+
+### 输出
+自检通过/不通过`,
+      outputHint: '自检结果',
+      optional: false
+    },
+    {
+      name: '展示并更新进度',
+      prompt: `展示规范给用户，更新进度。
+
+### 操作
+1. 展示 proposal.md 和 design.md 摘要
+
+### 输出
+展示结果 + 下一步命令`,
+      outputHint: '展示结果',
+      optional: false
+    }
+  ]
+}

package/src/stages/quick.js

@@ -0,0 +1,64 @@
+export const definition = {
+  name: 'quick',
+  title: '快速任务',
+  description: '跳过完整流程，直接做',
+  auxiliary: true,
+  steps: [
+    {
+      name: '理解任务',
+      prompt: `解析任务参数，加载项目上下文。
+
+### 操作
+1. 检查是否携带 \`--change <变更名>\`，确定记录方式
+2. 理解任务：模糊则问一个问题确认
+3. 加载项目信息：\`cat .sillyspec/projects/*.yaml 2>/dev/null\`（了解项目结构和技术栈）
+4. 加载上下文：\`cat .sillyspec/docs/<project>/scan/CONVENTIONS.md 2>/dev/null\`
+5. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`（构建命令、测试命令、环境变量等）
+6. 如有 \`--change\`，加载设计文档：\`cat .sillyspec/changes/<变更名>/design.md 2>/dev/null\`（理解设计意图）
+7. 如有需要，查询知识库：\`cat .sillyspec/knowledge/INDEX.md 2>/dev/null\`
+
+### 输出
+任务理解 + 上下文摘要`,
+      outputHint: '任务理解',
+      optional: false
+    },
+    {
+      name: '实现并验证',
+      prompt: `实现任务。
+
+### 操作
+1. 先读后写：调用已有方法前 \`cat\` 源文件确认签名，\`grep\` 确认方法存在
+2. 写代码完成任务
+3. 如涉及逻辑变更，建议写单元测试验证（不强制，纯配置/文档/小改动可跳过）
+4. **不要编译！** 除非用户明确要求或改动量很大
+
+### 输出
+实现摘要 + 修改文件列表
+
+### 铁律
+- 不要修改无关文件
+- 不要编造不存在的 CLI 子命令
+- **Reverse Sync**：如果发现 Bug 是 design.md 遗漏导致的，先修 design.md 再修代码`,
+      outputHint: '实现摘要',
+      optional: false
+    },
+    {
+      name: '暂存和记录',
+      prompt: `Git 暂存并记录任务。
+
+### 操作
+1. \`git add -A\` — **不要 commit**，由用户通过统一提交
+2. 记录：
+   - 有 \`--change\`：在 \`.sillyspec/changes/<变更名>/tasks.md\` 追加 task 并勾选，记录精确到秒的时间戳
+   - 无 \`--change\`：记录到 \`.sillyspec/quicklog/QUICKLOG-<git用户名>.md\`（按 git 用户名隔离）
+3. QUICKLOG 轮转：超过 500 行则重命名为 \`QUICKLOG-<USER>-YYYY-MM-DD.md\`
+4. 如果发现项目特有的坑，追加到 \`.sillyspec/knowledge/uncategorized.md\`
+5. 任务比预期复杂 → 建议用完整流程
+
+### 输出
+暂存确认 + 记录路径`,
+      outputHint: '暂存和记录确认',
+      optional: false
+    }
+  ]
+}

package/src/stages/scan.js

@@ -0,0 +1,141 @@
+export const definition = {
+  name: 'scan',
+  title: '代码扫描',
+  description: '分析项目结构、约定和架构',
+  auxiliary: true,
+  steps: [
+    {
+      name: '检查已有扫描文档和子项目列表',
+      prompt: `检查已有扫描文档和子项目列表。
+
+### 操作
+1. \`ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .\` — 检查已有文档
+1. \`ls .sillyspec/docs/*/scan/ 2>/dev/null\` — 检查已有文档
+2. \`wc -l .sillyspec/docs/*/scan/*.md 2>/dev/null\` — 文档行数
+3. 已有 3 份 → 建议升级深度扫描；已有 7 份 → 建议刷新或跳过
+5. 显示子项目列表供选择扫描范围
+
+### 输出
+已有文档状态 + 扫描建议`,
+      outputHint: '工作区和文档状态',
+      optional: false
+    },
+    {
+      name: '构建环境探测',
+      prompt: `探测项目的构建环境和依赖。
+
+### 操作
+1. \`cat package.json pom.xml build.gradle go.mod Cargo.toml requirements.txt pyproject.toml Gemfile composer.json 2>/dev/null\`
+2. \`find . -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null\`
+3. 结果保存到 \`.sillyspec/docs/<project>/scan/_env-detect.md\`（临时文件，扫描完删除）
+
+### 输出
+环境探测结果摘要`,
+      outputHint: '环境探测摘要',
+      optional: false
+    },
+    {
+      name: '断点续扫检测',
+      prompt: `检测已有扫描文档，只生成缺失的。
+
+### 操作
+1. \`PROJECT=$(python3 -c "import sys,json; print(json.load(open('.sillyspec/.runtime/progress.json')).get('project',''))" 2>/dev/null || basename "$(pwd)")\`
+2. 检查 7 份文档是否存在：ARCHITECTURE、STRUCTURE、CONVENTIONS、INTEGRATIONS、TESTING、CONCERNS、PROJECT
+3. 列出已有 ✅ 和缺失 ⬜
+4. 只生成缺失的文档
+
+### 输出
+已有/缺失文档列表`,
+      outputHint: '断点续扫状态',
+      optional: false
+    },
+    {
+      name: '深度扫描 — 技术架构',
+      prompt: `扫描技术栈 + 数据库 Schema + 架构模式。参考 _env-detect.md。
+
+### 操作
+1. 用 grep/rg 搜索（\`@Entity\`、\`schema.prisma\`、\`models.py\` 等），**禁止读源码全文**
+2. Schema 只记表名+说明+字段数
+3. 写入 \`.sillyspec/docs/<project>/scan/ARCHITECTURE.md\`
+4. 包含 \`## 技术栈\` \`## 架构概览\` \`## 数据模型（摘要）\`
+
+### 输出
+ARCHITECTURE.md 路径
+
+### 注意
+- 路径用反引号，不编造`,
+      outputHint: 'ARCHITECTURE.md 路径',
+      optional: false
+    },
+    {
+      name: '深度扫描 — 代码约定',
+      prompt: `扫描框架隐形规则 + 实体继承 + 代码风格。参考 _env-detect.md。
+
+### 操作
+1. 用 grep 搜索拦截器/插件/逻辑删除/基类/审计字段，**禁止读源码全文**
+2. 根据检测到的语言/框架自行决定搜索什么模式
+3. 提取 3-5 个典型示例
+4. 写入 \`.sillyspec/docs/<project>/scan/CONVENTIONS.md\`
+5. 包含 \`## 框架隐形规则\` \`## 实体继承规范\` \`## 代码风格\`
+
+### 输出
+CONVENTIONS.md 路径
+
+### 注意
+- 路径用反引号，不编造`,
+      outputHint: 'CONVENTIONS.md 路径',
+      optional: false
+    },
+    {
+      name: '深度扫描 — 目录结构和集成',
+      prompt: `扫描目录结构 + 外部集成。参考 _env-detect.md。
+
+### 操作
+1. 用 find/ls/tree 和 grep，**禁止读源码全文**
+2. 搜索 API 调用、MQ 配置、缓存、第三方 SDK
+3. 写入 \`.sillyspec/docs/<project>/scan/STRUCTURE.md\`（目录树+模块说明）
+4. 写入 \`.sillyspec/docs/<project>/scan/INTEGRATIONS.md\`（按类型分组）
+
+### 输出
+STRUCTURE.md 和 INTEGRATIONS.md 路径
+
+### 注意
+- 路径用反引号，不编造`,
+      outputHint: 'STRUCTURE.md + INTEGRATIONS.md 路径',
+      optional: false
+    },
+    {
+      name: '深度扫描 — 测试和债务',
+      prompt: `扫描测试现状 + 技术债务 + 项目概览。参考 _env-detect.md。
+
+### 操作
+1. 用 grep 搜索测试文件、TODO/FIXME、过时依赖，**禁止读源码全文**
+2. 写入 \`.sillyspec/docs/<project>/scan/TESTING.md\`（测试结构）
+3. 写入 \`.sillyspec/docs/<project>/scan/CONCERNS.md\`（按严重程度分组）
+4. 写入 \`.sillyspec/docs/<project>/scan/PROJECT.md\`（项目信息）
+
+### 输出
+TESTING.md、CONCERNS.md、PROJECT.md 路径`,
+      outputHint: '三份文档路径',
+      optional: false
+    },
+    {
+      name: '自检和提交',
+      prompt: `验证扫描完整性，清理并提交。
+
+### 操作
+1. 检查 7 份文档是否全部生成
+2. 自检门控：ARCHITECTURE（技术栈+Schema摘要）、CONVENTIONS（隐形规则+代码风格）、STRUCTURE（目录结构）、INTEGRATIONS（外部依赖）、TESTING（测试现状）、CONCERNS（技术债务）、PROJECT（项目概览）
+3. 清理：\`rm -f .sillyspec/docs/<project>/scan/_env-detect.md\`
+4. \`git add .\` — **不要 commit**，由用户通过统一提交工具处理
+
+### 输出
+扫描完整性报告
+
+### 注意
+- ❌ 修改代码 / 编造路径 / 读源码全文`,
+      outputHint: '自检报告',
+      optional: false
+    }
+  ]
+}