AIRP Renderer

VS Code / Cursor extension that reads and exports AIRP documents (*.airp.json).

AIRP screen capture

Make AI-written reports easier to read—and easier to change.

Ask AI for Markdown and you often get flat, meandering text. Ask for HTML and it can look fine, but it’s long, token-heavy, and painful to edit later. AIRP’s approach: have the AI write a *.airp.json source first, then open it with the AIRP Renderer extension as polished HTML. When you need to share, export HTML or Markdown.

The source is organized like Notion Blocks—46 of them so far (hero metrics, comparison, decision, timeline, Mermaid, architecture overview, and more). Each has its own layout, so plans, reviews, retros, and audits stay clear instead of turning into a wall of text.

How a report runs

Writing and reading stay separate. The *.airp.json in the middle is shaped by JSON Schema—generation and validation both treat it as the source of truth:

Who	What it does
`/airp` Skill	Have AI create or update the source, and validate it
VS Code extension	Read it in the editor; export HTML / Markdown

What you actually get:

Missing fields or sections fail validation—fewer half-finished deliverables.
The source fits Git and diffs; HTML / Markdown are just what humans read.
Clear Block boundaries are steadier for the model, and usually cheaper in tokens than a hand-written full HTML page.

Quick start

1. Install the VS Code extension

Install AIRP Renderer from the Marketplace (extension ID: airp.airp-renderer-vscode).

Open any *.airp.json to read it, or export HTML / Markdown. Needs a VS Code–compatible editor (e.g. Cursor).

2. Install the `/airp` Skill

If you’re only opening sources someone else already wrote, the extension is enough. Install the Skill when you want AI to write new reports:

npx skills add maosong-ai/airp

In chat, type /airp <topic>. The Skill generates and validates a source file (default folder: .docs/airp/). Open it with the extension to read. Optional flags: --locale en-US, --out <dir>.

Languages

Supported document languages: English (en-US), 简体中文 (zh-CN), 日本語 (ja-JP), 한국어 (ko-KR), Deutsch (de-DE), Français (fr-FR), Русский (ru-RU), Español (es-ES), Português Brasil (pt-BR), Italiano (it-IT). Pass /airp --locale … when you write a report.

Blocks

You don’t have to memorize these Blocks. The /airp Skill picks them from the content; use the table when you want to customize.

Layout and prose	Comparison and lists	Engineering and decisions
Hero(`hero`) The few metrics that matter most, up front	Table(`table`) Rows and columns lined up for comparison	Code(`code`) A short snippet
Lead(`lead`) One sentence on what this part is about	Comparison(`comparison`) Before and after, side by side	Code diff(`codeDiff`) Which lines changed
Section(`section`) A major topic you can jump to	Collection(`collection`) A set of items as cards	File tree(`fileTree`) A directory layout
Heading(`heading`) Marks a subsection level	Key-value list(`keyValueList`) Names paired with values	File changes(`fileChangeList`) Files added, modified, or deleted
Paragraph(`paragraph`) A stretch of explanation	Definition list(`definitionList`) Terms paired with meanings	Mermaid(`mermaid`) Flow, sequence, state, and similar diagrams
Group(`group`) Bundles neighboring content	Glossary(`glossary`) Terms used in the report, in one place	Architecture overview(`architectureOverview`) A system diagram plus module cards
Pull quote(`pullQuote`) Lifts one key line out on its own	Status board(`statusBoard`) Pass, fail, or partial at a glance	API inventory(`apiInventory`) Endpoints and what they’re for
Quote(`blockquote`) Quotes a passage or someone else	Checklist(`checklist`) Items you tick off	Test results(`testResult`) Passed and failed counts
Callout(`callout`) Flags a note, warning, or conclusion	Timeline(`timeline`) What happened, in time order	Requirement trace(`requirementTrace`) Requirements mapped to status and evidence
Bullet list(`bulletList`) Points side by side	Roadmap(`roadmap`) Goals and progress by phase	Decision(`decision`) What was chosen, and why
Numbered list(`numberedList`) Steps or items in order	Flow steps(`flowSteps`) A process broken into steps	Risk(`risk`) A risk and where it stands
Divider(`divider`) A line between what’s above and below	Link list(`linkList`) Related links	Assumption(`assumption`) A premise the report depends on
Spacer(`spacer`) Space between blocks	Citation(`citation`) Where a claim comes from	Constraint(`constraint`) A limit you can’t break
Image(`image`) A picture with a caption	Tabs(`tabs`) Several views in one place	Open question(`openQuestion`) Something still undecided
Embed(`embed`) An external page or resource	Collapsible(`collapsible`) Long, secondary content folded away	Agent note(`agentNote`) A note for the model; hidden from readers by default
Appendix(`appendix`) Extra material at the end

What’s next

Available today: Skill generates / validates sources; the extension reads and exports HTML / Markdown. Planned next:

Direction	Notes
Visual editing	Edit content in the extension—don’t need the Skill for every change
More export formats	Add PDF (print, archive)
Multi-page / multi-sheet	Split long reports by section or sheet instead of one endless page

Changelog

让 AI 写出来的报告更好读，也好改。

AI 直接出 Markdown，往往又平又散；直接出 HTML，版式好看，但又长又费 token，后面也不好改。AIRP 的做法是：先让 AI 写出一份 *.airp.json 源文件，再用 AIRP Renderer 扩展打开成排版好的 HTML；需要对外发时，再导出 HTML 或 Markdown。

