Kn Book

---
name: kn-book
description: "制作说书、荐书、拆书、书评或读书笔记短片。用户要求讲解一本书、做书单号或使用微信读书取料时使用；优先通过微信读书官方 Agent Gateway 获取书籍信息与热门划线，再组织痛点、精华和行动结构。"
metadata:
  kinema-managed-by: "agent/manifest.json"
  kinema-kind: "route"
  kinema-status: "stable"
  kinema-version: "2.0.0"
  kinema-owner: "Kinema"
  kinema-source: "workspace"
  kinema-trust: "first-party"
  kinema-digest: "sha256:ecb680246c81858626719cddec00e693fec4609b9c234ff710696ab822eec81d"
---
# kn-book · 图书说书（book explainer / 荐书带货）

**把一本书的精华做成片。** 说书是被市场反复验证的重赛道（董宇辉一句推荐让
《额尔古纳河右岸》加印 600 万册；书单号挂车佣金 30~50%），它的生死线是
**书里的具体内容**：观众要听到"书里怎么说"，而不是"这本书真的很好"。
本 skill 的独门供应链是**微信读书官方接口**——热门划线就是几万读者投票出的
金句榜，选材不用猜。

## 直接启动整套流程（`/kn-book <书名或主题>` 即可）

被调用后**按此联动执行，不需要用户再调用任何其他 skill**：
1. **Read [`../kinema/SKILL.md`](../kinema/SKILL.md)**（完整节点工作流与铁律）。
2. 立项：`project new --title "X" --id <英文词> --profile book`（skill 自动派生 kn-book）
   → **只有确认全片零人物出镜时**才 `project set <id> --skip-design`。
   有人物（书中人物、常驻说书人 IP、任何反复出镜的具体形象）就走常规设定集：
   `skip_design` 关掉的不只是设定图，还关掉了唯一那条像素核对回路——
   `consistency scan` 会对每一镜返回 `reason: skip_design`、`verdict: null`
   （实测 kindling 十镜十个 null），全章画面从此无人核对。
3. 默认竖屏 9:16（抖音/视频号书单号与带货主场），立项汇报交代画幅与改横屏的命令；
   深度拆书系列投 B站/YouTube 用 `--aspect 16:9`。旁白写声线描述定制：`voice custom <id> --narrator --prompt "<声线描述>" --adopt 1`
   （说书腔描述用词：磁性、中低音、语速中等）；要剪映同款官方「磁性解说」再
   `voice audition <id> --narrator` → `voice use`。
4. 动态化不需要：**a 模式（kenburns）即完整体**，全程零视频 API 成本。
5. 全自动 `run` 收尾会自动出系列主视觉与本章封面，画面命题按章节 `cover_prompt` > `theme`
   回落（`--desc` 只有 `cover` 命令有）——所以 **run 前把 `cover_prompt` 写进 ChapterPlan**
   （按下文《图书封面专项协议》写主体、关系、环境、光线与标题安全区）；副标题缺省「第 N 集」，
   要作者或本集裸标题就在 run 前先跑 `cover <id> --chapter <cid> --subtitle "…"`，run 收尾
   见封面已在盘即跳过；已出过的加 `--force` 只重生该章，系列主视觉不动。

### 章节命名硬规则（不可例外）

`chapter.title` 只写本集的内容标题，不写章节序号。序号由章节 `id/order` 和封面排版层管理，绝不把编号混进标题。

- **禁止**：`第二章：嘉靖为什么不上朝`、`第2章 嘉靖为什么不上朝`、`第2集：嘉靖为什么不上朝`、`卷二·嘉靖为什么不上朝`，
  以及任何同义的中英文编号前缀或后缀。
- **正确**：`嘉靖为什么不上朝`、`沉默才是嘉靖的权力`。
- 建章前先把候选名规范化为“裸标题”；如果用户或素材带了 `第N章/集/回`、`第二章/集/回`、`卷N`、`Episode N` 等编号，
  去掉编号及其分隔符后再写入。去掉后为空时，重新创作一个剧情钩子式标题，不能退回 `第一章`、`第二章` 这类占位名。
