@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/AGENTS.md CHANGED
@@ -1,67 +1,40 @@
1
1
  # art Agent 调用规范
2
2
 
3
- 本文件是 @kevlns/art-workshop 的随包执行规范。用户已经给出的授权与偏好持续有效;已有生图、编辑或服务管理授权时继续完成任务,不重复询问。仅预演、查看或分析报告不自动授权付费执行或采用风格。
3
+ 用户既有授权与偏好持续有效;查询和预演不授权生成或采用。规范与实时参数通过 v-cli agent docs art 和 v-cli agent describe art --json 获取。
4
4
 
5
- ## 首次发现与路径确认
5
+ ## 对象与参考
6
6
 
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
- ```
7
+ 工程必须使用 schemaVersion 2。project upgrade 是显式一次性升级,备份和原子替换;混合旧参考必须明确映射,日常读写无旧格式回退。
8
+ 风格和任务都有稳定 id 与 revision。UI、聊天和 CLI 共用对象;写入、派生与清理提交预期 revision,冲突重新读取。正式风格只读,改动创建派生风格;派生不继承报告、核心、批次、授权与对话。
9
+ 风格静态参考只有 style、palette、shape-language、rendering,分析理解可复用视觉语言。任务动态参考只有 subject、composition、pose、identity-color、surface、scene-light、text;编辑底图另列。导入复制原图,不修改用户文件。未适配直接参考时拒绝,不隐式上传风格图片。
15
10
 
16
- 首次 official 调用前读取插件规范,实时参数由 describe 确认。工程和任务以 index、generate/edit show 为准,不猜 ID。配置字段和资源路径以 config show 为准,不在工具安装目录写工程、原图、计划或产物。随包 [模式规范](docs/modes.md)、[配置规范](docs/configuration.md)、[命令参考](docs/commands.md) 是完整操作指导;agent docs 输出全部指南。
11
+ ## 风格生命周期
17
12
 
18
- ## 按模式检查后再执行
13
+ style create/read/update/derive/discard 管理草稿。style analyze --dry 只读编译,不联网、启动服务或创建参考目录。实际 analyze 创建 taskId 与独立参考证据;task status/wait/cancel 控制执行,recover 查原登记,resume 仅恢复远程查询与取回。
14
+ 报告绑定源配置、参考与模型。更新配置会清除当前报告,旧证据保留。style adopt 校验源版本、报告身份、冲突与未确定项,用户采用后冻结。采用中断通过 style recover 完成已授权事务,不能重新冻结另一份核心。
15
+ 退出风格配置先继续编辑、保存草稿或放弃;分析停止未确认时不能清理。
19
16
 
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 |
17
+ ## 计划与执行
28
18
 
29
- 模式检查是 Agent 调用要求;不要宣称 CLI 已自动完成百炼凭证验证或人工图片审查。doctor 的远程结果只是配置检查。当前百炼 CLI 无 bl doctor,使用 bl auth status、bl config show 和实际模型入口帮助;认证信息不得泄露。
19
+ 先读取实际 job,再 generate/edit plan 和 run --plan --dry,展示有效核心、设计尺寸、预留缩放、请求与实际像素、模型后端、候选数量和编辑底图。后端尺寸由工具统一解析,超限或未对齐选最近合法尺寸,保留设计基准并明确实际值;不承诺显存或自动缩放导出。
20
+ 授权覆盖方案后使用 run --background;前台同样创建执行身份。配置、核心、规格、参考、底图和后端变化拒绝旧方案,重新编译。重启查 taskId,不重复提交。不自动换模型或重跑成功项。
21
+ 每个任务只能有一个未停止确认的执行;编辑、派生、删除与运行共用状态检查。切页面不取消。
30
22
 
31
- 正常 run 可懒启动本地服务;提前验证时可以 doctor --start,不执行采样,检查后服务保留。plan/dry 不启动、探测 ComfyUI 或加载权重。配置/环境检查通过不代表实际采样、显存或图像质量通过。
23
+ ## 取消、异常和关闭
32
24
 
33
- ## 编译与来源约束
25
+ 任务状态与停止证据分开。queued/running/cancelling 仍占用资源;unknown 或 stopConfirmed=false 保留资源。failed/cancelled 也不能单凭状态释放资源;dispatching/accepted 远程回执尚未结清时继续占用。工作进程丢失标记 unknown,不推测停止。
26
+ task cancel 只取消指定运行,保留服务。远程取消只停止本地客户端,上游停止未知如实报告,不允许清理。shutdown 阻止提交、停止关联任务、核验共享队列和进程身份后关闭本地服务,不清空共享队列;有其他任务或停止未确认时保留服务。不得广泛杀所有 Python。
34
27
 
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 能力时不能静默忽略。
28
+ ## 生成与定版
40
29
 
41
- ## 内容与核心职责
30
+ 只有生成与定版两个产品阶段。check 验证计划、执行身份、文件哈希和完成事实;不要求人工 content/style/asset 评分。candidate finalize 按资产选定候选,重复操作幂等;替换已有定版需要明确 replace,保留历史。
31
+ candidate delete 先确认影响,拒绝运行中或被计划/底图引用的候选;先记删除事实,清理所属文件,并取消关联定版。定版不自动导入游戏或提交 Git。
42
32
 
43
- 核心负责可复用视觉规律;实体身份、数量、色相、动作及关系属于任务;背景、留白、文字、场景和设计基准属于 profile;模型及尺寸属于 execution/backend。按 [核心冻结指导规则](docs/core-guidance.md) 检查职责、证据与冲突。
33
+ ## 验证和技能
44
34
 
45
- 文生图核心依次为显式 --core、任务 core、工程 defaultCore。冲突或缺少选择时报错,不跨工程回退。编辑默认保留原图风格;明确绑定 core 后不能再声明 style 修改/保留。source 必须是真正编辑底图,不将风格参考图误传为主体。
35
+ 本地先 config validate、doctor、plan/dry,再按授权真实生成与编辑。配置有效、服务可连接与真实出图是不同证据。远程核对实际认证和模型入口;凭证不得写入项目、计划、日志或命令行。
36
+ 随包 skills/art-workshop 是技能源;通过 agent init 或 skill:sync 同步,保留项目扩展。查询和预演不自动同步。源码/单测/mock 不能代替真实模型、图像、桌面与安装验证。
46
37
 
47
- 设计换算以每项 execution 为准:每边 256~4096,本地还须为 32 的倍数;不自动改倍率、拉伸、补边。编码器 resolution 与输出 latent 尺寸是不同参数。普通生图默认纯白背景,其他背景须由需求和资产约束明确允许。
38
+ 模型、参数及支持状态只在 art 工具 model-catalog/model-registry 内维护,界面与 v-cli 不复制型号判断。远程图片由已注册协议适配器直接调用;视觉分析连接独立,未注入时使用百炼 CLI。Token Plan 是渠道,DashScope 是协议,不跨站点回退凭据。
48
39
 
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 和安装检查。历史试验报告仅为观察记录,不是旧命令、现价或通用模型规律的依据。
40
+ 远端上游身份持久化后才能轮询。`task resume TASK` 只恢复原身份查询与取回,不重发生成;无回执或仍处于 dispatching 的提交保持未知。界面与保存共用 modelEligibility,展示字段不进入执行契约。
package/README.md CHANGED
@@ -1,110 +1,48 @@
1
- # 美术工坊 art
1
+ # 美术工坊
2
2
 
3
- 美术工坊将风格分析与核心冻结、文生图、图编辑分为三个模块。生图和编辑可选百炼远程后端或本机 ComfyUI;全部生图后端配置保存在一份用户 config.json。风格分析仍调用百炼,与 generation.defaultBackend 独立。
3
+ 面向游戏资产的风格分析、图片生成与编辑工具。风格和任务按工程隔离,计划可预演,执行可追踪,候选按资产定版。产品流程只有「生成 → 定版」;完整性检查不会引入人工评分阶段。
4
4
 
5
- 本指南对应 0.2.1 的命令协议。命令与参数以实际安装的 v-cli agent describe art --json 为准。
5
+ 通过 `v-cli art` 使用,或直接运行 `art-workshop`。需要 Node.js >=20.9。安装不会创建工程、下载模型或生成图片;安装脚本会同步已有 Agent 技能目录中的随包技能。
6
6
 
7
- ## 阅读入口
8
-
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 的执行要求 |
18
-
19
- ## 安装与发现
20
-
21
- 要求 Node.js >=20。通过 v-cli 调用时,art 是官方插件;独立安装可用 npm install -g @kevlns/art-workshop。远程生图、编辑及风格分析另需已配置的 bailian-cli;纯本地生图不依赖百炼凭证。ComfyUI、插件和模型权重需独立安装,art 不自动下载。
22
-
23
- ```powershell
24
- v-cli agent index --json
7
+ ```sh
8
+ npm install -g @kevlns/v-cli
25
9
  v-cli agent docs art
26
10
  v-cli agent describe art --json
27
- v-cli art --version
28
11
  v-cli art config show
29
12
  v-cli art agent index
13
+ v-cli art config validate
30
14
  ```
