让 AI 代理的上下文一直保持新鲜（CocoIndex）

多数 RAG 或代理上下文的做法是一次性批处理：先把文档切块、算 embedding、灌进向量库，源数据改了，整条管道重跑。代码仓库、Slack、收件箱、会议纪要这类每天都在动的源，批处理的间隔就是代理看到过期信息的时间。

CocoIndex 是增量数据索引引擎，Rust 写核心、Python 写声明式流程，把文件与数据库等源数据同步成持续新鲜的向量表，供 AI 代理检索。

用法是声明目标里应该有什么，引擎负责长期保持一致。你写一段 Python 描述目标表的结构与内容，CocoIndex 算出当前状态与目标的差异，只重算变化的那部分，README 把它称作 Δ。第一次运行是回填，之后每次运行只处理改动过的文件。

第一次用它需要知道的事

• 入口是 Python，引擎是 Rust。流程写在 Python 里，核心放在 rust/ 目录，仓库根目录同时有 pyproject.toml 与 Cargo.toml，语言占比 Rust 51.5%、Python 48.2%。从源码构建要处理两套工具链，仓库没有说明 pip 安装是否会触发本地 Rust 编译。
• 目标存储要自己准备。示例把 Postgres 当目标表挂载，内置 target 还包括 LanceDB 与 ChromaDB。数据库实例、账号、权限都不在仓库范围内。
• 要接模型服务。示例里的 embed(chunk.text) 与 LLM 生成客户端都指向外部模型服务。仓库没有说明是否绑定特定厂商，也没有说明离线环境要怎么替换。
• Python 版本约束。根目录有 .python-version 文件，README 没写最低 Python 版本，具体约束以 pyproject.toml 为准。
• 项目状态。截至 2026-10-03 抓取时，cocoindex-io/cocoindex 有 11639 个 Star、910 个 Fork、103 个开放 Issue，采用 Apache-2.0 许可证，主要语言为 Rust。最新版本 v1.0.24 发布于 2026-09-20，最近一次提交在 2026-10-02。

最短上手路径

1. 装包：pip install -U cocoindex。
2. 准备目标存储，建好 Postgres 实例，示例用 postgres.mount_table_target(PG, table_name="docs") 把库表挂成目标。
3. 写处理函数，用 @coco.fn(memo=True) 装饰，逐个文件读文本、切块，再调用 table.declare_row(text=..., embedding=...) 声明行。
4. 声明向量索引：table.declare_vector_index(column="embedding")。
5. 写主函数并跑起来：coco.App(coco.AppConfig(name="docs"), main, src="./docs").update_blocking()，第一次运行是全量回填。
6. 再跑同一条命令看增量效果，只有改动过的文件会重新 embedding。
7. 想确认引擎到底跟踪了什么，用 cocoindex show 查看组件与目标状态的元数据。

它实际上能做哪些事

增量同步与状态跟踪

• 按输入与代码哈希做记忆化。@coco.fn(memo=True) 的缓存键包含输入与函数代码本身，两边都没变就跳过重算。局限在于记忆化的开关挂在装饰器上，有用户提出希望 memoize 与 batching 能在调用点配置，这条需求目前仍是待解决状态。
• 一次回填，之后长期保持一致。update_blocking() 首次运行建立全量索引，后续重复运行只处理变化的部分。文档里另有 live update 模式持续跟踪源变更，也有 Issue 提出让 CLI 显示每个源配置了哪种变更捕获机制。
• 查看跟踪状态。cocoindex show 能列出组件跟踪的元数据与目标状态。引擎状态存在 LMDB 里，早期版本中长时间的 App.update() 在 Linux 上会因为写事务跨线程而永久持有写锁，v1.0.24 已修复。

数据源与目标存储

• 本地目录与 Postgres 连接器。localfs.walk_dir(src) 遍历目录，postgres 连接器负责挂载目标表，两者是示例里最常出现的组合。
• 内置向量目标。LanceDB 与 ChromaDB 都是内置 target，ChromaDB 是后来作为可选依赖加入的，有对应 Issue 记录这次扩展。
• 自定义 sink。容器 sink 通过 per-action child slots 提供子目标，接口是 TargetActionSink.from_fn_with_children 与 from_async_fn_with_children；v1.0.23 起返回 ChildTargetDef 列表的做法被弃用，Rust SDK 里对应的闭包写法也有变化，升级时要留意。

