feat: Implement multi-phase project analysis workflow with Mermaid diagram generation and CPCC compliance documentation

- Phase 3: Added Mermaid diagram generation for system architecture, function modules, algorithms, class diagrams, sequence diagrams, and error flows. - Phase 4: Assembled analysis and diagrams into a structured CPCC-compliant document with section templates and figure numbering. - Phase 5: Developed compliance review process with iterative refinement based on analysis findings and user feedback. - Added CPCC compliance requirements and quality standards for project analysis reports. - Established a comprehensive project analysis skill with detailed execution flow and report types. - Enhanced error handling and recovery mechanisms throughout the analysis phases.
2026-02-14 02:42:04 +08:00 · 2025-12-26 11:44:29 +08:00
parent f14c3299bc
commit 89f6ac6804
25 changed files with 5018 additions and 34 deletions
--- a/.claude/skills/copyright-docs/phases/01-metadata-collection.md
+++ b/.claude/skills/copyright-docs/phases/01-metadata-collection.md
@@ -0,0 +1,78 @@
+# Phase 1: Metadata Collection
+
+Collect software metadata for document header and context.
+
+## Execution
+
+### Step 1: Software Name & Version
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "请输入软件名称（将显示在文档页眉）：",
+    header: "软件名称",
+    multiSelect: false,
+    options: [
+      {label: "自动检测", description: "从 package.json 或项目配置读取"},
+      {label: "手动输入", description: "输入自定义名称"}
+    ]
+  }]
+})
+```
+
+### Step 2: Software Category
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "软件属于哪种类型？",
+    header: "软件类型",
+    multiSelect: false,
+    options: [
+      {label: "命令行工具 (CLI)", description: "重点描述命令、参数"},
+      {label: "后端服务/API", description: "重点描述端点、协议"},
+      {label: "SDK/库", description: "重点描述接口、集成"},
+      {label: "数据处理系统", description: "重点描述数据流、转换"},
+      {label: "自动化脚本", description: "重点描述工作流、触发器"}
+    ]
+  }]
+})
+```
+
+### Step 3: Scope Definition
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "分析范围是什么？",
+    header: "分析范围",
+    multiSelect: false,
+    options: [
+      {label: "整个项目", description: "分析全部源代码"},
+      {label: "指定目录", description: "仅分析 src/ 或其他目录"},
+      {label: "自定义路径", description: "手动指定路径"}
+    ]
+  }]
+})
+```
+
+## Output
+
+Save metadata to `project-metadata.json`:
+
+```json
+{
+  "software_name": "智能数据分析系统",
+  "version": "V1.0.0",
+  "category": "后端服务/API",
+  "scope_path": "src/",
+  "tech_stack": {
+    "language": "TypeScript",
+    "runtime": "Node.js 18+",
+    "framework": "Express.js",
+    "dependencies": ["mongoose", "redis", "bull"]
+  },
+  "entry_points": ["src/index.ts", "src/cli.ts"],
+  "main_modules": ["auth", "data", "api", "worker"]
+}
+```
--- a/.claude/skills/copyright-docs/phases/02-deep-analysis.md
+++ b/.claude/skills/copyright-docs/phases/02-deep-analysis.md
@@ -0,0 +1,138 @@
+# Phase 2: Deep Code Analysis
+
+Launch 6 parallel agents for multi-dimensional code analysis.
+
+## Execution
+
+### Analysis Dimensions
+
+| 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 Prompts
+
+**Architecture Analysis:**
+```javascript
+Task({
+  subagent_type: "cli-explore-agent",
+  prompt: `
+## 分析目标
+分析项目的系统架构，为"系统架构图"章节提供数据。
+
+## 分析内容
+1. 分层结构：识别代码的分层（Controller/Service/Repository）
+2. 模块边界：各模块的职责范围和边界
+3. 依赖关系：模块间的依赖方向和类型
+4. 核心组件：系统的核心组件及其作用
+5. 数据流向：数据在各层之间的流动路径
+
+## 输出格式
+{
+  "layers": [{name, components, responsibility}],
+  "modules": [{name, path, responsibility, dependencies}],
+  "data_flow": [{from, to, data_type, description}],
+  "core_components": [{name, type, responsibility}]
+}
+`
+})
+```
+
+**Function Analysis:**
+```javascript
+prompt = `
+## 分析目标
+分析项目的功能模块，为"功能模块设计"章节提供数据。
+
+## 输出格式
+{
+  "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}]
+}
+`
+```
+
+**Algorithm Analysis:**
+```javascript
+prompt = `
+## 分析目标
+分析项目的核心算法和业务逻辑，为"核心算法与流程"章节提供数据。
+
+## 输出格式
+{
+  "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}]
+}
+`
+```
+
+**Data Structure Analysis:**
+```javascript
+prompt = `
+## 分析目标
+分析项目的数据结构，为"数据结构设计"章节提供数据。
+
+## 输出格式
+{
+  "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}]}]
+}
+`
+```
+
+**Interface Analysis:**
+```javascript
+prompt = `
+## 分析目标
+分析项目的接口设计，为"接口设计"章节提供数据。
+
+## 输出格式
+{
+  "apis": [{
+    name, path, method, description,
+    parameters: [{name, type, required, description}],
+    response: {type, schema, description},
+    category
+  }],
+  "protocols": [{name, type, description}]
+}
+`
+```
+
+**Exception Analysis:**
+```javascript
+prompt = `
+## 分析目标
+分析项目的异常处理机制，为"异常处理设计"章节提供数据。
+
+## 输出格式
+{
+  "exception_types": [{name, parent, code, message, file}],
+  "error_codes": [{code, message, severity, category}],
+  "handling_patterns": [{pattern, locations: [], description}],
+  "recovery_strategies": [{strategy, trigger, action, files}]
+}
+`
+```
+
+## Output
+
+Save each analysis to `analysis-{dimension}.json`.
--- a/.claude/skills/copyright-docs/phases/03-diagram-generation.md
+++ b/.claude/skills/copyright-docs/phases/03-diagram-generation.md
@@ -0,0 +1,147 @@
+# 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`.
--- a/.claude/skills/copyright-docs/phases/04-document-assembly.md
+++ b/.claude/skills/copyright-docs/phases/04-document-assembly.md
@@ -0,0 +1,128 @@
+# Phase 4: Document Assembly
+
+Assemble all analysis and diagrams into CPCC-compliant document.
+
+## Execution
+
+### Document Structure (7 Sections)
+
+```markdown
+<!-- 页眉：{软件名称} - 版本号：{版本号} -->
+<!-- 注：最终文档页码位于每页右上角 -->
+
+## 1. 软件概述
+### 1.1 软件背景与用途
+### 1.2 开发目标与特点
+### 1.3 运行环境与技术架构
+
+## 2. 系统架构图
+图2-1 系统架构图
+(Mermaid graph TD)
+
+## 3. 功能模块设计
+图3-1 功能模块结构图
+(Mermaid flowchart TD)
+
+## 4. 核心算法与流程
+图4-1 {算法名称}流程图
+(Mermaid flowchart TD)
+
+## 5. 数据结构设计
+图5-1 数据结构类图
+(Mermaid classDiagram)
+
+## 6. 接口设计
+图6-1 接口调用时序图
+(Mermaid sequenceDiagram)
+
+## 7. 异常处理设计
+图7-1 异常处理流程图
+(Mermaid flowchart TD)
+```
+
+### Section Templates
+
+**Section 1: 软件概述**
+```markdown
+## 1. 软件概述
+
+### 1.1 软件背景与用途
+
+${software_name}是一款${category}软件，主要用于${inferred_purpose}。
+
+本软件基于${tech_stack.language}语言开发，采用${tech_stack.framework}实现核心功能。
+
+### 1.2 开发目标与特点
+
+**开发目标**：
+${objectives}
+
+**技术特点**：
+${features}
+
+### 1.3 运行环境与技术架构
+
+**运行环境**：
+- 操作系统：${os}
+- 运行时：${runtime}
+- 依赖环境：${dependencies}
+
+**技术架构**：
+- 架构模式：${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;
+}
+```
+
+## Output
+
+Generate `{软件名称}-软件设计说明书.md`.
--- a/.claude/skills/copyright-docs/phases/05-compliance-refinement.md
+++ b/.claude/skills/copyright-docs/phases/05-compliance-refinement.md
@@ -0,0 +1,192 @@
+# Phase 5: Compliance Review & Iterative Refinement
+
+Discovery-driven refinement loop until CPCC compliance is met.
+
+## Execution
+
+### Step 1: Extract Compliance Issues
+
+```javascript
+function extractComplianceIssues(validationResult, deepAnalysis) {
+  return {
+    // Missing or incomplete sections
+    missingSections: validationResult.details
+      .filter(d => !d.pass)
+      .map(d => ({
+        section: d.name,
+        severity: 'critical',
+        suggestion: `需要补充 ${d.name} 相关内容`
+      })),
+
+    // Features with weak descriptions (< 50 chars)
+    weakDescriptions: (deepAnalysis.functions?.feature_list || [])
+      .filter(f => !f.description || f.description.length < 50)
+      .map(f => ({
+        feature: f.name,
+        current: f.description || '(无描述)',
+        severity: 'warning'
+      })),
+
+    // Complex algorithms without detailed flowcharts
+    complexAlgorithms: (deepAnalysis.algorithms?.algorithms || [])
+      .filter(a => (a.complexity || 0) > 10 && (a.steps?.length || 0) < 5)
+      .map(a => ({
+        algorithm: a.name,
+        complexity: a.complexity,
+        file: a.file,
+        severity: 'warning'
+      })),
+
+    // Data relationships without descriptions
+    incompleteRelationships: (deepAnalysis.data_structures?.relationships || [])
+      .filter(r => !r.description)
+      .map(r => ({from: r.from, to: r.to, severity: 'info'})),
+
+    // Diagram validation issues
+    diagramIssues: (deepAnalysis.diagrams?.validation || [])
+      .filter(d => !d.valid)
+      .map(d => ({file: d.file, issues: d.issues, severity: 'critical'}))
+  };
+}
+```
+
+### Step 2: Build Dynamic Questions
+
+```javascript
+function buildComplianceQuestions(issues) {
+  const questions = [];
+
+  if (issues.missingSections.length > 0) {
+    questions.push({
+      question: `发现 ${issues.missingSections.length} 个章节内容不完整，需要补充哪些？`,
+      header: "章节补充",
+      multiSelect: true,
+      options: issues.missingSections.slice(0, 4).map(s => ({
+        label: s.section,
+        description: s.suggestion
+      }))
+    });
+  }
+
+  if (issues.weakDescriptions.length > 0) {
+    questions.push({
+      question: `以下 ${issues.weakDescriptions.length} 个功能描述过于简短，请选择需要详细说明的：`,
+      header: "功能描述",
+      multiSelect: true,
+      options: issues.weakDescriptions.slice(0, 4).map(f => ({
+        label: f.feature,
+        description: `当前：${f.current.substring(0, 30)}...`
+      }))
+    });
+  }
+
+  if (issues.complexAlgorithms.length > 0) {
+    questions.push({
+      question: `发现 ${issues.complexAlgorithms.length} 个复杂算法缺少详细流程图，是否生成？`,
+      header: "算法详解",
+      multiSelect: false,
+      options: [
+        {label: "全部生成 (推荐)", description: "为所有复杂算法生成含分支/循环的流程图"},
+        {label: "仅最复杂的", description: `仅为 ${issues.complexAlgorithms[0]?.algorithm} 生成`},
+        {label: "跳过", description: "保持当前简单流程图"}
+      ]
+    });
+  }
+
+  questions.push({
+    question: "如何处理当前文档？",
+    header: "操作",
+    multiSelect: false,
+    options: [
+      {label: "应用修改并继续", description: "应用上述选择，继续检查"},
+      {label: "完成文档", description: "当前文档满足要求，生成最终版本"},
+      {label: "重新分析", description: "使用不同配置重新分析代码"}
+    ]
+  });
+
+  return questions.slice(0, 4);
+}
+```
+
+### Step 3: Apply Updates
+
+```javascript
+async function applyComplianceUpdates(responses, issues, analyses, outputDir) {
+  const updates = [];
+
+  if (responses['章节补充']) {
+    for (const section of responses['章节补充']) {
+      const sectionAnalysis = await Task({
+        subagent_type: "cli-explore-agent",
+        prompt: `深入分析 ${section.section} 所需内容...`
+      });
+      updates.push({type: 'section_supplement', section: section.section, data: sectionAnalysis});
+    }
+  }
+
+  if (responses['算法详解'] === '全部生成 (推荐)') {
+    for (const algo of issues.complexAlgorithms) {
+      const detailedSteps = await analyzeAlgorithmInDepth(algo, analyses);
+      const flowchart = generateAlgorithmFlowchart({
+        name: algo.algorithm,
+        inputs: detailedSteps.inputs,
+        outputs: detailedSteps.outputs,
+        steps: detailedSteps.steps
+      });
+      Write(`${outputDir}/diagrams/algorithm-${sanitizeId(algo.algorithm)}-detailed.mmd`, flowchart);
+      updates.push({type: 'algorithm_flowchart', algorithm: algo.algorithm});
+    }
+  }
+
+  return updates;
+}
+```
+
+### Step 4: Iteration Loop
+
+```javascript
+async function runComplianceLoop(documentPath, analyses, metadata, outputDir) {
+  let iteration = 0;
+  const maxIterations = 5;
+  
+  while (iteration < maxIterations) {
+    iteration++;
+    
+    // Validate current document
+    const document = Read(documentPath);
+    const validation = validateCPCCCompliance(document, analyses);
+    
+    // Extract issues
+    const issues = extractComplianceIssues(validation, analyses);
+    const totalIssues = Object.values(issues).flat().length;
+    
+    if (totalIssues === 0) {
+      console.log("✅ 所有检查通过，文档符合 CPCC 要求");
+      break;
+    }
+    
+    // Ask user
+    const questions = buildComplianceQuestions(issues);
+    const responses = await AskUserQuestion({questions});
+    
+    if (responses['操作'] === '完成文档') break;
+    if (responses['操作'] === '重新分析') return {action: 'restart'};
+    
+    // Apply updates
+    const updates = await applyComplianceUpdates(responses, issues, analyses, outputDir);
+    
+    // Regenerate document
+    const updatedDocument = regenerateDocument(document, updates, analyses);
+    Write(documentPath, updatedDocument);
+    
+    // Archive iteration
+    Write(`${outputDir}/iterations/v${iteration}.md`, document);
+  }
+  
+  return {action: 'finalized', iterations: iteration};
+}
+```
+
+## Output
+
+Final compliant document + iteration history in `iterations/`.