@my-life-buddies/cli 0.27.1-dev.1 → 0.27.1

package/README.md

@@ -1,10 +1,10 @@
-# buddy-cli-sit 使用说明
+# buddy-cli 使用说明
 
-创作者提供的参考素材应在开发主体时同步接入。使用 `buddy-cli-sit knowledge sync --plan .buddy/knowledge/plan.json` 生成分章节 Markdown、可读目录和来源映射；源资料更新时保留手工修改。计划格式见 `buddy-cli-sit knowledge --help`，完整流程见[运行知识接入](../../docs/cli/knowledge.md)。本功能只写本地文件，不增加 push 检查或自动上传。
+创作者提供的参考素材应在开发主体时同步接入。使用 `buddy-cli knowledge sync --plan .buddy/knowledge/plan.json` 生成分章节 Markdown、可读目录和来源映射；源资料更新时保留手工修改。计划格式见 `buddy-cli knowledge --help`，完整流程见[运行知识接入](../../docs/cli/knowledge.md)。本功能只写本地文件，不增加 push 检查或自动上传。
 
 这份说明按一次开发过程展开：登记搭子，准备工程，在本地预览，然后上传程序包。所有搭子统一使用 `@my-life-buddies/buddy-runtime`，业务能力通过 Prompt、`src/buddy-options.mjs` 和 Tool 实现。
 
-空白工程模板不预置 Runtime 依赖或版本。新建工程统一查询公共 npm dev 最新 Runtime，并写入准确版本与锁文件，不提供版本选择；查询或锁文件生成失败时停止，不回退旧版本。版本策略与联调范围见 [Runtime 集成说明](../../docs/runtime-integration.md)。
+空白工程模板不预置 Runtime 依赖或版本。新建工程动态查询公共 npm 的最新稳定版 Runtime，并写入准确版本与锁文件；查询或锁文件生成失败时停止，不回退旧版本。版本选择与联调范围见 [Runtime 集成说明](../../docs/runtime-integration.md)。
 
 ## 准备 CLI 和平台地址
 
@@ -14,36 +14,21 @@ CLI 发布目标为公共 Registry `https://registry.npmjs.org/`。已有仓库
 
 ```bash
 npm install
-npm run buddy-cli-sit -- --help
+npm run buddy-cli -- --help
 ```
 
-下文统一使用 `buddy-cli-sit`。源码运行时替换为 `npm run buddy-cli-sit --`；从公共 npm 安装已发布版本：
-
-```bash
-npm install --global --prefix "$HOME/.local/share/buddy-cli/sit" @my-life-buddies/cli@dev --registry=https://registry.npmjs.org/
-export PATH="$HOME/.local/share/buddy-cli/sit/bin:$PATH"
-```
-
-### 与正式版共存
-
-只使用一个 npm 包名 `@my-life-buddies/cli`。`latest` 提供 `buddy-cli`（ECS Test）；`dev` 提供 `buddy-cli-sit`（SIT）。SIT 按上面的 `--prefix` 命令安装在独立目录；正式版可保留原有全局安装：
+下文统一使用 `buddy-cli`。源码运行时替换为 `npm run buddy-cli --`；从公共 npm 安装已发布版本：
 
 ```bash
 npm install --global @my-life-buddies/cli@latest --registry=https://registry.npmjs.org/
-buddy-cli --version
-buddy-cli-sit --version
 ```
 
-`--global --prefix` 只向指定目录安装包及命令，不覆盖系统默认全局目录。将 `export PATH="$HOME/.local/share/buddy-cli/sit/bin:$PATH"` 加入 `~/.zshrc`，新终端也可直接使用 SIT 命令。不要把两个渠道安装到同一个 prefix。
-
-已有 `@my-life-buddies/cli-dev` 的用户，先卸载该旧独立包（按原安装位置卸载），再按上面的命令安装 `@my-life-buddies/cli@dev`。不删除搭子工程或登录凭据。后续仅维护同一包的两个标签。
-
 ### 查看帮助与开发指引
 
 ```bash
-buddy-cli-sit --help
-buddy-cli-sit init --help
-buddy-cli-sit guide
+buddy-cli --help
+buddy-cli init --help
+buddy-cli guide
 ```
 
 `--help` 列出命令，`<命令> --help` 说明当前命令的参数、限制和示例。`guide` 输出 Coding Agent 的完整开发指引，包括创作开场、资料确认、Skill 接续、实现和交付规则；无需工程或登录，先联网自检并按需自动更新 CLI，再输出新版指引，不修改工程文件。让 Agent 开始工作前先读取 `guide`，再按 CLI 返回的 `HANDOFF.md` 继续当前工程。HANDOFF 只包含当前工程、Skill 路径和接续方式，通用规则以 guide 为准；已生成文件在正常恢复创作时校验、备份并更新，CLI 升级不会直接覆盖工程里的 HANDOFF。`guide --help` 只显示该命令的简短用法。
@@ -57,23 +42,23 @@ Agent 按已确认需求判断是否需要联网查资料。需求没有说明
 ### 查看版本和更新 CLI
 
 ```bash
-buddy-cli-sit --version
-buddy-cli-sit update --check
-buddy-cli-sit update
+buddy-cli --version
+buddy-cli update --check
+buddy-cli update
 ```
 
-`--version`（也可写作 `-v`）显示当前运行的 CLI 版本，无需联网。`update --check` 查询 `@my-life-buddies/cli` 的 npm `dev` 版本，只检查、不安装；`update` 有新版本时安装检查到的准确版本，完成后核验安装结果。版本相同或本机版本更高时不安装、不降级。这三个用法均无需登录搭搭账号或进入搭子工程，从 CLI 0.8.0 开始支持。旧版用户先用上面的 npm 命令升级。
+`--version`（也可写作 `-v`）显示当前运行的 CLI 版本，无需联网。`update --check` 查询公共 npm 的 `latest` 版本，只检查、不安装；`update` 有新版本时安装检查到的准确版本，完成后核验安装结果。版本相同或本机版本更高时不安装、不降级。这三个用法均无需登录搭搭账号或进入搭子工程，从 CLI 0.8.0 开始支持。旧版用户先用上面的 npm 命令升级。
 
-从 CLI 0.17.0 起，每条正常命令（含 `guide` 和无参数入口）先查询 CLI 的公共 npm `dev` 标签，当前版本落后时自动更新，并由新版执行原命令。无需手动先运行 `update`，等待当前命令完成即可。更新发生在创建工程、领取凭据、启动 DEV 或上传之前；保留参数、工作目录、终端输入输出和退出状态，一次调用最多自动切换一次。版本相同或更高时继续执行，不降级；已经运行的 DEV 不因新版本发布而中断。
+从 CLI 0.17.0 起，每条正常命令（含 `guide` 和无参数入口）先查询公共 npm `latest`，当前版本落后时自动更新，并由新版执行原命令。无需手动先运行 `update`，等待当前命令完成即可。更新发生在创建工程、领取凭据、启动 DEV 或上传之前；保留参数、工作目录、终端输入输出和退出状态，一次调用最多自动切换一次。版本相同或更高时继续执行，不降级；已经运行的 DEV 不因新版本发布而中断。
 
