@my-life-buddies/cli 0.15.0 → 0.16.0

package/README.md

@@ -93,7 +93,7 @@ CLI 会把换取到的会话保存到 macOS Keychain。有效会话会复用，
 | `models` | 不需要，也不登录 | 始终联网读取 npm 最新 Runtime 的模型目录，提示工程版本差异；支持 `--directory`、`--json` |
 | `init` | 目标目录可以是空目录或已有官方工程 | 登记或恢复云端身份，准备本地文件 |
 | `dev`、`preview`、`push` | 需要有效清单和完整工程文件 | 运行、调试或打包该工程 |
-| `status` | 需要含 `buddyId` 的 `buddy.agent.json` | 查询该搭子的云端状态；创作尚未完成时也可使用 |
+| `status` | 需要含 `buddyId` 的 `package.json` | 查询该搭子的云端状态；创作尚未完成时也可使用 |
 | `avatar` | 从工程读取身份，或用 `--buddy-id` 指定 | 上传本地图片或清除搭子头像，保留其他资料；无需 Runtime |
 | `datasets` | 不需要，也不登录 | 与 models 使用同一 Runtime 来源，读取它的数据目录；支持 `--directory`、`--json` |
 
@@ -105,9 +105,9 @@ CLI 会把换取到的会话保存到 macOS Keychain。有效会话会复用，
 
 ## 登记前，先确认资料和头像
 
-`init --mode create` 和 `init --mode direct` 都先保存本地资料草稿。Coding Agent 读取 CLI 返回的 `.buddy/meta/HANDOFF.md`，完整读取独立下载的 `avatar-creator-skill/SKILL.md` 和配套规范，用宿主图片生成能力生成、检查并展示头像。开发者确认实际头像及名称、一句话介绍、详细介绍后，才调用 Meta 创建接口。
+`init --mode create` 和 `init --mode direct` 都先保存本地资料草稿。Coding Agent 读取 CLI 返回的 `.buddy/meta/HANDOFF.md`，完整读取独立下载的 `@my-life-buddies/avatar-creator-skill/SKILL.md` 和配套规范，用宿主图片生成能力生成、检查并展示头像。开发者确认实际头像及名称、一句话介绍、详细介绍后，才调用 Meta 创建接口。
 
-只有需要生成头像时才下载 `avatar-creator-skill`，本地缓存位于 `~/.cache/buddy-cli/avatar-skills/<版本>/`，同一次头像创作由 `.buddy/meta/skill-lock.json` 固定版本。已有候选图片、`--avatar` 指定图片及上传重试不需要加载生成 Skill。显式传入 `--avatar-skill-version 1.0.0` 可在未完成的头像准备流程中选择准确版本；这不会删除或重画已有候选图片。宿主图片生成工具仍负责实际生图，CLI 负责确认与上传。
+只有需要生成头像时才下载 `@my-life-buddies/avatar-creator-skill`，本地缓存位于 `~/.cache/buddy-cli/avatar-skills/my-life-buddies/<版本>/`，同一次头像创作由 `.buddy/meta/skill-lock.json` 固定版本。已有候选图片、`--avatar` 指定图片及上传重试不需要加载生成 Skill。显式传入 `--avatar-skill-version 1.0.0` 可在未完成的头像准备流程中选择准确版本；这不会删除或重画已有候选图片。宿主图片生成工具仍负责实际生图，CLI 负责确认与上传。
 
 Skill 维护者可本地联调（无需发布）：
 
@@ -151,10 +151,10 @@ CLI 只生成工程骨架，不分析手册或自动生成业务代码，也不
 
 ```text
 study-buddy/
-├── buddy.agent.json       平台 buddyId、模型与数据需求
+├── package.json           顶层 buddyId、npm 依赖与启动命令
 ├── agent.md               应用 Prompt，只包含自然语言
 ├── start.mjs              本地和云端共用的启动入口
-├── package.json           包含 npm start
+├── data-access.json       数据集 ID 和用途声明
 ├── package-lock.json      依赖锁文件
 ├── src/
 │   ├── buddy-options.mjs  BuddyFactory，组装工具与回合钩子
@@ -221,15 +221,10 @@ Runtime 0.12.2 的小挂件工具按操作区分：
 `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";
 
