webnovel-write

章の執筆手順

目標

公開可能な章を 正文/第{NNNN}章-{title}.md に出力します。デフォルトは2000～2500字です。ユーザーやアウトラインに別の指定がある場合は、そちらに従います。

モード

モード	手順
デフォルト	Step 1→2→3→4→5→6
--fast	Step 1→2→3（軽量）→4→5→6
--minimal	Step 1→2→3（no-review artifactを作成）→4（フォーマットのみ）→5→6

絶対ルール

• 手順の統合、スキップ、審査の偽造は禁止です。
• 指定された subagent の呼び出しには必ず Agent ツールを使用してください。メインフローの口頭説明で subagent の出力を代替してはいけません。
• 審査は1回のみ実行します。blocking issue は対象箇所を修正するか、ユーザーの裁定を経てから Step 4／5 に進みます。
• 失敗した場合は失敗した手順のみを再実行し、前の手順に戻ってはいけません。
• 参考資料は各手順で必要に応じて読み込みます。

優先順位

ユーザーの要求 > ステートマシンの絶対的なゲート条件 > プロジェクトの制約（全体方針／設定／記憶）> skill の手順 > reference の提案

CSV の検索（Step 2 で必要に応じて）

python -X utf8 "${SCRIPTS_DIR}/reference_search.py" --skill write --table {表名} --query "{关键词}" --genre {题材}

実行条件：新キャラクター→命名規則、戦闘→シーンの書き方、複数キャラクターの会話→執筆技法、感情描写→執筆技法、頻出する場面→シーンの書き方。

実行手順

準備：事前チェック

export WORKSPACE_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
export SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT:?}/scripts"
export SKILL_ROOT="${CLAUDE_PLUGIN_ROOT:?}/skills/webnovel-write"

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" preflight
export PROJECT_ROOT="$(python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" where)"

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" placeholder-scan --format text

準備：契約ツリーの更新

genre は .webnovel/state.json の初期化設定スナップショットから読み取り、契約ツリーの更新に使用します。執筆前のメインチェーンにおける真の情報源は、引き続き .story-system/ の契約です。story-system を呼び出す前に、必ず詳細アウトラインから実際の本章の目標を解析してください。{章纲目标}、第N章章纲目标 などのプレースホルダー query を渡すことは禁止です。

GENRE="$(python -X utf8 -c "import json,sys; s=json.load(open('${PROJECT_ROOT}/.webnovel/state.json',encoding='utf-8')); pi=s.get('project_info',{}); print(pi.get('genre') or s.get('project',{}).get('genre',''))")"

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
  story-system "${CHAPTER_GOAL}" --genre "${GENRE}" --chapter {chapter_num} --persist --emit-runtime-contracts --format both

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
  write-gate --chapter {chapter_num} --stage prewrite --format json

必須ファイル：MASTER_SETTING.json（トーン／禁止事項）、volume_{NNN}.json（巻単位の展開）、chapter_{NNN}.review.json（必須ノード／禁止領域）。いずれかが欠けている場合は処理を中断します。

chapter_{NNN}.json では、トップレベルの chapter_directive を必ず最優先で確認してください。chapter_focus の情報源は chapter_directive.goal または実際の query に限ります。dynamic_context の参考要約から引き継いではいけません。

執筆タスク指示書の順序は、必ず次のとおりにしてください。

1. 本章の必須制約：chapter_directive.goal/time_anchor/chapter_span/countdown/chapter_end_open_question
2. CBN／CPNs／CEN と must_cover_nodes
3. 本章の禁止領域：forbidden_zones。違反した場合は不合格です。
4. スタイル指針：reasoning、主人公のキャラクター逸脱に対する警戒、anti_patterns
5. シーンの書き方に関する補足：dynamic_context。スタイルの参考としてのみ使用し、章のアウトラインの制約を上書きしてはいけません。

Step 1：context-agent が執筆タスク指示書を作成

必ず Agent ツールを使用して context-agent を呼び出してください。メインフローでタスク指示書を独自にまとめてはいけません。

Use the Agent tool to run webnovel-writer:context-agent.

