前言¶
给智能体写协作规则，常见做法是把所有约定堆进一份全局提示词。规则一多就有两个问题：无关内容占用上下文，模型也分不清「哪条规则管哪些文件」。Claude Code 用 rules.md 和 # Path: 段落解决了这件事——规则自己声明管辖的文件范围，触碰匹配文件时才生效。
如果你在 DeepSeek Harness（DSH）上开发，想要同样的机制，下面介绍的 dsh-rules 提供的就是它：规则按 glob 匹配文件，agent 读取或编辑匹配文件时，规则内容自动注入对话。
这是什么¶
dsh-rules 由 rj-jiangyichen 维护，当前版本 0.1.1，MIT 许可证。定位一句话可以说清：为 DSH 提供 glob 激活的规则提示——每条规则声明 glob 模式，当 agent 触碰（读取/编辑）匹配文件时规则激活，内容以一条 <rules> 快照注入对话，并覆盖先前快照，机制上对标 Claude Code 的 rules.md / # Path: 风格。
DSH 的理念是「一切皆插件」，这个插件也遵循这一点：它适用于所有 DSH 部署形态——desktop / web / tui / headless / 自定义 profile，没有桌面专属依赖。
工作机制¶
先看规则从文件到对话的完整链路：
- agent 读取或编辑一个文件，插件以会话为单位记录触碰过的路径；
- 每个 step 由 agent/pre-step 监听器把触碰路径与所有规则的 glob 匹配，收集激活规则；
- 匹配结果渲染成一条
<rules>快照，作为用户消息注入对话。
围绕这条链路有几个值得留意的设计：
- 可见且持久：注入的是用户消息，UI 可见，会话日志也会留存；每个快照覆盖先前快照，模型始终看到当前生效的规则集。
- 字节预算：每次注入默认 32 KB（32768 UTF-8 字节），超预算时先丢弃低优先级规则，最后一条规则被截断；内容会转义，不会逃出框架标签。
- 会话恢复：resume 时从日志还原最后快照及其匹配文件，避免重复注入。
- 按会话跟踪：每个 agent/session 独立记录触碰过的文件，子代理也包括；没有声明 path 的全局规则始终激活。
- 规则热更新：规则源每步重新探测并带版本缓存，规则文件修改后下一步即生效。文件读取优先走 harness fs 服务（含包含性检查），未挂载 fs 服务时回退到 Node 文件系统。
安装与启用¶
通用安装方式，从 npm registry 一步完成安装并激活（profile 按部署形态换成 desktop / web / tui / headless）：
dsh plugin --profile desktop add dsh-rules
安装后重启 DSH（桌面形态重启应用，web / headless 形态重启进程）即可生效。更新用 update 子命令，也可以先 remove 再 add：
dsh plugin --profile desktop update dsh-rules
本地开发时，在仓库根目录执行下面这行命令：
dsh plugin --profile desktop add .
注意：pnpm 会在空格处拆分 add 参数，仓库路径含空格时必须通过无空格 junction 安装（如 mklink /J）。
DSH Desktop (Windows) 还提供一键脚本：先克隆仓库，再在仓库根目录运行：
node scripts\install-desktop.mjs
脚本完成后重启 DSH Desktop，插件即随下一次加载生效。
卸载有两种方式，任选其一：
# 方式一：一键脚本卸载
node scripts\install-desktop.mjs --uninstall
# 方式二：dsh 命令卸载
dsh plugin --profile desktop remove dsh-rules
安装与卸载都不会触碰 DSH 安装目录（resources\app.asar.unpacked），只改 profile 配置，完全可回退；操作后记得重启应用。环境要求：Node ^22.19.0 || >=24.0.0。
规则怎么写¶
规则有两种来源，可以混用。
来源 A：规则文件。 项目内放在 .dsh/rules/*.md，用户级规则放在 ~/.dsh/rules/*.md（可选）。frontmatter 的 path 字段声明 glob：
---
path:
- "src/**/*.ts"
- "!src/**/*.test.ts"
---
规则正文（markdown，激活时注入对话）
glob 语法支持 **、*、?、{a,b}、[abc] 及 ! 排除（底层是 picomatch），路径相对项目根、用 / 分隔。path 缺省或为空时，规则成为始终激活的全局规则。frontmatter 还支持可选的 name 字段，用于同名规则去重，缺省取文件名（去掉 .md 后缀）。
来源 B：# Path: 段落。 需要 includeClaudeSections: true。插件会解析 AGENTS.md / CLAUDE.md（含 .local.md 变体与 ~/.dsh/AGENTS.md）中的 # Path: 标题：
# Project notes
# Path: src/**/*.ts, scripts/**
这一段只在触碰 src/**/*.ts 或 scripts/ 下的文件时激活
每个 # Path: 标题开启一条规则，内容持续到下一个标题或文件末尾，globs 可用逗号或空格分隔。注意第一个 # Path: 标题之前的内容不由本插件注入——那部分由 DSH 内置的 agent-instructions 注入完整 AGENTS.md/CLAUDE.md 基线。
优先级与去重规则：项目规则（rank 100）> 用户规则（rank 200）> # Path: 段落（rank 300）。同名规则只保留优先级最高的那条；渲染顺序按 (rank, name) 确定，跨 step 保持一致。
配置¶
插件默认以代码内置值运行；要按 profile 覆盖，在 <profile>/cordis.patch.yml 中设置入口的 config：
- id: dsh-rules
name: dsh-rules
config:
includeClaudeSections: true
projectRootMarkers: [".git", ".dsh"]
上面这段开启了 # Path: 段落解析，并把项目根标记扩展为 .git 和 .dsh。常用配置项如下（完整列表以仓库 README 为准）：
| 配置项 | 默认值 | 说明 |
|---|---|---|
dshHome |
$DSH_HOME / ~/.dsh |
用户规则与 ~/.dsh/AGENTS.md 的根目录 |
projectRootMarkers |
[".git"] |
向上查找项目根时使用的标记文件/目录 |
ruleDirNames |
[".dsh/rules"] |
项目内规则目录（相对项目根，可配置多个） |
includeUserRules |
true |
是否启用 ~/.dsh/rules/*.md |
includeClaudeSections |
false |
是否解析 # Path: 段落 |
instructionFileCandidates |
["AGENTS.md", "CLAUDE.md"] |
# Path: 段落的候选文件名 |
localInstructionFileCandidates |
["AGENTS.local.md", "CLAUDE.local.md"] |
每目录候选文件名 |
maxBytes |
32768 |
每次注入的渲染预算（UTF-8 字节）；<= 0 时禁用插件 |
maxSourceBytes |
1048576 |
单条规则源文件大小上限，超限的文件被跳过 |
其中有两个边界容易踩到：maxBytes 设为 0 或负数会直接禁用整个插件；单个规则源文件超过 1 MB 会被整体跳过，不会部分注入。
适用场景与注意¶
适合谁：
- 在 DSH 上维护多模块项目，希望「改 src 走 src 的规范、改测试走测试的规范」的开发者；
- 从 Claude Code 迁移过来的团队——
.dsh/rules/*.md与 AGENTS.md / CLAUDE.md 里的# Path:段落都能直接沿用； - 在意上下文占用的场景：规则只在触碰匹配文件时注入，且有字节预算兜底。
注意事项：
- 插件以当前 dsh 进程的权限运行，安装前请先检查仓库源码与许可证（本项目为 MIT）。
- 本地仓库路径含空格时，必须先建立无空格 junction 再安装，否则 pnpm 会拆错 add 参数。
小结¶
dsh-rules 把 Claude Code 的按路径规则机制带进了 DSH：规则用 frontmatter 或 # Path: 声明 glob，agent 触碰匹配文件才注入，快照可恢复、预算可控，且适配 desktop / web / tui / headless 全部部署形态。如果你在 DSH 上管理多模块项目的协作规则，经过上面几步的安装与规则编写，就能直接用起来。
- 插件目录页：https://www.skillhub.cn/plugins/rj-jiangyichen/dsh-rules
- GitHub 仓库：https://github.com/rj-jiangyichen/dsh-rules
最后说明一句：上述目录页来自社区维护的插件站点，与 DeepSeek / 幻方无官方从属关系。
