diff --git a/retrieval.go b/retrieval.go
new file mode 100644
index 0000000..1f8e286
--- /dev/null
+++ b/retrieval.go
@@ -0,0 +1,46 @@
+package core
+
+import "context"
+
+// ---- 检索管线组件契约（设计 4.12：查询 → Embedding → 混合检索(向量+全文) → Rerank → TopK → 注入）----
+// 契约先行：实现按档位组合（嵌入式档=分块+FTS5+进程内向量扫描；PG 档可换
+// tsvector/pgvector）；管线编排见 backend internal/rag。
+
+// Chunk 是分块结果（Chunker 输出；Index 为文档内序号）。
+type Chunk struct {
+	Text  string `json:"text"`
+	Index int    `json:"index"`
+}
+
+// Chunker 把解析文档切分为检索块（策略由实现决定；空实现=整文档单块）。
+type Chunker interface {
+	Chunk(doc ParsedDocument) []Chunk
+}
+
+// EmbeddingProvider 文本批量 → 向量（OpenAI 兼容 /embeddings 或插件提供）。
+type EmbeddingProvider interface {
+	Embed(ctx context.Context, texts []string) ([][]float32, error)
+}
+
+// VectorIndex 向量存取；实现负责租户过滤（owner 本人 + 共享）。
+type VectorIndex interface {
+	Upsert(ctx context.Context, owner, docID, ref ID, vec []float32) error
+	DeleteByRef(ctx context.Context, owner ID, ref ID) error
+	// Search 按余弦相似度降序返回命中。
+	Search(ctx context.Context, owner ID, vec []float32, topK int, filter RetrievalQuery) ([]RetrievalHit, error)
+}
+
+// Reranker 对候选重排序；未配置时管线跳过（排序退化为混合分）。
+type Reranker interface {
+	Rerank(ctx context.Context, query string, docs []KnowledgeDoc, topK int) ([]KnowledgeDoc, error)
+}
+
+// Retriever 统一检索入口：实现决定全文/向量/混合与是否 rerank。
+type Retriever interface {
+	Retrieve(ctx context.Context, owner ID, q RetrievalQuery) ([]RetrievalHit, error)
+}
+
+// DocumentIndexer 检索索引写入（分块 + 全文 + 可选向量）；upload/工件产物统一走此入口。
+type DocumentIndexer interface {
+	IndexDocument(owner ID, projectID ID, source, title, ref, plainText string) error
+}