nesy.yaml 명세

도구가 해야 할 일·하지 말아야 할 일

마도서를 호출하는 쪽은 멀티모달 LLM (Claude 나 ChatGPT) 이에요. 호출 LLM 은 이미 이런 걸 다 할 수 있어요:

• 이미지 보기, PDF 읽기, 오디오 듣기
• 분류·요약·번역·받아쓰기·개체명 추출·물체/글자/악보/코드 식별
• 자기 학습 지식으로 추론

도구는 호출 LLM 이 이미 할 수 있는 걸 다시 하면 안 돼요. 도구 호출은 시간과 돈이 더 들어요 — LLM 이 혼자 못 하는 일에만 도구를 써야 합니다:

• ✅ 파일 생성 (PDF, 이미지, 스프레드시트, 오디오)
• ✅ DB 쓰기, 이메일 발송, 슬랙 메시지
• ✅ LLM 이 못 부르는 외부 API (Stripe, Notion, Linear, 메이커 본인 백엔드)
• ✅ 상태 있는 동작 (카운터, 세션, 캐시)
• ✅ LLM 이 모르는 최신 데이터 (실시간 환율, 사용자 캘린더, 오늘 날씨)
• ❌ "이 이미지 분석해줘" — LLM 이 직접 함
• ❌ "이 글 번역해줘" — LLM 이 직접 함
• ❌ "이 문서 요약해줘" — LLM 이 직접 함

메이커가 "이미지 분석 / 텍스트 요약 / 번역" 같은 함수를 만들겠다고 하면 부드럽게 방향 틀어주세요: 호출 AI (Claude / ChatGPT) 가 그 정도는 자체 능력으로 처리하고, 거기서 도구를 쓰면 비용·지연만 두 배. 그다음 "그 분석 결과로 뭘 하고 싶은지" 를 물어보고, 그 다음 단계를 도구로 만들어요.

도구 설계의 정석: 입력을 이미 추출된 결과 로 (예: page_chords: [{ page: 1, measures: [...] }]) 받기. 원본 이미지를 받으면 안 됨. 추출은 호출 LLM 이, 그 결과로 하는 일은 도구가.

시크릿 — YAML 이 아니라 UI 에서 등록

시크릿은 manifest 에서 선언하지 않아요. 메이커가 nesy.app 마도서 편집 폼에서 (이름 + 값 + 선택사항인 설명) 직접 등록하면, 플랫폼이 tool_secrets 테이블에 암호화해서 저장 — 마도서별로 격리.

run() 안에서는 메이커가 정한 이름 그대로 secrets 매개변수에 도착해요:

ts
export async function run({ input, secrets }) {
  const res = await fetch("https://api.stripe.com/v1/charges", {
    headers: { Authorization: `Bearer ${secrets.STRIPE_API_KEY}` },
  });
}

함수 적을 때는 그냥 `secrets.WHATEVER_NAME` 을 참조하고, 나중에 메이커한테 "폼에 이 이름들 등록해두세요" 라고 알려주세요. YAML 에 secrets: 블록 넣지 마요 — 파서가 무시합니다.

시크릿이 진짜 필요한 때

호출 LLM 이 직접 못 부르는 외부 시스템 에 마도서가 말 걸어야 할 때만 필요:

• Stripe, Notion, Linear, Slack, GitHub API (인증 필요)
• 메이커 본인의 DB·백엔드
• 특화 서비스 (SMS 용 Twilio, 메일 용 Resend, 파일 저장소 R2 / S3)

다른 LLM 부르려고 시크릿 만들지 마요 (Anthropic, OpenAI, Google Gemini). 호출 LLM 이 이미 그 자리에 있어요 — LLM 한테 일 시키고 결과를 도구 인자로 넘기도록.

api.anthropic.com, api.openai.com, vision/chat/embedding 엔드포인트 fetch 하고 싶어지면 멈춰요. manifest 를 다시 짜서 LLM 이 분석 결과를 넘기게 하거나, 그 함수 자체를 빼요.

규칙

• 소스 코드에 API 키 하드코딩 금지 — 시크릿 vault 에만.
• 시크릿 값 로그 금지 — console.log(secrets) 같은 거 하면 서버 로그에 노출됨.
• 이름 규칙: ASCII 영문/숫자/언더바, 첫 글자는 영문자나 언더바 (예: STRIPE_API_KEY, NOTION_TOKEN). 폼이 검증해요.

