feat: Implement adaptive RRF weights and query intent detection

- Added integration tests for adaptive RRF weights in hybrid search. - Enhanced query intent detection with new classifications: keyword, semantic, and mixed. - Introduced symbol boosting in search results based on explicit symbol matches. - Implemented embedding-based reranking with configurable options. - Added global symbol index for efficient symbol lookups across projects. - Improved file deletion handling on Windows to avoid permission errors. - Updated chunk configuration to increase overlap for better context. - Modified package.json test script to target specific test files. - Created comprehensive writing style guidelines for documentation. - Added TypeScript tests for query intent detection and adaptive weights. - Established performance benchmarks for global symbol indexing.
2026-02-14 02:42:04 +08:00 · 2025-12-26 15:08:47 +08:00
parent ecd5085e51
commit 4061ae48c4
29 changed files with 2685 additions and 828 deletions
--- a/.claude/skills/copyright-docs/phases/02-deep-analysis.md
+++ b/.claude/skills/copyright-docs/phases/02-deep-analysis.md
@@ -5,6 +5,22 @@
 > **模板参考**: [../templates/agent-base.md](../templates/agent-base.md)
 > **规范参考**: [../specs/cpcc-requirements.md](../specs/cpcc-requirements.md)

+## Agent 执行前置条件
+
+**每个 Agent 必须首先读取以下规范文件**：
+
+```javascript
+// Agent 启动时的第一步操作
+const specs = {
+  cpcc: Read(`${skillRoot}/specs/cpcc-requirements.md`)
+};
+```
+
+规范文件路径（相对于 skill 根目录）：
+- `specs/cpcc-requirements.md` - CPCC 软著申请规范要求
+
+---
+
 ## Agent 配置

 | Agent | 输出文件 | 章节 |
@@ -60,7 +76,13 @@ return { summaries, cross_notes: summaries.flatMap(s => s.cross_module_notes) };
 ```javascript
 Task({
  subagent_type: "cli-explore-agent",
+  run_in_background: false,
  prompt: `
+[SPEC]
+首先读取规范文件：
+- Read: ${skillRoot}/specs/cpcc-requirements.md
+严格遵循 CPCC 软著申请规范要求。
+
 [ROLE] 系统架构师，专注于分层设计和模块依赖。

 [TASK]
@@ -113,7 +135,13 @@ graph TD
 ```javascript
 Task({
  subagent_type: "cli-explore-agent",
+  run_in_background: false,
  prompt: `
+[SPEC]
+首先读取规范文件：
+- Read: ${skillRoot}/specs/cpcc-requirements.md
+严格遵循 CPCC 软著申请规范要求。
+
 [ROLE] 功能分析师，专注于功能点识别和交互。

 [TASK]
@@ -167,7 +195,13 @@ flowchart TD
 ```javascript
 Task({
  subagent_type: "cli-explore-agent",
+  run_in_background: false,
  prompt: `
+[SPEC]
+首先读取规范文件：
+- Read: ${skillRoot}/specs/cpcc-requirements.md
+严格遵循 CPCC 软著申请规范要求。
+
 [ROLE] 算法工程师，专注于核心逻辑和复杂度分析。

 [TASK]
@@ -226,7 +260,13 @@ flowchart TD
 ```javascript
 Task({
  subagent_type: "cli-explore-agent",
+  run_in_background: false,
  prompt: `
+[SPEC]
+首先读取规范文件：
+- Read: ${skillRoot}/specs/cpcc-requirements.md
+严格遵循 CPCC 软著申请规范要求。
+
 [ROLE] 数据建模师，专注于实体关系和类型定义。

 [TASK]
@@ -280,7 +320,13 @@ classDiagram
 ```javascript
 Task({
  subagent_type: "cli-explore-agent",
+  run_in_background: false,
  prompt: `
+[SPEC]
+首先读取规范文件：
+- Read: ${skillRoot}/specs/cpcc-requirements.md
+严格遵循 CPCC 软著申请规范要求。
+
 [ROLE] API设计师，专注于接口契约和协议。

 [TASK]
@@ -343,7 +389,13 @@ sequenceDiagram
 ```javascript
 Task({
  subagent_type: "cli-explore-agent",
+  run_in_background: false,
  prompt: `
