# API 文档编写说明

本文档定义 `docs/zh/api/` 目录下各 API 模块文档的统一结构和编写规范。

## 目录结构

API 文档按模块组织，每个模块一个文件，使用两位数字序号前缀。

## 文件统一结构

每个 API 模块文档应遵循以下结构：

````markdown
# <模块名称>

<简短介绍，说明本模块的主要功能和用途>

## <可选的概念/介绍章节>

（如需要，介绍本模块涉及的核心概念、工作流程等）

## API 参考

### <API 方法名 1>

#### 1. API 实现介绍

<介绍该 API 的用途，指向对应的代码入口，简单介绍原理和流程>

**代码入口**：
- `openviking/<模块>/<文件>.py:<类名>.<方法名>` - 核心实现
- `openviking/server/routers/<路由文件>.py` - HTTP 路由
- `crates/ov_cli/src/commands/<命令文件>.rs` - CLI 命令

#### 2. 接口和参数说明

**参数**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| <参数名> | <类型> | <是/否> | <默认值> | <详细说明> |
| ... | ... | ... | ... | ... |

**<可选的补充说明章节>**

（如需要，说明特殊行为、注意事项、使用场景等）

#### 3. 使用示例

**Python SDK**

```python
<SDK 调用示例>
```

**TypeScript SDK**

```typescript
<SDK 调用示例>
```

**Go SDK**

```go
<SDK 调用示例>
```

**HTTP API**

```
<HTTP 方法> <路径>
```

```bash
<curl 示例>
```

**CLI**

```bash
<CLI 命令示例>
```

**响应示例**

```json
<JSON 响应示例>
```

#### 4. 响应契约（必填）与错误处理（可选）

每个公开操作都必须说明成功返回值。JSON 接口至少给出一个与实现一致的响应包示例；文件下载、SSE、WebDAV 等非 JSON 接口必须说明 HTTP 状态、关键响应头、响应体或事件格式。不能只写“返回某些字段”而不展示结构。错误和异常处理示例可按需补充。

---

### <API 方法名 2>

（重复上述结构）

---

## <可选的其他章节>

## 相关文档

- [<文档标题>](<相对路径>) - <简短说明>
````

## 结构详解

### 标题与简介

- 一级标题是模块名称
- 简介用一段话说明该模块的用途和主要功能

### API 参考章节

每个接口按以下三个部分组织：

#### 1. API 实现介绍

- 说明该 API 的用途
- 提供代码入口路径，方便读者查阅源码
- 简单介绍实现原理和处理流程

**代码入口说明**：
- 核心实现：指向主要业务逻辑代码
- HTTP 路由：指向 FastAPI 路由定义
- CLI 命令：指向 CLI 命令实现（如有）

#### 2. 接口和参数说明

- 参数表：包含参数名、类型、是否必填、默认值、说明
- 补充说明（可选）：特殊行为、注意事项、使用场景等

#### 3. 使用示例

当一个接口并列展示所有调用方式时，建议按以下顺序提供：
- Python SDK 示例
- TypeScript SDK 示例
- Go SDK 示例（当它能补充说明该接口的调用形态，且可以保持简短时）
- HTTP API（方法 + 路径 + curl 示例）
- CLI 示例
- 响应示例

示例切换由加粗标签自动生成。调用方式标签必须单独成段，并使用以下固定基础写法：
`**Python SDK**`、`**TypeScript SDK**`、`**Go SDK**`、`**HTTP API**`、`**CLI**`。
需要区分调用形态时，可以在同一个加粗标签内追加半角括号限定词，例如
`**Python SDK (Embedded / HTTP)**`；不要把限定词写在加粗标签外，也不要使用全角括号。
只展示实现中真实存在的调用方式；某个 SDK 或 CLI 没有对应能力时应省略该 Tab，并简短说明
可用的替代入口。不要把手写 HTTP 请求包装成不存在的 SDK 方法。

如果现有接口因工作流说明采用了特殊结构，应保持该局部结构稳定，并将 TypeScript 放在其他
SDK 示例附近。

API 文档应按 API 模块和具体接口组织，而不是按客户端语言组织。SDK 片段只作为对应接口
“使用示例”中的简短调用示例出现。语言专属 quick reference、完整 walkthrough 或跨接口串联流程
应放在该 SDK 自己的文档中，不应新增到 API 模块页面里。

## 示例：完整接口文档

````markdown
### add_resource()

#### 1. API 实现介绍

向知识库添加资源，支持本地文件、目录、URL 等多种来源。

**处理流程**：
1. 识别资源类型（本地文件/目录/URL）
2. 调用对应 Parser 解析内容
3. 构建目录树并写入 AGFS
4. 异步生成 L0/L1 语义摘要
5. 建立向量索引

**代码入口**：
- `openviking/async_client.py:AsyncOpenViking.add_resource()` - 异步 SDK 入口
- `openviking/sync_client.py:SyncOpenViking.add_resource()` - 同步 SDK 入口
- `openviking/service/resource_service.py:ResourceService.add_resource()` - 核心实现
- `openviking/server/routers/resources.py:add_resource()` - HTTP 路由
- `crates/ov_cli/src/handlers.rs:handle_add_resource()` - 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 文档时，请检查：

- [ ] 实现介绍清晰，代码入口路径正确
- [ ] 参数表完整且准确
- [ ] 示例代码简洁且可运行
- [ ] 调用示例使用固定加粗标签，并且每个 SDK/CLI Tab 都有真实实现
- [ ] HTTP 方法和路径正确
- [ ] 每个公开操作都有成功响应契约，且示例与实际返回一致