- 建章后必须核对章节详情中的 `chapter.title`，并在交付前再次检查标题与 `project.json` 登记表一致；
  发现编号前缀立即修正，不得带着错误标题继续生图、合成或交付。

旁白试听、选音色、候选画面定稿或章节审阅如果要让用户在网页完成，先执行 base skill 的
[Studio 交互交接协议](../kinema/references/studio-handoff.md)，自动启动/复用控制台并给出
`项目 → 章节`入口，再停下等待用户；不要只说“请启动 Studio”。

## 取料协议（三级降级，引擎零联网——检索全部发生在指挥层）

**① 微信读书官方 Agent Gateway（有 `WEREAD_API_KEY` 时首选，合规正道）**：

**每次立项先探测 key（三处都查，探测与使用全程绝不回显 key 值）**。少查一处就会
把「用户已经配好了」误判成没配——`secrets.local.json` 正是 `setup` 向导、网页
配置中心和 `config secret` 三个入口的落点，且优先级高于 `secrets.yaml`：

```bash
test -n "$WEREAD_API_KEY" && echo env-ok || echo env-missing          # ① 环境变量
python3 -c 'import json,sys,pathlib
p=pathlib.Path("config/secrets.local.json")
d=json.loads(p.read_text()) if p.is_file() else {}
b=d.get("secrets") or d
sys.exit(0 if str(b.get("WEREAD_API_KEY","")).startswith("wrk-") else 1)' \
  && echo local-ok || echo local-missing                              # ② 本机密钥文件
grep -qE '^WEREAD_API_KEY:\s*"?wrk-' config/secrets.yaml 2>/dev/null \
  && echo secrets-ok || echo secrets-missing                          # ③ 仓库密钥文件
```

**三处都缺不阻塞、也不静默**：**直接走 ② 公开页取料把活干下去，同一轮回复里附一次
配置提示**。不要停下来等用户表态，也不要每轮复读提示——**同一会话提示一次即可**，
用户说过不配就不再提。提示要**如实交代差异**：公开页照样有书名、作者、出版社与目录
（事实四锚点能闭环），推荐值与评价人数也在；没 key 真正丢的是**完整热门划线榜、划线处读者想法、
中差评分档、资深会员推荐率和书架/笔记/阅读统计**——即拆书最吃劲的选材与判据。
提示内容就是下面三步：

1. 登录 https://weread.qq.com/r/weread-skills 申请个人 API Key（`wrk-` 前缀，免费，绑定微信读书账号）；
2. 写入任一处（**都不需要用户手工建文件**）：
   - `cd engine && python3 -m kinema config secret WEREAD_API_KEY wrk-...` —— 落
     `secrets.local.json`，优先级最高，文件由引擎自动创建；
   - 或直接编辑 `config/secrets.yaml` 的 `WEREAD_API_KEY:` 那行（该文件由
     `setup` 从模板自动生成，已在 `.gitignore`）；
   - 或 fish 固化 `set -Ux WEREAD_API_KEY wrk-...`。
3. 回到对话说"配好了"，AI 重新探测即接入。

**官方 weread-skills 包不自动安装**（本协议 curl 直连已闭环，装与不装取料能力
等价）：首次配好 key 后**问用户一句**要不要顺带装官方封装（价值在做视频之外的
日常用途：书架管理/笔记导出/阅读统计），用户点头才装、且装到**全局**
`~/.claude/skills/`——第三方产物绝不放进本仓库的 `.claude/skills/`（会进 git）：

```bash
curl -L https://cdn.weread.qq.com/skills/weread-skills.zip -o /tmp/weread-skills.zip \
  && unzip -o /tmp/weread-skills.zip -d ~/.claude/skills/
```

取用写法（**按引擎同一优先级 env > local.json > yaml 取**，借 shell 变量中转，日志零泄漏）：

