mirror of
https://github.com/NomaDamas/k-skill.git
synced 2026-06-24 02:04:11 +00:00
Document safe macOS KakaoTalk skill usage
Add the new kakaotalk-mac skill as a docs-first capability with regression coverage, repository discoverability, and clear macOS permission/install guidance built around kakaocli. The change keeps the repo docs-only while making the feature installable and reviewable through existing skill validation paths. Constraint: This repo ships skill definitions and docs, not KakaoTalk automation binaries Constraint: Guidance must stay macOS-specific and require explicit confirmation before sending to other people Rejected: Add executable integration code in this repo | issue scope is docs-only skill packaging Rejected: Document unofficial non-macOS workarounds | upstream tool is macOS-only and issue explicitly targets Mac Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep future updates aligned with upstream kakaocli commands and macOS permission requirements before broadening this skill Tested: node --test scripts/skill-docs.test.js Tested: npm run ci Tested: npx --yes skills add . --list Tested: Architect review approval on working tree Not-tested: Live kakaocli execution against a local KakaoTalk installation on macOS
This commit is contained in:
Jeffrey (Dongkyu) Kim
parent
ed92a858fa
commit
fbc44b795b
6 changed files with 275 additions and 1 deletions
|
|
@ -18,6 +18,7 @@ Claude code, codex, opencode 등 각종 코딩 에이전트 지원합니다.
|
|||
| --- | --- | --- | --- |
|
||||
| SRT 예매 | 열차 조회, 예약, 예약 확인, 취소 | 필요 | [SRT 예매 가이드](docs/features/srt-booking.md) |
|
||||
| KTX 예매 | 현재 작동하지 않음. KTX/Korail 열차 조회, 예약, 예약 확인, 취소 지원을 목표로 함 | 필요 | [KTX 예매 가이드](docs/features/ktx-booking.md) |
|
||||
| 카카오톡 Mac CLI | macOS에서 kakaocli로 대화 조회, 검색, 테스트 전송, 확인 후 실제 전송 | 불필요 | [카카오톡 Mac CLI 가이드](docs/features/kakaotalk-mac.md) |
|
||||
| 서울 지하철 도착정보 조회 | 역 기준 실시간 도착 예정 열차 확인 | 필요 | [서울 지하철 도착정보 가이드](docs/features/seoul-subway-arrival.md) |
|
||||
| KBO 경기 결과 조회 | 날짜별 경기 일정, 결과, 팀별 필터링 | 불필요 | [KBO 결과 가이드](docs/features/kbo-results.md) |
|
||||
| 로또 당첨 확인 | 최신 회차, 특정 회차, 번호 대조 | 불필요 | [로또 결과 가이드](docs/features/lotto-results.md) |
|
||||
|
|
@ -48,6 +49,7 @@ Claude code, codex, opencode 등 각종 코딩 에이전트 지원합니다.
|
|||
|
||||
- [SRT 예매](docs/features/srt-booking.md)
|
||||
- [KTX 예매](docs/features/ktx-booking.md)
|
||||
- [카카오톡 Mac CLI](docs/features/kakaotalk-mac.md)
|
||||
- [서울 지하철 도착정보 조회](docs/features/seoul-subway-arrival.md)
|
||||
- [KBO 경기 결과 조회](docs/features/kbo-results.md)
|
||||
- [로또 당첨 확인](docs/features/lotto-results.md)
|
||||
|
|
|
|||
60
docs/features/kakaotalk-mac.md
Normal file
60
docs/features/kakaotalk-mac.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
# 카카오톡 Mac CLI 가이드
|
||||
|
||||
## 이 기능으로 할 수 있는 일
|
||||
|
||||
- macOS에서 카카오톡 최근 대화 목록 확인
|
||||
- 특정 채팅방 최근 메시지 읽기
|
||||
- 키워드로 전체 대화 검색
|
||||
- 나와의 채팅으로 안전하게 테스트 전송
|
||||
- 사용자 확인 후 특정 채팅방으로 메시지 전송
|
||||
|
||||
## 먼저 필요한 것
|
||||
|
||||
- macOS
|
||||
- KakaoTalk for Mac 설치
|
||||
- Homebrew
|
||||
- `brew install silver-flight-group/tap/kakaocli`
|
||||
- 터미널 앱에 **Full Disk Access** 와 **Accessibility** 권한 부여
|
||||
|
||||
카카오톡 앱이 없으면 `mas` 로 먼저 설치할 수 있다.
|
||||
|
||||
```bash
|
||||
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. 읽기/검색은 JSON 모드로 실행한 뒤 사람이 읽기 쉽게 요약한다.
|
||||
4. 전송은 먼저 `--me` 또는 `--dry-run` 으로 테스트한다.
|
||||
5. 다른 사람에게 보내는 메시지는 항상 최종 확인 후에만 전송한다.
|
||||
|
||||
## 예시
|
||||
|
||||
```bash
|
||||
kakaocli status
|
||||
kakaocli auth
|
||||
kakaocli chats --limit 10 --json
|
||||
kakaocli messages --chat "지수" --since 1d --json
|
||||
kakaocli search "회의" --json
|
||||
kakaocli send --me _ "테스트 메시지"
|
||||
kakaocli send --dry-run "팀 공지방" "오늘 3시에 만나요"
|
||||
```
|
||||
|
||||
## 주의할 점
|
||||
|
||||
- **Full Disk Access** 가 없으면 읽기 명령도 실패할 수 있다.
|
||||
- **Accessibility** 가 없으면 전송과 harvest 계열 자동화가 실패한다.
|
||||
- macOS 전용이므로 Windows/Linux 대체 구현으로 넘어가지 않는다.
|
||||
- 다른 사람에게 보내는 메시지는 자동 전송하지 말고 확인을 먼저 받는다.
|
||||
|
|
@ -46,7 +46,8 @@ k-skill-setup 스킬을 사용해서 공통 설정을 진행해줘.
|
|||
npx --yes skills add <owner/repo> \
|
||||
--skill hwp \
|
||||
--skill kbo-results \
|
||||
--skill lotto-results
|
||||
--skill lotto-results \
|
||||
--skill kakaotalk-mac
|
||||
```
|
||||
|
||||
인증이 필요한 기능만 부분 설치할 때도 `k-skill-setup` 은 같이 넣는다.
|
||||
|
|
@ -97,6 +98,14 @@ npm install -g @ohah/hwpjs kbo-game k-lotto
|
|||
export NODE_PATH="$(npm root -g)"
|
||||
```
|
||||
|
||||
### macOS 바이너리
|
||||
|
||||
카카오톡 Mac CLI는 npm 패키지가 아니라 Homebrew tap 설치를 사용한다.
|
||||
|
||||
```bash
|
||||
brew install silver-flight-group/tap/kakaocli
|
||||
```
|
||||
|
||||
### Python 패키지
|
||||
|
||||
```bash
|
||||
|
|
|
|||
|
|
@ -8,6 +8,8 @@
|
|||
- `kbo-game`: https://github.com/vkehfdl1/kbo-game
|
||||
- `@ohah/hwpjs`: https://github.com/ohah/hwpjs
|
||||
- `hwp-mcp`: https://github.com/jkf87/hwp-mcp
|
||||
- `silver-flight-group/kakaocli`: https://github.com/silver-flight-group/kakaocli
|
||||
- KakaoTalk Mac 설치 참고(`mas`): https://velog.io/@bonjugi/%EB%A7%A5%EB%B6%81-M1%EC%97%90-homebrew%EB%A1%9C-node-vscode-%EC%B9%B4%EC%B9%B4%EC%98%A4%ED%86%A1-%EC%84%A4%EC%B9%98%ED%95%98%EA%B8%B0
|
||||
- 동행복권 로또 결과 페이지: https://www.dhlottery.co.kr/lt645/result
|
||||
- 동행복권 지난 회차 JSON 표면: https://www.dhlottery.co.kr/lt645/selectPstLt645InfoNew.do
|
||||
- 서울특별시 지하철 실시간 도착정보: https://www.data.go.kr/data/15058052/openapi.do
|
||||
|
|
|
|||
167
kakaotalk-mac/SKILL.md
Normal file
167
kakaotalk-mac/SKILL.md
Normal file
|
|
@ -0,0 +1,167 @@
|
|||
---
|
||||
name: kakaotalk-mac
|
||||
description: Use kakaocli on macOS to read KakaoTalk chats, search messages, and send replies after explicit confirmation.
|
||||
license: MIT
|
||||
metadata:
|
||||
category: messaging
|
||||
locale: ko-KR
|
||||
phase: v1.5
|
||||
---
|
||||
|
||||
# KakaoTalk Mac CLI
|
||||
|
||||
## What this skill does
|
||||
|
||||
`kakaocli` 를 사용해 macOS에서 카카오톡 대화 목록을 확인하고, 메시지를 검색하고, 필요할 때 답장을 보낸다.
|
||||
|
||||
이 스킬은 **macOS + 카카오톡 Mac 앱 설치**를 전제로 한다. 공식 Kakao API를 쓰는 것이 아니라 로컬 데이터베이스 읽기와 macOS 접근성 자동화 위에서 동작하므로, 권한과 안전 규칙을 먼저 확인해야 한다.
|
||||
|
||||
## When to use
|
||||
|
||||
- "카카오톡 최근 대화 목록 보여줘"
|
||||
- "특정 채팅방 최근 메시지 찾아줘"
|
||||
- "카카오톡 메시지 검색해줘"
|
||||
- "내 카톡으로 테스트 메시지 보내줘"
|
||||
- "답장 초안은 만들되 실제 전송 전에는 꼭 확인받아"
|
||||
|
||||
## When not to use
|
||||
|
||||
- macOS가 아닌 환경
|
||||
- 카카오톡 Mac 앱이 설치되어 있지 않은 환경
|
||||
- 사용자 확인 없이 다른 사람에게 메시지를 바로 보내야 하는 작업
|
||||
- 카카오 공식 API 범위 안에서 해결 가능한 서버-투-서버 연동 작업
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- macOS
|
||||
- KakaoTalk for Mac 설치
|
||||
- Homebrew
|
||||
- Mac App Store 로그인(`mas` 사용 시)
|
||||
- `kakaocli` 설치
|
||||
- 터미널 앱에 **Full Disk Access** 와 **Accessibility** 권한 부여
|
||||
|
||||
## Inputs
|
||||
|
||||
- 채팅방 이름 또는 검색 키워드
|
||||
- 읽기 범위: 최근 N개, `--since 1h`, `--since 7d` 등
|
||||
- 전송할 메시지 본문
|
||||
- 테스트 여부 (`--me`, `--dry-run`)
|
||||
|
||||
## Workflow
|
||||
|
||||
### 0. Install KakaoTalk for Mac first when missing
|
||||
|
||||
카카오톡 Mac 앱이 없으면 먼저 설치한다. `mas` 를 쓰려면 App Store 로그인 상태여야 한다.
|
||||
|
||||
```bash
|
||||
brew install mas
|
||||
mas account
|
||||
mas install 869223134
|
||||
```
|
||||
|
||||
`mas install` 이 막히면 App Store 앱에서 먼저 로그인한 뒤 다시 시도한다.
|
||||
|
||||
### 1. Install `kakaocli`
|
||||
|
||||
공식 저장소 기준 권장 설치는 Homebrew tap 이다.
|
||||
|
||||
```bash
|
||||
brew install silver-flight-group/tap/kakaocli
|
||||
```
|
||||
|
||||
설치 후 바로 상태를 확인한다.
|
||||
|
||||
```bash
|
||||
kakaocli status
|
||||
```
|
||||
|
||||
### 2. Grant the required macOS permissions
|
||||
|
||||
**System Settings > Privacy & Security** 에서 현재 사용하는 터미널 앱(iTerm, Terminal, Warp 등)에 아래 권한을 준다.
|
||||
|
||||
- **Full Disk Access**: 카카오톡 로컬 데이터베이스 읽기용
|
||||
- **Accessibility**: 메시지 전송, harvest, inspect 같은 UI 자동화용
|
||||
|
||||
기본 규칙:
|
||||
|
||||
- `status` / `auth` / `chats` 같은 읽기 명령도 Full Disk Access 가 필요하다.
|
||||
- `send`, `harvest`, `inspect` 류 작업은 Accessibility 권한까지 필요하다.
|
||||
|
||||
### 3. Verify read access before attempting side effects
|
||||
|
||||
먼저 읽기 경로가 되는지 확인한다.
|
||||
|
||||
```bash
|
||||
kakaocli status
|
||||
kakaocli auth
|
||||
kakaocli chats --limit 10 --json
|
||||
```
|
||||
|
||||
`auth` 가 성공하면 읽기 경로는 준비된 것이다.
|
||||
|
||||
### 4. Read or search messages
|
||||
|
||||
```bash
|
||||
kakaocli messages --chat "지수" --since 1h --json
|
||||
kakaocli search "점심" --json
|
||||
```
|
||||
|
||||
응답은 가능하면 JSON 모드로 받고, 사람이 읽기 쉽게 다시 요약한다.
|
||||
|
||||
### 5. Use safe testing before real sends
|
||||
|
||||
실제 전송 전에 먼저 자기 자신에게 테스트하거나 dry-run 으로 확인한다.
|
||||
|
||||
```bash
|
||||
kakaocli send --me _ "테스트 메시지"
|
||||
kakaocli send --dry-run "채팅방 이름" "보낼 문장"
|
||||
```
|
||||
|
||||
`--me` 는 나와의 채팅으로 보내므로 가장 안전한 테스트 경로다.
|
||||
|
||||
### 6. Confirm before sending to other people
|
||||
|
||||
다른 사람이나 단체방으로 보내기 전에는 반드시 사용자의 최종 확인을 받는다.
|
||||
|
||||
확인 전에는 아래만 준비한다.
|
||||
|
||||
- 대상 채팅방 이름
|
||||
- 전송할 문장
|
||||
- 왜 이 문장을 보내는지 한 줄 설명
|
||||
|
||||
확인을 받았을 때만 전송한다.
|
||||
|
||||
```bash
|
||||
kakaocli send "채팅방 이름" "보낼 문장"
|
||||
```
|
||||
|
||||
### 7. Use login storage only when the user explicitly wants auto-login
|
||||
|
||||
자동 로그인 편의를 원할 때만 자격증명을 저장한다.
|
||||
|
||||
```bash
|
||||
kakaocli login
|
||||
kakaocli login --status
|
||||
```
|
||||
|
||||
비밀번호를 채팅창에 보내라고 요구하지 않는다. 사용자가 직접 로컬 터미널에서 입력하게 한다.
|
||||
|
||||
## Done when
|
||||
|
||||
- 읽기 요청이면 상태 확인 + 대화/메시지 조회 결과가 정리되어 있다
|
||||
- 검색 요청이면 키워드 기준 결과가 정리되어 있다
|
||||
- 전송 요청이면 테스트(`--me` 또는 `--dry-run`)와 사용자 확인이 끝난 뒤 실제 전송 여부가 명확하다
|
||||
|
||||
## Failure modes
|
||||
|
||||
- KakaoTalk for Mac 미설치
|
||||
- App Store 로그인 누락으로 `mas install` 실패
|
||||
- Full Disk Access 미부여
|
||||
- Accessibility 미부여
|
||||
- 채팅방 이름 substring 이 애매해서 잘못된 후보가 여러 개 잡힘
|
||||
|
||||
## Notes
|
||||
|
||||
- 이 스킬은 macOS 전용이다.
|
||||
- 다른 사람에게 보내는 메시지는 항상 confirm before sending 원칙을 지킨다.
|
||||
- 첫 검증은 `kakaocli status` 와 `kakaocli auth` 부터 시작하는 편이 안전하다.
|
||||
|
|
@ -9,6 +9,12 @@ function read(relativePath) {
|
|||
return fs.readFileSync(path.join(repoRoot, relativePath), "utf8");
|
||||
}
|
||||
|
||||
test("root npm test script includes the skill docs regression suite", () => {
|
||||
const packageJson = JSON.parse(read("package.json"));
|
||||
|
||||
assert.match(packageJson.scripts.test, /node --test scripts\/skill-docs\.test\.js/);
|
||||
});
|
||||
|
||||
test("hwp skill documents environment-aware routing and supported operations", () => {
|
||||
const skillPath = path.join(repoRoot, "hwp", "SKILL.md");
|
||||
|
||||
|
|
@ -53,3 +59,31 @@ test("repository docs advertise the hwp skill", () => {
|
|||
assert.match(featureDoc, /Markdown 출력.*(data:|base64)/);
|
||||
assert.doesNotMatch(featureDoc, /Markdown 출력.*이미지 (파일 )?경로 생성 여부 확인/);
|
||||
});
|
||||
|
||||
test("repository docs advertise the kakaotalk-mac skill", () => {
|
||||
const readme = read("README.md");
|
||||
const install = read(path.join("docs", "install.md"));
|
||||
const featureDocPath = path.join(repoRoot, "docs", "features", "kakaotalk-mac.md");
|
||||
|
||||
assert.ok(fs.existsSync(featureDocPath), "expected docs/features/kakaotalk-mac.md to exist");
|
||||
assert.match(readme, /\| 카카오톡 Mac CLI \|/);
|
||||
assert.match(readme, /\[카카오톡 Mac CLI\]\(docs\/features\/kakaotalk-mac\.md\)/);
|
||||
assert.match(install, /--skill kakaotalk-mac/);
|
||||
});
|
||||
|
||||
test("kakaotalk-mac skill documents safe macOS kakaocli usage", () => {
|
||||
const skillPath = path.join(repoRoot, "kakaotalk-mac", "SKILL.md");
|
||||
|
||||
assert.ok(fs.existsSync(skillPath), "expected kakaotalk-mac/SKILL.md to exist");
|
||||
|
||||
const skill = read(path.join("kakaotalk-mac", "SKILL.md"));
|
||||
|
||||
assert.match(skill, /^name: kakaotalk-mac$/m);
|
||||
assert.match(skill, /kakaocli/);
|
||||
assert.match(skill, /macOS/i);
|
||||
assert.match(skill, /KakaoTalk/i);
|
||||
assert.match(skill, /Full Disk Access/i);
|
||||
assert.match(skill, /Accessibility/i);
|
||||
assert.match(skill, /--me/);
|
||||
assert.match(skill, /confirm before sending/i);
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue