harness-github

Readme

# harness-github

[![CI](https://github.com/988hj7tczd-oss/harness-github/actions/workflows/ci.yml/badge.svg)](https://github.com/988hj7tczd-oss/harness-github/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/harness-github.svg?color=blue)](https://www.npmjs.com/package/harness-github)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![dsh-plugin topic](https://img.shields.io/badge/topic-dsh--plugin-brightgreen)](https://github.com/topics/dsh-plugin)

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):

```bash
dsh plugin add harness-github
```

### 中文说明

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

## 快速上手 / Quick Start

### 中文

```text
用户:看看 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

```text
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

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

## 许可证 / License

MIT — 见 [LICENSE](./LICENSE)。