sillyspec 3.1.0 → 3.3.0

package/templates/scan.md

@@ -1,258 +1,135 @@
 ## 交互规范
 **当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
 
-## 核心约束（必须遵守）
-- ❌ 修改任何代码
-- ❌ 编造文件路径或代码模式（必须包含真实路径）
-- ❌ 一次性输出所有步骤（交互模式每步等用户回复）
-- ❌ 跳过状态检查，自行推断项目阶段
-- ❌ 跳过 Schema/框架隐形规则/实体继承扫描
-- ❌ 生成文档到非 `.sillyspec/codebase/` 目录
+你现在是 SillySpec 代码库扫描器（编排器）。**你不读源码，只编排子代理或串行执行。**
 
-## 状态检查（必须先执行）
+## 参数处理
+- 空白 → 交互式引导（逐步询问）
+- `--deep` → 直接深度扫描
+- 其他 → 快速扫描该区域
+
+## 流程控制（必须先执行）
 
 ```bash
 sillyspec status --json
 ```
 
-- `phase: "init"` 或无 phase → 继续
-- `phase: "scan:quick_done"` → 建议深度扫描
-- `phase: "scan:resume"` → `sillyspec check --json` 获取缺失文档，断点续扫
-- 其他 phase → 不需要扫描，提示 CLI 建议的下一步
-
-## 参数处理
-
-`$ARGUMENTS` 为空 → **交互式引导模式**；有内容 → **快速模式**（含 `--deep` 则深度扫描，否则快速扫描该区域）。快速模式跳到对应 Step。
+非 `init` phase → 以 CLI 返回为准决定下一步。
 
 ---
 
-## 交互式引导流程
-
-### Step 1: 检查工作区模式
-
-```bash
-cat .sillyspec/config.yaml 2>/dev/null
-```
-
-有 `projects` 字段 → 工作区模式：选择全量扫描、选子项目扫描、或退出。子项目文档存到各自 `<子项目路径>/.sillyspec/codebase/`，最后生成 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`。
+## 交互式引导（参数为空时）
 
-### Step 2: 检查已有文档
+### 检查工作区 & 已有文档
 
 ```bash
