docs · 마법책
nesy 마법책
마도서를 만들고 펴는 데 필요한 모든 장. 3줄 요약으로 먼저 훑어보고, 필요한 장만 펼쳐 보세요.
호출 마법언어 — 마도서 부르는 이름
- ·사용자가 마도서를 부를 때 외치는 짧은 별명. "네시, 졸트라크" 처럼 접두어 + 호출어 형태.
- ·마도서당 1~3개, 32자 이내, nesy.app 전체에서 유일. YAML 이 아니라 등록 폼에서 입력.
- ·플랫폼이 자동으로 description 뒤에 붙여줘서 호출 LLM 이 우선 부르게 만듦.
도구 설계 — 노출할 것·뺄 것
- ·호출 LLM 이 이미 할 수 있는 일 (이미지 보기, 번역, 요약, 분류) 은 도구로 만들지 마요 — 비용·지연만 두 배.
- ·도구는 LLM 이 못 하는 일만: 파일 생성·DB 쓰기·외부 API·상태 있는 동작·실시간 데이터.
- ·함수 입력은 이미 추출된 결과로 받기. 추출은 LLM 이, 결과로 뭘 하는 건 도구가.
주문 잘 적기
- ·각 주문은 호출 LLM 과의 계약. name 은 snake_case, description 은 1~4000자 — "무엇·언제·무엇 반환" 3 가지 담기.
- ·description 이 부실하면 LLM 이 안 부르거나 매번 부름. 한국어 OK, 트리거 발화 꼭 넣기.
- ·inputSchema 는 인자 있을 때만. property 마다 단위·예시 적고, required 로 모양 명확히.
시크릿 — 외부 API 만
- ·시크릿은 manifest 가 아니라 nesy.app 편집 폼에서 등록 — 이름 + 값 한 쌍씩.
- ·run() 에서는 secrets.STRIPE_API_KEY 같이 그대로 참조. 하드코딩·로그 금지.
- ·필요한 때는 외부 API (Stripe, Notion 같은) 만. 다른 LLM 부르려고 만들지 마요 — 호출 LLM 이 이미 옆에 있음.
user_settings — 사용자별 설정
- ·사용자별 기본값 (카테고리·통화·타임존 같은 거) 은 user_settings: 로 선언. 코드 한 줄도 안 짜요.
- ·플랫폼이 get_user_settings·update_user_settings 두 합성 함수를 자동 노출. 직접 만들면 중복돼서 LLM 혼란.
- ·필요할 때 run() 안에서는 data.get("__settings") 로 읽기.
사용자별 저장소 — data API
- ·(사용자, 마도서) 쌍마다 격리된 key-value 저장소. run() 안에서 data.set/get/list/delete 로 씀.
- ·row 당 64KB 한도. ":" 를 계층 구분자로 쓰면 list(prefix) 한 번에 묶음 조회 가능.
- ·list() 는 key 만 아니라 value 도 같이 줌 — list + N get 패턴 절대 금지 (시각화가 느려짐).
- ·관계형 DB·검색·트랜잭션 없음. 그게 필요하면 마도서 모양이 잘못된 것.
런타임 — V8 격리, WinterCG 부분집합
- ·메이커 코드는 V8 격리에서 WinterCG 부분집합으로 실행. Workers·Deno·Edge 에서 돌던 코드면 그대로 동작.
- ·fetch·crypto.subtle (digest·sign·verify)·setTimeout 같은 거 OK. fs·Buffer·Blob·DOM·네이티브 바인딩 없음.
- ·호출당 5초·128MB. fetch 자체는 4.5초 캡. 실패는 throw new Error("사용자용 메시지").
파일 채널 — type:file 입력 / return { files } 출력
- ·파일은 manifest 에 type: file 로 선언하면 끝 — 업로드·다운로드 인프라는 플랫폼이 알아서. uploads.create() 호출 금지.
- ·입력은 input.args.<필드> 가 Uint8Array 포함 객체 배열로 도착. 출력은 return { files: [...] }.
- ·원본 바이트가 진짜 필요할 때만. 보통은 LLM 이 채팅에서 추출한 구조화 데이터로 받기.
알림 (예약 푸시)
- ·notifications: 블록은 cron 으로 도는 백그라운드 함수 선언 (cadence 60~86400, 기본 300). tools[] 에 넣지 마요.
- ·함수는 사용자별 격리 실행 — { notifications: [{id, title, body?, url?}] } 반환. id 가 중복 제거 키.
- ·사용자 설정 같은 건 data API 로 읽기. 아직 설정 없으면 빈 배열 반환 (throw 금지).
시각화 (서재 위젯)
- ·visualization: 블록은 사용자 /library 의 시각화 모달에서 HTML 을 반환할 함수 선언. 함수는 { html: "..." } 만 반환.
- ·cadence 10~3600 초마다 자동 새로고침. inputSchema + postMessage 로 클릭 가능한 위젯 가능.
- ·tools_allowed + nesy.invoke 로 위젯 안 버튼이 마도서 함수 직접 호출 가능 (양방향).
- ·iframe 은 격리 (origin "null") — 위젯 안에서 쿠키·플랫폼 API 호출 금지.