AutoRAG Datasource Skills 完全指南CLI 数据源接入、访问控制与检索集成实战【免费下载链接】AutoRAGAutoRAG: Now your agent can find anything in your computer. It gets smarter if you are using it frequently.项目地址: https://gitcode.com/GitHub_Trending/au/AutoRAGAutoRAG 的 Datasource Skills 让 Agent 在保持本地文档检索与精选curation模型不变的前提下检索服务器配置的外部数据源——从 macOS 截图库、本地邮件档案、Slack 桌面缓存到 Google Drive / OneDrive 云盘与 KakaoTalk 聊天记录。本指南基于 datasource-skills.md 及仓库源码完整讲解 Datasource Skill 的契约模型、默认拒绝default-deny访问控制、共享 Embedding 运行时的所有权边界并逐个给出 ClawGallery、Spotlight、mailcrawl、slacrawl、rclone 云盘、katok 六大 CLI 数据源的可复制配置与运行命令。读完你能够独立配置多数据源 Agent、用连接别名管理同一提供商的多个账号、用频道白名单收窄聊天检索范围并依据新数据源检查清单扩展自己的数据源。一、Datasource Skill 是什么契约模型与注册管线AutoRAG 的 Datasource Skill 是一类CLI 支撑CLI-backed的外部数据源接入器它直接运行各数据源的本地原生二进制如clawgallery、mailcrawl、mdfind、rclone、katok并使用操作者提供的配置路径或各 CLI 自身的默认存储位置而不是复制一份数据到 AutoRAG 自己的仓库里。从源码契约看一个 Datasource Skill 同时承担两个职责见 types.ts 的DatasourceSkill接口索引钩子index()负责执行同步/索引并附带polling()元数据描述刷新节奏检索方法工厂retrievalMethods()返回一组接入共享检索管线的RetrievalMethod实例。此外还必须提供describeSources()为 librarian 提示词描述当前数据源里到底有什么数据例如每个实例对应的斜杠分层来源以及skillManifest()返回渐进式披露progressive disclosure的 Agent Skill 清单——name/description注入系统提示词完整content通过load_datasource_skill工具按需加载。这些检索方法通过常规 AutoRAG 管线注册链路为RetrievalMethodRegistry - ParallelRetriever - DatasourceResultFilter - ResultMerger - memory / curation其中DatasourceResultFilter是数据源访问控制的执行点它位于ParallelRetriever之后、结果合并之前对每个数据源方法要么整体丢弃访问被拒绝时返回空数组要么按可信 allow-scopes 与用户 scope 的交集收窄结果见 result-filter.ts。二、访问模型默认拒绝可信配置是唯一授权来源Datasource 访问是**默认拒绝default-deny**的。可信的服务器/API 配置通过两个字段授权datasourceAccess.allowedTags允许的标签列表datasourceAccess.allowedScopes允许的斜杠分层作用域列表。核心约束是模型可控的工具参数永远不能授予访问权。DatasourceAccessContext见 access-context.ts只从服务器提供的 allow-tags / allow-scopes 构造当未配置任何allowedTags时denyAll为true所有数据源描述符一律拒绝。模型对search_datasource_documents工具可见的完整 schema 只有{ query: string; topK?: number; scope?: string }scope只是用户请求的收窄过滤器仅对声明了scoped能力的数据源方法生效。此类方法返回的结果必须同时命中可信 allow-scopes 与请求的 scope 才能存活allowedSourcesPredicate中先校验可信 scope、再叠加用户 scope 取交集见 access-context.ts。不具备scoped能力的数据源例如 katok 的聊天身份结果则在数据源/标签级别整体授权由数据源自身负责更细的过滤。非数据源检索方法描述符没有datasourceId不受此上下文门控原样通过。安全责任内容可追溯脱敏由操作者决定检索结果、诊断信息与元数据是有意可追溯的它们原样携带真实文件路径、账号标识符与消息摘录。AutoRAG不会对数据源内容做脱敏或模糊化。如果这些内容不允许离开本机操作者必须用本地 LLM例如 Ollama 支撑的模型运行 AutoRAG而不是接入云厂商模型。三、共享 Embedding Runtime提供方边界而非共享仓库边界AutoRAG 的共享 Embedding Runtime 是提供方provider边界不是共享归档或向量库边界。它通过仅回环loopback的autorag-gateway计算 Embedding每个数据源保留自己的原生归档、分块、凭据、元数据、向量库、生成发布与来源身份。零配置边界很窄具体分工如下MinSync默认使用网关。AutoRAG 提供端点并记录 profile 身份MinSync 自己拥有.minsync、CDC 分块、向量与重建reindex决策。discrawl可以接收受管的原生[search.embeddings]配置段。当未显式提供connector.configPath时AutoRAG 只写.autorag/datasources/discrawl/config.toml文件以精确标记# AutoRAG managed discrawl embeddings v1开头写入provider、model、base_url和dimensions四个字段并在请求原生 CLI 重建前检查 discrawl 元数据。显式提供的configPath具有最高权威永不被重写。katok与mailcrawl仍等待上游提供方契约上游 issue #19 与 #31在契约发布前AutoRAG 不会把共享运行时强塞给这两个 CLI。qmd与clawgallery完全不受影响qmd 保留原生检索ClawGallery 保留 VDR/原生检索。纯词法lexical-only爬虫保持不变不接收任何语义提供方配置。Embedding 请求只携带文本与选定的模型/profile 数据。AutoRAG不会把归档 ID、源路径、凭据或原生存储路径发给网关。如果运行时不可用数据源在支持的地方保留原生词法/FTS 通道并上报诊断而不会静默切换到远程 Embedding 服务。四、CLI 数据源逐个实战4.1 ClawGallery本地截图与照片库ClawGallery 是面向本地截图与照片的 CLI 数据源。先用cargo install clawgallery安装上游 CLI然后配置可信连接{ datasources: { screenshots: { type: clawgallery, instanceId: personal, connector: { binaryPath: clawgallery, syncVisual: true, vdrBackend: vsplade } } }, datasourceAccess: { allowedTags: [clawgallery], allowedScopes: [/screenshots/personal/**] } }刷新refresh会运行 ClawGallery 的增量bootstrap并在启用时运行受信任的vdr sync。关键词、V-SPLADE 词法、稠密 Embedding 与混合检索全部委托给clawgallery search --jsonAutoRAG 从不读取images.jsonl或vdr.sqlite3也不会触发打标captioning或重命名。从 clawgallery/skill.ts 的实现看有几个值得注意的默认值与模式规则默认轮询间隔为 15 分钟pollingIntervalMs ?? 15 * 60 * 1000默认syncVisual为true检索模式由defaultMode决定顺序缺省为hybridkeyword模式基于图片路径与标题即使没有向量索引也可用lexical需要clawgallery vdr sync --backend vsplade建立的稀疏 V-SPLADE 索引embedding需要--backend mlx或其他稠密后端建立的稠密 VDR 索引hybrid是默认让 ClawGallery 对关键词结果与所有可用的稠密/稀疏向量通道做 RRF 融合。4.2 SpotlightmacOS 原生文件检索spotlight是macOS 独占的连接器 Skill驱动系统内置的mdfindCLI无需额外安装。索引阶段重新运行配置好的 Spotlight 查询并为文件补充文本内容结果元数据携带真实的绝对路径。搜索 Mail、Messages、Safari 等受保护位置时需要为主机应用授予完全磁盘访问权限Full Disk Access。非 macOS 主机上不可用。{ datasources: { mac-files: { type: spotlight, instanceId: local } }, datasourceAccess: { allowedTags: [spotlight], allowedScopes: [/mac-files/local/**] } }spotlight/skill.ts 的 Skill 定义还给出了操作者速查表mdfind query搜索、mdfind -onlyin dir限定目录、mdfind -name按文件名匹配mdls file查看元数据属性kMDItemDisplayName、kMDItemContentType 等mdutil -s /查看索引状态、sudo mdutil -i on //-i off /开关索引、sudo mdutil -E /擦除并重建索引。权限失败会以datasource-permission-denied诊断呈现而不是抛异常。4.3 mailcrawlHimalaya 支撑的本地邮件档案mailcrawl数据源把本地邮件同步与搜索委托给外部mailcrawlCLI。安装nomadamas/mailcrawl0.1.6或更新版本Node.js 24并单独配置 HimalayaAutoRAG 从不直接打开archive.sqlite。注意0.1.3 及更早版本在无操作同步后重复执行index会失败text array must be non-empty因此务必使用 0.1.6。默认情况下 mailcrawl 使用自己的原生归档只有操作者明确想要不同的 mailcrawl 数据目录时才设置connector.dataDir。{ datasources: { mailcrawl: { instanceId: personal, connector: { binaryPath: mailcrawl, account: personal, mailbox: INBOX } } }, datasourceAccess: { allowedTags: [mailcrawl, email], allowedScopes: [/mailcrawl/personal/**] } }刷新流程依次运行mailcrawl sync --json与mailcrawl index --json。检索层暴露**相互独立的 BM25、语义semantic与混合hybrid**三种方法并把结果映射到不透明的/mailcrawl/instance/chunks/chunk-id来源。上游命令请用mailcrawl --help查看——AutoRAG 不会发明一套共享的数据源命令分类法。从 mailcrawl/skill.ts 可以看到三个检索方法由MailcrawlMethod以bm25/semantic/hybrid三种模式实例化当语义索引不可用时例如remote-embedding-rejected只产生datasource-embedding-egress-rejected警告诊断BM25 仍可用。需要区分的是mail-export仍是静态.mbox/.eml路径mailcrawl 是唯一的 Himalaya 支撑的 IMAP/Maildir 路径Gmail 则继续通过 Gmail REST API 单独提供。4.4 Slack via slacrawl免 Token 的本地桌面缓存Slack 可以通过slacrawl的wiretap源使用本地 Slack 桌面缓存这条路径不需要 Slack token。API/bot/user token 仅在以下场景才需要服务器端历史、缺失的缓存数据、更广的线程覆盖或 DM/MPIM 访问。{ datasources: { slack-local: { type: slack, instanceId: local, description: Recent work conversations available in this Macs Slack Desktop cache., connector: { configPath: ~/.slacrawl/config.toml, syncSource: wiretap, timeoutMs: 120000 } } }, datasourceAccess: { allowedTags: [slack, chat], allowedScopes: [/slack-local/local/**] } }初始化并刷新本地镜像slacrawl init -db ~/.slacrawl/slacrawl.db -workspace local slacrawl sync --source wiretap autorag refresh --method datasources4.5 云盘 via rcloneTier-1 Google Drive 与通用清单契约cloud-drive数据源以外部rcloneCLI 作为提供方边界。OAuth、Apple ID/session 或其他凭据只在rclone config里配置AutoRAG 只拿到可信的 remote 名称永远接触不到提供方密钥。Tier-1 是 Google Drive。OneDrive 与挂载/网络 remote 使用同一套 provider 中立的契约。iCloud Drive 明确标记为实验性因为它的 rclone 后端为 Tier 4会周期性要求 Apple ID/密码、2FA 与重新认证。{ datasources: { personal-google-drive: { type: cloud-drive, instanceId: personal, connector: { provider: google-drive, remote: personal-gdrive: } }, company-onedrive: { type: cloud-drive, instanceId: work, pollingIntervalMs: 900000, connector: { provider: onedrive, remote: onedrive:Team Docs, include: [**/*.md, **/*.pdf], exclude: [Archive/**], maxBytesPerFile: 52428800, concurrency: 4, bandwidthLimit: 10M, dryRun: false } } }, datasourceAccess: { allowedTags: [cloud-drive], allowedScopes: [ /personal-google-drive/personal/**, /company-onedrive/work/** ] } }cloud-drive是可复用模板不是必须的连接名。每一个type为cloud-drive的配置键都会成为一个独立数据源配置键即数据源 ID 与 skill 后缀datasource-personal-google-drive与datasource-company-onedrive可分别通过load_datasource_skill独立加载来源作用域在同一别名下相互隔离manifest、mirror 与分块独立存储在.autorag/datasources/alias/instance/下。这让一个进程既能连接同一提供商的多个账号也能连接不同提供商。例如personal-google-drive与client-google-drive都使用 Google Drive但对应不同的 rclone remote。从旧gdrive数据源迁移原 REST 支撑的gdrive数据源及其backend: rclone兼容模式已移除。每个 Google Drive 连接都必须配置为具名的cloud-drive别名并用rclone config认证 remote{ datasources: { google-drive: { type: cloud-drive, instanceId: default, connector: { provider: google-drive, remote: my-google-drive: } } } }现有gdrive配置必须在下次刷新前重命名并转换旧的 REST token 设置与/gdrive/**作用域不再被读取。命令行数据源刷新rclone config autorag refresh --method datasources --config ./config.json autorag search the renewal terms in the team drive每次刷新的增量语义运行rclone lsjson --recursive --files-only --hash与工作区本地 manifest.autorag/datasources/connection-alias/instance/manifest.json比对然后只把新增/变更的可索引文件复制进mirror/已删除和重命名的虚拟路径会从完成快照中移除。无操作no-op刷新下载零字节且不重写chunks.json复制失败时保留上一份 manifest 与 mirror 供查询期检索使用。include、exclude、maxBytesPerFile、concurrency、bandwidthLimit、dryRun都是可信服务端配置模型/工具参数无法修改它们这些参数在 cloud-drive/skill.ts 的 Skill 定义中同样被列为可信清单项。搜索前Agent 先用load_datasource_skill加载数据源 skill再用自然语言查询调用search_datasource_documents可按需附加收窄 scope如/company-onedrive/work/**。它绝不能自己调用rclone或索取凭据。4.6 KakaoTalk via katokKakaoTalk 支持通过外部katokCLI 实现。硬性规则如下AutoRAG从不直接读取KakaoTalk 数据库缺失二进制、权限、同步或索引失败时返回诊断信息而不是抛异常远程 Embedding 出口配置在 spawnkatok之前就被拒绝对应datasource-embedding-egress-rejected诊断见 types.ts 的诊断码枚举katok 的 stdout/stderr 与抛出的错误文本会作为数据源诊断浮出。程序化接入示例autorag/librarianimport { AutoRAGAgent, KatokSkill } from autorag/librarian; const agent new AutoRAGAgent({ searchPaths: [/docs], datasourceSkills: [new KatokSkill({ instanceId: personal })], datasourceAccess: { allowedTags: [kakaotalk], allowedScopes: [/kakao/personal/**], }, }); await agent.refresh(); const hits await agent.searchDatasourceDocuments(contract renewal, { topK: 5 });五、通用连接别名与操作者描述每一个数据源条目都可以使用带连接别名的可复用模板从而在同一 Agent 里支撑同一提供商的多个连接{ datasources: { personal-gmail: { type: gmail, connector: { tokenEnv: PERSONAL_GMAIL_TOKEN } }, company-slack: { type: slack, connector: { configPath: /secure/company-slack.toml } }, family-kakao: { type: kakao, channels: { names: [가족방] }, connector: { binaryPath: katok } } } }在 factory.ts 的buildDatasourceSkills中当配置键名与模板名不一致、或配置了频道白名单时skill 会被包装为AliasedDatasourceSkill。从 aliased-skill.ts 可以看到别名机制的具体行为描述符的name、id、datasourceId全部改写为别名来源描述中的/原始名/段与datasource-原始名前缀被统一重写检索方法名如kakao-bm25与方法返回结果的source、id、datasourceId元数据一并重写保持模型可见身份独立其 source scope、诊断、方法名、本地存储/缓存命名空间与访问策略都落在别名之下即配置键 独立数据源 ID 可独立加载的datasource-aliasskill。操作者编写的数据源描述每个已配置连接都可以携带可选的description。这是受信任的操作者上下文会显示在数据源描述符与渐进式披露 skill manifest 中帮助 librarian 理解一个连接通常如何使用而不会改变其访问策略{ datasources: { personal-google-drive: { type: cloud-drive, instanceId: personal, description: Project contracts and government-support documents. Prefer this connection for current agreements; treat Archive/ as historical., connector: { provider: google-drive, remote: personal-gdrive: } } } }描述由用户提供不会自动推断也不能授予访问权或扩大datasourceAccess.allowedScopes。在 factory 中非空描述会通过DescribedDatasourceSkill包装进最终 skill见 factory.ts。六、聊天频道选择白名单别名 vs 全频道聊天/归档数据源kakao、discord、telegram、whatsapp、slack默认搜索所有频道、房间、聊天与 DM。要暴露受限数据源就创建另一个别名并用可信配置限制{ datasources: { all-discord: { type: discord, connector: { root: /managed/discrawl } }, release-channel: { type: discord, connector: { root: /managed/discrawl }, channels: { ids: [1234567890], names: [release-engineering] } } }, datasourceAccess: { allowedTags: [discord], allowedScopes: [/all-discord/**, /release-channel/**] } }后端归档仍按各 CLI 自己的配置本地共享别名是 AutoRAG 的可见性边界。受限别名会过滤返回的频道/聊天元数据而默认别名保持全频道。实现层面AliasedDatasourceSkill在后端搜索之后再执行频道白名单过滤matchesChannel检查channelId/chatId/roomId与channelName/chatName/roomName元数据见 aliased-skill.ts因此未提供白名单时天然保留后端全频道默认行为。Agent skill manifest 会明确声明自己是全频道还是白名单模式编排器可在搜索前据此选择正确的数据源。七、索引元数据与分层实例PollingMetadatanone / poll / cronPollingMetadata见 types.ts支持三种模式mode: none仅手动索引mode: pollintervalMs常规刷新检查mode: croncronExpr作为描述符元数据声明。当前 AutoRAG v1 执行全局刷新节拍agent.refresh()/ auto-refresh让每个 skill 自己决定哪些工作到期。Cron 元数据目前只做校验/声明尚未由 AutoRAG 调度执行parseCronExpr/isDue实现在 polling.ts测试见 test/datasource/polling.test.ts。分层实例Hierarchical instancesSkill 可以发布instances例如Slack 工作区 - 频道Google Drive 账号 - 文件夹KakaoTalk 账号 - 聊天语料Notion 工作区 - 数据库/页面树每个实例都映射到斜杠分层的数据库源根如/kakao/personal或/slack/local分块挂在/skill/instance/chunks/id之下。对应的构建函数是 scope.ts 中的buildDatasourceInstanceSource如/kakao/acct-1与buildDatasourceChunkSource如/kakao/acct-1/chunks/c-42。来源是不透明的纯路径树绝不产生或匹配#片段且与既有检索 scope 语法glob、前导斜杠归一化完全兼容。DatasourceSkillRegistry.resolveInstances只实例化DatasourceAccessContext允许的 skill 与其声明的实例每个实例携带从可信 skill 名与实例 ID 构建的sourcePath——绝不来自模型输入见 registry.ts。八、Datasource UI本地回环控制平面操作者可以在autorag ui中添加、测试、启用和移除连接而不必手改config.json。UI 是本地回环控制平面它使用同一个 factory绝不允许从模型工具参数授予访问权也绝不把 token 值写进配置。UI 也可以部署在显式配置的反向代理后面设置ui.allowRemote为true、把ui.tokenEnv保留在进程环境中、并在ui.corsOrigins中列出精确的浏览器来源。不支持通配符 CORS因为 UI 使用带凭据的请求。ui.publicOrigin是打印给操作者并在打开浏览器时使用的 URL。没有allowRemote时非回环绑定会被拒绝。九、新数据源接入检查清单对照 datasource-skills.md 与DatasourceSkill契约types.ts新增一个数据源需要满足实现DatasourceSkill接口describe/polling/index/retrievalMethods/describeSources/skillManifest返回的检索方法描述符必须设置datasourceId与授权tags发出斜杠分层的source值复用 scope.ts 的构建函数附带 polling/cron 元数据提供解释数据内容的来源描述describeSources添加默认拒绝与能力专属capability-specific的 scope 测试只有支持scoped能力的数据源才需要多 scope 与用户 scope 交集测试为缺失凭据/二进制/权限添加不抛异常的诊断对应DatasourceDiagnosticCode枚举添加 issue 标签datasource-skill、integration以及一个数据源专属标签。十、关联源码与测试速查核心契约与类型types.ts访问上下文default-deny 实现access-context.ts测试见 test/datasource/access-context.test.ts连接别名重写aliased-skill.ts测试见 test/datasource/aliased-skill.test.ts配置驱动工厂与内置模板列表skills/factory.ts来源路径与 scope 匹配scope.ts测试见 test/datasource/scope.test.ts注册表与实例解析registry.ts测试见 test/datasource/registry.test.ts结果过滤检索期门控result-filter.ts测试见 test/datasource/result-filter.test.ts各 Skill 实现clawgallery/skill.ts、spotlight/skill.ts、mailcrawl/skill.ts、cloud-drive/skill.ts、slack/index.ts、katok/skill.ts对应测试位于 test/datasource/skills/ 下【免费下载链接】AutoRAGAutoRAG: Now your agent can find anything in your computer. It gets smarter if you are using it frequently.项目地址: https://gitcode.com/GitHub_Trending/au/AutoRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考