-ls .sillyspec/codebase/ 2>/dev/null
+cat .sillyspec/config.yaml 2>/dev/null   # 有 projects → 工作区模式
+ls .sillyspec/codebase/ 2>/dev/null       # 检查已有文档
+wc -l .sillyspec/codebase/*.md 2>/dev/null
 ```
 
-- 无文档 → 直接选扫描模式
-- 3 份（快扫完成）→ 升级完整扫描 / 重新快扫 / 跳过
-- 7 份（深扫完成）→ 检查距上次扫描时间和新提交数，建议刷新或跳过
-- 用户选跳过 → 提示 `/sillyspec:brainstorm '你的需求'` 并结束
-
-### Step 3-5: 扫描模式、范围、排除目录
-
-AskUserQuestion 依次确认：快速⚡/深度🔍、扫描范围（留空全量）、排除目录（默认选中 `node_modules`、`.git`、`dist`、`build`、`vendor`、`target`、`__pycache__`、`.next`、`coverage`、`.nuxt`，用户可调整）。
+- 已有 3 份 → 建议升级深度扫描
+- 已有 7 份 → 建议刷新或跳过
+- 工作区 → 逐个扫描 / 选子项目 / 退出
 
-### Step 6: 确认并开始
-
-汇总选择，用户确认后执行。
+### 选择扫描模式、范围、排除目录、确认
+按原流程交互，确认后进入扫描。
 
 ---
 
-## 快速扫描
-
-**只读入口和配置文件，不读源码。** 生成 3 份文档到 `mkdir -p .sillyspec/codebase`：
+## 构建环境探测（主代理执行）
 
-1. `ARCHITECTURE.md` — 架构 + 技术栈（合并原 STACK.md）
-2. `STRUCTURE.md` — 目录结构
-3. `PROJECT.md` — 项目概览
-
-扫描命令：
 ```bash
-# 配置文件
-cat package.json tsconfig.json requirements.txt Cargo.toml go.mod pom.xml build.gradle 2>/dev/null
+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
-# 目录结构
-find . -type f -not -path "*/node_modules/*" -not -path "*/{dist,.git,vendor,build,__pycache__,.next,coverage,.nuxt,target}/*" | head -200
-# 最近提交
-git log --oneline -20
 ```
 
-## 🚨 三项强制扫描（快速和深度都必须执行）
-
-### A. 数据库 Schema 扫描
-
-**目的：** 防止后续阶段编造表名和字段名。
-
-```bash
-find . \( -name "schema.prisma" -o -name "*.model.ts" -o -name "*.entity.ts" -o -name "models.py" -o -name "models.go" -o -name "*.sql" -o -name "migration*" -o -name "*.entity.java" -o -name "*Mapper.xml" -o -name "schema.ts" \) \
-  -not -path "*/node_modules/*" -not -path "*/{.git,dist,build,vendor}/*" | head -30
-```
-
-**写入 ARCHITECTURE.md（只记摘要，不展开字段）：**
-
-```markdown
-## 数据模型（摘要）
-| 表名 | 说明 | 字段数 | 来源文件 |
-|---|---|---|---|
-| users | 用户表 | 12 | `src/entity/User.java` |
-
-### 关系
-- users 1:N orders
-```
-
-无数据库 → 写"本项目无数据库"。**铁律：所有阶段引用的表名必须来自此摘要，或 design.md 中声明的新增表。**
-
-### B. 框架隐形规则扫描
-
-**目的：** 防止 AI 生成的 SQL/代码违反框架自动处理机制（如自动注入字段、逻辑删除拦截器）。
-
-```bash
-# 通用检测：拦截器、审计、中间件、逻辑删除、多租户
-find . \( -name "*Interceptor*.java" -o -name "*Plugin*.java" -o -name "*Auditor*.java" \
-  -o -name "*EventListener*.java" -o -name "mybatis-config.xml" -o -name "settings.py" \
-  -o -name "*event*.py" -o -name "*listener*.py" -o -name "*mixin*.py" \) \
-  -not -path "*/node_modules/*" -not -path "*/{.git,dist,build,vendor}/*" | head -20
-# 框架特定：Prisma/GORM/TypeORM/Rails/Laravel 中间件和回调
-cat prisma/schema.prisma 2>/dev/null | grep -i "middleware\|plugin\|previewFeatures"
-find . \( -name "*.go" -o -name "*.ts" -o -name "*.rb" -o -name "*.php" \) \
-  -not -path "*/{node_modules,vendor}/*" | xargs grep -l "Callback\|Plugin\|EventSubscriber\|BeforeInsert\|acts_as_paranoid\|acts_as_tenant" 2>/dev/null | head -10
-# 逻辑删除/多租户字段
-find . \( -name "*.java" -o -name "*.py" -o -name "*.go" -o -name "*.ts" -o -name "*.php" \) \
-  -not -path "*/{node_modules,.git,vendor,dist,build}/*" | xargs grep -li "is_deleted\|deleted_at\|soft_delete\|tenant_id" 2>/dev/null | head -20
-```
-
-**写入 CONVENTIONS.md：**
-
-```markdown
-## 框架隐形规则
-### 自动注入字段（SQL 中不要手动写）
-| 字段 | 来源 | 说明 |
-|---|---|---|
-
-### 自动填充字段（INSERT/UPDATE 不需要手动赋值）
-| 字段 | 来源 | 说明 |
-|---|---|---|
-
-### DELETE 行为
-- 不要写 `DELETE FROM` → 使用逻辑删除（如 UPDATE xxx SET is_deleted=1）
-```
-
-无发现 → 写"未发现框架级别的自动处理配置"。**铁律：后续阶段生成 SQL/数据操作代码必须遵守这些规则。**
-
-### C. 实体继承规范扫描
-
-**目的：** 防止新建表时漏掉基类通用字段，导致 ORM 查询报 Unknown column。
-
-```bash
-find . \( -name "Base*.java" -o -name "Abstract*.java" \) \
-  \( -path "*/entity/*" -o -path "*/model/*" -o -path "*/po/*" \) \
-  -not -path "*/{node_modules,.git}/*" | head -20
-find . -name "*.java" -not -path "*/{node_modules,.git}/*" | xargs grep -l "@MappedSuperclass" 2>/dev/null | head -10
-```
-
-**追加到 CONVENTIONS.md：**
-
-```markdown
-## 实体继承规范
-### 基类通用字段（新建表必须包含）
-| 字段 | 类型 | 说明 |
-|---|---|---|
-（从扫描到的基类源码中提取，不编造）
-
-### 铁律：新建表 DDL 必须包含基类所有字段
-```
-
-无基类 → 写"本项目没有实体基类"。
-
-### D. 代码风格深度提取
-
-读取 2-3 个典型的 Controller、Service、ServiceImpl、Entity 源文件，提取具体风格（从源码提取，禁止编造）：
-
-1. **注解风格**：Controller 用 `@RestController` 还是 `@Controller`？方法用什么映射注解？参数校验方式？
-2. **返回值约定**：统一返回 `Result<T>` / `ResponseEntity<T>` / 其他？
-3. **异常处理**：用什么异常类？有没有全局异常处理器？
-4. **Service 层约定**：实现类命名、是否继承基类、基类通用方法、事务注解用法
-5. **实体/POJO 风格**：是否继承基类、Lombok 用法、ID 生成策略、`@TableId`
-6. **Mapper/DAO 风格**：XML Mapper 还是注解？有没有通用 Mapper 基类？
-
-将以上信息写入 CONVENTIONS.md「代码风格」章节。非 Java 项目参考同等概念提取。前端-only 项目写"不适用"。
+结果保存到 `.sillyspec/codebase/_env-detect.md`（临时文件，扫描完删除）。
 
 ---
 
 ## 深度扫描
 
-### Step 0: 预处理脚本
-
-```bash
-bash scripts/scan-preprocess.sh [扫描区域] 2>/dev/null
-```
-
-不存在则跳过。脚本输出 `.sillyspec/codebase/SCAN-RAW.md`（文件统计、配置、结构、import、类名/注解、Schema 位置）。
+`mkdir -p .sillyspec/codebase`
 
-### Step 1: 断点续扫
+### 断点续扫
 
 ```bash
-for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS; do
-  [ -f ".sillyspec/codebase/${f}.md" ] || [ -f ".sillyspec/codebase/details/${f}.md" ] && echo "✅ ${f}" || echo "⬜ ${f}"
+for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT; do
+  [ -f ".sillyspec/codebase/${f}.md" ] && echo "✅ ${f}.md" || echo "⬜ ${f}.md"
 done
 ```
 
-只生成缺失的文档，展示进度后继续。
-
-### Step 2: 基于 SCAN-RAW.md 分析
+只生成缺失的文档。
 
-**不直接读原始源码。** 读 SCAN-RAW.md，按需深挖相关文件。
+### 检测子代理可用性
+检查是否有 Task/Spawn 工具。有 → 子代理模式，无 → 串行模式。
 
-按顺序生成文档（写完立即保存，中断不丢失）：
+---
 
-1. `ARCHITECTURE.md` — 架构 + 技术栈 + 数据模型摘要（合并原 STACK.md）
-2. `CONVENTIONS.md` — 编码约定（含框架隐形规则、实体继承规范）
-3. `codebase/details/STRUCTURE.md` — 目录结构（深扫详情）
-4. `codebase/details/INTEGRATIONS.md` — 集成（深扫详情）
-5. `codebase/details/TESTING.md` — 测试现状（深扫详情）
-6. `codebase/details/CONCERNS.md` — 技术债务和风险（深扫详情）
+### 子代理模式（4 个并行）
 
-同时更新 `.sillyspec/PROJECT.md`。
+#### Agent 1: tech → ARCHITECTURE.md
+扫描技术栈 + 数据库 Schema + 架构模式。参考 `_env-detect.md`。
+用 grep/rg 搜索（`@Entity`、`schema.prisma`、`models.py` 等），**禁止读源码全文**。
+Schema 只记表名+说明+字段数。含 `## 技术栈` `## 架构概览` `## 数据模型（摘要）`。路径用反引号，不编造。
 
-> **注意：** `SCAN-RAW.md` 是临时文件，扫描完成后可删除。
+#### Agent 2: conventions → CONVENTIONS.md
+扫描框架隐形规则 + 实体继承 + 代码风格。参考 `_env-detect.md`。
+用 grep 搜索拦截器/插件/逻辑删除/基类/审计字段，**禁止读源码全文**。
+根据检测到的语言/框架自行决定搜索什么模式，提取 3-5 个典型示例。
+含 `## 框架隐形规则` `## 实体继承规范` `## 代码风格`。路径用反引号，不编造。
 
----
+#### Agent 3: structure → STRUCTURE.md + INTEGRATIONS.md
+扫描目录结构 + 外部集成。参考 `_env-detect.md`。
+用 find/ls/tree 和 grep，**禁止读源码全文**。
+搜索 API 调用、MQ 配置、缓存、第三方 SDK。STRUCTURE.md 含目录树+模块说明。INTEGRATIONS.md 按类型分组。路径用反引号，不编造。
 
-## 完成后
+#### Agent 4: quality → TESTING.md + CONCERNS.md + PROJECT.md
+扫描测试现状 + 技术债务 + 项目概览。参考 `_env-detect.md`。
+用 grep 搜索测试文件、TODO/FIXME、过时依赖，**禁止读源码全文**。
+TESTING.md 含测试结构。CONCERNS.md 按严重程度分组。PROJECT.md 含项目信息。路径用反引号，不编造。
 
-```bash
-sillyspec status --json
-sillyspec next
-```
+---
 
-将 CLI 返回的命令推荐给用户。工作区扫描完成后额外提示生成 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`。
+### 串行模式（降级）
+无子代理时，按 tech → conventions → structure → quality 顺序执行。
+每个 area 完成后**立即写文件**，下一个 area 开始前清除源码上下文。
 
-### Git 提交
+---
 
-```bash
-git add .sillyspec/
-git commit -m "chore: sillyspec scan - codebase mapped"
-```
+## 工作区模式
+对每个子项目：cd → 环境探测 → 扫描 → cd 回工作区。
+全部完成后汇总 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`（只读各子项目的 ARCHITECTURE.md + CONVENTIONS.md）。
 
-### 路径校验 + 自检门控
+---
 
-**路径校验：** 每份文档写完后检查必须在 `.sillyspec/codebase/` 下，误放则自动修正：
+## 扫描完成
 
 ```bash
-for f in $(find . -maxdepth 2 -name "{ARCHITECTURE,STRUCTURE,CONVENTIONS,INTEGRATIONS,TESTING,CONCERNS,PROJECT,SCAN-RAW}.md" ! -path "./.sillyspec/codebase/*" ! -path "./.sillyspec/codebase/details/*"); do
-  [ -f "$f" ] && mkdir -p .sillyspec/codebase && mv "$f" ".sillyspec/codebase/$(basename $f)"
+# 路径校验
+for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT; do
+  [ -f ".sillyspec/codebase/${f}.md" ] && echo "✅ ${f}.md"
 done
-```
 
-**自检门控：**
-- [ ] ARCHITECTURE.md 含主要语言、框架和整体架构？
-- [ ] ARCHITECTURE.md 含数据模型摘要？（深扫）
-- [ ] STRUCTURE.md 含目录结构？（深扫，位于 details/）
-- [ ] CONVENTIONS.md 含编码约定？（深扫）
-- [ ] INTEGRATIONS.md 列出外部依赖？（深扫，位于 details/）
-- [ ] TESTING.md 描述测试状况？（深扫，位于 details/）
-- [ ] CONCERNS.md 列出技术债务？（深扫，位于 details/）
-- [ ] PROJECT.md 已生成？
+# 验证 CLI
+sillyspec status --json   # 应返回 phase: "brainstorm"
+sillyspec next            # 推荐给用户
 
-```bash
-bash scripts/validate-scan.sh .sillyspec/codebase 2>/dev/null
+# 清理 + 提交
+rm -f .sillyspec/codebase/_env-detect.md
+git add .sillyspec/ && git commit -m "chore: sillyspec scan - codebase mapped"
 ```
+
+### 自检门控
+- [ ] ARCHITECTURE.md：技术栈 + Schema 摘要？
+- [ ] CONVENTIONS.md：隐形规则 + 代码风格？
+- [ ] STRUCTURE.md：目录结构？
+- [ ] INTEGRATIONS.md：外部依赖？
+- [ ] TESTING.md：测试现状？
+- [ ] CONCERNS.md：技术债务？
+- [ ] PROJECT.md：项目概览？
+
+## 绝对规则
+- ❌ 修改代码 / 编造路径 / 主代理读源码全文
+- ✅ 交互模式每步等用户 / 文档只写 `.sillyspec/codebase/`

package/templates/status.md

@@ -14,7 +14,42 @@
 cat .sillyspec/config.yaml 2>/dev/null
 ```
 
-**工作区模式：** 读取 config.yaml 子项目列表，对每个子项目检查 PROJECT.md、codebase 文档数、进行中变更、归档数。检查共享规范和工作区概览。输出汇总后结束，不执行单项目流程。
+**工作区模式：** 读取 config.yaml 子项目列表，对每个子项目检查 PROJECT.md、codebase 文档数、进行中变更、归档数。**同时检查工作区根目录 `.sillyspec/changes/` 下的未归档变更。** 检查共享规范和工作区概览。输出汇总后结束，不执行单项目流程。
+
+工作区变更检查命令：
+```bash
+# 工作区根目录的变更
+ls .sillyspec/changes/ 2>/dev/null | grep -v archive
+ls .sillyspec/changes/archive/ 2>/dev/null | wc -l
+
+# 每个子项目的变更
+for proj in $(cat .sillyspec/config.yaml | grep -oP 'path:\s*\K.*'); do
+  echo "=== $(basename $proj) changes ==="
+  ls "$proj/.sillyspec/changes/" 2>/dev/null | grep -v archive
+  ls "$proj/.sillyspec/changes/archive/" 2>/dev/null | wc -l
+done
+```
+
+**汇总输出格式：**
+```
+📊 SillySpec 状态
+📋 工作区模式 — N 个子项目
+
+工作区变更：
+  🔄 进行中：sec-bonus-penalty（tasks: 3/5）
+  ✅ 已归档：1 个
+
+主项目（工作区根目录）：
+  📂 代码库文档：— （主项目通常无独立代码）
+  🔄 进行中：N 个变更
+  ✅ 已归档：N 个变更
+
+┌───────────────────┬────────────┬────────────┬────────┬────────┐
+│ 子项目            │ PROJECT.md │ 代码库文档 │ 进行中 │ 已归档 │
+├───────────────────┼────────────┼────────────┼────────┼────────┤
+│ back-service      │ ✗          │ 7 份       │ 1      │ 0      │
+└───────────────────┴────────────┴────────────┴────────┴────────┘
+```
 
 **单项目模式：** 继续 Step 2。
 

package/templates/verify.md

@@ -11,11 +11,27 @@
 ## 状态检查（必须先执行）
 
 ```bash
-sillyspec status --json
+cat .sillyspec/STATE.md 2>/dev/null
 ```
 
-- `phase: "verify"` → ✅ 继续
-- 其他 phase → 提示 `sillyspec next`
+检查当前阶段。如果没有 STATE.md，检查是否有未归档变更：
+
+```bash
+ls .sillyspec/changes/ 2>/dev/null | grep -v archive
+```
+
+无 STATE.md 且无未归档变更 → 提示用户先完成 execute 或用 `/sillyspec:status` 查看状态。
+
+---
+
+## 工作区模式处理
+
+如果 `.sillyspec/config.yaml` 包含 `projects` 字段：
+
+1. 检查工作区根目录 `.sillyspec/changes/` 下的未归档变更
+2. 检查每个子项目 `<子项目路径>/.sillyspec/changes/` 下的未归档变更
+3. 列出所有未归档变更，让用户选择要验证哪个
+4. 根据 $ARGUMENTS 或用户选择，cd 到对应目录执行验证
 
 ---
 
@@ -24,8 +40,13 @@ sillyspec status --json
 ### 1. 加载规范
 
 ```bash
-LATEST=$(ls -d .sillyspec/changes/*/ | grep -v archive | tail -1)
-cat "$LATEST"/{design,tasks}.md 2>/dev/null
+# 确定变更目录
+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
 ```
 
 锚定确认实际存在的文件。
@@ -61,14 +82,6 @@ grep -r "TODO\|FIXME\|HACK\|XXX" src/ lib/ app/ --include="*.ts" --include="*.ts
 ## 结论：✅ PASS / ⚠️ PASS WITH NOTES / ❌ FAIL
 ```
 
-```bash
-bash scripts/validate-all.sh 2>/dev/null
-```
-
 ### 7. 完成
 
-```bash
-sillyspec status --json && sillyspec next
-```
-
-更新 `.sillyspec/STATE.md`：阶段改为 `verify ✅` 或 `verify ⚠️`。
+更新 `.sillyspec/STATE.md`（如存在）：阶段改为 `verify ✅` 或 `verify ⚠️`。