makelore/resources/coding-skills/data-service/SKILL.md

name, description

name	description
data-service	当用户明确要求为当前 MakeLore 项目添加持久化开发数据、集合或数据读写示例时使用；只在本地预览中验证，不用于已发布作品。

MakeLore 开发数据

为当前项目添加开发数据时，使用本 Skill 的顺序和完成条件。数据能力是 显式 opt-in，必须得到 explicit user intent；读取项目、创建项目、打开预览或复制项目本身都不会配置服务、 安装 SDK 或编辑源码。

1. Inspect

先 inspect 当前项目的实际目录、package.json、tsconfig.json（如果存在）、 已有入口文件和数据需求。识别完成当前功能所需的最小集合名称及每个集合的 最小文档形状；按实际源文件而不是 projectType 标签判断 TypeScript 或 JavaScript。

完成条件：已经列出实际布局、候选集合和最小示例，并且还没有修改应用源码、 安装 SDK 或调用 data_service_configure。

2. Explain and wait

向用户说明候选集合、示例文档、将要写入的目标文件和预览验证动作。等待用户 明确同意这个具体集合方案；推测用户意图、提前配置或先写模板都不算同意。

完成条件：用户明确同意本次集合方案；若用户拒绝或改变需求，回到 Inspect， 不要产生源码编辑。

3. Configure once

在明确同意后，用 data_service_configure 对这一个最终集合列表调用一次，且 只传实际项目上下文。不要因为响应慢、限流或不确定结果重复调用；配置响应是 后续步骤的唯一门槛。

完成条件：一次调用明确成功并返回配置/实例 DTO。若失败或返回 project_identity_required，立即停止，保持应用源码零编辑，并如实报告结果； 不要安装模板、创建示例或声称服务已配置。

4. Install the canonical SDK

配置成功后，根据实际布局选择唯一目标：

1. 有 src/ 时，若源代码/tsconfig.json 证明项目使用 TypeScript，目标是 src/lib/makelore-data.ts，否则是 src/lib/makelore-data.js。
2. 没有 src/ 时，若已验证 TypeScript 工具链，目标是项目根的 makelore-data.ts，否则是根目录 makelore-data.js。

从本 Skill 的 assets/makelore-data.ts 或 assets/makelore-data.js 逐字复制 选中的文件；不要让模型从说明重写 transport。目标不存在时创建它；目标文本 已与选中的 asset 完全相同则保持精确文本 no-op。目标存在但文本不同，先展示 实际路径和冲突事实，明确询问“替换 canonical 文件”或“保留并由用户自行 适配”；没有明确选择时不覆盖、不继续报告成功。

在最小有用的现有应用文件中加入指向该精确目标的相对 import，并添加最小 示例调用。只编辑完成示例所需的 import/应用代码；不要加入 cloud URL、账号 凭据、缓存、重试、离线同步、订阅、schema 或 policy 层。SDK 的 DELETE 是 普通程序操作，不接受 confirmed。

完成条件：配置成功后，canonical asset 已按实际布局逐字落到唯一目标；重复 运行会得到字节级 no-op；修改过的目标会先产生清晰冲突询问；最小应用编辑 只引用该目标且没有凭据或远端地址。

5. Preview verification

用 agent_browser 打开当前项目的 data-enabled preview，要求其使用 inject_project_data: true 的本地预览能力；不要在外部浏览器、发布运行时或 通用 Host 路径中寻找替代能力。实际运行最小示例，先执行一次真实 put，再 用返回的文档标识执行 get，读取并直接比较返回的文档数据与刚写入的数据。

完成条件：同一次数据预览会话中的真实 put 已成功，随后真实 get 的数据 逐项匹配且带有服务端返回的 revision。没有匹配的 read-back、没有预览注入、 或出现 runtime_unavailable 时，报告阻塞事实，不报告配置成功或配额状态。

6. report

只有 read-back 匹配后，才可用 data_service_inspect 读取并报告实际配置的 集合和响应中的 quota/usage 状态。报告只引用本次工具响应观察到的字段，不猜 测实例、owner、project、路径或剩余配额；如果 inspect 失败，报告验证失败而 不是补造状态。

完成条件：报告明确区分配置响应、真实 put/get 结果和观察到的 quota/usage， 并没有暴露凭据、云端地址、绝对路径或未观察到的服务端状态。

Fixed SDK surface

程序只使用 assets/makelore-data.ts 或 assets/makelore-data.js 提供的 data.get、data.list、data.put、data.delete 和可选 data.add。SDK 每次 调用读取 globalThis.__MAKELORE_DATA__，只接受 contractVersion === 1，将 集合/文档路径片段用 encodeURIComponent 编码，并把 ifRevision 转成一个 strong If-Match。它严格解析直接的文档/page/error DTO；缺失注入时返回稳定 runtime_unavailable 且不发网络请求。SDK 不持有凭据，不访问云端，不重试， 不缓存，也不实现离线、订阅、schema 或 policy。