@petercjl/competitor-visual-canvas 0.1.0 → 0.1.1

package/README.md

@@ -31,6 +31,21 @@ competitor-visual-canvas canvas --run NEW_DIR --submit --json
 
 The new run records cumulative assets and uses the same canvas. Duplicate IDs are skipped. Old elements retain their positions; a stale base, manual changes or excessive column width stops before saving. Main-image/video/SKU columns reserve at least 2400/1600/1840 canvas units initially. Legacy vertical-region canvases require an explicitly requested `reflow --run DIR --submit`; normal append does not move existing elements.
 
+Find an existing application canvas by its exact name and append without a previous local run:
+
+```sh
+competitor-visual-canvas find --title "My canvas" --json
+competitor-visual-canvas append --title "My canvas" --run NEW_DIR --input NEW_PRODUCT_ID --json
+competitor-visual-canvas canvas --run NEW_DIR --json
+competitor-visual-canvas canvas --run NEW_DIR --submit --json
+```
+
+Name lookup scans all result pages and matches the full title. Multiple matches return `AMBIGUOUS_CANVAS` with candidates; select with `append --canvas ID`. A missing name returns `CANVAS_NOT_FOUND`. Lookup never creates a canvas. ID and title may be combined to verify the chosen name; `--base-run` is an alternative selector.
+
+Cloud recovery restores this application's four-region layout, product IDs and existing links from element source metadata, including empty Frames. Old coordinates stay intact and submission rechecks the saved snapshot. Incomplete or unrelated canvases return `CANVAS_STATE_UNSUPPORTED`. Recovery snapshots live in private application state, outside npm. Original product titles, SKU attributes and collection evidence unavailable in cloud metadata are marked unavailable; a completed local base run retains that richer evidence. The application controls these rules; the media CLI continues to provide generic canvas listing, reading and writing.
+
+Agent prompt: “用竞品视觉素材画板工具，找到画板‘我的竞品素材’，追加商品 ID：123456789012。”
+
 ## Installation and updates
 
 Install `@petercjl/competitor-visual-canvas` globally, then use `competitor-visual-canvas skill install --agent codex|sealseek|workbuddy --json` for the current Agent. Its npm dependencies provide compatible tbcli and sealseek-media CLIs; service authorization remains separate. SealSeek resolves the active default workspace or a configured SEALSEEK_SKILLS_DIR; ambiguous roots require an explicit --path.

package/bin/competitor-visual-canvas.mjs

@@ -4,6 +4,7 @@ import {spawnSync} from 'node:child_process';
 import {performUpdate,latestVersion,updateStatus,setAutomatic} from '../src/update.mjs';
 import {collect,planRun,publishCanvas,invoke,read,fail,configureTool,appendRun} from '../src/workflow.mjs';
 import {reflowRun} from '../src/reflow.mjs';
+import {findCanvases,appendToCanvas} from '../src/canvas-target.mjs';
 import {ROOT,META,skill} from '../src/lifecycle.mjs';
 const argv=process.argv.slice(2),command=argv.shift(),options={},args=[];
 function parse(){for(let i=0;i<argv.length;i++){const k=argv[i];if(k==='--json')continue;if(['--submit','--yes'].includes(k)){options[k.slice(2)]=true;continue;}if(k.startsWith('--')){const key=k.slice(2),value=argv[++i];if(!value||value.startsWith('--'))fail('INVALID_INPUT','Missing '+k);if(!['input','raw','run','title','agent','canvas','tool','entry','base-run','path'].includes(key))fail('INVALID_INPUT','Unknown '+k);(options[key]??=[]).push(value);}else args.push(k);}}
