@dtt_siye/atool 1.3.0 → 1.3.1

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

@@ -1,6 +1,6 @@
-# Phase 4: SYNTHESIZE（主 Agent + Sub-Agents）
+# Phase 4: SYNTHESIZE（主 Agent — 聚合模式）
 
-**目标**：以模块文档 + 知识图谱为数据源，生成项目级交付物（overview/、quality/、diagrams/、project/）。
+**目标**：以 Phase 2.5 精炼后的模块文档 + 知识图谱为数据源，**聚合**为项目级交付物。Phase 4 不再从零生成模块级内容，而是聚合、补全项目级独有文档、并生成 PROJECT-DELIVERABLE.md 总览入口。
 
 ## 前置检查
 
@@ -12,46 +12,40 @@
 ## 输入数据
 
 - 模块文档（必须）：`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.1 聚合项目概述（overview/）
 
-创建 `atool-analysis/overview/` 目录下 4 个文件：
+#### 4.1a summary.md（聚合）
 
-#### 4.1a `summary.md` — 业务摘要
+从各模块 `README.md` 提取摘要，拼接为项目级概述：
+- 第 1 段：Executive Summary（CEO/VP 可读级别，3-5 句）
+- 第 2 段：模块清单表（模块名 / 职责 / 状态）
+- 第 3 段：技术栈概述（从 `analysis-state.json` 的 `detected_stack` 提取）
 
-面向**非技术用户**。必须包含：
-1. **项目是做什么的**（2-4 句话，完全不用技术术语）
-2. **核心业务能力**（5-8 项，用业务语言描述）
-3. **关键数字**（模块数、接口数、核心实体数）
-4. **健康度摘要**（如存在严重技术债，用业务影响语言描述，如"某模块修改风险较高，可能影响XX功能稳定性"）
+#### 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.1b `architecture.md` — 架构说明
+#### 4.1c tech-stack.md（保持不变）
 
-必须包含：
-1. **系统架构图**（Mermaid graph TB 格式，同时写入 `diagrams/architecture.mmd`）
-2. **各层/模块职责说明**
-3. **核心数据流**（用 Mermaid sequence diagram，同时写入 `diagrams/data-flow.mmd`）
-4. **关键设计决策**（ADR 格式：决策/选择/替代/理由）
+从 Phase 1 pre-scan 数据聚合，无需精炼。
 
-#### 4.1c `tech-stack.md` — 技术栈明细
+#### 4.1d getting-started.md（聚合）
 
-从 data.json 聚合：框架、语言版本、构建工具、主要依赖库、运行时环境。
-
-#### 4.1d `getting-started.md` — 新人上手指南
-
-**Zero-KT 标准**：新人仅凭此文档可完成：
-1. **环境搭建**（前置依赖 + 安装命令）
-2. **运行项目**（启动命令 + 验证成功的方式）
-3. **理解主要业务流程**（3-5 个核心场景 walkthrough）
-4. **添加第一个功能**（具体到哪个模块/文件/类，附代码模板）
-5. **运行测试**（命令 + 预期结果）
+从各模块 `dev-guide.md` 的快速启动部分聚合。
 
 ### 4.2 生成 Mermaid 图表（diagrams/）
 
@@ -120,49 +114,41 @@ Phase 3（1-3月）: {长期优化}
 #### 4.3c `recommendations.md`
 可行动的 Top 10 改进建议。每项包含：问题描述、建议行动、预期收益、工作量。
 
-### 4.4 生成项目级文档（project/）
-
-创建 `atool-analysis/project/` 目录下 4 个文件：
-
-#### 4.4a `project/prd.md` — 项目级 PRD（聚合视角）
-
-从所有模块的 prd.md 聚合，生成项目级视角：
+### 4.4 聚合项目级文档（project/）
 
-1. **Executive Summary**：项目整体业务定位（2-3 段，面向 CEO/VP 级别读者）
-2. **全局用户流**：跨模块的端到端用户旅程（Mermaid journey 格式，至少 3 个核心场景）
-3. **功能矩阵**：模块 × 功能的交叉表（哪个模块提供哪些功能）
-4. **非目标汇总**：整个项目明确不做的事
-5. **Phased Rollout**：MVP → v1.1 → v2.0 路线图建议（基于技术债和功能完成度推断）
+#### 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` — 部署文档
+#### 4.4b project/deployment.md（项目级独有）
 
-从代码中推断：
+Phase 4 主 agent 直接引用 software-architecture D 模板结构生成（不启动 sub-agent）：
+- 部署拓扑（Mermaid）
+- 环境配置矩阵（dev/staging/prod）
+- CI/CD 流程
+- 可观测性表
+- 回滚策略
+- 扩缩容规则
 
-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（聚合 + 项目级补全）
 
-#### 4.4c `project/testing-strategy.md` — 测试策略
+Phase 4 主 agent 聚合各模块 `test-cases.md` + 补全：
+- 模块级测试覆盖汇总
+- 集成测试策略
+- E2E 测试策略
+- 性能测试策略
 
-1. **测试金字塔**：单元:集成:E2E 比例建议（基于项目规模和技术栈）
-2. **覆盖率目标**：行覆盖/分支覆盖建议值
-3. **关键路径测试场景**：从 `project/prd.md` 核心用户流推导的 E2E 场景
-4. **自动化建议**：推荐测试框架 + 配置模板（基于技术栈，如 Jest/JUnit/pytest）
-5. **测试数据策略**：种子数据/工厂模式建议
+#### 4.4d project/runbook.md（聚合）
 
