Doramagic.ai
English

Doramagic 项目包 · 项目说明书

airweave 项目

面向 AI 智能体的开源上下文检索层

项目概述与系统架构

Airweave 是一个面向 AI 代理的数据接入与上下文同步平台，旨在把来自任意第三方 SaaS、数据源或企业内部系统的结构化/非结构化数据，统一抽取、转换、嵌入并写入可被检索的后端（如 Vespa），从而为 Agent、MCP 工具调用以及 RAG 场景提供实时、可追溯的上下文。其核心能力可概括为：

章节 相关页面

继续阅读本节完整说明和来源证据。

一、项目定位与核心能力

Airweave 是一个面向 AI 代理的数据接入与上下文同步平台，旨在把来自任意第三方 SaaS、数据源或企业内部系统的结构化/非结构化数据，统一抽取、转换、嵌入并写入可被检索的后端（如 Vespa），从而为 Agent、MCP 工具调用以及 RAG 场景提供实时、可追溯的上下文。其核心能力可概括为：

  • 多源连接器（Source Connectors）：覆盖云盘（如 OneDrive、SharePoint、Google Drive）、协作工具（如 Teams、Asana、Notion）、数据库（如 MongoDB、Appwrite、Odoo）、以及领域平台（如 Mistral、Firecrawl、Obsidian）等，社区对自定义连接器的呼声持续存在（见 #1268）。
  • 实体抽象与同步管道：连接器产出 Entity 对象，进入统一的同步工作流，完成分块、嵌入、索引、写入。
  • 可插拔后端与高可用：Vespa、Redis（已支持 Sentinel 拓扑，见 v0.9.72）等基础设施均可替换或水平扩展。
  • MCP 与多租户：通过 Model Context Protocol 暴露能力，配合 Collection、Source Connection 等模型实现多租户隔离。

资料来源：README.md:1-80

二、运行时架构

应用入口位于 backend/airweave/main.py，基于 FastAPI 启动 HTTP 服务并挂载异常处理器、CORS 与健康检查端点；随后由核心容器（Container）负责装配所有依赖（数据库会话、向量库、嵌入服务、连接器注册表等），并通过 wire 机制注入到 API 层与同步工作流中。

flowchart LR
    A[Source / SaaS API] --> B[Source Connector]
    B --> C[Entity Stream]
    C --> D[Transformer / Chunker]
    D --> E[Embedding Service]
    E --> F[Destination: Vespa / Vector DB]
    C --> G[(Postgres)]
    F --> G
    H[API / MCP] --> I[Container DI]
    I --> B

系统遵循"读取-转换-嵌入-写入"四阶段管道（ETL-Embed），连接器只负责产出实体，目的地抽象使得后端切换不影响上层逻辑。该结构在 architecture-refactor.md 中被进一步规范化，强调把"上下文准备"与"代理执行"解耦。

资料来源：backend/airweave/main.py:1-120、backend/airweave/core/container/container.py:1-200、backend/airweave/architecture-refactor.md:1-160

三、关键数据模型

模型职责关键字段
Collection租户级数据集合，决定同步目标与可见性name、readable_id、sync_id、vector_size
SourceConnection用户对某个数据源的授权绑定connection_id、short_name、status、credential_id
Sync / SyncJob同步编排与执行追踪sync_id、status、entities_count、error

Collection 与 SourceConnection 通过外键关联，构成"集合-来源"的多对多关系：同一数据源可被多个集合复用，同一集合可汇聚多个来源。status 字段在 OneDrive 等场景中扮演关键角色——当 OAuth 账户被锁定时，连接器仍可能继续预取，社区已就此提出 #1807，强调需要在凭据失效时主动将状态切换为 NEEDS_SOURCE 以避免数据泄露。

资料来源：backend/airweave/models/collection.py:1-180、backend/airweave/models/source_connection.py:1-200

四、安全、扩展与近期演进

OAuth 与凭据生命周期：社区在 #1024 中指出，OAuth 响应通常只返回 expires_in 而非 expires_at，Airweave 在内部统一换算以避免 SDK 误用。凭据错误（如客户凭据过期）不再被计入工作流失败，避免误告警（见 v0.9.69）。

