datopian/portaljs

PortalJS – 一个 AI 原生的数据门户框架

它是什么 – PortalJS 是一个开源的、MIT 许可的工具包，让数据团队只需几条命令就能创建功能齐全的开放数据门户。它附带一组 Claude Code “技能”（斜杠命令），充当 AI 助手：它们会采访你、推荐架构、搭建 Next.js 代码库，并自动添加数据集、图表、地图或元数据。生成的门户是普通的、可编辑的 Next.js – 无供应商锁定。

为什么重要 – 构建数据门户通常需要决定存储、目录、搜索、托管，然后连接 UI。PortalJS 将决策（advisor 技能）与代码生成捆绑在一起，让非工程师用自然语言描述需求，并立即获得一个可工作的门户。它还支持现代“湖仓”架构（Git + Cloudflare R2 + Parquet + DuckDB），同时仍允许经典后端如 CKAN。

关键组件

• Agentic 技能 – 一组 Claude Code 斜杠命令（/portaljs-architect、/portaljs-new-portal、/portaljs-add-dataset 等），用于推荐架构、搭建代码、摄取数据、生成图表/地图、输出 DCAT 提要并部署。
• 三界面 UI – 一个首页、一个用于数据集发现的目录（/search）和一个展示页（/@<namespace>/<slug>），显示元数据、预览、下载和可视化。
• DataProvider 契约 – 所有 UI 组件通过单一提供者接口读取数据，使后端可插拔（静态文件、Git-LFS + R2、CKAN、OpenMetadata 等）。
• 存储与计算选项 – 从简单的平面文件到完整的湖仓（R2 上的 Parquet，用 DuckDB 查询）或传统数据仓库/CKAN。
• Cloudflare 优先基础 – 默认部署使用 Cloudflare R2、Workers、D1 和 Pages，但存储保持 S3 兼容。

快速开始

# 一行命令创建带示例数据的门户
npm create portaljs@latest my-portal
cd my-portal
npm run dev   # http://localhost:3000

要使用 AI 助手，请一次性安装 Claude 技能：

curl -fsSL https://raw.githubusercontent.com/datopian/portaljs/main/scripts/install-portaljs-skills.sh | bash

然后在任何 Claude Code 会话中，你可以运行如下命令：

/portaljs-architect  we have 200 CSVs, need DCAT‑AP compliance
/portaljs-new-portal  "City Open Data Portal"
/portaljs-add-dataset  ./data/air-quality.csv

这些技能将生成 Next.js 项目、更新 datasets.json、通过 Git-LFS 将大文件推送到 R2，并创建相应的 UI 页面。

生态系统与可扩展性

• 包 – @portaljs/ckan（CKAN UI 组件）和 @portaljs/ckan-api-client-js 用于 API 访问。
• 示例 – 规范模板位于 examples/portaljs-catalog；一个生产级门户（OpenSpending）基于 PortalJS 构建。
• 社区 – Discord、GitHub Discussions 和问题跟踪器用于支持和贡献。
• 路线图 – 添加更多元数据模式、更多后端、浏览器中的 DuckDB 查询层以及细粒度访问控制。

谁应该使用 – 数据团队、市政开放数据项目、非政府组织，或任何需要快速发布数据集而不想依赖重型数据仓库，并希望获得 AI 辅助架构指导的人。

许可证 – MIT（完整源代码可在 GitHub 上获取）。