feat: 第三优先级完善 — CI/CD、PyPI、pre-commit、CHANGELOG、贡献指南、基准测试、ADR

docs/api_reference.md

@@ -0,0 +1,68 @@
+# md-vector-db API 参考文档
+
+## REST API
+
+- **Base URL**: `http://localhost:8000/api/v1`
+- **认证**: `X-API-Key` Header（取决于 `MD_VECTOR_API_KEY` 环境变量）
+- **速率限制**: 60s 窗口内最多 30 请求
+
+### GET /health — 健康检查
+
+无需认证。
+
+```json
+{
+  "status": "ok",
+  "checks": {
+    "chromadb": {"status": "ok", "count": 1240},
+    "embedder": {"status": "ok", "dimension": 512}
+  }
+}
+```
+
+### GET /collections — 列出集合
+
+需 API Key。返回 `{"collections": [{"name": "...", "count": N}, ...]}`。
+
+### POST /search — 语义检索
+
+| 字段 | 类型 | 必填 | 约束 |
+|------|------|------|------|
+| query | string | ✅ | 1-2000 字符 |
+| top_k | int | ❌ | 1-100，默认 10 |
+| collection | string | ❌ | ≤128 字符 |
+
+返回 `{"results": [...], "collection": "..."}`，每条结果含 `id`, `content`, `source_file`, `section_title`, `heading_level`, `score`。
+
+### POST /ingest — 入库文档
+
+| 字段 | 类型 | 必填 | 约束 |
+|------|------|------|------|
+| file_path | string | 二选一 | 安全路径 |
+| content | string | 二选一 | ≤500KB |
+| file_name | string | 推荐 | 1-255 字符 |
+| collection | string | ❌ | ≤128 字符 |
+
+返回 `{"status": "ok", "chunks": N, "file": "...", "collection": "..."}`。
+
+### DELETE /documents/{file_name} — 删除文档
+
+查询参数: `collection` (可选)。
+
+| 状态码 | 含义 |
+|--------|------|
+| 200 | 删除成功 |
+| 400 | file_name 不合法 |
+| 401 | API Key 无效 |
+| 404 | 文档不存在 |
+
+## CLI 命令
+
+```bash
+md-vector-db ingest <文件> --incremental --force
+md-vector-db ingest-dir <目录> -C <集合>
+md-vector-db search "<查询>" -k 10 --mode hybrid --json
+md-vector-db stats -C <集合>
+md-vector-db export -o output.json -f json
+md-vector-db serve -p 8000
+```

docs/architecture.md

@@ -0,0 +1,43 @@
+# 架构决策记录 (ADR)
+
+## ADR-1: 为什么选择 ChromaDB？
+
+**日期**: 2026-07-05 | **状态**: 已采纳
+
+**背景**: 需要一个嵌入式向量数据库来持久化文档嵌入。
+
+**候选**: ChromaDB（嵌入式 SQLite）、Qdrant（独立服务）、FAISS（纯内存）、Milvus（生产级集群）
+
+**决策**: ChromaDB。零运维成本远超吞吐量考量。内置 Collection 概念映射多知识库场景。
+
+**代价**: 高并发下逊于 Qdrant/Milvus。未来可透明迁移（Embedder/Searcher 已隔离 ChromaDB 依赖）。
+
+---
+
+## ADR-2: 为什么默认 bge-small-zh-v1.5？
+
+**日期**: 2026-07-05 | **状态**: 已采纳
+
+**候选**: bge-small-zh-v1.5 (512维/23M)、bge-large-zh-v1.5 (1024维/324M)、text2vec-large-chinese、m3e-base
+
+**决策**: bge-small-zh-v1.5。RTX 4060 上 729 chunks 嵌入仅 1.8s，日常精度足够。高精度场景可切换 large 模型或 OpenAI API。
+
+---
+
+## ADR-3: 为什么采用 Protocol 而非 ABC？
+
+**日期**: 2026-07-05 | **状态**: 已采纳
+
+**候选**: typing.Protocol（结构化子类型）、abc.ABC（名义子类型）、Callable（丢失类型信息）
+
+**决策**: Protocol。外部模块无需依赖本项目源码即可实现 Splitter/Embedder，对插件化友好。
+
+---
+
+## ADR-4: 为什么使用 rank-bm25 而非集成搜索引擎？
+
+**日期**: 2026-07-11 | **状态**: 已采纳
+
+**候选**: rank-bm25（纯 Python BM25）、Elasticsearch（外部服务）、Whoosh（纯 Python 全文搜索）
+
+**决策**: rank-bm25。零运维、轻量、与现有 ChromaDB 架构匹配。在向量候选上做 BM25 重打分（而非全文索引所有文档），兼顾性能和精度。