@ninkch/dsh-artcraft 0.2.6 → 0.2.8

package/README.md

@@ -25,13 +25,13 @@ This plugin brings that surface into DeepSeek Harness, so an AI agent can *opera
 not just talk about them:
 
 - **In chat** — four agent tools let any Harness session check the toolchain, run CLI commands,
-  send control-channel commands to a running app, and read/write files in a dedicated data root.
+  send control-channel commands to a running app, and do bridged file operations.
 - **In the browser** — a same-origin HTTP API (`/artcraft/api/*`) that any Harness web UI can call,
   no CORS, no keys. It was built for [无限画布 / infinite-canvas](../dsh-infinite_canvas/README.md),
   a node-based AI short-drama storyboard canvas, but any front end can use it.
-- **On disk** — one `dataRoot` per machine where assets, project files and rendered output live,
-  laid out per project (`media/ · craft/ · out/`), so generative pipelines and the desktop apps
-  meet on common ground.
+- **Paths belong to the caller** — this plugin is a bridge and owns no data directory. Files read
+  or written go wherever the caller points: chat invocations default to the current conversation
+  workspace (or any path named in the prompt); the canvas writes under its own project folder.
 
 A typical AI short-drama loop looks like this: generate storyboard frames with a model →
 batch color-grade and sharpen them in PhotoCraft → render an animated title in EffectCraft →
@@ -55,7 +55,8 @@ Every step after "generate" runs through this plugin, headless.
   headless edits          cut · grade · mix      Lottie export
        └───────────────────────┴───────────────────────┘
                                ▼
-              <dataRoot>/<project>/{media, craft, out}
+              caller-decided locations (chat → conversation
+              workspace · canvas → its project folder)
 ```
 
 Everything runs locally. No cloud round-trips, no accounts, no telemetry.
@@ -102,19 +103,19 @@ pnpm install --dir C:/Users/<you>/.dsh/profiles/desktop
 > If your Harness build ships a plugin manager UI that installs from a folder, that works too —
 > it ends up writing exactly the two lines above.
 
-**3. Configure** `artcraft.config.json` next to `index.js` (copy from
-`artcraft.config.json.example`; the file is git-ignored and re-read on every request — no restart
-needed for path changes):
+**3. Configure** `artcraft.config.json` (copy from
+`artcraft.config.json.example`). Recommended location: `C:\Users\<you>\.dsh\artcraft.config.json`
+(persists across plugin updates); placing it next to `index.js` also works (legacy). The file is
+re-read on every request — no restart needed for path changes:
 
 ```jsonc
 {
-  "dataRoot": "D:/craft-workspace",              // where assets & renders live
   "bins": {
     // three accepted forms: a directory (the <name>-cli binary is appended),
     // a full path to the executable, or a bare name looked up on PATH
     "photocraft":  "C:/craft/photocraft-0.6.0-windows-x64-portable",
     "filmcraft":   "C:/craft/filmcraft-0.5.0-windows-x64-portable",
-    "effectcraft": "C:/craft/effectcraft-windows-x64-portable"
+    "effectcraft": "C:/Program Files/EffectCraft"
   },
   "control": { "filmcraft": 9876, "effectcraft": 9877 }
 }
