@kevlns/art-workshop 0.2.1 → 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 (58) hide show
  1. package/AGENTS.md +24 -51
  2. package/README.md +31 -93
  3. package/art-workshop.mjs +69 -25
  4. package/docs/commands.md +913 -80
  5. package/docs/configuration.md +33 -139
  6. package/docs/core-guidance.md +7 -7
  7. package/docs/data-formats.md +14 -152
  8. package/docs/deployment.md +40 -0
  9. package/docs/model-architecture.md +52 -0
  10. package/docs/modes.md +15 -116
  11. package/docs/remote-models.md +42 -0
  12. package/docs/troubleshooting.md +30 -68
  13. package/lib/adapters/dashscope.mjs +234 -0
  14. package/lib/adapters/index.mjs +28 -0
  15. package/lib/agent.mjs +2 -2
  16. package/lib/analysis-worker.mjs +25 -0
  17. package/lib/analyze.mjs +8 -8
  18. package/lib/backends.mjs +350 -74
  19. package/lib/bl.mjs +3 -18
  20. package/lib/candidates.mjs +82 -0
  21. package/lib/comfyui.mjs +10 -8
  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/dimensions.mjs +22 -0
  27. package/lib/edit.mjs +6 -3
  28. package/lib/environments.mjs +67 -0
  29. package/lib/execution/remote.mjs +156 -0
  30. package/lib/executor.mjs +10 -24
  31. package/lib/generate.mjs +9 -5
  32. package/lib/generation-policy.mjs +198 -0
  33. package/lib/images.mjs +10 -0
  34. package/lib/lifecycle.mjs +40 -0
  35. package/lib/migration.mjs +154 -0
  36. package/lib/model-catalog.mjs +288 -0
  37. package/lib/model-registry.mjs +234 -0
  38. package/lib/plan.mjs +98 -28
  39. package/lib/project.mjs +13 -4
  40. package/lib/providers.mjs +27 -22
  41. package/lib/refs.mjs +12 -16
  42. package/lib/runtime.mjs +6 -4
  43. package/lib/service.mjs +45 -4
  44. package/lib/settings.mjs +2 -4
  45. package/lib/style-lifecycle.mjs +72 -0
  46. package/lib/task-references.mjs +35 -0
  47. package/lib/task-worker.mjs +225 -50
  48. package/lib/tasks.mjs +440 -63
  49. package/lib/templates.mjs +69 -0
  50. package/lib/transport/cli.mjs +69 -0
  51. package/lib/transport/http.mjs +82 -0
  52. package/lib/vision.mjs +46 -0
  53. package/lib/workflows.mjs +10 -1
  54. package/lib/workspace.mjs +190 -0
  55. package/package.json +9 -3
  56. package/skills/art-workshop/SKILL.md +27 -54
  57. package/v-cli.plugin.json +1257 -143
  58. package/docs//351/227/256/351/242/230/346/212/245/345/221/212-2026-10-08.md +0 -29
@@ -1,166 +1,60 @@
1
- # art 统一配置
1
+ # 配置与存储
2
2
 
3
- 配置是用户级结构化 JSON,远程与本地后端共用一份文件。工具配置只定义执行与资源路径;工程任务和冻结核心保持独立文件,认证由百炼 CLI 管理。
3
+ ## 配置入口
4
4
 
