구조화 편집 도구(update_*)

한 줄로: update_* 도구로 외부 AI 도구가 비트 보드, 연표, 대본, 관계도, 세계 지도를 고치되, 자기가 보지 못한 부분까지 날려 버리지 않게 하는 방법입니다.

이 글이 해결하는 문제

산문 파일은 통째로 다시 써도 됩니다. AI가 .md 전체를 읽었으니 전체를 돌려보낼 수 있고, 최악의 경우라고 해야 글이 마음에 안 드는 정도입니다. 버전 기록에서 되돌리면 그만입니다.

구조화 파일에는 그 안전망이 없습니다. .beats 한 장에는 막과 비트만 있는 게 아니라 작가가 직접 끌어다 놓은 챕터 카드가 들어 있습니다. .map 한 장에는 노드와 관계선, 그룹 상자, 그리고 각 노드가 캔버스 어디에 놓여 있는지까지 들어 있습니다. AI에게 JSON을 통째로 돌려 달라고 하는 것은, 본 적도 없는 부분까지 만들어서 돌려 달라는 뜻입니다. AI는 시키는 대로 합니다. 그리고 실패가 조용합니다. 파일은 멀쩡히 열리는데 작가의 작업만 한 덩어리 사라져 있습니다.

그래서 4.0 서버는 이 다섯 확장자에 대해 파일 통째 쓰기를 닫았습니다. write_file, edit_file, append_to_file은 모두 거부되고, 그 자리를 한 번에 한 가지 작업만 처리하는 필드 단위 도구가 대신합니다.

확장자	도구	작업
.beats 비트 보드	update_beat_board	add_act / update_act / remove_act / add_beat / update_beat / remove_beat / move_beat
.timeline 연표	update_timeline	add_entry / update_entry / remove_entry / set_config
.script 대본	update_script	add_scene / update_scene_heading / remove_scene / add_element / update_element / remove_element
.map 관계도	update_relationship_map	add_node / update_node / move_node / remove_node / add_edge / update_edge / remove_edge / add_group / update_group / remove_group / set_meta
.geomap 세계 지도	update_world_map	add_place / update_place / add_label / update_label / remove_element / add_river / add_border / paint_region / set_meta

이 표는 외울 필요도 없고, 최종 근거로 삼아서도 안 됩니다. get_capabilities가 이 서버가 지금 실제로 받아들이는 목록을 돌려줍니다. 가이드와 글쓰기 스킬을 참고하십시오.

어느 것에나 적용되는 규칙

파일부터 읽으십시오. 보내는 id는 전부 그때 읽은 결과에서 나와야 합니다. 기억에 의존해 다시 타이핑하지 말고, 지어내지도 마십시오. 없는 id를 보내면 거부되는데, 거부 메시지가 진짜 id 목록을 함께 돌려줍니다. 그래서 틀린 추측의 대가는 왕복 한 번이지 작가의 데이터가 아닙니다.

한 번에 한 작업. 각 작업은 자기 인자만 받습니다. 다른 작업에 속한 필드를 섞어 보내면 조용히 무시되는 게 아니라 거부됩니다.

op_ref는 같은 배치 안에서만 이어집니다. 어떤 작업이 만들어 낼 대상에 op_ref: "A2"라는 이름표를 달아 두면, 같은 배치의 뒤쪽 작업이 "@A2"로 그것을 가리킬 수 있습니다. 뒤에서 앞으로만 가리킬 수 있고, 그 배치 안에서만 유효합니다. 다음 호출에는 진짜 id가 필요한데, 그 id는 직전 응답의 applied에 들어 있습니다.

배치는 전부 아니면 전무입니다. 작업 하나가 실패하면 아무것도 기록되지 않습니다. "어디까지 진행됐을까"를 추론할 일이 없습니다. 한 번의 호출에 작업은 최대 200개이며, 그보다 많으면 나누라는 안내와 함께 거부됩니다.

전체 예시

update_relationship_map({
  "book_token": "bk_...",
  "path": "세계관/인물 관계도.map",
  "intent": "온온을 배조 옆에 배치하고 두 사람의 동료 관계를 추가",
  "operations": [
    { "op": "add_node", "label": "온온", "op_ref": "N1",
      "position": { "near_id": "n-peizhao", "direction": "right" } },
    { "op": "add_edge", "source_id": "n-peizhao", "target_id": "@N1", "label": "동료" }
  ]
})

intent는 주석이 아닙니다. 이 값이 그대로 커밋의 이름이 되고, 몇 주 뒤 작가가 버전 기록에서 읽게 되는 그 한 줄이 됩니다. 이 배치가 무엇을 했는지 쓰십시오. "일괄 업데이트"는 그런 문장이 아니고, 문단만큼 긴 설명은 아무것도 기록되기 전에 반려됩니다.

