@shiplens/cli 1.4.2 → 1.4.4

package/lib/assets/skill.js

@@ -1,204 +1,201 @@
 const SKILL_CONTENT = `---
 name: shiplens-analytics
-description: Shiplens Web 数据分析 — Agent 行为协议、排障诊断与数据分析执行。
+description: Shiplens Web Analytics — Agent behavior protocol, diagnostics, and data analysis execution.
 ---
 
-# Shiplens Web 数据分析 Skill 指引
+# Shiplens Web Analytics Skill (v3.1)
 
-Shiplens 通过 CLI 与 MCP 提供 Web 用户行为数据分析。本文档定义 AI Agent 如何为使用 Shiplens 的项目进行排障自检、项目接入与数据分析。
+Shiplens provides web user behavior analytics via CLI and MCP. This document defines how an AI Agent should diagnose, onboard, and analyze data for any project using Shiplens.
 
 ---
 
-## 1. 环境排障自检
+## 1. Environment Diagnostics
 
-执行任何分析命令前，检查三项线索以判定项目状态：
+Before executing any command, check three signals to determine project state:
 
-| 线索 | 检查项 |
-|------|--------|
-| **鉴权** | 本地是否存在 \`shiplens.env\` 或环境变量 \`SHIPLENS_ACCESS_SECRET\`？ |
-| **SDK** | \`package.json\` 是否包含 \`@shiplens/sdk\` 且源码已插桩？ |
-| **云端** | 云端接口（\`GET /api/projects\`）是否能查询到对应项目？ |
+| Signal | What to check |
+|--------|---------------|
+| **Auth** | Does \`shiplens.env\` or env var \`SHIPLENS_ACCESS_SECRET\` exist? |
+| **SDK** | Is \`@shiplens/sdk\` in \`package.json\` and instrumented in source? |
+| **Cloud** | Does \`.shiplens.json\` contain a valid \`app_id\`? |
 
-### 四状态矩阵
+### State Matrix
 
-| 状态 | 判定条件 | 应对行为 |
-|------|----------|----------|
-| **状态 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） |
+| State | Condition | Action |
+|-------|-----------|--------|
+| **A — Ready** | All three ✓ | Proceed to data analysis (§3) |
+| **A-1 — No project** | Auth ✓, no \`app_id\` | User authenticated, but cloud account has no projects or project is not linked. Guide user to \`shiplens.dev\` to verify account or create a project |
+| **B — No auth / New device** | SDK ✓, Auth ✗ | Missing local \`shiplens.env\`. Ask: *"Have you registered a Shiplens account?"*<br>• **Registered**: Guide user to visit \`https://shiplens.dev/settings/api-keys\`, download the \`shiplens.env\` file and place it in the project root (advanced users can copy the API key and run \`shiplens auth set --secret <key>\`).<br>• **Not registered**: Ask for email and run \`shiplens auth bind --email <email> --json\`. |
+| **C — Cold start** | SDK ✗, Auth ✗ | Run \`shiplens init\` (§2) |
 
-该矩阵同时作为排障基准线。系统出现任何异常时，按此三项线索回溯排查。
+This matrix doubles as the troubleshooting baseline. When anything breaks, trace back through these three signals.
 
 ---
 
-## 2. 项目极速接入
+## 2. Project Onboarding
 
-### 执行接入
+### Run
 \`\`\`bash
-npx.cmd --yes @shiplens/cli init --json          # Windows
+npx.cmd --yes @shiplens/cli init --json          # Windows PowerShell
 npx --yes @shiplens/cli init --json               # macOS / Linux
 \`\`\`
-备用镜像：追加 \`--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
-\`\`\`
-
-- **凭据下发机制**：执行 \`auth bind\` 时，服务端会随响应下发设备专属凭据，CLI 自动将其安全写入项目根目录的 \`shiplens.env\`（权限 0600）；
-- **激活即生效**：用户在邮箱中点击 Magic Link 完成注册激活后，**云端立即激活该设备凭据**；
-- **零后续摩擦**：本地 Agent **无需执行额外的登录命令或索要 Token**，已写入的 \`shiplens.env\` 即刻生效，后续的数据查询（\`shiplens query\`）与 MCP 服务（\`shiplens mcp serve\`）直接可用。
-
-### 汇报模板
-初始化完成后，输出标准卡片：
+Backup mirror fallback: add \`--registry=https://registry.npmmirror.com\`
+
+### What init does (~15 seconds, one atomic command)
+1. Detect framework (Next.js / Vite / Vue / HTML)
+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\`
+6. Write local state machine \`.shiplens.json\`
+7. Inject this AI Skill file and Agent rules
+
+### Overwrite Protection & Comparison
+If \`.shiplens.json\` or SDK instrumentation already exists, **stop and present the clear comparison**:
+- **Option 1 [Recommended]**: Keep existing statistics. Retain existing project ID and historical data, new traffic continues accumulating on current dashboard.
+- **Option 2 [Overwrite]**: Overwrite with \`--force\`. Request a brand new blank project ID from cloud and overwrite local code (**Note**: Old dashboard will stop receiving new data, old and new data cannot be merged).
+
+### Post-Init: Request Email & Seamless Activation
+When \`shiplens auth bind --email <email> --json\` is called:
+1. Server generates device credentials and writes them directly to local \`shiplens.env\` (0600 permissions, auto-gitignored).
+2. Server sends a Magic Link email to the user.
+3. Once the user clicks the email link, the cloud account and device credentials become active immediately.
+4. **Zero extra steps for Agent**: Future queries and \`shiplens mcp serve\` will authenticate automatically without manual login.
+
+### Reporting Template
+After init, present:
 
 \`\`\`markdown
-### 📊 项目与数据看板信息
-- **项目名称**：\\\`<project_name>\\\`
-- **应用 ID (App ID)**：\\\`<app_id>\\\`
-- **代码注入**：已在 [\\\`<injected_file>\\\`](file:///<path>) 中完成配置
-- **实时看板**：[\\\`<dashboard_url>\\\`](<dashboard_url>)
-- **用户个人账号**：<用户个人账号状态>
-
-> [!IMPORTANT]
-> **项目待激活（数据统计尚未生效）**
-> **请告诉我您的邮箱**：点击邮件中的链接即可完成注册，激活每月 50,000 事件的免费额度（约5000人访问），同时绑定项目和账号；激活后您与我直接对话，我就有权限查询并分析产品数据。
+### 📊 Project & Analytics Information
+- **Project Name**: \\\`<project_name>\\\`
+- **App ID**: \\\`<app_id>\\\`
+- **Code Injection**: [\\\`<injected_file>\\\`](file:///<path>)
+- **Live Dashboard**: [<dashboard_url>](<dashboard_url>)
+- **Account Status**: <status>
+- **AI Skill**: [\\\`.agents/skills/shiplens/SKILL.md\\\`](file:///<path>)
+
+> **Activate your project**: Share your email to activate monthly free event quota and link your project with your account.
 \`\`\`
 
-账号状态枚举：
-- \`已登录 (项目已与账号关联)\` — 本地存在有效凭据且云端项目已归属于当前账号
-- \`已登录 (项目和账号未关联)\` — 本地存在有效凭据但云端项目尚未归属于当前账号
-- \`未登录 (首次安装默认状态或本地不存在有效凭据)\` — 初次安装 CLI 或无有效凭据时的默认状态
+Account status values:
+- \`Logged in (project linked)\` — credentials exist, project bound
+- \`Logged in (project not linked)\` — credentials exist, project unbound
+- \`Not logged in (Default state after first installation or no valid local credentials)\`
 
 ---
 
-## 3. 数据分析协议 (6 步执行流)
-
-当用户提出任何独立的数据分析需求时：
+## 3. Data Analysis Protocol (6 Steps)
 
-**第 1 步 — 检查动态覆盖 (因地制宜)**：检查根目录是否存在 \`.shiplens/learnings.md\`。若存在，先读取【全局通用偏好】，再匹配当前分析场景对应的【场景细分偏好】（如留存分析偏好 14d、转化漏斗偏好 30d，严禁一刀切全局覆盖）。
+When processing any analytics or telemetry request:
 
-**第 2 步 — 锚定业务上下文**：读取 \`.shiplens/contexts/<app_id>.md\`（或执行 \`shiplens context show --json\`）。用具体页面名称和按钮文案解释数据，严禁仅输出生硬 ID。
+**Step 1 — Read Learnings**: Check \`.shiplens/learnings.md\` for project overrides (date range, metrics, cohort intervals).
 
-**第 3 步 — 定位分析场景**：打开 \`prompts/prompts_cli_zh.md\`，阅读顶部的**42 大场景全景提纲与索引导航**，找到契合场景，提取对应章节的确定性执行步骤与 SQL/CLI 语法。
+**Step 2 — Read Context**: Read \`.shiplens/contexts/<app_id>.md\` (or run \`shiplens context show --json\`) to ground numbers in real page routes and button labels.
 
-**第 4 步 — 执行命令**：执行预设的 CLI 命令，并带上第 1 步获取的场景细分覆盖参数。
+**Step 3 — Route Execution Path (Tri-Route Decision)**:
+- **Route A (Exact Action ID)**: If input contains an \`action_id\` (e.g. \`lifecycle_stage\` or \`Action: <id>\`), run \`shiplens action <id> --json\` to retrieve prescribed steps and commands.
+- **Route B (Scenario Preset Match)**: If input is natural language matching one of the 42 textbook growth/retention scenarios, run \`shiplens action <id> --json\` for that scenario.
+- **Route C (Ad-Hoc Autonomous Composition)**: If input is a custom, open-ended question without a preset action, autonomously select and compose CLI commands from the Atomic Toolset (§4) to query required metrics.
 
-**第 5 步 — 输出深度洞察**：将数据转化为具体的业务结论与优化建议，结合第 2 步的业务上下文进行解读。
+**Step 4 — Execute**: Run selected CLI commands with Step 1 overrides applied. Always include \`--json\`.
 
-**第 6 步 — 场景化自适应学习**：若用户对分析过程进行了纠偏（如针对留存提出“改用双周周期评估”），智能识别纠偏适用的场景范围，主动询问：*“是否需要我将「留存分析默认采用双周 14d 周期」记录到当前项目的 \`.shiplens/learnings.md\` 对应场景中？”* 确认后写入文件（§6）。
+**Step 5 — Synthesize**: Translate numbers into concrete business conclusions, metric benchmarks, and actionable next steps using UI terminology from Step 2.
 
-### 优先级规则
-- **优先级 1**：\`.shiplens/learnings.md\` — 项目专属用户动态偏好（场景细分覆盖 > 全局通用偏好）
-- **优先级 2**：\`prompts/prompts_cli_zh.md\` — 42 个教科书经典分析场景底座
+**Step 6 — Record**: If user clarifies or corrects preferences (e.g., "always use 14d for cohort retention"), ask to persist to \`.shiplens/learnings.md\` (§6).
 
 ---
 
-## 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） |
+## 4. Atomic CLI Toolset & Composition Matrix
+
+| Command | Capability | Typical Scenarios & Composition |
+|---------|------------|---------------------------------|
+| \`shiplens summary --range 7d --json\` | Macro Overview | Total UV, PV, bounce rates, top geos, device distribution |
+| \`shiplens query --metric <m> --range 7d --json\` | Multidimensional Metrics | Retention matrix (\`daily_retention\`), funnels (\`conversion_funnel\`), pageview trends |
+| \`shiplens pages --range 7d --json\` | Page Performance | Route visit counts, average dwell time, high-traffic pages |
+| \`shiplens paths --range 7d --json\` | User Journeys | Entry-to-exit flow, drop-off routes, navigation transitions |
+| \`shiplens heatmap --template <id> --json\` | UI & Click Patterns | Button click distributions, wireframe skeleton click rates |
+| \`shiplens sql --query "<sql>" --json\` | Custom Slicing | Multi-filter joins, power user segmentation, ad-hoc event queries |
+| \`shiplens dashboards create --title "..." --prompt "..." --json\` | Dashboard Creation | AI-generated 12-column live dashboards |
+| \`shiplens action [id] [--list] --json\` | Action Presets | 42 textbook scenario steps, commands, and theory |
+| \`shiplens doctor --json\` | Diagnostics | Diagnose config, SDK, network, credentials |
+| \`shiplens context show --json\` | Business Context | Inspect mapped page routes and UI button semantics |
+| \`shiplens auth bind --email <email> --json\` | Activation | Send Magic Link email for project binding |
+| \`shiplens mcp serve\` | MCP Server | Start local stdio MCP proxy for IDE/Agent |
+| \`shiplens projects delete --app-id <id> --json\` | Deletion | Delete project (**requires confirmation**, §5) |
 
 ---
 
-## 5. 安全红线与风控
+## 5. Safety Rules
 
-### 删除项目 — 强制二次确认 (HITL)
-删除任何项目前，必须执行：
-1. 向用户展示项目名称、\`app_id\` 及创建时间；
-2. 明确警告：*“此操作将彻底清空该项目的所有监控数据、看板与配置，且不可逆。”*；
-3. **暂停操作，等待用户显式回复“确认删除”**；
-4. 收到确认后方可执行 \`shiplens projects delete\`。
+### Project Deletion — Stop and Confirm (HITL)
+Before deleting any project:
+1. Show project name, \`app_id\`, and creation date.
+2. Warn: *"This permanently deletes all data, dashboards, and config. Cannot be undone."*
+3. Explicitly pause and wait for user to reply "confirm delete".
+4. Only then execute \`shiplens projects delete\`.
 
-严禁跳过确认静默删除。
+Never skip this step.
 
-### SQL 安全规则
-- 必须携带时间范围：\`WHERE timestamp >= now() - INTERVAL <N> DAY\`
-- 必须带 \`LIMIT\`（最大 1000 行）
-- 查询目标表：\`events\`（ClickHouse 只读沙箱）
+### SQL
+- Always \`WHERE timestamp >= now() - INTERVAL <N> DAY\`
+- Always \`LIMIT\` (max 1000)
+- Table: \`events\` (read-only ClickHouse)
 
-### Windows 终端规范
-- npm/npx 命令带 \`.cmd\` 后缀：\`npx.cmd --yes\`、\`npm.cmd\`
-- 多命令连接使用分号 \`;\`，禁止使用 \`&&\`
+### Windows Execution Policy
+- Use \`.cmd\` suffix: \`npx.cmd\`, \`npm.cmd\`
+- Chain commands with \`;\` not \`&&\`
 
 ---
 
-## 6. 自适应学习规范 (\`.shiplens/learnings.md\`)
+## 6. Adaptive Learning (\`.shiplens/learnings.md\`)
 
-存放项目专属的用户偏好覆盖规则。在用户首次确认保存前**不默认创建**。
+Stores user preferences that override defaults. Understand the specific scenario scope (e.g. retention vs. funnel vs. channels) instead of applying narrow rules globally.
 
-### 标准文件格式（因地制宜）
+### Format
 \`\`\`markdown
-# Shiplens AI 分析学习与项目偏好配置
+# Shiplens Project Learnings
+
+## Global Overrides
+- default_range: 30d
+- exclude_filter: user_id NOT IN ('test_1', 'test_2')
 
-## 全局通用偏好 (Global Preferences)
-- exclude_user_ids: ["test_user_01", "internal_qa"]
-- default_time_grain: day
+## Scenario-Specific Overrides
+### Retention Analysis
+- cohort_interval: 14d
+- retention_benchmark: day_1_day_7_day_30
 
-## 场景细分偏好 (Scenario-Specific Overrides)
-### 场景: [用户留存与流失分析] (retention_curve / retention_matrix)
-- default_range: 14d # 用户偏好以双周周期评估留存衰减
-- focus_metrics: ["第 14 天留存率", "次周回访率"]
+### Conversion Funnel
+- primary_conversion_goal: /signup → /onboarding → /dashboard
 
-### 场景: [转化漏斗与流失诊断] (funnel_dropoff)
-- default_range: 30d # 漏斗分析采用月度窗口
-- primary_conversion_goal: /checkout/success
+### Custom Analysis Habits
+- Always show week-over-week comparison
+- Report bounce rate per page, not aggregate
 \`\`\`
 
-### 维护规则
-- **严禁**在 \`init\` 时自动创建空文件
-- 仅在用户纠偏并明确确认后创建或追加
-- 每次写入前明确向用户确认适用场景范围
+### Rules
+- Do **not** create during \`init\`
+- Create on first user-confirmed preference save
+- Scope preferences accurately to avoid inappropriate global overrides
+- Always ask before writing
 
 ---
 
-## 7. 数据表结构与 SQL 参考
+## 7. SQL Reference
 
-**数据表**：\`events\`（ClickHouse 只读实例）
+**Table**: \`events\` (ClickHouse, read-only)
 
-| 字段名 | 类型 | 说明 |
-|--------|------|------|
-| \`timestamp\` | DateTime | 事件发生时间 |
+| Column | Type | Description |
+|--------|------|-------------|
+| \`timestamp\` | DateTime | Event time |
 | \`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()\`.
+| \`user_id\` | String | User ID |
+| \`session_id\` | String | Session ID |
+| \`template_id\` | String | DOM hash (page template) |
+| \`page_path\` | String | URL path |
+| \`referrer\` | String | Referrer URL |
+| \`properties\` | Map(String, String) | Custom event data |
+
+ClickHouse functions: \`countIf()\`, \`quantile(0.50)()\`, \`dateDiff()\`, \`uniq()\`.
 `;
 
 module.exports = { SKILL_CONTENT };

