工作区技能隔离 Sparrived/dsh-plugin-workspace-skill

dsh-plugin-workspace-skill

一个 DSH Cordis 插件，提供两个能力：

1. skill-create 技能 —— 指导 Agent 在当前工作区创建、编写、审查和验证可复用 Skill（SKILL.md 格式规范、正文结构、发布前验证清单）。设计参考了 OpenAI Codex 的 skill-creator 与 Skills 文档，并结合 DSH 的技能注册机制做了适配。
2. 工作区级 Skill 隔离 —— 一个 ctx.skills provider，把 /.dsh/skills/ 目录作为“仅当前工作区可见”的技能来源。一个项目里的私有 Skill 不会泄漏到其他工作区，还能按名字覆盖全局技能。

工作区隔离如何工作

每次技能发现时，provider 会：

1. 用调用方的 cwd 在 workspaceRegistry 中找出包含它的最深注册工作区（通过 fs.contains 规范比较，兼容 Windows 路径分隔符）。
2. 扫描该工作区根目录下的 .dsh/skills/，支持两种布局：
- .dsh/skills//SKILL.md —— 目录包，可携带 references/、scripts/、assets/ 等资源；
- .dsh/skills/.md —— 单文件扁平布局。
3. 解析 YAML frontmatter（name / description / whenToUse / disable-model-invocation / user-invocable），以 rank: 700 注册候选。

优先级：工作区技能 > 用户级与内置来源。同名时工作区版本胜出，因此项目可以安全地覆盖全局技能；cwd 不属于任何注册工作区时，此 provider 不产生任何候选。

安装

方式一：dsh plugin add（官方流程，推荐）

本包在 package.json 里声明了 dsh.bundle.patch: ./cordis.patch.yml（补丁清单就是下面的插件行），因此能被 dsh 识别为一个 profile 层：

从 npm 安装（发布后）
dsh plugin --profile web add dsh-plugin-workspace-skill

或直接从 GitHub 安装
dsh plugin --profile web add github:Sparrived/dsh-plugin-workspace-skill

或从本地 checkout 安装（相对路径 spec 会被锚定为绝对路径）
dsh plugin --profile web add D:\Code\dsh-plugin-workspace-skill

dsh plugin 会在 profile 目录（$DSH_HOME/profiles/）内转发 pnpm 完成安装，并把声明了 dsh.bundle 的依赖自动写入该 profile 的 dsh.profile.bundles 层列表。本包是纯 ESM、无构建步骤，无需 pnpm allowBuilds 放行。启动后可用 dsh --profile web --dump-config 确认 workspace-skill 行已进入组合树。

方式二：手动加插件行

不经过 bundle 机制时，直接在宿主 cordis.yml 或自定义 agent preset 的组合里写同一行：

- id: workspace-skill
name: dsh-plugin-workspace-skill
可选配置： config: providerName: workspace-isolated rootDir: .dsh/skills source: workspace rank: 700 registerGuideSkill: true

| 配置项 | 默认值 | 说明 |
| providerName | workspace-isolated | provider 名称 |
| rootDir | .dsh/skills | 相对工作区根目录的技能目录 |
| source | workspace | 候选的 source 标记 |
| rank | 700 | 排序优先级（越大越优先） |
| registerGuideSkill | true | 是否同时注册 skill-create 指导技能 |

插件声明 inject: ['skills', 'fs', 'workspaceRegistry']；停止或卸载时，provider 与运行时技能随 Cordis Fiber 一并撤销。

方式三：动态插件（临时试用）

在 DSH 会话里用动态 Cordis 插件加载 lib/index.js 的等价代码（cordis_define → cordis_run），无需改任何组合文件。注意动态插件只存活于当前进程。

方式四：只要指导技能本身

不需要隔离 provider 的话，直接把 skills/skill-create/SKILL.md 复制到用户级 ~/.dsh/skills/skill-create/SKILL.md 或某个项目的 .dsh/skills/skill-create/，DSH 内置文件系统 provider 即可发现它。

编写一个工作区 Skill

/
└── .dsh/
└── skills/
└── api-review/
├── SKILL.md
├── references/
│ └── checklist.md
└── scripts/
└── check-breaking.sh

name: api-review
description: 审查 API 变更的兼容性、安全性和测试覆盖率。
whenToUse: 在审查公共 API 或端点变更时使用。

API 审查

按下面的步骤执行……

要点：

- name 必须是小写 kebab-case，并与目录名一致；
- description 写清能力与适用场景；
- 资源放同目录下，正文中用相对路径引用。

验证

1. 在目标工作区内发起会话，确认 skill-create 出现在技能目录中；
2. 创建 .dsh/skills/hello-isolation/SKILL.md，确认它只在当前工作区可见，换到另一个工作区的会话后不可见；
3. 在用户级目录放置同名技能，确认工作区版本胜出；
4. 停用插件后确认以上技能全部消失（无残留副作用）。