5
- ## 位置与覆盖
5
+ `config path/show/init/validate` 分别查询位置、生效配置、创建模板和校验。`config init` 不覆盖已有文件。查询、发现和预演不创建参考目录;`config validate` 不联网、不启动服务。
6
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
- ```
7
+ 配置位置优先级为 CLI `--config`、`ART_WORKSHOP_CONFIG`、`<VANT_HOME 或 ~/.vant>/tools/art-workshop/config.json`。资源路径优先级为 CLI 路径选项、配置 paths、默认路径。配置文件和资源均须位于工具安装目录之外。
8
+
9
+ | 字段 | 职责与默认值 |
10
+ | --- | --- |
11
+ | paths.workspace | 默认 ~/.vant/tools/art-workshop/workspace,保存 projects 和 .runtime |
12
+ | paths.output | 默认与 workspace 相同;执行批次与候选产物根 |
13
+ | paths.refs | 默认 workspace/refs,素材导入基准;不是对象的权威参考目录 |
14
+ | paths.cache | 默认 workspace/.cache,分析等缓存 |
15
+ | execution | 全局执行默认值,具体范围由所选模型策略校验 |
16
+ | generation | defaultBackend、defaults、backends |
17
+ | analysisModel | 分析模型默认值,连接仍需单独就绪 |
18
+ | defaultProject | 未传 --project 时的工程 ID,不跨工程回退 |
19
+ | autoSyncSkills | 默认 true;实际分析、采用、运行入口可刷新随包技能,查询与 dry 不刷新 |
13
20
 
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。
21
+ Vant 显式传入绑定,把工程对象、参考、批次及图片集中在工程 `.vant/art`。独立 CLI 默认 workspace 可以容纳多个工程,不自动绑定当前 Git 工程。普通输入、计划和报告相对路径以 workspace 为基准;`check RUN` 相对批次以 output 为基准。参考源文件建议提供绝对路径。
15
22
 
16
- --config FILE 优先于 ART_WORKSHOP_CONFIG;未指定则使用默认位置。工作流、launch.executable 与 launch.cwd 的相对路径基于配置文件目录。资源目录建议写绝对路径:paths 中相对值实际按当前工作目录解析,不按 config.json 目录解析。
23
+ ## 后端配置
17
24
 
18
- ## 一份远程与本地配置
25
+ 远程 provider 为后端类别标识;执行协议来自 credentialReference.api,缺省 DashScope。协议必须已注册,型号必须在该协议目录中精确登记且支持所需模式。provider 名称不是权限或协议兼容性的证明。
19
26
 
20
- 以下是合法结构示例;路径、模型和后端 ID 需与本机安装匹配。
27
+ 下面仅示例结构,不含凭据。具体参数以 [适配目录](remote-models.md) 和生成预演为准。
21
28
 
22
29
  ```json
23
30
  {
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
31
  "generation": {
35
- "defaultBackend": "local-qwen",
36
- "defaults": { "perValue": 1, "promptExtend": false, "watermark": false },
32
+ "defaultBackend": "remote-image",
37
33
  "backends": {
38
- "remote-qwen": {
34
+ "remote-image": {
39
35
  "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
- }
36
+ "model": "qwen-image-2.0-pro",
37
+ "execution": { "size": "1024*1024", "perValue": 1, "watermark": false }
56
38
  }
57
39
  }
58
40
  }
59
41
  }
60
42
  ```
61
43
 
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 后端字段
44
+ ComfyUI 后端使用 provider=comfyui,声明 model、endpoints,以及可选 workflow、bindings、options、launch。省略 workflow 使用随包固定方案;自定义工作流必须是 API JSON,bindings 指向真实节点输入。endpoints 只允许本机 HTTP 根地址。launch 明确 executable/cwd/args;工具以 argv 启动,不拼接 shell。详情见 [本地部署](deployment.md)。
102
45
 
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
- ```
46
+ ## 认证与实例
139
47
 
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 连接 |
48
+ Vant 系统模型配置统一保存 Provider 实例及凭据,工程只引用实例身份、修订及不含密钥的连接信息。模板只负责预填新实例,不是独立可执行连接。模型目录发现、能力登记、启用与账号权限是不同事实。
148
49
 
149
- 节点 ID 和 input 名是执行映射,中文 title 只用于展示。options 的采样参数写入 seed 所在节点,因此需要对应输入。每次请求复制模板,动态填提示词、尺寸、seed;不修改原模板。perValue 次请求串行执行,seed 依次为初始 seed+index,要求每次恰好输出一张最终图片。
50
+ 远程图片由组织层通过 ART_IMAGE_CONNECTION(api/baseUrl)和 ART_IMAGE_KEY 注入内存;明确连接缺少密钥时拒绝,不能回退另一份密钥或站点。独立 DashScope 使用固定版本百炼核心库的既有认证来源。
150
51
 
