multica-manage-skills

name	multica-manage-skills
description	查询已部署的 multica 平台 API，获取 workspace / agent 统计信息（agent 运行次数、30 天活动明细、各 workspace 汇总）。当用户需要查 multica 数据（如“每个 workspace 的 agent 运行次数”“workspace 统计”“multica 接口数据”），或访问 <MULTICA_API_URL> 的 API 信息时使用。脚本为纯标准库 Python，无需安装依赖。

multica-manage-skills

Overview

multica 是自部署的 agent 编排平台（线上地址 <MULTICA_API_URL>）。本 skill 提供一套可随时调用的 Python API 客户端，用于拉取 workspace 列表、每个 workspace 的 agent 列表、agent 30 天运行次数与日活明细，并输出汇总报表。

认证与配置

脚本通过 Authorization: Bearer <token> 认证，workspace 通过 X-Workspace-Slug 请求头指定（slug 或 UUID 均可）。

本脚本不读取任何本地配置文件（不读 ~/.multica/config.json，也不读脚本目录下的 json），只接受命令行参数与环境变量，避免本地磁盘文件干扰。

token 解析优先级（从高到低）：

1. --token 参数
2. 环境变量 MULTICA_API_TOKEN

API 地址解析优先级（从高到低）：

1. --url 参数
2. 环境变量 MULTICA_API_URL
3. 默认 <MULTICA_API_URL>

推荐把 token 与地址放进环境变量，一劳永逸（PowerShell 持久化示例）：

[Environment]::SetEnvironmentVariable("MULTICA_API_TOKEN", "mul_xxx", "User")
[Environment]::SetEnvironmentVariable("MULTICA_API_URL", "<MULTICA_API_URL>", "User")

新开终端后即生效。token 在 Web UI 的 Settings → Access Tokens 创建（形如 mul_xxx）。如果脚本报 401/403，优先检查 MULTICA_API_TOKEN。

快速开始

脚本位置：{skill_base_dir}/scripts/multica_api.py（用户级 skill，任何项目可用）。

# 列出所有 workspace
python scripts/multica_api.py workspaces

# 某 workspace 的 agent 列表
python scripts/multica_api.py agents --workspace <workspace-slug>

# 某 workspace 每个 agent 的 30 天运行次数（JSON 输出）
python scripts/multica_api.py run-counts --workspace <workspace-slug> --json

# 某 workspace 每个 agent 的 30 天日活明细
python scripts/multica_api.py activity --workspace <workspace-slug>

# 所有 workspace 汇总统计
python scripts/multica_api.py report

# 单个 workspace 的 agent 级明细（合并运行次数+活动+名称）
python scripts/multica_api.py report --workspace <workspace-slug>

# 指定 token / 地址 / CSV 输出
python scripts/multica_api.py --token YOUR_API_TOKEN --url <MULTICA_API_URL> report --csv

命令一览

子命令	说明	必选参数
me	当前登录用户信息	无
workspaces	当前用户可见的所有 workspace（id/name/slug/created_at）	无
agents	某 workspace 的 agent 列表（id/name/runtime_mode）	--workspace
run-counts	某 workspace 每个 agent 的 30 天运行次数 [{agent_id, run_count}]	--workspace
activity	某 workspace 每个 agent 的 30 天日活 [{agent_id, bucket_at, task_count, failed_count}]	--workspace
report	汇总：不带 --workspace 输出各 workspace 汇总；带 --workspace 输出该 workspace 的 agent 明细（含 fail_rate）	可选 --workspace

通用参数：--url、--token、--workspace、--json、--csv。

常见场景

1. “统计每个 workspace 的 agent 运行次数” → 跑 report（不带 --workspace），一行一个 workspace，含 agent 数、30 天总运行数、任务数、失败数。
2. “某个 agent 最近运行情况” → run-counts --workspace <ws> 拿运行次数，再 activity --workspace <ws> 看每日明细，用 --json 便于程序处理。
3. 想以 Python 模块方式集成 → from multica_api import MulticaClient，构造 MulticaClient(base_url, token) 后直接调用 list_workspaces() / agent_run_counts(ws) / workspace_report(ws) 等方法，异常统一抛 MulticaError。
4. 服务器不通/鉴权失败 → 脚本会打印 HTTP 状态码与响应体片段；401/403 时提示检查 token。

端点说明（详见 references/api_reference.md）

• GET /api/me、GET /api/workspaces 无需 workspace 头
• GET /api/agents、GET /api/agent-run-counts、GET /api/agent-activity-30d 需要 X-Workspace-Slug

Resources

• scripts/multica_api.py — 上述 API 客户端 + CLI（纯标准库，可直接运行或 import）
• references/api_reference.md — 端点、请求头、响应结构说明（来自 multica 源码）