sophhub 0.2.2 → 0.2.4

package/skills/feishu-bitable/src/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: feishu-bitable
+description: CRUD operations for Feishu Bitable (multidimensional tables). Use when the user needs to manage tables, records, fields, or views in Feishu Bitable, or when dealing with bitable-related URLs.
+metadata: {"openclaw":{"emoji":"📊","requires":{"env":["FEISHU_APP_ID","FEISHU_APP_SECRET"]},"primaryEnv":"FEISHU_APP_ID"}}
+---
+
+# Feishu Bitable Skill
+
+CRUD operations for Feishu Bitable (多维表格) — tables, records, fields, and views.
+
+## Environment Variables
+
+`FEISHU_APP_ID` and `FEISHU_APP_SECRET` are already available from the Feishu channel configuration. No extra setup is needed. The CLI reads them automatically via `dotenv` or shell environment.
+
+## Extracting app-token from URLs
+
+Feishu Bitable URLs come in three formats. Extract the `app-token` as follows:
+
+| URL Format | Example | app-token |
+|-----------|---------|-----------|
+| **Wiki /wiki/** | `feishu.cn/wiki/AbCdEf?table=tblXXX` | Wiki token `AbCdEf` can be used directly as app-token (Feishu API accepts it) |
+| **Standalone /base/** | `feishu.cn/base/basXXXXXX` | `basXXXXXX` |
+| **Advanced /app/** | `feishu.cn/app/AbCdEf?pageId=pgeXXX` | `AbCdEf` |
+
+The `table=tblXXX` query parameter is the `table-id`. The `view=vewXXX` parameter is the view-id.
+
+**Note on /wiki/ URLs:** Feishu Bitable API accepts wiki tokens directly. If user provides a /wiki/ URL with `table=` parameter, you can safely pass the wiki token as `--app-token`. If unsure whether the URL is a bitable, use `feishu_wiki` to check `obj_type` first.
+
+## CLI Reference
+
+All commands are run from the skill directory:
+
+```bash
+cd {baseDir}
+node bin/cli.js <command> [options]
+```
+
+### Commands
+
+| Command | Required Options | Optional | Description |
+|---------|-----------------|----------|-------------|
+| `test` | — | — | Test connection and token validity |
+| `get-app` | `--app-token` | — | Get bitable app info |
+| `list-tables` | `--app-token` | `--page-size`, `--page-token` | List all tables |
+| `list-fields` | `--app-token --table-id` | `--page-size` | List fields in a table |
+| `list-records` | `--app-token --table-id` | `--page-size`, `--page-token`, `--filter`, `--sort` | List records |
+| `list-views` | `--app-token --table-id` | `--page-size` | List views |
+| `create-table` | `--app-token --name` | `--fields <json>` | Create a new table |
+| `create-record` | `--app-token --table-id --data <json>` | — | Create one record |
+| `batch-create` | `--app-token --table-id --data <json-array>` | — | Batch create records (max 100) |
+| `update-record` | `--app-token --table-id --record-id --data <json>` | — | Update a record |
+| `delete-record` | `--app-token --table-id --record-id` | — | Delete a record |
+
+### Data format
+
+The `--data` option accepts inline JSON or a file reference with `@` prefix:
+
+```bash
+# Inline JSON
+--data '{"任务名称": "新任务", "状态": "待办"}'
+
+# From file
+--data @examples/create-records.json
+```
+
+For `batch-create`, `--data` must be a JSON array of record objects.
+
+### Typical workflow
+
+1. Parse the user's Feishu URL to extract `app-token` and `table-id`
+2. `list-tables` → confirm the target table exists
+3. `list-fields` → understand the table schema (field names and types)
+4. Perform the requested operation (list/create/update/delete records)
+5. Verify the result by re-reading if needed
+
+## Field Types
+
+| Type | API Value | Example Data |
+|------|-----------|-------------|
+| Text | 1 | `"Hello"` |
+| Number | 2 | `123.45` |
+| SingleSelect | 3 | `"选项名"` |
+| MultiSelect | 4 | `["A", "B"]` |
+| DateTime | 5 | Unix timestamp in ms: `1700000000000` |
+| Checkbox | 7 | `true` / `false` |
+| User | 11 | `[{"id": "ou_xxx"}]` |
+| URL | 15 | `"https://..."` |
+| Formula | 20 | Read-only, computed |
+
+## Error Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 1254003 | WrongBaseToken | Check app-token format |
+| 1254004 | WrongTableId | Verify table-id exists via `list-tables` |
+| 1254041 | TableIdNotFound | Table does not exist |
+| 1254043 | RecordIdNotFound | Record does not exist |
+| 403 | Forbidden | App needs to be added as bitable collaborator with edit permission |
+
+## Collaboration with Other Skills
+
+- **File operations** (move/delete bitable): Use `feishu_drive` instead
+- **Sharing/permissions**: Use `feishu_perm` instead
+- **Wiki navigation**: Use `feishu_wiki` to discover file type from /wiki/ URLs when ambiguous
+- **Spreadsheets**: If user mentions 单元格/cell/行列/row/column/A1, use `feishu-sheets` instead
+- **Documents**: If user wants to edit text/paragraphs, use `feishu_doc` instead
+
+## Notes
+
+- Max 100 records per batch request
+- Field names must exactly match the column names in the bitable
+- DateTime fields use Unix timestamps in milliseconds
+- Formula fields are read-only

package/skills/feishu-bitable/src/_meta.json

@@ -0,0 +1,6 @@
+{
+  "ownerId": "kn79529g0cetfnymbs3ev6dtkx80n1ax",
+  "slug": "feishu-api-bitable",
+  "version": "1.0.0",
+  "publishedAt": 1770346670898
+}

package/skills/feishu-bitable/src/api.js

@@ -0,0 +1,381 @@
+/**
+ * 飞书多维表格API客户端
+ */
+
+const axios = require('axios');
+const { getEnvVar, getAccessToken, validateRequired, parseJsonInput, delay } = require('./utils');
+
+class FeishuBitableAPI {
+  constructor(options = {}) {
+    this.appId = options.appId || getEnvVar('FEISHU_APP_ID');
+    this.appSecret = options.appSecret || getEnvVar('FEISHU_APP_SECRET') || getEnvVar('FEISHU_APP_SECRET_PATH');
+    this.baseURL = options.baseURL || 'https://open.feishu.cn/open-apis/bitable/v1';
+    this.accessToken = options.accessToken;
+    this.autoRefreshToken = options.autoRefreshToken !== false;
+    
+    if (!this.appId || !this.appSecret) {
+      throw new Error('缺少FEISHU_APP_ID或FEISHU_APP_SECRET环境变量');
+    }
+    
+    this.client = axios.create({
+      baseURL: this.baseURL,
+      timeout: 30000,
+      headers: {
+        'Content-Type': 'application/json; charset=utf-8'
+      }
+    });
+    
+    // 请求拦截器：添加认证头
+    this.client.interceptors.request.use(async (config) => {
+      if (!this.accessToken) {
+        await this.refreshAccessToken();
+      }
+      
+      config.headers.Authorization = `Bearer ${this.accessToken}`;
+      return config;
+    });
+    
+    // 响应拦截器：处理token过期
+    this.client.interceptors.response.use(
+      (response) => response,
+      async (error) => {
+        const originalRequest = error.config;
+        
+        // 如果是token过期错误且未重试过
+        if (error.response && error.response.status === 99991663 && !originalRequest._retry && this.autoRefreshToken) {
+          originalRequest._retry = true;
+          
+          try {
+            await this.refreshAccessToken();
+            originalRequest.headers.Authorization = `Bearer ${this.accessToken}`;
+            return this.client(originalRequest);
+          } catch (refreshError) {
+            return Promise.reject(refreshError);
+          }
+        }
+        
+        return Promise.reject(error);
+      }
+    );
+  }
+  
+  /**
+   * 刷新访问令牌
+   */
+  async refreshAccessToken() {
+    try {
+      this.accessToken = await getAccessToken(this.appId, this.appSecret);
+      return this.accessToken;
+    } catch (error) {
+      throw new Error(`刷新访问令牌失败: ${error.message}`);
+    }
+  }
+  
+  /**
+   * 获取应用信息
+   */
+  async getApp(appToken) {
+    validateRequired({ appToken }, ['appToken']);
+    
+    try {
+      const response = await this.client.get(`/apps/${appToken}`);
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '获取应用信息');
+    }
+  }
+  
+  /**
+   * 获取数据表列表
+   */
+  async listTables(appToken, params = {}) {
+    validateRequired({ appToken }, ['appToken']);
+    
+    try {
+      const response = await this.client.get(`/apps/${appToken}/tables`, { params });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '获取数据表列表');
+    }
+  }
+  
+  /**
+   * 创建数据表
+   */
+  async createTable(appToken, tableData) {
+    validateRequired({ appToken }, ['appToken']);
+    
+    try {
+      const response = await this.client.post(`/apps/${appToken}/tables`, tableData);
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '创建数据表');
+    }
+  }
+  
+  /**
+   * 获取数据表详情
+   */
+  async getTable(appToken, tableId) {
+    validateRequired({ appToken, tableId }, ['appToken', 'tableId']);
+    
+    try {
+      const response = await this.client.get(`/apps/${appToken}/tables/${tableId}`);
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '获取数据表详情');
+    }
+  }
+  
+  /**
+   * 删除数据表
+   */
+  async deleteTable(appToken, tableId) {
+    validateRequired({ appToken, tableId }, ['appToken', 'tableId']);
+    
+    try {
+      const response = await this.client.delete(`/apps/${appToken}/tables/${tableId}`);
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '删除数据表');
+    }
+  }
+  
+  /**
+   * 获取字段列表
+   */
+  async listFields(appToken, tableId, params = {}) {
+    validateRequired({ appToken, tableId }, ['appToken', 'tableId']);
+    
+    try {
+      const response = await this.client.get(`/apps/${appToken}/tables/${tableId}/fields`, { params });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '获取字段列表');
+    }
+  }
+  
+  /**
+   * 创建字段
+   */
+  async createField(appToken, tableId, fieldData) {
+    validateRequired({ appToken, tableId }, ['appToken', 'tableId']);
+    
+    try {
+      const response = await this.client.post(`/apps/${appToken}/tables/${tableId}/fields`, fieldData);
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '创建字段');
+    }
+  }
+  
+  /**
+   * 更新字段
+   */
+  async updateField(appToken, tableId, fieldId, fieldData) {
+    validateRequired({ appToken, tableId, fieldId }, ['appToken', 'tableId', 'fieldId']);
+    
+    try {
+      const response = await this.client.put(`/apps/${appToken}/tables/${tableId}/fields/${fieldId}`, fieldData);
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '更新字段');
+    }
+  }
+  
+  /**
+   * 获取记录列表
+   */
+  async listRecords(appToken, tableId, params = {}) {
+    validateRequired({ appToken, tableId }, ['appToken', 'tableId']);
+    
+    try {
+      const response = await this.client.get(`/apps/${appToken}/tables/${tableId}/records`, { params });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '获取记录列表');
+    }
+  }
+  
+  /**
+   * 创建记录
+   */
+  async createRecord(appToken, tableId, recordData) {
+    validateRequired({ appToken, tableId }, ['appToken', 'tableId']);
+    
+    try {
+      const response = await this.client.post(`/apps/${appToken}/tables/${tableId}/records`, {
+        fields: recordData
+      });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '创建记录');
+    }
+  }
+  
+  /**
+   * 批量创建记录
+   */
+  async batchCreateRecords(appToken, tableId, records) {
+    validateRequired({ appToken, tableId }, ['appToken', 'tableId']);
+    
+    try {
+      const response = await this.client.post(`/apps/${appToken}/tables/${tableId}/records/batch_create`, {
+        records: records.map(record => ({ fields: record }))
+      });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '批量创建记录');
+    }
+  }
+  
+  /**
+   * 获取记录详情
+   */
+  async getRecord(appToken, tableId, recordId) {
+    validateRequired({ appToken, tableId, recordId }, ['appToken', 'tableId', 'recordId']);
+    
+    try {
+      const response = await this.client.get(`/apps/${appToken}/tables/${tableId}/records/${recordId}`);
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '获取记录详情');
+    }
+  }
+  
+  /**
+   * 更新记录
+   */
+  async updateRecord(appToken, tableId, recordId, recordData) {
+    validateRequired({ appToken, tableId, recordId }, ['appToken', 'tableId', 'recordId']);
+    
+    try {
+      const response = await this.client.put(`/apps/${appToken}/tables/${tableId}/records/${recordId}`, {
+        fields: recordData
+      });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '更新记录');
+    }
+  }
+  
+  /**
+   * 批量更新记录
+   */
+  async batchUpdateRecords(appToken, tableId, records) {
+    validateRequired({ appToken, tableId }, ['appToken', 'tableId']);
+    
+    try {
+      const response = await this.client.post(`/apps/${appToken}/tables/${tableId}/records/batch_update`, {
+        records: records.map(record => ({
+          record_id: record.record_id,
+          fields: record.fields
+        }))
+      });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '批量更新记录');
+    }
+  }
+  
+  /**
+   * 删除记录
+   */
+  async deleteRecord(appToken, tableId, recordId) {
+    validateRequired({ appToken, tableId, recordId }, ['appToken', 'tableId', 'recordId']);
+    
+    try {
+      const response = await this.client.delete(`/apps/${appToken}/tables/${tableId}/records/${recordId}`);
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '删除记录');
+    }
+  }
+  
+  /**
+   * 批量删除记录
+   */
+  async batchDeleteRecords(appToken, tableId, recordIds) {
+    validateRequired({ appToken, tableId }, ['appToken', 'tableId']);
+    
+    try {
+      const response = await this.client.post(`/apps/${appToken}/tables/${tableId}/records/batch_delete`, {
+        records: recordIds.map(recordId => ({ record_id: recordId }))
+      });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '批量删除记录');
+    }
+  }
+  
+  /**
+   * 获取视图列表
+   */
+  async listViews(appToken, tableId, params = {}) {
+    validateRequired({ appToken, tableId }, ['appToken', 'tableId']);
+    
+    try {
+      const response = await this.client.get(`/apps/${appToken}/tables/${tableId}/views`, { params });
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '获取视图列表');
+    }
+  }
+  
+  /**
+   * 获取视图详情
+   */
+  async getView(appToken, tableId, viewId) {
+    validateRequired({ appToken, tableId, viewId }, ['appToken', 'tableId', 'viewId']);
+    
+    try {
+      const response = await this.client.get(`/apps/${appToken}/tables/${tableId}/views/${viewId}`);
+      return response.data;
+    } catch (error) {
+      throw this.handleError(error, '获取视图详情');
+    }
+  }
+  
+  /**
+   * 错误处理
+   */
+  handleError(error, operation) {
+    if (error.response) {
+      const { status, data } = error.response;
+      const errorMsg = data.msg || data.message || error.message;
+      
+      const fullError = new Error(`${operation}失败: ${errorMsg} (状态码: ${status})`);
+      fullError.status = status;
+      fullError.data = data;
+      
+      return fullError;
+    } else if (error.request) {
+      return new Error(`${operation}失败: 网络错误，无法连接到飞书服务器`);
+    } else {
+      return new Error(`${operation}失败: ${error.message}`);
+    }
+  }
+  
+  /**
+   * 测试连接
+   */
+  async testConnection() {
+    try {
+      await this.refreshAccessToken();
+      return {
+        success: true,
+        message: '连接测试成功',
+        appId: this.appId,
+        tokenValid: !!this.accessToken
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: `连接测试失败: ${error.message}`,
+        appId: this.appId
+      };
+    }
+  }
+}
+
+module.exports = FeishuBitableAPI;