kmsg架构
介绍基于Swift和macOS辅助功能API的组件、数据流与设计决策。
更新于 2026年7月27日在GitHub编辑
概览
kmsg是面向macOS 13及更高版本的Swift 6可执行文件。它不实现KakaoTalk私有网络协议，而是通过辅助功能API操作屏幕上可见的macOS应用。
CLI commands
↓
KakaoTalk domain services
↓
Accessibility helpers + AX path cache
↓
AXUIElement / CGEvent / AppKit
↓
KakaoTalk for macOS
原生stdio MCP服务器通过子进程调用同一套kmsg命令，再将结果结构化返回。CLI与MCP因此共享权限、缓存及错误处理逻辑。
主要组件
| 组件 | 职责 |
|---|---|
Sources/kmsg/Commands/ |
参数解析、权限与认证、输出格式 |
UIElement |
AXUIElement封装和有界层级搜索 |
AXActionRunner |
焦点、文本输入、键盘与重试 |
AXPathCacheStore |
保存并验证AX路径 |
KakaoTalkApp |
进程与窗口的启动、定位和恢复 |
ChatListScanner |
读取聊天列表和预览 |
ChatIdentityRegistryStore |
管理本地chat_id |
ChatWindowResolver |
复用、搜索和恢复聊天窗口 |
KakaoTalkTranscriptReader |
将消息行规范化 |
KmsgMCPServer |
MCP帧、工具、超时和错误映射 |
数据流
启动与认证
- 需要UI访问的命令检查辅助功能权限。
- 如有需要，启动KakaoTalk。
- 检查当前登录状态。
- 使用加密凭据或提示用户输入。
read --background-safe不会自动启动、登录或操作前台UI。
读取
- 通过聊天名称或
chat_id解析目标窗口。 - 找到输入框、聊天面板和消息列表。
- 将可见行转换为规范化消息记录。
- 输出可读文本或单个JSON文档。
监控
watch在启动时建立现有记录基线，仅输出之后出现的消息。为避免重放旧消息，缺少可靠时间信息的行可能会在启动阶段被抑制。
发送
文本发送会找到输入框、输入Unicode文本并验证发送动作。图片发送使用macOS pasteboard，并处理KakaoTalk的确认UI。
本地状态
| 路径 | 内容 |
|---|---|
~/.config/kmsg/credentials.json |
加密凭据 |
~/.config/kmsg/credentials/primary.key |
本地AES-GCM密钥 |
~/.kmsg/ax-path-cache.json |
已验证的AX路径 |
~/.kmsg/chat-registry.json |
本地聊天ID |
缓存会检查KakaoTalk版本、根指纹、schema和TTL。过期路径会被丢弃，并通过有界搜索恢复。
设计决策
不使用私有协议
KakaoTalk没有公开面向第三方的官方消息API。kmsg不对LOCO协议进行逆向工程，而是与用户正在运行的应用UI交互。这并不代表官方集成或零风险使用。
macOS原生实现
Swift可直接连接AppKit、ApplicationServices、AXUIElement和CGEvent，并以无需额外运行时的单个二进制发布。
有界搜索与自修复
AX层级搜索开销较高，而且KakaoTalk更新后结构可能变化。所有搜索都设置节点预算；已缓存路径在使用前会再次验证。
输出通道分离
结构化结果写入stdout，AX诊断写入stderr，避免JSON消费者和MCP子进程把日志混入payload。
更完整的数据流与目录结构请参阅英文架构文档。