需要自动化韩国本地服务（SRT、KBO、로또、카카오톡…

在 Claude Code、Codex、Cursor 等编码代理中，通过 k-skill 统一安装和调用韩国服务自动化技能。

适用场景

解决思路

1. 安装全部技能：运行 `npx k-skill install`；或先 `npm install -g k-skill` 再运行 `k-skill install`。
2. 按需安装：运行 `npx k-skill install srt` 只装 SRT；运行 `npx k-skill install kbo lotto` 装 KBO 和 로또。
3. 安装后执行 `k-skill-setup`，生成 sops+age 密钥、初始化公共 secrets 文件并检查运行时。
4. 初始化顺序：先 `k-skill install`，再 `k-skill-setup`，然后把 secrets 值安全地注册到本地（禁止粘贴到聊天），最后查看各功能文档。
5. 禁止把密码/API key 输入聊天消息，禁止把 `.env` 提交到 git，禁止在代码里硬编码。
6. 使用标准环境变量：`SRT_USERNAME`、`SRT_PASSWORD`、`KORAIL_USERNAME`、`KORAIL_PASSWORD`、`SEOUL_METRO_API_KEY`。
7. 用 sops+age 加密保存 secrets：`age-keygen -o ~/.config/sops/age/keys.txt`；`sops --age $(grep 'public key' ~/.config/sops/age/keys.txt | awk '{print $4}') --encrypt secrets.yaml > secrets.enc.yaml`；`sops --decrypt secrets.enc.yaml | k-skill env inject`。
8. SRT：`const { SRTClient } = require('k-skill/srt');`，用 `new SRTClient({ username: process.env.SRT_USERNAME, password: process.env.SRT_PASSWORD })` 创建客户端。
9. SRT：调用 `await client.login()` 登录。
10. SRT：用 `await client.searchTrains({ departure: '수서', arrival: '부산', date: '20260401', time: '080000', passengers: 1 })` 查询列车，日期 YYYYMMDD，时间 HHmmss。
11. SRT：用 `await client.reserve({ trainNo: trains[0].trainNo, passengers: 1, seatType: 'normal' })` 预约，`seatType` 可用 `normal`、`window`、`aisle`。
12. SRT：用 `await client.getReservations()` 查看预约，用 `await client.cancelReservation(reservation.reservationId)` 取消预约。
13. SRT CLI：`k-skill srt search --from 수서 --to 부산 --date 20260401 --time 080000`；`k-skill srt reserve --train SRT123 --passengers 1`；`k-skill srt list`；`k-skill srt cancel --id RES456`。
14. KTX：当前 `KTXClient` 不工作，仅标记为开发中，不能用于查询/预约/确认/取消。
15. 카카오톡 Mac CLI：macOS 下使用 `kakaocli`，无需认证；`const { KakaoTalkMac } = require('k-skill/kakaotalk-mac'); const kakao = new KakaoTalkMac();`。
16. 카카오톡：用 `await kakao.listConversations()` 获取对话列表，用 `await kakao.searchConversations('개발팀')` 搜索对话。
17. 카카오톡：发送前用 `await kakao.previewSend({ to: '홍길동', message: '안녕하세요!' })` 预览；只有用户明确确认后才用 `await kakao.send({ to: '홍길동', message: '안녕하세요!', confirmed: true })` 真正发送。
18. 카카오톡 CLI：`kakaocli list`；`kakaocli send --to '홍길동' --message '테스트 메시지'`；`kakaocli read --name '홍길동' --count 20`；也可用 `k-skill kakao list`、`k-skill kakao send --to '홍길동' --message '메시지'`。
19. 首尔地铁：需要 공공데이터포털 API key；`const { SeoulSubway } = require('k-skill/seoul-subway'); const subway = new SeoulSubway({ apiKey: process.env.SEOUL_METRO_API_KEY });`。
20. 首尔地铁：用 `await subway.getArrivals('강남')` 按站名查实时到达；用 `await subway.getArrivals('강남', { line: '2호선' })` 过滤线路；用 `await subway.getArrivalsByCode('0222')` 按站码查询。
21. 首尔地铁 CLI：`k-skill subway arrivals --station 강남`；`k-skill subway arrivals --station 강남 --line 2호선`。
22. KBO：无需认证；`const { KBOClient } = require('k-skill/kbo'); const kbo = new KBOClient();`。
23. KBO：用 `await kbo.getGames()` 查今日赛程/结果；用 `await kbo.getGames({ date: '20260401' })` 查指定日期；用 `await kbo.getGames({ date: '20260401', team: 'LG' })` 按队伍过滤；用 `kbo.getTeamList()` 获取队伍列表。
24. KBO CLI：`k-skill kbo today`；`k-skill kbo games --date 20260401`；`k-skill kbo games --team LG`。
25. 로또：无需认证；`const { LottoClient } = require('k-skill/lotto'); const lotto = new LottoClient();`。
26. 로또：用 `await lotto.getLatestResult()` 查最新开奖；用 `await lotto.getResult(1100)` 查指定回次；用 `await lotto.checkNumbers([3,14,22,31,40,43])` 对照号码。
27. 로또 CLI：`k-skill lotto latest`；`k-skill lotto result --round 1100`；`k-skill lotto check --numbers 3,14,22,31,40,43`。
28. HWP：无需认证；`const { HWPProcessor } = require('k-skill/hwp'); const hwp = new HWPProcessor();`。
29. HWP：用 `await hwp.toMarkdown('./document.hwp')` 转 Markdown；用 `await hwp.toJSON('./document.hwp')` 转 JSON；用 `await hwp.toHTML('./document.hwp')` 转 HTML。
30. HWP：用 `await hwp.extractImages('./document.hwp', { outputDir: './extracted-images' })` 提取图片；用 `await hwp.batchConvert('./hwp-files/', { format: 'markdown', outputDir: './converted/' })` 批量转换。
31. HWP：Windows 且安装한글과컴퓨터应用时，用 `new HWPProcessor({ useWindowsApp: true })` 后调用 `toMarkdown('./document.hwp')` 直接控制原生应用。
32. HWP CLI：`k-skill hwp convert document.hwp --format markdown`；`k-skill hwp batch ./hwp-folder/ --format json --output ./output/`；`k-skill hwp extract-images document.hwp --output ./images/`。
33. 邮编：无需认证；`const { ZipcodeClient } = require('k-skill/zipcode'); const zipcode = new ZipcodeClient();`。
34. 邮编：用 `await zipcode.search('강남구 테헤란로')` 按地址关键词搜索；用 `await zipcode.search('롯데월드타워')` 按建筑名搜索；用 `await zipcode.getByZipcode('05510')` 按邮编反查。
35. 邮编 CLI：`k-skill zipcode search '강남구 테헤란로'`；`k-skill zipcode lookup 06236`。
36. 错误处理：`const { SRTClient, SRTError, SRTAuthError } = require('k-skill/srt');`，用 try/catch，遇到 `SRTAuthError` 提示检查账号密码，遇到 `SRTError` 打印 `err.message` 和 `err.code`，其他错误重新抛出。
37. 环境变量加载：可用 `require('dotenv').config()`；或用 `sops --decrypt secrets.enc.yaml | k-skill env inject` 注入后，通过 `process.env.SRT_USERNAME`、`process.env.SRT_PASSWORD` 读取。
38. CLI 设置：`k-skill install`、`k-skill install srt kbo lotto`、`k-skill-setup`、`k-skill env inject`。
39. 排障 SRT_USERNAME 缺失：运行 `echo $SRT_USERNAME` 检查；把 `SRT_USERNAME=your_id` 和 `SRT_PASSWORD=your_password` 追加到 `.env`；建议用 `k-skill-setup` 重新注册 secrets。
40. 排障 HWP 转换失败：运行 `npm install -g hwp.js`；使用 Python 后端时运行 `pip install python-hwp`；Windows 直接控制한컴应用时用 `k-skill hwp convert doc.hwp --use-native`。
41. 排障 카카오톡 CLI 不可用：运行 `which kakaocli` 检查；没有则用 `brew install kakaocli` 或 `npm install -g kakaocli` 安装。
42. 排障首尔地铁 API key 错误：到 `https://data.seoul.go.kr` 的“서울시 지하철 실시간 도착정보”申请 key，然后 `export SEOUL_METRO_API_KEY='발급받은_키'`。
43. 排障 Node.js 版本：运行 `node --version`，需 v18 以上；可用 `nvm install 20` 和 `nvm use 20` 切换。
44. 当前可用功能：SRT 预约、카카오톡 Mac CLI、首尔地铁到达信息、KBO 赛果、로또 中奖确认、HWP 文档处理、邮编搜索；KTX 预约未可用。
45. 未来候选功能（쿠팡、다나와、네이버 스토어、당근마켓、정부24、홈택스）尚未包含，不要按已支持功能调用。

适用边界 · 注意事项

• KTX/Korail 预约当前不可用，KTXClient 仍在开发中。
• 非 macOS 环境无法使用基于 kakaocli 的 카카오톡 Mac CLI。
• 未安装 k-skill/npm 依赖、没有韩国服务账号或首尔地铁 API key，或不安全保存 secrets 时，不要使用对应功能。