企业官网建设流程全解析

AutoRAG KakaoTalk/katok 数据源手动 QA 指南：default-deny 访问控制与五项必检清单

【免费下载链接】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

AutoRAG 通过外部katokCLI 将 KakaoTalk 聊天记录作为受信任数据源接入 Agent。本文以仓库中的 KakaoTalk / katok manual QA 检查清单 为主体，系统讲解该数据源的接入前置条件、基于标签（tag）的 default-deny 访问控制模型，以及一套可重复执行的五项手动质量验证流程。读完本文，你将掌握如何在 AutoRAG 中正确配置 KakaoTalk 数据源、验证其访问授权边界，并能在缺少真实 KakaoTalk 凭据的环境中安全地完成回归测试。

检查清单定位：验证什么，为什么重要

这份 manual QA 清单是 KakaoTalk 数据源技能的验收标准，核心验证两件事：

1. KatokSkill 数据源技能本身能否在 AutoRAG 中完成索引、检索与诊断的完整链路；
2. default-deny 的标签访问控制是否正确生效——未显式授权的场景下，KakaoTalk 数据必须被完全拒之门外，而不是部分可见。

清单同时强调了一个关键设计约束：katok 不暴露 per-source 的 scope 过滤能力。这意味着 AutoRAG 不会（也无法）对 KakaoTalk 数据做细粒度的虚拟源范围（virtual source scope）过滤，聊天/频道级别的过滤完全由 katok 自己负责。AutoRAG 侧的授权边界只存在于「数据源技能 + 标签」这一层。这一点贯穿整个清单的每一项检查，也是理解本数据源安全模型的前提。

前置条件：让 AutoRAG 能驱动 katok

在执行任何检查之前，环境必须满足三项前置条件（对应原文档 Preconditions 节）：

• katok 已安装且在PATH中可用，或者通过new KatokClient({ binaryPath })显式指定二进制路径。从源码看，KatokClient 的默认二进制名 为katok，即裸命令按 PATH 查找；binaryPath未提供时走默认值（见 client.ts 的 commandFor 实现）。
• KakaoTalk 的访问授权已在 AutoRAG 之外完成：AutoRAG 永远不直接打开 KakaoTalk 数据库，它只是把katok当作子进程调用（client.ts 的类注释 明确说明这一点），因此 macOS 应用容器权限、账号授权等步骤必须在系统层面预先就绪。
• AutoRAG 配置了KatokSkill并显式声明受信任访问。原文档给出的最小配置如下：

new AutoRAGAgent({ searchPaths: ["/docs"], datasourceSkills: [new KatokSkill({ instanceId: "personal" })], datasourceAccess: { allowedTags: ["kakaotalk"], }, });

这段配置揭示了两个关键点：

• KatokSkill通过instanceId区分实例。源码中默认实例名为default（skill.ts 的常量定义），支持传入instances数组管理多个实例，每个实例对应一个独立的/kakao/<instance-id>虚拟源（describeSources 实现）。
• datasourceAccess.allowedTags是 Agent 侧唯一对 KakaoTalk 生效的授权通道。KatokSkill的默认标签为["kakaotalk", "personal", "pii"]（skill.ts 常量），其中pii表明该数据源天然携带个人敏感信息，这与后文「公共回复需脱敏」的检查项相呼应。

AutoRAGAgent构造选项中的datasourceSkills与datasourceAccess定义位于 src/agent/agent.ts，两者通过DatasourceAccessContext衔接，构成整个访问控制链路。

访问控制模型：default-deny 与标签授权

KakaoTalk 数据源的访问控制建立在 DatasourceAccessContext 之上，其核心逻辑非常直白：

• 未配置任何allowedTags（或为空数组）⇒ 一律拒绝（denyAll = true），对应源码中isDenyAll的语义（access-context.ts#L37-L43）。
• 配置了标签后，数据源描述符（descriptor）必须至少有一个标签与allowedTags交集非空才可访问（isAccessible 实现）。
• 非数据源检索方法（无datasourceId，如posix）不受此上下文门控，直接放行（access-context.ts#L53-L54），保证普通检索不受影响。

