Add page data delivery and publication guards

docs/examples/page-data-survey-test.md

@@ -0,0 +1,75 @@
+# Page Data 问卷测试案例（TKMind 功能偏好调查）
+
+本地演示：john 用户工作区中的 `tkmind-survey.html` + `tkmind-survey-admin.html`。
+
+## 一次性准备
+
+确保 Portal 已启动（`pnpm dev`，默认 `http://localhost:8081`），然后执行：
+
+```bash
+node scripts/setup-page-data-survey-demo.mjs
+```
+
+脚本会：
+- **问卷页**以 `public` 发布（访客可直接提交，无需口令）
+- **后台页**以 `password` 发布（口令 **88888888**，平台要求至少 8 位）
+
+## 测试入口
+
+| 页面 | URL |
+|------|-----|
+| 问卷（访客提交，无需登录） | http://localhost:8081/MindSpace/1c99b83b-0454-474f-a5d2-129d34506a32/public/tkmind-survey.html |
+| 后台（查看记录，需口令） | http://localhost:8081/MindSpace/1c99b83b-0454-474f-a5d2-129d34506a32/public/tkmind-survey-admin.html |
+
+后台登录密码：**88888888**
+
+## 测试步骤
+
+### 1. 验证 pageId 自动注入
+
+打开问卷页 → 浏览器开发者工具 → Console：
+
+```javascript
+window.__MINDSPACE_PAGE_DATA__
+// 问卷页应返回 { pageId: "...", accessMode: "public" }
+// 后台页应返回 { pageId: "...", accessMode: "password" }
+```
+
+### 2. 提交问卷
+
+1. 打开问卷链接
+2. 逐步完成 3 道题并提交
+3. 应看到「感谢你的反馈」成功页
+
+### 3. 后台查看
+
+1. 打开后台链接
+2. 输入密码 `88888888`
+3. 表格中应出现刚提交的记录
+4. 可点「导出 CSV」验证
+
+### 4. 确认无旁路 API
+
+```bash
+lsof -i :8899   # 应无 survey-api 进程
+```
+
+数据读写应全部走同域 `/api/public/pages/:pageId/data/...`。
+
+## Agent 复现流程（供对照）
+
+```text
+load_skill → page-data-collect
+private_data_execute        # CREATE TABLE survey_responses ...
+private_data_register_dataset
+write_file                  # public/tkmind-survey.html + admin.html
+private_data_bind_workspace_page  # 问卷页 + 后台页各 bind 一次
+```
+
+HTML 中只需：
+
+```javascript
+MindSpacePageData.createClient({ apiBase: '/api' });
+```
+
+无需手写 `pageId`。

docs/page-data-api-usage.md

@@ -4,9 +4,10 @@
 
 ## 快速路径
 
-1. **Agent** 用 `private_data_execute` 建表，用 `private_data_register_dataset` 注册 dataset。
+1. **Agent** 加载 `page-data-collect` 技能（或按该技能流程执行）。
+2. **Agent** 用 `private_data_execute` 建表，用 `private_data_register_dataset` 注册 dataset。
 2. **发布页面** 时在发布面板勾选「启用页面数据」，选择 dataset 与公开能力；或发布后让 Agent 调用 `private_data_set_page_policy`。
-3. **HTML 页面** 引入 `/assets/page-data-client.js`，用 `MindSpacePageData.createClient({ pageId })` 读写数据。
+3. **HTML 页面** 引入 `/assets/page-data-client.js`，用 `MindSpacePageData.createClient({ apiBase: '/api' })` 读写数据（`pageId` 可由平台在访问时自动注入）。
 4. **运维** 在 MindSpace 页面详情「页面数据」面板查看日志、导出、撤销令牌、恢复软删除、关闭 dataset。
 
 ## 访问模式与默认能力
@@ -59,8 +60,8 @@ GET    /api/public/pages/:pageId/data/:dataset/stats
 ```html
 <script src="/assets/page-data-client.js"></script>
 <script>
+  // pageId 可省略：已绑定/已发布的页面访问时会注入 window.__MINDSPACE_PAGE_DATA__
   const client = MindSpacePageData.createClient({
-    pageId: '你的页面 UUID',
     apiBase: '/api',
   });