@ninkch/dsh-artcraft 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,158 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+Format: `## [X.Y.Z] -- date`. Entries are rebuilt from git tags and commit
+history; where the record is incomplete the entry says so instead of guessing.
+
+Released versions are exactly the git tags listed below. Versions without a
+tag (planned but never published) are **not** given entries.
+
+## [0.3.1] -- 2026-10-17
+
+### Fixed
+- `fix(tools)`: pass the computed fallback `output` through to
+  `ctx.tools.register()` -- fixes issue #1, where every agent tool failed to
+  register on DSH 44.0.0 ("must declare output { schema, render,
+  presentationMeta? }") while the HTTP API kept working.
+
+## [0.3.0] -- 2026-10-16
+
+First minor bump, explicitly approved by the maintainer (recorded in
+RELEASING.md); includes everything accumulated since 0.2.10.
+
+### Added
+- `feat`: FigCraft as the 13th family member (bins whitelist, catalog card,
+  capability stats) + the first bundled craft skill pack (7 skills).
+- `feat(skills+chains)`: batch-pipeline and multicam skills, 3 more
+  task-to-command chains, English skill index, frontend contract docs.
+- `feat(qc-v2+refs)`: app-side QC checks and five deeper craft references.
+- `feat(live)`: control-channel liveness probe (`artcraft_live` +
+  `GET /artcraft/api/live`).
+- `feat(ui+recipes)`: plugins-page card shows the bundled skill pack; 3 more
+  orchestration chains.
+- `feat(api)`: capability stats and bundled skill pack over HTTP.
+- `feat(qc+skills)`: deterministic delivery QC tool (`artcraft_qc`) + 2 more
+  craft skills + deep reference files.
+- `chore(release)`: 0.3.0 release commit.
+
+## [0.2.10] -- 2026-10-12
+
+### Fixed
+- `fix(update UX)`: persistent "restart Harness to finish update" state --
+  `/update/check` reports disk-vs-running version mismatch
+  (`pendingRestart`/`pendingVersion`/`diskVersion`); the client keeps the note
+  across re-mounts and suppresses the misleading "update available" state
+  while a restart is pending.
+- `docs(RELEASING)`: GitHub-facing text must be English/ASCII-only --
+  `Invoke-RestMethod` string bodies mangled non-ASCII into `?` (Latin-1
+  fallback); always send UTF-8 bytes + charset and read the body back.
+
+## [0.2.9] -- 2026-10-12
+
+### Added
+- `feat`: family expanded to 12 apps -- WordCraft, DeckCraft, GridCraft,
+  CADCraft, SoundCraft (bins whitelist, CLI defaults, display labels, client
+  card, auto-discovery, example config, docs).
+- `feat`: capability catalog for all 12 family apps -- `apps/catalog.json`
+  (subcommands / control ports / MCP / repos from official docs and local
+  `--help`), `artcraft_apps` tool + `GET /artcraft/api/apps`, control channel
+  extended to vectorcraft (7979) and lightcraft (7980) + port passthrough.
+
+## [0.2.8] -- 2026-10-12
+
+Note: 0.2.7 was planned during this cycle but never published (no tag) -- the
+minor bump was reverted to patch-level increments; the number was reused for
+this release.
+
+### Added
+- `feat!`: bridge semantics -- no `dataRoot`; callers decide paths (chat =
+  conversation workspace, canvas = project dir); the plugins-page card shows
+  the config directory instead. (Breaking API change, shipped as a patch per
+  the versioning rule.)
+- `feat(update)`: registry fallback chain (npmjs -> npmmirror) for update
+  checks and tarball downloads -- unblocks machines without a proxy.
+- `feat`: first-run auto-discovery of family CLI installs (bootstrap config)
+  + `POST /artcraft/api/discover` + `artcraft_discover` tool.
+- `feat`: the refresh button doubles as family-install discovery (creates /
+  repairs the config); `/discover` auto-corrects stale paths.
+- `feat`: built-in expert recipes -- 8 professional workflows with
+  principles/steps/checks + the `artcraft_recipes` tool.
+
+### Changed
+- `ci`: publish via GitHub Release (OIDC) -- the maintainer pushes, no direct
+  pushes from automation.
+- `docs(RELEASING)`: forbid "Frankenstein patches" -- installed copies must
+  come from npm only.
+
+## [0.2.6] -- 2026-10-11
+
+### Added
+- `feat(update)`: deterministic tarball updater v2 (sha512 from
+  `dist.integrity` + atomic swap, bypasses the pnpm age-gate); config now
+  persists at `~/.dsh/artcraft.config.json`.
+
+### Fixed
+- `ci(guard)`: tolerate push-order races -- the main-ancestor check retries 3x
+  before failing.
+
+## [0.2.5] -- 2026-10-10
+
+### Added
+- `feat(update)`: npm-mode self-update pins the official registry; docs cover
+  the install-mode switch to npm.
+
+### Fixed
+- `fix(tools)`: `output` declaration `{ schema, render }` -- matches the host
+  requirement; verified through the poster/video integration session.
+
+### Changed
+- `ci`: new guard -- `package.json` version must match the release tag.
+- `docs(RELEASING)`: record version/tag mismatch and update-semantics lessons.
+- `fix(release)`: bump `package.json` 0.2.4 -> 0.2.5 (the version guard
+  correctly intercepted the missing bump).
+
+## [0.2.4] -- 2026-10-10
+
+### Added
+- `feat(ui)`: status card on the plugins page via the `plugins.bundle.config`
+  keyed slot; 7-family bins; EffectCraft path resolution.
+- `chore`: release governance -- dev/main branching, main-tag guard,
+  RELEASING.md rules.
+
+### Fixed
+- `fix(release)`: bump `package.json` 0.2.3 -> 0.2.4 (tag/version mismatch
+  had broken publishing).
+
+## [0.2.3] -- 2026-10-10
+
+### Fixed
+- `fix`: strip the UTF-8 BOM from `package.json` (the DSH loader's
+  `JSON.parse` rejects BOMs; the package loaded as broken).
+
+## [0.2.2] -- 2026-10-10
+
+### Fixed
+- `fix(tools)`: declare the `output` schema (the registry requires
+  `{ schema, render?, presentationMeta? }`).
+
+## [0.2.1] -- 2026-10-10
+
+### Changed
+- `feat(ui)`: move status/update into the Plugins page detail card; the
+  sidebar panel is dropped (the bridge does not belong in the main panel).
+
+## [0.2.0] -- 2026-10-10
+
+### Added
+- `feat`: self-update (check/apply) + a sidebar panel with toolchain status.
+- `ci`: npm Trusted Publishing workflow (OIDC, release-triggered).
+
+## [0.1.1] -- 2026-10-10
+
+### Added
+- `feat`: initial plugin -- PhotoCraft / FilmCraft / EffectCraft automation
+  via headless CLIs and JSON control channels (as `@local/artcraft 0.1.1`).
+- `docs`: bilingual product README (English-first + zh-CN), npm metadata.
+- `docs(license)`: Apache-2.0 for the plugin; ArtCraft apps are fair-source
+  (verbatim notice in NOTICE.md).
+- `chore!`: rename to `@ninkch/dsh-artcraft` for npm + profile registration.