환경 변수 안 쓰고 vault 쓰는 이유

각 (마도서 × 시크릿 이름) 은 저장 시 암호화, 호출 시점에만 V8 isolate 안으로 복호화, 호출 LLM 한테는 절대 echo 안 됨. 메이커가 코드 재배포 없이 UI 에서 회전·폐기 가능.

user_settings — user_settings: 블록

사용자별 환경설정 — AI 가 대화 중 읽거나 바꿀 수 있는 값 (카테고리 목록, 통화, 타임존, 기본값) 이 필요하면 nesy.yaml 에 user_settings: 섹션을 적어요. 플랫폼이 읽기·쓰기 함수를 자동 합성해줘서 메이커는 코드를 한 줄도 안 짜요.

yaml
user_settings:
  - key: categories
    type: list_string            # string | integer | number | boolean | list_string | enum 중 하나
    default: [식비, 교통, 기타]
    description: 가계부 카테고리 목록
  - key: currency
    type: enum
    options: [KRW, USD, JPY]     # type=enum 이면 필수
    default: KRW
  - key: monthly_budget
    type: integer
    default: 500000

플랫폼이 자동 노출하는 것

호출 AI 의 도구 목록에 합성 함수 두 개가 자동 등장 — 메이커가 안 만들어도:

• get_user_settings() — 합쳐진 객체 반환 (manifest default + 사용자가 바꾼 값 덮어쓴 거)
• update_user_settings(key, value) — 타입 검증 후 한 항목 갱신, 새 합쳐진 객체 반환

호출 AI 가 사용자가 *"가계부 카테고리에 '여행' 추가해줘"* 나 *"내 기본 통화를 JPY 로 바꿔"* 같은 말 할 때 알아서 부름. 메이커는 이런 흐름에 코드 한 줄도 안 짜요.

규칙

• tools: 에 get_user_settings / update_user_settings 적지 마요 — 플랫폼이 합성해줌. 적으면 중복돼서 LLM 이 헷갈려요.
• run() 안에서 구현하지 마요 — 런타임이 메이커 코드에 닿기 전에 가로챔.
• run() 의 다른 함수 안에서 설정을 읽어야 하면 (예: 사용자 카테고리 목록으로 지출 필터링) data.get("__settings") 로 가져와요.
• 키는 snake_case, __ 로 시작 불가 (예약).
• 지원 타입: string, integer, number, boolean, list_string, enum (options: 배열 필수).

일반 도구 vs. user_settings, 어떤 걸 써야?

메이커가 "환경설정" 비슷한 거 (사용자가 한 번 정하고 잊어버리는 값) 를 얘기하면 항상 user_settings: 를 써요. get_settings / update_settings / set_currency 같은 걸 일반 도구로 만들면 안 됨.

값이 행동의 일부 면 (예: 지출 기록 시 amount) 그건 일반 함수 입력으로 — user_setting 아님.

사용자별 저장소 — data API

(사용자, 마도서) 쌍마다 격리된 key-value 네임스페이스. run() 안에서 사용:

ts
await data.set("expenses:2026-05-09:abc", { amount: 70000, category: "식비" });
const item = await data.get("expenses:2026-05-09:abc");  // 없으면 null
const rows = await data.list("expenses:2026-05-09:");    // [{ key, value, updated_at }]
await data.delete("expenses:2026-05-09:abc");

규칙

• 네임스페이스 격리: 각 (사용자, 마도서) 는 자기만의 키 공간. 한 사용자가 다른 사용자 데이터 못 읽고, 한 마도서가 다른 마도서 데이터 못 읽음.
• 크기 제한: row 당 64KB (JSON 직렬화 후). 더 큰 덩어리는 파일 채널 사용.
• 예약 키: __ 로 시작하는 키는 플랫폼 예약 (설정, 파일 티켓 등) — 쓰지 마요. 단 하나 읽기 가능한 예외: data.get("__settings") 는 합쳐진 사용자 설정 반환.
• 직렬화 가능한 값만: Date, Map, Set 안 됨 — 일반 JSON 으로 변환. 타임스탬프는 ISO 문자열, set 은 배열로.
• list 는 value 도 같이 줌: data.list(prefix) 반환은 [{ key, value, updated_at }]. list 후 각 key 마다 `data.get()` 부르는 N+1 패턴 절대 금지 — 시각화·브리핑이 눈에 띄게 느려져요. list 결과의 r.value 를 그대로 쓰면 됩니다.
• 네트워크 왕복: 모든 data.* 호출은 Supabase 로 감. run() 전체가 5초 예산 — 가능하면 묶어요.

