faster-code

name	faster-code
description	当代码运行缓慢、超时、被终止、消耗大量 CPU、执行长时间批处理作业、进行参数扫描、训练模型、处理大型数据集、运行模拟，或目标规模运行时间未知时，使用本技能。它指导智能体逐步探测运行时间，在可行时进行在线 N-T 进度插桩，采用固定超时采样，执行 N-T 扩展估算，并在尝试目标规模前作出全规模运行的通过/不通过决策。如果进行了优化，它要求保留慢速版本的规范输出，证明语义逐字节等价，并在通过并行投入更多 CPU 前优先消除无效工作。本技能不封装性能分析工具，也不提供通用优化方案；它负责判断应全规模运行、停止，还是转入性能分析和原则性优化。

faster-code

使用本技能改进计算密集型代码的运行方式：先判断目标规模能否在运行时间预算内完成，再决定是全规模运行、停止还是优化。不要一开始就让缓慢程序在长超时下运行。长超时只能证明浪费已经发生；短时有界探测可以更早提供决策信息。

核心目标

将“它能否在全规模下完成？”转化为运行前门禁：

1. 定义目标规模 N_full 和可接受的运行时间预算 T_budget。
2. 当程序具有自然工作计数器且源代码修改成本较低时，优先采用在线 N-T 进度插桩。
3. 使用短时超时、进度日志或输入切片构建 3–5 个有效 N-T 样本。
4. 使用多个简单模型估算目标规模运行时间。
5. 如果估算结果不可接受，不要全规模运行；转入性能分析、诊断或优化。

如果代码经过优化，应增加语义门禁：保留慢速版本的规范输出作为真值，然后要求快速版本在同一输入切片上生成逐字节相同的规范输出。如果浮点数差异是自然现象，应在写入规范输出前，按照预先声明的舍入或格式规则对数值进行规范化。为便于审计，可以牺牲有限精度，但最终比较仍必须逐字节进行。

优化有明确的优先顺序：先避免无效计算，再投入更多计算资源。减少不必要的工作通常优于用更多核心掩盖浪费。并行可能有用，但应作为靠后选项，仅在算法或工作负载削减不可用、风险过高或不足以满足运行时间预算时采用。

在线 N-T 优先

在选择切片批量运行前，先检查程序是否有自然进度计数器。许多慢速程序已经包含遍历行、文件、任务、参数组合、批次、epoch、窗口或请求的循环。如果存在这样的计数器，且编辑代码风险较低，应先加入在线 N-T 进度日志，再执行一次有界探测。

缺少进度日志应视为可修复的插桩缺口，而不是程序只能批量运行的证据。

以下条件全部满足时，加入在线采样：

• 存在单调递增的已处理工作计数器，或可以低成本计算；
• 该计数器能映射到选定的 N，或映射到有充分依据的组合 N；
• 可以每 5–10 秒或每个较粗粒度的工作间隔输出日志，且不会产生显著开销；
• 当前任务允许修改源代码，且修改不会改变计算语义；
• 程序可在超时终止前刷新日志。

以下任一条件满足时，不要加入在线采样：

• 唯一可用的计数器需要高成本同步、全局扫描或大幅增加内存；
• 日志会显著扰动被测工作负载；
• 当前任务无法安全编辑代码；
• 工作确实不可分割，也不会暴露有意义的局部进度。

插桩应保持最小化且便于解析。优先使用一种稳定的行格式：

PERF_PROGRESS processed=120000 total=1000000 elapsed_sec=31.2 rate=3846.1 unit=rows

对于嵌套工作，应明确记录组合 N，不要隐藏第二个规模变量：

PERF_PROGRESS processed=240000 total=2000000 elapsed_sec=31.2 unit=row_param_pairs rows=120000 params=2

如果在线插桩可行，应先实现插桩，再重复运行切片探测。如果不可行，应在报告的 instrumentation_decision 中说明原因。

程序分类

A. 进度可观察程序

如果程序能在运行时输出进度，或能以较低成本修改为输出进度，应优先执行一次短时超时探测，而不是多次切片运行。

有用的进度日志应稳定、低频且便于解析：

PERF_PROGRESS processed=120000 total=1000000 elapsed_sec=31.2 rate=3846.1

步骤：

1. 使用短时超时运行，通常为 30 秒。
2. 从日志中提取多个 elapsed_sec -> processed_N 数据点。
3. 如果已捕获进度日志，即使运行因超时被终止，也应将其视为有用样本。
4. 如果吞吐量随时间下降，应保守外推；不要从早期最快速率进行外推。

如果缺少进度日志，但满足在线 N-T 条件，应先加入日志，再执行重复切片运行。每 5–10 秒记录一次，而不是每处理一个元素就记录。

