rulemux 0.3.0 → 0.3.2

package/README.md

@@ -1,6 +1,7 @@
 # rulemux
 
-> One set of rules, delivered to every AI coding agent.
+> One set of rules, **one source of truth**: edit once, and it reaches **every agent in every
+> workspace**.
 > Same effect and same token cost as writing `AGENTS.md` by hand — **never fades out, never accumulates, no symlinks, free to add and remove files**.
 
 [中文版](README.zh-CN.md) | [Design docs](docs/design/architecture.md)
@@ -9,22 +10,98 @@
 
 ## 1. What is this
 
-You maintain a set of rule documents (coding conventions, project rules, …) and want every AI
-coding agent to read them in every workspace — with the exact same effect as if you had written
-`AGENTS.md` yourself.
+### 1.1 The pain
 
-`rulemux` takes the source files you list in a config and copies them into each agent's **native
-workspace rules directory**. You manage them in one place; they take effect everywhere.
+- **Every agent keeps rules somewhere else**: `.codebuddy/rules/`, `.claude/rules/`,
+  `.dsh/rules/`… one coding convention has to be rewritten once per agent.
+- **And every workspace keeps its own copy**: to make a rule apply in a workspace you write it
+  there again.
+- So the rules that are genuinely **shared** (team conventions, coding standards) can neither be
+  factored out nor maintained: one sentence means opening *agents × workspaces* files, with no
+  guarantee you did not miss one.
 
-- rulemux **does not own or maintain any rule content**. Your source files stay yours — rulemux
-  only copies them. Which agents / workspaces they apply to is declared in your config.
+### 1.2 What rulemux does
+
+You maintain **one source of truth**: a set of rule documents you wrote, declared in
+`~/.rulemux/config.toml` as the tree below. `rulemux sync` copies them — really copies — into
+each agent's **native rules directory**. Upper layers are inherited by the ones below them, so
+**one edit reaches every agent in every workspace on the next sync**.
+
+```
+One source of truth (your own .md files, declared in ~/.rulemux/config.toml)
+│
+├─ Layer 1 · org-wide rules ─────────────► every agent × every workspace
+│   │
+│   ├─ Layer 2 · dev rules
+│   │   ├─ Layer 3 · mini-app rules
+│   │   │   └─ …
+│   │   ├─ Layer 3 · backend rules
+│   │   │   └─ …
+│   │   └─ Layer 3 · client-side rules
+│   │       └─ …
+│   │
+│   └─ Layer 2 · non-dev rules
+│       └─ Layer 3 · workspace daily rules …
+│           └─ …
+│
+└─ Layer 4 · one workspace's own rules ──► only in that workspace
+
+              rulemux sync  ↓  real copies (never fades out / never accumulates / no symlinks)
+
+    workspace A ──► .codebuddy/rules/   .workbuddy/rules/   .dsh/rules/
+    workspace B ──► .codebuddy/rules/   .workbuddy/rules/   .dsh/rules/
+```
+
+- **Rules are reused**: layer 3 inherits layer 2, layer 2 inherits layer 1 — write what is shared
+  once, and get more specific as you go down.
+- **Layers fan out**: each layer declares which agents and which workspaces it applies to; no
+  file is duplicated per combination.
+- **Edit once, applies everywhere**: change a sentence up top and every workspace and agent that
+  inherits it is aligned on the next sync.
+- **No depth limit**: the `…` under layer 3 is a padding layer — `use` is expanded **recursively**,
+  so you can nest as deep as you like. The only thing not allowed is a **cycle**
+  (A uses B and B uses A), which fails at config load.
+
+The tree is built with `use` on `[[file_group]]` (inherit the layer above) plus `workspace` on
+`[[source]]` (where it lands):
+
+```toml
+[[file_group]]
+name = "base"                    # layer 1: org-wide
+path = ["/rules/00-base.md"]
+
+[[file_group]]
+name = "dev"                     # layer 2: dev rules
+use  = ["base"]                  # inherits layer 1
+path = ["/rules/10-dev.md"]
+
+[[file_group]]
+name = "miniapp"                 # layer 3: mini-app rules
+use  = ["dev"]                   # inherits layer 2 (and therefore layer 1)
+path = ["/rules/20-miniapp.md"]
+
+[[source]]
+groups    = ["miniapp"]          # lands as base + dev + miniapp
+workspace = ["/work/miniapp-a", "/work/miniapp-b"]
+
+[[source]]
+path      = ["/rules/proj-x-only.md"]   # layer 4: this workspace only
+workspace = ["/work/proj-x"]
+```
+
+See §5.2 for the full grouping and matching syntax.
+
+### 1.3 The invariants
+
+- **rulemux does not own or maintain any rule content**: your source files stay yours — rulemux
+  only delivers them. Which agents / workspaces they apply to is declared in your config.
 - **The session hook is (almost) only the courier.** Rule *content* is never injected: files are
   really copied into the directory the agent loads natively, so they enjoy static-prefix semantics
   (never fade out mid-conversation, never accumulate). The single, deliberate exception is one
   **transient notice line** the hook emits when it detects that the rules really changed — it asks
   you to start a new session. See §5.3.
