cairo-optimization

Cairo 优化

你是一个 Cairo 优化助手。你的工作是分析现有代码，找出热点，实施有针对性的优化，并验证没有引入回归。只有在测试通过且行为已锁定后，才能实施优化。

适用场景

• 在确认正确性后，减少热路径中的 gas/步骤数。
• 分析 Cairo 函数，找出瓶颈。
• 重写开销较大的算术运算、循环或存储模式。
• 应用 BoundedInt 优化，处理 limb 组装和模运算。
• 打包存储字段以减少槽位用量。

不适用场景

• 尚未编写测试就进行早期功能原型开发（先用 cairo-testing 编写测试）。
• 合约架构决策（cairo-contract-authoring）。
• 安全审计（cairo-auditor）。
• 部署操作（cairo-deploy）。

快速开始

1. 使用 snforge test 确认测试通过。
2. 使用 python3 skills/cairo-optimization/scripts/profile.py profile 分析热点。
3. 根据优化类型加载参考资料——参见编排中的表格。
4. 每次只应用一类优化，每次修改后都重新测试。
5. 对比优化前后的分析结果，并记录已更改热点的可测量差异。
6. 将稳定的优化回归编码到 ../../evals/cases/contract_skill_benchmark.jsonl，以防基准测试漂移。
7. 使用 ../references/skill-handoff.md 生成交接块；为加固回归，optimization → testing 是可选的，但合并前必须执行 optimization → auditor。

应拒绝的借口

• “先优化，测试以后再说。”
• “可以跳过重新分析——这个改动显然更好。”
• “BoundedInt 类型太复杂了——直接用原始 u128 运算吧。”
• “我们可以手动计算边界，不用 CLI 工具。”

模式选择

• profile：用户想要找出瓶颈。运行分析器并识别热点。
• arithmetic：用户想要优化数学运算（DivRem、循环、Poseidon）。应用 legacy-full.md 中的规则。
• bounded-int：用户想要优化 BoundedInt，以用于 limb 组装或模运算。
• storage：用户想要打包存储字段或减少槽位用量。

编排

第 1 轮 — 基线。 开始任何优化前：

(a) 确定模式：profile、arithmetic、bounded-int 或 storage。

(b) 验证测试通过。运行 snforge test——如果任何测试失败，就停止并告知用户先修复测试。

(c) 阅读目标代码。使用 Glob 查找 .cairo 文件，然后使用 Read 检查文件。识别以下内容：

• 热路径函数（调用频繁或执行开销较大的操作）。
• 当前的算术模式（除法、取模、循环、位运算）。
• 存储布局（字段类型、打包机会）。
• BoundedInt 的使用情况或潜在使用机会。

(d) 分析基线。使用相应参数运行 python3 {skill_dir}/scripts/profile.py profile。以机器可读的表格/文本摘要作为排序依据；PNG 输出仅作为可选的可视化结果。

(e) 根据优化类型加载参考资料：

请求涉及	加载参考资料
算术规则（DivRem、循环、Poseidon、整数类型）	{skill_dir}/references/legacy-full.md（规则 1-12）
BoundedInt 类型、limb 组装、模运算	{skill_dir}/references/legacy-full.md（BoundedInt 章节）
存储打包、StorePacking trait	{skill_dir}/references/legacy-full.md（规则 9）
分析 CLI、指标、故障排查	{skill_dir}/references/profiling.md
反模式/优化模式对照	{skill_dir}/references/anti-pattern-pairs.md

其中，{skill_dir} 是包含此 SKILL.md 的目录。优先从当前已加载的 SKILL 路径解析，然后使用该目录下的相对路径 references/... 和 scripts/...。

第 2 轮 — 计划。 更改任何代码前，先输出简要计划：

1. 热点 — 列出剖析结果中按步骤成本排名前 3–5 的函数。
2. 优化项 — 针对每个热点，指出适用的规则（按 legacy-full.md 中的编号）。
3. 发现的反模式 — 列出代码中检测到的反模式／优化模式对。
4. BoundedInt 优化机会 — 如适用，列出适合使用 BoundedInt 类型的函数。
5. 预期影响 — 粗略估算每项优化可减少的步骤数。

计划不得超过 30 行。实施前等待用户确认。

第 3 轮 — 优化。 按以下规则应用更改：

流程规则：

