dsh-trilogy：DeepSeek Harness 的項目記憶插件

前言¶

DeepSeek Harness (DSH) 的插件化架構旨在解決上下文管理的長期性問題。模型不具備持久的記憶能力，僅靠提示詞（Prompt）無法保證每個工作區都有統一的上下文。dsh-trilogy 是一個 Host 插件，它接管了記憶文件的創建、加載和持久化工作，不依賴模型自覺，而是通過插件在宿主端強制執行記憶行爲。

插件定位¶

名稱：dsh-trilogy
一句話介紹：爲每個工作區維護三份 Markdown 記憶文件：自動創建、自動加載、自動記錄。
維護者：TodayJin
許可證：MIT

安裝與啓用¶

前置條件：pnpm 在 PATH 上，DSH 版本 0.1.7-rc.2。

通過本地鏈接安裝，修改代碼後重啓 dsh web 即可生效：

dsh plugin --profile web add link:D:/path/to/dsh-trilogy

卸載插件不會刪除項目的 memory/ 目錄：

dsh plugin --profile web remove dsh-trilogy

核心功能¶

該插件爲每個工作區在 <項目根>/memory/ 下維護三份文件：

PROJECT.md：記錄項目現狀，就地編輯。
DECISIONS.md：記錄決策和被否決的方案，頂部追加。
SESSIONS.md：記錄發生了什麼，頂部追加。

主要能力：
1. 自動創建與加載：會話啓動時自動創建文件；自動注入三個文件的內容（內容未變則不重複注入）。
2. 工具支持：提供 memory_checkpoint（分類記錄）、memory_read（讀取文件）、memory_search（BM25 檢索）工具。
3. 區域分類：支持按區域標籤分類記錄，每個區域保底 1 條，其餘按活躍度加權。
4. 圖形界面：提供瀏覽器半邊界面，支持查看、編輯、導出/導入、歸檔與恢復記憶。
5. 注入預算控制：嚴格限制注入量，SESSIONS.md 全文不注入，只注入最近 N 條日誌。

使用方法¶

安裝後無需配置，在任意項目裏開一個會話，memory/ 目錄和 AGENTS.md 的 boot block 會自動創建。

1. Bootstrap（初次填充）¶

如果 PROJECT.md 還是空的，插件會注入一條指令，要求模型讀取 README、跑測試命令並填充 PROJECT.md 的五個固定節。填完後指令自動消失。

2. 會話注入機制¶

每個會話開始時，三個文件會自動注入上下文。
* 去重：內容沒變則不重複注入。
* 日誌策略：SESSIONS.md 全文不注入，只注入最近 N 條日誌（默認 15 條）。
* 預算降級：如果總注入預算超限，會優先保留 PROJECT.md，然後減少日誌條目數量，最後才丟棄歷史日誌。

3. 記錄進展¶

使用 memory_checkpoint 工具：
* 參數支持 sessions[]（可帶 area）、decisions[]、project[]、notes。
* 工具會根據路由表將內容寫入對應文件。
* 使用 memory_search 工具可以檢索記憶內容（含歸檔）。

4. 圖形界面操作¶

在 DSH Web 設置中找到“項目記憶”：
* 查看與編輯：按文件用途分頁籤查看（現狀/決策/日誌/歸檔）。
* 清除與忘記：清除會刪除記憶文件；忘記只移除註冊表索引，不刪除磁盤文件。
* 導入導出：支持將 memory/ 導出爲 JSON 包並在另一臺機器或工作區導入。

配置與注入策略¶

在 profile 的 cordis.patch.yml 中按 id 覆蓋配置：

- id: trilogy
  config:
    injectBudgetBytes: 24000
    nudgeMaxPerSession: 5

關鍵配置項：

鍵	默認值	說明
`sessionEntriesInjected`	`15`	決定有多少條 SESSIONS 日誌被注入上下文
`projectRootStrategy`	`"workspace"`	`"workspace"` 表示工作區即項目根；`"marker"` 表示向上找 `.git`
`projectStaleDays`	`14`	PROJECT.md 落後多少天提示陳舊
`writeBootBlock`	`true`	是否往 `AGENTS.md` 追加 Memory 段

注入優先級：
當注入預算不足時，按以下順序降級：
1. 完整注入三個文件；
2. 日誌條目逐檔減半（15 -> 7 -> 3 -> 1）；
3. 只保留 SESSIONS.md 的部分條目；
4. 只保留 DECISIONS.md 頭部；
5. 最後才截斷 PROJECT.md。

安全與注意事項¶

本機訪問限制：所有 /trilogy 路由限制爲本機訪問（非 loopback 返回 403），防止未授權訪問。
數據持久性：插件不依賴模型進行記憶維護，完全由 host 插件保證。卸載插件不會刪除項目的 memory/ 目錄。
UI 圖標：如果缺少特定圖標，會自動回退成一個變色圓點。
模板可改：三個文件和 boot block 的模板位於 templates/，可自定義。

總結¶

dsh-trilogy 通過 Host 插件機制解決了 DSH 中上下文不連貫的問題。它強制執行了項目記憶的“三文件”結構，並通過智能的注入預算和區域分類策略，確保模型能高效獲取上下文。適合需要長期維護項目上下文、多會話協作的開發場景。