企业官网建设流程全解析

Open Brain扩展开发指南：如何快速创建、部署并提交你自己的Extension

【免费下载链接】OB1Open Brain — The infrastructure layer for your thinking. One database, one AI gateway, one chat channel — any AI plugs in. No middleware, no SaaS.项目地址: https://gitcode.com/gh_mirrors/ob/OB1

🧠Open Brain（OB1）是一个去中心化的 AI 记忆基础设施：一个数据库 + 一个 AI 网关 + 一个聊天渠道，任何 AI 都能即插即用，无需中间件、无需 SaaS。本指南面向新手，带你走完Open Brain 扩展开发的完整流程：从零创建自己的 Extension、部署到云端 MCP 服务器，再到向社区提交开源贡献——只需 5 个步骤。

什么是 Open Brain Extension？

Extension（扩展）是 Open Brain 生态中「渐进式学习路径」的载体：每一个 Extension 都是一个完整的小应用，包含数据库表、MCP 服务器代码和分步教程，用来给 AI 增加一项新的生活能力。

官方已经内置了 6 个按难度递进的 Extension（详见 extensions/README.md），你可以把它理解为「学习范本」：

💡 关键特性：扩展是可叠加的。你的 CRM 能感知你记录的想法，你的餐食计划会检查本周谁在家——这就是扩展生态的复利效应。

动手前：了解一个 Extension 的「5 件套」

每个 Extension 就是一个文件夹（如extensions/your-extension/），包含固定 5 个文件。官方为 AI 助手准备了一份机器可读的生成规范 AGENT_SPEC.md，你也可以直接参照它手工编写：

📁 想要起点？直接从官方模板复制一份 extensions/_template/，里面还包含详细的格式规范注释（步骤徽章、验证检查点、SQL 折叠块等）。

步骤 1：搭建好 Open Brain 基础环境

开发 Extension 前，你需要一个能正常运行的 Open Brain 实例。跟着官方入门指南 docs/01-getting-started.md 完成搭建，确保你手上有：

• ✅ 已安装并链接好项目的Supabase CLI
• ✅ 一张「凭证跟踪表」（Project URL、Secret key、Project ref）
• ✅ 一个可对话的 AI 客户端（Claude Desktop、ChatGPT、Claude Code 均可）

步骤 2：创建你的 Extension 五件套

以"宠物养护记录"扩展为例，你需要依次准备 5 个文件：

1️⃣schema.sql— 设计数据表

在 Supabase SQL Editor 中运行建表语句。每张表都要有id、user_id，并启用RLS（行级安全策略），保证每个用户只能看到自己的数据。参考 household-knowledge 的 schema 就能看到标准的写法模式。

⚠️必做：新增表后必须手动GRANT权限给service_role，否则 MCP 服务器会报 "permission denied"。

2️⃣index.ts— 编写 MCP 工具

这是 AI 真正调用的"工具"。每个工具 = 名字 + 描述 + 参数定义 + 数据库操作，例如官方的add_household_item工具定义（见 index.ts）。新手只需模仿现有 Extension 的写法即可。

🔔安全规范：只读工具必须标注readOnlyHint: true，写入工具要标注readOnlyHint: false等注解——自动化审查会检查这一点。

3️⃣metadata.json— 填写元数据

必填字段包括name、description、category、author、version、requires.open_brain: true、tags、difficulty、estimated_time。完整示例见 CONTRIBUTING.md。

4️⃣deno.json— 依赖映射

绝大多数扩展直接复用官方模板里的那份内容即可，只有引入额外依赖时才需要修改。

5️⃣README.md— 编写安装指南

必须包含：功能说明、前置条件、分步指令、预期结果、故障排查。Extension 还要求额外包含"Why This Matters"（从一个真实生活痛点讲起）、学习路径表格和跨扩展集成说明。

步骤 3：一键部署为云端 MCP 服务器

Open Brain 的扩展不跑在本地，而是统一部署为 Supabase Edge Function——部署一次，任何 AI 客户端都能连接（这就是 Remote MCP 模式）。跟着 primitives/deploy-edge-function/ 指南，核心就 4 条命令：

1. 建函数目录：supabase functions new your-extension-mcp
2. 放入代码：把index.ts和deno.json放进函数目录
3. 设置密钥：生成一个 64 位访问密钥，supabase secrets set MCP_ACCESS_KEY=...
4. 部署上线：supabase functions deploy your-extension-mcp --no-verify-jwt

✅完成标志：supabase functions list中你的函数显示为ACTIVE，你的 MCP 连接 URL 形如https://你的项目ref.supabase.co/functions/v1/your-extension-mcp?key=你的密钥。

步骤 4：连接 AI 客户端并测试

按 primitives/remote-mcp/ 指南，把你的连接 URL 粘贴到任意 AI 客户端：

验证测试：在 AI 对话里用自然语言试 2~3 个你定义的工具，确认数据真的写进了数据库。遇到 401 错误？先核对?key=后面的密钥是否与 Supabase 中的一致。

步骤 5：提交你的开源贡献 🚀

Extensions 属于Curated（精选）类别——提交前建议先与维护者讨论，并确认你的扩展已在自己的 Open Brain 实例上跑通。提交规范见 CONTRIBUTING.md：

• PR 标题格式：[extensions] 你的扩展短描述
• PR 描述必写：功能说明、依赖的服务/工具、以及"已在自己的实例上测试通过"的确认
• 审查流程：自动化检查（文件结构、元数据合法性、无密钥泄露、SQL 安全等 16 条规则）→ 通过后人工审查，通常 2~5 个工作日
• 常见被拒原因：包含 API 密钥或秘密、依赖无免费替代的付费服务、文档不完整、修改了核心thoughts表结构

🎉 你的名字将出现在metadata.json的 author 字段和 CONTRIBUTORS.md 中——不写代码也能贡献：提一个想法 issue，社区导师会帮你实现，你仍是第一作者。

常见问题速查 🛠️

更多排障见 primitives/troubleshooting/。

写在最后

从一张表到 AI 随手可用，一个 Open Brain Extension 的开发周期远比你想象的短。建议路径：

1. 通读 extensions/household-knowledge/（最简范本）
2. 复制模板，做出你的第一个扩展
3. 部署、连接、测试，跑通闭环
4. 开 issue 讨论 → 提交 PR → 进入贡献者阶梯

另外提醒：每加一个扩展，AI 上下文里的工具数就会增加。工具多了之后，记得参考 MCP 工具审计指南 定期"给工具做体检"，让 AI 始终精准选对工具。祝你构建顺利！🧠

【免费下载链接】OB1Open Brain — The infrastructure layer for your thinking. One database, one AI gateway, one chat channel — any AI plugs in. No middleware, no SaaS.项目地址: https://gitcode.com/gh_mirrors/ob/OB1