面向 LLM 的数据加工

• 切分文本与代码。RecursiveSplitter 做递归切块；code_ast 用 tree-sitter 按语法切代码，v1.0.21 接入了 Lua 语法，其他语言的语法支持情况仓库没有逐一说明。
• LLM 生成与超时控制。提供 LlmGenerationClient 做生成调用，另有统一的 timeout / deadline 机制，用上下文管理器设置超时并向下游传播，避免单个函数长时间卡住。

参数速查

• @coco.fn(memo=True)：开启记忆化，决定这个函数是否按哈希跳过重算。
• coco.AppConfig(name="docs")：应用名，用于标识这套流程。
• coco.App(config, main, src="./docs")：把配置、主函数与源路径绑在一起。
• .update_blocking()：同步执行更新，首次全量、之后增量。
• declare_row(...) / declare_vector_index(column="embedding")：声明目标表的行与向量索引列。
• postgres.mount_table_target(PG, table_name="docs")：挂载 Postgres 目标表。
• 命令行：cocoindex setup 做初始化，cocoindex show 查看跟踪状态。

输出与结果位置

结果主要落在你指定的目标存储里：Postgres 表、LanceDB 或 ChromaDB 向量库，写入内容由 declare_row 决定。

引擎自身维护的状态与跟踪元数据存在 LMDB 中，用 cocoindex show 查看。终端会输出更新统计，Issue 里提过的进度条需求已经实现。仓库没有说明会生成报告文件或报告目录，需要审计记录得自己从目标存储或 CLI 输出里取。

实际使用中的坑

• 调用点配置记忆化与批处理还没做。有用户提出希望 memoize / batching 能在调用点配置，而不是只在装饰器上定死，这条目前待解决。
• 版本升级会撞上 SDK 改名。有人用 cocoindex==0.3.8 跑示例时报 AttributeError: module 'cocoindex._engine' has no attribute 'set_settings_fn'，属于引擎侧接口变动。这条已解决，但说明 1.0 之前的接口调整比较频繁，锁版本更稳妥。
• 单个函数可能长时间卡住。有用户反馈改用 Ollama 时单个函数会卡很久，官方为此加了统一超时机制，这条已解决。
• 长时间更新曾经在 Linux 上挂死。LMDB 写事务可能在不同运行时线程上恢复，写锁一直被持有，后续所有写入被阻塞。v1.0.24 修复，长 App.update() 不再永久挂起。

替代方案一览

CocoIndex 只管「数据变了索引跟着变」这一段。如果你真正的痛点是上下文太长、token 太贵，它帮不上忙，Headroom 那类本地压缩更对口；如果你要的是一次性把企业数据整理成一份可溯源的知识图谱供人查阅，持续同步机制反而是多余开销。只有当源数据本身每天在动、下游又必须拿到最新版本时，这套增量引擎才划算。

别踩的合规线

CocoIndex 的目标是把文件、邮箱、Slack、PDF、视频等内容持续索引进你的存储，这类用途只对自有资产或已获书面授权的数据源使用。

Slack、收件箱、会议纪要通常包含个人信息与第三方内容，抓取、切块、向量化之前要确认你有权处理，并遵守适用的个人信息保护法规与各平台的服务条款。embedding 与生成调用会把内容送到第三方模型服务，涉密或受监管数据要先确认这条数据出境路径是否被允许。绕过平台速率限制或访问控制去拉数据，可能触发账号封禁与法律责任。

什么时候值得用它

• 源数据持续在变，下游的代理或检索服务又必须拿到最新版本，增量重算能省下大量重复 embedding 的开销。
• 你已经在用 Postgres、LanceDB 或 ChromaDB 做向量检索，只想再补一层「自动跟着源变」的同步。
• 团队接受用 Python 声明式地描述目标状态，不介意为此自备数据库与模型服务。

反过来，一次性离线整理、之后不再更新的数据集，用它只会多出一层状态维护成本；把上下文长度当成主要瓶颈的场景，也不该指望它。仓库目前 103 个开放 Issue，1.0.x 期间接口仍在调整，生产使用前建议锁版本并留出升级验证的时间。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.9 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。