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

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 中的约束模型补偿，而不是削弱沙箱。
• 显式代理决策 —— 全局 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	浏览器半边：行配置页（手写工厂包，无构建步骤）
lib/config.js	设置 schema、默认值、实时读取、运行时选项解析
lib/settings.js	宿主设置接线：插件自有页面策略与 options thunk
lib/net.js、lib/tunnel.js	路由感知 HTTP 层；零依赖 CONNECT 代理隧道
lib/routes/	每条路由一个模块：api（GET-only REST）、gh（CLI）、git（协议）、html（页面解析）、mirror（raw 镜像）
lib/core/	每次调用的运行时装配与 pr/issue/file/probe 聚合器
lib/tools/	五个模型工具
lib/cache.js、lib/render.js、lib/util.js	TTL 缓存、文本渲染、守卫与整形
lib/skill.js、lib/guidance.js	技能内容与提示注入段落
test/	无运行时依赖的行为测试（见 开发）
docs/	设计与分析文档

开发

无构建步骤：插件是纯 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