webnovel-write

Chapter Writing Workflow

Goal

Produce a publishable chapter to 正文/第{NNNN}章-{title}.md. Default 2000-2500 words; follow user/outline requirements if otherwise specified.

Mode

Mode	Workflow
Default	Step 1→2→3→4→5→6
--fast	Step 1→2→3(lightweight)→4→5→6
--minimal	Step 1→2→3(write no-review artifact)→4(formatting only)→5→6

Hard Rules

• Merging steps, skipping steps, and faking review are prohibited
• Must use Agent tool call to specify subagent; must not substitute subagent output verbally in the main workflow
• Review runs only one round; only after targeted fixes for blocking issues or user adjudication may Step 4/5 proceed
• On failure, only re-run the failed step; do not roll back
• Load reference materials on demand per step

Priority

User requirements > state machine hard gates > project constraints (master outline/settings/memory) > skill workflow > reference suggestions

CSV Retrieval (on demand in Step 2)

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

Trigger conditions: new character→naming rules, combat→scene writing method, multi-character dialogue→writing techniques, emotional description→writing techniques, high-frequency tropes→scene writing method.

Execution Workflow

Preparation: Pre-check

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

Preparation: Refresh contract tree

genre is read from the initialization config snapshot of .webnovel/state.json , used to refresh the contract tree; the true source of the main chain before writing is still the .story-system/ contract. Before calling story-system, the real chapter goal must first be parsed from the detailed outline; passing placeholder queries such as {章纲目标}、第N章章纲目标 is prohibited.

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

Required files:MASTER_SETTING.json(tone/taboos),volume_{NNN}.json(volume-level pacing),chapter_{NNN}.review.json(mandatory nodes/forbidden zones). Block if missing.

chapter_{NNN}.json Must prioritize checking the top-level chapter_directive。chapter_focus can only come from chapter_directive.goal or a real query, and must not be inherited from the reference summary of dynamic_context .

The writing task brief order must be fixed as:

1. Hard constraints for this chapter:chapter_directive.goal/time_anchor/chapter_span/countdown/chapter_end_open_question
2. CBN/CPNs/CEN and must_cover_nodes
3. Forbidden zones for this chapter:forbidden_zones, violation means fail
4. Style guidance: reasoning, protagonist card OOC warning, anti_patterns
5. Scene writing method supplement:dynamic_context, for style reference only, cannot override chapter outline constraints

Step 1: context-agent generates the writing task brief

Must use Agent tool call context-agent, must not organize the task brief in the main workflow itself.

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, compatibility read only)
• Research first, then output the five-section writing task brief in the order: hard constraints for this chapter → CBN/CPNs/CEN → forbidden zones for this chapter → style guidance → dynamic_context supplementary reference.
• Return blocker when context is insufficient.

Artifact: a writing task brief that can independently support Step 2 drafting.

After the call, the main workflow must record the SubagentRun summary (for final report use only):

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

Insufficient context, legacy fallback, missing foreshadowing data, incomplete task brief, or abnormal duration must be written to problems / auto_handled, and must not be silent in the final report.

Step 2: Draft the main text

Draft only according to the task specification. Do not load core-constraints/anti-ai-guide (already internalized into the task specification). Output only the main text, with no placeholders. When there are structured nodes, develop around CBN→CPNs→CEN. Write with Chinese thinking.

Step 3: Review

Must use the Agent tool call reviewer, and the main flow must not forge the review 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}
• Return only strict reviewer schema JSON, and do not write any files.
• Do not score, and do not give an oral summary.

The reviewer returns only JSON; the main flow is responsible for using Write to write the returned JSON into ${PROJECT_ROOT}/.webnovel/tmp/review_results.json(the reviewer does not hold Write and is a non-writer of this artifact). Then review-pipeline must be run; review-pipeline will overwrite the same path with the standard review_result artifact (including blocking_count), for use by the precommit gate and subsequent submission commands.

