@petercjl/ecom-cli 0.2.0 → 0.3.0

package/INSTALL.md

@@ -10,4 +10,4 @@ User prompt: “帮我安装 @petercjl/ecom-cli，并安装它的配套 Skill。
 4. Verify `current=true`, `managed=true`, `edited=false`, SHA-256 verification, package version and returned CLI entry. Load the installed `SKILL.md` through the current Agent's own discovery mechanism; refresh discovery if the host requires it. Installation is complete only after both package integrity and host discovery succeed.
 5. Use the returned isolated `.runtime/bin/ecom-cli.mjs` with Node.js for subsequent calls. The bootstrap npm package may then be removed; this Skill and runtime remain functional. A system Node.js runtime and the separately installed Ecom browser are declared external dependencies.
 
-Existing unmanaged or edited destinations are preserved and produce a structured conflict. Choose an unused destination or reconcile user edits with a backup. Never install other Agents merely because their directories exist. Runtime support is capability-based; current real browser validation is macOS. No prior published updater exists for this first release.
+Existing unmanaged or edited destinations are preserved and produce a structured conflict. Choose an unused destination or reconcile user edits with a backup. Never install other Agents merely because their directories exist. Runtime support is capability-based; current real browser validation is macOS.

package/README.md

@@ -33,3 +33,19 @@ Task entry checks stable `latest` at most daily, with a 1.5 second bound. Detect
 `ecom-cli help --json`, `version --json`, `capabilities --json`, `schema --json`, and `doctor --json` expose supported commands and versioned results. Errors use JSON with stable codes; exit code 2 means invalid arguments, 1 means operational failure. stdout contains results; stderr contains diagnostics. Multiple Ecom instances require explicit `--profile` or `--instance` selection. Connection authenticates through owner-only local mailbox files, verifies the live Ecom executable, and uses no remote debugging port.
 
 The browser owns sessions, containers and authorization. This package owns discovery, read-only transport and managed installation. The Skill documents invocation, diagnosis and recovery. Additional browser capabilities will extend this same command/Skill contract.
+
+## 业务能力迁移（开发中）
+
+内置 sycmcli 0.4.0 的取数目录和 7 类填数计划。135 个取数入口统一使用固定原生目录，覆盖生意参谋、万相台、达摩盘与消费券。原生层在指定持久容器中准备服务认证并发送已登记的 GET／POST 读取，要求浏览器与 CLI 目录哈希一致。目录接入与逐项真实验收分别记录；旧浏览器兼容 88 个生意参谋 GET 入口，其余提示升级。填数支持计划、审查与确认，实际提交和回读由独立执行能力承担。
+
+发给当前 Agent：
+
+> 使用 Ecom CLI，查看指定账号可以查询哪些生意参谋数据。
+
+> 使用 Ecom CLI，获取指定账号昨天的交易概况。
+
+> 使用 Ecom CLI，为指定账号生成商品草稿的操作计划，供我审查。
+
+开发者通过 `sycm operations`、`sycm schema --operation ID`、`sycm run --operation ID --container VALUE --params-json JSON` 发现和调用原子取数能力；`sycm mutation plan/show/apply` 承接计划与确认。所有命令均支持结构化 JSON。
+
+取数优先使用后台原生请求。需要准备平台会话时，当前 Agent 可通过 `sycm open --operation ID --container VALUE` 在该容器打开注册入口，默认后台打开或复用；`--foreground` 用于明确需要前台的登录与验证。登录完成后继续调用原生接口，保留账号已设置的首页。

package/bin/ecom-cli.mjs

@@ -4,6 +4,6 @@ try {
   const result = await main(process.argv.slice(2));
   process.stdout.write(JSON.stringify(result) + '\n');
 } catch (error) {
-  process.stdout.write(JSON.stringify({ok:false,error:{code:error.code || 'CLI_ERROR',message:error.code ? error.message : 'Operation failed; inspect doctor and operation status',executed:error.executed ?? false,...(error.operationId ? {operationId:error.operationId} : {}),...(error.httpStatus!==undefined?{httpStatus:error.httpStatus}:{}),...(error.recovery ? {recovery:error.recovery} : {})}}) + '\n');
+  process.stdout.write(JSON.stringify({ok:false,error:{code:error.code || 'CLI_ERROR',message:error.code ? error.message : 'Operation failed; inspect doctor and operation status',executed:error.executed ?? false,...(error.operationId ? {operationId:error.operationId} : {}),...(error.httpStatus!==undefined?{httpStatus:error.httpStatus}:{}),...(error.diagnostics?{diagnostics:error.diagnostics}:{}),...(error.recovery ? {recovery:error.recovery} : {})}}) + '\n');
   process.exitCode = error.code === 'INVALID_ARGUMENT' ? 2 : 1;
 }

package/capabilities.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@petercjl/ecom-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "skills": [
     "ecom-cli"
   ],
@@ -251,6 +251,212 @@
         "PROTOCOL_MISMATCH",
         "OPERATION_TIMEOUT"
       ]
+    },
+    "sycm operations": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none",
+      "authorization": "Registered reads only, or local mutation-plan/confirmation records; no automatic platform writes. Credentials stay native."
+    },
+    "sycm capabilities": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        }
+      },
+      "sideEffects": "none",
+      "authorization": "Registered reads only, or local mutation-plan/confirmation records; no automatic platform writes. Credentials stay native."
+    },
+    "sycm schema": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--operation": {
+          "type": "string",
+          "required": true
+        }
+      },
+      "sideEffects": "none",
+      "authorization": "Registered reads only, or local mutation-plan/confirmation records; no automatic platform writes. Credentials stay native."
+    },
+    "sycm run": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--profile": {
+          "type": "string"
+        },
+        "--instance": {
+          "type": "string"
+        },
+        "--container": {
+          "type": "string",
+          "required": true
+        },
+        "--operation": {
+          "type": "string",
+          "required": true
+        },
+        "--params-json": {
+          "type": "string"
+        }
+      },
+      "sideEffects": "local-write",
+      "authorization": "Registered reads only, or local mutation-plan/confirmation records; no automatic platform writes. Credentials stay native.",
+      "output": {
+        "operation": "registered ID",
+        "service": "sycm, sycm-trade, alimama, dmp or coupon",
+        "instance": "pinned native instance",
+        "container": "stable id and current label",
+        "httpStatus": 200,
+        "businessStatus": "success after business-envelope checks",
+        "data": "native-redacted source response",
+        "registryHash": "compiled browser/CLI catalog identity"
+      },
+      "limits": {
+        "paramsBytes": 24576,
+        "nativeResponseBytes": 2097152,
+        "nativeOperationTimeoutMs": 50000,
+        "clientTimeoutMs": 75000,
+        "automaticRetries": false,
+        "methods": "Fixed catalog GET/POST reads; arbitrary method/path/body forbidden",
+        "accountBinding": "Current Ecom persistent container, no separate CLI store configuration"
+      },
+      "errors": [
+        "BROWSER_UPGRADE_REQUIRED",
+        "AUTH_CONTEXT_REQUIRED",
+        "AUTH_REQUIRED",
+        "AUTH_OR_RISK_CHALLENGE",
+        "PERMISSION_REQUIRED",
+        "RISK_VERIFICATION_REQUIRED",
+        "SHOP_VERIFICATION_FAILED",
+        "BUSINESS_READ_TIMEOUT",
+        "BUSINESS_RESPONSE_INVALID",
+        "PROTOCOL_MISMATCH"
+      ],
+      "errorDiagnostics": {
+        "phase": "bounded native stage",
+        "netError": "Chromium network code",
+        "bodyKind": "json/html/text/none",
+        "matchingTabFound": "boolean",
+        "entryCookieCount": "count only; does not prove authentication",
+        "failureClass": "safe fixed classification",
+        "publicScripts": "optional sanitized public CDN scripts; credentials excluded"
+      }
+    },
+    "sycm mutation plan": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--profile": {
+          "type": "string"
+        },
+        "--instance": {
+          "type": "string"
+        },
+        "--container": {
+          "type": "string",
+          "required": true
+        },
+        "--operation": {
+          "type": "string",
+          "required": true
+        },
+        "--params-json": {
+          "type": "string",
+          "required": true
+        }
+      },
+      "sideEffects": "local-write",
+      "authorization": "Registered reads only, or local mutation-plan/confirmation records; no automatic platform writes. Credentials stay native."
+    },
+    "sycm mutation show": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--plan": {
+          "type": "string",
+          "required": true
+        }
+      },
+      "sideEffects": "none",
+      "authorization": "Registered reads only, or local mutation-plan/confirmation records; no automatic platform writes. Credentials stay native."
+    },
+    "sycm mutation apply": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--profile": {
+          "type": "string"
+        },
+        "--instance": {
+          "type": "string"
+        },
+        "--container": {
+          "type": "string",
+          "required": true
+        },
+        "--plan": {
+          "type": "string",
+          "required": true
+        },
+        "--confirm": {
+          "type": "string",
+          "required": true
+        }
+      },
+      "sideEffects": "local-write",
+      "authorization": "Registered reads only, or local mutation-plan/confirmation records; no automatic platform writes. Credentials stay native."
+    },
+    "sycm open": {
+      "options": {
+        "--json": {
+          "type": "boolean"
+        },
+        "--profile": {
+          "type": "string"
+        },
+        "--instance": {
+          "type": "string"
+        },
+        "--container": {
+          "type": "string",
+          "required": true
+        },
+        "--operation": {
+          "type": "string",
+          "required": true
+        },
+        "--foreground": {
+          "type": "boolean",
+          "default": false
+        }
+      },
+      "sideEffects": "local-write",
+      "authorization": "Explicit page navigation or an authorized recovery fallback; fixed registered entry in the selected container. Background/reuse by default, foreground only when selected.",
+      "output": {
+        "navigation": "started or reused, not login success",
+        "container": "stable ID and current name",
+        "requestedUrl": "compiled registered entry",
+        "background": "boolean",
+        "authentication": "not-verified"
+      },
+      "errors": [
+        "BROWSER_UPGRADE_REQUIRED",
+        "BUSINESS_PAGE_UNSUPPORTED",
+        "CONTAINER_NOT_FOUND",
+        "CONTAINER_AMBIGUOUS",
+        "PROTOCOL_MISMATCH"
+      ],
+      "sideEffectDetails": "Registered browser navigation in the selected container; no website submission."
     }
   },
   "transport": {
@@ -409,7 +615,7 @@
     "enabledByDefault": true,
     "intervalHours": 24,
     "timeoutMs": 1500,
-    "trigger": "containers list, containers inspect and session request task entry",
+    "trigger": "containers list, containers inspect and session request task entry, sycm run, sycm mutation plan/apply, sycm open",
     "configuration": "Stable latest channel; detection only. Explicit update activates only the selected target runtime and Skill together.",
     "disable": "ECOM_CLI_UPDATE_CHECK=0",
     "recovery": "Offline checks retain installed runtime; local edit/ownership conflicts stop replacement; prior target kept as backup. Use recorded candidate and inspect target status before retrying.",
@@ -417,9 +623,9 @@
   },
   "compatibility": {
     "agents": "Any Agent with terminal, Node.js and Skill discovery capabilities; generic adapter",
-    "macos": "Runtime validation pending",
+    "macos": "Native container list, account inspection and authorized session GET verified on macOS arm64 Ecom Dev; host discovery is checked separately",
     "windows": "Package mechanics only; browser transport unsupported",
-    "historicalUpdater": "First release; registry package absent; no prior updater exists"
+    "historicalUpdater": "Actual published 0.1.1, 0.1.2, 0.1.3 and 0.2.0 updater entries verified with real npm, preserved prior versions, isolated targets and failure recovery"
   },
   "errors": [
     "INSTANCE_NOT_RUNNING",
@@ -444,5 +650,32 @@
     "BUSY",
     "REQUEST_FAILED",
     "NON_JSON_RESPONSE"
-  ]
+  ],
+  "businessIntegration": {
+    "sourcePackage": "@petercjl/sycmcli",
+    "sourceVersion": "0.4.0",
+    "registeredReads": 135,
+    "nativeGetCandidates": 88,
+    "serviceAdaptersRequired": 0,
+    "mutationWorkflows": 7,
+    "automaticMutation": false,
+    "inventoryCommand": "sycm capabilities",
+    "schemaCommand": "sycm schema --operation ID",
+    "readCommand": "sycm run --operation ID --container VALUE --params-json JSON",
+    "verification": "Transport availability is separate from per-endpoint live acceptance; inspect each operation schema. Plans authorize a workflow, not an executed submission.",
+    "sourceRegistryReads": 124,
+    "sourceFirstClassReadEndpoints": 11,
+    "nativeBusinessReadDefinitions": 135,
+    "serviceRuntimeAcceptance": "pending native build and per-service live checks",
+    "requiredNativeProtocol": 1,
+    "registryHashAgreementRequired": true,
+    "containerBinding": "Stable Ecom container ID, browser-owned session and native account verification; no separate Chrome store profile",
+    "nativeRegistryHash": "26d302541c1641b00ce45c6df4ae32bbb90e2b21352fe5f91e3cfedb21e35d5e",
+    "pageFallback": {
+      "command": "sycm open --operation ID --container VALUE",
+      "requiredNativeCapability": "businessPageOpenProtocol=1",
+      "default": "background and reuse",
+      "strategy": "Native HTTP and private auth initialization first. Open the registered container entry only when needed and authorized; verify data again afterward."
+    }
+  }
 }

