@kevlns/art-workshop 0.3.6 → 0.3.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/AGENTS.md CHANGED
@@ -1,36 +1,52 @@
1
- # art Agent 调用规范
1
+ # Vant 美术工坊 Agent 规范
2
+
3
+ ## 定位
4
+
5
+ 管理项目风格、参考图、图片生成、编辑和定版。支持本地 ComfyUI 与远程图片模型。
6
+
7
+ ## 调用流程
8
+
9
+ ```sh
10
+ art-workshop config show
11
+ art-workshop config validate
12
+ art-workshop agent index
13
+ ```
14
+
15
+ 首次调用前读取本规范,使用命令帮助或插件清单核对参数和执行范围。
16
+
17
+ ## 调用规范
2
18
 
3
19
  用户既有授权与偏好持续有效;查询和预演不授权生成或采用。规范与实时参数通过 v-cli agent docs art 和 v-cli agent describe art --json 获取。
4
20
 
5
- ## 对象与参考
21
+ ### 对象与参考
6
22
 
7
- 工程必须使用 schemaVersion 2。project upgrade 是显式一次性升级,备份和原子替换;混合旧参考必须明确映射,日常读写无旧格式回退。
23
+ 工程对象使用 schemaVersion 2;读写前核实工程配置和当前 revision。
8
24
  风格和任务都有稳定 id 与 revision。UI、聊天和 CLI 共用对象;写入、派生与清理提交预期 revision,冲突重新读取。正式风格只读,改动创建派生风格;派生不继承报告、核心、批次、授权与对话。
9
25
  风格静态参考只有 style、palette、rendering,只分析媒介、描绘、明暗、描边、笔触和色彩关系。具体造型、比例、结构、部件、身份色、材质与光源属于任务。任务动态参考只有 subject、composition、pose、identity-color、surface、scene-light、text;编辑底图另列。导入复制原图,不修改用户文件。未适配直接参考时拒绝,不隐式上传风格图片。
10
26
 
11
- ## 风格生命周期
27
+ ### 风格生命周期
12
28
 
13
29
  style create/read/update/derive/discard 管理草稿。style analyze --dry 只读编译,不联网、启动服务或创建参考目录。实际 analyze 创建 taskId 与独立参考证据;task status/wait/cancel 控制执行,recover 查原登记,resume 仅恢复远程查询与取回。
14
30
  报告绑定源配置、参考与模型。更新配置保留报告并标记需复核,旧证据不变。报告 recommendation.rules 是精炼独立成稿,规则含主题、强度和适用条件,不包含迭代描述。issues 仅列需用户取舍的矛盾,notes 保留不阻塞采用的证据局限。style resolve --input {issueId,optionId,note} 记录明确选择并修订有效方案,不重新分析;以 style read 的 review.ready 判断采用条件。复核沿用证据与决定,新证据才重新打开问题。style adopt 校验来源匹配和所有问题已决定,用户采用后冻结。采用中断通过 style recover 完成已授权事务,不能重新冻结另一份核心。
15
31
  退出风格配置先继续编辑、保存草稿或放弃;分析停止未确认时不能清理。
16
32
 
17
- ## 计划与执行
33
+ ### 计划与执行
18
34
 
19
35
  先读取实际 job,再 generate/edit plan 和 run --plan --dry,展示有效核心、设计尺寸、预留缩放、请求与实际像素、模型后端、候选数量和编辑底图。后端尺寸由工具统一解析,超限或未对齐选最近合法尺寸,保留设计基准并明确实际值;不承诺显存或自动缩放导出。
20
- 授权覆盖方案后使用 run --background;前台同样创建执行身份。配置、核心、规格、参考、底图和后端变化拒绝旧方案,重新编译。重启查 taskId,不重复提交。不自动换模型或重跑成功项。
36
+ 授权覆盖方案后使用 run --background;前台同样创建执行身份。配置、核心、规格、参考、底图和后端变化拒绝失效方案,重新编译。重启查 taskId,不重复提交。不自动换模型或重跑成功项。
21
37
  每个任务只能有一个未停止确认的执行;编辑、派生、删除与运行共用状态检查。切页面不取消。
