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

到 https://github.com/settings/applications/new 登录并填写表单：

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