前言¶
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。
