# DSH 指纹中转

让 DSH 连上那些**按 TLS 指纹拦截客户端**的供应商（例如 agentrouter.org）。

插件在本机跑一个被对方放行的 Python 出口进程，DSH 的请求经它转发出去。

## 什么时候需要它

供应商在浏览器或官方 CLI 里能正常用，但 DSH 里报 `unauthorized client detected` 或 403。

## 前置条件

- DSH Desktop（框架 `0.1.0-rc.8`）
- Python 3.11+

## 安装

```powershell
git clone https://github.com/Wilfred-wei/dsh-fingerprint-relay.git
cd dsh-fingerprint-relay
.\scripts\install.ps1
```

脚本会装插件、建 Python venv、装依赖、把解释器路径写进 profile，并校验安装结果。

装完**重启 DSH Desktop**。

<details>
<summary>不用脚本，手工两步</summary>

```powershell
# 1. 装插件
dsh plugin --profile web add dsh-fingerprint-relay

# 2. 建 Python 环境
$relay = "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-fingerprint-relay"
python -m venv "$env:USERPROFILE\.dsh\fingerprint-relay-venv"
& "$env:USERPROFILE\.dsh\fingerprint-relay-venv\Scripts\python.exe" -m pip install -r "$relay\resources\requirements.txt"
```

再把解释器写进 `%USERPROFILE%\.dsh\profiles\web\cordis.patch.yml`：

```yaml
- id: fingerprint-relay-host
  config:
    pythonPath: C:\Users\<你>\.dsh\fingerprint-relay-venv\Scripts\python.exe
```

</details>

## 使用

1. 设置 →「指纹中转」→ **添加中转**
   - 上游地址：`https://agentrouter.org`
   - 本地端口：`7187`
2. 点**启动**，状态显示 `running / healthy`
3. 在「经由中转的供应商」里，把 Anthropic 供应商（如 `agent-claude`）指向这个中转
4. 正常对话即可

API key 仍然只在供应商配置里填写一次，中转不保存密钥。

## 限制

- 只支持 Anthropic Messages 通道，OpenAI 协议的供应商不要绑
- 出口进程只监听 `127.0.0.1`
- 在 Windows 上验收

## 故障排查

| 现象 | 处理 |
| --- | --- |
| 设置页没有「指纹中转」 | 重启 DSH Desktop；`dsh --profile web --dump-config` 里应有 `fingerprint-relay-host` |
| 启动失败，提示缺少 Python 包 | 重跑 `.\scripts\install.ps1`，或对该解释器执行 `pip install fastapi uvicorn httpx anthropic` |
| 启动失败，提示端口被占用 | 换一个本地端口 |
| 请求返回 401 | 对应供应商没有配置 API key |
| 卡很久后报 `no stream data for 120s` | 上游卡住，中转已自动重试过一次，重发即可 |
| 改了配置没生效 | 在设置页点**停止**再**启动** |

## 从源码构建

```bash
npm install --legacy-peer-deps
npm run build
npm test
npm pack --ignore-scripts
```

架构与行为规格见 `docs/`。

## 许可证

MIT