@kevlns/art-workshop 0.3.9 → 0.4.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 (48) hide show
  1. package/AGENTS.md +26 -3
  2. package/README.md +1 -1
  3. package/art-workshop.mjs +26 -10
  4. package/docs/commands.md +115 -5
  5. package/docs/core-guidance.md +12 -4
  6. package/docs/data-formats.md +31 -5
  7. package/docs/deployment.md +1 -1
  8. package/docs/local-models/qwen-image-2.1.json +19 -1
  9. package/docs/local-models/qwen-image-2.1.md +6 -4
  10. package/docs/model-architecture.md +4 -0
  11. package/docs/modes.md +7 -1
  12. package/docs/troubleshooting.md +5 -2
  13. package/lib/agent.mjs +3 -1
  14. package/lib/analysis-worker.mjs +2 -1
  15. package/lib/analyze.mjs +8 -7
  16. package/lib/backends.mjs +8 -0
  17. package/lib/candidates.mjs +10 -4
  18. package/lib/comfy-recovery.mjs +17 -0
  19. package/lib/comfyui.mjs +12 -7
  20. package/lib/core.mjs +24 -7
  21. package/lib/edit.mjs +11 -8
  22. package/lib/environment-runtime.mjs +99 -0
  23. package/lib/environments.mjs +7 -4
  24. package/lib/executor.mjs +7 -4
  25. package/lib/favorites.mjs +49 -0
  26. package/lib/generate.mjs +12 -8
  27. package/lib/generation-policy.mjs +1 -1
  28. package/lib/heartbeat.mjs +16 -0
  29. package/lib/presentation.mjs +3 -1
  30. package/lib/prompt-structure.mjs +22 -0
  31. package/lib/shared.mjs +5 -1
  32. package/lib/style-bundle.mjs +85 -0
  33. package/lib/style-contract.mjs +14 -1
  34. package/lib/style-lifecycle.mjs +25 -3
  35. package/lib/style-review.mjs +10 -1
  36. package/lib/task-contract.mjs +33 -3
  37. package/lib/task-references.mjs +13 -1
  38. package/lib/task-worker.mjs +22 -5
  39. package/lib/tasks.mjs +23 -6
  40. package/lib/templates.mjs +4 -2
  41. package/lib/transparent-output.mjs +74 -0
  42. package/lib/workspace.mjs +30 -9
  43. package/package.json +1 -1
  44. package/rules/core-guidance.json +1 -0
  45. package/skills/art-workshop/SKILL.md +30 -5
  46. package/v-cli.plugin.json +271 -7
  47. package/workflows/vant-builtin-qwen-image-2.1-Q4-8GB.api.json +1 -1
  48. package/workflows/vant-builtin-qwen-image-2.1-Q4-8GB.json +2 -2
package/AGENTS.md CHANGED
@@ -20,30 +20,48 @@ art-workshop agent index
20
20
 
21
21
  ### 对象与参考
22
22
 
23
+ 任务参考只提取 purposes 指定且未被 ignore 排除的特征。用途范围外、用户已明确覆盖的背景和绘制差异不构成阻塞;conflicts 仅列范围内不可调和要求,uncertainties 仅列影响执行的关键缺失,两者为非空字符串数组,无问题用 []。不得删除用户参考或清空报告来绕过分析;应明确参考范围后重新分析,真正的未决取舍再交用户决定。
24
+
23
25
  工程对象使用 schemaVersion 2;读写前核实工程配置和当前 revision。
24
- 风格和任务都有稳定 id 与 revision。UI、聊天和 CLI 共用对象;写入、派生与清理提交预期 revision,冲突重新读取。正式风格只读,改动创建派生风格;派生不继承报告、核心、批次、授权与对话。
26
+ 风格和任务都有稳定 id 与 revision。UI、聊天和 CLI 共用对象;写入、派生与清理提交预期 revision,冲突重新读取。正式风格只读,改动创建派生风格;派生不继承核心、批次、授权与对话。当前版本冻结风格派生时保留结构化规则和独立参考,报告明确标记沿用原冻结证据;不伪造新的分析。
25
27
  风格静态参考只有 style、palette、rendering,只分析媒介、描绘、明暗、描边、笔触和色彩关系。具体造型、比例、结构、部件、身份色、材质与光源属于任务。任务动态参考只有 subject、composition、pose、identity-color、surface、scene-light、text;编辑底图另列。导入复制原图,不修改用户文件。未适配直接参考时拒绝,不隐式上传风格图片。
26
28
 
27
29
  ### 风格生命周期
28
30
 
29
- style create/read/update/derive/discard 管理草稿。style analyze --dry 只读编译,不联网、启动服务或创建参考目录。实际 analyze 创建 taskId 与独立参考证据;task status/wait/cancel 控制执行,recover 查原登记,resume 仅恢复远程查询与取回。
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 仅按已记录的上游身份恢复查询与取回,不重新提交。
30
35
  报告绑定源配置、参考与模型。更新配置保留报告并标记需复核,旧证据不变。报告 recommendation.rules 是精炼独立成稿,规则含主题、强度和适用条件,不包含迭代描述。issues 仅列需用户取舍的矛盾,notes 保留不阻塞采用的证据局限。style resolve --input {issueId,optionId,note} 记录明确选择并修订有效方案,不重新分析;以 style read 的 review.ready 判断采用条件。复核沿用证据与决定,新证据才重新打开问题。style adopt 校验来源匹配和所有问题已决定,用户采用后冻结。采用中断通过 style recover 完成已授权事务,不能重新冻结另一份核心。
31
36
  退出风格配置先继续编辑、保存草稿或放弃;分析停止未确认时不能清理。
32
37
 
33
38
  ### 计划与执行
34
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,再按独立工具的本地配置选择;任务绑定后端时使用其真实模型,不能被旧 execution.model 覆盖。宿主按实例注入凭据,不在对象或预案写入密钥;修改选择使原方案失效。
43
+
35
44
  先读取实际 job,再 generate/edit plan 和 run --plan --dry,展示有效核心、设计尺寸、预留缩放、请求与实际像素、模型后端、候选数量和编辑底图。后端尺寸由工具统一解析,超限或未对齐选最近合法尺寸,保留设计基准并明确实际值;不承诺显存或自动缩放导出。
36
45
  授权覆盖方案后使用 run --background;前台同样创建执行身份。配置、核心、规格、参考、底图和后端变化拒绝失效方案,重新编译。重启查 taskId,不重复提交。不自动换模型或重跑成功项。
