dsh-claude-compat 0.2.0 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-0.1.0-blue?style=flat-square" alt="Version">
+  <img src="https://img.shields.io/badge/version-0.3.0-blue?style=flat-square" alt="Version">
   <img src="https://img.shields.io/badge/node-%3E%3D20-green?style=flat-square&logo=node.js&logoColor=white" alt="Node">
   <img src="https://img.shields.io/badge/license-MIT-orange?style=flat-square" alt="License">
 </p>
@@ -24,15 +24,24 @@
 | `commands/*.md` | DSH skill provider | Same, plus user-invocable: `/command-name` works in the slash menu. |
 | `rules/*.md` | Message-stream injection | Rules are concatenated, wrapped in a `<system-reminder>` envelope, and prepended as a user-role message at the front of the message array once per session — the same channel Claude Code uses (`prependUserContext`), which models follow reliably. |
 
+The same three directories are also read from the **user-level** `~/.claude/` (skills, commands, rules). Same-name skills/commands/rules are deduped with a fixed priority:
+
+**project `.claude` > DSH native > `~/.claude`**
+
+- Project entries carry rank `50`, `~/.claude` entries rank `700`, and DSH's own bundled skills sit at rank `600` (`BUNDLED_SKILL_RANK`) — so a project skill always overrides the DSH-bundled and user copies, and a user skill never overrides a DSH-native one.
+- Rule files with the same basename in `~/.claude/rules` are skipped when the project already provides one.
+
 `CLAUDE.md` / `AGENTS.md` are **not** touched — DSH's built-in `dsh-agent-instructions` already handles those.
 
 ## Requirements
 
 - DSH with a profile (e.g. `web`)
-- A project using Claude Code conventions: `.claude/skills/`, `.claude/commands/`, `.claude/rules/`
+- A project using Claude Code conventions: `.claude/skills/`, `.claude/commands/`, `.claude/rules/` (all optional; `~/.claude/` equivalents are also picked up)
 
 ## Install
 
+One command — the package declares `dsh.bundle`, so DSH activates it automatically (no manual `cordis.patch.yml` editing):
+
 ```bash
 dsh plugin --profile web add dsh-claude-compat
 ```
