pr-ship

概述

针对 OpenClaw 拉取请求（pull request）的预发布风险报告。

该技能会频繁更新，以同步 OpenClaw 的版本发布。版本特定上下文（易错点、行为变更、当前活跃风险区域）会在每次上游发布时刷新。请定期运行 clawhub update pr-ship 以获取最新上下文。

其功能包括：

• 将当前分支与 OpenClaw 仓库中的 main 分支进行差异比对。
• 基于代码库本身，使用 grep / find / git 等命令动态分析每个被修改的模块。
• 生成结构化风险报告，其中所有发现均附有证据支持，并按严重程度分级（🟢/🟡/🔴）。
• 不设“批准/拒绝”门禁——仅提供信息，供你在发布前自主判断需修复的内容。

参考层（Reference Layers）

从 references/ 目录加载以下文件。每份文件用途明确：

1. STABLE-PRINCIPLES.md —— 恒久有效的 OpenClaw 编码规范：测试指南、文件命名约定、安全不变式（safety invariants）、常见陷阱、PR 实践准则。

2. ARCHITECTURE-MAP.md —— OpenClaw 架构上下文：模块层级结构、带校准阈值的风险等级定义、关键路径模式、跨模块耦合关系、变更影响矩阵。

3. CURRENT-CONTEXT.md （可选） —— 版本特定的易错点、近期行为变更及当前活跃风险区域。若该文件存在，请务必加载。它反映当前 OpenClaw 发布版本的状态。

4. EXPLORATION-PLAYBOOK.md —— 动态调查流程文档。仅含只读命令（grep、find、ls、git），用于探测 OpenClaw 代码库当前状态。

5. VISION-GUIDELINES.md —— 项目愿景、贡献政策与合并防护机制（merge guardrails），源自 OpenClaw 的 VISION.md。涵盖 PR 范围规则、安全哲学、plugin/core 边界、skills 政策、MCP 策略，以及明确列出的“不予合并”类别（will not merge list）。用于识别策略或架构层面的偏差。

STABLE-PRINCIPLES、ARCHITECTURE-MAP、EXPLORATION-PLAYBOOK 和 VISION-GUIDELINES 文件必须始终存在。CURRENT-CONTEXT 为可选文件——若缺失，本技能仍可正常运行，但将无法感知版本特定的易错点。

工作流

1. 加载参考层

• 阅读上述四份参考文件。

2. 获取相对于 main 的差异内容

• 获取当前分支名：git branch --show-current
• 获取变更文件列表：git diff --name-only main...HEAD
• 获取补丁内容：git diff main...HEAD

3. 对变更模块进行分类

• 对每个变更文件，识别其所属的 src// 路径。
• 在 ARCHITECTURE-MAP.md 中查询该模块对应的风险等级（risk tier）。
• 若模块未在该文件中列出，或需进一步验证，请执行 EXPLORATION-PLAYBOOK.md 中 “Dynamic Risk Classification”（动态风险分类）章节所列的动态消费者数量统计命令。

4. 针对每个变更模块执行动态探索

• 对每个变更文件，遵循 EXPLORATION-PLAYBOOK.md 中 “Blast Radius Discovery”（爆炸半径发现）流程。
• 对每种变更模块类型，遵循 “Module-Specific Investigation Strategies”（模块特异性调查策略）。
• 遵循 “Test Discovery”（测试发现）流程，定位相关测试用例。
• 将差异内容与 “Red Flags Table”（风险信号表）进行比对。

5. 评估发现项

• 将动态探索所得证据与以下内容比对：
  • STABLE-PRINCIPLES.md 中的安全不变式与常见陷阱
  • CURRENT-CONTEXT.md 中的版本特定易错点（如已加载）
  • ARCHITECTURE-MAP.md 中的架构耦合模式
  • VISION-GUIDELINES.md 中的贡献政策、合并防护机制与架构演进方向
