dsh-openwrite 0.2.28 → 0.2.34

package/docs/TOOLS.md

@@ -1,15 +1,15 @@
 # 小说工具参考
 
-本候选共 95 个 novel_* 工具。由 tools.ts 的注册定义生成；说明与参数保留实际 schema 原文，避免手册与接口漂移。用浏览器或编辑器搜索工具名即可定位。
+本候选共 56 个 novel_* 工具。由 tools.ts 的注册定义生成；说明与参数保留实际 schema 原文，避免手册与接口漂移。用浏览器或编辑器搜索工具名即可定位。
 
 ## 先选入口
 
-- 看当前作品：`novel_status`；查文件：`novel_doc_read`；看本章输入：`novel_context_preview`。上下文来源与预算见 [上下文槽位](CONTEXT_SLOTS.md)。
-- 修改大纲/设定/创作罗盘：先用 `novel_structured_change_plan` 预览并核对；只有作者已明确授权的精确变更才使用兼容的直接写入工具，如 `novel_focus`。
+- 看当前作品：`novel_status`；查文件：`novel_doc(action="read"`；看本章输入：`novel_context_preview`。上下文来源与预算见 [上下文槽位](CONTEXT_SLOTS.md)。
+- 修改大纲/设定/创作罗盘：先用 `novel_change_plan`（action="structured"）预览并核对；只有作者已明确授权的精确变更才使用兼容的直接写入工具，如 `novel_focus`。
 - 正文确认：`novel_manuscript_acceptance {}` 只读查 operation_id，核对影响后用 `novel_manuscript_acceptance_reconcile {"action":"acknowledge","operation_id":"实际返回值","confirm":true}` 确认；这不会补跑结算或审稿。
 - 结算缺失：核对目标章节后使用 `novel_settle_backfill {"chapter_ids":["ch_001"],"only_missing":true}`，再查返回任务；会调用模型并写入记忆/运行态资料，不重写正文。不要把 canon 未定论一律解释为缺结算。
-- 模型与嵌入：Chat 与 Embedding 档案独立；配置不等于连接成功。`novel_model_test` / `novel_model_embedding_test` 会实际请求提供方，可能计费。
-- 写章返回 task_id 后用 `novel_task_get` 查询；取消用 `novel_task_cancel`。超时/网络错误后先查任务与运行，避免重复提交。
+- 模型与嵌入：Chat 与 Embedding 档案独立；配置不等于连接成功。`novel_model_profiles(action="list"`（action="test"）/ `novel_embedding_profiles(action="list"`（action="test"）会实际请求提供方，可能计费。
+- 写章返回 task_id 后用 `novel_task`（action="get"）查询；取消用 action="cancel"。超时/网络错误后先查任务与运行，避免重复提交。
 
 ## 参数和错误
 
