rj-jiangyichen/dsh-rules

dsh-rules

License: MIT
DSH Plugin topic

面向 DeepSeek Harness（DSH）的 rules 插件：通过 glob 匹配文件路径，激活对应的提示词 / markdown 文档，对标 Claude Code 的 rules.md / # Path: 规则机制。每条规则声明 glob 模式；当 agent 读取或编辑了匹配文件时规则激活，其内容（任意提示词或 markdown 文档）作为一条"取代旧快照"的  用户消息注入对话。

适用于所有 DSH 部署：desktop / web / tui / headless / 自定义 profile——插件本身没有任何 desktop 专属依赖。

目录

- 特性
- 工作原理
- 安装
- 规则格式
- 配置项
- 发现与收录
- 已知限制
- 开发
- 许可证

特性

- glob 激活 —— 按 agent 触碰的文件逐个激活规则：、、?、{a,b}、[abc]、! 取反（picomatch）。
- Claude Code 兼容 —— 既支持规则文件（.dsh/rules/.md），也支持 CLAUDE.md / AGENTS.md 内的 # Path: 段落。
- 可见且持久 —— 激活的规则以用户消息注入，UI 可见、会话日志持久化；每次注入在对话里显示为一行可折叠的通知（与工具调用行同款外观，如 dsh-rules · Active rules: typescript, docs），展开可见完整规则文本；每个快照取代更早快照，模型始终看到最新集合。
- 预算可控 —— 字节预算渲染（默认 32 KB）：先丢弃低优先级规则，再截断最后一条；正文转义，无法逃逸框架标签。
- 恢复友好 —— 恢复会话时从日志恢复最近一次快照与已匹配文件列表，避免重复注入。
- 按会话跟踪 —— 每个 agent/会话独立跟踪触碰文件（含子代理）；无 path: 的全局规则恒激活。

工作原理

工作区
.dsh/rules/.md    ← 规则定义（frontmatter 声明 glob）
~/.dsh/rules/.md  ← 用户级规则（可选）
CLAUDE.md          ← 可选：# Path: 段落（Claude Code 兼容）

agent 读取/编辑文件（fs/observed）→ 记录每会话触碰路径
↓ 每个 step（agent/pre-step）
按 glob 匹配触碰路径 → 收集激活规则 → 渲染  快照注入对话

- 注入点：agent/pre-step 瀑布监听器追加一条  框架的用户消息；只在激活规则集合或规则正文变化时追加新消息——快照里的 matched files 列表只是渲染当时的记录，仅新增匹配文件不会重发规则正文。
- 发现与缓存：每个 step 重新探测规则源并做版本缓存（fs.stat().version，Node 回退为 mtimeMs:size）——规则文件改动在下一步即生效。
- 读取：优先 harness fs 服务（遵守沙箱约束）；无 fs 服务时回退 Node 文件系统。

安装

通用安装（任意 DSH 部署）

已发布到 npm registry —— dsh plugin 一步完成安装并激活：

profile 名按你的部署调整：desktop / web / tui / headless
dsh plugin --profile desktop add dsh-rules

插件包声明了 dsh.bundle.patch，dsh plugin add 的 reconcile 步骤会自动把 dsh-rules 追加到 profile 的 dsh.profile.bundles 层列表——无需手动编辑 cordis.patch.yml。重启 DSH（桌面版重启应用；web/headless 重启进程），插件随下次 Cordis 组合加载。

更新：dsh plugin --profile desktop update dsh-rules（或 remove 后 add）。

从本地仓库安装（开发模式）：

在仓库根目录执行——同样自动激活 bundle
dsh plugin --profile desktop add .

⚠️ pnpm 会按空格拆分 add 参数，仓库路径含空格时必须通过无空格 junction 安装（见下）。

DSH Desktop（Windows）一键脚本

1. 克隆本仓库后，在仓库根目录执行：
node scripts\install-desktop.mjs

2. 重启 DSH Desktop（插件在下次启动时随 Cordis 组合加载）

脚本会创建指向仓库的无空格 junction，并通过它执行桌面自带的 dsh plugin add（pnpm 按空格拆分 add 参数，路径含空格时必须走 junction）：

0) 为仓库创建无空格 junction（路径含空格时需要）
mklink /J "C:\code_repos\dsh-rules" "C:\code_repos\dsh rules plugin"

