@my-life-buddies/cli 0.24.1 → 0.25.0-dev.0

package/README.md

@@ -1,10 +1,10 @@
-# buddy-cli 使用说明
+# buddy-cli-sit 使用说明
 
-创作者提供的参考素材应在开发主体时同步接入。使用 `buddy-cli knowledge sync --plan .buddy/knowledge/plan.json` 生成分章节 Markdown、可读目录和来源映射；源资料更新时保留手工修改。计划格式见 `buddy-cli knowledge --help`，完整流程见[运行知识接入](../../docs/cli/knowledge.md)。本功能只写本地文件，不增加 push 检查或自动上传。
+创作者提供的参考素材应在开发主体时同步接入。使用 `buddy-cli-sit knowledge sync --plan .buddy/knowledge/plan.json` 生成分章节 Markdown、可读目录和来源映射；源资料更新时保留手工修改。计划格式见 `buddy-cli-sit knowledge --help`，完整流程见[运行知识接入](../../docs/cli/knowledge.md)。本功能只写本地文件，不增加 push 检查或自动上传。
 
 这份说明按一次开发过程展开：登记搭子，准备工程，在本地预览，然后上传程序包。所有搭子统一使用 `@my-life-buddies/buddy-runtime`，业务能力通过 Prompt、`src/buddy-options.mjs` 和 Tool 实现。
 
-空白工程模板不预置 Runtime 依赖或版本。新建工程动态查询公共 npm 的最新稳定版 Runtime，并写入准确版本与锁文件；查询或锁文件生成失败时停止，不回退旧版本。版本选择与联调范围见 [Runtime 集成说明](../../docs/runtime-integration.md)。
+空白工程模板不预置 Runtime 依赖或版本。新建工程统一查询公共 npm dev 最新 Runtime，并写入准确版本与锁文件，不提供版本选择；查询或锁文件生成失败时停止，不回退旧版本。版本策略与联调范围见 [Runtime 集成说明](../../docs/runtime-integration.md)。
 
 ## 准备 CLI 和平台地址
 
@@ -14,21 +14,36 @@ CLI 发布目标为公共 Registry `https://registry.npmjs.org/`。已有仓库
 
 ```bash
 npm install
-npm run buddy-cli -- --help
+npm run buddy-cli-sit -- --help
 ```
 
-下文统一使用 `buddy-cli`。源码运行时替换为 `npm run buddy-cli --`；从公共 npm 安装已发布版本：
+下文统一使用 `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` 命令安装在独立目录；正式版可保留原有全局安装：
 
 ```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 --help
-buddy-cli init --help
-buddy-cli guide
+buddy-cli-sit --help
+buddy-cli-sit init --help
+buddy-cli-sit guide
 ```
 
 `--help` 列出命令，`<命令> --help` 说明当前命令的参数、限制和示例。`guide` 输出 Coding Agent 的完整开发指引，包括创作开场、资料确认、Skill 接续、实现和交付规则；无需工程或登录，先联网自检并按需自动更新 CLI，再输出新版指引，不修改工程文件。让 Agent 开始工作前先读取 `guide`，再按 CLI 返回的 `HANDOFF.md` 继续当前工程。HANDOFF 只包含当前工程、Skill 路径和接续方式，通用规则以 guide 为准；已生成文件在正常恢复创作时校验、备份并更新，CLI 升级不会直接覆盖工程里的 HANDOFF。`guide --help` 只显示该命令的简短用法。
@@ -42,23 +57,23 @@ Agent 按已确认需求判断是否需要联网查资料。需求没有说明
 ### 查看版本和更新 CLI
 
 ```bash
-buddy-cli --version
-buddy-cli update --check
-buddy-cli update
+buddy-cli-sit --version
+buddy-cli-sit update --check
+buddy-cli-sit update
 ```
 
-`--version`（也可写作 `-v`）显示当前运行的 CLI 版本，无需联网。`update --check` 查询公共 npm 的 `latest` 版本，只检查、不安装；`update` 有新版本时安装检查到的准确版本，完成后核验安装结果。版本相同或本机版本更高时不安装、不降级。这三个用法均无需登录搭搭账号或进入搭子工程，从 CLI 0.8.0 开始支持。旧版用户先用上面的 npm 命令升级。
+`--version`（也可写作 `-v`）显示当前运行的 CLI 版本，无需联网。`update --check` 查询 `@my-life-buddies/cli` 的 npm `dev` 版本，只检查、不安装；`update` 有新版本时安装检查到的准确版本，完成后核验安装结果。版本相同或本机版本更高时不安装、不降级。这三个用法均无需登录搭搭账号或进入搭子工程，从 CLI 0.8.0 开始支持。旧版用户先用上面的 npm 命令升级。
 
