@cloudbywu/dsh-ustc-iwan

v0.1.1

Published

2 days ago

词元工坊插件：访问 USTC 模型与校内站点时走 ustc-iwan，其余流量保持原样，与 Clash TUN / WireGuard / Panabit iWAN 共存。

0High
0Medium
0Low

cloudbywu

dsh dsh-plugin tokenworks ustc iwan vpn proxy split-tunnel

@cloudbywu/dsh-ustc-iwan

让词元工坊（DSH / DeepSeek Harness）访问 USTC 系列模型（如 llm.ustc.edu.cn）与科大系列网站 时自动走 ustc-iwan，其余流量保持原样；与 Clash TUN、WireGuard、Panabit iWAN 等代理/隧道软件共存不冲突。

不改系统路由、不创建虚拟网卡、不改注册表——分流完全在应用进程内完成。
零第三方依赖：只需宿主自带的 @deepseek-ai/dsh-http-proxy（不可用时自动降级）。
带完整设置界面：状态指示灯、一键下载 iWAN 客户端、配置表单、分流测试、运行日志。

快速安装

词元工坊 → 侧边栏「插件」→ 安装，把下面任一来源粘贴进去，然后完全退出并重启应用：

@cloudbywu/dsh-ustc-iwan                       # npm 包名
https://github.com/cloudbywu/dsh-ustc-iwan      # GitHub 仓库地址
C:\Users\<你>\dsh-ustc-iwan                     # 本地目录（必须是绝对路径）

旧的无作用域包已撤销，请使用 scoped 包名；若官方源暂不可见，可改用 GitHub 或本地路径。详见安装。安装后打开 设置 → USTC IWAN。

工作原理

词元工坊出站请求（模型调用 / web 抓取 / 子进程 curl…）
        │  HTTP(S)_PROXY 指向本地分流代理
        ▼
┌─ 分流代理 127.0.0.1:18118（插件内置）────────────────┐
│  目标域名 → 解析 IPv4                                 │
│  ① 命中 USTC 网段（11 段，内置） ──→ iWAN SOCKS5:1080 │
│  ② 域名后缀命中 ustc.edu.cn 等   ──→ iWAN SOCKS5:1080 │
│  ③ fake-ip（TUN 接管 DNS）按 ② 兜底判断              │
│  ④ 其余目标 ──→ 用户原有代理（如 Clash 7890）或直连   │
│  ※ iWAN 出口连不上时自动回退直连，不掉线              │
└──────────────────────────────────────────────┘

插件在宿主进程内做三件事：

启动本地分流代理，按「网段命中 / 域名后缀命中」决定出口；
通过宿主自带的 @deepseek-ai/dsh-http-proxy 把 HTTP(S)_PROXY 指向分流代理（卸载时整体恢复原状）；
可选：托管 iwan-client-oidc --connect --socks 进程。

转发给 iWAN 的是域名（由 iWAN 在校内解析），因此不依赖本机 DNS；遇到 Clash TUN 的 fake-ip 时自动改用域名后缀判断。

内置网段

114.214.160.0/19  114.214.192.0/18  202.38.64.0/19   210.45.64.0/20
210.45.112.0/20   211.86.144.0/20   222.195.64.0/19   210.72.22.0/24
202.141.160.0/19  218.22.21.0/27    218.104.71.160/28

域名后缀默认：ustc.edu.cn、ustclug.org、ustc.life（均可在设置卡片中修改）。

安装

词元工坊的插件页支持 npm 包名 / GitHub 仓库地址 / 本地目录路径 三种来源，任选一种粘贴进「插件 → 安装」即可。安装完成后完全退出并重启应用，再打开设置 → USTC IWAN。

| 来源 | 适合 | 升级方式 | | --- | --- | --- | | npm 包名（最简单） | 只想用，不改代码 | 插件页「检查更新」 | | GitHub 仓库地址 | 想跟随仓库最新提交 | 插件页「检查更新」 | | 本地目录路径 | 想改代码（改完重启即生效） | 手动 git pull |

方式一：GitHub 仓库地址

在「插件 → 安装」中输入仓库地址：

