harness-github

DeepSeek Harness GitHub 插件 · A GitHub connector plugin for DeepSeek Harness (DSH).

处理 PR、issue、CI 与发布流程:检查 PR、分诊 issue、调试失败的 Actions 检查、处理 review 反馈、准备代码更改以供审查 —— 对齐 OpenAI Codex 插件市场的 GitHub 插件体验。

Handle PRs, issues, CI and releases: review PRs, triage issues, debug failed Actions checks, address review feedback, and prepare code changes for review — matching the OpenAI Codex GitHub plugin experience.

• 连接器优先(Connector-first):gh CLI 优先,REST(fetch)自动回退;每个工具描述都附对应 gh 命令。
• 认证零额外操作:复用 gh CLI 登录态 / GITHUB_TOKEN,不做 GitHub App、不做 OAuth 网页流程、不做 Device Flow。
• 安全:所有写操作每次执行前都请求 人工审批(ctx.approval,默认 ask,缺失 fail-closed 拒绝);token 永不进日志、永不写入配置文件。
• platform 无关:纯工具 + 系统提示,web / tui / headless 全部 profile 通用。

---

安装 / Install

需要 DSH ≥ 0.1.0-rc.6。任意 profile(web / tui / headless):

Requires DSH ≥ 0.1.0-rc.6. From any profile (web / tui / headless):

dsh plugin add harness-github

中文说明

1. dsh plugin add harness-github 会在 profile 目录执行 pnpm add 并登记 bundle;
2. 重启后插件生效,系统提示注入 github:workflow 工作流指引,并注册 18 个 github_* 工具;
3. 无需任何配置即可开始(公开仓库立即可用,写操作需要凭据 + 审批)。

快速上手 / Quick Start

中文

用户:看看 deepseek-ai/deepseek-harness 有没有待处理的 issue
Agent:github_issue_list repo=deepseek-ai/deepseek-harness → 分诊列表

用户:这个 PR #123 的 CI 挂了,帮我看看
Agent:github_pr_view repo=o/r number=123        → 详情 + checks 汇总
      github_workflow_run repo=o/r runId=…       → 失败步骤与关键日志
      修改本地代码 → 提交推送 → github_checks_view 确认

用户:处理一下这个 review 反馈,然后回复他们
Agent:github_review_feedback repo=o/r number=123 → 拉取评论线程
      github_pr_comment repo=o/r number=123     → 回复(审批)
      本地改代码 → 推送 → 再次 github_review_feedback 确认

用户:把我这些改动发个 PR
Agent:github_pr_prepare repo=o/r                 → 检查/提交/推送(审批)+ 建 PR(审批)

English

User: Any open issues in deepseek-ai/deepseek-harness worth triaging?
Agent: github_issue_list repo=deepseek-ai/deepseek-harness → triage list

User: CI is failing on PR #123, dig in.
Agent: github_pr_view repo=o/r number=123        → details + checks rollup
       github_workflow_run repo=o/r runId=…      → failed steps + key log lines
       fix locally → commit & push → github_checks_view to confirm

User: Address the review feedback and reply.
Agent: github_review_feedback repo=o/r number=123 → pull comment threads
       github_pr_comment repo=o/r number=123     → reply (approval)
       fix locally → push → re-check with github_review_feedback

User: Ship my changes as a PR.
Agent: github_pr_prepare repo=o/r                 → check/commit/push (approval) + create PR (approval)

---

工具清单 / Tools

| 工具 / Tool | 功能 / What it does | 对应 gh 命令 / Equivalent gh command | |---|---|---| | github_repo_view | 仓库概览(默认分支/语言/star/许可证/活跃度) | gh repo view <owner>/<repo> | | github_pr_list | 列 PR(open/closed/merged/all,可按作者/标签过滤) | gh pr list --repo <owner>/<repo> --state <state> | | github_pr_view | PR 详情 + 文件变更 + 评论 + checks 汇总 | gh pr view <n> --repo <owner>/<repo> --comments | | github_checks_view | 头提交状态检查 + Actions run 列表 | gh pr checks <n> --repo <owner>/<repo> | | github_workflow_run | 单 run 失败步骤 + 关键日志行 | gh run view <id> --repo <owner>/<repo> --log-failed | | github_issue_list | 列 issue(自动排除 PR) | gh issue list --repo <owner>/<repo> --state <state> | | github_issue_view | issue 详情 + 评论 | gh issue view <n> --repo <owner>/<repo> --comments | | github_search | 搜索 issue/PR/仓/代码(可按 repo 限定) | gh search issues/repos/code "<q>" | | github_release_list | 最近发布 | gh release list --repo <owner>/<repo> | | github_review_feedback | PR review 评论线程(逐条处理反馈) | gh pr view --comments + gh api .../reviews | | github_pr_create | 建 PR(防重复,draft 支持)✍️ | gh pr create --repo <owner>/<repo> --title ... | | github_pr_comment | 评论 PR/issue ✍️ | gh pr comment <n> --repo <owner>/<repo> --body ... | | github_review_submit | approve / comment / request-changes ✍️ | gh pr review <n> --repo <owner>/<repo> --approve | | github_pr_merge | merge / squash / rebase,可选删分支 ✍️ | gh pr merge <n> --repo <owner>/<repo> --squash | | github_issue_create | 建 issue(标签/负责人)✍️ | gh issue create --repo <owner>/<repo> --title ... | | github_issue_comment | 评论 issue ✍️ | gh issue comment <n> --repo <owner>/<repo> --body ... | | github_issue_close | 关闭 issue(可附原因评论)✍️ | gh issue close <n> --repo <owner>/<repo> | | github_pr_prepare | 本地流程:检查/提交/推送/建 PR ✍️ | git status && git push && gh pr create ... |

