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     # 设备码流程、路由处理器、认证工具测试