dsh-skill-creator

[!IMPORTANT] 依赖前置：相邻 dsh-src 检出（link: 依赖） 本项目在开发形态下使用 link: 依赖指向相邻的 DeepSeek Harness 源码检出（dsh-src）， 与当前仓库保持同一父目录布局（<parent>/dsh-src）。克隆本仓库后：

1. 先把官方 deepseek-ai/deepseek-harness 检出到与本仓库同级的 dsh-src/ 目录，并执行其 pnpm install && pnpm run build；
2. 再按下方「安装」一节执行本仓库的 pnpm install --offline && pnpm build 与测试。 发布到 npm 的版本会尽量把 link: 依赖替换为 registry 真实版本；无法替换的内部包保持 link:，见各包 README 说明。

一键生成 DSH 技能（SKILL.md）的 Cordis 插件：在 DeepSeek Harness 会话内，从一段对话/一份文档/一个流程描述自动生成符合 DSH 技能格式的 SKILL.md，并支持校验、打包分发、描述优化。

参考与许可：功能与流程参考 anthropics/claude-plugins-official 的 skill-creator（其源码为 Proprietary），本项目仅移植行为与规则，代码独立重写；脚本与逻辑见下方"从上游移植的内容"。本项目采用 MIT。

---

1. 安装与挂载

本项目是一个 DSH bundle（组合包）：package.json 通过 dsh.bundle.patch 指向 cordis.yml，cordis.yml 插入一行 skill-creator 插件。

# 在项目目录同级安装（dsh CLI）
dsh plugin --profile <name> add ./dsh-skill-creator
# 或直接加载本地元数据层
dsh --profile <name> --patch ./cordis.yml

cordis.yml 插件行可配置（均可省略）：

- insert:
    - id: skill-creator
      name: 'dsh-skill-creator'
      config:
        mountRuntimeProvider: true   # 是否把输出目录注册为运行期技能源
        # outputDir: /abs/path       # 技能输出根；默认 $DSH_HOME/skills
        # customSkillDirs: [...]     # 附加根；默认输出目录取首项

插件行为

• 4 个模型工具通过 defineTool 注册（tools 服务，effect 式注册，卸载自动清理）。
• 自带"输出目录挂载"：apply 时若 skills 注册表可用，将输出根（outputDir + customSkillDirs）注册为一个运行期 skill provider（registerProvider，rank 300 / source custom），因此 skill_new 写出的技能立即能被 skill 工具列出并加载，无需手工改配置。
• 若注册表不可用（未安装 @deepseek-ai/dsh-skill），插件在日志与 skill_new 返回里给出 mountHint：在 profile 的 skill-filesystem 配置中增加 customSkillDirs。

构建与测试：

pnpm install && pnpm build      # tsc → dist/（rewrite .ts → .js）
node tests/smoke.e2e.ts         # 离线冒烟测试（无外部依赖）

依赖说明：仅有 src/index.ts 引用 @deepseek-ai/cordis（仅类型）与 @deepseek-ai/dsh-tools。src/lib、src/tools 全部零 npm 依赖（只用 Node 内置模块），因此冒烟测试、Python 脚本与静态阅读均可在离线环境完成。

---

2. 四个工具

2.1 skill_new — 捕获意图生成草稿

参数	类型	说明
goal	string (必填)	要固化成技能的工作流描述：步骤、工具、输入/输出格式、边界
fromSession	boolean	尽力从当前会话历史抽取上下文（session 服务不可用时降级）
name / description	string	可选覆盖；默认由 goal 生成
outputDir	string	输出根；默认 插件 config.outputDir → customSkillDirs[0] → $DSH_HOME/skills
confirm	boolean	false（默认）= 干跑：返回意图抽取 + 澄清问题，不写盘；true = 写盘

流程（对齐上游 Capture Intent 迭代闭环的第 1–2 步）：

1. confirm=false 干跑 → 返回从 goal / 会话抽取的 steps / tools / formats / gaps 与澄清问题（缺口处让用户补）；
2. 确认后 confirm=true → 生成 SKILL.md（frontmatter name + description + 正文结构：Workflow / Inputs and outputs / Boundaries / Example）并写入，同时返回挂载提示。

写盘遵守 DSH 读改写策略：覆盖已存在文件前先读取（见 src/lib/fs-adapter.ts 的 serviceHostFs.writeText）。

2.2 skill_validate — 校验已有技能目录

参数 path（必填）。逐项 PASS/FAIL 检查（报错文案对齐上游 validate_skill()）：

1. SKILL.md exists — 文件必须存在；
2. SKILL.md readable — 可读；
3. frontmatter — 必须有 --- ... --- 且能解析为 YAML mapping；
4. name / description — 必须为非空字符串；
5. name — 必须匹配 DSH kebab-case 命名 ^[a-z0-9]+(?:-[a-z0-9]+)*$；
6. body — 正文非空（信息性检查）。

返回：{ ok, checks: [{ item, ok, message }], summary }。

2.3 skill_package — 打包 .skill（zip）

参数：path（必填）、outDir（可选，默认技能目录的父目录）。打包前先跑 skill_validate，校验失败拒绝打包。

排除规则（移植自上游 package_skill.py）：__pycache__/、node_modules/（任意深度）、*.pyc（任意深度）、.DS_Store（任意深度）、技能根级 evals/（仅根级；深层 evals 保留）。

产物结构：<skill-name>/ + 内容，输出 <outDir>/<skill-name>.skill。zip 使用 store 方式（src/lib/zip.ts 内建最小 ZIP 读写，零依赖，便于离线测试与验证）。

2.4 skill_improve_description — 改写 description 提高触发率

