sillyspec 3.10.7 → 3.11.0

package/package.json

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

package/src/stages/archive.js

@@ -18,19 +18,141 @@ export const definition = {
       outputHint: '完成度报告',
       optional: false
     },
+    {
+      name: 'extract-module-impact',
+      prompt: `分析本次变更影响的模块，生成模块影响记录。
+
+### 操作
+1. 读取变更目录下的 proposal.md、design.md、tasks.md
+2. 运行 \`git diff --name-only HEAD~1\`（或 \`git diff --name-only --cached\`）获取真实修改文件列表
+3. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`
+   - **如果不存在**：提示"建议运行 scan 生成模块映射"，但继续执行。跳到步骤 7 生成只有 unmapped 部分的 module-impact.md
+4. 三重交叉验证：
+   - 声明范围：proposal.md / design.md 中的"变更范围"/"文件变更清单"
+   - 任务范围：tasks.md / plan.md 中的任务文件路径
+   - 真实变更：git diff 文件列表
+   - **以 git diff 为准**（真实 > 声明）
+5. 将 git diff 文件按 \`_module-map.yaml\` 的 paths glob 匹配到模块
+6. 生成模块影响矩阵：
+
+| 模块 | 影响类型 | 相关文件 | 更新内容摘要 |
+|------|----------|----------|-------------|
+
+   影响类型：逻辑变更 / 数据结构变更 / 接口变更 / 调用关系变更 / 配置变更 / 新增
+
+7. 未匹配到任何模块的文件归入"未匹配文件"表格
+8. 生成 \`.sillyspec/changes/<change-name>/module-impact.md\`，格式：
+
+\`\`\`markdown
+# 模块影响分析
+
+author: <git用户名>
+created_at: <YYYY-MM-DD HH:mm:ss>
+
+## 变更：<change-name>
+
+## 模块影响矩阵
+| 模块 | 影响类型 | 相关文件 | 更新内容摘要 |
+|------|----------|----------|-------------|
+
+## 未匹配文件
+| 文件路径 | 说明 |
+|----------|------|
+
+## 更新结果
+（sync-module-docs 步骤完成后回填）
+| 模块文档 | 操作 | 状态 |
+|----------|------|------|
+\`\`\`
+
+### 输出
+module-impact.md 路径 + 影响模块数量 + 未匹配文件数量`,
+      outputHint: 'module-impact.md 路径 + 影响摘要',
+      optional: false
+    },
+    {
+      name: 'sync-module-docs',
+      prompt: `根据 module-impact.md 同步更新模块设计文档。
+
+### 原则
+- 模块文档正文**永远描述当前状态**（快照模式），不是变更日志
+- 底部只保留轻量变更索引
+- 模块文档是下一次 AI 开发前必须读取的上下文
+
+### 操作
+1. 读取 \`.sillyspec/changes/<change-name>/module-impact.md\`
+2. 如果没有受影响模块（只有 unmapped）→ 提示用户，跳过同步
+3. 对每个受影响模块：
+   a. 读取 \`.sillyspec/docs/<project>/modules/<module>.md\`（如不存在则新建）
+   b. 根据 module-impact.md 中的"更新内容摘要"，更新模块文档
+   c. **更新规则**：
+      - 新建：全量生成，使用下方模板
+      - 更新：只改相关章节（当前设计/对外接口/依赖关系等），保持其他章节不变
+      - 正文重写为当前状态，不追加历史
+      - 底部"变更索引"追加一行：\`| <日期> | <变更名> | <一句话摘要> |\`
+   d. 更新头部元数据：\`> 最后更新：YYYY-MM-DD\`、\`> 最近变更：<change-name>\`
+4. 展示所有模块文档的更新内容（diff 摘要），请用户确认
+5. 用户确认后，写入 \`.sillyspec/docs/<project>/modules/*.md\`
+6. 用户拒绝时，不写入模块文档，但提示"module-impact.md 已保留，可稍后手动同步"
+7. 回填 module-impact.md 的"更新结果"表格
+
+### 模块文档模板
+\`\`\`markdown
+# <module-name>
+
+> 最后更新：YYYY-MM-DD
+> 最近变更：<change-name>
+> 模块路径：<glob patterns>
+
+## 职责
+（一句话说清这个模块做什么）
+
+## 当前设计
+（架构、数据流、关键逻辑 — 描述当前状态，不是历史）
+
+## 对外接口
+| 接口 | 说明 | 调用方 |
+|------|------|--------|
+
+## 关键数据流
+\`\`\`text
+调用方 → 模块.方法() → 依赖模块.方法() → 返回结果
+\`\`\`
+
+## 设计决策
+| 决策 | 理由 | 来源 |
+|------|------|------|
+
+## 依赖关系
+### 依赖本模块
+### 本模块依赖
+
+## 注意事项
+（维护提醒、已知限制、修改时需同步检查的模块）
+
+## 变更索引
+| 日期 | 变更 | 摘要 |
+|------|------|------|
+\`\`\`
+
+### 输出
+已更新的模块文档路径列表 + 用户确认状态`,
+      outputHint: '模块文档更新结果',
+      optional: false
+    },
     {
       name: '确认归档',
       prompt: `展示即将归档的内容，请用户确认。
 
 ### 操作
-1. 展示：变更目录名、包含的文件列表、生成总结
+1. 展示：变更目录名、包含的文件列表（含 module-impact.md）、生成总结
 2. 请用户确认是否执行归档
-3. 确认后：将 \.sillyspec/changes/<change-name>/ 移动到 \.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/
+3. 确认后：将 \`.sillyspec/changes/<change-name>/\` 移动到 \`.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/\`
 4. 确保所有 checkbox 都已勾选
 
 ### 归档执行
 确认归档后，执行以下命令自动完成目录移动：
-\	\	sillyspec run archive --done --confirm --output "确认归档"
+\t\tsillyspec run archive --done --confirm --output "确认归档"
 - \`--confirm\` 标志会自动执行目录移动（原子操作）
 - 不带 \`--confirm\` 则只提示需要确认
 
@@ -46,7 +168,8 @@ export const definition = {
 ### 操作
 1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
 2. \`git add .sillyspec/changes/\` — 暂存归档结果（不要 commit，由用户通过统一提交工具处理）
-3. 更新 progress.json：
+3. \`git add .sillyspec/docs/\` — 暂存模块文档更新（如有）
+4. 更新 progress.json：
    - 清除当前变更信息（归档后不再活跃）
    - 如果是主变更（有 MASTER.md），标记所有阶段为 ✅，然后清除
    - 历史记录追加时间 + 归档完成

package/src/stages/execute.js

@@ -36,8 +36,14 @@ const fixedPrefix = [
 4. 读取 local.yaml（构建命令）
 5. 加载 CODEBASE-OVERVIEW.md
 
+### 模块文档加载
+6. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
+7. 根据 plan.md 中的任务文件路径匹配 _module-map.yaml 中的模块
+8. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
+9. 实现代码时遵循模块文档中描述的接口约定、数据流和依赖关系
+
 ### 输出
-已加载的上下文摘要`,
+已加载的上下文摘要（含模块文档）`,
     outputHint: '上下文摘要',
     optional: false
   },

package/src/stages/plan.js

@@ -33,8 +33,14 @@ export const fixedPrefix = [
 3. 读取 CONVENTIONS.md、ARCHITECTURE.md、STACK.md
 4. 读取 local.yaml 获取构建/测试命令
 
+### 模块文档加载
+5. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
+6. 根据 design.md 的文件变更清单匹配 _module-map.yaml 中的模块
+7. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
+8. 将模块文档作为制定计划的上下文，确保计划符合模块当前设计
+
 ### 输出
-已加载的文件清单`,
+已加载的文件清单（含模块文档）`,
     outputHint: '文件清单',
     optional: false
   },

package/src/stages/propose.js

@@ -26,8 +26,14 @@ export const definition = {
 2. 读取最新设计文档、需求文档、代码库约定
 3. 如果是子阶段变更，读取 MASTER.md 和前序阶段设计
 
+### 模块文档加载
+4. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
+5. 根据当前提案初步判断涉及的模块（匹配提案中的文件路径到 _module-map.yaml 的 paths）
+6. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
+7. 如果发现提案中的变更范围与某个模块文档描述的当前设计存在潜在冲突，在后续提案中明确标注并说明处理方案
+
 ### 输出
-已加载的文件列表`,
+已加载的文件列表（含模块文档）`,
       outputHint: '文件列表',
       optional: false
     },

package/src/stages/quick.js

@@ -68,8 +68,18 @@ export const definition = {
 4. 如果发现项目特有的坑，追加到 \`.sillyspec/knowledge/uncategorized.md\`
 5. 任务比预期复杂 → 建议用完整流程
 
+### 模块文档同步
+6. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
+7. 对比本次修改的文件（\`git diff --name-only\`）与模块映射
+8. 如果命中模块 → 直接同步模块文档：
+   - 读取对应的 \`.sillyspec/docs/<project>/modules/<module>.md\`（如不存在则新建）
+   - 根据本次改动内容更新模块文档（正文描述当前状态，底部追加变更索引）
+   - 写入模块文档
+   - 将更新的模块文件加入 \`git add\`
+9. 未命中任何模块 → 跳过，不做额外操作
+
 ### 输出
-暂存确认 + 记录路径`,
+暂存确认 + 记录路径 + 模块文档同步结果（如有）`,
       outputHint: '暂存和记录确认',
       optional: false
     }

package/src/stages/scan.js

@@ -158,6 +158,51 @@ local.yaml 生成结果（已存在/已生成）`,
       outputHint: 'local.yaml 生成状态',
       optional: false
     },
