KakaoTalk katok 搜索

Skill 功能

以 katok CLI 作为唯一的执行入口，将 macOS KakaoTalk 聊天记录同步至本地归档与搜索索引，并支持关键词（keyword）、BM25、语义（semantic）搜索以及 chunk 文本块查询。

本 Skill 沿用原有的 kakaotalk-mac 安装路径，但内部逻辑基于 katok 实现。发送/删除消息、UI 自动化、直接读取数据库、处理身份验证缓存及解密密钥/凭据等均不属于本 Skill 的功能范围。

隐私规则

切勿在本 Skill 中探查本地数据库内部细节。
切勿直接读取 KakaoTalk 的数据库文件。
切勿处理身份验证缓存或解密密钥/凭据。
增量同步/导入 macOS 本地 KakaoTalk 数据时，请使用 katok sync --source macos --json。
搜索命令应优先返回摘要片段（snippet）和 chunk ID。
仅当用户明确要求打开某个搜索结果或直接提供了 chunk ID 时，才获取完整的 chunk 内容。

适用场景

“帮我在 KakaoTalk 里搜一下某个关键词”
“在 KakaoTalk 记录里找找之前关于会议/合同/约定的聊天内容”
“打开这个搜索结果对应的 chunk 文本块”
“确认最新的聊天记录是否已同步，然后再帮我搜索”

不适用场景

非 macOS 环境
需要在 Intel 芯片 Mac 上构建本地 EmbeddingGemma 语义索引的场景
需要发送或删除 KakaoTalk 消息的场景
要求直接操作 KakaoTalk 数据库文件、验证缓存或解密密钥/凭据的请求
要求接入服务端官方 Kakao API 的请求

前置条件

Apple Silicon macOS
已安装 Mac 版 KakaoTalk
已安装 Homebrew 或 Cargo
已安装 katok CLI
当前终端应用已获授予完全磁盘访问权限（Full Disk Access）

安装 katok

Homebrew:

brew tap NomaDamas/katok https://github.com/NomaDamas/katok.git
brew install katok

Cargo:

cargo install katok
export PATH="$HOME/.cargo/bin:$PATH"

安装完成后，确认 CLI 是否正常可用。

katok --help
katok doctor --json

工作流

1. 检查准备状态（不触发应用数据权限弹窗）

katok doctor --json

通过 doctor --json 输出中的 freshness 字段查看上一次同步/索引状态。默认的 doctor 命令不会对 macOS 应用数据发起探测，因此非常适合在不触发权限弹窗的前提下检查系统准备状态。

2. 必要时打开 macOS 权限设置

若需要配置完全磁盘访问权限（Full Disk Access），可打开系统设置页面以便用户手动开启授权。

katok permissions macos

虽然 KakaoTalk UI 自动化不属于本 Skill 的范围，但若为了上游诊断确实需要打开辅助功能（Accessibility）设置页面，可以使用以下命令：

katok permissions macos --accessibility

3. 仅在必要时运行显式 macOS 配置诊断

仅当需要检查 KakaoTalk 应用安装状态、容器（container）以及数据库文件访问等 macOS 数据源适配器（source adapter）状态时，才执行探针（probe）。该命令可能会触发 macOS 的应用数据访问权限弹窗。

katok doctor --macos-probe --json

4. 同步本地 KakaoTalk 归档

如果需要最新的聊天记录，或者 freshness.recommendation.sync_before_search 返回为 true，请在搜索前先执行同步。

katok sync --source macos --json

如果使用配置文件中默认的数据源适配器：

katok sync --json

5. 构建或刷新语义索引

在进行语义搜索前，如果 freshness.recommendation.index_before_semantic_search 为 true，或者需要将刚同步的内容更新至语义搜索中，请先构建/刷新索引。

katok index --json

katok index 默认使用本地的 embeddinggemma-300m-q4 嵌入模型（embedder），无需依赖 Python、Jina、TEI 或独立的 HTTP 向量嵌入服务器。

6. 使用精准匹配度最高的模式进行搜索

精确匹配字符串、人名、银行账号、专有名词时，优先使用关键词搜索（keyword search）。

katok search keyword "검색어" --json

包含多个词汇的普通查询语句，使用 BM25 搜索。

katok search bm25 "지난주 미팅 자료" --json

记不清具体措辞的意图/语义类查询，使用语义搜索（semantic search）。

katok search semantic "최근에 논의한 세금 신고 일정" --json

7. 仅在需要时获取指定的 chunk 文本块

搜索结果应先围绕摘要片段（snippet）和 chunk ID 进行整理总结。只有当用户明确要求打开某条结果或主动提供了 chunk ID 时，才去查询原文字段 chunk。

katok chunk get <chunk-id> --json
katok chunk context <chunk-id> --json
katok chunk parent <chunk-id> --json

katok chunk get <chunk-id> --json: 查询该 chunk 的原文字段
katok chunk context <chunk-id> --json: 查询同一聊天室内的上下文微块（micro chunk）
katok chunk parent <chunk-id> --json: 查询语义搜索的父窗口（parent window）

仅限测试/仿真问答

仅在未安装实际 KakaoTalk，仅依靠上游 fixture 进行测试时，才使用测试数据源（fixture source）与确定性嵌入模型（deterministic embedder）。

katok sync --source fixture tests/fixtures/kakao/replies.jsonl --json
KATOK_EMBEDDER=local-test katok index --json
KATOK_EMBEDDER=mock katok index --json

在实际生产运行路径中，切勿使用 fixture、mock embedder 或远程向量嵌入端点（embedding endpoint）。

完成标准

若用户请求检查准备状态，已总结 katok doctor --json 的输出结果及 freshness 建议。
若用户请求搜索最新内容，已明确说明是否需要先执行 katok sync --source macos --json 与 katok index --json。
若为搜索请求，已阐明选用 keyword / BM25 / semantic 搜索模式的原因，并提供了 JSON 搜索结果摘要。
若为 chunk 查询请求，仅针对用户指定的 chunk ID 汇总了 katok chunk get/context/parent 的查询结果。

常见失败模式 / 排查

未安装 katok 或 Cargo 二进制可执行文件 PATH 环境变量缺失
设备非 Apple Silicon macOS
未安装 Mac 版 KakaoTalk
未授予完全磁盘访问权限（Full Disk Access）
执行 katok doctor --macos-probe --json 时容器（container）或数据库文件访问失败
未进行同步导致本地归档数据为空
语义索引已过期或尚未生成
搜索结果仅靠 snippet / chunk ID 不足以解答问题，需要显式获取 chunk 内容

说明事项

本 Skill 仅用于读取、搜索和调取数据（Read / Search / Retrieve）。
不支持发送与删除消息。
不直接处理数据库内部结构、身份验证缓存或解密密钥/凭据。
尽管旧有的 Skill 安装名称为 kakaotalk-mac，但实际调用的 CLI 工具名称为 katok。

kakaotalk-mac

相关 Skills