规则文件编辑器 Ytibu/dsh-agents-md

dsh-agents-md

给 DeepSeek Harness 加一个 AGENTS.md 的可视化编辑器。

不用再手动找文件、手动复制粘贴——在设置面板里点几下，就能编辑和生成 AGENTS.md。

适用版本：DSH 0.2.0-rc.2（详见文末兼容性）

它解决什么问题

DSH 会读取 AGENTS.md 里的规则来决定怎么干活。但手动管理这些文件很麻烦：

| 你可能遇到的麻烦 | 这个插件怎么办 |
| 找不到全局规则文件在哪，路径记不住 | 设置里直接打开编辑，页面会显示解析到的真实路径 |
| 换个项目就要再找一遍项目规则文件 | 下拉选工作区，直接编辑该项目的 AGENTS.md |
| 想让项目规则「整体继承全局规则，再加上项目特有的要求」，只能手动复制粘贴 | 选「合并全局规则」，AI 帮你融合成一份完整规则 |
| 不小心把已有规则覆盖没了 | 写入前自动备份成 AGENTS.md.bak-<时间戳>，同一毫秒内的多次保存也不会互相覆盖 |

插件不改变 DSH 的任何行为，只是给这些文件加了一个好用的编辑界面。

三个功能

1. 编辑全局规则

读写全局规则文件——它对所有项目生效。

- 路径解析与 DSH 完全一致：优先 $DSH_HOME/AGENTS.md，没设置就用 ~/.dsh/AGENTS.md
- 文件不存在时，保存会自动创建

2. 编辑项目规则

读写指定项目根目录下的 AGENTS.md。

- 从下拉列表选工作区，编辑它根目录的 AGENTS.md
- 同样支持自动创建与自动备份

3. 生成项目规则（这是最省事的一个）

你只需要用大白话写下你想要的规则，插件帮你生成规范的 AGENTS.md：

1. 选一个工作区
2. 写下你的要求，比如：

这个项目必须用 pnpm，不要用 npm 提交信息用中文改数据库前先写迁移脚本

3. 选一种生成方式（见下表）
4. 先预览，确认后才写入——在你点「确认写入」之前，磁盘上不会有任何改动

| 生成方式 | 做什么 | 什么时候用 |
| 合并全局规则 | 调 AI 把你的输入和全局 AGENTS.md 融合成一份完整规则：保留全局里仍然有效的要求，重复的合并，冲突时以你的项目规则为准 | 想让项目既遵守全局约定，又有自己的额外要求 |
| 直接覆盖 | 直接用你的输入生成，不参考全局规则 | 这个项目完全独立，不需要继承全局 |

全局规则文件不存在或为空时，「合并全局规则」会直接使用你输入的内容，不会报错。

生效时机

保存后：

- 新会话：立即生效
- 当前会话：在下一次文件操作后感知到新规则

（由 DSH 内置的动态检测机制负责，插件本身不做热重载。）

安装

以下内容面向愿意动手的使用者。

装进任意 DSH profile（目录形如 $DSH_HOME/profiles/<名字>）需要两步。

第一步：在 profile 的 package.json 里加上依赖，然后在 profile 目录执行 pnpm install：

"dsh-agents-md": "file:/绝对路径/to/dsh-agents-md"

当前 DSH 0.2.0-rc.2 没有随附 dsh CLI，所以上面这种 profile 手动安装是唯一可用的方式。
等 CLI 随版本发布后，也可以直接用 dsh plugin --profile web add Ytibu/dsh-agents-md——本插件的 package.json 已按该约定声明 dsh.bundle.patch 与 dsh.client，无需改动。

第二步：在同一个 package.json 的 dsh.profile.bundles 数组里加上插件名：

"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-agents-md"
]
}
}

只加 dependencies 不会让插件装载——必须同时加进 bundles。

最后重启 dsh web，打开 设置 → 「AGENTS.md 管理」。

本地开发时怎么让改动生效

file: 依赖在 pnpm 的 hoisted linker 下是硬链接，因此：

- 原地编辑已有文件会自动同步，不用重装
- 新增/重命名文件，或用「写临时文件再 rename」的原子保存（会断硬链接）时，需要重新 pnpm install

想彻底避开这类不确定性，可以把 profile 里的目录换成指向源码的联接：

Remove-Item "<profile>\node_modules\dsh-agents-md" -Recurse -Force
New-Item -ItemType Junction -Path "<profile>\node_modules\dsh-agents-md" -Target "<源码目录>"

