@kevlns/art-workshop 0.3.6 → 0.3.8
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 +40 -10
- package/LICENSE +1 -1
- package/README.md +40 -25
- package/art-workshop.mjs +1 -1
- package/docs/commands.md +79 -65
- package/docs/configuration.md +31 -9
- package/docs/core-guidance.md +22 -6
- package/docs/data-formats.md +30 -8
- package/docs/deployment.md +23 -5
- package/docs/documentation.md +24 -0
- package/docs/model-architecture.md +28 -6
- package/docs/modes.md +28 -10
- package/docs/remote-models.md +27 -5
- package/docs/troubleshooting.md +21 -7
- package/package.json +6 -5
- package/skills/art-workshop/SKILL.md +44 -10
- package/v-cli.plugin.json +1 -1
package/docs/data-formats.md
CHANGED
|
@@ -1,20 +1,30 @@
|
|
|
1
|
-
# art 工程与输入结构
|
|
1
|
+
# Vant art 工程与输入结构
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
art 工程与输入结构,适用于当前随包实现。
|
|
6
|
+
|
|
7
|
+
## 前置条件
|
|
8
|
+
|
|
9
|
+
先按包的环境要求准备工程与工具,使用实际配置和命令帮助核对目标。
|
|
10
|
+
|
|
11
|
+
## 字段与示例
|
|
12
|
+
|
|
13
|
+
### 工程和对象
|
|
4
14
|
|
|
5
15
|
project.json 必须声明 schemaVersion=2、revision、id、name、analysisModel、execution、cores、defaultCore。工程身份与目录匹配,核心必须属于同一工程。
|
|
6
16
|
|
|
7
17
|
projects/<projectId>/styles/<styleId>/style.json 与 tasks/<taskId>/task.json 使用 schema=art-workshop/style 或 art-workshop/task,schemaVersion=2、稳定 id、project、展示 name、revision、status、createdAt/updatedAt、config、references 和 report。正式风格的 core.json 不可原地覆写。任务的 config.kind 是 generate/edit,不能改身份与类型。
|
|
8
18
|
|
|
9
|
-
参考记录包括 id
|
|
19
|
+
参考记录包括 id、所属对象、对象内相对 path、SHA256、来源、category/purposes、usage、note、ignore。风格三类:style、palette、rendering。任务用途:subject、composition、pose、identity-color、surface、scene-light、text。sources 只放编辑底图。
|
|
10
20
|
|
|
11
|
-
|
|
21
|
+
### 需求与计划
|
|
12
22
|
|
|
13
23
|
生成 config 包括 project、kind、core、execution、items,以及互斥的 profile 或内联 asset 规格;实体及效果有稳定 id、数量、颜色、角色与关系。具体主体、构图、动作不冻结进风格。规格定义资产约束、设计基准与检查要点,内联规格属于当前任务,编译时形成同一不可变快照。编辑 config 的 items 明确 source、changes、preserve、mustRead、seed。
|
|
14
24
|
|
|
15
25
|
plan 包括 schema=art-workshop/plan、module/project/job、sources、snapshots、refs、execution、items、planHash。sources 绑定 taskRevision、taskConfigHash 和 coreHash;项目/核心/profile/任务形成快照。项含 inputHash、实际尺寸和 seed。任何来源或哈希变化拒绝运行。
|
|
16
26
|
|
|
17
|
-
|
|
27
|
+
### 执行与定版
|
|
18
28
|
|
|
19
29
|
对象 taskId(命令中称 job/id)与执行 taskId 是两种身份;每次真实执行有独立登记。运行记录包含 queued/running/cancelling/succeeded/failed/cancelled/unknown、heartbeat、workerPid、后端身份、manifestPath、stopConfirmed 与 unsettled。终态与停止证据独立;没有停止证据继续占用对象。配置状态及界面分组不能取代运行身份。
|
|
20
30
|
|
|
@@ -24,8 +34,20 @@ manifest 保存计划、每项输出及哈希、失败证据和完成事实。
|
|
|
24
34
|
|
|
25
35
|
task recover 根据工程和 operationId 找回唯一原执行;task resume 沿用原执行和 manifest,仅处理已有上游身份。retry-run 则创建新批次并记录 retryOf。三种身份流不能混用,详见 [任务控制](troubleshooting.md)。
|
|
26
36
|
|
|
27
|
-
旧格式只通过 project upgrade 显式转换,有备份与原子替换;共享图片须人工映射,不能猜测后删除。
|
|
28
37
|
|
|
29
|
-
升级事务登记在 workspace/.runtime/upgrades/<projectId>.json。替换中断后只通过显式 project upgrade 恢复原备份并重新转换;日常读写拒绝未完成事务。编辑源导入新对象私有 sources;历史快照保留旧事实。历史同资产多次批准须在 mapping 的 selections 中提供 task/assetId/runId/file/variantId,明确当前正式选择,其余保留替换历史,不猜测最近一张。
|
|
30
38
|
|
|
31
|
-
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
风格报告与 core.json 使用 schemaVersion=3。recommendation.rules 保存带主题、强度和条件的定性规则,issues 保存具体决策选项,decisions 保存已确认取舍,notes 保存不阻塞的提醒。style list/read 返回 review(ready、stale、openIssues、reason、有效 recommendation)及 compatibility。对象存储使用 schemaVersion=2。详细字段见 core-guidance.md。
|
|
42
|
+
|
|
43
|
+
## 执行边界
|
|
44
|
+
|
|
45
|
+
字段、路径与权限以当前 schema、运行时校验和明确授权为准;配置有效不等于外部服务已执行成功。
|
|
46
|
+
|
|
47
|
+
## 结果验证
|
|
48
|
+
|
|
49
|
+
结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
|
|
50
|
+
|
|
51
|
+
## 参考资料
|
|
52
|
+
|
|
53
|
+
[使用说明](../README.md)
|
package/docs/deployment.md
CHANGED
|
@@ -1,8 +1,18 @@
|
|
|
1
|
-
# 本地环境检测与部署
|
|
1
|
+
# Vant 本地环境检测与部署
|
|
2
|
+
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
本地环境检测与部署,适用于当前随包实现。
|
|
6
|
+
|
|
7
|
+
## 前置条件
|
|
8
|
+
|
|
9
|
+
先按包的环境要求准备工程与工具,使用实际配置和命令帮助核对目标。
|
|
10
|
+
|
|
11
|
+
## 操作流程
|
|
2
12
|
|
|
3
13
|
固定自动安装方案由 lib/deployment.mjs 的 LOCAL_RECIPE 维护:ComfyUI、GGUF 节点、Python/Torch 依赖以及三个模型的准确版本和 SHA256。自动部署当前只适配 Windows NVIDIA 环境;已有便携 Python 可复用,新建 venv 需要可用的 Python >=3.12。
|
|
4
14
|
|
|
5
|
-
|
|
15
|
+
### 目录与端口
|
|
6
16
|
|
|
7
17
|
Vant 检测窗口默认安装目录为 `<VANT_HOME 或 ~/.vant>/art-env`,允许选择其他目录及本机可用端口。已有便携安装应选择包含 ComfyUI 和 python_embeded 的根目录,而不是 models、ComfyUI 子目录或旧 .vant-art。
|
|
8
18
|
|
|
@@ -10,14 +20,14 @@ Vant 检测窗口默认安装目录为 `<VANT_HOME 或 ~/.vant>/art-env`,允
|
|
|
10
20
|
|
|
11
21
|
端口自动选择只证明检测时可绑定,不预约端口。目录或端口变更后重新检测,确认的地址随环境保存;实际启动仍可能因端口被其他程序占用而失败。不能把其他进程监听同一端口视为此目录的环境。
|
|
12
22
|
|
|
13
|
-
|
|
23
|
+
### 已有环境复用
|
|
14
24
|
|
|
15
25
|
1. 检查 Python、ComfyUI、GGUF 节点、固定模型文件及大小,检查生成与编辑工作流的实际节点能力和端口归属。
|
|
16
26
|
2. 对可复用但未登记环境,adoptInstallation 流式验证模型 SHA256,连接或启动对应服务,核验能力后写入标记及用户环境索引。保留原模型;不因未登记而再次下载整套环境。
|
|
17
27
|
3. 接入检测的 verification=capabilities 只代表环境和工作流能力验证。新部署产生的真实生成、编辑验证图是另一等级证据,不能混称。
|
|
18
28
|
4. 缺文件或版本不符时展示具体差异。固定部署不自动覆写不匹配源码、模型或用户安装;先明确处理差异,再生成新预案。
|
|
19
29
|
|
|
20
|
-
|
|
30
|
+
### 独立 CLI 流程
|
|
21
31
|
|
|
22
32
|
以下示例使用已核对的安装目录与端口;启动前必须有部署、下载及验证采样的任务授权。
|
|
23
33
|
|
|
@@ -35,8 +45,16 @@ start 创建后台 deploymentId,逐阶段记录实际进度,按固定方案
|
|
|
35
45
|
|
|
36
46
|
status 查询原部署。cancel 只停止已核验的本部署进程与采样,不删除用户素材或原模型,不关闭用户先前启动的服务。recover 只找回唯一原登记,不重复安装。工作进程丢失或停止未确认时保留 unknown 与安装占用。
|
|
37
47
|
|
|
38
|
-
|
|
48
|
+
### 存储与关闭
|
|
39
49
|
|
|
40
50
|
安装根保存程序、模型和 vant.art.config.json;环境索引、受管服务身份、日志和验证证据归 ~/.vant/state。项目生图归工程绑定的 .vant/art,不能写入共享模型环境。
|
|
41
51
|
|
|
42
52
|
Vant 退出使用其应用生命周期清理关联后台任务,并关闭可核验为 Vant 启动的 ComfyUI,确认本机端口释放。单独关闭部署窗口不取消部署。CLI shutdown 的工作区与共享服务边界见 [任务控制](troubleshooting.md)。
|
|
53
|
+
|
|
54
|
+
## 结果验证
|
|
55
|
+
|
|
56
|
+
结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
|
|
57
|
+
|
|
58
|
+
## 参考资料
|
|
59
|
+
|
|
60
|
+
[使用说明](../README.md)
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Vant 文档规范
|
|
2
|
+
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
所有包以简体中文为默认语言。包名、命令、参数、路径、协议、字段、错误码、第三方产品名与许可原文保留必要英文。品牌统一使用 Vant,版权统一为 Copyright © 2026 Vant;第三方归属声明保持准确。
|
|
6
|
+
|
|
7
|
+
## 结构
|
|
8
|
+
|
|
9
|
+
| 文档 | 一级内容顺序 |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| README | 功能、环境要求、安装、快速开始、使用说明、开发与验证、文档、许可与版权 |
|
|
12
|
+
| Agent 规范 | 定位、调用流程、调用规范、结果验证、参考资料、许可与版权 |
|
|
13
|
+
| 命令参考 | 定位、调用方式、参数与输出、执行边界、结果验证、参考资料 |
|
|
14
|
+
| 配置与协议 | 定位、前置条件、字段与示例、执行边界、结果验证、参考资料 |
|
|
15
|
+
| 操作指南 | 定位、前置条件、操作流程、结果验证、参考资料 |
|
|
16
|
+
| 故障诊断 | 定位、问题与处理、结果验证、参考资料 |
|
|
17
|
+
|
|
18
|
+
## 内容
|
|
19
|
+
|
|
20
|
+
只描述当前版本的功能、约束和可执行流程。正文不保存研发过程、历史兼容方案、失效版本表或未经验证的成功结论。版本历史集中在 CHANGELOG。已实现的数据转换命令按当前功能说明,不将历史方案混入常规操作。
|
|
21
|
+
|
|
22
|
+
## 维护
|
|
23
|
+
|
|
24
|
+
修改生成器、插件清单与源文档后重新生成随包文档。示例使用占位符,不包含账号、密钥或具体业务数据。命令、字段、链接和打包内容应通过检查;模拟验证不能替代真实平台结果。
|
|
@@ -1,4 +1,14 @@
|
|
|
1
|
-
# 模型与执行架构
|
|
1
|
+
# Vant 模型与执行架构
|
|
2
|
+
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
模型与执行架构,适用于当前随包实现。
|
|
6
|
+
|
|
7
|
+
## 前置条件
|
|
8
|
+
|
|
9
|
+
先按包的环境要求准备工程与工具,使用实际配置和命令帮助核对目标。
|
|
10
|
+
|
|
11
|
+
## 字段与示例
|
|
2
12
|
|
|
3
13
|
模型扩展不修改任务调度和界面判断。未知型号、未知协议、无效响应都明确失败;提交结果未知时禁止重复提交。
|
|
4
14
|
|
|
@@ -13,15 +23,15 @@
|
|
|
13
23
|
|
|
14
24
|
界面与配置保存共用 `modelEligibility`。接口类型列表由适配器注册表提供;模型发现只补齐准确型号的声明能力,不推定账号权限或自动启用。
|
|
15
25
|
|
|
16
|
-
|
|
26
|
+
### 扩展规则
|
|
17
27
|
|
|
18
|
-
|
|
28
|
+
同协议新模型增加完整模型定义与契约测试。字段规则描述类型、默认值、范围或枚举及协议字段名;参数由模型契约声明。模型声明在启动时检查重复标识、必要限制和协议字段。
|
|
19
29
|
|
|
20
30
|
新协议实现 `prepare / submit / query`,通过 `createAdapterRegistry` 登记。同步提交返回完成结果;异步提交返回上游任务身份。界面、任务运行时不包含型号名称分支。输入文件限制由模型声明提供。
|
|
21
31
|
|
|
22
|
-
`art/model-contract-v1` 排除型号别名列表、展示说明、来源链接及 CLI 示例字段;这些文案变化不改变执行哈希。`art/image-request-v1` 保存规范化请求,`art/execution-contract-v1`
|
|
32
|
+
`art/model-contract-v1` 排除型号别名列表、展示说明、来源链接及 CLI 示例字段;这些文案变化不改变执行哈希。`art/image-request-v1` 保存规范化请求,`art/execution-contract-v1` 冻结逐项契约。请求参数、尺寸、转换策略或协议规则变化必须重新预演。没有当前执行契约的失效预案不能启动。
|
|
23
33
|
|
|
24
|
-
|
|
34
|
+
### 生命周期
|
|
25
35
|
|
|
26
36
|
每个计划项分别保存 `remoteExecutions[inputHash]`,包括 schema=art/remote-receipt-v1、请求哈希、适配器及版本、服务地址、提交时间、上游任务 ID 和结果。回执不保存 API Key。
|
|
27
37
|
|
|
@@ -43,10 +53,22 @@ v-cli art task resume TASK
|
|
|
43
53
|
|
|
44
54
|
Vant 通过 `ART_IMAGE_CONNECTION` 和 `ART_IMAGE_KEY` 注入连接,不绑定厂商命名。单独使用 DashScope 时,适配器通过固定版本的百炼核心库读取既有 API Key 配置;明确注入连接后不回退到其他凭据或站点。
|
|
45
55
|
|
|
46
|
-
|
|
56
|
+
### 验证边界
|
|
47
57
|
|
|
48
58
|
单元与协议模拟验证声明扩展、统一筛选、严格响应和回执顺序;真实子进程测试验证工作进程丢失及取消后恢复,统计生成 POST 次数不增加。上述验证不等同于付费模型真实出图或已安装版本更新。
|
|
49
59
|
|
|
50
60
|
新模型至少覆盖合法请求、参数边界、模式和输入拒绝;新协议还需覆盖提交结果未知、持久化失败、按原身份恢复、取消及下载失败。HTTP 响应体、下载大小和时间有界;认证请求禁止重定向,下载不携带模型密钥。当前查询异常保留身份并停止等待,不自动重试查询或提交。
|
|
51
61
|
|
|
52
62
|
[适配目录](remote-models.md) · [任务控制](troubleshooting.md) · [配置](configuration.md)
|
|
63
|
+
|
|
64
|
+
## 执行边界
|
|
65
|
+
|
|
66
|
+
字段、路径与权限以当前 schema、运行时校验和明确授权为准;配置有效不等于外部服务已执行成功。
|
|
67
|
+
|
|
68
|
+
## 结果验证
|
|
69
|
+
|
|
70
|
+
结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
|
|
71
|
+
|
|
72
|
+
## 参考资料
|
|
73
|
+
|
|
74
|
+
[使用说明](../README.md)
|
package/docs/modes.md
CHANGED
|
@@ -1,8 +1,18 @@
|
|
|
1
|
-
# 模式与调用流程
|
|
1
|
+
# Vant 模式与调用流程
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## 定位
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
模式与调用流程,适用于当前随包实现。
|
|
6
|
+
|
|
7
|
+
## 前置条件
|
|
8
|
+
|
|
9
|
+
先按包的环境要求准备工程与工具,使用实际配置和命令帮助核对目标。
|
|
10
|
+
|
|
11
|
+
## 操作流程
|
|
12
|
+
|
|
13
|
+
### 风格分析与核心冻结
|
|
14
|
+
|
|
15
|
+
创建风格草稿,按 style、palette、rendering 分类导入专属参考。讨论澄清意图并回填草稿。style analyze --dry 只编译;实际 analyze 创建 taskId 与独立证据,逐图观察后生成风格报告。
|
|
6
16
|
|
|
7
17
|
报告含 summary、observations、recommendation、issues、notes、decisions 和 provenance。recommendation.rules 是可以独立使用的精炼规范,不含讨论过程。notes 不阻塞采用;issues 给出可执行选项。用户选择后通过 style resolve 记录决定,无需重新分析。style read 的 review.ready 为采用条件,不以聊天中的“可采用”作为事实。
|
|
8
18
|
|
|
@@ -10,34 +20,42 @@
|
|
|
10
20
|
|
|
11
21
|
style adopt 冻结当前有效规则与决策证据,style recover 只恢复原已授权事务。正式风格只读,修改使用 derive。任务动态参考仍使用 job analyze,不替代静态风格。
|
|
12
22
|
|
|
13
|
-
|
|
23
|
+
### 远程文生图
|
|
14
24
|
|
|
15
25
|
选择已启用、目录可用、保存凭据且已适配的图片模型。先 generate show,再 generate plan 保存计划,run --plan --dry 核对请求,再按授权执行。生成 API 由协议适配器直接调用;CLI 示例仅为诊断,不是实际提交链路。
|
|
16
26
|
|
|
17
27
|
型号的生成/编辑模式、输入数量、尺寸、提示词与参数限制统一来自 [模型目录](remote-models.md)。不能把 URL+Key 或 image 标签视为已经适配;不能以注册型号推定账号权限。
|
|
18
28
|
|
|
19
|
-
|
|
29
|
+
### 本地内置文生图
|
|
20
30
|
|
|
21
31
|
ComfyUI 后端省略 workflow 时使用 Qwen Image 2.1 Q4 与 CPU 文本编码器。config validate 校验模板,doctor 检查服务、节点与模型;doctor --start 可启动并保留服务,不采样。plan/dry 不启动服务。内置工作流不证明模型文件、节点和显存已就绪。
|
|
22
32
|
|
|
23
|
-
|
|
33
|
+
### 本地自定义文生图
|
|
24
34
|
|
|
25
35
|
CLI 支持显式 API workflow 与 bindings,调用方负责节点、参数、输入图、数量、输出与生命周期适配。Vant 当前只开放已适配内置方案,不把任意工作流导入作为可运行选择。
|
|
26
36
|
|
|
27
|
-
|
|
37
|
+
### 远程图编辑
|
|
28
38
|
|
|
29
|
-
显式绑定 source 及哈希,声明 changes、preserve 和 mustRead。修改与保留不能冲突。默认保留原图风格;绑定目标 core
|
|
39
|
+
显式绑定 source 及哈希,声明 changes、preserve 和 mustRead。修改与保留不能冲突。默认保留原图风格;绑定目标 core 后由核心统一提供 style。必须使用支持 edit 的准确型号,不能套用文生图端点。
|
|
30
40
|
|
|
31
41
|
上传、提交、查询和下载使用冻结请求。上游身份保存在原运行,恢复仅查询原任务或取回原结果,不重新提交。
|
|
32
42
|
|
|
33
|
-
|
|
43
|
+
### 本地 Qwen 2.1 图编辑
|
|
34
44
|
|
|
35
45
|
使用适配后的 LoadImage.image、VAE 和图像编码器连接,底图上传后显式绑定。latent 输出尺寸与编码器 resolution 分开。服务可连接不等于真实编辑成功,验证需实际底图和输出。
|
|
36
46
|
|
|
37
|
-
|
|
47
|
+
### 生成与定版
|
|
38
48
|
|
|
39
49
|
前台和后台真实运行均登记 taskId。候选必须有可核验计划、运行身份和完整文件。check 仅做技术完整性检查,candidate finalize 记录用户选择;没有人工三维评分或「验收此图」阶段。
|
|
40
50
|
|
|
41
51
|
按资产定版,重复请求幂等;替换用 --replace 并保留历史。candidate delete 用 --confirm 明确影响,拒绝运行中或受引用文件。定版不会自动导入游戏或提交 Git。
|
|
42
52
|
|
|
43
53
|
空闲任务可更新配置后重新编译运行,原批次保留。派生任务独立建立身份,不继承报告、授权、执行或定版。[全部命令](commands.md) · [取消与恢复](troubleshooting.md)
|
|
54
|
+
|
|
55
|
+
## 结果验证
|
|
56
|
+
|
|
57
|
+
结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
|
|
58
|
+
|
|
59
|
+
## 参考资料
|
|
60
|
+
|
|
61
|
+
[使用说明](../README.md)
|
package/docs/remote-models.md
CHANGED
|
@@ -1,8 +1,18 @@
|
|
|
1
|
-
# 远程图片适配与筛选
|
|
1
|
+
# Vant 远程图片适配与筛选
|
|
2
|
+
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
远程图片适配与筛选,适用于当前随包实现。
|
|
6
|
+
|
|
7
|
+
## 前置条件
|
|
8
|
+
|
|
9
|
+
先按包的环境要求准备工程与工具,使用实际配置和命令帮助核对目标。
|
|
10
|
+
|
|
11
|
+
## 字段与示例
|
|
2
12
|
|
|
3
13
|
型号、能力、参数与支持状态的唯一事实源是工具内部 lib/model-catalog.mjs;lib/model-registry.mjs 提供准确查找和统一资格判断。Vant 展示登记目录,不维护第二份模型清单。
|
|
4
14
|
|
|
5
|
-
|
|
15
|
+
### 已适配范围
|
|
6
16
|
|
|
7
17
|
| 模型 | 模式 | 总像素范围 | 输入与主要限制 |
|
|
8
18
|
| --- | --- | --- | --- |
|
|
@@ -21,22 +31,34 @@ Wan 2.7 不支持独立负向参数和提示词扩写开关:负向约束明确
|
|
|
21
31
|
|
|
22
32
|
预演与实际执行使用同一规范化请求。组图、框选、调色板和流式混排等未声明能力不自动开放,工具不承诺请求尺寸与服务端输出逐像素一致。
|
|
23
33
|
|
|
24
|
-
|
|
34
|
+
### 仅登记与未知型号
|
|
25
35
|
|
|
26
36
|
早期 Qwen Image/Max/Plus/Edit、Wan 2.5/2.2/2.1/2.0/V1 和 ImageEdit/Sketch/X-Painting 记录官方来源、支持状态及限制,不套用新型号协议执行。未精确登记的型号拒绝,不因名字相似自动推断支持。
|
|
27
37
|
|
|
28
38
|
modelCatalog() 返回工具登记,不是账号可用模型列表;resolveModel(api, model) 返回精确支持状态。注册不注入账号目录、不自动启用、不推定权限。
|
|
29
39
|
|
|
30
|
-
|
|
40
|
+
### 统一筛选
|
|
31
41
|
|
|
32
42
|
modelEligibility 共用于界面与配置保存,按实例启用、目录可用、模型启用、已保存凭据、图片协议、图片输出能力和准确型号支持状态给出原因。只有 ID 的未知元数据可从已适配型号补能力;显式用户能力配置受到尊重,不能因此跳过协议和模型策略。
|
|
33
43
|
|
|
34
44
|
视觉分析要求图片输入和文字输出,与图片生成筛选分开。具体执行还要校验 generate/edit 模式、输入数量、参数和尺寸;实例能够选中不保证每个任务都合法。
|
|
35
45
|
|
|
36
|
-
|
|
46
|
+
### 协议、渠道与恢复
|
|
37
47
|
|
|
38
48
|
Token Plan 是订阅渠道,DashScope 是 API 协议。按量与订阅共用适配目录,但始终保留所选实例原地址及密钥,不切换站点,不推定套餐提供同等权限。请求采用 native DashScope 适配器,CLI 只是可选诊断示例。
|
|
39
49
|
|
|
40
50
|
异步模型保存上游 taskId 后查询;同步模型保存完成 URL 后下载。取消只停止本地等待,恢复仅查询原身份和取回原结果。[生命周期](model-architecture.md) · [异常处理](troubleshooting.md)
|
|
41
51
|
|
|
42
52
|
登记依据链接:[Qwen 2 生成](https://help.aliyun.com/zh/model-studio/qwen-image-api)、[Qwen 2 编辑](https://help.aliyun.com/zh/model-studio/qwen-image-edit-api)、[Wan 2.7](https://help.aliyun.com/zh/model-studio/wan-image-generation-and-editing-api-reference)、[Wan 2.6 文生图](https://help.aliyun.com/zh/model-studio/text-to-image-v2-api-reference)、[Wan 2.6 编辑](https://help.aliyun.com/zh/model-studio/wan-image-generation-api-reference)。本文说明当前代码登记范围,不声称远端账号已开通或本轮已真实付费出图。
|
|
53
|
+
|
|
54
|
+
## 执行边界
|
|
55
|
+
|
|
56
|
+
字段、路径与权限以当前 schema、运行时校验和明确授权为准;配置有效不等于外部服务已执行成功。
|
|
57
|
+
|
|
58
|
+
## 结果验证
|
|
59
|
+
|
|
60
|
+
结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
|
|
61
|
+
|
|
62
|
+
## 参考资料
|
|
63
|
+
|
|
64
|
+
[使用说明](../README.md)
|
package/docs/troubleshooting.md
CHANGED
|
@@ -1,12 +1,18 @@
|
|
|
1
|
-
# 任务控制与诊断
|
|
1
|
+
# Vant 任务控制与诊断
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
任务控制与诊断,适用于当前随包实现。
|
|
6
|
+
|
|
7
|
+
## 问题与处理
|
|
8
|
+
|
|
9
|
+
### 先核对事实
|
|
4
10
|
|
|
5
11
|
先 config validate,再 doctor;远程 doctor 只核对配置,不验证认证、账号授权或云端连通性。本地 doctor 默认不启动、不采样;--start 可启动并保留服务。真实生成仍须 plan/dry 和任务授权。
|
|
6
12
|
|
|
7
13
|
技术检查不证明画面质量;mock 不证明模型真实出图;服务可连接不证明显存足够;包构建不证明安装及桌面交互通过。
|
|
8
14
|
|
|
9
|
-
|
|
15
|
+
### 状态与占用
|
|
10
16
|
|
|
11
17
|
task status 返回原运行阶段、心跳、工作进程、后端身份、manifestPath、错误和停止证据。queued/running/cancelling 仍占用对象。生成任务释放必须是已知终态、stopConfirmed=true,且无 unsettled、promptId、remoteCancellation 或 dispatching/accepted 远程回执;unknown 一律保留占用。
|
|
12
18
|
|
|
@@ -14,11 +20,11 @@ task status 返回原运行阶段、心跳、工作进程、后端身份、manif
|
|
|
14
20
|
|
|
15
21
|
分析阶段记录 reference-analysis(当前图片与已完成数量)、synthesis(汇总)、report-repair(一次格式修正)和 report-validation(校验回填),不会用心跳推测完成比例。模型响应文字按调用保存在对象 reports/<taskId>/responses/,不保存凭据或请求图片编码。格式校验失败最多基于已有结果修正一次,不重复读取已完成的图片;仍失败则保留原响应和草稿,明确显示错误。
|
|
16
22
|
|
|
17
|
-
多图风格分析将完整成功的分类观察缓存到配置的缓存目录 references
|
|
23
|
+
多图风格分析将完整成功的分类观察缓存到配置的缓存目录 references/。缓存身份包含图片内容哈希、分类、说明、排除项、观察提示、规则及模型连接配置,不依赖每次运行变化的证据副本路径。明确重新发起分析时只重读未命中观察;汇总失败不会自动发起下一次分析。先前运行没有这种缓存时,原响应仍保留,不把缺少缓存身份的文字猜作可复用观察。
|
|
18
24
|
|
|
19
25
|
工作进程丢失且心跳过期标记 unknown,不能推测上游停止。task wait 超时不取消;切面板不取消;本地客户端退出不代表云端取消或费用撤销。
|
|
20
26
|
|
|
21
|
-
|
|
27
|
+
### 查询、恢复和重试
|
|
22
28
|
|
|
23
29
|
| 情况 | 入口 | 行为 |
|
|
24
30
|
| --- | --- | --- |
|
|
@@ -35,7 +41,7 @@ resume 要求原工作进程已退出、运行终态、回执和冻结请求哈
|
|
|
35
41
|
|
|
36
42
|
retry-run 不能混用 dry/item/variant/offset/limit;原批次和先前重试必须停止确认,成功项不重复执行,远程完成待下载项不能走重生成。配置、模型契约、规格、核心、参考、底图或工作流变化后重编译,不能运行过期预案。
|
|
37
43
|
|
|
38
|
-
|
|
44
|
+
### 取消与关闭
|
|
39
45
|
|
|
40
46
|
task cancel 定向取消本工作区运行。本地按 promptId 处理自有请求,保留 ComfyUI 服务;远程无已适配上游取消能力时只停止本地等待,保留原身份与未知停止事实。
|
|
41
47
|
|
|
@@ -43,10 +49,18 @@ CLI shutdown 阻止新提交,停止当前工作区关联任务,再核验共
|
|
|
43
49
|
|
|
44
50
|
Vant 应用退出有独立所有权清理:关闭 Vant 启动并登记的后台进程和 ComfyUI,检查端口释放,不把外部用户服务收编为退出时终止目标。窗口关闭、CLI shutdown、应用退出三个入口的作用域不同。
|
|
45
51
|
|
|
46
|
-
|
|
52
|
+
### 常见配置问题
|
|
47
53
|
|
|
48
54
|
- 模型无法选择:依次核对实例/模型启用、目录可用、凭据、输出能力、图片协议、准确型号及模式支持。仅登记型号显示限制原因,不可执行;手工能力覆盖不能绕过缺失的协议适配。
|
|
49
55
|
- 报告过期或 revision 冲突:重新读取对象及版本,不覆盖用户输入;更新后重新分析或预演。
|
|
50
56
|
- 模型已存在仍提示部署:核对选择的是便携根目录、文件准确名称与大小,再做 SHA256 和能力接入;不以文件存在替代完整环境验证。
|
|
51
57
|
- 端口被占:区分原环境和其他程序,修改端口后重新检测;自动选择端口不等于长期预约。
|
|
52
58
|
- 候选删除清理失败:保留删除事实,仅重试所属文件清理,不恢复成可用候选。
|
|
59
|
+
|
|
60
|
+
## 结果验证
|
|
61
|
+
|
|
62
|
+
结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
|
|
63
|
+
|
|
64
|
+
## 参考资料
|
|
65
|
+
|
|
66
|
+
[使用说明](../README.md)
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kevlns/art-workshop",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.8",
|
|
4
4
|
"private": false,
|
|
5
|
-
"description": "
|
|
5
|
+
"description": "管理项目风格、参考图、图片生成、编辑和定版。支持本地 ComfyUI 与远程图片模型。",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"bin": {
|
|
8
8
|
"art-workshop": "art-workshop.mjs"
|
|
@@ -25,10 +25,11 @@
|
|
|
25
25
|
"skill:sync": "node scripts/sync-skill.mjs",
|
|
26
26
|
"test": "node scripts/test.mjs",
|
|
27
27
|
"pack:guard": "node scripts/pack-guard.mjs",
|
|
28
|
-
"check": "npm run docs:check && npm test && npm run pack:guard",
|
|
28
|
+
"check": "npm run docs:style && npm run docs:check && npm test && npm run pack:guard",
|
|
29
29
|
"test:package": "node scripts/test-package-install.mjs",
|
|
30
30
|
"docs:check": "node scripts/check-docs.mjs",
|
|
31
|
-
"docs:generate": "node scripts/command-docs.mjs"
|
|
31
|
+
"docs:generate": "node scripts/command-docs.mjs",
|
|
32
|
+
"docs:style": "node scripts/check-documentation.mjs"
|
|
32
33
|
},
|
|
33
34
|
"engines": {
|
|
34
35
|
"node": ">=20.9"
|
|
@@ -45,7 +46,7 @@
|
|
|
45
46
|
"access": "public"
|
|
46
47
|
},
|
|
47
48
|
"license": "MIT",
|
|
48
|
-
"author": "
|
|
49
|
+
"author": "Vant",
|
|
49
50
|
"vCli": {
|
|
50
51
|
"manifest": "v-cli.plugin.json"
|
|
51
52
|
},
|
|
@@ -3,39 +3,55 @@ name: art-workshop
|
|
|
3
3
|
description: 美术工坊风格、任务、参考、预演、执行与定版管理。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
#
|
|
6
|
+
# Vant 美术工坊 Agent 规范
|
|
7
|
+
|
|
8
|
+
## 定位
|
|
9
|
+
|
|
10
|
+
管理项目风格、参考图、图片生成、编辑和定版。支持本地 ComfyUI 与远程图片模型。
|
|
11
|
+
|
|
12
|
+
## 调用流程
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
art-workshop config show
|
|
16
|
+
art-workshop config validate
|
|
17
|
+
art-workshop agent index
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
首次调用前读取本规范,使用命令帮助或插件清单核对参数和执行范围。
|
|
21
|
+
|
|
22
|
+
## 调用规范
|
|
7
23
|
|
|
8
24
|
用户既有授权与偏好持续有效;查询和预演不授权生成或采用。规范与实时参数通过 v-cli agent docs art 和 v-cli agent describe art --json 获取。
|
|
9
25
|
|
|
10
|
-
|
|
26
|
+
### 对象与参考
|
|
11
27
|
|
|
12
|
-
|
|
28
|
+
工程对象使用 schemaVersion 2;读写前核实工程配置和当前 revision。
|
|
13
29
|
风格和任务都有稳定 id 与 revision。UI、聊天和 CLI 共用对象;写入、派生与清理提交预期 revision,冲突重新读取。正式风格只读,改动创建派生风格;派生不继承报告、核心、批次、授权与对话。
|
|
14
30
|
风格静态参考只有 style、palette、rendering,只分析媒介、描绘、明暗、描边、笔触和色彩关系。具体造型、比例、结构、部件、身份色、材质与光源属于任务。任务动态参考只有 subject、composition、pose、identity-color、surface、scene-light、text;编辑底图另列。导入复制原图,不修改用户文件。未适配直接参考时拒绝,不隐式上传风格图片。
|
|
15
31
|
|
|
16
|
-
|
|
32
|
+
### 风格生命周期
|
|
17
33
|
|
|
18
34
|
style create/read/update/derive/discard 管理草稿。style analyze --dry 只读编译,不联网、启动服务或创建参考目录。实际 analyze 创建 taskId 与独立参考证据;task status/wait/cancel 控制执行,recover 查原登记,resume 仅恢复远程查询与取回。
|
|
19
35
|
报告绑定源配置、参考与模型。更新配置保留报告并标记需复核,旧证据不变。报告 recommendation.rules 是精炼独立成稿,规则含主题、强度和适用条件,不包含迭代描述。issues 仅列需用户取舍的矛盾,notes 保留不阻塞采用的证据局限。style resolve --input {issueId,optionId,note} 记录明确选择并修订有效方案,不重新分析;以 style read 的 review.ready 判断采用条件。复核沿用证据与决定,新证据才重新打开问题。style adopt 校验来源匹配和所有问题已决定,用户采用后冻结。采用中断通过 style recover 完成已授权事务,不能重新冻结另一份核心。
|
|
20
36
|
退出风格配置先继续编辑、保存草稿或放弃;分析停止未确认时不能清理。
|
|
21
37
|
|
|
22
|
-
|
|
38
|
+
### 计划与执行
|
|
23
39
|
|
|
24
40
|
先读取实际 job,再 generate/edit plan 和 run --plan --dry,展示有效核心、设计尺寸、预留缩放、请求与实际像素、模型后端、候选数量和编辑底图。后端尺寸由工具统一解析,超限或未对齐选最近合法尺寸,保留设计基准并明确实际值;不承诺显存或自动缩放导出。
|
|
25
|
-
授权覆盖方案后使用 run --background
|
|
41
|
+
授权覆盖方案后使用 run --background;前台同样创建执行身份。配置、核心、规格、参考、底图和后端变化拒绝失效方案,重新编译。重启查 taskId,不重复提交。不自动换模型或重跑成功项。
|
|
26
42
|
每个任务只能有一个未停止确认的执行;编辑、派生、删除与运行共用状态检查。切页面不取消。
|
|
27
43
|
|
|
28
|
-
|
|
44
|
+
### 取消、异常和关闭
|
|
29
45
|
|
|
30
46
|
任务状态与停止证据分开。queued/running/cancelling 仍占用资源;unknown 或 stopConfirmed=false 保留资源。failed/cancelled 也不能单凭状态释放资源;dispatching/accepted 远程回执尚未结清时继续占用。工作进程丢失标记 unknown,不推测停止。
|
|
31
47
|
task cancel 只取消指定运行,保留服务。生成任务远程取消只停止本地客户端,上游停止未知如实报告,不允许清理。只读分析有 finishedAt、已知终态且工作进程已退出,无生成计划与回执时释放本地占用;云端计算与计费停止未知独立保留,不自动重发。没有完成证据的进程丢失仍保持 unknown。shutdown 阻止提交、停止关联任务、核验共享队列和进程身份后关闭本地服务,不清空共享队列;有其他任务或停止未确认时保留服务。不得广泛杀所有 Python。
|
|
32
48
|
|
|
33
|
-
|
|
49
|
+
### 生成与定版
|
|
34
50
|
|
|
35
51
|
只有生成与定版两个产品阶段。check 验证计划、执行身份、文件哈希和完成事实;不要求人工 content/style/asset 评分。candidate finalize 按资产选定候选,重复操作幂等;替换已有定版需要明确 replace,保留历史。
|
|
36
52
|
candidate delete 先确认影响,拒绝运行中或被计划/底图引用的候选;先记删除事实,清理所属文件,并取消关联定版。定版不自动导入游戏或提交 Git。
|
|
37
53
|
|
|
38
|
-
|
|
54
|
+
### 验证和技能
|
|
39
55
|
|
|
40
56
|
本地先 config validate、doctor、plan/dry,再按授权真实生成与编辑。配置有效、服务可连接与真实出图是不同证据。远程核对实际认证和模型入口;凭证不得写入项目、计划、日志或命令行。
|
|
41
57
|
随包 skills/art-workshop 是技能源;通过 agent init 或 skill:sync 同步,保留项目扩展。查询和预演不自动同步。源码/单测/mock 不能代替真实模型、图像、桌面与安装验证。
|
|
@@ -46,4 +62,22 @@ candidate delete 先确认影响,拒绝运行中或被计划/底图引用的
|
|
|
46
62
|
|
|
47
63
|
远端上游身份持久化后才能轮询。`task resume TASK` 只恢复原身份查询与取回,不重发生成;无回执或仍处于 dispatching 的提交保持未知。界面与保存共用 modelEligibility,展示字段不进入执行契约。
|
|
48
64
|
|
|
49
|
-
|
|
65
|
+
风格报告和核心使用 schemaVersion=3,只表达绘制语言,不限定主体题材。低刻画密度不删任务结构,干净笔触不禁止物体纹理,高光画法不统一物理材质。
|
|
66
|
+
|
|
67
|
+
任务草稿允许内容尚未完成,但拒绝编译器不支持的字段。生成任务的字段正本为 lib/task-contract.mjs;effect 使用 id/kind/target/color/relation/count,不支持 description。先读当前对象,完整保留未修改字段,按当前 revision 保存;保存成功后仍需编译预案,不能声称已生成图片。任务编译错误依据执行回执修正,不猜测风格或尺寸问题。
|
|
68
|
+
|
|
69
|
+
任务参考可通过 reference import --item-id <对象标识> 绑定单个出图对象;未绑定的参考为任务共用。生成与编辑只采纳共用参考和当前对象参考的观察。reference update 的 itemId 可改绑对象,null 表示任务共用。
|
|
70
|
+
|
|
71
|
+
`v-cli capability coverage --json` 核对结构化调用覆盖。参考导入的 `--item-id` 指定当前任务出图对象,省略表示任务共用;工具校验对象身份。
|
|
72
|
+
|
|
73
|
+
## 结果验证
|
|
74
|
+
|
|
75
|
+
核对原始错误、任务身份、停止状态及实际产物。只报告已经完成的验证,模拟测试与真实执行分别说明。
|
|
76
|
+
|
|
77
|
+
## 参考资料
|
|
78
|
+
|
|
79
|
+
通过 `art-workshop --help` 和 `art-workshop agent docs` 查阅使用规范。 · v-cli.plugin.json
|
|
80
|
+
|
|
81
|
+
## 许可与版权
|
|
82
|
+
|
|
83
|
+
MIT。Copyright © 2026 Vant。
|
package/v-cli.plugin.json
CHANGED