webnovel-review

name	webnovel-review
description	使用审查 Agent 评估章节质量，生成报告并写回审查指标。
allowed-tools	Read Grep Write Edit Bash Agent AskUserQuestion
argument-hint	[章号或范围，如 5 或 1-5]

Quality Review Skill

目标

• 解析真实书项目根，调度统一 reviewer 完成结构化审查并落库。
• 主链事实以 .story-system/reviews/chapter_{NNN}.review.json 与 latest accepted CHAPTER_COMMIT 为准；.webnovel/state.json 仅为兼容投影。
• 有 blocking=true 问题时交用户裁决。

前置加载：审查前先 skill("webnovel-craft") 加载通用工艺标准。审查维度（句长、句式、感官、情绪、五维度）的量化基准和阻断阈值由 webnovel-craft 定义，reviewer agent 专注于品味判断。

Review Mode 选择

支持三种对抗式审查模式，与 story-review 兼容：

模式	命令	说明
full	/webnovel-review full N	优先 spawn 4 个 Agent 并行审查（story-architect + character-designer + narrative-writer + consistency-checker）
lean	/webnovel-review lean N	优先 spawn story-architect + consistency-checker
solo	/webnovel-review solo N	当前会话执行基础审查，不 spawn

默认 full。Agent 缺失或 spawn 失败时自动降级 solo，报告中标注 fallback 原因。

• /webnovel-review N 或 /webnovel-review full N → 优先 spawn 全部 4 个 Agent
• /webnovel-review lean N → 优先 spawn story-architect + consistency-checker
• /webnovel-review solo N → 当前会话执行基础审查

Phase 0：预检与降级

1. 确定请求模式：解析输入中的 full、lean、solo；未指定时目标模式为 full。
2. 确认是否允许 spawn：如果当前已经在子 Agent 内执行，不再递归 spawn，直接降级为 solo。
3. 检查 Agent 部署状态：
   • 优先检查 .claude/agents/，其次 .opencode/agents/，再 .codex/agents/
   • full 必需：story-architect、character-designer、narrative-writer、consistency-checker
   • lean 必需：story-architect、consistency-checker
   • 任一缺失或 malformed → 降级 solo
4. 确定实际模式：报告中同时列出 Requested Mode 与 Effective Mode。

统一 Findings Schema

所有模式输出问题时必须使用统一结构：

- severity: S1 | S2 | S3 | S4
  category: structure | character | prose | consistency | platform | factual | format
  location: 文件路径:行号 或 章节/段落描述
  evidence: "引用原文或具体证据"
  issue: "问题描述"
  fix: "可执行修改建议"

严重度：

• S1：破坏主线、角色动机、世界规则或读者信任
• S2：明显影响章节效果、留存、节奏、人物可信度
• S3：局部质量问题，措辞、轻微格式、局部节奏
• S4：建议项或风格微调，不阻塞发布

平台 Rubric

审查时必须根据目标平台加载对应 rubric。平台优先级：用户显式指定 > 项目文档 目标平台 字段 > 未识别则使用通用网文 rubric。

平台	审查重点
番茄	强开局、强冲突、高频爽点/情绪反馈、低理解门槛
起点	设定自洽、升级路径、长线期待、世界观承载力
知乎盐言	短篇钩子、反转密度、情绪兑现、信息差推进
通用	核心卖点、冲突推进、情绪曲线、钩子与期待、角色动机、对话质量、设定一致性、文字自然度

full/lean 模式：并行 Agent 审查

full 模式 spawn 4 个 Agent 并行审查，lean 模式 spawn 2 个。每个 Agent prompt 必须自包含项目路径、审查范围、文件路径、审查基准摘要和 Findings Schema。

Agent 1: story-architect 审查视角：主题对齐、大纲结构、钩子/反转质量、情绪节奏、伏笔密度、高原构建。

Agent 2: character-designer（仅 full） 审查视角：角色语言风格一致性、对话质量、人物弧线、关系推进、好感度匹配。

Agent 3: narrative-writer（仅 full） 审查视角：AI 味检测（7-Gate + 模式 8 解释腔）、情绪烈度、格式合规、节奏均匀度。

Agent 4: consistency-checker 审查视角：grep-first + 推理型一致性检测、事实矛盾、时间线自洽、伏笔状态。

综合裁决

1. 收集实际执行的 reviewer VERDICT 和 FINDINGS
2. 合并去重：按 severity 排序（S1 > S2 > S3 > S4）
3. 分歧呈现：如果 reviewer 间有冲突意见，明确呈现让用户裁决
4. 输出综合审查报告，列出实际模式、fallback 原因、使用的 rubric

红线

• 必须通过 Agent 工具调用 reviewer，禁止主流程伪造结论或口头总结代替 subagent 输出。
• reviewer 只返回严格 JSON；主流程负责把返回值写入 ${PROJECT_ROOT}/.webnovel/tmp/review_results.json，随后由 review-pipeline 覆盖为标准 review_result artifact。
• 报告与 metrics 只由 review-pipeline --save-metrics 产出；主流程不伪造 overall_score。
• 项目根不合法 / 缺 .webnovel/state.json / 缺待审正文 → 阻断。

执行流程

Step 1：解析项目根

export WORKSPACE_ROOT="${CLAUDE_PROJECT_DIR:-${OPENCODE_PROJECT_DIR:-$PWD}}"
export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${OPENCODE_PLUGIN_ROOT:-}}"
export SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
export PROJECT_ROOT="$(python "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" where)"