-全局安装及通过 `--global --prefix` 指定的独立安装，只更新当前正在运行的 CLI 所在目录，不依赖当前 npm 的默认 prefix，不改动另一个渠道的安装；源码、`npm link`、项目内安装和 `npx` 自动下载准确版本到 `~/.cache/buddy-cli-sit/updates/releases/`，从缓存运行，不改写原安装或工程依赖。并发更新共用安装锁。手动 `update` 支持这两种安装目录。查询最多等待 10 秒，安装（含重试）最多等待 180 秒。安装通过 `--prefer-online` 刷新 npm 版本缓存；找不到版本（`ETARGET`）时最多重试一次，始终安装本次自检查到的准确版本。仍失败时说明 npm 的具体原因，不展示日志路径，也不修改用户的 npm 配置或清空缓存；失败或取消时停止原业务命令，不回退旧版。帮助、各命令 `--help`、`--version` 和应急清理命令 `dev stop` 不联网更新。自动更新进度写入 stderr，不混入业务命令的 stdout 或 JSON；更新失败时 `--json` 返回 `code=CLI_UPDATE_FAILED` 和 `error`。
+全局安装更新当前 CLI 所在的目录（包括自定义 `--prefix`），不覆盖其他安装；源码、`npm link`、项目内安装和 `npx` 自动下载准确版本到 `~/.cache/buddy-cli/updates/releases/`，从缓存运行，不改写原安装或工程依赖。并发更新共用安装锁。手动 `update` 仍只用于 npm 全局安装。查询最多等待 10 秒，安装（含重试）最多等待 180 秒。安装通过 `--prefer-online` 刷新 npm 版本缓存；找不到版本（`ETARGET`）时最多重试一次，始终安装本次自检查到的准确版本。仍失败时说明 npm 的具体原因，不展示日志路径，也不修改用户的 npm 配置或清空缓存；失败或取消时停止原业务命令，不回退旧版。帮助、各命令 `--help`、`--version` 和应急清理命令 `dev stop` 不联网更新。自动更新进度写入 stderr，不混入业务命令的 stdout 或 JSON；更新失败时 `--json` 返回 `code=CLI_UPDATE_FAILED` 和 `error`。
 
 更新只针对 CLI，已有工程的 Runtime 依赖、锁文件和业务适配仍需另行修改与验证。旧 CLI 不会自动获得自检能力，需要先用 npm 安装命令升级一次。
 
 可追加 `--json` 供 Coding Agent 或脚本读取，例如：
 
 ```bash
-buddy-cli-sit update --check --json
+buddy-cli update --check --json
 ```
 
 检查结果包含 `package`、`currentVersion`、`latestVersion`、`updateAvailable` 和 `status`。`status` 为 `update_available`、`up_to_date` 或 `ahead`；更新成功时为 `updated`，另有 `installedVersion`，`updateAvailable` 为 `false`。失败时输出 `error`。检查成功（包括发现更新）返回退出码 0，查询或安装失败返回 1，参数错误返回 2。JSON 输出不会混入 npm 进度文字。
@@ -85,20 +70,22 @@ buddy-cli-sit update --check --json
 ```bash
 npm run release:check
 npm run release             # 完整验证与演练
-npm run release -- --publish # 显式发布当前 dev 分支到 npm dev
+npm run release -- --publish # 显式发包，PROD 验收记录为空时禁止发布
 ```
 
-`dev` 构建 `@my-life-buddies/cli@dev`，只包含 `buddy-cli-sit` 命令。版本必须是 `x.y.z-dev.N`；发布校验拒绝 latest 标签。main 用同一个包名发布 `latest` 正式版本，提供 `buddy-cli`；两个版本必须分目录安装才能共存，同一目录中安装会互相替换。Core 和 Preview 保留 monorepo 开发边界并标记为 `private`，构建时合入 CLI 的内部模块；Preview 页面和工程模板资源进入 CLI 包；Creator 与 Avatar Skill 使用时独立加载。安装不会请求 `@buddy/cli-core` 或 `@buddy/preview`。第三方运行依赖按正常 npm dependencies 安装，构建工具 esbuild 不进入安装依赖。根工作区标记为 `private`。
+流程、CHANGELOG、tag 和 dev 合入规则见 [维护者发布规则](../../docs/releases.md)。当前 PROD 候选尚未发布；发布前须完成实际 PROD 验收。
+
+`main` 构建正式的 `@my-life-buddies/cli@latest`，只包含 `buddy-cli` 命令。`publishConfig` 明确指定 `latest`、公共 npm 和 `public` 访问级别；构建会拒绝预发布版本。正式发布必须从 main 重新构建，不可将测试产物直接改挂 latest。Core 和 Preview 保留 monorepo 开发边界并标记为 `private`，构建时合入 CLI 的内部模块；Preview 页面和工程模板资源进入 CLI 包；Creator 与 Avatar Skill 使用时独立加载。安装不会请求 `@buddy/cli-core` 或 `@buddy/preview`。第三方运行依赖按正常 npm dependencies 安装，构建工具 esbuild 不进入安装依赖。根工作区标记为 `private`。
 
 版本维护：每批修改 CLI 发布内容时递增一次版本，默认 patch；根包和内部工作区版本、依赖引用、锁文件一起更新。Agent 工程自己的项目版本独立。Runtime 版本由创建时动态查询并锁定；发布前验证真实 Runtime 的动态解析和独立安装，不向空白模板写入基准版本。
 
-SIT CLI 固定连接 SIT `https://buddies.sit.dots.chat`，无需配置地址：
+正式版 CLI 固定连接 PROD `https://buddies.dots.chat`，无需配置地址：
 
 ```bash
-buddy-cli-sit login
+buddy-cli login
 ```
 
-这是实际的 SIT 环境，使用 HTTPS；不能改为其他平台或本机网关。手机 App 需要连接同一环境。
+这是实际的 PROD 环境，使用 HTTPS；不能改为其他平台或本机网关。手机 App 需要连接同一环境。
 
 CLI 会打开搭搭创作者平台网页完成登录和授权。浏览器已有有效 Cookie 时，页面直接显示当前账号，开发者确认后即可返回终端；没有登录时，先在同一网页完成短信登录，再确认授权。CLI 不读取浏览器 Cookie，也拿不到短信验证码，只通过本机回调收到一次性授权码，再换取自己的会话。
 
@@ -113,12 +100,10 @@ CLI 会把换取到的会话保存到 macOS Keychain。有效会话会复用，
 | `--version [--json]` | 不需要，也不登录 | 显示当前运行的 CLI 版本，无需联网 |
 | `update [--check] [--json]` | 不需要，也不登录 | 检查公共 npm 最新版，或更新 npm 全局 CLI |
 | `login`、`logout` | 不需要 | 管理账号会话 |
-| `models` | 不需要，也不登录 | 始终联网读取 npm dev 最新 Runtime 的模型目录，提示工程版本差异；支持 `--directory`、`--json` |
+| `models` | 不需要，也不登录 | 始终联网读取 npm 最新 Runtime 的模型目录，提示工程版本差异；支持 `--directory`、`--json` |
 | `init` | 目标目录可以是空目录或已有官方工程 | 登记或恢复云端身份，准备本地文件 |
 | `dev`、`preview`、`push` | 需要有效清单和完整工程文件 | 运行、调试或打包该工程 |
 | `status` | 需要含 `buddyId` 的 `package.json` | 查询该搭子的云端状态；创作尚未完成时也可使用 |
-| `products submit` | 需要含 `buddyId` 的 `package.json` | 对明确的已有搭子版本补提或单独提交选中商品 |
-| `release` | 需要含 `buddyId` 的 `package.json` | 从原上传／补提回执确认发布，或显式只发布代码；查询、恢复、重试和取消原发布任务 |
 | `avatar` | 从工程读取身份，或用 `--buddy-id` 指定 | 上传本地图片或清除搭子头像，保留其他资料；无需 Runtime |
 | `datasets` | 不需要，也不登录 | 与 models 使用同一 Runtime 来源，读取它的数据目录；支持 `--directory`、`--json` |
 
@@ -132,13 +117,13 @@ CLI 会把换取到的会话保存到 macOS Keychain。有效会话会复用，
 
 `init --mode create` 和 `init --mode direct` 都先保存本地资料草稿。Coding Agent 读取 CLI 返回的 `.buddy/meta/HANDOFF.md`，完整读取独立下载的 `@my-life-buddies/avatar-creator-skill/SKILL.md` 和配套规范，用宿主图片生成能力生成、检查并展示头像。开发者确认实际头像及名称、一句话介绍、详细介绍后，才调用 Meta 创建接口。
 
-只有需要生成头像时才下载 `@my-life-buddies/avatar-creator-skill`，本地缓存位于 `~/.cache/buddy-cli-sit/avatar-skills/my-life-buddies/<版本>/`，同一次头像创作由 `.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 维护者可本地联调（无需发布）：
 
 ```bash
 BUDDY_AVATAR_SKILL_PATH=/absolute/path/avatar-creator-skill \
-  buddy-cli-sit init --mode create --directory ./my-buddy
+  buddy-cli init --mode create --directory ./my-buddy
 ```
 
 本地来源会记录在头像 Skill 锁中；切回 npm 时清除环境变量，并显式传入 `--avatar-skill-version`。首次下载失败会保留草稿，可在同目录重试，也可提供已有图片完成登记。
@@ -147,14 +132,14 @@ BUDDY_AVATAR_SKILL_PATH=/absolute/path/avatar-creator-skill \
 普通终端不会执行 skill，也不要求安装 Coding Agent：选择本地图片后会打开资料与头像预览，再询问是否确认登记。没有图片或暂不确认时保留草稿，退出码为 2，稍后在原目录继续。
 
 ```bash
