@waoooo/claude-skills 1.0.0

package/skills/api-docs-generate/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: api-docs-generate
+description: 从后端代码和 OpenAPI 规范自动生成 API 文档（api-reference/*.mdx），包含端点定义、请求参数、响应格式、使用示例等
+version: 0.1.0
+---
+
+# Skill: api-docs-generate
+
+## 功能
+
+从后端代码注释和 OpenAPI 规范自动生成 API 文档，输出到 waoooo-docs 的 api-reference 目录。
+
+## 何时调用
+
+- API 开发完成后，需要生成 API 文档
+- API 更新后，需要更新文档
+- 用户说："生成 API 文档"、"更新 API 文档"
+
+## 输入
+
+- `backendPath` - 后端代码路径
+- `endpoint` - API 端点（如 `/api/pricing/plans`）
+- `openApiPath` - OpenAPI 规范文件路径（可选）
+
+## 输出
+
+- `waoooo-docs/developer-docs/api-reference/rest-api/endpoints/<endpoint-name>.mdx`
+
+## 执行步骤
+
+### 1. 分析后端代码
+
+```bash
+# 扫描 FastAPI 路由
+- 查找 @router.get/post/put/delete 装饰器
+- 提取路径参数、查询参数、请求体
+- 提取响应模型
+- 提取文档字符串
+```
+
+### 2. 读取 OpenAPI 规范（如果有）
+
+```bash
+# 读取 OpenAPI JSON/YAML
+- 提取端点定义
+- 提取参数说明
+- 提取响应示例
+- 提取错误码
+```
+
+### 3. 生成文档
+
+```bash
+# 使用模板生成
+npx tsx .claude/skills/api-docs-generate/scripts/generate-api-docs.ts \
+  --backend-path <path> \
+  --endpoint <endpoint> \
+  --openapi-path <path>
+```
+
+### 4. 验证输出
+
+- 检查文档是否生成
+- 检查参数说明是否完整
+- 检查代码示例是否正确
+
+## 使用示例
+
+### 示例 1：生成单个端点文档
+
+```
+用户: "生成 /api/pricing/plans 的 API 文档"
+
+Agent 行动:
+1. 扫描后端代码: waoooo-service/api/routers/pricing.py
+2. 提取端点信息
+3. 生成文档: api-reference/rest-api/endpoints/get-pricing-plans.mdx
+4. 显示结果
+```
+
+### 示例 2：批量生成 API 文档
+
+```
+用户: "生成所有 pricing API 文档"
+
+Agent 行动:
+1. 扫描 pricing 路由: waoooo-service/api/routers/pricing.py
+2. 找到所有端点（5个）
+3. 逐个生成文档
+4. 显示结果列表
+```
+
+### 示例 3：从 OpenAPI 规范生成
+
+```
+用户: "从 OpenAPI 规范生成 API 文档"
+
+Agent 行动:
+1. 读取 OpenAPI 文件: openapi.json
+2. 提取所有端点
+3. 批量生成文档
+4. 显示结果
+```
+
+## 文档结构
+
+生成的文档包含以下章节：
+
+1. **端点定义** - 方法、路径、描述
+2. **认证要求** - 是否需要认证、权限要求
+3. **请求参数** - Path/Query/Body 参数说明
+4. **请求示例** - cURL、JavaScript、Python 示例
+5. **响应格式** - 成功响应、错误响应
+6. **错误码** - 可能的错误码和说明
+7. **相关端点** - 链接到相关 API
+
+## 模板文件
+
+- `assets/templates/api.mdx` - API 文档模板（**使用 Mintlify 标准 API 格式**）
+
+<Note>
+**重要：使用 Mintlify 标准 API 格式**
+
+生成的 API 文档必须遵循 Mintlify 的标准 API 格式：
+
+1. **Frontmatter 格式**：
+   ```yaml
+   ---
+   title: 'API 端点标题'
+   api: 'HTTP方法 /api/v1/路径'
+   description: '一句话描述'
+   ---
+   ```
+
+2. **参数定义**：
+   - 使用 `<ParamField>` 组件（不是 `<Param>`）
+   - 支持 `header`、`path`、`query`、`body` 类型
+   - 示例：`<ParamField path="id" type="string" required>`
+
+3. **响应定义**：
+   - 使用 `<ResponseField>` 组件
+   - 示例：`<ResponseField name="data" type="object" required>`
+
+4. **代码示例**：
+   - 使用 `<RequestExample>` 和 `<ResponseExample>` 包裹
+   - 支持多语言：cURL、TypeScript、Python
+
+5. **提示组件**：
+   - `<Note>` - 一般说明
+   - `<Tip>` - 最佳实践
+   - `<Warning>` - 注意事项
+
+参考示例：`waoooo-docs/developer-docs/api-reference/rest-api/endpoints/auth-revoke-session.mdx`
+</Note>
+
+## 错误处理
+
+### 错误 1：后端代码不存在
+
+```
+❌ 错误: 后端代码文件不存在
+📁 路径: waoooo-service/api/routers/pricing.py
+
+💡 建议:
+1. 检查后端代码路径是否正确
+2. 确认 API 已实现
+3. 检查文件名是否正确
+```
+
+### 错误 2：端点未找到
+
+```
+❌ 错误: 端点未找到
+🔍 端点: /api/pricing/plans
+
+💡 建议:
+1. 检查端点路径是否正确
+2. 确认 API 已实现
+3. 查看所有可用端点列表
+```
+
+### 错误 3：OpenAPI 规范格式错误
+
+```
+❌ 错误: OpenAPI 规范解析失败
+📁 文件: openapi.json
+
+💡 建议:
+1. 检查 JSON/YAML 格式是否正确
+2. 使用 OpenAPI 验证工具验证
+3. 重新生成 OpenAPI 规范
+```
+
+## 注意事项
+
+1. **文档与代码同步** - 生成的文档应该反映实际 API 实现
+2. **参数说明完整** - 确保所有参数都有清晰的说明
+3. **示例可运行** - 提供的代码示例应该可以直接运行
+4. **错误码准确** - 列出所有可能的错误码和场景
+
+## 相关 Skills
+
+- `capability-docs-generate` - 生成能力文档
+- `spec-generate` - 生成开发规范

package/skills/api-docs-generate/assets/templates/api.mdx

@@ -0,0 +1,140 @@
+---
+title: '[API 端点标题]'
+api: 'HTTP方法 /api/v1/[路径]'
+description: '[一句话描述端点功能]'
+---
+
+[详细描述端点功能和用途，说明该端点的作用、适用场景等]
+
+<Note>
+  此端点**需要认证**，必须提供有效的 Bearer Token（JWT）。
+</Note>
+
+## 认证
+
+<ParamField header="Authorization" type="string" required>
+  Bearer Token（JWT），从用户登录后获取
+</ParamField>
+
+## 路径参数
+
+<ParamField path="[参数名]" type="string" required>
+  [参数说明]
+</ParamField>
+
+## 查询参数
+
+<ParamField query="[参数名]" type="string" default="[默认值]">
+  [参数说明]
+</ParamField>
+
+## 请求体
+
+<ParamField body="[字段名]" type="string" required>
+  [字段说明]
+</ParamField>
+
+## Response
+
+<ResponseField name="success" type="boolean" required>
+  请求是否成功
+</ResponseField>
+
+<ResponseField name="data" type="object" required>
+  响应数据对象
+</ResponseField>
+
+<ResponseField name="error" type="object">
+  错误信息（仅在失败时返回）
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST "https://api.waoooo.com/api/v1/[路径]" \
+  -H "Authorization: Bearer <your_access_token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "[字段名]": "[值]"
+  }'
+```
+
+```typescript TypeScript
+const response = await fetch(
+  'https://api.waoooo.com/api/v1/[路径]',
+  {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${accessToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      [字段名]: '[值]',
+    }),
+  }
+);
+
+const data = await response.json();
+console.log(data);
+```
+
+```python Python
+import requests
+
+response = requests.post(
+    'https://api.waoooo.com/api/v1/[路径]',
+    headers={'Authorization': f'Bearer {access_token}'},
+    json={'[字段名]': '[值]'}
+)
+
+data = response.json()
+print(data)
+```
+</RequestExample>
+
+<ResponseExample>
+```json 成功响应
+{
+  "success": true,
+  "data": {
+    "id": "880e8400-e29b-41d4-a716-446655440001",
+    "[字段名]": "[值]"
+  }
+}
+```
+
+```json 错误响应 (400)
+{
+  "success": false,
+  "error": {
+    "code": "[错误码]",
+    "message": "[错误描述]"
+  }
+}
+```
+
+```json 未授权 (401)
+{
+  "detail": "Session revoked"
+}
+```
+</ResponseExample>
+
+## 使用场景
+
+### 1. [场景标题]
+
+[场景描述]
+
+## 最佳实践
+
+<Tip>
+**[实践标题]**：[实践说明]
+</Tip>
+
+<Note>
+**[建议标题]**：[建议说明]
+</Note>
+
+<Warning>
+**[注意事项标题]**：[注意事项说明]
+</Warning>

package/skills/api-docs-generate/scripts/generate-api-docs.ts

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+/**
+ * Generate API Documentation from Backend Code
+ * 
+ * This script generates API endpoint documentation by:
+ * 1. Analyzing FastAPI router code
+ * 2. Extracting endpoint metadata (path, method, params, response)
+ * 3. Filling the api.mdx template with extracted data
+ * 4. Outputting to waoooo-docs/developer-docs/api-reference/endpoints/<endpoint>.mdx
+ * 5. Updating mint.json navigation
+ * 
+ * Usage:
+ *   npx tsx generate-api-docs.ts \
+ *     --code <backend-code-path> \
+ *     --endpoint <endpoint-name>
+ * 
+ * Example:
+ *   npx tsx generate-api-docs.ts \
+ *     --code ../../../../../../waoooo-service/app/api/routers/payment.py \
+ *     --endpoint create-payment
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface APIEndpointData {
+  title: string;
+  method: string;
+  path: string;
+  description: string;
+  requiresAuth: boolean;
+  pathParams: Array<{ name: string; type: string; description: string; required: boolean }>;
+  queryParams: Array<{ name: string; type: string; description: string; default?: string }>;
+  bodyParams: Array<{ name: string; type: string; description: string; required: boolean }>;
+  responseFields: Array<{ name: string; type: string; description: string; required: boolean }>;
+  errorCodes: Array<{ code: string; status: number; description: string }>;
+  examples: {
+    request: string;
+    response: string;
+  };
+}
+
+// ============================================================================
+// CLI Arguments Parsing
+// ============================================================================
+
+function parseArgs(): {
+  codePath: string;
+  endpointName: string;
+} {
+  const args = process.argv.slice(2);
+  const result: any = {};
+
+  for (let i = 0; i < args.length; i += 2) {
+    const key = args[i].replace('--', '');
+    const value = args[i + 1];
+    result[key] = value;
+  }
+
+  if (!result.code || !result.endpoint) {
+    console.error('❌ Missing required arguments');
+    console.error('Usage: generate-api-docs.ts --code <path> --endpoint <name>');
+    process.exit(1);
+  }
+
+  return {
+    codePath: result.code,
+    endpointName: result.endpoint,
+  };
+}
+
+// ============================================================================
+// Code Analysis (FastAPI)
+// ============================================================================
+
+function analyzeEndpoint(codePath: string, endpointName: string): Partial<APIEndpointData> {
+  if (!fs.existsSync(codePath)) {
+    throw new Error(`Code file not found: ${codePath}`);
+  }
+
+  const code = fs.readFileSync(codePath, 'utf-8');
+
+  // Extract endpoint decorator (e.g., @router.post("/payment"))
+  const decoratorRegex = /@router\.(get|post|put|delete|patch)\s*\(\s*["']([^"']+)["']/g;
+  const matches = [...code.matchAll(decoratorRegex)];
+
+  // Find matching endpoint
+  let method = 'POST';
+  let apiPath = '/api/v1/unknown';
+  let description = '';
+
+  for (const match of matches) {
+    if (match[2].includes(endpointName) || endpointName.includes(match[2].replace(/[\/\{\}]/g, '-'))) {
+      method = match[1].toUpperCase();
+      apiPath = `/api/v1${match[2]}`;
+      break;
+    }
+  }
+
+  // Extract docstring
+  const docstringMatch = code.match(/"""([\s\S]*?)"""/);
+  if (docstringMatch) {
+    description = docstringMatch[1].trim().split('\n')[0];
+  }
+
+  // Extract Pydantic models for request/response
+  const modelRegex = /class\s+(\w+)\(BaseModel\):([\s\S]*?)(?=\nclass|\n@|\Z)/g;
+  const models = [...code.matchAll(modelRegex)];
+
+  const bodyParams: any[] = [];
+  const responseFields: any[] = [];
+
+  for (const model of models) {
+    const modelName = model[1];
+    const modelBody = model[2];
+
+    // Extract fields
+    const fieldRegex = /(\w+):\s*([\w\[\]]+)(?:\s*=\s*Field\((.*?)\))?/g;
+    const fields = [...modelBody.matchAll(fieldRegex)];
+
+    for (const field of fields) {
+      const fieldData = {
+        name: field[1],
+        type: field[2].replace('Optional[', '').replace(']', ''),
+        description: field[3] ? field[3].match(/description=["']([^"']+)["']/)?.[1] || '' : '',
+        required: !field[2].includes('Optional'),
+      };
+
+      // Heuristic: if model name contains "Request" or "Create", it's a body param
+      if (modelName.includes('Request') || modelName.includes('Create')) {
+        bodyParams.push(fieldData);
+      } else if (modelName.includes('Response') || modelName.includes('Result')) {
+        responseFields.push(fieldData);
+      }
+    }
+  }
+
+  return {
+    title: endpointName.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' '),
+    method,
+    path: apiPath,
+    description: description || `${endpointName} endpoint`,
+    requiresAuth: code.includes('Depends(get_current_user)') || code.includes('Depends(verify_token)'),
+    bodyParams,
+    responseFields,
+  };
+}
+
+// ============================================================================
+// Template Filling
+// ============================================================================
+
+function fillTemplate(data: APIEndpointData): string {
+  const templatePath = path.join(__dirname, '../assets/templates/api.mdx');
+  let template = fs.readFileSync(templatePath, 'utf-8');
+
+  // Replace basic info
+  template = template.replace(/\[API 端点标题\]/g, data.title);
+  template = template.replace(/HTTP方法/g, data.method);
+  template = template.replace(/\/api\/v1\/\[路径\]/g, data.path);
+  template = template.replace(/\[一句话描述端点功能\]/g, data.description);
+
+  // Replace body params
+  if (data.bodyParams.length > 0) {
+    const bodyParamsText = data.bodyParams
+      .map(
+        p => `<ParamField body="${p.name}" type="${p.type}" ${p.required ? 'required' : ''}>
+  ${p.description}
+</ParamField>`
+      )
+      .join('\n\n');
+    template = template.replace(
+      /<ParamField body="\[字段名\]"[\s\S]*?<\/ParamField>[\s\S]*?<ParamField body="\[字段名\]"[\s\S]*?<\/Expandable>\s*<\/ParamField>/m,
+      bodyParamsText
+    );
+  }
+
+  // Replace response fields
+  if (data.responseFields.length > 0) {
+    const responseFieldsText = data.responseFields
+      .map(
+        f => `    <ResponseField name="${f.name}" type="${f.type}" ${f.required ? 'required' : ''}>
+      ${f.description}
+    </ResponseField>`
+      )
+      .join('\n\n');
+    template = template.replace(
+      /<ResponseField name="id"[\s\S]*?<ResponseField name="created_at"[\s\S]*?<\/ResponseField>/m,
+      responseFieldsText
+    );
+  }
+
+  // Update last updated date
+  const today = new Date().toISOString().split('T')[0];
+  template = template.replace(/\*\*最后更新\*\*：\d{4}-\d{2}-\d{2}/, `**最后更新**：${today}`);
+
+  return template;
+}
+
+// ============================================================================
+// Update mint.json (using universal utility)
+// ============================================================================
+
+function updateMintJson(endpointName: string, docsPath: string) {
+  const projectRoot = path.resolve(__dirname, '../../../../../');
+
+  // Calculate relative path
+  const relativePath = path.relative(
+    path.join(projectRoot, 'waoooo-docs'),
+    docsPath
+  ).replace(/\.mdx$/, '');
+
+  // Call universal update-mint-nav utility
+  const updateScript = path.join(__dirname, '../../../../src/scripts/update-mint-nav.ts');
+  const { execSync } = require('child_process');
+
+  try {
+    execSync(
+      `npx tsx "${updateScript}" --section "API Reference" --group "Endpoints" --page "${relativePath}"`,
+      { stdio: 'inherit' }
+    );
+  } catch (error) {
+    console.warn('⚠️  Failed to update mint.json');
+  }
+}
+  } catch (error) {
+    console.warn('⚠️  Failed to update mint.json');
+  }
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  console.log('🚀 Generating API Documentation...\n');
+
+  const { codePath, endpointName } = parseArgs();
+
+  console.log('📥 Input:');
+  console.log(`  - Code: ${codePath}`);
+  console.log(`  - Endpoint: ${endpointName}\n`);
+
+  // Step 1: Analyze code
+  console.log('🔍 Step 1/4: Analyzing endpoint code...');
+  const endpointData = analyzeEndpoint(codePath, endpointName);
+  console.log('✅ Endpoint analyzed\n');
+
+  // Step 2: Fill template
+  console.log('📝 Step 2/4: Generating documentation...');
+  const apiData: APIEndpointData = {
+    title: endpointData.title || endpointName,
+    method: endpointData.method || 'POST',
+    path: endpointData.path || '/api/v1/unknown',
+    description: endpointData.description || '',
+    requiresAuth: endpointData.requiresAuth ?? true,
+    pathParams: endpointData.pathParams || [],
+    queryParams: endpointData.queryParams || [],
+    bodyParams: endpointData.bodyParams || [],
+    responseFields: endpointData.responseFields || [],
+    errorCodes: endpointData.errorCodes || [],
+    examples: endpointData.examples || { request: '', response: '' },
+  };
+
+  const output = fillTemplate(apiData);
+  console.log('✅ Documentation generated\n');
+
+  // Step 3: Write output
+  console.log('💾 Step 3/4: Writing file...');
+  const projectRoot = path.resolve(__dirname, '../../../../../');
+  const docsPath = path.join(
+    projectRoot,
+    'waoooo-docs/developer-docs/api-reference/endpoints',
+    `${endpointName}.mdx`
+  );
+
+  fs.mkdirSync(path.dirname(docsPath), { recursive: true });
+  fs.writeFileSync(docsPath, output, 'utf-8');
+  console.log('✅ File written\n');
+
+  // Step 4: Update mint.json
+  console.log('🔧 Step 4/4: Updating mint.json...');
+  updateMintJson(endpointName, docsPath);
+  console.log('');
+
+  console.log('📂 Output:');
+  console.log(`  ${docsPath}\n`);
+
+  console.log('🎉 Done!');
+  console.log('\n💡 Next steps:');
+  console.log('  1. Review the generated documentation');
+  console.log('  2. Fill in missing sections (examples, error codes, etc.)');
+  console.log('  3. Test the API endpoint');
+  console.log('  4. Commit the changes');
+}
+
+main().catch(error => {
+  console.error('❌ Error:', error.message);
+  process.exit(1);
+});

package/skills/ask/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ask
+description: Async via ask, end turn immediately; use when user explicitly delegates to any AI provider (gemini/codex/opencode/droid); NOT for questions about the providers themselves.
+metadata:
+  short-description: Ask AI provider asynchronously
+---
+
+# Ask AI Provider (Async)
+
+Send the user's request to specified AI provider asynchronously.
+
+## Usage
+
+The first argument must be the provider name, followed by the message:
+- `gemini` - Send to Gemini
+- `codex` - Send to Codex
+- `opencode` - Send to OpenCode
+- `droid` - Send to Droid
+
+## Execution (MANDATORY)
+
+```
+Bash(ask $PROVIDER "$MESSAGE")
+```
+
+## Rules
+
+- After running the command, say "[Provider] processing..." and immediately end your turn.
+- Do not wait for results or check status in the same turn.
+- The task ID and log file path will be displayed for tracking.
+
+## Examples
+
+- `/ask gemini What is 12+12?`
+- `/ask codex Refactor this code`
+- `/ask opencode Analyze this bug`
+- `/ask droid Execute this task`
+
+## Notes
+
+- `ask` already runs in background by default; no manual `nohup` is needed.
+- If it fails, check backend health with the corresponding ping command (`ping <provider>` (e.g., `ping gemini`)).