@shiplens/cli 1.3.1 → 1.4.1

package/lib/assets/skill.js

@@ -1,127 +1,204 @@
 const SKILL_CONTENT = `---
 name: shiplens-analytics
-description: Shiplens Web User Telemetry & AI Dashboard Skill Specification. Includes project onboarding, diagnostics, CLI & MCP dual integration, authentication, metadata caching, safe SQL analytics, and single-prompt workflow.
+description: Shiplens Web 数据分析 — Agent 行为协议、排障诊断与数据分析执行。
 ---
 
-# Shiplens Web Analytics Skill Specification (v2.0)
+# Shiplens Web 数据分析 Skill 指引
 
-> 💡 **Core Overview & Official Reference**:
-> 1. **Dual Track Integration**: Supports instant onboarding via **Shiplens CLI** (\`shiplens init\` / \`npx @shiplens/cli init\`) for dependency setup, project creation, and code injection; full support for **MCP Tools** and standard REST APIs inside IDE / Agent environments.
-> 2. Installing the SDK and viewing live dashboards requires no MCP server; advanced analytics requires authentication via OAuth, API keys/environment variables, or CLI credentials.
-> 3. **Authoritative FAQ**: \`https://shiplens.dev/faq\`.
+Shiplens 通过 CLI 与 MCP 提供 Web 用户行为数据分析。本文档定义 AI Agent 如何为使用 Shiplens 的项目进行排障自检、项目接入与数据分析。
 
-You are connected to **Shiplens Web Analytics & MCP Services**. When providing analytics, funnel diagnostics, cohort retention comparisons, and AI dashboard creation, follow the standard workflow and execution protocols below.
+---
+
+## 1. 环境排障自检
+
+执行任何分析命令前，检查三项线索以判定项目状态：
+
+| 线索 | 检查项 |
+|------|--------|
+| **鉴权** | 本地是否存在 \`shiplens.env\` 或环境变量 \`SHIPLENS_ACCESS_SECRET\`？ |
+| **SDK** | \`package.json\` 是否包含 \`@shiplens/sdk\` 且源码已插桩？ |
+| **云端** | 云端接口（\`GET /api/projects\`）是否能查询到对应项目？ |
+
+### 四状态矩阵
+
+| 状态 | 判定条件 | 应对行为 |
+|------|----------|----------|
+| **状态 A — 正常完备** | 鉴权与云端项目皆具备 | 直接开始数据分析（§3） |
+| **状态 A-1 — 有鉴权无项目** | 鉴权成功，但云端账号下无项目或当前项目未归属于该账号 | 提示用户前往 \`https://shiplens.dev\` 检查账号或创建/认领项目（非本地代码缺失） |
+| **状态 B — 缺少鉴权 / 换电脑** | SDK 已装，但本地缺有效凭据 | 询问：*“您之前是否注册过 Shiplens 账号？”*<br/>• **已注册** → 引导前往 \`https://shiplens.dev/settings/api-keys\` 下载 \`shiplens.env\` 放置到项目根目录下（亦可复制密钥后执行 \`shiplens auth set --secret <key>\` 保存）<br/>• **未注册** → 引导提供邮箱执行 \`shiplens auth bind --email <邮箱> --json\` 发送激活邮件 |
+| **状态 C — 完全冷启动** | SDK 未装，缺鉴权 | 引导执行初始化接入（§2） |
+
+该矩阵同时作为排障基准线。系统出现任何异常时，按此三项线索回溯排查。
 
 ---
 
-## 1. Project Onboarding & Step-by-Step Diagnostics
+## 2. 项目极速接入
 
-### Standard Workflow:
+### 执行接入
+\`\`\`bash
+npx.cmd --yes @shiplens/cli init --json          # Windows
+npx --yes @shiplens/cli init --json               # macOS / Linux
 \`\`\`
-Check Existing App ID ➔ Install SDK ➔ POST Connect & Get Dashboard URL ➔ Request Email for Free Quota ➔ Activate Magic Link ➔ Authenticate ➔ Complete
+备用镜像：追加 \`--registry=https://registry.npmmirror.com\`
+
+### 初始化操作（约 15 秒，单命令完成）
+1. 识别前端框架（Next.js / Vite / Vue / HTML）
+2. 4 级分类体系 (Genre/Subgenre/Tags) 智能推断与打标
+3. 安装 \`@shiplens/sdk\` 依赖
+4. 在入口文件注入采集代码
+5. 请求 \`POST /api/connect\` 注册项目 → 获取 \`app_id\` 与 \`dashboard_url\`
+6. 提取页面/按钮文案并写入本地 \`.shiplens/contexts/<app_id>.md\`
+7. 写入本地状态机 \`./.shiplens.json\`
+8. 下发通用 Agent Skill 规范（\`.agents/skills/shiplens/SKILL.md\` 与 rules）
+
+### 防误覆盖保护与大白话对比
+若本地已存在 \`./.shiplens.json\` 或代码已插桩，**必须暂停并比对配置，向用户以通俗大白话讲清利弊**：
+- **【推荐】保持现有统计**：继续沿用当前项目编号（ID: \`<已有app_id>\`），历史统计数据和看板完整保留，新访问将继续累积到现有看板中，无需修改代码；
+- **【覆盖】使用 \`--force\` 重新创建**：向云端申请一个全新的空白项目编号并覆盖本地代码插桩。**这意味着旧看板将停止接收新数据，后续数据将记录到全新空白看板中，新旧数据无法在同一个看板中直接合并**。
+
+### 接入后：索要邮箱激活额度 & 凭据机制
+向用户索要邮箱以激活 **每月 50,000 条免费事件（约 5,000 人访问）**：
+\`\`\`bash
+shiplens auth bind --email <邮箱> --json
 \`\`\`
 
-> ⚡ **Quick Execution**: In a terminal environment, execute \`npx.cmd --yes @shiplens/cli init --json\` (Windows) or \`npx --yes @shiplens/cli init --json\` (macOS/Linux) for automated 15-second zero-config setup. (China mirror fallback: \`--registry=https://registry.npmmirror.com\`).
+- **凭据下发机制**：执行 \`auth bind\` 时，服务端会随响应下发设备专属凭据，CLI 自动将其安全写入项目根目录的 \`shiplens.env\`（权限 0600）；
+- **激活即生效**：用户在邮箱中点击 Magic Link 完成注册激活后，**云端立即激活该设备凭据**；
+- **零后续摩擦**：本地 Agent **无需执行额外的登录命令或索要 Token**，已写入的 \`shiplens.env\` 即刻生效，后续的数据查询（\`shiplens query\`）与 MCP 服务（\`shiplens mcp serve\`）直接可用。
+
+### 汇报模板
+初始化完成后，输出标准卡片：
 
-### Step 0. Existing Project Detection (Overwrite Protection)
-- Check if \`./.shiplens.json\` or SDK instrumentation (\`initShiplens\`, \`data-app-id\`) exists locally.
-- If existing project is detected, pause and ask the user whether to reuse the existing ID or force overwrite with \`--force\`.
+\`\`\`markdown
+### 📊 项目与数据看板信息
+- **项目名称**：\\\`<project_name>\\\`
+- **应用 ID (App ID)**：\\\`<app_id>\\\`
+- **代码注入**：已在 [\\\`<injected_file>\\\`](file:///<path>) 中完成配置
+- **实时看板**：[\\\`<dashboard_url>\\\`](<dashboard_url>)
+- **用户个人账号**：<用户个人账号状态>
 
-### Step 1. Framework Auto-Detection & SDK Injection
-- Auto-detect Next.js (App/Pages router), Vite (React/Svelte), Vue 3, or Plain HTML.
-- Inject SDK code:
-  - **Next.js App Router**: Client component \`ShiplensTracker.tsx\` imported into root \`layout.tsx\`.
-  - **Vite / Vue**: Import and initialize \`initShiplens({ appId: '<app_id>' })\` in \`main.ts\` / \`main.js\`.
-  - **Plain HTML**: Inject \`<script src="https://cdn.shiplens.dev/sdk.js" data-app-id="<app_id>" defer></script>\` in \`<head>\`.
+> [!IMPORTANT]
+> **项目待激活（数据统计尚未生效）**
+> **请告诉我您的邮箱**：点击邮件中的链接即可完成注册，激活每月 50,000 事件的免费额度（约5000人访问），同时绑定项目和账号；激活后您与我直接对话，我就有权限查询并分析产品数据。
+\`\`\`
 
-### Step 2. Dependency Installation
-- Install \`@shiplens/sdk\` via \`npm\`, \`pnpm\`, \`yarn\`, or \`bun\` with \`--legacy-peer-deps\`.
+账号状态枚举：
+- \`已登录 (项目已与账号关联)\` — 本地存在有效凭据且云端项目已归属于当前账号
+- \`已登录 (项目和账号未关联)\` — 本地存在有效凭据但云端项目尚未归属于当前账号
+- \`未登录 (首次安装默认状态或本地不存在有效凭据)\` — 初次安装 CLI 或无有效凭据时的默认状态
 
-### Step 3. Cloud Registration (POST /api/connect)
-- Send project name, description, 4-level taxonomy (genre, subgenre, tags) to register project.
-- Retrieve permanent \`app_id\` and live \`dashboard_url\`.
+---
 
-#### ★ Initialization Standard Reporting Template
-Upon completing \`shiplens init\`, the Agent **MUST** present the exact information structure and immediately prompt for email activation:
+## 3. 数据分析协议 (6 步执行流)
 
-\`\`\`markdown
-Shiplens Analytics SDK successfully integrated and configured:
+当用户提出任何独立的数据分析需求时：
 
-### 📊 Project & Dashboard Information
-- **Project Name**: \`<project_name>\`
-- **App ID**: \`<app_id>\`
-- **Code Injection**: Automatically configured in [\`<injected_file>\`](file:///<absolute_path>)
-- **Live Dashboard / Activation URL**:
-  🔗 [<dashboard_url>](<dashboard_url>)
-- **User Account**: <User Account Status>
+**第 1 步 — 检查动态覆盖 (因地制宜)**：检查根目录是否存在 \`.shiplens/learnings.md\`。若存在，先读取【全局通用偏好】，再匹配当前分析场景对应的【场景细分偏好】（如留存分析偏好 14d、转化漏斗偏好 30d，严禁一刀切全局覆盖）。
 
----
+**第 2 步 — 锚定业务上下文**：读取 \`.shiplens/contexts/<app_id>.md\`（或执行 \`shiplens context show --json\`）。用具体页面名称和按钮文案解释数据，严禁仅输出生硬 ID。
 
-### 📦 Changes & Git Status
-- Changes automatically committed to Git (Commit: \`<hash>\`).
-- AI Skill ready: [\`.agents/skills/shiplens/SKILL.md\`](file:///<skill_path>).
+**第 3 步 — 定位分析场景**：打开 \`prompts/prompts_cli_zh.md\`，阅读顶部的**42 大场景全景提纲与索引导航**，找到契合场景，提取对应章节的确定性执行步骤与 SQL/CLI 语法。
 
-> [!IMPORTANT]
-> **Project Pending Activation (Analytics not active yet)**
-> **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.
-\`\`\`
+**第 4 步 — 执行命令**：执行预设的 CLI 命令，并带上第 1 步获取的场景细分覆盖参数。
 
-**User Account Status Evaluation**:
-- **State a**: \`Logged In (Project linked to account)\` / \`已登录（项目已于账号关联）\` — Local credentials exist and project is linked to user account.
-- **State b**: \`Logged In (Project not linked to account)\` / \`已登录（项目和账号未关联）\` — Local credentials exist but project could not be linked.
-- **State c**: \`Not Logged In (Project unlinked)\` / \`未登录（项目和账号可能未关联）\` — **Default state for first-time CLI installation or unauthenticated environments**.
+**第 5 步 — 输出深度洞察**：将数据转化为具体的业务结论与优化建议，结合第 2 步的业务上下文进行解读。
 
-### Step 4. Request Email for Quota Activation
-- Prompt user for email address to activate **50,000 monthly events** free tier.
-- Send Magic Link email via \`POST /api/auth/start-email\` (or \`shiplens auth bind --email <email> --json\`).
+**第 6 步 — 场景化自适应学习**：若用户对分析过程进行了纠偏（如针对留存提出“改用双周周期评估”），智能识别纠偏适用的场景范围，主动询问：*“是否需要我将「留存分析默认采用双周 14d 周期」记录到当前项目的 \`.shiplens/learnings.md\` 对应场景中？”* 确认后写入文件（§6）。
+
+### 优先级规则
+- **优先级 1**：\`.shiplens/learnings.md\` — 项目专属用户动态偏好（场景细分覆盖 > 全局通用偏好）
+- **优先级 2**：\`prompts/prompts_cli_zh.md\` — 42 个教科书经典分析场景底座
+
+---
+
+## 4. 核心 CLI 命令速查
+
+| 命令 | 用途 |
+|------|------|
+| \`shiplens init --json\` | 项目极速接入（§2） |
+| \`shiplens doctor --json\` | 诊断本地配置、代码插桩、SDK 安装、Ingestion 连通性与凭证状态 |
+| \`shiplens summary --range 7d --json\` | 宏观概览：总 PV、UV、停留时长、Top 来源 |
+| \`shiplens query --metric <m> --range 7d --json\` | 多维指标与转化漏斗查询 |
+| \`shiplens sql --query "<sql>" --json\` | 在 ClickHouse 只读沙箱上执行安全 SELECT 查询 |
+| \`shiplens pages --range 7d --json\` | 页面访问量与平均停留时长 |
+| \`shiplens paths --range 7d --json\` | 用户旅程与流转路径 |
+| \`shiplens heatmap --template <id> --json\` | 页面点击热力图与骨架图 |
+| \`shiplens dashboards create --title "..." --prompt "..." --json\` | AI 自动生成官方可视化看板 |
+| \`shiplens context push / pull / show\` | 业务上下文与页面按钮文案云端双向同步 |
+| \`shiplens auth bind --email <邮箱> --json\` | 发送 Magic Link 邮件绑定与下发凭据 |
+| \`shiplens auth set --secret <key>\` | 手动保存用户提供的 API 密钥到本地 \`shiplens.env\` |
+| \`shiplens mcp serve\` | 启动本地 stdio MCP 代理（供 AI Agent 客户端使用） |
+| \`shiplens projects delete --app-id <id> --json\` | 删除项目（**高危操作，必须二次确认**，§5） |
 
 ---
 
-## 2. Core CLI Commands Reference
+## 5. 安全红线与风控
 
-| Command | Purpose |
-| :--- | :--- |
-| \`shiplens doctor --json\` | End-to-end diagnostics on config, SDK, network, and credentials |
-| \`shiplens summary --range 7d --json\` | Product overview: PV, UV, bounce rates, top geos, devices |
-| \`shiplens query --metric <m> --range 7d --json\` | Multi-dimensional metric queries & funnels |
-| \`shiplens sql --query "<sql>" --json\` | Execute secure read-only SQL on ClickHouse |
-| \`shiplens pages --range 7d --json\` | Page-level visits and average dwell times |
-| \`shiplens paths --range 7d --json\` | Sankey user flow and transition paths |
-| \`shiplens heatmap --template <id> --json\` | Click heatmaps & skeleton wireframes |
-| \`shiplens dashboards create --title "..." --prompt "..." --json\` | Generate AI responsive dashboards |
-| \`shiplens auth bind --email <email> --json\` | Trigger Magic Link email binding |
+### 删除项目 — 强制二次确认 (HITL)
+删除任何项目前，必须执行：
+1. 向用户展示项目名称、\`app_id\` 及创建时间；
+2. 明确警告：*“此操作将彻底清空该项目的所有监控数据、看板与配置，且不可逆。”*；
+3. **暂停操作，等待用户显式回复“确认删除”**；
+4. 收到确认后方可执行 \`shiplens projects delete\`。
+
+严禁跳过确认静默删除。
+
+### SQL 安全规则
+- 必须携带时间范围：\`WHERE timestamp >= now() - INTERVAL <N> DAY\`
+- 必须带 \`LIMIT\`（最大 1000 行）
+- 查询目标表：\`events\`（ClickHouse 只读沙箱）
+
+### Windows 终端规范
+- npm/npx 命令带 \`.cmd\` 后缀：\`npx.cmd --yes\`、\`npm.cmd\`
+- 多命令连接使用分号 \`;\`，禁止使用 \`&&\`
 
 ---
 
-## 3. Dynamic Overrides & Adaptive Learning Protocol
+## 6. 自适应学习规范 (\`.shiplens/learnings.md\`)
+
+存放项目专属的用户偏好覆盖规则。在用户首次确认保存前**不默认创建**。
 
-When executing analytics requests (such as user prompts matching standard scenarios like \`What stage is my product in? What metrics should I track?\`), you must follow this 5-step protocol:
+### 标准文件格式（因地制宜）
+\`\`\`markdown
+# Shiplens AI 分析学习与项目偏好配置
+
+## 全局通用偏好 (Global Preferences)
+- exclude_user_ids: ["test_user_01", "internal_qa"]
+- default_time_grain: day
+
+## 场景细分偏好 (Scenario-Specific Overrides)
+### 场景: [用户留存与流失分析] (retention_curve / retention_matrix)
+- default_range: 14d # 用户偏好以双周周期评估留存衰减
+- focus_metrics: ["第 14 天留存率", "次周回访率"]
+
+### 场景: [转化漏斗与流失诊断] (funnel_dropoff)
+- default_range: 30d # 漏斗分析采用月度窗口
+- primary_conversion_goal: /checkout/success
+\`\`\`
 
-1. **Step 1 - Check Dynamic Overrides (Priority 1)**:
-   - Check if \`.shiplens/learnings.md\` exists in the project root.
-   - If present, apply any user-specified overrides (e.g. customized date range \`--range 14d\`, preferred metrics, custom funnel steps).
-2. **Step 2 - Context Grounding**:
-   - Check and read \`.shiplens/contexts/<app_id>.md\` (or run \`shiplens context show --json\`) to ground telemetry figures in real button labels and route semantics.
-3. **Step 3 - Deterministic CLI Execution (Priority 2 Base)**:
-   - Run the matched CLI command sequence with any overrides applied.
-4. **Step 4 - Business Synthesis**:
-   - Synthesize data into actionable takeaways and optimization levers.
-5. **Step 5 - Adaptive Learning**:
-   - If the user corrects your analysis (e.g. *"I need a 14-day window"* or *"Track signup completion as the final funnel step"*), immediately record the preference rule into \`.shiplens/learnings.md\` for future automatic reuse.
+### 维护规则
+- **严禁**在 \`init\` 时自动创建空文件
+- 仅在用户纠偏并明确确认后创建或追加
+- 每次写入前明确向用户确认适用场景范围
 
 ---
 
-## 4. SQL Standards & Guidelines
-
-- **Table Name**: \`events\` (Read-only ClickHouse instance)
-- **Key Columns**:
-  - \`timestamp\` (DateTime), \`event_name\` (String), \`user_id\` (String), \`session_id\` (String)
-  - \`template_id\` (String - DOM structure hash), \`page_path\` (String), \`referrer\` (String)
-  - \`properties\` (Map/JSON - custom event metadata)
-- **Rules**:
-  - Always apply time filters: \`timestamp >= now() - INTERVAL 7 DAY\`.
-  - Always specify \`LIMIT\` (maximum 1000 rows).
-  - Use ClickHouse aggregate functions: \`countIf()\`, \`quantile(0.50)()\`, \`dateDiff()\`.
+## 7. 数据表结构与 SQL 参考
+
+**数据表**：\`events\`（ClickHouse 只读实例）
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| \`timestamp\` | DateTime | 事件发生时间 |
+| \`event_name\` | String | pageview, click, custom |
+| \`user_id\` | String | 用户唯一标识 |
+| \`session_id\` | String | 会话唯一标识 |
+| \`template_id\` | String | DOM 结构哈希（页面骨架模板） |
+| \`page_path\` | String | 页面 URL 路径 |
+| \`referrer\` | String | 来源 URL |
+| \`properties\` | Map(String, String) | 自定义事件参数 |
+
+ClickHouse 常用聚合函数：\`countIf()\`, \`quantile(0.50)()\`, \`dateDiff()\`, \`uniq()\`.
 `;
 
 module.exports = { SKILL_CONTENT };

