@kevlns/art-workshop 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/AGENTS.md +25 -109
  2. package/LICENSE +21 -21
  3. package/README.md +63 -63
  4. package/art-workshop.mjs +174 -168
  5. package/docs/commands.md +116 -8
  6. package/docs/configuration.md +82 -82
  7. package/docs/core-guidance.md +50 -50
  8. package/docs/data-formats.md +85 -85
  9. package/docs/deployment.md +32 -32
  10. package/docs/local-models/qwen-image-2.1.json +73 -73
  11. package/docs/local-models/qwen-image-2.1.md +33 -33
  12. package/docs/model-architecture.md +78 -78
  13. package/docs/modes.md +67 -67
  14. package/lib/agent.mjs +32 -47
  15. package/lib/analysis-worker.mjs +32 -29
  16. package/lib/analyze.mjs +85 -78
  17. package/lib/asset-profile.mjs +23 -21
  18. package/lib/candidates.mjs +103 -101
  19. package/lib/comfy-recovery.mjs +17 -17
  20. package/lib/conversation.mjs +77 -0
  21. package/lib/core.mjs +75 -89
  22. package/lib/deployment-guide.mjs +12 -12
  23. package/lib/design.mjs +29 -29
  24. package/lib/dimensions.mjs +22 -22
  25. package/lib/edit.mjs +41 -40
  26. package/lib/environment-operations.mjs +49 -49
  27. package/lib/environment-runtime.mjs +99 -99
  28. package/lib/environments.mjs +55 -55
  29. package/lib/errors.mjs +32 -0
  30. package/lib/executor.mjs +107 -107
  31. package/lib/generate.mjs +58 -57
  32. package/lib/heartbeat.mjs +16 -16
  33. package/lib/images.mjs +1 -1
  34. package/lib/lifecycle.mjs +53 -53
  35. package/lib/migration.mjs +154 -154
  36. package/lib/object-format.mjs +112 -0
  37. package/lib/process-identity.mjs +14 -14
  38. package/lib/project.mjs +39 -39
  39. package/lib/refs.mjs +26 -26
  40. package/lib/runtime.mjs +25 -25
  41. package/lib/service.mjs +126 -126
  42. package/lib/settings.mjs +50 -50
  43. package/lib/shared.mjs +67 -66
  44. package/lib/style-bundle.mjs +85 -85
  45. package/lib/style-contract.mjs +74 -35
  46. package/lib/style-evidence.mjs +39 -0
  47. package/lib/style-lifecycle.mjs +125 -120
  48. package/lib/style-report.mjs +201 -0
  49. package/lib/style-review.mjs +14 -75
  50. package/lib/task-contract.mjs +93 -91
  51. package/lib/tasks.mjs +497 -495
  52. package/lib/templates.mjs +80 -74
  53. package/lib/vision.mjs +56 -46
  54. package/lib/workspace.mjs +292 -238
  55. package/package.json +3 -5
  56. package/rules/core-guidance.json +22 -22
  57. package/skills/art-workshop/SKILL.md +17 -116
  58. package/skills/art-workshop/references/conversation.md +11 -0
  59. package/skills/art-workshop/references/expression.md +27 -0
  60. package/skills/art-workshop/references/getty.md +76 -0
  61. package/skills/art-workshop/references/project.md +109 -0
  62. package/skills/art-workshop/references/style-discussion.md +27 -0
  63. package/skills/art-workshop/scripts/getty.py +269 -0
  64. package/v-cli.plugin.json +2747 -2491
  65. package/scripts/sync-skill.mjs +0 -6
  66. /package/{skills/art-workshop → adapters/codex}/agents/openai.yaml +0 -0