-- Invariants: **no symlinks** (real copies only) and **free add/remove** (delete a source from the
-  config and its copy disappears on the next sync).
+- **No symlinks, free add/remove**: real copies only; delete a source from the config and its copy
+  disappears on the next sync.
 
 > Why not "just inject with a hook"? Hook injection lands in the dynamic part of the context: it
 > gets summarised away on compaction (fades out) or re-appended every turn (token blow-up).
@@ -42,9 +119,10 @@ directory and hook location have been confirmed by a real canary test. Today:
 | **codebuddy** | Tier-1 (real copy) | `.codebuddy/rules/` | ✅ **Verified — installable** (`codebuddy-cn` is an alias) |
 | **workbuddy** | Tier-1 (real copy) | `.workbuddy/rules/` | ✅ **Verified — installable** (separate app: own `~/.workbuddy/settings.json` hook, no longer an alias of codebuddy) |
 | claude (Claude Code) | Tier-1 | `.claude/rules/` | ⚠️ registered, **not verified yet** — cannot be installed |
-| trae (Trae) | Tier-1 | `.trae/rules/` | ⚠️ registered, **not verified yet** — cannot be installed |
+| **trae** (Trae CN) | Tier-1 (real copy) | `.trae/rules/` | ✅ **Verified — installable** (2026-10-09 canary: user-level hook `~/.trae-cn/hooks.json`; the international `~/.trae` build is not wired yet) |
 | codex | Tier-2 (injection) | none — injects into context | ⚠️ registered, **not verified yet** |
 | opencode | Tier-2 (injection) | none — injects into context | ⚠️ registered, **not verified yet** |
+| **dsh** (DeepSeek Harness) | Tier-1 (real copy) | `.dsh/rules/` | ✅ **Verified — installable**; the reading half is a **separate dsh plugin** — install it with `dsh plugin --profile <p> add rulemux-dsh` (rulemux only syncs; it does not install the plugin) |
 
 - `rulemux init` **refuses** any agent that is not verified — it will not half-install an adapter
   whose behaviour has not been proven. `rulemux doctor` marks unverified agents with ⚠.
@@ -52,6 +130,20 @@ directory and hook location have been confirmed by a real canary test. Today:
   single `AGENTS.md`). It injects via the session hook and never touches your own `AGENTS.md`, but
   it cannot satisfy the "never fades out" bar. See
   [design/features/hook-injection.md](docs/design/features/hook-injection.md).