Task:

• chapter={chapter_num}
• project_root=${PROJECT_ROOT}
• scripts_dir=${SCRIPTS_DIR}
• storage_path=${PROJECT_ROOT}/.webnovel
• state_file=${PROJECT_ROOT}/.webnovel/state.json（projection/read-model。互換性のための読み取り専用）
• まず research を行い、次に 本章の必須制約 → CBN／CPNs／CEN → 本章の禁止領域 → スタイル指針 → dynamic_context による補足参考 の順で、5段落の執筆タスク指示書を出力する。
• コンテキストが不足している場合は blocker を返す。

成果物：Step 2 の草稿を単独で作成できる執筆タスク指示書。

呼び出し後、メインフローでは SubagentRun の概要を記録してください（最終レポートでのみ使用）。

{
  "name": "context-agent",
  "user_label": "整理写作依据",
  "status": "completed | partial | failed | skipped",
  "problems": [],
  "auto_handled": [],
  "needs_user_action": false,
  "duration_ms": 0,
  "outputs": []
}

コンテキスト不足、legacy fallback、伏線データの欠落、タスク指示書の不完全さ、または所要時間の異常は、必ず problems／auto_handled に記録し、最終レポートで黙って済ませてはいけません。

Step 2：本文の草稿を作成

タスク指示書のみに基づいて草稿を作成します。core-constraints／anti-ai-guide は読み込みません（すでにタスク指示書に反映されています）。プレースホルダーのない本文のみを出力します。構造化ノードがある場合は、CBN→CPNs→CEN を軸に展開します。中国語で考えながら執筆します。

Step 3：審査

必ず Agent ツールを使用して reviewer を呼び出してください。メインフローで審査 JSON を偽造してはいけません。

Use the Agent tool to run webnovel-writer:reviewer.

Task:

• chapter={chapter_num}
• chapter_file=${CHAPTER_FILE}
• project_root=${PROJECT_ROOT}
• scripts_dir=${SCRIPTS_DIR}
• reviewer schema に厳密に準拠した JSON のみを返し、ファイルには何も書き込まない。
• 採点せず、口頭で要約しない。

reviewer は JSON のみを返します。メインフローは Write を使用し、返された JSON を ${PROJECT_ROOT}/.webnovel/tmp/review_results.json に書き込んでください（reviewer は Write を持たず、この artifact の非書き込み側です）。その後、必ず review-pipeline を実行してください。review-pipeline は同じパスを標準の review_result artifact（blocking_count を含む）で上書きし、precommit gate および後続のコミットコマンドで使用できるようにします。

呼び出し後、メインフローでは SubagentRun の概要を記録してください（最終レポートでのみ使用）。

{
  "name": "reviewer",
  "user_label": "写作检查",
  "status": "completed | partial | failed | skipped",
  "problems": [],
  "auto_handled": [],
  "needs_user_action": false,
  "duration_ms": 0,
  "outputs": []
}

reviewer のスキップ、失敗、出力の不完全さ、--minimal での no-review artifact の作成、blocking issue、次元のスキップ、または所要時間の異常は、必ず problems／auto_handled に記録し、最終レポートで黙って済ませてはいけません。

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" review-pipeline \
  --chapter {chapter_num} \
  --review-results "${PROJECT_ROOT}/.webnovel/tmp/review_results.json" \
  --metrics-out "${PROJECT_ROOT}/.webnovel/tmp/review_metrics.json" \
  --report-file "审查报告/第{chapter_num}章审查报告.md" \
  --save-metrics

審査は1回のみ実行し、reviewer の呼び出しも1回のみとします。blocking=true の問題は、ストーリーを変更せず、設定を破らない範囲で対象箇所を修正した後、そのまま Step 4 に進みます。reviewer を再度呼び出してはいけません。修正できない blocking issue がある場合は、AskUserQuestion を使用してユーザーに裁定を求めます（現在のバージョンを受け入れる／手動で修正する／破棄する）。非 blocking issue は Step 4 で対応します。--fast では setting／timeline／continuity のみを確認します。

