webnovel-write

name	webnovel-write
description	产出可发布章节，完整执行上下文→起草→审查→润色→提交→备份。
version	6.0.0
tags	["writing","novel","chapter","drafting"]
requires_tools	["read_file","write_file","patch","search_files","terminal","clarify"]
requires_toolsets	["file","terminal"]

写章流程

目标

产出可发布章节到 正文/第{NNNN}章-{title}.md。默认 2000-2500 字，用户/大纲另有要求时从之。

模式

模式	流程
默认	Step 1→2→3→4→5→6
--fast	Step 1→2→3(轻量)→4→5→6
--minimal	Step 1→2→4(仅排版)→5→6

硬规则

• 禁止并步、跳步、伪造审查
• 必须使用 Agent 工具调用指定 subagent；不得用主流程口头代替 subagent 输出
• 审查只跑一轮；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="${WORKSPACE_ROOT:-$PWD}"
export SCRIPTS_DIR="${SKILL_ROOT_DIR:?}/scripts"
export SKILL_ROOT="${SKILL_ROOT_DIR:?}/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')); print(s.get('project',{}).get('genre',''))")"

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

必备文件：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、主角卡 OOC 警戒、anti_patterns
5. 场景写法补充：dynamic_context，仅作风格参考，不能覆盖章纲约束

Step 1：context-agent 生成写作任务书

必须使用 Agent 工具调用 context-agent，不得由主流程自行整理任务书。

Agent(
  subagent_type: "webfission-creative:context-agent",
  prompt: "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补充参考 的顺序输出五段写作任务书。"
)

产物：一份写作任务书，能独立支撑 Step 2 起草。

Step 2：起草正文

只根据任务书起草。不加载 core-constraints/anti-ai-guide（已内化到任务书）。只输出纯正文，无占位符。有结构化节点时围绕 CBN→CPNs→CEN 展开。中文思维写作。

Step 3：审查

必须使用 Agent 工具调用 reviewer，不得由主流程伪造审查 JSON。

Agent(
  subagent_type: "webfission-creative:reviewer",
  prompt: "chapter={chapter_num}; chapter_file=${CHAPTER_FILE}; project_root=${PROJECT_ROOT}; scripts_dir=${SCRIPTS_DIR}。严格输出 reviewer schema JSON，并保存到 ${PROJECT_ROOT}/.webnovel/tmp/review_results.json。"
)

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

审查只跑一轮，reviewer 只调用一次。blocking=true 的问题在不改剧情、不破设定的前提下定点修复后直接进 Step 4，不重新调用 reviewer；确实无法修复的 blocking 问题用 AskUserQuestion 让用户裁决（接受当前版本 / 手动修复 / 放弃）。非 blocking issue 交给 Step 4 处理。--fast 只检查 setting/timeline/continuity。--minimal 跳过。

Step 4：润色

加载 polish-guide.md、typesetting.md、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 三份 JSON，并复用 Step 3 的 review_results。

Agent(
  subagent_type: "webfission-creative:data-agent",
  prompt: "chapter={chapter_num}; chapter_file=${CHAPTER_FILE}; project_root=${PROJECT_ROOT}; scripts_dir=${SCRIPTS_DIR}。从正文提取事实，生成 .webnovel/tmp/ 下的 fulfillment_result.json、disambiguation_result.json、extraction_result.json；fulfillment_result.json 必须顶层包含 planned_nodes/covered_nodes/missed_nodes/extra_nodes；disambiguation_result.json 必须顶层包含 pending；extraction_result.json 必须严格按你的第7节格式输出顶层字段 accepted_events/state_deltas/entity_deltas/entities_appeared/scenes/summary_text，禁止包在 chapter/fulfillment/disambiguation/extraction 等外层对象里；accepted_events 子项必须包含 event_id/chapter/event_type/subject/payload；不直接写 state/index/summaries/memory。"
)

Data Agent 只提取事实+生成 artifacts，不直接写 state/index/summaries/memory。

5.2 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_status 五项（state/index/summary/memory/vector）全部 done 或 skipped。

chapter_status 由 projection writer 自动推进：accepted→committed，rejected→rejected。

5.4 失败隔离

commit 未生成→重跑 5.2。projection 失败→只补跑失败项。不回退 Step 1-4。

Step 6：Git 备份

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

备份必须以解析后的 PROJECT_ROOT 为准，禁止从工作区父目录执行裸全量 Git add，避免把书项目仓库作为父仓库的嵌入仓库/submodule 加入。

Pitfalls（常见陷阱）

陷阱	说明	规避方法
上下文不足	context-agent 输出的写作任务书信息不够	检查任务书字数和覆盖维度，不足则补充
审查未落库就润色	跳过reviewer直接润色	硬依赖：Step 3 必须在 Step 4 之前完成
blocking=true 被忽略	审查发现阻断问题但未修复	充分性闸门强制检查
Anti-AI 检测失败	润色后仍有明显AI味	anti_ai_force_check=pass 是硬门槛
Git 嵌套仓库	裸全量 git add 把父仓库嵌入	backup 必须以 PROJECT_ROOT 为锚点
正文编码异常	中文标点/特殊字符被截断	全程 UTF-8，write_file 前检查编码

Verification（验证标准）

# 验证正文文件存在且字数达标
wc -m 正文/第{NNNN}章-{title}.md  # 应 >= 2000 字

# 验证审查已落库
python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
  status --chapter {chapter_num} 2>&1 | grep -q "committed" && echo "✅ committed"

# 验证 CHAPTER_COMMIT 存在
ls .story-system/commits/CHAPTER_COMMIT-{chapter_num}-*.json && echo "✅ commit"

充分性闸门

1. 正文文件存在且非空
2. 审查已落库（--minimal 除外）
3. blocking=true 必须在 Step 3 定点修复或经用户裁决
4. anti_ai_force_check=pass（--minimal 除外）
5. accepted CHAPTER_COMMIT，projection 五项 done/skipped
6. chapter_status=committed（projection 自动推进）

失败恢复

审查缺失→重跑 Step 3。摘要/状态/记忆缺失→重跑 Step 5。润色失真→回 Step 4 修复后重跑 Step 5。SKILLEOF