notion-arena

Notion Arena

Notion 的组件注册表。
将 shadcn/ui 的模式应用于 Notion 仪表板：浏览、配置、复制、拥有，并通过代码安装。

---

🎯 什么是 Notion Arena？

Notion Arena 是一个面向 Notion 的机器可读组件注册表，包含 203 个预构建组件，可添加到任意 Notion 页面中：

	192 个小组件（嵌入 + HTML 块）	11 个原生配方（Notion API）
内容	可独立运行于 Notion 内的 HTML 文件	通过 API 安装的数据库架构、视图、公式和自动化
交付方式	<iframe> 嵌入或上传 HTML 文件	使用你的令牌调用 POST /api/install
网络	需要（嵌入）／不需要（HTML 块）	运行时不需要
数据	仅保存在浏览器本地	保存在你的 Notion 工作区中
团队同步	❌ 否	✅ 是
更新	自动（嵌入）／手动（HTML）	重新运行安装
最低套餐	免费	免费／Plus／Business

Notion 是 Notion Labs Inc. 的商标。 本项目为独立项目，与 Notion 无关联，也未获 Notion 背书。

---

🎨 热门小组件展示

| 小组件 | 类别 | 描述 | |--------|----------|-------------| | **番茄钟** | 时间 | 工作／休息循环，带进度环、时段计数器和提示音 | | **KPI 条** | 仪表板 | 4 个指标卡片，带迷你趋势图、变化值和目标环 | | **习惯网格** | 追踪器 | GitHub 风格热力图、连续记录和 5 级强度 | | **翻页时钟** | 仪表板 | 翻页时钟，支持时区、12／24 小时制和 Notion 字体 | | **会议笔记系统** | 文档 | 包含议程、笔记、决策和行动事项的模板 | | **目标环** | 仪表板 | 单指标主视觉，带里程碑和进度环 |

📦 全部 192 个小组件（点击展开）

| 类别 | 数量 | 示例 | |----------|-------|----------| | **时间** | 12 | 番茄钟、呼吸练习、秒表、倒计时、月历、日期计算器、翻页时钟、世界时钟、正计时、间隔计时器、白噪声、日出/日落、睡眠时长、家庭日历、学习时段记录、每日规划、日常清单、锻炼追踪器 | | **仪表板** | 9 | KPI 条、目标环、年度进度、月相、翻页时钟、世界时钟、每周状态报告、日出/日落、正计时、倒计时、月历、日期计算器、秒表、呼吸计时器 | | **追踪器** | 26 | 习惯网格、饮水追踪器、情绪追踪器、日常清单、锻炼追踪器、睡眠时长、植物养护日志、宠物护理清单、志愿服务时长日志、媒体观看清单、阅读进度、储蓄目标、净资产概览、支出追踪器、投资组合追踪器、债务还款追踪器、订阅追踪器、计费工时追踪器、出勤登记表、收藏品目录、装备数据库、家庭库存日志、汽车保养与行程日志、保修与维修日志、游戏收藏目录、愿望清单与收藏家日志、医疗用品库存、家庭联系人目录 | | **规划** | 37 | 迷你看板、艾森豪威尔矩阵、甘特时间线、每周规划表、旅行行程、膳食规划、杂货清单、行李清单、家务清单、房屋维护日志、产品路线图、冲刺回顾、用户故事地图、OKR 每周签到、每日规划、婚礼座位规划、活动流程表、里程碑追踪器、事件日志、QA 测试运行日志、活动宾客名单、旅行行程规划器 | | **业务** | 53 | ROI 计算器、预算规划器、库存追踪器、本地受理表、工单队列、资产借出登记、订阅追踪器、账单分摊器、货币转换器、报价生成器、CRM 销售管道、冲刺追踪器、发票生成器、客户入驻追踪器、销售跟进队列、营销活动规划器、面试评分卡、定价层级计算器、客户季度业务回顾准备、自由职业者提案追踪器、筹款联络追踪器、供应商登记表、访问权限审核日志、发票状态追踪器、休假与请假日志、续约看板、升级处理追踪器、采购申请追踪器、设备库存日志、审批申请日志、帮助台受理日志、编辑日历、现场日志、餐厅预订日志、捐赠者关系日志、探索性电话管道、房产列表目录、房产看房安排、租户与租约日志、制造工单追踪器、货运与物流追踪器、婚礼供应商目录 | | **文档** | 50 | 引文生成器、阅读追踪器、间隔重复、抽认卡、词汇训练器、书签库、阅读清单、作业追踪器、考试规划器、研究日志、协议清单、灵感收集箱、手稿进度、章节大纲、角色设定集、投稿追踪器、播客单集规划器、嘉宾准备表、单集制作清单、课程计划生成器、研究会议规划器、变更日志生成器、SEO 内容规划器、内容再利用追踪器、可用性发现日志、奖学金追踪器、播客节目备注日志、听众反馈日志、食谱与膳食库、班级主页、家长沟通日志、辅导课程日志、研究问题日志、实验室设备与样本日志、学生课程仪表板、论文里程碑追踪器、影响与成果日志、董事会会议记录、治疗师课程管理、医疗人员培训日志、旅行日志、评价与评分日志、旅行日志、评价与评分日志 | | **视觉内容** | 5 | 组织架构图、白板、引言卡片、每日引言卡片、电影镜头清单、分镜镜头日志 | | **自动化** | 1 | 自动化入门包 |