https://github.com/cloudbywu/dsh-ustc-iwan

以下写法等价，任选其一：

| 写法 | 说明 | | --- | --- | | https://github.com/cloudbywu/dsh-ustc-iwan | 仓库 URL（推荐） | | github:cloudbywu/dsh-ustc-iwan | GitHub 简写 | | git+https://github.com/cloudbywu/dsh-ustc-iwan.git | 显式 git 地址 | | https://github.com/cloudbywu/dsh-ustc-iwan#v0.1.1 | 固定到某个 tag / 分支 / 提交 | | github:cloudbywu/dsh-ustc-iwan#<40 位提交号> | 固定到具体提交（可被插件页更新检查追踪） |

通过 Git 安装时，插件以副本形式装进 profile 的 node_modules。要升级，在插件页对它执行检查更新 / 更新，或改为固定提交后重新安装。首次安装需要宿主能访问 GitHub。

方式二：npm 包名

@cloudbywu/dsh-ustc-iwan

旧的无作用域包已撤销。npm 安装使用 @cloudbywu/dsh-ustc-iwan： https://www.npmjs.com/package/@cloudbywu/dsh-ustc-iwan

npm view @cloudbywu/dsh-ustc-iwan version --registry=https://registry.npmjs.org/

若查询返回 404，请确认包名、公开访问权限和注册表；刚发布的包也可能尚不可见。暂时可使用方式一（GitHub）或本地路径安装。维护者发布流程见发布指南。

方式三：本地目录路径

git clone https://github.com/cloudbywu/dsh-ustc-iwan.git

在「插件 → 安装」中填入绝对路径（也支持 file: / link: 前缀）：

C:\Users\<你>\dsh-ustc-iwan
file:C:\Users\<你>\dsh-ustc-iwan

或下载 v0.1.1 源码 ZIP 解压，再按同样方式填入解压目录。

本地路径必须以绝对路径给出（相对路径会被插件管理器拒绝）。以 link: 链接方式安装时不会执行依赖安装，因此本项目刻意保持零第三方依赖，链接安装同样可用；这种方式改代码后重启应用即生效。

方式四：直接写进 profile（CLI / 进阶）

# 把 <DSH_HOME> 换成你的数据目录：
#   Windows 桌面端：%APPDATA%\tokenworks-desktop-harness
#   CLI 默认：~/.dsh
cd <DSH_HOME>/profiles/<profile>
pnpm add @cloudbywu/dsh-ustc-iwan
# 也可用 pnpm add github:cloudbywu/dsh-ustc-iwan 或 link:<本仓库绝对路径>

并把 @cloudbywu/dsh-ustc-iwan 加入该 profile package.json 的 dsh.profile.bundles。

安装后

完全退出并重启词元工坊（客户端 bundle 在启动时组合，仅刷新页面可能不够）；
打开 设置 → USTC IWAN，确认「分流代理」指示灯为绿色；
按首次使用下载 iWAN 客户端并完成一次认证。

首次使用

打开 设置 → USTC iWAN；
点 下载 iwan-client-oidc（自动存到 <DSH_HOME>/cache/ustc-iwan/，不做系统级安装；也可自行解压下载后填入「客户端路径」）。上游提供 ZIP，插件解出 exe，并在使用自动缓存前校验 SHA-256；旧缓存缺少记录时请重新下载。手动路径由用户确认可信。此哈希用于检测本地缓存变化，不是上游发布签名。
在卡片的「统一身份认证」中点「开始认证」，打开授权页完成登录，把 com.panabit.mobile://... 回调 URL 粘贴回卡片并提交。线路配置保存在 ~/.config/iwan/servers.json；启动、等待和提交阶段均可取消。如需终端方式，也可自行运行 iwan-client-oidc-windows-x86_64.exe --fetch。
新配置默认启用「托管 iWAN 客户端」；下载或认证完成后自动尝试连接。已有关闭选项会保留，也可手动点 启动 iWAN；
用 测试分流 输入 llm.ustc.edu.cn，显示「走 iWAN」即成功。

设置卡片

安装后 设置 → USTC iWAN 出现一张卡片，包含以下分组：

