dominds 1.27.6 → 1.28.0

package/dist/tools/prompts/ws_mod/en/scenarios.md

@@ -13,32 +13,26 @@
 
 ## Scenario Quick Reference
 
-| Scenario                        | Recommended Tools                                        | Description                                 |
-| ------------------------------- | -------------------------------------------------------- | ------------------------------------------- |
-| I want to view file content     | `read_file`                                              | With line number decoration, optional range |
-| I want to search and locate     | `ripgrep_snippets`                                       | Locate anchors by keywords                  |
-| I want to create a new file     | `create_new_file`                                        | Allows empty content                        |
-| I want to overwrite entire file | `overwrite_entire_file`                                  | Requires providing old file snapshot        |
-| I want to make small changes    | `prepare_file_range_edit` + `apply_file_modification`    | By line number range                        |
-| I want to append to end         | `prepare_file_append` + `apply_file_modification`        | Append to EOF                               |
-| I want to insert after a line   | `prepare_file_insert_after` + `apply_file_modification`  | Insert by anchor                            |
-| I want to insert before a line  | `prepare_file_insert_before` + `apply_file_modification` | Insert by anchor                            |
-| I want to replace a block       | `prepare_file_block_replace` + `apply_file_modification` | Double-anchor block replacement             |
+| Scenario                        | Recommended Tools       | Description                                      |
+| ------------------------------- | ----------------------- | ------------------------------------------------ |
+| I want to view file content     | `read_file`             | With line number decoration, optional range      |
+| I want to search and locate     | `ripgrep_snippets`      | Locate anchors by keywords                       |
+| I want to create a new file     | `create_new_file`       | Allows empty content                             |
+| I want to overwrite entire file | `overwrite_entire_file` | Requires providing old file snapshot             |
+| I want to make small changes    | `file_range_edit`       | Direct precise line range edit                   |
+| I want to append to end         | `file_append`           | Append to EOF                                    |
+| I want to insert after a line   | `file_insert_after`     | Insert by anchor                                 |
+| I want to insert before a line  | `file_insert_before`    | Insert by anchor                                 |
+| I want to replace a block       | `file_block_replace`    | Double-anchor block replacement                  |
+| I want to edit/move large text  | `pad_*` + file tools    | Prepare a pad, then write via `pad_id/pad_range` |
 
 ## Copy-Paste Ready Examples
 
 ### Append to End
 
 ```text
-Call the function tool `prepare_file_append` with:
-{ "path": "notes/prompt.md", "content": "## Tools\n- Use prepare_* + apply_file_modification for incremental edits.\n" }
-```
-
-Then in the next round:
-
-```text
-Call the function tool `apply_file_modification` with:
-{ "hunk_id": "<hunk_id>" }
+Call the function tool `file_append` with:
+{ "path": "notes/prompt.md", "content": "## Tools\n- Use file_range_edit for precise ranges; use file_block_replace for anchor-delimited blocks.\n" }
 ```
 
 ### Line Range Replace
@@ -46,28 +40,28 @@ Call the function tool `apply_file_modification` with:
 `content` can be empty string to indicate deletion:
 
 ```text
-Call the function tool `prepare_file_range_edit` with:
+Call the function tool `file_range_edit` with:
 { "path": "README.md", "range": "10~12", "content": "New line 10\nNew line 11\n" }
 ```
 
 ### Insert After Anchor
 
 ```text
-Call the function tool `prepare_file_insert_after` with:
+Call the function tool `file_insert_after` with:
 { "path": "config.yaml", "anchor": "database:", "content": "  host: localhost\n  port: 5432\n" }
 ```
 
 ### Insert Before Anchor
 
 ```text
-Call the function tool `prepare_file_insert_before` with:
+Call the function tool `file_insert_before` with:
 { "path": "config.yaml", "anchor": "---", "content": "# Configuration\n" }
 ```
 
 ### Double-Anchor Block Replace
 
 ```text
-Call the function tool `prepare_file_block_replace` with:
+Call the function tool `file_block_replace` with:
 { "path": "docs/spec.md", "start_anchor": "## Start", "end_anchor": "## End", "content": "NEW BLOCK LINE 1\nNEW BLOCK LINE 2\n" }
 ```
 