+- **dsh is a two-part story**: it has no hook file. rulemux writes `.dsh/rules/` (Tier-1); a
+  **separate plugin package** in this repo ([`dsh-plugin/`](dsh-plugin/)) reads it back, installed
+  the normal dsh way — it is on npm as `rulemux-dsh`:
+  `dsh plugin --profile web add rulemux-dsh` (or straight from git:
+  `add "github:cq-guojia/rulemux#path:/dsh-plugin"`). So
+  `rulemux init --agent dsh` installs nothing — it just prints the plugin command.
+  That plugin then **sets itself up as dsh starts** (restart dsh after installing): readiness is three
+  steps and **all of them must hold** — the `rulemux` CLI is resolved *and* its version satisfies the
+  plugin's minimum (an older one is upgraded with pnpm/npm and re-checked — never accepted as-is),
+  the plugin itself is loaded, and `~/.rulemux/config.toml` exists (created for you when missing,
+  never overwritten). Any step that does not hold **raises**, so the session fails visibly instead of
+  quietly running without rules. Because it happens at startup, `~/.rulemux/config.toml` is already
+  there when you go to edit it: install → restart → edit the config → open **one** session. Syncing
+  is a separate concern: a failing `rulemux sync` is logged, and the session carries on.
 
 ---
 
@@ -93,6 +185,24 @@ rulemux init --refresh   # rewrite rulemux's OWN hooks only: never installs, nev
 moved this agent's config directory with `CODEBUDDY_CONFIG_DIR`, rulemux follows it — see
 [design/external/agent-rules-dirs.md](docs/design/external/agent-rules-dirs.md) §五.
 
+### 3.1 dsh: a plugin, not a hook
+
+Every other agent is “`rulemux init --agent <id>` installs a session hook”. **dsh is the exception**:
+it has no hook file, so `rulemux init --agent dsh` installs nothing and only prints the command
+below — the reading half is a dsh plugin:
+
+```bash
+dsh plugin --profile <your profile> add rulemux-dsh        # npm
+# or straight from git, to try an unreleased change:
+dsh plugin --profile <your profile> add "github:cq-guojia/rulemux#path:/dsh-plugin"
+```
+
+**Restart dsh after installing**: the plugin becomes ready when dsh starts — it checks the
+`rulemux` CLI (upgrading it and re-checking when it is too old) and creates `~/.rulemux/config.toml`
+when it is missing (never overwriting one that exists). Any step that fails raises, so a session
+never quietly runs without rules. Because this happens at startup, the config file is already there
+when you go to edit it: install → restart → edit the config → open **one** session.
+
 ---
 
 ## 4. Quick start
@@ -178,6 +288,9 @@ Things worth knowing:
 
 - **`use` is a list** — `use = ["dev", "qa"]` reuses several groups at once, and groups nest
   (A pulls in B plus its own files).
+- **There is no depth limit** — `use` is expanded **recursively** (for file groups and workspace
+  groups alike), so you can nest as deep as you like. The only thing not allowed is a **cycle**
+  (A uses B and B uses A), which fails at config load.
 - **Mixing is allowed**: `groups` with `path`, and `workspace_groups` with `workspace`, in the same
   source. The result is the union.
 - **Duplicates are harmless** — everything is deduplicated by value, so each file is processed once.

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # rulemux
 
-> 一份规则，投递到各家 AI coding agent。
+> 一套规则，**一个真源**：一处修改，同步到**所有 agent 的所有工作区**。
 > 效果与 token 与直接写 `AGENTS.md` 一致：**永不淡出、不累积、不用软链、加删文件自由**。
 
 [English](README.md) | [设计文档](docs/design/architecture.md)
@@ -9,17 +9,87 @@
 
 ## 1. 这是什么
 
-你维护着一套规则文档（编码约定、项目规矩……），希望每个 AI coding agent 在每个工作区都读到它，
-且效果和直接写进 `AGENTS.md` 一模一样。
+### 1.1 先说痛点
 