package/lib/browser.mjs

@@ -1,10 +1,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import crypto from 'node:crypto';
 import {execFileSync} from 'node:child_process';
 import {setTimeout as pause} from 'node:timers/promises';
 import {fail,privatePath,writeNew,exists} from './common.mjs';
 const ps=(args)=>execFileSync('/bin/ps',args,{encoding:'utf8',timeout:3000,maxBuffer:4*1024*1024});
+export function processProfile(executable,command) {
+  const explicit=command.match(/(?:^| )--user-data-dir=(.*?)(?= --|$)/)?.[1];
+  if(explicit)return explicit;
+  if(executable.endsWith('/Ecom.app/Contents/MacOS/Ecom'))return path.join(os.homedir(),'Library','Application Support','Ecom','Ecom');
+  return null;
+}
 export function discover({profile,instance}={}) {
   if(process.platform!=='darwin') throw fail('PLATFORM_UNSUPPORTED','Browser transport currently supports macOS; no debugging fallback is available');
   const candidates=[];
@@ -13,7 +20,7 @@ export function discover({profile,instance}={}) {
     if(!m || Number(m[2])!==process.getuid() || !/\/(Ecom Dev|Ecom)\.app\/Contents\/MacOS\/\1$/.test(m[3])) continue;
     let command; try {command=ps(['-ww','-p',m[1],'-o','command=']).trim();}catch{continue;}
     if(/--(?:remote-debugging|headless|enable-automation)/.test(command)) continue;
-    const selected=command.match(/(?:^| )--user-data-dir=(.*?)(?= --|$)/)?.[1];
+    const selected=processProfile(m[3],command);
     if(!selected || !path.isAbsolute(selected) || (profile && path.resolve(profile)!==path.resolve(selected))) continue;
     const folder=path.join(selected,'Default','.ecom-native-cli'), file=path.join(folder,'endpoint.json');
     if(!exists(file)) continue;
@@ -27,7 +34,7 @@ export function discover({profile,instance}={}) {
   return candidates[0];
 }
 const instanceOf=({endpoint,channel})=>({id:endpoint.instanceId,pid:endpoint.pid,channel});
-const credentialKey=/token|cookie|csrf|password|authorization|secret|sessionid|api[-_]?key|access[-_]?key|credential/i;
+const credentialKey=/token|cookie|csrf|password|authorization|secret|sessionid|api[-_]?key|access[-_]?key|credential|^__d?tk$|^session$|^loginpointid$/i;
 function homeUrl(value) {
   try {
     const url=new URL(value);if(url.protocol!=='https:')return null;
@@ -83,6 +90,36 @@ export async function requestInConnection(connection,options) {
   if(body.containerId!==container.id||body.httpStatus!==200||!Object.hasOwn(body,'data'))throw fail('PROTOCOL_MISMATCH','Session response does not match selected container or JSON response contract',{operationId:body.operationId,executed:'unknown'});
   return {ok:true,schemaVersion:1,operationId:body.operationId,instance:instanceOf(connection),container,request:{method:'GET',url},httpStatus:body.httpStatus,data:body.data,businessStatus:'not-evaluated'};
 }
+export async function registeredReadInConnection(connection,options,operation,params,registryHash) {
+  if(connection.endpoint.businessReadProtocol!==1)throw fail('BROWSER_UPGRADE_REQUIRED','This operation needs an Ecom build with native business read protocol 1');
+  if(connection.endpoint.businessReadRegistryHash!==registryHash)throw fail('BROWSER_UPGRADE_REQUIRED','Browser and CLI business catalogs differ; update them together');
+  const listed=await readMailbox(connection),container=resolveContainer(listed.containers,options.container);
+  const body=await callMailbox(connection,{method:'business.read',containerId:container.id,operation,params},75000);
+  if(body.containerId!==container.id||body.businessOperation!==operation||body.httpStatus!==200||!Object.hasOwn(body,'data'))throw fail('PROTOCOL_MISMATCH','Registered response differs from the pinned container or operation',{operationId:body.operationId,executed:'unknown'});
+  return {ok:true,schemaVersion:1,operationId:body.operationId,instance:instanceOf(connection),container,operation,httpStatus:body.httpStatus,data:body.data,...(Array.isArray(body.dataFlows)&&body.dataFlows.length?{dataFlows:body.dataFlows}:{}),transport:'native-business-read',identityBinding:'container-bound-account',registryHash};
+}
+export async function openBusinessPageInConnection(connection,options,operation,entryUrl,registryHash) {
+  if(connection.endpoint.businessPageOpenProtocol!==1||connection.endpoint.businessReadRegistryHash!==registryHash)throw fail('BROWSER_UPGRADE_REQUIRED','Update Ecom to the matching registered-page navigation capability');
+  const listed=await readMailbox(connection),container=resolveContainer(listed.containers,options.container);
+  const background=!options.foreground;
+  const body=await callMailbox(connection,{method:'shops.open',containerId:container.id,businessOperation:operation,background,reuse:background});
+  if(body.containerId!==container.id||!['started','reused'].includes(body.navigation)||body.requestedUrl!==entryUrl)throw fail('PROTOCOL_MISMATCH','Navigation target differs from the registered container or entry page',{operationId:body.operationId,executed:'unknown'});
+  return {ok:true,schemaVersion:1,operationId:body.operationId,instance:instanceOf(connection),container,operation,requestedUrl:body.requestedUrl,navigation:body.navigation,background,authentication:'not-verified'};
+}
+function safeDiagnostics(value) {
+  if(!value||typeof value!=='object')return undefined;
+  const result={};
+  if(typeof value.phase==='string'&&/^[a-z-]{1,32}$/.test(value.phase))result.phase=value.phase;
+  if(Number.isInteger(value.netError)&&value.netError<=0&&value.netError>=-9999)result.netError=value.netError;
+  if(['json','html','text','none'].includes(value.bodyKind))result.bodyKind=value.bodyKind;
+  if(typeof value.matchingTabFound==='boolean')result.matchingTabFound=value.matchingTabFound;
+  if(Number.isInteger(value.entryCookieCount)&&value.entryCookieCount>=0&&value.entryCookieCount<=100000)result.entryCookieCount=value.entryCookieCount;
+  if(['unclassified','cors-rejected','csrf-rejected','verification-required','forbidden'].includes(value.failureClass))result.failureClass=value.failureClass;
+  if(Array.isArray(value.publicScripts))result.publicScripts=value.publicScripts.slice(0,20).filter(url=>{
+    try{const item=new URL(url);return item.protocol==='https:'&&item.hostname==='g.alicdn.com'&&!item.username&&!item.password&&!item.search&&!item.hash&&item.pathname.endsWith('.js')&&url.length<2048;}catch{return false;}
+  });
+  return Object.keys(result).length?result:undefined;
+}
 export async function callMailbox({folder,endpoint},payload,timeoutMs=10000) {
   privatePath(folder,true);privatePath(path.join(folder,'endpoint.json'));
   const current=JSON.parse(fs.readFileSync(path.join(folder,'endpoint.json'),'utf8'));
@@ -96,13 +133,14 @@ export async function callMailbox({folder,endpoint},payload,timeoutMs=10000) {
     if(exists(response)) {
       privatePath(response);
       const raw=fs.readFileSync(response,'utf8');
-      if(Buffer.byteLength(raw)>(payload.method==='session.get'?2*1024*1024+65536:1024*1024)) throw fail('PROTOCOL_MISMATCH','Oversized response',{operationId:id,executed:'unknown'});
+      if(Buffer.byteLength(raw)>(['session.get','business.read'].includes(payload.method)?2*1024*1024+65536:1024*1024)) throw fail('PROTOCOL_MISMATCH','Oversized response',{operationId:id,executed:'unknown'});
       let body;try{body=JSON.parse(raw);}catch{await pause(25);continue;}
       if(body.schemaVersion!==1 || body.instanceId!==endpoint.instanceId || body.operationId!==id) throw fail('PROTOCOL_MISMATCH','Response does not match this operation',{operationId:id,executed:'unknown'});
       fs.unlinkSync(response);
       if(body.ok!==true) {
         const code=/^[A-Z][A-Z0-9_]{0,63}$/.test(body.error?.code??'')?body.error.code:'BROWSER_ERROR';
-        throw fail(code,'Ecom refused the request: '+code,{operationId:id,executed:body.error?.executed??'unknown',...(Number.isInteger(body.error?.httpStatus)?{httpStatus:body.error.httpStatus}:{})});
+        const diagnostics=safeDiagnostics(body.error?.diagnostics);
+        throw fail(code,'Ecom refused the request: '+code,{operationId:id,executed:body.error?.executed??'unknown',...(Number.isInteger(body.error?.httpStatus)?{httpStatus:body.error.httpStatus}:{}),...(diagnostics?{diagnostics}:{})});
       }
       return body;
     }

package/lib/cli.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import {root,pkg,fail} from './common.mjs';
 import {discover,listContainers,inspectContainer,requestSession,validateReadUrl} from './browser.mjs';
 import {source,status,installSkill,checkUpdate,updateInstall} from './maintenance.mjs';
+import {inventory,operationSchema,runRead,openOperation,planMutation,showPlan,authorizePlan,nativeRegistryHash} from './sycm.mjs';
 export const capabilities=()=>JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8'));
 export function parse(argv) {
   const positions=[],options={}, caps=capabilities();
@@ -12,8 +13,8 @@ export function parse(argv) {
     if(word==='--version'&&argv.length===1){positions.push('version');continue;}
     const key=word.slice(2);
     if(Object.hasOwn(options,key)) throw fail('INVALID_ARGUMENT','Duplicate option '+word);
-    if(['json','help','yes'].includes(key))options[key]=true;
-    else if(['agent','target','profile','instance','name','version','container','url','method'].includes(key)&&argv[i+1]&&!argv[i+1].startsWith('--')) options[key]=argv[++i];
+    if(['json','help','yes','foreground'].includes(key))options[key]=true;
+    else if(['agent','target','profile','instance','name','version','container','url','method','operation','params-json','plan','confirm'].includes(key)&&argv[i+1]&&!argv[i+1].startsWith('--')) options[key]=argv[++i];
     else throw fail('INVALID_ARGUMENT','Unknown option or missing value: '+word);
   }
   let command=positions.join(' ')||'help';
@@ -27,11 +28,15 @@ export function parse(argv) {
     if(!options.container||!options.url)throw fail('INVALID_ARGUMENT','session request requires --container and --url');
     options.url=validateReadUrl(options.url,options.method??'GET');
   }
+  if(['sycm open','sycm run','sycm mutation plan','sycm mutation apply'].includes(command)&&!options.container)throw fail('INVALID_ARGUMENT','Specify --container');
+  if(['sycm open','sycm schema','sycm run','sycm mutation plan'].includes(command)&&!options.operation)throw fail('INVALID_ARGUMENT','Specify --operation');
+  if(['sycm mutation show','sycm mutation apply'].includes(command)&&!options.plan)throw fail('INVALID_ARGUMENT','Specify --plan');
+  if(command==='sycm mutation apply'&&!options.confirm)throw fail('INVALID_ARGUMENT','Specify --confirm from the reviewed plan');
   return {command,options,requested};
 }
 export async function main(argv) {
   const {command,options,requested}=parse(argv);
-  if(command==='help')return {ok:true,package:pkg.name,version:pkg.version,usage:'ecom-cli containers list|inspect | session request | skill source|status|install|update | update check|install | doctor; use help --json for required options',...capabilities(),...(capabilities().commandContracts[requested]??{})};
+  if(command==='help')return {ok:true,package:pkg.name,version:pkg.version,usage:'ecom-cli containers list|inspect | session request | sycm operations|schema|run|open|capabilities|mutation plan|show|apply | skill source|status|install|update | update check|install | doctor; use help --json for required options',...capabilities(),...(capabilities().commandContracts[requested]??{})};
   if(command==='version')return {ok:true,package:pkg.name,version:pkg.version,protocolVersion:1};
   if(command==='capabilities'||command==='schema')return {ok:true,...capabilities()};
   if(command==='skill source') {const item=source();return {...capabilities(),...item,complete:true,items:[item]};}
@@ -39,8 +44,20 @@ export async function main(argv) {
   if(command==='skill install'||command==='skill update')return installSkill(options);
   if(command==='update check')return checkUpdate();
   if(command==='update install')return updateInstall(options);
+  if(command==='sycm capabilities')return inventory();
+  if(command==='sycm operations'){const result=inventory();return {ok:true,schemaVersion:1,source:result.source,count:result.operations.length,operations:result.operations};}
+  if(command==='sycm schema')return {ok:true,schemaVersion:1,operation:operationSchema(options.operation)};
+  if(command==='sycm mutation show')return showPlan(options.plan);
+  if(['sycm open','sycm run','sycm mutation plan','sycm mutation apply'].includes(command)) {
+    const update=await checkUpdate({automatic:true});
+    if(update.available)process.stderr.write('Ecom CLI update available: '+update.latest+'\n');
+    if(command==='sycm run')return runRead(options);
+    if(command==='sycm open')return openOperation(options);
+    if(command==='sycm mutation plan')return planMutation(options);
+    return authorizePlan(options);
+  }
   if(command==='doctor') {
-    let instance,error;try{const found=discover(options);instance={id:found.endpoint.instanceId,pid:found.endpoint.pid,channel:found.channel};}catch(e){error={code:e.code,message:e.message};}
+    let instance,error;try{const found=discover(options);instance={id:found.endpoint.instanceId,pid:found.endpoint.pid,channel:found.channel,businessReadProtocol:found.endpoint.businessReadProtocol??0,businessPageOpenProtocol:found.endpoint.businessPageOpenProtocol??0,businessRegistryMatches:found.endpoint.businessReadRegistryHash===nativeRegistryHash()};}catch(e){error={code:e.code,message:e.message};}
     return {ok:!error,package:pkg.name,version:pkg.version,node:process.version,platform:process.platform,transport:'private-local-mailbox',debuggingRequired:false,instance,...(error?{error}:{}),skillSource:source().path};
   }
   if(['containers list','containers inspect','session request'].includes(command)) {

package/lib/maintenance.mjs

@@ -92,6 +92,11 @@ export function installSkill(options,base=root) {
   } finally {fs.closeSync(fd);fs.unlinkSync(lock);}
 }
 const cacheRoot=()=>path.join(os.homedir(),'.cache','ecom-cli');
+export function newerStableVersion(candidate,current) {
+  const a=candidate.split('.').map(Number),b=current.split('-')[0].split('.').map(Number);
+  for(let i=0;i<3;i++){if(a[i]!==b[i])return a[i]>b[i];}
+  return current.includes('-');
+}
 export async function checkUpdate({automatic=false}={}) {
   if(automatic&&process.env.ECOM_CLI_UPDATE_CHECK==='0') return {ok:true,disabled:true};
   const cache=path.join(cacheRoot(),'update.json');
@@ -102,7 +107,7 @@ export async function checkUpdate({automatic=false}={}) {
     const response=await fetch('https://registry.npmjs.org/@petercjl%2fecom-cli/latest',{signal:AbortSignal.timeout(1500)});
     if(!response.ok) throw Error('registry');
     const data=await response.json();if(data.name!==pkg.name||!/^\d+\.\d+\.\d+$/.test(data.version))throw Error('shape');
-    result={ok:true,version:pkg.version,latest:data.version,available:data.version!==pkg.version,checkedAt:Date.now(),channel:'latest'};
+    result={ok:true,version:pkg.version,latest:data.version,available:newerStableVersion(data.version,pkg.version),checkedAt:Date.now(),channel:'latest'};
   }catch{result={ok:false,code:'REGISTRY_UNAVAILABLE',version:pkg.version,checkedAt:Date.now(),retained:true};}
   if(automatic) {
     try {fs.mkdirSync(cacheRoot(),{recursive:true,mode:0o700});if(!exists(cache))writeNew(cache,result);else {const archive=cache+'.previous-'+crypto.randomUUID();fs.renameSync(cache,archive);writeNew(cache,result);}}catch{/* Detection must not block read-only work. */}

package/lib/sycm-vendor/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/sycm-vendor/business-capabilities.mjs

@@ -0,0 +1,57 @@
+const rows = [
+  ['alimama-insight', 'alimama', 'fetch-analysis', '行业、竞争、流量与趋势洞察', ['categoryOrKeyword', 'dateRange'], ['insightData']],
+  ['alimama-onebp-campaign-data', 'alimama', 'fetch', '万相台活动、报表、预测与预算建议', ['dateRange'], ['campaigns', 'report', 'predictions']],
+  ['category-best-selling-items-analysis', 'category', 'analysis', '类目热销商品及特征分析', ['category', 'dateRange'], ['featureSummary']],
+  ['category-info-query', 'category', 'fetch', '类目搜索、层级与名称查询', ['categoryIdOrKeyword'], ['categories']],
+  ['category-keyword-analysis', 'category', 'analysis', '类目关键词规模、效率与机会分析', ['category', 'dateRange'], ['keywordAnalysis']],
+  ['category-market-analysis', 'category', 'analysis', '品牌、价格带、卖点与竞争格局分析', ['topItems', 'priceSegments'], ['marketStructure']],
+  ['category-market-insight', 'category', 'workflow', '类目市场洞察完整工作流', ['category', 'dateRange'], ['report', 'detailData']],
+  ['category-price-band-analysis', 'category', 'analysis', '类目价格带分布与机会分析', ['category', 'dateRange'], ['priceBandAnalysis']],
+  ['category-top-items-fetch', 'category', 'fetch', '类目榜单商品分价格带取数', ['category', 'dateRange'], ['topItems']],
+  ['category-top-items-profile', 'category', 'analysis', '类目头部商品画像', ['category', 'dateRange'], ['itemProfile']],
+  ['category-top-shops-profile', 'category', 'analysis', '类目头部店铺画像', ['category', 'dateRange'], ['shopProfile']],
+  ['competitor-comparison-action-tracking', 'competitor', 'workflow', '竞店竞品对比与运营动作跟踪', ['competitors', 'dateRange'], ['comparison', 'actions']],
+  ['competitor-shop-analysis', 'competitor', 'analysis', '竞店核心指标、流量与商品对比', ['shopIds', 'dateRange'], ['shopComparison']],
+  ['comprehensive-product-data-analysis', 'item', 'workflow', '单品销售、流量、转化、客群综合诊断', ['itemId', 'dateRange'], ['itemDiagnosis']],
+  ['daily-shop-inspection', 'shop', 'workflow', '店铺日常巡检与风险建议', ['date'], ['inspectionReport']],
+  ['dmp-shop-insight', 'dmp', 'fetch-analysis', '达摩盘全店货品经营洞察', ['dateRange'], ['shopInsight']],
+  ['item-gallery-analysis', 'item', 'analysis', '商品主图表现与结构分析', ['itemId', 'dateRange'], ['galleryAnalysis']],
+  ['item-ops-event-impact-analysis', 'item', 'analysis', '运营动作前后影响分析', ['itemId', 'eventDate'], ['impactAnalysis']],
+  ['item-promotion-analysis', 'promotion', 'analysis', '商品付费推广效果分析', ['itemId', 'dateRange'], ['promotionAnalysis']],
+  ['item-search-word-fetch', 'item', 'fetch', '商品全量搜索词与核心词取数', ['itemId', 'dateRange'], ['searchWords']],
+  ['item-traffic-analysis', 'item', 'analysis', '商品渠道流量结构分析', ['itemId', 'dateRange'], ['trafficAnalysis']],
+  ['item-traffic-fluctuation-analysis', 'item', 'analysis', '商品流量异动定位', ['itemId', 'dateRange'], ['fluctuationAnalysis']],
+  ['market-blue-ocean-opportunity-mining', 'market', 'analysis', '蓝海类目与关键词机会发现', ['categoryScope', 'dateRange'], ['opportunities']],
+  ['marketing-price-check-pro', 'promotion', 'workflow', '本地价盘与线上价格批量核对', ['priceSheet', 'date'], ['priceRiskReport']],
+  ['mkt_insight-consumer-couponfee', 'promotion', 'fetch', '消费券费用、订单与结算明细查询', ['dateRange'], ['couponFees', 'orders']],
+  ['mkt_insight-marketing-knowledge', 'promotion', 'knowledge', '营销与价格规则知识问答', ['question'], ['answer']],
+  ['shop-core-index-analysis', 'shop', 'analysis', '店铺销售、流量与转化核心指标分析', ['dateRange'], ['coreIndexAnalysis']],
+  ['shop-core-potential-item-analysis', 'shop', 'analysis', '核心品、潜力品与引流款识别', ['dateRange'], ['itemPortfolio']],
+  ['shop-inspection-problem-info', 'shop', 'fetch', '店铺巡检预警与异常项查询', ['date'], ['problems']],
+  ['sycm-category-query', 'category', 'fetch', '批量类目 ID 转名称', ['categoryIds'], ['categoryNames']],
+  ['sycm-flow-itemsource-helper', 'item', 'fetch', '商品流量来源、趋势与下钻查询', ['itemId', 'dateRange'], ['trafficSources']],
+  ['sycm-item-competitor-analysis', 'competitor', 'fetch-analysis', '本品与竞品指标、趋势、来源、搜索词对比', ['itemId', 'competitorItemIds', 'dateRange'], ['competitorData']],
+  ['sycm-item-data-fetch', 'item', 'fetch', '商品排行、销售、退款、价格、标题、详情、流量和客群取数', ['itemIdOrScope', 'dateRange'], ['itemData']],
+  ['sycm-item-rank-helper', 'item', 'workflow', '店铺商品排行与单品分析入口', ['scope', 'dateRange'], ['itemRanking']],
+  ['sycm-market', 'market', 'fetch', '类目、市场排行、搜索排行与搜索词取数', ['categoryOrKeyword', 'dateRange'], ['marketData']],
+  ['sycm-market-competitive-product', 'competitor', 'fetch', '竞品流失、竞争监控与竞店数据取数', ['scope', 'dateRange'], ['competitionData']],
+  ['weekly-or-monthly-store-performance-reports', 'report', 'report', '店铺经营周报或月报', ['period'], ['markdownReport']]
+];
+
+export const businessCapabilities = rows.map(([id, domain, kind, summary, inputs, outputs]) => ({
+  id, domain, kind, summary, inputs, outputs, sideEffect: 'none'
+}));
+
+export const mutationCapabilities = [
+  { id: 'qianniu-product-batch-draft', domain: 'product', summary: '批量创建商品草稿', requiredFields: ['products'], entryUrl: 'https://myseller.taobao.com/', steps: ['validate-products', 'open-product-draft-editor', 'create-drafts-only', 'read-back-draft-ids'], verification: 'Every requested product has a returned draft ID; no product is published.' },
+  { id: 'product-migration-guide', domain: 'product', summary: '商品迁移与发布配置', requiredFields: ['sourceProducts', 'targetMode'], entryUrl: 'https://myseller.taobao.com/', steps: ['read-source-products', 'validate-target-category-and-properties', 'create-target-drafts', 'read-back-draft-ids'], verification: 'Target drafts exist and retain the approved category, SKU, media and price configuration.' },
+  { id: 'search-recommend-publish', domain: 'publish', summary: '搜索推荐内容发布', requiredFields: ['content', 'target'], entryUrl: 'https://myseller.taobao.com/', steps: ['validate-content-and-target', 'open-search-recommend-publisher', 'preview', 'publish', 'read-back-publication-status'], verification: 'Publication ID, target and status match the authorized plan.' },
+  { id: 'video-publish-item', domain: 'publish', summary: '商品视频发布', requiredFields: ['itemId', 'video'], entryUrl: 'https://myseller.taobao.com/', steps: ['validate-item-and-video', 'open-item-video-editor', 'upload-or-select-video', 'preview', 'publish', 'read-back-video-status'], verification: 'The bound item shows the expected video identifier and processing or published status.' },
+  { id: 'sucai-apply', domain: 'material', summary: '素材应用到商品或内容', requiredFields: ['materials', 'target'], entryUrl: 'https://myseller.taobao.com/', steps: ['validate-materials-and-target', 'open-material-workspace', 'preview-assignment', 'apply', 'read-back-assignment'], verification: 'The target contains exactly the authorized material identifiers and positions.' },
+  { id: 'shop-index-hosting-manager_2', domain: 'shop', summary: '店铺指标托管配置', requiredFields: ['settings'], entryUrl: 'https://myseller.taobao.com/', steps: ['read-current-settings', 'diff-settings', 'preview', 'apply-settings', 'read-back-settings'], verification: 'Read-back settings equal the authorized settings diff.' },
+  { id: 'mkt_insight-a2ui-price-plan-upload-card', domain: 'promotion', summary: '价格方案上传与应用', requiredFields: ['pricePlan'], entryUrl: 'https://myseller.taobao.com/', steps: ['validate-price-plan', 'open-price-plan-uploader', 'upload-and-parse', 'preview-price-diff', 'apply', 'read-back-price-plan-status'], verification: 'Accepted rows, rejected rows, plan ID and effective status are returned.' }
+].map((entry) => ({ ...entry, kind: 'mutation', sideEffect: 'write', planRequired: true, applyConfirmationRequired: true, excludedActions: ['delete', 'refund', 'cancel', 'account', 'permission', 'payment'] }));
+
+export function findBusinessCapability(id) {
+  return [...businessCapabilities, ...mutationCapabilities].find((entry) => entry.id === id) || null;
+}

package/lib/sycm-vendor/errors.mjs

@@ -0,0 +1,26 @@
+export class CliError extends Error {
+  constructor(code, message, { exitCode = 1, details, hint } = {}) {
+    super(message);
+    this.name = 'CliError';
+    this.code = code;
+    this.exitCode = exitCode;
+    this.details = details;
+    this.hint = hint;
+  }
+
+  toJSON() {
+    return {
+      ok: false,
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.details === undefined ? {} : { details: this.details }),
+        ...(this.hint ? { hint: this.hint } : {})
+      }
+    };
+  }
+}
+
+export function invariant(condition, code, message, options) {
+  if (!condition) throw new CliError(code, message, options);
+}

package/lib/sycm-vendor/operation-registry.mjs

@@ -0,0 +1,196 @@
+import { CliError, invariant } from './errors.mjs';
+
+const operations = [
+  ['competitor.core-indexes', 'sycm', 'GET', '/mc/mq/rivalItem/analysis/getCoreIndexes.json', ['itemId', 'rivalItemId', 'dateRange']],
+  ['competitor.core-trend', 'sycm', 'GET', '/mc/mq/rivalItem/analysis/getCoreTrend.json', ['itemId', 'rivalItemId', 'dateRange']],
+  ['competitor.search', 'sycm', 'GET', '/mc/ci/free/index/rival/item/search.json', ['keyWord']],
+  ['competitor.recommend', 'sycm', 'GET', '/mc/free/rivalShop/recommend/index/item.json', ['itemId']],
+  ['competitor.flow-origin', 'sycm', 'GET', '/mc/rivaItem/analysis/getFlowSource/origin/v4/free.json', ['itemId', 'rivalItemId', 'dateRange']],
+  ['competitor.flow-paid', 'sycm', 'GET', '/mc/rivalItem/getFlowsource/qzt/participate/free.json', ['itemId', 'rivalItemId', 'dateRange']],
+  ['competitor.flow-source', 'sycm', 'GET', '/mc/mq/rivalItem/analysis/getFlowSource/v4.json', ['itemId', 'rivalItemId', 'dateRange']],
+  ['competitor.search-words', 'sycm', 'GET', '/mc/mq/rivalItem/analysis/getSearchWords.json', ['itemId', 'rivalItemId', 'dateRange']],
+  ['alimama.access', 'alimama', 'POST', '/member/checkAccess.json', [], { encoding: 'json', defaultParams: { bizCode: 'universalBP', r: 'mx_13' } }],
+  ['alimama.campaigns', 'alimama', 'POST', '/campaign/horizontal/findPage.json', [], { encoding: 'json' }],
+  ['alimama.multi-target-campaigns', 'alimama', 'POST', '/campaign/onebpSite/multiTargCampaignFindPage.json', [], { encoding: 'json' }],
+  ['alimama.member-config', 'alimama', 'POST', '/member/getMemberConfig.json', [], { encoding: 'json' }],
+  ['alimama.report-config', 'alimama', 'POST', '/report/getReportConfig.json', [], { encoding: 'json' }],
+  ['alimama.report', 'alimama', 'POST', '/report/query.json', [], { encoding: 'json' }],
+  ['alimama.effect-prediction', 'alimama', 'POST', '/algo/listEffectPrediction.json', [], { encoding: 'json' }],
+  ['alimama.budget-suggestion', 'alimama', 'POST', '/algo/getBatchBudgetSuggestion.json', [], { encoding: 'json' }]
+];
+
+const alimamaInsightOperations = [
+  ['alimama.insight.industry-categories', 1638, 'onebpSearch', [], {}],
+  ['alimama.insight.industry-strategy', 1932, 'universalBP', [], { dateType: '7' }],
+  ['alimama.insight.industry-profile', 1833, 'universalBP', [], {}],
+  ['alimama.insight.industry-subcategories', 1640, 'onebpSearch', ['cateLevel1Id'], { cateLevel1Name: '', dateType: '7' }],
+  ['alimama.insight.industry-traffic-kpi', 1749, 'onebpSearch', ['cateLevel1Id'], {}],
+  ['alimama.insight.industry-traffic-chart', 1781, 'universalBP', ['cateLevel1Id'], {}],
+  ['alimama.insight.industry-daily-interpretation', 1748, 'universalBP', ['cateLevel1Id', 'startTime', 'endTime', 'vsStartTime', 'vsEndTime'], {}],
+  ['alimama.insight.industry-daily-chart', 1782, 'universalBP', ['cateLevel1Id', 'startTime', 'endTime', 'vsStartTime', 'vsEndTime'], {}],
+  ['alimama.insight.industry-opportunities', 1528, 'universalBP', ['cateLevel1Id', 'cateLevel1Name', 'cateLevel2Id', 'cateLevel2Name'], { dateType: 7 }],
+  ['alimama.insight.compete-default-category', 1523, 'universalBP', [], {}],
+  ['alimama.insight.compete-market-penetration', 5589, 'universalBP', ['catelv2Id'], { wordType: 'E', dataType: 1 }],
+  ['alimama.insight.compete-bubble-chart', 5686, 'universalBP', ['catelv2Id'], { wordType: 'E', dataType: 1 }],
+  ['alimama.insight.compete-my-items', 5958, 'universalBP', ['catelv2Id'], {}],
+  ['alimama.insight.compete-excellent-items', 5961, 'universalBP', ['catelv2Id'], { custLevel: '不限', cmpId: '3' }],
+  ['alimama.insight.traffic-shop-categories', 870, 'universalBP', [], {}],
+  ['alimama.insight.traffic-rank-list', 1463, 'universalBP', [], { needGray: true, isWordRankShow: 1 }],
+  ['alimama.insight.traffic-hot-words', 1524, 'universalBP', [], { needGray: true }],
+  ['alimama.insight.traffic-favorites', 1464, 'universalBP', [], {}],
+  ['alimama.insight.trend-topic-list', 6687, 'onebpSearch', [], { tab: 'member_item_search' }],
+  ['alimama.insight.trend-topic-overview', 15884, 'onebpSearch', ['topicId'], { topicName: '', topicCate: '', brandSource: '', brandType: '', tab: 'member_item_search' }],
+  ['alimama.insight.trend-topic-keywords', 15899, 'onebpSearch', ['topicId'], { topicName: '', topicCate: '', brandSource: '', brandType: '', tab: 'member_item_search' }],
+  ['alimama.insight.trend-topic-crowd', 4273, 'onebpSearch', ['topicId'], { topicName: '', topicCate: '', brandSource: '', brandType: '', tab: 'member_item_search' }]
+].map(([id, moduleId, bizCode, requiredParams, defaultParams]) => [id, 'alimama', 'POST', '/cube/triggerDynamicModule.json', requiredParams, {
+  encoding: 'json', requestShape: 'alimama-dynamic-module', moduleId, bizCode, accessBizCode: 'universalBP', defaultParams
+}]);
+
+operations.push(...alimamaInsightOperations);
+
+const sycmItemOperations = [
+  ['item.category-search', '/cc/common/category/getStdCate.json', ['keyWord']],
+  ['item.diagnose-core', '/cc/diagnose/coreIndex.json', ['itemId', 'dateRange'], { defaultParams: { dateType: 'recent30', crowdType: 'all' } }],
+  ['item.profile', '/cc/item/archive/profile.json', ['itemId']],
+  ['item.detail-list', '/cc/item/detail/analysis/list.json', ['itemId', 'dateRange'], { defaultParams: { dateType: 'day', byrType: 'all' } }],
+  ['item.loss-overview', '/cc/item/detail/analysis/loss/overview.json', ['itemId', 'dateRange']],
+  ['item.detail-overview', '/cc/item/detail/analysis/overview.json', ['itemId', 'dateRange'], { defaultParams: { dateType: 'day', byrType: 'all' } }],
+  ['item.main-pic-material', '/cc/item/detail/main/pic/analysis/material.json', ['itemId', 'dateRange'], { defaultParams: { dateType: 'day', byrType: 'all', orderBy: 'itemExposeUv', order: 'desc', page: '1', pageSize: '10', contentType: '', indexCode: 'itemExposeUv,itemInteractUv,itemPayUv,itemLossUv,itemLossRate,itemPayConvertRate' } }],
+  ['item.rank-live', '/cc/item/live/view/top.json', []],
+  ['item.price-info', '/cc/item/price/info.json', ['itemId']],
+  ['item.sale-overview', '/cc/item/sale/overview.json', ['itemId', 'dateRange'], { defaultParams: { dateType: 'day', device: '0' } }],
+  ['item.title-trend', '/cc/item/title/v2/diagnosis/trend.json', ['itemId', 'dateRange']],
+  ['item.title-score', '/cc/item/title/v2/titleScore.json', ['itemId']],
+  ['item.title-word-list', '/cc/item/title/v2/word/list.json', ['itemId', 'dateRange']],
+  ['item.title-word-recommend', '/cc/item/title/v2/word/recommend.json', ['itemId']],
+  ['item.title-words', '/cc/item/v2/getTitleWords.json', ['itemId', 'dateRange']],
+  ['item.dmp-product', '/cc/item/view/dmp/newproduct.json', ['itemId', 'dateRange']],
+  ['item.dmp-product-top', '/cc/item/view/dmp/newproduct/top.json', ['itemIdList', 'dateRange']],
+  ['item.rank', '/cc/item/view/top.json', ['dateRange'], { defaultParams: { dateType: 'recent7', page: '1', pageSize: '20' } }],
+  ['item.sale-live-overview', '/cc/live/item/sale/overview.json', ['itemId']],
+  ['item.sale-live-attributes', '/cc/live/item/sale/sku/attrDetail.json', ['itemId']],
+  ['item.sale-live-skus', '/cc/live/v2/item/sale/sku/list.json', ['itemId']],
+  ['item.rank-long-period', '/cc/long/period/nodistinct/item/view/top.json', ['dateRange']],
+  ['item.refund-skus', '/cc/refund/item/sku/list.json', ['itemId', 'dateRange']],
+  ['item.super-sku-overview', '/cc/supersku/overview.json', ['itemId', 'dateRange']],
+  ['item.refund-close-overview', '/csp/api/refund/item/close/overview.json', ['itemId', 'dateRange']],
+  ['item.refund-live-overview', '/csp/api/refund/item/live/overview.json', ['itemId']],
+  ['item.refund-live-trend', '/csp/api/refund/item/live/trend.json', ['itemId']],
+  ['item.refund-reasons', '/csp/api/refund/item/reason/list/v2.json', ['itemId', 'dateRange']],
+  ['item.refund-live-warnings', '/csp/api/refund/item/warn/live.json', ['itemId']],
+  ['item.flow-source-tree', '/flow/item/source/tree/support.json', ['itemId', 'dateRange'], { defaultParams: { dateType: 'day', orderBy: 'uv', order: 'desc', page: '1', pageSize: '10', activateBoost: 'sourceChannel', crowdType: 'all', flowBizType: 'classic', indexCode: 'uv,cltItmCnt,cartByrCnt,payByrCnt' } }],
+  ['item.flow-source-tree-v3', '/flow/v6/item/crowdtype/source/v3.json', ['itemId', 'dateRange'], { defaultParams: { dateType: 'day', device: '2', belong: 'all', orderBy: 'uv', order: 'desc', page: '1', pageSize: '10', indexCode: 'uv,cartByrCnt,payByrCnt' } }],
+  ['item.customer-loss-risk', '/mc/item/customers/lossrisk.json', ['itemId', 'dateRange']],
+  ['item.loss-rank', '/mc/item/detail/analysis/loss/rank.json', ['itemId', 'dateRange']],
+  ['item.price-band', '/mc/item/price/band/info/v3.json', ['itemId', 'dateRange']],
+  ['item.aftersales-trend', '/qos/aftersales/item/trend.json', ['itemId', 'dateRange']]
+].map(([id, path, requiredParams, options]) => [id, 'sycm', 'GET', path, requiredParams, options]);
+
+const sycmCompetitionOperations = [
+  ['competition.active-status', '/mc/ci/free/active/status.json', []],
+  ['competition.valid-group', '/mc/ci/free/config/rival/group/hasValidGroup.json', []],
+  ['competition.group-items', '/mc/ci/free/config/rival/group/listItemsBySourceType.json', ['sourceType']],
+  ['competition.monitored-shops-excluding-great', '/mc/ci/free/config/rival/shop/getMonitoredListExcludeGreatShop.json', []],
+  ['competition.item-monitor-list', '/mc/ci/free/item/monitor/list/page.json', []],
+  ['competition.item-state', '/mc/ci/free/item/state.json', ['itemId']],
+  ['competition.shop-monitor-list', '/mc/ci/free/v2/shop/monitor/listShop/page.json', []],
+  ['competition.search-drain-detail', '/mc/free/ci/item/search/drain/detail.json', ['itemId', 'dateRange']],
+  ['competition.search-drain-recognition', '/mc/free/ci/item/search/drain/recognition.json', ['dateRange']],
+  ['competition.view-drain-detail', '/mc/free/ci/item/view/drain/detail.json', ['itemId', 'dateRange']],
+  ['competition.view-drain-recognition', '/mc/free/ci/item/view/drain/recognition.json', ['dateRange']],
+  ['competition.item-monitor-list-live', '/mc/free/live/ci/item/monitor/list/page.json', []],
+  ['competition.shop-monitor-list-live', '/mc/free/live/ci/shop/monitor/listShop/page.json', []],
+  ['competitor.shop-core-live', '/mc/free/rivalShop/analysis/getCoreIndexesLive.json', ['sellerId']],
+  ['competitor.shop-trend-live', '/mc/free/rivalShop/analysis/getCoreTrendLive.json', ['sellerId']],
+  ['competitor.shop-top-items-live', '/mc/free/rivalShop/analysis/getLiveTopItems/page.json', ['sellerId']],
+  ['competitor.shop-highlight', '/mc/mq/mkt/offline/rival/highlight.json', ['sellerId', 'dateRange']],
+  ['competitor.shop-operation-summary', '/mc/mq/mkt/offline/rival/operation/summary.json', ['sellerId', 'dateRange']],
+  ['competitor.shop-strategy', '/mc/mq/mkt/offline/rival/strategy.json', ['sellerId', 'dateRange']],
+  ['competitor.group-core-indexes', '/mc/mq/rivalItem/analysis/group/getCoreIndexes.json', ['groupId', 'dateRange']],
+  ['competitor.shop-core', '/mc/mq/rivalShop/analysis/getCoreIndexes.json', ['sellerId', 'dateRange']],
+  ['competitor.shop-trend', '/mc/mq/rivalShop/analysis/getCoreTrend.json', ['sellerId', 'dateRange']],
+  ['competitor.shop-flow-source', '/mc/mq/rivalShop/analysis/getFlowSource/v4.json', ['sellerId', 'dateRange']],
+  ['competitor.shop-search-words', '/mc/mq/rivalShop/analysis/getSearchWords.json', ['sellerId', 'dateRange']],
+  ['competitor.shop-crowd', '/mc/mq/rivalShop/analysis/getShopCrowd.json', ['sellerId', 'dateRange']],
+  ['competitor.shop-top-items', '/mc/mq/rivalShop/analysis/getTopItems/page.json', ['sellerId', 'dateRange']],
+  ['competitor.shop-profile-check', '/mc/mq/rivalShop/checkProfile.json', ['sellerId']],
+  ['competitor.shop-profile', '/mc/mq/rivalShop/profile/detail.json', ['sellerId']],
+  ['competitor.shop-flow-origin', '/mc/rivalShop/analysis/getFlowSource/origin/v4/free.json', ['sellerId', 'dateRange']],
+  ['competitor.shop-flow-overview', '/mc/rivalShop/analysis/getFlowSource/overview/v4.json', ['sellerId', 'dateRange']],
+  ['competitor.shop-flow-paid', '/mc/rivalShop/getFlowsource/qzt/participate/free.json', ['sellerId', 'dateRange']]
+].map(([id, path, requiredParams]) => [id, 'sycm', 'GET', path, requiredParams]);
+
+operations.push(...sycmItemOperations, ...sycmCompetitionOperations);
+
+operations.push(
+  ['shop.trade-summary', 'sycm-trade', 'GET', '/bda/tradinganaly/overview/get_summary.json', ['dateRange'], { defaultParams: { dateType: 'recent7', device: '0' } }],
+  ['shop.trade-categories', 'sycm-trade', 'GET', '/bda/tradinganaly/overview/getCateTop.json', ['dateRange'], { defaultParams: { dateType: 'recent7' } }],
+  ['shop.trade-trend', 'sycm-trade', 'GET', '/bda/tradinganaly/overview/getTendency.json', ['categoryId', 'dateRange', 'indexs'], { defaultParams: { dateType: 'recent7', device: '0', diff: '0' } }]
+);
+
+operations.push(
+  ['dmp.shop-standard-categories', 'dmp', 'GET', '/api/dmp/shop/std/cate', [], { defaultParams: { cateModel: '2', filterModel: '0' } }],
+  ['dmp.shop-categories', 'dmp', 'GET', '/api/goods/cate/list', ['endDate'], { defaultParams: { period: '30', page: '1', pageSize: '10' } }],
+  ['dmp.shop-date-range', 'dmp', 'GET', '/api/goods/shop/dateRange', []],
+  ['dmp.shop-item-indicators', 'dmp', 'GET', '/api/goods/shop/item/indicators', [], { defaultParams: { type: '1' } }],
+  ['dmp.shop-items', 'dmp', 'GET', '/api/goods/shop/item/list', ['endDate'], { defaultParams: { period: '30', page: '1', pageSize: '20' } }],
+  ['dmp.shop-labels', 'dmp', 'GET', '/api/goods/shop/label/list', []],
+  ['dmp.shop-overview', 'dmp', 'GET', '/api/goods/shop/v3/overview', ['endDate'], { defaultParams: { period: '30', benchmark: '0' } }]
+);
+
+operations.push(
+  ['coupon.page-detail', 'coupon', 'GET', '/consumercoupon/renderCouponPageDetailView.do', []],
+  ['coupon.fee-init', 'coupon', 'GET', '/consumercoupon/getFeeInitInfo.do', []],
+  ['coupon.fee-groups', 'coupon', 'GET', '/consumercoupon/getFeeGroupList.do', ['startTime', 'endTime']],
+  ['coupon.fee-rule', 'coupon', 'GET', '/consumercoupon/getFeeRuleInfo.do', ['date']],
+  ['coupon.fee-rules', 'coupon', 'GET', '/consumercoupon/getFeeRuleInfoList.do', ['startTime', 'endTime']],
+  ['coupon.day-fee-summary', 'coupon', 'GET', '/consumercoupon/getDayFeeInfo.do', ['time']],
+  ['coupon.day-fee-detail', 'coupon', 'GET', '/consumercoupon/getDayFeeInfoDetail.do', ['time']],
+  ['coupon.day-fee-list', 'coupon', 'GET', '/consumercoupon/getDayFeeInfoListV2.do', ['startTime', 'endTime']],
+  ['coupon.detail-day-list', 'coupon', 'GET', '/consumercoupon/getDayVOList.do', ['startTime', 'endTime']],
+  ['coupon.download-tasks', 'coupon', 'GET', '/list/asyncTaskList/queryListData.do', ['processorKey', 'domainId']]
+);
+
+const services = {
+  sycm: { origin: 'https://sycm.taobao.com', entryUrl: 'https://sycm.taobao.com/mc/mq/market_monitor.htm', hosts: ['sycm.taobao.com'], tokenStrategy: 'sycm-meta' },
+  'sycm-trade': { origin: 'https://sycm.taobao.com', entryUrl: 'https://sycm.taobao.com/fa/trade/detail?activeKey=overview', hosts: ['sycm.taobao.com'], tokenStrategy: 'sycm-meta' },
+  alimama: { origin: 'https://one.alimama.com', entryUrl: 'https://one.alimama.com/', hosts: ['one.alimama.com'], tokenStrategy: 'alimama-access' },
+  dmp: { origin: 'https://dmp.advgateway.taobao.com', entryUrl: 'https://dmp.taobao.com/index_new.html#!/items/shop-insight', hosts: ['dmp.taobao.com'], tokenStrategy: 'dmp-magix' },
+  coupon: { origin: 'https://sale.taobao.com', entryUrl: 'https://myseller.taobao.com/home.htm/coupon_marketing/home?tab=fee', hosts: ['myseller.taobao.com', 'sale.taobao.com'], matchPath: '/home.htm/coupon_marketing/', tokenStrategy: 'taobao-cookie' }
+};
+
+export const operationRegistry = Object.freeze(Object.fromEntries(operations.map(([id, service, method, path, requiredParams, options = {}]) => [id, {
+  id, service, method, path, requiredParams, sideEffect: 'none', ...options
+}])));
+
+export function getService(id) {
+  const service = services[id];
+  if (!service) throw new CliError('UNKNOWN_SERVICE', `Unknown browser service: ${id}`, { exitCode: 2 });
+  return service;
+}
+
+export function getOperation(id) {
+  const operation = operationRegistry[id];
+  if (!operation) throw new CliError('UNKNOWN_OPERATION', `Unknown registered operation: ${id}`, { exitCode: 2, hint: 'Run sycmcli data operations.' });
+  return operation;
+}
+
+export function validateOperationParams(operation, params) {
+  invariant(params && typeof params === 'object' && !Array.isArray(params), 'INVALID_ARGUMENT', 'Operation params must be a JSON object.', { exitCode: 2 });
+  const missing = operation.requiredParams.filter((key) => params[key] === undefined || params[key] === null || params[key] === '');
+  invariant(missing.length === 0, 'MISSING_ARGUMENT', `Missing operation parameters: ${missing.join(', ')}.`, { exitCode: 2 });
+  if (operation.id.startsWith('alimama.insight.industry-')) {
+    if (params.dateType !== undefined) invariant([7, 15, 30, '7', '15', '30'].includes(params.dateType), 'INVALID_ARGUMENT', 'Industry dateType must be 7, 15, or 30.', { exitCode: 2 });
+    for (const key of ['startTime', 'endTime', 'vsStartTime', 'vsEndTime']) {
+      const value = params[key];
+      if (value !== undefined && value !== null) invariant(typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value, 'INVALID_ARGUMENT', `${key} must be a valid YYYY-MM-DD date.`, { exitCode: 2 });
+    }
+    if (params.startTime && params.endTime) invariant(params.startTime <= params.endTime, 'INVALID_ARGUMENT', 'startTime must not follow endTime.', { exitCode: 2 });
+    if (params.vsStartTime && params.vsEndTime) invariant(params.vsStartTime <= params.vsEndTime, 'INVALID_ARGUMENT', 'vsStartTime must not follow vsEndTime.', { exitCode: 2 });
+  }
+  return params;
+}
+
+export function listOperations() {
+  return Object.values(operationRegistry).map((operation) => ({ ...operation, ...getService(operation.service), origin: getService(operation.service).origin }));
+}

package/lib/sycm-vendor/provenance.json

@@ -0,0 +1,12 @@
+{
+  "package": "@petercjl/sycmcli",
+  "version": "0.4.0",
+  "license": "MIT",
+  "repository": "https://github.com/petercjl/sycmcli",
+  "files": {
+    "operation-registry.mjs": "bd41f205b22e1f6c02661defa61b39523f4714d839510ba61991575d2a34ff00",
+    "business-capabilities.mjs": "e3b1fec7152f5cc8f1f1aef7c36ebce42e5a0cb620e217c074b32921b0a15d2e",
+    "errors.mjs": "098faaf49430f93acdfc6601920a7e3a6e6baa6f978dbcc1b81b7d87ee1d6974",
+    "LICENSE": "cb0b6cc0ee0a14ca9f59f841b3743b9974968009ae536a7d27d6457f54e9ff39"
+  }
+}

package/lib/sycm.mjs

@@ -0,0 +1,208 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import {fail,exists,privatePath,writeNew} from './common.mjs';
+import {discover,requestInConnection,registeredReadInConnection,openBusinessPageInConnection,callMailbox,resolveContainer} from './browser.mjs';
+import {listOperations,operationRegistry,getService,validateOperationParams} from './sycm-vendor/operation-registry.mjs';
+import {businessCapabilities,mutationCapabilities} from './sycm-vendor/business-capabilities.mjs';
+
+const ORIGIN='https://sycm.taobao.com';
+// Additional first-class reads implemented outside the source registry in src/sycm.mjs.
+const legacyReads=[
+ ['category.tree','/mc/common/free/getCateInfo.json',[],{marketVersion:'free'}],
+ ['category.main','/portal/shop/getMainCateInfo.json',[],{}],
+ ['market.item-rank','/mc/mq/mkt/item/offline/rank.json',['cateId','dateRange'],{rankType:'gmv',indexCode:'payByrCnt,uv',page:1,pageSize:10,marketVersion:'free',sellerType:'-1',cateFlag:'2'}],
+ ['market.item-flow-rank','/mc/mq/mkt/item/offline/rank/search.json',['cateId','dateRange'],{rankType:'flow',indexCode:'uv,searchUv',page:1,pageSize:10,marketVersion:'free',sellerType:'-1',cateFlag:'2'}],
+ ['market.item-add-rank','/mc/mq/mkt/item/offline/rank/purpose.json',['cateId','dateRange'],{rankType:'add',indexCode:'cartByrCnt,cltByrCnt,uv',page:1,pageSize:10,marketVersion:'free',sellerType:'-1',cateFlag:'2'}],
+ ['market.price-segments','/mc/mq/mkt/priceSeg/list.json',['cateId','dateRange'],{sellerType:'0',marketVersion:'free'}],
+ ['market.keyword-rank','/mc/mq/mkt/keyword/rank/pro.json',['cateId','dateRange'],{kwType:'search',order:'desc',orderBy:'seIpvUvHits',rankType:'hot',page:1,pageSize:10,marketVersion:'free',device:'0'}],
+ ['word.overview','/mc/free/searchword/overview.json',['keyword','dateRange'],{device:'0',marketVersion:'free'}],
+ ['word.trend','/mc/free/searchword/propertyTrend.json',['keyword','dateRange'],{device:'0',marketVersion:'free'}],
+ ['word.related','/mc/mq/mkt/keyword/relate/analysis.json',['keyWord','dateRange'],{cycleFlag:'cycle',order:'desc',orderBy:'seIpvUvHits',rankType:'related',page:1,pageSize:10,device:'0',marketVersion:'free'}],
+ ['word.category','/mc/mq/mkt/keyword/cate/analysis.json',['keyWord','dateRange'],{order:'desc',orderBy:'clickHitsRatio',page:1,pageSize:10,device:'0',marketVersion:'free'}]
+].map(([id,path,requiredParams,defaultParams])=>({id,service:'sycm',method:'GET',path,requiredParams,defaultParams,sideEffect:'none',source:'src/sycm.mjs'}));
+const allOperations=()=>[...listOperations(),...legacyReads];
+const resolveOperation=id=>{
+  const found=legacyReads.find(x=>x.id===id)??(Object.hasOwn(operationRegistry,id)?operationRegistry[id]:null);
+  if(!found)throw fail('UNKNOWN_OPERATION','Choose a registered operation from sycm operations');
+  return found;
+};
+
+const sensitive=/token|cookie|csrf|password|passwd|authorization|secret|sessionid|credential|api[-_]?key|^__d?tk$|^session$|^loginpointid$/i;
+export function assertPublicParams(value) {
+  if(Array.isArray(value)){for(const child of value)assertPublicParams(child);return;}
+  if(value&&typeof value==='object')for(const [key,child]of Object.entries(value)) {
+    if(sensitive.test(key)||['__proto__','constructor','prototype'].includes(key))throw fail('CREDENTIAL_INPUT_REJECTED','Use browser-managed authentication; credential or prototype fields are forbidden');
+    assertPublicParams(child);
+  }
+  if(typeof value==='string'&&/(?:token|cookie|csrf(?:id)?|password|authorization|__tk|__dtk|loginpointid)=/i.test(value))throw fail('CREDENTIAL_INPUT_REJECTED','Credential-bearing strings are forbidden');
+}
+export function paramsObject(value) {
+  if(value===undefined)return {};
+  let text=value;
+  if(!text.trimStart().startsWith('{')) {
+    const info=fs.lstatSync(text);
+    if(!info.isFile()||info.size>262144)throw fail('INVALID_ARGUMENT','Parameter input must be a JSON object or a file at most 256 KiB');
+    text=fs.readFileSync(text,'utf8');
+  }
+  if(Buffer.byteLength(text)>262144)throw fail('INVALID_ARGUMENT','Parameter input is too large');
+  let result;try{result=JSON.parse(text);}catch{throw fail('INVALID_ARGUMENT','Invalid parameter JSON');}
+  if(!result||typeof result!=='object'||Array.isArray(result))throw fail('INVALID_ARGUMENT','Parameters must be a JSON object');
+  assertPublicParams(result);return result;
+}
+const transportFor=op=>op.method==='GET'&&getService(op.service).origin===ORIGIN?'native-session-get':'adapter-required';
+export function operationSchema(id) {
+  const op=resolveOperation(id), service=getService(op.service);
+  return {...op,origin:service.origin,entryUrl:service.entryUrl,tokenStrategy:service.tokenStrategy,transport:'native-business-read',legacyTransport:transportFor(op),runtimeVerified:false,
+    minimumBrowserCapability:'businessReadProtocol=1 with matching registry hash',limits:'Credentials remain native. Per-endpoint permissions, CSRF, date semantics and service login require real validation.'};
+}
+export function nativeRegistry() {
+  return Object.fromEntries(inventory().operations.map(op=>[op.id,{
+    id:op.id,service:op.service,method:op.method,path:op.path,origin:op.origin,
+    entryUrl:op.entryUrl,tokenStrategy:op.tokenStrategy,requiredParams:op.requiredParams,
+    defaultParams:op.defaultParams??{},...(op.encoding?{encoding:op.encoding}:{}),
+    ...(op.requestShape?{requestShape:op.requestShape,moduleId:op.moduleId,bizCode:op.bizCode,accessBizCode:op.accessBizCode}:{})
+  }]));
+}
+export const nativeRegistryHash=()=>crypto.createHash('sha256').update(JSON.stringify(nativeRegistry())).digest('hex');
+export function inventory() {
+  return {ok:true,schemaVersion:1,source:{package:'@petercjl/sycmcli',version:'0.4.0',license:'MIT'},
+    operations:allOperations().map(op=>operationSchema(op.id)),businessCapabilities,
+    mutations:mutationCapabilities.map(x=>({...x,execution:'plan-and-authorization-only',automaticSubmission:false}))};
+}
+export function buildRead(id,params) {
+  const op=resolveOperation(id);assertPublicParams(params);validateOperationParams(op,params);
+  if((id.startsWith('market.')||['word.related','word.category'].includes(id))&&params.pageSize!==undefined&&(!Number.isInteger(Number(params.pageSize))||Number(params.pageSize)<1||Number(params.pageSize)>20))throw fail('INVALID_ARGUMENT','Market pageSize must be an integer from 1 through 20');
+  if(transportFor(op)!=='native-session-get')throw fail('SERVICE_ADAPTER_REQUIRED','This registered operation requires a native '+op.service+' adapter; no alternate browser will be opened');
+  const url=new URL(op.path,ORIGIN);
+  for(const [key,value]of Object.entries({...op.defaultParams,...params})) {
+    if(value===undefined||value===null)continue;
+    if(!['string','number','boolean'].includes(typeof value))throw fail('INVALID_ARGUMENT','Native GET parameters must be scalar values');
+    url.searchParams.set(key,String(value));
+  }
+  return {operation:id,service:op.service,url:url.href};
+}
+function sanitized(value) {
+  if(Array.isArray(value))return value.map(sanitized);
+  if(value&&typeof value==='object')return Object.fromEntries(Object.entries(value).map(([key,child])=>[key,sensitive.test(key)?'[REDACTED]':sanitized(child)]));
+  if(typeof value==='string'&&/(?:token|cookie|csrf(?:id)?|password|authorization|__tk|__dtk|loginpointid)=/i.test(value))return '[REDACTED]';
+  return value;
+}
+export function businessResponse(value) {
+  if(!value||typeof value!=='object'||Array.isArray(value))throw fail('BUSINESS_RESPONSE_INVALID','Missing business envelope',{executed:true});
+  for(const envelope of [value,value.content].filter(x=>x&&typeof x==='object')) {
+    const failed=(envelope.code!==undefined&&envelope.code!==null&&![0,200,'0','200','SUCCESS'].includes(envelope.code))||envelope.success===false||envelope.info?.ok===false||envelope.hasError===true;
+    if(failed) {
+      const text=String(envelope.message??envelope.msg??envelope.info?.message??'');
+      const code=/login|登录|会话|session/i.test(text)?'AUTH_REQUIRED':/验证|风控|captcha|risk/i.test(text)?'RISK_VERIFICATION_REQUIRED':/权限|授权|permission|forbidden/i.test(text)?'PERMISSION_REQUIRED':'BUSINESS_REQUEST_FAILED';
+      throw fail(code,'Platform rejected the registered read; resolve login, verification or permissions in the selected container',{executed:true});
+    }
+  }
+  if(!Object.hasOwn(value,'data')&&!Object.hasOwn(value,'result')&&!Object.hasOwn(value.content??{},'data'))throw fail('BUSINESS_RESPONSE_INVALID','Unrecognized business data envelope',{executed:true});
+  return sanitized(value);
+}
+const template=value=>typeof value==='string'&&/^##[^#]+##$/.test(value);
+const hasTemplate=value=>template(value)||Boolean(value&&typeof value==='object'&&Object.values(value).some(hasTemplate));
+// Template semantics follow the pinned sycmcli MIT Alimama insight reader.
+export function resolveModuleResponse(response,flows) {
+  const results=flows.flatMap(flow=>businessResponse(flow.response)?.data?.resultList??[]);
+  const resolve=value=>{
+    if(template(value)) {
+      const ref=value.slice(2,-2),index=ref.match(/^result\[(\d+)\]$/);
+      if(index) {
+        for(const candidate of results)if(Array.isArray(candidate?.result)&&candidate.result[Number(index[1])]!==undefined)return candidate.result[Number(index[1])];
+        return results[Number(index[1])]??value;
+      }
+      for(const candidate of results) {
+        let current=candidate;
+        for(const key of ref.replace(/\[(\d+)\]/g,'.$1').split('.'))current=current&&typeof current==='object'&&Object.hasOwn(current,key)?current[key]:undefined;
+        if(current!==undefined)return current;
+      }
+      return value;
+    }
+    if(Array.isArray(value))return value.map(resolve);
+    if(value&&typeof value==='object')return Object.fromEntries(Object.entries(value).map(([key,child])=>[key,resolve(child)]));
+    return value;
+  };
+  const resolved=resolve(response);
+  if(hasTemplate(resolved)&&!flows.length)throw fail('DATA_FLOW_EXPANSION_REQUIRED','Registered module needs native data-flow expansion; retain the operation ID and inspect browser support',{executed:true});
+  return sanitized(resolved);
+}
+export async function runRead(options,deps={}) {
+  const params=paramsObject(options['params-json']),op=resolveOperation(options.operation);
+  assertPublicParams(params);validateOperationParams(op,params);
+  if(Buffer.byteLength(JSON.stringify(params))>24576)throw fail('INVALID_ARGUMENT','Read parameters exceed the native 24 KiB limit');
+  const connection=(deps.discover??discover)(options);
+  let result;
+  if(connection.endpoint.businessReadProtocol===1)result=await (deps.registeredRequest??registeredReadInConnection)(connection,options,op.id,params,nativeRegistryHash());
+  else {
+    if(transportFor(op)!=='native-session-get')throw fail('BROWSER_UPGRADE_REQUIRED','Upgrade Ecom to native business read protocol 1 for this registered service; keep the existing container login');
+    const built=buildRead(options.operation,params);
+    result=await (deps.request??requestInConnection)(connection,{...options,url:built.url,method:'GET'});
+  }
+  try {
+    const data=businessResponse(result.data),flows=result.dataFlows??[];
+    const expanded=op.requestShape==='alimama-dynamic-module'&&hasTemplate(data)?resolveModuleResponse(data,flows):undefined;
+    const partial=Boolean(expanded&&hasTemplate(expanded));
+    return {...result,...(flows.length?{dataFlows:sanitized(flows)}:{}),...(expanded?{resolvedResponse:expanded,completeness:{complete:!partial,scope:'registered-module-response',...(partial?{reason:'Platform data flows returned successfully but some template references have no returned value; inspect resolvedResponse and do not infer missing values.'}:{})}}:{}),operation:op.id,service:op.service,data,businessStatus:partial?'partial':'success',fetchedAt:new Date().toISOString(),dataDateVerification:'caller-must-check-requested-period-and-platform-update-time'};
+  }catch(error){error.operationId=result.operationId;throw error;}
+}
+export async function openOperation(options,deps={}) {
+  const op=operationSchema(options.operation),connection=(deps.discover??discover)(options);
+  return (deps.open??openBusinessPageInConnection)(connection,options,op.id,op.entryUrl,nativeRegistryHash());
+}
+async function account(connection,selector) {
+  const list=await callMailbox(connection,{method:'shops.list'});
+  if(!Array.isArray(list.shops))throw fail('PROTOCOL_MISMATCH','Missing account metadata');
+  const row=resolveContainer(list.shops,selector);
+  await callMailbox(connection,{method:'shops.verify',containerId:row.id},60000);
+  const refreshed=await callMailbox(connection,{method:'shops.list'});
+  const current=resolveContainer(refreshed.shops,row.id);
+  if(current.state!=='ready'||!current.identity?.shopId||!current.identity?.accountId)throw fail('AUTH_REQUIRED','A verified bound platform identity is required');
+  return {id:current.id,name:current.name,identity:{shopId:String(current.identity.shopId),accountId:String(current.identity.accountId)}};
+}
+function planDirectory(create=false) {
+  const state=process.env.ECOM_CLI_STATE_DIR??path.join(os.homedir(),'.ecom-cli');
+  if(!path.isAbsolute(state))throw fail('INVALID_ARGUMENT','State directory must be absolute');
+  const dir=path.join(state,'sycm-plans');
+  for(let p=dir;p!==path.dirname(p);p=path.dirname(p))if(exists(p)&&fs.lstatSync(p).isSymbolicLink()&&!(process.platform==='darwin'&&['/var','/tmp'].includes(p)&&fs.lstatSync(p).uid===0))throw fail('UNSAFE_PATH','Plan state must use physical directories');
+  if(create)fs.mkdirSync(dir,{recursive:true,mode:0o700});privatePath(dir,true);return dir;
+}
+function planFile(id) {
+  if(!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(id??''))throw fail('INVALID_ARGUMENT','Invalid plan ID');
+  return path.join(planDirectory(),id+'.json');
+}
+const digest=value=>crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+function mutation(id) {
+  const item=mutationCapabilities.find(x=>x.id===id);
+  if(!item)throw fail('UNKNOWN_MUTATION','Choose a registered mutation from sycm capabilities');
+  return item;
+}
+export async function planMutation(options,deps={}) {
+  const cap=mutation(options.operation),payload=paramsObject(options['params-json']);
+  for(const key of cap.requiredFields)if(payload[key]===undefined||payload[key]===null)throw fail('INVALID_ARGUMENT','Missing mutation field: '+key);
+  const connection=(deps.discover??discover)(options),target=await (deps.account??account)(connection,options.container);
+  const planId=crypto.randomUUID(),confirmationCode=crypto.randomBytes(4).toString('hex').toUpperCase(),now=Date.now();
+  const plan={schemaVersion:1,planId,capabilityId:cap.id,idempotencyKey:crypto.randomUUID(),container:target,instanceId:connection.endpoint.instanceId,payload,payloadDigest:digest(payload),confirmationDigest:digest({planId,confirmationCode}),createdAt:new Date(now).toISOString(),expiresAt:new Date(now+900000).toISOString()};
+  planDirectory(true);
+  writeNew(planFile(planId),plan);
+  return {ok:true,plan:{...publicPlan(plan),confirmationCode,payload:sanitized(payload)},executed:false,automaticSubmission:false};
+}
+function loadPlan(id) {const file=planFile(id);privatePath(file);return JSON.parse(fs.readFileSync(file,'utf8'));}
+function publicPlan(plan) {
+  const {payload,confirmationDigest,...result}=plan;
+  return {...result,payloadFields:Object.keys(payload).sort(),status:exists(planFile(plan.planId)+'.authorized')?'authorized':'planned'};
+}
+export function showPlan(id) {return {ok:true,plan:publicPlan(loadPlan(id)),executed:false,automaticSubmission:false};}
+export async function authorizePlan(options,deps={}) {
+  const plan=loadPlan(options.plan),cap=mutation(plan.capabilityId),file=planFile(plan.planId)+'.authorized';
+  if(exists(file))throw fail('PLAN_ALREADY_USED','Plan already authorized; inspect it before further action');
+  if(Date.parse(plan.expiresAt)<=Date.now())throw fail('PLAN_EXPIRED','Create and review a new plan');
+  if(plan.payloadDigest!==digest(plan.payload))throw fail('PLAN_TAMPERED','Payload digest mismatch');
+  if(plan.confirmationDigest!==digest({planId:plan.planId,confirmationCode:(options.confirm??'').toUpperCase()}))throw fail('CONFIRMATION_FAILED','Wrong confirmation code');
+  const connection=(deps.discover??discover)(options),target=await (deps.account??account)(connection,options.container);
+  if(connection.endpoint.instanceId!==plan.instanceId||target.id!==plan.container.id||JSON.stringify(target.identity)!==JSON.stringify(plan.container.identity))throw fail('STORE_IDENTITY_MISMATCH','Instance, container or platform identity differs from the reviewed plan');
+  try{writeNew(file,{planId:plan.planId,authorizedAt:new Date().toISOString(),payloadDigest:plan.payloadDigest});}catch(e){if(e.code==='EEXIST')throw fail('PLAN_ALREADY_USED','Plan already authorized');throw e;}
+  return {ok:true,planId:plan.planId,status:'authorized',executed:false,automaticSubmission:false,container:target,payload:sanitized(plan.payload),workflow:{...cap,readbackRequired:true},nextAction:'Execute only the reviewed workflow using an explicitly supported browser capability; return real readback evidence. This command performs no platform mutation.'};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/ecom-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Agent CLI and portable Skill for Ecom browser containers",
   "type": "module",
   "license": "MPL-2.0",

package/scripts/validate.mjs

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import assert from 'node:assert/strict';
+import crypto from 'node:crypto';
+import {inventory,nativeRegistryHash} from '../lib/sycm.mjs';
 import {root,pkg,tree} from '../lib/common.mjs';
 const caps=JSON.parse(fs.readFileSync(path.join(root,'capabilities.json'),'utf8'));
 const skill=JSON.parse(fs.readFileSync(path.join(root,'skills/ecom-cli/package.json'),'utf8'));
@@ -8,3 +10,13 @@ assert.equal(caps.version,pkg.version);assert.equal(skill.version,pkg.version);
 assert.equal(skill.name,pkg.name);assert.ok(fs.statSync(path.join(root,'skills/ecom-cli/SKILL.md')).size>100);
 tree(path.join(root,'skills')); // Reject shared links before packing.
 console.error('Version, Skill identity and physical resource checks passed: '+pkg.version);
+
+const vendor=path.join(root,'lib/sycm-vendor');
+const provenance=JSON.parse(fs.readFileSync(path.join(vendor,'provenance.json'),'utf8'));
+for(const [name,hash]of Object.entries(provenance.files)) {
+  assert.equal(crypto.createHash('sha256').update(fs.readFileSync(path.join(vendor,name))).digest('hex'),hash,'Pinned source changed without updating provenance');
+}
+assert.equal(inventory().operations.length,caps.businessIntegration.registeredReads);
+assert.equal(nativeRegistryHash(),caps.businessIntegration.nativeRegistryHash);
+assert.ok(inventory().operations.every(x=>x.sideEffect==='none'&&['GET','POST'].includes(x.method)));
+console.error('Pinned business catalog and native identity checks passed: '+nativeRegistryHash());

package/skills/ecom-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ecom-cli
-description: List and inspect account containers in the running Ecom browser, send explicitly authorized read-only HTTPS JSON requests using a selected container session, diagnose connections, or install/update the Ecom CLI and companion Skill. Use for Ecom account metadata and native-session API access; application business logic stays with the calling workflow.
+description: Use Ecom account containers for registered Shengyicanmou data reads, local mutation planning and confirmation, account inspection, native-session requests, or CLI and companion Skill maintenance. Business analysis and operating decisions belong to the caller.
 ---
 
 # Ecom CLI
@@ -18,8 +18,22 @@ Input is an Ecom container listing/detail request, an authorized read-only endpo
 5. For a session request, require an explicit authorized read-only endpoint from the user or a trusted business capability’s registered operation. Business selection, endpoint semantics, date/metrics and interpretation belong to that caller. Run `session request --container VALUE --url HTTPS_URL --method GET --json`. GET alone does not prove an endpoint has no side effects; resolve unclear endpoint intent before submission. The CLI pins one instance and container across discovery and execution. Credentials remain native; header/body/credential inputs, redirects and HTML are unsupported. The enabled origin is controlled by Ecom, not expanded by the CLI.
 6. Require `ok=true`, protocol version 1, operation ID and matching instance/container IDs. For requests, require the JSON response contract and distinguish HTTP success from business success: `businessStatus=not-evaluated` requires the caller’s platform-specific check. Preserve structured errors and executed status. These operations do not navigate or activate tabs.
 
+## Registered business operations
+
+For business data or mutation-planning requests, read [the business contract](references/sycm.md), then return to main-line target selection. The business registry is bundled with this runtime; no external sycmcli installation, Skill or browser is required. `sycm capabilities --json` exposes the complete imported catalog and native/legacy transport requirements. A registered endpoint is not proof that the current Ecom build can execute it or that its date and permission semantics have been verified. Use `sycm schema --operation ID --json` before execution. Never substitute another date to make a request succeed.
+
+`sycm open --operation ID --container VALUE --json` is the authorized page-preparation branch: background/reuse by default, `--foreground` for explicit visible login/verification. Opening is not proof of authentication; resume the same registered read after preparation. Prefer native initialization and preserve the caller’s page-fallback preference.
+
+`sycm run --operation ID --container VALUE --params-json JSON --json` fixes the native instance and container and validates the business envelope. Verify the returned period, platform update time and requested account before reporting metrics. A successful all-zero response is not by itself proof of zero business activity.
+
+Mutation plan/apply commands create local records and return reviewed workflow instructions. They perform no website submission. Report `executed=false` and require actual executor and readback evidence before describing a platform change as completed. Existing authorization can cover the reviewed plan; a development request itself grants no real store mutation authority.
+
 ## Diagnosis and recovery
 
+- BROWSER_UPGRADE_REQUIRED: update the Ecom browser and CLI together; native business protocol 1 requires matching compiled registry hashes. Preserve the account session.
+- AUTH_CONTEXT_REQUIRED: keep the existing login; native service context may need adapter diagnosis even when the page is logged in. Report the gap rather than repeatedly requesting login.
+- SERVICE_ADAPTER_REQUIRED: report the missing native adapter and preserve the selected container. Do not switch to CDP or another browser.
+- AUTH_REQUIRED, PERMISSION_REQUIRED or RISK_VERIFICATION_REQUIRED: complete the required first-party action in this original container, then explicitly resume.
 - SHOP_NOT_READY: inspect this exact account. Complete login and platform-identity verification through its Ecom account management page; a cookie expiry or account name does not satisfy readiness. If the native adapter cannot verify identity, report that gap and stop the data request. Return to step 5 only after readiness is established.
 - SHOP_VERIFICATION_FAILED: stop; the browser’s pre-request identity check failed. Preserve the selected target and report the failure.
 - ORIGIN_NOT_ALLOWED, CREDENTIAL_INPUT_REJECTED, METHOD_UNSUPPORTED or INVALID_URL: correct the intended input within the declared contract; do not broaden browser permissions.

package/skills/ecom-cli/adapters/generic.json

@@ -9,7 +9,7 @@
       },
       "status": "implemented",
       "discovery": "Current host resolves exact Skill directory and Node.js runtime; probe CLI version and capabilities",
-      "normalization": "Preserve ok, containers, instance and error from JSON; attach exit status to metadata",
+      "normalization": "Preserve the complete structured result, including container metadata, instance and operation identity, HTTP status, platform JSON and errors; attach process exit status separately",
       "permissions": "Local execution; explicit selected-target maintenance authorization",
       "limitations": "Browser transport currently macOS only; host discovery evidence is separate",
       "capability_id": "command.execute",

package/skills/ecom-cli/capabilities.json

@@ -29,7 +29,11 @@
         "httpStatus",
         "data",
         "businessStatus",
-        "error"
+        "error",
+        "operations",
+        "plan",
+        "workflow",
+        "executed"
       ],
       "side_effects": {
         "external_mutation": false,

package/skills/ecom-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/ecom-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "type": "module"
 }

package/skills/ecom-cli/references/sycm.md

@@ -0,0 +1,40 @@
+# Ecom business capability contract
+
+Use this reference for registered reads and mutation planning. Inputs are the operation, exact container, business date/filters and authorized read or local plan intent. Output is structured data with operation/instance/container identity, a precise unsupported/authentication error, or a reviewed local mutation plan. Analysis, commercial decisions and actual submission are separate responsibilities.
+
+## Read flow
+
+1. Inspect `sycm capabilities --json` and choose the atomic operation. The snapshot includes 124 source registry operations plus 11 category/market/search endpoints from first-class functions. The 37 business descriptions are application workflows, not additional automatic APIs.
+2. Inspect `sycm schema --operation ID --json`. Supply required fields through `--params-json` as an object or JSON file. Preserve parameter spelling and date semantics. Today's realtime data requires a suitable endpoint.
+3. Locate the account with `containers list` and `containers inspect`; select its stable ID and intended instance. Execute `sycm run --operation ID --container ID --params-json JSON --json`, with `--profile` or `--instance` when needed.
+4. Native business protocol 1 covers all 135 compiled reads: 88 SYCM GET endpoints, 30 Alimama POST reads, seven DMP reads and ten coupon reads. The browser prepares service authentication inside the selected persistent container. Browser/CLI catalog hashes must agree. Older Ecom builds can use only the 88 legacy SYCM GET reads; other reads require a browser upgrade. POST describes a registered read protocol, not a mutation.
+5. `businessStatus=success` means the business envelope passed status checks. Verify period, completeness, permissions and update time separately. The browser rechecks bound shop identity before requesting. Individual endpoint live acceptance is separate from registry/transport coverage. An all-zero response alone does not establish zero business activity.
+6. Preserve operation ID and executed status on failure. Inspect unknown outcomes before retry. Login, risk challenges and service authorization are completed manually in the original container. Credentials remain browser-private; no CDP or alternative browser is used.
+
+For pagination, pin the first response instance ID and stable container ID in every subsequent call with `--instance` and `--container`; issue explicit page/pageSize reads and compose results using stable IDs. Market pageSize is limited to 20. Record termination and coverage; one page is not a full dataset. Locate categories with `category.tree` or `category.main`. These commands return API data; analysis and reports remain caller-owned.
+
+## Mutation-plan flow
+
+Seven workflows cover product drafts, migration, search/recommend publishing, video, materials, shop hosting configuration and price plans. Required fields, steps, exclusions and readback criteria are discoverable in `sycm capabilities`.
+
+1. Select the verified account and gather the required payload. Check intended changes and existing authorization.
+2. Run `sycm mutation plan --operation CAPABILITY_ID --container ID --params-json JSON --json`. It verifies the account and creates a private 15-minute plan, payload digest, idempotency key and confirmation code. Review the actual payload, target and impact with the user.
+3. `sycm mutation show --plan PLAN_ID --json` returns metadata without the payload or confirmation digest.
+4. Within authorization, run `sycm mutation apply --plan PLAN_ID --container ID --confirm CODE --json`. It rechecks instance/container/platform identity, expiry and integrity, and authorizes the plan once.
+5. The result has `executed=false`, `automaticSubmission=false` and workflow/readback instructions. This preserves the source planning contract. A real executor is a separate capability; report completion only with real submission and readback evidence. Installation/testing requires no real store mutation.
+
+Private plan state lives beneath the configured CLI state directory and is excluded from npm. Restarted instances, changed targets, expired/tampered plans, wrong codes and used plans stop authorization. Resolve the cause and review a new plan rather than bypassing checks.
+
+## Native service context
+
+SYCM uses its own homepage request token; Alimama uses its fixed checkAccess handshake; coupon reads use the container entry page cookie context; DMP uses container cookies and its fixed read-only user-info initialization endpoint, then retains the returned request context inside the browser. Website account creation and account switching remain user/platform actions. Native data requests do not create or activate tabs. Credentials are not passed through the CLI.
+
+Alimama dynamic modules can return templates. The browser expands only data-flow IDs returned by that registered module, through a fixed read endpoint, with a maximum of 16 flows and the same total timeout. The CLI returns the original redacted `data`, optional `dataFlows`, and `resolvedResponse` when expansion is needed. Failed flows are errors. Successful flows with missing template values return `businessStatus=partial` and `completeness.complete=false`; do not treat a template or missing value as business data. Missing browser expansion returns DATA_FLOW_EXPANSION_REQUIRED. Plain member configuration reads may need an explicit `bizCode` such as the service's `universalBP`; inspect business semantics rather than assuming empty parameters will succeed.
+
+`AUTH_CONTEXT_REQUIRED` can indicate an adapter-context gap even when the visible service is logged in. Preserve the existing login and report the exact failure; repeated user login is not the default recovery. `BROWSER_UPGRADE_REQUIRED` requires matching browser and CLI catalogs. Per-endpoint business permission and actual dates remain separate acceptance checks. Read parameter JSON is limited to 24 KiB; results to 2 MiB; the client waits up to 75 seconds.
+
+## Authorized page fallback
+
+Prefer native reads and native service initialization. If an entry must prepare a service session and the caller authorizes page fallback, use `sycm open --operation ID --container ID --instance INSTANCE --json`. It selects the compiled first-party entry, preserves the account homepage and container ID, and opens/reuses a background container tab. `--foreground` explicitly opens a foreground tab when the user needs to log in or verify. No arbitrary URL, browser profile or JavaScript input is accepted by this command.
+
+A navigation result is not a login check. Preserve the original target and let the platform finish loading; the user handles any login, authorization or CAPTCHA. Resume the registered read only after the required preparation. Do not use a different container or copy credentials. Once a valid service session is established, native requests continue without routine page opening. An HTTP/context failure does not automatically prove expiration: inspect the bounded phase/network diagnostics before requesting another login.