@@ -11,7 +12,8 @@ const one=k=>options[k]?.at(-1);
 const help=`competitor-visual-canvas ${META.version}
   collect --input ID_OR_URL [--input MORE] --run NEW_DIR [--raw SAVED_COLLECTION.json ...] --json
   plan --run DIR [--title TEXT] [--base-run COMPLETED_DIR] --json
-  append --base-run COMPLETED_DIR --run NEW_DIR --input ID_OR_URL [--input MORE] [--raw FILE ...] --json
+  find --title EXACT_TITLE --json (read-only exact-name lookup)
+  append (--base-run COMPLETED_DIR | --title EXACT_TITLE | --canvas ID) --run NEW_DIR --input ID_OR_URL [--input MORE] [--raw FILE ...] --json
   reflow --run DIR [--submit] --json (migrate a legacy canvas to horizontal regions)
   canvas --run DIR [--submit] --json
   recover --run DIR --canvas ID --submit --json (bind verified existing canvas after uncertain creation)
@@ -39,10 +41,14 @@ async function main(){
     if(args[0]==='install'){if(!options.yes)fail('AUTHORIZATION_REQUIRED','Use --yes for package update.');return performUpdate({automatic:false});}
     fail('INVALID_INPUT','Use update check/install or auto status/on/off.');
   }
+  if(command==='find')return findCanvases(one('title'));
   const run=one('run');if(!run)fail('INVALID_INPUT','Provide --run DIR.');
   if(command==='collect'){const result=await collect(path.resolve(run),options.input||[],options.raw||[]);return {run_id:result.run_id,run:path.resolve(run),products:result.products.map(p=>({id:p.id,title:p.title,counts:Object.fromEntries(Object.entries(p.assets).map(([k,v])=>[k,v.length]))}))};}
   if(command==='plan')return planRun(path.resolve(run),{title:one('title'),baseRun:one('base-run')?path.resolve(one('base-run')):undefined});
-  if(command==='append'){if(!one('base-run'))fail('INVALID_INPUT','Provide --base-run COMPLETED_DIR.');return appendRun(path.resolve(run),path.resolve(one('base-run')),options.input||[],options.raw||[]);}
+  if(command==='append'){
+    if(one('base-run')){if(one('title')||one('canvas'))fail('INVALID_INPUT','Use a base run or a canvas selector.');return appendRun(path.resolve(run),path.resolve(one('base-run')),options.input||[],options.raw||[]);}
+    return appendToCanvas(path.resolve(run),{title:one('title'),canvas:one('canvas')},options.input||[],options.raw||[]);
+  }
   if(command==='reflow')return reflowRun(path.resolve(run),!!options.submit);
   if(command==='canvas')return publishCanvas(path.resolve(run),!!options.submit);
   if(command==='recover'){if(!one('canvas')||!options.submit)fail('SUBMIT_REQUIRED','Recovery requires --canvas ID --submit.');const {checkpoint}=await import('../src/workflow.mjs');const plan=await read(path.join(run,'layout.plan.json')),board=await invoke('sealseek-media',['canvas','get',one('canvas'),'--json']);if(board.title!==plan.title)fail('STATE_CONFLICT','Recovered canvas title differs.');await checkpoint(path.join(run,'canvas.state.json'),{run_id:plan.run_id,canvas_id:board.canvas_id,canvas_url:board.canvas_url,status:'recovered'});return {recovered:true,...board};}
@@ -54,4 +60,4 @@ async function execute(){
  }
  return main();
 }
-execute().then(value=>console.log(JSON.stringify(value,null,2))).catch(e=>{console.error(JSON.stringify({ok:false,code:e.code??'FAILED',message:e.message}));process.exitCode=1;});
+execute().then(value=>console.log(JSON.stringify(value,null,2))).catch(e=>{console.error(JSON.stringify({ok:false,code:e.code??'FAILED',message:e.message,...(e.details?{details:e.details}:{})}));process.exitCode=1;});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/competitor-visual-canvas",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Collect product visual assets and organize them into SealSeek canvas regions",
   "bin": {

package/skills/competitor-visual-canvas/SKILL.md

@@ -36,6 +36,10 @@ description: Collect Taobao or Tmall product main images, main videos, detail im
 
 ## 向已有画板追加商品
 
+用户给出已有画板名称时，按完整名称精确查找：`competitor-visual-canvas find --title EXACT_TITLE --json`。唯一匹配时执行 `competitor-visual-canvas append --title EXACT_TITLE --run NEW_DIR --input ID_OR_URL [--input MORE] --json`，再按主线第6、7步预览、提交与核验。名称可包含空格与中文，作为完整参数传入。用户提供画板 ID 或链接时可使用 `append --canvas ID`。同名候选由用户选择，随后传 `--canvas ID`；也可同时传 `--title` 校验名称。CANVAS_NOT_FOUND 时报告未找到，不自动新建。
+
+名称或 ID 追加从服务端读取当前内容，恢复本应用四区域 Frame、商品来源、已有素材及布局边界；无需旧对话或本地运行目录。恢复快照保存在本应用私有状态目录，输出 recovered_base_run。恢复依据元素的来源元数据及稳定 Frame 标识，支持空视频 Frame；保留已有元素的坐标、链接、归属和区域标题尺寸。原始采集证据、商品完整标题、SKU 属性等未保存在云端的信息标为 unavailable，不凭空补全。该方式适用于本应用当前四区域结构；缺少元数据、Frame 不完整或混入无法识别元素时返回 CANVAS_STATE_UNSUPPORTED，保留画板，使用可用的完整运行目录或交由用户决定如何整理。恢复和选择均只读，canvas --submit 才写入画板。
+
 用户提出继续添加商品时，使用最新已完成运行目录 BASE，不新建画板。执行 `competitor-visual-canvas append --base-run BASE --run NEW_DIR --input ID_OR_URL [--input MORE] --json`，先采集并规划；预览 `canvas --run NEW_DIR --json`，再在用户授权范围内执行加 `--submit` 的同命令。可重复 `--raw FILE` 复用 item media 原始结果。
 
 追加计划和素材清单为累计结果，沿用原画板 ID、标题、区域横向起点及旧元素 ID/位置；新商品主图、视频、SKU Frame 分别从对应区域底部继续向下，详情页 Frame 从最右侧继续向右。重复商品 ID 跳过；全部已存在时返回 changed:false。后续追加以 NEW_DIR 为最新基准，保留 BASE 作为恢复点。

package/skills/competitor-visual-canvas/adapters/codex.json

@@ -3,6 +3,22 @@
   "schema_version": "1.0.0",
   "platform": "codex",
   "mappings": [
+    {
+      "capability_id": "canvas.product.append",
+      "implementation": {
+        "type": "cli",
+        "command": "competitor-visual-canvas",
+        "discovery": "Current package CLI; find --title and append --title/--canvas/--base-run"
+      },
+      "features": [
+        "canvas-list",
+        "canvas-get",
+        "source-metadata"
+      ],
+      "status": "implemented",
+      "evidence": [],
+      "normalization": "Exact-title candidates, structured ambiguity errors, validated cloud recovery and cumulative append plan; host runtime evidence is separate."
+    },
     {
       "capability_id": "product.media.collect",
       "implementation": {

package/skills/competitor-visual-canvas/adapters/sealseek.json

@@ -3,6 +3,22 @@
   "schema_version": "1.0.0",
   "platform": "sealseek",
   "mappings": [
+    {
+      "capability_id": "canvas.product.append",
+      "implementation": {
+        "type": "cli",
+        "command": "competitor-visual-canvas",
+        "discovery": "Current package CLI; find --title and append --title/--canvas/--base-run"
+      },
+      "features": [
+        "canvas-list",
+        "canvas-get",
+        "source-metadata"
+      ],
+      "status": "implemented",
+      "evidence": [],
+      "normalization": "Exact-title candidates, structured ambiguity errors, validated cloud recovery and cumulative append plan; host runtime evidence is separate."
+    },
     {
       "capability_id": "product.media.collect",
       "implementation": {

package/skills/competitor-visual-canvas/adapters/workbuddy.json

@@ -3,6 +3,22 @@
   "schema_version": "1.0.0",
   "platform": "workbuddy",
   "mappings": [
+    {
+      "capability_id": "canvas.product.append",
+      "implementation": {
+        "type": "cli",
+        "command": "competitor-visual-canvas",
+        "discovery": "Current package CLI; find --title and append --title/--canvas/--base-run"
+      },
+      "features": [
+        "canvas-list",
+        "canvas-get",
+        "source-metadata"
+      ],
+      "status": "implemented",
+      "evidence": [],
+      "normalization": "Exact-title candidates, structured ambiguity errors, validated cloud recovery and cumulative append plan; host runtime evidence is separate."
+    },
     {
       "capability_id": "product.media.collect",
       "implementation": {

package/skills/competitor-visual-canvas/capabilities.json

@@ -8,6 +8,22 @@
     "workbuddy"
   ],
   "capabilities": [
+    {
+      "id": "canvas.product.append",
+      "purpose": "Resolve an exact canvas title or ID, recover application layout, and append products without moving existing assets",
+      "required": true,
+      "required_features": ["canvas-list", "canvas-get", "source-metadata"],
+      "input_fields": ["canvas_title_or_id_or_base_run", "product_ids", "new_run_directory"],
+      "output_fields": ["canvas_id", "recovered_base_run", "cumulative_plan"],
+      "errors": ["CANVAS_NOT_FOUND", "AMBIGUOUS_CANVAS", "CANVAS_STATE_UNSUPPORTED", "CANVAS_CHANGED"],
+      "side_effects": {
+        "reads": "authenticated canvas list and content",
+        "writes": "private recovery snapshot and new run files; canvas only on explicit submit",
+        "authorization": "user requested appending products to the selected canvas",
+        "external_mutation": true,
+        "may_cost_money": false
+      }
+    },
     {
       "id": "product.media.collect",
       "purpose": "Read ordered product media and source evidence",

package/src/canvas-target.mjs

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {stateRoot} from './core.mjs';
+import {invoke,fail,uid,create,REGIONS,validateLayout,matchesBatch,appendRun} from './workflow.mjs';
+
+const labels=['主图区','主图视频区','SKU区','详情页区'];
+const geometry=e=>Object.fromEntries(['x','y','width','height'].map(k=>[k,e[k]]));
+const reject=message=>fail('CANVAS_STATE_UNSUPPORTED',message+' Use a completed --base-run when available. Existing canvas content was preserved.');
+
+// Discovery is read-only; service keyword search is fuzzy, application selection is exact.
+export async function findCanvases(title,call=invoke){
+  if(typeof title!=='string'||!title.trim())fail('INVALID_INPUT','Provide an exact canvas title.');
+  const found=new Map();let page=1;
+  for(;;){
+    const result=await call('sealseek-media',['canvas','list','--keyword',title,'--page',String(page),'--limit','100','--json']);
+    if(!Array.isArray(result.canvases))fail('OUTPUT_CONTRACT_FAILED','Invalid canvas list.');
+    for(const b of result.canvases)if(b.title===title)found.set(String(b.canvas_id),b);
+    const pages=Number(result.pages??1);
+    if(!Number.isInteger(pages)||pages<0||pages>10000)fail('OUTPUT_CONTRACT_FAILED','Invalid canvas pagination.');
+    if(page>=pages)break;page++;
+  }
+  return {title,count:found.size,canvases:[...found.values()]};
+}
+
+export async function selectCanvas({title,canvas},call=invoke){
+  let id=canvas;
+  if(title&&!canvas){
+    const result=await findCanvases(title,call);
+    if(!result.count)fail('CANVAS_NOT_FOUND','No canvas has this exact title.');
+    if(result.count>1)throw Object.assign(new Error('Multiple canvases have this title; select a canvas ID.'),{code:'AMBIGUOUS_CANVAS',details:result});
+    id=result.canvases[0].canvas_id;
+  }
+  if(!/^\d+$/.test(id||''))fail('INVALID_INPUT','Provide --title TEXT or --canvas ID.');
+  const board=await call('sealseek-media',['canvas','get',String(id),'--json']);
+  if(String(board.canvas_id)!==String(id))fail('OUTPUT_CONTRACT_FAILED','Canvas identity mismatch.');
+  if(title&&board.title!==title)fail('CANVAS_CHANGED','Selected canvas title differs.');
+  return board;
+}
+
+// The application reconstructs only its own four-region contract. No provider API is duplicated.
+// Frame hashes bind even empty video Frames to their product, category and collection run.
+export function restoreCanvas(board,run_id=crypto.randomUUID()){
+  if(!board.canvas_id||!Array.isArray(board.elements))reject('Canvas content is unavailable.');
+  const elements=board.elements.filter(e=>!e.isDeleted),images=elements.filter(e=>e.type==='image');
+  const texts=labels.map(text=>{const found=elements.filter(e=>e.type==='text'&&e.text===text&&typeof e.id==='string'&&e.id.startsWith('region-'));if(found.length!==1)reject('Four unique region headings are required.');const e=found[0];if(!['x','y','width','height','fontSize'].every(k=>Number.isFinite(e[k]))||e.width<=0||e.height<=0||e.fontSize<8||e.fontSize>200)reject('Invalid heading geometry.');return {id:e.id,text,...geometry(e),fontSize:e.fontSize};});
+  if(texts.some((t,i)=>i&&t.x<=texts[i-1].x))reject('Unsupported region order.');
+  const products=new Map(),identities=new Map(),media=[],taskIds=new Set();
+  for(const e of images){
+    const s=e.customData?.sourceMetadata,task=e.customData?.cliTaskId;
+    if(!s||!REGIONS.includes(s.category)||!/^\d+$/.test(s.productId||'')||typeof s.assetId!=='string'||typeof task!=='string'||e.customData.cliOutputIndex!==0)reject('An image lacks application source metadata.');
+    const suffix='-'+s.assetId+'-'+s.category;
+    if(!task.endsWith(suffix))reject('Invalid application media identity.');
+    if(taskIds.has(task))reject('Duplicate application media identity.');taskIds.add(task);
+    const origin=task.slice(0,-suffix.length),key=origin+'|'+s.productId;
+    if(!origin)reject('Missing collection identity.');
+    if(!products.has(s.productId))products.set(s.productId,{id:s.productId,title:'商品 '+s.productId,url:s.sourceUrl,shop:{shopId:s.shopId,shopName:''},coverage:{recovered_from_canvas:true,original_collection:'unavailable'},assets:Object.fromEntries(REGIONS.map(c=>[c,[]]))});
+    identities.set(key,{origin,productId:s.productId});
+    const kind=s.category==='main_videos'?'video':'image',url=kind==='video'?e.customData.videoUrl:e.customData.fileUrl;
+    if(!url||(kind==='video'&&!e.customData.fileUrl)||!['x','y','width','height'].every(k=>Number.isFinite(e[k]))||e.width<=0||e.height<=0)reject('Invalid media geometry or URL.');
+    media.push({id:task,kind,urls:[url],frameId:e.frameId,placement:{mode:'explicit',positions:[geometry(e)]},...(kind==='video'?{posterUrl:e.customData.fileUrl}:{}),sourceMetadata:structuredClone(s)});
+    products.get(s.productId).assets[s.category].push({asset_id:s.assetId,kind,url,width:e.width,height:e.height,recovered:true,source_index:0});
+  }
+  if(!products.size)reject('No recoverable products were found.');
+  const frames=[],members=new Map(REGIONS.map(c=>[c,[]])),frameKeys=new Set();
+  for(const e of elements.filter(e=>e.type==='frame')){
+    const candidates=[];
+    for(const v of identities.values())for(const category of REGIONS)if(e.id==='frame-'+uid([v.origin,v.productId,category]))candidates.push({...v,category});
+    if(candidates.length!==1)reject('A Frame cannot be bound to an application product.');
+    const identity=candidates[0],p=products.get(identity.productId);
+    const key=identity.productId+'|'+identity.category;
+    if(frameKeys.has(key)||typeof e.name!=='string'||!e.name.trim()||!['x','y','width','height'].every(k=>Number.isFinite(e[k]))||e.width<=0||e.height<=0)reject('Duplicate Frame identity or invalid geometry.');
+    frameKeys.add(key);
+    if(p.shop.shopName&&p.shop.shopName!==e.name)reject('Product shop names differ across Frames.');
+    p.shop.shopName=e.name;
+    const frame={id:e.id,name:e.name,...geometry(e)};frames.push(frame);members.get(identity.category).push(frame);
+    for(const m of media.filter(m=>m.frameId===e.id))if(m.sourceMetadata.productId!==identity.productId||m.sourceMetadata.category!==identity.category)reject('Media source and Frame identity disagree.');
+  }
+  if(frames.length!==products.size*4||REGIONS.some(c=>members.get(c).length!==products.size)||media.some(m=>!frames.some(f=>f.id===m.frameId)))reject('Product Frames are incomplete.');
+  const known=new Set([...frames,...texts].map(e=>e.id));
+  if(elements.some(e=>!known.has(e.id)&&e.type!=='image'&&!(e.type==='rectangle'&&e.customData?.type==='frame-background'&&frames.some(f=>f.id===e.customData.ownerFrameId))))reject('The canvas contains unsupported elements.');
+  const regions=REGIONS.map((category,i)=>{
+    const list=members.get(category),horizontal=category==='detail_images',x=texts[i].x,y=Math.min(...list.map(f=>f.y));
+    list.sort((a,b)=>horizontal?a.x-b.x:a.y-b.y);
+    if(list.some(f=>horizontal?f.y!==y:f.x!==x)||list[0].x!==x)reject('Unsupported Frame alignment.');
+    const width=horizontal?Math.max(...list.map(f=>f.width)):texts[i+1].x-x-240;
+    if(list.some(f=>!horizontal&&f.width>width)||width<=0)reject('Unsupported region bounds.');
+    const bottom=Math.max(...list.map(f=>f.y+f.height)),right=Math.max(...list.map(f=>f.x+f.width));
+    return {category,x,y,width,axis:horizontal?'horizontal':'vertical',next_x:horizontal?right+96:x,next_y:horizontal?y:bottom+96,bottom,right,frame_ids:list.map(f=>f.id)};
+  });
+  const plan={schema_version:2,presentation_version:1,run_id,title:board.title,layout_options:{width:320,gap:32,padding:32,frameGap:96,regionGap:240},regions,batch:{frames,media,texts},recovered_from_canvas:String(board.canvas_id)};
+  validateLayout(plan);
+  if(!matchesBatch(board,plan.batch))reject('Recovered canvas does not match its source content.');
+  return {plan,manifest:{schema_version:1,run_id,captured_at:new Date().toISOString(),recovered_from_canvas:String(board.canvas_id),products:[...products.values()]}};
+}
+
+export async function appendToCanvas(run,selector,inputs,rawFiles=[],call=invoke){
+  const board=await selectCanvas(selector,call),{plan,manifest}=restoreCanvas(board);
+  const base=path.join(stateRoot(),'recovered-canvases',plan.run_id);
+  await create(path.join(base,'layout.plan.json'),plan);
+  await create(path.join(base,'canvas.batch.json'),plan.batch);
+  await create(path.join(base,'assets.manifest.json'),manifest);
+  await create(path.join(base,'canvas.state.json'),{run_id:plan.run_id,status:'completed',canvas_id:String(board.canvas_id),canvas_url:board.canvas_url});
+  return {...await appendRun(run,base,inputs,rawFiles),canvas_id:String(board.canvas_id),title:board.title,recovered_base_run:base};
+}