@@ -92,6 +86,20 @@ Call the function tool `overwrite_entire_file` with:
 { "path": "README.md", "content": "# New Content\n...", "known_old_total_lines": 42, "known_old_total_bytes": 1234 }
 ```
 
+### Large Body via Pad, Then File Write
+
+```text
+Call the function tool `pad_load_file_range` with:
+{ "pad_id": "rewrite_doc", "path": "docs/spec.md", "intent": "Rewrite docs/spec.md structure and wording", "completion": "Delete after writing back and verifying", "source_note": "Loaded from docs/spec.md full file" }
+```
+
+Then refine against the line-numbered reminder body with `pad_edit` / `pad_insert` / `pad_delete_range`, and finally:
+
+```text
+Call the function tool `overwrite_entire_file` with:
+{ "path": "docs/spec.md", "pad_id": "rewrite_doc", "known_old_total_lines": 42, "known_old_total_bytes": 1234, "content_format": "markdown" }
+```
+
 ## Tool Selection Decision Tree
 
 1. **Do you want to create a new file?**
@@ -99,13 +107,18 @@ Call the function tool `overwrite_entire_file` with:
    - No → Continue
 
 2. **Do you want to completely overwrite old content?**
-   - Yes → `read_file` to get snapshot → `overwrite_entire_file`
+   - Yes, and body is large → `read_file` to get snapshot → prepare a pad with `pad_write` or `pad_load_file_range` → `overwrite_entire_file({ pad_id })`
+   - Yes, and body is small → `read_file` to get snapshot → `overwrite_entire_file({ content })`
+   - No → Continue
+
+3. **Are you handling a large body or a body that needs multiple refinement steps?**
+   - Yes → prepare a pad with `pad_write` or `pad_load_file_range`, fill `intent/completion/source_note`, then use the target file tool's `pad_id/pad_range`
    - No → Continue
 
-3. **Do you know the specific line numbers?**
-   - Yes → `prepare_file_range_edit` → `apply_file_modification`
+4. **Do you know the specific line numbers?**
+   - Yes → `file_range_edit`
    - No → Continue
 
-4. **Can you locate by anchor?**
-   - Yes → Choose `prepare_file_insert_after/before` or `prepare_file_block_replace` based on scenario
+5. **Can you locate by anchor?**
+   - Yes → Choose `file_insert_after/before` or `file_block_replace` based on scenario
    - No → Consider using `ripgrep_snippets` to locate anchors first

package/dist/tools/prompts/ws_mod/en/tools.md

@@ -27,7 +27,7 @@
 
 ### 2.1 create_new_file
 
-Create a new file (no prepare/apply), allows empty content.
+Create a new file, allows empty content.
 
 - **Design intent**: Solve "creating empty/new files should not force incremental editing"; also avoid misusing `overwrite_entire_file` (its semantics is to overwrite existing files)
 - **Behavior**: If target already exists, reject (`FILE_EXISTS`/`NOT_A_FILE`); if not exists, create parent directories and write content
@@ -36,14 +36,15 @@ Create a new file (no prepare/apply), allows empty content.
 
 ### 2.2 overwrite_entire_file
 
-Full file overwrite (**no prepare/apply**).
+Full file overwrite (writes immediately).
 
 - **Usage suggestion**: First use `read_file` to get `total_lines/size_bytes` as input for `known_old_total_lines/known_old_total_bytes`
-- **Design intent**: For "new content is small (e.g., <100 lines)" or "clearly a reset/generated artifact" scenarios; prefer prepare/apply for other cases
+- **Design intent**: For "new content is small (e.g., <100 lines)" or "clearly a reset/generated artifact" scenarios; for large bodies, prepare a pad first and pass `pad_id/pad_range`
+- **Source**: pass small bodies directly with `content`; pass large bodies with `pad_id/pad_range`
 - **Guardrail (required)**: Must provide `known_old_total_lines/known_old_total_bytes` (old file snapshot) to execute; reject if reconciliation doesn't match
 - `content_format`: Optional text hint; any non-empty label is accepted (for example `yaml`, `toml`, `json`, `markdown`)
-- **Guardrail (default reject)**: If content looks like diff/patch and `content_format=diff|patch` is not explicitly declared, default reject and guide to use prepare/apply (avoid mistakenly writing patch text into file)
-- **Limitation**: Does not create files; for creating empty/new files use `create_new_file`; for creating new file with non-empty initial content use `prepare_file_append create=true` → `apply_file_modification`
+- **Guardrail (default reject)**: If content looks like diff/patch and `content_format=diff|patch` is not explicitly declared, default reject; use direct edit tools for actual edits, or declare diff/patch only when writing patch text literally
+- **Limitation**: Does not create files; for creating empty/new files use `create_new_file`
 
 ### 2.3 create_symlink / rm_symlink
 
@@ -54,77 +55,73 @@ Create or remove a symlink path.
 - **Removal**: `rm_symlink` removes the link path itself without touching the target, and can remove broken symlinks
 - **Output**: Success and failure outputs are YAML with `mode: create_symlink` / `mode: rm_symlink`
 
-## 3. Incremental Edits (prepare-first)
+## 3. Incremental Edits (direct edit)
 
-- `prepare_file_range_edit`: Preview replace/delete/append by line range (append via `N~` where `N=(last_line+1)`)
-- `prepare_file_append`: Preview append to EOF (optional `create=true|false`)
-- `prepare_file_insert_after` / `prepare_file_insert_before`: Preview insertion by anchor line (prepare phase strictly handles ambiguity; if anchor appears multiple times, must specify `occurrence`)
-- `prepare_file_block_replace`: Preview block replacement by start/end anchors (configurable `include_anchors` / `require_unique` / `strict` / `occurrence`, etc.)
+- `file_range_edit`: Directly replace/delete/append by precise line range (append via `N~` where `N=(last_line+1)`)
+- `file_append`: Directly append to EOF, optionally with `create=true|false`
+- `file_insert_after` / `file_insert_before`: Direct insertion by anchor line; if the anchor appears multiple times, specify `occurrence`
+- `file_block_replace`: Direct block replacement by start/end anchors (configurable `include_anchors` / `require_unique` / `strict` / `occurrence`, etc.)
   - `include_anchors=true` (default): Keep start/end anchor lines, only replace content between them
-  - `include_anchors=false`: Replacement range includes start/end anchor lines (will delete anchor lines and replace with new content)
-- `apply_file_modification`: The sole apply, can apply hunks from any `prepare_*` above (range/append/insert/block_replace)
+  - `include_anchors=false`: Replacement range includes start/end anchor lines
+- `prepare_occurrence_replace` / `apply_occurrence_replace`: Two-step literal occurrence replacement in one file, designed for multi-point same-literal replacement. This is the only prepare/apply path in ws_mod; direct file tools are usually clearer for one-off/single-block edits. If only one occurrence is selected, prepare succeeds but returns `notice: NOT_MULTI_OCCURRENCE`.
+- `create_new_file` / `overwrite_entire_file` / `file_range_edit` / `file_append` / `file_insert_*` / `file_block_replace` all support `content` and `pad_id/pad_range` sources; use direct `content` for small bodies and pad sources for large bodies
+- `pad_load_file_range({ pad_id, path })` can omit `range`, which defaults to the whole file; pass `range` to load only a file slice
+- For review output, pass `preview: true, show_diff: true` to the direct tool; otherwise it writes immediately and does not echo body text
 
-## 4. YAML Output Contract
+## 4. Scratch Pad Tools
+
+- `pad_write`: Create/replace/append/upsert pad body text; supports `intent`, `completion`, `source_note`, and `delete_when_done` metadata. Large bodies can enter a pad, but the first function-call argument still enters history.
+- `pad_load_file_range`: Load a whole file or line range into a pad; omitting `range` means the whole file. Pass `intent` / `completion` / `source_note` explicitly when useful; when `source_note` is omitted, the tool records the file source automatically.
+- `pad_edit` / `pad_insert` / `pad_delete_range`: Modify pad text directly by pad line numbers; the line-numbered reminder body is the editing reference.
+- `pad_copy` / `pad_move`: Copy/move line ranges between pads; when creating a target pad, source metadata is inherited and can be overridden by parameters.
+- `pad_delete`: Delete a pad once it is no longer needed. Pads are temporary workbench state and should be cleaned up after the task.
+
+Successful pad tool results do not echo body text and do not use line/hash stats as the main display; the reminder projection is the authoritative visible body.
+When a file tool succeeds with a pad source, it appends `pad_intent`, `pad_completion`, `pad_source_note`, `pad_delete_when_done`, and `pad_cleanup_suggestion` after the source audit fields; `preview: true` tells the agent to keep the pad, while actual writes should trigger deletion once the completion condition is met.
+
+## 5. YAML Output Contract
 
 > Goal: Scannable under low attention; stable fields for tooling and regression
 
-### 4.1 Plan (Common Fields)
+### 5.1 Direct Write (Common Fields)
 
 - `status: ok|error`
-- `mode: prepare_file_range_edit|prepare_file_append|prepare_file_insert_after|prepare_file_insert_before|prepare_file_block_replace`
+- `mode: file_range_edit|file_append|file_insert_after|file_insert_before|file_block_replace`
 - `path`
-- `hunk_id`, `expires_at_ms`
 - `action: replace|delete|append|insert|block_replace`
 - `normalized.*` (EOF newline analysis)
 - `summary` (1-2 sentences, scannable)
-- Followed by YAML, a ` ```diff ` unified diff (for review)
+- Followed by a unified diff only when `show_diff=true`
 
