@shiplens/cli 1.4.5 → 1.4.7

package/lib/assets/actions.json

@@ -693,7 +693,7 @@
     },
     {
       "id": "uninstall_cli",
-      "title": "Delete Shiplens CLI",
+      "title": "Delete Shiplens CLI and Restore Project",
       "suffix": "None",
       "category": "Initial Setup",
       "prompt": "Please prioritize calling Shiplens CLI (Action: uninstall_cli) to execute the above requirements. - Windows: npm.cmd uninstall -g @shiplens/cli - macOS/Linux: npm uninstall -g @shiplens/cli",
@@ -710,7 +710,7 @@
       "prompt": "Use Shiplens CLI to map pages, features, and button layouts into `.shiplens/contexts/<app_id>.md` so AI analytics can understand the business context behind each metric:",
       "steps": [
         "1. Check `./.shiplens.json` for current app_id and project name.",
-        "2. Inspect frontend code and routes to extract feature descriptions, user-facing copy, and button texts, locations, and actions.",
+        "2. Run AST static code scan across frontend code and routes to extract page purposes, feature copy, interactive buttons, test IDs, selectors, and exact source code locations.",
         "3. Write structured details into `.shiplens/contexts/<app_id>.md`, binding app_id and project name in the header."
       ],
       "commands": [],

package/lib/assets/skill.js

@@ -46,7 +46,7 @@ Backup mirror fallback: add \`--registry=https://registry.npmmirror.com\`
 2. Install \`@shiplens/sdk\`
 3. Inject tracking code into entry file
 4. Register project via \`POST /api/connect\` → receive \`app_id\` + \`dashboard_url\`
-5. Scan page content → generate \`.shiplens/contexts/<app_id>.md\`
+5. AST static source scan (pages, buttons, routes) → generate \`.shiplens/contexts/<app_id>.md\` UI business dictionary
 6. Write local state machine \`.shiplens.json\`
 7. Inject this AI Skill file and Agent rules
 

package/lib/cli.js

@@ -16,7 +16,7 @@ const { handleContext } = require('./commands/context');
 const { handleMcp } = require('./commands/mcp');
 const { handleAction } = require('./commands/action');
 
-let VERSION = '1.4.4';
+let VERSION = '1.4.7';
 try {
   const pkg = require('../package.json');
   if (pkg.version) VERSION = pkg.version;
@@ -90,7 +90,7 @@ Core Commands:
   heatmap       Retrieve click heatmaps and skeleton wireframes
   dashboards    AI dashboard management and one-click creation (list, create [--ai])
   doctor        Run full end-to-end diagnostics on SDK, credentials, and network
-  context       Manage business context dictionary (push, pull, show)
+  context       Manage business context dictionary (generate, push, pull, show)
   action        Retrieve deterministic steps, commands, and theory for analysis actions (list, <action_id>)
   mcp serve     Run local MCP proxy server with device credentials
 

package/lib/commands/context.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { getLocalConfig } = require('../config');
+const { generateProjectContext } = require('../context-generator');
 
 /**
  * Get standard storage path for business context: .shiplens/contexts/<app_id>.md
@@ -37,7 +38,7 @@ async function executeWithSafeFallback(fn, maxRetries = 2, baseMs = 500) {
 }
 
 /**
- * Handle context command (push, pull, show)
+ * Handle context command (generate, push, pull, show)
  */
 async function handleContext(subcommand, args, flags, ctx) {
   const targetSub = subcommand || 'show';
@@ -47,6 +48,23 @@ async function handleContext(subcommand, args, flags, ctx) {
   const projectName = flags.name || localCfg.project_name || '';
 
   switch (targetSub) {
+    case 'generate':
+    case 'scan':
+    case 'extract': {
+      const genResult = generateProjectContext(process.cwd(), appId, projectName, flags.framework || localCfg.framework);
+      ctx.output({
+        ok: true,
+        action: 'generate',
+        app_id: appId,
+        file: genResult.filePath,
+        rel_file: genResult.relPath,
+        pages_count: genResult.totalPages,
+        buttons_count: genResult.totalButtons,
+        message: `Project business context scanned and saved to ${genResult.relPath} (${genResult.totalPages} pages, ${genResult.totalButtons} buttons).`,
+      });
+      break;
+    }
+
     case 'push': {
       if (!fs.existsSync(filePath)) {
         const displayPath = path.relative(process.cwd(), filePath) || filePath;
@@ -173,7 +191,7 @@ async function handleContext(subcommand, args, flags, ctx) {
     }
 
     default:
-      throw new Error(`Unknown context subcommand: ${targetSub}. Supported: push, pull, show`);
+      throw new Error(`Unknown context subcommand: ${targetSub}. Supported: generate, push, pull, show`);
   }
 }
 

package/lib/commands/init.js

@@ -3,6 +3,7 @@ const { detectProject, detectExistingApp, injectSDK, injectSkill, installSDKDepe
 const { saveLocalConfig } = require('../config');
 const { saveDeviceEnv } = require('../device-env');
 const { resolveTaxonomyFromIDs, formatTaxonomySummary } = require('../taxonomy');
+const { generateProjectContext } = require('../context-generator');
 
 async function handleInit(args, flags, ctx) {
   const start = Date.now();
@@ -124,7 +125,13 @@ async function handleInit(args, flags, ctx) {
     last_synced_at: new Date().toISOString(),
   });
 
-  // 6. Install SDK dependency
+  // 6. Automatically scan page structures & generate UI business context (.shiplens/contexts/<app_id>.md)
+  let contextResult = null;
+  try {
+    contextResult = generateProjectContext(wd, appId, projectName, framework);
+  } catch (e) {}
+
+  // 7. Install SDK dependency
   let installResult = { success: true, manager: 'skipped' };
   if (!flags['no-install'] && detected.package_manager) {
     installResult = await installSDKDependency(wd, detected.package_manager);
@@ -152,7 +159,7 @@ async function handleInit(args, flags, ctx) {
     }
   }
 
-  // 7. Bind email if specified
+  // 8. Bind email if specified
   let targetEmail = flags.email;
   if (targetEmail === 'auto') {
     targetEmail = getGitEmail();
@@ -195,6 +202,10 @@ async function handleInit(args, flags, ctx) {
     sdk_manager: installResult.manager,
     skill_injected: true,
     skill_file: skillFile,
+    context_generated: !!contextResult,
+    context_file: contextResult ? contextResult.relPath : undefined,
+    context_pages_count: contextResult ? contextResult.totalPages : 0,
+    context_buttons_count: contextResult ? contextResult.totalButtons : 0,
     package_manager: detected.package_manager,
     auth_status: authStatus,
     shiplens_env_written: authStatus === 'magic_link_sent',
@@ -227,6 +238,9 @@ async function handleInit(args, flags, ctx) {
     console.log(`Live Dashboard / Activation URL: 🔗 ${dashboardUrl}`);
     console.log(`User Account: ${accountStatusText}`);
     console.log(`🧠 AI Skill Ready: ${skillFile}`);
+    if (contextResult && contextResult.relPath) {
+      console.log(`📑 Business Context: ${contextResult.relPath} (${contextResult.totalPages} pages, ${contextResult.totalButtons} buttons mapped)`);
+    }
     console.log(`🔒 [SHIPLENS_ATOMIC_COMPLETED] Setup completed atomically. No extra commands needed.`);
     console.log(`==================================================\n`);
 

package/lib/context-generator.js

@@ -0,0 +1,175 @@
+const fs = require('fs');
+const path = require('path');
+const { detectProjectPages } = require('./scanner');
+const { extractPageSkeleton } = require('./extractor');
+
+/**
+ * Infer page purpose from headings, descriptions, and route name
+ */
+function inferPagePurpose(page, headings, descriptions, faqs) {
+  if (descriptions && descriptions.length > 0) {
+    return descriptions[0];
+  }
+  if (headings && headings.length > 0) {
+    return headings.join(' / ');
+  }
+  if (page.path === '/') {
+    return 'Primary landing / core product overview page';
+  }
+  const cleanName = page.name.replace(/[^a-zA-Z0-9_\- ]/g, '');
+  return `Core ${cleanName} feature page`;
+}
+
+/**
+ * Infer intent and next step for interactive controls
+ */
+function inferButtonIntent(btn, page) {
+  if (btn.action_hint) {
+    return btn.action_hint;
+  }
+  const t = (btn.text || '').toLowerCase();
+  if (t.includes('start') || t.includes('free') || t.includes('try') || t.includes('get started') || t.includes('免费') || t.includes('试用')) {
+    return 'Primary conversion CTA / onboarding initiation';
+  }
+  if (t.includes('sign up') || t.includes('register') || t.includes('注册')) {
+    return 'User account registration';
+  }
+  if (t.includes('login') || t.includes('sign in') || t.includes('登录')) {
+    return 'User authentication login';
+  }
+  if (t.includes('upgrade') || t.includes('buy') || t.includes('pro') || t.includes('pricing') || t.includes('订阅') || t.includes('购买')) {
+    return 'Monetization checkout / subscription upgrade';
+  }
+  if (t.includes('save') || t.includes('submit') || t.includes('保存') || t.includes('提交')) {
+    return 'Save settings or submit form data';
+  }
+  if (t.includes('delete') || t.includes('remove') || t.includes('删除')) {
+    return 'Delete or purge data item';
+  }
+  if (t.includes('calculate') || t.includes('search') || t.includes('filter') || t.includes('计算') || t.includes('查询')) {
+    return 'Execute calculation / filter workflow';
+  }
+  return `Trigger ${btn.tag} interaction on ${page.path}`;
+}
+
+/**
+ * Generate standard business context markdown and write to .shiplens/contexts/<app_id>.md
+ * @param {string} dir Project root directory
+ * @param {string} appId Target App ID
+ * @param {string} projectName Project Name
+ * @param {string} framework Framework detected
+ * @returns {{ filePath: string, relPath: string, totalPages: number, totalButtons: number, markdown: string }}
+ */
+function generateProjectContext(dir = process.cwd(), appId, projectName = 'My App', framework = 'custom') {
+  const { framework: detectedFramework, pages } = detectProjectPages(dir);
+  const activeFramework = framework || detectedFramework;
+
+  const pageDetails = [];
+  let totalButtonsCount = 0;
+
+  for (const p of pages) {
+    const skeleton = extractPageSkeleton(p.filePath, p.path, p.name, dir);
+    const purpose = inferPagePurpose(p, skeleton.headings, skeleton.descriptions, skeleton.faqs);
+    totalButtonsCount += skeleton.raw_buttons.length;
+    pageDetails.push({
+      ...p,
+      relFilePath: path.relative(dir, p.filePath).replace(/\\/g, '/'),
+      purpose,
+      headings: skeleton.headings,
+      faqs: skeleton.faqs,
+      feature_bullets: skeleton.feature_bullets,
+      descriptions: skeleton.descriptions,
+      buttons: skeleton.raw_buttons.map((b) => ({
+        ...b,
+        intent: inferButtonIntent(b, p),
+      })),
+    });
+  }
+
+  const now = new Date().toISOString();
+  const mdLines = [
+    '# Shiplens Project Business Context & UI Dictionary',
+    '',
+    `> **Project Name**: ${projectName}`,
+    `> **App ID**: ${appId}`,
+    `> **Framework**: ${activeFramework}`,
+    `> **Generated At**: ${now}`,
+    '',
+    '---',
+    '',
+    '## 1. Page & Route Catalog',
+    '',
+  ];
+
+  if (pageDetails.length === 0) {
+    mdLines.push('*No frontend template pages detected during initial static scanning.*');
+    mdLines.push('');
+  } else {
+    for (const p of pageDetails) {
+      mdLines.push(`### Page: ${p.name} (\`${p.path}\`)`);
+      mdLines.push(`- **Source File**: [\`${p.relFilePath}\`](file:///${path.resolve(dir, p.relFilePath).replace(/\\/g, '/')})`);
+      mdLines.push(`- **Page Purpose**: ${p.purpose}`);
+
+      if (p.headings.length > 0) {
+        mdLines.push(`- **Key Headings**: ${p.headings.map((h) => `\`${h}\``).join(', ')}`);
+      }
+      if (p.feature_bullets.length > 0) {
+        mdLines.push('- **Feature Highlights**:');
+        for (const f of p.feature_bullets.slice(0, 5)) {
+          mdLines.push(`  - ${f}`);
+        }
+      }
+      if (p.faqs.length > 0) {
+        mdLines.push('- **FAQ Context**:');
+        for (const f of p.faqs.slice(0, 3)) {
+          mdLines.push(`  - Q: ${f.q}${f.a ? ` -> A: ${f.a}` : ''}`);
+        }
+      }
+
+      if (p.buttons.length > 0) {
+        mdLines.push('');
+        mdLines.push(`#### Interactive Elements & Buttons (${p.buttons.length}):`);
+        mdLines.push('| Button ID | Text / Label | Selector | Source Location | Inferred Action / Intent |');
+        mdLines.push('| :--- | :--- | :--- | :--- | :--- |');
+        for (const b of p.buttons) {
+          const textDisplay = (b.text || '').replace(/\|/g, '\\|').trim() || '(icon/action)';
+          const locDisplay = b.source_loc ? `\`${b.source_loc}\`` : '-';
+          mdLines.push(`| \`${b.id}\` | ${textDisplay} | \`${b.selector}\` | ${locDisplay} | ${b.intent} |`);
+        }
+      } else {
+        mdLines.push('- **Interactive Elements**: *(No buttons or interactive controls found on this page)*');
+      }
+      mdLines.push('');
+    }
+  }
+
+  mdLines.push('---');
+  mdLines.push('');
+  mdLines.push('## 2. Business Metric Grounding');
+  mdLines.push(`- **Total Pages Mapped**: ${pageDetails.length}`);
+  mdLines.push(`- **Total Interactive Controls**: ${totalButtonsCount}`);
+  mdLines.push('- **Usage**: When analyzing drop-offs, funnels, or heatmaps, reference the Button IDs and Page Purposes above to translate technical telemetry into actionable product insights.');
+  mdLines.push('');
+
+  const markdownContent = mdLines.join('\n');
+
+  // Standard storage path: .shiplens/contexts/<app_id>.md
+  const contextDir = path.join(dir, '.shiplens', 'contexts');
+  fs.mkdirSync(contextDir, { recursive: true });
+  const targetFilePath = path.join(contextDir, `${appId}.md`);
+  fs.writeFileSync(targetFilePath, markdownContent, 'utf8');
+
+  return {
+    filePath: targetFilePath,
+    relPath: path.relative(dir, targetFilePath).replace(/\\/g, '/'),
+    totalPages: pageDetails.length,
+    totalButtons: totalButtonsCount,
+    markdown: markdownContent,
+  };
+}
+
+module.exports = {
+  generateProjectContext,
+  inferPagePurpose,
+  inferButtonIntent,
+};

