@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
package/docs/modes.md CHANGED
@@ -1,140 +1,39 @@
1
- # art 模式与调用规范
1
+ # 模式与调用流程
2
2
 
3
- 本规范适用于通过 v-cli art、art-workshop 或 Node 入口调用的同一工具。示例后端 remote-qwen、local-qwen、local-custom、local-edit 是配置 ID;P、J、ITEM、TASK、RUN 为需替换的身份或路径。
4
-
5
- ## 所有模式的共同检查
3
+ ## 风格分析与核心冻结
6
4
 
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 与失败信息;生成成功后仍逐图人工验收。
5
+ 创建风格草稿,按 style、palette、shape-language、rendering 分类导入私有参考。style analyze --dry 只编译;实际 analyze 创建 taskId 和独立证据。报告绑定配置版本、图片哈希、分析模型和规则指纹;更新配置或参考后必须重新分析。冲突与未知项未处理时不能采用。
14
6
 
15
- 预演不会获得后续付费调用授权。已有明确生图或编辑授权时继续执行,不重复确认。冻结核心需要用户采用该报告的依据;不要把仅生成或查看报告当作采用。
7
+ style adopt 冻结当前已审阅报告;style recover 只恢复原已授权采用事务。正式风格只读,修改使用 derive,不能复制文件改身份。任务动态参考用 job analyze,只转写指定内容用途,不替代静态风格。
16
8
 
17
9
  ## 远程文生图
18
10
 
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
- 调用前检查:
11
+ 选择已启用、目录可用、保存凭据且已适配的图片模型。先 generate show,再 generate plan 保存计划,run --plan --dry 核对请求,再按授权执行。生成 API 由协议适配器直接调用;CLI 示例仅为诊断,不是实际提交链路。
22
12
 
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 便于对照,但模型更新、采样实现和环境变化可能影响结果,不能承诺跨后端逐像素一致。
13
+ 型号的生成/编辑模式、输入数量、尺寸、提示词与参数限制统一来自 [模型目录](remote-models.md)。不能把 URL+Key 或 image 标签视为已经适配;不能以注册型号推定账号权限。
40
14
 
41
15
  ## 本地内置文生图
42
16
 
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 检测通过不代表权重能成功加载。
17
+ ComfyUI 后端省略 workflow 时使用 Qwen Image 2.1 Q4 与 CPU 文本编码器。config validate 校验模板,doctor 检查服务、节点与模型;doctor --start 可启动并保留服务,不采样。plan/dry 不启动服务。内置工作流不证明模型文件、节点和显存已就绪。
62
18
 
63
19
  ## 本地自定义文生图
64
20
 
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。冻结计划保留工作流快照,不会自动读取磁盘上后来修改的模板。
21
+ CLI 支持显式 API workflow 与 bindings,调用方负责节点、参数、输入图、数量、输出与生命周期适配。Vant 当前只开放已适配内置方案,不把任意工作流导入作为可运行选择。
83
22
 
84
23
  ## 远程图编辑