| 分组 | 内容 | | --- | --- | | 运行状态 | 分流代理 / 出站策略 / iWAN SOCKS5 / 托管进程四个指示灯；启动 iWAN、停止托管、刷新状态、分流测试 | | 统一身份认证 | 应用内授权、提交回调、全阶段取消与结果状态 | | iWAN 客户端 | 一键下载 iwan-client-oidc（进度条、sha256 记录、失败自动清理） | | 配置 | SOCKS 地址、端口和日志开关热更新；轮询保留未保存草稿，支持显式放弃修改 | | 最近日志 | 最近 40 条运行日志 |

宿主侧对应路由：/ustc-iwan/api/{status,settings,download,connect,disconnect,test}，以及 /ustc-iwan/api/auth/{start,complete,cancel}。停止托管可取消正在启动的进程；关闭分流或卸载插件会清理托管进程及全部代理隧道，外部启动的进程不受影响。

状态驱动的操作

已下载：根据实际校验后的缓存显示，重启后仍可识别；安装版本和时间来自本地元数据，旧缓存版本缺失时明确显示未知。
检查更新 → 更新到指定版本：只在点击时访问上游 GitHub Release API，安装已检查的精确版本；已知更高版本不自动降级，无法比较的 tag 不冒充升级。普通状态轮询不查询 GitHub。
重新下载：已知版本重下同一版本；旧缓存版本未知时才获取最新。手动客户端仅显示「已配置」，缓存操作不覆盖其他手动路径。
安全替换：暂停插件托管，等待旧进程真实退出再下载；支持取消。完成或失败后按原状态恢复；用户手动停止会保持暂停，不结束外部进程。
默认托管：仅对新配置或缺少该字段的配置启用；缺少客户端或认证配置时等待引导，不反复拉起失败进程。

认证状态的含义

上游持久化的是加密线路配置，没有保存 token、证书或认证有效期。因此：

| 状态 | 含义 | | --- | --- | | 尚未认证 / 配置无效 | 没有可用的本地线路配置，需要完成认证或修正配置 | | 认证已保存，待连接验证 | 本地配置存在，但不能仅凭文件或 TCP 端口判断在线认证有效 | | 认证有效 | 本次插件托管的进程已完成认证并输出正确地址的 SOCKS5 监听行，且进程仍存活、配置及线路未改变 |

认证有效状态会在进程退出、停止或配置变化后撤销，并不表示保存的配置立即失效；下次连接成功后再次确认。外部端口在线、曾经完成认证流程、文件修改时间或额外的 expiry/JWT 字段都不会被当作有效证据。凭据状态对象仅返回脱敏状态、数量和配置变更标识，不返回密码、密钥或完整凭据。

依据：上游配置格式、认证及代理启动顺序。

配置项

配置持久化在 <DSH_HOME>/storages/ustc-iwan-settings.json（原子写）。环境变量优先级最高：

| 环境变量 | 对应配置 | | --- | --- | | USTC_IWAN_CLIENT_PATH | iwanClientPath | | USTC_IWAN_SERVER | iwanServer | | USTC_IWAN_UPSTREAM_PROXY | upstreamProxy | | USTC_IWAN_SOCKS_PORT | iwanSocksPort | | USTC_IWAN_DNS | dnsServer | | USTC_IWAN_DISABLED=1 | 完全停用本插件 |

| 字段 | 默认 | 说明 | | --- | --- | --- | | enabled | true | 关闭后插件完全不介入（策略恢复原状） | | listenPort | 18118 | 本地分流代理端口 | | iwanSocksHost / iwanSocksPort | 127.0.0.1 / 1080 | iWAN SOCKS5 地址 | | manageClient | true | 新配置默认托管；客户端和认证配置就绪后自动连接，保留已有明确关闭选项 | | iwanClientPath | 空 | 托管模式下 exe 路径；留空用已下载副本 | | iwanServer | 空 | 线路名或序号（传给 --server） | | upstreamProxy | 自动 | 非 USTC 流量的上游 HTTP 代理；留空自动沿用启动环境里的 HTTP(S)_PROXY，再无则直连 | | cidrs | 上表 11 段 | USTC 网段（逗号分隔） | | domainSuffixes | ustc.edu.cn,ustclug.org,ustc.life | 域名后缀兜底 | | dnsServer | 系统 | 分流解析用 DNS；TUN fake-ip 环境建议 223.5.5.5 | | verbose | false | 逐请求日志 |

