> ## Documentation Index > Fetch the complete documentation index at: https://docs.zerone.run/llms.txt > Use this file to discover all available pages before exploring further. # API Reference > Agent Hub 管理、认证与聊天接口的入口说明。 # API Reference Hub HTTP 接口主要位于 `/api/v1`。所有 `/api/v1/*` 接口都需要 `Authorization: Bearer `（CLI token 也可作为 bearer token 使用）。认证模式决定登录流程，但业务接口仍由 Hub 的角色中间件授权。 角色（`admin` / `maintainer` / `member`）由 Hub 本地管理，见 [配置](/zh/hub/configuration)。`/api/v1/admin/*` 路径按两个分组注册在相同路径上： * **adminWrite**（`RequireManager` = admin + maintainer）：所有写方法（POST/PUT/PATCH/DELETE）与敏感读（AIGC 配置、Agent 运行时文件内容 `files/content`、Provider 密钥明文）。 * **adminRead**（admin + maintainer + member）：非敏感 GET（列表、详情、tools/skills/mcps/knowledge 绑定、文件列表、部署状态）。member 只读。 用户管理（`/api/v1/admin/users`、`/api/v1/admin/invites`）仅 admin 可用（`RequireAdmin`）。 ## 接口区域 | 区域 | 用途 | 访问边界 | | ----------------- | ------------------------------- | --------------------- | | `/api/v1/admin/*` | Agent、Tool、Skill、Provider 和部署管理 | 按角色区分读写 | | `/api/v1/cli/*` | CLI token 与身份 | `admin`、`maintainer` | | `/api/v1/chat/*` | 聊天与会话 | 登录用户或受控回传密钥 | | `/api/v1/ops/*` | 多组织 OAuth client 运维 | 仅设置 `OPS_API_KEY` 后挂载 | Ops API 默认不挂载，未配置时返回 404。外部自动化应先确认部署采用的认证模式，并保存最小权限 token。 ## 认证 两个可互换的认证后端由 `AUTH_MODE` 选择（默认 `builtin`）： | 方法 | 路径 | 说明 | | ---- | --------------------------- | ------------------------------------------------------------------------------------------------------- | | GET | `/auth/mode` | 报告当前认证模式（`builtin` / `casdoor`） | | GET | `/auth/login?org=` | （casdoor）重定向到指定组织的 Casdoor 登录。`org` 省略/为空 → default 组织 → 全局环境变量 `CASDOOR_CLIENT_ID`；未注册的未知组织 → 404，绝不回落 | | GET | `/auth/org-check?org=` | （casdoor）登录预检：重定向前校验组织（未注册组织 → 404） | | GET | `/auth/callback` | （casdoor）OAuth 回调，返回 token | | POST | `/auth/login` | （builtin）用户名密码登录 | | POST | `/auth/setup` | （builtin）首次运行初始化，创建初始 `admin` 账号 | | POST | `/auth/register` | （builtin）通过一次性邀请 token 注册 | | GET | `/auth/invite/:token` | （builtin）邀请预检 | | POST | `/auth/change-password` | （builtin）修改自己的密码 | | GET | `/auth/userinfo` | 当前用户信息。`tenant_id` 是权威字段（casdoor 模式 = Casdoor 组织名；builtin 模式 = `default`）；`org_id` 为同源兼容字段 | | POST | `/auth/refresh` | 刷新 access\_token（轮转：旧 refresh token 被吊销） | | POST | `/auth/logout` | 吊销 token | ## Agent（公开） | 方法 | 路径 | 说明 | | ------ | ------------------------------------------------- | ---------------------------------- | | GET | `/api/v1/agents/manifest` | Agent 清单（含 contentHash，供客户端缓存失效判断） | | GET | `/api/v1/agents` | 已启用 Agent 的完整配置 | | GET | `/api/v1/agents/:name` | 单个 Agent 详情 | | GET | `/api/v1/agents/:name/chat/sessions` | 列出某 Agent 的聊天会话 | | POST | `/api/v1/agents/:name/chat/sessions` | 创建聊天会话 | | GET | `/api/v1/agents/:name/chat/sessions/:id/messages` | 列出会话消息 | | POST | `/api/v1/agents/:name/chat/sessions/:id/messages` | 发送消息（SSE 流） | | DELETE | `/api/v1/agents/:name/chat/sessions/:id` | 删除会话 | ## Provider（公开，供客户端消费） | 方法 | 路径 | 说明 | | --- | ---------------------------------- | ------------------------------------------------- | | GET | `/api/v1/providers` | 本租户 Provider + 共享种子行；锁定的 API key 以**掩码**返回，绝不返回明文 | | GET | `/api/v1/providers/:id` | 单个 Provider（同样掩码） | | GET | `/api/v1/providers/runtime-config` | 面向 Runtime 的 Provider 配置（供 Agent Runtime 消费） | 明文密钥仅 admin/maintainer 可通过 `POST /api/v1/admin/providers/:id/reveal-key` 获取。 ## Skill（公开） | 方法 | 路径 | 说明 | | --- | ------------------------------- | -------------------------------------- | | GET | `/api/v1/skills` | Skill 列表（支持 `?type=expert\|community`） | | GET | `/api/v1/skills/:name` | Skill 详情 | | GET | `/api/v1/skills/:name/download` | 预签名下载链接（有效期 1 小时） | ## Scene（公开） | 方法 | 路径 | 说明 | | --- | ---------------------- | -------- | | GET | `/api/v1/scenes` | Scene 列表 | | GET | `/api/v1/scenes/:name` | Scene 详情 | ## Chat（普通用户） | 方法 | 路径 | 说明 | | ---- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | POST | `/api/v1/chat/push` | 回传会话/消息（每请求最多 50 个会话，按 `updated_at` 做冲突检测）。鉴权：JWT/CLI token（默认）**或** `X-Chat-Push-Key: `——密钥模式下，每个会话的 `user_name`（必填）成为 `user_id`/`display_name`；租户由 `org` 决定：builtin 模式忽略 `org`（恒为 `default`）；casdoor 模式显式传则用所传值，省略时解析为已登记的 default 租户组织（未登记则返回 400） | ## 管理端点（`/api/v1/admin/*`） 覆盖 Agent / Tool / Skill / Scene / Provider / Knowledge / Chat 的 CRUD 与探活。重要成员： | 方法 | 路径 | 分组 | 说明 | | --------------- | -------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- | | GET | `/api/v1/admin/agents/:name/deploy` | adminRead | 部署状态（含 runtimeUrl/apiKey，member 可读） | | POST | `/api/v1/admin/agents/:name/deploy`（+ `/stop`、`/start`、DELETE） | adminWrite | 部署与生命周期控制 | | GET | `/api/v1/admin/agents/:name/files`、`/files/content` | read / write | 文件列表 member 可读；**文件内容仅 admin/maintainer** | | GET×3 + DELETE | `/api/v1/admin/chat/sessions...` | adminRead | 聊天历史。Handler 层 `chatScopeUserID` 隔离：member 只能查看/删除自己的会话（他人的返回 404）；admin/maintainer 可见本租户全部会话 | | GET/PUT/DELETE | `/api/v1/admin/aigc/config`（+ `POST /config/rotate-key`） | adminWrite | 每租户的 AIGC 内容标识配置（GB 45438-2025） | | GET/POST/DELETE | `/api/v1/admin/users`、`/admin/invites` | 仅 admin | 用户管理 / 邀请链接 | | GET | `/api/v1/admin/audit-logs` | 仅 admin | 审计日志查询——过滤 + 快照分页，见下文 | ### 审计日志（仅 admin） `GET /api/v1/admin/audit-logs`——审计查询，仅 admin（`RequireAdmin`；maintainer/member 返回 403）。审计日志只读，没有更新/删除接口。 查询参数： | 参数 | 默认值 | 说明 | | ------------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | `1` | 页码，≥ 1；非法 → 400「无效的分页参数」 | | `page_size` | `20` | ≥ 1，上限 100（超过 100 被截断而非拒绝）；非法 → 400「无效的分页参数」 | | `category` | — | 精确匹配：`auth` \| `user` \| `invite` \| `provider` \| `agent` \| `token` \| `aigc` | | `action` | — | 精确匹配，如 `user.update_role` | | `user` | — | 对 `userName` / `userId` 模糊匹配（LIKE `%…%`） | | `from`、`to` | — | RFC3339 时间戳；`createdAt` 闭区间（`from` ≤ t ≤ `to`）；非法 → 400「无效的时间范围」 | | `snapshotId` | — | 十进制字符串，可选。快照一致分页：首次请求省略时服务器捕获全租户 `MAX(id)`；后续请求回传返回的 `snapshotId`，使 items 与 `total` 共享同一 `id <= snapshotId` 视图。`"0"` 是空集哨兵（租户无日志）。非法 → 400「无效的快照参数」 | 响应（按 `createdAt DESC, id DESC` 排序）： ```json theme={null} {"items":[{"id":"42","tenantId":"default","userId":"7","userName":"alice","category":"user","action":"user.update_role","targetType":"user","targetId":"2","targetName":"bob","status":"success","detail":{"field":"role","from":"member","to":"maintainer"},"remoteIp":"10.0.0.1","userAgent":"…","createdAt":"2026-09-10T12:00:00.123456Z"}],"total":1,"snapshotId":"42"} ``` * `id` / `snapshotId` 是十进制字符串：uint64 超过 2^53-1 的值作为 JS number 会丢精度——保持字符串，绝不转成 number。 * `detail` 是 JSON 对象或 `null`，结构由按 `action` 的强类型白名单决定。 * `status` 为三态：`success` / `failure` / `partial`。 ## CLI Tokens（`/api/v1/cli/*`——仅 admin/maintainer） | 方法 | 路径 | 说明 | | ------ | ------------------------- | ----------------------------------------- | | POST | `/api/v1/cli/issue-token` | 签发长效 CLI token（`cli_`；仅存 SHA-256 哈希） | | GET | `/api/v1/cli/tokens` | 列出自己的 token | | DELETE | `/api/v1/cli/tokens/:id` | 吊销 token | CLI token 拥有与签发用户相同的权限。 ## Ops API（`/api/v1/ops/*`——X-Ops-Key 请求头） 仅在设置 `OPS_API_KEY` 时挂载。用于登记各组织的 Casdoor OAuth client（多组织登录），运维手册见 [配置](/zh/hub/configuration)。 | 方法 | 路径 | 说明 | | ------ | --------------------------------- | ----------------------------------------------- | | POST | `/api/v1/ops/tenant-clients` | 新增或更新组织 → Casdoor Application 映射 | | GET | `/api/v1/ops/tenant-clients` | 列出已登记组织（不返回 secret） | | DELETE | `/api/v1/ops/tenant-clients/:org` | 删除映射（若它是 default 且仍有其他行 → 409；删除不存在的组织幂等返回 204） | ## Agent ID、部署键与公开 URL 自 deployer v3.1 起，已部署 Agent 携带三个相互独立的标识： * **Agent ID**（裸 ``）：runtime agent 图身份；Hub 的聊天/详情代理通过 `/v1/agents/` 裸名寻址 runtime（subagent 同样使用裸名）。 * **Deployment key**（`-`）：Kong 实体 / deployer 容器键——所有生命周期寻址（get/start/stop/delete）与网关实体命名。 * **Public URL**：casdoor 模式为 `https:////`；builtin 模式为 `https:///`（无 `/default` 前缀，但部署键仍保留 `default-` 前缀）。无 Kong 时，Hub 代理在 `/runtime` 前缀下提供相同路径。 ### Provider 探活示例 ```bash theme={null} # 测试已保存 Provider 的连通性 curl -X POST http://localhost:8081/api/v1/admin/providers/1/probe \ -H "Authorization: Bearer $TOKEN" # 测试未保存的配置 curl -X POST http://localhost:8081/api/v1/admin/providers/probe \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "baseUrl": "https://api.anthropic.com", "apiKey": "sk-ant-...", "protocol": "anthropic", "authStyle": "api_key" }' ``` ## 核心能力端点速查 | 领域 | 关键端点 | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | **Agent** | `GET /api/v1/agents/manifest` | | **Tool** | `POST /api/v1/admin/tools`（multipart 上传自定义工具）；`PUT /api/v1/admin/tools/:name/file`（补传/替换）；`GET /api/v1/admin/tools/:name/download` | | **Skill** | `GET /api/v1/skills/:name/download` | | **Provider** | `GET /api/v1/providers` | | **Scene** | `GET /api/v1/scenes` | | **Chat** | `POST /api/v1/chat/push` | ### 自定义工具 * 单文件 `.ts/.mts/.js/.mjs`，≤ 5 MiB；工具名来自文件默认导出的 `name`（Hub 不执行代码，由 Runtime 在部署时校验）。 * `tools.source`：`builtin`（共享只读预设）/ `custom`（租户制品）；custom 制品状态派生 `ready` | `missing`。 * 删除仍被 Agent 挂载的自定义工具返回 `409` + `data.agents` 名单；内置工具拒绝一切写操作。 * 部署请求向 agent-deployer 下发 `customTools []ToolSource{name,url,hash,fileName}`（仅 custom + ready，按名排序；URL = `OSS_CDN_HOST` + 内容寻址 key）。 * `PUT /api/v1/admin/tools/:name` 仅接受 `title` / `description` / `descriptionEn`；其他字段（如 `isDefault`）会被静默忽略。