AGENTS.md — pre 项目协作指南

项目是什么

.pre 是一种 Web 原生的幻灯片+音频容器格式。它把一组单页 HTML 幻灯片和单页音频讲解打包成单个文件，并通过浏览器播放。

CLI 不是什么

CLI 不生产内容。它不会：

• 写讲稿或文案；
• 生成幻灯片内容；
• 合成语音（TTS）；
• 转换 PDF / PPTX / Keynote；
• 调用任何 LLM 或 agent。

CLI 只负责两件事：

1. pre package —— 把输入的 HTML 和音频打包成 .pre。
2. pre play —— 在浏览器中播放 .pre。

实现语言建议

pre CLI 推荐用 Go 实现：

• archive/zip：标准库支持打包与解压；
• net/http：标准库支持本地静态文件服务器；
• //go:embed：把 player/ 的 HTML/CSS/JS 直接嵌入二进制；
• 可编译成单个无依赖可执行文件，用户无需安装 Node.js 等运行时；
• 跨平台构建简单。

如果出于快速迭代目的继续使用 Node.js/TypeScript，也可以，但 Go 更符合“最小、独立、可分发”的长期目标。

Agent 与 CLI 的边界

Agent / Skill / 用户工具负责生产输入材料。CLI 负责把这些材料变成 .pre 并播放。

Agent / Skill / 用户工具
    │
    ├── 生成 slides/   （01.html, 02.html, ...）
    └── 生成 audio/    （01.mp3, 02.mp3, ...）
            │
            ↓
    pre package --slides <slides-dir> --audio <audio-dir> -o talk.pre
            │
            ↓
    pre play talk.pre

输入约定

CLI 要求两个目录，文件名按 basename 一一对应：

示例

slides/
  01.html
  02.html
  03.html

audio/
  01.mp3
  02.mp3
  03.mp3

• 幻灯片顺序由文件名排序决定。
• slides/ 和 audio/ 中 basename 必须完全匹配。
• Manifest 中的 id 取自 basename。

支持的音频格式

mp3、m4a、ogg、wav。

输出约定

pre package 生成一个 .pre 文件（ZIP 容器），内部包含：

• manifest.json：由 CLI 根据输入材料生成；
• slides/：原样复制输入；
• audio/：原样复制输入；
• player/：内置浏览器播放器；

CLI 不会修改、拆分、重采样或转码任何输入文件。

Manifest 结构示例

{
  "version": "1.0.0",
  "title": "演示标题",
  "author": "作者",
  "slides": [
    {
      "id": "01",
      "file": "slides/01.html",
      "audio": "audio/01.mp3",
      "start": 0.0,
      "end": 12.5
    },
    {
      "id": "02",
      "file": "slides/02.html",
      "audio": "audio/02.mp3",
      "start": 12.5,
      "end": 28.0
    }
  ],
  "notes": "notes.md"
}

播放器交互

pre 的浏览器播放器不显示任何可见控制界面。播放时，当前幻灯片铺满视口，对应音频同步播放。

用户通过键盘操作：

设计原则：

• 不添加按钮、进度条、工具栏等可见控件。
• 播放器 CSS 保持极简，幻灯片本身即为全部视觉内容。
• 键盘事件在页面级别监听，无需聚焦到特定元素。

Agent 应该如何调用 CLI

如果 agent 想帮用户生成 .pre，流程应该是：

1. 把每页 HTML 幻灯片写入临时目录，例如 /tmp/work/slides/。
2. 把每页音频写入临时目录，例如 /tmp/work/audio/，确保 basename 与幻灯片一致。
3. 执行：

   pre package --slides /tmp/work/slides --audio /tmp/work/audio -o talk.pre

4. 如需验证，可执行：

   pre play talk.pre

Agent 不应该要求 CLI 去生成内容、合成语音或拆分音频。如果 agent 需要这些能力，它必须在调用 pre package 之前自行完成。

为什么这个边界很重要

• CLI 保持确定性和离线可用性，不依赖任何外部模型或服务。
• 不同的 agent 可以在内容创作层竞争或协作，而无需修改 CLI。
• 用户可以自己手写、用熟悉工具导出，或让 agent 辅助——三种方式都通往同一个 CLI。

pre play 的浏览器播放实现建议

pre play 不是常驻后台服务，而是临时启动一个本地 HTTP 服务、打开浏览器，并在浏览器关闭后自动退出。

推荐实现（Go）：

1. 把 .pre 解压到临时目录。
2. 用 net/http 在 127.0.0.1:0 上启动静态文件服务，随机端口避免冲突。
3. 用 os/exec 或 github.com/pkg/browser 打开 http://127.0.0.1:<port>/player/player.html。
4. 播放器页面通过 fetch('/__ping') 或 navigator.sendBeacon('/__ping') 定期发送心跳。
5. 当心跳停止超过一定时间（如 5 秒），调用 http.Server.Shutdown 并清理临时目录。

要点：

• 127.0.0.1 确保服务不暴露到局域网。
• 用 net.Listen("tcp", "127.0.0.1:0") 取随机端口，避免端口占用。
• 不能依赖 exec.Command 的进程退出来判断浏览器是否关闭，因为 open/xdg-open/start 通常只是拉起浏览器，不会等待。
• 心跳是最简单的跨平台关闭检测方案；也可用 WebSocket 统计连接数。
• 这样 CLI 不会留下后台服务，播放结束即可清理临时文件。

许可证

MIT