31
15
 
32
- 本文示例统一使用 v-cli art。独立安装将前缀替换为 art-workshop;源码运行替换为 node art-workshop.mjs。独立 skill 的 runtime.json 记录实际 Node 入口,避免猜测安装路径。
33
-
34
- ## 执行前选择模式
35
-
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 |
43
-
44
- 这些检查是调用规范;CLI 不会自动执行百炼认证检查或人工图像审查。实际本地任务会重新探测环境,启动与工作流错误会写入任务状态和 manifest。config validate 检查全局配置及模板,不校验所有工程任务;plan 才检查指定任务和实际单体参数。doctor 通过不等于采样或显存验证通过。
45
-
46
- ## 一次本地文生图
47
-
48
- 以下 P、J、ITEM 是占位符,必须替换为 agent index 和 generate show 返回的真实身份。PLAN 是相对于 workspace 的计划路径。后端 ID 必须已在用户配置中声明。
49
-
50
- ```powershell
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
60
- ```
61
-
62
- 默认内置模板名为 vant-builtin-qwen-image-2.1-Q4-8GB。本地后端省略 workflow 时使用该模板,默认后端 ID 仍由 generation.defaultBackend 决定。模板为 Qwen 2.1 文生图,CPU 文本编码、512×512 默认画布;不声明 generation.defaultBackend 且未传 --backend 时仍走远程默认模式。内置模板不是开箱即用的模型安装包。
63
-
64
- 远程与编辑流程见 [模式规范](docs/modes.md)。新计划可以选择 --backend;运行冻结计划时不能再传 --backend、--project、--job、--core 或 --explore。修改配置或需求后重新 plan,不手改计划。
65
-
66
- ## 任务与验收
67
-
68
- ```powershell
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
74
- ```
75
-
76
- TASK 替换为 run 返回的 taskId。前台运行也创建任务并等待;后台立即返回 ID。wait 超时不会取消任务。cancel 只停止指定任务,保留本地服务;远程取消只保证本地调用退出,云端请求是否撤销不能保证。
16
+ ## 使用流程
77
17
 