```bash
WRK=$(python3 -c 'import json,os,pathlib,re
v = os.environ.get("WEREAD_API_KEY", "")
p = pathlib.Path("config/secrets.local.json")
if not v and p.is_file():
    d = json.loads(p.read_text()); v = (d.get("secrets") or d).get("WEREAD_API_KEY", "")
p = pathlib.Path("config/secrets.yaml")
if not v and p.is_file():
    m = re.search(r"^WEREAD_API_KEY:\s*\"?(wrk-[^\"\s]+)", p.read_text(), re.M)
    v = m.group(1) if m else ""
print(v)')
```

探测通过后，指挥层直接 Bash curl 调用（单端点 POST，接口靠 `api_name` 分派）：

```bash
curl -sX POST "https://i.weread.qq.com/api/agent/gateway" \
  -H "Authorization: Bearer $WRK" -H "Content-Type: application/json" \
  -d '{"api_name": "/store/search", "keyword": "纳瓦尔宝典 纳瓦尔·拉维坎特", "scope": 10, "count": 3}'
```

**取料六步链路（照打即可，不要自己摸索接口）**：

```text
1. /store/search  keyword="书名 作者" scope=10  → 核对回包 title 再取 bookId
2. /book/info     bookId    → 事实四锚点前三项 + intro 定主题
3. /book/chapterinfo bookId → 目录定骨架 + 体量（第四锚点）
4. /book/bestbookmarks bookId（chapterUid 不传）→ top20 热门划线金句
5. /review/list   bookId reviewListType=1/4/2 → 正面·中立·差评三档口碑
6. /book/readreviews  用第 4 步的 (chapterUid, range) → 金句处读者真实反应
```

- **热门划线是本 skill 的王牌素材**：划线密度＝读者共鸣图谱，被划最多的句子
  就是市场验证过的金句，直接进精华点；回包 `chapters[]` 给出金句所属章节，可口播出处。
- **事实四锚点前三项由第 2 步拿全**：`/book/info` 给 title/author/publisher/publishTime，
  体量走第 3 步目录。同一回包的 isbn/newRating（千分制，`836`=83.6%）/newRatingCount
  只作选题判断，不进成片。
- **三条硬闸**（细则与判据见 [`references/weread-gateway.md`](references/weread-gateway.md)）：
  `newRatingCount < 300` 时推荐值不可采信；`/review/list/mine` 参数名是小写 `bookid`；
  `/store/search` 有累积配额（约 20 次触 `-2014`），**搜索间 sleep ≥1s、一本书只搜一次**。
- **Gateway 没有榜单接口**——飙升/新书/神作/总榜走公开网页 `weread.qq.com/web/category/*`
  （WebFetch 可直接解析），Gateway 负责给榜单书补推荐值与划线。
- 用户自己的书架与笔记是**独家素材**（"我今年划线最多的一本书"人设向选题），但
  **空号是常态**：`/user/notebooks` 返回 `totalBookCount: 0` 是正常回包不是报错，
  先探测再承诺，别把用户不存在的阅读史写进文案。

接口分级（17 个逐个实调）、十条试错陷阱、错误码字典与数据化三过滤判据，全部在
[`references/weread-gateway.md`](references/weread-gateway.md)。`/_list` 自述与实际有多处
不符（`/book/similar` 恒废、`scope` 八选二、嵌套层级），**以该 reference 为准，不要照抄自述**。

**② 无 key 降级（探测缺 key 即自动走这条，不等用户确认）**——四步照打：

```text
1. WebSearch "<书名> <作者> 微信读书"  → 同时捞出两个直达 URL（见下方陷阱）
2. WebFetch  weread.qq.com/web/bookDetail/<v>   → 书名/作者/出版社/出版年/
                                                   推荐值%/评价人数/简介/目录
3. WebFetch  book.douban.com/subject/<id>       → ISBN/页数/豆瓣评分/星级分布/短评正文
4. 榜单      weread.qq.com/web/category/{rising,newbook,all,general_novel_rising}
```

