@dtt_siye/atool 1.2.1 → 1.3.1

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

@@ -0,0 +1,241 @@
+# Phase 4: SYNTHESIZE（主 Agent — 聚合模式）
+
+**目标**：以 Phase 2.5 精炼后的模块文档 + 知识图谱为数据源，**聚合**为项目级交付物。Phase 4 不再从零生成模块级内容，而是聚合、补全项目级独有文档、并生成 PROJECT-DELIVERABLE.md 总览入口。
+
+## 前置检查
+
+1. 确认 `phases.phase2_understand == "completed"`（必须）
+2. 检查 `phases.phase3_graph`：
+   - `"completed"` → 可使用图谱数据生成完整文档
+   - `"failed"` → 跳过图谱相关输出（data-flow.mmd、module-dependencies.mmd），其余正常生成
+
+## 输入数据
+
+- 模块文档（必须）：`atool-analysis/modules/*/README.md`
+- 模块精炼文档（必须）：`atool-analysis/modules/*/prd.md`、`dev-guide.md`、`test-cases.md`
+- 模块数据（必须）：`.atool-docs/modules/*/data.json`
+- 图谱数据（可选）：`.atool-docs/knowledge-graph.json`
+- 五维分析（可选）：`.atool-docs/multi-dimensional-analysis.json`
+
+## 步骤
+
+### 4.1 聚合项目概述（overview/）
+
+#### 4.1a summary.md（聚合）
+
+从各模块 `README.md` 提取摘要，拼接为项目级概述：
+- 第 1 段：Executive Summary（CEO/VP 可读级别，3-5 句）
+- 第 2 段：模块清单表（模块名 / 职责 / 状态）
+- 第 3 段：技术栈概述（从 `analysis-state.json` 的 `detected_stack` 提取）
+
+#### 4.1b architecture.md（聚合 + 项目级补全）
+
+从各模块精炼后的 `dev-guide.md` 的架构章节聚合：
+1. **全局架构图**（Mermaid graph TB）：从各模块的组件设计章节提取模块名和依赖关系，生成项目级视图
+2. **各模块架构摘要**：每个模块一段（模块名 / 分层 / 关键 ADR）
+3. **ADR 汇总**：从各模块 dev-guide.md 提取所有 ADR，汇总为项目级 ADR 列表
+4. **项目级补全**（引用 software-architecture A/E/F 模板结构）：
+   - A. Architecture Summary：Business Context + Technical Drivers + Style Decision
+   - E. Risk and Trade-offs：项目级风险登记表
+   - F. Evolution Roadmap：分阶段演进表
+
+#### 4.1c tech-stack.md（保持不变）
+
+从 Phase 1 pre-scan 数据聚合，无需精炼。
+
+#### 4.1d getting-started.md（聚合）
+
+从各模块 `dev-guide.md` 的快速启动部分聚合。
+
+### 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/）
+
+#### 4.4a project/prd.md（聚合）
+
+从各模块精炼后的 `prd.md` 聚合为项目级 PRD：
+1. **Executive Summary**：项目整体业务目标 + 成功标准
+2. **功能矩阵**：模块 × 功能 交叉表
+3. **NFR 汇总**：
+   - 从各模块 NFR-{MOD}-NNN 归纳生成 NFR-SYS-NNN（系统级）
+   - NFR-SYS-NNN 必须覆盖所有模块 NFR 的范围
+4. **全局用户流**：Mermaid journey 图
+5. **非目标汇总**：各模块非目标聚合
+6. **Phased Rollout Roadmap**
+
+#### 4.4b project/deployment.md（项目级独有）
+
+Phase 4 主 agent 直接引用 software-architecture D 模板结构生成（不启动 sub-agent）：
+- 部署拓扑（Mermaid）
+- 环境配置矩阵（dev/staging/prod）
+- CI/CD 流程
+- 可观测性表
+- 回滚策略
+- 扩缩容规则
+
+#### 4.4c project/testing-strategy.md（聚合 + 项目级补全）
+
+Phase 4 主 agent 聚合各模块 `test-cases.md` + 补全：
+- 模块级测试覆盖汇总
+- 集成测试策略
+- E2E 测试策略
+- 性能测试策略
+
+#### 4.4d project/runbook.md（聚合）
+
+Phase 4 主 agent 聚合各模块 `dev-guide.md` 的运维相关章节。
+
+### 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 NFR 一致性回扫
+
+在 `project/prd.md` 生成 NFR-SYS-NNN 后，对所有模块的 prd.md 执行回扫：
+
+1. 读取 `project/prd.md` 中的 NFR-SYS-NNN 列表
+2. 对每个 `modules/*/prd.md`：
+   - 将 `[待系统级确认]` 替换为 `(≤ NFR-SYS-NNN)`（匹配对应类别：性能→性能，安全→安全，可用性→可用性）
+   - 如果模块 NFR 数值超出系统 NFR 范围，标注 `[⚠️ 超出系统级约束 NFR-SYS-NNN]`
+3. 记录回扫结果到 `analysis-state.json`：`nfr_backscan.conflicts_count`
+
+### 4.7 架构违反率检测
+
+如果 `.atool-docs/knowledge-graph.json` 存在：
+
+```bash
+VIOLATIONS=$(jq '[.edges[] | select(.type == "layer_violation")] | length' .atool-docs/knowledge-graph.json)
+TOTAL=$(jq '.edges | length' .atool-docs/knowledge-graph.json)
+```
+
+如果 `VIOLATIONS / TOTAL > 0.30`（>30%）：
+- 记录到 `analysis-state.json`：`arch_violation_rate`
+- 在 Phase 5 完成摘要中建议：`⚠️ 架构层违反率 {rate}%（>30%），建议运行 /software-architecture 进行深度架构审查`
+
+### 4.8 生成 PROJECT-DELIVERABLE.md
+
+生成 `atool-analysis/PROJECT-DELIVERABLE.md` 总览入口文件。
+
+结构（硬性）：
+
+1. **标题 + 元信息**：项目名、生成时间、分析深度、技术栈、模块数/精炼数/降级数
+2. **执行摘要**：3-5 段项目级业务概述（CEO/VP 可读）
+3. **文档导航**：
+   - 项目级文档表（PRD / 架构 / 部署 / 测试策略 / 运维手册，含相对链接）
+   - 模块级文档表（每个模块一行，含 PRD/架构/API/数据模型/测试用例链接 + 精炼状态 ✅/⚠️）
+   - 质量报告表（code-review / tech-debt / security-audit / performance-baseline）
+4. **全局架构概览**：从 `overview/architecture.md` 内联 Mermaid 图
+5. **功能矩阵**：从 `project/prd.md` 内联核心功能表
+6. **精炼覆盖率报告**：每个模块的 PRD 覆盖率 + 架构完整度 + 精炼状态（从 `analysis-state.json` 的 `refine_status` 读取）
+7. **后续操作建议**：降级模块补全 / code-review / project-query / software-architecture（如架构违反率 >30%）
+
+## 完成条件
+
+- `overview/summary.md` 存在
+- `overview/architecture.md` 存在且包含 Mermaid 图
+- `project/prd.md` 存在且包含 NFR-SYS
+- `project/deployment.md` 存在
+- `project/testing-strategy.md` 存在
+- `project/runbook.md` 存在
+- `PROJECT-DELIVERABLE.md` 存在且包含所有模块链接
+- NFR 一致性回扫已执行
+- 更新 state：
+
+```bash
+jq '.phases.phase4_synthesize = "completed" | .deliverable_status.project_deliverable_md = "completed"' \
+   .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+```

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

