@my-life-buddies/cli 0.2.0 → 0.4.0

package/README.md

@@ -1,12 +1,14 @@
 # buddy-cli 使用说明
 
-这份说明按一次开发过程展开：登记搭子，准备工程，在本地预览，然后上传程序包。所有搭子统一使用 `@my-life-buddies/buddy-runtime`，业务能力通过 Prompt、`src/buddy.mjs` 和 Tool 实现。
+这份说明按一次开发过程展开：登记搭子，准备工程，在本地预览，然后上传程序包。所有搭子统一使用 `@my-life-buddies/buddy-runtime`，业务能力通过 Prompt、`src/buddy-options.mjs` 和 Tool 实现。
+
+工程模板已锁定公共 npm 的 Runtime `0.10.0`，本批接口变化与联调范围见 [Runtime 集成说明](../../docs/runtime-integration.md)。
 
 ## 准备 CLI 和平台地址
 
 目前只支持 macOS，要求 Node.js 24 或更新版本。
 
-当前 CLI 工程版本为 `0.2.0`，发布到公共 Registry `https://registry.npmjs.org/`。已有仓库源码时，在仓库根目录运行：
+当前 CLI 工程版本为 `0.4.0`，发布到公共 Registry `https://registry.npmjs.org/`。已有仓库源码时，在仓库根目录运行：
 
 ```bash
 npm install
@@ -16,7 +18,7 @@ npm run buddy-cli -- --help
 下文统一使用 `buddy-cli`。源码运行时替换为 `npm run buddy-cli --`；从公共 npm 安装已发布版本：
 
 ```bash
-npm install --global @my-life-buddies/cli@0.2.0 --registry=https://registry.npmjs.org/
+npm install --global @my-life-buddies/cli@latest --registry=https://registry.npmjs.org/
 ```
 
 维护者需先登录公共 npm，拥有 `@my-life-buddies` scope 的发布权限，并完成 npm 要求的两步验证（2FA）。在仓库根目录完成验证，只发布 CLI：
@@ -27,7 +29,7 @@ npm run verify:package
 npm publish --workspace @my-life-buddies/cli
 ```
 
-对外只有 `@my-life-buddies/cli@0.2.0`，`publishConfig` 已指定公共 npm 和 `public` 访问级别。Core 和 Preview 保留 monorepo 开发边界并标记为 `private`，构建时合入 CLI 的内部模块；Preview 页面、Creator Skill、工程模板资源一同进入 CLI 包。安装不会请求 `@buddy/cli-core` 或 `@buddy/preview`。第三方运行依赖按正常 npm dependencies 安装，构建工具 esbuild 不进入安装依赖。根工作区和 Web 同样保持 `private`。
+对外只有 `@my-life-buddies/cli@latest`，`publishConfig` 已指定公共 npm 和 `public` 访问级别。Core 和 Preview 保留 monorepo 开发边界并标记为 `private`，构建时合入 CLI 的内部模块；Preview 页面、Creator Skill、工程模板资源一同进入 CLI 包。安装不会请求 `@buddy/cli-core` 或 `@buddy/preview`。第三方运行依赖按正常 npm dependencies 安装，构建工具 esbuild 不进入安装依赖。根工作区和 Web 同样保持 `private`。
 
 版本维护：每批修改 CLI 发布内容时递增一次版本，默认 patch；根包和内部工作区版本、依赖引用、锁文件一起更新。Agent 工程自己的项目版本独立。升级 Runtime 时同步模板依赖与模板锁文件，并运行独立安装验收。
 
@@ -48,10 +50,12 @@ CLI 会把换取到的会话保存到 macOS Keychain。有效会话会复用，
 | 命令 | 是否需要 Agent 目录 | 会发生什么 |
 | --- | --- | --- |
 | `help`、`--help` | 不需要，也不登录 | 显示参数说明 |
