sillyspec 3.2.1 → 3.3.0

package/.claude/commands/sillyspec/scan-quick.md

@@ -0,0 +1,46 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+> 本模板由 `/sillyspec:scan --quick` 触发。如需完整深度扫描，使用 `/sillyspec:scan`。
+
+## 核心约束（必须遵守）
+- ❌ 修改任何代码
+- ❌ 编造文件路径或代码模式（必须包含真实路径）
+- ❌ 读源码文件（快扫只读配置和目录）
+
+## 快速扫描流程
+
+### Step 1: 检查工作区模式
+
+```bash
+cat .sillyspec/config.yaml 2>/dev/null
+```
+
+有 `projects` 字段 → 工作区模式：逐个子项目快扫。
+
+### Step 2: 读配置文件
+
+```bash
+cat package.json tsconfig.json requirements.txt Cargo.toml go.mod pom.xml build.gradle 2>/dev/null
+find . -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null
+```
+
+### Step 3: 生成文档
+
+`mkdir -p .sillyspec/codebase`，生成 3 份文档：
+
+1. **ARCHITECTURE.md** — 架构 + 技术栈（合并原 STACK.md）
+2. **STRUCTURE.md** — 目录结构（`find . -type f | head -200`）
+3. **PROJECT.md** — 项目概览
+
+### Step 4: Git 提交
+
+```bash
+git add .sillyspec/ && git commit -m "chore: sillyspec quick scan"
+```
+
+工作区模式在每个子项目分别提交。
+
+### 完成
+
+提示用户：快扫只提取基础信息。如需完整代码规范（框架规则、实体继承、代码风格），执行 `/sillyspec:scan` 进行深度扫描。

package/.claude/commands/sillyspec/scan.md

