sillyspec 2.4.3 → 2.5.0

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

@@ -1,672 +1,244 @@
----
-description: 代码库扫描 — 支持快速扫描和深度扫描两阶段
-argument-hint: "[可选：指定区域，如 'api' 或 'auth'] [--deep 深度扫描]"
----
-
-
-你现在是 SillySpec 的代码库扫描器。
-
-## 参数处理
-
-解析 `$ARGUMENTS`：
-- 空白或未提供 → **交互式引导模式**（逐步询问）
-- 包含具体内容 → **快速模式**，直接执行，跳过询问
-  - 含 `--deep` → 深度扫描
-  - 其他内容 → 当作扫描区域（快速扫描该区域）
-
-**以下流程只在交互式引导模式下执行。如果用户传了参数，跳到对应的 Step。**
-
----
+## 交互规范
+**当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。**
 
-## 🛑 流程控制（必须先执行）
+## 核心约束（必须遵守）
+- ❌ 修改任何代码
+- ❌ 编造文件路径或代码模式（必须包含真实路径）
+- ❌ 一次性输出所有步骤（交互模式每步等用户回复）
+- ❌ 跳过状态检查，自行推断项目阶段
+- ❌ 跳过 Schema/框架隐形规则/实体继承扫描
+- ❌ 生成文档到非 `.sillyspec/codebase/` 目录
 
-**在开始任何工作之前，先调用 SillySpec CLI 检查当前状态：**
+## 状态检查（必须先执行）
 
 ```bash
 sillyspec status --json
 ```
 
-**如果 CLI 返回的 phase 不是 "init"，说明已经有扫描数据。** 根据 CLI 返回结果决定：
+- `phase: "init"` 或无 phase → 继续
+- `phase: "scan:quick_done"` → 建议深度扫描
+- `phase: "scan:resume"` → `sillyspec check --json` 获取缺失文档，断点续扫
+- 其他 phase → 不需要扫描，提示 CLI 建议的下一步
 
-- `phase: "scan:quick_done"` → 已有快速扫描，建议深度扫描
-- `phase: "scan:resume"` → 深度扫描中断过，调用 `sillyspec check --json` 获取缺失文档列表
-- `phase` 是其他值 → 不需要扫描，提示用户 CLI 建议的下一步命令
+## 参数处理
 
-**不要自己推断项目状态，以 CLI 返回为准。**
+`$ARGUMENTS` 为空 → **交互式引导模式**；有内容 → **快速模式**（含 `--deep` 则深度扫描，否则快速扫描该区域）。快速模式跳到对应 Step。
 
 ---
 
 ## 交互式引导流程
 
-### Step 0: 检查工作区模式
+### Step 1: 检查工作区模式
 
 ```bash
 cat .sillyspec/config.yaml 2>/dev/null
 ```
 
-如果 config.yaml 存在且包含 `projects` → 工作区模式：
-
-询问用户：
-```
-检测到工作区模式，请选择扫描范围：
-  1) 全部子项目（逐个扫描后生成汇总）
-  2) 指定某个子项目
-  3) 取消
-```
-
-根据选择：
-- 选 1 → 逐个扫描，最后生成 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`
-- 选 2 → 列出子项目让用户选，只扫选中的
-- 选 3 → 退出
+有 `projects` 字段 → 工作区模式：选择全量扫描、选子项目扫描、或退出。子项目文档存到各自 `<子项目路径>/.sillyspec/codebase/`，最后生成 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`。
 
