dsh-baize-rules 0.1.0

package/lib/types/rules.d.ts

@@ -0,0 +1,45 @@
+/**
+ * User-set rule data model, scope reconciliation, and the model-visible
+ * rendering shared by the pre-step injection and the /rules command.
+ *
+ * @module @deepseek-ai/dsh-rules/rules
+ */
+export type RuleScope = 'global' | 'session' | 'project';
+/** One user requirement. Rules are plain text — the must-do / must-not intent is
+ *  expressed in the text itself (e.g. "用中文写注释" vs "不要改测试"), so there is
+ *  no separate kind tag. */
+export interface Rule {
+    /** Stable id minted once; the /rules command addresses rules by it. */
+    readonly id: string;
+    readonly text: string;
+    /** A rule may be temporarily paused without being deleted. */
+    readonly enabled: boolean;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+/** Ordered, deduplicated rule sets per scope for a single session view. */
+export interface RuleView {
+    readonly global: readonly Rule[];
+    readonly session: readonly Rule[];
+    readonly project?: readonly Rule[];
+}
+/** Concatenate global then session rules, honoring scope precedence. */
+export declare function activeRules(view: RuleView): readonly Rule[];
+/** Escape literal closing tags so user text cannot close the plugin frame. */
+export declare function escapeReminder(text: string): string;
+/** Enforce the configured byte budget by keeping the *prefix* (up to `budgetBytes`
+ *  UTF-8 bytes) and dropping the tail. Precedence is thus decided by callers:
+ *  {@link renderRules} lays the most specific section first, so a tight budget
+ *  sheds the broadest (global) rules before any specific (session/project) rule. */
+export declare function enforceBudget(lines: readonly string[], budgetBytes: number): {
+    lines: readonly string[];
+    omitted: number;
+};
+/** Render the full model-visible <system-reminder> text, or undefined when empty.
+ *  Sections are laid out specific-first (project > session > global) so prefix
+ *  retention under {@link enforceBudget} keeps the specific rules and sheds the
+ *  broadest (global) rules first. Returns undefined when no rule bullet survives
+ *  the budget, so we never inject a boilerplate-only reminder. */
+export declare function renderRules(view: RuleView, budgetBytes: number): string | undefined;
+/** SHA-1 digest of the rendered text, used to suppress redundant injection. */
+export declare function renderDigest(view: RuleView, budgetBytes: number): Promise<string | undefined>;

package/lib/types/store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Durable rule store: `global` and `session` rules both persist to JSON files
+ * under DSH_HOME — `global` to `$DSH_HOME/rules/global.json`, and each session's
+ * rules to `$DSH_HOME/rules/sessions/<sessionId>.json`. Files are read lazily at
+ * every view/pre-step and written on every mutating `/rules` command, so both
+ * scopes survive process restarts. `ctx.fs.writeText` creates parent dirs.
+ *
+ * Note: an event-sourced `rules/set` session event (方案 A) would be the cleanest
+ * "model-visible ⟺ logged" guarantee, but the public `Session.append` cannot mark
+ * an out-of-repo event type `ignorable`, so a harness reading such a log would
+ * refuse to reconstruct it. The per-session file is the pragmatic durable path.
+ *
+ * Pure CRUD helpers (addRule/removeRule/mutate/newRule) live in `core.ts`.
+ *
+ * @module dsh-baize-rules/store
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Rule, RuleView } from './rules.ts';
+/** Read a project's rule set from its durable file (empty when missing). */
+export declare function readProject(ctx: Context, projectId: unknown): Promise<Rule[]>;
+/** Replace a project's rule set in its durable file. */
+export declare function writeProject(ctx: Context, projectId: unknown, rules: readonly Rule[]): Promise<void>;
+/** Read the global rule set, tolerating a missing file and failing loud on a malformed store. */
+export declare function readGlobal(ctx: Context, config: {
+    globalRulesPath?: string;
+}): Promise<Rule[]>;
+/** Write the global rule set. */
+export declare function writeGlobal(ctx: Context, config: {
+    globalRulesPath?: string;
+}, rules: readonly Rule[]): Promise<void>;
+/** Read the per-session rule set from its durable file (empty when missing). */
+export declare function readSession(ctx: Context, sessionId: unknown): Promise<Rule[]>;
+/** Replace the per-session rule set in its durable file. */
+export declare function writeSession(ctx: Context, sessionId: unknown, rules: readonly Rule[]): Promise<void>;
+/** Assemble the merged view used for injection and /rules list. */
+export declare function view(ctx: Context, agent: Agent, config: {
+    globalRulesPath?: string;
+}): Promise<RuleView>;

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "dsh-baize-rules",
+  "description": "User-set session/global must-do and must-not requirements injected at conversation start (Baize).",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev:render": "tsx scripts/dev-render.ts",
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "slots",
+        "locale",
+        "layout",
+        "connection"
+      ],
+      "platform": "web"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-commands": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-fs": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-agent": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-commands": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-fs": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "3.18.1",
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  }
+}