Microsoft 生态强化：SharePoint/OneDrive 在 v0.9.70 起会按 Purview 敏感度标签跳过文件/站点；v0.9.67 修复了组织级共享链接绕过访问控制的问题（#1774、#1775）。同时，Teams 消息中的非法控制字符（如 0x1B）曾导致 Vespa 摄入失败，平台需要在写入前对实体文本进行清洗（见 #1269）。

可扩展性：Mistral SDK 的基础 URL 已可在 v0.9.73 进行配置化，便于私有化部署；Redis 通过 Sentinel 支持高可用拓扑（v0.9.72）；Collection 浏览新增表格视图并由特性开关控制（v0.9.68）。

社区驱动的连接器生态：MongoDB（#943）、Appwrite（#1276）、Odoo（#1278）、Lovable AI（#1288）、Meta Threads（#1801）等持续被请求。开发者可通过注册自定义连接器实现接入，平台在 Container 中保留连接器注册点以支持热加载。

资料来源：backend/airweave/core/container/container.py:200-360、backend/airweave/architecture-refactor.md:160-320

资料来源：README.md:1-80

同步管道与数据流

同步管道（Sync Pipeline）是 Airweave 的核心数据通路，负责把外部数据源（如 OneDrive、SharePoint、Microsoft Teams、Mistral 等连接器）抽取出来的实体（Entity）经过清洗、分块、向量化后写入目标向量数据库（Vespa）。runsourceconnection.py 是 Temporal 工作流入口，负责按计划或...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述与作用域

同步管道（Sync Pipeline）是 Airweave 的核心数据通路，负责把外部数据源（如 OneDrive、SharePoint、Microsoft Teams、Mistral 等连接器）抽取出来的实体（Entity）经过清洗、分块、向量化后写入目标向量数据库（Vespa）。run_source_connection.py 是 Temporal 工作流入口，负责按计划或手动触发一次同步；orchestrator.py 在工作流内部协调各阶段执行；factory.py 根据 source 与 destination 配置构造具体的管道实例。

核心组件

builders/sync.py 负责把 source connection、collection、destination、credential 组合成一个可执行的 SyncContext，这是管道运行时的输入契约。pipeline/entity_tracker.py 跟踪每个实体在管道中的处理状态（待处理 / 已向量化 / 已写入 / 失败），用来支持断点续传与去重。processors/chunk_embed.py 负责把原始文本切分成 chunk，再调用嵌入模型（OpenAI、Mistral 等）生成向量。

组件文件职责
Builderbuilders/sync.py装配同步上下文、校验配置
Orchestratororchestrator.py阶段调度、错误传播、状态汇报
Factoryfactory.py按配置生成处理器链
EntityTrackerpipeline/entity_tracker.py实体去重、增量游标
ChunkEmbedprocessors/chunk_embed.py分块 + 向量化

资料来源：backend/airweave/domains/sync_pipeline/builders/sync.py:1-100、backend/airweave/domains/sync_pipeline/pipeline/entity_tracker.py:1-120、backend/airweave/domains/sync_pipeline/processors/chunk_embed.py:1-140

数据流阶段

flowchart LR
  A[Source Connector] --> B[Entity Generator]
  B --> C[EntityTracker 去重]
  C --> D[ChunkEmbed 分块+向量化]
  D --> E[Destination Vespa]
  E --> F[Temporal Workflow 状态回报]
  1. 抽取：连接器（如 OneDrive、Teams）拉取原始实体。
  2. 去重与追踪：EntityTracker 通过 entity_id + cursor 比对，跳过已同步内容。
  3. 分块与嵌入：长文档按 token 切片，调用 LLM 嵌入模型生成 dense vector。
  4. 写入目的地：由 Destination 抽象（VespaDest 等）写入对应向量库。
  5. 状态回报：orchestrator 把进度写回 Temporal activity，供前端展示。

资料来源：backend/airweave/domains/sync_pipeline/orchestrator.py:40-160、backend/airweave/domains/sync_pipeline/pipeline/entity_tracker.py:30-110、backend/airweave/domains/sync_pipeline/processors/chunk_embed.py:20-180

错误处理与社区反馈

管道对失败的处理是分层的：抽取阶段失败（如 OAuth 凭证失效）从 v0.9.69 起不再被算作 workflow 整体失败，而是作为客户凭证错误单独标记。 资料来源：backend/airweave/domains/temporal/workflows/run_source_connection.py:80-200

