sillyspec 3.8.7 → 3.9.0

package/dist/steps/scan/01-env-detect.md

@@ -0,0 +1,51 @@
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+你现在是 SillySpec 代码库扫描器（编排器）。**你不读源码，只编排子代理或串行执行。**
+
+## 绝对规则
+- ❌ 修改代码 / 编造路径 / 主代理读源码全文
+- ✅ 交互模式每步等用户 / 文档只写 `.sillyspec/docs/<project>/scan/`
+
+## 参数处理
+- 空白 → 交互式引导（逐步询问）
+- `--deep` → 直接深度扫描
+- 其他 → 快速扫描该区域
+
+## 交互式引导（参数为空时）
+
+### 检查工作区 & 已有文档
+
+```bash
+ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .   # 有子项目配置 → 工作区模式
+ls .sillyspec/docs/<project>/scan/ 2>/dev/null       # 检查已有文档
+wc -l .sillyspec/docs/<project>/scan/*.md 2>/dev/null
+```
+
+- 已有 3 份 → 建议升级深度扫描
+- 已有 7 份 → 建议刷新或跳过
+- 工作区 → 逐个扫描 / 选子项目 / 退出
+
+### 选择扫描模式、范围、排除目录、确认
+按原流程交互，确认后进入扫描。
+
+## 构建环境探测（主代理执行）
+
+```bash
+cat package.json pom.xml build.gradle go.mod Cargo.toml requirements.txt pyproject.toml Gemfile composer.json 2>/dev/null
+find . -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null
+```
+
+结果保存到 `.sillyspec/docs/<project>/scan/_env-detect.md`（临时文件，扫描完删除）。
+
+## 断点续扫
+
+```bash
+for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT; do
+  [ -f ".sillyspec/docs/<project>/scan/${f}.md" ] && echo "✅ ${f}.md" || echo "⬜ ${f}.md"
+done
+```
+
+只生成缺失的文档。
+
+## 子代理可用性检测
+检查是否有 Task/Spawn 工具。有 → 子代理模式，无 → 串行模式。

package/dist/steps/scan/02-tech-stack.md

@@ -0,0 +1,16 @@
+扫描技术栈 + 数据库 Schema + 架构模式，生成 `ARCHITECTURE.md`。
+
+参考 `.sillyspec/docs/<project>/scan/_env-detect.md`。
+
+用 grep/rg 搜索（`@Entity`、`schema.prisma`、`models.py` 等），**禁止读源码全文**。
+
+Schema 只记表名+说明+字段数。
+
+输出文件必须包含以下章节：
+- `## 技术栈`
+- `## 架构概览`
+- `## 数据模型（摘要）`
+
+路径用反引号，不编造。保存到 `.sillyspec/docs/<project>/scan/ARCHITECTURE.md`。
+
+完成后立即写文件，下一个 area 开始前清除源码上下文。

package/dist/steps/scan/03-conventions.md

@@ -0,0 +1,16 @@
+扫描框架隐形规则 + 实体继承 + 代码风格，生成 `CONVENTIONS.md`。
+
+参考 `.sillyspec/docs/<project>/scan/_env-detect.md`。
+
+用 grep 搜索拦截器/插件/逻辑删除/基类/审计字段，**禁止读源码全文**。
+
+根据检测到的语言/框架自行决定搜索什么模式，提取 3-5 个典型示例。
+
+输出文件必须包含以下章节：
+- `## 框架隐形规则`
+- `## 实体继承规范`
+- `## 代码风格`
+
+路径用反引号，不编造。保存到 `.sillyspec/docs/<project>/scan/CONVENTIONS.md`。
+
+完成后立即写文件，下一个 area 开始前清除源码上下文。

package/dist/steps/scan/04-structure.md

@@ -0,0 +1,19 @@
+扫描目录结构 + 外部集成，生成 `STRUCTURE.md` 和 `INTEGRATIONS.md`。
+
+参考 `.sillyspec/docs/<project>/scan/_env-detect.md`。
+
+用 find/ls/tree 和 grep，**禁止读源码全文**。
+
+搜索 API 调用、MQ 配置、缓存、第三方 SDK。
+
+**STRUCTURE.md** 必须包含：
+- 目录树（用 tree 或 find 生成）
+- 模块说明
+
+**INTEGRATIONS.md** 按类型分组（数据库、缓存、MQ、第三方 API 等）。
+
+路径用反引号，不编造。分别保存到：
+- `.sillyspec/docs/<project>/scan/STRUCTURE.md`
+- `.sillyspec/docs/<project>/scan/INTEGRATIONS.md`
+
+完成后立即写文件，下一个 area 开始前清除源码上下文。

package/dist/steps/scan/05-quality.md

