Python to C++11 AI Agent Skill 设计文档

版本信息

1. 概述

1.1 项目背景

Python和C++是两种广泛使用的编程语言，各有优势：

• Python：简洁、易学、丰富的库生态

• C++：高性能、底层控制、内存效率

在嵌入式系统、边缘计算、高性能计算等领域，经常需要将Python代码转换为C++以获得更好的性能。特别是Rockchip RKNN/RKNNLite SDK，Python API和C++ API有显著差异，需要专门的转换支持。

1.2 项目目标

1. 完整性：转换后的C++代码不能遗漏任何功能

2. 正确性：转换后的代码逻辑必须与Python代码一致

3. 合规性：生成的代码必须符合C++11标准

4. 可验证：提供测试用例验证转换结果

5. 专业性：特别支持RKNN/RKNNLite SDK转换

1.3 适用范围

• Python 3.x 到 C++11 的代码转换

• 通用Python代码转换

• RKNN/RKNNLite SDK专用转换

• OpenCV集成代码转换

2. 系统架构

2.1 整体架构

┌─────────────────────────────────────────────────────────┐
│                    Skill Interface                       │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   SKILL.md  │  │  References │  │   Scripts   │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
├─────────────────────────────────────────────────────────┤
│                   Conversion Engine                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Parser    │  │  Converter  │  │  Generator  │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
├─────────────────────────────────────────────────────────┤
│                   Validation Layer                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Syntax    │  │  Semantic   │  │   Runtime   │     │
│  │  Validator  │  │  Validator  │  │   Tester    │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
├─────────────────────────────────────────────────────────┤
│                   Specialized Modules                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │    RKNN     │  │  RKNNLite   │  │   OpenCV    │     │
│  │   Module    │  │   Module    │  │   Module    │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────┘

2.2 核心组件

2.2.1 SKILL.md

• 技能描述和触发条件

• 完整的类型映射表

• 语法结构映射规则

• 最佳实践指南

2.2.2 References

• rknn_api_mapping.md：RKNN API完整映射

• rknnlite_api_mapping.md：RKNNLite API完整映射

• cpp11_patterns.md：C++11常用模式参考

2.2.3 Scripts

• convert.py：主转换脚本

• validate.py：验证脚本

2.2.4 Examples

• 基础转换示例

• RKNN转换示例

• RKNNLite转换示例

3. 转换规则详解

3.1 类型系统转换

3.1.1 基础类型映射

3.1.2 容器类型映射

3.1.3 特殊类型映射

3.2 语法结构转换

3.2.1 函数定义

转换规则：

1. 参数类型转换为C++类型

2. 返回类型显式声明

3. 默认参数保留

4. 文档字符串转换为注释

3.2.2 类定义

转换规则：

1. 类成员变量声明

2. 构造函数生成

3. 析构函数生成（如果需要）

4. 方法转换

5. 属性转换为getter/setter

3.2.3 控制流

3.2.4 列表推导式

# Python
result = [x * 2 for x in items if x > 0]

// C++11
std::vector<decltype(items[0] * 2)> result;
for (const auto& x : items) {
    if (x > 0) {
        result.push_back(x * 2);
    }
}

3.2.5 异常处理

3.3 RKNN/RKNNLite专用转换

3.3.1 RKNN初始化转换

# Python
from rknn.api import RKNN
rknn = RKNN()
rknn.load_rknn('model.rknn')
rknn.init_runtime(target='rk3588')

// C++11
#include "rknn_api.h"
​
rknn_context ctx;
std::ifstream file("model.rknn", std::ios::binary | std::ios::ate);
size_t size = file.tellg();
file.seekg(0, std::ios::beg);
std::vector<uint8_t> model_data(size);
file.read(reinterpret_cast<char*>(model_data.data()), size);
file.close();
​
rknn_init(&ctx, model_data.data(), size, 0, nullptr);

3.3.2 RKNN推理转换

# Python
outputs = rknn.inference(inputs=[img])

// C++11
rknn_input input;
memset(&input, 0, sizeof(input));
input.index = 0;
input.type = RKNN_TENSOR_UINT8;
input.size = img_size;
input.fmt = RKNN_TENSOR_NHWC;
input.buf = img_data;
​
rknn_set_input(ctx, 1, &input);
​
rknn_output output;
memset(&output, 0, sizeof(output));
output.want_float = 1;
output.is_prealloc = 0;
​
rknn_run(ctx, &output);

3.3.3 RKNNLite核心选择

# Python
rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0_1_2)

// C++11
// NPU核心掩码定义
constexpr uint32_t NPU_CORE_AUTO = 0;
constexpr uint32_t NPU_CORE_0 = 1 << 0;
constexpr uint32_t NPU_CORE_1 = 1 << 1;
constexpr uint32_t NPU_CORE_2 = 1 << 2;
constexpr uint32_t NPU_CORE_0_1_2 = NPU_CORE_0 | NPU_CORE_1 | NPU_CORE_2;
​
// 初始化时传入核心掩码
rknn_init(&ctx, model_data, model_size, NPU_CORE_0_1_2, nullptr);

4. 验证系统

4.1 语法验证

检查项：

• 头文件包含

• 括号匹配

• 分号使用

• 命名空间

4.2 编译验证

验证流程：

1. 生成临时源文件

2. 调用g++编译

3. 检查编译错误

4. 记录警告信息

4.3 运行验证

验证流程：

1. 执行编译后的程序

2. 比较输出结果

3. 验证边界条件

4.4 RKNN验证

专用检查：

• rknn_api.h包含

• rknn_init/rknn_destroy配对

• 内存分配/释放检查

• 输入输出格式验证

5. 测试用例

5.1 基础功能测试

5.2 RKNN专用测试

5.3 边界条件测试

6. 使用指南

6.1 CLI使用

# 基本转换
python scripts/convert.py --input input.py --output output.cpp
​
# RKNN专用转换
python scripts/convert.py --input rknn_demo.py --output rknn_demo.cpp --rknn
​
# RKNNLite专用转换
python scripts/convert.py --input rknnlite_demo.py --output rknnlite_demo.cpp --rknnlite
​
# 验证转换结果
python scripts/validate.py --cpp output.cpp --compile

6.2 编译配置

cmake_minimum_required(VERSION 3.10)
project(converted_code CXX)
​
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
​
# RKNN SDK路径
set(RKNN_SDK_PATH /path/to/rknpu2)
​
include_directories(
    ${RKNN_SDK_PATH}/include
)
​
add_executable(main main.cpp)
​
target_link_libraries(main
    rknnrt
)

7. 最佳实践

7.1 内存管理

1. 使用智能指针管理动态内存

2. 遵循RAII原则

3. 避免内存泄漏

7.2 类型安全

1. 使用强类型

2. 避免void*滥用

3. 使用const正确性

7.3 性能优化

1. 使用移动语义

2. 避免不必要的拷贝

3. 合理使用constexpr

7.4 RKNN优化

1. 合理分配NPU核心

2. 预分配内存

3. 批量处理

8. 局限性说明

8.1 语言差异

8.2 库差异

9. 版本历史

v1.0.0

• 初始版本

• 支持基础Python到C++11转换

• 支持RKNN/RKNNLite专用转换

• 完整的验证系统

• 详细的设计文档

10. 附录

10.1 文件清单

python-to-cpp11/
├── SKILL.md                      # 主技能描述
├── DESIGN.md                     # 设计文档
├── scripts/
│   ├── convert.py                # 转换脚本
│   └── validate.py               # 验证脚本
├── references/
│   ├── rknn_api_mapping.md       # RKNN API映射
│   ├── rknnlite_api_mapping.md   # RKNNLite API映射
│   └── cpp11_patterns.md         # C++11模式参考
├── examples/
│   ├── basic_conversion.py       # 基础示例
│   ├── rknn_conversion.py        # RKNN示例
│   └── rknnlite_conversion.py    # RKNNLite示例
└── evals/
    └── evals.json                # 测试用例

10.2 术语表

10.3 参考资料

1. C++11标准文档

2. Rockchip RKNN SDK文档

3. Python语言参考手册

4. OpenCV C++ API文档