-| `login`、`logout`、`models` | 不需要 | 管理账号会话或查询平台模型 |
+| `login`、`logout` | 不需要 | 管理账号会话 |
+| `models [--json]` | 不需要，也不登录 | 离线读取 CLI 内置模型目录 |
 | `init` | 目标目录可以是空目录或已有官方工程 | 登记或恢复云端身份，准备本地文件 |
 | `dev`、`preview`、`push` | 需要有效清单和完整工程文件 | 运行、调试或打包该工程 |
 | `status` | 需要含 `buddyId` 的 `buddy.agent.json` | 查询该搭子的云端状态；创作尚未完成时也可使用 |
+| `datasets` | 需要工程和安装好的 Runtime，无需登录 | 读取 Runtime 的全部数据集；支持 `--directory`、`--json` |
 
 项目命令可从工程子目录向上定位配置，也可用 `--directory` 指定工程。普通目录不会被悄悄初始化；已有官方工程可用 `init --mode direct` 补齐缺失的模板文件，已有文件不会被覆盖。
 
@@ -83,27 +87,27 @@ buddy-cli init --mode direct --directory ./study-buddy \
 
 CLI 只生成工程骨架，不分析手册或自动生成业务代码，也不固定追加一轮 Memory、Context 或其他技术选项的确认。Coding Agent 根据已确认需求完成实现；只有会影响体验、数据使用或权限的关键条件还不明确时，才用日常语言补问。
 
-默认能力满足需求时直接沿用；不满足时要落实到代码，而不是只修改描述。例如新 Runtime 不会自动查询或提炼长期记忆，需要记忆时必须按已确认的数据边界显式实现，并通过 `src/buddy.mjs` 接入相应 Tool 或 Hook。Runtime 会从 MLB 重建会话历史，但持续计划和结构化状态不应只依赖聊天记录。需要不同做法时，Coding Agent 应检查并补齐真实执行路径。
+默认能力满足需求时直接沿用；不满足时要落实到代码，而不是只修改描述。例如新 Runtime 不会自动查询或提炼长期记忆，需要记忆时必须按已确认的数据边界显式实现，并通过 `src/buddy-options.mjs` 接入相应 Tool 或 Hook。Runtime 会从 MLB 重建会话历史，但持续计划和结构化状态不应只依赖聊天记录。需要不同做法时，Coding Agent 应检查并补齐真实执行路径。
 
 你会得到：
 
 ```text
 study-buddy/
-├── buddy.agent.json           平台 buddyId、模型与数据需求
-├── agent.md                   应用 Prompt，只包含自然语言
-├── start.mjs                  本地和云端共用的启动入口
-├── package.json               包含 npm start
-├── package-lock.json          依赖锁文件
+├── buddy.agent.json       平台 buddyId、模型与数据需求
+├── agent.md               应用 Prompt，只包含自然语言
+├── start.mjs              本地和云端共用的启动入口
+├── package.json           包含 npm start
+├── package-lock.json      依赖锁文件
 ├── src/
-│   ├── buddy.mjs              BuddyFactory，组装工具与回合钩子
-│   ├── tools/                 自定义工具，默认空目录
-│   ├── hooks/                 执行钩子，默认空目录
-│   └── services/              普通业务代码，默认空目录
-├── resources/                 Markdown 参考资料，默认空目录
-└── widgets/                   小挂件类型的页面和 Schema，默认空目录
+│   ├── buddy-options.mjs  BuddyFactory，组装工具与回合钩子
+│   ├── tools/             自定义工具，默认空目录
+│   ├── hooks/             执行钩子，默认空目录
+│   └── services/          普通业务代码，默认空目录
+├── resources/             Markdown 参考资料，默认空目录
+└── widgets/               小挂件类型的页面和 Schema，默认空目录
 ```
 
-`src/buddy.mjs` 是每场会话的组装入口，导出 `createBuddy(conversation)`，返回 Runtime 所需的 `BuddyOptions`。它用 `new URL("../agent.md", import.meta.url)` 读取根目录 Prompt，显式导入和注册工具与钩子。
+`src/buddy-options.mjs` 是每场会话的组装入口，导出 `createBuddyOptions(conversation)`，返回 Runtime 所需的 `BuddyOptions`。它用 `new URL("../agent.md", import.meta.url)` 读取根目录 Prompt，显式导入和注册工具与钩子。
 
 | 目录 | 放什么 |
 | --- | --- |