@@ -43,29 +52,22 @@ Or from GitHub:
 dsh plugin --profile web add github:biedongbin/dsh-claude-compat
 ```
 
-Then register it in `~/.dsh/profiles/web/cordis.patch.yml` (merge into your existing patch list):
-
-```yaml
-- insert:
-    - id: claude-compat
-      name: 'dsh-claude-compat'
-      config:
-        enableSkills: true
-        enableRules: true
-```
-
 Restart DSH (`dsh web`). Done — skills show up in `/`, rules are injected into every new session.
 
 ## Configuration
 
 | Option | Default | Description |
 |---|---|---|
-| `enableSkills` | `true` | Register the `.claude/skills` + `.claude/commands` provider |
-| `enableRules` | `true` | Inject `.claude/rules/*.md` into the message stream |
-| `rulesMaxBytes` | `65536` | Hard cap on total injected rules text |
+| `enableSkills` | `true` | Register the `.claude/skills` + `.claude/commands` provider (project and `~/.claude`) |
+| `enableRules` | `true` | Inject project + `~/.claude` `rules/*.md` into the message stream |
+| `rulesMaxBytes` | `65536` | Hard cap on total injected project rules text |
+| `userRulesMaxBytes` | `65536` | Hard cap on total injected `~/.claude/rules` text |
 | `projectRootMarkers` | `[".git"]` | Ancestor markers for project-root discovery |
-| `skillRank` | `150` | Provider rank: between DSH-native `.dsh/skills` (100) and `.agents/skills` (200) — DSH-native wins conflicts |
-| `skillSource` | `project-claude` | Source tag for catalog entries |
+| `skillRank` | `50` | Provider rank for project `.claude` skills (wins every DSH-native collision) |
+| `skillSource` | `project-claude` | Source tag for project catalog entries |
+| `userSkillRank` | `700` | Provider rank for `~/.claude` skills (loses to DSH-native `600`) |
+| `userSkillSource` | `user-claude` | Source tag for `~/.claude` catalog entries |
+| `userClaudeDir` | `~/.claude` | User-level `.claude` directory (`~` expands to the home dir) |
 
 ## Notes
 

package/README.zh-CN.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-0.1.0-blue?style=flat-square" alt="Version">
+  <img src="https://img.shields.io/badge/version-0.3.0-blue?style=flat-square" alt="Version">
   <img src="https://img.shields.io/badge/node-%3E%3D20-green?style=flat-square&logo=node.js&logoColor=white" alt="Node">
   <img src="https://img.shields.io/badge/license-MIT-orange?style=flat-square" alt="License">
 </p>
@@ -24,15 +24,24 @@
 | `commands/*.md` | DSH skill provider | 同上，且用户可直接调用：斜杠菜单里 `/command-name` 可用。 |
 | `rules/*.md` | 消息流注入 | rules 全文拼接，包 `<system-reminder>` 信封，每会话一次以 user-role 消息插在消息数组最前 —— 与 Claude Code 同通道（`prependUserContext`），模型可靠遵循。 |
 
+同类三个目录同样读取**用户级** `~/.claude/`（skills、commands、rules）。同名 skill/command/rule 去重，优先级固定：
+
+**项目 `.claude` > DSH 原生 > `~/.claude`**
+
+- 项目条目 rank=`50`，`~/.claude` 条目 rank=`700`，DSH 自带 bundled skills 固定 rank=`600`（`BUNDLED_SKILL_RANK`）——项目 skill 永远压过 DSH 内置与用户副本；用户 skill 永远压不过 DSH 原生。
+- `~/.claude/rules` 中与项目同 basename 的 rule 文件被跳过（项目优先）。
+
 `CLAUDE.md` / `AGENTS.md` **不碰** —— DSH 内置 `dsh-agent-instructions` 已处理。
 
 ## 环境要求
 
 - DSH 及其 profile（如 `web`）
-- 使用 Claude Code 约定的项目：`.claude/skills/`、`.claude/commands/`、`.claude/rules/`
+- 使用 Claude Code 约定的项目：`.claude/skills/`、`.claude/commands/`、`.claude/rules/`（均可选；`~/.claude/` 对应目录同样生效）
 
 ## 安装
 
+一条命令 —— 包声明了 `dsh.bundle`，DSH 自动激活（无需手改 `cordis.patch.yml`）：
+
 ```bash
 dsh plugin --profile web add dsh-claude-compat
 ```
@@ -43,29 +52,22 @@ dsh plugin --profile web add dsh-claude-compat
 dsh plugin --profile web add github:biedongbin/dsh-claude-compat
 ```
 
-然后在 `~/.dsh/profiles/web/cordis.patch.yml` 注册（合并进现有 patch 列表）：
-
-```yaml
-- insert:
-    - id: claude-compat
-      name: 'dsh-claude-compat'
-      config:
-        enableSkills: true
-        enableRules: true
-```
-
 重启 DSH（`dsh web`）。完成 —— skills 出现在 `/` 菜单，rules 注入每个新会话。
 
 ## 配置
 
 | 选项 | 默认值 | 说明 |
 |---|---|---|
-| `enableSkills` | `true` | 注册 `.claude/skills` + `.claude/commands` provider |
-| `enableRules` | `true` | 注入 `.claude/rules/*.md` 到消息流 |
-| `rulesMaxBytes` | `65536` | 注入 rules 总量硬上限 |
+| `enableSkills` | `true` | 注册 `.claude/skills` + `.claude/commands` provider（项目与 `~/.claude` 均含） |
+| `enableRules` | `true` | 注入项目 + `~/.claude` 的 `rules/*.md` 到消息流 |
+| `rulesMaxBytes` | `65536` | 注入项目 rules 总量硬上限 |
+| `userRulesMaxBytes` | `65536` | 注入 `~/.claude/rules` 总量硬上限 |
 | `projectRootMarkers` | `[".git"]` | 项目根发现的祖先标记 |
-| `skillRank` | `150` | provider 排名：介于 DSH 原生 `.dsh/skills`（100）与 `.agents/skills`（200）之间 —— 冲突时 DSH 原生优先 |
-| `skillSource` | `project-claude` | catalog 条目来源标签 |
+| `skillRank` | `50` | 项目 `.claude` skills 的 provider 排名（压过一切 DSH 原生冲突） |
+| `skillSource` | `project-claude` | 项目 catalog 条目来源标签 |
+| `userSkillRank` | `700` | `~/.claude` skills 的 provider 排名（输给 DSH 原生 `600`） |
+| `userSkillSource` | `user-claude` | `~/.claude` catalog 条目来源标签 |
+| `userClaudeDir` | `~/.claude` | 用户级 `.claude` 目录（`~` 展开为 home 目录） |
 
 ## 说明
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-claude-compat",
-  "version": "0.2.0",
-  "description": "DeepSeek Harness plugin: bridge Claude Code's .claude/ directory (skills, commands, rules) into DSH native skill registry and message-stream rules injection.",
+  "version": "0.3.0",
+  "description": "DeepSeek Harness plugin: bridge Claude Code's .claude/ directories (project and ~/.claude: skills, commands, rules) into DSH native skill registry and message-stream rules injection.",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -15,6 +15,7 @@
   "files": [
     "src",
     "README.md",
+    "README.zh-CN.md",
     "cordis.patch.yml"
   ],
   "keywords": [
@@ -44,5 +45,8 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "scripts": {
+    "check": "node --check src/index.js && node --test test/self-check.test.js"
   }
 }

package/src/index.js

@@ -2,12 +2,19 @@
 //
 // Two contributions to the live runtime:
 //   1. Skill provider on ctx.skills — scans <projectRoot>/.claude/skills/**/SKILL.md