-#### 4.4d `project/runbook.md` — 运维手册
-
-1. **常见故障排查**：`| 症状 | 可能原因 | 诊断命令 | 解决方案 |`（至少 5 个场景）
-2. **监控指标建议**：API 延迟/错误率/内存/CPU/数据库连接池
-3. **告警阈值建议**：每个指标的 warning/critical 阈值
-4. **日志查看**：日志文件路径 + 常用查询命令（grep/jq）
-5. **扩缩容指南**（如有容器化）
+Phase 4 主 agent 聚合各模块 `dev-guide.md` 的运维相关章节。
 
 ### 4.5 生成安全和性能文档（quality/ 扩展）
 
@@ -197,64 +183,59 @@ OWASP Top 10 逐项检查，从所有 data.json 的 `security_issues` 聚合：
 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 深度"
-}
-```
+### 4.6 NFR 一致性回扫
 
-**如果平均覆盖率 < 70%**，在 Phase 5 完成摘要中显示：
-```
-⚠️  PRD 覆盖率不足（{score}%）
-    以下模块的 PRD 缺少按钮级交互定义/验收标准/字段校验：
-    - order-service (40%)
-    - payment-service (60%)
-    
-    建议运行 /requirements-writer 生成正式交付级 PRD：
-    → requirements-writer 会读取本次分析结果，自动进入后向增强模式
-    → 通过 Multi-Agent 并行补齐每个模块的按钮级定义和覆盖率检查表
+在 `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%）
+
 ## 完成条件
 
-- `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"`
+- `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

@@ -101,7 +101,70 @@
 > fi
 > ```
 
-### 5.4 更新 State + 打印完成摘要
+### 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
@@ -112,50 +175,33 @@
 >   && 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 5 EXPORT 完成
 
-**如果 Phase 4 检测到 PRD 覆盖率 < 70%（从 `analysis-state.json` 的 `prd_coverage` 读取），追加以下警告：**
+📦 交付物：
+  - atool-analysis/PROJECT-DELIVERABLE.md — 总览入口（文档导航 + 架构概览 + 覆盖率报告）
+  - atool-analysis/EXPORT-FULL.md — 单文件导出版（如已生成）
 
-```
-⚠️  PRD 覆盖率不足（{average_score}%）
-    以下模块缺少按钮级定义/验收标准/字段校验：
-    {modules_below_70 列表}
+📊 精炼覆盖率：
+  - 精炼模块：{M}/{N}
+  - 平均 PRD 覆盖率：{avg}%
+  - 降级模块：{list}（如有）
 
-    → 运行 /requirements-writer 可自动补齐：
-      requirements-writer 会读取本次分析结果，进入后向增强模式，
-      通过 Multi-Agent 并行为每个模块生成正式交付级 PRD。
-```
-
-**无论覆盖率如何，始终显示以下提示：**
-
-```
 💡 后续操作：
-  - 在 aTool Monitor → Projects 查看完整可视化（知识图谱 + Mermaid 渲染）
   - /project-query 查询分析结果（依赖分析、影响分析等）
-  - /requirements-writer 生成正式交付级 PRD（覆盖率检查表 + 按钮级定义）
+  - /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/understand-agent.md

@@ -170,6 +170,9 @@
 ## 输出文件 4：atool-analysis/modules/{module_name}/dev-guide.md
 （层2c: 开发指引 — 新开发者操作手册）
 
+> ⚠️ 此为初稿。Phase 2.5 将由 software-architecture 追加组件设计和 ADR 章节。
+> 初稿重点：准确描述开发操作流程和现有架构约束，不必追求架构文档的完整性。
+
 必须包含以下 4 节：
 
 ### 如何添加新功能
@@ -192,6 +195,9 @@
 ## 输出文件 5：atool-analysis/modules/{module_name}/prd.md
 （层2d: 模块级 PRD — 按钮级别功能定义）
 
+> ⚠️ 此为初稿。Phase 2.5 将按 requirements-writer 的 8 节标准模板精炼。
+> 初稿重点：准确提取业务逻辑和功能点，不必追求格式完美。
+
 质量标准：开发者拿到此文档 + api.md + data-model.md，无需再问产品经理任何问题即可完成全部开发。
 
 必须包含以下 4 节：
@@ -340,9 +346,20 @@
     "gaps": ["PRD 缺失用户删除功能描述", "API 文档缺少错误码表"],
     "inconsistencies": ["文档说支持批量删除，代码中未实现", "文档中的字段名与代码不一致：文档用 userName，代码用 username"]
   }
+  ,
+  "refine_hints": {
+    "detected_patterns": ["MVC", "CQRS", "Event-Driven"],
+    "key_decisions": ["选择 Redis 作为缓存层因为...", "使用 JWT 而非 Session 因为..."],
+    "cross_module_deps": ["依赖 user-service 的 /api/users/{id}", "消费 order-events 队列"]
+  }
 }
 ```
 
+**refine_hints 说明**：为 Phase 2.5 精炼提供线索，避免精炼 agent 重新读源码。
+- `detected_patterns`: sub-agent 识别到的架构模式名称
+- `key_decisions`: 从代码中识别的关键设计决策（原始描述，无需 ADR 格式）
+- `cross_module_deps`: 跨模块依赖的具体描述（API 路径、事件名、共享实体）
+
 字段说明：
 - `layer`：架构层（从路径和类名推断）
 - `quality_score`：0.0-1.0（从 quality_issues 的数量和严重程度计算）