GitHub 桥接 gaolei-mark43/dsh-github-bridge

dsh-github-bridge

中文 · English

一个 DSH 插件，让 DSH/dwsh 直接调用远程 GitHub API（仓库、issues、Pull Requests、文件、搜索），并支持像 Codex 等 CLI 工具那样的 GitHub OAuth 登录方式认证。

功能特性

- 基于登录的 GitHub 认证 — OAuth 2.0 设备码流程（github_login，或插件配置页里设置 → 插件中的 "Login with GitHub" 按钮）。无需手动创建 Personal Access Token；令牌存入 DSH 凭据服务，模型永远不会看到令牌本身。
- 通用 GitHub REST API 调用：github_request
- 用户与仓库：github_get_user、github_list_repos、github_get_repo
- Issues：github_list_issues、github_get_issue、github_create_issue
- Pull Requests：github_list_pull_requests
- 文件内容：github_get_file
- 搜索：github_search_repositories
- 认证辅助：github_auth_status、github_logout

安装

cd /path/to/dsh-github-bridge
dsh plugin --profile web add .

插件声明了 dsh.bundle.patch，所以 dsh plugin 会自动把它加入 dsh.profile.bundles。默认行 id 为 github-bridge。

安装后请重启一次 DSH。Web 应用在启动时扫描客户端 bundle（package.json 中的 dsh.client 声明），重启后插件配置卡片才会出现在 设置 → 插件 中。

如何配置

插件的所有配置都放在插件自身、手动配置，有两个入口：profile 的 cordis.patch.yml（或 --patch 覆盖层），以及配置页面（设置 → 插件 → dsh-github-bridge 卡片，OAuth 相关项可直接在页面上填，无需重启）：

方式一：配置文件（cordis.patch.yml）

- id: github-bridge
config:
GitHub OAuth App 的 Client ID。登录认证（设备码流程）必需。
在 https://github.com/settings/applications/new 创建，勾选 "Enable Device Flow"。设备码流程不需要 client_secret。
也可以直接在配置页面上填写，二选一。
clientId: Iv1.xxxxxxxxxxxxxxxx
OAuth 权限范围（空格分隔），默认 "repo"。
repo —— 完全控制私有+公开仓库（默认，权限最大） public_repo —— 只读写公开仓库（最小权限，更安全） workflow —— 修改 GitHub Actions 工作流文件（repo 不含它）例：repo read:user workflow scopes: repo OAuth 主机，默认 https://github.com（GitHub Enterprise 时改）。
oauthBaseUrl: https://github.com
令牌存储用的 DSH 凭据引用 / 环境变量名。
tokenEnv: GITHUB_TOKEN
baseUrl: https://api.github.com
可选：不给 owner/repo 参数时的默认值。
defaultOwner: my-org
defaultRepo: my-repo

方式二：配置页面（设置 → 插件 → dsh-github-bridge）

1. 卡片上的 OAuth 客户端（Client ID） 输入框填入你的 Client ID（如 Ov23li...），点 保存——立即生效，无需改文件、无需重启；
2. 权限范围（scopes）同理，在旁边的输入框里填（如 public_repo）后保存；
3. 卡片上的"手动粘贴令牌"框只接受访问令牌（ghp_… / github_pat_…）， Client ID（Iv1.… / Ov23li…）不是令牌，粘进去会被明确拒绝。

配置页面填入的值存放在 DSH settings 命名空间中，优先级高于 patch 层配置；清空某字段则回退到 patch 层的值。

defaultOwner / defaultRepo 是可选便利项；不填时工具要求显式给出 owner / repo 参数。

创建 GitHub OAuth App

到 登录并填写表单：

| 字段 | 填什么 |
| Application name | 任意，如 dsh-github-bridge |
| Homepage URL | http://localhost 即可——GitHub 只是展示它，不需要公网可达 |
| Authorization callback URL | http://localhost——只服务于网页重定向流程；设备码流程从不重定向（令牌通过轮询返回），该值永远不会被调用 |
| Enable Device Flow | 必须勾选，否则登录会报 device_flow_disabled |
| Expire user access tokens | 建议取消勾选：开启后令牌 8 小时过期，而本插件只存 access token（暂未支持 refresh token 刷新），过期后登录会失效 |

注册完成后，把 Client ID（应用主页上显示的 Iv1.… / Ov23li…； client_secret 设备码流程不需要）填进插件配置的 clientId。

登录 GitHub

在配置页面登录（设置 → 插件 → dsh-github-bridge）
1. 确认 clientId 已配置（见上）；
2. 打开 设置 → 插件，展开 dsh-github-bridge 卡片；
3. 点 Login with GitHub：卡片显示验证 URL 和一次性代码，并自动轮询；
4. 打开 URL、登录、输入代码。授权后卡片显示已登录用户；点 "Sign out" 清除令牌。

也可以在同一个卡片上手动粘贴令牌（"保存令牌"）。

在对话中登录

直接对 DSH 说"登录 GitHub"，智能体会运行 github_login：发起设备码流程、显示验证 URL + 代码，并轮询直到你授权。用 github_auth_status 查看登录状态， github_logout 退出登录。

令牌通过 DSH 凭据服务按次解析，登录后立即生效（首次启动后无需重启）。

在 DSH 中的用法

安装并登录后，可以直接问 DSH，例如：

- "列出我的 GitHub 仓库"
- "读取 my-org/my-repo 的 README"
- "列出 my-org/my-repo 的 open issues"
- "在 my-org/my-repo 创建 issue，标题是……，内容是……"
- "搜索 GitHub 上关于 dsh 的 TypeScript 插件"
- "我的 GitHub 登录状态怎么样？"（github_auth_status）
- "退出 GitHub 登录"（github_logout）

智能体会自动调用对应的 github_* 工具。

开发

npm test

目录结构：

dsh-github-bridge/
├── cordis.patch.yml # DSH bundle patch：把插件行插入 profile ├── client/ │ └── client.js # 浏览器端：设置 → 插件 的配置卡片 │ # （ModuleLoader 模块，注册 settings.plugin.item） ├── src/ │ ├── github.js # GitHub REST 客户端 + OAuth 设备码流程 + HTTP 辅助 │ └── index.js # DSH 插件入口：工具、认证路由、配置卡片接线 └── test/ ├── github.test.js # 客户端与辅助函数测试 ├── plugin.test.js # 插件注册 / 执行路径冒烟测试 └── auth.test.js # 设备码流程、路由处理器、认证工具测试