前言¶
在 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 / 幻方无官方从属关系。