-从 CLI 0.17.0 起，每条正常命令（含 `guide` 和无参数入口）先查询公共 npm `latest`，当前版本落后时自动更新，并由新版执行原命令。无需手动先运行 `update`，等待当前命令完成即可。更新发生在创建工程、领取凭据、启动 DEV 或上传之前；保留参数、工作目录、终端输入输出和退出状态，一次调用最多自动切换一次。版本相同或更高时继续执行，不降级；已经运行的 DEV 不因新版本发布而中断。
+从 CLI 0.17.0 起，每条正常命令（含 `guide` 和无参数入口）先查询 CLI 的公共 npm `dev` 标签，当前版本落后时自动更新，并由新版执行原命令。无需手动先运行 `update`，等待当前命令完成即可。更新发生在创建工程、领取凭据、启动 DEV 或上传之前；保留参数、工作目录、终端输入输出和退出状态，一次调用最多自动切换一次。版本相同或更高时继续执行，不降级；已经运行的 DEV 不因新版本发布而中断。
 
-全局安装更新当前 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`。
+全局安装及通过 `--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，已有工程的 Runtime 依赖、锁文件和业务适配仍需另行修改与验证。旧 CLI 不会自动获得自检能力，需要先用 npm 安装命令升级一次。
 
 可追加 `--json` 供 Coding Agent 或脚本读取，例如：
 
 ```bash
-buddy-cli update --check --json
+buddy-cli-sit 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 进度文字。
@@ -70,22 +85,20 @@ buddy-cli update --check --json
 ```bash
 npm run release:check
 npm run release             # 完整验证与演练
-npm run release -- --publish # 显式发包，PROD 验收记录为空时禁止发布
+npm run release -- --publish # 显式发布当前 dev 分支到 npm dev
 ```
 
-流程、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`。
+`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`。
 
 版本维护：每批修改 CLI 发布内容时递增一次版本，默认 patch；根包和内部工作区版本、依赖引用、锁文件一起更新。Agent 工程自己的项目版本独立。Runtime 版本由创建时动态查询并锁定；发布前验证真实 Runtime 的动态解析和独立安装，不向空白模板写入基准版本。
 
-正式版 CLI 固定连接 PROD `https://buddies.dots.chat`，无需配置地址：
+SIT CLI 固定连接 SIT `https://buddies.sit.dots.chat`，无需配置地址：
 
 ```bash
-buddy-cli login
+buddy-cli-sit login
 ```
 
-这是实际的 PROD 环境，使用 HTTPS；不能改为其他平台或本机网关。手机 App 需要连接同一环境。
+这是实际的 SIT 环境，使用 HTTPS；不能改为其他平台或本机网关。手机 App 需要连接同一环境。
 
 CLI 会打开搭搭创作者平台网页完成登录和授权。浏览器已有有效 Cookie 时，页面直接显示当前账号，开发者确认后即可返回终端；没有登录时，先在同一网页完成短信登录，再确认授权。CLI 不读取浏览器 Cookie，也拿不到短信验证码，只通过本机回调收到一次性授权码，再换取自己的会话。
 
@@ -100,7 +113,7 @@ CLI 会把换取到的会话保存到 macOS Keychain。有效会话会复用，
 | `--version [--json]` | 不需要，也不登录 | 显示当前运行的 CLI 版本，无需联网 |
 | `update [--check] [--json]` | 不需要，也不登录 | 检查公共 npm 最新版，或更新 npm 全局 CLI |
 | `login`、`logout` | 不需要 | 管理账号会话 |
-| `models` | 不需要，也不登录 | 始终联网读取 npm 最新 Runtime 的模型目录，提示工程版本差异；支持 `--directory`、`--json` |
+| `models` | 不需要，也不登录 | 始终联网读取 npm dev 最新 Runtime 的模型目录，提示工程版本差异；支持 `--directory`、`--json` |
 | `init` | 目标目录可以是空目录或已有官方工程 | 登记或恢复云端身份，准备本地文件 |
 | `dev`、`preview`、`push` | 需要有效清单和完整工程文件 | 运行、调试或打包该工程 |
 | `status` | 需要含 `buddyId` 的 `package.json` | 查询该搭子的云端状态；创作尚未完成时也可使用 |
@@ -117,13 +130,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/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-sit/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 init --mode create --directory ./my-buddy
+  buddy-cli-sit init --mode create --directory ./my-buddy
 ```
 
 本地来源会记录在头像 Skill 锁中；切回 npm 时清除环境变量，并显式传入 `--avatar-skill-version`。首次下载失败会保留草稿，可在同目录重试，也可提供已有图片完成登记。
@@ -132,14 +145,14 @@ BUDDY_AVATAR_SKILL_PATH=/absolute/path/avatar-creator-skill \
 普通终端不会执行 skill，也不要求安装 Coding Agent：选择本地图片后会打开资料与头像预览，再询问是否确认登记。没有图片或暂不确认时保留草稿，退出码为 2，稍后在原目录继续。
 
 ```bash
