dsh-skill-compat-plus 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shuxidemosheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# dsh-skill-compat-plus
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/dsh-skill-compat-plus.svg)](https://www.npmjs.com/package/dsh-skill-compat-plus)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](package.json)
+
+**把 Claude Code / Codex / ZCode 的技能目录挂进 DeepSeek Harness（dsh）。** 一个插件，让 dsh 直接看到你已有生态里的 agent skills——无需复制、无需迁移、改动即时生效。
+
+## 它是什么
+
+dsh 官方的技能发现只扫描 `.dsh/skills`、`.agents/skills`、`~/.dsh/skills` 等自有目录。而 Claude Code（`~/.claude/skills`）、Codex CLI（`~/.codex/skills`）、ZCode（`~/.zcode/skills`）各自维护着大量高质量技能。本插件以 **SkillProvider** 形式（`ctx.skills.registerProvider`）把这些目录作为只读来源挂进 dsh 的技能注册表：
+
+- **模型可用**：导入技能进入 `skill` 工具的目录（catalog），模型按需加载；
+- **用户可斜杠调用**：`user-invocable` 技能自动获得 dsh 原生的 `/name` 手势入口；
+- **热更新**：目录里新增/修改/删除技能文件，无需重启即可生效（chokidar + 存在性轮询）；
+- **零侵入**：只读挂载，不复制、不改写你的任何文件；卸载即恢复原状。
+
+## 功能
+
+- 三家来源默认全开，目录不存在时静默跳过：
+  - `claude-code`：`~/.claude/skills`（用户级）+ `<项目根>/.claude/skills`（项目级，按最近 `.git` 祖先探测）
+  - `codex`：`~/.codex/skills`（旧约定目录；Codex 新官方 `~/.agents/skills` dsh 原生已扫，不重复挂载）
+  - `zcode`：`~/.zcode/skills`（用户级）+ `<项目根>/.zcode/skills`（项目级）
+- **frontmatter 字段映射**（详见下表）：`when_to_use` → `whenToUse`、宽松布尔、Codex `agents/openai.yaml` 的 `policy.allow_implicit_invocation` 等
+- **名称规范化**：外来名不符合 dsh kebab-case 时自动 slug 化（如 `_references` → `references`、`code_review` → `code-review`），可关闭
+- **description 合成**：Claude 允许缺省 description，而 dsh 必填——自动取正文首段合成（可关闭）
+- **优先级体系**：dsh 原生技能永远压过同名导入技能；项目级导入压过用户级导入
+- **诊断聚合**：无效文件、命名冲突等按问题集合变化输出 warn，不刷屏
+- YAML 用官方同款 `yaml` 包解析——块标量（`>-`、`|`）、嵌套 metadata 都能正确处理
+
+## 字段映射表
+
+| 外来字段 | Claude Code | Codex | ZCode | 映射到 dsh |
+|---|---|---|---|---|
+| `name` | 可选（缺省取目录名） | 必填 | 可选（缺省取目录名） | 必填；缺省用目录名，不合规则 slug 化 |
+| `description` | 可选 | 必填 | 可选 | 必填；缺失时从正文首段合成（可关） |
+| `when_to_use` | 有 | 无 | 有 | `whenToUse`（snake → camel） |
+| `disable-model-invocation` | 有 | 无 | 无 | `invocation.modelInvocable` |
+| `user-invocable` | 有 | 无 | 无 | `invocation.userInvocable` |
+| `agents/openai.yaml` 的 `policy.allow_implicit_invocation: false` | 无 | 有 | 无 | `invocation.modelInvocable: false` |
+| `allowed-tools` / `disallowed-tools` | 有 | 有（空格分隔） | 无 | 保留在 `metadata`（dsh 无对应物） |
+| `model` / `effort` / `hooks` / `paths` / `shell` / `argument-hint` 等 | 有 | 无 | 无 | 保留在 `metadata` |
+| `license` / `compatibility` | 有 | 有 | 容忍 | 保留在 `metadata` |
+| `metadata`（map） | 有 | 有 | 有 | 原样保留 |
+
+整个原始 frontmatter 会全量保真进 `metadata`，不做静默丢弃。
+
+## 优先级（rank，越小越优先）
+
+| 来源 | 目录 | rank | 语义 |
+|---|---|---|---|
+| dsh 原生 project-dsh | `<项目根>/.dsh/skills` | 100 | 永远压过导入 |
+| dsh 原生 project-agents | `<项目根>/.agents/skills` | 200 | 永远压过导入 |
+| **claude-code 项目级** | `<项目根>/.claude/skills` | **210** | 输给 dsh 原生项目级 |
+| **zcode 项目级** | `<项目根>/.zcode/skills` | **220** | 同上 |
+| dsh 原生 custom | `Config.customSkillDirs` | 300 | |
+| **extraDirs** | 任意目录 | **300**（可按目录覆盖） | 与官方 custom 同档 |
+| dsh 原生 user-dsh | `~/.dsh/skills` | 400 | |
+| **claude-code 用户级** | `~/.claude/skills` | **450** | 输给 dsh 原生用户级 |
+| **codex 用户级** | `~/.codex/skills` | **460** | |
+| **zcode 用户级** | `~/.zcode/skills` | **470** | |
+| dsh 原生 user-agents / bundled | `~/.agents/skills` / 内置 | 500 / 600 | |
+
+同名技能裁决由 dsh 官方注册表完成（rank → provider 注册序 → list 内顺序），本插件只负责给出确定的 rank。
+
+## 安装
+
+| 方式 | 命令 / 操作 |
+|---|---|
+| CLI（npm 包） | `dsh plugin --profile <你的profile> add dsh-skill-compat-plus` |
+| 桌面端 | 插件页安装 `dsh-skill-compat-plus`，或：`ELECTRON_RUN_AS_NODE=1 "/d/DeepSeek Harness/DeepSeek Harness.exe" --expose-internals "D:/DeepSeek Harness/resources/app.asar/dsh/node_modules/@deepseek-ai/dsh-desktop-host/lib/cli.js" plugin --profile desktop add dsh-skill-compat-plus`（Git Bash，先完全退出应用含托盘） |
+| git 直装（始终最新 main） | `dsh plugin --profile <你的profile> add git+https://github.com/shuxidemosheng/dsh-skill-compat-plus.git` |
+| 本地 tgz | `npm pack` 后 `dsh plugin --profile <你的profile> add file:D:/AIcoding/dsh-skill-compat-plus/dsh-skill-compat-plus-0.1.0.tgz` |
+
+## 配置
+
+配置写在 `cordis.patch.yml` 的 entry `config` 下（profile 层可覆盖，整体替换语义）：
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `providerName` | `skill-compat-plus` | provider 注册名（`runtime` 为保留字，不可用） |
+| `sources.claude` | `true` | `boolean` 或 `{ enabled?, project?, root?, rank? }` |
+| `sources.codex` | `true` | 同上 |
+| `sources.zcode` | `true` | 同上 |
+| `extraDirs` | `[]` | `{ path, label?, rank? }[]`，任意额外技能目录 |
+| `watch` | `true` | 文件变化热更新 |
+| `watchUsePolling` | `false` | 网络盘/特殊文件系统上开启轮询监视 |
+| `watchStabilityThresholdMs` | `200` | awaitWriteFinish 稳定阈值 |
+| `watchPollIntervalMs` | `100` | awaitWriteFinish 轮询间隔 |
+| `watchMaxProjects` | `128` | 项目根监视 LRU 上限 |
+| `slugifyNames` | `true` | 关闭后不合规名直接 skip |
+| `synthesizeDescription` | `true` | 关闭后缺 description 的技能直接 skip |
+
+未知配置键会直接报错（fail-fast，不做静默忽略）。
+
+## 本地开发
+
+```bash
+# Git Bash
+npm install
+npm test              # vitest，32 个用例（含 Windows 路径、真实时序 watch 测试、与上游文法的对拍）
+npm run build         # tsc d.ts + esbuild bundle（yaml/chokidar 为外部运行时依赖）
+node scripts/smoke.mjs   # 用构建产物直接扫描本机真实技能目录并打印清单
+```
+
+## 安全
+
+- 本插件**只读**外部技能目录：唯一的写操作是 chokidar/fs.watchFile 的监视句柄。
+- 技能内容由 dsh 官方 `skill` 工具管线加载，本插件不执行任何技能内代码。
+- **产物最小化**：`yaml`/`chokidar` 作为运行时依赖（由 plugin-manager 安装进 profile），构建产物只含第一方代码——安全扫描面与攻击面都最小。
+- **Mimosa 深度扫描封印**（2026-10-11，v0.1.0，最终产物）：
+  - 发布前复核：scanId `scan-2026-10-11T10-22-46.363Z-046924c5dc3e`，seal `sha256:8b6abe1217fbf677d8f9577792cf63a89ba5c97b04f85c6ae67027340a0f93a7`，findings 0，依赖风险 0
+  - seal: `sha256:f35ddf0890c53725a25589f8515b20f3b13025d213f8901af52a28d2dc77ccf1`
+  - findings 0，依赖风险 0。
+  - 历史记录：最初的 472KB 自包含产物曾报 6 条静态 advisory（scanId `scan-2026-10-11T09-25-20.462Z-3a00d7a1835b`，全部位于当时打包进去的上游闭包——`yaml` scalar 解析器、`@deepseek-ai/schemastery`、`@deepseek-ai/dsh-skill` 注册表内部，属静态污点分析对官方包内部实现的误报模式）。据此改为外部依赖方案后复扫归零。
+
+## 已知限制
+
+- Claude/ZCode **插件包内部**的技能（`~/.claude/plugins`、`~/.zcode/cli/plugins/cache` 等）不在默认发现范围，可用 `extraDirs` 手动挂载；自动识别（`.claude-plugin/plugin.json` 等）留待后续版本。
+- 项目级只扫描最近 `.git` 祖先**一级**（对齐 dsh 官方）；ZCode 式的 CWD→worktree 多级扫描不做。
+- Claude Code 的嵌套 `<subdir>/.claude/skills`、`--add-dir`、企业托管目录不支持。
+- `allowed-tools` / `model` / `hooks` 等执行语义字段在 dsh 没有对应物，仅保留在 `metadata` 供追溯。
+- 大量导入技能会增大模型端 catalog（每个会话一条 `<available_skills>` 提醒）；建议用 `sources.*.enabled` / `extraDirs` 精选。
+- dsh 处于 developer preview：peerDependencies 锁 `@deepseek-ai/dsh-skill >=0.2.0-rc.2`，上游 breaking change 需跟进。
+
+## FAQ
+
+**Q: 会不会和 dsh 原生技能冲突？**
+同名时 dsh 原生优先（见 rank 表），不会出现不可预测的覆盖；本插件发现的重名会在日志里给出 `duplicate skill name` 诊断。
+
+**Q: `~/.agents/skills` 里的技能为什么没被本插件列出？**
+那本来就是 dsh 原生扫描的目录（同时也是 Codex 新官方用户根），无需桥接。
+
+**Q: 技能文件改了但没生效？**
+确认 `watch: true`；网络盘请开 `watchUsePolling: true`。watch 的存在性轮询约 2.5s，内容事件走 chokidar（亚秒级）。
+
+## 上游致谢
+
+- [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) —— SkillProvider 接缝、`dsh-skill-filesystem` 参考实现、插件 bundle 机制
+- 格式参考：[Claude Code skills 文档](https://code.claude.com/docs/en/skills)、[Codex skills 文档](https://developers.openai.com/codex/skills)、[Agent Skills 开放规范](https://agentskills.io)
+- 同类项目：[YTyangtao666/dsh-skills-bridge](https://github.com/YTyangtao666/dsh-skills-bridge)（首发思路），本插件在目录覆盖面、YAML 解析、Windows 路径正确性、诊断聚合与测试覆盖上做了全面增强
+
+## 许可证
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,16 @@
+- insert:
+    - id: skill-compat-plus
+      name: dsh-skill-compat-plus
+      config:
+        # 各外部技能来源：true/false 或 { enabled, project, root, rank } 精细控制。
+        # 三家默认全开；目录不存在时静默跳过。
+        sources:
+          claude: true   # ~/.claude/skills + <项目根>/.claude/skills
+          codex: true    # ~/.codex/skills（Codex 旧约定目录；新官方 ~/.agents/skills 由 dsh 原生扫描）
+          zcode: true    # ~/.zcode/skills + <项目根>/.zcode/skills
+        # 额外目录：{ path, label?, rank? }，rank 默认 300（与官方 custom 同档）
+        extraDirs: []
+        watch: true
+        watchUsePolling: false   # 网络盘/特殊文件系统上手动开启
+        slugifyNames: true       # 外来技能名不符合 dsh kebab-case 时自动转换
+        synthesizeDescription: true  # Claude 允许缺省 description；开启时从正文首段合成

package/lib/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 配置校验：手写 resolveConfig，未知键直接抛错（对齐官方 plan-mode 的纪律，
+ * 避免拼写错误的配置键被静默吞掉）。cordis.patch.yml 的 patch config 是整体
+ * 替换语义，这里拿到的是经过 YAML 反序列化后的普通对象。
+ */
+import type { ConfigInput, ResolvedConfig } from './types.js';
+/**
+ * 校验并规范化配置。任何未知键或非法值都会抛错——让错误在插件激活期
+ * 暴露，而不是在扫描期被静默吞掉。
+ */
+export declare function resolveConfig(input: ConfigInput | undefined): ResolvedConfig;

package/lib/config.js

@@ -0,0 +1,152 @@
+const CONFIG_KEYS = [
+    'providerName',
+    'sources',
+    'extraDirs',
+    'watch',
+    'watchUsePolling',
+    'watchStabilityThresholdMs',
+    'watchPollIntervalMs',
+    'watchMaxProjects',
+    'slugifyNames',
+    'synthesizeDescription',
+];
+const SOURCE_KEYS = ['enabled', 'project', 'root', 'rank'];
+const SOURCE_IDS = ['claude', 'codex', 'zcode'];
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function booleanField(source, key) {
+    const value = source[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new Error(`config field "${key}" must be a boolean, got ${typeof value}`);
+    return value;
+}
+function positiveNumberField(source, key) {
+    const value = source[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        throw new Error(`config field "${key}" must be a positive finite number`);
+    }
+    return value;
+}
+function stringField(source, key) {
+    const value = source[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`config field "${key}" must be a non-empty string`);
+    }
+    return value;
+}
+function resolveSourceOption(id, option) {
+    const settings = { enabled: true, project: true };
+    if (option === undefined || typeof option === 'boolean') {
+        settings.enabled = option !== false;
+        return settings;
+    }
+    if (!isPlainObject(option)) {
+        throw new Error(`config sources.${id} must be a boolean or an object`);
+    }
+    for (const key of Object.keys(option)) {
+        if (!SOURCE_KEYS.includes(key)) {
+            throw new Error(`unknown config sources.${id} key "${key}" (expected ${SOURCE_KEYS.join(', ')})`);
+        }
+    }
+    const enabled = booleanField(option, 'enabled');
+    const project = booleanField(option, 'project');
+    const root = stringField(option, 'root');
+    const rank = option.rank;
+    if (rank !== undefined && (typeof rank !== 'number' || !Number.isFinite(rank))) {
+        throw new Error('config sources rank must be a finite number');
+    }
+    return {
+        enabled: enabled ?? true,
+        project: project ?? true,
+        root,
+        rank,
+    };
+}
+function resolveExtraDirs(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error('config extraDirs must be an array');
+    const dirs = [];
+    for (const raw of value) {
+        if (!isPlainObject(raw))
+            throw new Error('config extraDirs entries must be objects like { path, label?, rank? }');
+        for (const key of Object.keys(raw)) {
+            if (!['path', 'label', 'rank'].includes(key)) {
+                throw new Error(`unknown config extraDirs entry key "${key}" (expected path, label, rank)`);
+            }
+        }
+        const path = stringField(raw, 'path');
+        if (path === undefined)
+            throw new Error('config extraDirs entry requires a non-empty "path"');
+        const label = stringField(raw, 'label') ?? 'custom';
+        const rank = raw.rank;
+        if (rank !== undefined && (typeof rank !== 'number' || !Number.isFinite(rank))) {
+            throw new Error('config extraDirs entry rank must be a finite number');
+        }
+        dirs.push({ path, label, rank: rank ?? 300 });
+    }
+    return dirs;
+}
+/**
+ * 校验并规范化配置。任何未知键或非法值都会抛错——让错误在插件激活期
+ * 暴露，而不是在扫描期被静默吞掉。
+ */
+export function resolveConfig(input) {
+    if (input !== undefined && !isPlainObject(input)) {
+        throw new Error('plugin config must be an object');
+    }
+    const source = input ?? {};
+    for (const key of Object.keys(source)) {
+        if (!CONFIG_KEYS.includes(key)) {
+            throw new Error(`unknown plugin config key "${key}" (expected ${CONFIG_KEYS.join(', ')})`);
+        }
+    }
+    const providerName = stringField(source, 'providerName') ?? 'skill-compat-plus';
+    if (providerName === 'runtime') {
+        throw new Error('config providerName "runtime" is reserved by the dsh skill registry');
+    }
+    const rawSources = source.sources;
+    if (rawSources !== undefined && !isPlainObject(rawSources)) {
+        throw new Error('config sources must be an object with keys claude, codex, zcode');
+    }
+    for (const key of Object.keys(rawSources ?? {})) {
+        if (!SOURCE_IDS.includes(key)) {
+            throw new Error(`unknown config sources key "${key}" (expected ${SOURCE_IDS.join(', ')})`);
+        }
+    }
+    const sources = {
+        claude: resolveSourceOption('claude', rawSources?.claude),
+        codex: resolveSourceOption('codex', rawSources?.codex),
+        zcode: resolveSourceOption('zcode', rawSources?.zcode),
+    };
+    const watch = booleanField(source, 'watch') ?? true;
+    const watchUsePolling = booleanField(source, 'watchUsePolling') ?? false;
+    const watchStabilityThresholdMs = positiveNumberField(source, 'watchStabilityThresholdMs') ?? 200;
+    const watchPollIntervalMs = positiveNumberField(source, 'watchPollIntervalMs') ?? 100;
+    const watchMaxProjects = positiveNumberField(source, 'watchMaxProjects') ?? 128;
+    const slugifyNames = booleanField(source, 'slugifyNames') ?? true;
+    const synthesizeDescription = booleanField(source, 'synthesizeDescription') ?? true;
+    const extraDirs = resolveExtraDirs(source.extraDirs);
+    const anySourceEnabled = sources.claude.enabled || sources.codex.enabled || sources.zcode.enabled || extraDirs.length > 0;
+    return Object.freeze({
+        providerName,
+        sources,
+        extraDirs: Object.freeze(extraDirs),
+        watch,
+        watchUsePolling,
+        watchStabilityThresholdMs,
+        watchPollIntervalMs,
+        watchMaxProjects,
+        slugifyNames,
+        synthesizeDescription,
+        anySourceEnabled,
+    });
+}

package/lib/frontmatter.d.ts

@@ -0,0 +1,55 @@
+import type { MappedSkill } from './types.js';
+export declare function isSkillName(name: string): boolean;
+export interface ParsedFrontmatter {
+    data: Record<string, unknown>;
+    body: string;
+}
+/**
+ * 切分并解析 frontmatter。边界判定逐行扫描（首行必须是独立的 ---，
+ * 兼容 \r），与官方 skill-filesystem 同构；YAML 本体交给官方同款 yaml 包，
+ * 因此块标量（>- / |）与嵌套 map 都能正确解析。
+ */
+export declare function splitFrontmatter(raw: string): ParsedFrontmatter | undefined;
+/**
+ * 宽松布尔解析（对齐官方 parseInvocationPolicy：1/0、"true/false/yes/no/on/off"）。
+ * 返回 undefined 表示不是合法布尔。
+ */
+export declare function lenientBoolean(value: unknown): boolean | undefined;
+/**
+ * 把外来名转换成 dsh kebab-case：小写、非 [a-z0-9] 的连续字符折叠成单 '-'、
+ * 去首尾 '-'。数字开头合法（dsh 正则允许 "4drawio"）。
+ */
+export declare function slugifySkillName(input: string): string;
+/** 从正文合成 description：取首个非空行，压缩空白后截到 ~200 字符。 */
+export declare function synthesizeDescription(body: string): string;
+export interface MapForeignSkillInput {
+    /** SKILL.md 或扁平 .md 的绝对路径。 */
+    filePath: string;
+    /** resource base（目录 bundle 的目录或扁平文件所在根）。 */
+    directory: string;
+    /** 目录名（目录 bundle）或去扩展名的文件名（扁平）。 */
+    entryName: string;
+    parsed: ParsedFrontmatter;
+    slugify: boolean;
+    synthesize: boolean;
+    /** Codex agents/openai.yaml 解析结果（可选文件，缺省视为允许隐式调用）。 */
+    allowImplicitInvocation?: boolean;
+}
+export type MapForeignSkillResult = {
+    readonly ok: true;
+    readonly skill: MappedSkill;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * 把一份已切分的外来 SKILL.md 映射成 dsh 技能字段。
+ * 失败返回人读 reason（由上层聚合成 warn），绝不 throw。
+ */
+export declare function mapForeignSkill(input: MapForeignSkillInput): MapForeignSkillResult;
+/**
+ * 读取 Codex 的 agents/openai.yaml（可选文件），提取
+ * policy.allow_implicit_invocation。文件不存在或格式异常时返回 undefined
+ * （可选文件解析失败不该拖垮整个技能）。
+ */
+export declare function readCodexOpenAiPolicy(directory: string): Promise<boolean | undefined>;

package/lib/frontmatter.js

@@ -0,0 +1,215 @@
+/**
+ * 外来 frontmatter → dsh 技能字段映射。
+ *
+ * 三家生态的格式差异（调研结论，字段细节见 README 映射表）：
+ * - Claude Code：全部字段可选，name 缺省取目录名；`when_to_use`（snake_case）；
+ *   可能出现 `allowed-tools`/`model`/`hooks` 等 dsh 无对应物的字段。
+ * - Codex / Agent Skills 规范：name+description 必填；可选 agents/openai.yaml
+ *   的 policy.allow_implicit_invocation=false 表示"只能显式调用"。
+ * - ZCode：name 缺省取目录名；`when_to_use`（snake_case）。
+ * - dsh：name/description 必填且 name 必须是 kebab-case
+ *   （/^[a-z0-9]+(?:-[a-z0-9]+)*$/），invocation 双布尔必给。
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+/**
+ * dsh 技能名的公共文法。刻意本地复制官方 @deepseek-ai/dsh-skill 内部常量
+ * SKILL_NAME 而不运行时引入该包：避免把注册表闭包（schemastery 等）打进
+ * 构建产物。一致性由 tests/frontmatter.spec.ts 的对拍用例保证——上游若
+ * 修改文法，该测试会失败提醒同步。
+ */
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function isSkillName(name) {
+    return SKILL_NAME.test(name);
+}
+/**
+ * 切分并解析 frontmatter。边界判定逐行扫描（首行必须是独立的 ---，
+ * 兼容 \r），与官方 skill-filesystem 同构；YAML 本体交给官方同款 yaml 包，
+ * 因此块标量（>- / |）与嵌套 map 都能正确解析。
+ */
+export function splitFrontmatter(raw) {
+    const firstLineEnd = raw.indexOf('\n');
+    if (firstLineEnd < 0)
+        return undefined;
+    const firstLine = raw.slice(0, firstLineEnd).replace(/\r$/, '');
+    if (firstLine !== '---')
+        return undefined;
+    const start = firstLineEnd + 1;
+    let lineStart = start;
+    while (lineStart <= raw.length) {
+        const nextNewline = raw.indexOf('\n', lineStart);
+        const lineEnd = nextNewline < 0 ? raw.length : nextNewline;
+        const line = raw.slice(lineStart, lineEnd).replace(/\r$/, '');
+        if (line === '---') {
+            const yamlText = raw.slice(start, lineStart);
+            let parsed;
+            try {
+                parsed = parseYaml(yamlText);
+            }
+            catch {
+                return undefined;
+            }
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+                return undefined;
+            return { data: parsed, body: raw.slice(nextNewline < 0 ? raw.length : nextNewline + 1) };
+        }
+        if (nextNewline < 0)
+            return undefined;
+        lineStart = nextNewline + 1;
+    }
+    return undefined;
+}
+/** dsh 禁止的 legacy camelCase 调用字段（官方解析器会直接 throw，这里同样拒绝）。 */
+const LEGACY_INVOCATION_KEYS = ['disableModelInvocation', 'modelInvocable', 'userInvocable'];
+/**
+ * 宽松布尔解析（对齐官方 parseInvocationPolicy：1/0、"true/false/yes/no/on/off"）。
+ * 返回 undefined 表示不是合法布尔。
+ */
+export function lenientBoolean(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (value === 1)
+            return true;
+        if (value === 0)
+            return false;
+        return undefined;
+    }
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (['true', 'yes', 'on', '1'].includes(normalized))
+            return true;
+        if (['false', 'no', 'off', '0'].includes(normalized))
+            return false;
+    }
+    return undefined;
+}
+/**
+ * 把外来名转换成 dsh kebab-case：小写、非 [a-z0-9] 的连续字符折叠成单 '-'、
+ * 去首尾 '-'。数字开头合法（dsh 正则允许 "4drawio"）。
+ */
+export function slugifySkillName(input) {
+    return input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+function firstMeaningfulText(text) {
+    for (const line of text.split(/\r?\n/)) {
+        const stripped = line.replace(/^\s*#+\s*/, '').trim();
+        if (stripped.length > 0)
+            return stripped;
+    }
+    return '';
+}
+/** 从正文合成 description：取首个非空行，压缩空白后截到 ~200 字符。 */
+export function synthesizeDescription(body) {
+    const text = firstMeaningfulText(body);
+    if (text.length <= 200)
+        return text;
+    const slice = text.slice(0, 200);
+    const lastSpace = slice.lastIndexOf(' ');
+    return (lastSpace >= 160 ? slice.slice(0, lastSpace) : slice) + '…';
+}
+function stringField(data, key) {
+    const value = data[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+/**
+ * 把一份已切分的外来 SKILL.md 映射成 dsh 技能字段。
+ * 失败返回人读 reason（由上层聚合成 warn），绝不 throw。
+ */
+export function mapForeignSkill(input) {
+    const { parsed, filePath } = input;
+    const data = parsed.data;
+    for (const key of LEGACY_INVOCATION_KEYS) {
+        if (key in data) {
+            return {
+                ok: false,
+                reason: `frontmatter field "${key}" is unsupported; use "disable-model-invocation"`,
+            };
+        }
+    }
+    // name：frontmatter 优先，缺省回退目录名（Claude/ZCode 语义）。
+    const rawName = stringField(data, 'name') ?? input.entryName;
+    let name = rawName;
+    if (!isSkillName(name)) {
+        if (!input.slugify) {
+            return { ok: false, reason: `invalid skill name "${rawName}" and slugifyNames is disabled` };
+        }
+        const slug = slugifySkillName(rawName);
+        if (!isSkillName(slug)) {
+            return { ok: false, reason: `invalid skill name "${rawName}" cannot be converted to a dsh kebab-case name` };
+        }
+        name = slug;
+    }
+    // description：dsh 硬性必填；Claude 允许缺省 → 从正文合成。
+    let description = stringField(data, 'description');
+    if (description === undefined) {
+        if (!input.synthesize) {
+            return { ok: false, reason: 'frontmatter requires a description and synthesizeDescription is disabled' };
+        }
+        description = synthesizeDescription(parsed.body);
+        if (description.length === 0) {
+            return { ok: false, reason: 'frontmatter requires a description and the body is empty' };
+        }
+    }
+    const whenToUse = stringField(data, 'whenToUse') ?? stringField(data, 'when_to_use');
+    const disableModelInvocation = lenientBoolean(data['disable-model-invocation']);
+    if (data['disable-model-invocation'] !== undefined && disableModelInvocation === undefined) {
+        return { ok: false, reason: 'frontmatter field "disable-model-invocation" must be a boolean' };
+    }
+    const userInvocableRaw = data['user-invocable'];
+    let userInvocable = true;
+    if (userInvocableRaw !== undefined) {
+        const parsed = lenientBoolean(userInvocableRaw);
+        if (parsed === undefined) {
+            return { ok: false, reason: 'frontmatter field "user-invocable" must be a boolean' };
+        }
+        userInvocable = parsed;
+    }
+    const modelInvocable = disableModelInvocation !== true && input.allowImplicitInvocation !== false;
+    return {
+        ok: true,
+        skill: {
+            name,
+            description,
+            whenToUse,
+            invocation: { modelInvocable, userInvocable },
+            // 原始 frontmatter 全量保真：allowed-tools/model/hooks 等字段在 dsh
+            // 没有对应物，保留在 metadata 里可追溯，不做静默丢弃。
+            metadata: Object.freeze({ ...data }),
+            path: filePath,
+            directory: input.directory,
+            content: parsed.body.trim(),
+        },
+    };
+}
+/**
+ * 读取 Codex 的 agents/openai.yaml（可选文件），提取
+ * policy.allow_implicit_invocation。文件不存在或格式异常时返回 undefined
+ * （可选文件解析失败不该拖垮整个技能）。
+ */
+export async function readCodexOpenAiPolicy(directory) {
+    let raw;
+    try {
+        raw = await readFile(join(directory, 'agents', 'openai.yaml'), { encoding: 'utf8' });
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const policy = parsed['policy'];
+    if (typeof policy !== 'object' || policy === null)
+        return undefined;
+    return lenientBoolean(policy['allow_implicit_invocation']);
+}

package/lib/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * dsh-skill-compat-plus —— 把 Claude Code / Codex / ZCode 的技能目录作为
+ * 只读 SkillProvider 挂载进 DeepSeek Harness。
+ *
+ * 纪律（与官方 postmortem 0001 / 既有插件一致）：
+ * - 绝不 export default（Loader 的 unwrapExports 会折叠模块并丢掉 inject）；
+ * - apply() 内同步调用 registerProvider；
+ * - 任何激活期失败都降级为 warn + return（entry 激活失败会让会话创建失败，
+ *   输家必须优雅退出）。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ConfigInput } from './types.js';
+export declare const name = "skill-compat-plus";
+/** 宿主服务依赖：技能注册表（ctx.skills）。 */
+export declare const inject: readonly ["skills"];
+export declare function apply(ctx: Context, config: ConfigInput | undefined): void;