dsh-github-bridge

Readme

# dsh-github-bridge

**中文** · [English](./README.en.md)

一个 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`

## 安装

```bash
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）

```yaml
- 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_*` 工具。

## 开发

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