22
38
 
23
- ## 取消、异常和关闭
39
+ ### 取消、异常和关闭
24
40
 
25
41
  任务状态与停止证据分开。queued/running/cancelling 仍占用资源;unknown 或 stopConfirmed=false 保留资源。failed/cancelled 也不能单凭状态释放资源;dispatching/accepted 远程回执尚未结清时继续占用。工作进程丢失标记 unknown,不推测停止。
26
42
  task cancel 只取消指定运行,保留服务。生成任务远程取消只停止本地客户端,上游停止未知如实报告,不允许清理。只读分析有 finishedAt、已知终态且工作进程已退出,无生成计划与回执时释放本地占用;云端计算与计费停止未知独立保留,不自动重发。没有完成证据的进程丢失仍保持 unknown。shutdown 阻止提交、停止关联任务、核验共享队列和进程身份后关闭本地服务,不清空共享队列;有其他任务或停止未确认时保留服务。不得广泛杀所有 Python。
27
43
 
28
- ## 生成与定版
44
+ ### 生成与定版
29
45
 
30
46
  只有生成与定版两个产品阶段。check 验证计划、执行身份、文件哈希和完成事实;不要求人工 content/style/asset 评分。candidate finalize 按资产选定候选,重复操作幂等;替换已有定版需要明确 replace,保留历史。
31
47
  candidate delete 先确认影响,拒绝运行中或被计划/底图引用的候选;先记删除事实,清理所属文件,并取消关联定版。定版不自动导入游戏或提交 Git。
32
48
 
33
- ## 验证和技能
49
+ ### 验证和技能
34
50
 
35
51
  本地先 config validate、doctor、plan/dry,再按授权真实生成与编辑。配置有效、服务可连接与真实出图是不同证据。远程核对实际认证和模型入口;凭证不得写入项目、计划、日志或命令行。
36
52
  随包 skills/art-workshop 是技能源;通过 agent init 或 skill:sync 同步,保留项目扩展。查询和预演不自动同步。源码/单测/mock 不能代替真实模型、图像、桌面与安装验证。
@@ -41,8 +57,22 @@ candidate delete 先确认影响,拒绝运行中或被计划/底图引用的
41
57
 
42
58
  远端上游身份持久化后才能轮询。`task resume TASK` 只恢复原身份查询与取回,不重发生成;无回执或仍处于 dispatching 的提交保持未知。界面与保存共用 modelEligibility,展示字段不进入执行契约。
43
59
 
44
- 风格报告和核心职责版本 schemaVersion=3;不再包含 shape、lighting、domains,不限定主体题材。旧核心保留,只能派生后重新分析采用;旧分类参考必须明确重新分类,不能猜测搬到任务或渲染。低刻画密度不删任务结构,干净笔触不禁止物体纹理,高光画法不统一物理材质。
60
+ 风格报告和核心使用 schemaVersion=3,只表达绘制语言,不限定主体题材。低刻画密度不删任务结构,干净笔触不禁止物体纹理,高光画法不统一物理材质。
45
61
 
46
62
  任务草稿允许内容尚未完成,但拒绝编译器不支持的字段。生成任务的字段正本为 lib/task-contract.mjs;effect 使用 id/kind/target/color/relation/count,不支持 description。先读当前对象,完整保留未修改字段,按当前 revision 保存;保存成功后仍需编译预案,不能声称已生成图片。任务编译错误依据执行回执修正,不猜测风格或尺寸问题。
47
63
 
48
64
  任务参考可通过 reference import --item-id <对象标识> 绑定单个出图对象;未绑定的参考为任务共用。生成与编辑只采纳共用参考和当前对象参考的观察。reference update 的 itemId 可改绑对象,null 表示任务共用。
