sillyspec 3.7.16 → 3.7.18

package/.claude/skills/sillyspec-verify/SKILL.md

@@ -3,144 +3,11 @@ name: sillyspec:verify
 description: 验证实现 — 对照规范检查 + 测试套件
 ---
 
-> **可选阶段。** execute 完成后会询问是否需要 verify，也可以手动调用。
+## 执行
 
-你现在是 SillySpec 的验证器。
+运行 `sillyspec run verify`，按提示逐步执行。
+每步完成后运行 `sillyspec run verify --done --output "摘要"`。
+阶段完成后自动提示下一步。
 
-## 🛑 流程控制（必须先执行）
-
-**在开始任何工作之前，先调用 SillySpec CLI 检查当前状态：**
-
-```bash
-sillyspec status --json
-```
-
-**根据 CLI 返回的 phase 决定是否允许执行 verify：**
-- `phase: "verify"` → ✅ 可以继续
-- 其他 phase → ❌ 不允许跳步，提示用户运行 `sillyspec next` 获取正确步骤
-
-**不要跳过状态检查。不要自己推断阶段。以 CLI 为准。**
-
-## 流程
-
-### 1. 加载规范
-
-```bash
-LATEST=$(ls -d .sillyspec/changes/*/ | grep -v archive | tail -1)
-cat "$LATEST/proposal.md"
-cat "$LATEST/design.md"
-cat "$LATEST/tasks.md"
-cat "$LATEST/specs/requirements.md" 2>/dev/null
-```
-
-### 1.5 锚定确认（必须完成）
-
-读取相关规范文件。对于存在的文件，确认理解；对于不存在的文件，标注跳过：
-
-```
-已读取并理解：
-- [x] proposal.md — 变更动机和范围（如果存在）
-- [x] design.md — 技术方案和文件变更（如果存在）
-- [x] tasks.md — 实现清单（如果存在）
-- [x] specs/requirements.md — 需求和场景（如果存在）
-
-所有可用上下文已加载，开始验证。
-```
-
-**文件不存在不是错误**。只确认实际存在的文件。不准跳过此步骤。
-
-### 2. 逐项检查 tasks.md
-
-对每个 checkbox 报告状态：
-- ✅ 已完成 / ❌ 未完成 / ⚠️ 部分完成
-
-### 3. 对照 design.md
-
-- 架构决策是否遵循？
-- 文件变更清单是否一致？
-- 数据模型是否符合？
-- API 设计是否符合？
-
-### 4. 运行完整测试套件（fresh run）
-
-```bash
-# 根据项目技术栈运行
-pnpm test 2>/dev/null || npm test 2>/dev/null || pytest 2>/dev/null || go test ./... 2>/dev/null
-```
-
-记录通过/失败数量。如有失败，分析原因。
-
-### 5. 代码质量扫描
-
-```bash
-# 搜索技术债务标记
-grep -r "TODO\|FIXME\|HACK\|XXX" src/ lib/ app/ --include="*.ts" --include="*.tsx" --include="*.py" --include="*.js" 2>/dev/null | head -20
-```
-
-### 6. 输出验证报告
-
-```markdown
-# SillySpec 验证报告
-
-## 任务完成度
-- [x] Task 1: xxx ✅
-- [x] Task 2: xxx ✅
-- [ ] Task 3: xxx ❌ 未实现
-完成度：2/3
-
-## 设计一致性
-- ✅ 架构决策遵循
-- ⚠️ API 返回格式与 design.md 略有差异（缺少 error 字段）
-
-## 测试结果
-- passed: 42, failed: 3
-
-## 技术债务标记
-- src/auth/login.ts:15 // TODO: add rate limiting
-- src/auth/login.ts:45 // FIXME: token expiry
-
-## 结论
-⚠️ PASS WITH NOTES
-```
-
-## 脚本校验（硬验证）
-
-在输出验证报告之前，运行综合校验脚本：
-
-```bash
-bash scripts/validate-all.sh
-```
-
-将脚本输出纳入验证报告中的"设计一致性"部分。
-
-### 7. 最后说：
-
-**用 CLI 验证并获取下一步：**
-
-```bash
-sillyspec status --json
-```
-
-展示结果给用户，然后：
-
-```bash
-sillyspec next
-```
-
-将 CLI 返回的命令推荐给用户。**不要自己编建议。**
-
-### 8. 更新 progress.json
-
-verify 完成后，**必须自动更新进度**：
-```bash
-sillyspec progress complete-stage verify
-```
-
-- 当前阶段改为 `verify ✅` 或 `verify ⚠️`
-- 下一步改为 `/sillyspec:archive`（PASS 时）或 `修复后重新 /sillyspec:verify`
-- 如果是子阶段，更新阶段进度；如果全部阶段完成，下一步改为 `/sillyspec:archive`
-- 历史记录追加时间 + 验证结果
-
-## 绝对规则
-- 不修改任何代码
-- 只做检查和报告
+## 用户指令
+$ARGUMENTS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.7.16",
+  "version": "3.7.18",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/progress.js