对 KakaoTalk 而言，KatokSkill的describe()会暴露type: "kakaotalk"与默认标签（skill.ts describe 实现），因此 Agent 侧的allowedTags: ["kakaotalk"]恰好与之匹配，从而完成授权。

需要特别强调 scope 层面的差异：数据源的allowedSourcesPredicate只对声明了scoped能力的数据源生效（access-context.ts#L61-L81）。而KatokSkill声明的能力是["chat", "external-cli", "polling", "bm25", "semantic"]（skill.ts#L61），不包含scoped。这从源码层面印证了原文档的判断：katok 数据源不做虚拟源范围过滤，授权只发生在标签层。聊天/频道级别的过滤（如哪些聊天可被搜索）由 katok 在自身数据层面完成并随命中元数据返回。

五项必检清单详解

以下五项检查构成完整的回归验证序列，建议按顺序执行。

检查 1：Default deny —— 未授权必须零结果

操作步骤：

1. 从配置中移除datasourceAccess（或清空allowedTags）；
2. 调用searchDatasourceDocuments("hello")；
3. 断言：数据源结果为零，且不抛任何异常。

期望与原理：移除datasourceAccess后，DatasourceAccessContext进入denyAll状态，任何 KakaoTalk 数据源描述符都不可访问，检索结果必然为空。这一行为同样体现在检索方法层：KatokBm25Method/KatokSemanticMethod的retrieve在客户端失败时「坍缩为空结果集，检索永不抛异常」（methods.ts 注释）。测试 skill.test.ts#L224-L240 专门验证了「底层搜索失败时降级为[]」的行为。

检查 2：Trusted allow —— 授权后数据源进入可用状态

操作步骤：

1. 恢复allowedTags: ["kakaotalk"]；
2. 执行agent.refresh()；
3. 断言：components.datasources状态为configured或degraded。

期望与原理：refresh 会触发KatokSkill.index()，其内部按doctor → sync → index三步串行执行（skill.ts index 实现）：

• doctor：探测 katok 是否就绪（ready布尔值）；
• sync：同步聊天记录（返回synced与可选messageCount）；
• index：生成分块索引（返回chunkCount）。

任一步失败都不会抛异常，而是返回带诊断码的结果——doctor失败为datasource-unavailable（warning 级），sync/index失败为datasource-index-failed（error 级）。这正是「configured或degraded」两种期望状态的来源：全链路成功即configured，索引部分失败即degraded，但都不至于让 Agent 崩溃。对应测试见 skill.test.ts#L134-L199。

成功索引后lastIndexedAt会被刷新，轮询元数据同步更新（skill.ts#L87）。KatokSkill默认以15 分钟为间隔进入 poll 模式（skill.ts#L34，测试见 skill.test.ts#L94-L104）。

检查 3：Datasource-native filtering —— 过滤职责归 katok

操作步骤：

1. 以已授权的 KakaoTalk 数据源执行搜索；
2. 断言：katok 自己的聊天/频道过滤与聊天身份元数据保持原样，AutoRAG 不施加虚拟源范围。

期望与原理：这是对「katok 不暴露 per-source scope」约束的实证。检索命中的源标识符是 path-opaque 的虚拟路径/kakao/<instance-id>/chunks/<chunk-id>（paths.ts katokSourcePath 实现），真实的文件系统路径、账号信息等被完全遮蔽。聊天身份元数据（如chat_name、sender_nickname、started_at、ended_at）由客户端从 katok 的 JSON 输出中解析并挂到命中的 metadata 上（client.ts normalizeHit 实现），AutoRAG 原样透传，不做二次过滤。测试 direct-cli.test.ts#L74-L112 用真实形态的 katok 输出验证了聊天身份字段的完整保留。

检查 4：Missing binary / permission failure —— 失败必须是诊断而非异常

操作步骤：