@@ -119,7 +123,7 @@ study-buddy/
 
 ```text
 widgets/
-└── sleep-record/     稳定的 widget 类型 ID
+└── sleep-record/  稳定的 widget 类型 ID
     ├── index.html    单文件页面，样式与脚本内联
     └── schema.json   MLB widget 类型定义
 ```
@@ -128,9 +132,9 @@ widgets/
 
 `schema.json` 的顶层是 `{ "description": "...", "modules": { ... } }`，各模块包含 `description` 和 `record`；`record` 才是该模块记录的 JSON Schema。不要直接把一份普通 JSON Schema 当作整个类型定义。
 
-CLI 将 HTML 和 Schema 随工程源码打包。模板锁定的 Runtime `0.7.0` 在 BuddyServer 启动时读取 `widgets/`，通过 `PUT /internal/v1/widget-types/:typeId` 一起上传 Schema 与 HTML；全部成功后才连接事件流。缺文件、无效 JSON 或平台拒绝上传会使启动失败，具体原因可在终端或 Preview 日志中查看。平台需要已部署该接口。
+CLI 将 HTML 和 Schema 随工程源码打包。工程安装的 Runtime 在 BuddyServer 启动时读取 `widgets/`，通过 `PUT /internal/v1/widget-types/:typeId` 一起上传 Schema 与 HTML；全部成功后才连接事件流。缺文件、无效 JSON 或平台拒绝上传会使启动失败，具体原因可在终端或 Preview 日志中查看。平台需要已部署该接口。
 
-模型使用小挂件工具时，在 `src/buddy.mjs` 的 `platformTools` 中显式选择 `widget_create`、`widget_write` 等工具；直接调用 `conversation.widgets` 不受该名单限制。类型按上传进程的 Buddy 身份保存，DEV 分身与正式版隔离。修改文件后重启 Runtime；删除或改名目录不会删除平台上的旧类型。浏览器中的 Widget 渲染预览仍待接入。
+模型使用小挂件工具时，在 `src/buddy-options.mjs` 的 `initialState.tools` 中加入 `conversation.tools.widget_create`、`conversation.tools.widget_write` 等工具；业务代码也可直接调用 `conversation.widget`，主动服务回合禁止写操作。类型按上传进程的 Buddy 身份保存，DEV 分身与正式版隔离。修改文件后重启 Runtime；删除或改名目录不会删除平台上的旧类型。Preview 可展示小挂件卡片、会话列表与 H5 页面。
 
 先改 `agent.md`，决定这个搭子怎么与用户交流：
 
@@ -138,19 +142,21 @@ CLI 将 HTML 和 Schema 随工程源码打包。模板锁定的 Runtime `0.7.0`
 你是学习搭子。先了解学习目标，再给一个今天能完成的练习；不要编造用户过去的学习记录。
 ```
 
-要增加业务 Tool 时，在 `src/buddy.mjs` 的 `initialState.tools` 注册 `AgentTool`；参数 Schema 的 `Type` 从 `typebox` 导入。Memory 通过 `conversation.memory` 显式读写，授权数据、小挂件和发消息也通过当前会话的 `conversation.memory / dataAccess / widgets / proactive` 调用。平台工具通过 `platformTools` 明确启用。完整契约见 [新 Runtime 说明](https://code.devops.xiaohongshu.com/dada/buddy-runtime)。
+要增加业务 Tool 时，在 `src/buddy-options.mjs` 的 `initialState.tools` 注册 `AgentTool`；参数 Schema 的 `Type` 从 `typebox` 导入。Memory 通过 `conversation.memory` 显式读写，授权数据、小挂件和发消息也通过当前会话的 `conversation.memory / dataAccess / widget / resource / proactive` 调用。平台工具从 `conversation.tools` 取出并加入 `initialState.tools`。完整契约见 [新 Runtime 说明](https://code.devops.xiaohongshu.com/dada/buddy-runtime)。
 
 
-`start.mjs` 是 CLI 生成的启动与停止入口；`src/buddy.mjs` 负责业务配置。启动文件通过以下方式接入组装器：
+`start.mjs` 是 CLI 生成的启动与停止入口；`src/buddy-options.mjs` 负责业务配置。启动文件通过以下方式接入组装器：
 
 ```js
