@petercjl/product-asset-set 0.0.0-stage → 0.1.1

package/INSTALL.md

@@ -0,0 +1,5 @@
+# 安装
+
+> 请安装 `@petercjl/product-asset-set` 提供的 Skill。
+
+当前 Agent 从 npm 获取并核对指定版本，读取包内 `skills/product-asset-set/SKILL.md`。按自身支持的安装及注册方式，将该目录和全部资源实体复制到自己的 Skill 环境。保留已存在的非受管文件和本地改动，安装后核对版本、文件哈希与实际加载状态。运行本地校验工具需要 Node.js 22 或更新版本。图像执行能力以 Skill 的能力声明为准。

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# product-asset-set
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build reusable product reference image sets.
+
+请把下面的提示词交给当前使用的 Agent。
+
+> 请安装 `@petercjl/product-asset-set` 提供的 Skill。
+
+[安装说明](INSTALL.md) · [更新说明](UPDATE.md)

package/UPDATE.md

@@ -0,0 +1,5 @@
+# 更新
+
+> 请检查并更新 `@petercjl/product-asset-set` 提供的 Skill。
+
+当前 Agent 先定位自己的已安装副本，再从 npm 获取稳定版本。保留可恢复备份，核对包版本和资源，更新同一个实体安装，即使版本相同也检查资源是否完整。按自身机制刷新注册，验证已加载版本与文件哈希；有本地编辑时先保留编辑，再处理冲突。

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@petercjl/product-asset-set",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Build reusable product reference image sets.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/petercjl/product-asset-set.git"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "skills",
+    "INSTALL.md",
+    "UPDATE.md",
+    "scripts/verify-package.mjs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "agentPackage": {
+    "kind": "application-skill",
+    "skills": [
+      {
+        "name": "product-asset-set",
+        "path": "skills/product-asset-set"
+      }
+    ],
+    "installation": "host-managed-physical-copy",
+    "installGuide": "INSTALL.md",
+    "updateGuide": "UPDATE.md"
+  },
+  "scripts": {
+    "check": "node scripts/verify-package.mjs",
+    "prepack": "node scripts/verify-package.mjs",
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/scripts/verify-package.mjs

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict';
+import {readFileSync, readdirSync, lstatSync} from 'node:fs';
+import {join} from 'node:path';
+import {spawnSync} from 'node:child_process';
+
+const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
+const [skill] = pkg.agentPackage.skills;
+assert.equal(pkg.agentPackage.skills.length, 1);
+assert.equal(pkg.name, '@petercjl/' + skill.name);
+assert.equal(skill.path, 'skills/' + skill.name);
+assert.match(readFileSync(join(skill.path, 'SKILL.md'), 'utf8'), new RegExp('^---\\nname: ' + skill.name + '\\n'));
+assert.equal(JSON.parse(readFileSync(join(skill.path, 'capabilities.json'), 'utf8')).skill, skill.name);
+for (const path of ['INSTALL.md', 'UPDATE.md']) assert.ok(readFileSync(path, 'utf8').includes(pkg.name));
+function verifyTree(directory) {
+  for (const name of readdirSync(directory)) {
+    const path = join(directory, name);
+    const stat = lstatSync(path);
+    assert.ok(stat.isFile() || stat.isDirectory(), 'Expected a physical file or directory: ' + path);
+    if (stat.isDirectory()) verifyTree(path);
+  }
+}
+verifyTree(skill.path);
+const result = spawnSync(process.execPath, ['--check', join(skill.path, 'scripts', 'asset-guide.mjs')], {stdio:'inherit'});
+assert.equal(result.status, 0);

package/skills/product-asset-set/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: product-asset-set
+description: 从产品原图、使用场景或详情页制作可复用的独立高清产品参考图组，交付资产说明.txt，支持逐张验收、修订和定稿。
+---
+
+# 产品资产生成
+
+输入是产品资料、可选的指定款色与形态基准。交付一个版本目录，包含独立高清 PNG 和一份 UTF-8 `资产说明.txt`。Agent 根据每张图的产品自然形态、拍摄角度和证据用途独立选择画幅，同一图组可同时包含横图、竖图和方图。用户明确指定的尺寸优先；与关键证据完整性冲突时说明取舍并确认。结束时提供版本目录、各图链接及用途；若用户想继续替换，提示另行提供目标场景和这套资产。
+
+1. **核对来源与形态。** 逐个打开实际文件，记录路径、编号、哈希和观察。每个查看结果与同次调用的文件标识绑定；文件名与描述冲突时，单独重开该文件核实。详情页查看全部商品相关区域，必要时按原像素裁切。比较轮廓、比例和可见结构，区分透视、遮挡与正常受压。如果有真实冲突或无法排除冲突，展示对应原图，等待用户指定基准对象；已有明确选择则复用。记录基准与相关素材各自的证据职责。
+2. **规划独立图片。** 至少包含一张完整全貌（`overall`）和一张有可辨参照物或人物的相对尺度（`scale`）。按新增证据规划 `structure`、`texture`、`marking` 或 `use`。同一用途优先留最清楚的一张。为每张分配稳定编号，列出画幅、目标尺寸、选择理由、证据来源、保留内容、编辑范围和验收点。先确定产品与必要参照物的自然朝向，再选择能完整容纳主体且主体占比足够的画幅。横向长条产品全貌优先评估 16:9 或 3:2，竖向产品或人物使用图优先评估 3:4、2:3 或 9:16，紧凑全貌和局部细节可用 1:1 或 4:3；按实际内容选择。产品的摆放、姿态和比例服从原始参考，避免为了适配画幅而旋转成长对角线、悬浮或改变产品形态。源图缺少必要证据时请求补图，可交付清楚标明缺口的阶段性预览。
+3. **先全貌，再逐张制作。** 优先用原照片和原人物、动作、场景。需要生成时，发现当前宿主的参考图编辑能力，核对所选画幅、服务支持的尺寸和费用，按授权每次生成一张。先对照原始基准验收全貌，再做依赖该全貌的图片。使用场景图由原图提供人物和使用关系，产品身份由基准参考提供。提示词聚焦构图和必要编辑，产品结构与材质服从参考。记录每张实际输出尺寸和比例。实际比例与计划略有偏差时，先看完整性与主体可读性；需要精确比例时仅采用保留关键证据的等比整理。逐张查看真实结果，验收身份、用途、清晰度和主体占比。每次调用记录原始输入、请求、可用的真实任务标识和结果；未知提交先查原任务。
+4. **打包、修订和定稿。** 按 [资产交接协议](references/asset-format.md) 构建说明并检查每个文件。技术验收通过后交给用户确认。局部修订创建新版本目录，复用其余已通过原件并比对哈希，只改对应编号与说明；更改形态基准时重新核对受影响图片。定稿依据为用户真实确认，记录在资产交付目录外。
+
+运行记录随项目保存，依次记录来源核对、图片计划、各编号的制作及验收、交付及确认。保留失败图与历史版本，展示给用户时提供每个业务阶段的结果和可打开的证据。

package/skills/product-asset-set/adapters/generic.json

@@ -0,0 +1,36 @@
+{
+  "schema": "portable-skill-adapter",
+  "platform": "generic",
+  "mappings": [
+    {
+      "capability_id": "asset.guide",
+      "status": "implemented",
+      "features": [
+        "verify-file-hashes",
+        "verify-png-dimensions"
+      ],
+      "implementation": {
+        "type": "node-script",
+        "path": "scripts/asset-guide.mjs",
+        "command": "check",
+        "runtime": "Node.js 22+"
+      }
+    },
+    {
+      "capability_id": "media.image.edit",
+      "status": "implemented",
+      "features": [
+        "ordered-references",
+        "one-image",
+        "local-artifact"
+      ],
+      "implementation": {
+        "type": "host-discovery",
+        "discovery": "Resolve the current host advertised image editing capability and verify required features before invocation.",
+        "on_missing": "CAPABILITY_UNAVAILABLE",
+        "on_unsupported": "FEATURE_UNSUPPORTED",
+        "output": "Return a local image and actual invocation or task receipt when exposed."
+      }
+    }
+  ]
+}

package/skills/product-asset-set/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "产品资产生成"
+  short_description: "Build reusable product reference image sets"

package/skills/product-asset-set/capabilities.json

@@ -0,0 +1,54 @@
+{
+  "schema": "portable-skill-capabilities",
+  "schema_version": "1.0.0",
+  "skill": "product-asset-set",
+  "target_platforms": [
+    "generic"
+  ],
+  "capabilities": [
+    {
+      "id": "asset.guide",
+      "purpose": "Validate the portable asset handoff",
+      "required": true,
+      "required_features": [
+        "verify-file-hashes",
+        "verify-png-dimensions"
+      ],
+      "input_fields": [
+        "guide"
+      ],
+      "output_fields": [
+        "verified-assets"
+      ],
+      "side_effects": {
+        "external_mutation": false,
+        "may_cost_money": false,
+        "authorization": "Local read access"
+      }
+    },
+    {
+      "id": "media.image.edit",
+      "purpose": "Produce one reference-conditioned image",
+      "required": false,
+      "required_features": [
+        "ordered-references",
+        "one-image",
+        "local-artifact"
+      ],
+      "input_fields": [
+        "references",
+        "prompt",
+        "aspect-ratio"
+      ],
+      "output_fields": [
+        "artifact",
+        "receipt"
+      ],
+      "side_effects": {
+        "external_mutation": true,
+        "may_cost_money": true,
+        "authorization": "Approved inputs, provider and generation budget"
+      }
+    }
+  ]
+}

package/skills/product-asset-set/references/asset-format.md

@@ -0,0 +1,22 @@
+# 产品资产图组交接协议 v2
+
+版本目录包含 `资产说明.txt` 和其列出的独立 PNG。每张有稳定编号、相对文件名、角色、用途、选用条件、局限、实际像素尺寸及 SHA-256。图组至少包含全貌与尺度。每张图按内容选择自己的画幅并记录实际比例，同一图组可混用横、竖、方图。格式 v2 在每张图的说明中记录比例；读取工具同时支持格式 v1 的整套统一比例。使用新图组的 Agent 需使用支持格式 v2 的读取工具，旧读取工具遇到 v2 时应先更新。
+
+用 Node.js 22+ 执行 `node scripts/asset-guide.mjs check PATH/资产说明.txt`。命令返回经过文件校验的 JSON，其中包含绝对路径、编号、用途和哈希。
+
+制作端执行 `node scripts/asset-guide.mjs write SET_DIR PLAN.json`，对目录中已备好的 PNG 生成说明。命令拒绝覆盖现有说明，修订写到新版本目录。计划示例：
+
+```json
+{
+  "product": "黄白月亮抱枕",
+  "version": "v1",
+  "images": [
+    {"id":"A01","file":"01-overall.png","role":"overall","ratio":"16:9","use":"完整轮廓","when":"整体替换","limits":"仅展示可见面"},
+    {"id":"A02","file":"02-scale.png","role":"scale","ratio":"3:4","use":"人物相对尺度","when":"抱持场景","limits":"仅相对尺度"}
+  ]
+}
+```
+
+角色为 overall、scale、structure、texture、marking、use。文件名使用单段英文 ASCII 名称。校验检查尺寸及文件身份，图像内容和用途由执行者实际看图验收。
+
+计划中每张图可填写 ratio，填写时工具核对实际像素比例；省略时从实际图片尺寸约分得到比例。顶层 ratio 作为旧计划的统一默认值继续兼容，逐图 ratio 优先。检查输出包含每图 ratio，整套 ratio 在所有图片比例一致时返回该值，混合比例时返回 null。

package/skills/product-asset-set/scripts/asset-guide.mjs

@@ -0,0 +1,122 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+const guideName = '资产说明.txt';
+const roles = new Set(['overall', 'scale', 'structure', 'texture', 'marking', 'use']);
+const pngSignature = Buffer.from('89504e470d0a1a0a', 'hex');
+const labels = { role: '角色', use: '可用于', when: '选用条件', limits: '局限', size: '尺寸', hash: 'SHA-256' };
+
+function requireValue(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function line(value, label) {
+  requireValue(typeof value === 'string' && value === value.trim() &&
+    value.length && !/[\u0000-\u001f\u007f\u2028\u2029]/u.test(value), `字段无效：${label}`);
+  return value;
+}
+
+function ratioParts(ratio) {
+  requireValue(typeof ratio === 'string' && /^[1-9]\d{0,9}:[1-9]\d{0,9}$/u.test(ratio), '比例无效');
+  return ratio.split(':').map(Number);
+}
+
+function reducedRatio(width, height) {
+  requireValue(width > 0 && height > 0, '图片尺寸无效');
+  let divisor = width;
+  let remainder = height;
+  while (remainder) {
+    [divisor, remainder] = [remainder, divisor % remainder];
+  }
+  return `${width / divisor}:${height / divisor}`;
+}
+
+function parseGuide(source) {
+  const [header, ...blocks] = source.replace(/\r\n/g, '\n').trimEnd().split('\n\n');
+  const match = /^格式版本：([12])\n产品：(.+)\n资产版本：(.+)(?:\n比例：(\d+:\d+))?$/u.exec(header);
+  requireValue(match, '说明头部格式不符');
+  const [, formatVersion, product, version, ratio] = match;
+  requireValue(formatVersion === '1' ? Boolean(ratio) : !ratio, '说明版本与比例字段不符');
+  const images = blocks.map(block => {
+    const [title, ...fields] = block.split('\n');
+    const heading = /^\[(A\d{2,})\] (.+)$/u.exec(title);
+    requireValue(heading, `图编号格式无效：${title}`);
+    const [, id, file] = heading;
+    const entries = Object.entries(formatVersion === '2' ? { ratio: '比例', ...labels } : labels);
+    requireValue(fields.length === entries.length, `图片说明字段数不符：${id}`);
+    return { id, file, ...Object.fromEntries(entries.map(([key, label], index) => {
+      const prefix = label + '：';
+      requireValue(fields[index].startsWith(prefix), `图片字段不符：${id} ${label}`);
+      return [key, fields[index].slice(prefix.length)];
+    })) };
+  });
+  return { product, version, ratio, images };
+}
+
+async function verify(plan, root, checking) {
+  const product = line(plan.product, '产品');
+  const version = line(plan.version, '资产版本');
+  const defaultRatio = plan.ratio;
+  if (defaultRatio !== undefined) ratioParts(defaultRatio);
+  requireValue(Array.isArray(plan.images) && plan.images.some(image => image?.role === 'overall') &&
+    plan.images.some(image => image?.role === 'scale'), '完整图组需要全貌和尺度图');
+  const ids = new Set();
+  const files = new Set();
+  const images = [];
+  for (const image of plan.images) {
+    const { id, file, role } = image;
+    requireValue(typeof id === 'string' && /^A\d{2,}$/u.test(id) && !ids.has(id), `编号无效或重复：${id}`);
+    requireValue(typeof file === 'string' && /^[a-z0-9][a-z0-9_-]*\.png$/iu.test(file) &&
+      !/^(con|prn|aux|nul|com[0-9]|lpt[0-9])\.png$/iu.test(file) && !files.has(file.toLowerCase()), `文件名无效或重复：${file}`);
+    requireValue(roles.has(role), `角色无效：${id}`);
+    ids.add(id);
+    files.add(file.toLowerCase());
+    const use = line(image.use, '可用于');
+    const when = line(image.when, '选用条件');
+    const limits = line(image.limits, '局限');
+    const path = join(root, file);
+    requireValue((await lstat(path)).isFile(), `需要实体图片文件：${file}`);
+    const bytes = await readFile(path);
+    requireValue(bytes.length >= 45 && bytes.subarray(0, 8).equals(pngSignature) &&
+      bytes.readUInt32BE(8) === 13 && bytes.toString('ascii', 12, 16) === 'IHDR' &&
+      bytes.subarray(-12).equals(Buffer.from('0000000049454e44ae426082', 'hex')), `PNG 文件头或结束块无效：${file}`);
+    const width = bytes.readUInt32BE(16);
+    const height = bytes.readUInt32BE(20);
+    const ratio = image.ratio ?? defaultRatio ?? reducedRatio(width, height);
+    const [rw, rh] = ratioParts(ratio);
+    requireValue(width > 0 && height > 0 && BigInt(width) * BigInt(rh) === BigInt(height) * BigInt(rw), `图片比例不符：${file} ${width}x${height}`);
+    const size = `${width}x${height}`;
+    const hash = createHash('sha256').update(bytes).digest('hex');
+    requireValue(!checking || (size === image.size && hash === image.hash), `尺寸或哈希不符：${file}`);
+    images.push({ id, file, path, ratio, role, use, when, limits, size, hash });
+  }
+  return { product, version, ratio: images.every(image => image.ratio === images[0].ratio) ? images[0].ratio : null, images };
+}
+
+function formatGuide({ product, version, images }) {
+  const header = `格式版本：2\n产品：${product}\n资产版本：${version}`;
+  const blocks = images.map(image => [
+    `[${image.id}] ${image.file}`,
+    ...Object.entries({ ratio: '比例', ...labels }).map(([key, label]) => `${label}：${image[key]}`),
+  ].join('\n'));
+  return [header, ...blocks].join('\n\n') + '\n';
+}
+
+async function main([command, location, planPath, ...extra]) {
+  const checking = command === 'check';
+  requireValue(location && !extra.length && ((checking && !planPath) ||
+    (command === 'write' && planPath)), '用法：check GUIDE 或 write SET_DIR PLAN.json');
+  const target = checking ? resolve(location) : join(resolve(location), guideName);
+  if (checking) requireValue((await lstat(target)).isFile(), '说明需为实体文件');
+  const source = new TextDecoder('utf-8', { fatal: true }).decode(await readFile(checking ? target : planPath));
+  const plan = checking ? parseGuide(source) : JSON.parse(source);
+  const result = await verify(plan, dirname(target), checking);
+  if (!checking) await writeFile(target, formatGuide(result), { encoding: 'utf8', flag: 'wx' });
+  process.stdout.write(JSON.stringify({ ok: true, guide: target, ...result }, null, 2) + '\n');
+}
+
+main(process.argv.slice(2)).catch(error => {
+  process.stderr.write(JSON.stringify({ ok: false, error: error.message }) + '\n');
+  process.exitCode = 1;
+});