@petercjl/taobao-ai-ops 0.1.0 → 0.1.1

package/README.md

@@ -1,38 +1,45 @@
-# 淘宝 AI 运营
+# 淘宝 AI 运营套件
 
-面向淘宝电商工作者的独立 SOP Skill 套件。当前版本包含运营路由、预策类目机会研究和淘宝搜索商品形态研究。类目研究支持本地 Excel 与授权 NAS/预策取数；商品研究接受搜索结果表。每个节点独立执行，报告保留其原有方法和完整证据。
+面向员工的统一管理入口。研究 Skill 和工具插件各自拥有独立 npm 包、源码和发布版本；套件只维护组件清单、安装更新、Skill发现与业务路由。
 
-```sh
-taobao-ai-ops nodes list --json
-taobao-ai-ops doctor --node category-research --mode excel --json
-taobao-ai-ops doctor --node product-research --json
-taobao-ai-ops skill source --name yuce-category-opportunity-report --json
-taobao-ai-ops skill install --agent codex --profile research --json
-```
-
-正式版本使用默认 `latest` 通道；跨 Agent 的完整验收范围见下文。安装后按需运行 `skill install`，服务访问仍需单独配置。
+## 安装与更新
 
 ```sh
 npm install --global @petercjl/taobao-ai-ops
-taobao-ai-ops version
-taobao-ai-ops skill install --agent codex --profile research --json
+taobao-ai-ops components install --agent codex --yes --json
+taobao-ai-ops doctor --json
+taobao-ai-ops update check --json
+taobao-ai-ops update install --agent codex --yes --json
 ```
 
-开发时用 `node bin/taobao-ai-ops.mjs` 执行。Node >=20，Python 依赖见 requirements.txt，可运行 `python -m pip install -r requirements.txt`；可通过 TAOBAO_AI_OPS_PYTHON 指定稳定解释器。CLI 也发现 Agent 管理的 Python 和已有商品研究环境。已有独立 Skill 先检查 `skill status`；明确授权迁移后使用 `--adopt`，CLI 会保留恢复点。
+SealSeek 用户改用 --agent sealseek。目标有歧义时通过 SEALSEEK_SKILLS_DIR 指定。已有非套件管理的 Skill 会阻止覆盖；明确授权迁移后用 --adopt，保留完整备份。本地修改会阻止更新。
+
+首次安装会获取清单中全部独立组件的正式 latest。统一更新检查套件及每个组件：套件版本不变也会更新组件。已安装组件的 Skill 同步可用 skill update；该命令只同步本地安装内容，不查询注册表。日常业务调用不更新环境，任务中保持已安装版本。
+
+组件在用户状态目录中独立安装，不随套件自身重新安装而被删除。更新先准备新安装目录，核对包身份、版本与 CLI 返回的 Skill 来源，再同步受管理 Skill。npm、来源验证或 Skill 同步失败时保留旧组件记录；Skill 同步有完整备份和恢复机制。离线检查失败时报告并保留当前环境。
 
-新安装默认在 macOS 使用链接、Windows 使用受管理副本。已有 Skill 迁移使用 `--adopt`，完整备份并校验；受管理本地修改会阻止覆盖。SealSeek 根目录可用 SEALSEEK_SKILLS_DIR 指定，发现歧义时会明确报错。
+## 组件
+
+- @petercjl/yuce-category-opportunity-report：24个月类目数据与相对容量路线、增长分析、双视图 HTML。
+- @petercjl/taobao-search-product-form：搜索结果数据和商品形态研究、机会判断卡及 HTML。
+- @petercjl/tbcli：淘宝数据与 NAS 数据库工具，含其独立 Skill。
+- @petercjl/sycmcli：店铺经营数据工具，含其独立 Skill。
+- taobao-ai-operations：套件自带的管理与业务路由 Skill。
+
+yccli 为取数时按需准备的外部工具，可用 TAOBAO_AI_OPS_YCCLI 指定；Excel 分析不需要 NAS、VPN 或平台登录。账号与授权留在包外，安装不会获得服务权限。
+
+## 调用与开发
 
 ```sh
+taobao-ai-ops components status --json
+taobao-ai-ops components check --json
+taobao-ai-ops skill source --name yuce-category-opportunity-report --json
 taobao-ai-ops script category-research build_report.py --help
-taobao-ai-ops script product-research clean_search_export.mjs SOURCE.xlsx CLEANED.xlsx
 taobao-ai-ops tool run tbcli capabilities --json
-taobao-ai-ops workflow plan --run-dir NEW_RUN --node product-research --input SOURCE.xlsx --json
 ```
 
-tbcli 0.10.4 与 sycmcli 0.3.1 是固定版本依赖，通过套件解析的实际入口调用，执行时关闭其独立自动更新。yccli 是按需发现的外部工具，可由 TAOBAO_AI_OPS_YCCLI 指定。Excel 分析不要求 NAS、VPN 或平台登录。服务账号和业务数据由使用者提供，包内不含凭证。
-
-节点的业务判断和图像审阅由 Agent 完成。doctor 验证确定性运行资源，并将原生图像能力列为需当前 Agent 核实；它不宣称完整业务回归通过。目标为 Codex/macOS、SealSeek/macOS 与 Windows，统一套件的真实跨 Agent 验收尚待完成。
+维护者分别发布各能力包的正式 latest。新增/移除组件或调整管理机制时才发布套件。源码开发可通过 components register --name ID --path CHECKOUT --yes 注册独立组件；开发记录由 Git 管理，不会被注册表更新覆盖。已安装 npm 组件的显式接入可加 --mode npm。源码套件自身通过 Git 更新。
 
-套件手动检查更新，运行期间使用固定版本；开发源码通过 Git 更新。已发布全局安装可用 `update install --agent AGENT --yes` 更新同一 npm prefix 的包与受管理 Skill，失败恢复旧包。安装、更新不发布商品或修改广告。
+Node >=20。Python 研究依赖通过稳定解释器准备；TAOBAO_AI_OPS_PYTHON 可指定已配置解释器。脚本和报告模板来自实际组件目录。原生图片理解由当前 Agent 提供；缺失时报告而非缩减流程。
 
-目前合并范围是研究链第一批。供应链、内容制作、经营复盘按后续阶段接入。来源记录在 suite-manifest.json；旧独立包仍保留作历史与过渡，后续维护以本套件的迁入节点为准。
+本地 macOS 确定性安装、更新与恢复测试单独记录；Windows/SealSeek 的真实宿主安装和端到端行为尚待验证。CI 发布前须先有可安装的类目独立包；所有发布通过 GitHub Actions OIDC。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/taobao-ai-ops",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Independent Taobao AI operations SOP skills with a managed suite lifecycle",
   "repository": {
     "type": "git",
@@ -17,7 +17,7 @@
   "files": [
     "bin",
     "src",
-    "skills",
+    "skills/taobao-ai-operations",
     "contracts",
     "suite-manifest.json",
     "requirements.txt",
@@ -37,10 +37,5 @@
     "test:business": "node scripts/test-business.mjs",
     "check": "node scripts/validate-suite.mjs",
     "prepack": "npm run check"
-  },
-  "dependencies": {
-    "@excel.js/exceljs": "0.9.0",
-    "@petercjl/tbcli": "0.10.4",
-    "@petercjl/sycmcli": "0.3.1"
   }
 }

package/skills/taobao-ai-operations/SKILL.md

@@ -18,7 +18,11 @@ Input: an operator's goal, supplied workbooks or authorized data sources, option
 
 ## Execution and branches
 
-Bundled node scripts run via `taobao-ai-ops script NODE SCRIPT ...`; supplied Excel does not require platform accounts. Optional platform calls use `taobao-ai-ops tool run TOOL ...` so the suite selects its fixed tool entry. Accounts, warehouse access and write permissions remain external. The category child's database-consent and additive-import boundaries apply in its NAS route.
+Component scripts run via `taobao-ai-ops script NODE SCRIPT ...`; supplied Excel does not require platform accounts. Optional platform calls use `taobao-ai-ops tool run TOOL ...` so the shell selects the installed independent component. Accounts, warehouse access and write permissions remain external. The category child's database-consent and additive-import boundaries apply in its NAS route.
+
+When a child was installed by the shell, forward its CLI examples through `taobao-ai-ops component run COMPONENT ...`, retaining all remaining arguments. This resolves the actual independent package even when its CLI is not on PATH or another global version exists. Use the shell's unified update entry for shell-managed components; a child's standalone global updater belongs only to independent global installations.
+
+The shell registers independent npm packages; each owns its method, resources and release. Ordinary tasks use installed versions. On an explicit install/update request, use `taobao-ai-ops skill install --agent AGENT` or `taobao-ai-ops update install --agent AGENT --yes`; the latter checks both shell and every registered component's stable latest version even when the shell is unchanged. Inspect returned versions and managed Skill state. Registry failure preserves current components; local edits stop synchronization. Missing components return COMPONENT_NOT_INSTALLED and require authorized installation before returning to step 2. Development registrations update through their Git owners and are reported separately. Skill source resolves to each component's own canonical package, not a shell copy.
 
 Current node selection and source resolution are deterministic contracts, with method judgment owned by each child Skill. The package manifest is the node registry and shared contracts are maintained in the package's contracts directory. Do not load unrelated node methods at startup.
 

package/src/cli.mjs

@@ -1,17 +1,21 @@
 import path from 'node:path';
 import {spawnSync} from 'node:child_process';
-import {MANIFEST,PACKAGE,nodeFor,source,fileHashes,digest,fail} from './core.mjs';
+import {MANIFEST,PACKAGE,nodeFor,source,nodeVersion,fileHashes,digest,fail,componentRecords,componentRecord} from './core.mjs';
+import {checkComponents,installComponents,registerComponent} from './components.mjs';
 import {targetRoot,status,install} from './skill-manager.mjs';
 import {runScript,doctor,toolEntry} from './runtime.mjs';
 import {plan,workflowStatus,createHandoff} from './workflow.mjs';
 import {checkUpdate,installUpdate} from './update.mjs';
 const print=v=>console.log(JSON.stringify(v,null,2));
