哪些工具在特定檔案上會不一樣

一句話：這篇整理哪些工具在特定檔案或特定書上跟你預期不一樣，以及那些差異各自的補救。

這解決什麼問題

大部分 MCP 工具對每個檔案的行為都一樣。下面這些不是。它們不會報錯，只是回一個你沒預期的東西——而沒預期到的成功，比明確的失敗難查得多。

read_file：兩種檔案回的東西不一樣

.map 關係圖回的是原始 JSON：節點 id、像素座標、群組成員清單。技術上沒問題，實務上很難用。改用 view_relationship_map，它會回一張圖加一段把每個角色與每條關係都列出來的摘要，見讓 AI 看見關係圖。

.geomap 世界地圖回的內容裡，三張地形網格會被換成一句說明。那不是被截斷，是刻意的：地形是機器編碼的，讀它沒有意義，而 paint_region 那些操作用的是格子座標。

search_content：搜到的東西看書的年紀

4.0 的書：所有檔案都會被搜，包含結構化檔案的原始 JSON。所以查 name、title 這種普通詞，命中的可能都是欄位名。要只搜散文就帶 file_types: ["md"]。

舊的劇本工作室書：反過來，*.character、*.scene、*.storyline、*.note、*.location 與 .script_studio/ 底下的 *.json 預設被排除——它們的原始 JSON 對全文搜尋只是雜訊。要一起搜就加 include_structured: true。

semantic_search：只看得到進了 commit 的東西

語意檢索是從書的最新一顆 commit 建索引的。作者剛在 app 裡打完、還沒落成一顆 commit 的段落，這裡搜不到。

很大又從來沒建過索引的書會轉去背景建，這一次搜尋會回空的——那是「還沒建好」，不是「沒有」。等一下再搜。完整說明見語意檢索與全文搜尋。

analyze_chapter：對準散文，不要對準結構化檔

舊的劇本工作室書整本不支援。 呼叫會直接被拒，訊息會叫你用 app 內的分析功能。

4.0 的書上要自己注意。 沒有東西會阻止你把 file_path 指向一份 .script 或 .beats，而那樣做等於請一位讀者讀一份 JSON 給你聽——它會照做，報告會很怪。Beta Reader 要對準 .md 稿件檔。

get_writing_stats：四種型別一律算 0

.map、.beats、.timeline、.geomap 的字數固定是 0——它們不是作者寫的散文。.script 相反，它算場景裡的字，而且會進每日字數與連勝。

所以幫作者整理一張年表不會在他的統計上留下假成績，而寫一集劇本會。

create_file：對五種結構化副檔名，你的內容會被忽略

伺服器會產一份空骨架，檔名成為文件裡的名字，回覆會明講內容被換掉了。想放進去的東西要用 update_* 一批一批填，見結構化編輯工具。

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

刪一個裡面還有東西的資料夾，預設會被拒（FOLDER_NOT_EMPTY）。確定要整棵刪就再送一次並帶 recursive: true。

這道防護擋的是一個真實的意外：只刪掉那一筆會讓子樹的檔案全部散到書的最外層，而伺服器回 200。

get_chapter 與 read_file：知道路徑就用後者

get_chapter 吃得下一個裸檔名（第一章 抄書娘.md），也吃得下不完整的路徑，找不到還會把可用的檔案列給你。代價是多幾次查詢。

路徑已經確定的時候，read_file 做的是同一件事，而且更直接。

相關

• Docs：檔案操作工具
• Docs：語意檢索與全文搜尋
• Docs：讓 AI 看見關係圖
• Docs：MCP 對每種檔案能做什麼
• Docs：AI Beta Reader 工具