前言¶
在 DSH 裏讓 agent 做研究或執行任務時，它常會給自己起的流程起一個短名，例如「三件套」「跑一輪」。這些叫法只在當前項目語境下有意義：用戶看到 agent 這樣說時不知道指什麼；換一輪對話後 agent 也可能忘掉當初的定義，於是重複解釋、前後不一致。
社區插件 黑話單（倉庫 zbc0315/dsh-jargon-list，npm 包 @tom2012/dsh-jargon-list）把「起名」落成一張可持久化的表：短名與詳細含義寫在項目工作區內，人和 agent 讀寫同一份數據，並在 Web 右側欄提供瀏覽與增刪改查。
這是什麼¶
黑話單是面向 DeepSeek Harness Web 的 DSH 插件，維護者爲 zbc0315，在生態目錄中歸類爲 記憶。它不自動改系統提示，也不做全局詞庫；數據文件跟着當前會話所錨定的項目目錄走，換項目即換表。
核心功能¶
人機共用一份數據¶
詞條保存在工作區下的 .dsh/jargon.json。文件爲 JSON，便於閱讀、diff，並可隨倉庫提交。切換 DSH 會話或項目即切換黑話表，其它項目互不影響。
右側欄頁籤¶
安裝並在 Web 中刷新後，可通過以下方式打開：
- 會話標題欄右側的「黑話單」圖標按鈕，直接在右側欄打開頁籤；
- 右側欄
+→ 指南卡片 → 「黑話單」。
頁籤內支持搜索、新增、就地編輯、刪除。
Agent 側工具¶
插件向 agent 註冊三個工具：
jargon_list：查詢詞條；jargon_save：新增或更新；jargon_delete：刪除。
用戶可在面板操作，agent 可在任務中讀寫，雙方針對同一文件；併發上同一詞條爲 last-write-wins，面板約每 2 秒輪詢 revision，外部改動最多約 2 秒後可見。
數據字段（摘錄）¶
單條詞條包含 term（trim 後 1–80 字，同一文件內大小寫/全半角不敏感唯一）、definition（trim 後 1–4000 字，換行保留）、createdAt / updatedAt，以及展示用字段 updatedBy（user | agent）。完整結構見倉庫 README 中的示例。
安裝與啓用¶
插件在 package.json 中聲明 engines.dsh 爲 >=0.2.1-rc.5 <0.3.0-0，README 寫明已在 0.2.1-rc.5 與 0.2.2-rc.1 上實測通過；0.3.x 未驗證且會被版本範圍擋在門外。安裝前請確認本機 DSH 版本在支持區間內。
推薦從 npm 安裝：
dsh plugin --profile web add @tom2012/dsh-jargon-list
也可讓 agent 通過 plugin_manager 安裝：action: install_bundle，target 傳 @tom2012/dsh-jargon-list。裝完後刷新 Web 頁面即可使用右側欄與 agent 工具。
插件以當前 DSH 進程的權限讀寫工作區文件；安裝前建議查看 GitHub 倉庫 源碼與 MIT 許可證。當前包版本爲 0.1.1（以 package.json 爲準）。
典型用法¶
在面板裏補一條黑話¶
打開右側欄「黑話單」，新增詞條。例如短名「三件套」，含義可寫爲：「研究前置三步：先查既有實現，再讀相關文檔，最後跑一次現狀測試。」（與 README 示例一致，可按項目實際改寫。）
讓 agent 在任務裏登記或查詢¶
任務中若 agent 反覆使用某個項目內簡稱，可讓它調用 jargon_save 寫入定義，或先用 jargon_list 覈對是否已有記錄，避免與用戶理解不一致。文件損壞或結構不符時，讀操作會報錯並顯示路徑，寫操作會被拒絕，需用戶自行修復或刪除該 JSON 文件。
行爲與限制（使用前須知）¶
- 錨定項目目錄：黑話單綁定會話 header 裏的原始
cwd，不跟隨 agent 在會話內的cd；在會話裏切到別的目錄不會把表「搬走」。 - 寫入方式：原子替換（臨時文件 + rename）；同一工作區進程內讀改寫串行。跨進程（同一工作區開兩個 DSH 實例同時寫）無鎖，僅進程內串行。
- v1 不做：全局黑話表、自動注入系統提示、別名/標籤/撤銷歷史；同一詞條併發編輯無衝突提示。
結尾¶
黑話單解決的是「項目內臨時簡稱」的沉澱與共享：數據落在 .dsh/jargon.json，人用右側欄維護，agent 用三個工具同步讀寫。目錄介紹見 SkillHub 插件頁，源碼與詳細契約見 GitHub：zbc0315/dsh-jargon-list。