After the call, the main flow must record the SubagentRun summary (for the final report only):

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

If the reviewer skips, fails, outputs incomplete,--minimal writes a no-review artifact, has a blocking issue, skips a dimension, or has an abnormal duration, it must be written into problems / auto_handled, and must not be silent in the final report.

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

Review runs only one round, and the reviewer is called only once.blocking=true After issues are fixed in a targeted way without changing the plot or breaking the setting, proceed directly to Step 4 without calling the reviewer again; blocking issues that truly cannot be fixed use AskUserQuestion to let the user adjudicate (accept the current version / fix manually / abandon). Non-blocking issues are left to Step 4.--fast Only checks setting/timeline/continuity.

--minimal Do not call the reviewer and review-pipeline, but mustoverwrite and writethis chapter's new no-review review_results.json(reusing old artifacts is prohibited), so that the Step 5 submission chain has a valid --review-result(the exemption in the success criterion "review has been persisted" for --minimal still holds):

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: Polishing

references/polish-guide.md For section reading: first Grep match ^#{1,3} to locate the anchor line number, then Read use offset/limit to take the section—the main path takes ## 2. 执行顺序（必须按序）; the Anti-AI final check separately takes ## 2A. Anti-AI 检测细则 and ## Phase 1 增补：Anti-AI 规范（7层，原版）(the vocabulary section), and does not read the full text.references/writing/typesetting.md、references/style-adapter.md For a short file, read the full text.

Order: fix non-blocking issues → style adaptation → formatting → Anti-AI final check.

Only change expression, not facts.anti_ai_force_check=fail Do not proceed to Step 5 when--minimal is only formatting.

Step 5: Submission

5.1 Data Agent extracts facts

Must use the Agent tool call data-agent, produce the three JSON files fulfillment_result / disambiguation_result / extraction_result, and reuse Step 3's review_results.

Use the Agent tool to run 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
• Generate the three artifacts fulfillment_result.json, disambiguation_result.json, and extraction_result.json according to your own schema (see the data-agent output format section).
• You are the sole writer of these three artifacts; do not directly write state/index/summaries/memory/vectors/projection.

The artifact field schema is defined by data-agent itself and validated by the runtime validator; the main flow only checks that the files exist and the schema, and does not rewrite, supplement, or verbally replace them.

After the call, the main flow must record the SubagentRun summary (for the final report only):

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

If any of the three artifacts fails to write, the schema is non-compliant, pending disambiguation exists, there is no progress for a long time, or the output is incomplete, it must be written to problems; automatic reruns or degraded handling must be written to auto_handled。

5.2 Pre-commit validation and CHAPTER_COMMIT

First run the precommit gate:

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

After precommit passes, run the pre-commit read-only git diff change-surface validation (write-ownership sanity check, read-only, no staging, no commit):

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

The change surface must not contain plugin directories, other book projects, other chapters' body text, or handwritten state files that do not belong to this chapter's workflow;git diff it only covers git-visible files; SQLite / .webnovel/ internal semantics are verified by 5.3 postcommit and runtime read-only queries. If the project root is not a git worktree, record "skip git diff validation", but do not skip the precommit gate because of this. This step is read-only; executing git add/git commit。

After validation passes, run 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"

Automatic determination: blocking_count>0 or missed_nodes non-empty or pending non-empty → rejected, otherwise accepted.

5.3 Verify projection

All five projection_status items (state/index/summary/memory/vector) are done or skipped.

chapter_status is automatically advanced by the 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 Failure isolation

commit not generated→rerun 5.2. projection failure→only rerun projection, do not roll back Step 1-4.

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

Step 6: Git backup

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

The backup must be based on the resolved PROJECT_ROOT ; it is forbidden to execute a bare full Git add from the workspace parent directory, to avoid adding the book project repository as an embedded repository/submodule of the parent repository.

Author-friendly process prompts and recovery contract

