it235 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 解析优先级（从高到低）：
--token参数- 环境变量
MULTICA_API_TOKEN
API 地址解析优先级（从高到低）：
--url参数- 环境变量
MULTICA_API_URL - 默认
<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。
常见场景
- “统计每个 workspace 的 agent 运行次数” → 跑
report（不带--workspace），一行一个 workspace，含 agent 数、30 天总运行数、任务数、失败数。 - “某个 agent 最近运行情况” →
run-counts --workspace <ws>拿运行次数，再activity --workspace <ws>看每日明细，用--json便于程序处理。 - 想以 Python 模块方式集成 →
from multica_api import MulticaClient，构造MulticaClient(base_url, token)后直接调用list_workspaces()/agent_run_counts(ws)/workspace_report(ws)等方法，异常统一抛MulticaError。 - 服务器不通/鉴权失败 → 脚本会打印 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 源码）