opensource/AstrBot
3
0
Fork 0
mirror of https://github.com/AstrBotDevs/AstrBot.git synced 2026-10-16 15:06:04 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
8831d9502575f0aa6fbe5a2f77339b3e94954819
AstrBot/docs/zh/dev/openapi-scopes.md
T
Soulter 8831d95025 feat(dashboard): scoped path-token auth for plugin views and complete the views rename (#10415) 
* refactor(dashboard): complete the plugin pages to views rename

Finish the remaining Pages -> Views rename on the dashboard:

- Fix the plugin card "Open View" button crash by pointing
  openPluginWebui at the renamed PluginView route
- Rename PluginPagePage.vue to PluginViewPage.vue and update its
  internals (loadPluginView, pluginViewTitle, .plugin-view-* classes)
- Rename openPluginWebui -> openPluginView and the open-webui emit to
  open-view; pluginPageTitle/Description -> pluginViewTitle/Description;
  isPluginPageRoute -> isPluginViewRoute
- Rename i18n keys (pluginWebui -> pluginView, openWebui -> openView,
  pluginPageType -> pluginViewType, messages) across en/zh/ja/ru locales

The postMessage bridge channel name (astrbot-plugin-page) is kept
unchanged because it is part of the wire protocol shared with
plugin_page_bridge.js.

* feat(dashboard): authenticate plugin view assets with scoped path tokens

Serve plugin view assets from
/api/v1/plugins/{id}/views/{page}/_t/{token}/... so the scoped token
travels in the URL path. Relative URLs inside the view then inherit the
token through normal path resolution, which removes the need for
server-side HTML/CSS/JS URL rewriting on this route.

- Add the _t routes with a require_plugin_view_token dependency
  (v1 paths bypass the dashboard auth middleware)
- Extend the plugin page asset token to a session-length TTL (7 days,
  aligned with the dashboard session) with a page_session purpose claim,
  still scoped to a single plugin and page
- Serialize the view entry content_path as the _t URL, keeping the
  asset_token query for plugins that parse location.search
- Keep the legacy /api/plugin/page/content/...?asset_token= form working
  during the transition
- Rename the OpenAPI tag Plugin Pages -> Plugin Views, document the new
  route, regenerate the frontend API client, and update the zh/en
  plugin-pages docs

* refactor(dashboard): remove the legacy plugin page content route and URL rewriting

The path-token view route makes the compatibility surface unnecessary:

- Drop /api/plugin/page/content/... (query asset_token form)
- Drop the redundant authenticated asset routes /plugins/page/assets,
  /plugins/view/assets, and /plugins/{id}/(pages|views)/{page}/assets/...
  which had no callers outside the generated client
- Remove the HTML/CSS/JS URL rewriting helpers; view assets are always
  served raw and only HTML gets bridge SDK injection plus theme handling
- Slim PluginPageAuth down to the bridge SDK endpoint, the only
  non-v1 path still authenticating scoped query tokens
- serialize_plugin_page no longer falls back to the legacy content path
- Update the plugin-pages docs (zh/en) and the OpenAPI spec, and
  regenerate the frontend API client

* refactor(dashboard): drop legacy plugin page API aliases

Remove the page-named plugin view API aliases now that the views rename
is complete and legacy compatibility is intentionally dropped:

- DELETE /api/v1/plugins/page(s) and /plugins/{plugin_id}/pages{,/{page_name}}
  aliases; /plugins/view(s) and /plugins/{plugin_id}/views{,/{page_name}}
  are the only entry config routes
- Remove the unused /api/v1/plugins/page-bridge-sdk.js route; the live
  bridge SDK stays at /api/plugin/page/bridge-sdk.js
- Dashboard calls the view-named endpoints; regenerate the API client
  and the OpenAPI scopes docs

* refactor(dashboard): keep plugin page APIs as deprecated view aliases

Restore the page-named plugin view routes removed in the previous commit
and keep them for a transition period, with view as the canonical API:

- /plugins/page(s) and /plugins/{plugin_id}/pages{,/{page_name}} serve as
  aliases of the corresponding /views routes (same handlers)
- The OpenAPI spec marks the page operations deprecated and points new
  clients at the view routes; the v1 page-bridge-sdk.js route is restored
- The dashboard keeps calling the view endpoints by default

* refactor(dashboard): rename the plugin view path parameter to view_name

The view entry and path-token asset routes now use {view_name} instead of
{page_name} in the OpenAPI-visible path, and the service layer renames its
internal page_name variables to match. Wire-compatible surfaces stay
unchanged: the page_name JWT claim, the pageName JSON field, query
parameters, and the deprecated /pages aliases. Error messages and the
plugin view docs (zh/en) complete the Page to View rename.
2026-10-06 18:18:22 +08:00

14 KiB
Raw Blame History

outline
outline
deep

API Scope 与接口对照

本页由 openspec/openapi-v1.yaml 自动生成。每个接口的基础权限来自 x-astrbot-scope；敏感操作还会列出需要显式授予的子权限。

bot

管理机器人及平台配置。

方法 接口 条件性敏感子权限
GET /api/v1/bot-types —
GET /api/v1/bots —
POST /api/v1/bots —
GET /api/v1/bots/by-id —
PUT /api/v1/bots/by-id —
DELETE /api/v1/bots/by-id —
PATCH /api/v1/bots/enabled —
GET /api/v1/bots/stats —
POST /api/v1/bots/test —
GET /api/v1/bots/{bot_id} —
PUT /api/v1/bots/{bot_id} —
DELETE /api/v1/bots/{bot_id} —
PATCH /api/v1/bots/{bot_id}/enabled —
POST /api/v1/bots/{bot_id}/test —

provider

管理模型服务提供商和提供商源。

方法 接口 条件性敏感子权限
GET /api/v1/provider-sources —
POST /api/v1/provider-sources —
GET /api/v1/provider-sources/by-id —
PUT /api/v1/provider-sources/by-id —
DELETE /api/v1/provider-sources/by-id —
GET /api/v1/provider-sources/models —
GET /api/v1/provider-sources/providers —
POST /api/v1/provider-sources/providers —
GET /api/v1/provider-sources/{source_id} —
PUT /api/v1/provider-sources/{source_id} —
DELETE /api/v1/provider-sources/{source_id} —
GET /api/v1/provider-sources/{source_id}/models —
GET /api/v1/provider-sources/{source_id}/providers —
POST /api/v1/provider-sources/{source_id}/providers —
GET /api/v1/providers —
POST /api/v1/providers —
GET /api/v1/providers/by-id —
PUT /api/v1/providers/by-id —
DELETE /api/v1/providers/by-id —
POST /api/v1/providers/embedding-dimension —
PATCH /api/v1/providers/enabled —
GET /api/v1/providers/schema —
POST /api/v1/providers/test —
GET /api/v1/providers/{provider_id} —
PUT /api/v1/providers/{provider_id} —
DELETE /api/v1/providers/{provider_id} —
POST /api/v1/providers/{provider_id}/embedding-dimension —
PATCH /api/v1/providers/{provider_id}/enabled —
POST /api/v1/providers/{provider_id}/test —

persona

管理人格设定和人格文件夹。

方法 接口 条件性敏感子权限
GET /api/v1/persona-folders —
POST /api/v1/persona-folders —
PUT /api/v1/persona-folders/{folder_id} —
DELETE /api/v1/persona-folders/{folder_id} —
GET /api/v1/personas —
POST /api/v1/personas —
GET /api/v1/personas/by-id —
PUT /api/v1/personas/by-id —
DELETE /api/v1/personas/by-id —
POST /api/v1/personas/move —
POST /api/v1/personas/reorder —
GET /api/v1/personas/tree —
GET /api/v1/personas/{persona_id} —
PUT /api/v1/personas/{persona_id} —
DELETE /api/v1/personas/{persona_id} —

im

主动发送 IM 消息，并查询机器人或平台标识。

方法 接口 条件性敏感子权限
GET /api/v1/im/bots —
POST /api/v1/im/messages —

config

管理配置文件、系统配置和通用配置，但不包含修改 admins_id 的能力。

  • 包含权限: bot、provider

  • 敏感子权限 config:edit_admin: 允许具有 config 权限的 Key 修改 admins_id。该子权限必须显式授予。

方法 接口 条件性敏感子权限
POST /api/v1/bot-types/{bot_type}/registration —
GET /api/v1/config-profiles —
POST /api/v1/config-profiles config:edit_admin
GET /api/v1/config-profiles/schema —
GET /api/v1/config-profiles/{config_id} —
PUT /api/v1/config-profiles/{config_id} config:edit_admin
PATCH /api/v1/config-profiles/{config_id} —
DELETE /api/v1/config-profiles/{config_id} —
GET /api/v1/config-routes —
PUT /api/v1/config-routes —
PUT /api/v1/config-routes/{umo} —
DELETE /api/v1/config-routes/{umo} —
GET /api/v1/subagents/available-tools —
GET /api/v1/subagents/config —
PUT /api/v1/subagents/config —
GET /api/v1/system-config —
PUT /api/v1/system-config config:edit_admin
GET /api/v1/system-config/runtime —
GET /api/v1/system-config/schema —
GET /api/v1/t2i/templates —
POST /api/v1/t2i/templates —
GET /api/v1/t2i/templates/active —
PUT /api/v1/t2i/templates/active —
POST /api/v1/t2i/templates/default/reset —
GET /api/v1/t2i/templates/{name} —
PUT /api/v1/t2i/templates/{name} —
DELETE /api/v1/t2i/templates/{name} —

chat

调用对话能力，并管理 ChatUI 会话和项目。

  • 敏感子权限 chat:admin: 允许 username 使用 AstrBot 中已配置的管理员 ID。该子权限必须显式授予。
方法 接口 条件性敏感子权限
POST /api/v1/chat chat:admin
GET /api/v1/chat/configs —
GET /api/v1/chat/projects —
POST /api/v1/chat/projects —
DELETE /api/v1/chat/projects/sessions/{session_id} —
GET /api/v1/chat/projects/{project_id} —
PATCH /api/v1/chat/projects/{project_id} —
DELETE /api/v1/chat/projects/{project_id} —
GET /api/v1/chat/projects/{project_id}/sessions —
POST /api/v1/chat/projects/{project_id}/sessions/{session_id} —
GET /api/v1/chat/projects/{project_id}/workspace/file —
GET /api/v1/chat/projects/{project_id}/workspace/file/download —
GET /api/v1/chat/projects/{project_id}/workspace/files —
GET /api/v1/chat/runs/{run_id}/stream —
GET /api/v1/chat/sessions —
POST /api/v1/chat/sessions/batch-delete —
GET /api/v1/chat/sessions/new —
GET /api/v1/chat/sessions/{session_id} —
PATCH /api/v1/chat/sessions/{session_id} —
DELETE /api/v1/chat/sessions/{session_id} —
PATCH /api/v1/chat/sessions/{session_id}/messages/{message_id} —
POST /api/v1/chat/sessions/{session_id}/messages/{message_id}/regenerate —
POST /api/v1/chat/sessions/{session_id}/stop —
POST /api/v1/chat/threads —
GET /api/v1/chat/threads/{thread_id} —
DELETE /api/v1/chat/threads/{thread_id} —
POST /api/v1/chat/threads/{thread_id}/messages —
GET /api/v1/chat/ws chat:admin

data

管理对话记录和平台会话数据。

方法 接口 条件性敏感子权限
GET /api/v1/conversations —
POST /api/v1/conversations/batch-delete —
POST /api/v1/conversations/export —
GET /api/v1/conversations/filter-options —
GET /api/v1/conversations/{conversation_id} —
PATCH /api/v1/conversations/{conversation_id} —
DELETE /api/v1/conversations/{conversation_id} —
PUT /api/v1/conversations/{conversation_id}/messages —
GET /api/v1/session-groups —
POST /api/v1/session-groups —
PUT /api/v1/session-groups/{group_id} —
DELETE /api/v1/session-groups/{group_id} —
GET /api/v1/sessions —
GET /api/v1/sessions/active-umos —
PATCH /api/v1/sessions/provider —
GET /api/v1/sessions/rules —
POST /api/v1/sessions/rules —
POST /api/v1/sessions/rules/delete —
PATCH /api/v1/sessions/service —

file

上传和下载对话附件。

方法 接口 条件性敏感子权限
GET /api/v1/file —
POST /api/v1/file —
POST /api/v1/files —
GET /api/v1/files/content —
POST /api/v1/files/upload/abort —
POST /api/v1/files/upload/chunk —
POST /api/v1/files/upload/complete —
POST /api/v1/files/upload/init —
POST /api/v1/files/upload/status —
GET /api/v1/files/{attachment_id} —
DELETE /api/v1/files/{attachment_id} —
GET /api/v1/files/{attachment_id}/content —

plugin

管理插件、插件配置、插件源和插件市场数据。

方法 接口 条件性敏感子权限
GET /api/v1/plugin-sources —
POST /api/v1/plugin-sources —
PUT /api/v1/plugin-sources —
DELETE /api/v1/plugin-sources/by-id —
DELETE /api/v1/plugin-sources/{source_id} —
GET /api/v1/plugins —
GET /api/v1/plugins/by-id —
DELETE /api/v1/plugins/by-id —
GET /api/v1/plugins/changelog —
GET /api/v1/plugins/config —
PUT /api/v1/plugins/config —
GET /api/v1/plugins/config-files —
POST /api/v1/plugins/config-files —
DELETE /api/v1/plugins/config-files —
GET /api/v1/plugins/config/schema —
PATCH /api/v1/plugins/enabled —
GET /api/v1/plugins/extensions/{plugin_path} —
POST /api/v1/plugins/extensions/{plugin_path} —
PUT /api/v1/plugins/extensions/{plugin_path} —
PATCH /api/v1/plugins/extensions/{plugin_path} —
DELETE /api/v1/plugins/extensions/{plugin_path} —
GET /api/v1/plugins/failed —
DELETE /api/v1/plugins/failed/{plugin_id} —
POST /api/v1/plugins/failed/{plugin_id}/reload —
POST /api/v1/plugins/install/git —
POST /api/v1/plugins/install/github —
POST /api/v1/plugins/install/upload —
POST /api/v1/plugins/install/url —
GET /api/v1/plugins/market —
GET /api/v1/plugins/market/categories —
GET /api/v1/plugins/page —
GET /api/v1/plugins/page-bridge-sdk.js —
GET /api/v1/plugins/pages —
GET /api/v1/plugins/readme —
POST /api/v1/plugins/reload —
POST /api/v1/plugins/update —
POST /api/v1/plugins/validate/repo —
POST /api/v1/plugins/version-support/check —
GET /api/v1/plugins/view —
GET /api/v1/plugins/views —
GET /api/v1/plugins/{plugin_id} —
DELETE /api/v1/plugins/{plugin_id} —
GET /api/v1/plugins/{plugin_id}/changelog —
GET /api/v1/plugins/{plugin_id}/config —
PUT /api/v1/plugins/{plugin_id}/config —
DELETE /api/v1/plugins/{plugin_id}/config-files —
GET /api/v1/plugins/{plugin_id}/config-files/{config_key} —
POST /api/v1/plugins/{plugin_id}/config-files/{config_key} —
GET /api/v1/plugins/{plugin_id}/config/schema —
PATCH /api/v1/plugins/{plugin_id}/enabled —
PUT /api/v1/plugins/{plugin_id}/log-level —
GET /api/v1/plugins/{plugin_id}/pages —
GET /api/v1/plugins/{plugin_id}/pages/{view_name} —
GET /api/v1/plugins/{plugin_id}/readme —
POST /api/v1/plugins/{plugin_id}/reload —
POST /api/v1/plugins/{plugin_id}/source —
POST /api/v1/plugins/{plugin_id}/update —
GET /api/v1/plugins/{plugin_id}/views —
GET /api/v1/plugins/{plugin_id}/views/{view_name} —

mcp

管理 MCP 服务器配置和服务端同步。

方法 接口 条件性敏感子权限
POST /api/v1/mcp/providers/modelscope/sync —
GET /api/v1/mcp/servers —
POST /api/v1/mcp/servers —
PUT /api/v1/mcp/servers/by-name —
DELETE /api/v1/mcp/servers/by-name —
PATCH /api/v1/mcp/servers/enabled —
POST /api/v1/mcp/servers/test —
PUT /api/v1/mcp/servers/{server_name} —
DELETE /api/v1/mcp/servers/{server_name} —
PATCH /api/v1/mcp/servers/{server_name}/enabled —
POST /api/v1/mcp/servers/{server_name}/test —

skill

管理 Skills、Skill 压缩包、Skill 文件和 Shipyard Neo Skill 流程。

方法 接口 条件性敏感子权限
GET /api/v1/skills —
POST /api/v1/skills —
GET /api/v1/skills/archive —
POST /api/v1/skills/batch —
PATCH /api/v1/skills/by-name —
DELETE /api/v1/skills/by-name —
GET /api/v1/skills/file —
PUT /api/v1/skills/file —
GET /api/v1/skills/files —
GET /api/v1/skills/neo/candidates —
POST /api/v1/skills/neo/candidates/delete —
POST /api/v1/skills/neo/evaluate —
GET /api/v1/skills/neo/payload —
POST /api/v1/skills/neo/promote —
GET /api/v1/skills/neo/releases —
POST /api/v1/skills/neo/releases/delete —
POST /api/v1/skills/neo/rollback —
POST /api/v1/skills/neo/sync —
PATCH /api/v1/skills/{skill_name} —
DELETE /api/v1/skills/{skill_name} —
GET /api/v1/skills/{skill_name}/archive —
GET /api/v1/skills/{skill_name}/files —
GET /api/v1/skills/{skill_name}/files/{file_path} —
PUT /api/v1/skills/{skill_name}/files/{file_path} —
Reference in New Issue View Git Blame Copy Permalink