@shiplens/cli 1.3.0 → 1.4.0

package/lib/commands/heatmap.js

@@ -2,33 +2,28 @@ async function handleHeatmap(args, flags, ctx) {
   const appId = ctx.resolveAppId();
   const templateId = flags.template || args[0];
   if (!templateId) {
-    throw new Error('Specify target page template ID via --template <id>');
+    throw new Error('请通过 --template <id> 指定目标页面模板 ID');
   }
 
   const env = flags.env || 'production';
   const domHash = flags['dom-hash'] || '';
 
-  const resp = await ctx.client.getHeatmap({
-    app_id: appId,
-    template_id: templateId,
-    env,
-    dom_hash: domHash,
-  });
+  const resp = await ctx.client.heatmap(appId, templateId, env, domHash);
 
   ctx.output(resp, () => {
-    console.log(`🔥 Page Heatmap Analysis (Template: ${resp.template_id}, DOM Hash: ${resp.dom_hash || '-'}):`);
+    console.log(`🔥 页面热力图分析 (模板: ${resp.template_id}, DOM 哈希: ${resp.dom_hash || '-'}):`);
     if (resp.skeleton_svg_url) {
-      console.log(`🖼️ Skeleton SVG Preview URL: ${resp.skeleton_svg_url}`);
+      console.log(`🖼️ 骨架图 SVG 预览地址: ${resp.skeleton_svg_url}`);
     }
-    console.log(`👆 Total Clicks: ${resp.clicks_total || 0}\n`);
+    console.log(`👆 总点击数: ${resp.clicks_total || 0}\n`);
     if (resp.elements && resp.elements.length > 0) {
-      console.log('Top Clicked Elements:');
+      console.log('高频点击元素分布:');
       resp.elements.forEach((el, i) => {
-        console.log(`[${i + 1}] Element: ${el.label || '-'} (Selector: ${el.selector})`);
-        console.log(`    Clicks: ${el.clicks} | Click Rate: ${((el.click_rate || 0) * 100).toFixed(2)}% | Coordinates: (${el.x_pct}, ${el.y_pct})`);
+        console.log(`[${i + 1}] 元素: ${el.label || '-'} (选择器: ${el.selector})`);
+        console.log(`    点击数: ${el.clicks} | 点击转化率: ${((el.click_rate || 0) * 100).toFixed(2)}% | 坐标: (${el.x_pct}, ${el.y_pct})`);
       });
     } else {
-      console.log('(No click data found for this template)');
+      console.log('（当前模板暂无点击元素数据）');
     }
   });
 }

package/lib/commands/init.js

@@ -1,5 +1,5 @@
 const readline = require('readline');
-const { detectProject, detectExistingApp, injectSDK, injectSkill, installSDKDependency, getGitEmail, autoGitCommit } = require('../injector');
+const { detectProject, detectExistingApp, injectSDK, injectSkill, installSDKDependency, getGitEmail } = require('../injector');
 const { saveLocalConfig } = require('../config');
 const { saveDeviceEnv } = require('../device-env');
 const { resolveTaxonomyFromIDs, formatTaxonomySummary } = require('../taxonomy');