@@ -1,82 +1,82 @@
1
- # Vant 配置与存储
2
-
3
- ## 定位
4
-
5
- 配置与存储,适用于当前随包实现。
6
-
7
- ## 前置条件
8
-
9
- 先按包的环境要求准备工程与工具,使用实际配置和命令帮助核对目标。
10
-
11
- ## 字段与示例
12
-
13
- ### 配置入口
14
-
15
- `config path/show/init/validate` 分别查询位置、生效配置、创建模板和校验。`config init` 不覆盖已有文件。查询、发现和预演不创建参考目录;`config validate` 不联网、不启动服务。
16
-
17
- 配置位置优先级为 CLI `--config`、`ART_WORKSHOP_CONFIG`、`<VANT_HOME 或 ~/.vant>/tools/art-workshop/config.json`。资源路径优先级为 CLI 路径选项、配置 paths、默认路径。配置文件和资源均须位于工具安装目录之外。
18
-
19
- | 字段 | 职责与默认值 |
20
- | --- | --- |
21
- | paths.workspace | 默认 ~/.vant/tools/art-workshop/workspace,保存 projects 和 .runtime |
22
- | paths.output | 默认与 workspace 相同;执行批次与候选产物根 |
23
- | paths.refs | 默认 workspace/refs,素材导入基准;不是对象的权威参考目录 |
24
- | paths.cache | 默认 workspace/.cache,分析等缓存 |
25
- | execution | 全局执行默认值,具体范围由所选模型策略校验 |
26
- | generation | defaultBackend、defaults、backends |
27
- | analysisModel | 分析模型默认值,连接仍需单独就绪 |
28
- | defaultProject | 未传 --project 时的工程 ID,不跨工程回退 |
29
- | autoSyncSkills | 默认 true;实际分析、采用、运行入口可刷新随包技能,查询与 dry 不刷新 |
30
-
31
- Vant 显式传入绑定,把工程对象、参考、批次及图片集中在工程 `.vant/art`。独立 CLI 默认 workspace 可以容纳多个工程,不自动绑定当前 Git 工程。普通输入、计划和报告相对路径以 workspace 为基准;`check RUN` 相对批次以 output 为基准。参考源文件建议提供绝对路径。
32
-
33
- ### 后端配置
34
-
35
- 远程 provider 为后端类别标识;执行协议来自 credentialReference.api,缺省 DashScope。协议必须已注册,型号必须在该协议目录中精确登记且支持所需模式。provider 名称不是权限或协议兼容性的证明。
36
-
37
- 下面仅示例结构,不含凭据。具体参数以 [适配目录](remote-models.md) 和生成预演为准。
38
-
39
- ```json
40
- {
41
- "generation": {
42
- "defaultBackend": "remote-image",
43
- "backends": {
44
- "remote-image": {
45
- "provider": "bailian",
46
- "model": "qwen-image-2.0-pro",
47
- "execution": { "size": "1024*1024", "perValue": 1, "watermark": false }
48
- }
49
- }
50
- }
51
- }
52
- ```
53
-
54
- ComfyUI 后端使用 provider=comfyui,声明 model、endpoints,以及可选 workflow、bindings、options、launch。省略 workflow 使用随包固定方案;自定义工作流必须是 API JSON,bindings 指向真实节点输入。endpoints 只允许本机 HTTP 根地址。launch 明确 executable/cwd/args;工具以 argv 启动,不拼接 shell。详情见 [本地部署](deployment.md)。
55
-
56
- ### 认证与实例
57
-
58
- Vant 系统模型配置统一保存 Provider 实例及凭据,工程只引用实例身份、修订及不含密钥的连接信息。模板只负责预填新实例,不是可执行连接。模型目录发现、能力登记、启用与账号权限是不同事实。
59
-
60
- 远程图片由组织层通过 ART_IMAGE_CONNECTION(api/baseUrl)和 ART_IMAGE_KEY 注入内存;明确连接缺少密钥时拒绝,不能回退另一份密钥或站点。直接调用 DashScope 使用固定版本百炼核心库的既有认证来源。
61
-
62
- 视觉分析独立使用 ART_VISION_CONFIG 与 ART_VISION_KEY,支持 openai-completions、openai-responses、anthropic-messages、google-generative-ai。未注入连接时分析走百炼 CLI。不要把图片输出模型当作视觉分析模型;分析要求图片输入和文字输出。
63
-
64
- 凭据不进入工程、计划、运行回执、日志或命令行。Token Plan 与按量渠道保留各自实例地址和密钥,不跨渠道回退。配置校验不证明凭据有效、模型授权或实际出图。
65
-
66
- ### 状态与共享环境
67
-
68
- 对象变更锁和执行登记归 workspace/.runtime;更换配置文件不产生另一套占用。共享服务登记归用户数据根的 state/art-services,环境索引、接入日志和证据归 state/art-environments。安装根保存模型、程序与 vant.art.config.json,控制数据写入用户 .vant 数据目录。
69
-
70
-
71
-
72
- ## 执行边界
73
-
74
- 字段、路径与权限以当前 schema、运行时校验和明确授权为准;配置有效不等于外部服务已执行成功。
75
-
76
- ## 结果验证
77
-
78
- 结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
79
-
80
- ## 参考资料
81
-
82
- [使用说明](../README.md)
1
+ # Vant 配置与存储
2
+
3
+ ## 定位
4
+
5
+ 配置与存储,适用于当前随包实现。
6
+
7
+ ## 前置条件
8
+
9
+ 先按包的环境要求准备工程与工具,使用实际配置和命令帮助核对目标。
10
+
11
+ ## 字段与示例
12
+
13
+ ### 配置入口
14
+
15
+ `config path/show/init/validate` 分别查询位置、生效配置、创建模板和校验。`config init` 不覆盖已有文件。查询、发现和预演不创建参考目录;`config validate` 不联网、不启动服务。
16
+
17
+ 配置位置优先级为 CLI `--config`、`ART_WORKSHOP_CONFIG`、`<VANT_HOME 或 ~/.vant>/tools/art-workshop/config.json`。资源路径优先级为 CLI 路径选项、配置 paths、默认路径。配置文件和资源均须位于工具安装目录之外。
18
+
19
+ | 字段 | 职责与默认值 |
20
+ | --- | --- |
21
+ | paths.workspace | 默认 ~/.vant/tools/art-workshop/workspace,保存 projects 和 .runtime |
22
+ | paths.output | 默认与 workspace 相同;执行批次与候选产物根 |
23
+ | paths.refs | 默认 workspace/refs,素材导入基准;不是对象的权威参考目录 |
24
+ | paths.cache | 默认 workspace/.cache,分析等缓存 |
25
+ | execution | 全局执行默认值,具体范围由所选模型策略校验 |
26
+ | generation | defaultBackend、defaults、backends |
27
+ | analysisModel | 分析模型默认值,连接仍需单独就绪 |
28
+ | defaultProject | 未传 --project 时的工程 ID,不跨工程回退 |
29
+ | autoSyncSkills | 旧配置兼容读取,已停用;安装和运行不向外部 Agent 写文件 |
30
+
31
+ Vant 显式传入绑定,把工程对象、参考、批次及图片集中在工程 `.vant/art`。独立 CLI 默认 workspace 可以容纳多个工程,不自动绑定当前 Git 工程。普通输入、计划和报告相对路径以 workspace 为基准;`check RUN` 相对批次以 output 为基准。参考源文件建议提供绝对路径。
32
+
33
+ ### 后端配置
34
+
35
+ 远程 provider 为后端类别标识;执行协议来自 credentialReference.api,缺省 DashScope。协议必须已注册,型号必须在该协议目录中精确登记且支持所需模式。provider 名称不是权限或协议兼容性的证明。
36
+
37
+ 下面仅示例结构,不含凭据。具体参数以 [适配目录](remote-models.md) 和生成预演为准。
38
+
39
+ ```json
40
+ {
41
+ "generation": {
42
+ "defaultBackend": "remote-image",
43
+ "backends": {
44
+ "remote-image": {
45
+ "provider": "bailian",
46
+ "model": "qwen-image-2.0-pro",
47
+ "execution": { "size": "1024*1024", "perValue": 1, "watermark": false }
48
+ }
49
+ }
50
+ }
51
+ }
52
+ ```
53
+
54
+ ComfyUI 后端使用 provider=comfyui,声明 model、endpoints,以及可选 workflow、bindings、options、launch。省略 workflow 使用随包固定方案;自定义工作流必须是 API JSON,bindings 指向真实节点输入。endpoints 只允许本机 HTTP 根地址。launch 明确 executable/cwd/args;工具以 argv 启动,不拼接 shell。详情见 [本地部署](deployment.md)。
55
+
56
+ ### 认证与实例
57
+
58
+ Vant 系统模型配置统一保存 Provider 实例及凭据,工程只引用实例身份、修订及不含密钥的连接信息。模板只负责预填新实例,不是可执行连接。模型目录发现、能力登记、启用与账号权限是不同事实。
59
+
60
+ 远程图片由组织层通过 ART_IMAGE_CONNECTION(api/baseUrl)和 ART_IMAGE_KEY 注入内存;明确连接缺少密钥时拒绝,不能回退另一份密钥或站点。直接调用 DashScope 使用固定版本百炼核心库的既有认证来源。
61
+
62
+ 视觉分析独立使用 ART_VISION_CONFIG 与 ART_VISION_KEY,支持 openai-completions、openai-responses、anthropic-messages、google-generative-ai。未注入连接时分析走百炼 CLI。不要把图片输出模型当作视觉分析模型;分析要求图片输入和文字输出。
63
+
64
+ 凭据不进入工程、计划、运行回执、日志或命令行。Token Plan 与按量渠道保留各自实例地址和密钥,不跨渠道回退。配置校验不证明凭据有效、模型授权或实际出图。
65
+
66
+ ### 状态与共享环境
67
+
68
+ 对象变更锁和执行登记归 workspace/.runtime;更换配置文件不产生另一套占用。共享服务登记归用户数据根的 state/art-services,环境索引、接入日志和证据归 state/art-environments。安装根保存模型、程序与 vant.art.config.json,控制数据写入用户 .vant 数据目录。
69
+
70
+
71
+
72
+ ## 执行边界
73
+
74
+ 字段、路径与权限以当前 schema、运行时校验和明确授权为准;配置有效不等于外部服务已执行成功。
75
+
76
+ ## 结果验证
77
+
78
+ 结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
79
+
80
+ ## 参考资料
81
+
82
+ [使用说明](../README.md)
@@ -1,50 +1,50 @@
1
- # Vant 风格核心职责与问题决策
2
-
3
- ## 定位
4
-
5
- 风格核心职责与问题决策,适用于当前随包实现。
6
-
7
- ## 前置条件
8
-
9
- 先按包的环境要求准备工程与工具,使用实际配置和命令帮助核对目标。
10
-
11
- ## 操作流程
12
-
13
- 风格定义如何绘制。主体轮廓、比例、部件、姿态、身份色、物理材质、光源、构图与资产尺寸由任务决定。
14
-
15
- ### 最终规范
16
-
17
- 报告和核心使用 schemaVersion=3,项目与对象存储版本仍为2。recommendation 只含 rules:每条具有稳定 id、scope、strength、instruction、when;avoid 可填写 negative 字符串数组。
18
-
19
- - scope:medium、shading、outline、highlights、brushwork、detail、palette。
20
- - strength:required 必须遵守、default 默认倾向、avoid 必须避免。“默认少用”仍使用 default,不升级为禁止。
21
- - instruction:300字以内的独立、准确、精炼绘制要求;不能出现本轮、上一版、修改经过等迭代描述。
22
- - when:适用条件,无条件时为空。局部例外与默认倾向可以共存,不强制精确色值、线宽或色阶。
23
-
24
- 生成提示按主题组织,保留条件与强度。正向表达绘制语言,负向排除抽象的渲染、笔触或语言混杂等特征;负向不能变成主体、部件、身份色、具体材质和纹理的黑名单。不得从参考图中未出现的内容推断禁止条件。
25
-
26
- negative 为可选的被排除特征列表,不加“避免、不要、禁止、no、without”等否定前缀。instruction 为同一规则的阅读说明;条件与例外写入 when。仅无条件 avoid 且明确填写 negative 时编译进独立负向段;其余文字约束及条件排除保留在正向规则段,不猜测条件、不机械转换。default 不升级为负向禁止;正向与负向按路由去重,完整冻结配置保留阅读说明。
27
-
28
- 模型支持独立 negative_prompt 时直接发送;不支持时适配器将负向约束明确并入正向排除段,使用合并后的提示词长度限制,不默默丢弃或截断。ComfyUI 将其绑定到 negativePrompt 输入,缺少绑定则明确报错。界面预案显示适配后实际请求,条件排除和全局负向分别说明。最终核心只使用规则,不把聊天记录、问题解释或证据局限混入生成规范。
29
-
30
- ### 报告与取舍
31
-
32
- summary 概述当前方案,observations 保存分类证据,notes 保存不影响执行的提醒。issues 只表达真正需要用户选择的矛盾,每项有稳定 id、question、reopenReason 与2至5个 options。选项含 id、label、remove 规则ID和 upsert 规则。
33
-
34
- style resolve 校验 revision、报告来源和选项,记录 issueId、问题指纹、optionId、用户依据和时间。选择应用于候选规范,不改变原始模型响应;reviewHistory 记录历次选择。覆盖已有决定涉及的规则时,相关已记录决定重新打开,不静默覆盖。采用要求当前来源匹配、所有问题已有有效决定;notes 非空仍可采用。
35
-
36
- 修改草稿或参考保留报告并标记需复核。已有规则按用户要求修改时,style revise 接收完整 rules、summary 与 note,沿用未变化的参考证据,记录原报告及用户依据,不调用模型、不自动冻结;自由补充不被删除。参考或分析配置改变时须重新分析,未决问题先集中确认。
37
-
38
- 当前职责版本的冻结风格派生后保留结构化规则及独立参考,报告标记 inherited-frozen;用户规则修订标记 user-rules,原模型观察作为证据保留,不伪称重新分析。旧职责版本仍保留只读证据,不能自动转换。
39
-
40
- 需要分析复核时,复核提供上一版方案和决定;同一证据、问题与选项不变时保留决定,新证据或明确重新打开理由要求重新确认。逐图观察按内容和分类契约缓存,未改变的图不重复请求。
41
-
42
-
43
-
44
- ## 结果验证
45
-
46
- 结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
47
-
48
- ## 参考资料
49
-
50
- [使用说明](../README.md)
1
+ # Vant 风格核心职责与问题决策
2
+
3
+ ## 定位
4
+
5
+ 风格核心职责与问题决策,适用于当前随包实现。
6
+
7
+ ## 前置条件
8
+
9
+ 先按包的环境要求准备工程与工具,使用实际配置和命令帮助核对目标。
10
+
11
+ ## 操作流程
12
+
13
+ 风格定义如何绘制。主体轮廓、比例、部件、姿态、身份色、物理材质、光源、构图与资产尺寸由任务决定。
14
+
15
+ ### 最终规范
16
+
17
+ 报告和核心使用 schemaVersion=3,项目与对象存储版本仍为2。recommendation 只含 rules:每条具有稳定 id、scope、strength、instruction、when;avoid 可填写 negative 字符串数组。
18
+
19
+ - scope:medium、shading、outline、highlights、brushwork、detail、palette。
20
+ - strength:required 必须遵守、default 默认倾向、avoid 必须避免。“默认少用”仍使用 default,不升级为禁止。
21
+ - instruction:300字以内的独立、准确、精炼绘制要求;不能出现本轮、上一版、修改经过等迭代描述。
22
+ - when:适用条件,无条件时为空。局部例外与默认倾向可以共存,不强制精确色值、线宽或色阶。
23
+
24
+ 生成提示按主题组织,保留条件与强度。正向表达绘制语言,负向排除抽象的渲染、笔触或语言混杂等特征;负向不能变成主体、部件、身份色、具体材质和纹理的黑名单。不得从参考图中未出现的内容推断禁止条件。
25
+
26
+ negative 为可选的被排除特征列表,不加“避免、不要、禁止、no、without”等否定前缀。instruction 为同一规则的阅读说明;条件与例外写入 when。仅无条件 avoid 且明确填写 negative 时编译进独立负向段;其余文字约束及条件排除保留在正向规则段,不猜测条件、不机械转换。default 不升级为负向禁止;正向与负向按路由去重,完整冻结配置保留阅读说明。
27
+
28
+ 模型支持独立 negative_prompt 时直接发送;不支持时适配器将负向约束明确并入正向排除段,使用合并后的提示词长度限制,不默默丢弃或截断。ComfyUI 将其绑定到 negativePrompt 输入,缺少绑定则明确报错。界面预案显示适配后实际请求,条件排除和全局负向分别说明。最终核心只使用规则,不把聊天记录、问题解释或证据局限混入生成规范。
29
+
30
+ ### 报告与取舍
31
+
32
+ summary 概述当前方案,observations 保存分类证据,notes 保存不影响执行的提醒。issues 只表达真正需要用户选择的矛盾,每项有稳定 id、question、reopenReason 与2至5个 options。选项含 id、label、remove 规则ID和 upsert 规则。
33
+
34
+ style resolve 校验 revision、报告来源和选项,记录 issueId、问题指纹、optionId、用户依据和时间。选择应用于候选规范,不改变原始模型响应;reviewHistory 记录历次选择。覆盖已有决定涉及的规则时,相关已记录决定重新打开,不静默覆盖。采用要求当前来源匹配、所有问题已有有效决定;notes 非空仍可采用。
35
+
36
+ 修改草稿或参考保留报告并标记需复核。已有规则按用户要求修改时,style revise 接收完整 rules、summary 与 note,沿用未变化的参考证据,记录原报告及用户依据,不调用模型、不自动冻结;自由补充不被删除。参考或分析配置改变时须重新分析,未决问题先集中确认。
37
+
38
+ 当前职责版本的冻结风格派生后保留结构化规则及独立参考,报告标记 inherited-frozen;用户规则修订标记 user-rules,原模型观察作为证据保留,不伪称重新分析。旧职责版本仍保留只读证据,不能自动转换。
39
+
40
+ 需要分析复核时,复核提供上一版方案和决定;同一证据、问题与选项不变时保留决定,新证据或明确重新打开理由要求重新确认。逐图观察按内容和分类契约缓存,未改变的图不重复请求。
41
+
42
+
43
+
44
+ ## 结果验证
45
+
46
+ 结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
47
+
48
+ ## 参考资料
49
+
50
+ [使用说明](../README.md)
@@ -1,85 +1,85 @@
1
- # Vant art 工程与输入结构
2
-
3
- ## 定位
4
-
5
- art 工程与输入结构,适用于当前随包实现。
6
-
7
- ## 前置条件
8
-
9
- 先按包的环境要求准备工程与工具,使用实际配置和命令帮助核对目标。
10
-
11
- ## 字段与示例
12
-
13
- ### 工程和对象
14
-
15
- 动态需求的意图、外观、身份色、动作、效果描述、关系、场景、编辑指令与 mustRead 条目不设字符数上限;原文进入方案,不自动截断。类型、必填内容、字段引用和版本校验仍生效。
16
-
17
- 任务参考只提取 purposes 指定且未被 ignore 排除的特征。用途范围外、用户已明确覆盖的背景和绘制差异不构成阻塞;conflicts 仅列范围内不可调和要求,uncertainties 仅列影响执行的关键缺失,两者为非空字符串数组,无问题用 []。不得删除用户参考或清空报告来绕过分析;应明确参考范围后重新分析,真正的未决取舍再交用户决定。
18
-
19
- project.json 必须声明 schemaVersion=2、revision、id、name、analysisModel、execution、cores、defaultCore。工程身份与目录匹配,核心必须属于同一工程。
20
-
21
- 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,不能改身份与类型。
22
-
23
- 参考记录包括 id、所属对象、对象内相对 path、SHA256、来源、category/purposes、usage、note、ignore。风格三类:style、palette、rendering。任务用途:subject、composition、pose、identity-color、surface、scene-light、text。sources 只放编辑底图。
24
-
25
- ### 需求与计划
26
-
27
- 风格 config 包含 description、constraints、rules 与 analysis(均按需要填写)。rules 每条为 id、scope、strength、instruction、when,avoid 可含 negative 抽象排除表达数组;条件写入 when,职责见 [风格规则](core-guidance.md)。report.evidenceHash 绑定参考与分析配置;provenance.method 区分模型分析、inherited-frozen 沿用冻结证据和 user-rules 用户修订。规则修订保留原报告与依据,采用后生成独立核心哈希。
28
-
29
- 生成 config 包括 project、kind、core、execution、analysis、generation、items,以及互斥的 profile 或内联 asset 规格;实体及效果有稳定 id、数量、颜色、角色与关系。具体主体、构图、动作不冻结进风格。规格定义资产约束、设计基准与检查要点,内联规格属于当前任务,编译时形成同一不可变快照。编辑 config 的 items 明确 source、changes、preserve、mustRead、seed。
30
-
31
- 生成实体可选 material 描述物理材质,按原文进入主体行。composition 的 lightDirection/lightQuality 由资产规格 allowedOverrides 成对提供非空词表,defaults 成对提供词表内默认值。有效值按规格、任务、variant 顺序覆盖,允许单项覆盖;未开放时携带光照键报错。新 custom 模板开放光照,既有规格不自动改写。
32
-
33
- mustRead 保持视觉特征字符串数组。生成和编辑 item 均可选 textSpecs 数组,每项为 {content,hierarchy,zone,fontHint?}:准确文字、层级、位置或载体为必填描述,字形可选,均不限制字数。草稿允许暂缺或留空,编译检查完整性。相同文字的不同位置、层级、字形保留,完全相同项仅在编译输出去重。生成禁文字规格仅拒绝非空 textSpecs,不拒绝视觉特征;编辑任务按底图和修改/保留集处理。文字要求独立编译为画面文字规格段,有文字规格时追加文字保真负向;候选 checks.content 保持字符串数组,accepted 只代表技术完整性。
34
-
35
- job read/list 的 resolvedAsset 是当前有效规格只读投影,assetError 是解析失败说明;两者不属于 config,不能保存为需求。新编译计划带 compilerVersion=4 并参与 planHash;版本不作为执行准入门槛,已有计划缺字段时保留缺席,后端重绑定不补版本。
36
-
37
- plan 包括 schema=art-workshop/plan、module/project/job、sources、snapshots、refs、execution、items、planHash。sources 绑定 taskRevision、taskConfigHash 和 coreHash;项目/核心/profile/任务形成快照。项含 inputHash、实际尺寸和 seed。透明背景为 {type:"transparent"};生成配置位于 composition.background,编辑配置位于 changes 中 target=background 的 value。预案项 output 固定 PNG、透明背景及处理版本并参与哈希;含完全透明区域的原生 alpha 保留,否则从边缘核实洋红底色,容许模型色偏,处理与外边界连通的底色及混合边缘。接近不透明的 alpha 噪声不视为透明背景。记录 outputProcessing,保留原图和透明 PNG。任何来源或哈希变化拒绝运行。
38
-
39
- analysis 为 {provider,model},风格和任务分别保存视觉分析实例。generation 为 {backend,remote?,options?},remote 为 {provider,model};选中后端的模型进入执行与请求快照,旧 execution.model 不覆盖所选后端。options 为当前任务的本地采样覆盖 {steps?,cfg?,sampler?,scheduler?},合并到冻结方案 backend.options,进入实际 ComfyUI 请求;远程后端拒绝这些字段。新任务本地推荐默认值为 steps=25、cfg=3、sampler=euler、scheduler=simple,内置工作流相同。显式值及历史计划保留。省略字段沿用后端或工作流默认值,数值 0 不视为省略。任务切换模型、后端或采样参数会改变配置哈希,必须重新编译。凭据由宿主按实例注入,不保存在配置。
40
-
41
- ### 执行与定版
42
-
43
- 对象 taskId(命令中称 job/id)与执行 taskId 是两种身份;每次真实执行有独立登记。运行记录包含 queued/running/cancelling/succeeded/failed/cancelled/unknown、heartbeat、workerPid、后端身份、manifestPath、stopConfirmed 与 unsettled。终态与停止证据独立;没有停止证据继续占用对象。配置状态及界面分组不能取代运行身份。
44
- 任务归档使用 job discard,在停止已确认且 revision 匹配后标记 status=discarded(归档存储状态)、记录 deletedAt。配置、参考、底图、运行、输出、收藏及定版历史保留。活跃任务、收藏和作品暂不显示归档内容;job restore 将同一任务恢复为 draft、清除 deletedAt 并记录 restoredAt,原收藏和定版重新显示。恢复不产生新完成通知,不自动执行旧方案;任何后续编辑或执行仍校验当前版本。
45
-
46
- manifest 保存计划、每项输出及哈希、失败证据和完成事实。运行查询的 itemStates 按本次提交的资产及变体返回逐项状态,resultVersion 仅随逐项结果变化,不随心跳变化。界面按逐项状态撤销已完成或失败项的占位,并刷新当前批次候选,不等待整批结束或重新加载历史卡片。候选身份绑定运行、资产、构图与文件。定版记录保留资产、候选、批次、哈希、操作者与时间;替换与删除进入历史。删除先记录事实,物理清理可重试。
47
- 候选 editable 表示原批次已停止且底图可用,accepted 表示符合定版所需的输出完整性。输出处理失败时保留的图片仍可进入编辑;已记录的哈希不匹配、文件缺失或已删除不能编辑。历史失败输出没有文件哈希时,只允许将当前可解码图片复制为新编辑草稿的私有底图并记录来源哈希,不补写原批次成功事实。
48
- 工程 favorites.json 使用 schemaVersion=1,items 保存 taskId/runId/candidateId/createdAt,以任务、批次和图片三者联合标识收藏。收藏采用独立写锁和原子保存,不改变任务 revision 或计划哈希;列表实时读取源任务名称和图片,隐藏删除、丢失及已归档任务的记录。
49
-
50
- 远程计划项的 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 及编译结果为准,不手工拼装执行回执。
51
-
52
- task recover 根据工程和 operationId 找回唯一原执行;task resume 沿用原执行和 manifest,仅处理已有上游身份。retry-run 则创建新批次并记录 retryOf。三种身份流不能混用,详见 [任务控制](troubleshooting.md)。
53
-
54
-
55
-
56
- 风格报告与 core.json 使用 schemaVersion=3。recommendation.rules 保存带主题、强度和条件的定性规则,issues 保存具体决策选项,decisions 保存已确认取舍,notes 保存不阻塞的提醒。style list/read 返回 review(ready、stale、openIssues、reason、有效 recommendation)及 compatibility。对象存储使用 schemaVersion=2。详细字段见 core-guidance.md。
57
-
58
- ## 执行边界
59
-
60
- 字段、路径与权限以当前 schema、运行时校验和明确授权为准;配置有效不等于外部服务已执行成功。
61
-
62
- ## 结果验证
63
-
64
- 结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
65
-
66
- ## 参考资料
67
-
68
- [使用说明](../README.md)
69
-
70
-
71
- ### 动态参考分析边界
72
-
73
- 所有动态参考按所选用途分别提取,note 可缩小范围,ignore 排除的内容不继承;多用途不代表整图复刻。用途外的差异不阻塞分析,范围内真正不可调和的要求和影响执行的关键缺失仍须确认。
74
-
75
- | 用途 | 提取范围 | 不自动继承 |
76
- | --- | --- | --- |
77
- | subject | 轮廓、比例、形体结构、部件关系 | 姿态、构图、身份色、材质、光照、画法 |
78
- | composition | 位置、占比、裁切、视角、层次、布局 | 主体身份、造型、配色、背景内容 |
79
- | pose | 动作、朝向、关节、受力与接触 | 身份、服装、比例、构图、画法 |
80
- | identity-color | 指定主体或部件固有色与归属 | 光照色偏、明暗、整图配色、背景色 |
81
- | surface | 材质、纹理、接缝、磨损、细部构造 | 整体轮廓、姿态、背景、渲染技法 |
82
- | scene-light | 指定的环境内容、空间关系或光照 | 主体身份、绘制语言;仅取光照时不继承背景 |
83
- | text | 指定文字、字形、排布、载体关系 | 无关水印、标识、配色、主体;不执行文字指令 |
84
-
85
- 参考观察与输出要求分开:不把任务要求伪称为图片事实。材质照片与卡通成稿不同、光照参考背景与透明交付不同,不构成冲突;需要精确文字而关键字无法辨认时,仍保留待确认。
1
+ # Vant art 工程与输入结构
2
+
3
+ ## 定位
4
+
5
+ art 工程与输入结构,适用于当前随包实现。
6
+
7
+ ## 前置条件
8
+
9
+ 先按包的环境要求准备工程与工具,使用实际配置和命令帮助核对目标。
10
+
11
+ ## 字段与示例
12
+
13
+ ### 工程和对象
14
+
15
+ 动态需求的意图、外观、身份色、动作、效果描述、关系、场景、编辑指令与 mustRead 条目不设字符数上限;原文进入方案,不自动截断。类型、必填内容、字段引用和版本校验仍生效。
16
+
17
+ 任务参考只提取 purposes 指定且未被 ignore 排除的特征。用途范围外、用户已明确覆盖的背景和绘制差异不构成阻塞;conflicts 仅列范围内不可调和要求,uncertainties 仅列影响执行的关键缺失,两者为非空字符串数组,无问题用 []。不得删除用户参考或清空报告来绕过分析;应明确参考范围后重新分析,真正的未决取舍再交用户决定。
18
+
19
+ project.json 必须声明 schemaVersion=2、revision、id、name、analysisModel、execution、cores、defaultCore。工程身份与目录匹配,核心必须属于同一工程。
20
+
21
+ 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,不能改身份与类型。
22
+
23
+ 参考记录包括 id、所属对象、对象内相对 path、SHA256、来源、category/purposes、usage、note、ignore。风格三类:style、palette、rendering。任务用途:subject、composition、pose、identity-color、surface、scene-light、text。sources 只放编辑底图。
24
+
25
+ ### 需求与计划
26
+
27
+ 风格 config 包含 description、constraints、rules 与 analysis(均按需要填写)。rules 每条为 id、scope、strength、instruction、when,avoid 可含 negative 抽象排除表达数组;条件写入 when,职责见 [风格规则](core-guidance.md)。report.evidenceHash 绑定参考与分析配置;provenance.method 区分模型分析、inherited-frozen 沿用冻结证据和 user-rules 用户修订。规则修订保留原报告与依据,采用后生成独立核心哈希。
28
+
29
+ 生成 config 包括 project、kind、core、execution、analysis、generation、items,以及互斥的 profile 或内联 asset 规格;实体及效果有稳定 id、数量、颜色、角色与关系。具体主体、构图、动作不冻结进风格。规格定义资产约束、设计基准与检查要点,内联规格属于当前任务,编译时形成同一不可变快照。编辑 config 的 items 明确 source、changes、preserve、mustRead、seed。
30
+
31
+ 生成实体可选 material 描述物理材质,按原文进入主体行。composition 的 lightDirection/lightQuality 由资产规格 allowedOverrides 成对提供非空词表,defaults 成对提供词表内默认值。有效值按规格、任务、variant 顺序覆盖,允许单项覆盖;未开放时携带光照键报错。新 custom 模板开放光照,既有规格不自动改写。
32
+
33
+ mustRead 保持视觉特征字符串数组。生成和编辑 item 均可选 textSpecs 数组,每项为 {content,hierarchy,zone,fontHint?}:准确文字、层级、位置或载体为必填描述,字形可选,均不限制字数。草稿允许暂缺或留空,编译检查完整性。相同文字的不同位置、层级、字形保留,完全相同项仅在编译输出去重。生成禁文字规格仅拒绝非空 textSpecs,不拒绝视觉特征;编辑任务按底图和修改/保留集处理。文字要求独立编译为画面文字规格段,有文字规格时追加文字保真负向;候选 checks.content 保持字符串数组,accepted 只代表技术完整性。
34
+
35
+ job read/list 的 resolvedAsset 是当前有效规格只读投影,assetError 是解析失败说明;两者不属于 config,不能保存为需求。新编译计划带 compilerVersion=4 并参与 planHash;版本不作为执行准入门槛,已有计划缺字段时保留缺席,后端重绑定不补版本。
36
+
37
+ plan 包括 schema=art-workshop/plan、module/project/job、sources、snapshots、refs、execution、items、planHash。sources 绑定 taskRevision、taskConfigHash 和 coreHash;项目/核心/profile/任务形成快照。项含 inputHash、实际尺寸和 seed。透明背景为 {type:"transparent"};生成配置位于 composition.background,编辑配置位于 changes 中 target=background 的 value。预案项 output 固定 PNG、透明背景及处理版本并参与哈希;含完全透明区域的原生 alpha 保留,否则从边缘核实洋红底色,容许模型色偏,处理与外边界连通的底色及混合边缘。接近不透明的 alpha 噪声不视为透明背景。记录 outputProcessing,保留原图和透明 PNG。任何来源或哈希变化拒绝运行。
38
+
39
+ analysis 为 {provider,model},风格和任务分别保存视觉分析实例。generation 为 {backend,remote?,options?},remote 为 {provider,model};选中后端的模型进入执行与请求快照,旧 execution.model 不覆盖所选后端。options 为当前任务的本地采样覆盖 {steps?,cfg?,sampler?,scheduler?},合并到冻结方案 backend.options,进入实际 ComfyUI 请求;远程后端拒绝这些字段。新任务本地推荐默认值为 steps=25、cfg=3、sampler=euler、scheduler=simple,内置工作流相同。显式值及历史计划保留。省略字段沿用后端或工作流默认值,数值 0 不视为省略。任务切换模型、后端或采样参数会改变配置哈希,必须重新编译。凭据由宿主按实例注入,不保存在配置。
40
+
41
+ ### 执行与定版
42
+
43
+ 对象 taskId(命令中称 job/id)与执行 taskId 是两种身份;每次真实执行有独立登记。运行记录包含 queued/running/cancelling/succeeded/failed/cancelled/unknown、heartbeat、workerPid、后端身份、manifestPath、stopConfirmed 与 unsettled。终态与停止证据独立;没有停止证据继续占用对象。配置状态及界面分组不能取代运行身份。
44
+ 任务归档使用 job discard,在停止已确认且 revision 匹配后标记 status=discarded(归档存储状态)、记录 deletedAt。配置、参考、底图、运行、输出、收藏及定版历史保留。活跃任务、收藏和作品暂不显示归档内容;job restore 将同一任务恢复为 draft、清除 deletedAt 并记录 restoredAt,原收藏和定版重新显示。恢复不产生新完成通知,不自动执行旧方案;任何后续编辑或执行仍校验当前版本。
45
+
46
+ manifest 保存计划、每项输出及哈希、失败证据和完成事实。运行查询的 itemStates 按本次提交的资产及变体返回逐项状态,resultVersion 仅随逐项结果变化,不随心跳变化。界面按逐项状态撤销已完成或失败项的占位,并刷新当前批次候选,不等待整批结束或重新加载历史卡片。候选身份绑定运行、资产、构图与文件。定版记录保留资产、候选、批次、哈希、操作者与时间;替换与删除进入历史。删除先记录事实,物理清理可重试。
47
+ 候选 editable 表示原批次已停止且底图可用,accepted 表示符合定版所需的输出完整性。输出处理失败时保留的图片仍可进入编辑;已记录的哈希不匹配、文件缺失或已删除不能编辑。历史失败输出没有文件哈希时,只允许将当前可解码图片复制为新编辑草稿的私有底图并记录来源哈希,不补写原批次成功事实。
48
+ 工程 favorites.json 使用 schemaVersion=1,items 保存 taskId/runId/candidateId/createdAt,以任务、批次和图片三者联合标识收藏。收藏采用独立写锁和原子保存,不改变任务 revision 或计划哈希;列表实时读取源任务名称和图片,隐藏删除、丢失及已归档任务的记录。
49
+
50
+ 远程计划项的 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 及编译结果为准,不手工拼装执行回执。
51
+
52
+ task recover 根据工程和 operationId 找回唯一原执行;task resume 沿用原执行和 manifest,仅处理已有上游身份。retry-run 则创建新批次并记录 retryOf。三种身份流不能混用,详见 [任务控制](troubleshooting.md)。
53
+
54
+
55
+
56
+ 风格报告与 core.json 使用 schemaVersion=3。recommendation.rules 保存带主题、强度和条件的定性规则,issues 保存具体决策选项,decisions 保存已确认取舍,notes 保存不阻塞的提醒。style list/read 返回 review(ready、stale、openIssues、reason、有效 recommendation)及 compatibility。对象存储使用 schemaVersion=2。详细字段见 core-guidance.md。
57
+
58
+ ## 执行边界
59
+
60
+ 字段、路径与权限以当前 schema、运行时校验和明确授权为准;配置有效不等于外部服务已执行成功。
61
+
62
+ ## 结果验证
63
+
64
+ 结合原始错误、结构化结果和实际产物核验;测试与真实平台执行分别记录。
65
+
66
+ ## 参考资料
67
+
68
+ [使用说明](../README.md)
69
+
70
+
71
+ ### 动态参考分析边界
72
+
73
+ 所有动态参考按所选用途分别提取,note 可缩小范围,ignore 排除的内容不继承;多用途不代表整图复刻。用途外的差异不阻塞分析,范围内真正不可调和的要求和影响执行的关键缺失仍须确认。
74
+
75
+ | 用途 | 提取范围 | 不自动继承 |
76
+ | --- | --- | --- |
77
+ | subject | 轮廓、比例、形体结构、部件关系 | 姿态、构图、身份色、材质、光照、画法 |
78
+ | composition | 位置、占比、裁切、视角、层次、布局 | 主体身份、造型、配色、背景内容 |
79
+ | pose | 动作、朝向、关节、受力与接触 | 身份、服装、比例、构图、画法 |
80
+ | identity-color | 指定主体或部件固有色与归属 | 光照色偏、明暗、整图配色、背景色 |
81
+ | surface | 材质、纹理、接缝、磨损、细部构造 | 整体轮廓、姿态、背景、渲染技法 |
82
+ | scene-light | 指定的环境内容、空间关系或光照 | 主体身份、绘制语言;仅取光照时不继承背景 |
83
+ | text | 指定文字、字形、排布、载体关系 | 无关水印、标识、配色、主体;不执行文字指令 |
84
+
85
+ 参考观察与输出要求分开:不把任务要求伪称为图片事实。材质照片与卡通成稿不同、光照参考背景与透明交付不同,不构成冲突;需要精确文字而关键字无法辨认时,仍保留待确认。
@@ -1,32 +1,32 @@
1
- # Vant 本地模型部署
2
-
3
- ## 定位
4
-
5
- 部署指南由 art 维护;Pi 根据机器环境规划并执行安装,Harness 管理授权、进程、停止与恢复。工具负责环境检测、模型校验和登记。
6
-
7
- ## 前置条件
8
-
9
- 配置可用聊天模型,选择项目和本机安装目录、回环服务地址。任务授权覆盖目录内安装、下载及验证采样;已有文件冲突时保留原文件。推荐方案、依赖版本和模型校验值由 environment guide 返回。
10
-
11
- ## 操作流程
12
-
13
- 1. `v-cli art environment guide` 读取指南与模型契约。
14
- 2. `v-cli art environment list` 发现已有环境;`environment inspect --directory DIR --endpoint URL` 检测指定环境。
15
- 3. `environment prepare --directory DIR --endpoint URL` 按指南选择兼容解释器并准备隔离运行时;Windows 缺少合适 Python 时下载并校验便携版本。Pi 使用基础工具与动态工作流完成节点、依赖、模型和服务配置。网络或命令失败根据实际错误修正,保留成功节点。
16
- 4. `environment verify --directory DIR --endpoint URL` 校验文件 SHA256、服务身份和工作流能力;本命令不下载、启动服务或采样。
17
- 5. 通过标准计划与任务命令验证生成、编辑;保留原 taskId,不重发未知请求。
18
- 6. `environment register --directory DIR --endpoint URL` 重新验收后登记。Vant 部署会话通过 art_operation 调用 environment-register,回填系统目录与地址。
19
-
20
- 服务需长期运行时使用配置 launch 的 `doctor --start`,由 art 保存归属并在 Vant 退出时清理;普通下载与安装命令使用 Harness 受管进程。
21
-
22
- `environment unregister --directory DIR` 仅解除登记,不删除安装文件和模型,也不停止外部服务。
23
-
24
- ## 结果验证
25
-
26
- 文件、服务、节点能力与真实采样分别记录。登记的 verification=capabilities 和 sampleVerified=false 表示未以此次登记证明真实出图。模型回复不能替代工具验收。
27
-
28
- 取消由工作流停止入口处理;普通插话和关闭设置页不终止部署。恢复先核对任务记录、原进程及实际文件,保留有效下载,不重新执行成功节点。未知副作用继续占用,不能当作已停止。
29
-
30
- ## 参考资料
31
-
32
- [部署指南](local-models/qwen-image-2.1.md) · [使用说明](../README.md)
1
+ # Vant 本地模型部署
2
+
3
+ ## 定位
4
+
5
+ 部署指南由 art 维护;Pi 根据机器环境规划并执行安装,Harness 管理授权、进程、停止与恢复。工具负责环境检测、模型校验和登记。
6
+
7
+ ## 前置条件
8
+
9
+ 配置可用聊天模型,选择项目和本机安装目录、回环服务地址。任务授权覆盖目录内安装、下载及验证采样;已有文件冲突时保留原文件。推荐方案、依赖版本和模型校验值由 environment guide 返回。
10
+
11
+ ## 操作流程
12
+
13
+ 1. `v-cli art environment guide` 读取指南与模型契约。
14
+ 2. `v-cli art environment list` 发现已有环境;`environment inspect --directory DIR --endpoint URL` 检测指定环境。
15
+ 3. `environment prepare --directory DIR --endpoint URL` 按指南选择兼容解释器并准备隔离运行时;Windows 缺少合适 Python 时下载并校验便携版本。Pi 使用基础工具与动态工作流完成节点、依赖、模型和服务配置。网络或命令失败根据实际错误修正,保留成功节点。
16
+ 4. `environment verify --directory DIR --endpoint URL` 校验文件 SHA256、服务身份和工作流能力;本命令不下载、启动服务或采样。
17
+ 5. 通过标准计划与任务命令验证生成、编辑;保留原 taskId,不重发未知请求。
18
+ 6. `environment register --directory DIR --endpoint URL` 重新验收后登记。Vant 部署会话通过 art_operation 调用 environment-register,回填系统目录与地址。
19
+
20
+ 服务需长期运行时使用配置 launch 的 `doctor --start`,由 art 保存归属并在 Vant 退出时清理;普通下载与安装命令使用 Harness 受管进程。
21
+
22
+ `environment unregister --directory DIR` 仅解除登记,不删除安装文件和模型,也不停止外部服务。
23
+
24
+ ## 结果验证
25
+
26
+ 文件、服务、节点能力与真实采样分别记录。登记的 verification=capabilities 和 sampleVerified=false 表示未以此次登记证明真实出图。模型回复不能替代工具验收。
27
+
28
+ 取消由工作流停止入口处理;普通插话和关闭设置页不终止部署。恢复先核对任务记录、原进程及实际文件,保留有效下载,不重新执行成功节点。未知副作用继续占用,不能当作已停止。
29
+
30
+ ## 参考资料
31
+
32
+ [部署指南](local-models/qwen-image-2.1.md) · [使用说明](../README.md)