37
- 每个任务只能有一个未停止确认的执行;编辑、派生、删除与运行共用状态检查。切页面不取消。
46
+ 每个任务只能有一个未停止确认的执行;编辑、派生、归档、恢复与运行共用状态检查。切页面不取消。
47
+ job discard 归档已停止的任务,草稿、待定版和已定版均可归档。按 revision 将任务标记为 discarded(归档存储状态),保留配置、参考、私有底图、运行、输出、收藏和定版历史;活跃列表、收藏及作品暂不显示。job restore 按同一身份和当前 revision 恢复到活跃列表,收藏与作品重新显示,不重新生成。归档与恢复均检查停止确认和版本,重复操作幂等;恢复后原方案需按当前版本重新编译。风格 discard 仍为草稿放弃,不参与任务归档。
38
48
 
39
49
  ### 取消、异常和关闭
40
50
 
51
+ 本地 ComfyUI 按资产及采样序号持久化 prompt ID。工作进程丢失后使用 task resume 或 Vant 原批次恢复入口,沿用原身份查询与取回,不重新上传或提交生图;未提交项不补发。Windows 心跳写入暂时失败记录诊断并重试,不能导致定时器异常退出;关键状态写入仍严格校验。
52
+
41
53
  任务状态与停止证据分开。queued/running/cancelling 仍占用资源;unknown 或 stopConfirmed=false 保留资源。failed/cancelled 也不能单凭状态释放资源;dispatching/accepted 远程回执尚未结清时继续占用。工作进程丢失标记 unknown,不推测停止。
42
54
  task cancel 只取消指定运行,保留服务。生成任务远程取消只停止本地客户端,上游停止未知如实报告,不允许清理。只读分析有 finishedAt、已知终态且工作进程已退出,无生成计划与回执时释放本地占用;云端计算与计费停止未知独立保留,不自动重发。没有完成证据的进程丢失仍保持 unknown。shutdown 阻止提交、停止关联任务、核验共享队列和进程身份后关闭本地服务,不清空共享队列;有其他任务或停止未确认时保留服务。不得广泛杀所有 Python。
43
55
 
44
56
  ### 生成与定版
45
57
 
58
+ 透明背景使用 `{type:"transparent"}`:生成任务设置 composition.background,编辑任务设置 changes 中 background 的 value。预案记录 PNG 输出处理版本并参与哈希;含完全透明区域的原生 alpha 保留,接近不透明的 alpha 噪声不视为透明背景。否则从边缘核实约定洋红底色,容许模型色偏,仅处理与外边界连通的底色及混合边缘。原图保留,候选使用处理后的 PNG;缺少合格背景或可见主体则报错,不伪称透明成功。纯色去背景可能影响与外部底色连通的同色细节,不能承诺任意半透明材质的抠图质量。
59
+
60
+ 编辑 target 是范围名称,允许 outline 等具体范围;同一范围可修改局部并保留其他特征,不能仅按标签重叠判矛盾。配置和预案仍校验字段、引用、版本及核心风格归属。
61
+
46
62
  只有生成与定版两个产品阶段。check 验证计划、执行身份、文件哈希和完成事实;不要求人工 content/style/asset 评分。candidate finalize 按资产选定候选,重复操作幂等;替换已有定版需要明确 replace,保留历史。
63
+ 候选 editable 与 accepted 分开:已停止批次中保留的有效图片可作为编辑底图,输出处理失败不阻止继续编辑;已记录的哈希不匹配、文件缺失或已删除则拒绝。job from-candidate 验证图片可解码后复制为独立编辑草稿的私有底图并记录来源,不改变原批次失败事实,也不授权定版或启动生成。
64
+ candidate favorite 使用 --value true/false 收藏或取消收藏,candidate favorites 查看工程收藏。收藏记录独立保存在工程 favorites.json,绑定源任务、批次和图片身份,不修改需求版本、执行或定版状态;可收藏有效的失败保留图。列表隐藏已删除、丢失或所属任务已归档的图片,源任务改名即时反映。
47
65
  candidate delete 先确认影响,拒绝运行中或被计划/底图引用的候选;先记删除事实,清理所属文件,并取消关联定版。定版不自动导入游戏或提交 Git。
48
66
 
49
67
  ### 验证和技能
@@ -69,6 +87,11 @@ candidate delete 先确认影响,拒绝运行中或被计划/底图引用的
69
87
 
70
88
  使用 environment guide 获取部署指南与契约,environment inspect 读取机器环境。Pi 通过基础工具和动态工作流完成安装、下载、修正与采样;environment verify 独立校验文件、服务和节点,environment register 验收后登记。任务授权、进程、互斥与恢复交由 Harness。不得把模型回复或服务连通当作真实出图。unregister 仅解除登记,不删除模型或停止外部服务。按 --guide 选择随包方案,模型事实和启动参数只由 art 维护。
71
89
 
90
+ ### 共享冻结风格
91
+
92
+ 用户要求共享时使用 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。输出文件不覆盖已有版本。
93
+
94
+
72
95
  ## 结果验证
73
96
 
74
97
  核对原始错误、任务身份、停止状态及实际产物。只报告已经完成的验证,模拟测试与真实执行分别说明。
package/README.md CHANGED
@@ -34,7 +34,7 @@ art-workshop agent index
34
34
  4. 按任务授权执行,保存 taskId;前台和后台都登记运行。查询原身份,不因超时或重启重复提交。
35
35
  5. `check` 核验产物,`candidate finalize` 定版。替换需 `--replace`,删除需 `--confirm`,均保留事实记录。
36
36
 
37
- 正式风格只读,修改需派生。任务空闲后可按原身份更新配置,历史批次不覆写。状态优先级为待定版、执行中、已定版、草稿;运行状态与停止证据分别判断,不能只看终态释放占用。
37
+ 正式风格只读,修改需派生。任务空闲后可按原身份更新配置,历史批次不覆写。job discard 归档任务,job restore 按当前版本恢复;配置、收藏与历史图片保留。任务列表默认按执行中、待定版、草稿、已定版排序;运行状态与停止证据分别判断,不能只看终态释放占用。
38
38
 
39
39
  ### 后端与数据归属
40
40
 
package/art-workshop.mjs CHANGED
@@ -1,10 +1,11 @@
1
1
  #!/usr/bin/env node
2
+ import {prepareRuntime} from './lib/environment-runtime.mjs';
2
3
  import {readdirSync,existsSync} from 'node:fs';
3
4
  import {join,resolve} from 'node:path';
4
5
  import {readJson,writeJson} from './lib/shared.mjs';
5
6
  const args=process.argv.slice(2),pos=[],options={};
6
7
  if(args.length===1&&['--version','-V'].includes(args[0])){console.log(readJson(new URL('./package.json',import.meta.url)).version);process.exit(0);}
