@kevlns/art-workshop 0.6.5 → 0.6.8

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 和对照图。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
 
@@ -3316,7 +3316,7 @@ v-cli art spine build --input <file>
3316
3316
 
3317
3317
  ### spine capture
3318
3318
 
3319
- 使用 WebGL 取帧、生成对照图和可选 GIF
3319
+ 使用 WebGL 捕获指定姿势的 PNG 和对照图
3320
3320
 
3321
3321
  ```sh
3322
3322
  v-cli art spine capture --input <file>
@@ -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
 
@@ -1,6 +1,5 @@
1
1
  import { buildSources, resolveApiKey } from "bailian-cli-core";
2
2
  import { readFile } from "node:fs/promises";
3
- import sharp from "sharp";
4
3
  import { compileRemoteRequest } from "../generation-policy.mjs";
5
4
  import { resolveModel } from "../model-registry.mjs";
6
5
  import { requestJson, RemoteError } from "../transport/http.mjs";
@@ -102,6 +101,7 @@ async function inputImage(path, policy) {
102
101
  const buffer = await readFile(path);
103
102
  if (buffer.length > policy.maxBytes)
104
103
  throw new Error("输入图片超过模型文件大小限制");
104
+ const { default: sharp } = await import("sharp");
105
105
  const info = await sharp(buffer, {
106
106
  limitInputPixels: 64 * 1024 * 1024,
107
107
  }).metadata();
@@ -1,5 +1,4 @@
1
1
  import {readFile,stat} from 'node:fs/promises';
2
- import sharp from 'sharp';
3
2
  import {RemoteError,requestJson} from '../transport/http.mjs';
4
3
 
5
4
  function fields(request) {
@@ -23,6 +22,7 @@ export const openaiImagesAdapter = {
23
22
  const headers={Authorization:'Bearer '+key};
24
23
  let body=fields(request);
25
24
  if(request.images.length) {
25
+ const {default:sharp} = await import('sharp');
26
26
  const form=new FormData();
27
27
  for(const [field,value] of Object.entries(body)) form.set(field,String(value));
28
28
  for(const [index,file] of request.images.entries()) {
package/lib/images.mjs CHANGED
@@ -1,7 +1,7 @@
1
- import sharp from 'sharp';
2
1
  export async function validateImage(buffer){
3
2
  if(!Buffer.isBuffer(buffer)||buffer.length>20*1024*1024)throw new Error('单张图片最大 20MB');
4
3
  try{
4
+ const {default:sharp} = await import('sharp');
5
5
  const pipeline=sharp(buffer,{limitInputPixels:64*1024*1024,failOn:'warning'}),metadata=await pipeline.metadata();
6
6
  if(!['png','jpeg','webp'].includes(metadata.format)||!metadata.width||!metadata.height||metadata.pages>1)throw new Error('只支持单帧 PNG/JPEG/WebP');
7
7
  await pipeline.resize(1,1).raw().toBuffer();
@@ -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();
@@ -3,7 +3,6 @@ import {dirname,join} from 'node:path';
3
3
  import {fileURLToPath} from 'node:url';
4
4
  import {readFile,writeFile} from 'node:fs/promises';
5
5
  import {TextureAtlas} from '@esotericsoftware/spine-webgl';
6
- import sharp from 'sharp';
7
6
  import {projectPath} from '../video/path.mjs';
8
7
  import {sheet} from './parts.mjs';
9
8
 
@@ -65,19 +64,14 @@ export async function captureFrames(root,recipe,out) {
65
64
  },{rig,atlas,textures,clip,width,height});
66
65
  const times=recipe.times ?? Array.from({length:frames},(_,i)=>duration*i/frames);
67
66
  if(!Array.isArray(times)||!times.length||times.length>120||width*height*times.length>32e6||times.some(t=>!Number.isFinite(t)||t<0||t>duration+1e-5)) throw Error('时间点必须位于动作时长内');
68
- const columns=Math.ceil(Math.sqrt(times.length)),layers=[],raw=[],files=[];
67
+ const columns=Math.ceil(Math.sqrt(times.length)),layers=[],files=[];
69
68
  for(const [i,time] of times.entries()) {
70
69
  const png=Buffer.from(await page.evaluate(t=>window.renderFrame(t),time),'base64');
71
70
  const name='frame-'+String(i+1).padStart(3,'0')+'.png';
72
71
  await writeFile(join(out,name),png);files.push(name);
73
72
  layers.push({input:png,left:i%columns*width,top:Math.floor(i/columns)*height});
74
- if(recipe.gif) raw.push(await sharp(png).ensureAlpha().raw().toBuffer());
75
73
  }
76
74
  await sheet(width*columns,height*Math.ceil(times.length/columns)).composite(layers).png().toFile(join(out,'comparison.png'));
77
- if(recipe.gif) {
78
- const delay=times.map((t,i)=>Math.max(20,Math.round(1000*((times[i+1]??duration)-t))));
79
- await sharp(Buffer.concat(raw),{raw:{width,height:height*raw.length,channels:4,pageHeight:height}}).gif({delay,loop:0}).toFile(join(out,'preview.gif'));
80
- }
81
- return {clip,duration,width,height,times,files,comparison:'comparison.png',...(recipe.gif?{gif:'preview.gif'}:{})};
75
+ return {clip,duration,width,height,times,files,comparison:'comparison.png'};
82
76
  } finally {await browser.close();}
83
77
  }
@@ -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,14 +5,15 @@ 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']},
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
- 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']}
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
+ 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:'parts 必填,指向含部件图像定位的 parts.json,编辑已有 rig 也需要它来重建图集。bones 按名增改骨骼;meshes 为网格配方列表,points 每项含 [骨名,骨局部x,y,正权重],权重和为1。rig 可指定可编辑的 Spine 4.2 JSON,保留其骨骼、皮肤、约束、网格、权重及时间线;animations 按动作名合并。未传 rig 时使用 parts 中的轴心建立绑定。',outputs:['骨架 JSON','atlas','PNG 图集','images/','animations.json','report.json']},
10
+ capture:{input:{source:'work/rig-01/actor.json',out:'work/frames-01',clip:'wave_001',width:384,height:384,frames:8},optional:'times 可直接指定秒数。无头 Chromium 使用 Spine WebGL 4.2 捕获实际像素。',outputs:['逐帧 PNG','comparison.png','capture.json']}
11
11
  };
12
12
  export async function runSpine(root,action,input) {
13
13
  if(action==='describe')return spineContract;
14
14
  if(!Object.hasOwn(spineContract,action))throw Error('未知 Spine 操作:'+action);
15
15
  if(typeof input?.out!=='string'||!input.out.trim()) throw Error('指定新的项目内输出目录 out');
16
+ if(action==='build' && !input.parts) throw Error('Spine build 缺少 parts,请指定拆件清单 parts.json');
16
17
  const target=await projectPath(root,input.out);
17
18
  if(await lstat(target).then(()=>true,e=>{if(e.code!=='ENOENT')throw e;return false;}))throw Error('输出目录已存在,请为本次结果选择新目录');
18
19
  await mkdir(dirname(target),{recursive:true});
@@ -1,6 +1,5 @@
1
1
  import {assertLocalEndpoint} from './local-runtime.mjs';
2
2
  import { atomicJson, atomicWrite, replaceFile } from "./atomic.mjs";
3
- import sharp from "sharp";
4
3
  import { createWriteStream, fstatSync } from "node:fs";
5
4
  import { Readable, Transform } from "node:stream";
6
5
  import { pipeline } from "node:stream/promises";
@@ -359,6 +358,7 @@ class VideoService {
359
358
  throw new Error("图片限 20MB");
360
359
  const mime = bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) ? "image/png" : bytes[0] === 255 && bytes[1] === 216 ? "image/jpeg" : bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP" ? "image/webp" : "";
361
360
  if (!mime) throw new Error("仅支持 PNG、JPEG、WebP 图片");
361
+ const { default: sharp } = await import("sharp");
362
362
  const decoder = sharp(bytes, {
363
363
  limitInputPixels: 32 * 1024 * 1024,
364
364
  failOn: "error"
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.8",
4
4
  "private": false,
5
- "description": "统一管理图片工坊与视频工坊:项目风格、图片生成编辑、剧本镜头、视频生成与成片精修。",
5
+ "description": "图片、视频与 Spine 制作工具链,提供风格与素材管理、生成编辑、骨架动画编译和运行预览。",
6
6
  "type": "module",
7
7
  "exports": {
8
8
  "./video": "./lib/video.mjs",
@@ -1,21 +1,23 @@
1
1
  ---
2
2
  name: art-workshop
3
- description: "处理图片与视频美术制作:图片讨论、风格、生成与编辑,视频剧本、镜头生成、成片与精修;按意图选择独立通道。"
3
+ description: "处理图片、视频和 Spine 制作:图片讨论、风格、生成与编辑,视频剧本、镜头生成、成片与精修;按意图选择独立通道。"
4
4
  ---
5
5
 
6
6
  # 美术工坊
7
7
 
8
+ 在 Vant 会话的 shell 中,示例里的 `v-cli` 代表插件入口:PowerShell 写作 `node "$env:DSH_VANT_CLI"`,sh 写作 `node "$DSH_VANT_CLI"`。
9
+
8
10
  制作、调整或交付 2D Spine 角色时,查阅同包技能 `vant-spine-production`,按当前阶段选择原型、拆件、绑定、动作或导出指导。在 Vant 中,用户要求将已确认的正式作品入美术仓或接入游戏时,接续工作台技能 `vant-asset-intake`。
9
11
 
10
- 工具包提供 `image` 和 `video` 两个独立二级通道。图片沿用下述会话与项目管线;视频剧本、镜头、成片和精修先读取 [视频通道](references/video.md)。不要把视频任务改造成图片生成请求,也不要用图片配置替代视频模型和工作流设置。
12
+ 按制作对象选择 `image`、`video` 或 `spine`。图片沿用下述会话与项目管线;视频参阅[视频通道](references/video.md),骨骼动画参阅[Spine 制作指南](../vant-spine-production/SKILL.md)。
11
13
 
12
14
  判断本轮是讨论、生成还是编辑,再确定归属会话或项目任务。信息充分时直接使用对应结构化工具,不把普通讨论升级为生成。当前消息明确指定的对象和图片优先于历史推断。
13
15
 
14
16
  以用户意图为主线,让表达更清楚、专业、便于执行,允许贴合原意的适度补充。留意补充是否改变了用户的方向、程度或选择空间,尤其不要将倾向升级成硬性禁令。看图分析可以提炼可见特征;影响不大的合理细化直接处理,实质性的新设计取舍再提出建议或询问。
15
17
 
16
- - 整理或回填美术表述前读取 [表达规范](references/expression.md),本会话已掌握时直接沿用。需要 Getty 核实时,先从中文意图提炼英文专业词,在一个批次中通过 art_getty 查询,再按原始上下文校验候选;失败或无匹配保留原表达,不阻塞其他内容,不重试或另找调用路径。
18
+ - 整理或回填美术表述前读取 [表达规范](references/expression.md),本会话已掌握时直接沿用。需要 Getty 核实时,先从中文意图提炼英文专业词,在一个批次中通过 vant_art_getty 查询,再按原始上下文校验候选;失败或无匹配保留原表达,不阻塞其他内容,不重试或另找调用路径。
17
19
  - 参考图风格讨论、分析并填写风格草稿,读取 [风格讨论与回填](references/style-discussion.md)。
18
- - 会话探索、新图及修改上一轮产物,读取 [会话管线](references/conversation.md),使用 art_conversation。
19
- - 已有项目任务、可编辑风格规则、打样与样张定版和正式资产交付,读取 [项目管线](references/project.md),使用 art_operation。
20
+ - 会话探索、新图及修改上一轮产物,读取 [会话管线](references/conversation.md),使用 vant_art_conversation。
21
+ - 已有项目任务、可编辑风格规则、打样与样张定版和正式资产交付,读取 [项目管线](references/project.md),使用 vant_art。
20
22
 
21
23
  同一请求只提交一次;重复调用复用请求身份。未知状态仅查询原运行,禁止更换身份重投。状态查询按工具返回的 wait/状态约束进行;到达等待上限就结束本轮并保留可恢复身份,不用修改需求或新建任务绕过失败。只有用户明确修改目标或请求新一轮生成时才创建新请求。
@@ -1,6 +1,6 @@
1
1
  # 会话美术管线
2
2
 
3
- 使用 art_conversation describe 获取当前输入契约。只讨论时自然答复,不执行生成。
3
+ 使用 vant_art_conversation describe 获取当前输入契约。只讨论时自然答复,不执行生成。
4
4
 
5
5
  一次 generate 或 edit 请求绑定 requestId;相同 requestId 重复调用只返回原运行,不重发。已有产物通过 attachmentId 指定;编辑必须明确底图,引用可以分别指定主体、配色、构图、风格等用途,不把全部会话图片自动作为参考。读取像素后再解释,不能看图时使用已配置的视觉分析能力或说明限制。
6
6
 
@@ -17,11 +17,11 @@
17
17
 
18
18
  1. 理解意图与主题归类:先明确对象、属性、调整方向、程度、条件及保留要求。区分跨主体复用的绘制语言与当前任务的主体、结构、材质、光照、构图和交付约束,按相关主题组织,不强制填满分类,不为分类补造需求。
19
19
  2. 初步整理与语义去重:统一同一对象的称呼,合并对象、含义和适用条件均一致的重复要求;程度、条件或对象不同的内容分别保留。含义不确定时保留原表达和上下文,暂不强行合并或替换,避免先精简掉消歧依据。
20
- 3. 按需专业对齐:发现专业概念歧义或需要核实时,先从中文原意、作用对象及条件中提炼简短的英文专业检索词,再通过实际可用的 Getty 或项目表达库召回概念。不是逐字翻译整段描述,也不将英译当成已确认结论;有多个合理含义时在同一批次查询,不在结果不理想后反复换词。原始中文及约束保留在 context,候选返回后结合类别、概念说明和原始上下文判断,不只按首条或分数采用。Vant 使用 art_getty 结构化入口,不拼 Python、脚本或请求文件路径。缓存由查询工具管理,仅复用完整检索词及影响结果的全部参数完全一致的请求,不做语义近似缓存;不伪造概念 ID、结果或工具能力。无需引入 OpenRefine 运行依赖。
20
+ 3. 按需专业对齐:发现专业概念歧义或需要核实时,先从中文原意、作用对象及条件中提炼简短的英文专业检索词,再通过实际可用的 Getty 或项目表达库召回概念。不是逐字翻译整段描述,也不将英译当成已确认结论;有多个合理含义时在同一批次查询,不在结果不理想后反复换词。原始中文及约束保留在 context,候选返回后结合类别、概念说明和原始上下文判断,不只按首条或分数采用。Vant 使用 vant_art_getty 结构化入口,不拼 Python、脚本或请求文件路径。缓存由查询工具管理,仅复用完整检索词及影响结果的全部参数完全一致的请求,不做语义近似缓存;不伪造概念 ID、结果或工具能力。无需引入 OpenRefine 运行依赖。
21
21
  4. 精炼表述与整体校验:采用明确且符合原意的概念后,删去空泛修饰与重复说明,形成独立完整的描述;保留对象、程度、条件、例外和 required/default/avoid 的原有强度,不设机械字数限制。核对前后术语及要求一致,未遗漏约束、增加未经支持的含义或混淆风格与任务职责。发现问题做局部修正,不自动回到起点反复检索或改写。
22
22
  5. 回填并结束:明确且校验通过的修改在用户当前编辑授权内自动回填,无需逐项确认;读取当前对象及 revision,保留未修改配置,按工具契约保存并核实返回结果。筛选后仍有多个合理解释时,按匹配程度排序,通过宿主现有决策入口展示候选含义、匹配依据、差异和拟回填内容,标明推荐项并允许保留原表达或自行修改;未决字段保留原值,其余明确修改继续处理。无匹配、查询能力不可用、服务失败或语义校验未通过时,保留受影响的原表达,简短说明局限并结束本次对齐,不强行绑定概念或自行重试循环。配置保存失败须如实报告,不声称已回填;技术契约校验仍按原规则执行。
23
23
 
24
- Getty 调用前按需读取 `references/getty.md`。Vant 的 art_getty 由宿主定位受管包中的 `scripts/getty.py` 和共享 Python,通过标准输入输出交换 JSON;模型不用寻找或创建脚本。其他宿主只使用其明确提供的执行入口与解释器,缺少能力时说明失败,不猜路径、搜索系统 Python 或改用临时脚本。适配器负责 AAT 查询、详情、精确缓存和错误分类,模型负责词语提炼和语义判断。上游 serviceScore 只是检索排序分数,serviceMatch 不等于语义通过;失败即保留原文并结束当前检索,不用网页查询冒充已完成 Getty 核实。
24
+ Getty 调用前按需读取 `references/getty.md`。Vant 的 vant_art_getty 由宿主定位受管包中的 `scripts/getty.py` 和共享 Python,通过标准输入输出交换 JSON;模型不用寻找或创建脚本。其他宿主只使用其明确提供的执行入口与解释器,缺少能力时说明失败,不猜路径、搜索系统 Python 或改用临时脚本。适配器负责 AAT 查询、详情、精确缓存和错误分类,模型负责词语提炼和语义判断。上游 serviceScore 只是检索排序分数,serviceMatch 不等于语义通过;失败即保留原文并结束当前检索,不用网页查询冒充已完成 Getty 核实。
25
25
 
26
26
 
27
27
  每轮对齐只做一次有界整理与查询批次;查询候选可含原词和有依据的候选译名,使用不同 query ID 保留来源。一次局部修正后仍有歧义就交决策卡或保留原文并结束,不为提高检索分数反复换词。用户选择候选后只处理该未决项,不重新启动整套流程。
@@ -4,13 +4,13 @@
4
4
 
5
5
  1. 从原始中文描述及作用对象中提炼简短英文专业检索词,优先术语而非整段直译。例如“晕涂法”可检索 sfumato;“版画感、双色、可见刻刀痕”可在同一批次检索 woodcut、linocut 等有依据的候选含义,不直接用 print feeling。术语不确定时保留为候选,不先确定画法。
6
6
  2. 原文及约束保留在每项 context.original、target 等上下文中;英文词只用于召回,不替换用户原文。一次准备好相关候选,最多 10 项,不向用户逐项确认英译。
7
- 3. Vant 调用 art_getty,参数为下文的查询 JSON。宿主从受管工具包定位脚本,使用共享 Python,通过 stdin 传入请求。模型直接使用结构化入口。
7
+ 3. Vant 调用 vant_art_getty,参数为下文的查询 JSON。宿主从受管工具包定位脚本,使用共享 Python,通过 stdin 传入请求。模型直接使用结构化入口。
8
8
  4. 用返回的类别、说明、别名与原始上下文校验候选。英文词也可能召回无关概念;中文候选、第一名、serviceScore 或 serviceMatch 均不能代替语义判断。全部不合适时保留原表达,不为了得到命中继续扩词查询。
9
9
  5. 本次核实完成或失败后继续主任务,不重试、更换路径或新增确认关卡。多候选本身不要求用户确认;真正影响主任务的设计取舍沿用已有交互,不另加 Getty 审批。
10
10
 
11
11
  ## Vant 执行结果
12
12
 
13
- art_getty 的主状态只有 succeeded 或 failed,stop=true 表示本轮查询已结束。同一用户轮次只有一个查询批次,重复调用或改变检索词会复用原结果,不再次执行。新的用户需求可以开始新一轮查询。
13
+ vant_art_getty 的主状态只有 succeeded 或 failed,stop=true 表示本轮查询已结束。同一用户轮次只有一个查询批次,重复调用或改变检索词会复用原结果,不再次执行。新的用户需求可以开始新一轮查询。
14
14
 
15
15
  - succeeded:适配器完整成功。data.status 为 candidates 或 no_match;零匹配是有效查询结果。
16
16
  - failed:读取 error.code、stage、message。资源或解释器问题是明确的前置失败;执行、网络、响应或详情错误也属于失败。runnerAttempted 等执行信息区分是否已尝试适配器,不把前置失败说成已经访问 Getty。
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: vant-spine-production
3
- description: "制作或调整 2D Spine 角色与动画时按需查阅。适用于从需求设计原型、高清拆件补绘、绑骨蒙皮、对照修形、动作与转场、GIF 验收,以及 Unity 或 Web 运行资源的质量与开销调优。"
3
+ description: "制作或调整 2D Spine 角色与动画时按需查阅。适用于从需求设计原型、高清拆件补绘、绑骨蒙皮、对照修形、动作与转场、运行时预览,以及 Unity 或 Web 运行资源的质量与开销调优。"
4
4
  ---
5
5
 
6
6
  # 2D Spine 制作指南
@@ -14,10 +14,10 @@ description: "制作或调整 2D Spine 角色与动画时按需查阅。适用
14
14
  | 只有一句角色设想,或要把已定稿的角色拆成可动部件 | [原型与拆件](references/art-parts.md#原型设计)、[拆分粒度](references/art-parts.md#拆分粒度) |
15
15
  | 放大后细节糊、转腕露洞、换表情时整张脸变了 | [高清重绘与补绘](references/art-parts.md#高清重绘与补绘) |
16
16
  | 原画很像,进引擎后脸宽了、手袖有缝或姿势不对 | [绑定与蒙皮](references/rig-motion.md#绑定与蒙皮)、[对照修形](references/rig-motion.md#对照修形) |
17
- | 想做一个动作、改善循环或检查两段动作如何衔接 | [动作与转场](references/rig-motion.md#动作与转场)、[GIF 预览](references/rig-motion.md#gif-预览) |
17
+ | 想做一个动作、改善循环或检查两段动作如何衔接 | [动作与转场](references/rig-motion.md#动作与转场)、[运行时预览](references/rig-motion.md#运行时预览) |
18
18
  | 要交给程序、接入 Vanter,或运行后模糊、掉帧、包太大 | [导出、运行验收与成本取舍](references/delivery.md) |
19
- | 需要选择制作工具或读取输入契约 | [工具入口](references/delivery.md#工具入口) |
19
+ | 需要选择制作工具或读取输入契约 | [工具入口](references/delivery.md#工具入口)、[图像处理备选](references/art-parts.md#图像处理备选) |
20
20
 
21
- **制作入口。** 用 `v-cli art spine describe` 查询配方。原画定位与蒙版回贴用 `parts`;骨架、权重、时间线和运行图集用 `build`;指定时刻实绘、对照图和分享 GIF 用 `capture`。这些命令可在独立工作目录执行。
21
+ **制作入口。** 在 Vant 中从会话提供的 `DSH_VANT_CLI` 运行 `art spine`。配方字段见 `art spine describe`。原画定位与蒙版回贴用 `parts`;骨架、权重、时间线和运行图集用 `build`;留存指定时刻的 PNG 和对照图 用 `capture`。这些命令可在独立工作目录执行。
22
22
 
23
- **在 Vant 中预览。** 桌面提供 `vant_spine_preview` 时,用项目骨架相对路径或已登记资产 ID 打开浮窗,可指定初始动作。需要逐帧、查看绑定或对照上一版时,打开美术工坊标题栏右侧的 Spine 页签。工作台以外使用目标版本的 Spine 播放器。需要分享动图时再导出 GIF。在 Vant 中确认某个项目导出版本入美术仓时,接续工作台的 `vant-asset-intake` 指南。
23
+ **在 Vant 中预览。** 桌面提供 `vant_spine_preview` 时,用项目骨架相对路径或已登记资产 ID 打开浮窗,可指定初始动作。需要逐帧、查看绑定或对照上一版时,打开美术工坊标题栏右侧的 Spine 页签。工作台以外使用目标版本的 Spine 播放器。在 Vant 中确认某个项目导出版本入美术仓时,接续工作台的 `vant-asset-intake` 指南。
@@ -19,3 +19,9 @@
19
19
  补绘看**动作将显露的面积**。移动原前景模拟抬手或侧摆,在独立底层补到最远暴露处,并给接缝留重叠。取回所需区域,与母版核对改动范围和透明边。若当前编辑工具无法精确限定像素,在图像编辑器以蒙版合回结果,检查蒙版外像素。大幅转面需要绘制新视角,拉伸正面纹理很容易失真。
20
20
 
21
21
  **Vanter 的处理。** 设计板有多个视图,造型以左上大正面为准。闭眼稿只取双眼,无五官底脸补全替换区域。手掌与圆袖按实际遮挡分别拆开,叉腰时另外补出被原手臂遮住的头发和衣身。这样加表情和手势可以沿用同一张脸和主体。
22
+
23
+ ## 图像处理备选
24
+
25
+ 当标准配方不能表达所需的局部裁切、蒙版运算、透明图层合成或像素差异对照时,可选用 Node.js + sharp,也可直接用当前工程的图像工具或编辑器。按所需操作和本机可用性选择,包括 macOS;无需为了遵循指南另装 sharp。若选 sharp,先在实际执行脚本的 Node 环境中验证能加载并处理一张小图,不依赖其他应用的私有安装路径。
26
+
27
+ 在副本上处理,保留原画坐标、轴心、图层顺序、像素尺寸和透明通道。将结果按原坐标叠回基准图,检查蒙版外像素及半透明边缘,再交给绑定与运行时预览。静态合成可用于定位差异,动作和蒙皮仍以实际骨架播放结果为准。
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## 目标端与交付物
4
4
 
5
- 核对项目实际使用的 Spine Runtime 主次版本、加载格式、材质和透明度约定,再选对应导出设置。制作源保留分层母版、定位信息、可编辑骨架及附件原图;运行目录仅放加载器消费的骨架、atlas、图集和项目要求的索引或集成资源。GIF、过程图和重复的原尺寸部件留在源资产或预览目录。
5
+ 核对项目实际使用的 Spine Runtime 主次版本、加载格式、材质和透明度约定,再选对应导出设置。制作源保留分层母版、定位信息、可编辑骨架及附件原图;运行目录仅放加载器消费的骨架、atlas、图集和项目要求的索引或集成资源。过程图和重复的原尺寸部件留在源资产或预览目录。
6
6
 
7
7
  Vanter 的实例交付 Spine 4.2 骨架 JSON、原始部件 PNG、PMA 图集、动作索引及 Unity 包。编辑时在匹配版本的 Spine Editor 导入 JSON 并关联原图,可再保存为原生 `.spine` 工程。交付说明要准确写出实际文件格式。
8
8
 
@@ -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
- | 制作验收 | 美术工坊 → Spine 接入导出骨架。桌面对话可用 `vant_spine_preview` 打开同一资产。需要留存指定姿势或分享时,用 `spine capture` 选择动作、秒数或均匀帧数,输出逐帧 PNG、对照图及可选 GIF;需要本机 Chrome、Edge 或 Chromium。 |
30
+ | 制作验收 | 美术工坊 → Spine 接入导出骨架。桌面对话可用 `vant_spine_preview` 打开同一资产。需要留存指定姿势或分享时,用 `spine capture` 选择动作、秒数或均匀帧数,输出逐帧 PNG 和对照图;需要本机 Chrome、Edge 或 Chromium。 |
31
31
  | 交付 | 核对导出的骨架、图集 PNG 与 atlas、animations.json 和 report.json。report 给出运行文件字节数、未压缩 RGBA 占用、骨骼、顶点和影响数。目标引擎的真实帧耗时需在该引擎测量。 |
@@ -26,8 +26,8 @@ Vanter 将设计板大正面与 Unity 首帧放在同一窗口对照。修脸时
26
26
 
27
27
  导出后运行 `node <技能目录>/scripts/check-variants.mjs <骨架.json> <animations.json>`。二进制交付使用同一次导出的 JSON 副本核对名称,再用目标播放器加载最终 SKEL 核对动作列表。接手已有资产时保留已公布的调用名;需要规范化改名时,同步修改源工程、索引、默认动作、转场及调用方,再重导验收。
28
28
 
29
- ## GIF 预览
29
+ ## 运行时预览
30
30
 
31
- 从目标运行时采帧。锁定相机、根位置与背景,取整段动作边界的并集并留边,避免逐帧自动裁切制造假抖动。记录播放速度、采样帧率和循环方式。按真实时长编码 GIF,循环段末尾避免重复首帧,一次性动作保留该看的停顿。需要检查转场时导出连播。
31
+ 在 Vant 中用 Spine 浮窗播放正在编辑的骨架,切换动作看起止姿势与循环接缝;复杂对照进 Spine 工坊。按最终显示尺寸看一次,固定根位置、缩放与背景,避免自动裁切造成假抖动。只有涉及目标引擎特有的材质或混合行为时,再到对应引擎复核。
32
32
 
33
- 至少按最终显示尺寸看一次,重点区域另看等比静帧。GIF 调色板和透明度会损失渐变、辉光和半透明边缘,出现闪色或锯齿时回看原始 PNG 帧和运行时。Vanter 的待机预览采用 Unity 输出的 144 帧,母版旁另存首帧对照图;预览 GIF 单独交付。
33
+ 需要留存问题帧时导出 PNG。采帧用相同画布、真实播放时长,循环末尾避免重复首帧。渐变或透明边的质量以运行时画面为准。
package/v-cli.plugin.json CHANGED
@@ -7014,7 +7014,7 @@
7014
7014
  "capture"
7015
7015
  ],
7016
7016
  "usage": "art-workshop spine capture --input <file>",
7017
- "description": "使用 WebGL 取帧、生成对照图和可选 GIF",
7017
+ "description": "使用 WebGL 捕获指定姿势的 PNG 和对照图",
7018
7018
  "arguments": [],
7019
7019
  "options": [
7020
7020
  {