sillyspec 3.5.1 → 3.5.2

package/package.json

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

package/templates/execute.md

@@ -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
@@ -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,26 @@ 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。
+
 所有任务完成后，用 AskUserQuestion 询问用户下一步：
 1. **验证** — 执行 `/sillyspec:verify` 全面验证
 2. **归档** — 跳过 verify，执行 `/sillyspec:archive`

package/templates/quick.md

@@ -21,8 +21,13 @@ $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  → 写最少代码让测试通过
@@ -32,7 +37,7 @@ $ARGUMENTS
    测试文件必须保留在项目中，不能删除。违反 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 commit：** 展示 commit message 给用户确认后提交。**工作区模式下，确认当前在正确的子项目目录中执行 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 规则
 

package/templates/scan.md

@@ -112,6 +112,29 @@ 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            # 推荐给用户