dsh-rules

RuleBase

DeepSeek Harness (dsh) 插件：全局 + 项目两级 Markdown 规则注入

以「全局 + 项目」两级 Markdown 规则文件为源，在每次对话开始 / 每次系统提示词组装时把规则注入给 AI，并在 dsh 设置面板提供可视化规则管理界面。

它能为你做什么：

• 把你想让 AI 记住的规矩，写进一处、处处生效——项目规范、代码风格、命令约定、注意事项等，以 Markdown 写成规则文件，dsh 每次对话自动把它注进系统提示词，AI 无需你重复交代。
• 全局一套 + 项目一套，互不干扰——全局规则（<DSH home>/rules/，跟随 DSH_HOME，未设置时为 ~/.dsh/rules/）管所有项目共用的规矩；项目规则（<cwd>/.dsh/rules/）跟着 agent.session.header.cwd 走，切到哪个项目就套用哪个项目的规则，跨项目切换自动跟随。
• 改一行、即时生效——规则文件保存即被文件监听捕获，下一次模型请求自动采用，无需重启 dsh。
• 可视化管理，不用碰命令行——dsh 设置面板「规则」区可直接增删改查全局/项目规则、一键刷新，配色随 dsh 亮/深外观自动切换。

一句话：RuleBase 让 AI 助手成为「懂你项目规矩的协作者」，把重复的口头交代固化成一劳永逸、随项目自动启用的规则库。

规则仅以 .md 文件持久化，不注册 dsh settings 命名空间、不写入 settings.yaml。

功能

• 注入：启动时扫描全局规则；每个新对话按 agent.session.header.cwd 扫描项目规则；全局 + 项目全量组装、全量替换，注入系统提示词。规则正文段以 ［规则库开始］ … ［规则库结束］ 成对标记包裹，为 AI 提供明确的规则库边界（0.1.9 起）。
• 项目路径识别：以 dsh 官方「当前主视图会话」（sessions.list 快照中 retainedBy.mainView > 0 的会话）的 cwd 作为当前项目路径，面板随切项目 / 切对话自动跟随；无主视图会话时视为「未选定项目」并提示。
• 即变即用：文件监听 + agent.inject()；保存规则后下一次模型请求自动采用。
• 管理界面：设置面板「规则」区支持全局 / 项目 tab、新建（下拉选全局/项目）、编辑（单击行或设置菜单）、删除、刷新；设置菜单与新建下拉在点击其它区域自动关闭，配色随 dsh 亮/深外观自动切换（--dsw-alias-* 主题 token）；项目 tab 在未选定项目时提示「请先开启一个项目对话」，保存项目规则时无项目会弹窗提示。

规则书写层级约定

规则文件按 Markdown 本能书写即可，无需记忆注入层级——注入时自动处理：

• 首行 # 标题 作为文件标题（承载为 H4）；
• 正文小节从 ## 起写（注入时自动降级到 H5）；
• 无论写 H1/H2/H3，注入时均按差值降级对齐，严格逐级递进。

示例：

# 我的规则

## 一、总则

内容…

## 二、细则

内容…

注入后层级：#### 我的规则(H4) → ##### 一、总则(H5) → ##### 二、细则(H5)，不倒挂。你写 #/##/### 均可，注入时会自动对齐；层级过深（原 H4 及更深）会被钳制到 H6（相邻层级可能因此合并显示）。

存储位置

每个 .md 文件即一条规则；文件名（去扩展名）作为规则 id。

从旧版本升级（v0.1.7 起）：全局规则目录改为跟随 DSH_HOME。默认安装（未设置 DSH_HOME）行为完全不变； 若你曾用非默认 DSH_HOME 的实例（例如测试实例）创建过全局规则，那些规则此前落在 %USERPROFILE%\.dsh\rules，升级后需手动搬迁到新 home 的 rules 目录。

安装与运行

⚠️ 不要在插件市场更新本插件。插件市场中升级的不是本插件，而是与之同名的其他项目。本插件未打包至 npm，但 npm 上有重名项目；下载安装该重名包会使 DeepSeek Harness 无法启动。请始终通过下文的 GitHub 源或本地 tarball 安装本插件。

发布态（从 GitHub 安装）

# 最新版（git 源安装，仓库含预构建产物，安装即用）
dsh plugin add github:mycodesite/dsh-rules

# 指定版本
dsh plugin add github:mycodesite/dsh-rules#v0.1.10

# 指定 profile（web / tui 等）
dsh plugin --profile web add github:mycodesite/dsh-rules

dsh plugin --profile dsh-tui add github:mycodesite/dsh-rules

