book-mirror

book-mirror：逐章个性化图书分析

约定： 关于本 skill 所归档的 media/<format>/<slug> 例外规则，请参阅 _brain-filing-rules.md。

约定： 有关引用规则、反向链接约束和输出质量标准，请参阅 conventions/quality.md。

约定： 上下文收集阶段所遵循的查找链（brain → 搜索 → 外部）说明，请参阅 conventions/brain-first.md。

功能说明

给定一本书（EPUB 或 PDF），生成一个 brain 页面。页面中每一章在一侧进行详细概括（“原章节”），在另一侧映射回读者的真实生活（“映照”），映照内容使用读者在 brain 中记录的个人语言、处境、人物和行为模式。输出为 brain 页面，路径为 media/books/<slug>-personalized.md。

这不是通用的图书摘要。映照才是核心价值：它让这本书读起来像一位深入了解读者生活的聪明朋友在页边做批注。映照的作用是带来认同感，即“这说的正是我”，然后便退到一旁。如果用户需要的是平铺直叙的摘要，请将其引导至其他 skill。

信任约定（运行前请先阅读）

book-mirror 以 CLI 命令（gbrain book-mirror）的形式运行，而不是由 Agent 通过工具调度的纯 Markdown skill。CLI 是可信运行时，skill 则是围绕它的编排说明。

这对 Agent 意味着：