Before starting to write a chapter, first explain in the author's language the goal of this session, the main stages, and whether they need to stay nearby; do not promise a fixed duration. Process prompts only say what is currently being done and what will be produced; do not directly output raw JSON, tracebacks, or long command logs; technical details are written to .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

Chapter-writing process nodes (at most 6):

1. Check the project environment: confirm the project, placeholders, and this chapter's requirements are available.
2. Organize the writing basis: read the chapter outline, recent plot, and unresolved foreshadowing.
3. Draft the body text: generate this chapter's body text according to the writing task document.
4. Writing check: review blocking issues and high-value revision suggestions.
5. Save this chapter's story facts: extract this chapter's goal completion status, ambiguities, and new facts.
6. Commit and back up: record this chapter's facts, update story materials, and back up.

When repeatedly executing the same chapter, first read the trusted breakpoint:

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 only gives continuation suggestions and does not automatically overwrite files. It determines where to continue based on the body text, review results, data artifacts, commit, projection, and backup status. If the body text has been manually modified, the chapter outline was updated later than the body text, or this chapter has already been accepted and is being rerun, it must stop and ask with limited options: keep the current body text / redraft / only view status; it must not overwrite the author's manual changes.

After each key step is completed, record run-ledger record-write-step, at least recording step, status, input/output file paths, problems, auto_handled, and duration_ms, for use in the next continuation and the final report.

Low-interruption confirmation strategy: by default, continue advancing; ask only when the creative direction, factual consistency, file overwrite risk, or a blocking issue cannot be handled in a targeted way. When user adjudication is needed, give 2-3 limited options and explain the impact of each option.

When stuck, you must state the blocking point, what has been completed, and recovery suggestions: for example, "The main text and review report have been retained; saving this chapter's story facts failed; rerunning /webnovel-write {chapter_num} will continue from data-agent." Only unrecoverable failures should be indicated in the final report prompt .webnovel/logs/run_last.log; ordinarily only keep logs and do not disturb the author.

At wrap-up, you must call the author report helper, and preferably organize the final reply based on the helper output:

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

Sufficiency gate

1. The main text file exists and is non-empty
2. Review has been persisted (--minimal excluded)
3. blocking=true must be fixed in a targeted way in Step 3 or adjudicated by the user
4. anti_ai_force_check=pass（--minimal excluded)
5. accepted CHAPTER_COMMIT, projection five items done/skipped
6. chapter_status=committed (projection automatically advances)
7. write-gate 's prewrite / precommit / postcommit all pass

Failure recovery

Review missing→rerun Step 3. Summary/state/memory missing→rerun Step 5. Polishing distortion→go back to Step 4 to fix, then rerun Step 5.

Author-friendly final report contract

The final reply must be author-facing and must not output raw JSON, traceback, or long command logs. Use a fixed three-part structure and begin with a one-sentence overall status:

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

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

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

三、下一步建议
- ...

Must report:

• Main text file path.
• Review report path.
• .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 update status.
• Backup status.
• Whether writing the next chapter can continue.

Status rules:

• chapter-commit rejected, any write-gate failed, or projection failed, the final status must not say "completed".
• --fast and --minimal skipped items must be explained;--minimal when review is skipped, it must be classified as "automatically handled" or "recommended for confirmation", and must not pretend that a full review was completed.
• When projection retry occurs, it must be explained that it was automatically handled and what the final result was.

Exception classification:

• Automatically handled: projection retry succeeded, RAG temporarily degraded but did not affect the result, old no-review artifact was overwritten by this chapter's new artifact.
• Recommended for confirmation: new character names / setting names, low-confidence ambiguity but non-blocking, non-blocking review suggestions.
• Must be handled: blocking issue not adjudicated, data artifacts missing or schema incomplete, commit rejected, projection failed.

Next-step suggestions must use task-oriented language + copyable commands, for example:

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

Do not write token statistics; if troubleshooting is needed, only give the log path or suggest running /webnovel-doctor。