api-debug

name	api-debug
description	用 AI Access Key 认证查询 PrdAgent 真实 API 数据，辅助排查问题、核对数据状态、理解系统行为，产出可直接分析的 JSON 响应。触发词："查 API 数据"、"调试接口"、"看真实数据"、"api debug"、"verify data state"。

API 调试

版本：v1.0.0 | 状态：已落地 | 触发：/api-debug、"查 API 数据"、"调试接口"

Query the PrdAgent API using AI Access Key authentication to fetch real data for debugging and investigation.

何时用

This skill should be used when:

• Debugging issues that require checking actual data states
• Investigating user-reported problems
• Verifying API behavior or data consistency
• Understanding system state without guessing

Configuration

The API uses AI Access Key authentication:

• Environment Variables:
  • AI_ACCESS_KEY - 通用 AI 认证密钥（CDS + MAP 平台 + 后端 API 共享）
  • MAP_AI_USER - X-AI-Impersonate 用户名（优先级最高，强烈建议配置）
• Request Headers:
  • X-AI-Access-Key: {key} - The configured access key
  • X-AI-Impersonate: {username} - A valid username to impersonate (must exist in database)

警告：严禁硬编码 admin 或 root。admin 通常不是数据库真实用户名，root 是破窗账户不在 users 集合中。 强烈建议：从 $MAP_AI_USER 环境变量读取用户名，避免每次都通过 JWT 登录发现。

Base URL

# 本地开发
http://localhost:5000

# 预览环境（v3：{tail}-{prefix}-{projectSlug}.miduo.org，统一走 cdscli 不要手拼）
python3 .claude/skills/cds/cli/cdscli.py --human preview-url

# 预览环境 Cloudflare 干扰时（通过 CDS container-exec）
http://localhost:5000  (容器内)

预览域名可能被 Cloudflare 干扰返回 500，此时需通过 CDS container-exec 在容器内测试。

Common API Endpoints

User Management

Method	Endpoint	Description
GET	/api/users	List all users
GET	/api/users/{userId}	Get user details

Authentication & Authorization

Method	Endpoint	Description
GET	/api/authz/users	List users with permissions
GET	/api/authz/roles	List system roles

Projects & PRD

Method	Endpoint	Description
GET	/api/prd/projects	List projects
GET	/api/prd/projects/{id}	Get project details

Model Management

Method	Endpoint	Description
GET	/api/mds/model-groups	List all model groups
PUT	/api/mds/model-groups/{id}	Update model group (e.g., set isDefaultForType)
GET	/api/mds/platforms	List LLM platforms
GET	/api/mds/models	List configured models

LLM Logs (Critical for debugging)

Method	Endpoint	Description
GET	/api/logs/llm?limit=10	Get recent LLM request logs

Visual Agent

Method	Endpoint	Description
GET	/api/visual-agent/image-master/workspaces	List workspaces
POST	/api/visual-agent/image-gen/generate	Generate image
POST	/api/visual-agent/image-gen/compose	Multi-image compose

System

Method	Endpoint	Description
GET	/api/init/status	Get system initialization status

Execution Steps

1. Identify the data needed: Determine which API endpoint to query based on the debugging context.

2. Execute the query: Use curl with the AI Access Key headers:

   curl -s "http://[::1]:5000/api/{endpoint}" \
     -H "X-AI-Access-Key: $AI_ACCESS_KEY" \
     -H "X-AI-Impersonate: $MAP_AI_USER"
   

3. Parse the response: The API returns JSON in this format:

   {
     "success": true,
     "data": { ... },
     "error": null
   }
   

4. Analyze the data: Use the returned data to understand the system state and diagnose issues.

LLM Log Analysis (Important)

When debugging LLM-related features, always check the LLM logs:

Invoke-RestMethod -Uri "http://localhost:8000/api/logs/llm?limit=10" -Headers @{"X-AI-Access-Key"="$env:AI_ACCESS_KEY"; "X-AI-Impersonate"="$env:MAP_AI_USER"} | ForEach-Object { $_.data.items } | ForEach-Object {
    Write-Host "---"
    Write-Host "Model: $($_.model)"
    Write-Host "Purpose: $($_.requestPurpose)"
    Write-Host "Status: $($_.status)"
    Write-Host "Duration: $($_.durationMs)ms"
    if ($_.error) { Write-Host "Error: $($_.error)" }
}

Key fields to check:

• requestPurpose: Identifies which feature made the call (e.g., visual-agent.compose::vision)
• status: succeeded or failed
• error: Error message if failed
• requestBody: The actual request sent to LLM (check if data is missing)
• answerPreview: Preview of LLM response

Example Queries

Get all users

curl -s "http://[::1]:5000/api/users" \
  -H "X-AI-Access-Key: $AI_ACCESS_KEY" \
  -H "X-AI-Impersonate: $MAP_AI_USER" | jq

Get specific user

curl -s "http://[::1]:5000/api/users/user1" \
  -H "X-AI-Access-Key: $AI_ACCESS_KEY" \
  -H "X-AI-Impersonate: $MAP_AI_USER" | jq

List projects with pagination

curl -s "http://[::1]:5000/api/prd/projects?page=1&pageSize=10" \
  -H "X-AI-Access-Key: $AI_ACCESS_KEY" \
  -H "X-AI-Impersonate: $MAP_AI_USER" | jq

Error Handling

• 401 Unauthorized: Check that AI_ACCESS_KEY environment variable is set on the server
• 401 User not found: The username in X-AI-Impersonate must exist in the database (use $MAP_AI_USER, never hardcode admin or root)
• 403 Forbidden: Should not happen with AI Access Key (has super permissions)
• 404 Not Found: Check the endpoint path
• HTTP 500 via preview domain: Cloudflare CDN 可能干扰认证请求。如果预览域名返回 500 但容器状态为 running，使用 CDS container-exec 在容器内直接 curl http://localhost:5000/... 绕过 CDN

常见陷阱

陷阱	后果	正确做法
使用 Authorization: Bearer header	认证失败	必须用 X-AI-Access-Key header
测试 /api/users/me	404（该端点不存在）	用 /api/users 列表验证认证是否正常
把 404 当成认证失败	误判根因、引入错误修复	区分 HTTP 状态码：401=认证失败，404=端点不存在
预览域名 500 认为代码有 bug	可能是 Cloudflare 干扰	通过 CDS container-exec 在容器内验证

Security Notes

• This skill has super permissions and can access all data
• Use responsibly for debugging purposes only
• The access key should be kept secure and not logged
• All requests are logged on the server for audit purposes

Related Skills

• auto-test-debug：涉及 LLM 调用链路的自动化测试与调试，包含完整的验证流程和问题定位方法