-//      and <projectRoot>/.claude/commands/*.md, surfaces them as DSH skills so the
-//      `/skill-name` slash trigger, the `skill` tool, and the model-visible catalog
-//      pick them up natively. Only name+description load at discovery; the body
-//      loads on demand — same contract as the shipped filesystem provider.
-//   2. System prompt section — injects <projectRoot>/.claude/rules/*.md as ordered
-//      guidance. CLAUDE.md / AGENTS.md are already handled by dsh-agent-instructions,
+//      and <projectRoot>/.claude/commands/*.md (plus the user-level
+//      ~/.claude/skills and ~/.claude/commands), surfaces them as DSH skills so
+//      the `/skill-name` slash trigger, the `skill` tool, and the model-visible
+//      catalog pick them up natively. Only name+description load at discovery;
+//      the body loads on demand — same contract as the shipped filesystem
+//      provider.
+//   2. Rules message-stream injection — injects <projectRoot>/.claude/rules/*.md
+//      and ~/.claude/rules/*.md as ONE user-role <system-reminder> message
+//      prepended at the front of the message array, once per session
+//      (agent/pre-step). This mirrors Claude Code's prependUserContext channel,
+//      which models follow reliably. Same-name rule files are deduped,
+//      project .claude winning over ~/.claude.
+//      CLAUDE.md / AGENTS.md are already handled by dsh-agent-instructions,
 //      so we do NOT re-inject them here.
 //
 // Skill name flattening: .claude/skills/gitnexus/gitnexus-guide/SKILL.md →
@@ -17,13 +24,22 @@
 // Commands: .claude/commands/commit-changes.md → skill "commit-changes",
 // user-invocable forced true so `/commit-changes` works in the slash menu.
 //
