@kevlns/art-workshop 0.1.3 → 0.3.0

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.
Files changed (61) hide show
  1. package/AGENTS.md +33 -12
  2. package/README.md +33 -135
  3. package/art-workshop.mjs +95 -25
  4. package/docs/commands.md +915 -0
  5. package/docs/configuration.md +60 -0
  6. package/docs/core-guidance.md +80 -13
  7. package/docs/data-formats.md +29 -0
  8. package/docs/deployment.md +40 -0
  9. package/docs/model-architecture.md +52 -0
  10. package/docs/modes.md +39 -0
  11. package/docs/remote-models.md +42 -0
  12. package/docs/troubleshooting.md +46 -0
  13. package/lib/adapters/dashscope.mjs +234 -0
  14. package/lib/adapters/index.mjs +28 -0
  15. package/lib/agent.mjs +3 -2
  16. package/lib/analysis-worker.mjs +25 -0
  17. package/lib/analyze.mjs +8 -8
  18. package/lib/backends.mjs +365 -0
  19. package/lib/bl.mjs +3 -18
  20. package/lib/candidates.mjs +82 -0
  21. package/lib/comfyui.mjs +64 -0
  22. package/lib/contracts.d.ts +67 -0
  23. package/lib/deployment-worker.mjs +97 -0
  24. package/lib/deployment.mjs +72 -0
  25. package/lib/design.mjs +5 -5
  26. package/lib/diagnostics.mjs +83 -0
  27. package/lib/dimensions.mjs +22 -0
  28. package/lib/edit.mjs +6 -3
  29. package/lib/environments.mjs +67 -0
  30. package/lib/execution/remote.mjs +156 -0
  31. package/lib/executor.mjs +10 -24
  32. package/lib/generate.mjs +9 -5
  33. package/lib/generation-policy.mjs +198 -0
  34. package/lib/images.mjs +10 -0
  35. package/lib/lifecycle.mjs +40 -0
  36. package/lib/migration.mjs +154 -0
  37. package/lib/model-catalog.mjs +288 -0
  38. package/lib/model-registry.mjs +234 -0
  39. package/lib/plan.mjs +98 -28
  40. package/lib/project.mjs +13 -4
  41. package/lib/providers.mjs +30 -0
  42. package/lib/refs.mjs +12 -16
  43. package/lib/runtime.mjs +25 -0
  44. package/lib/service.mjs +137 -0
  45. package/lib/settings.mjs +5 -6
  46. package/lib/shared.mjs +12 -2
  47. package/lib/style-lifecycle.mjs +72 -0
  48. package/lib/task-references.mjs +35 -0
  49. package/lib/task-worker.mjs +233 -0
  50. package/lib/tasks.mjs +458 -0
  51. package/lib/templates.mjs +69 -0
  52. package/lib/transport/cli.mjs +69 -0
  53. package/lib/transport/http.mjs +82 -0
  54. package/lib/vision.mjs +46 -0
  55. package/lib/workflows.mjs +28 -0
  56. package/lib/workspace.mjs +190 -0
  57. package/package.json +14 -6
  58. package/skills/art-workshop/SKILL.md +27 -27
  59. package/v-cli.plugin.json +1484 -135
  60. package/workflows/vant-builtin-qwen-image-2.1-Q4-8GB.api.json +116 -0
  61. package/workflows/vant-builtin-qwen-image-2.1-Q4-8GB.json +648 -0
package/AGENTS.md CHANGED
@@ -1,19 +1,40 @@
1
- # 美术工坊 Agent 指导
1
+ # art Agent 调用规范
2
2
 
3
- 首次使用运行 v-cli agent docs art、v-cli agent describe art --json,再用 v-cli art config show 和 v-cli art agent index 确认外部路径、工程及核心。所有独立 art-workshop 命令都可通过 v-cli art 原样调用。详细流程、配置和输入结构用 v-cli art agent docs 查看,参考分类用 v-cli art refs guide 查看。
3
+ 用户既有授权与偏好持续有效;查询和预演不授权生成或采用。规范与实时参数通过 v-cli agent docs art 和 v-cli agent describe art --json 获取。
4
4
 
5
- ## 流程与规则
5
+ ## 对象与参考
6
6
 
7
- - 风格分析与冻结:style analyze 生成报告,style validate 校验,用户采用报告后 style freeze。核心语言精炼、用词准确、前后一致、模块职责清楚;可复用视觉语言归核心,主体与动作归任务,背景与构图归资产配置,模型与尺寸归执行。已有冻结核心不可覆写。
8
- - 文生图:generate show 读取任务,generate plan 编译计划,generate run --plan FILE --dry 预演,授权后去掉 --dry 生图。工程内核心选择为显式 --core、任务绑定、工程默认;冲突拒绝,不跨工程回退。默认纯白背景,其他背景必须明确声明。
9
- - 图编辑:edit show / plan / run,明确原图、修改范围及保留范围。预演后按任务授权执行;不自动换背景或套默认核心。原图变化后重新预演。
10
- - 计划与 dry 不调用远程模型,不产生图片;真实分析与生成会调用 bl 并产生费用。修改需求后重新编译,不手改冻结计划。
11
- - check 导出或汇总人工验收,分别检查 content/style/asset;三项全部通过且完整性有效才可 select。工具不自动评价图片。
7
+ 工程必须使用 schemaVersion 2。project upgrade 是显式一次性升级,备份和原子替换;混合旧参考必须明确映射,日常读写无旧格式回退。
8
+ 风格和任务都有稳定 id 与 revision。UI、聊天和 CLI 共用对象;写入、派生与清理提交预期 revision,冲突重新读取。正式风格只读,改动创建派生风格;派生不继承报告、核心、批次、授权与对话。
9
+ 风格静态参考只有 style、palette、shape-language、rendering,分析理解可复用视觉语言。任务动态参考只有 subject、composition、pose、identity-color、surface、scene-light、text;编辑底图另列。导入复制原图,不修改用户文件。未适配直接参考时拒绝,不隐式上传风格图片。
12
10
 