-### 4.2 Plan (Key Fields by Tool/Action)
+### 5.2 Direct Write (Key Fields by Tool/Action)
 
-- `prepare_file_range_edit`:
-  - `range.input` / `range.resolved.start|end`
-  - `lines.old|new|delta`
-  - `evidence.before|range|after`
-- `prepare_file_append`:
+- `file_append`:
   - `file_line_count_before|after`, `appended_line_count`
   - `blankline_style.file_trailing_blank_line_count` / `content_leading_blank_line_count`
   - `evidence_preview.before_tail|append_preview|after_tail`
-- `prepare_file_insert_*`:
+- `file_insert_*`:
   - `position`, `anchor`, `match`
   - `candidates_count`, `occurrence_resolved`
   - `inserted_at_line`, `inserted_line_count`, `lines.old|new|delta`
   - `blankline_style.*`, `evidence_preview.*`
-- `prepare_file_block_replace`:
+- `file_block_replace`:
   - `start_anchor` / `end_anchor` / `match`
   - `include_anchors` / `require_unique` / `strict`
   - `candidates_count` / `occurrence_resolved`
   - `block_range`, `replace_slice`, `lines.old|new|delta`
   - `evidence_preview.before_preview|old_preview|new_preview|after_preview`
+- `prepare_occurrence_replace` / `apply_occurrence_replace`:
+  - `plan_id`, `find`, `occurrences_found`, `selected_occurrences`, `selected_count`
+  - `file.old_hash|new_hash`, `file.old_total_lines|new_total_lines`
+  - `match_preview` on prepare; `FILE_CHANGED_SINCE_PREPARE` on apply if the file drifted
 