一个 DSH Cordis 插件，具备两项能力：

1. skill-create 技能 —— 引导智能体在当前工作区中创建、编写、审查和验证可复用技能（SKILL.md 格式规则、正文结构、发布前检查清单）。灵感来自 OpenAI Codex 的 skill-creator 及其 Skills 文档，并适配了 DSH 的技能注册机制。
2. 工作区级技能隔离 —— 一个 ctx.skills 提供者，将 /.dsh/skills/ 视为仅对该工作区内的会话可见的技能来源。项目的私有技能绝不会泄漏到其他工作区，并且可以按名称覆盖全局技能。

工作区隔离的工作原理

在每次技能发现时，该提供者会：

1. 在 workspaceRegistry 中找到包含调用方 cwd 的最深层已注册工作区（通过 fs.contains 进行规范化比较，兼容 Windows 路径分隔符）。
2. 扫描该工作区根目录下的 .dsh/skills/，支持两种布局：
- .dsh/skills//SKILL.md —— 目录包，可包含可选的 references/、scripts/、assets/；
- .dsh/skills/.md —— 扁平的单文件布局。
3. 解析 YAML frontmatter（name / description / whenToUse / disable-model-invocation / user-invocable），并以 rank: 700 注册候选技能。

优先级：工作区技能 > 用户级和内置来源。同名的工作区技能胜出，因此项目可以安全地覆盖全局技能；当 cwd 不属于任何已注册工作区时，该提供者不贡献任何内容。

安装

方式一：dsh plugin add（官方流程，推荐）

该包在 package.json 中声明了 dsh.bundle.patch: ./cordis.patch.yml（补丁列表即下面的插件行），因此 dsh 会将其识别为一个 profile 层：

从 npm 安装（发布后）
dsh plugin --profile web add dsh-plugin-workspace-skill

或直接从 GitHub 安装
dsh plugin --profile web add github:Sparrived/dsh-plugin-workspace-skill

或从本地检出安装（相对路径规格会锚定为绝对路径）
dsh plugin --profile web add D:\Code\dsh-plugin-workspace-skill
dsh plugin 会在 profile 目录（$DSH_HOME/profiles/）内转发给 pnpm，然后自动将任何声明了 dsh.bundle 的依赖添加到该 profile 的 dsh.profile.bundles 层列表中。此包是纯 ESM，无需构建步骤，因此不需要 pnpm 的 allowBuilds 批准。启动后，使用 dsh --profile web --dump-config 验证 workspace-skill 行已落入组合树中。

选项 2：手动添加插件行

如果不使用 bundle 机制，可以直接在宿主 cordis.yml 或自定义 agent 预设组合中写入相同的行：

- id: workspace-skill
name: dsh-plugin-workspace-skill
Optional configuration:
config:
providerName: workspace-isolated
rootDir: .dsh/skills
source: workspace
rank: 700
registerGuideSkill: true

| 选项 | 默认值 | 描述 |
| providerName | workspace-isolated | 提供者名称 |
| rootDir | .dsh/skills | 相对于工作区根目录的技能目录 |
| source | workspace | 候选者上的来源标签 |
| rank | 700 | 排序优先级（数值越高越优先） |
| registerGuideSkill | true | 同时注册 skill-create 指南技能 |

该插件声明了 inject: ['skills', 'fs', 'workspaceRegistry']；在停止或卸载时，提供者和运行时技能会随 Cordis Fiber 一起解除。

选项 3：动态插件（快速试用）

在 DSH 会话中通过动态 Cordis 插件加载等效代码（cordis_define → cordis_run），无需改动任何组合文件。注意，动态插件仅在当前进程中存在。

选项 4：仅使用指南技能

如果你不需要隔离提供者，将 skills/skill-create/SKILL.md 复制到用户级 ~/.dsh/skills/skill-create/SKILL.md 或项目的 .dsh/skills/skill-create/ —— DSH 内置的文件系统提供者会发现它。

编写工作区技能

/
└── .dsh/
└── skills/
└── api-review/
├── SKILL.md
├── references/
│ └── checklist.md
└── scripts/
└── check-breaking.sh

name: api-review
description: Review API changes for compatibility, security, and test coverage.
whenToUse: Use when reviewing a public API or endpoint change.

API Review

Follow the steps below...

要点：

- name 必须是小写 kebab-case，并与目录名匹配；
- description 说明该能力及其适用场景；
- 将资源放在 SKILL.md 旁边，并使用相对路径引用它们。

验证

1. 在目标工作区内启动一个会话，确认 skill-create 出现在技能目录中；
2. 创建 .dsh/skills/hello-isolation/SKILL.md，确认它仅在此工作区中可见，而在另一个工作区的会话中不可见；
3. 在用户级放置一个同名技能，确认工作区版本优先；
4. 停止插件并确认以上所有内容消失（无残留副作用）。

许可证

MIT