--minimal では reviewer と review-pipeline を呼び出しません。ただし、その章の新しい no-review review_results.json を必ず上書きして書き込みます（古い artifact の再利用は禁止）。これにより、Step 5 のコミットチェーンで有効な --review-result を使用できます（成功条件「審査が保存済み」は、--minimal では引き続き適用除外です）。

python -X utf8 -c "import json,os; from pathlib import Path; root=Path(os.environ['PROJECT_ROOT']); ch=int('{chapter_num}'); p=root/'.webnovel'/'tmp'/'review_results.json'; p.parent.mkdir(parents=True,exist_ok=True); p.write_text(json.dumps({'chapter':ch,'issues':[],'issues_count':0,'blocking_count':0,'has_blocking':False,'summary':'minimal mode: reviewer skipped by user-selected --minimal flow','review_skipped':True,'review_mode':'minimal'},ensure_ascii=False,indent=2),encoding='utf-8')"

Step 4：推敲

references/polish-guide.md の該当箇所を読むときは、まず Grep で ^#{1,3} に一致する見出しを検索してアンカー行番号を特定し、次に Read の offset／limit で該当範囲を取得します。メイン経路では ## 2. 执行顺序（必须按序） を取得します。Anti-AI 最終チェックは別の区間から取得し、## 2A. Anti-AI 检测细则 と ## Phase 1 增补：Anti-AI 规范（7层，原版）（用語集の区間）を読みます。全文を読んではいけません。references/writing/typesetting.md と references/style-adapter.md は短いファイルなので、全文を読みます。

順序：非 blocking issue の修正 → スタイル調整 → フォーマット → Anti-AI 最終チェック。

表現のみを変更し、事実は変更しません。anti_ai_force_check=fail の場合は Step 5 に進みません。--minimal ではフォーマットのみを行います。

Step 5：コミット

5.1 Data Agent による事実の抽出

Agent ツールを使用して data-agent を呼び出し、fulfillment_result / disambiguation_result / extraction_result の3つの JSON を生成し、Step 3 の review_results を再利用します。

Agent ツールを使用して webnovel-writer:data-agent を実行します。

Task:

• chapter={chapter_num}
• chapter_file=${CHAPTER_FILE}
• project_root=${PROJECT_ROOT}
• scripts_dir=${SCRIPTS_DIR}
• output_dir=${PROJECT_ROOT}/.webnovel/tmp
• 独自のスキーマ（data-agent 出力形式のセクションを参照）に従って、fulfillment_result.json、disambiguation_result.json、extraction_result.json の3つの artifact を生成します。
• これら3つの artifact の唯一の書き込み担当者です。state/index/summaries/memory/vectors/projection は直接書き込みません。

artifact のフィールドスキーマは data-agent 自身が定義し、runtime validator が検証します。メインフローではファイルの存在とスキーマのみを確認し、書き換えたり、補完したり、口頭で代用したりしません。

呼び出し後、メインフローは SubagentRun の概要を記録する必要があります（最終レポートでのみ使用）：

{
  "name": "data-agent",
  "user_label": "保存本章故事事实",
  "status": "completed | partial | failed | skipped",
  "problems": [],
  "auto_handled": [],
  "needs_user_action": false,
  "duration_ms": 0,
  "outputs": []
}

3つの artifact の書き込み状態、スキーマ不適合、未解決の曖昧さ、長時間の進展停止、出力の不完全さは、必ず problems に記録します。自動再実行またはフォールバック処理は、必ず auto_handled に記録します。

5.2 コミット前の検証と CHAPTER_COMMIT

まず precommit gate を実行します：

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
  write-gate --chapter {chapter_num} --stage precommit --format json

precommit の通過後、コミット前に読み取り専用の git diff 変更範囲検証（書き込み所有権の健全性チェック。読み取り専用で、stage・コミットはしません）を実行します：

if git -C "${PROJECT_ROOT}" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  git -C "${PROJECT_ROOT}" diff --name-status -- .
  git -C "${PROJECT_ROOT}" diff --check -- .
fi