-function options(args){const out={};for(let i=0;i<args.length;i++){const k=args[i];if(['--json','--adopt','--yes'].includes(k))out[k.slice(2)]=true;else if(['--agent','--target-dir','--name','--node','--profile','--mode','--run-dir','--input','--out','--candidate','--query','--tag','--context','--run-id'].includes(k)){if(!args[i+1]||args[i+1].startsWith('--'))throw fail('USAGE',`${k} needs a value`);out[k.slice(2).replace(/-([a-z])/g,(_,c)=>c.toUpperCase())]=args[++i];}else throw fail('USAGE',`Unknown option ${k}`);}return out;}
+function options(args){const out={};for(let i=0;i<args.length;i++){const k=args[i];if(['--json','--adopt','--yes'].includes(k))out[k.slice(2)]=true;else if(['--path','--agent','--target-dir','--name','--node','--profile','--mode','--run-dir','--input','--out','--candidate','--query','--tag','--context','--run-id'].includes(k)){if(!args[i+1]||args[i+1].startsWith('--'))throw fail('USAGE',`${k} needs a value`);out[k.slice(2).replace(/-([a-z])/g,(_,c)=>c.toUpperCase())]=args[++i];}else throw fail('USAGE',`Unknown option ${k}`);}return out;}
 export async function main(argv){
  const [command,action,...rest]=argv;
- if(!command||['help','--help','-h'].includes(command))return console.log(`taobao-ai-ops ${PACKAGE.version}\nversion | nodes list | node show ID | capabilities\ndoctor --node ID [--mode excel|nas]\nskill source [--name NAME] | skill status|install|update --agent codex|sealseek|agents [--profile research] [--adopt] [--mode link|copy]\nscript NODE SCRIPT [arguments...] | tool run TOOL [arguments...]\nworkflow plan|status --run-dir DIR [--node ID] [--input FILE]\nhandoff create --node ID --input FILE --out FILE [--candidate PATH --query QUERY]\nupdate check|install [--tag next|latest] [--agent AGENT --yes]`);
+ if(!command||['help','--help','-h'].includes(command))return console.log(`taobao-ai-ops ${PACKAGE.version}\nversion | nodes list | node show ID | capabilities\ndoctor --node ID [--mode excel|nas]\nskill source [--name NAME] | skill status|install|update --agent AGENT [--profile research] [--adopt]\ncomponents status|check|install [--agent AGENT --yes]\ncomponents register --name ID --path CHECKOUT --yes [--mode npm]\ncomponent run ID [arguments...] | script NODE SCRIPT [arguments...] | tool run TOOL [arguments...]\nworkflow plan|status --run-dir DIR [--node ID] [--input FILE]\nhandoff create --node ID --input FILE --out FILE [--candidate PATH --query QUERY]\nupdate check|install [--tag latest] [--agent AGENT --yes]`);
  if(['version','--version'].includes(command))return console.log(PACKAGE.version);
  if(command==='script')return runScript(action,rest[0],rest.slice(1));
+ if(command==='component'&&action==='run'){
+  const record=componentRecord(rest[0]);const r=spawnSync(process.execPath,[record.entry,...rest.slice(1)],{stdio:'inherit',env:{...process.env,TBCLI_UPDATE_CHECK:'0',SYCMCLI_DISABLE_AUTO_UPDATE:'1'}});if(r.error)throw fail('EXECUTION_FAILED',r.error.message);process.exitCode=r.status??1;return;
+ }
  if(command==='tool'&&action==='run'){
   const entry=toolEntry(rest[0]);const r=spawnSync(entry.command,[...entry.args,...rest.slice(1)],{stdio:'inherit',env:{...process.env,TBCLI_UPDATE_CHECK:'0',SYCMCLI_DISABLE_AUTO_UPDATE:'1'}});if(r.error)throw fail('CAPABILITY_UNAVAILABLE',r.error.message);process.exitCode=r.status??1;return;
  }
@@ -20,15 +24,21 @@ export async function main(argv){
  if(command==='capabilities')return print({package:PACKAGE.name,version:PACKAGE.version,...MANIFEST});
  if(command==='doctor'){const opts=options(argv.slice(1));const r=await doctor(opts.node,opts.mode);print(r);if(!r.ok)process.exitCode=1;return;}
  const opts=options(rest);
+ if(command==='components'){
+  if(action==='status')return print({ok:true,components:componentRecords()});
+  if(action==='check')return print(await checkComponents());
+  if(action==='install')return print(await installComponents(opts));
+  if(action==='register')return print(await registerComponent(opts));
+ }
  if(command==='skill'){
-  if(action==='source'){const selected=opts.name?[nodeFor(opts.name)]:MANIFEST.nodes;const sources=await Promise.all(selected.map(async n=>({skill:n.skill,node:n.id,source:source(n),sourceDigest:digest(await fileHashes(source(n))),version:PACKAGE.version})));return print(opts.name?sources[0]:{package:PACKAGE.name,version:PACKAGE.version,skills:sources});}
+  if(action==='source'){const selected=opts.name?[nodeFor(opts.name)]:MANIFEST.nodes;const sources=await Promise.all(selected.map(async n=>({skill:n.skill,node:n.id,source:source(n),sourceDigest:digest(await fileHashes(source(n))),version:nodeVersion(n)})));return print(opts.name?sources[0]:{package:PACKAGE.name,version:PACKAGE.version,skills:sources});}
   if(action==='status'){const root=targetRoot(opts);return print({package:PACKAGE.name,root,skills:await Promise.all(MANIFEST.nodes.map(n=>status(root,n)))});}
-  if(['install','update'].includes(action))return print(await install(opts));
+  if(['install','update'].includes(action)){const records=componentRecords();return print(Object.keys(MANIFEST.components).every(id=>records[id])?await install(opts):await installComponents({...opts,yes:true}));}
  }
  if(command==='workflow'&&action==='plan')return print(await plan(opts));
  if(command==='workflow'&&action==='status')return print(await workflowStatus(opts));
  if(command==='handoff'&&action==='create')return print(await createHandoff(opts));
- if(command==='update'&&action==='check')return print(await checkUpdate(opts.tag));
+ if(command==='update'&&action==='check'){const suite=await checkUpdate(opts.tag),components=await checkComponents();print({ok:suite.ok&&components.ok,suite,components});if(!suite.ok||!components.ok)process.exitCode=1;return;}
  if(command==='update'&&action==='install')return print(await installUpdate(opts));
  throw fail('USAGE','Unknown command; run taobao-ai-ops --help');
 }

package/src/components.mjs

@@ -0,0 +1,73 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {randomUUID} from 'node:crypto';
+import {MANIFEST,PACKAGE,stateRoot,componentRecords,fail,stat} from './core.mjs';
+import {install} from './skill-manager.mjs';
+import {npm} from './update.mjs';
+
+const config=id=>{const c=MANIFEST.components[id];if(!c)throw fail('UNKNOWN_COMPONENT',id);return c;};
+export async function inspectComponent(id,root){
+ root=await fs.realpath(root);
+ const c=config(id),p=JSON.parse(await fs.readFile(path.join(root,'package.json'),'utf8'));
+ if(p.name!==c.package)throw fail('COMPONENT_IDENTITY_MISMATCH',`${id}: ${p.name}`);
+ const entry=path.resolve(root,p.bin?.[c.bin]||'');
+ if(!p.bin?.[c.bin]||!entry.startsWith(path.resolve(root)+path.sep))throw fail('INVALID_COMPONENT_ENTRY',id);
+ const sources={};
+ for(const skill of c.skills){
+  const r=spawnSync(process.execPath,[entry,'skill','source','--json'],{encoding:'utf8',timeout:30000,env:{...process.env,TBCLI_UPDATE_CHECK:'0',SYCMCLI_DISABLE_AUTO_UPDATE:'1'}});
+  if(r.status!==0)throw fail('COMPONENT_SOURCE_FAILED',r.stderr||id);
+  const result=JSON.parse(r.stdout);const s=result.source||(result.skills||[]).find(s=>s.skill===skill)?.source;
+  if(!s||!path.resolve(s).startsWith(path.resolve(root)+path.sep))throw fail('INVALID_COMPONENT_SOURCE',skill);
+  const text=await fs.readFile(path.join(s,'SKILL.md'),'utf8');
+  if(!new RegExp(`^name: ${skill}\\s*$`,'m').test(text))throw fail('SKILL_IDENTITY_MISMATCH',skill);
+  sources[skill]=s;
+ }
+ return {package:p.name,version:p.version,root:path.resolve(root),entry,sources};
+}
+async function save(records){
+ await fs.mkdir(stateRoot(),{recursive:true});const file=path.join(stateRoot(),'components.json'),tmp=file+'.'+randomUUID()+'.pending';
+ await fs.writeFile(tmp,JSON.stringify({schema_version:1,components:records},null,2),{flag:'wx',mode:0o600});await fs.rename(tmp,file);
+}
+async function locked(fn){
+ await fs.mkdir(stateRoot(),{recursive:true});const lock=path.join(stateRoot(),'components.lock');
+ try{await fs.mkdir(lock);}catch(e){if(e.code==='EEXIST')throw fail('UPDATE_BUSY','Another component operation is running');throw e;}
+ try{return await fn();}finally{await fs.rmdir(lock);}
+}
+export async function registerComponent(opts){
+ if(!opts.yes)throw fail('AUTHORIZATION_REQUIRED','Development registration requires --yes');
+ return locked(async()=>{const old=componentRecords(),record=await inspectComponent(opts.name,path.resolve(opts.path));
+  const backup=path.join(stateRoot(),'component-backups',randomUUID());await fs.mkdir(backup,{recursive:true});await fs.writeFile(path.join(backup,'components.json'),JSON.stringify(old),{flag:'wx'});
+  const development=opts.mode!=='npm';await save({...old,[opts.name]:{...record,development}});return {ok:true,component:opts.name,...record,development,backup};});
+}
+export async function checkComponents(registry=fetch){
+ const installed=componentRecords(),components=[];
+ for(const [id,c] of Object.entries(MANIFEST.components)){
+  if(installed[id]?.development){components.push({id,package:c.package,current:installed[id].version,updateAvailable:false,development:true,updateOwner:'git'});continue;}
+  try{const r=await registry(`https://registry.npmjs.org/${encodeURIComponent(c.package)}`,{signal:AbortSignal.timeout(15000)});
+   if(!r.ok)throw Error(`Registry HTTP ${r.status}`);const data=await r.json(),latest=data['dist-tags']?.latest;
+   if(!latest||latest.includes('-'))throw Error('No stable latest version');
+   components.push({id,package:c.package,current:installed[id]?.version||null,available:latest,updateAvailable:installed[id]?.version!==latest,development:Boolean(installed[id]?.development)});
+  }catch(e){components.push({id,package:c.package,current:installed[id]?.version||null,ok:false,code:'REGISTRY_UNAVAILABLE',message:e.message,offline:'keep-current'});}
+ }
+ return {ok:components.every(c=>c.ok!==false),components};
+}
+export async function installComponents(opts,services={}){
+ if(!opts.yes)throw fail('AUTHORIZATION_REQUIRED','Component installation/update requires --yes');
+ if(!opts.agent&&!opts.targetDir)throw fail('USAGE','Specify Agent or target directory');
+ return locked(async()=>{
+  const old=componentRecords(),check=await (services.check||checkComponents)();if(!check.ok)throw fail('REGISTRY_UNAVAILABLE','No changes made; one or more component checks failed',check);
+  const updates=check.components.filter(c=>c.updateAvailable&&!c.development);
+  if(updates.length===0)return {ok:true,action:'unchanged',check,skills:await install(opts)};
+  const generation=path.join(stateRoot(),'component-generations',randomUUID());await fs.mkdir(generation,{recursive:true});
+  await fs.writeFile(path.join(generation,'previous-components.json'),JSON.stringify(old),{flag:'wx'});
+  const next={...old};
+  try{
+   await (services.npm||npm)(['install','--prefix',generation,'--no-audit','--no-fund','--ignore-scripts',...updates.map(c=>`${c.package}@${c.available}`)]);
+   for(const c of updates){const r=await inspectComponent(c.id,path.join(generation,'node_modules',...c.package.split('/')));if(r.version!==c.available)throw fail('COMPONENT_VERSION_MISMATCH',c.id);next[c.id]=r;}
+   await save(next);
+   // The Skill manager backs up changed targets and rolls all Skill changes back on failure.
+   const skills=await install(opts);return {ok:true,action:'updated',suiteVersion:PACKAGE.version,components:updates,skills,backup:path.join(generation,'previous-components.json')};
+  }catch(e){await save(old);throw e;}
+ });
+}

package/src/core.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import os from 'node:os';
 import {fileURLToPath} from 'node:url';
 import {createHash} from 'node:crypto';
+import {readFileSync,existsSync} from 'node:fs';
 export const ROOT=fileURLToPath(new URL('../',import.meta.url));
 export const PACKAGE=JSON.parse(await fs.readFile(path.join(ROOT,'package.json'),'utf8'));
 export const MANIFEST=JSON.parse(await fs.readFile(path.join(ROOT,'suite-manifest.json'),'utf8'));
@@ -11,7 +12,10 @@ export const json=p=>fs.readFile(p,'utf8').then(JSON.parse);
 export const stat=p=>fs.lstat(p).catch(e=>{if(e.code==='ENOENT')return null;throw e;});
 export const hash=data=>createHash('sha256').update(data).digest('hex');
 export function nodeFor(id){const n=MANIFEST.nodes.find(n=>n.id===id||n.skill===id);if(!n)throw fail('UNKNOWN_NODE',`Unknown node: ${id}`);return n;}
-export const source=n=>path.join(ROOT,'skills',n.skill);
+export function componentRecords(){const file=path.join(stateRoot(),'components.json');return existsSync(file)?JSON.parse(readFileSync(file,'utf8')).components||{}:{};}
+export function componentRecord(id){const r=componentRecords()[id];if(!r)throw fail('COMPONENT_NOT_INSTALLED',`Install registered component ${id} with components install`);return r;}
+export const source=n=>n.component?componentRecord(n.component).sources[n.skill]||(()=>{throw fail('SKILL_SOURCE_MISSING',n.skill);})():path.join(ROOT,'skills',n.skill);
+export const nodeVersion=n=>n.component?componentRecord(n.component).version:PACKAGE.version;
 export function stateRoot(){return process.env.TAOBAO_AI_OPS_STATE_DIR||path.join(os.homedir(),'.local','state','taobao-ai-ops');}
 export async function fileHashes(root,rel=''){
  const out={};

package/src/runtime.mjs

@@ -3,8 +3,7 @@ import path from 'node:path';
 import os from 'node:os';
 import {spawnSync} from 'node:child_process';
 import {createRequire} from 'node:module';
-import {ROOT,MANIFEST,PACKAGE,nodeFor,source,fail} from './core.mjs';
-const require=createRequire(import.meta.url);
+import {ROOT,MANIFEST,PACKAGE,nodeFor,source,componentRecord,fail} from './core.mjs';
 export function pythonEnvironment(env=process.env){
  return {...env,PYTHONUTF8:'1',PYTHONIOENCODING:'utf-8',PYTHONDONTWRITEBYTECODE:'1'};
 }
@@ -21,25 +20,21 @@ export function resolvePython(imports,candidates=pythonCandidates()){
 export function toolEntry(id){
  const tool=MANIFEST.tools[id];if(!tool)throw fail('UNKNOWN_TOOL',`Unknown tool ${id}`);
  if(tool.external)return {command:process.env[tool.executable_env]||id,args:[],external:true};
- let packageRoot;
- try{packageRoot=path.dirname(require.resolve(`${tool.package}/package.json`));}
- catch{let dir=path.dirname(require.resolve(tool.package));while(dir!==path.dirname(dir)){const p=path.join(dir,'package.json');if(fs.existsSync(p)&&JSON.parse(fs.readFileSync(p,'utf8')).name===tool.package){packageRoot=dir;break;}dir=path.dirname(dir);}}
- if(!packageRoot)throw fail('CAPABILITY_UNAVAILABLE',`Cannot resolve ${tool.package}`);
- const entry=path.join(packageRoot,tool.entry);
- if(!fs.existsSync(entry))throw fail('CAPABILITY_UNAVAILABLE',`Missing ${id} entry`,{entry});
- return {command:process.execPath,args:[entry],version:JSON.parse(fs.readFileSync(path.join(packageRoot,'package.json'),'utf8')).version};
+ const managed=componentRecord(tool.component);
+ if(!fs.existsSync(managed.entry))throw fail('CAPABILITY_UNAVAILABLE',`Missing ${id} entry`);
+ return {command:process.execPath,args:[managed.entry],version:managed.version};
 }
 export function runScript(id,name,args){
- const n=nodeFor(id);if(!n.scripts.includes(name))throw fail('SCRIPT_NOT_ALLOWED',`Script ${name} is not exposed by ${n.id}`);
- const runtime=name.endsWith('.py')?resolvePython(n.python_imports):{command:process.execPath,prefix:[]};
- if(!runtime)throw fail('RUNTIME_UNAVAILABLE',`Python imports required: ${n.python_imports.join(', ')}`);
- const r=spawnSync(runtime.command,[...runtime.prefix,path.join(source(n),'scripts',name),...args],{stdio:'inherit',env:pythonEnvironment()});
+ const n=nodeFor(id);if(!n.component||!/^[a-z][a-z0-9_]*\.(py|mjs)$/.test(name))throw fail('SCRIPT_NOT_ALLOWED',`Invalid component script ${name}`);
+ // The independent CLI owns its current allowlist and runtime; new component scripts need no shell release.
+ const record=componentRecord(n.component);
+ const r=spawnSync(process.execPath,[record.entry,'script',name,...args],{stdio:'inherit',env:pythonEnvironment()});
  if(r.error)throw fail('EXECUTION_FAILED',r.error.message);process.exitCode=r.status??1;
 }
 export async function doctor(id,mode='excel'){
  const n=nodeFor(id||'operations'),checks=[];
  checks.push({id:'node',ok:Number(process.versions.node.split('.')[0])>=20,value:process.version});
- checks.push({id:'skill',ok:fs.existsSync(path.join(source(n),'SKILL.md'))});
+ try{checks.push({id:'skill',ok:fs.existsSync(path.join(source(n),'SKILL.md'))});}catch(e){return {ok:false,node:n.id,checks:[...checks,{id:'component',ok:false,code:e.code,message:e.message}],native_requirements:[]};}
  if(n.id==='operations'){
   const children=await Promise.all(n.requires_skills.map(skill=>doctor(skill,mode)));
   return {ok:checks.every(c=>c.ok)&&children.every(c=>c.ok),package:PACKAGE.name,version:PACKAGE.version,node:n.id,checks,children,native_requirements:children.flatMap(c=>c.native_requirements)};
@@ -47,7 +42,8 @@ export async function doctor(id,mode='excel'){
  if(n.python_imports.length){const python=resolvePython(n.python_imports);checks.push({id:'python',ok:Boolean(python),value:python,required_imports:n.python_imports});}
  if(n.id==='category-research')checks.push({id:'report-runtime',ok:['assets/report-template.html','assets/chart-views.js'].every(p=>fs.existsSync(path.join(source(n),p)))});
  if(n.id==='product-research'){
-  checks.push({id:'exceljs',ok:Boolean(await import('@excel.js/exceljs').catch(()=>null))});
+  const componentRequire=createRequire(path.join(componentRecord(n.component).root,'package.json'));
+  try{checks.push({id:'exceljs',ok:Boolean(componentRequire.resolve('@excel.js/exceljs'))});}catch(e){checks.push({id:'exceljs',ok:false,message:e.message});}
   checks.push({id:'report-runtime',ok:['report_runtime/renderer.py','report_runtime/validator.py','report_runtime/templates/workbench.html'].every(p=>fs.existsSync(path.join(source(n),p)))});
  }
  if(!['excel','nas'].includes(mode))throw fail('USAGE','Doctor mode must be excel or nas');

package/src/skill-manager.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 import {randomUUID} from 'node:crypto';
-import {PACKAGE,source,closure,json,stat,fileHashes,digest,fail,stateRoot} from './core.mjs';
+import {PACKAGE,source,nodeVersion,closure,json,stat,fileHashes,digest,fail,stateRoot} from './core.mjs';
 
 const OWNER='.taobao-ai-ops-managed.json';
 export function targetRoot(opts){
@@ -22,7 +22,7 @@ export function targetRoot(opts){
 import {existsSync as osExists} from 'node:fs';
 async function owners(root){const p=path.join(root,OWNER);if(!await stat(p))return {package:PACKAGE.name,skills:{}};const value=await json(p);if(value.package!==PACKAGE.name)throw fail('OWNERSHIP_CONFLICT','Suite ownership file belongs to another package');return value;}
 export async function status(root,n){
- const dest=path.join(root,n.skill),files=await fileHashes(source(n));const base={skill:n.skill,node:n.id,source:source(n),destination:dest,sourceDigest:digest(files),version:PACKAGE.version};
+ const dest=path.join(root,n.skill),files=await fileHashes(source(n));const base={skill:n.skill,node:n.id,source:source(n),destination:dest,sourceDigest:digest(files),version:nodeVersion(n)};
  const s=await stat(dest);if(!s)return {...base,state:'absent',managed:false};
  const own=(await owners(root)).skills[n.skill];
  if(s.isSymbolicLink()){
@@ -40,7 +40,7 @@ export async function status(root,n){
 async function makeCopy(dest,n){
  const files=await fileHashes(source(n));await fs.mkdir(dest,{recursive:true});
  for(const relative of Object.keys(files)){const d=path.join(dest,relative);await fs.mkdir(path.dirname(d),{recursive:true});await fs.copyFile(path.join(source(n),relative),d);}
- await fs.writeFile(path.join(dest,'.suite-install.json'),JSON.stringify({package:PACKAGE.name,skill:n.skill,version:PACKAGE.version,sourceDigest:digest(files),files}),{flag:'wx'});
+ await fs.writeFile(path.join(dest,'.suite-install.json'),JSON.stringify({package:PACKAGE.name,skill:n.skill,version:nodeVersion(n),sourceDigest:digest(files),files}),{flag:'wx'});
  await fs.writeFile(path.join(dest,'.install-meta.json'),JSON.stringify({title:n.skill,description:`Taobao AI operations: ${n.id}`}),{flag:'wx'});
 }
 async function restore(backup,dest,inPlace){
@@ -72,7 +72,7 @@ export async function install(opts,options={}){
    if(mode==='link')await fs.symlink(source(n),dest,process.platform==='win32'?'junction':'dir');else await makeCopy(dest,n);
    if(mode==='copy'&&record.backup){const ui=path.join(record.backup,'.install-meta.json');if(await stat(ui))await fs.copyFile(ui,path.join(dest,'.install-meta.json'));}
    const after=await status(root,n);if(after.state!=='current')throw fail('INSTALL_VERIFY_FAILED',`Skill verification failed: ${n.skill}`);
-   old.skills[n.skill]={source:source(n),version:PACKAGE.version,digest:after.sourceDigest,mode,backup:record.backup};
+   old.skills[n.skill]={source:source(n),version:nodeVersion(n),digest:after.sourceDigest,mode,backup:record.backup};
    results.push({...after,action:item.state==='absent'?'installed':item.managed?'updated':'adopted',backup:record.backup,strategy:inPlace?'in-place':'rename'});
    if(options.failAfter===changed.length)throw fail('TEST_INJECTED_FAILURE','Injected migration failure');
   }

package/src/update.mjs

@@ -3,12 +3,12 @@ import path from 'node:path';
 import {spawnSync} from 'node:child_process';
 import {existsSync,realpathSync} from 'node:fs';
 import {ROOT,PACKAGE,fail,stateRoot} from './core.mjs';
-export async function checkUpdate(tag='next'){
+export async function checkUpdate(tag='latest'){
  if(!['latest','next'].includes(tag))throw fail('USAGE','Tag must be latest or next');
  try{const r=await fetch(`https://registry.npmjs.org/${encodeURIComponent(PACKAGE.name)}`,{signal:AbortSignal.timeout(15000)});if(r.status===404)return {ok:true,published:false,current:PACKAGE.version,updateAvailable:false,tag};if(!r.ok)throw Error(`Registry HTTP ${r.status}`);const p=await r.json();const version=p['dist-tags']?.[tag];return {ok:true,published:true,current:PACKAGE.version,available:version,updateAvailable:Boolean(version&&version!==PACKAGE.version),tag};}
  catch(e){return {ok:false,code:'REGISTRY_UNAVAILABLE',current:PACKAGE.version,updateAvailable:false,message:e.message,offline:'keep-current'};}
 }
-function npm(args){
+export function npm(args){
  let cli=process.env.npm_execpath;
  if(!cli||!cli.endsWith('npm-cli.js')){
   const found=spawnSync(process.platform==='win32'?'where':'which',[process.platform==='win32'?'npm.cmd':'npm'],{encoding:'utf8',timeout:10000});
@@ -23,7 +23,7 @@ export async function installUpdate(opts){
  if(!opts.agent&&!opts.targetDir)throw fail('USAGE','Specify --agent or --target-dir before updating');
  const nodeModules=path.dirname(path.dirname(ROOT.slice(0,-1)));
  if(path.basename(nodeModules)!=='node_modules'||(process.platform!=='win32'&&path.basename(path.dirname(nodeModules))!=='lib'))throw fail('SOURCE_CHECKOUT','This source or local test install updates through its owner, not global npm');
- const check=await checkUpdate(opts.tag||'next');if(!check.ok)throw fail(check.code,check.message);if(!check.updateAvailable)return {...check,action:'unchanged'};
+ const check=await checkUpdate(opts.tag||'latest');if(!check.ok)throw fail(check.code,check.message);if(!check.updateAvailable)return {...check,components:await (await import('./components.mjs')).installComponents(opts)};
  // Persist the installed version as a local archive for recovery, including unpublished prerequisites.
  const backup=await fs.mkdtemp(path.join(await fs.mkdir(path.join(stateRoot(),'package-backups'),{recursive:true}).then(()=>path.join(stateRoot(),'package-backups')),'update-'));
  const packed=JSON.parse(npm(['pack',ROOT,'--ignore-scripts','--pack-destination',backup,'--json']))[0];
@@ -31,8 +31,8 @@ export async function installUpdate(opts){
  try{
   npm(['install','--global','--prefix',prefix,'--ignore-scripts',`${PACKAGE.name}@${check.available}`]);
   const fresh=path.join(nodeModules,...PACKAGE.name.split('/'),'bin','taobao-ai-ops.mjs');
-  const args=['skill','update','--json'];if(opts.targetDir)args.push('--target-dir',opts.targetDir);else if(opts.agent)args.push('--agent',opts.agent);else throw fail('USAGE','Specify the Agent or custom target for managed Skill synchronization');
-  const r=spawnSync(process.execPath,[fresh,...args],{encoding:'utf8',timeout:60000});if(r.status!==0)throw fail('SKILL_SYNC_FAILED',r.stderr||r.error?.message||'Skill synchronization failed');
+  const args=['components','install','--yes','--json'];if(opts.targetDir)args.push('--target-dir',opts.targetDir);else if(opts.agent)args.push('--agent',opts.agent);else throw fail('USAGE','Specify the Agent or custom target for managed Skill synchronization');
+  const r=spawnSync(process.execPath,[fresh,...args],{encoding:'utf8',timeout:300000});if(r.status!==0)throw fail('SKILL_SYNC_FAILED',r.stderr||r.error?.message||'Skill synchronization failed');
   const v=spawnSync(process.execPath,[fresh,'version'],{encoding:'utf8',timeout:10000});if(v.stdout.trim()!==check.available)throw fail('UPDATE_VERIFY_FAILED','Installed version differs from registry selection');
   return {ok:true,from:PACKAGE.version,to:check.available,backup:path.join(backup,packed.filename),skills:JSON.parse(r.stdout)};
  }catch(e){npm(['install','--global','--prefix',prefix,'--ignore-scripts',path.join(backup,packed.filename)]);const restored=path.join(nodeModules,...PACKAGE.name.split('/'),'bin','taobao-ai-ops.mjs');const args=['skill','update','--json',...(opts.targetDir?['--target-dir',opts.targetDir]:['--agent',opts.agent])];const synced=spawnSync(process.execPath,[restored,...args],{encoding:'utf8',timeout:60000});if(synced.status!==0)throw fail('ROLLBACK_SYNC_REQUIRED','Old package restored; managed Skill recovery needs attention',{original_error:e.message,backup:path.join(backup,packed.filename)});throw e;}

package/src/workflow.mjs

@@ -1,14 +1,14 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import {randomUUID} from 'node:crypto';
-import {ROOT,PACKAGE,MANIFEST,closure,nodeFor,hash,json,stat,fail} from './core.mjs';
+import {ROOT,PACKAGE,MANIFEST,closure,nodeFor,nodeVersion,hash,json,stat,fail} from './core.mjs';
 export async function plan(opts){
  if(!opts.runDir)throw fail('USAGE','--run-dir is required');
  const root=path.resolve(opts.runDir),dest=path.join(root,'taobao-ai-ops-run.json');
  if(await stat(dest))throw fail('OUTPUT_EXISTS','Run already exists; use workflow status');
- const nodes=closure(opts).filter(n=>n.id!=='operations');
+ const nodes=closure(opts).filter(n=>n.id!=='operations'&&n.stage!=='tools');
  const inputs=[];for(const p of [].concat(opts.input||[])){inputs.push({path:path.resolve(p),sha256:hash(await fs.readFile(p))});}
- const value={schema_version:1,run_id:randomUUID(),package:PACKAGE.name,package_version:PACKAGE.version,manifest_sha256:hash(await fs.readFile(path.join(ROOT,'suite-manifest.json'))),created_at:new Date().toISOString(),inputs,nodes:nodes.map(n=>({node_id:n.id,method_version:n.method_version,status:'planned',artifacts:[],verified:false})),context:opts.context||null,requirement:'Each node loads its complete Skill and executes its own QA; planning does not execute business work.'};
+ const value={schema_version:1,run_id:randomUUID(),package:PACKAGE.name,package_version:PACKAGE.version,manifest_sha256:hash(await fs.readFile(path.join(ROOT,'suite-manifest.json'))),created_at:new Date().toISOString(),inputs,nodes:nodes.map(n=>({node_id:n.id,component:n.component,component_version:nodeVersion(n),method_version:n.method_version,status:'planned',artifacts:[],verified:false})),context:opts.context||null,requirement:'Each node loads its complete Skill and executes its own QA; planning does not execute business work.'};
  await fs.mkdir(root,{recursive:true});await fs.writeFile(dest,JSON.stringify(value,null,2),{flag:'wx'});return {ok:true,ledger:dest,...value};
 }
 export async function workflowStatus(opts){if(!opts.runDir)throw fail('USAGE','--run-dir is required');return json(path.join(path.resolve(opts.runDir),'taobao-ai-ops-run.json'));}

package/suite-manifest.json

@@ -1,17 +1,170 @@
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "package": "@petercjl/taobao-ai-ops",
-  "profiles": {"research": ["operations", "category-research", "product-research"]},
+  "profiles": {
+    "research": [
+      "operations",
+      "category-research",
+      "product-research",
+      "tbcli-tools",
+      "sycmcli-tools"
+    ]
+  },
   "nodes": [
-    {"id": "operations", "skill": "taobao-ai-operations", "stage": "routing", "method_version": "1.0", "requires_skills": ["yuce-category-opportunity-report", "taobao-search-product-form"], "python_imports": [], "scripts": [], "native_requirements": []},
-    {"id": "category-research", "skill": "yuce-category-opportunity-report", "stage": "discover-market", "method_version": "yuce-category-opportunity@2.0", "requires_skills": [], "python_imports": ["openpyxl"], "scripts": ["build_report.py"], "native_requirements": [], "optional_tools": ["tbcli", "yccli"], "origin": {"kind": "accepted-local-skill", "skill_md_sha256": "e93ea7817d44eada35f9934007f5d4d04736553fb28afb01339fdcdacf8275ef"}},
-    {"id": "product-research", "skill": "taobao-search-product-form", "stage": "research-product", "method_version": "taobao-search-product-form@0.1.1", "requires_skills": [], "python_imports": ["pandas", "numpy", "openpyxl", "PIL", "jieba"], "native_requirements": ["image.observe"], "origin": {"package": "@petercjl/taobao-search-product-form", "version": "0.1.1", "repository": "https://github.com/petercjl/taobao-search-product-form", "commit": "49a574d572895ea4f0047d54766633de754b07d4", "npm_integrity": "sha512-RSoCkbdp3Ggh+VwJl9ejR+IpGHaWeIkExWq4/WcqBS6xzcxYbfuPzX6Fx15PXgh/K2QffjLjgll4mQMiJK3yig=="}, "scripts": ["clean_search_export.mjs", "prepare.py", "analyze.py", "analyze_advertisers.py", "analyze_geography.py", "analyze_price_bands.py", "analyze_title_roots.py", "assemble_opportunity_evidence.py", "build_report_viewmodel.py", "build_visual_review_viewmodel.py", "cluster_visual_forms.py", "compile_style_prototypes.py", "compile_visual_review.py", "compile_visual_selection.py", "render_report.py", "validate_opportunity_cards.py", "validate_report_viewmodel.py", "visual_form_pipeline.py", "visual_observation_batches.py", "workflow_ledger.py"]}
+    {
+      "id": "operations",
+      "skill": "taobao-ai-operations",
+      "stage": "routing",
+      "method_version": "1.0",
+      "requires_skills": [
+        "yuce-category-opportunity-report",
+        "taobao-search-product-form"
+      ],
+      "python_imports": [],
+      "scripts": [],
+      "native_requirements": []
+    },
+    {
+      "id": "category-research",
+      "skill": "yuce-category-opportunity-report",
+      "stage": "discover-market",
+      "method_version": "yuce-category-opportunity@2.0",
+      "requires_skills": [],
+      "python_imports": [
+        "openpyxl"
+      ],
+      "scripts": [
+        "build_report.py"
+      ],
+      "native_requirements": [],
+      "optional_tools": [
+        "tbcli",
+        "yccli"
+      ],
+      "component": "category-research"
+    },
+    {
+      "id": "product-research",
+      "skill": "taobao-search-product-form",
+      "stage": "research-product",
+      "method_version": "taobao-search-product-form@0.1.1",
+      "requires_skills": [],
+      "python_imports": [
+        "pandas",
+        "numpy",
+        "openpyxl",
+        "PIL",
+        "jieba"
+      ],
+      "native_requirements": [
+        "image.observe"
+      ],
+      "scripts": [
+        "clean_search_export.mjs",
+        "prepare.py",
+        "analyze.py",
+        "analyze_advertisers.py",
+        "analyze_geography.py",
+        "analyze_price_bands.py",
+        "analyze_title_roots.py",
+        "assemble_opportunity_evidence.py",
+        "build_report_viewmodel.py",
+        "build_visual_review_viewmodel.py",
+        "cluster_visual_forms.py",
+        "compile_style_prototypes.py",
+        "compile_visual_review.py",
+        "compile_visual_selection.py",
+        "render_report.py",
+        "validate_opportunity_cards.py",
+        "validate_report_viewmodel.py",
+        "visual_form_pipeline.py",
+        "visual_observation_batches.py",
+        "workflow_ledger.py"
+      ],
+      "component": "product-research"
+    },
+    {
+      "id": "tbcli-tools",
+      "skill": "tbcli",
+      "component": "tbcli",
+      "stage": "tools",
+      "requires_skills": [],
+      "python_imports": [],
+      "scripts": [],
+      "native_requirements": []
+    },
+    {
+      "id": "sycmcli-tools",
+      "skill": "sycmcli",
+      "component": "sycmcli",
+      "stage": "tools",
+      "requires_skills": [],
+      "python_imports": [],
+      "scripts": [],
+      "native_requirements": []
+    }
   ],
   "tools": {
-    "tbcli": {"package": "@petercjl/tbcli", "version": "0.10.4", "entry": "scripts/tbcli.mjs", "role": "existing monthly exports, warehouse and additive category import"},
-    "sycmcli": {"package": "@petercjl/sycmcli", "version": "0.3.1", "entry": "scripts/sycmcli.mjs", "role": "store-bound market, category, keyword and competitor read operations"},
-    "yccli": {"external": true, "minimum_version": "0.5.0", "executable_env": "TAOBAO_AI_OPS_YCCLI", "role": "authorized Yuce monthly collection; optional for supplied Excel"}
+    "tbcli": {
+      "package": "@petercjl/tbcli",
+      "entry": "scripts/tbcli.mjs",
+      "role": "existing monthly exports, warehouse and additive category import",
+      "component": "tbcli"
+    },
+    "sycmcli": {
+      "package": "@petercjl/sycmcli",
+      "entry": "scripts/sycmcli.mjs",
+      "role": "store-bound market, category, keyword and competitor read operations",
+      "component": "sycmcli"
+    },
+    "yccli": {
+      "external": true,
+      "minimum_version": "0.5.0",
+      "executable_env": "TAOBAO_AI_OPS_YCCLI",
+      "role": "authorized Yuce monthly collection; optional for supplied Excel"
+    }
+  },
+  "targets": {
+    "codex:macos": "implemented",
+    "sealseek:macos": "implemented",
+    "sealseek:windows": "implemented"
+  },
+  "update_policy": {
+    "owner": "shell",
+    "channel": "latest",
+    "during_run": "installed-component-set",
+    "automatic_install": false,
+    "offline": "keep-current",
+    "source_checkout": "git-managed"
   },
-  "targets": {"codex:macos": "implemented", "sealseek:macos": "implemented", "sealseek:windows": "implemented"},
-  "update_policy": {"owner": "suite", "during_run": "fixed-version-set", "automatic_install": false, "offline": "keep-current", "source_checkout": "git-managed"}
+  "components": {
+    "category-research": {
+      "package": "@petercjl/yuce-category-opportunity-report",
+      "bin": "yuce-category-research",
+      "skills": [
+        "yuce-category-opportunity-report"
+      ]
+    },
+    "product-research": {
+      "package": "@petercjl/taobao-search-product-form",
+      "bin": "taobao-search-form",
+      "skills": [
+        "taobao-search-product-form"
+      ]
+    },
+    "tbcli": {
+      "package": "@petercjl/tbcli",
+      "bin": "tbcli",
+      "skills": [
+        "tbcli"
+      ]
+    },
+    "sycmcli": {
+      "package": "@petercjl/sycmcli",
+      "bin": "sycmcli",
+      "skills": [
+        "sycmcli"
+      ]
+    }
+  }
 }