页面
工作台里的小型网页应用：仪表盘、报表、追踪表与小工具，能定时刷新、能调用来源，长驻在侧栏里。
页面如何工作
页面是住在工作区里的小型网页应用：仪表盘、报表、追踪表或者一个小工具。和聊天回复不同，页面会一直留在那里——它出现在侧栏的页面区域，可以直接在应用内打开。
每个页面是一份自包含的 HTML 文档加上一份小数据仓，存放在工作区的 pages 目录下。打开时它在应用内的沙箱框里渲染，不弹独立窗口；页面自身不持有任何凭据，也拿不到你的应用数据与文件系统。
页面有三种类型，决定了它能做什么。
从侧栏 Pages 打开网格，点击 New Page 可先建空白页，也可以让 Agent 创建页面并填入数据。页面工具在提供这些工具的会话模式中使用；不要仅写一个 HTML 文件就当作已登记的 Page。
| 类型 | 是否运行脚本 | 适合做什么 |
|---|---|---|
| 静态 | 否 | 固定文档、格式化报表 |
| 交互 | 是 | 计算器、可探索的工具、读者点击着用的界面 |
| 实时 | 是，并在打开时接收数据更新 | 由计划或 Agent 喂数据的仪表盘 |
数据模型
和 HTML 分开，每个页面都有一份内置的小数据仓，只有两种数据形状。
页面每次读取的是这份数据仓的一个快照，它不直接碰底层存储。这也是同一个页面在桌面端、网页端和共享副本里都能渲染一致的原因。
- 键值：把一个名字映射到任意 JSON 值，适合存当前数字：一个总量、一个状态对象、最后一次更新时间。
- 时间序列：一串具名数据点，每个点是时间加数值，适合任何需要按时间作图的内容：计数、耗时、价格。
给页面填入初始数据
「填入初始数据」指的是在页面第一次按计划刷新之前，先把第一批数据写进它的数据仓，这样页面一打开就有内容。Agent 在构建页面时会顺手完成这一步，但了解数据怎么进来仍然有用。
- Agent 写入初始数据：当你要求一个数据驱动的页面时，Agent 会一边创建页面，一边把数字取回来写成键值项与时间序列点。
- 计划保持新鲜：如果你还要求它随时间更新，Agent 会同时挂上刷新计划，每次运行都往同一份数据仓里追加。
| 你想要 | 可以这样说 |
|---|---|
| 一次性仪表盘 | 做一个页面，按团队展示当前人数，用柱状图 |
| 先填数据再持续跟踪 | 做一个实时页面跟踪下载量，先填今天的数字，之后每天加一个点 |
| 从文件生成 | 把这份月度营收 CSV 变成一个带折线图的页面 |
连接来源
交互式页面可以调用你已接入的来源，比如一个通过邮件来源发信的按钮，或者一个创建协作平台议题的表单，而页面自身并不持有任何凭据。
安全边界靠授权维持：页面只能通过你批准的授权调用来源，授权是一份具体且有界的权限，比如「这个页面可以从代码托管平台读取」或「这个页面可以调用发信工具」。
- 授权绑定内容版本：授权与页面当前内容绑定，页面内容一变就需要重新批准。
- 授权会过期：授权在约 30 天后失效，届时需要重新批准。
- 随时可查可撤：在页面菜单里可以查看并移除已批准的调用。
- 每次调用留痕：调用记录写入审计日志，便于回溯。
- 读操作可以直接跑：只有读取类的接口调用可以在打开时自动执行，写入、MCP 工具与脚本调用都需要你在页面里点一下来发起。
来源失去认证时重新连接
页面已授权的来源需要重新认证时，页面内容上方会出现由 ZeroWorks 显示的 Reconnect 横幅，来源名称取自工作区配置。它处理来源认证，不等于重新批准页面动作。
- 先核对横幅里的来源名称和当前工作区，避免把凭据填进页面 HTML 自己画出的表单。
- OAuth 来源点 Reconnect，完成该来源实际支持的授权流程；单值 API key、Bearer、单 header 或 query 凭据在工作台的安全输入框里更新。
- Basic 或多 header 等多字段认证会显示 Fix with agent，转到会话修复来源配置；不能只填其中一个值就当作认证恢复。
- 认证状态更新后横幅会消失，再触发一次原读取/按钮操作。若页面内容改过、授权过期或已撤销，仍需重新批准对应动作。
让页面跑一段脚本
页面可请求运行工作区脚本的授权：先由你批准确定的脚本、运行时和参数，再由页面中的点击触发。已有有效授权可以复用，不是每次执行都弹出一次新的批准窗口；运行主机是工作区服务所在主机。
脚本路径必须留在工作区内部，以参数数组启动而不经过 shell；环境包含 CRAFT_* 变量与少量运行时必要的平台变量，不继承完整环境或普通凭据。默认 60 秒超时、最长 15 分钟。
- 参数在批准时就固定：页面在调用时不能改脚本、运行时与参数，需要多种行为就分别批准不同脚本。
- 自有分享打包路径会拒绝带脚本授权的页面；条件性 Claude artifact 副本也不携带授权或主机执行能力。
- 随时可以撤：在页面的已批准操作里移除即可。
定时刷新
实时页面通常配一条刷新计划：到点自动跑一次脚本取数、写进数据仓、页面在打开状态下同步更新，不用你手动点刷新。
刷新计划写在页面自己的刷新规格里，由 cron 表达式驱动，不经过 Agent 会话，也不会新建会话。
- 让 Agent 通过 list_pages / get_page 确认页面 slug 和当前 refresh 配置，再创建实际取数脚本；脚本路径相对于工作区根目录。
- 验证脚本能完成写入后，用 update_page 保存下面这种 refresh 对象，替换为该页面的真实 slug 和已存在的脚本路径。
- 等待下一次计划，核对 lastRefresh.ok、at 和数据快照；live 页面收到替换快照后更新。脚本调度不会创建 Agent 会话。
- 计划有下限：cron 必须能解析、能真正触发，而且不能比每 5 分钟一次更频繁，写错的规格会让页面保存失败并给出原因。
- 脚本要在工作区里：默认用 Bun，也支持已配置的 node 或 python3；需要 bun:sqlite 数据仓时使用 Bun。环境沿用受限脚本环境，并注入 CRAFT_WORKSPACE_PATH、CRAFT_PAGE_SLUG、CRAFT_PAGE_DIR、CRAFT_PAGE_DATA_DIR。
- 脚本自己写数据：更新数据仓、导出快照、退出即可，执行器随后盖章并把新快照推给打开的页面。
{ "slug": "build-health", "refresh": { "cron": "*/15 * * * *", "timezone": "Asia/Shanghai", "script": "scripts/refresh-build-health.ts", "timeoutMs": 60000, "enabled": true } }
暂停计划、排查失败与恢复
- 失败时先检查脚本文件、运行时、超时、来源认证和工作区路径。用 Open folder 查看实际 index.html、page.json 与 data/snapshot.json。
- 修复后运行一次相同脚本验证输出；快照契约为 version: 1、generatedAt 毫秒时间戳、kv 对象和 series 对象，序列点使用 { t, v }，不是 { time, value }。
- 确认计划已启用并等待下一次触发，检查新的 lastRefresh 成功记录和实际数值。服务进程关闭时不会刷新，恢复进程不等于所有错过时刻都补跑。
| 状态或操作 | 检查与处理 |
|---|---|
| 暂停 | 保留完整 refresh 对象，仅把 enabled 设为 false；不会删除既有数据 |
| 恢复 | 用 update_page 写回同一份完整 refresh 对象并设 enabled: true，等待下次匹配 |
| 删除计划 | update_page 的 refresh: null 清除计划；与暂停不同 |
| 刷新失败 | 查看页面顶部错误和 get_page 返回的 lastRefresh.error、ok、at、durationMs；画面里的旧数据不能当成新读取结果 |
| 预览过期 | Refresh preview 只重截缩略图，不运行取数脚本，不改变数据更新时间 |
| 页面载入失败 | 使用 Retry 重新取得渲染内容；它不替代来源重连或定时脚本修复 |
分享页面
需要交付文件时，让 Agent 从页面 HTML 和当前数据快照生成一份自包含副本，并实际打开核对数据与布局。生成交付文件需要明确嵌入快照，不能只复制 index.html 就假定它已带数据，也不要假定页面菜单有一键导出。
ZeroWorks 自有 Pages 公网发布默认关闭：新建公开链接、更新公开版本及设置公开密码会被拦截，返回 PAGE_SHARING_DISABLED。历史公开副本保留撤回入口，撤回仍依赖原托管服务和管理凭据。
- 生成文件副本：嵌入所需快照，去除工作台动作依赖，确认能独立打开后交付或归档。
- 写进项目文档：让页面成为长期可检索的一部分，而不只是临时文件。
- 经来源附到协作平台：把页面结论发到对应的议题或讨论里。
条件性入口：发布为 Claude artifact
这是独立的第三方发布路径。当前桌面代码仅在存在 Claude 账号连接时显示 Publish as Claude artifact；连接需为 providerType: anthropic、authType: oauth，单独的 API key 不满足条件。WebUI 不显示该入口，避免把服务端账号当作浏览者账号发布。
入口可见只说明本地存在对应连接，不保证账号已获 Artifact 工具或组织政策允许发布。自有 Pages 公开链接仍保持关闭，不会因 Claude artifact 入口出现而开放。
- 在桌面端「设置 → AI」核对 Claude 账号连接及实际账号；优先使用默认 Claude 账号连接，否则代码会选第一个符合条件的连接。先确认它就是打算存放副本的账号。
- 检查页面 HTML 与当前完整数据快照，因为此路径会一起上传它们。打开页面头部的 Publish as Claude artifact；没有入口或返回 ARTIFACT_UNAVAILABLE 时停止，检查账号能力与组织政策。
- 只有收到真实成功结果与 URL 后，再通过 Open Claude artifact 打开 claude.ai 核对内容；对外分享权限在 claude.ai 中单独管理，不等于已经向他人分享。
- 后续使用 Update Claude artifact 更新同一副本，不会实时同步数据。若返回 ARTIFACT_AUTH_REQUIRED，用 Reconnect 回到「设置 → AI」重新登录；ARTIFACT_CONFLICT 时先在 claude.ai 核对并协调已有改动。
管理页面
页面在侧栏的页面区域集中管理，可以重命名、移动到别的项目、刷新预览或删除。
网格里的方块会显示页面预览，需要最新的画面时可以从方块的右键菜单里强制刷新预览。
详情页的更多菜单提供 Open folder、Refresh preview，以及有授权时显示的 Approved actions；在 Approved actions 中检查来源/脚本权限，移除不再需要的授权。
删除会移除页面目录及数据。已有自有公开副本会先尝试撤回；若结果提示 publicCopyMayRemain，必须继续处理远端副本。已生成文件、项目文档和 Claude artifact 不会跟着消失。