dsh-github-cli

Readme

<div align="center">

# dsh-github-cli

**把你的 GitHub CLI (`gh`) 直接接进 DeepSeek Harness —— 零 token 配置，只读优先。**

[![CI](https://github.com/Nico0713520/dsh-github-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Nico0713520/dsh-github-cli/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![dsh-plugin](https://img.shields.io/badge/topic-dsh--plugin-purple)](https://github.com/topics/dsh-plugin)

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

</div>

> 如果你已经用 `gh` 登录过这台机器，这个插件装完就能用。你的 Agent 可以直接查 PR、看 issue、搜代码、跑 `gh api` —— 用你已有的账号，不用再配任何 token。

## 为什么是 `gh`，而不是 GitHub MCP server？

DeepSeek Harness 支持 MCP，GitHub 也有官方 MCP server。但它们不是一回事：

| | dsh-github-cli（本插件） | GitHub MCP server |
|---|---|---|
| 登录 | **复用你现有的 `gh` 登录**（含企业版/SSO） | 需要单独 PAT 或 OAuth 流程 |
| 命令面 | 每个 `gh` 子命令 + `gh api` | 只有精选的几个工具 |
| 写保护 | **逐命令白名单**（默认只读） | 工具级 scope |
| 配置 | 零配置、零 token | 装 server + 配 transport + 配 token |

一句话：**`gh` 是你已经信任、已经登录的那把钥匙，这里只是把它递给你的 Agent。**

## 特性

- ✅ **零配置** —— 复用 `gh` 本机登录态，不用生成、粘贴、管理任何新 token
- ✅ **只读优先** —— 默认只放行安全命令（view/list/status/search/checks/diff），写操作需显式开启
- ✅ **凭据永禁** —— `auth token`、`secret`、`ssh-key` 等命令即使开了全访问也拒绝，杜绝密钥泄露进对话
- ✅ **无注入** —— `execFile` + 参数数组（`shell: false`），不存在 shell 注入
- ✅ **企业友好** —— 已登录的 enterprise / SSO 账号直接可用
- ✅ **18 项单元测试 + 三版本 Node CI** —— 每个命令边界都有测试兜底

## 30 秒上手

```bash
# 1. 安装（GitHub 源，立即可用）
dsh plugin --profile web add git+https://github.com/Nico0713520/dsh-github-cli.git

# 2. 重启 dsh web（让插件作为 bundle 层生效）
# 3. 在对话里直接问
```

安装后，在任意会话里：

```
你：这个仓库有哪些未关闭的 PR？
Agent：→ 执行 gh pr list --state open -R deepseek-ai/deepseek-harness

你：帮我看看 PR #123 改了什么
Agent：→ 执行 gh pr diff 123

你：gh 在这台机器上登录了没？
Agent：→ 执行 gh_auth_status
```

## 工具

| 工具 | 作用 |
|---|---|
| `gh_cli_run` | 以参数数组执行任意 `gh` 子命令 |
| `gh_auth_status` | 检查 `gh` 是否已安装并登录 |

## 安全模型

这是本插件与其他 gh 封装最核心的区别 —— 每个命令都落在三个层级之一：

| 层级 | 示例 | 行为 |
|---|---|---|
| 🟢 只读白名单 | `repo view/list`、`pr view/list/status/diff/checks`、`issue view/list`、`search *`、`gist view/list`、`release view/list`、`run view/list`、`workflow view/list`、`api`（仅 GET）、`auth status`、`version`、`help` | **默认放行** |
| 🟡 写操作 | `pr create/merge`、`issue close`、`repo delete`、`release create`、`api --method POST/DELETE`、`api -f/--field/--input` | 需配置 `fullAccess: true` 才放行 |
| 🔴 永禁 | `auth login/logout/token/refresh`、`secret *`、`ssh-key *` | **任何情况都拒绝** |

### 为什么要这样设计

- **只读命令不会改动 GitHub 状态**，按需执行是安全的。
- **写命令会改变真实世界**，`fullAccess` 是一个明确、写在文档里的主动选择。
- **凭据类命令无条件拒绝**，因为它们的输出可能把密钥泄露进对话、或破坏你的登录。
- 命令通过 `execFile` + 参数数组执行（`shell: false`），**不存在参数注入**。
- 顺带处理了两个容易踩的坑：`gh api -f key=value` 会**隐式变成 POST**（已识别为写）；`workflow run list`（读）和 `workflow run <file>`（写）能精确区分。

## 配置

插件读取 `GhCliConfig`（在 profile 的插件配置里设置）：

```ts
interface GhCliConfig {
  ghPath?: string        // gh 路径，默认 PATH 上的 `gh`
  fullAccess?: boolean   // 允许写命令，默认 false
  extraReadOnly?: string[]  // 额外放行的只读前缀，如 ['gist create']
  timeoutMs?: number     // 单次调用超时，默认 60_000
}
```

cordis patch 示例：

```yaml
- insert:
    - id: gh-cli
      name: gh-cli
      config:
        fullAccess: false
        timeoutMs: 120000
```

## FAQ

**装了之后怎么没生效？** —— 一个包只有声明了 `dsh.bundle.patch` 才会成为激活的 Harness 层（本插件自带 `cordis.patch.yml`）。装完必须**重启 `dsh web`**（或刷新页面）。

**会泄露我的 token 吗？** —— 不会。`gh auth token` 这类命令在最高安全层级，任何情况下都拒绝执行；只读命令的输出不含凭据。

**为什么默认不是全功能？** —— 把 `gh` 交给一个能读你工作区、跑 shell 的 Agent，最稳妥的做法是"默认只读、按需放开"。安全边界应该是显式的，而不是隐式的。

**支持哪些 gh 版本？** —— 只要 `gh` 已登录且版本较新即可；本插件用参数数组调用，不依赖特定版本语法。

## 开发

```bash
git clone https://github.com/Nico0713520/dsh-github-cli.git
cd dsh-github-cli
npm install
npm run typecheck
npm test
npm run build

# 在本地 Harness 检出里调试
dsh plugin --profile web add "link:$(pwd)"
```

## 要求

- Node.js ≥ 20
- [GitHub CLI](https://cli.github.com/) 已安装并登录（`gh auth login`）
- DeepSeek Harness（`@deepseek-ai/dsh`）—— 已在 `0.1.0-rc.x` 验证

## 相关链接

- [贡献指南](./CONTRIBUTING.md)
- [更新日志](./CHANGELOG.md)
- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — 官方仓库
- [dsh-plugin topic](https://github.com/topics/dsh-plugin) — 发现更多插件

## License

MIT — 见 [LICENSE](./LICENSE)。