WebNovel 连载流水线（Quartz）

⚠️ 安全提示

本技能可能触发杀毒软件的误报，原因如下：

• Shell 脚本（.sh）：仅用于 ffmpeg 图像格式转换及依赖项检查
• subprocess 调用：仅用于调用 Python 代码风格检查（linting）脚本
• prepublish_check.py：一款安全扫描器，用于检测恶意代码模式（讽刺的是，它自身反而被杀软标记）
  • 内含 curl、wget 等正则表达式模式，仅用于 识别（而非执行）潜在恶意代码
  • 这是一项安全功能，并非恶意软件

所有代码均为开源且可审计，不含任何恶意行为。

本技能文档完整记录了我们为 托管于 Quartz 的韩语网络小说连载（例如：Drama/야간조）所采用的端到端工作流。

快速上手（复制粘贴即可）

在终端中执行：

# 1) 安装
clawhub install webnovel-serial-pipeline

# 2) 进入技能目录
cd skills/webnovel-serial-pipeline

# 3) 设置 Quartz 根路径（环境变量）
export WEBNOVEL_QUARTZ_ROOT="/absolute/path/to/8.quartz"

# 4) 验证依赖项
bash scripts/check_deps.sh

# 5) 在用户确认“검수 완료”后，执行发布 + 同步索引
bash scripts/publish_review_ok.sh --series "야간조" --episode 2 --slug "불-꺼지면-가지-마세요" --draft-file "/path/to/draft.md"

目标

• 每集内容具备可读性（杜绝“作者旁白式”语气）
• 每集至少包含1 张配图
• 配图需轻量化适配 Web：原始尺寸约 1K → 转为 WebP（质量参数 q=70~80，最长边不超过 1200px）
• 发布流程须确保安全：初稿存档于 draft 目录 → 经人工审核通过后，再移入 Quartz 正式发布

设计与需求定义（动笔前）

本节记录我们实际采用的提案 + 需求分析过程（即流水线构建前的关键阶段）。

启动提问（一次性发送，选择题形式）

将以下问题整合为一条消息发出；待用户完成选择/应答后，其答案即作为后续文本基调的固定依据。

• 类型（必选）：戏剧 / 办公室惊悚 / 黑色喜剧 / 现实向爱情
• 参考作品（必选）：（此为关键启动点）若用户选择一部其已熟知的韩剧风格，则无需额外说明，文风、镜头语言、情绪走向即可立即锁定。
  • 示例：《我的大叔》/《未生》/《D.P.》/《我的解放日志》/《黑暗荣耀》（仅参考风格）/《Signal》/《秘密森林》/《坏家伙们》/《怪物》/《My Name》
  • 推荐方式：主参考 1 部 + 辅助参考 1 部
• 分级（必选）：12 岁 / 15 岁 / 青少年不宜
• 单集长度（必选）：35 分钟时长 / 510 分钟时长（按网络小说阅读体感换算）
• 背景设定（必选）：老城区 / 江南办公区 / 居住区 / 公共机构
• 角色（必填）：2～6 名（需提供姓名 + 一句话性格描述）

避免幼稚化（基础默认规则：8 条）

• 冲突须基于现实逻辑（工作/金钱/伦理/人际关系），禁止超能力或夸张设定。
• 禁用网络迷因（meme）、流行语、令人尴尬（오글）的台词。
• 禁用过度解释（설명충）：用“行动/选择”代替“口头说明”来呈现意图。
• 必须嵌入 1～2 处潜台词（서브텍스트），即表层话语 ≠ 内心真实想法。
• 禁用非黑即白的善恶二分法：角色需由“缺陷 + 欲望 + 恐惧”三要素共同构建。
• 喜剧处理应聚焦于情境或反讽，而非取笑人物。
• 禁止过度特效、字体变形、情绪夸张（包括句子语气本身）。
• 结局应侧重留下“余波（代价）”，而非单纯喜/悲收尾。

成熟度（质量）评估量表 —— 自动校验项

• 无 오글 / 迷因类台词（0 条）
• 解释性台词占比 ≤ 20%（主体应为行动/选择）
• 至少 2 名人物因不同目标发生直接冲突
• 事件结果（代价）至少体现为 1 项具体损失（金钱 / 关系 / 信任 / 名誉）

季播（10 集）结构设计模板

• EP01：钩子/触发事件（将故事种子以“确定性”方式锚定）
• EP02：首个事件（向前推进一个明确台阶）
• EP03～04：结构/关联线索浮现（从偶然 → 显现规律）
• EP05：揭示现实制约（如：“为何无法报案？”等合理障碍）
• EP06～07：强制抉择（关系 / 金钱 / 伦理维度的代价权衡）
• EP08：真相/系统轮廓初显（内部知情者 / 责任转嫁机制）
• EP09：唯一机会（不可逆的最终抉择）
• EP10：收尾聚焦于“之后”（而非解决），保持克制不渲染

关系构建规则（克制而细腻的羁绊）

• 禁用“靠闲聊拉近距离” → 改用两次微小人情债推动关系进展。
  • A→B：一次微小但具体的关照（重行动，轻言语）
  • B→A：一次沉默务实的帮助（禁用英雄式拯救）