package/NOTICE.md

@@ -1,72 +1,7 @@
 # Third-party notices
 
-## ArtCraft (PhotoCraft / FilmCraft / EffectCraft — getartcraft.com)
+- **ArtCraft family apps** (getartcraft.com, built by the ArtCraft team): this plugin ships none
+  of their code — it drives the apps through their public automation surfaces (headless CLI +
+  JSON control channel). The apps' own license terms apply to the apps themselves.
 
-The ArtCraft applications that this plugin drives are distributed by the ArtCraft team under the
-**ArtCraft License (WIP)** — a "fair source" license. The text below is reproduced **verbatim** as
-published by the project (~ Brandon Thomas). This plugin contains **no ArtCraft code**; it only
-drives the apps' public automation surfaces (headless CLI + JSON control channel).
-
----
-
-## ArtCraft License (WIP)
-
-(Warning: This isn't a real lawyery license full of legitimate legalese yet, but we'll take care of that ASAP.)
-
-ArtCraft is a form of "fair source" software. It's like free beer in that we give you the code, but there are a few small limitations on what you can do with it.
-
-First, what you can do with ArtCraft:
-
-You do not have to pay us to use ArtCraft. It's free.
-
-You can back up, copy, modify, compile, and use the code for your own private personal purposes.
-
-You can do anything you want with the media you create with ArtCraft. Generated assets are yours.
-
-What you can't do with ArtCraft:
-
-You cannot sell the ArtCraft software commercially (eg. as your own software).
-
-You cannot use the ArtCraft code to develop a competing business or product (eg. selling AI image and video tools).
-
-You cannot fork ArtCraft and remove ArtCraft community, donation links, or paid model services. We intend to make money to improve ArtCraft for everyone.
-
-You cannot use the ArtCraft name, logo, or mascot characters to promote your business without permission.
-
-This license means you can see what we're doing and not be at risk of having the rug pulled out from under you (eg. if our founders die, if our business collapses, if zombies or space aliens invade). It also gives you a really great way to customize the software or lend a hand in reporting (or even fixing) bugs.
-
-Our desire is to support artists, designers, and filmmakers. We want to help you build your own creative studios and businesses. We want to give you creative software you can use forever.
-
-ArtCraft is free. We do offer models available through us where you can pay us and support our development, but we also offer the ability for you to use other providers - and we'll keep adding more options so you have maximum flexibility.
-
-### Our Promise
-
-All development and business plans will be communicated openly with the community.
-
-Except for minor test scripts or a few small places where we might need to use licensed 3rd party code, all of our engineering efforts will live in a single publicly available monorepo. You can see everything we do and even benefit from using it for personal use. We plan on building a lot more than what you see today, and you'll get all of it.
-
-We will not "rug pull" our users. If our business shuts down, gets acquired, or otherwise changes, the tools we create will always continue to function in the same way.
-
-If the business ends and our founders quit working in this space, we'll make it so the software transitions to an OSI-approved open source license. (We don't intend to quit!)
-
-### Why not OSI Open Source?
-
-Philosophical answer: The OSI is an industry body led by hyperscalers. They poach from open source all the time, yet hyperscaler systems and code (AWS, GCP, YouTube, etc.) remain closed source. The tiniest nuggets are open, but the vast machinery surrounding it - systems, user behaviors, funnels, at-scale moneymakers - is totally closed.
-
-Practical answer: OSI licenses make it exceptionally challenging to grow big things commercially. And many of the licenses leave room for hyperscalers to reach in and cherry-pick pieces for themselves that they can better commercialize than the original authors.
-
-Then there's completely open source software that doesn't even attempt to be a business.
-
-We love software like Blender, but (1) developing ArtCraft is our full-time job, (2) we want to build something at scale that is much bigger than what you presently see, and (3) this will eventually become much more capital intensive than just writing code - we want to train novel models that work directly in conjunction with the user interface.
-
-If and when we do get to scale, we intend to keep every bit of our work in the open, including the models. Available for use, inspection, learning, fitting onto consumer GPU hardware, and more.
-
-Not having a way to make money is unfortunately what killed Stability.ai. Stability.ai walked so that others could eventually run. (Black Forest Labs, et al.) We're not egotistical enough to count ourselves in that party yet, but we believe in the original Stability.ai ethos and that their model can work with a few tweaks.
-
-We want to build big and incredible tools the world hasn't seen before. We want to keep them free and entirely source available. You don't have to pay us, but if you do, all of your investment goes right back into the engineering and the tools. We're writing code you can clone and keep.
-
-### Inspiration
-
-We took inspiration for this from Fair Source, Fair Code, the Defold License, and Hacker News discussions. The folks at Obsidian have some pretty good thoughts on this as well.
-
-~ Brandon Thomas
+This repository itself is **Apache-2.0** — see [LICENSE](LICENSE).

package/README.md

@@ -27,7 +27,7 @@ for agents from day one.
 This plugin brings that surface into DeepSeek Harness, so an AI agent can *operate* the apps —
 not just talk about them:
 
-- **In chat** — nine agent tools let any Harness session check the toolchain, run CLI commands,
+- **In chat** — ten agent tools let any Harness session check the toolchain, run CLI commands,
   send control-channel commands to a running app, do bridged file operations, run delivery QC,
   and consult a per-app capability catalog.
 - **A bundled craft skill pack** — eleven skills (`artcraft-ops`, `artcraft-shot-language`,
@@ -43,9 +43,6 @@ not just talk about them:
 - **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.
-- **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 →
@@ -81,7 +78,7 @@ Everything runs locally. No cloud round-trips, no accounts, no telemetry.
 - **ArtCraft apps** — grab what you need from [getartcraft.com](https://getartcraft.com/apps)
   or the [storytold GitHub releases](https://github.com/storytold). The portable/installer builds
   ship the CLI binaries on Windows and Linux (`photocraft-cli.exe` …); macOS ships them as a
-  separate notarized zip. Versions tested: PhotoCraft 0.6, FilmCraft 0.5, EffectCraft (early).
+  separate notarized zip. Versions tested: PhotoCraft 0.9, FilmCraft 0.8, EffectCraft (early).
 - Nothing else. No Python, no FFmpeg — the ArtCraft apps bring their own codecs.
 
 ## Setup
@@ -127,8 +124,8 @@ re-read on every request — no restart needed for path changes:
   "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",
+    "photocraft":  "C:/craft/<PhotoCraft portable folder>",
+    "filmcraft":   "C:/craft/<FilmCraft portable folder>",
     "effectcraft": "C:/Program Files/EffectCraft"
   },
   "control": { "filmcraft": 9876, "effectcraft": 9877 }
@@ -140,7 +137,7 @@ re-read on every request — no restart needed for path changes:
 
 ## Driving it from chat
 
-The plugin registers four tools. The agent composes them, so plain language works:
+The plugin registers ten tools. The agent composes them, so plain language works:
 
 > *"Color-grade every PNG in `demo/media` with a soft S-curve and smart sharpening at 80, put the
 > results in `demo/out/graded`."*
@@ -154,7 +151,7 @@ artcraft_cli  { bin:"photocraft", args:["batch","--actions","demo/craft/grade.js
 
 | Tool | What it does |
 |---|---|
-| `artcraft_status` | Toolchain health check: which of the 12 CLIs resolved, config location, control ports, running jobs |
+| `artcraft_status` | Toolchain health check: which of the 13 CLIs resolved, config location, control ports, running jobs |
 | `artcraft_cli` | Run any CLI subcommand synchronously (`photocraft-cli run/batch`, `wordcraft-cli convert`, …) |
 | `artcraft_control` | One command over the JSON control channel of a *running* app (filmcraft 9876 / effectcraft 9877 / vectorcraft 7979 / lightcraft 7980, or pass `port`) |
 | `artcraft_fs` | Bridged file ops — list / stat / read / write / mkdir at caller-decided absolute paths |
@@ -198,7 +195,7 @@ Full route list:
 | `POST /artcraft/api/control` | Synchronous control-channel call (`app` or `port`) |
 | `GET /artcraft/api/apps[?id=…]` | Family capability catalog (13 apps + command-family stats) |
 | `GET /artcraft/api/qc?path=…[&platform=…][&kind=…]` | Delivery QC: platform-spec checks with fix commands |
-| `GET /artcraft/api/skills` | Bundled skill pack listing (9 skills + their reference files) |
+| `GET /artcraft/api/skills` | Bundled skill pack listing (11 skills + their reference files) |
 | `GET /artcraft/api/live[?ports=app:port,…]` | Control-channel liveness (which apps are running) |
 | `POST /artcraft/api/discover` | Family install discovery + config self-repair |
 | `GET /artcraft/api/update/check` · `POST /artcraft/api/update/apply` | The plugin's own update |
@@ -332,22 +329,7 @@ explicit approval.
 
 ## License
 
-**This plugin (`@ninkch/dsh-artcraft`): Apache-2.0** — see [LICENSE](LICENSE). It ships none of the
-ArtCraft apps' code — it only drives their public automation surfaces (headless CLI + JSON
-control channel).
-
-**The ArtCraft apps themselves** are *not* OSI open source: they are distributed under the
-**ArtCraft License (WIP)**, a "fair source" license ([verbatim text](NOTICE.md)). The short
-version for anyone building on them:
-
-- ✅ free to use; back up, copy, modify and compile for private purposes
-- ✅ **every piece of media you create with the apps is yours** — your rendered episodes are
-  commercial assets, full stop
-- ❌ no selling the apps as your own software, no competing products built from their code
-- ❌ no stripping community/donation links from a fork; no using the ArtCraft name, logo or
-  mascots to promote a business without permission
-- 🤝 the team's public promise: if the business ever ends, the software transitions to an
-  OSI-approved open-source license
-
-Practical reading for an AI short-drama studio: run the apps locally, leave their community
-links alone, and sell your films — not the apps.
+This plugin (`@ninkch/dsh-artcraft`): **Apache-2.0** — see [LICENSE](LICENSE). It ships none of the
+ArtCraft apps' code; it only drives their public automation surfaces (headless CLI + JSON control
+channel). The ArtCraft apps themselves are separate projects by the ArtCraft team — the apps' own
+licenses apply to the apps.

package/README.zh-CN.md

@@ -25,7 +25,7 @@ Adobe 对标工具，共 **13 个应用**：**PhotoCraft**（Photoshop）、**Ve
 
 本插件把这套自动化面接进 DeepSeek Harness，让 AI 不只是"谈论"这些软件，而是真的**操作**它们：
 
-- **对话里** —— 九个 Agent 工具，任何 Harness 会话都能检查工具链、执行 CLI 命令、向运行中的
+- **对话里** —— 十个 Agent 工具，任何 Harness 会话都能检查工具链、执行 CLI 命令、向运行中的
   App 发控制通道命令、做桥接文件操作、跑交付质检、查每个应用的能力目录。
 - **随插件分发的技能包** —— 十一个技能（`artcraft-ops`、`artcraft-shot-language`、
   `artcraft-edit-rhythm`、`artcraft-color-light`、`artcraft-sound-design`、`artcraft-motion-vfx`、
@@ -70,7 +70,7 @@ FilmCraft 剪辑、调色、混音、烧字幕 → 导出 H.264。"生成"之后
 - **ArtCraft 应用** —— 从 [getartcraft.com](https://getartcraft.com/apps) 或
   [storytold GitHub Releases](https://github.com/storytold) 按需下载。Windows 与 Linux 的
   portable/安装包内置 CLI（`photocraft-cli.exe` 等）；macOS 的 CLI 是单独的公证 zip。
-  已验证版本：PhotoCraft 0.6、FilmCraft 0.5、EffectCraft（早期构建）。
+  已验证版本：PhotoCraft 0.9、FilmCraft 0.8、EffectCraft（早期构建）。
 - 其他什么都不需要：无 Python、无 FFmpeg —— ArtCraft 自带编解码器。
 
 ## 安装
@@ -112,8 +112,8 @@ pnpm install --dir C:/Users/<你>/.dsh/profiles/desktop
 {
   "bins": {
     // 三种写法：目录（自动拼接 <名>-cli 可执行文件）、完整 exe 路径、或走 PATH 的裸命令名
-    "photocraft":  "C:/craft/photocraft-0.6.0-windows-x64-portable",
-    "filmcraft":   "C:/craft/filmcraft-0.5.0-windows-x64-portable",
+    "photocraft":  "C:/craft/<PhotoCraft 便携目录>",
+    "filmcraft":   "C:/craft/<FilmCraft 便携目录>",
     "effectcraft": "C:/Program Files/EffectCraft"
   },
   "control": { "filmcraft": 9876, "effectcraft": 9877 }
@@ -124,7 +124,7 @@ pnpm install --dir C:/Users/<你>/.dsh/profiles/desktop
 
 ## 在对话里驱动
 
-插件注册四个工具，agent 自行编排，所以自然语言直接可用：
+插件注册十个工具，agent 自行编排，所以自然语言直接可用：
 
 > *"把 `demo/media` 里的 PNG 都用柔和 S 曲线调色、智能锐化 80，结果放进 `demo/out/graded`。"*
 
@@ -137,7 +137,7 @@ artcraft_cli  { bin:"photocraft", args:["batch","--actions","demo/craft/grade.js
 
 | 工具 | 用途 |
 |---|---|
-| `artcraft_status` | 工具体检：12 个 CLI 是否找到、配置目录、控制端口、进行中的任务 |
+| `artcraft_status` | 工具体检：13 个 CLI 是否找到、配置目录、控制端口、进行中的任务 |
 | `artcraft_cli` | 同步执行任意 CLI 子命令（`photocraft-cli run/batch`、`wordcraft-cli convert` 等） |
 | `artcraft_control` | 向**运行中**的 App 控制通道发一条命令（filmcraft 9876 / effectcraft 9877 / vectorcraft 7979 / lightcraft 7980，或 port 直连） |
 | `artcraft_fs` | 桥接文件操作 —— list / stat / 读 / 写 / 建目录，路径由调用方绝对指定 |
@@ -306,16 +306,4 @@ GitHub 上传本仓库即可：`README.md` 英文优先，附
 
 ## 许可
 
-**本插件（`@ninkch/dsh-artcraft`）：Apache-2.0**（见 [LICENSE](LICENSE)）。不包含 ArtCraft 应用的任何代码 —— 只调用其公开自动化面
-（无头 CLI + JSON 控制通道）。
-
-**ArtCraft 各应用本身并非 OSI 开源**：它们采用 **ArtCraft License (WIP)** —— 一种 "fair source"
-（公平源代码）许可（[全文见 NOTICE.md](NOTICE.md)）。给构建在其上的使用者划重点：
-
-- ✅ 免费使用；可为私人目的备份、复制、修改、编译
-- ✅ **用这些应用创作的所有媒体完全归你** —— 渲染出的短剧成片就是你的商业资产，没有附加条件
-- ❌ 不得把应用当作自己的软件出售；不得用其代码开发竞品
-- ❌ 不得在 fork 中移除社区/捐赠链接；未经许可不得用 ArtCraft 名称、Logo 或吉祥物做商业宣传
-- 🤝 团队公开承诺：若业务终结，软件将转为 OSI 认可的开源许可
-
-对 AI 短剧工作室的务实解读：本地随便用，别动应用里的社区链接，卖你的片子——而不是卖应用。
+**本插件（`@ninkch/dsh-artcraft`）：Apache-2.0**（见 [LICENSE](LICENSE)）。不包含 ArtCraft 应用的任何代码——只调用其公开自动化面（无头 CLI + JSON 控制通道）。ArtCraft 各应用本身是 ArtCraft 团队的独立项目，应用自身的条款以其许可为准。

package/apps/catalog.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "note": "ArtCraft 家族 12 应用的自动化能力目录。来源：官方 getartcraft.com/apps、各应用 GitHub 仓库（storytold/*）、本机 12 个 <app>-cli --help 实测（0.2.9 时点）。要拿某应用的实时命令注册表，用 artcraft_cli 跑该应用的 commands 子命令。",
+  "note": "ArtCraft 家族 13 应用的自动化能力目录。来源：官方 getartcraft.com/apps、各应用 GitHub 仓库（storytold/*）、本机 13 个 <app>-cli --help 实测（2026-10 时点）。要拿某应用的实时命令注册表，用 artcraft_cli 跑该应用的 commands 子命令。",
   "controlProtocol": "家族共用 JSON-lines 控制协议（127.0.0.1:<port>，请求 {\"id\",\"method\",\"params\"}，方法如 engine.execute / engine.commands / ui.inspect / ui.screenshot）。App 需以 --control 启动。artcraft_control 已代理有固定默认端口的应用；其余应用端口动态（app --port 启动时指定），可用 artcraft_control 的 port 参数直连。",
   "apps": [
     {
@@ -325,21 +325,21 @@
     }
   ],
   "capabilityStats": {
-    "note": "2026-10 实测：本机 13 个成员 CLI 的命令注册表规模与主要命令族。JSON 注册表入口（filmcraft / effectcraft / photocraft / gridcraft / wordcraft / figcraft 用 commands --json）为精确条目数，其余为 id 扫描值（近似）。用 artcraft_cli 跑 commands 可随时复核。",
+    "note": "2026-10-25 实测（家族全量更新后：photocraft 0.15.1 / vectorcraft 0.16.0 / filmcraft 0.12.0 / lightcraft 0.13.0 / pdfcraft 0.13.0 / effectcraft 0.16.0 / designcraft 0.12.0 / wordcraft 0.10.0 / deckcraft 0.10.0 / gridcraft 0.11.1 / cadcraft 0.12.0 / soundcraft 0.12.1 / figcraft 0.10.0）。JSON 注册表入口（filmcraft / effectcraft / photocraft / gridcraft / wordcraft / figcraft 用 commands --json）为精确条目数，其余为 id 扫描值（近似）。用 artcraft_cli 跑 commands 可随时复核。",
     "apps": {
-      "photocraft": { "commands": 364, "topFamilies": ["filter 62（gallery 47 / blur 11 / stylize 9 / distort 9 / render 9）", "edit 31", "layer 26", "select 19", "file.automate 18", "channel 18", "actions 14", "image.adjustments 9"] },
-      "vectorcraft": { "commands": 385, "topFamilies": ["object 71", "perspective 24", "select 18", "file 17", "swatch 15", "document 12", "layer 11", "path 11", "symbol 10", "dataset 10"] },
+      "photocraft": { "commands": 935, "topFamilies": ["filter 62（gallery 47 / blur 11 / stylize 9 / distort 9 / render 9）", "image.adjustments 9", "layer 26", "edit 31", "select 19", "paint 12", "brush 13", "gradient 12", "type 9", "shape 9", "path 9", "pattern 10", "file.automate 18", "channel 18", "actions 14", "swatches 9", "slice 6", "select.refineEdge（0.15 参数化选择与遮罩）"] },
+      "vectorcraft": { "commands": 404, "topFamilies": ["object 71", "perspective 24", "select 18", "text 10", "variable 9", "brush 9", "library 9", "print 9", "pdf.preset 5", "flattener 6", "swatch 15", "document 12", "layer 11", "path 11", "symbol 10", "dataset 10", "shaper 4"] },
       "filmcraft": { "commands": 701, "topFamilies": ["graphics 82", "clip 57", "file 57", "timeline 56", "sequence 45", "project 40", "edit 39", "multicam 35", "markers 32", "trim 24", "captions 22", "mixer 20", "export 19", "effects 16", "transcript 14", "masks 12", "essentialSound 9", "lumetri 7", "tts 7", "lut 4"] },
-      "lightcraft": { "commands": 192, "developControls": 122, "topFamilies": ["library 20", "faces 17", "denoise 16", "develop 16（122 个控制 / 14 分区）", "photo 14", "mask 12", "keyword 12", "preset 9", "crop 6", "stack 6"] },
-      "pdfcraft": { "commands": 71, "topFamilies": ["edit 13", "page 10", "measure 7", "a11y 5", "export 4", "ocr 3", "form 3", "comment 3", "protect 2", "sign 2"] },
-      "effectcraft": { "commands": 731, "effects": 307, "topFamilies": ["layer 121", "view 78", "file 61", "keys 36", "comp 31", "edit 27", "track 22", "essential 22", "renderQueue 20", "effect 19", "camera 19", "prop 18", "mask 17", "time 17", "roto 14", "text 13", "puppet 10"], "exportFormats": ["H264", "Hevc", "Av1", "ProRes", "Uncompressed", "WebM", "PngSequence", "JpegSequence", "TiffSequence", "ExrSequence", "Gif", "Wav", "Aiff"], "expressions": true, "scripting": true },
-      "designcraft": { "commands": 279, "topFamilies": ["object 22", "style 17", "file 15", "transform 10", "data 10", "type 10", "library 8", "layout 7", "book 7", "edit 7", "text 7", "layer 7", "table 7", "article 6"] },
-      "wordcraft": { "commands": 299, "topFamilies": ["para 28", "format 25", "file 18", "review 16", "equation 15", "insert 15", "table 14", "view 13", "select 12", "picture 11", "styles 11", "references 10", "mailings 9"] },
-      "deckcraft": { "commands": 165, "topFamilies": ["format 32", "shape 19", "slide 15", "file 13", "animation 10", "text 10", "edit 9", "media 7", "insert 7", "arrange 7", "design 5", "transition 4"] },
-      "gridcraft": { "commands": 115, "topFamilies": ["home 12", "pivot 11", "insert 10", "data 10", "view 9", "sheet 8", "edit 7", "file 7", "selection 6", "formulas 5", "chart 3", "slicer 3"] },
-      "cadcraft": { "commands": 139, "topFamilies": ["table 11", "arc 10", "zoom 9", "dimstyle 7", "blocks 6", "grip 6", "layout 6", "layerstate 5", "vports 5", "circle 5", "dimtedit 5"] },
-      "soundcraft": { "commands": 478, "topFamilies": ["view 96", "edit 93", "track 65", "event 35", "options 35", "clip 31", "mix 29", "setup 20", "file 17", "transport 13", "session 11（含 audio_health）", "automation 10"] },
-      "figcraft": { "commands": 552, "topFamilies": ["text 52", "view 48", "vector 40", "object 27", "tool 21", "select 21", "component 21", "collab 20", "file 20", "proto 20", "library 18", "variable 18", "edit 15", "comment 14", "plugin 11", "style 10"] }
+      "lightcraft": { "commands": 227, "developControls": 122, "topFamilies": ["print 17（打印版式模板：cell/layout/template）", "slideshow.export", "library 20", "faces 17", "denoise 16", "develop 16（122 个控制 / 14 分区）", "photo 14", "mask 12", "keyword 12", "preset 9", "crop 6", "stack 6"] },
+      "pdfcraft": { "commands": 79, "topFamilies": ["edit 13", "page 10", "measure 7", "a11y 5", "export 4", "ocr 3", "form 3", "comment 3", "protect 2", "sign 2", "create 1（新建 PDF）", "text_edit 1"] },
+      "effectcraft": { "commands": 731, "effects": 307, "topFamilies": ["layer 121", "view 78", "file 61", "keys 36", "comp 31", "edit 27", "track 22", "essential 22", "renderQueue 20", "effect 19", "camera 19", "prop 18（0.13.0 起属性读写统一走 prop.get/set，effect.setParam 已移除）", "mask 17", "time 17", "roto 14", "text 13", "puppet 10", "face 5（0.13 新增）", "learn 5（0.13 新增）"], "exportFormats": ["H264", "Hevc", "Av1", "ProRes", "Uncompressed", "WebM", "PngSequence", "JpegSequence", "TiffSequence", "ExrSequence", "Gif", "Wav", "Aiff"], "expressions": true, "scripting": true },
+      "designcraft": { "commands": 311, "topFamilies": ["object 22", "style 17", "file 15", "transform 10", "data 10", "type 10", "toc 3（目录）", "footnote 4（脚注）", "xref 3（交叉引用）", "index 3（索引）", "preflight.run（印前检查）", "condition 5（条件样式）", "flex 5", "layout 7", "book 7", "article 6"] },
+      "wordcraft": { "commands": 638, "topFamilies": ["para 28", "format 25", "file 18", "review 16", "caret 7", "edit 10", "outline 8", "layout 7", "fields 6", "arrange 9", "draw 9", "canvas 4", "chart 3", "shape 6", "equation 15", "insert 15", "table 14", "styles 11", "references 10"] },
+      "deckcraft": { "commands": 209, "topFamilies": ["format 32", "shape 19", "slide 15", "file 13", "animation 10", "text 10", "picture 9", "comment 7", "review 7", "table 5", "chart 3", "design 5", "transition 4", "handout 1", "master 2"] },
+      "gridcraft": { "commands": 346, "topFamilies": ["home 12", "pivot 11", "insert 10", "data 10", "cell 2", "range 1", "table 3", "object 2", "link 1", "draw 4", "arrange 3", "review 2", "formulas 5", "chart 3", "window 1"] },
+      "cadcraft": { "commands": 139, "topFamilies": ["table 11", "arc 10", "zoom 9", "dimstyle 7", "blocks 6", "grip 6", "layout 6", "layerstate 5", "vports 5", "circle 5", "dimtedit 5", "compare 2", "quickcalc 1"] },
+      "soundcraft": { "commands": 480, "topFamilies": ["view 96", "edit 93", "track 65", "event 35", "options 35", "clip 31", "mix 29", "setup 20", "file 17", "transport 13", "session 11（含 audio_health）", "automation 10", "midi 6（0.10 新增）", "video 3（0.10 新增）", "audiosuite 1"] },
+      "figcraft": { "commands": 569, "topFamilies": ["text 52", "view 48", "vector 40", "object 27", "tool 21", "select 21", "component 21", "collab 20", "file 20", "proto 20", "library 18", "variable 18", "edit 15", "comment 14", "plugin 11", "style 10"] }
     }
   }
 }

package/artcraft.config.json.example

@@ -1,8 +1,8 @@
 {
   "bins": {
-    "photocraft": "D:/craft/photocraft-0.6.0/photocraft-0.6.0-windows-x64-portable",
+    "photocraft": "C:/craft/<PhotoCraft portable folder>",
     "vectorcraft": "C:/Program Files/VectorCraft",
-    "filmcraft": "D:/craft/filmcraft-0.5.0/filmcraft-0.5.0-windows-x64-portable",
+    "filmcraft": "C:/craft/<FilmCraft portable folder>",
     "lightcraft": "C:/Program Files/LightCraft",
     "pdfcraft": "C:/Program Files/PdfCraft",
     "effectcraft": "C:/Program Files/EffectCraft",

package/client.js

@@ -118,6 +118,29 @@ window.__ModuleLoader__.load({
         finally { if (alive.current) setBusy(''); }
       }, []);
 
+      // 一键自动探测（AC-04）：POST /discover 做缺失项填空 + 失效路径纠正；
+      // 用户显式配置有效则原样不动（服务端保证），失败/无动作都有明确文案，不静默。
+      const runDiscover = useCallback(async () => {
+        setBusy('discover'); setOut(''); setDone(false);
+        try {
+          const r = await api('/discover', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}' });
+          if (!alive.current) return;
+          const applied = r.applied ?? {};
+          const appliedNames = Object.keys(applied).map((k) => LABELS[k] || k);
+          setOut(
+            (r.note || '') + '\n' +
+            (appliedNames.length
+              ? '本次写入配置：' + appliedNames.join('、') + '\n'
+              : '没有需要更新的家族程序（已有配置均有效）\n') +
+            '已探测到本机安装：' + (Object.keys(r.discovered ?? {}).map((k) => LABELS[k] || k).join('、') || '（无）') + '\n' +
+            '配置文件：' + (r.configPath || '（未知）'),
+          );
+          loadStatus(); // 探测写盘后立即重读 bins 状态，灯色即变
+        } catch (e) {
+          if (alive.current) setOut('自动探测失败：' + String(e.message || e) + '（可检查插件是否注册、或手动编辑 artcraft.config.json）');
+        } finally { if (alive.current) setBusy(''); }
+      }, [loadStatus]);
+
       useEffect(() => { loadStatus(); checkUpdate(); }, [loadStatus, checkUpdate]);
 
       const bins = status?.bins ?? {};
@@ -153,6 +176,9 @@ window.__ModuleLoader__.load({
             (upd?.pendingRestart ? '（磁盘已是 v' + (upd.pendingVersion ?? upd.diskVersion ?? '?') + '，待重启）' : '') +
             (upd ? ' · npm latest v' + (upd.latest ?? '—') : '') +
             (upd?.mode ? '（' + (upd.mode === 'git' ? 'git 仓库' + (upd.gitClean === false ? ' · 有本地改动' : '') : 'npm 安装') + '）' : '')),
+          h('button', { className: 'dshac-btn', onClick: runDiscover, disabled: busy !== '',
+            title: '自动探测本机 ArtCraft 家族安装位置：缺失项填入配置，已失效的路径被纠正；你的显式有效配置不会被覆盖' },
+            busy === 'discover' ? '探测中…' : '自动探测'),
           h('button', { className: 'dshac-btn primary', onClick: checkUpdate, disabled: busy !== '' },
             busy === 'check' ? '检查中…' : '检查更新'),
           h('button', {

package/index.js

@@ -55,7 +55,7 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 
 const NAME = 'artcraft';
-const VERSION = '0.3.1';
+const VERSION = '0.3.3';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
 const BINS = [
@@ -183,11 +183,13 @@ 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 + 相对路径组合）');
+  if (!path.isAbsolute(s)) {
+    throw new Error(
+      `需要绝对路径，收到相对路径 "${s}" —— 本插件不持有数据目录，不会按进程 cwd 解析；`
+      + '请改传绝对 path=<绝对路径>，或用 base=<绝对目录> + rel=<相对路径>。',
+    );
   }
-  return abs;
+  return path.normalize(s);
 }
 
 function resolveBaseRel(base, rel) {
@@ -364,7 +366,7 @@ async function statOutputs(outputs, cwd) {
     try {
       abs = base ? path.resolve(base, spec) : resolveCallerPath(spec);
     } catch {
-      out.push({ rel: spec, exists: false, dir: false, size: null, mtime: null });
+      out.push({ rel: spec, exists: false, dir: false, size: null, mtime: null, reason: 'relative-output-without-cwd' });
       continue;
     }
     try {
@@ -1038,6 +1040,9 @@ async function updateApply() {
 const toolNames = [];
 const toolErrors = [];
 
+/** 单测钩子：只暴露纯函数，不改运行时行为（scripts/test-fs-paths.mjs 使用） */
+export const __testables = { resolveCallerPath, resolveBaseRel, statOutputs };
+
 export const inject = ['tools', 'webServer'];
 
 export function apply(ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninkch/dsh-artcraft",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "Drive the open-source ArtCraft studio suite (13 family apps: PhotoCraft, VectorCraft, FilmCraft, LightCraft, PdfCraft, EffectCraft, DesignCraft, WordCraft, DeckCraft, GridCraft, CADCraft, SoundCraft, FigCraft) from DeepSeek Harness: agent tools, a same-origin HTTP API, a bundled craft skill pack, and plugins-page status with self-update.",
   "keywords": [
@@ -26,6 +26,9 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "selftest": "node scripts/selftest.mjs"
+  },
   "exports": {
     ".": "./index.js",
     "./client": "./client.js",
@@ -41,6 +44,7 @@
     "artcraft.config.json.example",
     "apps",
     "recipes",
+    "CHANGELOG.md",
     "README.md",
     "README.zh-CN.md",
     "NOTICE.md"

package/skills/README.md

@@ -1,6 +1,6 @@
 # ArtCraft craft skill pack (bundled with @ninkch/dsh-artcraft)
 
-Eleven skills ship inside this plugin. They are registered through the plugin's own skill
+Twelve skills ship inside this plugin. They are registered through the plugin's own skill
 provider (`@ninkch/dsh-artcraft/skills`) and load on demand — you never install them separately.
 
 Skill bodies are written in Chinese (the maintainer's language and the language of the rest of the
@@ -20,6 +20,7 @@ so you know which skill to open.
 | `artcraft-film-study` | Shot-by-shot film study: 8-step method, shot-table schema, emotion-score criteria, traceable conclusions, report template | Analysing an existing film (review/research) |
 | `artcraft-batch-pipeline` | Batch and pipeline work: headless batch formats, HTTP job queue, in-app queues, proxies and cache, media health/relink, incremental and resumable runs, retries, QC hook-up | Dozens/hundreds of files, a whole season |
 | `artcraft-multicam` | Multicam: build sources, align, grid browsing, `selectCamera*` vs `cutToCamera*`, live switching, audio-follows-video, cross-camera matching, switching rhythm | Interviews, concerts, live cuts |
+| `artcraft-director-lens` | 20 director lenses (Spielberg…Wong Kar-wai, Zhang Yimou, Bi Gan…): each maps a director's working method to ArtCraft parameters — ASL targets, transition bias, light ratio, palette→mixer channels, sound rules, QC hooks. | "Cut/grade this like <director>", style bible references a lens |
 
 ## Reference files (loaded with a skill)
 

package/skills/artcraft-color-light/SKILL.md

@@ -16,7 +16,7 @@ description: 影调与调色决策——一级（曝光/对比/白平衡/饱和
 | 3 | 白平衡（色温/色调） | 矢量示波器：肤色线附近 | 偏黄/偏青不察 |
 | 4 | 饱和 / 自然饱和度 | 矢量示波器不越界 | 过饱和→溢出结块 |
 
-**LightCraft 落点（122 控制 / 14 分区）**——标准冲洗顺序：
+**LightCraft 落点（122 控制 / 14 分区，0.10 未变）**——标准冲洗顺序：
 
 ```
 profile.amount → wb.temp / wb.tint → light.exposure / light.contrast /
@@ -32,6 +32,8 @@ geometry.*（透视/旋转/裁切）→ effects.texture/clarity/dehaze → grain
 
 **PhotoCraft 落点**：`image.adjustments.exposure/levels/curves/vibrance/desaturate`；RAW 走 `filter.cameraRaw`；批量一致性用 `actions.record → actions.save → file.automate.batch`。
 
+**打印版式（LightCraft 0.10 新增）**：`print.template.list/apply/save` + `print.cell.*` + `print.layout`——把冲洗结果按版式模板排进打印页；`slideshow.export` 直接出幻灯片。
+
 ## 二、二级校色与局部
 
 | 手法 | 何时用 | 落点 |