AutoContrib

用于无人值守的 GitHub 开源贡献：发现问题 → 修复验证 → 提交 PR → 跟进反馈。AutoContrib 在 DSH 中按计划执行、恢复中断任务，并展示贡献成果和面试材料。当前版本 0.8.6，宿主兼容范围为 DSH 0.2.1-rc.2 至 0.2.x（peer 范围 ^0.2.1-rc.2，已在 0.2.1-rc.2 与 0.2.1-rc.3 实测；新的 0.3 版本线需重新验证）。原生展示功能见 GitHub 贡献面板，贡献执行的历史验证见 0.3 验收。

插件 ID 为 auto-contrib，npm 包名为 dsh-plugin-auto-contrib。项目原名 oss-contrib；当前仓库为 BlueX888/dsh-plugin-auto-contrib（全新历史），旧仓库 dsh-plugin-oss-contrib 已归档，保留历史与发布。现有安装的迁移步骤见安装与升级。

已实现

• 33 个原生 DSH 工具：贡献执行、轮次、证据、成果统计、画板与面试准备。
• DSH Agent 执行器：原生任务描述 → 独立 session → 持久化结果 → 原生结算。
• 定时器、心跳、任务步数与时间上限、取消、卸载清理、恢复与互斥。
• 沿用原生策略、配额、独立验证收据、文件锁、发布去重和账本格式。
• 价值合同记录用户场景、影响、行为契约、验证方案与来源；材料不足保留待调研，人工反馈优先。
• 并发自适应：不设固定槽位。从上次学到的值(或 3)起步，槽位被占满且仍有工作时逐个上调，遇限流/超时/内存故障减半；模型请求速率接近预算时暂停派发，重任务按空闲内存与 CPU 放行；上限为 agent.maxConcurrent 与原生资源配置。仍受同 PR 写入互斥和性能任务独占限制。
• 0.4 并行流程：prepare 复用 30 分钟内的后台快照；只认领能立即开工的任务，槽位空出即经 oss run extend 滚动补位；有产出的周期 2 分钟后接续；模型额度/鉴权失败熔断；单任务失败不影响同伴；worker 经 oss_submit_result 结构化回传。设计与取舍见核心仓库 DECISIONS D-47。
• DSH 原生 AutoContrib 入口中的 GitHub 贡献面板：Mac 风格深色仪表盘、账号资料、GitHub 活跃日历、合并趋势、主题分布、所有值得讲的案例、搜索筛选、一分钟讲稿与证据入口；使用宿主认证连接。
• 保留本地只读画板，展示账本统计、等待事项、并发槽位和已合并 PR 面试卡，支持筛选及 Markdown 导出。

插件包自带 core/bin/ 执行内核和 policies/ 贡献规则。安装后由 DSH 工具与独立 worker session 直接执行，不需要额外源码目录或 Skill。paths.root 只指定可写数据工作区，默认 ~/.auto-contrib；已有 F:/PR 账本可以原位继续使用。账户和配额以包内核心/账本为准；配置中的 github.user、quota.* 是一致性检查，不能用来更换账户或静默修改配额。

安装 · 执行与工具 · 故障排查 · 历史验收证据 · 测试说明

看成果与准备面试

在 DSH 左侧面板列表点击 AutoContrib，打开 GitHub 贡献面板，直接在主区域浏览，与当前聊天无关。首页展示六项统计、13 周 PR 趋势、贡献分布、公开账号资料与 GitHub 活跃日历。默认展示全部对外已合并 PR，下方切换“已合并贡献 / 面试案例 / 项目 / 全部记录”，支持近 30 天、项目、主题、状态和关键词筛选。代表案例优先选择材料完整、主题不同的已合并贡献；详情提供一分钟讲稿、根因/方案/验证、追问和来源链接。复制讲稿后按真实经历补充个人参与。

打开和刷新面板只读取本地账本与材料，不启动贡献周期或调用模型。后台默认每 15 分钟完整同步账号对外合并 PR，每批自动整理最多 3 项，启动时补历史；不依赖贡献 scheduler。证据充分的案例进入面试列表，简单改动可保留为简报，证据不足时保留缺口并等待材料更新。面板显示完整同步时间与整理进度，来源变化使旧稿失效。现有 interview/cards 手写材料与生成稿分别保存。

需要独立网页时，调用 oss_dashboard_open 打开返回的本地地址；也可用 oss_contribution_stats 读取相同统计。独立画板按需启动，绑定 127.0.0.1 随机端口，卸载自动关闭。

主面板统计来自完整 GitHub 合并缓存与本地账本，按稳定 PR 身份去重，排除账号自有仓库；未完整同步时明确提示。全部记录中的未合并 PR 仍是本地跟踪口径。合并不等于生产采用。

oss_interview_card {repo, number} 为已合并 PR 读取讲述稿、根因/方案/取舍/验证/review 追问、来源与待补项。复用已有 interview/cards 笔记和 _data 来源，不覆盖手工材料。

oss_interview_prepare {repo, number} 先以只读 GitHub 请求刷新 PR、文件与 review，再使用独立 DSH session 整理中文讲稿。该 session 禁用全部工具，与贡献执行互斥；来源变化会使旧生成稿失效。refreshSources:false 可显式使用缓存。个人职责始终待本人确认，缺证据不编造指标。新稿保存于 <state>/dsh-plugin/interviews/。

使用

在 DSH 中调用 oss_* 工具，或开启插件定时器。插件自动把 policies/contribution.md 注入每个贡献 worker，并提供对应任务种类的包内规则文件；无需安装或调用技能。完整执行与恢复流程见 执行与工具。

先调用 oss_doctor 检查依赖和有效配置，再调用：