@@ -17,7 +17,7 @@ const PROGRESS_FILE = 'progress.json';
 const BACKUP_FILE = 'progress.json.bak';
 
 const CURRENT_VERSION = 2;
-const VALID_STAGES = ['brainstorm', 'propose', 'plan', 'execute', 'verify'];
+const VALID_STAGES = ['brainstorm', 'propose', 'plan', 'execute', 'verify', 'scan', 'quick', 'archive', 'status'];
 const VALID_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked'];
 
 const STAGE_LABELS = {
@@ -26,6 +26,10 @@ const STAGE_LABELS = {
   plan: '📐 实现计划',
   execute: '⚡ 波次执行',
   verify: '🔍 验证确认',
+  scan: '🔍 代码扫描',
+  quick: '⚡ 快速任务',
+  archive: '📦 归档变更',
+  status: '📊 状态查看',
 };
 
 function emptyStage() {

package/src/run.js

@@ -6,7 +6,7 @@
 import { basename, join } from 'path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync } from 'fs'
 import { ProgressManager } from './progress.js'
-import { stageRegistry, getNextStage } from './stages/index.js'
+import { stageRegistry, getNextStage, auxiliaryStages } from './stages/index.js'
 import { buildExecuteSteps } from './stages/execute.js'
 
 /**
@@ -76,6 +76,11 @@ function outputStep(stageName, stepIndex, steps, cwd) {
   console.log(`---\n`)
   console.log(`## Step ${stepIndex + 1}/${total}: ${step.name}\n`)
   console.log(step.prompt)
+  console.log(`\n### ⚠️ 铁律`)
+  console.log('- 只做本步骤描述的操作，不得自行扩展或跳过')
+  console.log('- 不要回头修改已完成的步骤')
+  console.log('- 完成后立即执行 --done 命令，不得跳过')
+  console.log('- 生成的文件头部必须包含 author（git 用户名）和 created_at（精确到秒）')
   console.log(`\n### 完成后执行`)
   console.log(`sillyspec run ${stageName} --done --output "你的摘要"`)
 }
@@ -106,12 +111,18 @@ export function runCommand(args, cwd) {
     outputText = flags[outputIdx + 1]
   }
 
+  const isAuxiliary = auxiliaryStages.includes(stageName)
+
   const pm = new ProgressManager()
   let progress = pm.read(cwd)
 
   if (!progress) {
-    console.error('❌ 未找到 progress.json，请先运行 sillyspec init')
-    process.exit(1)
+    // 辅助命令可以在没有 progress.json 时工作（比如 scan）
+    if (!isAuxiliary) {
+      console.error('❌ 未找到 progress.json，请先运行 sillyspec init')
+      process.exit(1)
+    }
+    progress = pm.init(cwd)
   }
 
   // --reset

package/src/stages/archive.js

@@ -0,0 +1,54 @@
+export const definition = {
+  name: 'archive',
+  title: '归档变更',
+  description: '规范沉淀，可追溯',
+  auxiliary: true,
+  steps: [
+    {
+      name: '任务完成度检查',
+      prompt: `检查 tasks.md 中所有 checkbox 是否已勾选。
+
+### 操作
+1. 读取 \`.sillyspec/changes/<change-name>/tasks.md\`
+2. 检查所有 checkbox 是否已勾选
+3. 如有遗漏 → 询问用户是否继续归档
+
+### 输出
+完成度报告`,
+      outputHint: '完成度报告',
+      optional: false
+    },
+    {
+      name: '确认归档',
+      prompt: `展示即将归档的内容，请用户确认。
+
+### 操作
+1. 展示：变更目录名、包含的文件列表、生成总结
+2. 请用户确认是否执行归档
+3. 确认后：将 \`.sillyspec/changes/<change-name>/\` 移动到 \`.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/\`
+4. 确保所有 checkbox 都已勾选
+
+### 输出
+归档确认`,
+      outputHint: '归档确认',
+      optional: false
+    },
+    {
+      name: '更新路线图和提交',
+      prompt: `更新路线图并 Git 提交。
+
+### 操作
+1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
+2. \`git add .sillyspec/ && git commit -m "docs: archive sillyspec change <change-name>"\`
+3. 更新 progress.json：
+   - 清除当前变更信息（归档后不再活跃）
+   - 如果是主变更（有 MASTER.md），标记所有阶段为 ✅，然后清除
+   - 历史记录追加时间 + 归档完成
+
+### 输出
+归档完成确认 + 累积规范统计`,
+      outputHint: '归档完成',
+      optional: false
+    }
+  ]
+}

package/src/stages/index.js

@@ -3,16 +3,24 @@ import { definition as propose } from './propose.js'
 import { definition as plan } from './plan.js'
 import { definition as execute } from './execute.js'
 import { definition as verify } from './verify.js'
+import { definition as scan } from './scan.js'
+import { definition as quick } from './quick.js'
+import { definition as archive } from './archive.js'
+import { definition as status } from './status.js'
 
 export const stageRegistry = {
   brainstorm,
   propose,
   plan,
   execute,
-  verify
+  verify,
+  scan,
+  quick,
+  archive,
+  status
 }
 
-// 阶段顺序，用于 getNextStage
+// 流程阶段顺序，用于 getNextStage
 const stageOrder = ['brainstorm', 'propose', 'plan', 'execute', 'verify']
 
 export function getNextStage(currentStage) {
@@ -20,3 +28,6 @@ export function getNextStage(currentStage) {
   if (index === -1 || index >= stageOrder.length - 1) return null
   return stageOrder[index + 1]
 }
+
+// 辅助命令（不影响流程阶段推进）
+export const auxiliaryStages = ['scan', 'quick', 'archive', 'status']

package/src/stages/quick.js

@@ -0,0 +1,93 @@
+export const definition = {
+  name: 'quick',
+  title: '快速任务',
+  description: '跳过完整流程，直接做',
+  auxiliary: true,
+  steps: [
+    {
+      name: '解析参数和上下文',
+      prompt: `解析任务参数，加载项目上下文。
+
+### 操作
+1. 检查是否携带 \`--change <变更名>\`，确定记录方式
+2. 理解任务：模糊则问一个问题确认
+3. 加载上下文：\`cat .sillyspec/codebase/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null\`
+4. 加载扫描文档（如存在）：\`cat docs/<project>/scan/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null\`
+
+### 输出
+任务理解 + 上下文摘要`,
+      outputHint: '任务理解',
+      optional: false
+    },
+    {
+      name: '知识库和文档查询',
+      prompt: `查询知识库和外部文档。
+
+### 操作
+1. \`cat .sillyspec/knowledge/INDEX.md 2>/dev/null\` — 根据关键词匹配
+2. 命中时 \`cat\` 对应知识文件
+3. 如果涉及不熟悉的库/框架/API：通过 Context7 查询官方文档
+4. 将查询结果纳入后续开发考量
+
+### 输出
+相关知识条目和文档查询结果`,
+      outputHint: '知识查询结果',
+      optional: true
+    },
+    {
+      name: 'TDD 实现',
+      prompt: `按 TDD 流程实现任务。
+
+### 操作
+1. 先读后写：调用已有方法前 \`cat\` 源文件确认签名，\`grep\` 确认方法存在
+2. 🔴 RED → 先写测试，运行确认失败
+3. 🟢 GREEN → 写最少代码让测试通过
+4. 🔵 REFACTOR → 清理，保持测试通过
+5. ✅ STAGE → git add 暂存（测试文件必须包含）
+
+### 纯配置/数据/文档可跳过 TDD，其他一律走 TDD。
+
+### 输出
+实现摘要 + 修改文件列表
+
+### 铁律
+- ❌ 不写测试（底线是仍然要写测试）
+- ❌ 修改无关文件
+- ❌ 跳过测试因为"任务太简单"`,
+      outputHint: '实现摘要',
+      optional: false
+    },
+    {
+      name: '运行测试',
+      prompt: `运行测试确认通过。
+
+### 操作
+1. 检查 local.yaml 构建命令配置：\`cat .sillyspec/local.yaml 2>/dev/null\`
+2. 有则使用 local.yaml 中的命令，否则使用默认命令
+3. 默认命令：\`mvn test -pl <模块> -Dtest=<测试类>\` 或 \`./gradlew test --tests <测试类>\` 或 \`pnpm test\` 或 \`npm test\` 或 \`pytest <测试文件>\`
+
+### 输出
+测试通过/失败结果`,
+      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 .\` — 判断是否工作区模式
+2. \`ls docs/*/scan/ 2>/dev/null\` — 检查已有文档
+3. \`wc -l docs/*/scan/*.md 2>/dev/null\` — 文档行数
+4. 已有 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. 结果保存到 \`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. 写入 \`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. 写入 \`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. 写入 \`docs/<project>/scan/STRUCTURE.md\`（目录树+模块说明）
+4. 写入 \`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. 写入 \`docs/<project>/scan/TESTING.md\`（测试结构）
+3. 写入 \`docs/<project>/scan/CONCERNS.md\`（按严重程度分组）
+4. 写入 \`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 docs/<project>/scan/_env-detect.md\`
+4. \`git add . && git commit -m "chore: sillyspec scan - codebase mapped"\`
+
+### 输出
+扫描完整性报告 + commit hash
+
+### 注意
+- ❌ 修改代码 / 编造路径 / 读源码全文`,
+      outputHint: '自检报告 + commit hash',
+      optional: false
+    }
+  ]
+}