B. 仅批量程序

只有在线 N-T 插桩不可用、不安全或会扭曲测量结果时，才使用数据切片和重复的有界运行。

步骤：

1. 找出用于控制输入规模的参数，例如 --limit、日期范围、文件数量、采样比例、批次数量或参数数量。
2. 从较小的 N 开始，并按指数扩大，例如 1k、2k、4k、8k。
3. 当一次运行超时时，在上一个已完成的 N 和失败的 N 之间进行二分查找。
4. 使用二分查找构建可靠的 N-T 样本，而不是寻找精确的最大可行 N。
5. 不要浪费运行次数去命中精确秒数；目标是获得扩展趋势，而不是精确基准测试。

定义 N

外推前，先定义主要规模变量 N。不要假设 N 始终表示行数。

常见定义包括：

• 输入行数；
• 已处理的文件或对象；
• 生成的事件或任务；
• 参数组合；
• 工作进程、分片或独立单元；
• 训练窗口或批次；
• rows x parameter_combinations x files 等组合变量。

如果程序有多个主导规模变量，应使用最能解释工作量的组合变量。如果 N 无法代表全规模计算，应将结果标记为 INCONCLUSIVE。

采样要求

默认规则：

• 外推到全规模前，至少需要 3 个已完成样本点。
• 最好有 3–5 个已完成样本点。
• 除非样本不稳定，否则通常不需要超过 5 个点。
• 探测应从 30 秒超时开始。
• 除非用户明确接受其成本，否则单个探测节点应避免超过约 180 秒。

有用的时间区间：

• 30 秒节点：20–40 秒内完成的样本可接受。
• 60 秒节点：45–75 秒内完成的样本可接受。
• 120 秒节点：90–150 秒内完成的样本可接受。
• 180 秒节点：140–220 秒内完成的样本可接受。

超时样本表示 T(N) > timeout。拟合时不要把它当作 T(N) = timeout。

至少记录：

N:
runtime_sec:
status: completed | timeout | failed
timeout_sec:
command:
slice_method:
notes:

如果可以获取，还应记录峰值内存、CPU 利用率、输出大小和缓存状态。

外推方法

不要只使用一种估算。至少比较以下三种视角，并作出保守决策。

1. 线性外推

T_full = T_last * N_full / N_last

这是下界检查。如果连线性估算都超过预算，通常应停止。

2. 幂律拟合

T = a * N^p
log(T) = log(a) + p * log(N)

用它估算扩展指数 p。

默认解释：

• p <= 1.2：近似线性。
• 1.2 < p <= 1.6：需要谨慎；目标估算必须显著低于预算。
• 1.6 < p <= 2.2：高风险；通常应先优化或缩小范围。
• p > 2.2：除非 N_full 非常小，否则不要盲目全规模运行。

3. 局部斜率外推

只使用最大的两个或三个已完成 N 样本估算后期增长。这可发现小样本运行很快、但大样本性能下降的情况。

如果线性、幂律和局部斜率估算结果差异很大，应将结果标记为 INCONCLUSIVE 或 FAIL。不要使用最乐观的估算批准全规模运行。

通过/不通过决策

必须且只能返回以下一项：

PASS: 可以运行目标规模。
FAIL: 不要运行目标规模；应先诊断或优化。
INCONCLUSIVE: 证据不足或不稳定；暂时不要运行目标规模。

默认失败条件：

• 已完成样本点少于 3 个。
• N 不能代表主导计算。
• 线性外推已经超过 T_budget。
• 保守估算超过 T_budget 的 1.5 倍以上。
• 扩展指数明显差于线性，且 N_full 远超采样范围。
• 样本非单调或不稳定，且无法解释。
• 探测表明内存、输出大小或 I/O 可能成为瓶颈。

默认通过条件：

• 样本稳定。
• N 可信。
• 多种估算都低于 T_budget。
• 最大样本与 N_full 相距不远，或扩展趋势接近线性。

优化后的语义门禁

当任务从“能否完成？”转向“让它更快”时，应先保护慢速版本的语义。慢速版本虽然缓慢，但通常更清晰、更可信。没有语义检查的快速版本可能只是更快地产生了不同结果。

步骤：

1. 修改代码前，选择一个能够完成且覆盖关键路径的小型或中型样本。
2. 用慢速版本生成规范输出，并将其保存在快速版本无法覆盖的位置。
3. 定义规范字段、排序顺序、浮点数格式、时间戳格式、空值表示和随机性控制。
4. 如果存在浮点数，在写入规范输出前定义固定的舍入或格式规则，包括小数位数、科学记数法、NaN/Inf 表示和负零处理。
5. 使用相同输入、相同参数和相同环境假设，让快速版本生成候选规范输出。
6. 最终比较必须逐字节相同。
7. 不要用运行时容差比较取代规范化。容差只能体现在写入前的舍入或格式规则中。
8. 语义检查通过前，快速版本不得取代慢速版本，也不得用于支持全规模结论。