- **两套评分口径交叉验证**（微信读书推荐值 % 与豆瓣 10 分制），比单一来源硬。
- **陷阱一**：`bookDetail` URL 里的 `<v>` 是不透明 token，**bookId 拼不出来**
  （`/web/bookDetail/<bookId>` 恒 404），只能靠 WebSearch 捞现成链接。
- **陷阱二**：豆瓣**搜索页**是 JS 渲染，WebFetch 抓不到结果；**条目页无反爬无登录**，
  必须 WebSearch 拿到 `subject/<id>` 后直达。
- **拿不到**：完整热门划线榜（公开页只挂"去 App 查看全部"）、读者点评正文、
  中差评分档。金句只能退回自己转述观点，不引原句。

**③ 用户直给**：点名书目、贴自己的读书笔记、自供实拍书影。

无论哪级，**事实四锚点必须核查后写进 `script`**：书名＋作者＋出版信息（出版社与年份；
网文改用实体出版物名）＋体量（字数/章节数）——说书失败多在张冠李戴。引擎不联网是铁律，
取料只在指挥层。

**口碑数据一条都不进成片**：评分、推荐值、评价人数、销量印量、榜单名次、读者评论
原话、平台与站点名——取料链路照常全量取，但它们止步于指挥层。清单与改写方向见
[`../kinema/references/copywriting.md`](../kinema/references/copywriting.md)《外部评价不进成片》。

## 选题协议（三过滤）

- **选题源**：微信读书榜单（飙升/神作/新书，走公开网页）→ 热点勾连（影视化上映、
  社会情绪、游戏带火的文化母题）→ 用户书架反选（留言想要什么书单就拆什么）。
- **三过滤，全过才立项**：① 有痛点共鸣（书回答了一个观众正在疼的问题）；
  ② 有反常识增量（书里至少一个"你以为 X 其实 Y"）；③ 有可执行行动（观众今天
  就能做的一件事）。三者缺一 = 只能夸书不能拆书，换书。
- **有 key 时三过滤用回包字段判，不靠感觉**：热门划线 top5 多为祈使句/练习题
  → 拆得动；多为抒情金句 → 只能氛围荐书。反常识增量到 `reviewListType=4/2`
  的中差评里找（正面书评只复述，争议点在中差评）。判据全表见
  [`references/weread-gateway.md`](references/weread-gateway.md)。**判据止步于这一步**：
  可播的是那个增量本身，不是划线人数，也不是评论原话。
- 带货向选书 20~50 元价位转化最好（市场口径）；冷门佳作值得挑，但钩子从书里找，
  不从印量找。

## 精华提炼方法论（拆书公式）

读料顺序：**简介定主题 → 目录定骨架 → 热门划线定金句**。然后压进固定结构：

1. **痛点钩子镜（≤3s）**：把书的核心议题翻成一句扎心问题或反常识结论——
   "你不是懒，你只是被这本书说中了"，绝不以"今天推荐一本书"开头。
2. **书卡镜**：书名＋作者＋一句定位——定位句从书的内容里长出来（"一个硅谷投资人的
   人生算法"），不从外界评价里借（"年度畅销榜第一的神作"）。
3. **精华点 ×3**：每点＝**场景故事**（书中案例讲成 15 秒小故事）＋**金句**
   （热门划线原句）＋**行动**（今天就能用的一步）。一点讲不透就砍，绝不摊平。
4. **收尾升华＋CTA 镜**：回扣钩子一句话，行动号召要具体——"这本书在下方链接/
   评论区，先看第三章"，别用万金油"点赞关注"。

**引用纪律（版权红线）**：narration 以**你自己的转述**为主；直接引用原文单条
≤50 字、全片 ≤3 条，口播带出处（"书里写道……"）。大段搬运原文＝侵权；
金句超长时压缩转述，观点保留、句子重写。

## 视觉语言 DNA（题材在这里定，画风在 profile 里定）

profile 前缀只管**看起来什么样**（纸感光、低饱和暖色、油墨哑光层次），
它不规定画什么——画什么由本节与逐镜 `image_prompt` 定：

