教材转笔记的总流程

本页最后更新于 ，内容可能过时

本文件写顺序, 产物传递, 以及写作与补图的操作细则
笔记的结构与版式细则在仓库根 STYLES.md, 本文件不重复

• 渲染页面: pdf-page-image
• 写笔记: 版式照 STYLES.md, 流程照本文件
• 裁插图: pdf-figure-crop
• 上传与回填链接: coscmd

定目标文件

路径形如 Coursera/[学科]/(课程)/(N)章节名.md
(N) 是仓库内的顺序号, 与教材章号不是一回事
输出换到别的根目录时, 按同样的三层结构套用

文件不存在就先建 0 字节骨架
空骨架文件是合法的中间状态, 可以提交

教材名从仓库根 README.md 的映射表取

流程

1. 查对应关系
   读仓库根 README.md 的映射表
   左边是 Coursera/<学科>/ 下的笔记目录, 右边是电子书根目录 G:\我的云端硬盘\电子书 下的 PDF 路径
   没有对应条目就直接问用户

用户未指定章次时, 先询问, 不代为选择
整本书丢过来时尤其容易犯这个错: 目录里有很多章, 随便选一章做下去等于替用户做了决定
正确做法是只读到能列出候选章为止, 把候选项列出来让用户选
不要用"先按第 X 章做起来"这种默认值推进, 也不要拿第一章当答案
只有用户明确说了"随便挑一章""你看着办"时才自行选定, 并且要先说清楚选了哪一章

1. 对齐风格, 这一步做不完不要进入写作

参考笔记由用户指定, 不代为选择
问用户: 这次参考哪几篇已完成的笔记
用户给了路径就直接用
用户没给, 从同目录下属同一学科体系的已完成笔记里列 5 到 8 篇候选让用户选
候选要挑跟本次教材同一门课, 或同一编写风格的
用户说"你看着办"时才自行选定, 并说明选定的篇目

参考笔记要给两样东西
把绝对路径交给子 agent, 要求每个子 agent 至少全文读 2 篇
只给摘要不够, 摘要会丢掉行文节奏和排版细节
只给路径也不够, 各章之间会不统一

风格落点是 STYLES.md
按参考笔记复查一遍 STYLES.md, 与实际写法有出入的地方当场问用户
定下来以后改 STYLES.md, 不要改子 agent 的提示词
提示词里只给 STYLES.md 的绝对路径, 不内联全文
内联的问题: 同一段内容在十几个提示词里各存一份, 改一处要改十几处;
长任务跑到中途上下文被压缩时, 内联的部分可能丢失, 文件路径不会

STYLES.md 与 CLAUDE.md 冲突时
CLAUDE.md 管用词与语气, STYLES.md 管文件形态, 两者不应重叠
真的重叠了, 当场问用户以哪个为准, 并把结果写进 STYLES.md

风格没对齐不要开跑
整本或整章派多个子 agent 时, 这一轮对齐做错, 返工面是全部章
宁可先拿一节试写, 让用户看过再批量开

1. 查看 PDF 的基本情况
   python .claude/skills/pdf-page-image/scripts/render.py info "<pdf>"
   记下页数, 文字层判定, 书签目录
   判定为 scanned garbled thin 时只能靠目测定位页码, 正文靠读图
   判定为 ok 也只看作可以按关键词定位页码, 正文仍要读图核对
   [只有由 epub 或 txt 等纯文本转换生成的 PDF, 文字层才是可信的原生文本, 才可以不读图]
   判定的具体口径见 pdf-page-image
   没有书签目录时先做 pdf-bookmark

2. 渲染本节页面
   pdf-page-image 的 render, 默认一次一页
   渲染出的页面图给下一步读, 坐标清单(与图同名的 .json)留着给裁图换算

3. 读图写笔记
   版式与取舍照 STYLES.md
   篇幅大时按 并行写作 一节拆给子 agent

4. 插图默认只留占位
   写笔记时默认不裁图, 不上传
   该进笔记的图, 图注照常写, 图片位置写成 ![图N-M]()
   不调用 pdf-figure-crop 与 coscmd, 也不读页面图找图
   教材里取不到, 又确实需要图时, 问用户要, 不要自己上网找
   用户给了网址或图片文件就用, 没给就按纯文字排版, 不要为了填空硬配图
   等全部笔记写完, 交给用户看时再问用户要不要补图
   用户明确要补图, 才在页面图上量坐标 → pdf-figure-crop 裁出 → 按 coscmd 上传 → 回填链接, 替换占位

补图时要分清两种情形

情形	步骤
首次插入新图	上传, 校验链接, 回填
替换笔记里已有的图	走 coscmd 的七步替换流程

七步流程里有取原图, grep 旧链接, 删旧对象这三步, 只对替换有意义
新图误走七步会去 grep 一个不存在的旧链接并尝试删除

1. 停下来给用户看
   默认一节做完就停, 不要一次把整本做完
   用户指定做整章或整本时, 按用户给的粒度在批次之间停
   等用户确认风格和取舍之后再继续
   这一轮顺带问用户要不要补图

返工

用户提出修改时, 按下面这张表判断落在哪一步, 只重跑受影响的部分

用户说的	重跑哪几步
换材料, 换章节	从第 3 步起, 全部重来
换参考笔记	第 2 步重新对齐, 已写的内容按新风格复查一遍
内容取舍, 例题	第 5 步, 另读该节页面图
分页, 标题层级	第 5 步, 一般只调排版
补图	第 6 步的补图流程
图注, 图号	只改笔记, 不动图