1. 将KatokClient指向不存在的二进制路径，或在缺少 OS 权限的环境下运行；
2. 断言：不抛异常，失败以 warning/error 诊断的形式呈现。

期望与原理：这是客户端「永不抛异常」契约的实战检验。KatokClient将binary-missing（ENOENT）、nonzero-exit、spawn-error、timeout、aborted、stdout/stderr-too-large、invalid-json、invalid-shape等九类失败原因统一收敛为ok: false的判别联合（types.ts KatokFailureReason 定义），由调用方转为诊断对象。

更值得注意的是隐私保护：任何包含路径分隔符的 stderr 输出都会被替换为通用文案「katok command failed; details suppressed for datasource privacy」（client.ts sanitizeDiagnosticText 实现，skill.ts 同名字段），防止真实文件路径经诊断通道泄露。同时子进程环境经过白名单过滤，仅继承HOME、LANG、LC_ALL、PATH、TMPDIR等安全键与KATOK_前缀变量（client.ts#L26-L27），进一步收窄攻击面。测试 skill.test.ts#L188-L199 验证了「步骤抛异常时结果不含原始错误信息」。

检查 5：Public response curation —— 公共回复必须脱敏

操作步骤：

1. 调用searchDocuments()，让 librarian（Agent 侧的答案策展层）基于数据源证据生成 KakaoTalk 支持的答案；
2. 断言：可见的answer与results中包含扎根于数据源证据的策展事实。

期望与原理：这一步是端到端的产出检查。答案必须基于数据源证据生成（grounded），而不是模型凭空捏造。同时存在硬性输出约束——KatokSkill的 skill manifest 明确写入输出规则：/kakao/<instance>/chunks/<id>这类内部源标识符、真实文件路径、账号 ID、电话号码一律不得出现在可见答案中（skill.ts skillManifest 的 Output rules 段）。skill manifest 测试同时断言内容不包含Library/Containers等真实 macOS 路径（skill.test.ts#L80-L91），确保给 Agent 的指令本身就是脱敏的。

环境限制说明：CI 与开发容器中的执行策略

原文档明确了一个现实约束：CI 和大多数开发容器中没有真实的 KakaoTalk 配置文件，也没有 macOS 应用容器的权限。因此：

• 检查 1 和检查 4 可在这些环境用 test/fake 的 katok 客户端执行（它们不依赖真实聊天数据，只验证拒绝与失败处理路径）；
• 依赖真实数据的检查（2、3、5）应如实记录为「因本地缺少 KakaoTalk 凭据而手动受阻」，而不是绕过安全要求。

仓库为这种受限环境提供了现成的测试基建：skill.test.ts用StubSkillClient模拟 doctor/sync/index/search 的成败（skill.test.ts#L9-L27），direct-cli.test.ts则用临时目录中的假 katok 脚本做真实子进程调用验证（direct-cli.test.ts#L31-L41），两者组合可以无真实凭据地覆盖「拒绝」「失败诊断」「CLI 参数正确性」「聊天元数据解析」等核心路径。需要说明的是，KatokClient的默认超时为 60 秒、最大缓冲为 1 MiB（types.ts#L32-L39），在 CI 中做 fake 验证时可适当沿用这些默认值。

常见失败模式速查

结合源码与测试，把检查中可能观察到的失败现象与对应根因整理如下，便于排障：

小结

本清单的价值在于把「KakaoTalk 数据源的安全接入」压缩成五项可重复、可断言的检查：拒绝必须彻底（check 1）、授权必须可见（check 2）、过滤边界必须清晰（check 3）、失败必须温和且脱敏（check 4）、产出必须可溯源且合规（check 5）。配合仓库中KatokSkill/KatokClient/DatasourceAccessContext的实现与skill.test.ts、direct-cli.test.ts的测试基建，即使在没有真实 KakaoTalk 凭据的 CI 环境中，也能守住安全要求的同时完成大部分回归验证。接入生产前，务必在具备真实凭据的机器上补齐检查 2、3、5，并以实际数据确认聊天级过滤与输出脱敏符合预期。

【免费下载链接】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