前言¶
DeepSeek Harness 桌面殼每次啓動都會用隨機端口拉起 Host（--port 0），認證 Cookie 的名字又與 127.0.0.1:<端口> 綁定。瀏覽器對 Cookie 按主機聚合、不區分端口，舊端口的 dsh-auth-* 會一直留在 jar 裏；多次開關之後，請求頭的 Cookie 會撐破 Node 默認 16KB 上限，窗口白屏或打不開。下面介紹社區 Host 插件 dsh-auth-cookie-guard 如何在不改業務邏輯的前提下做回收與自愈。
這是什麼¶
dsh-auth-cookie-guard 是 DeepSeek Harness 的 Host 插件，由維護者 Ethan1999991231 發佈，在 SkillHub 插件目錄 中歸類爲聯網工具。它針對「反覆開關桌面 Harness 後窗口打不開」這一現象：源碼與 RFC 行爲表明，約第 71 次開關時單主機上堆積的 dsh-auth-* 會使 HTTP 請求頭超過默認 16384 字節，觸發 HPE_HEADER_OVERFLOW。插件在響應路徑上過期非當前端口的 Cookie，並在已溢出時通過 clientError 路徑引導瀏覽器丟棄舊 Cookie 後重試。
故障鏈路（背景）¶
理解插件前，先把鏈條對齊到倉庫 README 裏引用的 Harness 組件行爲：
- 桌面 Host 以
127.0.0.1和端口0啓動，每次端口不同。 - Cookie 名形如
dsh-auth-+ 對 authority 的哈希，authority 含端口；默認有效期 30 天，且官方路徑沒有主動過期舊端口 Cookie 的邏輯。 - 瀏覽器向
127.0.0.1發請求時帶上該主機下所有歷史dsh-auth-*。 - Host Web 服務未放寬
maxHeaderSize時，Node 默認 16KB 上限會導致超限請求在進業務前失敗。
README 中按單條約 225 字節估算，閾值約 70.8 次，與「第 71 次開關越界」的反饋一致。插件解決的是這條鏈路，而不是替代官方長期方案（例如在啓動時清理非本實例 authority 的 Cookie，或調整 Cookie 命名策略）。
核心功能¶
經 README 覈實，插件做三件事：
回收（治本）¶
包裹 dsh-host-frontend-static 裏對 connection.authorizeIndex 的調用。在寫響應時，對 Cookie jar 裏「不屬於當前監聽端口」的 dsh-auth-* 追加 Max-Age=0 的 Set-Cookie。當 jar 中 dsh-auth-* 超過滯回閾值 4 條時開始回收，使同類 Cookie 數量被壓在 5 條以內，避免再次爬到 71 條附近。
自愈（治已壞）¶
已堆滿 jar 的請求可能到不了正常業務處理，但 Node 仍會拋出帶 rawPacket 的 HPE_HEADER_OVERFLOW。插件從截斷包中解析 Cookie 名與原 URL，返回 303 See Other 並逐條下發過期 Cookie；瀏覽器丟棄後自動重試，幾跳內可恢復打開，無需手動清站點數據。
診斷¶
運行狀態寫入 $DSH_HOME/auth-cookie-guard/state.json，字段包括回收次數、見過的最大 jar 規模、溢出修復次數等，便於確認插件是否在起作用。
安全邊界與實現方式¶
插件採用防禦式掛載：不修改請求業務邏輯、不改配置文件；ctx.effect 卸載時還原被包裹的方法；內部結構不匹配時退化爲 no-op 並打日誌。
README 明確的安全約束包括：
- 滯回閾值
REAP_ABOVE = 4：jar 不超過 4 條時不動作，降低誤傷同一DSH_HOME下另一 Harness 實例（不同 authority）登錄態的風險。 - 只過期當前請求
Cookie頭裏出現過的dsh-auth-*名字，不憑猜測構造。 - 同主機校驗：僅當請求 authority 的 hostname 與本監聽器一致時纔回收。
- Secure 對齊：監聽器爲 https 時，過期 Set-Cookie 同樣帶
Secure。
插件只處理 dsh-auth- 前綴且出現在請求中的名字，不讀憑據文件、不聯網。
安裝與啓用¶
需要 DeepSeek Harness 0.2.1-rc.5 或更新（依賴 connection.browserAuth 與公開的 webServer.server）。package.json 要求 Node >= 20。許可證爲 MIT，當前發佈版本 1.0.0。
任選一種安裝方式（命令來自倉庫 README）：
# 1) 從 npm
dsh plugin --profile desktop add dsh-auth-cookie-guard
# 2) 從 Release 裏的 tarball
dsh plugin --profile desktop add ./dsh-auth-cookie-guard-1.0.0.tgz
# 3) 從本地源碼（link，改完即時生效）
dsh plugin --profile desktop add ./
裝完後重啓一次 Harness。同一 profile 內不要同時安裝本地 link 版（@local/dsh-auth-cookie-guard）與 npm 發佈版：loader 行 id 相同會導致 duplicate loader entry 啓動失敗；切換前先刪掉另一版。
典型用法與驗證¶
確認插件在工作¶
安裝並重啓後，可查看狀態文件：
{ "reaped": 12, "reapEvents": 5, "overflowRepairs": 0, "maxJarSeen": 3, "errors": 0 }
overflowRepairs 大於 0 表示某次啓動曾撞上已溢出的舊 jar，並由自愈路徑恢復。
開發與發佈側自測¶
倉庫內提供零依賴測試（README 原文）：
npm test # 真起 node:http 服務，覆蓋閾值、保留當前 Cookie、16KB 溢出自愈等
npm run check # node --check index.js
拿到 tarball 時也可：
tar -xzf dsh-auth-cookie-guard-1.0.0.tgz && cd package && node test/guard.test.mjs
適用場景與注意¶
適合誰：經常使用 Harness desktop profile、習慣反覆開關桌面窗口，或已經遇到「開關很多次後頁面打不開 / 白屏」的開發者。它屬於社區維護的緩解方案，不是 DeepSeek Harness 官方內置行爲。
安裝前建議：插件以當前 DSH 進程權限在 Host 內運行，會通過 Set-Cookie 修改瀏覽器中與 dsh-auth-* 相關的項。安裝前應閱讀 GitHub 源碼與 LICENSE，確認與己方安全策略一致。SkillHub 目錄與 DeepSeek / 幻方無官方從屬關係，生態定位是「一切皆插件」的社區擴展。
README 亦說明：更理想的官方修復方向是啓動時清理與本實例 authority 不一致的 Cookie，或調整 Cookie 與端口的綁定方式；在此之前的日常開發中，本插件可作爲 Host 側補丁使用。
結尾¶
dsh-auth-cookie-guard 把隨機端口帶來的 dsh-auth-* 堆積釘在可控規模內，並在請求頭已溢出的情況下嘗試自動修復，同時把回收與修復次數落到 state.json 便於覈對。若你正在桌面 Harness 上反覆拉起 Host，可先按 README 安裝、重啓，再對照狀態文件與 overflowRepairs 判斷是否曾觸發溢出自愈。