-buddy-cli init --mode direct --directory "<搭子工程目录>" --avatar "<头像文件路径>"
+buddy-cli-sit init --mode direct --directory "<搭子工程目录>" --avatar "<头像文件路径>"
 ```
 
 非交互调用必须由宿主先取得开发者明确确认，再传 `--avatar "<已确认图片路径>" --confirm-meta`。该标志声明开发者确认了本次资料和实际图片；不能把“帮我创建搭子”当作头像确认。CLI 不生成图片、不推断对话授权，也不以示例图替代新头像。
 
 `.buddy/meta/` 保存草稿、候选图片、预览与接续说明，push 不上传。上传失败保留已创建的 buddyId，重试复用原身份；已有云端头像不会在恢复中被覆盖。Meta 创建响应丢失时会明确暂停，核对后台身份后用 `--buddy-id` 恢复，避免重复创建。
 
-基础资料和头像的确认不等于 Creator 四册已确认。已有搭子的恢复沿用原身份和云端头像；明确需要更换头像时使用 `buddy-cli meta update --avatar`。
+基础资料和头像的确认不等于 Creator 四册已确认。已有搭子的恢复沿用原身份和云端头像；明确需要更换头像时使用 `buddy-cli-sit meta update --avatar`。
 
 ## 需求明确时，直接开发
 
@@ -148,7 +161,7 @@ buddy-cli init --mode direct --directory "<搭子工程目录>" --avatar "<头
 直接生成官方 Runtime 工程：
 
 ```bash
-buddy-cli init --mode direct --directory ./study-buddy \
+buddy-cli-sit init --mode direct --directory ./study-buddy \
   --name "学习搭子" --tagline "把学习目标拆成每天能完成的小步骤" \
   --intro "根据学习目标与每日反馈，帮助用户安排练习并复盘。"
 ```
@@ -200,11 +213,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；CLI 同时等待初始化完成与平台在线，才报告 DEV 就绪。缺文件、无效 JSON 或平台拒绝上传会使启动失败，具体原因可在终端或 Preview 日志中查看。平台需要已部署该接口。
+CLI 将 HTML 和 Schema 随工程源码打包。工程安装的 Runtime 在 BuddyServer 启动时读取 `widgets/`，通过 `PUT /internal/v1/widget-types/:typeId` 一起上传 Schema 与 HTML；先连接事件流，再完成这些上传；全部成功后才就绪。缺文件、无效 JSON 或平台拒绝上传会使启动失败，具体原因可在终端或 Preview 日志中查看。平台需要已部署该接口。
 
-模型使用小挂件工具时，在 `src/buddy-options.mjs` 的 `initialState.tools` 中加入 `conversation.tools.widget_create`、`conversation.tools.widget_write_record` 等工具；业务代码也可直接调用 `conversation.widget`，主动服务回合禁止写操作。类型按上传进程的 Buddy 身份保存，DEV 分身与正式版隔离。修改文件后重启 Runtime；删除或改名目录不会删除平台上的旧类型。Preview 可展示小挂件卡片、会话列表与 H5 页面，并通过 `window.dadaWidget` 按 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 页面。
 
-小挂件工具按操作区分，具体以工程 Runtime 为准；平台已停用整个 Widget 删除：
+小挂件工具按工程选定的 Runtime 版本使用；SIT 新协议按操作区分：
 
 | 操作 | `conversation.tools` 工具 | 业务代码 API |
 | --- | --- | --- |
@@ -216,7 +229,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_delete`。
+`widget_read` 接收 `widgetId`；模块读取和单条记录删除使用各自的工具。只向模型注册业务需要的工具。
 
 先改 `agent.md`，决定这个搭子怎么与用户交流：
 