-const config = JSON.parse(readFileSync(new URL("./buddy.agent.json", import.meta.url), "utf8"));
-await BuddyServer.start({
-  dataRequirements: config.datasets ?? [],
-  buddy: createBuddyOptions,
-});
+await BuddyServer.start(createBuddyOptions);
 ```
 
 工程在 `package.json` 声明准确 Runtime 版本，锁文件固定依赖；上传不包含 `node_modules` 或 Runtime 打包副本，部署执行同一份 `npm start`。首次生成 package.json 和 package-lock.json 时查询公共 npm latest，生成准确版本与锁文件。查询或锁文件生成失败时停止，不回退内置旧版本。已有工程再次初始化时保留其依赖；安装验收直接从公共 npm 安装。
@@ -259,7 +254,7 @@ buddy-cli init --mode create --directory ./study-buddy \
          → 基础技术自测 → 打开真实预览 → 开发者体验并反馈
 ```
 
-CLI 0.15.0 起，Creator 使用独立 npm 包 `@my-life-buddies/creator-skill`。新项目首次创作查询稳定版，校验后缓存到 `~/.cache/buddy-cli/creator-skills/<版本>/`，在 `.buddy/creator/skill-lock.json` 记录准确版本与完整性摘要。恢复项目优先使用固定版本缓存，不自动升级，已有缓存时 Skill 准备无需联网（平台身份校验仍需联网）。Skill 负责人独立发包，不再要求重发 CLI。
+CLI 0.15.0 起，Creator 使用独立 npm 包 `@my-life-buddies/buddy-creator-skill`。新项目首次创作查询稳定版，校验后缓存到 `~/.cache/buddy-cli/creator-skills/buddy-creator-skill/<版本>/`，在 `.buddy/creator/skill-lock.json` 记录准确版本与完整性摘要。恢复项目优先使用固定版本缓存，不自动升级，已有缓存时 Skill 准备无需联网（平台身份校验仍需联网）。Skill 负责人独立发包，不再要求重发 CLI。
 
 显式升级某个项目：
 
@@ -288,9 +283,9 @@ BUDDY_CREATOR_SKILL_PATH=/absolute/path/buddy-creator-skill \
 buddy-cli init --mode direct --directory ./study-buddy
 ```
 
-创作阶段的 `buddy.agent.json` 只有 `schemaVersion` 和 `buddyId`；CLI 用它从平台读取最新资料并重新校验归属，不另建搭子。创作中断后可以在原目录重试 `--mode create`，继续使用原作品；手册完成后执行 `--mode direct`，在保留已有模型和数据选择的前提下补齐工程文件，并为尚未填写的数据需求写入空数组。旧 `--mode interview` 已停止使用。
+创作阶段的 `package.json` 只有顶层 `buddyId`；CLI 用它从平台读取最新资料并重新校验归属，不另建搭子。创作中断后可以在原目录重试 `--mode create`，继续使用原作品；手册完成后执行 `--mode direct`，保留已有业务代码与数据声明，补齐 npm 字段和缺失的工程文件；缺失 `data-access.json` 时生成空 requirements 数组。旧 `--mode interview` 已停止使用。
 
-两条主线都遵循同一个登记规则：名称、`tagline`（一句话介绍）、`intro`（完整介绍）先同步到平台，返回的 ID 写入 `buddy.agent.json.buddyId`。公开资料不在本地留副本。若平台已创建成功、本地写盘失败，可用 `--buddy-id <平台返回的 ID>` 恢复；它不是自定义 ID 的入口。
+两条主线都遵循同一个登记规则：名称、`tagline`（一句话介绍）、`intro`（完整介绍）先同步到平台，返回的 ID 写入 `package.json.buddyId`。公开资料不在本地留副本。若平台已创建成功、本地写盘失败，可用 `--buddy-id <平台返回的 ID>` 恢复；它不是自定义 ID 的入口。
 
 Creator 例外保留首次创作背景快照，用于接续同一作品；恢复时使用它校验接续说明，云端后来修改名称或介绍不会因此阻断创作，也不会被首次快照覆盖。
 
@@ -315,7 +310,7 @@ buddy-cli avatar --clear
 
 `--file` 与 `--clear` 二选一。支持静态 PNG、JPEG、WebP，最大 5 MiB。Server 校验图片并裁剪成 512 × 512 WebP，生成头像地址；CLI 不再提供 `--url`。服务端处理失败时保留原头像。
 
-命令默认向上寻找 `buddy.agent.json`，可用 `--directory ./my-buddy` 指定工程；图片路径始终相对执行命令的当前目录。创作阶段只有身份清单时也能使用，无需安装 Runtime。工程外可直接指定平台 ID：
+命令默认向上寻找 `package.json`，可用 `--directory ./my-buddy` 指定工程；图片路径始终相对执行命令的当前目录。创作阶段只有身份清单时也能使用，无需安装 Runtime。工程外可直接指定平台 ID：
 
 ```bash
 buddy-cli avatar --buddy-id b_example --file ./avatar.png
