@kevlns/art-workshop 0.4.2 → 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 (68) hide show
  1. package/AGENTS.md +25 -105
  2. package/LICENSE +21 -21
  3. package/README.md +63 -63
  4. package/art-workshop.mjs +174 -167
  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 -79
  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 -0
  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 -38
  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 -59
  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/presentation.mjs +18 -2
  38. package/lib/process-identity.mjs +14 -14
  39. package/lib/project.mjs +39 -39
  40. package/lib/prompt-structure.mjs +7 -3
  41. package/lib/refs.mjs +26 -26
  42. package/lib/runtime.mjs +25 -25
  43. package/lib/service.mjs +126 -126
  44. package/lib/settings.mjs +50 -50
  45. package/lib/shared.mjs +67 -66
  46. package/lib/style-bundle.mjs +85 -85
  47. package/lib/style-contract.mjs +74 -35
  48. package/lib/style-evidence.mjs +39 -0
  49. package/lib/style-lifecycle.mjs +125 -120
  50. package/lib/style-report.mjs +201 -0
  51. package/lib/style-review.mjs +14 -75
  52. package/lib/task-contract.mjs +93 -59
  53. package/lib/tasks.mjs +497 -495
  54. package/lib/templates.mjs +80 -70
  55. package/lib/vision.mjs +56 -46
  56. package/lib/workspace.mjs +292 -238
  57. package/package.json +3 -5
  58. package/rules/core-guidance.json +22 -22
  59. package/skills/art-workshop/SKILL.md +17 -112
  60. package/skills/art-workshop/references/conversation.md +11 -0
  61. package/skills/art-workshop/references/expression.md +27 -0
  62. package/skills/art-workshop/references/getty.md +76 -0
  63. package/skills/art-workshop/references/project.md +109 -0
  64. package/skills/art-workshop/references/style-discussion.md +27 -0
  65. package/skills/art-workshop/scripts/getty.py +269 -0
  66. package/v-cli.plugin.json +2747 -2491
  67. package/scripts/sync-skill.mjs +0 -6
  68. /package/{skills/art-workshop → adapters/codex}/agents/openai.yaml +0 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kevlns/art-workshop",
3
- "version": "0.4.2",
3
+ "version": "0.5.1",
4
4
  "private": false,
5
5
  "description": "管理项目风格、参考图、图片生成、编辑和定版。支持本地 ComfyUI 与远程图片模型。",
6
6
  "type": "module",
@@ -12,17 +12,15 @@
12
12
  "lib/",
13
13
  "rules/",
14
14
  "skills/",
15
- "scripts/sync-skill.mjs",
16
15
  "README.md",
17
16
  "LICENSE",
18
17
  "v-cli.plugin.json",
19
18
  "AGENTS.md",
20
19
  "workflows/",
21
- "docs/"
20
+ "docs/",
21
+ "adapters/"
22
22
  ],