13
- ## 本地资源与配套
11
+ ## 风格生命周期
14
12
 
15
- 本地配置位于用户配置目录,可用 config path/show/init 发现;冻结核心在 workspace/projects/工程/cores。工程、参考、报告、计划、缓存、原图和产物都在安装目录之外,不纳入工具 Git 或 npm 包。相对资源按 workspace 解析,参考图按 refs 解析,RUN 按 output 解析。每次配置生效会补齐 refs 分类目录,包括 dry,不覆盖素材。
13
+ style create/read/update/derive/discard 管理草稿。style analyze --dry 只读编译,不联网、启动服务或创建参考目录。实际 analyze 创建 taskId 与独立参考证据;task status/wait/cancel 控制执行,recover 查原登记,resume 仅恢复远程查询与取回。
14
+ 报告绑定源配置、参考与模型。更新配置会清除当前报告,旧证据保留。style adopt 校验源版本、报告身份、冲突与未确定项,用户采用后冻结。采用中断通过 style recover 完成已授权事务,不能重新冻结另一份核心。
15
+ 退出风格配置先继续编辑、保存草稿或放弃;分析停止未确认时不能清理。
16
16
 
17
- 随包 skills/art-workshop 是使用规范源,agent init --directory DIR 同步到已有 Agent 技能目录,保留扩展文件;自动同步也可用 npm run skill:sync。v-cli 负责路由、清单与本指导发现,美术工坊负责实际任务、核心选择与模型请求。安装 v-cli 会安装此官方依赖。
17
+ ## 计划与执行
18
18
 
19
- UI 尺寸:文生图 profile.design 声明 resolution 与 outputScale,item.design 声明控件 width/height 与可选 outputScale。单体实际出图尺寸为设计尺寸乘倍率;不能同时指定任务 execution.size。换算越界报错,不自动改变比例;完整约束见 agent docs。
19
+ 先读取实际 job,再 generate/edit plan 和 run --plan --dry,展示有效核心、设计尺寸、预留缩放、请求与实际像素、模型后端、候选数量和编辑底图。后端尺寸由工具统一解析,超限或未对齐选最近合法尺寸,保留设计基准并明确实际值;不承诺显存或自动缩放导出。
20
+ 授权覆盖方案后使用 run --background;前台同样创建执行身份。配置、核心、规格、参考、底图和后端变化拒绝旧方案,重新编译。重启查 taskId,不重复提交。不自动换模型或重跑成功项。
21
+ 每个任务只能有一个未停止确认的执行;编辑、派生、删除与运行共用状态检查。切页面不取消。
22
+
23
+ ## 取消、异常和关闭
24
+
25
+ 任务状态与停止证据分开。queued/running/cancelling 仍占用资源;unknown 或 stopConfirmed=false 保留资源。failed/cancelled 也不能单凭状态释放资源;dispatching/accepted 远程回执尚未结清时继续占用。工作进程丢失标记 unknown,不推测停止。
26
+ task cancel 只取消指定运行,保留服务。远程取消只停止本地客户端,上游停止未知如实报告,不允许清理。shutdown 阻止提交、停止关联任务、核验共享队列和进程身份后关闭本地服务,不清空共享队列;有其他任务或停止未确认时保留服务。不得广泛杀所有 Python。
27
+
28
+ ## 生成与定版
29
+
30
+ 只有生成与定版两个产品阶段。check 验证计划、执行身份、文件哈希和完成事实;不要求人工 content/style/asset 评分。candidate finalize 按资产选定候选,重复操作幂等;替换已有定版需要明确 replace,保留历史。
31
+ candidate delete 先确认影响,拒绝运行中或被计划/底图引用的候选;先记删除事实,清理所属文件,并取消关联定版。定版不自动导入游戏或提交 Git。
32
+
33
+ ## 验证和技能
34
+
35
+ 本地先 config validate、doctor、plan/dry,再按授权真实生成与编辑。配置有效、服务可连接与真实出图是不同证据。远程核对实际认证和模型入口;凭证不得写入项目、计划、日志或命令行。
36
+ 随包 skills/art-workshop 是技能源;通过 agent init 或 skill:sync 同步,保留项目扩展。查询和预演不自动同步。源码/单测/mock 不能代替真实模型、图像、桌面与安装验证。
37
+
38
+ 模型、参数及支持状态只在 art 工具 model-catalog/model-registry 内维护,界面与 v-cli 不复制型号判断。远程图片由已注册协议适配器直接调用;视觉分析连接独立,未注入时使用百炼 CLI。Token Plan 是渠道,DashScope 是协议,不跨站点回退凭据。
39
+
40
+ 远端上游身份持久化后才能轮询。`task resume TASK` 只恢复原身份查询与取回,不重发生成;无回执或仍处于 dispatching 的提交保持未知。界面与保存共用 modelEligibility,展示字段不进入执行契约。
package/README.md CHANGED
@@ -1,150 +1,48 @@
1
1
  # 美术工坊
2
2
 
3
- 三个独立模块:风格分析与核心冻结、文生图、图编辑。默认模型 qwen-image-3.0-pro,尺寸 1024*1024,关闭 prompt 扩写。
3
+ 面向游戏资产的风格分析、图片生成与编辑工具。风格和任务按工程隔离,计划可预演,执行可追踪,候选按资产定版。产品流程只有「生成 → 定版」;完整性检查不会引入人工评分阶段。
4
4
 
5
- ## 随包 skill 与能力发现
5
+ 通过 `v-cli art` 使用,或直接运行 `art-workshop`。需要 Node.js >=20.9。安装不会创建工程、下载模型或生成图片;安装脚本会同步已有 Agent 技能目录中的随包技能。
6
6
 
