@dtt_siye/atool 1.2.0 → 1.3.0

package/skills/project-analyze/phases/phase1-setup.md

@@ -0,0 +1,182 @@
+# Phase 1: SETUP（纯 Bash，无 AI）
+
+**目标**：检测技术栈、统计文件、运行 pre-scan（语法提取）、获得用户确认分析参数。
+
+**执行时间目标**：< 30秒（纯 bash）
+
+## 前置检查
+
+1. 检查 `.atool-docs/analysis-state.json` 是否存在
+2. 如果存在且 `phases.phase1_setup == "completed"` → 跳过 Phase 1，直接进入 Phase 2
+3. 如果不存在或状态非 completed → 继续执行
+
+## 步骤
+
+### 1.1 技术栈检测
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> mkdir -p "$DOCS_DIR"
+> source lib/detect-stack.sh 2>/dev/null || true
+> STACK=$(detect_stack "$PROJECT_ROOT" 2>/dev/null || echo "unknown")
+> FILE_COUNT=$(find "$PROJECT_ROOT" -type f \
+>   ! -path "*/node_modules/*" ! -path "*/.git/*" \
+>   ! -path "*/target/*" ! -path "*/dist/*" \
+>   ! -path "*/build/*" ! -path "*/vendor/*" \
+>   ! -path "*/.atool-docs/*" ! -path "*/atool-analysis/*" \
+>   | wc -l | tr -d ' ')
+> echo "Stack: $STACK | Files: $FILE_COUNT"
+> ```
+
+### 1.2 规模评估
+
+根据 FILE_COUNT 确定 SCALE：
+
+| 文件数 | SCALE | 默认深度 |
+|--------|-------|---------|
+| 1-50 | TINY | L3 |
+| 51-200 | SMALL | L2 |
+| 201-500 | MEDIUM | L2 |
+| 501-1500 | LARGE | L2 |
+| 1501-5000 | XLARGE | L2 |
+| 5001+ | MEGA | L2 |
+
+### 1.3 Pre-Scan（语法提取）
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> mkdir -p "$DOCS_DIR/pre-scan"
+> source lib/pre-scan.sh 2>/dev/null
+> pre_scan_project "$PROJECT_ROOT" "$DOCS_DIR/pre-scan" 2>/dev/null
+> if [ -f "$DOCS_DIR/pre-scan/manifest.json" ]; then
+>   echo "Pre-scan OK: $(jq '.modules | length' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null || echo '?') modules"
+> else
+>   echo "WARNING: Pre-scan failed or manifest.json not created. Phase 2 will fall back to full AI read."
+> fi
+> ```
+>
+> **成功验证**：`$DOCS_DIR/pre-scan/manifest.json` 存在且非空。
+> **失败处理**：记录 warning，继续。Phase 2 sub-agents 将自动降级为全量 AI 读取。
+
+### 1.4 模块发现与重要性评分
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> if [ -f "$DOCS_DIR/pre-scan/manifest.json" ]; then
+>   # 从 pre-scan manifest 提取模块列表
+>   MODULES=$(jq -r '.modules[].slug' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null)
+>   echo "Discovered modules:"
+>   echo "$MODULES"
+>   MODULE_COUNT=$(echo "$MODULES" | wc -l | tr -d ' ')
+>   echo "Total: $MODULE_COUNT modules"
+> else
+>   echo "No manifest — modules will be detected from directory structure"
+> fi
+> ```
+
+### 1.4a 扫描已有文档（用户已有的 PRD/README 等）
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> # 扫描项目中的已有文档（排除 aTool 产物和 node_modules）
+> EXISTING_DOCS=$(find "$PROJECT_ROOT" -maxdepth 3 -type f \
+>   \( -name "*.md" -o -name "PRD*" -o -name "SRS*" -o -name "API*" \) \
+>   ! -path "*/node_modules/*" ! -path "*/.atool-docs/*" \
+>   ! -path "*/atool-analysis/*" ! -path "*/.git/*" \
+>   2>/dev/null | head -50)
+> if [ -n "$EXISTING_DOCS" ]; then
+>   echo "Found existing docs:"
+>   echo "$EXISTING_DOCS"
+>   DOC_COUNT=$(echo "$EXISTING_DOCS" | wc -l | tr -d ' ')
+>   echo "Total: $DOC_COUNT existing documents"
+> else
+>   echo "No existing documentation found"
+> fi
+> ```
+>
+> 将结果写入 `analysis-state.json` 的 `existing_docs` 字段（在 §1.6 初始化时）。
+> Phase 2 sub-agent 将使用此信息检测文档与代码的差异并补齐缺失内容。
+
+### 1.4b 重要性评分
+
+如果 `lib/compute-importance.sh` 可用，运行重要性评分：
+> **执行命令（可选）：**
+> ```bash
+> source lib/compute-importance.sh 2>/dev/null && \
+>   compute_importance_batch "$DOCS_DIR/pre-scan/manifest.json" "$PROJECT_ROOT" 2>/dev/null && \
+>   echo "Importance scoring done" || echo "Importance scoring skipped"
+> ```
+
+### 1.5 用户确认
+
+向用户展示分析预览，等待确认：
+
+```
+📊 项目分析预览
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+技术栈：{STACK}
+文件数：{FILE_COUNT}（已排除 node_modules/build/.git 等）
+规模等级：{SCALE}
+识别模块：{MODULE_LIST}
+
+分析深度选项：
+  L1  结构扫描    ~5分钟   ~10K tokens   目录树+技术栈识别
+  L2  架构分析    ~20分钟  ~50K tokens   架构图+模块文档（推荐）
+  L3  深度实现    ~40分钟  ~100K tokens  核心函数+设计决策
+  L4  函数级      ~80分钟  ~200K tokens  调用链+性能+安全
+  L5  跨模块推断  ~120分钟 ~350K tokens  时序图+状态机+数据血缘
+
+请选择深度 (L1-L5) 或直接回车选择推荐值：
+```
+
+### 1.6 初始化 analysis-state.json
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> DEPTH="${DEPTH:-L2}"  # 用户确认的深度，默认 L2
+> STACK="${STACK:-unknown}"
+> SCALE="${SCALE:-MEDIUM}"
+>
+> # 从 manifest 提取模块列表，fallback 为空数组
+> MODULES_JSON=$(jq -c '[.modules[].slug]' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null || echo '[]')
+>
+> # 构建 module_status 初始值
+> MODULE_STATUS=$(echo "$MODULES_JSON" | jq -c '[.[] | {key: ., value: {phase2: "pending"}}] | from_entries' 2>/dev/null || echo '{}')
+>
+> cat > "$DOCS_DIR/analysis-state.json" << STATEEOF
+> {
+>   "version": "5.1",
+>   "project_root": "$PROJECT_ROOT",
+>   "stack": "$STACK",
+>   "depth": "$DEPTH",
+>   "scale": "$SCALE",
+>   "modules": $MODULES_JSON,
+>   "phases": {
+>     "phase1_setup": "completed",
+>     "phase2_understand": "pending",
+>     "phase3_graph": "pending",
+>     "phase4_synthesize": "pending",
+>     "phase5_export": "pending"
+>   },
+>   "module_status": $MODULE_STATUS,
+>   "updated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+> }
+> STATEEOF
+> echo "State initialized: $(jq -c '.phases' "$DOCS_DIR/analysis-state.json")"
+> ```
+
+## 完成条件
+
+- `.atool-docs/pre-scan/manifest.json` 存在（或 warning 已记录）
+- `.atool-docs/analysis-state.json` 已写入且 `phases.phase1_setup = "completed"`
+- 用户已确认分析深度

package/skills/project-analyze/phases/phase2-understand.md

@@ -0,0 +1,108 @@
+# Phase 2: UNDERSTAND（AI Sub-Agents）
+
+**目标**：每个模块派发 1 个 sub-agent，产出三层文档（业务/技术/数据），直接写入 `atool-analysis/modules/`。
+
+**并发上限：5 个 sub-agent**
+
+## 前置检查
+
+1. 读取 `.atool-docs/analysis-state.json`
+2. 确认 `phases.phase1_setup == "completed"` — 否则先执行 Phase 1
+3. 如果 `phases.phase2_understand == "completed"` → 跳过
+4. 加载模块列表 `state.modules[]`
+
+## 输入数据
+
+- Pre-Scan 数据：`.atool-docs/pre-scan/{module-slug}.json`（如存在）
+- 技术栈规则：`rules/{STACK}.md`（优先），fallback `rules/generic.md`
+
+### Pre-scan 降级规则
+
+当 pre-scan 数据缺失时（Phase 1 pre-scan 失败），sub-agent prompt 自动降级：
+- `{prescan_data}` → 替换为 `"⚠️ Pre-scan data NOT available. Read ALL source files to extract structural information first."`
+- Sub-agent 必须先读取模块内所有源文件，自行提取结构信息，然后进行深度分析
+
+## 执行流程
+
+### 2.1 加载分析规则
+
+读取技术栈规则文件：
+1. 优先：`rules/{STACK}.md`（如 `rules/java-spring.md`、`rules/web-react.md`）
+2. Fallback：`rules/generic.md`
+
+### 2.2 模块排序（按重要性降序）
+
+如果 Phase 1 运行了 importance scoring：
+> **执行命令（可选）：**
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> if [ -f "$DOCS_DIR/pre-scan/manifest.json" ]; then
+>   jq -r '.modules | sort_by(-.importance) | .[].slug' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null
+> fi
+> ```
+
+否则按 `state.modules[]` 原始顺序。
+
+### 2.3 批量派发 Sub-Agents
+
+**规则**：
+- 每批最多 5 个 sub-agent 并行（使用 Agent 工具）
+- 等待当前批次**全部完成**后再派发下一批
+- 每个 sub-agent 完成后立即更新 `module_status`
+
+**每个 sub-agent 使用 `prompts/understand-agent.md` 模板**
+
+派发前准备每个 sub-agent 的变量：
+1. `{module_name}` — 模块名（slug）
+2. `{module_path}` — 模块在项目中的路径
+3. `{prescan_data}` — 读取 `.atool-docs/pre-scan/{module-slug}.json` 的内容（或降级消息）
+4. `{stack_rules}` — 读取的技术栈规则内容
+5. `{depth_instructions}` — 当前深度级别的追加指令（L2 留空，L3/L4/L5 内联具体指令）
+
+### 2.4 Sub-Agent 输出路径
+
+每个 sub-agent 写入以下文件：
+```
+atool-analysis/modules/{module-name}/README.md       # 层1: 业务摘要
+atool-analysis/modules/{module-name}/api.md          # 层2a: 接口文档
+atool-analysis/modules/{module-name}/data-model.md   # 层2b: 数据模型（如有实体）
+atool-analysis/modules/{module-name}/dev-guide.md    # 层2c: 开发指引
+.atool-docs/modules/{module-name}/data.json          # 层3: 机器数据（供 Phase 3）
+```
+
+### 2.5 Checkpoint 写入
+
+每个模块完成后：
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> MODULE_SLUG="{module-slug}"  # 替换为实际模块名
+> jq --arg mod "$MODULE_SLUG" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+>   '.module_status[$mod].phase2 = "completed" | .module_status[$mod].phase2_at = $ts | .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"
+> ```
+
+### 2.6 断点续传
+
+如果从中断恢复：
+1. 读取 `module_status`，找到 `phase2 != "completed"` 的模块
+2. 只对未完成模块派发 sub-agent
+3. 已完成模块跳过
+
+## 完成条件
+
+- 所有模块的 `module_status.{slug}.phase2 == "completed"`
+- `atool-analysis/modules/*/README.md` 全部存在
+- `.atool-docs/modules/*/data.json` 全部存在
+- 更新 state：`phases.phase2_understand = "completed"`
+
+> **执行命令：**
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+>   '.phases.phase2_understand = "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"
+> ```

package/skills/project-analyze/phases/phase3-graph.md

@@ -0,0 +1,77 @@
+# Phase 3: GRAPH（纯 Bash，无 AI）
+
+**目标**：从 Phase 2 的 data.json 构建知识图谱 + 五维分析。全部通过 bash 库函数执行，禁止 AI 生成。
+
+**执行时间目标**：< 30秒
+
+## 前置检查
+
+1. 读取 `.atool-docs/analysis-state.json`
+2. 确认 `phases.phase2_understand == "completed"` — 否则先完成 Phase 2
+3. 如果 `phases.phase3_graph == "completed"` → 跳过
+4. 确认 `.atool-docs/modules/*/data.json` 至少有 1 个文件存在
+
+## 步骤
+
+### 3.1 构建知识图谱
+
+> ⚠️ **必须通过 Bash 工具执行 — 禁止 AI 直接生成 knowledge-graph.json**
+> AI 生成的 JSON 格式与 `generate-visualization.sh` 和 aTool Monitor 期望的 `nodes`/`edges` 格式不兼容。
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> cd "$PROJECT_ROOT"
+> source lib/knowledge-graph.sh 2>/dev/null
+> assemble_enhanced_graph "$DOCS_DIR" "$PROJECT_ROOT" 2>/dev/null
+> if [ -f "$DOCS_DIR/knowledge-graph.json" ]; then
+>   NODES=$(jq '.nodes | length' "$DOCS_DIR/knowledge-graph.json" 2>/dev/null || echo 0)
+>   EDGES=$(jq '.edges | length' "$DOCS_DIR/knowledge-graph.json" 2>/dev/null || echo 0)
+>   echo "Knowledge graph built: $NODES nodes, $EDGES edges"
+> else
+>   echo "WARNING: knowledge-graph.json not created. Phase 4 will skip graph-dependent docs."
+> fi
+> ```
+>
+> **成功验证**：`$DOCS_DIR/knowledge-graph.json` 存在且包含 `nodes` 和 `edges` 字段。
+> **失败处理**：记录 `phases.phase3_graph = "failed"`，继续 Phase 4（Phase 4 检测此标记后跳过图谱相关文档）。
+
+### 3.2 五维分析
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> DOCS_DIR="$PROJECT_ROOT/.atool-docs"
+> cd "$PROJECT_ROOT"
+> source lib/multi-dimensional-analysis.sh 2>/dev/null
+> run_multi_dimensional_analysis "$DOCS_DIR" 2>/dev/null
+> if [ -f "$DOCS_DIR/multi-dimensional-analysis.json" ]; then
+>   echo "Multi-dimensional analysis complete"
+> else
+>   echo "WARNING: multi-dimensional-analysis.json not created"
+> fi
+> ```
+
+### 3.3 更新 State
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> if [ -f "$DOCS_DIR/knowledge-graph.json" ]; then
+>   STATUS="completed"
+> else
+>   STATUS="failed"
+> fi
+> jq --arg status "$STATUS" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+>   '.phases.phase3_graph = $status | .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"
+> echo "Phase 3 status: $STATUS"
+> ```
+
+## 完成条件
+
+- `.atool-docs/knowledge-graph.json` 存在（或 state 标记为 "failed"）
+- `.atool-docs/multi-dimensional-analysis.json` 存在（可选，失败不阻断）
+- `phases.phase3_graph` 已更新为 `"completed"` 或 `"failed"`

package/skills/project-analyze/phases/phase4-synthesize.md

@@ -0,0 +1,260 @@
+# Phase 4: SYNTHESIZE（主 Agent + Sub-Agents）
+
+**目标**：以模块文档 + 知识图谱为数据源，生成项目级交付物（overview/、quality/、diagrams/、project/）。
+
+## 前置检查
+
+1. 确认 `phases.phase2_understand == "completed"`（必须）
+2. 检查 `phases.phase3_graph`：
+   - `"completed"` → 可使用图谱数据生成完整文档
+   - `"failed"` → 跳过图谱相关输出（data-flow.mmd、module-dependencies.mmd），其余正常生成
+
+## 输入数据
+
+- 模块文档（必须）：`atool-analysis/modules/*/README.md`
+- 模块数据（必须）：`.atool-docs/modules/*/data.json`
+- 图谱数据（可选）：`.atool-docs/knowledge-graph.json`
+- 五维分析（可选）：`.atool-docs/multi-dimensional-analysis.json`
+
+## 步骤
+
+### 4.1 生成项目概述（overview/）
+
+创建 `atool-analysis/overview/` 目录下 4 个文件：
+
+#### 4.1a `summary.md` — 业务摘要
+
+面向**非技术用户**。必须包含：
+1. **项目是做什么的**（2-4 句话，完全不用技术术语）
+2. **核心业务能力**（5-8 项，用业务语言描述）
+3. **关键数字**（模块数、接口数、核心实体数）
+4. **健康度摘要**（如存在严重技术债，用业务影响语言描述，如"某模块修改风险较高，可能影响XX功能稳定性"）
+
+**质量标准**：让产品经理读完能回答"系统能做什么"和"有什么主要风险"。
+
+#### 4.1b `architecture.md` — 架构说明
+
+必须包含：
+1. **系统架构图**（Mermaid graph TB 格式，同时写入 `diagrams/architecture.mmd`）
+2. **各层/模块职责说明**
+3. **核心数据流**（用 Mermaid sequence diagram，同时写入 `diagrams/data-flow.mmd`）
+4. **关键设计决策**（ADR 格式：决策/选择/替代/理由）
+
+#### 4.1c `tech-stack.md` — 技术栈明细
+
+从 data.json 聚合：框架、语言版本、构建工具、主要依赖库、运行时环境。
+
+#### 4.1d `getting-started.md` — 新人上手指南
+
+**Zero-KT 标准**：新人仅凭此文档可完成：
+1. **环境搭建**（前置依赖 + 安装命令）
+2. **运行项目**（启动命令 + 验证成功的方式）
+3. **理解主要业务流程**（3-5 个核心场景 walkthrough）
+4. **添加第一个功能**（具体到哪个模块/文件/类，附代码模板）
+5. **运行测试**（命令 + 预期结果）
+
+### 4.2 生成 Mermaid 图表（diagrams/）
+
+将架构和数据流写成独立的 `.mmd` 文件：
+- `atool-analysis/diagrams/architecture.mmd` — graph TB 整体架构
+- `atool-analysis/diagrams/module-dependencies.mmd` — 模块依赖（从 data.json dependencies 聚合）
+- `atool-analysis/diagrams/data-flow.mmd` — 核心数据流（从 data.json data_flows 聚合）
+
+**如果 Phase 3 失败**：`module-dependencies.mmd` 和 `data-flow.mmd` 跳过（缺少图谱数据），在 `architecture.md` 中注明。
+
+### 4.3 生成质量报告（quality/）
+
+#### 4.3a `code-review.md`
+从所有 data.json 的 `quality_issues` 聚合，按严重程度排序。包含：
+- 总体质量评分
+- 按维度分析（复杂度、耦合度、代码风格等）
+- Top 10 最严重问题（文件路径 + 问题描述 + 建议修复方式）
+
+**深化内容**（在上述基础分析之后追加）：
+
+##### 重构优先级矩阵
+
+从所有 data.json 的 `quality_issues` 聚合，按 impact × effort 排序：
+
+```
+| 问题 | 影响范围（模块数） | 修复工作量（人天） | 业务风险 | 优先级 |
+|------|-------------------|-------------------|---------|--------|
+| {问题描述} | {N 个模块} | {X 人天} | HIGH/MED/LOW | P0-P3 |
+```
+
+##### 架构迁移路线图（如架构问题严重）
+
+当架构维度评分 < 60 或存在循环依赖 > 3 处时生成：
+
+```
+Phase 1（1-2周）: {快速修复}
+- 目标：解耦循环依赖、修复分层违反
+- 涉及模块：{列出}
+- 风险：{评估}
+- 验证方式：{依赖图无环 + 单元测试通过}
+
+Phase 2（2-4周）: {中期重构}
+- 目标：抽取共享服务、统一错误处理
+- 涉及模块：{列出}
+- 风险：{评估}
+- 验证方式：{集成测试通过 + 耦合度下降}
+
+Phase 3（1-3月）: {长期优化}
+- 目标：架构模式迁移（如单体→模块化/微服务）
+- 涉及模块：{全局}
+- 风险：{评估}
+- 验证方式：{E2E 测试 + 性能基准不退化}
+```
+
+##### 重构代码示例（Top 3 问题）
+
+对 Top 3 严重问题，各提供：
+- **文件:行号**：精确定位
+- **当前代码**（关键片段，≤15 行）
+- **重构后代码**（同等片段）
+- **改进说明**：为什么这样改 + 预期收益（可量化：如圈复杂度从 X 降至 Y）
+
+#### 4.3b `tech-debt.md`
+技术债清单，按优先级排序。每项包含：影响范围、修复工作量估算、业务风险。
+
+#### 4.3c `recommendations.md`
+可行动的 Top 10 改进建议。每项包含：问题描述、建议行动、预期收益、工作量。
+
+### 4.4 生成项目级文档（project/）
+
+创建 `atool-analysis/project/` 目录下 4 个文件：
+
+#### 4.4a `project/prd.md` — 项目级 PRD（聚合视角）
+
+从所有模块的 prd.md 聚合，生成项目级视角：
+
+1. **Executive Summary**：项目整体业务定位（2-3 段，面向 CEO/VP 级别读者）
+2. **全局用户流**：跨模块的端到端用户旅程（Mermaid journey 格式，至少 3 个核心场景）
+3. **功能矩阵**：模块 × 功能的交叉表（哪个模块提供哪些功能）
+4. **非目标汇总**：整个项目明确不做的事
+5. **Phased Rollout**：MVP → v1.1 → v2.0 路线图建议（基于技术债和功能完成度推断）
+
+**质量标准**：客户可直接使用此文档进行项目验收。
+
+#### 4.4b `project/deployment.md` — 部署文档
+
+从代码中推断：
+
+1. **环境要求**：语言版本/运行时/数据库/中间件（从 package.json/pom.xml/go.mod 等提取）
+2. **配置项清单**：从 config/env 文件提取，格式：`| 变量名 | 类型 | 默认值 | 必填 | 说明 |`
+3. **启动命令**：dev/staging/production 三套（从 scripts/Makefile/docker-compose 提取）
+4. **Docker 配置**（如有 Dockerfile）：镜像构建 + 运行命令
+5. **部署检查清单**：10 项 checkbox（数据库迁移/配置注入/健康检查/日志/监控/回滚准备...）
+6. **回滚策略**：基于部署方式的回滚步骤
+7. **健康检查接口**：从代码中的 /health /ready /live 端点提取
+
+#### 4.4c `project/testing-strategy.md` — 测试策略
+
+1. **测试金字塔**：单元:集成:E2E 比例建议（基于项目规模和技术栈）
+2. **覆盖率目标**：行覆盖/分支覆盖建议值
+3. **关键路径测试场景**：从 `project/prd.md` 核心用户流推导的 E2E 场景
+4. **自动化建议**：推荐测试框架 + 配置模板（基于技术栈，如 Jest/JUnit/pytest）
+5. **测试数据策略**：种子数据/工厂模式建议
+
+#### 4.4d `project/runbook.md` — 运维手册
+
+1. **常见故障排查**：`| 症状 | 可能原因 | 诊断命令 | 解决方案 |`（至少 5 个场景）
+2. **监控指标建议**：API 延迟/错误率/内存/CPU/数据库连接池
+3. **告警阈值建议**：每个指标的 warning/critical 阈值
+4. **日志查看**：日志文件路径 + 常用查询命令（grep/jq）
+5. **扩缩容指南**（如有容器化）
+
+### 4.5 生成安全和性能文档（quality/ 扩展）
+
+#### 4.5a `quality/security-audit.md` — 安全审计总结
+
+OWASP Top 10 逐项检查，从所有 data.json 的 `security_issues` 聚合：
+
+```
+| OWASP 项 | 检查结果 | 风险等级 | 发现问题数 | 代表性问题 | 修复建议 |
+|-----------|---------|---------|-----------|-----------|---------|
+| A01 Broken Access Control | ⚠️ 发现 | HIGH | 3 | UserController 缺少角色检查 | 添加 @PreAuthorize |
+| A02 Cryptographic Failures | ✅ 未发现 | - | 0 | - | - |
+| A03 Injection | ... | ... | ... | ... | ... |
+| A04 Insecure Design | ... | ... | ... | ... | ... |
+| A05 Security Misconfiguration | ... | ... | ... | ... | ... |
+| A06 Vulnerable Components | ... | ... | ... | ... | ... |
+| A07 Auth Failures | ... | ... | ... | ... | ... |
+| A08 Software/Data Integrity | ... | ... | ... | ... | ... |
+| A09 Logging/Monitoring Failures | ... | ... | ... | ... | ... |
+| A10 SSRF | ... | ... | ... | ... | ... |
+```
+
+**安全建议 Top 5**：可行动的改进措施，按风险等级降序排列，每项包含：问题描述、影响评估、修复步骤、验证方式。
+
+#### 4.5b `quality/performance-baseline.md` — 性能基准
+
+从代码中推断的性能特征：
+
+1. **API 延迟估算**：从代码中的缓存/索引/分页推断（无缓存的复杂查询标记为高风险）
+2. **数据库查询分析**：N+1 查询风险点、缺失索引
+3. **内存使用估算**：大对象/集合加载模式
+4. **并发处理**：线程池/连接池配置评估
+5. **建议优化点**：Top 5 性能改进建议（按预期收益排序，每项包含：问题/影响/建议/预期收益）
+
+### 4.6 更新 State
+
+> **执行命令（必须通过 Bash 工具）：**
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+>   '.phases.phase4_synthesize = "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"
+> echo "Phase 4 completed"
+> ```
+
+### 4.7 PRD 覆盖率检测
+
+在所有文档生成完成后，检查模块级 PRD 的覆盖率：
+
+**对每个 `atool-analysis/modules/{name}/prd.md`，检查是否包含以下关键要素**：
+1. 用户故事（As a... I want...）— 搜索 "As a" 或 "用户故事"
+2. 验收标准（AC-）— 搜索 "AC-" 或 "验收标准"
+3. 按钮/交互定义 — 搜索 "按钮" 或 "输入字段" 或 "交互"
+4. 字段校验规则 — 搜索 "校验" 或 "必填" 或 "validation"
+5. 四种状态 — 搜索 "加载中" 或 "空数据" 或 "错误状态"
+
+**覆盖率评分**：每个要素命中 = 20分，总分 0-100。
+
+将评分写入 `analysis-state.json`：
+```json
+"prd_coverage": {
+  "average_score": 60,
+  "modules_below_70": ["order-service", "payment-service"],
+  "recommendation": "建议运行 /requirements-writer 补齐 PRD 深度"
+}
+```
+
+**如果平均覆盖率 < 70%**，在 Phase 5 完成摘要中显示：
+```
+⚠️  PRD 覆盖率不足（{score}%）
+    以下模块的 PRD 缺少按钮级交互定义/验收标准/字段校验：
+    - order-service (40%)
+    - payment-service (60%)
+    
+    建议运行 /requirements-writer 生成正式交付级 PRD：
+    → requirements-writer 会读取本次分析结果，自动进入后向增强模式
+    → 通过 Multi-Agent 并行补齐每个模块的按钮级定义和覆盖率检查表
+```
+
+## 完成条件
+
+- `atool-analysis/overview/summary.md` 存在
+- `atool-analysis/overview/architecture.md` 存在
+- `atool-analysis/overview/getting-started.md` 存在
+- `atool-analysis/diagrams/architecture.mmd` 存在
+- `atool-analysis/quality/code-review.md` 存在（含重构优先级矩阵 + 代码示例）
+- `atool-analysis/project/prd.md` 存在
+- `atool-analysis/project/deployment.md` 存在
+- `atool-analysis/project/testing-strategy.md` 存在
+- `atool-analysis/project/runbook.md` 存在
+- `atool-analysis/quality/security-audit.md` 存在
+- `atool-analysis/quality/performance-baseline.md` 存在
+- PRD 覆盖率检测已执行（结果写入 state.json）
+- `phases.phase4_synthesize = "completed"`