65
+
66
+ `v-cli capability coverage --json` 核对结构化调用覆盖。参考导入的 `--item-id` 指定当前任务出图对象,省略表示任务共用;工具校验对象身份。
67
+
68
+ ## 结果验证
69
+
70
+ 核对原始错误、任务身份、停止状态及实际产物。只报告已经完成的验证,模拟测试与真实执行分别说明。
71
+
72
+ ## 参考资料
73
+
74
+ [使用说明](README.md) · [文档规范](docs/documentation.md) · v-cli.plugin.json
75
+
76
+ ## 许可与版权
77
+
78
+ MIT。Copyright © 2026 Vant。
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 kevlns
3
+ Copyright © 2026 Vant
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,21 +1,34 @@
1
- # 美术工坊
1
+ # Vant 美术工坊
2
2
 
3
- 面向游戏资产的风格分析、图片生成与编辑工具。风格和任务按工程隔离,计划可预演,执行可追踪,候选按资产定版。产品流程只有「生成 → 定版」;完整性检查不会引入人工评分阶段。
3
+ `@kevlns/art-workshop`
4
4
 
5
- 通过 `v-cli art` 使用,或直接运行 `art-workshop`。需要 Node.js >=20.9。安装不会创建工程、下载模型或生成图片;安装脚本会同步已有 Agent 技能目录中的随包技能。
5
+ ## 功能
6
+
7
+ 管理项目风格、参考图、图片生成、编辑和定版。支持本地 ComfyUI 与远程图片模型。
8
+
9
+ ## 环境要求
10
+
11
+ Node.js 20 及以上;本地生成还需工具检测通过的 Python、显卡驱动与 ComfyUI 环境。
12
+
13
+ ## 安装
14
+
15
+ ```sh
16
+ npm install -g @kevlns/art-workshop
17
+ ```
18
+
19
+ ## 快速开始
6
20
 
7
21
  ```sh
8
- npm install -g @kevlns/v-cli
9
- v-cli agent docs art
10
- v-cli agent describe art --json
11
- v-cli art config show
12
- v-cli art agent index
13
- v-cli art config validate
22
+ art-workshop config show
23
+ art-workshop config validate
24
+ art-workshop agent index
14
25
  ```
15
26
 
16
- ## 使用流程
27
+ ## 使用说明
17
28
 
18
- 1. 创建 schemaVersion 2 工程和风格草稿,导入对象私有参考;分析预演后按授权运行,审阅报告并采用为冻结核心。
29
+ ### 使用流程
30
+
31
+ 1. 创建 schemaVersion 2 工程和风格草稿,导入对象专属参考;分析预演后按授权运行,审阅报告并采用为冻结核心。
19
32
  2. 用 `job template` 获取任务模板,填写实际需求后创建任务。动态参考先 `job analyze`;编辑底图单独绑定。
20
33
  3. 编译 `generate plan` 或 `edit plan`,保存并用 `run --plan ... --dry` 核对模型、尺寸、候选数、输入和参数转换。
21
34
  4. 按任务授权执行,保存 taskId;前台和后台都登记运行。查询原身份,不因超时或重启重复提交。
@@ -23,7 +36,7 @@ v-cli art config validate
23
36
 
24
37
  正式风格只读,修改需派生。任务空闲后可按原身份更新配置,历史批次不覆写。状态优先级为待定版、执行中、已定版、草稿;运行状态与停止证据分别判断,不能只看终态释放占用。
25
38
 
26
- ## 后端与数据归属
39
+ ### 后端与数据归属
27
40
 
28
41
  本地为 ComfyUI 内置 Qwen Image 2.1 Q4、CPU 文本编码器方案,支持生成和显式底图编辑。自定义 API workflow 需要明确 bindings 与完整适配,不能把任意导入工作流视为可执行。