注意：dsh plugin 是 pnpm 转发器。发布包已含预构建产物（lib/），git 源安装即装即用，无需在 profile 的 pnpm-workspace.yaml 中放行构建脚本（allowBuilds）。

dsh 版本支持线（v0.1.4 起）：dsh ≥0.1.5-rc.1。0.1.5 起 client-connection 的 rpc.handle 两参化、 connection 服务先于 webServer 可用，本插件已按新范式适配（规则端点经 /api 共享通道精确路由 /api/rulebase/<op> 承载、per-channel authority 选项废弃、鉴权由传输层 BrowserAuth + Host/Origin fence 统一接管）。面板操作失败不再静默挂起：任何失败均以错误文本或弹窗可见呈现。 旧版 dsh（≤0.1.1-rc.2）不在支持范围。

也可以下载 GitHub Releases 中的最小化 tarball（仅含构建产物与 patch），本地安装：

dsh plugin add /path/to/rulebase-<版本>.tgz

# 指定 profile 安装本地包
dsh plugin --profile <模式> add /path/to/rulebase-<版本>.tgz

安装矩阵

运行时零依赖带来的改变（v0.1.2 起）：已构建的源码树以 link: 安装时，不再需要该目录下有 node_modules。构建本身仍需 devDependencies（tsdown / esbuild）——这是开发期依赖，正常且不可避免。

卸载

# web profile
dsh plugin --profile web remove rulebase

# tui profile
dsh plugin --profile dsh-tui remove rulebase

注意：remove 的参数必须用注册名（包名）rulebase，不能用安装源写法（如 mycodesite/dsh-rules、github:mycodesite/dsh-rules、dsh-rules）。dsh plugin 是 pnpm 转发器，remove 按 profile package.json 中依赖的 key 匹配——该 key 是 pnpm 安装时解析出的包名 rulebase，与安装时使用的源写法无关；用源写法会报 ERR_PNPM_CANNOT_REMOVE_MISSING_DEPS: no such dependency found（web 与 tui 行为一致）。卸载后 dsh.profile.bundles 层也会自动移除该插件。

开发态（源码直接挂载）

npm install
node scripts/make-dev-patch.mjs          # 生成 cordis.local.yml（git 忽略，不提交）
dsh web --patch ./cordis.local.yml       # web 模式
dsh --profile dsh-tui --patch ./cordis.local.yml  # tui 模式

.npmrc 中已配置 legacy-peer-deps=true，开发态安装无需手动传 --legacy-peer-deps 标志。

cordis.local.yml 由脚本按仓库绝对路径生成，仓库内不写死本机路径，克隆后可移植。

脚本

目录结构

src/
├─ host/
│  ├─ index.ts       # 装配入口（apply）：store / injector / service
│  ├─ paths.ts       # 规则级别与目录解析
│  ├─ store.ts       # RuleStore：md 文件读写
│  ├─ injector.ts    # RuleInjector：注入与刷新（异步读盘 + 同步读缓存）
│  └─ service.ts     # RulesService：Connection RPC 桥（UI↔host）
├─ client/
│  ├─ index.ts       # 注册 settings.section
│  ├─ types.ts       # 最小类型（Rule / RpcResult）
│  ├─ controller.ts  # RuleController：列表状态机 + rpc 客户端
│  └─ RuleSection.tsx# 设置面板「规则」区 UI
scripts/
├─ build-client.mjs     # client 半 esbuild 构建
├─ make-dev-patch.mjs   # 生成开发态补丁
├─ release.mjs          # 发布准备（typecheck+test+build+pack）
└─ sync-dsh-deps.mjs    # 自动跟随 DSH next 通道同步 devDeps
tests/
└─ smoke.test.ts        # RuleStore 全量读写 / 路径解析
docs/
├─ API文档.md           # 模块 API 总览
└─ api/                 # 分模块文档
.github/workflows/ci.yml # CI：typecheck + test + build + pack（tag 自动发 Release）

文档

• 模块 API：见 docs/API文档.md 与 docs/api/。
• 变更记录：见 CHANGELOG.md。

环境要求

• Node.js >= 22.5
• 运行时零依赖：本插件对 @deepseek-ai/dsh-* 与 @deepseek-ai/cordis 仅有编译期类型依赖（import type，转译后擦除）；宿主契约函数（createUserMessage / transportError）已在 src/host/contract.ts 本地逐字实现。因此任意安装形态、任意新环境（包括无 node_modules 的目录）均可直接运行，不依赖宿主依赖闭包。
• 构建期守卫：npm run build 内置产物检查（check:artifact），产物含任何 @deepseek-ai/* 运行时导入即构建失败——这是本插件的核心安全不变量，由 CI 与 npm pack（prepack → build）双重覆盖。

许可

MIT © mycodesite