+[SPEC]
+首先读取规范文件：
+- Read: ${skillRoot}/specs/cpcc-requirements.md
+严格遵循 CPCC 软著申请规范要求。
+
 [ROLE] 可靠性工程师，专注于异常处理和恢复策略。

 [TASK]
--- a/.claude/skills/copyright-docs/phases/02.5-consolidation.md
+++ b/.claude/skills/copyright-docs/phases/02.5-consolidation.md
@@ -1,14 +1,23 @@
 # Phase 2.5: Consolidation Agent

-汇总所有分析 Agent 的产出，识别跨模块问题，生成汇总报告。
+汇总所有分析 Agent 的产出，生成设计综述，为 Phase 4 索引文档提供内容。
+
+> **规范参考**: [../specs/cpcc-requirements.md](../specs/cpcc-requirements.md)
+
+## 核心职责
+
+1. **设计综述**：生成 synthesis（软件整体设计思路）
+2. **章节摘要**：生成 section_summaries（导航表格内容）
+3. **跨模块分析**：识别问题和关联
+4. **质量检查**：验证 CPCC 合规性

 ## 输入

 ```typescript
 interface ConsolidationInput {
  output_dir: string;
-  agent_summaries: AgentReturn[];      // 6个Agent的简要返回
-  cross_module_notes: string[];        // 所有跨模块备注
+  agent_summaries: AgentReturn[];
+  cross_module_notes: string[];
  metadata: ProjectMetadata;
 }
 ```
