@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.
Files changed (61) hide show
  1. package/AGENTS.md +33 -12
  2. package/README.md +33 -135
  3. package/art-workshop.mjs +95 -25
  4. package/docs/commands.md +915 -0
  5. package/docs/configuration.md +60 -0
  6. package/docs/core-guidance.md +80 -13
  7. package/docs/data-formats.md +29 -0
  8. package/docs/deployment.md +40 -0
  9. package/docs/model-architecture.md +52 -0
  10. package/docs/modes.md +39 -0
  11. package/docs/remote-models.md +42 -0
  12. package/docs/troubleshooting.md +46 -0
  13. package/lib/adapters/dashscope.mjs +234 -0
  14. package/lib/adapters/index.mjs +28 -0
  15. package/lib/agent.mjs +3 -2
  16. package/lib/analysis-worker.mjs +25 -0
  17. package/lib/analyze.mjs +8 -8
  18. package/lib/backends.mjs +365 -0
  19. package/lib/bl.mjs +3 -18
  20. package/lib/candidates.mjs +82 -0
  21. package/lib/comfyui.mjs +64 -0
  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/diagnostics.mjs +83 -0
  27. package/lib/dimensions.mjs +22 -0
  28. package/lib/edit.mjs +6 -3
  29. package/lib/environments.mjs +67 -0
  30. package/lib/execution/remote.mjs +156 -0
  31. package/lib/executor.mjs +10 -24
  32. package/lib/generate.mjs +9 -5
  33. package/lib/generation-policy.mjs +198 -0
  34. package/lib/images.mjs +10 -0
  35. package/lib/lifecycle.mjs +40 -0
  36. package/lib/migration.mjs +154 -0
  37. package/lib/model-catalog.mjs +288 -0
  38. package/lib/model-registry.mjs +234 -0
  39. package/lib/plan.mjs +98 -28
  40. package/lib/project.mjs +13 -4
  41. package/lib/providers.mjs +30 -0
  42. package/lib/refs.mjs +12 -16
  43. package/lib/runtime.mjs +25 -0
  44. package/lib/service.mjs +137 -0
  45. package/lib/settings.mjs +5 -6
  46. package/lib/shared.mjs +12 -2
  47. package/lib/style-lifecycle.mjs +72 -0
  48. package/lib/task-references.mjs +35 -0
  49. package/lib/task-worker.mjs +233 -0
  50. package/lib/tasks.mjs +458 -0
  51. package/lib/templates.mjs +69 -0
  52. package/lib/transport/cli.mjs +69 -0
  53. package/lib/transport/http.mjs +82 -0
  54. package/lib/vision.mjs +46 -0
  55. package/lib/workflows.mjs +28 -0
  56. package/lib/workspace.mjs +190 -0
  57. package/package.json +14 -6
  58. package/skills/art-workshop/SKILL.md +27 -27
  59. package/v-cli.plugin.json +1484 -135
  60. package/workflows/vant-builtin-qwen-image-2.1-Q4-8GB.api.json +116 -0
  61. package/workflows/vant-builtin-qwen-image-2.1-Q4-8GB.json +648 -0
