@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.
package/AGENTS.md CHANGED
@@ -1,19 +1,67 @@
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
+ 本文件是 @kevlns/art-workshop 的随包执行规范。用户已经给出的授权与偏好持续有效;已有生图、编辑或服务管理授权时继续完成任务,不重复询问。仅预演、查看或分析报告不自动授权付费执行或采用风格。
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
+ ```powershell
8
+ v-cli agent index --json
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
14
+ ```
12
15
 
13
- ## 本地资源与配套
16
+ 首次 official 调用前读取插件规范,实时参数由 describe 确认。工程和任务以 index、generate/edit show 为准,不猜 ID。配置字段和资源路径以 config show 为准,不在工具安装目录写工程、原图、计划或产物。随包 [模式规范](docs/modes.md)、[配置规范](docs/configuration.md)、[命令参考](docs/commands.md) 是完整操作指导;agent docs 输出全部指南。
14
17
 
15
- 本地配置位于用户配置目录,可用 config path/show/init 发现;冻结核心在 workspace/projects/工程/cores。工程、参考、报告、计划、缓存、原图和产物都在安装目录之外,不纳入工具 Git 或 npm 包。相对资源按 workspace 解析,参考图按 refs 解析,RUN 按 output 解析。每次配置生效会补齐 refs 分类目录,包括 dry,不覆盖素材。
18
+ ## 按模式检查后再执行
16
19
 
17
- 随包 skills/art-workshop 是使用规范源,agent init --directory DIR 同步到已有 Agent 技能目录,保留扩展文件;自动同步也可用 npm run skill:sync。v-cli 负责路由、清单与本指导发现,美术工坊负责实际任务、核心选择与模型请求。安装 v-cli 会安装此官方依赖。
20
+ | 模式 | 必须核对 |
21
+ |---|---|
22
+ | 远程文生图 | provider=bailian;百炼真实入口、auth status、config show;模型和执行参数;plan 与 run --dry |
23
+ | 远程编辑 | 远程检查加原图哈希、changes/preserve/mustRead;编辑模型能力;edit plan 与 dry |
24
+ | 本地内置文生图 | 内置名称/模型、config validate、doctor;32 像素对齐、关闭扩写/水印;plan 与 dry |
25
+ | 本地自定义文生图 | API JSON、bindings、插件/模型/输出数量;config validate、doctor、plan 与 dry |
26
+ | 本地 Qwen 2.1 编辑 | 编辑模板、LoadImage.image 和 VAELoader.vae_name 绑定、编码器;一项一张原图;范围检查、doctor、edit plan 与 dry |
27
+ | 风格分析/冻结 | 百炼 analysisModel 与参考 scope;analyze --dry;报告 validate、人工审阅、用户采用后 freeze |
18
28
 