package/lib/extractor.js

@@ -0,0 +1,609 @@
+const fs = require('fs');
+const path = require('path');
+const parser = require('@babel/parser');
+const traverse = require('@babel/traverse').default || require('@babel/traverse');
+const t = require('@babel/types');
+
+/**
+ * 清洗代码字符串，去除注释、import、CSS-in-JS 与复杂逻辑噪音
+ * @param {string} rawCode 原始文件代码
+ * @returns {string} 精简后的模板与文案字符串
+ */
+function cleanCode(rawCode) {
+  return rawCode
+    // 移除多行注释与 JSDoc
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    // 移除单行注释
+    .replace(/\/\/.*$/gm, '')
+    // 移除 import 语句
+    .replace(/^import\s+[\s\S]*?from\s+['"].*?['"];?/gm, '')
+    // 移除 require 语句
+    .replace(/const\s+.*?=\s*require\(.*?\);?/gm, '');
+}
+
+/**
+ * 深度提取页面内的多维富文本文案：
+ * 包含：H1~H6 标题、FAQ 折叠问答、套餐权益列表 (li)、卡片段落描述 (p)、Badge 标签
+ * @param {string} code 清洗后的代码
+ * @returns {{ headings: string[], faqs: Array<{ q: string, a?: string }>, feature_bullets: string[], descriptions: string[] }}
+ */
+function extractRichPageContent(code) {
+  const headings = [];
+  const faqs = [];
+  const featureBullets = [];
+  const descriptions = [];
+
+  // 1. 提取 H1 到 H6 标题
+  const headingRegex = /<h[1-6][^>]*>([\s\S]*?)<\/h[1-6]>/gi;
+  let match;
+  while ((match = headingRegex.exec(code)) !== null) {
+    const text = cleanTagContent(match[1]);
+    if (text && text.length > 1 && text.length < 120 && !headings.includes(text)) {
+      headings.push(text);
+    }
+  }
+
+  // 2. 提取 FAQ 问答结构 (<details><summary> 或常见 FAQ 容器)
+  const detailsRegex = /<details[^>]*>[\s\S]*?<summary[^>]*>([\s\S]*?)<\/summary>([\s\S]*?)<\/details>/gi;
+  while ((match = detailsRegex.exec(code)) !== null) {
+    const question = cleanTagContent(match[1]);
+    const answer = cleanTagContent(match[2]);
+    if (question && question.length > 2) {
+      faqs.push({
+        q: question,
+        ...(answer ? { a: answer.slice(0, 150) } : {})
+      });
+    }
+  }
+
+  // 匹配 dt/dd 键值问答
+  const dtRegex = /<dt[^>]*>([\s\S]*?)<\/dt>[\s\S]*?<dd[^>]*>([\s\S]*?)<\/dd>/gi;
+  while ((match = dtRegex.exec(code)) !== null) {
+    const q = cleanTagContent(match[1]);
+    const a = cleanTagContent(match[2]);
+    if (q && q.length > 2 && !faqs.some(f => f.q === q)) {
+      faqs.push({ q, ...(a ? { a: a.slice(0, 150) } : {}) });
+    }
+  }
+
+  // 3. 提取套餐权益与核心特性列表 (<li>)
+  const liRegex = /<li[^>]*>([\s\S]*?)<\/li>/gi;
+  while ((match = liRegex.exec(code)) !== null) {
+    const text = cleanTagContent(match[1]);
+    if (text && text.length > 2 && text.length < 100 && !featureBullets.includes(text)) {
+      featureBullets.push(text);
+    }
+  }
+
+  // 4. 提取核心描述段落 (<p> 及含有 desc/title/text 类的元素)
+  const pRegex = /<p[^>]*>([\s\S]*?)<\/p>/gi;
+  while ((match = pRegex.exec(code)) !== null) {
+    const text = cleanTagContent(match[1]);
+    if (text && text.length > 5 && text.length < 200 && !descriptions.includes(text) && !headings.includes(text)) {
+      descriptions.push(text);
+    }
+  }
+
+  return {
+    headings: headings.slice(0, 8),
+    faqs: faqs.slice(0, 10),
+    feature_bullets: featureBullets.slice(0, 12),
+    descriptions: descriptions.slice(0, 6)
+  };
+}
+
+const NATIVE_BUTTON_TAGS = new Set(['button', 'a', 'input']);
+const CUSTOM_BUTTON_PATTERN = /^(?:.*Button|.*Btn|.*CTA|.*Submit|.*Link|Link|Button|CTA|Submit)$/i;
+
+function getTagName(nameNode) {
+  if (!nameNode) return '';
+  if (t.isJSXIdentifier(nameNode)) return nameNode.name;
+  if (t.isJSXMemberExpression(nameNode)) {
+    return `${getTagName(nameNode.object)}.${nameNode.property.name}`;
+  }
+  if (t.isJSXNamespacedName(nameNode)) {
+    return `${nameNode.namespace.name}:${nameNode.name.name}`;
+  }
+  return '';
+}
+
+function extractAttributeStringValue(valNode) {
+  if (!valNode) return null;
+  if (t.isStringLiteral(valNode)) return valNode.value;
+  if (t.isJSXExpressionContainer(valNode)) {
+    const expr = valNode.expression;
+    if (t.isStringLiteral(expr)) return expr.value;
+    if (t.isNumericLiteral(expr)) return String(expr.value);
+    if (t.isTemplateLiteral(expr)) {
+      return expr.quasis.map((q) => q.value.raw).join('');
+    }
+  }
+  return null;
+}
+
+function extractHandlerDescription(valNode) {
+  if (!valNode) return '';
+  if (t.isJSXExpressionContainer(valNode)) {
+    const expr = valNode.expression;
+    if (t.isIdentifier(expr)) return expr.name;
+    if (t.isCallExpression(expr)) {
+      if (t.isIdentifier(expr.callee)) return `${expr.callee.name}()`;
+      if (t.isMemberExpression(expr.callee) && t.isIdentifier(expr.callee.property)) {
+        return `${expr.callee.property.name}()`;
+      }
+      return 'function()';
+    }
+    if (t.isArrowFunctionExpression(expr) || t.isFunctionExpression(expr)) {
+      if (t.isCallExpression(expr.body)) {
+        if (t.isIdentifier(expr.body.callee)) return `${expr.body.callee.name}()`;
+        if (t.isMemberExpression(expr.body.callee) && t.isIdentifier(expr.body.callee.property)) {
+          return `${expr.body.callee.property.name}()`;
+        }
+      }
+      if (t.isBlockStatement(expr.body) && expr.body.body.length > 0) {
+        const firstStmt = expr.body.body[0];
+        if (t.isExpressionStatement(firstStmt) && t.isCallExpression(firstStmt.expression)) {
+          const call = firstStmt.expression;
+          if (t.isIdentifier(call.callee)) return `${call.callee.name}()`;
+          if (t.isMemberExpression(call.callee) && t.isIdentifier(call.callee.property)) {
+            return `${call.callee.property.name}()`;
+          }
+        }
+      }
+      return 'inline handler';
+    }
+  }
+  return '';
+}
+
+function extractAttrs(attributes) {
+  const result = {
+    id: null,
+    shiplensLabel: null,
+    testId: null,
+    href: null,
+    to: null,
+    type: null,
+    role: null,
+    className: null,
+    clickHandler: null,
+    hasClick: false,
+    value: null,
+    rel: null,
+  };
+
+  for (const attr of attributes) {
+    if (t.isJSXAttribute(attr) && t.isJSXIdentifier(attr.name)) {
+      const name = attr.name.name;
+      const attrNameLower = name.toLowerCase();
+      const valNode = attr.value;
+      const strVal = extractAttributeStringValue(valNode);
+
+      if (attrNameLower === 'id') {
+        result.id = strVal;
+      } else if (attrNameLower === 'data-shiplens-label' || attrNameLower === 'data-label') {
+        result.shiplensLabel = strVal;
+      } else if (attrNameLower === 'data-testid' || attrNameLower === 'data-test-id' || attrNameLower === 'testid') {
+        result.testId = strVal;
+      } else if (attrNameLower === 'href') {
+        result.href = strVal;
+      } else if (attrNameLower === 'to') {
+        result.to = strVal;
+      } else if (attrNameLower === 'type') {
+        result.type = strVal;
+      } else if (attrNameLower === 'role') {
+        result.role = strVal;
+      } else if (attrNameLower === 'class' || attrNameLower === 'classname') {
+        result.className = strVal;
+      } else if (attrNameLower === 'value') {
+        result.value = strVal;
+      } else if (attrNameLower === 'rel') {
+        result.rel = strVal;
+      }
+
+      if (['onclick', '@click', 'v-on:click', 'onpress', 'ontap', 'bindtap'].includes(attrNameLower)) {
+        result.hasClick = true;
+        result.clickHandler = extractHandlerDescription(valNode);
+      }
+    }
+  }
+
+  return result;
+}
+
+function extractChildText(children) {
+  const parts = [];
+
+  for (const child of children) {
+    if (t.isJSXText(child)) {
+      const text = child.value.replace(/\s+/g, ' ').trim();
+      if (text) parts.push(text);
+    } else if (t.isJSXExpressionContainer(child)) {
+      const expr = child.expression;
+      if (t.isStringLiteral(expr)) {
+        const text = expr.value.trim();
+        if (text) parts.push(text);
+      } else if (t.isNumericLiteral(expr)) {
+        parts.push(String(expr.value));
+      } else if (t.isTemplateLiteral(expr)) {
+        const text = expr.quasis.map((q) => q.value.raw).join('').trim();
+        if (text) parts.push(text);
+      } else if (t.isConditionalExpression(expr)) {
+        const consequent = t.isStringLiteral(expr.consequent) ? expr.consequent.value.trim() : '';
+        const alternate = t.isStringLiteral(expr.alternate) ? expr.alternate.value.trim() : '';
+        if (consequent && alternate) {
+          parts.push(`${consequent} / ${alternate}`);
+        } else if (consequent || alternate) {
+          parts.push(consequent || alternate);
+        } else {
+          parts.push('{conditional}');
+        }
+      }
+    } else if (t.isJSXElement(child)) {
+      const nested = extractChildText(child.children);
+      if (nested) parts.push(nested);
+    }
+  }
+
+  return parts.join(' ').trim();
+}
+
+function inferActionHint(attrs) {
+  const target = attrs.href || attrs.to;
+  if (target) return `navigate to ${target}`;
+  if (attrs.clickHandler) return `calls ${attrs.clickHandler}`;
+  if (attrs.type === 'submit') return 'submit form';
+  return '';
+}
+
+function cleanClassName(classStr) {
+  if (!classStr) return '';
+  return classStr
+    .split(/\s+/)
+    .filter((c) => c && !/^(css-|_[a-z0-9]{5,}|[a-z0-9]{8,})/i.test(c))
+    .slice(0, 2)
+    .join(' ');
+}
+
+function cleanTagContent(content) {
+  if (!content) return '';
+  return content
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/\{[^}]*\}/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function extractInputValue(attrs) {
+  const match = attrs.match(/value=["']([^"']+)["']/i);
+  return match ? match[1].trim() : '';
+}
+
+function generateIdFromTextOrClass(text, classStr, tag, index) {
+  if (text && typeof text === 'string') {
+    const cleanText = text.replace(/[\r\n\t]+/g, ' ').trim();
+    if (cleanText.length >= 1 && cleanText.length <= 50) {
+      if (/[\u4e00-\u9fa5]/.test(cleanText)) {
+        const hexToken = encodeURIComponent(cleanText)
+          .replace(/%/g, '')
+          .slice(0, 12)
+          .toLowerCase();
+        if (hexToken) return `btn_${hexToken}`;
+      } else {
+        const slug = cleanText
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/g, '_')
+          .replace(/^_+|_+$/g, '')
+          .slice(0, 24);
+        if (slug) return `btn_${slug}`;
+      }
+    }
+  }
+
+  if (classStr && typeof classStr === 'string') {
+    const firstClass = classStr.split(' ')[0].replace(/[^a-zA-Z0-9_-]/g, '');
+    if (firstClass) return `btn_${firstClass.replace(/^btn_?/, '') ? firstClass : `btn_${firstClass}`}`;
+  }
+
+  return `btn_${(tag || 'element').toLowerCase()}_${index || 1}`;
+}
+
+/**
+ * 基于 Babel AST 遍历提取页面内所有的交互按钮、链接和提交控件
+ * @param {string} code 源代码
+ * @param {string} filePath 相对文件路径（用于 source_loc）
+ * @returns {Array<{ id: string, tag: string, text: string, selector: string, label?: string, action_hint?: string, source_loc?: string, is_custom_component?: boolean }> | null}
+ */
+function extractInteractiveElementsAST(code, filePath = '') {
+  let ast;
+  try {
+    ast = parser.parse(code, {
+      sourceType: 'unambiguous',
+      plugins: [
+        'jsx',
+        'typescript',
+        'decorators-legacy',
+        'classProperties',
+        'classPrivateProperties',
+        'classPrivateMethods',
+        'exportDefaultFrom',
+        'exportNamespaceFrom',
+        'asyncGenerators',
+        'dynamicImport',
+        'objectRestSpread',
+        'optionalCatchBinding',
+        'optionalChaining',
+        'nullishCoalescingOperator',
+      ],
+      errorRecovery: true,
+    });
+  } catch (e) {
+    return null;
+  }
+
+  const elements = [];
+  let elementIndex = 1;
+
+  traverse(ast, {
+    JSXElement(pathNode) {
+      const opening = pathNode.node.openingElement;
+      const rawTagName = getTagName(opening.name);
+      if (!rawTagName) return;
+
+      const lowerTagName = rawTagName.toLowerCase();
+      const isNative = NATIVE_BUTTON_TAGS.has(lowerTagName);
+      const isCustom = CUSTOM_BUTTON_PATTERN.test(rawTagName);
+
+      // 过滤 HTML head 中的 link 标签 (如 <link rel="stylesheet" />)
+      const attrs = extractAttrs(opening.attributes);
+      if (lowerTagName === 'link' && attrs.rel && !attrs.href && !attrs.to && !attrs.hasClick) {
+        return;
+      }
+
+      const isSubmit = attrs.type === 'submit';
+      const isButtonRole = attrs.role === 'button' || attrs.role === 'link';
+
+      if (!isNative && !isCustom && !attrs.hasClick && !isSubmit && !isButtonRole) {
+        return;
+      }
+
+      const childText = extractChildText(pathNode.node.children);
+      const text = childText || (attrs.value ? attrs.value : '');
+
+      const stableId =
+        attrs.shiplensLabel ||
+        attrs.id ||
+        attrs.testId ||
+        generateIdFromTextOrClass(text, attrs.className || '', rawTagName, elementIndex);
+
+      const cleanClass = cleanClassName(attrs.className);
+      const firstClass = cleanClass ? cleanClass.split(' ')[0] : '';
+      const selector = attrs.id
+        ? `#${attrs.id}`
+        : firstClass
+        ? `${lowerTagName}.${firstClass}`
+        : `${lowerTagName}`;
+
+      const actionHint = inferActionHint(attrs);
+
+      let sourceLoc = undefined;
+      if (opening.loc) {
+        const line = opening.loc.start.line;
+        sourceLoc = filePath ? `${filePath}:${line}` : `line ${line}`;
+      }
+
+      elements.push({
+        id: stableId,
+        tag: lowerTagName,
+        text: text || '(图标/无文案)',
+        selector: selector,
+        ...(attrs.shiplensLabel ? { label: attrs.shiplensLabel } : {}),
+        ...(actionHint ? { action_hint: actionHint } : {}),
+        ...(sourceLoc ? { source_loc: sourceLoc } : {}),
+        ...(isCustom && !isNative ? { is_custom_component: true } : {}),
+      });
+
+      elementIndex += 1;
+    },
+  });
+
+  // 去重保底（相同 id 保留第一个）
+  const seenIds = new Set();
+  return elements.filter((el) => {
+    if (seenIds.has(el.id)) return false;
+    seenIds.add(el.id);
+    return true;
+  });
+}
+
+/**
+ * 正则状态机提取按钮（AST 解析异常时的平滑降级保底）
+ * @param {string} code 清洗后的代码
+ * @param {string} filePath 相对文件路径
+ * @returns {Array<{ id: string, tag: string, text: string, selector: string, label?: string, action_hint?: string, source_loc?: string }>}
+ */
+function extractInteractiveElementsRegex(code, filePath = '') {
+  const elements = [];
+  let elementIndex = 1;
+
+  // 匹配所有 <button, <a, <Link, <input, <div, <span 开头的标签
+  const tagStartRegex = /<([a-zA-Z0-9_\-]+)(?:\s+|>)/g;
+  let match;
+
+  while ((match = tagStartRegex.exec(code)) !== null) {
+    const tag = match[1];
+    const targetTags = ['button', 'a', 'link', 'input', 'div', 'span'];
+    const isTargetTag = targetTags.includes(tag.toLowerCase()) || CUSTOM_BUTTON_PATTERN.test(tag);
+    if (!isTargetTag) {
+      continue;
+    }
+
+    const startIndex = match.index;
+    let index = startIndex + tag.length + 1;
+    let inQuotes = null;
+    let braceDepth = 0;
+    let isSelfClosing = false;
+    let tagEndIndex = -1;
+
+    // 解析属性直到遇到真正的 '>'
+    while (index < code.length) {
+      const char = code[index];
+      const prevChar = code[index - 1];
+
+      if (inQuotes) {
+        if (char === inQuotes && prevChar !== '\\') {
+          inQuotes = null;
+        }
+      } else if (char === '"' || char === "'" || char === '`') {
+        inQuotes = char;
+      } else if (char === '{') {
+        braceDepth += 1;
+      } else if (char === '}') {
+        braceDepth = Math.max(0, braceDepth - 1);
+      } else if (char === '>' && braceDepth === 0) {
+        tagEndIndex = index;
+        if (code[index - 1] === '/') {
+          isSelfClosing = true;
+        }
+        break;
+      }
+      index += 1;
+    }
+
+    if (tagEndIndex === -1) continue;
+
+    const attrs = code.slice(startIndex + tag.length + 1, tagEndIndex);
+    let innerContent = '';
+
+    if (!isSelfClosing) {
+      const closeTagStr = `</${tag}>`;
+      const closeTagIndex = code.indexOf(closeTagStr, tagEndIndex + 1);
+      if (closeTagIndex !== -1 && closeTagIndex - tagEndIndex < 2000) {
+        innerContent = code.slice(tagEndIndex + 1, closeTagIndex);
+      }
+    }
+
+    const isExplicitButton = /^(button|a|link)$/i.test(tag) || CUSTOM_BUTTON_PATTERN.test(tag);
+    const hasClick = /onClick|@click|v-on:click|onPress|role=["']button["']/i.test(attrs);
+    const isSubmit = /type=["']submit["']/i.test(attrs);
+
+    if (!isExplicitButton && !hasClick && !isSubmit) {
+      continue;
+    }
+
+    // 过滤 HTML head 中的 link 标签
+    if (tag.toLowerCase() === 'link' && /rel=["'](?:stylesheet|icon|preload|manifest)["']/i.test(attrs)) {
+      continue;
+    }
+
+    const idMatch = attrs.match(/\bid=["']([^"']+)["']/i);
+    const rawId = idMatch ? idMatch[1] : null;
+
+    const labelMatch = attrs.match(/data-shiplens-label=["']([^"']+)["']/i);
+    const explicitLabel = labelMatch ? labelMatch[1] : null;
+
+    const testIdMatch = attrs.match(/data-testid=["']([^"']+)["']/i);
+    const testId = testIdMatch ? testIdMatch[1] : null;
+
+    const classMatch = attrs.match(/(?:class|className)=["']([^"']+)["']/i);
+    const classStr = classMatch ? cleanClassName(classMatch[1]) : '';
+
+    const text = cleanTagContent(innerContent) || extractInputValue(attrs);
+
+    const hrefMatch = attrs.match(/(?:href|to)=["']([^"']+)["']/i);
+    const href = hrefMatch ? hrefMatch[1] : '';
+
+    const clickMatch = attrs.match(/(?:onClick|@click|onPress)=["']?\{?([^"'>}]+)\}?["']?/i);
+    const clickHandler = clickMatch ? clickMatch[1].trim() : '';
+
+    const stableId = explicitLabel 
+      || rawId 
+      || testId
+      || generateIdFromTextOrClass(text, classStr, tag, elementIndex);
+
+    const selector = rawId 
+      ? `#${rawId}` 
+      : classStr 
+      ? `${tag.toLowerCase()}.${classStr.split(' ')[0]}` 
+      : `${tag.toLowerCase()}`;
+
+    let actionHint = '';
+    if (href) actionHint = `navigate to ${href}`;
+    else if (clickHandler) actionHint = `calls ${clickHandler}`;
+    else if (isSubmit) actionHint = 'submit form';
+
+    elements.push({
+      id: stableId,
+      tag: tag.toLowerCase(),
+      text: text || '(图标/无文案)',
+      selector: selector,
+      ...(explicitLabel ? { label: explicitLabel } : {}),
+      ...(actionHint ? { action_hint: actionHint } : {})
+    });
+
+    elementIndex += 1;
+  }
+
+  const seenIds = new Set();
+  return elements.filter((el) => {
+    if (seenIds.has(el.id)) return false;
+    seenIds.add(el.id);
+    return true;
+  });
+}
+
+/**
+ * 提取页面内所有的交互按钮、链接和提交控件（入口函数：优先 AST，降级正则）
+ * @param {string} code 代码
+ * @param {string} filePath 相对文件路径
+ * @returns {Array<{ id: string, tag: string, text: string, selector: string, label?: string, action_hint?: string, source_loc?: string, is_custom_component?: boolean }>}
+ */
+function extractInteractiveElements(code, filePath = '') {
+  try {
+    const astResult = extractInteractiveElementsAST(code, filePath);
+    if (astResult !== null && astResult.length >= 0) {
+      return astResult;
+    }
+  } catch (e) {
+    // 降级兜底
+  }
+  return extractInteractiveElementsRegex(code, filePath);
+}
+
+/**
+ * 完整解析一个页面的结构与富文本骨架
+ * @param {string} filePath 文件绝对路径
+ * @param {string} routePath 对应路由
+ * @param {string} pageName 页面候选名称
+ * @param {string} rootDir 项目根目录（用于计算相对 source_loc）
+ * @returns {{ path: string, name: string, headings: string[], faqs: Array, feature_bullets: string[], descriptions: string[], raw_buttons: Array }}
+ */
+function extractPageSkeleton(filePath, routePath, pageName, rootDir = '') {
+  if (!fs.existsSync(filePath)) {
+    return { path: routePath, name: pageName, headings: [], faqs: [], feature_bullets: [], descriptions: [], raw_buttons: [] };
+  }
+
+  const rawCode = fs.readFileSync(filePath, 'utf-8');
+  const code = cleanCode(rawCode);
+  const richContent = extractRichPageContent(code);
+  const relFilePath = rootDir ? path.relative(rootDir, filePath).replace(/\\/g, '/') : filePath.replace(/\\/g, '/');
+  const rawButtons = extractInteractiveElements(rawCode, relFilePath);
+
+  return {
+    path: routePath,
+    name: pageName,
+    ...richContent,
+    raw_buttons: rawButtons
+  };
+}
+
+module.exports = {
+  cleanCode,
+  extractRichPageContent,
+  extractInteractiveElementsAST,
+  extractInteractiveElementsRegex,
+  extractInteractiveElements,
+  extractPageSkeleton,
+  generateIdFromTextOrClass
+};
+

package/lib/scanner.js

@@ -0,0 +1,152 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * 递归扫描目录中的代码文件
+ * @param {string} dir 目标目录
+ * @param {string[]} extensions 支持的扩展名
+ * @param {string[]} ignoreDirs 忽略的目录
+ * @returns {string[]} 文件绝对路径列表
+ */
+function scanFiles(dir, extensions = ['.tsx', '.jsx', '.vue', '.html', '.svelte', '.js', '.ts'], ignoreDirs = ['node_modules', '.git', '.next', 'dist', 'build', 'out', '.agents']) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!ignoreDirs.includes(entry.name)) {
+        results.push(...scanFiles(fullPath, extensions, ignoreDirs));
+      }
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (extensions.includes(ext)) {
+        results.push(fullPath);
+      }
+    }
+  }
+  return results;
+}
+
+/**
+ * 自动探测项目类型并提取页面路由列表
+ * @param {string} rootDir 项目根目录
+ * @returns {{ framework: string, pages: Array<{ path: string, filePath: string, name: string }> }}
+ */
+function detectProjectPages(rootDir) {
+  const pages = [];
+  let framework = 'custom';
+
+  // 1. 检测 Next.js App Router (src/app 或 app)
+  const appRouterDir = fs.existsSync(path.join(rootDir, 'src', 'app')) 
+    ? path.join(rootDir, 'src', 'app') 
+    : fs.existsSync(path.join(rootDir, 'app')) 
+    ? path.join(rootDir, 'app') 
+    : null;
+
+  if (appRouterDir) {
+    framework = 'nextjs-app-router';
+    const allFiles = scanFiles(appRouterDir, ['.tsx', '.jsx', '.js', '.ts']);
+    for (const file of allFiles) {
+      const baseName = path.basename(file);
+      if (/^page\.(tsx|jsx|js|ts)$/.test(baseName)) {
+        const relDir = path.relative(appRouterDir, path.dirname(file));
+        const routePath = relDir === '' ? '/' : `/${relDir.replace(/\\/g, '/').replace(/\(.*?\)\/?/g, '')}`;
+        pages.push({
+          path: routePath || '/',
+          filePath: file,
+          name: routePath === '/' ? 'Home (首页)' : routePath
+        });
+      }
+    }
+  }
+
+  // 2. 检测 Next.js / Nuxt Pages Router (src/pages 或 pages)
+  if (pages.length === 0) {
+    const pagesRouterDir = fs.existsSync(path.join(rootDir, 'src', 'pages')) 
+      ? path.join(rootDir, 'src', 'pages') 
+      : fs.existsSync(path.join(rootDir, 'pages')) 
+      ? path.join(rootDir, 'pages') 
+      : null;
+
+    if (pagesRouterDir) {
+      framework = 'pages-router';
+      const allFiles = scanFiles(pagesRouterDir, ['.tsx', '.jsx', '.vue', '.js', '.ts']);
+      for (const file of allFiles) {
+        const rel = path.relative(pagesRouterDir, file);
+        const nameWithoutExt = rel.replace(/\.[^/.]+$/, '').replace(/\\/g, '/');
+        if (nameWithoutExt.startsWith('_') || nameWithoutExt.startsWith('api/')) continue;
+
+        const routePath = nameWithoutExt === 'index' ? '/' : `/${nameWithoutExt.replace(/\/index$/, '')}`;
+        pages.push({
+          path: routePath,
+          filePath: file,
+          name: routePath === '/' ? 'Home (首页)' : routePath
+        });
+      }
+    }
+  }
+
+  // 3. 检测通用 Vite / React / Vue (src/views, src/routes, src/pages, 或扫描全部 .vue/.tsx 组件)
+  if (pages.length === 0) {
+    const candidateDirs = ['src/views', 'src/pages', 'src/routes', 'src/components', 'src'].map(d => path.join(rootDir, d));
+    for (const cDir of candidateDirs) {
+      if (fs.existsSync(cDir)) {
+        const files = scanFiles(cDir, ['.tsx', '.jsx', '.vue', '.html', '.svelte']);
+        for (const file of files) {
+          const base = path.basename(file, path.extname(file));
+          // 过滤通用辅助或原子组件 (如 Button, Icon, Header)
+          if (/^(Page|View|Screen|Home|Pricing|Login|Dashboard|Checkout|Register|Setting|About)/i.test(base)) {
+            const cleanName = base.toLowerCase().replace(/(page|view|screen)$/i, '');
+            const routePath = cleanName === 'home' || cleanName === 'index' ? '/' : `/${cleanName}`;
+            pages.push({
+              path: routePath,
+              filePath: file,
+              name: base
+            });
+          }
+        }
+        if (pages.length > 0) {
+          framework = 'vite-react-vue';
+          break;
+        }
+      }
+    }
+  }
+
+  // 4. 静态 HTML 项目保底
+  if (pages.length === 0) {
+    const htmlFiles = scanFiles(rootDir, ['.html'], ['node_modules', '.git', 'dist']);
+    if (htmlFiles.length > 0) {
+      framework = 'static-html';
+      for (const file of htmlFiles) {
+        const rel = path.relative(rootDir, file).replace(/\\/g, '/');
+        const routePath = rel === 'index.html' ? '/' : `/${rel.replace(/\.html$/, '')}`;
+        pages.push({
+          path: routePath,
+          filePath: file,
+          name: path.basename(file)
+        });
+      }
+    }
+  }
+
+  // 去重保底
+  const uniqueMap = new Map();
+  for (const p of pages) {
+    if (!uniqueMap.has(p.path)) {
+      uniqueMap.set(p.path, p);
+    }
+  }
+
+  return {
+    framework,
+    pages: Array.from(uniqueMap.values())
+  };
+}
+
+module.exports = {
+  scanFiles,
+  detectProjectPages
+};

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@shiplens/cli",
-  "version": "1.4.5",
+  "version": "1.4.7",
   "description": "Shiplens CLI — Automated Web User Analytics & AI Agent Analysis Engine",
   "main": "lib/index.js",
   "bin": {
-    "cli": "./bin/shiplens.js",
-    "shiplens": "./bin/shiplens.js",
-    "shiplens-cli": "./bin/shiplens.js"
+    "cli": "bin/shiplens.js",
+    "shiplens": "bin/shiplens.js",
+    "shiplens-cli": "bin/shiplens.js"
   },
   "keywords": [
     "shiplens",
@@ -46,5 +46,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@babel/parser": "^8.0.4",
+    "@babel/traverse": "^8.0.4",
+    "@babel/types": "^8.0.4"
   }
 }