@@ -0,0 +1,207 @@
+# 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 生成 EXPORT-FULL.md（可选）
+
+**触发条件**：用户使用 `--export` 参数，或在完成摘要中选择导出。
+
+拼接逻辑（bash）：
+
+```bash
+OUTPUT="atool-analysis/EXPORT-FULL.md"
+
+# 1. 标题 + 元信息
+echo "# $(jq -r '.project' .atool-docs/analysis-state.json) — 完整项目交付文档" > "$OUTPUT"
+echo "" >> "$OUTPUT"
+echo "> 自动生成于 $(date '+%Y-%m-%d %H:%M') | 单文件导出版" >> "$OUTPUT"
+echo "" >> "$OUTPUT"
+echo "---" >> "$OUTPUT"
+
+# 2. 项目级文档
+for FILE in \
+  "atool-analysis/overview/architecture.md" \
+  "atool-analysis/project/prd.md" \
+  ; do
+  [ -f "$FILE" ] && { echo ""; echo "---"; echo ""; cat "$FILE"; } >> "$OUTPUT"
+done
+
+# 3. 模块级文档（按重要性排序）
+for MOD in $(jq -r '.modules | sort_by(-.importance) | .[].name' .atool-docs/pre-scan/manifest.json); do
+  for DOC in prd.md dev-guide.md api.md data-model.md test-cases.md; do
+    FILE="atool-analysis/modules/$MOD/$DOC"
+    [ -f "$FILE" ] && { echo ""; echo "---"; echo ""; echo "## $MOD / $DOC"; echo ""; cat "$FILE"; } >> "$OUTPUT"
+  done
+done
+
+# 4. 项目级剩余文档
+for FILE in \
+  "atool-analysis/project/deployment.md" \
+  "atool-analysis/project/testing-strategy.md" \
+  "atool-analysis/project/runbook.md" \
+  ; do
+  [ -f "$FILE" ] && { echo ""; echo "---"; echo ""; cat "$FILE"; } >> "$OUTPUT"
+done
+
+# 5. 质量摘要（仅前 50 行 + 链接）
+[ -f "atool-analysis/quality/code-review.md" ] && {
+  echo ""; echo "---"; echo ""
+  head -50 "atool-analysis/quality/code-review.md"
+  echo ""; echo "*完整报告见 quality/code-review.md*"
+} >> "$OUTPUT"
+
+# 6. 附录
+echo ""; echo "---"; echo ""
+echo "## 附录：精炼覆盖率报告" >> "$OUTPUT"
+echo "" >> "$OUTPUT"
+echo "| 模块 | PRD 覆盖率 | 架构门禁 | 状态 |" >> "$OUTPUT"
+echo "|------|-----------|---------|------|" >> "$OUTPUT"
+jq -r '.refine_status | to_entries[] | "| \(.key) | \(.value.prd_coverage // "N/A")% | \(.value.arch_gate // "N/A") | \(if .value.degraded then "⚠️ 降级" else "✅" end) |"' \
+  .atool-docs/analysis-state.json >> "$OUTPUT"
+```
+
+更新 state：
+```bash
+jq '.deliverable_status.export_single_file = "completed"' .atool-docs/analysis-state.json > tmp && mv tmp .atool-docs/analysis-state.json
+```
+
+### 5.5 更新 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"
+> ```
+
+**打印完成摘要：**
+
+```
+✅ Phase 5 EXPORT 完成
+
+📦 交付物：
+  - atool-analysis/PROJECT-DELIVERABLE.md — 总览入口（文档导航 + 架构概览 + 覆盖率报告）
+  - atool-analysis/EXPORT-FULL.md — 单文件导出版（如已生成）
+
+📊 精炼覆盖率：
+  - 精炼模块：{M}/{N}
+  - 平均 PRD 覆盖率：{avg}%
+  - 降级模块：{list}（如有）
+
+💡 后续操作：
+  - /project-query 查询分析结果（依赖分析、影响分析等）
+  - /requirements-writer 对降级模块补全 PRD
+  - /code-review 执行 8 维度深度代码审查
+  - /software-architecture 深度架构审查（如架构违反率 >30%）
+```
+
+其中 `{M}/{N}` 和 `{avg}` 从 `analysis-state.json` 的 `refine_status` 计算。如果 `refine_status` 不存在（旧版 state），显示 "N/A"。
+
+## 完成条件
+
+- `atool-analysis/manifest.json` 存在
+- `atool-analysis/data/modules.json` 存在
+- `atool-analysis/PROJECT-DELIVERABLE.md` 存在
+- `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" 的含义，必须展开为具体的分析要求。