项目定位与目标

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

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

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

双 SDK 与统一语义

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

• Python SDK 使用装饰器（@coco.fn、@cocoindex）把函数挂到流图上，源/目标通过 localfs、postgres、kafka 等模块导入。例如 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 —— 提议打造一套与 Python SDK 等价的、惯用的 Rust SDK，沿用 proc-macro + 显式 &Ctx 思路，提供记忆化、作用域组件、带指纹的目录遍历等能力。

两套 SDK 共享同一套核心算子，例如 IdGenerator、entity_resolution 等都能在两侧复用（见 examples/rust/conversation_to_knowledge/README.md 与 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）。
• Live（长连接）：追平后继续监听变化，使用 cocoindex update -L main，在源上声明 live=True（见 examples/text_embedding_lancedb/README.md）。

1. Function / Component（计算节点）：所有自定义转换默认是纯函数，其输出按输入内容缓存。Rust 端用 #[cocoindex::function(memo)]，Python 端用 @coco.fn(memo=True)（examples/rust/files_transform/README.md）。
2. Target（目标）：声明式目标（如 DirTarget、postgres::mount_table_target）负责把新结果写入、跳过未变更文件、删除已不存在的源对应产物。例如 examples/rust/pdf_to_markdown/README.md 中提到"删除源 PDF 时，对应输出 .md 会在下一次运行中自动移除"。

架构示意

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 在三张 Postgres 表上分别挂载 mount_table_target，而 examples/rust/kafka_consume/README.md 在 catch-up 阶段会把日志压缩到每个 key 的最新值（tombstone 即删除）。

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

• LanceDB 提交优化（issue #1429）：当小批量追加频繁时，Lance 表的 fragment 会膨胀，需要在每若干千行后做 compaction 与索引优化。代码嵌入示例 examples/code_embedding_lancedb/README.md 同样依赖 ./lancedb_data/ 目录的稳定写入语义。
• Shadow Run / 预览（issue #1890）：希望在分块策略或抽取 prompt 修改后，先以"影子模式"跑一遍，预览差异再决定是否落盘，以降低破坏管线的风险。
• MCP 支持（issue #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），是后续代码知识图谱（examples/multi_codebase_summarization/README.md）的基础设施之一。

See Also

• 文本嵌入与 RAG 示例：text_embedding、text_embedding_lancedb、text_embedding_qdrant、text_embedding_turbopuffer
• 知识图谱与多代码库：docs_to_knowledge_graph、meeting_notes_graph_neo4j、meeting_notes_graph_falkordb、multi_codebase_summarization
• Rust SDK 示例：rust/files_transform、rust/pdf_to_markdown、rust/hn_trending_topics、rust/conversation_to_knowledge、rust/kafka_consume、rust/paper_metadata
• 相关 issue：#160 (MCP)、#1429 (LanceDB commit)、#1667 (Ergonomic Rust SDK)、#1890 (Shadow run / preview)

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。

其工作流可概括为：

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)
• 示例：Files Transform
• 示例：Multi-Codebase Summarization
• 示例：Docs to Knowledge Graph (Neo4j)
• 示例：Meeting Notes Graph (Neo4j)

概述

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

资料来源：examples/text_embedding/README.md

核心连接器生态

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

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

资料来源：examples/rust/files_transform/README.md、examples/rust/text_embedding/README.md

关键 Ops 与转换

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

• 文本切分（Chunking）：Python 侧使用 RecursiveSplitter，Rust 侧对应 cocoindex_ops_text::RecursiveChunker，二者均支持按语言定制规则（如 "abstract" 自定义语言）以适配学术论文摘要等场景。资料来源：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、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、rust/code_match/src/lang/mod.rs
• PDF → Markdown：Python 侧使用 docling 的 ML 文档理解流水线；Rust 侧由于缺少等价方案，使用 lopdf 进行纯文本提取，并在 README 中明确标注质量差异。资料来源：examples/pdf_to_markdown/README.md、examples/rust/pdf_to_markdown/README.md
• 多代码库摘要：使用 instructor + LiteLLM 让 LLM 直接产出 Mermaid 语法，其中粗体标注 @coco.fn 函数，粗箭头（==>）表达 mount/use_mount 调用关系。资料来源：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、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

目标写入

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

资料来源：examples/text_embedding/README.md、examples/rust/files_transform/README.md

社区关注与演进方向

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

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

最新发布的 v1.0.13 主要围绕 code_match 的匹配器与预过滤性能进行了一系列增强（裸关键字、锚定正则匹配、片段区间、子运行扫描剪枝等），表明 Ops 层与代码理解的集成仍是当前投入重点。资料来源：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/

增量更新机制与运行模式

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

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

在 Python 文本嵌入示例中，运行方式由源声明决定（live=True 时实时监听），CLI 仅切换模式 examples/text_embedding/README.md：

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。

多语言 SDK 架构

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

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：

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

多目标后端与场景选型

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

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

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

典型运维特征：

• 源数据未变更时，记忆化（memo）自动跳过函数级计算 examples/rust/files_transform/README.md
• 托管式目标（如 DirTarget、TableTarget）会清理孤立行——源被删除后输出自动消失 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。

See Also

• 项目概览
• Python SDK 基础
• Rust SDK 入门
• 目标后端适配器
• 增量与状态模型

Pitfall Log / 踩坑日志

项目：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