-`rulemux` 把你在配置里列出的源文件，复制进各 agent **原生的工作区规则目录** —— 一处管理，多处生效。
+- **每家 agent 的规则目录都不一样**：`.codebuddy/rules/`、`.claude/rules/`、`.dsh/rules/`……
+  同一条编码约定，要按各家的方式抄 N 遍。
+- **每个工作区又各有一份**：想让规则在哪个工作区生效，就得去那个工作区再写一遍。
+- 结果就是：那些**真正通用的规则**（团队约定、编码规范）既抽不出来，也管不动 ——
+  改一句话，要打开「agent 数 × 工作区数」个文件，改完还不敢保证哪份漏了。
 
-- rulemux **不持有、不维护任何规则内容**。源文件完全由你维护，rulemux 只负责复制；
-  「适用于哪些 agent / 哪些工作区」在你的配置里声明。
-- **会话钩子（几乎）只当「投递员」**：规则**正文**从不注入，文件是真正拷进 agent 原生加载的目录，
-  因此享有静态前缀语义 —— 不会随对话老化淡出，也不会每轮累积。
-  唯一刻意的例外：当钩子检测到规则**确有变化**时，会注入**一条瞬态提示**，请你新开会话（见 §5.3）。
-- 底线：**不用软链**（一律真实拷贝）、**加删自由**（配置里删掉某源文件，下次同步它的副本即消失）。
+### 1.2 rulemux 的做法
+
+你只维护**唯一的一份真源**：一组自己写的规则文档，在 `~/.rulemux/config.toml` 里按下面这棵树
+声明。`rulemux sync` 把它们**真实拷进每个 agent 的原生规则目录** —— 上层规则被下层继承复用，
+**改一处，所有 agent、所有工作区下一次同步就全变了**。
+
+```
+唯一真源（你自己写的 .md，在 ~/.rulemux/config.toml 里声明）
+│
+├─ 第 1 层 · 统一规则 ─────────────► 所有 agent × 所有工作区
+│   │
+│   ├─ 第 2 层 · 开发类规则
+│   │   ├─ 第 3 层 · 小程序开发规则
+│   │   │   └─ …
+│   │   ├─ 第 3 层 · 后台开发规则
+│   │   │   └─ …
+│   │   └─ 第 3 层 · C 端开发规则
+│   │       └─ …
+│   │
+│   └─ 第 2 层 · 非开发类规则
+│       └─ 第 3 层 · 工作区日常规则 …
+│           └─ …
+│
+└─ 第 4 层 · 某个工作区自己的规则 ──► 只在这个工作区生效
+
+              rulemux sync  ↓  真实拷贝（永不淡出 / 不累积 / 不用软链）
+
+    工作区 A ──► .codebuddy/rules/   .workbuddy/rules/   .dsh/rules/
+    工作区 B ──► .codebuddy/rules/   .workbuddy/rules/   .dsh/rules/
+```
+
+- **规则复用**：第 3 层继承第 2 层、第 2 层继承第 1 层 —— 通用的只写一次，越往下越具体。
+- **层级下放**：每一层各自声明「给哪些 agent、哪些工作区」，不用为每个组合复制一份文件。
+- **改一处，处处生效**：上层一句话改动，所有继承它的工作区与 agent 同步即到位。
+- **层数不限**：第 3 层下面那个 `…` 是垫层 —— `use` 是**递归展开**的，想套多少层就套多少层；
+  唯一不允许的是**成环**（A 引 B、B 又引 A），配置一加载就报错。
+
+搭这棵树用的就是 `[[file_group]]` 的 `use`（继承上层）+ `[[source]]` 的 `workspace`（限定落到哪）：
+
+```toml
+[[file_group]]
+name = "base"                    # 第 1 层：统一规则
+path = ["/rules/00-base.md"]
+
+[[file_group]]
+name = "dev"                     # 第 2 层：开发类
+use  = ["base"]                  # 继承第 1 层
+path = ["/rules/10-dev.md"]
+
+[[file_group]]
+name = "miniapp"                 # 第 3 层：小程序开发
+use  = ["dev"]                   # 继承第 2 层（也就含了第 1 层）
+path = ["/rules/20-miniapp.md"]
+
+[[source]]
+groups    = ["miniapp"]          # 落地 = base + dev + miniapp
+workspace = ["/work/miniapp-a", "/work/miniapp-b"]
+
+[[source]]
+path      = ["/rules/proj-x-only.md"]   # 第 4 层：只给这一个工作区
+workspace = ["/work/proj-x"]
+```
+
+完整的分组与匹配写法见 §5.2。
+
+### 1.3 几条不变的规矩
+
+- **rulemux 不持有、不维护任何规则内容**：源文件完全由你写，rulemux 只负责投递；
+  「给哪些 agent / 哪些工作区」在你的配置里声明。
+- **会话钩子（几乎）只当投递员**：规则正文从不注入，文件是真正拷进 agent 原生加载的目录，
+  因此享有静态前缀语义 —— 不淡出、不累积。唯一刻意的例外：检测到规则确有变化时，注入
+  **一条瞬态提示**请你新开会话（见 §5.3）。
+- **不用软链、加删自由**：一律真实拷贝；配置里删掉某源文件，下次同步它的副本即消失。
 
 > 为什么不直接用钩子注入？注入落在上下文的动态区，压缩时会被摘要掉（淡出），
 > 或每轮追加（token 爆炸）。见 [`docs/design/architecture.md`](docs/design/architecture.md) §一。
