dsh-skill-importer 0.1.2 → 0.2.1

package/README.md

@@ -26,7 +26,7 @@
 
 | Import | Organize | Invoke |
 | :--- | :--- | :--- |
-| Upload `SKILL.md` or paste a URL. Frontmatter is validated and normalized before writing. | Browse skills grouped across project, legacy project, and global roots. Remove any copy individually. | Use the composer picker, run `/skills`, or type `/skill-name` directly. |
+| Upload `SKILL.md`, paste a URL, or migrate a complete skills directory from Claude Code, Codex, and similar agents. | Browse skills grouped across project and global roots. Remove any copy individually. | Use the composer picker, run `/skills`, or type `/skill-name` directly. |
 
 ### Built for a fast loop
 
@@ -37,6 +37,12 @@
 - **Bilingual UI** — English and Chinese copy follows the harness locale.
 - **Safe by design** — fixed skill roots, 256 KB limit, and same-origin POST checks.
 
+### Batch migration with a real preflight
+
+The third import entry accepts a local skills root such as `~/.claude/skills`, `~/.codex/skills`, or another `.agents/skills` directory. It scans before it writes, validates every `SKILL.md`, preserves each skill's `scripts`, `references`, `assets`, and other resources, and reports invalid entries without touching the destination.
+
+Destination name conflicts are skipped by default. Choose **Replace** per skill, review the add/replace/skip summary, then confirm. Each accepted skill is copied through a same-root staging directory; replacements keep a temporary backup and roll back if the swap fails. A preflight is single-use, expires after ten minutes, and verifies source-content fingerprints again at commit time.
+
 ## Three natural ways to use a skill
 
 1. **Composer picker** — open the pill beside the access-mode selector, search by name, and choose.
@@ -47,26 +53,68 @@ All three fill the composer with the same highlighted `/name ` gesture; sending
 
 ## Installation
 
-### 1. Add the plugin to the Web profile
+### First install
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@latest
+```
+
+The plugin registers itself with the Web profile through `dsh.bundle`; do not edit `cordis.patch.yml` manually.
+
+Restart dsh Web after installation:
 
 ```sh
-dsh plugin --profile web add dsh-skill-importer
+npx @deepseek-ai/dsh web
 ```
 
-### 2. Enable it in the profile
+### Update to the latest version
 
-Add the following entry to `$DSH_HOME/profiles/web/cordis.patch.yml`:
+Existing users can run the same command to update:
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@latest
+```
+
+Updating replaces only the plugin package. It does not remove project skills in `.agents/skills` or global skills in `~/.dsh/skills`. Restart dsh Web after updating.
+
+Check the latest published version:
+
+```sh
+npm view dsh-skill-importer version
+```
+
+List the plugins installed in the Web profile:
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web list
+```
+
+#### Supply-chain waiting period for new releases
+
+DSH profiles use pnpm to manage plugins. pnpm's `minimumReleaseAge` policy delays newly published versions; during that window, `@latest` may still resolve to the previous mature release. This is an intentional supply-chain safeguard, not a download failure. The recommended path is to wait for the profile's configured window, then rerun the `@latest` command above.
+
+Pre-1.0 semver ranges also stop at the next minor: for example, `^0.1.2` does not include `0.2.0`. After the waiting period, specify the target version when crossing a minor:
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@X.Y.Z
+```
+
+If you have verified the release and must install it immediately, add a temporary exception for that **exact version** to `$DSH_HOME/profiles/web/pnpm-workspace.yaml`, then run the exact-version command:
 
 ```yaml
-- id: skill-importer
-  name: dsh-skill-importer
+minimumReleaseAgeExclude:
+  - dsh-skill-importer@X.Y.Z
 ```
 
-### 3. Restart dsh Web
+Replace both `X.Y.Z` placeholders with the same target version. This opts that version out of the supply-chain waiting period. Do not permanently exempt the package name; remove the exact-version exception after the release matures.
+
+Open **Settings → Skills**. Import a Markdown file or URL, or choose **Batch import** to migrate another agent's complete skills directory. Choose a target and the imported skills will appear as soon as the filesystem watcher discovers them.
+
+> Requires DeepSeek Harness `>= 0.1.0-rc.6`.
 
-Open **Settings → Skills**. Import a Markdown file or URL, choose a target, and the skill will appear as soon as the filesystem watcher discovers it.
+### Duplicate plugin after upgrading
 
-> Requires DeepSeek Harness `>= 0.1.0-rc.6` via `npx @deepseek-ai/dsh web`.
+If startup fails with `duplicate loader entry id: skill-importer`, the profile still contains the old manual configuration. Remove the manually added `skill-importer` entry from `$DSH_HOME/profiles/web/cordis.patch.yml`, then restart dsh Web. Current releases register automatically and do not need that entry.
 
 ## How it works
 
