企业官网建设流程全解析

• 可观测性

本篇技术指南围绕 analyzer.md 展开，深入剖析 Sentry JavaScript SDK 仓库中 skill-creator 技能开发闭环里的一环——Post-hoc Analyzer（事后分析器）。它承担两项职责：在盲测比较判定胜负之后"解盲"结果、拆解胜因与败因并生成可落地的技能改进建议；以及在多轮基准测试运行后挖掘聚合指标无法直接显现的模式与异常。读完本文，你将掌握 analyzer 的输入参数、分步分析流程、结构化 JSON 输出设计、建议分类与优先级体系，以及它与仓库内 grader、comparator、聚合脚本和 JSON Schema 之间的完整协作关系，能够在自己搭建的 Agent 技能评估流水线中复现这套方法论。

1. 定位：analyzer 在 skill-creator 闭环中的角色

在 skill-creator/SKILL.md 定义的"起草 → 测试 → 评审 → 改进 → 重复"循环中，analyzer 是结果解读层的关键子代理。SKILL.md 的评估流程分四步：

1. 每个测试用例并行启动 with-skill 与 baseline 两个子代理（新建技能时 baseline 为无技能；改进既有技能时 baseline 为旧版本快照）；
2. 运行期间起草可量化断言（assertions）；
3. 运行完成后由 grader 子代理按 grader.md 对每条断言打分；
4. 运行聚合脚本生成 benchmark 数据，随后"Do an analyst pass"—— 即由 analyzer 阅读基准数据，挖掘聚合统计可能掩盖的模式（见 SKILL.md 中 "Step 4: Grade, aggregate, and launch the viewer" 一节）。

此外，SKILL.md 的 "Advanced: Blind comparison" 一节描述了更严格的对比场景：当用户问"新版本真的更好吗"时，先由 comparator.md 中定义的盲比较器对 A/B 两份输出打分且不知道各自出自哪个技能，再由 analyzer 解开结果、分析胜负原因。analyzer.md 正是这两个场景的共用"解读者"。

从源码结构看，analyzer 文档位于.agents/skills/skill-creator/agents/目录，与 grader.md、comparator.md 并列，配套的脚本（scripts/aggregate_benchmark.py、scripts/run_eval.py、scripts/run_loop.py等）和 Schema 文档（references/schemas.md）共同构成完整的评估工具链。analyzer 自身不直接执行评测，而是消费评测产物（比较结果 JSON、执行转录、benchmark.json）并产出两类分析成果：针对单次盲测的analysis.json，以及针对多轮基准的笔记数组。

2. 双模角色：Post-hoc Analyzer 与 Benchmark Analyzer

analyzer.md 定义了同一文件的两种分析模式，二者目的不同，不能混用：

Post-hoc 模式的输入参数含义如下：

• winner：盲比较判定的胜方标识 "A" 或 "B"；
• winner_skill_path / loser_skill_path：产出胜方/败方输出的技能路径；
• winner_transcript_path / loser_transcript_path：双方执行的转录（markdown）路径；
• comparison_result_path：盲比较器输出的 JSON 路径；
• output_path：分析结果保存位置。

Benchmark 模式则只关心benchmark_data_path（进行中的 benchmark.json，含全部运行结果）、skill_path（被基准测试的技能）与output_path（笔记保存路径）。

3. Post-hoc Analyzer：盲测胜因的八步拆解法

3.1 八步分析流程

Post-hoc Analyzer 按顺序执行以下 8 个步骤：

Step 1: Read Comparison Result—— 读取comparison_result_path处的盲比较输出，记录胜方（A/B）、比较器的推理过程与评分，明确比较器在胜方输出中看重了什么。

Step 2: Read Both Skills—— 读取双方技能的SKILL.md及关键引用文件，识别结构性差异，重点对比四个方面：

• 指令的清晰度与具体性（instructions clarity and specificity）；
• 脚本/工具的使用模式（script/tool usage patterns）；
• 示例覆盖度（example coverage）；
• 边界情况处理（edge case handling）。

Step 3: Read Both Transcripts—— 读取双方执行转录，对比执行模式：

• 双方对技能指令的遵循程度；
• 工具使用的差异；
• 败方在何处偏离了最优行为；
• 双方是否遇到错误并做出恢复尝试。

Step 4: Analyze Instruction Following—— 逐转录评估：是否遵循了技能的显式指令？是否使用了技能提供的工具/脚本？是否存在错过的利用技能内容的机会？是否添加了技能之外的多余步骤？最终为指令遵循度打出1-10 分并记录具体问题。

