dsh-glob-rules

dsh-glob-rules

中文 | English

为 DeepSeek Harness（DSH）提供 glob 激活式规则提示——Claude Code rules.md / # Path: 风格的机制。每条规则声明 glob 模式；当 agent 读取或编辑 匹配的文件时，规则激活，其内容（任意提示词或 markdown 文档）以一条“取代旧快照”的 <rules> 消息注入对话。

这是 dsh-rules 的 TypeScript 重制版，行为一致，但按当前官方插件开发文档与本机安装的框架版本（cordis 4.x、dsh-* rc 包）重写。与原版相比的关键 API 变化：会话历史改用 session.snapshotEvents() 读取（旧版 session.events 数组已不存在）；同时改为与现生态一致的 TypeScript + tsc 构建。

适用于所有 DSH 部署形态：桌面 / web / tui / headless / 自定义 profile。

特性

• Glob 激活 — 按 agent 触碰的文件激活规则：支持 **、*、?、{a,b}、[abc] 与 ! 取反（picomatch）。
• 兼容 Claude Code — 支持普通规则文件（.dsh/rules/*.md），也支持 CLAUDE.md / AGENTS.md 中的 # Path: 段落。
• 可见且持久 — 激活的规则作为用户消息注入：UI 可见、会话日志持久保存；每条快照取代之前的快照，模型始终看到当前集合。
• 会话格式 v4 的 source 契约 — 每条快照都声明生产者自有的消息 source（{ kind: 'dsh-glob-rules', form: 'instructions' }）。DSH 0.1.7+（会话格式 v4）拒绝已废弃的共享写法 { kind: 'plugin', plugin: … }——它会让整轮对话失败并报 "format v4 message requires a producer-owned source kind"——本插件不再产生该写法；同时旧版内核写入会话日志的旧写法，在续聊播种时仍能被识别。
• 预算受限 — 按字节预算渲染（默认 32 KB）：优先丢弃低优先级规则，最后一条被截断；内容被转义，不会逃逸出框架标签。
• 可续聊 — 会话续聊时从日志（session.snapshotEvents()）恢复最近一次快照及其匹配文件，避免重复注入。
• 按会话跟踪 — 每个 agent/会话各自记录触碰的文件（含子代理）；无 path 的全局规则始终激活。

工作方式

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

agent 读取/编辑文件（fs/observed）→ 记录本会话触碰路径
  ↓ 每一步（agent/pre-step）
用 globs 匹配触碰路径 → 收集激活规则 → 渲染 <rules> 快照注入对话
  （快照 source 声明本插件自有 kind：{ kind: 'dsh-glob-rules', form: 'instructions' }）

安装

包声明了 dsh.bundle.patch（DSH bundle），因此 dsh plugin 一条命令即可安装并激活：

# 按需调整 profile 名：desktop / web / tui / headless
dsh plugin --profile desktop add dsh-glob-rules

reconcile 会自动把 dsh-glob-rules 追加进 profile 的 dsh.profile.bundles 层列表——无需手工编辑 cordis.patch.yml。重启 DSH 后插件随下一次 Cordis 组合加载。

本地或 git 安装：包带 prepare 脚本（tsc 从 src/ 构建 lib/），因此 dsh plugin --profile desktop add .（或 add github:you/dsh-glob-rules）同样可用。pnpm ≥10 会先要求你放行 git 依赖的 prepare 脚本：把 pnpm 打印的包 key 抄进 profile 的 pnpm-workspace.yaml 的 allowBuilds 后重试 add。

按 profile 覆盖默认配置（可选），在 <profile>/cordis.patch.yml 中写：

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

卸载：dsh plugin --profile desktop remove dsh-glob-rules，然后重启。

规则格式

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

---
path:
  - "src/**/*.ts"
  - "!src/**/*.test.ts"
---
规则正文（markdown，激活时原样注入——任何提示词内容均可）

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

解析 AGENTS.md / CLAUDE.md（含 .local.md 变体与 ~/.dsh/AGENTS.md）中的 # Path: <globs…> 标题：

# 项目说明（首个标题之前的内容由内置 agent-instructions 处理，不属于本插件）

# Path: src/**/*.ts, scripts/**
仅当触碰 src/**/*.ts 或 scripts/ 下文件时本段落才激活

• 每个 # Path: 标题开启一条规则，直到下一个标题或文件末尾。
• globs 可用逗号或空格分隔。
• 首个 # Path: 之前的内容有意不注入——DSH 内置的 agent-instructions 已注入完整 AGENTS.md/CLAUDE.md 基线。

优先级与去重

项目规则（100）> 用户规则（200）> # Path: 段落（300）。同名保留高优先级条目；渲染按 (rank, name) 排序，跨步骤确定。

配置

开发

pnpm install
pnpm run check   # typecheck + build（tsc）
pnpm test        # node --test：解析 / glob 匹配 / 优先级 / 预算 / 确定性 / fs 回退

目录结构：

• src/index.ts — 插件入口（name / Config / apply）：fs/observed 触碰跟踪、agent/pre-step 注入、agent/disposed 清理、基于 session.snapshotEvents() 的续聊恢复。
• src/rules.ts — 纯逻辑：frontmatter 与 # Path: 解析、glob 编译/匹配、优先级合并、预算渲染。
• src/fs.ts — 带版本缓存的发现/读取：优先 harness fs 服务，回退 Node 文件系统。
• test/rules.test.mjs、test/apply.test.mjs — 单元 + apply 级测试（对编译后的 lib/ 运行）。
• examples/.dsh/rules/ — 示例规则（复制进你的项目即可上手）。
• fixtures/demo-project/ — 现成的试玩项目。

License

MIT — 保留对本项目所移植原版 dsh-rules 的署名。