-每个子项目的文档存到各自的 `<子项目路径>/.sillyspec/codebase/` 下。
-
-### Step 1: 检查已有文档
+### Step 2: 检查已有文档
 
 ```bash
 ls .sillyspec/codebase/ 2>/dev/null
-wc -l .sillyspec/codebase/*.md 2>/dev/null
-```
-
-根据已有文档情况智能提示：
-
-**没有任何文档：**
-→ 不提示，直接进入 Step 2 选择扫描模式。
-
-**已有 3 份（STACK + STRUCTURE + PROJECT）：**
-```
-检测到上次的快速扫描结果。
-→ 输入 1 升级为完整扫描（补充 4 份文档）
-→ 输入 2 重新快速扫描（覆盖现有文档）
-→ 输入 3 跳过，直接开始开发
-```
-
-**已有 7 份完整文档：**
-先检查距上次扫描过了多久：
-```bash
-git log -1 --format="%ci" .sillyspec/codebase/ 2>/dev/null
-git log --oneline --since="上次扫描时间" | wc -l
-```
-
-```
-上次扫描距今 X 天，期间有 Y 个新提交。
-→ 输入 1 刷新（重新扫描全部）
-→ 输入 2 跳过，直接开始开发
-```
-
-**用户选跳过** → 输出"可以开始开发了。建议下一步：`/sillyspec:brainstorm '你的需求'`"然后结束。
-
-### Step 2: 选择扫描模式
-
-```
-请选择扫描模式：
-
-  1. 快速扫描 ⚡
-     读取配置文件和目录结构，约 30 秒
-     生成 3 份文档：技术栈 + 目录结构 + 项目概览
-
-  2. 深度扫描 🔍
-     读取全部源代码并分析，约 2-3 分钟
-     生成 7 份文档：技术栈 + 架构 + 目录结构 + 编码约定 + 集成 + 测试 + 技术债务
-
-  3. 取消
 ```
 
-根据选择进入对应的扫描流程。
+- 无文档 → 直接选扫描模式
+- 3 份（快扫完成）→ 升级完整扫描 / 重新快扫 / 跳过
+- 7 份（深扫完成）→ 检查距上次扫描时间和新提交数，建议刷新或跳过
+- 用户选跳过 → 提示 `/sillyspec:brainstorm '你的需求'` 并结束
 
-### Step 3: 选择扫描范围
+### Step 3-5: 扫描模式、范围、排除目录
 
-```
-扫描范围：（留空则扫描整个项目）
-
-  提示：可以输入目录名或模块名，如：
-  - api
-  - src/auth
-  - frontend
-  - 多个区域用空格分隔：api auth
-```
+AskUserQuestion 依次确认：快速⚡/深度🔍、扫描范围（留空全量）、排除目录。
 
-留空 → 全量扫描
-有输入 → 只扫描指定区域
+### Step 6: 确认并开始
 
-### Step 4: 确认排除目录
-
-```
-以下目录将被排除（不扫描）：
-  node_modules  dist  .git  vendor  build  __pycache__
-  .next  coverage  .nuxt  target
-
-是否需要添加额外的排除目录？（留空跳过）
-```
-
-如果用户输入了额外目录 → 追加到排除列表。
-
-### Step 5: 显示扫描计划并确认
-
-把以上选择汇总，让用户最后确认：
-
-```
-扫描计划确认：
-  模式：深度扫描
-  范围：整个项目
-  排除：node_modules, dist, .git, vendor, build, __pycache__, .next, coverage, .nuxt, target
-
-开始扫描？（输入 y 确认，或修改以上选项）
-```
-
-用户确认 → 执行扫描。用户想改 → 回到对应步骤。
+汇总选择，用户确认后执行。
 
 ---
 
 ## 快速扫描
 
-**只读取入口和配置文件，不读源代码：**
+**只读入口和配置文件，不读源码。** 生成 3 份文档到 `mkdir -p .sillyspec/codebase`：
 
+1. `STACK.md` — 技术栈
+2. `STRUCTURE.md` — 目录结构
+3. `PROJECT.md` — 项目概览
+
+扫描命令：
 ```bash
-# 读取配置文件
-cat package.json 2>/dev/null
-cat tsconfig.json 2>/dev/null
-cat requirements.txt 2>/dev/null
-cat Cargo.toml 2>/dev/null
-cat go.mod 2>/dev/null
-cat pom.xml 2>/dev/null
-cat build.gradle 2>/dev/null
+# 配置文件
+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
-
-# 查看目录结构（排除依赖和构建产物）
-find . -type f -not -path "*/node_modules/*" -not -path "*/dist/*" -not -path "*/.git/*" -not -path "*/vendor/*" -not -path "*/build/*" -not -path "*/__pycache__/*" -not -path "*/.next/*" -not -path "*/coverage/*" -not -path "*/.nuxt/*" -not -path "*/target/*" | head -200
-
+# 目录结构
+find . -type f -not -path "*/node_modules/*" -not -path "*/{dist,.git,vendor,build,__pycache__,.next,coverage,.nuxt,target}/*" | head -200
 # 最近提交
 git log --oneline -20
 ```
 
-## 🚨 数据库 Schema 强制扫描（必须执行）
+## 🚨 三项强制扫描（快速和深度都必须执行）
 