参数：path（必填）、usage（必填，触发场景样例）、commit（默认 false）。

• commit=false：返回改写稿 proposed + 逐条 reasons + preserved（保留的原始触发词）/ added（新增场景词）。改写引擎保留原始触发场景覆盖（每个原始触发词仍出现在改写稿中）。
• commit=true：把审核通过的改写稿写回 SKILL.md 的 frontmatter description（仅替换该行，其余字段与正文逐字节不变；写回前先读取）。

配合 DSH 常规交互：模型先拿提案给用户确认，再以 commit=true 落盘。

---

3. 目录与交付物

dsh-skill-creator/
├── cordis.yml                  # bundle 层：插入 skill-creator 插件行
├── package.json                # dsh.bundle 清单（patch: ./cordis.yml）
├── tsconfig.json               # TypeScript 构建配置（rewrite .ts → .js）
├── LICENSE                     # MIT
├── src/
│   ├── index.ts                # 插件装配：声明 Config/apply，注册 4 工具 + 输出目录挂载
│   ├── tools/
│   │   ├── skill-new.ts
│   │   ├── skill-validate.ts
│   │   ├── skill-package.ts
│   │   └── skill-improve-description.ts
│   └── lib/                    # 零依赖核心（工具与冒烟测试共用）
│       ├── skill-name.ts       # kebab-case 校验与 slug
│       ├── frontmatter.ts      # 最小 YAML frontmatter 解析/生成/字段原地替换
│       ├── fs-adapter.ts       # HostFs：ctx.fs 服务优先，回退 Node；写前先读
│       ├── tool-spec.ts        # 工具规格类型（defineTool 适配层）
│       ├── validate-skill.ts   # skill_validate 核心
│       ├── zip.ts              # 最小 ZIP 读写（store + CRC-32）
│       ├── package-skill.ts    # skill_package 核心（排除规则）
│       ├── draft.ts            # skill_new 核心（意图抽取/澄清问题/草稿生成）
│       ├── improve.ts          # skill_improve_description 核心（改写+提交）
│       ├── provider.ts         # 输出目录运行期 skill provider（挂载机制）
│       └── tool-env.ts         # 输出根解析、mountHint、会话尾部抽取
├── scripts/
│   ├── quick_validate.py       # 移植自上游 quick_validate.py 的校验规则（PyYAML，权威校验）
│   └── package_skill.py        # 移植自上游 package_skill.py 的打包规则（zipfile）
├── tests/
│   └── smoke.e2e.ts            # 离线冒烟测试：4 个工具主路径 + 验收标准
└── README.md

TS 侧校验器 src/lib/frontmatter.ts 实现的是文档化 YAML 子集（块映射、嵌套缩进、引号标量、块标量、行内列表等），与 scripts/quick_validate.py（PyYAML 全量解析）检查项一致、互为印证；生成文件只使用该子集，故两者判定等价。

---

4. 验收标准对照

验收标准	落实位置
1. 生成技能可被 ctx.skills 列出并加载	skill_new 写盘 → 运行期 provider（lib/provider.ts）暴露给 skills 注册表；冒烟测试用 OutputDirSkillSource.list()/get() 验证
2. skill_validate 对三类样本正确判定	lib/validate-skill.ts + 冒烟测试（缺文件/缺 frontmatter/非法名/正常）
3. 打包 zip 不含排除项、结构 = 技能名/ + 内容	lib/package-skill.ts + scripts/package_skill.py；冒烟测试用内建 zip 读取回验，Python 侧用 unzip -l 验证
4. 改写保留原始触发场景覆盖	lib/improve.ts（preserved ⊆ proposed）+ 冒烟测试逐词断言
5. 冒烟测试覆盖 4 工具主路径	tests/smoke.e2e.ts（45 条断言，离线通过）

---

5. 运维与限制

• 最小 YAML 子集：src/lib/frontmatter.ts 不解析复杂 YAML（锚点、多文档、嵌套序列等会报 invalid YAML frontmatter 或保守解析）。权威校验以 scripts/quick_validate.py（PyYAML）为准。
• 挂载优先级：运行期 provider 的 rank=300（custom 层），项目根（rank 100/200）同名技能优先；与技能注册表默认行为一致。
• 二进制写盘：.skill 产物与目录创建走 Node（fs 服务为文本只写）；若部署环境限制插件写盘，请把 outputDir 指向允许的路径并配置 skill-filesystem.customSkillDirs。
• fromSession 为尽力而为：读取不到 session 服务时仅按 goal 抽取并在结果中注明。
• model 改写：本版本描述改写使用确定性规则引擎（离线可测、可复现）；对更强的语义改写，可在 src/lib/improve.ts 中注入模型完成器（当前不引入 LLM 运行时依赖）。

---

6. 上游移植说明

上游（Proprietary）	本项目（MIT）
scripts/quick_validate.py 校验规则与报错风格	scripts/quick_validate.py（重写）+ src/lib/validate-skill.ts（TS 移植）
scripts/package_skill.py 排除规则与"先校验后打包"	scripts/package_skill.py（重写）+ src/lib/package-skill.ts（TS 移植）
Capture Intent（步骤/工具/格式抽取 + 澄清问题）	src/lib/draft.ts（确定性启发式，行为对齐）
improve_description.py description 优化	src/lib/improve.ts（保留触发覆盖的改写引擎）
迭代闭环（草稿→测试→评估→重写）	由使用方（会话中的模型）通过 4 个工具编排复现

src/lib/zip.ts、src/lib/frontmatter.ts、src/lib/fs-adapter.ts、src/lib/provider.ts 为本项目新增实现（无上游对应源码）。