@shiplens/cli 1.4.2 → 1.4.4

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

@@ -1,205 +0,0 @@
-# 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`** | 项目专属动态偏好覆盖（自定义时间周期、目标漏斗、过滤规则） |