社区中已记录的几类典型数据流问题：

  • Vespa 摄入非法字符：Microsoft Teams 消息含 0x1B 等不可打印控制字符，导致 Vespa 摄入失败，需要在 chunk/embed 阶段或 destination 写入前做清洗。 （Issue #1269）
  • 账户锁定后仍预取：OneDrive 连接器在 Microsoft 账户失联后未及时停止预取，建议 EntityTracker 与 source connection 状态机（NEEDS_SOURCE）联动提前中断。 （Issue #1807）
  • Purview 敏感标签过滤：v0.9.70 起，SharePoint/OneDrive 在抽取阶段按 Purview 敏感标签跳过文件，从而减少后续管道压力。 （Release v0.9.70）
  • Replay 测试支持：v0.9.71 让 ArfReplaySource.generate_entities 接受 sync pipeline kwargs，便于回放测试整条数据流。 （PR #1791）

扩展点

新增连接器时通常只需实现 Source.generate_entities()，并由 SyncPipelineFactory 把生成器接入既有管道；新增目的地只需实现 Destination.upsert()。entity_tracker 的 cursor 机制保证了重复运行同步的幂等性。

资料来源：backend/airweave/domains/sync_pipeline/builders/sync.py:1-100、backend/airweave/domains/sync_pipeline/pipeline/entity_tracker.py:1-120、backend/airweave/domains/sync_pipeline/processors/chunk_embed.py:1-140

连接器生态与定制开发

Airweave 的连接器生态是一套围绕"源（Source）→ 实体（Entity）→ 目标（Destination）"管道构建的可扩展集成体系。每个连接器都负责将外部系统（如 Microsoft Teams、OneDrive、SharePoint、Notion 等）中的数据拉取、转换为统一的实体模型，再交由后端的同步工作流完成嵌入、索引与目标写入。这种设计使得第三方贡献者...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 Source 基类

继续阅读本节完整说明和来源证据。

章节 Entity 基类

继续阅读本节完整说明和来源证据。

章节 Source Registry

继续阅读本节完整说明和来源证据。

概述

Airweave 的连接器生态是一套围绕"源（Source）→ 实体（Entity）→ 目标（Destination）"管道构建的可扩展集成体系。每个连接器都负责将外部系统（如 Microsoft Teams、OneDrive、SharePoint、Notion 等）中的数据拉取、转换为统一的实体模型，再交由后端的同步工作流完成嵌入、索引与目标写入。这种设计使得第三方贡献者可以在不改动核心管道的前提下，新增特定数据源的接入能力。社区中大量"Connector Request"工单（如 Obsidian、Firecrawl、Appwrite、Odoo、Meta Threads、MongoDB 等）正是围绕该定制开发流程展开的。

资料来源：backend/airweave/platform/sources/_base.py:1-40

核心架构与抽象基类

Source 基类

Source 是所有连接器的根基，定义在 backend/airweave/platform/sources/_base.py 中。其核心责任包括：

  • 生成实体流：通过 generate_entities() 异步方法从上游系统产出标准化的实体对象。
  • 生命周期管理：内置 create()、close() 等上下文方法，配合 AirweaveClient 负责对源对象的初始化与资源释放。
  • 配置校验：在 validate_config() 中校验连接器所需的必填字段（如 client_id、tenant_id、drive_id 等），避免错误配置进入同步管道。

资料来源：backend/airweave/platform/sources/_base.py:40-120

Entity 基类

实体是同步管道中流通的标准数据单元，定义于 backend/airweave/platform/entities/_base.py。每个实体必须实现：

  • entity_id()：返回上游系统中该对象的唯一标识，用于目标端的去重与幂等更新。
  • to_storage_dict() 与 to_search_dict()：分别生成用于持久化存储和用于向量检索的两份序列化结果。
  • 字段级元数据：包括 web_url、metadata、breadcrumbs 等，便于在检索阶段补充来源链接与导航路径。

社区曾报告 TeamsMessageEntity 中包含 0x1B 等控制字符导致 Vespa 摄取失败（见 issue #1269），其根源正是实体层在序列化前未对不可打印字符做归一化处理，这也是实体基类在定制开发时需要重点关注的健壮性点。

资料来源：backend/airweave/platform/entities/_base.py:20-90

注册机制与发现

Source Registry