package/src/api.ts

@@ -0,0 +1,106 @@
+/**
+ * Host HTTP API for the rules panel. The client (`lib/client.js`) fetches rules
+ * via GET and applies mutations via POST, reusing the same store + core as the
+ * `/baize-rules` command (so the panel and command are the same source of truth).
+ *
+ * Routes (json):
+ *   GET  /baize-rules.api?sessionId=...  -> { global, session }
+ *   POST /baize-rules.api { sessionId, raw, scope } -> { ok, text, view }
+ *
+ * @module dsh-baize-rules/api
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver' // augments Context with `webServer`
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { RuleScope } from './rules.ts'
+import { runCommand } from './core.ts'
+import { view, writeGlobal, writeSession, writeProject, readProject } from './store.ts'
+
+type RulesApiOptions = { globalRulesPath?: string }
+
+function sendJson(res: unknown, status: number, payload: unknown): void {
+  const r = res as { writeHead(s: number, h: Record<string, string>): void; end(body: string): void }
+  r.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' })
+  r.end(JSON.stringify(payload))
+}
+
+function readBody(req: unknown): Promise<string> {
+  return new Promise((resolve) => {
+    const r = req as { on(e: string, cb: (c: string) => void): void }
+    let body = ''
+    r.on('data', (chunk) => { body += chunk })
+    r.on('end', () => resolve(body))
+    r.on('error', () => resolve(''))
+  })
+}
+
+function parseBody(text: string): Record<string, unknown> {
+  try { return JSON.parse(text || '{}') } catch { return {} }
+}
+
+/** Register the rules panel API on the host web server. */
+export function registerRulesApi(ctx: Context, options: RulesApiOptions = {}): () => void {
+  if (ctx.webServer === undefined) return () => {}
+  return ctx.webServer.register({
+    kind: 'exact',
+    path: '/baize-rules.api',
+    handler: async (req: IncomingMessage, res: ServerResponse) => {
+      const method = req.method ?? ''
+      const url = req.url ?? ''
+      const query = new URLSearchParams(url.split('?')[1] ?? '')
+      const sessionId = query.get('sessionId') ?? ''
+      const project = await resolveProject(ctx, sessionId, query.get('project') ?? '')
+
+      if (method === 'GET') {
+        try {
+          sendJson(res, 200, await viewFor(ctx, sessionId, project, options))
+        } catch (e) {
+          sendJson(res, 500, { error: String(e) })
+        }
+        return
+      }
+
+      if (method === 'POST') {
+        const body = parseBody(await readBody(req))
+        const pSessionId = String(body.sessionId ?? '')
+        const pProject = await resolveProject(ctx, pSessionId, String(body.project ?? ''))
+        const raw = String(body.raw ?? '')
+        const defaultScope = (body.scope ?? 'session') as RuleScope
+        if (!raw.trim()) { sendJson(res, 400, { error: 'empty raw' }); return }
+        try {
+          const v = await viewFor(ctx, pSessionId, pProject, options)
+          const out = runCommand({ raw, view: v, defaultScope })
+          if (out.nextView !== undefined) {
+            await writeGlobal(ctx, options, out.nextView.global)
+            if (pSessionId) await writeSession(ctx, pSessionId, out.nextView.session)
+            if (pProject) await writeProject(ctx, pProject, out.nextView.project ?? [])
+          }
+          sendJson(res, out.ok ? 200 : 400, { ok: out.ok, text: out.text, view: out.nextView ?? v })
+        } catch (e) {
+          sendJson(res, 500, { error: String(e) })
+        }
+        return
+      }
+
+      sendJson(res, 405, { error: 'method not allowed' })
+    },
+  })
+}
+
+/** Resolve the project key (cwd) from an explicit `project`, else the session's header cwd. */
+async function resolveProject(ctx: Context, sessionId: string, project: string): Promise<string> {
+  if (project) return project
+  if (!sessionId) return ''
+  try {
+    const sess = (ctx as Context & { sessions?: { get?(id: string): { header?: { cwd?: string } } | undefined } }).sessions?.get?.(sessionId)
+    return (sess && sess.header?.cwd) || ''
+  } catch { return '' }
+}
+
+/** Load global (disk) + session (per-session file) + project (per-cwd file) rules. */
+async function viewFor(ctx: Context, sessionId: string, project: string, options: RulesApiOptions) {
+  const v = await view(ctx, { id: sessionId } as never, options)
+  const proj = project ? await readProject(ctx, project) : []
+  return { ...v, project: proj }
+}

