前言¶
DeepSeek Harness（DSH）采用「一切皆插件」的架构，智能体通过插件扩展能力。针对需要直接操作 GitHub 的场景，社区贡献了 knlcxy/dsh-github。装上之后，agent 可以直接调用 GitHub REST API、一次提交多个文件（一个 commit）、建仓库、查 token 的权限与配额。
插件定位¶
这是一个为 DSH 提供的 GitHub 工具插件，由 KNLCXY 维护。它不依赖任何外部服务，所有 API 请求通过 GitHub REST API 完成。token 存在插件自己的设置里，不会出现在仓库源码或工具输出中。
核心功能¶
插件提供以下工具：
github_status：查看登录名、token 掩码、scopes、API 配额余量。github_api：直接调用 GitHub REST API，支持 GET、POST、PUT、PATCH、DELETE。github_push_files：一批文件 = 一个 commit（blob → tree → commit → 更新 ref）。github_repo_create：建仓库，可设置 description、private、topics。github_release_create：建 Release 并上传附件（tgz 等），可标 draft / prerelease。github_fix_git_auth：诊断并修复 git 凭据弹窗问题（CredentialHelperSelector）。
安装与启用¶
从 GitHub 仓库安装：
dsh plugin --profile <你的 profile> add github:KNLCXY/dsh-github
从本地目录安装（要改代码时）：
dsh plugin --profile <你的 profile> add "file:/绝对路径/dsh-github"
装完重启 DSH（client 半在进程启动时组装）。
配置 GitHub token¶
打开 设置 → GitHub，把 token 粘进第一个输入框，点保存。
| 输入框 | 说明 |
|---|---|
| GitHub token | 只有示例占位符 ghp_xxxxxxxxxxxxxxxxxxxx，没有默认值；不填就是没配 |
| API 地址 | 留空用 https://api.github.com；只有 GitHub Enterprise 才需要改 |
| 代理 | 留空 = 直连。GitHub 直连超时的网络填 http://127.0.0.1:7897 |
也可以直接写文件（等价）：
// ~/.dsh/storages/dsh-github/settings.json
{
"token": "ghp_xxxxxxxxxxxxxxxxxxxx",
"apiBase": "https://api.github.com",
"proxyUrl": "http://127.0.0.1:7897"
}
token 权限¶
| 你想干什么 | 最小权限 |
|---|---|
| 只读仓库、看 issue / PR | Contents: Read（+ Issues: Read） |
提交文件（github_push_files） |
Contents: Read and write |
| 建仓库、设 topics | 再加 Administration: Read and write |
| 用 classic token 图省事 | 勾一个 repo 就全有了 |
- fine-grained：https://github.com/settings/personal-access-tokens/new → 选仓库 → 配上面几项 → Generate
- classic：https://github.com/settings/tokens/new → 勾
repo→ Generate
建议设过期时间（7–30 天）。不用了随时在同一个页面 Revoke。
典型用法¶
1. 查看当前 token 状态¶
github_status()
返回类似：
✅ token 可用：KNLCXY
token：ghp_…9c31 · 代理：http://127.0.0.1:7897
scopes：repo
配额：4986/5000
2. 调用 REST API¶
github_api({ path: "/repos/KNLCXY/dsh-github" })
github_api({ path: "/search/repositories?q=dsh-plugin&sort=stars" })
github_api({ path: "/repos/KNLCXY/x/issues", method: "POST", body: '{"title":"hi","body":"…"}' })
3. 一次提交多个文件¶
github_push_files({
repo: "KNLCXY/scratch",
message: "docs: 补 README",
files: [
{ path: "README.md", content: "# hi\n" },
{ path: "docs/a.md", content: "…" },
{ path: "logo.png", content: "<base64>", encoding: "base64" },
],
})
返回 ✅ 已提交 N 个文件 … commit abc1234 … https://github.com/owner/repo/commit/…。
4. 建仓库¶
github_repo_create({
name: "my-repo",
description: "a repo created by DSH",
private: false,
topics: "dsh,dsh-plugin,deepseek-harness"
})
适用场景¶
- DSH 智能体需要自动创建仓库、提交代码。
- 需要通过 API 查询仓库、issue、PR 等信息。
- 需要批量上传文件到一个 commit。
- 需要创建 Release 并上传附件。
安全边界¶
| 事项 | 做法 |
|---|---|
| token 存在哪 | ~/.dsh/storages/dsh-github/settings.json（本机，不进 git） |
| 会不会进 repo | 不会。仓库里的 cordis.patch.yml 写的是 token: '' |
| 会不会进工具输出 | 不会。只有 github_status 显示掩码（首 4 + 末 4） |
| 设置接口返回什么 | hasToken / tokenHint / 占位符，没有 token 字段 |
| 明文出现在哪 | 只有设置文件本身和 github_api 发出去的 Authorization 头 |
想再稳一点：给 token 设 7 天过期，用完 Revoke；或者用只含目标仓库的 fine-grained token（不要 “All repositories”）。
排错¶
| 现象 | 原因 / 修法 |
|---|---|
还没有配置 GitHub token |
去 设置 → GitHub 粘一个；或者写进 settings.json |
401 Bad credentials |
token 打错、已 Revoke、或复制时带了空格 |
403 Resource not accessible by personal access token |
权限不够。fine-grained 要给 Contents: Read and write（推文件）或 Administration（建仓库/设 topics） |
403 API rate limit exceeded |
未认证限流 60/小时，认证后 5000/小时；等一会儿或用别的 token |
404 Not Found |
仓库名拼错，或 token 没有这个仓库的访问权（fine-grained 要显式选仓库） |
请求超时 / fetch failed |
这个网络到 GitHub 不稳，在设置里填代理（http://127.0.0.1:7897），或用 github_status 对比直连与代理 |
| 设置页没有「GitHub」 | client 半在进程启动时组装：重启 DSH |
反复弹 CredentialHelperSelector |
git 的 system 配置把 credential.helper 设成了 helper-selector。用 github_fix_git_auth({ apply: true })，或在「设置 → GitHub」点「修复」——只改 git 凭据存储，不碰 token |
生态背景¶
DSH 理念是「一切皆插件」，社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。本文介绍的插件来自社区，安装前建议检查源码与许可证。
参考¶
- 目录页：https://www.skillhub.cn/plugins/KNLCXY/dsh-github
- GitHub：https://github.com/KNLCXY/dsh-github
- 许可：MIT © KNLCXY
