dsh-comfyui 0.3.0-beta.5 → 0.3.0-beta.6

package/README.en.md

@@ -8,7 +8,7 @@
 
 <h1 align="center">dsh-comfyui</h1>
 
-<p align="center">Let the DeepSeek Harness agent drive your ComfyUI server directly to generate and process images and videos.</p>
+<p align="center">Let the DeepSeek Harness agent smartly drive a local or remote ComfyUI to generate anything — with workflow and asset management panels, per-workflow skill packs, a companion skill and a same-origin media proxy.</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/dsh-comfyui"><img src="https://img.shields.io/npm/v/dsh-comfyui" alt="npm version" /></a>
@@ -20,206 +20,94 @@
 
 ### Agent tools
 
-- `comfyui_run` — submit a ComfyUI API-format workflow, or pick a built-in template, and get the generated media back. Two modes: `sync` (wait and return media) and `async` (start a background job, collect with `job_output` — ideal for video).
-- `comfyui_object_info` — list the node definitions of your ComfyUI server so the agent can build valid workflows on the fly.
-- `comfyui_workflow` — list and run runnable workflows from the plugin library. `action: list` also reports your ComfyUI server address and local install dirs (the `env` field), plus graph workflows you saved on the ComfyUI server and whether each has been **extracted** into runnable workflows; unextracted graphs are flagged so the agent tells you to extract them in the panel first. `action: refresh` re-derives one workflow's parameter snapshot by id and saves it back (force-rescans the TTS voice library first, then updates option/number metadata from the current node definitions) — run it after the voice library or node definitions changed.
+The agent drives ComfyUI directly, no canvas work needed:
+
+- `comfyui_run` — submit an API-format workflow or a built-in template (`txt2img` / `img2img` / `video`) and get media back; `mode: "sync"` waits for the result, `mode: "async"` runs a background job (recommended for video).
+- `comfyui_object_info` — list the node definitions your ComfyUI server supports, so the agent can build valid workflows on the fly.
+- `comfyui_workflow` — manage the plugin's runnable-workflow library: `list` (server address, local ComfyUI dirs, load-area media, per-workflow parameter lists), `run` (by id + parameter overrides), `skill` (on-demand read of a workflow's skill pack), `refresh` (re-derive a parameter snapshot).
+- `comfyui_skill` — read and write workflow skill packs (`list` / `read` / `write` / `append` / `mkdir` / `rename` / `delete` / `enable` / `require`); the agent can write its lessons back into a pack and reuse them across sessions.
 
 ### UI panel
 
-Right-docked; open from the sidebar rail — three tabs:
+A right-docked panel with three tabs:
 
-- **Workflows** — the plugin library of runnable (API) workflows: create / edit / run / delete, plus "Import file" to load an API-format `.json` directly. The **ComfyUI-saved graphs** section auto-detects graph workflows you saved in ComfyUI, shows which runnable workflows were extracted from each, and offers **extract** with per-graph analysis: a canvas often holds several independent flows, so you choose extract all / extract per component / extract main flow only. Workflows can be classified with **tags** (see below).
-- **Assets** — everything the plugin generated, newest first, with a detail view and download links. Hovering a card reveals a red trash button; it opens a confirmation dialog listing the files, and confirming removes the index record and deletes the matching files from the ComfyUI output directory. ComfyUI itself has no API for deleting output files, so the plugin touches the filesystem directly: files are only really deleted when DSH can reach that directory (same-machine installs); otherwise just the record goes and the dialog says so.
-- **Queue** — a task center over ComfyUI's unified jobs API (`/api/jobs`): every task across the live queue **and** history in five states (pending / in progress / completed / failed / cancelled), filterable by state, with per-task progress bars (plugin-submitted jobs), preview thumbnails, failure messages and duration, plus actions — delete, interrupt, rerun, clear queue/history, free memory. Tasks the plugin queued are marked with their workflow name.
+- **Workflows** — the runnable workflow library (create / edit / run / delete / import `.json`, tag classification with a dropdown filter); auto-detects graphs saved on the ComfyUI server and can **extract** them into runnable workflows (whole / per component / main flow only when a canvas holds several independent flows).
+- **Assets** — every generated result with preview, download, and hover-to-delete (also removes the file from the ComfyUI output directory).
+- **Queue** — live queue plus full history in five states, with delete / interrupt / rerun / clear / free-memory actions; plugin-submitted jobs show a progress bar and preview.
 
 <p align="center"><img src="images/panel.png" width="70%" alt="Main panel: workflows / assets / queue" title="Main panel: workflows / assets / queue" /></p>
 