@@ -0,0 +1,18 @@
+扫描测试现状 + 技术债务 + 项目概览，生成 `TESTING.md`、`CONCERNS.md`、`PROJECT.md`。
+
+参考 `.sillyspec/docs/<project>/scan/_env-detect.md`。
+
+用 grep 搜索测试文件、TODO/FIXME、过时依赖，**禁止读源码全文**。
+
+**TESTING.md** 必须包含测试结构（框架、目录、覆盖情况）。
+
+**CONCERNS.md** 按严重程度分组（🔴 必须 / 🟡 建议 / 🔵 优化）。
+
+**PROJECT.md** 包含项目基本信息。
+
+路径用反引号，不编造。分别保存到：
+- `.sillyspec/docs/<project>/scan/TESTING.md`
+- `.sillyspec/docs/<project>/scan/CONCERNS.md`
+- `.sillyspec/docs/<project>/scan/PROJECT.md`
+
+

package/dist/steps/scan/06-complete.md

@@ -0,0 +1,49 @@
+## 扫描完成
+
+```bash
+# 路径校验
+for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT; do
+  [ -f ".sillyspec/docs/<project>/scan/${f}.md" ] && echo "✅ ${f}.md"
+done
+
+# 生成知识库骨架
+mkdir -p .sillyspec/knowledge
+if [ ! -f ".sillyspec/knowledge/INDEX.md" ]; then
+  cat > .sillyspec/knowledge/INDEX.md << 'EOF'
+# Knowledge Index
+
+> 子代理任务开始前查询此文件，按关键词匹配，只读命中的知识文件。
+> execute/quick 执行中发现的坑自动追加到 uncategorized.md，经用户确认后归类到对应文件。
+
+<!-- 格式：关键词1|关键词2|关键词3 → 文件路径 -->
+EOF
+fi
+if [ ! -f ".sillyspec/knowledge/uncategorized.md" ]; then
+  cat > .sillyspec/knowledge/uncategorized.md << 'EOF'
+# 未分类知识
+
+> execute/quick 执行中发现的坑暂存于此，用户审阅后归类到对应文件并更新 INDEX.md。
+EOF
+fi
+
+# 记录状态
+cat > .sillyspec/STATE.md << 'EOF'
+# 项目状态
+
+## 最近活动
+- $(date '+%Y-%m-%d %H:%M:%S') scan 完成
+EOF
+
+# 清理
+rm -f .sillyspec/docs/<project>/scan/_env-detect.md
+git add .sillyspec/
+```
+
+### 自检门控
+- [ ] ARCHITECTURE.md：技术栈 + Schema 摘要？
+- [ ] CONVENTIONS.md：隐形规则 + 代码风格？
+- [ ] STRUCTURE.md：目录结构？
+- [ ] INTEGRATIONS.md：外部依赖？
+- [ ] TESTING.md：测试现状？
+- [ ] CONCERNS.md：技术债务？
+- [ ] PROJECT.md：项目概览？

package/dist/steps/scan/manifest.yaml

@@ -0,0 +1,16 @@
+phase: scan
+description: 项目代码库扫描
+requires: []
+steps:
+  - file: 01-env-detect.md
+    name: 环境探测
+  - file: 02-tech-stack.md
+    name: 技术栈识别
+  - file: 03-conventions.md
+    name: 代码风格提取
+  - file: 04-structure.md
+    name: 项目结构分析
+  - file: 05-quality.md
+    name: 质量评估
+  - file: 06-complete.md
+    name: 扫描完成

package/dist/steps/verify/01-load-specs.md

@@ -0,0 +1,28 @@
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+## 核心约束（必须遵守）
+- ❌ 修改任何代码（只做检查和报告）
+- ❌ 自行推进到下一阶段
+
+## 加载规范
+
+```bash
+# 确定变更目录
+if [ -n "$ARGUMENTS" ]; then
+  CHANGE_DIR=".sillyspec/changes/$ARGUMENTS"
+else
+  CHANGE_DIR=$(ls -d .sillyspec/changes/*/ 2>/dev/null | grep -v archive | tail -1)
+fi
+cat "$CHANGE_DIR"/{design,tasks}.md 2>/dev/null
+cat .sillyspec/local.yaml 2>/dev/null
+```
+
+锚定确认实际存在的文件。
+
+## 工作区模式处理
+
+如果 `.sillyspec/projects/` 目录下有 yaml 文件：
+1. 检查工作区根目录 `.sillyspec/changes/` 下的未归档变更
+2. 检查每个子项目 `<子项目路径>/.sillyspec/changes/` 下的未归档变更
+3. 列出所有未归档变更，让用户选择要验证哪个
+4. 根据 $ARGUMENTS 或用户选择，cd 到对应目录执行验证

package/dist/steps/verify/02-check-tasks.md

