模块: math_add
类:   MathAdd
方法: add
文件: math_add_MathAdd.c
函数: math_add_MathAdd_add

#include "math_add_MathAdd.h"
int math_add_MathAdd_add(PikaObj* self, int a, int b){
    return a + b;
}

浮点返回: 优先使用 pika_float 以避免被解释器截断为 0.0。
字符串返回: 当返回函数内的局部变量字符串时，必须使用 obj_cacheStr() 进行缓存，以防悬垂引用。
```
char buf[32];
snprintf(buf, sizeof(buf), "%d", value);
return obj_cacheStr(self, buf);
```
函数签名陷阱: C 函数的返回类型必须与接口头文件严格匹配。返回 Arg* 而接口期望 PikaObj* 会导致 "conflicting types" 编译错误。返回对象时使用 PikaObj*（返回 NULL 表示 None），返回混合类型时使用 Arg*（用 arg_newObj() 包装对象）。
*Arg 返回值处理 (重要先验知识)**:
- 核心陷阱: 不能直接引用或复制现有的 Arg* 对象返回。arg_incRef() 和 arg_newRef() 等API可能不存在或参数类型不匹配。
- 正确模式: 根据数据类型使用对应的构造函数创建新的 Arg* 对象：
```
// 错误：尝试引用现有对象
return arg_incRef(existing_arg); // 函数不存在
return arg_newRef(existing_arg); // 参数类型不匹配

// 正确：创建新的类型特定对象
if (arg_getType(result_arg) == ARG_TYPE_INT) {
    return arg_newInt(arg_getInt(result_arg));
} else if (arg_getType(result_arg) == ARG_TYPE_FLOAT) {
    return arg_newFloat(arg_getFloat(result_arg));
} else if (arg_getType(result_arg) == ARG_TYPE_STRING) {
    return arg_newStr(arg_getStr(result_arg));
}
```
- 常见误区: 认为可以像标准C一样直接返回指针或引用对象。在PikaPython中，必须通过API构造函数创建运行时可识别的对象。
- 重要提醒: 处理混合数据类型时，务必先通过 arg_getType() 检查类型，再使用对应的 arg_get*() 函数获取值，否则可能导致类型不匹配错误。
bytes 返回: bytes 作为返回值时，C 函数应返回 Arg* 类型。必须使用 arg_newBytes(bytes_ptr, len) 来创建返回值。
```
// 示例: 返回一个 bytes 对象
uint8_t data[] = {0x01, 0x02, 0x03};
return arg_newBytes(data, sizeof(data));
```

返回 None: 使用 arg_newNone()。此函数返回一个 Arg* 类型的 None 值。

// 正确示例: 当列表为空时返回 None
if (pikaList_getSize(nums) == 0) {
    return arg_newNone();
}

检查 None: 使用 arg_getType(arg) == ARG_TYPE_NONE。

// 正确示例: 检查返回值是否为 None
Arg* result = some_function(self, nums);
if (arg_getType(result) == ARG_TYPE_NONE) {
    // 处理 None 的情况
}

常见误区:
- 禁止使用 arg_setNull(NULL): 这是一个过时且类型不安全的宏，会引发编译警告或错误。
- 禁止使用 arg_isNull(...): 这个函数不存在，会导致链接错误。

函数签名:

// 错误: PikaObj* 无法直接承载 None
PikaObj* my_function(PikaObj* self, PikaObj* nums);

// 正确: Arg* 可以同时代表对象和 None
Arg* my_function(PikaObj* self, PikaObj* nums);

返回对象 (重要修正): 当返回一个 PikaPython 对象（如 PikaTuple*, PikaList*）时，必须使用 arg_newObj() 将其包装成 Arg*。一律使用 arg_newObj 以减少显式类型参数与误用风险。
- 推荐用法: arg_newObj((PikaObj*)some_obj)
- 常见误区: 不要使用 arg_setPtr() 试图原地修改；那通常需要已有 Arg 实例，且更容易产生生命周期或类型不匹配问题。
```
// 正确示例: 返回一个元组对象
PikaTuple* tuple = New_PikaTuple();
// ... 填充 tuple ...
return arg_newObj((PikaObj*)tuple);
```

安全地使用返回值: 从 Arg* 类型的返回值中提取对象指针前，必须先检查它是否为 None，否则可能导致段错误。

Arg* result_arg = my_function(self, nums);