85
24
 
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
- ```
25
+ 显式绑定 source 及哈希,声明 changes、preserve 和 mustRead。修改与保留不能冲突。默认保留原图风格;绑定目标 core 后不再重复声明修改或保留 style。必须使用支持 edit 的准确型号,不能套用文生图端点。
97
26
 
98
- 必须明确 changes、preserve、mustRead,同一范围不能同时修改和保留。编辑默认保留原风格,不使用工程 defaultCore;若明确绑定 core,则不能再声明 style 修改或保留。原图哈希变化需重新 plan。
27
+ 上传、提交、查询和下载使用冻结请求。上游身份保存在原运行,恢复仅查询原任务或取回原结果,不重新提交。
99
28
 
100
29
  ## 本地 Qwen 2.1 图编辑
101
30
 
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 管理。
31
+ 使用适配后的 LoadImage.image、VAE 和图像编码器连接,底图上传后显式绑定。latent 输出尺寸与编码器 resolution 分开。服务可连接不等于真实编辑成功,验证需实际底图和输出。
133
32
 
134
- ## 计划、数量与结果检查
33
+ ## 生成与定版
135
34
 
136
- variants 是同一需求的构图/seed 候选;perValue 是每个选中 item/variant 的出图张数(1~4)。预计图片数等于选中组合数乘对应 perValue。--limit/--offset 按独立 item ID 计数。run 默认 base;新计划来源调用可用 --explore 展开候选;冻结计划运行只能按 --variant 选择,不能加 --explore。
35
+ 前台和后台真实运行均登记 taskId。候选必须有可核验计划、运行身份和完整文件。check 仅做技术完整性检查,candidate finalize 记录用户选择;没有人工三维评分或「验收此图」阶段。
137
36
 
138
- 运行冻结计划时可以设置 --item、--variant、--offset、--limit、--dry、--background 及输出路径,但禁止同时覆盖 --backend、--project、--job、--core、--explore。--timeout 只用于 task wait,不设置模型任务超时;ComfyUI 采样超时在 backend.options.timeoutSeconds。
37
+ 按资产定版,重复请求幂等;替换用 --replace 并保留历史。candidate delete 用 --confirm 明确影响,拒绝运行中或受引用文件。定版不会自动导入游戏或提交 Git。
139
38
 
140
- 每种模式都须核对 planHash、后端、每项 execution、refs 和候选选择。失败读取 diagnostic 与日志;成功进入 check 的 content/style/asset 人工验收,不能只看 CLI 退出码。
39
+ 空闲任务可更新配置后重新编译运行,原批次保留。派生任务独立建立身份,不继承报告、授权、执行或定版。[全部命令](commands.md) · [取消与恢复](troubleshooting.md)
@@ -0,0 +1,42 @@
1
+ # 远程图片适配与筛选
2
+
3
+ 型号、能力、参数与支持状态的唯一事实源是工具内部 lib/model-catalog.mjs;lib/model-registry.mjs 提供准确查找和统一资格判断。Vant 展示登记目录,不维护第二份模型清单。
4
+
5
+ ## 已适配范围
6
+
7
+ | 模型 | 模式 | 总像素范围 | 输入与主要限制 |
8
+ | --- | --- | --- | --- |
9
+ | Qwen Image 2.0 / Pro | generate、edit | 512²–2048² | 编辑 1–3 图;编辑尺寸 16 对齐;负向词最多 500 字符;正向词官方上限 1300 Token |
10
+ | Qwen Image 3.0 / Pro | generate、edit | 512²–2048² | 编辑 1–3 图;负向词最多 500 字符 |
11
+ | Wan 2.7 | generate、edit | 768²–2048² | 编辑 1–9 图;比例 1:8–8:1 |
12
+ | Wan 2.7 Pro | generate、edit | 无图生成 768²–4096²;带图最高 2048² | 编辑 1–9 图;比例 1:8–8:1 |
13
+ | wan2.6-t2i | 仅 generate | 1280²–1440² | 无输入图;比例 1:4–4:1;16 对齐;异步任务 |
14
+ | wan2.6-image | 仅 edit | 768²–2048² | 1–4 图;比例 1:4–4:1;16 对齐;不开放流式图文混排 |
15
+
16
+ 准确标识包括 qwen-image-2.0、qwen-image-2.0-pro、qwen-image-3.0、qwen-image-3.0-pro、wan2.7-image、wan2.7-image-pro,以及 2.0-2026-03-03、2.0-pro-2026-03-03/04-22/06-22 快照。快照使用完整 qwen-image- 前缀,不靠前缀通配放行未来型号。
17
+
18
+ 工具共同边界为单边 256–4096、每项 1–4 张、seed 0–2147483647;各模型额外限制取交集。尺寸在计划阶段选择最近合法值,记录请求、实际值和调整原因;设计任务保留设计基准。Token 数由服务端计算,不用字符数冒充。
19
+
20
+ Wan 2.7 不支持独立负向参数和提示词扩写开关:负向约束明确并入主提示词,合并后最多 5000 字符;显式开启 promptExtend 被拒绝。Wan 2.6 支持负向参数与扩写,主提示词最多 2000 字符、负向词最多 500 字符。不能把 2.7 限制推广到所有万相。
21
+
22
+ 预演与实际执行使用同一规范化请求。组图、框选、调色板和流式混排等未声明能力不自动开放,工具不承诺请求尺寸与服务端输出逐像素一致。
23
+
24
+ ## 仅登记与未知型号
25
+
26
+ 早期 Qwen Image/Max/Plus/Edit、Wan 2.5/2.2/2.1/2.0/V1 和 ImageEdit/Sketch/X-Painting 记录官方来源、支持状态及限制,不套用新型号协议执行。未精确登记的型号拒绝,不因名字相似自动推断支持。
27
+
28
+ modelCatalog() 返回工具登记,不是账号可用模型列表;resolveModel(api, model) 返回精确支持状态。注册不注入账号目录、不自动启用、不推定权限。
29
+
30
+ ## 统一筛选
31
+
32
+ modelEligibility 共用于界面与配置保存,按实例启用、目录可用、模型启用、已保存凭据、图片协议、图片输出能力和准确型号支持状态给出原因。只有 ID 的未知元数据可从已适配型号补能力;显式用户能力配置受到尊重,不能因此跳过协议和模型策略。
33
+
34
+ 视觉分析要求图片输入和文字输出,与图片生成筛选分开。具体执行还要校验 generate/edit 模式、输入数量、参数和尺寸;实例能够选中不保证每个任务都合法。
35
+
36
+ ## 协议、渠道与恢复
37
+
38
+ Token Plan 是订阅渠道,DashScope 是 API 协议。按量与订阅共用适配目录,但始终保留所选实例原地址及密钥,不切换站点,不推定套餐提供同等权限。请求采用 native DashScope 适配器,CLI 只是可选诊断示例。
39
+
40
+ 异步模型保存上游 taskId 后查询;同步模型保存完成 URL 后下载。取消只停止本地等待,恢复仅查询原身份和取回原结果。[生命周期](model-architecture.md) · [异常处理](troubleshooting.md)
41
+
42
+ 登记依据链接:[Qwen 2 生成](https://help.aliyun.com/zh/model-studio/qwen-image-api)、[Qwen 2 编辑](https://help.aliyun.com/zh/model-studio/qwen-image-edit-api)、[Wan 2.7](https://help.aliyun.com/zh/model-studio/wan-image-generation-and-editing-api-reference)、[Wan 2.6 文生图](https://help.aliyun.com/zh/model-studio/text-to-image-v2-api-reference)、[Wan 2.6 编辑](https://help.aliyun.com/zh/model-studio/wan-image-generation-api-reference)。本文说明当前代码登记范围,不声称远端账号已开通或本轮已真实付费出图。
@@ -1,84 +1,46 @@
1
- # art 诊断与任务控制
1
+ # 任务控制与诊断
2
2
 
3
- 检查分为全局配置、环境、任务编译、请求预演和真实执行五层。前一层通过不能代替后一层;HTTP 服务可达也不能证明 GPU 权重能加载或生成图片。
3
+ ## 先核对事实
4
4
 
5
- ## 配置和环境
5
+ 先 config validate,再 doctor;远程 doctor 只核对配置,不验证认证、账号授权或云端连通性。本地 doctor 默认不启动、不采样;--start 可启动并保留服务。真实生成仍须 plan/dry 和任务授权。
6
6
 
7
- ```powershell
8
- v-cli art config show
9
- v-cli art config validate
10
- v-cli art config validate --backend local-qwen
11
- v-cli art doctor --backend local-qwen
12
- v-cli art doctor --backend local-qwen --start
13
- ```
7
+ 技术检查不证明画面质量;mock 不证明模型真实出图;服务可连接不证明显存足够;包构建不证明安装及桌面交互通过。
14
8
 
15
- config validate 检查字段、模板格式、连接、bindings 和共享执行限制;不遍历所有工程。doctor 检查启动路径、ComfyUI 版本、节点、枚举中的模型和选项及输出索引;不执行全部自定义节点的任意校验逻辑。使用当前配置检查时,冻结任务可能有不同快照,须同时查看其 plan/manifest。
9
+ ## 状态与占用
16
10
 
17
- 仅指定本机 endpoints,不扫描局域网。doctor 不可达时默认退出 1 并提示 --start。--start 可能懒启动;启动失败看返回 issues、嵌套 diagnostic 和 .runtime 中服务日志,检查完可 shutdown。编辑图的 LoadImage 占位值跳过已有图片枚举检查,因为实际输入会上传。
11
+ task status 返回原运行阶段、心跳、工作进程、后端身份、manifestPath、错误和停止证据。queued/running/cancelling 仍占用对象。释放必须是已知终态、stopConfirmed=true,且无 unsettled、promptId、remoteCancellation 或 dispatching/accepted 远程回执;unknown 一律保留占用。
18
12
 
19
- 远程 doctor 只检查配置。检查百炼安装用 bl --help,认证用 bl auth status,生效区域/URL 用 bl config show;当前安装没有 bl doctor。只读检查不能保证云端联网、额度和模型实际可用,需在任务授权范围内验证真实调用。
13
+ 工作进程丢失且心跳过期标记 unknown,不能推测上游停止。task wait 超时不取消;切面板不取消;本地客户端退出不代表云端取消或费用撤销。
20
14
 
21
- ## 工作流错误结构
15
+ ## 查询、恢复和重试
22
16
 
23
- ```powershell
24
- v-cli art task status TASK
25
- v-cli art task wait TASK --timeout 60
26
- ```
17
+ | 情况 | 入口 | 行为 |
18
+ | --- | --- | --- |
19
+ | 已知 taskId | task status / task wait | 查询原运行 |
20
+ | 启动回执丢失 | task recover --project P --operation ID | 唯一原登记查找;不启动进程 |
21
+ | 已有 accepted/completed 远程回执 | task resume TASK | 原 taskId 继续查询与下载,不发生成 POST |
22
+ | dispatching 中断但无上游 ID | 保留未知,核对原提供方记录 | 不允许猜测恢复或重发 |
23
+ | 上游完成但下载失败 | task resume TASK | 取回原结果,不付费重生成 |
24
+ | 明确失败且停止确认 | run --plan FILE --retry-run RUN | 新批次只重试明确失败项,记录 retryOf |
25
+ | 风格采用事务中断 | style recover | 完成原事务,不重新冻结另一份核心 |
26
+ | 部署启动回执丢失 | deployment recover --operation ID | 只读恢复唯一登记 |
27
27
 
28
- 本地环境不兼容、工作流提交拒绝和采样异常分别记录 diagnostic.stage=environment/submission/execution。task 状态、前台等待结果和 manifest 提供错误;单体失败记录也保留 diagnostic。
28
+ resume 要求原工作进程已退出、运行终态、回执和冻结请求哈希一致。跳过成功文件、上游失败或取消项,不补发未提交项。无回执、身份不符或无可查询/取回项目均拒绝。查询失败保留原 ID;当前不自动重发提交或自动重试查询。
29
29
 
30
- | 字段 | 读取方式 |
31
- |---|---|
32
- | kind/stage | 是否工作流相关,失败发生在哪一层 |
33
- | backend/workflow | 任务实际冻结的后端与模板身份 |
34
- | promptId | ComfyUI 已接受的执行 ID;提交前失败可能没有 |
35
- | nodes | 提交校验节点 ID/类型/title/errors,或执行异常节点、异常类型、信息和 traceback |
36
- | environments | 环境不兼容时的 endpoint、版本和缺失节点/模型 issues |
37
- | messages | ComfyUI 返回的历史执行消息 |
38
- | hint | 辅助修复建议,以原始错误为依据 |
39
- | unsettled | 无法确认后端已经停止;不能宣称回收完成 |
30
+ retry-run 不能混用 dry/item/variant/offset/limit;原批次和先前重试必须停止确认,成功项不重复执行,远程完成待下载项不能走重生成。配置、模型契约、规格、核心、参考、底图或工作流变化后重编译,不能运行过期预案。
40
31
 
41
- 启动入口、网络、上传或输出数量错误不一定有节点 diagnostic,应读取 error、logPath 和 manifestPath。ComfyUI 接受 promptId 同时报告节点错误时,art 先请求停止该 prompt,再记录失败,避免遗留执行。
32
+ ## 取消与关闭
42
33
 
43
- ## 按原因处理
34
+ task cancel 定向取消本工作区运行。本地按 promptId 处理自有请求,保留 ComfyUI 服务;远程无已适配上游取消能力时只停止本地等待,保留原身份与未知停止事实。
44
35
 
45
- | 现象 | 检查与处理 |
46
- |---|---|
47
- | configuration/workflow_format | 修复字段;导出 API JSON,而非画布 nodes/links |
48
- | workflow_link/workflow_binding | 对照节点 ID、input 名和输出索引;不要只看中文标题 |
49
- | missing_node | 安装或修复相关 ComfyUI 插件,重启服务后 doctor |
50
- | missing_model/invalid_node_value | 核对模型文件名、目录及节点实际可选值;检查执行 model 覆盖 |
51
- | comfyui_version | 升级到支持按 prompt_id 中断的版本,至少 0.39.0 |
52
- | launch_path/launch_entry/startup | 核对 executable/cwd/args、端口和服务日志;不能用端口占用证明服务兼容 |
53
- | CUDA OutOfMemory/内存不足 | 降低尺寸或候选工作负载,确认 lowvram 与 CPU 编码配置;重新 plan |
54
- | 只输出零张或多张图片 | 模板每次须恰好一张最终 output;检查 SaveImage 和 batch_size |
55
- | 原图或计划哈希变化 | 从当前任务和原图重新 plan,不手改哈希或 frozen plan |
56
- | 远程调用失败 | 检查百炼入口、凭证、区域、模型限制和任务日志;不自动换模型或后端 |
36
+ CLI shutdown 阻止新提交,停止当前工作区关联任务,再核验共享队列及服务进程身份。它不清空共享队列;存在其他运行/排队请求、停止未知或身份不可验证时保留服务。不要广泛杀所有 Python。
57
37
 
58
- 修复模板或配置后重新 plan、run --dry,再在授权范围内重试。检查结果不自动选择替代模型、不改设计尺寸、不下载权重。
38
+ Vant 应用退出有独立所有权清理:关闭 Vant 启动并登记的后台进程和 ComfyUI,检查端口释放,不把外部用户服务收编为退出时终止目标。窗口关闭、CLI shutdown、应用退出三个入口的作用域不同。
59
39
 
60
- ## 单次任务生命周期
40
+ ## 常见配置问题
61
41
 
62
- | 状态 | 含义与后续 |
63
- |---|---|
64
- | queued | 工作进程已提交,等待运行 |
65
- | running | 可能正在启动服务、等串行锁、加载或采样;查看 currentItem/promptId |
66
- | succeeded | 所选任务完成;进入人工审查 |
67
- | failed | 执行失败;读取 error/diagnostic/manifest;可能已有部分图片 |
68
- | cancelled | 当前任务已取消;查看已完成产物与远程取消说明 |
69
- | lost | worker 死亡且状态过期;后端可能仍在执行,需要 cancel/shutdown |
70
-
71
- 后台任务不会因终端窗口关闭自动取消。task wait 只等待;--timeout 超时后仍可 status/wait/cancel。task cancel 请求指定任务停止,保留服务;已完成任务会返回原终态。部分图片保留,不自动删除。
72
-
73
- ## shutdown 的完整语义
74
-
75
- ```powershell
76
- v-cli art task cancel TASK
77
- v-cli art shutdown
78
- ```
79
-
80
- cancel 针对一个 art 任务;shutdown 针对当前 --config 识别的全部 art 生图/编辑任务,以及配置和历史冻结任务引用的本地后端:阻止新提交、请求取消、清空队列、全局中断、等待停止、关闭核验后的服务进程。后端上浏览器或其他客户端的任务也会被清空/中断。同步 style analyze 不属于该队列。
81
-
82
- 关闭前核对 PID、创建时间和命令身份。art 启动的服务保存身份;Windows 可定位与 launch.executable 和入口匹配的已有实例。其他平台无法核验的外部进程不能宣称已回收。未确认停止或关闭失败则返回错误;读取失败信息再处理,不广泛终止所有 Python 进程。
83
-
84
- 远程取消终止本地 bl 调用,不保证云端请求停止或费用撤销。remoteCancellation 字段与 shutdown.remoteCancellationUnconfirmed 提供这个边界;不能把本地 cancelled 当作云端已取消。
42
+ - 模型无法选择:依次核对实例/模型启用、目录可用、凭据、输出能力、图片协议、准确型号及模式支持。仅登记型号显示限制原因,不可执行;手工能力覆盖不能绕过缺失的协议适配。
43
+ - 报告过期或 revision 冲突:重新读取对象及版本,不覆盖用户输入;更新后重新分析或预演。
44
+ - 模型已存在仍提示部署:核对选择的是便携根目录、文件准确名称与大小,再做 SHA256 和能力接入;不以文件存在替代完整环境验证。
45
+ - 端口被占:区分原环境和其他程序,修改端口后重新检测;自动选择端口不等于长期预约。
46
+ - 候选删除清理失败:保留删除事实,仅重试所属文件清理,不恢复成可用候选。
@@ -0,0 +1,234 @@
1
+ import { buildSources, resolveApiKey } from "bailian-cli-core";
2
+ import { readFile } from "node:fs/promises";
3
+ import sharp from "sharp";
4
+ import { compileRemoteRequest } from "../generation-policy.mjs";
5
+ import { resolveModel } from "../model-registry.mjs";
6
+ import { requestJson, RemoteError } from "../transport/http.mjs";
7
+ export function buildRemoteArgs(plan, item, outDir, prefix) {
8
+ const request = compileRemoteRequest(plan, item),
9
+ spec = resolveModel(
10
+ request.api,
11
+ request.model,
12
+ request.module,
13
+ !!request.images.length,
14
+ );
15
+ return commandPreview(request, spec, outDir, prefix);
16
+ }
17
+ function commandPreview(request, spec, outDir, prefix) {
18
+ const args = ["image", request.module === "edit" ? "edit" : "generate"];
19
+ for (const image of request.images) args.push("--image", image);
20
+ args.push(
21
+ "--prompt",
22
+ request.prompt,
23
+ "--model",
24
+ request.model,
25
+ "--size",
26
+ request.size,
27
+ "--n",
28
+ String(request.count),
29
+ "--seed",
30
+ String(request.seed),
31
+ );
32
+ for (const rule of Object.values(spec.fields))
33
+ if (request.parameters[rule.wire] !== undefined)
34
+ args.push(rule.cli, String(request.parameters[rule.wire]));
35
+ if (request.negativePrompt)
36
+ args.push("--negative-prompt", request.negativePrompt);
37
+ args.push("--out-dir", outDir, "--out-prefix", prefix);
38
+ return args;
39
+ }
40
+ export function serializeRequest(request, images = request.images) {
41
+ return {
42
+ model: request.model,
43
+ input: {
44
+ messages: [
45
+ {
46
+ role: "user",
47
+ content: [
48
+ ...images.map((image) => ({ image })),
49
+ { text: request.prompt },
50
+ ],
51
+ },
52
+ ],
53
+ },
54
+ parameters: request.parameters,
55
+ };
56
+ }
57
+ function endpoint(value) {
58
+ const base = new URL(value);
59
+ if (
60
+ base.username ||
61
+ base.password ||
62
+ base.search ||
63
+ base.hash ||
64
+ !(
65
+ base.protocol === "https:" ||
66
+ (base.protocol === "http:" &&
67
+ ["127.0.0.1", "localhost", "[::1]"].includes(base.hostname))
68
+ )
69
+ )
70
+ throw new Error("图片接口地址无效");
71
+ return base;
72
+ }
73
+ function credentials(context) {
74
+ let configured;
75
+ if (process.env.ART_IMAGE_CONNECTION) {
76
+ configured = JSON.parse(process.env.ART_IMAGE_CONNECTION);
77
+ if (configured.api !== "dashscope" || !process.env.ART_IMAGE_KEY)
78
+ throw new Error("图片连接与协议或凭据不匹配");
79
+ if (
80
+ context.baseUrl &&
81
+ endpoint(context.baseUrl).href.replace(/\/$/, "") !==
82
+ endpoint(configured.baseUrl).href.replace(/\/$/, "")
83
+ )
84
+ throw new Error("图片连接地址与冻结请求不同");
85
+ }
86
+ const credential = configured
87
+ ? { token: process.env.ART_IMAGE_KEY, baseUrl: configured.baseUrl }
88
+ : resolveApiKey(buildSources({}));
89
+ const base = endpoint(context.baseUrl ?? credential.baseUrl),
90
+ key = credential.token;
91
+ if (!key) throw new Error("未配置图片服务凭据");
92
+ return {
93
+ base,
94
+ headers: {
95
+ Authorization: "Bearer " + key,
96
+ "Content-Type": "application/json",
97
+ },
98
+ };
99
+ }
100
+ async function inputImage(path, policy) {
101
+ if (/^https?:\/\//.test(path) || path.startsWith("data:")) return path;
102
+ const buffer = await readFile(path);
103
+ if (buffer.length > policy.maxBytes)
104
+ throw new Error("输入图片超过模型文件大小限制");
105
+ const info = await sharp(buffer, {
106
+ limitInputPixels: 64 * 1024 * 1024,
107
+ }).metadata();
108
+ if (!policy.formats.includes(info.format))
109
+ throw new Error("输入图片格式不受模型支持");
110
+ if (
111
+ (policy.alpha === false && info.hasAlpha) ||
112
+ info.width < (policy.minAxis ?? 1) ||
113
+ info.height < (policy.minAxis ?? 1) ||
114
+ info.width > (policy.maxAxis ?? Infinity) ||
115
+ info.height > (policy.maxAxis ?? Infinity) ||
116
+ info.width / info.height < (policy.minRatio ?? 0) ||
117
+ info.width / info.height > (policy.maxRatio ?? Infinity)
118
+ )
119
+ throw new Error("输入图片透明通道、尺寸或比例不符合模型限制");
120
+ return (
121
+ "data:image/" +
122
+ (info.format === "jpeg" ? "jpeg" : info.format) +
123
+ ";base64," +
124
+ buffer.toString("base64")
125
+ );
126
+ }
127
+ function urls(body) {
128
+ const list =
129
+ body.output?.results?.map((entry) => entry.url) ??
130
+ body.output?.choices?.flatMap((choice) =>
131
+ (choice.message?.content ?? [])
132
+ .filter((entry) => entry.image)
133
+ .map((entry) => entry.image),
134
+ );
135
+ if (
136
+ !Array.isArray(list) ||
137
+ !list.length ||
138
+ list.some((url) => {
139
+ try {
140
+ const u = new URL(url);
141
+ return (
142
+ !["https:", "http:"].includes(u.protocol) ||
143
+ !!u.username ||
144
+ !!u.password
145
+ );
146
+ } catch {
147
+ return true;
148
+ }
149
+ })
150
+ )
151
+ throw new RemoteError("图片服务缺少有效的图片结果", { unsettled: true });
152
+ return list;
153
+ }
154
+ export const dashscopeAdapter = {
155
+ preview: (request) => serializeRequest(request),
156
+ commandPreview: (request, outDir, prefix) =>
157
+ commandPreview(
158
+ request,
159
+ resolveModel(
160
+ request.api,
161
+ request.model,
162
+ request.module,
163
+ !!request.images.length,
164
+ ),
165
+ outDir,
166
+ prefix,
167
+ ),
168
+ id: "dashscope",
169
+ label: "DashScope 图片生成(支持兼容网关)",
170
+ version: 1,
171
+ cancellation: "unsupported",
172
+ async prepare(request, context) {
173
+ const auth = credentials(context),
174
+ images = await Promise.all(
175
+ request.images.map((path) => inputImage(path, request.inputPolicy)),
176
+ );
177
+ return {
178
+ ...auth,
179
+ endpoint: auth.base.href.replace(/\/$/, ""),
180
+ body: serializeRequest(request, images),
181
+ };
182
+ },
183
+ async submit(request, context) {
184
+ const prepared = context.prepared;
185
+ const body = await requestJson(
186
+ new URL(prepared.base.href.replace(/\/$/, "") + request.transport.path),
187
+ {
188
+ ...context,
189
+ timeout: request.transport.timeoutMilliseconds ?? 1800000,
190
+ method: "POST",
191
+ headers: {
192
+ ...prepared.headers,
193
+ ...(request.transport.mode === "async"
194
+ ? { "X-DashScope-Async": "enable" }
195
+ : {}),
196
+ },
197
+ body: prepared.body,
198
+ },
199
+ );
200
+ if (request.transport.mode === "sync")
201
+ return { state: "completed", urls: urls(body) };
202
+ const taskId = body.output?.task_id;
203
+ if (
204
+ typeof taskId !== "string" ||
205
+ !taskId ||
206
+ !/^[a-zA-Z0-9_-]+$/.test(taskId)
207
+ )
208
+ throw new RemoteError("异步响应缺少合法任务身份", { unsettled: true });
209
+ return { state: "accepted", taskId };
210
+ },
211
+ async query(receipt, context) {
212
+ const { base, headers } = credentials(context),
213
+ body = await requestJson(
214
+ new URL(
215
+ base.href.replace(/\/$/, "") +
216
+ "/api/v1/tasks/" +
217
+ encodeURIComponent(receipt.taskId),
218
+ ),
219
+ { ...context, headers },
220
+ );
221
+ if (body.output?.task_id !== receipt.taskId)
222
+ throw new RemoteError("上游返回了其他任务的结果", { unsettled: true });
223
+ const status = body.output?.task_status;
224
+ if (status === "SUCCEEDED") return { state: "completed", urls: urls(body) };
225
+ if (status === "FAILED")
226
+ return { state: "failed", message: "上游图片生成失败" };
227
+ if (status === "CANCELED")
228
+ return { state: "cancelled", message: "上游已取消" };
229
+ if (["PENDING", "RUNNING"].includes(status)) return { state: "accepted" };
230
+ throw new RemoteError("上游任务状态未知;保留原任务身份", {
231
+ unsettled: true,
232
+ });
233
+ },
234
+ };
@@ -0,0 +1,28 @@
1
+ import { dashscopeAdapter } from "./dashscope.mjs";
2
+ export function createAdapterRegistry(entries) {
3
+ const registry = new Map();
4
+ for (const adapter of entries) {
5
+ if (
6
+ !adapter.id ||
7
+ registry.has(adapter.id) ||
8
+ !["prepare", "submit", "query"].every(
9
+ (key) => typeof adapter[key] === "function",
10
+ )
11
+ )
12
+ throw new Error("协议适配器声明无效或重复");
13
+ registry.set(adapter.id, Object.freeze(adapter));
14
+ }
15
+ return Object.freeze({
16
+ list: () =>
17
+ [...registry.values()].map((adapter) => ({
18
+ id: adapter.id,
19
+ label: adapter.label ?? adapter.id,
20
+ })),
21
+ get(id) {
22
+ const adapter = registry.get(id);
23
+ if (!adapter) throw new Error("图片协议尚未接入:" + id);
24
+ return adapter;
25
+ },
26
+ });
27
+ }
28
+ export const adapters = createAdapterRegistry([dashscopeAdapter]);
package/lib/agent.mjs CHANGED
@@ -39,7 +39,7 @@ export function autoSync({root=ROOT,cwd=process.cwd(),home=homedir(),env=process
39
39
  return syncSkill({root,skillDirs:dirs});
40
40
  }
41
41
  export function agentIndex(root=ROOT,workspace=loadSettings().paths.workspace) {
42
- return {tool:'art-workshop',displayName:'美术工坊',root,workspace,config:loadSettings().file,entry:join(root,'art-workshop.mjs'),skill:{name:'art-workshop',source:join(root,'skills','art-workshop','SKILL.md'),automaticDiscovery:true},modules:[{name:'style',actions:['analyze','validate','freeze','show']},{name:'generate',actions:['show','plan','run']},{name:'edit',actions:['show','plan','run']},{name:'refs',actions:['guide']},{name:'agent',actions:['index','docs','init']}],utilities:['list','check','select','compare','task','shutdown','doctor','workflow','config'],projects:(directory(join(workspace,'projects'))?readdirSync(join(workspace,'projects')):[]).filter(id=>directory(join(workspace,'projects',id))).map(id=>{const p=loadProject(id,workspace);return {id:p.id,cores:p.cores,defaultCore:p.defaultCore,jobs:readdirSync(join(workspace,'projects',id,'jobs')).filter(x=>x.endsWith('.json')).map(x=>x.slice(0,-5))};})};
42
+ return {tool:'art-workshop',displayName:'美术工坊',root,workspace,config:loadSettings().file,entry:join(root,'art-workshop.mjs'),skill:{name:'art-workshop',source:join(root,'skills','art-workshop','SKILL.md'),automaticDiscovery:true},modules:[{name:'style',actions:['create','list','read','update','derive','discard','analyze','adopt','recover','validate','show']},{name:'generate',actions:['show','plan','run']},{name:'edit',actions:['show','plan','run']},{name:'refs',actions:['guide']},{name:'agent',actions:['index','docs','init']}],utilities:['project','job','reference','candidate','list','check','compare','task','shutdown','doctor','workflow','config'],projects:(directory(join(workspace,'projects'))?readdirSync(join(workspace,'projects')):[]).filter(id=>directory(join(workspace,'projects',id))).map(id=>{const p=loadProject(id,workspace);return {id:p.id,cores:p.cores,defaultCore:p.defaultCore,jobs:readdirSync(join(workspace,'projects',id,'tasks')).filter(x=>existsSync(join(workspace,'projects',id,'tasks',x,'task.json')))};})};
43
43
  }
44
- export const GUIDE_FILES=['README.md','docs/modes.md','docs/configuration.md','docs/data-formats.md','docs/commands.md','docs/troubleshooting.md','docs/core-guidance.md'];
44
+ export const GUIDE_FILES=['README.md','docs/modes.md','docs/configuration.md','docs/data-formats.md','docs/commands.md','docs/deployment.md','docs/troubleshooting.md','docs/remote-models.md','docs/model-architecture.md','docs/core-guidance.md'];
45
45
  export function agentDocs(root=ROOT) {return GUIDE_FILES.map(file=>readFileSync(join(root,file),'utf8')).join('\n\n');}
@@ -0,0 +1,25 @@
1
+ import {existsSync} from 'node:fs';
2
+ import {join} from 'node:path';
3
+ import {readJson,writeJson,hash} from './shared.mjs';
4
+ import {readObject,objectFile,objectDirectory} from './workspace.mjs';
5
+ import {callBailian} from './transport/cli.mjs';
6
+ import {callVision} from './vision.mjs';
7
+ import {analyzeStyle} from './analyze.mjs';
8
+ import {analyzeTaskReferences} from './task-references.mjs';
9
+ const file=process.argv[2],task=readJson(file);
10
+ const persist=()=>{task.heartbeat=new Date().toISOString();writeJson(file,task);};
11
+ const cancelled=()=>existsSync(file+'.cancel')||existsSync(join(task.root,'shutdown.json'));
12
+ task.workerPid=process.pid;task.status='running';persist();const heartbeat=setInterval(persist,1000);
13
+ try{
14
+ const analyzer=task.objectKind==='task'?analyzeTaskReferences:analyzeStyle;
15
+ const report=await analyzer({projectId:task.project,input:task.input,root:task.workspace,refsDir:task.workspace,analysisModel:task.model,cacheDir:join(task.cache,'analysis'),runner:args=>{if(cancelled())throw new Error('分析已取消');task.currentItem={stage:'visual-analysis'};persist();const call=process.env.ART_VISION_CONFIG?callVision:callBailian;return call([...args,'--output','json'],{cancelled,onRemoteCancel:()=>{task.remoteCancellation='client-stopped; upstream execution cannot be confirmed';task.unsettled=true;persist();}});}});
16
+ if(cancelled())throw new Error('分析已取消');
17
+ {
18
+ // This run owns the object until its final heartbeat; mutation entrypoints refuse active runs.
19
+ const record=readObject(task.workspace,task.project,task.objectKind,task.objectId);
20
+ if(record.revision!==task.sourceRevision||record.status!=='draft'||hash({config:record.config,references:record.references})!==task.sourceHash)throw new Error('分析来源已变化,不回填旧结果');
21
+ const reportPath=join(objectDirectory(task.workspace,task.project,task.objectKind,task.objectId),'reports',task.taskId,'report.json');writeJson(reportPath,report);
22
+ record.report={data:report,runId:task.taskId,sourceHash:task.sourceHash,sourceRevision:task.sourceRevision,path:reportPath};record.revision++;record.updatedAt=new Date().toISOString();writeJson(objectFile(task.workspace,task.project,task.objectKind,task.objectId),record);task.reportPath=reportPath;
23
+ }task.status='succeeded';
24
+ }catch(error){task.status=cancelled()?'cancelled':'failed';task.error=error.message;}
25
+ finally{clearInterval(heartbeat);task.stopConfirmed=!task.unsettled&&!task.remoteCancellation;task.finishedAt=new Date().toISOString();persist();}