★ FEATURED ARTICLE 【免费下载链接】xerjXERJ is the new way for AI to search data. Its autoindex capability activates agents to know your data without the token waste of grep and sed. One command indexes code, docs, logs and PDFs for search, RAG, security audits and agent memory, using 40x fewer tokens than grep. Elasticsearch compatible, so existing clients just work.项目地址https://gitcode.com/GitHub_Trending/xe/xerj点击查看免费下载XERJ 仓库中的 PROMPT_CPU.md 是一份面向 AI Agent 的「CPU 性能剖析分析提示词CPU profile analysis prompt」它把一次受控实验下的 CPU pprof 产物审查从「凭感觉猜热点」升级为「必须基于可复现证据链下结论」的标准化流程。本文以该文档为核心逐条展开其 7 步报告要求与 CONFIRMED / LIKELY / UNKNOWN 三级结论规则并结合 capture.py、inspect.py、debug_profiling.rs 等仓库源码说明这些要求背后的工具链与实现依据。读完本文你将掌握如何审查一份 XERJ CPU profile 清单、如何把采样热点追溯到源码函数、如何设计最小化验证实验以及为什么「仅凭采样百分比不能断言吞吐与耗时因果」。一、这份提示词解决什么问题XERJ 的调试剖析工具链demo/playbooks/debug-profiling/README.md在受控实验下产出两类 pprof 产物cpu.pb进程在采样窗口内把 CPU 时间花在了哪些调用栈上heap.pb.gzjmemalloc 在捕获结束时刻保留的存活字节归属于哪些分配调用栈。PROMPT_CPU.md 专门规范前者。它的核心立场是一份 CPU profile 本身只能证明「采样到了哪些热点栈」不能证明「某个优化真的赢了」。因此它要求分析者先读取完整证据输入再按固定清单输出结论并在证据缺失时主动标注INCONCLUSIVE。整份提示词实际定义了一个可被机器检查的审查契约输入4 类、报告7 项、结论3 级 1 个禁用态。二、输入侧分析前必须完成的四项准备提示词第 25 行规定Agent 在动手分析前必须依次处理四类输入完整读取manifest.json这是整个审查的证据锚点。由 capture.py 生成schema 为xerj.debug_profile.v1记录二进制 SHA-256、完整启动命令、Git 修订与脏状态、主机形态、捕获参数、退出状态与各产物哈希。manifest 在进程启动前即写入初始status: running运行结束后原地更新为complete/profile_failed/process_failed并补充 artifacts 清单。用pprof -top、-tree与聚焦的-list视图检查cpu.pb三种视图各回答一个问题——top 给出扁平样本排行tree 给出累计调用链归属list 针对单个热点函数展开行级样本分布。读取 manifest 中标定的 Git 修订对应的精确源码注意 manifest 中source_build_binding固定为UNVERIFIED——wrapper 无法证明二进制确实由该次 checkout 构建源码↔二进制的绑定只能靠独立 attestation 升级为已验证。读取 benchmark 的正确性与吞吐输出这是把采样热点与「实际变快」关联起来的必要条件。没有正确性数据快但错了的改动就是回归。这四类输入与提示词第 14 行的要求核对哈希、捕获时长/频率、二进制哈希、声明的修订/构建、命令、主机、进程是否正常终止一一对应构成了「先核证据、后谈性能」的顺序纪律。三、7 步报告清单逐条解析提示词第 1221 行规定了报告的 7 项内容下面逐条说明其意图与落地方式。1. 证据核验第 14 行确认产物哈希、捕获时长与频率、二进制哈希、声明的修订与构建、启动命令、主机形态以及进程是否正常终止。结合源码看这些字段都来自 manifestcapture.py 写入binary_sha256、capturecpu_seconds/heap_seconds/cpu_hz/delay_seconds、experiment、host与sourcegit_head、git_status、tracked_diff_sha256运行结束后再写入exit_code与terminated_after_capture_window。关键纪律只要 source/build 绑定未被独立证实就一律按UNVERIFIED对待——declared_build_unverified字段明确标记 profile/features 是操作者声明而非从二进制中提取。2. Top 15 扁平与累计栈第 15 行同时列出 flat 与 cumulative 两个维度、样本数与百分比。这一条在提示词层面只是「列出」但其设计意图可从 PROMPT_COMPARE.md 的反面教训读出只看百分比会把「无关工作整体变大」误读成「某函数变好」因此绝对样本数samples与占比必须同时呈现。3. 按成本类别分组第 16 行把成本归入PDF 抽取、tokenization/embedding、HTTP/JSON、索引、flush/merge、分配器/同步、存储 I/O以及未知。这一分组直接映射 XERJ 的管道形态——从 xerj-server 的 crate 依赖xerj-engine、xerj-vector、xerj-ai、xerj-storage 等可以看出一次查询/摄取请求会横跨解析、嵌入、检索、落盘多个阶段分类账目式的分组能让「热点到底在哪一段」一目了然。注意提示词刻意保留unknown桶无法归类的栈必须显式存在而不是被含糊塞进别的类别。4. 热点栈溯源第 17 行把每个主要栈追溯到源码文件与函数并明确标注哪些是推断inference。这是「证据 vs 猜测」的分界线manifest 中source_build_binding: UNVERIFIED意味着即使哈希全对栈到函数的映射也可能因构建不确定性而失真因此提示词要求分析者诚实声明推断成分。5. 并行瓶颈诊断第 18 行找出并行度瓶颈、lock/futex 等待、重复的解析/拷贝以及单线程阶段。这些症状在采样栈上有典型信号futex/锁等待表现为大量样本落在同步原语上重复解析/拷贝表现为同一文档在多个栈中反复出现单线程阶段表现为捕获窗口内样本集中在一个工作线程的栈上。此类诊断正是「热点 → 瓶颈 → 最小实验」链条的中间环节。6. 三个最小可证伪实验第 19 行针对疑似瓶颈推荐三个最小的、能证伪该假设的实验。这是本提示词最有方法论价值的一条不做「再跑一次全量语料」式的大实验而是用最小干预直接攻击假设。比如怀疑 PDF 抽取重复解析就构造一个只含单个 PDF 的小语料、只测抽取路径怀疑 flush/merge 锁竞争就固定并发度对比开关 flush 的两次运行。与 PROMPT_HEAP.md 第 6 条「在再次跑全量语料前先用确定性小语料复现每个主导 owner」的设计同构——都是先小后大、先证伪后推广。7. 因果性禁区第 20 行不得仅凭采样百分比断言耗时或吞吐的因果。这是整份文档的底线条款采样百分比只描述「CPU 时间分布」与「墙钟时间变短」「每秒文档数变多」之间隔着并发、IO 重叠、调度等因素不能直接画等号。这一条与 README.md 的公平 A/B 协议语料、工作负载、并发、捕获时长、CPU 频率、构建 profile、feature 集、机器、缓存状态全部保持一致先验证正确性再比速度相互印证。四、结论分级CONFIRMED / LIKELY / UNKNOWN 与 INCONCLUSIVE 禁用态提示词第 2224 行定义了输出收尾的强制结构CONFIRMED有完整证据链支撑的结论哈希核对通过、源码映射明确、有正确性与吞吐数据佐证LIKELY证据支持但有推断成分例如依赖UNVERIFIED绑定或缺少某类遥测UNKNOWN证据不足、无法归类的部分INCONCLUSIVE禁用态当正确性、工作负载结果或可比遥测未随附时任何性能结论都必须整体标注为INCONCLUSIVE。提示词的原话是「一个 CPU profile 单独只能识别被采样的热点栈不能代表一个被验证过的优化收益」。这条规则在工具链中同样被强制inspect.py 会扫描--attach进清单的附件标签若没有任何含 result/correct/bench/telemetry 字样的证据就在摘要中输出警告「性能结论必须为 INCONCLUSIVE」。也就是说工具从机制上阻止了「只有 profile、没有正确性数据」的分析被当作有效结论——这正是该提示词想内化的工程纪律。五、底层实现这份规范所约束的剖析机制了解规范约束的对象才能理解为何要求如此苛刻。剖析机制的实现位于 debug_profiling.rs仅在debug-profilingfeature 下编译普通构建不包含任何剖析器、不开放任何调试 HTTP 端点Cargo.toml 注释明确说明该 feature 被排除在所有发布 feature 集之外因为 jemalloc profiling 会改变分配器快路径、pprof 会安装 SIGPROF。5.1 配置即环境变量剖析完全由环境变量驱动debug_profiling.rs环境变量语义取值范围 / 默认值XERJ_DEBUG_PROFILE_DIR产物输出目录必须已存在必填触发剖析XERJ_DEBUG_CPU_SECONDSCPU 采样时长1300 秒XERJ_DEBUG_HEAP_SECONDS堆采样时长1300 秒XERJ_DEBUG_CPU_HZCPU 采样频率11000 Hz默认 100 HzXERJ_DEBUG_PROFILE_DELAY_SECONDS进程启动后的延迟0300 秒默认 0CPU 与堆至少配置其一否则启动报错。配置解析在Config::parse中完成越界值直接拒绝启动——对应 test_tooling.py 中configuration_requires_a_bounded_capture所验证的行为非法配置导致服务启动失败而不是静默地不产生产物。5.2 启动时机delay0 即初始化剖析剖析在 main.rs 中于配置加载、TLS、引擎回放与路由构建之前启动注释明确说明「delay0 是真正的初始化剖析」。这意味着如果你把 delay 设为 0采样窗口会覆盖启动阶段若只想剖析稳态工作负载则用--delay-seconds给出同步窗口——注意 README 强调该延迟是相对进程启动的同步窗口不是就绪探测。5.3 CPU 采样机制与已知限制CPU 采样基于SIGPROF libgcc 栈展开debug_profiling.rsblocklist 屏蔽 libc/libgcc/pthread/vdso 以降低噪声。README 明确提醒pprof-rs 上游文档记载了信号安全限制因此这套工具只用于受控调试构建不是常驻生产剖析器。这也是 PROMPT_CPU.md 要求核对「捕获频率」的原因之一——采样率是解读样本数的前提。5.4 产物安全与原子发布产物以 0600 权限创建、原子发布、永不复写debug_profiling.rs先写临时文件并sync_all再用hard_link发布改名会覆盖既有产物目录级锁.xerj-debug-profile.lock拒绝并发控制器。单元测试atomic_publication_never_overwrites_evidence验证了二次写入失败且首份内容保持原样。捕获失败时写出cpu-error.json/heap-error.json结构化错误。操作要点若目录残留 stale 锁需先确认没有 XERJ 进程占用该目录再删除且仅删除该锁文件——控制器在正常与受控关闭时都会自行移除锁。六、配合工具链从捕获到清单校验再到分析PROMPT_CPU.md 假定的「受控实验产物」由两段脚本支撑捕获阶段capture.pypython3 demo/playbooks/debug-profiling/capture.py \ --output /tmp/xerj-profile-before \ --cpu-seconds 30 --heap-seconds 30 --delay-seconds 5 \ --workload financebench-fb20-v1 \ --corpus financebench-20-sha256-example \ --concurrency 4 --cache-state cold \ --build-features debug-profiling,onnx-experimental \ --build-profile profiling \ --attach correctness/tmp/fb20-correctness.json \ --attach telemetry/tmp/fb20-memory.ndjson \ -- \ engine/target/profiling/xerj --data-dir /tmp/xerj-profile-data要点输出目录必须不存在--cpu-seconds/--heap-seconds至少一个在 1300--stop-after必须给捕获结束外加 5 秒的发布窗口转换与原子发布发生在采样停止之后精确对齐边界的终止会被拒绝--attach LABELPATH可重复使用把正确性、吞吐、RSS、jemalloc 与 XERJ 遥测文件复制进清单并哈希——没有这些附件分析提示词就要求INCONCLUSIVE。wrapper 以start_new_sessionTrue启动整个服务进程组并在超时后先 SIGTERM、再 SIGKILL 兜底。校验阶段inspect.pypython3 demo/playbooks/debug-profiling/inspect.py /tmp/xerj-profile-before该校验器核对每个产物的 SHA-256、附件哈希、heap.pb.gz是否为合法 gzip、cpu.pb是否为空并输出机器可读摘要valid、capture_status、source_build_binding、declared_build_unverified、experiment、attached_evidence与comparison_ready标志。返回码 0/1 对应通过/失败——test_tooling.py 的test_missing_requested_profile_is_machine_readable_failure验证了缺失产物时清单为profile_failed、inspect 返回 1。七、构建侧纪律三种 profile 的正确用法提示词第 14 行要求核对「声明的构建」而构建 profile 的选择直接决定剖析质量相关配置在 engine/Cargo.tomlprofile优化设置用途与注意profiling继承 releasedebug1、stripfalse、ltothin、codegen-units16快速迭代编辑-剖析-再编辑循环。不等价于生产代码生成不得与 release 结果直接比较profiling-final继承 releaseopt-level3、ltofat、codegen-units1且保留符号最终确认发布性能声明前的复测必须用它releasestriptrue、panicabort禁止用于剖析剥离符号后堆地址几乎无法解析因此一个合规的发布级性能声明路径是先用profiling发现热点快速、符号完整再用同 profile 的profiling-finalA/B 复测确认——PROMPT_COMPARE.md 明确要求「用快速 profiling 发现的热点或收益只是临时性的须经 profiling-final 确认后方可作出生产代码生成的性能声明」。README 还强调cargo build --no-default-features --features debug-profiling,onnx-experimental的构建方式保证剖析 feature 不污染默认发布二进制。八、把提示词当作可审计的审查契约使用PROMPT_CPU.md 的价值不在「让 LLM 看一份 profile」而在于它把一次性能审查拆解成可逐项勾选、可机器校验的契约四类输入缺一不可——尤其正确性/工作负载输出缺失即INCONCLUSIVE7 项报告从证据核验、Top 15 栈、成本分组、源码溯源、并行诊断到最小实验层层递进杜绝「只报热点不验证收益」结论强制以 CONFIRMED / LIKELY / UNKNOWN 收尾并把未经验证的断言显式隔离与 PROMPT_HEAP.md堆保留字节账目与 RSS 拆分和 PROMPT_COMPARE.md正确性优先的 A/B 对照配合使用可覆盖「CPU 在哪、内存在哪、改动后赢没赢」的完整审查闭环。实际使用时建议把这份 prompt 原样作为 Agent 的任务说明书传入同时附上manifest.json与校验器输出的摘要 JSONAgent 的答复应能逐条映射到本文第二、三节的清单条目。若清单缺少正确性/遥测附件Agent 应主动给出INCONCLUSIVE而非继续编造结论——这正是这份规范最想内化的工程习惯采样热点可以指向怀疑但只有带正确性护栏的可复现实验才能宣告优化成立。赞分享【免费下载链接】xerjXERJ is the new way for AI to search data. Its autoindex capability activates agents to know your data without the token waste of grep and sed. One command indexes code, docs, logs and PDFs for search, RAG, security audits and agent memory, using 40x fewer tokens than grep. Elasticsearch compatible, so existing clients just work.项目地址https://gitcode.com/GitHub_Trending/xe/xerj点击查看免费下载相关推荐XERJ 调试剖析实战用 pprof 做有界、本地、可审计的 CPU 与内存剖析XERJ 调试剖析实战用 pprof 做有界、本地、可审计的 CPU 与内存剖析 本文基于 XERJ 仓库中的 debug profiling recipeEnvoy 性能剖析实战指南基于 gperftools、pprof 与 Perfetto 的 CPU / 内存分析方法论Envoy 性能剖析实战指南基于 gperftools、pprof 与 Perfetto 的 CPU / 内存分析方法论 本指南系统讲解如何在 Envoy 云云原生服务网格网络微服务Easydict 中基于 Agent Skill 的 PR 审查报告结构规范与实现解析Easydict 中基于 Agent Skill 的 PR 审查报告结构规范与实现解析 导读 PR 审查报告是代码评审中信息密度最高、也最容易变得冗长难读的产物桌面应用AI 应用上一篇Python Machine Learning 深度解析均值中心化与特征缩放对 PCA 主成分分析的影响下一篇ArduPilot高精度定位架构深度解析RTK与传感器融合的工程实践指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