+import { readFileSync } from "node:fs";
 import { BuddyServer } from "@my-life-buddies/buddy-runtime";
-import createBuddy from "./src/buddy.mjs";
+import createBuddyOptions from "./src/buddy-options.mjs";
 
-await BuddyServer.start({ model, buddy: createBuddy });
+const config = JSON.parse(readFileSync(new URL("./buddy.agent.json", import.meta.url), "utf8"));
+await BuddyServer.start({ dataRequirements: config.datasets ?? [], buddy: createBuddyOptions });
 ```
 
-新工程在 `package.json` 中固定 Runtime `0.7.0` 并保留锁文件，先运行 `npm ci`，再运行 `buddy-cli dev`。已有工程的依赖不会被 CLI 升级自动覆盖；在该工程运行 `npm install --save-exact @my-life-buddies/buddy-runtime@0.7.0 --registry=https://registry.npmjs.org/`，同步更新依赖和锁文件后重启。上传不包含 `node_modules` 或 Runtime 打包副本；部署端安装依赖后执行同一个 `npm start`。
+工程在 `package.json` 声明准确 Runtime 版本，锁文件固定依赖；上传不包含 `node_modules` 或 Runtime 打包副本，部署执行同一份 `npm start`。模板及锁文件使用 Runtime `0.10.0`，安装验收直接从公共 npm 安装，不替换依赖。
 
 ## 想法还模糊时，先梳理需求
 
@@ -171,14 +177,15 @@ buddy-cli init --mode create --directory ./study-buddy \
 ```text
 登录 → 确定登记资料（Agent 拟稿须确认或获授权代定）
      → 登记身份 → 准备 Creator Skill → Coding Agent 完成创作
-         → 用户确认 Booklet → Creator 交还控制 → 根据手册落实代码
+         → 四册确认 → 小挂件清单确认 → 原型确认 → 设计验收
+         → 交付校验 → Creator 交还控制 → 自动根据手册落实代码
          （只对关键缺口补问，不重新采访）
          → 基础技术自测 → 打开真实预览 → 开发者体验并反馈
 ```
 
-当前内置 Creator Skill 1.3.1，随 CLI 安装，不需要运行时从 GitHub 下载或全局注册。执行它的工具需要 Python 3.9+；登录与身份登记仍要联网。Skill 的作品预览不是 Agent 聊天模拟器。已有作品升级后沿用原工作区，让 Coding Agent 重新读取 Skill 和宿主协议即可按新规则接续。
+当前内置 Creator Skill 1.4.0，随 CLI 安装，不需要运行时从 GitHub 下载或全局注册。执行它的工具需要 Python 3.9+；登录与身份登记仍要联网。Skill 的作品预览不是 Agent 聊天模拟器。已有作品升级后沿用原工作区，让 Coding Agent 重新读取 Skill 和宿主协议即可按新规则接续。
 
