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 逻辑

文档建议结构

# 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
## 错误响应

需要覆盖的接口

从当前代码至少覆盖：

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。
文档不声称尚不存在的行为。
纯文档任务无需修改源码。

测试建议

纯文档任务可不跑全量测试。建议至少用代码核对路由：

rg "HandleFunc|SetProtectedRoute" pkg/api/server.go

如果顺手补了 API 测试，则运行：

go test ./pkg/api

并行注意

本任务只写文档，适合和 Gateway 拆分并行执行。若 Gateway 拆分改动路由注册位置，最终合并时再核对一次 API 文档。

2.4 KiB Raw Blame History Unescape Escape