Step 5: Identify Winner Strengths—— 确定赢家胜出的原因，可能来自更清晰的指令、更好的脚本/工具、更全面的示例或更好的错误处理指导。文档要求具体化：凡相关之处直接引用技能与转录原文。

Step 6: Identify Loser Weaknesses—— 确定拖累败方的原因，可能来自歧义指令导致的次优选择、缺失工具/脚本被迫绕行、边界情况覆盖缺口、或导致失败的错误处理缺陷。

Step 7: Generate Improvement Suggestions—— 基于分析产出针对败方技能的可执行建议（而非笼统建议）：具体指令修改、要新增/修改的工具脚本、要补充的示例、要处理的边界情况。按影响力排序，优先聚焦那些足以改变本轮胜负的改动。

Step 8: Write Analysis Results—— 将结构化分析保存到{output_path}。

3.2 输出格式：analysis.json 完整结构

Step 8 产出的 JSON 结构（与 references/schemas.md 中analysis.json的定义一致）：

{ "comparison_summary": { "winner": "A", "winner_skill": "path/to/winner/skill", "loser_skill": "path/to/loser/skill", "comparator_reasoning": "Brief summary of why comparator chose winner" }, "winner_strengths": [ "Clear step-by-step instructions for handling multi-page documents", "Included validation script that caught formatting errors", "Explicit guidance on fallback behavior when OCR fails" ], "loser_weaknesses": [ "Vague instruction 'process the document appropriately' led to inconsistent behavior", "No script for validation, agent had to improvise and made errors", "No guidance on OCR failure, agent gave up instead of trying alternatives" ], "instruction_following": { "winner": { "score": 9, "issues": ["Minor: skipped optional logging step"] }, "loser": { "score": 6, "issues": [ "Did not use the skill's formatting template", "Invented own approach instead of following step 3", "Missed the 'always validate output' instruction" ] } }, "improvement_suggestions": [ { "priority": "high", "category": "instructions", "suggestion": "Replace 'process the document appropriately' with explicit steps: 1) Extract text, 2) Identify sections, 3) Format per template", "expected_impact": "Would eliminate ambiguity that caused inconsistent behavior" }, { "priority": "high", "category": "tools", "suggestion": "Add validate_output.py script similar to winner skill's validation approach", "expected_impact": "Would catch formatting errors before final output" }, { "priority": "medium", "category": "error_handling", "suggestion": "Add fallback instructions: 'If OCR fails, try: 1) different resolution, 2) image preprocessing, 3) manual extraction'", "expected_impact": "Would prevent early failure on difficult documents" } ], "transcript_insights": { "winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script -> Fixed 2 issues -> Produced output", "loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods -> No validation -> Output had errors" } }

关键字段语义：comparison_summary记录比较概要；winner_strengths/loser_weaknesses为逐条优势/弱点（要求引用具体证据）；instruction_following为双方的 1-10 分指令遵循度评分及问题清单；improvement_suggestions是带priority、category、suggestion、expected_impact四元组的建议列表；transcript_insights用一步到位的执行链路概览总结双方行为模式。

3.3 建议分类体系

改进建议必须归入以下六类之一，便于后续按类别批量处理：

3.4 优先级级别

每条建议按预期影响力标注三级优先级：

• high：很可能改变本次比较的胜负；
• medium：会提升质量但不一定改变输赢；
• low：锦上添花，边际改进。

3.5 分析原则

analyzer.md 给出了六条硬性原则，约束分析质量：

• Be specific：引用技能与转录原文，不能只说"指令不清晰"；
• Be actionable：建议应是具体改动而非含糊意见；
• Focus on skill improvements：目标是改进失败技能，而非批评 agent；
• Prioritize by impact：哪些改动最可能改变结果；
• Consider causation：需要判断技能弱点是否真的导致了更差输出，还是仅属巧合（incidental）；
• Stay objective：只分析发生了什么，不做主观发挥；
• Think about generalization：该改进是否也能惠及其他 eval。

4. Benchmark Analyzer：跨运行的模式与异常挖掘

4.1 角色定位

分析基准测试结果时，analyzer 的职责从"建议技能改进"切换为在多轮运行中表面化模式与异常。关键区别在于：聚合指标（如平均通过率）无法单独呈现的规律，正是此处要挖掘的对象。此模式禁止提出技能改进建议（那属于改进环节而非基准环节），也禁止做出主观质量判断（"输出好/坏"）和无证据的因果推测。