-buddy-cli-sit init --mode direct --directory "<搭子工程目录>" --avatar "<头像文件路径>"
+buddy-cli init --mode direct --directory "<搭子工程目录>" --avatar "<头像文件路径>"
 ```
 
 非交互调用必须由宿主先取得开发者明确确认，再传 `--avatar "<已确认图片路径>" --confirm-meta`。该标志声明开发者确认了本次资料和实际图片；不能把“帮我创建搭子”当作头像确认。CLI 不生成图片、不推断对话授权，也不以示例图替代新头像。
 
 `.buddy/meta/` 保存草稿、候选图片、预览与接续说明，push 不上传。上传失败保留已创建的 buddyId，重试复用原身份；已有云端头像不会在恢复中被覆盖。Meta 创建响应丢失时会明确暂停，核对后台身份后用 `--buddy-id` 恢复，避免重复创建。
 
-基础资料和头像的确认不等于 Creator 需求手册已确认。已有搭子的恢复沿用原身份和云端头像；明确需要更换头像时使用 `buddy-cli-sit meta update --avatar`。
+基础资料和头像的确认不等于 Creator 需求手册已确认。已有搭子的恢复沿用原身份和云端头像；明确需要更换头像时使用 `buddy-cli meta update --avatar`。
 
 ## 需求明确时，直接开发
 
@@ -163,7 +148,7 @@ buddy-cli-sit init --mode direct --directory "<搭子工程目录>" --avatar "<
 直接生成官方 Runtime 工程：
 
 ```bash
-buddy-cli-sit init --mode direct --directory ./study-buddy \
+buddy-cli init --mode direct --directory ./study-buddy \
   --name "学习搭子" --tagline "把学习目标拆成每天能完成的小步骤" \
   --intro "根据学习目标与每日反馈，帮助用户安排练习并复盘。"
 ```
@@ -215,11 +200,11 @@ widgets/
 
 `schema.json` 的顶层是 `{ "description": "...", "modules": { ... } }`，各模块包含 `description` 和 `record`；`record` 才是该模块记录的 JSON Schema。不要直接把一份普通 JSON Schema 当作整个类型定义。
 
-CLI 将 HTML 和 Schema 随工程源码打包。工程安装的 Runtime 在 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；CLI 同时等待初始化完成与平台在线，才报告 DEV 就绪。缺文件、无效 JSON 或平台拒绝上传会使启动失败，具体原因可在终端或 Preview 日志中查看。平台需要已部署该接口。
 
-模型使用小挂件工具时，在 `src/buddy-options.mjs` 的 `initialState.tools` 中加入 `conversation.tools.widget_create`、`conversation.tools.widget_write_record` 等工具；业务代码也可直接调用 `conversation.widget`。类型按上传进程的 Buddy 身份保存，DEV 分身与正式版隔离。修改文件后重启 Runtime；删除或改名目录不会删除平台上的旧类型。Preview 可展示小挂件卡片、会话列表与 H5 页面。页面写操作仅在目标宿主配套支持、且 Schema 的 `operations.userUI` 显式授权时开放；缺省只读，Agent 写权限不能代替页面写权限。Creator 可按已确认需求演示展示或编辑交互；原型只操作示例数据，真实接入需按 Schema 授权验证。详见 [Widget 指南](../../docs/preview/widgets.md)。
+模型使用小挂件工具时，在 `src/buddy-options.mjs` 的 `initialState.tools` 中加入 `conversation.tools.widget_create`、`conversation.tools.widget_write_record` 等工具；业务代码也可直接调用 `conversation.widget`，主动服务回合禁止写操作。类型按上传进程的 Buddy 身份保存，DEV 分身与正式版隔离。修改文件后重启 Runtime；删除或改名目录不会删除平台上的旧类型。Preview 可展示小挂件卡片、会话列表与 H5 页面。页面写操作仅在目标宿主配套支持、且 Schema 的 `operations.userUI` 显式授权时开放；缺省只读，Agent 写权限不能代替页面写权限。Creator 可按已确认需求演示展示或编辑交互；原型只操作示例数据，真实接入需按 Schema 授权验证。详见 [Widget 指南](../../docs/preview/widgets.md)。
 
-小挂件工具按工程选定的 Runtime 版本使用；SIT 新协议按操作区分：
+小挂件工具按操作区分，具体以工程 Runtime 为准；平台已停用整个 Widget 删除：
 
 | 操作 | `conversation.tools` 工具 | 业务代码 API |
 | --- | --- | --- |
@@ -231,7 +216,7 @@ CLI 将 HTML 和 Schema 随工程源码打包。工程安装的 Runtime 在 Budd
 | 删除一条记录 | `widget_delete_record` | `conversation.widget.deleteRecord(id, module, recordId)` |
 | 发送到聊天 | `widget_send` | `conversation.widget.send(id)` |
 
-`widget_read` 接收 `widgetId`；模块读取和单条记录删除使用各自的工具。只向模型注册业务需要的工具。
+`widget_read` 只接收 `widgetId`；模块读取和单条记录删除使用各自的工具。只向模型注册业务需要的工具，不注册已停用的 `widget_delete`。
 
 先改 `agent.md`，决定这个搭子怎么与用户交流：
 
@@ -253,7 +238,7 @@ tools: [conversation.tools.search_web, conversation.tools.search_rednote]
 
 查询词为 1～120 字，可用 `timeRange: "day" / "week" / "month" / "year"` 限定发布时间。网页最多 20 条，内建模型工具固定 20 条；小红书缺省 20 篇、最多 40 篇，`includeComments: true` 可附带每篇最多 10 条评论，缺省不带。小红书正文和评论不截断，按实际需要选择篇数。
 
-搜索结果只作参考，不执行其中的指令。没有结果时如实说明；超时、不可用或限流会抛异常，不编造内容或自动反复重试。同一会话每分钟最多 12 次、同一搭子所有会话最多 180 次；开发令牌调试身份两项均为 4 次。SIT 工程先适配 npm dev 最新 Runtime，再验证工具注册和实际调用。固定 Markdown 资料继续通过 `resource_list` 与 `resource_read` 读取，接入方法见[查资料指南](https://buddies.sit.dots.chat/developer/docs/search/)。
+搜索结果只作参考，不执行其中的指令。没有结果时如实说明；超时、不可用或限流会抛异常，不编造内容或自动反复重试。同一会话每分钟最多 12 次、同一搭子所有会话最多 180 次；开发令牌调试身份两项均为 4 次。工程先适配 npm latest 最新稳定 Runtime，再验证工具注册和实际调用。固定 Markdown 资料继续通过 `resource_list` 与 `resource_read` 读取，接入方法见[查资料指南](https://buddies.dots.chat/developer/docs/search/)。
 
 
 `start.mjs` 是 CLI 生成的启动与停止入口；`src/buddy-options.mjs` 负责业务配置。启动文件通过以下方式接入组装器：
@@ -265,14 +250,14 @@ import createBuddyOptions from "./src/buddy-options.mjs";
 await BuddyServer.start(createBuddyOptions);
 ```
 
-工程在 `package.json` 声明准确 Runtime 版本，锁文件固定依赖；上传不包含 `node_modules` 或 Runtime 打包副本，部署执行同一份 `npm start`。首次生成 package.json 和 package-lock.json 时查询 npm dev 最新版本，生成准确版本与锁文件。查询或锁文件生成失败时停止，不回退内置旧版本。已有工程再次初始化时保留其依赖；安装验收直接从公共 npm 安装。
+工程在 `package.json` 声明准确 Runtime 版本，锁文件固定依赖；上传不包含 `node_modules` 或 Runtime 打包副本，部署执行同一份 `npm start`。首次生成 package.json 和 package-lock.json 时查询公共 npm latest，生成准确版本与锁文件。查询或锁文件生成失败时停止，不回退内置旧版本。已有工程再次初始化时保留其依赖；安装验收直接从公共 npm 安装。
 
 ## 想法还模糊时，先梳理需求
 
 确认用于登记的基础资料后，再执行下面的命令；这里的文案只是示例，不是通用默认值。
 
 ```bash
-buddy-cli-sit init --mode create --directory ./study-buddy \
+buddy-cli init --mode create --directory ./study-buddy \
   --name "学习搭子" --tagline "帮助用户建立学习习惯" \
   --intro "与用户一起明确目标，形成可以坚持的学习安排。"
 ```