package/lib/cli.js

@@ -14,8 +14,13 @@ const { handleDashboards } = require('./commands/dashboards');
 const { handleDoctor } = require('./commands/doctor');
 const { handleContext } = require('./commands/context');
 const { handleMcp } = require('./commands/mcp');
+const { handleAction } = require('./commands/action');
 
-const VERSION = require('../package.json').version;
+let VERSION = '1.4.4';
+try {
+  const pkg = require('../package.json');
+  if (pkg.version) VERSION = pkg.version;
+} catch (e) {}
 
 function parseArgs(argv) {
   const flags = {};
@@ -65,61 +70,62 @@ function parseArgs(argv) {
 }
 
 function printHelp() {
-  console.log(`Shiplens CLI — 极速用户行为数据分析与 SDK 管理工具 (v${VERSION})
+  console.log(`Shiplens CLI - High-Speed User Telemetry & SDK Management Tool (v${VERSION})
 
-使用方法:
-  shiplens <命令> [子命令] [选项]
-  npx.cmd --yes shiplens-cli <命令> [子命令] [选项]   (Windows)
-  npx --yes shiplens-cli <命令> [子命令] [选项]        (macOS/Linux)
+Usage:
+  shiplens <command> [subcommand] [options]
+  npx.cmd --yes shiplens-cli <command> [subcommand] [options]   (Windows)
+  npx --yes shiplens-cli <command> [subcommand] [options]        (macOS/Linux)
 
-核心命令:
-  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 读取设备凭证
+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)
+  action        Retrieve deterministic steps, commands, and theory for analysis actions (list, <action_id>)
+  mcp serve     Run local MCP proxy server with device credentials
 
-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 配置
+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
 
-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>   自动或手动绑定激活邮箱
+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
 
-全局选项:
-  --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         显示帮助信息
+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
 `);
 }
 
@@ -162,12 +168,12 @@ async function runCLI(argv = process.argv.slice(2)) {
         status: err.status,
       }, null, 2));
     } else {
-      console.error(`❌ 错误 [${code}]: ${err.message}`);
+      console.error(`❌ Error [${code}]: ${err.message}`);
     }
     process.exitCode = 1;
   };
 
-  // 解析凭证与 API 客户端
+  // Resolve credentials and API client
   const resolvedAuth = resolveSecret(flags.secret);
   let apiUrl = flags['api-url'] || process.env.SHIPLENS_API_URL;
   if (!apiUrl) {
@@ -182,7 +188,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('未找到目标 app_id，请传入 --app-id 或在已初始化的项目目录下执行');
+    const err = new Error('Target app_id not found. Provide --app-id or run inside an initialized project directory.');
     err.code = 'APP_NOT_FOUND';
     throw err;
   };
@@ -240,11 +246,14 @@ async function runCLI(argv = process.argv.slice(2)) {
       case 'context':
         await handleContext(subcommand || 'show', args.slice(2), flags, ctx);
         break;
+      case 'action':
+        await handleAction(cmdArgs, flags, ctx);
+        break;
       case 'mcp':
         await handleMcp(subcommand || 'serve');
         break;
       default:
-        throw new Error(`未知命令: ${command}。使用 shiplens --help 查看支持的命令。`);
+        throw new Error(`Unknown command: ${command}. Use shiplens --help to view supported commands.`);
     }
   } catch (err) {
     outputError(err);

package/lib/commands/action.js

@@ -0,0 +1,112 @@
+const path = require('path');
+const fs = require('fs');
+
+let actionsCache = null;
+
+function loadActions() {
+  if (actionsCache) return actionsCache;
+  const filePath = path.join(__dirname, '..', 'assets', 'actions.json');
+  try {
+    if (fs.existsSync(filePath)) {
+      const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      actionsCache = data.actions || [];
+    } else {
+      actionsCache = [];
+    }
+  } catch (e) {
+    actionsCache = [];
+  }
+  return actionsCache;
+}
+
+function findSimilarActions(id, allActions) {
+  const normalized = (id || '').toLowerCase().replace(/[-_\s]+/g, '');
+  return allActions
+    .filter((a) => {
+      const aNorm = a.id.toLowerCase().replace(/[-_\s]+/g, '');
+      return aNorm.includes(normalized) || normalized.includes(aNorm) || a.title.toLowerCase().includes(id.toLowerCase());
+    })
+    .slice(0, 3)
+    .map((a) => a.id);
+}
+
+async function handleAction(cmdArgs, flags, ctx) {
+  const actions = loadActions();
+  const rawId = flags.id || (cmdArgs[0] && cmdArgs[0] !== 'list' ? cmdArgs[0] : null);
+  const isList = flags.list || cmdArgs[0] === 'list' || !rawId;
+
+  if (isList) {
+    const listData = {
+      ok: true,
+      total: actions.length,
+      actions: actions.map((a) => ({
+        id: a.id,
+        title: a.title,
+        category: a.category,
+        commands: a.commands,
+      })),
+    };
+
+    ctx.output(listData, () => {
+      console.log(`\n📋 Shiplens Action Preset Library (${actions.length} Scenarios)\n`);
+      const grouped = {};
+      for (const a of actions) {
+        if (!grouped[a.category]) grouped[a.category] = [];
+        grouped[a.category].push(a);
+      }
+      for (const [cat, items] of Object.entries(grouped)) {
+        console.log(`  📂 ${cat}:`);
+        for (const item of items) {
+          console.log(`    • ${item.id.padEnd(28)} - ${item.title}`);
+        }
+        console.log('');
+      }
+      console.log('💡 Usage: shiplens action <action_id> [--json]');
+    });
+    return;
+  }
+
+  const targetId = rawId.toLowerCase().trim();
+  const matched = actions.find((a) => a.id.toLowerCase() === targetId);
+
+  if (!matched) {
+    const suggestions = findSimilarActions(targetId, actions);
+    const err = new Error(`Action preset '${rawId}' not found.` + (suggestions.length > 0 ? ` Did you mean: ${suggestions.join(', ')}?` : ''));
+    err.code = 'ACTION_NOT_FOUND';
+    err.suggestions = suggestions;
+    throw err;
+  }
+
+  const result = {
+    ok: true,
+    action: matched,
+  };
+
+  ctx.output(result, () => {
+    console.log(`\n🎯 [${matched.id}] ${matched.title}`);
+    console.log(`📂 Category: ${matched.category}`);
+    if (matched.suffix) console.log(`🏷️ Suffix: ${matched.suffix}`);
+    console.log(`\n📝 Execution Steps:`);
+    for (const s of matched.steps) {
+      console.log(`  ${s}`);
+    }
+    if (matched.commands && matched.commands.length > 0) {
+      console.log(`\n⚡ Prescribed CLI Commands:`);
+      for (const c of matched.commands) {
+        console.log(`  $ ${c}`);
+      }
+    }
+    if (matched.foundation) {
+      console.log(`\n📚 Analysis Foundation:\n  ${matched.foundation}`);
+    }
+    if (matched.source) {
+      console.log(`\n📖 Source:\n  ${matched.source}`);
+    }
+    console.log('');
+  });
+}
+
+module.exports = {
+  handleAction,
+  loadActions,
+};