@shiplens/cli 1.3.1 → 1.4.0

package/README.md

@@ -1,95 +1,71 @@
-# 🚀 Shiplens CLI (In Development)
+# 🚀 Shiplens CLI
 
-> **Fast User Telemetry, Instant SDK Instrumentation & AI Analytics Engine for Modern Web Apps.**
+> **Shiplens 官方命令行工具 — 面向 Web 前端的用户行为数据统计与 AI Agent 智能分析引擎。**
 
 [![npm version](https://img.shields.io/npm/v/@shiplens/cli.svg)](https://www.npmjs.com/package/@shiplens/cli)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Node Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg)](package.json)
-[![Status](https://img.shields.io/badge/status-active%20development-orange.svg)]()
 
 ---
 
-> [!NOTE]
-> **Active Development Preview**: This package is currently in active development. Features and API endpoints are being iterated rapidly. 50,000 monthly telemetry events are included for free upon registration.
+Shiplens CLI 是 [shiplens.dev](https://shiplens.dev) 官方配套的命令行工具。它为前端项目提供自动化的数据统计接入，并与各类 AI Agent（Cursor、Windsurf、Codex、Claude 等）无缝协同，实现对话式数据查询与自动化分析。
 
 ---
 
-## ⚡ Instant Setup (Under 15 Seconds)
+## 🌟 核心功能
 
-Run in the root of any Next.js, Vite, Vue, or HTML project:
+- **自动化接入与代码插桩**：自动识别前端项目框架（Next.js、Vite、Vue、HTML 等），无感注入 `@shiplens/sdk` 数据采集代码；
+- **用户行为数据统计**：秒级查看全站流量大盘、访问路径、页面留存与点击热力图；
+- **AI Agent 智能分析**：支持通过 CLI 与本地 stdio MCP 代理（`shiplens mcp serve`）与 AI 对话，让 Agent 直接读取产品数据并输出教科书级业务洞察；
+- **AI 实时看板生成**：一句话自然语言诉求，云端自动拼装 12 列响应式数据看板；
+- **业务上下文与动态自适应**：自动提取页面功能文案辅助 AI 理解业务，并支持按项目自适应记忆个性化分析偏好。
 
-```bash
-# Zero-install execution via npx
-npx --yes @shiplens/cli init --json
-
-# Windows PowerShell (Avoid execution policy blocking)
-npx.cmd --yes @shiplens/cli init --json
-
-# In China or restricted networks (Alibaba Cloud / npmmirror fallback)
-npx --yes --registry=https://registry.npmmirror.com @shiplens/cli init --json
-```
+---
 
-### What `init` Does Automatically:
-1. **Detects Framework**: Automatically recognizes Next.js (App / Pages router), Vite (React / Svelte), Vue 3, or plain HTML.
-2. **Injects Tracking SDK**: Inserts `@shiplens/sdk` tracking snippets into your entry files without breaking your code layout.
-3. **Connects Cloud Project**: Registers the project, generates a live responsive dashboard URL, and writes local configuration (`.shiplens.json`).
-4. **Installs Dependency**: Adds `@shiplens/sdk` via your project package manager (`npm`, `pnpm`, `yarn`, or `bun`) with 4-tier download fallback (NPM -> Alibaba npmmirror -> GitHub -> CDN, 5s timeout & 2 retries per tier).
-5. **Deploys AI Skills**: Injects `.agents/skills/shiplens/SKILL.md` and Cursor rules (`.cursor/rules/shiplens.mdc`) for seamless LLM Agent integration.
-6. **Performs Git Commit**: Automatically commits all instrumentation changes atomically.
+## ⚡ 快速开始
 
----
+在任何前端项目根目录下执行初始化命令：
 
-## 🧠 Dynamic Overrides & Adaptive Learning
+```bash
+# 通用终端
+npx --yes @shiplens/cli init
 
-Shiplens introduces an adaptive learning loop for AI Agents:
+# Windows PowerShell
+npx.cmd --yes @shiplens/cli init
 
-```text
-[User Prompt] ➔ [Match Preset] ➔ [Apply .shiplens/learnings.md (Priority 1)] ➔ [Execute CLI] ➔ [Update Learnings]
+# 备用镜像源
+npx --yes --registry=https://registry.npmmirror.com @shiplens/cli init
 ```
 
-- **Priority 1 (Dynamic Overrides)**: Local `.shiplens/learnings.md` rules always override default CLI parameters (e.g. customized date ranges, funnel goals, or granular filters).
-- **Priority 2 (Deterministic Base)**: Standard 42 scenario-based CLI execution presets in `prompts/cli/prompt_cli_en.md`.
-
 ---
 
-## 📊 Core Commands
+## 📊 常用命令速查
 
-| Command | Description |
+| 命令 | 说明 |
 | :--- | :--- |
-| `npx @shiplens/cli init --json` | 15-second zero-config analytics onboarding |
-| `npx @shiplens/cli doctor --json` | End-to-end diagnostics on SDK, network, and credentials |
-| `npx @shiplens/cli summary --range 7d --json` | Traffic overview: PV, UV, bounce rates, geos, devices |
-| `npx @shiplens/cli query --metric pageviews --json` | Multi-dimensional metrics & funnel queries |
-| `npx @shiplens/cli sql --query "<sql>" --json` | Sandboxed read-only ClickHouse SQL execution |
-| `npx @shiplens/cli pages --range 7d --json` | Page-level visits and average dwell times |
-| `npx @shiplens/cli paths --range 7d --json` | User journeys and Sankey transition paths |
-| `npx @shiplens/cli heatmap --template <id> --json` | Click heatmaps & skeleton wireframe snapshots |
-| `npx @shiplens/cli dashboards create --prompt "..." --json` | AI-driven dashboard generation |
-| `npx @shiplens/cli auth bind --email <email> --json` | Request Magic Link for quota activation & authorization |
-| `npx @shiplens/cli auth configure --client cursor --json` | Auto-configure MCP servers in IDEs |
-
----
-
-## 🔒 Security & Sandboxing
-
-- **Tenant Isolation**: Strict per-project `app_id` isolation across all telemetry queries.
-- **Read-Only ClickHouse Sandbox**: AST query validator enforces `SELECT`-only operations, mandatory time bounds, and maximum 1000-row limits.
-- **Safe Secrets Handling**: Credential tokens and secrets are automatically masked in all console outputs (`sk_live_...9f2a`).
+| `shiplens init` | 为当前项目接入数据统计并下发 AI Skill 规范 |
+| `shiplens summary` | 查看产品流量大盘概览（PV、UV、时长、受众分布） |
+| `shiplens query` | 多维指标聚合与用户转化漏斗查询 |
+| `shiplens sql` | 执行自定义安全只读数据分析查询 |
+| `shiplens pages` | 页面级访问量与停留时长统计 |
+| `shiplens heatmap` | 查看页面点击热力分布与骨架图 |
+| `shiplens dashboards create` | 通过自然语言生成官方数据看板 |
+| `shiplens doctor` | 检查本地配置、代码插桩与网络通道健康度 |
+| `shiplens context show` | 查看当前项目的业务上下文与页面功能文案 |
+| `shiplens auth bind` | 绑定邮箱并激活设备数据分析授权 |
+| `shiplens mcp serve` | 启动本地 stdio MCP 代理服务供 AI Agent 调度 |
 
 ---
 
-## 📁 Documentation & Prompts
+## 🔗 相关资源
 
-- [CLI Architecture & Roadmap](./docs/01_CLI_ARCHITECTURE_AND_ROADMAP.md)
-- [Complete Command Reference](./docs/02_CLI_COMMAND_REFERENCE.md)
-- [AI Skill & Dynamic Overrides Spec](./docs/03_SKILL_SPEC_AND_PROMPTS.md)
-- [CLI Execution Prompts (42 Scenarios)](./prompts/cli/prompt_cli_en.md)
-- [Web Showcase Prompts (42 Scenarios)](./prompts/web/prompt_web_en.md)
-- [Backend API Specification](./docs/BACKEND_API_SPEC.md)
-- [Project Context Specification](./docs/SHIPLENS_CONTEXT_API_SPEC.md)
+- 官方网站：[https://shiplens.dev](https://shiplens.dev)
+- 常见问题与支持：[https://shiplens.dev/faq](https://shiplens.dev/faq)
+- 全命令参考手册：[`docs/02_SHIPLENS_CLI_全命令参考手册.md`](./docs/02_SHIPLENS_CLI_全命令参考手册.md)
 
 ---
 
-## 📜 License
+## 📜 开源协议
 
 Apache-2.0 © Shiplens Team
+

package/docs/02_SHIPLENS_CLI_/345/205/250/345/221/275/344/273/244/345/217/202/350/200/203/346/211/213/345/206/214.md

@@ -0,0 +1,205 @@
+# Shiplens CLI 全命令参考手册 (Reference Manual)
+
+> 本文档定义了 Shiplens CLI 所有命令的输入参数、选项、使用语法与输出说明。供 AI Agent 调用。
+
+---
+
+## 全局选项 (Global Flags)
+
+所有子命令均继承以下全局选项：
+
+| 选项 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `--json` | bool | 强制以标准 JSON 格式输出结果（AI Agent 必选） |
+| `--app-id <string>` | string | 显式指定目标项目 `app_id`（默认自动读取 `./.shiplens.json`） |
+| `--env <string>` | string | 目标环境：`production`（默认）或 `staging` |
+| `--secret <string>` | string | 显式传入 Access Secret 鉴权密钥（覆盖本地配置） |
+| `--api-url <string>` | string | 自定义后端 API 基址（默认为 `http://120.26.230.33`） |
+| `-v, --version` | flag | 输出当前 CLI 版本号 |
+| `-h, --help` | flag | 打印当前命令的帮助说明 |
+
+> **Windows 终端免拦截**：在 Windows 下调用时必须使用 `npx.cmd --yes shiplens-cli <命令>`，严禁裸敲 `npx`，避免 PowerShell 脚本策略拦截。
+
+---
+
+## 1. 项目接入与初始化 (`init`)
+
+```bash
+shiplens init [options]
+```
+
+### 选项说明：
+- `--name <string>`：项目名称（默认从 `package.json` 自动提取）
+- `--description <string>`：项目功能简介与定位描述
+- `--industry <string>`：行业分类标识
+- `--genre <id>`：Level 1 大类 ID（如 `utilities`, `finance_fintech`）
+- `--subgenre <id>`：Level 2 子类别 ID（如 `developer_tools`）
+- `--tags <tag1,tag2>`：Level 4 特性标签 ID 列表（逗号分隔，最多 10 个）
+- `--email <email>`：绑定邮箱（传 `auto` 时自动读取 `git config user.email`）
+- `--framework <type>`：强制指定框架类型（`nextjs-app`, `nextjs-pages`, `vite`, `vue`, `html`）
+- `--force`：强制覆盖本地已存在的 Shiplens 配置与项目编号
+- `--no-install`：跳过包管理器 `install` 依赖安装步骤
+
+---
+
+## 2. 身份与凭证管理 (`auth`)
+
+### 子命令列表：
+- `shiplens auth status`：检查当前鉴权凭证的有效性
+- `shiplens auth set [secret]`：将 Access Secret 写入本地 `~/.shiplens/config.json`
+- `shiplens auth whoami`：查询当前登录账户详情与绑定的项目信息
+- `shiplens auth logout`：清除本地存储的所有凭证
+- `shiplens auth bind --email <email>`：请求 Magic Link 激活邮件绑定
+- `shiplens auth mcp-config --client <client>`：输出指定 Agent 客户端的 stdio MCP 配置
+- `shiplens auth configure --client <client>`：自动将 MCP 配置写入目标客户端（`cursor`, `codex`, `claude`, `antigravity`, `manual`）
+- `shiplens auth secret list/create/revoke`：管理离线自动化 Access Secret 密钥
+
+---
+
+## 3. 项目管理与绑定 (`projects`)
+
+### 子命令列表：
+- `shiplens projects list`：列出当前账户名下的所有项目
+- `shiplens projects bind`：将当前本地目录的项目与云端账户绑定
+- `shiplens projects delete [--force]`：删除项目及其全部历史数据
+
+---
+
+## 4. 多维结构化指标分析 (`query`)
+
+```bash
+shiplens query [options]
+```
+
+### 选项说明：
+- `--metric <name>` / `--metrics <m1,m2>`：查询指标名称（如 `pageviews`, `daily_retention`, `bounce_rate`, `conversion_funnel`）
+- `--range <range>`：时间窗口（`24h`, `7d`, `14d`, `30d`, `90d`）
+- `--grain <grain>`：聚合时间粒度（`hour`, `day`, `week`, `month`）
+- `--group-by <dim>`：分组维度（`path`, `template_id`, `country`, `browser`, `device_type` 等）
+- `--filter <key=value>`：多维过滤条件
+- `--limit <num>`：返回数据行数限制（默认: 30）
+- `--file <path>`：从 JSON 文件载入完整的 `AnalyticsQueryRequest` 查询结构
+
+---
+
+## 5. 只读安全 SQL 沙箱 (`sql`)
+
+```bash
+shiplens sql --query "<sql>" [options]
+```
+
+### 选项说明：
+- `--query "<sql>"` / `--sql "<sql>"`：只读 SQL 查询语句
+- `--stdin`：从标准输入流读取 SQL 语句（管道输入专用）
+
+---
+
+## 6. 产品大盘概览 (`summary`)
+
+```bash
+shiplens summary [--range <range>]
+```
+
+返回指定周期内的 PV、UV、会话数、平均停留时长、跳出率及受众地域分布。
+
+---
+
+## 7. 页面分析与行为路径 (`pages` / `paths` / `canvas`)
+
+- `shiplens pages [--range 7d]`：获取页面维度的 PV、UV、平均停留时长与跳出率列表
+- `shiplens paths [--range 7d]`：获取高频页面流转路径拓扑
+- `shiplens canvas [--range 7d]`：获取完整的节点关系与全景可视化拓扑
+
+---
+
+## 8. 页面点击热力图 (`heatmap`)
+
+```bash
+shiplens heatmap --template <template_id> [--range 7d]
+```
+
+拉取目标页面的点击热力坐标、交互事件分布与页面黑白骨架图。
+
+---
+
+## 9. AI 实时看板管理 (`dashboards`)
+
+- `shiplens dashboards list`：查看已创建的 AI 数据看板
+- `shiplens dashboards create --title "<标题>" --prompt "<分析诉求>"`：一键创建并生成在线实时看板链接
+
+---
+
+## 10. 环境与连通性体检 (`doctor`)
+
+```bash
+shiplens doctor
+```
+
+一键自检 5 大核心项：本地配置、SDK 安装、代码插桩、网络连通性及凭证有效性。
+
+---
+
+## 11. 业务上下文同步 (`context`)
+
+- `shiplens context show`：查看当前产品的 `.shiplens/contexts/<app_id>.md` 业务上下文内容
+- `shiplens context push`：将本地页面/按钮功能描述同步至云端
+- `shiplens context pull`：从云端拉取已持久化的业务上下文文件
+
+---
+
+## 12. 本地 stdio MCP 代理服务 (`mcp serve`)
+
+启动本地 stdio MCP 代理通道，自动读取当前目录的 `shiplens.env` 设备凭证并安全转发 MCP 工具调用。
+
+---
+
+## 13. 全系统前后端接口调用拓扑 (12 步端到端数据流)
+
+全系统从用户接入、激活到数据分析的完整数据链路：
+
+```mermaid
+sequenceDiagram
+    participant User as 用户 / AI Agent
+    participant CLI as Shiplens CLI
+    participant Cloud as Cloud API 云端
+    participant SDK as @shiplens/sdk
+    participant MCP as 本地 stdio MCP 代理
+
+    Note over User,MCP: 一、 极速初始化与激活流程 (步骤 1-7)
+    User->>CLI: 1. npx @shiplens/cli init
+    CLI->>Cloud: 2. POST /api/connect (注册项目及 4 级行业分类)
+    Cloud-->>CLI: 返回 app_id + 临时 dashboard_url
+    CLI->>CLI: 3. 智能检测框架并注入 SDK 采集代码
+    CLI->>CLI: 4. 4级降级安装 @shiplens/sdk 依赖
+    CLI->>CLI: 5. 扫描页面文案生成 .shiplens/contexts/<app_id>.md
+    User->>CLI: 6. shiplens auth bind --email <用户邮箱>
+    CLI->>Cloud: POST /api/auth/start-email (发送 Magic Link)
+    Cloud-->>User: 7. 发送激活邮件 → 用户点击链接完成激活
+    Cloud-->>CLI: 下发设备凭证至本地 shiplens.env (0600权限)
+
+    Note over User,MCP: 二、 数据分析与查询链路 (步骤 8-12)
+    User->>CLI: 8. 执行 shiplens summary / query / sql
+    CLI->>CLI: 9. 加载 shiplens.env 凭证与 learnings 覆盖规则
+    CLI->>Cloud: 10. 发起携带身份签名的 API 请求
+    Cloud-->>CLI: 11. 返回聚合指标 / 漏斗数据 / 热力坐标
+    CLI-->>User: 12. 结构化 JSON 交付 → AI 输出深度洞察
+
+    Note over User,MCP: 三、 MCP 协议代理接入 (备选)
+    User->>MCP: shiplens mcp serve (stdio)
+    MCP->>Cloud: 携带本地凭据透传调用远程 MCP 服务
+    Cloud-->>MCP: 返回数据响应
+    MCP-->>User: 交付结构化工具调用结果
+```
+
+### 核心组件角色与职责分工
+
+| 核心组件 | 角色职责与定位 |
+|---------|---------------|
+| **Shiplens CLI** (`@shiplens/cli`) | 15 秒极速插桩、本地配置管理、直接数据分析与诊断 |
+| **Cloud API** | 项目注册、Magic Link 鉴权、数据多维聚合与看板托管 |
+| **SDK** (`@shiplens/sdk`) | 客户端无感 PV/点击/自定义事件采集、DOM 骨架哈希映射 |
+| **`shiplens.env`** | 设备级凭证（Access Secret），0600 安全权限，自动 .gitignore 保护 |
+| **本地 stdio MCP 代理** (`shiplens mcp serve`) | 供 Cursor/Antigravity/Codex 等 IDE 的 stdio 通道，携带本地凭据安全转发 |
+| **`./.shiplens.json`** | 本地项目状态机缓存（`app_id`、项目名、Schema 更新时间戳） |
+| **`.shiplens/contexts/<app_id>.md`** | 业务上下文字典（页面路由、按钮文本、功能语义说明） |
+| **`.shiplens/learnings.md`** | 项目专属动态偏好覆盖（自定义时间周期、目标漏斗、过滤规则） |

package/lib/api.js

@@ -24,21 +24,25 @@ class APIClient {
     const fullURL = `${this.baseURL}${path}`;
     const parsed = new URL(fullURL);
     const isHttps = parsed.protocol === 'https:';
-    const lib = isHttps ? https : http;
+    const transport = isHttps ? https : http;
 
-    const payload = body ? (typeof body === 'string' ? body : JSON.stringify(body)) : null;
-    let pkgVer = '1.3.0';
+    let pkgVer = '1.3.1';
     try {
       pkgVer = require('../package.json').version || pkgVer;
     } catch (e) {}
+
     const headers = {
       'Content-Type': 'application/json',
       'User-Agent': `Shiplens-CLI/${pkgVer} (Node.js)`,
     };
+
     if (this.secret) {
       headers['Authorization'] = `Bearer ${this.secret}`;
     }
-    if (payload) {
+
+    let payload = null;
+    if (body !== null && body !== undefined) {
+      payload = typeof body === 'string' ? body : JSON.stringify(body);
       headers['Content-Length'] = Buffer.byteLength(payload);
     }
 
@@ -52,16 +56,14 @@ class APIClient {
     };
 
     return new Promise((resolve, reject) => {
-      const req = lib.request(options, (res) => {
-        let resData = '';
-        res.on('data', (chunk) => {
-          resData += chunk;
-        });
+      const req = transport.request(options, (res) => {
+        let raw = '';
+        res.on('data', (chunk) => { raw += chunk; });
         res.on('end', () => {
           let json = null;
           try {
-            json = JSON.parse(resData);
-          } catch (e) {
+            json = JSON.parse(raw);
+          } catch {
             json = null;
           }
 
@@ -75,12 +77,12 @@ class APIClient {
               case 429: code = ERROR_CODES.RATE_LIMITED; break;
               case 400: case 422: code = ERROR_CODES.INVALID_SQL; break;
             }
-            const msg = (json && (json.message || json.error || (json.detail && (typeof json.detail === 'string' ? json.detail : JSON.stringify(json.detail))))) || resData || `HTTP ${res.statusCode}`;
+            const msg = (json && (json.message || json.error || (json.detail && (typeof json.detail === 'string' ? json.detail : JSON.stringify(json.detail))))) || raw || `HTTP ${res.statusCode}`;
             const err = new Error(msg);
             err.code = (json && json.code) || code;
             err.statusCode = res.statusCode;
             err.status = res.statusCode;
-            err.response = json || resData;
+            err.response = json || raw;
             err.ok = false;
             return reject(err);
           }
@@ -89,16 +91,16 @@ class APIClient {
         });
       });
 
-      req.on('error', (err) => {
-        const error = new Error(`Network connection error: ${err.message}`);
-        error.code = ERROR_CODES.NETWORK_FAILED;
-        error.ok = false;
-        reject(error);
-      });
-
       req.on('timeout', () => {
         req.destroy();
-        const error = new Error(`Request timed out (${options.timeout}ms)`);
+        const err = new Error(`请求超时 (${options.timeout}ms): ${method} ${path}`);
+        err.code = ERROR_CODES.NETWORK_FAILED;
+        err.ok = false;
+        reject(err);
+      });
+
+      req.on('error', (err) => {
+        const error = new Error(`网络连接异常: ${err.message}`);
         error.code = ERROR_CODES.NETWORK_FAILED;
         error.ok = false;
         reject(error);
@@ -111,26 +113,26 @@ class APIClient {
     });
   }
 
-  // 15-second connect & project registration (POST /api/connect)
+  // 15 秒极速建立连接/上报项目 (POST /api/connect)
   async connect(data) {
     const res = await this.request('POST', '/api/connect', data);
     if (typeof res === 'object') res.ok = true;
     return res;
   }
 
-  // Send Magic Link for email binding (POST /api/auth/email/start)
+  // 一键发送 Magic Link 邮箱绑定 (POST /api/auth/email/start)
   async startEmail(data) {
     const res = await this.request('POST', '/api/auth/email/start', data);
     if (typeof res === 'object') res.ok = true;
     return res;
   }
 
-  // Check email activation status (GET /api/auth/email-status?token=...)
+  // 检查邮箱绑定/激活状态 (GET /api/auth/email-status?token=...)
   async checkEmailStatus(token) {
     return this.request('GET', `/api/auth/email-status?token=${encodeURIComponent(token)}`);
   }
 
-  // Exponential backoff retry for startEmail
+  // startEmail 指数退避重试
   async startEmailWithRetry(data, retry = 2, baseMs = 500) {
     let lastErr;
     for (let i = 0; i <= retry; i++) {
@@ -147,53 +149,60 @@ class APIClient {
     throw lastErr;
   }
 
-  // List offline Access Secrets (GET /api/auth/api-keys)
+  // 查询离线 Access Secret 列表 (GET /api/auth/api-keys)
   async listAccessSecrets() {
     return this.request('GET', '/api/auth/api-keys');
   }
 
-  // Create offline Access Secret (POST /api/auth/api-keys)
+  // 创建离线 Access Secret (POST /api/auth/api-keys)
   async createAccessSecret(data) {
     return this.request('POST', '/api/auth/api-keys', data);
   }
 
-  // Revoke offline Access Secret (DELETE /api/auth/api-keys/:keyId)
+  // 吊销离线 Access Secret (DELETE /api/auth/api-keys/:keyId)
   async revokeAccessSecret(apiKeyId) {
     return this.request('DELETE', `/api/auth/api-keys/${encodeURIComponent(apiKeyId)}`);
   }
 
+  // 获取当前登录用户信息 (GET /api/me)
   async me() {
     const res = await this.request('GET', '/api/me');
     if (typeof res === 'object') res.ok = true;
     return res;
   }
 
+  // 获取用户项目列表 (GET /api/apps)
   async listProjects() {
     const res = await this.request('GET', '/api/apps');
     if (typeof res === 'object') res.ok = true;
     return res;
   }
 
+  // 绑定项目到当前登录账号 (POST /api/projects/bind)
   async bindProject(appId, projectName = '') {
     return this.request('POST', '/api/projects/bind', { app_id: appId, project_name: projectName });
   }
 
+  // 更新项目分类法配置 (PUT /api/apps/:appId/taxonomy)
   async updateTaxonomy(appId, data) {
     const res = await this.request('PUT', `/api/apps/${encodeURIComponent(appId)}/taxonomy`, data);
     if (typeof res === 'object') res.ok = true;
     return res;
   }
 
+  // 获取项目分类法配置 (GET /api/apps/:appId/taxonomy)
   async getTaxonomy(appId) {
     const res = await this.request('GET', `/api/apps/${encodeURIComponent(appId)}/taxonomy`);
     if (typeof res === 'object') res.ok = true;
     return res;
   }
 
+  // 删除项目 (DELETE /api/apps/:appId)
   async deleteProject(appId) {
     return this.request('DELETE', `/api/apps/${encodeURIComponent(appId)}`);
   }
 
+  // 综合指标分析查询 (POST /api/ai/apps/:appId/analytics/query)
   async queryAnalytics(appId, queryReq) {
     const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
     const actualReq = typeof appId === 'object' ? appId : queryReq;
@@ -209,7 +218,7 @@ class APIClient {
     return this.queryAnalytics(appId, queryReq);
   }
 
-  // executeSQL (POST /api/mcp/apps/:appId/sql, payload: { sql: queryStr })
+  // 执行只读 SQL 查询 (POST /api/mcp/apps/:appId/sql)
   async executeSQL(appId, queryStr) {
     const start = Date.now();
     let actualAppId = appId;
@@ -228,6 +237,7 @@ class APIClient {
     return res;
   }
 
+  // 产品概览数据 (GET /api/ai/apps/:appId/summary)
   async summary(appId, range = '7d', env = 'production') {
     const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
     const actualRange = typeof appId === 'object' ? (appId.range || range) : range;
@@ -238,6 +248,7 @@ class APIClient {
     return res;
   }
 
+  // 页面访问与停留时长统计 (GET /api/ai/apps/:appId/pages)
   async pages(appId, range = '7d', env = 'production', limit = 10) {
     const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
     const actualRange = typeof appId === 'object' ? (appId.range || range) : range;
@@ -253,6 +264,7 @@ class APIClient {
     return this.pages(data);
   }
 
+  // 用户行为路径/流转分析 (GET /api/ai/apps/:appId/paths)
   async paths(appId, range = '7d', env = 'production') {
     const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
     const actualRange = typeof appId === 'object' ? (appId.range || range) : range;
@@ -270,6 +282,7 @@ class APIClient {
     return this.paths(data);
   }
 
+  // 全局行为画布拓扑 (GET /api/ai/apps/:appId/behavior-canvas)
   async behaviorCanvas(appId, range = '7d', env = 'production') {
     const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
     const actualRange = typeof appId === 'object' ? (appId.range || range) : range;
@@ -280,6 +293,7 @@ class APIClient {
     return res;
   }
 
+  // 点击热力图与骨架图 (GET /api/ai/apps/:appId/pages/:templateId/heatmap)
   async heatmap(appId, templateId, env = 'production', domHash = '') {
     const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
     const actualTemplateId = typeof appId === 'object' ? appId.template_id : templateId;
@@ -300,12 +314,14 @@ class APIClient {
     return this.heatmap(data);
   }
 
+  // 查询仪表盘列表 (GET /api/apps/:appId/dashboards)
   async listDashboards(appId) {
     const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
     const res = await this.request('GET', `/api/apps/${encodeURIComponent(actualAppId)}/dashboards`);
     return Array.isArray(res) ? res : (res.dashboards || []);
   }
 
+  // 创建自定义仪表盘 (POST /api/apps/:appId/dashboards)
   async createDashboard(appId, data) {
     const actualAppId = typeof appId === 'object' ? (appId.app_id || '') : appId;
     const actualData = typeof appId === 'object' ? appId : data;
@@ -314,12 +330,14 @@ class APIClient {
     return res;
   }
 
+  // 测试网络连接与服务端连通性
   async testConnectivity() {
     const start = Date.now();
     await this.request('GET', '/api/ai/tools');
     return Date.now() - start;
   }
 
+  // 获取指标元数据 Schema (GET /api/ai/apps/:appId/analytics/schema)
   async getAnalyticsSchema(appId) {
     const actualAppId = typeof appId === 'object' ? appId.app_id : appId;
     const res = await this.request('GET', `/api/ai/apps/${encodeURIComponent(actualAppId)}/analytics/schema`);
@@ -327,33 +345,35 @@ class APIClient {
     return res;
   }
 
-  // Natural language AI dashboard creation (POST /api/dashboard)
+  // 自然语言 AI 生成仪表盘 (POST /api/dashboard)
   async createAIDashboard(data) {
     const res = await this.request('POST', '/api/dashboard', data);
     if (typeof res === 'object') res.ok = true;
     return res;
   }
 
-  // Retrieve project business context (GET /api/apps/:appId/context) - 5s timeout
+  // 获取项目业务上下文 (GET /api/apps/:appId/context) - 5秒超时
   async getProjectContext(appId) {
     const res = await this.request('GET', `/api/apps/${encodeURIComponent(appId)}/context`, null, { timeout: 5000 });
     if (typeof res === 'object') res.ok = true;
     return res;
   }
 
-  // Upload/sync project business context (PUT /api/apps/:appId/context) - 5s timeout
+  // 上传/同步项目业务上下文 (PUT /api/apps/:appId/context) - 5秒超时
   async uploadProjectContext(appId, data) {
     const res = await this.request('PUT', `/api/apps/${encodeURIComponent(appId)}/context`, data, { timeout: 5000 });
     if (typeof res === 'object') res.ok = true;
     return res;
   }
 
-  // Delete project business context (DELETE /api/apps/:appId/context) - 5s timeout
+  // 删除云端项目业务上下文 (DELETE /api/apps/:appId/context) - 5秒超时
   async deleteProjectContext(appId) {
-    return this.request('DELETE', `/api/apps/${encodeURIComponent(appId)}/context`, null, { timeout: 5000 });
+    const res = await this.request('DELETE', `/api/apps/${encodeURIComponent(appId)}/context`, null, { timeout: 5000 });
+    if (typeof res === 'object') res.ok = true;
+    return res;
   }
 
-  // Request with exponential backoff retry for general methods
+  // 带重试的请求方法
   async requestWithRetry(method, path, body = null, maxRetries = 2) {
     let lastErr = null;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {