@ninkch/dsh-infinite-canvas 0.17.0 → 0.17.2

package/cordis.patch.yml

@@ -1,4 +1,4 @@
-- insert:
-    - id: infinite-canvas
-      name: '@ninkch/dsh-infinite-canvas'
-      config: {}
+- insert:
+    - id: infinite-canvas
+      name: '@ninkch/dsh-infinite-canvas'
+      config: {}

package/docs/artcraft-handoff.md

@@ -1,110 +1,110 @@
-# ArtCraft ↔ 无限画布 对接手册（画布侧需求书）
-
-> 供 dsh-artcraft 侧对照实施/实测。本文只描述**画布侧发起的调用与期望**，
-> 契约基础：`dsh-artcraft/README.md`（已实现并验证其 HTTP 形状）。
-> 画布侧代码：`dsh-infinite_canvas/client.js`（dsh-infinite-canvas v0.16+）中 `craft*` 相关段。
-
-## 1. 环境配置（artcraft.config.json）
-
-```jsonc
-{
-  "dataRoot": "C:/craft-workspace",          // 任意可写目录；画布按 <dataRoot>/<项目slug>/ 隔离
-  "bins": {
-    "photocraft":  "C:/craft/photocraft-...-portable",   // 目录（自动拼 photocraft-cli.exe）或完整 exe 或 PATH 裸名
-    "filmcraft":   "C:/craft/filmcraft-...-portable",
-    "effectcraft": "C:/craft/effectcraft-...-portable"
-  },
-  "control": { "filmcraft": 9876, "effectcraft": 9877 } // 仅 P2 控制通道模式需要
-}
-```
-
-- 画布对 bins.*.found 的判定完全信任 `GET /artcraft/api/status`；`note` 字段会原文展示给用户（红灯原因）。
-- `dataRoot.path` 会被拼进 FCP7 XML 的 `file://localhost/` 绝对引用——**必须是 FilmCraft 能访问的本机绝对路径**。
-
-## 2. 画布会发起的 HTTP 调用（逐条）
-
-| # | 调用 | 触发时机 | 画布侧超时 | 期望响应 |
-|---|---|---|---|---|
-| 1 | `GET /api/status` | 设置卡片/各 Craft 入口挂载时（静默探测） | 20s | `dataRoot.path/exists`、`bins.*.found/note` |
-| 2 | `POST /api/fs?action=write&rel=…` | 资产同步 / timeline.xml / srt / grade.json | 180s | `{ok,rel,size}`；**body 为原始 Blob**（视频可达数十 MB） |
-| 3 | `POST /api/job` | PhotoCraft 处理 / FilmCraft 导出 | 30s | `{id,…}` |
-| 4 | `GET /api/job?id=…&tail=…` | 轮询（PhotoCraft 1.5s / FilmCraft 2s） | 20s | `{status,stdout,stderr,outputs:[{rel,exists,size}]}` |
-| 5 | `POST /api/job/cancel` | 用户点取消 | 20s | 任意 |
-| 6 | `GET /api/file?rel=…` | 回收产物（graded 图 / final.mp4） | 180s | 原始字节 + 按扩展名 content-type |
-
-- rel 一律**相对 dataRoot、正斜杠、无前导 /**，形如 `<项目slug>/media/…`。
-- 画布在 status 不可达/404 时全部 Craft 入口置灰并提示，不会发后续调用。
-
-## 3. 画布发起的确切 CLI 命令行（cwd = dataRoot）
-
-### 3.1 PhotoCraft 单图处理（T4，已实现）
-
-```
-photocraft-cli run <项目slug>/media/<assetId>.<ext> --cmd <命令ID> --params <JSON字符串> --out <项目slug>/out/graded/<assetId>-graded<ext>
-```
-
-- 已内置命令（下拉可选，用户可自定义任意 cmd）：
-  - `filter.sharpen.smartSharpen`，params `{"amount":80}`
-  - `layer.newAdjustmentLayer.curves`，params `{"points":[[0,0],[64,48],[192,212],[255,255]]}`
-- **需实测确认**：`run` 子命令是否存在；`--params` 是字符串还是文件；`--out` 是文件还是目录；处理 PNG/WEBP 输入是否支持。
-
-### 3.2 PhotoCraft 批量（配方已确认，UI 未接）
-
-```
-photocraft-cli batch --actions <项目slug>/craft/grade.json --in <项目slug>/media --out <项目slug>/out/graded
-```
-
-grade.json：`{ "actions": [ { "cmd": "...", "params": {...} }, … ] }`
-
-### 3.3 FilmCraft 导出（T5，**待实测回填**）
-
-画布写入两个文件后发起（args 为 JSON 数组，用户可在确认框编辑）：
-
-```
-写入 <项目slug>/craft/timeline.xml   （FCP7 XML xmeml v1，单视频轨顺序片段）
-写入 <项目slug>/craft/subs.srt       （按片段顺序的字幕）
-然后：
-filmcraft-cli --project <项目slug>/craft/drama.fcproj --import <项目slug>/craft/timeline.xml --export <项目slug>/out/final.mp4
-```
-
-**需实测回填的问题**：
-1. `--project` 指向的 `.fcproj` 不存在时是否自动创建？还是需要先 `init`？
-2. 导入时间线的确切子命令形态（`--import` 一次调用？还是 `import` 子命令 + `export` 子命令两步）？
-3. `--export` 的格式参数（h264 预设名/质量参数/CRF？音频是否自动混入源片段音轨？）
-4. xmeml 的 `<pathurl>file://localhost/…` 引用是否能自动 relink 到 media/ 下文件（含中文/空格/URL 编码）？
-5. 字幕：是否支持 `--subs <srt>` 之类参数烧录/挂载？（画布已生成 subs.srt，参数确定后追加）
-
-### 3.4 EffectCraft（T6 骨架，画布 UI 未接）
-
-```
-effectcraft-cli render --comp Main --out <项目slug>/out/intro.mp4 <项目slug>/craft/intro.ecproj
-```
-
-## 4. 目录与命名约定（画布侧已实现，artcraft 无需感知，但排错时有用）
-
-```
-<dataRoot>/<项目slug>/
-  media/<assetId><ext>        画布资产（ext 由 mime/name 推断：png/jpg/webp/webm/mp4/mp3/wav）
-  craft/timeline.xml          FCP7 XML（xmeml v1，30fps，单视频轨）
-  craft/subs.srt              成片字幕（与片段顺序一致）
-  craft/grade.json            （批量调色预留）
-  out/graded/<assetId>-graded<ext>
-  out/final.mp4
-```
-
-- `<项目slug>`：项目名去掉 `\/:*?"<>|` 后保留中文；重名冲突加 `-<项目id尾4>` 后缀；slug 一经分配稳定不变（映射画布侧持久化）。
-- 同名重复同步 = **覆盖写**（幂等）。
-
-## 5. 退出码与错误约定（画布轮询依赖）
-
-- 退出码 0 → 画布判 `done`，按 `outputs[].exists` 决定是否回收；非 0 → `failed`，画布展示 **stderr 尾 3 行**。
-- CLI 必须：无交互、headless 可跑、错误写 stderr、成功写 stderr/stdout 的进度行（画布把 stdout 尾行显示为进度）。
-- 任务超时由画布提交时的 `timeoutMs` 控制（photocraft 10min / filmcraft 30min），artcraft 侧默认值被覆盖。
-
-## 6. 联调流程建议
-
-1. `artcraft.config.json` 配好三 bins + dataRoot → `GET /api/status` 三绿灯。
-2. 画布资产页点"同步全部资产到磁盘"→ 检查 `<dataRoot>/<项目>/media/` 出现文件。
-3. 资产卡 → PhotoCraft 处理 → 选"智能锐化" → 开始处理 → 确认 `out/graded/` 产物入库。
-4. 搭一个最小分镜流（2 个视频片段）→ 成片节点 FilmCraft 导出 → 用 `artcraft_cli {bin:"filmcraft",args:["commands"]}`（或本地 `filmcraft-cli commands`）核对 3.3 的五个问题 → 回填确认框默认 args。
-5. 全绿后把实测参数发回画布侧更新默认模板。
+# ArtCraft ↔ 无限画布 对接手册（画布侧需求书）
+
+> 供 dsh-artcraft 侧对照实施/实测。本文只描述**画布侧发起的调用与期望**，
+> 契约基础：`dsh-artcraft/README.md`（已实现并验证其 HTTP 形状）。
+> 画布侧代码：`dsh-infinite_canvas/client.js`（dsh-infinite-canvas v0.16+）中 `craft*` 相关段。
+
+## 1. 环境配置（artcraft.config.json）
+
+```jsonc
+{
+  "dataRoot": "C:/craft-workspace",          // 任意可写目录；画布按 <dataRoot>/<项目slug>/ 隔离
+  "bins": {
+    "photocraft":  "C:/craft/photocraft-...-portable",   // 目录（自动拼 photocraft-cli.exe）或完整 exe 或 PATH 裸名
+    "filmcraft":   "C:/craft/filmcraft-...-portable",
+    "effectcraft": "C:/craft/effectcraft-...-portable"
+  },
+  "control": { "filmcraft": 9876, "effectcraft": 9877 } // 仅 P2 控制通道模式需要
+}
+```
+
+- 画布对 bins.*.found 的判定完全信任 `GET /artcraft/api/status`；`note` 字段会原文展示给用户（红灯原因）。
+- `dataRoot.path` 会被拼进 FCP7 XML 的 `file://localhost/` 绝对引用——**必须是 FilmCraft 能访问的本机绝对路径**。
+
+## 2. 画布会发起的 HTTP 调用（逐条）
+
+| # | 调用 | 触发时机 | 画布侧超时 | 期望响应 |
+|---|---|---|---|---|
+| 1 | `GET /api/status` | 设置卡片/各 Craft 入口挂载时（静默探测） | 20s | `dataRoot.path/exists`、`bins.*.found/note` |
+| 2 | `POST /api/fs?action=write&rel=…` | 资产同步 / timeline.xml / srt / grade.json | 180s | `{ok,rel,size}`；**body 为原始 Blob**（视频可达数十 MB） |
+| 3 | `POST /api/job` | PhotoCraft 处理 / FilmCraft 导出 | 30s | `{id,…}` |
+| 4 | `GET /api/job?id=…&tail=…` | 轮询（PhotoCraft 1.5s / FilmCraft 2s） | 20s | `{status,stdout,stderr,outputs:[{rel,exists,size}]}` |
+| 5 | `POST /api/job/cancel` | 用户点取消 | 20s | 任意 |
+| 6 | `GET /api/file?rel=…` | 回收产物（graded 图 / final.mp4） | 180s | 原始字节 + 按扩展名 content-type |
+
+- rel 一律**相对 dataRoot、正斜杠、无前导 /**，形如 `<项目slug>/media/…`。
+- 画布在 status 不可达/404 时全部 Craft 入口置灰并提示，不会发后续调用。
+
+## 3. 画布发起的确切 CLI 命令行（cwd = dataRoot）
+
+### 3.1 PhotoCraft 单图处理（T4，已实现）
+
+```
+photocraft-cli run <项目slug>/media/<assetId>.<ext> --cmd <命令ID> --params <JSON字符串> --out <项目slug>/out/graded/<assetId>-graded<ext>
+```
+
+- 已内置命令（下拉可选，用户可自定义任意 cmd）：
+  - `filter.sharpen.smartSharpen`，params `{"amount":80}`
+  - `layer.newAdjustmentLayer.curves`，params `{"points":[[0,0],[64,48],[192,212],[255,255]]}`
+- **需实测确认**：`run` 子命令是否存在；`--params` 是字符串还是文件；`--out` 是文件还是目录；处理 PNG/WEBP 输入是否支持。
+
+### 3.2 PhotoCraft 批量（配方已确认，UI 未接）
+
+```
+photocraft-cli batch --actions <项目slug>/craft/grade.json --in <项目slug>/media --out <项目slug>/out/graded
+```
+
+grade.json：`{ "actions": [ { "cmd": "...", "params": {...} }, … ] }`
+
+### 3.3 FilmCraft 导出（T5，**待实测回填**）
+
+画布写入两个文件后发起（args 为 JSON 数组，用户可在确认框编辑）：
+
+```
+写入 <项目slug>/craft/timeline.xml   （FCP7 XML xmeml v1，单视频轨顺序片段）
+写入 <项目slug>/craft/subs.srt       （按片段顺序的字幕）
+然后：
+filmcraft-cli --project <项目slug>/craft/drama.fcproj --import <项目slug>/craft/timeline.xml --export <项目slug>/out/final.mp4
+```
+
+**需实测回填的问题**：
+1. `--project` 指向的 `.fcproj` 不存在时是否自动创建？还是需要先 `init`？
+2. 导入时间线的确切子命令形态（`--import` 一次调用？还是 `import` 子命令 + `export` 子命令两步）？
+3. `--export` 的格式参数（h264 预设名/质量参数/CRF？音频是否自动混入源片段音轨？）
+4. xmeml 的 `<pathurl>file://localhost/…` 引用是否能自动 relink 到 media/ 下文件（含中文/空格/URL 编码）？
+5. 字幕：是否支持 `--subs <srt>` 之类参数烧录/挂载？（画布已生成 subs.srt，参数确定后追加）
+
+### 3.4 EffectCraft（T6 骨架，画布 UI 未接）
+
+```
+effectcraft-cli render --comp Main --out <项目slug>/out/intro.mp4 <项目slug>/craft/intro.ecproj
+```
+
+## 4. 目录与命名约定（画布侧已实现，artcraft 无需感知，但排错时有用）
+
+```
+<dataRoot>/<项目slug>/
+  media/<assetId><ext>        画布资产（ext 由 mime/name 推断：png/jpg/webp/webm/mp4/mp3/wav）
+  craft/timeline.xml          FCP7 XML（xmeml v1，30fps，单视频轨）
+  craft/subs.srt              成片字幕（与片段顺序一致）
+  craft/grade.json            （批量调色预留）
+  out/graded/<assetId>-graded<ext>
+  out/final.mp4
+```
+
+- `<项目slug>`：项目名去掉 `\/:*?"<>|` 后保留中文；重名冲突加 `-<项目id尾4>` 后缀；slug 一经分配稳定不变（映射画布侧持久化）。
+- 同名重复同步 = **覆盖写**（幂等）。
+
+## 5. 退出码与错误约定（画布轮询依赖）
+
+- 退出码 0 → 画布判 `done`，按 `outputs[].exists` 决定是否回收；非 0 → `failed`，画布展示 **stderr 尾 3 行**。
+- CLI 必须：无交互、headless 可跑、错误写 stderr、成功写 stderr/stdout 的进度行（画布把 stdout 尾行显示为进度）。
+- 任务超时由画布提交时的 `timeoutMs` 控制（photocraft 10min / filmcraft 30min），artcraft 侧默认值被覆盖。
+
+## 6. 联调流程建议
+
+1. `artcraft.config.json` 配好三 bins + dataRoot → `GET /api/status` 三绿灯。
+2. 画布资产页点"同步全部资产到磁盘"→ 检查 `<dataRoot>/<项目>/media/` 出现文件。
+3. 资产卡 → PhotoCraft 处理 → 选"智能锐化" → 开始处理 → 确认 `out/graded/` 产物入库。
+4. 搭一个最小分镜流（2 个视频片段）→ 成片节点 FilmCraft 导出 → 用 `artcraft_cli {bin:"filmcraft",args:["commands"]}`（或本地 `filmcraft-cli commands`）核对 3.3 的五个问题 → 回填确认框默认 args。
+5. 全绿后把实测参数发回画布侧更新默认模板。

package/docs/release.md

@@ -0,0 +1,122 @@
+# 发布与测试流程（Runbook）
+
+> 维护者向导：如何从"本地改动"走到"公众可用的 npm 版本"。
+> 铁律见 §0；测试三层漏斗见 §1；日常操作 §2–§5；更新检查逻辑 §6。
+
+## 0. 铁律（不可违反）
+
+1. **未经用户明确批准，绝不 `npm publish`、绝不合并 main、绝不 `git push origin main`。**
+2. **绝不自动重启 Harness、绝不自动刷新页面。** 更新/安装后只提示（横幅/文案），何时生效由用户决定。
+3. **beta 版本号绝不复用**（npm 本身也禁止覆盖已发布版本）；**正式版本号只在 main 上诞生**。
+4. **版本单一来源 = `package.json`**。改版本一律用 `npm version …`，不手改；Host 运行时读取它，禁止在代码里硬编码版本号。
+5. npm token 只通过命令行注入，**绝不写入任何文件**。
+
+## 1. 测试三层漏斗
+
+| 层 | 目的 | 载体 | 代价 |
+| --- | --- | --- | --- |
+| ① 开发自测 | 验证代码逻辑；改动即时可见 | profile 以 `link:` 符号链接直连本仓库 | 零发布物 |
+| ② Beta 集成测试 | 验证 100% 真实 npm 安装链路（包内容、`dsh.bundle.patch`、安装器行为） | npm prerelease + `--tag next` | 一个公开的 beta 版本号（无害，可留存） |
+| ③ 正式发布 | 公众 `latest` | main 分支 + `npm publish` | 需用户批准 |
+
+三层是递进关系：改动至少过 ①；要发版必须过 ②（除非纯文档改动）。
+
+## 2. 层①：开发自测循环
+
+**切换到开发态**（改动即时生效）：
+
+1. 编辑 `C:\Users\PC\.dsh\profiles\desktop\package.json`：
+   `"@ninkch/dsh-infinite-canvas": "link:D:/code/deepseek-plugin/dsh-infinite_canvas"`
+2. 在该 profile 目录执行 `pnpm install`
+3. **手动重启 Harness**（Host 代码只在重启时加载）
+
+**每轮改动的固定动作**（dev 分支）：
+
+```
+node --check client.js
+node --check index.js
+node scripts/smoke-render.mjs   # 渲染冒烟：抓渲染期 ReferenceError（黑屏级联卸载）
+```
+
+- 仅 client.js 改动 → 刷新页面即生效
+- index.js 改动 → 需手动重启 Harness
+- 测完切回正式版：依赖改回版本号 → `pnpm install` → 重启
+
+## 3. 发布前校验（两个脚本都必须绿）
+
+```
+node scripts/check-pack.mjs     # 打包清单 + 元数据核对（npm pack --dry-run）
+node scripts/smoke-render.mjs   # 渲染冒烟：假 React 走真实组件树
+node scripts/test-update.mjs    # 更新检查功能测试（真实 registry 比对）
+```
+
+`check-pack` 防的三类事故：漏打包（如 locale/icon 没进包）、多打包（`.github`/`scripts` 混入）、元数据漂移（版本/exports/`dsh.bundle.patch`）。
+
+## 4. 层②：Beta 集成测试
+
+```
+# 1) 打 beta 号（每轮自增，绝不复用；dev 分支上操作）
+npm version 0.17.3-beta.0        # 显式指定；或 npm version prerelease --preid=beta
+
+# 2) 提交 beta 号变更到 dev
+git add package.json && git commit -m "chore: v0.17.3-beta.0" && git push origin dev
+
+# 3) 经用户批准后发布到 next 标签（绝不占 latest）
+npm publish --tag next --access public --registry=https://registry.npmjs.org '--//registry.npmjs.org/:_authToken=<TOKEN>'
+
+# 4) 安装测试
+#    在插件管理安装 @ninkch/dsh-infinite-canvas 精确版本 0.17.3-beta.0
+#    → 手动重启 Harness → 冒烟：RPC ping + 页面渲染 + 核心流程
+
+# 5) 回滚（任何问题）：安装回正式精确版本 → 重启，零残留
+```
+
+说明：
+
+- prerelease 排序低于同号正式版，安装器不会把 beta 当"更新"推给正式用户；beta 留在 registry 无害。
+- 清理 next 标签（可选）：`npm dist-tag rm @ninkch/dsh-infinite-canvas next`
+
+## 5. 层③：正式发布（全部需用户批准）
+
+```
+# 1) 合并
+git checkout main
+git merge dev
+git push origin main
+
+# 2) 出正式号（在 main 上打）
+npm version 0.17.3
+git push origin main --follow-tags   # npm version 会自动打 git tag vX.Y.Z
+
+# 3) 发布（两条路任选）
+#    a. GitHub Actions Trusted Publishing（首选，无 token）：GitHub 建 Release vX.Y.Z → Actions 自动发布
+#    b. 手动注入：
+npm publish --access public --registry=https://registry.npmjs.org '--//registry.npmjs.org/:_authToken=<TOKEN>'
+
+# 4) 验证
+npm view @ninkch/dsh-infinite-canvas version   # 应为新版
+GET /infinite-canvas/api/rpc ping               # 安装重启后 version 应为新版
+```
+
+发布完成汇报模板：**"已发布 vX.Y.Z，重启 Harness 后生效"**（绝不替用户重启）。
+
+## 6. 插件内"检查更新"（面向公众的统一逻辑）
+
+与安装方式**完全无关**（npm 在线安装 / 本地 link 开发态 / 其它，同一条逻辑）：
+
+- **当前版本** = 当前加载副本的 `package.json`（Host 启动时读取）
+- **最新版本** = npm registry `…/@ninkch%2Fdsh-infinite-canvas/latest`（即 `latest` dist-tag，beta 不会出现）
+- 本地版本 ≥ 远端 → 视为最新；仅真正落后 → 画布顶部横幅"新版本可用 vX（当前 vY）"
+- 横幅"去升级"按钮 → **仅提示**："请在 DSH 插件管理 中升级…重启 Harness 生效"
+- **绝不自动安装、绝不自动刷新、绝不自动重启**；网络失败静默（手动点击才提示错误）
+
+实现位置：`index.js` `updateCheck()`（RPC `updateCheck`）；文案 key：`updateGo` / `npmUpgradeHint` / `updateCurrent`。
+
+## 7. 发布日检查清单
+
+- [ ] dev 全部改动已提交并推送
+- [ ] `node --check` × 2 + `smoke-render` + `check-pack` 全绿
+- [ ] beta 版实测通过（层②）
+- [ ] **用户明确批准发布**
+- [ ] 合并 main → `npm version` → publish → 确认 registry
+- [ ] 汇报版本号 + "重启 Harness 后生效"

package/icon.svg

@@ -1,8 +1,8 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
-  <rect x="4" y="4" width="56" height="56" rx="14" fill="#4f6bfa"/>
-  <circle cx="21" cy="23" r="5.5" fill="#ffffff"/>
-  <rect x="34" y="36" width="13" height="13" rx="3.5" fill="#ffffff"/>
-  <circle cx="45" cy="19" r="4.5" fill="#ffd66e"/>
-  <path d="M27 22.5 L39.5 19.8" stroke="#ffffff" stroke-width="3" stroke-linecap="round"/>
-  <path d="M24 28 C29 33 29 36 33.5 40.5" stroke="#ffffff" stroke-width="3" fill="none" stroke-linecap="round"/>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect x="4" y="4" width="56" height="56" rx="14" fill="#4f6bfa"/>
+  <circle cx="21" cy="23" r="5.5" fill="#ffffff"/>
+  <rect x="34" y="36" width="13" height="13" rx="3.5" fill="#ffffff"/>
+  <circle cx="45" cy="19" r="4.5" fill="#ffd66e"/>
+  <path d="M27 22.5 L39.5 19.8" stroke="#ffffff" stroke-width="3" stroke-linecap="round"/>
+  <path d="M24 28 C29 33 29 36 33.5 40.5" stroke="#ffffff" stroke-width="3" fill="none" stroke-linecap="round"/>
+</svg>