printing-press-output-review

printing-press-output-review（内部）

检查打印版 CLI 的抽样输出，找出那些 dogfood、verify 和基于规则的 scorecard --live-check 检查无法发现的可信度问题。Wave B 策略：所有发现均作为警告呈现，绝不作为错误。

此技能仅供内部使用（user-invocable: false）。它由上级调用——主 printing-press 技能在 shipcheck 的第 4.85 阶段调用，printing-press-polish 技能则在其诊断循环中调用。单独运行此技能只会产生没有 ship 判定、没有修复、也没有发布选项的零散发现文本；可执行操作的包装入口为 /printing-press 和 /printing-press-polish。此技能设置了 context: fork，以隔离审查 Agent 的诊断交流，避免其进入调用技能的上下文。

输入

调用方将 $CLI_DIR 作为参数传入：打印版 CLI 工作目录的绝对路径。

此技能可发现的问题

基于规则的检查无法发现的问题，通常需要 5 分钟的实际测试才能发现，但可能逃过 dogfood、verify 和 scorecard --live-check 规则：

• 子串匹配结果碰巧包含查询内容，但语义上并不匹配（例如，查询匹配了一个更大的无关词语中的子串）
• 聚合命令在请求的 N 项中只有部分返回时，悄无声息地丢弃某些来源
• 排名或排序命令返回的前 N 项结果在合理性上并非该查询的最佳结果（权重错误、提取器回退）
• 输出中的 URL 指向类别索引页面、订阅源端点或随机选择路由，而非规范内容永久链接
• 基于规则的检查无法发现的格式问题（乱码、复数形式不一致、单元格内容截断或换行）

流程

第 1 步：收集样本数据

# Locate research.json. Adjacent to the binary covers the post-promote
# layout (standalone polish, shipcheck against the library copy). The
# grandparent fallback covers mid-pipeline invocations where $CLI_DIR is
# $PRESS_RUNSTATE/runs/<id>/working/<cli> and research.json lives at
# $PRESS_RUNSTATE/runs/<id>/research.json. Without the fallback, scorecard
# reports `unable: true` mid-pipeline and we SKIP the most informative review.
# Use a bash array so the flag survives paths with spaces.
RESEARCH_ARGS=()
if [ ! -f "$CLI_DIR/research.json" ]; then
  _grandparent="$(dirname "$(dirname "$CLI_DIR")")"
  if [ -f "$_grandparent/research.json" ]; then
    RESEARCH_ARGS=(--research-dir "$_grandparent")
  fi
fi

cli-printing-press scorecard --dir "$CLI_DIR" "${RESEARCH_ARGS[@]}" --live-check --json > /tmp/output-review-livecheck.json 2>&1 || true

如果 scorecard 调用失败，或 /tmp/output-review-livecheck.json 为空，则返回 SKIP 结果（第 3 步），且不要调度审查 Agent。

调度前，如果存在 live_check.review_status 字段，请读取该字段。 如果其值为 skipped，或 live_check.features[] 中 status 为 pass 的条目数为零，则返回 SKIP，原因是 no eligible passing samples; plausibility not assessed。不要调度审查 Agent。跳过审查不代表通过：绝不要输出 status: PASS，也不要仅仅因为所有抽样命令都失败或被排除，就将结果描述为 审查无问题。

Step 2：派发审查 Agent

使用 Agent 工具（通用型），并采用以下提示词约定：

审查已发布 CLI 在 $CLI_DIR 中的抽样输出。以下是真实数据来源：

• 抽样命令输出：读取 /tmp/output-review-livecheck.json，并检查 live_check.features[] 数组。每个条目都包含命令、示例调用、已脱敏的 stdout 证据（位于 output_sample 中，限制在约 4 KiB）、已脱敏的通过／失败原因，以及 warnings 数组（由基于规则的检查填充，例如原始 HTML 实体检测器）。将 <redacted> 标记视为隐私脱敏值，而非格式错误。
• 仅审查 status: pass 的条目。 status: fail 的条目可能崩溃、超时，或使用了占位参数（<id>、<url>），因此未能产生真实输出——其样本为空，无需判断。
• $CLI_DIR/research.json 中的 novel_features（各功能的计划行为）和 novel_features_built（已验证构建的命令）。
• CLI 二进制文件 $CLI_DIR/<cli-name>-pp-cli——如需核实某项发现，你可以调用其他命令获取更多输出。

针对以下每项检查报告发现，每项不超过 50 个词。只报告人类用户在 5 分钟的实际操作中会注意到的问题——无需覆盖全面 QA 才会发现的每个边缘情况：

