# C/C++2Rust 转译规则

## 规则简介

用于指导 C/C++ 到 Rust 的代码转译过程，确保转译质量、功能一致性和类型安全。本规则涵盖从规划、实现、构建、审查、优化到评估的完整转译流程。

⚠️ **重要提醒**：C/C++ 到 Rust 转译是一项非常复杂的任务，必须保证每个指定接口的功能一致性，任何疏忽都可能导致严重的功能错误。

**支持的语言特性：**
- **C 语言**：函数、结构体、联合体、枚举、指针、数组等
- **C++ 语言**：类、模板、命名空间、STL容器、智能指针、继承、多态、运算符重载等

## 你必须遵守的原则

### 1. 任务管理原则（核心）

**要求说明：**

- **必须**：每个函数的转译过程都必须使用 `task_list_manager` 进行任务管理
- **必须**：在开始转译前创建任务列表，规划所有任务（规划、实现、构建、审查、优化、评估）
- **必须**：使用 task_list_manager 的 `add_tasks` 操作添加所有子任务
- **必须**：按照依赖关系设置任务依赖（如：实现阶段依赖规划阶段）
- **禁止**：跳过 task_list_manager，直接执行任务

**多层级任务列表要求：**

C/C++ 到 Rust 转译是一个复杂的流程，需要根据转译规模建立不同层级的任务列表：

1. **目录级任务列表**（按需）
   - **何时需要**：转译整个目录或多个相关目录时
   - **任务内容**：规划目录结构、模块组织、依赖关系等
   - **子任务**：包含该目录下所有文件的转译任务
   - **示例场景**：转译 `src/utils/` 目录下的所有 C/C++ 文件（`.c`, `.cpp`, `.h`, `.hpp`）

2. **文件级任务列表**（按需）
   - **何时需要**：转译单个文件或多个相关函数/类时
   - **任务内容**：规划文件模块位置、函数/类分组、共享类型定义等
   - **子任务**：包含该文件中所有函数/类的转译任务
   - **示例场景**：
     - C：转译 `hash.c` 文件中的所有哈希相关函数
     - C++：转译 `vector.hpp` 文件中的 `Vector` 类及其成员函数

3. **函数/类级任务列表**（必须）
   - **何时需要**：转译单个函数或类时（这是最小粒度，必须创建）
   - **任务内容**：规划函数/类签名、实现策略、测试用例等
   - **子任务**：包含该函数/类的规划、实现、构建、审查、优化、评估阶段
   - **示例场景**：
     - C：转译单个函数 `calculate_hash`
     - C++：转译单个类 `String` 及其所有成员函数

**任务列表层级关系：**

- 目录级任务列表 → 文件级任务列表 → 函数级任务列表
- 上级任务列表的子任务可以是下级任务列表
- 如果只转译单个函数，只需创建函数级任务列表
- 如果转译多个函数但属于同一文件，可以创建文件级任务列表，包含多个函数级子任务
- 如果转译多个文件，可以创建目录级任务列表，包含多个文件级子任务

**任务列表要求：**

- 任务类型：复杂任务使用 `sub` 类型，简单任务使用 `main` 类型
- 任务描述：每个任务必须包含约束条件、必须要求、禁止事项、验证标准
- 预期输出：必须使用结构化格式列出预期输出
- 验证方法：任务完成后必须提供验证方法说明
- **C/C++ 代码位置信息**：**必须**在每个子任务中包含原始 C/C++ 代码的行号位置信息
  - 函数/类级任务：必须包含 C/C++ 函数/类所在的文件路径和行号范围
    - C：`path/to/file.c:42-67` 或 `path/to/file.h:10-25`
    - C++：`path/to/file.cpp:42-67` 或 `path/to/file.hpp:10-25`
  - 文件级任务：必须包含 C/C++ 文件的路径（`.c`, `.cpp`, `.h`, `.hpp`）
  - 目录级任务：必须包含 C/C++ 目录的路径
  - 位置信息应包含在 `background` 字段或 `task_desc` 字段中

**示例：**

**示例1：函数级任务列表（必须）**

