MoYuSOwO/dsh-provision

dsh-provision

面向 DeepSeek Harness 配置文件的清单驱动式置备工具。
一份清单即可声明所有资产——插件、技能、智能体预设、MCP 服务器——provision.py 会同步全部内容：上游跟踪、构建、注册、规划与回滚。

中文说明 · MIT

功能简介

DSH 配置文件资产来源众多（npm 包、GitHub 仓库、技能集合、智能体预设、自建插件）。dsh-provision 是所有这些资产的唯一可信来源：

- 一份清单（manifest.yml）记录每个资产的来源、版本、构建方式和注册信息——无需再手动编辑 package.json / cordis.patch.yml 的托管区段。
- 六种资产来源：npm（注册表包）、github（克隆 → 构建 → 安装）、release（GitHub Release 压缩包，无需构建）、skill（SKILL.md 集合 → 自动生成入口+路由插件）、preset（智能体预设 → ~/.dsh/.agent-presets/）、local（自建，仅注册）。
- 技能提取：技能仓库会被克隆，子技能被提取，并自动生成“入口技能 + 引用路由”插件——入口技能显示在目录中，子技能通过 read 按需加载。
- MCP 注册：清单中声明的 MCP 服务器会由 --patch 写入配置文件补丁的托管区段。
- 安全性：改动前可用 --plan 试运行查看差异，具备冲突检测（重复入口 id、无法解析的 bundle、重复 MCP 名称），以及通过 --rollback 实现的自动事务性备份。
- 快速：对超大仓库使用稀疏检出，--fast 增量模式（按上游提交跳过未变更的资产），在 versions.yml 中跟踪版本/提交。

快速开始

cd ~/.dsh/provision
uv sync                                  # 首次运行：安装依赖（pyyaml）
cp manifest.example.yml manifest.yml     # 首次运行：基于模板构建你的资产清单
uv run python provision.py --check       # 只读状态检查（包含冲突警告）
uv run python provision.py --sync --fast # 增量同步（无变更时仅需数秒）

manifest.yml / ASSETS.md / versions.yml / .cache/ / .backups/ 均已加入 gitignore——
你的个人配置永远不会被发布。仓库提供 manifest.example.yml 作为模板。

用法

uv run python provision.py --check            # 所有资产的状态（只读，包含冲突警告）
uv run python provision.py --plan             # 试运行：显示组装将产生的差异（不执行）
uv run python provision.py --sync             # 完整同步（克隆/构建/提取/安装/生成补丁，自动备份）
uv run python provision.py --sync --fast      # 增量：跳过未变更的上游；无变更时跳过组装
uv run python provision.py --sync --asset latex    # 同步单个资产（允许多个 id）bash
uv run python provision.py --install          # 仅重写依赖 + pnpm install
uv run python provision.py --patch            # 重新生成 profile patch 托管段（MCP）
uv run python provision.py --backups          # 列出事务性备份点
uv run python provision.py --rollback    # 从 .backups/ 恢复 package.json/patch 并重新安装

事务：每次组装（--sync / --install / --patch）都会先将
package.json / cordis.patch.yml / pnpm-lock.yaml 备份到 .backups//；
--rollback  会恢复并重新安装。--plan 会在你提交任何更改之前显示差异。

资产来源

| 来源 | 含义 | 同步操作 |
|---|---|---|
| npm | 注册表包（monorepo 子包 / 原生构建） | 在组装期间通过 pnpm 安装 |
| github | 单仓库插件；克隆，可选构建 | 克隆 → 构建 → 复制到 plugins/，file: 依赖 + bundle |
| release | GitHub Release tarball，预构建（源码构建需要特殊环境的项目） | 下载 → 解压 → 复制到 plugins/ |
| skill | 技能集合仓库（SKILL.md 集合） | 克隆 → 提取技能 → 生成“入口 + 引用路由”插件 |
| preset | agent 预设（agent.cordis.yml / preset.yml） | 克隆 → 复制到 ~/.dsh/.agent-presets/（不是依赖） |
| local | 自建插件 | 仅注册，从不改动 |

技能资产如何生成

每个技能资产会生成一个插件包 plugins/dsh-/：

dsh-/
├── package.json          # name/dsh.bundle.patch → cordis.patch.yml
├── index.js              # skills provider：注册入口技能
├── cordis.patch.yml      # 插入行（插件通过 bundles 组装）
└── skills/
├── /SKILL.md  # 入口技能（在目录中可见），引导读取引用
└── references//  # 子技能原始文件（带有自己的资源）

入口 SKILL.md 带有一条“dsh 适配”说明：$name / namespace:name 引用会解析为
skills/references//SKILL.md —— 需要时读取该文件并遵循其说明。

添加 / 修改资产

1. 编辑 manifest.yml：将仓库添加到 repos（如果是新仓库），向 assets 添加一行，向 mcp 添加 MCP 服务器。
2. uv run python provision.py --sync --asset （单个）或 --sync（全部）。
3. 完整的 --sync 会重写 profile 依赖，运行 pnpm install，并重新生成 patch 托管段。

自建（local）插件直接在 plugins/ 中编辑 —— 同步永远不会覆盖它们。

注意事项

- manifest.yml 是唯一事实来源；package.json 和 cordis.patch.yml 的托管段是生成的，会被覆盖。
- 组装后，重启 dsh web（技能/预设需要新会话）以使更改生效。
- 完整的 --sync 会重新运行 pnpm install（file: 依赖是副本，必须重新安装；provision 会自动处理清除）。
- versions.yml 按每次同步记录上游提交，以供回滚参考。