mirrors/k-skill
2
0
Fork 0
mirror of https://github.com/NomaDamas/k-skill.git synced 2026-06-24 02:04:11 +00:00
Code Issues Projects Releases Packages Wiki Activity
k-skill/docs/features/kakaotalk-mac.md
Jeffrey (Dongkyu) Kim c9116b555f
 Feature/#121 (#127) 
* Recover KakaoTalk mac skill auth when upstream user_id detection fails

Issue #121 reproduces on a real MacBook because `kakaocli auth` can fail even when the encrypted hex-named DB exists. This change adds a thin repo-owned helper that recovers the active user_id from plist revision hashes, caches the validated DB/key tuple, and reuses it for read-only `kakaocli` commands. The skill and feature docs now steer users to the helper when upstream auto-detection stops at candidate key mismatch, and regression tests lock the recovery flow before the implementation.

Constraint: Must stay a thin adapter around upstream kakaocli rather than forking the CLI
Constraint: Must verify on a real local macOS KakaoTalk install where issue #121 reproduces
Rejected: Full kakaocli reimplementation inside k-skill | too broad for the user_id/key-derivation failure scope
Rejected: Docs-only workaround | does not actually fix the broken auth path for users
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep this helper limited to auth/key recovery and read-only passthrough unless upstream gaps widen materially
Tested: python3 -m unittest scripts.test_kakaotalk_mac
Tested: node --test scripts/skill-docs.test.js
Tested: npm run ci
Tested: python3 scripts/kakaotalk_mac.py auth --refresh --max-user-id 800000000 --workers 8 --chunk-size 2000000
Tested: python3 scripts/kakaotalk_mac.py chats --limit 1 --json
Not-tested: Other kakaocli subcommands beyond auth/chats/messages/search/query/schema

* Protect the KakaoTalk helper's safe recovery path

Address the PR follow-up by treating malformed auth cache files as cache misses,
removing write-capable passthrough from the wrapper surface, and redacting
human-readable auth output so the cached SQLCipher key is not echoed back into
terminal history. The docs and regression suite now describe and enforce the
read-only contract that the helper is meant to preserve.

Constraint: Helper must remain a read-only recovery wrapper around local kakaocli access
Rejected: Keep query support with SQL validation | still leaves a risky write-capable escape hatch
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Do not re-expose arbitrary SQL passthrough or print the SQLCipher key in default text output
Tested: python3 -m unittest scripts.test_kakaotalk_mac; node --test scripts/skill-docs.test.js; npm run ci; python3 scripts/kakaotalk_mac.py auth --refresh --max-user-id 800000000 --workers 8 --chunk-size 2000000; python3 scripts/kakaotalk_mac.py chats --limit 1 --json; python3 scripts/kakaotalk_mac.py auth --cache-path <bad-json>; python3 scripts/kakaotalk_mac.py query --help
Not-tested: External automation consumers that depend on shell/json auth output beyond the documented helper flows

* Lock the helper CLI surface against accidental regressions

The approved issue #121 fixes already hardened the KakaoTalk Mac helper, but the test suite still only exercised the passthrough validator directly. Add an explicit parser-level regression so the public CLI contract stays read-only and `query` cannot quietly reappear in future edits.

Constraint: Follow-up is on the existing feature/#121 PR branch and must stay minimal
Rejected: Re-open helper implementation changes | current code already satisfies the approved review findings
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep parser exposure tests aligned with READ_ONLY_COMMANDS whenever helper subcommands change
Tested: python3 -m unittest scripts.test_kakaotalk_mac; node --test scripts/skill-docs.test.js; npm run ci; python3 scripts/kakaotalk_mac.py auth --refresh --max-user-id 800000000 --workers 8 --chunk-size 2000000; python3 scripts/kakaotalk_mac.py chats --limit 1 --json; python3 scripts/kakaotalk_mac.py auth --cache-path <bad-json>
Not-tested: No new production code paths changed in this follow-up

* Honor explicit Kakao auth recovery overrides

The helper now treats manual auth overrides as a cache-bypassing recovery request and rejects invalid brute-force tuning flags at the CLI boundary so users get deterministic behavior instead of stale cached tuples or Python tracebacks. Regression coverage locks both paths before the PR follow-up lands.

Constraint: The helper must remain a thin read-only wrapper around kakaocli auth recovery
Rejected: Require --refresh whenever --user-id/--uuid is passed | worse UX than honoring overrides directly
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep explicit auth overrides ahead of cache reuse unless the CLI contract is redesigned and documented
Tested: python3 -m unittest scripts.test_kakaotalk_mac; node --test scripts/skill-docs.test.js; npm run ci; python3 scripts/kakaotalk_mac.py auth --refresh --max-user-id 800000000 --workers 8 --chunk-size 2000000; python3 scripts/kakaotalk_mac.py chats --limit 1 --json; python3 scripts/kakaotalk_mac.py auth --cache-path <bad-json>; python3 scripts/kakaotalk_mac.py auth --refresh --max-user-id -1; python3 scripts/kakaotalk_mac.py auth --refresh --workers 2 --chunk-size 0 --max-user-id 10; python3 scripts/kakaotalk_mac.py auth --cache-path <temp-cache> --user-id 999; python3 scripts/kakaotalk_mac.py auth --cache-path <temp-cache> --uuid <live-uuid>
Not-tested: Manual override success with a truly alternate valid user_id/uuid pair on a multi-account local install
2026-04-18 01:08:06 +09:00

