一句话总结：CocoIndex 是一个声明式的 Python 增量数据处理引擎。你描述你想从数据源中提取什么，它自动维护与源数据的同步，每次只处理增量（Δ），支持代码库、PDF、视频、Slack、数据库等任意数据源。

一、为什么需要 CocoIndex？

构建 AI Agent 时，一个常见的场景是：Agent 需要访问某个文档库或代码库的最新内容来做决策。传统做法有两种：

• 全量重建：每次更新跑一遍完整的数据管道，简单粗暴但计算成本高，embedding API 费用随时间线性增长
• 定时批处理：每小时或每天跑一次批任务，服务器压力不小，而且数据永远有延迟

这两种方案都无法很好地支持长周期 Agent（Long Horizon Agent）——也就是那些需要持续运行数小时甚至数天的自主 Agent。

CocoIndex 的增量引擎通过 hash 对比 + 内容寻址，能从数据流动的 DAG 中精确定位哪些节点需要重新计算，哪些可以跳过。结果是：更新 1000 个文件中的 3 个，只需要重新处理这 3 个。

二、核心概念

2.1 声明式数据描述

你不需要写繁琐的数据管道代码。CocoIndex 使用一个声明式的 Python API 来描述数据流：

import cocoindex as coco
from cocoindex.connectors import localfs, postgres
from cocoindex.ops.text import RecursiveSplitter
@coco.fn(memo=True)  # 缓存——相同输入 + 相同代码，自动跳过
async def index_file(file, table):
    for chunk in RecursiveSplitter().split(await file.read_text()):
        table.declare_row(
            text=chunk.text,
            embedding=embed(chunk.text)
        )
@coco.fn
async def main(src):
    table = await postgres.mount_table_target(PG, table_name="docs")
    table.declare_vector_index(column="embedding")
    await coco.mount_each(
        index_file,
        localfs.walk_dir(src).items(),
        table
    )
coco.App(
    coco.AppConfig(name="docs"),
    main,
    src="./docs"
).update_blocking()

这个例子做了什么？

• 声明了一个数据源（本地目录 ./docs）和一个目标（PostgreSQL 向量表）
• 定义了如何将文件转换为带 Embedding 的文本块
• 第一次运行时全量建立索引
• 后续运行只处理变化的部分——通过 @coco.fn(memo=True) 自动实现

2.2 增量引擎的设计哲学

CocoIndex 核心团队将其与 React 类比：

• 响应式更新：源数据发生变化时，自动触发下游的增量计算
• 只处理 Δ：通过内容 hash 识别变化，只重新处理受影响的节点
• 并行执行：Rust 核心，增量计算天然可以并行
• 失败隔离：一条数据的处理失败不会阻塞整个管道

三、安装与快速上手

3.1 安装

pip install -U cocoindex

就这么简单。CocoIndex 的 Rust 核心会通过 Python wheel 安装，不需要手动编译。

3.2 使用 AI 编码 Agent 配合

CocoIndex 提供了专门的 CocoIndex Skill，可以 Drop-in 到 Claude Code / Codex 等 AI 编码 Agent 的工作流中。这样 Agent 在写 CocoIndex 代码时，能直接了解其概念、API 和最佳实践。

3.3 20+ 内置示例

CocoIndex 官方仓库提供了 20+ 可直接运行的示例，覆盖常见场景：

• code_embedding：代码库索引与语义搜索
• pdf_embedding：PDF 文档索引
• hn_trending_topics：Hacker News 热点追踪
• conversation_to_knowledge：聊天记录转知识库
• multi_codebase_summarization：多代码库联合摘要
• patient_intake_extraction：结构化数据提取（使用 BAML）
• csv_to_kafka：CSV 数据流式写入 Kafka