@my-life-buddies/cli 0.22.0 → 0.23.0-dev.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +95 -62
  2. package/dist/bin/buddy.js +88 -70
  3. package/dist/bin/buddy.js.map +4 -4
  4. package/dist/bin/core.js +629 -475
  5. package/dist/bin/core.js.map +4 -4
  6. package/dist/web/app.js +2 -2
  7. package/package.json +8 -7
package/README.md CHANGED
@@ -1,10 +1,10 @@
1
- # buddy-cli 使用说明
1
+ # buddy-cli-sit 使用说明
2
2
 
3
- 创作者提供的参考素材应在开发主体时同步接入。使用 `buddy-cli knowledge sync --plan .buddy/knowledge/plan.json` 生成分章节 Markdown、可读目录和来源映射；源资料更新时保留手工修改。计划格式见 `buddy-cli knowledge --help`，完整流程见[运行知识接入](../../docs/cli/knowledge.md)。本功能只写本地文件，不增加 push 检查或自动上传。
3
+ 创作者提供的参考素材应在开发主体时同步接入。使用 `buddy-cli-sit knowledge sync --plan .buddy/knowledge/plan.json` 生成分章节 Markdown、可读目录和来源映射；源资料更新时保留手工修改。计划格式见 `buddy-cli-sit knowledge --help`，完整流程见[运行知识接入](../../docs/cli/knowledge.md)。本功能只写本地文件，不增加 push 检查或自动上传。
4
4
 
5
5
  这份说明按一次开发过程展开：登记搭子，准备工程，在本地预览，然后上传程序包。所有搭子统一使用 `@my-life-buddies/buddy-runtime`，业务能力通过 Prompt、`src/buddy-options.mjs` 和 Tool 实现。
6
6
 
7
- 新建工程动态查询公共 npm 的最新稳定版 Runtime，并写入准确版本与锁文件；查询或锁文件生成失败时停止，不回退旧版本。版本选择与联调范围见 [Runtime 集成说明](../../docs/runtime-integration.md)。
7
+ 新建工程先询问开发者使用哪个 Runtime，再动态查询公共 npm 的所选版本，并写入准确版本与锁文件；查询或锁文件生成失败时停止，不回退旧版本。版本选择与联调范围见 [Runtime 集成说明](../../docs/runtime-integration.md)。
8
8
 
9
9
  ## 准备 CLI 和平台地址
10
10
 
@@ -14,21 +14,36 @@ CLI 发布目标为公共 Registry `https://registry.npmjs.org/`。已有仓库
14
14
 
15
15
  ```bash
16
16
  npm install
17
- npm run buddy-cli -- --help
17
+ npm run buddy-cli-sit -- --help
18
18
  ```
19
19
 
20
- 下文统一使用 `buddy-cli`。源码运行时替换为 `npm run buddy-cli --`；从公共 npm 安装已发布版本：
20
+ 下文统一使用 `buddy-cli-sit`。源码运行时替换为 `npm run buddy-cli-sit --`；从公共 npm 安装已发布版本：
21
+
22
+ ```bash
23
+ npm install --global --prefix "$HOME/.local/share/buddy-cli/sit" @my-life-buddies/cli@dev --registry=https://registry.npmjs.org/
24
+ export PATH="$HOME/.local/share/buddy-cli/sit/bin:$PATH"
25
+ ```
26
+
27
+ ### 与正式版共存
28
+
29
+ 只使用一个 npm 包名 `@my-life-buddies/cli`。`latest` 提供 `buddy-cli`（ECS Test）；`dev` 提供 `buddy-cli-sit`（SIT）。SIT 按上面的 `--prefix` 命令安装在独立目录；正式版可保留原有全局安装：
21
30
 
22
31
  ```bash
23
32
  npm install --global @my-life-buddies/cli@latest --registry=https://registry.npmjs.org/
33
+ buddy-cli --version
34
+ buddy-cli-sit --version
24
35
  ```
25
36
 
37
+ `--global --prefix` 只向指定目录安装包及命令，不覆盖系统默认全局目录。将 `export PATH="$HOME/.local/share/buddy-cli/sit/bin:$PATH"` 加入 `~/.zshrc`，新终端也可直接使用 SIT 命令。不要把两个渠道安装到同一个 prefix。
38
+
39
+ 已有 `@my-life-buddies/cli-dev` 的用户，先卸载该旧独立包（按原安装位置卸载），再按上面的命令安装 `@my-life-buddies/cli@dev`。不删除搭子工程或登录凭据。后续仅维护同一包的两个标签。
40
+
26
41
  ### 查看帮助与开发指引
27
42
 
28
43
  ```bash
29
- buddy-cli --help
30
- buddy-cli init --help
31
- buddy-cli guide
44
+ buddy-cli-sit --help
45
+ buddy-cli-sit init --help
46
+ buddy-cli-sit guide
32
47
  ```
33
48
 
34
49
  `--help` 列出命令，`<命令> --help` 说明当前命令的参数、限制和示例。`guide` 输出 Coding Agent 的完整开发指引，包括创作开场、资料确认、Skill 接续、实现和交付规则；无需工程或登录，先联网自检并按需自动更新 CLI，再输出新版指引，不修改工程文件。让 Agent 开始工作前先读取 `guide`，再按 CLI 返回的 `HANDOFF.md` 继续当前工程。HANDOFF 只包含当前工程、Skill 路径和接续方式，通用规则以 guide 为准；已生成文件在正常恢复创作时校验、备份并更新，CLI 升级不会直接覆盖工程里的 HANDOFF。`guide --help` 只显示该命令的简短用法。
