完善文档

docs/api/README.md

@@ -0,0 +1,3 @@
+# API
+
+API 契约与协议文档目录。

docs/api/authentication.md

@@ -0,0 +1,7 @@
+# Authentication
+
+认证与授权分离。
+
+认证回答“你是谁”；授权回答“你能做什么”。
+
+支持的认证方式由部署环境决定，业务代码只依赖统一 Identity Context。

docs/api/conventions.md

@@ -0,0 +1,8 @@
+# API Conventions
+
+- REST 资源使用名词。
+- JSON 使用统一编码。
+- 时间使用 ISO 8601。
+- ID 使用稳定唯一标识。
+- API 版本必须可演进。
+- 分页、排序、过滤采用统一约定。

docs/api/errors.md

@@ -0,0 +1,11 @@
+# API Errors
+
+统一错误模型：
+
+- code
+- message
+- details
+- request_id
+- trace_id
+
+不要把内部异常堆栈直接返回给用户。

docs/api/overview.md

@@ -0,0 +1,16 @@
+# API
+
+API 使用 OpenAPI 3.1。
+
+核心领域：
+
+- Auth
+- Agent
+- Session
+- Run
+- Task
+- Memory
+- Knowledge
+- Tool
+- File
+- MCP

docs/api/streaming.md

@@ -0,0 +1,13 @@
+# Streaming
+
+SSE 是 Agent 流式输出默认方案。
+
+事件至少包含：
+
+- event_id
+- run_id
+- event_type
+- timestamp
+- payload
+
+客户端断线后通过 Last-Event-ID 请求恢复。