@nomadamas/k-skill 0.10.2 → 0.10.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -2,132 +2,102 @@
|
|
|
2
2
|
|
|
3
3
|
## What this skill does
|
|
4
4
|
|
|
5
|
-
헤이유미 공식 CLI(`heyyumi`, npm, https://github.com/hmp-dev/heyyumi-cli)로 한국 식당·카페·바를 찾고,
|
|
5
|
+
헤이유미 공식 CLI(`heyyumi`, npm, https://github.com/hmp-dev/heyyumi-cli)로 한국 식당·카페·바를 찾고, 예약 요청을 보낸 뒤 매장의 수락/거절/만료까지 확인한다. 같은 CLI로 "지금 자리 있어요? 웨이팅 몇 분이에요?" 같은 실시간 문의도 매장에 보낸다.
|
|
6
6
|
|
|
7
|
-
- 구글 로그인 한 번이면 쓴다.
|
|
7
|
+
- 구글 로그인 한 번이면 쓴다. 키를 직접 발급하거나 붙여 넣을 필요 없다.
|
|
8
8
|
- 공식 CLI만 쓴다. 크롤링·화면 스크래핑은 하지 않고, k-skill-proxy도 쓰지 않는다. 호출은 사용자 머신에서 헤이유미 서버로 직접 간다.
|
|
9
|
-
-
|
|
9
|
+
- 예약에 선결제는 없다.
|
|
10
10
|
|
|
11
11
|
## When to use
|
|
12
12
|
|
|
13
13
|
- "을지로 힙한 카페 찾아서 예약해줘", "홍제동 저녁 2명 파스타집 예약 가능한 곳"
|
|
14
14
|
- "이 식당 예약돼? 지금 10명 앉을 수 있어? 웨이팅 몇 분이야?"
|
|
15
|
-
-
|
|
15
|
+
- "판교에서 주차되고 아이랑 가기 좋은 한식집", "제주시 몸국 파는 집" 같은 조건·메뉴로 식당 찾기
|
|
16
|
+
- "Find a bibimbap place near Myeongdong"처럼 외국어로 묻는 경우
|
|
16
17
|
|
|
17
|
-
쓰지 않는 경우: 매출 기반 순위가 목적이면 `bccard-eatpl-search`, 길찾기·지도는 `kakao-map`, KTX·버스 예약은 해당 스킬.
|
|
18
|
+
쓰지 않는 경우: 매출 기반 순위가 목적이면 `bccard-eatpl-search`, 길찾기·지도는 `kakao-map`, KTX·버스 예약은 해당 스킬.
|
|
18
19
|
|
|
19
20
|
## Run
|
|
20
21
|
|
|
21
22
|
```bash
|
|
22
|
-
npx -y heyyumi
|
|
23
|
+
npx -y heyyumi <command> [flags]
|
|
23
24
|
```
|
|
24
25
|
|
|
25
|
-
|
|
26
|
+
`@0`처럼 버전 범위를 붙이지 않는다. 범위를 붙이면 npx가 처음 받은 사본을 계속 써서 새 버전이 안 들어온다.
|
|
26
27
|
|
|
27
|
-
|
|
28
|
+
출력은 stdout의 JSON이고 진행 로그는 stderr로 간다. 종료 코드는 `0` 정상, `1` 서버/도구 오류, `2` 사용법 오류, `3` 로그인 필요다. 오류 JSON은 `error.code`, `error.message`, `error.next`를 가진다.
|
|
29
|
+
|
|
30
|
+
### 1. 헤이유미 규칙 읽기 (작업마다 처음 한 번)
|
|
28
31
|
|
|
29
32
|
```bash
|
|
30
|
-
npx -y heyyumi
|
|
31
|
-
npx -y heyyumi
|
|
32
|
-
npx -y heyyumi
|
|
33
|
+
npx -y heyyumi guide # 헤이유미 서버가 주는 최신 사용 규칙
|
|
34
|
+
npx -y heyyumi guide reserve # 예약 요청을 보내기 전에
|
|
35
|
+
npx -y heyyumi guide live # 실시간 문의를 보내기 전에
|
|
33
36
|
```
|
|
34
37
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
이미 대시보드 키(`hmp_...`)가 있으면 `HEYYUMI_API_KEY`로 넘겨도 된다(로그인 생략). 키·토큰은 채팅에 출력하지 않는다.
|
|
38
|
+
검색·예약·답변 규칙은 헤이유미 서버가 내려 준다. 이 문서보다 항상 최신이므로, 이 문서와 다르면 `guide`를 따른다. 규칙에 나오는 도구 이름(`search_places`, `request_reservation` 등)은 출력의 `commands`에 적힌 CLI 명령으로 실행한다.
|
|
38
39
|
|
|
39
|
-
### 2.
|
|
40
|
+
### 2. 로그인 (머신당 한 번)
|
|
40
41
|
|
|
41
42
|
```bash
|
|
42
|
-
npx -y heyyumi
|
|
43
|
-
npx -y heyyumi
|
|
44
|
-
npx -y heyyumi
|
|
45
|
-
npx -y heyyumi@0 nearby --lat 37.5662 --lng 126.991 --radius 800
|
|
46
|
-
npx -y heyyumi@0 place 324146172 --fields quality,contact_hours,edge
|
|
43
|
+
npx -y heyyumi status # signedIn 여부 확인
|
|
44
|
+
npx -y heyyumi login # 브라우저에서 구글 로그인, 끝나면 스스로 종료
|
|
45
|
+
npx -y heyyumi login --no-browser # 로그인 URL만 stderr로 출력
|
|
47
46
|
```
|
|
48
47
|
|
|
49
|
-
|
|
50
|
-
- 검색은 지역/음식과 함께 쓴다. 지역 없이 파트너 전체를 나열하면 `partner_scope_required`가 나온다.
|
|
51
|
-
- 플래그는 도구 필터 이름 그대로다(`--region`→`region_name`). 오타는 CLI가 거절하고 비슷한 이름을 알려 준다. 전체 어휘는 `npx -y heyyumi@0 tools search_places`.
|
|
52
|
-
- 자주 쓰는 값: `--subtype`(`coffee`, `dessert`, `bakery`, `brunch`, `korean`, `italian`, `cocktail_bar`, `korean_bbq` …, 쉼표=OR, 한국어도 됨), `--atmosphere`(`trendy`, `cozy`, `quiet`, `lively`, `view`, `spacious` …), `--recommended_for`(`date`, `group_dining`, `business_meeting` …), `--open_at`(한국시간 `"2026-10-25 19:00"`), 불리언은 값 없이 `--parking`.
|
|
53
|
-
- **`--atmosphere`는 순위 가중치일 뿐 걸러내지 않는다.** `meta.softenedFilters`에 나열된 조건은 "확정 매칭이 아니라 선호 정렬"이라고 사용자에게 알린다. "힙한" 같은 요청은 `atmosphere`에 `trendy`가 있는지, `aiSummary`, 메뉴, 리뷰 수, 인스타(`snsLinks`)로 근거를 보여 준다.
|
|
54
|
-
- 응답: 검색은 `{success, data:[...], meta, locationNote}`, 상세는 `{success, data:{...}}`. 매장 id는 `data[].id`.
|
|
55
|
-
- 결과 해석: `confidence`(0~1, 높을수록 신뢰), `freshnessScore`(0~1, 높을수록 최근), `possiblyClosed`/`closureSignal`이 있으면 알린다. `openNow`와 `hours`는 한국시간. 점수가 낮다고 폐업으로 단정하지 않는다.
|
|
56
|
-
- `locationNote`는 어느 지역을 검색했는지 한 줄로 알리라는 지시다. 행정동 코드·"읍/면" 같은 용어 없이 "을지로 상권을 찾았어요"처럼 말하고, 같은 이름의 다른 지역일 수 있으면 짧게 되묻는다.
|
|
57
|
-
- 후보는 이름, 주소, 가까운 역, 오늘/해당 시각 영업 여부, 예약 가능 여부(파트너 여부와 `requestHours`), `placeUrl`을 붙여 2~5곳으로 정리한다.
|
|
58
|
-
|
|
59
|
-
### 3. 예약 가능 여부 판단
|
|
60
|
-
|
|
61
|
-
검색·상세 결과의 `yumiBooking`을 읽는다.
|
|
62
|
-
|
|
63
|
-
| 값 | 의미 |
|
|
64
|
-
| --- | --- |
|
|
65
|
-
| `canRequest: true, partner: true, requestHours: "anytime"` | 유미 파트너. 언제든 요청 가능, 응답이 빠르고 실시간 문의도 가능 |
|
|
66
|
-
| `canRequest: true, partner: null, requestHours: "11:00-21:00 KST"` | 비파트너. **매일 11:00~21:00 KST에만 요청을 받는다.** 그 밖 시간이면 `reservation_requests_closed`와 `retryAfter` |
|
|
67
|
-
| `canRequest: false` 또는 `yumiBooking` 없음 | 이 CLI로는 예약 요청 불가. `reservationChannels`/`phone`/`bookingUrl`로 전화·외부 예약을 안내 |
|
|
68
|
-
|
|
69
|
-
예약 요청 가능 시각과 매장 영업시간은 별개다. 영업 요일·시간(`hours`, `openNow`)도 확인하고, 휴무 요일이나 영업 외 시간이면 사용자에게 알리고 시각을 바꾼다.
|
|
70
|
-
|
|
71
|
-
### 4. 예약 정보 모으기
|
|
72
|
-
|
|
73
|
-
필수: 매장(`PLACE_ID`), 날짜·시각(한국시간), 인원(`--party`), **예약자 휴대폰 번호(`--phone`)**. 이름(`--name`)은 강하게 권장하고, `--note`(알레르기·기념일·좌석)와 `--lang`은 선택이다. 한국 번호가 아니면 **`--email`이 필수**다(문자를 못 보내 이메일로 결과를 보낸다). 한국 번호 사용자에게는 이메일을 묻지 않는다.
|
|
48
|
+
`status`가 `signedIn:false`거나 어떤 명령이 종료 코드 3을 내면 `login`을 실행한다. **로그인과 약관 동의는 사용자가 직접 한다.** 에이전트가 구글 로그인 화면을 대신 누르지 않는다. `--no-browser`일 때는 stderr의 URL을 사용자에게 주고 같은 컴퓨터의 브라우저에서 열게 한다(콜백이 `127.0.0.1`로 돌아오므로 원격 셸에서는 안 된다). 토큰은 `~/.config/heyyumi/credentials.json`(0600)에 저장되고 자동 갱신된다. `logout`으로 지운다.
|
|
74
49
|
|
|
75
|
-
|
|
50
|
+
이미 대시보드 키(`hmp_...`)가 있으면 `HEYYUMI_API_KEY`로 넘겨도 된다. 키·토큰은 채팅에 출력하지 않는다.
|
|
76
51
|
|
|
77
|
-
###
|
|
78
|
-
|
|
79
|
-
1. **`clarify`로 정확한 매장명·주소, 날짜·시각(요일 포함), 인원, 예약자 이름·번호(·이메일), 요청사항을 보여 주고 "이 내용으로 사장님에게 예약 요청을 보낼까요? 선결제는 없고 실제 매장으로 전달됩니다"라고 승인받는다.** 승인 전에는 `reserve`를 실행하지 않는다. 사장님 푸시와 손님 문자는 취소할 수 없다.
|
|
80
|
-
2. 승인 후에만 실행한다.
|
|
52
|
+
### 3. 후보 찾기 (부작용 없음)
|
|
81
53
|
|
|
82
54
|
```bash
|
|
83
|
-
npx -y heyyumi
|
|
55
|
+
npx -y heyyumi search --region 을지로 --subtype coffee --atmosphere trendy --page-size 8
|
|
56
|
+
npx -y heyyumi search 파스타 --region 홍제동 --open_at "2026-10-25 19:00"
|
|
57
|
+
npx -y heyyumi place 324146172
|
|
84
58
|
```
|
|
85
59
|
|
|
86
|
-
|
|
60
|
+
전체 필터는 `npx -y heyyumi tools search_places`로 본다. 오타 난 플래그는 CLI가 거절하고 비슷한 이름을 알려 준다. 결과에 사용자에게 전할 안내 문구가 붙어 오면 사용자 언어로 전한다.
|
|
61
|
+
|
|
62
|
+
### 4. 예약 요청 (`clarify` 승인 후에만)
|
|
87
63
|
|
|
88
|
-
|
|
64
|
+
1. `npx -y heyyumi guide reserve`를 읽고 필요한 정보를 모은다. 빠진 값은 사용자에게 묻고 지어내지 않는다.
|
|
65
|
+
2. **`clarify`로 매장명·주소, 날짜·시각(요일 포함), 인원, 예약자 이름·번호, 요청사항을 보여 주고 "이 내용으로 매장에 예약 요청을 보낼까요? 선결제는 없고 실제 매장으로 전달됩니다"라고 승인받는다.** CLI에는 전송 없는 미리보기가 없어서 `reserve`를 실행하는 순간이 곧 전송이다.
|
|
66
|
+
3. 승인 후에만 실행한다.
|
|
89
67
|
|
|
90
68
|
```bash
|
|
91
|
-
npx -y heyyumi
|
|
69
|
+
npx -y heyyumi reserve 324146172 --time "2026-10-25 19:00" --party 2 --name "홍길동" --phone 010-1234-5678
|
|
92
70
|
```
|
|
93
71
|
|
|
94
|
-
|
|
72
|
+
4. 출력에 `cli.next`가 있으면 그 명령을 실행하고, 결과는 `guide reserve`에 적힌 대로 전한다. 확정 전에는 "예약 완료"라고 말하지 않는다. 네트워크 오류로 같은 요청을 다시 보낼 때는 `--idempotency-key`를 같은 값으로 준다.
|
|
95
73
|
|
|
96
|
-
###
|
|
74
|
+
### 5. 실시간 문의 (`clarify` 승인 후에만)
|
|
97
75
|
|
|
98
76
|
```bash
|
|
99
|
-
npx -y heyyumi
|
|
100
|
-
npx -y heyyumi
|
|
101
|
-
npx -y heyyumi
|
|
102
|
-
npx -y heyyumi@0 live-wait QUERY_ID --timeout 110
|
|
77
|
+
npx -y heyyumi guide live
|
|
78
|
+
npx -y heyyumi live PLACE_ID --kind wait --topic "웨이팅"
|
|
79
|
+
npx -y heyyumi live-wait QUERY_ID
|
|
103
80
|
```
|
|
104
81
|
|
|
105
|
-
|
|
82
|
+
예약처럼 승인받은 뒤 실행한다. 문의는 매장 휴대폰으로 바로 간다.
|
|
106
83
|
|
|
107
84
|
## Done when
|
|
108
85
|
|
|
109
|
-
- 검색 요청: 조건에 맞는 후보를
|
|
110
|
-
- 예약 요청: 사용자 승인 후 `reserve`를 보냈고,
|
|
111
|
-
- 사용자가 승인하지 않았거나 필수 정보가 비어 있으면
|
|
86
|
+
- 검색 요청: 조건에 맞는 후보를 근거와 함께 제시했다.
|
|
87
|
+
- 예약 요청: 사용자 승인 후 `reserve`를 보냈고, 매장의 답이나 이후 확인 방법을 보고했다.
|
|
88
|
+
- 사용자가 승인하지 않았거나 필수 정보가 비어 있으면 **보내지 않은 상태로 끝냈다**고 밝혔다.
|
|
112
89
|
|
|
113
90
|
## Failure modes
|
|
114
91
|
|
|
115
|
-
| 증상 |
|
|
116
|
-
| --- | --- |
|
|
117
|
-
| 종료 코드 3
|
|
118
|
-
|
|
|
119
|
-
| 종료 코드
|
|
120
|
-
| `
|
|
121
|
-
| `reservation_requests_closed` | 비파트너 매장 요청 시간(11:00~21:00 KST) 밖 | `retryAfter` 이후에 다시 안내 |
|
|
122
|
-
| `venue_closed_at_requested_time` | 요청 시각이 휴무/영업 외 | 다른 시각 제안 |
|
|
123
|
-
| `reservation_time_past` | 지난 시각 | 시각 확인 |
|
|
124
|
-
| `guest_phone_required` / `guest_email_required` | 연락처 누락 | 사용자에게 다시 묻기 |
|
|
125
|
-
| `live_status_not_available` | 사장님 앱이 없는 매장 | 재시도 금지, 검색 결과의 영업시간으로 답 |
|
|
126
|
-
| `partner_scope_required` | 지역 없이 파트너 나열 | 지역이나 음식을 받아 다시 검색 |
|
|
127
|
-
| `http_error`/`rpc_error`, 종료 코드 1 | 서버 오류·한도 | 메시지를 그대로 알리고 잠시 후 한 번만 재시도 |
|
|
92
|
+
| 증상 | 처리 |
|
|
93
|
+
| --- | --- |
|
|
94
|
+
| 종료 코드 3 | `login` 안내(사용자가 구글 로그인). `invalid_api_key`면 키를 확인하거나 unset 후 `login` |
|
|
95
|
+
| 종료 코드 2, `usage`/`unknown_option` | 메시지의 제안대로 플래그를 고친다 |
|
|
96
|
+
| 종료 코드 1, 그 밖의 `error.code` | `error.message`를 사용자 언어로 전하고 `error.next`나 `guide`가 안내하는 대로 한다. 같은 요청을 자동으로 되풀이하지 않는다 |
|
|
97
|
+
| `Unknown command "guide"` | 오래된 CLI 사본이다. `npx -y heyyumi@latest guide`로 실행한다 |
|
|
128
98
|
|
|
129
99
|
## Boundaries
|
|
130
100
|
|
|
131
|
-
- 개인의 대화형 사용을 위한 스킬이다. 무료는 개인 사용 기준이며 하루 질문 한도가 있다. 회사 제품·서비스에 넣는 상업 이용과 대량 수집은 헤이유미 별도 라이선스 대상이라 이 스킬로 하지 않는다. 대량 목록 요청이
|
|
101
|
+
- 개인의 대화형 사용을 위한 스킬이다. 무료는 개인 사용 기준이며 하루 질문 한도가 있다. 회사 제품·서비스에 넣는 상업 이용과 대량 수집은 헤이유미 별도 라이선스 대상이라 이 스킬로 하지 않는다. 대량 목록 요청이 막히면 조건을 좁힌다.
|
|
132
102
|
- 토큰·키·연락처를 저장소, 로그, 채팅에 남기지 않는다. 결제·카드 정보는 다루지 않는다(선결제 없음).
|
|
133
103
|
- 이 스킬은 헤이유미 공식 기능이 아니며 제휴 관계를 주장하지 않는다. 출처를 "헤이유미(HeyYumi)"로 표기한다.
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "heyyumi",
|
|
3
|
-
"description": "한국 식당·카페·바를
|
|
3
|
+
"description": "헤이유미(HeyYumi)로 한국 식당·카페·바를 찾고, 그 자리에서 예약 요청을 보내 매장의 수락/거절까지 확인하는 스킬. 지역·역·랜드마크, 메뉴 이름(몸국, 소금빵 등), 분위기, 영업 시각, 주차, 채식·비건, 아이·반려동물 동반, 외국어 응대 같은 조건으로 맛집 찾기, 식당 예약, 테이블 예약, 카페 예약, 예약 가능 여부 확인, 지금 자리 있나·웨이팅 몇 분인지 매장에 물어보기가 필요할 때 사용한다. 한국어를 몰라도 되고, 외국어로 쓴 요리 이름과 지명도 알아듣는다. Use when the user wants to find a Korean restaurant, cafe, or bar by area, dish, or condition (parking, vegan, kids, pets, foreigner-friendly), book a table or send a reservation request via HeyYumi, or ask a venue about current wait time or seat availability, in any language.",
|
|
4
4
|
"profiles": [
|
|
5
5
|
"vault",
|
|
6
6
|
"action:booking"
|
|
7
7
|
],
|
|
8
|
-
"frontmatter": "name: heyyumi\ndescription: 한국 식당·카페·바를
|
|
8
|
+
"frontmatter": "name: heyyumi\ndescription: 헤이유미(HeyYumi)로 한국 식당·카페·바를 찾고, 그 자리에서 예약 요청을 보내 매장의 수락/거절까지 확인하는 스킬. 지역·역·랜드마크, 메뉴 이름(몸국, 소금빵 등), 분위기, 영업 시각, 주차, 채식·비건, 아이·반려동물 동반, 외국어 응대 같은 조건으로 맛집 찾기, 식당 예약, 테이블 예약, 카페 예약, 예약 가능 여부 확인, 지금 자리 있나·웨이팅 몇 분인지 매장에 물어보기가 필요할 때 사용한다. 한국어를 몰라도 되고, 외국어로 쓴 요리 이름과 지명도 알아듣는다. Use when the user wants to find a Korean restaurant, cafe, or bar by area, dish, or condition (parking, vegan, kids, pets, foreigner-friendly), book a table or send a reservation request via HeyYumi, or ask a venue about current wait time or seat availability, in any language.\nlicense: MIT\nmetadata:\n category: food\n locale: ko-KR\n phase: v1"
|
|
9
9
|
}
|