// 1. 必须先检查 None
if (arg_getType(result_arg) == ARG_TYPE_NONE) {
    // ... 处理 None ...
    return;
}

// 2. 确认不是 None 后，再安全地获取对象指针
PikaObj* result_obj = arg_getPtr(result_arg);
// ... 在此使用 result_obj ...

val_mod = stats.min_max([])
assert val_mod is None, "min_max of empty list should be None"

// 正确的、健壮的列表遍历方式
int len = pikaList_getSize((PikaList*)nums); // 注意：参数通常是 PikaObj*，需要强制转换
for (int i = 0; i < len; i++) {
    Arg* arg = pikaList_get((PikaList*)nums, i);
    pika_float val = 0.0;

    // 检查类型并分别处理
    if (arg_getType(arg) == ARG_TYPE_INT) {
        val = (pika_float)arg_getInt(arg);
    } else if (arg_getType(arg) == ARG_TYPE_FLOAT) {
        val = arg_getFloat(arg);
    }
    
    // ... 在此处理 val ...
}

创建空对象:
- PikaList* my_list = New_PikaList();
- PikaTuple* my_tuple = New_PikaTuple();
- PikaDict* my_dict = New_PikaDict();
- 错误用法: 不要使用 newNormalObj(New_List)，这是过时且错误的。

列表 (List) 操作:

添加元素: pikaList_append(my_list, arg_newFloat(3.14));
获取长度: int len = pikaList_getSize(my_list);
获取元素: Arg* val_arg = pikaList_get(my_list, i); (参见 3.5.1 的类型处理)

列表遍历 (重要先验知识):

推荐模式：使用 pikaList_forEach 回调: 这是遍历列表最健壮、最高效的方法。
核心陷阱: pikaList_forEach 的回调函数签名是固定的，必须包含 itemIndex 参数。错误的签名会导致编译警告 (-Wincompatible-pointer-types) 和潜在的运行时错误。
正确签名: int32_t callback(PikaObj* self, int itemIndex, Arg* itemEach, void* context)

示例:

// 1. 定义一个上下文结构体来持有状态
typedef struct {
    PikaList* integers;
    PikaList* strings;
} MyContext;

// 2. 实现回调函数 (注意 itemIndex 参数)
int32_t process_item_callback(PikaObj* self, int itemIndex, Arg* item_arg, void* context) {
    MyContext* ctx = (MyContext*)context;
    if (arg_getType(item_arg) == ARG_TYPE_INT) {
        pikaList_append(ctx->integers, item_arg);
    } else if (arg_getType(item_arg) == ARG_TYPE_STRING) {
        pikaList_append(ctx->strings, item_arg);
    }
    return 0; // 返回 0 以继续遍历
}

// 3. 在主函数中调用 forEach
MyContext ctx = { .integers = New_PikaList(), .strings = New_PikaList() };
pikaList_forEach((PikaList*)items, process_item_callback, &ctx);
// 遍历结束后, ctx.integers 和 ctx.strings 将包含所需结果

元组 (Tuple) 操作:

元组在 C 层面通常被当作不可变列表处理。

创建并填充元组:

PikaTuple* tuple = New_PikaTuple();
pikaList_append((PikaList*)tuple, arg_newFloat(val1));
pikaList_append((PikaList*)tuple, arg_newFloat(val2));
return (PikaObj*)tuple; // 返回时转换为 PikaObj*

Python 类型注解	C 原生类型	C 函数签名中的类型	说明
`int`	`int`	`int`	Python 基本类型
`int64`	`int64_t`	`int64_t`	64 位整型
`float`	`pika_float`	`pika_float`	Python 基本类型
`str`	`char *`	`char*`	Python 基本类型
`bytes`	`uint8_t *`	`uint8_t*`	Python 基本类型
`list`	`PikaObj *`	`PikaObj*`	注意：在C函数中接收为 `PikaObj*`
`dict`	`PikaObj *`	`PikaObj*`	注意：在C函数中接收为 `PikaObj*`
`tuple`	`PikaObj *`	`PikaObj*`	注意：在C函数中接收为 `PikaObj*`
`any`	`Arg*`	`Arg*`	PikaPython 提供的泛型容器
任意 class	`PikaObj *`	`PikaObj*`	PikaPython 提供的对象容器

