@petercjl/cloud-hug-style-transfer 0.3.1 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 将旧详情页、产品摄影、主 KV 或 SKU 转换为抱抱云朵社品牌视觉，保留当次商品事实、文案与用途。包内包含完整 19 页定稿、品牌标识、人物设定与摄影排版方法，约 41 MB 素材。
 
-支持 Codex、SealSeek、WorkBuddy。需要 Node.js 22+、宿主命令执行和看图能力。生图统一通过必需的 `@petercjl/sealseek-media-cli`（0.6.1+）及其配套 `sealseek-media` Skill 执行；每次任务先检查，缺失或不兼容时暂停整个任务，安装并复查通过后继续。有效 SealSeek 登录、网络及额度由使用者准备，包不附带账号或额度。宿主生图效果仍需分别实测。
+支持 Codex、SealSeek、WorkBuddy。需要 Node.js 22+、宿主命令执行和看图能力。生图统一通过必需的 `@petercjl/sealseek-media-cli`（0.6.1+）及其配套 `sealseek-media` Skill 执行；每次业务任务先检查，缺失或不兼容时暂停整个任务，安装并复查通过后继续。有效 SealSeek 登录、网络及额度由使用者准备，包不附带账号或额度。宿主生图效果仍需分别实测。
 
 先安装生图依赖，将提示词发送给 Agent：
 
@@ -28,7 +28,7 @@
 
 > 请诊断并修复 cloud-hug-style-transfer 的这次报错：粘贴报错内容。
 
-安装、更新与检查由 Agent 执行包内 CLI。包的 `skill source --json` 提供规范来源；Agent 随后调用 `skill install --agent <当前宿主>`，支持 `--root` 指定实际技能目录。普通任务不联网检查或自动更新。显式更新使用 stable latest，备份旧包并同步已登记的受管 Skill，失败时恢复旧包；离线保留当前安装。已有独立安装或本地修改将停止覆盖并报告。源码或上层工具管理的包由其拥有者更新。
+安装、更新与检查由 Agent 执行包内 CLI。包的 `skill source --json` 提供规范来源；Agent 随后调用 `skill install --agent <当前宿主>`，支持 `--root` 指定实际技能目录。普通任务不联网检查或自动更新。显式更新使用 stable latest，备份旧包并同步已登记的受管 Skill；npm 已是最新版时仍修复旧 Skill 与兼容元数据，返回安装位置、来源、校验、备份和耗时。包升级失败时恢复旧包；离线保留当前安装。已有独立安装或本地修改将停止覆盖并报告。源码或上层工具管理的包由其拥有者更新。
 
 兼容证据分别记录安装机制与生图效果。CI 覆盖 macOS、Windows、Linux 的包管理机制；宿主实际生成需使用各自账户独立验证。品牌与输入素材须具备相应使用权；公开 npm 分发不转让商标与素材的独立再分发权。
 

package/capabilities.json

@@ -24,7 +24,7 @@
     "nested_skills": [
       "sealseek-media"
     ],
-    "generation": "Required @petercjl/sealseek-media-cli >=0.6.1 and its canonical sealseek-media Skill; missing or incompatible dependency pauses all tasks before analysis or planning.",
+    "generation": "Required for business planning and generation; maintenance is independent of media service dependencies.",
     "host_capability_skills": {
       "codex": [],
       "sealseek": [],
@@ -70,5 +70,249 @@
     "archive": "none during generation; explicit pair batch after each success",
     "planner": "canvas row --input JSON_FILE --json",
     "recovery": "same canvas/task/row IDs; inspect before replay"
+  },
+  "commandContracts": {
+    "version": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        }
+      },
+      "sideEffects": "none"
+    },
+    "capabilities": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        }
+      },
+      "sideEffects": "none"
+    },
+    "doctor": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--agent": {
+          "type": "string",
+          "enum": [
+            "codex",
+            "sealseek",
+            "workbuddy"
+          ],
+          "description": "Target host; defaults to codex."
+        },
+        "--root": {
+          "type": "string",
+          "description": "Skill parent directory; the CLI appends cloud-hug-style-transfer. Requires --agent on doctor and update."
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill source": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill status": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--agent": {
+          "type": "string",
+          "enum": [
+            "codex",
+            "sealseek",
+            "workbuddy"
+          ],
+          "description": "Target host; defaults to codex."
+        },
+        "--root": {
+          "type": "string",
+          "description": "Skill parent directory; the CLI appends cloud-hug-style-transfer. Requires --agent on doctor and update."
+        }
+      },
+      "sideEffects": "none"
+    },
+    "skill install": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--agent": {
+          "type": "string",
+          "enum": [
+            "codex",
+            "sealseek",
+            "workbuddy"
+          ],
+          "description": "Target host; defaults to codex."
+        },
+        "--root": {
+          "type": "string",
+          "description": "Skill parent directory; the CLI appends cloud-hug-style-transfer. Requires --agent on doctor and update."
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "skill update": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--agent": {
+          "type": "string",
+          "enum": [
+            "codex",
+            "sealseek",
+            "workbuddy"
+          ],
+          "description": "Target host; defaults to codex."
+        },
+        "--root": {
+          "type": "string",
+          "description": "Skill parent directory; the CLI appends cloud-hug-style-transfer. Requires --agent on doctor and update."
+        }
+      },
+      "sideEffects": "local-write"
+    },
+    "update check": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--agent": {
+          "type": "string",
+          "enum": [
+            "codex",
+            "sealseek",
+            "workbuddy"
+          ],
+          "description": "Target host; defaults to codex."
+        },
+        "--root": {
+          "type": "string",
+          "description": "Skill parent directory; the CLI appends cloud-hug-style-transfer. Requires --agent on doctor and update."
+        }
+      },
+      "sideEffects": "none"
+    },
+    "update install": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--agent": {
+          "type": "string",
+          "enum": [
+            "codex",
+            "sealseek",
+            "workbuddy"
+          ],
+          "description": "Target host; defaults to codex."
+        },
+        "--root": {
+          "type": "string",
+          "description": "Skill parent directory; the CLI appends cloud-hug-style-transfer. Requires --agent on doctor and update."
+        },
+        "--yes": {
+          "type": "boolean",
+          "required": true,
+          "description": "Authorize package and managed Skill reconciliation."
+        }
+      },
+      "sideEffects": "package-and-skill-update"
+    },
+    "canvas row": {
+      "options": {
+        "--json": {
+          "type": "boolean",
+          "description": "Machine-readable JSON (also the default)."
+        },
+        "--help": {
+          "type": "boolean",
+          "description": "Read-only help for this command."
+        },
+        "--input": {
+          "type": "string",
+          "required": true,
+          "description": "Comparison input JSON file."
+        }
+      },
+      "sideEffects": "none"
+    }
+  },
+  "maintenance": {
+    "targetPrecedence": [
+      "explicit --root",
+      "host skills directory environment",
+      "Agent home/default"
+    ],
+    "codexSkillsEnvironment": "CODEX_SKILLS_DIR",
+    "defaultUpdateScope": "registered and current-host managed targets; explicit --agent selects one target",
+    "receipt": [
+      "package",
+      "version",
+      "source",
+      "entry",
+      "owner",
+      "packageChanged",
+      "skills",
+      "verified",
+      "backup",
+      "warnings",
+      "timingsMs"
+    ],
+    "sameVersion": "reconcile managed Skills and metadata; verified no-op when current",
+    "metadata": "preserve customization; remove known unsupported api product with backup; unknown invalid schema requires reconciliation"
   }
 }