7
- const help='art-workshop: config path/show/init/validate | doctor [--backend ID] [--start] | workflow list | environment guide/list/inspect/verify/register/unregister | refs guide | agent index/docs/init | list | style create/list/read/update/derive/discard/analyze/resolve/adopt/recover/validate/show | generate show/plan/run | edit show/plan/run | task list/status/wait/cancel/recover/resume | shutdown | check RUN | project init/upgrade | job template/from-candidate/create/list/read/update/derive/discard/analyze | reference import/list/update/remove | candidate list/finalize/delete/finalizations | compare PLAN PLAN\nrun --background 返回任务 ID;--backend 选择后端。shutdown 停止当前工作区关联任务,核验共享队列和进程身份后关闭本地服务。\n也可用 v-cli art 调用;先 v-cli agent docs art,再 v-cli agent describe art --json 查看完整参数。';
8
+ const help='art-workshop: config path/show/init/validate | doctor [--backend ID] [--start] | workflow list | environment guide/list/prepare/inspect/verify/register/unregister | refs guide | agent index/docs/init | list | style export/import/sources/create/list/read/update/derive/discard/analyze/resolve/adopt/recover/validate/show | generate show/plan/run | edit show/plan/run | task list/status/wait/cancel/recover/resume | shutdown | check RUN | project init/upgrade | job template/from-candidate/create/list/read/update/derive/discard/restore/analyze | reference import/list/update/remove | candidate list/favorites/favorite/finalize/delete/finalizations | compare PLAN PLAN\nrun --background 返回任务 ID;--backend 选择后端。shutdown 停止当前工作区关联任务,核验共享队列和进程身份后关闭本地服务。\n也可用 v-cli art 调用;先 v-cli agent docs art,再 v-cli agent describe art --json 查看完整参数。';
8
9
  if(!args.length||args.length===1&&['--help','-h','help'].includes(args[0])){console.log(help);process.exit(0);}
9
10
  const {loadJob,loadProject}=await import('./lib/project.mjs');
10
11
  const {referenceRoot,referenceGuide}=await import('./lib/refs.mjs');
