api-docs

我是 API 文档自动生成技能，专门从 xiaozhi-client 项目的源代码中提取 API 信息，生成符合 Nextra (Next.js) 标准的 MDX 文档，同时遵循务实开发理念。

技能使用原则

• 保持文档质量，但避免过度复杂：生成清晰有用的文档，但不追求完美的文档结构
• 实用功能优先，理论完美次之：解决实际的文档需求比完美的文档设计更重要
• 简单解决方案优于复杂方案：优先选择直接有效的文档生成方式
• 务实开发指导：评估文档的必要性，避免为了文档而文档

技能能力

1. 源代码分析

深度解析 TypeScript/JavaScript 源代码，提取 API 相关信息：

支持的代码元素

• 类和方法：使用 @Tool 装饰器的方法
• 函数接口：纯函数和工具方法
• 类型定义：接口、类型别名、枚举
• 参数信息：使用 @Param 装饰器的参数定义
• 注释文档：JSDoc 格式的代码注释

解析能力

// 示例源代码
@Tool("控制灯光设备 - 支持通过名称控制灯光设备的开关、亮度和色温")
public async LightControl(
  @Param(z.string().describe("灯光设备名称"))
  name: string,
  @Param(z.enum(["turn_on", "turn_off"]).describe("控制动作"))
  action: "turn_on" | "turn_off",
  @Param(z.number().min(1).max(100).optional().describe("亮度百分比"))
  brightnessPct?: number
) {
  // 实现逻辑...
}

// 提取的信息
{
  name: "LightControl",
  description: "控制灯光设备 - 支持通过名称控制灯光设备的开关、亮度和色温",
  parameters: [
    {
      name: "name",
      type: "string",
      description: "灯光设备名称",
      required: true
    },
    {
      name: "action",
      type: "turn_on | turn_off",
      description: "控制动作",
      required: true
    },
    {
      name: "brightnessPct",
      type: "number",
      description: "亮度百分比",
      required: false,
      constraints: { min: 1, max: 100 }
    }
  ]
}

2. MDX 文档生成

基于提取的信息生成符合 xiaozhi-client 项目标准的 Nextra MDX 文档。

文档结构模板

# {ToolName}

## 工具介绍

{工具描述}

## 参数定义

| 参数 | 类型 | 范围 | 说明 |
|------|------|------|------|
{参数表格}

## 使用示例

### 基础用法
{基础示例代码}

### 高级功能
{高级示例代码}

## 错误信息

| 错误类型 | 错误信息 | 处理建议 |
|----------|----------|----------|
{错误表格}

## 返回值格式

### 成功响应
{成功响应示例}

### 错误响应
{错误响应示例}

3. 类型信息集成

从类型定义文件中提取相关类型信息，增强文档的完整性。

类型文档化

// 源类型定义
export interface LightControlParams {
  entity_id: string;
  action: LightActionType;
  brightness?: number;
  transition?: number;
}

export type LightActionType = "turn_on" | "turn_off" | "toggle";

// 生成的类型文档
### LightControlParams
灯光控制参数接口

| 属性 | 类型 | 必需 | 说明 |
|------|------|------|------|
| entity_id | string | 是 | 灯光设备实体ID |
| action | LightActionType | 是 | 控制动作类型 |
| brightness | number | 否 | 亮度百分比 (1-100) |
| transition | number | 否 | 渐变时间(秒) |

### LightActionType
灯光控制动作类型

**可选值：**
- `"turn_on"` - 开灯
- `"turn_off"` - 关灯
- `"toggle"` - 切换开关状态