@kevlns/art-workshop 0.1.3 → 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.
- package/AGENTS.md +33 -12
- package/README.md +33 -135
- package/art-workshop.mjs +95 -25
- package/docs/commands.md +915 -0
- package/docs/configuration.md +60 -0
- package/docs/core-guidance.md +80 -13
- package/docs/data-formats.md +29 -0
- package/docs/deployment.md +40 -0
- package/docs/model-architecture.md +52 -0
- package/docs/modes.md +39 -0
- package/docs/remote-models.md +42 -0
- package/docs/troubleshooting.md +46 -0
- package/lib/adapters/dashscope.mjs +234 -0
- package/lib/adapters/index.mjs +28 -0
- package/lib/agent.mjs +3 -2
- package/lib/analysis-worker.mjs +25 -0
- package/lib/analyze.mjs +8 -8
- package/lib/backends.mjs +365 -0
- package/lib/bl.mjs +3 -18
- package/lib/candidates.mjs +82 -0
- package/lib/comfyui.mjs +64 -0
- package/lib/contracts.d.ts +67 -0
- package/lib/deployment-worker.mjs +97 -0
- package/lib/deployment.mjs +72 -0
- package/lib/design.mjs +5 -5
- package/lib/diagnostics.mjs +83 -0
- package/lib/dimensions.mjs +22 -0
- package/lib/edit.mjs +6 -3
- package/lib/environments.mjs +67 -0
- package/lib/execution/remote.mjs +156 -0
- package/lib/executor.mjs +10 -24
- package/lib/generate.mjs +9 -5
- package/lib/generation-policy.mjs +198 -0
- package/lib/images.mjs +10 -0
- package/lib/lifecycle.mjs +40 -0
- package/lib/migration.mjs +154 -0
- package/lib/model-catalog.mjs +288 -0
- package/lib/model-registry.mjs +234 -0
- package/lib/plan.mjs +98 -28
- package/lib/project.mjs +13 -4
- package/lib/providers.mjs +30 -0
- package/lib/refs.mjs +12 -16
- package/lib/runtime.mjs +25 -0
- package/lib/service.mjs +137 -0
- package/lib/settings.mjs +5 -6
- package/lib/shared.mjs +12 -2
- package/lib/style-lifecycle.mjs +72 -0
- package/lib/task-references.mjs +35 -0
- package/lib/task-worker.mjs +233 -0
- package/lib/tasks.mjs +458 -0
- package/lib/templates.mjs +69 -0
- package/lib/transport/cli.mjs +69 -0
- package/lib/transport/http.mjs +82 -0
- package/lib/vision.mjs +46 -0
- package/lib/workflows.mjs +28 -0
- package/lib/workspace.mjs +190 -0
- package/package.json +14 -6
- package/skills/art-workshop/SKILL.md +27 -27
- package/v-cli.plugin.json +1484 -135
- package/workflows/vant-builtin-qwen-image-2.1-Q4-8GB.api.json +116 -0
- package/workflows/vant-builtin-qwen-image-2.1-Q4-8GB.json +648 -0
package/AGENTS.md
CHANGED
|
@@ -1,19 +1,40 @@
|
|
|
1
|
-
#
|
|
1
|
+
# art Agent 调用规范
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
用户既有授权与偏好持续有效;查询和预演不授权生成或采用。规范与实时参数通过 v-cli agent docs art 和 v-cli agent describe art --json 获取。
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## 对象与参考
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
-
|
|
10
|
-
- 计划与 dry 不调用远程模型,不产生图片;真实分析与生成会调用 bl 并产生费用。修改需求后重新编译,不手改冻结计划。
|
|
11
|
-
- check 导出或汇总人工验收,分别检查 content/style/asset;三项全部通过且完整性有效才可 select。工具不自动评价图片。
|
|
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;编辑底图另列。导入复制原图,不修改用户文件。未适配直接参考时拒绝,不隐式上传风格图片。
|
|
12
10
|
|
|
13
|
-
##
|
|
11
|
+
## 风格生命周期
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
style create/read/update/derive/discard 管理草稿。style analyze --dry 只读编译,不联网、启动服务或创建参考目录。实际 analyze 创建 taskId 与独立参考证据;task status/wait/cancel 控制执行,recover 查原登记,resume 仅恢复远程查询与取回。
|
|
14
|
+
报告绑定源配置、参考与模型。更新配置会清除当前报告,旧证据保留。style adopt 校验源版本、报告身份、冲突与未确定项,用户采用后冻结。采用中断通过 style recover 完成已授权事务,不能重新冻结另一份核心。
|
|
15
|
+
退出风格配置先继续编辑、保存草稿或放弃;分析停止未确认时不能清理。
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
## 计划与执行
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
先读取实际 job,再 generate/edit plan 和 run --plan --dry,展示有效核心、设计尺寸、预留缩放、请求与实际像素、模型后端、候选数量和编辑底图。后端尺寸由工具统一解析,超限或未对齐选最近合法尺寸,保留设计基准并明确实际值;不承诺显存或自动缩放导出。
|
|
20
|
+
授权覆盖方案后使用 run --background;前台同样创建执行身份。配置、核心、规格、参考、底图和后端变化拒绝旧方案,重新编译。重启查 taskId,不重复提交。不自动换模型或重跑成功项。
|
|
21
|
+
每个任务只能有一个未停止确认的执行;编辑、派生、删除与运行共用状态检查。切页面不取消。
|
|
22
|
+
|
|
23
|
+
## 取消、异常和关闭
|
|
24
|
+
|
|
25
|
+
任务状态与停止证据分开。queued/running/cancelling 仍占用资源;unknown 或 stopConfirmed=false 保留资源。failed/cancelled 也不能单凭状态释放资源;dispatching/accepted 远程回执尚未结清时继续占用。工作进程丢失标记 unknown,不推测停止。
|
|
26
|
+
task cancel 只取消指定运行,保留服务。远程取消只停止本地客户端,上游停止未知如实报告,不允许清理。shutdown 阻止提交、停止关联任务、核验共享队列和进程身份后关闭本地服务,不清空共享队列;有其他任务或停止未确认时保留服务。不得广泛杀所有 Python。
|
|
27
|
+
|
|
28
|
+
## 生成与定版
|
|
29
|
+
|
|
30
|
+
只有生成与定版两个产品阶段。check 验证计划、执行身份、文件哈希和完成事实;不要求人工 content/style/asset 评分。candidate finalize 按资产选定候选,重复操作幂等;替换已有定版需要明确 replace,保留历史。
|
|
31
|
+
candidate delete 先确认影响,拒绝运行中或被计划/底图引用的候选;先记删除事实,清理所属文件,并取消关联定版。定版不自动导入游戏或提交 Git。
|
|
32
|
+
|
|
33
|
+
## 验证和技能
|
|
34
|
+
|
|
35
|
+
本地先 config validate、doctor、plan/dry,再按授权真实生成与编辑。配置有效、服务可连接与真实出图是不同证据。远程核对实际认证和模型入口;凭证不得写入项目、计划、日志或命令行。
|
|
36
|
+
随包 skills/art-workshop 是技能源;通过 agent init 或 skill:sync 同步,保留项目扩展。查询和预演不自动同步。源码/单测/mock 不能代替真实模型、图像、桌面与安装验证。
|
|
37
|
+
|
|
38
|
+
模型、参数及支持状态只在 art 工具 model-catalog/model-registry 内维护,界面与 v-cli 不复制型号判断。远程图片由已注册协议适配器直接调用;视觉分析连接独立,未注入时使用百炼 CLI。Token Plan 是渠道,DashScope 是协议,不跨站点回退凭据。
|
|
39
|
+
|
|
40
|
+
远端上游身份持久化后才能轮询。`task resume TASK` 只恢复原身份查询与取回,不重发生成;无回执或仍处于 dispatching 的提交保持未知。界面与保存共用 modelEligibility,展示字段不进入执行契约。
|
package/README.md
CHANGED
|
@@ -1,150 +1,48 @@
|
|
|
1
1
|
# 美术工坊
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
面向游戏资产的风格分析、图片生成与编辑工具。风格和任务按工程隔离,计划可预演,执行可追踪,候选按资产定版。产品流程只有「生成 → 定版」;完整性检查不会引入人工评分阶段。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
通过 `v-cli art` 使用,或直接运行 `art-workshop`。需要 Node.js >=20.9。安装不会创建工程、下载模型或生成图片;安装脚本会同步已有 Agent 技能目录中的随包技能。
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
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
|
-
配置结构:
|
|
26
|
-
|
|
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 解析。
|
|
47
|
-
|
|
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。构图、文字、姿态的具体要求属于单体计划,不自动冻结进核心。
|
|
51
|
-
|
|
52
|
-
```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
|
|
7
|
+
```sh
|
|
8
|
+
npm install -g @kevlns/v-cli
|
|
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
|
|
57
14
|
```
|
|
58
15
|
|
|
59
|
-
##
|
|
60
|
-
|
|
61
|
-
顶层指导规则:rules/core-guidance.json。工程配置位于 projects/<project>/project.json;briefs 保存分析输入,reports 保存报告,cores 保存冻结核心,profiles 保存资产规格,jobs 保存真实需求。这些目录位于外部工作目录,不属于工具安装目录。输出默认位于系统下载目录的 image.g,参考图与缓存也使用外部路径。
|
|
16
|
+
## 使用流程
|
|
62
17
|
|
|
63
|
-
|
|
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`,均保留事实记录。
|
|
64
23
|
|
|
65
|
-
|
|
24
|
+
正式风格只读,修改需派生。任务空闲后可按原身份更新配置,历史批次不覆写。状态优先级为待定版、执行中、已定版、草稿;运行状态与停止证据分别判断,不能只看终态释放占用。
|
|
66
25
|
|
|
67
|
-
|
|
26
|
+
## 后端与数据归属
|
|
68
27
|
|
|
69
|
-
|
|
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
|
-
```
|
|
28
|
+
本地为 ComfyUI 内置 Qwen Image 2.1 Q4、CPU 文本编码器方案,支持生成和显式底图编辑。自定义 API workflow 需要明确 bindings 与完整适配,不能把任意导入工作流视为可执行。
|
|
76
29
|
|
|
77
|
-
|
|
30
|
+
远程图片通过工具登记的协议适配器直接调用,目前登记 DashScope。模型、参数与支持状态由 art 内部登记表维护,Vant 读取同一目录,不复制型号判断。分析使用独立视觉模型连接;未注入视觉连接时使用百炼 CLI。Token Plan 是渠道,DashScope 是协议,不能据协议擅自替换实例地址和凭据。
|
|
78
31
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
## 文生图
|
|
82
|
-
|
|
83
|
-
任务 kind 为 generate,core 绑定风格,profile 绑定资产规格。items 声明 intent、entities、effects、relations、composition、mustRead、seed 与 variants。候选只调整构图和 seed。
|
|
84
|
-
|
|
85
|
-
核心选择顺序:显式 --core → 任务 core → 工程 defaultCore。显式指定与任务绑定冲突时报错,须先修改任务绑定。没有明确选择时不能猜测。计划保存核心身份、哈希、选择依据与完整快照。
|
|
86
|
-
|
|
87
|
-
```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
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
plan 编译全部候选;run 默认 base,--variant 选指定候选,--explore 执行全部候选。修改任务后重新 plan,冻结计划不能同时修改来源配置。
|
|
96
|
-
|
|
97
|
-
背景默认 {type:solid,color:#FFFFFF},纯黑用 #000000。其他纯色可显式配置,渐变用 gradient/from/to,场景用 scene/description 且须被资产规格允许。背景提示词和验收共用解析结果。
|
|
98
|
-
|
|
99
|
-
## 图编辑
|
|
100
|
-
|
|
101
|
-
任务 kind 为 edit,每项有 source、changes、preserve、mustRead、可选 seed。范围为 background/style/shape/color/composition/content/detail/text;同一范围不能同时修改和保留。背景修改用结构化 value,其他范围用 instruction。
|
|
102
|
-
|
|
103
|
-
```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
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
编辑默认保留原图风格,不自动读取工程默认核心或替换背景。目标风格须明确绑定 core,此时不能再写 style 修改或保留。原图哈希写入计划,原图改变后须重新预演。示例任务将已有 skill-01 改成纯白背景,保留主体、效果和构图。
|
|
111
|
-
|
|
112
|
-
## 预演与验收
|
|
113
|
-
|
|
114
|
-
plan 与 run --dry 均不调用远程生图,分别返回完整编译快照与选定项实际请求参数,不生成图片。分析 --dry 返回预计请求,实际远程调用数为 0。
|
|
115
|
-
|
|
116
|
-
实际 run 保存图片、输入和输出哈希、失败记录。人工分别检查 content/style/asset,产物完整、生成成功且三个维度全部 pass 才能 select。check 汇总人工验收,不自动评价图像。
|
|
117
|
-
|
|
118
|
-
```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
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
依赖 Node.js 与已配置的 bailian-cli。历史图片保留供对照,旧配置和旧计划接口不再支持。真实模型效果需另行实测。
|
|
128
|
-
|
|
129
|
-
## v-cli 接入
|
|
130
|
-
|
|
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 设计分辨率与单体出图尺寸
|
|
133
|
-
|
|
134
|
-
UI 设计基准属于资产规格,不写进冻结风格核心。文生图 profile 可声明:
|
|
135
|
-
|
|
136
|
-
```json
|
|
137
|
-
"design": { "resolution": { "width": 1920, "height": 1080 }, "outputScale": 2 }
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
任务 item 可声明独立控件尺寸与可选倍率:
|
|
141
|
-
|
|
142
|
-
```json
|
|
143
|
-
"design": { "width": 240, "height": 80, "outputScale": 4 }
|
|
144
|
-
```
|
|
32
|
+
应用数据根默认 `~/.vant`,可由 `VANT_HOME` 覆盖。工具配置为 `~/.vant/tools/art-workshop/config.json`;Vant 将工程美术数据绑定至工程 `.vant/art`。共享模型环境默认 `~/.vant/art-env`,控制状态与日志归用户数据根;安装根保存环境标记 `vant.art.config.json`。
|
|
145
33
|
|
|
146
|
-
|
|
34
|
+
## 文档
|
|
147
35
|
|
|
148
|
-
|
|
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) | 风格与需求的职责边界 |
|
|
149
47
|
|
|
150
|
-
|
|
48
|
+
开发校验:`npm run docs:generate`、`npm run check`、`npm run test:package`。模拟测试、配置有效和服务可连接都不能代替真实出图;文档更新不代表新包已发布或桌面安装已更新。
|
package/art-workshop.mjs
CHANGED
|
@@ -4,40 +4,90 @@ 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/
|
|
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,
|
|
10
|
+
const {referenceRoot,referenceGuide}=await import('./lib/refs.mjs');
|
|
11
11
|
const {loadSettings,initSettings,externalPath}=await import('./lib/settings.mjs');
|
|
12
|
-
const {
|
|
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
|
-
const
|
|
20
|
-
const
|
|
18
|
+
const {backendDefaults,bindBackend,buildComfyRequest}=await import('./lib/backends.mjs');
|
|
19
|
+
const {startTask,taskStatus,taskView,recoverTask,resumeTask,waitTask,cancelTask,shutdown}=await import('./lib/tasks.mjs');
|
|
20
|
+
const {runtimeRoot,tasks}=await import('./lib/runtime.mjs');
|
|
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');
|
|
26
|
+
const {workflowList}=await import('./lib/workflows.mjs');
|
|
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]);
|
|
21
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]);}
|
|
22
32
|
const print=x=>console.log(JSON.stringify(x,null,2));
|
|
23
|
-
|
|
33
|
+
if(pos[0]==='workflow'&&pos[1]==='list'){print(workflowList());process.exit(0);}
|
|
34
|
+
let settings;
|
|
35
|
+
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']});}
|
|
36
|
+
catch(error){print({ok:false,stage:'configuration',issues:[{code:'configuration',message:error.message}]});process.exit(1);}
|
|
37
|
+
if(pos[0]==='config'&&pos[1]==='validate'||pos[0]==='doctor'){
|
|
38
|
+
if(pos[0]==='doctor'&&pos[1])throw new Error('doctor 不接受位置参数');
|
|
39
|
+
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;
|
|
40
|
+
}else{
|
|
41
|
+
if(options.start)throw new Error('--start 仅用于 doctor');
|
|
24
42
|
const ROOT=settings.paths.workspace;
|
|
25
43
|
const path=x=>externalPath(resolve(ROOT,x),'资源文件');
|
|
26
44
|
function required(k){const value=options[k]??(k==='project'?settings.defaultProject:undefined);if(!value) throw new Error('需要 --'+k);return value;}
|
|
27
45
|
function manifestPath(value){const p=externalPath(resolve(settings.paths.output,value));return p.endsWith('.json')?p:join(p,'manifest.json');}
|
|
28
46
|
try {
|
|
29
47
|
const [module,action]=pos;
|
|
30
|
-
|
|
31
|
-
const
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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'){
|
|
36
60
|
if(action==='path') console.log(settings.file);
|
|
37
61
|
else if(action==='show') print(settings);
|
|
38
62
|
else if(action==='init') print(initSettings(settings.file));
|
|
39
63
|
else throw new Error('未知 config 操作');
|
|
40
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
|
+
}
|
|
41
91
|
else if(module==='refs'){
|
|
42
92
|
if(action!=='guide') throw new Error('未知 refs 操作;使用 refs guide');
|
|
43
93
|
console.log(referenceGuide(effectiveRefs));
|
|
@@ -51,27 +101,47 @@ try {
|
|
|
51
101
|
else if(module==='list'){print((existsSync(join(ROOT,'projects'))?readdirSync(join(ROOT,'projects')):[]).map(id=>readJson(join(ROOT,'projects',id,'project.json'))));}
|
|
52
102
|
else if(module==='style'){
|
|
53
103
|
const projectId=required('project');
|
|
54
|
-
if(action==='analyze')
|
|
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}));
|
|
55
107
|
else if(action==='validate') print(validateReport(readJson(path(required('report'))),projectId));
|
|
56
|
-
else if(action==='freeze') print(freezeCore({projectId,report:readJson(path(required('report'))),note:options.note,root:ROOT}));
|
|
57
108
|
else if(action==='show') print(loadCore(projectId,required('core'),ROOT));
|
|
58
109
|
else throw new Error('未知 style 操作');
|
|
59
110
|
}else if(['generate','edit'].includes(module)){
|
|
60
111
|
if(action==='show') print(loadJob(required('project'),required('job'),module,ROOT));
|
|
61
112
|
else if(['plan','run'].includes(action)){
|
|
62
113
|
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.
|
|
114
|
+
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('计划模块不匹配');}
|
|
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);
|
|
65
116
|
if(action==='plan'){if(options.out) writeJson(path(options.out),plan);print(plan);}
|
|
66
|
-
else {
|
|
117
|
+
else {
|
|
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)});
|
|
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});}
|
|
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;}}
|
|
123
|
+
}
|
|
67
124
|
}else throw new Error('未知模块操作');
|
|
68
|
-
}else if(
|
|
69
|
-
const
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
if(
|
|
73
|
-
else
|
|
125
|
+
}else if(module==='task'){
|
|
126
|
+
const root=runtimeRoot(settings),taskId=pos[2];
|
|
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')));
|
|
129
|
+
else if(action==='status')print(taskView(taskStatus(root,taskId)));
|
|
130
|
+
else if(action==='resume')print(await resumeTask(root,taskId));
|
|
131
|
+
else if(action==='cancel')print(taskView(await cancelTask(root,taskId)));
|
|
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;}
|
|
133
|
+
else throw new Error('未知 task 操作');
|
|
134
|
+
}else if(module==='shutdown'){if(action)throw new Error('shutdown 不接受位置参数');print(await shutdown(settings));}
|
|
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'))));
|
|
74
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}))});}
|
|
75
144
|
else if(!module||module==='help') console.log(help);
|
|
76
145
|
else throw new Error('未知模块或旧入口:'+module);
|
|
77
|
-
}catch(e){
|
|
146
|
+
}catch(e){print({ok:false,error:e.message,...(e.diagnostic?{diagnostic:e.diagnostic}:{})});process.exitCode=1;}
|
|
147
|
+
}
|