GitHub 发布助手 maxid/dsh-github-aide

dsh-github-aide

把项目发布到 GitHub 的 DeepSeek Harness 插件 —— 一个插件同时具备两件事：

- 发布当前工作区：创建仓库、初始化 git、提交、处理远端分叉、推送；
- 上传任意项目目录：只读预检、凭据扫描、按技术栈生成 .gitignore、一次性完成建仓与推送。

它由两个插件的能力合并而来：s-huizhuy-u/dsh-github-sync（工作区同步、凭据库 token、分叉协调）与 3164481170/dsh-github-upload（项目预检、机密扫描、.gitignore 生成、Web 面板）。合并后只有一套令牌解析、一套 GitHub REST 客户端、一套 git 层、一个设置命名空间。

你： 把这个项目传到 GitHub

DSH： 已把 12 个变更文件发布到 maxid/my-project（分支 main）。
仓库：https://github.com/maxid/my-project

功能

| 能力 | 说明 |
| 项目预检 | 目录内容、技术栈、体积、凭据扫描、git 状态、GitHub 账号、同名仓库是否存在 |
| 机密扫描 | 命中 .env、私钥、ghp_、AKIA、sk-、私钥块等特征时默认拦截发布 |
| .gitignore 生成 | 项目没有 .gitignore 时按识别到的技术栈生成；已有则不改动 |
| 创建仓库 | GitHub 上不存在就创建（默认私有），已存在则复用 |
| 初始化 git | 只在还不是仓库时执行；沿用已有分支，新仓库用 main |
| 提交 | 暂存整棵工作树并提交；无变更时复用 HEAD，不报错 |
| 处理远端分叉 | 推送前先 fetch + rebase；冲突时回滚并报告 REBASE_CONFLICT |
| 推送 | 只把令牌交给内存中的 askpass，origin 始终是干净的 HTTPS URL |
| 只读预览 | github_status / dryRun 报告将要做什么，不写任何文件、不建仓库 |
| Web 面板 | 侧边栏填写令牌与目录 → 预检 → 发布 |

环境要求

- DeepSeek Harness 0.2.1 或更高（已在 0.2.1-rc.3 上验证加载）
- Node.js 22+
- PATH 中有 git（不需要 gh CLI）
- 一个 GitHub personal access token

安装

推荐用 DSH 的插件命令（profile 名按你的实际环境替换）：

dsh plugin --profile desktop add "link:$PWD"

或把仓库目录复制进 profile 后，用附带脚本完成声明（脚本会打印每一个写入路径，可重复执行）：

node scripts/install.mjs --profile desktop

装完重启 DSH。脚本会把插件放到 <profile>/.local-plugins/ 与 <profile>/node_modules/，加入 dsh.profile.bundles，并把加载行写进 cordis.patch.yml。

认证

需要一个 GitHub personal access token，按优先级三种来源：

1. 环境变量 GITHUB_TOKEN，其次 GH_TOKEN（适合 CI，不在磁盘留痕）；
2. 对话里存：说「存一下我的 GitHub token」，助手调用 github_configure；
3. 面板：侧边栏「GitHub 发布」→ 填令牌 → 保存并校验。

权限要求：

| token 类型 | 需要的权限 |
| classic | repo（只发公开仓库可用 public_repo） |
| fine-grained | Contents: Read and write；若让插件建仓库还需 Administration: Read and write（或账户级 Repository creation） |

存储的令牌保存在 DSH 凭据库（github-aide 作用域），不会写进 settings.yaml。所有 token 形态在进入日志或对话前都会被遮蔽，包括 git 报错时回显 remote URL 的情况。

工具

github_publish —— 发布

| 参数 | 类型 | 默认值 | 含义 |
| path | string | 工作区根目录 | 要发布的项目目录 |
| repo | string | 目录名 slug 化 | 仓库名 |
| owner | string | 配置值 → token 所属用户 | 仓库所有者 |
| description | string | — | 仓库描述（仅创建时生效） |
| visibility | private \| public \| internal | 配置值 → private | 新仓库可见性 |
| private | boolean | — | 兼容简写：true 私有、false 公开 |
| branch | string | 当前分支 → 配置值 → main | 推送分支 |
| commitMessage | string | 自动 | 提交信息 |
| autoInit | boolean | false | 是否让 GitHub 创建首个提交 |
| allowSensitive | boolean | false | 扫描命中仍继续（慎用） |
| autoIgnore | boolean | true | 无 .gitignore 时自动生成 |
| push | boolean | true | false 则只在本地提交 |
| force | boolean | false | 历史冲突时覆盖远端分支（始终 --force-with-lease） |
| dryRun | boolean | false | 只预演，不写文件、不建仓库、不推送 |

github_status —— 只读预检

github_status(path?) 返回：解析后的仓库名/所有者/分支、项目技术栈与文件数、凭据扫描命中、git 状态、远端仓库是否存在、令牌来源，以及待处理的 harness 升级提醒。不做任何写入。

github_configure —— 令牌

| 参数 | 类型 | 含义 |
| token | string | 校验并保存 token（永不回显） |
| clear | boolean | 删除已保存的 token |

Web 面板

侧边栏「GitHub 发布」：

1. 填令牌 → 保存并校验（显示账号与 scope）；
2. 填项目目录（默认工作区根目录）；
3. 预检（只读） 查看技术栈、扫描命中、仓库是否存在；
4. 发布：dryRun 可先预演；allowSensitive 放行扫描命中。