材料没变就不要重跑读图, 渲染出的页面图还在临时目录里, 直接接着用

长会话的上下文可能被自动压缩
压缩之后先重读目标笔记已有的小节与临时目录的产物清单, 确认做到哪一步
不要凭记忆续写, 否则会把已经写过的段落再写一遍

同一条命令连续两次出现同样的失败就停下来, 把命令与错误原文报给用户, 不要反复试

产物传递

临时目录固定在仓库外

$tmp = "$env:TEMP\mindcity-pdf\<教材名>"
New-Item -ItemType Directory -Force $tmp

阶段	产物	命名
渲染	页面图	p<起>-<止>-d<dpi>.png, 单页写成 p<页号>-d<dpi>.png
渲染	坐标清单	同名 .json
裁剪	插图	fig-<章号>-<图序>.png, 例如 图2-1 存成 fig-2-1.png
上传	图床 key	沿用 coscmd 的 <年月日时分秒>000.png, 并行补图时末三位按子 agent 的编号分块

并行写作

拆分粒度按章或按节, 看读图量定
一章正文超过这个量就按节拆, 没超过就一章一个子 agent

• 按章拆时一篇笔记一个子 agent, 各写各的文件
• 按节拆时一个子 agent 写一节, 产物先落临时文件, 由主线程按顺序合并进目标笔记
• 两种拆法都不要让多个子 agent 写同一个文件
• 子 agent 不再往下派子 agent, 一层为止

子 agent 提示词清单

逐条写明, 不要指望子 agent 自己推断

• 目标文件绝对路径, 教材 PDF 绝对路径, 页码范围
• STYLES.md 的绝对路径
• 参考笔记的绝对路径, 并要求至少全文读 2 篇
• 节标题层级用 # 还是 ##, 当场写明, 不交由子 agent 判断
• 插图只留 ![图N-M]() 空占位, 不裁不传
• 补图批次另给图床百位区间, 并写明不要用别的区间
• 不往下派子 agent
• 只写自己的目标文件, 不改仓库其他文件与 skill
• 中间产物放 %TEMP%
• 每写完 2 到 3 节写入一次, 不要等全部写完再一次性写入
• 报告要列: 收录的图号, 跳过的页, 拿不准的写法, 与 skill 冲突处, 自己的决定

补图批次里, 图床 key 是秒级时间戳加三位计数
按子 agent 分块: 子 agent 1 占 000 到 099, 子 agent 2 占 100 到 199, 以此类推
同一个 agent 的同一秒传多张, 就在自己块内递增
[百位区间只有 10 个, 同时跑的子 agent 不超过 10 个]

中断与续跑

并行写作最常见的问题是进度丢失, 按这几条处理

• 子 agent 被用户停止后, 主线程不能把它恢复
  SendMessage 会直接返回失败, 不要把时间花在重试上
  这是客户端的生命周期限制, 与所用 API 服务商无关
• 用户可以在 transcript 视图里手动恢复被停掉的 agent, 恢复后它接着跑
  所以需要保留上下文时, 请用户从 transcript 视图恢复, 不要另起新 agent 重跑一遍
  用户不想恢复, 或者原 agent 已失效时, 才按下面的续写流程起新的
• 想让在跑的子 agent 改做法时, 用 SendMessage 下发新指令, 不要先 stop
  下发的消息会在它下一次工具调用时生效, 而被 stop 之后只有用户能救回来
• 已经停止的 agent, 起一个新的续写
  提示词第一件事写成: 先 Read 目标文件全文, 列出已完成的节与未完成的节, 以现有内容为基础续写, 不整体重写, 不覆盖已完成部分
  同时写明: 已有的图片链接保持不动, 不重新上传
• 一节的正文先写完, 再处理插图, 中途中断时正文仍然可读

主线程收尾

每个子 agent 结束任务后, 主线程按 STYLES.md 的「自检」一节扫一遍

• 一次 grep 扫全部文件, 不逐篇打开
• 图号与例题号的前缀, 跳号与重复
• 图注数与图片行数是否一一对应
• 标题层级: 各篇之间用同一级, 单篇之内没有混用
• 跨篇重复
  只比长度超过若干字符的整行
  命中的绝大多数是化学方程式, 属于正常引用, 不算重复
  真正要看的是一整段解释性文字被两章各写一遍

机械性质的小问题, 比如 \ce{} 里混了全角顿号, 主线程直接改掉, 不要为此重派子 agent
内容问题才重派

冲突与未覆盖

skill 与参考笔记冲突时, 按第 2 步定的口径处理
第 2 步没覆盖到的, 以参考笔记为准, 并把冲突写进报告
skill 没覆盖的地方可以自行决定, 但要把决定逐条列进报告
渲染或排版拿不准的写法照原样写, 留给用户确认

注意事项

• 非必要不做 OCR, 正文靠读渲染出的页面图
• 书页号与 PDF 页号不一致, 偏移量按章可能不同, 优先采信 PDF 书签目录
• 中间产物一律放 %TEMP%, 仓库的 .gitignore 没有通用 tmp 规则, 不能依赖它
• 一章 30 到 45 页的正文, 逐页读图加写完正文, 一个子 agent 约需 40 到 95 分钟
  整本并行时要提前跟用户说明这一点, 不要默认几分钟就能返回
• 子 agent 之间不要写同一个文件, 也不要让它们改同一份 skill