@shiplens/cli 1.4.2 → 1.4.3

package/README.md

@@ -1,6 +1,6 @@
 # 🚀 Shiplens CLI
 
-> **Shiplens 官方命令行工具 — 面向 Web 前端的用户行为数据统计与 AI Agent 智能分析引擎。**
+> **Official Shiplens CLI — Automated Web User Analytics & AI Agent Analysis Engine.**
 
 [![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)
@@ -8,64 +8,64 @@
 
 ---
 
-Shiplens CLI 是 [shiplens.dev](https://shiplens.dev) 官方配套的命令行工具。它为前端项目提供自动化的数据统计接入，并与各类 AI Agent（Cursor、Windsurf、Codex、Claude 等）无缝协同，实现对话式数据查询与自动化分析。
+Shiplens CLI is the official command-line tool for [shiplens.dev](https://shiplens.dev). It provides automated analytics instrumentation for modern web frontend applications and seamlessly pairs with AI coding agents (Cursor, Windsurf, Codex, Claude, Antigravity, etc.) for conversational data analysis and real-time dashboards.
 
 ---
 
-## 🌟 核心功能
+## 🌟 Key Features
 
-- **自动化接入与代码插桩**：自动识别前端项目框架（Next.js、Vite、Vue、HTML 等），无感注入 `@shiplens/sdk` 数据采集代码；
-- **用户行为数据统计**：秒级查看全站流量大盘、访问路径、页面留存与点击热力图；
-- **AI Agent 智能分析**：支持通过 CLI 与本地 stdio MCP 代理（`shiplens mcp serve`）与 AI 对话，让 Agent 直接读取产品数据并输出教科书级业务洞察；
-- **AI 实时看板生成**：一句话自然语言诉求，云端自动拼装 12 列响应式数据看板；
-- **业务上下文与动态自适应**：自动提取页面功能文案辅助 AI 理解业务，并支持按项目自适应记忆个性化分析偏好。
+- **Automated Setup & Instrumentation**: Automatically detects frontend frameworks (Next.js, Vite, Vue, HTML, etc.) and injects `@shiplens/sdk` tracking code.
+- **Web User Analytics**: Real-time traffic summaries, user journeys, retention cohorts, and click heatmaps.
+- **AI Agent Intelligence**: Query and analyze product behavior data directly from AI coding assistants via CLI and local stdio MCP proxy (`shiplens mcp serve`).
+- **AI-Powered Live Dashboards**: Assemble 12-column responsive analytics dashboards from natural language prompts.
+- **Business Context & Adaptive Learning**: Automatically maps DOM hashes to real page names and remembers per-project analysis preferences.
 
 ---
 
-## ⚡ 快速开始
+## ⚡ Quick Start
 
-在任何前端项目根目录下执行初始化命令：
+Run the initialization command in the root directory of any frontend project:
 
 ```bash
-# 通用终端
+# General terminal
 npx --yes @shiplens/cli init
 
 # Windows PowerShell
 npx.cmd --yes @shiplens/cli init
 
-# 备用镜像源
+# Backup mirror fallback
 npx --yes --registry=https://registry.npmmirror.com @shiplens/cli init
 ```
 
 ---
 
-## 📊 常用命令速查
+## 📊 Core Commands Reference
 
-| 命令 | 说明 |
+| Command | Description |
 | :--- | :--- |
-| `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 调度 |
+| `shiplens init` | Onboard project, instrument tracking SDK, and inject AI skill |
+| `shiplens summary` | Macro traffic overview (PV, UV, dwell time, geos, devices) |
+| `shiplens query` | Multi-dimensional metrics aggregation and conversion funnels |
+| `shiplens sql` | Safe read-only custom SQL queries |
+| `shiplens pages` | Page-level visits and average dwell times |
+| `shiplens heatmap` | Visual click heatmaps and skeleton wireframe snapshots |
+| `shiplens dashboards create` | Generate live AI dashboards from natural language |
+| `shiplens doctor` | End-to-end diagnostics on SDK, network, and configuration |
+| `shiplens context show` | Inspect business context and page semantic mappings |
+| `shiplens auth bind` | Request Magic Link to activate authorization and event quota |
+| `shiplens mcp serve` | Start local stdio MCP proxy for AI IDEs and Agents |
 
 ---
 
-## 🔗 相关资源
+## 🔗 Resources
 
-- 官方网站：[https://shiplens.dev](https://shiplens.dev)
-- 常见问题与支持：[https://shiplens.dev/faq](https://shiplens.dev/faq)
-- 全命令参考手册：[`docs/02_SHIPLENS_CLI_全命令参考手册.md`](./docs/02_SHIPLENS_CLI_全命令参考手册.md)
+- Website: [https://shiplens.dev](https://shiplens.dev)
+- Support & FAQ: [https://shiplens.dev/faq](https://shiplens.dev/faq)
+- Command Reference: [`docs/02_CLI_COMMAND_REFERENCE.md`](./docs/02_CLI_COMMAND_REFERENCE.md)
 
 ---
 
-## 📜 开源协议
+## 📜 License
 
 Apache-2.0 © Shiplens Team
 

package/docs/02_CLI_COMMAND_REFERENCE.md

@@ -0,0 +1,195 @@
+# Shiplens CLI Command Reference
+
+> Complete documentation for all Shiplens CLI commands, flags, arguments, and sample outputs for AI Agent execution.
+
+---
+
+## Global Flags
+
+| Flag | Type | Description |
+| :--- | :--- | :--- |
+| `--json` | boolean | Output results in JSON format (required for AI Agents) |
+| `--app-id <id>` | string | Explicitly specify target `app_id` (default: auto-read from `.shiplens.json`) |
+| `--env <env>` | string | Target environment: `production` (default) or `staging` |
+| `--secret <key>` | string | Explicitly pass Access Secret |
+| `--api-url <url>` | string | Custom backend API base URL (default: `http://120.26.230.33`) |
+| `--help`, `-h` | boolean | Display help information |
+
+---
+
+## 1. Project Onboarding (`init`)
+
+```bash
+shiplens init [options]
+```
+
+### Options:
+- `--name <name>`: Project name (default: package.json name)
+- `--description <desc>`: Project description
+- `--industry <ind>`: Industry category
+- `--genre <id>`: Level 1 Genre ID
+- `--subgenre <id>`: Level 2 Sub-genre ID
+- `--tags <tag1,tag2>`: Comma-separated feature tag IDs (max 10)
+- `--email <email>`: Binding email (pass `auto` to use git config)
+- `--framework <type>`: Override detected framework (`nextjs-app`, `nextjs-pages`, `vite`, `vue`, `html`)
+- `--force`: Force overwrite existing local configuration
+- `--no-install`: Skip package manager installation
+- `--no-commit`: Skip automatic Git commit
+
+---
+
+## 2. Authentication (`auth`)
+
+### Subcommands:
+- `shiplens auth status`: Check credential validity
+- `shiplens auth set [secret]`: Save Access Secret to `~/.shiplens/config.json`
+- `shiplens auth whoami`: Display authenticated user details
+- `shiplens auth logout`: Clear local credentials
+- `shiplens auth bind --email <email>`: Request Magic Link activation email
+- `shiplens auth mcp-config --client <client>`: Generate MCP client configuration
+- `shiplens auth configure --client <client>`: Automatically write MCP configuration
+
+---
+
+## 3. Projects Management (`projects`)
+
+### Subcommands:
+- `shiplens projects list`: List all projects associated with current account
+- `shiplens projects bind`: Bind current project to account
+- `shiplens projects delete [--force]`: Delete project and its data
+
+---
+
+## 4. Multi-Dimensional Query (`query`)
+
+```bash
+shiplens query [options]
+```
+
+### Options:
+- `--metric <name>` / `--metrics <m1,m2>`: Metric name(s)
+- `--range <range>`: Time range (`24h`, `7d`, `14d`, `30d`, `90d`)
+- `--grain <grain>`: Time grain (`hour`, `day`, `week`, `month`)
+- `--group-by <dim>`: Group dimension (`path`, `template_id`, `country`, `browser`, `device_type`)
+- `--filter <key=value>`: Filter condition (e.g. `--filter country=US`)
+- `--limit <num>`: Result limit (default: 30)
+- `--file <path>`: Load full `AnalyticsQueryRequest` from JSON file
+
+---
+
+## 5. Sandboxed SQL (`sql`)
+
+```bash
+shiplens sql --query "<sql>" [options]
+```
+
+### Options:
+- `--query "<sql>"` / `--sql "<sql>"`: SQL query string
+- `--stdin`: Read SQL query from stdin stream
+
+---
+
+## 6. Product Summary (`summary`)
+
+```bash
+shiplens summary [--range <range>]
+```
+
+Returns total PV, UV, average session duration, bounce rate, top countries, and top devices.
+
+---
+
+## 7. Page Telemetry (`pages`, `paths`, `canvas`)
+
+- `shiplens pages [--range 7d] [--limit 10]`: Page-level visits and dwell times
+- `shiplens paths [--range 7d]`: Sankey user flow and transition paths
+- `shiplens canvas [--range 7d]`: Behavioral canvas node-link topology
+
+---
+
+## 8. Click Heatmaps (`heatmap`)
+
+```bash
+shiplens heatmap --template <template_id> [--dom-hash <hash>]
+```
+
+Returns skeleton wireframe SVG URL, total clicks, and element click distribution.
+
+---
+
+## 9. AI Dashboards (`dashboards`)
+
+- `shiplens dashboards list`: List all dashboards for project
+- `shiplens dashboards create --title "..." --prompt "..."`: Create responsive dashboard via prompt
+- `shiplens dashboards create --ai --prompt "..."`: AI-driven dashboard generation
+
+---
+
+## 10. Environment Diagnostics (`doctor`)
+
+```bash
+shiplens doctor [--json]
+```
+
+Performs health checks on:
+1. `local_config`: `.shiplens.json` validity
+2. `sdk_dependency`: `@shiplens/sdk` in `package.json`
+3. `code_injection`: SDK import in entry files
+4. `ingestion_connectivity`: Network latency to API
+5. `auth_credential`: Access secret resolution
+6. `email_binding`: Quota activation status
+7. `schema_freshness`: Schema synchronization age
+
+---
+
+## End-to-End System Topology
+
+The full data flow from user action to analytics delivery:
+
+```mermaid
+sequenceDiagram
+    participant User as User / Agent
+    participant CLI as Shiplens CLI
+    participant Cloud as Cloud API
+    participant SDK as @shiplens/sdk
+    participant MCP as Local MCP Proxy
+
+    Note over User,MCP: Onboarding Flow (Steps 1-7)
+    User->>CLI: 1. npx @shiplens/cli init
+    CLI->>Cloud: 2. POST /api/connect (register project, 4-level taxonomy)
+    Cloud-->>CLI: app_id + dashboard_url
+    CLI->>CLI: 3. Inject SDK code into entry file
+    CLI->>CLI: 4. Install @shiplens/sdk dependency
+    CLI->>CLI: 5. Scan pages → .shiplens/contexts/<app_id>.md
+    User->>CLI: 6. shiplens auth bind --email <email>
+    CLI->>Cloud: POST /api/auth/start-email
+    Cloud-->>User: 7. Magic Link email → user clicks → project activated
+    Cloud-->>CLI: Device credentials → shiplens.env (0600)
+
+    Note over User,MCP: Analysis Flow (Steps 8-12)
+    User->>CLI: 8. shiplens summary / query / sql
+    CLI->>CLI: 9. Load shiplens.env credentials
+    CLI->>Cloud: 10. Authenticated API request
+    Cloud-->>CLI: 11. Analytics data response
+    CLI-->>User: 12. JSON output → Agent synthesizes insights
+
+    Note over User,MCP: MCP Integration (Alternative)
+    User->>MCP: shiplens mcp serve (stdio)
+    MCP->>Cloud: Proxied requests with shiplens.env credentials
+    Cloud-->>MCP: Data response
+    MCP-->>User: Structured tool results
+```
+
+### Component Roles
+
+| Component | Responsibility |
+|-----------|---------------|
+| **CLI** (`npx @shiplens/cli`) | Onboarding, SDK injection, local config management, direct analytics queries |
+| **Cloud API** | Project registration, authentication, data aggregation, dashboard hosting |
+| **SDK** (`@shiplens/sdk`) | Client-side event capture (pageviews, clicks, custom events), DOM hashing |
+| **shiplens.env** | Device-level credentials (Access Secret), file permission 0600, auto-gitignored |
+| **Local MCP Proxy** (`shiplens mcp serve`) | stdio bridge for IDE/Agent integration, forwards requests with local credentials |
+| **.shiplens.json** | Project metadata cache (app_id, project_name, schema timestamp) |
+| **.shiplens/contexts/\<app_id\>.md** | Business context dictionary (page routes, button labels, feature descriptions) |
+| **.shiplens/learnings.md** | User preference overrides (date range, metrics, filters) |
+

package/lib/api.js

@@ -24,25 +24,21 @@ class APIClient {
     const fullURL = `${this.baseURL}${path}`;
     const parsed = new URL(fullURL);
     const isHttps = parsed.protocol === 'https:';
-    const transport = isHttps ? https : http;
+    const lib = isHttps ? https : http;
 
-    let pkgVer = '1.3.1';
+    const payload = body ? (typeof body === 'string' ? body : JSON.stringify(body)) : null;
+    let pkgVer = '1.3.0';
     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}`;
     }
-
-    let payload = null;
-    if (body !== null && body !== undefined) {
-      payload = typeof body === 'string' ? body : JSON.stringify(body);
+    if (payload) {
       headers['Content-Length'] = Buffer.byteLength(payload);
     }
 
@@ -56,14 +52,16 @@ class APIClient {
     };
 
     return new Promise((resolve, reject) => {
-      const req = transport.request(options, (res) => {
-        let raw = '';
-        res.on('data', (chunk) => { raw += chunk; });
+      const req = lib.request(options, (res) => {
+        let resData = '';
+        res.on('data', (chunk) => {
+          resData += chunk;
+        });
         res.on('end', () => {
           let json = null;
           try {
-            json = JSON.parse(raw);
-          } catch {
+            json = JSON.parse(resData);
+          } catch (e) {
             json = null;
           }
 
@@ -77,12 +75,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))))) || raw || `HTTP ${res.statusCode}`;
+            const msg = (json && (json.message || json.error || (json.detail && (typeof json.detail === 'string' ? json.detail : JSON.stringify(json.detail))))) || resData || `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 || raw;
+            err.response = json || resData;
             err.ok = false;
             return reject(err);
           }
@@ -91,16 +89,16 @@ class APIClient {
         });
       });
 
-      req.on('timeout', () => {
-        req.destroy();
-        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(`Network connection error: ${err.message}`);
+        error.code = ERROR_CODES.NETWORK_FAILED;
+        error.ok = false;
+        reject(error);
       });
 
-      req.on('error', (err) => {
-        const error = new Error(`网络连接异常: ${err.message}`);
+      req.on('timeout', () => {
+        req.destroy();
+        const error = new Error(`Request timed out (${options.timeout}ms)`);
         error.code = ERROR_CODES.NETWORK_FAILED;
         error.ok = false;
         reject(error);
@@ -113,26 +111,26 @@ class APIClient {
     });
   }
 
-  // 15 秒极速建立连接/上报项目 (POST /api/connect)
+  // 15-second connect & project registration (POST /api/connect)
   async connect(data) {
     const res = await this.request('POST', '/api/connect', data);
     if (typeof res === 'object') res.ok = true;
     return res;
   }
 
-  // 一键发送 Magic Link 邮箱绑定 (POST /api/auth/email/start)
+  // Send Magic Link for email binding (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;
   }
 
-  // 检查邮箱绑定/激活状态 (GET /api/auth/email-status?token=...)
+  // Check email activation status (GET /api/auth/email-status?token=...)
   async checkEmailStatus(token) {
     return this.request('GET', `/api/auth/email-status?token=${encodeURIComponent(token)}`);
   }
 
-  // startEmail 指数退避重试
+  // Exponential backoff retry for startEmail
   async startEmailWithRetry(data, retry = 2, baseMs = 500) {
     let lastErr;
     for (let i = 0; i <= retry; i++) {
@@ -149,60 +147,53 @@ class APIClient {
     throw lastErr;
   }
 
-  // 查询离线 Access Secret 列表 (GET /api/auth/api-keys)
+  // List offline Access Secrets (GET /api/auth/api-keys)
   async listAccessSecrets() {
     return this.request('GET', '/api/auth/api-keys');
   }
 
-  // 创建离线 Access Secret (POST /api/auth/api-keys)
+  // Create offline Access Secret (POST /api/auth/api-keys)
   async createAccessSecret(data) {
     return this.request('POST', '/api/auth/api-keys', data);
   }
 
-  // 吊销离线 Access Secret (DELETE /api/auth/api-keys/:keyId)
+  // Revoke offline 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;
@@ -218,7 +209,7 @@ class APIClient {
     return this.queryAnalytics(appId, queryReq);
   }
 
-  // 执行只读 SQL 查询 (POST /api/mcp/apps/:appId/sql)
+  // executeSQL (POST /api/mcp/apps/:appId/sql, payload: { sql: queryStr })
   async executeSQL(appId, queryStr) {
     const start = Date.now();
     let actualAppId = appId;
@@ -237,7 +228,6 @@ 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;
@@ -248,7 +238,6 @@ 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;
@@ -264,7 +253,6 @@ 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;
@@ -282,7 +270,6 @@ 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;
@@ -293,7 +280,6 @@ 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;
@@ -314,14 +300,12 @@ 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;
@@ -330,14 +314,12 @@ 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`);
@@ -345,35 +327,33 @@ class APIClient {
     return res;
   }
 
-  // 自然语言 AI 生成仪表盘 (POST /api/dashboard)
+  // Natural language AI dashboard creation (POST /api/dashboard)
   async createAIDashboard(data) {
     const res = await this.request('POST', '/api/dashboard', data);
     if (typeof res === 'object') res.ok = true;
     return res;
   }
 
-  // 获取项目业务上下文 (GET /api/apps/:appId/context) - 5秒超时
+  // Retrieve project business context (GET /api/apps/:appId/context) - 5s timeout
   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;
   }
 
-  // 上传/同步项目业务上下文 (PUT /api/apps/:appId/context) - 5秒超时
+  // Upload/sync project business context (PUT /api/apps/:appId/context) - 5s timeout
   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 /api/apps/:appId/context) - 5秒超时
+  // Delete project business context (DELETE /api/apps/:appId/context) - 5s timeout
   async deleteProjectContext(appId) {
-    const res = await this.request('DELETE', `/api/apps/${encodeURIComponent(appId)}/context`, null, { timeout: 5000 });
-    if (typeof res === 'object') res.ok = true;
-    return res;
+    return this.request('DELETE', `/api/apps/${encodeURIComponent(appId)}/context`, null, { timeout: 5000 });
   }
 
-  // 带重试的请求方法
+  // 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++) {