dsh-github-router

dsh-github-router

English | 中文

为 DeepSeek Harness 项目提供只读的 GitHub 访问——通过内部多路由（API、gh CLI、git 协议、页面 HTML、镜像）的工具加载 PR、issue、文件与 API 数据，agent 不再需要在终端里反复对抗 TLS 或代理故障。

一个 DeepSeek Harness 插件捆绑包，为 agent 提供无需终端重试的 GitHub 读取能力：

• 五个只读工具 —— github_probe、github_pr、github_issue、github_file、github_api，外加 github-router 技能与系统提示引导段落。整个包内不存在任何写入、推送、评论或变更能力。
• 工具内路由 —— 每个请求都在宿主进程侧执行（不受沙箱 TLS/代理限制），并按路由阶梯回退：api.github.com（直连 → 代理）→ gh CLI（只读子命令）→ git 协议（插件自有 fetch 缓存，或对本地克隆仅做 log/diff/show 读取）→ PR/issue 页面 HTML（严格 JSON 岛提取）→ 用户配置的 raw 镜像。
• 一次调用、结构化结果 —— PR 一次返回元数据、讨论、评审、提交、变更文件与 diff，每个部件标注来源路由；失败时返回路由矩阵，而不是十几条重试过的终端命令。
• 连通性探针 —— github_probe 一次调用报告宿主侧哪些路由存活，附耗时与推荐路由链。
• 零运行时依赖 —— peer 依赖由 DSH profile 解析；代理请求走插件自带的 CONNECT 隧道（不依赖第三方 HTTP 栈），因此可以完全离线安装。
• 框架级插件设置页 —— 侧栏 插件（Plugins） 页打开本插件卡片即显示配置区（该行上的「配置」控件打开同一表单）（框架声明式配置：插件导出 Config schema，框架以 Loader entry id dsh-github-router 作为设置命名空间服务到浏览器、派生表单、校验并落盘写入；dsh-github-router 设置命名空间含 secret token、代理、路由开关、缓存 TTL、字节上限）。编辑本地暂存、保存才写入；被用户覆盖的字段带徽标与「恢复默认」控件；token 为只写字段，留空表示保持已存 token，页面提供「清除已保存的 token」控件。
• 上下文效率 —— 按类别 TTL 的响应缓存、全局字节上限、带截断注记的列表上限，以及限流余量提示。

环境要求

• Node.js >= 22.19
• 可选：gh 路由需要已安装且认证的 gh CLI；git 路由需要 git

安装

从 npm：

dsh plugin --profile web add dsh-github-router

从本地检出（开发）：

dsh plugin --profile web add link:<本仓库的绝对路径>

从 git 仓库：

dsh plugin --profile web add github:<owner>/dsh-github-router

然后重启 DSH 后端——宿主组合在进程启动时装载。新会话中即可使用 github_probe、github_pr、github_issue、github_file、github_api， 以及 github-router 技能。

兼容性

本插件跟随 DSH 的插件 API 走，而 DSH 在快速迭代，不保证跨版本兼容。 请选择与你的 DeepSeek Harness 版本匹配的插件版本：

该映射同时记录在 package.json 的 dsh.compatibility.dshReleases 中。

使用

Agent 侧：

github_probe                                                  # 当前哪些路由存活
github_pr { owner: "o", repo: "r", number: 12 }               # PR 全貌
github_pr { owner: "o", repo: "r", number: 12, localRepo: "C:/src/r" }  # 从本地克隆读提交与 diff
github_issue { owner: "o", repo: "r", number: 34 }
github_file { owner: "o", repo: "r", path: "src/index.js", ref: "main" }
github_api { path: "/repos/o/r/commits", query: { per_page: 5 } }

行为说明：

• 路由顺序按部件类型固定：先 API（直连后代理），再 gh，再页面 HTML（代理优先——直连 TLS 被重置的机器通常能经代理取到页面），再 git，最后镜像。每个部件记录其 serving 路由。
• 匿名 API 使用受限流（每 IP 60 次/小时）；配置 token（设置项或 GITHUB_TOKEN）后为 5000 次/小时。响应缓存可省配额；forceRefresh 绕过缓存。
• 镜像默认关闭——它们是会看到请求路径的第三方；只有在接受这一点时才在配置页中启用。
• git 路由绝不写入用户仓库：本地克隆只做 git log/diff/show 读取，fetch 仅发生在插件自有缓存目录 <DSH_HOME>/storages/dsh-github-router/ 下。

配置

侧栏 插件（Plugins） 页 → dsh-github-router bundle 卡片：打开该卡片即 在描述与部件之间直接渲染插件的配置区；该行上的配置控件打开同一 表单。页面外框由框架负责：它读取本插件导出的 schema、 把 dsh-github-router 命名空间服务到浏览器，并渲染保存控件。被用户覆盖的字段带徽标和「恢复默认」控件，清空字段即回退到下方 默认值。token 为只写字段：留空表示保持已存 token，「清除已保存的 token」 控件才会暂存删除并在保存时写入。同样的值也可以在组合（profile 的 cordis.patch.yml）中作为插件基础配置写入；页面按用户覆盖，且保存的值在 下一次工具调用即生效。

工作原理

• 宿主侧执行 —— 插件代码运行在宿主进程，沙箱的 TLS 凭据重置与代理错乱完全不适用。这一不受限的令牌由 SECURITY.md 中的约束模型补偿，而不是削弱沙箱。
• 显式代理决策 —— 全局 fetch 不继承环境代理；每次尝试显式选择直连或代理，代理请求走零依赖 CONNECT 隧道（node:http/node:tls），TLS 对目标主机名校验，accept-encoding: identity。
• 严格解析 —— 页面 HTML 路由只提取 react-app.embeddedData JSON 岛并执行 JSON.parse（绝不求值）；有界 BFS 只拷贝白名单字段，CSRF token 与原始载荷绝不进入模型。
• 纯 argv 子进程 —— 每次 gh/git 调用都是固定参数列表的 argv 数组；用户输入经正则校验后才进入 argv，全插件无 shell 插值。
• 工具契约 —— 规范值为无损失 JSON（数组不挂侧属性）、字节受限，并渲染为带路由归属的紧凑文本。
• 技能与引导 —— github-router 技能教授工具优先用法与"GitHub 读取不升级沙箱权限"规则；一条系统提示段落（dsh-github-router:guidance，order 118）提醒每个会话 github_* 工具是合规路径。

项目结构

开发

无构建步骤：插件是纯 ESM，测试直接用 Node 运行（mock ctx 代替 DSH 服务；真实的 defineTool 校验每个 schema）：

npm test
# 或：node --test --test-isolation=none "test/*.test.js"

测试完全离线——覆盖 JSON 岛提取、入参守卫、URL 构建、TTL 缓存、提交日志 解析、隧道请求头与 apply() 装配。开发循环与离线 peer 解析见 CONTRIBUTING.md。

安全

构造上只读：不存在写入动词；token 只附加到 api.github.com 且在每条 边界脱敏；页面载荷按白名单提取；唯一的磁盘写入是 <DSH_HOME>/storages/dsh-github-router/ 下的两个插件自有缓存。完整威胁 模型与缓解清单见 SECURITY.md。

文档

• docs/design.md — 架构、路由阶梯、缓存与约束模型、已知局限
• SECURITY.md — 威胁模型与补偿控制
• CHANGELOG.md — 版本历史

许可证

MIT