spherse-build-data-app

构建数据型应用

数据型应用是由 HTML 页面和一个或多个 Agent 围绕同一份 *.data.json 持续互动的应用，例如虚拟论坛、任务系统、经营模拟、社区、知识库或工作流看板。

这套 data 能力有两个核心目标：

1. 让 Agent 通过业务命名的查询只获取当前任务所需的数据，避免每次读取整个数据文件占用上下文。
2. 让页面和 Agent 通过经过 schema 校验的原子 mutation 修改数据，避免手工编辑 JSON 时选错路径、写错字段或覆盖并发变更。

本 Skill 负责数据建模与协作方式。生成 HTML 时同时加载 spherse-write-html，查询 UI SDK 参数时加载 spherse-use-ui-sdk。

核心原则

• 数据会增长或需要 Agent 参与读写时，必须使用 *.data.json 并内嵌 $manifest。
• 先设计 Agent 会问的问题和会执行的业务动作，再设计 queries 和 mutations，最后生成页面。
• 把 $manifest 当作页面与 Agent 共享的业务接口，不只是数据结构说明。
• Agent 首次接触文件时用 read_data 获取 outline，后续优先使用 query_data 和 mutate_data。
• 页面和 Agent 对同一种业务写入必须调用同名 mutation，不能各自实现一套读改写逻辑。
• 集合条目必须有稳定且唯一的 identity，通常是由 auto 生成的 UUID。
• manifest 保持精简（建议不超过 2KB），只保存路径映射、入口描述和 schema，不放示例数据。
• manifest 的 path 使用对象字段 dot-path（如 forum.threads），不支持数组下标。
• 创建参与互动的 Agent 时，根据职责显式启用所需的 data tools，并遵循最小权限原则。

设计工作流

1. 列出 Agent 的读取问题

从 Agent 的实际任务出发列出需要回答的问题，而不是先暴露整份数据。例如虚拟论坛中的 Agent 可能需要：

• 查看最新的开放主题
• 按板块查看主题
• 根据主题 ID 获取单个主题
• 查看某个主题下的回复

将高频、边界明确的问题设计为命名 query。query 名称应表达业务语义，例如 listOpenThreads、listRepliesByThread，不要使用 getData、queryItems 等模糊名称。

当前 query 引擎适合数组数据，支持：

• enum、string、integer、boolean 参数按同名字段相等过滤
• identity 字段精确定位单条记录
• sort + dir 排序
• defaultLimit、limit 和 after 分页

需要分页或按 ID 定位的 query 必须声明唯一 identity。翻页时把上次结果的 nextAfter 传给下一次调用；不要修改已有条目的 identity。

不要为了“以后可能需要”暴露大量入口。只声明页面或 Agent 确实会使用的查询。

2. 列出业务写入动作

把每种写入建模为命名 mutation：

业务动作	mutation op	示例
新增集合条目	append	createThread、addReply
按 identity 修改条目	update	setThreadStatus
按 identity 删除条目	remove	removeReply
合并更新对象	set	updateForumStats

mutation 名称描述业务动作，fields 只开放允许调用方写入的字段。使用 required、enum 和 default 固化数据约束；使用 auto.uuid 和 auto.nowIso 统一生成 identity 与时间。

match 用于 update 和 remove 定位条目，通常与对应 query 的 identity 相同。调用方把 match 字段放在 args 中传入，但不要在 fields 中重复声明。

3. 同源生成三部分

一次完成并保持一致：

1. *.data.json 的业务数据结构和 $manifest
2. HTML 的读取、渲染与 spherse.data.mutate 调用
3. 参与 Agent 的职责说明和 data tool 权限