94 lines
5.1 KiB
Markdown
94 lines
5.1 KiB
Markdown
---
|
||
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` 打开当前项目的 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。
|