margo：AI Agent 工具实践指南

真正理解margo，要从它处理的任务开始：margo 是一款快如闪电、受 Hugo 启发的演示引擎，它将纯 Markdown 编译成样式精美、高度可编写脚本的幻灯片，专为开发人员和 AI 代理而构建。团队若要把它用于文档与演示交付，应先处理内容结构和版式在转换后容易走样，否则试用结果很容易失真。落地前可以拿一份结构复杂的真实文档完成转换，用标题层级、表格图片、字体版式和可编辑性判断它是否真的省事。我的判断是，它更适合经常交付正式文档或演示稿的团队；若眼下没有这类需求，先保留观察即可。

Markdown 演示引擎 | 灵感来自 雨果 | 开发商和代理商友好

该项目的概述是使用 margo 构建的 幻灯片！

玛戈

margo 是一款 Go 应用程序，用于使用类似 Hugo 的项目模型从 Markdown 构建幻灯片。

当前的存储库包含：

• CLI 实施
• docs/product/PRD.md 和 docs/product/implementation-plan.md 中的产品文档
• 用户指南 docs/AUTHORING_GUIDE.md
• 工作本地套牌 scaffold/build/serve 流程
• examples/reference-deck 中的一个专用参考夹具平台
• examples/benchmark-deck 中的一套承诺基准套牌
• examples/omarchy-theme-showcase 中可安装的 Omarchy 调色板主题和预览平台

目前状态

这是一个早期原型，不是一个可发布的工具。

版本控制的 margo 产品平台 随每个版本发布一起部署到存储库的 GitHub 页面站点。发布的网站是使用与发布的二进制文件相同的发布标签构建的。它的来源也是用户和贡献者的工作平台和参考。

今天工作：

• margo new <deck-name>
• margo init
• margo build
• margo serve
• margo pack <deck-dir>
• margo unpack <archive.margo> [destination]
• margo theme add <repo>
• margo theme pack <theme-name>
• margo theme import <archive.margot>
• margo theme list
• margo clean
• 玛戈升级--计划|--应用
• margo 技能安装品牌主题 --scope 用户|项目[--计划]
• margo deploy github-pages
• margo new slide <name>
• margo 滑动插入件 <name>（--<slide> 之前） | --<slide>之后 | --位置 <n>)
• margo 滑动移动 <slide>（--<slide> 之前） | --<slide> 之后 | --位置 <n>)
• margo slide delete <slide>
• margo new theme <name>
• margo new theme <name> blank
• margo theme update <name>
• margo theme contract init [theme-name]

在内容模型中实现：

• YAML 配置解析
• YAML 幻灯片正面内容
• 使用 Goldmark 进行 Markdown 渲染
• 从 themes/<name>/ 加载主题
• 每张幻灯片的布局选择
• 草稿过滤
• hidden/skip 过滤
• 章节上下文
• 基于捆绑的 Markdown 笔记，包括演讲者脚本和研究，以及可选的交互式 HTML 查看

未完成：

• 高级 PPTX 主题食谱和完整的短代码奇偶校验
• 演示者模式
• 支架默认主题之外的浏览器刷新注入

构建

构建本地二进制文件：

go build -o ./bin/margo ./cmd/margo

无需安装直接运行：

go run ./cmd/margo help

使用 Go 安装最新的标记版本：

go install github.com/jjanuszczak/margo/cmd/margo@latest

对于预构建的二进制文件，请从以下位置下载适合您的平台的存档： GitHub 发布 页面和 使用发布的 checksums.txt 文件进行验证。 macOS 和 Linux 用户可以 也可以通过个人 Homebrew Tap 安装：

brew install jjanuszczak/margo/margo

构建版本化的发布档案：

VERSION=0.1.0 ./scripts/release.sh

维护人员的自制包装说明位于 docs/HOMEBREW.md。

通过传递显式的 GOOS/GOARCH 对来覆盖默认目标：

VERSION=0.1.0 ./scripts/release.sh darwin/arm64 linux/amd64

维护者发布程序记录在 docs/RELEASING.md.

示例工作流程

创建套牌：

./bin/margo new my-deck
cd my-deck
../bin/margo build

本地提供甲板服务：

../bin/margo serve

如果默认预览端口不可用，请以交互方式选择另一个端口或显式传递一个端口：

../bin/margo serve --port 1414

创建幻灯片：

../bin/margo new slide roadmap

将幻灯片插入现有幻灯片：

../bin/margo slide insert roadmap --after 02-why --archetype agenda

当每个现有捆绑包都使用位置名称（例如 01-title、margo）时 自动对以后的捆绑包重新编号。对于具有描述性捆绑名称的套牌， 它保留这些路径并仅更新幻灯片顺序。添加 --renumber 时 您明确希望将这些包路径转换为位置名称。

使用相同的排序规则移动或删除幻灯片：

../bin/margo slide move 12-market-size --after 04-product
../bin/margo slide delete 04-product

删除将捆绑包移动到甲板本地 .margo-trash/ 目录中，因此它 内容、笔记和资产都可以恢复。

创建一个主题：

../bin/margo new theme custom

从 Git 存储库安装供应商主题：

../bin/margo theme add https://example.com/brand-theme.git --ref v0.1.0
../bin/margo theme list

从记录的 Git 源更新已安装的供应商主题：

../bin/margo theme update brand

在旧套牌中升级 margo 管理的特工指导，无需更换 创作的幻灯片、配置、资产或主题：

margo upgrade --plan
margo upgrade --apply

为已存储在 Git 中的卡片配置 GitHub Pages 部署 存储库。生成的工作流在推送 v* 标签时部署，并且可以 也可以根据 GitHub 操作的需求运行：

margo deploy github-pages --margo-version v0.3.0

新的甲板脚手架包括用于甲板创作的存储库本地代理指导， 主题工作、品牌主题创建、GitHub 页面部署和错误分类。 在旧甲板上运行 margo upgrade --plan 以安全地添加缺失的指导。 使用“margo Skills install”安装完整的用户全局品牌主题工作流程 品牌主题--范围用户`。

项目形状

目前生成的牌组如下所示：

my-deck/
  margo.yaml
  slides/
    01-title/index.md
    02-why/index.md
  themes/
    default/
      theme.yaml
      layouts/
        deck.html
        slide-default.html
        slide-title.html
  archetypes/
    default/
      archetype.yaml
  assets/

开发笔记

• 存储库根目录是 CLI 源存储库，而不是套牌项目。
• .gitignore 会忽略生成的测试平台和本地缓存。
• examples/reference-deck 是用于手动检查和回归工作的专用夹具平台。
• examples/benchmark-deck 是专用的 20 个载玻片平台，用于手动性能和密度检查。
• margo serve 默认使用 127.0.0.1:1313。如果该端口不可用，交互式运行现在会提示输入另一个端口，非交互式运行应使用 --port <port>。
• 某些本地预览验证需要在沙箱外部运行，因为在此环境中绑定本地端口可能受到限制。

通过以下方式对承诺的 20 张幻灯片构建路径进行基准测试：

go test -run '^$' -bench BenchmarkBenchmarkDeckBuildFlow ./internal/output/html