19
- UI 尺寸:文生图 profile.design 声明 resolution 与 outputScale,item.design 声明控件 width/height 与可选 outputScale。单体实际出图尺寸为设计尺寸乘倍率;不能同时指定任务 execution.size。换算越界报错,不自动改变比例;完整约束见 agent docs。
29
+ 模式检查是 Agent 调用要求;不要宣称 CLI 已自动完成百炼凭证验证或人工图片审查。doctor 的远程结果只是配置检查。当前百炼 CLI 无 bl doctor,使用 bl auth status、bl config show 和实际模型入口帮助;认证信息不得泄露。
30
+
31
+ 正常 run 可懒启动本地服务;提前验证时可以 doctor --start,不执行采样,检查后服务保留。plan/dry 不启动、探测 ComfyUI 或加载权重。配置/环境检查通过不代表实际采样、显存或图像质量通过。
32
+
33
+ ## 编译与来源约束
34
+
35
+ - 新任务明确 --project、--job;用 --backend 选配置 ID。未声明默认后端也未显式选时走百炼通用路径;comfyui 后端省略 workflow 时才选择内置 vant-builtin-qwen-image-2.1-Q4-8GB。
36
+ - 先 show 读来源,再 plan 保存快照与哈希,run --plan --dry 校对所选项。已有明确执行授权时按已确认范围运行。
37
+ - 冻结计划运行禁止 --backend、--project、--job、--core、--explore;可选 item/variant/offset/limit/dry/background。修改来源、配置、模板或原图后重新 plan,不手改哈希。
38
+ - --limit 按 item 数,variants 是构图候选,perValue 是每组合出图数。不要把 limit 1 当作保证只生成一张。
39
+ - --timeout 只用于 task wait;本地采样 timeout 在 options.timeoutSeconds。后端没有 promptExtend/watermark 能力时不能静默忽略。
40
+
41
+ ## 内容与核心职责
42
+
43
+ 核心负责可复用视觉规律;实体身份、数量、色相、动作及关系属于任务;背景、留白、文字、场景和设计基准属于 profile;模型及尺寸属于 execution/backend。按 [核心冻结指导规则](docs/core-guidance.md) 检查职责、证据与冲突。
44
+
45
+ 文生图核心依次为显式 --core、任务 core、工程 defaultCore。冲突或缺少选择时报错,不跨工程回退。编辑默认保留原图风格;明确绑定 core 后不能再声明 style 修改/保留。source 必须是真正编辑底图,不将风格参考图误传为主体。
46
+
47
+ 设计换算以每项 execution 为准:每边 256~4096,本地还须为 32 的倍数;不自动改倍率、拉伸、补边。编码器 resolution 与输出 latent 尺寸是不同参数。普通生图默认纯白背景,其他背景须由需求和资产约束明确允许。
48
+
49
+ ## 任务和进程
50
+
51
+ run --background 返回 taskId;前台同样创建 task。用 task status/wait 检查结果。wait 超时不取消任务;task cancel 只取消指定运行、保留服务;failed/lost 不证明后端已停止。
52
+
53
+ shutdown 阻止提交、停止当前配置范围全部 art 生图/编辑任务、清空配置和历史快照关联后端队列、中断采样、等待停止、核验进程身份后关闭服务。浏览器提交到同一后端的任务也受影响。同步 style analyze 不在任务队列内。
54
+
55
+ 无法确认停止时保留 unsettled 并如实报告;不能广泛终止所有 Python 进程。远程 cancel 只保证本地 bl 退出,不保证云端取消、计费撤销;读取 remoteCancellation 与 remoteCancellationUnconfirmed。
56
+
57
+ ## 失败与结果报告
58
+
59
+ 本地任务失败先读取 error、diagnostic、manifestPath、logPath。diagnostic 提供阶段、workflow/backend、节点与原始错误,环境失败可能包含 environments。按节点缺失、模型枚举、连接、启动或内存原因处理,不自动换模型、后端或设计尺寸。修复后重新 plan/dry 再在授权范围重试。
60
+
61
+ 生成成功后 check 导出 content/style/asset 人工验收;只有完整性有效、生成成功且全部 pass 的唯一图片可 select。不要把模型输出、mock 测试或环境检测当作生产验收。报告说明实际模式、模型、任务结果、输出位置和已做验证,明确未验证的云端、显存或视觉边界。
62
+
63
+ ## 文档与技能维护
64
+
65
+ 随包 skills/art-workshop 是技能源,修改后用 agent init 或 skill:sync 同步;不直接改已同步副本。init 只刷新已有 Agent 技能目录里的随包文件,保留扩展,不写工作区 AGENTS.md。正常非 dry 分析/冻结/run 可自动同步,查询、plan、dry 不自动同步。
66
+
67
+ 修改调用规范时同步更新 README、docs、SKILL.md 和 v-cli.plugin.json;执行 npm run docs:check、适当测试、pack:guard 和安装检查。历史试验报告仅为观察记录,不是旧命令、现价或通用模型规律的依据。
package/README.md CHANGED
@@ -1,150 +1,110 @@
1
- # 美术工坊
1
+ # 美术工坊 art
2
2
 
3
- 三个独立模块:风格分析与核心冻结、文生图、图编辑。默认模型 qwen-image-3.0-pro,尺寸 1024*1024,关闭 prompt 扩写。
3
+ 美术工坊将风格分析与核心冻结、文生图、图编辑分为三个模块。生图和编辑可选百炼远程后端或本机 ComfyUI;全部生图后端配置保存在一份用户 config.json。风格分析仍调用百炼,与 generation.defaultBackend 独立。
4
4
 