导入 & Python 基线函数：import <module_name>；定义 py_xxx(...)。
功能测试：调用 C 模块与基线，比较。
多样化测试数据: 为了验证算法的通用性并防止硬编码，测试脚本必须包含至少两组独立的、合理的常见输入数据。测试应优先覆盖核心功能，可以不包含边界值或可能引发底层环境问题的奇异值（如None 等，除非任务明确要求）。例如：
```
# 第一组数据
data1 = [3, 1, 5, 9, 2]
# ... 对 data1 进行完整测试 ...
# 第二组数据
data2 = [10, 20, 30, 5, 15]
# ... 再次对 data2 进行完整测试 ...
```
只有当所有不同输入的测试都通过时，任务才被视为功能正确。
仅当断言成功后再进行性能测试（4.2）。
输出顺序：[EXAMPLE] -> [PERF] python_total -> [PERF] cmod_total -> [PERF] speedup -> [EXAMPLE][SELFTEST]。

ITER = 10000
# 计时 Python 基线
# 计时 C 模块

禁止三元表达式:
- 错误: val = x / y if y != 0 else 0
- 正确:
```
if y != 0:
    val = x / y
else:
    val = 0
```
禁止 f-string:
- 错误: print(f"value is {x}") 或 assert False, f"error {x}"
- 正确: print("value is", x) 和 assert False, "error " + str(x)

禁止多元赋值 (Tuple Unpacking):

错误: a, b = 1, 2 或 mn, mx = min_max(data)

正确:

a = 1
b = 2
# 对于函数返回元组
min_max_val = min_max(data)
mn = min_max_val[0]
mx = min_max_val[1]

禁止使用迭代器 (iter/next):
- 原因: PikaPython 的 for 循环对迭代器的支持不完整，直接使用 iter() 和 next() 可能导致运行时错误或段错误。
- 错误:
```
it = iter(nums)
first = next(it)
for x in it:
    # ...
```
- 正确: 使用 range 和索引进行遍历。
```
# 正确的遍历方式
if len(nums) == 0:
    return
first = nums[0]
for i in range(1, len(nums)):
    x = nums[i]
    # ...
```
禁止 try...except Exception as e 语法:
- 原因: PikaPython 的 try...except 实现可能不完全支持 as e 语法来捕获异常对象。使用它可能导致 NameError: name 'e' is not defined。

# 初始化一个空字典
counts = {}
for i in range(len(data)):
    item = data[i]
    # 第一步：使用 .get() 获取当前计数，注意：必须检查是否为 None
    current_count = counts.get(item)
    if current_count is None:
        # 第二步：键不存在，设置初始值
        counts[item] = 1
    else:
        # 第三步：键存在，更新计数
        counts[item] = current_count + 1

禁止使用部分内置函数 (如 sum()):
- 原因: PikaPython 的标准库实现非常精简，不包含所有 Python 的内置函数，例如 sum()。这是导致运行时 NameError: name 'sum' is not defined 的最常见原因之一。
- 错误: total = sum(my_list)
- 正确 (避障策略): 使用手动循环来实现相同的功能。
```
total = 0
for x in my_list:
    total += x
```
- 其他受限内置函数: 包括但不限于 max(), min(), abs(), round() 等。遇到 NameError 时，首先检查是否使用了不支持的内置函数。
算法选择在受限环境下的权衡 (重要先验知识):
- 核心原则: 在PikaPython受限环境下，实用性优先于理论最优。宁可选择时间复杂度较高的确定可行算法，也不要使用可能导致运行时崩溃的高效算法。
- 典型案例: 对于计数类问题，优先使用双重循环手动计数（O(n²)），而非字典计数（可能触发 KeyError 或语法不支持）。
- 决策准则: 如果标准Python实现依赖字典、复杂数据结构或高级语法，应主动寻求等价的简化实现，即使性能稍差。