変更範囲に、プラグインディレクトリ、他の書籍プロジェクト、他の章の本文、本章のフローに属さない手書きの状態ファイルが含まれていてはなりません。git diff が対象とするのは Git から確認できるファイルのみです。SQLite / .webnovel/ 内部の意味検証は、5.3 の postcommit と runtime の読み取り専用クエリで確認します。プロジェクトルートが git worktree でない場合は「git diff 検証をスキップ」と記録しますが、それを理由に precommit gate をスキップしてはいけません。この手順は読み取り専用です。ここで git add / git commit を実行してはいけません。

検証に合格したら、chapter-commit を実行します：

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" chapter-commit \
  --chapter {chapter_num} \
  --review-result "${PROJECT_ROOT}/.webnovel/tmp/review_results.json" \
  --fulfillment-result "${PROJECT_ROOT}/.webnovel/tmp/fulfillment_result.json" \
  --disambiguation-result "${PROJECT_ROOT}/.webnovel/tmp/disambiguation_result.json" \
  --extraction-result "${PROJECT_ROOT}/.webnovel/tmp/extraction_result.json"

自動判定：blocking_count>0、または missed_nodes が空でない、または pending が空でない場合は rejected、それ以外は accepted です。

5.3 projection の検証

projection_status の5項目（state/index/summary/memory/vector）は、すべて done または skipped である必要があります。

chapter_status は projection writer によって自動的に更新されます：accepted→committed、rejected→rejected。

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
  write-gate --chapter {chapter_num} --stage postcommit --format json

5.4 失敗の切り分け

commit が生成されていない場合→5.2 を再実行します。projection に失敗した場合→projection のみを再実行し、Step 1-4 には戻りません。

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
  projections retry --chapter {chapter_num} --format json

Step 6：Git バックアップ

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" backup \
  --chapter {chapter_num} \
  --chapter-title "{title}"

バックアップでは、解析済みの PROJECT_ROOT を基準にする必要があります。書籍プロジェクトのリポジトリが親リポジトリの埋め込みリポジトリ/submodule として追加されるのを防ぐため、ワークスペースの親ディレクトリから Git の全件追加を実行してはいけません。

作者に配慮した進行状況の案内と復旧の契約