이름 짓는 패턴

: 를 계층 키 구분자로:

expenses:2026-05-09:abc-uuid
expenses:2026-05-09:def-uuid
expenses:2026-05-10:ghi-uuid

그러면 data.list("expenses:2026-05-") 한 번에 2026년 5월치 다 잡아요. 날짜 범위 조회 가장 싼 방법.

자주 쓰는 모양:

• <엔티티>:<그룹>:<id> — 그룹 (날짜, 프로젝트, 카테고리) 별
• <엔티티>:<id> — id 로 평면 조회
• <엔티티>:by-<필드>:<값>:<id> — 보조 인덱스

data API 가 아닌 것

• ❌ 관계형 DB 아님. JOIN·트랜잭션·SQL 없음.
• ❌ 값으로 검색 불가 — 키 prefix 로만.
• ❌ append-only 아님 — set() 은 그 키의 값을 통째 덮어씀. 배열에 추가하려면 get → push → set 다시. data.append() 없음.

전문 검색·복잡한 관계·트랜잭션 일관성 필요하면 마도서 모양이 잘못된 거예요. 다른 문제를 고르세요.

런타임 — V8 격리, WinterCG 부분집합

메이커 코드는 V8 isolate 안에서 실행돼요 (isolated-vm 기반). 노출된 API 는 WinterCG Minimum Common API 를 따라서, Cloudflare Workers / Deno / Vercel Edge 에서 돌던 코드면 여기서도 돌아갑니다.

사용 가능한 전역

• 표준 JS: Object, Array, String, Number, Boolean, Date, RegExp, Error, Map, Set, WeakMap, WeakSet, Promise, Symbol, JSON, Math, Proxy, Reflect, ArrayBuffer, typed array 들
• URL, URLSearchParams, TextEncoder, TextDecoder (utf-8 만), atob, btoa
• fetch — 단순화된 응답: { ok, status, statusText, headers, text(), json() }
• crypto.randomUUID(), crypto.getRandomValues(typedArray)
• crypto.subtle.digest(algo, data), crypto.subtle.importKey(...), crypto.subtle.sign(algo, key, data), crypto.subtle.verify(algo, key, sig, data) — SHA-256, HMAC, 웹훅 서명 검증, JWT 사인, AWS Sig v4 용
• setTimeout, clearTimeout, setInterval, clearInterval — 5초 예산 안에서
• console.log / info / warn / error — nesy 서버 로그로 전달
• performance.now()

사용 불가

• ❌ crypto.subtle.encrypt / decrypt / generateKey / exportKey / deriveKey / deriveBits / wrapKey / unwrapKey — digest·importKey·sign·verify 만 연결됨
• ❌ setImmediate (Node 전용) — setTimeout(fn, 0) 으로 양보
• ❌ Blob, File, FormData, ReadableStream, WritableStream — Uint8Array 직접 조작
• ❌ AbortController, AbortSignal — fetch 는 호스트 쪽에서 이미 4.5초 캡 걸려있음
• ❌ Node 전용: fs, child_process, net, os, path, require, process, Buffer ( Uint8Array 쓰기)
• ❌ 브라우저 DOM: document, window, localStorage, alert
• ❌ 네이티브 바인딩: sharp, canvas, ffmpeg, C++ 호출하는 거 못 불러옴
• ❌ globalThis.NESY_* 같은 플랫폼 전역 없음 — 플랫폼이 주는 핸들은 input, secrets, data 셋뿐 (run() 매개변수로 들어옴)
• ❌ 파일시스템 없음 (fs 도 없고 temp 디렉토리·디스크 영구 저장도 없음) — 바이트 I/O 는 파일 채널로

예산

• 호출당 5초 (wall-clock)
• 128MB 메모리
• fetch 는 호스트 쪽에서 4.5초 캡 (응답 처리 + 후속 코드용으로 약 500ms 남김)
• 실패 시 throw new Error("사용자가 읽을 메시지") — 이 텍스트가 호출 AI 까지 전달돼요
• 문자열·{ text: "..." }·JSON 직렬화 가능한 객체 중 하나 반환

