前言¶
在 DSH 裏跑智能體，Agent 的長期指令都寫在 ~/.dsh/AGENTS.md。改這個文件目前沒有界面入口：要麼退出會話去翻文件，要麼用外部編輯器保存，改錯了要到新一輪對話纔看得出來，同名衝突也沒有提示。
dsh-agents-md-editor 就是爲此加的一個左側欄入口。下面介紹它的定位、安裝方式和需要注意的權限邊界。
這是什麼¶
由 AikawaNaya 維護的 DSH bundle，在 Web UI 左側欄註冊一個面板，打開後可以查看、修改並保存 ~/.dsh/AGENTS.md。它屬於客戶端類插件，不改變 Agent 的行爲，只提供編輯入口。
核心功能¶
1、左側欄入口。bundle 註冊在 sidebar.panellist，對應打開的 main keyed panel。
2、實時讀取。頁面每 2 秒輪詢一次文件的 sha1 版本。如果別處（Agent 自身、其他編輯器）改了文件，buffer 乾淨時會自動同步；文本未保存時彈出提示而不是覆蓋。
3、安全保存。保存走 POST /agents-md-editor/api/save，請求裏帶上頁面加載時讀到的版本號。文件中途變了會返回 conflict（409），寫入被拒絕。寫盤先寫臨時兄弟文件再 rename，進程崩潰不會留下截斷的指令文件。
4、切換面板不丟草稿。切到會話再切回來，未保存的文本會還原。
5、跟隨主題字號。所有尺寸讀主題變量（--dsh-content-font-size、--dsh-content-font-size-secondary），沒有硬編碼 px。Settings → General 裏改正文字號，這個頁面跟着變。
安裝與啓用¶
從 registry 安裝：
dsh plugin --profile desktop add dsh-agents-md-editor
本地 checkout 的開發場景：
dsh plugin --profile desktop add ./dsh-agents-md-editor
兩種方式都會把 bundle 落到 profile，左側欄多一個入口（「代理說明編輯器」/「Agent Instructions Editor」）。
組件要求 Node.js >=22（見包內 engines）。
配置¶
filePath 是插件讀寫的唯一文件，默認 ~/.dsh/AGENTS.md。路徑裏的 ~ 和 ~/ 會被展開，相對路徑按 Host 進程的工作目錄解析。
- id: agents-md-editor
name: 'dsh-agents-md-editor'
config:
filePath: '~/.dsh/AGENTS.md'
提供的接口¶
兩條路由都由 ctx.connection.requestRejection 把關，與內置插件同一套瀏覽器信任柵欄，且都不接受路徑參數，因此可觸達範圍就是上面配置的那一個文件。
| 路由 | 方法 | 請求或返回 |
|---|---|---|
/agents-md-editor/api/state |
GET | { exists, path, content, version, mtimeMs, size } |
/agents-md-editor/api/save |
POST | 請求 { content, baseVersion }，返回 { path, version, mtimeMs, size, savedAt } |
version 是文件 UTF-8 字節的 sha1。
Host 側用 node:fs 直接寫，不走文件沙箱。原因是目標文件刻意位於會話工作區之外，UI 動作沒有審批通道。又因爲路由表不接受用戶傳入路徑，實際能寫的只有配置裏的那一個文件。
驗證與測試¶
node test/host.test.mjs # 或：npm test
測試針對 OS 臨時目錄中的一個一次性文件做 22 項檢查：文件不存在、首次創建、正常保存、baseVersion 過期返回 409 且文件不變、405/404/400、信任柵欄返回 403，以及 ~ 展開。測試不會打開真實的 ~/.dsh/AGENTS.md。
適用場景與注意¶
適合經常調整 AGENTS.md、希望改完直接生效並立刻看到結果的智能體開發者，也適合多人共用同一份指令文件、需要版本衝突提示的場景。
三條需要留意：
1、插件以當前 dsh 進程的權限運行，能讀寫的就是你在配置裏指定的那個路徑。安裝前先讀一遍源碼，再確認許可證（包內爲 MIT）。
2、保存時如果文件已被別處改動，請求會被拒絕並返回 409，此時要重新讀取文件再提交。
3、頁面每 2 秒輪詢一次文件版本，編輯窗口長期開着時會有持續請求。
結尾¶
這個插件的價值不在功能多，而在於把 AGENTS.md 從會話外面搬進了左側欄：改完即存、衝突即報、崩潰不留半截文件。
- 目錄頁：https://www.skillhub.cn/plugins/AikawaNaya/dsh-agents-md-editor
- GitHub：https://github.com/AikawaNaya/dsh-agents-md-editor
目錄站是獨立站點，與 DeepSeek / 幻方無官方從屬關係。