23
23
  "scripts": {
24
- "postinstall": "node scripts/sync-skill.mjs",
25
- "skill:sync": "node scripts/sync-skill.mjs",
26
24
  "test": "node scripts/test.mjs",
27
25
  "pack:guard": "node scripts/pack-guard.mjs",
28
26
  "check": "npm run docs:style && npm run docs:check && npm test && npm run pack:guard",
@@ -1,22 +1,22 @@
1
- {
2
- "principles": [
3
- "风格只定义如何绘制,跨主体复用;不能冻结参考作品的具体内容。",
4
- "具体轮廓、比例、结构、部件、姿态、数量、身份色、物理材质和光源方向由任务需求定义。",
5
- "刻画密度只控制绘制繁简,不省略任务声明的结构、部件或文字。",
6
- "高光是表现方式,不统一物体材质;笔触是绘画痕迹,不禁止需求中的鳞片、花纹或表面结构。",
7
- "色彩规则描述饱和度、色相对比和阴影偏色;主体身份色与实际光照以任务声明为准。",
8
- "背景、视角、构图、留白、裁切、文字和尺寸属于任务与资产规格。",
9
- "分类决定观察焦点,不按图片主体或文件名推断;风格参考不配置任务用途。",
10
- "区分观察、建议和未确定项,不从参考图片中的内容生成全局主题或题材白名单。",
11
- "规则精炼且一致,模型、凭据、参数和运行状态不进入风格核心。",
12
- "风格负向只排除可跨主体复用的抽象绘制语言,不冻结具体内容黑名单;明确 negative 表达不加否定前缀,条件与例外写入 when,条件规则不展开为全局禁止。",
13
- "冻结可追溯,核心不可原地覆写;旧职责版本必须重新分析和明确采用。"
14
- ],
15
- "ownership": {
16
- "core": "媒介、描绘细节、明暗方式、描边、高光画法、笔触、明度对比与色彩关系",
17
- "brief": "主体、轮廓、比例、结构、部件、姿态、动作、数量、身份色、材质与光源",
18
- "profile": "画幅、背景、视角、构图、留白、裁切、文字和投影要求",
19
- "execution": "模型、像素尺寸、候选数量、seed、水印与扩写",
20
- "edit": "明确的修改目标、保持目标和编辑底图,二者不得冲突"
21
- }
22
- }
1
+ {
2
+ "principles": [
3
+ "风格只定义如何绘制,跨主体复用;不能冻结参考作品的具体内容。",
4
+ "具体轮廓、比例、结构、部件、姿态、数量、身份色、物理材质和光源方向由任务需求定义。",
5
+ "刻画密度只控制绘制繁简,不省略任务声明的结构、部件或文字。",
6
+ "高光是表现方式,不统一物体材质;笔触是绘画痕迹,不禁止需求中的鳞片、花纹或表面结构。",
7
+ "色彩规则描述饱和度、色相对比和阴影偏色;主体身份色与实际光照以任务声明为准。",
8
+ "背景、视角、构图、留白、裁切、文字和尺寸属于任务与资产规格。",
9
+ "分类决定观察焦点,不按图片主体或文件名推断;风格参考不配置任务用途。",
10
+ "区分观察、建议和未确定项,不从参考图片中的内容生成全局主题或题材白名单。",
11
+ "规则精炼且一致,模型、凭据、参数和运行状态不进入风格核心。",
12
+ "风格负向只排除可跨主体复用的抽象绘制语言,不冻结具体内容黑名单;明确 negative 表达不加否定前缀,条件与例外写入 when,条件规则不展开为全局禁止。",
13
+ "冻结可追溯,核心不可原地覆写;旧职责版本必须重新分析和明确采用。"
14
+ ],
15
+ "ownership": {
16
+ "core": "媒介、描绘细节、明暗方式、描边、高光画法、笔触、明度对比与色彩关系",
17
+ "brief": "主体、轮廓、比例、结构、部件、姿态、动作、数量、身份色、材质与光源",
18
+ "profile": "画幅、背景、视角、构图、留白、裁切、文字和投影要求",
19
+ "execution": "模型、像素尺寸、候选数量、seed、水印与扩写",
20
+ "edit": "明确的修改目标、保持目标和编辑底图,二者不得冲突"
21
+ }
22
+ }
@@ -1,112 +1,17 @@
1
- ---
2
- name: art-workshop
3
- description: "管理项目风格、参考图、图片生成、编辑和定版。支持本地 ComfyUI 与远程图片模型。"
4
- ---
5
-
6
- 随包规范通过 `v-cli agent docs art` 读取;使用说明与数据契约通过 `v-cli art agent docs` 读取。
7
-
8
- # Vant 美术工坊 Agent 规范
9
-
10
- ## 定位
11
-
12
- 管理项目风格、参考图、图片生成、编辑和定版。支持本地 ComfyUI 与远程图片模型。
13
-
14
- ## 调用流程
15
-
16
- ```sh
17
- art-workshop config show
18
- art-workshop config validate
19
- art-workshop agent index
20
- ```
21
-
22
- 首次调用前读取本规范,使用命令帮助或插件清单核对参数和执行范围。
23
-
24
- ## 调用规范
25
-
26
- 用户既有授权与偏好持续有效;查询和预演不授权生成或采用。规范与实时参数通过 v-cli agent docs art 和 v-cli agent describe art --json 获取。
27
-
28
- ### 对象与参考
29
-
30
- 任务参考只提取 purposes 指定且未被 ignore 排除的特征。用途范围外、用户已明确覆盖的背景和绘制差异不构成阻塞;conflicts 仅列范围内不可调和要求,uncertainties 仅列影响执行的关键缺失,两者为非空字符串数组,无问题用 []。不得删除用户参考或清空报告来绕过分析;应明确参考范围后重新分析,真正的未决取舍再交用户决定。
31
-
32
- 工程对象使用 schemaVersion 2;读写前核实工程配置和当前 revision。
33
- 风格和任务都有稳定 id 与 revision。UI、聊天和 CLI 共用对象;写入、派生与清理提交预期 revision,冲突重新读取。正式风格只读,改动创建派生风格;派生不继承核心、批次、授权与对话。当前版本冻结风格派生时保留结构化规则和独立参考,报告明确标记沿用原冻结证据;不伪造新的分析。
34
- 风格静态参考只有 style、palette、rendering,只分析媒介、描绘、明暗、描边、笔触和色彩关系。具体造型、比例、结构、部件、身份色、材质与光源属于任务。任务动态参考只有 subject、composition、pose、identity-color、surface、scene-light、text;编辑底图另列。导入复制原图,不修改用户文件。未适配直接参考时拒绝,不隐式上传风格图片。
35
-
36
- ### 风格生命周期
37
-
38
- 草稿可含 rules,每条为 id/scope/strength/instruction/when,avoid 可另填 negative 字符串数组。按媒介、描边、明暗、高光、笔触、刻画、配色整理,主题不必填满。required 必须遵守、default 默认倾向、avoid 必须避免;“默认少用”使用 default,不升级为禁止。条件保留在 when。风格负向只表达跨主体复用的抽象绘制语言,不排除具体主体、部件、身份色、物体纹理、材质或资产规格。negative 直接描述被排除的视觉特征,不加否定前缀;instruction 为同一规则的阅读说明,条件和例外写入 when。无条件且明确填写的 negative 编译为独立负向表达,条件规则连同排除表达保留在正向条件段;未填写 negative 的文字约束保留原文,不机械转换。支持负向参数的模型直接传递,不支持时由适配器并入排除段,不丢弃、不截断。
39
- 已有证据的规则编辑可用 style revise --project ID --id STYLE --revision N --input FILE,输入 {rules,summary,note};这是用户修订方案,沿用未改变的参考,记录原报告和用户依据,不调用模型、不自动采用。参考或分析配置变化、未决问题、旧职责版本仍需对应处理。用户明确授权后 adopt 冻结新身份,旧核心与历史任务快照保留。
40
-
41
- style create/read/update/derive/discard 管理草稿。style analyze --dry 只读编译,不联网、启动服务或创建参考目录。实际 analyze 创建 taskId 与独立参考证据;task status/wait/cancel 控制执行,recover 查原登记,resume 仅按已记录的上游身份恢复查询与取回,不重新提交。
42
- 报告绑定源配置、参考与模型。更新配置保留报告并标记需复核,旧证据不变。报告 recommendation.rules 是精炼独立成稿,规则含主题、强度和适用条件,不包含迭代描述。issues 仅列需用户取舍的矛盾,notes 保留不阻塞采用的证据局限。style resolve --input {issueId,optionId,note} 记录明确选择并修订有效方案,不重新分析;以 style read 的 review.ready 判断采用条件。复核沿用证据与决定,新证据才重新打开问题。style adopt 校验来源匹配和所有问题已决定,用户采用后冻结。采用中断通过 style recover 完成已授权事务,不能重新冻结另一份核心。
43
- 退出风格配置先继续编辑、保存草稿或放弃;分析停止未确认时不能清理。
44
-
45
- ### 计划与执行
46
-
47
- 动态需求自由文本不设字数上限:意图、外观、颜色、动作、效果与关系、场景说明、编辑指令和可读特征均完整保存与编译,不为通过校验删减或截断。必填项仍检查非空、类型和占位符;标识符、模型名称、采样器等结构字段保留各自契约。
48
-
49
- 风格与任务用 config.analysis{provider,model} 保存独立视觉分析实例;任务另用 config.generation{backend,remote?,options?} 保存生成后端,remote 为 {provider,model}。本地采样参数通过任务 generation.options 保存:steps 为 1~10000 整数,cfg 为 0~100 数值,sampler/scheduler 为 ComfyUI 支持的名称。新任务的本地推荐值为 steps=25、cfg=3、sampler=euler、scheduler=simple;内置工作流采用同一默认值,确保普通 CFG 负向分支参与引导。显式配置(含 cfg=0/1)保留,旧批次不改写。省略沿用后端或工作流默认值,远程后端不接受这些参数。使用 job update(v-cli art.job-update)更新任务后重新 plan,核对 backend.options 和 dry 请求的采样节点;不要通过独立 CLI config.json 或宿主管理的工程 settings.json 调整当前任务。聊天模型不改写执行选择。CLI plan 优先使用显式 --backend,其次任务 backend,再按独立工具的本地配置选择;任务绑定后端时使用其真实模型,不能被旧 execution.model 覆盖。宿主按实例注入凭据,不在对象或预案写入密钥;修改选择使原方案失效。
50
-
51
- 先读取实际 job,再 generate/edit plan 和 run --plan --dry,展示有效核心、设计尺寸、预留缩放、请求与实际像素、模型后端、候选数量和编辑底图。后端尺寸由工具统一解析,超限或未对齐选最近合法尺寸,保留设计基准并明确实际值;不承诺显存或自动缩放导出。
52
- 授权覆盖方案后使用 run --background;前台同样创建执行身份。配置、核心、规格、参考、底图和后端变化拒绝失效方案,重新编译。重启查 taskId,不重复提交。不自动换模型或重跑成功项。
53
- 每个任务只能有一个未停止确认的执行;编辑、派生、归档、恢复与运行共用状态检查。切页面不取消。
54
- job discard 归档已停止的任务,草稿、待定版和已定版均可归档。按 revision 将任务标记为 discarded(归档存储状态),保留配置、参考、私有底图、运行、输出、收藏和定版历史;活跃列表、收藏及作品暂不显示。job restore 按同一身份和当前 revision 恢复到活跃列表,收藏与作品重新显示,不重新生成。归档与恢复均检查停止确认和版本,重复操作幂等;恢复后原方案需按当前版本重新编译。风格 discard 仍为草稿放弃,不参与任务归档。
55
-
56
- ### 取消、异常和关闭
57
-
58
- 本地 ComfyUI 按资产及采样序号持久化 prompt ID。工作进程丢失后使用 task resume 或 Vant 原批次恢复入口,沿用原身份查询与取回,不重新上传或提交生图;未提交项不补发。Windows 心跳写入暂时失败记录诊断并重试,不能导致定时器异常退出;关键状态写入仍严格校验。
59
-
60
- 任务状态与停止证据分开。queued/running/cancelling 仍占用资源;unknown 或 stopConfirmed=false 保留资源。failed/cancelled 也不能单凭状态释放资源;dispatching/accepted 远程回执尚未结清时继续占用。工作进程丢失标记 unknown,不推测停止。
61
- task cancel 只取消指定运行,保留服务。生成任务远程取消只停止本地客户端,上游停止未知如实报告,不允许清理。只读分析有 finishedAt、已知终态且工作进程已退出,无生成计划与回执时释放本地占用;云端计算与计费停止未知独立保留,不自动重发。没有完成证据的进程丢失仍保持 unknown。shutdown 阻止提交、停止关联任务、核验共享队列和进程身份后关闭本地服务,不清空共享队列;有其他任务或停止未确认时保留服务。不得广泛杀所有 Python。
62
-
63
- ### 生成与定版
64
-
65
- 透明背景使用 `{type:"transparent"}`:生成任务设置 composition.background,编辑任务设置 changes 中 background 的 value。预案记录 PNG 输出处理版本并参与哈希;含完全透明区域的原生 alpha 保留,接近不透明的 alpha 噪声不视为透明背景。否则从边缘核实约定洋红底色,容许模型色偏,仅处理与外边界连通的底色及混合边缘。原图保留,候选使用处理后的 PNG;缺少合格背景或可见主体则报错,不伪称透明成功。纯色去背景可能影响与外部底色连通的同色细节,不能承诺任意半透明材质的抠图质量。
66
-
67
- 编辑 target 是范围名称,允许 outline 等具体范围;同一范围可修改局部并保留其他特征,不能仅按标签重叠判矛盾。配置和预案仍校验字段、引用、版本及核心风格归属。
68
-
69
- 只有生成与定版两个产品阶段。check 验证计划、执行身份、文件哈希和完成事实;不要求人工 content/style/asset 评分。candidate finalize 按资产选定候选,并把图片复制到美术仓库 VantArtForge。导出名称可空,空名称使用 vant-gen-任务-资产-批次。同一候选且同一导出名重复操作幂等;替换已有定版需要明确 replace,保留历史。导出文件名不能包含路径。
70
- 候选 editable 与 accepted 分开:已停止批次中保留的有效图片可作为编辑底图,输出处理失败不阻止继续编辑;已记录的哈希不匹配、文件缺失或已删除则拒绝。job from-candidate 验证图片可解码后复制为独立编辑草稿的私有底图并记录来源,不改变原批次失败事实,也不授权定版或启动生成。
71
- candidate favorite 使用 --value true/false 收藏或取消收藏,candidate favorites 查看工程收藏。收藏记录独立保存在工程 favorites.json,绑定源任务、批次和图片身份,不修改需求版本、执行或定版状态;可收藏有效的失败保留图。列表隐藏已删除、丢失或所属任务已归档的图片,源任务改名即时反映。
72
- candidate delete 先确认影响,拒绝运行中或被计划/底图引用的候选;先记删除事实,清理所属文件,并取消关联定版。定版不自动导入游戏或提交 Git。
73
-
74
- ### 验证和技能
75
-
76
- 本地先 config validate、doctor、plan/dry,再按授权真实生成与编辑。配置有效、服务可连接与真实出图是不同证据。远程核对实际认证和模型入口;凭证不得写入项目、计划、日志或命令行。
77
- 随包 skills/art-workshop 是技能源;通过 agent init 或 skill:sync 同步,保留项目扩展。查询和预演不自动同步。源码/单测/mock 不能代替真实模型、图像、桌面与安装验证。
78
-
79
- 任务动态参考先 `job analyze`,缺失、过期或职责越界的观察不能进入生成预案。分析与生成共用任务占用与停止确认。启动回执丢失只能 `task recover --project P --operation ID` 查询唯一原登记;没有唯一证据时保持未知,不能重发生成。
80
-
81
- 模型、参数及支持状态只在 art 工具 model-catalog/model-registry 内维护,界面与 v-cli 不复制型号判断。远程图片由已注册协议适配器直接调用;视觉分析连接独立,未注入时使用百炼 CLI。Token Plan 是渠道,DashScope 是协议,不跨站点回退凭据。
82
-
83
- 远端上游身份持久化后才能轮询。`task resume TASK` 只恢复原身份查询与取回,不重发生成;无回执或仍处于 dispatching 的提交保持未知。界面与保存共用 modelEligibility,展示字段不进入执行契约。
84
-
85
- 风格报告和核心使用 schemaVersion=3,只表达绘制语言,不限定主体题材。低刻画密度不删任务结构,干净笔触不禁止物体纹理,高光画法不统一物理材质。
86
-
87
- 任务草稿允许内容尚未完成,但拒绝编译器不支持的字段。生成任务的字段正本为 lib/task-contract.mjs;effect 使用 id/kind/target/color/relation/count,不支持 description。先读当前对象,完整保留未修改字段,按当前 revision 保存;保存成功后仍需编译预案,不能声称已生成图片。任务编译错误依据执行回执修正,不猜测风格或尺寸问题。
88
-
89
- 任务参考可通过 reference import --item-id <对象标识> 绑定单个出图对象;未绑定的参考为任务共用。生成与编辑只采纳共用参考和当前对象参考的观察。reference update 的 itemId 可改绑对象,null 表示任务共用。
90
-
91
- `v-cli capability coverage --json` 核对结构化调用覆盖。参考导入的 `--item-id` 指定当前任务出图对象,省略表示任务共用;工具校验对象身份。
92
-
93
- ### 本地环境部署
94
-
95
- 使用 environment guide 获取部署指南与契约,environment inspect 读取机器环境。Pi 通过基础工具和动态工作流完成安装、下载、修正与采样;environment verify 独立校验文件、服务和节点,environment register 验收后登记。任务授权、进程、互斥与恢复交由 Harness。不得把模型回复或服务连通当作真实出图。unregister 仅解除登记,不删除模型或停止外部服务。按 --guide 选择随包方案,模型事实和启动参数只由 art 维护。
96
-
97
- ### 共享冻结风格
98
-
99
- 用户要求共享时使用 style export --project ID --id STYLE --out FILE.style.json,收集冻结核心和必要参考,不复制运行记录或设置。style sources --input DIRS.json 只读列出多个来源,单个来源不可用时报告并继续,重复身份内容冲突按来源明确选择。style import --project TARGET --file FILE.style.json 导入固定快照,保留来源身份、版本及核心哈希;不重新分析、采用或随来源更新。导入的冻结对象只读,改动使用 style derive。输出文件不覆盖已有版本。
100
-
101
-
102
- ## 结果验证
103
-
104
- 核对原始错误、任务身份、停止状态及实际产物。只报告已经完成的验证,模拟测试与真实执行分别说明。
105
-
106
- ## 参考资料
107
-
108
- 使用说明 · 文档规范 · v-cli.plugin.json
109
-
110
- ## 许可与版权
111
-
112
- MIT。Copyright © 2026 Vant。
1
+ ---
2
+ name: art-workshop
3
+ description: "处理美术讨论、风格与任务表达、会话生图和图片编辑;根据意图与引用选择会话或项目管线。"
4
+ ---
5
+
6
+ # 美术工坊
7
+
8
+ 判断本轮是讨论、生成还是编辑,再确定归属会话或项目任务。信息充分时直接使用对应结构化工具,不把普通讨论升级为生成。当前消息明确指定的对象和图片优先于历史推断。
9
+
10
+ 以用户意图为主线,让表达更清楚、专业、便于执行,允许贴合原意的适度补充。留意补充是否改变了用户的方向、程度或选择空间,尤其不要将倾向升级成硬性禁令。看图分析可以提炼可见特征;影响不大的合理细化直接处理,实质性的新设计取舍再提出建议或询问。
11
+
12
+ - 整理或回填美术表述前读取 [表达规范](references/expression.md),本会话已掌握时直接沿用。需要 Getty 核实时,先从中文意图提炼英文专业词,在一个批次中通过 art_getty 查询,再按原始上下文校验候选;失败或无匹配保留原表达,不阻塞其他内容,不重试或另找调用路径。
13
+ - 参考图风格讨论、分析并填写风格草稿,读取 [风格讨论与回填](references/style-discussion.md)。
14
+ - 会话探索、新图及修改上一轮产物,读取 [会话管线](references/conversation.md),使用 art_conversation。
15
+ - 已有项目任务、风格冻结和正式资产交付,读取 [项目管线](references/project.md),使用 art_operation。
16
+
17
+ 同一请求只提交一次;重复调用复用请求身份。未知状态仅查询原运行,禁止更换身份重投。状态查询按工具返回的 wait/状态约束进行;到达等待上限就结束本轮并保留可恢复身份,不用修改需求或新建任务绕过失败。只有用户明确修改目标或请求新一轮生成时才创建新请求。
@@ -0,0 +1,11 @@
1
+ # 会话美术管线
2
+
3
+ 使用 art_conversation describe 获取当前输入契约。只讨论时自然答复,不执行生成。
4
+
5
+ 一次 generate 或 edit 请求绑定 requestId;相同 requestId 重复调用只返回原运行,不重发。已有产物通过 attachmentId 指定;编辑必须明确底图,引用可以分别指定主体、配色、构图、风格等用途,不把全部会话图片自动作为参考。读取像素后再解释,不能看图时使用已配置的视觉分析能力或说明限制。
6
+
7
+ 生成和编辑使用 prompt、引用及已有执行设置,不创建业务 job 或冻结风格。未指定主题规格时使用会话默认值,不能伪造资产要求。只补问实际影响行动的歧义;已授权的普通生成不重复要求确认,宿主执行策略仍生效。
8
+
9
+ generate/edit 返回 runId 后只查询该运行;status 每次只读取一次状态,不进行模型轮询循环。完成后由宿主发布真实图片附件,失败如实说明,unknown 只查询或恢复原运行。等待达到上限时结束本轮并保留句柄;不自动重跑成功项,不换模型重投,不将取消变成新请求。
10
+
11
+ 用户对结果提出新修改时,使用明确底图提交新一轮,requestId 仍由宿主绑定该条用户消息。用户要求转为项目任务时调用 promote,保留原图片及来源,不重新生图、不自动定版。
@@ -0,0 +1,27 @@
1
+ # 美术表达规范
2
+
3
+ 讨论、风格分析、报告和任务配置中的美术表达采用以下默认顺序;简单修改可以合并步骤,没有专业歧义或核实需要时跳过检索,不将步骤变成固定工作流或逐项确认关卡。只优化前置表述,不为验证措辞启动分析、生图或出图评审。
4
+
5
+ ## 适度整理与补充
6
+
7
+ 目标是让美术同学更容易理解和执行,不要求逐字改写或零扩写。可以调整次序、合并重复、使用专业表达,也可以补充与原意一致的自然衔接和合理执行细节;是否合适主要看有没有改变用户想要的结果。
8
+
9
+ - 保持原有方向、程度、条件和例外。“少用”不宜变成全面禁止,“可以有”不宜变成必须出现;局部调整也不宜扩大到整幅或所有资产。这些是实质性变化,与普通措辞补充区别处理。
10
+ - 看图分析可以提炼有图像依据的媒介观感、线条、笔触、明暗和色彩关系,并适度转化为可用的风格描述。对推测性的工艺、媒介来源或通用性判断用恰当的倾向表达,不因单张图没有某种表现就认为以后必须禁止。
11
+ - Getty 帮助核实概念,不代替美术判断。结合上下文解释即可,不必将定义未提到的内容判为不允许,也不为术语分类强行拆开可以并存的要求。
12
+ - 少量、顺理成章的补充可直接融入,无需逐项标建议或请求确认。明显改变画面方向、增加硬性限制或存在多种差异较大的解释时,再简短提出建议或请用户选择,其余明确内容继续处理。
13
+
14
+ 回填前快速看一遍有没有偏离原意、遗漏保留项或无意升级强度;必要时局部修正即可。不要为每个新增形容词建立证明或确认关卡,也不因细节未穷尽而反复追问。原配置与工具默认值继续沿用,避免把本轮讨论扩大成全面重写。
15
+
16
+ ## 整理与保存
17
+
18
+ 1. 理解意图与主题归类:先明确对象、属性、调整方向、程度、条件及保留要求。区分跨主体复用的绘制语言与当前任务的主体、结构、材质、光照、构图和交付约束,按相关主题组织,不强制填满分类,不为分类补造需求。
19
+ 2. 初步整理与语义去重:统一同一对象的称呼,合并对象、含义和适用条件均一致的重复要求;程度、条件或对象不同的内容分别保留。含义不确定时保留原表达和上下文,暂不强行合并或替换,避免先精简掉消歧依据。
20
+ 3. 按需专业对齐:发现专业概念歧义或需要核实时,先从中文原意、作用对象及条件中提炼简短的英文专业检索词,再通过实际可用的 Getty 或项目表达库召回概念。不是逐字翻译整段描述,也不将英译当成已确认结论;有多个合理含义时在同一批次查询,不在结果不理想后反复换词。原始中文及约束保留在 context,候选返回后结合类别、概念说明和原始上下文判断,不只按首条或分数采用。Vant 使用 art_getty 结构化入口,不拼 Python、脚本或请求文件路径。缓存由查询工具管理,仅复用完整检索词及影响结果的全部参数完全一致的请求,不做语义近似缓存;不伪造概念 ID、结果或工具能力。无需引入 OpenRefine 运行依赖。
21
+ 4. 精炼表述与整体校验:采用明确且符合原意的概念后,删去空泛修饰与重复说明,形成独立完整的描述;保留对象、程度、条件、例外和 required/default/avoid 的原有强度,不设机械字数限制。核对前后术语及要求一致,未遗漏约束、增加未经支持的含义或混淆风格与任务职责。发现问题做局部修正,不自动回到起点反复检索或改写。
22
+ 5. 回填并结束:明确且校验通过的修改在用户当前编辑授权内自动回填,无需逐项确认;读取当前对象及 revision,保留未修改配置,按工具契约保存并核实返回结果。筛选后仍有多个合理解释时,按匹配程度排序,通过宿主现有决策入口展示候选含义、匹配依据、差异和拟回填内容,标明推荐项并允许保留原表达或自行修改;未决字段保留原值,其余明确修改继续处理。无匹配、查询能力不可用、服务失败或语义校验未通过时,保留受影响的原表达,简短说明局限并结束本次对齐,不强行绑定概念或自行重试循环。配置保存失败须如实报告,不声称已回填;技术契约校验仍按原规则执行。
23
+
24
+ Getty 调用前按需读取 `references/getty.md`。Vant 的 art_getty 由宿主定位受管包中的 `scripts/getty.py` 和共享 Python,通过标准输入输出交换 JSON;模型不用寻找或创建脚本。其他宿主只使用其明确提供的执行入口与解释器,缺少能力时说明失败,不猜路径、搜索系统 Python 或改用临时脚本。适配器负责 AAT 查询、详情、精确缓存和错误分类,模型负责词语提炼和语义判断。上游 serviceScore 只是检索排序分数,serviceMatch 不等于语义通过;失败即保留原文并结束当前检索,不用网页查询冒充已完成 Getty 核实。
25
+
26
+
27
+ 每轮对齐只做一次有界整理与查询批次;查询候选可含原词和有依据的候选译名,使用不同 query ID 保留来源。一次局部修正后仍有歧义就交决策卡或保留原文并结束,不为提高检索分数反复换词。用户选择候选后只处理该未决项,不重新启动整套流程。
@@ -0,0 +1,76 @@
1
+ # Getty AAT 查询契约
2
+
3
+ ## 自动处理顺序
4
+
5
+ 1. 从原始中文描述及作用对象中提炼简短英文专业检索词,优先术语而非整段直译。例如“晕涂法”可检索 sfumato;“版画感、双色、可见刻刀痕”可在同一批次检索 woodcut、linocut 等有依据的候选含义,不直接用 print feeling。术语不确定时保留为候选,不先确定画法。
6
+ 2. 原文及约束保留在每项 context.original、target 等上下文中;英文词只用于召回,不替换用户原文。一次准备好相关候选,最多 10 项,不向用户逐项确认英译。
7
+ 3. Vant 调用 art_getty,参数为下文的查询 JSON。宿主从受管工具包定位脚本,使用共享 Python,通过 stdin 传入请求。模型直接使用结构化入口。
8
+ 4. 用返回的类别、说明、别名与原始上下文校验候选。英文词也可能召回无关概念;中文候选、第一名、serviceScore 或 serviceMatch 均不能代替语义判断。全部不合适时保留原表达,不为了得到命中继续扩词查询。
9
+ 5. 本次核实完成或失败后继续主任务,不重试、更换路径或新增确认关卡。多候选本身不要求用户确认;真正影响主任务的设计取舍沿用已有交互,不另加 Getty 审批。
10
+
11
+ ## Vant 执行结果
12
+
13
+ art_getty 的主状态只有 succeeded 或 failed,stop=true 表示本轮查询已结束。同一用户轮次只有一个查询批次,重复调用或改变检索词会复用原结果,不再次执行。新的用户需求可以开始新一轮查询。
14
+
15
+ - succeeded:适配器完整成功。data.status 为 candidates 或 no_match;零匹配是有效查询结果。
16
+ - failed:读取 error.code、stage、message。资源或解释器问题是明确的前置失败;执行、网络、响应或详情错误也属于失败。runnerAttempted 等执行信息区分是否已尝试适配器,不把前置失败说成已经访问 Getty。
17
+ - 核心详情(首选名、别名、概念说明)获取失败仍是 failed,data 可保留已取得的候选,不宣称概念说明已核实。层级单独获取,失败不撤销核心详情成功;查看 data.enrichment.hierarchy 的状态和错误。可继续用已取得的定义校验原意,不依赖缺失的层级作结论,也不重试。
18
+ - request 保留本批次的英文词与中文上下文。查询失败后不再用 shell、其他词或网页替代本次 Getty 核实;其余清楚内容继续处理。
19
+
20
+ 缺少工具资源时由宿主报 TOOL_RESOURCE_MISSING,缺少共享 Python 报 PYTHON_UNAVAILABLE。宿主仅执行受管工具包内的脚本。
21
+
22
+ ## 适配器入口
23
+
24
+ `scripts/getty.py` 使用 Python 3.9+ 标准库,接收 JSON 并输出 JSON。宿主负责提供解释器与受管资源。脚本只查询,不修改任务或风格配置。
25
+
26
+ ```sh
27
+ python <SKILL_DIR>/scripts/getty.py --input <REQUEST.json>
28
+ ```
29
+
30
+ ## 输入
31
+
32
+ `--input` 接收 UTF-8 JSON 文件,省略或为 `-` 时从标准输入读取。一次请求包含 1~10 个查询,每项最多返回 limit 个候选,limit 默认 5、范围 1~10;更多查询分批提交。不截断用户原始美术描述。
33
+
34
+ ```json
35
+ {
36
+ "queries": [
37
+ {
38
+ "id": "medium",
39
+ "query": "watercolors",
40
+ "context": {"original": "采用水彩绘制语言", "target": "整体绘制风格"},
41
+ "properties": {}
42
+ }
43
+ ],
44
+ "limit": 5
45
+ }
46
+ ```
47
+
48
+ `id` 可省略,由脚本生成批次内标识;显式 ID 必须唯一。`query` 原样传递,不自动翻译、改大小写、裁剪空格或扩展同义词。`context.original` 为必填原文,`context.target` 可指定作用对象;context 只回显到结果,不发送 Getty,也不改变上游查询。可选 `properties` 支持 `note`(概念说明)、`broaderExt`(上位概念)、`label`(其他名称),值为非空字符串,参与真实 Getty 查询与缓存键。仅在确有依据时填写,不为提高分数编造属性。
49
+
50
+ `properties` 是缩小检索范围的属性约束,不是指定返回字段。首选名、别名、说明与层级会自动取回;只想取得概念说明时保持 `properties` 为空,不填写“返回说明”“want scope note”等指令。
51
+
52
+ ## 输出与处理
53
+
54
+ 独立脚本标准输出为单个 UTF-8 JSON 对象,`schema` 固定为 `art-workshop/getty-v1`。正常检索与无匹配退出 0;输入、检索或核心详情获取失败退出 1。层级作为补充信息,失败时保留警告,核心详情成功仍退出 0。Vant 将此协议放在 data 中,并用上文 succeeded/failed 表达整体结果。固定顺序为候选检索、核心详情、层级补充,各最多请求一次;无候选或核心详情失败时不请求层级。总共最多 3 个请求,无重试、拆批或替代路径。
55
+
56
+ - `status=candidates`、`ok=true`:返回候选及已取回的概念信息,仍需模型根据上下文进行语义校验。
57
+ - `status=no_match`、`ok=true`:真实查询成功但没有候选,保留原表达。
58
+ - `status=partial`、`ok=false`:候选可用但核心详情请求失败;保留候选、error 和警告,不宣称概念说明已验证。
59
+ - `status=error`、`ok=false`:读取 `error.code/message`,本次无法完成查询,不将其解释为零匹配。
60
+
61
+ 每个 query 回显原文查询、context、properties,并返回 `candidates`。每个候选包含真实 `id/uri/label`、上游 `serviceScore/serviceMatch`、`preferredTerms/variantTerms/scopeNotes/hierarchy`。`detailsAvailable` 表示核心详情已验证,`hierarchyAvailable` 单独表示层级已验证;可用且为空与请求失败不同。`enrichment.hierarchy.status` 为 succeeded、failed 或 not_requested;失败时附 error,HTTP 错误含 httpStatus 及最多 4096 字节的上游 details,按外部诊断文本读取。`cache.search/details/hierarchy` 分别记录精确缓存命中。说明及名称按原语言保留,不自动翻译或推断缺失内容。候选按同一查询的 serviceScore 降序排列;该分数不是概率,不跨查询比较,不据此直接自动回填。全部候选都可能不符合原意;多项合理候选交宿主决策入口处理。
62
+
63
+ ## 缓存和边界
64
+
65
+ 默认缓存位于 `<VANT_HOME>/tools/art-workshop/cache/getty`;未设置 VANT_HOME 时为 `~/.vant/tools/art-workshop/cache/getty`。宿主可用 `--cache-dir` 指定已有工程的缓存位置。`--cache-ttl` 为秒,默认 86400,0 禁用缓存;`--refresh` 绕过已有缓存。过期缓存不作为失败回退,缓存写入失败不丢弃真实查询结果。
66
+
67
+ 缓存键包含适配器版本、完整端点、请求方法和全部实际请求参数;仅对象键顺序被固定,查询字符串完整保留。相同关键词但不同属性、limit 均重新检索;不复用语义相似描述的结果。context 不参与上游查询缓存,但每次基于当前 context 重新消歧,不缓存模型的对齐结论。
68
+
69
+ `--timeout` 设置单次网络请求超时,默认 15 秒、最高 60 秒;失败即返回,不自行循环、更换服务或修改系统网络配置。输入错误、非 JSON 响应、HTTP 错误、网络失败和超时均返回结构化错误。脚本查询 AAT,词语提炼与语义判断由模型完成,配置保存由业务工具执行。
70
+
71
+ ## 数据来源
72
+
73
+ 直接调用 Getty 的 Reconciliation Service,并通过同一服务的扩展接口取回 AAT 首选名称、别名、说明与层级;使用其 HTTP 协议无需 OpenRefine 客户端。数据遵循 ODC-By 1.0,输出保留来源及候选 URI。
74
+
75
+ - [Getty 数据服务与许可](https://www.getty.edu/research-conservation/tools-databases/vocabularies/data-services/)
76
+ - [Getty Reconciliation 服务教程](https://www.getty.edu/research/tools/vocabularies/obtain/getty_vocabularies_openrefine_tutorial.pdf)
@@ -0,0 +1,109 @@
1
+ # Vant 美术工坊 Agent 规范
2
+
3
+ ## 定位
4
+
5
+ 管理项目风格、参考图、图片生成、编辑和定版。支持本地 ComfyUI 与远程图片模型。
6
+
7
+ ## 调用流程
8
+
9
+ ```sh
10
+ art-workshop config show
11
+ art-workshop config validate
12
+ art-workshop agent index
13
+ ```
14
+
15
+ 首次调用前读取本规范,使用命令帮助或插件清单核对参数和执行范围。
16
+
17
+ ## 调用规范
18
+
19
+ 用户既有授权与偏好持续有效;查询和预演不授权生成或采用。规范与实时参数通过 v-cli agent docs art 和 v-cli agent describe art --json 获取。
20
+
21
+ ### 对象与参考
22
+
23
+ 任务参考只提取 purposes 指定且未被 ignore 排除的特征。用途范围外、用户已明确覆盖的背景和绘制差异不构成阻塞;conflicts 仅列范围内不可调和要求,uncertainties 仅列影响执行的关键缺失,两者为非空字符串数组,无问题用 []。不得删除用户参考或清空报告来绕过分析;应明确参考范围后重新分析,真正的未决取舍再交用户决定。
24
+
25
+ 工程对象使用 schemaVersion 2;读写前核实工程配置和当前 revision。
26
+ 风格和任务都有稳定 id 与 revision。UI、聊天和 CLI 共用对象;写入、派生与清理提交预期 revision,冲突重新读取。正式风格只读,改动创建派生风格;派生不继承核心、批次、授权与对话。冻结风格派生保留结构化规则和独立参考,报告标明引用的冻结证据。
27
+ 风格静态参考只有 style、palette、rendering,只分析媒介、描绘、明暗、描边、笔触和色彩关系。具体造型、比例、结构、部件、身份色、材质与光源属于任务。任务动态参考只有 subject、composition、pose、identity-color、surface、scene-light、text;编辑底图另列。导入复制原图,不修改用户文件。未适配直接参考时拒绝,不隐式上传风格图片。
28
+
29
+ ### 风格生命周期
30
+
31
+ 草稿可含 rules,每条为 id/scope/strength/instruction/when,avoid 可另填 negative 字符串数组。按媒介、描边、明暗、高光、笔触、刻画、配色整理,主题不必填满。required 必须遵守、default 默认倾向、avoid 必须避免;“默认少用”使用 default,不升级为禁止。条件保留在 when。风格负向只表达跨主体复用的抽象绘制语言,不排除具体主体、部件、身份色、物体纹理、材质或资产规格。negative 直接描述被排除的视觉特征,不加否定前缀;instruction 为同一规则的阅读说明,条件和例外写入 when。无条件且明确填写的 negative 编译为独立负向表达,条件规则连同排除表达保留在正向条件段;未填写 negative 的文字约束保留原文,不机械转换。支持负向参数的模型直接传递,不支持时由适配器并入排除段,不丢弃、不截断。
32
+ 已有证据的规则编辑可用 style revise --project ID --id STYLE --revision N --input FILE,输入 {rules,summary,note};这是用户修订方案,沿用未改变的参考,记录原报告和用户依据,不调用模型、不自动采用。参考或分析配置变化时需分析,未决问题按报告处理。用户明确授权后 adopt 冻结新身份,保留源核心与任务快照。
33
+
34
+ style create/read/update/derive/discard 管理草稿。style analyze --dry 只读编译,不联网、启动服务或创建参考目录。实际 analyze 创建 taskId 与独立参考证据;task status/wait/cancel 控制执行,recover 查原登记,resume 仅按已记录的上游身份恢复查询与取回,不重新提交。
35
+ 报告绑定源配置、参考与模型。更新配置保留报告并标记需复核,源证据保持不变。报告 recommendation.rules 是精炼独立成稿,规则明确主题、强度和适用条件。issues 仅列需用户取舍的矛盾,notes 保留不阻塞采用的证据局限。style resolve --input {issueId,optionId,note} 记录明确选择并修订有效方案,不重新分析;以 style read 的 review.ready 判断采用条件。复核沿用证据与决定,新证据才重新打开问题。style adopt 校验来源匹配和所有问题已决定,用户采用后冻结。采用中断通过 style recover 完成已授权事务,不能重新冻结另一份核心。
36
+ 退出风格配置先继续编辑、保存草稿或放弃;分析停止未确认时不能清理。
37
+
38
+ ### 计划与执行
39
+
40
+ 动态需求自由文本不设字数上限:意图、外观、颜色、动作、效果与关系、场景说明、编辑指令和可读特征均完整保存与编译,不为通过校验删减或截断。必填项仍检查非空、类型和占位符;标识符、模型名称、采样器等结构字段保留各自契约。
41
+
42
+ 风格与任务用 config.analysis{provider,model} 保存独立视觉分析实例;任务另用 config.generation{backend,remote?,options?} 保存生成后端,remote 为 {provider,model}。本地采样参数通过任务 generation.options 保存:steps 为 1~10000 整数,cfg 为 0~100 数值,sampler/scheduler 为 ComfyUI 支持的名称。新任务的本地推荐值为 steps=25、cfg=3、sampler=euler、scheduler=simple;内置工作流采用同一默认值,确保普通 CFG 负向分支参与引导。显式配置(含 cfg=0/1)保留,采样参数随批次保存。省略沿用后端或工作流默认值,远程后端不接受这些参数。使用 job update(v-cli art.job-update)更新任务后重新 plan,核对 backend.options 和 dry 请求的采样节点;不要通过独立 CLI config.json 或宿主管理的工程 settings.json 调整当前任务。聊天模型不改写执行选择。CLI plan 优先使用显式 --backend,其次任务 backend,再按独立工具的本地配置选择;任务绑定后端时使用该后端的模型。宿主按实例注入凭据,不在对象或预案写入密钥;修改选择使原方案失效。
43
+
44
+ 先读取实际 job,再 generate/edit plan 和 run --plan --dry,展示有效核心、设计尺寸、预留缩放、请求与实际像素、模型后端、候选数量和编辑底图。后端尺寸由工具统一解析,超限或未对齐选最近合法尺寸,保留设计基准并明确实际值;不承诺显存或自动缩放导出。
45
+ 授权覆盖方案后使用 run --background;前台同样创建执行身份。配置、核心、规格、参考、底图和后端变化拒绝失效方案,重新编译。重启查 taskId,不重复提交。不自动换模型或重跑成功项。
46
+ 每个任务只能有一个未停止确认的执行;编辑、派生、归档、恢复与运行共用状态检查。切页面不取消。
47
+ job discard 归档已停止的任务,草稿、待定版和已定版均可归档。按 revision 将任务标记为 discarded(归档存储状态),保留配置、参考、私有底图、运行、输出、收藏和定版历史;活跃列表、收藏及作品暂不显示。job restore 按同一身份和当前 revision 恢复到活跃列表,收藏与作品重新显示,不重新生成。归档与恢复均检查停止确认和版本,重复操作幂等;恢复后重新编译预案。风格 discard 仍为草稿放弃,不参与任务归档。
48
+
49
+ ### 取消、异常和关闭
50
+
51
+ 本地 ComfyUI 按资产及采样序号持久化 prompt ID。工作进程丢失后使用 task resume 或 Vant 原批次恢复入口,沿用原身份查询与取回,不重新上传或提交生图;未提交项不补发。Windows 心跳写入暂时失败记录诊断并重试,不能导致定时器异常退出;关键状态写入仍严格校验。
52
+
53
+ 任务状态与停止证据分开。queued/running/cancelling 仍占用资源;unknown 或 stopConfirmed=false 保留资源。failed/cancelled 也不能单凭状态释放资源;dispatching/accepted 远程回执尚未结清时继续占用。工作进程丢失标记 unknown,不推测停止。
54
+ task cancel 只取消指定运行,保留服务。生成任务远程取消只停止本地客户端,上游停止未知如实报告,不允许清理。只读分析有 finishedAt、已知终态且工作进程已退出,无生成计划与回执时释放本地占用;云端计算与计费停止未知独立保留,不自动重发。没有完成证据的进程丢失仍保持 unknown。shutdown 阻止提交、停止关联任务、核验共享队列和进程身份后关闭本地服务,不清空共享队列;有其他任务或停止未确认时保留服务。不得广泛杀所有 Python。
55
+
56
+ ### 生成与定版
57
+
58
+ 透明背景使用 `{type:"transparent"}`:生成任务设置 composition.background,编辑任务设置 changes 中 background 的 value。预案记录 PNG 输出处理版本并参与哈希;含完全透明区域的原生 alpha 保留,接近不透明的 alpha 噪声不视为透明背景。否则从边缘核实约定洋红底色,容许模型色偏,仅处理与外边界连通的底色及混合边缘。原图保留,候选使用处理后的 PNG;缺少合格背景或可见主体则报错,不伪称透明成功。纯色去背景可能影响与外部底色连通的同色细节,不能承诺任意半透明材质的抠图质量。
59
+
60
+ 编辑 target 是范围名称,允许 outline 等具体范围;同一范围可修改局部并保留其他特征,不能仅按标签重叠判矛盾。配置和预案仍校验字段、引用、版本及核心风格归属。
61
+
62
+ 只有生成与定版两个产品阶段。check 验证计划、执行身份、文件哈希和完成事实;不要求人工 content/style/asset 评分。candidate finalize 按资产选定候选,并把图片复制到美术仓库 VantArtForge。导出名称可空,空名称使用 vant-gen-任务-资产-批次。同一候选且同一导出名重复操作幂等;替换已有定版需要明确 replace,保留历史。导出文件名不能包含路径。
63
+ 候选 editable 与 accepted 分开:已停止批次中保留的有效图片可作为编辑底图,输出处理失败不阻止继续编辑;已记录的哈希不匹配、文件缺失或已删除则拒绝。job from-candidate 验证图片可解码后复制为独立编辑草稿的私有底图并记录来源,不改变原批次失败事实,也不授权定版或启动生成。
64
+ candidate favorite 使用 --value true/false 收藏或取消收藏,candidate favorites 查看工程收藏。收藏记录独立保存在工程 favorites.json,绑定源任务、批次和图片身份,不修改需求版本、执行或定版状态;可收藏有效的失败保留图。列表隐藏已删除、丢失或所属任务已归档的图片,源任务改名即时反映。
65
+ candidate delete 先确认影响,拒绝运行中或被计划/底图引用的候选;先记删除事实,清理所属文件,并取消关联定版。定版不自动导入游戏或提交 Git。
66
+
67
+ ### 验证和技能
68
+
69
+ 本地先 config validate、doctor、plan/dry,再按授权真实生成与编辑。配置有效、服务可连接与真实出图是不同证据。远程核对实际认证和模型入口;凭证不得写入项目、计划、日志或命令行。
70
+ 技能由插件清单声明并随包发布,由 Vant 统一分发;不扫描或自动同步其他宿主目录。源码/单测/mock 不能代替真实模型、图像、桌面与安装验证。
71
+
72
+ 任务动态参考先 `job analyze`,缺失、过期或职责越界的观察不能进入生成预案。分析与生成共用任务占用与停止确认。启动回执丢失只能 `task recover --project P --operation ID` 查询唯一原登记;没有唯一证据时保持未知,不能重发生成。
73
+
74
+ 模型、参数及支持状态只在 art 工具 model-catalog/model-registry 内维护,界面与 v-cli 不复制型号判断。远程图片由已注册协议适配器直接调用;视觉分析连接独立,未注入时使用百炼 CLI。Token Plan 是渠道,DashScope 是协议,不跨站点回退凭据。
75
+
76
+ 远端上游身份持久化后才能轮询。`task resume TASK` 只恢复原身份查询与取回,不重发生成;无回执或仍处于 dispatching 的提交保持未知。界面与保存共用 modelEligibility,展示字段不进入执行契约。
77
+
78
+ 风格报告和核心使用 schemaVersion=3,只表达绘制语言,不限定主体题材。低刻画密度不删任务结构,干净笔触不禁止物体纹理,高光画法不统一物理材质。
79
+
80
+ 任务草稿允许内容尚未完成,但拒绝编译器不支持的字段。生成任务的字段正本为 lib/task-contract.mjs;effect 使用 id/kind/target/color/relation/count,不支持 description。先读当前对象,完整保留未修改字段,按当前 revision 保存;保存成功后仍需编译预案,不能声称已生成图片。任务编译错误依据执行回执修正,不猜测风格或尺寸问题。
81
+
82
+ 任务 mustRead 是必须看清的视觉特征,保持字符串数组;画面文字使用独立 textSpecs 数组,每项 content(准确文字)、hierarchy(层级)、zone(位置或载体)必填,fontHint(字形)可选。所有描述完整保存,不设字数上限;草稿允许未填完,预案要求完整。生成任务仅在资产规格允许文字时接受非空 textSpecs,编辑任务按底图及 changes/preserve 执行;不把视觉特征转成文字,不自动开启文字权限。entity.material 是可选物理材质描述。composition.lightDirection/lightQuality 由资产规格成对声明词表及默认值,任务和 variant 可以单项覆盖,未开放能力时携带字段会报错。
83
+
84
+ job read 返回的 resolvedAsset 是只读有效资产规格,assetError 表示解析失败;更新只提交原 config,不回填投影或默认值。任务对象 schemaVersion=2、风格核心 schemaVersion=3 与计划 compilerVersion=4 相互独立。预案在编译时记录编译版本;读取与执行保持预案及其绑定对象不变。
85
+
86
+ 任务参考可通过 reference import --item-id <对象标识> 绑定单个出图对象;未绑定的参考为任务共用。生成与编辑只采纳共用参考和当前对象参考的观察。reference update 的 itemId 可改绑对象,null 表示任务共用。
87
+
88
+ `v-cli capability coverage --json` 核对结构化调用覆盖。参考导入的 `--item-id` 指定当前任务出图对象,省略表示任务共用;工具校验对象身份。
89
+
90
+ ### 本地环境部署
91
+
92
+ 使用 environment guide 获取部署指南与契约,environment inspect 读取机器环境。Pi 通过基础工具和动态工作流完成安装、下载、修正与采样;environment verify 独立校验文件、服务和节点,environment register 验收后登记。任务授权、进程、互斥与恢复交由 Harness。不得把模型回复或服务连通当作真实出图。unregister 仅解除登记,不删除模型或停止外部服务。按 --guide 选择随包方案,模型事实和启动参数只由 art 维护。
93
+
94
+ ### 共享冻结风格
95
+
96
+ 用户要求共享时使用 style export --project ID --id STYLE --out FILE.style.json,收集冻结核心和必要参考,不复制运行记录或设置。style sources --input DIRS.json 只读列出多个来源,单个来源不可用时报告并继续,重复身份内容冲突按来源明确选择。style import --project TARGET --file FILE.style.json 导入固定快照,保留来源身份、版本及核心哈希;不重新分析、采用或随来源更新。导入的冻结对象只读,改动使用 style derive。输出文件不覆盖已有版本。
97
+
98
+
99
+ ## 结果验证
100
+
101
+ 核对原始错误、任务身份、停止状态及实际产物。只报告已经完成的验证,模拟测试与真实执行分别说明。
102
+
103
+ ## 参考资料
104
+
105
+ 使用说明(工具包 `README.md`) · 文档规范(工具包 `docs/documentation.md`) · v-cli.plugin.json
106
+
107
+ ## 许可与版权
108
+
109
+ MIT。Copyright © 2026 Vant。
@@ -0,0 +1,27 @@
1
+ # 参考图风格讨论与回填
2
+
3
+ 用户说“看看这张图的风格,帮我填进去”时,先沿用当前风格对象与会话引用;没有对象且用户要求保存时才创建草稿。先读当前对象、revision 和宿主返回的讨论契约,不让用户重复提供已知信息。当前消息指定的图片和用途优先,不将历史图片全部作为参考。
4
+
5
+ 导入会话附件时,source 原样使用宿主提供的项目相对 path;该 path 可能已经是没有扩展名的哈希文件,不在后面拼附件名称,也不改用应用仓库路径。无法读取时先核对本条附件资料,不全盘搜索其他项目来猜来源。
6
+
7
+ ## 从图像观察到草稿
8
+
9
+ 读取真实图片像素,再分析可复用的媒介观感、线条、笔触、明暗处理、刻画密度及色彩关系。某张图里的具体人物、比例、部件、身份色、材质、场景和光源记录在相关观察上下文,不写成跨主体风格要求。没有证据的分类可以不填,不补齐一套看似完整的规则。
10
+
11
+ 宿主模型能直接看图时,可以根据当前图像观察整理风格草稿;这不等于已经执行了正式风格分析任务。宿主无法看图时使用当前对象配置的视觉分析能力,能力未配置或不可用就说明限制,不凭图片名称猜测。只为普通措辞修改不重复分析。
12
+
13
+ 用户已授权分析和填写时,把贴合目标的分析与适度专业化描述自动保存到当前草稿,保留未修改配置,使用工具提供的 description、constraints、rules、analysis 等实际字段。图像观察通常适合写成 default 倾向;required/avoid 用于确实需要必须遵守或避免的要求,注意不要仅因参考图如此就升级强度。既有身份、分析模型、参考分类及无关规则保持不变。
14
+
15
+ 描述可以有细节,重点是保持适用范围和弹性。例如由柔和光晕提炼出柔和高光是合理的,直接变成所有资产禁止硬边高光就可能过度。毛发、雪面等可作观察例子,通用规则尽量提炼其背后的笔触或过渡方式。配色可描述参考图中的颜色及关系,但不要无意中固定以后所有主体的身份色。无需机械删除具体颜色、数量或形容词,按它们是否有依据、是否帮助当前目标来判断,也不要求填满所有绘制主题。
16
+
17
+ rules 使用当前工具返回的规则数组,不把主题目录包装成新对象。没有正式分析报告的草稿使用对象更新;已有可沿用的正式报告与参考证据时才使用规则修订入口,不先试一个会报错的入口再换另一个。
18
+
19
+ 用户后续说“线条稍利落一点,颜色别变”时,只局部调整相关规则的措辞与程度,保留其他规则和配置,不把小幅修改改成全局禁用软边、纹理或其他技法。原意已清楚就直接保存,不以分类未填满为由继续追问。
20
+
21
+ ## 正式报告与实际保存
22
+
23
+ 需要运行正式分析任务时,按 [项目管线](project.md) 和当前工具契约执行,沿用原 taskId 查询或恢复,不通过新建分析绕过失败。区分三份内容:图像观察是证据;报告 recommendation.rules 是分析建议;对象 config.rules 才是实际保存的草稿规则。正式风格核心另由采用操作生成。
24
+
25
+ 不能只展示报告建议就声称已回填。用户要求填写配置时,分析完成后还需按真实契约保存可用规则;已有未变参考证据的规则修订用对应 revise 入口,其他情况按工具允许的更新入口处理。真实未决问题保留对应项,不清空问题或更改参考来强行通过,也不自动采用或冻结。
26
+
27
+ 用保存回执中的完整对象核对 revision 及实际 config;回执缺少完整内容时再读取一次。简短展示实际填入内容与必要未决项;用户要看最终配置时直接展示保存后的 JSON,不展示另写的一份理想配置。不逐条解释自己没有做哪些扩写,也不附带与本轮无关的下一步确认。保存失败、分析尚未完成或仅有观察建议时如实说明,不声称已经生效。一次校验后结束,本轮不自发循环分析、改写或出图。