-### 4.3 Apply (Common Fields)
-
-- `status`
-- `mode: apply_file_modification`
-- `path`, `hunk_id`
-- `action`
-- `context_match: exact|fuzz|rejected`
-- `apply_evidence` (required)
-- `summary` - Followed by YAML, unified diff (recalculated based on "current file + parsed target position" at apply time; if `context_match=exact`, matches plan diff)
-
-### 4.4 Apply (Key Fields by Action)
-
-- `append`: `append_range.start|end` + tail previews
-- `insert`: `position` / `anchor` / `inserted_at_line` / `inserted_line_count`
-- `replace|delete` (range): `applied_range.start|end` + `lines.*`
-- `block_replace`: `block_range` / `replace_slice` / `lines.*`
-
-### 4.5 read_file / overwrite_entire_file (Structured Header)
+### 5.5 read_file / overwrite_entire_file (Structured Header)
 
 - `read_file` output starts with YAML header (followed by code block content), which includes:
   - `total_lines` (for reconciliation guardrail: empty file is 0, can be directly used for `overwrite_entire_file.known_old_total_lines`)
 - `overwrite_entire_file` success/failure outputs are both YAML (for programmatic handling and retry)
 
-## 5. Relationship with .minds/
+## 6. Relationship with .minds/
 
-`.minds/` is the core of team configuration and rtws (runtime workspace) memory, and should usually be operated through the `team_mgmt` toolset's mirrored tools (e.g., `team_mgmt_prepare_file_insert_after`, etc.).
-This toolset's "prepare-first + single apply" mental model remains consistent, but path and permission semantics are determined by the team_mgmt tool wrapper layer (see team_mgmt documentation).
+`.minds/` is the core of team configuration and rtws (runtime workspace) memory, and should usually be operated through the `team_mgmt` toolset's mirrored tools (e.g., `team_mgmt_file_insert_after`, etc.).
+This toolset's direct edit mental model remains consistent, but path and permission semantics are determined by the team_mgmt tool wrapper layer (see team_mgmt documentation).

package/dist/tools/prompts/ws_mod/zh/errors.md

@@ -12,33 +12,26 @@
 
 ## 错误分类
 