-创作资料保存在 `.buddy/creator/`。四册确认完成、手册有效时，Skill 返回 `directive=creator_complete` 和 `completion.manualPath`。Coding Agent 结束采访，重新读取 `HANDOFF.md` 和完整手册。开发已经获准时，它根据手册继续实现，不等你再次问“下一步”，也不要求重新确认整份方案。未明确的实现方式或关键条件才需要补问。若你只想完成设计，则交付手册后停止。
+创作资料保存在 `.buddy/creator/`。新项目须完成四册、小挂件清单、当前原型和设计验收，并通过交付校验，Skill 才返回 `directive=creator_complete` 和有效的 `completion.manualPath`；明确确认不使用小挂件时无需制造原型，旧项目按 Skill 版本规则接续。完整创建任务中，当前 Coding Agent 退出采访，在同一轮重新读取 `HANDOFF.md`、完整手册及小挂件设计与验收产物，自动开始开发，无需再说“继续”。四册确认或手册文件存在不能单独触发开发。只有影响实现的关键缺口才补问；仅设计、流程测试和暂停仍遵守原范围。
 
 手册中的角色、方法、处理路径和持续服务要求，都是开发依据。Coding Agent 按这些要求判断是否需要工具、专业方法、特定处理步骤、记忆与历史整理，技术选择不逐项交给开发者；完成后向开发者简要说明需求来源、实现位置、检查结果和缺口，不要求额外生成 README。已经明确的直接做，不能实现的如实说明；只有元数据或默认配置，不代表手册要求已经完成。
 
@@ -210,7 +217,7 @@ Creator 例外保留首次创作背景快照，用于接续同一作品；恢复
 buddy-cli models
 ```
 
-CLI 调用 `GET /cli/models` 查询 ID 列表。选择其中一个，写进现有 `buddy.agent.json`；例如平台确实返回了 `deepseek-v4-pro` 时，官方工程可以是：
+CLI 本地列出 `kimi-k2.6`、`kimi-k3`、`deepseek-v4-flash`、`deepseek-v4-pro`，无需登录、联网或先创建工程。脚本可用 `buddy-cli models --json`。选择一个写进现有 `buddy.agent.json`，例如：
 
 ```json
 {
@@ -221,9 +228,9 @@ CLI 调用 `GET /cli/models` 查询 ID 列表。选择其中一个，写进现
 }
 ```
 
-其他身份和工程字段要保留，不要整份替换配置。重启开发会话后，主回复固定使用这个模型；新 Runtime 不会自动做 Memory 提炼。
+其他身份和工程字段要保留，不要整份替换配置。模板的会话工厂读取 `model` 并放入 `initialState.model`，重启后生效。自定义工厂也可按会话选择受支持模型。
 
-接口没有声明平台默认项。省略 `model` 会沿用当前接入代码的 `kimi-k2.6`；不可用时返回错误，不自动换模型。列表也不等于上游服务实时健康检查。
+省略 `model` 时模板使用 `kimi-k2.6`；不可用时返回错误，不自动换模型。列表也不等于上游服务实时健康检查。
 
 官方 Runtime 统一通过平台代理调用选定模型，不把外部模型密钥带进项目。
 
@@ -243,24 +250,11 @@ CLI 调用 `GET /cli/models` 查询 ID 列表。选择其中一个，写进现
 }
 ```
 
-| ID | 数据 |
-| --- | --- |
-| `health.sleep` | 睡眠 |
-| `health.workouts` | 运动记录 |
-| `health.distance` | 运动距离与配速 |
-| `health.heartRate` | 心率 |
-| `health.hrv` | 心率变异性 |
-| `health.respiratoryRate` | 呼吸频率 |
-| `health.oxygenSaturation` | 血氧饱和度 |
-| `health.environmentalAudioExposure` | 环境音量 |
+完整选项以工程目录运行 `buddy-cli datasets` 的输出为准；脚本可加 `--json`。目录由安装的 Runtime 提供，Runtime 0.10.0 包含 HealthKit 与小红书两类，共 10 项。
 
 CLI 校验声明，并把清单原样放入源码包。服务端从包中解析申请清单、绑定版本，以及 App 展示和取得用户授权的流程仍需接入；当前 CLI 不会额外调用接口修改平台权限。工程中的声明不代表用户已经授权，也不会自动启用查询工具。
 
