DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

cloudbywu /

cloudbywu/dsh-ustc-iwan

Verified

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

★ 1 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@e207af94

@cloudbywu/dsh-ustc-iwan

License: MIT DSH npm

让词元工坊(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 出口连不上时自动回退直连,不掉线              │
└──────────────────────────────────────────────┘

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

  1. 启动本地分流代理,按「网段命中 / 域名后缀命中」决定出口;
  2. 通过宿主自带的 @deepseek-ai/dsh-http-proxy 把 HTTP(S)_PROXY 指向分流代理 (卸载时整体恢复原状);
  3. 可选:托管 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.3 固定到某个 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.3 源码 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。

安装后

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

首次使用

  1. 打开 设置 → USTC iWAN;

  2. 点 下载 iwan-client-oidc(自动存到 <DSH_HOME>/cache/ustc-iwan/, 不做系统级安装;也可自行解压下载后填入「客户端路径」)。上游提供 ZIP,插件解出 exe, 并在使用自动缓存前校验 SHA-256;旧缓存缺少记录时请重新下载。手动路径由用户确认可信。 此哈希用于检测本地缓存变化,不是上游发布签名。

  3. 在卡片的「统一身份认证」中点「开始认证」,打开授权页完成登录, 把 com.panabit.mobile://... 回调 URL 粘贴回卡片并提交。 线路配置保存在 ~/.config/iwan/servers.json;启动、等待和提交阶段均可取消。 如需终端方式,也可自行运行 iwan-client-oidc-windows-x86_64.exe --fetch。

  4. 新配置默认启用「托管 iWAN 客户端」;下载或认证完成后自动尝试连接。已有关闭选项会保留,也可手动点 启动 iWAN;

  5. 用 测试分流 输入 llm.ustc.edu.cn,显示「走 iWAN」即成功。

设置卡片

安装后 设置 → USTC iWAN 出现一张卡片。首次使用按「准备客户端 → 统一身份认证 → 启动并验证分流」展示三步指引,就绪后可收起。外部客户端模式与实时端口状态分别判断;「走 iWAN」只代表规则命中,不等于真实目标可达。

卡片包含以下分组:

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

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

状态驱动的操作

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

休眠、网络恢复与重新连接

  • 设置卡片在窗口重新获得焦点、页面重新可见或浏览器恢复联网时立即刷新;旧响应不覆盖新状态及未保存草稿,请求有 30 秒超时。
  • 启用自动托管后,后台每 10 秒检查本地 SOCKS 端口;普通端口异常连续两次才重建托管连接。
  • 检测到 30 秒以上的事件循环长暂停(如系统休眠)时,先留 5 秒网络恢复宽限,再重新建立自己的托管会话,避免旧监听仍开但休眠前会话已经失效。
  • 重连失败按 10 / 20 / 40 / 60 秒退避,连续 5 次失败后暂停自动尝试,提示人工检查;可点「重新连接」明确重试。
  • 「停止托管」、关闭自动托管/分流、下载维护或认证期间不会被后台抢先拉起;外部启动的进程不会被结束或自动重启。
  • 唤醒后撤销旧认证会话证明,并清除旧 DNS 解析缓存;新托管连接完成真实认证后才重新显示有效。本地 SOCKS 端口在线不等于远端目标站全链路可达。

瞬时 connect error 与客户端内部重连

  • 托管默认显式使用 --server 1,等价于原先空线路选择第一条;避免上游每次内部重连再次等待交互选线。显式线路或 auto 不被改写。
  • connection ended: ...; reconnecting (...) 表示原生会话中断,此时进程存活不代表 SOCKS 监听和认证仍有效。卡片显示客户端重连中,直到新的正确监听行出现才恢复认证证明。
  • 插件优先等原生客户端自行恢复:单轮无新进度最多 30 秒、一次断线总计最多 90 秒;超时或进程退出才由监测器接管,手动停止/重连仍可立即打断。
  • 仅对明确回环地址的本地 SOCKS 建立期传输错误,最多等待 3 秒、最多尝试 7 次,再按既有策略回退直连;路由、所有尝试和回退共用同一总时限。认证拒绝、坏协议、目标错误和握手超时不泛重试。
  • 上述等待发生在 CONNECT 200 和 HTTP 业务字节发送前;一旦隧道已交接,不自动重放模型 POST、已建立隧道或响应流,避免增加重复执行/计费风险。宿主自身的模型请求重试是独立机制。
  • send VPN packet 是上游隧道 UDP 发送错误的外层上下文,不足以定位 Windows errno。上述修复避免选线挂起、两套重连相互打断和短闪断过早回退,不等于已根治所有底层网络错误。

认证状态的含义

上游持久化的是加密线路配置,没有保存 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 隧道与 TUN:客户端优先选择物理接口,但 Windows 上绑定源 IPv4 不等于强制绕过 TUN 路由;建议把实际 iWAN 服务器地址设置为 DIRECT(含 UDP)。网卡变化或路由环路需要用底层错误链另行核实,不能仅凭外层 send VPN packet 断言。
  • 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/reconnect-monitor.js 休眠心跳、健康检查与重试退避
lib/binary.js         iWAN 客户端下载
lib/policy.js         出站策略安装/恢复
lib/settings-store.js 设置持久化
lib/client.js         浏览器半边(设置卡片)

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

许可

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

—/ 5

No ratings yet

Verified DSH bundle

Commit e207af9464e7

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout