dsh-github-router 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-19
+
+First release.
+
+### Added
+
+- Five read-only model tools: `github_probe`, `github_pr`, `github_issue`, `github_file`, `github_api`
+- In-tool route ladder: api.github.com (direct → CONNECT-tunnel proxy) → gh CLI (read-only subcommands) → git protocol (plugin fetch cache + read-only local repo reads) → PR/issue page HTML (strict `react-app.embeddedData` JSON extraction) → user-configured raw mirrors (off by default), with per-part route attribution on every result
+- `github_probe` connectivity matrix with per-route timings and a recommended route chain
+- TTL response cache with atomic writes and corruption-tolerant reads
+- Settings: the `dsh-github-router` namespace on the official settings seam (secret token / `tokenEnv` credential ref, proxy, route switches, cache TTLs, byte caps, granted local repos), an independent Settings page (the dsh-notification `settings.section` mechanism; common fields up top, the long tail in a collapsed "Advanced settings" disclosure), and plugin-owned `/dsh-github-router/config` web routes (the dsh-market pattern) with same-origin enforcement and revision fencing
+- `github-router` skill and a system-prompt guidance section (order 118)
+- Zero runtime dependencies: zero-dependency CONNECT tunnel for proxied requests; peers resolve from the DSH profile
+- 72 offline tests (`node --test`) covering extraction, guards, cache, tunnel, tool wiring, client bundle, config routes, and localization compliance
+- Documentation: bilingual README, SECURITY, design notes, and a development guide
+
+### Security
+
+- Read-only by construction: no write/push/comment/mutation verb exists anywhere
+- Tokens attach only to api.github.com and are redacted on every wire boundary
+- Page HTML is parsed with `JSON.parse` only (never evaluated); a bounded BFS copies a whitelist of fields
+- Subprocess calls are argv arrays with fixed flag lists — no shell interpolation
+- Configuration writes require same-origin POSTs and are body-capped