@@ -238,7 +251,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 次。工程先适配 npm latest 最新稳定 Runtime，再验证工具注册和实际调用。固定 Markdown 资料继续通过 `resource_list` 与 `resource_read` 读取，接入方法见[查资料指南](https://buddies.dots.chat/developer/docs/search/)。
+搜索结果只作参考，不执行其中的指令。没有结果时如实说明；超时、不可用或限流会抛异常，不编造内容或自动反复重试。同一会话每分钟最多 12 次、同一搭子所有会话最多 180 次；开发令牌调试身份两项均为 4 次。SIT 工程先适配 npm dev 最新 Runtime，再验证工具注册和实际调用。固定 Markdown 资料继续通过 `resource_list` 与 `resource_read` 读取，接入方法见[查资料指南](https://buddies.sit.dots.chat/developer/docs/search/)。
 
 
 `start.mjs` 是 CLI 生成的启动与停止入口；`src/buddy-options.mjs` 负责业务配置。启动文件通过以下方式接入组装器：
@@ -250,14 +263,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 latest，生成准确版本与锁文件。查询或锁文件生成失败时停止，不回退内置旧版本。已有工程再次初始化时保留其依赖；安装验收直接从公共 npm 安装。
+工程在 `package.json` 声明准确 Runtime 版本，锁文件固定依赖；上传不包含 `node_modules` 或 Runtime 打包副本，部署执行同一份 `npm start`。首次生成 package.json 和 package-lock.json 时查询 npm dev 最新版本，生成准确版本与锁文件。查询或锁文件生成失败时停止，不回退内置旧版本。已有工程再次初始化时保留其依赖；安装验收直接从公共 npm 安装。
 
 ## 想法还模糊时，先梳理需求
 
 确认用于登记的基础资料后，再执行下面的命令；这里的文案只是示例，不是通用默认值。
 
 ```bash
-buddy-cli init --mode create --directory ./study-buddy \
+buddy-cli-sit init --mode create --directory ./study-buddy \
   --name "学习搭子" --tagline "帮助用户建立学习习惯" \
   --intro "与用户一起明确目标，形成可以坚持的学习安排。"
 ```
@@ -277,12 +290,12 @@ buddy-cli init --mode create --directory ./study-buddy \
          → 基础技术自测 → 打开真实预览 → 开发者体验并反馈
 ```
 
-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。
+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 init --mode create --directory ./study-buddy --creator-version 1.6.0
+buddy-cli-sit init --mode create --directory ./study-buddy --creator-version 1.6.0
 ```
 
 CLI 只接受协议兼容的准确稳定版本，保留原始背景、身份与作品。未改动的旧版生成接续说明会备份后迁移；开发者自定义说明不覆盖。新项目下载失败会报错并保留登记身份，可在同目录重试。
@@ -291,7 +304,7 @@ CLI 只接受协议兼容的准确稳定版本，保留原始背景、身份与
 
 ```bash
 BUDDY_CREATOR_SKILL_PATH=/absolute/path/buddy-creator-skill \
-  buddy-cli init --mode create --directory ./study-buddy
+  buddy-cli-sit init --mode create --directory ./study-buddy
 ```
 
 本地来源同样记录在项目中，适合 Skill 开发，不要求发布。要切回 npm，清除环境变量并显式指定 `--creator-version`。Python 执行仍需 3.9+，不安装 Python 第三方依赖。阶段与创作规则由 Skill 的 `references/cli-workflow.md` 管理，CLI 只处理身份、目录和有效交付后的开发接续。
@@ -303,7 +316,7 @@ BUDDY_CREATOR_SKILL_PATH=/absolute/path/buddy-creator-skill \
 手册完成后，Coding Agent 用下面的命令补齐官方 Runtime 工程，再据手册实现功能；这不是 Creator Skill 自己执行的操作：
 
 ```bash
-buddy-cli init --mode direct --directory ./study-buddy
+buddy-cli-sit init --mode direct --directory ./study-buddy
 ```
 
 创作阶段的 `package.json` 只有顶层 `buddyId`；CLI 用它从平台读取最新资料并重新校验归属，不另建搭子。创作中断后可以在原目录重试 `--mode create`，继续使用原作品；手册完成后执行 `--mode direct`，保留已有业务代码与数据声明，补齐 npm 字段和缺失的工程文件；缺失 `data-access.json` 时生成空 requirements 数组。旧 `--mode interview` 已停止使用。
@@ -327,10 +340,10 @@ Creator 例外保留首次创作背景快照，用于接续同一作品；恢复
 登记后用 `meta` 查看云端资料，用 `meta update` 修改名称、介绍或替换头像：
 
 ```bash
-buddy-cli meta
-buddy-cli meta update --name "川大厨" --tagline "帮你安排每天吃什么"
-buddy-cli meta update --intro "根据食材、人数和口味推荐菜谱"
-buddy-cli meta update --avatar ./avatar.png
+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
 ```
 
 `meta` 只读，修改时必须带 `update` 并至少提供一个字段。多个修改参数可以组合，未传字段保持原样，包括云端已有的扩展资料。文字字段不能为空，名称最多 60 字，一句话介绍最多 200 字，完整介绍最多 10000 字。头像只上传替换，不提供清除选项；支持静态 PNG、JPEG、WebP，最大 5 MiB。Server 校验图片并生成地址，处理失败时保留原头像。
@@ -338,8 +351,8 @@ buddy-cli meta update --avatar ./avatar.png
 默认向上寻找 `package.json.buddyId`，也可用 `--directory ./cooking-buddy` 指定工程；图片路径始终相对执行命令的当前目录。创作阶段只有身份清单时也能使用，无需安装或启动 Runtime。工程外可直接指定平台 ID：
 
 ```bash
-buddy-cli meta --buddy-id b_example
-buddy-cli meta update --buddy-id b_example --name "川大厨" --avatar ./avatar.png
+buddy-cli-sit meta --buddy-id b_example
+buddy-cli-sit 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。
@@ -350,17 +363,17 @@ buddy-cli meta update --buddy-id b_example --name "川大厨" --avatar ./avatar.
 
 ## 为这个搭子选一个模型
 
-进入工程开发时，新业务工厂必须由开发者明确选择模型。交互终端会展示工程 Runtime 的模型目录；Coding Agent 先列出可用模型并询问开发者，再用 `buddy-cli init --mode direct --model <已确认模型 ID>` 继续。非交互缺少选择或模型不受支持时，CLI 停止，不登记新身份或生成工程。create 路线在手册完成、进入 direct 开发时确认模型。
+进入工程开发时，新业务工厂必须由开发者明确选择模型。交互终端会展示工程 Runtime 的模型目录；Coding Agent 先列出可用模型并询问开发者，再用 `buddy-cli-sit init --mode direct --model <已确认模型 ID>` 继续。非交互缺少选择或模型不受支持时，CLI 停止，不登记新身份或生成工程。create 路线在手册完成、进入 direct 开发时确认模型。
 
 已有 `src/buddy-options.mjs` 保留原模型，恢复时不传 `--model`；如需更换，先确认，再修改业务工厂。明确确认过的同一选择不重复询问。
 
 ```bash
-buddy-cli models
+buddy-cli-sit models
 ```
 
-不必先创建工程。无论是否在工程内，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。
+无论工程内外，均读取公共 npm dev 最新 Runtime 的目录。缓存按准确版本保存，命令不修改工程依赖。JSON 中 `latestRuntimeVersion` 表示 dev 标签的最新版本，`projectRuntimeVersion` 为工程版本；不匹配时 `adaptationRequired` 为 true。
 
-在已有工程执行 `buddy-cli`、`init` 或打开 `preview` 时检查更新并提示适配，但允许继续编辑工程。正式包中，`dev`、Preview 中每次启动 DEV、文件自动重载，以及 `push` 必须联网查询 npm 最新稳定版，工程声明及实际安装版本必须与本次查询结果完全一致；不接受旧版、超前版、预发布版或范围依赖。查询失败即停止，不使用缓存冒充最新，也没有跳过检查参数。已有 npm 锁文件需与目标版本一致，push 还会按本次查询结果校验实际上传快照及其中的 npm 锁文件。失败信息包含原因和适配提示，CLI 不自动修改工程依赖、模型或数据权限。修复后重新启动；自动重载失败后保存文件可重试。帮助、登录、status、meta 和兼容命令 avatar 不查询 Runtime。
+在已有工程执行 `buddy-cli-sit`、`init` 或打开 `preview` 时检查 npm dev 最新 Runtime。`dev`、Preview 启动 DEV、自动重载和 `push` 要求准确声明、实际安装和锁文件与最新 dev 版本一致；npm 查询失败时停止。CLI 不自动修改依赖、模型和数据权限。工程版本不匹配时，安装提示中的准确版本、完成适配后重试。帮助、登录、status、meta 和兼容命令 avatar 不查询 Runtime。
 
 此限制由本版 CLI 执行，不修改服务端策略或已部署进程；直接运行工程 `npm start`、旧 CLI 或服务端发布入口不受本版 CLI 检查约束。
 
@@ -391,43 +404,43 @@ initialState: {
 }
 ```
 
-新工程生成 `{ "requirements": [] }`。最多 32 项，ID 不能重复；`id`、`purpose` 会去除首尾空白，用途必须为 1～200 字。完整选项由 `buddy-cli datasets [--json]` 按当前环境的版本规则读取，DEV 与 push 使用工程安装的 SDK 校验 ID。
+新工程生成 `{ "requirements": [] }`。最多 32 项，ID 不能重复；`id`、`purpose` 会去除首尾空白，用途必须为 1～200 字。完整选项由 `buddy-cli-sit 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, 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, memberId?, idempotencyKey })`；只申请已声明的 1～8 项数据。
 
 只有 `available` 携带数据；`notDeclared` 要修正工程声明，`systemPermissionDenied` 需要用户检查 App 的系统权限，`unavailable` 表示暂无可用结果，不代表用户拒绝。位置与日历的快照过期时由平台尝试请求在线 App 刷新；浏览器模拟器提示去 App 处理授权，CLI 不采集设备数据。
 
 ## 在模拟器里聊一次
 
-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` 仍自动打开后台，`--no-open` 不与 `--local` 混用。
+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 校验工程身份，后台验证账号与搭子归属。同一电脑、同一工程已有连接时，新命令复用它并退出，由原 CLI 继续维持连接；请保持原终端运行。连接其他电脑或工程前，请先退出原 CLI。
 
 后台显示「未连接本地工程」「已连接但 DEV 未启动」「DEV 运行中」。CLI 主动发起 HTTPS 连接，后台通过受限调试接口控制本机 Runtime，浏览器不需访问 localhost。工程路径用于显示连接身份，源码不会经调试通道上传。连接每 500 ms 交换待处理请求；持续中断 10 秒停止 DEV，后台最迟约 17 秒显示断开；短暂断网恢复后手动启动 DEV；若后台已结束或撤销连接，CLI 会退出，需要重新执行连接指令。页面刷新只恢复状态，CLI 退出停止 DEV 并断开。
 
-后台暂不可用时，用 `buddy-cli preview --local` 打开独立本地备用预览，可加 `--port`。后台模式不使用固定本地端口，不需要公网隧道。预览不会提审或发布。
+后台暂不可用时，用 `buddy-cli-sit preview --local` 打开独立本地备用预览，可加 `--port`。后台模式不使用固定本地端口，不需要公网隧道。预览不会提审或发布。
 
 以下两个命令按需选择，不必同时启动同一个工程：
 
 ```bash
-buddy-cli dev --directory ./study-buddy
-buddy-cli preview --directory ./study-buddy
+buddy-cli-sit dev --directory ./study-buddy
+buddy-cli-sit preview --directory ./study-buddy
 ```
 
 ### 停止 DEV 与强制断连（CLI 0.18.0 起）
 
 - `dev` 运行本机 Runtime；`preview` 维持后台与工程的连接，在页面启动 DEV 后才运行 Runtime。
-- 「停止 DEV」或在工程目录执行 `buddy-cli dev stop`：停止 Runtime 和文件监听，已有 preview 连接保留，不重新启动。
+- 「停止 DEV」或在工程目录执行 `buddy-cli-sit dev stop`：停止 Runtime 和文件监听，已有 preview 连接保留，不重新启动。
 - Ctrl+C、SIGTERM 或关闭终端（SIGHUP）：停止 CLI 管理的 Runtime 进程组，释放锁并断开后台连接。
 - 后台「强制断连」：先阻止新的调试操作，尝试停止该工程的 DEV，再撤销连接；旧 CLI 不能自动接回。页面会明确显示本机是否已确认停止。
 - CLI 被强杀、电脑离线或旧版进程无法响应时，网页不能保证本机进程已退出。到原电脑的工程目录执行后台提供的停止指令，例如：
 
 ```bash
-buddy-cli dev stop --buddy-id b_example --app-server https://buddies.dots.chat
+buddy-cli-sit dev stop --buddy-id b_example --app-server https://buddies.sit.dots.chat
 ```
 
 `dev stop` 无需登录、查询 npm 或访问平台，支持 `--directory`；按平台和工程 buddyId 查找本机进程。原 CLI 存活时通知它停止监听与 Runtime，原 CLI 已退出时核对进程身份后清理残留；不能确认身份时保留锁并报错，不误杀其他进程。同一搭子从其他目录启动时，应在提示的原工程目录执行。其他电脑的进程需到那台电脑停止。清理后如需调试，重新执行连接指令，再在页面启动 DEV；不会提审或发布。
@@ -444,7 +457,11 @@ buddy-cli dev stop --buddy-id b_example --app-server https://buddies.dots.chat
 
 回合列表按“第几轮、开始时间、状态”显示，默认跟随最新回合。选择历史回合或点击上一轮、下一轮后，会停留在所选回合，并同步切换各调试面板；勾选“跟随最新回合”可恢复跟随。完整执行 ID 可单独复制。编号只表示本次预览服务记录的顺序，不是聊天消息序号；列表保留最近 100 轮，旧记录移出后也不会重新编号。
 
-Preview 展示平台对话记录、发送与流式输出耗时、会话状态和协议事件。调试页中的协议日志也会显示 Runtime 的 stdout/stderr，包括启动失败和工具报错；凭据会遮蔽，超长单行截断，最多保留最近 300 条事件。模型内部上下文、Memory 操作与 Tool 轨迹需要 Runtime 提供结构化调试契约后再接入。
+Preview 连接工程后，无需发送消息即可在「工程信息」查看模型、在「工具列表」查看已注册工具的用途与参数。CLI 沿 `start.mjs` 的工厂引用只读现有 JavaScript 源码，支持常量、局部工厂、对象/数组展开和常见 TypeBox Schema；不执行业务代码、不读取 `.env` 来推测配置、不新增工程配置文件。已有标准工程直接适用，无需为此升级 Runtime。保存后自动刷新，环境变量、会话条件、动态注册、不支持的语法和 Runtime 按模型追加的工具明确标注待确认。工具的动态描述或参数也会标明未完整读取。
+
+Preview 展示平台对话记录、发送与流式输出耗时、会话状态和协议事件。左侧调试记录按最新在前展示；右侧聊天保持正常会话顺序。模型调用读取 Runtime 已有的请求和响应日志，展示实际模型、请求工具、响应中的工具名称与参数，可按工具调用或文本响应筛选。模型选择工具不等于工具已经执行成功；执行结果以对应运行日志和对话记录为准。无法解析或超限的记录保留原始日志并明确标记，不推断缺失参数。
+
+调试页显示 Runtime 的 stdout/stderr，包括启动失败和工具报错；凭据会遮蔽，单行及单条模型日志最多保留 98,304 个字符，超限标记截断。模型日志最多保留最近 200 条并受总容量约束；协议事件最多保留最近 300 条。历史消息和流式回复支持 Markdown 加粗等行内格式。
 
 工具执行记录里没有正文时不显示空气泡，有正文时保留可见内容；平台仍处于 replying 时，不会因工具记录或中途正文而提前结束回合。
 
@@ -456,27 +473,25 @@ Preview 展示平台对话记录、发送与流式输出耗时、会话状态和
 
 ### 正式包的平台与 Runtime
 
-正式包固定连接 PROD：`https://buddies.dots.chat`，后台为 `https://buddies.dots.chat/developer/`。无需手动设置 `MLB_GATEWAY_URL`，也不询问开发或发布环境。
+SIT 包固定连接 SIT：`https://buddies.sit.dots.chat`，后台为 `https://buddies.sit.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`。已知 ECS 工程按下述规则自动连接 PROD；SIT 或其他环境使用对应 CLI，不复制 `.env`、buddyId 或凭据。`--refresh-token` 仅刷新同一环境的开发凭据。
+- 创建或恢复工程、读取或修改工程资料、预览、DEV 和上传都会检查工程 `.env`。其他环境工程请使用对应 CLI；迁移到公共平台需在新目录重新登记搭子后复制业务代码，不复制 `.env`、buddyId 或凭据。`--refresh-token` 仅刷新同一环境的开发凭据。
 - 登录态按平台 origin 保存，开发 Token 与本地实例锁继续按平台和搭子隔离。不读取旧的无平台归属登录记录。CLI 地址限制不代替 Server 的账号、归属及凭据环境校验。
 
-已知 ECS 的 HTTPS 地址及两个旧 HTTP 入口支持自动连接 PROD：先验证原登录态与同一 buddyId 的归属，再在 DEV 启动时更新 `.env`。保留业务配置和注释，身份校验或网络失败时不改文件；登录态过期时需正常登录。详见 [原工程连接 PROD](../../docs/ecs-to-prod.md)。
+临时保留同一 ECS 的旧入口迁移：`http://47.116.168.81:8788` 和 `http://47.116.168.81` 转为 HTTPS。启动 DEV 时校验归属，取得实例锁后更新 `.env`，保留业务配置与注释；失败不改文件。正式推广完成后可移除此兼容分支。
 
-`models`、`datasets` 和新建工程动态查询公共 npm 的 Runtime `latest`，只接受正式版本；新工程固定准确版本与锁文件。DEV、自动重载及 push 要求工程声明、实际安装和锁文件与本次最新正式版一致；不提供 `--runtime-version` 或测试版选择，不自动修改已有依赖。CLI 与 Runtime 的版本号无需一致。Runtime 发布者须在 PROD 支持对应能力后才更新 `latest`。
+`models`、`datasets` 统一读取 npm dev 最新 Runtime 的目录。新建工程自动解析并固定准确版本，不提供 Runtime 版本选择；已有工程不自动改依赖。DEV 和 push 要求准确声明、安装和锁文件与最新 dev 版本一致，开发者或 Coding Agent 应按提示更新依赖并验证业务兼容性。
 
-正式 CLI 自动更新也只查询 `latest`；若该标签误指向预发布版本，停止并提示发布者修正，不跨到测试渠道。
+SIT CLI 只查询自身包的 dev 标签，遇到稳定版本或其他预发布命名会拒绝更新；不会安装正式包。
 
 ## 上传程序包，不等于发布
 
-上传后 CLI 显示构建状态，并最多等待 60 秒。构建失败显示原因；未完成或查询失败时用 `buddy-cli status` 重查，不重复上传。构建完成后仍需在后台手动发布。
-
 ```bash
-buddy-cli push --directory ./study-buddy --commit "根据完成情况调整练习难度"
-buddy-cli status --directory ./study-buddy
+buddy-cli-sit push --directory ./study-buddy --commit "根据完成情况调整练习难度"
+buddy-cli-sit status --directory ./study-buddy
 ```
 
 `push` 收集包含顶层 `buddyId` 的 `package.json`、`data-access.json`、源码和依赖锁文件，生成 `tar.gz`，上传到 `/cli/buddies/:id/packages/push`。`commit` 是改动说明，与本地 Git 是否提交无关。版本由 MLB 返回，CLI 不上传自己生成的 tag 或提审时间戳。
@@ -518,18 +533,18 @@ CLI 不提供 `release`、`publish`、`disable`、`enable` 或 `unpublish`。最
 
 参考 Creator 已确认的需求、原型和设计说明，在 `widgets/<小挂件类型>/` 中编写 `index.html` 和 `schema.json`，并在搭子业务中接入创建、读写和发送能力。
 
-使用 `buddy-cli preview` 调试页面与交互，修改后重启 DEV；准备上传时运行 `buddy-cli push`。Runtime 启动时读取小挂件文件并上传平台。开发步骤见仓库 `docs/widgets/design-delivery.md`。
+使用 `buddy-cli-sit preview` 调试页面与交互，修改后重启 DEV；准备上传时运行 `buddy-cli-sit push`。Runtime 启动时读取小挂件文件并上传平台。开发步骤见仓库 `docs/widgets/design-delivery.md`。
 
 ## 查看数据集，不依赖 Coding Agent
 
 工程内外均可直接查询最新目录，不要求先安装工程依赖：
 
 ```bash
-buddy-cli datasets
-buddy-cli datasets --directory ./my-buddy --json
+buddy-cli-sit datasets
+buddy-cli-sit datasets --directory ./my-buddy --json
 ```
 
-正式包的目录来自 npm 最新稳定版 Runtime 的 `DATA_ACCESS_CAPABILITIES`，包括 ID、名称、来源和 Schema 版本。JSON 返回版本信息、适配状态和 `datasets` 数组（字段见上方模型目录说明）。命令不登录、不启动搭子、不申请权限，也不修改配置；从子目录运行会向上找到工程。每次都需要联网检查 latest，下载失败时明确报错，不把旧缓存称为最新版。
+目录来自npm dev 最新 Runtime 的 `DATA_ACCESS_CAPABILITIES`，包括 ID、名称、来源和 Schema 版本。JSON 返回版本信息、适配状态和 `datasets` 数组（字段见上方模型目录说明）。命令不登录、不启动搭子、不申请权限，也不修改配置；从子目录运行会向上找到工程。每次都需要联网查询 dev 最新版本，下载失败时明确报错，不把旧缓存称为最新版。
 
 开发者将实际选择的 ID 和用途写进 `data-access.json.requirements`。JSON Schema 检查形状与用途；DEV 和上传预检按工程安装的 Runtime 检查所选模型与非空数据声明。目录缺失、依赖未安装或版本不匹配时明确报错。Runtime 0.12.2 有 10 项，但单次数据查询仍最多 8 项。
 
@@ -541,13 +556,13 @@ Preview 文本发送采用 App WebSocket 的 `messages` 数组，并校验逐项
 
 同一个搭子的开发者共享开发 Token 和 `<buddyId>-dev` 身份；同一开发身份仍只能保持一条 Runtime 事件流。正式身份使用另一把 Token，两者互不顶替。开发凭据没有自动过期时间，Server 重置或删除搭子后才失效。
 
-开发 Token 被平台重置后，停止当前 CLI，再运行 `buddy-cli dev --refresh-token` 或 `buddy-cli preview --refresh-token`。这会跳过本地开发凭据，重新领取服务端当前的开发 Token 并更新 `.env`，不在 Server 生成新密钥。工程启动不再从旧版 Keychain 的开发 Token 缓存领取凭据。
+开发 Token 被平台重置后，停止当前 CLI，再运行 `buddy-cli-sit dev --refresh-token` 或 `buddy-cli-sit 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 的 `.env` 也可使用。后续复用前向 Server 核对 Token；`--refresh-token` 重新领取后更新此文件。开发者登录凭据仍使用系统凭据存储。`.env` 加入 Git 忽略，且始终排除在上传包之外。
+首次启动 DEV 时，CLI 将开发版 `BUDDY_TOKEN` 和 `MLB_GATEWAY_URL` 写入工程 `.env`，保留其他配置和注释，移除旧 `BUDDY_ID` 赋值。身份始终来自 `package.json.buddyId`；只有 Token 而没有网关的旧配置不会复用 Token，将重新校验搭子归属并领取当前环境凭据。后续复用前向 Server 核对 Token；`--refresh-token` 重新领取后更新此文件。开发者登录凭据仍使用系统凭据存储。`.env` 加入 Git 忽略，且始终排除在上传包之外。
 
 CLI、Preview 与标准 `npm start` 均由 Node 的 `--env-file-if-exists=.env` 加载本地配置，Runtime 从 `package.json.buddyId` 读取身份、从环境变量读取 Token 和网关；托管时平台注入的同名环境变量优先。已有工程显式升级 Runtime 后，CLI 只自动迁移能精确识别的生成入口及标准启动命令，自定义业务代码和脚本保留。
 
@@ -569,4 +584,22 @@ Runtime 0.19.0 支持在 `schema.json.openTargets` 声明入口。业务通过 `
 
 ## CLI 0.20：MLB 统一提供服务
 
-正式包入口固定与 PROD 网页同源，使用 HTTPS。CLI 的一次性浏览器授权走 `/cli/web/authorizations`、`/cli/web/exchange`，预览连接走 `/cli/preview/*`。不调用独立 Web 服务，不支持地址覆盖；预览不触发上传或发布。
+正式包入口固定与 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` 查询，不能重复上传当作查询。审核通过、构建就绪和线上发布是不同状态，发布仍需在后台手动完成。
+
+DEV 要同时看到 Runtime 初始化完成和服务端在线后才就绪。SIT 后台的 Widget 编辑需配套 Server 和 Web 部署，支持 Schema 授权的记录操作、图片上传与关闭后的聚合通知；API 和错误处理见 [编辑指南](../../docs/preview/widgets.md)。iOS 编辑桥接和付费服务不在本版范围。