cat-admin

name	cat-admin
description	使用 Cat 项目的 `mix cat.api_admin` 命令完成管理端操作任务。用于读取 `openapi/admin_openapi.yaml` 查找管理端接口，并调用管理端 API 查询列表、查看详情或执行管理端写操作。手动调用触发。
disable-model-invocation	true

Cat Admin

Use this skill from the Cat project root.

Workflow

1. Read openapi/admin_openapi.yaml before calling any endpoint.
2. Locate the exact admin path, HTTP method, query parameters, and request body schema.
3. Build the command with mix cat.api_admin.
4. Run read-only GET calls directly when needed.
5. For destructive or high-impact POST calls, state the endpoint and payload first unless the user already explicitly requested the action.
6. Report the relevant response data, not the entire JSON blob unless the user asks for raw output.

Do not guess endpoint names from memory. The OpenAPI YAML is the source of truth.

Finding Endpoints

Start with targeted search:

rg -n "summary:|description:|/api/admin/.+<keyword>|operationId:" openapi/admin_openapi.yaml

Then inspect the nearby YAML block for:

• paths.<path>.<method>
• parameters for GET query values
• requestBody schema reference for POST payloads
• components.schemas.<SchemaName> for required fields and types

If a schema uses $ref, follow it inside components.schemas.

Calling Admin APIs

Command format:

mix cat.api_admin METHOD PATH [--query key=value ...] [--body JSON] [--base-url URL] [--token TOKEN] [--pretty]

Rules:

• Prefer CAT_BOT_API_TOKEN from the environment. Use --token only when the user provides one for this task.
• Use CAT_API_BASE_URL or --base-url only when the user needs a non-default server. Default is http://localhost:5000.
• Pass every GET parameter as repeated --query key=value.
• Pass POST/PUT/PATCH/DELETE payloads as one JSON string via --body.
• Keep id values as strings.
• Use --pretty for human inspection; omit it when downstream shell processing needs compact JSON.
• Do not print or summarize API tokens in the final answer.

Resolving IDs vs IDNames

Some admin resources support both id and idname query/body fields, especially Catalog Class and Property endpoints.

• Treat Cat database IDs as Sonyflake strings; they are usually long numeric strings.
• When the user explicitly says idname, pass idname=<value> directly. Do not probe id=<value> first just because the value is numeric-looking.
• Short numeric-looking values such as 8090 are often domain idname; prefer idname unless the user explicitly says it is a database ID / Sonyflake.
• Before a write to Class / Property by user-provided identifier, run the read-only detail endpoint with the intended identifier kind and resolve the actual target.
• When the lookup succeeds, use the returned canonical id or confirmed idname in the write payload and mention the resolved target in the summary.

Examples:

mix cat.api_admin get /api/admin/accounts/list_users --query role=bot --pretty
mix cat.api_admin get /api/admin/accounts/get_user --query id=614400000000000000 --pretty
mix cat.api_admin post /api/admin/accounts/regenerate_bot_api_token --body '{"id":"614400000000000000"}' --pretty

Response Handling

Admin API responses use the Cat JSON envelope:

{"success": true, "data": {}}

On failure, preserve the server error code and message in the user-facing summary:

{"success": false, "data": null, "error": {"code": "...", "message": "..."}}

If mix cat.api_admin fails before sending the request, check:

• CAT_BOT_API_TOKEN is set or --token is provided.
• The path exists in openapi/admin_openapi.yaml.
• The HTTP method matches the OpenAPI entry.
• The token belongs to a staff/superuser-capable bot for the requested action.