@kevlns/art-workshop 0.6.5 → 0.6.6

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 CHANGED
@@ -4,11 +4,11 @@
4
4
 
5
5
  ## 功能
6
6
 
7
- 同一个工具包提供两个独立二级通道:`image` 管理项目风格、参考图、图片生成、编辑与定版;`video` 管理剧本、镜头、视频生成、成片合成与精修。图片支持本地 ComfyUI 与远程图片模型,视频使用已配置的本机 ComfyUI 和 FFmpeg。
7
+ `image` 管理图片风格、参考、制作与定版,`video` 管理剧本、镜头和成片,`spine` 从原画拆件、骨架蒙皮和动作配方构建 Spine 4.2 运行资源,并生成验收帧。
8
8
 
9
9
  ## 环境要求
10
10
 
11
- 图片通道需要 Node.js 20.9 及以上;视频通道需要 Node.js 22.13 及以上及 SQLite 支持。本地生成还需工具检测通过的 Python、显卡驱动与 ComfyUI 环境;视频合成和取帧需要 FFmpeg / ffprobe。
11
+ 图片通道需要 Node.js 20.9 及以上;视频通道需要 Node.js 22.13 及以上及 SQLite 支持。本地生成还需工具检测通过的 Python、显卡驱动与 ComfyUI 环境;视频合成和取帧需要 FFmpeg / ffprobe。 Spine 拆件与编译在本地执行,WebGL 取帧需要 Chrome、Edge 或 Chromium。
12
12
 
13
13
  ## 安装
14
14
 
@@ -28,7 +28,7 @@ art-workshop image agent index
28
28
 
29
29
  ### 使用流程
30
30
 
31
- 图片命令以 `art-workshop image` 或 `v-cli art image` 开头;原有不带 `image` 的图片命令继续兼容。视频以 `art-workshop video` 或 `v-cli art video` 开头,`--workspace` 明确指定工程根目录,不复用图片对象工作区。两条通道的模型配置、任务身份和状态分别保存。完整调用、SDK 和失败模式见 [图片与视频通道](docs/channels.md)。
31
+ 用 `v-cli art image`、`v-cli art video` 和 `v-cli art spine` 选择通道,也可直接调用 `art-workshop`。执行 `v-cli art spine describe` 读取拆件、绑定与取帧配方。工作区、输入和产物见[制作通道](docs/channels.md)。
32
32
 
33
33
  1. 创建 schemaVersion 2 工程和风格,按关注点导入分析参考;讨论后保存描述、约束和绘制规则,通过 `style confirm` 确定性编译当前风格。修改内容后需要重新确认。
34
34
  2. 用 `style sample-job` 创建仅文字打样任务,`--input` 可提交自定义主体、验证目标、尺寸和生成方案,`--count` 指定每个主体生成 1~4 张候选,配置模型、编译预案并按任务授权生成。用户认可候选后用 `style sample-select` 完成样张定版并加入当前风格的运行时参考;不合适时修改配置并重新确认,再准备新样张。
package/art-workshop.mjs CHANGED
@@ -15,7 +15,7 @@ const channel=['image','video'].includes(args[0])?args.shift():null;
15
15
  if(args.length===1&&['--version','-V'].includes(args[0])){console.log(readJson(new URL('./package.json',import.meta.url)).version);process.exit(0);}
16
16
  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/confirm/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 停止当前工作区关联任务,核验共享队列和进程身份后关闭本地服务。';
17
17
  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 操作必须显式调用。';
18
- const help='art-workshop: image(图片)、video(视频)、spine(骨骼动画)制作通道;spine describe 查看制作契约。图片旧根命令继续兼容。\n'+imageHelp+'\n'+videoHelp+'\n也可用 v-cli art 调用;先 v-cli agent docs art,再 v-cli agent describe art --json 查看完整参数。';
18
+ const help='art-workshop: image(图片)、video(视频)、spine(骨骼动画)制作通道;spine describe 查看制作契约。\n'+imageHelp+'\n'+videoHelp+'\n也可用 v-cli art 调用;先 v-cli agent docs art,再 v-cli agent describe art --json 查看完整参数。';
19
19
  if(!args.length||args.length===1&&['--help','-h','help'].includes(args[0])){console.log(channel==='video'?videoHelp:channel==='image'?imageHelp:help);process.exit(0);}
