企业官网建设流程全解析

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.gz：jmemalloc 在捕获结束时刻保留的存活字节归属于哪些分配调用栈。

PROMPT_CPU.md 专门规范前者。它的核心立场是：一份 CPU profile 本身只能证明「采样到了哪些热点栈」，不能证明「某个优化真的赢了」。因此它要求分析者先读取完整证据输入，再按固定清单输出结论，并在证据缺失时主动标注INCONCLUSIVE。整份提示词实际定义了一个可被机器检查的审查契约：输入（4 类）、报告（7 项）、结论（3 级 + 1 个禁用态）。

二、输入侧：分析前必须完成的四项准备

提示词第 2～5 行规定，Agent 在动手分析前必须依次处理四类输入：

1. 完整读取manifest.json：这是整个审查的证据锚点。由 capture.py 生成，schema 为xerj.debug_profile.v1，记录二进制 SHA-256、完整启动命令、Git 修订与脏状态、主机形态、捕获参数、退出状态与各产物哈希。manifest 在进程启动前即写入（初始status: "running"），运行结束后原地更新为complete/profile_failed/process_failed并补充 artifacts 清单。
2. 用pprof -top、-tree与聚焦的-list视图检查cpu.pb：三种视图各回答一个问题——top 给出扁平样本排行，tree 给出累计调用链归属，list 针对单个热点函数展开行级样本分布。
3. 读取 manifest 中标定的 Git 修订对应的精确源码：注意 manifest 中source_build_binding固定为"UNVERIFIED"——wrapper 无法证明二进制确实由该次 checkout 构建，源码↔二进制的绑定只能靠独立 attestation 升级为已验证。
4. 读取 benchmark 的正确性与吞吐输出：这是把采样热点与「实际变快」关联起来的必要条件。没有正确性数据，快但错了的改动就是回归。

这四类输入与提示词第 14 行的要求（核对哈希、捕获时长/频率、二进制哈希、声明的修订/构建、命令、主机、进程是否正常终止）一一对应，构成了「先核证据、后谈性能」的顺序纪律。

三、7 步报告清单逐条解析

提示词第 12～21 行规定了报告的 7 项内容，下面逐条说明其意图与落地方式。

1. 证据核验（第 14 行）

确认产物哈希、捕获时长与频率、二进制哈希、声明的修订与构建、启动命令、主机形态，以及进程是否正常终止。结合源码看，这些字段都来自 manifest：capture.py 写入binary_sha256、capture（cpu_seconds/heap_seconds/cpu_hz/delay_seconds）、experiment、host与source（git_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 禁用态

提示词第 22～24 行定义了输出收尾的强制结构：

• 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）：

CPU 与堆至少配置其一，否则启动报错。配置解析在Config::parse中完成，越界值直接拒绝启动——对应 test_tooling.py 中configuration_requires_a_bounded_capture所验证的行为：非法配置导致服务启动失败，而不是静默地不产生产物。

5.2 启动时机：delay=0 即初始化剖析

剖析在 main.rs 中于配置加载、TLS、引擎回放与路由构建之前启动，注释明确说明「delay=0 是真正的初始化剖析」。这意味着如果你把 delay 设为 0，采样窗口会覆盖启动阶段；若只想剖析稳态工作负载，则用--delay-seconds给出同步窗口——注意 README 强调该延迟是相对进程启动的同步窗口，不是就绪探测。

5.3 CPU 采样机制与已知限制

CPU 采样基于SIGPROF+ libgcc 栈展开（debug_profiling.rs），blocklist 屏蔽 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.py）：

python3 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至少一个在 1～300；--stop-after必须给捕获结束外加 5 秒的发布窗口（转换与原子发布发生在采样停止之后，精确对齐边界的终止会被拒绝）；--attach LABEL=PATH可重复使用，把正确性、吞吐、RSS、jemalloc 与 XERJ 遥测文件复制进清单并哈希——没有这些附件，分析提示词就要求INCONCLUSIVE。wrapper 以start_new_session=True启动整个服务进程组并在超时后先 SIGTERM、再 SIGKILL 兜底。

校验阶段（inspect.py）：

python3 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.toml：

因此一个合规的发布级性能声明路径是：先用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」，而在于它把一次性能审查拆解成可逐项勾选、可机器校验的契约：

1. 四类输入缺一不可——尤其正确性/工作负载输出，缺失即INCONCLUSIVE；
2. 7 项报告从证据核验、Top 15 栈、成本分组、源码溯源、并行诊断到最小实验，层层递进，杜绝「只报热点不验证收益」；
3. 结论强制以 CONFIRMED / LIKELY / UNKNOWN 收尾，并把未经验证的断言显式隔离；
4. 与 PROMPT_HEAP.md（堆保留字节账目与 RSS 拆分）和 PROMPT_COMPARE.md（正确性优先的 A/B 对照）配合使用，可覆盖「CPU 在哪、内存在哪、改动后赢没赢」的完整审查闭环。

实际使用时，建议把这份 prompt 原样作为 Agent 的任务说明书传入，同时附上manifest.json与校验器输出的摘要 JSON；Agent 的答复应能逐条映射到本文第二、三节的清单条目。若清单缺少正确性/遥测附件，Agent 应主动给出INCONCLUSIVE而非继续编造结论——这正是这份规范最想内化的工程习惯：采样热点可以指向怀疑，但只有带正确性护栏的可复现实验才能宣告优化成立。