✍️ = 写操作,执行前需要人工审批(approval)。

---

认证与权限 / Authentication & Permissions

解析顺序(单次操作)/ Resolution order (per operation)

1. gh CLI 已登录(gh auth status 有效)→ 直接复用,免 token;
2. GITHUB_TOKEN(进程环境变量 / ctx.credentials 凭据库)→ REST 带 Bearer;
3. 公开仓库只读:无任何凭据时走 REST 匿名调用(速率受限,约 60 次/小时);
4. 都没有且要写操作 → 工具失败,唯一指引:运行 gh auth login 或设置 GITHUB_TOKEN。

权限边界 / Permission boundaries

| 操作类型 | 公开仓库 | private 仓库 | 需要 | |---|---|---|---| | 只读(10 个读工具) | ✅ 匿名可用 | 需 gh / token | 读权限 | | 写(8 个写工具) | 需 gh / token | 需 gh / token | repo 写权限 + 每次人工审批 |

写操作的审批:默认策略 ask(弹出人工确认);审批不可用或策略为 never 时一律拒绝,绝不静默放行;审批拒绝 → 零副作用。

---

兼容性 / Compatibility

| 项 / Item | 要求 / Requirement | |---|---| | DSH | >= 0.1.0-rc.6 < 0.2.0(推荐 0.1.0-rc.7 / rc.8) | | Node.js | ≥ 18(内置 fetch) | | gh CLI | 可选(未安装自动走 REST) | | GitHub | github.com(Enterprise host 二期支持) | | profile | web / tui / headless 通用 |

---

FAQ

gh 未安装怎么办? / gh is not installed?

自动回退 REST(fetch + token / 匿名只读),功能等价。只有需要本地 git 流程(github_pr_prepare)时才要求 git 本身(而非 gh)。

gh 未登录怎么办? / gh is not logged in?

自动回退 REST。写操作请:gh auth login,或设置 GITHUB_TOKEN 环境变量,或在 DSH 设置里配置 GITHUB_TOKEN 凭据。

遇到速率限制(rate limit)怎么办? / Rate limited?

匿名只读限额很低(约 60 次/小时,搜索 10 次/分钟)。做一次 gh auth login 或配置 GITHUB_TOKEN 即解除;错误信息会明确提示。

token 会不会被写进配置或日志? / Is the token persisted or logged?

不会。token 只在单次操作内存中使用(REST Bearer 头),永不写入 profile 配置文件,日志输出带防御性脱敏。

写操作会不会未经确认就执行? / Can writes happen without confirmation?

不会。所有写工具执行前调用 ctx.approval.request(...),仅 allowed-once 放行;approval 服务缺失、策略为 never、或用户拒绝,都会直接失败且零副作用。

为什么 github_pr_create 报 422 Validation Failed? / Why does github_pr_create fail with 422?

GitHub 拒绝创建 base 与 head 之间没有提交差异的 PR(包括 head 分支直接指向 base 同一提交)。确保 head 分支上先有至少一个自己的提交并已 push,再创建 PR。

GitHub rejects PRs with no commit differences between base and head (including a head branch pointing at base's exact commit). Make sure the head branch has at least one commit of its own and is pushed first.

为什么我的只读工具报错 404? / Why does a read tool return 404?

可能原因:仓库是 private(匿名访问 GitHub 对 private 仓库返回 404 而非 401);或 owner/repo 写错。检查 repo 参数格式为 owner/repo,并用 gh auth login/GITHUB_TOKEN 访问 private 仓库。

---

开发与测试 / Development

pnpm install
pnpm test        # 47 个离线单测(node:test,mock gh/REST,不联网)
node scripts/check.mjs  # 语法检查 + import 冒烟
npm pack --dry-run      # 发布前检查包内容

许可证 / License

MIT — 见 LICENSE。