@@ -36,15 +106,27 @@ rulemux **每个 agent 一套适配器**；只有「规则目录 + 钩子落点
 | **codebuddy** | Tier-1（真实拷贝） | `.codebuddy/rules/` | ✅ **已验证，可安装**（`codebuddy-cn` 是它的别名） |
 | **workbuddy** | Tier-1（真实拷贝） | `.workbuddy/rules/` | ✅ **已验证，可安装**（独立应用：自有 `~/.workbuddy/settings.json` 钩子，不再是 codebuddy 的别名） |
 | claude（Claude Code） | Tier-1 | `.claude/rules/` | ⚠️ 已注册，**尚未验证**，不可安装 |
-| trae（Trae） | Tier-1 | `.trae/rules/` | ⚠️ 已注册，**尚未验证**，不可安装 |
+| **trae**（Trae CN） | Tier-1（真实拷贝） | `.trae/rules/` | ✅ **已验证，可安装**（2026-10-09 canary 坐实：用户级钩子 `~/.trae-cn/hooks.json`；国际版目录 `~/.trae` 尚未接入） |
 | codex | Tier-2（注入） | 无 —— 注入上下文 | ⚠️ 已注册，**尚未验证** |
 | opencode | Tier-2（注入） | 无 —— 注入上下文 | ⚠️ 已注册，**尚未验证** |
+| **dsh**（DeepSeek Harness） | Tier-1（真实拷贝） | `.dsh/rules/` | ✅ **已验证，可安装**；读取那半由**独立的 dsh 插件**做 —— 用 `dsh plugin --profile <p> add rulemux-dsh` 安装（rulemux 只负责同步，不替你装插件） |
 
 - `rulemux init` **会拒绝**未验证的 agent —— 不会给你装一个行为未经验证的半成品。
   `rulemux doctor` 会给未验证的 agent 标 ⚠。
 - **Tier-2 是刻意的降级**：面向没有规则目录、只认单个 `AGENTS.md` 的 agent，走会话钩子注入，
   且绝不碰你自己的 `AGENTS.md`；但它满足不了「永不淡出」。见
   [`docs/design/features/hook-injection.md`](docs/design/features/hook-injection.md)。
