webnovel-review

name	webnovel-review
description	使用审查 Agent 评估章节质量，生成报告并写回审查指标。
version	6.0.0
tags	["writing","novel","review","quality"]
requires_tools	["read_file","write_file","search_files","terminal","clarify"]
requires_toolsets	["file","terminal"]

Quality Review Skill

目标

• 解析真实书项目根目录，按统一流程完成章节审查。
• 调用统一 reviewer 生成结构化问题列表与审查报告。
• 把审查指标写入 index.db，并把审查记录写入 .webnovel/state.json 兼容投影，主链事实仍以 review contract 与 accepted CHAPTER_COMMIT 为准。
• 审查时优先依据 .story-system/reviews/chapter_{NNN}.review.json 与 latest accepted CHAPTER_COMMIT 判断主链事实。
• 若存在关键问题，明确交给用户决定是否立即返工。

常见误区

• ❌ 没看 reviewer 原始 JSON 就直接口头总结
• ❌ 有 blocking issue 仍将流程视为通过
• ❌ 把 report 文件生成等同于已落库（review-pipeline --save-metrics 未跑）
• ❌ 主流程伪造 overall_score 或审查结论
• ❌ 按需参考一次性全部读完

优先级链

1. 用户明确要求（最高）
2. blocking=true 硬门槛
3. 项目私有约束（设定集、已有剧情）
4. skill 默认流程
5. reference 建议（最低）

决策树入口

• 若项目根不合法或缺少 .webnovel/state.json → 阻断
• 若正文文件不存在 → 阻断
• 若 reviewer 返回 blocking=true issue → 进入 Step 6 用户裁决
• 若所有 issue 均为非 blocking → 正常落库，流程结束

执行流程

Step 1：解析项目根目录并建立环境变量

export WORKSPACE_ROOT="${WORKSPACE_ROOT:-$PWD}"
export SKILL_ROOT="${SKILL_ROOT_DIR}/skills/webnovel-review"
export SCRIPTS_DIR="${SKILL_ROOT_DIR}/scripts"
export PROJECT_ROOT="$(python "${SCRIPTS_DIR}/webnovel.py" --project-root "${WORKSPACE_ROOT}" where)"

若目标章缺少 runtime 合同，先补齐：

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

要求：

• PROJECT_ROOT 必须包含 .webnovel/state.json
• 任一关键目录不存在时立即阻断
• CHAPTER_GOAL 必须来自详细大纲真实目标；若 chapter_brief.meta.query 仍是 {章纲目标} / 第N章章纲目标，按系统问题记录。

Step 2：按需加载参考资料

md 必读

Trigger	Reference
always	../../references/shared/core-constraints.md
always	../../references/review-schema.md

md 按需

Trigger	Reference
审查涉及爽点或钩子分析	../../references/shared/cool-points-guide.md
审查涉及多线交织	../../references/shared/strand-weave-pattern.md
blocking issue 需用户决策 (Step 6)	../../references/review/blocking-override-guidelines.md

Step 3：加载项目投影状态与待审正文

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

要求：

• 明确当前章节号与对应正文文件
• 若缺少正文或兼容状态文件，立即阻断

Step 4：调用统一审查 Agent

必须通过 Agent 工具调用 reviewer，禁止主流程伪造结论或口头总结代替 subagent 输出。

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。"
)

输入：

• chapter
• chapter_file
• project_root
• scripts_dir

输出约束：

• 只输出 JSON
• 每个 issue 必须有 evidence
• 不输出 overall_score

中间产物约定：

• reviewer 原始结果：${PROJECT_ROOT}/.webnovel/tmp/review_results.json
• 落库指标：${PROJECT_ROOT}/.webnovel/tmp/review_metrics.json

Step 5：生成审查报告并落库

报告保存到：审查报告/第{chapter_num}章审查报告.md

报告结构：

• 总览（问题数 / 阻断数）
• 阻断问题
• 其他问题
• 修复方向

标准文件流：

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 必须同时完成报告生成、metrics 文件输出、review_metrics 表写入
• 阻断判断以 reviewer 原始结果中的 blocking=true 为准

Step 6：写入兼容审查记录并处理阻断

先写入兼容审查记录（read-model/projection，不是写后事实真源）：

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

如存在任意 blocking=true 问题，必须使用 AskUserQuestion 询问用户：

• 立即修复
• 仅保存报告，稍后处理

若用户选择立即修复：

• 输出返工清单
• 在用户明确授权下做最小修改

若用户选择稍后处理：

• 保留报告与指标记录，结束流程

Pitfalls（常见陷阱）

陷阱	说明	规避方法
审查维度遗漏	六维审查只跑了部分	逐维度输出结果，缺失维度必须标注
审查报告未写入 index.db	指标丢失，后续查询不到	报告生成后必须执行 review_metrics 写入
blocking=true 未交互	阻断问题直接跳过未通知用户	硬规则：blocking=true 必须 AskUserQuestion
审查过严/过松	标准不一致导致质量波动	使用统一 reviewer agent，不手动审查
章节不存在	审查不存在的章节编号	审查前先验证文件存在性

Verification（验证标准）

# 验证审查报告存在
ls 审查报告/第{chapter_num}章-*.md && echo "✅ 报告"

# 验证 metrics 已写入
python -X utf8 "${SCRIPTS_DIR}/webnovel.py" --project-root "${PROJECT_ROOT}" \
  status --chapter {chapter_num} 2>&1 | grep -q "review" && echo "✅ metrics"

成功标准

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