構造化編集ツール（update_*）

ひとことで：update_*ツールを使って、外部のAIツールにビートボード・年表・脚本・関係マップ・世界地図を編集させる方法です。AIが見ていない部分を落とさずに済みます。

これで解決すること

散文のファイルは丸ごと書き直せます。AIは.mdの全部を読んでいるので、全部を返せます。いちばん悪くても文章が下手になるだけで、バージョン履歴から戻せます。

構造化ファイルには、そのセーフティーネットがありません。1つの.beatsの中には幕とビートがあり、作者がドラッグして置いた実際の章のカードもあります。1枚の.mapにはノードと関係の線とグループの枠、それに各ノードがキャンバスのどこに座っているかが入っています。JSONを丸ごと送り返してくれとAIに頼むのは、見せていない部分まで送り返してくれと頼むのと同じです。AIはそのとおりにやろうとします。そして失敗は静かです。ファイルはちゃんと開きます。ただ、作者の仕事がひとかたまり減っています。

そこで4.0のサーバーは、この5つの拡張子について丸ごとの書き込みを閉じました。write_file、edit_file、append_to_fileはどれも拒否されます。代わりに、1回に1操作ずつ進めるフィールド単位のツールが型ごとに1つ用意されています。

拡張子	ツール	操作
.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が一覧で返ってきます。だから間違えても失うのは1往復だけで、作者のデータには届きません。

1つの変更につき1操作。 それぞれの操作は自分の引数しか受け取りません。別の操作に属するフィールドを混ぜると、黙って無視されるのではなく拒否されます。

op_refは同じバッチの中だけでつながる。 操作が作ったものにop_ref: "A2"という札を付けておくと、同じバッチのあとの操作が"@A2"でそれを指せます。参照できるのは前に戻る向きだけ、有効なのはそのバッチの中だけです。次の呼び出しには本物のidが要りますが、それは前回の返答のappliedに入っています。

バッチは全部通るか、何も残らないか。 1つでも失敗すれば何も書き込まれません。「どこまで進んだのか」を推理する必要はありません。1回の呼び出しで運べる操作は最大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はコメントではありません。これがこのコミットの名前になります。つまり、何週間かあとに作者がバージョン履歴で読む1行です。このバッチが何をしたのかを書いてください。「一括更新」はその1行ではありませんし、長すぎる文章は何も書き込まれる前に拒否されます。

返ってくるものは3つです。作ったものの本物のid、巻き添えで起きたこと（ノードを1つ消すと、その線も一緒に消えます）、そしてコミットのトークン。真ん中の1つは作者に伝えてください。頼んでいないのに画面に出てくる変化は、それだからです。

ここにレビューの一段はありません

アプリの中でAI コーチが構造化ファイルを編集すると、変更はまず破線のカードとして現れて、作者が「採用」か「見送る」を選びます（AIの提案をレビューする）。

MCPにその一段はありません。 外部のツールから送ったバッチはそのままコミットになり、すぐバージョン履歴に入ります。ですから、手を動かす前に何をするかを言い、動かしたあとに何をしたかを言ってください。送ってから「これでいいですか」と聞くのは順番が逆です。取り消しはバージョン履歴から。自分で書いた段落を戻すのと同じです。しかもバージョン履歴には「外部ツールから来たコミット」という印は付きません。1行に出るのはメッセージと時刻と文字数だけです。書いたintentが唯一の手がかりで、だからこそ中身のある1行にする必要があります。

構造化ファイルを新しく作る

create_fileはこの5つの拡張子でも動きます。ただし送った内容は無視されます。サーバーは空の骨組みを書き、ファイル名がそのままファイルの中の文書名になります。内容が差し替わったことは返答にはっきり書かれます。

つまり2段構えです。まずcreate_fileで空のものを作り、そのあとupdate_*のバッチで埋めていきます。

誰が使えるか

この5つの型への書き込み、そして削除は、Slimaの有料プランの機能です。Freeのアカウントから呼ぶとSUBSCRIPTION_REQUIREDというコードの403が返り、読み取りには制限がないことがメッセージに書かれています。ファイルを読んで、こう直したらどうかを言葉で伝えれば、作者がアプリの中で自分で直せます。契約すれば、AIが直接直せます。

型ごとに知っておきたいこと

.map関係マップ。 位置はレイアウトではなく内容です。update_nodeは何も動かしません。動かすのはmove_nodeで、そのおかげで「彼女を彼の隣に移した」ことが、それ自体で見えて戻せる1つの変更になります。座標を自分で計算するより{near_id, direction}を使ってください。既存のノードが押しのけられることはなく、最後にどこへ落ちたかは返答に入っています。グループの枠はmember_idsから計算されるので、幅や高さや座標は絶対に送らないでください。

.geomap世界地図。 座標はピクセルではなくマス目です（xは0〜519、yは0〜363）。read_fileは3枚の地形グリッドを1行の説明に置き換えて返します。機械向けの符号化なので、読む必要はありません。paint_regionもマス目で動きます。地形にやり直しはないので、直すときは上から塗ってください。remove_elementはどの要素のidでも受け取ります（pl_地点、lb_ラベル、rv_川、bd_境界）。地点を動かすときはupdate_placeで。消してから足し直すのはやめてください。

.timeline年表。 出来事を章に紐づけるのは、ここの仕事ではありません。紐づけ用のフィールドを送ると、理由とともに拒否されます。

.beatsビートボード。 幕を1つ消しても、その中のビートは消えません。どの幕にも属さない状態になり、いくつそうなったかが返答に書かれます。

.script脚本。 1話につき1ファイルです。シーンの見出し（屋内か屋外か、場所、時間帯）はupdate_scene_heading、シーンの中の動作・人物・台詞・ト書き・トランジション・ショットはadd_element／update_elementで扱います。

関連

• Docs：ファイル操作ツール
• Docs：MCPがファイル種別ごとにできること
• Docs：構造化ファイルの保護
• Docs：ビートボードとは何か、いつ使うか
• Docs：年表（.timeline）とは
• Docs：世界地図ファイル（.geomap）とは