backend/airweave/domains/sources/registry.py 中的 SourceRegistry 是连接器运行时发现的中心。它以"短名称 → Source 类"的映射方式注册全部内置源，并在启动时扫描 platform/sources/ 下的子类实现，使任意继承自 Source 的新类都能自动暴露给 API 层与 SDK 层。这种约定优于配置（convention over configuration）的模式降低了添加新源的门槛。

资料来源：backend/airweave/domains/sources/registry.py:15-80

Auth Provider Registry

与 Source Registry 平行的 AuthProviderRegistry（位于 backend/airweave/domains/auth_provider/registry.py）用于登记每个源所支持的认证方式（OAuth2、API Key、PAT 等）。定制开发者在新增连接器时，必须同时声明其依赖的认证提供者，否则同步流水线会因为缺少凭据解析器而中止。

资料来源：backend/airweave/domains/auth_provider/registry.py:10-60

下面用一张表格总结两类注册中心的关键差异：

维度SourceRegistryAuthProviderRegistry
注册对象Source 类（数据拉取逻辑）AuthProvider（凭据获取逻辑）
触发时机进程启动时扫描 platform/sources/启动时按需懒加载
关键接口register(name, cls)、get(name)register(provider), get_for_source(name)
定制开发要求继承 Source 并实现 generate_entities复用内置 OAuth2 / API Key Provider

认证与令牌管理

OAuth2 是大多数 SaaS 连接器（Microsoft、Notion、Slack 等）所使用的统一认证路径。backend/airweave/domains/oauth/oauth2_service.py 中的 OAuth2Service 负责：

  1. 构造授权 URL（authorization_code 模式，含 PKCE 与 state）。
  2. 接收回调后用 code 换取 access_token、refresh_token。
  3. 处理 expires_in（秒数）与 expires_at（绝对时间戳）的换算问题——社区 issue #1024 正是反馈 SDK 在该字段上的不一致。

资料来源：backend/airweave/domains/oauth/oauth2_service.py:30-140

backend/airweave/domains/sources/token_providers/oauth.py 则把 OAuth2Service 封装为每个连接器实例可调用的 OAuthTokenProvider，它会：

  • 在每次同步开始前检查 token 是否即将过期；
  • 自动调用刷新接口并把新令牌回写到数据库；
  • 在 OneDrive 等场景下，账户被锁定时仍尝试拉取数据的问题（issue #1807）反映出该层需要更严格的失败短路策略。

资料来源：backend/airweave/domains/sources/token_providers/oauth.py:25-95

定制开发流程与社区生态

综合上述抽象与注册机制，定制一个新的连接器通常包含以下步骤：

flowchart LR
    A[继承 Source 基类] --> B[实现 generate_entities]
    B --> C[定义 Entity 子类]
    C --> D[在 SourceRegistry 注册]
    D --> E[绑定 AuthProvider]
    E --> F[接入 OAuth2Service]
    F --> G[端到端同步测试]

社区的连接器请求工单（如 Obsidian、Firecrawl、MongoDB、Meta Threads 等）正是遵循这一模式提出的。值得注意的是，issue #1268 明确表达了用户希望以"自定义连接器"形式注入自有源，而不是等待官方实现；这暗示着 Airweave 未来有可能引入"运行时 Source 插件"机制，允许将自定义 Source 子类以 Python 包的形式上传到实例中，并由 SourceRegistry 在运行时加载，从而真正兑现"开放生态"的承诺。

此外，#41 中关于 OpenAI、Groq、Ollama 等模型提供方 API Key 可配置化的诉求，也间接体现出在更大范围内的"凭据可插拔"设计哲学，与 AuthProviderRegistry 的演进方向一致。

资料来源：backend/airweave/platform/sources/_base.py:40-120、backend/airweave/domains/sources/registry.py:15-80、backend/airweave/domains/auth_provider/registry.py:10-60、backend/airweave/domains/oauth/oauth2_service.py:30-140、backend/airweave/domains/sources/token_providers/oauth.py:25-95、backend/airweave/platform/entities/_base.py:20-90

资料来源：backend/airweave/platform/sources/_base.py:1-40

搜索、AI 集成与部署运维

Airweave 的"搜索、AI 集成与部署运维"由三大支柱组成：底层的搜索领域服务（搜索执行器 + 经典/代理/浏览三类搜索模式）、AI 集成层（通过可配置的 LLM 客户端驱动代理式搜索与同步增强），以及面向生产环境的部署运维栈（Vespa 目的地、Redis 哨兵、容器编排与监控）。该模块把外部数据源拉取到的实体文档写入可索引后端，再由搜索入口暴露给上层 API 与 ...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述与系统定位

Airweave 的"搜索、AI 集成与部署运维"由三大支柱组成：底层的搜索领域服务（搜索执行器 + 经典/代理/浏览三类搜索模式）、AI 集成层（通过可配置的 LLM 客户端驱动代理式搜索与同步增强），以及面向生产环境的部署运维栈（Vespa 目的地、Redis 哨兵、容器编排与监控）。该模块把外部数据源拉取到的实体文档写入可索引后端，再由搜索入口暴露给上层 API 与 MCP 客户端，并允许用户通过模型上下文协议调用 AI 代理完成复杂的多步检索任务。资料来源：backend/airweave/domains/search/executor.py:1-40。

搜索子系统架构

搜索子系统的入口是 domains/search/executor.py 中的执行器，它作为统一的调度层，把入站查询路由到三个具体的搜索服务实现。这种"路由 + 策略实现"的分层让系统既能保留传统的向量/关键词检索能力，又能承载代理式多步推理与集合浏览视图。

模式服务文件典型用途适用场景
经典搜索classic/service.py单轮向量 + 元数据过滤简单查询、低延迟
代理搜索agentic/service.py多轮 LLM 驱动的工具调用复杂问答、跨源检索
浏览视图browse/service.py表格化集合浏览结果浏览与人工审阅

资料来源：backend/airweave/domains/search/classic/service.py:1-30、backend/airweave/domains/search/agentic/service.py:1-35、backend/airweave/domains/search/browse/service.py:1-30。

执行器负责组装请求上下文（租户、集合、可访问的连接器源）并对响应进行归一化，三种服务实现则专注于各自的检索语义。代理服务通常会调用经典服务作为底层的"取回工具"，并叠加改写、规划与结果合成步骤。

AI 集成与代理能力

AI 集成层围绕"可插拔的 LLM 客户端"展开，使代理搜索与同步过程中对模型推理的调用能够灵活切换提供商。社区长期关注的 #41 号议题（"Add Configurable API Key Support for OpenAI, Groq, Ollama, and More"）正是推动该层开放配置能力的来源，目的是允许用户自带 API Key 而非完全依赖平台预置凭证。资料来源：backend/airweave/platform/llms/azure_openai.py:1-25。

代理式搜索的核心动作包括：

  1. 根据用户查询生成检索计划，决定调用哪些连接器源、是否需要多步迭代；
  2. 调用底层经典搜索获取候选实体；
  3. 通过 LLM 对候选结果进行重排、汇总与引用归因；
  4. 返回结构化响应，支持 MCP 客户端做后续处理。

由于代理路径会反复触发外部 LLM 调用，运维上需要关注速率限制、token 成本与失败重试策略。Airweave 在同步流程里区分"工作流失败"与"客户凭证失败"，后者不再计入失败指标（v0.9.69 的修复），代理搜索侧的凭证错误也理应被同样宽容对待。资料来源：backend/airweave/domains/search/agentic/service.py:60-120。

部署与基础设施

生产部署由若干可独立扩展的组件构成：

  • Vespa 目的地：实体同步写入 Vespa，vespa_client.py 封装了 HTTP/feed/delete 等操作，并依赖 base_entity.sd 中定义的 schema 字段（如 airweave_system_id_*）。Schema 字段必须与 Python 实体的属性一致，否则会出现 #1269 中描述的"非法码点 0x1B 导致 Vespa 入库失败"之类的字符兼容问题。资料来源：backend/airweave/platform/destinations/vespa/vespa_client.py:1-60、vespa/app/schemas/base_entity.sd:1-40。
  • Redis：作为队列与缓存，自 v0.9.72 起支持 Sentinel 高可用拓扑，便于在多副本环境下维持同步任务不中断。资料来源：docker-compose.yml:1-80。
  • OAuth 与凭证：通过 platform/auth/oauth.py 集中管理外部源的访问令牌。社区 #1024 号议题指出 OAuth 响应中常见 expires_in 而非 expires_at，提示在凭证刷新逻辑中需要做时差换算。资料来源：backend/airweave/platform/auth/oauth.py:40-90。
  • 容器化编排：docker-compose.yml 将 API、后端 worker、Postgres、Redis、Vespa 等组件统一拉起，便于本地与准生产环境复现。