1. 输出在语义上符合查询意图。 对于带有查询参数的抽样新功能，判断结果是否相关，不要只依赖 live-check 已执行的机械式查询词检查。通过 live-check 的 outputMentionsQuery 测试，只代表输出中包含某个查询词——例如，“buttermilk”作为子字符串出现在“butter”的结果中，或者提取器回退到相邻内容，导致搜索“brownies”却返回辣椒食谱，这些情况都会通过机械检查。只有当人类用户看到顶部结果时会觉得“这不是我想要的”，才报告问题。示例不含查询参数时，跳过此项检查。
2. 没有明显的格式错误。 输出中是否包含原始 HTML 实体、乱码（标题中出现问号或替换字符），或格式错误的 URL（指向分类索引页、Feed 端点或随机选择路由，而非规范的内容永久链接）？基于规则的 live-check 会检测数字实体；此步骤用于检测更广泛的问题类型。
3. 聚合命令展示了所有请求的数据源。 对于带有 --source/--site/--region CSV 标志的命令：如果用户请求了 N 个数据源，输出是否展示了 N 个，或者 stderr 是否说明了缺少哪些数据源？静默丢弃失败的数据源是扇出命令中最常见的问题之一。
4. 结果顺序／排名合理。 对于声称会排名或排序的命令，顶部结果是否看起来与查询相符且排名合理？注意检查分数权重错误、排序差一位的错误，以及相关性计算失败后静默回退到按时间排序的情况。

learn-loop 命令样本（recall、learnings、playbook）的校准说明：在全新环境中，打印时本地学习存储为空，因此候选列表为空、learnings stats 计数为零，以及输出“未记录学习内容”都可能是正确表现。不要将它们报告为静默失败或数据缺失。

返回发现列表。每项包括：检查名称、严重性（Wave B 使用 warning；error 仅用于 Wave C）、单行描述，以及一句修复建议。如果 CLI 通过全部四项检查，则返回“PASS — no findings”。

第 3 步：输出结构化结果块

在技能响应末尾添加 ---OUTPUT-REVIEW-RESULT--- 块，供上级解析：

检查通过时：

仅当审查者评估了至少一个符合条件的 status: pass 样本时，才使用此结果。

---OUTPUT-REVIEW-RESULT---
status: PASS
findings: []
---END-OUTPUT-REVIEW-RESULT---

有警告时：

---OUTPUT-REVIEW-RESULT---
status: WARN
findings:
- check: <check-name>
  severity: warning
  description: <one-line>
  suggestion: <one-sentence>
- ...
---END-OUTPUT-REVIEW-RESULT---

审查失败或没有可评估的输出时（超时、Agent 预算耗尽、缺少实时检查数据、review_status: skipped，或符合条件的 status: pass 样本数为零）：

---OUTPUT-REVIEW-RESULT---
status: SKIP
reason: <one-line description>
findings: []
---END-OUTPUT-REVIEW-RESULT---

status: SKIP 不算通过。调用方必须将其报告为已跳过，且不得将其计为通过的审查。

Wave B 政策（当前）

• 所有发现均标记为 warning，绝不标记为 error。无论如何，Shipcheck 都会继续。
• 调用方会将发现记录到本次运行的产物目录（例如 manuscripts/<api>/<run>/proofs/phase-4.85-findings.md），并告知用户。发现不会持久化到 scorecard.json，该路径留待 Wave C 使用。
• 用户逐项决定发布前是否修复。

非交互式约定（CI、cron、批量重新生成）：

• 如果 stdout 不是 TTY，调用方会遵循“记录后放行”原则：记录发现，Shipcheck 继续运行，不提示用户。
• status: SKIP（审查者崩溃、超时、缺少数据）仅供参考，Shipcheck 不会因此阻塞。
• 目前没有 --auto-approve-warnings 标志。Wave B 的政策本就是“警告不阻塞”，因此该标志不会产生任何门控效果。

Wave C（单独的后续 PR）将在整个库的校准数据显示误报率低于 10% 后，将 error 级别的发现改为阻塞项。

为什么采用 Agent 式审查，而不是仅使用模板

输出是否合理的问题无法通过匹配源内容中的模式来判断。基于规则的实时检查规则可以覆盖正则表达式能检测的内容（数字 HTML 实体、查询词令牌缺失）。其他所有问题——“这些替换结果对于该查询来说是否合理？”、“排名靠前的搜索结果看起来相关吗？”——都属于大模型问题。令牌成本有上限（每次运行一次，而非每条命令一次），而且对于促使我们开展此阶段的错误类别，其检出率足以证明值得进行调度。

已知盲点

• 无法验证数值准确性（价格、评分、排名是否符合真实数据）。如果 CLI 显示某个食谱有 4.8 星，但实际上只有 4.2 星，此技能无法发现。
• 无法检测数据时效性问题（食谱发布于 2019 年而非 2024 年）。这需要与权威来源进行实时比对。
• 无法判断主观偏好（“这是不是最适合做巧克力曲奇的食谱？”）。
• 仅抽查输出——覆盖 live_check.features[] 中的命令。完整的命令树覆盖应由主 printing-press 技能的第 5 阶段试用负责，而非本次审查。
• 非英语输出：审查者的查询意图检查假设查询和输出均为英文。对于非英语 CLI，请单独校准提示词。