@@ -0,0 +1 @@
+逐项检查 tasks.md，对每个 checkbox 报告：✅ 已完成 / ❌ 未完成 / ⚠️ 部分完成

package/dist/steps/verify/03-check-design.md

@@ -0,0 +1,6 @@
+对照 design.md 检查：
+
+- 架构决策是否落实？
+- 文件变更是否一致？
+- 数据模型是否正确？
+- API 设计是否符合预期？

package/dist/steps/verify/04-run-tests.md

@@ -0,0 +1,7 @@
+运行单元测试：
+
+```bash
+pnpm test 2>/dev/null || npm test 2>/dev/null || pytest 2>/dev/null || go test ./... 2>/dev/null
+```
+
+报告测试结果（通过/失败数量）。

package/dist/steps/verify/05-e2e-tests.md

@@ -0,0 +1,27 @@
+检测项目中是否有 E2E 测试或测试步骤文件：
+```bash
+ls tests/e2e/ e2e/ cypress/e2e/ 2>/dev/null | head -5
+cat .sillyspec/changes/*/e2e-steps.md 2>/dev/null | head -5
+```
+
+**无任何测试** → 跳过此步骤。
+
+**有测试** → 确认修复策略（AskUserQuestion）：
+1. 自动修复，同一用例最多 5 次（超过停止，提示人工介入）
+2. 一直修复直到全绿
+3. 只报告，不自动修复
+
+**按优先级执行：**
+
+**优先级 1：专业 E2E 框架（Playwright/Cypress）**
+```bash
+npx playwright test 2>/dev/null || npx cypress run 2>/dev/null
+```
+
+**优先级 2：通用测试框架（jest/vitest）**
+```bash
+npx vitest run 2>/dev/null || npx jest 2>/dev/null
+```
+
+**优先级 3：浏览器 MCP + e2e-steps.md（兜底）**
+读取 `.sillyspec/changes/<变更名>/e2e-steps.md`，按步骤逐条执行。每条标注 ✅/❌。

package/dist/steps/verify/05b-e2e-fix.md

@@ -0,0 +1,33 @@
+**自动修复循环（选了策略 1 或 2 时）：**
+
+```
+ROUND = 1
+MAX_ROUNDS = 策略1时为5，策略2时为50
+
+while ROUND <= MAX_ROUNDS:
+    1. 运行失败测试，捕获完整输出
+    2. 全部通过 → 跳出循环，标记 ✅
+    3. 对每个失败测试：
+       a. fixAttempts >= MAX_ROUNDS → 跳过，标记 ❌ MAX_REACHED
+       b. 否则 → 调用修复工具，prompt 必须包含失败测试路径、测试名、完整错误信息、相关源文件路径
+       c. 修复后重跑确认
+       d. 通过 → fixAttempts 不变；仍失败 → fixAttempts + 1
+    4. 写入 .sillyspec/local.yaml
+    5. ROUND++
+    6. 本轮无任何修复 → 跳出循环
+```
+
+**禁止行为：**
+- ❌ 只看错误摘要就修复（必须看完整输出）
+- ❌ 跳过 fixAttempts 计数
+- ❌ 一次修复多个不相关的失败（逐个修复，每次修复后重跑确认）
+- ❌ 直接修改代码（verify 阶段禁止改代码）
+
+**更新测试结果到 `.sillyspec/local.yaml`：**
+```yaml
+e2e:
+  {变更名}:
+    {测试文件名}:
+      status: passed/failed
+      fixAttempts: 0
+```

package/dist/steps/verify/06-code-quality.md

@@ -0,0 +1,25 @@
+代码质量扫描：
+
+```bash
+grep -r "TODO\|FIXME\|HACK\|XXX" src/ lib/ app/ --include="*.ts" --include="*.tsx" --include="*.py" --include="*.js" 2>/dev/null | head -20
+```
+
+审查 design.md「文件变更」中列出的文件：
+- 安全问题（输入校验、SQL拼接、硬编码敏感信息）
+- 潜在 bug（空值、边界条件）
+- 与 `.sillyspec/docs/<project>/scan/CONVENTIONS.md` 一致性
+
+每个问题标 🔴必须 / 🟡建议 / 🔵优化。
+
+## MCP 基础设施验证
+
+检查当前可用工具列表中是否存在以下 MCP 工具：
+- 数据库相关工具（postgres/sqlite/mysql/redis）
+- 浏览器相关工具（browser/chrome/puppeteer/playwright/devtools）
+- 搜索相关工具（search/web_search）
+
+**数据库 MCP：** 对照 design.md 验证表/集合、字段类型、约束。⚠️ 只执行 SELECT 查询。
+
+**浏览器 MCP：** 验证页面加载、UI 元素、基础交互。
+
+**无 MCP → 跳过此部分。**

