@kevlns/art-workshop 0.5.2 → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +13 -11
- package/art-workshop.mjs +50 -10
- package/docs/channels.md +49 -0
- package/docs/commands.md +2158 -91
- package/docs/configuration.md +8 -0
- package/docs/core-guidance.md +12 -4
- package/docs/data-formats.md +10 -6
- package/docs/local-models/qwen-image-2.1.json +1 -1
- package/docs/modes.md +12 -6
- package/docs/release-0.6.0.md +9 -0
- package/lib/analysis-worker.mjs +9 -5
- package/lib/backends.mjs +2 -0
- package/lib/candidates.mjs +2 -1
- package/lib/channel-operation.mjs +84 -0
- package/lib/core.mjs +33 -2
- package/lib/edit.mjs +5 -3
- package/lib/generate.mjs +5 -3
- package/lib/generation-policy.mjs +1 -1
- package/lib/object-format.mjs +2 -2
- package/lib/prompt-structure.mjs +3 -3
- package/lib/service.mjs +21 -0
- package/lib/style-bundle.mjs +19 -6
- package/lib/style-contract.mjs +3 -3
- package/lib/style-lifecycle.mjs +7 -73
- package/lib/style-report.mjs +1 -1
- package/lib/style-samples.mjs +94 -0
- package/lib/task-contract.mjs +2 -1
- package/lib/templates.mjs +1 -1
- package/lib/video/PROVENANCE.json +63 -0
- package/lib/video/atomic.mjs +32 -0
- package/lib/video/channel.mjs +70 -0
- package/lib/video/contract-local-media.mjs +42 -0
- package/lib/video/contract-story.mjs +213 -0
- package/lib/video/contract-video.mjs +117 -0
- package/lib/video/contracts.mjs +3 -0
- package/lib/video/h3.mjs +232 -0
- package/lib/video/local-runtime.mjs +20 -0
- package/lib/video/media.mjs +223 -0
- package/lib/video/models.mjs +336 -0
- package/lib/video/path.mjs +18 -0
- package/lib/video/process.mjs +15 -0
- package/lib/video/resource.mjs +15 -0
- package/lib/video/service.mjs +731 -0
- package/lib/video/workflow.mjs +571 -0
- package/lib/video.mjs +12 -0
- package/lib/workspace.mjs +35 -21
- package/package.json +8 -3
- package/rules/core-guidance.json +1 -1
- package/skills/art-workshop/SKILL.md +4 -2
- package/skills/art-workshop/references/project.md +18 -9
- package/skills/art-workshop/references/style-discussion.md +8 -6
- package/skills/art-workshop/references/video.md +13 -0
- package/v-cli.plugin.json +4380 -276
package/README.md
CHANGED
|
@@ -4,11 +4,11 @@
|
|
|
4
4
|
|
|
5
5
|
## 功能
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
同一个工具包提供两个独立二级通道:`image` 管理项目风格、参考图、图片生成、编辑与定版;`video` 管理剧本、镜头、视频生成、成片合成与精修。图片支持本地 ComfyUI 与远程图片模型,视频使用已配置的本机 ComfyUI 和 FFmpeg。
|
|
8
8
|
|
|
9
9
|
## 环境要求
|
|
10
10
|
|
|
11
|
-
Node.js 20
|
|
11
|
+
图片通道需要 Node.js 20.9 及以上;视频通道需要 Node.js 22.13 及以上及 SQLite 支持。本地生成还需工具检测通过的 Python、显卡驱动与 ComfyUI 环境;视频合成和取帧需要 FFmpeg / ffprobe。
|
|
12
12
|
|
|
13
13
|
## 安装
|
|
14
14
|
|
|
@@ -19,22 +19,24 @@ npm install -g @kevlns/art-workshop
|
|
|
19
19
|
## 快速开始
|
|
20
20
|
|
|
21
21
|
```sh
|
|
22
|
-
art-workshop config show
|
|
23
|
-
art-workshop config validate
|
|
24
|
-
art-workshop agent index
|
|
22
|
+
art-workshop image config show
|
|
23
|
+
art-workshop image config validate
|
|
24
|
+
art-workshop image agent index
|
|
25
25
|
```
|
|
26
26
|
|
|
27
27
|
## 使用说明
|
|
28
28
|
|
|
29
29
|
### 使用流程
|
|
30
30
|
|
|
31
|
-
|
|
32
|
-
2. 用 `job template` 获取任务模板,填写实际需求后创建任务。动态参考先 `job analyze`;编辑底图单独绑定。
|
|
33
|
-
3. 编译 `generate plan` 或 `edit plan`,保存并用 `run --plan ... --dry` 核对模型、尺寸、候选数、输入和参数转换。
|
|
34
|
-
4. 按任务授权执行,保存 taskId;前台和后台都登记运行。查询原身份,不因超时或重启重复提交。
|
|
35
|
-
5. `check` 核验产物,`candidate finalize` 定版。替换需 `--replace`,删除需 `--confirm`,均保留事实记录。
|
|
31
|
+
图片命令以 `art-workshop image` 或 `v-cli art image` 开头;原有不带 `image` 的图片命令继续兼容。视频以 `art-workshop video` 或 `v-cli art video` 开头,`--workspace` 明确指定工程根目录,不复用图片对象工作区。两条通道的模型配置、任务身份和状态分别保存。完整调用、SDK 和失败模式见 [图片与视频通道](docs/channels.md)。
|
|
36
32
|
|
|
37
|
-
|
|
33
|
+
1. 创建 schemaVersion 2 工程和风格,按关注点导入分析参考;直接填写并保存规则,讨论直接整理成 config.rules,无需独立分析报告。规则随时增删修改,保存有效规则即生效。
|
|
34
|
+
2. 用 `style sample-job` 创建仅规则打样任务,--count 可指定每个主体生成 1~4 张候选,配置模型、编译预案并按任务授权生成。用户认可候选后用 `style sample-select` 完成样张定版并加入当前风格的运行时参考;不合适时修改规则重新打样。
|
|
35
|
+
3. 用 `job template` 创建实际任务,填写需求,选择 `styleReferenceMode` 为 `approved`(运行时参考)或 `text-only`(仅规则)。动态参考先 `job analyze`;编辑底图单独绑定。
|
|
36
|
+
4. 编译 `generate plan` 或 `edit plan`,保存并用 `run --plan ... --dry` 核对模型、尺寸、候选数、样张输入和参数转换,再按任务授权执行。
|
|
37
|
+
5. 保存执行 taskId;前台和后台都登记运行。查询原身份,不因超时或重启重复提交。`check` 核验产物,`candidate finalize` 定版;替换需 `--replace`,删除需 `--confirm`,均保留事实记录。
|
|
38
|
+
|
|
39
|
+
风格按当前 revision 保存,不要求派生或重新采用;历史核心快照和批次保留,规则或样张变化后重新编译预案。原始分主题参考用于分析,不自动整图上传。运行时参考与规则哈希绑定,过期样张不作为当前规则的视觉依据;后端不支持图片输入时明确报错,可选择仅规则模式。任务空闲后可按原身份更新配置。job discard 归档任务,job restore 按当前版本恢复;配置、收藏与历史图片保留。任务列表默认按执行中、待定版、草稿、已定版排序;运行状态与停止证据分别判断,不能只看终态释放占用。
|
|
38
40
|
|
|
39
41
|
### 后端与数据归属
|
|
40
42
|
|
package/art-workshop.mjs
CHANGED
|
@@ -4,9 +4,50 @@ import {readdirSync,existsSync} from 'node:fs';
|
|
|
4
4
|
import {join,resolve} from 'node:path';
|
|
5
5
|
import {readJson,writeJson} from './lib/shared.mjs';
|
|
6
6
|
const args=process.argv.slice(2),pos=[],options={};
|
|
7
|
+
const channel=['image','video'].includes(args[0])?args.shift():null;
|
|
7
8
|
if(args.length===1&&['--version','-V'].includes(args[0])){console.log(readJson(new URL('./package.json',import.meta.url)).version);process.exit(0);}
|
|
8
|
-
const
|
|
9
|
-
|
|
9
|
+
const imageHelp='art-workshop image: config path/show/init/validate | doctor [--backend ID] [--start] | workflow list | environment guide/list/prepare/inspect/verify/register/unregister | refs guide | agent index/docs/export | conversation start/status/cancel/resume | list | style export/import/sources/create/list/read/update/derive/discard/sample-job/sample-select/sample-remove/recover/show | generate show/plan/run | edit show/plan/run | task list/status/wait/cancel/recover/resume | shutdown | check RUN | project init/upgrade | job template/from-candidate/create/list/read/update/derive/discard/restore/analyze | reference import/list/update/remove | candidate list/favorites/favorite/finalize/delete/finalizations | compare PLAN PLAN\nrun --background 返回任务 ID;--backend 选择后端。shutdown 停止当前工作区关联任务,核验共享队列和进程身份后关闭本地服务。';
|
|
10
|
+
const videoHelp='art-workshop video: describe | snapshot | settings get/save/presets h3 | runtime status/start/stop | task list/read/create/rename/archive | operation create/update/rename/derive/validate/run/resume/cancel/accept/bind | script read/update/plan/apply | film compose/refine/preview/adopt/undo | material list/import/import-file/upload/hide | image | media status | execution status\n--workspace <工程根目录> --project <项目身份,默认 project> --input <工程内 JSON 对象文件> --operation <稳定CLI操作身份>\n所有写入必须传 --operation,重复同身份只核对原回执;execution status --operation 查询意图/回执。先 describe 读取业务输入契约;写入保留 revision/expectedRevision,生成必须传稳定 requestId。unknown 只查询原运行,不换 ID 重投。读取不会启动服务,runtime start/operation run/film 操作必须显式调用。';
|
|
11
|
+
const help='art-workshop: image(图片)与 video(视频)两个独立通道。图片旧根命令继续兼容。\n'+imageHelp+'\n'+videoHelp+'\n也可用 v-cli art 调用;先 v-cli agent docs art,再 v-cli agent describe art --json 查看完整参数。';
|
|
12
|
+
if(!args.length||args.length===1&&['--help','-h','help'].includes(args[0])){console.log(channel==='video'?videoHelp:channel==='image'?imageHelp:help);process.exit(0);}
|
|
13
|
+
if(channel==='video'){
|
|
14
|
+
let api;
|
|
15
|
+
try{
|
|
16
|
+
const positions=[],values={},allowed=new Set(['workspace','project','input','operation']);
|
|
17
|
+
for(let index=0;index<args.length;index++){
|
|
18
|
+
const argument=args[index];
|
|
19
|
+
if(argument.startsWith('-')){
|
|
20
|
+
const key=argument.slice(2);
|
|
21
|
+
if(!argument.startsWith('--')||!allowed.has(key)||key in values)throw Object.assign(new Error('未知或重复视频参数 '+argument),{code:'video-cli-argument-invalid'});
|
|
22
|
+
const value=args[++index];if(!value||value.startsWith('--'))throw Object.assign(new Error('视频参数缺少值 '+argument),{code:'video-cli-argument-invalid'});values[key]=value;
|
|
23
|
+
}else positions.push(argument);
|
|
24
|
+
}
|
|
25
|
+
const {actions,readActions,createVideoChannel}=await import('./lib/video.mjs');
|
|
26
|
+
const action=positions.join('.');
|
|
27
|
+
if(!actions.has(action)&&action!=='execution.status')throw Object.assign(new Error('未知视频操作:'+positions.join(' ')),{code:'video-action-invalid'});
|
|
28
|
+
const root=resolve(values.workspace||process.cwd()),workspaceId=values.project||'project';
|
|
29
|
+
if(action==='execution.status'){
|
|
30
|
+
if(values.input)throw new Error('execution status 不接受 --input');
|
|
31
|
+
const {readChannelOperation}=await import('./lib/channel-operation.mjs');
|
|
32
|
+
console.log(JSON.stringify(await readChannelOperation({root,operationId:values.operation}),null,2));process.exit(0);
|
|
33
|
+
}
|
|
34
|
+
let input={};
|
|
35
|
+
if(values.input){
|
|
36
|
+
const {projectPath}=await import('./lib/video/path.mjs');
|
|
37
|
+
const {readFile,stat}=await import('node:fs/promises');
|
|
38
|
+
const file=await projectPath(root,values.input),info=await stat(file);
|
|
39
|
+
if(!info.isFile()||info.size>32*1024*1024)throw Object.assign(new Error('视频请求必须为不超过32MiB的工程内JSON文件'),{code:'video-input-invalid'});
|
|
40
|
+
input=JSON.parse(await readFile(file,'utf8'));
|
|
41
|
+
if(!input||typeof input!=='object'||Array.isArray(input))throw Object.assign(new Error('视频请求必须为JSON对象'),{code:'video-input-invalid'});
|
|
42
|
+
}
|
|
43
|
+
api=createVideoChannel({root,workspaceId});
|
|
44
|
+
const readonly=readActions.has(action)||action==='media.status';
|
|
45
|
+
const result=readonly?await api.execute(action,input):await (await import('./lib/channel-operation.mjs')).executeChannelOperation({root,workspaceId,operationId:values.operation,action,input,execute:()=>api.execute(action,input)});
|
|
46
|
+
console.log(JSON.stringify(result,null,2));
|
|
47
|
+
}catch(error){console.log(JSON.stringify({ok:false,error:error.message,...(error.code?{code:error.code}:{}),...(error.unknown===true?{unknown:true}:{}),...(error.operationId?{operationId:error.operationId}:{})},null,2));process.exitCode=1;}
|
|
48
|
+
finally{if(api)await api.dispose();}
|
|
49
|
+
process.exit(process.exitCode||0);
|
|
50
|
+
}
|
|
10
51
|
const {taskObjectView}=await import('./lib/asset-profile.mjs');
|
|
11
52
|
const {loadJob,loadProject}=await import('./lib/project.mjs');
|
|
12
53
|
const {referenceRoot,referenceGuide}=await import('./lib/refs.mjs');
|
|
@@ -22,8 +63,9 @@ const {startTask,taskStatus,taskView,recoverTask,resumeTask,waitTask,cancelTask,
|
|
|
22
63
|
const {runtimeRoot,tasks}=await import('./lib/runtime.mjs');
|
|
23
64
|
const {validateConfiguration,doctor}=await import('./lib/diagnostics.mjs');
|
|
24
65
|
const {finishMigration,createProject,createObject,listObjects,readObject,styleView,updateObject,deriveObject,discardObject,restoreTask,importReference,removeReference,updateReference,taskDisplayState,STYLE_CATEGORIES,TASK_PURPOSES}=await import('./lib/workspace.mjs');
|
|
25
|
-
const {startAnalysis,
|
|
66
|
+
const {startAnalysis,recoverStyleAdoption}=await import('./lib/style-lifecycle.mjs');
|
|
26
67
|
const {candidates,finalize,deleteCandidate,finalizations,editFromCandidate}=await import('./lib/candidates.mjs');
|
|
68
|
+
const {createStyleSampleJob,selectStyleSample,removeStyleSample}=await import('./lib/style-samples.mjs');
|
|
27
69
|
const {favoriteList,setFavorite}=await import('./lib/favorites.mjs');
|
|
28
70
|
const {upgradeProject}=await import('./lib/migration.mjs');
|
|
29
71
|
const {workflowList}=await import('./lib/workflows.mjs');
|
|
@@ -32,9 +74,9 @@ const {deploymentGuide}=await import('./lib/deployment-guide.mjs');
|
|
|
32
74
|
const {inspectInstallation,discoverInstallations}=await import('./lib/environments.mjs');
|
|
33
75
|
const {verifyInstallation,registerInstallation,unregisterInstallation}=await import('./lib/environment-operations.mjs');
|
|
34
76
|
const flags=new Set(['dry','explore','background','start','replace','confirm','all-variants']);
|
|
35
|
-
const allowed=new Set(['config','workspace','output-dir','refs-dir','cache-dir','directory','host','session','request','endpoint','guide','project','input','out','report','note','core','job','plan','item','variant','offset','limit','file','backend','timeout','kind','id','revision','source','category','purposes','mapping','run','candidate','actor','operation','retry-run','item-id','value','name',...flags]);
|
|
77
|
+
const allowed=new Set(['config','workspace','output-dir','refs-dir','cache-dir','directory','host','session','request','endpoint','guide','project','input','out','report','note','core','job','plan','item','variant','offset','limit','file','backend','timeout','kind','id','revision','source','category','purposes','mapping','run','candidate','sample','actor','operation','retry-run','item-id','value','name','count',...flags]);
|
|
36
78
|
for(let i=0;i<args.length;i++){if(args[i].startsWith('--')){const k=args[i].slice(2);if(!allowed.has(k)||k in options) throw new Error('未知或重复参数 '+k);options[k]=flags.has(k)?true:args[++i];if(options[k]===undefined) throw new Error('参数缺少值 '+k);}else pos.push(args[i]);}
|
|
37
|
-
const print=x=>console.log(JSON.stringify(x?.schema==='art-workshop/style'?styleView(settings.paths.workspace,x):x,null,2));
|
|
79
|
+
const print=x=>console.log(JSON.stringify(x?.schema==='art-workshop/style'&&!x.format?styleView(settings.paths.workspace,x):x,null,2));
|
|
38
80
|
if(pos[0]==='workflow'&&pos[1]==='list'){print(workflowList());process.exit(0);}
|
|
39
81
|
let settings;
|
|
40
82
|
try{settings=loadSettings({file:options.config?resolve(options.config):undefined,workspace:options.workspace,output:options['output-dir'],refs:options['refs-dir'],cache:options['cache-dir']});}
|
|
@@ -121,12 +163,10 @@ try {
|
|
|
121
163
|
}
|
|
122
164
|
else if(module==='style'){
|
|
123
165
|
const projectId=required('project');
|
|
124
|
-
if(action==='
|
|
166
|
+
if(action==='sample-job')print(await createStyleSampleJob(settings,projectId,required('id'),Number(required('revision')),{name:options.name,...(options.count!==undefined?{count:Number(options.count)}:{})}));
|
|
167
|
+
else if(action==='sample-select')print(await selectStyleSample(settings,projectId,required('id'),Number(required('revision')),{job:required('job'),run:required('run'),candidate:required('candidate'),note:options.note}));
|
|
168
|
+
else if(action==='sample-remove')print(await removeStyleSample(settings,projectId,required('id'),Number(required('revision')),required('sample')));
|
|
125
169
|
else if(action==='recover')print(await recoverStyleAdoption(settings,projectId,required('id')));
|
|
126
|
-
else if(action==='revise')print(styleView(ROOT,await reviseStyleRules(settings,projectId,required('id'),Number(required('revision')),readJson(path(required('input'))))));
|
|
127
|
-
else if(action==='resolve')print(styleView(ROOT,await resolveStyleIssue(settings,projectId,required('id'),Number(required('revision')),readJson(path(required('input'))))));
|
|
128
|
-
else if(action==='adopt')print(await adoptStyle(settings,projectId,required('id'),Number(required('revision')),{note:options.note}));
|
|
129
|
-
else if(action==='validate') print(validateReport(readJson(path(required('report'))),projectId));
|
|
130
170
|
else if(action==='show') print(loadCore(projectId,required('core'),ROOT));
|
|
131
171
|
else throw new Error('未知 style 操作');
|
|
132
172
|
}else if(['generate','edit'].includes(module)){
|
package/docs/channels.md
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# 图片与视频通道
|
|
2
|
+
|
|
3
|
+
`art-workshop` 是同一工具包,`image` 和 `video` 是独立二级通道。宿主可以把它们展示成相邻的“图片工坊”“视频工坊”,两者无需共用一个页面或一套任务状态。
|
|
4
|
+
|
|
5
|
+
## 调用与兼容
|
|
6
|
+
|
|
7
|
+
图片命令使用 `art-workshop image ...` 或 `v-cli art image ...`。原有 `art-workshop style ...`、`art-workshop generate ...` 及 `art.*` 结构化能力继续兼容;`art.image-*` 提供明确的图片通道能力。图片对象、计划和运行仍走原来的图片执行链路。
|
|
8
|
+
|
|
9
|
+
视频命令使用 `art-workshop video ...` 或 `v-cli art video ...`,对应结构化能力为 `art.video-*`。`--workspace` 指向工程绝对根目录。请求 JSON 通过工程内 `--input` 文件传入,不把整份剧本、图片或凭据拼入命令行。具体路径与参数以 [命令参考](commands.md) 为准。
|
|
10
|
+
|
|
11
|
+
视频通道处理任务、操作、剧本规划、素材、模型设置、运行时观察、成片和精修。读取、校验、规划与保存配置不会启动模型生成;只有显式运行操作才提交生成。运行继续使用原 `requestId`、`runId` 和 `upstreamId`,恢复只查询原队列或原结果。
|
|
12
|
+
|
|
13
|
+
## SDK 与宿主边界
|
|
14
|
+
|
|
15
|
+
```js
|
|
16
|
+
import { createVideoChannel } from '@kevlns/art-workshop/video';
|
|
17
|
+
|
|
18
|
+
const channel = createVideoChannel({ root: projectRoot, workspaceId });
|
|
19
|
+
try {
|
|
20
|
+
const tasks = await channel.execute('task.list', {});
|
|
21
|
+
} finally {
|
|
22
|
+
await channel.dispose();
|
|
23
|
+
}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
SDK 的 `execute / snapshot / media / settingsRevision / dispose` 由同一包内的 VideoService、VideoModels、VideoWorkflow、VideoMedia 和本地运行时实现。宿主注入图片素材来源及覆盖范围;未注入来源时明确报告不可用,不扫描其他宿主的会话或资料。
|
|
27
|
+
|
|
28
|
+
DSH 负责自己的权限、项目与会话身份、原生附件准入及外层事务。工具包不反向依赖 DSH,不创建应用服务器、聊天会话或审批系统。DSH 的视频入口调用本 SDK,不维护第二份 VideoService 算法。
|
|
29
|
+
|
|
30
|
+
## 配置、状态与失败
|
|
31
|
+
|
|
32
|
+
| 内容 | 归属 |
|
|
33
|
+
| --- | --- |
|
|
34
|
+
| 图片全局默认配置 | `<VANT_HOME 或 ~/.vant>/tools/art-workshop/config.json` |
|
|
35
|
+
| 图片项目对象与批次 | 显式绑定的图片 workspace;DSH 通常绑定工程 `.vant/art` |
|
|
36
|
+
| 视频模型、工作流与 FFmpeg 配置 | 工程 `.vant/config/video.json` |
|
|
37
|
+
| 视频任务、操作、素材与成片 | 工程 `.vant/video`,真源为 `project.json` |
|
|
38
|
+
| 视频外层请求、意图与回执 | 工程 `.vant/state/video` |
|
|
39
|
+
| 跨进程视频资源锁 | 工程 `.vant/state/locks`,沿用规范路径的 SHA-256 SQLite 身份 |
|
|
40
|
+
|
|
41
|
+
图片和视频保持各自配置、版本和运行记录。视频设置按旧 revision 校验后保存,目录跳转、路径逃逸和损坏状态明确拒绝,不覆盖为默认值。请求及结果未知时保留原身份与未决索引,不能通过更换操作 ID 或入口再次提交。
|
|
42
|
+
|
|
43
|
+
视频需要 Node.js 22.13 及以上和可用 SQLite;不足时返回 `video-runtime-unsupported`,不改变图片通道的 Node.js 20.9 兼容范围。DSH 找不到带视频通道的工具包时返回 `video-core-unavailable`,不会回退到另一份内核。
|
|
44
|
+
|
|
45
|
+
视频队列取消仅删除原排队任务。共享运行中的 ComfyUI 没有安全的通用单任务中断接口时,返回 `video-running-cancel-unavailable`,不调用全局 interrupt。模型请求丢回执、下载损坏或结果写入失败均不能作为重新付费生成的依据。
|
|
46
|
+
|
|
47
|
+
## 验证边界
|
|
48
|
+
|
|
49
|
+
协议 fixture、真实 FFmpeg 媒体处理、包安装和 DSH 界面分别验证。fake HTTP 返回的生成结果只证明调用、恢复与产物处理机制,不代表真实 GPU 或远程模型完成生成。未发布的源码与本地开发链接不代表 npm 已更新。
|