@@ -292,38 +277,32 @@ buddy-cli-sit init --mode create --directory ./study-buddy \
          → 基础技术自测 → 打开真实预览 → 开发者体验并反馈
 ```
 
-CLI 0.15.0 起，Creator 使用独立 npm 包 `@my-life-buddies/buddy-creator-skill`。新项目首次创作查询稳定版，校验后缓存到 `~/.cache/buddy-cli-sit/creator-skills/buddy-creator-skill/<版本>/`，在 `.buddy/creator/skill-lock.json` 记录准确版本与完整性摘要。恢复项目优先使用固定版本缓存，不自动升级，已有缓存时 Skill 准备无需联网（平台身份校验仍需联网）。Skill 负责人独立发包，不再要求重发 CLI。
-
-显式升级某个项目：
-
-```bash
-buddy-cli-sit init --mode create --directory ./study-buddy --creator-version 1.6.0
-```
+CLI 0.15.0 起，Creator 使用独立 npm 包 `@my-life-buddies/buddy-creator-skill`。每次进入或恢复创作都查询公共 npm latest 最新正式版，校验后缓存到 `~/.cache/buddy-cli/creator-skills/buddy-creator-skill/<版本>/`，在 `.buddy/creator/skill-lock.json` 记录本次准确版本与完整性摘要。只有查证缓存对应最新版后才复用；版本记录不会阻止升级，恢复时也需要联网。Skill 负责人独立发包，不再要求重发 CLI。
 
-CLI 只接受协议兼容的准确稳定版本，保留原始背景、身份与作品。未改动的旧版生成接续说明会备份后迁移；开发者自定义说明不覆盖。新项目下载失败会报错并保留登记身份，可在同目录重试。
+不再提供 `--creator-version` 固定版本入口。CLI 查询 latest 后验证协议及完整性，保留原始背景、身份与作品。未改动的旧版生成接续说明会备份后迁移；开发者自定义说明不覆盖。查询、下载或协议校验失败都会报错，不退回旧缓存；已有资料和登记身份保留，可在同目录重试。
 
 维护者本地联调：
 
 ```bash
 BUDDY_CREATOR_SKILL_PATH=/absolute/path/buddy-creator-skill \
-  buddy-cli-sit init --mode create --directory ./study-buddy
+  buddy-cli init --mode create --directory ./study-buddy
 ```
 
-本地来源同样记录在项目中，适合 Skill 开发，不要求发布。要切回 npm，清除环境变量并显式指定 `--creator-version`。Python 执行仍需 3.9+，不安装 Python 第三方依赖。阶段与创作规则由 Skill 的 `references/cli-workflow.md` 管理，CLI 只处理身份、目录和有效交付后的开发接续。
+本地来源同样记录在项目中，仅用于显式 Skill 联调，不要求发布。每次联调都需要提供该环境变量；清除后会查询公共 npm latest，不因旧的本地版本记录继续使用本地目录。Python 执行仍需 3.9+，不安装 Python 第三方依赖。阶段与创作规则由 Skill 的 `references/cli-workflow.md` 管理，CLI 只处理身份、目录和有效交付后的开发接续。
 
-创作资料保存在 `.buddy/creator/`。CLI 支持 Creator 接入协议 1 和 2；Creator 2.1 的新作品使用 `workflowVersion=2` 的三册，旧作品继续原工作流，不自动迁移。按该作品工作流完成手册、小挂件清单、当前原型和设计验收，并通过交付校验，Skill 才返回 `directive=creator_complete`、`completion.status=ready` 和有效的 `completion.manualPath`；明确确认不使用小挂件时无需制造原型。完整创建任务中，当前 Coding Agent 退出采访，在同一轮重新读取 `HANDOFF.md`、真实手册、同目录实际 manifest、来源映射及小挂件设计与验收产物，自动开始开发，无需再说“继续”。不按旧四册文件名硬编码交付清单；手册确认或文件存在不能单独触发开发。只有影响实现的关键缺口才补问；仅设计、流程测试和暂停仍遵守原范围。
+创作资料保存在 `.buddy/creator/`。CLI 支持 Creator 接入协议 1 和 2；最新版 Creator 统一使用 `workflowVersion=2` 的三册（定位、知识与方法、付费服务）；旧四册由 Creator 的 open 保存历史后迁移，复用资料与可用进度，补充缺口并重新确认发生变化的内容，不把旧完成标记直接当作新交付。按该作品工作流完成手册、小挂件清单、当前原型和设计验收，并通过交付校验，Skill 才返回 `directive=creator_complete`、`completion.status=ready` 和有效的 `completion.manualPath`；明确确认不使用小挂件时无需制造原型。完整创建任务中，当前 Coding Agent 退出采访，在同一轮重新读取 `HANDOFF.md`、真实手册、同目录实际 manifest、来源映射及小挂件设计与验收产物，自动开始开发，无需再说“继续”。不按旧四册文件名硬编码交付清单；手册确认或文件存在不能单独触发开发。只有影响实现的关键缺口才补问；仅设计、流程测试和暂停仍遵守原范围。
 
-工作流 2 还需读取 `completion.capabilityContractPath` 指向的能力契约，按 Skill 的 `references/implementation-handoff.md` 保存 `implementation-report.json`，记录当前契约版本、逐需求实现和真实验证证据，再运行 `handoff-check`。该命令只核对报告结构、版本及覆盖，仍需实际 Runtime 验证；旧工作流不因升级 CLI 或 Skill 而强制补交新版契约和报告。「平台能力」中的方案来自 `service.blueprint.data.capabilityPlan`；旧作品仍可读取 `proactiveReminders`，方案展示不代表已经启用。
+新版三册还需读取 `completion.capabilityContractPath` 指向的能力契约，按 Skill 的 `references/implementation-handoff.md` 保存 `implementation-report.json`，记录当前契约版本、逐需求实现和真实验证证据，再运行 `handoff-check`。该命令只核对报告结构、版本及覆盖，仍需实际 Runtime 验证；迁移后的项目也须通过当前三册交付校验。「平台能力」中的方案来自 `service.blueprint.data.capabilityPlan`；旧资料迁移时可读取 `proactiveReminders`，方案展示不代表已经启用。
 
 手册中的角色、方法、处理路径和持续服务要求，都是开发依据。Coding Agent 按这些要求判断是否需要工具、专业方法、特定处理步骤、记忆与历史整理，技术选择不逐项交给开发者；完成后向开发者简要说明需求来源、实现位置、检查结果和缺口，不要求额外生成 README。已经明确的直接做，不能实现的如实说明；只有元数据或默认配置，不代表手册要求已经完成。
 
 手册完成后，Coding Agent 用下面的命令补齐官方 Runtime 工程，再据手册实现功能；这不是 Creator Skill 自己执行的操作：
 
 ```bash
-buddy-cli-sit init --mode direct --directory ./study-buddy
+buddy-cli init --mode direct --directory ./study-buddy
 ```
 
-创作阶段的 `package.json` 只有顶层 `buddyId`；CLI 用它从平台读取最新资料并重新校验归属，不另建搭子。创作中断后可以在原目录重试 `--mode create`，继续使用原作品；手册完成后执行 `--mode direct`，保留已有业务代码与数据声明，补齐 npm 字段和缺失的工程文件；缺失 `data-access.json` 时生成空 requirements 数组。旧 `--mode interview` 已停止使用。
+创作阶段的 `package.json` 只有顶层 `buddyId`；CLI 用它从平台读取最新资料并重新校验归属，不另建搭子。创作中断后在原目录重试 `--mode create`，检查最新 Creator 后接续原作品；手册完成后执行 `--mode direct`，保留已有业务代码与数据声明，补齐 npm 字段和缺失的工程文件；缺失 `data-access.json` 时生成空 requirements 数组。旧 `--mode interview` 已停止使用。
 
 两条主线都遵循同一个登记规则：名称、`tagline`（一句话介绍）、`intro`（完整介绍）先同步到平台，返回的 ID 写入 `package.json.buddyId`。公开资料不在本地留副本。若平台已创建成功、本地写盘失败，可用 `--buddy-id <平台返回的 ID>` 恢复；它不是自定义 ID 的入口。
 
@@ -337,26 +316,28 @@ Creator 例外保留首次创作背景快照，用于接续同一作品；恢复
 
 你明确要求自动体验或多场景回归时，Coding Agent 再按指定范围执行。`push` 仍需要明确授权。若你只要求初始化、修改某段代码或完成设计，也不会因为这套默认流程就自动启动预览。
 
-这些规则通过 CLI 帮助、命令输出和 Creator 的 `HANDOFF.md` 交给 Coding Agent；CLI 不会在 `init` 内自动执行采访、编写业务代码或批量调用模型。重试创作时复用当前接续说明和作品，不覆盖开发者修改的文件。已有完整工程无需重新初始化，可从更新后的 CLI 帮助和 `preview` 输出读取交接规则。
+这些规则通过 CLI 帮助、命令输出和 Creator 的 `HANDOFF.md` 交给 Coding Agent；CLI 不会在 `init` 内自动执行采访、编写业务代码或批量调用模型。重试创作时查询最新 Creator 并刷新生成的接续说明，保留原作品和开发者修改的文件。已有完整工程且保留 Creator 记录时，也可执行 `init --mode create` 接续创作，业务文件不会重建；没有 Creator 历史的直接开发工程继续按已有需求开发。
 
 ## 查看和修改搭子资料
 
 登记后用 `meta` 查看云端资料，用 `meta update` 修改名称、介绍或替换头像：
 
 ```bash