package/src/command.ts

@@ -0,0 +1,46 @@
+/**
+ * Thin dsh adapter for the `/rules` command: feeds the live `view` + current
+ * `defaultScope` into the dependency-free decision core (`core.ts`), then
+ * persists the resulting `nextView` (global → disk, session → memory) and any
+ * `/rules scope` default change.
+ *
+ * @module dsh-baize-rules/command
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands'
+import type { RuleScope } from './rules.ts'
+import { runCommand } from './core.ts'
+import { view, writeGlobal, writeSession, readProject, writeProject } from './store.ts'
+
+/** Runtime state the command handler needs from the plugin's `apply`. */
+export interface RulesRuntime {
+  readonly globalRulesPath?: string
+  readonly getScope: () => RuleScope
+  readonly setScope: (scope: RuleScope) => void
+}
+
+/** The registered handler contract: adapt command input → core decision → persist. */
+export async function handle(
+  ctx: Context,
+  invocation: CommandInvocation,
+  runtime: RulesRuntime,
+): Promise<CommandResult> {
+  const cwd = (invocation.agent.session?.header as { cwd?: string } | undefined)?.cwd ?? ''
+  const v = await view(ctx, invocation.agent, { globalRulesPath: runtime.globalRulesPath })
+  const viewWithProject = cwd ? { ...v, project: await readProject(ctx, cwd) } : v
+  const out = runCommand({
+    raw: invocation.rawInput,
+    view: viewWithProject,
+    defaultScope: runtime.getScope(),
+  })
+
+  if (out.nextView !== undefined) {
+    await writeGlobal(ctx, { globalRulesPath: runtime.globalRulesPath }, out.nextView.global)
+    await writeSession(ctx, invocation.agent.id, out.nextView.session)
+    if (cwd) await writeProject(ctx, cwd, out.nextView.project ?? [])
+  }
+  if (out.defaultScope !== undefined) runtime.setScope(out.defaultScope)
+
+  return out.ok ? { kind: 'success', text: out.text } : { kind: 'error', text: out.text }
+}

package/src/core.ts