@@ -22,97 +22,58 @@
 | 工具 | 影响 | 必填参数 |
 | --- | --- | --- |
 | [novel_arc_reconcile](#novel_arc_reconcile) | 会提交操作或保存文件；具体取决于 action/参数 | `data` |
-| [novel_asset_create](#novel_asset_create) | 会提交操作或保存文件；具体取决于 action/参数 | `kind`, `id` |
-| [novel_asset_read](#novel_asset_read) | 只读查询（可更新检索缓存） | `kind`, `id` |
-| [novel_asset_update](#novel_asset_update) | 会提交操作或保存文件；具体取决于 action/参数 | `kind`, `id`, `revision` |
-| [novel_assets_list](#novel_assets_list) | 只读查询（可更新检索缓存） | 无 |
-| [novel_assets_package_export](#novel_assets_package_export) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
-| [novel_assets_package_import](#novel_assets_package_import) | 会提交操作或保存文件；具体取决于 action/参数 | `upload_id` |
-| [novel_assets_package_preview](#novel_assets_package_preview) | 会提交操作或保存文件；具体取决于 action/参数 | `package_base64` |
+| [novel_assets](#novel_assets) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
+| [novel_assets_package](#novel_assets_package) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
+| [novel_change_plan](#novel_change_plan) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
 | [novel_chapter_delete](#novel_chapter_delete) | 会提交操作或保存文件；具体取决于 action/参数 | `path`, `confirm`, `version` |
 | [novel_chapter_delete_batch](#novel_chapter_delete_batch) | 会提交操作或保存文件；具体取决于 action/参数 | `keep_through`, `confirm`, `version` |
 | [novel_chapter_run_action](#novel_chapter_run_action) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
-| [novel_chapter_scenes](#novel_chapter_scenes) | 只读查询（可更新检索缓存） | `chapter_id` |
-| [novel_chapter_work](#novel_chapter_work) | 只读查询（可更新检索缓存） | `chapter_id` |
-| [novel_context_preview](#novel_context_preview) | 只读查询（可更新检索缓存） | 无 |
-| [novel_continuity](#novel_continuity) | 只读查询（可更新检索缓存） | 无 |
+| [novel_chapter_scenes](#novel_chapter_scenes) | 会提交操作或保存文件；具体取决于 action/参数 | `chapter_id` |
+| [novel_chapter_work](#novel_chapter_work) | 会提交操作或保存文件；具体取决于 action/参数 | `chapter_id` |
+| [novel_context_preview](#novel_context_preview) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
+| [novel_continuity](#novel_continuity) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
 | [novel_diagnostics](#novel_diagnostics) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
-| [novel_doc_create](#novel_doc_create) | 会提交操作或保存文件；具体取决于 action/参数 | `kind`, `name` |
-| [novel_doc_read](#novel_doc_read) | 只读查询（可更新检索缓存） | `path` |
-| [novel_doc_write](#novel_doc_write) | 会提交操作或保存文件；具体取决于 action/参数 | `path`, `content` |
-| [novel_document_change_plan](#novel_document_change_plan) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
+| [novel_doc](#novel_doc) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
 | [novel_drift_entry](#novel_drift_entry) | 会提交操作或保存文件；具体取决于 action/参数 | `group_id`, `chapter_id`, `kind`, `impact`, `note`, `expected_revision` |
-| [novel_embedding_profile_delete](#novel_embedding_profile_delete) | 会提交操作或保存文件；具体取决于 action/参数 | `profile_id` |
-| [novel_embedding_profile_save](#novel_embedding_profile_save) | 会提交操作或保存文件；具体取决于 action/参数 | `profile` |
-| [novel_embedding_profile_select](#novel_embedding_profile_select) | 会提交操作或保存文件；具体取决于 action/参数 | `profile_id` |
-| [novel_embedding_profiles](#novel_embedding_profiles) | 只读查询（可更新检索缓存） | 无 |
-| [novel_export](#novel_export) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
-| [novel_export_preflight](#novel_export_preflight) | 只读查询（可更新检索缓存） | 无 |
+| [novel_embedding_profiles](#novel_embedding_profiles) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
+| [novel_export](#novel_export) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
 | [novel_focus](#novel_focus) | 会提交操作或保存文件；具体取决于 action/参数 | `goal` |
 | [novel_foreshadowing](#novel_foreshadowing) | 会提交操作或保存文件；具体取决于 action/参数 | `action`, `node_id` |
-| [novel_import](#novel_import) | 会提交操作或保存文件；具体取决于 action/参数 | `content` |
-| [novel_import_preview](#novel_import_preview) | 会提交操作或保存文件；具体取决于 action/参数 | `content` |
-| [novel_manuscript_acceptance](#novel_manuscript_acceptance) | 只读查询（可更新检索缓存） | 无 |
+| [novel_import](#novel_import) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
+| [novel_manuscript_acceptance](#novel_manuscript_acceptance) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
 | [novel_manuscript_acceptance_reconcile](#novel_manuscript_acceptance_reconcile) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
 | [novel_manuscript_edit_action](#novel_manuscript_edit_action) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
 | [novel_manuscript_import_action](#novel_manuscript_import_action) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
-| [novel_manuscript_metrics](#novel_manuscript_metrics) | 只读查询（可更新检索缓存） | `chapter_id` |
+| [novel_manuscript_metrics](#novel_manuscript_metrics) | 会提交操作或保存文件；具体取决于 action/参数 | `chapter_id` |
 | [novel_model_benchmark](#novel_model_benchmark) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
-| [novel_model_configure](#novel_model_configure) | 会提交操作或保存文件；具体取决于 action/参数 | `model` |
-| [novel_model_embedding_test](#novel_model_embedding_test) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
-| [novel_model_profile_delete](#novel_model_profile_delete) | 会提交操作或保存文件；具体取决于 action/参数 | `profile_id` |
-| [novel_model_profile_save](#novel_model_profile_save) | 会提交操作或保存文件；具体取决于 action/参数 | `profile` |
-| [novel_model_profiles](#novel_model_profiles) | 只读查询（可更新检索缓存） | 无 |
-| [novel_model_routes_save](#novel_model_routes_save) | 会提交操作或保存文件；具体取决于 action/参数 | `routes` |
-| [novel_model_test](#novel_model_test) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
+| [novel_model_profiles](#novel_model_profiles) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
 | [novel_multi_write](#novel_multi_write) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
 | [novel_narrative_forecast_action](#novel_narrative_forecast_action) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
-| [novel_outline_audit](#novel_outline_audit) | 只读查询（可更新检索缓存） | 无 |
+| [novel_outline_audit](#novel_outline_audit) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
 | [novel_outline_edit](#novel_outline_edit) | 会提交操作或保存文件；具体取决于 action/参数 | `operation`, `revision` |
-| [novel_outline_read](#novel_outline_read) | 只读查询（可更新检索缓存） | 无 |
-| [novel_project_archive_action](#novel_project_archive_action) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
-| [novel_project_archive_download](#novel_project_archive_download) | 会提交操作或保存文件；具体取决于 action/参数 | `archive_id` |
-| [novel_project_delete](#novel_project_delete) | 会提交操作或保存文件；具体取决于 action/参数 | `project_path`, `confirm` |
-| [novel_project_init](#novel_project_init) | 会提交操作或保存文件；具体取决于 action/参数 | `novel_id`, `title` |
-| [novel_project_open](#novel_project_open) | 会提交操作或保存文件；具体取决于 action/参数 | `project_path` |
-| [novel_reading_order](#novel_reading_order) | 只读查询（可更新检索缓存） | 无 |
-| [novel_reading_order_move](#novel_reading_order_move) | 会提交操作或保存文件；具体取决于 action/参数 | `document_id`, `target_volume_id`, `target_index`, `expected_revision` |
-| [novel_reading_packet](#novel_reading_packet) | 只读查询（可更新检索缓存） | `document_id` |
+| [novel_outline_read](#novel_outline_read) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
+| [novel_project](#novel_project) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
+| [novel_reading_order](#novel_reading_order) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
+| [novel_reading_packet](#novel_reading_packet) | 会提交操作或保存文件；具体取决于 action/参数 | `document_id` |
 | [novel_reference_library_action](#novel_reference_library_action) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
-| [novel_research_report](#novel_research_report) | 只读查询（可更新检索缓存） | `report_id` |
+| [novel_research_report](#novel_research_report) | 会提交操作或保存文件；具体取决于 action/参数 | `report_id` |
 | [novel_research_settings_save](#novel_research_settings_save) | 会提交操作或保存文件；具体取决于 action/参数 | `settings` |
-| [novel_research_status](#novel_research_status) | 只读查询（可更新检索缓存） | 无 |
+| [novel_research_status](#novel_research_status) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
 | [novel_review_chapter](#novel_review_chapter) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
-| [novel_review_framework](#novel_review_framework) | 只读查询（可更新检索缓存） | 无 |
-| [novel_revision_apply](#novel_revision_apply) | 会提交操作或保存文件；具体取决于 action/参数 | `proposal_id` |
-| [novel_revision_create_from_review](#novel_revision_create_from_review) | 会提交操作或保存文件；具体取决于 action/参数 | `chapter_id`, `issue_ids` |
-| [novel_revision_create_selection](#novel_revision_create_selection) | 会提交操作或保存文件；具体取决于 action/参数 | `chapter_id`, `start`, `end` |
-| [novel_revision_get](#novel_revision_get) | 只读查询（可更新检索缓存） | `proposal_id` |
-| [novel_revision_regenerate](#novel_revision_regenerate) | 会提交操作或保存文件；具体取决于 action/参数 | `proposal_id` |
-| [novel_revision_reject](#novel_revision_reject) | 会提交操作或保存文件；具体取决于 action/参数 | `proposal_id` |
-| [novel_revisions_list](#novel_revisions_list) | 只读查询（可更新检索缓存） | 无 |
+| [novel_review_framework](#novel_review_framework) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
+| [novel_revision](#novel_revision) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
 | [novel_rolling_plan_action](#novel_rolling_plan_action) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
 | [novel_rule_action](#novel_rule_action) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
 | [novel_runtime_skill_action](#novel_runtime_skill_action) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
-| [novel_scene_migration_apply](#novel_scene_migration_apply) | 会提交操作或保存文件；具体取决于 action/参数 | `expected_preview_revision`, `confirm` |
-| [novel_scene_migration_preview](#novel_scene_migration_preview) | 只读查询（可更新检索缓存） | 无 |
-| [novel_scene_migration_rollback](#novel_scene_migration_rollback) | 会提交操作或保存文件；具体取决于 action/参数 | `migration_id`, `expected_revision` |
-| [novel_scene_move](#novel_scene_move) | 会提交操作或保存文件；具体取决于 action/参数 | `scene_id`, `target_chapter_id`, `target_index`, `expected_revision`, `expected_source_revision`, `expected_target_revision` |
-| [novel_scene_structure](#novel_scene_structure) | 只读查询（可更新检索缓存） | 无 |
-| [novel_scene_update](#novel_scene_update) | 会提交操作或保存文件；具体取决于 action/参数 | `scene_id`, `expected_revision` |
-| [novel_search](#novel_search) | 只读查询（可更新检索缓存） | `q` |
+| [novel_scene](#novel_scene) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
+| [novel_scene_migration](#novel_scene_migration) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
+| [novel_search](#novel_search) | 会提交操作或保存文件；具体取决于 action/参数 | `q` |
 | [novel_settle_backfill](#novel_settle_backfill) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
 | [novel_source_action](#novel_source_action) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
-| [novel_status](#novel_status) | 只读查询（可更新检索缓存） | 无 |
-| [novel_structured_change_plan](#novel_structured_change_plan) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
+| [novel_status](#novel_status) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
 | [novel_sync](#novel_sync) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
-| [novel_task_cancel](#novel_task_cancel) | 会提交操作或保存文件；具体取决于 action/参数 | `task_id` |
-| [novel_task_confirm](#novel_task_confirm) | 会提交操作或保存文件；具体取决于 action/参数 | `task_id` |
-| [novel_task_create](#novel_task_create) | 会提交操作或保存文件；具体取决于 action/参数 | `type`, `input` |
-| [novel_task_get](#novel_task_get) | 会提交操作或保存文件；具体取决于 action/参数 | `task_id` |
-| [novel_task_retry](#novel_task_retry) | 会提交操作或保存文件；具体取决于 action/参数 | `task_id` |
-| [novel_tasks_list](#novel_tasks_list) | 只读查询（可更新检索缓存） | 无 |
-| [novel_trace_list](#novel_trace_list) | 只读查询（可更新检索缓存） | 无 |
+| [novel_task](#novel_task) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
+| [novel_trace_list](#novel_trace_list) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
 | [novel_write_chapter](#novel_write_chapter) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
 | [novel_writing_assets](#novel_writing_assets) | 会提交操作或保存文件；具体取决于 action/参数 | `action` |
 | [novel_writing_targets](#novel_writing_targets) | 会提交操作或保存文件；具体取决于 action/参数 | 无 |
@@ -127,92 +88,59 @@ Resolve selected drift entries by absorbing authored outline metadata, schedulin
 | --- | --- | --- | --- |
 | data | json | 是 | Object: group_id, expected_revision, entry_ids[], decision absorb/recover/freeze, confirm:true. absorb: outline_revision, outline_updates[{node_id,metadata}], resume?. recover: plan, target_chapter_id. |
 
-## novel_asset_create
+## novel_assets
 
-Create a structured asset. character/world assets take front-matter fields via `data` plus an optional `body_markdown`; progression assets take their YAML mapping via `data`. Fails with a conflict if the id exists — use novel_asset_update instead.
+List, read, create and update the writing assets of the current project (terminology, sample pools, character attribute groups and related records).
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| kind | string | 是 | ["character","world","progression"]；Asset kind. |
-| id | string | 是 | Asset id (letters, digits, "_", "-", "."). |
+| action | string | 是 | ["list","read","create","update"]；Writing-asset operation. |
+| kind | string | 否 | ["character","world","progression"]；Restrict to one asset kind; omit to list all kinds. |
+| id | string | 否 | Asset id; required for read/create/update. Must match [A-Za-z0-9][A-Za-z0-9_.-]{0,79}. |
 | data | json | 否 | Object of asset fields (e.g. name, summary, aliases). |
 | body_markdown | string | 否 | Markdown body (character/world assets). |
-
-## novel_asset_read
-
-Read one structured asset by kind and id, including its relation view.
-
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| kind | string | 是 | ["character","world","progression"]；Asset kind. |
-| id | string | 是 | Asset id. |
-
-## novel_asset_update
-
-Immediate compatibility write for an asset change the author has already authorized exactly; otherwise use novel_structured_change_plan. Update a structured asset (character / world / progression). Revision-gated: pass the `revision` fingerprint from novel_assets_list; the server rejects the update with a conflict if the asset changed. Pass field changes via `data` (merged into the asset front matter), `body_markdown` to replace the markdown body, or `raw_text` to replace the whole document.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| kind | string | 是 | ["character","world","progression"]；Asset kind. |
-| id | string | 是 | Asset id. |
-| revision | string | 是 | The asset revision fingerprint from a fresh novel_assets_list call. |
-| data | json | 否 | Object of asset fields to merge (e.g. name, summary, aliases). |
-| body_markdown | string | 否 | Replacement markdown body (character/world assets). |
+| revision | string | 否 | The asset revision fingerprint from a fresh novel_assets(action="list") call. |
 | raw_text | string | 否 | Full replacement document text, validated by the server. |
 | related_mode | string | 否 | ["merge","replace"]；Preserve and merge existing related entries by default; replace explicitly clears or replaces relations. |
 
-## novel_assets_list
+## novel_assets_package
 
-List structured assets (characters, world entities, progression systems) of the current novel project.
-
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| kind | string | 否 | ["character","world","progression"]；Restrict to one asset kind; omit to list all kinds. |
-
-## novel_assets_package_export
-
-Export assets as an .owasset.zip package and save it locally. Omit selections to export all assets.
+Export the project assets into a portable package, preview a package before importing it, and import a reviewed package with explicit dependency resolutions.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
+| action | string | 是 | ["export","preview","import"]；Asset package operation. |
 | selections | array[string] | 否 | Asset selectors in "kind:id" form, e.g. ["character:hero", "world:capital"]. |
-
-## novel_assets_package_import
-
-Import a previously staged asset package (see novel_assets_package_preview). Resolves per-asset conflicts via `resolutions`; set allow_missing_dependencies to skip missing dependency checks.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| upload_id | string | 是 | The upload_id returned by novel_assets_package_preview. |
-| package_sha256 | string | 否 | Optional expected package digest guard. |
+| package_base64 | string | 否 | Base64-encoded .owasset.zip package (max 25 MB decoded). |
+| upload_id | string | 否 | The upload_id returned by novel_assets_package(action="preview"). |
+| package_sha256 | string | 否 | Package digest. Required for import: pass the package_sha256 returned by action="preview"; the server rejects an import without it as a stale package. |
 | resolutions | json | 否 | Object mapping conflicting asset keys to resolutions. |
 | allow_missing_dependencies | boolean | 否 | Allow import despite missing asset dependencies (default false). |
 
-## novel_assets_package_preview
+## novel_change_plan
 
-Stage an .owasset.zip asset package (base64) and preview its contents and conflicts without importing. Returns an upload_id to pass to novel_assets_package_import.
+Preview, apply, reject, retry and undo a change plan. document plans edit one project document as text; structured plans edit the manuscript model (outline, scenes, canon) as operations. Both are two-step: preview returns a token the follow-up step must present.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| package_base64 | string | 是 | Base64-encoded .owasset.zip package (max 25 MB decoded). |
+| action | string | 是 | ["document","structured"]；Plan kind: document edits a project document, structured edits the manuscript model. |
+| step | string | 否 | ["preview","apply","reject","retry","undo"]；Plan lifecycle step. |
+| confirm | boolean | 否 | Required true for apply and undo after author acceptance. |
+| path | string | 否 | Existing document path for preview, relative to the novel root. |
+| edits | json | 否 | Preview edits: [{old_text,new_text}] or [{start_text,end_text,new_text,end_inclusive}]. Range end defaults to inclusive for compatibility; end_inclusive:false preserves the end anchor (e.g. the next heading). |
+| preview_token | string | 否 | Immutable preview or undo token for apply/reject/retry/undo. |
+| change_kind | string | 否 | ["outline","asset","focus","foreshadowing","writing_targets"]；Structured domain for a preview. |
+| change | json | 否 | One direct-tool-shaped change object, required for preview. |
 
 ## novel_chapter_delete
 
-Delete the LATEST manuscript chapter. The server enforces three safeguards: the path must be a chapter under data/manuscript, confirm must exactly equal the chapter id (e.g. "ch_0007"), and version must equal the document version fingerprint from a fresh novel_doc_read. Only the newest chapter can be deleted, and never while a background task is active.
+Delete the LATEST manuscript chapter. The server enforces three safeguards: the path must be a chapter under data/manuscript, confirm must exactly equal the chapter id (e.g. "ch_0007"), and version must equal the document version fingerprint from a fresh novel_doc(action="read"). Only the newest chapter can be deleted, and never while a background task is active.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
@@ -220,7 +148,7 @@ Delete the LATEST manuscript chapter. The server enforces three safeguards: the
 | --- | --- | --- | --- |
 | path | string | 是 | Chapter path, e.g. "data/manuscript/ch_0007.md". |
 | confirm | string | 是 | Must exactly equal the chapter id, e.g. "ch_0007". |
-| version | string | 是 | The document version fingerprint from novel_doc_read. |
+| version | string | 是 | The document version fingerprint from novel_doc(action="read"). |
 
 ## novel_chapter_delete_batch
 
@@ -232,7 +160,7 @@ Delete the contiguous latest manuscript tail in one server request, retaining th
 | --- | --- | --- | --- |
 | keep_through | string | 是 | Last chapter to retain, e.g. "ch_0030". |
 | confirm | string | 是 | Must exactly equal DELETE_AFTER:<keep_through>. |
-| version | string | 是 | The latest chapter version fingerprint from a fresh novel_doc_read. |
+| version | string | 是 | The latest chapter version fingerprint from a fresh novel_doc(action="read"). |
 
 ## novel_chapter_run_action
 
@@ -267,7 +195,7 @@ Manage Chapter Run V2 records (the server's per-chapter write/review run ledger)
 
 Read the revision-labelled scene slice for one chapter.
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
@@ -277,7 +205,7 @@ Read the revision-labelled scene slice for one chapter.
 
 Read one chapter work brief: manuscript/acceptance/review revisions, writing target, recent edits, tasks, and categorized foreshadowing obligations.
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
@@ -287,9 +215,9 @@ Read one chapter work brief: manuscript/acceptance/review revisions, writing tar
 
 ## novel_context_preview
 
-Preview the context packet OpenWrite would assemble for writing a chapter (relevant outline, assets, foreshadowing, and prior-chapter memory). Set include_agent_payload to inspect canonical writer inputs and document inclusion without calling a model.
+Preview the context packet OpenWrite would assemble for writing a chapter (relevant outline, assets, foreshadowing, and prior-chapter memory). The chapter must already exist in the outline; an unknown chapter id is rejected instead of returning an empty generic context. Set include_agent_payload to inspect canonical writer inputs and document inclusion without calling a model.
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
@@ -300,7 +228,7 @@ Preview the context packet OpenWrite would assemble for writing a chapter (relev
 
 Get the continuity report: unresolved foreshadowing, character state drift, and timeline consistency of the current project.
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
@@ -316,54 +244,22 @@ Run runtime diagnostics over the project (read-only): stuck runs, stale locks, a
 | --- | --- | --- | --- |
 | stuck_minutes | integer | 否 | Minutes after which a run counts as stuck (default 30). |
 
-## novel_doc_create
-
-Create a new project document by kind and name (e.g. a setting or character note), then returns the created document.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| kind | string | 是 | Document kind (e.g. "setting", "character"). |
-| name | string | 是 | Document name. |
-| description | string | 否 | Short description of the document. |
-
-## novel_doc_read
-
-Read a project document (path relative to the novel data root, e.g. "src/outline.md" or "data/manuscript/ch_0007.md"). Returns content plus a `version` fingerprint needed by novel_doc_write.
+## novel_doc
 
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| path | string | 是 | Document path relative to the novel data root. |
-
-## novel_doc_write
-
-Write a project document (path relative to the novel data root). Uses a version-based optimistic lock: pass the `version` returned by novel_doc_read; the server rejects with a conflict if the document changed. Omit version to create a new document; set force to bypass the lock.
+Read, write and create the plain documents of the current project (notes, briefs and other author-owned files). Writes are optimistic and reject a stale version.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| path | string | 是 | Document path relative to the novel data root. |
-| content | string | 是 | Full new document content (max 2 MB). |
-| version | string | 否 | The version fingerprint from novel_doc_read (optimistic lock). |
+| action | string | 是 | ["read","write","create"]；Document operation. |
+| path | string | 否 | Document path relative to the novel data root (read/write). Writable roots are src/ and data/manuscript/; create derives its path from kind and name. |
+| content | string | 否 | Full new document content (max 2 MB). |
+| version | string | 否 | The version fingerprint from novel_doc(action="read") (optimistic lock). |
 | force | boolean | 否 | Bypass the version check (default false). |
-
-## novel_document_change_plan
-
-Stage and review revision-gated changes to an existing novel document. Use action "preview" with path and edits to receive an immutable preview_token and real before/after summary. Use "apply" only after author acceptance, passing that token and confirm: true; "reject" discards it, "retry" rebuilds it against the current source, and "undo" safely applies an undo_preview_token returned by a prior apply. Each edit uses old_text/new_text or unique start_text/end_text/new_text anchors. Preview returns applied:false; changed/would_change describe only the proposed difference. OLD_TEXT_NOT_FOUND is an anchor mismatch (400), while revision conflicts are 409; use the exact suggested bytes and reread the source before retrying. The server rechecks the source revision and writes exactly the stored preview.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| action | string | 是 | ["preview","apply","reject","retry","undo"]；Plan lifecycle action. |
-| confirm | boolean | 否 | Required true for apply and undo after author acceptance. |
-| path | string | 否 | Existing document path for preview, relative to the novel root. |
-| edits | json | 否 | Preview edits: [{old_text,new_text}] or [{start_text,end_text,new_text,end_inclusive}]. Range end defaults to inclusive for compatibility; end_inclusive:false preserves the end anchor (e.g. the next heading). |
-| preview_token | string | 否 | Immutable preview or undo token for apply/reject/retry/undo. |
+| kind | string | 否 | Document kind for create: "character" or "world" (the server derives the file path). |
+| name | string | 否 | Document name. |
+| description | string | 否 | Short description of the document. |
 
 ## novel_drift_entry
 
@@ -381,74 +277,38 @@ Record author-observed chapter drift. Saves an immutable outline/manuscript base
 | note | string | 是 | Observed drift and supporting evidence. |
 | expected_revision | integer | 是 | ledger.revision from outline audit. |
 
-## novel_embedding_profile_delete
-
-Delete an independent Embedding profile; the active profile automatically moves to another one.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| profile_id | string | 是 |  |
-
-## novel_embedding_profile_save
+## novel_embedding_profiles
 
-Create or update an independent Embedding profile; it is never attached to a Chat profile.
+List, save, select, delete and test embedding profiles. Selection chooses the profile the server uses for semantic search and recall.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| profile | json | 是 | Embedding profile: id, label, provider, model, base_url, dimension, max_tokens. |
+| action | string | 是 | ["list","save","select","delete","test"]；Embedding configuration operation. |
+| profile | json | 否 | Embedding profile: id, label, provider, model, base_url, dimension, max_tokens. |
 | api_key | string | 否 | Embedding API key. |
 | remember_api_key | boolean | 否 | Persist the key (default true). |
-
-## novel_embedding_profile_select
-
-Select the active independent Embedding profile used by search.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| profile_id | string | 是 |  |
-
-## novel_embedding_profiles
-
-List independent Embedding profiles and the active selection. Embedding is configured separately from Chat profiles.
-
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| 无 | — | — | — |
+| profile_id | string | 否 |  |
+| id | string | 否 | Stored profile id to probe. |
+| candidate | json | 否 | Embedding candidate settings object (merged into the request). |
 
 ## novel_export
 
-Export the manuscript as a file download and save it locally. Inspect novel_export_preflight first and pass its preflight_revision unchanged to bind the download to that inspected manuscript state. Returns the saved file path.
+Preflight and run a manuscript export. Preflight validates the selection, purpose and format and returns a revision the export must present.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| format | string | 否 | ["md","txt","epub"]；Export format (default "md"). |
-| purpose | string | 否 | ["backup","delivery","personal_archive"]；Export purpose (default "delivery"). |
-| preflight_revision | string | 否 | Revision returned by novel_export_preflight for the same format and purpose. |
-
-## novel_export_preflight
-
-Inspect the current manuscript export order, structural defects, writing targets, metadata, review freshness, manuscript acceptance, blockers, and warnings. Pass the returned preflight_revision unchanged to novel_export so the downloaded file is bound to the manuscript state that was inspected.
-
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
+| action | string | 是 | ["preflight","export"]；Export step; preflight reports what would be written without writing it. |
 | format | string | 否 | ["md","txt","epub"]；Export format (default "md"). |
 | purpose | string | 否 | ["backup","delivery","personal_archive"]；Export purpose (default "delivery"). personal_archive preserves author copies with gate findings recorded as warnings. |
+| preflight_revision | string | 否 | Revision returned by novel_export(action="preflight") for the same format and purpose. |
 
 ## novel_focus
 
-Immediate compatibility write for a focus change the author has already authorized exactly; otherwise use novel_structured_change_plan. Set the writing focus compass for the project.
+Immediate compatibility write for a focus change the author has already authorized exactly; otherwise use novel_change_plan(action="structured"). Set the writing focus compass for the project.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
@@ -461,7 +321,7 @@ Immediate compatibility write for a focus change the author has already authoriz
 
 ## novel_foreshadowing
 
-Immediate compatibility write for a foreshadowing change the author has already authorized exactly; otherwise use novel_structured_change_plan. Manage the foreshadowing DAG. action "create": node_id + content, optional weight (1-10, default 5), layer (default "支线"), target_chapter. action "update": node_id + status (e.g. planted/paid-off).
+Immediate compatibility write for a foreshadowing change the author has already authorized exactly; otherwise use novel_change_plan(action="structured"). Manage the foreshadowing DAG. action "create": node_id + content, optional weight (1-10, default 5), layer (default "支线"), target_chapter. action "update": node_id + status (e.g. planted/paid-off).
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
@@ -477,27 +337,14 @@ Immediate compatibility write for a foreshadowing change the author has already
 
 ## novel_import
 
-Import a TXT/Markdown manuscript as chapters (split on headings). Preview first with novel_import_preview; the server rejects conflicting chapter ids unless force is set.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| content | string | 是 | The manuscript text to import. |
-| filename | string | 否 | Source filename; suffix must be .txt/.md/.markdown (default "import.md"). |
-| arc_id | string | 否 | Arc id like "arc_001" (default: the project's current arc). |
-| start_number | integer | 否 | First chapter number (default: continue numbering). |
-| force | boolean | 否 | Overwrite conflicting existing chapters (default false). |
-
-## novel_import_preview
-
-Preview a TXT/Markdown manuscript import without writing anything: detected chapters, numbering, and conflicts with existing chapters. Run this before novel_import.
+Preview an imported manuscript and then import it. Preview reports the parsed chapters, arc mapping and conflicts without writing; import applies the reviewed plan.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| content | string | 是 | The manuscript text to import. |
+| action | string | 是 | ["preview","import"]；Import step; preview never writes anything. |
+| content | string | 否 | The manuscript text to import. |
 | filename | string | 否 | Source filename; suffix must be .txt/.md/.markdown (default "import.md"). |
 | arc_id | string | 否 | Arc id like "arc_001" (default: the project's current arc). |
 | start_number | integer | 否 | First chapter number (default: after the last existing chapter). |
@@ -507,7 +354,7 @@ Preview a TXT/Markdown manuscript import without writing anything: detected chap
 
 Inspect the canonical manuscript acceptance ledger: current and accepted content revisions, drift, recoverable operations, derived-result impacts, and chapters that require author review.
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
@@ -531,7 +378,7 @@ Reconcile the canonical manuscript acceptance ledger. Actions: "baseline" (accep
 
 ## novel_manuscript_edit_action
 
-Chapter snapshots, annotations and saved drafts. Actions: "drafts" (list recoverable uncommitted prose), "restore_draft" (run_id_v2 + revision + confirm: true; copy the exact saved bytes without generation, then reconcile facts). Other actions: "versions" (chapter_id), "version" (chapter_id + version_id — returns the snapshot content), "checkpoint" (chapter_id, optional label — save a snapshot), "compare" (chapter_id + version_id — preview current-to-snapshot differences without writing), "restore" (chapter_id + version_id + revision — REVERTS the chapter to a snapshot; revision-gated and confirmation-gated: the server demands confirm: true), "annotations" (chapter_id), "annotate" (chapter_id + revision + quote + note, optional start_hint/end_hint and color amber|rose|sky|lime|violet), "resolve_annotation" (chapter_id + annotation_id).
+Chapter snapshots, annotations and saved drafts. Actions: "drafts" (list recoverable uncommitted prose), "restore_draft" (run_id_v2 + revision + confirm: true; copy the exact saved bytes without generation, then reconcile facts). Other actions: "versions" (chapter_id), "version" (chapter_id + version_id — returns the snapshot content), "checkpoint" (chapter_id, optional label — save a snapshot), "compare" (chapter_id + version_id — preview current-to-snapshot differences without writing), "restore" (chapter_id + version_id + revision — REVERTS the chapter to a snapshot; revision-gated and confirmation-gated: the server demands confirm: true), "annotations" (chapter_id), "annotate" (chapter_id + revision + quote + note, optional start_hint/end_hint (derived from the quote when omitted) and color amber|rose|sky|lime|violet), "resolve_annotation" (chapter_id + annotation_id).
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
@@ -564,7 +411,7 @@ Operate the durable, resumable import workspace for the author's own TXT/Markdow
 | limit | integer | 否 | Maximum operations for list (default 50). |
 | filename | string | 否 | Source filename ending in .txt, .md, or .markdown. |
 | content | string | 否 | The author's own manuscript text for prepare. |
-| arc_id | string | 否 | Target arc id, e.g. arc_001. |
+| arc_id | string | 否 | Target arc id, e.g. arc_001. Optional for prepare; defaults to the project's current arc. |
 | start_number | integer | 否 | Optional first chapter number. |
 | expected_preview_revision | string | 否 | Current preview revision required by structure/confirm. |
 | chapters | array[json] | 否 | Edited chapter objects: chapter_id, title, content. |
@@ -574,7 +421,7 @@ Operate the durable, resumable import workspace for the author's own TXT/Markdow
 
 Read deterministic chapter metrics, terminology findings, overlap against anchors and the previous three chapters, duplicate paragraphs and selected character groups. Overlap spans use Unicode codepoint offsets. No model call.
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
@@ -603,98 +450,32 @@ Run or inspect isolated chapter or outline model benchmarks through OpenWrite pr
 | concurrency | integer | 否 | Concurrent model jobs, 1-4. |
 | limit | integer | 否 | List limit, default 20. |
 
-## novel_model_configure
+## novel_model_profiles
 
-Apply and persist the server's active model connection (OpenWrite's own LLM for writing/review — independent of the dsh model). max_tokens must stay below context_tokens.
+List, save, delete and test OpenWrite model profiles, per-task routing and the active model settings. Profiles select which provider/model each task uses; routes map tasks to profiles.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
+| action | string | 是 | ["list","save","delete","save_routes","configure","test"]；Model configuration operation. |
+| profile | json | 否 | Profile object, e.g. {"id": "fast", "label": "...", "provider": "openai", "model": "...", "base_url": "...", "max_output_tokens": 24000}. |
+| api_key | string | 否 | Chat API key to store with the profile. |
+| remember_api_key | boolean | 否 | Persist the API key on the server (default true). |
+| profile_id | string | 否 | Profile id to delete. |
+| fallback_id | string | 否 | Profile id to reroute to (default: the server default profile). |
+| routes | json | 否 | Object mapping operation names to profile ids. |
 | provider | string | 否 | ["openai","anthropic","custom"]；Provider (default "openai"). |
-| model | string | 是 | Model name (max 120 characters). |
-| api_key | string | 否 | API key; omit to reuse the server environment key. |
+| model | string | 否 | Model name (max 120 characters). |
 | base_url | string | 否 | Base URL (required for provider "custom"). |
 | api_format | string | 否 | ["chat","responses"]；API format (default "chat"). |
 | context_tokens | integer | 否 | Context budget (min 12000). |
 | max_tokens | integer | 否 | Max output tokens (min 256, must be < context_tokens). |
-| remember_api_key | boolean | 否 | Persist the API key on the server (default true). |
-
-## novel_model_embedding_test
-
-Probe an independent Embedding profile without changing Chat profiles.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| id | string | 否 | Stored profile id to probe. |
-| candidate | json | 否 | Embedding candidate settings object (merged into the request). |
-| api_key | string | 否 | Embedding API key override. |
-
-## novel_model_profile_delete
-
-Delete a stored model profile. Routes pointing at it fall back to fallback_id.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| profile_id | string | 是 | Profile id to delete. |
-| fallback_id | string | 否 | Profile id to reroute to (default: the server default profile). |
-
-## novel_model_profile_save
-
-Save (create or update) a named model profile on the server, with an optional API key.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| profile | json | 是 | Profile object, e.g. {"id": "fast", "label": "...", "provider": "openai", "model": "...", "base_url": "...", "max_output_tokens": 24000}. |
-| api_key | string | 否 | Chat API key to store with the profile. |
-| remember_api_key | boolean | 否 | Persist the API key on the server (default true). |
-
-## novel_model_profiles
-
-List the server's model profiles and per-task routing (which provider/model OpenWrite uses for writing, review, etc.).
-
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| 无 | — | — | — |
-
-## novel_model_routes_save
-
-Save per-task model routing: map operation names (e.g. "chapter_write", "review", "research") to profile ids.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| routes | json | 是 | Object mapping operation names to profile ids. |
-
-## novel_model_test
-
-Test a model connection without changing active settings. Pass id to test a stored profile, or a full candidate (provider/model/base_url/api_key...).
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
 | id | string | 否 | Stored profile id to test. |
-| provider | string | 否 | ["openai","anthropic","custom"]；Provider (default "openai"). |
-| model | string | 否 | Model name (required when id is omitted). |
-| base_url | string | 否 | Base URL (required for provider "custom"). |
-| api_format | string | 否 | ["chat","responses"]；API format (default "chat"). |
-| api_key | string | 否 | API key; omit to reuse the server environment key. |
-| context_tokens | integer | 否 | Context budget. |
-| max_tokens | integer | 否 | Max output tokens. |
 
 ## novel_multi_write
 
-Queue a BACKGROUND continuous-writing run: writes up to max_chapters chapters following the outline, reviewing each; stops early on review blockers, continuity errors, low scores, or budget limits. Returns immediately with a task id — poll with novel_task_get and resume paused runs with novel_task_confirm.
+Queue a BACKGROUND continuous-writing run: writes up to max_chapters chapters following the outline, reviewing each; stops early on review blockers, continuity errors, low scores, or budget limits. Returns immediately with a task id — poll with novel_task(action="get"). A paused run is resumed with novel_task(action="confirm"), which returns a continuation task: poll that returned task_id. Confirming the same paused task again is idempotent.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
@@ -710,7 +491,7 @@ Queue a BACKGROUND continuous-writing run: writes up to max_chapters chapters fo
 | temperature | number | 否 | Sampling temperature (default 0.7). |
 | stop_on_blocker | boolean | 否 | Stop when a review reports a blocker issue (default true). |
 | stop_on_continuity_error | boolean | 否 | Stop on high-severity continuity issues (default true). |
-| require_confirmation_after_each_chapter | boolean | 否 | Pause for novel_task_confirm after each chapter (default false). |
+| require_confirmation_after_each_chapter | boolean | 否 | Pause for novel_task(action="confirm") after each chapter (default false). |
 
 ## novel_narrative_forecast_action
 
@@ -735,7 +516,7 @@ Manage narrative forecasts (branching "what-if" plot projections). Actions: "lis
 
 Read countable chapter-group facts: budgets/actual words, declared promises and function streaks, declared/confirmed payoffs, overdue hooks and drift ledger. Never generates a score or claims prose fulfilled a promise. No model call.
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
@@ -745,7 +526,7 @@ Read countable chapter-group facts: budgets/actual words, declared promises and
 
 ## novel_outline_edit
 
-Immediate compatibility write for an outline change the author has already authorized exactly; otherwise use novel_structured_change_plan. Apply ONE atomic structural edit to the outline tree. Edits are revision-gated: read the current `revision` via novel_outline_read first and pass it back; the server rejects the edit with a conflict if the outline changed in between. Operations: "rename" (node_id + title), "update_summary" (node_id + summary), "add_child" (node_id = parent, + title/summary/kind), "add_after" (node_id = sibling, + title/summary/kind), "delete" (node_id, cascade=false keeps children), "promote" (remove a container), and "get_meta"/"set_meta" (chapter metadata, optionally updates[] for a batch).
+Immediate compatibility write for an outline change the author has already authorized exactly; otherwise use novel_change_plan(action="structured"). Apply ONE atomic structural edit to the outline tree. Edits are revision-gated: read the current `revision` via novel_outline_read first and pass it back; the server rejects the edit with a conflict if the outline changed in between. Operations: "rename" (node_id + title), "update_summary" (node_id + summary), "add_child" (node_id = parent, + title/summary/kind), "add_after" (node_id = sibling, + title/summary/kind), "delete" (node_id, cascade=false keeps children), "promote" (remove a container), and "get_meta"/"set_meta" (chapter metadata, optionally updates[] for a batch).
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
@@ -753,7 +534,7 @@ Immediate compatibility write for an outline change the author has already autho
 | --- | --- | --- | --- |
 | operation | string | 是 | ["rename","update_summary","add_child","add_after","delete","promote","get_meta","set_meta"]；The structural operation to apply. |
 | cascade | boolean | 否 | For delete, false removes only the container and keeps children and chapter IDs. |
-| metadata | json | 否 | Field object for set_meta; use target_words, beats, hooks or characters. |
+| metadata | json | 否 | Field object for set_meta; use dramatic_position, content_focus, goals, target_words, word_budget, characters, settings, emotional_arc, beats, hooks, promise, payoff_of or function. Text fields (dramatic_position, content_focus, emotional_arc) take one line of text; word counts (target_words, word_budget) take a number. List fields (goals, beats, hooks, characters, settings, payoff_of, function) take an array of strings or one comma-separated string; promise accepts both too. |
 | chapter_id | string | 否 | Chapter ID alias for node_id in get_meta/set_meta. |
 | updates | json | 否 | Batch of 1-50 {chapter_id, metadata} objects for set_meta, or {chapter_id} for get_meta; one revision guards the whole batch. |
 | revision | string | 是 | The outline revision fingerprint from a fresh novel_outline_read call. |
@@ -766,21 +547,29 @@ Immediate compatibility write for an outline change the author has already autho
 
 Read the live outline tree. The response carries a `revision` fingerprint required by novel_outline_edit and a chapter `recommendation`.
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
 | chapter | string | 否 | Optional chapter id to get a writing recommendation for. |
 
-## novel_project_archive_action
+## novel_project
 
-Inspect, create, and restore complete .owarchive project archives. Use preflight before create; use restore_preview before restore to inspect path/reference rewrites, conflicts, warnings, checksum, and the archived-without-auto-resume task policy. Restore requires the preview archive_sha256 and explicit confirmation.
+Initialize, open and delete a novel project, and manage its archive packages (list, get, create, restore preview, restore, download). Archiving never touches the live project.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| action | string | 是 | ["preflight","list","get","create","restore_preview","restore"]；Archive lifecycle action. |
+| action | string | 是 | ["init","open","delete","archive","download"]；Project operation. |
+| novel_id | string | 否 | Project id, e.g. "my_novel" (2-64 chars: letters, digits, "-", "_"). |
+| title | string | 否 | Book title (max 120 characters). |
+| author | string | 否 | Author credit for delivery export (max 120 characters). |
+| language | string | 否 | Book language tag, e.g. zh-CN or en (default zh-CN). |
+| project_path | string | 否 | Target directory on the server; omit to use the server default location. |
+| template | string | 否 | ["default","demo_short"]；Project template (default "default"). |
+| confirm_novel_id | string | 否 | Must exactly equal the project's novel_id (from its novel_config.yaml). |
+| archive_op | string | 否 | ["preflight","list","get","create","restore_preview","restore"]；Archive lifecycle operation. |
 | archive_id | string | 否 | Archive id shaped owa_<24 lowercase hex>. |
 | expected_preflight_revision | string | 否 | Current archive preflight revision for create. |
 | target_root | string | 否 | Absolute new or empty project directory for restore. |
@@ -789,80 +578,25 @@ Inspect, create, and restore complete .owarchive project archives. Use preflight
 | archive_sha256 | string | 否 | Checksum returned by restore_preview. |
 | confirm | boolean | 否 | Must be true for restore. |
 
-## novel_project_archive_download
-
-Download one complete .owarchive project archive and save it in this workspace's local export directory.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| archive_id | string | 是 | Archive id shaped owa_<24 lowercase hex>. |
-
-## novel_project_delete
-
-PERMANENTLY delete a project directory and all its contents from the server machine (recursive delete, not recoverable). The server requires confirm to exactly equal the project's novel_id as a safeguard.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| project_path | string | 是 | Project directory to delete. |
-| confirm | string | 是 | Must exactly equal the project's novel_id (from its novel_config.yaml). |
-
-## novel_project_init
-
-Create a new OpenWrite novel project on the server machine and make it the active project. Works without a currently open project. novel_id must be 2-64 chars of letters/digits/"-"/"_".
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| novel_id | string | 是 | Project id, e.g. "my_novel" (2-64 chars: letters, digits, "-", "_"). |
-| title | string | 是 | Book title (max 120 characters). |
-| author | string | 否 | Author credit for delivery export (max 120 characters). |
-| language | string | 否 | Book language tag, e.g. zh-CN or en (default zh-CN). |
-| project_path | string | 否 | Target directory on the server; omit to use the server default location. |
-| template | string | 否 | ["default","demo_short"]；Project template (default "default"). |
-
-## novel_project_open
-
-Switch the Studio server to another existing project directory (must contain novel_config.yaml). Works without a currently open project; afterwards every other novel_* tool targets the newly opened project. The server rejects the switch while a background task is active.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| project_path | string | 是 | Absolute project directory path on the server machine. |
-
 ## novel_reading_order
 
-Read the canonical manuscript order with stable document/occurrence ids, volume membership, previous/next links, revision, and explicit duplicate or missing-file issues.
-
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| 无 | — | — | — |
-
-## novel_reading_order_move
-
-Move one manuscript document within or across volumes. Requires the fresh reading-order revision and rejects ambiguous, missing, or concurrently changed order.
+Read the reading order of the current project and move one document to another volume or position. The move is optimistic and requires the current revision.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| document_id | string | 是 | Stable document_id or unambiguous occurrence_id. |
-| target_volume_id | string | 是 | Target volume_id from novel_reading_order. |
-| target_index | integer | 是 | Zero-based position inside the target volume. |
-| expected_revision | string | 是 | Fresh reading-order revision used for CAS. |
+| action | string | 是 | ["get","move"]；Reading-order operation. |
+| document_id | string | 否 | Stable document_id or unambiguous occurrence_id. |
+| target_volume_id | string | 否 | Target volume_id from novel_reading_order. |
+| target_index | integer | 否 | Zero-based position inside the target volume. |
+| expected_revision | string | 否 | Fresh reading-order revision used for CAS. |
 
 ## novel_reading_packet
 
 Read a bounded continuous-reading window around one stable manuscript document or occurrence id.
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
@@ -899,7 +633,7 @@ Reference-library pipeline (decomposing reference works into structured evidence
 
 Read one deep-research report by id (ids come from novel_research_status).
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
@@ -917,9 +651,9 @@ Save deep-research API settings (search/LLM providers, API keys, defaults). Pass
 
 ## novel_research_status
 
-Get the deep-research surface: settings status, report list, and the configured model route. Run a research job via novel_task_create with type "research".
+Get the deep-research surface: settings status, report list, and the configured model route. Run a research job via novel_task(action="create") with type "research".
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
@@ -947,102 +681,43 @@ Run OpenWrite's multi-dimensional review on a drafted manuscript chapter (LONG-R
 
 Inspect the canonical reusable chapter-review DAG blueprint: its version, revision, six quality domains, 37 checks, hard gates, dependencies, invariants, and extension points.
 
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| 无 | — | — | — |
-
-## novel_revision_apply
-
-Apply a staged revision proposal to the manuscript. Optionally override the generated text or apply only selected diff hunks. Fails with a conflict if the document changed since the proposal was created.
-
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| proposal_id | string | 是 | Revision proposal id (rev_*). |
-| replacement_text | string | 否 | Replacement text overriding the proposal. |
-| selected_hunk_ids | array[string] | 否 | Apply only these diff hunk ids. |
+| 无 | — | — | — |
 
-## novel_revision_create_from_review
+## novel_revision
 
-Create a revision proposal that addresses selected issues from a chapter review (LONG-RUNNING, model-generated). Issue ids come from novel_review_chapter's issue_details. Pass selection to constrain rewriting to an exact manuscript range; overlapping issue evidence never expands that range. The proposal is only staged — apply it with novel_revision_apply.
+List, inspect, create, regenerate, apply and reject revision proposals for a chapter. Create builds a proposal from review issues (source=review) or from an explicit text selection (source=selection); apply writes the accepted hunks into the manuscript.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| chapter_id | string | 是 | Chapter id (ch_<digits>). |
-| issue_ids | array[string] | 是 | Review issue ids to fix. |
+| action | string | 是 | ["list","get","create","regenerate","apply","reject"]；Revision operation; create reads its source from the source parameter. |
+| chapter | string | 否 | Chapter id filter (e.g. "ch_0007"). |
+| status | string | 否 | Status filter (e.g. "proposed", "applied", "rejected"). |
+| proposal_id | string | 否 | Revision proposal id (rev_*). |
+| source | string | 否 | ["review","selection"]；Create source: review (default) fixes review issues, selection revises an explicit text range. |
+| chapter_id | string | 否 | Chapter id (ch_<digits>). |
+| issue_ids | array[string] | 否 | Review issue ids to fix; required for create with source="review". |
 | selection | object | 否 | Optional exact saved-text range in Unicode code points; preserve raw CR/LF characters. |
 | instruction | string | 否 | Additional revision instruction. |
 | target_units | integer | 否 | Target length in writing units (0 = keep similar). |
 | expected_review_revision | string | 否 | Exact review file revision from the chapter work brief. |
 | expected_document_revision | string | 否 | Exact manuscript revision from the chapter work brief. |
-
-## novel_revision_create_selection
-
-Create a revision proposal for a text selection in a chapter (LONG-RUNNING, model-generated). start/end are Unicode code-point offsets in the exact saved text, including original CR/LF characters; pass the selected text as original_text and the current expected_document_revision. The proposal is only staged — apply it with novel_revision_apply.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| chapter_id | string | 是 | Chapter id (ch_<digits>). |
-| start | integer | 是 | Selection start offset. |
-| end | integer | 是 | Selection end offset. |
+| start | integer | 否 | Selection start offset. |
+| end | integer | 否 | Selection end offset. |
 | original_text | string | 否 | The selected original text. |
-| expected_document_revision | string | 否 | Current exact manuscript revision; reject before generation if the source changed. |
-| instruction | string | 否 | Revision instruction (max 4000 characters). |
-| action | string | 否 | ["rewrite","expand","compress","pace","dialogue","naturalize","custom"]；Revision mode (default "rewrite"). |
-| target_units | integer | 否 | Target length in writing units (0 = keep similar). |
+| mode | string | 否 | ["rewrite","expand","compress","pace","dialogue","naturalize","custom"]；Revision mode (default "rewrite"). |
 | full_chapter | boolean | 否 | Treat the whole chapter as the selection (default false). |
-
-## novel_revision_get
-
-Get one revision proposal with its diff hunks by proposal id (rev_*).
-
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| proposal_id | string | 是 | Revision proposal id (rev_*). |
-
-## novel_revision_regenerate
-
-Regenerate the text of a staged revision proposal (LONG-RUNNING, model-generated).
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| proposal_id | string | 是 | Revision proposal id (rev_*). |
-
-## novel_revision_reject
-
-Reject and discard a staged revision proposal. This permanently drops the generated text — it cannot be recovered except by regenerating.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| proposal_id | string | 是 | Revision proposal id (rev_*). |
-
-## novel_revisions_list
-
-List revision proposals, optionally filtered by chapter and/or status.
-
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| chapter | string | 否 | Chapter id filter (e.g. "ch_0007"). |
-| status | string | 否 | Status filter (e.g. "proposed", "applied", "rejected"). |
+| replacement_text | string | 否 | Replacement text overriding the proposal. |
+| selected_hunk_ids | array[string] | 否 | Apply only these diff hunk ids. |
 
 ## novel_rolling_plan_action
 
-Manage rolling plan candidates (mid-range plot planning windows). Actions: "list" (limit?), "create" (current_arc?, window_size? default 50, max 50). current_window/accepted_window is accepted manuscript facts only; next_window/planned_window is outline plan, not facts. "get" (candidate_id), "stage" (candidate_id + proposal + revision — stages a plan proposal against the candidate; revision-gated), "delete" (candidate_id + revision), "apply" (candidate_id + revision — appends staged draft chapters that do not collide with the canonical outline into src/outline.md; never writes accepted facts).
+Manage rolling plan candidates (mid-range plot planning windows). Actions: "list" (limit?), "create" (current_arc?, window_size? default 50, max 50). current_window/accepted_window is accepted manuscript facts only; next_window/planned_window is outline plan, not facts. "get" (candidate_id), "stage" (candidate_id + proposal + revision — stages a Markdown plan; chapter headings should read "第N章：标题" or "第N章 标题" and Chinese numerals are accepted; revision-gated), "delete" (candidate_id + revision), "apply" (candidate_id + revision — appends staged draft chapters that do not collide with the canonical outline into src/outline.md; never writes accepted facts; a proposal without recognizable chapter headings is reported as such instead of as "already exists").
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
@@ -1083,85 +758,47 @@ Inspect OpenWrite runtime skills. Actions: "list" (all discovered skills), "diag
 | intent | string | 否 | Intent hint for resolve. |
 | document_type | string | 否 | Document type hint for resolve. |
 
-## novel_scene_migration_apply
-
-Apply one freshly read scene migration preview. Requires the exact preview revision and explicit confirmation.
+## novel_scene
 
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| expected_preview_revision | string | 是 | Exact preview_revision from novel_scene_migration_preview. |
-| confirm | boolean | 是 | Must be true after the author approves the preview. |
-
-## novel_scene_migration_preview
-
-Build a read-only, exact-revision preview that segments existing chapters into stable scenes. This does not write a sidecar.
-
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| 无 | — | — | — |
-
-## novel_scene_migration_rollback
-
-Restore the byte-exact scene sidecar that preceded a migration, guarded by the current scene-structure revision.
+Read the scene structure of a chapter, update one scene, and move a scene to another chapter or position. Structure is read-only; update and move are optimistic and require the current revision.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| migration_id | string | 是 | Migration id returned by novel_scene_migration_apply. |
-| expected_revision | string | 是 | Fresh scene-structure revision used for CAS. |
-
-## novel_scene_move
-
-Move one complete scene within or across chapters with scene/source/target revision guards. Cross-chapter moves start the existing manuscript acceptance flow.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| scene_id | string | 是 | Stable scene id from novel_scene_structure. |
-| target_chapter_id | string | 是 | Target chapter id (ch_<digits>). |
-| target_index | integer | 是 | Zero-based scene position inside the target chapter. |
-| expected_revision | string | 是 | Fresh scene-structure revision. |
-| expected_source_revision | string | 是 | Fresh source chapter revision. |
-| expected_target_revision | string | 是 | Fresh target chapter revision. |
-
-## novel_scene_structure
-
-Read the canonical scene structure with stable scene ids, reading/story-time order, chapter revisions, references, freshness, and explicit issues.
-
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| 无 | — | — | — |
+| action | string | 是 | ["structure","update","move"]；Scene operation. |
+| scene_id | string | 否 | Stable scene id from novel_scene(action="structure"). |
+| expected_revision | string | 否 | Fresh scene-structure revision used for CAS. |
+| title | string | 否 | Optional scene title. |
+| story_time_sort_key | string | 否 | Optional lexical story-time sort key. |
+| story_time_label | string | 否 | Optional author-facing story-time label. |
+| characters | array[string] | 否 | Character references; replaces the current list when supplied. |
+| locations | array[string] | 否 | Location references; replaces the current list when supplied. |
+| events | array[string] | 否 | Event references; replaces the current list when supplied. |
+| target_chapter_id | string | 否 | Target chapter id (ch_<digits>). |
+| target_index | integer | 否 | Zero-based scene position inside the target chapter. |
+| expected_source_revision | string | 否 | Fresh source chapter revision. |
+| expected_target_revision | string | 否 | Fresh target chapter revision. |
 
-## novel_scene_update
+## novel_scene_migration
 
-CAS-update scene title, story time, and character/location/event references without changing manuscript prose.
+Preview, apply and roll back the paragraph-to-scene migration of one chapter. The preview is read-only; apply and rollback are guarded by the revisions the previous step reported.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| scene_id | string | 是 | Stable scene id from novel_scene_structure. |
-| expected_revision | string | 是 | Fresh scene-structure revision used for CAS. |
-| title | string | 否 | Optional scene title. |
-| story_time_sort_key | string | 否 | Optional lexical story-time sort key. |
-| story_time_label | string | 否 | Optional author-facing story-time label. |
-| characters | array[string] | 否 | Character references; replaces the current list when supplied. |
-| locations | array[string] | 否 | Location references; replaces the current list when supplied. |
-| events | array[string] | 否 | Event references; replaces the current list when supplied. |
+| action | string | 是 | ["preview","apply","rollback"]；Scene migration step; apply and rollback require the revision the previous step reported. |
+| expected_preview_revision | string | 否 | Exact preview_revision from novel_scene_migration(action="preview"). |
+| confirm | boolean | 否 | Must be true after the author approves the preview. |
+| migration_id | string | 否 | Migration id returned by novel_scene_migration(action="apply"). |
+| expected_revision | string | 否 | Fresh scene-structure revision used for CAS. |
 
 ## novel_search
 
 Search the novel project (semantic + exact match) across chapters, outline, and assets.
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
@@ -1171,7 +808,7 @@ Search the novel project (semantic + exact match) across chapters, outline, and
 
 ## novel_settle_backfill
 
-Settlement backfill for existing/imported chapters: replay the writer pipeline observer+settler over the actual chapter prose (never rewriting it) and commit chapter memory, runtime-truth notes and a character-state index refresh. Run once after importing an old manuscript so later chapters, reviews and canon/continuity checks have real facts from earlier chapters (without it, review canon stays inconclusive and context lacks previous-chapter recaps). Returns a background task (tsk_*); poll with novel_task_get.
+Settlement backfill for existing/imported chapters: replay the writer pipeline observer+settler over the actual chapter prose (never rewriting it) and commit chapter memory, runtime-truth notes and a character-state index refresh. Run once after importing an old manuscript so later chapters, reviews and canon/continuity checks have real facts from earlier chapters (without it, review canon stays inconclusive and context lacks previous-chapter recaps). Returns a background task (tsk_*); poll with novel_task(action="get").
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
@@ -1197,7 +834,7 @@ Style/setting source pipeline (learning from reference texts). Actions: "extract
 | chunk_id | string | 否 | Chunk to retry (retry_v2). |
 | source_ids | array[string] | 否 | Sources to synthesize (synthesize_v2). |
 | profile_id | string | 否 | Analysis profile id (profile_v2/promotion_preview_v2). |
-| target | string | 否 | Promotion target (promotion_preview_v2/promote, default "all"). |
+| target | string | 否 | Promotion target: style/rules/inspiration/setting_candidates for promotion_preview_v2 (required); style/setting/world/all for legacy promote (default "all"). |
 | preview_id | string | 否 | Promotion preview id (promote_v2). |
 | confirm | boolean | 否 | Confirm a gated promotion (default false). |
 
@@ -1205,24 +842,11 @@ Style/setting source pipeline (learning from reference texts). Actions: "extract
 
 Get a snapshot of the current OpenWrite novel project: title, chapters, word counts, writing targets, and focus compass.
 
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| 无 | — | — | — |
-
-## novel_structured_change_plan
-
-Stage one structured OpenWrite domain change without writing it. Supported change_kind values are "outline", "asset", "focus", "foreshadowing", and "writing_targets"; `change` uses the corresponding direct tool payload. Use action "preview" to receive an immutable token and entity-level before/after summary. Only after author acceptance pass that token unchanged to "apply". "reject" consumes it, "retry" rebuilds the same semantic change against current source, and "undo" accepts only the revision-bound undo token returned by apply. The server writes the exact validated preview and rejects source conflicts.
-
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| action | string | 是 | ["preview","apply","reject","retry","undo"]；Plan lifecycle action. |
-| change_kind | string | 否 | ["outline","asset","focus","foreshadowing","writing_targets"]；Structured domain for a preview. |
-| change | json | 否 | One direct-tool-shaped change object, required for preview. |
-| preview_token | string | 否 | Immutable preview or undo token for apply/reject/retry/undo. |
+| 无 | — | — | — |
 
 ## novel_sync
 
@@ -1234,74 +858,27 @@ Synchronize derived caches that are direct src derivatives: outline hierarchy (d
 | --- | --- | --- | --- |
 | 无 | — | — | — |
 
-## novel_task_cancel
-
-Request cancellation of a queued or running task. Check cancelled and cancellation_status for the actual outcome; poll novel_task_get while cancellation is requested.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| wait_seconds | number | 否 | Wait up to 30 seconds for actual cancellation; running model calls may finish later. |
-| task_id | string | 是 | Task id (tsk_*). |
-
-## novel_task_confirm
-
-Confirm a background task that is awaiting confirmation (e.g. a continuous_write run paused between chapters), letting it resume.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| task_id | string | 是 | Task id (tsk_*). |
-
-## novel_task_create
+## novel_task
 
-Queue a background AI task and return immediately; poll with novel_task_get. Task types and their `input` keys: chapter_write {chapter_id?, guidance?, target_words?, temperature?, outline_revision?}; chapter_review {chapter_id | path, strict?, dimensions?}; revision_selection / revision_from_review (same inputs as the novel_revision_create_* tools); source_operation / reference_operation (same inputs as novel_source_action / novel_reference_library_action); manuscript_import (same input as novel_import); research {prompt, search?, language?, quality?, llm?}; manuscript_reconcile (durable acceptance analysis; usually started through novel_manuscript_acceptance_reconcile); settle_backfill {chapter_ids?, only_missing?} — prefer the novel_settle_backfill convenience tool; continuous_write — prefer the novel_multi_write convenience tool.
+Queue a background AI task and return immediately; poll with get or list. Task types and their `input` keys: chapter_write {chapter_id?, guidance?, target_words?, temperature?, outline_revision?}; chapter_review {chapter_id | path, strict?, dimensions?}; revision_selection / revision_from_review (same inputs as the novel_revision create action); source_operation / reference_operation (same inputs as novel_source_action / novel_reference_library_action); manuscript_import (same input as novel_import); research {prompt, search?, language?, quality? (advisory|balanced|strict), llm?}; manuscript_reconcile (durable acceptance analysis; usually started through novel_manuscript_acceptance_reconcile); settle_backfill {chapter_ids?, only_missing?} - prefer the novel_settle_backfill convenience tool; continuous_write - prefer the novel_multi_write convenience tool.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
-| type | string | 是 | ["chapter_write","chapter_review","revision_selection","revision_from_review","source_operation","reference_operation","manuscript_import","manuscript_reconcile","continuous_write","research","settle_backfill"]；Task type. |
-| input | json | 是 | Task input object; shape depends on the task type (see description). |
-
-## novel_task_get
-
-Get one background task with its event log by task id (tsk_*). Completed chapter write/review/revision tasks refresh the chapter-delivery DoG graph; chapter reviews also materialize the 37-dimension graph.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| task_id | string | 是 | Task id (tsk_*). |
-
-## novel_task_retry
-
-Retry a failed or cancelled background task.
-
-影响：会提交操作或保存文件；具体取决于 action/参数。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
-| task_id | string | 是 | Task id (tsk_*). |
-
-## novel_tasks_list
-
-List background tasks (queued/running/finished AI jobs) with per-status counts.
-
-影响：只读查询（可更新检索缓存）。
-
-| 参数 | 类型 | 必填 | 允许值 / 说明 |
-| --- | --- | --- | --- |
+| action | string | 是 | ["create","get","list","cancel","confirm","retry"]；Task operation; long-running work returns a task id immediately. confirm resumes a paused run and returns a continuation task: poll the returned task_id; re-confirming the paused task is idempotent. |
+| type | string | 否 | ["chapter_write","chapter_review","revision_selection","revision_from_review","source_operation","reference_operation","manuscript_import","manuscript_reconcile","continuous_write","research","settle_backfill"]；Task type; required for create. |
+| input | json | 否 | Task input object; required for create. Shape depends on the task type (see description). |
+| task_id | string | 否 | Task id (tsk_*). |
 | since | string | 否 | ISO timestamp filter for requests whose response was lost. |
 | limit | integer | 否 | Maximum number of tasks (server default 100). |
+| wait_seconds | number | 否 | Wait up to 30 seconds for actual cancellation; running model calls may finish later. |
 
 ## novel_trace_list
 
 Inspect recent redacted Prompt→context→model→tool→domain traces. Raw prompts, context, model output, credentials, chain-of-thought, and mutation values are never stored.
 
-影响：只读查询（可更新检索缓存）。
+影响：会提交操作或保存文件；具体取决于 action/参数。
 
 | 参数 | 类型 | 必填 | 允许值 / 说明 |
 | --- | --- | --- | --- |
@@ -1309,7 +886,7 @@ Inspect recent redacted Prompt→context→model→tool→domain traces. Raw pro
 
 ## novel_write_chapter
 
-Queue a chapter write and immediately return a durable task_id. Poll novel_task_get for progress/result. Omit chapter_id to write the outline-recommended next chapter; a given chapter_id must match the current recommendation. Preview context first with novel_context_preview and consult novel_outline_read for the recommendation. Cancel with novel_task_cancel. Generated partial prose is retained; resume_from_draft continues it in a new run when the source/context revisions still match.
+Queue a chapter write and immediately return a durable task_id. Poll novel_task(action="get") for progress/result. Omit chapter_id to write the outline-recommended next chapter; a given chapter_id must match the current recommendation. Preview context first with novel_context_preview and consult novel_outline_read for the recommendation. Cancel with novel_task(action="cancel"). Generated partial prose is retained; resume_from_draft continues it in a new run when the source/context revisions still match.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。
 
@@ -1342,7 +919,7 @@ Read or save shared project terminology, review_terms toggle, concrete noun lexi
 
 ## novel_writing_targets
 
-Immediate compatibility write for targets the author has already authorized exactly; otherwise use novel_structured_change_plan. Update the project writing targets. Ranges: book_words 10000-5000000, chapter_words 200-50000, outline_volume_words 100-5000, outline_act_words 80-3000, outline_section_words 50-2000, outline_chapter_words 30-1000. Omitted fields keep their current values.
+Immediate compatibility write for targets the author has already authorized exactly; otherwise use novel_change_plan(action="structured"). Update the project writing targets. Ranges: book_words 10000-5000000, chapter_words 200-50000, outline_volume_words 100-5000, outline_act_words 80-3000, outline_section_words 50-2000, outline_chapter_words 30-1000. Omitted fields keep their current values.
 
 影响：会提交操作或保存文件；具体取决于 action/参数。