-buddy-cli-sit meta
-buddy-cli-sit meta update --name "川大厨" --tagline "帮你安排每天吃什么"
-buddy-cli-sit meta update --intro "根据食材、人数和口味推荐菜谱"
-buddy-cli-sit meta update --avatar ./avatar.png
+buddy-cli meta
+buddy-cli meta update --name "川大厨" --tagline "帮你安排每天吃什么"
+buddy-cli meta update --intro "根据食材、人数和口味推荐菜谱"
+buddy-cli meta update --avatar ./avatar.png
 ```
 
-`meta` 只读，修改时必须带 `update` 并至少提供一个字段。多个修改参数可以组合，未传字段保持原样，包括云端已有的扩展资料。文字字段不能为空，名称最多 60 字，一句话介绍最多 200 字，完整介绍最多 10000 字。头像只上传替换，不提供清除选项；支持静态 PNG、JPEG、WebP，最大 5 MiB。Server 校验图片并生成地址，处理失败时保留原头像。
+`meta` 只读，修改时必须带 `update` 并至少提供一个字段。多个修改参数可以组合，未传字段保持原样，包括云端已有的扩展资料。文字字段不能为空，名称最多 60 字，一句话介绍最多 200 字，完整介绍最多 10000 字。头像只上传替换，不提供清除选项；支持静态 PNG、JPEG、WebP，原图最大 5 MiB、宽高不超过 4096 px。Server 校验图片并生成地址，处理失败时保留原头像。
+
+头像上传请求最多等待 5 分钟，适用于首次登记、替换头像以及同时修改文字和头像。CLI 上传前按服务端规则居中裁切至 512×512，编码为无损 WebP，保留颜色和透明度；原始文件与本地原图草稿不变；查询、仅文字更新和兼容命令清除头像仍使用 30 秒超时。
 
 默认向上寻找 `package.json.buddyId`，也可用 `--directory ./cooking-buddy` 指定工程；图片路径始终相对执行命令的当前目录。创作阶段只有身份清单时也能使用，无需安装或启动 Runtime。工程外可直接指定平台 ID：
 
 ```bash
-buddy-cli-sit meta --buddy-id b_example
-buddy-cli-sit meta update --buddy-id b_example --name "川大厨" --avatar ./avatar.png
+buddy-cli meta --buddy-id b_example
+buddy-cli meta update --buddy-id b_example --name "川大厨" --avatar ./avatar.png
 ```
 
 `--buddy-id` 和 `--directory` 不能同时使用。命令复用 CLI 登录态，由 Server 校验搭子归属。CLI 先通过 `GET /cli/buddies/:id` 获取最新资料，合并指定修改，再通过 `PUT /cli/buddies/:id/meta` 更新；含头像时使用 multipart，文字和图片通过校验后一起提交。头像地址由平台生成，文字更新不提交原头像 URL。
@@ -367,17 +348,17 @@ buddy-cli-sit meta update --buddy-id b_example --name "川大厨" --avatar ./ava
 
 ## 为这个搭子选一个模型
 
-进入工程开发时，新业务工厂必须由开发者明确选择模型。交互终端会展示工程 Runtime 的模型目录；Coding Agent 先列出可用模型并询问开发者，再用 `buddy-cli-sit init --mode direct --model <已确认模型 ID>` 继续。非交互缺少选择或模型不受支持时，CLI 停止，不登记新身份或生成工程。create 路线在手册完成、进入 direct 开发时确认模型。
+进入工程开发时，新业务工厂必须由开发者明确选择模型。交互终端会展示工程 Runtime 的模型目录；Coding Agent 先列出可用模型并询问开发者，再用 `buddy-cli init --mode direct --model <已确认模型 ID>` 继续。非交互缺少选择或模型不受支持时，CLI 停止，不登记新身份或生成工程。create 路线在手册完成、进入 direct 开发时确认模型。
 
 已有 `src/buddy-options.mjs` 保留原模型，恢复时不传 `--model`；如需更换，先确认，再修改业务工厂。明确确认过的同一选择不重复询问。
 
 ```bash
-buddy-cli-sit models
+buddy-cli models
 ```
 
-无论工程内外，均读取公共 npm dev 最新 Runtime 的目录。缓存按准确版本保存，命令不修改工程依赖。JSON 中 `latestRuntimeVersion` 表示 dev 标签的最新版本，`projectRuntimeVersion` 为工程版本；不匹配时 `adaptationRequired` 为 true。
+不必先创建工程。无论是否在工程内，CLI 每次查询公共 npm latest，把对应 Runtime 缓存到 `~/.cache/buddy-cli/runtimes/<版本>` 并读取枚举；同版本复用缓存，不修改工程依赖。查询或下载失败时明确报错，不把旧缓存称为最新版。两个目录命令的 `--json` 返回 `source`（固定为 `npm`）、`runtimeVersion`、目录，以及 `projectRuntimeVersion`、`latestRuntimeVersion`、`versionStatus`、`adaptationRequired`。版本状态为 `no_project`、`unconfigured`、`current`、`update_available` 或 `project_ahead`；没有准确工程版本时返回 `null`，工程未锁定版本或版本与 npm latest 不一致时需要适配。提示输出到 stderr，stdout 保持纯 JSON。
 
-在已有工程执行 `buddy-cli-sit`、`init` 或打开 `preview` 时检查 npm dev 最新 Runtime。`dev`、Preview 启动 DEV、自动重载和 `push` 要求准确声明、实际安装和锁文件与最新 dev 版本一致；npm 查询失败时停止。CLI 不自动修改依赖、模型和数据权限。工程版本不匹配时，安装提示中的准确版本、完成适配后重试。帮助、登录、status、meta 和兼容命令 avatar 不查询 Runtime。
+在已有工程执行 `buddy-cli`、`init` 或打开 `preview` 时检查更新并提示适配，但允许继续编辑工程。正式包中，`dev`、Preview 中每次启动 DEV、文件自动重载，以及 `push` 必须联网查询 npm 最新稳定版，工程声明及实际安装版本必须与本次查询结果完全一致；不接受旧版、超前版、预发布版或范围依赖。查询失败即停止，不使用缓存冒充最新，也没有跳过检查参数。已有 npm 锁文件需与目标版本一致，push 还会按本次查询结果校验实际上传快照及其中的 npm 锁文件。失败信息包含原因和适配提示，CLI 不自动修改工程依赖、模型或数据权限。修复后重新启动；自动重载失败后保存文件可重试。帮助、登录、status、meta 和兼容命令 avatar 不查询 Runtime。
 
 此限制由本版 CLI 执行，不修改服务端策略或已部署进程；直接运行工程 `npm start`、旧 CLI 或服务端发布入口不受本版 CLI 检查约束。
 
@@ -408,43 +389,43 @@ initialState: {
 }
 ```
 
