sync-sdk-skill

同步 SDK 技能

将 skills/base44-sdk/ 技能与 Base44 SDK 仓库中的最新 SDK 源代码同步。

用法

激活后，此命令会询问：

1. SDK 源文件夹路径（必填）- Base44 SDK 源代码的本地路径
2. 文档 URL（可选）- 用于获取更多文档的 URL

步骤

第 1 步：收集输入

如果有 AskQuestion 工具，请使用该工具向用户询问必需的输入；否则以对话方式询问：

必填：

• SDK 源文件夹路径（例如，~/projects/base44-sdk 或 /Users/me/base44-sdk）

可选：

• 文档 URL（例如，https://docs.base44.com/sdk）

如果用户已在初始提示中提供这些信息，请使用相应值。

第 2 步：验证源文件夹

1. 检查所提供的路径是否存在且包含 SDK 源代码
2. 查找以下关键标识：
   • 包含 @base44/sdk 或类似 SDK 相关内容的 package.json
   • 包含模块实现的 src/ 目录
   • 包含 SDK 模块导出的 TypeScript/JavaScript 文件（例如，entities.ts、auth.ts、client.ts）

如果验证失败，请让用户检查路径。

第 3 步：发现 SDK 模块

扫描 SDK 源文件夹，查找所有可用模块。查找以下内容：

1. 模块文件，位于以下目录等位置：

   • src/
   • src/modules/
   • lib/

2. 对于每个模块，提取：

   • 模块名称和导出项
   • 可用方法及其签名
   • 方法参数和类型
   • 返回类型
   • 用法示例（如果源代码或 JSDoc 中存在）
   • 子模块（例如，integrations.Core、integrations.custom）

3. 从以下内容解析模块定义：

   • TypeScript 接口和类型
   • 类定义和方法
   • JSDoc 注释和注解
   • 导出语句

4. 需要查找的关键模块：

   • entities - 对数据模型执行 CRUD 操作
   • auth - 登录、注册、用户管理
   • agents - AI 对话和消息
   • functions - 调用后端函数
   • integrations - AI、电子邮件、文件上传、自定义 API
   • connectors - OAuth 令牌（仅限服务角色）
   • analytics - 跟踪自定义事件
   • appLogs - 记录用户活动
   • users - 用户邀请
   • client - 创建和配置客户端

第 4 步：阅读现有技能

阅读当前技能文件，了解需要更新的内容：

skills/base44-sdk/
├── SKILL.md
└── references/
    ├── analytics.md
    ├── app-logs.md
    ├── auth.md
    ├── base44-agents.md
    ├── client.md
    ├── connectors.md
    ├── entities.md
    ├── functions.md
    ├── integrations.md
    └── users.md

第 5 步：比较并确定变更

将发现的 SDK 模块与现有技能文档进行比较：

1. 新模块：源代码中存在，但技能引用中没有的模块
2. 新方法：添加到现有模块中的方法
3. 已更新的方法：签名、参数或返回类型发生变化的方法
4. 已弃用的方法：标记为已弃用的方法
5. 已移除的方法：技能中存在但源代码中没有的方法（移除前请先确认）
6. 新参数：添加到现有方法中的新选项

在应用变更前，创建变更摘要并向用户展示。

第 6 步：获取外部文档（可选）

如果提供了文档 URL：

1. 获取文档页面
2. 提取相关的模块和方法文档
3. 使用这些内容补充源代码中的信息
4. 交叉参考以确保准确性

第 7 步：更新技能文件

对于确定的每项变更：

更新参考文件

对于每个模块，更新或创建 references/{module-name}.md：

# {ModuleName} Module

{Description from source}

## Overview

{Brief explanation of what the module does}

## Methods

### `{methodName}(params)`

{Method description}

**Parameters:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| `param1` | `string` | {description} | Yes |
| `options` | `object` | {description} | No |

**Returns:** `Promise<{ReturnType}>`

**Example:**

```javascript
const result = await base44.{module}.{methodName}({
  param1: "value"
});

注意事项

{任何重要的行为说明、前端/后端可用性等}

#### Update SKILL.md

1. Update the **SDK Modules** table if modules changed
2. Update **Quick Start** if core patterns changed
3. Update **Module Selection** section with new capabilities
4. Update **Common Patterns** with new usage examples
5. Update **Frontend vs Backend** table if availability changed
6. Keep the existing structure and formatting
7. Do NOT change the frontmatter description unless explicitly asked

### Step 8: Present Summary

After updates, present a summary to the user:

同步摘要

已更新的文件

• references/new-module.md（已创建）
• references/entities.md（已更新方法）
• SKILL.md（已更新模块表格）

所做的变更

• 添加了新模块：newModule
• 更新了 entities 模块：添加了 bulkCreate() 方法
• 为 auth.me() 添加了新参数 options.cache
• 弃用了 integrations.legacyMethod()

建议手动审查

• [列出需要验证的变更]

## Important Notes

- **Preserve existing content**: Don't remove detailed explanations, examples, or warnings unless they're outdated
- **Keep formatting consistent**: Match the existing style of SKILL.md and reference files
- **Maintain progressive disclosure**: Keep detailed docs in references, summaries in SKILL.md
- **Flag uncertainties**: If source code is unclear, flag it for manual review
- **Document frontend/backend availability**: Always note if a method is backend-only (e.g., `connectors`, `asServiceRole`)
- **Preserve type information**: Include TypeScript types in method signatures
- **Keep examples practical**: Examples should reflect real-world usage patterns

## Module-Specific Guidelines

### entities.md
- Document CRUD methods: `create`, `get`, `list`, `filter`, `update`, `delete`
- Include query filter syntax and operators
- Document `subscribe()` for real-time updates
- Note RLS/FLS security implications if applicable

### auth.md
- Cover all authentication methods (email/password, OAuth, etc.)
- Document `me()`, `updateMe()`, `logout()`
- Include redirect flow examples
- Note token handling

### integrations.md
- Document `Core` submodule methods (InvokeLLM, SendEmail, UploadFile, GenerateImage)
- Document `custom.call()` for custom integrations
- Include AI prompt examples

### connectors.md
- Note this is service role / backend only
- Document `getAccessToken()` for OAuth providers

### functions.md
- Show both frontend invocation and backend implementation
- Include `createClientFromRequest()` usage
- Document `asServiceRole` access patterns

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Can't find module files | Try searching for `export class` or `export function` patterns |
| Types not detected | Look for `.d.ts` files or inline TypeScript annotations |
| Missing method descriptions | Check for JSDoc comments (`/** ... */`) above methods |
| Submodule structure | Modules like `integrations.Core` may be in nested files |
| Return types unclear | Check TypeScript generics and Promise wrappers |