内容
# ktok
`ktok` 是一款 카카오톡 macOS 自动化命令行工具、MCP 服务器和共享本地工作空间所有者。
`ktok` 保留了 카카오톡 I/O 层：它观察消息/附件、发送消息/文件、下载附件并导入原始历史记录。它还拥有位于 `KTOK_HOME` 或 `~/.ktok` 的规范本地数据工作空间，以便其他本地服务可以存储和读取共享的 카카오톡相关输入、事件和文件，而无需语言 SDK。
## 快速入门
```bash
swift build
ktok status
ktok login work
ktok chats --json
ktok read "채팅방" --json
ktok watch "채팅방" --json
ktok monitor "채팅방" --persona luna
ktok inputs save-text --account work --source my-service --text "hello" --json
ktok inputs save-file --account work --source my-service /path/to/file.pdf --json
ktok storage paths --account work --chat "채팅방" --json
ktok mcp-server
```
`read --json` 保留现有的 `messages` 数组，并包含可见的附件候选项：
```json
{
"chat": "채팅방",
"fetched_at": "2026-05-29T10:00:00.000Z",
"count": 1,
"messages": [
{"author": "홍길동", "time_raw": "10:00", "body": "확인 부탁드립니다"}
],
"attachments": [
{
"attachment_id": "att_0123456789abcdef",
"chat": "채팅방",
"filename": "report.pdf",
"candidate_value": "report.pdf",
"author": "홍길동",
"time_raw": "10:00",
"row_index": 42,
"reason": "extension"
}
]
}
```
默认情况下，`read` 和 `watch` 也会将观察到的消息/附件事件记录到共享工作空间中。使用 `--no-record-events` 禁用一次性记录。
`monitor` 打开一个房间一次，保持监视该固定房间，只有在配置的角色应该响应时才响应：
```bash
ktok assume work
ktok monitor "채팅방" --persona luna
```
`luna` 角色响应直接调用（例如 `루나` 或 `비서야`）、一般问候和温暖的同理心提示。它不将 `친구` 或 `지인` 视为 Luna。监视状态保存在活动账户 SQLite 数据库中，位于 `~/.ktok/accounts/<alias>/history.sqlite`。
如果监视读取恢复失败重复出现，它会记录失败阶段并使用相同的参数重新启动自身。使用 `--restart-after-read-failures 0` 仅在您要禁用该恢复行为时。
## 共享工作空间
存储根目录为 `KTOK_HOME`（如果设置），否则为 `~/.ktok`。
```text
~/.ktok/
.gitignore
README.md
config/
state/
current-account.json
accounts/
<alias>/
account.json
rooms.json
history.sqlite
events/
yyyy-mm-dd.jsonl
inputs/
text/yyyy-mm-dd/<input_id>.json
files/yyyy-mm-dd/<input_id>/original.*
files/yyyy-mm-dd/<input_id>/metadata.json
rooms/
<chat_id>/
events/yyyy-mm-dd.jsonl
attachments/<attachment_id>/metadata.json
attachments/<attachment_id>/original.*
downloads/
exports/
jobs/
cache/
ax-cache.json
logs/
```
工作空间规则：
- `~/.ktok` 是 `ktok` 和本地服务共享的规范本地工作空间。
- 服务应首先通过 `ktok storage`、`ktok events` 和 `ktok inputs` 编写共享数据。
- 直接文件写入仅在遵循开发指南的原子写入和 JSONL 锁定规则时才允许。
- 机密信息不存储在 `~/.ktok` 中；登录密码存储在 Keychain 或平台机密后端中。
- `history.sqlite` 保留由 `sync-history` 和 `import-history` 填充的原始搜索数据库。
`~/.ktok` 内的默认 `.gitignore` 是本地优先的：
```gitignore
*
!.gitignore
!README.md
!config/
!config/.gitkeep
```
## 工作空间命令行界面
```bash
ktok storage paths --json
ktok storage paths --account work --chat "채팅방" --json
ktok storage validate --json
ktok events append --account work --type message --json-file event.json --json
ktok inputs save-text --account work --source service --text "hello" --json
ktok inputs save-file --account work --source service /path/to/file.pdf --json
```
写入命令会创建父目录，使用原子文件写入，并在文件锁下追加 JSONL 事件。JSON 输出包括 `id`、`account_alias`、`chat_id`、`path`、`event_path`、`event_paths` 和 `created_at`。
## 登录模型
```bash
scripts/setup-login-env.sh --alias work
ktok login work
ktok login private --trust-state
ktok assume work
ktok whoami --json
ktok logout
```
`scripts/setup-login-env.sh` 将非机密登录设置写入 `~/.ktok/config/.env`，删除该别名的任何明文密码条目，并将密码存储在平台机密后端中。`ktok login <alias>` 从环境或 `.env` 读取账户 ID，从环境或机密后端读取密码，登录 카카오톡，并写入账户元数据/状态。
- macOS：Keychain 服务 `ktok`，账户 `login:<alias>`。
- Windows 端口推荐：Windows Credential Manager 目标 `ktok/login/<alias>`。
- Linux 端口推荐：Secret Service/libsecret。
如果用户手动切换 카카오톡 账户，请在账户范围写入之前运行 `ktok whoami` 或 `ktok assume <alias>`。
## MCP
运行：
```bash
ktok mcp-server
```
MCP 服务器暴露了 12 种工具：
| 工具 | 用途 |
| --- | --- |
| `ktok_read` | 读取可见的消息和附件候选项 |
| `ktok_send` | 发送文本消息 |
| `ktok_send_image` | 发送图像 |
| `ktok_send_file` | 发送文件 |
| `ktok_download_file` | 通过 `attachment_id` 或 `filename` 下载附件 |
| `ktok_sync_history` | 将完整聊天 CSV 导出/导入原始历史数据库 |
| `ktok_import_history` | 导入现有的 카카오톡 CSV |
| `ktok_query_history` | 查询原始历史数据库 |
| `ktok_storage_paths` | 解析共享工作空间路径 |
| `ktok_inputs_save_text` | 将用户文本输入保存到 `~/.ktok` |
| `ktok_inputs_save_file` | 将用户文件输入保存到 `~/.ktok` |
| `ktok_events_append` | 追加共享工作空间事件 |
`ktok watch --json` 故意作为命令行子进程管理，因为它是一个长期运行的流。
## 文档
- [docs/CLI.md](docs/CLI.md)：完整的命令行参考。
- [docs/BOT_ONBOARDING.md](docs/BOT_ONBOARDING.md)：机器人 LaunchAgent、Codex 和故障排除操作手册。
- [docs/DEV_GUIDE.md](docs/DEV_GUIDE.md)：其他服务的共享工作空间规则。
- [docs/SERVICE_INTEGRATION.md](docs/SERVICE_INTEGRATION.md)：与开发指南的兼容性指针。
## 开发检查
```bash
swift build
swift build -c release
git diff --check
KTOK_HOME=/tmp/ktok-home-test ktok storage paths --json
KTOK_HOME=/tmp/ktok-home-test ktok inputs save-text --account work --source test --text "hello" --json
```