package/src/stages/status.js

@@ -0,0 +1,92 @@
+export const definition = {
+  name: 'status',
+  title: '状态查看',
+  description: '查看项目进度和状态',
+  auxiliary: true,
+  steps: [
+    {
+      name: '检查工作区模式',
+      prompt: `判断是否为工作区模式。
+
+### 操作
+1. \`ls .sillyspec/projects/*.yaml 2>/dev/null | grep -q .\`
+2. 是 → 工作区模式，对每个子项目执行状态检查
+3. 否 → 单项目模式，继续后续步骤
+
+### 工作区模式输出格式：
+\`\`\`
+🏢 工作区状态
+📦 子项目：
+  ✅ frontend  ./frontend
+     📋 项目：已初始化
+     📂 代码库：已扫描（7 份文档）
+     🔄 进行中：1 个变更
+  ⚠️ backend   ./backend
+     📂 代码库：未扫描
+📄 共享规范：2 份
+\`\`\`
+
+### 输出
+工作区/单项目判断`,
+      outputHint: '模式判断',
+      optional: false
+    },
+    {
+      name: '项目基础信息',
+      prompt: `收集项目基础信息。
+
+### 操作
+1. \`cat .sillyspec/PROJECT.md 2>/dev/null || echo "未初始化"\`
+2. 获取 project 名
+3. \`ls docs/<project>/scan/ 2>/dev/null | head -10\`
+4. \`cat .sillyspec/REQUIREMENTS.md 2>/dev/null | head -20\`
+5. \`cat .sillyspec/ROADMAP.md 2>/dev/null\`
+
+### 输出
+项目基础信息摘要`,
+      outputHint: '项目基础信息',
+      optional: false
+    },
+    {
+      name: '变更状态',
+      prompt: `检查进行中的变更和归档历史。
+
+### 操作
+1. \`ls .sillyspec/changes/ 2>/dev/null | grep -v archive\`
+2. 对每个进行中的变更：检查 proposal.md ✅/❌、design.md ✅/❌、requirements.md ✅/❌、tasks.md — X/Y 完成
+3. \`ls .sillyspec/changes/archive/ 2>/dev/null | wc -l\`
+4. \`cat .sillyspec/HANDOFF.json 2>/dev/null\`
+
+### 输出
+变更状态列表`,
+      outputHint: '变更状态',
+      optional: false
+    },
+    {
+      name: '输出状态报告',
+      prompt: `生成完整状态报告。
+
+### 输出格式：
+\`\`\`
+📊 SillySpec 状态
+
+📋 项目：xxx（已初始化 / 未初始化）
+📂 代码库：已扫描（7 份文档）/ 未扫描
+
+🔄 进行中：N 个变更
+  - [change-1] Phase 3 (Execute) — tasks 5/8
+
+✅ 已归档：N 个变更
+📝 设计文档：N 份
+📝 实现计划：N 份
+
+💡 下一步：/sillyspec:continue
+\`\`\`
+
+### 注意
+- 不修改任何文件`,
+      outputHint: '状态报告',
+      optional: false
+    }
+  ]
+}