• 依据 Vision 贡献规则检查 PR 范围（单个 PR = 单一主题；尺寸限制；打包策略）。
• 检查是否匹配 VISION-GUIDELINES.md 第 7 节中定义的 “will not merge” 类别。
• 评估新增能力是否符合 plugin/core 边界划分及安全哲学。
• 每一项发现均须包含：
  • 差异证据（文件名 + 代码片段）
  • 探索证据（命令输出，展示爆炸半径、消费者数量或模式匹配结果）
  • 参考依据（明确指向所关联的具体原则、易错点或耦合模式）

6. 生成报告

• 采用下方指定的报告格式。
• 不得输出 “approved/rejected” 等判定结论。

严重程度与告警评分标准

• 🟢 低风险（评分 1–2） 细微观察、风格偏好或信息性提示。可不经修改直接发布。

• 🟡 需关注（评分 3–6） 部分不匹配、语义模糊、缺少加固措施或非阻断性不一致。值得审阅，但引发故障的可能性较低。

• 🔴 高风险（评分 7–10） 明显违反 OpenClaw 编码规范、架构模式或版本特定约束。极可能导致缺陷、回归问题或策略违规。

评分方式：

• 对每项发现独立评分（1–10 分）。
• final_alert_score = max(per_finding_scores)。若无任何发现，则 final_alert_score = 0。

报告格式

## pr-ship report

- Branch: ``
- Base: `main`
- Files changed: ``
- Modules touched: ``
- Findings: ``
- Final alert score: `<0-10>`

### Module Risk Summary

| Module | Risk Tier | Consumers | Files Changed |
| --- | --- | --- | --- |
|  | CRITICAL/HIGH/MEDIUM/LOW |  |  |

### Findings

1. 🟢/🟡/🔴 Title
   - Alert: `<1-10>`
   - Reference: ``
   - Evidence in diff: ``
   - Exploration evidence: ``
   - Why this matters: `<1-2 lines>`
   - Suggested fix: `<1-2 concrete actions>`

(repeat)

### Executive summary
- ``
- ``

约束条件

• 本技能**仅适用于 OpenClaw 仓库**，不可用于其他项目。
• 仅审查当前分支相对于 main 的差异内容。
• 不得审查与本次 PR 无关的仓库历史记录。
• 除非明确要求，否则不得自动编辑代码。
• 除非明确要求，否则不得将报告转化为“批准/拒绝”决策。
• 所有探索类命令均为只读操作（grep、find、ls、git diff）。严禁执行构建、测试或代码生成类命令；可在发现项中向用户推荐此类操作。

来源信息

• 源地址： github.com/Glucksberg/pr-ship
• 维护者： Markus Glucksberg (@Glucksberg)
• 更新机制： CURRENT-CONTEXT.md 元数据通过 cron 每日自动刷新——当 OpenClaw 上游 CHANGELOG.md 发生变更时触发。GitHub 仓库由维护者另行手动更新。
• 校验方式： GitHub 仓库为唯一可信源。验证本地安装副本是否一致的方法如下：

# 快速校验：比对文件列表与版本号
diff <(clawhub list | grep pr-ship) <(curl -s https://api.github.com/repos/Glucksberg/pr-ship/contents/package.json | jq -r '.content' | base64 -d | jq -r .version)

# 完整校验：逐文件比对本地安装与 GitHub 主干
SKILL_DIR="$(find ~/.openclaw/skills -maxdepth 1 -name pr-ship -type d 2>/dev/null || echo skills/pr-ship)"
for f in SKILL.md package.json references/CURRENT-CONTEXT.md; do
  diff <(cat "$SKILL_DIR/$f") <(curl -s "https://raw.githubusercontent.com/Glucksberg/pr-ship/main/$f") && echo "$f: ✔ match" || echo "$f: ✘ differs"
done

安全提示

本技能生成的报告可能包含来自你本地仓库的差异内容（diff）与 grep 输出。若你的配置文件、环境变量或代码中包含敏感信息（如 API 密钥、令牌、凭证等），这些值可能出现在报告中。在公开或共享报告前，请务必先行人工审查，确认不包含任何敏感数据。

致谢

原始 DEVELOPER-REFERENCE.md 格式与方法论借鉴自 mudrii 的开发者参考方法论。动态探索方法的设计，基于 OpenClaw 维护者社区的反馈意见。