29
42
 
@@ -31,18 +44,20 @@ v-cli art config validate
31
44
 
32
45
  应用数据根默认 `~/.vant`,可由 `VANT_HOME` 覆盖。工具配置为 `~/.vant/tools/art-workshop/config.json`;Vant 将工程美术数据绑定至工程 `.vant/art`。共享模型环境默认 `~/.vant/art-env`,控制状态与日志归用户数据根;安装根保存环境标记 `vant.art.config.json`。
33
46
 
47
+ ## 开发与验证
48
+
49
+ ```sh
50
+ npm ci
51
+ npm run check
52
+ npm run test:package
53
+ ```
54
+
55
+ 命令返回、结构校验、模拟测试与外部平台实际运行分别核验。发布版本和依赖以随包 `package.json` 为准。
56
+
34
57
  ## 文档
35
58
 
36
- | 文档 | 内容 |
37
- | --- | --- |
38
- | [模式与流程](docs/modes.md) | 分析、生成、编辑及定版 |
39
- | [配置](docs/configuration.md) | 路径、后端、连接与凭据边界 |
40
- | [数据结构](docs/data-formats.md) | 工程、对象、计划、运行与回执 |
41
- | [命令参考](docs/commands.md) | 从插件清单生成的完整命令与选项 |
42
- | [本地部署](docs/deployment.md) | 已有环境复用、部署预案与进度 |
43
- | [任务控制与诊断](docs/troubleshooting.md) | 取消、恢复、重试和关闭 |
44
- | [远程图片适配](docs/remote-models.md) | 支持范围、参数限制和筛选 |
45
- | [模型架构](docs/model-architecture.md) | 登记、适配器和扩展规范 |
46
- | [核心冻结](docs/core-guidance.md) | 风格与需求的职责边界 |
47
-
48
- 开发校验:`npm run docs:generate`、`npm run check`、`npm run test:package`。模拟测试、配置有效和服务可连接都不能代替真实出图;文档更新不代表新包已发布或桌面安装已更新。
59
+ [Agent 调用规范](AGENTS.md) · [文档规范](docs/documentation.md) · [art 命令参考](docs/commands.md) · [配置与存储](docs/configuration.md) · [风格核心职责与问题决策](docs/core-guidance.md) · [art 工程与输入结构](docs/data-formats.md) · [本地环境检测与部署](docs/deployment.md) · [模型与执行架构](docs/model-architecture.md) · [模式与调用流程](docs/modes.md) · [远程图片适配与筛选](docs/remote-models.md) · [任务控制与诊断](docs/troubleshooting.md)
60
+
61
+ ## 许可与版权
62
+
63
+ 本工具采用 [MIT 许可](LICENSE)。Copyright © 2026 Vant。Vant 为工具集品牌;Figma、Unity、Steam、微信及其组件归各自权利人所有,第三方组件适用各自许可。
package/art-workshop.mjs CHANGED
@@ -27,7 +27,7 @@ const {workflowList}=await import('./lib/workflows.mjs');
27
27
  const {jobTemplate}=await import('./lib/templates.mjs');
28
28
  const {deploymentPlan,startDeployment,deploymentStatus,cancelDeployment,recoverDeployment}=await import('./lib/deployment.mjs');
29
29
  const flags=new Set(['dry','explore','background','start','replace','confirm','all-variants']);
30
- const allowed=new Set(['config','workspace','output-dir','refs-dir','cache-dir','directory','endpoint','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',...flags]);
30
+ const allowed=new Set(['config','workspace','output-dir','refs-dir','cache-dir','directory','endpoint','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',...flags]);
31
31
  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]);}
32
32
  const print=x=>console.log(JSON.stringify(x?.schema==='art-workshop/style'?styleView(settings.paths.workspace,x):x,null,2));
33
33
  if(pos[0]==='workflow'&&pos[1]==='list'){print(workflowList());process.exit(0);}