@my-life-buddies/cli 0.3.0 → 0.5.0

package/README.md

@@ -2,11 +2,13 @@
 
 这份说明按一次开发过程展开：登记搭子，准备工程，在本地预览，然后上传程序包。所有搭子统一使用 `@my-life-buddies/buddy-runtime`，业务能力通过 Prompt、`src/buddy-options.mjs` 和 Tool 实现。
 
+工程模板已锁定公共 npm 的 Runtime `0.11.0`，本批接口变化与联调范围见 [Runtime 集成说明](../../docs/runtime-integration.md)。
+
 ## 准备 CLI 和平台地址
 
 目前只支持 macOS，要求 Node.js 24 或更新版本。
 
-当前 CLI 工程版本为 `0.2.2`，发布到公共 Registry `https://registry.npmjs.org/`。已有仓库源码时，在仓库根目录运行：
+当前 CLI 工程版本为 `0.5.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` 补齐缺失的模板文件，已有文件不会被覆盖。
 
@@ -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-options.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,26 @@ CLI 将 HTML 和 Schema 随工程源码打包。模板锁定的 Runtime `0.7.0`
 你是学习搭子。先了解学习目标，再给一个今天能完成的练习；不要编造用户过去的学习记录。
 ```
 
-要增加业务 Tool 时，在 `src/buddy-options.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-options.mjs` 负责业务配置。启动文件通过以下方式接入组装器：
 
 ```js
+import { readFileSync } from "node:fs";
 import { BuddyServer } from "@my-life-buddies/buddy-runtime";
 import createBuddyOptions from "./src/buddy-options.mjs";
 
-await BuddyServer.start({ model, buddy: createBuddyOptions });
+const config = JSON.parse(readFileSync(new URL("./buddy.agent.json", import.meta.url), "utf8"));
+await BuddyServer.start({
+  buddyId: process.env.BUDDY_ID,
+  token: process.env.BUDDY_TOKEN,
+  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.11.0`，安装验收直接从公共 npm 安装，不替换依赖。
 
 ## 想法还模糊时，先梳理需求
 
@@ -211,7 +222,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
 {
@@ -222,9 +233,9 @@ CLI 调用 `GET /cli/models` 查询 ID 列表。选择其中一个，写进现
 }
 ```
 
-其他身份和工程字段要保留，不要整份替换配置。重启开发会话后，主回复固定使用这个模型；新 Runtime 不会自动做 Memory 提炼。
+其他身份和工程字段要保留，不要整份替换配置。模板的会话工厂读取 `model` 并放入 `initialState.model`，重启后生效。自定义工厂也可按会话选择受支持模型。
 
-接口没有声明平台默认项。省略 `model` 会沿用当前接入代码的 `kimi-k2.6`；不可用时返回错误，不自动换模型。列表也不等于上游服务实时健康检查。
+省略 `model` 时模板使用 `kimi-k2.6`；不可用时返回错误，不自动换模型。列表也不等于上游服务实时健康检查。
 
 官方 Runtime 统一通过平台代理调用选定模型，不把外部模型密钥带进项目。
 
@@ -244,24 +255,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.11.0 包含 HealthKit 与小红书两类，共 10 项。
 
 CLI 校验声明，并把清单原样放入源码包。服务端从包中解析申请清单、绑定版本，以及 App 展示和取得用户授权的流程仍需接入；当前 CLI 不会额外调用接口修改平台权限。工程中的声明不代表用户已经授权，也不会自动启用查询工具。
 
-`src/buddy-options.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 校验用户权限；上传包解析与发布版本绑定仍待实现。
 
 ## 在模拟器里聊一次
 
@@ -296,16 +294,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。
 
 ## 上传程序包，不等于发布
 
@@ -336,8 +334,8 @@ CLI 不提供 `release`、`publish`、`disable`、`enable` 或 `unpublish`。最
 
 | 环境变量 | 作用 |
 | --- | --- |
-| `MLB_BUDDY_ID` | 平台部署的搭子身份，须与工程匹配 |
-| `MLB_BUDDY_TOKEN` | 连接 MLB 的 Buddy 凭据 |
+| `BUDDY_ID` | 平台部署的搭子身份，须与工程匹配 |
+| `BUDDY_TOKEN` | 连接 MLB 的 Buddy 凭据 |
 | `MLB_GATEWAY_URL` | 平台网关，由部署环境显式注入；未设置时沿用 Runtime 的默认地址 |
 
 这些值由部署环境提供，不写入提审包。云端安装工程声明的 Runtime 和业务依赖，执行 `npm start`，不需要安装 CLI。Runtime 主动连接网关事件流。
@@ -347,4 +345,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.11.0 有 10 项，但单次数据查询仍最多 8 项。
+
+Preview 文本发送采用 App WebSocket 的 `messages` 数组，并校验逐项回执。`ask_question` 的全部选项以文字显示，开发者直接回复选择；权限卡提示到搭搭 App 处理，浏览器不模拟系统授权。