---

⚙️ 原生方案（11 个）

方案	等级	创建内容	套餐
CRM Pipeline	Pro	3 个数据库、6 个公式、5 个视图、2 个模板、3 个自动化	Plus
Sprint Tracker	Pro	2 个数据库、4 个公式、4 个视图、1 个模板	Plus
OKR System	免费	2 个数据库、5 个公式、3 个视图、1 个模板	Plus
Meeting Notes OS	免费	2 个数据库、1 个模板、2 个按钮、4 个视图、2 个自动化	免费
Content Calendar	免费	2 个数据库、3 个公式、5 个视图、1 个循环模板	Plus
Invoice Generator	Pro	3 个数据库、6 个公式、1 个模板、1 个按钮、3 个视图	Plus
PARA Life OS	Pro	5 个数据库、7 个关联、6 个视图、3 个模板、1 个仪表板	Plus
Habit OS (native)	Pro	2 个数据库、5 个公式、4 个视图、1 个按钮、1 个循环模板	Plus
Client Portal	Pro	3 个数据库、4 个视图、1 个同步块、1 个页面、2 个自动化	Business
Job Tracker	免费	2 个数据库、4 个公式、4 个视图、3 个模板	免费
Automation Starter	免费	2 个数据库、12 个自动化、6 个按钮、3 个循环模板、4 个公式	Plus

---

🤖 面向 AI Agent — MCP + Skill

将 Notion Arena 直接接入你的 AI Agent——Claude Code、Cursor、Windsurf、Claude Desktop。

MCP 服务

为你的 Agent 提供用于列出、搜索、配置和规划安装全部 203 个组件的工具：

# Claude Code (project scope)
claude mcp add --scope project notion-arena -- npx -y notion-arena-mcp

# Or pinned version
npx -y [email protected]

# Cursor — .cursor/mcp.json
# Claude Desktop — claude_desktop_config.json
# See docs/AGENT_SETUP.md for all clients

Skill

帮助你的 Agent 了解 Notion Arena 工作流、交付渠道和小组件契约：

# Via skills.sh (Vercel) — cross-agent
npx skills add SynergyFlowLabs/notion-arena --skill notion-arena

# Via Claude Code plugin marketplace
/plugin marketplace add SynergyFlowLabs/notion-arena
/plugin install notion-arena@notion-arena-marketplace

# Manual
cp -r skills/notion-arena .claude/skills/notion-arena

两者安装完成后，只需提出需求：

“帮我找一个适用于 Notion 的番茄钟” “在我的 Notion 中添加一个 CRM Pipeline” “我需要一个可离线使用的习惯追踪器”

你的 Agent 将自动使用 search_components、get_component、build_embed_url、plan_install。

MCP 工具：list_components、search_components、get_component、get_widget_schema、build_embed_url、plan_install、get_registry_item、get_install_guide、get_categories、get_site_info

Skill：skills/notion-arena/SKILL.md + .claude/skills/notion-arena/SKILL.md + .claude-plugin/plugin.json + .claude-plugin/marketplace.json

有关 MCP + Skill 设置，请参阅 docs/AGENT_SETUP.md；有关免费部署（Vercel），以及将 MCP 发布到 npm 和注册表、将 Skill 发布到 skills.sh 和插件市场，请参阅 docs/DEPLOY_AND_PUBLISH.md。

---

🏗️ 三种交付渠道——可视化

	嵌入 URL	HTML 块	原生 Recipe
内容	我们托管小组件，Notion 通过 iframe 嵌入	你将文件上传到 Notion 的存储空间	我们调用 Notion API
安装	/embed → 粘贴	/html → 上传，或调用 3 次 API	POST /api/install
渲染时需要网络	需要	不需要	不需要
读取你的 Notion 数据	否	否	数据本身就是它
与团队共享状态	否	否	是
获取我们的更新	自动	否。固定不变	不适用
最低套餐	免费	免费	免费

一个 HTML 文件同时服务于两种小组件渠道，因此它们不会出现差异。托管路径的配置来自查询字符串，下载路径的配置来自内置的 <script id="bk-config">，因为沙盒块没有 URL。