151
- Qwen 2.1 编辑模板额外加入 LoadImage,并声明 image/vae bindings;编辑时适配器连接 TextEncodeQwenImage21 的 images.image_1 与 vae。模板编码器 resolution=1024 是参考编码参数,不是输出宽高;EmptyLatentImage 的动态 size 决定采样画布。
52
+ 视觉分析独立使用 ART_VISION_CONFIG 与 ART_VISION_KEY,支持 openai-completions、openai-responses、anthropic-messages、google-generative-ai。未注入连接时分析走百炼 CLI。不要把图片输出模型当作视觉分析模型;分析要求图片输入和文字输出。
152
53
 
153
- ## 路径与持久化检查
54
+ 凭据不进入工程、计划、运行回执、日志或命令行。Token Plan 与按量渠道保留各自实例地址和密钥,不跨渠道回退。配置校验不证明凭据有效、模型授权或实际出图。
154
55
 
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 目录覆盖 | 当前工作目录;建议使用绝对路径 |
56
+ ## 状态与共享环境
163
57
 
164
- --workspace、--output-dir、--refs-dir、--cache-dir 临时覆盖目录。参考目录顺序为显式 --refs-dir、工程 refsDir、用户 paths.refs。任务状态、锁和服务日志存于 config.json 旁 .runtime/<配置路径哈希>;该目录不是 workspace 的分析缓存。
58
+ 对象变更锁和执行登记归 workspace/.runtime;更换配置文件不产生另一套占用。共享服务登记归用户数据根的 state/art-services,环境索引、接入日志和证据归 state/art-environments。安装根保存模型、程序与 vant.art.config.json,不再新建 .vant-art 控制目录。
165
59
 
166
- config validate 不执行节点、不探测 HTTP,也不检查全部工程文件。doctor 检查环境;plan 校验具体任务和参数;run --dry 校对具体请求;真实运行验证模型可执行性。通过某一层不能省略后续层的模式要求。
60
+ 旧工程仅通过显式 project upgrade 备份转换;旧用户目录或环境状态不能靠文档重命名完成迁移。迁移与异常边界见 [数据结构](data-formats.md) 和 [诊断](troubleshooting.md)。
@@ -16,7 +16,7 @@
16
16
 
17
17
  1. 一条规则表达一个可执行判断,去掉同义重复和无助于生成的修辞。
18
18
  2. 视觉术语明确;强度、数量、颜色、范围有明确字段,避免互斥渲染机制。
19
- 3. 推荐、冻结、正向提示词、负向约束与验收从同一结构生成,前后一致。
19
+ 3. 推荐、冻结、正向提示词、负向约束与定版时的审查依据来自同一结构,前后一致。
20
20
  4. 核心只拥有视觉语言;具体主体、布局、背景、模型、尺寸不得混入核心。
21
21
  5. 一个事实只有一个权威字段;不再追加另一段冻结 styleBlock 覆盖结构化核心。
22
22
  6. domains 规则明确作用于实体类别;表面科幻处理不等于给所有主体套同一结构。
@@ -29,11 +29,11 @@ style validate 检查结构、枚举、已定义语义矛盾、语言长度和
29
29
  ```powershell
30
30
  v-cli art style validate --project P --report projects/P/reports/style.json
31
31
  # 已有用户采用报告的依据后执行。
32
- v-cli art style freeze --project P --report projects/P/reports/style.json --note "采用已审阅的推荐风格"
32
+ v-cli art style adopt --project p --id style-id --revision 2 --note "采用已审阅的推荐风格"
33
33
  v-cli art style show --project P --core style
34
34
  ```
35
35
 
36
- freeze 会写核心并更新 project.cores;没有 defaultCore 时可设为新核心。需要第二套风格时使用新的报告/核心 ID,不复制冻结文件改身份。
36
+ style adopt 校验当前报告后原子写核心并更新 project.cores;没有 defaultCore 时可设为新核心。需要第二套风格时派生新草稿,重新分析和采用,不复制冻结文件改身份。
37
37
 
38
38
  ## 生图时的核心检查
39
39
 
