@dtt_siye/atool 1.2.0 → 1.3.0

package/skills/project-analyze/phases/phase5-export.md

@@ -0,0 +1,161 @@
+# Phase 5: EXPORT（纯 Bash，无 AI）
+
+**目标**：整理最终交付物目录，导出 JSON 数据供 aTool Monitor 消费，注册项目到全局注册表。
+
+**执行时间目标**：< 10秒
+
+## 前置检查
+
+1. 确认 `phases.phase4_synthesize == "completed"`（必须）
+2. 如果 `phases.phase5_export == "completed"` → 跳过
+
+## 步骤
+
+### 5.1 导出 data/ 目录（供 aTool Monitor 消费）
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> EXPORT_DIR="$PROJECT_ROOT/atool-analysis/data"
+> mkdir -p "$EXPORT_DIR"
+>
+> # 1. 复制知识图谱
+> if [ -f "$DOCS_DIR/knowledge-graph.json" ]; then
+>   cp "$DOCS_DIR/knowledge-graph.json" "$EXPORT_DIR/"
+>   echo "Exported: knowledge-graph.json"
+> else
+>   echo "Skipped: knowledge-graph.json (not available)"
+> fi
+>
+> # 2. 生成 modules.json（模块列表 + 基础指标）
+> if ls "$DOCS_DIR"/modules/*/data.json 1>/dev/null 2>&1; then
+>   jq -s '[.[] | {
+>     slug: .module,
+>     layer: (.layer // "unknown"),
+>     file_count: ((.files // []) | length),
+>     api_count: ((.exposed_apis // []) | length),
+>     quality_score: (.quality_score // null),
+>     dependencies: [(.dependencies // [])[] | .target]
+>   }]' "$DOCS_DIR"/modules/*/data.json > "$EXPORT_DIR/modules.json"
+>   echo "Exported: modules.json ($(jq length "$EXPORT_DIR/modules.json") modules)"
+> else
+>   echo "[]" > "$EXPORT_DIR/modules.json"
+>   echo "Exported: modules.json (empty — no data.json found)"
+> fi
+>
+> # 3. 复制五维分析指标
+> if [ -f "$DOCS_DIR/multi-dimensional-analysis.json" ]; then
+>   cp "$DOCS_DIR/multi-dimensional-analysis.json" "$EXPORT_DIR/metrics.json"
+>   echo "Exported: metrics.json"
+> else
+>   echo "Skipped: metrics.json (not available)"
+> fi
+>
+> echo "Data export complete: $(ls "$EXPORT_DIR" | tr '\n' ' ')"
+> ```
+
+### 5.2 生成 manifest.json
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> PROJECT_NAME=$(basename "$PROJECT_ROOT")
+> STACK=$(jq -r '.stack // "unknown"' "$DOCS_DIR/analysis-state.json" 2>/dev/null || echo "unknown")
+> DEPTH=$(jq -r '.depth // "L2"' "$DOCS_DIR/analysis-state.json" 2>/dev/null || echo "L2")
+> MODULE_COUNT=$(jq -r '.modules | length' "$DOCS_DIR/analysis-state.json" 2>/dev/null || echo 0)
+> FILE_COUNT=$(find "$PROJECT_ROOT" -type f \
+>   ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/target/*" \
+>   ! -path "*/dist/*" ! -path "*/build/*" ! -path "*/.atool-docs/*" \
+>   ! -path "*/atool-analysis/*" | wc -l | tr -d ' ')
+>
+> cat > "$PROJECT_ROOT/atool-analysis/manifest.json" << EOF
+> {
+>   "name": "$PROJECT_NAME",
+>   "path": "$PROJECT_ROOT",
+>   "stack": "$STACK",
+>   "depth": "$DEPTH",
+>   "module_count": $MODULE_COUNT,
+>   "file_count": $FILE_COUNT,
+>   "analyzed_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+>   "analysis_version": "5.1.0",
+>   "atool_analysis_schema": "1.0"
+> }
+> EOF
+> echo "manifest.json written"
+> ```
+
+### 5.3 注册到 ~/.atool/projects.json
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> cd "$PROJECT_ROOT"
+> if [ -f "lib/export-analysis.sh" ]; then
+>   source lib/export-analysis.sh
+>   register_project "$PROJECT_ROOT"
+> else
+>   echo "WARNING: lib/export-analysis.sh not found — project not registered in ~/.atool/projects.json"
+>   echo "Manual registration: add entry to ~/.atool/projects.json"
+> fi
+> ```
+
+### 5.4 更新 State + 打印完成摘要
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+>   '.phases.phase5_export = "completed" | .updated_at = $ts' \
+>   "$DOCS_DIR/analysis-state.json" > "$DOCS_DIR/analysis-state.json.tmp" \
+>   && mv "$DOCS_DIR/analysis-state.json.tmp" "$DOCS_DIR/analysis-state.json"
+> ```
+
+**打印完成摘要（直接输出文本，不是 bash 命令）：**
+
+```
+✅ 项目分析完成！
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+项目：{PROJECT_NAME}
+技术栈：{STACK} | 深度：{DEPTH}
+模块数：{MODULE_COUNT} | 文件数：{FILE_COUNT}
+
+📁 文档目录：atool-analysis/
+  📋 overview/summary.md         — 项目业务摘要
+  🏗️ overview/architecture.md     — 系统架构说明
+  🚀 overview/getting-started.md  — 新人上手指南
+  📦 modules/                      — 模块文档（PRD/API/数据模型/测试用例/开发指引）
+  📊 quality/                      — 代码质量 + 安全审计 + 性能基准
+  📐 diagrams/                     — Mermaid 架构图源文件
+  📂 project/                      — 项目级 PRD/部署/测试策略/运维手册
+```
+
+**如果 Phase 4 检测到 PRD 覆盖率 < 70%（从 `analysis-state.json` 的 `prd_coverage` 读取），追加以下警告：**
+
+```
+⚠️  PRD 覆盖率不足（{average_score}%）
+    以下模块缺少按钮级定义/验收标准/字段校验：
+    {modules_below_70 列表}
+
+    → 运行 /requirements-writer 可自动补齐：
+      requirements-writer 会读取本次分析结果，进入后向增强模式，
+      通过 Multi-Agent 并行为每个模块生成正式交付级 PRD。
+```
+
+**无论覆盖率如何，始终显示以下提示：**
+
+```
+💡 后续操作：
+  - 在 aTool Monitor → Projects 查看完整可视化（知识图谱 + Mermaid 渲染）
+  - /project-query 查询分析结果（依赖分析、影响分析等）
+  - /requirements-writer 生成正式交付级 PRD（覆盖率检查表 + 按钮级定义）
+  - /code-review 执行 8 维度深度代码审查
+```
+
+## 完成条件
+
+- `atool-analysis/manifest.json` 存在
+- `atool-analysis/data/modules.json` 存在
+- `phases.phase5_export = "completed"`
+- 完成摘要已打印给用户