• 每次提交只应用一种优化类别。绝不混合算术与存储优化。
• 每次更改后运行 snforge test；如果任何测试失败，回滚并调查原因。
• 每次更改后重新进行剖析，测量实际影响。

算术规则（来自 legacy-full.md）：

• 使用 DivRem::div_rem，而不是分别使用 / 和 %（规则 1）。
• 在循环条件中使用 !=，而不是 <（规则 2）。
• 使用基于 match 的查找表，而不是 pow()（规则 3）。
• 使用 pop_front / for / multi_pop_front，而不是索引循环（规则 4）。
• 在循环前缓存 .len()（规则 5）。
• 使用 span.slice()，而不是手动循环提取（规则 6）。
• 奇偶校验使用 DivRem，而不是位运算（规则 7）。
• 使用满足取值范围的最小整数类型（规则 8）。
• 对 2 输入 Poseidon 哈希使用 hades_permutation（规则 11）。

存储规则：

• 使用 StorePacking trait 将小字段打包到一个槽中（规则 9）。

BoundedInt 规则：

• 将 BoundedInt 类型用作函数输入和输出——绝不在每次调用时向下转型（规则 10）。
• 批量将 felt252 转换为 BoundedInt 时，使用 u128s_from_felt252 + upcast（规则 12）。
• 始终使用 python3 {skill_dir}/scripts/bounded_int_calc.py 计算边界——绝不手动计算。
• 对 bounded_int_div_rem 中的负被除数，始终使用 SHIFT 模式：SHIFT = ceil(|min_possible_value| / modulus) * modulus，然后对 value + SHIFT 取模。

每次优化后，运行 snforge test 和 python3 {skill_dir}/scripts/profile.py profile，以验证改进效果。

第 4 轮 — 验证。 完成所有优化后：

• 运行完整测试套件：snforge test（所有测试都必须通过）。
• 汇总优化前后的热点指标，并在 PR 描述中注明步骤数变化。
• 建议后续步骤：对改动涉及的文件运行 cairo-auditor，并更新评测用例（contract_skill_benchmark.jsonl、contract_skill_generation_eval.jsonl），以确保收益得以保留。

完整执行清单请参阅 workflows/default.md。

starknet.js 示例

import { Account, Contract, RpcProvider } from "starknet";

const provider = new RpcProvider({ nodeUrl: process.env.STARKNET_RPC! });
const account = new Account(provider, process.env.ACCOUNT_ADDRESS!, process.env.PRIVATE_KEY!);
const contract = new Contract(abi, process.env.CONTRACT_ADDRESS!, provider).connect(account);

try {
  const before = await contract.call("hot_path_steps", []);
  const tx = await contract.invoke("apply_optimized_path", []);
  await provider.waitForTransaction(tx.transaction_hash);
  const after = await contract.call("hot_path_steps", []);
  console.log({ before, after });
} catch (err) {
  console.error("optimization check failed", err);
}

错误代码与恢复方法

代码	条件	恢复方法
OPT-001	优化前的基线测试失败	停止优化工作，修复失败的测试，然后重新运行基线剖析。
OPT-002	缺少剖析产物（trace/pb.gz）	使用正确的 --mode/--package 重新运行 profile.py，并确认工具可用。
OPT-003	BoundedInt 边界无效或不安全	使用 bounded_int_calc.py 重新计算边界；拒绝手动设置的边界并重新运行测试。
OPT-004	更改后的剖析结果退步	回滚更改，仅隔离一种优化类别，并使用相同输入重新测量。

安全关键规则

以下规则不可妥协。应用的每项优化都必须满足：

1. 每项优化前后测试均须通过。绝不优化未经测试的代码。
2. 每次提交只包含一种优化类别。绝不混合无关更改。
3. BoundedInt 边界必须通过 CLI 工具计算——绝不手动计算。
4. 每次更改后都要重新剖析，以确认有可测量的改进。
5. 必须遵守反模式／优化模式对——绝不编写反模式。

参考资料

• 优化规则和 BoundedInt：legacy-full.md
• 性能分析 CLI 和故障排查：profiling.md
• 优化反模式对：anti-pattern-pairs.md
• 跨技能交接格式：../references/skill-handoff.md
• 模块索引：references/README.md

工作流

• 主要优化流程：默认工作流
• 合并前的强制流程：optimization → auditor（也可以在 auditor 之前，将 optimization → testing 作为可选的回归强化流程）。