sillyspec 3.5.1 → 3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "type": "module",
   "bin": {

package/src/init.js

@@ -22,6 +22,7 @@ const DESCRIPTIONS = {
   execute: '波次执行 — 子代理并行 + 强制 TDD + 两阶段审查',
   verify: '验证实现 — 对照规范检查 + 测试套件',
   archive: '归档变更 — 规范沉淀，可追溯',
+  commit: '智能提交 — 自动收集变更信息，生成 commit message',
   status: '查看项目进度和状态',
   continue: '自动判断并执行下一步',
   state: '查看当前工作状态 — 显示 STATE.md 内容',
@@ -41,6 +42,7 @@ const ARG_HINTS = {
   execute: '[任务编号或 \'all\']',
   verify: '[可选：指定验证范围]',
   archive: '[变更名]',
+  commit: '[可选：自定义 commit message]',
   status: '',
   continue: '',
   state: '[可选备注]',

package/templates/archive.md

@@ -54,9 +54,11 @@ $ARGUMENTS
 - **tasks.md：** 确保所有 checkbox 都已勾选 `[x]`
 - **ROADMAP.md**（如存在）：标记对应 Phase 已完成
 - **STATE.md：** 清除当前变更信息，历史记录追加归档完成（含精确到秒的时间戳）
-- **Git 提交：** `git add .sillyspec/ && git commit -m "docs: archive sillyspec change <change-name>"`
+- **Git 暂存：** `git add .sillyspec/`
 
-**工作区模式下：** 如果变更属于某个子项目，cd 到子项目目录执行 git commit。工作区根目录无 git 则跳过。
+**工作区模式下：** 如果变更属于某个子项目，cd 到子项目目录执行 git add。工作区根目录无 git 则跳过。
+
+💡 归档产出已暂存。准备好后用 `/sillyspec:commit` 提交。
 
 ### 最后说：
 

package/templates/brainstorm.md

@@ -53,7 +53,7 @@ $ARGUMENTS
 cat .sillyspec/config.yaml 2>/dev/null
 ```
 
-**工作区模式：** AskUserQuestion 选子项目，**cd 到子项目目录执行**，加载子项目上下文 + 共享规范 + 工作区概览，设计文档保存到子项目 `.sillyspec/changes/`。git commit 在子项目目录执行。
+**工作区模式：** AskUserQuestion 选子项目，**cd 到子项目目录执行**，加载子项目上下文 + 共享规范 + 工作区概览，设计文档保存到子项目 `.sillyspec/changes/`。修改在子项目目录中暂存。
 
 **单项目模式：**
 ```bash
@@ -100,9 +100,10 @@ mkdir -p .sillyspec/changes/<变更名>/stages
 
 ```bash
 git add .sillyspec/changes/<变更名>/MASTER.md
-git commit -m "docs: master change plan for <变更名>"
 ```
 
+💡 大模块计划已暂存。准备好后用 `/sillyspec:commit` 提交。
+
 提示用户：`/sillyspec:brainstorm <变更名>/stage-1`
 
 **子阶段 brainstorm：** 读取 MASTER.md + 前序阶段经验 + 对应原型，设计文档保存到 `.sillyspec/changes/<变更名>/stages/<stage-N>/`。

package/templates/commit.md

@@ -0,0 +1,121 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+## 用法
+- `/sillyspec:commit` — 智能提交：自动收集变更信息，生成 commit message
+- `/sillyspec:commit "自定义 message"` — 使用指定 message 直接提交
+
+## 任务
+$ARGUMENTS
+
+---
+
+## 流程
+
+### 1. 检查是否有未提交的修改
+
+```bash
+git diff --quiet 2>/dev/null; UNSTAGED=$?
+git diff --cached --quiet 2>/dev/null; STAGED=$?
+```
+
+两者都为 0（无修改）→ 提示"没有需要提交的修改"，结束。
+
+### 2. 暂存所有修改
+
+```bash
+git add -A
+```
+
+### 3. 收集变更语义信息
+
+```bash
+# 上次 commit 时间
+LAST_COMMIT_TIME=$(git log -1 --format=%ci 2>/dev/null)
+
+# 修改的文件列表
+git diff --cached --stat
+```
+
+从以下来源收集语义信息（筛选时间戳 > LAST_COMMIT_TIME 的条目）：
+
+**来源 A — QUICKLOG（quick 产生的修改）：**
+```bash
+USER=$(git config user.name 2>/dev/null || echo "default")
+cat .sillyspec/quicklog/QUICKLOG-${USER}.md 2>/dev/null
+```
+
+**来源 B — tasks.md（execute 产生的修改）：**
+```bash
+LATEST=$(ls -d .sillyspec/changes/*/ 2>/dev/null | grep -v archive | tail -1)
+cat "$LATEST/tasks.md" 2>/dev/null
+```
+筛选时间戳 > LAST_COMMIT_TIME 的已勾选 task。
+
+**来源 C — 阶段产出（scan/brainstorm/propose/plan/archive 等）：**
+检查 `.sillyspec/` 下新增或修改的文件，根据路径识别来源阶段：
+- `codebase/*.md` → scan 产出
+- `changes/<name>/proposal.md` → propose 产出
+- `changes/<name>/design.md` 或 `tasks.md` → plan 产出
+- `changes/archive/` → archive 产出
+- `specs/*.md` → brainstorm 产出
+- `knowledge/*.md` → 知识库更新
+
+### 4. 自动生成 commit message
+
+按 conventional commits 格式，根据来源生成 message：
+
+| 来源 | type | 示例 |
+|---|---|---|
+| 只有 quick 条目 | fix/refactor | `fix: 手机号校验修复（含正则修正）` |
+| 只有 execute 条目 | feat | `feat(user): 用户模块 task 1~3` |
+| 只有阶段产出 | docs | `docs: sillyspec scan 完成` |
+| 混合来源 | 取最主要的 type | body 里列出所有条目 |
+| 无匹配来源 | — | 展示 diff stat，让用户自己写 |
+
+**如果 $ARGUMENTS 非空**，直接使用用户指定的 message，跳过自动生成。
+
+**多条 quick 合并规则：**
+- 2 条以内 → 逐条列出
+- 3 条以上 → 摘要 + body 详情
+
+### 5. 展示确认
+
+用 AskUserQuestion 展示：
+
+```
+📝 建议的 commit message：
+  fix: 手机号校验修复（含正则修正）
+
+📁 修改文件（N 个）：
+  src/UserService.java (+15 -3)
+  src/PhoneValidator.java (+28 -0)
+
+选择：确认提交 / 编辑 message / 取消
+```
+
+用户选择编辑 → 让用户输入新 message → 再次确认。
+
+### 6. 执行提交
+
+```bash
+git commit -m "{确认后的 message}"
+```
+
+提交成功后展示 commit hash + 文件数 + 行数统计。
+
+## 工作区模式
+
+```bash
+cat .sillyspec/config.yaml 2>/dev/null
+```
+
+有子项目配置时：
+- 检查修改的文件分别属于哪个子项目
+- 修改集中在一个子项目 → 在该子项目目录中 commit
+- 修改跨多个子项目 → 用 AskUserQuestion 让用户选择：分开提交（每个子项目一个 commit）/ 合并提交
+
+## 绝对规则
+- ❌ 不要自动提交，必须展示 message 让用户确认
+- ❌ 不要丢弃用户的修改
+- ✅ $ARGUMENTS 非空时可跳过确认直接提交

package/templates/execute.md

@@ -34,7 +34,7 @@ $ARGUMENTS
 cat .sillyspec/config.yaml 2>/dev/null
 ```
 
-**工作区模式：** 根据计划 Task 标注确定子项目，额外加载共享规范 + CODEBASE-OVERVIEW.md。所有代码修改、测试运行、git commit 都在子项目目录中执行。
+**工作区模式：** 根据计划 Task 标注确定子项目，额外加载共享规范 + CODEBASE-OVERVIEW.md。所有代码修改、测试运行在子项目目录中执行。
 
 **加载以下文件（主代理读取，后续注入子代理）：**
 ```bash
@@ -45,6 +45,13 @@ cat .sillyspec/codebase/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null
 cat .sillyspec/local.yaml 2>/dev/null
 ```
 
+**知识库查询（强制步骤）：**
+主代理在 dispatch 每个子代理前，必须执行：
+```bash
+cat .sillyspec/knowledge/INDEX.md 2>/dev/null
+```
+根据当前 task 描述中的关键词（技术名词、模块名、文件路径等）匹配 INDEX.md 条目。命中时读取对应 knowledge 文件，将内容注入子代理 prompt 的「相关知识」段。未命中则跳过，不注入空段。
+
 如果 `$ARGUMENTS` 指定范围（如 `wave-1`、`task-3`），只执行对应部分。
 
 ---
@@ -91,6 +98,9 @@ cat .sillyspec/local.yaml 2>/dev/null
 ## 工作目录
 {子项目目录路径，工作区模式需要 cd 到此目录}
 
+## 相关知识（如有）
+{主代理从 knowledge/ 中按任务关键词匹配到的内容，未命中则删除此段}
+
 ## 铁律（必须遵守）
 1. **先读后写：** 先 cat 要修改的文件和参考文件，确认风格和方法签名后再写
 2. **grep 确认：** 调用已有方法前必须 grep 确认存在，grep 不到 → 报告 BLOCKED
@@ -98,7 +108,7 @@ cat .sillyspec/local.yaml 2>/dev/null
 4. **不自行补全：** 发现缺失接口/方法，不自己写，报告 BLOCKED
 5. **TDD 不跳步：** 按任务步骤逐步执行，每步必须运行测试命令并确认结果
 6. **测试直接通过 = 测了已有行为，重写测试**
-7. **commit：** 完成后在工作目录执行 git add -A && git commit
+7. **暂存：** 完成后在工作目录执行 git add -A（不要 commit，由用户通过 /sillyspec:commit 统一提交）
 8. **不修改计划外的文件**，如必须修改则在报告中说明
 
 ## 完成后报告（严格按此格式）
@@ -108,6 +118,7 @@ cat .sillyspec/local.yaml 2>/dev/null
 - **测试结果：** {通过/失败/跳过及原因}
 - **Commit:** {hash 或 "无"}
 - **问题：** {BLOCKED 原因 / DONE_WITH_CONCERNS 描述 / 无}
+- **发现的坑：** {执行过程中发现的项目特有规律/陷阱/约定，如无则写"无"。示例："XxxMapper.selectPage() 第一个参数必须是 IPage 对象，传 null 会 NPE 而非返回全部"}
 ```
 
 ### 子代理结果处理
@@ -121,10 +132,28 @@ cat .sillyspec/local.yaml 2>/dev/null
    - 跳过（勾选并标注 SKIPPED）
    - 停止（暂停执行，用户处理后继续）
 
+**知识库写入：** 如果子代理报告中「发现的坑」不为"无"，主代理将内容追加到 `.sillyspec/knowledge/uncategorized.md`，格式：
+```markdown
+### [待确认] {简短标题}
+> 来源：{变更名} / {task 编号} | {时间戳}
+
+{坑的具体描述}
+```
+
 ---
 
 ## 完成后
 
+**知识库审阅：** 检查是否有待确认的知识条目：
+```bash
+grep -c '^\### \[待确认\]' .sillyspec/knowledge/uncategorized.md 2>/dev/null
+```
+如果有待确认条目，提示用户：
+> 📚 本轮执行发现了 N 条新知识，请审阅：`cat .sillyspec/knowledge/uncategorized.md`
+> 确认后请将 `[待确认]` 改为 `[已确认]`，并可归类到 knowledge/ 下的专题文件中更新 INDEX.md。
+
+💡 所有修改已暂存。准备好后用 `/sillyspec:commit` 提交。
+
 所有任务完成后，用 AskUserQuestion 询问用户下一步：
 1. **验证** — 执行 `/sillyspec:verify` 全面验证
 2. **归档** — 跳过 verify，执行 `/sillyspec:archive`

package/templates/init.md

@@ -49,9 +49,11 @@ ls -la
 ### Step 6: Git 初始化
 
 ```bash
-git init && git add . && git commit -m "chore: sillyspec init - project initialized"
+git init && git add .
 ```
 
+💡 项目已初始化并暂存。准备好后用 `/sillyspec:commit` 提交。
+
 ### 最后说：
 
 > ✅ 项目初始化完成！

package/templates/quick.md

@@ -21,18 +21,23 @@ $ARGUMENTS
 1. **解析参数：** 检查是否携带 `--change <变更名>`，确定记录方式
 2. **理解任务：** 模糊则问一个问题确认
 3. **加载上下文：** `cat .sillyspec/codebase/{CONVENTIONS,ARCHITECTURE}.md 2>/dev/null`
-4. **先读后写：** 调用已有方法前 `cat` 源文件确认签名，`grep` 确认方法存在
-5. **TDD 执行：**
+4. **知识库查询（强制步骤）：**
+   ```bash
+   cat .sillyspec/knowledge/INDEX.md 2>/dev/null
+   ```
+   根据当前任务描述中的关键词匹配 INDEX.md 条目，命中时 `cat` 对应知识文件，将内容纳入后续开发考量。未命中则跳过。
+5. **先读后写：** 调用已有方法前 `cat` 源文件确认签名，`grep` 确认方法存在
+6. **TDD 执行：**
    ```
    🔴 RED    → 先写测试，运行确认失败
    🟢 GREEN  → 写最少代码让测试通过
    🔵 REFACTOR → 清理，保持测试通过
-   ✅ COMMIT  → git 提交（测试文件必须包含在提交中）
+   ✅ STAGE   → git add 暂存（测试文件必须包含在暂存中）
    ```
    测试文件必须保留在项目中，不能删除。违反 TDD → 删掉代码从测试重新开始。
    - 纯配置/数据/文档可跳过 TDD
    - 其他情况一律走 TDD
-6. **运行测试：** 先检查 local.yaml 构建命令配置：
+7. **运行测试：** 先检查 local.yaml 构建命令配置：
 ```bash
 cat .sillyspec/local.yaml 2>/dev/null
 ```
@@ -40,17 +45,30 @@ cat .sillyspec/local.yaml 2>/dev/null
 ```bash
 mvn test -pl <模块> -Dtest=<测试类> 2>/dev/null || ./gradlew test --tests <测试类> 2>/dev/null || pnpm test 2>/dev/null || npm test 2>/dev/null || pytest <测试文件> 2>/dev/null
 ```
-7. **Git commit：** 展示 commit message 给用户确认后提交。**工作区模式下，确认当前在正确的子项目目录中执行 commit。**
-8. **记录：**
+8. **Git 暂存：** `git add -A`。**不要 commit**，由用户通过 `/sillyspec:commit` 统一提交。**工作区模式下，确认当前在正确的子项目目录中执行暂存。**
+9. **记录：**
    - **有 `--change`：** 在 `.sillyspec/changes/<变更名>/tasks.md` 追加 task 并勾选，**记录精确到秒的时间戳**：
 
 ```
 - [x] [YYYY-MM-DD HH:MM:SS] 任务描述
 ```
    - **无 `--change`：** 记录到 `.sillyspec/quicklog/QUICKLOG-<git用户名>.md`（见下方规则）
-9. **检查复杂度：** 任务比预期复杂 → 建议用完整流程
+10. **检查复杂度：** 任务比预期复杂 → 建议用完整流程
+
+11. **记录发现的坑：** 执行过程中如果发现项目特有的规律、陷阱或约定（如"某方法参数顺序容易搞反"、"某表有隐藏软删除字段"），追加到 `.sillyspec/knowledge/uncategorized.md`，格式：
+
+```markdown
+### [待确认] {简短标题}
+> 来源：quick / {时间戳}
+
+{坑的具体描述}
+```
+
+**工作区模式下：** 只影响当前子项目 → 写入当前子项目 `.sillyspec/knowledge/uncategorized.md`；影响多个子项目 → 写入工作区根目录 `.sillyspec/knowledge/uncategorized.md`。
 
-10. **记录发现的坑：** 执行过程中如果发现项目特有的规律、陷阱或约定（如"某方法参数顺序容易搞反"、"某表有隐藏软删除字段"），追加到 CONVENTIONS.md 的「注意事项」章节。**工作区模式下：** 只影响当前子项目 → 写入当前子项目 `.sillyspec/codebase/CONVENTIONS.md`；影响多个子项目 → 写入 `.sillyspec/shared/CONVENTIONS.md`（共享规范，所有子项目可见）。
+12. **知识库审阅提示：** 如果本次执行向 knowledge/ 写入了新条目，提示用户：
+> 📚 本次 quick 发现了新知识，请审阅：`cat .sillyspec/knowledge/uncategorized.md`
+> 确认后请将 `[待确认]` 改为 `[已确认]`，并可归类到 knowledge/ 下的专题文件中更新 INDEX.md。
 
 ### QUICKLOG 规则
 
@@ -67,7 +85,6 @@ LOG_FILE=".sillyspec/quicklog/QUICKLOG-${USER}.md"
 ```markdown
 ## YYYY-MM-DD HH:MM:SS | fix: 任务描述
 - 文件：`修改的文件列表`
-- commit：`commit hash`
 - 关联归档：`相关的已归档变更名`（如有）
 ```
 

package/templates/scan-quick.md

@@ -34,13 +34,15 @@ find . -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "
 3. **CONVENTIONS.md** — 空骨架文件，含章节标题（注意事项、代码风格等），供后续 quick/execute 追加
 4. **PROJECT.md** — 项目概览
 
-### Step 4: Git 提交
+### Step 4: 暂存修改
 
 ```bash
-git add .sillyspec/ && git commit -m "chore: sillyspec quick scan"
+git add .sillyspec/
 ```
 
-工作区模式在每个子项目分别提交。
+工作区模式在每个子项目分别暂存。
+
+💡 扫描产出已暂存。准备好后用 `/sillyspec:commit` 提交。
 
 ### 完成
 

package/templates/scan.md

@@ -112,15 +112,40 @@ for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJEC
   [ -f ".sillyspec/codebase/${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 → 文件路径 -->
+<!-- 示例：mybatis-plus|分页|Page → pagination.md -->
+<!-- 示例：跨域|CORS|preflight → cors.md -->
+EOF
+fi
+if [ ! -f ".sillyspec/knowledge/uncategorized.md" ]; then
+  cat > .sillyspec/knowledge/uncategorized.md << 'EOF'
+# 未分类知识
+
+> execute/quick 执行中发现的坑暂存于此，用户审阅后归类到对应文件并更新 INDEX.md。
+
+EOF
+fi
+
 # 验证 CLI
 sillyspec status --json   # 应返回 phase: "brainstorm"
 sillyspec next            # 推荐给用户
 
-# 清理 + 提交
+# 清理
 rm -f .sillyspec/codebase/_env-detect.md
-git add .sillyspec/ && git commit -m "chore: sillyspec scan - codebase mapped"
+git add .sillyspec/
 ```
 
+💡 扫描产出已暂存。准备好后用 `/sillyspec:commit` 提交。
+
 ### 自检门控
 - [ ] ARCHITECTURE.md：技术栈 + Schema 摘要？
 - [ ] CONVENTIONS.md：隐形规则 + 代码风格？