PikaPython环境限制补充:
- 禁止f-string、三元表达式、多元赋值、复杂断言、迭代器、部分内置函数（如sum、max、min、round、abs等）。
- print仅支持逗号分隔参数，禁止f-string和.format。
- 字典不支持key in dict，必须用dict.get(key)并检查None。
- C端类型系统严格区分Arg*与PikaObj*，返回值类型必须与接口头文件一致。
- 字符串返回必须用obj_cacheStr()，对象返回用arg_newObj()。
- 列表元素类型需分支处理，不能直接用getFloat读取int。
- 性能测试必须在功能断言全部通过后进行，避免无效数据。
- 性能测试参数需根据环境实际调整，避免超时。
- 复杂对象嵌套（如字典值为列表）需用arg_newObj包装，禁止用setPtr存指针。
- 断言表达式复杂导致解析失败，需拆分为简单断言。
- 所有函数入口优先处理空列表、None、越界等情况。
- 任何硬编码、伪造逻辑都视为失败，禁止为通过测试而虚假实现。
典型报错诊断经验补充:
- KeyError：极大概率为基线函数用key in dict，需改为dict.get(key)模式。
- NameError：常见于sum、max等内置函数或f-string，需用手动循环或print分隔参数替代。
- TypeError: exceptions must derive from BaseException：断言表达式过于复杂，需拆分为简单断言。
- Assertion "self != 0" failed：C端未检查NULL指针，需在用arg_getType前加NULL判断。
- arg type not support：C端返回了原始指针或类型不符，需用arg_newObj包装对象。
- conflicting types编译错误：C函数返回类型与接口头文件不一致，需严格匹配。
- undefined reference to 'arg_incRef'：API不存在，需用类型构造函数如arg_newInt等。
- incompatible pointer types：arg_newRef参数类型错误，需用arg_getPtr或直接用arg_newObj。
- ValueError: invalid literal for int()：数字字面量带下划线，需去除。
最佳实践与避障策略补充:
- 所有基线函数优先用最基础for循环和if-else，避免任何高阶语法。
- 字典计数优先用双重循环替代，保证稳定性。
- 调试时优先创建极简测试用例，逐步增量恢复。
- C端所有对象操作前必须做类型和NULL检查。
- 遇到API不确定时，优先用grep在源码中查找。
- 记录所有API用法和修复模式，形成知识库。
主动调试与增量修复补充:
- 先实现最小可运行版本，逐步添加逻辑。
- 每次修改后立即编译运行，遇错即回退。
- 记录所有API用法和修复经验，形成知识库。
代码探索黄金法则补充:
- API不确定时，优先用grep在pikapython-linux/pikapython/pikascript-core/PikaObj.h查找。
- 记录所有API用法和修复经验，形成知识库。

函数签名类型冲突诊断:
- 现象: 编译时出现 error: conflicting types for 'function_name'; have 'Arg *(PikaObj *, PikaObj *)' but want 'PikaObj *(PikaObj *, PikaObj *)'。
- 原因: C 函数实现中的返回类型与接口头文件 (.pyi 生成的 .h 文件) 中声明的返回类型不匹配。通常是返回了 Arg* 但接口期望 PikaObj*，反之亦然。
- 诊断步骤:
  1. 检查生成的头文件中的函数声明。
  2. 对比 C 实现文件中的函数签名。
  3. 确认返回类型是否匹配（PikaObj* vs Arg*）。
- 修复模式: 根据接口要求调整函数签名。对于返回对象的情况，使用 PikaObj* 并返回 NULL 表示 None；对于可能返回对象或 None 的情况，使用 Arg* 并用 arg_newObj() 包装对象。
arg_newRef 参数类型不匹配诊断:
- 现象: 编译时出现 error: incompatible pointer types 或运行时崩溃。
- 原因: arg_newRef() 函数期望接收 PikaObj* 类型，但传入的是 Arg* 类型。
- 诊断步骤:
  1. 检查所有 arg_newRef() 调用，确保参数是 PikaObj* 类型。
  2. 如果需要从 Arg* 转换为 PikaObj*，使用 arg_getPtr() 函数。
  3. 验证对象生命周期，确保返回的对象在函数作用域内有效。
- 修复模式: return arg_newRef(arg_getPtr(arg)); 而非直接 return arg_newRef(arg);。
NULL 指针断言失败诊断:
- 现象: 运行时出现 Assertion 'obj != NULL' failed 或类似崩溃。
- 原因: 在调用 arg_getType() 或其他需要有效对象的函数前，未检查对象是否为 NULL。
- 诊断步骤:
  1. 检查所有 arg_getType() 调用前是否有 NULL 检查。
  2. 验证参数获取逻辑，确保 arg_getPtr() 返回值不为 NULL。
  3. 添加防御性编程：if (NULL == obj) return arg_newNone();。