-新工程生成 `{ "requirements": [] }`。最多 32 项，ID 不能重复；`id`、`purpose` 会去除首尾空白，用途必须为 1～200 字。完整选项由 `buddy-cli-sit datasets [--json]` 按当前环境的版本规则读取，DEV 与 push 使用工程安装的 SDK 校验 ID。
+新工程生成 `{ "requirements": [] }`。最多 32 项，ID 不能重复；`id`、`purpose` 会去除首尾空白，用途必须为 1～200 字。完整选项由 `buddy-cli datasets [--json]` 按当前环境的版本规则读取，DEV 与 push 使用工程安装的 SDK 校验 ID。
 
 Runtime 0.17.0 启动时自动读取该文件，通过 `PUT /internal/v1/data-access/requirements` 登记；文件缺失或空数组会上传空声明，清除旧声明。登记失败阻止启动，不会带着未同步的配置上线。DEV 监听该文件，保存后重启 Runtime 并重新登记。部署环境需提供对应登记接口。
 
 CLI 将文件原样放入源码包，启动入口只调用 `BuddyServer.start(createBuddyOptions)`。Runtime 0.23.0 起，健康、位置和日历都通过 Dataset 查询，所需项目都要放入 `requirements`；声明不代表用户已授权，也不会自动启用工具。
 
-在 `initialState.tools` 注册 `conversation.tools.data_access_query` 和 `conversation.tools.data_access_request`。先查询，返回 `notGranted` 时调用 `data_access_request({ datasets, reason })` 发私聊授权卡，等待用户处理后再次查询。业务代码使用 `conversation.dataAccess.query({ datasets, memberId? })` 与 `conversation.dataAccess.request({ datasets, reason, memberId?, idempotencyKey })`；只申请已声明的 1～8 项数据。
+在 `initialState.tools` 注册 `conversation.tools.data_access_query` 和 `conversation.tools.data_access_request`。先查询，返回 `notGranted` 时调用 `data_access_request({ datasets, reason })` 发私聊授权卡，等待用户处理后再次查询。业务代码使用 `conversation.dataAccess.query({ datasets, memberId? })` 与 `conversation.dataAccess.request({ datasets, reason, idempotencyKey })`；只申请已声明的 1～8 项数据。
 
 只有 `available` 携带数据；`notDeclared` 要修正工程声明，`systemPermissionDenied` 需要用户检查 App 的系统权限，`unavailable` 表示暂无可用结果，不代表用户拒绝。位置与日历的快照过期时由平台尝试请求在线 App 刷新；浏览器模拟器提示去 App 处理授权，CLI 不采集设备数据。
 
 ## 在模拟器里聊一次
 
-CLI 0.13.0 起，默认预览 UI 由后台提供。后台「获取连接指令」返回 `buddy-cli-sit preview --buddy-id <id> --developer-web <后台 URL> --app-server <平台 URL> --no-open`；请在对应工程目录执行。CLI 0.17.7 起支持 `--no-open`，只连接工程，返回原调试页即可，不重复打开网页；页面已关闭时可打开终端打印的地址。直接执行 `buddy-cli-sit preview` 仍自动打开后台，`--no-open` 不与 `--local` 混用。
+CLI 0.13.0 起，默认预览 UI 由后台提供。后台「获取连接指令」返回 `buddy-cli preview --buddy-id <id> --developer-web <后台 URL> --app-server <平台 URL> --no-open`；请在对应工程目录执行。CLI 0.17.7 起支持 `--no-open`，只连接工程，返回原调试页即可，不重复打开网页；页面已关闭时可打开终端打印的地址。直接执行 `buddy-cli preview` 仍自动打开后台。
 
 CLI 校验工程身份，后台验证账号与搭子归属。同一电脑、同一工程已有连接时，新命令复用它并退出，由原 CLI 继续维持连接；请保持原终端运行。连接其他电脑或工程前，请先退出原 CLI。
 
 后台显示「未连接本地工程」「已连接但 DEV 未启动」「DEV 运行中」。CLI 主动发起 HTTPS 连接，后台通过受限调试接口控制本机 Runtime，浏览器不需访问 localhost。工程路径用于显示连接身份，源码不会经调试通道上传。连接每 500 ms 交换待处理请求；持续中断 10 秒停止 DEV，后台最迟约 17 秒显示断开；短暂断网恢复后手动启动 DEV；若后台已结束或撤销连接，CLI 会退出，需要重新执行连接指令。页面刷新只恢复状态，CLI 退出停止 DEV 并断开。
 
-后台暂不可用时，用 `buddy-cli-sit preview --local` 打开独立本地备用预览，可加 `--port`。后台模式不使用固定本地端口，不需要公网隧道。预览不会提审或发布。
+CLI 0.27.0 起，调试页面完全由后台维护，安装包不再包含独立本地网页。`--local`、`--port` 已停用，使用旧参数会提示改用 `buddy-cli preview`。本地连接不需要公网隧道；DEV、日志、消息、小挂件和商品调试接口继续保留，预览不会提审或发布。
 
 以下两个命令按需选择，不必同时启动同一个工程：
 
 ```bash
-buddy-cli-sit dev --directory ./study-buddy
-buddy-cli-sit preview --directory ./study-buddy
+buddy-cli dev --directory ./study-buddy
+buddy-cli preview --directory ./study-buddy
 ```
 
 ### 停止 DEV 与强制断连（CLI 0.18.0 起）
 
 - `dev` 运行本机 Runtime；`preview` 维持后台与工程的连接，在页面启动 DEV 后才运行 Runtime。
-- 「停止 DEV」或在工程目录执行 `buddy-cli-sit dev stop`：停止 Runtime 和文件监听，已有 preview 连接保留，不重新启动。
+- 「停止 DEV」或在工程目录执行 `buddy-cli dev stop`：停止 Runtime 和文件监听，已有 preview 连接保留，不重新启动。
 - Ctrl+C、SIGTERM 或关闭终端（SIGHUP）：停止 CLI 管理的 Runtime 进程组，释放锁并断开后台连接。
 - 后台「强制断连」：先阻止新的调试操作，尝试停止该工程的 DEV，再撤销连接；旧 CLI 不能自动接回。页面会明确显示本机是否已确认停止。
 - CLI 被强杀、电脑离线或旧版进程无法响应时，网页不能保证本机进程已退出。到原电脑的工程目录执行后台提供的停止指令，例如：
 
 ```bash
-buddy-cli-sit dev stop --buddy-id b_example --app-server https://buddies.sit.dots.chat
+buddy-cli dev stop --buddy-id b_example --app-server https://buddies.dots.chat
 ```
 
 `dev stop` 无需登录、查询 npm 或访问平台，支持 `--directory`；按平台和工程 buddyId 查找本机进程。原 CLI 存活时通知它停止监听与 Runtime，原 CLI 已退出时核对进程身份后清理残留；不能确认身份时保留锁并报错，不误杀其他进程。同一搭子从其他目录启动时，应在提示的原工程目录执行。其他电脑的进程需到那台电脑停止。清理后如需调试，重新执行连接指令，再在页面启动 DEV；不会提审或发布。
@@ -477,28 +458,28 @@ Preview 展示平台对话记录、发送与流式输出耗时、会话状态和
 
 ### 正式包的平台与 Runtime
 
-SIT 包固定连接 SIT：`https://buddies.sit.dots.chat`，后台为 `https://buddies.sit.dots.chat/developer/`。无需手动设置 `MLB_GATEWAY_URL`，也不询问开发或发布环境。
+正式包固定连接 PROD：`https://buddies.dots.chat`，后台为 `https://buddies.dots.chat/developer/`。无需手动设置 `MLB_GATEWAY_URL`，也不询问开发或发布环境。
 
 - 登录、API、凭据领取、预览与上传均使用固定目标；CLI 将该网关及开发 Token 写入工程 `.env` 给 Runtime 使用。
 - `--app-server`、`--developer-web` 仅接受同一固定目标，兼容已有后台连接指令，不能切换环境。
 - `MLB_GATEWAY_URL`、`BUDDY_APP_SERVER_URL`、`BUDDY_DEV_APP_SERVER_URL`、`BUDDY_DEVELOPER_WEB_URL` 任一冲突都会报错；显式正确参数不能掩盖其他冲突配置。按提示移除终端及 shell 配置里的旧值，重新打开 Coding Agent 或终端后重试。