package/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing
+
+Thanks for your interest in dsh-github-router. This plugin is small,
+plain-ESM, and dependency-free at runtime — the development loop is
+correspondingly simple.
+
+## Development loop
+
+```bash
+npm test
+# or: node --test --test-isolation=none "test/*.test.js"
+```
+
+The tests run with Node directly, with zero network access. A mock cordis
+context stands in for the DSH services, while the real
+`@deepseek-ai/dsh-tools` `defineTool` validates every tool schema — so
+schema mistakes fail in `test/apply.test.js` rather than at host boot.
+
+After changing anything in `lib/`, re-run the tests and then reinstall the
+plugin into a local profile:
+
+```bash
+dsh plugin --profile <profile> add link:<absolute-path-to-this-repo>
+```
+
+Restart the DSH backend to pick up host-side changes (the host composition
+loads at process start).
+
+## Offline peer resolution
+
+The plugin's imports (`@deepseek-ai/dsh-tools`, `dsh-settings`,
+`dsh-credentials`, `schemastery`, `cordis`) are peer dependencies and
+resolve from the DSH profile in production. To run the tests without a
+registry round-trip, create a local junction inside the checkout:
+
+```powershell
+New-Item -ItemType Junction -Path node_modules\@deepseek-ai -Target <dschome>\node_modules\@deepseek-ai\dsh\node_modules\@deepseek-ai
+```
+
+(`node_modules/` is git-ignored; the junction is a local convenience only.)
+
+## Conventions
+
+- **Plain ESM, no build step.** No TypeScript, no bundler.
+- **One module per concern** — `lib/routes/*` are transport adapters with no
+  knowledge of the tools; `lib/core/*` aggregate routes; `lib/tools/*` are
+  the only modules that touch `defineTool`.
+- **No shell interpolation.** Every subprocess is an argv array; anything
+  user-derived must pass a guard in `lib/util.js` first.
+- **Lossless JSON.** Tool execute results must round-trip
+  `JSON.parse(JSON.stringify(value))` unchanged — never attach enumerable
+  side properties to arrays, never return `undefined`-valued fields.
+- **Tests for every guard and parser.** Input guards, the JSON-island
+  walker, the tunnel request head, and the TTL cache all have offline
+  tests; add one whenever behavior changes.
+
+## Security rules for contributions
+
+This plugin runs host-side with the host token. Before adding anything,
+re-read [SECURITY.md](SECURITY.md). Hard rules:
+
+1. **No write capability, ever.** No POST/PATCH/PUT/DELETE, no push, no
+   comments. If a mutating capability is ever proposed, it must be a
+   separate tool behind an explicit user-facing consent surface — and it
+   still needs a strong justification to exist here.
+2. **No execution of remote content.** Page payloads are `JSON.parse`-only;
+   never introduce `eval`/`Function` or any HTML/script interpretation.
+3. **Secrets stay out of outputs.** Tokens attach only to api.github.com;
+   proxy URLs in error text must be credential-stripped.
+4. **Bounded everything.** Every response body, walk, list, and retry needs
+   an explicit cap with a visible truncation note.
+
+## Releasing
+
+1. Bump `version` in `package.json`, update `CHANGELOG.md` (Keep a
+   Changelog), commit.
+2. `npm test` (runs via `prepublishOnly` as well).
+3. `npm publish` and verify the package through
+   `dsh plugin --profile <profile> add dsh-github-router` in a fresh
+   profile.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-github-router contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# dsh-github-router
+
+**English** | [中文](README.zh.md)
+
+> Read-only GitHub access for a DeepSeek Harness project — load PRs, issues, files, and API data through tools that route internally (API, gh CLI, git protocol, page HTML, mirrors), so an agent never burns turns fighting shell-side TLS or proxy failures.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js >= 20.18](https://img.shields.io/badge/Node.js-%3E%3D20.18-brightgreen)](https://nodejs.org/)
+[![npm version](https://img.shields.io/npm/v/dsh-github-router)](https://www.npmjs.com/package/dsh-github-router)
+
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin bundle that gives agents GitHub reads without shell retries:
+
+- **Five read-only tools** — `github_probe`, `github_pr`, `github_issue`, `github_file`, `github_api` — plus the `github-router` skill and a system-prompt guidance section. No write, push, comment, or mutation capability exists anywhere in the package.
+- **In-tool routing** — every request runs host-side (outside the sandbox's TLS/proxy restrictions) and falls through a route ladder: `api.github.com` (direct → proxy) → `gh` CLI (read-only subcommands) → git protocol (plugin fetch cache, or a local clone read with log/diff/show only) → PR/issue page HTML (strict JSON island extraction) → user-configured raw mirrors.
+- **One call, structured outcome** — PRs come back with metadata, discussion, reviews, commits, changed files, and the diff, each part annotated with the route that served it; failures return a route matrix instead of a dozen retried shell commands.
+- **Connectivity probe** — `github_probe` reports which routes are live from the host in one call, with timings and a recommended route chain.
+- **Zero runtime dependencies** — peers resolve from the DSH profile; proxied requests travel through the plugin's own CONNECT tunnel (no third-party HTTP stack), so the package installs fully offline.
+- **Settings page** — an independent Settings entry ("GitHub Router", like the 通知 section): the `dsh-github-router` settings namespace (secret token, proxy, route switches, cache TTLs, byte caps) with staged edits, save/discard, and override badges.
+- **Context efficiency** — response caching with per-kind TTLs, byte caps everywhere, list caps with truncation notes, and rate-limit surfacing.
+
+## Requirements
+
+- Node.js >= 20.18
+- A DSH profile composed from `@deepseek-ai/dsh-base` (it provides the `tools`, `subprocess`, `skills`, `settings`, and `credentials` services the plugin uses)
+- Optional: the `gh` CLI (authenticated) for the gh route; `git` for the git route
+
+## Install
+
+From npm:
+
+```bash
+dsh plugin --profile web add dsh-github-router
+```
+
+From a local checkout (development):
+
+```bash
+dsh plugin --profile web add link:<absolute-path-to-this-repo>
+```
+
+From a git host:
+
+```bash
+dsh plugin --profile web add github:<owner>/dsh-github-router
+```
+
+Then **restart the DSH backend** — the host composition loads at process start. The tools appear in new sessions: `github_probe`, `github_pr`, `github_issue`, `github_file`, `github_api`, plus the `github-router` skill.
+
+## Usage
+
+Agent side:
+
+| Tool | What it does |
+| ---- | ------------ |
+| `github_probe` | One-shot connectivity matrix (api direct/proxy, gh installed/authed, git ls-remote, page direct/proxy, mirrors, token presence) with timings and a recommended route chain. Call first when access fails or is slow. |
+| `github_pr` | Full PR view: metadata, description, discussion (issue + inline review comments), reviews, commits, changed files, and the unified diff, each with route attribution. Parts toggle (`includeDiscussion`/`includeReviews`/`includeCommits`/`includeFiles`/`includeDiff`) and cap (`maxDiffBytes`/`maxItems`). `localRepo` (or session-cwd auto-detection) reads commits/diff from a local clone with zero network. |
+| `github_issue` | Issue metadata, body, labels, and comments, with route attribution. |
+| `github_file` | File content (or directory listing) at a branch/tag/sha via api contents → raw → mirrors → git; returns size, truncation state, and the serving route. |
+| `github_api` | Validated **GET-only** escape hatch for any `api.github.com` endpoint; query values sanitized, responses cached, rate-limit headers surfaced, errors carry stable codes. |
+
+```text
+github_probe                                                  # which routes are live right now
+github_pr { owner: "o", repo: "r", number: 12 }               # full PR view
+github_pr { owner: "o", repo: "r", number: 12, localRepo: "C:/src/r" }  # commits/diff from a local clone
+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 } }
+```
+
+Behavior notes:
+
+- Route order is fixed per part type: API first (direct then proxy), then gh, then page HTML (proxy-first — machines with reset direct TLS usually reach pages through the proxy), then git, then mirrors. Each part records the route that served it.
+- Anonymous API use is rate-limited (60 requests/hour per IP); configure a token (Settings or `GITHUB_TOKEN`) for 5000/hour. Responses are cached to save quota; `forceRefresh` bypasses the cache.
+- Mirrors are **off by default** — they are third parties that see requested paths; enable them in settings only if you accept that.
+- The git route never writes to user repositories: local clones are read with `git log`/`diff`/`show` only, and fetches happen exclusively in the plugin-owned cache under `<DSH_HOME>/storages/dsh-github-router/`.
+
+## Configuration
+
+Settings → **GitHub Router** opens an independent settings page (a nav
+entry registered into `settings.section`, the same mechanism as the 通知
+section): edits are staged locally and written only on save, fields
+overridden by the user are badged, and blank fields fall back to the
+defaults below. The same values can be set in the composition (profile
+`cordis.patch.yml`) as the plugin's base config; the Settings UI overrides
+per user.
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `token` | — | Literal GitHub token (secret; redacted on the wire, write-only input). Prefer `tokenEnv`. |
+| `tokenEnv` | `GITHUB_TOKEN` | Environment variable / credential ref naming the token. |
+| `proxy` | `''` | Proxy URL for proxy attempts. `''` inherits ambient `HTTP(S)_PROXY`; `direct` never proxies. |
+| `directTimeoutMs` / `proxyTimeoutMs` | 8000 / 15000 | Per-attempt timeouts. |
+| `retries` | 1 | Retries for idempotent GETs on 429/5xx (honors `Retry-After`). |
+| `routesApi` / `routesGh` / `routesGit` / `routesHtml` / `routesMirror` | on / on / on / on / **off** | Route switches (the card shows them as checkboxes). |
+| `mirrors` | `[]` | Raw-content mirror bases, e.g. `["https://ghproxy.net"]`. |
+| `cacheTtlMeta` / `cacheTtlContent` | 300 / 86400 | Response cache TTLs (PR/issue metadata vs immutable-ish content), in seconds. |
+| `maxBytes` | 1048576 | Byte cap for every response body read by the plugin. |
+| `repos` | `[]` | Local repositories granted for read-only git-route reads. |
+| `gitCacheDir` | `''` | Plugin fetch-cache dir; `''` = `<DSH_HOME>/storages/dsh-github-router/git`. |
+
+## How it works
+
+- **Host-side execution** — plugin code runs in the host process, so the sandbox's TLS credential resets and proxy misrouting never apply. The unrestricted token is compensated by the confinement model in [SECURITY.md](SECURITY.md) — not by weakening the sandbox.
+- **Explicit proxy decisions** — global `fetch` does not inherit ambient proxy env; each attempt gets an explicit direct/proxy choice, and proxied requests use a zero-dependency CONNECT tunnel (`node:http`/`node:tls`) with target-hostname TLS validation and `accept-encoding: identity`.
+- **Strict parsing** — the page-HTML route extracts only `react-app.embeddedData` JSON islands and runs `JSON.parse` (never evaluated); a bounded BFS copies a whitelist of fields, so CSRF tokens and the raw payload never reach the model.
+- **Argv-only subprocesses** — every `gh`/`git` invocation is an argv array with fixed flag lists; user input reaches argv only after regex validation, and nothing is shell-interpolated.
+- **Tool contract** — canonical values are lossless JSON (arrays carry no side properties), byte-capped, and rendered as compact text with route attribution.
+- **Skill & guidance** — the `github-router` skill teaches tool-first usage and the "never escalate for GitHub reads" rule; one system-prompt section (`dsh-github-router:guidance`, order 118) reminds every session that the github_* tools are the sanctioned path.
+
+## Project layout
+
+| Path | Purpose |
+| ---- | ------- |
+| `cordis.patch.yml` | Profile patch layer inserting the `dsh-github-router` row |
+| `lib/index.js` | Host plugin: settings section, five tools, skill, guidance |
+| `lib/client.js` | Browser half: the independent Settings page (hand-written factory bundle, no build step) |
+| `lib/config.js` | Settings schema, defaults, runtime option resolution |
+| `lib/net.js`, `lib/tunnel.js` | Route-aware HTTP layer; zero-dependency CONNECT proxy tunnel |
+| `lib/routes/` | One module per route: `api` (GET-only REST), `gh` (CLI), `git` (protocol), `html` (page parse), `mirror` (raw mirrors) |
+| `lib/core/` | Per-call runtime assembly and the `pr`/`issue`/`file`/`probe` aggregators |
+| `lib/tools/` | The five model tools |
+| `lib/cache.js`, `lib/render.js`, `lib/util.js` | TTL cache, text renderers, guards and shaping |
+| `lib/skill.js`, `lib/guidance.js` | Skill content and prompt-injection section |
+| `test/` | Runtime-free behavior tests (see Development) |
+| `docs/` | Design and analysis documents |
+
+## Development
+
+No build step: the plugin is plain ESM and the tests run with Node directly
+(a mock ctx stands in for the DSH services; the real `defineTool` validates
+every schema):
+
+```bash
+npm test
+# or: node --test --test-isolation=none "test/*.test.js"
+```
+
+The tests are fully offline — they cover JSON-island extraction, input
+guards, URL builders, the TTL cache, commit-log parsing, the tunnel request
+head, and the apply() wiring. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
+development loop, including offline peer resolution.
+
+## Security
+
+Read-only by construction: no write verb exists, tokens attach only to
+`api.github.com` and are redacted on every boundary, page payloads are
+whitelist-extracted, and the only disk writes are the two plugin-owned
+caches under `<DSH_HOME>/storages/dsh-github-router/`. See
+[SECURITY.md](SECURITY.md) for the complete threat model and mitigation
+list.
+
+## Documentation
+
+- [docs/design.md](docs/design.md) — architecture, route ladder, cache and confinement model, known limitations
+- [SECURITY.md](SECURITY.md) — threat model and compensating controls
+- [CHANGELOG.md](CHANGELOG.md) — release history
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,156 @@
+# dsh-github-router
+
+[English](README.md) | **中文**
+
+> 为 DeepSeek Harness 项目提供只读的 GitHub 访问——通过内部多路由（API、gh CLI、git 协议、页面 HTML、镜像）的工具加载 PR、issue、文件与 API 数据，agent 不再需要在终端里反复对抗 TLS 或代理故障。
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js >= 20.18](https://img.shields.io/badge/Node.js-%3E%3D20.18-brightgreen)](https://nodejs.org/)
+[![npm version](https://img.shields.io/npm/v/dsh-github-router)](https://www.npmjs.com/package/dsh-github-router)
+
+一个 [DeepSeek Harness](https://github.com/deepseek-ai/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 栈），因此可以完全离线安装。
+- **独立设置页** —— 设置中出现独立的「GitHub 路由」入口（与「通知」同机制）：`dsh-github-router` 设置命名空间（secret token、代理、路由开关、缓存 TTL、字节上限），编辑暂存、保存/放弃、覆盖徽标。
+- **上下文效率** —— 按类别 TTL 的响应缓存、全局字节上限、带截断注记的列表上限，以及限流余量提示。
+
+## 环境要求
+
+- Node.js >= 20.18
+- 由 `@deepseek-ai/dsh-base` 组合的 DSH profile（提供插件使用的 `tools`、`subprocess`、`skills`、`settings`、`credentials` 服务）
+- 可选：gh 路由需要已安装且认证的 `gh` CLI；git 路由需要 `git`
+
+## 安装
+
+从 npm：
+
+```bash
+dsh plugin --profile web add dsh-github-router
+```
+
+从本地检出（开发）：
+
+```bash
+dsh plugin --profile web add link:<本仓库的绝对路径>
+```
+
+从 git 仓库：
+
+```bash
+dsh plugin --profile web add github:<owner>/dsh-github-router
+```
+
+然后**重启 DSH 后端**——宿主组合在进程启动时装载。新会话中即可使用
+`github_probe`、`github_pr`、`github_issue`、`github_file`、`github_api`，
+以及 `github-router` 技能。
+
+## 使用
+
+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` 端点；查询值净化、响应缓存、限流头提示、错误带稳定代码。 |
+
+```text
+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/` 下。
+
+## 配置
+
+设置 → **GitHub 路由** 打开独立设置页（注册进 `settings.section` 的导航
+入口，与「通知」区块同机制）：编辑内容先本地暂存、点保存才落盘，被用户
+覆盖的字段带标记，留空字段回退到下方默认值。同样的值也可以在组合
+（profile 的 `cordis.patch.yml`）中作为插件基础配置写入；设置 UI 按用户
+覆盖。
+
+| 字段 | 默认 | 含义 |
+| --- | --- | --- |
+| `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` | 宿主插件：设置段、五个工具、技能、引导 |
+| `lib/client.js` | 浏览器半边：独立设置页（手写工厂包，无构建步骤） |
+| `lib/config.js` | 设置 schema、默认值、运行时选项解析 |
+| `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）：
+
+```bash
+npm test
+# 或：node --test --test-isolation=none "test/*.test.js"
+```
+
+测试完全离线——覆盖 JSON 岛提取、入参守卫、URL 构建、TTL 缓存、提交日志
+解析、隧道请求头与 apply() 装配。开发循环与离线 peer 解析见
+[CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 安全
+
+构造上只读：不存在写入动词；token 只附加到 `api.github.com` 且在每条
+边界脱敏；页面载荷按白名单提取；唯一的磁盘写入是
+`<DSH_HOME>/storages/dsh-github-router/` 下的两个插件自有缓存。完整威胁
+模型与缓解清单见 [SECURITY.md](SECURITY.md)。
+
+## 文档
+
+- [docs/design.md](docs/design.md) — 架构、路由阶梯、缓存与约束模型、已知局限
+- [SECURITY.md](SECURITY.md) — 威胁模型与补偿控制
+- [CHANGELOG.md](CHANGELOG.md) — 版本历史
+
+## 许可证
+
+MIT

package/SECURITY.md

@@ -0,0 +1,112 @@
+# SECURITY.md
+
+`dsh-github-router` runs **host-side with the host token** — unrestricted by
+the agent's sandbox. That freedom is compensated by construction-level
+constraints documented here.
+
+## Threat model
+
+The hostile inputs are: (1) agent-supplied tool arguments, (2) remote
+GitHub responses (API JSON, git output, HTML pages, file bytes), and (3)
+the configured proxy/mirrors (which see request URLs). The agent is assumed
+untrusted for argument content; GitHub itself is assumed untrusted for
+response content.
+
+## Hard constraints
+
+### 1. Read-only by construction
+
+- The plugin contains **no write verb**. There is no POST/PATCH/PUT/DELETE,
+  no body, no push/checkout/reset/merge into user repositories, no comment
+  or reaction endpoints. `github_api` accepts only a validated relative
+  path and always performs GET.
+- The only disk writes are: the TTL response cache and the git fetch cache,
+  both under `<DSH_HOME>/storages/dsh-github-router`. A user repository is
+  never fetched into — local clones are read with `git log`/`diff`/`show`/
+  `rev-parse`/`config --get` only, and only when the user granted the path
+  (`repos` setting), passed `localRepo`, or the session cwd's origin
+  matches the requested owner/repo.
+- Code review note: if a future change adds any mutating capability, it
+  must be its own tool behind an explicit user-facing consent surface.
+
+### 2. No shell interpolation
+
+Every subprocess (`gh`, `git`) is spawned as an **argv array** through the
+platform subprocess service. Nothing is concatenated into a shell command
+string, so argument injection (spaces, `;`, `|`, `--flags`) cannot escape
+the argv element. User-derived values reach argv only after validation:
+
+- `owner`/`repo`: `/^[A-Za-z0-9][A-Za-z0-9._-]*$/`
+- `number`: positive integer
+- api path: starts `/`, no `..`, no spaces/control chars, ≤ 2048 chars
+- file path: relative, no `..`, no control chars, ≤ 1024 chars
+- ref: plain name/sha, rejects leading `-`, `..`, `~^:*?[]`, ≤ 512 chars
+- query values: short strings without control chars, finite numbers,
+  booleans; ≤ 20 entries
+
+### 3. Token handling
+
+- The token is attached **only** to `api.github.com` requests (never to
+  proxies, mirrors, raw hosts, or the gh CLI — gh uses its own stored
+  auth).
+- Settings declare the token with `role('secret')`: it is redacted at every
+  wire boundary, rendered as a write-only input, and never returned in tool
+  output. No output path carries it: tool results contain only parsed
+  payload fields, and failure notes carry error messages that never echo
+  request headers; proxy URLs in error text are credential-stripped.
+- Resolution order: literal setting → credentials service
+  (`credentialRef(tokenEnv)`) → environment variable. Nothing is logged.
+
+### 4. Page HTML parsing is JSON-only
+
+The PR/issue page route extracts only
+`<script type="application/json" data-target="react-app.embeddedData">`
+islands and runs **`JSON.parse`** on them — never `eval`, `Function`, or
+any executable interpretation. Extraction is a bounded BFS (depth 10, ≤
+40k nodes) that copies a whitelist of fields (title, body text, state,
+author, dates, review/discussion items) and drops everything else — CSRF
+tokens, session data, and the raw payload never reach the model. Bodies
+are HTML-tag-stripped for display and byte-capped.
+
+### 5. Proxy and mirrors
+
+- Global `fetch` does **not** inherit ambient proxy env automatically; each
+  attempt gets an explicit proxy decision (`direct` first for API/raw,
+  `proxy` first for page HTML), so a broken ambient proxy cannot silently
+  hijack traffic.
+- Proxied requests travel through the plugin's own zero-dependency CONNECT
+  tunnel (node:http/tls): TLS is validated against the target hostname
+  exactly as direct requests validate it, the request carries
+  `accept-encoding: identity`, and every body passes the same byte cap.
+  No third-party HTTP stack is involved.
+- Mirrors are **off by default**: they are third parties that see the
+  requested repo/path and can substitute bytes. Enabling them in settings
+  is an explicit user decision. Mirror responses pass through the same
+  byte caps as every other route.
+
+### 6. Response containment
+
+- Every response body (API JSON, HTML, raw files, git stdout) is
+  byte-capped (`maxBytes`, default 1 MiB); oversized bodies truncate with
+  an explicit marker.
+- Non-2xx API responses are classified into stable codes
+  (`AUTH_REQUIRED`, `RATE_LIMITED`, `NOT_FOUND`, `HTTP`, `TRANSPORT`,
+  `TIMEOUT`, `ABORTED`) so failures are cheap to reason about.
+- Cache files are parsed defensively: corrupt or expired entries are
+  dropped as misses; writes are tmp+rename (torn files degrade to a miss).
+
+## Residual risks
+
+- **Rate limits**: anonymous API use shares the host IP's 60 req/h quota.
+  Configure a token (Settings) to raise it to 5000 req/h; the cache is the
+  second line of defense.
+- **git fetch cache growth**: repeated fetches grow the cache dir; it is
+  shallow (`--depth`), and users may delete it at any time — it rebuilds
+  on demand.
+- **Mirrors/proxies see URLs**: enabling mirrors or a proxy reveals which
+  repos/files are requested. Off by default; opt-in.
+- **gh CLI surface**: only fixed subcommands are constructed, but `gh api
+  <path>` inherits gh's own scoped token permissions; paths are validated
+  and the method is GET, yet an account-scoped token with broad grants
+  could still read beyond the public surface. Prefer the API route with
+  the plugin token when least-privilege matters.

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-github-router bundle patch.
+#
+# Applied as a profile patch layer after every in-box bundle. Inserts the
+# plugin row at the profile root; later layers (or the user's own
+# cordis.patch.yml) can address it by id with the last write winning.
+- insert:
+    - id: dsh-github-router
+      name: 'dsh-github-router'