@@ -0,0 +1,60 @@
1
+ # 配置与存储
2
+
3
+ ## 配置入口
4
+
5
+ `config path/show/init/validate` 分别查询位置、生效配置、创建模板和校验。`config init` 不覆盖已有文件。查询、发现和预演不创建参考目录;`config validate` 不联网、不启动服务。
6
+
7
+ 配置位置优先级为 CLI `--config`、`ART_WORKSHOP_CONFIG`、`<VANT_HOME 或 ~/.vant>/tools/art-workshop/config.json`。资源路径优先级为 CLI 路径选项、配置 paths、默认路径。配置文件和资源均须位于工具安装目录之外。
8
+
9
+ | 字段 | 职责与默认值 |
10
+ | --- | --- |
11
+ | paths.workspace | 默认 ~/.vant/tools/art-workshop/workspace,保存 projects 和 .runtime |
12
+ | paths.output | 默认与 workspace 相同;执行批次与候选产物根 |
13
+ | paths.refs | 默认 workspace/refs,素材导入基准;不是对象的权威参考目录 |
14
+ | paths.cache | 默认 workspace/.cache,分析等缓存 |
15
+ | execution | 全局执行默认值,具体范围由所选模型策略校验 |
16
+ | generation | defaultBackend、defaults、backends |
17
+ | analysisModel | 分析模型默认值,连接仍需单独就绪 |
18
+ | defaultProject | 未传 --project 时的工程 ID,不跨工程回退 |
19
+ | autoSyncSkills | 默认 true;实际分析、采用、运行入口可刷新随包技能,查询与 dry 不刷新 |
20
+
21
+ Vant 显式传入绑定,把工程对象、参考、批次及图片集中在工程 `.vant/art`。独立 CLI 默认 workspace 可以容纳多个工程,不自动绑定当前 Git 工程。普通输入、计划和报告相对路径以 workspace 为基准;`check RUN` 相对批次以 output 为基准。参考源文件建议提供绝对路径。
22
+
23
+ ## 后端配置
24
+
25
+ 远程 provider 为后端类别标识;执行协议来自 credentialReference.api,缺省 DashScope。协议必须已注册,型号必须在该协议目录中精确登记且支持所需模式。provider 名称不是权限或协议兼容性的证明。
26
+
27
+ 下面仅示例结构,不含凭据。具体参数以 [适配目录](remote-models.md) 和生成预演为准。
28
+
29
+ ```json
30
+ {
31
+ "generation": {
32
+ "defaultBackend": "remote-image",
33
+ "backends": {
34
+ "remote-image": {
35
+ "provider": "bailian",
36
+ "model": "qwen-image-2.0-pro",
37
+ "execution": { "size": "1024*1024", "perValue": 1, "watermark": false }
38
+ }
39
+ }
40
+ }
41
+ }
42
+ ```
43
+
44
+ ComfyUI 后端使用 provider=comfyui,声明 model、endpoints,以及可选 workflow、bindings、options、launch。省略 workflow 使用随包固定方案;自定义工作流必须是 API JSON,bindings 指向真实节点输入。endpoints 只允许本机 HTTP 根地址。launch 明确 executable/cwd/args;工具以 argv 启动,不拼接 shell。详情见 [本地部署](deployment.md)。
45
+
46
+ ## 认证与实例
47
+
48
+ Vant 系统模型配置统一保存 Provider 实例及凭据,工程只引用实例身份、修订及不含密钥的连接信息。模板只负责预填新实例,不是独立可执行连接。模型目录发现、能力登记、启用与账号权限是不同事实。
49
+
50
+ 远程图片由组织层通过 ART_IMAGE_CONNECTION(api/baseUrl)和 ART_IMAGE_KEY 注入内存;明确连接缺少密钥时拒绝,不能回退另一份密钥或站点。独立 DashScope 使用固定版本百炼核心库的既有认证来源。
51
+
52
+ 视觉分析独立使用 ART_VISION_CONFIG 与 ART_VISION_KEY,支持 openai-completions、openai-responses、anthropic-messages、google-generative-ai。未注入连接时分析走百炼 CLI。不要把图片输出模型当作视觉分析模型;分析要求图片输入和文字输出。
53
+
54
+ 凭据不进入工程、计划、运行回执、日志或命令行。Token Plan 与按量渠道保留各自实例地址和密钥,不跨渠道回退。配置校验不证明凭据有效、模型授权或实际出图。
55
+
56
+ ## 状态与共享环境
57
+
58
+ 对象变更锁和执行登记归 workspace/.runtime;更换配置文件不产生另一套占用。共享服务登记归用户数据根的 state/art-services,环境索引、接入日志和证据归 state/art-environments。安装根保存模型、程序与 vant.art.config.json,不再新建 .vant-art 控制目录。
59
+
60
+ 旧工程仅通过显式 project upgrade 备份转换;旧用户目录或环境状态不能靠文档重命名完成迁移。迁移与异常边界见 [数据结构](data-formats.md) 和 [诊断](troubleshooting.md)。
@@ -1,15 +1,82 @@
1
1
  # 核心冻结指导规则
2
2
 