+    {
+      name: '生成模块映射',
+      prompt: `生成模块映射配置文件，建立"文件路径 → 模块"的稳定映射。
+
+### 操作
+1. 检查 \.sillyspec/docs/<project>/modules/_module-map.yaml\` 是否已存在，已存在则跳过
+2. 分析项目 src/ 目录结构（或主代码目录），识别模块划分：
+   - 用 \`find . -maxdepth 2 -type d -not -path "*/node_modules/*" -not -path "*/.git/*"\` 查看目录结构
+   - 每个独立目录（有明确职责的）识别为一个模块
+   - 路径用 glob 模式（如 \`src/auth/**\`）
+3. 生成 \.sillyspec/docs/<project>/modules/_module-map.yaml\`
+4. 如果 modules/ 目录不存在，先创建
+5. 原子写入（先写 tmp 文件再 rename）
+
+### YAML 格式
+\`\`\`yaml
+# 模块映射（自动生成，可手动修改）
+# 用于 archive 阶段识别变更影响的模块
+modules:
+  <module-name>:
+    paths:
+      - <glob-pattern>
+    description: <一句话描述>
+\`\`\`
+
+### 示例
+\`\`\`yaml
+modules:
+  core:
+    paths:
+      - src/core/**
+      - src/utils/**
+    description: 核心工具和公共逻辑
+
+  stages:
+    paths:
+      - src/stages/**
+    description: 阶段定义（brainstorm/plan/execute/verify/archive等）
+\`\`\`
+
+### 输出
+_module-map.yaml 生成结果（已存在/已生成/模块列表）`,
+      outputHint: '_module-map.yaml 生成状态',
+      optional: true
+    },
     {
       name: '自检和提交',
       prompt: `验证扫描完整性，清理并提交。

package/src/stages/verify.js

@@ -27,8 +27,13 @@ export const definition = {
 4. 加载代码规范：\`cat .sillyspec/docs/<project>/scan/CONVENTIONS.md 2>/dev/null\`
 5. 标注每个文件的存在/不存在状态
 
+### 模块文档加载
+6. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
+7. 根据 design.md 的文件变更清单匹配 _module-map.yaml 中的模块
+8. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
+
 ### 输出
-文件加载确认清单`,
+文件加载确认清单（含模块文档）`,
       outputHint: '文件确认清单',
       optional: false
     },
@@ -95,9 +100,10 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
 3. 数据模型是否符合
 4. API 设计是否符合
 5. **Reverse Sync 检查**：如果发现实现合理但 design.md 未覆盖，先更新 design.md 补充遗漏
+6. **模块文档一致性检查**：如果在"加载规范并锚定"步骤中加载了模块文档，检查实现是否符合模块文档描述的当前设计（特别关注接口签名、数据流、依赖关系）。不符合时标记 ⚠️（不阻断，模块文档可能未及时更新）
 
 ### 输出
-探针报告 + 设计一致性检查结果`,
+探针报告 + 设计一致性检查结果 + 模块文档一致性检查结果`,
       outputHint: '设计一致性报告',
       optional: false
     },