dsh-github-router

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

dsh-github-router

[English](README.md) | 中文

为 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 版本匹配的插件版本：

DeepSeek Harness · 安装

0.1.7-rc.2 · dsh-github-router@0.4.0 或最新

0.1.2 ~ 0.1.6 · dsh-github-router@0.3.2

0.1.1 及更早 · dsh-github-router@0.2.1

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

使用

Agent 侧：

工具 · 作用

github_probe · 一次性连通性矩阵（api 直连/代理、gh 安装/认证、git ls-remote、页面直连/代理、镜像、token 有无），附耗时与推荐路由链。访问失败或变慢时先调用它。

github_pr · PR 全貌：元数据、描述、讨论（issue 评论 + 行内评审评论）、评审、提交、变更文件与统一 diff，各部分标注来源路由。可用 includeDiscussion/includeReviews/includeCommits/includeFiles/includeDiff 开关部件，用 maxDiffBytes/maxItems 限幅。传 localRepo（或自动探测会话 cwd）可从本地克隆零网络读取提交与 diff。

github_issue · issue 元数据、正文、标签与评论，附路由归属。

github_file · 指定分支/标签/commit 的文件内容（或目录列表），经 api contents → raw → 镜像 → git 依次路由；返回大小、截断状态与 serving 路由。

github_api · 校验后的 GET-only 逃生舱，可访问任意 api.github.com 端点；查询值净化、响应缓存、限流头提示、错误带稳定代码。

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）中作为插件基础配置写入；页面按用户覆盖，且保存的值在

下一次工具调用即生效。

字段 · 默认 · 含义

token · — · 字面 GitHub token（secret；线上脱敏、只写输入）。优先用 tokenEnv。

tokenEnv · GITHUB_TOKEN · 指向 token 的环境变量 / 凭据引用。

proxy · '' · 代理地址。'' 继承环境变量 HTTP(S)_PROXY；direct 永不代理。

directTimeoutMs / proxyTimeoutMs · 8000 / 15000 · 单次尝试超时。

retries · 1 · 幂等 GET 在 429/5xx 上的重试次数（尊重 Retry-After）。

routesApi / routesGh / routesGit / routesHtml / routesMirror · 开 / 开 / 开 / 开 / 关 · 各路由开关（卡片中以复选框展示）。

mirrors · [] · raw 镜像基址，如 ["https://ghproxy.net"]。

cacheTtlMeta / cacheTtlContent · 300 / 86400 · 响应缓存 TTL（PR/issue 元数据 / 近似不可变内容），单位秒。

maxBytes · 1048576 · 插件读取的每个响应体的字节上限。

repos · [] · 授权只读 git 路由使用的本地仓库路径。

gitCacheDir · '' · 插件 fetch 缓存目录；'' = <DSH_HOME>/storages/dsh-github-router/git。

工作原理

• 宿主侧执行 —— 插件代码运行在宿主进程，沙箱的 TLS 凭据重置与代理错乱完全不适用。这一不受限的令牌由 [SECURITY.md](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_* 工具是合规路径。

项目结构

路径 · 用途

cordis.patch.yml · 插入 dsh-github-router 行的 profile patch 层

lib/index.js · 宿主插件：导出 Config schema、五个工具、技能、引导

lib/client.js · 浏览器半边：行配置页（手写工厂包，无构建步

…(truncated)