@@ -13,7 +13,7 @@ async function handleInit(args, flags, ctx) {
   const description = flags.description || detected.description || '';
   const framework = flags.framework || detected.framework;
 
-  // Taxonomy resolution
+  // 4 级分类判定：优先命令行显式参数，否则使用 detectProject 智能推断结果
   let taxonomy = detected.taxonomy;
   if (flags.genre || flags.subgenre || flags.tags) {
     const rawTags = flags.tags ? (Array.isArray(flags.tags) ? flags.tags : flags.tags.split(',').map((t) => t.trim())) : (taxonomy ? taxonomy.feature_tag_ids : []);
@@ -24,18 +24,20 @@ async function handleInit(args, flags, ctx) {
   const subgenreId = taxonomy?.subgenre?.id || 'browser_web_utility';
   const featureTagIds = taxonomy?.feature_tag_ids || [];
   if (featureTagIds.length > 10) {
-    throw new Error('Maximum 10 feature tags allowed.');
+    throw new Error('最多只能提交 10 个四级特性标签');
   }
   const industry = flags.industry || subgenreId || 'saas';
 
-  // 1. Safety check for existing project configuration
+  // 1. 检查本地是否已存在 SDK 或已有项目编号 (防意外覆盖分支)
   const existing = detectExistingApp(wd);
   if (existing.has_existing && !flags.force) {
     if (ctx.isJSON) {
       const result = {
         ok: false,
         code: 'PROJECT_EXISTS_LOCALLY',
-        message: `Existing Shiplens configuration detected (App ID: ${existing.app_id}) in ${existing.source_file}. Use --force to overwrite.`,
+        message: `检测到本地已存在 Shiplens 统计配置 (项目 ID: ${existing.app_id})，位于 ${existing.source_file}。` +
+          `选项 1 [推荐]: 保持现有统计，保留原项目编号与历史数据；` +
+          `选项 2: 重新创建并覆盖 (追加 --force，向云端申请全新项目编号并覆盖本地，旧看板将停止接收新数据)。`,
         existing_app_id: existing.app_id,
         source_file: existing.source_file,
         project_name: existing.project_name || projectName,
@@ -45,43 +47,44 @@ async function handleInit(args, flags, ctx) {
       process.exitCode = 1;
       return;
     } else if (!process.stdin.isTTY) {
-      console.log(`\n⚠️  Existing Shiplens project detected!`);
-      console.log(`📌 App ID: ${existing.app_id} (Source: ${existing.source_file})`);
-      console.log(`📊 Dashboard: ${ctx.client.baseURL}/dashboard/${existing.app_id}`);
-      console.log(`🛑 Non-interactive terminal detected (CI/Agent). Existing configuration preserved.`);
-      console.log(`💡 To overwrite and create a new project, run with --force:`);
-      console.log(`   npx @shiplens/cli init --force\n`);
+      console.log(`\n⚠️  检测到当前项目已存在 Shiplens 配置！`);
+      console.log(`📌 本地已存在项目编号: ${existing.app_id} (来源: ${existing.source_file})`);
+      console.log(`📊 现有数据看板: ${ctx.client.baseURL}/dashboard/${existing.app_id}`);
+      console.log(`🛑 检测到非交互式终端环境 (CI/Agent)，已自动保留现有配置。`);
+      console.log(`💡 选项 1 [推荐]: 保持现有统计，保留原项目 ID 与历史数据；`);
+      console.log(`💡 选项 2: 若要强制重新创建新项目并覆盖本地配置，请追加 --force 参数:`);
+      console.log(`   npx.cmd --yes @shiplens/cli init --force\n`);
       return;
     } else {
-      console.log(`\n⚠️  Existing Shiplens project detected!`);
-      console.log(`📌 App ID: ${existing.app_id} (Source: ${existing.source_file})`);
-      console.log(`📊 Dashboard: ${ctx.client.baseURL}/dashboard/${existing.app_id}`);
-      console.log(`\n💡 Option 1 [Recommended]: Keep existing setup and reuse App ID.`);
-      console.log(`💡 Option 2: Run with --force to overwrite and create a new project:`);
-      console.log(`   npx @shiplens/cli init --force\n`);
+      console.log(`\n⚠️  检测到当前项目可能正在统计中！`);
+      console.log(`📌 本地已存在项目编号: ${existing.app_id} (来源: ${existing.source_file})`);
+      console.log(`📊 现有数据看板: ${ctx.client.baseURL}/dashboard/${existing.app_id}`);
+      console.log(`\n💡 选项 1 [推荐]: 保持现有统计，继续使用原项目 ID，历史数据和现有看板完整保留；`);
+      console.log(`💡 选项 2: 强制重新创建并覆盖 (追加 --force)，申请全新空白项目 ID 覆盖本地 (注意：旧看板停止接收新数据，新旧数据无法合并):`);
+      console.log(`   npx.cmd --yes @shiplens/cli init --force\n`);
 
       const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
       const confirmed = await new Promise((resolve) => {
-        rl.question('Overwrite and create a new project? (y/N): ', (ans) => {
+        rl.question('是否确认覆盖并重新创建全新项目？(y/N): ', (ans) => {
           rl.close();
           resolve(ans.trim().toLowerCase() === 'y' || ans.trim().toLowerCase() === 'yes');
         });
       });
       if (!confirmed) {
-        console.log('🛑 Operation cancelled. Existing configuration preserved.');
+        console.log('🛑 操作已取消，已保留原项目配置与统计。');
         return;
       }
     }
   }
 
-  // 2. Inject AI Skill (.agents/skills/shiplens/SKILL.md & Cursor rules)
+  // 2. 自动释放/注入通用 AI Skill 技能书 (.agents/skills/shiplens/SKILL.md 及 rules)
   const skillFile = injectSkill(wd);
 
-  // 3. Register project on cloud
+  // 3. 上报/同步到服务端注册项目
   let appId = '';
   let dashboardUrl = '';
   let accountStatus = 'not_logged_in_unlinked';
-  let accountStatusText = 'Not Logged In (Project unlinked)';
+  let accountStatusText = '未登录 (首次安装默认状态或本地不存在有效凭据)';
 
   try {
     const connResp = await ctx.client.connect({
@@ -99,24 +102,24 @@ async function handleInit(args, flags, ctx) {
     if (ctx.resolvedAuth && ctx.resolvedAuth.is_present) {
       if (connResp.account_linked !== false && connResp.linked !== false && !connResp.unlinked) {
         accountStatus = 'logged_in_linked';
-        accountStatusText = 'Logged In (Project linked to account)';
+        accountStatusText = '已登录 (项目已与账号关联)';
       } else {
         accountStatus = 'logged_in_unlinked';
-        accountStatusText = 'Logged In (Project not linked to account)';
+        accountStatusText = '已登录 (项目和账号未关联)';
       }
     } else {
       accountStatus = 'not_logged_in_unlinked';
-      accountStatusText = 'Not Logged In (Project unlinked)';
+      accountStatusText = '未登录 (首次安装默认状态或本地不存在有效凭据)';
     }
   } catch (netErr) {
     netErr.code = netErr.code || 'CONNECT_FAILED';
     throw netErr;
   }
 
-  // 4. Inject SDK code
+  // 4. 自动插桩注入 SDK 代码
   const injectedFile = injectSDK(wd, framework, appId);
 
-  // 5. Save local configuration
+  // 5. 写入本地状态机 .shiplens.json
   saveLocalConfig(wd, {
     app_id: appId,
     project_name: projectName,
@@ -129,17 +132,17 @@ async function handleInit(args, flags, ctx) {
     last_synced_at: new Date().toISOString(),
   });
 
-  // 6. Install SDK dependency
+  // 6. 安装依赖 (4-Tier 阶梯并发竞速)
   let installResult = { success: true, manager: 'skipped' };
   if (!flags['no-install'] && detected.package_manager) {
     installResult = await installSDKDependency(wd, detected.package_manager);
     if (!installResult.success) {
-      const errMsg = `SDK installation failed: Unable to download @shiplens/sdk across all download sources (official npm registry, Alibaba Cloud npmmirror, GitHub mirror, and Shiplens CDN mirror).\n` +
-        `Troubleshooting steps:\n` +
-        `  1. Check your local network connection or HTTP proxy / VPN settings;\n` +
-        `  2. Try running manually with Alibaba mirror: npm install @shiplens/sdk --registry=https://registry.npmmirror.com;\n` +
-        `  3. Or install via official registry: npm install @shiplens/sdk;\n` +
-        `  4. Visit https://shiplens.com for latest SDK status and installation guides.`;
+      const errMsg = `SDK 安装失败: 无法从 NPM 官方源、备用镜像源、GitHub 源码镜像或官方 CDN 镜像下载安装 @shiplens/sdk。\n` +
+        `排查步骤建议:\n` +
+        `  1. 检查本地网络连接或 HTTP 代理 / VPN 状态；\n` +
+        `  2. 尝试手动使用备用镜像安装: npm install @shiplens/sdk --registry=https://registry.npmmirror.com；\n` +
+        `  3. 或手动通过官方源安装: npm install @shiplens/sdk；\n` +
+        `  4. 访问 https://shiplens.dev 查看最新 SDK 状态与手动安装指南。`;
 
       if (ctx.isJSON) {
         ctx.output({
@@ -157,7 +160,7 @@ async function handleInit(args, flags, ctx) {
     }
   }
 
-  // 7. Bind email if specified
+  // 7. 绑定邮箱 (若用户显式指定或传 auto)
   let targetEmail = flags.email;
   if (targetEmail === 'auto') {
     targetEmail = getGitEmail();
@@ -180,12 +183,6 @@ async function handleInit(args, flags, ctx) {
     }
   }
 
-  // 8. Auto Git commit
-  let gitCommitResult = { committed: false };
-  if (!flags['no-commit']) {
-    gitCommitResult = autoGitCommit(wd, 'feat: Integrate Shiplens SDK and configure dashboard');
-  }
-
   const elapsed = Date.now() - start;
   const taxonomyFormatted = formatTaxonomySummary(taxonomy);
 
@@ -208,44 +205,39 @@ async function handleInit(args, flags, ctx) {
     auth_status: authStatus,
     shiplens_env_written: authStatus === 'magic_link_sent',
     activation_required: authStatus === 'pending',
-    free_tier_info: '50,000 free events/month (~5,000 unique visitors)',
+    free_tier_info: '每月 50,000 事件 (约 5,000 独立访客) 永久免费统计额度',
     bound_email: targetEmail || undefined,
-    git_committed: gitCommitResult.committed,
-    git_commit_hash: gitCommitResult.hash || undefined,
     elapsed_ms: elapsed,
     atomic_completed: true,
   };
 
   ctx.output(result, () => {
     console.log(`\n==================================================`);
-    console.log(`✅ Shiplens SDK successfully integrated (${elapsed} ms)\n`);
-    console.log(`📦 Project & Dashboard Information`);
-    console.log(`Project Name: ${projectName}`);
+    console.log(`✅ Shiplens 数据统计 SDK 已成功安装并完成代码插桩！(耗时 ${elapsed} ms)\n`);
+    console.log(`📦 项目与数据看板信息`);
+    console.log(`项目名称: ${projectName}`);
     if (description) {
-      console.log(`Description: ${description}`);
+      console.log(`项目详情: ${description}`);
     }
     if (taxonomyFormatted) {
-      console.log(`Taxonomy:`);
+      console.log(`项目类别:`);
       console.log(taxonomyFormatted);
     }
-    console.log(`App ID: ${appId}`);
-    console.log(`Code Injection: Automatically configured in ${injectedFile} (Framework: ${framework})`);
-    console.log(`Live Dashboard / Activation URL: 🔗 ${dashboardUrl}`);
-    console.log(`User Account: ${accountStatusText}`);
-    if (gitCommitResult.committed) {
-      console.log(`Git Commit: Automatically committed changes (Commit: ${gitCommitResult.hash})`);
-    }
-    console.log(`🧠 AI Skill Ready: ${skillFile}`);
-    console.log(`🔒 [SHIPLENS_ATOMIC_COMPLETED] Setup completed atomically. No extra commands needed.`);
+    console.log(`应用 ID (App ID): ${appId}`);
+    console.log(`代码注入: 已自动在入口文件 ${injectedFile} 中配置集成 (框架: ${framework})`);
+    console.log(`实时数据看板 / 项目激活链接: 🔗 ${dashboardUrl}`);
+    console.log(`用户个人账号: ${accountStatusText}`);
+    console.log(`🧠 AI 技能就绪: ${skillFile}`);
+    console.log(`🔒 [SHIPLENS_ATOMIC_COMPLETED] 所有操作已原子化闭环，无需执行 git status / doctor 等额外检查。`);
     console.log(`==================================================\n`);
 
     if (authStatus === 'magic_link_sent' && targetEmail) {
-      console.log(`📧 Activation email sent to: ${targetEmail}`);
-      console.log(`👉 Click the link in your email to activate your 50,000 monthly free events quota and authorize this device.`);
+      console.log(`📧 激活邮件已发送至: ${targetEmail}`);
+      console.log(`👉 请点击邮件中的链接完成注册与设备授权，即可永久激活每月 50,000 事件免费统计额度。`);
     } else {
       console.log(`> [!IMPORTANT]`);
-      console.log(`> **Project Pending Activation (Analytics not active yet)**`);
-      console.log(`> **Please share your email**: Click the link in the email to complete registration, activate 50,000 free monthly events (~5,000 visitors), and bind your project to your account. Once activated, you can chat directly with me to query and analyze product data.`);
+      console.log(`> **项目待激活（数据统计尚未生效）**`);
+      console.log(`> **请告诉我您的邮箱**：点击邮件中的链接即可完成注册，激活每月 50,000 事件的免费额度（约5000人访问），同时绑定项目和账号；激活后您与我直接对话，我就有权限查询并分析产品数据。`);
     }
   });
 }

package/lib/commands/mcp.js

@@ -39,9 +39,9 @@ function emitResponse(result) {
 }
 
 async function handleMcp(subcommand) {
-  if (subcommand !== 'serve') throw new Error('Supported mcp subcommand: serve');
+  if (subcommand !== 'serve') throw new Error('支持的 mcp 子命令: serve');
   const deviceEnv = getDeviceEnv();
-  if (!deviceEnv) throw new Error('shiplens.env not found. Run shiplens auth bind and complete email activation first.');
+  if (!deviceEnv) throw new Error('未找到 shiplens.env，请先执行 shiplens auth bind 并完成邮件激活');
   let buffer = '';
   let sessionId = '';
   process.stdin.setEncoding('utf8');

package/lib/commands/pages.js

@@ -4,22 +4,23 @@ async function handlePages(args, flags, ctx) {
   const env = flags.env || 'production';
   const limit = parseInt(flags.limit || '10', 10);
 
-  const resp = await ctx.client.getPages({ app_id: appId, range, env, limit });
+  const resp = await ctx.client.pages(appId, range, env, limit);
 
   ctx.output(resp, () => {
-    console.log(`📄 Page Telemetry Evidence (Range: ${range}, Top ${limit}):\n`);
+    console.log(`📄 页面证据分析 (时间范围: ${range}, 前 ${limit} 页):\n`);
     const pages = Array.isArray(resp.pages) ? resp.pages : (Array.isArray(resp) ? resp : []);
     if (pages.length === 0) {
-      console.log('(No page data found. Verify SDK reporting.)');
+      console.log('（暂无页面数据，请确认 SDK 已正常上报）');
       return;
     }
-    console.log('#   | Path / Title                       | PV      | UV      | Avg Dwell(s)');
-    console.log('--- | ---------------------------------- | ------- | ------- | ------------');
+    // 表格化输出
+    console.log('序号 | 路径/标题                          | PV      | UV      | 平均停留(s)');
+    console.log('---  | ---------------------------------- | ------- | ------- | ----------');
     pages.forEach((p, i) => {
       const path = (p.path || p.template_id || '-').padEnd(34);
       const pv = String(p.pv || p.pageviews || 0).padEnd(7);
       const uv = String(p.uv || p.unique_visitors || 0).padEnd(7);
-      const dur = String(p.avg_duration_s || p.avg_session_duration_s || 0).padEnd(12);
+      const dur = String(p.avg_duration_s || p.avg_session_duration_s || 0).padEnd(10);
       console.log(`[${String(i + 1).padEnd(2)}] | ${path} | ${pv} | ${uv} | ${dur}`);
     });
   });
@@ -30,27 +31,30 @@ async function handlePaths(args, flags, ctx) {
   const range = flags.range || '7d';
   const env = flags.env || 'production';
 
-  const resp = await ctx.client.queryPaths({ app_id: appId, range, env });
+  const resp = await ctx.client.paths(appId, range, env);
 
   ctx.output(resp, () => {
-    console.log(`🔀 User Flow & Path Analysis (Range: ${range}):\n`);
+    console.log(`🔀 页面流转路径分析 (时间范围: ${range}):\n`);
 
+    // 入口页面
     if (resp.entry_pages && resp.entry_pages.length > 0) {
-      console.log('▶ Top Entry Pages:');
+      console.log('▶ 主要入口页面:');
       resp.entry_pages.slice(0, 5).forEach((e, i) =>
-        console.log(`  [${i + 1}] ${e.path || e.page} - ${e.sessions || e.count || 0} sessions`)
+        console.log(`  [${i + 1}] ${e.path || e.page} — ${e.sessions || e.count || 0} 次会话`)
       );
     }
+    // 退出页面
     if (resp.exit_pages && resp.exit_pages.length > 0) {
-      console.log('\n◀ Top Exit Pages:');
+      console.log('\n◀ 主要退出页面:');
       resp.exit_pages.slice(0, 5).forEach((e, i) =>
-        console.log(`  [${i + 1}] ${e.path || e.page} - Exit Rate ${((e.exit_rate || 0) * 100).toFixed(1)}%`)
+        console.log(`  [${i + 1}] ${e.path || e.page} — 退出率 ${((e.exit_rate || 0) * 100).toFixed(1)}%`)
       );
     }
+    // 路径流转
     if (resp.paths && resp.paths.length > 0) {
-      console.log('\n↔ High-Frequency Paths:');
+      console.log('\n↔ 高频页面流转路径:');
       resp.paths.slice(0, 8).forEach((p, i) =>
-        console.log(`  [${i + 1}] ${p.from || p.source} → ${p.to || p.target}  (${p.count || p.sessions || 0} times)`)
+        console.log(`  [${i + 1}] ${p.from || p.source} → ${p.to || p.target}  (${p.count || p.sessions || 0} 次)`)
       );
     } else {
       console.log(JSON.stringify(resp, null, 2));
@@ -63,18 +67,18 @@ async function handleCanvas(args, flags, ctx) {
   const range = flags.range || '7d';
   const env = flags.env || 'production';
 
-  const resp = await ctx.client.queryPaths({ app_id: appId, range, env, mode: 'canvas' });
+  const resp = await ctx.client.behaviorCanvas(appId, range, env);
 
   ctx.output(resp, () => {
-    console.log(`🎨 User Behavior Canvas Topology (Range: ${range}):\n`);
+    console.log(`🎨 用户行为画布拓扑 (时间范围: ${range}):\n`);
     const nodeCount = (resp.nodes || []).length;
     const edgeCount = (resp.edges || resp.links || []).length;
     if (nodeCount > 0 || edgeCount > 0) {
-      console.log(`📍 ${nodeCount} nodes, ${edgeCount} edges`);
+      console.log(`📍 共 ${nodeCount} 个节点, ${edgeCount} 条边`);
       if (resp.nodes && resp.nodes.length > 0) {
-        console.log('\nMain Nodes:');
+        console.log('\n主要节点:');
         resp.nodes.slice(0, 10).forEach((n, i) =>
-          console.log(`  [${i + 1}] ${n.label || n.path || n.id}  (Visits: ${n.value || n.count || 0})`)
+          console.log(`  [${i + 1}] ${n.label || n.path || n.id}  (访问量: ${n.value || n.count || 0})`)
         );
       }
     } else {

package/lib/commands/projects.js

@@ -9,19 +9,19 @@ async function handleProjects(subcommand, args, flags, ctx) {
       ctx.output(resp, () => {
         const projects = resp.projects || [];
         if (projects.length === 0) {
-          console.log('No associated projects found. Use shiplens init to create a new project.');
+          console.log('暂无关联项目。可使用 shiplens init 初始化一个新项目。');
           return;
         }
-        console.log(`📦 Found ${projects.length} project(s):\n`);
+        console.log(`📦 共有 ${projects.length} 个项目:\n`);
         projects.forEach((p, i) => {
           console.log(`[${i + 1}] ${p.project_name || p.app_name || 'Untitled'} (${p.app_id})`);
-          if (p.description) console.log(`    Description: ${p.description}`);
+          if (p.description) console.log(`    简介: ${p.description}`);
           if (p.taxonomy?.subgenre?.name) {
             const tags = (p.taxonomy.feature_tags || []).map((tag) => tag.name).join(', ');
-            console.log(`    Taxonomy: ${p.taxonomy.genre?.name || '-'} / ${p.taxonomy.subgenre.name}${tags ? ` - ${tags}` : ''}`);
+            console.log(`    分类: ${p.taxonomy.genre?.name || '-'} / ${p.taxonomy.subgenre.name}${tags ? ` · ${tags}` : ''}`);
           }
-          console.log(`    Industry: ${p.industry || '-'} | Status: ${p.status || 'active'} | Schema Timestamp: ${p.schema_last_modified_at || 0}`);
-          if (p.created_at) console.log(`    Created: ${p.created_at}`);
+          console.log(`    行业: ${p.industry || '-'} | 状态: ${p.status || 'active'} | Schema更新时间戳: ${p.schema_last_modified_at || 0}`);
+          if (p.created_at) console.log(`    创建时间: ${p.created_at}`);
           console.log('');
         });
       });
@@ -32,7 +32,7 @@ async function handleProjects(subcommand, args, flags, ctx) {
       const appId = ctx.resolveAppId();
       const res = await ctx.client.bindProject(appId, flags.name);
       ctx.output(res, () => {
-        console.log(`✅ Project ${appId} bound to current account successfully.`);
+        console.log(`✅ 项目 ${appId} 已成功绑定至当前账号！`);
       });
       break;
     }
@@ -40,36 +40,36 @@ async function handleProjects(subcommand, args, flags, ctx) {
     case 'delete': {
       const appId = ctx.resolveAppId();
       if (!flags.force) {
-        console.log(`⚠️ Warning: Deleting project ${appId} and all historical event data. This action cannot be undone!`);
+        console.log(`⚠️ 警告：正在删除项目 ${appId} 及其全部历史事件数据。该操作不可逆！`);
         const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
         const confirmed = await new Promise((resolve) => {
-          rl.question(`Enter App ID or 'yes' to confirm deletion: `, (ans) => {
+          rl.question(`请输入项目 ID 或 'yes' 确认删除: `, (ans) => {
             rl.close();
             resolve(ans.trim() === 'yes' || ans.trim() === appId);
           });
         });
         if (!confirmed) {
-          console.log('🛑 Operation cancelled.');
+          console.log('🛑 操作已取消。');
           return;
         }
       }
 
       const res = await ctx.client.deleteProject(appId);
 
-      // Clean up local business context file
+      // 清理本地专属业务上下文文件
       const localContextPath = path.join(process.cwd(), '.shiplens', 'contexts', `${appId}.md`);
       if (fs.existsSync(localContextPath)) {
         try { fs.unlinkSync(localContextPath); } catch {}
       }
 
       ctx.output(res, () => {
-        console.log(`🗑️ Project ${appId} deleted successfully.`);
+        console.log(`🗑️ 项目 ${appId} 已被成功删除。`);
       });
       break;
     }
 
     default:
-      throw new Error(`Unknown projects subcommand: ${subcommand}. Supported: list, bind, delete`);
+      throw new Error(`未知的 projects 子命令: ${subcommand}。支持 list, bind, delete`);
   }
 }
 

package/lib/commands/query.js

@@ -11,28 +11,29 @@ async function handleQuery(args, flags, ctx) {
 
   let queryReq;
 
-  // Support --file: read full AnalyticsQueryRequest from JSON file
+  // 支持 --file：从 JSON 文件读取完整 AnalyticsQueryRequest，最大灵活度
   if (flags.file) {
     if (!fs.existsSync(flags.file)) {
-      const err = new Error(`Query config file not found: ${flags.file}`);
+      const err = new Error(`查询配置文件不存在: ${flags.file}`);
       err.code = 'INVALID_ARGS';
       throw err;
     }
     try {
       queryReq = JSON.parse(fs.readFileSync(flags.file, 'utf8'));
     } catch (e) {
-      const err = new Error(`Failed to parse query config file (${flags.file}): ${e.message}`);
+      const err = new Error(`无法解析查询配置文件 (${flags.file}): ${e.message}`);
       err.code = 'INVALID_ARGS';
       throw err;
     }
+    // 允许用命令行 range / env 覆盖文件中的值
     if (!queryReq.range) queryReq.range = range;
     if (!queryReq.env) queryReq.env = env;
   } else {
-    // Support --metrics (comma-separated) or --metric
+    // 支持 --metrics 多指标（逗号分隔）或单指标 --metric
     const metricsRaw = flags.metrics || flags.metric || 'pageviews';
     const metricList = String(metricsRaw).split(',').map((m) => m.trim()).filter(Boolean);
 
-    // Parse --filter key=val
+    // 解析 --filter key=val（可多次指定）
     const filters = {};
     const filterList = Array.isArray(flags.filter)
       ? flags.filter
@@ -42,12 +43,13 @@ async function handleQuery(args, flags, ctx) {
       if (k && v.length > 0) filters[k.trim()] = v.join('=').trim();
     }
 
+    // 每个指标生成一个 panel
     queryReq = {
       env,
       range,
       panels: metricList.map((metric, idx) => ({
         panel_id: `panel_cli_${idx}`,
-        title: `${metric} Trend`,
+        title: `${metric} 趋势`,
         metric,
         chart_type: chartType,
         time_grain: grain,
@@ -58,22 +60,22 @@ async function handleQuery(args, flags, ctx) {
     };
   }
 
-  const resp = await ctx.client.query(appId, queryReq);
+  const resp = await ctx.client.queryAnalytics(appId, queryReq);
 
   ctx.output(resp, () => {
     const metricNames = (queryReq.panels || []).map((p) => p.metric).join(', ');
-    console.log(`📊 Query Metrics: ${metricNames} | Range: ${queryReq.range}`);
+    console.log(`📊 查询指标: ${metricNames} | 时间范围: ${queryReq.range}`);
     if (resp.data && resp.data.length > 0) {
       resp.data.forEach((row) => console.log('•', JSON.stringify(row)));
     } else if (resp.panels && resp.panels.length > 0) {
       resp.panels.forEach((p) => {
-        console.log(`\n📈 Panel: ${p.title || p.panel_id}`);
+        console.log(`\n📈 面板: ${p.title || p.panel_id}`);
         if (Array.isArray(p.data)) {
           p.data.forEach((row) => console.log('  •', JSON.stringify(row)));
         }
       });
     } else {
-      console.log('(No matching data found)');
+      console.log('（暂无匹配数据）');
     }
   });
 }

package/lib/commands/sql.js

@@ -2,7 +2,7 @@ async function handleSQL(args, flags, ctx) {
   const appId = ctx.resolveAppId();
   let queryStr = flags.query || flags.sql || args.join(' ');
 
-  // Support --stdin for piped SQL execution
+  // 支持 --stdin：从标准输入读取 SQL（兼容管道，如 echo "SELECT..." | shiplens sql --stdin）
   if (flags.stdin || flags['read-stdin']) {
     const chunks = [];
     for await (const chunk of process.stdin) {
@@ -13,18 +13,19 @@ async function handleSQL(args, flags, ctx) {
   }
 
   if (!queryStr) {
-    const err = new Error('SQL query string cannot be empty. Pass --query "SELECT ..." or pipe via --stdin.');
+    const err = new Error('SQL 查询语句不能为空，请使用 --query "SELECT ..." 或通过管道传入 --stdin');
     err.code = 'INVALID_SQL';
     throw err;
   }
 
-  const resp = await ctx.client.executeSQL({ app_id: appId, query: queryStr });
+  const resp = await ctx.client.executeSQL(appId, queryStr);
 
   ctx.output(resp, () => {
     const rowCount = resp.row_count !== undefined ? resp.row_count : (resp.rows ? resp.rows.length : 0);
-    console.log(`🔍 SQL executed successfully (${resp.elapsed_ms || 0} ms, ${rowCount} rows returned):\n`);
+    console.log(`🔍 SQL 执行成功 (耗时: ${resp.elapsed_ms || 0} ms, 返回 ${rowCount} 行):\n`);
 
     if (resp.columns && resp.columns.length > 0) {
+      // 计算每列宽度，对齐输出
       const colWidths = resp.columns.map((col) => {
         let maxW = col.length;
         if (resp.rows) {

package/lib/commands/summary.js

@@ -6,16 +6,16 @@ async function handleSummary(args, flags, ctx) {
   const resp = await ctx.client.summary(appId, range, env);
 
   ctx.output(resp, () => {
-    console.log(`📈 Core Product Summary (Range: ${range}):`);
-    console.log(`• Total Pageviews (PV): ${resp.total_pv || 0}`);
-    console.log(`• Unique Visitors (UV): ${resp.total_uv || 0}`);
-    console.log(`• Avg Session Duration: ${resp.avg_session_duration_s || 0} s`);
-    console.log(`• Bounce Rate: ${((resp.bounce_rate || 0) * 100).toFixed(1)}%`);
+    console.log(`📈 产品核心数据摘要 (时间范围: ${range}):`);
+    console.log(`• 总浏览量 (PV): ${resp.total_pv || 0}`);
+    console.log(`• 独立访客 (UV): ${resp.total_uv || 0}`);
+    console.log(`• 平均会话时长: ${resp.avg_session_duration_s || 0} 秒`);
+    console.log(`• 跳出率: ${((resp.bounce_rate || 0) * 100).toFixed(1)}%`);
     if (resp.top_countries && resp.top_countries.length > 0) {
-      console.log('• Top Countries:', resp.top_countries);
+      console.log('• Top 国家/地区:', resp.top_countries);
     }
     if (resp.top_devices && resp.top_devices.length > 0) {
-      console.log('• Top Devices:', resp.top_devices);
+      console.log('• Top 访问设备:', resp.top_devices);
     }
   });
 }