dsh-comfyui 0.3.0-beta.5 → 0.4.0

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>
@@ -16,210 +16,107 @@
   <img src="https://img.shields.io/npm/l/dsh-comfyui" alt="license" />
 </p>
 
+> **版本配对（选对 dsh 版本再装，否则 dshmarket 会报风险提示）**：
+>
+> | dsh-comfyui | 配对的 DeepSeek Harness | 说明 |
+> | --- | --- | --- |
+> | **0.4.0（最新，`latest` tag）** | **≥ 0.1.2** | 0.4.0 起使用新版 settings 服务 API |
+> | **0.3.x（beta 线，`beta` tag）** | **0.1.1** | 老版本 dsh 请留在 0.3.x 线 |
+>
+> 安装：`dsh plugin --profile web add dsh-comfyui`（装最新 0.4.0）/ `dsh plugin --profile web add dsh-comfyui@beta`（老宿主装 0.3.x）。
+
 ## 功能
 
 ### 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