前言¶
在 DeepSeek Harness（DSH）里做智能体或插件开发时，经常要把当前工作区或某个本地项目推到 GitHub：既要建仓库、初始化 git、提交和推送，又要避免把 .env、token 之类写进远端。社区里原先有侧重「工作区同步」和「项目预检上传」的两套插件，维护与令牌解析路径也不完全一致。maxid/dsh-github-aide 把这两类能力合并成一套：同一套令牌解析、GitHub REST 客户端、git 层和设置命名空间 github-aide，既支持发布当前 DSH 工作区，也支持指定任意目录，并在发布前做只读预检与机密扫描。
下面按定位、能力、安装、用法和注意事项说明。
这是什么¶
dsh-github-aide 是 DSH 的联网类插件，维护者为 maxid。仓库：https://github.com/maxid/dsh-github-aide；社区目录页：https://www.skillhub.cn/plugins/maxid/dsh-github-aide。
一句话：在 DSH 内完成「预检 →（可选）生成 .gitignore → 创建或复用 GitHub 仓库 → 本地 git 初始化/提交 → 处理远端分叉 → 推送」，令牌保存在 DSH 凭据库，不写入 settings.yaml 或 git 配置。
核心功能¶
资料中列出的能力如下。
| 能力 | 说明 |
|---|---|
| 项目预检 | 目录内容、技术栈、体积、凭据扫描、git 状态、GitHub 账号、同名仓库是否存在 |
| 机密扫描 | 命中 .env、私钥、ghp_*、AKIA*、sk-* 等特征时默认拦截发布 |
.gitignore 生成 |
无 .gitignore 时按识别到的技术栈生成；已有则不改动 |
| 创建仓库 | GitHub 上不存在则创建（默认私有），已存在则复用 |
| 初始化 git | 仅在还不是仓库时执行；沿用已有分支，新仓库用 main |
| 提交 | 暂存整棵工作树并提交；无变更时复用 HEAD |
| 处理远端分叉 | 推送前 fetch + rebase；冲突时回滚并报告 REBASE_CONFLICT |
| 推送 | 令牌经内存中的 askpass 传递，origin 为不含凭据的 HTTPS URL |
| 只读预览 | github_status 或 dryRun 只报告将执行的操作，不写文件、不建仓库 |
| Web 面板 | 侧边栏填令牌与目录 → 预检 → 发布 |
插件还提供三个 Agent 工具：github_publish（发布）、github_status（只读预检）、github_configure（保存或清除 token）。对话示例（来自 README）：
你： 把这个项目传到 GitHub
DSH： 已把 12 个变更文件发布到 maxid/my-project（分支 main）。
仓库：https://github.com/maxid/my-project
环境要求¶
- DeepSeek Harness：
>=0.2.1-rc.3 <0.3.0-0（package.json中engines.dsh；README 写明在0.2.1-rc.5与桌面版0.2.1-rc.3上验证过加载） - Node.js 22+
PATH中有git（不需要ghCLI）- 一个 GitHub personal access token
插件 tag 与 DSH 官方版本对应，命名形如 dsh-v<版本>。当前 README 示例为 DSH 0.2.1-rc.5 对应 tag dsh-v0.2.1-rc.5。
安装与启用¶
推荐用 DSH 插件命令（profile 名按实际环境替换）：
dsh plugin --profile desktop add "link:$PWD"
若从 GitHub 按 DSH 版本安装，README 给出的命令为：
dsh plugin --profile desktop add "github:maxid/dsh-github-aide#dsh-v0.2.1-rc.5"
也可将仓库复制进 profile 后，用附带脚本声明（可重复执行，会打印写入路径）：
node scripts/install.mjs --profile desktop
装完后重启 DSH。脚本会把插件放到 profile 的 .local-plugins/ 与 node_modules/，加入 dsh.profile.bundles，并在 cordis.patch.yml 写入加载行。
认证与默认设置¶
Token 来源优先级：环境变量 GITHUB_TOKEN 或 GH_TOKEN → 对话中通过 github_configure 存入凭据库 → Web 面板「GitHub 发布」保存并校验。
Classic token 需要 repo（仅公开仓库可用 public_repo）；fine-grained 需要 Contents: Read and write，若由插件创建仓库还需 Administration: Read and write（或账户级 Repository creation）。
设置命名空间为 github-aide，可在 设置 → 插件 或 profile 的 cordis.patch.yml 中配置，例如：
- id: github-aide
name: dsh-github-aide
config:
owner: maxid
visibility: private
timeoutMs: 600000
常用键包括：owner、visibility（默认 private）、branch、commitMessage、allowSensitive、autoIgnore（默认 true）、timeoutMs（默认 600000）、maxScanFiles（默认 8000）等，完整表见仓库 README。
典型用法¶
1. 只读预检（不写盘）
调用工具 github_status(path?)，或在面板点「预检（只读）」。返回仓库名/所有者/分支、技术栈、扫描命中、git 状态、远端是否存在、令牌来源等。
2. 发布
github_publish 主要参数：path（默认工作区根）、repo、owner、visibility、branch、commitMessage、dryRun、allowSensitive、autoIgnore、push、force 等。dryRun: true 时只预演；机密扫描命中默认中止，需显式 allowSensitive=true 才继续。
3. HTTP 接口（Host 已启动时）
同源/回环请求：GET /plugins/dsh-github-aide/status；POST .../preflight、.../publish、.../config（参数与工具/面板一致）。
适用场景与注意¶
适合在 DSH 会话或面板里快速把本地项目同步到 GitHub、且希望发布前有预检与机密拦截的场景。合并后只需维护一套令牌与 git 行为，比分别安装 sync/upload 两类插件更省事。
务必注意：
- 插件以当前 DSH 进程权限运行；安装前应自行查看源码与 MIT 许可证，确认行为可接受。
- 凭据扫描默认可拦截发布；确认无风险后再使用
allowSensitive。 github_publish声明isConcurrencySafe: false，同一目录不宜并发两次 git 操作。- 社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本插件是社区维护的联网工具之一。
常见错误如 No GitHub token is configured、SENSITIVE_BLOCKED、REBASE_CONFLICT、HTTP 403 / PERMISSION 等，README「故障排查」表中有对应原因与处理方式。
结尾¶
dsh-github-aide 把 DSH 工作区发布与任意目录上传合并为一条流水线：只读预检、机密扫描、.gitignore 生成、建仓、提交、分叉协调与推送，令牌留在 DSH 凭据库与内存 askpass 中。需要安装命令、工具参数与安全设计细节时，以仓库 README 为准。
- 目录页：https://www.skillhub.cn/plugins/maxid/dsh-github-aide
- GitHub：https://github.com/maxid/dsh-github-aide