@@ -90,7 +138,6 @@ POST routes verify the `Origin` header and only accept loopback sources (`127.0.
 | Scope | Directory |
 | :--- | :--- |
 | Project | `.agents/skills` |
-| Legacy project | `.dsh/skills` |
 | Global | `~/.dsh/skills` |
 
 ## Development
@@ -109,7 +156,7 @@ npm run build
 | Composer picker | `src/client/SkillsPicker.tsx` |
 | Settings experience | `src/client/SkillImporterSection.tsx` |
 
-Available routes: `GET /skill-importer/health` · `GET /skill-importer/list` · `POST /skill-importer/import` · `POST /skill-importer/import-url` · `POST /skill-importer/delete`
+Available routes: `GET /skill-importer/health` · `GET /skill-importer/list` · `POST /skill-importer/import` · `POST /skill-importer/import-url` · `POST /skill-importer/delete` · `POST /skill-importer/batch/scan` · `POST /skill-importer/batch/commit`
 
 ### Local checkout
 
@@ -119,12 +166,13 @@ npm run build
 dsh plugin --profile web add /path/to/dsh-skill-importer
 ```
 
-Add the profile entry shown above, then restart dsh Web.
+If `dsh` is not installed globally, replace the last line with `npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-skill-importer`. The plugin registers automatically; restart dsh Web afterward.
 
 ## Notes
 
 - A single imported file may be up to 256 KB.
-- URL import preserves `.md` sources; HTML pages use lightweight text extraction, so direct Markdown URLs work best.
+- Batch import accepts `.claude/skills`, `.codex/skills`, `.agents/skills`, `.dsh/skills`, or one skill directory directly below those roots. A scan accepts up to 200 skills; each skill may contain up to 2,000 files and 10 MB of resources. Symbolic links are refused.
+- URL import is HTTPS-only and refuses loopback, private, link-local, and reserved addresses; every redirect is validated again. `.md` sources are preserved, while HTML pages use lightweight text extraction, so direct Markdown URLs work best.
 - The installed list polls briefly after import (every 2 seconds for up to 20 seconds). **Refresh** syncs external changes immediately.
 
 ## License

package/README.zh.md

@@ -26,7 +26,7 @@
 
 | 导入 | 管理 | 调用 |
 | :--- | :--- | :--- |
-| 上传 `SKILL.md` 或粘贴 URL，写入前自动校验并规范化 frontmatter。 | 按项目、旧版项目和全局目录分组查看，每个副本都能独立删除。 | 使用输入框选择器、运行 `/skills`，或直接输入 `/skill-name`。 |
+| 上传 `SKILL.md`、粘贴 URL，或从 Claude Code、Codex 等 Agent 的技能目录完整迁移。 | 按项目和全局目录分组查看，每个副本都能独立删除。 | 使用输入框选择器、运行 `/skills`，或直接输入 `/skill-name`。 |
 
 ### 为高速工作流而生
 
@@ -37,6 +37,12 @@
 - **中英双语** — UI 文案自动跟随 harness 语言。
 - **安全边界清晰** — 固定技能目录、256 KB 限制、同源 POST 校验。
 
+### 带完整预检的批量迁移
+
+第三个导入入口支持选择 `~/.claude/skills`、`~/.codex/skills` 或其他 `.agents/skills` 目录。写入前会扫描并校验每个 `SKILL.md`，同时完整保留技能的 `scripts`、`references`、`assets` 等资源；不合规项只展示错误，绝不会写入目标目录。
+
+目标中存在同名技能时默认跳过。用户可逐项勾选「替换」，检查新增、替换和跳过数量后再确认。每个技能先复制到目标根目录下的临时目录；替换时会暂存旧版本，交换失败自动回滚。扫描结果只能提交一次、十分钟后过期，并在提交时重新核对源内容摘要。
+
 ## 三种自然的技能入口
 
 1. **输入框选择器** — 点击权限模式旁边的 pill，按名称搜索并选中。
@@ -47,26 +53,68 @@
 
 ## 安装
 
-### 1. 安装到 Web profile
+### 首次安装
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@latest
+```
+
+插件通过 `dsh.bundle` 自动注册到 Web profile，无需手动修改 `cordis.patch.yml`。
+
+安装完成后重启 dsh Web：
 
 ```sh
-dsh plugin --profile web add dsh-skill-importer
+npx @deepseek-ai/dsh web
 ```
 
-### 2. 在 profile 中启用
+### 更新到最新版
 
-向 `$DSH_HOME/profiles/web/cordis.patch.yml` 添加：
+已安装用户执行同一条命令即可更新：
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@latest
+```
+
+更新只会替换插件包，不会删除 `.agents/skills` 中的项目技能或 `~/.dsh/skills` 中的全局技能。更新后请重启 dsh Web。
+
+查看 npm 上的最新版本：
+
+```sh
+npm view dsh-skill-importer version
+```
+
+查看 Web profile 中已安装的插件：
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web list
+```
+
+#### 新版本的安全等待期
+
+DSH profile 使用 pnpm 管理插件。pnpm 会按 `minimumReleaseAge` 暂缓安装刚发布的版本；在等待期内，`@latest` 可能仍解析到上一个已成熟版本。这是供应链保护机制，不是下载失败。推荐等待 profile 配置的时间窗口结束后，再执行上面的 `@latest` 命令。
+
+`0.x` 版本还遵循特殊的 semver 范围：例如 `^0.1.2` 不包含 `0.2.0`。跨 minor 更新时可在等待期结束后明确指定目标版本：
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add dsh-skill-importer@X.Y.Z
+```
+
+如果已经核验该版本并且必须立即安装，可在 `$DSH_HOME/profiles/web/pnpm-workspace.yaml` 中为这个**精确版本**添加临时信任例外，再执行精确版本命令：
 
 ```yaml
-- id: skill-importer
-  name: dsh-skill-importer
+minimumReleaseAgeExclude:
+  - dsh-skill-importer@X.Y.Z
 ```
 
-### 3. 重启 dsh Web
+将两处 `X.Y.Z` 替换为同一个目标版本。这会绕过该版本的供应链等待期，不建议把包名永久加入例外列表。版本成熟后可以删除这条例外。
+
+打开 **设置 → 技能**，选择 Markdown 文件、粘贴 URL，或通过「批量导入」迁移其他 Agent 的完整技能目录，再选择目标范围。文件系统 watcher 发现后，技能会立即出现。
+
+> 需要 DeepSeek Harness `>= 0.1.0-rc.6`。
 
-打开 **设置 → 技能**，选择 Markdown 文件或粘贴 URL，再选择目标目录。文件系统 watcher 发现后，技能会立即出现。
+### 旧配置导致重复插件
 
-> 需要 DeepSeek Harness `>= 0.1.0-rc.6`，使用 `npx @deepseek-ai/dsh web` 运行。
+如果启动时报错 `duplicate loader entry id: skill-importer`，说明 profile 中还保留了旧版手动配置。请从 `$DSH_HOME/profiles/web/cordis.patch.yml` 删除手动添加的 `skill-importer` 条目，再重启 dsh Web。当前版本会自动注册，不需要保留该条目。
 
 ## 工作原理
 
@@ -85,12 +133,11 @@ Markdown 文件或 URL
 skills/change → 热刷新
 ```
 
-所有 POST 路由都会校验 `Origin`，仅接受 loopback 来源（`127.0.0.1` 或 `localhost`）。写入范围固定为三个标准目录：
+所有 POST 路由都会校验 `Origin`，仅接受 loopback 来源（`127.0.0.1` 或 `localhost`）。写入范围固定为两个标准目录：
 
 | 范围 | 目录 |
 | :--- | :--- |
 | 项目 | `.agents/skills` |
-| 旧版项目 | `.dsh/skills` |
 | 全局 | `~/.dsh/skills` |
 
 ## 开发
@@ -109,7 +156,7 @@ npm run build
 | 输入框技能选择器 | `src/client/SkillsPicker.tsx` |
 | 设置页 | `src/client/SkillImporterSection.tsx` |
 
-路由一览：`GET /skill-importer/health` · `GET /skill-importer/list` · `POST /skill-importer/import` · `POST /skill-importer/import-url` · `POST /skill-importer/delete`
+路由一览：`GET /skill-importer/health` · `GET /skill-importer/list` · `POST /skill-importer/import` · `POST /skill-importer/import-url` · `POST /skill-importer/delete` · `POST /skill-importer/batch/scan` · `POST /skill-importer/batch/commit`
 
 ### 本地源码安装
 
@@ -119,12 +166,13 @@ npm run build
 dsh plugin --profile web add /path/to/dsh-skill-importer
 ```
 
-随后添加上文的 profile 配置并重启 dsh Web。
+如果没有全局 `dsh` 命令，可将最后一行替换为 `npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-skill-importer`。插件会自动注册，随后重启 dsh Web 即可。
 
 ## 注意事项
 
 - 单个导入文件最大 256 KB。
-- URL 导入会原样保留 `.md`；HTML 页面仅做轻量正文提取，因此推荐使用 Markdown 直链。
+- 批量导入仅接受 `.claude/skills`、`.codex/skills`、`.agents/skills`、`.dsh/skills` 或其中的单个技能目录；每次最多扫描 200 个技能，单个技能最多包含 2,000 个文件和 10 MB 资源，不接受符号链接。
+- URL 导入仅支持 HTTPS，并拒绝本机、私有网络、链路本地和保留地址；每次重定向都会重新校验。`.md` 会原样保留，HTML 页面仅做轻量正文提取，因此推荐使用 Markdown 直链。
 - 导入后列表会短暂轮询（每 2 秒一次，最多 20 秒）；外部改动可点击 **刷新** 立即同步。
 
 ## License