```json
// ✅ 正确：函数级任务列表（包含C/C++代码行号位置信息）
{
  "action": "add_tasks",
  "main_goal": "转译函数 foo",
  "background": "C 函数 foo 位于 path/to/foo.c:42-67，功能是...",
  "tasks_info": [
    {
      "task_name": "规划阶段",
      "task_desc": "为函数 foo (path/to/foo.c:42-67) 选择模块位置和设计 Rust 签名...",
      "expected_output": "- 模块路径：src/foo.rs\n- Rust 签名：pub fn foo(...) ...\n- C/C++ 代码位置：path/to/foo.c:42-67\n- 规划文档：docs/transpilation/foo_planning.md",
      "agent_type": "sub",
      "dependencies": []
    },
    {
      "task_name": "实现阶段",
      "task_desc": "使用 TDD 方法实现函数 foo (path/to/foo.c:42-67)...",
      "expected_output": "- 测试用例已编写\n- 实现已完成\n- C/C++ 代码位置：path/to/foo.c:42-67\n- 实现文档：docs/transpilation/foo_implementation.md",
      "agent_type": "sub",
      "dependencies": ["规划阶段"]
    },
    {
      "task_name": "构建阶段",
      "task_desc": "运行 cargo test 并修复构建问题（转译自 path/to/foo.c:42-67）...",
      "expected_output": "- 所有测试通过\n- 无编译错误\n- C/C++ 代码位置：path/to/foo.c:42-67\n- 构建文档：docs/transpilation/foo_build.md",
      "agent_type": "sub",
      "dependencies": ["实现阶段"]
    },
    {
      "task_name": "审查阶段",
      "task_desc": "审查代码质量、功能一致性、测试完备性（转译自 path/to/foo.c:42-67）...",
      "expected_output": "- 审查报告\n- 问题列表\n- C/C++ 代码位置：path/to/foo.c:42-67\n- 审查文档：docs/transpilation/foo_review.md",
      "agent_type": "sub",
      "dependencies": ["构建阶段"]
    },
    {
      "task_name": "优化阶段",
      "task_desc": "修复审查发现的问题并验证（转译自 path/to/foo.c:42-67）...",
      "expected_output": "- 问题已修复\n- 所有测试通过\n- C/C++ 代码位置：path/to/foo.c:42-67\n- 优化文档：docs/transpilation/foo_optimization.md",
      "agent_type": "sub",
      "dependencies": ["审查阶段"]
    },
    {
      "task_name": "评估阶段",
      "task_desc": "使用子agent对整体效果进行评估，检查功能对齐情况（转译自 path/to/foo.c:42-67）...",
      "expected_output": "- 评估报告\n- 功能对齐检查结果\n- 如有问题，创建优化子任务\n- C/C++ 代码位置：path/to/foo.c:42-67\n- 评估文档：docs/transpilation/foo_evaluation.md",
      "agent_type": "sub",
      "dependencies": ["优化阶段"]
    }
  ]
}
```

**示例2：文件级任务列表（按需）**

```json
// ✅ 正确：文件级任务列表（转译 hash.c/hash.cpp 文件，包含C/C++代码行号位置信息）
{
  "action": "add_tasks",
  "main_goal": "转译文件 hash.c",
  "background": "C 文件 hash.c 包含多个哈希相关函数：hash_init (hash.c:15-45), hash_update (hash.c:47-78), hash_final (hash.c:80-110)...",
  "tasks_info": [
    {
      "task_name": "规划阶段",
      "task_desc": "规划 hash.c 的模块位置和整体结构...",
      "expected_output": "- 模块路径：src/hash.rs\n- 共享类型定义\n- 函数分组方案\n- C/C++ 文件位置：hash.c",
      "agent_type": "sub",
      "dependencies": []
    },
    {
      "task_name": "转译函数 hash_init",
      "task_desc": "转译函数 hash_init (hash.c:15-45)（包含规划、实现、构建、审查、优化、评估）...",
      "expected_output": "- hash_init 函数已转译完成\n- 测试通过\n- 功能对齐验证通过\n- C/C++ 代码位置：hash.c:15-45",
      "agent_type": "sub",
      "dependencies": ["规划阶段"]
    },
    {
      "task_name": "转译函数 hash_update",
      "task_desc": "转译函数 hash_update (hash.c:47-78)（包含规划、实现、构建、审查、优化、评估）...",
      "expected_output": "- hash_update 函数已转译完成\n- 测试通过\n- 功能对齐验证通过\n- C/C++ 代码位置：hash.c:47-78",
      "agent_type": "sub",
      "dependencies": ["规划阶段"]
    },
    {
      "task_name": "转译函数 hash_final",
      "task_desc": "转译函数 hash_final (hash.c:80-110)（包含规划、实现、构建、审查、优化、评估）...",
      "expected_output": "- hash_final 函数已转译完成\n- 测试通过\n- 功能对齐验证通过\n- C/C++ 代码位置：hash.c:80-110",
      "agent_type": "sub",
      "dependencies": ["规划阶段"]
    },
    {
      "task_name": "文件级集成测试",
      "task_desc": "运行文件级集成测试，确保所有函数协同工作（转译自 hash.c）...",
      "expected_output": "- 集成测试通过\n- 文件转译完成\n- C/C++ 文件位置：hash.c",
      "agent_type": "sub",
      "dependencies": ["转译函数 hash_init", "转译函数 hash_update", "转译函数 hash_final"]
    }
  ]
}
```

**示例3：目录级任务列表（按需）**