4.2 六步流程

Step 1: Read Benchmark Data—— 读取包含全部运行结果的 benchmark.json，记录被测试的配置（with_skill/without_skill），理解已计算的run_summary聚合值。

Step 2: Analyze Per-Assertion Patterns—— 对每个期望（expectation）跨所有运行分类，这是本模式最有价值的产出。每类模式对应的解读为：

• always pass in both configurations（两配置恒通过）：可能无法区分技能价值（non-differentiating）；
• always fail in both configurations（两配置恒失败）：可能已损坏或超出能力范围；
• always pass with skill but fail without（带技能恒通过、无技能恒失败）：技能在此断言上明确增值；
• always fail with skill but pass without（带技能恒失败、无技能恒通过）：技能可能在起反作用；
• highly variable（高度波动）：可能是 flaky 期望或非确定性行为。

Step 3: Analyze Cross-Eval Patterns—— 跨 eval 寻找规律：某些 eval 类型是否一贯更难/更易？某些 eval 是否高方差而其他稳定？是否存在与预期相悖的意外结果？

Step 4: Analyze Metrics Patterns—— 观察time_seconds、tokens、tool_calls：技能是否显著增加执行时间？资源使用是否有高方差？是否存在扭曲聚合的离群运行？

Step 5: Generate Notes—— 以字符串列表形式输出自由文本观察，每条笔记需满足三条要求：陈述一个具体观察；基于数据而非推测；帮助用户理解聚合指标无法展示的信息。

Step 6: Write Notes—— 将笔记以 JSON 字符串数组保存到{output_path}。

4.3 输出格式与示例笔记

[ "Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value", "Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure", "Without-skill runs consistently fail on table extraction expectations", "Skill adds 13s average execution time but improves pass rate by 50%" ]

文档给出的更多笔记示例还包括："Token usage is 80% higher with skill, primarily due to script output parsing"、"All 3 without-skill runs for eval 1 produced empty output" 等。这些示例展示了如何把聚合值翻译成可操作的信号：例如某断言 100% 恒通过意味着它在区分技能价值上无效，应被视为评估设计的信号而非好消息。

4.4 DO 与 DO NOT

• DO：报告数据中观察到的现象；明确指出涉及哪些 eval、期望或运行；记录聚合指标会隐藏的模式；提供有助于解读数字的上下文。
• DO NOT：向技能提出改进建议；做主观质量判断；无证据推测原因；重复run_summary聚合中已有的信息。

5. 与仓库脚本和 Schema 的衔接：数据从哪来、结果往哪去

5.1 benchmark.json 的生成：aggregate_benchmark.py

Benchmark Analyzer 的输入benchmark_data_path指向的 benchmark.json，由 aggregate_benchmark.py 生成。该脚本支持两种目录布局：

# Workspace layout（skill-creator 迭代产出） <benchmark_dir>/ └── eval-N/ ├── with_skill/ │ ├── run-1/grading.json │ └── run-2/grading.json └── without_skill/ ├── run-1/grading.json └── run-2/grading.json # Legacy layout（带 runs/ 子目录） <benchmark_dir>/ └── runs/ └── eval-N/ ├── with_skill/run-1/grading.json └── without_skill/run-1/grading.json

脚本从每个 run 目录的grading.json读取summary.pass_rate、timing（优先取 grading.json 内嵌的 timing，回退到同级timing.json的total_duration_seconds与total_tokens）以及execution_metrics等字段，动态发现配置目录名（而非硬编码with_skill/without_skill），因此也支持new_skill/old_skill这类改进场景的配置命名。关键实现细节位于 aggregate_benchmark.py：aggregate_results()用样本标准差公式（n>1 时除以 n-1）计算 mean/stddev/min/max，再对前两个配置计算 delta 字符串（如+0.50、+13.0、+1700）。

值得注意的是，aggregate_benchmark.py 生成的 benchmark.json 中notes字段初始为空数组，注释明确写着"To be filled by analyzer"—— 这正是 Benchmark Analyzer 在 Step 5/6 中的填充目标。同时 SKILL.md 提示：如果手工生成 benchmark.json，必须严格参照 references/schemas.md 中定义的字段名（configuration而非config，pass_rate必须嵌套在result下），否则 viewer 会显示空值——analyzer 的笔记同样依赖这份精确契约。

5.2 analysis.json 的 Schema 契约