-### Load area
-
-A media loader in the style of ComfyUI's LoadImage node, sitting at the top of the Workflows tab: besides images, the picker also lists the video and audio files available to the ComfyUI loader nodes (LoadVideo / LoadAudio).
-
-- **Multiple slots**: the load area is a list of slots — a lone slot stretches across the panel, two or more share a fixed width and wrap into rows. "+ Add slot" at the bottom appends one; an empty slot reads "Slot N / Add media" and fills on click; hovering a slot reveals an **×** in its corner that deletes it, and the picker's first tile ("None") empties a slot while keeping it. Filled slots fill the workflow's unset loader parameters in order — a two-reference workflow just needs two slots, with no file names for the agent to guess.
-- Clicking any slot opens a picker window with a nav bar (All / Imported / Generated), a type filter, a paste/upload drop zone on the right, and a masonry grid of every loadable image / video / audio file in the ComfyUI `input` directory plus everything the plugin generated. **Video and audio play right in the card** (clicking the player only plays, it never selects); clicking the file name under a card picks it and closes the window. File kind is decided by extension, and each loader's input key is read from the ComfyUI node definition (`LoadImage.image` / `LoadVideo.file` / `LoadAudio.audio`), so no media type goes missing.
-- Load-area media are the **default inputs**: unset loader parameters are filled from the slots in order (slot 1 → first image parameter, slot 2 → second; video/audio parameters take slots of their own kind) — the agent does not need to name a file. Parameters with no matching slot keep the workflow's authored value.
-- **Visible to the agent**: `comfyui_workflow action: list` reports a `loadArea` field (slot count, how many are filled, and the file list), so the agent knows what the user loaded without asking.
-- **Resolution auto-match**: uploads record their pixel size; when a run leaves `width`/`height` unset, they default to the source image's actual size.
-- **Hash naming + dedup**: uploads are renamed to `original_shorthash.ext` (SHA-256 first 10 hex); re-uploading an identical file reuses the existing name instead of storing a duplicate. The picker refreshes live after uploads.
-- Selecting a **generated** image copies it from the output directory into `input` on the fly, so image-loading nodes can use it.
-
-<p align="center"><img src="images/loadarea.png" width="70%" alt="Load area: image picking and upload" title="Load area: image picking and upload" /></p>
-
-### Workflow tags
-
-Classify runnable workflows with preset categories (image-to-image / text-to-image / text-to-video / image-to-video / reference-to-video / text-to-audio / reference-to-audio) plus any custom tags. Tags are edited in the workflow editor, shown on the top-right of each card, and the library list has a filter bar with per-tag counts.
-
-### Built-in templates
-
-`txt2img` (SDXL text-to-image), `img2img` (SDXL image-to-image), `video` (Wan 2.1 text-to-video via ComfyUI-WanVideoWrapper). Template node ids are documented in the tool description so the agent overrides the right inputs.
-
-### Media proxy
-
-Generated files are addressed by `filename + subfolder + type` and stream through a same-origin route (`/comfyui/media`), never through ComfyUI's in-memory history — older results in the asset panel keep opening after a ComfyUI restart or a history clear, as long as the file is still in the output directory. The browser never talks to ComfyUI directly: no CORS, no mixed-content, no API key in the page, and remote ComfyUI installs work unchanged. The media URL base is auto-detected: on every page load the browser self-reports the origin it actually uses via `/comfyui/ping` (LAN IP / domain / reverse proxy all produce working links), or you can pin it explicitly with the `mediaHost` config key.
-
-### Tool card
-
-Results render as a media wall (images/videos with download links) right in the chat, including background-job status.
-
-### Settings page
-
-A ComfyUI section in the DH settings where you can edit the server URL (`baseUrl`), API-key env var (`apiKeyEnv`), media base URL (`mediaHost`), the local ComfyUI install directories (`comfyuiDirs`, multiple allowed — mapped dirs / multiple installs; the agent uses them to locate your ComfyUI files and the TTS voice library without asking), test the connection, and switch the plugin UI language (Chinese / English — stored in the browser, applies to the whole plugin UI), all without touching `cordis.yml`. The data directory and asset cap are configured in `cordis.yml` only and are not exposed in the settings page.
-
-<p align="center"><img src="images/settings.png" width="70%" alt="ComfyUI settings page (with UI language switch)" title="ComfyUI settings page (with UI language switch)" /></p>
-
-### Companion skill
-
-A runtime skill (`dsh-comfyui-workflows`) registered through `ctx.skills.register`: the agent learns the graph-vs-runnable model, canvas analysis rules (connected components, bypassed groups, dangling nodes), when to ask you about extract mode, and the extraction tech rules. The skill also carries the **local environment** story (read `env.comfyuiDirs` from `comfyui_workflow list`) and the **TTS-Audio-Suite voice-library workflow** (one unified flow: refresh the snapshot first, then query — refresh via the `/api/tts-audio-suite/voice-library?refresh=1` endpoint plus `action: refresh` to re-derive and write the snapshot back; query prefers the HTTP endpoint, otherwise lists `{comfyuiDir}/models/voices` etc.; a new voice rejected at run time = stale snapshot), so the agent never has to dig through the plugin's source again.
+### Load area (media loader)
 
-### Graph workflows vs runnable workflows
+A media loader at the top of the Workflows tab, in the style of ComfyUI's LoadImage node: visual picking (with in-place playback for video/audio), paste/upload, and multiple slots. Filled slots fill the workflow's unset loader parameters in order — **the agent doesn't need to guess file names**; unset `width`/`height` auto-match the source image's size. Uploads are renamed by content hash (dedup).
 
-ComfyUI works in two layers:
+The `loadArea` field of `comfyui_workflow list` exposes the slots and their contents to the agent.
 
-- **Graph workflow** — the UI graph you save in ComfyUI (nodes/links/widgets). It is a source, not directly runnable, and a single canvas is often a **test bench holding several independent flows at once**. Visual `groups` are just rectangles — the real executable unit is a **connected component** over the links, with bypassed (`mode 4`) and dangling nodes excluded.
-- **Runnable workflow** — an API-format prompt, the actual execution unit. You get one by **extracting** it from a graph (1 graph → N runnable workflows) or by pasting/importing an API `.json` directly.
+### Workflow skill packs (a manual for the agent)
 
-The **extract** flow analyzes the canvas first (components with their node counts and group membership, bypassed/dangling counts) and lets you pick:
+A parameter list tells the agent which knobs exist, not what the workflow is *for* or which step goes wrong. A complex workflow can carry a **skill pack** (enable it from the "Skill pack" button on the workflow card):
 
-- **Extract all** — merge every component into one runnable workflow (everything executes together).
-- **Extract per component** (recommended) — one runnable workflow per independent flow.
-- **Extract main flow only** — the largest component only (usually the flow under test).
-
-Extraction follows the live `/object_info`: rewires Reroute/bypass pass-throughs, maps widget values (including dynamic sub-widgets and `control_after_generate`), inlines primitives, drops stale slot references with a warning, skips components with no output node, and fails loudly when a required input was never wired — every extracted workflow is validated by `POST /prompt` (zero `node_errors`) before it is stored.
-
-### Adjustable parameters
-
-Every runnable workflow carries an adjustable **parameter set** (`parameters`) so one workflow can produce different results per run:
+```
+<data dir>/skills/<workflow>/
+  SKILL.md          # main doc: when to use / key parameters / gotchas
+  references/       # reference docs: style catalogs, troubleshooting
+  assets/           # reference images etc (previewable in the panel)
+```
 
