From 291f038e598a233d1758b9653aebca51d9fe92f8 Mon Sep 17 00:00:00 2001
From: fanghanjun <17737663888@163.com>
Date: Thu, 16 Apr 2026 10:05:15 -0700
Subject: [PATCH] docs(core): clarify edit/write tool boundaries vs specialised
 tools
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The generic edit and write tools were described abstractly. Spell out
when to reach for specialised tools instead — patch_chapter_text for
chapter text, write_truth_file for canonical truth files,
revise_chapter for chapter revisions — so the agent stops overwriting
chapters or truth files with the generic tools.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 packages/core/src/agent/agent-system-prompt.ts |  8 ++++----
 packages/core/src/agent/agent-tools.ts         | 10 ++++++----
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/packages/core/src/agent/agent-system-prompt.ts b/packages/core/src/agent/agent-system-prompt.ts
index ba76cbf0..a8469a34 100644
--- a/packages/core/src/agent/agent-system-prompt.ts
+++ b/packages/core/src/agent/agent-system-prompt.ts
@@ -82,8 +82,8 @@ export function buildAgentSystemPrompt(bookId: string | null, language: string):
 - **write_truth_file** — 整文件覆盖真相文件（story_bible、volume_outline、book_rules、current_focus 等）
 - **rename_entity** — 统一改角色/实体名
 - **patch_chapter_text** — 对已有章节做局部定点修补
-- **edit** — 通用精确字符串替换编辑
-- **write** — 新建或整文件覆盖写入
+- **edit** — 在设定文件里做精确字符串替换（章节正文请用 patch_chapter_text）
+- **write** — 新建文件，或者重写整个文件（已有内容会被覆盖；真相文件优先用 write_truth_file，章节修订用 revise_chapter）
 - **grep** — 搜索内容（如"哪一章提到了某个角色"）
 - **ls** — 列出文件或章节
 
@@ -131,8 +131,8 @@ export function buildAgentSystemPrompt(bookId: string | null, language: string):
 - **write_truth_file** — Replace a canonical truth file in story/
 - **rename_entity** — Rename a character or entity across the book
 - **patch_chapter_text** — Apply a local deterministic patch to a chapter
-- **edit** — Generic exact string replacement editor
-- **write** — Create or fully overwrite a file
+- **edit** — Exact string replacement on setting files (use patch_chapter_text for chapter text)
+- **write** — Create a new file, or fully replace an existing file's content (prefer write_truth_file for canonical truth files, revise_chapter for chapter revisions)
 - **grep** — Search content across chapters
 - **ls** — List files or chapters
 
diff --git a/packages/core/src/agent/agent-tools.ts b/packages/core/src/agent/agent-tools.ts
index d1a2a61f..9a061a67 100644
--- a/packages/core/src/agent/agent-tools.ts
+++ b/packages/core/src/agent/agent-tools.ts
@@ -393,8 +393,9 @@ export function createEditTool(projectRoot: string): AgentTool<typeof EditParams
   return {
     name: "edit",
     description:
-      "Edit a file using exact string replacement. " +
-      "old_string must appear exactly once in the file. Path is relative to books/.",
+      "Edit a file under books/ via exact string replacement. " +
+      "old_string must appear exactly once in the file. " +
+      "For chapter text use patch_chapter_text; for canonical truth files (story_bible/volume_outline/book_rules/current_focus) prefer write_truth_file.",
     label: "Edit File",
     parameters: EditParams,
     async execute(
@@ -436,8 +437,9 @@ export function createWriteFileTool(projectRoot: string): AgentTool<typeof Write
   return {
     name: "write",
     description:
-      "Create a new file or overwrite an existing file. " +
-      "Path is relative to books/. Parent directories are created automatically.",
+      "Create a new file, or fully replace an existing file's content under books/. " +
+      "Parent directories are created automatically. Existing content is overwritten silently — " +
+      "for canonical truth files prefer write_truth_file; for chapter revisions use revise_chapter.",
     label: "Write File",
     parameters: WriteFileParams,
     async execute(