5
- ## 随包 skill 与能力发现
5
+ 本指南对应 0.2.1 的命令协议。命令与参数以实际安装的 v-cli agent describe art --json 为准。
6
6
 
7
- skills/art-workshop 是精简的使用指导,随 npm 包一起分发,支持隐式发现。安装或更新包时,以及正常分析、冻结、生成或编辑调用时,自动同步到当前目录及用户目录下已有的 Agent 技能目录(含 .codex/skills、.agents/skills、.claude/skills 等;也支持 CODEX_HOME/skills)。不存在的技能目录不创建。只读查询、plan 与 --dry 不自动同步。
7
+ ## 阅读入口
8
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
- 配置结构:
9
+ | 文档 | 内容 |
10
+ |---|---|
11
+ | [模式与调用规范](docs/modes.md) | 每种模式的检查顺序、预演与执行流程 |
12
+ | [统一配置](docs/configuration.md) | 配置字段、优先级、路径及工作流绑定 |
13
+ | [工程与输入结构](docs/data-formats.md) | 工程、分析输入、生成任务、编辑任务、设计尺寸 |
14
+ | [命令参考](docs/commands.md) | 全部入口、参数、退出结果及副作用 |
15
+ | [诊断与任务控制](docs/troubleshooting.md) | 环境与工作流错误、取消及 shutdown |
16
+ | [核心冻结指导规则](docs/core-guidance.md) | 风格职责、报告检查、冻结与验收 |
17
+ | [Agent 规范](AGENTS.md) | AI Agent 的执行要求 |
26
18
 
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 解析。
19
+ ## 安装与发现
47
20
 
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。构图、文字、姿态的具体要求属于单体计划,不自动冻结进核心。
21
+ 要求 Node.js >=20。通过 v-cli 调用时,art 是官方插件;独立安装可用 npm install -g @kevlns/art-workshop。远程生图、编辑及风格分析另需已配置的 bailian-cli;纯本地生图不依赖百炼凭证。ComfyUI、插件和模型权重需独立安装,art 不自动下载。
51
22
 
52
23
  ```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
24
+ v-cli agent index --json
25
+ v-cli agent docs art
26
+ v-cli agent describe art --json
27
+ v-cli art --version
28
+ v-cli art config show
29
+ v-cli art agent index
57
30
  ```
58
31
 
59
- ## 工程结构
32
+ 本文示例统一使用 v-cli art。独立安装将前缀替换为 art-workshop;源码运行替换为 node art-workshop.mjs。独立 skill 的 runtime.json 记录实际 Node 入口,避免猜测安装路径。
60
33
 
61
- 顶层指导规则:rules/core-guidance.json。工程配置位于 projects/<project>/project.json;briefs 保存分析输入,reports 保存报告,cores 保存冻结核心,profiles 保存资产规格,jobs 保存真实需求。这些目录位于外部工作目录,不属于工具安装目录。输出默认位于系统下载目录的 image.g,参考图与缓存也使用外部路径。
34
+ ## 执行前选择模式
62
35
 
63
- 所有模块明确指定工程;核心不跨工程回退。新工程须创建自己的 project.json,并通过该工程的报告冻结核心,不能复制冻结文件并修改身份。工程 cores 可列多份核心,defaultCore 为明确默认或 null。
36
+ | 模式 | 后端选择 | 执行前检查 |
37
+ |---|---|---|
38
+ | 远程文生图或编辑 | --backend remote-qwen | config validate、百炼入口与认证、任务 plan、run --dry |
39
+ | 本地内置文生图 | --backend local-qwen | config validate、workflow list、doctor、plan、run --dry |
40
+ | 本地自定义文生图 | --backend local-custom | 自定义 API JSON/bindings 校验、doctor、plan、run --dry |
41
+ | 本地 Qwen 2.1 图编辑 | --backend local-edit | 编辑模板/image/vae 绑定、doctor、原图和范围检查、plan、run --dry |
42
+ | 风格分析与冻结 | analysisModel 或工程 analysisModel | 百炼入口与认证、analyze --dry、报告 validate、用户采用后 freeze |
64
43
 
