本机常驻代理：改动、回归与归属

适用

• 给本机长驻 HTTP/SSE 反代加可选开关、调超时、改流式处理。
• 多个实例抢端口、重启后“磁盘是新版、进程还是旧版”、旧 cmd 窗口把新实例顶掉。
• 需要在不动生产流量的前提下证明新代码行为正确。

Qoder BYOK 反代的端口、日志字段与现有阈值放 references/qoder-byok-proxy.md。主线写通用判据。

1. 动手前先证明“这是谁的进程”

按顺序取证，缺一条就不得停进程：

1. 健康端点（/_health 或等价）返回的版本/源码指纹。
2. 命令行 / 启动脚本路径（wmic process get ProcessId,CommandLine 或 PowerShell Get-CimInstance Win32_Process）。
3. 监听归属：Get-NetTCPConnection -LocalPort <port> -State Listen | Select OwningProcess；Git Bash 的 netstat 无输出时改走 PowerShell。
4. 启动时间与磁盘文件 mtime：启动晚于改动才可能加载新代码。
5. 进程句柄/父进程：旧 cmd 窗口可能重新拉起无开关实例，必须 taskkill /PID <pid> /T 连父链，不只杀 node。

外来监听负对照：在沙箱里起一个同端口但命令行不含本代理特征的假监听，确认启停脚本不会杀它；只按镜像名（node.exe）或端口杀进程是禁止项。

2. 开关式改造：默认关闭 + 基线逐字节对照

1. 改前用 backup-file.js 留基线，记录文件 SHA-256。
2. 新开关默认关闭；关闭路径必须与改动前行为逐字节一致（相同输入 → 相同输出/相同响应）。
3. 用可信本地 TLS 上游 + 独占端口做夹具；自签证书在 Git Bash 下要 MSYS_NO_PATHCONV=1，否则 /CN= 被当路径改写。
4. 四场景矩阵：
   • 开关关闭：与改动前脚本的 dump cmp 逐字节相同；
   • 开关打开 + 上游慢：新行为按设计生效，且不改变客户端可见协议；
   • 开关打开 + 上游快：必须透传不变（不能为了“优化”篡改响应）；
   • 上游返回非 SSE / 错误：守卫必须拦下或转成协议内错误，不能伪装成功。
5. 重启后从健康端点回读 version 与开关字段；磁盘 SHA 与运行态指纹不一致即“未生效”。

3. 透明 SSE 代理回归矩阵

先明确三条禁止项：不伪造前导事件、不改写响应 ID、不改写序号。代理只转发与必要的保活，不扮演模型。

用增量 UTF-8 解码与标准 SSE 解析，覆盖：

分别断言四件事，不能相互替代：传输完成（连接正常结束）、协议完整（SSE 事件闭合）、模型生成成功（有正常终态/完成事件）、内容一致（与上游逐字节或逐事件一致）。

4. 超时与保活归属

• 先看代理侧日志的时间戳与 outcome，不要只看客户端报错。
• 客户端在首包前断开（CLIENT_DISCONNECTED 且无上游 headers 行）⇒ 客户端先放弃，不是代理超时。
• 代理自己的头超时与客户端首包超时是两个阈值；调错方向会制造“改了没用”。
• 假慢上游夹具：可控延迟 < 阈值 / > 阈值 / 永不回头，分别断言早期头、透传与错误事件。
• 早期头/心跳只能保连接，不能延长客户端对“有效数据”的计时；阈值必须小于客户端上限，且与总超时联动时要做安全收紧，不得拒绝启动。

5. 运行态 == 磁盘

修复后固定三条比对：

1. 进程启动时间 vs 文件 mtime（晚于启动的改动不可能生效）。
2. 健康端点回显的版本/源码 sha256 前 12 位 vs 磁盘文件哈希。
3. 不一致即判“新代码未被加载”；重启后复验版本一致才算修好。

只看到“进程还在、端口还在”不算生效。无法重启时如实写“代码已验证，现役未生效”。

6. 交付判据

• 进程身份四项以上取证，停启按精确 PID，含外来监听负对照。
• 关路径与改动前逐字节一致；开路径四场景通过。
• SSE 矩阵覆盖切分/行尾/截断/ID/工具参数/空输出/超时。
• 四项成功判据分开报告。
• 运行态版本与磁盘一致，或有明确的“未生效”标注。

相关

• 模型请求失败与 UA 指纹：byok-model-retry。
• 通用证据纪律：verify-before-claim。
• 分流规则持久化：proxy-rule-surgery。