3
- 权威规则:rules/core-guidance.json。模型分析、配置校验和冻结记录共用这一份。
4
-
5
- 1. 语言精炼:每条规则表达一个可执行要求,避免重复和修辞。
6
- 2. 用词准确:统一术语,明确强度、范围与条件,不混用不同渲染机制。
7
- 3. 前后一致:报告、推荐、冻结、正向和负向提示词、验收要求保持一致。
8
- 4. 职责分明:核心定义视觉规律;资产定义背景和构图许可;需求定义主体、数量、动作与关系;执行定义模型和尺寸;编辑定义修改与保留。
9
- 5. 单一来源:一个事实只有一个权威字段,提示词从结构化配置生成。
10
- 6. 作用域明确:规则明确作用对象,题材适配不能覆盖全局渲染或冻结单张内容。
11
- 7. 观察与建议分开:观察保留证据和置信度,建议进入推荐配置,不确定性显式列出。
12
- 8. 跨内容复用:不把参考图偶然的颜色、数量、背景和布局冻结为普遍要求。
13
- 9. 冻结可追溯:保留报告、规则、身份和哈希,冻结后不原地修改,任务明确选择基础核心。
14
-
15
- 校验覆盖结构、枚举、已知语义组合、精炼度与常见职责越界,不能穷尽自然语言全部语义矛盾,冻结前仍需审阅。未解决的 conflicts 或 uncertainties 会阻止冻结。
3
+ 权威规则为 rules/core-guidance.json。风格分析请求、推荐校验与冻结来源使用同一份规则。此文解释审查方法,不另造第二份可修改的风格提示词。
4
+
5
+ ## 各层拥有的内容
6
+
7
+ | 层 | 负责内容 | 审查重点 |
8
+ |---|---|---|
9
+ | core | 媒介、形体、渲染、光照、色彩关系、题材表面处理 | 是否跨主体复用,正负向是否一致 |
10
+ | profile | 背景、构图许可、留白、文字、外框、投影、设计基准 | 是否适合目标资产与设计尺寸 |
11
+ | generate item | 实体、数量、身份色、动作、关系、效果、单张构图 | 是否可从 mustRead 和实体字段确认内容 |
12
+ | execution/backend | 模型、size、perValue、seed、水印、扩写、workflow | 是否符合当前模式与环境 |
13
+ | edit item | 底图、changes、preserve | 修改与保留是否冲突,原图是否正确 |
14
+
15
+ ## 报告到冻结的检查
16
+
17
+ 1. 一条规则表达一个可执行判断,去掉同义重复和无助于生成的修辞。
18
+ 2. 视觉术语明确;强度、数量、颜色、范围有明确字段,避免互斥渲染机制。
19
+ 3. 推荐、冻结、正向提示词、负向约束与定版时的审查依据来自同一结构,前后一致。
20
+ 4. 核心只拥有视觉语言;具体主体、布局、背景、模型、尺寸不得混入核心。
21
+ 5. 一个事实只有一个权威字段;不再追加另一段冻结 styleBlock 覆盖结构化核心。
22
+ 6. domains 规则明确作用于实体类别;表面科幻处理不等于给所有主体套同一结构。
23
+ 7. observations 保留 source、scope、feature、evidence、confidence;建议进入 recommendation,推断和未知进入 uncertainties。
24
+ 8. 不把参考图偶然的颜色、数量、背景和布局当成全局要求;不同主体允许保留自己的身份色。
25
+ 9. 冻结来源、身份与哈希可追溯;旧核心不能原地覆写,任务明确选择新核心。
26
+
27
+ style validate 检查结构、枚举、已定义语义矛盾、语言长度和常见职责越界。它不能穷尽自然语言矛盾或替代图像审查。未解决 conflicts/uncertainties 阻止冻结;处理后重新验证。
28
+
29
+ ```powershell
30
+ v-cli art style validate --project P --report projects/P/reports/style.json
31
+ # 已有用户采用报告的依据后执行。
32
+ v-cli art style adopt --project p --id style-id --revision 2 --note "采用已审阅的推荐风格"
33
+ v-cli art style show --project P --core style
34
+ ```
35
+
36
+ style adopt 校验当前报告后原子写核心并更新 project.cores;没有 defaultCore 时可设为新核心。需要第二套风格时派生新草稿,重新分析和采用,不复制冻结文件改身份。
37
+
38
+ ## 生图时的核心检查
39
+
40
+ 文生图核心选择顺序为显式 --core、任务 core、工程 defaultCore。显式指定与任务 core 冲突时先修改任务绑定;没有明确选择时不跨工程回退。
41
+
42
+ 图编辑默认保留原图风格,不读取 defaultCore。明确绑定目标 core 时,style 的修改或保留由核心负责,任务不再重复声明。
43
+
44
+ 换远程/本地后端只改变执行能力,不自动改核心或需求。同一提示词在不同模型上的表现可能不同,定版时需结合实际内容、风格和资产用途判断;工具不设置评分字段或人工验收门槛。
45
+
46
+ ## 风格变化的对照
47
+
48
+ 新风格先生成新报告和核心,再对相同任务编译两个计划,核对 compare 与 dry,固定可控 seed,在授权范围内做少量图像对照。compare 只对比计划,不评价风格一致性;同 seed 也不保证跨模型、版本或设备逐像素复现。
49
+
50
+ ```powershell
51
+ v-cli art compare .cache/old-plan.json .cache/new-plan.json
52
+ v-cli art check RUN
53
+ ```
54
+
55
+ check 核验产物完整性、生成成功事实、文件哈希和计划归属。用户可通过 candidate finalize 定版;没有人工评分门槛。定版记录表示用户选择,不声称产物已经集成或符合游戏运行要求。
56
+ ## 推荐核心结构示例
57
+
58
+ 以下是报告 recommendation 的合法结构示例,展示 energy 类别的风格处理。它不是已冻结文件,仍需依据实际证据产生报告、审阅并 style adopt;不要人为补 coreHash 绕过流程。
59
+
60
+ ```json
61
+ {
62
+ "medium": "illustration",
63
+ "shape": { "contour": "rounded", "detail": "low" },
64
+ "render": {
65
+ "shading": "cel",
66
+ "toneSteps": 2,
67
+ "outline": { "enabled": true, "color": "#34445C", "width": 0.004 },
68
+ "highlights": "hard-edge",
69
+ "finish": "matte",
70
+ "texture": "none"
71
+ },
72
+ "lighting": { "direction": "top-front", "contrast": "medium" },
73
+ "color": { "preserveIdentity": true, "shadowShift": "cool" },
74
+ "domains": {
75
+ "energy": { "treatment": "emissive", "signature": "用简洁硬边高光表达能量表面。" }
76
+ }
77
+ }
78
+ ```
79
+
80
+ medium 可为 illustration/painting/pixel-art/photography;轮廓为 rounded/angular/mixed,细节为 low/medium/high。shading 可为 cel/flat/smooth/painterly/pixel;cel 至少两阶、不能有软高光或可见纹理,flat 一阶,smooth/painterly 的 toneSteps 为 null,pixel-art 应配 pixel,photography 应配 smooth 且无描边。其他组合和长度限制由 style validate 核对。
81
+
82
+ 描边 width 是画幅宽度比 0~0.03,不是像素值;关闭描边时 width=0。domain treatment 可为 organic/hard-surface/emissive/structure/symbol,signature 只描述表面和形态处理,不声明本张主体、数量或背景。
@@ -0,0 +1,29 @@
1
+ # art 工程与输入结构
2
+
3
+ ## 工程和对象
4
+
5
+ project.json 必须声明 schemaVersion=2、revision、id、name、analysisModel、execution、cores、defaultCore。工程身份与目录匹配,核心必须属于同一工程。
6
+
7
+ 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
+
9
+ 参考记录包括 id、所属对象、私有相对 path、SHA256、来源、category/purposes、usage、note、ignore。风格四类:style、palette、shape-language、rendering。任务用途:subject、composition、pose、identity-color、surface、scene-light、text。sources 只放编辑底图。
10
+
11
+ ## 需求与计划
12
+
13
+ 生成 config 包括 project、kind、core、execution、items,以及互斥的 profile 或内联 asset 规格;实体及效果有稳定 id、数量、颜色、角色与关系。具体主体、构图、动作不冻结进风格。规格定义资产约束、设计基准与检查要点,内联规格属于当前任务,编译时形成同一不可变快照。编辑 config 的 items 明确 source、changes、preserve、mustRead、seed。
14
+
15
+ plan 包括 schema=art-workshop/plan、module/project/job、sources、snapshots、refs、execution、items、planHash。sources 绑定 taskRevision、taskConfigHash 和 coreHash;项目/核心/profile/任务形成快照。项含 inputHash、实际尺寸和 seed。任何来源或哈希变化拒绝运行。
16
+
17
+ ## 执行与定版
18
+
19
+ 对象 taskId(命令中称 job/id)与执行 taskId 是两种身份;每次真实执行有独立登记。运行记录包含 queued/running/cancelling/succeeded/failed/cancelled/unknown、heartbeat、workerPid、后端身份、manifestPath、stopConfirmed 与 unsettled。终态与停止证据独立;没有停止证据继续占用对象。配置状态及界面分组不能取代运行身份。
20
+
21
+ manifest 保存计划、每项输出及哈希、失败证据和完成事实。候选身份绑定运行、资产、构图与文件。定版记录保留资产、候选、批次、哈希、操作者与时间;替换与删除进入历史。删除先记录事实,物理清理可重试。
22
+
23
+ 远程计划项的 request 使用 art/image-request-v1,executionContract 使用 art/execution-contract-v1。执行记录 remoteExecutions[inputHash] 保存 art/remote-receipt-v1,状态为 dispatching/accepted/completed/failed/cancelled;包含适配器版本、requestHash、baseUrl 及可用的 taskId/urls。dispatching 先于提交,accepted 先于轮询,completed 先于下载;不含密钥。具体字段以 lib/contracts.d.ts 及编译结果为准,不手工拼装执行回执。
24
+
25
+ task recover 根据工程和 operationId 找回唯一原执行;task resume 沿用原执行和 manifest,仅处理已有上游身份。retry-run 则创建新批次并记录 retryOf。三种身份流不能混用,详见 [任务控制](troubleshooting.md)。
26
+
27
+ 旧格式只通过 project upgrade 显式转换,有备份与原子替换;共享图片须人工映射,不能猜测后删除。
28
+
29
+ 升级事务登记在 workspace/.runtime/upgrades/<projectId>.json。替换中断后只通过显式 project upgrade 恢复原备份并重新转换;日常读写拒绝未完成事务。编辑源导入新对象私有 sources;历史快照保留旧事实。历史同资产多次批准须在 mapping 的 selections 中提供 task/assetId/runId/file/variantId,明确当前正式选择,其余保留替换历史,不猜测最近一张。
@@ -0,0 +1,40 @@
1
+ # 本地环境检测与部署
2
+
3
+ 固定自动安装方案由 lib/deployment.mjs 的 LOCAL_RECIPE 维护:ComfyUI、GGUF 节点、Python/Torch 依赖以及三个模型的准确版本和 SHA256。自动部署当前只适配 Windows NVIDIA 环境;已有便携 Python 可复用,新建 venv 需要可用的 Python >=3.12。
4
+
5
+ ## 目录与端口
6
+
7
+ Vant 检测窗口默认安装目录为 `<VANT_HOME 或 ~/.vant>/art-env`,允许选择其他目录及本机可用端口。已有便携安装应选择包含 ComfyUI 和 python_embeded 的根目录,而不是 models、ComfyUI 子目录或旧 .vant-art。
8
+
9
+ 空目录输入时,组织层可用 discoverInstallations 读取环境索引,并在默认目录、用户 AI 目录及 Windows C:/AI、D:/AI、E:/AI 有界扫描环境标记和 ComfyUI。扫描有深度和数量预算,不是全盘检索。独立 CLI deployment plan 必须明确 --directory,不会自行执行界面的自动选择逻辑。
10
+
11
+ 端口自动选择只证明检测时可绑定,不预约端口。目录或端口变更后重新检测,确认的地址随环境保存;实际启动仍可能因端口被其他程序占用而失败。不能把其他进程监听同一端口视为此目录的环境。
12
+
13
+ ## 已有环境复用
14
+
15
+ 1. 检查 Python、ComfyUI、GGUF 节点、固定模型文件及大小,检查生成与编辑工作流的实际节点能力和端口归属。
16
+ 2. 对可复用但未登记环境,adoptInstallation 流式验证模型 SHA256,连接或启动对应服务,核验能力后写入标记及用户环境索引。保留原模型;不因未登记而再次下载整套环境。
17
+ 3. 接入检测的 verification=capabilities 只代表环境和工作流能力验证。新部署产生的真实生成、编辑验证图是另一等级证据,不能混称。
18
+ 4. 缺文件或版本不符时展示具体差异。固定部署不自动覆写不匹配源码、模型或用户安装;先明确处理差异,再生成新预案。
19
+
20
+ ## 独立 CLI 流程
21
+
22
+ 以下示例使用已核对的安装目录与端口;启动前必须有部署、下载及验证采样的任务授权。
23
+
24
+ ```sh
25
+ v-cli art deployment plan --directory C:/AI/ComfyUI_windows_portable --endpoint http://127.0.0.1:8188/ --out deployment.json
26
+ v-cli art deployment start --plan deployment.json --operation local-deploy-001
27
+ v-cli art deployment status --id DEPLOYMENT
28
+ v-cli art deployment cancel --id DEPLOYMENT
29
+ v-cli art deployment recover --operation local-deploy-001
30
+ ```
31
+
32
+ plan 检测 GPU、Python、文件与磁盘,不下载、不启动、不采样;现有文件存在不等于哈希已验证。start 复核冻结预案后创建后台 deploymentId,逐阶段记录实际进度,按固定方案安装、校验、生成与编辑采样;完成后才提交配置。下载或校验失败不覆写既有冲突文件。
33
+
34
+ status 查询原部署。cancel 只停止已核验的本部署进程与采样,不删除用户素材或原模型,不关闭用户先前启动的服务。recover 只找回唯一原登记,不重复安装。工作进程丢失或停止未确认时保留 unknown 与安装占用。
35
+
36
+ ## 存储与关闭
37
+
38
+ 安装根保存程序、模型和 vant.art.config.json;环境索引、受管服务身份、日志和验证证据归 ~/.vant/state。项目生图归工程绑定的 .vant/art,不能写入共享模型环境。
39
+
40
+ Vant 退出使用其应用生命周期清理关联后台任务,并关闭可核验为 Vant 启动的 ComfyUI,确认本机端口释放。单独关闭部署窗口不取消部署。CLI shutdown 的工作区与共享服务边界见 [任务控制](troubleshooting.md)。
@@ -0,0 +1,52 @@
1
+ # 模型与执行架构
2
+
3
+ 模型扩展不修改任务调度和界面判断。未知型号、未知协议、无效响应都明确失败;提交结果未知时禁止重复提交。
4
+
5
+ | 模块 | 职责 |
6
+ | --- | --- |
7
+ | `lib/model-catalog.mjs` | 模型型号、输入输出能力、参数规则、尺寸、协议操作和展示说明 |
8
+ | `lib/model-registry.mjs` | 启动时验证并索引定义;提供执行契约及统一资格判断 |
9
+ | `lib/generation-policy.mjs` | 校验、规范化请求、记录参数转换、冻结和复核执行契约 |
10
+ | `lib/adapters/` | 协议登记、准备输入、序列化、提交、查询、响应解析 |
11
+ | `lib/execution/remote.mjs` | 持久化回执后轮询、取消等待、恢复原任务、下载原结果 |
12
+ | `lib/transport/` | 有界 HTTP/JSON 与 CLI 子进程,不承载模型判断 |
13
+
14
+ 界面与配置保存共用 `modelEligibility`。接口类型列表由适配器注册表提供;模型发现只补齐准确型号的声明能力,不推定账号权限或自动启用。
15
+
16
+ ## 扩展规则
17
+
18
+ 同协议新模型增加完整模型定义与契约测试。字段规则描述类型、默认值、范围或枚举及协议字段名;参数不再受全局固定白名单限制。模型声明在启动时检查重复标识、必要限制和协议字段。
19
+
20
+ 新协议实现 `prepare / submit / query`,通过 `createAdapterRegistry` 登记。同步提交返回完成结果;异步提交返回上游任务身份。界面、任务运行时不包含型号名称分支。输入文件限制由模型声明提供。
21
+
22
+ `art/model-contract-v1` 排除型号别名列表、展示说明、来源链接及 CLI 示例字段;这些文案变化不改变执行哈希。`art/image-request-v1` 保存规范化请求,`art/execution-contract-v1` 冻结逐项契约。请求参数、尺寸、转换策略或协议规则变化必须重新预演。没有当前执行契约的旧预案不能启动。
23
+
24
+ ## 生命周期
25
+
26
+ 每个计划项分别保存 `remoteExecutions[inputHash]`,包括 schema=art/remote-receipt-v1、请求哈希、适配器及版本、服务地址、提交时间、上游任务 ID 和结果。回执不保存 API Key。
27
+
28
+ 1. `prepare` 先检查凭据与输入,不发起生成。
29
+ 2. 持久化 `dispatching` 后才能 POST。
30
+ 3. 持久化 `accepted + taskId` 后才能查询。
31
+ 4. 持久化 `completed + urls` 后才能下载。
32
+ 5. 下载采用临时文件和排他发布,不覆盖已有不同内容的产物。
33
+
34
+ 提交中断而无任务 ID 的运行保持未知,不能重发。取消等待不等于上游取消;适配器没有停止能力时保留任务身份和占用。
35
+
36
+ ```sh
37
+ v-cli art task resume TASK
38
+ ```
39
+
40
+ `task resume` 仅恢复原上游任务查询或原结果下载,不调用提交接口,也不补发尚未提交的项目。已有成功产物跳过;参数及请求身份不同、原工作进程仍活着、原提交结果未知均拒绝恢复。恢复沿用 taskId、manifest 和每项输入哈希。
41
+
42
+ 上游已完成而本地下载失败时,恢复原运行取回结果,不能通过失败项重试再次付费生成。原运行查询入口 `task recover --operation` 仍只查登记,不隐式启动工作进程。
43
+
44
+ Vant 通过 `ART_IMAGE_CONNECTION` 和 `ART_IMAGE_KEY` 注入连接,不绑定厂商命名。单独使用 DashScope 时,适配器通过固定版本的百炼核心库读取既有 API Key 配置;明确注入连接后不回退到其他凭据或站点。
45
+
46
+ ## 验证边界
47
+
48
+ 单元与协议模拟验证声明扩展、统一筛选、严格响应和回执顺序;真实子进程测试验证工作进程丢失及取消后恢复,统计生成 POST 次数不增加。上述验证不等同于付费模型真实出图或已安装版本更新。
49
+
50
+ 新模型至少覆盖合法请求、参数边界、模式和输入拒绝;新协议还需覆盖提交结果未知、持久化失败、按原身份恢复、取消及下载失败。HTTP 响应体、下载大小和时间有界;认证请求禁止重定向,下载不携带模型密钥。当前查询异常保留身份并停止等待,不自动重试查询或提交。
51
+
52
+ [适配目录](remote-models.md) · [任务控制](troubleshooting.md) · [配置](configuration.md)
package/docs/modes.md ADDED
@@ -0,0 +1,39 @@
1
+ # 模式与调用流程
2
+
3
+ ## 风格分析与核心冻结
4
+
5
+ 创建风格草稿,按 style、palette、shape-language、rendering 分类导入私有参考。style analyze --dry 只编译;实际 analyze 创建 taskId 和独立证据。报告绑定配置版本、图片哈希、分析模型和规则指纹;更新配置或参考后必须重新分析。冲突与未知项未处理时不能采用。
6
+
7
+ style adopt 冻结当前已审阅报告;style recover 只恢复原已授权采用事务。正式风格只读,修改使用 derive,不能复制文件改身份。任务动态参考用 job analyze,只转写指定内容用途,不替代静态风格。
8
+
9
+ ## 远程文生图
10
+
11
+ 选择已启用、目录可用、保存凭据且已适配的图片模型。先 generate show,再 generate plan 保存计划,run --plan --dry 核对请求,再按授权执行。生成 API 由协议适配器直接调用;CLI 示例仅为诊断,不是实际提交链路。
12
+
13
+ 型号的生成/编辑模式、输入数量、尺寸、提示词与参数限制统一来自 [模型目录](remote-models.md)。不能把 URL+Key 或 image 标签视为已经适配;不能以注册型号推定账号权限。
14
+
15
+ ## 本地内置文生图
16
+
17
+ ComfyUI 后端省略 workflow 时使用 Qwen Image 2.1 Q4 与 CPU 文本编码器。config validate 校验模板,doctor 检查服务、节点与模型;doctor --start 可启动并保留服务,不采样。plan/dry 不启动服务。内置工作流不证明模型文件、节点和显存已就绪。
18
+
19
+ ## 本地自定义文生图
20
+
21
+ CLI 支持显式 API workflow 与 bindings,调用方负责节点、参数、输入图、数量、输出与生命周期适配。Vant 当前只开放已适配内置方案,不把任意工作流导入作为可运行选择。
22
+
23
+ ## 远程图编辑
24
+
25
+ 显式绑定 source 及哈希,声明 changes、preserve 和 mustRead。修改与保留不能冲突。默认保留原图风格;绑定目标 core 后不再重复声明修改或保留 style。必须使用支持 edit 的准确型号,不能套用文生图端点。
26
+
27
+ 上传、提交、查询和下载使用冻结请求。上游身份保存在原运行,恢复仅查询原任务或取回原结果,不重新提交。
28
+
29
+ ## 本地 Qwen 2.1 图编辑
30
+
31
+ 使用适配后的 LoadImage.image、VAE 和图像编码器连接,底图上传后显式绑定。latent 输出尺寸与编码器 resolution 分开。服务可连接不等于真实编辑成功,验证需实际底图和输出。
32
+
33
+ ## 生成与定版
34
+
35
+ 前台和后台真实运行均登记 taskId。候选必须有可核验计划、运行身份和完整文件。check 仅做技术完整性检查,candidate finalize 记录用户选择;没有人工三维评分或「验收此图」阶段。
36
+
37
+ 按资产定版,重复请求幂等;替换用 --replace 并保留历史。candidate delete 用 --confirm 明确影响,拒绝运行中或受引用文件。定版不会自动导入游戏或提交 Git。
38
+
39
+ 空闲任务可更新配置后重新编译运行,原批次保留。派生任务独立建立身份,不继承报告、授权、执行或定版。[全部命令](commands.md) · [取消与恢复](troubleshooting.md)
@@ -0,0 +1,42 @@
1
+ # 远程图片适配与筛选
2
+
3
+ 型号、能力、参数与支持状态的唯一事实源是工具内部 lib/model-catalog.mjs;lib/model-registry.mjs 提供准确查找和统一资格判断。Vant 展示登记目录,不维护第二份模型清单。
4
+
5
+ ## 已适配范围
6
+
7
+ | 模型 | 模式 | 总像素范围 | 输入与主要限制 |
8
+ | --- | --- | --- | --- |
9
+ | Qwen Image 2.0 / Pro | generate、edit | 512²–2048² | 编辑 1–3 图;编辑尺寸 16 对齐;负向词最多 500 字符;正向词官方上限 1300 Token |
10
+ | Qwen Image 3.0 / Pro | generate、edit | 512²–2048² | 编辑 1–3 图;负向词最多 500 字符 |
11
+ | Wan 2.7 | generate、edit | 768²–2048² | 编辑 1–9 图;比例 1:8–8:1 |
12
+ | Wan 2.7 Pro | generate、edit | 无图生成 768²–4096²;带图最高 2048² | 编辑 1–9 图;比例 1:8–8:1 |
13
+ | wan2.6-t2i | 仅 generate | 1280²–1440² | 无输入图;比例 1:4–4:1;16 对齐;异步任务 |
14
+ | wan2.6-image | 仅 edit | 768²–2048² | 1–4 图;比例 1:4–4:1;16 对齐;不开放流式图文混排 |
15
+
16
+ 准确标识包括 qwen-image-2.0、qwen-image-2.0-pro、qwen-image-3.0、qwen-image-3.0-pro、wan2.7-image、wan2.7-image-pro,以及 2.0-2026-03-03、2.0-pro-2026-03-03/04-22/06-22 快照。快照使用完整 qwen-image- 前缀,不靠前缀通配放行未来型号。
17
+
18
+ 工具共同边界为单边 256–4096、每项 1–4 张、seed 0–2147483647;各模型额外限制取交集。尺寸在计划阶段选择最近合法值,记录请求、实际值和调整原因;设计任务保留设计基准。Token 数由服务端计算,不用字符数冒充。
19
+
20
+ Wan 2.7 不支持独立负向参数和提示词扩写开关:负向约束明确并入主提示词,合并后最多 5000 字符;显式开启 promptExtend 被拒绝。Wan 2.6 支持负向参数与扩写,主提示词最多 2000 字符、负向词最多 500 字符。不能把 2.7 限制推广到所有万相。
21
+
22
+ 预演与实际执行使用同一规范化请求。组图、框选、调色板和流式混排等未声明能力不自动开放,工具不承诺请求尺寸与服务端输出逐像素一致。
23
+
24
+ ## 仅登记与未知型号
25
+
26
+ 早期 Qwen Image/Max/Plus/Edit、Wan 2.5/2.2/2.1/2.0/V1 和 ImageEdit/Sketch/X-Painting 记录官方来源、支持状态及限制,不套用新型号协议执行。未精确登记的型号拒绝,不因名字相似自动推断支持。
27
+
28
+ modelCatalog() 返回工具登记,不是账号可用模型列表;resolveModel(api, model) 返回精确支持状态。注册不注入账号目录、不自动启用、不推定权限。
29
+
30
+ ## 统一筛选
31
+
32
+ modelEligibility 共用于界面与配置保存,按实例启用、目录可用、模型启用、已保存凭据、图片协议、图片输出能力和准确型号支持状态给出原因。只有 ID 的未知元数据可从已适配型号补能力;显式用户能力配置受到尊重,不能因此跳过协议和模型策略。
33
+
34
+ 视觉分析要求图片输入和文字输出,与图片生成筛选分开。具体执行还要校验 generate/edit 模式、输入数量、参数和尺寸;实例能够选中不保证每个任务都合法。
35
+
36
+ ## 协议、渠道与恢复
37
+
38
+ Token Plan 是订阅渠道,DashScope 是 API 协议。按量与订阅共用适配目录,但始终保留所选实例原地址及密钥,不切换站点,不推定套餐提供同等权限。请求采用 native DashScope 适配器,CLI 只是可选诊断示例。
39
+
40
+ 异步模型保存上游 taskId 后查询;同步模型保存完成 URL 后下载。取消只停止本地等待,恢复仅查询原身份和取回原结果。[生命周期](model-architecture.md) · [异常处理](troubleshooting.md)
41
+
42
+ 登记依据链接:[Qwen 2 生成](https://help.aliyun.com/zh/model-studio/qwen-image-api)、[Qwen 2 编辑](https://help.aliyun.com/zh/model-studio/qwen-image-edit-api)、[Wan 2.7](https://help.aliyun.com/zh/model-studio/wan-image-generation-and-editing-api-reference)、[Wan 2.6 文生图](https://help.aliyun.com/zh/model-studio/text-to-image-v2-api-reference)、[Wan 2.6 编辑](https://help.aliyun.com/zh/model-studio/wan-image-generation-api-reference)。本文说明当前代码登记范围,不声称远端账号已开通或本轮已真实付费出图。
@@ -0,0 +1,46 @@
1
+ # 任务控制与诊断
2
+
3
+ ## 先核对事实
4
+
5
+ 先 config validate,再 doctor;远程 doctor 只核对配置,不验证认证、账号授权或云端连通性。本地 doctor 默认不启动、不采样;--start 可启动并保留服务。真实生成仍须 plan/dry 和任务授权。
6
+
7
+ 技术检查不证明画面质量;mock 不证明模型真实出图;服务可连接不证明显存足够;包构建不证明安装及桌面交互通过。
8
+
9
+ ## 状态与占用
10
+
11
+ task status 返回原运行阶段、心跳、工作进程、后端身份、manifestPath、错误和停止证据。queued/running/cancelling 仍占用对象。释放必须是已知终态、stopConfirmed=true,且无 unsettled、promptId、remoteCancellation 或 dispatching/accepted 远程回执;unknown 一律保留占用。
12
+
13
+ 工作进程丢失且心跳过期标记 unknown,不能推测上游停止。task wait 超时不取消;切面板不取消;本地客户端退出不代表云端取消或费用撤销。
14
+
15
+ ## 查询、恢复和重试
16
+
17
+ | 情况 | 入口 | 行为 |
18
+ | --- | --- | --- |
19
+ | 已知 taskId | task status / task wait | 查询原运行 |
20
+ | 启动回执丢失 | task recover --project P --operation ID | 唯一原登记查找;不启动进程 |
21
+ | 已有 accepted/completed 远程回执 | task resume TASK | 原 taskId 继续查询与下载,不发生成 POST |
22
+ | dispatching 中断但无上游 ID | 保留未知,核对原提供方记录 | 不允许猜测恢复或重发 |
23
+ | 上游完成但下载失败 | task resume TASK | 取回原结果,不付费重生成 |
24
+ | 明确失败且停止确认 | run --plan FILE --retry-run RUN | 新批次只重试明确失败项,记录 retryOf |
25
+ | 风格采用事务中断 | style recover | 完成原事务,不重新冻结另一份核心 |
26
+ | 部署启动回执丢失 | deployment recover --operation ID | 只读恢复唯一登记 |
27
+
28
+ resume 要求原工作进程已退出、运行终态、回执和冻结请求哈希一致。跳过成功文件、上游失败或取消项,不补发未提交项。无回执、身份不符或无可查询/取回项目均拒绝。查询失败保留原 ID;当前不自动重发提交或自动重试查询。
29
+
30
+ retry-run 不能混用 dry/item/variant/offset/limit;原批次和先前重试必须停止确认,成功项不重复执行,远程完成待下载项不能走重生成。配置、模型契约、规格、核心、参考、底图或工作流变化后重编译,不能运行过期预案。
31
+
32
+ ## 取消与关闭
33
+
34
+ task cancel 定向取消本工作区运行。本地按 promptId 处理自有请求,保留 ComfyUI 服务;远程无已适配上游取消能力时只停止本地等待,保留原身份与未知停止事实。
35
+
36
+ CLI shutdown 阻止新提交,停止当前工作区关联任务,再核验共享队列及服务进程身份。它不清空共享队列;存在其他运行/排队请求、停止未知或身份不可验证时保留服务。不要广泛杀所有 Python。
37
+
38
+ Vant 应用退出有独立所有权清理:关闭 Vant 启动并登记的后台进程和 ComfyUI,检查端口释放,不把外部用户服务收编为退出时终止目标。窗口关闭、CLI shutdown、应用退出三个入口的作用域不同。
39
+
40
+ ## 常见配置问题
41
+
42
+ - 模型无法选择:依次核对实例/模型启用、目录可用、凭据、输出能力、图片协议、准确型号及模式支持。仅登记型号显示限制原因,不可执行;手工能力覆盖不能绕过缺失的协议适配。
43
+ - 报告过期或 revision 冲突:重新读取对象及版本,不覆盖用户输入;更新后重新分析或预演。
44
+ - 模型已存在仍提示部署:核对选择的是便携根目录、文件准确名称与大小,再做 SHA256 和能力接入;不以文件存在替代完整环境验证。
45
+ - 端口被占:区分原环境和其他程序,修改端口后重新检测;自动选择端口不等于长期预约。
46
+ - 候选删除清理失败:保留删除事实,仅重试所属文件清理,不恢复成可用候选。