-- 创建或恢复工程、读取或修改工程资料、预览、DEV 和上传都会检查工程 `.env`。其他环境工程请使用对应 CLI；迁移到公共平台需在新目录重新登记搭子后复制业务代码，不复制 `.env`、buddyId 或凭据。`--refresh-token` 仅刷新同一环境的开发凭据。
+- 创建或恢复工程、读取或修改工程资料、预览、DEV 和上传都会检查工程 `.env`。已知 ECS 工程按下述规则自动连接 PROD；SIT 或其他环境使用对应 CLI，不复制 `.env`、buddyId 或凭据。`--refresh-token` 仅刷新同一环境的开发凭据。
 - 登录态按平台 origin 保存，开发 Token 与本地实例锁继续按平台和搭子隔离。不读取旧的无平台归属登录记录。CLI 地址限制不代替 Server 的账号、归属及凭据环境校验。
 
-临时保留同一 ECS 的旧入口迁移：`http://47.116.168.81:8788` 和 `http://47.116.168.81` 转为 HTTPS。启动 DEV 时校验归属，取得实例锁后更新 `.env`，保留业务配置与注释；失败不改文件。正式推广完成后可移除此兼容分支。
+已知 ECS 的 HTTPS 地址及两个旧 HTTP 入口支持自动连接 PROD：先验证原登录态与同一 buddyId 的归属，再在 DEV 启动时更新 `.env`。保留业务配置和注释，身份校验或网络失败时不改文件；登录态过期时需正常登录。详见 [原工程连接 PROD](../../docs/ecs-to-prod.md)。
 
-`models`、`datasets` 统一读取 npm dev 最新 Runtime 的目录。新建工程自动解析并固定准确版本，不提供 Runtime 版本选择；已有工程不自动改依赖。DEV 和 push 要求准确声明、安装和锁文件与最新 dev 版本一致，开发者或 Coding Agent 应按提示更新依赖并验证业务兼容性。
+`models`、`datasets` 和新建工程动态查询公共 npm 的 Runtime `latest`，只接受正式版本；新工程固定准确版本与锁文件。DEV、自动重载及 push 要求工程声明、实际安装和锁文件与本次最新正式版一致；不提供 `--runtime-version` 或测试版选择，不自动修改已有依赖。CLI 与 Runtime 的版本号无需一致。Runtime 发布者须在 PROD 支持对应能力后才更新 `latest`。
 
-SIT CLI 只查询自身包的 dev 标签，遇到稳定版本或其他预发布命名会拒绝更新；不会安装正式包。
+正式 CLI 自动更新也只查询 `latest`；若该标签误指向预发布版本，停止并提示发布者修正，不跨到测试渠道。
 
 ## 上传、商品审核与发布
 
-先在后台创建商品取得稳定 ID，完善资料和截图后点击“保存”。从未上架商品必须随新搭子版本上传提审并一起发布，商品页不提供独立“提交审核”。搭子代码可以引用该 ID；无需创建 `product.json`，平台查询商品元数据的接口本期尚未实现。
+先在后台创建商品取得稳定 ID，完善资料后点击“保存”（体验截图选填）。从未上架商品必须随新搭子版本上传提审并一起发布，商品页不提供独立“提交审核”。搭子代码可以引用该 ID；无需创建 `product.json`，平台查询商品元数据的接口本期尚未实现。
 
 ```bash
-buddy-cli-sit push --directory ./study-buddy --commit "根据完成情况调整练习难度"
-buddy-cli-sit push --directory ./study-buddy --commit "增加写作陪伴" --product prd_12345678
-buddy-cli-sit status --directory ./study-buddy
+buddy-cli push --directory ./study-buddy --commit "根据完成情况调整练习难度"
+buddy-cli push --directory ./study-buddy --commit "增加写作陪伴" --product prd_12345678
+buddy-cli status --directory ./study-buddy
 ```
 
 `--product` 可以重复，每次仅提交明确选中的商品当前已保存内容。新商品 ID 使用 `prd_` 加八位数字（如 `prd_12345678`），已有 `ps_` 商品 ID 继续兼容；复制后台返回的真实 ID，不要自行生成。未传该参数只上传代码，不扫描代码猜测商品，也不自动提交其他商品修改。CLI 在发送前固定本次上传 ID、源码包、商品审核 ID 和内容版本；平台为该上传生成唯一版本并自动通过代码和商品审核，构建状态单独显示。审核通过不会自动发布。
@@ -508,8 +489,8 @@ buddy-cli-sit status --directory ./study-buddy
 ### 恢复原上传
 
 ```bash
-buddy-cli-sit push --status <pushId>
-buddy-cli-sit push --resume <pushId>
+buddy-cli push --status <pushId>
+buddy-cli push --resume <pushId>
 ```
 
 网络中断或结果未知时，按终端给出的 ID 查询或恢复原操作。恢复使用原包和原商品版本，不会把后来编辑的内容悄悄提交。代码已上传但商品提交失败时，先修正并保存商品，再对同一待发布版本发起一次补提。首次商品仅允许恢复原上传已明确携带且提交失败的项，由平台核验原上传凭证；不能补入其他首次商品或关联已经上线的版本。
@@ -517,33 +498,21 @@ buddy-cli-sit push --resume <pushId>
 ### 补提或单独提交商品
 
 ```bash
-buddy-cli-sit products submit --version <已上传版本> --product prd_12345678
-buddy-cli-sit products submit --resume <submissionId>
+buddy-cli products submit --version <已上传版本> --product prd_12345678
+buddy-cli products submit --resume <submissionId>
 ```
 
 提交结果包含准确的审核快照 ID。只有曾上架商品（包括已下架商品）才可独立选择已有版本提交修改；当前线上代码支持本次修改时，可以选择当前已发布版本，之后单独发布修改。首次商品仅可通过此命令恢复原上传的商品提交失败，仍须与关联搭子版本一起发布。
 
-### 确认发布
+### 在后台确认发布
 
-```bash
-buddy-cli-sit release --from-push <pushId>
-buddy-cli-sit release --from-submission <submissionId>
-buddy-cli-sit release --from-submission <submissionId> --products-only
-buddy-cli-sit release --version <版本> --code-only
-```
+CLI 负责上传代码、提交明确选中的商品以及查询或恢复这些操作。上传、审核和构建成功后，在开发者后台“版本与发布”核对本次版本与获批商品快照，再确认发布；CLI 不提供最终发布命令。
 
-前两种方式使用原回执中的版本与获批快照。`--products-only` 仅用于曾上架商品的修改，要求目标仍为当前已发布搭子版本；首次商品不能使用此选项，必须随关联搭子版本一起发布。已下架商品发布修改后仍保持下架。只希望更新代码时，明确使用 `--code-only`，商品内容保持原样。读取回执失败或商品提交失败不会被自动当成空商品清单继续发布。也可以到后台“版本与发布”确认本次发布内容。
+首次商品必须随关联搭子版本一起发布。曾上架商品的修改可以在当前线上代码支持时，从后台单独发布；已下架商品发布修改后仍保持下架。只希望更新代码时，在后台明确选择仅发布代码，商品内容保持原样。
 
-```bash
-buddy-cli-sit release --status <releaseId>
-buddy-cli-sit release --resume <releaseId>
-buddy-cli-sit release --retry <releaseId>
-buddy-cli-sit release --cancel <releaseId>
-```
-
-发布结果未知时先查询或恢复原任务；明确失败后可重试。取消阻止本任务后续激活商品，但不回滚已经开始的代码部署。仅 `active` 表示本次发布与商品激活完成。状态和恢复记录按平台、账号、搭子隔离，保存在本机私有操作目录；记录不包含登录凭据，恢复使用当前账号重新鉴权。
+发布任务的状态查询、重试和取消也在后台操作。取消阻止本任务后续激活商品，但不回滚已经开始的代码部署。后台显示发布成功后，仍需确认实际服务体验。下架仍在后台操作。
 
-本期沿用平台已有的发布成功标准，没有新增 Runtime 初始化完成回报。页面或 CLI 显示发布成功，不等于实际服务已通过人工体验。下架仍在后台操作。
+CLI 的上传和商品补提恢复记录按平台、账号、搭子隔离，保存在本机私有操作目录；记录不包含登录凭据，恢复使用当前账号重新鉴权。
 
 ### 上传前检查
 
@@ -578,18 +547,20 @@ buddy-cli-sit release --cancel <releaseId>
 
 参考 Creator 已确认的需求、原型和设计说明，在 `widgets/<小挂件类型>/` 中编写 `index.html` 和 `schema.json`，并在搭子业务中接入创建、读写和发送能力。按每项设计确定展示或编辑交互；pageEditing 记录所需操作、字段和目标环境，不授予生产权限。沿用已确认方案，按真实 Schema 和宿主支持接入；旧版作品升级需重新确认受影响设计。
 
