@kevlns/art-workshop 0.1.3 → 0.2.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.
@@ -0,0 +1,166 @@
1
+ # art 统一配置
2
+
3
+ 配置是用户级结构化 JSON,远程与本地后端共用一份文件。工具配置只定义执行与资源路径;工程任务和冻结核心保持独立文件,认证由百炼 CLI 管理。
4
+
5
+ ## 位置与覆盖
6
+
7
+ ```powershell
8
+ v-cli art config path
9
+ v-cli art config init
10
+ v-cli art config show
11
+ v-cli art config validate
12
+ ```
13
+
14
+ config init 创建默认文件,已有文件不覆盖。默认位置:Windows 的 %APPDATA%/art-workshop/config.json;macOS 的 ~/Library/Application Support/art-workshop/config.json;Linux 的 $XDG_CONFIG_HOME/art-workshop/config.json,未设置时使用 ~/.config/art-workshop/config.json。
15
+
16
+ --config FILE 优先于 ART_WORKSHOP_CONFIG;未指定则使用默认位置。工作流、launch.executable 与 launch.cwd 的相对路径基于配置文件目录。资源目录建议写绝对路径:paths 中相对值实际按当前工作目录解析,不按 config.json 目录解析。
17
+
18
+ ## 一份远程与本地配置
19
+
20
+ 以下是合法结构示例;路径、模型和后端 ID 需与本机安装匹配。
21
+
22
+ ```json
23
+ {
24
+ "paths": {
25
+ "workspace": "C:/ArtWorkspace",
26
+ "output": "C:/ArtWorkspace/output",
27
+ "refs": "C:/ArtReferences",
28
+ "cache": "C:/ArtWorkspace/.cache"
29
+ },
30
+ "execution": {},
31
+ "analysisModel": null,
32
+ "defaultProject": null,
33
+ "autoSyncSkills": true,
34
+ "generation": {
35
+ "defaultBackend": "local-qwen",
36
+ "defaults": { "perValue": 1, "promptExtend": false, "watermark": false },
37
+ "backends": {
38
+ "remote-qwen": {
39
+ "provider": "bailian",
40
+ "model": "qwen-image-3.0-pro",
41
+ "execution": { "size": "1024*1024" }
42
+ },
43
+ "local-qwen": {
44
+ "provider": "comfyui",
45
+ "model": "qwen-image-2.1-UC-Q4_K_M.gguf",
46
+ "execution": { "size": "512*512" },
47
+ "endpoints": ["http://127.0.0.1:8188"],
48
+ "workflow": "vant-builtin-qwen-image-2.1-Q4-8GB",
49
+ "options": { "steps": 25, "cfg": 1, "sampler": "euler", "scheduler": "simple", "timeoutSeconds": 1800, "pollMilliseconds": 500 },
50
+ "launch": {
51
+ "executable": "C:/AI/ComfyUI_windows_portable/python_embeded/python.exe",
52
+ "cwd": "C:/AI/ComfyUI_windows_portable",
53
+ "args": ["-s", "ComfyUI/main.py", "--windows-standalone-build", "--disable-dynamic-vram", "--lowvram", "--disable-auto-launch"],
54
+ "startupTimeoutSeconds": 120
55
+ }
56
+ }
57
+ }
58
+ }
59
+ }
60
+ ```
61
+
62
+ ## 顶层字段
63
+
64
+ | 字段 | 规范 |
65
+ |---|---|
66
+ | paths.workspace | 工程根目录,包含 projects |
67
+ | paths.output | 运行文件夹、图片与 manifest 的根目录 |
68
+ | paths.refs | 默认参考目录;--refs-dir 或工程 refsDir 可覆盖 |
69
+ | paths.cache | 分析缓存目录 |
70
+ | execution | 已有全局执行覆盖;建议新配置保持空,将模式参数放在各后端 |
71
+ | generation | 默认后端、共享默认值、后端字典 |
72
+ | analysisModel | 覆盖工程分析模型;null 使用工程值,与生图后端独立 |
73
+ | defaultProject | 省略 --project 时使用的真实工程 ID,或 null |
74
+ | autoSyncSkills | 自动同步随包 skill,默认 true;不影响手动 agent init |
75
+
76
+ 默认资源根为系统下载目录/image.g;cache 默认其 .cache,refs 默认其 refs。Windows 尊重系统下载 Known Folder,Linux 尊重 XDG 下载配置。运行资源须在安装目录之外,禁止通过链接绕回安装目录。
77
+
78
+ ## 执行参数与优先级
79
+
80
+ 最终参数按下列过程形成,后写入者覆盖前值:
81
+
82
+ 1. 通用默认:qwen-image-3.0-pro、1024*1024、perValue=1、promptExtend=false、watermark=false。
83
+ 2. 工程 project.execution。
84
+ 3. 所选后端的默认层:内置本地模板先提供 size=512*512,再合并 generation.defaults、backend.execution、backend.model。
85
+ 4. 顶层 execution。
86
+ 5. job.execution。
87
+ 6. 使用 design 时,以每项换算的 outputSize 覆盖 size。
88
+
89
+ 没有显式 --backend 和 generation.defaultBackend 时,不使用 generation.defaults,按已有顶层 execution 路径走百炼默认。冻结计划保留生成时的值,不会随配置变化更新。
90
+
91
+ | 参数 | 规范 |
92
+ |---|---|
93
+ | model | 顶层/工程/任务 execution 可指定;backend.model 必填,后端 execution 不接受 model |
94
+ | size | 明确 W*H,不能写 1:1;每边 256~4096,本地额外要求 32 的倍数 |
95
+ | perValue | 每个选中 item/variant 生成 1~4 张 |
96
+ | promptExtend | 布尔值;本地只能 false |
97
+ | watermark | 布尔值;本地只能 false |
98
+
99
+ generation.defaults 和 backend.execution 仅接受 size/perValue/promptExtend/watermark。后端 ID 为配置字典键,不是模型名。--backend 只在编译新计划时选后端。
100
+
101
+ ## ComfyUI 后端字段
102
+
103
+ | 字段 | 规范 |
104
+ |---|---|
105
+ | provider | comfyui;远程为 bailian |
106
+ | model | 工作流使用的生成模型文件名,与 model binding 对应 |
107
+ | endpoints | 非空列表;仅 http、本机 127.0.0.1/localhost/[::1] 根地址;无认证、路径或查询参数 |
108
+ | workflow | 省略或内置名称时使用内置模板;其他字符串为 API JSON 文件路径 |
109
+ | bindings | 内置模板提供默认绑定;自定义模板必须声明 |
110
+ | options | steps 1~10000;cfg 0~100;sampler/scheduler 按实际节点选项;timeoutSeconds 1~86400;pollMilliseconds 50~10000 |
111
+ | launch | 可选;没有可用服务且未配置时,任务报错;不自动寻找安装目录 |
112
+
113
+ launch 使用直接 executable 和 args 数组,不执行 shell 脚本。cwd 为启动工作目录。startupTimeoutSeconds 范围 1~600,默认 120。--start 和正常任务可触发启动;服务保留至 shutdown,没有闲置自动回收。多个 endpoint 按顺序探测;若需启动,则用同一 launch 启动并期待第一个 endpoint 可用,args 中的监听端口应与之匹配。
114
+
115
+ ## 自定义 workflow 与 bindings
116
+
117
+ 从 ComfyUI 导出 API 格式:顶层是节点 ID 字典,节点包含 class_type/inputs。普通画布 JSON 的 nodes/links 不能用于任务;workflow list 中的 UI JSON 用于导入画布,API JSON 用于 art。
118
+
119
+ 以下片段可作为后端条目,放入 generation.backends;指定文件须真实存在。
120
+
121
+ ```json
122
+ {
123
+ "provider": "comfyui",
124
+ "model": "qwen-image-2.1-UC-Q4_K_M.gguf",
125
+ "execution": { "size": "512*512" },
126
+ "endpoints": ["http://127.0.0.1:8188"],
127
+ "workflow": "workflows/custom-api.json",
128
+ "bindings": {
129
+ "model": { "node": "1", "input": "unet_name" },
130
+ "prompt": { "node": "4", "input": "prompt" },
131
+ "negativePrompt": { "node": "4", "input": "negative_prompt" },
132
+ "width": { "node": "5", "input": "width" },
133
+ "height": { "node": "5", "input": "height" },
134
+ "count": { "node": "5", "input": "batch_size" },
135
+ "seed": { "node": "6", "input": "seed" }
136
+ }
137
+ }
138
+ ```
139
+
140
+ | Binding | 调用检查 |
141
+ |---|---|
142
+ | prompt/width/height/seed | 必需,指向实际已有输入 |
143
+ | negativePrompt | 任务负向词非空时必需 |
144
+ | count | 执行时写 1;未绑定时模板中 batch_size 必须已为 1 |
145
+ | model | 写入最终 execution.model;未绑定时 GGUF 固定模型须与执行模型一致 |
146
+ | image | 本地图编辑必需,指向 LoadImage.image |
147
+ | vae | 本地图编辑必需,指向 VAELoader.vae_name;用于建立编码器 VAE 连接 |
148
+
149
+ 节点 ID 和 input 名是执行映射,中文 title 只用于展示。options 的采样参数写入 seed 所在节点,因此需要对应输入。每次请求复制模板,动态填提示词、尺寸、seed;不修改原模板。perValue 次请求串行执行,seed 依次为初始 seed+index,要求每次恰好输出一张最终图片。
150
+
151
+ Qwen 2.1 编辑模板额外加入 LoadImage,并声明 image/vae bindings;编辑时适配器连接 TextEncodeQwenImage21 的 images.image_1 与 vae。模板编码器 resolution=1024 是参考编码参数,不是输出宽高;EmptyLatentImage 的动态 size 决定采样画布。
152
+
153
+ ## 路径与持久化检查
154
+
155
+ | 对象 | 相对路径基准 |
156
+ |---|---|
157
+ | --input/--report/--plan/--out/--review、edit source | workspace |
158
+ | check/select RUN | output |
159
+ | 分析 refs[].path | 命令实际参考目录 |
160
+ | project.refsDir | workspace |
161
+ | workflow、launch.executable、launch.cwd | config.json 的目录 |
162
+ | paths 字段、CLI 目录覆盖 | 当前工作目录;建议使用绝对路径 |
163
+
164
+ --workspace、--output-dir、--refs-dir、--cache-dir 临时覆盖目录。参考目录顺序为显式 --refs-dir、工程 refsDir、用户 paths.refs。任务状态、锁和服务日志存于 config.json 旁 .runtime/<配置路径哈希>;该目录不是 workspace 的分析缓存。
165
+
166
+ config validate 不执行节点、不探测 HTTP,也不检查全部工程文件。doctor 检查环境;plan 校验具体任务和参数;run --dry 校对具体请求;真实运行验证模型可执行性。通过某一层不能省略后续层的模式要求。
@@ -1,15 +1,82 @@
1
1
  # 核心冻结指导规则
