democut 0.6.46 → 1.0.0
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/README.md +82 -74
- package/dist/cli.js +35059 -25936
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -41,76 +41,89 @@ democut auth login --json
|
|
|
41
41
|
토큰은 **승인한 사람의 워크스페이스와 플랜(tier/role)** 으로 스코프된다 — 워크스페이스마다
|
|
42
42
|
각자의 에이전트를 붙일 수 있는 멀티테넌트 구조.
|
|
43
43
|
|
|
44
|
-
##
|
|
44
|
+
## 명령 — MCP 도구와 **같은 이름**
|
|
45
|
+
|
|
46
|
+
`democut mcp` 가 에이전트에게 주는 도구를 터미널·스크립트에서도 그대로 부른다. 이름은 도구 이름의
|
|
47
|
+
밑줄만 하이픈으로 바꾼 것이고, 밑줄·`democut_` 접두사 형태도 그대로 받는다.
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
democut_estimate_cuts (MCP 도구)
|
|
51
|
+
democut estimate-cuts (CLI — 같은 인자, 같은 결과)
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
명령·인자·설명은 **손으로 쓰지 않는다.** 서버의 도구 표(`GET /api/meta/tools`)를 빌드 때 받아
|
|
55
|
+
생성하므로 계약과 어긋날 자리가 없다.
|
|
45
56
|
|
|
46
57
|
```bash
|
|
47
|
-
democut
|
|
48
|
-
democut
|
|
49
|
-
democut
|
|
58
|
+
democut --help # 묶음별 명령 목록
|
|
59
|
+
democut help export # 한 묶음만 자세히
|
|
60
|
+
democut estimate-cuts --help # 그 명령의 인자
|
|
50
61
|
```
|
|
51
62
|
|
|
52
|
-
###
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
###
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
63
|
+
### 인자 주는 법
|
|
64
|
+
|
|
65
|
+
플래그로 주거나, MCP 호출 본문을 통째로 넘긴다.
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
# 플래그 — 사람이 치기 좋다
|
|
69
|
+
democut estimate-cuts --slug demo --items '[{"cut_id":"c1","mode":"ai_video"}]'
|
|
70
|
+
|
|
71
|
+
# 인자 객체 그대로 — 에이전트·스크립트가 MCP 호출을 그대로 옮길 때
|
|
72
|
+
democut estimate-cuts --args-json '{"slug":"demo","items":[…]}'
|
|
73
|
+
echo '{"slug":"demo","items":[…]}' | democut estimate-cuts --args-json @-
|
|
74
|
+
democut estimate-cuts --args-json @payload.json
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
둘을 함께 주면 **플래그가 이긴다**(통째로 준 본문 위에 한 값만 덮어쓰는 것이 자연스럽다).
|
|
78
|
+
불리언은 값 없이 켜고(`--transcribe`) `--no-` 로 끈다. 배열·객체 인자는 JSON 문자열이다.
|
|
79
|
+
모르는 인자는 **조용히 무시하지 않고 거부한다** — 삼키면 넣은 값이 오류 없이 사라진다.
|
|
80
|
+
|
|
81
|
+
### 출력
|
|
82
|
+
|
|
83
|
+
기본은 사람이 읽는 문장이고, `--json` 은 성공·실패를 같은 모양으로 stdout 에 낸다.
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
democut get-storyboard --slug demo --json
|
|
87
|
+
# {"ok":true,"text":"…","data":{…}} ← data 는 MCP 의 structuredContent 와 같은 값
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
실패도 stdout 에 같은 모양으로 나온다(파이프로 읽는 쪽이 두 경로를 합치지 않아도 되게).
|
|
91
|
+
실패라는 사실은 **종료 코드**가 말한다.
|
|
92
|
+
|
|
93
|
+
### 비용 승인
|
|
94
|
+
|
|
95
|
+
돈이 나가는 명령은 승인 없이 진행하지 않는다. 대상은 계약이 정한다(도움말의 `[과금]`·`[소액]`).
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
# 대화형 — y/N 을 묻는다
|
|
99
|
+
democut make-cuts --slug demo --items '[…]' --confirmed-total-krw 1200 --rate-version 3
|
|
100
|
+
|
|
101
|
+
# 비대화형(CI·에이전트) — --yes 가 없으면 거부한다
|
|
102
|
+
democut make-cuts … --yes
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
승인 전에는 **요청을 보내지 않는다.** 물어보기만 하고 이미 제출했으면 게이트가 무의미하다.
|
|
90
106
|
|
|
91
107
|
### 종료 코드
|
|
92
108
|
|
|
93
109
|
| 코드 | 뜻 | 대응 |
|
|
94
110
|
|---|---|---|
|
|
95
111
|
| 0 | 성공 | — |
|
|
96
|
-
| 1 | 일반 오류 | 미로그인·사용자
|
|
97
|
-
| 2 |
|
|
98
|
-
| 3 | 일시적
|
|
99
|
-
| 4 | 업스트림 거부
|
|
100
|
-
| 5 |
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
| `-o`, `--output <경로>` | 생성된 mp4 저장. 서명 URL 이 24시간 후 만료되므로 사실상 필수 |
|
|
112
|
-
| `--json` | 기계 판독용 JSON 한 줄 |
|
|
113
|
-
| `--base-url <url>` | 서버 지정 (기본: prod) |
|
|
112
|
+
| 1 | 일반 오류 | 미로그인·사용자 취소·알 수 없음 |
|
|
113
|
+
| 2 | 고쳐서 재시도 가능 | 인자 오류·승인 누락. **과금 없음** |
|
|
114
|
+
| 3 | 일시적 오류 | **그대로 재시도해도 안전하다** |
|
|
115
|
+
| 4 | 업스트림 거부 | **재시도하면 재과금될 수 있다 — 자동 재시도 금지** |
|
|
116
|
+
| 5 | 대기 시한 초과 | 실패가 아니다. 작업은 서버에서 계속된다 — 재제출 금지 |
|
|
117
|
+
|
|
118
|
+
2~4 는 서버가 알려 준 재시도 안전성을 그대로 옮긴 것이다. 스크립트가 코드만 보고
|
|
119
|
+
「다시 걸어도 되는가」 를 판단할 수 있어야 재제출로 두 번 과금되지 않는다.
|
|
120
|
+
|
|
121
|
+
### 가이드
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
democut guide # 서버가 배포하는 에이전트 규약 원문(로그인 불필요)
|
|
125
|
+
democut init-agent # 그 규약을 레포의 CLAUDE.md 에 블록으로 써 준다(멱등)
|
|
126
|
+
```
|
|
114
127
|
|
|
115
128
|
## 개발
|
|
116
129
|
|
|
@@ -145,18 +158,12 @@ claude mcp add democut -- npx -y democut@latest mcp
|
|
|
145
158
|
쓰는 것보다 큰 소리로 안 뜨는 편이 낫다**(레지스트리가 막힌 사내망이면 아래 원격 HTTP 나
|
|
146
159
|
전역 설치를 쓴다).
|
|
147
160
|
|
|
148
|
-
|
|
161
|
+
도구 목록은 서버의 계약 표에서 생성된다(`GET /api/meta/tools`) — 수를 여기 적지 않는 이유는 표가 늘면 이 문장이 곧 거짓이 되기 때문이다. 목록과 인자는
|
|
162
|
+
`democut --help` 로 보는 것과 같다 — 같은 표에서 나오기 때문이다.
|
|
149
163
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
| `democut_estimate_video_cost` | 없음 — 비용만 계산 |
|
|
154
|
-
| `democut_credit_balance` | 없음 — 크레딧 잔액 |
|
|
155
|
-
| `democut_credit_ledger` | 없음 — 크레딧 사용 내역 |
|
|
156
|
-
| `democut_list_projects` | 없음 — 프로젝트 목록(최근 수정순) |
|
|
157
|
-
| `democut_get_video_status` | 없음 — 상태 조회 + 선택적 저장 |
|
|
158
|
-
| `democut_create_project` | **쓰기**(과금 없음) — 같은 제목이면 기존 것을 돌려준다 |
|
|
159
|
-
| `democut_generate_video` | **과금** — `confirmed_cost_usd` 필수 |
|
|
164
|
+
대부분은 조회·견적이라 부작용이 없고, 돈이 나가는 것은 계약이 `charge`·`small` 로 표시한
|
|
165
|
+
소수뿐이다(`make_cuts`·`make_export`·`make_thumbnails`·`make_cut_image`·`make_character_photo`·
|
|
166
|
+
`apply_proposal`·`propose`·`generate_youtube_meta`).
|
|
160
167
|
|
|
161
168
|
### 비용 승인이 프로토콜에 맞게 바뀐다
|
|
162
169
|
|
|
@@ -164,9 +171,10 @@ CLI 는 TTY 에 `y/N` 을 물어 사람을 막지만 MCP 에는 물어볼 화면
|
|
|
164
171
|
|
|
165
172
|
1. **호스트의 도구 승인** — Claude Code 등이 도구 호출 전에 사용자에게 확인을 받는다.
|
|
166
173
|
우리가 제어할 수 없으므로 이것만 믿지 않는다.
|
|
167
|
-
2. **`
|
|
168
|
-
보내야 하고, 서버가 방금 계산한 값과 대조해 어긋나면
|
|
169
|
-
|
|
174
|
+
2. **`confirmed_total_krw` 재확인** — 생성 도구는 호출자가 *직접 본* 견적 금액과 `rate_version` 을
|
|
175
|
+
다시 실어 보내야 하고, 서버가 방금 계산한 값과 대조해 어긋나면 409 `QUOTE_MISMATCH` 로 거부한다
|
|
176
|
+
(그때 과금은 0이고 새 견적을 준다). 모델이 견적을 건너뛰고 바로 만드는 것을 막고, 사람에게
|
|
177
|
+
보여준 금액과 실제 청구액이 갈라지지 않게 한다.
|
|
170
178
|
|
|
171
179
|
### stdio 와 원격 HTTP — 어느 쪽을 언제 쓰나
|
|
172
180
|
|