7
- skills/art-workshop 是精简的使用指导,随 npm 包一起分发,支持隐式发现。安装或更新包时,以及正常分析、冻结、生成或编辑调用时,自动同步到当前目录及用户目录下已有的 Agent 技能目录(含 .codex/skills、.agents/skills、.claude/skills 等;也支持 CODEX_HOME/skills)。不存在的技能目录不创建。只读查询、plan 与 --dry 不自动同步。
8
-
9
- ```powershell
10
- node art-workshop.mjs agent index
11
- node art-workshop.mjs agent docs
12
- node art-workshop.mjs agent init --directory C:/MyProject --dry
13
- node art-workshop.mjs agent init --directory C:/MyProject
14
- npm run skill:sync
15
- ```
16
-
17
- index 输出工程、核心、任务及模块入口,docs 输出随包完整指导。init 只同步技能,不写 AGENTS.md。随包文件是权威来源,同名文件更新,其他扩展文件保留;同步结果列出 current/updated/would-update。runtime.json 记录实际工具入口,已发现的 skill 无须猜测安装位置。Agent 通常在下次加载技能列表或新会话时发现它。安装:`npm install -g @kevlns/art-workshop`;本地配置与工程冻结核心均位于工具目录之外,不随 npm 包发布。
18
-
19
- ## 本地配置与外部路径
20
-
21
- 本地配置默认位于 Windows 的 %APPDATA%/art-workshop/config.json、macOS 的 ~/Library/Application Support/art-workshop/config.json、Linux 的 $XDG_CONFIG_HOME/art-workshop/config.json(未设置时使用 ~/.config)。它在用户目录,不进入工具 Git 仓库或 npm 包。
22
-
23
- `config path` 查看位置,`config show` 查看生效配置,`config init` 创建默认文件,不覆盖已有文件。通过 `--config FILE` 或 ART_WORKSHOP_CONFIG 可指定其他外部配置文件。
24
-
25
- 配置结构:
26
-
27
- ```json
28
- {
29
- "paths": {
30
- "workspace": "C:/Users/你的用户名/Downloads/image.g",
31
- "output": "C:/Users/你的用户名/Downloads/image.g",
32
- "refs": "D:/ArtReferences",
33
- "cache": "C:/Users/你的用户名/Downloads/image.g/.cache"
34
- },
35
- "execution": {},
36
- "analysisModel": null,
37
- "defaultProject": null,
38
- "autoSyncSkills": true
39
- }
40
- ```
41
-
42
- paths 的四个目录均可独立修改;默认采用系统下载目录/image.g,Windows 会读取实际下载 Known Folder,Linux 尊重 XDG 下载目录。workspace 存放 projects;output 存放每次运行的独立文件夹与 manifest;refs 为默认参考图目录;cache 为分析缓存。所有运行资源路径必须在工具目录之外,包括编辑原图、报告与计划。
43
-
44
- execution 可配置 model、size、promptExtend、perValue、watermark。尺寸使用明确像素,如 1024*1024。生图参数优先级为内置默认 → 工程配置 → 本地 execution → 任务 execution;已有冻结计划保留预演时的实际参数,需重新 plan 才能采用新默认值。analysisModel 覆盖工程的分析模型;defaultProject 可省略常用 --project;autoSyncSkills 控制自动同步,手动 agent init 始终可用。
45
-
46
- 命令行 --workspace、--output-dir、--refs-dir、--cache-dir 临时覆盖对应路径。参考图的相对 path 以参考图目录解析,绝对 path 直接使用;参考目录优先级为 --refs-dir → 工程 refsDir → 本地配置。其他相对资源文件路径以 workspace 解析;check/select 的相对运行目录以 output 解析。
47
-
48
- 每次 CLI 配置生效时,自动检查并补齐 refs 下的 style、palette、subject、composition、material、text、pose 分类目录;选定工程有独立 refsDir 时也会检查该目录。包括只读查询和 --dry,只创建缺少的目录,不移动或覆盖素材;目录位置被文件占用时明确报错。配置解析本身无文件写入,CLI 应用配置时完成目录初始化。
49
-
50
- `refs guide` 解释各目录作用、推荐图片样式与可用分析 scope,并显示实际参考目录;可加 `--project P` 查看工程目录,或 `--refs-dir DIR` 临时指定。目录仅用于整理,不自动识别角色或绑定图片。分析仍在输入 refs 中显式声明 path、scope 和 note。构图、文字、姿态的具体要求属于单体计划,不自动冻结进核心。
51
-
52
- ```powershell
53
- node art-workshop.mjs config show
54
- node art-workshop.mjs refs guide --project cellgame
55
- node art-workshop.mjs style analyze --project cellgame --input projects/cellgame/briefs/style.json --refs-dir D:/ArtReferences --dry
56
- node art-workshop.mjs generate run --plan .cache/plans/white-cell.json --dry
7
+ ```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
57
14
  ```
58
15
 
59
- ## 工程结构
60
-
61
- 顶层指导规则:rules/core-guidance.json。工程配置位于 projects/<project>/project.json;briefs 保存分析输入,reports 保存报告,cores 保存冻结核心,profiles 保存资产规格,jobs 保存真实需求。这些目录位于外部工作目录,不属于工具安装目录。输出默认位于系统下载目录的 image.g,参考图与缓存也使用外部路径。
16
+ ## 使用流程
62
17
 
63
- 所有模块明确指定工程;核心不跨工程回退。新工程须创建自己的 project.json,并通过该工程的报告冻结核心,不能复制冻结文件并修改身份。工程 cores 可列多份核心,defaultCore 为明确默认或 null。
18
+ 1. 创建 schemaVersion 2 工程和风格草稿,导入对象私有参考;分析预演后按授权运行,审阅报告并采用为冻结核心。
19
+ 2. 用 `job template` 获取任务模板,填写实际需求后创建任务。动态参考先 `job analyze`;编辑底图单独绑定。
20
+ 3. 编译 `generate plan` 或 `edit plan`,保存并用 `run --plan ... --dry` 核对模型、尺寸、候选数、输入和参数转换。
21
+ 4. 按任务授权执行,保存 taskId;前台和后台都登记运行。查询原身份,不因超时或重启重复提交。
22
+ 5. `check` 核验产物,`candidate finalize` 定版。替换需 `--replace`,删除需 `--confirm`,均保留事实记录。
64
23
 
65
- ## 风格分析与冻结
24
+ 正式风格只读,修改需派生。任务空闲后可按原身份更新配置,历史批次不覆写。状态优先级为待定版、执行中、已定版、草稿;运行状态与停止证据分别判断,不能只看终态释放占用。
66
25
 
67
- 输入包含 project、id、description、refs、constraints。图片参考声明 path、scope(style/palette/shape/render)、note。纯语言也可分析;多图分别观察后合并。参考图只用于分析,文生图不会自动把这些图片传给生图模型。
26
+ ## 后端与数据归属
68
27
 
69
- ```powershell
70
- node art-workshop.mjs style analyze --project cellgame --input projects/cellgame/briefs/style.json --dry
71
- node art-workshop.mjs style analyze --project cellgame --input projects/cellgame/briefs/style.json --out projects/cellgame/reports/new-style.json
72
- node art-workshop.mjs style validate --project cellgame --report projects/cellgame/reports/new-style.json
73
- node art-workshop.mjs style freeze --project cellgame --report projects/cellgame/reports/new-style.json
74
- node art-workshop.mjs style show --project cellgame --core new-style
75
- ```
28
+ 本地为 ComfyUI 内置 Qwen Image 2.1 Q4、CPU 文本编码器方案,支持生成和显式底图编辑。自定义 API workflow 需要明确 bindings 与完整适配,不能把任意导入工作流视为可执行。
76
29
 
77
- 分析只生成报告,不自动冻结。报告区分观察证据、置信度、推荐配置、conflicts 与 uncertainties。处理完冲突和未确定项才能冻结。freeze 表示采用推荐配置;已有核心不能覆写,另一套风格使用新的核心 ID。
30
+ 远程图片通过工具登记的协议适配器直接调用,目前登记 DashScope。模型、参数与支持状态由 art 内部登记表维护,Vant 读取同一目录,不复制型号判断。分析使用独立视觉模型连接;未注入视觉连接时使用百炼 CLI。Token Plan 是渠道,DashScope 是协议,不能据协议擅自替换实例地址和凭据。
78
31
 
79
- 核心只拥有媒介、形体、渲染、光照、色彩关系与题材适配。正向和负向风格提示词从同一结构化核心生成。结构校验覆盖已定义的矛盾;自然语言证据与完整语义仍需审阅。规则详见 docs/core-guidance.md。
80
-
81
- ## 文生图
82
-
83
- 任务 kind 为 generate,core 绑定风格,profile 绑定资产规格。items 声明 intent、entities、effects、relations、composition、mustRead、seed 与 variants。候选只调整构图和 seed。
84
-
85
- 核心选择顺序:显式 --core → 任务 core → 工程 defaultCore。显式指定与任务绑定冲突时报错,须先修改任务绑定。没有明确选择时不能猜测。计划保存核心身份、哈希、选择依据与完整快照。
86
-
87
- ```powershell
88
- node art-workshop.mjs generate show --project cellgame --job skills
89
- node art-workshop.mjs generate plan --project cellgame --job skills --out .cache/skills-plan.json
90
- node art-workshop.mjs generate run --plan .cache/skills-plan.json --item skill-01 --dry
91
- node art-workshop.mjs generate run --plan .cache/skills-plan.json --limit 2
92
- node art-workshop.mjs generate run --plan .cache/skills-plan.json --item skill-01 --variant front --dry
93
- ```
94
-
95
- plan 编译全部候选;run 默认 base,--variant 选指定候选,--explore 执行全部候选。修改任务后重新 plan,冻结计划不能同时修改来源配置。
96
-
97
- 背景默认 {type:solid,color:#FFFFFF},纯黑用 #000000。其他纯色可显式配置,渐变用 gradient/from/to,场景用 scene/description 且须被资产规格允许。背景提示词和验收共用解析结果。
98
-
99
- ## 图编辑
100
-
101
- 任务 kind 为 edit,每项有 source、changes、preserve、mustRead、可选 seed。范围为 background/style/shape/color/composition/content/detail/text;同一范围不能同时修改和保留。背景修改用结构化 value,其他范围用 instruction。
102
-
103
- ```powershell
104
- node art-workshop.mjs edit show --project cellgame --job edit-white-background
105
- node art-workshop.mjs edit plan --project cellgame --job edit-white-background --out .cache/edit-plan.json
106
- node art-workshop.mjs edit run --plan .cache/edit-plan.json --dry
107
- node art-workshop.mjs edit run --plan .cache/edit-plan.json
108
- ```
109
-
110
- 编辑默认保留原图风格,不自动读取工程默认核心或替换背景。目标风格须明确绑定 core,此时不能再写 style 修改或保留。原图哈希写入计划,原图改变后须重新预演。示例任务将已有 skill-01 改成纯白背景,保留主体、效果和构图。
111
-
112
- ## 预演与验收
113
-
114
- plan 与 run --dry 均不调用远程生图,分别返回完整编译快照与选定项实际请求参数,不生成图片。分析 --dry 返回预计请求,实际远程调用数为 0。
115
-
116
- 实际 run 保存图片、输入和输出哈希、失败记录。人工分别检查 content/style/asset,产物完整、生成成功且三个维度全部 pass 才能 select。check 汇总人工验收,不自动评价图像。
117
-
118
- ```powershell
119
- node art-workshop.mjs check <runId> --out .cache/review.json
120
- # 编辑 review 的 content/style/asset 为 pass/fail/pending,并填写 reason。
121
- node art-workshop.mjs check <runId> --review .cache/review.json
122
- node art-workshop.mjs select <runId> --item skill-01 --variant base --review .cache/review.json
123
- node art-workshop.mjs compare .cache/plan-a.json .cache/plan-b.json
124
- node --test tests/art-workshop.test.mjs
125
- ```
126
-
127
- 依赖 Node.js 与已配置的 bailian-cli。历史图片保留供对照,旧配置和旧计划接口不再支持。真实模型效果需另行实测。
128
-
129
- ## v-cli 接入
130
-
131
- 美术工坊是 v-cli 的随包官方插件,入口为 `v-cli art`。先运行 `v-cli agent docs art` 和 `v-cli agent describe art --json`,再运行 `v-cli art config show`、`v-cli art agent index` 选择正确工程。本文所有 `art-workshop` 命令都可将前缀替换为 `v-cli art`;参数、外部本地配置和冻结核心保持一致。`v-cli art --help` 查看入口,`v-cli art agent docs` 查看完整使用规范。
132
- ## UI 设计分辨率与单体出图尺寸
133
-
134
- UI 设计基准属于资产规格,不写进冻结风格核心。文生图 profile 可声明:
135
-
136
- ```json
137
- "design": { "resolution": { "width": 1920, "height": 1080 }, "outputScale": 2 }
138
- ```
139
-
140
- 任务 item 可声明独立控件尺寸与可选倍率:
141
-
142
- ```json
143
- "design": { "width": 240, "height": 80, "outputScale": 4 }
144
- ```
32
+ 应用数据根默认 `~/.vant`,可由 `VANT_HOME` 覆盖。工具配置为 `~/.vant/tools/art-workshop/config.json`;Vant 将工程美术数据绑定至工程 `.vant/art`。共享模型环境默认 `~/.vant/art-env`,控制状态与日志归用户数据根;安装根保存环境标记 `vant.art.config.json`。
145
33
 
146
- 该按钮实际请求 size 为 960*320。同一任务的其他控件可使用不同设计尺寸;单体没有 design 时按 profile 的整幅设计分辨率出图。未覆盖倍率时继承 profile.outputScale。倍率为 1~4 的整数,设计尺寸为正整数且不得超过基准分辨率;换算后的每条边必须在工具支持的 256~4096 像素范围内,越界报错,不自动拉伸、补边或更改倍率。模型可能有额外尺寸与比例限制,工具的通用范围不等于模型能力保证。
34
+ ## 文档
147
35
 
148
- 启用设计尺寸时禁止同时设置任务 execution.size;工程和本地 execution.size 默认值被单体换算尺寸替代,模型等其他执行参数保留既有优先级。旧任务不声明 design 时保持原有行为。设计模式的提示词不再附加整体占画幅 75% 等比例要求,而声明设计宽高比和安全留白。
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) | 风格与需求的职责边界 |
149
47
 
150
- 编译计划的每项包含 design(resolution、size、outputScale、outputSize)与实际 execution。预演、真实请求、输入哈希与执行验收使用同一份单体参数。修改设计尺寸后必须重新 plan。此配置控制请求画布,不保证模型精确绘制控件边界、描边或圆角像素,也不自动生成九宫切片、裁切或透明底资源。
48
+ 开发校验:`npm run docs:generate`、`npm run check`、`npm run test:package`。模拟测试、配置有效和服务可连接都不能代替真实出图;文档更新不代表新包已发布或桌面安装已更新。
package/art-workshop.mjs CHANGED
@@ -4,40 +4,90 @@ import {join,resolve} from 'node:path';
4
4
  import {readJson,writeJson} from './lib/shared.mjs';
5
5
  const args=process.argv.slice(2),pos=[],options={};
6
6
  if(args.length===1&&['--version','-V'].includes(args[0])){console.log(readJson(new URL('./package.json',import.meta.url)).version);process.exit(0);}
7
- const help='art-workshop: config path/show/init | refs guide | agent index/docs/init | list | style analyze/validate/freeze/show | generate show/plan/run | edit show/plan/run | check/select RUN | compare PLAN PLAN\n也可用 v-cli art 调用;先 v-cli agent docs art,再 v-cli agent describe art --json 查看完整参数。';
7
+ const help='art-workshop: config path/show/init/validate | doctor [--backend ID] [--start] | workflow list | deployment plan/start/status/cancel/recover | refs guide | agent index/docs/init | list | style create/list/read/update/derive/discard/analyze/adopt/recover/validate/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/analyze | reference import/list/update/remove | candidate list/finalize/delete/finalizations | compare PLAN PLAN\nrun --background 返回任务 ID;--backend 选择后端。shutdown 停止当前工作区关联任务,核验共享队列和进程身份后关闭本地服务。\n也可用 v-cli art 调用;先 v-cli agent docs art,再 v-cli agent describe art --json 查看完整参数。';
8
8
  if(!args.length||args.length===1&&['--help','-h','help'].includes(args[0])){console.log(help);process.exit(0);}
9
9
  const {loadJob,loadProject}=await import('./lib/project.mjs');
10
- const {referenceRoot,ensureReferenceDirectories,referenceGuide}=await import('./lib/refs.mjs');
10
+ const {referenceRoot,referenceGuide}=await import('./lib/refs.mjs');
11
11
  const {loadSettings,initSettings,externalPath}=await import('./lib/settings.mjs');
12
- const {analyzeStyle}=await import('./lib/analyze.mjs');
13
- const {validateReport,freezeCore,loadCore}=await import('./lib/core.mjs');
12
+ const {validateReport,loadCore}=await import('./lib/core.mjs');
14
13
  const {compileGenerate}=await import('./lib/generate.mjs');
15
14
  const {compileEdit}=await import('./lib/edit.mjs');
16
15
  const {validatePlan,selectItems}=await import('./lib/plan.mjs');
17
16
  const {executePlan,checkRun}=await import('./lib/executor.mjs');
18
17
  const {agentIndex,agentDocs,syncSkill,autoSync}=await import('./lib/agent.mjs');
19
- const flags=new Set(['dry','explore']);
20
- const allowed=new Set(['config','workspace','output-dir','refs-dir','cache-dir','directory','project','input','out','report','note','core','job','plan','item','variant','offset','limit','review','file',...flags]);
18
+ const {backendDefaults,bindBackend,buildComfyRequest}=await import('./lib/backends.mjs');
19
+ const {startTask,taskStatus,taskView,recoverTask,resumeTask,waitTask,cancelTask,shutdown}=await import('./lib/tasks.mjs');
20
+ const {runtimeRoot,tasks}=await import('./lib/runtime.mjs');
21
+ const {validateConfiguration,doctor}=await import('./lib/diagnostics.mjs');
22
+ const {createProject,createObject,listObjects,readObject,updateObject,deriveObject,discardObject,importReference,removeReference,updateReference,taskDisplayState,STYLE_CATEGORIES,TASK_PURPOSES}=await import('./lib/workspace.mjs');
23
+ const {startAnalysis,adoptStyle,recoverStyleAdoption}=await import('./lib/style-lifecycle.mjs');
24
+ const {candidates,finalize,deleteCandidate,finalizations,editFromCandidate}=await import('./lib/candidates.mjs');
25
+ const {upgradeProject}=await import('./lib/migration.mjs');
26
+ const {workflowList}=await import('./lib/workflows.mjs');
27
+ const {jobTemplate}=await import('./lib/templates.mjs');
28
+ const {deploymentPlan,startDeployment,deploymentStatus,cancelDeployment,recoverDeployment}=await import('./lib/deployment.mjs');
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]);
21
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]);}
22
32
  const print=x=>console.log(JSON.stringify(x,null,2));
23
- const settings=loadSettings({file:options.config?resolve(options.config):undefined,workspace:options.workspace,output:options['output-dir'],refs:options['refs-dir'],cache:options['cache-dir']});
33
+ if(pos[0]==='workflow'&&pos[1]==='list'){print(workflowList());process.exit(0);}
34
+ let settings;
35
+ 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']});}
36
+ catch(error){print({ok:false,stage:'configuration',issues:[{code:'configuration',message:error.message}]});process.exit(1);}
37
+ if(pos[0]==='config'&&pos[1]==='validate'||pos[0]==='doctor'){
38
+ if(pos[0]==='doctor'&&pos[1])throw new Error('doctor 不接受位置参数');
39
+ const report=pos[0]==='doctor'?await doctor(settings,{backend:options.backend,start:options.start}):validateConfiguration(settings,{backend:options.backend});print(report);process.exitCode=report.ok?0:1;
40
+ }else{
41
+ if(options.start)throw new Error('--start 仅用于 doctor');
24
42
  const ROOT=settings.paths.workspace;
25
43
  const path=x=>externalPath(resolve(ROOT,x),'资源文件');
26
44
  function required(k){const value=options[k]??(k==='project'?settings.defaultProject:undefined);if(!value) throw new Error('需要 --'+k);return value;}
27
45
  function manifestPath(value){const p=externalPath(resolve(settings.paths.output,value));return p.endsWith('.json')?p:join(p,'manifest.json');}
28
46
  try {
29
47
  const [module,action]=pos;
30
- ensureReferenceDirectories(settings.paths.refs);
31
- const selectedProject=options.project??(['refs','style','generate','edit'].includes(module)?settings.defaultProject:undefined);
32
- const effectiveRefs=selectedProject?referenceRoot({workspace:ROOT,defaultRefsDir:settings.paths.refs,refsDir:options['refs-dir']?settings.paths.refs:undefined,project:loadProject(selectedProject,ROOT)}):settings.paths.refs;
33
- ensureReferenceDirectories(effectiveRefs);
34
- if(settings.autoSyncSkills&&!options.dry&&['style','generate','edit'].includes(module)&&['analyze','freeze','run'].includes(action)){try{autoSync();}catch(error){console.error('skill 自动同步失败:'+error.message+';可用 agent init 重试。');}}
35
- if(module==='config'){
48
+
49
+ const effectiveRefs=referenceRoot({defaultRefsDir:settings.paths.refs});
50
+ if(settings.autoSyncSkills&&!options.dry&&['style','generate','edit'].includes(module)&&['analyze','adopt','run'].includes(action)){try{autoSync();}catch(error){console.error('skill 自动同步失败:'+error.message+';可用 agent init 重试。');}}
51
+ if(module==='deployment'){
52
+ if(action==='plan'){const plan=deploymentPlan(settings,{directory:required('directory'),endpoint:options.endpoint});if(options.out)writeJson(path(options.out),plan);print(plan);}
53
+ else if(action==='start')print(await startDeployment(settings,readJson(path(required('plan'))),{operationId:required('operation')}));
54
+ else if(action==='status')print(deploymentStatus(settings,required('id')));
55
+ else if(action==='cancel')print(cancelDeployment(settings,required('id')));
56
+ else if(action==='recover')print(await recoverDeployment(settings,required('operation')));
57
+ else throw new Error('未知 deployment 操作');
58
+ }
59
+ else if(module==='config'){
36
60
  if(action==='path') console.log(settings.file);
37
61
  else if(action==='show') print(settings);
38
62
  else if(action==='init') print(initSettings(settings.file));
39
63
  else throw new Error('未知 config 操作');
40
64
  }
65
+ else if(module==='project'){
66
+ if(action==='upgrade')print(await upgradeProject(ROOT,required('project'),{dry:options.dry,settings,referenceAssignments:options.mapping?readJson(path(options.mapping)):undefined}));
67
+ else if(action==='init')print(await createProject(settings,required('project'),readJson(path(required('input')))));
68
+ else throw new Error('未知 project 操作');
69
+ }
70
+ else if(module==='reference'){
71
+ const projectId=required('project'),kind=required('kind'),objectId=required('id');
72
+ if(action==='list')print(readObject(ROOT,projectId,kind,objectId).references);
73
+ else if(action==='import')print(await importReference(settings,projectId,kind,objectId,Number(required('revision')),{source:required('source'),category:options.category,purposes:options.purposes?.split(','),note:options.note??''}));
74
+ else if(action==='remove')print(await removeReference(settings,projectId,kind,objectId,Number(required('revision')),required('item')));
75
+ else if(action==='update')print(await updateReference(settings,projectId,kind,objectId,Number(required('revision')),required('item'),readJson(path(required('input')))));
76
+ else throw new Error('未知 reference 操作');
77
+ }
78
+ else if(module==='job'||module==='style'&&['create','list','update','derive','discard','read'].includes(action)){
79
+ const projectId=required('project'),kind=module==='job'?'task':'style';
80
+ if(action==='template'&&kind==='task')print(jobTemplate(ROOT,projectId,{kind:options.kind,core:options.core}));
81
+ else if(action==='from-candidate'&&kind==='task')print(await editFromCandidate(settings,projectId,required('id'),{runId:required('run'),candidateId:required('candidate')}));
82
+ else if(action==='list'){const records=listObjects(ROOT,projectId,kind),runs=kind==='task'?tasks(runtimeRoot(settings)).map(t=>taskStatus(runtimeRoot(settings),t.taskId)):[];print(records.map(record=>kind==='task'?{...record,display:taskDisplayState(record,runs,record.finalizations??[])}:record));}
83
+ else if(action==='create')print(await createObject(settings,projectId,kind,readJson(path(required('input')))));
84
+ else if(action==='read')print(readObject(ROOT,projectId,kind,required('id')));
85
+ else if(action==='update')print(await updateObject(settings,projectId,kind,required('id'),Number(required('revision')),readJson(path(required('input')))));
86
+ else if(action==='analyze'&&kind==='task')print(await startAnalysis(settings,projectId,required('id'),Number(required('revision')),{dry:options.dry,kind:'task',operationId:options.operation}));
87
+ else if(action==='derive')print(await deriveObject(settings,projectId,kind,required('id'),Number(required('revision'))));
88
+ else if(action==='discard')print(await discardObject(settings,projectId,kind,required('id'),Number(required('revision'))));
89
+ else throw new Error('未知对象操作');
90
+ }
41
91
  else if(module==='refs'){
42
92
  if(action!=='guide') throw new Error('未知 refs 操作;使用 refs guide');
43
93
  console.log(referenceGuide(effectiveRefs));
@@ -51,27 +101,47 @@ try {
51
101
  else if(module==='list'){print((existsSync(join(ROOT,'projects'))?readdirSync(join(ROOT,'projects')):[]).map(id=>readJson(join(ROOT,'projects',id,'project.json'))));}
52
102
  else if(module==='style'){
53
103
  const projectId=required('project');
54
- if(action==='analyze'){const result=analyzeStyle({projectId,input:readJson(path(required('input'))),out:options.out?path(options.out):undefined,root:ROOT,refsDir:options['refs-dir']?settings.paths.refs:undefined,defaultRefsDir:settings.paths.refs,cacheDir:join(settings.paths.cache,'analysis'),analysisModel:settings.analysisModel,dry:options.dry});print(result);}
104
+ if(action==='analyze')print(await startAnalysis(settings,projectId,required('id'),Number(required('revision')),{dry:options.dry,operationId:options.operation}));
105
+ else if(action==='recover')print(await recoverStyleAdoption(settings,projectId,required('id')));
106
+ else if(action==='adopt')print(await adoptStyle(settings,projectId,required('id'),Number(required('revision')),{note:options.note}));
55
107
  else if(action==='validate') print(validateReport(readJson(path(required('report'))),projectId));
56
- else if(action==='freeze') print(freezeCore({projectId,report:readJson(path(required('report'))),note:options.note,root:ROOT}));
57
108
  else if(action==='show') print(loadCore(projectId,required('core'),ROOT));
58
109
  else throw new Error('未知 style 操作');
59
110
  }else if(['generate','edit'].includes(module)){
60
111
  if(action==='show') print(loadJob(required('project'),required('job'),module,ROOT));
61
112
  else if(['plan','run'].includes(action)){
62
113
  let plan;
63
- if(options.plan){if(action!=='run'||['project','job','core','explore'].some(k=>options[k]!==undefined)) throw new Error('冻结计划不能同时调整来源;修改任务后重新 plan');plan=readJson(path(options.plan));validatePlan(plan);if(plan.module!==module) throw new Error('计划模块不匹配');}
64
- else plan=(module==='generate'?compileGenerate:compileEdit)({projectId:required('project'),jobId:required('job'),coreId:options.core,root:ROOT,localExecution:settings.execution});
114
+ if(options.plan){if(action!=='run'||['project','job','core','explore','backend'].some(k=>options[k]!==undefined)) throw new Error('冻结计划不能同时调整来源;修改任务后重新 plan');plan=readJson(path(options.plan));validatePlan(plan);if(plan.module!==module) throw new Error('计划模块不匹配');}
115
+ else plan=bindBackend((module==='generate'?compileGenerate:compileEdit)({projectId:required('project'),jobId:required('job'),coreId:options.core,root:ROOT,localExecution:backendDefaults(settings,options.backend)}),settings,options.backend);
65
116
  if(action==='plan'){if(options.out) writeJson(path(options.out),plan);print(plan);}
66
- else {const variant=options.variant??(options.explore?undefined:'base');const items=selectItems(plan,{item:options.item,variant,offset:options.offset===undefined?0:Number(options.offset),limit:options.limit===undefined?undefined:Number(options.limit)});const result=executePlan(plan,items,{outputRoot:settings.paths.output,dry:options.dry});if(result.manifest?.summary.failed) process.exitCode=1;}
117
+ else {
118
+ if(options['retry-run']&&(options.dry||options.variant||options.item||options.offset||options.limit))throw new Error('失败项重试不能混用预演或手动筛选');
119
+ if(options.variant&&options['all-variants'])throw new Error('不能同时选择单个候选与全部候选');
120
+ const variant=options.variant??(options.explore||options['all-variants']?undefined:'base');const items=selectItems(plan,{item:options.item,variant,offset:options.offset===undefined?0:Number(options.offset),limit:options.limit===undefined?undefined:Number(options.limit)});
121
+ if(options.dry){if(plan.backend?.provider==='comfyui')print({dry:true,remoteCalls:0,planHash:plan.planHash,requests:items.map(item=>({itemId:item.itemId,variantId:item.variantId,requests:Array.from({length:(item.execution??plan.execution).perValue},(_,index)=>buildComfyRequest(plan,item,{index}))}))});else executePlan(plan,items,{outputRoot:settings.paths.output,dry:true});}
122
+ else {const task=await startTask(plan,items,settings,{operationId:options.operation,retryRun:options['retry-run']??null});if(options.background)print(task);else {console.log('task → '+task.taskId);const result=await waitTask(runtimeRoot(settings),task.taskId);print(taskView(result));if(result.status!=='succeeded')process.exitCode=1;}}
123
+ }
67
124
  }else throw new Error('未知模块操作');
68
- }else if(['check','select'].includes(module)){
69
- const file=manifestPath(action??required('file')),manifest=readJson(file);
70
- const review=options.review?readJson(path(options.review)):manifest.review;
71
- const rows=checkRun(manifest,file,review);
72
- if(module==='check'){if(options.out) writeJson(path(options.out),rows);print(rows);}
73
- else {const matched=rows.filter(x=>x.itemId===required('item')&&x.variantId===required('variant')&&(!options.file||x.file===options.file));if(matched.length!==1||!matched[0].accepted) throw new Error('只能选择唯一且全部验收通过的产物');manifest.review=rows;manifest.selections[options.item]=matched[0];writeJson(file,manifest);print(matched[0]);}
125
+ }else if(module==='task'){
126
+ const root=runtimeRoot(settings),taskId=pos[2];
127
+ if(action==='list')print(tasks(root).filter(t=>!options.project||(t.plan?.project??t.project)===options.project).map(t=>taskView(taskStatus(root,t.taskId))));
128
+ else if(action==='recover')print(recoverTask(root,required('project'),required('operation')));
129
+ else if(action==='status')print(taskView(taskStatus(root,taskId)));
130
+ else if(action==='resume')print(await resumeTask(root,taskId));
131
+ else if(action==='cancel')print(taskView(await cancelTask(root,taskId)));
132
+ else if(action==='wait'){const timeoutSeconds=options.timeout===undefined?3600:Number(options.timeout);if(!Number.isFinite(timeoutSeconds)||timeoutSeconds<=0)throw new Error('timeout 必须为正秒数');const result=await waitTask(root,taskId,{timeoutSeconds});print(taskView(result));if(result.status!=='succeeded')process.exitCode=1;}
133
+ else throw new Error('未知 task 操作');
134
+ }else if(module==='shutdown'){if(action)throw new Error('shutdown 不接受位置参数');print(await shutdown(settings));}
135
+ else if(module==='candidate'){
136
+ const projectId=required('project'),jobId=required('job');
137
+ if(action==='list')print(candidates(settings,projectId,jobId,required('run')));
138
+ else if(action==='finalize')print(await finalize(settings,projectId,jobId,Number(required('revision')),{runId:required('run'),candidateId:required('candidate'),replace:options.replace,actor:required('actor')}));
139
+ else if(action==='delete')print(await deleteCandidate(settings,projectId,jobId,Number(required('revision')),{runId:required('run'),candidateId:required('candidate'),confirm:options.confirm,actor:required('actor')}));
140
+ else if(action==='finalizations')print(finalizations(settings,projectId,jobId));
141
+ else throw new Error('未知 candidate 操作');
142
+ }else if(module==='check'){print(checkRun(readJson(manifestPath(action??required('file'))),manifestPath(action??required('file'))));
74
143
  }else if(module==='compare'){const read=value=>{const data=readJson(path(value));const plan=data.plan??data;validatePlan(plan);return plan;};const a=read(action),b=read(pos[2]);print({sameCore:a.sources.coreHash===b.sources.coreHash,execution:{before:a.execution,after:b.execution},items:b.items.map(x=>({itemId:x.itemId,variantId:x.variantId,changed:a.items.find(y=>y.itemId===x.itemId&&y.variantId===x.variantId)?.inputHash!==x.inputHash}))});}
75
144
  else if(!module||module==='help') console.log(help);
76
145
  else throw new Error('未知模块或旧入口:'+module);
77
- }catch(e){console.error(e.message);process.exitCode=1;}
146
+ }catch(e){print({ok:false,error:e.message,...(e.diagnostic?{diagnostic:e.diagnostic}:{})});process.exitCode=1;}
147
+ }