PosterForge Skill

English

用命令行参数或一份很小的 JSON，为 Agent、机器人、告警、战报、汇报和社交内容生成高质量移动端文字海报。

PosterForge Skill 不是设计软件，不是图片生成模型，不是 PPT 工具，也不是多图轮播系统。它是一个面向 Agent 的文字海报渲染器：支持直接命令行输入，版式稳定，本地渲染，输出高分辨率 PNG。

| 告警简报 | 事故复盘 | 用户反馈 | | --- | --- | --- | | | | |

30 秒开始

npm install -g posterforge

最快的方式不需要先写 JSON，直接通过命令行传入内容：

posterforge render \
  --style signal \
  --title "Service Health" \
  --summary "Errors dropped after the routing fix. Latency is back within the normal range." \
  --item "Impact: Only one provider route was affected." \
  --item "Action: Keep the fallback route enabled and monitor for one hour." \
  --item "Status: Traffic is stable and no new alerts are firing." \
  --out card.png

默认逻辑画布是 1080x1440，导出为 3x，最终 PNG 尺寸是 3240x4320。

如果需要稳定复用，再创建 card.json：

{
  "style": "signal",
  "title": "Service Health",
  "summary": "Errors dropped after the routing fix. Latency is back within the normal range.",
  "content": [
    { "title": "Impact", "text": "Only one provider route was affected." },
    { "title": "Action", "text": "Keep the fallback route enabled and monitor for one hour." },
    { "title": "Status", "text": "Traffic is stable and no new alerts are firing." }
  ],
  "footer": "Ops Brief"
}

渲染：

posterforge render card.json --out card.png

也可以先用参数生成一份可复用 JSON：

posterforge spec \
  --style ledger \
  --title "Alert Brief" \
  --summary "Kong 4xx increased on one route." \
  --item "Cause: Upstream returned model-not-found." \
  --out card.json

为什么用 PosterForge

| 需求 | PosterForge 的做法 | | --- | --- | | Agent 需要稳定输出 | 使用很小的 CardSpec，不依赖自由 HTML 或图片提示词。 | | 文字海报必须可读 | 每个主题都有保守的字数预算。 | | 自动化流程需要可重复 | 依赖安装完成后，本地渲染结果稳定。 | | 团队需要多种风格 | 内置 20 套视觉系统，用短 style 名选择。 | | 开源贡献要简单 | 新主题集中在模板注册表和模板包里维护。 |

使用场景

| 场景 | 示例 | 推荐风格 | | --- | --- | --- | | 告警根因总结 | examples/alert.json, examples/incident-brief.json | ledger, audit, terminal, noir | | 排行榜、战报 | examples/battle-ranking.json | arena, podium, sprint, matrix | | 实验或 KPI 更新 | examples/experiment.json | signal, prism, atlas, mercury | | 周报、日报、团队简报 | examples/weekly-brief.json | editorial, signal, atlas | | 产品发布更新 | examples/product-update.json | signal, bulletin, compass |

场景预设

Preset 是常见 Agent 任务的内容蓝图。它先生成标准 CardSpec，你可以直接用默认风格，也可以覆盖成其他视觉风格。

posterforge presets
posterforge preset incident-review --out incident.json
posterforge render --preset alert-brief --out alert.png
posterforge render --preset launch-notes --style mercury --out launch.png

内置预设：

| Preset | 默认风格 | 适合场景 | | --- | --- | --- | | alert-brief | ledger | 告警排查、根因总结 | | incident-review | noir | 事故总结、复盘快照 | | weekly-report | editorial | 周报、团队简报、管理层摘要 | | launch-notes | bulletin | 发布说明、上线公告 | | decision-memo | compass | 架构决策、产品取舍 | | experiment-result | signal | 实验结果、KPI 变化 | | ranking-report | arena | 排行榜、战报 | | product-feedback | prism | 用户反馈、问卷总结 | | daily-digest | mercury | 日报、站会简报 | | quote-card | pulse | 金句、原则、短观点 |

Preset 封面图廊：

| 告警简报 | 事故复盘 | 周报 | | --- | --- | --- | | | | |

| 发布说明 | 决策备忘 | 实验结果 | | --- | --- | --- | | | | |

| 战报排行 | 用户反馈 | 日报 | | --- | --- | --- | | | | |

| 金句卡 |   |   | | --- | --- | --- | | |   |   |

完整说明见 docs/PRESETS.md。

渲染内置示例：

pnpm render:alert
pnpm render:incident
pnpm render:weekly
pnpm render:product

主题图廊

下面这些预览图都来自同一份 JSON 结构，可以用 pnpm generate:previews 重新生成。

| Arena | Podium | Sprint | | --- | --- | --- | | | | |

| Delta | Matrix | Heat | | --- | --- | --- | | | | |

| Ledger | Dossier | Audit | | --- | --- | --- | | | | |

| Terminal | Bulletin | Noir | | --- | --- | --- | | | | |

| Graphite | Signal | Pulse | | --- | --- | --- | | | | |

| Atlas | Prism | Compass | | --- | --- | --- | | | | |

| Mercury | Editorial |   | | --- | --- | --- | | | |   |

安装

环境要求：

• Node.js >=20
• 开发时推荐使用 pnpm
• 高质量 PNG 导出需要 Chromium、Google Chrome 或兼容的无头浏览器

直接从 GitHub 安装：

npm install -g github:sumingcheng/posterforge-skill

从 npm 安装：

npm install -g posterforge

直接从源码使用：

git clone https://github.com/sumingcheng/posterforge-skill.git
cd posterforge-skill
pnpm install
pnpm build
node ./bin/posterforge.mjs render ./examples/alert.json --out ./dist/alert.png

开发时也可以把本地 CLI 挂到全局：

npm install -g .
posterforge templates

CLI

从 JSON 渲染：

posterforge render card.json --out card.png

直接传参数渲染：

posterforge render --style mercury --title "Launch Notes" --summary "The release is ready." --item "Scope: Mobile onboarding." --item "Next: Watch activation." --out launch.png

创建 starter spec：

posterforge init --style signal --out card.json

创建场景预设 spec：

posterforge preset alert-brief --out card.json

列出所有风格：

posterforge templates

列出所有场景预设：

posterforge presets

输出 npm 包内置的 skill 文件路径，方便接入 Agent runtime：

posterforge skill-path

Agent 和 Skill 使用

项目内置了 Skill 定义：skill/SKILL.md。可以给 OpenClaw、Codex、Claude 或任何支持读取 skill 文件并调用本地命令的 Agent runtime 使用。

推荐流程：

1. 把原始内容压缩成 CardSpec。
2. 根据意图选择风格。
3. 检查 docs/TEXT_BUDGETS.md。
4. 渲染 PNG。
5. 检查图片是否截断或拥挤，再交付。

Agent 不应该在输出里说“我正在使用这个 skill”，直接生成图片即可。

完整 Agent 接入说明见 docs/AGENT_USAGE.md。

CardSpec

推荐输入非常简单：

type CardSpec = {
  style: string;
  title: string;
  summary: string;
  content: Array<{ title: string; text: string }> | string[] | string;
  footer?: string;
};

新的输入尽量只使用 title、summary、content。旧的 metrics、rankings、sections 仍然兼容，会被自动归一化成 content。

完整协议见 docs/CARD_SPEC.md。

风格

通过 style 选择视觉系统：

| 分类 | 风格 | 适合场景 | | --- | --- | --- | | 排行/战报 | arena, podium, sprint, delta, matrix, heat | 战报、排行榜、Top List | | 运维/事故 | ledger, dossier, audit, terminal, bulletin, noir, graphite | 告警、事故、根因分析、排查总结 | | 汇报/简报 | signal, pulse, atlas, prism, compass, mercury, editorial | KPI、实验、周报、日报、方向性总结 |

查看所有可用模板：

posterforge templates

字数预算

每个风格都有保守的字数预算。因为这些模板是固定海报版式，文字太长会破坏设计，甚至发生截断。

渲染器也会在截图导出前做文本保护：受约束的文本块会自动使用更安全的换行，并在即将溢出时小幅缩小字号。这是保护层，不是替代精简输入的理由。

每个主题的限制见 docs/TEXT_BUDGETS.md。

简单规则：

• 标题要短，不要写成长句。
• 摘要是一段结论，不要写成正文。
• 每个内容点都要短。
• 原始日志、长聊天记录、长文档必须先压缩。
• 如果渲染后看起来拥挤或被截断，必须缩短后重新渲染。

架构

CardSpec JSON
  -> schema normalization
  -> template registry
  -> React/HTM templates
  -> Tailwind CSS
  -> high-DPI Chromium PNG

关键文件：

• src/schema/card-spec.mjs：输入归一化
• src/templates/style-pack.mjs：模板实现
• src/templates/registry.mjs：风格注册
• bin/posterforge.mjs：CLI 渲染器
• docs/DESIGN_RESEARCH.md：设计参考

开发

pnpm install
pnpm build
pnpm lint
pnpm check
pnpm dev
pnpm generate:previews

新增主题前先看 CONTRIBUTING.md。

npm 发布流程见 docs/PUBLISHING.md。

设计原则

• 默认只生成一张图。
• 文字优先。
• 用字体和版式表达，而不是堆装饰。
• 输入 JSON 要小。
• 不伪造数据。
• 不直接塞长日志、长 transcript。
• 遵守每个主题的字数预算。
• 默认高分辨率导出。

License

MIT。见 LICENSE。