Page Data API 使用说明

面向 MindSpace 页面 owner、Agent 与 HTML 页面开发者。实现细节见 page-data-api-public-access-plan-20260708.md。

快速路径

Agent 加载 page-data-collect 技能（或按该技能流程执行）。
Agent 用 private_data_execute 建表，用 private_data_register_dataset 注册 dataset。
发布页面 时在发布面板勾选「启用页面数据」，选择 dataset 与公开能力；或发布后让 Agent 调用 private_data_set_page_policy。
HTML 页面 引入 /assets/page-data-client.js，用 MindSpacePageData.createClient({ apiBase: '/api' }) 读写数据（pageId 可由平台在访问时自动注入）。
运维在 MindSpace 页面详情「页面数据」面板查看日志、导出、撤销令牌、恢复软删除、关闭 dataset。

访问模式与默认能力

发布访问模式	Page Data 模式	默认公开能力
完全公开	`public`	仅 insert
口令访问	`password`	read + insert
登录访问	`login_required`	read + insert + update

可在发布面板或策略中逐项覆盖。

Owner API（需登录，仅后台管理界面）

/api/page-data/* 已移除，不可被公开 HTML 调用；旧页面请求会收到 410 legacy_page_data_api_removed。

GET    /api/admin/page-data                          # 列出已注册 dataset
GET    /api/admin/page-data/:dataset
POST   /api/admin/page-data/:dataset/rows
PATCH  /api/admin/page-data/:dataset/rows/:id
DELETE /api/admin/page-data/:dataset/rows/:id   # soft delete
POST   /api/admin/page-data/:dataset/rows/:id/restore

GET    /api/admin/page-data/policies
GET    /api/admin/page-data/policies/:pageId
PUT    /api/admin/page-data/policies/:pageId
POST   /api/admin/page-data/policies/:pageId/apply-publish
GET    /api/admin/page-data/policies/:pageId/ops
GET    /api/admin/page-data/policies/:pageId/logs
POST   /api/admin/page-data/policies/:pageId/tokens/revoke
POST   /api/admin/page-data/policies/:pageId/password/reset
POST   /api/admin/page-data/policies/:pageId/datasets/:dataset/close

公开 API（无需平台登录）

POST   /api/public/pages/:pageId/data-auth              # 口令页换 token
GET    /api/public/pages/:pageId/data/:dataset
POST   /api/public/pages/:pageId/data/:dataset/rows
PATCH  /api/public/pages/:pageId/data/:dataset/rows/:id
DELETE /api/public/pages/:pageId/data/:dataset/rows/:id
GET    /api/public/pages/:pageId/data/:dataset/schema
GET    /api/public/pages/:pageId/data/:dataset/stats

公开请求可带 x-page-data-token（口令/登录会话）。完全公开模式下：默认仅 insert；若策略显式开启 read，匿名访问者可读白名单字段并查看 stats。

HTML 页面嵌入

<script src="/assets/page-data-client.js"></script>
<script>
  // pageId 可省略：已绑定/已发布的页面访问时会注入 window.__MINDSPACE_PAGE_DATA__
  const client = MindSpacePageData.createClient({
    apiBase: '/api',
  });

  // 口令页先认证
  // await client.authenticate('页面口令');

  // 列表
  const { rows } = await client.listRows('signups', { limit: 20 });

  // 提交表单
  await client.insertRow('signups', { name: '张三', phone: '13800000000' });
</script>

公开表单 + Cloudflare Turnstile

服务端配置环境变量 PAGE_DATA_TURNSTILE_SECRET 后，完全公开模式的 insert 必须带验证码。

<script src="/assets/page-data-client.js"></script>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
<div class="cf-turnstile" data-sitekey="你的站点密钥"></div>
<form id="signup">
  <input name="name" required />
  <button type="submit">提交</button>
</form>
<script>
  const client = MindSpacePageData.createClient({ pageId: '页面UUID' });
  document.getElementById('signup').addEventListener('submit', async (e) => {
    e.preventDefault();
    const name = e.target.name.value.trim();
    const token = turnstile.getResponse();
    await client.insertRow('signups', { name }, { turnstileToken: token });
    turnstile.reset();
  });
</script>

验证码 token 也可放在请求体 turnstile_token / captcha_token，或通过头 x-page-data-captcha 传递。

Agent MCP 工具

private_data_register_dataset — 注册 dataset
private_data_set_page_policy — 为已发布页写 Page Access Policy
private_data_close_page_dataset — 关闭某 dataset 的公开访问

本地验证

node --test page-data-acceptance.test.mjs page-data-integration.test.mjs page-data-public-service.test.mjs
node scripts/run-memind-tests.mjs --mode changed

安全提醒

公开读默认关闭；开启前确认字段不含敏感信息。
密码访问无法强身份绑定，仅适合轻量协作。
生产公开写入建议开启 Turnstile 并监控「页面数据」操作日志。

4.9 KiB Raw Blame History