-**无论快速还是深度模式，必须执行以下步骤。** 防止 AI 在后续阶段编造表名和字段名。
+### A. 数据库 Schema 扫描
 
-### 第一步：查找 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*" \
-  \) \
-  -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" \
-  -not -path "*/build/*" -not -path "*/vendor/*" | head -30
+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
 ```
 
-支持的格式：
-
-| 框架 | 识别文件 |
-|---|---|
-| Prisma | `prisma/schema.prisma` |
-| SQLAlchemy / Django | `**/models.py` |
-| TypeORM | `**/*.entity.ts` |
-| Mongoose | `**/*.model.ts`（检查 mongoose schema） |
-| Java JPA / Hibernate | `**/entity/*.java`、`**/model/*.java`（含 `@Entity` / `@Table` 注解的类） |
-| MyBatis | `**/*Mapper.xml`（提取 `resultMap` 和表名） |
-| Go GORM | `**/models.go`、`**/model.go` |
-| Drizzle | `**/schema.ts` |
-| 原始 SQL | `**/migrations/*.sql` |
-
-### 第二步：生成 Schema 摘要
-
-**只记录表名 + 说明 + 字段数量，不展开字段细节。** 写入 ARCHITECTURE.md：
+**写入 ARCHITECTURE.md（只记摘要，不展开字段）：**
 
 ```markdown
 ## 数据模型（摘要）
-
 | 表名 | 说明 | 字段数 | 来源文件 |
 |---|---|---|---|
 | users | 用户表 | 12 | `src/entity/User.java` |
-| roles | 角色表 | 5 | `src/entity/Role.java` |
-| orders | 订单表 | 18 | `prisma/schema.prisma` |
 
 ### 关系
-- users 1:N roles
 - users 1:N orders
 ```
 
-如果项目没有数据库 → 写"本项目无数据库"，后续阶段不准引用任何表。
-
-### 第三步：在后续命令中按需深挖
-
-**brainstorm/propose/plan 阶段，根据当前需求只读取相关表的详细 schema。**
-
-执行规则：
-1. 先读 ARCHITECTURE.md 的 Schema 摘要，确定涉及哪些表
-2. 只读取相关表的源文件（`cat src/entity/User.java`）
-3. 没涉及的表不要读，节省上下文
-4. 如果摘要中没有但需要新表 → 必须在 propose 的 design.md 中声明
+无数据库 → 写"本项目无数据库"。**铁律：所有阶段引用的表名必须来自此摘要，或 design.md 中声明的新增表。**
 
-**铁律：所有阶段引用的表名必须来自 Schema 摘要列表，或 design.md 中声明的新增表。**
+### B. 框架隐形规则扫描
 
-## 🚨 框架隐形规则扫描（必须执行）
-
-**无论快速还是深度模式，必须执行。** 防止 AI 生成 SQL/代码时违反项目框架的自动处理机制。
-
-### 为什么需要这一步
-
-很多项目有"隐形规则"——某些字段由框架自动处理，SQL 里不需要写；某些拦截器会自动注入条件，手动写反而会冲突。这些规则不在 schema 里，AI 扫不到就会犯错。
-
-**典型踩坑：**
-- MyBatis 多租户插件自动注入 tenant_id → SQL 里再写就重复了
-- JPA @CreatedDate 自动填充 create_time → INSERT 里再写就冲突了
-- 逻辑删除拦截器把 DELETE 改成 UPDATE → AI 直接写 DELETE FROM 就错了
-
-### 扫描步骤
+**目的：** 防止 AI 生成的 SQL/代码违反框架自动处理机制（如自动注入字段、逻辑删除拦截器）。
 
 ```bash
-# 1. MyBatis 拦截器 / 插件配置
-find . \( -name "*Interceptor*.java" -o -name "*Plugin*.java" \
-  -o -name "mybatis-config.xml" -o -name "mybatis*.yml" -o -name "mybatis*.yaml" \) \
-  -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20
-
-# 2. JPA / Hibernate 配置和审计注解
-find . \( -name "*Auditor*.java" -o -name "*EventListener*.java" \
-  -o -name "persistence.xml" -o -name "application*.yml" -o -name "application*.yaml" \) \
-  -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20
-
-# 3. Django 配置（中间件、模型 Meta）
-find . -name "settings.py" -not -path "*/node_modules/*" | head -5
-find . -name "models.py" -not -path "*/node_modules/*" | head -10
-
-# 4. SQLAlchemy 事件监听
-find . \( -name "*event*.py" -o -name "*listener*.py" -o -name "*mixin*.py" \) \
-  -not -path "*/node_modules/*" -not -path "*/.git/*" | head -10
-
-# 5. Prisma 中间件 / 扩展
+# 通用检测：拦截器、审计、中间件、逻辑删除、多租户
+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"
-
-# 6. Go GORM 插件 / 回调
-find . -name "*.go" -not -path "*/vendor/*" | xargs grep -l "gorm:\|Callback\|Plugin" 2>/dev/null | head -10
-
-# 7. TypeORM 订阅器 / 监听器
-find . -name "*.ts" -not -path "*/node_modules/*" | xargs grep -l "EventSubscriber\|@BeforeInsert\|@AfterUpdate\|@DeleteDateColumn" 2>/dev/null | head -10
-
-# 8. Rails / Active Record 回调
-find . -name "*.rb" -not -path "*/vendor/*" | xargs grep -l "before_save\|before_create\|acts_as_paranoid\|acts_as_tenant" 2>/dev/null | head -10
-
-# 9. Laravel / Eloquent 作用域和 trait
-find . \( -name "*Scope*.php" -o -name "boot*.php" -o -name "ServiceProvider.php" \) \
-  -not -path "*/vendor/*" | head -10
-
-# 10. 通用逻辑删除 / 审计字段检测
-find . \( -name "*.java" -o -name "*.py" -o -name "*.go" -o -name "*.ts" \
-  -o -name "*.php" -o -name "*.rb" \) \
-  -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/vendor/*" \
-  -not -path "*/dist/*" -not -path "*/build/*" \
-  | xargs grep -li "is_deleted\|deleted_at\|soft_delete\|paranoid\|tenant_id\|tenantId" 2>/dev/null | head -20
+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
-
-**创建或追加到 `.sillyspec/codebase/CONVENTIONS.md`，添加"框架隐形规则"章节。**
-
-格式：
+**写入 CONVENTIONS.md：**
 
 ```markdown
 ## 框架隐形规则
-
 ### 自动注入字段（SQL 中不要手动写）
-
 | 字段 | 来源 | 说明 |
 |---|---|---|
-| tenant_id | MyBatis 多租户拦截器 TenantLineInnerInterceptor | 自动注入租户过滤条件，SQL 不需要 WHERE tenant_id=? |
-| is_deleted | 逻辑删除拦截器 | DELETE 自动改为 UPDATE xxx SET is_deleted=1 |
 
 ### 自动填充字段（INSERT/UPDATE 不需要手动赋值）
-
 | 字段 | 来源 | 说明 |
 |---|---|---|
-| create_time | JPA @CreatedDate / MyBatis-Plus MetaObjectHandler | INSERT 时自动填充 |
-| update_time | JPA @LastModifiedDate / MyBatis-Plus MetaObjectHandler | INSERT 和 UPDATE 时自动填充 |
-| create_by | MetaObjectHandler | 从 SecurityContext 获取当前用户 |
-
-### 查询增强（框架自动追加条件）
-
-| 规则 | 说明 |
-|---|---|
-| 数据权限过滤 | 某些表自动追加 WHERE 条件，SQL 中不需要手动加 |
-| 软删除过滤 | 查询自动排除 is_deleted=1 的数据，SQL 不需要 WHERE is_deleted=0 |
 
 ### DELETE 行为
-
-- 不要写 `DELETE FROM` → 使用 `UPDATE xxx SET is_deleted = 1 WHERE id = ?`
+- 不要写 `DELETE FROM` → 使用逻辑删除（如 UPDATE xxx SET is_deleted=1）
 ```
 
-**如果项目没有发现任何隐形规则** → 写"未发现框架级别的自动处理配置，SQL 可以按常规方式编写"。
-
-**铁律：后续阶段生成 SQL 或数据操作代码时，必须遵守这些规则。违反 = 生成的代码会报错或产生数据错误。**
-
-## 🚨 实体继承规范扫描（必须执行）
+无发现 → 写"未发现框架级别的自动处理配置"。**铁律：后续阶段生成 SQL/数据操作代码必须遵守这些规则。**
 
-**无论快速还是深度模式，必须执行。** 防止 AI 新建表时漏掉基类的通用字段，导致 MyBatis-Plus/JPA 自动查询报 Unknown column。
+### C. 实体继承规范扫描
 
-### 为什么需要这一步
-
-很多项目用实体基类（BaseModel、BaseEntity、BasePO 等）定义通用字段（审计字段、逻辑删除、多租户等）。子类继承基类后，ORM 框架会自动查询这些字段。如果新建表的 DDL 漏掉了这些列，SQL 就会报错。
-
-**典型踩坑：**
-- 实体类继承了 BaseModel，有 remarks、dept_id 字段
-- AI 生成建表 SQL 时只写了业务字段，漏了通用字段
-- MyBatis-Plus 自动 SELECT 包含 remarks → Unknown column
-
-### 扫描步骤
+**目的：** 防止新建表时漏掉基类通用字段，导致 ORM 查询报 Unknown column。
 
 ```bash
-# 1. Java: 查找实体基类（BaseModel / BaseEntity / BasePO）
 find . \( -name "Base*.java" -o -name "Abstract*.java" \) \
-  -path "*/entity/*" -o -path "*/model/*" -o -path "*/po/*" -o -path "*/entity/*" \
-  -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20
-
-# 2. Java: 查找 @MappedSuperclass 注解的类
-find . -name "*.java" -not -path "*/node_modules/*" -not -path "*/.git/*" \
-  | xargs grep -l "@MappedSuperclass" 2>/dev/null | head -10
-
-# 3. Java: 查看子类继承关系
-grep -rn "extends Base" --include="*.java" \
-  -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20
-
-# 4. Python / Django: 查找 Abstract 模型
-find . -name "models.py" -not -path "*/node_modules/*" | xargs grep -l "class.*Abstract\|class.*Base" 2>/dev/null | head -10
-
-# 5. Go: 查找嵌入的 BaseModel struct
-find . -name "*.go" -not -path "*/vendor/*" | xargs grep -l "type.*struct" | xargs grep -l "BaseModel\|BaseEntity" 2>/dev/null | head -10
-
-# 6. TypeORM: 查找 @Entity 基类的子类
-find . -name "*.entity.ts" -not -path "*/node_modules/*" | xargs grep -l "extends\|@ChildEntity" 2>/dev/null | head -10
-
-# 7. Prisma: 查找 model 共用字段（通过 generator 或注释）
-cat prisma/schema.prisma 2>/dev/null
-
-# 8. Rails: 查找 ApplicationRecord concern
-find . -name "*.rb" -not -path "*/vendor/*" | xargs grep -l "include.*Concern\|include.*Module" 2>/dev/null | head -10
-
-# 9. Laravel: 查找 Model trait
-find . -name "*.php" -path "*/Models/*" -not -path "*/vendor/*" | head -10
+  \( -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
-
-在"框架隐形规则"章节后追加：
+**追加到 CONVENTIONS.md：**
 
 ```markdown
 ## 实体继承规范
-
 ### 基类通用字段（新建表必须包含）
-
-以下字段来自基类 BaseModel，所有子类实体自动继承，DDL 必须包含：
-
 | 字段 | 类型 | 说明 |
 |---|---|---|
-| id | BIGINT | 主键 |
-| remarks | VARCHAR(500) | 备注 |
-| dept_id | BIGINT | 部门ID |
-| create_time | DATETIME | 创建时间 |
-| update_time | DATETIME | 更新时间 |
-| create_by | VARCHAR(64) | 创建人 |
-| update_by | VARCHAR(64) | 更新人 |
-| is_deleted | TINYINT(1) | 逻辑删除 |
-
-### 铁律
-- 新建表的 DDL 必须包含基类的所有字段，不能只写业务字段
-- ORM 自动查询基类字段，数据库缺少这些列会报 Unknown column
-- 如果基类有变更（新增通用字段），需要同步更新所有子表的 DDL
-```
-
-**注意：** 上表是示例，实际字段必须从扫描到的基类源码中提取，不要编造。
-
-**如果项目没有实体基类** → 写"本项目没有实体基类，所有字段在各自实体中定义"。
-
-**铁律：后续阶段新建表或修改表结构时，必须包含基类的所有通用字段。**
-
----
-
-**快速扫描生成 3 份文档：**
+（从扫描到的基类源码中提取，不编造）
 
-创建目录 `mkdir -p .sillyspec/codebase`
+### 铁律：新建表 DDL 必须包含基类所有字段
+```
 
-**1. `.sillyspec/codebase/STACK.md`** — 技术栈
-**2. `.sillyspec/codebase/STRUCTURE.md`** — 目录结构
-**3. `.sillyspec/codebase/PROJECT.md`** — 项目概览
+无基类 → 写"本项目没有实体基类"。
 
 ---
 
 ## 深度扫描
 
-### Step 0: 运行预处理脚本（必须）
-
-**深度扫描前，必须先运行预处理脚本。** 这是零 token 的 shell 操作：
+### Step 0: 预处理脚本
 
 ```bash
-bash scripts/scan-preprocess.sh [扫描区域]
+bash scripts/scan-preprocess.sh [扫描区域] 2>/dev/null
 ```
 
-如果 `scripts/scan-preprocess.sh` 不存在（Windows 或远程项目），跳过此步骤，AI 直接基于快速扫描结果进行深度分析。
-
-**预处理脚本会自动完成：**
-- 统计源文件数量和大小
-- 估算扫描耗时（按文件数量动态计算，不是写死的 3 分钟）
-- 提取配置文件内容（package.json、pom.xml 等）
-- 提取目录结构树
-- 提取 import/依赖关系（按语言分别分析）
-- 提取类名/函数名/注解（Java @Entity、@Controller 等）
-- 检测数据库 Schema 文件位置
-- 检测框架和 ORM
-- 检测框架配置文件（拦截器、审计、基类等）
+不存在则跳过。脚本输出 `.sillyspec/codebase/SCAN-RAW.md`（文件统计、配置、结构、import、类名/注解、Schema 位置）。
 
-所有结果写入 `.sillyspec/codebase/SCAN-RAW.md`。
-
-**脚本输出示例：**
-```
-📊 文件统计：
-  Java: 280
-  Vue: 180
-  配置文件: 3
-  ────────────────
-  源文件总计: 460 个
-  源码总大小: 3200KB
-  预计耗时: 约 5-8 分钟
-  上下文风险: 中
-```
-
-### Step 1: 断点续扫检查
-
-**检查已生成的文档，跳过已完成的：**
+### Step 1: 断点续扫
 
 ```bash
 for f in STACK ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS; do
-  if [ -f ".sillyspec/codebase/${f}.md" ]; then
-    echo "✅ ${f}.md 已存在，跳过"
-  else
-    echo "⬜ ${f}.md 待生成"
-  fi
+  [ -f ".sillyspec/codebase/${f}.md" ] && echo "✅ ${f}" || echo "⬜ ${f}"
 done
 ```
 
-**只生成缺失的文档。** 如果中断后重新执行，不会重复生成已有文档，也不会重复消耗 token。
-
-将检查结果展示给用户：
-```
-📊 扫描进度检查：
-  ✅ STACK.md         已存在
-  ✅ ARCHITECTURE.md  已存在
-  ✅ STRUCTURE.md     已存在
-  ⬜ CONVENTIONS.md   待生成 ← 从这里继续
-  ⬜ INTEGRATIONS.md  待生成
-  ⬜ TESTING.md       待生成
-  ⬜ CONCERNS.md      待生成
-
-  继续生成剩余 4 份文档。
-```
+只生成缺失的文档，展示进度后继续。
 
 ### Step 2: 基于 SCAN-RAW.md 分析
 
-**不要直接读取原始源码。** 读取预处理脚本生成的 SCAN-RAW.md：
-
-```bash
-cat .sillyspec/codebase/SCAN-RAW.md
-```
-
-基于 SCAN-RAW.md 中的结构化信息，**只按需深挖**相关文件：
-
-1. **架构分析** → 如果 SCAN-RAW.md 标注了 460 个文件，不要全部读。读核心入口文件 + 目录结构推断架构
-2. **编码约定** → 如果 SCAN-RAW.md 有 import 分析，基于高频 import 推断约定。必要时抽样读 3-5 个文件确认
-3. **集成分析** → 读 SCAN-RAW.md 中的配置文件内容，不需要重新读原始文件
-4. **数据库 Schema** → 读 SCAN-RAW.md 中标注的 schema 文件位置，只读相关文件
-
-**铁律：每份文档写完立即保存。** 不要攒在一起最后统一写。这样即使中断，已生成的文档不会丢失。
+**不直接读原始源码。** 读 SCAN-RAW.md，按需深挖相关文件。
 
-**按以下顺序生成缺失的文档：**
+按顺序生成 7 份文档（写完立即保存，中断不丢失）：
 
-1. `.sillyspec/codebase/STACK.md` — 技术栈（基于 SCAN-RAW.md 的框架检测 + 配置文件）
-2. `.sillyspec/codebase/ARCHITECTURE.md` — 架构（含数据模型摘要）
-3. `.sillyspec/codebase/STRUCTURE.md` — 目录结构（基于 SCAN-RAW.md 的目录分布）
-4. `.sillyspec/codebase/CONVENTIONS.md` — 代码约定
-5. `.sillyspec/codebase/INTEGRATIONS.md` — 集成
-6. `.sillyspec/codebase/TESTING.md` — 测试现状
-7. `.sillyspec/codebase/CONVENTIONS.md` — 编码约定（含框架隐形规则）
-8. `.sillyspec/codebase/CONCERNS.md` — 技术债务和风险
+1. `STACK.md` — 技术栈
+2. `ARCHITECTURE.md` — 架构（含数据模型摘要）
+3. `STRUCTURE.md` — 目录结构
+4. `CONVENTIONS.md` — 编码约定（含框架隐形规则、实体继承规范）
+5. `INTEGRATIONS.md` — 集成
+6. `TESTING.md` — 测试现状
+7. `CONCERNS.md` — 技术债务和风险
 
 同时更新 `.sillyspec/PROJECT.md`。
 
 ---
 
-## 扫描完成
-
-### 快速扫描完成后
-
-**用 CLI 验证结果：**
+## 完成后
 
 ```bash
 sillyspec status --json
-```
-
-展示给用户：
-> ✅ 快速扫描完成！
-> 
-> 生成文档到 `.sillyspec/codebase/`：
-> - STACK.md — 技术栈
-> - STRUCTURE.md — 目录结构
-> - PROJECT.md — 项目概览
-
-**下一步由 CLI 决定：**
-
-```bash
 sillyspec next
 ```
 
-将 CLI 返回的命令推荐给用户。
-
-### 深度扫描完成后
-
-**用 CLI 验证结果：**
-
-```bash
-sillyspec status --json
-```
-
-CLI 应返回 `phase: "brainstorm"`。如果返回其他阶段，说明有文档缺失，需要补全。
-
-展示给用户：
-> ✅ 深度扫描完成！
-> 
-> 生成 7 份文档到 `.sillyspec/codebase/`：
-> - STACK.md — 技术栈
-> - ARCHITECTURE.md — 架构（含数据模型摘要）
-> - STRUCTURE.md — 目录结构
-> - CONVENTIONS.md — 代码约定
-> - INTEGRATIONS.md — 集成
-> - TESTING.md — 测试现状
-> - CONCERNS.md — 技术债务和风险
+将 CLI 返回的命令推荐给用户。工作区扫描完成后额外提示生成 `.sillyspec/workspace/CODEBASE-OVERVIEW.md`。
 
-**下一步由 CLI 决定，不要自己编建议：**
-
-```bash
-sillyspec next
-```
-
-将 CLI 返回的命令推荐给用户。
-
-### 工作区扫描完成后
-
-> ✅ 工作区扫描完成！
->
-> - 子项目 frontend：`frontend/.sillyspec/codebase/`（快扫，3 份文档）
-> - 子项目 backend：`backend/.sillyspec/codebase/`（深扫，7 份文档）
-> - 工作区概览：`.sillyspec/workspace/CODEBASE-OVERVIEW.md`
->
-> 建议下一步：`/sillyspec:brainstorm '你的需求'`
-
----
-
-## Step 6: Git 提交
+### Git 提交
 
 ```bash
 git add .sillyspec/
 git commit -m "chore: sillyspec scan - codebase mapped"
 ```
 
-## 绝对规则
+### 路径校验 + 自检门控
 
-- 不修改任何代码
-- 文档必须包含真实文件路径（用反引号格式）
-- 有具体代码模式就列出来（不要写模糊的描述）
-- 如果项目为空 → 告知用户使用 `/sillyspec:init` 初始化新项目
-- **交互模式下，每一步都要等用户回复再继续，不要一次性全部输出**
-
-### 路径校验（写入后立即检查）
-
-**每份文档写完后，必须用脚本验证路径正确。这是防止 AI 把文件写错目录的硬约束。**
+**路径校验：** 每份文档写完后检查必须在 `.sillyspec/codebase/` 下，误放则自动修正：
 
 ```bash
-# 检查所有 codebase 文档是否在正确位置
-for f in STACK ARCHITECTURE STRUCTURE CONVENTIONS INTEGRATIONS TESTING CONCERNS PROJECT SCAN-RAW; do
-  if [ -f ".sillyspec/codebase/${f}.md" ]; then
-    echo "✅ .sillyspec/codebase/${f}.md"
-  elif [ -f "${f}.md" ] || [ -f ".sillyspec/${f}.md" ] || [ -f "codebase/${f}.md" ]; then
-    echo "❌ ${f}.md 路径错误！必须在 .sillyspec/codebase/ 下"
-    # 自动修正：移动到正确位置
-    mkdir -p .sillyspec/codebase
-    if [ -f "${f}.md" ]; then mv "${f}.md" ".sillyspec/codebase/${f}.md" && echo "  已修正: ${f}.md → .sillyspec/codebase/${f}.md"; fi
-    if [ -f ".sillyspec/${f}.md" ]; then mv ".sillyspec/${f}.md" ".sillyspec/codebase/${f}.md" && echo "  已修正: .sillyspec/${f}.md → .sillyspec/codebase/${f}.md"; fi
-    if [ -f "codebase/${f}.md" ]; then mv "codebase/${f}.md" ".sillyspec/codebase/${f}.md" && echo "  已修正: codebase/${f}.md → .sillyspec/codebase/${f}.md"; fi
-  fi
-done
-
-# 额外检查：扫描整个项目，找出误放的文档
-for f in $(find . -maxdepth 2 -name "ARCHITECTURE.md" -o -name "STACK.md" -o -name "STRUCTURE.md" -o -name "CONVENTIONS.md" -o -name "INTEGRATIONS.md" -o -name "TESTING.md" -o -name "CONCERNS.md" -o -name "PROJECT.md" | grep -v ".sillyspec/codebase/"); do
-  if [ -f "$f" ]; then
-    echo "❌ 发现误放文件: $f（应该在 .sillyspec/codebase/ 下）"
-    mkdir -p .sillyspec/codebase
-    name=$(basename "$f")
-    mv "$f" ".sillyspec/codebase/${name}"
-    echo "  已自动修正: $f → .sillyspec/codebase/${name}"
-  fi
+for f in $(find . -maxdepth 2 -name "{ARCHITECTURE,STACK,STRUCTURE,CONVENTIONS,INTEGRATIONS,TESTING,CONCERNS,PROJECT,SCAN-RAW}.md" ! -path "./.sillyspec/codebase/*"); do
+  [ -f "$f" ] && mkdir -p .sillyspec/codebase && mv "$f" ".sillyspec/codebase/$(basename $f)"
 done
 ```
 
-**铁律：所有扫描生成的文档必须且只能在 `.sillyspec/codebase/` 目录下。** 如果发现 AI 生成到了其他位置，立即移动到正确位置。
-
-### 自检门控（Hard Gate）
-
-- [ ] STACK.md 是否包含主要语言和框架？
-- [ ] ARCHITECTURE.md 是否描述了整体架构？
-- [ ] STRUCTURE.md 是否包含目录结构？
-- [ ] CONVENTIONS.md 是否描述了编码约定？（深度扫描）
-- [ ] INTEGRATIONS.md 是否列出外部依赖？（深度扫描）
-- [ ] TESTING.md 是否描述了测试状况？（深度扫描）
-- [ ] CONCERNS.md 是否列出了技术债务？（深度扫描）
-- [ ] PROJECT.md 是否生成？
-
-### 脚本校验（硬验证）
-
-Hard Gate 自检通过后，运行校验脚本：
+**自检门控：**
+- [ ] STACK.md 含主要语言和框架？
+- [ ] ARCHITECTURE.md 描述了整体架构？
+- [ ] STRUCTURE.md 含目录结构？
+- [ ] CONVENTIONS.md 含编码约定？（深扫）
+- [ ] INTEGRATIONS.md 列出外部依赖？（深扫）
+- [ ] TESTING.md 描述测试状况？（深扫）
+- [ ] CONCERNS.md 列出技术债务？（深扫）
+- [ ] PROJECT.md 已生成？
 
 ```bash
-bash scripts/validate-scan.sh .sillyspec/codebase
+bash scripts/validate-scan.sh .sillyspec/codebase 2>/dev/null
 ```
-
-- 脚本返回 0 → 自检通过，继续
-- 脚本返回非 0 → 根据错误提示修正文档，重新运行脚本