mirror of
https://github.com/YspCoder/clawgo.git
synced 2026-05-17 08:07:28 +08:00
121 lines
2.4 KiB
Markdown
121 lines
2.4 KiB
Markdown
# 05 Gateway API 文档
|
||
|
||
## 背景
|
||
|
||
Gateway 暴露了较多 WebUI/API endpoint，但目前主要靠 `pkg/api/server.go` 阅读理解。对前端、集成方和测试编写者来说，需要一份稳定的 API 文档。
|
||
|
||
## 目标
|
||
|
||
新增 Gateway API 文档，说明认证方式、核心接口、请求/响应样例、错误约定和常见调用场景。
|
||
|
||
## 建议改动范围
|
||
|
||
主要文件：
|
||
|
||
- 新增 `docs/API.md`
|
||
- 可选更新 `README.md` 或 `docs/PROJECT_OVERVIEW.md` 增加链接
|
||
|
||
参考文件：
|
||
|
||
- `pkg/api/server.go`
|
||
- `cmd/cmd_gateway.go`
|
||
- `config.example.json`
|
||
|
||
尽量避免修改：
|
||
|
||
- API handler 行为
|
||
- Gateway runtime 行为
|
||
- 前端资源或 WebUI 逻辑
|
||
|
||
## 文档建议结构
|
||
|
||
```text
|
||
# Gateway API
|
||
|
||
## 认证
|
||
## 基础 URL
|
||
## 健康检查
|
||
## Chat
|
||
## Chat History
|
||
## Live Chat / SSE
|
||
## Events
|
||
## Config
|
||
## Provider OAuth
|
||
## Provider Models / Runtime
|
||
## Weixin Login
|
||
## Upload
|
||
## Cron
|
||
## Skills
|
||
## Sessions
|
||
## Memory
|
||
## Workspace File
|
||
## Tools
|
||
## MCP Install
|
||
## Logs
|
||
## 错误响应
|
||
```
|
||
|
||
## 需要覆盖的接口
|
||
|
||
从当前代码至少覆盖：
|
||
|
||
```text
|
||
GET /health
|
||
* /api/config
|
||
* /api/chat
|
||
* /api/chat/history
|
||
* /api/chat/live
|
||
* /api/events/live
|
||
* /api/version
|
||
* /api/provider/oauth/start
|
||
* /api/provider/oauth/complete
|
||
* /api/provider/oauth/import
|
||
* /api/provider/oauth/accounts
|
||
* /api/provider/models
|
||
* /api/provider/runtime
|
||
* /api/weixin/status
|
||
* /api/weixin/login/start
|
||
* /api/weixin/login/cancel
|
||
GET /api/weixin/qr.svg
|
||
* /api/weixin/accounts/remove
|
||
* /api/weixin/accounts/default
|
||
* /api/upload
|
||
* /api/cron
|
||
* /api/skills
|
||
* /api/sessions
|
||
* /api/memory
|
||
* /api/workspace_file
|
||
* /api/tool_allowlist_groups
|
||
* /api/tools
|
||
* /api/mcp/install
|
||
* /api/logs/live
|
||
* /api/logs/recent
|
||
```
|
||
|
||
## 验收标准
|
||
|
||
- 新增 `docs/API.md`。
|
||
- 每个核心接口至少有用途、方法、认证、主要参数、响应示例。
|
||
- 文档说明 gateway token 的传递方式。
|
||
- 文档中明确哪些接口用于 SSE/live。
|
||
- 文档不声称尚不存在的行为。
|
||
- 纯文档任务无需修改源码。
|
||
|
||
## 测试建议
|
||
|
||
纯文档任务可不跑全量测试。建议至少用代码核对路由：
|
||
|
||
```bash
|
||
rg "HandleFunc|SetProtectedRoute" pkg/api/server.go
|
||
```
|
||
|
||
如果顺手补了 API 测试，则运行：
|
||
|
||
```bash
|
||
go test ./pkg/api
|
||
```
|
||
|
||
## 并行注意
|
||
|
||
本任务只写文档，适合和 Gateway 拆分并行执行。若 Gateway 拆分改动路由注册位置，最终合并时再核对一次 API 文档。
|