@@ -40,23 +55,23 @@ buddy-cli guide
40
55
  ### 查看版本和更新 CLI
41
56
 
42
57
  ```bash
43
- buddy-cli --version
44
- buddy-cli update --check
45
- buddy-cli update
58
+ buddy-cli-sit --version
59
+ buddy-cli-sit update --check
60
+ buddy-cli-sit update
46
61
  ```
47
62
 
48
- `--version`（也可写作 `-v`）显示当前运行的 CLI 版本，无需联网。`update --check` 查询公共 npm 的 `latest` 版本，只检查、不安装；`update` 有新版本时安装检查到的准确版本，完成后核验安装结果。版本相同或本机版本更高时不安装、不降级。这三个用法均无需登录搭搭账号或进入搭子工程，从 CLI 0.8.0 开始支持。旧版用户先用上面的 npm 命令升级。
63
+ `--version`（也可写作 `-v`）显示当前运行的 CLI 版本，无需联网。`update --check` 查询 `@my-life-buddies/cli` 的 npm `dev` 版本，只检查、不安装；`update` 有新版本时安装检查到的准确版本，完成后核验安装结果。版本相同或本机版本更高时不安装、不降级。这三个用法均无需登录搭搭账号或进入搭子工程，从 CLI 0.8.0 开始支持。旧版用户先用上面的 npm 命令升级。
49
64
 
50
- 从 CLI 0.17.0 起，每条正常命令（含 `guide` 和无参数入口）先查询公共 npm `latest`，当前版本落后时自动更新，并由新版执行原命令。无需手动先运行 `update`，等待当前命令完成即可。更新发生在创建工程、领取凭据、启动 DEV 或上传之前；保留参数、工作目录、终端输入输出和退出状态，一次调用最多自动切换一次。版本相同或更高时继续执行，不降级；已经运行的 DEV 不因新版本发布而中断。
65
+ 从 CLI 0.17.0 起，每条正常命令（含 `guide` 和无参数入口）先查询 CLI 的公共 npm `dev` 标签，当前版本落后时自动更新，并由新版执行原命令。无需手动先运行 `update`，等待当前命令完成即可。更新发生在创建工程、领取凭据、启动 DEV 或上传之前；保留参数、工作目录、终端输入输出和退出状态，一次调用最多自动切换一次。版本相同或更高时继续执行，不降级；已经运行的 DEV 不因新版本发布而中断。
51
66
 
52
- 全局安装更新当前 npm 环境中对应的 CLI；源码、`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`。
67
+ 全局安装及通过 `--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`。
53
68
 
54
69
  更新只针对 CLI，已有工程的 Runtime 依赖、锁文件和业务适配仍需另行修改与验证。旧 CLI 不会自动获得自检能力，需要先用 npm 安装命令升级一次。
55
70
 
56
71
  可追加 `--json` 供 Coding Agent 或脚本读取，例如：
57
72
 
58
73
  ```bash
59
- buddy-cli update --check --json
74
+ buddy-cli-sit update --check --json
60
75
  ```
61
76
 
62
77
  检查结果包含 `package`、`currentVersion`、`latestVersion`、`updateAvailable` 和 `status`。`status` 为 `update_available`、`up_to_date` 或 `ahead`；更新成功时为 `updated`，另有 `installedVersion`，`updateAvailable` 为 `false`。失败时输出 `error`。检查成功（包括发现更新）返回退出码 0，查询或安装失败返回 1，参数错误返回 2。JSON 输出不会混入 npm 进度文字。
@@ -68,20 +83,20 @@ buddy-cli update --check --json
68
83
  ```bash
69
84
  npm run check
70
85
  npm run verify:package
71
- npm publish --workspace @my-life-buddies/cli
86
+ npm publish --workspace @my-life-buddies/cli --tag dev
72
87
  ```
73
88
 
74
- `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 不进入安装依赖。根工作区和 Web 同样保持 `private`。
89
+ `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 不进入安装依赖。根工作区和 Web 同样保持 `private`。
75
90
 
76
91
  版本维护：每批修改 CLI 发布内容时递增一次版本，默认 patch；根包和内部工作区版本、依赖引用、锁文件一起更新。Agent 工程自己的项目版本独立。升级 Runtime 时同步模板依赖与模板锁文件，并运行独立安装验收。
77
92
 
78
- 正式版 CLI 固定连接 ECS Test `https://47.116.168.81`，无需配置地址：
93
+ SIT CLI 固定连接 SIT `https://buddies.sit.dots.chat`，无需配置地址：
79
94
 
80
95
  ```bash
81
- buddy-cli login
96
+ buddy-cli-sit login
82
97
  ```
83
98
 
84
- 这是实际的 ECS Test 环境，使用 HTTPS；不能改为其他平台或本机网关。手机 App 需要连接同一环境。
99
+ 这是实际的 SIT 环境，使用 HTTPS；不能改为其他平台或本机网关。手机 App 需要连接同一环境。
85
100
 
86
101
  CLI 会打开搭搭创作者平台网页完成登录和授权。浏览器已有有效 Cookie 时，页面直接显示当前账号，开发者确认后即可返回终端；没有登录时，先在同一网页完成短信登录，再确认授权。CLI 不读取浏览器 Cookie，也拿不到短信验证码，只通过本机回调收到一次性授权码，再换取自己的会话。
87
102
 
@@ -96,7 +111,7 @@ CLI 会把换取到的会话保存到 macOS Keychain。有效会话会复用，
96
111
  | `--version [--json]` | 不需要，也不登录 | 显示当前运行的 CLI 版本，无需联网 |