@@ -139,10 +140,10 @@ artcraft_cli  { bin:"photocraft", args:["batch","--actions","demo/craft/grade.js
 
 | Tool | What it does |
 |---|---|
-| `artcraft_status` | Toolchain health check: which CLIs resolved, data root, control ports, running jobs |
+| `artcraft_status` | Toolchain health check: which CLIs resolved, config location, control ports, running jobs |
 | `artcraft_cli` | Run any CLI subcommand synchronously (`photocraft-cli run/batch`, `filmcraft-cli commands`, …) |
 | `artcraft_control` | One command over the JSON control channel of a *running* FilmCraft / EffectCraft |
-| `artcraft_fs` | list / stat / read / write / mkdir inside `dataRoot` (writing `grade.json`, fetching a rendered `.ecproj`, …) |
+| `artcraft_fs` | Bridged file ops — list / stat / read / write / mkdir at caller-decided absolute paths |
 
 ## Driving it from the browser
 
@@ -170,15 +171,16 @@ Full route list:
 | Route | Purpose |
 |---|---|
 | `GET /artcraft/api/status` | Toolchain health (same payload as `artcraft_status`) |
-| `GET /artcraft/api/projects` | Project directories under `dataRoot` |
-| `POST /artcraft/api/fs?action=write&rel=…` | Write a file — raw body (Blob upload) or JSON `{rel, text\|base64}` |
-| `GET /artcraft/api/fs?op=list\|stat\|readtext&rel=…` | Read directories, metadata, small text files |
-| `GET /artcraft/api/file?rel=…` | Download a file — streamed, up to 2 GB |
+| `POST /artcraft/api/fs?action=write&path=…` | Write a file — absolute `path`, raw body (Blob upload) or JSON `{base, rel, text\|base64}` |
+| `GET /artcraft/api/fs?op=list\|stat\|readtext&path=…` | Read directories, metadata, small text files |
+| `GET /artcraft/api/file?path=…` | Download a file — streamed, up to 2 GB |
 | `POST /artcraft/api/job` · `GET ?id=…` · `POST /artcraft/api/job/cancel` | Job lifecycle with output statting and tail logs |
 | `POST /artcraft/api/control` | Synchronous control-channel call |
 
 Uploads are capped at 320 MB per request (Blob direct, no base64 needed for the raw path);
-downloads stream up to 2 GB. Path arguments are always relative to `dataRoot` and confined to it.
+downloads stream up to 2 GB. All path arguments are **absolute** (or `base` absolute directory +
+relative `rel`) — the caller decides where files live: chat calls point at the conversation
+workspace, the canvas points at its project folder.
 
 ## The control channel: drive a running app
 
@@ -259,14 +261,15 @@ a web UI.
   loopback-only and unauthenticated, so nothing else will answer on that port.
 - **A job hangs** — `GET /artcraft/api/job` lists everything with logs; cancel by id. Plugin
   reloads kill all child jobs by design.
-- **Path escape errors** — by design: every filesystem argument must resolve inside `dataRoot`.
+- **"需要绝对路径" errors** — pass absolute paths (chat: the conversation workspace; canvas: the
+  project folder), or a `base` absolute directory + relative `rel`.
 
 ## Security & trust model
 
 The HTTP surface has **no authentication** and rides on the Harness web server, which listens on
 loopback only — treat the port as trusted-local and don't expose it to a network; put a reverse
-proxy with auth in front if you must. Child processes are locked to the three allow-listed
-binaries; file access is locked to `dataRoot`; the control channel only ever dials `127.0.0.1`.
+proxy with auth in front if you must. Child processes are locked to the seven allow-listed
+family CLIs; the control channel only ever dials `127.0.0.1`.
 
 ## Publishing
 
@@ -281,10 +284,10 @@ GitHub: this repository is self-contained; `README.md` is English-first with a
 [简体中文](README.zh-CN.md) companion.
 
 **Releases run through npm Trusted Publishing** (GitHub Actions OIDC — no tokens, no OTP):
-`.github/workflows/publish.yml` fires on `v*` tags **on `main` only** (a guard step rejects tags
-from other branches); the trusted publisher on the npm package points at `NINKCH/dsh-artcraft` /
-`publish.yml`. Release flow and rules live in [RELEASING.md](RELEASING.md) — in short: changes
-land on `dev`, get tested there, and are only merged to `main` and tagged with the maintainer's
+publishing is triggered by **creating a GitHub Release** (tag `vX.Y.Z` matching `package.json`);
+`.github/workflows/publish.yml` verifies the release commit is on `main` and the versions align,
+then publishes. Release flow and rules live in [RELEASING.md](RELEASING.md) — in short: changes
+land on `dev`, get tested there, and are only merged to `main` and released with the maintainer's
 explicit approval.
 
 ## License

package/README.zh-CN.md

@@ -24,12 +24,12 @@ Effects）等。它们有一个大多数桌面软件都不具备的共同基因
 本插件把这套自动化面接进 DeepSeek Harness，让 AI 不只是"谈论"这些软件，而是真的**操作**它们：
 
 - **对话里** —— 四个 Agent 工具，任何 Harness 会话都能检查工具链、执行 CLI 命令、向运行中的
-  App 发控制通道命令、在专属数据目录里读写文件。
+  App 发控制通道命令、做桥接文件操作。
 - **浏览器里** —— 同源 HTTP API（`/artcraft/api/*`），任何 Harness 前端都能直接调用：无 CORS、
   无密钥。它为 [无限画布 / infinite-canvas](../dsh-infinite_canvas/README.md)（节点式 AI 短剧
   分镜画布）而建，但任何前端都可用。
-- **磁盘上** —— 每台机器一个 `dataRoot`，素材、工程文件、渲染产物按项目分区
-  （`media/ · craft/ · out/`），生成式流水线与桌面应用在同一片地基上会合。
+- **路径由调用方决定** —— 本插件只是桥接，不持有数据目录：对话调用默认落在当前对话工作空间
+  （或提示词指定的任意位置）；画布调用则写在自己项目目录下。
 
 典型的 AI 短剧闭环：模型生成分镜图 → PhotoCraft 批量调色锐化 → EffectCraft 渲染动态片头 →
 FilmCraft 剪辑、调色、混音、烧字幕 → 导出 H.264。"生成"之后的每一步都由本插件无头驱动。
@@ -51,7 +51,7 @@ FilmCraft 剪辑、调色、混音、烧字幕 → 导出 H.264。"生成"之后
   （无头）                 混音导出                Lottie 导出
        └───────────────────────┴───────────────────────┘
                                ▼
-              <dataRoot>/<项目>/{media, craft, out}
+              产物位置由调用方决定（对话 → 当前工作空间 · 画布 → 项目目录）
 ```
 
 全流程本地运行：不联网、无账号、无遥测。
@@ -96,17 +96,17 @@ pnpm install --dir C:/Users/<你>/.dsh/profiles/desktop
 
 > 若你的 Harness 版本带有"从文件夹安装插件"的管理界面，用它也行 —— 最终落盘的就是上面两行。
 
-**3. 配置** `index.js` 旁边的 `artcraft.config.json`（从 `artcraft.config.json.example` 复制；
-该文件已 gitignore，且每次请求都会重读 —— 改路径无需重启）：
+**3. 配置** `artcraft.config.json`（从 `artcraft.config.json.example` 复制）。推荐放
+`C:\Users\<你>\.dsh\artcraft.config.json`（持久，更新插件不丢）；放在 `index.js` 旁也可（旧版兼容）。
+文件已 gitignore，且每次请求都会重读 —— 改路径无需重启：
 
 ```jsonc
 {
-  "dataRoot": "D:/craft-workspace",              // 素材与产物的根目录
   "bins": {
     // 三种写法：目录（自动拼接 <名>-cli 可执行文件）、完整 exe 路径、或走 PATH 的裸命令名
     "photocraft":  "C:/craft/photocraft-0.6.0-windows-x64-portable",
     "filmcraft":   "C:/craft/filmcraft-0.5.0-windows-x64-portable",
-    "effectcraft": "C:/craft/effectcraft-windows-x64-portable"
+    "effectcraft": "C:/Program Files/EffectCraft"
   },
   "control": { "filmcraft": 9876, "effectcraft": 9877 }
 }
@@ -129,10 +129,10 @@ artcraft_cli  { bin:"photocraft", args:["batch","--actions","demo/craft/grade.js
 
 | 工具 | 用途 |
 |---|---|
-| `artcraft_status` | 工具体检：CLI 是否找到、数据目录、控制端口、进行中的任务 |
+| `artcraft_status` | 工具体检：CLI 是否找到、配置目录、控制端口、进行中的任务 |
 | `artcraft_cli` | 同步执行任意 CLI 子命令（`photocraft-cli run/batch`、`filmcraft-cli commands` 等） |
 | `artcraft_control` | 向**运行中**的 FilmCraft / EffectCraft 控制通道发一条命令 |
-| `artcraft_fs` | 在 `dataRoot` 内 list / stat / 读 / 写 / 建目录（写 `grade.json`、取回 `.ecproj` 等） |
+| `artcraft_fs` | 桥接文件操作 —— list / stat / 读 / 写 / 建目录，路径由调用方绝对指定 |
 
 ## 在浏览器里驱动
 
@@ -159,15 +159,15 @@ POST /artcraft/api/job/cancel  { "id":"7f2c…" }
 | 路由 | 用途 |
 |---|---|
 | `GET /artcraft/api/status` | 工具体检（与 `artcraft_status` 同数据） |
-| `GET /artcraft/api/projects` | `dataRoot` 下的项目目录 |
-| `POST /artcraft/api/fs?action=write&rel=…` | 写文件 —— 原始字节流（Blob 直传）或 JSON `{rel, text\|base64}` |
-| `GET /artcraft/api/fs?op=list\|stat\|readtext&rel=…` | 读目录、元数据、小文本 |
-| `GET /artcraft/api/file?rel=…` | 下载文件 —— 流式，上限 2 GB |
+| `POST /artcraft/api/fs?action=write&path=…` | 写文件 —— 绝对 `path`，原始字节流（Blob 直传）或 JSON `{base, rel, text\|base64}` |
+| `GET /artcraft/api/fs?op=list\|stat\|readtext&path=…` | 读目录、元数据、小文本 |
+| `GET /artcraft/api/file?path=…` | 下载文件 —— 流式，上限 2 GB |
 | `POST /artcraft/api/job` · `GET ?id=…` · `POST /artcraft/api/job/cancel` | 任务生命周期，含产物探测与日志尾部 |
 | `POST /artcraft/api/control` | 控制通道同步调用 |
 
 上传单次上限 320 MB（原始路径 Blob 直传，无需 base64）；下载流式上限 2 GB。
-所有路径参数相对 `dataRoot` 且被限制在其中。
+所有路径参数为**绝对路径**（或 `base` 绝对目录 + 相对 `rel`）—— 位置由调用方决定：
+对话调用指向当前工作空间，画布调用指向其项目目录。
 
 ## 控制通道：驱动正在运行的 App
 
@@ -244,13 +244,14 @@ NVENC 硬编）、ProRes、DNxHR，附 EBU R128 响度归一与字幕烧录。
   不会有别的应答者。
 - **任务卡住** —— `GET /artcraft/api/job` 带日志列出全部任务，按 id 取消；插件重载会按设计
   终止所有子任务。
-- **路径越界报错** —— 设计如此：所有文件参数必须落在 `dataRoot` 之内。
+- **"需要绝对路径"报错** —— 传绝对路径即可：对话用当前工作空间下的路径，画布用项目目录下的
+  路径（或 `base` 绝对目录 + 相对 `rel`）。
 
 ## 安全与信任模型
 
 HTTP 面无鉴权，挂在 Harness Web 服务之下（仅回环监听）—— 把端口当本机可信处理，**不要暴露
-到网络**；确需远程请加带鉴权的反向代理。子进程锁定三个白名单可执行文件；文件访问锁定
-`dataRoot`；控制通道只会拨 `127.0.0.1`。
+到网络**；确需远程请加带鉴权的反向代理。子进程锁定 7 个白名单家族 CLI；控制通道只会拨
+`127.0.0.1`。
 
 ## 发布
 
@@ -264,9 +265,9 @@ GitHub 上传本仓库即可：`README.md` 英文优先，附
 [简体中文](README.zh-CN.md) 对照。
 
 **发版走 npm Trusted Publishing**（GitHub Actions OIDC —— 无令牌、无 OTP）：
-`.github/workflows/publish.yml` 仅在 **main 分支**的 `v*` 标签推送时触发（守卫步骤会拒绝其他分支
-的标签）；npm 包侧的可信发布指向 `NINKCH/dsh-artcraft` / `publish.yml`。发版流程与红线见
-[RELEASING.md](RELEASING.md)：改动先进 `dev` 测试，维护者明确批准后才合并 main 并打标签。
+发布由 **GitHub Release** 触发（tag `vX.Y.Z` 与 package.json version 一致）；`.github/workflows/publish.yml`
+会校验发布提交在 main 上且版本对齐，然后自动发布。发版流程与红线见
+[RELEASING.md](RELEASING.md)：改动先进 `dev` 测试，维护者明确批准后才合并 main 并发 Release。
 
 ## 许可
 

package/artcraft.config.json.example

@@ -1,9 +1,12 @@
 {
-  "dataRoot": "D:/craft-workspace",
   "bins": {
-    "photocraft": "C:/craft/photocraft-0.6.0-windows-x64-portable",
-    "filmcraft": "C:/craft/filmcraft-0.5.0-windows-x64-portable",
-    "effectcraft": "C:/craft/effectcraft-0.1.0-windows-x64-portable"
+    "photocraft": "D:/craft/photocraft-0.6.0/photocraft-0.6.0-windows-x64-portable",
+    "vectorcraft": "C:/Program Files/VectorCraft",
+    "filmcraft": "D:/craft/filmcraft-0.5.0/filmcraft-0.5.0-windows-x64-portable",
+    "lightcraft": "C:/Program Files/LightCraft",
+    "pdfcraft": "C:/Program Files/PdfCraft",
+    "effectcraft": "C:/Program Files/EffectCraft",
+    "designcraft": "C:/Program Files/DesignCraft"
   },
   "control": {
     "filmcraft": 9876,

package/client.js

@@ -62,10 +62,19 @@ window.__ModuleLoader__.load({
       useEffect(() => () => { alive.current = false; }, []);
 
       const loadStatus = useCallback(async () => {
+        setBusy('refresh');
         try {
+          // 刷新 = 状态 + 顺带一次家族安装探测（后装软件/改安装目录后自动修正配置；
+          // 探测端点在旧版插件上不存在时静默跳过）
+          try {
+            await api('/discover', {
+              method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}',
+            });
+          } catch { /* 旧版无此路由 → 静默跳过 */ }
           const s = await api('/status');
           if (alive.current) { setStatus(s); setStatusErr(null); }
         } catch (e) { if (alive.current) setStatusErr(String(e.message || e)); }
+        finally { if (alive.current) setBusy(''); }
       }, []);
 
       const checkUpdate = useCallback(async () => {
@@ -120,8 +129,8 @@ window.__ModuleLoader__.load({
         statusErr
           ? h('div', { className: 'dshac-muted' }, '未连接：' + statusErr + '（插件可能未注册或 Harness 需要重启）')
           : h('div', null, Object.keys(LABELS).map(binRow),
-              status?.dataRoot ? h('div', { className: 'dshac-row dshac-muted' },
-                '数据目录：', h('span', { className: 'dshac-mono' }, status.dataRoot.path)) : null),
+              status?.config?.path ? h('div', { className: 'dshac-row dshac-muted' },
+                '配置目录：', h('span', { className: 'dshac-mono' }, status.config.path)) : null),
         h('div', { className: 'dshac-row', style: { marginTop: '10px' } },
           h('span', { className: 'dshac-muted' },
             '当前 v' + (status?.version ?? upd?.current ?? '?') +

package/index.js

@@ -1,15 +1,20 @@
 /**
  * @ninkch/dsh-artcraft — DeepSeek Harness 插件（Host 半侧）
  *
- * 把 ArtCraft 家族的自动化接口封装成两种形态：
+ * 本插件只是【桥接】：把 ArtCraft 家族软件的自动化接口转接给 Harness，不持有任何数据目录。
+ * 结果文件的位置由调用方决定 ——
+ *   对话调用：当前对话工作空间下的绝对路径（或提示词指定的任意位置）
+ *   画布调用：画布项目目录下的绝对路径（哪个项目使用就放哪个项目下）
+ *
+ * 两种形态：
  *   1) Agent Tools（对话内直接驱动）:
- *        artcraft_status  —— 检查三个 CLI 是否可用、数据目录、控制通道配置
- *        artcraft_cli     —— 运行 photocraft-cli / filmcraft-cli / effectcraft-cli 任意命令
+ *        artcraft_status  —— 检查 7 个家族 CLI 是否可用、配置目录、控制通道配置
+ *        artcraft_cli     —— 运行 7 个家族 CLI 任意命令（cwd / 文件参数由调用方给绝对路径）
  *        artcraft_control —— 向运行中的 FilmCraft/EffectCraft JSON 控制通道发一条命令
- *        artcraft_fs      —— 在 dataRoot 内读写文件（准备 actions.json / 取回产物）
+ *        artcraft_fs      —— 桥接文件操作（list/stat/readtext/write/mkdir，绝对路径）
+ *        artcraft_update  —— 插件自身更新（检查/应用）
  *   2) HTTP API（同源 /artcraft/api/*，供无限画布等前端调用，无 CORS 问题）:
  *        GET  /artcraft/api/status     环境自检
- *        GET  /artcraft/api/projects   列出 dataRoot 下的项目目录
  *        GET  /artcraft/api/fs         list / stat / readtext
  *        POST /artcraft/api/fs         write（JSON base64/text 或原始字节流）
  *        GET  /artcraft/api/file       下载产物（流式，raw 或 text）
@@ -19,12 +24,10 @@
  *        POST /artcraft/api/control    控制通道同步调用（engine.execute / ui.*）
  *
  * 安全约定：
- *   - 所有文件操作限制在 dataRoot 内（拒绝 .. 越界与绝对路径外逃）；
- *   - 子进程只允许三个白名单键（photocraft/filmcraft/effectcraft），
- *     具体可执行文件由 artcraft.config.json 指定；
+ *   - 子进程只允许 7 个白名单键（家族 CLI），具体可执行文件由 artcraft.config.json 指定；
  *   - 控制通道只连 127.0.0.1，与 ArtCraft 官方协议一致（App 需以 --control 启动；
  *     PhotoCraft 的控制通道为鉴权模式，本插件不代理，故仅支持 filmcraft/effectcraft）；
- *   - 本插件与 infinite-canvas 零代码耦合，仅通过 HTTP + 磁盘目录约定协作。
+ *   - 本插件与 infinite-canvas 零代码耦合，仅通过 HTTP + 调用方给定路径协作。
  *
  * 信任模型：HTTP API 无鉴权，随 DSH Web GUI 仅监听回环；不要把 GUI 端口暴露到局域网。
  */
@@ -39,7 +42,7 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
 const NAME = 'artcraft';
-const VERSION = '0.2.6';
+const VERSION = '0.2.8';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
 const BINS = ['photocraft', 'vectorcraft', 'filmcraft', 'lightcraft', 'pdfcraft', 'effectcraft', 'designcraft'];
@@ -55,7 +58,6 @@ const LINE_CAP = 4000;                       // 单行截断
 const KEEP_JOBS = 64;                        // 已结束任务保留条数
 
 const DEFAULT_CONFIG = {
-  dataRoot: path.join(os.homedir(), 'craft-workspace'),
   bins: {
     photocraft: 'photocraft-cli',
     vectorcraft: 'vectorcraft-cli',
@@ -68,13 +70,19 @@ const DEFAULT_CONFIG = {
   control: { ...DEFAULT_PORTS },
 };
 
+const APP_DISPLAY = {
+  photocraft: 'PhotoCraft', vectorcraft: 'VectorCraft', filmcraft: 'FilmCraft',
+  lightcraft: 'LightCraft', pdfcraft: 'PdfCraft', effectcraft: 'EffectCraft', designcraft: 'DesignCraft',
+};
+
 /* ============================ 配置 ============================ */
 
 async function loadConfig() {
   const cfg = {
-    dataRoot: DEFAULT_CONFIG.dataRoot,
     bins: { ...DEFAULT_CONFIG.bins },
     control: { ...DEFAULT_PORTS },
+    configPath: null, // 实际生效的配置文件（供界面显示"配置目录"）
+    autoDiscovered: false, // 首次运行是否由自动探测生成了配置
   };
   // 配置查找顺序：~/.dsh（持久，推荐 —— 更新替换包目录也不丢）→ 包目录（旧版兼容）
   const candidates = [
@@ -84,7 +92,6 @@ async function loadConfig() {
   for (const candidate of candidates) {
     try {
       const user = JSON.parse(await fs.readFile(candidate, 'utf8'));
-      if (user && typeof user.dataRoot === 'string' && user.dataRoot) cfg.dataRoot = user.dataRoot;
       if (user && user.bins) {
         for (const k of BINS) {
           if (typeof user.bins[k] === 'string' && user.bins[k]) cfg.bins[k] = user.bins[k];
@@ -96,28 +103,82 @@ async function loadConfig() {
           if (Number.isInteger(p) && p > 0 && p < 65536) cfg.control[k] = p;
         }
       }
+      cfg.configPath = candidate;
       break; // 第一个可解析的配置生效
     } catch { /* 该候选不存在/非法 → 试下一个 */ }
   }
+  // 首次运行（没有任何配置文件）：自动探测本机家族软件安装位置并生成持久配置
+  if (!cfg.configPath) {
+    try {
+      const found = await discoverBinPaths();
+      const target = path.join(os.homedir(), '.dsh', 'artcraft.config.json');
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await fs.writeFile(target, JSON.stringify({ bins: { ...cfg.bins, ...found }, control: { ...cfg.control } }, null, 2) + '\n');
+      for (const k of Object.keys(found)) cfg.bins[k] = found[k];
+      cfg.configPath = target;
+      cfg.autoDiscovered = Object.keys(found).length > 0;
+    } catch { /* 自动探测失败不影响默认行为 */ }
+  }
   return cfg;
 }
 
+/** 自动探测：扫描常见安装位置（Program Files 等）里的家族 CLI */
+async function discoverBinPaths() {
+  const isWin = process.platform === 'win32';
+  const pf = process.env['ProgramFiles'] || (isWin ? 'C:\\Program Files' : '/usr/local/bin');
+  const pf86 = process.env['ProgramFiles(x86)'] || '';
+  const lap = process.env['LOCALAPPDATA']
+    ? path.join(process.env['LOCALAPPDATA'], 'Programs')
+    : path.join(os.homedir(), '.local');
+  const roots = [pf, ...(pf86 ? [pf86] : []), lap];
+  const found = {};
+  for (const key of BINS) {
+    const cliName = cliNameFor(key);
+    const names = [APP_DISPLAY[key], key, key.toUpperCase(), key.toLowerCase()];
+    outer: for (const root of roots) {
+      for (const name of names) {
+        const exe = path.join(root, name, cliName);
+        try {
+          if ((await fs.stat(exe)).isFile()) { found[key] = path.join(root, name); break outer; }
+        } catch { /* 继续 */ }
+      }
+    }
+  }
+  return found;
+}
+
 /* ============================ 路径与进程 ============================ */
 
-/** 把 rel 解析为 dataRoot 内的绝对路径，拒绝越界 */
-function resolveSafeRel(dataRoot, rel) {
-  const root = path.resolve(String(dataRoot));
-  const p = path.resolve(root, String(rel ?? '.'));
-  if (p !== root && !p.startsWith(root + path.sep)) {
-    throw new Error(`路径越界（必须在数据目录内）: ${rel}`);
+/**
+ * 桥接语义：路径由调用方决定（本插件只是桥梁，不设数据目录）——
+ *   对话调用：当前对话工作空间下的绝对路径（或提示词指定的任意位置）
+ *   画布调用：画布项目目录下的绝对路径
+ * 支持 ~ 展开；也接受 base(绝对目录) + rel(相对) 组合，方便批量调用。
+ */
+function resolveCallerPath(p) {
+  let s = String(p ?? '').trim();
+  if (!s) throw new Error('缺少路径参数');
+  if (s === '~' || s.startsWith('~/') || s.startsWith('~\\')) s = path.join(os.homedir(), s.slice(1));
+  const abs = path.resolve(s);
+  if (!path.isAbsolute(abs)) {
+    throw new Error('需要绝对路径 —— 对话调用传当前工作空间下的绝对路径，画布传项目目录下的绝对路径（或用 base + 相对路径组合）');
   }
-  return p;
+  return abs;
 }
 
-async function ensureDirSafe(cfg, rel) {
-  const p = resolveSafeRel(cfg.dataRoot, rel ?? '.');
-  await fs.mkdir(p, { recursive: true });
-  return p;
+function resolveBaseRel(base, rel) {
+  if (base) {
+    const b = resolveCallerPath(base);
+    if (rel == null || String(rel) === '') return b;
+    return path.resolve(b, String(rel));
+  }
+  return resolveCallerPath(rel);
+}
+
+async function ensureDir(p) {
+  const abs = resolveCallerPath(p);
+  await fs.mkdir(abs, { recursive: true });
+  return abs;
 }
 
 function cliNameFor(key) {
@@ -266,15 +327,27 @@ function controlCall(port, method, params, { timeoutMs = 30_000 } = {}) {
 
 const jobs = new Map(); // id -> job
 
-async function statOutputs(cfg, outputs) {
+/**
+ * 桥接语义：产物路径由调用方给定 ——
+ *   绝对路径直接使用；也可传 cwd（绝对目录）让 outputs 以它为基准。
+ */
+async function statOutputs(outputs, cwd) {
   const out = [];
+  const base = cwd ? resolveCallerPath(cwd) : null;
   for (const item of outputs ?? []) {
-    const rel = String(item.rel ?? item);
+    const spec = String(item.rel ?? item.path ?? item);
+    let abs;
     try {
-      const st = await fs.stat(resolveSafeRel(cfg.dataRoot, rel));
-      out.push({ rel, exists: true, dir: st.isDirectory(), size: st.size, mtime: st.mtimeMs });
+      abs = base ? path.resolve(base, spec) : resolveCallerPath(spec);
     } catch {
-      out.push({ rel, exists: false, dir: false, size: null, mtime: null });
+      out.push({ rel: spec, exists: false, dir: false, size: null, mtime: null });
+      continue;
+    }
+    try {
+      const st = await fs.stat(abs);
+      out.push({ rel: spec, path: abs, exists: true, dir: st.isDirectory(), size: st.size, mtime: st.mtimeMs });
+    } catch {
+      out.push({ rel: spec, path: abs, exists: false, dir: false, size: null, mtime: null });
     }
   }
   return out;
@@ -309,18 +382,19 @@ function pruneJobs() {
   }
 }
 
-async function startJob(cfg, { bin, args, cwdRel, outputs, timeoutMs }) {
+async function startJob(cfg, { bin, args, cwd, outputs, timeoutMs }) {
   if (!BINS.includes(bin)) throw new Error(`bin 必须是 ${BINS.join(' | ')} 之一`);
   if (args != null && !Array.isArray(args)) throw new Error('args 必须是字符串数组');
   const exe = await resolveBin(cfg, bin);
-  const cwd = await ensureDirSafe(cfg, cwdRel ?? '.');
+  // 桥接语义：cwd 由调用方给绝对路径（对话=工作空间下的目录，画布=项目目录）；不传则继承 Host 进程
+  const cwdAbs = cwd ? await ensureDir(cwd) : null;
   const id = crypto.randomUUID();
   const job = {
     id,
     bin,
     exe,
     args: (args ?? []).map(String),
-    cwd,
+    cwd: cwdAbs,
     status: 'running',
     code: null,
     signal: null,
@@ -328,11 +402,11 @@ async function startJob(cfg, { bin, args, cwdRel, outputs, timeoutMs }) {
     endedAt: null,
     stdout: [],
     stderr: [],
-    outputs: (outputs ?? []).map((rel) => ({ rel: String(rel) })),
+    outputs: (outputs ?? []).map((o) => ({ rel: String(o.rel ?? o.path ?? o) })),
     child: null,
     timer: null,
   };
-  const child = spawn(job.exe, job.args, { cwd, windowsHide: true });
+  const child = spawn(job.exe, job.args, { cwd: cwdAbs ?? undefined, windowsHide: true });
   job.child = child;
   child.stdout?.setEncoding('utf8');
   child.stderr?.setEncoding('utf8');
@@ -384,13 +458,13 @@ async function statusInfo(cfg, meta) {
     }
     bins[key] = { configured: cfg.bins[key], exe, found, note };
   }
-  let dataRoot = { path: cfg.dataRoot, exists: false };
-  try { dataRoot.exists = (await fs.stat(cfg.dataRoot)).isDirectory(); } catch { /* 不存在 */ }
+  let configPath = null;
+  try { configPath = cfg.configPath && (await fs.stat(cfg.configPath)).isFile() ? cfg.configPath : null; } catch { /* 不存在 */ }
   return {
     plugin: NAME,
     version: VERSION,
     platform: process.platform,
-    dataRoot,
+    config: { path: configPath, found: !!configPath, autoDiscovered: !!cfg.autoDiscovered },
     bins,
     control: cfg.control,
     jobs: {
@@ -502,17 +576,30 @@ async function detectInstall() {
   return { mode: repoDir ? 'git' : 'npm', here, real, repoDir, profileDir, gitClean, branch };
 }
 
+const REGISTRIES = ['https://registry.npmjs.org', 'https://registry.npmmirror.com'];
+
 async function fetchLatestVersion() {
-  const url = `https://registry.npmjs.org/${PKG_NAME.replace('/', '%2f')}/latest`;
-  try {
-    const res = await fetch(url, { signal: AbortSignal.timeout(12000) });
-    if (res.status === 404) return { latest: null, note: 'npm 上还没有这个包' };
-    if (!res.ok) throw new Error('registry 返回 ' + res.status);
-    const j = await res.json();
-    return { latest: j.version ?? null, tarball: j.dist?.tarball ?? null, integrity: j.dist?.integrity ?? null };
-  } catch (e) {
-    return { latest: null, note: '查询 npm 失败: ' + String(e?.cause?.message || e?.message || e) };
+  const slug = PKG_NAME.replace('/', '%2f');
+  const errors = [];
+  // 回退链：官方源 → npmmirror 镜像（国内无代理机器也能完成检查与更新）
+  for (const reg of REGISTRIES) {
+    try {
+      const res = await fetch(`${reg}/${slug}/latest`, { signal: AbortSignal.timeout(12000) });
+      if (res.status === 404) { errors.push(`${reg}: 404`); continue; }
+      if (!res.ok) throw new Error('HTTP ' + res.status);
+      const j = await res.json();
+      if (!j.version) { errors.push(`${reg}: 无版本数据`); continue; }
+      return {
+        latest: j.version ?? null,
+        tarball: j.dist?.tarball ?? null,
+        integrity: j.dist?.integrity ?? null,
+        source: reg,
+      };
+    } catch (e) {
+      errors.push(`${reg}: ${String(e?.cause?.message || e?.message || e)}`);
+    }
   }
+  return { latest: null, note: '查询失败（官方源与 npmmirror 均不可达）—— ' + errors.join('；') };
 }
 
 async function updateCheck() {
@@ -554,8 +641,20 @@ async function updateApply() {
   await fs.mkdir(tmp, { recursive: true });
   try {
     const tgzPath = path.join(tmp, 'pkg.tgz');
-    const res = await fetch(meta.tarball, { signal: AbortSignal.timeout(180000) });
-    if (!res.ok) throw new Error('下载 tarball 失败: HTTP ' + res.status);
+    // 下载：优先元数据自带的官方地址；失败时回退 npmmirror 镜像（sha512 校验保证内容一致）
+    let res;
+    try {
+      res = await fetch(meta.tarball, { signal: AbortSignal.timeout(180000) });
+      if (!res.ok) throw new Error('HTTP ' + res.status);
+    } catch (e) {
+      const slug = PKG_NAME.replace('/', '%2f');
+      const mirrorUrl = `https://registry.npmmirror.com/${slug}/-/${PKG_NAME.split('/')[1]}-${meta.latest}.tgz`;
+      WriteMirrorRetry: {
+        res = await fetch(mirrorUrl, { signal: AbortSignal.timeout(180000) });
+        if (!res.ok) throw new Error('HTTP ' + res.status);
+        break WriteMirrorRetry;
+      }
+    }
     const buf = Buffer.from(await res.arrayBuffer());
     if (buf.length > 64 * 1024 * 1024) throw new Error('tarball 超过 64MB 上限，已终止');
     const digest = crypto.createHash('sha512').update(buf).digest('base64');
@@ -632,7 +731,7 @@ export function apply(ctx) {
 
     attempt({
       name: 'artcraft_status',
-      description: '检查 ArtCraft 工具链（photocraft/filmcraft/effectcraft CLI）是否可用，报告数据目录、控制通道端口与任务状态。',
+      description: '检查 ArtCraft 家族 7 个 CLI 是否可用，报告配置目录、控制通道端口与任务状态。本插件只是桥接，产物路径由调用方决定。',
       schema: { type: 'object', properties: {}, additionalProperties: false },
       async execute() {
         const cfg = await loadConfig();
@@ -648,7 +747,7 @@ export function apply(ctx) {
         properties: {
           bin: { type: 'string', enum: [...BINS], description: '工具键' },
           args: { type: 'array', items: { type: 'string' }, description: '命令行参数（不含程序名）' },
-          cwdRel: { type: 'string', description: '工作目录，相对 dataRoot' },
+          cwd: { type: 'string', description: '工作目录（绝对路径，可选）：对话=当前工作空间下的目录，画布=项目目录；不传则继承 Host 进程' },
           timeoutMs: { type: 'number', description: '超时毫秒，默认 900000' },
         },
         required: ['bin', 'args'],
@@ -658,7 +757,7 @@ export function apply(ctx) {
         const cfg = await loadConfig();
         if (args.args != null && !Array.isArray(args.args)) throw new Error('args 必须是字符串数组');
         const exe = await resolveBin(cfg, String(args.bin));
-        const cwd = await ensureDirSafe(cfg, args.cwdRel ?? '.');
+        const cwd = args.cwd ? await ensureDir(args.cwd) : null;
         const r = await runProcess(exe, args.args ?? [], { cwd, timeoutMs: args.timeoutMs });
         return { bin: args.bin, exe, cwd, ...r };
       },
@@ -689,56 +788,57 @@ export function apply(ctx) {
 
     attempt({
       name: 'artcraft_fs',
-      description: '在 craft 数据目录（dataRoot）内进行文件操作：list / stat / readtext / write / mkdir。所有路径相对 dataRoot，禁止越界。',
+      description: '桥接文件操作：list / stat / readtext / write / mkdir。路径由调用方决定 —— 对话调用传当前工作空间下的绝对路径，画布调用传项目目录下的绝对路径（或 base + rel 组合）。',
       schema: {
         type: 'object',
         properties: {
           op: { type: 'string', enum: ['list', 'stat', 'readtext', 'write', 'mkdir'] },
-          rel: { type: 'string', description: '相对 dataRoot 的路径' },
+          path: { type: 'string', description: '绝对路径（或 ~/ 展开）' },
+          base: { type: 'string', description: '可选：绝对基准目录，rel 相对它解析' },
+          rel: { type: 'string', description: '可选：相对 base 的路径（需同时给 base）' },
           text: { type: 'string', description: 'op=write 时的文本内容' },
           base64: { type: 'string', description: 'op=write 时的二进制内容（base64）' },
         },
-        required: ['op', 'rel'],
+        required: ['op'],
         additionalProperties: false,
       },
       async execute(args) {
-        const cfg = await loadConfig();
-        const rel = String(args.rel ?? '');
         const op = String(args.op);
+        const P = () => resolveBaseRel(args.base, args.path ?? args.rel);
         if (op === 'list') {
-          const dir = resolveSafeRel(cfg.dataRoot, rel || '.');
+          const dir = P();
           const entries = await fs.readdir(dir, { withFileTypes: true });
           const out = [];
           for (const ent of entries) {
             const st = await fs.stat(path.join(dir, ent.name)).catch(() => null);
             out.push({ name: ent.name, dir: ent.isDirectory(), size: st?.size ?? null, mtime: st?.mtimeMs ?? null });
           }
-          return { rel, entries: out };
+          return { path: dir, entries: out };
         }
         if (op === 'stat') {
-          const st = await fs.stat(resolveSafeRel(cfg.dataRoot, rel));
-          return { rel, size: st.size, mtime: st.mtimeMs, dir: st.isDirectory() };
+          const st = await fs.stat(P());
+          return { path: P(), size: st.size, mtime: st.mtimeMs, dir: st.isDirectory() };
         }
         if (op === 'readtext') {
-          const p = resolveSafeRel(cfg.dataRoot, rel);
+          const p = P();
           const st = await fs.stat(p);
           if (st.size > TEXT_CAP) throw new Error('文件超过 16MB，请用 GET /artcraft/api/file 取回');
           const buf = await fs.readFile(p);
-          return { rel, text: buf.toString('utf8') };
+          return { path: p, text: buf.toString('utf8') };
         }
         if (op === 'mkdir') {
-          const p = await ensureDirSafe(cfg, rel);
-          return { rel, path: p };
+          const p = await ensureDir(P());
+          return { path: p };
         }
         if (op === 'write') {
-          const p = resolveSafeRel(cfg.dataRoot, rel);
+          const p = P();
           await fs.mkdir(path.dirname(p), { recursive: true });
           let data;
           if (typeof args.base64 === 'string') data = Buffer.from(args.base64, 'base64');
           else if (typeof args.text === 'string') data = Buffer.from(args.text, 'utf8');
           else throw new Error('write 需要 text 或 base64');
           await fs.writeFile(p, data);
-          return { rel, size: data.length };
+          return { path: p, size: data.length };
         }
         throw new Error(`未知 op: ${op}`);
       },
@@ -746,7 +846,7 @@ export function apply(ctx) {
 
     attempt({
       name: 'artcraft_update',
-      description: '检查/应用 @ninkch/dsh-artcraft 插件自身的更新：action=check 对比本地与 npm latest；action=apply 执行更新（git pull 或 pnpm add，按安装形态自动选择），完成后需重启 Harness 生效。',
+      description: '检查/应用 @ninkch/dsh-artcraft 插件自身的更新：action=check 对比本地与 npm latest；action=apply 执行更新（git pull 或官方 tarball 直装 + sha512 校验，按安装形态自动选择），完成后需重启 Harness 生效。',
       schema: {
         type: 'object',
         properties: {
@@ -761,6 +861,63 @@ export function apply(ctx) {
       },
     });
 
+    attempt({
+      name: 'artcraft_discover',
+      description: '自动探测本机 ArtCraft 家族软件安装位置（Program Files / LocalAppData\\Programs 等），写入/修复配置：填充默认空缺项，并自动纠正已失效的路径（改安装目录、卸载重装到别处）；用户显式配置仍有效则不动。',
+      schema: { type: 'object', properties: {}, additionalProperties: false },
+      async execute() {
+        const cfg = await loadConfig();
+        const found = await discoverBinPaths();
+        const applied = {};
+        for (const k of BINS) {
+          if (!found[k]) continue;
+          let effective = null;
+          try { effective = await resolveBin(cfg, k); } catch { /* 未配置 */ }
+          const ok = effective ? await fileExists(effective) : false;
+          if (ok) continue; // 现有配置仍有效 → 不动
+          applied[k] = found[k];
+        }
+        if (!Object.keys(applied).length) {
+          return { applied: {}, configPath: cfg.configPath, note: '家族程序路径均已就绪，无需更新' };
+        }
+        const target = cfg.configPath || path.join(os.homedir(), '.dsh', 'artcraft.config.json');
+        let obj = {};
+        try { obj = JSON.parse(await fs.readFile(target, 'utf8')); } catch { /* 新文件 */ }
+        obj.bins = { ...(obj.bins ?? {}), ...applied };
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await fs.writeFile(target, JSON.stringify(obj, null, 2) + '\n');
+        return { applied, configPath: target, note: '已写入配置，立即生效' };
+      },
+    });
+
+    attempt({
+      name: 'artcraft_recipes',
+      description: '内置专家处理方案库：ArtCraft 家族的专业工作流配方（短剧海报、分镜批量调色、横转竖、响度标准化、SRT 字幕烧录、动态片头、多平台分发包、先探测后验证纪律）。action=list 列出全部；action=get + id 取单个配方的专业原则、执行步骤与验证清单。',
+      schema: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['list', 'get'] },
+          id: { type: 'string', description: 'action=get 时的配方 id' },
+        },
+        required: ['action'],
+        additionalProperties: false,
+      },
+      async execute(args) {
+        const recipesPath = path.join(HERE, 'recipes', 'recipes.json');
+        const catalog = JSON.parse(await fs.readFile(recipesPath, 'utf8'));
+        if (String(args.action) === 'get') {
+          const r = catalog.recipes.find((x) => x.id === String(args.id ?? ''));
+          if (!r) throw new Error('配方不存在: ' + args.id + '（可用: ' + catalog.recipes.map((x) => x.id).join(', ') + '）');
+          return r;
+        }
+        return {
+          version: catalog.version,
+          recipes: catalog.recipes.map((r) => ({ id: r.id, title: r.title, apps: r.apps, goal: r.goal })),
+          hint: 'action=get + id 取完整配方（专业原则 + 执行步骤 + 验证清单）',
+        };
+      },
+    });
+
     return () => {
       for (const d of disposers) { try { d(); } catch { /* ignore */ } }
     };
@@ -774,48 +931,34 @@ export function apply(ctx) {
         sendJson(res, 200, await statusInfo(cfg, { registered: [...toolNames], errors: [...toolErrors] }));
       }),
 
-      makeRoute(`/${NAME}/api/projects`, async (req, res) => {
-        const cfg = await loadConfig();
-        await fs.mkdir(cfg.dataRoot, { recursive: true });
-        const entries = await fs.readdir(cfg.dataRoot, { withFileTypes: true });
-        const projects = [];
-        for (const ent of entries) {
-          if (!ent.isDirectory()) continue;
-          const st = await fs.stat(path.join(cfg.dataRoot, ent.name)).catch(() => null);
-          projects.push({ name: ent.name, mtime: st?.mtimeMs ?? null });
-        }
-        projects.sort((a, b) => (b.mtime ?? 0) - (a.mtime ?? 0));
-        sendJson(res, 200, { dataRoot: cfg.dataRoot, projects });
-      }),
-
       makeRoute(`/${NAME}/api/fs`, async (req, res) => {
-        const cfg = await loadConfig();
         const url = new URL(req.url, 'http://x');
+        const base = url.searchParams.get('base'); // 可选：绝对基准目录（画布=项目目录，对话=工作空间下目录）
+        const P = () => resolveBaseRel(base, url.searchParams.get('path') ?? url.searchParams.get('rel'));
         if (req.method === 'GET') {
           const op = url.searchParams.get('op') ?? 'list';
-          const rel = url.searchParams.get('rel') ?? '.';
           if (op === 'list') {
-            const dir = resolveSafeRel(cfg.dataRoot, rel);
+            const dir = P();
             const entries = await fs.readdir(dir, { withFileTypes: true });
             const out = [];
             for (const ent of entries) {
               const st = await fs.stat(path.join(dir, ent.name)).catch(() => null);
               out.push({ name: ent.name, dir: ent.isDirectory(), size: st?.size ?? null, mtime: st?.mtimeMs ?? null });
             }
-            sendJson(res, 200, { rel, entries: out });
+            sendJson(res, 200, { path: dir, entries: out });
             return;
           }
           if (op === 'stat') {
-            const st = await fs.stat(resolveSafeRel(cfg.dataRoot, rel));
-            sendJson(res, 200, { rel, size: st.size, mtime: st.mtimeMs, dir: st.isDirectory() });
+            const st = await fs.stat(P());
+            sendJson(res, 200, { path: P(), size: st.size, mtime: st.mtimeMs, dir: st.isDirectory() });
             return;
           }
           if (op === 'readtext') {
-            const p = resolveSafeRel(cfg.dataRoot, rel);
+            const p = P();
             const st = await fs.stat(p);
             if (st.size > TEXT_CAP) throw new Error('文件超过 16MB，请改用 GET /artcraft/api/file');
             const buf = await fs.readFile(p);
-            sendJson(res, 200, { rel, text: buf.toString('utf8') });
+            sendJson(res, 200, { path: p, text: buf.toString('utf8') });
             return;
           }
           throw new Error(`未知 op: ${op}`);
@@ -824,47 +967,43 @@ export function apply(ctx) {
           const action = url.searchParams.get('action') ?? 'write';
           if (action === 'mkdir') {
             const body = await readJson(req);
-            const p = await ensureDirSafe(cfg, body.rel ?? url.searchParams.get('rel'));
+            const p = await ensureDir(resolveBaseRel(body.base ?? url.searchParams.get('base'), body.path ?? body.rel ?? url.searchParams.get('rel')));
             sendJson(res, 200, { ok: true, path: p });
             return;
           }
-          // write：JSON {rel, base64|text} 或原始字节流（rel 走查询串）
+          // write：JSON {path 或 base+rel, base64|text} 或原始字节流（路径走查询串）
           const isJson = String(req.headers['content-type'] ?? '').includes('json');
-          let rel;
+          let target;
           let data;
           if (isJson) {
             const body = await readJson(req, WRITE_CAP);
-            rel = String(body.rel ?? url.searchParams.get('rel') ?? '');
             if (typeof body.base64 === 'string') data = Buffer.from(body.base64.replace(/\s+/g, ''), 'base64');
             else if (typeof body.text === 'string') data = Buffer.from(body.text, 'utf8');
             else throw new Error('write 需要 base64 或 text 字段');
+            target = resolveBaseRel(body.base ?? url.searchParams.get('base'), body.path ?? body.rel ?? url.searchParams.get('rel'));
           } else {
-            rel = String(url.searchParams.get('rel') ?? '');
             data = await readBody(req, WRITE_CAP);
+            target = resolveBaseRel(url.searchParams.get('base'), url.searchParams.get('path') ?? url.searchParams.get('rel'));
           }
-          if (!rel) throw new Error('缺少 rel');
-          const p = resolveSafeRel(cfg.dataRoot, rel);
-          await fs.mkdir(path.dirname(p), { recursive: true });
-          await fs.writeFile(p, data);
-          sendJson(res, 200, { ok: true, rel, size: data.length });
+          await fs.mkdir(path.dirname(target), { recursive: true });
+          await fs.writeFile(target, data);
+          sendJson(res, 200, { ok: true, path: target, size: data.length });
           return;
         }
         throw new Error('仅支持 GET/POST');
       }),
 
       makeRoute(`/${NAME}/api/file`, async (req, res) => {
-        const cfg = await loadConfig();
         if (req.method !== 'GET') throw new Error('仅支持 GET');
         const url = new URL(req.url, 'http://x');
-        const rel = String(url.searchParams.get('rel') ?? '');
-        const p = resolveSafeRel(cfg.dataRoot, rel);
+        const p = resolveBaseRel(url.searchParams.get('base'), url.searchParams.get('path') ?? url.searchParams.get('rel'));
         const st = await fs.stat(p);
         if (!st.isFile()) throw new Error('不是常规文件');
         if (st.size > READ_CAP) throw new Error(`文件超过读取上限（${Math.round(READ_CAP / 1048576)}MB）`);
         if (url.searchParams.get('as') === 'text') {
           if (st.size > TEXT_CAP) throw new Error('文本模式上限 16MB，请直接下载原始文件');
           const buf = await fs.readFile(p);
-          sendJson(res, 200, { rel, text: buf.toString('utf8') });
+          sendJson(res, 200, { path: p, text: buf.toString('utf8') });
           return;
         }
         // 流式传输：产物可能是几百 MB 的视频，不整读进内存
@@ -882,13 +1021,13 @@ export function apply(ctx) {
           if (id) {
             const job = jobs.get(id);
             if (!job) throw new Error('任务不存在或已被回收');
-            job.outputs = await statOutputs(cfg, job.outputs);
+            job.outputs = await statOutputs(job.outputs, job.cwd);
             sendJson(res, 200, jobSnapshot(job, tail));
             return;
           }
           const list = [];
           for (const job of [...jobs.values()].reverse()) {
-            job.outputs = await statOutputs(cfg, job.outputs);
+            job.outputs = await statOutputs(job.outputs, job.cwd);
             list.push(jobSnapshot(job, 5));
           }
           sendJson(res, 200, { jobs: list });
@@ -925,6 +1064,36 @@ export function apply(ctx) {
         sendJson(res, 200, await updateApply());
       }),
 
+      makeRoute(`/${NAME}/api/discover`, async (req, res) => {
+        if (req.method !== 'POST') throw new Error('仅支持 POST');
+        const cfg = await loadConfig();
+        const found = await discoverBinPaths();
+        // 只填充默认空缺项；显式配置仅在已失效（改安装目录/卸载重装）时自动纠正，有效则不动
+        const applied = {};
+        for (const k of BINS) {
+          if (!found[k]) continue;
+          let effective = null;
+          try { effective = await resolveBin(cfg, k); } catch { /* 未配置 */ }
+          const ok = effective ? await fileExists(effective) : false;
+          if (ok) continue;
+          applied[k] = found[k];
+        }
+        if (Object.keys(applied).length) {
+          const target = cfg.configPath || path.join(os.homedir(), '.dsh', 'artcraft.config.json');
+          let obj = {};
+          try { obj = JSON.parse(await fs.readFile(target, 'utf8')); } catch { /* 新文件 */ }
+          obj.bins = { ...(obj.bins ?? {}), ...applied };
+          await fs.mkdir(path.dirname(target), { recursive: true });
+          await fs.writeFile(target, JSON.stringify(obj, null, 2) + '\n');
+        }
+        sendJson(res, 200, {
+          discovered: found,
+          applied,
+          configPath: cfg.configPath,
+          note: Object.keys(applied).length ? '已探测并写入配置，立即生效' : '没有需要更新的家族程序',
+        });
+      }),
+
       makeRoute(`/${NAME}/api/control`, async (req, res) => {
         if (req.method !== 'POST') throw new Error('仅支持 POST');
         const cfg = await loadConfig();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninkch/dsh-artcraft",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "type": "module",
   "description": "Drive the open-source ArtCraft studio apps (PhotoCraft / FilmCraft / EffectCraft) from DeepSeek Harness ? agent tools, a same-origin HTTP API, and plugins-page status with self-update.",
   "keywords": [
@@ -35,6 +35,7 @@
     "client.js",
     "cordis.patch.yml",
     "artcraft.config.json.example",
+    "recipes",
     "README.md",
     "README.zh-CN.md",
     "NOTICE.md"

package/recipes/recipes.json

@@ -0,0 +1,143 @@
+{
+  "version": 1,
+  "updated": "2026-10-10",
+  "recipes": [
+    {
+      "id": "poster-short-drama",
+      "title": "短剧海报（竖版）",
+      "apps": ["photocraft"],
+      "goal": "生成竖版短剧海报：标题层级、装饰元素、无损输出",
+      "principles": [
+        "视觉层级：主标题 → 副标题 → 装饰元素，字号/字重至少差 2 级，同屏不超过 3 个信息层",
+        "对比度：文字与背景亮度差 ≥ 4.5:1，浅背景加深色字，深背景加浅色字，或加投影/描边兜底",
+        "安全边距：四周留 5% 不放关键内容（平台裁切友好）",
+        "中文字体显式指定（如 Noto Sans SC），不要依赖默认字体（缺 CJK 字形会变方框）",
+        "HTTP 传中文参数一律走 UTF-8 字节体，避免编码损坏"
+      ],
+      "steps": [
+        "photocraft-cli run --new '{\"width\":1080,\"height\":1440}' --cmd <背景填充/渐变命令> --out <工作空间>/poster.png",
+        "标题：Noto Sans SC，主标题字号 ≥ 120，副标题 ≤ 48；装饰条用像素层绘制",
+        "逐层 --cmd 叠加（每条 --params 作用于前一个 --cmd），最后 --out 输出 PNG 无损"
+      ],
+      "checks": ["取回产物做视觉检查：字形完整、层级清晰、四边安全区无关键内容"]
+    },
+    {
+      "id": "storyboard-color-grade",
+      "title": "分镜批量调色（一致性）",
+      "apps": ["photocraft"],
+      "goal": "整批分镜图统一色调，保持跨镜一致性",
+      "principles": [
+        "先定基调再微调：一条柔和 S 曲线 + 少量 vibrance，避免逐张各调各的",
+        "保护肤色：调整幅度宁小勿大，人脸偏色比不够风格化更伤观感",
+        "锐化放在调色之后（amount 60-80），避免锐化放大噪点",
+        "actions.json 一处定义、整批复用，保证批次内完全一致"
+      ],
+      "steps": [
+        "写 craft/grade.json：[{\"cmd\":\"layer.newAdjustmentLayer.curves\",\"params\":{\"points\":[[0,0],[64,48],[192,212],[255,255]]}},{\"cmd\":\"filter.sharpen.smartSharpen\",\"params\":{\"amount\":80}}]",
+        "photocraft-cli batch --actions <项目>/craft/grade.json --in <项目>/media --out <项目>/out/graded",
+        "抽 2-3 张对比原图检查，不满意只调曲线中段（64,48 / 192,212 两点）重跑"
+      ],
+      "checks": ["抽样对比：同场景相邻分镜色调一致；高光不过曝、暗部不死黑"]
+    },
+    {
+      "id": "vertical-reframe",
+      "title": "横转竖重构图",
+      "apps": ["filmcraft", "photocraft"],
+      "goal": "16:9 素材适配 9:16 竖屏，三种策略按画面主体选择",
+      "principles": [
+        "策略选择：主体居中 → 居中裁切；主体偏侧 → 位移裁切（保主体）；多主体/全景 → 模糊填充（上原图下补景，不裁掉信息）",
+        "人脸安全：裁切框上缘留在头顶上方 10%，下缘到胸口",
+        "分辨率对齐目标平台：抖音/快手/视频号 1080×1920@30fps"
+      ],
+      "steps": [
+        "filmcraft-cli probe <素材> 先量分辨率/时长/帧率（永远先探测再动手）",
+        "序列设 1080×1920@30，放置后按位移/缩放保留主体",
+        "导出 H.264：--quality 80 起步"
+      ],
+      "checks": ["导出后 probe 验证分辨率/时长；抽帧目检主体完整、不切脸"]
+    },
+    {
+      "id": "loudness-web",
+      "title": "网络平台响度标准化",
+      "apps": ["filmcraft"],
+      "goal": "成片响度对齐平台标准，避免用户手动调音量",
+      "principles": [
+        "主流短视频平台目标：integrated -14 LUFS，true peak ≤ -1 dBTP",
+        "导出时一次完成（file.exportMedia loudnessLufs 参数），不要二次压限",
+        "BGM 与人声分层：人声为主轨，BGM 侧链闪避 6-10 dB"
+      ],
+      "steps": [
+        "exec file.exportMedia {\"path\":<out>,\"format\":\"h264\",\"loudnessLufs\":-14,\"wait\":true}",
+        "probe 产物核对时长/编码/音轨"
+      ],
+      "checks": ["probe 报告音轨存在且响度参数已应用；多平台分发时每平台独立导出"]
+    },
+    {
+      "id": "srt-burn",
+      "title": "字幕烧录（SRT）",
+      "apps": ["filmcraft"],
+      "goal": "SRT 字幕导入并烧录进成片",
+      "principles": [
+        "单行 ≤ 15 个中文字符，超长拆条；每条最短停留 1 秒",
+        "位置：底部安全区，避开平台 UI（进度条/互动栏约占底部 15%）",
+        "样式统一：描边 2-3px 或半透明底条，全片一种字体"
+      ],
+      "steps": [
+        "exec captions.import {\"path\":<srt 绝对路径>}",
+        "可选 exec captions.setStyle {\"font\":…,\"size\":…,\"outline\":…}",
+        "exec file.exportMedia {\"path\":<out>,\"format\":\"h264\",\"burnCaptions\":true,\"wait\":true}"
+      ],
+      "checks": ["抽帧目检字幕：无溢出、无遮挡主体、时间轴同步"]
+    },
+    {
+      "id": "title-motion",
+      "title": "动态片头/花字（EffectCraft）",
+      "apps": ["effectcraft"],
+      "goal": "生成动态片头，叠加回剪辑或直接使用",
+      "principles": [
+        ".ecproj 是版本化 JSON —— 直接生成或模板替换文本，比逐帧描述高效",
+        "动画时长 1.5-3s：入场 0.3-0.5s 缓动（ease），停留 ≥ 1s，出场 0.3s",
+        "双出口：MP4 直用；或导出 Lottie 嵌网页预览；带 alpha 的 ProRes 4444 可叠进 FilmCraft 当图形层"
+      ],
+      "steps": [
+        "生成/填充 intro.ecproj（composition 尺寸对齐主序列）",
+        "effectcraft-cli render --comp Main --out <项目>/out/intro.mp4 <项目>/craft/intro.ecproj",
+        "或 exec file.exportLottie 导出 .json 给网页端播放"
+      ],
+      "checks": ["render 后 probe 时长/分辨率；视觉检查动画节奏（入场不突兀、停留可读完整标题）"]
+    },
+    {
+      "id": "delivery-pack",
+      "title": "多平台分发包",
+      "apps": ["filmcraft"],
+      "goal": "同一成片产出多平台版本（分辨率/帧率/响度/命名规范）",
+      "principles": [
+        "平台参数表：抖音/快手/视频号 1080×1920@30 -14LUFS；B 站/西瓜 1920×1080@30 -14LUFS",
+        "命名规范：<项目>_<平台>_v<序号>.mp4，一次导出成组不散落",
+        "每平台独立导出（各自过 loudness 与 probe），不要一份文件多处转发"
+      ],
+      "steps": [
+        "逐平台 exec file.exportMedia {\"path\":<out>,\"format\":\"h264\",\"width\":…,\"height\":…,\"loudnessLufs\":-14,\"wait\":true}",
+        "每个产物跑一次 probe 核对"
+      ],
+      "checks": ["probe 全部产物：分辨率/帧率/音轨符合平台表；文件命名一致"]
+    },
+    {
+      "id": "probe-verify",
+      "title": "通用纪律：先探测、后验证",
+      "apps": ["filmcraft", "photocraft", "effectcraft"],
+      "goal": "所有媒体操作的通用工作流纪律（来自专业剪辑技能的通用实践）",
+      "principles": [
+        "先探测再动手：永远先 probe 素材拿真实时长/分辨率/帧率/音轨，不从文件名猜",
+        "能无损不重编：剪切片段优先流复制，只在必须（精确剪切/滤镜/换格式）时重编码",
+        "做完必验证：产物 probe 一次 + 关键帧目检，报告里写明验证结果",
+        "诚实标注：成功是 Done、失败是 Failed，部分完成必须写出缺口"
+      ],
+      "steps": [
+        "任何处理前：filmcraft-cli probe <media>",
+        "处理后：filmcraft-cli probe <out> + 抽帧目检"
+      ],
+      "checks": ["probe 输出与预期一致；差异写入报告而不是含糊带过"]
+    }
+  ]
+}