- 修复模式: 在所有对象操作前添加 NULL 检查。
编译警告的系统性处理:
- 格式字符串警告: %d vs %ld 类型不匹配，虽然不影响功能，但应统一使用 %ld（long int）。
- 未使用变量警告: 移除或注释掉未使用的变量声明。
- 隐式声明警告: 确保所有函数都有正确的原型声明。
- 处理原则: 即使警告不影响运行，也应及时修复以维护代码质量。

错误场景: C 模块执行时，程序因 Aborted 退出，日志显示 Assertion "self != 0" failed, in function: arg_getType()。
核心原因: 这是一个空指针断言失败。它意味着一个 NULL 指针被传递给了 arg_getType() 函数，而该函数期望一个有效的 Arg* 参数。这几乎总是由 pikaDict_get() 或 pikaList_get() 等查找函数在未找到指定内容时返回 NULL（而不是一个 ARG_TYPE_NONE 的 Arg* 对象）引起的。
诊断步骤:
1. 定位来源: 找到日志中失败的 arg_getType() 调用在 C 源码中的位置。
2. 追溯上游: 查看被传入 arg_getType() 的那个 Arg* 变量是从哪里获取的。大概率是来自一个 pikaDict_get() 或 pikaList_get() 的调用。
3. 确认问题: 这表明上游的查找操作失败了（例如，字典中不存在该键），并且其返回的 NULL 值未经检查就直接被使用了。

解决方向: 必须在使用 pikaDict_get() 或 pikaList_get() 的返回值之前，添加一个 NULL 指针检查。

// 错误：未检查 pikaDict_get 的返回值
Arg* count_arg = pikaDict_get(counts, key);
if (arg_getType(count_arg) == ARG_TYPE_NONE) { // 如果 count_arg 是 NULL，这里会崩溃
    // ...
}

// 正确：在使用前进行 NULL 检查
Arg* count_arg = pikaDict_get(counts, key);
if (count_arg == NULL) { // 键不存在，返回了 NULL
    // 处理键不存在的情况，例如设置初始值
    pikaDict_setInt(counts, key, 1);
} else {
    // 键存在，可以安全地使用 count_arg
    int current_count = arg_getInt(count_arg);
    pikaDict_setInt(counts, key, current_count + 1);
}

错误场景: 编译时出现 undefined reference to 'arg_incRef' 或类似 "implicit declaration" 警告。
核心原因: 尝试使用了不存在的API函数。PikaPython的API可能与预期不符，某些函数名不存在或签名不同。
诊断步骤:
1. 检查函数名: 确认是否使用了正确的API。arg_incRef 不存在，应使用类型特定的构造函数。
2. 查找替代方案: 使用 grep 在头文件中搜索相关API，或参考现有成功案例。

解决方向:

使用类型构造函数: 不要尝试引用现有对象，而是创建新的：

// 错误
return arg_incRef(existing_arg);

// 正确
if (arg_getType(existing_arg) == ARG_TYPE_INT) {
    return arg_newInt(arg_getInt(existing_arg));
}

适用场景:
- 遇到“未定义引用 (undefined reference)”或“隐式声明 (implicit declaration)”编译错误。
- 不确定某个功能的 API 函数名（例如，是 pikaList_len, pika_list_len 还是 pika_list_length）。
- 想要查找某个宏或类型的定义。

黄金操作范例:

定位核心头文件: PikaPython 的绝大多数核心 API 都定义在 pikapython-linux/pikapython/pikascript-core/PikaObj.h。

使用 grep 精准搜索:

# 示例：当不确定列表长度函数的准确名称时，
# 搜索包含 "pikaList" 和 "len" 的行
grep -n "pikaList" ./pikapython-linux/pikapython/pikascript-core/PikaObj.h | grep "len"

# 示例：宽泛地搜索与 "pikaList" 相关的所有 API
grep -n "pikaList" ./pikapython-linux/pikapython/pikascript-core/PikaObj.h | head -20

核心价值: 这种方法能让你自主发现最准确、最新的 API 用法，减少因信息不全或规则遗漏导致的错误重试，是成为高级问题解决者的关键一步。

实践一：创建小型、独立的测试用例
- 场景: 当一个复杂的测试用例失败时，很难确定是哪个输入或逻辑分支导致了问题。
- 策略: 不要直接在原始的 test_example.py 中反复修改。创建一个新的、临时的 Python 文件（例如 debug_test.py），在其中只包含最简单的代码来复现问题。
- 步骤:
  1. 隔离: 从复杂的输入数据中提取出能触发 bug 的最小子集。
  2. 简化: 编写一个只调用问题 C 函数的极简 Python 脚本。
  3. 运行: 使用 python run_pika.py 独立运行这个调试脚本。