```json
// ✅ 正确：目录级任务列表（转译 src/utils/ 目录，包含C/C++代码行号位置信息）
{
  "action": "add_tasks",
  "main_goal": "转译目录 src/utils/",
  "background": "C/C++ 目录 src/utils/ 包含多个工具文件：string.c, math.cpp, memory.hpp...",
  "tasks_info": [
    {
      "task_name": "规划阶段",
      "task_desc": "规划目录结构、模块组织、依赖关系（转译自 src/utils/）...",
      "expected_output": "- Rust 模块结构规划\n- 依赖关系图\n- 转译顺序\n- C/C++ 目录位置：src/utils/",
      "agent_type": "sub",
      "dependencies": []
    },
    {
      "task_name": "转译文件 string.c",
      "task_desc": "转译 string.c 文件（包含该文件的所有函数，位于 src/utils/string.c）...",
      "expected_output": "- string.c 已转译完成\n- 所有函数测试通过\n- 功能对齐验证通过\n- C/C++ 文件位置：src/utils/string.c",
      "agent_type": "sub",
      "dependencies": ["规划阶段"]
    },
    {
      "task_name": "转译文件 math.cpp",
      "task_desc": "转译 math.cpp 文件（包含该文件的所有类和函数，位于 src/utils/math.cpp）...",
      "expected_output": "- math.cpp 已转译完成\n- 所有类和函数测试通过\n- 功能对齐验证通过\n- C/C++ 文件位置：src/utils/math.cpp",
      "agent_type": "sub",
      "dependencies": ["规划阶段"]
    },
    {
      "task_name": "转译文件 memory.hpp",
      "task_desc": "转译 memory.hpp 文件（包含该文件的所有类和模板，位于 src/utils/memory.hpp）...",
      "expected_output": "- memory.hpp 已转译完成\n- 所有类和模板测试通过\n- 功能对齐验证通过\n- C/C++ 文件位置：src/utils/memory.hpp",
      "agent_type": "sub",
      "dependencies": ["规划阶段"]
    },
    {
      "task_name": "目录级集成测试",
      "task_desc": "运行目录级集成测试，确保所有模块协同工作（转译自 src/utils/）...",
      "expected_output": "- 集成测试通过\n- 目录转译完成\n- C/C++ 目录位置：src/utils/",
      "agent_type": "sub",
      "dependencies": ["转译文件 string.c", "转译文件 math.c", "转译文件 memory.c"]
    }
  ]
}
```

```bash
# ❌ 错误：直接执行，未使用 task_list_manager
echo "开始转译函数 foo"
# 直接编写代码，没有任务管理
```

### 2. TDD 开发原则

**要求说明：**

- **必须**：先写测试（#[cfg(test)] mod tests），基于 C/C++ 函数/类行为设计测试用例
- **必须**：编写实现使测试通过，确保与 C/C++ 语义等价
- **必须**：优化代码，保持测试通过（重构阶段）
- **禁止**：在没有测试的情况下直接编写实现代码
- **禁止**：使用 `todo!` 或 `unimplemented!` 作为占位符

**C++ 特有考虑：**
- 类的成员函数需要分别测试公共接口和私有实现（通过公共接口）
- 模板函数/类需要测试不同的模板参数实例化
- 继承和多态需要测试基类和派生类的行为
- 运算符重载需要测试所有重载的运算符

**示例：**

```rust
// ❌ 错误：先写实现
pub fn calculate(x: i32) -> i32 {
    x * 2
}

#[cfg(test)]
mod tests {
    #[test]
    fn test_calculate() { }
}
```

```rust
// ✅ 正确：先写测试
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_calculate_normal() {
        assert_eq!(calculate(5), 10);
    }

    #[test]
    fn test_calculate_zero() {
        assert_eq!(calculate(0), 0);
    }
}

pub fn calculate(x: i32) -> i32 {
    x * 2
}
```

### 3. 功能一致性原则

**要求说明：**

- **必须**：核心功能定义与 C/C++ 实现一致（主要目的和预期行为）
- **允许**：安全改进导致的行为不一致（修复缓冲区溢出、空指针解引用等安全漏洞）
- **忽略**：语言差异导致的行为不一致（整数溢出处理、未定义行为处理等）
- **允许**：使用不同的类型设计、错误处理方式、资源管理方式
- **禁止**：改变核心功能逻辑

**说明：** 核心功能指函数/类的主要目的（如"计算哈希值"、"解析字符串"、"管理动态数组"），不包括实现细节。

**C++ 特有考虑：**
- 类的封装性：保持公共接口一致，内部实现可以不同
- 继承关系：保持继承层次和虚函数行为一致
- 模板实例化：确保模板在不同类型参数下的行为一致
- STL 容器：可以使用 Rust 标准库的等价容器（如 `Vec` 对应 `std::vector`）
- 智能指针：可以使用 Rust 的所有权系统（`Box`, `Rc`, `Arc`）替代

### 4. 模块化设计原则

**要求说明：**