---

📋 小组件规范——4 条规则

public/widgets/ 中的每个小组件都遵循相同的 4 条规则。完整指南和检查清单请参阅 /docs/authoring。

规则	说明
1. 零外部请求	不使用 CDN、网络字体、fetch() 或 @import。沙盒没有网络——远程资源会显示为空白块。
2. 两种配置来源	内置的 bk-config 脚本标签（优先级 1），然后是 URLSearchParams（优先级 2）。只保留已声明的参数；buildConfig() 会丢弃未知键。
3. 每个小组件都支持主题和强调色	theme=auto|light|dark 会在 <html> 上设置 data-theme，并在设置为 auto 时遵循 prefers-color-scheme；accent 会设置 --accent，并通过 color-mix(in oklab, …) 派生色调。
4. 命名空间状态	保存浏览器状态的小组件使用 notion-arena.<slug>.v1，并在 try/catch 中封装存储访问。状态仅保存在单个浏览器中，不会同步——共享追踪器应使用原生 Recipe。

此外：设置 body { overflow: hidden }，由 .wrap 管理自身滚动（只显示一个滚动条，而非两个）；提供 prefers-reduced-motion 选项；剪贴板导出时始终也会通过 console.log 输出载荷，作为备用方案。

---

🏃 在本地运行

# Install dependencies
npm install

# Restore 13 design/dev skills into .agents/skills/
npx skills experimental_install -y

# Start dev server
npm run dev          # http://localhost:3000

要求：Node 22+、Next.js 16（Turbopack）、React 19、Tailwind v4、TypeScript。

# Type-check
npx tsc --noEmit

# Widget contract checks (offline HTML validation)
npm run check:widgets

# Contrast audit
npm run audit:contrast

# Production build
npm run build

# MCP server
npm run generate:mcp-catalog  # 143 components → mcp/src/data/catalog.json
npm run build:mcp             # build notion-arena-mcp
npm run dev:mcp               # run MCP server with tsx (stdio)

在生产环境中设置 NEXT_PUBLIC_SITE_URL 为 https://notionarena.vercel.app，以便注册表清单为正确的主机生成绝对 URL。如果未设置，URL 将根据请求转发的主机生成；若无法获取，则回退到 https://notionarena.vercel.app（本地开发时为 http://localhost:3000）。

---

📁 项目结构