@@ -1,347 +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
+cat .sillyspec/config.yaml 2>/dev/null   # 有 projects → 工作区模式
+ls .sillyspec/codebase/ 2>/dev/null       # 检查已有文档
+wc -l .sillyspec/codebase/*.md 2>/dev/null
 ```
 
-有 `projects` 字段 → 工作区模式：选择全量扫描、选子项目扫描、或退出。子项目文档存到各自 `<子项目路径>/.sillyspec/codebase/`，最后生成 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`。
-
-### Step 2: 检查已有文档
-
-```bash
-ls .sillyspec/codebase/ 2>/dev/null
-```
-
-- 无文档 → 直接选扫描模式
-- 3 份（快扫完成）→ 升级完整扫描 / 重新快扫 / 跳过
-- 7 份（深扫完成）→ 检查距上次扫描时间和新提交数，建议刷新或跳过
-- 用户选跳过 → 提示 `/sillyspec:brainstorm '你的需求'` 并结束
-
-### Step 3-5: 扫描模式、范围、排除目录
-
-AskUserQuestion 依次确认：快速⚡/深度🔍、扫描范围（留空全量）、排除目录（默认选中 `node_modules`、`.git`、`dist`、`build`、`vendor`、`target`、`__pycache__`、`.next`、`coverage`、`.nuxt`，用户可调整）。
-
-### Step 6: 确认并开始
+- 已有 3 份 → 建议升级深度扫描
+- 已有 7 份 → 建议刷新或跳过
+- 工作区 → 逐个扫描 / 选子项目 / 退出
 
-汇总选择，用户确认后执行。
-
-### 🚨 工作区扫描铁律（防止上下文爆炸）
-
-**工作区模式下，必须逐个子项目扫描并写入，禁止跨子项目累积上下文：**
-
-```
-子项目 A → 读取 → 写入文档 → 清理上下文
-子项目 B → 读取 → 写入文档 → 清理上下文
-...
-最后 → 生成 CODEBASE-OVERVIEW.md
-```
-
-- ✅ 每个子项目扫描完成后**立即写入** `.sillyspec/codebase/` 文件
-- ✅ 写入后**不再回头读**该子项目的源码
-- ❌ 禁止同时读取多个子项目的源码再一次性全部写入
-- ❌ 禁止在一个子项目扫描过程中去读另一个子项目的文件
-
-**CODEBASE-OVERVIEW.md** 只读各子项目已生成的 ARCHITECTURE.md + CONVENTIONS.md（不读源码），生成汇总。
+### 选择扫描模式、范围、排除目录、确认
+按原流程交互，确认后进入扫描。
 
 ---
 
-## 快速扫描
-
-**只读入口和配置文件，不读源码。** 生成 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. 构建环境探测（IDE vs 终端差异修复）
-
-**目的：** 解决 IDEA 有私服配置但终端跑不了 `mvn test` / `npm test` 的问题。
-
-**探测步骤：**
-
-```bash
-# 检测项目使用的构建工具
-ls pom.xml build.gradle package.json requirements.txt go.mod Cargo.toml pyproject.toml 2>/dev/null
-# 检测是否有 wrapper
-ls mvnw gradlew package-lock.json yarn.lock pnpm-lock.yaml 2>/dev/null
-# 检测是否有 IDEA 特殊配置
-grep -r "mavenHome\|settings\.xml\|gradleHome\|nodeInterpreter" .idea/workspace.xml 2>/dev/null | head -5
-# 检测是否有本地配置文件
-cat .mvn/maven.config 2>/dev/null
-cat .mvn/jvm.config 2>/dev/null
-cat .npmrc 2>/dev/null
-cat pip.conf .pip/pip.conf ~/.pip/pip.conf 2>/dev/null
-cat ~/.gradle/gradle.properties 2>/dev/null
-```
-
-**AskUserQuestion 询问用户：**
-
-> "检测到本项目使用 [Maven/Gradle/npm/pip/Go]，终端执行构建命令时是否需要特殊配置？"
-> 选项：
-> - 不需要，默认配置就能跑
-> - 需要指定配置文件（如 Maven 的 settings.xml）→ 让用户输入路径
-> - 需要额外参数（如私服地址、代理等）→ 让用户输入
-> - 不确定，先试试默认命令
-
-**如果用户选择了需要配置，测试默认命令是否能跑通：**
-
-```bash
-# Maven
-mvn test -s <用户提供的路径> --fail-at-end 2>&1 | tail -5
-# Gradle
-./gradlew test 2>&1 | tail -5 || gradle test 2>&1 | tail -5
-# npm
-npm test 2>&1 | tail -5 || pnpm test 2>&1 | tail -5
-# pip
-pip install -e . 2>&1 | tail -5 && pytest --collect-only 2>&1 | tail -5
-# Go
-go test ./... 2>&1 | tail -5
-```
-
-**写入 `.sillyspec/local.yaml`（本地记忆文件，不提交到 git）：**
-
-此文件存储每个开发者独立的本地配置。如果文件已存在则追加，已有字段则跳过：
-
-```yaml
-# .sillyspec/local.yaml — 本地记忆文件（已在 .gitignore 中，不提交）
-# 每个开发者独立配置，clone 后重新 scan 即可生成
-
-build:
-  tool: maven
-  test_cmd: 'mvn test -s "D:/software/maven/conf/settings.xml"'
-  compile_cmd: 'mvn compile -s "D:/software/maven/conf/settings.xml"'
-  single_test_cmd: 'mvn test -s "D:/software/maven/conf/settings.xml" -pl {module} -Dtest={test_class}'
-```
-
-**铁律：后续 execute / verify 阶段执行构建或测试命令时，必须先读取 `.sillyspec/local.yaml` 中的 build 配置，使用记录的命令执行。如果 local.yaml 不存在或无 build 配置，使用默认命令。**
-
-无构建工具 → 跳过此步骤。
-
-### B. 数据库 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 中声明的新增表。**
-
-### C. 框架隐形规则扫描
-
-**目的：** 防止 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/数据操作代码必须遵守这些规则。**
-
-### D. 实体继承规范扫描
-
-**目的：** 防止新建表时漏掉基类通用字段，导致 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 必须包含基类所有字段
-```
-
-无基类 → 写"本项目没有实体基类"。
-
-### E. 代码风格深度提取
-
-读取 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
 ```
 
-只生成缺失的文档，展示进度后继续。
+只生成缺失的文档。
+
+### 检测子代理可用性
+检查是否有 Task/Spawn 工具。有 → 子代理模式，无 → 串行模式。
 
-### Step 2: 基于 SCAN-RAW.md 分析
+---
 
-**不直接读原始源码。** 读 SCAN-RAW.md，按需深挖相关文件。
+### 子代理模式（4 个并行）
 
-按顺序生成文档（写完立即保存，中断不丢失）：
+#### Agent 1: tech → ARCHITECTURE.md
+扫描技术栈 + 数据库 Schema + 架构模式。参考 `_env-detect.md`。
+用 grep/rg 搜索（`@Entity`、`schema.prisma`、`models.py` 等），**禁止读源码全文**。
+Schema 只记表名+说明+字段数。含 `## 技术栈` `## 架构概览` `## 数据模型（摘要）`。路径用反引号，不编造。
 
-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` — 技术债务和风险（深扫详情）
+#### Agent 2: conventions → CONVENTIONS.md
+扫描框架隐形规则 + 实体继承 + 代码风格。参考 `_env-detect.md`。
+用 grep 搜索拦截器/插件/逻辑删除/基类/审计字段，**禁止读源码全文**。
+根据检测到的语言/框架自行决定搜索什么模式，提取 3-5 个典型示例。
+含 `## 框架隐形规则` `## 实体继承规范` `## 代码风格`。路径用反引号，不编造。
 
-同时更新 `.sillyspec/PROJECT.md`。
+#### Agent 3: structure → STRUCTURE.md + INTEGRATIONS.md
+扫描目录结构 + 外部集成。参考 `_env-detect.md`。
+用 find/ls/tree 和 grep，**禁止读源码全文**。
+搜索 API 调用、MQ 配置、缓存、第三方 SDK。STRUCTURE.md 含目录树+模块说明。INTEGRATIONS.md 按类型分组。路径用反引号，不编造。
 
-> **注意：** `SCAN-RAW.md` 是临时文件，扫描完成后可删除。
+#### Agent 4: quality → TESTING.md + CONCERNS.md + PROJECT.md
+扫描测试现状 + 技术债务 + 项目概览。参考 `_env-detect.md`。
+用 grep 搜索测试文件、TODO/FIXME、过时依赖，**禁止读源码全文**。
+TESTING.md 含测试结构。CONCERNS.md 按严重程度分组。PROJECT.md 含项目信息。路径用反引号，不编造。
 
 ---
 
-## 完成后
+### 串行模式（降级）
+无子代理时，按 tech → conventions → structure → quality 顺序执行。
+每个 area 完成后**立即写文件**，下一个 area 开始前清除源码上下文。
 
-```bash
-sillyspec status --json
-sillyspec next
-```
+---
 
-将 CLI 返回的命令推荐给用户。工作区扫描完成后额外提示生成 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`。
+## 工作区模式
+对每个子项目：cd → 环境探测 → 扫描 → cd 回工作区。
+全部完成后汇总 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`（只读各子项目的 ARCHITECTURE.md + CONVENTIONS.md）。
 
-### Git 提交
+---
 
-**单项目模式：**
-```bash
-git add .sillyspec/ && git commit -m "chore: sillyspec scan - codebase mapped"
-```
+## 扫描完成
 
-**工作区模式：** 在每个子项目目录分别 commit（主工作区无 git 则跳过）：
 ```bash
-for proj in $(cat .sillyspec/config.yaml | grep -oP 'path:\s*\K.*'); do
-  cd "$proj" && git add .sillyspec/ 2>/dev/null && git commit -m "chore: sillyspec scan - codebase mapped" && cd - > /dev/null
+# 路径校验
+for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT; do
+  [ -f ".sillyspec/codebase/${f}.md" ] && echo "✅ ${f}.md"
 done
-```
 
-### 路径校验 + 自检门控
+# 验证 CLI
+sillyspec status --json   # 应返回 phase: "brainstorm"
+sillyspec next            # 推荐给用户
 
-**路径校验：** 每份文档写完后检查必须在 `.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)"
-done
+# 清理 + 提交
+rm -f .sillyspec/codebase/_env-detect.md
+git add .sillyspec/ && git commit -m "chore: sillyspec scan - codebase mapped"
 ```
 
-**自检门控：**
-- [ ] ARCHITECTURE.md 含主要语言、框架和整体架构？
-- [ ] ARCHITECTURE.md 含数据模型摘要？（深扫）
-- [ ] STRUCTURE.md 含目录结构？（深扫，位于 details/）
-- [ ] CONVENTIONS.md 含编码约定？（深扫）
-- [ ] INTEGRATIONS.md 列出外部依赖？（深扫，位于 details/）
-- [ ] TESTING.md 描述测试状况？（深扫，位于 details/）
-- [ ] CONCERNS.md 列出技术债务？（深扫，位于 details/）
-- [ ] PROJECT.md 已生成？
+### 自检门控
+- [ ] ARCHITECTURE.md：技术栈 + Schema 摘要？
+- [ ] CONVENTIONS.md：隐形规则 + 代码风格？
+- [ ] STRUCTURE.md：目录结构？
+- [ ] INTEGRATIONS.md：外部依赖？
+- [ ] TESTING.md：测试现状？
+- [ ] CONCERNS.md：技术债务？
+- [ ] PROJECT.md：项目概览？
 
-```bash
-bash scripts/validate-scan.sh .sillyspec/codebase 2>/dev/null
-```
+## 绝对规则
+- ❌ 修改代码 / 编造路径 / 主代理读源码全文
+- ✅ 交互模式每步等用户 / 文档只写 `.sillyspec/codebase/`

package/.claude/commands/sillyspec/status.md

@@ -39,6 +39,11 @@ done
   🔄 进行中：sec-bonus-penalty（tasks: 3/5）
   ✅ 已归档：1 个
 
+主项目（工作区根目录）：
+  📂 代码库文档：— （主项目通常无独立代码）
+  🔄 进行中：N 个变更
+  ✅ 已归档：N 个变更
+
 ┌───────────────────┬────────────┬────────────┬────────┬────────┐
 │ 子项目            │ PROJECT.md │ 代码库文档 │ 进行中 │ 已归档 │
 ├───────────────────┼────────────┼────────────┼────────┼────────┤

package/package.json

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

package/templates/scan-quick.md

@@ -0,0 +1,46 @@
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
+
+> 本模板由 `/sillyspec:scan --quick` 触发。如需完整深度扫描，使用 `/sillyspec:scan`。
+
+## 核心约束（必须遵守）
+- ❌ 修改任何代码
+- ❌ 编造文件路径或代码模式（必须包含真实路径）
+- ❌ 读源码文件（快扫只读配置和目录）
+
+## 快速扫描流程
+
+### Step 1: 检查工作区模式
+
+```bash
+cat .sillyspec/config.yaml 2>/dev/null
+```
+
+有 `projects` 字段 → 工作区模式：逐个子项目快扫。
+
+### Step 2: 读配置文件
+
+```bash
+cat package.json tsconfig.json requirements.txt Cargo.toml go.mod pom.xml build.gradle 2>/dev/null
+find . -maxdepth 2 -name "*.config.*" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20 | xargs cat 2>/dev/null
+```
+
+### Step 3: 生成文档
+
+`mkdir -p .sillyspec/codebase`，生成 3 份文档：
+
+1. **ARCHITECTURE.md** — 架构 + 技术栈（合并原 STACK.md）
+2. **STRUCTURE.md** — 目录结构（`find . -type f | head -200`）
+3. **PROJECT.md** — 项目概览
+
+### Step 4: Git 提交
+
+```bash
+git add .sillyspec/ && git commit -m "chore: sillyspec quick scan"
+```
+
+工作区模式在每个子项目分别提交。
+
+### 完成
+
+提示用户：快扫只提取基础信息。如需完整代码规范（框架规则、实体继承、代码风格），执行 `/sillyspec:scan` 进行深度扫描。

package/templates/scan.md

@@ -1,347 +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
+cat .sillyspec/config.yaml 2>/dev/null   # 有 projects → 工作区模式
+ls .sillyspec/codebase/ 2>/dev/null       # 检查已有文档
+wc -l .sillyspec/codebase/*.md 2>/dev/null
 ```
 
-有 `projects` 字段 → 工作区模式：选择全量扫描、选子项目扫描、或退出。子项目文档存到各自 `<子项目路径>/.sillyspec/codebase/`，最后生成 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`。
-
-### Step 2: 检查已有文档
-
-```bash
-ls .sillyspec/codebase/ 2>/dev/null
-```
-
-- 无文档 → 直接选扫描模式
-- 3 份（快扫完成）→ 升级完整扫描 / 重新快扫 / 跳过
-- 7 份（深扫完成）→ 检查距上次扫描时间和新提交数，建议刷新或跳过
-- 用户选跳过 → 提示 `/sillyspec:brainstorm '你的需求'` 并结束
-
-### Step 3-5: 扫描模式、范围、排除目录
-
-AskUserQuestion 依次确认：快速⚡/深度🔍、扫描范围（留空全量）、排除目录（默认选中 `node_modules`、`.git`、`dist`、`build`、`vendor`、`target`、`__pycache__`、`.next`、`coverage`、`.nuxt`，用户可调整）。
-
-### Step 6: 确认并开始
+- 已有 3 份 → 建议升级深度扫描
+- 已有 7 份 → 建议刷新或跳过
+- 工作区 → 逐个扫描 / 选子项目 / 退出
 
-汇总选择，用户确认后执行。
-
-### 🚨 工作区扫描铁律（防止上下文爆炸）
-
-**工作区模式下，必须逐个子项目扫描并写入，禁止跨子项目累积上下文：**
-
-```
-子项目 A → 读取 → 写入文档 → 清理上下文
-子项目 B → 读取 → 写入文档 → 清理上下文
-...
-最后 → 生成 CODEBASE-OVERVIEW.md
-```
-
-- ✅ 每个子项目扫描完成后**立即写入** `.sillyspec/codebase/` 文件
-- ✅ 写入后**不再回头读**该子项目的源码
-- ❌ 禁止同时读取多个子项目的源码再一次性全部写入
-- ❌ 禁止在一个子项目扫描过程中去读另一个子项目的文件
-
-**CODEBASE-OVERVIEW.md** 只读各子项目已生成的 ARCHITECTURE.md + CONVENTIONS.md（不读源码），生成汇总。
+### 选择扫描模式、范围、排除目录、确认
+按原流程交互，确认后进入扫描。
 
 ---
 
-## 快速扫描
-
-**只读入口和配置文件，不读源码。** 生成 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. 构建环境探测（IDE vs 终端差异修复）
-
-**目的：** 解决 IDEA 有私服配置但终端跑不了 `mvn test` / `npm test` 的问题。
-
-**探测步骤：**
-
-```bash
-# 检测项目使用的构建工具
-ls pom.xml build.gradle package.json requirements.txt go.mod Cargo.toml pyproject.toml 2>/dev/null
-# 检测是否有 wrapper
-ls mvnw gradlew package-lock.json yarn.lock pnpm-lock.yaml 2>/dev/null
-# 检测是否有 IDEA 特殊配置
-grep -r "mavenHome\|settings\.xml\|gradleHome\|nodeInterpreter" .idea/workspace.xml 2>/dev/null | head -5
-# 检测是否有本地配置文件
-cat .mvn/maven.config 2>/dev/null
-cat .mvn/jvm.config 2>/dev/null
-cat .npmrc 2>/dev/null
-cat pip.conf .pip/pip.conf ~/.pip/pip.conf 2>/dev/null
-cat ~/.gradle/gradle.properties 2>/dev/null
-```
-
-**AskUserQuestion 询问用户：**
-
-> "检测到本项目使用 [Maven/Gradle/npm/pip/Go]，终端执行构建命令时是否需要特殊配置？"
-> 选项：
-> - 不需要，默认配置就能跑
-> - 需要指定配置文件（如 Maven 的 settings.xml）→ 让用户输入路径
-> - 需要额外参数（如私服地址、代理等）→ 让用户输入
-> - 不确定，先试试默认命令
-
-**如果用户选择了需要配置，测试默认命令是否能跑通：**
-
-```bash
-# Maven
-mvn test -s <用户提供的路径> --fail-at-end 2>&1 | tail -5
-# Gradle
-./gradlew test 2>&1 | tail -5 || gradle test 2>&1 | tail -5
-# npm
-npm test 2>&1 | tail -5 || pnpm test 2>&1 | tail -5
-# pip
-pip install -e . 2>&1 | tail -5 && pytest --collect-only 2>&1 | tail -5
-# Go
-go test ./... 2>&1 | tail -5
-```
-
-**写入 `.sillyspec/local.yaml`（本地记忆文件，不提交到 git）：**
-
-此文件存储每个开发者独立的本地配置。如果文件已存在则追加，已有字段则跳过：
-
-```yaml
-# .sillyspec/local.yaml — 本地记忆文件（已在 .gitignore 中，不提交）
-# 每个开发者独立配置，clone 后重新 scan 即可生成
-
-build:
-  tool: maven
-  test_cmd: 'mvn test -s "D:/software/maven/conf/settings.xml"'
-  compile_cmd: 'mvn compile -s "D:/software/maven/conf/settings.xml"'
-  single_test_cmd: 'mvn test -s "D:/software/maven/conf/settings.xml" -pl {module} -Dtest={test_class}'
-```
-
-**铁律：后续 execute / verify 阶段执行构建或测试命令时，必须先读取 `.sillyspec/local.yaml` 中的 build 配置，使用记录的命令执行。如果 local.yaml 不存在或无 build 配置，使用默认命令。**
-
-无构建工具 → 跳过此步骤。
-
-### B. 数据库 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 中声明的新增表。**
-
-### C. 框架隐形规则扫描
-
-**目的：** 防止 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/数据操作代码必须遵守这些规则。**
-
-### D. 实体继承规范扫描
-
-**目的：** 防止新建表时漏掉基类通用字段，导致 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 必须包含基类所有字段
-```
-
-无基类 → 写"本项目没有实体基类"。
-
-### E. 代码风格深度提取
-
-读取 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
 ```
 
-只生成缺失的文档，展示进度后继续。
+只生成缺失的文档。
+
+### 检测子代理可用性
+检查是否有 Task/Spawn 工具。有 → 子代理模式，无 → 串行模式。
 
-### Step 2: 基于 SCAN-RAW.md 分析
+---
 
-**不直接读原始源码。** 读 SCAN-RAW.md，按需深挖相关文件。
+### 子代理模式（4 个并行）
 
-按顺序生成文档（写完立即保存，中断不丢失）：
+#### Agent 1: tech → ARCHITECTURE.md
+扫描技术栈 + 数据库 Schema + 架构模式。参考 `_env-detect.md`。
+用 grep/rg 搜索（`@Entity`、`schema.prisma`、`models.py` 等），**禁止读源码全文**。
+Schema 只记表名+说明+字段数。含 `## 技术栈` `## 架构概览` `## 数据模型（摘要）`。路径用反引号，不编造。
 
-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` — 技术债务和风险（深扫详情）
+#### Agent 2: conventions → CONVENTIONS.md
+扫描框架隐形规则 + 实体继承 + 代码风格。参考 `_env-detect.md`。
+用 grep 搜索拦截器/插件/逻辑删除/基类/审计字段，**禁止读源码全文**。
+根据检测到的语言/框架自行决定搜索什么模式，提取 3-5 个典型示例。
+含 `## 框架隐形规则` `## 实体继承规范` `## 代码风格`。路径用反引号，不编造。
 
-同时更新 `.sillyspec/PROJECT.md`。
+#### Agent 3: structure → STRUCTURE.md + INTEGRATIONS.md
+扫描目录结构 + 外部集成。参考 `_env-detect.md`。
+用 find/ls/tree 和 grep，**禁止读源码全文**。
+搜索 API 调用、MQ 配置、缓存、第三方 SDK。STRUCTURE.md 含目录树+模块说明。INTEGRATIONS.md 按类型分组。路径用反引号，不编造。
 
-> **注意：** `SCAN-RAW.md` 是临时文件，扫描完成后可删除。
+#### Agent 4: quality → TESTING.md + CONCERNS.md + PROJECT.md
+扫描测试现状 + 技术债务 + 项目概览。参考 `_env-detect.md`。
+用 grep 搜索测试文件、TODO/FIXME、过时依赖，**禁止读源码全文**。
+TESTING.md 含测试结构。CONCERNS.md 按严重程度分组。PROJECT.md 含项目信息。路径用反引号，不编造。
 
 ---
 
-## 完成后
+### 串行模式（降级）
+无子代理时，按 tech → conventions → structure → quality 顺序执行。
+每个 area 完成后**立即写文件**，下一个 area 开始前清除源码上下文。
 
-```bash
-sillyspec status --json
-sillyspec next
-```
+---
 
-将 CLI 返回的命令推荐给用户。工作区扫描完成后额外提示生成 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`。
+## 工作区模式
+对每个子项目：cd → 环境探测 → 扫描 → cd 回工作区。
+全部完成后汇总 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`（只读各子项目的 ARCHITECTURE.md + CONVENTIONS.md）。
 
-### Git 提交
+---
 
-**单项目模式：**
-```bash
-git add .sillyspec/ && git commit -m "chore: sillyspec scan - codebase mapped"
-```
+## 扫描完成
 
-**工作区模式：** 在每个子项目目录分别 commit（主工作区无 git 则跳过）：
 ```bash
-for proj in $(cat .sillyspec/config.yaml | grep -oP 'path:\s*\K.*'); do
-  cd "$proj" && git add .sillyspec/ 2>/dev/null && git commit -m "chore: sillyspec scan - codebase mapped" && cd - > /dev/null
+# 路径校验
+for f in ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT; do
+  [ -f ".sillyspec/codebase/${f}.md" ] && echo "✅ ${f}.md"
 done
-```
 
-### 路径校验 + 自检门控
+# 验证 CLI
+sillyspec status --json   # 应返回 phase: "brainstorm"
+sillyspec next            # 推荐给用户
 
-**路径校验：** 每份文档写完后检查必须在 `.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)"
-done
+# 清理 + 提交
+rm -f .sillyspec/codebase/_env-detect.md
+git add .sillyspec/ && git commit -m "chore: sillyspec scan - codebase mapped"
 ```
 
-**自检门控：**
-- [ ] ARCHITECTURE.md 含主要语言、框架和整体架构？
-- [ ] ARCHITECTURE.md 含数据模型摘要？（深扫）
-- [ ] STRUCTURE.md 含目录结构？（深扫，位于 details/）
-- [ ] CONVENTIONS.md 含编码约定？（深扫）
-- [ ] INTEGRATIONS.md 列出外部依赖？（深扫，位于 details/）
-- [ ] TESTING.md 描述测试状况？（深扫，位于 details/）
-- [ ] CONCERNS.md 列出技术债务？（深扫，位于 details/）
-- [ ] PROJECT.md 已生成？
+### 自检门控
+- [ ] ARCHITECTURE.md：技术栈 + Schema 摘要？
+- [ ] CONVENTIONS.md：隐形规则 + 代码风格？
+- [ ] STRUCTURE.md：目录结构？
+- [ ] INTEGRATIONS.md：外部依赖？
+- [ ] TESTING.md：测试现状？
+- [ ] CONCERNS.md：技术债务？
+- [ ] PROJECT.md：项目概览？
 
-```bash
-bash scripts/validate-scan.sh .sillyspec/codebase 2>/dev/null
-```
+## 绝对规则
+- ❌ 修改代码 / 编造路径 / 主代理读源码全文
+- ✅ 交互模式每步等用户 / 文档只写 `.sillyspec/codebase/`

package/templates/status.md

@@ -39,6 +39,11 @@ done
   🔄 进行中：sec-bonus-penalty（tasks: 3/5）
   ✅ 已归档：1 个
 
+主项目（工作区根目录）：
+  📂 代码库文档：— （主项目通常无独立代码）
+  🔄 进行中：N 个变更
+  ✅ 已归档：N 个变更
+
 ┌───────────────────┬────────────┬────────────┬────────┬────────┐
 │ 子项目            │ PROJECT.md │ 代码库文档 │ 进行中 │ 已归档 │
 ├───────────────────┼────────────┼────────────┼────────┼────────┤