• CLI 会提交 N 个只读子 Agent 任务（每章一个）。每个子 Agent 仅拥有 allowed_tools: ['get_page', 'search'] 权限，不能调用 put_page 或任何写入类操作。它们通过最终消息输出 Markdown 格式的分析结果。
• CLI 读取每个子任务的 job.result，组装最终页面，并通过一次具备操作员信任级别的 put_page 写入。
• 因此，不可信的 EPUB/PDF 内容无法对任何 people/* 页面进行提示词注入。信任收缩发生在工具白名单层，而不是 slug 前缀层。

流水线

1. ACQUIRE   → User has the EPUB/PDF locally (manual; book-acquisition is
               not currently shipped — see "Acquiring the book" below).
2. EXTRACT   → Pull chapter text from EPUB/PDF into one .txt per chapter.
3. CONTEXT   → Gather everything the brain knows about the reader.
4. ANALYZE   → `gbrain book-mirror` fans out N read-only subagents.
5. ASSEMBLE  → CLI reads each child result and writes one put_page.
6. PDF       → Optional: render via skills/brain-pdf for delivery.

1. 获取图书

book-acquisition（灰色地带下载器）在本 skill 这一批次中被有意不予发布。由用户手动放入 EPUB/PDF。用户可能使用的常见路径如下：

# User-supplied path
ls path/to/book.epub
ls path/to/book.pdf

# Or already in the brain repo (recommended for tracking)
ls $BRAIN_DIR/media/books/

从 gbrain 配置中解析 $BRAIN_DIR（gbrain config get sync.repo_path），或由用户直接提供。

2. 文本提取

目标：在临时目录下为每一章生成一个 .txt 文件。Agent 拥有 shell 和 python 访问权限；CLI 位于此步骤之后，以提取后的目录作为输入。

EPUB

SLUG="this-book"                                # kebab-case
WORK="$(mktemp -d)/$SLUG"
mkdir -p "$WORK/chapters"
unzip -o path/to/book.epub -d "$WORK/unpacked"

# Find content files (XHTML/HTML), sorted (chapter order = sort order)
find "$WORK/unpacked" -name "*.xhtml" -o -name "*.html" | sort > "$WORK/files.txt"

# Strip HTML to text per chapter
python3 - <<'PY'
from bs4 import BeautifulSoup
import os, sys
work = os.environ['WORK']
files = open(f'{work}/files.txt').read().splitlines()
for i, path in enumerate(files, 1):
    html = open(path, encoding='utf-8', errors='replace').read()
    text = BeautifulSoup(html, 'html.parser').get_text('\n')
    text = '\n'.join(line.strip() for line in text.splitlines() if line.strip())
    with open(f'{work}/chapters/{i:02d}.txt', 'w') as f:
        f.write(text)
PY

如果缺少 bs4，请执行：pip3 install beautifulsoup4 lxml。

检查章节文件，区分真正的章节与前置内容（目录、版权页、致谢等）。EPUB 通常每个文件对应一章，但有时一个文件包含多章。可使用 head -5 "$WORK/chapters/"*.txt 抽查。

PDF

pdftotext -layout path/to/book.pdf "$WORK/full.txt"

然后使用 awk 或 python，按章节标题切分（查找 “Chapter N”、“CHAPTER N” 或全大写标题行）。如果 PDF 是没有嵌入文本的扫描件，则回退到 skills/brain-pdf 或其他视觉工具进行 OCR。

质量检查

对每个章节文件进行以下检查：

• 字数大于 1500（典型章节长度为 2k 至 8k 字）。
• 不包含 HTML 标签。
• 段落以 \n\n 保留。

保存一份 chapters/INDEX.md，记录章节编号、标题、文件和字数，以便查阅。

3. 上下文收集

这是最关键的一步。映照的质量完全取决于提供给每个章节子 Agent 的上下文。

需要拉取的内容

1. 模板：USER.md 和 SOUL.md（如果用户有维护这些文件） （gbrain 在 templates/USER.md 和 templates/SOUL.md 提供模板； 填充后它们位于 brain 仓库中。完整读取。）
2. 近期每日记忆：wiki/personal/reflections/ 下的 brain 页面，或用户保存每日笔记的任何位置，取最近 14 天的内容。
3. 与主题相关的 brain 搜索，针对书籍的主题：
   • 婚姻类书籍：gbrain query "marriage"、gbrain query "couples therapy"。
   • 商业类书籍：gbrain query "founders"、gbrain query "fundraising"。
   • 心理学类书籍：gbrain query "shame"、gbrain query "anger"。
4. 相关实体的 brain 页面：对可能会出现的人物，执行 gbrain query "<name>"。
5. 长期模式：用户的反思或原始笔记中反复出现的任何内容。

深度检索（默认开启，不可选）

过于单薄的静态上下文包是导致镜像流于泛泛的头号原因。质量上限取决于 brain 本身，而不是手动塞进某个文件的内容。在调用 CLI 之前，先按章节进行检索：

1. 将书籍拆分为若干章节（章、部分或主题单元）。
2. 针对每个章节，根据作者在该章节中的表述，生成 15–20 条有针对性的 brain 搜索。
3. 获取这些搜索结果中排名靠前的 brain 页面。
4. 将检索到的材料整合进上下文包，按章节分组，使每个章节的子 Agent 都能看到与其所属章节对应的页面。

查询生成策略（按章节）：

• 字面主题匹配：作者字面上在谈论什么？
• 心理对应：这一内容映射到读者生活中的哪种模式？
• 具体事件挖掘：作者可能在描述哪些带日期的事件？
• 关系与人物对应：读者生活中谁与之对应？
• 时间对应：读者生活中哪一时期与之最接近？

执行：

gbrain query "QUERY" --limit 3
gbrain get "PAGE_SLUG"

**预算：**每个章节 15–20 次搜索 × N 个章节，外加 40–60 次完整页面获取。所有查询均为本地数据库查询，几乎没有成本。检索到的 brain 上下文总量目标为 5–8 万字符。章节子 Agent 在运行时也会携带只读的 search 和 get_page 工具，因此上下文包是下限而不是上限，但不要指望子 Agent 重新发现编排阶段已经找到的内容。

高风险镜像的最低检索材料要求：

• 所有章节合计检索到 40 个以上 brain 页面。
• 10 条以上来自读者本人的直接引语（逐字摘自 brain 页面）。
• 在有条件时，提供带日期的事件和反复出现的模式。
• 覆盖生活的多个领域：日记与反思、工作与创作产出、人际关系、公共与公民生活、具体的快乐时刻、文化身份，而不只是最沉重的素材。

组装上下文包

将所有内容写入一个 CLI 可以读取的单一文件：

CONTEXT="$WORK/context.md"
{
  echo "## USER.md (if any)"
  [ -f "$BRAIN_DIR/USER.md" ] && cat "$BRAIN_DIR/USER.md"
  echo
  echo "## SOUL.md (if any)"
  [ -f "$BRAIN_DIR/SOUL.md" ] && cat "$BRAIN_DIR/SOUL.md"
  echo
  echo "## Recent reflections (last 14 days)"
  # Pull recent daily reflections — adapt to the user's filing scheme
  # ...
  echo
  echo "## Topic-relevant brain pages (grouped per chapter)"
  # Deep-retrieval results from above, grouped by the chapter they serve
  # ...
  echo
  echo "## Themes & cruxes"
  # A 1-page summary, written by the agent, calling out:
  # - What's currently active in the user's life that this book intersects
  # - Specific quotes from the user that map to book themes
  # - People and dates that should appear in the mirror
  # - The anti-repetition constraints (domain map + phrase caps, below)
} > "$CONTEXT"

让它内容密集。每个章节子 Agent 都会读取它。请将反重复约束（见下一节）编码进此处，因为每章的领域分配和短语上限只有在每个子 Agent 都能看到时才会生效。

质量体系（硬性规则）

这些规则是通过跨模态评估的反复迭代得出的。对每一本书的镜像都是强制性的。

原则：章节部分才是多样性的引擎

最重要的经验是：丰富的章节摘要能推动多样化的镜像。如果压缩源材料，镜像就只能回应它自己最常用的那些套路。两部分是相辅相成的，而不是争夺篇幅的关系。

**规则：**作者提出的每一个不同的观点、故事、框架、编号列表项和令人印象深刻的短语，都应各自占有一个独立的小节。如果作者列出六种孤独，就应有六个小节。如果作者讲了三个故事，就应有三个小节。章节部分应当足够详细，使读者即使跳过原书，也不会损失太多。镜像部分则应针对每一个具体观点，给出一种不同的个人对应。

布局：顶部对齐的 HTML 表格或分段结构（硬性规则）

不要输出裸的 | The Chapter | The Mirror | Markdown 管道表格。GitHub（以及大多数渲染器）会把表格行的单元格补齐到相同高度，并将较短单元格的文字垂直居中。因此，只要两侧内容长度不同（而且总是不同），其中一列就会向下漂浮，上方出现一大段空白。普通 Markdown 没有单元格级别的垂直对齐功能。这是根本原因，而不是样式细节问题。

有两种合法的容器，两者都正确，按使用场景选择：

1. 顶部对齐的 HTML 表格（命令行默认方式）。 gbrain book-mirror 的章节提示词已经强制要求每个 <td> 都带有 valign="top" 的 HTML <table>，这已被固化在可信运行时中。手写或修复镜像时需要知道：GitHub 会保留 valign="top"，但会去掉内联的 style="vertical-align"；并且不会在原始 <td> 中渲染 Markdown 强调语法，因此需要先把强调转换为 <em>/<strong>，单元格内的段落分隔使用 <br><br>。

2. 分段结构。 最适合移动端和聊天场景交付，也是任何手工组装的镜像（儿童版、旧页面的修复版）的最佳选择：

   ### Chapter N: <title>
   
   **The Chapter**
   
   <chapter prose, normal paragraphs separated by blank lines>
   
   **The Mirror**
   
   <mirror prose, normal paragraphs separated by blank lines>
   

   使用真正的空行段落分隔，不要在表格单元格之外使用 <br><br>。这样内容始终从上到下顺序阅读，不会出现对齐问题。章节的 Chapter/Mirror 命名以及“每个想法一个小节”的丰富度规则保持不变，只改变容器。

防止重复（硬性约束，而非凭感觉）

“再多样一些”这种指令不起作用。大模型会不断重组它所拿到的素材：如果素材只有 6 张卡片，它就会把这 6 张卡片反复使用 N 次。请使用硬性约束，并将其写入上下文包的“主题与核心矛盾”部分：

1. 领域映射： 写作前，为每个章节分配一个主要的人生领域（职业、家庭、公共事务、创作生活、某段特定关系、童年、智识生活、精神修行等）。相邻的两个章节不得共享同一个主要领域。

2. 短语上限： 任何词语或短语作为主题锚点出现的章节数不得超过 3 个。找出读者的“高频主题”（如果不加约束，会主导全文的 5–6 个主题），并设定明确的限制或禁用规则。

3. 故事去重： 写每个镜像之前，检查：“这个故事、事件或引语我在之前的章节里用过吗？”如果用过，就换一个。

4. 情感范围要求： 至少 25% 的章节必须对应喜悦、幽默、创作激情或胜利，而不只是伤痛与挣扎。当作者描述美好的事物时，镜像也应在读者的生活中找到美好的事物。

编辑准则（最重要的规则）

深度检索是引擎，而不是产品。读者不应感觉自己在阅读研究论文或搜索结果页面。镜像应当读起来像一篇出色的随笔，作者深刻了解读者，而不是一份证明自己做过功课的报告。

检验标准： 如果去掉所有引用和出处说明，镜像是否仍能让读者感到被理解？它是否仍能带来顿悟？它作为独立文本是否仍然成立？如果都成立，检索就达到了目的。如果镜像只有依靠引用才成立，那么检索就失败了。

引用： 可选。仅在来源确实带来价值时，谨慎地以脚注形式使用（当读者知道你真的读过那篇日记时，“你 19 岁时写下的这句话”会产生不同的触动）。但绝不能让引用成为重点，也绝不能让镜像读起来像在刻意表现自己的周全。

跨模态评估关卡（高风险镜像推荐使用）

生成镜像后，使用以下自定义维度运行 gbrain eval cross-modal（或 skills/cross-modal-review/SKILL.md 中的手动关卡）：

• VARIETY（每章是否都有新变化？）
• SPECIFICITY（是否有真实的故事、日期、引文？）
• DEPTH（是否有新见解，而非重复个人档案？）
• LEFT_COLUMN_FIDELITY（是否忠实于原书？）
• EMOTIONAL_RANGE（是否兼顾喜悦与挣扎？）

gbrain eval cross-modal --slug <slug>-personalized \
  --dimensions VARIETY,SPECIFICITY,DEPTH,LEFT_COLUMN_FIDELITY,EMOTIONAL_RANGE

通过阈值：所有维度在各模型间的平均分达到 7 分及以上。若任一维度低于 6 分，则针对性修复后重建。评估→修复→再评估的循环是质量的倍增器。评估模型组合与拒绝路由遵循 conventions/cross-modal.yaml。

儿童绘本变体

对于绘本和儿童读物（约 5K 词以内），使用 家长阅读指南 格式替代标准镜像：

• 章节部分：书中每一页/每个跨页的内容。
• 镜像部分：专门写给正在朗读的家长——每一页读起来会有什么感受，不同年龄的孩子可能会问什么，孩子提问时该如何回应，以及这本书在简单文字之下真正传达的内容。
• 包括：何时阅读、如何应对具体反应，以及将书籍的深层结构与发展心理学研究相对应。
• 语气：温暖、实用，并结合读者孩子的姓名和年龄（来自 brain 上下文）具体说明。

此类手工组装的变体使用堆叠式章节容器。

4. 分析：调用 gbrain book-mirror

gbrain book-mirror \
  --chapters-dir "$WORK/chapters" \
  --context-file "$CONTEXT" \
  --slug "$SLUG" \
  --title "Book Title Goes Here" \
  --author "Author Name" \
  --model claude-opus-4-7

该 CLI：

• 校验输入并加载章节文件。
• 打印成本估算（Opus 下约 $0.30/章）并提示确认。
• 提交 N 个带只读 allowed_tools 的子 Agent 任务。
• 等待所有子任务完成。
• 读取每个子任务的 job.result（Markdown 分析文本）。
• 将所有章节组装为一个页面，包含 frontmatter、引言、各章节部分和结语。
• 向 media/books/<slug>-personalized.md 写入一次 put_page。
• 在标准输出上报告 JSON 信封： {"slug": "...", "chapters_total": N, "chapters_completed": N, "chapters_failed": 0}。

若有任何章节失败，CLI 以退出码 1 结束，用户可重新运行——幂等键（book-mirror:<slug>:ch-<N>）会在队列层面对已完成的章节去重，因此重试成本很低。需注意，同时复现书中原文引语与读者的原话，偶尔可能触发服务商的输出过滤器；因此被拦截的章节只是失败章节——重新运行，或使用不同的 --model 重试即可。

模型：默认使用 Opus

默认模型为 claude-opus-4-7。Sonnet 也可用（使用 --model claude-sonnet-4-6），但镜像质量会明显下降——而正是这种质感，让分析读起来像是出自一位了解读者需要 Opus 级推理能力的人之手。

成本关卡

在非 TTY 环境中，若未加 --yes，CLI 会拒绝执行花费。CI / 脚本化调用必须显式传入 --yes。TTY 用户在提交前会看到 [y/N] 提示。

与轻量的静态上下文包相比，深度检索会显著提高总成本（在 Opus 费率下大约高出一个数量级）。对于读者真正在意的书籍，质量提升值得这一成本；仅在低风险运行中使用静态包。

5. PDF（可选）

brain 页面写入后（CLI 已完成 put_page），使用 skills/brain-pdf 渲染为 PDF：

# See skills/brain-pdf/SKILL.md for the invocation.

如果用户需要交付物，优先提供 PDF，而非直接发送原始 Markdown——brain 页面是事实来源，PDF 则是便于传播的成品。

6. 事实核查与交叉链接

页面生成后，对有关读者本人的事实性陈述进行一轮核查（父母、兄弟姐妹、婚姻经历、工作、家族背景）。需要留意的常见错误模式：

• 将读者父母的关系与大家庭中的模式混为一谈。
• 当读者父母仍在一起时，编造背景故事（例如“在他父母离婚之后……”）。
• 子女数量或年龄错误，配偶、子女或兄弟姐妹姓名错误。

如果某个陈述无法核实，就删除它。宁可少一些细节，也不要引入错误信息。

为分析中提到的实体建立交叉链接：

• 对于镜像页中引用的每个在 brain 中有页面的人物，都需要从 people/<slug> 添加一个回链，指向新的 media/books/<slug>-personalized 页面（依据 conventions/quality.md 的铁律）。

质量标准（基准）

章节部分应当：

• 保留作者的真实故事、统计数据、框架与示例。
• 逐字引用令人印象深刻的原句。
• 内容足够详细，使读者即使不读原书，也不会损失太多。

镜像部分应当：

• 使用上下文包中读者实际引用的原话。
• 引用具体的日期、情境，并点名具体的人。
• 读起来像一位了解读者生活的聪明朋友：指出事情，而不是给出指令。
• 只观察，不指示。 镜像呈现的是一面镜子，读者自己决定如何应对。不要出现指令、行动项、“你应该”、“不妨考虑”，也不要替读者重新安排生活。
• 将联系表述为观察或温和的提示，例如“这与……是同一种模式”或“很难不听到……的回响”，而不是“你需要处理这个问题”或“把这个框架应用到你的第三季度规划中”。
• 对直接命中的内容坦率说明（“这正是[说出一个真实情境]”）。
• 对未命中的内容诚实说明（“这一章的直接相关性较弱，因为……”）。不要强行建立联系。
• 引发共鸣，而非可执行。 镜像的作用是让人认出自己，而不是给出指示。“我们正是这样做的”才是成功。“这里有一个七点计划来修复它”就越界了。
• 对于团队镜像： 为了提供背景而提及团队成员（例如“这与某位队友的工作相关”），绝不能为了分派任务而提及（例如“队友：周五前完成 X”）。不要编造组织政策、否决链、检查清单或团队尚未做出的结构性决定。只引用团队实际文档中已有的决定。其他内容一律以问题或观察的形式呈现。

整篇文档应当读起来像出自同一个声音，贴合读者的真实生活，而不是泛泛的个人档案；并且诚实地指出，对于这位特定读者而言，书中的框架在哪些地方站不住脚。它应当让读者感到被看见，而不是被研究；并且即使去掉所有引注，依然是一篇优秀的独立文字。

反模式（请勿这样做）

• ❌ 浅尝辄止地略读章节。 常设要求：保留细节。
• ❌ 泛泛的镜像式描述。 「这可能适用于你曾经感到……的时候」→ 一经发现立即删除。
• ❌ 对读者生活的事实性错误。 组装完成后务必进行事实核查。
• ❌ 让子 Agent 拥有 put_page 权限。 信任契约是只读的；写入由 CLI 完成。
• ❌ 强行建立关联。 如果某章不适用，就直接说明。
• ❌ 在镜像中谄媚或说教。 不要出现「你应该……」、「可以考虑……」、「也许是时候……了」。
• ❌ 顾问模式。 镜像不是战略方案书。不要给出行动项，不要给具名人员分配任务，不要编造政策或组织架构，不要写「每季度审计一次」，也不要列出编号的实施清单。镜像只负责观察和共鸣。它像酒吧里的朋友说「这一段太像我们了」，而不是一次咨询服务。如果读者想把某个观察变成计划，那是他们自己的事，不是我们的。
• ❌ 虚构读者从未说过的规则。 否决链、编辑与营销分离、监察员结构、营销活动清单：如果读者没有确立这些，镜像就不能宣称它们存在。若要提及，应将其表述为作者可能提出的问题（例如「这里谁拥有否决权？」），否则就不要写入。
• ❌ 截断章节部分。 书的实际内容必须得到保留。这是头号质量问题：章节内容丰富，镜像才会丰富多样。
• ❌ 裸露的 Markdown 管道表格。 在 GitHub 和大多数渲染器上，它们会导致参差不齐的单元格错位。应使用 HTML <table>，并为每个 <td> 设置 valign="top"，或者改用分段结构。参见上文的布局硬性规则。
• ❌ 在所有章节中重复相同的 5–6 个主题。 使用质量体系中的领域映射和短语上限。
• ❌ 上下文包过于单薄。 如果上下文包只有 USER.md 的要点，镜像就会流于泛泛。应投入精力进行深度检索。
• ❌ 在高风险镜像上跳过评估关卡。 至少要进行一次自检：统计各章中关键主题的出现次数。若某个主题出现在超过 3 个章节中，交付前必须修正。

输出检查清单

• 本地存在书籍文件（路径已知）。
• 章节文本位于 $WORK/chapters/*.txt，字数合理。
• 上下文包位于 $WORK/context.md，内容充实：深度检索结果按章节分组，并附领域映射与短语上限。
• gbrain book-mirror --chapters-dir … --context-file … --slug … --title … 返回退出码 0。
• media/books/<slug>-personalized.md 已存在于知识库中。
• 布局检查：页面中不存在裸露的 Markdown 管道表格。
• 反重复自检：没有任何主题锚点出现在超过 3 个章节中。
• 事实核查已完成（与 USER.md 或其他权威来源页面相比，没有错误）。
• 已为所引用的人员和公司添加交叉链接。
• 可选：跨模型评估关卡已通过（所有维度均为 7 分及以上）。
• 可选：已通过 brain-pdf 渲染 PDF 并交付。

相关技能

• skills/brain-pdf/SKILL.md：将个性化页面渲染为 PDF。
• skills/strategic-reading/SKILL.md：通过特定问题视角阅读一本书，而不是针对整个读者进行个性化。
• skills/article-enrichment/SKILL.md：与此相同的形式，但应用于文章而非书籍。
• skills/cross-modal-review/SKILL.md：手动的第二模型质量关卡；gbrain eval cross-modal 是其脚本化的对应接口。

契约

本技能保证：

• 路由与 frontmatter 中的规范触发条件一致。
• 输出写入 writes_to: 所列目录下（如适用）。
• 所引用的约定（quality.md、brain-first.md、_brain-filing-rules.md）均被遵守。
• 隐私契约得到保持：不出现真实姓名、不出现特定分支的文件系统路径字面量，也不出现上游分支引用。

完整的行为契约记录在上文各节中；本节仅用于一致性测试。

Output Format

该 Skill 的输出结构已在上方正文各节中说明（参见 "Output"、"Brain page format" 或同类内容）。此处的字面章节标题用于一致性测试（test/skills-conformance.test.ts）。

When it fails

对于任何 gbrain 错误 code、退出码、[AGENT] 块或提示块，请遵循 agent operator protocol。针对本 Skill 的具体情况：

• CLI 会在执行前停下来确认费用（退出码 3，或在非 TTY 环境下未带 --yes 而被拒绝）：向用户转达每章的预估费用，并等待用户同意后再添加 --yes。
• 付费运行因用户设置了费用上限而以 no_pricing 停止：查询该模型的每 token 费率，告知用户；用户同意后，请 brain 主机的运维人员执行 gbrain pricing set <model> --input <usd-per-1M> --output <usd-per-1M>；然后重试。
• 退出码为 1 且 chapters_failed > 0：已完成的章节会保留；重新运行同一命令，仅重试失败的章节，并告知用户仍缺失多少章节。

Anti-Patterns

完整的反模式列表见上方正文各节；此标题用于一致性测试，以防正文使用不同的大小写写法。