package/skills/project-analyze/prompts/{deep-analysis-agent.md → archive/deep-analysis-agent.md}

@@ -27,6 +27,10 @@
 - 大文件（>500 行）：{large_files_list} — 仅读取 pre-scan 标记的关键区域（函数体、类定义）
 - confidence: "low" 文件：{low_confidence_files} — 必须全文读取验证
 
+> **降级指令**：如果上方 Pre-Scan 摘要或 Inventory 数据为空/标记为缺失，说明 Phase 0.5/1 未执行。
+> 此时你必须先读取模块内所有源文件，自行提取结构信息（imports, classes, functions），
+> 然后再进行深度分析。**这不是正常流程**，应在 Phase 0.5/1 修复后避免。
+
 ## 技术栈规则
 {rules_content}
 
@@ -104,4 +108,13 @@
 
 ### Depth-Specific Instructions
 
-For depth level specific instructions to append, see `phases/phase2-deep-analysis.md` section 2.2b (L1/L2/L3/L4/L5 追加指令).
+**重要：`{depth_specific_instructions}` 变量必须内联替换为完整指令内容，禁止只写"L3 分析"等抽象标签。**
+
+具体填充方式（根据当前 depth 值）：
+- **L1**: 此 prompt 不使用（Phase 2 跳过）
+- **L2**: 留空（使用上方标准模板即可）
+- **L3**: 读取 `phases/phase2-deep-analysis.md` section "L3 追加指令" → **将完整代码块内容**（含所有 bullet points）内联到 `{depth_specific_instructions}` 位置
+- **L4**: 读取 `phases/phase2a-l4-analysis.md` → 使用 `prompts/l4-analysis-agent.md` 独立 prompt，不走此模板
+- **L5**: 读取 `phases/phase2b-l5-analysis.md` → 使用独立 prompt
+
+**禁止行为**：用 "执行 L3 深度分析" 等一句话替代具体指令。sub-agent 无法理解 "L3" 的含义，必须展开为具体的分析要求。