@@ -0,0 +1,197 @@
+/**
+ * Dependency-free rules-command core: parsing, scope resolution, and CRUD
+ * application over a {@link RuleView}. No dsh runtime needed, so it is testable
+ * in the Loop 0 harness (`pnpm test`). The dsh-facing adapter (`command.ts`)
+ * feeds in the live `view` + `defaultScope` and persists `nextView`/`defaultScope`.
+ *
+ * @module dsh-baize-rules/core
+ */
+
+import type { Rule, RuleScope, RuleView } from './rules.ts'
+
+export const RULE_SCOPES: readonly RuleScope[] = ['global', 'session', 'project']
+const SCOPE_SET = new Set<RuleScope>(RULE_SCOPES)
+/** Verbs where a trailing scope token is a *target* to modify, not an argument. */
+const SCOPE_MODIFIER_VERBS = new Set<CommandVerb>(['add', 'remove', 'enable', 'disable'])
+
+export type CommandVerb =
+  | 'list' | 'add' | 'remove' | 'enable' | 'disable' | 'edit' | 'scope' | 'clear' | 'export'
+
+export interface ParsedCommand {
+  readonly verb: CommandVerb | 'help' | undefined
+  readonly args: readonly string[]
+  /** Explicit scope keyword (leading or trailing), if present. */
+  readonly scope?: RuleScope
+}
+
+export interface CommandInput {
+  readonly raw: string
+  readonly view: RuleView
+  readonly defaultScope: RuleScope
+}
+
+export interface CommandOutput {
+  readonly ok: boolean
+  readonly text: string
+  /** Present when the store should be persisted to this new view. */
+  readonly nextView?: RuleView
+  /** Present when `/rules scope` chose a new default scope. */
+  readonly defaultScope?: RuleScope
+}
+
+const USAGE =
+  'Usage: /rules [list|add <text>|remove <id>|edit <id> <text>|enable|disable <id>|scope <global|session|project>|clear <scope>|export]'
+
+/** Parse a `/rules` line into a verb + args, isolating an explicit scope keyword.
+ *  Scope is accepted as a **leading** token (`/rules global add …`) or a
+ *  **trailing** token (`/rules add … global`, only the LAST arg qualifies),
+ *  so a rule whose text merely contains "global" is never misread as a scope. */
+export function parseCommand(raw: string): ParsedCommand {
+  const tokens = raw.trim().split(/\s+/).filter(Boolean)
+  if (tokens.length === 0) return { verb: undefined, args: [] }
+
+  let verb: CommandVerb | 'help' | undefined
+  let scope: RuleScope | undefined
+  let rest: string[]
+
+  if (SCOPE_SET.has(tokens[0] as RuleScope)) {
+    scope = tokens[0] as RuleScope
+    verb = tokens[1] as CommandVerb | undefined
+    rest = tokens.slice(2)
+  } else {
+    verb = tokens[0] as CommandVerb | undefined
+    rest = tokens.slice(1)
+    // Strip a trailing scope only for verbs that take a *target* scope modifier,
+    // never for `scope`/`clear` where the scope is the argument itself.
+    if (verb !== undefined && SCOPE_MODIFIER_VERBS.has(verb) && rest.length > 0
+      && SCOPE_SET.has(rest[rest.length - 1] as RuleScope)) {
+      scope = rest[rest.length - 1] as RuleScope
+      rest = rest.slice(0, -1)
+    }
+  }
+  return { verb, args: rest.filter(Boolean), scope }
+}
+
+/** Explicit scope wins, else the caller's default. */
+export function resolveScope(scope: RuleScope | undefined, fallback: RuleScope): RuleScope {
+  return scope ?? fallback
+}
+
+/** Mint a fully-specified rule (dependency-free; uses global `crypto.randomUUID`). */
+export function newRule(text: string, now = Date.now()): Rule {
+  return {
+    id: crypto.randomUUID(),
+    text,
+    enabled: true,
+    createdAt: now,
+    updatedAt: now,
+  }
+}
+
+/** Return a new view with one rule appended to a scope. */
+function listOf(view: RuleView, scope: RuleScope): readonly Rule[] {
+  return scope === 'global' ? view.global : scope === 'project' ? (view.project ?? []) : view.session
+}
+function withList(view: RuleView, scope: RuleScope, list: readonly Rule[]): RuleView {
+  if (scope === 'global') return { ...view, global: [...list] }
+  if (scope === 'project') return { ...view, project: [...list] }
+  return { ...view, session: [...list] }
+}
+
+export function addRule(view: RuleView, scope: RuleScope, rule: Rule): RuleView {
+  return withList(view, scope, [...listOf(view, scope), rule])
+}
+
+/** Return a new view with a rule removed from one scope. */
+export function removeRule(view: RuleView, scope: RuleScope, id: string): RuleView {
+  return withList(view, scope, listOf(view, scope).filter(rule => rule.id !== id))
+}
+
+/** Mutate a copy of a scope's rules for the given id; returns whether found. */
+export function mutate(view: RuleView, scope: RuleScope, id: string, fn: (rule: Rule) => Rule): RuleView {
+  return withList(view, scope, listOf(view, scope).map(rule => rule.id === id ? fn(rule) : rule))
+}
+
+/** Render a compact human-readable list of the active rules. */
+export function formatList(view: RuleView): string {
+  const line = (rule: Rule) =>
+    `[${rule.id.slice(0, 8)}] ${rule.enabled ? '' : '(disabled) '}${rule.text}`
+  const parts: string[] = []
+  if (view.project && view.project.length > 0) { parts.push('Project:'); parts.push(...view.project.map(line)) }
+  if (view.global.length > 0) { parts.push('Global:'); parts.push(...view.global.map(line)) }
+  if (view.session.length > 0) { parts.push('Session:'); parts.push(...view.session.map(line)) }
+  return parts.length === 0 ? 'No active rules.' : parts.join('\n')
+}
+
+/** Apply one parsed `/rules` command to the given view + default scope. */
+export function runCommand(input: CommandInput): CommandOutput {
+  const { verb, args, scope } = parseCommand(input.raw)
+  if (verb === undefined || verb === 'list') {
+    return { ok: true, text: formatList(input.view) }
+  }
+
+  const chosen = resolveScope(scope, input.defaultScope)
+
+  switch (verb) {
+    case 'add': {
+      const text = args.join(' ')
+      if (text.length === 0) {
+        return { ok: false, text: USAGE }
+      }
+      return {
+        ok: true,
+        text: `Added rule to ${chosen}: ${text}`,
+        nextView: addRule(input.view, chosen, newRule(text)),
+      }
+    }
+
+    case 'remove': {
+      const id = args[0] ?? ''
+      if (id.length === 0) return { ok: false, text: USAGE }
+      return {
+        ok: true,
+        text: `Removed rule ${id} from ${chosen}.`,
+        nextView: removeRule(input.view, chosen, id),
+      }
+    }
+
+    case 'enable':
+    case 'disable': {
+      const id = args[0] ?? ''
+      if (id.length === 0) return { ok: false, text: USAGE }
+      const enable = verb === 'enable'
+      const next = mutate(input.view, chosen, id, rule => ({ ...rule, enabled: enable, updatedAt: Date.now() }))
+      return { ok: true, text: `${enable ? 'Enabled' : 'Disabled'} rule ${id}.`, nextView: next }
+    }
+
+    case 'edit': {
+      const id = args[0] ?? ''
+      const text = args.slice(1).join(' ')
+      if (id.length === 0 || text.length === 0) return { ok: false, text: USAGE }
+      const list = listOf(input.view, chosen)
+      if (!list.some(rule => rule.id === id)) return { ok: false, text: `Rule ${id} not found.` }
+      const next = mutate(input.view, chosen, id, rule => ({ ...rule, text, updatedAt: Date.now() }))
+      return { ok: true, text: `Updated rule ${id}.`, nextView: next }
+    }
+
+    case 'scope': {
+      const nextScope = args[0] as RuleScope | undefined
+      if (nextScope === undefined || !SCOPE_SET.has(nextScope)) return { ok: false, text: USAGE }
+      return { ok: true, text: `Default scope is now ${nextScope}.`, defaultScope: nextScope }
+    }
+
+    case 'clear': {
+      const clearScope = args[0] as RuleScope | undefined
+      if (clearScope === undefined || !SCOPE_SET.has(clearScope)) return { ok: false, text: USAGE }
+      const next = clearScope === 'global' ? { ...input.view, global: [] } : { ...input.view, session: [] }
+      return { ok: true, text: `Cleared ${clearScope} rules.`, nextView: next }
+    }
+
+    case 'export': {
+      return { ok: true, text: JSON.stringify({ global: input.view.global, session: input.view.session }, null, 2) }
+    }
+
+    default:
+      return { ok: false, text: USAGE }
+  }
+}