-// Rules text is re-read every system-prompt assembly (per model step), so rule
-// edits take effect without a DSH restart. No file watcher — the cost of
-// stat'ing a handful of small markdown files is negligible per step.
+// Precedence (DSH registry semantics: candidates sort by rank ascending and
+// duplicate skill names are first-wins — LOWER rank wins). The native ladder
+// is project-dsh 100, project-agents 200, custom 300, user-dsh 400,
+// user-agents 500, DSH bundled 600 (fixed BUNDLED_SKILL_RANK). This plugin
+// emits project .claude at rank 50 and ~/.claude at rank 700, so conflicts
+// resolve as: project .claude > DSH native (600) > ~/.claude.
+//
+// Rules are read once per session (cached per session cwd, from
+// agent.session.header.cwd — NOT process.cwd(), the DSH process may be
+// launched from anywhere). Editing a rule mid-session takes effect in the
+// next session.
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { join, dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
 import z from '@deepseek-ai/schemastery';
 import { parse } from 'yaml';
 import { isSkillName } from '@deepseek-ai/dsh-skill';
@@ -34,11 +50,17 @@ export const inject = ['skills'];
 
 export const Config = z.object({
   projectRootMarkers: z.array(z.string()).default(['.git']),
-  // 150: between project-dsh (100) and project-agents (200). DSH-native skills
-  // win over Claude skills; Claude skills win over user-level.
-  skillRank: z.number().default(150),
+  // DSH dedupes by rank ascending (lower wins). 50 beats the DSH-native
+  // project roots (100/200) and the bundled root (600) — project .claude wins
+  // every collision. 700 loses to bundled 600 — DSH native wins over
+  // ~/.claude. Final priority: project .claude > DSH native > ~/.claude.
+  skillRank: z.number().default(50),
   skillSource: z.string().default('project-claude'),
+  userSkillRank: z.number().default(700),
+  userSkillSource: z.string().default('user-claude'),
+  userClaudeDir: z.string().default('~/.claude'),
   rulesMaxBytes: z.number().default(65536),
+  userRulesMaxBytes: z.number().default(65536),
   enableRules: z.boolean().default(true),
   enableSkills: z.boolean().default(true),
 });
@@ -60,27 +82,38 @@ class ClaudeCompatSkillProvider {
     this.ctx = ctx;
     this.name = 'claude-compat';
     this.config = config;
-    this.skillRank = config.skillRank ?? 150;
+    this.skillRank = config.skillRank ?? 50;
     this.source = config.skillSource ?? 'project-claude';
+    this.userSkillRank = config.userSkillRank ?? 700;
+    this.userSkillSource = config.userSkillSource ?? 'user-claude';
+    this.userClaudeDir = resolveUserClaudeDir(config.userClaudeDir);
     control.signal.addEventListener('abort', () => {}, { once: true });
   }
 
   async list(options) {
     const cwd = options?.cwd;
-    if (cwd === undefined || cwd === null) return [];
-    const projectRoot = await findProjectRoot(cwd, this.config.projectRootMarkers);
-    if (projectRoot === undefined) return [];
-    const claudeDir = join(projectRoot, '.claude');
-    if (!(await pathExists(claudeDir))) return [];
-
     const candidates = [];
-    for (const c of await discoverSkills(join(claudeDir, 'skills'), this.name, this.source, this.skillRank)) {
+    // Project .claude needs a cwd to locate the project root; user ~/.claude
+    // is cwd-independent (mirrors DSH's own user-dsh/user-agents roots, which
+    // are scanned unconditionally).
+    if (cwd !== undefined && cwd !== null) {
+      const projectRoot = await findProjectRoot(cwd, this.config.projectRootMarkers);
+      if (projectRoot !== undefined) {
+        await this.addRootCandidates(candidates, join(projectRoot, '.claude'), this.source, this.skillRank);
+      }
+    }
+    await this.addRootCandidates(candidates, this.userClaudeDir, this.userSkillSource, this.userSkillRank);
+    return candidates;
+  }
+
+  async addRootCandidates(candidates, claudeDir, source, rank) {
+    if (!(await pathExists(claudeDir))) return;
+    for (const c of await discoverSkills(join(claudeDir, 'skills'), this.name, source, rank)) {
       candidates.push(c);
     }
-    for (const c of await discoverCommands(join(claudeDir, 'commands'), this.name, this.source, this.skillRank)) {
+    for (const c of await discoverCommands(join(claudeDir, 'commands'), this.name, source, rank)) {
       candidates.push(c);
     }
-    return candidates;
   }
 
   async get(candidate) {
@@ -103,7 +136,7 @@ class ClaudeCompatSkillProvider {
   }
 }
 
-// ─── discovery: .claude/skills (recursive, ≤3 levels) ────────────────────────
+// ─── discovery: <root>/.claude/skills (recursive, ≤3 levels) ─────────────────
 
 async function discoverSkills(rootDir, providerName, source, rank) {
   const out = [];
@@ -132,7 +165,7 @@ async function discoverSkills(rootDir, providerName, source, rank) {
   }
 }
 
-// ─── discovery: .claude/commands (flat) ──────────────────────────────────────
+// ─── discovery: <root>/.claude/commands (flat) ───────────────────────────────
 
 async function discoverCommands(rootDir, providerName, source, rank) {
   const out = [];
@@ -241,22 +274,29 @@ function registerRulesSection(ctx, config) {
 }
 
 function buildRulesText(cwd, config, maxBytes) {
-  const projectRoot = findProjectRootSync(cwd, config.projectRootMarkers);
-  if (projectRoot === undefined) return '';
-  const rulesDir = join(projectRoot, '.claude', 'rules');
-  const files = listMdFilesSync(rulesDir);
-  if (files.length === 0) return '';
   const parts = [];
-  let total = 0;
-  for (const f of files) {
-    let raw;
-    try { raw = readFileSync(f, 'utf8'); } catch { continue; }
-    const basename = f.split('/').pop();
-    const chunk = `## ${basename}\n\n${raw.trim()}\n`;
-    if (total + chunk.length > maxBytes) break;
-    parts.push(chunk);
-    total += chunk.length;
+  const seen = new Set();
+  const pushRoot = (rootDir, cap) => {
+    let remaining = cap;
+    const files = listMdFilesSync(rootDir);
+    for (const f of files) {
+      const basename = f.split('/').pop();
+      if (seen.has(basename)) continue; // higher-priority root already included
+      let raw;
+      try { raw = readFileSync(f, 'utf8'); } catch { continue; }
+      const chunk = `## ${basename}\n\n${raw.trim()}\n`;
+      if (chunk.length > remaining) break;
+      remaining -= chunk.length;
+      seen.add(basename);
+      parts.push(chunk);
+    }
+  };
+  // Project .claude/rules first: wins same-name collisions against ~/.claude.
+  const projectRoot = findProjectRootSync(cwd, config.projectRootMarkers);
+  if (projectRoot !== undefined) {
+    pushRoot(join(projectRoot, '.claude', 'rules'), maxBytes);
   }
+  pushRoot(join(resolveUserClaudeDir(config.userClaudeDir), 'rules'), config.userRulesMaxBytes ?? maxBytes);
   if (parts.length === 0) return '';
   // Exact envelope Claude Code uses in prependUserContext (api.ts):
   // user-role <system-reminder> with "# claudeMd" framing.
@@ -294,6 +334,13 @@ function listMdFilesSync(dir) {
 
 // ─── helpers ─────────────────────────────────────────────────────────────────
 
+function resolveUserClaudeDir(dir) {
+  if (dir === undefined || dir === null || dir === '') return join(homedir(), '.claude');
+  if (dir === '~') return homedir();
+  if (dir.startsWith('~/')) return join(homedir(), dir.slice(2));
+  return resolve(dir);
+}
+
 async function findProjectRoot(cwd, markers = ['.git']) {
   let current = resolve(cwd);
   while (true) {