- **必须**：按功能内聚与依赖方向选择模块，避免循环依赖
- **必须**：模块路径必须位于 crate 的 src/ 目录下
- **必须**：优先将函数放置到已存在的模块中
- **允许**：必要时创建新的子模块文件
- **禁止**：将不相关的功能放在同一模块

### 5. 类型安全原则

**要求说明：**

- **必须**：优先使用 Rust 原生类型（i32/u32、&str/String、&[T]/&mut [T]、Result<T,E>）
- **禁止**：优先使用 C 风格类型（core::ffi::c*\*、libc::c*\*）
- **禁止**：使用 extern "C"（除非是 FFI 导出要求）
- **必须**：函数签名应遵循 Rust 最佳实践，不需要兼容 C 的数据类型
- **禁止**：使用 `use ...::*` 通配导入

### 6. 文档记录原则

**要求说明：**

- **必须**：每个转译阶段都必须生成文档记录
- **必须**：文档记录应包含阶段执行过程、决策依据、遇到的问题和解决方案
- **必须**：文档记录应包含 C 代码位置信息，便于追溯
- **必须**：文档记录应使用结构化格式（Markdown），便于阅读和维护
- **必须**：文档记录应在阶段完成后立即生成，确保信息准确完整
- **禁止**：跳过文档记录，直接进入下一阶段

**文档记录要求：**

- 文档格式：使用 Markdown 格式
- 文档位置：建议保存在 `docs/transpilation/` 目录下，按函数/文件/目录组织
- 文档命名：使用清晰的命名规则（如：`function_name_planning.md`、`file_name_implementation.md`）
- 文档内容：必须包含阶段概述、执行过程、关键决策、问题与解决方案、验证结果
- 文档链接：在任务列表的预期输出中包含文档路径

## 你必须执行的操作

**重要提示：** 在开始转译前，必须根据转译规模选择合适的任务列表层级：

- **转译单个函数**：创建函数级任务列表（必须）
- **转译单个文件或多个相关函数**：创建文件级任务列表，包含多个函数级子任务（按需）
- **转译整个目录或多个相关目录**：创建目录级任务列表，包含多个文件级子任务（按需）

以下操作阶段适用于所有层级的任务列表，但具体执行粒度取决于任务列表层级。

### 阶段 1：规划阶段

#### 操作1：记录 C/C++ 代码位置信息

- **必须**：记录原始 C/C++ 代码的位置信息
  - 函数/类级：记录 C/C++ 函数/类所在的文件路径和行号范围
    - C：`path/to/file.c:42-67` 或 `path/to/file.h:10-25`
    - C++：`path/to/file.cpp:42-67` 或 `path/to/file.hpp:10-25`
  - 文件级：记录 C/C++ 文件的完整路径（`.c`, `.cpp`, `.h`, `.hpp`）
  - 目录级：记录 C/C++ 目录的路径（如：`path/to/dir/`）
- **必须**：将位置信息包含在任务描述、背景信息或预期输出中
- **必须**：确保位置信息准确，便于后续追溯和验证
- **C++ 特有**：对于模板类/函数，需要记录所有实例化的位置

#### 操作2：选择模块位置

- 分析函数的功能特性，确定所属的功能模块
- 检查 crate 目录结构，选择或创建合适的模块文件
- 确保模块路径位于 src/ 目录下
- 评估是否需要创建新的子模块文件

#### 操作3：设计 Rust 函数/结构体/特征签名

- 根据 C/C++ 函数/类签名设计 Rust 函数/结构体/特征签名
- 优先使用 Rust 原生类型，避免 C/C++ 风格类型
- 考虑使用 `Result<T, E>` 或 `Option<T>` 处理错误
- 如果是根符号，必须使用 `pub` 关键字
- **必须**：在函数/结构体注释中记录对应的 C/C++ 代码位置信息（如：`/// 转译自 path/to/file.c:42-67`）

**C++ 特有处理：**
- **类转结构体**：C++ 类转换为 Rust 结构体，成员函数转换为关联函数或方法
- **继承转特征**：C++ 继承关系转换为 Rust 特征（trait）和实现（impl）
- **模板转泛型**：C++ 模板转换为 Rust 泛型（`<T>`）
- **命名空间转模块**：C++ 命名空间转换为 Rust 模块
- **STL 容器映射**：
  - `std::vector<T>` → `Vec<T>`
  - `std::string` → `String` 或 `&str`
  - `std::map<K, V>` → `std::collections::HashMap<K, V>`
  - `std::unique_ptr<T>` → `Box<T>`
  - `std::shared_ptr<T>` → `Rc<T>` 或 `Arc<T>`
- **运算符重载**：使用 Rust 的运算符特征（如 `Add`, `Sub`, `Deref` 等）

#### 操作4：评估是否需要实现

以下情况可以跳过实现（设置 skip_implementation 为 true）：