- **锚点镜（书卡/开场/收尾）**：书房暖光静物——精装书、台灯、咖啡、亚麻桌布，
  定全片调性。
- **内容镜（精华点）**：**优先把观点演成事件**。书里的案例本来就有人、有动作、
  有前后变化：把人登记进 `characters`、把取景地登记进 `scenes`、按镜绑定，
  才有得动、有得演、有得对剪。`characters` 整章全空的片子动不了也演不了，
  镜与镜之间没有任何可对剪的东西——讲焚书与阅读之死也能一个人都不出现。
  确实演不出来的抽象观点再退回概念隐喻插画（"注意力是资产"→
  `一枚金色沙漏立于书页翻开的山谷之间，沙粒是细小的金币`）——**隐喻必须物理自洽**：
  把「四五一度」与「烧书」硬焊成「冒火花的水银温度计」，温度计不冒火花，观众只看到
  一个不存在的物件。
- **肖像红线**：不画**真实可辨认的人**（作者本人、公众人物）——那是肖像权与
  相似度问题，用书桌/钢笔/背影剪影代替。书中人物、虚构角色、无从辨认的路人
  不在此列，照常登记进 `characters` 出镜。
- **金句镜**：大留白氛围画面，金句进 `narration` 由字幕逐字承载（音字一致铁律），
  **不把金句烤进图**——长句进图必出错字。
- **书影纪律**：**AI 不复刻真实书封**（封面是出版社版权物，模型也写不对书名字）。
  两条路：① 生成"意象书卡"（无字精装书+主题意象环绕）；② **实拍书影 `supply`
  直供**（带货片需要真书露出——自拍或用出版社授权物料，登记为分镜画面与 AI
  意象镜混排，正是市面书单号的标准形态）。

## 分镜法则

8~14 镜，45~90s：钩子 ≤3s → 书卡 1 镜 → 每个精华点 2~3 镜（故事镜+金句镜）→
行动清单 1 镜 → CTA 1 镜。`narration` ≤30 字/镜（口播密度）；`emotion` 给钩子、
金句、收尾镜标注。运镜安全档：`缓慢推近`（金句凝视）、`拉远揭示`（书卡全貌）、
`凝视呼吸`（静物停留）——书卷气质忌快运动，进阶运镜（▲/■ 档）不用。
转场**不主动加**（缺省无转场，精华点之间直接硬切）；用户点名要分段字卡时才插，
本档合用 `fade_black`（"第二把钥匙"）或 `wipe --color` 配暖纸色。

## 声音设计

- 音色描述用词按书选：**磁性解说**（通用说书）· **悬疑解说**（故事性强的小说/
  历史）· **深夜播客**（情感疗愈/散文）——写进 `voice custom --narrator --prompt … --adopt 1`
  定制立档，一个账号锁一把声音即品牌声纹；要官方模版音色再 `voice audition` → `voice use`。
- **金句前留气口**：金句镜 `delivery.pause_before: 0.6`（kenburns 下生效，
  折进 dur）——说书的呼吸感全在金句前那半秒。
- BGM calm 低音量钢琴/lofi；语速中等（比知识解说慢半档，说书要"讲给你听"
  不要"念给你听"）。

## 系列化与商业化

- **图书封面专项协议**：图书封面不是“古风人物 + 城市背景 + 一行大字”的泛用海报，
  而是一个缩小后仍能读懂的出版物信息封面。每张封面先确定一个视觉命题：一个核心书籍
  对象、一个冲突关系、一个环境层；历史/政治类优先使用权力关系的象征物（空置龙椅、封口
  奏疏、朱批、账册、宫门、棋局、秤与印），不要无依据地生成英俊主角肖像来代替书的观点。
  大主体不超过 1 个，辅助主体不超过 2 个，装饰纹理不能抢主标题和视觉命题。