1) 用桌面自带的 dsh 命令把插件装进 profile（经 junction 路径）
& "C:\Program Files\DSH Desktop\DSH Desktop.exe" --expose-internals
"C:\Program Files\DSH Desktop\resources\app.asar.unpacked\lib\desktop-cli.js"
plugin --profile desktop add "C:\code_repos\dsh-rules"

按 profile 自定义配置（可选）：插件按代码默认值加载；如需定制，在 /cordis.patch.yml 里以 id 定位覆盖该条目的 config：

- id: dsh-rules
name: dsh-rules
config:
includeClaudeSections: true
projectRootMarkers: [".git", ".dsh"]

卸载：node scripts\install-desktop.mjs --uninstall（或 dsh plugin --profile desktop remove dsh-rules），再重启应用。安装/卸载均不修改 DSH 安装目录（resources\app.asar.unpacked），只动 profile 配置，可随时回滚。

规则格式

来源 A：规则文件（.dsh/rules/.md 与 ~/.dsh/rules/.md）

path:
- "src//.ts"
- "!src//.test.ts"

规则正文（markdown，激活时原样注入，可以是任意提示词内容）

| frontmatter 字段 | 说明 |
| --- | --- |
| path | 字符串或字符串数组；glob 相对项目根、使用 / 分隔符；! 前缀为排除模式。缺省或为空 = 全局常驻规则（工作区任意会话都激活）。 |
| name | 可选；规则标识（用于同名规则去重），缺省取文件名（去掉 .md）。 |

来源 B：# Path: 段落（需 includeClaudeSections: true）

从 AGENTS.md / CLAUDE.md（含 .local.md，以及 ~/.dsh/AGENTS.md）中解析 # Path:  标题段落：

项目说明（此段之前的内容交给 agent-instructions 基线处理，本插件不注入）

Path: src//.ts, scripts/
本段仅在触碰 src 下 .ts 或 scripts 下文件时激活

- 每个 # Path: 标题之后直到下一个标题（或文件尾）是一条规则。
- glob 支持逗号或空格分隔。
- 首个 # Path: 之前的内容不由本插件注入（DSH 内置的 agent-instructions 已负责注入 AGENTS.md/CLAUDE.md 基线全文）。

优先级与去重

项目规则（rank 100）> 用户规则（rank 200）> # Path: 段落（rank 300）。同名规则仅保留最高优先级者；渲染顺序按（rank, 名称）确定，保证跨 step 稳定。

配置项

| 配置 | 默认 | 说明 |
| --- | --- | --- |
| 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 | 单条规则源文件大小上限，超出跳过 |
| maxTouchedPaths | 512 | 每会话记录的触碰路径上限（FIFO 淘汰） |

发现与收录

本插件通过 GitHub dsh-plugin topic 被 DSH 生态发现——这是 DeepSeek Harness 官方 README "Community and support" 章节推荐的插件收录渠道（Add the dsh-plugin topic to your plugin repository for discoverability）。社区插件列表与市场（如 awesome-dsh-plugin、dsh-plugin-marketplace）据此自动扫描收录；仓库 About 栏可查看/添加该标签。

已知限制

- 只有项目根内的文件能激活规则；读取项目外文件不触发（避免 ../ 误匹配）。
- 触碰集合是内存态：恢复会话后，规则随 agent 重新读取文件逐步重新激活（已匹配文件列表会从日志恢复）。
- includeRuntimeContext: false 的部署不受影响（本插件注入独立消息，不依赖运行时上下文快照）。
- 规则注入为"取代旧快照"的消息流，会话日志中会保留历史快照；每个快照本身是完整集合，模型以最新快照为准。
- 快照里的 matched files 列表是渲染当时的记录：之后新增的匹配文件不会重发规则，所以模型手里那份清单可能滞后；激活集合始终以最新快照为准。

开发

pnpm install
pnpm test        # node --test：解析 / glob / 优先级 / 预算 / 确定性 / fs 回退

代码结构：

- lib/index.js — 插件入口（name / Config / apply）：fs/observed 触碰跟踪、agent/pre-step 注入、agent/disposed 清理。
- lib/rules.js — 纯函数：frontmatter 与 # Path: 解析、glob 编译匹配、优先级合并、预算渲染。
- lib/fs.js — 版本化发现/读取：优先 harness fs 服务，缺失时回退 Node fs。
- test/rules.test.mjs — 单元测试。
- examples/.dsh/rules/ — 示例规则（可直接复制到项目使用）。
- fixtures/demo-project/ — 现成的体验项目。

许可证

MIT