65
- ## 风格分析与冻结
44
+ 这些检查是调用规范;CLI 不会自动执行百炼认证检查或人工图像审查。实际本地任务会重新探测环境,启动与工作流错误会写入任务状态和 manifest。config validate 检查全局配置及模板,不校验所有工程任务;plan 才检查指定任务和实际单体参数。doctor 通过不等于采样或显存验证通过。
66
45
 
67
- 输入包含 project、id、description、refs、constraints。图片参考声明 path、scope(style/palette/shape/render)、note。纯语言也可分析;多图分别观察后合并。参考图只用于分析,文生图不会自动把这些图片传给生图模型。
46
+ ## 一次本地文生图
68
47
 
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
- ```
76
-
77
- 分析只生成报告,不自动冻结。报告区分观察证据、置信度、推荐配置、conflicts 与 uncertainties。处理完冲突和未确定项才能冻结。freeze 表示采用推荐配置;已有核心不能覆写,另一套风格使用新的核心 ID。
78
-
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。显式指定与任务绑定冲突时报错,须先修改任务绑定。没有明确选择时不能猜测。计划保存核心身份、哈希、选择依据与完整快照。
48
+ 以下 P、J、ITEM 是占位符,必须替换为 agent index 和 generate show 返回的真实身份。PLAN 是相对于 workspace 的计划路径。后端 ID 必须已在用户配置中声明。
86
49
 
87
50
  ```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
51
+ v-cli art config validate --backend local-qwen
52
+ v-cli art workflow list
53
+ v-cli art doctor --backend local-qwen
54
+ # 服务未运行时,按配置启动并检测;不执行采样。
55
+ v-cli art doctor --backend local-qwen --start
56
+ v-cli art generate show --project P --job J
57
+ v-cli art generate plan --project P --job J --backend local-qwen --out .cache/local-plan.json
58
+ v-cli art generate run --plan .cache/local-plan.json --item ITEM --dry
59
+ v-cli art generate run --plan .cache/local-plan.json --item ITEM --background
93
60
  ```
94
61
 
95
- plan 编译全部候选;run 默认 base,--variant 选指定候选,--explore 执行全部候选。修改任务后重新 plan,冻结计划不能同时修改来源配置。
96
-
97
- 背景默认 {type:solid,color:#FFFFFF},纯黑用 #000000。其他纯色可显式配置,渐变用 gradient/from/to,场景用 scene/description 且须被资产规格允许。背景提示词和验收共用解析结果。
62
+ 默认内置模板名为 vant-builtin-qwen-image-2.1-Q4-8GB。本地后端省略 workflow 时使用该模板,默认后端 ID 仍由 generation.defaultBackend 决定。模板为 Qwen 2.1 文生图,CPU 文本编码、512×512 默认画布;不声明 generation.defaultBackend 且未传 --backend 时仍走远程默认模式。内置模板不是开箱即用的模型安装包。
98
63
 
99
- ## 图编辑
64
+ 远程与编辑流程见 [模式规范](docs/modes.md)。新计划可以选择 --backend;运行冻结计划时不能再传 --backend、--project、--job、--core 或 --explore。修改配置或需求后重新 plan,不手改计划。
100
65
 
101
- 任务 kind 为 edit,每项有 source、changes、preserve、mustRead、可选 seed。范围为 background/style/shape/color/composition/content/detail/text;同一范围不能同时修改和保留。背景修改用结构化 value,其他范围用 instruction。
66
+ ## 任务与验收
102
67
 
103
68
  ```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