- **信息层级**：章节封面主标题必须是微信读书核实过的实际书名（如《大明王朝1566》），
  可用一行小字补作者（刘和平）或本集裸标题（嘉靖为什么不上朝）；项目品牌名只能做很小的
  角标，不能覆盖书名。章节序号属于元数据和封面组件，不得写进 `chapter.title`，也不能
  代替书名。封面上的书名、作者、章节标题必须与脚本事实一致，禁止泛化成“图书解说”。
- **构图与缩略图**：默认 3:4 竖版 + 4:3 横版双套；3:4 画面上半部承载视觉命题，底部约
  20%~28% 保留干净的标题安全区，标题不压脸、不压关键道具、不贴边。至少做一次 84px
  缩略图检查：缩小后仍能分辨书名轮廓、主色对比和唯一主体；缩小后只剩“一个人站在场景里”
  就判为失败，重写视觉命题而不是继续堆粒子。
- **色彩与字体**：一主色 + 一撞色，标题只用一种主字体和一种强调色；中文标题优先后置排版
  （`--typeset-title`，字体从 song/kai/hei/yuan 选择），不让模型直接生成书名。背景必须留
  出真实的低密度地板，标题与背景保持足够对比，禁止白字黑描边的默认贴图感。
- **系列与章节分离**：系列封面可以表达“图书解说”品牌，但章节封面必须有自己的书名、视觉
  命题和无字背景。封面生成后逐项核对 `project.cover` 与 `chapters/<cid>.json.cover`：
  章节应有独立 `*_bg` 和成品文件，路径不能指向 `series_*`；若项目同时承载多本书，而引擎
  只能从项目级标题排版，不能静默沿用品牌名，应先按单书建项目或补齐章节级封面标题能力，
  不得把泛品牌封面当作章节封面交付。
- **两段式封面流程**：先生成无字 key visual，再以无字图为唯一画面基准后置排版；章节背景
  可以参考系列无字背景承接色板，但必须在 `desc` 中写出本章独有的视觉命题，至少包含主体、
  关系、空间、光线和标题安全区。生成后同时 Read 原图与缩略图，检查错字、信息层级、主体
  是否单一、标题是否清晰；任一失败就重做封面，不带问题进入合成或交付。
- **本章示例**：`《大明王朝1566》` 的章节封面应围绕“皇帝不露面却控制所有人”构图：
  空置龙椅作为核心、封口奏疏和层层宫门形成权力链、朱红印记作为唯一撞色，画面留出标题区；
  不应使用无来源的男主近景、泛古城和“图书解说”大字。
- **系列封面**：`cover` 命令三锚点（同版式+系列背景参考图+同前缀同 seed）锁系列感；
  系列品牌名与期数由排版层后置，不靠模型写字，但不得因此替代章节实际书名。
- **变现组合拳**（市场验证口径）：视频挂车＋评论区置顶＋主页橱窗，佣金 30~50%；
  发布侧合规与排期不在集群范围内，成片交付后由用户自行上传。

## 成本口径

生图＝镜数 ×¥0.3 ＋ TTS 按字；视频 API **零调用**。60s/10 镜典型 ≈ ¥3~5；
接官方 Gateway 取料零成本（个人 key 免费额度内）。

## 重做意见词典（review retake 用）

| 症状 | `--note` 建议写法 |
|---|---|
| 出成了真实书封复刻 | `改为无字精装书意象书卡：合上的布面精装书+主题象征物环绕，书脊无文字` |
| 插画太具象/像课件 | `改为单一隐喻场景：一个视觉主体承载观点，留白40%，暖纸色调` |
| 出现真人面孔 | `人物改为背影或剪影，或用书桌钢笔等象征物替代` |
| 画面冷硬无书卷气 | `加入暖光台灯与纸张织物质感，色温压暖，对比度放柔` |
| 静物太摆拍 | `加入使用痕迹：翻开的书页、压痕便签、喝了一半的咖啡` |

## 何时不用

讲概念不讲书 → `kn-explainer`；纯金句卡 → `kn-quote`；TopN 强榜单感书单 →
`kn-ranking`（序号徽章字幕）。