- **已实现的函数/类**：函数/类已经在目标模块中实现，且功能与 C/C++ 实现一致
- **资源释放类函数**：如 fclose、free、delete 等，通过 RAII 自动管理
- **已被库替代**：函数/类已被标准库或第三方 crate 替代，且功能完全一致
- **空实现或无意义函数**：C/C++ 函数是空实现、简单返回常量
- **内联函数或宏**：在 C/C++ 中是内联函数或宏
- **C++ 特有**：
  - 纯虚函数（如果 Rust 特征已定义）
  - 默认构造函数/析构函数（Rust 自动处理）
  - 某些 STL 容器的简单包装（可直接使用 Rust 标准库）

**重要**：跳过实现必须在 notes 字段中详细说明原因。

#### 操作5：生成规划阶段文档

- **必须**：生成规划阶段文档记录
- **必须**：文档包含以下内容：
  - C 代码位置信息（文件路径和行号范围）
  - 模块选择决策和理由
  - Rust 函数签名设计说明
  - 实现必要性评估结果
  - 关键设计决策和考虑因素
- **必须**：文档保存到指定位置（如：`docs/transpilation/<function_name>_planning.md`）
- **必须**：在任务预期输出中包含文档路径

### 阶段 2：实现阶段

#### 操作1：编写测试用例

- 在 `#[cfg(test)] mod tests { ... }` 块中编写测试
- 测试用例必须覆盖：
  - 主要功能路径
  - 边界情况（空输入、极值、边界值）
  - 错误情况（如果 C/C++ 实现有错误处理）
- 测试用例的预期结果必须与 C/C++ 实现的行为一致
- 使用清晰的测试名称和适当的断言

**C++ 特有测试要求：**
- **类测试**：测试所有公共方法，包括构造函数、析构函数、运算符重载
- **继承测试**：测试基类和派生类的方法，包括虚函数的多态行为
- **模板测试**：测试模板在不同类型参数下的行为（如 `Vec<i32>`, `Vec<String>`）
- **异常处理**：C++ 异常转换为 Rust 的 `Result` 或 `panic`，需要相应测试
- **移动语义**：测试移动构造函数和移动赋值运算符的等价行为

#### 操作2：实现函数/结构体/特征

- 使测试通过，实现与 C/C++ 语义等价的功能
- 使用 Rust 原生类型和惯用法
- 考虑使用 RAII 管理资源
- 添加中文注释说明逻辑

**C++ 特有实现要求：**
- **类实现**：将 C++ 类转换为 Rust 结构体，成员变量作为字段，成员函数作为方法
- **构造函数**：使用 `new()` 或 `Default` 特征实现
- **析构函数**：使用 `Drop` 特征实现
- **继承**：使用特征和实现（`impl Trait for Struct`）模拟继承
- **多态**：使用特征对象（`Box<dyn Trait>`）实现运行时多态
- **模板泛型**：使用 Rust 泛型实现，考虑使用特征约束（`where T: Trait`）
- **运算符重载**：实现相应的运算符特征（如 `Add`, `Sub`, `Mul`, `Deref` 等）
- **智能指针**：
  - `std::unique_ptr<T>` → `Box<T>`
  - `std::shared_ptr<T>` → `Rc<T>`（单线程）或 `Arc<T>`（多线程）
  - `std::weak_ptr<T>` → `Weak<T>`

#### 操作3：重构代码

- 优化代码结构，保持测试通过
- 改进代码可读性和可维护性
- 确保不改变功能行为

#### 操作4：生成实现阶段文档

- **必须**：生成实现阶段文档记录
- **必须**：文档包含以下内容：
  - C 代码位置信息（文件路径和行号范围）
  - 测试用例设计说明和覆盖情况
  - 实现策略和关键实现细节
  - 遇到的实现难点和解决方案
  - 重构说明和改进点
  - 代码变更摘要
- **必须**：文档保存到指定位置（如：`docs/transpilation/<function_name>_implementation.md`）
- **必须**：在任务预期输出中包含文档路径

### 阶段 3：构建阶段

#### 操作1：运行 cargo test

- 确保所有测试用例都能通过
- 修复编译错误和测试失败
- 如果修复过程中导致其他测试失败，必须一并修复

#### 操作2：修复构建问题

- 处理编译错误（类型不匹配、缺少依赖等）
- 处理测试失败（断言错误、panic 等）
- 最小化修改，避免无关重构
- 使用精确的 use 语句，禁止通配导入

#### 操作3：生成构建阶段文档

- **必须**：生成构建阶段文档记录
- **必须**：文档包含以下内容：
  - C 代码位置信息（文件路径和行号范围）
  - 构建过程记录（编译命令、测试命令）
  - 遇到的构建问题和错误信息
  - 问题分析和解决方案
  - 修复后的验证结果
  - 构建时间统计（如适用）
- **必须**：文档保存到指定位置（如：`docs/transpilation/<function_name>_build.md`）
- **必须**：在任务预期输出中包含文档路径

### 阶段 4：审查阶段

**审查优先级：**