+- **dsh 是「两半」的故事**：它没有钩子配置文件。rulemux 负责写 `.dsh/rules/`（Tier-1）；读取那半由本仓库里
+  **独立的插件包** [`dsh-plugin/`](dsh-plugin/) 做，按 dsh 正常方式安装（npm 上就是 `rulemux-dsh`）：
+  `dsh plugin --profile web add rulemux-dsh`（也可 git 直装：
+  `add "github:cq-guojia/rulemux#path:/dsh-plugin"`）。
+  所以 `rulemux init --agent dsh` 什么都不装 —— 只打印插件安装命令。
+  装完后该插件会**在 dsh 启动时（插件装载）自动就绪**（装完插件记得重启 dsh）。就绪是**三步，必须全部成立**：
+  `rulemux` 命令行工具可得**且版本满足插件要求**（偏旧会用 pnpm/npm 升级并复查，不会「装了就当成过」）、
+  插件本身已装载、`~/.rulemux/config.toml` 存在（缺失则替你生成，**已存在绝不覆盖**）。
+  任何一步不成立就**抛错**，让失败在会话里可见，绝不悄悄跑在没有规则的状态下。
+  因为发生在启动时，你**去改配置时那份 `config.toml` 已经在**：装插件 → 重启 → 改配置 → 开**一次**会话即可。
+  同步是另一回事：`rulemux sync` 失败只记日志，会话照常继续。
 
 ---
 
@@ -81,6 +163,22 @@ rulemux init --refresh   # 只刷新「我们自己装过的」钩子：不新
 `CODEBUDDY_CONFIG_DIR` 把该 agent 的配置目录挪走过，rulemux 会跟随 —— 见
 [`docs/design/external/agent-rules-dirs.md`](docs/design/external/agent-rules-dirs.md) §五。
 
+### 3.1 dsh：装的是插件，不是钩子
+
+其余 agent 都是「`rulemux init --agent <id>` 装一条会话钩子」，**dsh 例外**：它没有钩子配置文件，
+所以 `rulemux init --agent dsh` 什么都不装 —— 只把下面这条命令打印给你。规则由插件那半读：
+
+```bash
+dsh plugin --profile <你的 profile> add rulemux-dsh        # npm
+# 想试未发布的改动，也可以从 git 直装：
+dsh plugin --profile <你的 profile> add "github:cq-guojia/rulemux#path:/dsh-plugin"
+```
+
+**装完要重启 dsh**：插件在 dsh 启动时就绪 —— 检查 `rulemux` 命令行工具（版本不够会自动升级并复查）、
+并在 `~/.rulemux/config.toml` 缺失时替你生成（已存在绝不覆盖）。三步缺一步就抛错，不会悄悄跑在
+没有规则的会话里。因为就绪发生在启动时，你去改配置时那份文件已经在了：装插件 → 重启 → 改配置 →
+开**一次**会话。
+
 ---
 
 ## 4. 快速开始
@@ -164,6 +262,8 @@ workspace        = ["/path/to/standalone"] # 也可与 workspace_groups 同时
 要点：
 
 - **`use` 是数组** —— `use = ["dev", "qa"]` 一次复用多个组，且支持嵌套（A 组引入 B 组再加自己的文件）。
+- **层数没有上限** —— `use` 递归展开（文件组、工作区分组都是），想套多少层就套多少层；
+  唯一不允许的是**成环**（A 引 B、B 又引 A），配置加载时直接报错。
 - **允许混合书写**：同一条 source 里 `groups` 可与 `path` 并存，`workspace_groups` 可与 `workspace` 并存，结果取并集。
 - **重复无害** —— 最终按值去重，每个文件只处理一次。
 - 文件组与工作区分组是**两套独立命名空间**，允许同名。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulemux",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "One set of rules, delivered to every AI coding agent: copies the rule files you declare into each agent's native workspace rules directory, with the same effect and token cost as writing AGENTS.md by hand.",
   "license": "MIT",
   "repository": {