-`src/buddy.mjs` 通过 `platformTools: ["data_access_query"]` 把通用查询工具开放给模型，或在业务工具中调用 `conversation.dataAccess.query()`。Runtime 0.7.0 仍从平台读取已生效的数据声明，不直接读取本地 `datasets`；平台按声明和用户授权检查具体访问。
-
-### 已有工程升级到 CLI 0.2
-
-新清单不接受 `runtime` 字段。已有工程需要移除该字段，并在需要时填写 `datasets`。旧模板生成的 `start.mjs` 还包含 `config.runtime?.language !== "node"` 检查，需要同时移除这项条件。其他启动逻辑和业务实现保留；`init` 不覆盖已有启动文件。只有 JSON、没有实际入口文件的项目仍不能运行 `dev`、`preview` 或 `push`。
+`start.mjs` 将 `config.datasets ?? []` 传给 `BuddyServer.start` 的 `dataRequirements`。模型通过 `data_access_query` 查询，通过 `data_access_request` 发授权卡；HealthKit 授权后重查 Dataset，位置和日历用 `data_access_read_result` 读取一次性结果。业务代码使用 `conversation.dataAccess.query/request/readResult`。Runtime 随实际业务请求携带完整声明，Server 校验用户权限；上传包解析与发布版本绑定仍待实现。
 
 ## 在模拟器里聊一次
 
@@ -295,16 +289,16 @@ Preview 展示平台对话记录、发送与流式输出耗时、会话状态和
 
 ### 什么时候需要另一个服务地址
 
-不配置时，所有命令使用上述默认 test 地址。覆盖顺序如下：
+需要平台连接的命令默认使用上述 test 地址。`models` 和 `datasets` 读取本地目录，不使用平台地址。覆盖顺序如下：
 
 | 命令 | 地址优先级（从高到低） |
 | --- | --- |
-| `login`、`init`、`logout`、`models`、`push`、`status` | `BUDDY_APP_SERVER_URL` → `BUDDY_DEV_APP_SERVER_URL` → 默认 test |
+| `login`、`init`、`logout`、`push`、`status` | `BUDDY_APP_SERVER_URL` → `BUDDY_DEV_APP_SERVER_URL` → 默认 test |
 | `dev`、`preview` | `--app-server` → `BUDDY_DEV_APP_SERVER_URL` → `BUDDY_APP_SERVER_URL` → 默认 test |
 
 `BUDDY_DEV_APP_SERVER_URL` 保留为开发会话的专用覆盖。如果希望所有命令连接同一环境，只配置 `BUDDY_APP_SERVER_URL` 即可。
 
-这些是地址配置选项，不表示开发版搭子一定运行在另一套域名或独立数据库里。`models`、`init` 和 `push` 使用平台地址；如果特意配置了不同服务器，需要确认查询的模型和搭子属于目标服务器。除固定 test 入口外，远程服务必须使用 HTTPS；本机 loopback 仍允许 HTTP。
+这些是地址配置选项，不表示开发版搭子一定运行在另一套域名或独立数据库里。如果特意配置了不同服务器，需要确认搭子属于目标服务器，且该服务器已开放所选模型。除固定 test 入口外，远程服务必须使用 HTTPS；本机 loopback 仍允许 HTTP。
 
 ## 上传程序包，不等于发布
 
@@ -321,8 +315,8 @@ CLI 不提供 `release`、`publish`、`disable`、`enable` 或 `unpublish`。最
 
 ### 上传前检查
 
