# 只读知识库 API 0.1.0

基址是 HTTPS 域名根部，不含 `/api`。正文仅在 Bearer 认证后返回；权限由服务端 reader 的 prefixes 强制约束。

| GET 路径 | 参数 | 返回 |
|---|---|---|
| `/health` | 无；无需令牌 | 服务名、服务版本和 ok；不等于正文就绪 |
| `/api/manifest` | 无 | status、version、document_count、entry_documents、read_only、formats |
| `/api/tree` | prefix、offset=0、limit=50（最多100） | 相对路径、字节数、SHA256、修改时间，以及 total、offset、limit、version |
| `/api/search` | q（1–200字符）、prefix、offset=0、limit=20（最多50） | 路径、命中行、片段、SHA256、version，以及分页元数据 |
| `/api/document` | path、start=1、lines=100（最多200）、version | content、行范围、total_lines、truncated、next_start、SHA256、修改时间、version、citation |

路径只允许知识根目录内的显式相对路径；不接受绝对路径、隐藏路径、反斜杠、冒号、百分号或 `..`。不提供写入端点。

目录源版本是内容清单 SHA256；Git 源版本是提交对象 ID。SHA256 是文档原始字节摘要，content 是去除 BOM、按行选取并用 LF 拼接的文本片段，不能直接用片段计算全文摘要。

`status`：ready=有可读正文；empty=可访问但无可读正文；not_configured=来源未启用；source_unavailable=来源不可用。Git 源只读已提交普通 blob，跳过符号链接、子模块、LFS 指针、隐藏文件和不支持的格式，不执行 pull/push/checkout。

错误仅返回固定错误码：400 参数错误；401 认证失败；404 文档或路径不存在；409 版本变化；413 单行超过返回上限；429 限流；503 来源未准备好。遇到 409 必须重新搜索；遇到 429 暂停至少 60 秒后再按需调用，客户端本身不自动重试。

`citation` 含 path、start_line、end_line、version。检索片段不保证完整，阅读时检查 truncated 和 next_start。单次正文最多 128 KiB；分页目录默认最多 5000 个已索引文档、单文档 1 MiB、总计 32 MiB（可由服务器管理员调整）。