dsh-comfyui 0.3.0-beta.5 → 0.4.0

package/lib/config.d.ts

@@ -23,6 +23,12 @@ export declare const Config: z<Schemastery.ObjectS<{
     dataDir: z<string, string>;
     /** Max asset records kept in the asset index. */
     maxAssets: z<number, number>;
+    /** Directory holding the per-workflow skill packs. Empty = `<dataDir>/skills`.
+     * Separate from `dataDir` on purpose: packs are documents a user may want on
+     * another drive, in a synced folder, or under version control, while the
+     * JSON state files belong with the rest of the plugin data. Must be absolute;
+     * a relative value is ignored. */
+    skillsDir: z<string, string>;
     /** External base URL for generated media (e.g. http://192.168.1.5:3080). Empty = auto-detect the browser's request host, then http://127.0.0.1:<webServerPort>. */
     mediaHost: z<string, string>;
     /** ComfyUI's output directory on this machine, used to delete asset files
@@ -55,6 +61,12 @@ export declare const Config: z<Schemastery.ObjectS<{
     dataDir: z<string, string>;
     /** Max asset records kept in the asset index. */
     maxAssets: z<number, number>;
+    /** Directory holding the per-workflow skill packs. Empty = `<dataDir>/skills`.
+     * Separate from `dataDir` on purpose: packs are documents a user may want on
+     * another drive, in a synced folder, or under version control, while the
+     * JSON state files belong with the rest of the plugin data. Must be absolute;
+     * a relative value is ignored. */
+    skillsDir: z<string, string>;
     /** External base URL for generated media (e.g. http://192.168.1.5:3080). Empty = auto-detect the browser's request host, then http://127.0.0.1:<webServerPort>. */
     mediaHost: z<string, string>;
     /** ComfyUI's output directory on this machine, used to delete asset files
@@ -88,6 +100,8 @@ export type Config = {
     dataDir: string;
     /** Max asset records kept in the asset index. */
     maxAssets: number;
+    /** Directory holding the per-workflow skill packs; empty = `<dataDir>/skills`. */
+    skillsDir: string;
     /** External base URL for generated media; empty auto-detects the request host. */
     mediaHost: string;
     /** ComfyUI's output directory on this machine; empty infers it from reported file paths. */

package/lib/config.js

@@ -23,6 +23,12 @@ export const Config = z.object({
     dataDir: z.string().default(''),
     /** Max asset records kept in the asset index. */
     maxAssets: z.number().min(1).max(10_000).default(200),
+    /** Directory holding the per-workflow skill packs. Empty = `<dataDir>/skills`.
+     * Separate from `dataDir` on purpose: packs are documents a user may want on
+     * another drive, in a synced folder, or under version control, while the
+     * JSON state files belong with the rest of the plugin data. Must be absolute;
+     * a relative value is ignored. */
+    skillsDir: z.string().default(''),
     /** External base URL for generated media (e.g. http://192.168.1.5:3080). Empty = auto-detect the browser's request host, then http://127.0.0.1:<webServerPort>. */
     mediaHost: z.string().default(''),
     /** ComfyUI's output directory on this machine, used to delete asset files

package/lib/index.js

@@ -1,6 +1,5 @@
 import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings';
+import { isAbsolute, join } from 'node:path';
 import { Config } from './config.js';
 import { ComfyUIClient, CLIENT_ID } from './comfyui.js';
 import { ComfyUIStore } from './store.js';
@@ -10,6 +9,7 @@ import { analyzeGraph } from './analyze.js';
 import { ProgressTracker } from './progress.js';
 import { COMFYUI_SKILL } from './skill.js';
 import { analyzeWorkflowParameters, applyWorkflowParameters } from './params.js';
+import { createWorkflowSkillPacks } from './skillpack.js';
 import { registerComfyUITools } from './tools.js';
 import { mountComfyUIRoutes } from './routes.js';
 import { mountComfyUIProxy } from './proxy.js';
@@ -25,7 +25,7 @@ export { Config };
  * apply).
  */
 export const inject = ['tools'];
-const COMFYUI_NS = settingsNamespace('comfyui');
+const COMFYUI_NS = 'comfyui';
 /** object_info is large and changes only when nodes are (re)installed. */
 const OBJECT_INFO_TTL_MS = 60_000;
 let objectInfoCache;
@@ -76,6 +76,7 @@ export async function apply(ctx, entryConfig) {
         maxMediaBytes: entryConfig.maxMediaBytes ?? 64 * 1024 * 1024,
         dataDir: entryConfig.dataDir !== undefined && entryConfig.dataDir !== '' ? entryConfig.dataDir : defaultDataDir(),
         maxAssets: entryConfig.maxAssets ?? 200,
+        skillsDir: entryConfig.skillsDir ?? '',
         mediaHost: entryConfig.mediaHost ?? '',
         outputDir: entryConfig.outputDir ?? '',
         comfyuiDirs: Array.isArray(entryConfig.comfyuiDirs)
@@ -84,6 +85,22 @@ export async function apply(ctx, entryConfig) {
     };
     const store = new ComfyUIStore(resolved.dataDir, resolved.maxAssets);
     await store.init();
+    // Per-workflow skill packs default to `<dataDir>/skills`; `skillsDir` moves
+    // them anywhere absolute (another drive, a synced folder, a repo) without
+    // dragging the JSON state along. The root is a getter, not a snapshot, so a
+    // settings-page change applies to the next call rather than the next restart.
+    // Directories are created lazily when a user attaches a pack, so nothing is
+    // written for a library that never uses them.
+    const skillPacks = createWorkflowSkillPacks({
+        skillsRoot: () => {
+            const configured = resolved.skillsDir.trim();
+            // A relative path would resolve against the process cwd, which is not
+            // something a user typing into the settings page can predict.
+            return configured !== '' && isAbsolute(configured) ? configured : store.skillsRoot;
+        },
+        getWorkflow: (id) => store.getWorkflow(id),
+        updateWorkflowSkill: (id, patch) => store.updateWorkflowSkill(id, patch),
+    });
     const tracker = new QueueTracker({
         load: () => store.loadTracked(),
         save: (state) => store.saveTracked(state),
@@ -182,6 +199,7 @@ export async function apply(ctx, entryConfig) {
             return client.getOk('/api/tts-audio-suite/voice-library?refresh=1', 20_000);
         },
         deleteWorkflow: (id) => store.deleteWorkflow(id),
+        skillPacks,
         listMediaSizes: () => store.loadMediaSizes(),
         saveMediaSize: (name, size) => store.saveMediaSize(name, size),
         lookupMediaHash: (hash) => store.lookupMediaHash(hash),
@@ -300,13 +318,15 @@ export async function apply(ctx, entryConfig) {
     // The settings section rides the plugin fiber: a host without a settings
     // service simply never registers it, and the entry config stands as composed.
     let source = () => resolved;
-    installSettingsSection(ctx, COMFYUI_NS, Config, resolved, {
-        setSource: (current) => {
-            source = current;
-        },
-        onChange: () => {
-            Object.assign(resolved, source());
-        },
+    ctx.inject(['settings'], (settingsCtx) => {
+        settingsCtx.settings.installSection(ctx, COMFYUI_NS, Config, resolved, {
+            setSource: (current) => {
+                source = current;
+            },
+            onChange: () => {
+                Object.assign(resolved, source());
+            },
+        });
     });
     ctx.effect(() => {
         const disposers = registerComfyUITools(ctx, runtime);

package/lib/routes.js

@@ -1,7 +1,9 @@
 import { errorMessage, readJsonBody, readRawBody, sameOrigin, sendJson } from './http.js';
 import { analyzeWorkflowParameters, comboChildInfo, inputOptions, numberSpecOf, refreshParameterMetadata, uploadKindOf } from './params.js';
 import { collectMedia, historyErrorMessage, mediaProxyUrl } from './comfyui.js';
+import { MAX_ASSET_BYTES, SKILL_MAIN, SKILL_PRESET_DIRS, joinFrontmatter, splitFrontmatter } from './skillpack.js';
 import { unlink } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 /**
  * Rebuild an asset's media URLs from the stored file references.
@@ -129,6 +131,10 @@ function redact(runtime, apiKey) {
         maxMediaItems: config.maxMediaItems,
         mediaHost: config.mediaHost,
         comfyuiDirs: config.comfyuiDirs,
+        skillsDir: config.skillsDir,
+        // The path actually in use, so the page can show where packs land even
+        // when skillsDir is empty (the `<dataDir>/skills` default).
+        skillsRoot: runtime.skillPacks.root,
         writable: runtime.settingsWritable(),
     };
 }
@@ -657,6 +663,253 @@ export function mountComfyUIRoutes(ctx, runtime) {
             sendJson(response, 200, { ok: true });
         }),
     }));
+    // The skill-pack editor's whole surface: one GET for the listing (plus a
+    // single file's text when `path` is given) and one action-style POST for
+    // every mutation. Paths from the browser are untrusted and re-validated
+    // inside the pack store, which is also where the containment check lives.
+    disposers.push(webServer.register({
+        kind: 'exact',
+        path: '/comfyui/workflows/skill',
+        handler: withHint(async (request, response) => {
+            if (methodIs(request, 'GET')) {
+                const url = new URL(request.url ?? '/', 'http://localhost');
+                const id = url.searchParams.get('id') ?? '';
+                if (id === '') {
+                    sendJson(response, 400, { error: 'id is required' });
+                    return;
+                }
+                const workflow = await runtime.getWorkflow(id);
+                if (workflow === undefined) {
+                    sendJson(response, 404, { error: `workflow "${id}" not found` });
+                    return;
+                }
+                const path = url.searchParams.get('path');
+                if (path !== null && path !== '') {
+                    const file = await runtime.skillPacks.readFile(id, path);
+                    if (!file.ok) {
+                        sendJson(response, 200, { ok: false, error: file.error });
+                        return;
+                    }
+                    // SKILL.md's frontmatter stays a host-side concern: the panel edits a
+                    // summary field and a body, never the raw `---` block.
+                    if (path === SKILL_MAIN) {
+                        const split = splitFrontmatter(file.value);
+                        sendJson(response, 200, { ok: true, path, content: file.value, summary: split.summary, body: split.body });
+                        return;
+                    }
+                    sendJson(response, 200, { ok: true, path, content: file.value });
+                    return;
+                }
+                const pack = await runtime.skillPacks.info(id);
+                sendJson(response, 200, {
+                    ok: true,
+                    enabled: pack !== undefined,
+                    root: runtime.skillPacks.root,
+                    // Suggested directory names, defined once on the host so the panel
+                    // dropdown and the agent-facing tool offer the same list.
+                    presetDirs: SKILL_PRESET_DIRS,
+                    pack: pack ?? null,
+                });
+                return;
+            }
+            if (!methodIs(request, 'POST')) {
+                sendJson(response, 405, { error: 'method not allowed' });
+                return;
+            }
+            const body = await readSameOriginPost(request, response);
+            if (body === undefined)
+                return;
+            const id = typeof body.id === 'string' ? body.id : '';
+            if (id === '') {
+                sendJson(response, 400, { error: 'id is required' });
+                return;
+            }
+            const action = typeof body.action === 'string' ? body.action : '';
+            const path = typeof body.path === 'string' ? body.path : '';
+            const content = typeof body.content === 'string' ? body.content : '';
+            try {
+                switch (action) {
+                    case 'enable': {
+                        const result = await runtime.skillPacks.enable(id);
+                        sendJson(response, 200, result.ok ? { ok: true, enabled: true, pack: result.value } : { ok: false, error: result.error });
+                        return;
+                    }
+                    case 'disable': {
+                        const result = await runtime.skillPacks.disable(id);
+                        sendJson(response, 200, result.ok ? { ok: true, enabled: false, pack: null } : { ok: false, error: result.error });
+                        return;
+                    }
+                    case 'destroy': {
+                        const result = await runtime.skillPacks.destroy(id);
+                        sendJson(response, 200, result.ok ? { ok: true, enabled: false, pack: null } : { ok: false, error: result.error });
+                        return;
+                    }
+                    case 'require': {
+                        const result = await runtime.skillPacks.setRequired(id, body.required === true);
+                        sendJson(response, 200, result.ok ? { ok: true, enabled: true, pack: result.value } : { ok: false, error: result.error });
+                        return;
+                    }
+                    case 'mkdir': {
+                        const name = typeof body.name === 'string' ? body.name : '';
+                        const result = await runtime.skillPacks.makeDir(id, name);
+                        sendJson(response, 200, result.ok ? { ok: true, enabled: true, pack: result.value } : { ok: false, error: result.error });
+                        return;
+                    }
+                    case 'write': {
+                        const text = path === SKILL_MAIN && typeof body.summary === 'string'
+                            ? joinFrontmatter(body.summary, content)
+                            : content;
+                        const result = await runtime.skillPacks.writeFile(id, path, text);
+                        sendJson(response, 200, result.ok ? { ok: true, enabled: true, pack: result.value } : { ok: false, error: result.error });
+                        return;
+                    }
+                    case 'rename': {
+                        const to = typeof body.to === 'string' ? body.to : '';
+                        const result = await runtime.skillPacks.renameFile(id, path, to);
+                        sendJson(response, 200, result.ok ? { ok: true, enabled: true, pack: result.value } : { ok: false, error: result.error });
+                        return;
+                    }
+                    case 'delete': {
+                        const result = await runtime.skillPacks.deleteFile(id, path);
+                        sendJson(response, 200, result.ok ? { ok: true, enabled: true, pack: result.value } : { ok: false, error: result.error });
+                        return;
+                    }
+                    default:
+                        sendJson(response, 400, { error: `unknown action: ${action}` });
+                }
+            }
+            catch (error) {
+                sendJson(response, 200, { ok: false, error: errorMessage(error) });
+            }
+        }),
+    }));
+    // Importing a file into a pack: the raw bytes ride the request body with the
+    // name in the query, so images and scripts arrive byte-exact without a
+    // multipart parser. The destination bucket comes from the extension unless
+    // the panel names one; the caps live in the pack store, not here.
+    disposers.push(webServer.register({
+        kind: 'exact',
+        path: '/comfyui/workflows/skill/import',
+        handler: withHint(async (request, response) => {
+            if (!methodIs(request, 'POST')) {
+                sendJson(response, 405, { error: 'method not allowed' });
+                return;
+            }
+            if (!sameOrigin(request)) {
+                sendJson(response, 403, { error: 'forbidden: same-origin requests only' });
+                return;
+            }
+            const url = new URL(request.url ?? '/', 'http://localhost');
+            const id = url.searchParams.get('id') ?? '';
+            const name = url.searchParams.get('name') ?? '';
+            const bucket = url.searchParams.get('bucket') ?? '';
+            if (id === '' || name === '') {
+                sendJson(response, 400, { error: 'id and name are required' });
+                return;
+            }
+            try {
+                const raw = await readRawBody(request);
+                if (raw.length === 0) {
+                    sendJson(response, 200, { ok: false, error: '文件为空' });
+                    return;
+                }
+                // Cheap upper bound before the store's per-bucket check, so an oversized
+                // upload is rejected on the size it actually has.
+                if (raw.length > MAX_ASSET_BYTES) {
+                    sendJson(response, 200, { ok: false, error: `单个文件不能超过 ${Math.floor(MAX_ASSET_BYTES / 1024 / 1024)} MB` });
+                    return;
+                }
+                const result = await runtime.skillPacks.importFile(id, name, raw, bucket);
+                sendJson(response, 200, result.ok
+                    ? { ok: true, enabled: true, path: result.value.path, pack: result.value.pack }
+                    : { ok: false, error: result.error });
+            }
+            catch (error) {
+                sendJson(response, 200, { ok: false, error: errorMessage(error) });
+            }
+        }),
+    }));
+    // Opens the pack directory in the desktop file manager. This is the one
+    // route that launches a local process, so it stays deliberately narrow: the
+    // directory comes from the pack store (never from the request), the opener is
+    // spawned with an argument array rather than a shell string, and the request
+    // must be same-origin. It acts on the machine running DSH, which is not the
+    // user's machine when the panel is open from another host — the panel says so
+    // and shows the path either way.
+    disposers.push(webServer.register({
+        kind: 'exact',
+        path: '/comfyui/workflows/skill/reveal',
+        handler: withHint(async (request, response) => {
+            if (!methodIs(request, 'POST')) {
+                sendJson(response, 405, { error: 'method not allowed' });
+                return;
+            }
+            const body = await readSameOriginPost(request, response);
+            if (body === undefined)
+                return;
+            const id = typeof body.id === 'string' ? body.id : '';
+            if (id === '') {
+                sendJson(response, 400, { error: 'id is required' });
+                return;
+            }
+            const pack = await runtime.skillPacks.info(id);
+            if (pack === undefined) {
+                sendJson(response, 200, { ok: false, error: '该工作流没有技能包' });
+                return;
+            }
+            const opener = process.platform === 'win32'
+                ? 'explorer.exe'
+                : process.platform === 'darwin' ? 'open' : 'xdg-open';
+            try {
+                // Detached and unref'd: the file manager outlives this request, and
+                // explorer.exe reports a non-zero exit code even when it succeeded, so
+                // the exit status is deliberately not awaited.
+                const child = spawn(opener, [pack.dir], { detached: true, stdio: 'ignore' });
+                child.on('error', () => { });
+                child.unref();
+                sendJson(response, 200, { ok: true, dir: pack.dir });
+            }
+            catch (error) {
+                sendJson(response, 200, { ok: false, error: errorMessage(error), dir: pack.dir });
+            }
+        }),
+    }));
+    // Serves one pack file verbatim so the panel can preview an imported image.
+    disposers.push(webServer.register({
+        kind: 'exact',
+        path: '/comfyui/workflows/skill/raw',
+        handler: withHint(async (request, response) => {
+            if (!methodIs(request, 'GET') && !methodIs(request, 'HEAD')) {
+                sendJson(response, 405, { error: 'method not allowed' });
+                return;
+            }
+            const url = new URL(request.url ?? '/', 'http://localhost');
+            const id = url.searchParams.get('id') ?? '';
+            const path = url.searchParams.get('path') ?? '';
+            if (id === '' || path === '') {
+                sendJson(response, 400, { error: 'id and path are required' });
+                return;
+            }
+            const file = await runtime.skillPacks.readRaw(id, path);
+            if (!file.ok) {
+                sendJson(response, 404, { error: file.error });
+                return;
+            }
+            response.writeHead(200, {
+                'content-type': file.value.contentType,
+                'content-length': String(file.value.bytes.length),
+                'cache-control': 'no-store',
+                // Pack files are user content served from the app origin; never let a
+                // browser sniff one into something executable.
+                'x-content-type-options': 'nosniff',
+                'content-disposition': 'inline',
+            });
+            if (methodIs(request, 'HEAD'))
+                response.end();
+            else
+                response.end(file.value.bytes);
+        }),
+    }));
     disposers.push(webServer.register({
         kind: 'exact',
         path: '/comfyui/workflows/delete',
@@ -673,6 +926,12 @@ export function mountComfyUIRoutes(ctx, runtime) {
                 sendJson(response, 400, { error: 'id is required' });
                 return;
             }
+            // A workflow with a skill pack takes its documentation with it only when
+            // the user says so: the panel asks before deleting, and an unanswered
+            // delete leaves the directory behind rather than silently discarding
+            // hand-written notes.
+            if (body.deleteSkill === true)
+                await runtime.skillPacks.destroy(id).catch(() => undefined);
             await runtime.deleteWorkflow(id);
             sendJson(response, 200, { ok: true });
         }),

package/lib/skill.js

@@ -7,7 +7,7 @@ export const COMFYUI_SKILL = {
     name: 'dsh-comfyui-workflows',
     source: 'runtime',
     description: 'ComfyUI 工作流管理：区分“图工作流”（ComfyUI 端保存的画布，衍生主题）与“API 工作流”（可执行，运行主题），分析画布中的多个独立流程（连通分量），以及图→API 提取的规则与面板操作引导。也包含本机环境（用户 ComfyUI 目录）与 TTS-Audio-Suite 音色库的快速查询/快照刷新方案。处理 comfyui_workflow、需要定位用户 ComfyUI 文件/音色库，或用户要求运行 ComfyUI 端保存的工作流时加载。',
-    whenToUse: '用户要求运行/管理 ComfyUI 中保存的工作流，或 comfyui_workflow list 显示未提取的图工作流时；需要判断一个画布是否包含多个独立流程、或解释为何某个工作流无法直接运行时；需要查询 TTS-Audio-Suite 音色库、刷新已存工作流的音色参数快照、或定位用户本机 ComfyUI 目录时。',
+    whenToUse: '用户要求运行/管理 ComfyUI 中保存的工作流，或 comfyui_workflow list 显示未提取的图工作流时；需要判断一个画布是否包含多个独立流程、或解释为何某个工作流无法直接运行时；需要查询 TTS-Audio-Suite 音色库、刷新已存工作流的音色参数快照、或定位用户本机 ComfyUI 目录时；或 comfyui_workflow list 里某个工作流带“技能包”标记、需要在运行前读取它时。',
     content: `# dsh-comfyui 工作流管理
 
 本插件把 ComfyUI 工作流分成两个主题：
@@ -87,11 +87,58 @@ TTS-Audio-Suite（\`{comfyuiDir}/custom_nodes/tts_audio_suite\`）的"🎭 Chara
 - **命名与去重**：上传文件按内容哈希命名（\`原名_短哈希.ext\`，如 \`image_3f9a2b1c0d.png\`），同一张图重复上传会直接复用已有文件（不会产生 \`image(1).png\` 之类的重复文件）。
 - 选中"已生成"的图后，插件会自动把它从 output 复制到 input 目录（同名），保证加载节点可用。
 
+## 工作流技能包（谁写的、什么时候读）
+
+有些工作流参数多、坑多，或者带一整套风格提示。这类工作流可以挂一个**技能包**：一份 \`SKILL.md\`（适用场景 / 关键参数 / 注意事项）加上若干子目录（\`references/\` \`scripts/\` \`assets/\` \`templates/\` \`agents/\` …，也可以自定义目录名，只有一层），存在技能包目录 \`skills/<目录名>/\` 下。用户在面板里写，**你也可以用 \`comfyui_skill\` 工具自己写**（见下）。
+
+涉及**两个工具**，别弄混作用域：
+
+- **\`comfyui_workflow\`（工作流工具）**：管"工作流库"这一层。\`action: list\` 列出**整个工作流库**（所有 API 工作流 + ComfyUI 端图工作流 + 加载区 + env），**它不是技能包列表**——挂了技能包的工作流只是多一行 \`技能包: <摘要>\`（含文件数与是否必读），正文不进来。\`action: skill { id }\` 取**某一个**工作流的 \`SKILL.md\` 正文。**没有"列出所有工作流技能包"的命令**：发现靠 list 的一行摘要，详情必须按 id 单独查。
+- **\`comfyui_skill\`（技能包工具）**：管"某个技能包内部"这一层。每个动作都要带 \`workflow_id\`，只操作**那一个**工作流的技能包。它的 \`action: list\` 是看那个技能包的内部结构（文件/子目录/大小），**不是**"全库技能包一览"。
+
+技能包**不常驻对话**，按需分三步取用，别跳步也别提前全读：
+
+1. \`comfyui_workflow action: list\` 里，挂了技能包的工作流会多出一行 \`技能包: <摘要>\`（必读的写作 \`技能包（运行前必读）\`）。这是你唯一的线索，只有一句话。
+2. 决定要用这个工作流之后、运行之前，\`comfyui_workflow action: skill { id: "<工作流id>" }\` 取回 \`SKILL.md\` 正文和技能包的**绝对目录**。返回体是 \`<skill_content>\` 块，照着里面的指示做。
+3. 正文里点名某个参考文档（如 \`references/styles.md\`）时，才用文件读取工具按「Base directory + 相对路径」去打开它。\`assets/\` 里可能有参考图（png/jpg 等），同样按需读取（用能读图的文件工具）。**不要**一上来就把整个目录读一遍——分文件存放就是为了让你只取需要的那一份。
+
+规则：
+- **「运行前必读」是个布尔开关**：在面板技能包编辑器里勾选，或 \`comfyui_skill action: require { workflow_id, required: true }\` 设置（\`false\` 关掉）。它**只拦 \`action: run\` 这一条路径**：本会话没读过该工作流的技能包就调 \`action: run\`，会被直接拒绝，报错里指明先跑 \`action: skill { id }\`；\`list\` / \`skill\` / \`get\` / \`refresh\` 都不受影响。
+- **拦截粒度是「会话 × 工作流」**：读过一次即解除——\`action: skill\`，或 \`comfyui_skill action: read\` 读到 \`SKILL.md\`，都算读过；之后同一会话内 run 不再拦。**换一个新会话会重新拦**（拦截状态记在当前 Agent 会话上，不跨会话、不跨工作流），所以另一个会话的 Agent 跑同一工作流时仍要先读一遍。
+- 技能包是**用户为这个工作流写的**，优先级高于你的通用经验：它和本 skill 的通用规则冲突时，以技能包为准。
+- 没有 \`技能包:\` 那行的工作流就是没挂，别去猜也别调 \`action: skill\`（会报"没有技能包"）——想给它建一个就用 \`comfyui_skill action: enable\`。
+
+### 自己维护技能包（\`comfyui_skill\` 工具）
+
+技能包不是只读的：\`comfyui_skill\` 让你查看并编写某个工作流的技能包，每个动作都带 \`workflow_id\`。逐个动作：
+
+- \`list\` —— 看这个技能包的内部结构：文件清单（含字节大小）、子目录（含空目录）、摘要、是否必读、绝对目录。技能包已存在才能看（没挂会报"没有技能包"）。
+- \`read { path }\` —— 读一个文件（如 \`references/styles.md\`）；超过 40k 字符会截断并标记。读到 \`SKILL.md\` 与 \`comfyui_workflow action: skill\` 一样解除必读拦截。
+- \`write { path, content }\` —— **创建或整体覆盖**一个文件。已存在的文件被 write 会丢掉原内容：新建、或写自己刚建的文件才用它；给已有文件加内容用 \`append\`。写 \`SKILL.md\` 时带 \`summary\` 参数会更新 list 里那行摘要。
+- \`append { path, content }\` —— 追加到文件末尾（自动空行分隔），不动已有内容。踩坑结论、补充说明用这个。
+- \`mkdir { name }\` —— 建一层子目录（\`references\` / \`scripts\` / \`templates\` …可自定义，字母/数字/汉字/下划线/连字符）。先 mkdir 再 write 进去，比直接 write \`目录/文件\` 更稳。
+- \`rename { path, to }\` —— 改名/移动。\`to\` 是裸文件名 = 同目录改名；\`to\` 带 \`子目录/\` 前缀 = 挪到那个目录。\`SKILL.md\` 不能改名。
+- \`delete { path }\` —— 删一个文件。\`SKILL.md\` 不能删；整包销毁没有对应动作，那是用户在面板上的决定。
+- \`enable\` —— **给没有技能包的工作流建一个**：建目录 + 写骨架 \`SKILL.md\`（自动列出该工作流全部可调参数名占位）。**创建只有这一条路**：其他所有动作都要求技能包已存在，没挂技能包时 \`write\` / \`mkdir\` / \`read\` 等都会报"没有技能包"。
+- \`require { required: true/false }\` —— 开关「运行前必读」，与面板勾选是同一个布尔值，见上文规则。
+
+什么时候写：
+- **跑完一个工作流、踩到了坑**（某个参数组合失败、某个音色不存在、视频必须 async 之类），用 \`append\` 把结论追加进 \`SKILL.md\` 的注意事项，或写进 \`references/\` 下的专题文件。下一次（换个会话也一样）就不用重新踩。
+- **总结出了成套的可复用内容**（风格提示词合集、模板、参数配方），\`mkdir\` 一个目录（如 \`templates/\` 或 \`prompts/\`）再 \`write\` 进去，然后在 \`SKILL.md\` 里列一行指向它。
+- **工作流还没有技能包**但你判断它值得有：\`action: enable\` 会建好目录并写入一份骨架（自动列出全部可调参数名），往里填内容即可，别整体覆盖骨架。
+
+写作要求：
+- \`SKILL.md\` **整份都会进上下文**，所以它只放"怎么选、怎么填、哪里会翻车"和一张指向其他文件的目录。成体系的长内容一律拆进子目录，让后来的自己按需去读。
+- 写 \`SKILL.md\` 时带上 \`summary\` 参数（一句话，说明这个工作流什么时候用）——这句话就是 list 里那唯一的一行线索。
+- 只写你**验证过**的结论，不要把猜测写成事实；技能包会被后续所有会话当作权威。
+- 用户手写的内容不要随意重写或删除，优先用 \`append\` 追加。销毁整个技能包没有对应动作，那是用户在面板上的决定。
+
 ## 运行工作流的正确流程（省 token）
 
 1. **list 了解**：\`comfyui_workflow list\` 看每个工作流的名称、描述、**标签**（图生图/文生图/文生视频/图生视频/参考生视频/文生音频/参考生音频等，可自定义）和 \`parameters\` 参数清单（含含义 label 和默认值），挑出符合当前场景的工作流。面板上可点标签筛选工作流列表。
-2. **参数决策**：只依据清单里的参数（键名用英文名），选择/覆盖适合的值——**不需要查看工作流内部结构**。
-3. **run 直接调用**：\`comfyui_workflow run { id, parameters: {...} }\`。插件直接从库里取该工作流的 JSON 提交给 ComfyUI，你**只传参数覆盖值，绝不自己输出或复制完整工作流 JSON**（那会浪费大量 token）。
+2. **有技能包就先读**：list 里某个工作流带 \`技能包:\` 那一行，说明用户为它写了专属说明书（适用场景、参数怎么填、哪些环节会翻车）。选中它之后、运行之前，先 \`comfyui_workflow action: skill { id }\` 把正文读进来并照着做。标注「运行前必读」的，不读会被 run 直接拒绝。没有这行的工作流跳过本步。
+3. **参数决策**：只依据清单里的参数（键名用英文名），选择/覆盖适合的值——**不需要查看工作流内部结构**。
+4. **run 直接调用**：\`comfyui_workflow run { id, parameters: {...} }\`。插件直接从库里取该工作流的 JSON 提交给 ComfyUI，你**只传参数覆盖值，绝不自己输出或复制完整工作流 JSON**（那会浪费大量 token）。
    - **视频/音频工作流一律 \`mode: "async"\`**：生成要几分钟，sync 会等待超时中断（报 generation aborted）。async 立即返回 job id，**启动后不要阻塞等待**（不要对返回的 job 用 wait: true 卡住），继续做其他事，后台任务完成时系统会通知你，到时再用 job_output（不 wait）收集结果和媒体回显。
    - 图片生成可 sync（通常 <1 分钟）；若不确定输出类型，也用 async。
 - \`action: get\` 只在**诊断/检查**工作流内容时使用（它会输出完整 JSON、占用大量 token），它**不是运行路径**。