bvcvb/dsh-baize-rules

dsh-baize-rules

English | 简体中文　—　中文说明见 README.zh.md。

dsh-baize-rules (Baize) is a dsh plugin that injects user-set, durable "must-do / must-not" requirements — plain-text rules — into the model at conversation start as a sourced user/message.

The name comes from Baize (白泽) — a mythical beast said to "understand the nature of all creatures, know the names of all things, and comprehend the principles of everything." It carries the behavioral baseline that the user sets for the model.

• Rules are plain text with no must/mustNot markers — whether something is "must-do" or "must-not" is expressed by the language of the body itself (e.g. Write comments in Chinese. = must, Do not delete the tests. = must-not).
• Injection happens at the start of a conversation: the currently active rules are injected into the model request as a persistent user/message, wrapped in a <system-reminder> frame, with source.kind='plugin' and plugin='baize-rules'.
• No rules → no injection; if the byte budget shrinks such that all rules are cut, it returns undefined and never injects an empty reminder shell.

---

Features

How this compares to AGENTS.md instructions

dsh ships @deepseek-ai/dsh-agent-instructions, which loads the workspace instruction chain (AGENTS.md / CLAUDE.md). The two are complementary — pick by where the rule has to live:

Both inject a sourced user/message framed with <system-reminder>, and both carry the same precedence sentence, so they reinforce rather than fight each other.

---

Installation

dsh plugins are distributed from npm and installed into a profile via dsh plugin.

# Install from npm into the web profile (use the actual published version)
dsh plugin --profile web add dsh-baize-rules@0.2.4
pm2 restart dsh          # Reload when dsh is managed by pm2
dsh --profile web