public/widgets/*.html      the products: 192 self-contained HTML files
lib/catalog.ts             source of truth for all 203 components
lib/types.ts               component/param types + the 8 categories
lib/widget.ts              config coercion, injection, HTML rendering  (server)
lib/widget-url.ts          URL builders                                (browser-safe)
lib/notion/schema.ts       Notion API payload builders
lib/notion/installer.ts    executes plans against @notionhq/client
lib/recipes/               11 recipe declarations + planInstall()
lib/registry.ts            shadcn-compatible manifest generation
components/                site UI, catalog browser, configurator, docs prose
app/embed/[slug]/          framed, configured widget HTML
app/api/widget/[slug]/     the same HTML as a download
app/r/[name]/              registry: index.json, schema.json, {name}.json
app/api/install/           plan | embed | html-block | api
docs/RESEARCH.md           the research behind all of it
skills/notion-arena/       AI agent skill (workflow, channels, contract)
mcp/                       MCP server (tools for agents)

---

📦 注册表（兼容 shadcn）

GET /r/index.json          the whole catalog
GET /r/{name}.json         one item, HTML or recipe JSON inline
GET /r/schema.json         JSON Schema of every widget's parameters

// mcp config / components.json
{ "registries": { "@notion-arena": "https://notionarena.vercel.app/r/{name}.json" } }

# see exactly what an install will do: no credentials, touches nothing
curl -X POST localhost:3000/api/install \
  -H 'content-type: application/json' \
  -d '{"component":"crm-pipeline","mode":"plan"}'

# then run it
curl -X POST localhost:3000/api/install \
  -H 'content-type: application/json' \
  -d '{"component":"crm-pipeline","mode":"api",
       "token":"'"$NOTION_TOKEN"'","parentPageId":"'"$PAGE_ID"'"}'

mode: "plan" 无需令牌是有意为之：在授权对工作区进行任何写入之前，先检查请求序列。

---

⚠️ 两件值得了解的事

小组件无法读取或写入你的 Notion 数据。 Notion 的 HTML 块沙盒无法访问网络，也无法与其父页面通信。小组件可以在此浏览器中保留用户输入的个人状态，但该状态不是 Notion 数据，也不会共享。如果工作流需要工作区记录、协作、权限或审计跟踪，请使用原生数据库或配方。

关联属性需要分两步安装。 由于 Notion 将数据库与数据源拆分，relation 属性需要指向一个 data_source_id，而该 ID 只有在目标数据库创建并读回后才会存在。因此，planInstall() 会依次执行：创建包含基础属性的数据库 → 读回每个数据源 ID → 补入关联属性 → 补入汇总属性 → 补入公式 → 视图 → 初始行 → 页面 → 分批添加每批 100 个的块内容。

配方也会声明自己无法实现的功能。4 个真实的 API 缺口（没有 button 块类型、没有自动化端点、没有定期模板端点、无法复制同步块）会作为 manual[] 步骤列出，并各自注明限制。理由是“手动操作更简单”的手动步骤会被拒绝。

---

🤝 参与贡献

欢迎贡献！无论是新小组件、原生配方、错误修复、文档还是想法，都可以通过以下方式参与贡献。

贡献者快速入门

1. 提交 Issue — 先讨论你的想法。检查是否有重复提案，并获取维护者的反馈。
2. Fork 并克隆 — 创建你的分支：git checkout -b feat/my-widget
3. 开发 — 遵循小组件约定（见下方检查清单）
4. 测试 — 在本地运行所有检查
5. 提交 Pull Request — 标题清晰，关联 Issue，附上截图/GIF，并更新 CHANGELOG
6. 审核 — 维护者审核、CI 检查、小组件约定审计
7. 合并 — 自动部署到 Vercel，重新生成 MCP 目录，即刻可用

小组件编写检查清单

每个小组件都必须通过所有检查后才能合并 — 详见 scripts/check-widgets.mjs。

添加新小组件

1. 创建 public/widgets/my-widget.html（单个 HTML 文件，内容自包含）
2. 在 lib/catalog.ts 中添加条目，并包含所有必需字段：

   {
     slug: "my-widget",
     name: "My Widget",
     emoji: "🎯",
     tagline: "One-line hook",
     description: "Full paragraph explaining what it does and why.",
     category: "time", // time | dashboards | trackers | planning | business | docs | visuals | automations
     kind: "widget",
     tier: "free", // free | pro
     tags: ["tag1", "tag2"],
     color: "blue", // red | orange | yellow | green | blue | purple | pink | brown | gray
     params: [
       { key: "param1", label: "Label", type: "number", default: 10, min: 1, max: 100 },
       { key: "theme", label: "Theme", type: "select", default: "auto", options: [...] },
       { key: "accent", label: "Accent", type: "color", default: "#2383e2" },
     ],
     features: ["Feature 1", "Feature 2"],
     useCases: ["Use case 1", "Use case 2"],
     capabilities: {
       interactive: true,
       offlineSafe: true,
       persistsLocally: false,
       writesToNotion: false,
       needsNetwork: false,
     },
   }
   

3. 运行 npm run check:widgets 和 npm run typecheck
4. 在 Notion 中测试（嵌入 + HTML 块）
5. 提交 PR

添加原生配方

1. 在 lib/recipes/my-recipe.ts 中创建配方，并导出 planInstall() 和 schema
2. 在 lib/catalog.ts 中添加条目，并设置 kind: "native" 和 recipe: "my-recipe"
3. 运行 npm run generate:mcp-catalog 和 npm run build:mcp
4. 先使用 mode: "plan"，再使用 mode: "api" 进行测试
5. 提交 PR

代码风格

• TypeScript 严格模式 — 不使用 any，显式声明类型
• Tailwind v4 — 优先使用工具类，除非必要，否则不写自定义 CSS
• React 19 — 默认使用服务端组件，仅在需要时使用 'use client'
• Conventional Commits — feat:、fix:、docs:、chore:、refactor:

---

📜 诚信政策

• 不捏造安装量、星标数或客户 Logo
• 徽章仅表示定性信息（new、popular、staff-pick），并根据目录生成
• 仅在注明来源的地方展示市场数据
• 功能声明以目录中的布尔值形式提供（interactive、offlineSafe、persistsLocally、writesToNotion、needsNetwork），并在注册表中公开，方便 Agent 按这些值筛选，而无需阅读文字说明

---

📄 许可证

MIT License — 详见 LICENSE。

下载的组件归你所有：你可以修改、托管，也可以将其打包到你出售的模板中。免费组件无需注明出处。详见 /legal/terms。

---

🔗 Links

• Live Site: https://notionarena.vercel.app
• MCP Package: https://www.npmjs.com/package/notion-arena-mcp
• MCP Registry: https://registry.modelcontextprotocol.io
• Documentation: https://notionarena.vercel.app/docs
• Research: docs/RESEARCH.md
• Agent Setup: docs/AGENT_SETUP.md
• Deploy & Publish: docs/DEPLOY_AND_PUBLISH.md
• Contributing: CONTRIBUTING.md
• Changelog: CHANGELOG.md

---

Made with ❤️ by SynergyFlow Labs and contributors