前言¶
DeepSeek Harness（DSH）桌面端每次启动都会在本地随机端口上建监听器，并通过浏览器里的启动 Cookie 完成欢迎页握手。若长期固定同一 profile（同一 userData），Cookie 会在 127.0.0.1 下按域名不断累积，最终把请求 Cookie 头撑过 Node 默认的 16 KiB 上限，握手在 HTTP 解析层以 431 失败，日志里表现为 desktop welcome: Web authentication failed，且重启、撤销授权、重装都无法自愈。社区插件 dsh-auth-cookie-guard（维护者 jitianjiyan）在 Host 侧做两层防护：抬高监听器头部预算，并在每次请求里按规则退休旧启动 Cookie。下面介绍它的定位、机制、安装方式与使用注意。
这是什么¶
dsh-auth-cookie-guard 是 DSH 社区目录中的客户端（Host）类插件，npm 包名与 bundle 名均为 dsh-auth-cookie-guard，当前发布版本 1.0.6（MIT 许可证）。它只运行在 Host 进程内，没有浏览器端资源，也不提供 service / tool / event。
一句话：为本地 webServer 监听器预留足够大的请求头预算，并在启动后删除不再需要的旧 dsh-auth-* 启动 Cookie，避免固定 profile 连续启动约 72 次后因 431 导致桌面欢迎握手永久失败。
症状与根因（插件要解决的问题）¶
固定 profile 连续启动约 72 次后，桌面端可能再也进不去；日志常见：
desktop welcome: Web authentication failed（与 connectDesktopWelcome 相关）。换整个 profile（换掉 Chromium cookie 库）才能恢复。
README 归纳的根因链条如下：
- Host 每次启动绑定随机端口；会话 Cookie 名称为
dsh-auth-<base64url(sha256(host:port))>。 - 浏览器按域名存 Cookie，端口不进键；每启动一次，
127.0.0.1上就多一条约 173 字符、Max-Age30 天的持久 Cookie，且原先没有删除逻辑。 - 建监听器时沿用 Node 默认
maxHeaderSize = 16384字节。 - 累积到第 71 条后，再下发 1 条会使
Cookie头超过 16384，Node 返回 431；客户端当作认证失败。此后每次启动都超上限，431 在解析层就被拒，应用层没有机会清理——故障是累积型且不可自愈。
核心功能¶
插件采用两层防护，README 强调缺一不可：
| 层 | 行为 | 默认值 |
|---|---|---|
| 头部预算 | webServer 就绪后把 server.maxHeaderSize 提升 |
maxHeaderBytes: 65536（64 KiB） |
| 退休旧 Cookie | 每个请求只读 Cookie 头里符合 dsh-auth- + 43 位 base64url 的名字；按浏览器发送顺序（旧→新）保留最后 keep 条 + 当前端口对应的一条，其余用 Max-Age=0; Path=/ 删除（单响应最多 96 条） |
keep: 4 |
设计要点（均来自 README）：
- 只抬预算：约 350 次启动仍会撞墙；只清理不抬预算：431 时清理逻辑跑不到。
- 只读 Cookie 名字与顺序，从 1.0.4 起不解码值、不写入日志；整包仅
import node:crypto，无网络、文件、子进程。 - 不参与 DSH 签名校验与登录判断，只删 jar 里本实例不再用的启动 Cookie。
- 卸载或 dispose 时会还原监听器原始头部预算。
安装与启用¶
在 DSH 插件页填入 dsh-auth-cookie-guard 安装，或执行：
dsh plugin add dsh-auth-cookie-guard
工具会写入 profile 的 package.json（dsh.profile.bundles 与 npm 依赖）；bundle 自带 cordis.patch.yml 作为独立层插入，不要手改 profile 里的 patch 文件。
- 生效：安装时宿主重载组合，插件当场 apply，一般无需重启桌面端；之后每次启动自动生效。
- 卸载：在插件管理中移除该 bundle，重启桌面端；头部预算会随 dispose 还原。
开发时可安装仓库源码目录（工具以 link: 引入）；发布版走 npm 包 dsh-auth-cookie-guard。
配置¶
一般使用默认即可。若需在 profile 的 patch 层调整，在该 bundle 条目下增加 config（maxHeaderBytes 会被限制在 16 KiB–1 MiB，keep 在 1–64）：
- id: auth-cookie-guard
name: dsh-auth-cookie-guard
config:
maxHeaderBytes: 131072
keep: 4
若某台机器上 Cookie 已多到超过 64 KiB（约 350 次启动），可临时把 maxHeaderBytes 调到 262144，启动一次让清理跑完，再调回默认。
典型验证方式¶
README 提供了本地模拟与线上探测思路。安装后 Host 日志可能出现：
auth-cookie-guard: listener header budget 65536 bytes, keeping 4 launch cookie(s)
auth-cookie-guard: retired N launch cookie(s), kept 4
模拟 71 条旧 Cookie + 本轮 1 条时，安装前可能得到 431，安装后握手可通过并当场退休多余条数；第二次请求删除头应幂等。回归测试可通过包内 npm test（14 例，见仓库 test/handshake.test.js）。
复现环境在 README 中注明为 Windows 11、DSH 0.2.1-rc.3、Electron 44.7.0、Node 24.x；插件 engines 要求 ^22.19.0 || >=24.0.0。
适用场景与注意¶
适合谁：长期固定同一 DSH profile、频繁重启桌面端或 Host，且担心或已遇到欢迎握手失败与 431 累积问题的用户。
安全与边界（安装前建议阅读仓库源码与 MIT 许可证）：
- 插件以当前 DSH Host 进程权限运行，只能看到发往本监听的请求所带的 Cookie。
- 默认把监听器
maxHeaderSize提到 64 KiB；若把 DSH 绑到回环之外，远端请求可能多占每连接头部内存——对外暴露时应加反向代理或访问控制，或调低maxHeaderBytes。 - 同 host 多实例：浏览器 Cookie 按 host 共享；较旧实例的登录 Cookie 可能被清理，需重新握手；当前实例端口对应 Cookie 始终保留。
DSH 生态是「一切皆插件」；社区目录 SkillHub 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-auth-cookie-guard 用「头部预算 + 按序退休启动 Cookie」解决固定 profile 下 Cookie 头膨胀导致的永久 431 锁死，改动集中在 Host 监听器与响应头，对认证语义本身不做重写。需要详情、Issue 与源码时，见 GitHub 仓库：jitianjiyan/dsh-auth-cookie-guard。