另外：同步的只是文件，插件模块要重启 dsh web 才会重新加载（Client 半边随页面刷新更新，Host 半边不会）。

兼容性

仅适用于 DSH 0.2.0-rc.2

| 项 | 值 |
| 开发与测试所依据的 DSH 版本 | 0.2.0-rc.2 |
| 对应应用包 | @deepseek-ai/dsh-desktop / @deepseek-ai/dsh-desktop-runtime 0.2.0-rc.2 |
| 分发渠道 | nightly |

本插件用的是 DSH 内部契约，不是稳定的公开 API。 版本一变，下列接口可能改名或消失，插件会随之失效（通常表现为设置页入口消失，或路由 404）： ctx.connection.fetch.register · ctx.workspaceRegistry · ctx.llm.stream · ctx.agentDefaultModel.currentSelection · slots 服务与 settings.section 槽位 · window.__ModuleLoader__.load

换 DSH 版本后请先跑一次自检：

node check-contracts.mjs

它直接读你本机安装的 DSH 源码，打印你的版本并逐项核对上述契约；退出码 0 表示兼容。你的版本与 0.2.0-rc.2 不一致时，这个脚本的结论比本文档更可信。

常见问题

设置里看不到「AGENTS.md 管理」入口？ 最常见的原因是只加了 dependencies、没加进 dsh.profile.bundles（两步缺一不可），然后需要重启 dsh web 并刷新页面。

页面提示 401 / 会话未通过鉴权？ 这是预期行为——接口受 DSH 鉴权保护，非浏览器会话访问会被拒绝。刷新页面重新登录即可。

改了源码但没生效？ 分两层：文件同步（file: 依赖是硬链接，原地编辑自动跟随，新增文件需重装）与模块加载（Host 半边必须重启 dsh web）。

更多症状（合并失败、降级提示、备份文件、EBUSY、换版本后失效）见 TROUBLESHOOTING.md。

给开发者

工作原理与自检脚本

Host（lib/index.js）用 ctx.connection.fetch.register 注册 5 条 Fetch 路由，挂在 Connection 的 /api 通道上——因此自动落进 Host/Origin 栅栏与浏览器鉴权：

| 路由 | 方法 | 作用 |
| /api/agents-md/global | GET / POST | 读 / 写全局 AGENTS.md |
| /api/agents-md/project?workspace=<id> | GET / POST | 读 / 写 <工作区>/AGENTS.md |
| /api/agents-md/compose | POST | 生成内容，不落盘 |
| /api/agents-md/workspaces | GET | 工作区列表 |
| /api/agents-md/models | GET | 模型目录 |

必须走 connection.fetch：若改用 ctx.webServer.register 注册 kind:'exact' 的 /api/... 路由，会遮蔽 Connection 的 /api 前缀栅栏（webServer 的路由匹配是「先查 exact 表，未命中再最长前缀」），使只读接口失去鉴权。

Client（lib/client.js）是手写 __ModuleLoader__.load bundle，注册 settings.section 槽位，零构建。

自检脚本

node test-smoke.mjs # 离线冒烟测试（65 项断言，不需要运行中的 DSH）
node test-client-contract.mjs # 客户端契约测试（19 项断言，锁住 host/client 接口一致）
node check-contracts.mjs # 兼容性自检：核对本机 DSH 是否满足所依赖的契约
node check-live.mjs # 运行态自检：栅栏是否生效 + client bundle 是否注入

目录结构

dsh-agents-md/
├── cordis.patch.yml # bundle patch：插入插件层 ├── package.json # 含 dsh.compat（记录测试版本与依赖契约） ├── lib/ │ ├── index.js # Host：5 条 connection.fetch 路由 │ └── client.js # Client：手写 __ModuleLoader__ bundle ├── test-smoke.mjs # 离线冒烟测试 ├── test-client-contract.mjs # 客户端契约测试 ├── check-contracts.mjs # 兼容性自检 ├── check-live.mjs # 运行态自检 ├── CHANGELOG.md # 更新日志 └── TROUBLESHOOTING.md # 故障排查

参与贡献

欢迎贡献。提 issue 请务必附上你的 DSH 版本和 node check-contracts.mjs 的完整输出——这两样能直接区分「版本不兼容」还是「代码有问题」。仓库里有问题模板会提醒你填。

改动代码前请读一下 CONTRIBUTING.md，重点只有一条：新增对 DSH 内部契约的依赖时，要同步更新 check-contracts.mjs 和本文档的兼容性表格——这是插件最容易在 DSH 升级时静默失效的地方。

License

MIT