-- 必须包含非空且不超过 64 KiB 的 `agent.md`、业务入口 `src/buddy.mjs`、`start.mjs`，以及 `scripts.start` 为 `node start.mjs`、在 dependencies 中声明准确 Runtime 版本的 `package.json`。
-- 保留一份有效的依赖锁文件（`package-lock.json`、`pnpm-lock.yaml` 或 `yarn.lock`），并确保 `src/buddy.mjs` 与它引用的业务源码实际进入程序包。模板恢复会沿用已有锁文件，不另加一份 npm 锁文件。
+- 必须包含非空且不超过 64 KiB 的 `agent.md`、业务入口 `src/buddy-options.mjs`、`start.mjs`，以及 `scripts.start` 为 `node start.mjs`、在 dependencies 中声明准确 Runtime 版本的 `package.json`。
+- 保留一份有效的依赖锁文件（`package-lock.json`、`pnpm-lock.yaml` 或 `yarn.lock`），并确保 `src/buddy-options.mjs` 与它引用的业务源码实际进入程序包。模板恢复会沿用已有锁文件，不另加一份 npm 锁文件。
 - `.buddy/`、依赖安装目录、常见凭据文件和私钥不会进入包。默认排除包括 `.env`、`.env.*`（含示例）、`*.env`、`.envrc`、`.npmrc`、`.yarnrc`、`.yarnrc.yml`，以及 `.ssh`、`.aws` 等目录；完整规则见 [打包实现](../../packages/cli-core/src/push/preflight.ts)。
 - 排除不依赖 Git，也不继承 `.gitignore`。放进 Git 忽略列表，不代表不会上传。
 - 源码包只收录文件，不保留空目录；`src/tools/`、`src/hooks/`、`src/services/`、`resources/` 和 `widgets/` 有实际文件后会正常收录，不需要占位文件。
@@ -346,4 +340,27 @@ CLI 不提供 `release`、`publish`、`disable`、`enable` 或 `unpublish`。最
 
 维护者可在仓库根目录执行 `npm run verify:package`。它验证 npm 安装、初始化、模板启动和消息链路，MLB 与模型使用测试替身。
 
-`BUDDY_CLI_MOCK_CLOUD=1` 仅用于初始化交互测试，会产生明确标记的 `b_mock_*` 身份。它不提供真实模型目录、push 或 status，不能用来判断平台已打通。
+`BUDDY_CLI_MOCK_CLOUD=1` 仅用于初始化交互测试，会产生明确标记的 `b_mock_*` 身份。它不提供真实 push 或 status，不能用来判断平台已打通。模型命令在此模式下仍读取同一份本地目录。
+
+
+## 小挂件设计落地检查
+
+已完成 Creator 设计的项目在开发阶段执行 `buddy-cli widgets sync`，把当前验收版本绑定到工程；填写每类的实际类型、数据字段和创建／更新／展示代码路径后运行 `buddy-cli widgets check --json`。
+
+对照实际 H5 与原型核对首次、补充、更新后三态，保存观察和证据，再执行 `buddy-cli widgets verify --id <设计ID> --evidence .buddy/evidence/<设计ID>.json`。代码变化会让旧记录失效。DEV 允许调试并显示缺项；push 会在上传前拦截遗漏、过期或尚未核对的交付。
+
+这些命令不自动证明视觉一致、不替开发者验收，也不发起上传或发布。完整格式与兼容规则见仓库 `docs/widgets/design-delivery.md`；CLI 创建接续说明也包含此流程。
+## 查看数据集，不依赖 Coding Agent
+
+先按工程锁文件安装 Runtime，再执行：
+
+```bash
+buddy-cli datasets
+buddy-cli datasets --directory ./my-buddy --json
+```
+
+目录直接来自当前工程 Runtime 的 `DATA_ACCESS_CAPABILITIES`，包括 ID、名称、来源和 Schema 版本。普通输出供开发者阅读，JSON 返回 `runtimeVersion` 和 `datasets` 数组供脚本处理。命令不登录、不启动搭子、不申请权限，也不修改配置；从子目录运行会向上找到工程。
+
+开发者将实际选择的 ID 和用途写进 `buddy.agent.json.datasets`。JSON Schema 检查形状与用途；DEV 和非空数据声明的上传预检按工程安装的 Runtime 检查 ID。目录缺失、依赖未安装或版本不匹配时明确报错。Runtime 0.10.0 有 10 项，但单次数据查询仍最多 8 项。
+
+Preview 文本发送采用 App WebSocket 的 `messages` 数组，并校验逐项回执。`ask_question` 的全部选项以文字显示，开发者直接回复选择；权限卡提示到搭搭 App 处理，浏览器不模拟系统授权。