78
- shutdown 停止当前配置范围内全部 art 生图/编辑任务,清空关联 ComfyUI 队列、中断采样,等待停止,再关闭经身份核验的服务进程。它也影响相同后端上浏览器提交的任务。同步风格分析不属于这个任务队列。失败时读取 diagnostic、日志及 unsettled,不能把失败或 lost 当作后端已停止。
18
+ 1. 创建 schemaVersion 2 工程和风格草稿,导入对象私有参考;分析预演后按授权运行,审阅报告并采用为冻结核心。
19
+ 2. 用 `job template` 获取任务模板,填写实际需求后创建任务。动态参考先 `job analyze`;编辑底图单独绑定。
20
+ 3. 编译 `generate plan` 或 `edit plan`,保存并用 `run --plan ... --dry` 核对模型、尺寸、候选数、输入和参数转换。
21
+ 4. 按任务授权执行,保存 taskId;前台和后台都登记运行。查询原身份,不因超时或重启重复提交。
22
+ 5. `check` 核验产物,`candidate finalize` 定版。替换需 `--replace`,删除需 `--confirm`,均保留事实记录。
79
23
 
80
- ```powershell
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
85
- ```
86
-
87
- RUN 替换为输出目录名或 manifest 路径。check 检查记录与哈希并汇总人工判断,不自动评价图片。只有完整性有效、生成成功且三个维度全通过的唯一产物可 select。
88
-
89
- ## 文件与默认值
24
+ 正式风格只读,修改需派生。任务空闲后可按原身份更新配置,历史批次不覆写。状态优先级为待定版、执行中、已定版、草稿;运行状态与停止证据分别判断,不能只看终态释放占用。
90
25
 