@@ -19,9 +20,10 @@ const {backendDefaults,bindBackend,buildComfyRequest}=await import('./lib/backen
19
20
  const {startTask,taskStatus,taskView,recoverTask,resumeTask,waitTask,cancelTask,shutdown}=await import('./lib/tasks.mjs');
20
21
  const {runtimeRoot,tasks}=await import('./lib/runtime.mjs');
21
22
  const {validateConfiguration,doctor}=await import('./lib/diagnostics.mjs');
22
- const {createProject,createObject,listObjects,readObject,styleView,updateObject,deriveObject,discardObject,importReference,removeReference,updateReference,taskDisplayState,STYLE_CATEGORIES,TASK_PURPOSES}=await import('./lib/workspace.mjs');
23
- const {startAnalysis,adoptStyle,recoverStyleAdoption,resolveStyleIssue}=await import('./lib/style-lifecycle.mjs');
23
+ const {createProject,createObject,listObjects,readObject,styleView,updateObject,deriveObject,discardObject,restoreTask,importReference,removeReference,updateReference,taskDisplayState,STYLE_CATEGORIES,TASK_PURPOSES}=await import('./lib/workspace.mjs');
24
+ const {startAnalysis,adoptStyle,recoverStyleAdoption,resolveStyleIssue,reviseStyleRules}=await import('./lib/style-lifecycle.mjs');
24
25
  const {candidates,finalize,deleteCandidate,finalizations,editFromCandidate}=await import('./lib/candidates.mjs');
26
+ const {favoriteList,setFavorite}=await import('./lib/favorites.mjs');
25
27
  const {upgradeProject}=await import('./lib/migration.mjs');
26
28
  const {workflowList}=await import('./lib/workflows.mjs');
27
29
  const {jobTemplate}=await import('./lib/templates.mjs');
@@ -29,7 +31,7 @@ const {deploymentGuide}=await import('./lib/deployment-guide.mjs');
29
31
  const {inspectInstallation,discoverInstallations}=await import('./lib/environments.mjs');
30
32
  const {verifyInstallation,registerInstallation,unregisterInstallation}=await import('./lib/environment-operations.mjs');
31
33
  const flags=new Set(['dry','explore','background','start','replace','confirm','all-variants']);
32
- const allowed=new Set(['config','workspace','output-dir','refs-dir','cache-dir','directory','endpoint','guide','project','input','out','report','note','core','job','plan','item','variant','offset','limit','file','backend','timeout','kind','id','revision','source','category','purposes','mapping','run','candidate','actor','operation','retry-run','item-id',...flags]);
34
+ const allowed=new Set(['config','workspace','output-dir','refs-dir','cache-dir','directory','endpoint','guide','project','input','out','report','note','core','job','plan','item','variant','offset','limit','file','backend','timeout','kind','id','revision','source','category','purposes','mapping','run','candidate','actor','operation','retry-run','item-id','value',...flags]);
33
35
  for(let i=0;i<args.length;i++){if(args[i].startsWith('--')){const k=args[i].slice(2);if(!allowed.has(k)||k in options) throw new Error('未知或重复参数 '+k);options[k]=flags.has(k)?true:args[++i];if(options[k]===undefined) throw new Error('参数缺少值 '+k);}else pos.push(args[i]);}
34
36
  const print=x=>console.log(JSON.stringify(x?.schema==='art-workshop/style'?styleView(settings.paths.workspace,x):x,null,2));
35
37
  if(pos[0]==='workflow'&&pos[1]==='list'){print(workflowList());process.exit(0);}
@@ -53,6 +55,7 @@ try {
53
55
  if(module==='environment'){
54
56
  if(action==='guide')print(deploymentGuide(options.guide));
55
57
  else if(action==='list')print({environments:discoverInstallations()});
58
+ else if(action==='prepare')print(await prepareRuntime(required('directory'),{guideId:options.guide}));
56
59
  else if(action==='inspect')print(await inspectInstallation(required('directory'),required('endpoint'),options.guide));
57
60
  else if(action==='verify'){const result=await verifyInstallation(required('directory'),required('endpoint'),{guideId:options.guide});print(result);if(!result.ok)process.exitCode=1;}
58
61
  else if(action==='register')print(await registerInstallation(required('directory'),required('endpoint'),{guideId:options.guide}));
@@ -88,6 +91,7 @@ try {
88
91
  else if(action==='update'){const record=await updateObject(settings,projectId,kind,required('id'),Number(required('revision')),readJson(path(required('input'))));print(kind==='style'?styleView(ROOT,record):record);}
89
92
  else if(action==='analyze'&&kind==='task')print(await startAnalysis(settings,projectId,required('id'),Number(required('revision')),{dry:options.dry,kind:'task',operationId:options.operation}));
90
93
  else if(action==='derive')print(await deriveObject(settings,projectId,kind,required('id'),Number(required('revision'))));
94
+ else if(action==='restore'&&kind==='task')print(await restoreTask(settings,projectId,required('id'),Number(required('revision'))));
91
95
  else if(action==='discard')print(await discardObject(settings,projectId,kind,required('id'),Number(required('revision'))));
92
96
  else throw new Error('未知对象操作');
93
97
  }
@@ -102,10 +106,17 @@ try {
102
106
  else throw new Error('未知 agent 操作');
103
107
  }
104
108
  else if(module==='list'){print((existsSync(join(ROOT,'projects'))?readdirSync(join(ROOT,'projects')):[]).map(id=>readJson(join(ROOT,'projects',id,'project.json'))));}
109
+ else if(module==='style'&&['export','import','sources'].includes(action)){
110
+ const bundle=await import('./lib/style-bundle.mjs');
111
+ if(action==='export')print(bundle.exportStyleBundle(ROOT,required('project'),required('id'),path(required('out'))));
112
+ else if(action==='import')print(await bundle.importStyleBundle(settings,required('project'),path(required('file'))));
113
+ else print(bundle.listStyleSources(readJson(path(required('input')))));
114
+ }
105
115
  else if(module==='style'){
106
116
  const projectId=required('project');
107
117
  if(action==='analyze')print(await startAnalysis(settings,projectId,required('id'),Number(required('revision')),{dry:options.dry,operationId:options.operation}));
108
118
  else if(action==='recover')print(await recoverStyleAdoption(settings,projectId,required('id')));
119
+ else if(action==='revise')print(styleView(ROOT,await reviseStyleRules(settings,projectId,required('id'),Number(required('revision')),readJson(path(required('input'))))));
109
120
  else if(action==='resolve')print(styleView(ROOT,await resolveStyleIssue(settings,projectId,required('id'),Number(required('revision')),readJson(path(required('input'))))));
110
121
  else if(action==='adopt')print(await adoptStyle(settings,projectId,required('id'),Number(required('revision')),{note:options.note}));
111
122
  else if(action==='validate') print(validateReport(readJson(path(required('report'))),projectId));
@@ -116,7 +127,7 @@ try {
116
127
  else if(['plan','run'].includes(action)){
117
128
  let plan;
118
129
  if(options.plan){if(action!=='run'||['project','job','core','explore','backend'].some(k=>options[k]!==undefined)) throw new Error('冻结计划不能同时调整来源;修改任务后重新 plan');plan=readJson(path(options.plan));validatePlan(plan);if(plan.module!==module) throw new Error('计划模块不匹配');}
119
- else plan=bindBackend((module==='generate'?compileGenerate:compileEdit)({projectId:required('project'),jobId:required('job'),coreId:options.core,root:ROOT,localExecution:backendDefaults(settings,options.backend)}),settings,options.backend);
130
+ else {const job=loadJob(required('project'),required('job'),module,ROOT),backend=options.backend??job.generation?.backend;plan=bindBackend((module==='generate'?compileGenerate:compileEdit)({projectId:required('project'),jobId:required('job'),coreId:options.core,root:ROOT,localExecution:backendDefaults(settings,backend)}),settings,backend);}
120
131
  if(action==='plan'){if(options.out) writeJson(path(options.out),plan);print(plan);}
121
132
  else {
122
133
  if(options['retry-run']&&(options.dry||options.variant||options.item||options.offset||options.limit))throw new Error('失败项重试不能混用预演或手动筛选');
@@ -137,11 +148,16 @@ try {
137
148
  else throw new Error('未知 task 操作');
138
149
  }else if(module==='shutdown'){if(action)throw new Error('shutdown 不接受位置参数');print(await shutdown(settings));}
139
150
  else if(module==='candidate'){
140
- const projectId=required('project'),jobId=required('job');
141
- if(action==='list')print(candidates(settings,projectId,jobId,required('run')));
142
- else if(action==='finalize')print(await finalize(settings,projectId,jobId,Number(required('revision')),{runId:required('run'),candidateId:required('candidate'),replace:options.replace,actor:required('actor')}));
143
- else if(action==='delete')print(await deleteCandidate(settings,projectId,jobId,Number(required('revision')),{runId:required('run'),candidateId:required('candidate'),confirm:options.confirm,actor:required('actor')}));
144
- else if(action==='finalizations')print(finalizations(settings,projectId,jobId));
151
+ const projectId=required('project');
152
+ if(action==='favorites')print(favoriteList(settings,projectId));
153
+ else if(action==='favorite'){
154
+ if(!['true','false'].includes(options.value))throw new Error('value 必须为 true 或 false');
155
+ print(await setFavorite(settings,projectId,required('job'),{runId:required('run'),candidateId:required('candidate'),value:options.value==='true'}));
156
+ }
157
+ else if(action==='list')print(candidates(settings,projectId,required('job'),required('run')));
158
+ else if(action==='finalize')print(await finalize(settings,projectId,required('job'),Number(required('revision')),{runId:required('run'),candidateId:required('candidate'),replace:options.replace,actor:required('actor')}));
159
+ else if(action==='delete')print(await deleteCandidate(settings,projectId,required('job'),Number(required('revision')),{runId:required('run'),candidateId:required('candidate'),confirm:options.confirm,actor:required('actor')}));
160
+ else if(action==='finalizations')print(finalizations(settings,projectId,required('job')));
145
161
  else throw new Error('未知 candidate 操作');
146
162
  }else if(module==='check'){print(checkRun(readJson(manifestPath(action??required('file'))),manifestPath(action??required('file'))));
147
163
  }else if(module==='compare'){const read=value=>{const data=readJson(path(value));const plan=data.plan??data;validatePlan(plan);return plan;};const a=read(action),b=read(pos[2]);print({sameCore:a.sources.coreHash===b.sources.coreHash,execution:{before:a.execution,after:b.execution},items:b.items.map(x=>({itemId:x.itemId,variantId:x.variantId,changed:a.items.find(y=>y.itemId===x.itemId&&y.variantId===x.variantId)?.inputHash!==x.inputHash}))});}
package/docs/commands.md CHANGED
@@ -507,9 +507,24 @@ v-cli art style resolve
507
507
 
508
508
  - 查询不写入;修改验证 revision、归属和停止确认;冻结风格只读
509
509
 
510
+ ### style revise
511
+
512
+ 按用户要求修订完整规则方案;input 为 {rules,summary,note},沿用未变化的参考证据,不调用模型或自动冻结
513
+
514
+ ```sh
515
+ v-cli art style revise
516
+ ```
517
+
518
+ - `--project <id>`:工程身份
519
+ - `--id <id>`:对象身份
520
+ - `--revision <number>`:预期对象版本
521
+ - `--input <file>`:JSON {rules,summary,note};rules 为完整规则数组,每条 id/scope/strength/instruction/when,avoid 可含 negative 抽象排除表达数组
522
+
523
+ - 查询不写入;修改验证 revision、归属和停止确认;冻结风格只读
524
+
510
525
  ### style derive
511
526
 
512
- 派生独立草稿,不继承执行、报告或定版
527
+ 派生独立草稿,保留结构化规则与独立参考;当前冻结证据标记沿用,不继承核心、执行或授权
513
528
 
514
529
  ```sh
515
530
  v-cli art style derive
@@ -604,7 +619,7 @@ v-cli art job derive
604
619
 
605
620
  ### job discard
606
621
 
607
- 确认空闲后丢弃草稿并清理所属资源
622
+ 归档已停止的任务,保留配置、参考、收藏、图片与执行历史;可恢复到活跃列表
608
623
 
609
624
  ```sh
610
625
  v-cli art job discard
@@ -614,7 +629,21 @@ v-cli art job discard
614
629
  - `--id <id>`:对象身份
615
630
  - `--revision <number>`:预期对象版本
616
631
 
617
- - 查询不写入;修改验证 revision、归属和停止确认;冻结风格只读
632
+ - 验证 revision、任务归属和停止确认;归档和恢复均保留原配置、收藏与所有历史文件,不自动执行
633
+
634
+ ### job restore
635
+
636
+ 恢复已归档任务到活跃列表,保留原身份、配置与历史;不重新执行
637
+
638
+ ```sh
639
+ v-cli art job restore
640
+ ```
641
+
642
+ - `--project <id>`:工程身份
643
+ - `--id <id>`:对象身份
644
+ - `--revision <number>`:预期对象版本
645
+
646
+ - 验证 revision、任务归属和停止确认;归档和恢复均保留原配置、收藏与所有历史文件,不自动执行
618
647
 
619
648
  ### style adopt
620
649
 
@@ -735,6 +764,34 @@ v-cli art candidate list
735
764
 
736
765
  - 只读;校验批次计划和候选身份
737
766
 
767
+ ### candidate favorites
768
+
769
+ 网格收藏夹的数据来源,列出工程中仍可用的收藏图片及源任务身份
770
+
771
+ ```sh
772
+ v-cli art candidate favorites --project <id>
773
+ ```
774
+
775
+ - `--project <id>`:工程身份
776
+
777
+ - 只读;忽略已删除的图片和已归档的任务
778
+
779
+ ### candidate favorite
780
+
781
+ 设置图片收藏状态,不修改任务需求、版本、定版或运行状态
782
+
783
+ ```sh
784
+ v-cli art candidate favorite --project <id> --job <id> --run <id> --candidate <id> --value <true|false>
785
+ ```
786
+
787
+ - `--project <id>`:工程身份
788
+ - `--job <id>`:源任务身份
789
+ - `--run <id>`:源批次身份
790
+ - `--candidate <id>`:图片候选身份
791
+ - `--value <true|false>`:true 收藏,false 取消收藏
792
+
793
+ - 仅修改工程收藏记录;重复操作幂等,不启动分析或生成
794
+
738
795
  ### candidate finalizations
739
796
 
740
797
  查看资产定版
@@ -846,7 +903,7 @@ v-cli art job template --project <id> --kind <generate|edit> [--core <id>]
846
903
 
847
904
  ### job from-candidate
848
905
 
849
- 将完整候选导入私有底图,创建独立编辑草稿,不运行
906
+ 将已停止批次中的可用图片导入私有底图,创建独立编辑草稿,不要求定版通过、不运行
850
907
 
851
908
  ```sh
852
909
  v-cli art job from-candidate --project <id> --id <task> --run <id> --candidate <id>
@@ -855,7 +912,7 @@ v-cli art job from-candidate --project <id> --id <task> --run <id> --candidate <
855
912
  - `--project <id>`:工程身份
856
913
  - `--id <task>`:源任务身份
857
914
  - `--run <id>`:真实批次
858
- - `--candidate <id>`:完整候选身份
915
+ - `--candidate <id>`:可用图片的候选身份
859
916
 
860
917
  - 写入新的编辑草稿和私有底图;保留候选来源;不启动生成
861
918
 
@@ -896,6 +953,20 @@ v-cli art environment list
896
953
 
897
954
  - 不执行安装、下载或采样;register 重新验收后登记,unregister 不删除安装文件或停止服务
898
955
 
956
+ ### environment prepare
957
+
958
+ 自动准备兼容 Python 运行时,保留已有环境
959
+
960
+ ```sh
961
+ v-cli art environment prepare
962
+ ```
963
+
964
+ - `--directory <value>`:本机环境根目录
965
+ - `--endpoint <value>`:本机 HTTP 服务根地址
966
+ - `--guide <id>`:部署指南标识;省略使用环境登记或推荐方案
967
+
968
+ - 仅在目标目录创建运行时;复用兼容 Python,不兼容虚拟环境先改名保留,不修改全局 Python
969
+
899
970
  ### environment inspect
900
971
 
901
972
  本地环境只读检测
@@ -950,6 +1021,45 @@ v-cli art environment unregister
950
1021
 
951
1022
  - 不执行安装、下载或采样;register 重新验收后登记,unregister 不删除安装文件或停止服务
952
1023
 
1024
+ ### style export
1025
+
1026
+ 导出冻结风格及必要参考,不复制运行状态
1027
+
1028
+ ```sh
1029
+ v-cli art style export
1030
+ ```
1031
+
1032
+ - `--project <value>`:工程身份
1033
+ - `--id <value>`:冻结风格身份
1034
+ - `--out <value>`:风格包输出文件
1035
+
1036
+ - 冻结风格包只读;不覆盖已有文件;修改请派生草稿;只导出明确引用的参考图片
1037
+
1038
+ ### style import
1039
+
1040
+ 导入固定版本的共享冻结风格,保留原身份和版本
1041
+
1042
+ ```sh
1043
+ v-cli art style import
1044
+ ```
1045
+
1046
+ - `--project <value>`:目标工程
1047
+ - `--file <value>`:风格包文件
1048
+
1049
+ - 冻结风格包只读;不覆盖已有文件;修改请派生草稿;只导出明确引用的参考图片
1050
+
1051
+ ### style sources
1052
+
1053
+ 只读列出多个冻结风格来源并报告不可用目录和身份冲突
1054
+
1055
+ ```sh
1056
+ v-cli art style sources
1057
+ ```
1058
+
1059
+ - `--input <value>`:来源目录列表 JSON 文件
1060
+
1061
+ - 冻结风格包只读;不覆盖已有文件;修改请派生草稿;只导出明确引用的参考图片
1062
+
953
1063
  ## 结果验证
954
1064
 
955
1065
  按任务身份、停止证据和实际产物核验;只读检查不证明真实出图。
@@ -14,14 +14,18 @@
14
14
 
15
15
  ### 最终规范
16
16
 
17
- 报告和核心使用 schemaVersion=3,项目与对象存储版本仍为2。recommendation 只含 rules:每条具有稳定 id、scope、strength、instruction、when。
17
+ 报告和核心使用 schemaVersion=3,项目与对象存储版本仍为2。recommendation 只含 rules:每条具有稳定 id、scope、strength、instruction、when;avoid 可填写 negative 字符串数组。
18
18
 
19
19
  - scope:medium、shading、outline、highlights、brushwork、detail、palette。
20
- - strength:required 必须、default 默认倾向、avoid 避免。
20
+ - strength:required 必须遵守、default 默认倾向、avoid 必须避免。“默认少用”仍使用 default,不升级为禁止。
21
21
  - instruction:300字以内的独立、准确、精炼绘制要求;不能出现本轮、上一版、修改经过等迭代描述。
22
22
  - when:适用条件,无条件时为空。局部例外与默认倾向可以共存,不强制精确色值、线宽或色阶。
23
23
 
24
- 生成提示保留条件与强度。带条件的避免规则不会被展开为全局负面提示。最终核心只使用规则,不把聊天记录、问题解释或证据局限混入生成规范。
24
+ 生成提示按主题组织,保留条件与强度。正向表达绘制语言,负向排除抽象的渲染、笔触或语言混杂等特征;负向不能变成主体、部件、身份色、具体材质和纹理的黑名单。不得从参考图中未出现的内容推断禁止条件。
25
+
26
+ negative 为可选的被排除特征列表,不加“避免、不要、禁止、no、without”等否定前缀。instruction 为同一规则的阅读说明;条件与例外写入 when。仅无条件 avoid 且明确填写 negative 时编译进独立负向段;其余文字约束及条件排除保留在正向规则段,不猜测条件、不机械转换。default 不升级为负向禁止;正向与负向按路由去重,完整冻结配置保留阅读说明。
27
+
28
+ 模型支持独立 negative_prompt 时直接发送;不支持时适配器将负向约束明确并入正向排除段,使用合并后的提示词长度限制,不默默丢弃或截断。ComfyUI 将其绑定到 negativePrompt 输入,缺少绑定则明确报错。界面预案显示适配后实际请求,条件排除和全局负向分别说明。最终核心只使用规则,不把聊天记录、问题解释或证据局限混入生成规范。
25
29
 
26
30
  ### 报告与取舍
27
31
 
@@ -29,7 +33,11 @@ summary 概述当前方案,observations 保存分类证据,notes 保存不
29
33
 
30
34
  style resolve 校验 revision、报告来源和选项,记录 issueId、问题指纹、optionId、用户依据和时间。选择应用于候选规范,不改变原始模型响应;reviewHistory 记录历次选择。覆盖已有决定涉及的规则时,相关已记录决定重新打开,不静默覆盖。采用要求当前来源匹配、所有问题已有有效决定;notes 非空仍可采用。
31
35
 
32
- 修改草稿或参考保留报告并标记需复核。复核提供上一版方案和决定;同一证据、问题与选项不变时保留决定,新证据或明确重新打开理由要求重新确认。逐图观察按内容和分类契约缓存,未改变的图不重复请求。
36
+ 修改草稿或参考保留报告并标记需复核。已有规则按用户要求修改时,style revise 接收完整 rules、summary 与 note,沿用未变化的参考证据,记录原报告及用户依据,不调用模型、不自动冻结;自由补充不被删除。参考或分析配置改变时须重新分析,未决问题先集中确认。
37
+
38
+ 当前职责版本的冻结风格派生后保留结构化规则及独立参考,报告标记 inherited-frozen;用户规则修订标记 user-rules,原模型观察作为证据保留,不伪称重新分析。旧职责版本仍保留只读证据,不能自动转换。
39
+
40
+ 需要分析复核时,复核提供上一版方案和决定;同一证据、问题与选项不变时保留决定,新证据或明确重新打开理由要求重新确认。逐图观察按内容和分类契约缓存,未改变的图不重复请求。
33
41
 
34
42
 
35
43
 
@@ -12,6 +12,10 @@ art 工程与输入结构,适用于当前随包实现。
12
12
 
13
13
  ### 工程和对象
14
14
 
15
+ 动态需求的意图、外观、身份色、动作、效果描述、关系、场景、编辑指令与 mustRead 条目不设字符数上限;原文进入方案,不自动截断。类型、必填内容、字段引用和版本校验仍生效。
16
+
17
+ 任务参考只提取 purposes 指定且未被 ignore 排除的特征。用途范围外、用户已明确覆盖的背景和绘制差异不构成阻塞;conflicts 仅列范围内不可调和要求,uncertainties 仅列影响执行的关键缺失,两者为非空字符串数组,无问题用 []。不得删除用户参考或清空报告来绕过分析;应明确参考范围后重新分析,真正的未决取舍再交用户决定。
18
+
15
19
  project.json 必须声明 schemaVersion=2、revision、id、name、analysisModel、execution、cores、defaultCore。工程身份与目录匹配,核心必须属于同一工程。
16
20
 
17
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,不能改身份与类型。
@@ -20,15 +24,22 @@ projects/<projectId>/styles/<styleId>/style.json 与 tasks/<taskId>/task.json
20
24
 
21
25
  ### 需求与计划
22
26
 
23
- 生成 config 包括 project、kind、core、execution、items,以及互斥的 profile 或内联 asset 规格;实体及效果有稳定 id、数量、颜色、角色与关系。具体主体、构图、动作不冻结进风格。规格定义资产约束、设计基准与检查要点,内联规格属于当前任务,编译时形成同一不可变快照。编辑 config 的 items 明确 source、changes、preserve、mustRead、seed。
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。
24
30
 
25
- plan 包括 schema=art-workshop/plan、module/project/job、sources、snapshots、refs、execution、items、planHash。sources 绑定 taskRevision、taskConfigHash 和 coreHash;项目/核心/profile/任务形成快照。项含 inputHash、实际尺寸和 seed。任何来源或哈希变化拒绝运行。
31
+ 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。任何来源或哈希变化拒绝运行。
32
+
33
+ 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 不视为省略。任务切换模型、后端或采样参数会改变配置哈希,必须重新编译。凭据由宿主按实例注入,不保存在配置。
26
34
 
27
35
  ### 执行与定版
28
36
 
29
37
  对象 taskId(命令中称 job/id)与执行 taskId 是两种身份;每次真实执行有独立登记。运行记录包含 queued/running/cancelling/succeeded/failed/cancelled/unknown、heartbeat、workerPid、后端身份、manifestPath、stopConfirmed 与 unsettled。终态与停止证据独立;没有停止证据继续占用对象。配置状态及界面分组不能取代运行身份。
38
+ 任务归档使用 job discard,在停止已确认且 revision 匹配后标记 status=discarded(归档存储状态)、记录 deletedAt。配置、参考、底图、运行、输出、收藏及定版历史保留。活跃任务、收藏和作品暂不显示归档内容;job restore 将同一任务恢复为 draft、清除 deletedAt 并记录 restoredAt,原收藏和定版重新显示。恢复不产生新完成通知,不自动执行旧方案;任何后续编辑或执行仍校验当前版本。
30
39
 
31
- manifest 保存计划、每项输出及哈希、失败证据和完成事实。候选身份绑定运行、资产、构图与文件。定版记录保留资产、候选、批次、哈希、操作者与时间;替换与删除进入历史。删除先记录事实,物理清理可重试。
40
+ manifest 保存计划、每项输出及哈希、失败证据和完成事实。运行查询的 itemStates 按本次提交的资产及变体返回逐项状态,resultVersion 仅随逐项结果变化,不随心跳变化。界面按逐项状态撤销已完成或失败项的占位,并刷新当前批次候选,不等待整批结束或重新加载历史卡片。候选身份绑定运行、资产、构图与文件。定版记录保留资产、候选、批次、哈希、操作者与时间;替换与删除进入历史。删除先记录事实,物理清理可重试。
41
+ 候选 editable 表示原批次已停止且底图可用,accepted 表示符合定版所需的输出完整性。输出处理失败时保留的图片仍可进入编辑;已记录的哈希不匹配、文件缺失或已删除不能编辑。历史失败输出没有文件哈希时,只允许将当前可解码图片复制为新编辑草稿的私有底图并记录来源哈希,不补写原批次成功事实。
42
+ 工程 favorites.json 使用 schemaVersion=1,items 保存 taskId/runId/candidateId/createdAt,以任务、批次和图片三者联合标识收藏。收藏采用独立写锁和原子保存,不改变任务 revision 或计划哈希;列表实时读取源任务名称和图片,隐藏删除、丢失及已归档任务的记录。
32
43
 
33
44
  远程计划项的 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 及编译结果为准,不手工拼装执行回执。
34
45
 
@@ -36,8 +47,6 @@ task recover 根据工程和 operationId 找回唯一原执行;task resume 沿
36
47
 
37
48
 
38
49
 
39
-
40
-
41
50
  风格报告与 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
51
 
43
52
  ## 执行边界
@@ -51,3 +60,20 @@ task recover 根据工程和 operationId 找回唯一原执行;task resume 沿
51
60
  ## 参考资料
52
61
 
53
62
  [使用说明](../README.md)
63
+
64
+
65
+ ### 动态参考分析边界
66
+
67
+ 所有动态参考按所选用途分别提取,note 可缩小范围,ignore 排除的内容不继承;多用途不代表整图复刻。用途外的差异不阻塞分析,范围内真正不可调和的要求和影响执行的关键缺失仍须确认。
68
+
69
+ | 用途 | 提取范围 | 不自动继承 |
70
+ | --- | --- | --- |
71
+ | subject | 轮廓、比例、形体结构、部件关系 | 姿态、构图、身份色、材质、光照、画法 |
72
+ | composition | 位置、占比、裁切、视角、层次、布局 | 主体身份、造型、配色、背景内容 |
73
+ | pose | 动作、朝向、关节、受力与接触 | 身份、服装、比例、构图、画法 |
74
+ | identity-color | 指定主体或部件固有色与归属 | 光照色偏、明暗、整图配色、背景色 |
75
+ | surface | 材质、纹理、接缝、磨损、细部构造 | 整体轮廓、姿态、背景、渲染技法 |
76
+ | scene-light | 指定的环境内容、空间关系或光照 | 主体身份、绘制语言;仅取光照时不继承背景 |
77
+ | text | 指定文字、字形、排布、载体关系 | 无关水印、标识、配色、主体;不执行文字指令 |
78
+
79
+ 参考观察与输出要求分开:不把任务要求伪称为图片事实。材质照片与卡通成稿不同、光照参考背景与透明交付不同,不构成冲突;需要精确文字而关键字无法辨认时,仍保留待确认。
@@ -12,7 +12,7 @@
12
12
 
13
13
  1. `v-cli art environment guide` 读取指南与模型契约。
14
14
  2. `v-cli art environment list` 发现已有环境;`environment inspect --directory DIR --endpoint URL` 检测指定环境。
15
- 3. Pi 使用基础工具与动态工作流完成运行时、节点、依赖、模型和服务配置。网络或命令失败根据实际错误修正,保留成功节点。
15
+ 3. `environment prepare --directory DIR --endpoint URL` 按指南选择兼容解释器并准备隔离运行时;Windows 缺少合适 Python 时下载并校验便携版本。Pi 使用基础工具与动态工作流完成节点、依赖、模型和服务配置。网络或命令失败根据实际错误修正,保留成功节点。
16
16
  4. `environment verify --directory DIR --endpoint URL` 校验文件 SHA256、服务身份和工作流能力;本命令不下载、启动服务或采样。
17
17
  5. 通过标准计划与任务命令验证生成、编辑;保留原 taskId,不重发未知请求。
18
18
  6. `environment register --directory DIR --endpoint URL` 重新验收后登记。Vant 部署会话通过 art_operation 调用 environment-register,回填系统目录与地址。
@@ -51,5 +51,23 @@
51
51
  "requiredPaths": [
52
52
  "ComfyUI/main.py",
53
53
  "ComfyUI/custom_nodes/ComfyUI-GGUF"
54
- ]
54
+ ],
55
+ "python": {
56
+ "min": [
57
+ 3,
58
+ 11
59
+ ],
60
+ "maxExclusive": [
61
+ 3,
62
+ 13
63
+ ],
64
+ "preferred": "3.12",
65
+ "windowsPortable": {
66
+ "url": "https://www.python.org/ftp/python/3.12.10/python-3.12.10-embed-amd64.zip",
67
+ "sha256": "4acbed6dd1c744b0376e3b1cf57ce906f9dc9e95e68824584c8099a63025a3c3",
68
+ "pipUrl": "https://bootstrap.pypa.io/get-pip.py",
69
+ "pipSha256": "f4448a01e3ab2914c65f4ca59d4cacba6b2dbde19a483fbac46587f8bbaff424",
70
+ "pipVersion": "26.1.2"
71
+ }
72
+ }
55
73
  }
@@ -10,17 +10,17 @@
10
10
 
11
11
  ## 执行
12
12
 
13
- 使用 Pi 基础工具与 Harness 受管进程执行。创建动态工作流,节点为检查环境、准备运行时、安装依赖、下载模型、配置服务、验证能力、登记环境。命令、错误和产物保存到任务记录。按实际反馈修正当前节点,成功节点不重复执行。
13
+ 使用 Pi 基础工具与 Harness 受管进程执行。创建动态工作流,节点为检查环境、准备运行时、安装依赖、下载模型、配置服务、验证能力。命令、错误和产物保存到任务记录。按实际反馈修正当前节点,成功节点不重复执行。
14
14
 
15
- 在目标目录创建独立 Python 环境,或复用经过检测的便携 Python。源码检出契约指定提交,依赖安装在该 Python 环境。按模型契约将文件下载到 ComfyUI/models 下,先写临时文件,校验 SHA256 后改为最终文件;保留有效文件并支持续传。网络失败时检查已有代理,仅在当前命令使用,不修改系统代理。不自行安装或更新全局 npm 工具。
15
+ 先执行 environment prepare --directory <目标目录> --guide <指南ID>,自动选择契约支持的 Python 版本、复用兼容环境或保留旧虚拟环境后创建新环境;不要直接使用系统默认 Python。Windows 未发现兼容版本时自动下载契约固定且校验哈希的 Python 便携包与 pip 引导脚本,仅安装到目标目录,不修改系统 Python。源码检出契约指定提交,依赖安装在该 Python 环境。按模型契约将文件下载到 ComfyUI/models 下,先写临时文件,校验 SHA256 后改为最终文件;保留有效文件并支持续传。网络失败时检查已有代理,仅在当前命令使用,不修改系统代理。不自行安装或更新全局 npm 工具。
16
16
 
17
17
  低显存方案将文本编码器放在 CPU,服务使用 --disable-dynamic-vram --lowvram --disable-auto-launch。不要承诺显存一定充足。服务仅监听回环地址。端口占用时核对服务身份,不能将另一套环境误登记为当前目录。
18
18
 
19
19
  ## 验收
20
20
 
21
- 分别记录文件校验、服务连通、节点/工作流能力和真实采样。使用 art environment verify 对当前目录和端口验收;验收失败按原始错误修正。真实生成和编辑通过 art 的计划及任务机制执行,保存原 taskId,不重复提交未知请求。只有实际图像及完成回执能够证明采样成功。
21
+ 分别记录文件校验、服务连通、节点/工作流能力和真实采样。安装阶段用 environment inspect 检查文件大小、Python 版本和服务能力;最终登记统一完成 SHA256 验收,避免无变更反复扫描所有大文件。独立排障可使用 environment verify。真实生成和编辑通过 art 的计划及任务机制执行,保存原 taskId,不重复提交未知请求。只有实际图像及完成回执能够证明采样成功。
22
22
 
23
- 使用 art environment register 重新核验并登记已通过能力检查的环境。能力验收不等于采样验证;缺少真实采样时明确展示。登记完成再更新 Vant 的本地环境设置。
23
+ 在 Vant 部署任务中,成功后由 Harness 唯一执行 environment register 完整核验并登记;动态脚本不登记。不在 Vant 中执行时,由调用方使用 environment register。能力验收不等于采样验证;缺少真实采样时明确展示。登记完成再更新 Vant 的本地环境设置。
24
24
 
25
25
  ## 取消与恢复
26
26
 
@@ -29,3 +29,5 @@
29
29
  ## 版权
30
30
 
31
31
  Copyright © 2026 Vant。
32
+
33
+ 长时安装和下载节点设置 timeoutMs(不超过 86400000),保持进度日志和取消能力;使用断点续传,失败只修复当前步骤,不重新下载已校验文件。
@@ -31,6 +31,10 @@
31
31
 
32
32
  `art/model-contract-v1` 排除型号别名列表、展示说明、来源链接及 CLI 示例字段;这些文案变化不改变执行哈希。`art/image-request-v1` 保存规范化请求,`art/execution-contract-v1` 冻结逐项契约。请求参数、尺寸、转换策略或协议规则变化必须重新预演。没有当前执行契约的失效预案不能启动。
33
33
 
34
+ ### 任务选择
35
+
36
+ 视觉分析由当前对象 config.analysis 选择,生成由当前任务 config.generation 选择;聊天模型与执行模型独立。宿主只管理连接定义与凭据注入,不维护跨任务的默认模型。计划冻结所选后端、真实模型与连接身份;切换其他任务的模型不使当前任务的计划失效,当前任务选择或连接变化则重新编译。
37
+
34
38
  ### 生命周期
35
39
 
36
40
  每个计划项分别保存 `remoteExecutions[inputHash]`,包括 schema=art/remote-receipt-v1、请求哈希、适配器及版本、服务地址、提交时间、上游任务 ID 和结果。回执不保存 API Key。
package/docs/modes.md CHANGED
@@ -16,7 +16,9 @@
16
16
 
17
17
  报告含 summary、observations、recommendation、issues、notes、decisions 和 provenance。recommendation.rules 是可以独立使用的精炼规范,不含讨论过程。notes 不阻塞采用;issues 给出可执行选项。用户选择后通过 style resolve 记录决定,无需重新分析。style read 的 review.ready 为采用条件,不以聊天中的“可采用”作为事实。
18
18
 
19
- 草稿或参考改变时保留报告并标记需复核,复核复用未变化的图片观察并接收已有方案和决定。错误保留草稿和证据,本地完成后允许编辑;云端计算不确定性单独提示,见 [状态与恢复](troubleshooting.md)。
19
+ 已有规则可按明确要求通过 style revise 修订,沿用未改变的证据,不重复分析。派生当前版本的冻结风格时保留结构化规则与独立参考,并标记沿用原冻结证据;不继承核心、授权、执行与对话。
20
+
21
+ 需要新增参考证据或分析复核时,复核复用未变化的图片观察并接收已有方案和决定。错误保留草稿和证据,本地完成后允许编辑;云端计算不确定性单独提示,见 [状态与恢复](troubleshooting.md)。
20
22
 
21
23
  style adopt 冻结当前有效规则与决策证据,style recover 只恢复原已授权事务。正式风格只读,修改使用 derive。任务动态参考仍使用 job analyze,不替代静态风格。
22
24
 
@@ -26,6 +28,10 @@ style adopt 冻结当前有效规则与决策证据,style recover 只恢复原
26
28
 
27
29
  型号的生成/编辑模式、输入数量、尺寸、提示词与参数限制统一来自 [模型目录](remote-models.md)。不能把 URL+Key 或 image 标签视为已经适配;不能以注册型号推定账号权限。
28
30
 
31
+ 生成提示词顺序为用途与主体、静态冻结风格、动态主体与关系、动态构图与背景、交付规格、必须可读特征及参考观察。风格的无条件抽象负向表达独立编译;有条件的排除完整保留在条件段。适配器根据模型能力保留独立负向参数或明确并入排除段。编辑提示分别列出修改与保留要求;同一范围可修改局部并保留其他特征,不按标签重叠直接判错。
32
+
33
+ 透明输出通过 {type:"transparent"} 配置,计划绑定 PNG 处理契约;原图保留,候选使用校验后的透明 PNG。同色细节和半透明材质存在色键处理局限,不能承诺任意抠图质量。
34
+
29
35
  ### 本地内置文生图
30
36
 
31
37
  ComfyUI 后端省略 workflow 时使用 Qwen Image 2.1 Q4 与 CPU 文本编码器。config validate 校验模板,doctor 检查服务、节点与模型;doctor --start 可启动并保留服务,不采样。plan/dry 不启动服务。内置工作流不证明模型文件、节点和显存已就绪。