69
+ v-cli art task list
70
+ v-cli art task status TASK
71
+ v-cli art task wait TASK --timeout 60
72
+ v-cli art task cancel TASK
73
+ v-cli art shutdown
108
74
  ```
109
75
 
110
- 编辑默认保留原图风格,不自动读取工程默认核心或替换背景。目标风格须明确绑定 core,此时不能再写 style 修改或保留。原图哈希写入计划,原图改变后须重新预演。示例任务将已有 skill-01 改成纯白背景,保留主体、效果和构图。
111
-
112
- ## 预演与验收
76
+ TASK 替换为 run 返回的 taskId。前台运行也创建任务并等待;后台立即返回 ID。wait 超时不会取消任务。cancel 只停止指定任务,保留本地服务;远程取消只保证本地调用退出,云端请求是否撤销不能保证。
113
77
 
114
- plan 与 run --dry 均不调用远程生图,分别返回完整编译快照与选定项实际请求参数,不生成图片。分析 --dry 返回预计请求,实际远程调用数为 0。
115
-
116
- 实际 run 保存图片、输入和输出哈希、失败记录。人工分别检查 content/style/asset,产物完整、生成成功且三个维度全部 pass 才能 select。check 汇总人工验收,不自动评价图像。
78
+ shutdown 停止当前配置范围内全部 art 生图/编辑任务,清空关联 ComfyUI 队列、中断采样,等待停止,再关闭经身份核验的服务进程。它也影响相同后端上浏览器提交的任务。同步风格分析不属于这个任务队列。失败时读取 diagnostic、日志及 unsettled,不能把失败或 lost 当作后端已停止。
117
79
 
118
80
  ```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