91
- config path/show/init 管理用户配置;默认输出为系统下载目录/image.g。工程、原图、参考、报告、计划、缓存和运行产物必须放在工具目录之外。一般相对资源路径基于 workspace;check/select 的相对 RUN 基于 output;参考图 path 基于实际 refs;自定义 workflow 和 launch 路径基于 config.json 所在目录。
26
+ ## 后端与数据归属
92
27
 
93
- plan 和 --dry 不调用生图或启动服务,但普通 CLI 路由会补齐 refs 分类目录;plan 指定 --out 会写计划。config validate、doctor、workflow list 走独立检查路由,不补齐 refs。doctor --start 可启动并保留服务,权重通常在首次实际采样时加载。
28
+ 本地为 ComfyUI 内置 Qwen Image 2.1 Q4、CPU 文本编码器方案,支持生成和显式底图编辑。自定义 API workflow 需要明确 bindings 与完整适配,不能把任意导入工作流视为可执行。
94
29
 
95
- 远程通用默认是 qwen-image-3.0-pro、1024×1024,每候选一张,扩写和水印关闭。内置本地模板另提供 512×512 默认值。最终模型和每项尺寸以 plan 与 dry 为准;配置优先级见 [统一配置](docs/configuration.md)。
30
+ 远程图片通过工具登记的协议适配器直接调用,目前登记 DashScope。模型、参数与支持状态由 art 内部登记表维护,Vant 读取同一目录,不复制型号判断。分析使用独立视觉模型连接;未注入视觉连接时使用百炼 CLI。Token Plan 是渠道,DashScope 是协议,不能据协议擅自替换实例地址和凭据。
96
31
 
97
- ## 随包文档与开发检查
32
+ 应用数据根默认 `~/.vant`,可由 `VANT_HOME` 覆盖。工具配置为 `~/.vant/tools/art-workshop/config.json`;Vant 将工程美术数据绑定至工程 `.vant/art`。共享模型环境默认 `~/.vant/art-env`,控制状态与日志归用户数据根;安装根保存环境标记 `vant.art.config.json`。
98
33
 