- 优势: 这种方法可以快速验证关于 bug 的假设，排除干扰因素，并显著加快定位速度。
实践二：在 C 代码中打印中间变量
- 场景: 当 C 模块的最终输出不符合预期（例如，返回了 None、错误的计数值或空列表），但程序没有崩溃时。
- 策略: 在 C 函数的关键逻辑点，使用 printf 打印出中间变量的值。这可以让你清晰地追踪算法的执行流程和数据状态。
- 步骤:
  1. 包含头文件: 确保 C 文件顶部有 #include <stdio.h>。
  2. 植入打印语句: 在循环内部、条件判断分支、返回值之前等关键位置添加 printf。为了方便在日志中识别，可以加上特殊前缀。
```
// 示例：在循环中打印计数值
printf("[DEBUG] Key: %s, Current Count: %d\n", key, current_count);
```
  3. 重新构建和运行: 执行 python run_pika.py ...。
  4. 分析日志: 在 compile.log（如果 printf 导致编译错误）或 run.log 中查找你的 [DEBUG] 输出，观察变量的变化是否符合预期。
- 注意: 调试完成后，应移除或注释掉这些 printf 语句。
实践三：API学习与错误驱动开发
- 场景: 对PikaPython API不熟悉，导致多次编译和运行时错误。
- 策略: 采用渐进式API探索，从错误信息中学习正确的用法。
- 步骤:
  1. 从简单开始: 先实现最基本的逻辑，使用已知可行的API。
  2. 错误驱动学习: 当遇到编译错误时，不要猜测，而是使用 grep 在源码中查找正确API。
  3. 小步验证: 每次只尝试一个新的API调用，立即编译验证。
  4. 记录模式: 将学到的API模式记录下来，避免重复犯错。
- 关键教训:
  - 不要假设API的存在性，总要验证。

[MODULE] <module_name>
[OUTPUT]
<关键运行输出行：EXAMPLE / PERF / SELFTEST>
[END]

字典 (Dict) 操作:

设置键值对:

pikaDict_setFloat(my_dict, "mean", 12.3);
pikaDict_setInt(my_dict, "count", 5);
pikaDict_setStr(my_dict, "status", "ok");

核心陷阱：在字典中存储对象（如列表、其他字典）
- 问题描述: 当你希望一个字典的值是另一个 PikaPython 对象（例如，一个 PikaList*）时，一个致命的错误是使用 pikaDict_setPtr()。这个函数只会存储该对象的原始内存地址（指针），而不是运行时可识别的对象引用。
- 错误后果: 在 Python 测试脚本中，当你访问这个字典键时，你得到的是一个无法使用的整数（内存地址），而不是一个可操作的列表或字典对象。对其调用 len() 或进行索引将导致 TypeError 或 len: arg type not support 错误。
- 常见误区 (错误示例):
```
PikaList* evens_list = New_PikaList();
// ... 填充列表 ...
// 错误！这只存储了 evens_list 的地址，Python 端无法使用
pikaDict_setPtr(result_dict, "even", (PikaObj*)evens_list);
```
- 正确模式：使用 arg_newObj() 和 pikaDict_set():
  1. 创建你的对象（例如 PikaList*）。
  2. 使用 arg_newObj() 将该对象包装成一个运行时可识别的 Arg*。
  3. 使用 pikaDict_set() 将这个 Arg* 存入字典。
```
// 正确示例
PikaList* evens_list = New_PikaList();
// ... 填充列表 ...
// 1. 将 PikaList* 包装成 Arg*
Arg* arg_list = arg_newObj((PikaObj*)evens_list);
// 2. 将 Arg* 存入字典
pikaDict_set(result_dict, "even", arg_list);
```
先验知识：字典与复杂对象: PikaPython 的字典在处理嵌套的复杂对象（尤其是返回 None 的情况）时可能存在不稳定性，容易引发 arg_isCallable 等运行时断言失败。
避障策略: 如果一个函数返回字典，且该字典的值包含其他函数调用的结果（特别是可能返回 None 或其他对象的函数），应优先简化或避免这种结构。如果遇到难以调试的运行时崩溃，可尝试将返回字典的复杂函数从测试中暂时移除，以优先确保其他核心功能的正确性。
字典 (Dict) 遍历 (重要先验知识)
- 核心陷阱: PikaPython 的 C API 中 不存在 pikaDict_keys() 函数。尝试调用它会导致 undefined reference 编译错误。