1. **测试破坏性检查**（最高优先级）
   - 检查 `#[test]` 标记是否丢失
   - 检查 `#[test]` 标记是否重复
   - 检查代码插入位置是否破坏测试结构
   - 验证测试仍然可以运行

2. **严重问题检查**
   - 空指针解引用风险
   - 越界访问问题
   - 会导致 panic 的严重错误

3. **测试用例完备性检查**
   - 是否有测试用例
   - 是否覆盖主要功能
   - 是否覆盖边界情况
   - 是否覆盖错误情况

4. **功能一致性检查**
   - 核心输入输出是否一致
   - 主要功能逻辑是否一致
   - 允许安全改进导致的行为不一致
   - **C++ 特有**：
     - 类的公共接口是否一致
     - 继承关系是否正确转换
     - 模板实例化行为是否一致
     - 运算符重载行为是否一致

5. **破坏性变更检测**
   - 检查模块导出变更
   - 检查类型定义变更
   - 允许签名不一致（只要功能实现）

6. **文件结构合理性检查**
   - 模块文件位置是否合理
   - 文件命名是否符合规范
   - 模块导出是否正确

**操作：** 根据审查结果，提供详细的问题描述、修复建议和修复代码示例。

#### 操作：生成审查阶段文档

- **必须**：生成审查阶段文档记录
- **必须**：文档包含以下内容：
  - C 代码位置信息（文件路径和行号范围）
  - 审查范围和方法
  - 审查结果摘要（按优先级分类）
  - 发现的问题列表（详细描述、严重程度、影响范围）
  - 修复建议和代码示例
  - 审查结论和改进方向
- **必须**：文档保存到指定位置（如：`docs/transpilation/<function_name>_review.md`）
- **必须**：在任务预期输出中包含文档路径

### 阶段 5：优化阶段

#### 操作1：修复审查发现的问题

- 按优先级修复问题（严重问题 > 功能一致性问题 > 其他问题）
- 最小化修改，避免无关重构
- 修复后必须重新运行 cargo test 验证

#### 操作2：验证所有测试通过

- 确保当前函数的测试通过
- 确保其他函数的测试没有因修改而失败
- 如果引入回归问题，必须一并修复

#### 操作3：生成优化阶段文档

- **必须**：生成优化阶段文档记录
- **必须**：文档包含以下内容：
  - C 代码位置信息（文件路径和行号范围）
  - 优化的问题列表和优先级
  - 每个问题的修复方案和执行过程
  - 修复后的验证结果
  - 回归测试结果
  - 优化效果总结
- **必须**：文档保存到指定位置（如：`docs/transpilation/<function_name>_optimization.md`）
- **必须**：在任务预期输出中包含文档路径

### 阶段 6：评估阶段

**重要说明：** 评估阶段必须使用子 agent 进行独立评估，确保客观性和全面性。

#### 操作1：使用子 agent 进行整体效果评估

- **必须**：使用子 agent（`agent_type: "sub"`）对转译结果进行独立评估
- **必须**：评估范围包括：
  - 功能对齐检查：对比 C/C++ 实现和 Rust 实现的核心功能是否一致
  - 测试覆盖检查：测试用例是否充分覆盖 C/C++ 函数/类的行为
  - 边界情况检查：边界条件和错误处理是否与 C/C++ 实现一致
  - 性能影响评估：Rust 实现的性能是否满足要求（如适用）
  - 代码质量评估：代码可读性、可维护性、类型安全性
  - **C++ 特有**：
    - 类的封装性是否保持
    - 继承和多态行为是否一致
    - 模板实例化的行为是否一致
    - 运算符重载是否完整
    - 异常处理是否正确转换
- **必须**：生成详细的评估报告，包含：
  - 评估范围和方法
  - 功能对齐检查结果（逐项对比）
  - 发现的问题列表（如有）
  - 改进建议（如有）
- **必须**：将评估报告保存为文档（如：`docs/transpilation/<function_name>_evaluation.md`）
- **必须**：在任务预期输出中包含文档路径

#### 操作2：处理功能未对齐问题

- **必须**：如果评估发现功能未对齐问题，必须创建优化子任务
- **必须**：优化子任务应包含：
  - 问题描述：详细说明功能未对齐的具体表现
  - 对齐目标：明确需要对齐的功能点
  - 修复计划：制定修复方案和验证方法
  - 依赖关系：依赖评估阶段
- **必须**：执行优化子任务，修复功能对齐问题
- **必须**：修复后重新进行评估，直到功能完全对齐

#### 操作3：迭代优化直到完全对齐

- **必须**：如果重新评估仍发现功能未对齐，继续创建优化子任务
- **必须**：重复"优化 → 评估"循环，直到：
  - 所有功能对齐检查通过
  - 评估报告确认功能完全对齐
  - 所有测试用例通过
- **禁止**：在功能未完全对齐的情况下结束转译任务

