draftgo-cli 3.0.1 → 3.0.33

package/resources/skill/references/api-endpoints.md

@@ -0,0 +1,178 @@
+---
+read_when: 需要查具体 API 端点时 · 构造请求时
+---
+
+# 后端 API 速查
+
+> 优先运行 `draftgo api <keyword>` 做结构化查询；需要完整 OpenAPI 时见 [api.json]({{SKILL_SHARED}}/references/api.json)。
+> `draftgo api` 仅索引 DraftGo 底座 API。自定义服务的运行时路由由本地 `app.Route` 动态注册，不会出现在该 OpenAPI 中；按 `<METHOD> /api/x/<slug><route-path>` 推导，推送后必须请求无副作用 GET Route 验证。
+> 统一响应信封：`{ code: 200, data: <载荷>, message: "success" }`
+> GET 列表端点通常在不传 `page` / `page_size` 时全量返回；自定义服务执行记录是固定分页特例（默认 20，最大 100）。
+> Go 自定义服务使用 `draftgo.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，筛选和分页见 `references/custom-services.md`。
+
+## 认证
+
+```
+POST /api/auth/login, /register, /logout, /refresh
+POST /api/auth/forgot-password, /reset-password
+POST /api/auth/wechat/mp/oauth, /wechat/mini/login
+POST /api/auth/wechat/mp/qr/create  GET /wechat/mp/qr/poll
+```
+
+## 用户 & 角色
+
+```
+GET/PUT  /api/users/me                PUT /api/users/me/password
+GET/POST /api/users                   GET/PUT/DELETE /api/users/{id}
+POST     /api/users/{id}/ban, /unban
+
+GET/POST /api/roles                   GET/PUT/DELETE /api/roles/{id}
+POST     /api/roles/{id}/assign/{uid} DELETE /api/roles/{id}/revoke/{uid}
+```
+
+## 页面
+
+```
+GET/POST           /api/pages/
+GET/PUT/DELETE     /api/pages/{id}
+POST               /api/pages/{id}/reset-system
+GET                /api/pages/by-route?route=/xxx
+GET                /api/pages/{id}/versions
+POST               /api/pages/{page_id}/versions/{version_id}/restore, /star
+```
+
+## 导航栏
+
+```
+GET/POST      /api/navigations
+GET           /api/navigations/{code}
+PUT/DELETE    /api/navigations/{id}
+```
+
+## 动态 DB
+
+```
+GET            /api/db/{type}
+               支持 filters/order_by/order/page/page_size/populate/scope=mine
+               scope=mine 仅 admin 用户的列表 GET 生效：非后台业务页用，后台管理页不用
+               📌 filters 语法 → references/data.md#filters-操作符
+               📌 searchable 模式 → references/data.md#searchable-字段标记
+               📌 ref/populate/onDelete → references/data.md#关联关系ref
+POST           /api/db/{type}       body: { data: {...} } 或数组
+PATCH          /api/db/{type}/batch
+GET/PUT/DELETE /api/db/{type}/{id}
+               DELETE 会按真实引用字段的 ref.onDelete 处理级联 / 置空 / 阻止 / 解除关联
+```
+
+## DB Meta ⚠️
+
+```
+GET/POST         /api/db-meta
+GET              /api/db-meta/{type}   ← 必须用 type，不是 id！
+PUT/DELETE       /api/db-meta/{id}
+POST             /api/db-meta/{type}/reconcile-fields
+```
+
+## 自定义服务
+
+```
+GET/POST         /api/scripts
+GET              /api/scripts/options/roles
+GET/PUT/DELETE   /api/scripts/{id}
+GET              /api/scripts/{id}/routes
+POST             /api/scripts/{id}/enable, /disable, /execute
+GET              /api/scripts/{id}/versions
+POST             /api/scripts/{id}/versions/{version_id}/restore
+GET              /api/scripts/{id}/executions
+GET              /api/scripts/{id}/executions/{execution_id}
+ANY              /api/x/{slug}/{path}   ← 脚本运行时端点
+```
+
+自定义服务要点：
+
+- 本地文件：`.draftgo/custom_scripts/index.json` + 每条记录的 `code_file`。
+- 新服务使用 Go `Register(app *sdk.App)`；用 `app.Route` / `app.On` / `app.Schedule` 自动注册。
+- 新服务使用 `mode=mixed`，可同时暴露 HTTP、响应事件和执行 cron。
+- route 注册来自 `app.Route("METHOD", "/path", handler)`；一个服务可声明多个 route，共用同一个 slug 命名空间。
+- event 和 scheduled 分别来自 `app.On(...)` 与 `app.Schedule(...)`；均支持在一个服务内声明多个 handler。
+- 旧 `triggers` 字段不参与注册，CLI 不再创建或推送该字段。
+- route handler 签名：`func handler(draftgo *sdk.Context) (any, error)`；实际字段位于 `draftgo.Input`，用户身份用 `draftgo.Auth.CurrentUser()`。
+- Route 的普通 SDK 调用继承当前调用者资源权限，管理员创建服务不自动提升；需要管理员权限时逐次显式调用 `draftgo.Admin.DB`、`draftgo.Admin.Users` 等。`Admin` 调用以管理员身份执行并自动写入执行审计，但不会向代码暴露 SAT。带 `user_id` / `actor_user_id` 的事件继承该用户，定时任务及无可解析用户的事件才是系统身份。
+- 路径换算：`slug=order` + `app.Route("POST", "/pay", handler)` → `POST /api/x/order/pay`。
+- route 是精确路径匹配，不支持 `/items/{id}` 参数模板；ID 使用 query/body。
+- 动态数据访问使用 `draftgo.DB.Query("order", sdk.QueryOptions{...})`，结果为 `sdk.QueryResult`；筛选与分页见 `references/custom-services.md`。
+- `permission` 控制调用权限；`config.route_security` 控制限流、IP、body 大小和超时。
+- `scripts:*` 控制服务管理权限，和 Route 的调用权限彼此独立；执行列表固定分页，详情日志按单条加载。
+- `config.max_concurrency` / `queue_timeout_ms` 控制服务级退避；Route 饱和返回 429。
+- 完整 SDK、`draftgo`、AIHub、事件、配置与运行限制见 `references/custom-services.md`。
+
+## AIHub & AI推理
+
+```
+GET/POST   /api/aihub                     ← AIHub 资源（模型/Agent 定义）CRUD
+POST       /api/aihub/{id}/sync           ← 同步供应商模型目录
+GET        /api/v1/models
+POST       /api/v1/chat/completions       ← OpenAI 兼容格式（直连模型）
+POST       /api/v1/embeddings             ← 向量嵌入（OpenAI 兼容）
+POST       /api/v1/images/generations     ← 图片生成（OpenAI 兼容）
+```
+
+Agent 调用面（页面/调用方用 agent id 调用，不是直连模型）：
+```
+GET        /api/agents                    ← 列出当前用户可调用的 Agent（拿 id/name/describe）
+GET        /api/agents/{id}/selectable-models  ← { user_selectable, models }
+POST       /api/agents/{id}/chat          ← 对话，见下方 body；stream=true 返回 SSE
+POST       /api/agents/{id}/images        ← 图片模式 Agent（body.prompt 必填）
+POST       /api/agents/{id}/preview-chat  ← 只解析不执行：回 { model, fallback_models, candidate_provider_ids, messages }，用于调试路由
+```
+
+`/api/agents/{id}/chat` 请求体：
+```
+{ messages:[{role,content}] | message:"简写字符串", stream?:bool,
+  model?:"覆盖模型", session_id?:"多轮会话键", context?:{} }
+```
+- `stream:true` → `text/event-stream`，逐帧 `data: {...}`，以 `data: [DONE]` 结束；否则返回 OpenAI 风格完整结果。
+- 传 `session_id` 且 Agent 开启持续对话（checkpoint）时，服务端加载并续写该会话历史；不传即无状态单轮。
+
+AI 运行观测（`/admin/ai-runs` 页数据源）：
+```
+GET        /api/aihub/runs                ← 运行列表，支持 status/model/trace_id/agent_id/event_type/time_start/time_end + 分页
+GET        /api/aihub/runs/{trace_id}     ← 单次运行详情（含 spans / tokens / ttft_ms / 延迟）
+DELETE     /api/aihub/runs                ← 按 trace_ids 或时间范围批量清理
+```
+
+## 文档中心
+
+```
+GET/POST   /api/docs/categories
+GET        /api/docs/articles, /api/docs/articles/{key}, /api/docs/search
+POST       /api/docs/articles    PUT/DELETE /api/docs/articles/{id}
+```
+
+## 系统 & 备份
+
+```
+GET          /api/system/config
+GET/PUT/DELETE /api/system/{key}
+GET/POST     /api/system/backup
+POST         /api/system/restore, /api/system/reset
+POST         /api/system/restore/selective?mode=replace|merge|append
+POST         /api/upload
+GET          /api/system/logs
+```
+
+## 二次认证（高危操作前必须）
+
+restore / reset / undo / cleanup-orphans 需要：
+```
+POST /api/auth/reauth  { password, scope }  → 返回 confirm_token
+请求头加：X-Confirm-Token: <token>
+```
+
+## 不使用信封的端点
+
+| 端点 | 格式 |
+|---|---|
+| `POST /api/v1/chat/completions` | OpenAI SSE / JSON |
+| `GET /api/v1/models` | `{ object:"list", data:[...] }` |
+| `ANY /api/x/{slug}/{path}` | 脚本自定义 |