@@ -18,74 +27,94 @@ interface ConsolidationInput {
 ```javascript
 Task({
  subagent_type: "cli-explore-agent",
+  run_in_background: false,
  prompt: `
+## 规范前置
+首先读取规范文件：
+- Read: ${skillRoot}/specs/cpcc-requirements.md
+严格遵循 CPCC 软著申请规范要求。
+
 ## 任务
-作为汇总 Agent，读取所有章节文件，执行跨模块分析，生成汇总报告。
+作为汇总 Agent，读取所有章节文件，生成设计综述和跨模块分析报告。

 ## 输入
- 章节文件: {output_dir}/sections/section-*.md
+- 章节文件: ${outputDir}/sections/section-*.md
 - Agent 摘要: ${JSON.stringify(agent_summaries)}
 - 跨模块备注: ${JSON.stringify(cross_module_notes)}
+- 软件信息: ${JSON.stringify(metadata)}

-## 分析维度
+## 核心产出

-### 1. 一致性检查
- 术语一致性：同一概念是否使用相同名称
- 命名规范：中英文命名是否统一
- 图表编号：是否连续且正确
+### 1. 设计综述 (synthesis)
+用 2-3 段落描述软件整体设计思路：
+- 第一段：软件定位与核心设计理念
+- 第二段：模块划分与协作机制
+- 第三段：技术选型与设计特点

-### 2. 完整性检查
- 功能覆盖：section-3的功能是否都有对应接口(section-6)
- 算法覆盖：section-4的算法是否在功能中被引用
- 异常覆盖：section-7的异常是否覆盖所有接口
+### 2. 章节摘要 (section_summaries)
+为每个章节提取一句话说明，用于导航表格：

-### 3. 关联性检查
- 模块依赖：架构图(section-2)的依赖是否与实际一致
- 数据流向：数据结构(section-5)是否与接口(section-6)匹配
- 跨模块调用：是否存在未记录的跨模块依赖
+| 章节 | 文件 | 一句话说明 |
+|------|------|------------|
+| 2. 系统架构设计 | section-2-architecture.md | ... |
+| 3. 功能模块设计 | section-3-functions.md | ... |
+| 4. 核心算法与流程 | section-4-algorithms.md | ... |
+| 5. 数据结构设计 | section-5-data-structures.md | ... |
+| 6. 接口设计 | section-6-interfaces.md | ... |
+| 7. 异常处理设计 | section-7-exceptions.md | ... |

-### 4. 质量检查
- 图表语法：Mermaid 语法是否正确
- 内容深度：各章节是否有足够的详细说明
- 代码引用：是否包含具体的文件路径和行号
+### 3. 跨模块分析
+- 一致性：术语、命名规范
+- 完整性：功能-接口对应、异常覆盖
+- 关联性：模块依赖、数据流向

 ## 输出文件

-写入: {output_dir}/cross-module-summary.md
+写入: ${outputDir}/cross-module-summary.md

 ### 文件格式

 \`\`\`markdown
 # 跨模块分析报告

-## 1. 文档统计
+## 设计综述

-| 章节 | 图表数 | 子章节数 | 字数 |
-|------|--------|----------|------|
-| 系统架构图 | 1 | 2 | ~500 |
-| ... | ... | ... | ... |
+[2-3 段落的软件设计思路描述]

-## 2. 发现的问题
+## 章节摘要

-### 2.1 严重问题 (必须修复)
+| 章节 | 文件 | 说明 |
+|------|------|------|
+| 2. 系统架构设计 | section-2-architecture.md | 一句话说明 |
+| ... | ... | ... |
+
+## 文档统计
+
+| 章节 | 图表数 | 字数 |
+|------|--------|------|
+| ... | ... | ... |
+
+## 发现的问题
+
+### 严重问题 (必须修复)

 | ID | 类型 | 位置 | 描述 | 建议 |
 |----|------|------|------|------|
-| E001 | 缺失 | section-6 | 缺少权限管理接口 | 补充 /api/permissions 相关接口 |
+| E001 | ... | ... | ... | ... |

-### 2.2 警告 (建议修复)
+### 警告 (建议修复)

 | ID | 类型 | 位置 | 描述 | 建议 |
 |----|------|------|------|------|
-| W001 | 一致性 | section-3/6 | 功能名"用户管理"与接口名"UserModule"不一致 | 统一使用中文或英文 |
+| W001 | ... | ... | ... | ... |

-### 2.3 提示 (可选修复)
+### 提示 (可选修复)

 | ID | 类型 | 位置 | 描述 |
 |----|------|------|------|
-| I001 | 增强 | section-4 | 建议为复杂算法添加复杂度分析 |
+| I001 | ... | ... | ... |

-## 3. 跨模块关联图
+## 跨模块关联图

 \`\`\`mermaid
 graph LR
@@ -94,21 +123,11 @@ graph LR
    S3 --> S6[接口]
    S5[数据结构] --> S6
    S6 --> S7[异常]
-
-    S3 -.->|缺少关联| S5
 \`\`\`

-## 4. 修复建议优先级
+## 修复建议优先级

-1. **E001**: 补充权限管理接口 (阻塞合规)
-2. **W001**: 统一术语命名 (影响一致性)
-3. ...
-
-## 5. 下一步行动
-
- [ ] 修复 E001-E00x 严重问题
- [ ] 处理 W001-W00x 警告
- [ ] 可选处理 I001-I00x 提示
+[按优先级排序的建议，段落式描述]
 \`\`\`

 ## 返回格式 (JSON)
@@ -116,21 +135,28 @@ graph LR
 {
  "status": "completed",
  "output_file": "cross-module-summary.md",
+
+  // Phase 4 索引文档所需
+  "synthesis": "2-3 段落的设计综述文本",
+  "section_summaries": [
+    {"file": "section-2-architecture.md", "title": "2. 系统架构设计", "summary": "一句话说明"},
+    {"file": "section-3-functions.md", "title": "3. 功能模块设计", "summary": "一句话说明"},
+    {"file": "section-4-algorithms.md", "title": "4. 核心算法与流程", "summary": "一句话说明"},
+    {"file": "section-5-data-structures.md", "title": "5. 数据结构设计", "summary": "一句话说明"},
+    {"file": "section-6-interfaces.md", "title": "6. 接口设计", "summary": "一句话说明"},
+    {"file": "section-7-exceptions.md", "title": "7. 异常处理设计", "summary": "一句话说明"}
+  ],
+
+  // 质量信息
  "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": "建议添加复杂度分析"}
-    ]
+    "errors": [...],
+    "warnings": [...],
+    "info": [...]
  },
  "cross_refs": {
    "found": 12,
@@ -151,34 +177,16 @@ graph LR

 ## 问题类型

-| 类型 | 说明 | 检查范围 |
-|------|------|----------|
-| 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);
-```
+| 类型 | 说明 |
+|------|------|
+| missing | 缺失内容（功能-接口对应、异常覆盖）|
+| inconsistency | 不一致（术语、命名、编号）|
+| circular | 循环依赖 |
+| orphan | 孤立内容（未被引用）|
+| syntax | Mermaid 语法错误 |
+| enhancement | 增强建议 |

 ## Output

- 文件: `cross-module-summary.md`
- 返回: 问题列表 + 统计信息
+- **文件**: `cross-module-summary.md`（完整汇总报告）
+- **返回**: JSON 包含 Phase 4 所需的 synthesis 和 section_summaries
--- a/.claude/skills/copyright-docs/phases/04-document-assembly.md
+++ b/.claude/skills/copyright-docs/phases/04-document-assembly.md
@@ -1,9 +1,16 @@
 # Phase 4: Document Assembly

-合并所有章节文件，生成最终 CPCC 合规文档。
+生成索引式文档，通过 markdown 链接引用章节文件。

 > **规范参考**: [../specs/cpcc-requirements.md](../specs/cpcc-requirements.md)

+## 设计原则
+
+1. **引用而非嵌入**：主文档通过链接引用章节，不复制内容
+2. **索引 + 综述**：主文档提供导航和软件概述
+3. **CPCC 合规**：保持章节编号符合软著申请要求
+4. **独立可读**：各章节文件可单独阅读
+
 ## 输入

 ```typescript
@@ -11,6 +18,12 @@ interface AssemblyInput {
  output_dir: string;
  metadata: ProjectMetadata;
  consolidation: {
+    synthesis: string;           // 跨章节综合分析
+    section_summaries: Array<{
+      file: string;
+      title: string;
+      summary: string;
+    }>;
    issues: { errors: Issue[], warnings: Issue[], info: Issue[] };
    stats: { total_sections: number, total_diagrams: number };
  };
@@ -22,8 +35,7 @@ interface AssemblyInput {
 ```javascript
 // 1. 检查是否有阻塞性问题
 if (consolidation.issues.errors.length > 0) {
-  // 阻止装配，先修复
-  return AskUserQuestion({
+  const response = await AskUserQuestion({
    questions: [{
      question: `发现 ${consolidation.issues.errors.length} 个严重问题，如何处理？`,
      header: "阻塞问题",
@@ -35,33 +47,26 @@ if (consolidation.issues.errors.length > 0) {
      ]
    }]
  });
+
+  if (response === "查看并修复") {
+    return { action: "fix_required", errors: consolidation.issues.errors };
+  }
+  if (response === "终止") {
+    return { action: "abort" };
+  }
 }

-// 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`)
-];
+// 2. 生成索引式文档（不读取章节内容）
+const doc = generateIndexDocument(metadata, consolidation);

-// 3. 读取汇总报告
-const crossModuleSummary = Read(`${outputDir}/cross-module-summary.md`);
-
-// 4. 装配文档
-const finalDoc = assembleDocument(metadata, sections, crossModuleSummary);
-
-// 5. 写入最终文件
-Write(`${outputDir}/${metadata.software_name}-软件设计说明书.md`, finalDoc);
+// 3. 写入最终文件
+Write(`${outputDir}/${metadata.software_name}-软件设计说明书.md`, doc);
 ```

-## 文档结构
+## 文档模板

 ```markdown
 <!-- 页眉：{软件名称} - 版本号：{版本号} -->
-<!-- 注：最终文档页码位于每页右上角 -->

 # {软件名称} 软件设计说明书

@@ -78,109 +83,56 @@ Write(`${outputDir}/${metadata.software_name}-软件设计说明书.md`, finalDo
 ## 1. 软件概述

 ### 1.1 软件背景与用途
-{从 metadata 生成}
+
+[从 metadata 生成的软件背景描述]

 ### 1.2 开发目标与特点
-{从 metadata 生成}
+
+[从 metadata 生成的目标和特点]

 ### 1.3 运行环境与技术架构
-{从 metadata.tech_stack 生成}
+
+[从 metadata.tech_stack 生成]

 ---

-<!-- 以下章节直接引用 Agent 产出 -->
+## 文档导航

-{section-2-architecture.md 内容}
+{consolidation.synthesis - 软件整体设计思路综述}
+
+| 章节 | 说明 | 详情 |
+|------|------|------|
+| 2. 系统架构设计 | {summary} | [查看](./sections/section-2-architecture.md) |
+| 3. 功能模块设计 | {summary} | [查看](./sections/section-3-functions.md) |
+| 4. 核心算法与流程 | {summary} | [查看](./sections/section-4-algorithms.md) |
+| 5. 数据结构设计 | {summary} | [查看](./sections/section-5-data-structures.md) |
+| 6. 接口设计 | {summary} | [查看](./sections/section-6-interfaces.md) |
+| 7. 异常处理设计 | {summary} | [查看](./sections/section-7-exceptions.md) |

 ---

-{section-3-functions.md 内容}
+## 附录

---
-
-{section-4-algorithms.md 内容}
-
---
-
-{section-5-data-structures.md 内容}
-
---
-
-{section-6-interfaces.md 内容}
-
---
-
-{section-7-exceptions.md 内容}
-
---
-
-## 附录A：跨模块分析
-
-{cross-module-summary.md 的问题列表和关联图}
-
---
-
-## 附录B：文档统计
-
-| 章节 | 图表数 | 字数 |
-|------|--------|------|
-| ... | ... | ... |
+- [跨模块分析报告](./cross-module-summary.md)
+- [章节文件目录](./sections/)

 ---

 <!-- 页脚：生成时间 {timestamp} -->
 ```

-## Section 1 生成
+## 生成函数

 ```javascript
-function generateSection1(metadata) {
-  const categoryDescriptions = {
-    "命令行工具 (CLI)": "提供命令行界面，用户通过终端命令与系统交互",
-    "后端服务/API": "提供 RESTful/GraphQL API 接口，支持前端或其他服务调用",
-    "SDK/库": "提供可复用的代码库，供其他项目集成使用",
-    "数据处理系统": "处理数据导入、转换、分析和导出",
-    "自动化脚本": "自动执行重复性任务，提高工作效率"
-  };
+function generateIndexDocument(metadata, consolidation) {
+  const date = new Date().toLocaleDateString('zh-CN');

-  return `
-## 1. 软件概述
+  // 章节导航表格
+  const sectionTable = consolidation.section_summaries
+    .map(s => `| ${s.title} | ${s.summary} | [查看](./sections/${s.file}) |`)
+    .join('\n');

-### 1.1 软件背景与用途
-
-${metadata.software_name}是一款${metadata.category}软件。${categoryDescriptions[metadata.category]}
-
-本软件基于${metadata.tech_stack.language}语言开发，运行于${metadata.tech_stack.runtime}环境，采用${metadata.tech_stack.framework || '原生'}框架实现核心功能。
-
-### 1.2 开发目标与特点
-
-**开发目标**：
-${generateObjectives(metadata)}
-
-**技术特点**：
-${generateFeatures(metadata)}
-
-### 1.3 运行环境与技术架构
-
-**运行环境**：
- 操作系统：${metadata.os || 'Windows/Linux/macOS'}
- 运行时：${metadata.tech_stack.runtime}
- 依赖环境：${metadata.tech_stack.dependencies?.join(', ') || '无'}
-
-**技术架构**：
- 架构模式：${metadata.architecture_pattern || '分层架构'}
- 核心框架：${metadata.tech_stack.framework || '原生实现'}
- 主要模块：${metadata.main_modules?.join(', ') || '见第2章'}
-`;
-}
-```
-
-## 装配函数
-
-```javascript
-function assembleDocument(metadata, sections, crossModuleSummary) {
-  const header = `<!-- 页眉：${metadata.software_name} - 版本号：${metadata.version} -->
-<!-- 注：最终文档页码位于每页右上角 -->
+  return `<!-- 页眉：${metadata.software_name} - 版本号：${metadata.version} -->

 # ${metadata.software_name} 软件设计说明书

@@ -190,87 +142,120 @@ function assembleDocument(metadata, sections, crossModuleSummary) {
 |------|------|
 | 软件名称 | ${metadata.software_name} |
 | 版本号 | ${metadata.version} |
-| 生成日期 | ${new Date().toLocaleDateString('zh-CN')} |
+| 生成日期 | ${date} |

 ---

-`;
+## 1. 软件概述

-  const section1 = generateSection1(metadata);
+### 1.1 软件背景与用途

-  // 合并章节 (sections 已经是完整的 MD 内容)
-  const mainContent = sections.join('\n\n---\n\n');
+${generateBackground(metadata)}

-  // 提取跨模块问题作为附录
-  const appendixA = extractAppendixA(crossModuleSummary);
+### 1.2 开发目标与特点

-  // 生成统计
-  const appendixB = generateStats(sections);
+${generateObjectives(metadata)}
+
+### 1.3 运行环境与技术架构
+
+${generateTechStack(metadata)}
+
+---
+
+## 设计综述
+
+${consolidation.synthesis}
+
+---
+
+## 文档导航
+
+| 章节 | 说明 | 详情 |
+|------|------|------|
+${sectionTable}
+
+---
+
+## 附录
+
+- [跨模块分析报告](./cross-module-summary.md)
+- [章节文件目录](./sections/)

-  const footer = `
 ---

 <!-- 页脚：生成时间 ${new Date().toISOString()} -->
 `;
+}

-  return header + section1 + '\n\n---\n\n' + mainContent + '\n\n' + appendixA + '\n\n' + appendixB + footer;
+function generateBackground(metadata) {
+  const categoryDescriptions = {
+    "命令行工具 (CLI)": "提供命令行界面，用户通过终端命令与系统交互",
+    "后端服务/API": "提供 RESTful/GraphQL API 接口，支持前端或其他服务调用",
+    "SDK/库": "提供可复用的代码库，供其他项目集成使用",
+    "数据处理系统": "处理数据导入、转换、分析和导出",
+    "自动化脚本": "自动执行重复性任务，提高工作效率"
+  };
+
+  return `${metadata.software_name}是一款${metadata.category}软件。${categoryDescriptions[metadata.category] || ''}
+
+本软件基于${metadata.tech_stack.language}语言开发，运行于${metadata.tech_stack.runtime}环境，采用${metadata.tech_stack.framework || '原生'}框架实现核心功能。`;
+}
+
+function generateObjectives(metadata) {
+  return `本软件旨在${metadata.purpose || '解决特定领域的技术问题'}。
+
+主要技术特点包括${metadata.tech_stack.framework ? `采用 ${metadata.tech_stack.framework} 框架` : '模块化设计'}，具备良好的可扩展性和可维护性。`;
+}
+
+function generateTechStack(metadata) {
+  return `**运行环境**
+
+- 操作系统：${metadata.os || 'Windows/Linux/macOS'}
+- 运行时：${metadata.tech_stack.runtime}
+- 依赖环境：${metadata.tech_stack.dependencies?.join(', ') || '无特殊依赖'}
+
+**技术架构**
+
+- 架构模式：${metadata.architecture_pattern || '分层架构'}
+- 核心框架：${metadata.tech_stack.framework || '原生实现'}
+- 主要模块：详见第2章系统架构设计`;
 }
 ```

-## 附录生成
+## 输出结构

-### 附录A：跨模块分析
+```
+.workflow/.scratchpad/copyright-{timestamp}/
+├── sections/                           # 独立章节（Phase 2 产出）
+│   ├── section-2-architecture.md
+│   ├── section-3-functions.md
+│   └── ...
+├── cross-module-summary.md             # 跨模块报告（Phase 2.5 产出）
+└── {软件名称}-软件设计说明书.md         # 索引文档（本阶段产出）
+```

-```javascript
-function extractAppendixA(crossModuleSummary) {
-  // 从 cross-module-summary.md 提取关键内容
-  return `
-## 附录A：跨模块分析
+## 与 Phase 2.5 的协作

-本附录汇总了文档生成过程中发现的跨模块问题和关联关系。
+Phase 2.5 consolidation agent 需要提供：

-${extractSection(crossModuleSummary, '## 2. 发现的问题')}
-
-${extractSection(crossModuleSummary, '## 3. 跨模块关联图')}
-`;
+```typescript
+interface ConsolidationOutput {
+  synthesis: string;           // 设计思路综述（2-3 段落）
+  section_summaries: Array<{
+    file: string;              // 文件名
+    title: string;             // 章节标题（如"2. 系统架构设计"）
+    summary: string;           // 一句话说明
+  }>;
+  issues: {...};
+  stats: {...};
 }
 ```

-### 附录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`
- 保留原始章节文件供追溯
+| 原设计 | 新设计 |
+|--------|--------|
+| 读取章节内容并拼接 | 链接引用，不读取内容 |
+| 嵌入完整章节 | 仅提供导航索引 |
+| 重复生成统计 | 引用 cross-module-summary.md |
+| 大文件 | 精简索引文档 |