**评估报告模板：**

```markdown
## 转译评估报告

### 评估范围
- 转译对象：[函数名/类名/文件名/目录名]
- C/C++ 代码位置：[文件路径:行号范围]（如：path/to/file.c:42-67 或 path/to/file.cpp:42-67）
- 评估时间：[时间戳]
- 评估方法：[使用的评估方法]

### 功能对齐检查结果
1. [功能点1]：✅ 对齐 / ❌ 未对齐
   - C/C++ 实现位置：[文件路径:行号范围]
   - C/C++ 实现行为：[描述]
   - Rust 实现位置：[文件路径:行号范围]
   - Rust 实现行为：[描述]
   - 差异分析：[如有差异，说明原因]

2. [功能点2]：✅ 对齐 / ❌ 未对齐
   - C/C++ 实现位置：[文件路径:行号范围]
   ...

### 测试覆盖检查
- 主要功能路径：✅ 已覆盖 / ❌ 未覆盖
- 边界情况：✅ 已覆盖 / ❌ 未覆盖
- 错误情况：✅ 已覆盖 / ❌ 未覆盖
- **C++ 特有**：
  - 类的所有公共方法：✅ 已覆盖 / ❌ 未覆盖
  - 继承和多态：✅ 已覆盖 / ❌ 未覆盖
  - 模板实例化：✅ 已覆盖 / ❌ 未覆盖
  - 运算符重载：✅ 已覆盖 / ❌ 未覆盖

### 发现的问题
1. [问题1]：[详细描述]
2. [问题2]：[详细描述]
...

### 改进建议
1. [建议1]：[详细说明]
2. [建议2]：[详细说明]
...

### 结论
- 功能对齐状态：✅ 完全对齐 / ❌ 部分对齐 / ❌ 未对齐
- 是否需要优化：是 / 否
- 下一步行动：[具体行动]
```

**阶段文档模板：**

每个阶段的文档应遵循以下基本结构：

```markdown
# [阶段名称]文档 - [函数名/文件名/目录名]

## 基本信息
- C/C++ 代码位置：[文件路径:行号范围]（如：path/to/file.c:42-67 或 path/to/file.cpp:42-67）
- 转译对象：[函数名/类名/文件名/目录名]
- 阶段：[规划/实现/构建/审查/优化/评估]
- 执行时间：[时间戳]
- 执行人员：[agent名称]

## 阶段概述
[简要描述本阶段的目标和主要工作]

## 执行过程
[详细记录执行步骤和过程]

## 关键决策
1. [决策1]：[决策内容和理由]
2. [决策2]：[决策内容和理由]
...

## 问题与解决方案
1. [问题1]：[问题描述]
   - 解决方案：[解决方案]
   - 结果：[解决结果]
2. [问题2]：[问题描述]
   ...

## 验证结果
- [验证项1]：✅ 通过 / ❌ 失败
- [验证项2]：✅ 通过 / ❌ 失败
...

## 总结
[阶段总结和下一步计划]
```

## 检查清单

### 任务管理检查清单

**多层级任务列表检查：**

- [ ] 已根据转译规模确定任务列表层级（目录级/文件级/函数级）
- [ ] 目录级任务列表（如需要）：已规划目录结构、模块组织、依赖关系
- [ ] 文件级任务列表（如需要）：已规划文件模块位置、函数分组、共享类型
- [ ] 函数级任务列表（必须）：已为每个函数创建任务列表
- [ ] 任务列表层级关系正确（目录级 → 文件级 → 函数级）

**任务列表质量检查：**

- [ ] 已使用 task_list_manager 创建任务列表
- [ ] 任务列表包含所有阶段（规划、实现、构建、审查、优化、评估）
- [ ] 任务类型正确（sub/main）
- [ ] 任务描述完整（包含约束条件、必须要求、禁止事项、验证标准）
- [ ] **每个子任务都包含 C/C++ 代码行号位置信息**
- [ ] C/C++ 代码位置信息格式正确（函数/类级：`file.c:start-end` 或 `file.cpp:start-end`，文件级：`file.c`/`file.cpp`/`file.hpp`，目录级：`dir/`）
- [ ] 预期输出结构化（使用分条列出格式）
- [ ] 预期输出中包含 C 代码位置信息
- [ ] 任务依赖关系正确设置
- [ ] 已验证任务列表创建成功

### 规划阶段检查清单

- [ ] 已记录 C/C++ 代码位置信息（文件路径和行号范围）
- [ ] C/C++ 代码位置信息已包含在任务描述或背景信息中
- [ ] 对于 C++ 模板，已记录所有实例化的位置
- [ ] 已选择合适的模块位置
- [ ] 已设计符合 Rust 最佳实践的函数签名
- [ ] 函数/结构体/特征注释中包含对应的 C/C++ 代码位置信息
- [ ] 对于 C++ 类，已考虑转换为 Rust 结构体和特征
- [ ] 对于 C++ 模板，已考虑转换为 Rust 泛型
- [ ] 已评估是否需要实现（如跳过，已详细说明原因）
- [ ] 如果是根符号，签名包含 `pub` 关键字
- [ ] **已生成规划阶段文档记录**
- [ ] 规划文档包含所有必需内容（位置信息、决策、评估结果等）
- [ ] 规划文档已保存到指定位置
- [ ] 任务预期输出中包含文档路径