面板只拿到布尔值、账号名和结果，令牌从不离开 Host。

设置

命名空间 github-aide，可在 设置 → 插件 中编辑，也可在 profile 的 cordis.patch.yml 里配置：

| 键 | 默认值 | 含义 |
| owner | 空 | 新仓库所属账号；空表示 token 自己的用户 |
| visibility | private | 新仓库可见性 |
| autoInit | false | 是否让 GitHub 创建首个提交（保持关闭，首次推送才不会被拒） |
| branch | 空 | 推送分支；空表示沿用当前分支，再退到 main |
| commitMessage | 空 | 提交信息；空表示新仓库 Initial commit、之后 chore: publish |
| allowSensitive | false | 允许发布扫描到凭据的项目 |
| autoIgnore | true | 无 .gitignore 时自动生成 |
| timeoutMs | 600000 | 单次发布超时（毫秒） |
| maxScanFiles | 8000 | 凭据扫描文件数上限 |

- id: github-aide
name: dsh-github-aide
config:
owner: maxid
visibility: private
timeoutMs: 600000

安全设计

- 令牌永不落盘：origin 始终是 https://github.com/<owner>/<repo>.git，令牌只通过内存中的 GIT_ASKPASS 子进程环境传递，不进入 argv、.git/config 或任何 git 配置文件。
- git 永不弹出提示：每次调用都带 GIT_TERMINAL_PROMPT=0、GIT_ASKPASS=、GCM_INTERACTIVE=never；认证失败会直接报错，而不是挂到超时。
- 凭据扫描默认拦截：命中特征时中止，需要显式 allowSensitive=true 才继续；扫描不跟随符号链接。
- 远端分叉是协调，不是覆盖：先 fetch + rebase，force 也只用 --force-with-lease。
- 日志脱敏：错误、警告、git stderr 都先经过 redact，任何 URL 里的 user:token@ 和 Bearer 都被遮蔽。
- 并发安全：github_publish 声明 isConcurrencySafe: false，同一目录两次 git 不会撞索引锁。

HTTP 接口

| 方法 | 路径 | 用途 |
| GET | /plugins/dsh-github-aide/status | 令牌状态、默认值、工作区、能力 |
| POST | /plugins/dsh-github-aide/preflight | 只读预检（{ path? }） |
| POST | /plugins/dsh-github-aide/publish | 发布（参数同工具） |
| POST | /plugins/dsh-github-aide/config | { token } / { clear: true } / {} 校验 |

路由只接受同源/回环请求。

验证

node --test test/.test.mjs # 128 项：纯逻辑 + 假 API + 真实 git 的离线端到端
node test/verify.mjs # 32 项，自带的轻量断言运行器
node scripts/apply-harness.mjs # 12 项：用假 Cordis ctx 验证 apply() 注册 3 个工具、4 条路由、1 个设置命名空间
node scripts/live-smoke.mjs # 11 项：真实 git + 本地 bare 仓库的发布/分叉/冲突/强制推送
node scripts/http-check.mjs http://127.0.0.1:PORT # 对已启动的 host 做 HTTP 探测（未安装时自动跳过）

全部离线运行，不需要 DSH 包、不联网、不需要真实 GitHub 令牌。

目录结构

index.js Host 半：设置、3 个 agent 工具、HTTP 路由 client.js Web 面板 lib/config.js 设置默认值 + 凭据库 token 存取 lib/github.js 最小 GitHub REST 客户端（viewer / scopes / 查仓库 / 建仓库） lib/git.js git 子进程封装 + 内存 askpass + force-with-lease lib/detect.js 技术栈识别、.gitignore、凭据特征、身份推导 lib/scan.js 有界目录遍历 + 凭据扫描（不跟随符号链接） lib/publish.js 预检与发布编排（依赖注入，可离线测） lib/workspace.js 工作区/目录解析、仓库名 slug lib/errors.js 统一错误类型 + 脱敏 lib/update-notice.js harness 升级提醒 scripts/ 安装、升级监视、离线冒烟、HTTP 校验

故障排查

| 现象 | 原因与处理 |
| No GitHub token is configured | 设置 GITHUB_TOKEN，或用 github_configure 存一个，然后重启 DSH |
| HTTP 401 / TOKEN_REJECTED | token 过期或错误，重新签发 |
| HTTP 403 / PERMISSION | 按返回的 x-accepted-github-permissions 补权限（fine-grained 通常是 contents=write、administration=write 或 repository_creation=write） |
| 自己的仓库却 404 | fine-grained token 需要勾选该仓库，并授予 Contents 写权限 |
| SENSITIVE_BLOCKED | 检查扫描命中的文件；确认无风险后带 allowSensitive=true 重试 |
| REBASE_CONFLICT | 在项目里手动解决冲突，或带 force 重跑（仅 --force-with-lease） |
| PUSH_REJECTED | 重试；non-fast-forward 会提示先 rebase 或用 force |
| TLS_UNTRUSTED | TLS 中间人代理/加速器：把其根证书 PEM 指给 NODE_EXTRA_CA_CERTS 后重启 DSH |
| GIT_MISSING | 安装 git 并重启 DSH，让新 PATH 生效 |
| 插件不出现 | 确认 cordis.patch.yml 有加载行、包在 profile 的 node_modules/ 下，然后重启 |

许可证

MIT —— 见 LICENSE。行为与部分实现来自上述两个 MIT/开源插件，感谢原作者；见 NOTICE。