3.5 KiB
Raw Permalink Blame History

카카오톡 Mac CLI 가이드

이 기능으로 할 수 있는 일

  • macOS에서 카카오톡 최근 대화 목록 확인
  • 특정 채팅방 최근 메시지 읽기
  • 키워드로 전체 대화 검색
  • 나와의 채팅으로 안전하게 테스트 전송
  • 사용자 확인 후 특정 채팅방으로 메시지 전송

먼저 필요한 것

  • macOS
  • KakaoTalk for Mac 설치
  • Homebrew
  • brew install silver-flight-group/tap/kakaocli
  • python3 3.10+
  • 이 저장소의 helper scripts/kakaotalk_mac.py
  • 터미널 앱에 Full Disk Access 와 Accessibility 권한 부여

카카오톡 앱이 없으면 mas 로 먼저 설치할 수 있다.

brew install mas
mas account
mas install 869223134

입력값

  • 채팅방 이름
  • 검색 키워드
  • 최근 범위(--since 1h, --since 7d 등)
  • 전송 메시지 본문
  • 테스트 여부(--me, --dry-run)

기본 흐름

  1. KakaoTalk for Mac 과 kakaocli 가 설치되어 있는지 확인한다.
  2. kakaocli status, kakaocli auth 로 권한과 DB 접근이 되는지 먼저 확인한다.
  3. user_id 자동 감지가 실패하면 helper python3 scripts/kakaotalk_mac.py auth --refresh 로 복구한다.
  4. 읽기/검색은 JSON 모드로 실행한 뒤 사람이 읽기 쉽게 요약한다.
  5. 전송은 먼저 --me 또는 --dry-run 으로 테스트한다.
  6. 다른 사람에게 보내는 메시지는 항상 최종 확인 후에만 전송한다.

예시

kakaocli status
kakaocli auth
python3 scripts/kakaotalk_mac.py auth --refresh
python3 scripts/kakaotalk_mac.py chats --limit 10 --json
python3 scripts/kakaotalk_mac.py messages --chat "지수" --since 1d --json
python3 scripts/kakaotalk_mac.py search "회의" --json
kakaocli chats --limit 10 --json
kakaocli messages --chat "지수" --since 1d --json
kakaocli search "회의" --json
kakaocli send --me _ "테스트 메시지"
kakaocli send --dry-run "팀 공지방" "오늘 3시에 만나요"

helper 가 해결하는 문제

kakaocli auth 실패가 항상 “DB 파일이 없음”을 의미하지는 않는다. 실제 Mac 환경에서는:

  • container 안에 KakaoTalk.db 라는 이름 대신 78자 hex 파일이 DB 로 존재할 수 있다.
  • kakaocli status 는 정상이어도 auth 는 user_id 자동 감지 실패 로 끝날 수 있다.
  • 이 경우 plist 의 AlertKakaoIDsList 후보만으로는 부족하고, DESIGNATEDFRIENDSREVISION:<SHA-512(user_id)> 에서 실제 user_id 를 더 오래 찾아야 할 수 있다.

helper scripts/kakaotalk_mac.py 는 그 얇은 read-only 어댑터 역할을 한다.

  • plist 에서 후보 user_id 와 active hash 를 읽는다.
  • hash recovery 가 필요하면 더 긴 검색으로 실제 user_id 를 찾는다.
  • 검증된 DB 경로와 SQLCipher key 를 ~/.cache/k-skill/kakaotalk-mac-auth.json 에 캐시한다.
  • 이후 read-only helper 명령 chats, messages, search, schema 를 cached --db / --key 와 함께 다시 실행한다.

주의할 점

  • Full Disk Access 가 없으면 읽기 명령도 실패할 수 있다.
  • Accessibility 가 없으면 전송과 harvest 계열 자동화가 실패한다.
  • macOS 전용이므로 Windows/Linux 대체 구현으로 넘어가지 않는다.
  • 다른 사람에게 보내는 메시지는 자동 전송하지 말고 확인을 먼저 받는다.
  • helper cache 는 로컬 auth material 을 담으므로 본인 장비에서만 보관한다.
  • 기본 auth 텍스트 출력은 key 를 다시 보여주지 않는다. 자동화가 필요할 때만 --format json 또는 --format shell 을 사용한다.