응답에는 세 가지가 담겨 옵니다. 새로 만든 대상의 진짜 id, 딸려서 함께 일어난 일(노드를 지우면 거기 붙은 선도 함께 지워집니다), 그리고 커밋 토큰입니다. 가운데 항목은 작가에게 그대로 전달하십시오. 작가가 화면에서 보게 되지만 요청한 적은 없는 변화이기 때문입니다.

여기에는 검토 패널이 없습니다

앱 안에서 AI 코치가 구조화 파일을 고치면, 그 변경은 먼저 점선 카드로 떠서 작가가 「반영」이나 「건너뛰기」를 눌러야 확정됩니다(AI 수정 사항 검토하기 참고).

MCP에는 그 단계가 없습니다. 외부 도구에서 보낸 배치 하나가 곧 커밋이고, 곧바로 버전 기록에 들어갑니다. 그러니 손대기 전에 무엇을 할지 말하고, 손댄 뒤에 무엇을 했는지 말하십시오. 보내 놓고 "이렇게 해도 괜찮을까요"라고 묻지는 마십시오. 되돌리기는 버전 기록에서 합니다. 직접 쓴 문단을 되돌릴 때와 똑같습니다. 게다가 버전 기록에는 「외부 도구에서 온 커밋」이라는 표시가 붙지 않습니다. 한 줄에 보이는 것은 메시지와 시각과 글자 수뿐입니다. 적어 보낸 intent가 유일한 단서이니, 그 한 줄에 내용이 있어야 하는 이유가 여기 있습니다.

구조화 파일 새로 만들기

create_file은 이 다섯 확장자에도 동작합니다. 다만 보낸 내용은 무시됩니다. 서버가 빈 골격을 만들고, 파일 이름이 그 안에 든 문서의 제목이 됩니다. 응답에도 내용이 교체됐다고 분명히 적혀 옵니다.

그래서 순서는 두 단계입니다. 먼저 create_file로 빈 파일을 만들고, 그다음 update_* 배치로 한 덩어리씩 채워 넣습니다.

누가 쓸 수 있는가

이 다섯 종류에 쓰는 일은, 그리고 지우는 일도, Slima 구독 플랜에 속합니다. 무료 계정으로 호출하면 403이 오고 오류 코드는 SUBSCRIPTION_REQUIRED입니다. 메시지에는 읽기가 제한되지 않는다는 점이 함께 적혀 옵니다. 파일을 읽고, 어떻게 고치면 좋을지 말로 설명하십시오. 그러면 작가가 앱에서 직접 고치거나, 구독한 뒤 AI에게 맡길 수 있습니다.

파일 종류별로 알아 둘 것

.map 관계도. 위치는 내용이지 레이아웃이 아닙니다. update_node는 아무것도 움직이지 않습니다. 옮기는 일은 move_node가 합니다. 그래야 "그 사람을 이쪽 옆으로 옮겼다"가 눈에 보이고 되돌릴 수 있는 하나의 변경이 됩니다. 좌표를 직접 계산하기보다 {near_id, direction}을 쓰십시오. 기존 노드는 밀려나지 않고, 최종 좌표는 응답에 실려 옵니다. 그룹 상자는 member_ids에서 계산되므로 폭·높이·좌표는 절대 보내지 마십시오.

.geomap 세계 지도. 좌표 단위는 픽셀이 아니라 격자 칸입니다(x 0–519, y 0–363). read_file은 세 장의 지형 격자를 한 줄 설명으로 바꿔서 돌려줍니다. 기계용 인코딩이라 읽을 것이 없기 때문입니다. paint_region도 칸 단위로 동작합니다. 지형에는 되돌리기가 없으니 고칠 때는 위에 덧칠하십시오. remove_element는 어떤 요소 id든 받습니다(pl_ 장소, lb_ 라벨, rv_ 강, bd_ 경계). 장소를 옮길 때는 update_place를 쓰고, 지웠다가 다시 추가하지 마십시오.

.timeline 연표. 항목을 챕터에 연결하는 일은 여기서 하지 않습니다. 연결 필드를 보내면 이유와 함께 거부됩니다.

.beats 비트 보드. 막을 지워도 그 안의 비트는 지워지지 않습니다. 미배정 상태가 되고, 몇 개가 그렇게 됐는지 응답이 알려 줍니다.

.script 대본. 한 화에 한 파일입니다. 신 제목(내부·외부, 장소, 시간대)은 update_scene_heading으로, 신 안의 액션·인물·대사·지문·전환·샷은 add_element / update_element로 다룹니다.

관련 문서

• Docs: 파일 조작 도구
• Docs: MCP가 파일 종류별로 할 수 있는 일
• Docs: 구조화 파일 보호
• Docs: 비트 보드란 무엇이고 언제 쓰는가
• Docs: 연표란 무엇인가
• Docs: 세계 지도란 무엇인가