• 称呼须符合现实逻辑：
  • 尚未知悉姓名前：尽量使用职业/功能型称谓（如“医生”、“科长”）
  • 确认姓名后：避免使用“大叔”等模糊敬称，统一采用 **“名字 + 씨”** 形式（如：도현 씨）

分发部署准备（路径 + 可选 API）

1) 设置 Quartz 根路径（发布目录）

为保障可移植性，我们绝不硬编码机器特定路径。

必需环境变量：

• WEBNOVEL_QUARTZ_ROOT = 你的 Quartz vault 根目录（即正式发布内容所在文件夹）

可选环境变量：

• WEBNOVEL_DRAFT_ROOT = 存放草稿的本地路径
• NANO_BANANA_KEY（仅当你使用 nano-banana-pro 生成封面时需要）

示例：

export WEBNOVEL_QUARTZ_ROOT="/absolute/path/to/8.quartz"
export WEBNOVEL_DRAFT_ROOT="/absolute/path/to/drafts"   # 可选

2) 依赖项检查

在本技能目录内执行：

bash scripts/check_deps.sh

3) 发布前安全检查（ClawHub）

执行 clawhub publish 前，请先运行：

python3 scripts/prepublish_check.py

若检测到明显的外泄/下载特征标记，该脚本将失败退出。

目录规范

• Quartz vault 根目录（已发布内容）：
  • $WEBNOVEL_QUARTZ_ROOT（示例：/path/to/8.quartz）
• 系列示例目录结构：
  • Drama//index.md（系列主页 + 制作规范说明）
  • Drama//-01-....md（已发布各集正文）
  • Drama//images/*.webp（封面图）
• 草稿目录（未发布）：
  • $WEBNOVEL_DRAFT_ROOT/_serial_drafts/（示例：/path/to/drafts/yaganjo_serial_drafts/）

标准工作流（推荐）

0) 明确“单集任务”定位

• EP01：钩子/触发（埋下核心种子）
• EP02+：推进（每集仅新增一个关键事件）

1) 创建单集草稿

首先在草稿目录中撰写本集内容。

2) 封面图像（1K 尺寸）

使用 Nano Banana Pro 生成 PNG 封面（1K 尺寸），再转换为 WebP 格式。

3) 嵌入图像 + 添加标签

• 确保 Frontmatter 中包含全部 6 维度标签：
  • domain/topic/format/audience/intent/lang
• 在正文开头附近嵌入封面图，使用 Quartz wikilink 格式：
  • ![[Drama//images/.webp]]

4) 语法与风格检查（Lint）

发布前请先运行轻量级检查：

• 禁止重复句式：같아서/것 같아서
• 规避作者旁白腔：避免滥用概括性陈述
• 对话需自然简短

5) 正式发布（移入 Quartz）

仅在用户明确确认后执行。

推荐发布命令（自动复制草稿至 Quartz 并规范化文件名）：

python3 scripts/publish_episode.py 
  --draft-file /path/to/draft.md 
  --quartz-root "$WEBNOVEL_QUARTZ_ROOT" 
  --series-dir "$WEBNOVEL_QUARTZ_ROOT/Drama/" 
  --series "" 
  --episode 2 
  --slug "불-꺼지면-가지-마세요"

6) 同步 index.md 中的剧集列表（可选，强烈推荐）

在 Drama//index.md 中预先插入标记：

## 에피소드

然后执行：

python3 scripts/sync_index.py 
  --index-file "$WEBNOVEL_QUARTZ_ROOT/Drama//index.md" 
  --series-dir "$WEBNOVEL_QUARTZ_ROOT/Drama/" 
  --series ""

一键发布工作流（仅限用户确认“검수 완료”后执行）

这是推荐的人工安全保障流程：务必等待用户明确说出 검수 완료 后，再运行：

bash scripts/publish_review_ok.sh 
  --series "야간조" 
  --episode 2 
  --slug "불-꺼지면-가지-마세요" 
  --draft-file "/path/to/drafts/yaganjo_serial_drafts/야간조-연재-02-불-꺼지면-가지-마세요.md"

该脚本将自动执行：

• 代码风格检查（lint）+ 资源校验 + 复制草稿至 Quartz（公开目录）
• 在 Drama//index.md 的 episode 标记区间内同步更新剧集列表

可用脚本

A) 创建新集草稿模板

python3 scripts/new_episode.py 
  --series "야간조" 
  --series-dir "$WEBNOVEL_QUARTZ_ROOT/Drama/야간조" 
  --episode 2 
  --slug "불-꺼지면-가지-마세요" 
  --draft-dir "/path/to/drafts/yaganjo_serial_drafts"

B) PNG → WebP 快速转换

bash scripts/to_webp.sh 
  /path/to/cover.png 
  /path/to/cover.webp

C) 单集语法与风格检查

python3 scripts/lint_episode.py 
  --file /path/to/episode.md

实际生产规则（我们真实采用的准则）

• 禁用作者旁白：删除类似“그래서 더 진짜였다”的主观评论句
• 展示而非解释：将意图说明替换为具体动作
• 禁用模式堆砌：尤其警惕连续出现的 ~같아서 结构
• 关系演进：依靠两次微小人情债（A→B 和 B→A）推进，而非冗长寒暄
• 钩子设计：每集结尾必须设置一个清晰、尖锐的下一步触发点