这是一个用于排查应用 HTTP API 接口响应缓慢原因、并给出提速方案的性能测试技能。其默认模式是在预热后以单用户、逐请求方式测量，而不是压力测试。所有结论都要求有证据：每个结论都标注为“实测”（附证据）或“根据代码推断”，两者不得混用。
【用途】 测量单用户端点速度，找出耗时集中在哪一层，并对修复方案排序。安装 Grafana 相关技能（promql、loki、tempo、k6、pyroscope、performance-rca）后，Grafana 工作会委托给这些技能；写查询前应加载对应查询语言的技能，而不是猜测语法。
【按仓库维护的文件】 该技能是通用的，每个应用在 <repo>/.claude/perf/ 下维护自己的事实文件：
- app-context.md：技术栈、启动方式、base URL、环境判定、认证、服务名、数据源 UID、生产日志来源、种子数据命令、已知发现。
- grafana-queries.md：已针对该应用真实指标、标签和服务名校验过的 gcx 命令。
- endpoints.json：measure_endpoints.py 的默认端点列表。
- gcx-env.sh：可选包装脚本，从 .env 中读取凭据传给 gcx。 报告输出到 <repo>/.perf-reports/（被 gitignore 忽略），与种子脚本的 seed-manifest.json 相邻。
【主要流程】
- 加载上下文并检测环境。读取 .claude/perf/app-context.md，按其中记录的方法判定模式并在运行开始时说明。本地模式（笔记本）走完整流程，包括种子数据、经用户同意的临时埋点、轻量并发检查和实际修复；生产模式（VPS 或判定不清时）只做只读调查：允许单用户 GET 小样本测量（3 次预热 + 5 次测量）、gcx 读操作、app-context.md 中列出的 VPS 日志来源（只读、限时，如 --since、tail -n、grep -m）、通过只读客户端执行 EXPLAIN（绝不用 EXPLAIN ANALYZE）；不允许负载或并发测试、写请求、改配置/日志级别/代码、重启、临时埋点、种子数据。修复方案只提出不实施，写入报告由笔记本端执行。永不打印日志中的密钥或个人数据。
- 准备数据（仅本地模式）。检查 seed-manifest.json 与当前行数；数据库为空、过小或规模不符时，询问是否用 app-context.md 中的命令重新播种（每次运行确认一次），并在报告中记录规模与种子，只比较同规模同种子的运行。生产模式绝不播种。
- 查找端点。从代码列出路由（方法、路径、处理文件），以 endpoints.json 为起点补充新增项，填写路径参数：本地用清单中的已知 ID，对典型记录和重记录分别测量（慢点常藏在重记录里）；生产用只读方式从 Grafana 或日志取得 ID，或向用户询问。展示列表让用户缩小范围。
- 客户端侧测量。运行 measure_endpoints.py，记录每个请求的 DNS、连接、TLS、TTFB、下载和总耗时，以及 p50/p95/max、大小、状态码和每个端点的 UTC 时间窗口；对 TTFB p50 >200ms 标中、>500ms 标高、>1000ms 标危急。无 --allow-writes 时拒绝非 GET/HEAD/OPTIONS 请求，且该参数仅接受本地主机。生产中用 --warmup 3 --samples 5，并通过 --cookie-env VAR 传入会话（由用户设置变量，绝不回显）。
- 分层拆分时间。按优先级取证：客户端计时（DNS/连接/TLS 属网络；TTFB 与总耗时差距大且响应体大指向载荷或序列化）；链路（tempo 技能，按子跨度类型汇总 DB、HTTP 客户端、缓存等耗时，余量为处理程序自身代码，每请求 DB 跨度多且近似说明 N+1）；指标（promql 技能：按路由的请求时长、DB 时间、连接池等待、CPU、GC）；性能剖析（performance-rca 或 pyroscope，处理程序时间占主导时定位热点函数）；日志（loki 技能：访问日志时长、慢查询、超时与重试）；VPS 专属日志。无遥测时按代码阅读请求路径（路由→中间件→服务→数据访问→外部调用→序列化），并 EXPLAIN 查询。本地允许临时查询日志，但须还原并列入报告。
- 查找原因与修复。依据 bottleneck-checklist.md 检查 N+1、缺失索引、顺序独立调用、缺缓存、过度取数与大载荷、连接池上限、CPU 密集代码、阻塞 I/O 等。每个修复写明文件与行号、代码草图、预估收益（如“21 次查询→1 次，约 −150ms”）和工作量（S/M/L）。
- 编写报告。输出 .perf-reports/<YYYY-MM-DD-HHMM>-report.md 并附原始 JSON：头部含模式（本地模式含数据规模与种子）；摘要列前 3 项收益；端点表含方法、路径、记录类型、p50、p95、主导层、严重度（每个实测端点都有 p95）；每个发现按影响/投入排序，含证据（实测或推断）→原因→修复（文件路径）→预期收益→工作量；列出已做并还原的临时改动。
- 可选检查（本地模式，按需）。前后对比：同规模同种子修复后重测。规模测试：1× 播种测量，10× 重播再测，按增长排序端点（10 倍数据下约慢 10 倍说明工作量与表大小成正比，如缺索引、无分页、N+1；大致持平则正常）。轻量并发：用 k6 按 1→5→10 用户找连接池或锁上限。类生产资源：在 app-context.md 指定的 Compose override 下运行，把 CPU 和内存限制到 VPS 规格。
【安全约束】 默认只读方法：GET/HEAD/OPTIONS 无需许可；POST/PUT/PATCH/DELETE 会改数据，每次运行需询问，仅限本地或开发环境、仅测试数据，绝不用于生产；被要求对生产做写基准测试时拒绝该部分，改为本地种子数据。默认单用户速度：负载测试需明确请求并确认本地目标，绝不对生产加压。播种仅限本地且会清空数据，播种器须在环境为本地、DB 主机为本地且传入显式清空标志时才允许。Grafana 只读：仅用 gcx query、label、list、help 命令，绝不用 resources、api、alert、login、datasources create/update/delete 或任何自适应子命令。输出不含密钥：不打印 .env 值或会话 cookie，报告中掩码令牌，运行时从环境读凭据。完成前还原临时改动（日志标志、计时代码）并列出。