@@ -41,7 +41,7 @@ freeze 会写核心并更新 project.cores;没有 defaultCore 时可设为新
41
41
 
42
42
  图编辑默认保留原图风格,不读取 defaultCore。明确绑定目标 core 时,style 的修改或保留由核心负责,任务不再重复声明。
43
43
 
44
- 换远程/本地后端只改变执行能力,不自动改核心或需求。同一提示词在不同模型上的表现可能不同,必须按 content/style/asset 分别审查。
44
+ 换远程/本地后端只改变执行能力,不自动改核心或需求。同一提示词在不同模型上的表现可能不同,定版时需结合实际内容、风格和资产用途判断;工具不设置评分字段或人工验收门槛。
45
45
 
46
46
  ## 风格变化的对照
47
47
 
@@ -49,13 +49,13 @@ freeze 会写核心并更新 project.cores;没有 defaultCore 时可设为新
49
49
 
50
50
  ```powershell
51
51
  v-cli art compare .cache/old-plan.json .cache/new-plan.json
52
- v-cli art check RUN --out .cache/review.json
52
+ v-cli art check RUN
53
53
  ```
54
54
 
55
- 只有产物完整、生成成功且 content/style/asset 全部 pass 才可 select。规则检查、模型成功返回或生成缩略图都不能单独作为生产资产验收。
55
+ check 核验产物完整性、生成成功事实、文件哈希和计划归属。用户可通过 candidate finalize 定版;没有人工评分门槛。定版记录表示用户选择,不声称产物已经集成或符合游戏运行要求。
56
56
  ## 推荐核心结构示例
57
57
 
58
- 以下是报告 recommendation 的合法结构示例,与 data-formats.md 的 energy 类别配套。它不是已冻结文件,仍需依据实际证据产生报告、审阅并 freeze;不要人为补 coreHash 绕过流程。
58
+ 以下是报告 recommendation 的合法结构示例,展示 energy 类别的风格处理。它不是已冻结文件,仍需依据实际证据产生报告、审阅并 style adopt;不要人为补 coreHash 绕过流程。
59
59
 
60
60
  ```json
61
61
  {
@@ -1,167 +1,29 @@
1
1
  # art 工程与输入结构
2
2
 
3
- 所有工程数据放在配置的 workspace。工具只随包发布规则、指南和内置工作流,不随包发布用户工程、模型权重或图片。
3
+ ## 工程和对象
4
4
 
5
- ## 工程布局
5
+ project.json 必须声明 schemaVersion=2、revision、id、name、analysisModel、execution、cores、defaultCore。工程身份与目录匹配,核心必须属于同一工程。
6
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
- ```
7
+ projects/<projectId>/styles/<styleId>/style.json 与 tasks/<taskId>/task.json 使用 schema=art-workshop/style 或 art-workshop/task,schemaVersion=2、稳定 id、project、展示 name、revision、status、createdAt/updatedAt、config、references 和 report。正式风格的 core.json 不可原地覆写。任务的 config.kind 是 generate/edit,不能改身份与类型。
18
8
 
19
- project.json 的最小结构示例:
9
+ 参考记录包括 id、所属对象、私有相对 path、SHA256、来源、category/purposes、usage、note、ignore。风格四类:style、palette、shape-language、rendering。任务用途:subject、composition、pose、identity-color、surface、scene-light、text。sources 只放编辑底图。
20
10
 
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
- ```
11
+ ## 需求与计划
31
12
 
32
- 实际 ID(示例 demo)必须与目录名一致,使用小写字母、数字、连字符。新工程先分析并冻结自己的核心,不能复制冻结文件修改身份。cores 可包含多核心,defaultCore 为成员 ID 或 null;没有默认值时明确选核心。refsDir 是可选工程参考目录。
13
+ 生成 config 包括 project、kind、core、execution、items,以及互斥的 profile 或内联 asset 规格;实体及效果有稳定 id、数量、颜色、角色与关系。具体主体、构图、动作不冻结进风格。规格定义资产约束、设计基准与检查要点,内联规格属于当前任务,编译时形成同一不可变快照。编辑 config 的 items 明确 source、changes、preserve、mustRead、seed。
33
14
 
34
- ## 风格分析输入
15
+ plan 包括 schema=art-workshop/plan、module/project/job、sources、snapshots、refs、execution、items、planHash。sources 绑定 taskRevision、taskConfigHash 和 coreHash;项目/核心/profile/任务形成快照。项含 inputHash、实际尺寸和 seed。任何来源或哈希变化拒绝运行。
35
16
 
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
- ```
17
+ ## 执行与定版
47
18
 
