# https://github.com/cocoindex-io/cocoindex 项目说明书

生成时间：2026-06-23 00:54:19 UTC

## 目录

- [概览与系统架构](#page-1)
- [核心概念与编程模型](#page-2)
- [连接器、Ops 与集成](#page-3)
- [高级主题、运维与扩展](#page-4)

<a id='page-1'></a>

## 概览与系统架构

### 相关页面

相关主题：[核心概念与编程模型](#page-2), [高级主题、运维与扩展](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [examples/docs_to_knowledge_graph/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/docs_to_knowledge_graph/README.md)
- [examples/rust/files_transform/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/files_transform/README.md)
- [examples/multi_codebase_summarization/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/multi_codebase_summarization/README.md)
- [examples/pdf_to_markdown/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/pdf_to_markdown/README.md)
- [examples/text_embedding_lancedb/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_lancedb/README.md)
- [examples/rust/pdf_to_markdown/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/pdf_to_markdown/README.md)
- [examples/rust/hn_trending_topics/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/hn_trending_topics/README.md)
- [examples/rust/conversation_to_knowledge/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/conversation_to_knowledge/README.md)
- [examples/rust/kafka_consume/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/kafka_consume/README.md)
- [examples/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding/README.md)
- [examples/rust/paper_metadata/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/paper_metadata/README.md)
- [rust/code_match/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/rust/code_match/README.md)
</details>

# 概览与系统架构

## 项目定位与目标

CocoIndex 是一个面向增量数据处理与索引构建的 ETL 框架，核心目标是把"源数据 → 自定义转换 → 目标存储"这一过程声明化、可观测、且天然支持增量重算。从仓库内的多个示例来看，它覆盖了三类典型工作负载：

- **文档嵌入与检索（RAG）**：把 Markdown / PDF 切分、向量化后写入向量库或关系库，例如 [examples/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding/README.md)、[examples/text_embedding_lancedb/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_lancedb/README.md)、[examples/text_embedding_qdrant/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_qdrant/README.md) 与 [examples/text_embedding_turbopuffer/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_turbopuffer/README.md)。
- **代码与知识图谱构建**：使用 LLM + 结构化输出（`instructor` / `litellm`）从文档或代码中抽取实体与三元组，写入图数据库，例如 [examples/docs_to_knowledge_graph/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/docs_to_knowledge_graph/README.md)、[examples/multi_codebase_summarization/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/multi_codebase_summarization/README.md)。
- **流式 / 实时接入**：通过 `LiveMapView` 与 `mount_each_live` 持续消费外部消息流，例如 Kafka 主题（[examples/rust/kafka_consume/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/kafka_consume/README.md)）。

整个系统强调"声明式数据流 + 自动增量"，用户只需描述一次管道，框架负责追踪每个步骤的输入指纹并跳过未变更的节点。

## 双 SDK 与统一语义

仓库同时维护 Python 与 Rust 两套 SDK，二者在概念层面对齐，但在 API 风格上做出适配：

- **Python SDK** 使用装饰器（`@coco.fn`、`@cocoindex`）把函数挂到流图上，源/目标通过 `localfs`、`postgres`、`kafka` 等模块导入。例如 [examples/files_transform/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/files_transform/README.md) 中的 `@coco.fn(memo=True) process_file` 与 `localfs.declare_file`。
- **Rust SDK** 用过程宏（`#[cocoindex::function(memo)]`）与显式的 `&Ctx` 上下文参数，并通过 `cocoindex::fs::walk`、`cocoindex::postgres`、`cocoindex::kafka` 等模块组装。社区正在跟踪 [issue #1667](https://github.com/cocoindex-io/cocoindex/issues/1667) —— 提议打造一套与 Python SDK 等价的、惯用的 Rust SDK，沿用 proc-macro + 显式 `&Ctx` 思路，提供记忆化、作用域组件、带指纹的目录遍历等能力。

两套 SDK 共享同一套核心算子，例如 `IdGenerator`、`entity_resolution` 等都能在两侧复用（见 [examples/rust/conversation_to_knowledge/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/conversation_to_knowledge/README.md) 与 [examples/rust/hn_trending_topics/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/hn_trending_topics/README.md) 的对比表）。

## 核心架构与执行模式

CocoIndex 的执行模型围绕 **Source → Function(memo) → Target** 三个角色展开。数据流的关键约束是：

1. **Source（源）**：以 `LiveMapView` 形式暴露"键 → 当前值"映射，支持两种模式：
   - **Catch-up（追平）**：扫描到高水位后退出，例如 `cocoindex update main`（见 [examples/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding/README.md)）。
   - **Live（长连接）**：追平后继续监听变化，使用 `cocoindex update -L main`，在源上声明 `live=True`（见 [examples/text_embedding_lancedb/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_lancedb/README.md)）。
2. **Function / Component（计算节点）**：所有自定义转换默认是纯函数，其输出按输入内容缓存。Rust 端用 `#[cocoindex::function(memo)]`，Python 端用 `@coco.fn(memo=True)`（[examples/rust/files_transform/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/files_transform/README.md)）。
3. **Target（目标）**：声明式目标（如 `DirTarget`、`postgres::mount_table_target`）负责把新结果写入、跳过未变更文件、删除已不存在的源对应产物。例如 [examples/rust/pdf_to_markdown/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/pdf_to_markdown/README.md) 中提到"删除源 PDF 时，对应输出 `.md` 会在下一次运行中自动移除"。

### 架构示意

```mermaid
flowchart LR
    Source[Source<br/>localfs / kafka / Google Drive] -->|LiveMapView| Ctx[Ctx / 函数注册器]
    Ctx -->|memo 键| Fn1[Function: parse<br/>pypdf / lopdf / docling]
    Fn1 -->|memo 键| Fn2[Function: LLM extract<br/>litellm + instructor]
    Fn2 -->|memo 键| Fn3[Function: embed<br/>sentence-transformers / fastembed]
    Fn3 --> Tgt[Target<br/>Postgres / LanceDB / Neo4j / FalkorDB / SurrealDB / Turbopuffer / Qdrant / Kafka]
    Tgt -->|reconcile| FS[(持久化存储)]
```

## 增量、记忆化与已知限制

增量处理是 CocoIndex 的最大价值。`memo=True` 让函数只在输入指纹变化时重跑；而声明式目标会自动对齐源/产物的对应关系（写入、更新、删除）。这在长流式工作负载下尤为关键，例如 [examples/rust/paper_metadata/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/paper_metadata/README.md) 在三张 Postgres 表上分别挂载 `mount_table_target`，而 [examples/rust/kafka_consume/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/kafka_consume/README.md) 在 catch-up 阶段会把日志压缩到每个 key 的最新值（tombstone 即删除）。

社区当前关注的几个工程化方向：

- **LanceDB 提交优化**（[issue #1429](https://github.com/cocoindex-io/cocoindex/issues/1429)）：当小批量追加频繁时，Lance 表的 fragment 会膨胀，需要在每若干千行后做 compaction 与索引优化。代码嵌入示例 [examples/code_embedding_lancedb/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/code_embedding_lancedb/README.md) 同样依赖 `./lancedb_data/` 目录的稳定写入语义。
- **Shadow Run / 预览**（[issue #1890](https://github.com/cocoindex-io/cocoindex/issues/1890)）：希望在分块策略或抽取 prompt 修改后，先以"影子模式"跑一遍，预览差异再决定是否落盘，以降低破坏管线的风险。
- **MCP 支持**（[issue #160](https://github.com/cocoindex-io/cocoindex/issues/160)）：社区期望把 CocoIndex 暴露为 MCP（Model Context Protocol）服务，让外部 agent 直接查询/触发增量管道。
- **代码匹配能力**：v1.0.13 在 `rust/code_match` 中增强了 tree-sitter 匹配，支持 bare keyword、anchored regex、fragment 范围与子节点剪枝（见 [rust/code_match/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/rust/code_match/README.md)），是后续代码知识图谱（[examples/multi_codebase_summarization/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/multi_codebase_summarization/README.md)）的基础设施之一。

## See Also

- 文本嵌入与 RAG 示例：[text_embedding](https://github.com/cocoindex-io/cocoindex/tree/main/examples/text_embedding)、[text_embedding_lancedb](https://github.com/cocoindex-io/cocoindex/tree/main/examples/text_embedding_lancedb)、[text_embedding_qdrant](https://github.com/cocoindex-io/cocoindex/tree/main/examples/text_embedding_qdrant)、[text_embedding_turbopuffer](https://github.com/cocoindex-io/cocoindex/tree/main/examples/text_embedding_turbopuffer)
- 知识图谱与多代码库：[docs_to_knowledge_graph](https://github.com/cocoindex-io/cocoindex/tree/main/examples/docs_to_knowledge_graph)、[meeting_notes_graph_neo4j](https://github.com/cocoindex-io/cocoindex/tree/main/examples/meeting_notes_graph_neo4j)、[meeting_notes_graph_falkordb](https://github.com/cocoindex-io/cocoindex/tree/main/examples/meeting_notes_graph_falkordb)、[multi_codebase_summarization](https://github.com/cocoindex-io/cocoindex/tree/main/examples/multi_codebase_summarization)
- Rust SDK 示例：[rust/files_transform](https://github.com/cocoindex-io/cocoindex/tree/main/examples/rust/files_transform)、[rust/pdf_to_markdown](https://github.com/cocoindex-io/cocoindex/tree/main/examples/rust/pdf_to_markdown)、[rust/hn_trending_topics](https://github.com/cocoindex-io/cocoindex/tree/main/examples/rust/hn_trending_topics)、[rust/conversation_to_knowledge](https://github.com/cocoindex-io/cocoindex/tree/main/examples/rust/conversation_to_knowledge)、[rust/kafka_consume](https://github.com/cocoindex-io/cocoindex/tree/main/examples/rust/kafka_consume)、[rust/paper_metadata](https://github.com/cocoindex-io/cocoindex/tree/main/examples/rust/paper_metadata)
- 相关 issue：#160 (MCP)、#1429 (LanceDB commit)、#1667 (Ergonomic Rust SDK)、#1890 (Shadow run / preview)

---

<a id='page-2'></a>

## 核心概念与编程模型

### 相关页面

相关主题：[概览与系统架构](#page-1), [连接器、Ops 与集成](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [examples/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding/README.md)
- [examples/files_transform/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/files_transform/README.md)
- [examples/multi_codebase_summarization/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/multi_codebase_summarization/README.md)
- [examples/rust/files_transform/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/files_transform/README.md)
- [examples/rust/paper_metadata/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/paper_metadata/README.md)
- [examples/docs_to_knowledge_graph/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/docs_to_knowledge_graph/README.md)
- [examples/rust/conversation_to_knowledge/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/conversation_to_knowledge/README.md)
- [examples/meeting_notes_graph_neo4j/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/meeting_notes_graph_neo4j/README.md)
</details>

# 核心概念与编程模型

CocoIndex 是一个面向增量数据处理与索引构建的编程框架。它将"源—计算—目标"抽象为声明式数据流（dataflow），并通过记忆化（memoization）让重复运行自动跳过未变更的部分。本页基于仓库内多个示例的 README 提炼其核心概念与编程模型。

## 1. 应用（App）与数据流（Flow）

CocoIndex 的顶层入口是 `App` 对象。Python 端通过 `coco.App(coco.AppConfig(name="..."), app_main, ...)` 注册一个应用，传入主函数 `app_main`；主函数内部按需挂载（`mount`）其它子函数，形成一棵树状的数据流图。资料来源：[examples/multi_codebase_summarization/README.md:1-10]() 中 `app_main` 会枚举子目录、对每个项目 `mount` `process_project`，再由 `process_project` 进一步驱动抽取、聚合与生成 Markdown 的步骤。

Rust SDK 采用对应的 proc-macro 形式：`#[cocoindex::function(...)]` 标记函数，调用者通过显式 `&Ctx` 上下文参数与函数组合，文件目录遍历则由 `cocoindex::fs::walk` 提供。资料来源：[examples/rust/paper_metadata/README.md:1-12]() 中给出了 Python `@coco.fn(memo=True)` 与 Rust `#[cocoindex::function(memo)]` 的对照。

## 2. 数据源（Source）与目标（Target）

数据流的两端分别是 Source 和 Target，二者都是声明式的、可增量协调（reconcile）的。

- **Source** 描述从哪里读取数据。例如 `localfs.walk_dir(..., live=True)` 会扫描本地目录并在 live 模式下持续监听文件变更。资料来源：[examples/files_transform/README.md:1-8]() 显示 `walk_dir` 监听 `data/` 目录并默认走实时模式；[examples/rust/files_transform/README.md:1-8]() 则说明 Rust 端使用 `cocoindex::fs::walk`。
- **Target** 描述将数据写入哪里。常见的有 `postgres.mount_table_target`、本地文件 `localfs.declare_file` 以及 Rust 中的 `DirTarget::declare_file` 与 `postgres::TableTarget`。Target 的关键特性是"幂等协调"：未变化的内容会被跳过，被删除的源对应的输出会被自动清理。资料来源：[examples/rust/files_transform/README.md:1-8]() 中明确说明 `DirTarget` 会写入/更新文件、跳过未变更文件，并在源 Markdown 被删除时**自动删除**对应输出；[examples/rust/pdf_to_markdown/README.md:1-10]() 中也有相同描述。

## 3. 函数（Function）与记忆化（Memoization）

被 `@coco.fn`（Python）或 `#[cocoindex::function(memo)]`（Rust）装饰的函数会进入增量记忆化体系：函数的输入（包括其依赖的 Source 状态）构成一个指纹（fingerprint），运行时若指纹未变则直接复用上次结果。这是 CocoIndex 实现"只重做必要工作"的核心机制。资料来源：[examples/multi_codebase_summarization/README.md:1-10]() 中提到"**Incremental Processing**: CocoIndex handles caching - only re-processes changed files"；[examples/rust/hn_trending_topics/README.md:1-10]() 也用同一句话总结增量收益的来源。

函数可以分层组合：上层函数通过 `mount` 或 `use_mount` 复用下层函数。在 Mermaid 渲染中，CocoIndex 用粗体表示被 `@coco.fn`/`#[cocoindex::function(...)]` 标记的节点，用粗箭头 `==>` 表示 `mount`/`use_mount` 关系。资料来源：[examples/multi_codebase_summarization/README.md:1-10]() 中给出了完整示例图。

## 4. 增量处理与运行模式

CocoIndex 提供两种主要运行模式，统一通过 `cocoindex update` 命令触发：

- **追赶运行（catch-up）**：`cocoindex update main`，扫描源、对齐变更后退出。资料来源：[examples/text_embedding/README.md:1-8]()。
- **实时运行（live）**：`cocoindex update -L main`，在追赶后继续监听源变化。前提是 Source 声明了 `live=True`，例如 `walk_dir(..., live=True)`。资料来源：[examples/files_transform/README.md:1-8]()。

其工作流可概括为：

```mermaid
flowchart LR
    A[Source<br/>walk_dir / fs::walk] --> B[Function<br/>@coco.fn memo=True]
    B --> C{指纹是否变化?}
    C -- 否 --> D[复用上次结果]
    C -- 是 --> E[执行计算<br/>LLM / Embedding / Chunking]
    E --> F[Target<br/>postgres / DirTarget]
    F --> G[幂等协调:<br/>写入新行, 跳过未变, 删除孤儿]
```

## 5. 进阶：实体解析与多步 LLM 流程

在构建知识图谱或富文本抽取时，常需要把同一概念的多个表述折叠为同一节点。CocoIndex 提供 `entity_resolution` 操作：先用嵌入模型生成向量索引，再用 LLM 做"成对判断"合并近义实体。资料来源：[examples/rust/conversation_to_knowledge/README.md:1-10]() 显示 Rust 端使用 `cocoindex::entity_resolution` 配合 `fastembed` 与 LLM 判别器完成人物/技术/组织去重；[examples/docs_to_knowledge_graph/README.md:1-10]() 中也指出，文档图谱可借助 `meeting_notes_graph_neo4j` 的实体解析模板来合并 "CocoIndex"/"Cocoindex" 这类近似名称。

此外，复杂任务常被拆为多步 LLM 流程：第一步识别说话人与元信息，第二步再抽取陈述与被提及实体。资料来源：[examples/rust/conversation_to_knowledge/README.md:1-10]() 明确给出"两轮 LLM + 实体解析"的范式。

## 6. 社区关注的演进方向

- **Rust SDK 的体面化（#1667）**：用户期待"显式 `&Ctx`、proc-macro 而非装饰器、保持记忆化与作用域语义"，这与 `examples/rust/*` 已展示的 `#[cocoindex::function(memo)]`、`cocoindex::fs::walk`、`cocoindex::entity_resolution` 等 API 方向一致。
- **预览/影子运行（#1890）**：希望在不改写目标的前提下预览 chunking 等变更将影响哪些行；目前尚未内置，需要通过单独 dry-run 目标或新操作来扩展。
- **LanceDB 写入优化（#1429）**：在大量小批量追加场景下，Target 层需周期性触发 compaction/索引优化以避免碎片化。
- **MCP 支持（#160）**：希望 CocoIndex 能以 MCP 形式暴露为外部 Agent 的工具。

## 7. 失败模式与使用注意

- **忘记开启 `live=True`**：Source 不会持续监听，运行会一次性退出。
- **目标存储未配置**：`POSTGRES_URL`、`TURBOPUFFER_API_KEY` 等环境变量缺失会导致连接失败。资料来源：[examples/text_embedding/README.md:1-8]() 与 [examples/text_embedding_turbopuffer/README.md:1-8]() 均要求 `.env` 中显式设置这些密钥。
- **Python 与 Rust 渲染差异**：例如 Markdown 渲染中 `pulldown-cmark` 与 `markdown-it-py` 输出非字节一致；Rust 端 `lopdf` 文本抽取也无法完全替代 `docling` 的结构化结果。资料来源：[examples/rust/files_transform/README.md:1-8]() 与 [examples/rust/pdf_to_markdown/README.md:1-10]()。
- **未建立向量索引**：`text_embedding` 示例不会自动创建 pgvector 索引，查询会走顺序扫描。资料来源：[examples/text_embedding/README.md:1-8]()。

## 另请参阅

- [示例：Text Embedding (Postgres)](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding/README.md)
- [示例：Files Transform](https://github.com/cocoindex-io/cocoindex/blob/main/examples/files_transform/README.md)
- [示例：Multi-Codebase Summarization](https://github.com/cocoindex-io/cocoindex/blob/main/examples/multi_codebase_summarization/README.md)
- [示例：Docs to Knowledge Graph (Neo4j)](https://github.com/cocoindex-io/cocoindex/blob/main/examples/docs_to_knowledge_graph/README.md)
- [示例：Meeting Notes Graph (Neo4j)](https://github.com/cocoindex-io/cocoindex/blob/main/examples/meeting_notes_graph_neo4j/README.md)

---

<a id='page-3'></a>

## 连接器、Ops 与集成

### 相关页面

相关主题：[核心概念与编程模型](#page-2), [高级主题、运维与扩展](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [examples/docs_to_knowledge_graph/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/docs_to_knowledge_graph/README.md)
- [examples/meeting_notes_graph_neo4j/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/meeting_notes_graph_neo4j/README.md)
- [examples/meeting_notes_graph_falkordb/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/meeting_notes_graph_falkordb/README.md)
- [examples/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding/README.md)
- [examples/text_embedding_lancedb/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_lancedb/README.md)
- [examples/text_embedding_qdrant/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_qdrant/README.md)
- [examples/text_embedding_turbopuffer/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_turbopuffer/README.md)
- [examples/pdf_to_markdown/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/pdf_to_markdown/README.md)
- [examples/multi_codebase_summarization/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/multi_codebase_summarization/README.md)
- [examples/rust/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/text_embedding/README.md)
- [examples/rust/paper_metadata/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/paper_metadata/README.md)
- [examples/rust/conversation_to_knowledge/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/conversation_to_knowledge/README.md)
- [examples/rust/hn_trending_topics/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/hn_trending_topics/README.md)
- [examples/rust/files_transform/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/files_transform/README.md)
- [examples/rust/pdf_to_markdown/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/pdf_to_markdown/README.md)
- [rust/code_match/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/rust/code_match/README.md)
</details>

# 连接器、Ops 与集成

## 概述

CocoIndex 是一个面向增量数据处理与知识构建的框架，其设计哲学围绕 **Sources（源）→ 函数 / Ops（计算）→ Targets（目标）** 的声明式管道展开。"连接器、Ops 与集成" 涵盖了三层内容：与外部存储系统对接的 **连接器（Connectors / Targets）**、对数据执行转换与推理的 **Ops 算子**，以及让整套管道可被嵌入不同运行环境（本地文件系统、Google Drive、YouTube 等）的 **集成模式**。两套官方 SDK（Python 与 Rust）共享相同的语义，使同一套业务逻辑可以在不同语言栈之间无缝迁移。

资料来源：[examples/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding/README.md)

## 核心连接器生态

CocoIndex 的连接器层覆盖了向量库、图数据库、关系型数据库、本地目录与远程文件系统等多种后端。下表梳理了仓库示例中已被验证的连接器及其典型用例：

| 类别 | 连接器 / 目标 | 示例入口 | 典型场景 |
|------|---------------|----------|----------|
| 向量 / 嵌入式数据库 | LanceDB | [examples/text_embedding_lancedb/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_lancedb/README.md) | 嵌入式存储、便携目录 `./lancedb_data/` |
| 向量 / 嵌入式数据库 | Qdrant | [examples/text_embedding_qdrant/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_qdrant/README.md) | 通过 HTTP/gRPC 写入向量与 FTS |
| 向量 / 嵌入式数据库 | Turbopuffer | [examples/text_embedding_turbopuffer/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_turbopuffer/README.md) | 服务化向量命名空间，支持区域选择 |
| 向量 / 关系型数据库 | Postgres + pgvector | [examples/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding/README.md), [examples/rust/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/text_embedding/README.md) | `TableTarget` + `declare_vector_index` |
| 图数据库 | Neo4j | [examples/docs_to_knowledge_graph/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/docs_to_knowledge_graph/README.md), [examples/meeting_notes_graph_neo4j/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/meeting_notes_graph_neo4j/README.md) | 属性图节点 / 关系写入，含 `MENTION` 与 `ATTENDED` 等边 |
| 图数据库 | FalkorDB | [examples/meeting_notes_graph_falkordb/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/meeting_notes_graph_falkordb/README.md) | 同 Neo4j 的图模式，Redis 后端 |
| 图数据库 | SurrealDB | [examples/rust/conversation_to_knowledge/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/conversation_to_knowledge/README.md) | 用于会话 / 声明图谱 |
| 本地目录 | 声明式 `DirTarget` / `localfs` | [examples/rust/files_transform/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/files_transform/README.md), [examples/rust/pdf_to_markdown/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/pdf_to_markdown/README.md) | 输出文件级产物，源删除时自动清理 |

这些连接器共同遵循 **声明式 + 增量** 模式：开发者只需声明节点 / 表结构，框架负责按指纹（fingerprint）决定是否写入、删除孤儿行，或跳过未变化的源文件。例如，`localfs.declare_file` 在源 Markdown 文件删除后会自动回收对应输出文件，而 `postgres.TableTarget` 会在源行消失时删除表中孤儿记录。

资料来源：[examples/rust/files_transform/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/files_transform/README.md)、[examples/rust/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/text_embedding/README.md)

## 关键 Ops 与转换

Ops 是管道中承担实际转换 / 推理的可调用单元，CocoIndex 提供了一组开箱即用的算子，也允许用户以函数形式扩展。

- **文本切分（Chunking）**：Python 侧使用 `RecursiveSplitter`，Rust 侧对应 `cocoindex_ops_text::RecursiveChunker`，二者均支持按语言定制规则（如 "abstract" 自定义语言）以适配学术论文摘要等场景。资料来源：[examples/rust/paper_metadata/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/paper_metadata/README.md)
- **实体解析（Entity Resolution）**：在 `meeting_notes_graph_neo4j`、`meeting_notes_graph_falkordb` 与 `conversation_to_knowledge` 示例中，框架先用嵌入模型生成候选，再调用 LLM 做配对判定，从而将 "Alice" / "Alice Chen" / "alice c." 合并为同一 `Person` 节点。资料来源：[examples/meeting_notes_graph_neo4j/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/meeting_notes_graph_neo4j/README.md)、[examples/rust/conversation_to_knowledge/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/conversation_to_knowledge/README.md)
- **代码匹配（Code Match）**：仓库内置的 `rust/code_match` 提供 30 余种语言（TypeScript、Rust、Go、SQL、HTML、CSS、JSON、YAML 等）的扁平词法分析器，支持 metavar 捕获、跨行容忍、前导 / 尾部容差、正则匹配以及预过滤索引，但尚不支持重写与子模式量化。资料来源：[rust/code_match/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/rust/code_match/README.md)、[rust/code_match/src/lang/mod.rs](https://github.com/cocoindex-io/cocoindex/blob/main/rust/code_match/src/lang/mod.rs)
- **PDF → Markdown**：Python 侧使用 docling 的 ML 文档理解流水线；Rust 侧由于缺少等价方案，使用 `lopdf` 进行纯文本提取，并在 README 中明确标注质量差异。资料来源：[examples/pdf_to_markdown/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/pdf_to_markdown/README.md)、[examples/rust/pdf_to_markdown/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/pdf_to_markdown/README.md)
- **多代码库摘要**：使用 `instructor` + LiteLLM 让 LLM 直接产出 Mermaid 语法，其中粗体标注 `@coco.fn` 函数，粗箭头（`==>`）表达 `mount`/`use_mount` 调用关系。资料来源：[examples/multi_codebase_summarization/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/multi_codebase_summarization/README.md)

## 集成模式与跨语言 SDK

CocoIndex 的集成关注三个维度：**源接入、计算编排、目标写入**，并通过 Python 与 Rust 两套 SDK 提供等价能力。

### 源接入

源既可以是本地路径（如 `cocoindex::fs::walk` 对应 Python `localfs.walk_dir`，二者均支持 glob 模式与指纹缓存），也可以是远程 API。例如 `hn_trending_topics` 通过 Algolia HN API 拉取线程与评论；`conversation_to_knowledge` 则先用 `yt-dlp` 抓取 YouTube 音频，再调用 AssemblyAI REST 接口生成对话者分离的转写。资料来源：[examples/rust/hn_trending_topics/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/hn_trending_topics/README.md)、[examples/rust/conversation_to_knowledge/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/conversation_to_knowledge/README.md)

### 计算编排

Python 侧通过 `@coco.fn(memo=True)` 装饰器实现记忆化函数；Rust 侧改用 `#[cocoindex::function(memo)]` 过程宏，并通过显式 `&Ctx` 注入上下文（社区 Issue #1667 正在推动更符合 Rust 习惯的 API 形态）。`IdGenerator`、作用域组件等基础能力在两套 SDK 中保持一致语义，确保 Python 与 Rust 端口可以共享同一增量视图。资料来源：[examples/rust/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/text_embedding/README.md)

### 目标写入

所有写入都是声明式：声明一次 `TableTarget` 或 `DirTarget`，CocoIndex 会比较上次落盘状态与当前产物集，自动产生 **新增、更新、删除** 三类操作，从而避免手动清理逻辑。Live 模式（`cocoindex update -L`）在补齐差异后保持监听，源文件改动会立即触发相应更新。

资料来源：[examples/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding/README.md)、[examples/rust/files_transform/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/files_transform/README.md)

## 社区关注与演进方向

从社区讨论可以看到，连接器与集成层仍在快速演进：

- **#160 [FEATURE] Support MCP**：用户希望 CocoIndex 暴露为 MCP（Model Context Protocol）服务器，让 LLM 客户端可以直接调用其索引 / 查询能力，作为新的"集成面"。
- **#1429 [FEATURE] Optimize for LanceDB commit**：高频小批量追加场景下，Lance 表需要定期 [compaction](https://lance.org/guide/read_and_write/?h=compaction#compact-data-files) 才能保持读性能，社区呼吁在 `LanceTarget` 中内建自动压缩调度。
- **#1890 [FEATURE] shadow run / preview**：当分块策略或 Schema 调整时，用户希望在 **真正写入目标前** 预览差异（例如新增 / 修改 / 删除的行），以降低管线破坏风险。

最新发布的 **v1.0.13** 主要围绕 `code_match` 的匹配器与预过滤性能进行了一系列增强（裸关键字、锚定正则匹配、片段区间、子运行扫描剪枝等），表明 Ops 层与代码理解的集成仍是当前投入重点。资料来源：[rust/code_match/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/rust/code_match/README.md)

## See Also

- Rust SDK API 参考：`rust/cocoindex/src/`
- Ops 算子清单：`python/cocoindex/ops/`
- 图数据库集成示例：`examples/docs_to_knowledge_graph/`、`examples/meeting_notes_graph_neo4j/`
- 向量数据库集成示例：`examples/text_embedding_lancedb/`、`examples/text_embedding_qdrant/`、`examples/text_embedding_turbopuffer/`

---

<a id='page-4'></a>

## 高级主题、运维与扩展

### 相关页面

相关主题：[概览与系统架构](#page-1), [核心概念与编程模型](#page-2), [连接器、Ops 与集成](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [examples/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding/README.md)
- [examples/text_embedding_lancedb/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_lancedb/README.md)
- [examples/text_embedding_qdrant/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_qdrant/README.md)
- [examples/text_embedding_turbopuffer/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_turbopuffer/README.md)
- [examples/code_embedding_lancedb/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/code_embedding_lancedb/README.md)
- [examples/docs_to_knowledge_graph/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/docs_to_knowledge_graph/README.md)
- [examples/meeting_notes_graph_neo4j/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/meeting_notes_graph_neo4j/README.md)
- [examples/meeting_notes_graph_falkordb/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/meeting_notes_graph_falkordb/README.md)
- [examples/rust/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/text_embedding/README.md)
- [examples/rust/kafka_consume/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/kafka_consume/README.md)
- [examples/rust/files_transform/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/files_transform/README.md)
- [examples/rust/paper_metadata/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/paper_metadata/README.md)
- [examples/pdf_to_markdown/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/pdf_to_markdown/README.md)
- [examples/multi_codebase_summarization/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/multi_codebase_summarization/README.md)
- [rust/code_match/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/rust/code_match/README.md)
</details>

# 高级主题、运维与扩展

本页面面向已经熟悉 CocoIndex 基础概念（源、算子、目标、增量）的读者，聚焦于跨示例共享的运行模式、多语言 SDK 体系、多样化的存储后端，以及社区高频关注的扩展方向。

## 增量更新机制与运行模式

CocoIndex 的核心运维价值在于**自动化增量同步**。所有示例（Python 与 Rust）共享同一套运行语义：

- **追赶运行（catch-up）**：扫描所有输入源，将变更同步到目标后端后退出
- **实时运行（live）**：先执行追赶，然后持续监听源数据变更

在 Python 文本嵌入示例中，运行方式由源声明决定（`live=True` 时实时监听），CLI 仅切换模式 [examples/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding/README.md)：

```sh
cocoindex update main    # 追赶
cocoindex update -L main # 实时（live）
```

Rust SDK 同样提供 catch-up / live 两阶段语义：例如 `cocoindex::kafka::topic_as_map` 在 catch-up 模式下将日志压缩到每个 key 的最新值，live 模式则继续 `watch()` 新记录 [examples/rust/kafka_consume/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/kafka_consume/README.md)。

## 多语言 SDK 架构

CocoIndex 同时提供 Python 与 Rust 两套 SDK，二者在概念层一一对应，差异主要体现在语法风格上。

```mermaid
graph LR
    A[Python SDK<br/>@coco.fn / @coco.op] --> E[核心引擎与状态存储]
    C[Rust SDK<br/>#[cocoindex::function]<br/>proc macros] --> E
    E --> F[统一的目标后端]
```

主要映射关系（以文本嵌入为例）[examples/rust/text_embedding/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/text_embedding/README.md)：

| 维度 | Python | Rust |
|------|--------|------|
| 文件源 | `localfs.walk_dir` | `cocoindex::fs::walk` |
| 记忆化函数 | `@coco.fn(memo=True)` | `#[cocoindex::function(memo)]` |
| 目标声明 | `postgres.TableTarget` | `postgres::TableTarget` |
| 文本分块 | `RecursiveSplitter` | `RecursiveChunker` |
| LLM 提取 | `instructor` + `litellm` | `reqwest` → OpenAI JSON 模式 |

社区正在讨论改进 Rust SDK 的易用性（Issue #1667），希望提供更符合 Rust 习惯的 `&Ctx` 显式参数和过程宏。

## 多目标后端与场景选型

CocoIndex 通过统一的 `Target` 抽象兼容多种存储后端。下表汇总示例中使用的后端类型与典型场景：

| 后端 | 典型示例 | 适用场景与说明 |
|------|---------|----------------|
| Postgres + pgvector | `text_embedding` | 关系型数据库，可叠加向量索引，需部署 pgvector 扩展 |
| LanceDB | `text_embedding_lancedb`, `code_embedding_lancedb` | 嵌入式存储，数据落在 `./lancedb_data/`，零外部依赖、易移植 |
| Qdrant | `text_embedding_qdrant` | 专业向量数据库，提供 Dashboard |
| Turbopuffer | `text_embedding_turbopuffer` | 托管向量服务，按量计费，需 `TURBOPUFFER_API_KEY` |
| Neo4j | `docs_to_knowledge_graph`, `meeting_notes_graph_neo4j` | 属性图，适合 (subject, predicate, object) 三元组 |
| FalkorDB | `meeting_notes_graph_falkordb` | 轻量图数据库，Neo4j 的精简替代 |

LanceDB 作为嵌入式引擎特别适合本地与轻量部署——删除目录即可完全重置索引 [examples/text_embedding_lancedb/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_lancedb/README.md)。Turbopuffer 默认 region 为 `gcp-us-central1`，可通过 `TURBOPUFFER_REGION` 切换 [examples/text_embedding_turbopuffer/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_turbopuffer/README.md)。

## 运维实践与社区关注的扩展方向

**典型运维特征：**

- 源数据未变更时，记忆化（memo）自动跳过函数级计算 [examples/rust/files_transform/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/files_transform/README.md)
- 托管式目标（如 `DirTarget`、`TableTarget`）会清理孤立行——源被删除后输出自动消失 [examples/rust/files_transform/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/examples/rust/files_transform/README.md)
- LanceDB 在大量小批次追加场景下需要定期 compaction（见社区 Issue #1429）

**社区高频请求的扩展点：**

- **MCP 支持**（#160）：将 CocoIndex 流程作为 Model Context Protocol 服务对外暴露
- **Shadow run / 预览模式**（#1890）：在修改 chunking 等关键参数时，预览将产生的差异，避免破坏生产数据
- **LanceDB 提交优化**（#1429）：定期合并数据片段并重建索引，避免碎片化
- **Ergonomic Rust SDK**（#1667）：提供与 Python SDK 等价的语义、更 Rust 化的 API

**最新发布动态：** v1.0.13 重点增强了 `code_match` 模块，支持裸关键字、锚定正则匹配器、片段范围与子运行扫描剪枝；目前支持匹配与捕获（含前导/后导容差、descendant containment `\{{ … \}}`、预过滤与索引），重写能力与节点类型匹配器、子模式（`{ … }`、`|`、量词）以及规则 DSL 已在规划中 [rust/code_match/README.md](https://github.com/cocoindex-io/cocoindex/blob/main/rust/code_match/README.md)。

## See Also

- [项目概览](../README.md)
- [Python SDK 基础](./python_sdk_basics.md)
- [Rust SDK 入门](./rust_sdk_intro.md)
- [目标后端适配器](./targets.md)
- [增量与状态模型](./incremental_model.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：cocoindex-io/cocoindex

摘要：发现 17 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: v1.0.5。

## 1. 安装坑 · 失败模式：installation: v1.0.5

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v1.0.5
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.5
- 证据：failure_mode_cluster:github_release | https://github.com/cocoindex-io/cocoindex/releases/tag/v1.0.5 | v1.0.5

## 2. 配置坑 · 失败模式：configuration: v1.0.7

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.0.7
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.7
- 证据：failure_mode_cluster:github_release | https://github.com/cocoindex-io/cocoindex/releases/tag/v1.0.7 | v1.0.7

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/cocoindex-io/cocoindex | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/cocoindex-io/cocoindex | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/cocoindex-io/cocoindex | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/cocoindex-io/cocoindex | no_demo; severity=medium

## 7. 能力坑 · 失败模式：conceptual: [FEATURE] allow users to specify type hints for component states

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: [FEATURE] allow users to specify type hints for component states
- 对用户的影响：Developers may hit a documented source-backed failure mode: [FEATURE] allow users to specify type hints for component states
- 证据：failure_mode_cluster:github_issue | https://github.com/cocoindex-io/cocoindex/issues/2198 | [FEATURE] allow users to specify type hints for component states

## 8. 运行坑 · 失败模式：performance: v1.0.8

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v1.0.8
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.8
- 证据：failure_mode_cluster:github_release | https://github.com/cocoindex-io/cocoindex/releases/tag/v1.0.8 | v1.0.8

## 9. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/cocoindex-io/cocoindex | issue_or_pr_quality=unknown

## 10. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/cocoindex-io/cocoindex | release_recency=unknown

## 11. 维护坑 · 失败模式：maintenance: v1.0.10

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.0.10
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.10
- 证据：failure_mode_cluster:github_release | https://github.com/cocoindex-io/cocoindex/releases/tag/v1.0.10 | v1.0.10

## 12. 维护坑 · 失败模式：maintenance: v1.0.11

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.0.11
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.11
- 证据：failure_mode_cluster:github_release | https://github.com/cocoindex-io/cocoindex/releases/tag/v1.0.11 | v1.0.11

## 13. 维护坑 · 失败模式：maintenance: v1.0.12

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.0.12
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.12
- 证据：failure_mode_cluster:github_release | https://github.com/cocoindex-io/cocoindex/releases/tag/v1.0.12 | v1.0.12

## 14. 维护坑 · 失败模式：maintenance: v1.0.13

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.0.13
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.13
- 证据：failure_mode_cluster:github_release | https://github.com/cocoindex-io/cocoindex/releases/tag/v1.0.13 | v1.0.13

## 15. 维护坑 · 失败模式：maintenance: v1.0.4

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.0.4
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.4
- 证据：failure_mode_cluster:github_release | https://github.com/cocoindex-io/cocoindex/releases/tag/v1.0.4 | v1.0.4

## 16. 维护坑 · 失败模式：maintenance: v1.0.6

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.0.6
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.6
- 证据：failure_mode_cluster:github_release | https://github.com/cocoindex-io/cocoindex/releases/tag/v1.0.6 | v1.0.6

## 17. 维护坑 · 失败模式：maintenance: v1.0.9

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.0.9
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.9
- 证据：failure_mode_cluster:github_release | https://github.com/cocoindex-io/cocoindex/releases/tag/v1.0.9 | v1.0.9

<!-- canonical_name: cocoindex-io/cocoindex; human_manual_source: deepwiki_human_wiki -->