运维注意事项与社区反馈

  • 字符清洗：Microsoft Teams 等来源可能带来 0x1B 等控制字符，需在写入 Vespa 前清洗，避免入库失败（#1269）。
  • OAuth 时序：使用 expires_in 计算 expires_at 时务必基于一致的时区与基准时间（#1024）。
  • 配置灵活度：长期需求是为 OpenAI、Groq、Ollama 等模型开放自带 Key 路径（#41），这意味着运维层需要支持多租户凭据隔离与回退策略。
  • 安全敏感性：OneDrive 连接器在账户锁定后仍可能继续预取（#1807），建议在搜索与同步执行器侧加入"源健康状态"短路判断，必要时复用 v0.9.71 的 ArfReplaySource.generate_entities 修复思路对失败源进行优雅降级。
  • 高可用：v0.9.72 引入的 Redis Sentinel 应在部署清单中启用，避免单点故障导致同步任务堆积。

通过把搜索服务、AI 代理、目的地与运维工具链按上述层次组织，Airweave 能够在保持检索语义清晰的同时，把外部数据源、LLM 与底层索引引擎解耦，从而支持从本地开发到云端高可用部署的完整生命周期。

资料来源：backend/airweave/domains/search/classic/service.py:1-30、backend/airweave/domains/search/agentic/service.py:1-35、backend/airweave/domains/search/browse/service.py:1-30。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：[Connector Request] Meta Threads Integration for Drafting, Scheduling, and Publishing

可能影响授权、密钥配置或安全边界。

medium 可能修改宿主 AI 配置

安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。

medium 失败模式：configuration: OneDrive connector appears to continue prefetching after Microsoft account lockout / source s...

Developers may misconfigure credentials, environment, or host setup: OneDrive connector appears to continue prefetching after Microsoft account lockout / source state NEEDS_SOURCE

medium 失败模式：configuration: [Bug] Sync Failure: Illegal code point 0x1B in TeamsMessageEntity causes Vespa ingestion to fail

Developers may misconfigure credentials, environment, or host setup: [Bug] Sync Failure: Illegal code point 0x1B in TeamsMessageEntity causes Vespa ingestion to fail

Pitfall Log / 踩坑日志

项目：airweave-ai/airweave

摘要：发现 26 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[Connector Request] Meta Threads Integration for Drafting, Scheduling, and Publishing。

1. 安全/权限坑 · 来源证据：[Connector Request] Meta Threads Integration for Drafting, Scheduling, and Publishing

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Connector Request] Meta Threads Integration for Drafting, Scheduling, and Publishing
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 证据：community_evidence:github | https://github.com/airweave-ai/airweave/issues/1801 | 来源类型 github_issue 暴露的待验证使用条件。

2. 配置坑 · 可能修改宿主 AI 配置

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
  • 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
  • 证据：capability.host_targets | https://github.com/airweave-ai/airweave | host_targets=cursor, chatgpt

3. 配置坑 · 失败模式：configuration: OneDrive connector appears to continue prefetching after Microsoft account lockout / source s...

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: OneDrive connector appears to continue prefetching after Microsoft account lockout / source state NEEDS_SOURCE
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: OneDrive connector appears to continue prefetching after Microsoft account lockout / source state NEEDS_SOURCE
  • 证据：failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1807 | OneDrive connector appears to continue prefetching after Microsoft account lockout / source state NEEDS_SOURCE

4. 配置坑 · 失败模式：configuration: [Bug] Sync Failure: Illegal code point 0x1B in TeamsMessageEntity causes Vespa ingestion to fail

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: [Bug] Sync Failure: Illegal code point 0x1B in TeamsMessageEntity causes Vespa ingestion to fail
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Bug] Sync Failure: Illegal code point 0x1B in TeamsMessageEntity causes Vespa ingestion to fail
  • 证据：failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1269 | [Bug] Sync Failure: Illegal code point 0x1B in TeamsMessageEntity causes Vespa ingestion to fail

5. 配置坑 · 失败模式：configuration: [Connector Request] Meta Threads Integration for Drafting, Scheduling, and Publishing

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: [Connector Request] Meta Threads Integration for Drafting, Scheduling, and Publishing
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Connector Request] Meta Threads Integration for Drafting, Scheduling, and Publishing
  • 证据：failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1801 | [Connector Request] Meta Threads Integration for Drafting, Scheduling, and Publishing

