parallel optimization groundwork

docs/optimization/05-gateway-api-docs.md

@@ -0,0 +1,120 @@
+# 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 文档。