Peer dependencies (@deepseek-ai/*, react, etc.) are provided by the dsh profile; if any are missing, pnpm resolves them against peerDependencies in the profile directory.

Uninstall

# Remove the plugin from the profile
dsh plugin --profile web remove dsh-baize-rules
pm2 restart dsh          # Reload when dsh is managed by pm2

If the entry lingers in the profile's dsh.profile.bundles, delete that line from $DSH_HOME/profiles/web/package.json and restart dsh again. Your rule files under $DSH_HOME/rules/ are not touched — delete them by hand if you want a clean slate.

Try it without touching your running setup

Install into a separate profile so your currently running dsh stays unchanged:

dsh plugin --profile smoke add dsh-baize-rules@0.2.4
dsh --profile smoke --dump-config   # read & compose the config only — does not boot dsh

--dump-config only composes and prints the tree; it does not start a server, so it is safe to run alongside your live dsh. To actually try the plugin in that profile, run dsh --profile smoke.

Note on pm2 restart dsh: it reloads the profile you are running. Install/remove only changes the profile on disk — nothing takes effect until the next boot (or that restart).

Local development (link)

If you haven't published yet, or want to pick up source changes live, use this directory as a link dependency:

// /home/abc/.dsh/profiles/web/package.json
"dependencies": {
  "dsh-baize-rules": "link:/home/abc/work/plugin/dsh-baize-rules"
}

Then run pnpm install in the profile directory and add dsh-baize-rules to dsh.profile.bundles.

---

Quick Start

/baize-rules                                   # Same as /baize-rules list: show the currently active rules
/baize-rules add Write comments in Chinese.    # Add to the default scope (usually session)
/baize-rules global add Don't delete or rewrite existing tests.  # Explicitly add to global
/baize-rules list                              # Show project + session + global (abbreviated id / disabled markers)
/baize-rules list project                      # List one scope only
/baize-rules edit <id> Use pnpm to build only. # Edit a rule's text
/baize-rules disable <id>                      # Disable one (keep it, don't delete)
/baize-rules enable <id>                       # Re-enable
/baize-rules scope global                      # Subsequent commands default to global
/baize-rules clear session                     # Clear the current session's rules
/baize-rules global clear                      # Same thing: `clear <scope>` and `<scope> clear` are equivalent
/baize-rules export                            # Export all rules as JSON
# --- tags ---
/baize-rules tag <id> flow release              # Tag a rule (idempotent, deduped)
/baize-rules untag <id> release                 # Drop one tag
# --- templates ---
/baize-rules save <id>                          # Store this rule as a template ("Save as template" in the panel)
/baize-rules tmpl list                          # List the template library (optionally by tag)
/baize-rules from <id|#tag>                     # Add rules from templates (#tag = all with that tag)
/baize-rules tmpl export ./templates.json       # Export the library to a JSON file
/baize-rules tmpl import ./templates.json --yes # Import (dry run by default; --yes writes)

Scope goes before the verb. Write /baize-rules global add <text>. A scope word at the end is no longer a modifier — in /baize-rules add Deploy after tests global the word global is part of the rule text. See Scope syntax.

---

Commands

All subcommands live under /baize-rules; no argument is equivalent to list.

/baize-rules [<scope>] <command>                     # scope is global|session|project, written BEFORE the verb
/baize-rules [list [scope]|add <text>|remove <id>|edit <id> <text>|enable|disable <id>|tag|untag <id> <tag…>|save <id> [#tag…]|from <id|#tag>|tmpl <list|add|edit|rm|export|import>|scope <scope>|clear <scope>|export]

tmpl subcommands

Argument details

• <text>: the rule body, may contain spaces. Whether it's "must-do" or "must-not" is expressed by the body's language; there is no marker.
• <id>: a stable rule id (crypto.randomUUID). list shows the first 8 characters as an abbreviated id for readability; remove/edit/enable/disable/tag/untag/save all accept the full id or a unique prefix. An ambiguous prefix reports ambiguous and lists the candidates — it never guesses. Same for tmpl rm/tmpl edit.
• <tag…>: free-text tags, space separated, # prefix optional (#flow ≡ flow). At most 8 tags per item, 24 characters each; dedupe and filtering are case-insensitive, while the stored spelling is what you first typed.
• from duplicate guard: a rule whose text already exists in the target scope is skipped (Skipped N duplicate(s)), so re-adding from a template never piles up duplicates. A template that is actually applied gets its use count +1.

Scope syntax

A scope modifier is written before the verb — this is the only form:

• /baize-rules global add Write in Chinese.
• /baize-rules project add Run the tests before every commit.
• /baize-rules session remove <id>

BREAKING (0.2.1): the trailing scope form was removed. A scope word at the end of the line is no longer a modifier — it is part of the argument. /baize-rules add Deploy after tests global now stores the body Deploy after tests global in the default scope. Before 0.2.1 the same line dropped the word global from the body and wrote the rule into global, silently truncating rule text and mis-targeting the write, so the trailing form was removed outright rather than kept as an alias.

The verbs this applies to are add/remove/edit/enable/disable/from. A scope word anywhere other than the first token is plain text: /baize-rules add Run global checks before release. stores that whole sentence as the body. from lost its positional scope argument with the trailing form: write /baize-rules project from <id> (or set the default with /baize-rules scope project) instead of /baize-rules from <id> project.

Trailing tag metadata is unchanged. tag/untag/save/tmpl still take a trailing run of #tag tokens as metadata, not rule text. They take the scope in the prefix form only (/baize-rules global tag <id> frontend), so a tag literally named project/global/session can never be swallowed as a scope.

Where the scope is an argument, not a modifier, both orders work — /baize-rules clear global ≡ /baize-rules global clear, /baize-rules scope project ≡ /baize-rules project scope, and /baize-rules list project ≡ /baize-rules project list.

When no scope is given, the default set by /baize-rules scope is used (initially from Config.scope, usually session).

---

Injection behavior (how the model context changes)

• Conversation-start baseline: at the start of a session, agent/pre-step (prepend:true) inserts the active rules as a user/message into the request, framed as <system-reminder> with source.kind='plugin', plugin='baize-rules', form='snapshot'.
• All three scopes are injected: project > session > global, specific first. project rules are read from the session's working directory, so they join the view (and the model context) whenever the session declares a cwd; they are rendered under the header Project requirements (this directory only):.
• Specificity wins: when the budget is tight the broader global rules are trimmed first.
• Deduplication: a SHA-1 digest is computed over the rendered text; unchanged rules aren't re-injected. injectAtEveryStep:true forces a refresh on each step.
• A fresh copy after a session lifecycle change: agent/session-start (startup / resume / clear / compact) drops that session's record, so the next step publishes the full rules again — a compacted or cleared session cannot be left without them, which is the one case where "inject once at the start" could lose them for good.
• A fresh copy every refreshAfterSteps steps: once the last published copy is that many steps old it is republished even when the text is byte-identical (default 20, 0 disables the periodic refresh). A step counter that restarts after compaction counts as stale as well. Because the message is a snapshot, the model still sees a single copy — this only moves it back to where the conversation is now.
• Escape: a literal </system-reminder> in a body is escaped via escapeReminder.
• Tags stay out of the model: tags are not injected by default (injectTags:false), so tagging or retagging a rule neither changes the text the model sees nor triggers a redundant re-injection.
• Empty / fully trimmed: when there are no rules, or the budget cuts all of them, it returns undefined (i.e. does not inject that message).
• A corrupt file never blocks the step: every read degrades instead of throwing — a broken file makes that scope read as empty and adds a problems entry. The step always completes; the warning is what tells you a file needs fixing.

What the model actually sees

<system-reminder>
The following user requirements apply to every step of this conversation. Obey them.
More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.

Project requirements (this directory only):
- Run the tests before every commit.

Session requirements (this conversation only):
- Always test the plugin in isolation before deploying.

Global requirements:
- Write comments in Chinese.
- Do not delete or rewrite existing tests.
</system-reminder>

(The Project requirements (this directory only): section appears only when the session has a working directory and that directory has active rules.)

---

Configuration (Config)

On startup the plugin validates Config with @deepseek-ai/schemastery; an invalid value makes the plugin fail to load.

scope and maxBytes are required by the schema, not optional with an implicit fallback. Omitting either fails the plugin load with an explicit error naming the missing field — silently defaulting an undefined scope used to hide a broken configuration.

apiOriginCheck (default false). When switched on, the panel API answers only requests that come from this machine and, when the browser states an Origin, from the host's own origin (or a local file:// page, which sends a null origin); anything else is refused with 403. It is off by default because the web UI is routinely reached through a reverse proxy, where the request arrives from the proxy's address instead of loopback and the panel would break. Turn it on when the port is reachable by others and no proxy layer authenticates the callers — the check exists because the global rule file reaches every conversation's prompt, so "anything that can reach the port" must not be enough. With the check off, authentication belongs to the transport (dsh's own token) and the proxy.

Mount metadata (cordis.patch.yml)

The published npm package ships dsh.bundle.patch, wired up automatically by dsh when you install dsh-baize-rules@<version>: cordis.patch.yml inserts a single plugin line with default scope: session and maxBytes: 8192. To adjust the default scope / budget, change it there.

To mount by hand instead of relying on the bundle patch, insert the same row yourself — note the whole mounted-rows list is inserted into the tree, and config mirrors the Config schema:

# $DSH_HOME/profiles/<profile>/cordis.patch.yml   (e.g. ~/.dsh/profiles/web/cordis.patch.yml)
- insert:
    - id: baize-rules
      name: 'dsh-baize-rules'
      config:
        scope: session
        maxBytes: 8192

After editing the profile's cordis.patch.yml, restart dsh (pm2 restart dsh when it is pm2-managed); the profile file is read at boot.

---

Data location

$DSH_HOME is resolved by @deepseek-ai/dsh-home-paths, default ~/.dsh.

Reads never throw. They go through ctx.fs (resolve/stat/readText; writes auto-create directories). A missing file is simply an empty scope, and a corrupt or hand-edited file degrades to an empty scope plus a problems entry — the failure is reported (command output gains a ⚠ … line, the panel shows a warning), never fatal to the step. Writes replace a whole file (there is no partial edit on disk), so a write is either the new complete file or nothing at all.

Concurrent writes are guarded. Every write carries the freshness token of the file it read. If the file changed in between (another panel window, another command), the write is refused — the command reports a conflict and asks you to retry, the HTTP API answers 409 — instead of silently overwriting the other edit.

No empty files. Only the scopes that actually changed are rewritten, and an untouched empty scope is not written at all. (Older versions left a 3-byte [] file per session under $DSH_HOME/rules/sessions/; those leftovers are harmless and can be deleted by hand — new ones are no longer created.)

project rules are part of the model context. When the session declares a working directory, its project rules are read and injected under Project requirements (this directory only):, most specific first (project > session > global). The project file name is a slug of the session's cwd: the characters \ / : * ? " < > | become _, leading and trailing _ are trimmed, and a cwd made entirely of those characters falls back to the literal _. With no session or no cwd there is no project key, so nothing is written to disk (the HTTP API refuses such a write with 400).

---

Client panel (optional)