OSS 贡献系统

一套面向开源仓库贡献的完整系统。四大能力构成一个学习闭环——每次贡献都会让下一次贡献更高效、更高质量。

快速上手

1. 首次使用？ 只需输入：oss discover

   • 系统将自动创建档案（profile），检查仓库是否对社区开放，并为你筛选高价值 issue。

2. 已找到一个 issue？ 输入：oss auto #12345

   • 端到端自动化流程：实现修复 → 提交 PR → 响应机器人评论 → 标记为 ready → @ 维护者。

3. 已有待处理的 PR？ 输入：oss check

   • 自动检查 CI 状态、机器人评论、PR 是否过期，并执行相应操作。

4. 需要高质量评审？ 输入：oss pr review #12345

   • 涵盖根因分析、diff 审查、PR 描述质量评估、机器人响应策略建议等维度。

系统工作原理

discover --> auto --> pr --> check --> retrospective
   ^                   ^       |              |
   |                   +-------+              |
   |              (人工评审循环)             |
   |                                          v
   |                              profile 持续成长（沉淀经验与模式）
   |                                          |
   +---- 检查归档历史 ------------------------+
         （避免重蹈覆辙）

档案（Profile）（./oss-pilot-data/profiles/.md）：存储仓库专属知识，包括构建命令、维护者风格、机器人行为、已验证的经验教训等。每次贡献后自动更新。结构定义详见 _template.md。

上下文文件（Context files）（./oss-pilot-data/context/pr--.md）：记录每个 PR 的解决思路、机器人交互决策及最终结果；合并或关闭后自动归档，供后续复盘参考。

四大核心能力

oss-discover（find.md）

发现高价值 issue，优先选择合并概率最高的任务。

• 评估仓库对外部贡献者的开放程度（外部贡献者 PR 合并率）
• 评估 issue 处理活跃度（issue 被认领的速度）
• 扫描 8 类高信号来源：高价值标签 → bug → CI 失败 → 可回收的 stale PR → 已合并未覆盖的模块缺口 → 特定模块合并率 → 代码库清理机会
• 验证 bug 是否仍存在、检查 issue 评论中的关键线索、评估修复可行性

详见：discover.md

oss-auto（auto.md）

一条命令，从 issue 直达已打开的 PR。协调调用 discover 与 pr 能力完成全流程。

• 冷启动支持：对新仓库自动创建初始 profile
• 执行完整流程：可行性判断 → 编码实现 → 提交 PR → 响应机器人 → 标记 ready → @ 维护者
• 自动识别构建工具链（Node/Python/Go/Rust/Make）
• 读取仓库中的 CONTRIBUTING.md 和 CLAUDE.md，适配项目约定规范

详见：auto.md

oss-pr（pr.md）

PR 质量守门员，在请求人工评审前完成关键校验。

• 根因分析（是否在正确层级修复？影响范围是否可控？是否违反语义契约？）
• 常见错误模式与反模式识别
• PR 描述需明确包含「哪些内容未改动」和「哪些内容尚未验证」
• 机器人响应策略（接受 / 拒绝 / 重试等场景处理）
• CI 失败诊断模板

详见：pr.md

oss-check（check.md）

每日晨间巡检，统一管理所有待处理 PR。

• 持续监控 CI 状态、机器人反馈、PR 是否过期
• 对已合并/已关闭的 PR 进行复盘（记录 Outcome 并归类沉淀经验）
• 日常维护：清理过时经验条目、归档旧上下文文件
• 兼容 fork PR 的 CI 跳过机制（外部贡献者的正常行为）

详见：check.md

前置依赖

• 已安装并认证 GitHub CLI（gh）：gh auth status
• 拥有目标仓库的 GitHub Fork
• 可选：本地克隆仓库用于代码库扫描（对应 Source 8）

安全模型

该能力会指示 agent 执行来自目标仓库的构建、检查与测试命令（例如：pnpm install、make、cargo test）。这是贡献自动化中固有且必要的环节——不运行仓库自身的工具链，就无法真实验证修复效果。

攻击面说明：若目标仓库包含恶意构建脚本（如 npm postinstall 钩子），这些命令将在你的机器上执行。其风险等级与你手动克隆仓库后运行 npm install 完全一致。

风险控制机制：

• 用户信任边界：由你自主选择目标仓库，该能力绝不会自行决定目标。
• 运行时闸门机制：OpenClaw 的 exec 审批系统会在执行任何 shell 命令前主动提示确认。该能力仅输出指令，是否执行由运行时环境最终裁定。
• 变更范围检查点：当拟提交的变更超过 5 个文件或 200 行时，系统将暂停并要求人工确认。

推荐加固措施：

• 针对不熟悉的仓库，建议在容器中运行（openclaw --container ）或使用独立虚拟机。
• 首次运行前，请手动审查目标仓库的 package.json scripts 或 Makefile targets。
• 如需更强隔离性，可为自动化任务单独创建专用 GitHub 账号。

数据目录结构

系统自动创建并维护以下目录：

• ./oss-pilot-data/profiles/ —— 每个仓库对应一个 profile 文件
• ./oss-pilot-data/context/ —— 当前活跃 PR 的上下文文件
• ./oss-pilot-data/context/_archived/ —— 已完成 PR 的上下文归档（用于持续学习）