package/src/index.ts

@@ -0,0 +1,105 @@
+/**
+ * User-set session/global must-do and must-not requirements injected at
+ * conversation start. Named for 白泽 (Baize), the beast that knows all and
+ * distinguishes right from wrong — hence the must/mustNot framing.
+ *
+ * @module dsh-baize-rules
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import type { RuleScope } from './rules.ts'
+import { renderDigest, renderRules } from './rules.ts'
+import { view } from './store.ts'
+import { handle, type RulesRuntime } from './command.ts'
+import { registerRulesApi } from './api.ts'
+
+/** Cordis plugin name used by loader diagnostics + the injected message source. */
+export const name = 'baize-rules'
+
+/** Services granted on `ctx` by cordis before `apply` runs. We use `ctx.agents`
+ *  (agent-plane scoping), `ctx.commands` (register /baize-rules), `ctx.fs`
+ *  (persist global + session rule files), and `ctx.webServer` (rules panel API);
+ *  each must be declared in `inject`. */
+export const inject = ['agents', 'commands', 'fs', 'webServer', 'sessions']
+
+/** Policy for the rules plugin. Invalid values fail plugin load. */
+export interface Config {
+  /** Default scope that `/rules add|remove|...` edits when the line omits a scope keyword. */
+  scope: 'global' | 'session'
+  /** Model-visible byte budget; a tight budget sheds the broadest rules first. */
+  maxBytes: number
+  /** Override the global rules file path (default `$DSH_HOME/rules/global.json`). */
+  globalRulesPath?: string
+  /** When true, re-render an updated rules message on every step, not just on change. */
+  injectAtEveryStep?: boolean
+}
+
+/** Schemastery validation for {@link Config}. */
+export const Config: z<Config> = z.object({
+  scope: z.union([z.const('global'), z.const('session')]),
+  maxBytes: z.number().required(),
+  globalRulesPath: z.string(),
+  injectAtEveryStep: z.boolean(),
+})
+
+/** Per-session digest of the last injected rules, used to suppress duplicate injection. */
+const lastInjected = /* @__PURE__ */ new WeakMap<Agent['session'], string>()
+
+/**
+ * Register a prepended pre-step listener that injects the rendered rules as a
+ * durable user message on conversation start, plus the `/rules` command.
+ * @param ctx - plugin context; listener and command dispose with it.
+ * @param config - scope, budget, and redundancy policy.
+ */
+export function apply(ctx: Context, config: Config): void {
+  // `/rules scope` mutates this process-visible default, so the command and the
+  // pre-step view always read the current choice.
+  const mutableScope: { scope: RuleScope } = { scope: config.scope }
+
+  ctx.on('agent/pre-step', async (
+    { agent, signal },
+    next,
+  ): Promise<PreStepDecision> => {
+    const decision = await next()
+    if (decision.kind === 'reject' || signal.aborted) return decision
+    const v = await view(ctx, agent, config)
+    const text = renderRules(v, config.maxBytes)
+    if (text === undefined) return decision
+    const digest = await renderDigest(v, config.maxBytes)
+    const previous = lastInjected.get(agent.session)
+    if (!config.injectAtEveryStep && previous !== undefined && previous === digest) return decision
+    lastInjected.set(agent.session, digest ?? '')
+    return {
+      kind: 'enter',
+      messages: [
+        ...decision.messages,
+        createUserMessage({
+          content: [{ type: 'text', text }],
+          source: { kind: 'plugin', plugin: name, form: 'snapshot', sections: [{ name, text }] },
+        }),
+      ],
+    }
+  }, { prepend: true })
+
+  ctx.effect(function* () {
+    const runtime: RulesRuntime = {
+      globalRulesPath: config.globalRulesPath,
+      getScope: () => mutableScope.scope,
+      setScope: (scope) => { mutableScope.scope = scope },
+    }
+    yield ctx.commands.register({
+      name: 'baize-rules',
+      description: '查看/增删改 会话或全局的 必须/禁止 要求',
+      input: {
+        hint: 'list | add <text> | remove <id> | enable|disable <id> | scope <global|session|project> | clear <scope> | export',
+      },
+      handler: invocation => handle(ctx, invocation, runtime),
+    })
+  }, 'baize-rules lifecycle')
+
+  // Host HTTP API for the rules panel (client reads/writes here).
+  ctx.effect(() => registerRulesApi(ctx, { globalRulesPath: config.globalRulesPath }), 'baize-rules api')
+}

package/src/invariant.ts

@@ -0,0 +1,37 @@
+/**
+ * Package-owned invariant companion for `dsh-baize-rules`.
+ *
+ * Follows the @deepseek-ai/dsh-invariants contract used by other dsh context
+ * plugins (e.g. `@deepseek-ai/dsh-agent-instructions`): a Cordis companion that
+ * exports `name` / `inject=['invariants']` / `apply`, and registers itself via
+ * `ctx.invariants.register(PACKAGE_NAME, install)`.
+ *
+ * @module dsh-baize-rules/invariant
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = 'dsh-baize-rules'
+
+/** Cordis companion plugin name. */
+export const name = 'baize-rules-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * M1 hook: install a real check that any rules-tagged `user/message` in the
+ * session log carries the rules plugin's own source marker and reconstructs from
+ * the current rule set. For now it is an explainable no-op so it never blocks a
+ * session; the reference implementation's naive `registerInvariant` (a nonexistent
+ * export from a wrong package name) is replaced by this contract-correct shape.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))