webnovel-review - SKILL.md Agent Skill

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 问题时交用户裁决。

红线

必须通过 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:-$PWD}"
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 让用户裁决：

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

成功标准

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

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

审查开始前先说明本次会经历：定位待审正文 -> 刷新缺失合同 -> 写作检查 -> 生成报告和指标 -> 处理阻断裁决。过程提示用作者语言，不直接输出原始 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。