mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-14 02:42:04 +08:00
Refactor project analysis phases: remove diagram generation phase, enhance report generation with detailed structure and quality checks, and introduce consolidation agent for cross-module analysis. Update CLI commands to support final output options and improve history management with copy functionality.
This commit is contained in:
catlog22
@@ -1,138 +1,402 @@
|
||||
# Phase 2: Deep Code Analysis
|
||||
|
||||
Launch 6 parallel agents for multi-dimensional code analysis.
|
||||
6 个并行 Agent，各自直接写入 MD 章节文件。
|
||||
|
||||
## Execution
|
||||
> **模板参考**: [../templates/agent-base.md](../templates/agent-base.md)
|
||||
> **规范参考**: [../specs/cpcc-requirements.md](../specs/cpcc-requirements.md)
|
||||
|
||||
### Analysis Dimensions
|
||||
## Agent 配置
|
||||
|
||||
| Agent | Dimension | Analysis Focus | Output Section |
|
||||
|-------|-----------|----------------|----------------|
|
||||
| 1 | architecture | 分层、模块、依赖 | Section 2 |
|
||||
| 2 | functions | 功能、工作流、交互 | Section 3 |
|
||||
| 3 | algorithms | 核心逻辑、复杂度、流程 | Section 4 |
|
||||
| 4 | data_structures | 实体、属性、关系 | Section 5 |
|
||||
| 5 | interfaces | API、参数、响应 | Section 6 |
|
||||
| 6 | exceptions | 错误类型、处理、恢复 | Section 7 |
|
||||
| Agent | 输出文件 | 章节 |
|
||||
|-------|----------|------|
|
||||
| architecture | section-2-architecture.md | 系统架构图 |
|
||||
| functions | section-3-functions.md | 功能模块设计 |
|
||||
| algorithms | section-4-algorithms.md | 核心算法与流程 |
|
||||
| data_structures | section-5-data-structures.md | 数据结构设计 |
|
||||
| interfaces | section-6-interfaces.md | 接口设计 |
|
||||
| exceptions | section-7-exceptions.md | 异常处理设计 |
|
||||
|
||||
### Agent Prompts
|
||||
## CPCC 规范要点 (所有 Agent 共用)
|
||||
|
||||
```
|
||||
[CPCC_SPEC]
|
||||
1. 内容基于代码分析，无臆测或未来计划
|
||||
2. 图表编号格式: 图N-M (如图2-1, 图3-1)
|
||||
3. 每个子章节内容不少于100字
|
||||
4. Mermaid 语法必须正确可渲染
|
||||
5. 包含具体文件路径引用
|
||||
6. 中文输出，技术术语可用英文
|
||||
```
|
||||
|
||||
## 执行流程
|
||||
|
||||
```javascript
|
||||
// 1. 准备目录
|
||||
Bash(`mkdir -p ${outputDir}/sections`);
|
||||
|
||||
// 2. 并行启动 6 个 Agent
|
||||
const results = await Promise.all([
|
||||
launchAgent('architecture', metadata, outputDir),
|
||||
launchAgent('functions', metadata, outputDir),
|
||||
launchAgent('algorithms', metadata, outputDir),
|
||||
launchAgent('data_structures', metadata, outputDir),
|
||||
launchAgent('interfaces', metadata, outputDir),
|
||||
launchAgent('exceptions', metadata, outputDir)
|
||||
]);
|
||||
|
||||
// 3. 收集返回信息
|
||||
const summaries = results.map(r => JSON.parse(r));
|
||||
|
||||
// 4. 传递给 Phase 2.5
|
||||
return { summaries, cross_notes: summaries.flatMap(s => s.cross_module_notes) };
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent 提示词
|
||||
|
||||
### Architecture
|
||||
|
||||
**Architecture Analysis:**
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
prompt: `
|
||||
## 分析目标
|
||||
分析项目的系统架构，为"系统架构图"章节提供数据。
|
||||
[ROLE] 系统架构师，专注于分层设计和模块依赖。
|
||||
|
||||
## 分析内容
|
||||
1. 分层结构：识别代码的分层（Controller/Service/Repository）
|
||||
2. 模块边界：各模块的职责范围和边界
|
||||
3. 依赖关系：模块间的依赖方向和类型
|
||||
4. 核心组件：系统的核心组件及其作用
|
||||
5. 数据流向：数据在各层之间的流动路径
|
||||
[TASK]
|
||||
分析 ${meta.scope_path}，生成 Section 2: 系统架构图。
|
||||
输出: ${outDir}/sections/section-2-architecture.md
|
||||
|
||||
## 输出格式
|
||||
{
|
||||
"layers": [{name, components, responsibility}],
|
||||
"modules": [{name, path, responsibility, dependencies}],
|
||||
"data_flow": [{from, to, data_type, description}],
|
||||
"core_components": [{name, type, responsibility}]
|
||||
}
|
||||
[CPCC_SPEC]
|
||||
- 内容基于代码分析，无臆测
|
||||
- 图表编号: 图2-1, 图2-2...
|
||||
- 每个子章节 ≥100字
|
||||
- 包含文件路径引用
|
||||
|
||||
[TEMPLATE]
|
||||
## 2. 系统架构图
|
||||
|
||||
本章节展示${meta.software_name}的系统架构设计。
|
||||
|
||||
\`\`\`mermaid
|
||||
graph TD
|
||||
subgraph Layer1["层名"]
|
||||
Comp1[组件1]
|
||||
end
|
||||
Comp1 --> Comp2
|
||||
\`\`\`
|
||||
|
||||
**图2-1 系统架构图**
|
||||
|
||||
### 2.1 分层说明
|
||||
| 层级 | 组件 | 职责 |
|
||||
|------|------|------|
|
||||
|
||||
### 2.2 模块依赖
|
||||
| 模块 | 依赖 | 说明 |
|
||||
|------|------|------|
|
||||
|
||||
[FOCUS]
|
||||
1. 分层: 识别代码层次 (Controller/Service/Repository 或其他)
|
||||
2. 模块: 核心模块及职责边界
|
||||
3. 依赖: 模块间依赖方向
|
||||
4. 数据流: 请求/数据的流动路径
|
||||
|
||||
[RETURN JSON]
|
||||
{"status":"completed","output_file":"section-2-architecture.md","summary":"<50字摘要>","cross_module_notes":["跨模块发现"],"stats":{"diagrams":1,"subsections":2}}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Function Analysis:**
|
||||
```javascript
|
||||
prompt = `
|
||||
## 分析目标
|
||||
分析项目的功能模块，为"功能模块设计"章节提供数据。
|
||||
### Functions
|
||||
|
||||
## 输出格式
|
||||
{
|
||||
"feature_list": [{id, name, description, module, entry_file}],
|
||||
"feature_groups": [{group_name, features: []}],
|
||||
"feature_hierarchy": {root: {children: [...]}},
|
||||
"interactions": [{caller, callee, trigger, description}],
|
||||
"key_workflows": [{name, steps: [], files_involved}]
|
||||
}
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
prompt: `
|
||||
[ROLE] 功能分析师，专注于功能点识别和交互。
|
||||
|
||||
[TASK]
|
||||
分析 ${meta.scope_path}，生成 Section 3: 功能模块设计。
|
||||
输出: ${outDir}/sections/section-3-functions.md
|
||||
|
||||
[CPCC_SPEC]
|
||||
- 内容基于代码分析，无臆测
|
||||
- 图表编号: 图3-1, 图3-2...
|
||||
- 每个子章节 ≥100字
|
||||
- 包含文件路径引用
|
||||
|
||||
[TEMPLATE]
|
||||
## 3. 功能模块设计
|
||||
|
||||
本章节展示${meta.software_name}的功能模块结构。
|
||||
|
||||
\`\`\`mermaid
|
||||
flowchart TD
|
||||
ROOT["${meta.software_name}"]
|
||||
subgraph Group1["模块组1"]
|
||||
F1["功能1"]
|
||||
end
|
||||
ROOT --> Group1
|
||||
\`\`\`
|
||||
|
||||
**图3-1 功能模块结构图**
|
||||
|
||||
### 3.1 功能清单
|
||||
| ID | 功能名称 | 模块 | 入口文件 | 说明 |
|
||||
|----|----------|------|----------|------|
|
||||
|
||||
### 3.2 功能交互
|
||||
| 调用方 | 被调用方 | 触发条件 |
|
||||
|--------|----------|----------|
|
||||
|
||||
[FOCUS]
|
||||
1. 功能点: 枚举所有用户可见功能
|
||||
2. 模块分组: 按业务域分组
|
||||
3. 入口: 每个功能的代码入口 \`src/path/file.ts\`
|
||||
4. 交互: 功能间的调用关系
|
||||
|
||||
[RETURN JSON]
|
||||
{"status":"completed","output_file":"section-3-functions.md","summary":"<50字>","cross_module_notes":[],"stats":{}}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Algorithm Analysis:**
|
||||
```javascript
|
||||
prompt = `
|
||||
## 分析目标
|
||||
分析项目的核心算法和业务逻辑，为"核心算法与流程"章节提供数据。
|
||||
### Algorithms
|
||||
|
||||
## 输出格式
|
||||
{
|
||||
"algorithms": [{
|
||||
name, file, line, description, complexity,
|
||||
inputs: [{name, type, description}],
|
||||
outputs: [{name, type, description}],
|
||||
steps: [{step_num, description, type, next, conditions}]
|
||||
}],
|
||||
"complex_functions": [{name, file, cyclomatic_complexity}]
|
||||
}
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
prompt: `
|
||||
[ROLE] 算法工程师，专注于核心逻辑和复杂度分析。
|
||||
|
||||
[TASK]
|
||||
分析 ${meta.scope_path}，生成 Section 4: 核心算法与流程。
|
||||
输出: ${outDir}/sections/section-4-algorithms.md
|
||||
|
||||
[CPCC_SPEC]
|
||||
- 内容基于代码分析，无臆测
|
||||
- 图表编号: 图4-1, 图4-2... (每个算法一个流程图)
|
||||
- 每个算法说明 ≥100字
|
||||
- 包含文件路径和行号引用
|
||||
|
||||
[TEMPLATE]
|
||||
## 4. 核心算法与流程
|
||||
|
||||
本章节展示${meta.software_name}的核心算法设计。
|
||||
|
||||
### 4.1 {算法名称}
|
||||
|
||||
**说明**: {描述，≥100字}
|
||||
**位置**: \`src/path/file.ts:line\`
|
||||
|
||||
**输入**: param1 (type) - 说明
|
||||
**输出**: result (type) - 说明
|
||||
|
||||
\`\`\`mermaid
|
||||
flowchart TD
|
||||
Start([开始]) --> Input[/输入/]
|
||||
Input --> Check{判断}
|
||||
Check -->|是| P1[步骤1]
|
||||
Check -->|否| P2[步骤2]
|
||||
P1 --> End([结束])
|
||||
P2 --> End
|
||||
\`\`\`
|
||||
|
||||
**图4-1 {算法名称}流程图**
|
||||
|
||||
### 4.N 复杂度分析
|
||||
| 算法 | 时间 | 空间 | 文件 |
|
||||
|------|------|------|------|
|
||||
|
||||
[FOCUS]
|
||||
1. 核心算法: 业务逻辑的关键算法 (>10行或含分支循环)
|
||||
2. 流程步骤: 分支/循环/条件逻辑
|
||||
3. 复杂度: 时间/空间复杂度估算
|
||||
4. 输入输出: 参数类型和返回值
|
||||
|
||||
[RETURN JSON]
|
||||
{"status":"completed","output_file":"section-4-algorithms.md","summary":"<50字>","cross_module_notes":[],"stats":{}}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Data Structure Analysis:**
|
||||
```javascript
|
||||
prompt = `
|
||||
## 分析目标
|
||||
分析项目的数据结构，为"数据结构设计"章节提供数据。
|
||||
### Data Structures
|
||||
|
||||
## 输出格式
|
||||
{
|
||||
"entities": [{
|
||||
name, file, type,
|
||||
properties: [{name, type, visibility, description}],
|
||||
methods: [{name, params, return_type, visibility}]
|
||||
}],
|
||||
"relationships": [{from, to, type, cardinality, description}],
|
||||
"enums": [{name, values: [{name, value, description}]}]
|
||||
}
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
prompt: `
|
||||
[ROLE] 数据建模师，专注于实体关系和类型定义。
|
||||
|
||||
[TASK]
|
||||
分析 ${meta.scope_path}，生成 Section 5: 数据结构设计。
|
||||
输出: ${outDir}/sections/section-5-data-structures.md
|
||||
|
||||
[CPCC_SPEC]
|
||||
- 内容基于代码分析，无臆测
|
||||
- 图表编号: 图5-1 (数据结构类图)
|
||||
- 每个子章节 ≥100字
|
||||
- 包含文件路径引用
|
||||
|
||||
[TEMPLATE]
|
||||
## 5. 数据结构设计
|
||||
|
||||
本章节展示${meta.software_name}的核心数据结构。
|
||||
|
||||
\`\`\`mermaid
|
||||
classDiagram
|
||||
class Entity1 {
|
||||
+type field1
|
||||
+method1()
|
||||
}
|
||||
Entity1 "1" --> "*" Entity2 : 关系
|
||||
\`\`\`
|
||||
|
||||
**图5-1 数据结构类图**
|
||||
|
||||
### 5.1 实体说明
|
||||
| 实体 | 类型 | 文件 | 说明 |
|
||||
|------|------|------|------|
|
||||
|
||||
### 5.2 关系说明
|
||||
| 源 | 目标 | 类型 | 基数 |
|
||||
|----|------|------|------|
|
||||
|
||||
[FOCUS]
|
||||
1. 实体: class/interface/type 定义
|
||||
2. 属性: 字段类型和可见性 (+public/-private/#protected)
|
||||
3. 关系: 继承(--|>)/组合(*--)/关联(-->)
|
||||
4. 枚举: enum 类型及其值
|
||||
|
||||
[RETURN JSON]
|
||||
{"status":"completed","output_file":"section-5-data-structures.md","summary":"<50字>","cross_module_notes":[],"stats":{}}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Interface Analysis:**
|
||||
```javascript
|
||||
prompt = `
|
||||
## 分析目标
|
||||
分析项目的接口设计，为"接口设计"章节提供数据。
|
||||
### Interfaces
|
||||
|
||||
## 输出格式
|
||||
{
|
||||
"apis": [{
|
||||
name, path, method, description,
|
||||
parameters: [{name, type, required, description}],
|
||||
response: {type, schema, description},
|
||||
category
|
||||
}],
|
||||
"protocols": [{name, type, description}]
|
||||
}
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
prompt: `
|
||||
[ROLE] API设计师，专注于接口契约和协议。
|
||||
|
||||
[TASK]
|
||||
分析 ${meta.scope_path}，生成 Section 6: 接口设计。
|
||||
输出: ${outDir}/sections/section-6-interfaces.md
|
||||
|
||||
[CPCC_SPEC]
|
||||
- 内容基于代码分析，无臆测
|
||||
- 图表编号: 图6-1, 图6-2... (每个核心接口一个时序图)
|
||||
- 每个接口详情 ≥100字
|
||||
- 包含文件路径引用
|
||||
|
||||
[TEMPLATE]
|
||||
## 6. 接口设计
|
||||
|
||||
本章节展示${meta.software_name}的接口设计。
|
||||
|
||||
\`\`\`mermaid
|
||||
sequenceDiagram
|
||||
participant C as Client
|
||||
participant A as API
|
||||
participant S as Service
|
||||
C->>A: POST /api/xxx
|
||||
A->>S: method()
|
||||
S-->>A: result
|
||||
A-->>C: 200 OK
|
||||
\`\`\`
|
||||
|
||||
**图6-1 {接口名}时序图**
|
||||
|
||||
### 6.1 接口清单
|
||||
| 接口 | 方法 | 路径 | 说明 |
|
||||
|------|------|------|------|
|
||||
|
||||
### 6.2 接口详情
|
||||
|
||||
#### METHOD /path
|
||||
**请求**:
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
|
||||
**响应**:
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
|
||||
[FOCUS]
|
||||
1. API端点: 路径/方法/说明
|
||||
2. 参数: 请求参数类型和校验规则
|
||||
3. 响应: 响应格式、状态码、错误码
|
||||
4. 时序: 典型调用流程 (选2-3个核心接口)
|
||||
|
||||
[RETURN JSON]
|
||||
{"status":"completed","output_file":"section-6-interfaces.md","summary":"<50字>","cross_module_notes":[],"stats":{}}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**Exception Analysis:**
|
||||
```javascript
|
||||
prompt = `
|
||||
## 分析目标
|
||||
分析项目的异常处理机制，为"异常处理设计"章节提供数据。
|
||||
### Exceptions
|
||||
|
||||
## 输出格式
|
||||
{
|
||||
"exception_types": [{name, parent, code, message, file}],
|
||||
"error_codes": [{code, message, severity, category}],
|
||||
"handling_patterns": [{pattern, locations: [], description}],
|
||||
"recovery_strategies": [{strategy, trigger, action, files}]
|
||||
}
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
prompt: `
|
||||
[ROLE] 可靠性工程师，专注于异常处理和恢复策略。
|
||||
|
||||
[TASK]
|
||||
分析 ${meta.scope_path}，生成 Section 7: 异常处理设计。
|
||||
输出: ${outDir}/sections/section-7-exceptions.md
|
||||
|
||||
[CPCC_SPEC]
|
||||
- 内容基于代码分析，无臆测
|
||||
- 图表编号: 图7-1 (异常处理流程图)
|
||||
- 每个子章节 ≥100字
|
||||
- 包含文件路径引用
|
||||
|
||||
[TEMPLATE]
|
||||
## 7. 异常处理设计
|
||||
|
||||
本章节展示${meta.software_name}的异常处理机制。
|
||||
|
||||
\`\`\`mermaid
|
||||
flowchart TD
|
||||
Req[请求] --> Try{Try-Catch}
|
||||
Try -->|正常| Process[处理]
|
||||
Try -->|异常| ErrType{类型}
|
||||
ErrType -->|E1| H1[处理1]
|
||||
ErrType -->|E2| H2[处理2]
|
||||
H1 --> Log[日志]
|
||||
H2 --> Log
|
||||
Process --> Resp[响应]
|
||||
\`\`\`
|
||||
|
||||
**图7-1 异常处理流程图**
|
||||
|
||||
### 7.1 异常类型
|
||||
| 异常类 | 错误码 | HTTP状态 | 说明 |
|
||||
|--------|--------|----------|------|
|
||||
|
||||
### 7.2 恢复策略
|
||||
| 场景 | 策略 | 说明 |
|
||||
|------|------|------|
|
||||
|
||||
[FOCUS]
|
||||
1. 异常类型: 自定义异常类及继承关系
|
||||
2. 错误码: 错误码定义和分类
|
||||
3. 处理模式: try-catch/中间件/装饰器
|
||||
4. 恢复策略: 重试/降级/熔断/告警
|
||||
|
||||
[RETURN JSON]
|
||||
{"status":"completed","output_file":"section-7-exceptions.md","summary":"<50字>","cross_module_notes":[],"stats":{}}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
Save each analysis to `analysis-{dimension}.json`.
|
||||
各 Agent 写入 `sections/section-N-xxx.md`，返回简要 JSON 供 Phase 2.5 汇总。
|
||||
|
||||
184
.claude/skills/copyright-docs/phases/02.5-consolidation.md
Normal file
184
.claude/skills/copyright-docs/phases/02.5-consolidation.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# Phase 2.5: Consolidation Agent
|
||||
|
||||
汇总所有分析 Agent 的产出，识别跨模块问题，生成汇总报告。
|
||||
|
||||
## 输入
|
||||
|
||||
```typescript
|
||||
interface ConsolidationInput {
|
||||
output_dir: string;
|
||||
agent_summaries: AgentReturn[]; // 6个Agent的简要返回
|
||||
cross_module_notes: string[]; // 所有跨模块备注
|
||||
metadata: ProjectMetadata;
|
||||
}
|
||||
```
|
||||
|
||||
## 执行
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
prompt: `
|
||||
## 任务
|
||||
作为汇总 Agent，读取所有章节文件，执行跨模块分析，生成汇总报告。
|
||||
|
||||
## 输入
|
||||
- 章节文件: {output_dir}/sections/section-*.md
|
||||
- Agent 摘要: ${JSON.stringify(agent_summaries)}
|
||||
- 跨模块备注: ${JSON.stringify(cross_module_notes)}
|
||||
|
||||
## 分析维度
|
||||
|
||||
### 1. 一致性检查
|
||||
- 术语一致性：同一概念是否使用相同名称
|
||||
- 命名规范：中英文命名是否统一
|
||||
- 图表编号：是否连续且正确
|
||||
|
||||
### 2. 完整性检查
|
||||
- 功能覆盖：section-3的功能是否都有对应接口(section-6)
|
||||
- 算法覆盖：section-4的算法是否在功能中被引用
|
||||
- 异常覆盖：section-7的异常是否覆盖所有接口
|
||||
|
||||
### 3. 关联性检查
|
||||
- 模块依赖：架构图(section-2)的依赖是否与实际一致
|
||||
- 数据流向：数据结构(section-5)是否与接口(section-6)匹配
|
||||
- 跨模块调用：是否存在未记录的跨模块依赖
|
||||
|
||||
### 4. 质量检查
|
||||
- 图表语法：Mermaid 语法是否正确
|
||||
- 内容深度：各章节是否有足够的详细说明
|
||||
- 代码引用：是否包含具体的文件路径和行号
|
||||
|
||||
## 输出文件
|
||||
|
||||
写入: {output_dir}/cross-module-summary.md
|
||||
|
||||
### 文件格式
|
||||
|
||||
\`\`\`markdown
|
||||
# 跨模块分析报告
|
||||
|
||||
## 1. 文档统计
|
||||
|
||||
| 章节 | 图表数 | 子章节数 | 字数 |
|
||||
|------|--------|----------|------|
|
||||
| 系统架构图 | 1 | 2 | ~500 |
|
||||
| ... | ... | ... | ... |
|
||||
|
||||
## 2. 发现的问题
|
||||
|
||||
### 2.1 严重问题 (必须修复)
|
||||
|
||||
| ID | 类型 | 位置 | 描述 | 建议 |
|
||||
|----|------|------|------|------|
|
||||
| E001 | 缺失 | section-6 | 缺少权限管理接口 | 补充 /api/permissions 相关接口 |
|
||||
|
||||
### 2.2 警告 (建议修复)
|
||||
|
||||
| ID | 类型 | 位置 | 描述 | 建议 |
|
||||
|----|------|------|------|------|
|
||||
| W001 | 一致性 | section-3/6 | 功能名"用户管理"与接口名"UserModule"不一致 | 统一使用中文或英文 |
|
||||
|
||||
### 2.3 提示 (可选修复)
|
||||
|
||||
| ID | 类型 | 位置 | 描述 |
|
||||
|----|------|------|------|
|
||||
| I001 | 增强 | section-4 | 建议为复杂算法添加复杂度分析 |
|
||||
|
||||
## 3. 跨模块关联图
|
||||
|
||||
\`\`\`mermaid
|
||||
graph LR
|
||||
S2[架构] --> S3[功能]
|
||||
S3 --> S4[算法]
|
||||
S3 --> S6[接口]
|
||||
S5[数据结构] --> S6
|
||||
S6 --> S7[异常]
|
||||
|
||||
S3 -.->|缺少关联| S5
|
||||
\`\`\`
|
||||
|
||||
## 4. 修复建议优先级
|
||||
|
||||
1. **E001**: 补充权限管理接口 (阻塞合规)
|
||||
2. **W001**: 统一术语命名 (影响一致性)
|
||||
3. ...
|
||||
|
||||
## 5. 下一步行动
|
||||
|
||||
- [ ] 修复 E001-E00x 严重问题
|
||||
- [ ] 处理 W001-W00x 警告
|
||||
- [ ] 可选处理 I001-I00x 提示
|
||||
\`\`\`
|
||||
|
||||
## 返回格式 (JSON)
|
||||
|
||||
{
|
||||
"status": "completed",
|
||||
"output_file": "cross-module-summary.md",
|
||||
"stats": {
|
||||
"total_sections": 6,
|
||||
"total_diagrams": 8,
|
||||
"total_words": 3500
|
||||
},
|
||||
"issues": {
|
||||
"errors": [
|
||||
{"id": "E001", "type": "missing", "section": "section-6", "desc": "缺少权限管理接口"}
|
||||
],
|
||||
"warnings": [
|
||||
{"id": "W001", "type": "inconsistency", "sections": ["section-3", "section-6"], "desc": "术语不一致"}
|
||||
],
|
||||
"info": [
|
||||
{"id": "I001", "type": "enhancement", "section": "section-4", "desc": "建议添加复杂度分析"}
|
||||
]
|
||||
},
|
||||
"cross_refs": {
|
||||
"found": 12,
|
||||
"missing": 3
|
||||
}
|
||||
}
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
## 问题分类
|
||||
|
||||
| 严重级别 | 前缀 | 含义 | 处理方式 |
|
||||
|----------|------|------|----------|
|
||||
| Error | E | 阻塞合规检查 | 必须修复 |
|
||||
| Warning | W | 影响文档质量 | 建议修复 |
|
||||
| Info | I | 可改进项 | 可选修复 |
|
||||
|
||||
## 问题类型
|
||||
|
||||
| 类型 | 说明 | 检查范围 |
|
||||
|------|------|----------|
|
||||
| missing | 缺失内容 | 功能-接口对应、异常覆盖 |
|
||||
| inconsistency | 不一致 | 术语、命名、编号 |
|
||||
| circular | 循环依赖 | 模块依赖关系 |
|
||||
| orphan | 孤立内容 | 未被引用的功能/数据结构 |
|
||||
| syntax | 语法错误 | Mermaid 图表 |
|
||||
| enhancement | 增强建议 | 内容深度、引用 |
|
||||
|
||||
## 与 Phase 4 的集成
|
||||
|
||||
```javascript
|
||||
// Phase 4 装配时读取汇总报告
|
||||
const summary = JSON.parse(Read(`${outputDir}/cross-module-summary.md`));
|
||||
|
||||
if (summary.issues.errors.length > 0) {
|
||||
// 阻止装配，先修复严重问题
|
||||
return {
|
||||
action: "fix_required",
|
||||
errors: summary.issues.errors
|
||||
};
|
||||
}
|
||||
|
||||
// 在最终文档中插入跨模块说明
|
||||
insertCrossModuleSummary(document, summary);
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
- 文件: `cross-module-summary.md`
|
||||
- 返回: 问题列表 + 统计信息
|
||||
@@ -1,147 +0,0 @@
|
||||
# Phase 3: Mermaid Diagram Generation
|
||||
|
||||
Generate Mermaid diagrams for each document section.
|
||||
|
||||
> **Reference**: See [mermaid-utils.md](../../_shared/mermaid-utils.md) for utility functions.
|
||||
|
||||
## Execution
|
||||
|
||||
### Diagram Mapping
|
||||
|
||||
| Section | Diagram Type | Format | File |
|
||||
|---------|--------------|--------|------|
|
||||
| 2. 系统架构图 | Architecture | graph TD | architecture.mmd |
|
||||
| 3. 功能模块设计 | Function Tree | flowchart TD | functions.mmd |
|
||||
| 4. 核心算法与流程 | Algorithm Flow | flowchart TD | algorithm-*.mmd |
|
||||
| 5. 数据结构设计 | Class Diagram | classDiagram | class-diagram.mmd |
|
||||
| 6. 接口设计 | Sequence | sequenceDiagram | sequence-*.mmd |
|
||||
| 7. 异常处理设计 | Error Flow | flowchart TD | exception-flow.mmd |
|
||||
|
||||
### Section 2: System Architecture
|
||||
|
||||
```javascript
|
||||
function generateArchitectureDiagram(analysis) {
|
||||
let mermaid = 'graph TD\n';
|
||||
|
||||
for (const layer of analysis.layers) {
|
||||
mermaid += ` subgraph ${sanitizeId(layer.name)}["${escapeLabel(layer.name)}"]\n`;
|
||||
for (const comp of layer.components) {
|
||||
mermaid += ` ${sanitizeId(comp)}["${escapeLabel(comp)}"]\n`;
|
||||
}
|
||||
mermaid += ' end\n';
|
||||
}
|
||||
|
||||
for (const flow of analysis.data_flow) {
|
||||
mermaid += ` ${sanitizeId(flow.from)} -->|"${escapeLabel(flow.description)}"| ${sanitizeId(flow.to)}\n`;
|
||||
}
|
||||
|
||||
return mermaid;
|
||||
}
|
||||
```
|
||||
|
||||
### Section 3: Function Modules
|
||||
|
||||
```javascript
|
||||
function generateFunctionDiagram(analysis, softwareName) {
|
||||
let mermaid = 'flowchart TD\n';
|
||||
mermaid += ` ROOT["${escapeLabel(softwareName)}"]\n`;
|
||||
|
||||
for (const group of analysis.feature_groups) {
|
||||
mermaid += ` subgraph ${sanitizeId(group.group_name)}["${escapeLabel(group.group_name)}"]\n`;
|
||||
for (const feature of group.features) {
|
||||
mermaid += ` ${sanitizeId(feature.id)}["${escapeLabel(feature.name)}"]\n`;
|
||||
}
|
||||
mermaid += ' end\n';
|
||||
mermaid += ` ROOT --> ${sanitizeId(group.group_name)}\n`;
|
||||
}
|
||||
|
||||
return mermaid;
|
||||
}
|
||||
```
|
||||
|
||||
### Section 4: Algorithm Flowchart (with branches)
|
||||
|
||||
```javascript
|
||||
// Uses generateAlgorithmFlowchart from _shared/mermaid-utils.md
|
||||
// Supports: type (process/decision/io), next, conditions
|
||||
|
||||
const flowchart = generateAlgorithmFlowchart({
|
||||
name: algorithm.name,
|
||||
inputs: algorithm.inputs,
|
||||
outputs: algorithm.outputs,
|
||||
steps: algorithm.steps // Each step can have type, next, conditions
|
||||
});
|
||||
```
|
||||
|
||||
### Section 5: Class Diagram
|
||||
|
||||
```javascript
|
||||
function generateClassDiagram(analysis) {
|
||||
let mermaid = 'classDiagram\n';
|
||||
|
||||
for (const entity of analysis.entities) {
|
||||
mermaid += ` class ${sanitizeId(entity.name)} {\n`;
|
||||
for (const prop of entity.properties) {
|
||||
const vis = {public: '+', private: '-', protected: '#'}[prop.visibility] || '+';
|
||||
mermaid += ` ${vis}${sanitizeType(prop.type)} ${prop.name}\n`;
|
||||
}
|
||||
for (const method of entity.methods) {
|
||||
const vis = {public: '+', private: '-', protected: '#'}[method.visibility] || '+';
|
||||
mermaid += ` ${vis}${method.name}(${method.params}) ${sanitizeType(method.return_type)}\n`;
|
||||
}
|
||||
mermaid += ' }\n';
|
||||
}
|
||||
|
||||
const arrows = {
|
||||
inheritance: '--|>',
|
||||
composition: '*--',
|
||||
aggregation: 'o--',
|
||||
association: '-->'
|
||||
};
|
||||
|
||||
for (const rel of analysis.relationships) {
|
||||
const arrow = arrows[rel.type] || '-->';
|
||||
mermaid += ` ${sanitizeId(rel.from)} ${arrow} ${sanitizeId(rel.to)} : ${escapeLabel(rel.description)}\n`;
|
||||
}
|
||||
|
||||
return mermaid;
|
||||
}
|
||||
```
|
||||
|
||||
### Section 6: Sequence Diagram
|
||||
|
||||
```javascript
|
||||
function generateSequenceDiagram(scenario) {
|
||||
let mermaid = 'sequenceDiagram\n';
|
||||
|
||||
for (const actor of scenario.actors) {
|
||||
mermaid += ` participant ${sanitizeId(actor.id)} as ${escapeLabel(actor.name)}\n`;
|
||||
}
|
||||
|
||||
for (const msg of scenario.messages) {
|
||||
const arrow = msg.type === 'async' ? '-)' : '->>';
|
||||
mermaid += ` ${sanitizeId(msg.from)}${arrow}${sanitizeId(msg.to)}: ${escapeLabel(msg.description)}\n`;
|
||||
}
|
||||
|
||||
return mermaid;
|
||||
}
|
||||
```
|
||||
|
||||
### Validation
|
||||
|
||||
```javascript
|
||||
// Validate all generated diagrams
|
||||
const results = validateDiagramDirectory(`${outputDir}/diagrams`);
|
||||
const failed = results.filter(r => !r.valid);
|
||||
|
||||
if (failed.length > 0) {
|
||||
// Regenerate failed diagrams with stricter escaping
|
||||
for (const f of failed) {
|
||||
regenerateWithFixes(f.file, f.issues);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
Save diagrams to `diagrams/` with `manifest.json`.
|
||||
@@ -1,128 +1,276 @@
|
||||
# Phase 4: Document Assembly
|
||||
|
||||
Assemble all analysis and diagrams into CPCC-compliant document.
|
||||
合并所有章节文件，生成最终 CPCC 合规文档。
|
||||
|
||||
## Execution
|
||||
> **规范参考**: [../specs/cpcc-requirements.md](../specs/cpcc-requirements.md)
|
||||
|
||||
### Document Structure (7 Sections)
|
||||
## 输入
|
||||
|
||||
```typescript
|
||||
interface AssemblyInput {
|
||||
output_dir: string;
|
||||
metadata: ProjectMetadata;
|
||||
consolidation: {
|
||||
issues: { errors: Issue[], warnings: Issue[], info: Issue[] };
|
||||
stats: { total_sections: number, total_diagrams: number };
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## 执行流程
|
||||
|
||||
```javascript
|
||||
// 1. 检查是否有阻塞性问题
|
||||
if (consolidation.issues.errors.length > 0) {
|
||||
// 阻止装配，先修复
|
||||
return AskUserQuestion({
|
||||
questions: [{
|
||||
question: `发现 ${consolidation.issues.errors.length} 个严重问题，如何处理？`,
|
||||
header: "阻塞问题",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{label: "查看并修复", description: "显示问题列表，手动修复后重试"},
|
||||
{label: "忽略继续", description: "跳过问题检查，继续装配"},
|
||||
{label: "终止", description: "停止文档生成"}
|
||||
]
|
||||
}]
|
||||
});
|
||||
}
|
||||
|
||||
// 2. 读取章节文件
|
||||
const sections = [
|
||||
Read(`${outputDir}/sections/section-2-architecture.md`),
|
||||
Read(`${outputDir}/sections/section-3-functions.md`),
|
||||
Read(`${outputDir}/sections/section-4-algorithms.md`),
|
||||
Read(`${outputDir}/sections/section-5-data-structures.md`),
|
||||
Read(`${outputDir}/sections/section-6-interfaces.md`),
|
||||
Read(`${outputDir}/sections/section-7-exceptions.md`)
|
||||
];
|
||||
|
||||
// 3. 读取汇总报告
|
||||
const crossModuleSummary = Read(`${outputDir}/cross-module-summary.md`);
|
||||
|
||||
// 4. 装配文档
|
||||
const finalDoc = assembleDocument(metadata, sections, crossModuleSummary);
|
||||
|
||||
// 5. 写入最终文件
|
||||
Write(`${outputDir}/${metadata.software_name}-软件设计说明书.md`, finalDoc);
|
||||
```
|
||||
|
||||
## 文档结构
|
||||
|
||||
```markdown
|
||||
<!-- 页眉：{软件名称} - 版本号：{版本号} -->
|
||||
<!-- 注：最终文档页码位于每页右上角 -->
|
||||
|
||||
# {软件名称} 软件设计说明书
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 软件名称 | {software_name} |
|
||||
| 版本号 | {version} |
|
||||
| 生成日期 | {date} |
|
||||
|
||||
---
|
||||
|
||||
## 1. 软件概述
|
||||
|
||||
### 1.1 软件背景与用途
|
||||
{从 metadata 生成}
|
||||
|
||||
### 1.2 开发目标与特点
|
||||
{从 metadata 生成}
|
||||
|
||||
### 1.3 运行环境与技术架构
|
||||
{从 metadata.tech_stack 生成}
|
||||
|
||||
## 2. 系统架构图
|
||||
图2-1 系统架构图
|
||||
(Mermaid graph TD)
|
||||
---
|
||||
|
||||
## 3. 功能模块设计
|
||||
图3-1 功能模块结构图
|
||||
(Mermaid flowchart TD)
|
||||
<!-- 以下章节直接引用 Agent 产出 -->
|
||||
|
||||
## 4. 核心算法与流程
|
||||
图4-1 {算法名称}流程图
|
||||
(Mermaid flowchart TD)
|
||||
{section-2-architecture.md 内容}
|
||||
|
||||
## 5. 数据结构设计
|
||||
图5-1 数据结构类图
|
||||
(Mermaid classDiagram)
|
||||
---
|
||||
|
||||
## 6. 接口设计
|
||||
图6-1 接口调用时序图
|
||||
(Mermaid sequenceDiagram)
|
||||
{section-3-functions.md 内容}
|
||||
|
||||
## 7. 异常处理设计
|
||||
图7-1 异常处理流程图
|
||||
(Mermaid flowchart TD)
|
||||
---
|
||||
|
||||
{section-4-algorithms.md 内容}
|
||||
|
||||
---
|
||||
|
||||
{section-5-data-structures.md 内容}
|
||||
|
||||
---
|
||||
|
||||
{section-6-interfaces.md 内容}
|
||||
|
||||
---
|
||||
|
||||
{section-7-exceptions.md 内容}
|
||||
|
||||
---
|
||||
|
||||
## 附录A：跨模块分析
|
||||
|
||||
{cross-module-summary.md 的问题列表和关联图}
|
||||
|
||||
---
|
||||
|
||||
## 附录B：文档统计
|
||||
|
||||
| 章节 | 图表数 | 字数 |
|
||||
|------|--------|------|
|
||||
| ... | ... | ... |
|
||||
|
||||
---
|
||||
|
||||
<!-- 页脚：生成时间 {timestamp} -->
|
||||
```
|
||||
|
||||
### Section Templates
|
||||
## Section 1 生成
|
||||
|
||||
**Section 1: 软件概述**
|
||||
```markdown
|
||||
```javascript
|
||||
function generateSection1(metadata) {
|
||||
const categoryDescriptions = {
|
||||
"命令行工具 (CLI)": "提供命令行界面，用户通过终端命令与系统交互",
|
||||
"后端服务/API": "提供 RESTful/GraphQL API 接口，支持前端或其他服务调用",
|
||||
"SDK/库": "提供可复用的代码库，供其他项目集成使用",
|
||||
"数据处理系统": "处理数据导入、转换、分析和导出",
|
||||
"自动化脚本": "自动执行重复性任务，提高工作效率"
|
||||
};
|
||||
|
||||
return `
|
||||
## 1. 软件概述
|
||||
|
||||
### 1.1 软件背景与用途
|
||||
|
||||
${software_name}是一款${category}软件，主要用于${inferred_purpose}。
|
||||
${metadata.software_name}是一款${metadata.category}软件。${categoryDescriptions[metadata.category]}
|
||||
|
||||
本软件基于${tech_stack.language}语言开发，采用${tech_stack.framework}实现核心功能。
|
||||
本软件基于${metadata.tech_stack.language}语言开发，运行于${metadata.tech_stack.runtime}环境，采用${metadata.tech_stack.framework || '原生'}框架实现核心功能。
|
||||
|
||||
### 1.2 开发目标与特点
|
||||
|
||||
**开发目标**：
|
||||
${objectives}
|
||||
${generateObjectives(metadata)}
|
||||
|
||||
**技术特点**：
|
||||
${features}
|
||||
${generateFeatures(metadata)}
|
||||
|
||||
### 1.3 运行环境与技术架构
|
||||
|
||||
**运行环境**：
|
||||
- 操作系统：${os}
|
||||
- 运行时：${runtime}
|
||||
- 依赖环境：${dependencies}
|
||||
- 操作系统：${metadata.os || 'Windows/Linux/macOS'}
|
||||
- 运行时：${metadata.tech_stack.runtime}
|
||||
- 依赖环境：${metadata.tech_stack.dependencies?.join(', ') || '无'}
|
||||
|
||||
**技术架构**：
|
||||
- 架构模式：${architecture_pattern}
|
||||
- 核心框架：${framework}
|
||||
```
|
||||
|
||||
**Section 2-7: Pattern**
|
||||
```markdown
|
||||
## {N}. {章节标题}
|
||||
|
||||
本章节展示${software_name}的{描述}。
|
||||
|
||||
\`\`\`mermaid
|
||||
${diagram_content}
|
||||
\`\`\`
|
||||
|
||||
**图{N}-1 {图表标题}**
|
||||
|
||||
### {子标题}
|
||||
|
||||
{详细说明}
|
||||
```
|
||||
|
||||
### Figure Numbering
|
||||
|
||||
| Section | Figure Number | Title |
|
||||
|---------|---------------|-------|
|
||||
| 2 | 图2-1 | 系统架构图 |
|
||||
| 3 | 图3-1 | 功能模块结构图 |
|
||||
| 4 | 图4-1, 图4-2... | {算法名称}流程图 |
|
||||
| 5 | 图5-1 | 数据结构类图 |
|
||||
| 6 | 图6-1, 图6-2... | {接口名称}时序图 |
|
||||
| 7 | 图7-1 | 异常处理流程图 |
|
||||
|
||||
### Assembly Code
|
||||
|
||||
```javascript
|
||||
function assembleDocument(metadata, analyses, diagrams) {
|
||||
let doc = '';
|
||||
|
||||
// Header
|
||||
doc += `<!-- 页眉：${metadata.software_name} - 版本号：${metadata.version} -->\n`;
|
||||
doc += `<!-- 注：最终文档页码位于每页右上角 -->\n\n`;
|
||||
|
||||
// Generate each section
|
||||
doc += generateSection1(metadata, analyses.architecture);
|
||||
doc += generateSection2(analyses.architecture, diagrams.architecture);
|
||||
doc += generateSection3(analyses.functions, diagrams.functions, metadata.software_name);
|
||||
doc += generateSection4(analyses.algorithms, diagrams.algorithms);
|
||||
doc += generateSection5(analyses.data_structures, diagrams.class);
|
||||
doc += generateSection6(analyses.interfaces, diagrams.sequences);
|
||||
doc += generateSection7(analyses.exceptions, diagrams.exception_flow);
|
||||
|
||||
return doc;
|
||||
- 架构模式：${metadata.architecture_pattern || '分层架构'}
|
||||
- 核心框架：${metadata.tech_stack.framework || '原生实现'}
|
||||
- 主要模块：${metadata.main_modules?.join(', ') || '见第2章'}
|
||||
`;
|
||||
}
|
||||
```
|
||||
|
||||
## Output
|
||||
## 装配函数
|
||||
|
||||
Generate `{软件名称}-软件设计说明书.md`.
|
||||
```javascript
|
||||
function assembleDocument(metadata, sections, crossModuleSummary) {
|
||||
const header = `<!-- 页眉：${metadata.software_name} - 版本号：${metadata.version} -->
|
||||
<!-- 注：最终文档页码位于每页右上角 -->
|
||||
|
||||
# ${metadata.software_name} 软件设计说明书
|
||||
|
||||
## 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 软件名称 | ${metadata.software_name} |
|
||||
| 版本号 | ${metadata.version} |
|
||||
| 生成日期 | ${new Date().toLocaleDateString('zh-CN')} |
|
||||
|
||||
---
|
||||
|
||||
`;
|
||||
|
||||
const section1 = generateSection1(metadata);
|
||||
|
||||
// 合并章节 (sections 已经是完整的 MD 内容)
|
||||
const mainContent = sections.join('\n\n---\n\n');
|
||||
|
||||
// 提取跨模块问题作为附录
|
||||
const appendixA = extractAppendixA(crossModuleSummary);
|
||||
|
||||
// 生成统计
|
||||
const appendixB = generateStats(sections);
|
||||
|
||||
const footer = `
|
||||
---
|
||||
|
||||
<!-- 页脚：生成时间 ${new Date().toISOString()} -->
|
||||
`;
|
||||
|
||||
return header + section1 + '\n\n---\n\n' + mainContent + '\n\n' + appendixA + '\n\n' + appendixB + footer;
|
||||
}
|
||||
```
|
||||
|
||||
## 附录生成
|
||||
|
||||
### 附录A：跨模块分析
|
||||
|
||||
```javascript
|
||||
function extractAppendixA(crossModuleSummary) {
|
||||
// 从 cross-module-summary.md 提取关键内容
|
||||
return `
|
||||
## 附录A：跨模块分析
|
||||
|
||||
本附录汇总了文档生成过程中发现的跨模块问题和关联关系。
|
||||
|
||||
${extractSection(crossModuleSummary, '## 2. 发现的问题')}
|
||||
|
||||
${extractSection(crossModuleSummary, '## 3. 跨模块关联图')}
|
||||
`;
|
||||
}
|
||||
```
|
||||
|
||||
### 附录B：文档统计
|
||||
|
||||
```javascript
|
||||
function generateStats(sections) {
|
||||
const stats = sections.map((content, idx) => {
|
||||
const diagrams = (content.match(/```mermaid/g) || []).length;
|
||||
const words = content.length;
|
||||
const sectionNames = ['系统架构图', '功能模块设计', '核心算法与流程',
|
||||
'数据结构设计', '接口设计', '异常处理设计'];
|
||||
return { name: sectionNames[idx], diagrams, words };
|
||||
});
|
||||
|
||||
let table = `
|
||||
## 附录B：文档统计
|
||||
|
||||
| 章节 | 图表数 | 字数 |
|
||||
|------|--------|------|
|
||||
`;
|
||||
|
||||
stats.forEach(s => {
|
||||
table += `| ${s.name} | ${s.diagrams} | ${s.words} |\n`;
|
||||
});
|
||||
|
||||
const total = stats.reduce((acc, s) => ({
|
||||
diagrams: acc.diagrams + s.diagrams,
|
||||
words: acc.words + s.words
|
||||
}), { diagrams: 0, words: 0 });
|
||||
|
||||
table += `| **总计** | **${total.diagrams}** | **${total.words}** |\n`;
|
||||
|
||||
return table;
|
||||
}
|
||||
```
|
||||
|
||||
## 输出
|
||||
|
||||
- 最终文档: `{软件名称}-软件设计说明书.md`
|
||||
- 保留原始章节文件供追溯
|
||||
|
||||
Reference in New Issue
Block a user