# API 概览

本页介绍如何连接 OpenViking 以及所有 API 端点共享的约定。

## 连接 OpenViking

OpenViking 支持三种连接模式：

| 模式 | 使用场景 | 说明 |
|------|----------|------|
| **嵌入式** | 本地开发，单进程 | 本地运行，数据存储在本地 |
| **HTTP** | 连接 OpenViking Server | 通过 HTTP API 连接远程服务 |
| **CLI** | Shell 脚本、Agent 工具调用 | 通过 CLI 命令连接服务端 |

### 嵌入式模式

```python
import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()
```

嵌入式模式通过 `ov.conf` 配置 embedding、vlm、storage 等模块。默认路径 `~/.openviking/ov.conf`，也可通过环境变量指定：

```bash
export OPENVIKING_CONFIG_FILE=/path/to/ov.conf
```

最小配置示例：

```json
{
  "embedding": {
    "dense": {
      "api_base": "<api-endpoint>",
      "api_key": "<your-api-key>",
      "provider": "<volcengine|openai|jina|...>",
      "dimension": 1024,
      "model": "<model-name>"
    }
  },
  "vlm": {
    "api_base": "<api-endpoint>",
    "api_key": "<your-api-key>",
    "provider": "<volcengine|openai|openai-codex|kimi|glm>",
    "model": "<model-name>"
  }
}
```

当 `provider: "openai-codex"` 时，只要通过 `openviking-server init` 完成 Codex OAuth，就可以不填写 `vlm.api_key`。

完整配置选项和各服务商示例见 [配置指南](../guides/01-configuration.md)。

### HTTP 模式

```python
client = ov.SyncHTTPClient(
    url="http://localhost:1933",
    api_key="your-key",
    agent_id="my-agent",
    timeout=120.0,
)
client.initialize()
```

未显式传入 `url` 时，HTTP 客户端会自动从 `ovcli.conf` 读取连接信息。`ovcli.conf` 是 HTTP 客户端和 CLI 共享的配置文件，默认路径 `~/.openviking/ovcli.conf`，也可通过环境变量指定：

```bash
export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf
```

```json
{
  "url": "http://localhost:1933",
  "api_key": "your-key",
  "account": "acme",
  "user": "alice",
  "agent_id": "my-agent"
}
```

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `url` | 服务端地址 | （必填） |
| `api_key` | API Key | `null`（无认证） |
| `account` | 面向租户请求的默认 account 请求头 | `null` |
| `user` | 面向租户请求的默认 user 请求头 | `null` |
| `agent_id` | Agent 标识符 | `null` |
| `timeout` | HTTP 请求超时时间（秒） | `60.0` |
| `output` | 默认输出格式：`"table"` 或 `"json"` | `"table"` |

