前言¶
在 DeepSeek Harness（DSH）里让智能体操作 GitHub，常见做法是外挂脚本或临时拼 REST 调用：token 散落、写操作难审计、浏览器端还要迁就 ESM 与 window.__ModuleLoader__ 的加载约束。valing1837 维护的 dsh-plugin-github 走另一条路——host-only：只注册宿主侧 agent 工具，不附带客户端 bundle，从结构上避开桌面版 web 启动与模块格式冲突；token 从 DSH 凭证域解析，写 GitHub 状态前可走审批门禁；另带不依赖模型凭据的确定性 PR 审查与可复用的 composite action 思路。插件面向 DSH 0.2.0-rc.2，在 Node 22.19 或 24 上开发与测试（package 声明 ^22.19.0 || >=24.0.0）。
这是什么¶
dsh-plugin-github 是社区插件（分类：工作流），仓库 valing1837/dsh-plugin-github，目录页 SkillHub。一句话：通过 GitHub REST API 与本地 git，把建库、读 diff、开/审/合并 PR、issue、搜索、checks、发版等能力暴露为 DSH 工具；审查侧用纯函数规则扫 unified diff，刻意不做模型调用。许可证 MIT，当前 package 版本 0.1.0。
为什么是 host-only¶
插件没有 dsh.client、没有 lib/client.js。DSH 0.2.x 浏览器端要求客户端以 window.__ModuleLoader__.load({...}) 自注册且不含顶层 import；普通 ESM 放进去会导致 web 启动失败（README 实测：Cannot use import statement outside a module）。本插件只挂主机工具，不触发该类故障。
核心功能¶
Agent 工具（29 个）¶
README 工具表覆盖仓库生命周期、PR/issue、内容与 CI 等，例如：
| 类别 | 代表工具 |
|---|---|
| 诊断 | github_status（配置与 token 来源，不发请求、不打印密钥）、github_whoami |
| 仓库 | github_create_repo、github_list_repos、github_delete_repo（需 confirm 精确等于 owner/repo）、github_clone、github_push |
| 内容与分支 | github_get_file、github_put_file、github_delete_file、github_list_branches、github_compare |
| Pull Request | github_list_pulls、github_get_pull（元数据 + 逐文件 patch + 全量 unified diff）、github_create_pull、github_update_pull、github_review_pull、github_merge_pull |
| Issue | github_list_issues、github_get_issue、github_create_issue、github_update_issue、github_comment |
| 搜索与 CI | github_search、github_get_checks、github_set_status |
| 发版 | github_list_releases、github_create_release |
| 审查（只读） | github_analyze_pull：对 PR diff 跑确定性规则，返回发现 + 可发布的 review body + 行内评论形状 |
斜杠命令 /github¶
不经过模型轮次，直接查询（实现上不硬注入 commands，而用 ctx.get('commands') 探测，避免缺组合命令运行时整包加载失败）：
/github status token 来源、apiBase、门禁状态
/github whoami 当前账号
/github repo <owner>/<name> 仓库概要
/github pr <owner>/<name> <n> PR 概要
/github checks <owner>/<name> <ref> CI 状态（列出不是绿色的 run）
/github review <owner>/<name> <n> 对 PR 跑确定性审查
/github search <query> 搜索 issue / PR
写操作审批门禁¶
配置 approveWrites 默认 true 时，注册 tools/pre-execute 监听器，对 14 个会改变 GitHub 状态的工具返回 { kind: 'ask', reason: '... will change state on GitHub: ...' }。运行时经 ctx.approval 派发，仅 allowed-once 继续；无应答方则拒绝。被拦工具包括 create_repo、delete_repo、push、create_pull、update_pull、review_pull、merge_pull、create_issue、update_issue、comment、put_file、delete_file、create_release、set_status。github_clone 不在门禁内（只从 GitHub 读，本地写由文件沙箱管）。可设 approveWrites: false 关闭监听器。
确定性审查（lib/review.js）¶
纯函数：输入 unified diff，输出发现；无网络、无时钟、无随机数。规则示例：secret-literal、known-token-prefix、conflict-marker、focused-test、sensitive-file 等为 error；debug-leftover、dangerous-eval、destructive-shell 等为 warning；todo-added、trailing-whitespace、lockfile-only、large-change（默认超过 largeChangeLines 800 行）等为 note。输出含发现列表、带标记 <!-- dsh-plugin-github:review --> 的 review body，以及可锚定新增行的 GitHub 行内评论；文件级/PR 级进 unanchoredFindings。
安全相关设计（README 摘要）¶
- Token 不写进插件源码；
github_push/github_clone完成后尽量把origin设为无凭证 URL。 - stdout/stderr 经
redact()再返回，避免 git 报错泄露带 token 的 URL。 - 提交身份优先用已有
git config user.email，为空才用配置的authorName/authorEmail。
安装与启用¶
桌面版 profile 由 Electron 独占，CLI 的 dsh plugin add 会拒绝管理 desktop profile，因此官方步骤是 clone 后跑安装脚本（幂等，改 package.json 前会备份）：
git clone https://github.com/valing1837/dsh-plugin-github
cd dsh-plugin-github
powershell -ExecutionPolicy Bypass -File install.ps1
脚本将包复制到 <profile>\node_modules\dsh-plugin-github，并把 dsh-plugin-github 写入 <profile>\package.json 的 dsh.profile.bundles。默认 profile 为 %USERPROFILE%\.dsh\profiles\desktop，可用 -ProfileDir 覆盖。装完需重启 DSH（宿主侧改动不会被 HMR 重载）。
Token 与权限¶
解析顺序：
- 配置项
token（字面值，不推荐） - DSH 凭证域
credentialRef(tokenRef)，默认引用名GITHUB_TOKEN - 环境变量
GITHUB_TOKEN
推荐在 %USERPROFILE%\.dsh\.credentials.yaml 的 refs: 下配置：
refs:
GITHUB_TOKEN: ghp_xxxxxxxx
| 方式 | 需要什么 |
|---|---|
| 经典 token | scope repo（含建库、推送、PR/issue、删除仓库） |
| 细粒度 token | Contents / Pull requests / Issues 各 RW，Metadata R；建库另需 Account → Administration RW |
用 github_status 看 token 是否解析、来源何处；github_whoami 验证有效性。
配置项（节选）¶
可在 profile patch 中覆盖，均有默认值：
| 键 | 默认 | 说明 |
|---|---|---|
tokenRef |
GITHUB_TOKEN |
凭证引用名 |
apiBase |
https://api.github.com |
REST 基址 |
gitHost |
github.com |
Enterprise 可改 |
approveWrites |
true |
写操作审批 |
reviewMinSeverity |
warning |
行内评论最低严重度 |
reviewMaxComments |
20 |
行内评论上限（≤50） |
largeChangeLines |
800 |
大改动提示阈值 |
完整列表见仓库 README「配置项」一节。
典型用法¶
- 安装并重启 DSH，在凭证文件或环境中配置
GITHUB_TOKEN。 - 在会话中让 agent 调用
github_status/github_whoami确认连通。 - 读 PR：
github_get_pull或斜杠/github pr owner/name n；只分析不发文：github_analyze_pull或/github review owner/name n。 - 需要改 GitHub 状态时，在
approveWrites: true下于 UI 审批一次（allowed-once）后再执行github_push、github_create_pull、github_merge_pull等。
仓库还提供 action.yml 与审查 CLI，供 CI 侧复用同一套 diff 规则；README 注明 composite action 已在本地 Git Bash 对真实 PR 做过脚本验证，尚未在 GitHub 托管 runner 上跑完 self-review 工作流（计划在本仓库下一 PR 完成）。
适用场景与注意¶
适合：已在 DSH 0.2.x 桌面 profile 上开发、希望 agent 稳定操作 GitHub（仓库/PR/issue/审查/状态），且希望写操作有人工门禁、PR 审查不绑定模型 API 的团队或个人。
注意：
- 插件以当前 DSH 进程权限运行，安装前请自行审阅源码与 MIT 许可证。
- 不要使用资料未给出的
dsh plugin add github:...安装方式；以 README 的install.ps1为准。 github_delete_repo不可逆，且需 confirm 护栏；经典 token 的reposcope 权限范围大，应按最小需要选用 token 类型。- 社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系，本文仅介绍社区插件能力。
结尾¶
dsh-plugin-github 把 GitHub 工作流收进 DSH 主机侧：29 个工具、写审批、确定性 diff 审查与 /github 快捷查询，token 走凭证域，审查方不必持有模型凭据。进一步了解请访问 SkillHub 目录页 与 GitHub 仓库。
