规则语义检索 songjongdevsecops/dsh-regras

dsh-regras

在 DeepSeek Harness 里，对目录树中的 Markdown 规则做语义搜索。

智能体靠 AGENTS.md 和 README.md 了解仓库怎么运作。dsh-regras 用 memsearch 给这些文件建索引，再给智能体一个工具，用来找出适用于当前任务的规则，并带上真实文件路径和行号范围，方便它打开原文。另有一条命令提供卫生报告：疑似重复的条目、已不存在的路径引用，以及代码改了、文档却没跟上的地方。

一行插件，两个入口：

| 谁用 | 怎么用 | 得到什么 |
| 智能体 | qual_regra 工具 | 适用于当前任务的规则片段，带真实路径和行号范围 |
| 你，在聊天里 | /regras [higiene \| pares \| buscar <termo>] | 卫生报告，或一次规则搜索 |

环境要求

- Node.js ^22.19.0 || >=24.0.0（与 DeepSeek Harness 支持的范围一致）。
- pnpm 在 PATH 上；harness 用它管理配置档插件。
- DeepSeek Harness 本体，例如 npx @deepseek-ai/dsh web。
- memsearch 用来建索引，需要本地 ONNX 嵌入扩展： uv tool install "memsearch[onnx]"（或 pipx install "memsearch[onnx]"）。

qual_regra 工具是纯 Node.js。/regras 卫生报告是 bash 加 Python 脚本（relatorio.sh 调用 relatorio.py），所以能在 Linux 和 macOS 上跑；Windows 上请从 WSL 或 Git Bash 运行，并确保 Python 可用。

安装

1. pnpm (needed by dsh plugin)
npm install -g pnpm

2. add the plugin to your web profile
npx @deepseek-ai/dsh plugin --profile web add github:songjongdevsecops/dsh-regras

3. restart the harness: the bundle layer is read at boot
npx @deepseek-ai/dsh web

如果 dsh 已经全局安装，第 2 步就是 dsh plugin --profile web add github:songjongdevsecops/dsh-regras。

包声明了 dsh.bundle.patch，所以 dsh plugin add 会把 dsh-regras 追加到配置档清单的 dsh.profile.bundles 里。这一行就是唯一的启用方式，每次启动都会生效。

检查已加载的行：

npx @deepseek-ai/dsh --profile web --dump-config | grep -A3 regras

预期结构：

- id: regras
name: dsh-regras
config: {}

更新与卸载

update: re-run the add command, then restart the harness
npx @deepseek-ai/dsh plugin --profile web remove dsh-regras # uninstall, then restart

建索引

dsh-regras 读取已有的 memsearch 集合，自己不嵌入任何内容。先给存放规则的目录树建一次索引：

memsearch index ~/workspaces -c regras-bgem3-v1
memsearch stats -c regras-bgem3-v1

这条命令会给目录树下所有 Markdown 文件建索引。如果你只想要 AGENTS.md 和 README.md，就给 memsearch index 一个只含这些文件的目录（用符号链接镜像也行）。插件通过以下方式解析每个命中项： realpath，所以答案引用的始终是真实文件，不是镜像。

集合名是索引与插件之间的约定：默认 regras-bgem3-v1，两边都可配置。

配置

每个路径都可配置，默认值从你的主目录推导，不绑定特定机器。用环境变量覆盖，或在配置档补丁的 regras 行配置里覆盖。补丁会替换该行的整份配置，所以想保留的键都要重新写一遍。

| 配置键 | 环境变量 | 默认值 | 含义 |
| raiz | DSH_REGRAS_RAIZ | ~/workspaces | 规则树根目录 |
| colecao | DSH_REGRAS_COLECAO | regras-bgem3-v1 | memsearch 集合 |
| memsearch | DSH_REGRAS_MEMSEARCH | ~/.local/bin/memsearch | memsearch 可执行文件 |
| espelho | DSH_REGRAS_ESPELHO | <package>/.espelho，否则 raiz | 卫生报告扫描的语料 |

报告还会用到 DSH_REGRAS_PY（一个装有 pymilvus 和 numpy 的 Python 解释器）；默认先用 memsearch 工具环境，再退回 python3。

配置档补丁示例（~/.dsh/profiles/web/cordis.patch.yml）：

- id: regras
config:
raiz: '/home/you/rules'
colecao: 'regras-bgem3-v1'
memsearch: '/home/you/.local/bin/memsearch'
espelho: '/home/you/rules'

用法

问智能体某个东西该放哪、怎么命名、什么被禁止、归谁管。它会调用 qual_regra，拿到匹配的片段及其来源路径。

在聊天里：

/regras buscar naming # five best rule segments
/regras higiene # duplicate candidates, orphan paths, doc/code drift
/regras pares # the candidate pairs, with both texts, for review

higiene 会在包旁边写出 relatorios/<date>-higiene/，里面有 relatorio.md 和 pares-candidatos.jsonl。重复项那一行只是候选：嵌入衡量的是主题接近度，不是矛盾，两条相反的规则在向量空间里看着很像。读者拿着两段原文自己判断。什么都不会被改写：报告只读文件。

验证

从仓库的克隆里：

node --test tests/
python3 scripts/relatorio.py --selftest

测试套件覆盖工具与命令注册、真实路径解析、密钥路径拒绝和包约定。报告自测覆盖路径引用、孤儿检测、git 漂移和 kNN。两者都不需要索引。

要验证安装，看上面的 dump-config 输出，再问智能体一条规则。

排障

- binário não encontrado: memsearch —— 安装 memsearch，或把 DSH_REGRAS_MEMSEARCH 指向该可执行文件。
- 没有结果 —— 集合是空的，或者名字不一样。运行 memsearch index <tree> -c <name>，让名字对上。
- 报告提示 pymilvus indisponível —— 运行报告的解释器没有 pymilvus。把 DSH_REGRAS_PY 设为 memsearch 环境的 Python （~/.local/share/uv/tools/memsearch/bin/python），然后重启 harness，或者直接运行 DSH_REGRAS_PY=<that-python> bash scripts/relatorio.sh。
- pnpm not found on PATH — 执行 npm install -g pnpm，然后重新运行。
- 插件已安装，但什么都没出现 — 重启 harness；bundle 层在启动时读取，安装时不会读取。

License

MIT