48
- refs 可为空;有参考时 path 指向可读图片,scope 仅允许 style/palette/shape/render,note 描述观察边界。style、palette、subject、composition、material、text、pose 分类目录仅帮助整理,不自动绑定图片;分析 scope 与目录名不是同一组枚举。
19
+ 对象 taskId(命令中称 job/id)与执行 taskId 是两种身份;每次真实执行有独立登记。运行记录包含 queued/running/cancelling/succeeded/failed/cancelled/unknown、heartbeat、workerPid、后端身份、manifestPath、stopConfirmed 与 unsettled。终态与停止证据独立;没有停止证据继续占用对象。配置状态及界面分组不能取代运行身份。
49
20
 
50
- 报告包含 observations、recommendation、conflicts、uncertainties 和 provenance。recommendation 的完整合法结构由核心规则和分析请求提供;用 style validate 检查后审阅,解决冲突和不确定项,再经用户采用 freeze。冻结文件带身份与哈希,不手写或原地修改。
21
+ manifest 保存计划、每项输出及哈希、失败证据和完成事实。候选身份绑定运行、资产、构图与文件。定版记录保留资产、候选、批次、哈希、操作者与时间;替换与删除进入历史。删除先记录事实,物理清理可重试。
51
22
 
52
- ## 文生图任务
23
+ 远程计划项的 request 使用 art/image-request-v1,executionContract 使用 art/execution-contract-v1。执行记录 remoteExecutions[inputHash] 保存 art/remote-receipt-v1,状态为 dispatching/accepted/completed/failed/cancelled;包含适配器版本、requestHash、baseUrl 及可用的 taskId/urls。dispatching 先于提交,accepted 先于轮询,completed 先于下载;不含密钥。具体字段以 lib/contracts.d.ts 及编译结果为准,不手工拼装执行回执。
53
24
 