try:
    # ... some code that might fail ...
except Exception as e:
    print("An error occurred:", e)

正确 (避障策略): 使用不带 as e 的 except 块来捕获异常，但这将无法获取异常对象的具体信息。

try:
    # ... some code that might fail ...
except:
    print("An error occurred")

禁止复杂的断言表达式:

原因: PikaPython 的断言处理不支持复杂的布尔表达式，可能导致 TypeError: exceptions must derive from BaseException。
错误: assert len(a) == len(b) == 0

正确:

assert len(a) == 0, "a should be empty"
assert len(b) == 0, "b should be empty"

实践五：类型前缀键策略处理混合数据类型

场景: 需要在 C 代码中对包含不同数据类型的列表进行计数或分组。
策略: 使用带类型前缀的字符串键来处理混合数据类型。

实现模式:

char key[128] = {0};
if (arg_getType(item_arg) == ARG_TYPE_INT) {
    snprintf(key, sizeof(key), "i_%ld", (long)arg_getInt(item_arg));
} else if (arg_getType(item_arg) == ARG_TYPE_FLOAT) {
    snprintf(key, sizeof(key), "f_%.6f", arg_getFloat(item_arg));
} else if (arg_getType(item_arg) == ARG_TYPE_STRING) {
    snprintf(key, sizeof(key), "s_%s", arg_getStr(item_arg));
}

优势: 完美解决 PikaPython 字典键必须是字符串的限制，支持混合类型处理。

实践七：类型安全的数据提取模式

场景: 在 C 代码中处理 Python 列表元素时，需要安全地提取 int 和 float 值。
策略: 建立标准化的类型检查和提取模式，避免类型不匹配错误。

实现模式:

// 标准化的元素处理模式
pika_float value = 0.0;
if (arg_getType(element) == ARG_TYPE_INT) {
    value = (pika_float)arg_getInt(element);
} else if (arg_getType(element) == ARG_TYPE_FLOAT) {
    value = arg_getFloat(element);
} else {
    // 处理不支持的类型或返回错误
    return arg_newNone();
}

优势: 确保类型安全，避免运行时崩溃，并提供清晰的错误处理。

实践八：边界情况优先设计

场景: 忘记处理空列表、None 值等边界情况，导致运行时错误。
策略: 在函数开始处优先检查边界情况，确保核心逻辑只处理有效输入。

实现模式:

// 边界情况优先处理
int len = pikaList_getSize((PikaList*)nums);
if (len == 0) {
    // 直接返回适当的默认值
    return arg_newNone(); // 或空列表等
}
// 然后处理正常情况

优势: 简化核心逻辑，提高代码可读性和鲁棒性。

正确模式 1：通过索引遍历 (不推荐但可用)

API: pikaDict_getSize() 和 pikaDict_getArgByindex()。
描述: 此方法通过索引 i 从 0 到 size-1 遍历字典。pikaDict_getArgByindex() 返回的是键的 Arg*。你需要用这个键再次调用 pikaDict_get() 来获取值。
缺点: 效率较低，且容易出错（例如，忘记检查 NULL 返回值）。

int dict_size = pikaDict_getSize(counts);
for (int i = 0; i < dict_size; i++) {
    Arg* key_arg = pikaDict_getArgByindex(counts, i);
    if (key_arg == NULL) continue;
    
    char* key = arg_getStr(key_arg);
    Arg* count_arg = pikaDict_get(counts, key);
    // ... process count_arg ...
}

正确模式 2：使用 forEach 回调 (强烈推荐)

API: pikaDict_forEach()。
描述: 这是遍历字典最健壮、最高效的方法。它接受一个回调函数，该函数会对字典中的每一个键值对被调用。你可以通过一个上下文结构体 (context) 来传递和修改状态。

示例:

// 1. 定义一个上下文结构体来持有状态
typedef struct {
    int max_count;
    char max_key[128];
} MaxCountContext;