-| 阶段    | 错误码                    | 说明                          | 解决方案                                             |
-| ------- | ------------------------- | ----------------------------- | ---------------------------------------------------- |
-| prepare | `PATH_REQUIRED`           | 缺少文件路径                  | 提供非空的 rtws 内相对路径                           |
-| prepare | `INVALID_ARGS`            | 工具参数非法                  | 按错误信息修正参数结构                               |
-| prepare | `INVALID_PATH`            | 路径越界或不合法              | 使用 rtws 内的规范化相对路径                         |
-| prepare | `INVALID_FORMAT`          | 修改格式非法                  | 使用所选 prepare 工具要求的格式                      |
-| prepare | `FILE_NOT_FOUND`          | 文件不存在                    | 使用 `create=true` 参数或先创建文件                  |
-| prepare | `CONTENT_REQUIRED`        | 正文为空但该工具需要正文      | 为 insert/append/block_replace 提供 `content`        |
-| prepare | `INVALID_HUNK_ID`         | hunkId 非法                   | 使用非空且不含换行的 hunkId                          |
-| prepare | `WRONG_MODE`              | 既有 hunkId 属于其它模式      | 换用新 hunkId，或使用同一种 prepare 模式             |
-| prepare | `HUNK_ID_CONFLICT`        | hunkId 与活跃 hunk 冲突       | 换用唯一 hunkId                                      |
-| prepare | `ANCHOR_NOT_FOUND`        | 锚点行未找到                  | 检查锚点文本是否正确，或使用 `ripgrep_snippets` 定位 |
-| prepare | `ANCHOR_AMBIGUOUS`        | 锚点有多个匹配                | 指定 `occurrence` 参数来明确是第几个匹配             |
-| prepare | `OCCURRENCE_OUT_OF_RANGE` | occurrence 超范围             | 检查 occurrence 值是否在 `1~candidates_count` 范围内 |
-| apply   | `HUNK_NOT_FOUND`          | hunk 过期/已应用/不存在       | 重新执行 prepare 生成新的 hunk                       |
-| apply   | `WRONG_OWNER`             | hunk 非当前成员规划           | hunk 必须由当前成员生成                              |
-| apply   | `WRONG_MODE`              | hunkId 属于其它模式           | 应用匹配的 hunk 模式，或重新执行 prepare             |
-| apply   | `FILE_NOT_FOUND`          | 文件在 apply 时不存在         | 检查文件是否被删除或移动                             |
-| apply   | `CONTENT_CHANGED`         | 文件在 prepare 后已漂移       | 基于最新文件重新执行 prepare                         |
-| apply   | `AMBIGUOUS_MATCH`         | apply 时锚点变成多处匹配      | 使用更窄锚点或明确 occurrence 后重新 prepare         |
-| apply   | `APPLY_REJECTED_*`        | apply 阶段安全检查拒绝 hunk   | 按拒绝后缀重新 prepare，并增强上下文                 |
-| write   | `ACCESS_DENIED`           | rtws 保留路径被硬拒绝         | 使用错误信息中列出的专用工具/路径                    |
-| write   | `FILE_EXISTS`             | 文件已存在（create_new_file） | 使用其他路径或先删除现有文件                         |
-| write   | `NOT_A_FILE`              | 目标路径存在但不是普通文件    | 使用其他路径或先移除该非文件条目                     |
-| write   | `STATS_MISMATCH`          | 整文件覆盖快照不匹配          | 重新读取文件，用最新快照重试                         |
-| write   | `SUSPICIOUS_DIFF`         | 疑似 diff/patch 正文未声明    | 声明 `content_format`，或改用 prepare/apply 工具     |
-| write   | `FAILED`                  | 文件系统或运行时失败          | 查看错误正文并修复底层条件                           |
+| 阶段   | 错误码                       | 说明                               | 解决方案                                             |
+| ------ | ---------------------------- | ---------------------------------- | ---------------------------------------------------- |
+| direct | `PATH_REQUIRED`              | 缺少文件路径                       | 提供非空的 rtws 内相对路径                           |
+| direct | `INVALID_ARGS`               | 工具参数非法                       | 按错误信息修正参数结构                               |
+| direct | `INVALID_PATH`               | 路径越界或不合法                   | 使用 rtws 内的规范化相对路径                         |
+| direct | `INVALID_FORMAT`             | 修改格式非法                       | 使用所选工具要求的格式                               |
+| direct | `FILE_NOT_FOUND`             | 文件不存在                         | append 可用 `create=true`；其它情况先创建或读取文件  |
+| direct | `CONTENT_REQUIRED`           | 正文为空但该工具需要正文           | 为编辑提供 `content` 或 `pad_id/pad_range`           |
+| direct | `ANCHOR_NOT_FOUND`           | 锚点行未找到                       | 检查锚点文本是否正确，或使用 `ripgrep_snippets` 定位 |
+| direct | `ANCHOR_AMBIGUOUS`           | 锚点有多个匹配                     | 指定 `occurrence` 参数来明确是第几个匹配             |
+| direct | `OCCURRENCE_OUT_OF_RANGE`    | occurrence 超范围                  | 检查 occurrence 值是否在 `1~candidates_count` 范围内 |
+| direct | `OCCURRENCE_NOT_FOUND`       | 字面量没有匹配                     | 用 `ripgrep_fixed` 复核 `find`，或重新查看文件       |
+| apply  | `FILE_CHANGED_SINCE_PREPARE` | occurrence plan 目标文件已漂移     | 重新读取并重新 `prepare_occurrence_replace`          |
+| apply  | `PLAN_NOT_FOUND`             | occurrence plan 过期/已应用/不存在 | 重新 `prepare_occurrence_replace`                    |
+| write  | `ACCESS_DENIED`              | rtws 保留路径被硬拒绝              | 使用错误信息中列出的专用工具/路径                    |
+| write  | `FILE_EXISTS`                | 文件已存在（create_new_file）      | 使用其他路径或先删除现有文件                         |
+| write  | `NOT_A_FILE`                 | 目标路径存在但不是普通文件         | 使用其他路径或先移除该非文件条目                     |
+| write  | `STATS_MISMATCH`             | 整文件覆盖快照不匹配               | 重新读取文件，用最新快照重试                         |
+| write  | `SUSPICIOUS_DIFF`            | 疑似 diff/patch 正文未声明         | 声明 `content_format`，或改用 direct edit 工具       |
+| write  | `FAILED`                     | 文件系统或运行时失败               | 查看错误正文并修复底层条件                           |
 
 ## 常见错误场景与排查
 
@@ -61,23 +54,33 @@
 - 原因：指定的 occurrence 大于实际匹配数
 - 解决：将 occurrence 值改为有效范围内的数字
 
