---
name: data-service
description: 当用户明确要求为当前 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` 的 `open` 输入 `{ action: "open", url: "<本地预览地址>", injectProjectData: true }`
打开当前项目的 data-enabled preview；不要在外部浏览器、发布运行时或
通用 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。