从工作表到Playbook
仓库:包含 ingest/ingest.py 的文件夹(如果Claude Code是在该克隆内打开的,则为当前项目)。以下所有路径均相对于它。在阶段3之前请先阅读 ingest/RAW_FORMAT.md:它包含转录格式和编写playbook的规则。
目标是当天快速交付,且不编造任何内容。网站上的每一行都必须追溯到一张照片或一段语音备注;ingest.py verify 会强制实施这一点。
在每一阶段用一两行告诉用户你正在做什么。以下阶段时间对于大约十二张桌子是粗略指南。
在活动当天之前,playbook.config.json 应列出组织者姓名并提供playbook的网址(承诺卡上的二维码指向该网址)。如果它仍保留中性默认值,请告知用户,但继续操作:这些设置只更改名称和颜色,不更改内容。--config <文件> 配合 verify、draft 和 publish 可选择不同的设置文件。
1. 准备(1到2分钟)
python3 ingest/ingest.py prepare "<文件夹>"
python3 ingest/ingest.py transcribe # 仅当文件夹中有语音备注时运行;在后台运行
prepare 在 runs/ 下创建新的运行(并将 runs/latest 指向它):照片旋转至正立,HEIC转换,每张照片给出锐度评分,生成用于细读的2×2平铺图,联系表存放在 contact/ 中,语音备注转换为16 kHz WAV。transcribe 使用本地Whisper(small.en,下载后离线运行),并根据开头的“Table seven…”猜测每条备注所属的表格。
第二批照片(更多照片或卡片,在第一半进行中之后):python3 ingest/ingest.py prepare "<文件夹>" --into <运行> 将其添加到同一运行中。新ID从最后一个延续(P022…),保留标签和原始文件,已存在于运行中的文件被跳过。然后仅标注新ID。
2. 标注并检查覆盖率(约5分钟;请先完成这一步,它耗时关键)
查看每张联系表(contact/sheet-*.jpg),对于缩略图不清晰的地方,查看 view/ 中的照片。在运行文件夹中编写 labels.json:
{"photos": {"P001": {"table": 7, "sheet": "S2"}, "P014": {"kind": "stubs"}, "P020": {"kind": "other", "note": "房间照片"}},
"audio": {"A01": {"table": 7, "by": "speech"}}}
- 每张联系表底部角落带有打印的代码(S1、S2、S3、SS)和打印的标题;表格编号由表格负责人手写在右上角的圆圈内以及代码旁边(
S2 · Table 7)。工具包的默认标题:S1“支持在何处卡住?”,S2“什么有帮助,或没有?”,S3“人们现在可以尝试什么,以及如何坚持下去?”,SS为侧页“听到好的东西?写在这里。”(引用 · 问题 · 资源)。如果组织者更改了问题,请依据打印的代码。当圆圈和角落不一致时,笔的颜色和内容可解决:检查该表格的其他联系表。 - 保留
transcribe已填写的任何音频标签,但在对照转录第一行检查后保留。 - 两张不同但代码和表格编号相同的联系表(
status会列出任何包含超过一张照片的联系表:检查这些):如果国家/地区和内容重叠,则是一张桌子使用了两个副本;两者都标注该编号,并且阅读者转录两者。如果它们显然是两张桌子,给第二个分配一个从91开始的备用编号,添加"note": "写了22;第二张桌子",并告知用户。任一张桌子都可以是“第二张”:选择一张,并在备注中描述两者(部门、笔的颜色),以便审阅能够区分它们。 - 特写镜头中没有表格编号(仅显示计票框等):将其标注为它匹配的联系表,并添加
"note": "表格根据<匹配的内容>推断"。 - 一张照片中有两张联系表(并排别在一起):将其标注为
"sheet": ["S2", "S3"],以便status将其计入两者,并在note中说明,以便阅读者知道哪一半是哪一张。 prepare无法旋转在画面中上下颠倒的照片(没有可读取的旋转标志)。阅读者可以处理,但请在note中说明。卡片照片的锐度评分低于联系表(普通卡片,细笔),因此在要求重拍之前,请在view/中检查一张标记为BLURRY?的卡片。
然后运行 python3 ingest/ingest.py status(如果没有12张表格,则添加 --tables <n>),立即告知用户任何缺失或模糊的联系表。联系表还会标记LOW-RES(通过消息应用转发的:如果文字较大则没问题)和DARK(通常可阅读):提及它们,但不是需要重拍的内容。理想情况下,此检查应在联系表仍挂在墙上且可以再次拍照时进行。
3. 转录每张表格(并行,约5到10分钟)
为每张表格生成一个子代理(Agent工具,general-purpose,后台运行,全部在一条消息中),如果有承诺卡存根,则再生成一个。不要降低模型等级:手写识别准确度至关重要。每个提示必须独立并包含:
- 绝对仓库路径、运行文件夹、表格编号、其照片ID(
view/<id>.jpg和manifest.json中列出的平铺图),以及其语音转录路径(如有)。 - “阅读
ingest/RAW_FORMAT.md阶段1,并严格按照它执行。在运行文件夹中编写raw/T<nn>.json,然后运行python3 ingest/ingest.py verify --run <运行>并修复它报告的有关你文件的任何错误。回复简短摘要:每张联系表的项目数,每个unclear条目,以及你省略的每个被划掉的单词。” - 对于存根:按照阶段1末尾所述编写
raw/commitments.json,包括卡片上的可选姓名和组织字段,完全按照原文书写,并遵循其中的卡片规则(未撕裂的卡片、签章、一张卡片出现在两张照片中)。
在它们运行时,自行阅读语音转录(如果有),以便在撰写之前了解整个会场的情况。
4. 编写Playbook(约10到15分钟)
遵循 RAW_FORMAT.md 阶段2。编写 <运行>/session.json,并设置 meta.status: "draft"。从 examples/session-template.json 开始 meta,并根据用户告知的内容填写活动的具体细节(活动名称、日期、地点);如果用户知道实际出席人数,则将 people 设置为该数字。切勿猜测这些内容:将字段保留为模板中的样子并列出给用户。
5. 验证、修复、构建审阅包
python3 ingest/ingest.py verify --links
python3 ingest/ingest.py draft # <运行>/playbook-draft.html:虚线框 = 空白,标签 = 来源
python3 ingest/ingest.py review # <运行>/review.html:每个项目旁边有其照片
修复每个错误(无法追踪的行、偏离的引用、遗留的姓名)并重新运行,直到验证通过。警告留给人类审阅:报告它们,不要掩盖它们。
然后向用户提供审阅摘要:挑战和哪些表格合并了,每个 unclear 阅读项及其照片ID,每个阅读者省略的划掉单词,未使用的原始项目,链接问题,以及你不确定如何分组的内容。review.html 显示每位阅读者的备注和每张表格下的“谁在这张桌子?”计票。为用户打开 review.html 和 playbook-draft.html。
有大量不确定的单词? 审阅应用比逐行阅读 review.html 更快:
python3 tools/review/make_review.py --run <运行>
``` 构建 `<运行>/review/index.html`,每个不确定的阅读项附带手写特写图。用户确认或更正每一项,保存决策文件,然后运行 `python3 tools/review/apply_review.py --run <运行> <decisions.json>` 将阅读结果写回原始文件和 `session.json`。随后重新运行 `verify` 和 `draft`。不属于不确定单词的问题(可能表示划掉的勾号、是否合并两张表格、是否命名资源)在构建应用前放入 `<运行>/review/extra.json` 作为检查点和决策项;`apply_review.py` 将答案列在 `<运行>/review/to-action.md` 中供你采取行动。参见 `tools/review/README.md`。
## 6. 发布(在人检查草稿之后)
将审阅者的修复应用到 `session.json`,设置 `meta.status` 为 `"final"`,然后:
```bash
python3 ingest/ingest.py publish --links # 如果有任何内容无法追踪或某个部分为空则拒绝
这会写入 data/session.json 和 playbook/index.html。playbook/ 文件夹是一个静态网站:将其部署到任何地方是一个单独的步骤,因此请先询问。页面中的所有链接均由脚本处理,因此直接从磁盘打开也能正常工作。
绝不能
- 添加来自通用知识的内容,即使是“有帮助”的上下文。空着总比编造好。
- 默默猜测一个单词:使用
[?word]或[illegible]并将其列出。 - 在已发布的页面上放置任何人的姓名或雇主名称,除非是该人在卡片上写下的自己的姓名和组织(
verify会检查这些内容与卡片是否一致)。 - 在未通过
verify且没有人类阅读草稿的情况下发布。
之后
照片和语音备注可能包含姓名和面孔。一旦Playbook定稿,提醒用户删除 runs/*/audio、源照片和语音备注,以及组织者同意不保留的任何其他内容。