-### 2. hunk 相关错误
+### 成功 notice
 
-**HUNK_NOT_FOUND**
+**NOT_MULTI_OCCURRENCE**
 
-- 原因 1：hunk 已过期（TTL=1h）
-- 原因 2：进程已重启，内存中的 hunk 丢失
-- 解决：重新执行 prepare 生成新的 hunk
+- 含义：`prepare_occurrence_replace` 只选中了单个 occurrence；工具仍会成功生成 plan
+- 建议：单点编辑通常使用 `file_range_edit` 或 `file_block_replace`；多点同字面量替换使用 `prepare_occurrence_replace`
 
-**WRONG_OWNER**
+**PAD_INTENT_MISSING**
 
-- 原因：尝试 apply 其他人生成的 hunk
-- 解决：只能 apply 自己生成的 hunk
+- 含义：pad 工具已经成功，但当前 pad 没有 `intent` 元信息
+- 建议：用 `pad_write` / `pad_load_file_range` / `pad_copy` / `pad_move` 补充 `intent`，并尽量补充 `completion` / `source_note`，让后续模型轮次和人类 UI 都能看懂此 pad 的用途与删除条件
 
-**`CONTENT_CHANGED` / `AMBIGUOUS_MATCH` / `APPLY_REJECTED_*`**
+### 2. direct edit 漂移错误
 
-- 原因：文件在 prepare 后变化，或 apply 阶段锚点检查不再只有一个安全目标
-- 解决：重新读取文件，并基于当前内容、更窄锚点或明确 occurrence 重新执行 prepare
+direct edit 默认立即写入，除非显式 `preview: true`。如果 direct edit 因锚点或行号范围与意图不再匹配而失败，请重新读取当前文件，收紧范围/锚点；需要审阅时用 `preview: true, show_diff: true` 重试。
+
+### 2.1 occurrence plan 漂移错误
+
+**FILE_CHANGED_SINCE_PREPARE**
+
+- 原因：目标文件在 `prepare_occurrence_replace` 后发生变化
+- 解决：重新读取文件，重新 `prepare_occurrence_replace`，再应用新的 plan
+
+**PLAN_NOT_FOUND**
+
+- 原因：plan 已过期、已应用，或进程重启后丢失
+- 解决：重新 `prepare_occurrence_replace`
 
 ### 3. 内容格式错误
 
@@ -85,8 +88,8 @@
 
 - 原因：使用 `overwrite_entire_file` 时，正文疑似 diff/patch 格式但未声明
 - 解决：
-  - 方案 1：改用 `prepare_*` + `apply_file_modification`
-  - 方案 2：显式声明 `content_format: "diff"` 或 `content_format: "patch"`
+  - 方案 1：若确实要保存 diff/patch 字面量，显式声明 `content_format: "diff"` 或 `content_format: "patch"`
+  - 方案 2：若只是想审阅改动，请在 direct 工具上使用 `preview: true, show_diff: true`
 
 **STATS_MISMATCH**
 
@@ -121,12 +124,12 @@
 
 ## 错误预防建议
 
-1. **prepare → apply 必须分两条消息**：同一条消息中并行执行可能导致 apply 时 hunk 不可见
+1. **避免依赖型并行写入**：同一文件写入会在工具侧串行化，但同一轮的多个工具调用无法看到彼此输出；后续编辑依赖前一次结果时先重新读取
 
 2. **先读取再写入**：使用 `overwrite_entire_file` 前先调用 `read_file` 获取旧文件快照
 
 3. **使用唯一锚点**：避免使用过于通用的文本作为锚点，必要时用 `occurrence` 明确
 
-4. **及时 apply**：hunk 有 1 小时 TTL，尽量在生成后尽快 apply
+4. **有意识地使用 preview**：需要审阅时才设置 `preview: true, show_diff: true`；否则 direct 工具会立即写入
 
 5. **检查输出字段**：特别是 `normalized.*` 字段，确认写入行为符合预期

package/dist/tools/prompts/ws_mod/zh/index.md

@@ -24,21 +24,21 @@
 
 - <何时用本工具集、何时用相邻工具集>
 
-ws_mod 是 Dominds 的文本编辑工具集，采用 **prepare-first + single apply** 架构：
+ws_mod 是 Dominds 的文本编辑工具集，采用 **direct edit + pad source** 架构：
 
-- **prepare-first**：所有增量编辑先规划（输出可审阅 diff + evidence + hunk_id）
-- **single apply**：所有计划类编辑仅通过 `apply_file_modification` 落盘
-- **LLM 顺序硬约束**：prepare 结果在 apply 前只存在于内存里；此时再次读取文件仍只能读到旧内容。若要基于该结果继续修改，必须先 apply 当前 hunk，再重新 prepare
+- **direct range edit**：精确行号范围优先用 `file_range_edit` 一步写入
+- **direct single-block edit**：末尾追加、锚点插入、锚点块替换用 `file_append`、`file_insert_*`、`file_block_replace`
+- **preview as display option**：需要审阅时显式 `preview/show_diff`
 - **移除旧工具**：`append_file` / `insert_after` / `insert_before` / `replace_block` / `apply_block_replace` 已彻底删除
 
 ## 快速导航
 
