byteplan-cli 1.0.2 → 1.2.0

package/skills/byteplan-api/API_REFERENCE.md

@@ -0,0 +1,249 @@
+# API Reference
+
+> 本文档详细说明 api.js 的函数接口，需要深入了解时阅读。
+
+## 导入方式
+
+```javascript
+// 从 byteplan-api skill 导入
+import { login, loginWithEnv, getUserInfo, setEnvironment } from '/Users/fudebao/.claude/skills/byteplan-api/scripts/api.js';
+```
+
+## 环境管理
+
+| 函数 | 描述 |
+|------|------|
+| `setEnvironment(env)` | 设置登录环境（仅支持 'uat'） |
+| `getEnvironment()` | 获取当前环境 |
+| `getBaseUrl()` | 获取当前环境的基础 URL |
+| `setCliMode(useCli)` | 设置是否使用 CLI 模式（默认 true） |
+| `isUsingCli()` | 检查当前是否使用 CLI 模式 |
+
+## 登录认证
+
+| 函数 | 描述 |
+|------|------|
+| `login(username, password, env?)` | 使用凭证登录（自动处理 RSA 加密，**自动保存 token**） |
+| `loginWithEnv()` | 使用 `.env` 凭证登录（自动使用缓存 token，**自动续期**） |
+| `loginWithEnv(env, forceReLogin)` | 强制重新登录 |
+| `getToken()` | 从 `.env` 获取 token |
+
+```javascript
+// 方式 1：自动使用缓存 token（推荐）
+// 首次登录会保存 token，后续调用自动复用
+import { loginWithEnv } from './api.js';
+const result = await loginWithEnv();
+const token = result.access_token;
+if (result._cached) {
+  console.log('使用缓存的 token'); // 无需重新登录
+}
+
+// 方式 2：强制重新登录
+const result = await loginWithEnv('uat', true); // forceReLogin = true
+
+// 方式 3：手动传入凭证（也会自动保存 token）
+import { login } from './api.js';
+const result = await login('手机号', '密码', 'uat');
+const token = result.access_token;
+```
+
+## Token 持久化
+
+登录成功后，系统会自动将以下信息保存到 `~/.byteplan/.env` 文件：
+
+| 字段 | 说明 |
+|------|------|
+| `ACCESS_TOKEN` | 访问令牌 |
+| `REFRESH_TOKEN` | 刷新令牌 |
+| `TOKEN_EXPIRES_IN` | 过期时间戳（毫秒） |
+
+**自动续期机制**：
+- `loginWithEnv()` 会自动检查 token 是否过期
+- 如果 token 有效（未过期或距离过期超过 5 分钟），直接使用缓存
+- 如果 token 过期，自动使用保存的账号密码重新登录
+
+## 用户与租户
+
+| 函数 | 描述 |
+|------|------|
+| `getUserInfo(token)` | 获取用户和租户信息，返回 `{ user: {...}, tenantList: [...] }` |
+| `switchTenant(token, tenantId)` | 切换租户上下文 |
+
+```javascript
+// 获取用户信息和可用租户列表
+const userInfo = await getUserInfo(token);
+// userInfo.user = { name, userName, tenantName, ... }
+// userInfo.tenantList = [{ tenantId, tenantName }, ...]
+
+// 如需切换到特定租户
+await switchTenant(token, tenantId);
+```
+
+## 模型查询
+
+| 函数 | 描述 |
+|------|------|
+| `queryModels(token, options?)` | 列出可用模型 |
+| `getModelColumns(token, modelCodes)` | 获取模型字段定义 |
+| `getModelData(token, modelCode, params)` | 查询模型数据 |
+
+### 返回值格式说明（重要）
+
+**⚠️ 所有 API 函数直接返回后端响应，无需额外处理：**
+
+| 函数 | 返回值类型 | 说明 |
+|------|-----------|------|
+| `queryModels()` | `Array` | **直接返回数组**，可用 `models.map()` 遍历 |
+| `getModelColumns()` | `Object` | 返回 `{ data: [...], ... }` 结构 |
+| `getModelData()` | `Object` | 返回 `{ data: [...], total: number }` 结构，用 `.data` 取数据 |
+
+```javascript
+// ❌ 错误用法：queryModels 返回的是数组，不要加 .data
+const models = await queryModels(token);
+const list = models.data;  // 错误！models 本身就是数组
+
+// ✅ 正确用法：直接遍历
+const models = await queryModels(token);
+const modelList = models.map(m => ({ name: m.modelName, code: m.modelCode }));
+// models.length = 模型总数
+
+// ✅ getModelData 返回的是对象，需要用 .data 取数据数组
+const result = await getModelData(token, 'model_code');
+const items = result.data;      // 数据数组
+const total = result.total;     // 总记录数
+
+// ✅ getModelColumns 返回的是对象
+const columns = await getModelColumns(token, ['model_code_1']);
+// columns.data = 字段定义数组
+```
+
+## 字段类型值获取
+
+| 函数 | 描述 |
+|------|------|
+| `getDimValues(token, dimCode, options?)` | 获取 DIM 字段可选值 |
+| `getListValues(token, listCode, options?)` | 获取 LIST 字段可选值 |
+| `getLovValues(token, lovCode, options?)` | 获取 LOV 字段可选值 |
+| `getLevelValues(token, levelCode, options?)` | 获取 LEVEL 字段可选值 |
+
+```javascript
+// 获取维度值
+const dimValues = await getDimValues(token, 'dim_code', {
+  modelCode: 'model_code',
+  colName: 'field_name',
+  page: 0,
+  size: 100
+});
+
+// 获取列表值
+const listValues = await getListValues(token, 'list_code', {
+  modelCode: 'model_code',
+  colName: 'field_name'
+});
+
+// 获取 LOV 值
+const lovValues = await getLovValues(token, 'lov_code', {
+  keywords: '搜索关键词'
+});
+
+// 获取层级值
+const levelValues = await getLevelValues(token, 'level_code', {
+  modelCode: 'model_code',
+  colName: 'field_name'
+});
+```
+
+## 查询语法
+
+### 条件结构
+
+```javascript
+{
+  type: 'condition',
+  field: '字段名',
+  operator: '=',  // 支持: =, !=, >, <, >=, <=, LIKE, IN, BETWEEN
+  value: '值'
+}
+```
+
+### 条件组结构（多条件）
+
+```javascript
+{
+  type: 'group',
+  logic: 'AND',  // AND 或 OR
+  children: [
+    { type: 'condition', field: '字段1', operator: '=', value: '值1' },
+    { type: 'condition', field: '字段2', operator: '>', value: '值2' }
+  ]
+}
+```
+
+### 特殊字段类型
+
+对于 DIM、LIST、LOV、LEVEL 类型字段：
+- 直接使用原字段名（不需要拼接 `.code` 或 `.name`）
+- 使用编码值进行筛选
+
+```javascript
+// 示例：按性别筛选（DIM 类型）
+{ field: 'sex', operator: '=', value: '1' }  // '1' = 男性编码
+
+// 示例：按学科筛选（LIST 类型）
+{ field: 'subject', operator: '=', value: 'math' }
+```
+
+### 聚合查询
+
+```javascript
+const result = await getModelData(token, 'model_code', {
+  groupFields: ['category'],
+  functions: [
+    { func: 'sum', field: 'amount', alias: 'total_amount' },
+    { func: 'avg', field: 'price', alias: 'avg_price' }
+  ]
+});
+```
+
+## 完整登录示例
+
+```javascript
+import { login, loginWithEnv, getUserInfo } from './api.js';
+import { existsSync } from 'fs';
+import { homedir } from 'os';
+import path from 'path';
+
+// 凭证文件路径
+const BYTEPLAN_DIR = path.join(homedir(), '.byteplan');
+const ENV_FILE = path.join(BYTEPLAN_DIR, '.env');
+
+// 尝试使用 ~/.byteplan/.env 凭证登录
+let token;
+if (existsSync(ENV_FILE)) {
+  try {
+    const result = await loginWithEnv();
+    token = result.access_token;
+  } catch (e) {
+    // 凭证无效，需要询问用户
+  }
+}
+
+// 如果没有 token，询问用户输入账号密码
+if (!token) {
+  // 使用 AskUserQuestion 询问用户名和密码
+  // const username = ...;
+  // const password = ...;
+  const result = await login(username, password, 'uat');
+  token = result.access_token;
+}
+
+// ✅ 显示当前租户信息
+const userInfo = await getUserInfo(token);
+const currentTenant = userInfo.user?.tenantName || '未知租户';
+const userName = userInfo.user?.name || userInfo.user?.userName || '未知用户';
+
+`✅ 登录成功！
+   环境: UAT 环境
+   用户: ${userName}
+   当前租户: ${currentTenant}`;
+```

