# 贡献指南

先感谢你愿意花时间。这个项目的目标很小：**在传输边界上，把「这个 provider 走哪条路、以什么身份发出去」变成一条可解释、可复现、可回滚的规则。**

## 环境

- Node.js >= 18（CI 覆盖 18 / 20 / 22，Windows + Linux）
- 一个可运行的 DeepSeek Harness（桌面端或 `dsh` CLI），用于手工验证界面与真实出网
- 不需要任何第三方运行时依赖：插件本身零依赖，测试也只用 `node:*`

## 本地开发循环

```powershell
git clone https://github.com/dyh886/dsh-llm-net-router.git
cd dsh-llm-net-router

# 让 Harness 从 profile 里解析到这个工作副本（Windows，管理员不需要）
$dshHome = $env:DSH_HOME; if (-not $dshHome) { $dshHome = "$env:USERPROFILE\.dsh" }
New-Item -ItemType Junction `
  -Path "$dshHome\profiles\desktop\node_modules\dsh-llm-net-router" `
  -Target (Get-Location)

# 在 profiles\desktop\package.json 的 dependencies / dsh.profile.bundles 里注册
# 然后重启 Harness（桌面端：托盘退出 → 重新启动）
```

改完 `lib/*.js` 或 `client.js` 后重启 Harness；只改 `client.js` 且 `pnpm run dev:web` 在跑时可热更新。

不想反复重启也能验证大部分逻辑：探测引擎、传输层、规则存储在测试里是纯 Node 跑的。

## 测试

```powershell
npm run check          # 所有 .js/.mjs 过 node --check
npm run test:unit      # 离线用例：规则、传输、拦截、探测、客户端 bundle
npm test               # 加上 integration.network.test.mjs（没有代理时自动 skip）
```

联网集成用例需要本机代理：

```powershell
$env:DSH_NET_ROUTER_IT = "1"
$env:DSH_NET_ROUTER_PROXY = "http://127.0.0.1:7890"
node --test test/integration.network.test.mjs
```

**新增行为的 PR 必须带测试。** 每个测试文件都对应一个模块边界：

| 文件 | 覆盖 |
|---|---|
| `test/store.test.mjs` | 规则归一化、host 匹配优先级、原子落盘、BOM 容忍 |
| `test/httpclient.test.mjs` | 直连 / HTTP(S) 代理 / SOCKS5 的真 socket 往返、TLS、重定向、AbortSignal |
| `test/router.test.mjs` | `fetch` 包装、头改写、1M beta 累加、回退、幂等安装 |
| `test/probe.test.mjs` | 矩阵探测与推荐的三条判定原则 |
| `test/client.test.mjs` | 客户端 bundle 的加载契约与真实渲染（自带迷你 React） |
| `test/index.test.mjs` | 配置合并、声明式 provider 与规则文件的优先级 |
| `test/diagnostics.test.mjs` | baseURL 空白、规则漂移等体检项 |

## 代码风格

- ESM、2 空格、双引号、保留分号；不引入格式化器依赖
- 注释解释**为什么**（尤其是踩过的坑），而不是复述代码在做什么
- 不在代码或测试里写真实 API key、Cookie、真实请求头原值；用 `sk-test` 之类的占位
- 传输层保持零依赖：Node 内置模块之外的东西不要进 `lib/`

## 提交与 PR

- 提交信息用 Conventional Commits：`fix(router): ...`、`feat(probe): ...`、`docs: ...`
- 一个 PR 只做一件事；行为变化同步更新 `README.md` 与 `CHANGELOG.md`
- PR 描述里贴实际跑过的命令与输出，不要写“应该没问题”
- 涉及传输层或指纹的改动，请说明你实际验证过的站点类型与失败模式（脱敏）

## 不打算接受的方向

- 把插件改成全局 `undici` dispatcher（表达不了按 host 决策，理由见 README「实现要点」）
- 引入 HTTP/2、PAC、SOCKS4
- 内置任何真实中转站地址、密钥或“默认可用”的指纹列表
- 为通过某个站的校验而内置对抗性随机化（这个项目的定位是**可解释的固定指纹**，不是反检测军备竞赛）