97
112
  | `update [--check] [--json]` | 不需要，也不登录 | 检查公共 npm 最新版，或更新 npm 全局 CLI |
98
113
  | `login`、`logout` | 不需要 | 管理账号会话 |
99
- | `models` | 不需要，也不登录 | 始终联网读取 npm 最新 Runtime 的模型目录，提示工程版本差异；支持 `--directory`、`--json` |
114
+ | `models` | 不需要，也不登录 | 始终联网读取 npm 选定 Runtime 的模型目录，提示工程版本差异；支持 `--directory`、`--json` |
100
115
  | `init` | 目标目录可以是空目录或已有官方工程 | 登记或恢复云端身份，准备本地文件 |
101
116
  | `dev`、`preview`、`push` | 需要有效清单和完整工程文件 | 运行、调试或打包该工程 |
102
117
  | `status` | 需要含 `buddyId` 的 `package.json` | 查询该搭子的云端状态；创作尚未完成时也可使用 |
@@ -113,13 +128,13 @@ CLI 会把换取到的会话保存到 macOS Keychain。有效会话会复用，
113
128
 
114
129
  `init --mode create` 和 `init --mode direct` 都先保存本地资料草稿。Coding Agent 读取 CLI 返回的 `.buddy/meta/HANDOFF.md`，完整读取独立下载的 `@my-life-buddies/avatar-creator-skill/SKILL.md` 和配套规范，用宿主图片生成能力生成、检查并展示头像。开发者确认实际头像及名称、一句话介绍、详细介绍后，才调用 Meta 创建接口。
115
130
 
116
- 只有需要生成头像时才下载 `@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 负责确认与上传。
131
+ 只有需要生成头像时才下载 `@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 负责确认与上传。
117
132
 
118
133
  Skill 维护者可本地联调（无需发布）：
119
134
 
120
135
  ```bash
121
136
  BUDDY_AVATAR_SKILL_PATH=/absolute/path/avatar-creator-skill \
122
- buddy-cli init --mode create --directory ./my-buddy
137
+ buddy-cli-sit init --mode create --directory ./my-buddy
123
138
  ```
124
139
 
125
140
  本地来源会记录在头像 Skill 锁中；切回 npm 时清除环境变量，并显式传入 `--avatar-skill-version`。首次下载失败会保留草稿，可在同目录重试，也可提供已有图片完成登记。
@@ -128,14 +143,14 @@ BUDDY_AVATAR_SKILL_PATH=/absolute/path/avatar-creator-skill \
128
143
  普通终端不会执行 skill，也不要求安装 Coding Agent：选择本地图片后会打开资料与头像预览，再询问是否确认登记。没有图片或暂不确认时保留草稿，退出码为 2，稍后在原目录继续。
129
144
 
130
145
  ```bash
131
- buddy-cli init --mode direct --directory "<搭子工程目录>" --avatar "<头像文件路径>"
146
+ buddy-cli-sit init --mode direct --runtime-version "<已确认的版本>" --directory "<搭子工程目录>" --avatar "<头像文件路径>"
132
147
  ```
133
148
 
134
149
  非交互调用必须由宿主先取得开发者明确确认，再传 `--avatar "<已确认图片路径>" --confirm-meta`。该标志声明开发者确认了本次资料和实际图片；不能把“帮我创建搭子”当作头像确认。CLI 不生成图片、不推断对话授权，也不以示例图替代新头像。
135
150
 
136
151
  `.buddy/meta/` 保存草稿、候选图片、预览与接续说明，push 不上传。上传失败保留已创建的 buddyId，重试复用原身份；已有云端头像不会在恢复中被覆盖。Meta 创建响应丢失时会明确暂停，核对后台身份后用 `--buddy-id` 恢复，避免重复创建。
137
152
 
138
- 基础资料和头像的确认不等于 Creator 四册已确认。已有搭子的恢复沿用原身份和云端头像；明确需要更换头像时使用 `buddy-cli meta update --avatar`。
153
+ 基础资料和头像的确认不等于 Creator 四册已确认。已有搭子的恢复沿用原身份和云端头像；明确需要更换头像时使用 `buddy-cli-sit meta update --avatar`。
139
154
 
140
155
  ## 需求明确时，直接开发
141
156
 
@@ -144,7 +159,7 @@ buddy-cli init --mode direct --directory "<搭子工程目录>" --avatar "<头
144
159
  直接生成官方 Runtime 工程：
145
160
 
146
161
  ```bash
147
- buddy-cli init --mode direct --directory ./study-buddy \
162
+ buddy-cli-sit init --mode direct --runtime-version "<已确认的版本>" --directory ./study-buddy \
148
163
  --name "学习搭子" --tagline "把学习目标拆成每天能完成的小步骤" \
149
164
  --intro "根据学习目标与每日反馈，帮助用户安排练习并复盘。"
150
165
  ```
@@ -196,7 +211,7 @@ widgets/
196
211
 
197
212
  `schema.json` 的顶层是 `{ "description": "...", "modules": { ... } }`，各模块包含 `description` 和 `record`；`record` 才是该模块记录的 JSON Schema。不要直接把一份普通 JSON Schema 当作整个类型定义。
198
213
 
199
- CLI 将 HTML 和 Schema 随工程源码打包。工程安装的 Runtime 在 BuddyServer 启动时读取 `widgets/`，通过 `PUT /internal/v1/widget-types/:typeId` 一起上传 Schema 与 HTML；全部成功后才连接事件流。缺文件、无效 JSON 或平台拒绝上传会使启动失败，具体原因可在终端或 Preview 日志中查看。平台需要已部署该接口。
214
+ CLI 将 HTML 和 Schema 随工程源码打包。工程安装的 Runtime 在 BuddyServer 启动时读取 `widgets/`，通过 `PUT /internal/v1/widget-types/:typeId` 一起上传 Schema 与 HTML；先连接事件流，再完成这些上传；全部成功后才就绪。缺文件、无效 JSON 或平台拒绝上传会使启动失败，具体原因可在终端或 Preview 日志中查看。平台需要已部署该接口。
200
215
 
201
216
  模型使用小挂件工具时，在 `src/buddy-options.mjs` 的 `initialState.tools` 中加入 `conversation.tools.widget_create`、`conversation.tools.widget_write_record` 等工具；业务代码也可直接调用 `conversation.widget`，主动服务回合禁止写操作。类型按上传进程的 Buddy 身份保存，DEV 分身与正式版隔离。修改文件后重启 Runtime；删除或改名目录不会删除平台上的旧类型。Preview 可展示小挂件卡片、会话列表与 H5 页面。
202
217
 
@@ -233,14 +248,14 @@ import createBuddyOptions from "./src/buddy-options.mjs";
233
248
  await BuddyServer.start(createBuddyOptions);
234
249
  ```
235
250
 
236
- 工程在 `package.json` 声明准确 Runtime 版本，锁文件固定依赖；上传不包含 `node_modules` 或 Runtime 打包副本，部署执行同一份 `npm start`。首次生成 package.json 和 package-lock.json 时查询公共 npm latest，生成准确版本与锁文件。查询或锁文件生成失败时停止，不回退内置旧版本。已有工程再次初始化时保留其依赖；安装验收直接从公共 npm 安装。
251
+ 工程在 `package.json` 声明准确 Runtime 版本，锁文件固定依赖；上传不包含 `node_modules` 或 Runtime 打包副本，部署执行同一份 `npm start`。首次生成 package.json 和 package-lock.json 时查询用户选择的 npm 版本，生成准确版本与锁文件。查询或锁文件生成失败时停止，不回退内置旧版本。已有工程再次初始化时保留其依赖；安装验收直接从公共 npm 安装。
237
252
 
238
253
  ## 想法还模糊时，先梳理需求
239
254
 
240
255
  确认用于登记的基础资料后，再执行下面的命令；这里的文案只是示例，不是通用默认值。
241
256
 
242
257
  ```bash
243
- buddy-cli init --mode create --directory ./study-buddy \
258
+ buddy-cli-sit init --mode create --directory ./study-buddy \
244
259
  --name "学习搭子" --tagline "帮助用户建立学习习惯" \
245
260
  --intro "与用户一起明确目标，形成可以坚持的学习安排。"
246
261
  ```
@@ -260,12 +275,12 @@ buddy-cli init --mode create --directory ./study-buddy \
260
275
  → 基础技术自测 → 打开真实预览 → 开发者体验并反馈
261
276
  ```
262
277
 
263
- 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。
278
+ 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。
264
279
 
265
280
  显式升级某个项目：
266
281
 
267
282
  ```bash
268
- buddy-cli init --mode create --directory ./study-buddy --creator-version 1.6.0
283
+ buddy-cli-sit init --mode create --directory ./study-buddy --creator-version 1.6.0
269
284
  ```
270
285
 
271
286
  CLI 只接受协议兼容的准确稳定版本，保留原始背景、身份与作品。未改动的旧版生成接续说明会备份后迁移；开发者自定义说明不覆盖。新项目下载失败会报错并保留登记身份，可在同目录重试。
@@ -274,7 +289,7 @@ CLI 只接受协议兼容的准确稳定版本，保留原始背景、身份与
274
289
 
275
290
  ```bash
276
291
  BUDDY_CREATOR_SKILL_PATH=/absolute/path/buddy-creator-skill \
277
- buddy-cli init --mode create --directory ./study-buddy
292
+ buddy-cli-sit init --mode create --directory ./study-buddy
278
293
  ```
279
294
 
280
295
  本地来源同样记录在项目中，适合 Skill 开发，不要求发布。要切回 npm，清除环境变量并显式指定 `--creator-version`。Python 执行仍需 3.9+，不安装 Python 第三方依赖。阶段与创作规则由 Skill 的 `references/cli-workflow.md` 管理，CLI 只处理身份、目录和有效交付后的开发接续。
@@ -286,7 +301,7 @@ BUDDY_CREATOR_SKILL_PATH=/absolute/path/buddy-creator-skill \
286
301
  手册完成后，Coding Agent 用下面的命令补齐官方 Runtime 工程，再据手册实现功能；这不是 Creator Skill 自己执行的操作：
287
302
 
288
303
  ```bash
289
- buddy-cli init --mode direct --directory ./study-buddy
304
+ buddy-cli-sit init --mode direct --runtime-version "<已确认的版本>" --directory ./study-buddy
290
305
  ```
291
306
 
292
307
  创作阶段的 `package.json` 只有顶层 `buddyId`；CLI 用它从平台读取最新资料并重新校验归属，不另建搭子。创作中断后可以在原目录重试 `--mode create`，继续使用原作品；手册完成后执行 `--mode direct`，保留已有业务代码与数据声明，补齐 npm 字段和缺失的工程文件；缺失 `data-access.json` 时生成空 requirements 数组。旧 `--mode interview` 已停止使用。
@@ -310,10 +325,10 @@ Creator 例外保留首次创作背景快照，用于接续同一作品；恢复
310
325
  登记后用 `meta` 查看云端资料，用 `meta update` 修改名称、介绍或替换头像：
311
326
 
312
327
  ```bash
313
- buddy-cli meta
314
- buddy-cli meta update --name "川大厨" --tagline "帮你安排每天吃什么"
315
- buddy-cli meta update --intro "根据食材、人数和口味推荐菜谱"
316
- buddy-cli meta update --avatar ./avatar.png
328
+ buddy-cli-sit meta
329
+ buddy-cli-sit meta update --name "川大厨" --tagline "帮你安排每天吃什么"
330
+ buddy-cli-sit meta update --intro "根据食材、人数和口味推荐菜谱"
331
+ buddy-cli-sit meta update --avatar ./avatar.png
317
332
  ```
318
333
 
319
334
  `meta` 只读，修改时必须带 `update` 并至少提供一个字段。多个修改参数可以组合，未传字段保持原样，包括云端已有的扩展资料。文字字段不能为空，名称最多 60 字，一句话介绍最多 200 字，完整介绍最多 10000 字。头像只上传替换，不提供清除选项；支持静态 PNG、JPEG、WebP，最大 5 MiB。Server 校验图片并生成地址，处理失败时保留原头像。
@@ -321,8 +336,8 @@ buddy-cli meta update --avatar ./avatar.png
321
336
  默认向上寻找 `package.json.buddyId`，也可用 `--directory ./cooking-buddy` 指定工程；图片路径始终相对执行命令的当前目录。创作阶段只有身份清单时也能使用，无需安装或启动 Runtime。工程外可直接指定平台 ID：
322
337
 
323
338
  ```bash
324
- buddy-cli meta --buddy-id b_example
325
- buddy-cli meta update --buddy-id b_example --name "川大厨" --avatar ./avatar.png
339
+ buddy-cli-sit meta --buddy-id b_example
340
+ buddy-cli-sit meta update --buddy-id b_example --name "川大厨" --avatar ./avatar.png
326
341
  ```
327
342
 
328
343
  `--buddy-id` 和 `--directory` 不能同时使用。命令复用 CLI 登录态，由 Server 校验搭子归属。CLI 先通过 `GET /cli/buddies/:id` 获取最新资料，合并指定修改，再通过 `PUT /cli/buddies/:id/meta` 更新；含头像时使用 multipart，文字和图片通过校验后一起提交。头像地址由平台生成，文字更新不提交原头像 URL。
@@ -334,12 +349,12 @@ buddy-cli meta update --buddy-id b_example --name "川大厨" --avatar ./avatar.
334
349
  ## 为这个搭子选一个模型
335
350
 
336
351
  ```bash
337
- buddy-cli models
352
+ buddy-cli-sit models
338
353
  ```
339
354
 
340
- 不必先创建工程。无论是否在工程内，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。
355
+ 工程内读取准确 Runtime 依赖对应的目录；工程外先用 `--runtime-version <准确版本|latest|dev>` 选择版本。目录缓存按版本保存，不改工程依赖。JSON 中 `selectedRuntimeVersion` 表示选定版本，`latestRuntimeVersion` 为 null，工程匹配时 `versionStatus` 为 selected。
341
356
 
342
- 在已有工程执行 `buddy-cli`、`init` 或打开 `preview` 时检查更新并提示适配，但允许继续编辑工程。正式包中，`dev`、Preview 中每次启动 DEV、文件自动重载，以及 `push` 必须联网查询 npm 最新稳定版，工程声明及实际安装版本必须与本次查询结果完全一致；不接受旧版、超前版、预发布版或范围依赖。查询失败即停止，不使用缓存冒充最新，也没有跳过检查参数。已有 npm 锁文件需与目标版本一致，push 还会按本次查询结果校验实际上传快照及其中的 npm 锁文件。失败信息包含原因和适配提示，CLI 不自动修改工程依赖、模型或数据权限。修复后重新启动；自动重载失败后保存文件可重试。帮助、登录、status、meta 和兼容命令 avatar 不查询 Runtime。
357
+ 在已有工程执行 `buddy-cli-sit`、`init` 或打开 `preview` 时检查工程选定版本是否可用。`dev`、Preview 启动 DEV、自动重载和 `push` 校验准确声明、实际安装和锁文件一致；npm 查询失败时停止。已有工程不自动跟随 latest 或 dev 标签，也不自动修改依赖、模型和数据权限。切换 Runtime 先向开发者确认，显式安装准确版本、完成适配后重试。帮助、登录、status、meta 和兼容命令 avatar 不查询 Runtime。
343
358
 
344
359
  此限制由本版 CLI 执行，不修改服务端策略或已部署进程；直接运行工程 `npm start`、旧 CLI 或服务端发布入口不受本版 CLI 检查约束。
345
360
 
@@ -370,43 +385,43 @@ initialState: {
370
385
  }
371
386
  ```
372
387
 
373
- 新工程生成 `{ "requirements": [] }`。最多 32 项，ID 不能重复；`id`、`purpose` 会去除首尾空白，用途必须为 1～200 字。完整选项由 `buddy-cli datasets [--json]` 按当前环境的版本规则读取，DEV 与 push 使用工程安装的 SDK 校验 ID。
388
+ 新工程生成 `{ "requirements": [] }`。最多 32 项，ID 不能重复；`id`、`purpose` 会去除首尾空白，用途必须为 1～200 字。完整选项由 `buddy-cli-sit datasets [--json]` 按当前环境的版本规则读取，DEV 与 push 使用工程安装的 SDK 校验 ID。
374
389
 
375
390
  Runtime 0.17.0 启动时自动读取该文件，通过 `PUT /internal/v1/data-access/requirements` 登记；文件缺失或空数组会上传空声明，清除旧声明。登记失败阻止启动，不会带着未同步的配置上线。DEV 监听该文件，保存后重启 Runtime 并重新登记。部署环境需提供对应登记接口。
376
391
 
377
392
  CLI 将文件原样放入源码包，启动入口只调用 `BuddyServer.start(createBuddyOptions)`。Runtime 0.23.0 起，健康、位置和日历都通过 Dataset 查询，所需项目都要放入 `requirements`；声明不代表用户已授权，也不会自动启用工具。
378
393
 
379
- 在 `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 项数据。
394
+ 在 `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 项数据。
380
395
 
381
396
  只有 `available` 携带数据；`notDeclared` 要修正工程声明，`systemPermissionDenied` 需要用户检查 App 的系统权限，`unavailable` 表示暂无可用结果，不代表用户拒绝。位置与日历的快照过期时由平台尝试请求在线 App 刷新；浏览器模拟器提示去 App 处理授权，CLI 不采集设备数据。
382
397
 
383
398
  ## 在模拟器里聊一次
384
399
 
385
- 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` 混用。
400
+ 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` 混用。
386
401
 
387
402
  CLI 校验工程身份，后台验证账号与搭子归属。同一电脑、同一工程已有连接时，新命令复用它并退出，由原 CLI 继续维持连接；请保持原终端运行。连接其他电脑或工程前，请先退出原 CLI。
388
403
 
389
404
  后台显示「未连接本地工程」「已连接但 DEV 未启动」「DEV 运行中」。CLI 主动发起 HTTPS 连接，后台通过受限调试接口控制本机 Runtime，浏览器不需访问 localhost。工程路径用于显示连接身份，源码不会经调试通道上传。连接每 500 ms 交换待处理请求；持续中断 10 秒停止 DEV，后台最迟约 17 秒显示断开；短暂断网恢复后手动启动 DEV；若后台已结束或撤销连接，CLI 会退出，需要重新执行连接指令。页面刷新只恢复状态，CLI 退出停止 DEV 并断开。
390
405
 
391
- 后台暂不可用时，用 `buddy-cli preview --local` 打开独立本地备用预览，可加 `--port`。后台模式不使用固定本地端口，不需要公网隧道。预览不会提审或发布。
406
+ 后台暂不可用时，用 `buddy-cli-sit preview --local` 打开独立本地备用预览，可加 `--port`。后台模式不使用固定本地端口，不需要公网隧道。预览不会提审或发布。
392
407
 
393
408
  以下两个命令按需选择，不必同时启动同一个工程：
394
409
 
395
410
  ```bash
396
- buddy-cli dev --directory ./study-buddy
397
- buddy-cli preview --directory ./study-buddy
411
+ buddy-cli-sit dev --directory ./study-buddy
412
+ buddy-cli-sit preview --directory ./study-buddy
398
413
  ```
399
414
 
400
415
  ### 停止 DEV 与强制断连（CLI 0.18.0 起）
401
416
 
402
417
  - `dev` 运行本机 Runtime；`preview` 维持后台与工程的连接，在页面启动 DEV 后才运行 Runtime。
403
- - 「停止 DEV」或在工程目录执行 `buddy-cli dev stop`：停止 Runtime 和文件监听，已有 preview 连接保留，不重新启动。
418
+ - 「停止 DEV」或在工程目录执行 `buddy-cli-sit dev stop`：停止 Runtime 和文件监听，已有 preview 连接保留，不重新启动。
404
419
  - Ctrl+C、SIGTERM 或关闭终端（SIGHUP）：停止 CLI 管理的 Runtime 进程组，释放锁并断开后台连接。
405
420
  - 后台「强制断连」：先阻止新的调试操作，尝试停止该工程的 DEV，再撤销连接；旧 CLI 不能自动接回。页面会明确显示本机是否已确认停止。
406
421
  - CLI 被强杀、电脑离线或旧版进程无法响应时，网页不能保证本机进程已退出。到原电脑的工程目录执行后台提供的停止指令，例如：
407
422
 
408
423
  ```bash
409
- buddy-cli dev stop --buddy-id b_example --app-server https://47.116.168.81
424
+ buddy-cli-sit dev stop --buddy-id b_example --app-server https://buddies.sit.dots.chat
410
425
  ```
411
426
 
412
427
  `dev stop` 无需登录、查询 npm 或访问平台，支持 `--directory`；按平台和工程 buddyId 查找本机进程。原 CLI 存活时通知它停止监听与 Runtime，原 CLI 已退出时核对进程身份后清理残留；不能确认身份时保留锁并报错，不误杀其他进程。同一搭子从其他目录启动时，应在提示的原工程目录执行。其他电脑的进程需到那台电脑停止。清理后如需调试，重新执行连接指令，再在页面启动 DEV；不会提审或发布。
@@ -435,7 +450,7 @@ Preview 展示平台对话记录、发送与流式输出耗时、会话状态和
435
450
 
436
451
  ### 正式包的平台与 Runtime
437
452
 
438
- 正式包固定连接 ECS Test：`https://47.116.168.81`，后台为 `https://47.116.168.81/developer/`。无需手动设置 `MLB_GATEWAY_URL`，也不询问开发或发布环境。
453
+ SIT 包固定连接 SIT：`https://buddies.sit.dots.chat`，后台为 `https://buddies.sit.dots.chat/developer/`。无需手动设置 `MLB_GATEWAY_URL`，也不询问开发或发布环境。
439
454
 
440
455
  - 登录、API、凭据领取、预览与上传均使用固定目标；CLI 将该网关及开发 Token 写入工程 `.env` 给 Runtime 使用。
441
456
  - `--app-server`、`--developer-web` 仅接受同一固定目标，兼容已有后台连接指令，不能切换环境。
@@ -445,15 +460,15 @@ Preview 展示平台对话记录、发送与流式输出耗时、会话状态和
445
460
 
446
461
  临时保留同一 ECS 的旧入口迁移：`http://47.116.168.81:8788` 和 `http://47.116.168.81` 转为 HTTPS。启动 DEV 时校验归属，取得实例锁后更新 `.env`，保留业务配置与注释；失败不改文件。正式推广完成后可移除此兼容分支。
447
462
 
448
- `models`、`datasets` 和新建工程动态查询公共 npm 的 Runtime `latest`，只接受正式版本；新工程固定准确版本与锁文件。DEV、自动重载及 push 要求工程声明、实际安装和锁文件与本次最新正式版一致；不提供 `--runtime-version` 或测试版选择，不自动修改已有依赖。CLI 与 Runtime 的版本号无需一致。Runtime 发布者须在 ECS Test 支持对应能力后才更新 `latest`。
463
+ `models`、`datasets` 使用选定 Runtime 的目录。新建工程先由 Coding Agent 询问，再用 `--runtime-version <准确版本|latest|dev>` 动态解析并固定准确版本；已有工程不自动改依赖。DEV 和 push 检查准确声明、安装和锁文件一致。选择 dev 版前核对目标 SIT 能力，不因 npm 版本更高就认为服务端已支持。
449
464
 
450
- 正式 CLI 自动更新也只查询 `latest`；若该标签误指向预发布版本，停止并提示发布者修正，不跨到测试渠道。
465
+ SIT CLI 只查询自身包的 dev 标签，遇到稳定版本或其他预发布命名会拒绝更新；不会安装正式包。
451
466
 
452
467
  ## 上传程序包，不等于发布
453
468
 
454
469
  ```bash
455
- buddy-cli push --directory ./study-buddy --commit "根据完成情况调整练习难度"
456
- buddy-cli status --directory ./study-buddy
470
+ buddy-cli-sit push --directory ./study-buddy --commit "根据完成情况调整练习难度"
471
+ buddy-cli-sit status --directory ./study-buddy
457
472
  ```
458
473
 
459
474
  `push` 收集包含顶层 `buddyId` 的 `package.json`、`data-access.json`、源码和依赖锁文件，生成 `tar.gz`，上传到 `/cli/buddies/:id/packages/push`。`commit` 是改动说明，与本地 Git 是否提交无关。版本由 MLB 返回，CLI 不上传自己生成的 tag 或提审时间戳。
@@ -495,18 +510,18 @@ CLI 不提供 `release`、`publish`、`disable`、`enable` 或 `unpublish`。最
495
510
 
496
511
  参考 Creator 已确认的需求、原型和设计说明，在 `widgets/<小挂件类型>/` 中编写 `index.html` 和 `schema.json`，并在搭子业务中接入创建、读写和发送能力。
497
512
 
498
- 使用 `buddy-cli preview` 调试页面与交互，修改后重启 DEV；准备上传时运行 `buddy-cli push`。Runtime 启动时读取小挂件文件并上传平台。开发步骤见仓库 `docs/widgets/design-delivery.md`。
513
+ 使用 `buddy-cli-sit preview` 调试页面与交互，修改后重启 DEV；准备上传时运行 `buddy-cli-sit push`。Runtime 启动时读取小挂件文件并上传平台。开发步骤见仓库 `docs/widgets/design-delivery.md`。
499
514
 
500
515
  ## 查看数据集，不依赖 Coding Agent
501
516
 
502
517
  工程内外均可直接查询最新目录，不要求先安装工程依赖：
503
518
 
504
519
  ```bash
505
- buddy-cli datasets
506
- buddy-cli datasets --directory ./my-buddy --json
520
+ buddy-cli-sit datasets
521
+ buddy-cli-sit datasets --directory ./my-buddy --json
507
522
  ```
508
523
 
509
- 正式包的目录来自 npm 最新稳定版 Runtime 的 `DATA_ACCESS_CAPABILITIES`，包括 ID、名称、来源和 Schema 版本。JSON 返回版本信息、适配状态和 `datasets` 数组（字段见上方模型目录说明）。命令不登录、不启动搭子、不申请权限，也不修改配置；从子目录运行会向上找到工程。每次都需要联网检查 latest，下载失败时明确报错，不把旧缓存称为最新版。
524
+ 目录来自工程选定 Runtime 的 `DATA_ACCESS_CAPABILITIES`，包括 ID、名称、来源和 Schema 版本。JSON 返回版本信息、适配状态和 `datasets` 数组（字段见上方模型目录说明）。命令不登录、不启动搭子、不申请权限，也不修改配置；从子目录运行会向上找到工程。每次都需要联网确认选定版本，下载失败时明确报错，不把旧缓存称为最新版。
510
525
 
511
526
  开发者将实际选择的 ID 和用途写进 `data-access.json.requirements`。JSON Schema 检查形状与用途；DEV 和上传预检按工程安装的 Runtime 检查所选模型与非空数据声明。目录缺失、依赖未安装或版本不匹配时明确报错。Runtime 0.12.2 有 10 项，但单次数据查询仍最多 8 项。
512
527
 
@@ -518,13 +533,13 @@ Preview 文本发送采用 App WebSocket 的 `messages` 数组，并校验逐项
518
533
 
519
534
  同一个搭子的开发者共享开发 Token 和 `<buddyId>-dev` 身份；同一开发身份仍只能保持一条 Runtime 事件流。正式身份使用另一把 Token，两者互不顶替。开发凭据没有自动过期时间，Server 重置或删除搭子后才失效。
520
535
 
521
- 开发 Token 被平台重置后，停止当前 CLI，再运行 `buddy-cli dev --refresh-token` 或 `buddy-cli preview --refresh-token`。这会跳过本地开发凭据，重新领取服务端当前的开发 Token 并更新 `.env`，不在 Server 生成新密钥。工程启动不再从旧版 Keychain 的开发 Token 缓存领取凭据。
536
+ 开发 Token 被平台重置后，停止当前 CLI，再运行 `buddy-cli-sit dev --refresh-token` 或 `buddy-cli-sit preview --refresh-token`。这会跳过本地开发凭据，重新领取服务端当前的开发 Token 并更新 `.env`，不在 Server 生成新密钥。工程启动不再从旧版 Keychain 的开发 Token 缓存领取凭据。
522
537
 
523
538
  账号登录凭据仍保存在 macOS Keychain，不写入工程。开发 Token 保存在权限为 `0600` 的工程 `.env`，不传给 Web，也不进入上传包或命令行参数。
524
539
 
525
540
  ### 本地身份与连接配置
526
541
 
527
- 首次启动 DEV 时，CLI 将开发版 `BUDDY_TOKEN` 和 `MLB_GATEWAY_URL` 写入工程 `.env`，保留其他配置和注释，移除旧 `BUDDY_ID` 赋值。身份始终来自 `package.json.buddyId`；只配置 Token 的 `.env` 也可使用。后续复用前向 Server 核对 Token；`--refresh-token` 重新领取后更新此文件。开发者登录凭据仍使用系统凭据存储。`.env` 加入 Git 忽略，且始终排除在上传包之外。
542
+ 首次启动 DEV 时，CLI 将开发版 `BUDDY_TOKEN` 和 `MLB_GATEWAY_URL` 写入工程 `.env`，保留其他配置和注释，移除旧 `BUDDY_ID` 赋值。身份始终来自 `package.json.buddyId`；只有 Token 而没有网关的旧配置不会复用 Token，将重新校验搭子归属并领取当前环境凭据。后续复用前向 Server 核对 Token；`--refresh-token` 重新领取后更新此文件。开发者登录凭据仍使用系统凭据存储。`.env` 加入 Git 忽略，且始终排除在上传包之外。
528
543
 
529
544
  CLI、Preview 与标准 `npm start` 均由 Node 的 `--env-file-if-exists=.env` 加载本地配置，Runtime 从 `package.json.buddyId` 读取身份、从环境变量读取 Token 和网关；托管时平台注入的同名环境变量优先。已有工程显式升级 Runtime 后，CLI 只自动迁移能精确识别的生成入口及标准启动命令，自定义业务代码和脚本保留。
530
545
 
@@ -546,4 +561,22 @@ Runtime 0.19.0 支持在 `schema.json.openTargets` 声明入口。业务通过 `
546
561
 
547
562
  ## CLI 0.20：MLB 统一提供服务
548
563
 
549
- 正式包入口固定与 ECS Test 网页同源，使用 HTTPS。CLI 的一次性浏览器授权走 `/cli/web/authorizations`、`/cli/web/exchange`，预览连接走 `/cli/preview/*`。不调用独立 Web 服务，不支持地址覆盖；预览不触发上传或发布。
564
+ 正式包入口固定与 SIT 网页同源，使用 HTTPS。CLI 的一次性浏览器授权走 `/cli/web/authorizations`、`/cli/web/exchange`，预览连接走 `/cli/preview/*`。不调用独立 Web 服务，不支持地址覆盖；预览不触发上传或发布。
565
+
566
+ ## SIT 包与准确版本复现
567
+
568
+ ```sh
569
+ npm install --global --prefix "$HOME/.local/share/buddy-cli/sit" @my-life-buddies/cli@dev --registry=https://registry.npmjs.org/
570
+ export PATH="$HOME/.local/share/buddy-cli/sit/bin:$PATH"
571
+ buddy-cli-sit --version
572
+ # 复现某一版（必须与已安装版本完全匹配）
573
+ export BUDDY_CLI_PIN_VERSION=0.23.0-dev.1
574
+ buddy-cli-sit preview
575
+ unset BUDDY_CLI_PIN_VERSION
576
+ ```
577
+
578
+ SIT 平台固定为 `https://buddies.sit.dots.chat`。CLI 地址约束是客户端防误连机制；服务端仍须独立校验身份、Token 和权限，不是完整的服务端安全隔离。
579
+
580
+ SIT `push` 触发异步构建，显示 `building/ready/failed` 及失败原因，最多等待一分钟；仍在构建时用 `buddy-cli-sit status` 查询，不能重复上传当作查询。审核通过、构建就绪和线上发布是不同状态，发布仍需在后台手动完成。
581
+
582
+ DEV 要同时看到 Runtime 初始化完成和服务端在线后才就绪。Widget 编辑和付费服务本版暂不接入；Widget 编辑后续工作见仓库 `docs/todo/sit-widget-editing.md`。