package/skills/byteplan-api/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: byteplan-api
+description: BytePlan 数据平台 API 封装。提供登录认证、模型查询、数据获取等接口。可被 byteplan-analysis、byteplan-excel、byteplan-html、byteplan-ppt、byteplan-video、byteplan-word 等技能依赖使用。
+---
+
+# BytePlan API Skill
+
+## 概述
+
+提供 BytePlan 数据平台的 JavaScript API 封装，支持：
+- 登录认证（UAT 环境）
+- 用户与租户管理
+- 模型查询与数据获取
+- 字段类型值获取（DIM/LIST/LOV/LEVEL）
+
+## CLI 模式
+
+本 skill 支持两种调用模式：
+
+1. **CLI 模式（默认）**：优先使用 `byteplan-cli` 命令行工具
+2. **直接 API 模式**：当 CLI 未安装或执行失败时，自动回退到直接 API 调用
+
+### CLI 自动安装
+
+使用 API 前，系统会自动检测用户是否安装了 `byteplan-cli`：
+- 如果未安装，会自动执行 `npm i -g byteplan-cli` 进行安装
+- 安装成功后，后续操作优先使用 CLI 模式
+
+### CLI 命令帮助
+
+如果不知道 CLI 命令的参数和用法，可以使用 `-h` 或 `--help` 查看帮助信息：
+
+```bash
+byteplan --help
+byteplan login --help
+byteplan model --help
+byteplan data --help
+```
+
+## 依赖此 Skill 的其他 Skill
+
+- [byteplan-analysis](../byteplan-analysis/SKILL.md) - 从 BytePlan 平台查询数据并生成分析报告
+- [byteplan-excel](../byteplan-excel/SKILL.md) - 数据分析 Excel 报告生成
+- [byteplan-html](../byteplan-html/SKILL.md) - 数据分析网页报告生成
+- [byteplan-ppt](../byteplan-ppt/SKILL.md) - 数据分析 PPT 报告生成
+- [byteplan-video](../byteplan-video/SKILL.md) - 数据可视化视频生成
+- [byteplan-word](../byteplan-word/SKILL.md) - 数据分析 Word 文档报告生成
+
+## 环境配置
+
+**凭证存储路径**：`~/.byteplan/.env`
+
+登录成功后自动创建 `.env` 文件：
+
+```env
+BP_ENV=uat
+BP_USER=你的手机号
+BP_PASSWORD="你的密码"
+ACCESS_TOKEN=              # 自动管理
+REFRESH_TOKEN=             # 自动管理
+TOKEN_EXPIRES_IN=          # 自动管理
+```
+
+**注意**：
+- 密码包含特殊字符时用引号包裹
+- Token 由系统自动管理，无需手动修改
+
+### 首次使用流程
+
+如果没有 `.env` 文件或 token 无效，**必须询问用户输入**：
+1. 询问用户名（手机号）
+2. 询问密码
+3. 使用凭证登录
+4. 登录成功后显示当前租户信息
+
+## API 详细文档
+
+需要深入了解 api.js 的函数接口时，请阅读 [API_REFERENCE.md](./API_REFERENCE.md)。
+
+## 快速开始
+
+```javascript
+import { loginWithEnv, getUserInfo, queryModels } from './scripts/api.js';
+
+// 自动登录（使用缓存的 token 或重新登录）
+const result = await loginWithEnv();
+const token = result.access_token;
+
+// 获取用户信息
+const userInfo = await getUserInfo(token);
+console.log(`当前租户: ${userInfo.user?.tenantName}`);
+
+// 查询模型列表
+const models = await queryModels(token);
+console.log(`可用模型: ${models.length} 个`);
+```

package/skills/byteplan-api/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "byteplan-api",
+  "version": "1.0.0",
+  "description": "BytePlan 数据平台 API 封装",
+  "type": "module",
+  "dependencies": {
+    "dotenv": "^16.4.5"
+  },
+  "keywords": [
+    "byteplan",
+    "api",
+    "data-platform"
+  ],
+  "author": "",
+  "license": "MIT"
+}