99
- agent docs 输出完整指南;agent init 只向指定目录下已有 Agent 技能目录同步随包 skill,保留扩展文件,不写 AGENTS.md。正常分析、冻结及非 dry 运行可自动同步;只读命令、plan、dry 不自动同步。用户配置 autoSyncSkills=false 可关闭自动同步。
34
+ ## 文档
100
35
 
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
- ```
109
-
110
- 开发检查验证文档命令、配置示例、单元及集成测试、包内容与安装入口;模拟后端测试不代表真实云端或模型效果验证。[2026-10-08 试验记录](docs/问题报告-2026-10-08.md) 只保留历史观察,不作为当前接口、价格或模型行为规范。
36
+ | 文档 | 内容 |
37
+ | --- | --- |
38
+ | [模式与流程](docs/modes.md) | 分析、生成、编辑及定版 |
39
+ | [配置](docs/configuration.md) | 路径、后端、连接与凭据边界 |
40
+ | [数据结构](docs/data-formats.md) | 工程、对象、计划、运行与回执 |
41
+ | [命令参考](docs/commands.md) | 从插件清单生成的完整命令与选项 |
42
+ | [本地部署](docs/deployment.md) | 已有环境复用、部署预案与进度 |
43
+ | [任务控制与诊断](docs/troubleshooting.md) | 取消、恢复、重试和关闭 |
44
+ | [远程图片适配](docs/remote-models.md) | 支持范围、参数限制和筛选 |
45
+ | [模型架构](docs/model-architecture.md) | 登记、适配器和扩展规范 |
46
+ | [核心冻结](docs/core-guidance.md) | 风格与需求的职责边界 |
47
+
48
+ 开发校验:`npm run docs:generate`、`npm run check`、`npm run test:package`。模拟测试、配置有效和服务可连接都不能代替真实出图;文档更新不代表新包已发布或桌面安装已更新。
package/art-workshop.mjs CHANGED
@@ -4,25 +4,30 @@ 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/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 查看完整参数。';
7
+ const help='art-workshop: config path/show/init/validate | doctor [--backend ID] [--start] | workflow list | deployment plan/start/status/cancel/recover | refs guide | agent index/docs/init | list | style create/list/read/update/derive/discard/analyze/adopt/recover/validate/show | generate show/plan/run | edit show/plan/run | task list/status/wait/cancel/recover/resume | shutdown | check RUN | project init/upgrade | job template/from-candidate/create/list/read/update/derive/discard/analyze | reference import/list/update/remove | candidate list/finalize/delete/finalizations | compare PLAN PLAN\nrun --background 返回任务 ID;--backend 选择后端。shutdown 停止当前工作区关联任务,核验共享队列和进程身份后关闭本地服务。\n也可用 v-cli art 调用;先 v-cli agent docs art,再 v-cli agent describe art --json 查看完整参数。';
8
8
  if(!args.length||args.length===1&&['--help','-h','help'].includes(args[0])){console.log(help);process.exit(0);}
9
9
  const {loadJob,loadProject}=await import('./lib/project.mjs');
10
- const {referenceRoot,ensureReferenceDirectories,referenceGuide}=await import('./lib/refs.mjs');
10
+ const {referenceRoot,referenceGuide}=await import('./lib/refs.mjs');
11
11
  const {loadSettings,initSettings,externalPath}=await import('./lib/settings.mjs');
12
- const {analyzeStyle}=await import('./lib/analyze.mjs');
13
- const {validateReport,freezeCore,loadCore}=await import('./lib/core.mjs');
12
+ const {validateReport,loadCore}=await import('./lib/core.mjs');
14
13
  const {compileGenerate}=await import('./lib/generate.mjs');
15
14
  const {compileEdit}=await import('./lib/edit.mjs');
16
15
  const {validatePlan,selectItems}=await import('./lib/plan.mjs');
17
16
  const {executePlan,checkRun}=await import('./lib/executor.mjs');
18
17
  const {agentIndex,agentDocs,syncSkill,autoSync}=await import('./lib/agent.mjs');
19
18
  const {backendDefaults,bindBackend,buildComfyRequest}=await import('./lib/backends.mjs');
20
- const {startTask,taskStatus,taskView,waitTask,cancelTask,shutdown}=await import('./lib/tasks.mjs');
19
+ const {startTask,taskStatus,taskView,recoverTask,resumeTask,waitTask,cancelTask,shutdown}=await import('./lib/tasks.mjs');
21
20
  const {runtimeRoot,tasks}=await import('./lib/runtime.mjs');
22
21
  const {validateConfiguration,doctor}=await import('./lib/diagnostics.mjs');
22
+ const {createProject,createObject,listObjects,readObject,updateObject,deriveObject,discardObject,importReference,removeReference,updateReference,taskDisplayState,STYLE_CATEGORIES,TASK_PURPOSES}=await import('./lib/workspace.mjs');
23
+ const {startAnalysis,adoptStyle,recoverStyleAdoption}=await import('./lib/style-lifecycle.mjs');
24
+ const {candidates,finalize,deleteCandidate,finalizations,editFromCandidate}=await import('./lib/candidates.mjs');
25
+ const {upgradeProject}=await import('./lib/migration.mjs');
23
26
  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]);
27
+ const {jobTemplate}=await import('./lib/templates.mjs');
28
+ const {deploymentPlan,startDeployment,deploymentStatus,cancelDeployment,recoverDeployment}=await import('./lib/deployment.mjs');
29
+ const flags=new Set(['dry','explore','background','start','replace','confirm','all-variants']);
30
+ const allowed=new Set(['config','workspace','output-dir','refs-dir','cache-dir','directory','endpoint','project','input','out','report','note','core','job','plan','item','variant','offset','limit','file','backend','timeout','kind','id','revision','source','category','purposes','mapping','run','candidate','actor','operation','retry-run',...flags]);
26
31
  for(let i=0;i<args.length;i++){if(args[i].startsWith('--')){const k=args[i].slice(2);if(!allowed.has(k)||k in options) throw new Error('未知或重复参数 '+k);options[k]=flags.has(k)?true:args[++i];if(options[k]===undefined) throw new Error('参数缺少值 '+k);}else pos.push(args[i]);}
27
32
  const print=x=>console.log(JSON.stringify(x,null,2));
28
33
  if(pos[0]==='workflow'&&pos[1]==='list'){print(workflowList());process.exit(0);}
@@ -40,17 +45,49 @@ function required(k){const value=options[k]??(k==='project'?settings.defaultProj
40
45
  function manifestPath(value){const p=externalPath(resolve(settings.paths.output,value));return p.endsWith('.json')?p:join(p,'manifest.json');}
41
46
  try {
42
47
  const [module,action]=pos;
43
- ensureReferenceDirectories(settings.paths.refs);
44
- const selectedProject=options.project??(['refs','style','generate','edit'].includes(module)?settings.defaultProject:undefined);
45
- const effectiveRefs=selectedProject?referenceRoot({workspace:ROOT,defaultRefsDir:settings.paths.refs,refsDir:options['refs-dir']?settings.paths.refs:undefined,project:loadProject(selectedProject,ROOT)}):settings.paths.refs;
46
- ensureReferenceDirectories(effectiveRefs);
47
- if(settings.autoSyncSkills&&!options.dry&&['style','generate','edit'].includes(module)&&['analyze','freeze','run'].includes(action)){try{autoSync();}catch(error){console.error('skill 自动同步失败:'+error.message+';可用 agent init 重试。');}}
48
- if(module==='config'){
48
+
49
+ const effectiveRefs=referenceRoot({defaultRefsDir:settings.paths.refs});
50
+ if(settings.autoSyncSkills&&!options.dry&&['style','generate','edit'].includes(module)&&['analyze','adopt','run'].includes(action)){try{autoSync();}catch(error){console.error('skill 自动同步失败:'+error.message+';可用 agent init 重试。');}}
51
+ if(module==='deployment'){
52
+ if(action==='plan'){const plan=deploymentPlan(settings,{directory:required('directory'),endpoint:options.endpoint});if(options.out)writeJson(path(options.out),plan);print(plan);}
53
+ else if(action==='start')print(await startDeployment(settings,readJson(path(required('plan'))),{operationId:required('operation')}));
54
+ else if(action==='status')print(deploymentStatus(settings,required('id')));
55
+ else if(action==='cancel')print(cancelDeployment(settings,required('id')));
56
+ else if(action==='recover')print(await recoverDeployment(settings,required('operation')));
57
+ else throw new Error('未知 deployment 操作');
58
+ }
59
+ else if(module==='config'){
49
60
  if(action==='path') console.log(settings.file);
50
61
  else if(action==='show') print(settings);
51
62
  else if(action==='init') print(initSettings(settings.file));
52
63
  else throw new Error('未知 config 操作');
53
64
  }
65
+ else if(module==='project'){
66
+ if(action==='upgrade')print(await upgradeProject(ROOT,required('project'),{dry:options.dry,settings,referenceAssignments:options.mapping?readJson(path(options.mapping)):undefined}));
67
+ else if(action==='init')print(await createProject(settings,required('project'),readJson(path(required('input')))));
68
+ else throw new Error('未知 project 操作');
69
+ }
70
+ else if(module==='reference'){
71
+ const projectId=required('project'),kind=required('kind'),objectId=required('id');
72
+ if(action==='list')print(readObject(ROOT,projectId,kind,objectId).references);
73
+ else if(action==='import')print(await importReference(settings,projectId,kind,objectId,Number(required('revision')),{source:required('source'),category:options.category,purposes:options.purposes?.split(','),note:options.note??''}));
74
+ else if(action==='remove')print(await removeReference(settings,projectId,kind,objectId,Number(required('revision')),required('item')));
75
+ else if(action==='update')print(await updateReference(settings,projectId,kind,objectId,Number(required('revision')),required('item'),readJson(path(required('input')))));
76
+ else throw new Error('未知 reference 操作');
77
+ }
78
+ else if(module==='job'||module==='style'&&['create','list','update','derive','discard','read'].includes(action)){
79
+ const projectId=required('project'),kind=module==='job'?'task':'style';
80
+ if(action==='template'&&kind==='task')print(jobTemplate(ROOT,projectId,{kind:options.kind,core:options.core}));
81
+ else if(action==='from-candidate'&&kind==='task')print(await editFromCandidate(settings,projectId,required('id'),{runId:required('run'),candidateId:required('candidate')}));
82
+ else if(action==='list'){const records=listObjects(ROOT,projectId,kind),runs=kind==='task'?tasks(runtimeRoot(settings)).map(t=>taskStatus(runtimeRoot(settings),t.taskId)):[];print(records.map(record=>kind==='task'?{...record,display:taskDisplayState(record,runs,record.finalizations??[])}:record));}
83
+ else if(action==='create')print(await createObject(settings,projectId,kind,readJson(path(required('input')))));
84
+ else if(action==='read')print(readObject(ROOT,projectId,kind,required('id')));
85
+ else if(action==='update')print(await updateObject(settings,projectId,kind,required('id'),Number(required('revision')),readJson(path(required('input')))));
86
+ else if(action==='analyze'&&kind==='task')print(await startAnalysis(settings,projectId,required('id'),Number(required('revision')),{dry:options.dry,kind:'task',operationId:options.operation}));
87
+ else if(action==='derive')print(await deriveObject(settings,projectId,kind,required('id'),Number(required('revision'))));
88
+ else if(action==='discard')print(await discardObject(settings,projectId,kind,required('id'),Number(required('revision'))));
89
+ else throw new Error('未知对象操作');
90
+ }
54
91
  else if(module==='refs'){
55
92
  if(action!=='guide') throw new Error('未知 refs 操作;使用 refs guide');
56
93
  console.log(referenceGuide(effectiveRefs));
@@ -64,9 +101,10 @@ try {
64
101
  else if(module==='list'){print((existsSync(join(ROOT,'projects'))?readdirSync(join(ROOT,'projects')):[]).map(id=>readJson(join(ROOT,'projects',id,'project.json'))));}
65
102
  else if(module==='style'){
66
103
  const projectId=required('project');
67
- if(action==='analyze'){const result=analyzeStyle({projectId,input:readJson(path(required('input'))),out:options.out?path(options.out):undefined,root:ROOT,refsDir:options['refs-dir']?settings.paths.refs:undefined,defaultRefsDir:settings.paths.refs,cacheDir:join(settings.paths.cache,'analysis'),analysisModel:settings.analysisModel,dry:options.dry});print(result);}
104
+ if(action==='analyze')print(await startAnalysis(settings,projectId,required('id'),Number(required('revision')),{dry:options.dry,operationId:options.operation}));
105
+ else if(action==='recover')print(await recoverStyleAdoption(settings,projectId,required('id')));
106
+ else if(action==='adopt')print(await adoptStyle(settings,projectId,required('id'),Number(required('revision')),{note:options.note}));
68
107
  else if(action==='validate') print(validateReport(readJson(path(required('report'))),projectId));
69
- else if(action==='freeze') print(freezeCore({projectId,report:readJson(path(required('report'))),note:options.note,root:ROOT}));
70
108
  else if(action==='show') print(loadCore(projectId,required('core'),ROOT));
71
109
  else throw new Error('未知 style 操作');
72
110
  }else if(['generate','edit'].includes(module)){
@@ -77,27 +115,33 @@ try {
77
115
  else plan=bindBackend((module==='generate'?compileGenerate:compileEdit)({projectId:required('project'),jobId:required('job'),coreId:options.core,root:ROOT,localExecution:backendDefaults(settings,options.backend)}),settings,options.backend);
78
116
  if(action==='plan'){if(options.out) writeJson(path(options.out),plan);print(plan);}
79
117
  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)});
118
+ if(options['retry-run']&&(options.dry||options.variant||options.item||options.offset||options.limit))throw new Error('失败项重试不能混用预演或手动筛选');
119
+ if(options.variant&&options['all-variants'])throw new Error('不能同时选择单个候选与全部候选');
120
+ const variant=options.variant??(options.explore||options['all-variants']?undefined:'base');const items=selectItems(plan,{item:options.item,variant,offset:options.offset===undefined?0:Number(options.offset),limit:options.limit===undefined?undefined:Number(options.limit)});
81
121
  if(options.dry){if(plan.backend?.provider==='comfyui')print({dry:true,remoteCalls:0,planHash:plan.planHash,requests:items.map(item=>({itemId:item.itemId,variantId:item.variantId,requests:Array.from({length:(item.execution??plan.execution).perValue},(_,index)=>buildComfyRequest(plan,item,{index}))}))});else executePlan(plan,items,{outputRoot:settings.paths.output,dry:true});}
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;}}
122
+ else {const task=await startTask(plan,items,settings,{operationId:options.operation,retryRun:options['retry-run']??null});if(options.background)print(task);else {console.log('task → '+task.taskId);const result=await waitTask(runtimeRoot(settings),task.taskId);print(taskView(result));if(result.status!=='succeeded')process.exitCode=1;}}
83
123
  }
84
124
  }else throw new Error('未知模块操作');
85
125
  }else if(module==='task'){
86
126
  const root=runtimeRoot(settings),taskId=pos[2];
87
- if(action==='list')print(tasks(root).map(t=>taskView(taskStatus(root,t.taskId))));
127
+ if(action==='list')print(tasks(root).filter(t=>!options.project||(t.plan?.project??t.project)===options.project).map(t=>taskView(taskStatus(root,t.taskId))));
128
+ else if(action==='recover')print(recoverTask(root,required('project'),required('operation')));
88
129
  else if(action==='status')print(taskView(taskStatus(root,taskId)));
130
+ else if(action==='resume')print(await resumeTask(root,taskId));
89
131
  else if(action==='cancel')print(taskView(await cancelTask(root,taskId)));
90
132
  else if(action==='wait'){const timeoutSeconds=options.timeout===undefined?3600:Number(options.timeout);if(!Number.isFinite(timeoutSeconds)||timeoutSeconds<=0)throw new Error('timeout 必须为正秒数');const result=await waitTask(root,taskId,{timeoutSeconds});print(taskView(result));if(result.status!=='succeeded')process.exitCode=1;}
91
133
  else throw new Error('未知 task 操作');
92
134
  }else if(module==='shutdown'){if(action)throw new Error('shutdown 不接受位置参数');print(await shutdown(settings));}
93
- else if(['check','select'].includes(module)){
94
- const file=manifestPath(action??required('file')),manifest=readJson(file);
95
- const review=options.review?readJson(path(options.review)):manifest.review;
96
- const rows=checkRun(manifest,file,review);
97
- if(module==='check'){if(options.out) writeJson(path(options.out),rows);print(rows);}
98
- else {const matched=rows.filter(x=>x.itemId===required('item')&&x.variantId===required('variant')&&(!options.file||x.file===options.file));if(matched.length!==1||!matched[0].accepted) throw new Error('只能选择唯一且全部验收通过的产物');manifest.review=rows;manifest.selections[options.item]=matched[0];writeJson(file,manifest);print(matched[0]);}
135
+ else if(module==='candidate'){
136
+ const projectId=required('project'),jobId=required('job');
137
+ if(action==='list')print(candidates(settings,projectId,jobId,required('run')));
138
+ else if(action==='finalize')print(await finalize(settings,projectId,jobId,Number(required('revision')),{runId:required('run'),candidateId:required('candidate'),replace:options.replace,actor:required('actor')}));
139
+ else if(action==='delete')print(await deleteCandidate(settings,projectId,jobId,Number(required('revision')),{runId:required('run'),candidateId:required('candidate'),confirm:options.confirm,actor:required('actor')}));
140
+ else if(action==='finalizations')print(finalizations(settings,projectId,jobId));
141
+ else throw new Error('未知 candidate 操作');
142
+ }else if(module==='check'){print(checkRun(readJson(manifestPath(action??required('file'))),manifestPath(action??required('file'))));
99
143
  }else if(module==='compare'){const read=value=>{const data=readJson(path(value));const plan=data.plan??data;validatePlan(plan);return plan;};const a=read(action),b=read(pos[2]);print({sameCore:a.sources.coreHash===b.sources.coreHash,execution:{before:a.execution,after:b.execution},items:b.items.map(x=>({itemId:x.itemId,variantId:x.variantId,changed:a.items.find(y=>y.itemId===x.itemId&&y.variantId===x.variantId)?.inputHash!==x.inputHash}))});}
100
144
  else if(!module||module==='help') console.log(help);
101
145
  else throw new Error('未知模块或旧入口:'+module);
102
- }catch(e){if(e.diagnostic)print({ok:false,error:e.message,diagnostic:e.diagnostic});else console.error(e.message);process.exitCode=1;}
146
+ }catch(e){print({ok:false,error:e.message,...(e.diagnostic?{diagnostic:e.diagnostic}:{})});process.exitCode=1;}
103
147
  }