@karoc/dsh-proxy 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## [0.1.0]
+
+- Initial release: external DeepSeek Harness plugin providing a model-provider
+  forward proxy with per-host routing and a dedicated Settings page.
+- Host half (`src/index.ts` + `src/proxy-core.ts`): starts a loopback forward
+  proxy (HTTP + CONNECT, HTTP/HTTPS/SOCKS5 upstreams, Basic auth, per-host
+  routing, live config re-read, self-loop guard), points the process's
+  `HTTP(S)_PROXY` / `NODE_USE_ENV_PROXY` / `NO_PROXY` at it, and serves
+  `/proxy/api` (GET view, POST save / test / persist). Engine is a faithful TS
+  port of dsh-desktop's `scripts/proxy.mjs`; `test` probe and `sanitizeUpstream`
+  mirror the desktop shell's Rust implementations.
+- Client half (`src/client/*`): registers a `settings.section` (id `dsh-proxy`,
+  order 25) after the built-in Models and Model-reasoning pages. UI mirrors the
+  desktop settings window: upstream card (enable / protocol / host / port /
+  user / pass / test connection), model-provider hosts derived from
+  `settings.yaml`, other observed hosts, per-host checkboxes, and a search box.
+- Config persisted at `<DSH_HOME>/proxy.json`; changes take effect immediately
+  (the proxy re-reads the file on every request).
+- Settings page: a provider/observed-host row whose label truncates shows the
+  full label (all display names + host) in a custom hover bubble (DSH
+  `Tooltip`) — no native `title` tooltip. Overflow is measured on every commit
+  plus `ResizeObserver` / `document.fonts.ready` / window resize, so a late
+  webfont that widens the text retroactively arms the bubble; short labels stay
+  quiet.
+- Tests: `scripts/proxy-core.spec.mjs` — 13 scenarios (ported from
+  dsh-desktop's `test-proxy.mjs` plus settings-helper coverage), no external
+  network.
+- Full release tooling: bilingual README, CHANGELOG, CONTRIBUTING, release
+  gate + post-publish verification.

package/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing to dsh-proxy
+
+Thanks for helping with `dsh-proxy` — an external DeepSeek Harness plugin for
+model-provider proxying.
+
+## Development
+
+```sh
+pnpm install        # dev deps (tsdown, typescript, react types)
+pnpm typecheck      # tsc --noEmit
+pnpm test           # typecheck + scripts/proxy-core.spec.mjs (13 scenarios)
+pnpm bundle         # emit lib/index.js + lib/client.js
+```
+
+The host half (`src/index.ts` + `src/proxy-core.ts`) is pure Node — no dsh
+runtime needed to test it: `pnpm test` runs the proxy against fake origins and
+fake upstreams on `127.0.0.1` (no external network). The client half
+(`src/client/*`) is only exercised inside a running `dsh web`.
+
+### Local install without publishing
+
+To see the plugin live in the GUI, link it into a profile:
+
+```jsonc
+// ~/.dsh/profiles/web/package.json
+"dependencies": { "@karoc/dsh-proxy": "link:/path/to/dsh-proxy", ... },
+"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", ..., "dsh-proxy"] } }
+```
+
+Then `cd ~/.dsh/profiles/web && pnpm install` and **restart `dsh web`**
+(changing the plugin set requires a restart; only bundle content changes hot
+reload via the dev-server watcher).
+
+## Layout
+
+- `src/proxy-core.ts` — the forward proxy engine (ported from dsh-desktop;
+  keep behavior compatible). Pure Node, no dsh imports.
+- `src/index.ts` — host `apply`: starts the proxy, sets `*PROXY` env vars,
+  registers `/proxy/api`.
+- `src/client/` — settings page + slot registration + i18n + styles.
+
+## Release checklist
+
+Every release must be done in one pass (code + docs + changelog + version +
+tag). The gate script (`pnpm release:check`, also run by `prepack` and
+`prepublishOnly`) enforces:
+
+1. `README.md` and `README.zh.md` exist and have the **same number of `##` and
+   `###` sections** (bilingual structural sync — add/remove sections in both).
+2. `CHANGELOG.md` has a non-empty entry for the current version, as the latest
+   released entry.
+3. `package.json` version matches the latest CHANGELOG entry.
+4. Git tag `v<version>` exists and points at HEAD.
+5. Working tree is clean (everything committed).
+6. `lib/` is present and fresh (run `pnpm bundle` after touching `src/`).
+7. The version is not already published on npm.
+
+Release steps:
+
+```sh
+# 1. write code + update README.md/README.zh.md + CHANGELOG.md together
+# 2. bump version in package.json
+git add -A && git commit -m "dsh-proxy v<version>"
+git tag v<version> && git push origin v<version>
+pnpm release:check
+```
+
+### Publishing is a manual step (2FA)
+
+The npm account has two-factor authentication enabled, so **the agent cannot
+complete the publish** — OTP needs a human. Everything must be prepared to
+"one command away" (clean tree, version + tag in place, `release:check`
+passing, `npm pack --dry-run` content confirmed), then the human runs:
+
+```sh
+npm login     # 2FA
+npm publish   # runs the gate (prepack/prepublishOnly), then postpublish verifies
+```
+
+`npm publish --ignore-scripts` bypasses all gates and post-publish verification
+— treat it as a process violation. After a successful publish, `postpublish`
+polls the registry until the version is visible and verifies `dist-tags.latest`
+plus the tarball contents.
+
+### Known release-check "failures" that are actually fine
+
+- After a release, the next `release:check` fails with "version already
+  published" / "tag not at HEAD" — that's the gate protecting an already-live
+  version. Bump to the next version and tag it instead of overwriting.
+- The first publish of a brand-new package: the post-publish registry poll
+  covers the whole-package-not-yet-visible case; if it still times out, verify
+  manually with `npm view @karoc/dsh-proxy versions` — do not re-publish the
+  same version without checking.
+
+## License
+
+MIT

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 karoc
+
+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,211 @@
+# dsh-proxy
+
+English | [简体中文](README.zh.md)
+
+[![npm version](https://img.shields.io/npm/v/@karoc/dsh-proxy.svg)](https://www.npmjs.com/package/@karoc/dsh-proxy)
+[![npm downloads](https://img.shields.io/npm/dm/@karoc/dsh-proxy.svg)](https://www.npmjs.com/package/@karoc/dsh-proxy)
+[![license MIT](https://img.shields.io/npm/l/@karoc/dsh-proxy.svg)](LICENSE)
+
+An **external** DeepSeek Harness plugin: a model-provider **forward proxy** with
+**per-host routing**, plus a **Settings page** dedicated to model-provider
+proxying.
+
+It runs a loopback forward proxy inside the dsh host process, points the
+process's egress traffic at it (`HTTP(S)_PROXY` + `NODE_USE_ENV_PROXY`), and
+routes **only the hosts you select** through an optional upstream proxy
+(HTTP / HTTPS / SOCKS5, with optional Basic auth). Everything else stays
+direct. Model-provider hosts are derived from your dsh `settings.yaml`, and
+hosts observed in traffic are collected for you — both appear as checkboxes.
+
+Why an external plugin: the built-in settings pages don't cover outbound
+proxying, and adding one to a built-in package would be overwritten by the next
+official release. This package ships as an installable **bundle** that never
+touches repository source, so official updates cannot clobber it.
+
+The proxy engine and settings UI are extracted from
+[karoc/dsh-desktop](https://github.com/karoc/dsh-desktop) (behavior preserved)
+so a browser-only `dsh web` gets the same model-provider proxy controls the
+desktop shell had.
+
+## What it adds
+
+A new Settings section, **「代理 / Proxy」**, placed after the built-in
+**Models** and **Model reasoning** pages. It shows:
+
+- an **upstream proxy card**: enable toggle, protocol selector (HTTP / HTTPS /
+  SOCKS5), host, port, optional username/password, and a **Test connection**
+  button that verifies the upstream speaks its protocol;
+- a **model providers** list — hosts read from your dsh `settings.yaml`
+  (`llm-deepseek.baseURL`, `llm-pi-ai.providers.<n>.baseURL`, any `llm-*`
+  namespace), labeled with the friendly display name where available;
+- an **other observed hosts** list — hosts the proxy has seen in traffic
+  (including `registry.npmjs.org` install/update traffic), persisted into
+  `proxy.json` so they survive restarts;
+- a **search box** that filters both lists by host / name as you type.
+
+Check a host to route it through the upstream proxy. Saving writes
+`<DSH_HOME>/proxy.json`; the running proxy **re-reads the file on every
+request**, so changes take effect immediately — no dsh restart needed.
+
+### How the proxy routes traffic
+
+```
+dsh host process
+  ├─ undici fetch (model requests, web search) ──┐
+  ├─ npm / pnpm / git / child CLIs ──────────────┤  HTTP(S)_PROXY → loopback proxy
+  └─ subagents ──────────────────────────────────┘        │
+                                                          ▼
+                              127.0.0.1:<random>  forward proxy (raw net/http)
+                                                          │
+                              ┌───────────────────────────┴────────────┐
+                              ▼                                        ▼
+                     hosts in proxiedHosts                      everything else
+                     + upstream enabled                      DIRECT (loopback ALWAYS direct)
+                              │
+                              ▼
+                     upstream proxy (HTTP/HTTPS/SOCKS5, optional Basic auth)
+```
+
+Safety rules (hard-coded, not configurable):
+
+- **loopback targets are always direct** — never sent to an upstream proxy;
+- an upstream pointing back at this very proxy is treated as **disabled**
+  (self-loop guard);
+- the proxy itself uses raw `net`/`http`, so it can never route its own
+  outbound connections back through itself.
+
+### Config file
+
+```
+<DSH_HOME>/proxy.json     # $DSH_HOME, or ~/.dsh by default
+```
+
+```json
+{
+  "upstream": { "enabled": false, "protocol": "http", "host": "", "port": 0, "username": "", "password": "" },
+  "proxiedHosts": ["api.deepseek.com"],
+  "knownHosts": ["api.deepseek.com", "registry.npmjs.org"]
+}
+```
+
+`knownHosts` is written by the plugin (observed traffic); `upstream` and
+`proxiedHosts` are written from the settings page. You can also hand-edit the
+file while dsh runs — it is re-read live.
+
+## Install
+
+**Prerequisites:** a DeepSeek Harness install with the `dsh` CLI, plus [pnpm](https://pnpm.io) (the `dsh plugin` command runs pnpm under the hood). This is an installable **bundle** — it is loaded by `dsh`, not imported as a library.
+
+### From npm (recommended)
+
+The package is published to npm as `@karoc/dsh-proxy`:
+
+```sh
+dsh plugin --profile web add @karoc/dsh-proxy
+```
+
+This installs the prebuilt bundle and appends it to the `web` profile. Then **restart `dsh web`** and open **Settings → 代理 / Proxy**.
+
+### From git
+
+```sh
+dsh plugin --profile web add github:karoc/dsh-proxy#<sha>
+```
+
+A git install runs the package's `prepare` script to build the bundle. pnpm ≥ 10 requires allowlisting that build once — copy the exact package key pnpm prints into the profile's `pnpm-workspace.yaml` under `allowBuilds`, then re-run `add` (see `docs/user/develop/basic/publish.md` in the DSH repo).
+
+### Updating
+
+Bump to the newest release with pnpm update (or re-add to pick up a newer git ref):
+
+```sh
+dsh plugin --profile web update dsh-proxy
+# or, if the dependency spec is pinned: dsh plugin --profile web add dsh-proxy
+```
+
+Then **restart `dsh web`** so the new client bundle loads.
+
+### Removing
+
+```sh
+dsh plugin --profile web remove dsh-proxy
+```
+
+This removes both the dependency and its bundle layer from the `web` profile. Restart `dsh web` for the section to disappear.
+
+## Layout
+
+```
+cordis.patch.yml      # bundle layer: mounts the row that the client-modules
+                      # service discovers (dsh.client manifest)
+package.json          # dsh.bundle (patch) + dsh.client (web) + exports["./client"]
+tsdown.config.ts      # self-contained build: node half + module-table client bundle
+src/proxy-core.ts     # forward proxy engine (HTTP+CONNECT, SOCKS5/HTTPS upstream,
+                      # per-host routing, live config, test probe) — TS port of
+                      # dsh-desktop's scripts/proxy.mjs
+src/index.ts          # host apply: starts the proxy, sets *PROXY env vars,
+                      # registers /proxy/api (GET view / POST save·test·persist)
+src/client/index.ts   # client apply: register settings.section (id dsh-proxy)
+src/client/ProxySection.tsx  # the settings page (upstream card + host lists)
+src/client/styles.ts  # design-token styles (--dsw-alias-*) + injection
+src/client/locales.ts # en/zh copy
+scripts/proxy-core.spec.mjs  # behavioral tests (13 scenarios, no network)
+```
+
+### The /proxy/api route
+
+The host half serves the settings page over a same-origin HTTP route (the
+built-in `/api` prefix is reserved for the gateway, so this uses `/proxy/api`):
+
+- `GET  /proxy/api` → `{ upstream, proxiedHosts, knownHosts, hosts, providers, port }`
+- `POST /proxy/api` `{ op: 'save', upstream, proxiedHosts }` → sanitized + persisted config
+- `POST /proxy/api` `{ op: 'test', upstream }` → `{ ok, detail }`
+- `POST /proxy/api` `{ op: 'persist' }` → merge observed hosts into `knownHosts`
+
+## Build
+
+```sh
+pnpm install
+pnpm bundle          # emits lib/index.js + lib/client.js
+pnpm test            # tsc --noEmit + proxy-core.spec.mjs (13 scenarios)
+pnpm release:check   # release gate: docs/changelog/tag/tree/build/registry must all pass
+pnpm publish         # runs the gate (prepack/prepublishOnly), then postpublish verifies the live release
+```
+
+The bundle leaves the platform packages (`react`, `@deepseek-ai/cordis`,
+`@deepseek-ai/dsh-client-*`) external — they resolve at runtime from the loader's
+module table; everything else is inlined.
+
+## Notes / limitations
+
+- **The proxy is an egress point for the process, not a per-request switch the
+  model reads.** It works by pointing the process's `HTTP(S)_PROXY` at itself.
+  Requests that dsh starts *after* this plugin's host `apply()` runs (any
+  subprocess, and undici fetches whose global dispatcher is still lazy) ride
+  the proxy. A dsh-internal fetch that already materialized its dispatcher
+  before plugin load may not route through it — a dsh restart is the documented
+  remedy (the desktop shell enforces the same boundary by setting env before
+  spawning dsh).
+- `npm`/`pnpm` install/update traffic goes through the proxy like everything
+  else; toggling a host **related to install/update** takes effect on the next
+  install/update (already-in-flight operations keep their environment).
+- **Section nav icon is shell-assigned, not plugin-assigned.** The built-in
+  `ui-settings-general` `SettingsRoot.tsx` `navIcon(id)` maps known ids and
+  falls back to a gear for every other id — including this section's
+  `dsh-proxy`. The `settings.section` registration has no icon field, so an
+  external plugin cannot set it without patching the shell. When DSH exposes a
+  per-section icon, use `IconGlobeOutline14` from `dsh-client-ui-primitives`
+  for this section.
+- The desktop shell (`dsh-desktop`) keeps its own proxy and tray settings
+  window — this plugin is a standalone extraction, not a replacement. Both can
+  coexist (e.g. install `dsh-proxy` into the shell's profile to get the
+  in-dsh settings page too).
+
+## License
+
+[MIT](LICENSE)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) (development + release checklist) and
+[CHANGELOG.md](CHANGELOG.md) for version history.

package/README.zh.md

@@ -0,0 +1,160 @@
+# dsh-proxy
+
+[English](README.md) | 简体中文
+
+[![npm version](https://img.shields.io/npm/v/@karoc/dsh-proxy.svg)](https://www.npmjs.com/package/@karoc/dsh-proxy)
+[![npm downloads](https://img.shields.io/npm/dm/@karoc/dsh-proxy.svg)](https://www.npmjs.com/package/@karoc/dsh-proxy)
+[![license MIT](https://img.shields.io/npm/l/@karoc/dsh-proxy.svg)](LICENSE)
+
+一个**外部** DeepSeek Harness 插件：为**模型提供方**提供带**按主机路由**的**正向代理**，并附带一个专职设置页。
+
+它在 dsh host 进程内启动一个 loopback 正向代理，把进程的出站流量指向它（`HTTP(S)_PROXY` + `NODE_USE_ENV_PROXY`），**只把你在设置页勾选的主机**转发到可选的上游代理（HTTP / HTTPS / SOCKS5，支持可选 Basic 认证），其余全部直连。模型提供方主机从你的 dsh `settings.yaml` 读取，流量中观测到的主机也会被收集——两者都以复选框形式出现。
+
+为什么要做成外部插件：内置设置页不覆盖出站代理，而给内置包加一页会在官方下次发布时被覆盖。本包作为可安装的 **bundle** 交付，从不触碰仓库源码，官方更新无法覆盖它。
+
+代理引擎与设置 UI 抽取自 [karoc/dsh-desktop](https://github.com/karoc/dsh-desktop)（行为保持一致），让纯浏览器版的 `dsh web` 也能获得桌面壳原有的模型提供方代理控制。
+
+## 它新增了什么
+
+一个放在内置 **Models** 与 **Model reasoning** 页之后的新设置项 **「代理 / Proxy」**，包含：
+
+- **上游代理卡片**：启用开关、协议选择（HTTP / HTTPS / SOCKS5）、主机、端口、可选用户名/密码，以及**测试连接**按钮（验证上游是否会说对应协议）；
+- **模型提供方**列表——从你的 dsh `settings.yaml` 读取的主机（`llm-deepseek.baseURL`、`llm-pi-ai.providers.<n>.baseURL`、任意 `llm-*` 命名空间），有友好显示名时以显示名标注；
+- **其它已观测主机**列表——代理在流量中见过的主机（含 `registry.npmjs.org` 等安装/更新流量），持久化进 `proxy.json` 以跨重启保留；
+- **搜索框**——输入时按主机 / 名称过滤上面两个列表。
+
+勾选主机即让该主机走上游代理。保存会写入 `<DSH_HOME>/proxy.json`；运行中的代理**每个请求都重读该文件**，因此改动立即生效——无需重启 dsh。
+
+### 代理如何路由流量
+
+```
+dsh host 进程
+  ├─ undici fetch（模型请求、联网搜索）──┐
+  ├─ npm / pnpm / git / 子 CLI ──────────┤  HTTP(S)_PROXY → loopback 代理
+  └─ 子代理 ─────────────────────────────┘        │
+                                                   ▼
+                            127.0.0.1:<随机>  forward proxy（裸 net/http）
+                                                   │
+                            ┌──────────────────────┴──────────────┐
+                            ▼                                     ▼
+                    在 proxiedHosts 中的主机                  其它一切
+                    + 上游已启用                         DIRECT（loopback 恒直连）
+                            │
+                            ▼
+                    上游代理（HTTP/HTTPS/SOCKS5，可选 Basic 认证）
+```
+
+安全规则（硬编码，不可配置）：
+
+- **loopback 目标恒直连**——绝不发给上游代理；
+- 指向本代理自身的上游被当作**禁用**（防自环保护）；
+- 代理自身只用裸 `net`/`http`，所以永远不可能把自己出站连接再路由回自己。
+
+### 配置文件
+
+```
+<DSH_HOME>/proxy.json     # $DSH_HOME，默认 ~/.dsh
+```
+
+```json
+{
+  "upstream": { "enabled": false, "protocol": "http", "host": "", "port": 0, "username": "", "password": "" },
+  "proxiedHosts": ["api.deepseek.com"],
+  "knownHosts": ["api.deepseek.com", "registry.npmjs.org"]
+}
+```
+
+`knownHosts` 由插件写入（观测到的流量）；`upstream` 与 `proxiedHosts` 由设置页写入。你也可以在 dsh 运行中手改该文件——它是实时重读的。
+
+## 安装
+
+**前置要求：** 已安装带 `dsh` CLI 的 DeepSeek Harness，以及 [pnpm](https://pnpm.io)（`dsh plugin` 命令底层调用 pnpm）。这是一个可安装的 **bundle**——由 `dsh` 加载，不是当作库 import。
+
+### 从 npm 安装（推荐）
+
+包已发布到 npm，名为 `@karoc/dsh-proxy`：
+
+```sh
+dsh plugin --profile web add @karoc/dsh-proxy
+```
+
+安装预构建 bundle 并追加到 `web` profile。然后**重启 `dsh web`**，打开 **设置 → 代理 / Proxy**。
+
+### 从 git 安装
+
+```sh
+dsh plugin --profile web add github:karoc/dsh-proxy#<sha>
+```
+
+git 安装会运行包的 `prepare` 脚本构建 bundle。pnpm ≥ 10 需要先放行该构建——把 pnpm 打印的包 key 复制到 profile 的 `pnpm-workspace.yaml` 的 `allowBuilds` 下，再重跑 `add`（见 DSH 仓库 `docs/user/develop/basic/publish.md`）。
+
+### 更新
+
+用 pnpm update 升到最新版（或重 `add` 以拉取更新的 git ref）：
+
+```sh
+dsh plugin --profile web update dsh-proxy
+# 或，若依赖规格被 pin 住：dsh plugin --profile web add dsh-proxy
+```
+
+然后**重启 `dsh web`** 以加载新客户端 bundle。
+
+### 卸载
+
+```sh
+dsh plugin --profile web remove dsh-proxy
+```
+
+同时从 `web` profile 移除依赖与 bundle 层。重启 `dsh web` 后该设置项消失。
+
+## 目录结构
+
+```
+cordis.patch.yml      # bundle 层：挂一行让 client-modules 服务发现（dsh.client manifest）
+package.json          # dsh.bundle (patch) + dsh.client (web) + exports["./client"]
+tsdown.config.ts      # 自包含构建：node 半区 + 模块表客户端 bundle
+src/proxy-core.ts     # 前向代理引擎（HTTP+CONNECT、SOCKS5/HTTPS 上游、按主机路由、
+                      # 实时配置、测试探针）—— dsh-desktop scripts/proxy.mjs 的 TS 移植
+src/index.ts          # host apply：起代理、设 *PROXY 环境变量、注册 /proxy/api（GET 视图 / POST save·test·persist）
+src/client/index.ts   # client apply：注册 settings.section（id dsh-proxy）
+src/client/ProxySection.tsx  # 设置页（上游卡片 + 主机列表）
+src/client/styles.ts  # design-token 样式（--dsw-alias-*）+ 注入
+src/client/locales.ts # en/zh 文案
+scripts/proxy-core.spec.mjs  # 行为测试（13 场景，无外部网络）
+```
+
+### /proxy/api 路由
+
+host 半区用同源 HTTP 路由为设置页供数（内置 `/api` 前缀被 gateway 占用，故用 `/proxy/api`）：
+
+- `GET  /proxy/api` → `{ upstream, proxiedHosts, knownHosts, hosts, providers, port }`
+- `POST /proxy/api` `{ op: 'save', upstream, proxiedHosts }` → 清洗后持久化的配置
+- `POST /proxy/api` `{ op: 'test', upstream }` → `{ ok, detail }`
+- `POST /proxy/api` `{ op: 'persist' }` → 把观测主机并入 `knownHosts`
+
+## 构建
+
+```sh
+pnpm install
+pnpm bundle          # 产出 lib/index.js + lib/client.js
+pnpm test            # tsc --noEmit + proxy-core.spec.mjs（13 场景）
+pnpm release:check   # 发布门禁：文档/changelog/tag/工作区/构建/registry 全过
+pnpm publish         # 跑门禁（prepack/prepublishOnly），随后 postpublish 验证线上发布
+```
+
+bundle 把平台包（`react`、`@deepseek-ai/cordis`、`@deepseek-ai/dsh-client-*`）保持 external——它们在运行时从 loader 的模块表解析；其余全部内联。
+
+## 注意事项 / 限制
+
+- **代理是进程级出站点，不是模型逐请求读的开关。** 它通过把进程的 `HTTP(S)_PROXY` 指向自身来实现。本插件 host `apply()` 之后 dsh 发起的请求（任何子进程、以及 global dispatcher 仍是惰性的 undici fetch）会走代理。若某个 dsh 内部 fetch 在插件加载前就已实体化了 dispatcher，可能不会走它——文档化的解法是重启 dsh（桌面壳通过 spawn dsh 前设环境变量来施加同样的边界）。
+- `npm`/`pnpm` 安装/更新流量与其它一样走代理；改动**与安装/更新相关的主机**会在下次安装/更新时生效（已在进行的操作保留其环境）。
+- **设置页导航图标由壳分配，插件无法自定义。** 内置 `ui-settings-general` 的 `SettingsRoot.tsx` `navIcon(id)` 只映射已知 id，其它 id（包括本节的 `dsh-proxy`）一律齿轮。`settings.section` 注册没有 icon 字段，外部插件不 patch 壳就改不了。等 DSH 开放每节图标后，本节建议用 `dsh-client-ui-primitives` 的 `IconGlobeOutline14`。
+- 桌面壳（`dsh-desktop`）保留自己的代理与托盘设置窗口——本插件是独立抽取，不是替代品。两者可共存（例如把 `dsh-proxy` 装进壳的 profile，同时获得 dsh 内设置页）。
+
+## License
+
+[MIT](LICENSE)
+
+## 参与贡献
+
+见 [CONTRIBUTING.md](CONTRIBUTING.md)（开发 + 发布清单）与 [CHANGELOG.md](CHANGELOG.md)（版本历史）。

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# Bundle layer applied when a profile lists this package. The row names the
+# package so the host loader resolves the node half and client-modules serves
+# exports["./client"] at /plugins/dsh-proxy/client.js. The host half starts the
+# loopback forward proxy and registers /proxy/api; the client half registers
+# the settings.section settings page.
+- insert:
+    - id: dsh-proxy
+      name: dsh-proxy