API 文档编写说明
本文档定义 docs/zh/api/ 目录下各 API 模块文档的统一结构和编写规范。
目录结构
API 文档按模块组织，每个模块一个文件，使用两位数字序号前缀。
文件统一结构
每个 API 模块文档应遵循以下结构：
markdown
# <模块名称>
<简短介绍，说明本模块的主要功能和用途>
## <可选的概念/介绍章节>
（如需要，介绍本模块涉及的核心概念、工作流程等）
## API 参考
### <API 方法名 1>
#### 1. API 实现介绍
<介绍该 API 的用途，指向对应的代码入口，简单介绍原理和流程>
**代码入口**：
- `openviking/<模块>/<文件>.py:<类名>.<方法名>` - 核心实现
- `openviking/server/routers/<路由文件>.py` - HTTP 路由
- `openviking_cli/commands/<命令文件>.py` - CLI 命令
#### 2. 接口和参数说明
**参数**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| <参数名> | <类型> | <是/否> | <默认值> | <详细说明> |
| ... | ... | ... | ... | ... |
**<可选的补充说明章节>**
（如需要，说明特殊行为、注意事项、使用场景等）
#### 3. 使用示例
**HTTP API**
```
<HTTP 方法> <路径>
```
```bash
<curl 示例>
```
**Python SDK**
```python
<SDK 调用示例>
```
**CLI**
```bash
<CLI 命令示例>
```
**响应示例**
```json
<JSON 响应示例>
```
#### 4. 响应示例、错误和异常处理等（可选）
---
### <API 方法名 2>
（重复上述结构）
---
## <可选的其他章节>
## 相关文档
- [<文档标题>](<相对路径>) - <简短说明>结构详解
标题与简介
- 一级标题是模块名称
- 简介用一段话说明该模块的用途和主要功能
API 参考章节
每个接口按以下三个部分组织：
1. API 实现介绍
- 说明该 API 的用途
- 提供代码入口路径，方便读者查阅源码
- 简单介绍实现原理和处理流程
代码入口说明：
- 核心实现：指向主要业务逻辑代码
- HTTP 路由：指向 FastAPI 路由定义
- CLI 命令：指向 CLI 命令实现（如有）
2. 接口和参数说明
- 参数表：包含参数名、类型、是否必填、默认值、说明
- 补充说明（可选）：特殊行为、注意事项、使用场景等
3. 使用示例
按顺序提供：
- HTTP API（方法 + 路径 + curl 示例）
- Python SDK 示例
- CLI 示例
- 响应示例
示例：完整接口文档
markdown
### add_resource()
#### 1. API 实现介绍
向知识库添加资源，支持本地文件、目录、URL 等多种来源。
**处理流程**：
1. 识别资源类型（本地文件/目录/URL）
2. 调用对应 Parser 解析内容
3. 构建目录树并写入 AGFS
4. 异步生成 L0/L1 语义摘要
5. 建立向量索引
**代码入口**：
- `openviking/core/client.py:OpenViking.add_resource()` - SDK 入口
- `openviking/resource/importer.py:ResourceImporter.import_resource()` - 核心实现
- `openviking/server/routers/resources.py` - HTTP 路由
- `openviking_cli/commands/resources.py` - CLI 命令
#### 2. 接口和参数说明
**参数**
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| path | str | 是 | - | 本地路径、目录路径或 URL |
| to | str | 否 | None | 目标 Viking URI（必须在 resources 作用域内） |
| reason | str | 否 | "" | 添加该资源的原因 |
| wait | bool | 否 | False | 是否等待语义处理完成 |
**说明**
- SDK/CLI 可直接传本地路径；裸 HTTP 需要先用 `temp_upload` 上传
- 当指定 `to` 且目标已存在时，走增量更新流程
#### 3. 使用示例
**HTTP API**
```
POST /api/v1/resources
```
```bash
curl -X POST http://localhost:1933/api/v1/resources \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{
"path": "https://example.com/guide.md",
"reason": "User guide documentation",
"wait": true
}'
```
**Python SDK**
```python
import openviking as ov
client = ov.OpenViking(path="./data")
client.initialize()
result = client.add_resource(
"./documents/guide.md",
reason="User guide documentation"
)
print(f"Added: {result['root_uri']}")
client.wait_processed()
```
**CLI**
```bash
openviking add-resource ./documents/guide.md --reason "User guide documentation" --wait
```
**响应示例**
```json
{
"status": "ok",
"result": {
"status": "success",
"root_uri": "viking://resources/documents/guide.md",
"source_path": "./documents/guide.md",
"errors": []
},
"time": 0.123
}
```
---文档维护清单
新增或修改 API 文档时，请检查：
- [ ] 实现介绍清晰，代码入口路径正确
- [ ] 参数表完整且准确
- [ ] 示例代码简洁且可运行
- [ ] HTTP 方法和路径正确
- [ ] 响应示例与实际返回一致