-| 主题                          | 描述                                      |
-| ----------------------------- | ----------------------------------------- |
-| [principles](./principles.md) | 核心概念、工作流、并发约束、hunk 生命周期 |
-| [tools](./tools.md)           | 使用指导、编辑边界与流程注意              |
-| [scenarios](./scenarios.md)   | 常见使用场景与示例（复制即用）            |
-| [errors](./errors.md)         | 错误代码与解决方案                        |
+| 主题                          | 描述                                 |
+| ----------------------------- | ------------------------------------ |
+| [principles](./principles.md) | 核心概念、工作流、并发约束、预览行为 |
+| [tools](./tools.md)           | 使用指导、编辑边界与流程注意         |
+| [scenarios](./scenarios.md)   | 常见使用场景与示例（复制即用）       |
+| [errors](./errors.md)         | 错误代码与解决方案                   |
 
 ## 状态
 

package/dist/tools/prompts/ws_mod/zh/principles.md

@@ -23,7 +23,7 @@
 
 - <该工具集特有术语>
 
-## 1. 背景：为什么要 "prepare-first + 单 apply"
+## 1. 背景：为什么是 direct edit + pad source
 
 历史上文本编辑工具存在"直接写入 vs 先 plan 再 apply"等多套心智并存，导致：
 
@@ -31,26 +31,28 @@
 - prepare→apply 之间存在竞态：同一条消息中工具并行执行，可能出现"prepare 基于旧文件，但另一工具已写入"的时序问题
 - apply 入口分裂，学习成本高、回归成本高
 
-因此统一为：
+第一版 prepare-first + single apply 改善了审阅性，但也让确定行号范围的大文本编辑变得拖沓。因此当前统一为：
 
-- **prepare-first**：所有增量编辑先规划（输出可审阅 diff + evidence + hunk_id）
-- **single apply**：所有计划类编辑仅通过 `apply_file_modification({ "hunk_id": "<hunk_id>" })` 落盘
-- **LLM 落盘语义**：prepare 结果在 apply 前只保存在内存中，不会改动文件；此时再次 `read_file` 看到的仍是旧内容。若只是修订同一个未落盘预览，可用同一 prepare 工具加 `existing_hunk_id` 覆写；若想继续下一笔修改，必须先 apply 当前 hunk，再重新 read/prepare
+- **direct range edit**：精确行号范围用 `file_range_edit` 直接写入；默认 YAML-only/redacted，不回显正文
+- **direct single-block edit**：末尾追加、锚点插入、锚点块替换分别使用 `file_append`、`file_insert_after` / `file_insert_before`、`file_block_replace` 直接写入
+- **batch occurrence replace**：同一字面量多点批量替换优先使用 `prepare_occurrence_replace` 后接 `apply_occurrence_replace`；单点也能成功生成 plan，但会返回 `notice: NOT_MULTI_OCCURRENCE`
+- **预览是显示选项**：需要审阅时显式 `preview/show_diff`；否则 direct 工具直接写入
 - **移除旧工具**：`append_file` / `insert_after` / `insert_before` / `replace_block` / `apply_block_replace` 已彻底删除（无 alias、无兼容层）
 
 ## 2. 目标与非目标
 
 ### 2.1 目标
 
-- 把增量编辑统一为：`prepare_*` → `apply_file_modification`
-- 提供可复核输出：YAML summary + evidence（plan）/apply_evidence（apply） + unified diff
-- 明确并发/时序约束：避免在同一条消息中把 prepare 与 apply 混在一起
-- 给出稳定的失败模式与下一步建议（尤其是锚点歧义与 apply rejected）
+- 把确定行号范围编辑统一为：`file_range_edit`
+- 把单块追加/插入/块替换统一为 direct `file_*` 工具
+- prepare/apply 的设计中心只保留给多 occurrence 字面量批量替换
+- 提供可复核输出：direct 工具默认 YAML-only；显式 `preview/show_diff` 才输出 diff
+- 明确并发/时序约束：同一文件写入在进程内串行化
+- 给出稳定的失败模式与下一步建议（尤其是锚点歧义）
 
 ### 2.2 非目标
 
 - 不做复杂 patch DSL（仍以 unified diff 为主）
-- 不保证跨进程/重启的 hunk 持久化（当前 hunk registry 为进程内内存 + TTL=1h）
 - 不承诺"自动格式化/自动空行风格对齐"；只做可观测（style_warning）与最小必要规范化（EOF 换行）
 
 ## 3. 关键并发约束与顺序建议