PROJECT_ROOT 必须包含 .webnovel/state.json，否则阻断。

Step 2：目标章缺合同时刷新 runtime 合同

目标章缺 runtime 合同时，先用详细大纲的真实本章目标刷新（CHAPTER_GOAL 禁止 {章纲目标} / 第N章章纲目标 占位文本）：

GENRE="$(python -X utf8 -c "import json; 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

Step 3：按需加载参考

Trigger	Reference
always	../../references/shared/core-constraints.md
always	../../references/review-schema.md
审查涉及爽点或钩子	../../references/shared/cool-points-guide.md
审查涉及多线交织	../../references/shared/strand-weave-pattern.md
blocking issue 需用户裁决 (Step 8)	../../references/review/blocking-override-guidelines.md

Step 4：加载投影状态与待审正文

cat "${PROJECT_ROOT}/.webnovel/state.json"

确认当前章节号与对应正文文件；缺正文或缺兼容状态文件立即阻断。

Step 5：调用统一审查 Agent

必须通过 Agent 工具调用 reviewer。审查方法与维度细则由 reviewer 自带，本 Skill 不展开。

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

Prompt: chapter={chapter_num}; chapter_file={chapter_file}; project_root=${PROJECT_ROOT}; scripts_dir=${SCRIPTS_DIR}。严格输出 reviewer schema JSON，不评分，不口头总结。

reviewer 返回后，主流程把严格 JSON 写入 ${PROJECT_ROOT}/.webnovel/tmp/review_results.json（reviewer 不持 Write，是这份 artifact 的非写入方）。review-pipeline 必须把同一路径覆盖为标准 review_result artifact（含 blocking_count）。

调用后主流程必须记录 SubagentRun 汇总（仅供最终报告使用）：

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

reviewer 跳过、失败、输出不完整、正文为空、维度跳过、blocking issue 或耗时异常，必须写入 problems / auto_handled，不得在最终报告中静默。

Step 6：生成报告并落库

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-pipeline --save-metrics 同时完成报告生成、review_metrics.json 输出、review_metrics 表写入。阻断判断以 review_results 中的 blocking=true 为准。

Step 7：写入兼容审查记录

python "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" update-state -- --add-review "{chapter_num}-{chapter_num}" "审查报告/第{chapter_num}章审查报告.md"

兼容投影 / read model，不是写后事实真源。

Step 8：处理阻断

存在任意 blocking=true 问题时，用 AskUserQuestion 让用户裁决：

• 立即修复：输出返工清单，仅在用户明确授权下做最小修改。
• 仅保存报告，稍后处理：保留报告与指标记录，结束流程。

成功标准

1. 已解析真实书项目根。
2. 已通过 reviewer 输出结构化问题 JSON，落盘到 .webnovel/tmp/review_results.json。
3. 审查报告已生成，review_metrics 已写入 index.db，review_metrics.json 已输出。
4. 审查记录已写入 .webnovel/state.json 兼容投影。
5. 存在阻断问题时，用户已明确选择处理策略。

作者友好过程提示与恢复契约

审查开始前先说明本次会经历：定位待审正文 -> 刷新缺失合同 -> 写作检查 -> 生成报告和指标 -> 处理阻断裁决。过程提示用作者语言，不直接输出原始 JSON、traceback 或长命令日志；技术详情写入 .webnovel/logs/run_last.log：

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

过程提示每次不超过两行，只说当前动作和影响，例如“正在生成审查报告：会把阻断问题和最值得改的建议放到顶部”。少打扰确认策略：无阻断时不询问；存在 blocking issue、缺待审正文、用户要求是否立即修改时才询问。

需要用户裁决时使用有限选项，并说明影响；例如立即修复 / 仅保存报告稍后处理 / 放弃本次审查。卡住时必须说明卡点、已完成内容和恢复建议，例如“reviewer 结果已保存，metrics 落库失败；重新运行 /webnovel-review {chapter_num} 会从报告落库继续”。

不可恢复故障才在最终报告提示 .webnovel/logs/run_last.log；平时只保留日志，不打扰作者。收尾必须调用作者报告 helper：

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

作者友好最终报告契约

最终回复必须面向作者，不输出原始 JSON、traceback 或长命令日志。使用固定三段式，并以一句总状态开头：

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

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

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

三、下一步建议
- ...

必须汇报：

• 审查报告文件。
• .webnovel/tmp/review_results.json。
• .webnovel/tmp/review_metrics.json。
• review_metrics 是否落库。
• 阻断问题数量。
• 用户裁决状态。
• 如果无阻断，明确可以继续写作。

状态规则：

• 有 blocking 问题且用户未选择处理策略时，最终状态为“需要你处理”。
• 只保存报告、稍后处理时，最终状态为“需要你处理”或“部分完成”。
• reviewer 跳过、失败或输出不完整时，最终状态不得写“已完成”。

异常分类：

• 已自动处理：重复生成报告、覆盖本次旧审查中间文件、成功补写 metrics。
• 建议确认：非阻断但高收益修改建议、命名或设定细节建议看一眼。
• 必须处理：blocking issue、缺待审正文、reviewer 输出不完整、metrics 落库失败。

下一步建议必须使用任务化语言 + 可复制命令，例如：

- 审查无阻断，可以继续写下一章：
  /webnovel-write {next_chapter}

不写 token 统计；如需排查故障，只给日志路径或建议运行 /webnovel-doctor。