详见 [配置指南](../guides/01-configuration.md#ovcliconf)。

**HTTP 模式下的本地文件**

- CLI、`SyncHTTPClient`、`AsyncHTTPClient` 遇到本地文件或目录时，会先自动上传，再调用服务端 API。
- 裸 HTTP 调用没有这层封装。使用 `curl` 或其他 HTTP 客户端时，需要先调用 `POST /api/v1/resources/temp_upload`，再把返回的 `temp_file_id` 传给目标 API。
- 裸 HTTP 如果导入本地目录，需要先自行打成 `.zip` 再上传；服务端不接受直接传宿主机目录路径。
- `POST /api/v1/resources` 可以直接接收远端 URL，但不接受 `./doc.md`、`/tmp/doc.md` 这类宿主机本地路径。

### 直接 HTTP（curl）

```bash
curl http://localhost:1933/api/v1/fs/ls?uri=viking:// \
  -H "X-API-Key: your-key"
```

### CLI 模式

CLI 连接到 OpenViking 服务端，将所有操作暴露为 Shell 命令。CLI 同样从 `ovcli.conf` 读取连接信息（与 HTTP 客户端共享）。

**基本用法**

```bash
openviking [全局选项] <command> [参数] [命令选项]
```

**全局选项**（必须放在命令名之前）

| 选项 | 说明 |
|------|------|
| `--output`, `-o` | 输出格式：`table`（默认）、`json` |
| `--version` | 显示 CLI 版本 |

示例：

```bash
openviking -o json ls viking://resources/
```

## 生命周期

**嵌入式模式**

```python
import openviking as ov

client = ov.OpenViking(path="./data")
client.initialize()

# ... 使用 client ...

client.close()
```

**HTTP 模式**

```python
import openviking as ov

client = ov.SyncHTTPClient(url="http://localhost:1933")
client.initialize()

# ... 使用 client ...

client.close()
```

## 认证

详见 [认证指南](../guides/04-authentication.md)。

- **X-API-Key** 请求头：`X-API-Key: your-key`
- **Bearer** 请求头：`Authorization: Bearer your-key`
- 如果服务端未配置 API Key，则跳过认证。
- `/health` 端点始终不需要认证。

## 响应格式

所有 HTTP API 响应遵循统一格式：

**成功**

```json
{
  "status": "ok",
  "result": { ... },
  "time": 0.123
}
```

顶层 `status` 表示本次 HTTP API 请求是否成功。某些成功响应会在 `result` 中返回业务状态，
例如 `"status": "success"`、`"status": "accepted"` 或任务状态。这些字段不是 API
传输层错误。

**错误**

```json
{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found: viking://resources/nonexistent/"
  },
  "time": 0.01
}
```

HTTP 错误始终使用顶层错误 envelope。资源解析、同步 reindex 等同步处理失败会返回非 2xx
响应，顶层为 `status="error"`，并包含 `error` 对象。客户端不应通过
`result.status="error"` 判断请求失败。

请求校验失败，包括 JSON 格式错误、缺少必填字段和参数值非法，统一返回 HTTP `400`，
并使用 `error.code="INVALID_ARGUMENT"`。响应不会使用 FastAPI 原生的 `{"detail": ...}`
错误格式；当存在字段级校验信息时，会通过 `error.details.validation_errors` 返回。

Python HTTP SDK（`SyncHTTPClient` 和 `AsyncHTTPClient`）会把该 envelope 映射为对应的
`OpenVikingError` 子类。例如 `PROCESSING_ERROR` 会抛出 `ProcessingError`。

## CLI 输出格式

### Table 模式（默认）

列表数据渲染为表格，非列表数据 fallback 到格式化 JSON：

```bash
openviking ls viking://resources/
# name          size  mode  isDir  uri
# .abstract.md  100   420   False  viking://resources/.abstract.md
```

### JSON 模式（`--output json`）

所有命令输出格式化 JSON，与 API 响应的 `result` 结构一致：

```bash
openviking -o json ls viking://resources/
# [{ "name": "...", "size": 100, ... }, ...]
```

可在 `ovcli.conf` 中设置默认输出格式：

```json
{
  "url": "http://localhost:1933",
  "output": "json"
}
```

### 紧凑模式（`--compact`, `-c`）

- 当 `--output=json` 时：紧凑 JSON 格式 + `{ok, result}` 包装，适用于脚本
- 当 `--output=table` 时：对表格输出采取精简表示（如去除空列等）

**JSON 输出 - 成功**

```json
{"ok": true, "result": ...}
```

**JSON 输出 - 错误**

```json
{"ok": false, "error": {"code": "NOT_FOUND", "message": "Resource not found", "details": {}}}
```

### 特殊情况

- **字符串结果**（`read`、`abstract`、`overview`）：直接打印原文
- **None 结果**（`mkdir`、`rm`、`mv`）：无输出

### 退出码

| 退出码 | 含义 |
|--------|------|
| 0 | 成功 |
| 1 | 一般错误 |
| 2 | 配置错误 |
| 3 | 连接错误 |

## 错误码

| 错误码 | HTTP 状态码 | 说明 |
|--------|-------------|------|
| `OK` | 200 | 成功 |
| `INVALID_ARGUMENT` | 400 | 无效参数 |
| `INVALID_URI` | 400 | 无效的 Viking URI 格式 |
| `NOT_FOUND` | 404 | 资源未找到 |
| `ALREADY_EXISTS` | 409 | 资源已存在 |
| `UNAUTHENTICATED` | 401 | 缺少或无效的 API Key |
| `PERMISSION_DENIED` | 403 | 权限不足 |
| `RESOURCE_EXHAUSTED` | 429 | 超出速率限制 |
| `FAILED_PRECONDITION` | 412 | 前置条件不满足 |
| `CONFLICT` | 409 | 操作与正在进行的任务或已有状态冲突 |
| `DEADLINE_EXCEEDED` | 504 | 操作超时 |
| `UNAVAILABLE` | 503 | 服务不可用 |
| `PROCESSING_ERROR` | 500 | 资源或语义处理失败 |
| `INTERNAL` | 500 | 内部服务器错误 |
| `UNIMPLEMENTED` | 501 | 功能未实现 |
| `EMBEDDING_FAILED` | 500 | Embedding 生成失败 |
| `VLM_FAILED` | 500 | VLM 调用失败 |
| `SESSION_EXPIRED` | 410 | 会话已过期 |

## API 端点

### 系统

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查（无需认证） |
| GET | `/ready` | 就绪探针（无需认证） |
| GET | `/metrics` | Prometheus 指标导出 |
| GET | `/api/v1/system/status` | 系统状态 |
| POST | `/api/v1/system/wait` | 等待处理完成 |

### 资源

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/resources/temp_upload` | 裸 HTTP 导入资源 / pack 时上传本地文件 |
| POST | `/api/v1/resources` | 添加资源 |
| POST | `/api/v1/skills` | 添加技能 |
| POST | `/api/v1/pack/export` | 导出 .ovpack |
| POST | `/api/v1/pack/import` | 导入 .ovpack |

### 文件系统

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/fs/ls` | 列出目录 |
| GET | `/api/v1/fs/tree` | 目录树 |
| GET | `/api/v1/fs/stat` | 资源状态 |
| POST | `/api/v1/fs/mkdir` | 创建目录 |
| DELETE | `/api/v1/fs` | 删除资源 |
| POST | `/api/v1/fs/mv` | 移动资源 |

### 内容

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/content/read` | 读取完整内容（L2） |
| GET | `/api/v1/content/abstract` | 读取摘要（L0） |
| GET | `/api/v1/content/overview` | 读取概览（L1） |
| GET | `/api/v1/content/download` | 下载原始文件字节流 |
| POST | `/api/v1/content/write` | 修改已有文件并自动刷新语义与向量 |
| POST | `/api/v1/content/reindex` | 重新构建已有内容的语义/向量索引 |

### 搜索

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/search/find` | 语义搜索 |
| POST | `/api/v1/search/search` | 上下文感知搜索 |
| POST | `/api/v1/search/grep` | 模式搜索 |
| POST | `/api/v1/search/glob` | 文件模式匹配 |

### 关联

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/relations` | 获取关联 |
| POST | `/api/v1/relations/link` | 创建链接 |
| DELETE | `/api/v1/relations/link` | 删除链接 |

### 会话

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/sessions` | 创建会话 |
| GET | `/api/v1/sessions` | 列出会话 |
| GET | `/api/v1/sessions/{id}` | 获取会话 |
| GET | `/api/v1/sessions/{id}/context` | 获取组装后的会话上下文 |
| DELETE | `/api/v1/sessions/{id}` | 删除会话 |
| POST | `/api/v1/sessions/{id}/commit` | 提交会话 |
| POST | `/api/v1/sessions/{id}/extract` | 从会话提取记忆 |
| POST | `/api/v1/sessions/{id}/messages` | 添加消息 |
| POST | `/api/v1/sessions/{id}/used` | 记录实际使用的上下文 / 技能 |
| GET | `/api/v1/sessions/{id}/archives/{archive_id}` | 获取特定会话归档 |

### 任务

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/tasks/{task_id}` | 获取后台任务状态 |
| GET | `/api/v1/tasks` | 列出后台任务 |

### Observer

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/observer/queue` | 队列状态 |
| GET | `/api/v1/observer/vikingdb` | VikingDB 状态 |
| GET | `/api/v1/observer/models` | 模型状态（VLM / embedding / rerank） |
| GET | `/api/v1/observer/lock` | 锁子系统状态 |
| GET | `/api/v1/observer/retrieval` | 检索子系统状态 |
| GET | `/api/v1/observer/system` | 系统状态 |

### 调试

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/debug/health` | 快速健康检查 |
| GET | `/api/v1/debug/vector/scroll` | 分页查看向量记录 |
| GET | `/api/v1/debug/vector/count` | 统计向量记录数量 |

### 管理员（多租户）

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/admin/accounts` | 创建工作区 + 首个 admin（ROOT） |
| GET | `/api/v1/admin/accounts` | 列出工作区（ROOT） |
| DELETE | `/api/v1/admin/accounts/{account_id}` | 删除工作区（ROOT） |
| POST | `/api/v1/admin/accounts/{account_id}/users` | 注册用户（ROOT, ADMIN） |
| GET | `/api/v1/admin/accounts/{account_id}/users` | 列出用户（ROOT, ADMIN） |
| DELETE | `/api/v1/admin/accounts/{account_id}/users/{user_id}` | 移除用户（ROOT, ADMIN） |
| PUT | `/api/v1/admin/accounts/{account_id}/users/{user_id}/role` | 修改用户角色（ROOT） |
| POST | `/api/v1/admin/accounts/{account_id}/users/{user_id}/key` | 重新生成 User Key（ROOT, ADMIN） |

## 相关文档

- [资源管理](02-resources.md) - 资源管理 API
- [检索](06-retrieval.md) - 搜索 API
- [文件系统](03-filesystem.md) - 文件系统操作
- [会话管理](05-sessions.md) - 会话管理
- [技能](04-skills.md) - 技能管理
- [系统](07-system.md) - 系统和监控 API
- [指标与 Metrics](09-metrics.md) - Prometheus 指标导出与抓取说明
- [管理员](08-admin.md) - 多租户管理 API