檔案操作工具

一句話：這篇是「對著路徑做事」那一組檔案工具的參考——讀、局部改、整檔覆寫、新建、刪除、追加、搜尋。

這解決什麼問題

MCP 真正動到稿子的地方就是這一組。它們的共同點是都吃一個 path，而且每一次寫入都會產生一顆 commit——沒有存檔這個步驟，作者會在版本歷史裡看到你的 commit 跟他自己的並排。

工具	做什麼	參數
read_file	讀一個檔	book_token、path
edit_file	找一段字換掉	path、old_string、new_string、replace_all?、commit_message?
write_file	整檔覆寫	path、content、commit_message?
create_file	建一個新檔	path、content?、content_type?、commit_message?
delete_file	刪一個檔或資料夾	path、recursive?、commit_message?
append_to_file	接在檔案結尾	path、content、commit_message?
search_content	全文搜尋	query、file_types?、limit?、include_structured?

想「看見」一張關係圖是另一支工具的事，見讓 AI 看見關係圖。

改稿優先用 edit_file

它是最常用的一支，也是唯一在「作者正在改同一個檔」時會明確失敗而不是覆蓋掉的寫法。

比對與替換是在伺服器端、在鎖裡面做的，所以回報的替換次數就是真的落地的次數，不是本機猜的。要找的那段字不存在、或出現多次而無法判斷時，呼叫會失敗並告訴你下一步——照它說的改，不要拿同一組參數再送一次。

replace_all 預設是 false，只換第一處。new_string 傳空字串就是刪掉那段。

write_file 會把整個檔換掉

適合真的要全面重寫的時候。作者剛打的字會一起消失，所以能用 edit_file 就不要用它。

create_file：content_type 決定字數算不算

要寫一章就傳 content_type: "manuscript"。 不指定的話，新檔會繼承所在資料夾，放在最外層則預設是 reference——那些字不會進作者的字數、連勝與稿件匯出。可選值是 manuscript、reference、character、location、storyline。

路徑上不存在的資料夾會自動建出來，不必先建目錄。詳見稿件與參考資料。

delete_file：非空的資料夾要說出口

刪一個裡面還有東西的資料夾，預設會被拒絕，訊息會告訴你裡面有幾個。確定要整棵刪就帶 recursive: true。

這道防護擋的是一個真實的意外：只刪掉資料夾那一筆，裡面的檔案會失去父層，app 於是把整棵子樹攤在書的最外層——作者看到檔案散了一地，而伺服器回的是成功。

刪除也是一顆 commit，所以檔案還在版本歷史裡，從那裡還原得回來，見還原版本或單一檔案。

search_content：三個參數，沒有 scope

search_content({
  "book_token": "bk_...",
  "query": "熔字爐",
  "file_types": ["md"],
  "limit": 20
})

file_types 吃副檔名，帶不帶點都可以（["md", ".txt"]）。

在 4.0 的書上，file_types 比你想的重要。 結構化檔案的原始 JSON 也會被搜，所以查 name、title 這種普通詞可能命中一整頁欄位名。要只搜散文就明講 file_types: ["md"]。舊的劇本工作室書反過來：那邊的結構化檔案預設被排除，要加 include_structured: true。詳見哪些工具在特定檔案上會不一樣。

哪些檔案這一組工具動不了

• 散文檔（.md / .markdown / .txt）：這一組全部可用。
• 五種結構化檔（.map / .beats / .timeline / .script / .geomap）：write_file、edit_file、append_to_file 一律被拒，而拒絕訊息會指名該用哪一支 update_*。兩個例外要記住：create_file 建得出來，但你送的內容會被忽略（伺服器產一份空骨架）；delete_file 刪得掉（刪除不看型別政策，只看方案）。寫入與刪除都屬於訂閱方案。
• .character / .location / .json / .yaml：完全不能寫，也沒有欄位級的替代路徑。

要改結構化檔就走結構化編輯工具。權威的清單永遠是 get_capabilities 回的那張表。

commit_message 值得填

不填會自動產生一句，但作者事後在版本歷史裡讀到的就是那一句。寫「這一次改了什麼」比「Update file」有用得多。

相關

• Docs：結構化編輯工具
• Docs：讓 AI 看見關係圖
• Docs：MCP 對每種檔案能做什麼
• Docs：寫入被拒：怎麼處理
• Docs：自動版本規則