20
20
  if(channel==='video'){
21
21
  let api;
package/docs/channels.md CHANGED
@@ -1,14 +1,14 @@
1
- # 图片与视频通道
1
+ # 美术制作通道
2
2
 
3
- `art-workshop` 是同一工具包,`image` 和 `video` 是独立二级通道。宿主可以把它们展示成相邻的“图片工坊”“视频工坊”,两者无需共用一个页面或一套任务状态。
3
+ 美术工坊提供图片、视频与 Spine 三个页签。三个通道的制作命令可单独运行。
4
4
 
5
- ## 调用与兼容
5
+ ## 调用
6
6
 
7
- 图片命令使用 `art-workshop image ...` 或 `v-cli art image ...`。原有 `art-workshop style ...`、`art-workshop generate ...` 及 `art.*` 结构化能力继续兼容;`art.image-*` 提供明确的图片通道能力。图片对象、计划和运行仍走原来的图片执行链路。
7
+ - 图片使用 `v-cli art image` 或 `art-workshop image` 管理风格、参考和制作任务。
8
+ - 视频使用 `v-cli art video` 或 `art-workshop video`。传入工程根目录和工程内请求文件,按任务身份保存剧本、镜头、运行记录和成片。
9
+ - Spine 使用 `v-cli art spine` 或 `art-workshop spine`。`describe` 返回配方,`parts` 从原型生成可配准的部件,`build` 导出骨架与动作索引,`capture` 实绘指定动作并输出 PNG 或 GIF。SDK 入口为 `@kevlns/art-workshop/spine` 的 `spineContract` 与 `runSpine(root, action, input)`。
8
10
 
9
- 视频命令使用 `art-workshop video ...` 或 `v-cli art video ...`,对应结构化能力为 `art.video-*`。`--workspace` 指向工程绝对根目录。请求 JSON 通过工程内 `--input` 文件传入,不把整份剧本、图片或凭据拼入命令行。具体路径与参数以 [命令参考](commands.md) 为准。
10
-
11
- 视频通道处理任务、操作、剧本规划、素材、模型设置、运行时观察、成片和精修。读取、校验、规划与保存配置不会启动模型生成;只有显式运行操作才提交生成。运行继续使用原 `requestId`、`runId` 和 `upstreamId`,恢复只查询原队列或原结果。
11
+ 完整选项见[命令参考](commands.md)。
12
12
 
13
13
  ## SDK 与宿主边界
14
14
 
package/docs/commands.md CHANGED
@@ -22,7 +22,7 @@
22
22
 
23
23
  ## 执行约束
24
24
 
25
- `image` 与 `video` 是独立二级通道。图片可使用 `v-cli art image ...`,旧图片根命令与原 `art.*` 能力身份保留。新 SDK 暴露 `art.image-*` 和 `art.video-*`;已安装旧版 v-cli 不会自动获得新能力。
25
+ 选择 `image`、`video` 或 `spine` 通道。对应能力 ID 为 `art.image-*`、`art.video-*` 和 `art.spine-*`。Spine 制作配方和新输出目录均绑定工程,`spine describe` 提供完整示例。
26
26
 
27
27
  图片的相对计划、输入和报告路径以 workspace 为基准;运行批次以 output 为基准。参考导入的源文件建议使用绝对路径。查询与预演不初始化参考目录。
28
28
 
@@ -12,7 +12,7 @@
12
12
 
13
13
  ### 配置入口
14
14
 
15
- 本页的全局配置默认属于图片通道,`image` 前缀与旧命令使用同一份配置。视频通道显式绑定工程根目录,模型和工作流单独保存到 `.vant/config/video.json`,任务及成片保存在 `.vant/video`;不会把视频配置写入图片全局设置。详见 [图片与视频通道](channels.md)。
15
+ 本页说明图片通道的全局配置。视频设置在工程的 `.vant/config/video.json`,任务与成片位于 `.vant/video`。Spine 通过工程内的配方文件指定原型、部件、骨架、动作和输出目录,详见[美术制作通道](channels.md)。
16
16
 
17
17
  `config path/show/init/validate` 分别查询位置、生效配置、创建模板和校验。`config init` 不覆盖已有文件。查询、发现和预演不创建参考目录;`config validate` 不联网、不启动服务。
18
18
 
@@ -43,7 +43,7 @@ async function makeAtlas(root,folder,parts,out,name) {
43
43
  names.add(id.toLowerCase());
44
44
  const img=await projectPath(root,join(folder,part.image)),data=await readFile(img);
45
45
  const {width:w,height:h,format}=await sharp(data).metadata();
46
- if(format!=='png'||w!==part.rect.width||h!==part.rect.height||w+4>4096||h+4>4096) throw Error(id+' 的 PNG 尺寸无法打包');
46
+ if(format!=='png'||w!== (part.textureWidth??part.rect.width)||h!== (part.textureHeight??part.rect.height)||w+4>4096||h+4>4096) throw Error(id+' 的 PNG 尺寸无法打包');
47
47
  if(x+w+4>4096) {y+=row;x=0;row=0;}
48
48
  if(y+h+4>4096) await flush();
49
49
  const padded=await sharp(data).extend({top:2,left:2,right:2,bottom:2,extendWith:'copy'}).png().toBuffer();
@@ -13,7 +13,7 @@ function dimensions(actual, expected, label) {
13
13
  if(actual.width !== expected.width || actual.height !== expected.height) throw Error(label+' 尺寸与定位矩形不一致');
14
14
  }
15
15
  export async function splitParts(root, recipe, out) {
16
- const source = await projectPath(root,recipe.prototype);
16
+ const source = await projectPath(root,recipe.sourceImage ?? recipe.prototype);
17
17
  const {width,height} = await sharp(source).metadata();
18
18
  if(width*height>32e6 || !Array.isArray(recipe.parts) || !recipe.parts.length || recipe.parts.length>256) throw Error('需要原型和 1–256 个有序部件');
19
19
  const images = join(out,'images');
@@ -30,12 +30,16 @@ export async function splitParts(root, recipe, out) {
30
30
  if(pixels>64e6) throw Error('部件总像素过大');
31
31
  const pivot=part.pivot ?? [left+w/2,top+h/2];
32
32
  if(!Array.isArray(pivot)||pivot.length!==2||!pivot.every(Number.isFinite)) throw Error('轴心使用母版像素坐标 [x,y]');
33
+ let fullSize, textureWidth=w, textureHeight=h;
33
34
  let image=sharp(source).extract(part.rect).ensureAlpha();
34
35
  if(part.replacement) {
35
36
  const replacement=await projectPath(root,part.replacement);
36
37
  const size=await sharp(replacement).metadata();
37
38
  if(size.width*h!==size.height*w) throw Error(name+' 补绘图与部件矩形宽高比不一致');
38
- image=sharp(replacement).resize(w,h).ensureAlpha();
39
+ textureWidth=size.width; textureHeight=size.height; pixels+=Math.max(0,size.width*size.height-w*h);
40
+ if(pixels>64e6) throw Error('部件总像素过大');
41
+ fullSize=sharp(replacement).ensureAlpha();
42
+ image=fullSize.clone().resize(w,h);
39
43
  }
40
44
  let coverage;
41
45
  if(part.mask) {
@@ -61,16 +65,20 @@ export async function splitParts(root, recipe, out) {
61
65
  if(coverage) {
62
66
  const alpha=await sharp(coverage,{raw:{width:w,height:h,channels:1}}).toColourspace('srgb').joinChannel(coverage,{raw:{width:w,height:h,channels:1}}).png().toBuffer();
63
67
  image=image.composite([{input:alpha,blend:'dest-in'}]);
68
+ if(fullSize) {
69
+ const textureMask=await sharp(alpha).resize(textureWidth,textureHeight).png().toBuffer();
70
+ fullSize=fullSize.composite([{input:textureMask,blend:'dest-in'}]);
71
+ }
64
72
  }
65
73
  const bytes=await image.png().toBuffer();
66
- await writeFile(join(images,name+'.png'),bytes);
74
+ await writeFile(join(images,name+'.png'),fullSize ? await fullSize.png().toBuffer() : bytes);
67
75
  layers.push({input:bytes,left,top});
68
- parts.push({name,rect:part.rect,pivot,occludedBy:part.occludedBy ?? [],image:'images/'+name+'.png'});
76
+ parts.push({name,textureWidth,textureHeight,rect:part.rect,pivot,occludedBy:part.occludedBy ?? [],image:'images/'+name+'.png'});
69
77
  }
70
78
  for(const part of parts) if(!Array.isArray(part.occludedBy)||part.occludedBy.some(id=>!parts.some(p=>p.name===id) || id===part.name)) throw Error('遮挡关系引用了无效部件:'+part.name);
71
79
  await sheet(width,height).composite(layers).png().toFile(join(out,'assembled.png'));
72
80
  if(patched) await sharp(patched,{raw:{width,height,channels:4}}).png().toFile(join(out,'patched.png'));
73
- const metadata={width,height,prototype:recipe.prototype,parts,...(patched?{patched:"patched.png"}:{})};
81
+ const metadata={width,height,sourceImage:recipe.sourceImage ?? recipe.prototype,parts,...(patched?{patched:"patched.png"}:{})};
74
82
  await writeFile(join(out,'parts.json'),JSON.stringify(metadata,null,2));
75
83
  return metadata;
76
84
  }
package/lib/spine.mjs CHANGED
@@ -5,7 +5,7 @@ import {splitParts} from './spine/parts.mjs';
5
5
  import {buildRig} from './spine/build.mjs';
6
6
 
7
7
  export const spineContract={
8
- parts:{input:{prototype:'art/prototype.png',out:'work/parts-01',parts:[{name:'body',rect:{left:0,top:0,width:100,height:100},pivot:[50,75],occludedBy:[]}]},optional:'parts 的顺序为从后到前。mask 取透明通道或灰度,可传母版大小或局部大小。replacement 接受同比例补绘图。',outputs:['parts.json','images/','assembled.png']},
8
+ parts:{input:{sourceImage:'art/prototype.png',out:'work/parts-01',parts:[{name:'body',rect:{left:0,top:0,width:100,height:100},pivot:[50,75],occludedBy:[]}]},optional:'parts 的顺序为从后到前。mask 取透明通道或灰度,可传母版大小或局部大小。replacement 接受同比例补绘图。',outputs:['parts.json','images/','assembled.png']},
9
9
  build:{input:{parts:'work/parts-01/parts.json',name:'actor',out:'work/rig-01',animations:{wave_001:{bones:{body:{rotate:[{time:0,value:0},{time:0.5,value:22}]}}}}},meshExample:{slot:'body',uvs:[0,0,1,0,0,1],triangles:[0,1,2],points:[[['body',-50,75,1]],[['body',50,75,1]],[['body',-50,-25,1]]]},optional:'bones 按名增改骨骼;meshes 为网格配方列表,points 每项含 [骨名,骨局部x,y,正权重],权重和为1。rig 可指定可编辑的 Spine 4.2 JSON,保留其骨骼、皮肤、约束、网格、权重及时间线;animations 按动作名合并。未传 rig 时使用 parts 中的轴心建立绑定。',outputs:['骨架 JSON','atlas','PNG 图集','images/','animations.json','report.json']},
10
10
  capture:{input:{source:'work/rig-01/actor.json',out:'work/frames-01',clip:'wave_001',width:384,height:384,frames:8,gif:true},optional:'times 可直接指定秒数。无头 Chromium 使用 Spine WebGL 4.2 捕获实际像素。',outputs:['逐帧 PNG','comparison.png','preview.gif(可选)','capture.json']}
11
11
  };
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@kevlns/art-workshop",
3
- "version": "0.6.5",
3
+ "version": "0.6.6",
4
4
  "private": false,
5
- "description": "统一管理图片工坊与视频工坊:项目风格、图片生成编辑、剧本镜头、视频生成与成片精修。",
5
+ "description": "图片、视频与 Spine 制作工具链,提供风格与素材管理、生成编辑、骨架动画编译和运行预览。",
6
6
  "type": "module",
7
7
  "exports": {
8
8
  "./video": "./lib/video.mjs",
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  name: art-workshop
3
- description: "处理图片与视频美术制作:图片讨论、风格、生成与编辑,视频剧本、镜头生成、成片与精修;按意图选择独立通道。"
3
+ description: "处理图片、视频和 Spine 制作:图片讨论、风格、生成与编辑,视频剧本、镜头生成、成片与精修;按意图选择独立通道。"
4
4
  ---
5
5
 
6
6
  # 美术工坊
7
7
 
8
8
  制作、调整或交付 2D Spine 角色时,查阅同包技能 `vant-spine-production`,按当前阶段选择原型、拆件、绑定、动作或导出指导。在 Vant 中,用户要求将已确认的正式作品入美术仓或接入游戏时,接续工作台技能 `vant-asset-intake`。
9
9
 
10
- 工具包提供 `image` 和 `video` 两个独立二级通道。图片沿用下述会话与项目管线;视频剧本、镜头、成片和精修先读取 [视频通道](references/video.md)。不要把视频任务改造成图片生成请求,也不要用图片配置替代视频模型和工作流设置。
10
+ 按制作对象选择 `image`、`video` 或 `spine`。图片沿用下述会话与项目管线;视频参阅[视频通道](references/video.md),骨骼动画参阅[Spine 制作指南](../vant-spine-production/SKILL.md)。
11
11
 
12
12
  判断本轮是讨论、生成还是编辑,再确定归属会话或项目任务。信息充分时直接使用对应结构化工具,不把普通讨论升级为生成。当前消息明确指定的对象和图片优先于历史推断。
13
13
 
@@ -25,7 +25,7 @@ Vanter 的实例交付 Spine 4.2 骨架 JSON、原始部件 PNG、PMA 图集、
25
25
 
26
26
  | 当前工作 | 入口与产物 |
27
27
  | --- | --- |
28
- | 原型与补绘 | 使用当前工作环境的生图、编辑工具制作原型和补绘图。用 `spine parts` 指定母版像素矩形、轴心、前后顺序与遮挡关系。蒙版接受透明度或灰度图;同比例高清替换图配准到原矩形。检查 assembled.png,采用补绘前后对照 patched.png 与原图。 |
28
+ | 原型与补绘 | 使用当前工作环境的生图、编辑工具制作原型和补绘图。用 `spine parts` 指定母版像素矩形、轴心、前后顺序与遮挡关系。蒙版接受透明度或灰度图;同比例高清替换图按原矩形配准,图集保留替换图像素尺寸。检查 assembled.png,采用补绘前后对照 patched.png 与原图。 |
29
29
  | 骨架与动画 | `spine build` 读取 parts.json,按轴心建立初始绑定。用 bones 按名增改骨骼,meshes 指定目标插槽、UV、三角索引、各点的骨名/骨局部坐标/权重。animations 使用 Spine 4.2 时间线。后续可传已编辑的 rig 骨架 JSON,保留其余皮肤、约束和动作。 |
30
30
  | 制作验收 | 美术工坊 → Spine 接入导出骨架。桌面对话可用 `vant_spine_preview` 打开同一资产。需要留存指定姿势或分享时,用 `spine capture` 选择动作、秒数或均匀帧数,输出逐帧 PNG、对照图及可选 GIF;需要本机 Chrome、Edge 或 Chromium。 |
31
31
  | 交付 | 核对导出的骨架、图集 PNG 与 atlas、animations.json 和 report.json。report 给出运行文件字节数、未压缩 RGBA 占用、骨骼、顶点和影响数。目标引擎的真实帧耗时需在该引擎测量。 |