Menu
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/ArtisanCloud/PowerX --skill api-namingThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
Based on SOC occupation classification
| name | api-naming |
| description | PowerX API 命名与访问规范（/api/v1、/admin、/internal 边界）。 |
本文件内嵌规则。# PowerX API 命名与访问规范（全局）
> 本文件定义 PowerX 平台所有 HTTP API 的路径前缀、用途边界、版本策略、鉴权与命名风格。适用于 CoreX 底座、插件框架、插件业务服务。
## 1. 路径前缀与用途边界
### 1.1 公共访问域（对外/客户端）
- **/api/v1/**：对外开放的稳定 API（OpenAPI 可暴露）
- 典型对象：租户端、开放平台、第三方客户端
- 版本语义：语义化版本 v1 / v2
- **/api/**：兼容入口（老路径或内部自用），可作为路由代理或重定向到 /api/v1
- 若 /api/v1 存在同名路径，优先迁移到 /api/v1
> **注意：APIPrefix 可配置**（`cfg.Server.APIPrefix`）。本文档使用 `/api` 作为默认示例，实际运行路径为 `<APIPrefix>/...`，常见取值：`/api` 或 `/api/v1`。
### 1.2 管理/后台域（管理端/控制台）
- **/api/v1/admin/**：管理端 API（带管理权限）
- 典型对象：管理控制台、运营/内部管理系统
- 典型调用主体：PowerX Admin、插件 Admin 页面
- 鉴权语义：用户 JWT + tenant member + RBAC + 业务权限
- 必须带授权 token
- 不作为插件服务态 STS 直连的默认开放域
### 1.2.1 外部业务域（Web / Mini-app / Customer）
- **/api/v1/**：外部业务开放 API
- 典型对象：租户侧 Web、mini-app、customer portal、第三方客户端
- 典型调用主体：web user、mini-app user、customer actor、service actor
- 鉴权语义：用户 JWT、customer token、API Key、OAuth client 或明确声明的 STS
- 资源边界：默认 tenant-scoped；customer/mini-app 自助接口必须 owner-scoped/self-scoped
- 不得复用 `/api/v1/admin/*` 的全量治理语义
### 1.2.2 Capability 统一调用域
- **/api/v1/tenant/invocations**：服务态 capability 调度入口
- 典型对象：插件后端、agent、skill、系统集成
- 鉴权语义：STS/API Key/OAuth client + capability registration/grant
- 语义：按 `capability_id` 调用已授权能力，而不是直接暴露后台路由
### 1.3 内部/宿主域（仅内部使用）
- **<APIPrefix>/internal/**：宿主/插件内部调用入口（不对公网开放）
- 典型对象：PowerXPlugin Framework、CLI、宿主内部服务
- **必须最小化暴露，不写入公开 OpenAPI**
- 允许与 /api/v1 同时存在，但用途必须明确区分
> 说明：已有历史文档/实现中使用 `/internal/*` 或 `/api/internal/*`，统一向 `/api/internal/*` 对齐。
---
## 2. 版本策略
- 稳定对外接口必须挂在 `/api/v1`，有破坏性变更时升级 `/api/v2`
- `/api/internal` 不承诺稳定版本，但变更需记录在变更日志
- `/api` 仅作为兼容入口或内部路由代理，不建议新功能落地
---
## 3. 鉴权与租户透传
- **所有 `/api/v1/admin` 与 `/api/internal` 必须鉴权**
- 租户信息必须通过 token（JWT claims）或 `tenant_uuid` 字段解析，不接受遗留租户头注入。
- 内部接口也需 tenant 校验，禁止跨租户调用
- 设计新接口前必须声明调用主体：`admin_user`、`service_actor`、`web_user`、`mini_app_user`、`customer_actor`。
- 后台用户态接口和外部业务接口即使操作同一资源，也必须按 actor、资源范围、风险等级和授权开关判断是否复用同一 capability。
- customer/mini-app 自助接口不得使用 admin 全量管理权限；默认只能访问当前 customer/user/owner 可见资源。
---
## 4. 命名风格
### 4.1 资源命名
- REST 资源采用名词复数：
- `/api/v1/admin/agents`
- `/api/v1/admin/knowledge-spaces`
- `/api/v1/customer/accounts`
### 4.1.0 Actor 边界命名
- 后台管理：`/api/v1/admin/<resources>`
- 示例：`/api/v1/admin/customer/accounts`
- 外部业务/客户自助：`/api/v1/<domain>/<resources>` 或 `/api/v1/customer/<resources>`
- 示例：`/api/v1/customer/account`
- 示例：`/api/v1/customer/orders`
- 服务态开放接口：`/api/v1/<domain>/<resources>`，必须在能力或接口文档中声明允许的 STS/API Key/OAuth actor
- 示例：`/api/v1/scheduler/jobs`
- 统一能力调度：`/api/v1/tenant/invocations`
路径前缀不等于 capability。`/api/v1/admin/<resource>` 与 `/api/v1/<resource>` 如果业务语义和授权边界一致，可以是同一个 capability 的不同 binding；如果 actor 可操作资源范围不同，必须拆 capability。
### 4.1.1 插件相关命名
- 管理端插件资源：`/api/v1/admin/plugins/*`
- 示例：`/api/v1/admin/plugins`、`/api/v1/admin/plugins/:id`
- 宿主内部插件资源：`/api/internal/plugins/*`
- 示例：`/api/internal/plugins/local/reload`、`/api/internal/plugins/environments/check`
- 插件发布/治理内部分发：`/api/internal/version/*`、`/api/internal/notify/*`
- 宿主模式插件前端入口（反代）：`/_p/<pluginId>/admin/<path>`
- 示例：`/_p/com.powerx.helloworld/admin/intro`
- 宿主模式插件后端 API（反代）：`/_p/<pluginId>/api/<path>`
- 示例：`/_p/com.powerx.helloworld/api/healthz`
### 4.2 行为/动作
- 动作用 **子路径** 或 **操作端点**：
- `/api/v1/admin/agents/:id/activate`
- `<APIPrefix>/internal/ws-bus/publish`
### 4.3 异步任务
- 提交任务：`POST /.../tasks`
- 查询任务：`GET /.../tasks/:taskId`
---
## 5. OpenAPI / 合同要求
- `/api/v1` 与 `/api/v1/admin` 必须有 OpenAPI 文档
- `/api/internal` 默认不在公开 OpenAPI 中暴露
- 任何新增对外接口必须更新 specs/contracts
---
## 6. 日志 / 追踪 / 审计
- 对外与管理接口必须具备 trace_id
- `/api/internal` 必须记录 tenant/topic/trace_id（若涉及事件）
---
## 7. 示例
### 7.1 对外 API
```
GET /api/v1/knowledge-spaces
```
### 7.2 管理端 API
```
POST /api/v1/admin/agents/test/connection
```
### 7.2.1 Customer / Mini-app API
```
GET /api/v1/customer/account
PATCH /api/v1/customer/account/profile
GET /api/v1/customer/orders
```
### 7.2.2 Capability Invocation API
```
POST /api/v1/tenant/invocations
GET /api/v1/tenant/capabilities
```
### 7.3 内部 API
```
POST <APIPrefix>/internal/ws-bus/publish
```
### 7.4 插件相关 API
```
GET /api/v1/admin/plugins
POST /api/internal/plugins/local/reload
GET /_p/<pluginId>/admin/
GET /_p/<pluginId>/api/healthz
```
---
## 8. 变更记录
- 2026-02-03：首次定义 `/api/internal` 作为宿主/插件内部 API 前缀