Community编程与开发github.com

sheets-to-playbook

将工作坊或社区活动照片(纸质工作表的照片、承诺卡存根和可选语音备注)转化为草稿版Playbook网站,逐行对照照片检查并发布。

sheets-to-playbook 是什么?

这是一个面向活动组织者的人工智能代理技能,能从工作坊纸质工作表的照片中快速生成一个可发布的Playbook网站。它设计用于在活动当天快速交付,支持Claude Code等平台。工作流程包括:通过 `prepare` 命令准备照片(旋转、转换、生成联系表和评分),在 `labels.json` 中手工标注表格号和纸张代码,并行转录每张表格(借助本地Whisper处理语音备注),根据严格的RAW_FORMAT.md规则编写 `session.json`,然后运行 `verify` 和 `draft` 进行逐行验证。关键约束是标记来源——网站上的每一行都必须追溯到照片或语音备注,禁止发明内容。它通过 `status` 命令提供覆盖检查,通过 `review` 命令生成审阅包,并通过 `publish` 进行最终发布。它支持自动标注、合并重复表格和处理多张照片中的纸张。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Chris-Keene/sheets-to-playbook/tree/HEAD/.claude/skills/sheets-to-playbook

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

从工作表到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、源照片和语音备注,以及组织者同意不保留的任何其他内容。

相关技能