package/npm/arguments.mjs

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { root, fail } from './runtime.mjs';
+export const manifest=JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8'));
+export function parse(args) {
+ const tokens=[...args];
+ if(tokens[0]==='--version')tokens[0]='version';
+ if(tokens[0]==='help') {tokens.shift();tokens.push('--help');}
+ const words=[];while(tokens.length&&!tokens[0].startsWith('-'))words.push(tokens.shift());
+ const command=words.join(' '), contract=manifest.commandContracts[command];
+ if(!command&&(!tokens.length||tokens.every(x=>['--help','-h','--json'].includes(x))))return {command:'help',options:{}};
+ if(!contract)throw fail('INVALID_COMMAND','Unknown command; use --help.');
+ const options={};
+ while(tokens.length) {
+  let flag=tokens.shift();if(flag==='-h')flag='--help';
+  const spec=contract.options[flag];
+  if(!spec||flag in options)throw fail('INVALID_ARGUMENT',`Unknown or duplicate option ${flag}; use ${command} --help.`);
+  const value=spec.type==='boolean'?true:tokens.shift();
+  if(value===undefined || (spec.type==='string'&&value.startsWith('-')))throw fail('INVALID_ARGUMENT',`${flag} needs a value.`);
+  if(spec.enum&&!spec.enum.includes(value))throw fail('INVALID_AGENT',`Choose ${spec.enum.join(', ')}.`);
+  options[flag]=value;
+ }
+ if(!options['--help']) {
+  for(const [flag,spec]of Object.entries(contract.options))if(spec.required&&!options[flag])throw fail(flag==='--yes'?'PERMISSION_REQUIRED':'INVALID_ARGUMENT',`${command} requires ${flag}.`);
+  if(['doctor','update check','update install'].includes(command)&&options['--root']&&!options['--agent'])throw fail('INVALID_ARGUMENT','--root requires an explicit --agent for this command.');
+ }
+ return {command,options,contract};
+}

package/npm/cli.mjs

@@ -2,44 +2,38 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { root, pkg, fail } from './runtime.mjs';
-import { source, targetPath, status, install, inventory } from './skills.mjs';
-import { checkUpdate, installUpdate } from './update.mjs';
+import { source, resolveTarget, status, install, inventory, skillMetadata } from './skills.mjs';
+import { checkUpdate, installUpdate, globalPrefix } from './update.mjs';
 import { mediaDependency } from './media-dependency.mjs';
 import { comparisonRow } from './canvas-layout.mjs';