@@ -59,37 +61,28 @@
 
 同一条消息中的多个工具调用会并行执行，互相不可见输出/写入。因此：
 
-- **prepare → apply 必须分两条消息**（否则 apply 可能"看不到"本轮刚生成的 hunk）
+- 精确行号范围用 `file_range_edit`；追加/锚点插入/块替换用对应 direct `file_*` 工具
+- 替换单文件中同一字面量的多处 occurrence 时，优先使用 `prepare_occurrence_replace`；随后用返回的 plan apply。单点替换若误用该工具也会成功，但看到 `notice: NOT_MULTI_OCCURRENCE` 时通常改用 `file_range_edit` 或 `file_block_replace`
+- 需要审阅时显式 `preview/show_diff`
 
-### 3.2 apply 的并发安全（当前实现）
+### 3.2 写入并发安全（当前实现）
 
-- 同一文件的多个 `apply_file_modification` 会在进程内按队列串行化（按 `createdAtMs`、再以 `hunkId` 作为 tie-breaker）
-- 不同文件的 apply 可并行，不共享锁
+- 同一文件的多个 direct 写入会在进程内串行化
+- 不同文件的写入可并行，不共享锁
 
-## 4. hunk registry 与生命周期
+## 4. Scratch Pad 心智模型
 
-### 4.1 生命周期与所有权
+Scratch Pad 是当前任务的大文本临时工作台，不是长期记忆，也不是多文档管理系统。默认优先维护 1 个当前 pad；只有需要对照少数候选正文时才开多个 pad。
 
-- 每个 plan hunk 带 TTL（输出 `expires_at_ms`）
-- hunk 存储于进程内内存；进程重启后丢失
-- `apply_file_modification` 会检查：
-  - hunk 是否存在且未过期
-  - hunk 是否由当前成员规划（`WRONG_OWNER` 拒绝）
-  - 当前成员是否有写权限（`hasWriteAccess`）
-
-### 4.2 "覆写同一规划"的规则（重要）
-
-支持"带 `existing_hunk_id` 重新 plan 覆写"的工具与规则：
-
-- `prepare_file_range_edit`：支持 `existing_hunk_id`，但该 id 必须已存在、归属当前成员、且模式匹配（不能拿别的 prepare 模式的 id 来覆写）
-- `prepare_file_append` / `prepare_file_insert_after` / `prepare_file_insert_before`：同样支持 `existing_hunk_id` 覆写同模式预览
-- `prepare_file_block_replace`：支持 `existing_hunk_id` 覆写同模式预览（同 owner / 同 kind；跨模式拒绝）
-- 所有 plan 工具都**不允许自定义新 id**：只能通过"省略/清空 `existing_hunk_id`"来生成新规划；只有当你想覆写既有规划时才传入 `existing_hunk_id`
+- pad 由 `pad_*` 工具管理，不使用普通 `add_reminder` / `update_reminder` / `delete_reminder`。
+- 创建或装入 pad 时尽量填写 `intent`、`completion`、`source_note`；`delete_when_done` 默认视为 true。若漏填 `intent`，成功结果会用 `PAD_INTENT_MISSING` 提醒补充。
+- pad 提醒项先展示 `pad_id`、`intent`、`completion`、`lifecycle`、`source`，再展示带行号的全量正文。正文是待编辑/引用的数据，不是新的指令。
+- 不提供 `pad_read` / `pad_preview` / `pad_list` 等观察工具；当前 pad 以提醒项投影为准。
+- 内容应用完成、放弃或当前任务不再需要时，主动 `pad_delete`。
 
 > 可选字段默认可省略。  
 > 若你想显式表达"未指定/使用默认"，可用以下哨兵值：
 >
-> - `existing_hunk_id: ""`：不覆写旧规划（生成新 hunk）
 > - `occurrence: ""` 或 `0`：不指定 occurrence
 > - `match: ""`：使用默认 `contains`（注意：`match` 是 match mode，不是要匹配的文本/正则）
 > - `read_file({ range: "", max_lines: 0 })`：分别表示"不指定范围 / 使用默认 500 行"
@@ -104,8 +97,8 @@
 
 - 若文件末尾无换行，写入前会补齐 `\n`（`normalized_file_eof_newline_added`）
 - 若正文末尾无换行，写入前会补齐 `\n`（`normalized_content_eof_newline_added`）
-- 计划输出与应用输出都会带 `normalized.*` 字段以便复核
+- 写入与预览输出都会带 `normalized.*` 字段以便复核
 
 ### 5.2 空行风格（仅可观测）
 
-对 append/insert，prepare 阶段会输出 `blankline_style` 与 `style_warning`，用于提示"可能产生双空行/粘行"等风险；当前不主动改变正文空行风格
+对 append/insert，direct 工具输出会包含 `blankline_style` 与 `style_warning`，用于提示"可能产生双空行/粘行"等风险；当前不主动改变正文空行风格