6. 配置坑 · 失败模式：configuration: [Connector Request] neo4j as a source would also be helpful

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: [Connector Request] neo4j as a source would also be helpful
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Connector Request] neo4j as a source would also be helpful
  • 证据：failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1117 | [Connector Request] neo4j as a source would also be helpful

7. 配置坑 · 失败模式：configuration: [connector support] push

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this configuration risk before relying on the project: [connector support] push
  • 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [connector support] push
  • 证据：failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1148 | [connector support] push, failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1148 | [connector support] push

8. 配置坑 · 失败模式：configuration: v0.9.64

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

9. 配置坑 · 失败模式：configuration: v0.9.66

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

10. 配置坑 · 失败模式：configuration: v0.9.69

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

11. 配置坑 · 失败模式：configuration: v0.9.73

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

12. 能力坑 · 能力判断依赖假设

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

13. 维护坑 · 维护活跃度未知

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

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

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

16. 安全/权限坑 · 来源证据：OneDrive connector appears to continue prefetching after Microsoft account lockout / source state NEEDS_SOURCE

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OneDrive connector appears to continue prefetching after Microsoft account lockout / source state NEEDS_SOURCE
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 证据：community_evidence:github | https://github.com/airweave-ai/airweave/issues/1807 | 来源类型 github_issue 暴露的待验证使用条件。

17. 安全/权限坑 · 来源证据：[Bug] Sync Failure: Illegal code point 0x1B in TeamsMessageEntity causes Vespa ingestion to fail

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] Sync Failure: Illegal code point 0x1B in TeamsMessageEntity causes Vespa ingestion to fail
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 证据：community_evidence:github | https://github.com/airweave-ai/airweave/issues/1269 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

18. 能力坑 · 失败模式：capability: Jira connector: enrich issues with comments and basic metadata

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this capability risk before relying on the project: Jira connector: enrich issues with comments and basic metadata
  • 对用户的影响：Developers may hit a documented source-backed failure mode: Jira connector: enrich issues with comments and basic metadata
  • 证据：failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1164 | Jira connector: enrich issues with comments and basic metadata, failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1164 | Jira connector: enrich issues with comments and basic metadata

19. 能力坑 · 失败模式：capability: [Connector Request] ERPnext from Frappe

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this capability risk before relying on the project: [Connector Request] ERPnext from Frappe
  • 对用户的影响：Developers may hit a documented source-backed failure mode: [Connector Request] ERPnext from Frappe
  • 证据：failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1110 | [Connector Request] ERPnext from Frappe

20. 能力坑 · 失败模式：capability: [Connector Request] Obsidian

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this capability risk before relying on the project: [Connector Request] Obsidian
  • 对用户的影响：Developers may hit a documented source-backed failure mode: [Connector Request] Obsidian
  • 证据：failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1185 | [Connector Request] Obsidian

21. 能力坑 · 失败模式：capability: [Connector Request] Telegram

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this capability risk before relying on the project: [Connector Request] Telegram
  • 对用户的影响：Developers may hit a documented source-backed failure mode: [Connector Request] Telegram
  • 证据：failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1188 | [Connector Request] Telegram

22. 能力坑 · 失败模式：capability: [Connector Request] google sheet

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this capability risk before relying on the project: [Connector Request] google sheet
  • 对用户的影响：Developers may hit a documented source-backed failure mode: [Connector Request] google sheet
  • 证据：failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1151 | [Connector Request] google sheet, failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1151 | [Connector Request] google sheet

23. 能力坑 · 失败模式：capability: [Connector Request] logseq

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this capability risk before relying on the project: [Connector Request] logseq
  • 对用户的影响：Developers may hit a documented source-backed failure mode: [Connector Request] logseq
  • 证据：failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1187 | [Connector Request] logseq

24. 能力坑 · 失败模式：capability: [Connector Request] oracle db

  • 严重度：low
  • 证据强度：source_linked
  • 发现：Developers should check this capability risk before relying on the project: [Connector Request] oracle db
  • 对用户的影响：Developers may hit a documented source-backed failure mode: [Connector Request] oracle db
  • 证据：failure_mode_cluster:github_issue | https://github.com/airweave-ai/airweave/issues/1130 | [Connector Request] oracle db

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

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

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

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

来源：Doramagic 发现、验证与编译记录