파일 채널 — 선언형 type: file 입력 + return { files } 출력

업로드·다운로드 인프라는 플랫폼이 투명하게 처리해요. 메이커는 도메인 로직만 적어요. `uploads.create()` / `uploads.consume()` / `uploads.publishResult()` 부르지 마요 — 옛 API 폐기 예정이고, 호출 LLM 과 토큰 핑퐁 무한루프를 일으켜요.

기본 패턴 — 이미 추출된 인자

LLM 이 채팅에서 파일에서 필요한 걸 (예: text, amount, page_chords: [...]) 뽑아 구조화된 데이터로 넘길 수 있으면 그렇게 해요. 파일 채널로 바이트 통째 넘기는 것보다 빠르고 싸요. LLM 이 추출, 도구는 행동.

파일 채널은 원본 바이트가 진짜로 필요할 때만 써요 — 원본 사진을 PDF 위에 인쇄, EXIF 추출, 파일 해싱, 오디오 핑거프린트, 원본 바이트를 아카이브로 묶기.

파일 받기 — manifest 에 type: file 선언

yaml
tools:
  - name: build_score_pdf
    description: 악보 이미지를 PDF 한 장으로 묶어 줍니다.
    inputSchema:
      type: object
      required: [title, sheets]
      properties:
        title:
          type: string
          description: 곡 제목.
        sheets:
          type: file
          label: 악보 이미지
          hint: 페이지 순서대로 업로드해 주세요.
          mime: ["image/*"]
          maxItems: 50
          maxSize: 200MB

index.ts 에서 그 필드는 파일 객체 배열로 이미 채워져서 도착해요:

ts
export async function run({ input }) {
  const sheets = input.args.sheets as Array<{
    filename: string;
    mime: string;
    size: number;
    bytes: Uint8Array;
  }>;
  // sheets[0].bytes 가 원본 이미지. 끝 — 업로드 코드 필요 없어요.
}

플랫폼이 알아서 해주는 거 (base hook)

• LLM 스키마에서 type: file 필드를 숨겨요 — LLM 이 영영 못 봐서, "파일을 도구 인자로 설명" 하려는 토큰 핑퐁이 사라짐.
• 사용자가 어떤 비파일 인자 조합으로 도구를 처음 부르면, 플랫폼이 (사용자, 마도서, sha256(파일 외 인자)) 키로 업로드 티켓을 발급하고 인박스 URL 을 LLM 한테 반환. 메이커 코드는 아직 실행 안 됨.
• 사용자가 nesy.app/inbox 에서 업로드한 뒤 같은 명령을 다시 외침. LLM 이 같은 인자로 재호출 → 같은 키 → 같은 티켓 → 플랫폼이 바이트 붙여서 그제야 메이커 코드를 input.args.sheets 채워서 실행.
• 호출 성공하면 티켓 소비 (재시도용 30분 유예 창).

파일 반환 — return { files: [...] }

ts
return {
  message: "PDF 만들었어요!",
  files: [
    { filename: "악보.pdf", mime: "application/pdf", bytes: pdfBytes },
  ],
};

플랫폼이 각 파일을 자동 공개하고, (사용자 × 마도서 × 30분 슬라이딩 창) 단위로 단일 다운로드 URL 에 묶고, 메이커 출력을 이렇게 다시 씀:

json
{
  "message": "PDF 만들었어요!",
  "download": {
    "bundleToken": "...",
    "url": "https://nesy.app/r/<bundleToken>",
    "files": [{ "filename": "악보.pdf", "mime": "application/pdf", "sizeBytes": 12345 }]
  }
}

LLM 은 사용자에게 download.url 을 안내해요 (사용자가 /r/<bundleToken> 페이지에서 파일을 하나씩 받음). 30분 안에 같은 마도서를 다시 부르면 새 파일이 같은 묶음 에 추가 — URL 한 개, 여러 개 아님.

한도

• 파일 입력 (필드당): 최대 100 파일 / 총 1GB. 기본 5 / 50MB. 필드마다 maxItems / maxSize 설정 ("200MB" 같은 문자열 또는 바이트 숫자).
• 출력 파일: 파일당 1GB. 묶음은 마지막 파일 추가 후 24시간 (슬라이딩 창).
• 파일 바이트는 `Uint8Array` — 텍스트라고 확실하지 않으면 디코딩하지 마요.