-- **Auto-detected (conservative)**: prompt text inputs, resolution (`EmptyLatentImage` width/height), sampler steps (`KSampler.steps`), and seed (`KSampler.seed`, randomized per run by default). Sampling-related inputs (cfg/denoise) and model selections stay as authored.
-- **Advanced parameters**: the panel's workflow editor can expose any node input as a custom parameter (pick node → pick input → name it), and edit each parameter's name, label, default, and random toggle. The list offers every widget value of the node (a loader's `upload` entry included); inputs currently driven by a link are left out, since they carry no editable value and exposing one would only fight the connection.
-- **Boolean parameters use a checkbox**: pick `true` / `false` directly; at run time the `"true"` / `"false"` / `0` / `1` spellings are accepted too (defaults stored as strings by older versions are normalized instead of being silently dropped).
-- **Int vs. float number parameters**: the declared input type (`INT` / `FLOAT`) is read from the ComfyUI node definition, so FLOAT inputs like `cfg` or `denoise` accept decimals while INT inputs like `steps` or `seed` are rounded at run time; unknown types are treated as decimals. Each row shows `number/int` or `number/float`, with range and step in the tooltip.
-- **Agent-facing**: the parameter list is written into the workflow's input notes (`inputs` field) and shown by `comfyui_workflow` `action: list`; `action: run` accepts `parameters: {"prompt": "...", "seed": 42}` overrides — explicit values win over random/default, omitted parameters use their defaults.
-- **Parameter snapshot & refresh**: a parameter's options/number metadata (`options`, `numberKind`, …) is copied from the ComfyUI node definitions **at save time** and is never auto-updated afterwards (noticeable with growing lists like the voice library or uploaded files). Refresh it via `comfyui_workflow action: refresh { id }`, or — from other programs — the same-origin route `POST /comfyui/workflows/refresh-params` (body `{ "id": ... }`). Refreshing only touches derived fields; your hand-added advanced parameters and authored defaults are preserved. Until refreshed, `action: list` may be missing new voices and `action: run` will reject them.
-- **Load-area integration**: an unset image-type parameter is filled with the load-area's current source image, and unset `width`/`height` are auto-matched to that image's recorded pixel size. Explicit values always win, so the agent can still override both.
+- **Progressive disclosure, no resident context cost**: `comfyui_workflow list` shows one summary line → `action: skill` fetches the SKILL.md body once the workflow is chosen → a referenced document is read only when the body points at it. Dozens of workflows can carry full packs, and the daily context cost stays one line each.
+- **Edited in the panel**: file list + editor, import (auto-bucketed by extension), custom subdirectories, image preview, and the whole pack root can be moved to another drive / a synced folder (the `技能包目录` setting).
+- **The agent can write it too**: the `comfyui_skill` tool lets the agent read and author a pack — `append` a pitfall to SKILL.md and the next session (even another one) reuses that experience.
+- **Read-before-run**: a "required" flag makes `run` refuse until the skill pack has been read in this session, with an error pointing to `action: skill`.
 
-## Requirements
+### Media proxy & settings
 
-- DeepSeek Harness (web / desktop profile) — the plugin targets the `web` and `desktop` profiles (web side requires `@deepseek-ai/dsh-web-app` ≥ 0.1.0-rc.6).
-- A running [ComfyUI](https://github.com/comfystack/ComfyUI) server (default `http://127.0.0.1:8188`).
-- For the `video` template: the [ComfyUI-WanVideoWrapper](https://github.com/kijai/ComfyUI-WanVideoWrapper) custom nodes and Wan 2.1 model files.
+Generated files are served through a same-origin route (`/comfyui/media`) addressed by file name, independent of ComfyUI's in-memory history — old results keep opening after a restart or a history clear. The browser never touches ComfyUI directly: no CORS, no mixed content, and the API key never leaves the host.
 
-## Installation
+The DH settings page gets a "ComfyUI" section: server address, API key env var name, local ComfyUI directories, media host, connection test and a zh/en UI language switch — applied immediately, no `cordis.yml` edits needed.
 
-Web profile:
+## Install
 
 ```sh
+# web profile
 dsh plugin --profile web add dsh-comfyui
+# desktop profile
+dsh plugin --profile desktop add dsh-comfyui
 ```
 
-Desktop profile:
+After restarting the app: a panel entry appears in the sidebar, a "ComfyUI" section in settings, and the agent gets all tools plus the companion skill right away.
 
-```sh
-dsh plugin --profile desktop add dsh-comfyui
-```
+## Usage
 
-Then restart the corresponding app (web server or desktop app; host-side rows mount at boot). The panel trigger appears in the sidebar rail, the settings section "ComfyUI" appears in the settings page, and the agent gains `comfyui_run`, `comfyui_object_info`, `comfyui_workflow`, and the `dsh-comfyui-workflows` skill immediately.
+Just tell the agent, e.g.:
 
-### API key (remote servers)
+- "Draw a red cat with ComfyUI"
+- "Turn this image into cyberpunk style"
+- "Turn the anime image in the load area into a photorealistic portrait, same resolution"
+- "Generate a 5-second clip: city at sunset"
+- "Run my Krea-Afterlight saved in ComfyUI" (if the graph isn't extracted yet, the agent will ask you to **extract** it in the panel first)
 
-For a remote ComfyUI behind an authenticating proxy, provide the key through the credentials store or an environment variable named by `apiKeyEnv` (default `COMFYUI_API_KEY`). The key is resolved per request on the host and never sent to the browser.
+For a remote ComfyUI behind an authenticated proxy, provide the key via credential storage or the `apiKeyEnv` env var (default `COMFYUI_API_KEY`) — it is resolved on the host and never sent to the browser.
 
-## Usage
+## Configuration
 
-Ask the agent, e.g.:
-
-- "Generate a red cat image with ComfyUI"
-- "Turn this image into cyberpunk style" (img2img with an input image filename)
-- "Turn the anime girl in the load area into a realistic photo, matching the original resolution" (load-area source image + resolution auto-match)
-- "Generate a 5-second clip of a city at sunset" (video; needs the Wan wrapper)
-- "Run my Krea-Afterlight workflow saved in ComfyUI" — the agent lists server-side graphs; if yours is not extracted yet it will tell you to click **extract** in the panel first (a canvas may contain several independent flows, so you can extract all as one, per component, or the main flow only).
-
-The agent picks a template, inspects your server with `comfyui_object_info`, or runs a library workflow with `comfyui_workflow`.
-
-### Configuration
-
-The plugin reads a `comfyui` section from `cordis.yml` (or the settings page):
-
-```yaml
-# cordis.yml
-- id: comfyui
-  name: dsh-comfyui
-  config:
-    baseUrl: http://127.0.0.1:8188
-    apiKeyEnv: COMFYUI_API_KEY
-    timeoutMs: 900000
-    maxMediaItems: 12
-    dataDir: ''
-    maxAssets: 200
-    mediaHost: ''
-    outputDir: ''
-    comfyuiDirs:
-      - 'D:\ComfyUI'
-```
+`comfyui` section of `cordis.yml` (most is editable in the settings page):
 
 | Key | Default | Description |
 | --- | --- | --- |
-| `baseUrl` | `http://127.0.0.1:8188` | ComfyUI HTTP server base URL |
-| `apiKeyEnv` | `COMFYUI_API_KEY` | Env-variable / credential name for the optional API key |
-| `connectTimeoutMs` | `10000` | Per-request connect/read timeout |
-| `timeoutMs` | `900000` | Sync generation wait budget (15 min; raise for video) |
-| `pollIntervalMs` | `1000` | History polling interval while waiting |
-| `maxMediaItems` | `12` | Max media items returned per workflow |
-| `maxMediaBytes` | `67108864` | Max bytes the media proxy streams per file |
-| `dataDir` | *(DSH data dir)* | Where the workflow library and asset index live (`$DSH_HOME/data/dsh-comfyui` by default) |
-| `maxAssets` | `200` | Max entries kept in the asset index |
-| `mediaHost` | `''` (auto-detect) | External base URL for generated media (e.g. `http://192.168.1.5:3080`); empty auto-uses the origin the browser actually reaches this server with |
-| `outputDir` | `''` (inferred) | ComfyUI's output directory on this machine, used to locate files when deleting an asset; empty infers it from the paths ComfyUI reports, and deletion falls back to removing the index record when it cannot (e.g. a remote ComfyUI) |
-| `comfyuiDirs` | `[]` | Local ComfyUI install root(s) (multiple allowed: mapped dirs / multiple installs). The agent reads them via `env.comfyuiDirs` from `comfyui_workflow list` to locate models, custom nodes and the TTS-Audio-Suite voice library directly |
-
-## Roadmap & design boundaries
-
-Confirmed scope decisions for this phase:
-
-- **Image-to-video / reference-to-video / audio variants** are not plugin-side features: they share the same upload node as image-to-image, so any such workflow (extracted or imported) works as-is. Add the workflow, not plugin code.
-- **No front-end parameter presets/favorites.** Advanced customization happens in the workflow editor (edit parameter defaults, or add an advanced parameter for any node input). This keeps one source of truth.
-- **Model-strength knobs** (e.g. `ref_boost`) are handled through the advanced-parameter mechanism: expose the node input, label its effect, and the agent can tune it per run.
-- **Planned**: auto-commit of run parameters — after a successful run, save the used parameter values as that workflow's new defaults, so the next run opens with the previous session's values instead of the authored ones.
-
-## Security
-
-- The tools only ever connect to the **configured** `baseUrl` — the agent cannot name arbitrary targets (SSRF containment).
-- The API key lives on the host (credentials store / environment), resolved per request; `/comfyui/config` reports only `hasApiKey`.
-- Media is capped by size; config writes require same-origin requests.
-- Workflows extracted from ComfyUI are validated (non-empty `class_type`, object inputs, zero `node_errors` on the server) before they are stored.
-- Headless profiles without a web server keep the tools and skip the routes silently.
-
-## Architecture
-
-A single npm package with two halves, following the DH plugin conventions:
-
-- `src/index.ts` — host entry: `inject: ['tools']`; registers the tools and the companion skill (`ctx.skills.register`, optional service), and mounts routes + media proxy on a `webServer` sub-fiber (`ctx.inject`) so concurrent entry settling can never skip the mounts.
-- `src/comfyui.ts` — minimal ComfyUI HTTP client (queue prompt, poll history, object_info, system_stats, interrupt, view download, userdata list/read).
-- `src/analyze.ts` — canvas analysis: connected components over active nodes, group membership, dangling/isolated nodes, bypassed counts.
-- `src/convert.ts` — graph → API extraction: rewires links (Reroute / bypass pass-through), derives widget order from the graph's own input array plus object_info (including `control_after_generate` and dynamic sub-widgets), inlines primitive values, drops stale slot references with a warning, and fails loudly when a required input was never wired.
-- `src/skill.ts` — the `dsh-comfyui-workflows` companion skill body.
-- `src/params.ts` — parameter application: fills an unset image parameter with the load-area source image, auto-matches `width`/`height` to the source's recorded size, and re-syncs DynamicCombo parent/child pairs.
-- `src/store.ts` — the workflow library and asset index on disk (`workflows.json` + `assets.json`), plus the load-area records (`current-image.json`, `media-sizes.json`, `media-hashes.json`).
-- `src/queue.ts` — tracks prompts the plugin queued and moves completed ones into the asset index (sweep-on-read, no timers).
-- `src/tools.ts` — `ToolDefinition`s registered through `ctx.tools.register`; results carry `presentationMeta` so the client card renders from the session log.
-- `src/routes.ts` — same-origin HTTP routes for the panel (config, workflows, ComfyUI-side graphs + analyze/extract, assets, queue, run, load area, upload with hash dedup + size recording).
-- `src/client/` — browser half: the `shell.overlay` right-docked panel + `sidebar.footer.action` trigger, the `tool.call.toolview` card (key `comfyui_run`), and the `settings.section` page (id `comfyui`).
-- `cordis.patch.yml` — the `dsh.bundle.patch` layer that inserts the `comfyui` row into a profile.
-
-## Development
+| `baseUrl` | `http://127.0.0.1:8188` | ComfyUI server address |
+| `apiKeyEnv` | `COMFYUI_API_KEY` | Optional API key env var / credential name |
+| `dataDir` | *(DSH data dir)* | Where the workflow library and asset index live |
+| `comfyuiDirs` | `[]` | Local ComfyUI install dirs (multiple allowed); the agent locates models, custom nodes, TTS voice libraries through these |
+| `outputDir` | `''` (inferred) | ComfyUI output dir (used to locate files when deleting assets) |
+| `mediaHost` | `''` (auto) | External base URL for generated media |
+| `skillsDir` | `''` (default `dataDir/skills`) | Skill pack root (absolute path; a synced folder or VCS works) |
 
-```sh
-pnpm install
-npm run typecheck   # host + client
-npm run build       # tsc (host lib/) + tsdown (client bundle)
-npm pack --dry-run  # inspect the publish contents
-```
+## Requirements
 
-To test against a local profile: `dsh plugin --profile web add <path-to-this-repo>` (pnpm links the directory), restart the web server, and rebuild with `npm run build` after changes.
+- DeepSeek Harness (`web` / `desktop` profile)
+- A running [ComfyUI](https://github.com/comfystack/ComfyUI) server (default `http://127.0.0.1:8188`)
+- The `video` template needs [ComfyUI-WanVideoWrapper](https://github.com/kijai/ComfyUI-WanVideoWrapper) and Wan 2.1 models
 
 ## License
 
-MIT
+MIT

package/README.md

@@ -8,7 +8,7 @@
 
 <h1 align="center">dsh-comfyui</h1>
 
-<p align="center">让 DeepSeek Harness 的 Agent 直接驱动 ComfyUI 生成与处理图像、视频。</p>
+<p align="center">让 DeepSeek Harness 的 Agent 智能驱动本地或远程 ComfyUI 生成任何内容。附带工作流、资产管理面板与技能包管理挂载。配套 skill 与同源媒体代理。</p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/dsh-comfyui"><img src="https://img.shields.io/npm/v/dsh-comfyui" alt="npm version" /></a>
@@ -20,206 +20,94 @@
 
 ### Agent 工具
 
-- `comfyui_run` —— 提交 ComfyUI API 格式的工作流，或选用内置模板，返回生成的媒体。两种模式：`sync`（等待并返回媒体）与 `async`（后台任务，用 `job_output` 收集结果——视频生成强烈建议）。
-- `comfyui_object_info` —— 列出你的 ComfyUI 服务器支持的节点定义，让 Agent 能当场构造合法的工作流。
-- `comfyui_workflow` —— 列出并运行插件库中的可运行工作流。`action: list` 还会报告你的 ComfyUI 服务器地址与本机 ComfyUI 目录（`env` 字段），以及你在 ComfyUI 端保存的图工作流和每个是否已**提取**出可运行执行流；未提取的会明确标注，Agent 会先转告你在面板里点"提取"。`action: refresh` 按 id 重算某个工作流的参数快照并写回（先强制 TTS 音色库重扫，再按最新节点定义更新参数的选项/数值声明）——音色库或节点定义变更后跑它。
+Agent 直接驱动 ComfyUI，无需手动操作画布：
+
+- `comfyui_run` —— 提交 API 格式工作流或内置模板（txt2img / img2img / video），返回生成媒体；`mode: "sync"` 等待结果，`mode: "async"` 后台任务（视频生成强烈建议）。
+- `comfyui_object_info` —— 列出服务器支持的节点定义，让 Agent 现场构造合法工作流。
+- `comfyui_workflow` —— 管理插件工作流库：`list`（含服务器地址、本机 ComfyUI 目录、加载区素材、每个工作流的参数清单）、`run`（按 id 运行 + 参数覆盖）、`skill`（按需读取某工作流的技能包）、`refresh`（重算参数快照）。
+- `comfyui_skill` —— 读写工作流技能包（`list` / `read` / `write` / `append` / `mkdir` / `rename` / `delete` / `enable` / `require`），Agent 可把踩坑经验写回技能包，跨会话复用。
 
 ### UI 面板
 
-右侧停靠；从侧边栏轨道打开——三个页签：
+右侧停靠面板，三个页签：
 
-- **工作流** —— 插件库（可运行的 API 工作流）：新建 / 编辑 / 运行 / 删除，支持"导入文件"直接加载 API 格式 `.json`。"ComfyUI 端保存"分区自动检测你在 ComfyUI 里保存的图工作流，显示每个已提取出的执行流，并提供**提取**：画布上往往躺着多个独立流程，可整体提取 / 按分量提取 / 只提取主流程。工作流可用**标签**分类（见下）。
-- **资产** —— 插件生成的所有结果，最新在前，带详情视图和下载链接。鼠标悬停卡片右上角出现红色垃圾桶，点击弹出确认框（列出将删除的文件名），确认后移除索引记录并删除 ComfyUI 输出目录里的对应文件。ComfyUI 自身没有删除输出文件的接口，这一步由插件直接操作文件系统，因此只有当 DSH 能访问到输出目录（通常是同机部署）时才会真正删文件，否则只移除记录并在对话框里说明。
-- **队列** —— 基于 ComfyUI 统一任务 API（`/api/jobs`）的任务中心：实时队列**和**历史里所有任务按五态展示（待生成 / 生成中 / 已完成 / 失败 / 已取消），可按状态筛选；插件提交的任务带进度条（进度来自 ComfyUI WS 的 progress 事件），终态任务带预览缩略图、失败原因与耗时；支持操作：删除、中断、重跑、清空队列/历史、释放内存。插件提交的任务标注工作流名。
+- **工作流** —— 可运行工作流库（新建 / 编辑 / 运行 / 删除 / 导入 `.json`，标签分类 + 下拉筛选）；自动检测 ComfyUI 端保存的图工作流，支持**提取**为可运行工作流（画布含多个独立流程时可选整体 / 按分量 / 主流程）。
+- **资产** —— 所有生成结果，预览、下载、悬停可删除（同步清理 ComfyUI 输出目录里的文件）。
+- **队列** —— 实时队列 + 历史任务五态展示，支持删除 / 中断 / 重跑 / 清空 / 释放内存，插件提交的任务带进度条与预览。
 
 <p align="center"><img src="images/panel.png" width="70%" alt="插件主面板：工作流 / 资产 / 队列" title="插件主面板：工作流 / 资产 / 队列" /></p>
 
-### 加载区
-
-仿 ComfyUI LoadImage 节点的媒体加载器，位于工作流页顶部：除图片外，选择窗口也会列出 ComfyUI 加载节点（LoadVideo / LoadAudio）可用的视频与音频文件。
-
-- **多加载位**：加载区由若干加载位组成——只有一个时横向铺满面板，两个及以上时等宽排列并自动换行。底部"＋ 添加加载区"新增加载位；空加载位显示"加载位 N / 添加素材"，点击即可放入；鼠标悬停在任一加载位右上角会出现 **×**，点击删除该加载位；在选择窗口第一格选"空"则只清空该位、保留加载位。已放入的素材按顺序填进工作流里未显式指定的加载参数——两张参考图的工作流放两个加载位即可，Agent 无需点名文件。
-- 点击任一加载位打开加载窗口：上方导航条（全部 / 已导入 / 已生成）、类型筛选、右侧粘贴/上传区、下方瀑布流网格展示 ComfyUI `input` 目录里图像 / 视频 / 音频的全部可加载文件 + 插件生成的全部结果。**视频与音频可就地播放试听**（卡片内自带播放器，点播放器只播放、不会误选）；点卡片下方的文件名即选定并关闭窗口。加载文件的类型按扩展名判定，加载节点的输入键从 ComfyUI 节点定义读取（`LoadImage.image` / `LoadVideo.file` / `LoadAudio.audio`），不会漏掉某一类媒体。
-- 加载区素材即**默认输入**：工作流运行中未显式指定的加载参数按加载位顺序自动填入（第 1 位 → 第 1 个图片参数，第 2 位 → 第 2 个；视频/音频参数各取同类型加载位）——无需指定文件名。没有对应加载位的参数保持工作流原值。
-- **Agent 可见**：`comfyui_workflow action: list` 的输出带 `loadArea`（加载位数量、已放入素材数、文件清单），Agent 能直接知道用户加载了几个素材、分别是什么。
-- **分辨率自动匹配**：上传时记录像素尺寸；运行时不传 `width`/`height` 则自动用源图实际分辨率。
-- **哈希命名 + 去重**：上传重命名为 `原名_短哈希.ext`（SHA-256 前 10 位十六进制）；重复上传相同文件直接复用已有文件名，不产生重复存储。上传后列表实时刷新。
-- 选中**已生成**的图时会自动从输出目录复制到 `input`，图像加载节点即可使用。
-
-<p align="center"><img src="images/loadarea.png" width="70%" alt="加载区：图像选择与上传" title="加载区：图像选择与上传" /></p>
-
-### 工作流标签
-
-用预设分类（图生图 / 文生图 / 文生视频 / 图生视频 / 参考生视频 / 文生音频 / 参考生音频）+ 自定义标签给可运行工作流分类。标签在编辑工作流时勾选/添加，显示在卡片右上角，列表顶部有带计数的标签筛选条。
-
-### 内置模板
-
-`txt2img`（SDXL 文生图）、`img2img`（SDXL 图生图）、`video`（Wan 2.1 文生视频，需要 ComfyUI-WanVideoWrapper）。模板节点 id 写在工具描述里，Agent 会覆盖正确的输入。
-
-### 媒体代理
-
-生成文件按 `文件名 + 子目录 + 类型` 经同源路由（`/comfyui/media`）转发，不依赖 ComfyUI 的内存态历史记录——重启 ComfyUI 或清空历史后，资产面板里的旧结果照样能打开（只要文件还在输出目录）。浏览器不直接接触 ComfyUI：没有 CORS、没有混合内容、页面里不出现 API Key，远程 ComfyUI 部署也可直接使用。媒体 URL 的访问地址自动检测：页面加载时浏览器经 `/comfyui/ping` 自报实际访问的 origin（局域网 IP / 域名 / 反向代理都能拼出正确的链接），也可用配置键 `mediaHost` 显式指定基址。
-
-### 工具卡片
-
-结果在对话里渲染成媒体墙（图片/视频带下载链接），后台任务也有状态提示。
-
-### 设置页
-
-DH 设置里新增 "ComfyUI" 分区：改服务器地址（`baseUrl`）、API Key 环境变量名（`apiKeyEnv`）、媒体访问地址（`mediaHost`）、本机 ComfyUI 安装目录（`comfyuiDirs`，可多条——目录映射 / 多实例；Agent 据此直接定位你的 ComfyUI 文件与 TTS 音色库，无需再询问）、测试连接，并可切换插件界面语言（中文 / English——存于浏览器，作用于整个插件 UI），无需改动 `cordis.yml`。数据目录与资产上限只通过 `cordis.yml` 配置，不在设置页暴露。
-
-<p align="center"><img src="images/settings.png" width="70%" alt="ComfyUI 设置页（含界面语言切换）" title="ComfyUI 设置页（含界面语言切换）" /></p>
-
-### 配套 skill
-
-通过 `ctx.skills.register` 注册的运行时 skill（`dsh-comfyui-workflows`）：让 Agent 掌握图工作流 vs 执行流的概念、画布分析规则（连通分量、绕过组、悬空节点）、何时该询问你提取方式，以及图→API 提取的技术规则。skill 还附带了**本机环境**说明（从 `comfyui_workflow list` 的 `env` 读你的 ComfyUI 目录）与**TTS-Audio-Suite 音色库查询**（统一流程：先刷新快照再查询——刷新用 ComfyUI 的 `/api/tts-audio-suite/voice-library?refresh=1` + `action: refresh` 重算写回快照，查询优先走 HTTP 接口、其次直接列 `{comfyuiDir}/models/voices` 等目录；新音色运行被拒 = 快照过期），Agent 不必反复翻插件源码。
-
-### 图工作流 vs 可运行工作流（提取执行流）
+### 加载区（媒体加载器）
 
-ComfyUI 分两层：
+工作流页顶部的媒体加载器，仿 ComfyUI LoadImage 节点：图片 / 视频 / 音频可视化选择（可就地试听）、粘贴上传、多加载位。已放入的素材按顺序自动填进工作流里未显式指定的加载参数——**Agent 不需要猜文件名**；未传 `width`/`height` 时自动匹配源图分辨率。上传按内容哈希去重命名。
 
-- **图工作流（衍生主题）** —— 你在 ComfyUI 里保存的 UI 图（nodes/links/widgets），是"源"，不能直接运行。一个画布常常是**同时测试多个独立流程的试验台**；视觉 `groups` 只是矩形，真正可执行单元是**连通分量**（按连线连通，排除绕过与悬空节点）。
-- **可运行工作流（运行主题）** —— API 格式的 prompt，真正的执行单元。从图里**提取**出来（1 图 → N 个执行流），或直接粘贴/导入 API `.json`。
+`comfyui_workflow list` 的 `loadArea` 字段会把加载位数与内容暴露给 Agent。
 
-**提取**流程会先分析画布（各分量的节点数与所在组、绕过/悬空计数），然后让你选择：
+### 工作流技能包（给 Agent 的说明书）
 
-- **整体提取** —— 所有分量合成一个执行流（运行时全部执行）。
-- **按分量提取**（推荐）—— 每个独立流程一个执行流。
-- **只提取主流程** —— 只取最大分量（通常是当前测试区块）。
+参数清单只能告诉 Agent"有哪些旋钮"，说不出"这个工作流适合什么、哪一步会翻车"。复杂工作流可以挂一个**技能包**（面板工作流卡片上点「技能包」按钮启用）：
 
-提取严格对照实时 `/object_info`：重排 Reroute/bypass 直通、映射 widget 值（含动态子 widget 与 `control_after_generate`）、内联 Primitive、丢弃失效的输出槽位引用并警告、跳过无输出节点的分量、必需输入缺失时明确报错——每个提取出的执行流都会先经 `POST /prompt` 校验（`node_errors` 为空）才入库。
+```
+<数据目录>/skills/<工作流>/
+  SKILL.md          # 主文档：适用场景 / 关键参数 / 注意事项
+  references/       # 参考文档：风格合集、排错记录
+  assets/           # 参考图等素材（可在面板预览）
+```
 
-### 可调参数
+- **按需三级披露，不占常驻上下文**：`comfyui_workflow list` 只有一行摘要 → 选中工作流后 `action: skill` 取正文 → 正文点名某份参考文档时才读那一篇。几十个工作流各带整套文档，平时对话成本也只是一行摘要。
+- **面板编辑**：左栏文件列表 + 右栏编辑器，支持导入（按扩展名自动分目录）、自定义子目录、图片预览、把整个技能包目录挪到别的盘或同步盘（设置页 `技能包目录`）。
+- **Agent 也能写**：`comfyui_skill` 工具让 Agent 查看/编写技能包——踩到坑就 `append` 进 SKILL.md，下次（换个会话也一样）直接复用经验。
+- **运行前必读**：可勾选「运行前必读」，勾上后 Agent 本会话没读过该技能包就调 `run` 会被拒绝并提示先读。
 
-每个可运行工作流带一组**可调参数**（`parameters`），让同一流程按需生成不同结果：
+### 媒体代理与设置
 
-- **自动识别（保守集）**：提取时自动提取 提示词（文本输入节点）、分辨率（`EmptyLatentImage` 宽高）、采样步数（`KSampler.steps`）、种子（`KSampler.seed`，默认**每次运行随机**）。采样相关（cfg/denoise）与模型选择不暴露，保持工作流原样。
-- **高级参数**：面板"编辑工作流"里可手动暴露任意节点的任意输入为参数（选节点 → 选输入 → 命名），并调整每个参数的名称、显示名、默认值、是否随机。输入列表列出该节点全部 widget 值（含加载节点的 `upload` 项），当前由连线驱动的输入不列出——它们没有可编辑的值，暴露出来只会和连线打架。
-- **布尔参数用勾选框编辑**：`true` / `false` 直接点选；运行时也接受 `"true"` / `"false"` / `0` / `1` 这些写法（旧版本存成字符串的默认值会自动归一，不再被静默忽略）。
-- **数字参数区分整数/小数**：从 ComfyUI 节点定义读取输入的声明类型（`INT` / `FLOAT`），`cfg`、`denoise` 这类 FLOAT 参数可直接填小数，`steps`、`seed` 这类 INT 参数在运行时四舍五入；类型未知时按小数处理。参数行会标出 `number/int`、`number/float`，鼠标悬停显示取值范围与步长。
-- **Agent 感知**：参数清单自动写入工作流的"参数说明"（`inputs` 字段），`comfyui_workflow` 工具的 `action: list` 会展示；`action: run` 接受 `parameters: {"prompt": "...", "seed": 42}` 覆盖——显式传值优先于随机/默认，未传参数用默认值。
-- **参数快照与刷新**：每个参数的选项/数值声明（`options`、`numberKind` 等）在**保存工作流那一刻**从 ComfyUI 节点定义拷贝，之后不会自动更新（音色库、上传文件这类会长大的列表尤其明显）。刷新手段：Agent 用 `comfyui_workflow action: refresh { id }`；其他程序可调同源路由 `POST /comfyui/workflows/refresh-params`（body `{ "id": ... }`）。刷新只更新派生字段，**不会**动你手动加的高级参数与默认值；不刷新时，`action: list` 的选项可能缺新音色、`action: run` 传新音色会被拒绝。
-- **加载区联动**：未显式指定的加载参数按加载位顺序自动填入（同类型匹配）；未传的 `width`/`height` 自动匹配源图记录的像素尺寸。显式传值始终优先，Agent 仍可覆盖两者，并能从 `action: list` 的 `loadArea` 字段看到用户加载了什么。
+生成文件经同源路由（`/comfyui/media`）按文件名转发，不依赖 ComfyUI 内存态历史——重启或清空历史后旧结果照样能打开。浏览器不直接接触 ComfyUI：无 CORS、无混合内容、API Key 不下发。
 
-## 环境要求
-
-- DeepSeek Harness（web / desktop profile）—— 本插件面向 `web` 与 `desktop` profile（web 端要求 `@deepseek-ai/dsh-web-app` ≥ 0.1.0-rc.6）。
-- 一个运行中的 [ComfyUI](https://github.com/comfystack/ComfyUI) 服务器（默认 `http://127.0.0.1:8188`）。
-- 使用 `video` 模板需要 [ComfyUI-WanVideoWrapper](https://github.com/kijai/ComfyUI-WanVideoWrapper) 自定义节点和 Wan 2.1 模型文件。
+DH 设置页新增 "ComfyUI" 分区：服务器地址、API Key 环境变量名、本机 ComfyUI 目录、媒体访问地址、测试连接、界面语言切换，改完即生效，无需改 `cordis.yml`。
 
 ## 安装
 
-Web 端（web profile）：
-
 ```sh
+# web profile
 dsh plugin --profile web add dsh-comfyui
-```
-
-桌面端（desktop profile）：
-
-```sh
+# desktop profile
 dsh plugin --profile desktop add dsh-comfyui
 ```
 
-然后重启对应应用（Web 服务或桌面端；Host 端行在启动时挂载）。侧边栏轨道出现面板入口，设置页出现 "ComfyUI" 分区，Agent 立即获得 `comfyui_run`、`comfyui_object_info`、`comfyui_workflow` 与 `dsh-comfyui-workflows` skill。
-
-### API Key（远程服务器）
-
-远程 ComfyUI 若位于需要鉴权的代理之后，通过凭据存储或 `apiKeyEnv` 指定的环境变量（默认 `COMFYUI_API_KEY`）提供密钥。密钥在 Host 端按请求解析，绝不发给浏览器。
+重启应用后：侧边栏出现面板入口，设置页出现 "ComfyUI" 分区，Agent 立即获得全部工具与配套 skill。
 
 ## 使用
 
 直接告诉 Agent，例如：
 
 - "用 ComfyUI 画一张红猫的图"
-- "把这幅图转成赛博朋克风格"（img2img，需要输入图片文件名）
-- "把加载区这张动漫图转成真人照片，分辨率跟原图一致"（加载区源图 + 分辨率自动匹配）
-- "生成一段 5 秒的短视频：日落下的城市"（video，需要 Wan 插件）
-- "用我之前在 ComfyUI 里保存的 Krea-Afterlight 跑一下" —— Agent 会列出服务器端的图工作流；如果你指的那个还没提取，它会先转告你去面板里点**提取**（画布可能含多个独立流程，可选整体/按分量/主流程）。
-
-Agent 会选用模板，或用 `comfyui_object_info` 探查你的服务器，或用 `comfyui_workflow` 运行插件库里已保存的执行流。
-
-### 配置
-
-插件读取 `cordis.yml` 中的 `comfyui` 段（或通过设置页修改）：
-
-```yaml
-# cordis.yml
-- id: comfyui
-  name: dsh-comfyui
-  config:
-    baseUrl: http://127.0.0.1:8188
-    apiKeyEnv: COMFYUI_API_KEY
-    timeoutMs: 900000
-    maxMediaItems: 12
-    dataDir: ''
-    maxAssets: 200
-    mediaHost: ''
-    outputDir: ''
-    comfyuiDirs:
-      - 'D:\ComfyUI'
-```
+- "把这幅图转成赛博朋克风格"
+- "把加载区这张动漫图转成真人照片，分辨率跟原图一致"
+- "生成一段 5 秒的短视频：日落下的城市"
+- "用我之前在 ComfyUI 里保存的 Krea-Afterlight 跑一下"（若该图还没提取，Agent 会转告你先去面板点**提取**）
+
+远程 ComfyUI 若位于需鉴权的代理之后，通过凭据存储或 `apiKeyEnv` 指定的环境变量（默认 `COMFYUI_API_KEY`）提供密钥，绝不发给浏览器。
+
+## 配置
+
+`cordis.yml` 的 `comfyui` 段（多数可在设置页改）：
 
 | 键 | 默认值 | 说明 |
 | --- | --- | --- |
-| `baseUrl` | `http://127.0.0.1:8188` | ComfyUI HTTP 服务器地址 |
-| `apiKeyEnv` | `COMFYUI_API_KEY` | 可选 API Key 的环境变量/凭据名 |
-| `connectTimeoutMs` | `10000` | 单次请求连接/读取超时 |
-| `timeoutMs` | `900000` | 同步生成的等待预算（15 分钟；视频请调大） |
-| `pollIntervalMs` | `1000` | 等待完成时的历史轮询间隔 |
-| `maxMediaItems` | `12` | 每个工作流最多返回的媒体条数 |
-| `maxMediaBytes` | `67108864` | 媒体代理单文件流式传输上限（字节） |
-| `dataDir` | *（DSH 数据目录）* | 工作流库与资产索引存放位置（默认 `$DSH_HOME/data/dsh-comfyui`） |
-| `maxAssets` | `200` | 资产索引最多保留的条数 |
-| `mediaHost` | `''`（自动检测） | 生成媒体的外网访问基址（如 `http://192.168.1.5:3080`）；留空自动使用浏览器实际访问本服务器的地址 |
-| `outputDir` | `''`（自动推断） | ComfyUI 在本机的输出目录，删除资产时用它定位文件；留空则从 ComfyUI 返回的文件路径自动推断，推断不出（如远程部署）时只删索引记录 |
-| `comfyuiDirs` | `[]` | 本机 ComfyUI 安装目录列表（可多条：目录映射 / 多实例）。Agent 通过 `comfyui_workflow list` 的 `env.comfyuiDirs` 读取，据此定位 models、自定义节点与 TTS-Audio-Suite 音色库等文件 |
-
-## Roadmap 与设计边界
-
-本阶段确认的范围决策：
-
-- **图生视频 / 参考生视频 / 音视频变体**不是插件侧功能：它们与图生图共用同一个上传节点，任何这类工作流（提取或导入）开箱即用。缺的是工作流本身，不是插件代码。
-- **不做前端参数预设/收藏**。高级定制在工作流编辑里完成（修改参数默认值，或把任意节点输入添加为高级参数）。保持唯一事实来源。
-- **模型强度类参数**（如 `ref_boost`）走高级参数机制：暴露节点输入、标注作用，Agent 即可按次调节。
-- **规划中**：运行参数自动回写——运行成功后把本次使用的参数值保存为该工作流的新默认值，下次打开就是上一次会话用的值，而不是作者初始值。
-
-## 安全
-
-- 工具只会连接**配置好的** `baseUrl` —— Agent 无法指定任意目标（SSRF 遏制）。
-- API Key 只存在于 Host（凭据存储/环境变量），按请求解析；`/comfyui/config` 只回传 `hasApiKey`。
-- 媒体有大小上限；配置写入要求同源请求。
-- 从 ComfyUI 提取的执行流会先校验（非空 `class_type`、对象型 inputs、服务器 `node_errors` 为空）再入库。
-- 无 Web 服务器的 headless profile 只保留工具，路由静默跳过。
-
-## 架构
-
-一个 npm 包、双端实现，遵循 DH 插件约定：
-
-- `src/index.ts` —— Host 入口：`inject: ['tools']`；注册工具与配套 skill（`ctx.skills.register`，可选服务），并把路由与媒体代理挂到 `webServer` 子 fiber（`ctx.inject`）上，避免并发 settle 导致挂载被静默跳过。
-- `src/comfyui.ts` —— 精简的 ComfyUI HTTP 客户端（排队、轮询历史、object_info、system_stats、interrupt、view 下载、userdata 列表/读取）。
-- `src/analyze.ts` —— 画布分析：激活节点的连通分量、组归属、悬空/孤立节点、绕过计数。
-- `src/convert.ts` —— 图 → API 提取：重排连线（Reroute / bypass 直通）、按图自身输入顺序 + object_info 推导 widget 顺序（含 `control_after_generate` 与动态子 widget）、内联 Primitive 值、丢弃失效的输出槽位引用并警告、必需输入缺失时明确报错。
-- `src/skill.ts` —— `dsh-comfyui-workflows` 配套 skill 正文。
-- `src/params.ts` —— 参数应用：未指定的图片参数填入加载区源图、`width`/`height` 自动匹配源图记录尺寸、DynamicCombo 父子联动同步。
-- `src/store.ts` —— 工作流库与资产索引落盘（`workflows.json` + `assets.json`），以及加载区记录（`current-image.json`、`media-sizes.json`、`media-hashes.json`）。
-- `src/queue.ts` —— 追踪插件提交的 prompt，完成后移入资产索引（读时清扫，无定时器）。
-- `src/tools.ts` —— 通过 `ctx.tools.register` 注册的 `ToolDefinition`；结果携带 `presentationMeta`，客户端卡片从会话日志渲染。
-- `src/routes.ts` —— 面板用的同源 HTTP 路由（配置、工作流、ComfyUI 端图 + 分析/提取、资产、队列、运行、加载区、带哈希去重与尺寸记录的上传）。
-- `src/client/` —— 浏览器端：`shell.overlay` 右侧停靠面板 + `sidebar.footer.action` 触发器、`tool.call.toolview` 卡片（key `comfyui_run`）、`settings.section` 设置页（id `comfyui`）。
-- `cordis.patch.yml` —— `dsh.bundle.patch` 补丁层，把 `comfyui` 行插入 profile。
-
-## 开发
+| `baseUrl` | `http://127.0.0.1:8188` | ComfyUI 服务器地址 |
+| `apiKeyEnv` | `COMFYUI_API_KEY` | 可选 API Key 的环境变量 / 凭据名 |
+| `dataDir` | *（DSH 数据目录）* | 工作流库与资产索引存放位置 |
+| `comfyuiDirs` | `[]` | 本机 ComfyUI 安装目录列表（可多条），Agent 据此定位 models、自定义节点、TTS 音色库 |
+| `outputDir` | `''`（自动推断） | ComfyUI 输出目录（删除资产时定位文件用） |
+| `mediaHost` | `''`（自动检测） | 生成媒体的外网访问基址 |
+| `skillsDir` | `''`（默认 `dataDir/skills`） | 技能包根目录（绝对路径，可放同步盘 / 版本库） |
 
-```sh
-pnpm install
-npm run typecheck   # host + client
-npm run build       # tsc（host lib/）+ tsdown（client bundle）
-npm pack --dry-run  # 检查发布内容
-```
+## 环境要求
 
-本地测试：`dsh plugin --profile web add <本仓库路径>`（pnpm 链接目录），重启 Web 服务，改动后 `npm run build` 重新构建。
+- DeepSeek Harness（`web` / `desktop` profile）
+- 一个运行中的 [ComfyUI](https://github.com/comfystack/ComfyUI) 服务器（默认 `http://127.0.0.1:8188`）
+- `video` 模板需要 [ComfyUI-WanVideoWrapper](https://github.com/kijai/ComfyUI-WanVideoWrapper) 与 Wan 2.1 模型
 
 ## License
 
-MIT
+MIT