package/prompts/prompts_cli_en-US.md

@@ -781,7 +781,7 @@ Delete Shiplens project analytics data and SDK integration (analytics no longer
 Please prioritize calling Shiplens CLI (Action: remove_sdk) to execute the above requirements.
 ```
 
-#### [uninstall_cli] Delete Shiplens CLI (Suffix: None)
+#### [uninstall_cli] Delete Shiplens CLI and Restore Project (Suffix: None)
 ```text
 Please prioritize calling Shiplens CLI (Action: uninstall_cli) to execute the above requirements.
  - Windows: npm.cmd uninstall -g @shiplens/cli
@@ -792,7 +792,7 @@ Please prioritize calling Shiplens CLI (Action: uninstall_cli) to execute the ab
 ```text
 Use Shiplens CLI to map pages, features, and button layouts into `.shiplens/contexts/<app_id>.md` so AI analytics can understand the business context behind each metric:
 1. Check `./.shiplens.json` for current app_id and project name.
-2. Inspect frontend code and routes to extract feature descriptions, user-facing copy, and button texts, locations, and actions.
+2. Run AST static code scan across frontend code and routes to extract page purposes, feature copy, interactive buttons, test IDs, selectors, and exact source code locations.
 3. Write structured details into `.shiplens/contexts/<app_id>.md`, binding app_id and project name in the header.
 Please prioritize calling Shiplens CLI (Action: generate_context) to execute the above requirements.
 ```