Post-hoc Analyzer 的输出在 references/schemas.md 中有独立小节（analysis.json），其字段结构与 analyzer.md 中 Step 8 的 JSON 完全对齐：comparison_summary、winner_strengths、loser_weaknesses、instruction_following、improvement_suggestions、transcript_insights。这保证了分析结果可被下游工具确定性解析。

5.3 与 comparator、grader 的协作链路

• 上游：盲比较结果由 comparator.md 定义。盲比较器在不知道输出出自哪个技能的前提下，用内容维度（Correctness / Completeness / Accuracy）与结构维度（Organization / Formatting / Usability）的双向 1-5 分制 Rubric 打分，先按 Rubric 总分、再按断言通过率判定winner（"A"/"B"/"TIE"），写入comparison-N.json（保存于<grading-dir>/）。analyzer 读取的comparison_result_path即此文件。
• 旁证：grader 在 grader.md 中定义了严格的 PASS/FAIL 标准——PASS 要求证据反映真实任务完成而非表面合规（"文件存在且内容正确，而不仅仅是文件名正确"），FAIL 包括证据矛盾、无法验证、表面合规等情形，且"不确定时举证责任在期望本身"。analyzer 在 Step 4 评估指令遵循度时，转录中 grader 已标注的证据可直接复用。

5.4 触发评估脚本对"分析输入"的启发

虽然 analyzer 不直接参与描述触发优化，但 run_eval.py 展示了同仓库中"基于流事件早停"的评估技术（通过--include-partial-messages监听content_block_start中的tool_use事件判断技能是否被触发），以及 run_loop.py 按should_trigger分层抽样的 train/test 划分。理解这些脚本有助于把 analyzer 的"模式挖掘"思路延伸到触发评估的失败样本上（例如 should-not-trigger 误触发的近邻查询模式），但需注意 analyzer 文档本身限定其分析对象为执行结果与转录。

6. 实战应用建议

在 skill-creator 工作流中调用 analyzer 的时机与姿势：

• 盲测后必跑 Post-hoc 分析：当用户质疑"新版本真的更好吗"并启动 comparator 盲测后，应立即以 comparation 结果 JSON 为输入运行 Post-hoc 分析。SKILL.md 明确指出该流程"可选、需要子代理、多数用户不需要"，常规人工评审循环通常足够，但一旦启用，analyzer 的胜因拆解能给出比"赢/输"更可执行的结论。
• 每轮迭代做 analyst pass：SKILL.md 的 Step 4 要求每轮迭代在聚合 benchmark 之后进行 analyst pass，特别关注"无论技能如何恒通过的断言（非区分性）""高方差 eval（可能 flaky）"以及"时间/token 权衡"。这些正是 analyzer.md 中 Benchmark 模式的核心输出。
• 区分两种分析的口径：Post-hoc 模式可以对技能提出改进建议，Benchmark 模式严禁越界——两者输出格式不同（对象 vs 字符串数组），保存路径语义也不同（<grading-dir>/analysis.jsonvs 笔记数组文件）。
• 改进落地参考 SKILL.md 的迭代循环：analyzer 产出的improvement_suggestions应回流到 SKILL.md 描述的改进步骤（"Apply your improvements to the skill → Rerun all test cases into a new iteration → 用--previous-workspace启动下一轮评审"），形成"测试 → 盲比/基准 → 分析 → 改进 → 再测试"的闭环。改进时遵循 SKILL.md 的原则：优先将重复出现的手写辅助脚本收编进技能的scripts/目录（"如果 3 个测试用例都各自写了一个 create_docx.py，技能就该内置这个脚本"），并避免用僵硬的全大写 MUST 指令压制模型的判断力，转而解释指令背后的"为什么"。

7. 小结

analyzer.md 定义了技能评估流水线中最具"解释力"的一环：Post-hoc Analyzer 把盲测的二元胜负拆解为可归因的胜因/败因清单和按优先级排布的建议列表，Benchmark Analyzer 则把多轮运行的聚合数字还原为可行动的异常信号。二者共享同一套纪律——具体、可执行、聚焦技能而非指责 agent、以因果而非巧合判断改动价值。结合仓库中的 aggregate_benchmark.py 数据管线、grader.md 的证据标准、comparator.md 的盲测 Rubric 以及 schemas.md 的字段契约，这套分析设计可以直接迁移到任何基于 Agent 技能的质量度量与迭代改进系统中。

• 可观测性