81
+ v-cli art check RUN --out .cache/review.json
82
+ # 按实际图片填写 content/style/asset 的 pass、fail 或 pending,以及 reason。
83
+ v-cli art check RUN --review .cache/review.json
84
+ v-cli art select RUN --item ITEM --variant base --review .cache/review.json
125
85
  ```
126
86
 
127
- 依赖 Node.js 与已配置的 bailian-cli。历史图片保留供对照,旧配置和旧计划接口不再支持。真实模型效果需另行实测。
128
-
129
- ## v-cli 接入
87
+ RUN 替换为输出目录名或 manifest 路径。check 检查记录与哈希并汇总人工判断,不自动评价图片。只有完整性有效、生成成功且三个维度全通过的唯一产物可 select。
130
88
 
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 设计分辨率与单体出图尺寸
89
+ ## 文件与默认值
133
90
 
134
- UI 设计基准属于资产规格,不写进冻结风格核心。文生图 profile 可声明:
91
+ config path/show/init 管理用户配置;默认输出为系统下载目录/image.g。工程、原图、参考、报告、计划、缓存和运行产物必须放在工具目录之外。一般相对资源路径基于 workspace;check/select 的相对 RUN 基于 output;参考图 path 基于实际 refs;自定义 workflow 和 launch 路径基于 config.json 所在目录。
135
92
 
136
- ```json
137
- "design": { "resolution": { "width": 1920, "height": 1080 }, "outputScale": 2 }
138
- ```
93
+ plan 和 --dry 不调用生图或启动服务,但普通 CLI 路由会补齐 refs 分类目录;plan 指定 --out 会写计划。config validate、doctor、workflow list 走独立检查路由,不补齐 refs。doctor --start 可启动并保留服务,权重通常在首次实际采样时加载。
139
94
 
140
- 任务 item 可声明独立控件尺寸与可选倍率:
95
+ 远程通用默认是 qwen-image-3.0-pro、1024×1024,每候选一张,扩写和水印关闭。内置本地模板另提供 512×512 默认值。最终模型和每项尺寸以 plan 与 dry 为准;配置优先级见 [统一配置](docs/configuration.md)。
141
96
 
142
- ```json
143
- "design": { "width": 240, "height": 80, "outputScale": 4 }
144
- ```
97
+ ## 随包文档与开发检查
145
98
 
146
- 该按钮实际请求 size 为 960*320。同一任务的其他控件可使用不同设计尺寸;单体没有 design 时按 profile 的整幅设计分辨率出图。未覆盖倍率时继承 profile.outputScale。倍率为 1~4 的整数,设计尺寸为正整数且不得超过基准分辨率;换算后的每条边必须在工具支持的 256~4096 像素范围内,越界报错,不自动拉伸、补边或更改倍率。模型可能有额外尺寸与比例限制,工具的通用范围不等于模型能力保证。
99
+ agent docs 输出完整指南;agent init 只向指定目录下已有 Agent 技能目录同步随包 skill,保留扩展文件,不写 AGENTS.md。正常分析、冻结及非 dry 运行可自动同步;只读命令、plan、dry 不自动同步。用户配置 autoSyncSkills=false 可关闭自动同步。
147
100
 
148
- 启用设计尺寸时禁止同时设置任务 execution.size;工程和本地 execution.size 默认值被单体换算尺寸替代,模型等其他执行参数保留既有优先级。旧任务不声明 design 时保持原有行为。设计模式的提示词不再附加整体占画幅 75% 等比例要求,而声明设计宽高比和安全留白。
101
+ ```powershell
102
+ v-cli art agent docs
103
+ v-cli art agent init --directory C:/MyProject --dry
104
+ v-cli art agent init --directory C:/MyProject
105
+ npm run docs:check
106
+ npm run check
107
+ npm run test:package
108
+ ```
149
109
 
150
- 编译计划的每项包含 design(resolution、size、outputScale、outputSize)与实际 execution。预演、真实请求、输入哈希与执行验收使用同一份单体参数。修改设计尺寸后必须重新 plan。此配置控制请求画布,不保证模型精确绘制控件边界、描边或圆角像素,也不自动生成九宫切片、裁切或透明底资源。
110
+ 开发检查验证文档命令、配置示例、单元及集成测试、包内容与安装入口;模拟后端测试不代表真实云端或模型效果验证。[2026-10-08 试验记录](docs/问题报告-2026-10-08.md) 只保留历史观察,不作为当前接口、价格或模型行为规范。
package/art-workshop.mjs CHANGED
@@ -4,7 +4,7 @@ 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 | refs guide | agent index/docs/init | list | style analyze/validate/freeze/show | generate show/plan/run | edit show/plan/run | task list/status/wait/cancel | shutdown | check/select RUN | 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
10
  const {referenceRoot,ensureReferenceDirectories,referenceGuide}=await import('./lib/refs.mjs');
@@ -16,11 +16,24 @@ const {compileEdit}=await import('./lib/edit.mjs');
16
16
  const {validatePlan,selectItems}=await import('./lib/plan.mjs');
17
17
  const {executePlan,checkRun}=await import('./lib/executor.mjs');
18
18
  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]);
19
+ const {backendDefaults,bindBackend,buildComfyRequest}=await import('./lib/backends.mjs');
20
+ const {startTask,taskStatus,taskView,waitTask,cancelTask,shutdown}=await import('./lib/tasks.mjs');
21
+ const {runtimeRoot,tasks}=await import('./lib/runtime.mjs');
22
+ const {validateConfiguration,doctor}=await import('./lib/diagnostics.mjs');
23
+ const {workflowList}=await import('./lib/workflows.mjs');
24
+ const flags=new Set(['dry','explore','background','start']);
25
+ 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','backend','timeout',...flags]);
21
26
  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
27
  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']});
28
+ if(pos[0]==='workflow'&&pos[1]==='list'){print(workflowList());process.exit(0);}
29
+ let settings;
30
+ 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']});}
31
+ catch(error){print({ok:false,stage:'configuration',issues:[{code:'configuration',message:error.message}]});process.exit(1);}
32
+ if(pos[0]==='config'&&pos[1]==='validate'||pos[0]==='doctor'){
33
+ if(pos[0]==='doctor'&&pos[1])throw new Error('doctor 不接受位置参数');
34
+ 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;
35
+ }else{
36
+ if(options.start)throw new Error('--start 仅用于 doctor');
24
37
  const ROOT=settings.paths.workspace;
25
38
  const path=x=>externalPath(resolve(ROOT,x),'资源文件');
26
39
  function required(k){const value=options[k]??(k==='project'?settings.defaultProject:undefined);if(!value) throw new Error('需要 --'+k);return value;}
@@ -60,12 +73,24 @@ try {
60
73
  if(action==='show') print(loadJob(required('project'),required('job'),module,ROOT));
61
74
  else if(['plan','run'].includes(action)){
62
75
  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});
76
+ 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('计划模块不匹配');}
77
+ 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
78
  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;}
79
+ else {
80
+ 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)});
81
+ 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});}
82
+ else {const task=await startTask(plan,items,settings);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;}}
83
+ }
67
84
  }else throw new Error('未知模块操作');
68
- }else if(['check','select'].includes(module)){
85
+ }else if(module==='task'){
86
+ const root=runtimeRoot(settings),taskId=pos[2];
87
+ if(action==='list')print(tasks(root).map(t=>taskView(taskStatus(root,t.taskId))));
88
+ else if(action==='status')print(taskView(taskStatus(root,taskId)));
89
+ else if(action==='cancel')print(taskView(await cancelTask(root,taskId)));
90
+ 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;}
91
+ else throw new Error('未知 task 操作');
92
+ }else if(module==='shutdown'){if(action)throw new Error('shutdown 不接受位置参数');print(await shutdown(settings));}
93
+ else if(['check','select'].includes(module)){
69
94
  const file=manifestPath(action??required('file')),manifest=readJson(file);
70
95
  const review=options.review?readJson(path(options.review)):manifest.review;
71
96
  const rows=checkRun(manifest,file,review);
@@ -74,4 +99,5 @@ try {
74
99
  }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
100
  else if(!module||module==='help') console.log(help);
76
101
  else throw new Error('未知模块或旧入口:'+module);
77
- }catch(e){console.error(e.message);process.exitCode=1;}
102
+ }catch(e){if(e.diagnostic)print({ok:false,error:e.message,diagnostic:e.diagnostic});else console.error(e.message);process.exitCode=1;}
103
+ }
@@ -0,0 +1,82 @@
1
+ # art 命令参考
2
+
3
+ 所有 art 命令均可通过 v-cli art 调用。本页按 0.2.1 协议整理;实际完整参数先运行 v-cli agent describe art --json。CLI 查询和检查主要输出 JSON,不需要额外 --json;--json 属于 v-cli agent 的发现命令。--version 与 --help 单独使用。
4
+
5
+ ## 公共目录参数
6
+
7
+ --config FILE、--workspace DIR、--output-dir DIR、--refs-dir DIR、--cache-dir DIR 临时选择用户配置和目录。路径基准见 configuration.md。配置未声明字段或参数重复时拒绝,不用兼容入口代替。
8
+
9
+ ## 命令与检查规范
10
+
11
+ | 命令 | 必需身份或文件 | 主要选项与调用要求 |
12
+ |---|---|---|
13
+ | help / --help | 无 | 只显示入口,不读取配置 |
14
+ | --version | 无 | 只显示版本,不读取配置 |
15
+ | config path | 无 | 返回配置路径;配置需能解析 |
16
+ | config show | 无 | 返回生效路径、后端及默认项 |
17
+ | config init | 无 | 创建默认文件;已有不覆盖 |
18
+ | config validate | 无 | --backend ID 可限定;校验全局配置与模板,失败退出 1 |
19
+ | doctor | 无 | --backend ID 可限定;--start 可启动本地服务,不采样 |
20
+ | workflow list | 无 | 返回内置名称和 API/UI 路径;不依赖用户配置合法性 |
21
+ | refs guide | 无 | --project P 可选,--refs-dir 可覆盖;显示实际分类与 scope |
22
+ | list | 无 | 列出外部工程,不是旧风格包列表 |
23
+ | agent index | 无 | 返回工程、核心、任务、模块、入口与外部路径 |
24
+ | agent docs | 无 | 输出随包完整指南 |
25
+ | agent init | 无 | --directory DIR 指定已存在目录;--dry 预览同步 |
26
+ | style analyze | --project P、--input FILE | --out REPORT、--dry;非 dry 可调用远程分析 |
27
+ | style validate | --project P、--report REPORT | 校验报告、推荐核心、冲突及不确定项 |
28
+ | style freeze | --project P、--report REPORT | --note TEXT;用户采用后冻结,不覆盖已有核心 |
29
+ | style show | --project P、--core CORE | 读取并核对冻结身份与哈希 |
30
+ | generate show | --project P、--job J | 展示源任务,不是编译后的最终请求 |
31
+ | generate plan | --project P、--job J | --core CORE、--backend ID、--out PLAN |
32
+ | generate run | --plan PLAN,或 --project P、--job J | 选择、预演及后台参数见下文 |
33
+ | edit show | --project P、--job J | 展示底图与修改、保留要求 |
34
+ | edit plan | --project P、--job J | --core CORE、--backend ID、--out PLAN;核对 source 哈希 |
35
+ | edit run | --plan PLAN,或 --project P、--job J | 编辑适配器须支持原图;与 generate 同一任务机制 |
36
+ | task list | 无 | 当前配置范围内运行记录;不等于所有 ComfyUI 浏览器任务 |
37
+ | task status | TASK | 状态、日志、manifest、diagnostic;失联任务可被标记 lost |
38
+ | task wait | TASK | --timeout SECONDS,默认 3600;超时不取消任务 |
39
+ | task cancel | TASK | 请求停止并等待最多 60 秒;保留服务 |
40
+ | shutdown | 无 | 停止当前范围全部任务、清空关联后端队列、关闭服务 |
41
+ | check | RUN,或 --file RUN | --out REVIEW、--review REVIEW;汇总完整性和人工审查 |
42
+ | select | RUN、--item ITEM、--variant VARIANT | --review REVIEW、--file IMAGE;必须选唯一且全通过的图片 |
43
+ | compare | PLAN_A PLAN_B | 比较计划/manifest 的计划快照,不分析图片 |
44
+
45
+ 省略 --project 时可使用 defaultProject,但示例推荐显式指定。TASK/RUN/PLAN 等均为占位符,替换后再运行。
46
+
47
+ ## run 的两种来源
48
+
49
+ ```powershell
50
+ # 根据当前来源重新编译,可以选后端。
51
+ v-cli art generate run --project P --job J --backend local-qwen --item ITEM --dry
52
+ # 使用冻结计划,只选执行项,不调整来源。
53
+ v-cli art generate run --plan .cache/local-plan.json --item ITEM --variant base --background
54
+ ```
55
+
56
+ 使用 --plan 时禁止 --project、--job、--core、--backend、--explore。允许 --item、--variant、--offset、--limit、--dry、--background,以及公共路径覆盖。新来源调用可加 --explore 执行全部 variants;默认只选 base。--variant 为单一候选 ID;--limit/--offset 按 item ID 计数,limit 为正整数,offset 为非负整数。
57
+
58
+ --dry 显示请求,不创建 task、上传原图、联网或采样。--background 返回 taskId;前台创建同样任务并等待。run 不支持用 --timeout 改等待或采样时间,应单独使用 task wait 或修改后端 timeoutSeconds 后重新 plan。
59
+
60
+ ## 退出码和产物
61
+
62
+ config validate/doctor 检查通过为 0,失败为 1;远程 doctor 的 0 只代表配置检查。后台 run 的 0 只表示成功提交工作进程,任务结果看 task status/wait。前台 run 和 task wait 遇到非 succeeded 终态返回 1;等待超时也返回错误,但后台任务继续。task status 是查询,failed 状态并不意味着查询命令本身失败;task cancel 返回取消后的记录,也可能返回已完成终态,应检查 status/unsettled。
63
+
64
+ 检查或编译失败不产生图片。实际任务文件位于配置旁 .runtime,生成目录在 output。取消或失败可能留下已生成图片与 manifest,不能把文件存在当作验收通过。
65
+
66
+ ## 副作用范围
67
+
68
+ | 操作 | 网络、进程与写入 |
69
+ |---|---|
70
+ | help/version/workflow list | 无服务启动、模型请求或 refs 初始化 |
71
+ | config validate | 读取配置和模板,不探测 HTTP、不补 refs |
72
+ | doctor | HTTP 环境查询;默认不启动、不采样、不补 refs |
73
+ | doctor --start | 可写服务状态/日志并启动;检查后服务保留 |
74
+ | 普通查询、plan、run --dry | 可补齐外部 refs 分类;plan --out 写计划;不调用生图服务 |
75
+ | style analyze | 非 dry 可远程调用、写缓存/报告;不自动冻结 |
76
+ | style freeze | 写核心和 project.json;需采用报告;可同步 skill |
77
+ | 非 dry run | 启动任务进程、保存产物;本地可懒启动和采样,远程可产生费用;可同步 skill |
78
+ | task status/list/wait | 读状态;发现死 worker 时可写 lost;普通 CLI 仍可能补 refs |
79
+ | task cancel/shutdown | 请求取消,按范围操作队列或进程,写状态;shutdown 范围更广 |
80
+ | check/select/agent init | 检查或写审查、选择、技能文件;不调用模型 |
81
+
82
+ --dry 不是所有命令的通用零副作用开关,只在明确支持的 analyze/run/agent init 中有意义。不要把命令未使用的参数当作模式切换。