package/lib/cli.js

@@ -15,11 +15,7 @@ const { handleDoctor } = require('./commands/doctor');
 const { handleContext } = require('./commands/context');
 const { handleMcp } = require('./commands/mcp');
 
-let VERSION = '1.3.0';
-try {
-  const pkg = require('../package.json');
-  if (pkg.version) VERSION = pkg.version;
-} catch (e) {}
+const VERSION = '1.2.4';
 
 function parseArgs(argv) {
   const flags = {};
@@ -69,61 +65,61 @@ function parseArgs(argv) {
 }
 
 function printHelp() {
-  console.log(`Shiplens CLI - High-Speed User Telemetry & SDK Management Tool (v${VERSION})
+  console.log(`Shiplens CLI — 极速用户行为数据分析与 SDK 管理工具 (v${VERSION})
 
-Usage:
-  shiplens <command> [subcommand] [options]
-  npx.cmd --yes shiplens-cli <command> [subcommand] [options]   (Windows)
-  npx --yes shiplens-cli <command> [subcommand] [options]        (macOS/Linux)
+使用方法:
+  shiplens <命令> [子命令] [选项]
+  npx.cmd --yes shiplens-cli <命令> [子命令] [选项]   (Windows)
+  npx --yes shiplens-cli <命令> [子命令] [选项]        (macOS/Linux)
 
-Core Commands:
-  init          15-second zero-config analytics initialization & dashboard setup
-  auth          Authentication & credentials (status, set, secret, whoami, logout, bind, mcp-config, configure)
-  projects      Project management (list, bind, delete)
-  query         Multi-dimensional metrics and conversion funnel queries
-  sql           Execute secure read-only SQL queries on ClickHouse
-  summary       Retrieve product overview (traffic, bounce rates, geos, devices)
-  pages         Inspect page-level visits and average dwell times
-  paths         Analyze user flow journeys and Sankey transition paths
-  canvas        Retrieve global user behavior canvas topology
-  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)
-  mcp serve     Run local MCP proxy server with device credentials
+核心命令:
+  init          一键 15 秒极速初始化 Shiplens 埋点与数据看板 (内置 4 级分类自动打标与 Git 提交)
+  auth          鉴权凭证管理 (status, set, secret, whoami, logout, bind, mcp-config, configure)
+  projects      项目管理与绑定 (list, bind, delete)
+  query         向云端发起多维结构化指标与漏斗聚合分析 (支持 --metrics 多指标 / --file)
+  sql           在云端 ClickHouse 只读副本上执行安全 SQL (支持 --stdin 管道)
+  summary       获取产品整体流量、受众画像与关键指标摘要
+  pages         获取页面级访问与停留时长证据
+  paths         获取页面流转与跳转桑基流路径分析
+  canvas        获取全局用户行为画布拓扑数据
+  heatmap       获取页面点击热力图与骨架图快照
+  dashboards    AI 看板管理与一键创建 (list, create [--ai])
+  doctor        对当前项目的埋点、连通性与凭证进行全面体检
+  context       项目业务上下文管理 (push, pull, show)
+  mcp serve     运行本地 MCP 代理；它从 shiplens.env 读取设备凭证
 
-auth Subcommands:
-  auth status                          Check credential validity
-  auth set [--secret-stdin]            Save Access Secret
-  auth secret list                     List Access Secrets (masked)
-  auth secret create [--scopes ...]    Create scoped offline Access Secret
-  auth secret revoke --key-id <id>     Revoke offline Access Secret
-  auth whoami                          Display current authenticated user
-  auth logout                          Clear local credentials
-  auth bind --email <email> [--json]   Send Magic Link email for account binding
-  auth mcp-config [--client <client>]  Print MCP configuration (cursor/codex/claude/antigravity/manual)
-  auth configure --client <client>     Write MCP configuration into target client
-  auth configure --client manual       Output standard MCP JSON configuration
+auth 子命令:
+  auth status                          检查当前凭证是否有效
+  auth set [--secret-stdin]            设置 Access Secret
+  auth secret list                     列出离线 Access Secret（仅显示掩码）
+  auth secret create [--scopes ...]    创建受范围和失效时间约束的离线 Access Secret
+  auth secret revoke --key-id <id>     撤销离线 Access Secret
+  auth whoami                          查看当前登录用户信息
+  auth logout                          清除本地凭证
+  auth bind --email <邮箱> [--json]    ★ 一键邮箱绑定：发送 Magic Link 激活邮件
+  auth mcp-config [--client <client>]  输出 MCP 配置（client: cursor/codex/claude/antigravity/manual）
+  auth configure --client <client>     写入 Cursor、Codex Desktop、Claude Desktop 或 Antigravity 配置
+  auth configure --client manual       输出可手动粘贴的标准 MCP JSON 配置
 
-init Dedicated Options:
-  --name <string>        Project name (default: auto-read from package.json)
-  --description <string> Project functional description & positioning
-  --genre <id>           Level 1 category ID (e.g. utilities, finance, casual_games)
-  --subgenre <id>        Level 2 subcategory ID (e.g. developer_tools, financial_tools)
-  --tags <ids>           Level 4 feature tags (comma-separated tag_ids)
-  --industry <string>    Compatibility industry category field
-  --email <email|auto>   Auto or manual binding email
+init 专用选项 (支持自动推断，亦可显式覆盖):
+  --name <string>        项目名称 (默认自动读取 package.json)
+  --description <string> 项目功能描述与定位详情
+  --genre <id>           Level 1 大类 ID (如 utilities, finance, casual_games)
+  --subgenre <id>        Level 2 子类别 ID (如 developer_tools, financial_tools)
+  --tags <ids>           Level 4 特性标签列表 (逗号分隔 tag_id)
+  --industry <string>    兼容性行业类别字段
+  --email <email|auto>   自动或手动绑定激活邮箱
 
-Global Options:
-  --json             Output in standard JSON format (required for AI Agents)
-  --force            Force overwrite existing local configuration and project ID
-  --no-commit        Skip automatic Git commit after initialization
-  --app-id <id>      Explicitly specify target project app_id
-  --env <env>        Target environment (production / staging, default: production)
-  --secret <key>     Pass Access Secret explicitly
-  --api-url <url>    Custom backend API base URL (default: http://120.26.230.33)
-  -v, --version      Display CLI version
-  -h, --help         Display help information
+全局选项:
+  --json             以标准 JSON 格式输出结果 (AI Agent 必选)
+  --force            强制覆盖本地已存在的 Shiplens 统计配置与项目 ID
+  --no-commit        初始化完成后跳过自动 Git 提交
+  --app-id <id>      显式指定目标项目 app_id (默认自动读取 .shiplens.json)
+  --env <env>        目标环境 (production / staging，默认 production)
+  --secret <key>     显式传入 Access Secret 鉴权密钥
+  --api-url <url>    自定义后端 API 基址 (默认 http://120.26.230.33)
+  -v, --version      显示当前 CLI 版本号
+  -h, --help         显示帮助信息
 `);
 }
 
@@ -166,12 +162,12 @@ async function runCLI(argv = process.argv.slice(2)) {
         status: err.status,
       }, null, 2));
     } else {
-      console.error(`❌ Error [${code}]: ${err.message}`);
+      console.error(`❌ 错误 [${code}]: ${err.message}`);
     }
     process.exitCode = 1;
   };
 
-  // Resolve credentials and API client
+  // 解析凭证与 API 客户端
   const resolvedAuth = resolveSecret(flags.secret);
   let apiUrl = flags['api-url'] || process.env.SHIPLENS_API_URL;
   if (!apiUrl) {
@@ -186,7 +182,7 @@ async function runCLI(argv = process.argv.slice(2)) {
     if (flags['app-id']) return flags['app-id'];
     const localCfg = getLocalConfig();
     if (localCfg && localCfg.app_id) return localCfg.app_id;
-    const err = new Error('Target app_id not found. Provide --app-id or run inside an initialized project directory.');
+    const err = new Error('未找到目标 app_id，请传入 --app-id 或在已初始化的项目目录下执行');
     err.code = 'APP_NOT_FOUND';
     throw err;
   };
@@ -248,7 +244,7 @@ async function runCLI(argv = process.argv.slice(2)) {
         await handleMcp(subcommand || 'serve');
         break;
       default:
-        throw new Error(`Unknown command: ${command}. Use shiplens --help to view supported commands.`);
+        throw new Error(`未知命令: ${command}。使用 shiplens --help 查看支持的命令。`);
     }
   } catch (err) {
     outputError(err);