-使用 `buddy-cli-sit preview` 调试页面与交互，修改后重启 DEV；准备上传时运行 `buddy-cli-sit push`。Runtime 启动时读取小挂件文件并上传平台。开发步骤见仓库 `docs/widgets/design-delivery.md`。
+使用 `buddy-cli preview` 调试页面与交互，修改后重启 DEV；准备上传时运行 `buddy-cli push`。Runtime 启动时读取小挂件文件并上传平台。开发步骤见仓库 `docs/widgets/design-delivery.md`。
+
+后台的 Widget 编辑需配套 Server 和 Web 部署，只开放 `operations.userUI` 授权的记录操作，并遵守字段只读限制；409 冲突需重读核对，不能自动覆盖。图片上传与关闭后的聚合通知、API 和错误处理见 [Widget 指南](../../docs/preview/widgets.md)。目标 App 仍需提供编辑桥接并单独验收，后台预览成功不代表手机端已支持。记录编辑不代表多人实时同步、玩家身份认证或同一 Widget 内的玩家私有数据隔离；付费服务不在此范围。
 
 ## 查看数据集，不依赖 Coding Agent
 
 工程内外均可直接查询最新目录，不要求先安装工程依赖：
 
 ```bash
-buddy-cli-sit datasets
-buddy-cli-sit datasets --directory ./my-buddy --json
+buddy-cli datasets
+buddy-cli datasets --directory ./my-buddy --json
 ```
 
-目录来自npm dev 最新 Runtime 的 `DATA_ACCESS_CAPABILITIES`，包括 ID、名称、来源和 Schema 版本。JSON 返回版本信息、适配状态和 `datasets` 数组（字段见上方模型目录说明）。命令不登录、不启动搭子、不申请权限，也不修改配置；从子目录运行会向上找到工程。每次都需要联网查询 dev 最新版本，下载失败时明确报错，不把旧缓存称为最新版。
+正式包的目录来自 npm 最新稳定版 Runtime 的 `DATA_ACCESS_CAPABILITIES`，包括 ID、名称、来源和 Schema 版本。JSON 返回版本信息、适配状态和 `datasets` 数组（字段见上方模型目录说明）。命令不登录、不启动搭子、不申请权限，也不修改配置；从子目录运行会向上找到工程。每次都需要联网检查 latest，下载失败时明确报错，不把旧缓存称为最新版。
 
 开发者将实际选择的 ID 和用途写进 `data-access.json.requirements`。JSON Schema 检查形状与用途；DEV 和上传预检按工程安装的 Runtime 检查所选模型与非空数据声明。目录缺失、依赖未安装或版本不匹配时明确报错。Runtime 0.12.2 有 10 项，但单次数据查询仍最多 8 项。
 
@@ -601,13 +572,13 @@ Preview 文本发送采用 App WebSocket 的 `messages` 数组，并校验逐项
 
 同一个搭子的开发者共享开发 Token 和 `<buddyId>-dev` 身份；同一开发身份仍只能保持一条 Runtime 事件流。正式身份使用另一把 Token，两者互不顶替。开发凭据没有自动过期时间，Server 重置或删除搭子后才失效。
 
-开发 Token 被平台重置后，停止当前 CLI，再运行 `buddy-cli-sit dev --refresh-token` 或 `buddy-cli-sit preview --refresh-token`。这会跳过本地开发凭据，重新领取服务端当前的开发 Token 并更新 `.env`，不在 Server 生成新密钥。工程启动不再从旧版 Keychain 的开发 Token 缓存领取凭据。
+开发 Token 被平台重置后，停止当前 CLI，再运行 `buddy-cli dev --refresh-token` 或 `buddy-cli preview --refresh-token`。这会跳过本地开发凭据，重新领取服务端当前的开发 Token 并更新 `.env`，不在 Server 生成新密钥。工程启动不再从旧版 Keychain 的开发 Token 缓存领取凭据。
 
 账号登录凭据仍保存在 macOS Keychain，不写入工程。开发 Token 保存在权限为 `0600` 的工程 `.env`，不传给 Web，也不进入上传包或命令行参数。
 
 ### 本地身份与连接配置
 
-首次启动 DEV 时，CLI 将开发版 `BUDDY_TOKEN` 和 `MLB_GATEWAY_URL` 写入工程 `.env`，保留其他配置和注释，移除旧 `BUDDY_ID` 赋值。身份始终来自 `package.json.buddyId`；只有 Token 而没有网关的旧配置不会复用 Token，将重新校验搭子归属并领取当前环境凭据。后续复用前向 Server 核对 Token；`--refresh-token` 重新领取后更新此文件。开发者登录凭据仍使用系统凭据存储。`.env` 加入 Git 忽略，且始终排除在上传包之外。
+首次启动 DEV 时，CLI 将开发版 `BUDDY_TOKEN` 和 `MLB_GATEWAY_URL` 写入工程 `.env`，保留其他配置和注释，移除旧 `BUDDY_ID` 赋值。身份始终来自 `package.json.buddyId`；只配置 Token 的 `.env` 也可使用。后续复用前向 Server 核对 Token；`--refresh-token` 重新领取后更新此文件。开发者登录凭据仍使用系统凭据存储。`.env` 加入 Git 忽略，且始终排除在上传包之外。
 
 CLI、Preview 与标准 `npm start` 均由 Node 的 `--env-file-if-exists=.env` 加载本地配置，Runtime 从 `package.json.buddyId` 读取身份、从环境变量读取 Token 和网关；托管时平台注入的同名环境变量优先。已有工程显式升级 Runtime 后，CLI 只自动迁移能精确识别的生成入口及标准启动命令，自定义业务代码和脚本保留。
 
@@ -629,22 +600,4 @@ Runtime 0.19.0 支持在 `schema.json.openTargets` 声明入口。业务通过 `
 
 ## CLI 0.20：MLB 统一提供服务
 
-正式包入口固定与 SIT 网页同源，使用 HTTPS。CLI 的一次性浏览器授权走 `/cli/web/authorizations`、`/cli/web/exchange`，预览连接走 `/cli/preview/*`。不调用独立 Web 服务，不支持地址覆盖；预览不触发上传或发布。
-
-## SIT 包与准确版本复现
-
-```sh
-npm install --global --prefix "$HOME/.local/share/buddy-cli/sit" @my-life-buddies/cli@dev --registry=https://registry.npmjs.org/
-export PATH="$HOME/.local/share/buddy-cli/sit/bin:$PATH"
-buddy-cli-sit --version
-# 复现某一版（必须与已安装版本完全匹配）
-export BUDDY_CLI_PIN_VERSION=0.23.0-dev.2
-buddy-cli-sit preview
-unset BUDDY_CLI_PIN_VERSION
-```
-
-SIT 平台固定为 `https://buddies.sit.dots.chat`。CLI 地址约束是客户端防误连机制；服务端仍须独立校验身份、Token 和权限，不是完整的服务端安全隔离。
-
-SIT `push` 触发异步构建，显示 `building/ready/failed` 及失败原因，最多等待一分钟；仍在构建时用 `buddy-cli-sit status` 查询，不能重复上传当作查询。审核通过、构建就绪和线上发布是不同状态；确认上传回执中的版本与商品快照后，可在后台发布，或执行 `buddy-cli-sit release --from-push <pushId>`，仅 `active` 表示发布生效。
-
-DEV 要同时看到 Runtime 初始化完成和服务端在线后才就绪。后台的 Widget 编辑需配套 Server 和 Web 部署，只开放 `operations.userUI` 授权的记录操作，并遵守字段只读限制；409 冲突需重读核对，不能自动覆盖。图片上传与关闭后的聚合通知、API 和错误处理见 [Widget 指南](../../docs/preview/widgets.md)。目标 App 仍需提供编辑桥接并单独验收，后台预览成功不代表手机端已支持。记录编辑不代表多人实时同步、玩家身份认证或同一 Widget 内的玩家私有数据隔离；付费服务不在此范围。
+正式包入口固定与 PROD 网页同源，使用 HTTPS。CLI 的一次性浏览器授权走 `/cli/web/authorizations`、`/cli/web/exchange`，预览连接走 `/cli/preview/*`。不调用独立 Web 服务，不支持地址覆盖；预览不触发上传或发布。