54
- 任务顶层允许 project/kind/core/profile/execution/items。以下示例假定已存在工程核心 style 和 profile icon;不是无需准备即可运行的工程。
25
+ task recover 根据工程和 operationId 找回唯一原执行;task resume 沿用原执行和 manifest,仅处理已有上游身份。retry-run 则创建新批次并记录 retryOf。三种身份流不能混用,详见 [任务控制](troubleshooting.md)。
55
26
 
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
- ```
27
+ 旧格式只通过 project upgrade 显式转换,有备份与原子替换;共享图片须人工映射,不能猜测后删除。
80
28
 
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、设计或后端片段当作完整用户配置。
29
+ 升级事务登记在 workspace/.runtime/upgrades/<projectId>.json。替换中断后只通过显式 project upgrade 恢复原备份并重新转换;日常读写拒绝未完成事务。编辑源导入新对象私有 sources;历史快照保留旧事实。历史同资产多次批准须在 mapping 的 selections 中提供 task/assetId/runId/file/variantId,明确当前正式选择,其余保留替换历史,不猜测最近一张。
@@ -0,0 +1,40 @@
1
+ # 本地环境检测与部署
2
+
3
+ 固定自动安装方案由 lib/deployment.mjs 的 LOCAL_RECIPE 维护:ComfyUI、GGUF 节点、Python/Torch 依赖以及三个模型的准确版本和 SHA256。自动部署当前只适配 Windows NVIDIA 环境;已有便携 Python 可复用,新建 venv 需要可用的 Python >=3.12。
4
+
5
+ ## 目录与端口
6
+
7
+ Vant 检测窗口默认安装目录为 `<VANT_HOME 或 ~/.vant>/art-env`,允许选择其他目录及本机可用端口。已有便携安装应选择包含 ComfyUI 和 python_embeded 的根目录,而不是 models、ComfyUI 子目录或旧 .vant-art。
8
+
9
+ 空目录输入时,组织层可用 discoverInstallations 读取环境索引,并在默认目录、用户 AI 目录及 Windows C:/AI、D:/AI、E:/AI 有界扫描环境标记和 ComfyUI。扫描有深度和数量预算,不是全盘检索。独立 CLI deployment plan 必须明确 --directory,不会自行执行界面的自动选择逻辑。
10
+
11
+ 端口自动选择只证明检测时可绑定,不预约端口。目录或端口变更后重新检测,确认的地址随环境保存;实际启动仍可能因端口被其他程序占用而失败。不能把其他进程监听同一端口视为此目录的环境。
12
+
13
+ ## 已有环境复用
14
+
15
+ 1. 检查 Python、ComfyUI、GGUF 节点、固定模型文件及大小,检查生成与编辑工作流的实际节点能力和端口归属。
16
+ 2. 对可复用但未登记环境,adoptInstallation 流式验证模型 SHA256,连接或启动对应服务,核验能力后写入标记及用户环境索引。保留原模型;不因未登记而再次下载整套环境。
17
+ 3. 接入检测的 verification=capabilities 只代表环境和工作流能力验证。新部署产生的真实生成、编辑验证图是另一等级证据,不能混称。
18
+ 4. 缺文件或版本不符时展示具体差异。固定部署不自动覆写不匹配源码、模型或用户安装;先明确处理差异,再生成新预案。
19
+
20
+ ## 独立 CLI 流程
21
+
22
+ 以下示例使用已核对的安装目录与端口;启动前必须有部署、下载及验证采样的任务授权。
23
+
24
+ ```sh
25
+ v-cli art deployment plan --directory C:/AI/ComfyUI_windows_portable --endpoint http://127.0.0.1:8188/ --out deployment.json
26
+ v-cli art deployment start --plan deployment.json --operation local-deploy-001
27
+ v-cli art deployment status --id DEPLOYMENT
28
+ v-cli art deployment cancel --id DEPLOYMENT
29
+ v-cli art deployment recover --operation local-deploy-001
30
+ ```
31
+
32
+ plan 检测 GPU、Python、文件与磁盘,不下载、不启动、不采样;现有文件存在不等于哈希已验证。start 复核冻结预案后创建后台 deploymentId,逐阶段记录实际进度,按固定方案安装、校验、生成与编辑采样;完成后才提交配置。下载或校验失败不覆写既有冲突文件。
33
+
34
+ status 查询原部署。cancel 只停止已核验的本部署进程与采样,不删除用户素材或原模型,不关闭用户先前启动的服务。recover 只找回唯一原登记,不重复安装。工作进程丢失或停止未确认时保留 unknown 与安装占用。
35
+
36
+ ## 存储与关闭
37
+
38
+ 安装根保存程序、模型和 vant.art.config.json;环境索引、受管服务身份、日志和验证证据归 ~/.vant/state。项目生图归工程绑定的 .vant/art,不能写入共享模型环境。
39
+
40
+ Vant 退出使用其应用生命周期清理关联后台任务,并关闭可核验为 Vant 启动的 ComfyUI,确认本机端口释放。单独关闭部署窗口不取消部署。CLI shutdown 的工作区与共享服务边界见 [任务控制](troubleshooting.md)。
@@ -0,0 +1,52 @@
1
+ # 模型与执行架构
2
+
3
+ 模型扩展不修改任务调度和界面判断。未知型号、未知协议、无效响应都明确失败;提交结果未知时禁止重复提交。
4
+
5
+ | 模块 | 职责 |
6
+ | --- | --- |
7
+ | `lib/model-catalog.mjs` | 模型型号、输入输出能力、参数规则、尺寸、协议操作和展示说明 |
8
+ | `lib/model-registry.mjs` | 启动时验证并索引定义;提供执行契约及统一资格判断 |
9
+ | `lib/generation-policy.mjs` | 校验、规范化请求、记录参数转换、冻结和复核执行契约 |
10
+ | `lib/adapters/` | 协议登记、准备输入、序列化、提交、查询、响应解析 |
11
+ | `lib/execution/remote.mjs` | 持久化回执后轮询、取消等待、恢复原任务、下载原结果 |
12
+ | `lib/transport/` | 有界 HTTP/JSON 与 CLI 子进程,不承载模型判断 |
13
+
14
+ 界面与配置保存共用 `modelEligibility`。接口类型列表由适配器注册表提供;模型发现只补齐准确型号的声明能力,不推定账号权限或自动启用。
15
+
16
+ ## 扩展规则
17
+
18
+ 同协议新模型增加完整模型定义与契约测试。字段规则描述类型、默认值、范围或枚举及协议字段名;参数不再受全局固定白名单限制。模型声明在启动时检查重复标识、必要限制和协议字段。
19
+
20
+ 新协议实现 `prepare / submit / query`,通过 `createAdapterRegistry` 登记。同步提交返回完成结果;异步提交返回上游任务身份。界面、任务运行时不包含型号名称分支。输入文件限制由模型声明提供。
21
+
22
+ `art/model-contract-v1` 排除型号别名列表、展示说明、来源链接及 CLI 示例字段;这些文案变化不改变执行哈希。`art/image-request-v1` 保存规范化请求,`art/execution-contract-v1` 冻结逐项契约。请求参数、尺寸、转换策略或协议规则变化必须重新预演。没有当前执行契约的旧预案不能启动。
23
+
24
+ ## 生命周期
25
+
26
+ 每个计划项分别保存 `remoteExecutions[inputHash]`,包括 schema=art/remote-receipt-v1、请求哈希、适配器及版本、服务地址、提交时间、上游任务 ID 和结果。回执不保存 API Key。
27
+
28
+ 1. `prepare` 先检查凭据与输入,不发起生成。
29
+ 2. 持久化 `dispatching` 后才能 POST。
30
+ 3. 持久化 `accepted + taskId` 后才能查询。
31
+ 4. 持久化 `completed + urls` 后才能下载。
32
+ 5. 下载采用临时文件和排他发布,不覆盖已有不同内容的产物。
33
+
34
+ 提交中断而无任务 ID 的运行保持未知,不能重发。取消等待不等于上游取消;适配器没有停止能力时保留任务身份和占用。
35
+
36
+ ```sh
37
+ v-cli art task resume TASK
38
+ ```
39
+
40
+ `task resume` 仅恢复原上游任务查询或原结果下载,不调用提交接口,也不补发尚未提交的项目。已有成功产物跳过;参数及请求身份不同、原工作进程仍活着、原提交结果未知均拒绝恢复。恢复沿用 taskId、manifest 和每项输入哈希。
41
+
42
+ 上游已完成而本地下载失败时,恢复原运行取回结果,不能通过失败项重试再次付费生成。原运行查询入口 `task recover --operation` 仍只查登记,不隐式启动工作进程。
43
+
44
+ Vant 通过 `ART_IMAGE_CONNECTION` 和 `ART_IMAGE_KEY` 注入连接,不绑定厂商命名。单独使用 DashScope 时,适配器通过固定版本的百炼核心库读取既有 API Key 配置;明确注入连接后不回退到其他凭据或站点。
45
+
46
+ ## 验证边界
47
+
48
+ 单元与协议模拟验证声明扩展、统一筛选、严格响应和回执顺序;真实子进程测试验证工作进程丢失及取消后恢复,统计生成 POST 次数不增加。上述验证不等同于付费模型真实出图或已安装版本更新。
49
+
50
+ 新模型至少覆盖合法请求、参数边界、模式和输入拒绝;新协议还需覆盖提交结果未知、持久化失败、按原身份恢复、取消及下载失败。HTTP 响应体、下载大小和时间有界;认证请求禁止重定向,下载不携带模型密钥。当前查询异常保留身份并停止等待,不自动重试查询或提交。
51
+
52
+ [适配目录](remote-models.md) · [任务控制](troubleshooting.md) · [配置](configuration.md)