dsh-github-toolkit

dsh-github-toolkit

English | 中文

把 GitHub 接进 DeepSeek Harness：18 个模型可直接调用的 github_* 工具，外加一个 Web 设置页 —— 粘贴 PAT、当场测试连接、指定默认仓库、开关写权限，全在 GUI 里完成，不需要终端，也不需要重启。

无构建步骤、无运行时依赖：宿主半边只用 Node 内置 fetch，浏览器半边只 require react 与 shell 的静态 UI 原语。

• 令牌不进配置：从 DSH 凭证库按引用读取（默认 GITHUB_TOKEN），每次请求现取 —— 轮换令牌对下一次调用立即生效，cordis.patch.yml 与 settings.yaml 里永远没有明文密钥。
• 配置即改即生效：设置页保存后宿主立刻按新配置工作（关掉写权限会直接注销写工具），不用重启。
• 错误直接给出下一步：401 → 换令牌；403 且额度为 0 → 何时重置；403 其他 → scope / SAML SSO；404 → 不存在或无权访问；422 → 带上 GitHub 的字段级明细。
• 返回值先裁剪再给模型：正文 / patch / diff 都按预算截断并标注「已截断」，避免把 GitHub 的原始大对象灌进上下文。

环境要求

• DeepSeek Harness 0.1.5-rc.1 或更新（@deepseek-ai/dsh-tools、@deepseek-ai/dsh-credentials 由 harness 以 peerDependencies 形式提供）。
• Node.js 22+（宿主半边用到 AbortSignal.any）。
• 一个 GitHub PAT。建议用 classic token（勾 repo）：细粒度令牌默认没有「创建仓库」这类权限，容易在后续操作上卡住（详见下方排错）。

快速上手（3 步）

# 1) 安装
dsh plugin --profile web add dsh-github-toolkit

2. 刷新 http://127.0.0.1:3080 ，打开 设置 → GitHub
3. 粘贴 PAT → 点 测试连接（页面会显示 @你的账号、权限范围、剩余额度）→ 点 保存令牌

点开左下角的「设置」→ GitHub，看到的就是这一页：

然后就能直接对话了，例如：

• 「看一下 owner/repo 的开放 issue，按标签分个类」
• 「把这个报错整理成 issue 提上去，标题用 xxx」
• 「PR #42 改了什么？CI 过了吗？值得合并吗？」
• 「在 src 目录里搜一下 TODO( ，列出来」
• 「把 docs/readme.md 的第 12 行改掉，提交到 chore/fix-typo 分支并开 PR」

安装

包声明了 dsh.bundle，所以安装器会把它加进 profile 的 dsh.profile.bundles，bundle 里的 cordis.patch.yml 负责挂载宿主半边；浏览器半边通过 package.json 的 dsh.client 自动出现，不需要额外注册。

# npm 名（发布到 npm 时）
dsh plugin --profile web add dsh-github-toolkit

# 直接从仓库装（推荐，当前即如此）
dsh plugin --profile web add github:QDchuan/dsh-github-toolkit

包里没有构建脚本，所以从 git 安装不需要 allowBuilds 授权，几秒装完。

本地开发（不想发布、只想让 profile 指向当前目录）：

./install.ps1 -DryRun     # 只打印将要复制与写入的内容
./install.ps1             # 复制进 web profile 并写入一段手工 patch 行
./install.ps1 -Uninstall  # 删除副本与那段 patch 行

⚠️ 不要和 dsh plugin add 的安装方式同时使用：两者解析到同一个包，而同一个包有两个活跃 Loader 来源会直接组合报错。要从本地开发切到已发布版本，先 .\install.ps1 -Uninstall。

GUI 设置页

几个刻意的交互决定：

• 测试连接在浏览器里做：GitHub REST API 允许跨域（Access-Control-Allow-Origin: *，并暴露 X-OAuth-Scopes、X-RateLimit-*），所以在令牌交给宿主之前就能先验证它，测试结果会显示账号、scope、剩余额度。
• 已保存的令牌不回显：凭证库只回答「是否已配置 / 来源 / 可写」，页面拿不到值；想复核就重新粘贴一次点测试，或让模型调用 github_auth_status。
• 保存即生效：关掉写开关会注销 6 个写工具、把 github_api 收紧为仅 GET；打开则重新注册 —— 不用重启。
• 留空 = 恢复默认：文本框清空后保存，等于清掉该项覆盖，回到 composition 默认值（例如默认 owner 留空后，模型必须每次显式给出 owner/repo）。
• 写操作与只读分开建模：便于用权限预设把写工具设为 ask；一个开关就能整体退成只读插件。

工具

配置

设置页写的是 settings.yaml 里的 tool-github 命名空间；composition 那一行只放默认值：

凭证与权限

PAT 存在 $DSH_HOME/.credentials.yaml 的 refs 段（设置页会写，也可以手工编辑）：

refs:
  GITHUB_TOKEN: ghp_xxxxxxxx

查找优先级（由 dsh-credentials-local 决定）：启动环境变量 > 凭证文件 > 项目 .env > $DSH_HOME/.env。启动 dsh 前 shell 里已经存在的 GITHUB_TOKEN 会盖过凭证文件，设置页会如实显示来源。

令牌怎么选

只做读写代码/issue/PR 的话，细粒度令牌按下面勾就够：Contents: read/write、Issues: read/write、Pull requests: read/write、Metadata: read，读 CI 再加 Actions: read、Checks: read；组织仓库若启用 SAML SSO，需要为令牌显式授权该组织，否则 API 返回 403。

如果你希望 DeepSeek 顺手帮你建仓库、设 topics，用 classic token 勾 repo 最省事。

排错

安全边界

• 令牌只经 ctx.credentials 每次现取，插件不缓存、不落盘、不打日志，也没有任何把令牌写进配置的代码路径。
• 「测试连接」把输入框里的值直接发给 api.github.com（不发给宿主），只存在于当前页面内存；保存成功后输入框立即清空。
• github_api 会绕过专用工具的字段校验，写开关关闭时可限制为 GET。
• 凭证库按文件权限保护，但 agent 的工具进程以同一个 OS 用户运行，所以它读得到该文件 —— 这是「不主动告知路径」的克制，不是隔离。要真正隔离密钥，需要换一种存储方式。

开发

npm install          # 安装测试会 import 的 @deepseek-ai 依赖
npm test             # 宿主契约 + 浏览器 bundle（离线，另含一次真实网络 401 校验）
npm run test:installed

• test/smoke.mjs 不需要 PAT：它按加载器的方式驱动宿主半边，用极简 React 运行器真实渲染设置分页并跑一遍保存/测试/配置写入，再用桩响应断言错误映射；有网络时还会用无效令牌验证真实的 401 映射，离线自动跳过。里面固定了几条容易回归的约束，例如「工具返回值必须是无损 JSON」。
• test/installed.mjs 校验运行时实际加载的那份：文件、清单（含 dsh.bundle）、profile 的 patch 行、宿主导入、浏览器 bundle 只依赖基线模块。用法：node test/installed.mjs [profile] [pluginDir]。

文件

已知限制

• 工具覆盖本插件建模过的 REST 面；其他接口走 github_api，它返回有界的 JSON 而不是类型化结果。
• GitHub 搜索的 total_count 在结果集很大时是近似值，插件原样透出。
• 浏览器半边是手写客户端 bundle，控件是自绘的而非 schema 驱动表单；新增选项要同时改 lib/client.js 与 lib/index.js。
• 已经加载过客户端 bundle 的 profile 需要刷新页面才能拿到新版本。

许可

MIT