2
2
 
3
- 权威规则:rules/core-guidance.json。模型分析、配置校验和冻结记录共用这一份。
4
-
5
- 1. 语言精炼:每条规则表达一个可执行要求,避免重复和修辞。
6
- 2. 用词准确:统一术语,明确强度、范围与条件,不混用不同渲染机制。
7
- 3. 前后一致:报告、推荐、冻结、正向和负向提示词、验收要求保持一致。
8
- 4. 职责分明:核心定义视觉规律;资产定义背景和构图许可;需求定义主体、数量、动作与关系;执行定义模型和尺寸;编辑定义修改与保留。
9
- 5. 单一来源:一个事实只有一个权威字段,提示词从结构化配置生成。
10
- 6. 作用域明确:规则明确作用对象,题材适配不能覆盖全局渲染或冻结单张内容。
11
- 7. 观察与建议分开:观察保留证据和置信度,建议进入推荐配置,不确定性显式列出。
12
- 8. 跨内容复用:不把参考图偶然的颜色、数量、背景和布局冻结为普遍要求。
13
- 9. 冻结可追溯:保留报告、规则、身份和哈希,冻结后不原地修改,任务明确选择基础核心。
14
-
15
- 校验覆盖结构、枚举、已知语义组合、精炼度与常见职责越界,不能穷尽自然语言全部语义矛盾,冻结前仍需审阅。未解决的 conflicts 或 uncertainties 会阻止冻结。
3
+ 权威规则为 rules/core-guidance.json。风格分析请求、推荐校验与冻结来源使用同一份规则。此文解释审查方法,不另造第二份可修改的风格提示词。
4
+
5
+ ## 各层拥有的内容
6
+
7
+ | 层 | 负责内容 | 审查重点 |
8
+ |---|---|---|
9
+ | core | 媒介、形体、渲染、光照、色彩关系、题材表面处理 | 是否跨主体复用,正负向是否一致 |
10
+ | profile | 背景、构图许可、留白、文字、外框、投影、设计基准 | 是否适合目标资产与设计尺寸 |
11
+ | generate item | 实体、数量、身份色、动作、关系、效果、单张构图 | 是否可从 mustRead 和实体字段确认内容 |
12
+ | execution/backend | 模型、size、perValue、seed、水印、扩写、workflow | 是否符合当前模式与环境 |
13
+ | edit item | 底图、changes、preserve | 修改与保留是否冲突,原图是否正确 |
14
+
15
+ ## 报告到冻结的检查
16
+
17
+ 1. 一条规则表达一个可执行判断,去掉同义重复和无助于生成的修辞。
18
+ 2. 视觉术语明确;强度、数量、颜色、范围有明确字段,避免互斥渲染机制。
19
+ 3. 推荐、冻结、正向提示词、负向约束与验收从同一结构生成,前后一致。
20
+ 4. 核心只拥有视觉语言;具体主体、布局、背景、模型、尺寸不得混入核心。
21
+ 5. 一个事实只有一个权威字段;不再追加另一段冻结 styleBlock 覆盖结构化核心。
22
+ 6. domains 规则明确作用于实体类别;表面科幻处理不等于给所有主体套同一结构。
23
+ 7. observations 保留 source、scope、feature、evidence、confidence;建议进入 recommendation,推断和未知进入 uncertainties。
24
+ 8. 不把参考图偶然的颜色、数量、背景和布局当成全局要求;不同主体允许保留自己的身份色。
25
+ 9. 冻结来源、身份与哈希可追溯;旧核心不能原地覆写,任务明确选择新核心。
26
+
27
+ style validate 检查结构、枚举、已定义语义矛盾、语言长度和常见职责越界。它不能穷尽自然语言矛盾或替代图像审查。未解决 conflicts/uncertainties 阻止冻结;处理后重新验证。
28
+
29
+ ```powershell
30
+ v-cli art style validate --project P --report projects/P/reports/style.json
31
+ # 已有用户采用报告的依据后执行。
32
+ v-cli art style freeze --project P --report projects/P/reports/style.json --note "采用已审阅的推荐风格"
33
+ v-cli art style show --project P --core style
34
+ ```
35
+
36
+ freeze 会写核心并更新 project.cores;没有 defaultCore 时可设为新核心。需要第二套风格时使用新的报告/核心 ID,不复制冻结文件改身份。
37
+
38
+ ## 生图时的核心检查
39
+
40
+ 文生图核心选择顺序为显式 --core、任务 core、工程 defaultCore。显式指定与任务 core 冲突时先修改任务绑定;没有明确选择时不跨工程回退。
41
+
42
+ 图编辑默认保留原图风格,不读取 defaultCore。明确绑定目标 core 时,style 的修改或保留由核心负责,任务不再重复声明。
43
+
44
+ 换远程/本地后端只改变执行能力,不自动改核心或需求。同一提示词在不同模型上的表现可能不同,必须按 content/style/asset 分别审查。
45
+
46
+ ## 风格变化的对照
47
+
48
+ 新风格先生成新报告和核心,再对相同任务编译两个计划,核对 compare 与 dry,固定可控 seed,在授权范围内做少量图像对照。compare 只对比计划,不评价风格一致性;同 seed 也不保证跨模型、版本或设备逐像素复现。
49
+
50
+ ```powershell
51
+ v-cli art compare .cache/old-plan.json .cache/new-plan.json
52
+ v-cli art check RUN --out .cache/review.json
53
+ ```
54
+
55
+ 只有产物完整、生成成功且 content/style/asset 全部 pass 才可 select。规则检查、模型成功返回或生成缩略图都不能单独作为生产资产验收。
56
+ ## 推荐核心结构示例
57
+
58
+ 以下是报告 recommendation 的合法结构示例,与 data-formats.md 的 energy 类别配套。它不是已冻结文件,仍需依据实际证据产生报告、审阅并 freeze;不要人为补 coreHash 绕过流程。
59
+
60
+ ```json
61
+ {
62
+ "medium": "illustration",
63
+ "shape": { "contour": "rounded", "detail": "low" },
64
+ "render": {
65
+ "shading": "cel",
66
+ "toneSteps": 2,
67
+ "outline": { "enabled": true, "color": "#34445C", "width": 0.004 },
68
+ "highlights": "hard-edge",
69
+ "finish": "matte",
70
+ "texture": "none"
71
+ },
72
+ "lighting": { "direction": "top-front", "contrast": "medium" },
73
+ "color": { "preserveIdentity": true, "shadowShift": "cool" },
74
+ "domains": {
75
+ "energy": { "treatment": "emissive", "signature": "用简洁硬边高光表达能量表面。" }
76
+ }
77
+ }
78
+ ```
79
+
80
+ medium 可为 illustration/painting/pixel-art/photography;轮廓为 rounded/angular/mixed,细节为 low/medium/high。shading 可为 cel/flat/smooth/painterly/pixel;cel 至少两阶、不能有软高光或可见纹理,flat 一阶,smooth/painterly 的 toneSteps 为 null,pixel-art 应配 pixel,photography 应配 smooth 且无描边。其他组合和长度限制由 style validate 核对。
81
+
82
+ 描边 width 是画幅宽度比 0~0.03,不是像素值;关闭描边时 width=0。domain treatment 可为 organic/hard-surface/emissive/structure/symbol,signature 只描述表面和形态处理,不声明本张主体、数量或背景。
@@ -0,0 +1,167 @@
1
+ # art 工程与输入结构
2
+
3
+ 所有工程数据放在配置的 workspace。工具只随包发布规则、指南和内置工作流,不随包发布用户工程、模型权重或图片。
4
+
5
+ ## 工程布局
6
+
7
+ ```text
8
+ workspace/
9
+ projects/P/
10
+ project.json
11
+ briefs/style.json
12
+ reports/style.json
13
+ cores/style.json
14
+ profiles/icon.json
15
+ jobs/generate.json
16
+ jobs/edit.json
17
+ ```
18
+
19
+ project.json 的最小结构示例:
20
+
21
+ ```json
22
+ {
23
+ "id": "demo",
24
+ "name": "示例工程",
25
+ "analysisModel": "qwen3-vl-plus",
26
+ "execution": { "size": "1024*1024", "perValue": 1, "promptExtend": false, "watermark": false },
27
+ "cores": [],
28
+ "defaultCore": null
29
+ }
30
+ ```
31
+
32
+ 实际 ID(示例 demo)必须与目录名一致,使用小写字母、数字、连字符。新工程先分析并冻结自己的核心,不能复制冻结文件修改身份。cores 可包含多核心,defaultCore 为成员 ID 或 null;没有默认值时明确选核心。refsDir 是可选工程参考目录。
33
+
34
+ ## 风格分析输入
35
+
36
+ ```json
37
+ {
38
+ "project": "demo",
39
+ "id": "style",
40
+ "description": "圆润低细节的科幻插画,用硬边色块表达明暗。",
41
+ "refs": [
42
+ { "path": "style/reference.png", "scope": "render", "note": "只观察明暗和描边,不继承主体或背景。" }
43
+ ],
44
+ "constraints": ["核心应适用于多个主体,主体身份色由任务声明。"]
45
+ }
46
+ ```
47
+
48
+ refs 可为空;有参考时 path 指向可读图片,scope 仅允许 style/palette/shape/render,note 描述观察边界。style、palette、subject、composition、material、text、pose 分类目录仅帮助整理,不自动绑定图片;分析 scope 与目录名不是同一组枚举。
49
+
50
+ 报告包含 observations、recommendation、conflicts、uncertainties 和 provenance。recommendation 的完整合法结构由核心规则和分析请求提供;用 style validate 检查后审阅,解决冲突和不确定项,再经用户采用 freeze。冻结文件带身份与哈希,不手写或原地修改。
51
+
52
+ ## 文生图任务
53
+
54
+ 任务顶层允许 project/kind/core/profile/execution/items。以下示例假定已存在工程核心 style 和 profile icon;不是无需准备即可运行的工程。
55
+
56
+ ```json
57
+ {
58
+ "project": "demo",
59
+ "kind": "generate",
60
+ "core": "style",
61
+ "profile": "icon",
62
+ "items": [
63
+ {
64
+ "id": "energy",
65
+ "seed": 1000,
66
+ "intent": "一颗青色能量球,两个细轨道前后环绕。",
67
+ "entities": [
68
+ { "id": "ball", "kind": "energy", "appearance": "能量球", "color": "青色", "role": "primary", "count": 1 }
69
+ ],
70
+ "effects": [
71
+ { "id": "orbit", "kind": "细轨道", "target": "ball", "color": "亮青色", "relation": "前后穿插环绕", "count": 2 }
72
+ ],
73
+ "composition": { "focalTarget": "ball" },
74
+ "mustRead": ["一个青色主体", "两个轨道环绕关系"],
75
+ "variants": [{ "id": "base" }]
76
+ }
77
+ ]
78
+ }
79
+ ```
80
+
81
+ entities 的 kind 必须在核心 domains 中有规则。id 不重复,角色为 primary/support,数量 1~100。效果 target 和 relations.from/to 必须指向声明的对象。身份色、数量、动作和关系属于需求,不放进全局风格。variants 只允许 id/composition/seed,不能通过候选偷偷改变实体语义。
82
+
83
+ profile 定义 constraints、defaults、allowedOverrides、presets、checks 和可选 design。构图字段只能在允许的枚举或范围内变化;焦点必须存在。核心选择依次为显式 --core、任务 core、工程 defaultCore;显式选择与任务绑定冲突时报错。
84
+
85
+ 背景默认纯白。其他纯色用 {type:solid,color:#RRGGBB};渐变声明 type=gradient/from/to;场景声明 type=scene/description 且 profile 允许 scene。默认留白、文字、外框、投影等由 profile 决定,plan 检查覆盖是否合法。
86
+
87
+ ## 图编辑任务
88
+
89
+ ```json
90
+ {
91
+ "project": "demo",
92
+ "kind": "edit",
93
+ "core": null,
94
+ "items": [
95
+ {
96
+ "id": "energy-white",
97
+ "source": "output/previous-run/energy--base.png",
98
+ "changes": [{ "target": "background", "value": { "type": "solid", "color": "#FFFFFF" } }],
99
+ "preserve": [
100
+ { "target": "content", "instruction": "保留能量球和两条轨道。" },
101
+ { "target": "style", "instruction": "保留主体渲染风格。" }
102
+ ],
103
+ "mustRead": ["纯白背景", "主体与轨道完整"],
104
+ "seed": 1000
105
+ }
106
+ ]
107
+ }
108
+ ```
109
+
110
+ source 基于 workspace,而不是 output;建议写绝对路径以避免目录误解。changes 非空,preserve 为数组;target 可为 background/style/shape/color/composition/content/detail/text。同一 target 不能重复或同时修改和保留。background 修改用 value,其余范围用 instruction。
111
+
112
+ 编辑不读取工程默认核心;显式选择或任务绑定核心才改变目标风格,且禁止再声明 style 的修改或保留。source 哈希进入 plan;更换底图后重新编译。当前接口每项仅一个 source,本地适配器仅上传一张底图。
113
+
114
+ ## UI 设计尺寸
115
+
116
+ 设计基准属于 profile,不属于冻结核心。profile 可加入:
117
+
118
+ ```json
119
+ { "design": { "resolution": { "width": 1920, "height": 1080 }, "outputScale": 2 } }
120
+ ```
121
+
122
+ 任务 item 可加入独立控件尺寸:
123
+
124
+ ```json
125
+ { "design": { "width": 240, "height": 80, "outputScale": 4 } }
126
+ ```
127
+
128
+ 该控件输出 960*320;同一任务其他控件可有不同尺寸。没有 item.design 时使用 profile 的整幅设计基准。倍率为 1~4 整数,控件每边为正整数且不得超过基准;未写倍率则继承 profile。每边实际输出必须在 256~4096 内,本地还要为 32 的倍数。越界报错,不自动拉伸、补边或调整倍率。
129
+
130
+ 使用 design 时禁止 job.execution.size;设计换算覆盖工程及全局 size 默认值,其他执行参数保持优先级。每项 plan 保存 design 和 execution;预演、执行、哈希和验收共用这些参数。设计尺寸控制请求画布,不保证控件边缘精确,也不自动切图、生成九宫格或透明底。
131
+
132
+ ## 输出与审查
133
+
134
+ 运行目录为 output/<job>-<taskId>,manifest 保存 plan 快照、输入与输出哈希、请求、文件、状态、失败诊断、验收及选择。图片名基于 itemId--variantId,多张带序号。不要将已生成图片、失败记录或 review 当作冻结核心。
135
+
136
+ compare 对比计划的核心哈希、执行与单体变化;不对图片打分。check 导出每图的人工 content/style/asset 检查要求;select 记录通过审查的唯一产物,不自动复制或导入游戏工程。
137
+ ## 完整 profile 示例
138
+
139
+ 以下保存为 projects/demo/profiles/icon.json,与前面的任务配套。可以从这一份最小规格扩展允许的构图;不要直接添加不在 allowedOverrides 中的值。
140
+
141
+ ```json
142
+ {
143
+ "project": "demo",
144
+ "id": "icon",
145
+ "name": "无框能量图案",
146
+ "constraints": { "text": false, "frame": false, "scene": false, "crop": false, "shadow": false },
147
+ "defaults": {
148
+ "preset": "centered",
149
+ "view": "正面",
150
+ "direction": "无方向",
151
+ "occupancy": 0.7,
152
+ "effectIntensity": "中",
153
+ "background": { "type": "solid", "color": "#FFFFFF" }
154
+ },
155
+ "allowedOverrides": {
156
+ "preset": ["centered"],
157
+ "view": ["正面"],
158
+ "direction": ["无方向"],
159
+ "occupancy": { "min": 0.6, "max": 0.8 },
160
+ "effectIntensity": ["中"]
161
+ },
162
+ "presets": { "centered": "主体居中,轨道穿插可读。" },
163
+ "checks": ["无文字和边框", "主体及轨道完整"]
164
+ }
165
+ ```
166
+
167
+ 任务示例的 energy 类别需要在推荐核心中声明,对应例子见 core-guidance.md。JSON 片段必须合并到对应文件,不把 profile、设计或后端片段当作完整用户配置。
package/docs/modes.md ADDED
@@ -0,0 +1,140 @@
1
+ # art 模式与调用规范
2
+
3
+ 本规范适用于通过 v-cli art、art-workshop 或 Node 入口调用的同一工具。示例后端 remote-qwen、local-qwen、local-custom、local-edit 是配置 ID;P、J、ITEM、TASK、RUN 为需替换的身份或路径。
4
+
5
+ ## 所有模式的共同检查
6
+
7
+ 1. 首次通过 v-cli 调用先读取 v-cli agent docs art 与 v-cli agent describe art --json,确认当前安装版本支持的命令与参数。
8
+ 2. config show 确认实际 config、workspace、output、refs;agent index 发现真实工程、任务及核心,不猜测 ID。
9
+ 3. config validate 校验配置和模板。检查全部后端失败时定位相应项;可用 --backend 只检查本次选择,其他后端问题不会因此修复。
10
+ 4. generate/edit show 读取任务。确认模块、核心选择、主体或原图、资产约束、尺寸、候选数与授权范围。
11
+ 5. 按对应模式检查依赖,再 plan 固化参数。运行 --plan 的 --dry 查看所选项请求,确认模型、size、seed、候选、输入图片和输出路径。
12
+ 6. 在已授权的任务范围内执行。首次验证选择一个 item/variant;--limit 按 item 数限制,不按实际图片数限制。
13
+ 7. 根据 taskId 跟踪结果,读取 manifest 与失败信息;生成成功后仍逐图人工验收。
14
+
15
+ 预演不会获得后续付费调用授权。已有明确生图或编辑授权时继续执行,不重复确认。冻结核心需要用户采用该报告的依据;不要把仅生成或查看报告当作采用。
16
+
17
+ ## 远程文生图
18
+
19
+ 远程使用 provider=bailian。art 将请求交给 bailian-cli,认证、区域和 Base URL 由该 CLI 配置管理;art 配置不保存 API Key,也没有 --api-key/--base-url 透传入口。BL_BIN 可指定 bailian-cli/dist/bailian.mjs 的真实 Node 文件,不是 .cmd/.ps1 shim。
20
+
21
+ 调用前检查:
22
+
23
+ - bl --help 与 bl image generate --help 确认入口及当前版本参数。
24
+ - bl auth status 确认模型 API 凭证;bl config show 确认生效配置与区域。不要在共享日志中输出完整密钥。
25
+ - art doctor --backend remote-qwen 仅检查 art 配置,不能证明认证、联网、额度或模型可用。当前百炼 CLI 没有 bl doctor 入口。
26
+ - 模型尺寸、数量等限制以服务端和当前模型为准;art 的 256~4096 通用像素检查不能替代模型能力检查。
27
+
28
+ ```powershell
29
+ bl image generate --help
30
+ bl auth status
31
+ bl config show
32
+ v-cli art config validate --backend remote-qwen
33
+ v-cli art generate show --project P --job J
34
+ v-cli art generate plan --project P --job J --backend remote-qwen --out .cache/remote-plan.json
35
+ v-cli art generate run --plan .cache/remote-plan.json --item ITEM --variant base --dry
36
+ v-cli art generate run --plan .cache/remote-plan.json --item ITEM --variant base --background
37
+ ```
38
+
39
+ 实际执行会发送提示词并可能产生费用。固定 seed 便于对照,但模型更新、采样实现和环境变化可能影响结果,不能承诺跨后端逐像素一致。
40
+
41
+ ## 本地内置文生图
42
+
43
+ 选择 provider=comfyui 且省略 workflow,或填 vant-builtin-qwen-image-2.1-Q4-8GB。内置 bindings 可省略;所需模型名和 API/UI 文件位置由 workflow list 返回。
44
+
45
+ 调用前检查:
46
+
47
+ - config validate 确认 endpoints 是显式本机 HTTP 根地址,launch 指向可用入口,模型与尺寸配置正确。
48
+ - doctor 检查 ComfyUI >=0.39.0、节点注册、模型枚举、连接输出索引和启动路径。未运行服务时可用 --start;检测后服务保留,不采样。
49
+ - workflow list 中的模型和插件必须已经安装;art 不安装依赖或下载权重。
50
+ - 内置 8GB 模板将文本编码器放在 CPU,512×512 为默认值;实际更大尺寸的显存、RAM和速度需任务验证。promptExtend、watermark 必须关闭;本地每边须为 32 的倍数。
51
+
52
+ ```powershell
53
+ v-cli art config validate --backend local-qwen
54
+ v-cli art workflow list
55
+ v-cli art doctor --backend local-qwen --start
56
+ v-cli art generate plan --project P --job J --backend local-qwen --out .cache/local-plan.json
57
+ v-cli art generate run --plan .cache/local-plan.json --item ITEM --dry
58
+ v-cli art generate run --plan .cache/local-plan.json --item ITEM --background
59
+ ```
60
+
61
+ 正常 run 自行复用服务或懒启动;doctor --start 用于提前验证,不是每次运行的必需步骤。未配置 launch 时,只能复用已经可用的服务。GPU 权重在首次采样时加载,HTTP 检测通过不代表权重能成功加载。
62
+
63
+ ## 本地自定义文生图
64
+
65
+ 自定义模板仍走 ComfyUI 适配器,不是任意推理引擎。workflow 指向 API JSON,必须声明 prompt/width/height/seed bindings。根据模板声明 negativePrompt/count/model,约束详见配置文档。
66
+
67
+ 调用前额外检查:
68
+
69
+ - 用 ComfyUI 的 API 格式导出,而非画布 nodes/links 格式。config validate 确认节点、连接及绑定存在。
70
+ - 输出须每次恰好一张最终图片,默认串行执行 perValue 个采样;不要同时让 batch_size>1 或多个 SaveImage 节点产生多个最终输出。
71
+ - doctor 读取环境中真实节点和选项。自定义节点的完整执行校验、必需输入类型或任意复杂逻辑仍由 ComfyUI 提交及执行决定。
72
+ - steps/cfg/sampler/scheduler 配置写入 seed binding 所在节点;该节点须具有相应输入,否则 plan 拒绝。
73
+
74
+ ```powershell
75
+ v-cli art config validate --backend local-custom
76
+ v-cli art doctor --backend local-custom --start
77
+ v-cli art generate plan --project P --job J --backend local-custom --out .cache/custom-plan.json
78
+ v-cli art generate run --plan .cache/custom-plan.json --item ITEM --dry
79
+ v-cli art generate run --plan .cache/custom-plan.json --item ITEM --background
80
+ ```
81
+
82
+ 修改模板、bindings、参数或核心后重新 plan。冻结计划保留工作流快照,不会自动读取磁盘上后来修改的模板。
83
+
84
+ ## 远程图编辑
85
+
86
+ 使用远程后端,额外检查 bl image edit --help,以及原图存在、可读并符合模型输入要求。source 是待编辑的底图;风格分析参考图不会自动加入编辑请求。
87
+
88
+ ```powershell
89
+ bl image edit --help
90
+ bl auth status
91
+ v-cli art config validate --backend remote-qwen
92
+ v-cli art edit show --project P --job J
93
+ v-cli art edit plan --project P --job J --backend remote-qwen --out .cache/remote-edit-plan.json
94
+ v-cli art edit run --plan .cache/remote-edit-plan.json --item ITEM --dry
95
+ v-cli art edit run --plan .cache/remote-edit-plan.json --item ITEM --background
96
+ ```
97
+
98
+ 必须明确 changes、preserve、mustRead,同一范围不能同时修改和保留。编辑默认保留原风格,不使用工程 defaultCore;若明确绑定 core,则不能再声明 style 修改或保留。原图哈希变化需重新 plan。
99
+
100
+ ## 本地 Qwen 2.1 图编辑
101
+
102
+ 当前本地图编辑适配的是 Qwen 2.1 参考图编码路径,每项仅一张底图;不是支持所有 ComfyUI 编辑图的通用适配器。内置文生图模板没有 image/vae 编辑绑定,不能直接作为默认编辑后端使用。
103
+
104
+ 创建 local-edit 自定义 API 模板及后端:image 绑定 LoadImage.image,vae 绑定 VAELoader.vae_name,prompt 绑定 TextEncodeQwenImage21.prompt。执行时上传原图,将编码器 images.image_1 和 vae 连接到相应节点。LoadImage 中原图占位文件无需预先存在,因为真正文件在任务执行时上传。
105
+
106
+ ```powershell
107
+ v-cli art config validate --backend local-edit
108
+ v-cli art doctor --backend local-edit --start
109
+ v-cli art edit show --project P --job J
110
+ v-cli art edit plan --project P --job J --backend local-edit --out .cache/local-edit-plan.json
111
+ v-cli art edit run --plan .cache/local-edit-plan.json --item ITEM --dry
112
+ v-cli art edit run --plan .cache/local-edit-plan.json --item ITEM --background
113
+ ```
114
+
115
+ dry 展示模板和动态参数但不上传原图,因此不显示服务器最终分配的上传文件名。输出 size 由 latent 尺寸控制;编码器 resolution 控制参考编码,不替代输出画布,也不保证原图比例自动保持。
116
+
117
+ ## 风格分析与核心冻结
118
+
119
+ style analyze 使用百炼 analysisModel;选择本地 generation 后端不会使分析转为本地。先检查 bl auth status 及 bl vision describe --help / bl text chat --help。纯语言输入调用文本分析,一张参考图调用视觉分析,多张图分别观察后合并;存在有效缓存时可复用报告。
120
+
121
+ ```powershell
122
+ bl auth status
123
+ bl vision describe --help
124
+ bl text chat --help
125
+ v-cli art style analyze --project P --input projects/P/briefs/style.json --dry
126
+ v-cli art style analyze --project P --input projects/P/briefs/style.json --out projects/P/reports/style.json
127
+ v-cli art style validate --project P --report projects/P/reports/style.json
128
+ # 用户已采用该报告,且无未解决冲突或不确定项时执行。
129
+ v-cli art style freeze --project P --report projects/P/reports/style.json
130
+ ```
131
+
132
+ 参考 path、scope、note 必须显式声明。报告中的主体、颜色、数量、布局和背景不能误冻为普遍风格。同步分析不返回 taskId,不受 task cancel 或 shutdown 管理。
133
+
134
+ ## 计划、数量与结果检查
135
+
136
+ variants 是同一需求的构图/seed 候选;perValue 是每个选中 item/variant 的出图张数(1~4)。预计图片数等于选中组合数乘对应 perValue。--limit/--offset 按独立 item ID 计数。run 默认 base;新计划来源调用可用 --explore 展开候选;冻结计划运行只能按 --variant 选择,不能加 --explore。
137
+
138
+ 运行冻结计划时可以设置 --item、--variant、--offset、--limit、--dry、--background 及输出路径,但禁止同时覆盖 --backend、--project、--job、--core、--explore。--timeout 只用于 task wait,不设置模型任务超时;ComfyUI 采样超时在 backend.options.timeoutSeconds。
139
+
140
+ 每种模式都须核对 planHash、后端、每项 execution、refs 和候选选择。失败读取 diagnostic 与日志;成功进入 check 的 content/style/asset 人工验收,不能只看 CLI 退出码。