### 实现阶段检查清单

- [ ] 已先编写测试用例
- [ ] 测试用例覆盖主要功能、边界情况、错误情况
- [ ] 已实现函数使测试通过
- [ ] 未使用 `todo!` 或 `unimplemented!` 占位符
- [ ] 使用 Rust 原生类型和惯用法
- [ ] 注释使用中文
- [ ] 函数/结构体/特征注释中包含 C/C++ 代码位置信息
- [ ] 对于 C++ 类，已正确转换为 Rust 结构体和特征
- [ ] 对于 C++ 继承，已正确转换为 Rust 特征和实现
- [ ] 对于 C++ 模板，已正确转换为 Rust 泛型
- [ ] 未使用 `use ...::*` 通配导入
- [ ] **已生成实现阶段文档记录**
- [ ] 实现文档包含所有必需内容（测试设计、实现策略、重构说明等）
- [ ] 实现文档已保存到指定位置
- [ ] 任务预期输出中包含文档路径

### 构建阶段检查清单

- [ ] 所有测试用例通过
- [ ] 无编译错误
- [ ] 修复过程未破坏其他测试
- [ ] 修改最小化，无无关重构
- [ ] **已生成构建阶段文档记录**
- [ ] 构建文档包含所有必需内容（构建过程、问题与解决方案、验证结果等）
- [ ] 构建文档已保存到指定位置
- [ ] 任务预期输出中包含文档路径

### 审查阶段检查清单

- [ ] 测试用例未被破坏（#[test] 标记完整）
- [ ] 无严重问题（空指针、越界等）
- [ ] 测试用例完备（覆盖主要功能、边界、错误）
- [ ] 核心功能与 C/C++ 实现一致
- [ ] 对于 C++ 类，公共接口与原始实现一致
- [ ] 对于 C++ 继承，继承关系正确转换
- [ ] 文件结构合理
- [ ] 问题报告包含详细描述、修复建议和修复代码示例
- [ ] **已生成审查阶段文档记录**
- [ ] 审查文档包含所有必需内容（审查结果、问题列表、修复建议等）
- [ ] 审查文档已保存到指定位置
- [ ] 任务预期输出中包含文档路径

### 优化阶段检查清单

- [ ] 已按优先级修复所有问题
- [ ] 修复后所有测试通过
- [ ] 未引入回归问题
- [ ] 修改最小化
- [ ] **已生成优化阶段文档记录**
- [ ] 优化文档包含所有必需内容（优化问题、修复方案、验证结果等）
- [ ] 优化文档已保存到指定位置
- [ ] 任务预期输出中包含文档路径

### 评估阶段检查清单

- [ ] 已使用子 agent 进行独立评估
- [ ] 评估报告已生成，包含功能对齐检查结果
- [ ] 评估报告中包含 C/C++ 代码位置信息
- [ ] 功能对齐检查已完成，逐项对比 C/C++ 和 Rust 实现
- [ ] 对于 C++ 类，已检查类的封装性和接口一致性
- [ ] 对于 C++ 继承，已检查继承和多态行为
- [ ] 对于 C++ 模板，已检查模板实例化行为
- [ ] 测试覆盖检查已完成
- [ ] 边界情况检查已完成
- [ ] 如发现功能未对齐问题，已创建优化子任务
- [ ] 优化子任务包含 C 代码位置信息
- [ ] 优化子任务已执行并修复问题
- [ ] 修复后已重新评估，功能完全对齐
- [ ] 评估报告确认功能完全对齐
- [ ] 所有测试用例通过
- [ ] **已生成评估阶段文档记录**
- [ ] 评估文档包含所有必需内容（评估报告、功能对齐检查、问题与建议等）
- [ ] 评估文档已保存到指定位置
- [ ] 任务预期输出中包含文档路径

### 根符号特殊要求

如果函数是根符号（需要从 crate 外部访问）：

- [ ] 函数签名包含 `pub` 关键字
- [ ] 函数所在的模块已在 `src/lib.rs` 中导出（`pub mod <模块名>;`）
- [ ] 如果需要 FFI 导出，使用了 `#[no_mangle]` 和 `pub extern "C"`

## 相关资源

- 参考 TDD 规则：{{ rule_file_dir }}/../development_workflow/tdd.md
- 参考代码审查规则：{{ rule_file_dir }}/../code_quality/code_review.md
- 参考 Rust 性能优化：{{ rule_file_dir }}/../performance/rust_performance.md