与代理软件共存

Clash TUN 开着也能用：分流在应用进程内完成；Clash 接管 DNS 出现 fake-ip 时，插件改用域名后缀兜底，且转发给 iWAN 的是域名（由 iWAN 在校内解析）。建议在 Clash 配置里把 iWAN 服务器地址与上述 USTC 网段设为 DIRECT 更稳。
iWAN 隧道不被抢走：ustc-iwan 客户端本身把隧道 UDP 绑定到物理网卡（排除 VPN/TUN 虚拟网卡）。
WireGuard / Panabit iWAN：它们接管系统路由不影响应用层分流，插件不与之争抢任何系统资源。
iWAN 掉线：USTC 请求自动回退直连（校内场景仍可用），并在日志中提示。

排错

| 现象 | 处理 | | --- | --- | | 设置里没有「USTC IWAN」卡片 | 完全退出应用后重启（客户端 bundle 需重建）；仍无则按 F12 看控制台报错 | | 端口 1080 上没有…且未配置 iwanClientPath | 先手动启动 iWAN，或填写「客户端路径」 | | iWAN 客户端一启动就退出 | 先在终端单独跑 --connect --socks 看输出；多为线路选择或认证过期，重跑 --fetch | | USTC 请求走了直连且校外不可达 | 确认 iWAN SOCKS 端口存活；看日志是否提示 fake-ip，必要时设 DNS 为 223.5.5.5 | | 下载失败 | 走 GitHub Releases，网络不畅时手动下载并填入「客户端路径」 |

已知边界

网段决策只覆盖 IPv4；IPv6 字面量或仅有 AAAA 记录时按域名后缀兜底。
浏览器渲染层自身发出的请求不经宿主网络栈，不在分流范围内；分流目标是 应用出站请求（模型调用、web 抓取、子进程等）。
iWAN 不可达时仍按设计回退直连，本插件不是强制禁止直连的隐私代理。
测试覆盖代理分包与数据交接、HTTP/TLS 上游、认证和进程取消、缓存校验、配置热更新、表单草稿及卸载清理。
测试使用本机回环与模拟进程，不替代真实校园认证和宿主环境验收。

开发

使用 Node.js 24.9.0 或更新版本，无需安装额外测试依赖：

npm run check
npm test

测试命令已包含隔离模拟需要的 --experimental-vm-modules；网络测试只使用本机回环临时端口。 CI 配置覆盖 Windows / Linux 的 Node 24、26，不自动发布 npm。

lib/index.js          Host 入口（运行时 + 路由挂载）
lib/runtime.js        运行时状态机（设置、分流代理、策略、托管）
lib/routes.js         /ustc-iwan/api/* 路由
lib/split-proxy.js    本地分流代理（CONNECT + 明文 HTTP）
lib/socks.js          极简 SOCKS5 CONNECT 客户端
lib/cidr.js           USTC 网段匹配 + fake-ip 识别
lib/resolver.js       带缓存 DNS 解析
lib/iwan-client.js    iWAN 客户端探测/托管
lib/binary.js         iWAN 客户端下载
lib/policy.js         出站策略安装/恢复
lib/settings-store.js 设置持久化
lib/client.js         浏览器半边（设置卡片）

修改 lib/client.js 后需重启应用，浏览器才会拉到新的客户端 bundle。

许可

MIT。ustc-iwan 客户端由 yyy1mu/ustc-iwan 提供，本项目仅在运行时调用它，不重新分发其二进制。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@cloudbywu/dsh-ustc-iwan

快速安装

目录

工作原理

内置网段

安装

方式一：GitHub 仓库地址

方式二：npm 包名

方式三：本地目录路径

方式四：直接写进 profile（CLI / 进阶）

安装后

首次使用

设置卡片

状态驱动的操作

认证状态的含义

配置项

与代理软件共存

排错

已知边界

开发

许可