# 后端接口契约（开发版）

> 本文档记录当前前后端联调使用的接口壳子。业务服务尚未实现，最终字段以 FastAPI 运行时生成的 OpenAPI 为准。

## 契约入口

- Swagger UI：`GET /docs`
- OpenAPI：`GET /openapi.json`
- 所有普通接口使用 JSON。
- Chat 和 Agent 实时事件使用 `text/event-stream`（SSE）。
- 内部时间统一使用 UTC ISO 8601。
- ID 使用稳定业务 ID，不使用文件路径代替 ID。

## 接口清单

### System

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/health` | Sidecar 健康检查 |
| GET | `/api/status` | 获取服务名称、版本和环境 |

### Notes 与 Search

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/api/notes` | 获取笔记列表 |
| POST | `/api/notes` | 创建笔记 |
| GET | `/api/notes/{note_id}` | 获取笔记及 Block |
| PATCH | `/api/notes/{note_id}` | 更新笔记 |
| DELETE | `/api/notes/{note_id}` | 删除笔记 |
| POST | `/api/notes/{note_id}/move` | 移动笔记 |
| POST | `/api/search` | FTS、Vector 或 Hybrid 检索 |

### Chat、Agent 与 Tool

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| POST | `/api/chat` | 发起聊天并返回 ModelEvent SSE |
| GET | `/api/agent/runs` | 获取 Agent Run 列表 |
| POST | `/api/agent/runs` | 创建 Agent Run |
| GET | `/api/agent/runs/{run_id}` | 获取 Agent Run 状态与 Trace 摘要 |
| POST | `/api/agent/runs/{run_id}/cancel` | 取消 Agent Run |
| GET | `/api/agent/runs/{run_id}/events` | 订阅 AgentEvent SSE |
| POST | `/api/agent/runs/{run_id}/permissions/{request_id}` | 响应 Tool 权限确认 |
| GET | `/api/tools` | 获取已注册 Tool Definition |

### Skill 与 Plugin

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/api/skills` | 获取 Skill 列表及状态 |
| POST | `/api/skills/install` | 安装 Skill |
| GET | `/api/skills/{skill_id}` | 获取 Skill Manifest 与状态 |
| POST | `/api/skills/{skill_id}/enable` | 启用 Skill |
| POST | `/api/skills/{skill_id}/disable` | 停用 Skill |
| DELETE | `/api/skills/{skill_id}` | 卸载 Skill |
| GET | `/api/plugins` | 获取 Plugin 列表及状态 |
| POST | `/api/plugins/install` | 安装 Plugin |
| GET | `/api/plugins/{plugin_id}` | 获取 Plugin Manifest 与状态 |
| POST | `/api/plugins/{plugin_id}/enable` | 启用 Plugin |
| POST | `/api/plugins/{plugin_id}/disable` | 停用 Plugin |
| PUT | `/api/plugins/{plugin_id}/permissions` | 设置 Plugin 已授权权限 |
| DELETE | `/api/plugins/{plugin_id}` | 卸载 Plugin |

### Provider

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/api/providers` | 获取 Provider 配置列表 |
| POST | `/api/providers` | 新建 Provider 配置 |
| GET | `/api/providers/{provider_id}` | 获取 Provider 配置 |
| PATCH | `/api/providers/{provider_id}` | 更新 Provider 配置 |
| DELETE | `/api/providers/{provider_id}` | 删除 Provider 配置 |
| GET | `/api/providers/{provider_id}/models` | 获取模型及 Capability 列表 |
| POST | `/api/providers/test` | 测试 Provider 连接 |

Provider Contract 只传递 `credential_id` 或临时 `credential_context_id`。当前前后端开发阶段通过独立的 `PUT /api/credentials/{credential_id}` 接收 API Key，并立即加密落盘；该接口只返回配置状态，不返回密钥。Provider CRUD、模型列表和测试接口均不携带明文 API Key。Tauri 集成后由 Stronghold 接管存储实现。

### Tasks、Media 与 Index

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/api/tasks` | 获取任务列表 |
| POST | `/api/tasks` | 创建任务 |
| GET | `/api/tasks/{task_id}` | 获取任务 |
| PATCH | `/api/tasks/{task_id}` | 更新任务 |
| DELETE | `/api/tasks/{task_id}` | 删除任务 |
| POST | `/api/media/transcriptions` | 创建音频转写任务 |
| GET | `/api/media/transcriptions/{job_id}` | 获取转写任务状态 |
| GET | `/api/index/status` | 获取索引服务状态 |
| POST | `/api/index/rebuild` | 创建索引重建任务 |
| GET | `/api/index/jobs/{job_id}` | 获取索引任务状态 |

## 统一错误

所有普通 HTTP 错误统一返回：

```json
{
  "error": {
    "code": "NOT_IMPLEMENTED",
    "message": "The contract is available, but its business service is not implemented.",
    "details": {}
  }
}
```

当前接口主要返回：

- `422 VALIDATION_ERROR`：请求字段不符合 Pydantic Contract；
- `404 RESOURCE_NOT_FOUND`：路由或资源不存在。
- `409`：资源冲突、依赖缺失或扩展尚未获得权限；
- `429 AGENT_CAPACITY_EXCEEDED`：活动 Agent Run 达到上限。

前端只根据 `error.code` 判断业务错误，不解析第三方 SDK 的原始异常文本。

## SSE 约定

每条 SSE 包含事件名和对应 JSON Contract：

```text
event: TextDelta
data: {"event":"TextDelta","sequence":1,"data":{"text":"..."},"timestamp":"..."}
```

ModelEvent 类型：

```text
TextDelta
ThinkingDelta
ToolCallStart
ToolCallDelta
ToolCallEnd
Usage
Error
Done
```

AgentEvent 类型：

```text
RunStarted
TextDelta
ThinkingDelta
ToolCall
ToolResult
PermissionRequired
Usage
Citation
RunCompleted
RunFailed
RunCancelled
```

## 当前实现状态

- Chat、Agent Run、Agent Events、Tool 列表、Provider 配置生命周期、模型列表和连接测试已经接入 AI Core。
- Provider Adapter 当前包含 Mock、真正增量 SSE 的 OpenAI-Compatible Chat Completions，以及 Ollama JSONL Streaming。
- Notes、Search、Index、Skills、Plugins、Tasks 和 Provider 生命周期均已接入业务服务。
- Note Move 保留 `note_id`；Citation 的字符偏移统一使用 UTF-16 code unit，供浏览器编辑器直接定位。
- Plugin 启用前必须通过权限接口记录授权，未知权限默认拒绝。
- Attachment Tool 读取 Host 管理的 `attachments` 目录；音频接口读取 Host 生成的转写文本，真实本地语音模型在第二阶段接入。
- 接入业务模块时保持当前路径和 Contract，不在 Router 中直接实现数据库、Provider 或 Agent 逻辑。