规范输出应小而稳定。只包含可证明语义等价的内容，例如：

• 最终指标和关键中间指标；
• 每个元素、任务或结果的核心输出；
• 排序后的 ID、时间戳、分数、状态、标签或决策；
• 必需的聚合校验和或汇总行。

不要使用巨大的临时文件作为规范输出。规范输出用于审计语义，而不是复制每项产物。

优化后的附加通过条件：

• 慢速版本的规范输出存在且已保留。
• 快速版本的候选规范输出存在。
• 逐字节比较通过。
• 运行时间采样表明，快速版本提高了目标规模的可行性，且没有新增无法解释的不稳定性。

优化后的附加失败条件：

• 不存在慢速版本的规范输出。
• 快速版本的规范输出未做到逐字节相同。
• 浮点数在写入规范输出前未经过规范化。
• 在看到差异后修改了舍入或格式规则。
• 只有聚合指标相近，但重要的逐元素输出发生偏移。

优化优先级

本技能不规定固定优化方案，因为工作负载各不相同。但它规定优化顺序：先节省算力，再缩短实际运行时间。

需要优化时，应优先选择减少总工作量的改动：

• 消除重复、冗余或未使用的计算；
• 避免不必要的扫描、连接、排序、转换、序列化、网络调用或磁盘 I/O；
• 只有在能减少净工作量，且不会造成数据陈旧或内存负担过重时，才缓存或预计算；
• 当采样、性能分析或代码检查表明存在可避免的增长时，改变数据结构或算法；
• 使用正确的过滤、提前退出、去重、批处理、剪枝或增量处理缩小工作负载。

只有在检查无效工作后，才使用并行。增加工作进程可以缩短耗时，但会增加 CPU 总用量、内存压力、I/O 争用和运营成本。以下情况适合采用并行：

• 剩余工作是必要且相互独立的；
• 算法或工作负载削减已用尽，或对当前任务风险过高；
• 瓶颈并非已经出现在内存、磁盘、网络、锁争用或速率限制上；
• 并行版本仍能通过语义等价验证和有界 N-T 采样。

不要把多进程、多线程、GPU、更大型机器或更多分片作为首选修复方案，除非证据表明工作已经是必要的、分区合理，且并非由浪费主导。

性能分析器指引

本技能不封装也不规定性能分析工具。但当门禁返回 FAIL 或 INCONCLUSIVE 时，特别是在复杂度高、吞吐量下降、怀疑存在内存瓶颈或样本不稳定的情况下，应告知用户使用适合项目和语言的现有性能分析器或热点审计工具。

性能分析器是下一阶段的输入，不能取代本门禁。性能分析应保持短时、受控且可复现：

• 分析能够稳定触发慢速路径的小型或中型样本。
• 设置明确超时，避免性能分析演变成另一次盲目的全规模运行。
• 捕获热点函数、热点行、调用次数、累计时间、分配压力或 I/O 等待。
• 如果没有规范输出，不要根据性能分析结果重写语义敏感代码。
• 优化后重新使用本技能：通过规范输出逐字节门禁，然后重复 N-T 采样和全规模通过/不通过决策。

报告格式

使用以下结构：

Performance Gate Result: PASS | FAIL | INCONCLUSIVE

Target:
- N_full:
- T_budget:
- command:
- N_definition:

Program Type:
- progress_observable | batch_only
- sampling_method:
- instrumentation_decision:

Samples:
| N | runtime_sec | status | timeout_sec | notes |

Scaling:
- linear_estimate:
- power_law_p:
- power_law_estimate:
- local_slope_estimate:
- conservative_estimate:

Canonical Check, if optimized code was created:
- slow_canonical:
- fast_candidate_canonical:
- compare_rule:
- compare_result:
- semantic_gate:

Decision:
- conclusion:
- reason:
- optimization_priority, if optimized:
- next_step:

非目标

本技能不会：

• 封装性能分析工具；
• 提供通用优化方案；
• 自动重写算法；
• 在检查无效工作前优先使用并行；
• 证明估算绝对精确；
• 在证据不足时鼓励全规模运行。

如果门禁失败，应建议进行性能分析、诊断、算法修改、进度日志记录、采用更好的切片策略或重新定义 N。不要开始长时间的目标规模运行。

操作规则

当用户要求全规模运行、检查某项工作是否会超时或让慢速代码更快时，应在长时间执行前使用本技能。将超时视为采样信号，而不是最终答案。目标是尽早获取决策信息，避免把算力浪费在本可预见的失败运行上。