CodeBurn 性能迭代日志（perf/ITERATION-LOG.md）实战解读：从 Phase 0 基线到可复现的性能回归防线

【免费下载链接】codeburnFree, local tool to track AI coding token usage and cost across 37 tools and agents (Claude Code, Cursor, Codex, Gemini and more), by model, project, and task. npx codeburn项目地址https://gitcode.com/gh_mirrors/co/codeburn点击查看免费下载本文以 CodeBurn 仓库中的 perf/ITERATION-LOG.md 为核心骨架结合同目录下的 perf/README.md、perf/BASELINES.md 以及scripts/perf/下的真实实现源码完整解读 CodeBurn 的性能度量体系如何用一条命令复现每个指标、如何用合成语料在隔离环境中测量冷启动/解析/周期切换/内存等 wait-path 延迟以及开发者如何按照Measure → change → measure的迭代契约持续压测并把结果追加进迭代日志。读完本文你将能够亲手复现 Phase 0 全部基线、读懂并追加一行合格的迭代记录。一、迭代日志在 CodeBurn 性能工程中的定位perf/ITERATION-LOG.md是整个性能治理体系的账本它是一份**只能追加append-only**的表格每行代表一次针对单一指标的优化尝试记录日期、分支/PR、指标、改动前后数值、判定结果kept/reverted与机制说明。当前仓库中它只有一条记录Datebranch/PRmetricbefore → afterverdictmechanism2026-08-29perf/harness-phase0harness (all)n/a → pinnedkeptPhase 0 harness synthetic fixture; no product change这条记录本身就是一个重要的工程信号性能优化的第一步不是改代码而是先把量尺钉死。perf/harness-phase0分支所做的全部工作就是搭建测量框架与合成语料、把基线数值固化进 perf/BASELINES.md不包含任何产品改动no product change。在 CodeBurn 的性能方法论里没有 before/after 数字的迭代不存在——这正是 perf/BASELINES.md 开头那句规则的由来An iteration without a before/after number from this harness does not exist.迭代日志是这条规则的落地点一行合格的记录必须同时携带改动前后的数值、复现命令、所属 fixture 以及判定结论让任何一位敌意审查者都能用一条命令重新跑出同样的数字。二、性能框架总览Measure → change → measureperf/README.md 用一句话概括了整个 perf 目录的设计哲学Measure → change → measure. This directory is the hill: one command per metric, pinned baselines, and an append-only iteration log.翻译成工程语言就是三条约束一个指标一条命令每个性能指标都有对应的run-metric.mjs --metric name入口杜绝手写脚本各测各的导致的不可复现。基线必须固化Phase 0 的基线被人工粘贴进perf/BASELINES.md任何一次迭代都必须与这张表比对。迭代日志只追加每次尝试要么留下kept的改进记录要么留下reverted的失败记录从不改写历史。这套框架是对 #1164 引入的 release-acceptance 证据体系的扩展性能 harness 沿用其timings.csv模板与 wait-path 数字形状但不取代scripts/release-acceptance/run.mjs作为 SHA/包级发布门禁的地位。两者的分工是release-acceptance 负责这个制品对不对perf harness 负责这个制品快不快。被明确划定的边界迭代日志机制还明确列出了性能框架禁止触碰的产品文件因为这些表面正处于在途或刚落地的高质量工作PR 1159–1171、open #1149/#1062/#940src/parser.tssrc/session-cache.tssrc/dashboard.tsxapp/electron/main.tsapp/electron/cli.tsmac/Sources/CodeBurnMenubar/**这条禁令保证了性能分支永远从干净的产品代码出发测量结果不会被半成品的质量改动污染。三、Phase 0 度量矩阵六个指标各测什么、不测什么perf/README.md给出了六个核心指标的完整定义。这张表的关键价值在于同时声明了每个数字是什么和不是什么——这是性能测量中最容易造假、也最需要纪律的部分Metric命令这个数字是什么它不是什么Cold start (wait-path)run-metric.mjs --metric cold-start-cli一次性status --format menubar-jsonargvDesktop/Menu Bar 已经会 spawn 的进程的完整返回耗时安装版窗口展示 / 菜单栏火焰动画Session parse--metric session-parse冷解析合成语料输出 MB/s 与毫秒大型真实语料Incremental re-parse--metric incremental-reparse在同一 inode 上追加两行 JSONL 后重新运行重写 / inode 变更Period switch--metric period-switch热serve --stdio下 7D/30D 的 p50/p95安装版 Desktop 在真实语料上的 250ms p95Dock/TUI interactions--metric dock-tui-proxyOverview 刷新与视图切换的 wait pathCapacity Dock hover原生、从不 spawn 该 argv或 TTY TUI 按键Memory--metric memory冷加载后的 RSS可选--idle-ms 3600000打包应用 RSS从源码看这些指标的参数解析位于 scripts/perf/run-metric.mjs合法指标集合被硬编码为session-parse、incremental-reparse、period-switch、cold-start-cli、dock-tui-proxy、memory与all传入非法值会直接以退出码 2 拒绝执行。命令行还支持--trials-cold默认 3、--trials-warm默认 5、--idle-ms默认 0等调参项其中冷/热试验次数与 release-acceptance 的三次冷、五次暖观测纪律保持一致。关于那个 18 秒的历史数字perf/README.md特别记录了一段历史收据而非当前可复现基线安装版 Desktop 0.9.21、真实语料、2026-08-27 测量空闲 30 秒后的 7D 有用摘要耗时18286.98 ms而规范目标是250 ms p95的就绪摘要、未变化代际零原始读取。README 明确警告该数字来自一次未发布的安装版审计属于历史上下文无法从本仓库重新推导——读者不应把安装版指标与 harness 的 wait-path 数字混为一谈。四、一条命令复现全部基线perf/README.md给出了两条命令的一键复现流程HOME_DIR$(mktemp -d /tmp/codeburn-perf-XXXX) node scripts/perf/gen-fixture.mjs --home $HOME_DIR --target-mb 30 node scripts/perf/run-metric.mjs --metric all --home $HOME_DIR等价写法是 npm 脚本形式见 package.jsonnpm run perf:all -- --home $HOME_DIR相关 npm 脚本还有npm run perf:fixture→node scripts/perf/gen-fixture.mjsnpm run perf:metric→node scripts/perf/run-metric.mjsnpm run perf:all→node scripts/perf/run-metric.mjs --metric all流程要点生成合成语料gen-fixture.mjs在隔离 HOME 下生成约 30MB 的合成会话语料默认--target-mb 30--seed默认0x9e3779b9保证确定性--force可覆盖已存在的同名 fixture。跑全部指标run-metric.mjs --metric all会依次执行六个指标并把summary.json、每个指标的明细 JSON 以及timings.csv写入perf/results/run-id/目录。固化新阶段基线把本次运行的summary.json数字人工粘贴进 perf/BASELINES.md。基线固化每个阶段只做一次不需要脚本参与。fixture 的合成语料严格使用假路径/work/api-gateway等与 lorem 工具负载生成字节只存在于被 gitignore 的隔离 HOME 下README 明令不要把真实会话文件复制进仓库或 PR。五、隔离机制绝不污染真实 HOME性能测量最怕环境串味。perf/README.md说明隔离规则与scripts/upgrade-path/run.mjs的cliEnv()一致而 scripts/perf/lib.mjs 给出了具体实现构造隔离环境时只透传PATH、PATHEXT、SystemRoot、ComSpec、windir、TEMP、TMP、NUMBER_OF_PROCESSORS、NODE_PATH等必要变量其余全部指向隔离 HOMEHOME/USERPROFILE→ 隔离目录CODEBURN_CACHE_DIR→home/.cache/codeburnAPPDATA/LOCALAPPDATA/XDG_CONFIG_HOME/XDG_DATA_HOME/XDG_CACHE_HOME→ 隔离目录下的对应子路径TZUTC固定时区CODEBURN_PRICING_SNAPSHOT_ONLY1与CODEBURN_FX_NO_FETCH1关闭网络依赖更硬核的是 lib.mjs 的assertIsolatedHome它会把目标目录与真实主目录含homedir()、userInfo().homedir、$HOME的解析结果逐一比对一旦发现目标位于真实主目录之下直接抛错拒绝生成。这条防线有测试背书——tests/perf-harness-phase0.test.ts 专门验证了拒绝把合成 fixture 写到真实主目录下另一个用例则验证生成结果同时包含.claude/projects与.codex/sessions两类混合事件类型、且清单中不出现真实用户路径。六、迭代契约一行合格日志的完整生命周期perf/README.md 定义了五步迭代契约这正是追加一行ITERATION-LOG.md记录前的完整动作序列Attack one baseline row一次只针对BASELINES.md中的一行基线发起进攻不贪多。Branchperf/metric-short-namefrom current main分支名本身携带指标名与短名例如perf/session-parse-early-exit。One change一个分支只做一处改动确保 before/after 差异可以归因。Measure with this harness用 harness 测量产出 before/after 数字。Draft PR with before, after, command, fixturePR 必须携带改动前后数值、复现命令与 fixture 说明并且永远不要从这条性能分支合并产品代码。完成验证后最后一步才是向 perf/ITERATION-LOG.md 追加一行记录标记kept或reverted。也就是说日志本身是契约的收尾动作而不是开始——它存在的意义是让每一次性能尝试都留下可审计的证据链。七、Phase 0 基线全表当前可以复现的数字perf/BASELINES.md 固化了 Phase 0 的全部基线测量环境为 Mac15,14arm64、Node v22.22.3、CLI 入口tsx src/cli.ts、SHA93b7b9a7da02ee77c80ac54264b87358121c5cf7metricfixture命令numbernotessession-parse cold (ms p50/p95)gen-fixture.mjs --target-mb 30--metric session-parse1768.0 / 1791.0MB/s p5015.091fixture_bytes27977201incremental-reparse (ms)30MB fixture 追加 2 行 JSONL--metric incremental-reparse463.0同一 inode 追加日常路径period-switch first 7D after load (ms)30MB fixture viaserve --stdio--metric period-switch120.9index-ready 首 7D18s 收据的模拟对应物period-switch first 30D after load (ms)同上同上166.3index-ready 首 30Dwait-pathperiod-switch 7D warm (ms p50/p95)同上同上0.4 / 0.6安装版 UI 目标仍为 250ms p95period-switch 30D warm (ms p50/p95)同上同上0.3 / 0.5wait-pathserve ready (ms)30MB fixture同上399.3{ready:true}帧cold-start desktop wait-path (ms p50/p95)30MB fixture--metric cold-start-cli1651.4 / 1729.5status menubar-json --period today --no-timelineUI 未验证cold-start menubar wait-path (ms p50/p95)30MB fixture同上1510.4 / 1526.0--provider all --period today --no-optimizeUI 未验证refresh proxy (ms p95)30MB fixture--metric dock-tui-proxy211.4hover 是原生 dock这里是 payload 复用view-switch proxy (ms p95)30MB fixture同上121.3week 请求侧栏绘制未验证memory RSS after cold load (bytes)30MB fixture--metric memory366460928本次未跑 1h idle需--idle-ms 3600000表中有几处值得注意的工程细节冷启动基线分 Desktop/Menu Bar 两条它们使用不同的 argvlib.mjs 中DESKTOP_OVERVIEW_ARGS为status --format menubar-json --period today --no-timelineMENUBAR_STATUS_ARGS为status --format menubar-json --provider all --period today --no-optimize分别模拟两种表面实际 spawn 的进程。period-switch 的 warm 数字0.4/0.6ms与 first 数字120.9/166.3ms差距悬殊这正是 CodeBurn 缓存体系的设计意图——索引就绪后周期切换几乎零成本而首次 7D/30D才是真实等待路径。所有数字都标注了 UI NOT VERIFIED / wait-path only基线明确声明这些是 CLI/serve 的 wait-path 测量不是安装版 Desktop/Menu Bar 的界面证明。任何引用这些数字的人都不应越界宣称UI 已达标。八、源码级实现六个指标在代码里如何被测量run-metric.mjs的六个 runner 各有独立的测量逻辑理解它们有助于你在追加迭代记录时准确引用机制一栏session-parserun-metric.mjs每轮试验先emptyCache清空缓存再以FULL_CORPUS_ARGS--period all一次性运行 CLI记录总耗时并换算 MB/s输出PERF-PARSE-001行。incremental-reparserun-metric.mjs先热加载一次再通过appendClaudeDelta向perf-00000.jsonl在同一 inode上追加一 user 一 assistant 两行 JSONL含 tool_use 与 usage 字段随后重跑并记录增量耗时与追加字节数。period-switchrun-metric.mjsspawnserve --stdio进程等待{ready:true}帧ServeClient在 lib.mjs 实现 JSONL 行协议先做一次全语料加载再依次请求首次 7D、首次 30D最后跑 5 轮 warm 试验统计 p50/p95并顺带用ps -o rss采集进程 RSS。cold-start-clirun-metric.mjs交替测量 Desktop 与 Menubar 两种 argv每轮先清缓存属于纯冷启动 wait-path。dock-tui-proxyrun-metric.mjs用ServeClient热复用以DESKTOP_OVERVIEW_ARGS模拟 overview.refresh、以 week 周期请求模拟视图切换注释明确不测 Capacity Dock hover因为那是原生 quota UI、从不 spawn 该 argv为它造一个数字就是作秀。memoryrun-metric.mjs冷加载后立即测 RSS若传入--idle-ms则等待指定毫秒后再测一次用于泄漏检查。最终所有行都会汇入timings.csv列头定义在 lib.mjs包含run_id、surface、operation、cache_state、first_feedback_ms、complete_ms等字段与 release-acceptance 的时序模板完全同构可以被同一套审查工具消费。九、与 release-acceptance 证据体系的衔接perf/README.md 明确指出这套 harness 是 docs/release-acceptance/README.md#1164的延伸而非替代release-acceptance 的scripts/release-acceptance/run.mjs依然是 SHA/包级门禁而 perf harness 只负责把 session parse、incremental re-parse、period switch、CLI cold start 等 wait-path 数字以timings.csv模板形态输出。release-acceptance 文档docs/release-acceptance/README.md也反向引用了scripts/perf/与perf/README.md两套体系互为补充一个管正确性证据一个管性能证据。十、总结与实战清单CodeBurn 的perf/ITERATION-LOG.md不是一个孤立的表格而是整个性能治理闭环的对外凭证。把这个体系用于你自己的性能工作可以提炼出四条可迁移的方法论先固测量再谈优化没有 Phase 0 harness 和 pinned baseline 之前一切性能讨论都缺乏锚点Phase 0 记录n/a → pinned的价值不亚于任何一次真正的优化。数字必须附带边界声明每个指标都要写清楚测了什么与没测什么wait-path vs 安装版 UI、合成语料 vs 真实语料防止数字被误用为产品级 SLA。隔离环境是可信度的前提assertIsolatedHome这类硬校验配合测试用例让绝不污染真实数据从口号变成机器强制。迭代日志是纪律的载体一个分支一个改动、一次只攻击一行基线、append-only 记录 before/after保证任何一次回归都可以被一条命令重新证伪。如果你要在 CodeBurn 仓库中实践这套流程完整路径是通读 perf/README.md → 对照 perf/BASELINES.md 选择攻击目标 → 运行npm run perf:fixture与npm run perf:metric或perf:all复现基线 → 按迭代契约完成一轮Measure → change → measure→ 把结果追加到 perf/ITERATION-LOG.md。当前日志中perf/harness-phase0那一行正是这套体系为后续所有性能迭代铺好的第一块基石。赞分享【免费下载链接】codeburnFree, local tool to track AI coding token usage and cost across 37 tools and agents (Claude Code, Cursor, Codex, Gemini and more), by model, project, and task. npx codeburn项目地址https://gitcode.com/gh_mirrors/co/codeburn点击查看免费下载相关推荐Banana Slides蕉幻后端架构与开发指南Flask Gemini 驱动的 AI PPT 生成服务Banana Slides蕉幻后端架构与开发指南Flask Gemini 驱动的 AI PPT 生成服务 导读 本文是 backend/README.AI Agent 策略引擎性能回归防线基于 Criterion 与基线对比的 ACS Core 性能回归测试指南AI Agent 策略引擎性能回归防线基于 Criterion 与基线对比的 ACS Core 性能回归测试指南 导读 本指南围绕 policy engine人工智能AI AgentAI 安全治理策略引擎Agent 沙箱认证鉴权海尔智能家居集成Haier的开发者指南如何贡献代码海尔智能家居集成Haier的开发者指南如何贡献代码 海尔智能家居集成Haier项目是一个允许用户将海尔智能家居设备接入HomeAssistant的开源项目。本智能家居物联网创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考