-const args=process.argv.slice(2);
-const option=name=>{const i=args.indexOf(name);if(i<0)return undefined;if(!args[i+1]||args[i+1].startsWith('--'))throw fail('INVALID_ARGUMENT',`${name} needs a value.`);return args[i+1];};
+import { parse, manifest } from './arguments.mjs';
+const started=performance.now();
 const out=value=>console.log(JSON.stringify(value,null,2));
 try {
- if(args[0]==='version'||args[0]==='--version') out({ok:true,name:pkg.name,version:pkg.version});
- else if(args[0]==='capabilities') out({...JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8')),version:pkg.version});
- else if(args[0]==='canvas'&&args[1]==='row') {
-  const input=option('--input');if(!input)throw fail('INVALID_ARGUMENT','canvas row requires --input JSON_FILE.');
-  out(comparisonRow(JSON.parse(fs.readFileSync(input,'utf8'))));
- }
- else if(args[0]==='skill') {
-  const action=args[1];
-  if(action==='source')out({ok:true,package:pkg.name,version:pkg.version,source});
-  else {
-   const target=targetPath(option('--agent')||'codex',option('--root'));
-   if(action==='status')out({...status(target),record:undefined});
-   else if(['install','update'].includes(action))out(install(target));
-   else throw fail('INVALID_COMMAND','Use skill source/status/install/update.');
-  }
- } else if(args[0]==='doctor') {
-  const files=inventory(source), expected=JSON.parse(fs.readFileSync(path.join(root,'npm','integrity.json'),'utf8'));
+ const {command,options:o,contract}=parse(process.argv.slice(2));
+ const identity={package:pkg.name,version:pkg.version,source,entry:{node:process.execPath,cli:path.join(root,'npm/cli.mjs')},owner:globalPrefix()?'global-npm':'source-or-parent'};
+ if(command==='help')out({ok:true,...identity,commands:manifest.commandContracts});
+ else if(o['--help'])out({ok:true,command,...contract});
+ else if(command==='version')out({ok:true,name:pkg.name,...identity});
+ else if(command==='capabilities')out({...manifest,...identity});
+ else if(command==='canvas row')out(comparisonRow(JSON.parse(fs.readFileSync(o['--input'],'utf8'))));
+ else if(command==='skill source')out({ok:true,...identity});
+ else if(command.startsWith('skill ')) {
+  const resolution=resolveTarget(o['--agent']||'codex',o['--root']);
+  const result=command==='skill status'?{ok:true,...status(resolution.target),record:undefined}:install(resolution.target);
+  out({...identity,...result,resolution});
+ } else if(command==='doctor') {
+  const files=inventory(source),expected=JSON.parse(fs.readFileSync(path.join(root,'npm/integrity.json'),'utf8'));
   const problems=Object.entries(expected).filter(([name,hash])=>files[name]!==hash).map(([name])=>name);
-  const capabilities=JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8'));
-  const media=mediaDependency();
-  const result={ok:Number(process.versions.node.split('.')[0])>=22&&problems.length===0&&media.ok,package:pkg.name,version:pkg.version,node:process.versions.node,source,files:Object.keys(files).length,integrity:{ok:problems.length===0,problems},installationReady:problems.length===0,dependencies:{media},hostCapabilityDependencies:capabilities.requirements.host_capability_skills,generation:{provider:'@petercjl/sealseek-media-cli',state:media.ok?'requires-live-preflight':'paused',runtimeTested:false,requiredFeatures:['image-inspection','multiple-reference-edit','local-reference-input','viewable-output']}};
+  const media=mediaDependency();const metadata=skillMetadata(source);
+  const result={ok:Number(process.versions.node.split('.')[0])>=22&&!problems.length&&metadata.valid&&media.ok,...identity,node:process.versions.node,files:Object.keys(files).length,integrity:{ok:!problems.length,problems},metadata:{valid:metadata.valid},installationReady:!problems.length&&metadata.valid,dependencies:{media},hostCapabilityDependencies:manifest.requirements.host_capability_skills,generation:{provider:'@petercjl/sealseek-media-cli',state:media.ok?'requires-live-preflight':'paused',runtimeTested:false,requiredFeatures:['image-inspection','multiple-reference-edit','local-reference-input','viewable-output']}};
   if(!media.ok){result.code=media.code;result.action='pause';result.installPrompt=media.installPrompt;}
-  if(option('--agent'))result.installation={...status(targetPath(option('--agent'),option('--root'))),record:undefined};
-  out(result);if(!result.ok)process.exitCode=1;
- } else if(args[0]==='update') {
-  if(!['check','install'].includes(args[1]))throw fail('INVALID_COMMAND','Use update check/install.');
-  if(args[1]==='install'&&!args.includes('--yes'))throw fail('PERMISSION_REQUIRED','Package update requires --yes.');
-  const check=await checkUpdate();
-  if(args[1]==='check'){out(check);if(!check.ok)process.exitCode=1;}
-  else {if(!check.ok)throw fail(check.code,'Registry unavailable; installed version retained.');out(check.updateAvailable?installUpdate(check):{ok:true,changed:false,version:pkg.version});}
- } else if(!args.length||['--help','help','-h'].includes(args[0])) console.log('cloud-hug-style-transfer\nversion | capabilities --json | doctor --json [--agent AGENT]\ncanvas row --input JSON_FILE --json (read-only comparison layout)\nskill source/status/install/update [--agent codex|sealseek|workbuddy] [--root SKILLS_DIRECTORY]\nupdate check | update install --yes\nNode.js 22+. Updates are explicit; business calls never auto-update.');
- else throw fail('INVALID_COMMAND','Unknown command; use --help.');
-} catch(e){out({ok:false,code:e.code||'COMMAND_FAILED',message:e.message});process.exitCode=1;}
+  if(o['--agent']){result.resolution=resolveTarget(o['--agent'],o['--root']);result.installation={...status(result.resolution.target),record:undefined};if(!result.installation.current){result.ok=false;result.code||='SKILL_RECONCILIATION_REQUIRED';}}
+  out({...result,timingsMs:{total:performance.now()-started}});if(!result.ok)process.exitCode=1;
+ } else if(command.startsWith('update ')) {
+  const resolution=o['--agent']?resolveTarget(o['--agent'],o['--root']):undefined;
+  const registryStarted=performance.now();const check=await checkUpdate();const registryMs=performance.now()-registryStarted;
+  if(command==='update check'){out({...check,...identity,...(resolution?{resolution,installation:{...status(resolution.target),record:undefined}}:{}),timingsMs:{total:performance.now()-started}});if(!check.ok)process.exitCode=1;}
+  else {if(!check.ok)throw fail(check.code,'Registry unavailable; installed version retained.');const result=installUpdate(check,{resolution});out({...result,timingsMs:{...result.timingsMs,registry:registryMs,total:performance.now()-started}});}
+ }
+} catch(e){out({ok:false,code:e.code||'COMMAND_FAILED',message:e.message,...(e.causeCode?{causeCode:e.causeCode}:{}),...(e.backup?{backup:e.backup}:{}),...(e.details?{details:e.details}:{}),timingsMs:{total:performance.now()-started}});process.exitCode=1;}

package/npm/integrity.json

@@ -1,9 +1,9 @@
 {
-  "SKILL.md": "4610ef29e4d007d2b37d9c33a0d75be3747c3d7eb541c5ff1b2fd9073ecfa5e2",
+  "SKILL.md": "98df8d4271e525c687a1f0b3e877345bd42f3ca537515c0f84a9c0d58b17612b",
   "adapters/codex.json": "bea8d59e6e0dafae7439693b33356825023516a6f52be02a64c976d7ce47ce76",
   "adapters/sealseek.json": "04ef053762fd4cfc2309573ec87425afad14b2df85a1ea8ef0aa06d98fee1aee",
   "adapters/workbuddy.json": "cd0a1d8d5b9fcebc5a709b8c7523911f41973adb95f71af2c0f644473a43a6b4",
-  "agents/openai.yaml": "8afeabba706e83f2f20d616579e8d79b6509fe93427acdc2b650ef6387049983",
+  "agents/openai.yaml": "d8ebec24c4e3034f4b45aa052b9468ab35790ec7fd93febcfde512c746d2d1d1",
   "assets/approved/all-colors-user-finish.webp": "539c77de8ec0dd46a29793befecf813e97ce6ae66f7cbe69486846383b2ae936",
   "assets/approved/brand-kv-user-finish-20261012.png": "cb09198481e779444696864b265c689f467207bf7de9610f7adc2b850f0be7b4",
   "assets/approved/detail-final-20261016/01.jpg": "ecb481a422b3eadb0050b8c1080a1781e3fbd50ce4479f92e9f4a8beffd91187",
@@ -62,6 +62,7 @@
   "references/cases.md": "9d0d2d3d210e367411d5a291fc78ef6c9c733afd79c9da76451c580fcbcd4d3e",
   "references/detail-final-20261016.md": "d9311413420db743466bbecfe98c31b9753eeead905472d69839afec9578c557",
   "references/kv-layout-case-20261012.md": "845b287cfc57912aabedc48e558ca661cf86bf136304ea841030205a806ef06f",
+  "references/maintenance.md": "ccaa22cbe537885c7936d76b9091ef681491fd75d3791f6dbcf803d2337cee8e",
   "references/model-generation.json": "21daa2c3bf7d2000c7ddf52ab0b980cb7ee95d6c9d345602dc59ecbc128ec147",
   "references/model.md": "c4da688e22e2ada3f251fe0dc87effcaf5cb6ed6176f9d9c20a9661414bffab5",
   "references/page-patterns.md": "bdd6756e303c95e432d0239be27ec5af1faf75abf71594917f2e11467255a1b4",

package/npm/metadata.mjs

@@ -0,0 +1,18 @@
+import { parseDocument } from 'yaml';
+import { fail } from './runtime.mjs';
+const allowed=new Set(['chatgpt','codex','atlas','CHATGPT','CODEX','ATLAS']);
+export function metadataPlan(text) {
+ const doc=parseDocument(text,{uniqueKeys:true});
+ if(doc.errors.length)throw fail('SKILL_METADATA_INVALID','Invalid agents/openai.yaml; preserve and repair the YAML before updating.');
+ const value=doc.toJS();
+ if(!value||typeof value!=='object'||Array.isArray(value))throw fail('SKILL_METADATA_INVALID','Skill metadata must be a mapping.');
+ if(value.interface!==undefined&&(!value.interface||typeof value.interface!=='object'||Array.isArray(value.interface)||Object.values(value.interface).some(v=>typeof v!=='string')))throw fail('SKILL_METADATA_INVALID','Skill interface values must be strings.');
+ if(value.policy!==undefined&&(!value.policy||typeof value.policy!=='object'||Array.isArray(value.policy)))throw fail('SKILL_METADATA_INVALID','Skill policy must be a mapping.');
+ const policy=value.policy;
+ if(policy?.allow_implicit_invocation!==undefined&&typeof policy.allow_implicit_invocation!=='boolean')throw fail('SKILL_METADATA_INVALID','allow_implicit_invocation must be boolean.');
+ const products=policy?.products;
+ if(products!==undefined&&(!Array.isArray(products)||products.some(p=>!allowed.has(p)&&p!=='api')))throw fail('SKILL_METADATA_INVALID','Unsupported policy.products; preserve and resolve the custom policy before updating.');
+ const changed=products?.includes('api')||false;
+ if(changed){const valid=products.filter(p=>p!=='api');if(!valid.length)throw fail('SKILL_METADATA_INVALID','Removing api would leave an empty custom product policy.');doc.setIn(['policy','products'],valid);}
+ return {valid:!changed,changed,text:changed?doc.toString():text,warnings:changed?['Removed unsupported legacy api product; custom interface and other policy fields preserved.']:[]};
+}

package/npm/pack.mjs

@@ -0,0 +1,8 @@
+import path from 'node:path';
+import { pkg, fail } from './runtime.mjs';
+export function packReceipt(text) {
+ let value;try{value=JSON.parse(text);}catch{throw fail('UPDATE_BACKUP_FAILED','npm pack did not return valid JSON.');}
+ const receipt=Array.isArray(value)&&value.length===1?value[0]:value?.[pkg.name];
+ if(!receipt||typeof receipt.filename!=='string'||!receipt.filename.endsWith('.tgz')||receipt.filename.includes('\\')||path.basename(receipt.filename)!==receipt.filename||(receipt.name&&receipt.name!==pkg.name))throw fail('UPDATE_BACKUP_FAILED','Invalid npm pack receipt.');
+ return receipt;
+}

package/npm/skills.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { metadataPlan } from './metadata.mjs';
 import { stateRoot } from './update.mjs';
 import { root, pkg, fail } from './runtime.mjs';
 
@@ -23,14 +24,19 @@ export function inventory(dir) {
   walk(dir);
   return result;
 }
-export function targetPath(agent, targetRoot) {
+export function resolveTarget(agent='codex', targetRoot) {
   if (!['codex', 'sealseek', 'workbuddy'].includes(agent)) throw fail('INVALID_AGENT', 'Choose --agent codex, sealseek or workbuddy.');
-  let base = targetRoot;
-  if (!base && agent === 'codex') base = path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'skills');
-  if (!base && agent === 'sealseek') base = process.env.SEALSEEK_SKILLS_DIR || path.join(os.homedir(), '.sealseek', 'workspaces', 'default', 'skills');
-  if (!base && agent === 'workbuddy') base = process.env.WORKBUDDY_SKILLS_DIR || path.join(os.homedir(), '.workbuddy', 'skills');
-  if (!base) throw fail('AGENT_PATH_REQUIRED', 'Provide the actual SealSeek skills directory through --root or SEALSEEK_SKILLS_DIR.');
-  return path.join(path.resolve(base), 'cloud-hug-style-transfer');
+  const envName={codex:'CODEX_SKILLS_DIR',sealseek:'SEALSEEK_SKILLS_DIR',workbuddy:'WORKBUDDY_SKILLS_DIR'}[agent];
+  const homeBase=agent==='codex' ? path.join(process.env.CODEX_HOME || path.join(os.homedir(),'.codex'),'skills') : agent==='sealseek' ? path.join(os.homedir(),'.sealseek','workspaces','default','skills') : path.join(os.homedir(),'.workbuddy','skills');
+  const candidates=[targetRoot&&{source:'--root',root:targetRoot},process.env[envName]&&{source:envName,root:process.env[envName]},{source:agent==='codex'&&process.env.CODEX_HOME?'CODEX_HOME':'agent-default',root:homeBase}].filter(Boolean).map(v=>({...v,root:path.resolve(v.root)}));
+  const selected=candidates[0];
+  return {agent,target:path.join(selected.root,'cloud-hug-style-transfer'),root:selected.root,resolvedFrom:selected.source,candidates,warnings:[...new Set(candidates.filter(c=>c.root!==selected.root).map(c=>`${selected.source} takes precedence over ${c.source}.`))]};
+}
+export const targetPath=(agent,targetRoot)=>resolveTarget(agent,targetRoot).target;
+export function skillMetadata(target) {
+  const file=path.join(target,metadata);
+  if(!exists(file))return {valid:false,changed:false,missing:true,warnings:['Skill UI metadata is missing.']};
+  return metadataPlan(fs.readFileSync(file,'utf8'));
 }
 export function status(target) {
   const st = exists(target);
@@ -43,18 +49,21 @@ export function status(target) {
   const files = inventory(target);
   const edited = Object.entries(record.files).some(([file, hash]) => file !== metadata && files[file] !== hash);
   const expected = inventory(source);
-  const current = !edited && Object.entries(expected).every(([file, hash]) => file === metadata || files[file] === hash);
-  return { installed: true, managed: true, current, edited, target, version: record.version, record };
+  const ui=skillMetadata(target);
+  const current = record.version === pkg.version && ui.valid && !edited && Object.entries(expected).every(([file, hash]) => file === metadata || files[file] === hash);
+  return { installed: true, managed: true, current, edited, target, version: record.version, metadata:{valid:ui.valid,migrationRequired:ui.changed,warnings:ui.warnings}, record };
 }
 export function install(target) {
-  const state = status(target);
+  const started=performance.now();
+  let state = status(target);
   if (state.installed && !state.managed) throw fail('SKILL_UNMANAGED', 'An existing user-owned Skill occupies this target; preserve it and choose a new root or explicitly migrate it.');
   if (state.edited) throw fail('SKILL_EDITED', 'Managed Skill files contain local edits; preserve and reconcile those edits before updating.');
   const registry = path.join(stateRoot(), 'skill-targets');
   fs.mkdirSync(registry, { recursive: true });
   const registration = path.join(registry, crypto.createHash('sha256').update(target).digest('hex') + '.json');
   if (!exists(registration)) fs.writeFileSync(registration, JSON.stringify({ target }), { flag: 'wx', mode: 0o600 });
-  if (state.current && state.version === pkg.version) return { ...state, record: undefined, ok: true, changed: false };
+  const receipt={package:pkg.name,source,owner:'package-managed',verified:true};
+  if (state.current && state.version === pkg.version) return { ...state, record: undefined, ...receipt, ok: true, changed: false, timingsMs:{total:performance.now()-started} };
   const expected = inventory(source);
   for (const file of Object.keys(expected)) {
     if (state.installed && exists(path.join(target, file)) && !(file in state.record.files) && file !== metadata) throw fail('SKILL_UNMANAGED_FILE', 'A new bundled file would overwrite a user-owned file.');
@@ -65,6 +74,11 @@ export function install(target) {
   try { lockfd = fs.openSync(lock, 'wx', 0o600); } catch (e) { if (e.code === 'EEXIST') throw fail('SKILL_BUSY', 'Another Skill installation holds the lock.'); throw e; }
   let backup;
   try {
+    state=status(target);
+    if(state.installed&&!state.managed)throw fail('SKILL_UNMANAGED','Target ownership changed while waiting for the lock.');
+    if(state.edited)throw fail('SKILL_EDITED','Target changed while waiting for the lock.');
+    for(const file of Object.keys(expected))if(state.installed&&exists(path.join(target,file))&&!(file in state.record.files)&&file!==metadata)throw fail('SKILL_UNMANAGED_FILE','Target file ownership changed before the lock.');
+    const ui=state.installed?skillMetadata(target):null;
     if (state.installed) {
       backup = path.join(stateRoot(), 'skill-backups', crypto.randomUUID());
       fs.mkdirSync(path.dirname(backup), { recursive: true });
@@ -72,7 +86,7 @@ export function install(target) {
     } else fs.mkdirSync(target);
     // In-place updates support hosts holding a directory handle open. Backup is recoverable.
     for (const file of Object.keys(expected)) {
-      if (file === metadata && exists(path.join(target, file))) continue;
+      if (file === metadata && exists(path.join(target, file))) { if(ui.changed)fs.writeFileSync(path.join(target,file),ui.text); continue; }
       fs.mkdirSync(path.dirname(path.join(target, file)), { recursive: true });
       fs.copyFileSync(path.join(source, file), path.join(target, file));
     }
@@ -81,9 +95,10 @@ export function install(target) {
     }
     const actual = inventory(target);
     if (Object.entries(expected).some(([file, hash]) => file !== metadata && actual[file] !== hash)) throw fail('SKILL_VERIFY_FAILED', 'Installed Skill hashes differ from the package.');
+    if(!skillMetadata(target).valid)throw fail('SKILL_VERIFY_FAILED','Skill UI metadata validation failed.');
     fs.writeFileSync(path.join(target, marker), JSON.stringify({ package: pkg.name, version: pkg.version, files: expected }, null, 2));
-    return { ok: true, installed: true, managed: true, current: true, changed: true, target, version: pkg.version, backup: backup || null };
+    return { ...receipt, metadata:{valid:true,migrated:ui?.changed||false}, warnings:ui?.warnings||[], timingsMs:{total:performance.now()-started}, ok: true, installed: true, managed: true, current: true, changed: true, target, version: pkg.version, backup: backup || null };
   } catch (e) {
-    throw fail('SKILL_INSTALL_FAILED', `Skill installation failed; ${backup ? 'restore from ' + backup : 'inspect the partial target at ' + target}.`);
+    throw Object.assign(fail('SKILL_INSTALL_FAILED', `Skill installation failed; ${backup ? 'restore from ' + backup : 'inspect the partial target at ' + target}.`),{causeCode:e.code,backup:backup||null,target});
   } finally { fs.closeSync(lockfd); fs.unlinkSync(lock); }
 }

package/npm/update.mjs

@@ -3,6 +3,8 @@ import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
+import { packReceipt } from './pack.mjs';
+import { source, resolveTarget, status } from './skills.mjs';
 import { root, pkg, fail } from './runtime.mjs';
 
 export const stateRoot = () => process.env.CLOUD_HUG_STATE_DIR || (process.platform === 'win32' ? path.join(process.env.LOCALAPPDATA || os.homedir(), 'cloud-hug-style-transfer') : path.join(os.homedir(), '.local', 'state', 'cloud-hug-style-transfer'));
@@ -40,45 +42,58 @@ function npm(args) {
   return r.stdout;
 }
 export function installUpdate(check, services={}) {
-  const prefix=services.prefix || globalPrefix();
-  if(!prefix) throw fail('UPDATE_OWNER_REQUIRED','This installation is managed by its source checkout or parent package.');
-  const state=stateRoot(); fs.mkdirSync(state,{recursive:true});
+  if(!check.ok)throw fail(check.code||'REGISTRY_UNAVAILABLE','Registry check failed; installation retained.');
+  const started=performance.now(), prefix=services.prefix || globalPrefix();
+  const state=stateRoot();fs.mkdirSync(state,{recursive:true});
   const lock=path.join(state,'update.lock');
-  try { fs.mkdirSync(lock); } catch { throw fail('UPDATE_BUSY','Another update is running. Retry this command after it finishes.'); }
-  const run=services.npm || npm, spawn=services.spawn || spawnSync;
-  const backup=path.join(state,'package-backups',crypto.randomUUID());
-  const targets=[];
+  try {fs.mkdirSync(lock);}catch{throw fail('UPDATE_BUSY','Another update is running. Retry after it finishes.');}
+  const run=services.npm||npm, spawn=services.spawn||spawnSync;
+  const entry=path.join(root,'npm','cli.mjs'), targets=[], skills=[];
+  const sync=target=>{
+    const r=spawn(process.execPath,[entry,'skill','update','--agent',target.agent||'codex','--root',path.dirname(target.target),'--json'],{encoding:'utf8',timeout:30000,env:{...process.env,CLOUD_HUG_AUTO_UPDATE:'0'}});
+    let receipt;try{receipt=JSON.parse(r.stdout);}catch{/* malformed receipt is a failure */}
+    if(r.status!==0||!receipt?.ok||!receipt.current||!receipt.verified)throw Object.assign(fail('SKILL_SYNC_FAILED','Managed Skill reconciliation failed.'),{details:{target:target.target,result:receipt||null}});
+    return {...receipt,resolution:target};
+  };
+  let archivePath,mutated=false,version;
   try {
-    // Recheck the live package under the lock; another process may have updated it.
     const live=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8'));
-    if(!newer(check.available,live.version)) return {ok:true,changed:false,version:live.version};
-    fs.mkdirSync(backup,{recursive:true});
-    const archive=JSON.parse(run(['pack',root,'--ignore-scripts','--pack-destination',backup,'--json']))[0];
-    const registered=path.join(state,'skill-targets');
-    const known=[path.join(process.env.CODEX_HOME || path.join(os.homedir(),'.codex'),'skills','cloud-hug-style-transfer')];
-    for(const f of (fs.existsSync(registered) ? fs.readdirSync(registered) : [])) {
-      try { known.push(JSON.parse(fs.readFileSync(path.join(registered,f),'utf8')).target); } catch { /* invalid registration */ }
-    }
-    for(const target of new Set(known)) {
-      try { if(JSON.parse(fs.readFileSync(path.join(target,'.cloud-hug-style-transfer-managed.json'),'utf8')).package===pkg.name) targets.push(target); } catch { /* unmanaged or absent */ }
+    const packageChanged=newer(check.available,live.version);
+    if(packageChanged&&!prefix)throw fail('UPDATE_OWNER_REQUIRED','This installation is managed by its source checkout or parent package.');
+    if(services.resolution)targets.push(services.resolution);
+    else {
+      const known=[resolveTarget('codex'),resolveTarget('sealseek'),resolveTarget('workbuddy')];
+      const registered=path.join(state,'skill-targets');
+      for(const file of fs.existsSync(registered)?fs.readdirSync(registered):[]) {
+        try{const r=JSON.parse(fs.readFileSync(path.join(registered,file),'utf8'));if(typeof r.target==='string'&&path.isAbsolute(r.target)&&path.basename(r.target)==='cloud-hug-style-transfer')known.push({target:r.target,resolvedFrom:'managed-registration'});}catch{/* invalid registration is ignored */}
+      }
+      for(const r of known)if(!targets.some(t=>t.target===r.target)&&status(r.target).managed)targets.push(r);
     }
-    const entry=path.join(root,'npm','cli.mjs');
-    const sync=target=>spawn(process.execPath,[entry,'skill','update','--root',path.dirname(target)],{encoding:'utf8',timeout:30000,env:{...process.env,CLOUD_HUG_AUTO_UPDATE:'0'}});
-    let mutated=false;
-    try {
+    // Ownership, local edits and metadata conflicts are checked before replacing the package.
+    for(const t of targets){const s=status(t.target);if(s.installed&&!s.managed)throw fail('SKILL_UNMANAGED','Selected Skill is user-owned.');if(s.edited)throw fail('SKILL_EDITED','Managed Skill contains local edits; reconcile before updating.');}
+    const preflightMs=performance.now()-started;
+    if(packageChanged) {
+      const backup=path.join(state,'package-backups',crypto.randomUUID());fs.mkdirSync(backup,{recursive:true});
+      const archive=packReceipt(run(['pack',root,'--ignore-scripts','--pack-destination',backup,'--json']));
+      if(!archive?.filename||path.basename(archive.filename)!==archive.filename)throw fail('UPDATE_BACKUP_FAILED','Invalid package backup receipt.');
+      archivePath=path.join(backup,archive.filename);
+      if(!fs.statSync(archivePath).size)throw fail('UPDATE_BACKUP_FAILED','Package backup is empty.');
       mutated=true;
       run(['install','--global','--prefix',prefix,'--prefer-online','--ignore-scripts','--no-audit','--no-fund',`${pkg.name}@${check.available}`]);
-      const version=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8')).version;
-      if(version!==check.available) throw fail('UPDATE_VERIFY_FAILED','Installed package version mismatch.');
-      for(const target of targets) if(sync(target).status!==0) throw fail('SKILL_SYNC_FAILED','A managed Skill needs reconciliation.');
-      return {ok:true,changed:true,from:pkg.version,version,backup:path.join(backup,archive.filename)};
-    } catch(e) {
-      if(mutated) {
-        try { run(['install','--global','--prefix',prefix,'--ignore-scripts',path.join(backup,archive.filename)]); }
-        catch { throw fail('ROLLBACK_REQUIRED','Automatic recovery failed; restore the package archive before running commands.'); }
-        for(const target of targets) if(sync(target).status!==0) throw fail('ROLLBACK_SYNC_REQUIRED','Package restored; reconcile edited Skill files before updating.');
-      }
-      throw e;
     }
-  } finally { fs.rmdirSync(lock); }
+    version=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8')).version;
+    if(version!==(packageChanged?check.available:live.version))throw fail('UPDATE_VERIFY_FAILED','Installed package version mismatch.');
+    const packageMs=performance.now()-started-preflightMs;
+    for(const t of targets)skills.push(sync(t));
+    if(skills.some(r=>r.version!==version))throw fail('SKILL_VERIFY_FAILED','Package and Skill versions differ.');
+    return {ok:true,package:pkg.name,source,entry:{node:process.execPath,cli:entry},owner:prefix?'global-npm':'source-or-parent',from:live.version,version,packageChanged,changed:packageChanged||skills.some(r=>r.changed),skills,verified:true,backup:archivePath||null,warnings:targets.length?[]:['No managed Skill target discovered; use an explicit --agent to install one.'],timingsMs:{preflight:preflightMs,package:packageMs,skills:performance.now()-started-preflightMs-packageMs,total:performance.now()-started}};
+  } catch(e) {
+    if(mutated) {
+      try{run(['install','--global','--prefix',prefix,'--ignore-scripts',archivePath]);const restored=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8')).version;if(restored!==pkg.version)throw Error('Rollback version mismatch');}
+      catch{throw Object.assign(fail('ROLLBACK_REQUIRED','Restore the package archive before continuing.'),{backup:archivePath});}
+      for(const t of targets)try{sync(t);}catch{throw Object.assign(fail('ROLLBACK_SYNC_REQUIRED','Package restored; restore affected Skill backups or reconcile local edits.'),{backup:archivePath,details:{skills,cause:e.details||e.message}});}
+    }
+    if(archivePath)e.backup=archivePath;
+    throw e;
+  } finally {fs.rmdirSync(lock);}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/cloud-hug-style-transfer",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "抱抱云朵社品牌风格转换 Skill，支持 Codex、SealSeek 与 WorkBuddy",
   "type": "module",
   "bin": {
@@ -18,7 +18,7 @@
   },
   "scripts": {
     "test": "node --test test/*.test.mjs",
-    "check": "node --check npm/cli.mjs && node --check npm/skills.mjs && node --check npm/update.mjs",
+    "check": "node --check npm/cli.mjs && node --check npm/skills.mjs && node --check npm/update.mjs && node --check npm/arguments.mjs && node --check npm/metadata.mjs && node --check npm/pack.mjs",
     "prepack": "npm run check && npm test"
   },
   "publishConfig": {
@@ -28,5 +28,8 @@
     "type": "git",
     "url": "git+https://github.com/petercjl/cloud-hug-style-transfer.git"
   },
-  "license": "UNLICENSED"
+  "license": "UNLICENSED",
+  "dependencies": {
+    "yaml": "^2.9.1"
+  }
 }

package/skills/cloud-hug-style-transfer/SKILL.md

@@ -11,9 +11,13 @@ description: 独立把旧详情页、产品摄影、主KV或SKU转换为抱抱
 
 输入是当前源页、商品资料和本次目标；输出是约定数量的独立成图、原图与成图逐行对照的无限画板及简短验收说明，或用户仅要求的规划。本 Skill 负责品牌方法、素材选择、提示词、版式和业务验收；`@petercjl/sealseek-media-cli` 负责生图服务、认证、参考图传输、任务恢复和结果下载；宿主负责命令执行、实际看图和交付。
 
+### 维护入口：安装、更新和诊断
+
+维护请求先执行本入口；业务规划与生图进入下面的必需依赖检查。维护只读取包合同与安装状态，按需加载 [维护说明](references/maintenance.md)，无需加载品牌图片或生图服务。
+
 ### 入口：必需依赖检查
 
-**每次任务先检查依赖，通过后才进入第 1 节；规划任务也遵守此入口。** 执行 `cloud-hug-style-transfer doctor --json`，核对 `dependencies.media.ok`。检查支持当前 npm 安装树、PATH 安装及显式配置的 `CLOUD_HUG_MEDIA_ROOT`；返回的 `dependencies.media.invocation` 是经过包身份核验的 CLI 调用入口，使用宿主当前 Node 运行时，可用于 Agent 管理的运行时或套件组件。
+**每次业务任务先检查依赖，通过后才进入第 1 节；规划任务也遵守此入口。** 执行 `cloud-hug-style-transfer doctor --json`，核对 `dependencies.media.ok`。检查支持当前 npm 安装树、PATH 安装及显式配置的 `CLOUD_HUG_MEDIA_ROOT`；返回的 `dependencies.media.invocation` 是经过包身份核验的 CLI 调用入口，使用宿主当前 Node 运行时，可用于 Agent 管理的运行时或套件组件。
 
 未检测到 `@petercjl/sealseek-media-cli` 时返回 `DEPENDENCY_MISSING` 并**暂停整个任务**，保留输入和进度，给出最简安装提示词：“请安装 npm 包 @petercjl/sealseek-media-cli。”等待安装并重新检查通过后，从本入口恢复。版本低于 0.6.1、CLI 无法执行、规范 Skill 缺失或合同不兼容同样暂停，按诊断修复后复查。不得以宿主内置生图、其他提供商或继续规划代替依赖通过；本入口不自动安装软件或提交生成。
 

package/skills/cloud-hug-style-transfer/agents/openai.yaml

@@ -8,6 +8,5 @@ policy:
   products:
   - chatgpt
   - codex
-  - api
   - atlas
   allow_implicit_invocation: true

package/skills/cloud-hug-style-transfer/references/maintenance.md

@@ -0,0 +1,9 @@
+# 安装与维护合同
+
+1. 通过当前 CLI 的 `capabilities --json` 获取参数合同；用 `skill source --json` 定位规范 Skill。首次安装执行 `skill install --agent 当前宿主 --json`。
+2. 显式更新执行 `update install --yes --json`，在默认范围核对已登记和当前宿主约定位置的受管 Skill；仅更新一个宿主时传 `--agent`。npm 已最新时仍同步旧 Skill 与可迁移元数据。源码或上层工具拥有的包由其拥有者升级；当前版本的 Skill 同步仍可执行。
+3. 需要指定位置时，`--root` 是技能父目录，CLI 自动附加本 Skill 目录名；`doctor` 与 `update` 的 `--root` 同时要求 `--agent`。Codex 优先级为显式 root、`CODEX_SKILLS_DIR`、`CODEX_HOME/skills`、平台默认；其他宿主见实时合同及回执。读取 resolution 核对目标与来源。
+4. 检查回执 `verified`、`packageChanged`、各 `skills` 的 `current/version/target` 和备份。完全当前即 verified no-op。未知参数报错后读取该命令的 `--help --json`；避免猜其他工具的选项。
+5. 本地编辑或非受管目录保留原文件并报告。失败时保留回执中的 backup；先检查包版本与受管状态，再按错误恢复，避免重复升级。元数据只迁移已知不受支持的字段值，自定义展示字段保留。
+
+`doctor --json` 同时报告安装完整性与生图依赖；媒体依赖缺失不阻止独立的 `skill` 或 `update` 维护操作。普通业务任务不自动更新。