章の執筆を始める前に、今回の目標、主な段階、付き添いが必要かどうかを作者の言葉で説明します。所要時間を確約してはいけません。進行状況の案内では、現在の作業内容と生成されるものだけを伝え、生の JSON、traceback、長いコマンドログは直接出力しません。技術的な詳細は .webnovel/logs/run_last.log に記録します：

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" run-log \
  --event write-start \
  --payload-json "{\"chapter\": {chapter_num}, \"mode\": \"{mode}\"}" \
  --format text

章の執筆プロセスの節目（最大 6 件）：

1. プロジェクト環境を確認：プロジェクト、プレースホルダー、本章の要件が利用可能であることを確認します。
2. 執筆の根拠を整理：章のプロット、直近の展開、未回収の伏線を読み込みます。
3. 本文を起草：執筆タスクの指示書に基づいて本章の本文を生成します。
4. 執筆内容を確認：ブロッキングの問題と、効果の高い修正案を確認します。
5. 本章の物語上の事実を保存：本章の目標達成状況、曖昧さ、新たな事実を抽出します。
6. コミットとバックアップ：本章の事実を記録し、物語資料を更新してバックアップします。

同じ章を再実行する場合は、まず信頼できる再開地点を読み込みます：

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" run-ledger write-resume \
  --chapter {chapter_num} \
  --mode "{mode}" \
  --format json

run-ledger write-resume は再開の提案のみを行い、ファイルを自動的に上書きしません。本文、レビュー結果、data artifact、commit、projection、バックアップの状態に基づいて、どこから続行するかを判断します。本文が手動で変更されている場合、章のプロットの更新日時が本文より後の場合、本章がすでに accepted なのに再実行される場合は、必ず停止して、現在の本文を使う／再起草する／状態のみ確認する、という限られた選択肢を提示して確認します。作者が手動で変更した内容を上書きしてはいけません。

各重要手順の完了後に run-ledger record-write-step を記録します。少なくとも step、status、入力／出力ファイルのパス、problems、auto_handled、duration_ms を記録し、次回の再開と最終レポートで使用します。

確認を最小限にする方針：デフォルトでは処理を続行します。創作の方向性、事実の整合性、ファイル上書きのリスク、または blocking issue を特定して処理できない場合に限り、質問します。ユーザーの判断が必要な場合は、2～3個の限られた選択肢を提示し、それぞれの選択が及ぼす影響を説明します。

行き詰まった場合は、問題箇所、完了済みの内容、復旧案を必ず説明します。例：「本文とレビュー報告は保持されていますが、本章の物語上の事実の保存に失敗しました。/webnovel-write {chapter_num} を再実行すると、data-agent から続行します」。復旧不能な障害の場合に限り、最終レポートで .webnovel/logs/run_last.log を案内します。通常はログを保持するだけにし、作者の作業を妨げません。

完了時には必ず作者向けレポートヘルパーを呼び出し、最終回答の構成にはヘルパーの出力を優先して使用します：

python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" user-report \
  --stage write \
  --chapter {chapter_num} \
  --format text

十分性ゲート

1. 本文ファイルが存在し、空でない
2. レビューが保存されている（--minimal を除く）
3. blocking=true の場合は Step 3 で問題を特定して修正するか、ユーザーの判断を得る
4. anti_ai_force_check=pass（--minimal を除く）
5. accepted の CHAPTER_COMMIT があり、projection の5項目が done/skipped
6. chapter_status=committed（projection が自動的に更新）
7. write-gate の prewrite / precommit / postcommit がすべて通過

失敗からの復旧

レビューがない場合→Step 3 を再実行します。要約／状態／メモリーがない場合→Step 5 を再実行します。推敲によって内容が歪んだ場合→Step 4 に戻って修正してから、Step 5 を再実行します。

作者に配慮した最終レポートの契約

最終回答は作者向けとし、生の JSON、traceback、長いコマンドログは出力しません。固定の3部構成とし、最初に総合ステータスを一文で示します：

总状态：已完成 / 部分完成 / 需要你处理 / 未完成。

一、产生的文件与完成情况
- ...

二、过程中遇到的问题与异常耗时
- 已自动处理：...
- 建议确认：...
- 必须处理：...

三、下一步建议
- ...

必ず以下を報告します：

• 本文ファイルのパス。
• レビュー報告のパス。
• .webnovel/tmp/review_results.json。
• .webnovel/tmp/fulfillment_result.json。
• .webnovel/tmp/disambiguation_result.json。
• .webnovel/tmp/extraction_result.json。
• .story-system/commits/chapter_{NNN}.commit.json。
• state / index / summary / memory / vector の更新状態。
• バックアップの状態。
• 次の章の執筆を続けられるかどうか。

ステータスのルール：

• chapter-commit rejected、いずれかの write-gate が failed、または projection が failed の場合、最終ステータスに「完了」と記載してはいけません。
• --fast と --minimal によるスキップ項目は明記します。--minimal でレビューをスキップした場合は「自動処理済み」または「確認推奨」に分類し、完全なレビューが完了したかのように扱ってはいけません。
• projection retry が発生した場合は、自動処理した内容と最終結果を必ず説明します。

例外の分類：

• 自動処理済み：projection retry の成功、結果に影響しない RAG の一時的なフォールバック、古い no-review artifact の本章の新しい artifact による置き換え。
• 確認推奨：新しいキャラクター名／設定名、ブロッキングではない信頼度の低い曖昧さ、ブロッキングではないレビュー提案。
• 要対応：未解決の blocking issue、data artifact の欠落またはスキーマの不完全さ、commit rejected、projection failed。

次のステップの提案では、タスク形式の表現とコピー可能なコマンドを使用します。例：

- 接下来可以写下一章：
  /webnovel-write {next_chapter}

トークン数は記載しません。障害の調査が必要な場合は、ログのパスを示すか、/webnovel-doctor の実行を提案します。