package/dist/steps/verify/07-lint-check.md

@@ -0,0 +1,27 @@
+Lint / Format 检查：
+
+```bash
+# ESLint
+if [ -f .eslintrc -o -f .eslintrc.js -o -f .eslintrc.cjs -o -f .eslintrc.json -o -f .eslintrc.yml ] || grep -q '"eslint"' package.json 2>/dev/null; then
+  npx eslint . --max-warnings 0 2>&1 | tail -50
+fi
+
+# Prettier（检查而非修复）
+if [ -f .prettierrc -o -f .prettierrc.js -o -f .prettierrc.json -o -f .prettierrc.yml ] || grep -q '"prettier"' package.json 2>/dev/null; then
+  npx prettier --check . 2>&1 | tail -30
+fi
+
+# TypeScript 类型检查
+if [ -f tsconfig.json ]; then
+  npx tsc --noEmit 2>&1 | tail -30
+fi
+
+# Stylelint
+if [ -f .stylelintrc -o -f .stylelintrc.js -o -f .stylelintrc.json ] || grep -q '"stylelint"' package.json 2>/dev/null; then
+  npx stylelint "**/*.{css,scss,less}" 2>&1 | tail -30
+fi
+```
+
+**处理策略（AskUserQuestion）：**
+1. **自动修复** — 对支持 `--fix` 的工具自动修复后重跑，同一问题最多修复 3 次
+2. **只报告** — 仅列出所有 lint 错误，不修改代码

package/dist/steps/verify/08-output-report.md

@@ -0,0 +1,14 @@
+输出验证报告：
+
+```markdown
+# SillySpec 验证报告
+## 任务完成度：X/Y
+## 设计一致性
+## 测试结果：passed N, failed N
+## 技术债务标记
+## 代码审查：🔴 N / 🟡 N / 🔵 N
+## Lint 检查：ESLint ✅/❌ | Prettier ✅/❌ | TypeScript ✅/❌ | Stylelint ✅/❌
+## MCP 基础设施验证：数据库 ✅/❌/跳过 | 页面 ✅/❌/跳过 | API ✅/❌/跳过
+## E2E 测试：passed N / failed N / fixAttempts 详情
+## 结论：✅ PASS / ⚠️ PASS WITH NOTES / ❌ FAIL
+```

package/dist/steps/verify/manifest.yaml

@@ -0,0 +1,22 @@
+phase: verify
+description: 验证与检查
+requires: [execute]
+steps:
+  - file: 01-load-specs.md
+    name: 加载规范
+  - file: 02-check-tasks.md
+    name: 检查任务完成度
+  - file: 03-check-design.md
+    name: 对照设计文档
+  - file: 04-run-tests.md
+    name: 运行单元测试
+  - file: 05-e2e-tests.md
+    name: E2E 测试
+  - file: 05b-e2e-fix.md
+    name: E2E 自动修复
+  - file: 06-code-quality.md
+    name: 代码质量扫描
+  - file: 07-lint-check.md
+    name: Lint 检查
+  - file: 08-output-report.md
+    name: 输出验证报告

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sillyspec",
-  "version": "3.8.7",
-  "description": "SillySpec CLI \u2014 \u6d41\u7a0b\u72b6\u6001\u673a\uff0c\u8ba9 AI \u4e25\u683c\u6309\u6b65\u9aa4\u6765",
+  "version": "3.9.0",
+  "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "type": "module",
   "bin": {
     "sillyspec": "./bin/sillyspec.js"
@@ -33,4 +33,4 @@
   "devDependencies": {
     "vitepress": "^1.6.4"
   }
-}
+}

package/src/index.js

@@ -24,6 +24,10 @@ SillySpec CLI — 规范驱动开发工具包
     [--dir <path>]             指定目录
   sillyspec setup [--list]     安装推荐 MCP 工具
     [--list]                   查看已安装状态
+  sillyspec step <phase>         步骤调度器
+    [--next] [--status] [--list] [--jump <n>]
+    [--sessions] [--clean]
+    [--session <id>] [--json]
   sillyspec dashboard          启动 Dashboard Web UI
     [--port <number>]          指定端口（默认 3456）
     [--no-open]                不自动打开浏览器
@@ -100,6 +104,12 @@ async function main() {
       const setupList = filteredArgs.includes('--list') || filteredArgs.includes('-l');
       await (await import('./setup.js')).cmdSetup(dir, { json, list: setupList });
       break;
+    case 'step': {
+      const stepArgs = filteredArgs.slice(1);
+      if (json) stepArgs.push('--json');
+      await (await import('./step.js')).cmdStep(dir, stepArgs);
+      break;
+    }
     case 'progress':
       console.log('⚠️  阶段控制功能已移除，各阶段独立运行。');
       break;