源文件按 Notion 那套 积木块（Block） 组织，目前有 46 种——指标首屏、对比、决策、时间线、Mermaid、架构总览等。每种有自己的版式，方案、评审、复盘、审计这类报告会清楚很多，不会糊成一坨字。

报告是怎么跑起来的

写和读是分开的。中间那份 *.airp.json 由 JSON Schema 约束，生成和校验都以它为准：

谁	干什么
`/airp` Skill	让 AI 生成或改源文件，并做校验
VS Code 扩展	在编辑器里阅读；导出 HTML / Markdown

这样做的实际好处：

缺字段、缺章节时校验会失败，少交半成品。
源文件适合进 Git、做 diff；HTML / Markdown 只当给人看的成品。
积木块边界清楚，对模型更稳，通常也比整页手写 HTML 更省 token。

快速开始

1. 安装 VS Code 扩展

到 Marketplace 安装 AIRP Renderer（扩展 ID：airp.airp-renderer-vscode）。

打开任意 *.airp.json 就能读，也可以导出 HTML / Markdown。需要 VS Code 兼容编辑器（如：Cursor）。

2. 安装 `/airp` Skill

只读别人已经写好的源文件，装扩展就够了。要让 AI 帮你写新报告时，再装 Skill：

npx skills add maosong-ai/airp

对话里输入 /airp <主题>，Skill 会生成并校验源文件（默认目录：.docs/airp/），再用扩展打开即可阅读。可选参数：--locale zh-CN、--out <目录>。

多语言

支持这些文档语言：English（en-US）、简体中文（zh-CN）、日本語（ja-JP）、한국어（ko-KR）、Deutsch（de-DE）、Français（fr-FR）、Русский（ru-RU）、Español（es-ES）、Português Brasil（pt-BR）、Italiano（it-IT）。写报告时用 /airp --locale … 指定。

积木块

不用记这些积木块，/airp Skill 会按内容自己选；想定制时再对照下面的表。

版式与正文	对照与清单	工程与决策
指标首屏(`hero`) 开篇放最关键的几项指标	表格(`table`) 多行多列对齐对照	代码(`code`) 放一段短代码
导语(`lead`) 用一句话点明本节要讲什么	对比(`comparison`) 左右两栏看改前改后	代码差异(`codeDiff`) 标出改了哪些行
章节(`section`) 按主题分成可跳转的大段	卡片集(`collection`) 用卡片铺开一组条目	文件树(`fileTree`) 展示目录结构
标题(`heading`) 标出小节层级	键值列表(`keyValueList`) 成对列出名称和取值	文件变更(`fileChangeList`) 列出新增、修改、删除的文件
段落(`paragraph`) 写一段说明文字	定义列表(`definitionList`) 术语和释义成对列出	Mermaid(`mermaid`) 画流程、时序、状态等图
分组(`group`) 把相邻内容收成一组	术语表(`glossary`) 集中解释文中用词	架构总览(`architectureOverview`) 总图加模块卡片看系统
醒目引文(`pullQuote`) 把一句关键结论单独拎出来	状态板(`statusBoard`) 一眼看过、不过或部分通过	接口清单(`apiInventory`) 列出接口及其用途
引用(`blockquote`) 引用一段原文或他人说法	检查清单(`checklist`) 勾选事项是否完成	测试结果(`testResult`) 汇总用例通过与失败数
提示(`callout`) 标出注意、警告或结论	时间线(`timeline`) 按时间排出发生过的事	需求追溯(`requirementTrace`) 把需求对到状态和证据
无序列表(`bulletList`) 并列列出若干要点	路线图(`roadmap`) 按阶段排出目标和进度	决策(`decision`) 记下选了什么、为什么
有序列表(`numberedList`) 按顺序写步骤或条目	步骤流(`flowSteps`) 把流程拆成先后步骤	风险(`risk`) 写出风险和处理现状
分隔线(`divider`) 在上下内容之间划开	链接列表(`linkList`) 列出相关链接	假设(`assumption`) 写明当前依赖的前提
留白(`spacer`) 在块与块之间留出空隙	出处(`citation`) 标明引用的来源	约束(`constraint`) 标出不能突破的限制
图片(`image`) 插入一张图并配说明	分页签(`tabs`) 同一处切换多种看法	待决问题(`openQuestion`) 记下还没定的问题
外链嵌入(`embed`) 嵌一段外部页面或资源	折叠(`collapsible`) 把次要的长内容收起来	代理备注(`agentNote`) 留给模型看的备注，默认不展示给人
附录(`appendix`) 把补充材料放到文末

接下来打算做什么

现在已经能用：Skill 生成 / 校验源文件，扩展阅读并导出 HTML / Markdown。后面计划：

方向	说明
可视化编辑	在扩展里直接改内容，不必事事找 Skill
更多导出格式	增加 PDF（打印、归档）
多页 / 多 Sheet	长报告按章节或工作表拆开，别堆成一页

变更记录

License

MIT

AIRP Renderer

airp

AIRP Renderer

How a report runs

Quick start

1. Install the VS Code extension

2. Install the /airp Skill

Languages

Blocks

What’s next

Changelog

报告是怎么跑起来的

快速开始

1. 安装 VS Code 扩展

2. 安装 /airp Skill

多语言

积木块

接下来打算做什么

变更记录

License

2. Install the `/airp` Skill

2. 安装 `/airp` Skill