// 2. 实现回调函数
int32_t find_max_count_callback(PikaObj* self, Arg* keyEach, Arg* valEach, void* context) {
    MaxCountContext* ctx = (MaxCountContext*)context;
    int count = arg_getInt(valEach);
    if (count > ctx->max_count) {
        ctx->max_count = count;
        // 关键：从 keyEach (这是一个 Arg*) 中获取字符串
        char* key_str = arg_getStr(keyEach);
        // 安全地更新上下文中的 max_key
        strncpy(ctx->max_key, key_str, sizeof(ctx->max_key) - 1);
        ctx->max_key[sizeof(ctx->max_key) - 1] = '\\0';
    }
    return 0; // 返回 0 以继续遍历
}

// 3. 在主函数中调用 forEach
MaxCountContext ctx = {0, ""}; // 初始化上下文
pikaDict_forEach((PikaObj*)counts, find_max_count_callback, &ctx);
// 遍历结束后, ctx.max_key 和 ctx.max_count 将包含所需结果

Pikapython | Skills Pool

Pikapython

Pikapython

1 角色与总体目标

2 执行阶段

2.1 模块生成

2.2 测试脚本生成（功能优先，性能后置）

2.3 构建与运行

2.4 结果提取

2.5 错误处理

3 命名与实现规范

3.1 文件与路径

3.2 C 文件/函数命名

3.2.1 C 文件头文件规范

3.2.2 函数封装规范

3.3 返回值与字符串

3.4 None 值与复杂返回值处理（重要）

3.4.1 None 值的正确处理 API

3.4.2 处理“对象或 None”的返回值

3.5 列表 (List)、元组 (Tuple)、字典 (Dict) 操作指南

3.5.1 核心陷阱：Python int 与 C float 的类型不匹配

3.5.2 PikaPython 核心对象创建与操作

3.6 可用的类型注解

4 测试脚本格式规范

4.1 结构与顺序（必须严格遵守）

4.2 性能测试准则

5 运行与工具使用

5.1 允许写入路径（再声明）

5.2 工具调用规则

5.3 构建命令重述

6 环境差异与限制

6.1 Python 语法子集限制 (重要)

6.1.1 基线函数增量修复流程（强制）

6.1.2 基线函数设计的“避障优先”原则

6.1.3 案例经验教训与提醒

6.2 print 使用限制

6.3 轻量运行时差异

7 调试与故障排查

7.1 Segmentation fault 增量定位策略

7.1.1 基于分析报告的诊断经验

7.2 错误输出格式

7.2.1 运行时错误诊断经验：arg type not support

7.2.2 运行时错误诊断经验：IndexError: index out of range

7.2.3 运行时错误诊断经验：Assertion "self != 0" failed

7.2.4 运行时错误诊断经验：KeyError

7.2.5 运行时错误诊断经验：ValueError: invalid literal for int()

7.2.6 运行时错误诊断经验：NameError

7.2.7 编译错误诊断经验：undefined reference to 'arg_incRef'

7.2.8 运行时错误诊断经验：incompatible pointer types (arg_newRef)

7.2.9 编译错误诊断经验：format '%d' expects argument of type 'int', but argument has type 'int64_t'

7.2.10 运行时错误诊断经验：KeyError (字典操作)

7.3 主动代码探索黄金法则 (grep 的妙用)

7.4 语义完整性原则与退化报告

7.5 主动调试最佳实践

8 输出格式定义

Bun Runtime

Bun Runtime

Python Patterns

Python Patterns

Publish Extension

Minecraft Modpack Server

3.4 `None` 值与复杂返回值处理（重要）

3.4.1 `None` 值的正确处理 API

3.5.1 核心陷阱：Python `int` 与 C `float` 的类型不匹配

7.2.1 运行时错误诊断经验：`arg type not support`

7.2.2 运行时错误诊断经验：`IndexError: index out of range`

7.2.3 运行时错误诊断经验：`Assertion "self != 0" failed`

7.2.4 运行时错误诊断经验：`KeyError`

7.2.5 运行时错误诊断经验：`ValueError: invalid literal for int()`

7.2.6 运行时错误诊断经验：`NameError`

7.2.7 编译错误诊断经验：`undefined reference to 'arg_incRef'`

7.2.8 运行时错误诊断经验：`incompatible pointer types` (arg_newRef)

7.2.9 编译错误诊断经验：`format '%d' expects argument of type 'int', but argument has type 'int64_t'`

7.2.10 运行时错误诊断经验：`KeyError` (字典操作)

7.3 主动代码探索黄金法则 (`grep` 的妙用)