@@ -337,44 +332,36 @@ buddy-cli models
 
 此限制由本版 CLI 执行，不修改服务端策略或已部署进程；直接运行工程 `npm start`、旧 CLI 或服务端发布入口不受本版 CLI 检查约束。
 
-选择一个写进现有 `buddy.agent.json`，例如：
+将选定的模型直接写进 `src/buddy-options.mjs` 返回值的 `initialState.model`：
 
-```json
-{
-  "schemaVersion": 1,
-  "buddyId": "平台返回的搭子 ID",
-  "model": "deepseek-v4-pro",
-  "datasets": []
+```js
+initialState: {
+  model: "deepseek-v4-pro",
+  systemPrompt,
+  tools: [],
 }
 ```
 
-其他身份和工程字段要保留，不要整份替换配置。模板的会话工厂读取 `model` 并放入 `initialState.model`，重启后生效。自定义工厂也可按会话选择受支持模型。
-
-省略 `model` 时模板使用 `kimi-k2.6`；不可用时返回错误，不自动换模型。列表也不等于上游服务实时健康检查。
-
-官方 Runtime 统一通过平台代理调用选定模型，不把外部模型密钥带进项目。
+模板默认生成 `kimi-k2.6`，后续可直接修改业务代码；自定义工厂也可按会话选择受支持模型。CLI 不执行业务工厂来推断模型；模型有效性由 Runtime 在创建会话时检查。模型不可用时返回错误，不自动换模型。目录不代表上游实时健康状态。官方 Runtime 通过平台代理调用模型，工程不保存外部模型密钥。
 
 ## 声明这个搭子需要的数据
 
-在 `buddy.agent.json` 的 `datasets` 中声明数据集及用途。新工程默认 `[]`；省略该字段也表示不申请数据。每个 ID 只能出现一次，`purpose` 是展示给用户的用途说明，必须包含非空白内容，最多 200 字。
+在工程根目录 `data-access.json` 的 `requirements` 中声明数据集及用途：
 
 ```json
 {
-  "schemaVersion": 1,
-  "buddyId": "b_example",
-  "model": "kimi-k2.6",
-  "datasets": [
+  "requirements": [
     { "id": "health.sleep", "purpose": "根据最近睡眠调整作息建议" },
     { "id": "health.workouts", "purpose": "结合运动记录安排训练和恢复" }
   ]
 }
 ```
 
-完整选项以工程目录运行 `buddy-cli datasets` 的输出为准；脚本可加 `--json`。目录由 npm 最新 Runtime 提供，具体条目以查询结果为准；使用新版条目前需完成工程升级与适配。
+新工程生成 `{ "requirements": [] }`。最多 32 项，ID 不能重复；`id`、`purpose` 会去除首尾空白，用途必须为 1～200 字。完整选项由 `buddy-cli datasets [--json]` 从 npm 最新 Runtime 读取，DEV 与 push 使用工程安装的 SDK 校验 ID。
 
-CLI 校验声明，并把清单原样放入源码包。服务端从包中解析申请清单、绑定版本，以及 App 展示和取得用户授权的流程仍需接入；当前 CLI 不会额外调用接口修改平台权限。工程中的声明不代表用户已经授权，也不会自动启用查询工具。
+Runtime 0.17.0 启动时自动读取该文件，通过 `PUT /internal/v1/data-access/requirements` 登记；文件缺失或空数组会上传空声明，清除旧声明。登记失败阻止启动，不会带着未同步的配置上线。DEV 监听该文件，保存后重启 Runtime 并重新登记。部署环境需提供对应登记接口。
 
-`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 校验用户权限；上传包解析与发布版本绑定仍待实现。
+CLI 将文件原样放入源码包，启动入口只调用 `BuddyServer.start(createBuddyOptions)`。声明不代表用户已授权，也不会自动启用工具。模型查询需要注册 `data_access_query`；HealthKit 授权后重新查询，位置和日历使用一次性授权与 `data_access_read_result`，不放进 `requirements`。
 
 ## 在模拟器里聊一次
 
@@ -393,7 +380,7 @@ buddy-cli preview --directory ./study-buddy
 
 `dev` 启动本地 Agent 并连接 MLB；`preview` 连接当前工程并打开对应搭子的创造者后台「开发调试」，等待开发者在后台启动 DEV。本地进程准备好之后，CLI 通过平台通知接收消息，不需要公网隧道。
 
-平台身份保存在 `buddy.agent.json.buddyId`，模拟器访问的是对应的 `<buddyId>-dev`。MLB 决定当前账号是否可以访问这只开发版搭子。不要把本地 `buddyId` 改成 `-dev`，也不需要传 `x-mlb-dev`。
+平台身份保存在 `package.json.buddyId`，模拟器访问的是对应的 `<buddyId>-dev`。MLB 决定当前账号是否可以访问这只开发版搭子。不要把本地 `buddyId` 改成 `-dev`，也不需要传 `x-mlb-dev`。
 
 打开模拟器就会查询 `GET /app/buddies/:buddyId`，不必先启动 DEV。名称来自云端资料，预览标识来自服务端 `isDev`；详情查询不会添加搭子或触发欢迎。
 
@@ -433,7 +420,7 @@ buddy-cli push --directory ./study-buddy --commit "根据完成情况调整练
 buddy-cli status --directory ./study-buddy
 ```
 
-`push` 收集 `buddy.agent.json`、源码和依赖锁文件，生成 `tar.gz`，上传到 `/cli/buddies/:id/packages/push`。`commit` 是改动说明，与本地 Git 是否提交无关。版本由 MLB 返回，CLI 不上传自己生成的 tag 或提审时间戳。
+`push` 收集包含顶层 `buddyId` 的 `package.json`、`data-access.json`、源码和依赖锁文件，生成 `tar.gz`，上传到 `/cli/buddies/:id/packages/push`。`commit` 是改动说明，与本地 Git 是否提交无关。版本由 MLB 返回，CLI 不上传自己生成的 tag 或提审时间戳。
 
 审核状态以平台响应为准，可能已经是 `approved`，不能仅因命令名叫“提审”就假定一定进入等待审核。`status` 查询搭子资料和最近 5 次程序包记录，显示线上版本、运行状态、审核结果及说明。
 
@@ -441,7 +428,7 @@ CLI 不提供 `release`、`publish`、`disable`、`enable` 或 `unpublish`。最
 
 ### 上传前检查
 
-- 必须包含非空且不超过 64 KiB 的 `agent.md`、业务入口 `src/buddy-options.mjs`、`start.mjs`，以及 `scripts.start` 为 `node --env-file-if-exists=.env start.mjs`（0.16.0 及以上 Runtime）、在 dependencies 中声明准确 Runtime 版本的 `package.json`。
+- 必须包含非空且不超过 64 KiB 的 `agent.md`、业务入口 `src/buddy-options.mjs`、`start.mjs`，以及 `scripts.start` 为 `node --env-file-if-exists=.env start.mjs`（0.17.0 及以上 Runtime）、在 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 忽略列表，不代表不会上传。
@@ -486,7 +473,7 @@ buddy-cli datasets --directory ./my-buddy --json
 
 目录来自 npm 最新 Runtime 的 `DATA_ACCESS_CAPABILITIES`，包括 ID、名称、来源和 Schema 版本。JSON 返回版本信息、适配状态和 `datasets` 数组（字段见上方模型目录说明）。命令不登录、不启动搭子、不申请权限，也不修改配置；从子目录运行会向上找到工程。每次都需要联网检查 latest，下载失败时明确报错，不把旧缓存称为最新版。
 
-开发者将实际选择的 ID 和用途写进 `buddy.agent.json.datasets`。JSON Schema 检查形状与用途；DEV 和上传预检按工程安装的 Runtime 检查所选模型与非空数据声明。目录缺失、依赖未安装或版本不匹配时明确报错。Runtime 0.12.2 有 10 项，但单次数据查询仍最多 8 项。
+开发者将实际选择的 ID 和用途写进 `data-access.json.requirements`。JSON Schema 检查形状与用途；DEV 和上传预检按工程安装的 Runtime 检查所选模型与非空数据声明。目录缺失、依赖未安装或版本不匹配时明确报错。Runtime 0.12.2 有 10 项，但单次数据查询仍最多 8 项。
 
 Preview 文本发送采用 App WebSocket 的 `messages` 数组，并校验逐项回执。`ask_question` 的全部选项以文字显示，开发者直接回复选择；权限卡提示到搭搭 App 处理，浏览器不模拟系统授权。
 
@@ -500,8 +487,18 @@ CLI 0.14.1 起，开发 Token 优先从工程 `.env` 读取；首次启动时可
 
 账号登录凭据仍保存在 macOS Keychain，不写入工程。开发 Token 保存在权限为 `0600` 的工程 `.env`，不传给 Web，也不进入上传包或命令行参数。
 
-### Runtime 0.16.0 本地配置
+### Runtime 0.17.0 本地配置
 
 首次启动 DEV 时，CLI 将 `BUDDY_ID`、开发版 `BUDDY_TOKEN` 和 `MLB_GATEWAY_URL` 写入工程 `.env`，保留其他配置和注释。后续优先复用；`--refresh-token` 重新领取后更新此文件。开发者登录凭据仍使用系统凭据存储。`.env` 加入 Git 忽略，且始终排除在上传包之外。
 
 CLI、Preview 与标准 `npm start` 均由 Node 的 `--env-file-if-exists=.env` 加载本地配置，Runtime 自行读取环境变量；托管时平台注入的同名环境变量优先。已有工程显式升级 Runtime 后，CLI 只自动迁移能精确识别的生成入口及标准启动命令，自定义业务代码和脚本保留。
+
+### CLI 0.15.1 的 Skill 包名
+
+Creator 使用 `@my-life-buddies/buddy-creator-skill`，头像使用 `@my-life-buddies/avatar-creator-skill`。缓存按新包名分别保存；本次不提供旧包或旧锁文件迁移。
+
+### CLI 0.16 工程配置
+
+新工程以 `package.json.buddyId` 作为唯一工程绑定，不生成 `buddy.agent.json`，也不需要工程配置的 `schemaVersion`。创建阶段先保存 `{ "buddyId": "平台返回的 ID" }`，生成代码时在同一文件补齐 npm 字段，不覆盖已有工程配置。模型直接维护在业务工厂中，数据声明独立放在 `data-access.json`。本次不提供旧工程自动迁移。
+
+本地 CLI 校验绑定与 `.env.BUDDY_ID`，准备开发凭据；托管身份由 MLB Server 注入环境变量。生成的 `start.mjs` 不读取 `package.json` 或比较 ID。Server 对包中 ID 的部署校验由 Server 实现，CLI 不代替服务端鉴权。