{"mode":"followup","batchSize":3}

上面是 oss_run_execute 的参数，跟进已有贡献。定向任务可用：

{"mode":"ship","targets":["owner/repo#123"],"batchSize":1}

oss_run_status 查看状态和 session ID；oss_run_cancel 中断并保留恢复记录；oss_run_recover 恢复最近未完成周期。恢复同一 run 必须保持 mode/targets。没有适合任务时返回 idle，不代表完成了新贡献。

手动 oss_ship_publish 默认 dry-run；明确 execute:true 才调用受原生门禁约束的外部写入。运行贡献周期会执行核心为任务授权的操作，包括满足门禁后的发布。不要把真实周期当成只读测试。

无人值守配置

在已有 auto-contrib 插件行上更新配置。旧安装先按 安装与升级 替换原 oss-contrib 行的 ID 和包名并保留 config；不要同时保留新旧两行，以免重复调度：

- id: auto-contrib
  name: dsh-plugin-auto-contrib
  config:
    paths:
      root: F:/PR # 已有数据保持原位；新安装可省略，默认 ~/.auto-contrib
    agent:
      maxConcurrent: 12 # 上限;实际并发由自适应控制器在其下学习
      adaptive: true # 按模型请求速率、延迟、空闲内存、CPU 与拥塞信号动态调整
      modelRpm: 50 # 共享 key 每分钟请求预算,接近 85% 时暂停派发
      memoryReserveMb: 4096 # 为宿主及其他程序保留的空闲内存
      heavyMemoryMb: 2048 # 每个重任务(克隆/安装/测试)需要的空闲内存
      taskTimeoutMs: 3600000
      maxSteps: 160
      heartbeatMs: 300000 # 租约 120 分钟
      runBudgetMs: 2700000 # 单周期停止补位的时间
      maxTasksPerRun: 32
    scheduler:
      enabled: true
      interval: '0 */6 * * *'
      timezone: Asia/Shanghai
      runOnStart: false
      mode: all
      batchSize: 3
      targets: []
      continuous: true # 有产出则 continuousDelayMs 后接续,空转等 interval
      continuousDelayMs: 120000

贡献调度默认 scheduler.enabled:false，避免安装即发起贡献；讲解整理默认 interviewAutomation.enabled:true，只读 GitHub 并写本地案例。宿主加载 agents/agentLoop 后开始调度，同一账本的周期互斥，周期内按原生资源计划并发；缺少容量合同退回一个槽位。槽位释放立即补派，同一 PR 单写者，GitHub 发布仍串行。最近有未完成周期时优先恢复。默认模型继承宿主；可指定 agent.provider/model/preset。

内置贡献合同自动加载，无需配置 agent.promptFile。该可选字段只用于用户偏好与任务优先级，例如现有 F:/PR/loop-prompt.md；不能替代或放宽内置规则。每轮保存规则内容和 SHA-256，恢复时沿用原快照，新周期读取更新。显式配置的文件不可读、空白或超过 128 KiB 时不开始新周期。DSH 协调器负责 prepare、心跳、派发与结算，worker 只执行领取的任务。

工作 session 继承宿主权限；可用 agent.permissionPreset 指定已存在的 DSH 权限预设，仅作用于插件创建的 session。需要人工批准的工具请求返回拒绝，提示 worker 以 needs_user 记录所需操作，避免无限等待。身份登录、仓库策略、配额或维护者回复未满足时仍应等待或阻塞，不绕过门禁。

宿主退出后不运行定时任务；硬崩溃后的活跃原生租约不会被强抢，恢复会等待其失效。已保存结果会直接结算；尚未保存的工作可能重做，外部发布的幂等由原生发布器保证。运行日志保存在 <state>/dsh-plugin/latest.json 和 runs/<runId>.json，原生证据/结果仍由核心保存。日志不保存 token。

工具

分组	工具
状态	oss_state_brief、oss_state_summary、oss_state_worklist、oss_state_ready_peek
发现	oss_hunt_discover、oss_hunt_probe、oss_hunt_screen、oss_hunt_preflight
发布与证据	oss_ship_quota、oss_ship_publish、oss_ship_comment、oss_ship_claim、oss_ship_evidence
跟踪	oss_track_snapshot、oss_track_cards、oss_homepage_status
执行	oss_run_execute、oss_run_recover、oss_run_status、oss_run_cancel
轮次	oss_round_start、oss_round_status、oss_round_stop、oss_round_report
高级周期接口	oss_run_prepare、oss_run_heartbeat、oss_run_finish_task、oss_run_finish
诊断	oss_doctor
画板与面试	oss_contribution_stats、oss_dashboard_open、oss_interview_card、oss_interview_prepare

高级接口用于已有协调器接入；通常只需 execute，不要与执行中的周期混用。包内命令由插件提供的绝对路径和运行环境调用，不需要安装全局 oss 命令。

开发

开发需要 Node.js 22、Python 3.12+、Git；真实 GitHub 操作另需已认证 gh 和可用的 DSH Agent/模型。此仓库包含完整源码，可以单独检出、构建、测试和打包；无需另一个核心仓库。core/bin/ 是直接维护并发布的 Python 源码，core/tests/ 与 core/workflows/ 用于内核开发测试。构建仅编译 Host 与浏览器入口，详见 测试说明。

npm ci
npm test
npm run test:core
npm run format:check
npm pack

本地画板预览：node scripts/preview-dashboard.mjs。预览的 paths.root 默认指向父目录的数据，也可通过 OSS_PREVIEW_ROOT 指定；执行代码来自构建后的插件包。地址保存到 .runtime-check/dashboard-preview.json，最多运行 12 小时。

MIT