GitHub 集成 Xiaodaidai-521/dsh-plugin-github

dsh-plugin-github

DeepSeek Harness 的 GitHub 集成 —— 用 GitHub 账号登录，按 github.com 的布局浏览仓库，还能让智能体直接操作分支、拉取请求、议题、Actions 和文件提交。

你能得到什么

左侧栏里多出一个 GitHub 面板：

- 用 GitHub 登录（OAuth 设备流）—— 不用手动创建 Personal Access Token
- 仓库切换器：token 能访问的仓库全都在，可搜索，重启后仍记得
- GitHub 风格的代码页：分支选择器、标签/分支计数、Go to file 过滤、最新提交行、文件表格（显示每个条目的最后提交）和 README 卡片
- 右侧栏：About / Releases / Contributors / Languages（沿用 GitHub 的语言配色）
- 真正能用的标签页：Code、Issues、Pull requests、Actions
- Star / unstar 和 fork 按钮
- 内联文件查看器、Add file 上传、New branch、New pull request

还有 14 个智能体工具，助手不用你点鼠标也能干同样的活：

| 工具 | 用途 |
| github_auth_status | token 属于哪个账号，以及它从哪来 |
| github_repo_info | 默认分支、可见性、star、fork、watcher |
| github_list_branches / github_create_branch | 查看和创建分支 |
| github_list_pulls / github_get_pull / github_create_pull | 审阅和发起拉取请求 |
| github_list_files / github_read_file | 不克隆仓库也能浏览和读取文件 |
| github_upload_file / github_delete_file | 创建、更新或删除单个文件 |
| github_commit | 在一次原子提交里提交多个文件（Git Data API） |
| github_list_commits | 最近的提交，可按路径过滤 |

安装

插件是纯 ESM，没有运行时依赖，也不需要构建。

1. 让包能按名字解析

DSH 从包清单里发现面板（dsh.client），所以插件必须作为包解析，不能只给一个文件路径。把它链接进配置档的 node_modules：

Windows
$nm = "$env:APPDATA\dsh-desktop\harness\profiles\web\node_modules"
New-Item -ItemType Junction -Path "$nm\dsh-plugin-github" -Target "C:\path\to\dsh-plugin-github"

macOS / Linux
ln -s /path/to/dsh-plugin-github "$HOME/.config/dsh-desktop/harness/profiles/web/node_modules/dsh-plugin-github"

2. 添加加载器条目

往配置档的 cordis.patch.yml 末尾追加：

dsh-plugin-github >>>
- insert:
- id: dsh-plugin-github
name: dsh-plugin-github
<<< dsh-plugin-github <<<

该条目上的可选配置：

config:
repository: 'owner/name' # default repo when a call omits repo
oauthClientId: 'Ov23li…' # OAuth App client id (see below) tokenEnv: GITHUB_TOKEN apiUrl: https://api.github.com

3. 重启 DSH Desktop

宿主插件在启动时组装；手动改过的补丁不会实时重新读取。请完全退出（包括托盘），再重新启动。

登录

一键登录：OAuth 设备流（推荐）

注册一个 GitHub OAuth App，只需一次，大约一分钟。client id 是公开值，可以随插件一起发布，这样每个用户都能一键登录：

1. <https://github.com/settings/applications/new>
2. 名称和主页随便填。
3. Authorization callback URL：任意合法 URL 都行，例如 https://github.com/login/device。设备流从不重定向，但表单不接受空值。
4. 向下滚动，勾选 Enable Device Flow。不勾选流程会失败。
5. 复制 Client ID。

把它粘贴到面板的登录界面（保存在 <DSH_HOME>/storages/dsh-plugin-github/config.json），或者通过补丁配置 / GITHUB_OAUTH_CLIENT_ID 提供。

之后点 Sign in with GitHub，界面会显示 8 位字符码；在 github.com/login/device 输入该码，面板会自动继续。

请求的 scope 是 repo read:user read:org workflow。之所以包含 workflow，是因为写入涉及 .github/workflows/ 时，没有它 GitHub 会返回 404，而不是 403。

备用方案：Personal Access Token

登录界面也接受 PAT：repo scope，只读公开仓库则用 public_repo。

token 存在哪里

登录成功后，会同时写入两个地方，这是有意为之：

- DSH 凭据存储（GITHUB_TOKEN），通过 ctx.credentials 写入，这是首选位置。
- <DSH_HOME>/storages/dsh-plugin-github/token.json，一份独立副本，AES-256-GCM 加密，密钥由机器名、当前用户和平台派生。

之所以保留第二份副本，是因为凭据存储归宿主所有：重建配置档、更新应用或重置都可能丢掉条目，然后面板会悄悄变成「未登录」，要求你重新登录。保留一份独立的加密副本，登录状态才能扛过这些操作。

该文件换到另一个账户或机器上无法读取；文件被改动后，认证标签校验会失败，而不会被使用。说实话，加密带来的好处是：消除了「明文密钥躺在磁盘上」这种情况。它不是密钥保管库，能以此用户身份运行代码的人，都能重新派生出密钥。

如果 GitHub 以 401 拒绝已保存的 token，插件会从两处删除它，并要求重新登录，而不是一直失败下去。

- token 绝不发送到浏览器，绝不存入 localStorage，也绝不在任何响应中回显。
解析顺序：凭据存储 → 面板保存的 token → 环境变量（GITHUB_TOKEN / GH_TOKEN）→ gh auth token。退出登录会删除已保存的副本，并在该进程中停用环境变量与 gh 这两条回退路径。

安全说明

- 面板是浏览器模块，通过两条 POST 路由（api/dsh-plugin-github/state 和 .../action）与宿主通信。token 始终留在宿主侧。
- 设备流轮询密钥从不离开宿主；浏览器只能看到短用户码。
- 登录时先调用 GET /user 校验 token，通过后才保存，所以输错一次也不会变成已保存的凭据。

已知限制

- 登录状态按宿主区分，不按 DSH 用户区分——最后登录的账号就是实际使用的账号。
- 面板实现了 Code / Issues / Pull requests / Actions。Projects、Wiki、Security 和 Insights 是刻意不做的，而不是摆几个点不动的标签页。
- github_commit 要求目标分支已存在；请先用 github_create_branch 或在面板里创建。
- 内置的 client id 标识的是本插件的 OAuth App，不是你：每个登录的用户授权的都是自己的 GitHub 账号，拿到的 token 从不离开自己的机器。
- 在 .github/workflows/ 下写文件需要 workflow 权限；没有这个权限，GitHub 会返回 404。

自己动手验证

仓库里附带了验证上述每项行为所用的同一批脚本：

node scripts/verify-client.mjs # browser-bundle contract, mounts, both screens, render smoke
node scripts/verify-json.mjs # every tool result is lossless JSON
node scripts/verify-login.mjs # PAT sign-in, refusal of bad tokens, sign-out
node scripts/verify-device.mjs # device-flow wiring
node scripts/verify-clientid.mjs # a client id saved from the UI survives a restart
node scripts/verify-persist.mjs # token persistence and a real sign-out
node scripts/verify-repos.mjs # repository switcher list
node scripts/verify-overview.mjs # About / Releases / Contributors / Languages data
node scripts/verify-browse.mjs # directory listing and file reads
node scripts/verify-oauth-live.mjs <client-id> # full device flow, end to end

其中大部分脚本会直接调用线上 GitHub API，所以机器上需要有 token（GITHUB_TOKEN 或先执行 gh auth login）。

许可证

MIT —— 见 LICENSE。