package/skills/project-analyze/prompts/understand-agent.md

@@ -0,0 +1,407 @@
+# Phase 2 UNDERSTAND Sub-Agent Prompt Template
+
+> **派发方**：Phase 2 控制器（主 agent）
+> **执行方**：sub-agent（每个模块 1 个）
+> **输出目标**：三层文档 → `atool-analysis/modules/{module-name}/` + `.atool-docs/modules/{module-name}/`
+
+---
+
+## Prompt Template
+
+```
+## 任务
+深度分析模块「{module_name}」，生成三层文档（业务摘要 + 开发指引 + PRD + 测试用例 + 机器数据）。
+
+## 已有数据（来自 Phase 1 pre-scan）
+
+### Pre-Scan 结构数据
+{prescan_data}
+
+> 已提取信息：imports, exports, classes, functions, decorators, api_endpoints, data_models
+> 无需重复读取以下结构信息，直接引用即可。
+
+> **降级指令**：如果上方数据为空或标记为缺失，你必须先读取模块内所有源文件，
+> 自行提取结构信息（imports, classes, functions），然后再进行深度分析。
+
+### 源文件读取策略
+- 小文件（<100 行）：直接使用 pre-scan 数据，无需读取源文件
+- 中文件（100-500 行）：读取全文进行分析
+- 大文件（>500 行）：仅读取 pre-scan 标记的关键行范围（类定义、函数体、API handler）
+
+## 技术栈规则
+{stack_rules}
+
+## 项目上下文
+- 技术栈：{stack}
+- 项目名：{project_name}
+- 模块路径：{module_path}
+- 已识别模块：{module_list}
+
+## 输出语言
+所有文档**必须中文**。
+例外（保持英文）：代码块、文件路径、技术标识符、API 路径、包名。
+
+## 真实数据要求
+- 必须使用实际包路径/导入路径（从 pre-scan 提取，禁止使用 com/example/ 等默认值）
+- 必须使用实际版本号（从配置文件提取，禁止编造）
+- 所有推断内容标记 `[推断]`
+
+---
+
+## 输出文件 1：atool-analysis/modules/{module_name}/README.md
+（层1: 业务摘要 — 产品经理/业务人员必须能看懂）
+
+必须包含以下 4 节，**禁止出现代码块、类名、函数名**（那是 dev-guide.md 的内容）：
+
+### 这个模块是做什么的
+2-3 句话，用纯业务语言描述。
+示例：「用户服务负责管理系统中所有用户的注册、登录和个人信息维护，是系统的核心身份管理模块。」
+
+### 它解决什么问题
+从业务视角描述，说清楚没有它会发生什么。
+示例：「如果没有用户服务，系统无法识别谁在操作，也无法控制不同角色的访问权限。」
+
+### 核心业务场景
+3-5 个具体场景，主谓宾句式。每个场景 2-3 句描述完整业务流程。
+示例：
+1. **新用户注册**：用户提交注册信息后，系统验证邮箱唯一性，创建账户，发送验证邮件。
+2. **用户登录**：用户输入凭证后，系统验证身份，生成会话令牌，记录登录日志。
+
+### 关键业务概念
+≤10 个，每个用 2 句话解释。表格格式：概念 | 含义 | 使用场景。
+
+---
+
+## 输出文件 2：atool-analysis/modules/{module_name}/api.md
+（层2a: 接口文档 — 调用方视角）
+
+每个公开接口必须包含：
+- **签名**（方法名 + 参数类型 + 返回类型）
+- **用途**（一句话说清楚做什么）
+- **请求头**（Content-Type、Authorization、自定义 Header 等，标明必填/可选）
+- **参数说明**（每个参数：名称、类型、是否必填、含义）
+- **请求体 Schema**（JSON 格式，每个字段包含完整定义）：
+  | 字段名 | 类型 | 必填 | 校验规则 | 示例值 | 说明 |
+  |--------|------|------|----------|--------|------|
+- **返回值说明**：
+  - 成功响应（200/201）：完整结构 + 每个字段含义
+  - 失败响应（4xx/5xx）：每种错误的响应结构
+- **完整错误码表**：
+  | HTTP Status | Error Code | 触发条件 | 用户提示 | 解决方案 |
+  |-------------|------------|----------|----------|----------|
+- **curl 调用示例**（包含请求和响应）：
+  ```bash
+  # 请求
+  curl -X POST http://localhost:8080/api/users \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer {token}" \
+    -d '{"name": "张三", "email": "zhangsan@example.com"}'
+
+  # 成功响应 (201)
+  {"id": 1, "name": "张三", "email": "zhangsan@example.com", "createdAt": "..."}
+
+  # 失败响应 (409)
+  {"error": "DUPLICATE_EMAIL", "message": "该邮箱已注册"}
+  ```
+- **频率限制**（如有，从代码中的 rate limiter/throttle 配置推断）：
+  - 限制规则（如 100 次/分钟）
+  - 超限响应（429 状态码 + 响应体）
+  - 重试策略（Retry-After header）
+- **版本兼容性**（如有，从 URL 路径版本号或 Header 版本控制推断）
+
+没有公开 API 的模块可跳过此文件（在 README.md 中注明）。
+
+---
+
+## 输出文件 3：atool-analysis/modules/{module_name}/data-model.md
+（层2b: 数据模型 — 仅当模块有数据实体时生成）
+
+必须包含：
+
+### ER 关系图
+- **Mermaid ER 图**（erDiagram 格式，展示实体关系，包含字段类型和关系基数）
+
+### 实体字段详表
+对每个实体，提供完整字段定义表：
+
+| 字段名 | 类型 | 约束 | 默认值 | 索引 | 业务含义 | 验证规则 |
+|--------|------|------|--------|------|----------|----------|
+
+约束列可选值：`NOT NULL`、`UNIQUE`、`PK`、`FK(表名.字段)`、组合约束
+索引列可选值：`PRIMARY`、`UNIQUE`、`INDEX`、`COMPOSITE(字段列表)`、无
+
+### 枚举值定义
+对状态、类型等枚举字段，列出所有可选值：
+
+| 枚举字段 | 可选值 | 含义 | 状态流转规则 |
+|----------|--------|------|-------------|
+
+示例：
+| `order_status` | `PENDING` | 待支付 | 创建后初始状态 |
+| | `PAID` | 已支付 | PENDING → PAID（支付成功） |
+| | `CANCELLED` | 已取消 | PENDING → CANCELLED（超时/手动） |
+| | `COMPLETED` | 已完成 | PAID → COMPLETED（确认收货） |
+
+如有状态流转逻辑，附 Mermaid stateDiagram。
+
+### 关联关系说明
+对每对关联实体：
+- 关系类型：1:1 / 1:N / N:M
+- 关联字段：外键字段名 + 被引用字段
+- 级联策略：`CASCADE` / `SET NULL` / `RESTRICT` / `NO ACTION`（从 ORM 注解或 migration 文件推断）
+- 业务含义：用业务语言解释为什么需要这个关联
+
+### 数据量估算
+从代码中的分页参数、批处理大小、缓存策略推断：
+- 预估单表数据量级（百/千/万/百万）
+- 分页默认值（pageSize）
+- 批处理大小（batchSize）
+- 缓存 TTL
+
+### 数据库迁移
+如果可从 migration/flyway/liquibase/alembic 文件推断：
+- 迁移文件列表
+- 版本演进历史（关键 schema 变更）
+
+没有数据实体的模块可跳过此文件。
+
+---
+
+## 输出文件 4：atool-analysis/modules/{module_name}/dev-guide.md
+（层2c: 开发指引 — 新开发者操作手册）
+
+必须包含以下 4 节：
+
+### 如何添加新功能
+具体到哪个文件、哪个类、按什么模式添加。附代码模板（不是完整实现，而是骨架）。
+示例：「添加新的用户查询接口：1. 在 `UserController.java` 添加新的 @GetMapping 方法 → 2. 在 `UserService.java` 添加业务逻辑 → 3. 在 `UserRepository.java` 添加查询方法」
+
+### 如何修改数据模型
+数据库迁移步骤、ORM 映射更新方式。
+
+### 常见 Bug 排查
+按症状组织（3-5 个）：
+| 症状 | 可能原因 | 排查步骤 | 解决方案 |
+
+### 架构约束
+不允许做什么、为什么。
+示例：「禁止在 Controller 层直接操作 Repository — 必须经过 Service 层，因为 Service 包含事务管理和业务校验逻辑。」
+
+---
+
+## 输出文件 5：atool-analysis/modules/{module_name}/prd.md
+（层2d: 模块级 PRD — 按钮级别功能定义）
+
+质量标准：开发者拿到此文档 + api.md + data-model.md，无需再问产品经理任何问题即可完成全部开发。
+
+必须包含以下 4 节：
+
+### 1. 模块概述
+- **业务问题**（1-2 句，为什么需要这个模块）
+- **解决方案**（1-2 句，这个模块怎么解决）
+- **成功标准**（3-5 个可度量 KPI，从代码中的监控指标/日志/计数器推断）
+  示例：「注册转化率 > 80%」「API 平均响应时间 < 200ms」「错误率 < 0.1%」
+
+### 2. 功能需求（按页面/功能点组织）
+对每个功能点/页面：
+
+#### 2.x {功能名}
+- **用户故事**：As a [角色], I want to [操作] so that [收益]
+- **验收标准**：
+  - [ ] 条件1
+  - [ ] 条件2
+- **UI 交互定义**（从代码中的组件/模板/路由推断）：
+  - 页面布局（文字描述或 ASCII 线框图）
+  - 按钮行为：`[按钮名]` → 触发 `{API}` → 成功/失败反馈
+  - 输入字段：
+    | 字段 | 类型 | 必填 | 校验规则 | 默认值 | 占位文本 |
+    |------|------|------|----------|--------|----------|
+  - 四种状态：加载中 / 空数据 / 错误 / 正常（每种状态的 UI 表现）
+  - 权限控制：哪些角色可见/可操作（从代码中的 RBAC/权限注解推断）
+- **边界条件**：
+  - 并发场景（如多用户同时操作同一资源）
+  - 数据量极端情况（空列表/超大列表/超长文本）
+  - 网络异常处理（超时/断线/重试策略）
+
+### 3. 非功能需求
+- **性能**：API 响应时间要求（从代码中的超时设置/缓存配置/异步处理推断）
+- **安全**：认证方式 / 授权粒度 / 数据脱敏规则（从代码的安全配置推断）
+- **兼容性**：浏览器/设备/API 版本兼容（从代码中的 polyfill/UA 检测/版本号推断）
+
+### 4. 非目标（Not in Scope）
+本模块明确不负责的功能（从代码中的 TODO/FIXME、未实现接口、注释中的 "out of scope" 推断）。
+列出每项非目标及推断依据。
+
+---
+
+## 输出文件 6：atool-analysis/modules/{module_name}/test-cases.md
+（层2e: 模块级测试用例 — QA 直接可用）
+
+质量标准：QA 团队可直接用此文档编写自动化测试脚本。
+
+必须包含以下 4 节：
+
+### 1. 功能测试用例
+对每个核心 API/功能，生成完整用例表：
+
+| 用例 ID | 场景 | 前置条件 | 操作步骤 | 预期结果 | 优先级 |
+|---------|------|----------|----------|----------|--------|
+| TC-{module}-001 | 正常创建用户 | 用户已登录+有权限 | POST /api/users {...} | 201 + 返回用户对象 | P0 |
+| TC-{module}-002 | 缺少必填字段 | 同上 | POST /api/users {} | 400 + 错误消息 | P0 |
+| TC-{module}-003 | 重复邮箱 | 邮箱已存在 | POST /api/users {...} | 409 + 冲突消息 | P1 |
+
+优先级定义：
+- P0：核心正常路径，必须通过
+- P1：常见异常路径，必须通过
+- P2：边界条件，应当通过
+- P3：极端场景，建议通过
+
+### 2. 边界测试
+针对每个输入字段，覆盖以下边界条件：
+- 空值/null/undefined
+- 超长字符串（>255 字符、>65535 字符）
+- 特殊字符（SQL 注入 payload：`' OR 1=1 --`、XSS payload：`<script>alert(1)</script>`）
+- 超大数值（Integer.MAX_VALUE、负数、0、小数）
+- 并发竞争（两个请求同时创建相同资源 → 预期仅一个成功）
+- 空列表 / 超大分页（pageSize=0、pageSize=10000）
+
+### 3. 安全测试
+- 未授权访问（无 Token → 401）
+- 角色越权（普通用户访问管理员接口 → 403）
+- CSRF 防护验证
+- XSS payload 注入（在所有输入字段）
+- SQL 注入 payload（在所有查询参数）
+- 敏感数据泄露（response 中不应包含密码/密钥/内部路径）
+- 水平越权（用户 A 访问用户 B 的资源 → 403/404）
+
+### 4. 集成测试建议
+- 依赖模块的 Mock 策略（哪些模块需要 mock、推荐 mock 方式）
+- 端到端场景描述（完整业务流程的测试路径）
+- 测试数据准备（需要预置哪些数据、推荐的 seed 脚本）
+
+---
+
+## 已有文档检测
+
+在生成文档前，先检查模块目录中是否存在以下文件：
+- README.md、PRD.md、CHANGELOG.md、API.md、docs/*.md
+
+如果存在，读取其内容并与代码实现进行对比：
+1. 代码中已实现但文档未描述的功能 → 补充到 prd.md，标注 `[补齐：代码中已实现但文档未记录]`
+2. 文档中描述但代码未实现的功能 → 在 prd.md 中标注 `[待实现：文档有描述但代码中未找到实现]`
+3. 文档与代码不一致的地方 → 标注 `[不一致：文档说X，代码实际做Y]`
+
+将检测结果写入 data.json 的 `existing_docs` 字段。
+
+---
+
+## 输出文件 7：.atool-docs/modules/{module_name}/data.json
+（层3: 机器数据 — Phase 3 图谱构建使用）
+
+```json
+{
+  "module": "{module_name}",
+  "layer": "presentation|service|repository|domain|infrastructure|ui",
+  "business_domain": "用中文描述此模块的业务领域",
+  "responsibility": "用中文一句话描述核心职责",
+  "files": ["src/path/to/file1.java", "src/path/to/file2.java"],
+  "dependencies": [
+    {"target": "other-module", "type": "imports", "files": ["具体引用文件"]}
+  ],
+  "exposed_apis": [
+    {"name": "createUser", "path": "/api/users", "method": "POST", "file": "UserController.java"}
+  ],
+  "data_entities": [
+    {"name": "User", "fields": ["id", "name", "email", "role"], "file": "User.java"}
+  ],
+  "data_flows": [
+    {"trigger": "用户注册", "path": "Controller → Service → Repository → DB", "direction": "inbound"}
+  ],
+  "quality_issues": [
+    {"type": "high_complexity", "file": "UserService.java", "detail": "方法 createUser 圈复杂度 15", "severity": "medium"}
+  ],
+  "quality_score": 0.75,
+  "business_terms": [
+    {"term": "审批流", "identifier": "approval_flow", "meaning": "多级审批的流程定义"}
+  ],
+  "security_issues": [
+    {"type": "sql_injection|xss|hardcoded_secret|insecure_deserialization|path_traversal|missing_auth", "file": "UserController.java", "line": 42, "detail": "用户输入直接拼接到 SQL 查询中，未使用参数化查询", "severity": "high|medium|low"}
+  ],
+  "test_coverage_estimate": {
+    "has_tests": true,
+    "test_files": ["tests/user.test.ts", "tests/user.spec.ts"],
+    "test_framework": "jest|junit|pytest|go_test|...",
+    "estimated_coverage": "high|medium|low|none",
+    "untested_apis": ["DELETE /api/users/{id}", "PATCH /api/users/{id}/role"],
+    "untested_functions": ["UserService.batchImport", "UserService.exportCsv"]
+  },
+  "existing_docs": {
+    "found": ["README.md", "docs/api.md"],
+    "gaps": ["PRD 缺失用户删除功能描述", "API 文档缺少错误码表"],
+    "inconsistencies": ["文档说支持批量删除，代码中未实现", "文档中的字段名与代码不一致：文档用 userName，代码用 username"]
+  }
+}
+```
+
+字段说明：
+- `layer`：架构层（从路径和类名推断）
+- `quality_score`：0.0-1.0（从 quality_issues 的数量和严重程度计算）
+- `quality_issues`：实际发现的代码质量问题（不是通用建议）
+- `security_issues`：实际发现的安全问题（从代码扫描中发现的具体漏洞，不是通用建议）
+- `test_coverage_estimate`：测试覆盖估算（从测试文件存在性和测试用例覆盖的 API/函数推断）
+- `existing_docs`：已有文档检测结果（发现的文档、缺失内容、与代码的不一致）
+- 所有数组字段如果为空则使用空数组 `[]`，不要省略字段
+- 所有对象字段如果无数据则使用空对象 `{}` 或保留结构填充默认值，不要省略字段
+
+---
+
+## 禁止行为
+- 禁止在 README.md 中出现代码块、类名、函数名（那是 dev-guide.md 和 api.md 的内容）
+- 禁止使用未替换的模板占位符（com/example/、{{PROJECT_NAME}}、xxx、TODO、...）
+- 禁止使用通用建议替代实际分析结果（如"建议添加单元测试"）
+- 禁止重新提取 pre-scan 已包含的结构信息
+- 禁止编造不存在的 API、类、方法
+
+## 深度级别追加指令
+{depth_instructions}
+```
+
+---
+
+## Depth-Specific Instructions
+
+**重要：`{depth_instructions}` 变量必须内联替换为完整指令内容，禁止只写"L3 分析"等抽象标签。**
+
+具体填充方式（根据当前 depth 值）：
+
+- **L1**: 此 prompt 不使用（Phase 2 跳过，使用 pre-scan 数据直接生成 lite 文档）
+- **L2**: 留空（使用上方标准模板即可）
+- **L3**: 内联以下内容：
+  ```
+  ## L3 深度追加要求
+  在标准输出之外，dev-guide.md 额外包含：
+  1. 每个核心函数的完整签名 + 参数说明 + 返回值 + 调用链
+  2. 设计模式识别（Factory/Strategy/Observer 等）+ 为什么选择此模式
+  3. 设计决策记录（ADR 格式）：每个重要决策的 选择/替代方案/理由/权衡
+  4. 模块内部架构图（Mermaid 类图或组件图）
+  ```
+- **L4**: 内联以下内容：
+  ```
+  ## L4 函数级追加要求
+  在 L3 基础上，额外分析：
+  1. 每个公开函数的完整调用链追踪（caller → callee 直到叶子节点）
+  2. 性能热点识别（循环嵌套、大量 IO、N+1 查询等）
+  3. 安全审计点（SQL 注入、XSS、未验证输入、硬编码凭证）
+  4. data.json 额外字段：call_chains[], performance_hotspots[], security_issues[]
+  ```
+- **L5**: 内联以下内容：
+  ```
+  ## L5 跨模块追加要求
+  在 L4 基础上，额外分析：
+  1. 跨模块时序图（Mermaid sequenceDiagram，每个核心业务场景一个）
+  2. 状态机推断（如有状态转换逻辑：Mermaid stateDiagram）
+  3. 数据血缘追踪（每个核心实体从创建到消费的完整路径）
+  4. data.json 额外字段：sequence_diagrams[], state_machines[], data_lineage[]
+  ```
+
+**禁止行为**：用 "执行 L3 深度分析" 等一句话替代具体指令。sub-agent 无法理解 "L3" 的含义，必须展开为具体的分析要求。

package/skills/requirements-writer/README.md

@@ -98,7 +98,7 @@ This skill helps you write comprehensive PRDs and User Stories following Inspect
 - [ ] Test scenarios included
 
 **Data & Security**
-- [ ] Data entities reference `docs/500-data/502-data-dictionary.md`
+- [ ] Data entities reference `docs/600-data/502-data-dictionary.md`
 - [ ] RBAC requirements defined
 - [ ] Data scope defined per role
 - [ ] Audit requirements for critical operations