@my-life-buddies/cli 0.26.2 → 0.27.1-dev.2

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 +117 -86
  2. package/dist/bin/buddy.js +47 -38
  3. package/dist/bin/buddy.js.map +2 -2
  4. package/dist/bin/core.js +375 -411
  5. package/dist/bin/core.js.map +4 -4
  6. package/dist/web/app.js +2 -2
  7. package/package.json +6 -6
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
- 空白工程模板不预置 Runtime 依赖或版本。新建工程动态查询公共 npm 的最新稳定版 Runtime，并写入准确版本与锁文件；查询或锁文件生成失败时停止，不回退旧版本。版本选择与联调范围见 [Runtime 集成说明](../../docs/runtime-integration.md)。
7
+ 空白工程模板不预置 Runtime 依赖或版本。新建工程统一查询公共 npm dev 最新 Runtime，并写入准确版本与锁文件，不提供版本选择；查询或锁文件生成失败时停止，不回退旧版本。版本策略与联调范围见 [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` 只显示该命令的简短用法。
@@ -42,23 +57,23 @@ Agent 按已确认需求判断是否需要联网查资料。需求没有说明
42
57
  ### 查看版本和更新 CLI
43
58
 
44
59
  ```bash
45
- buddy-cli --version
46
- buddy-cli update --check
47
- buddy-cli update
60
+ buddy-cli-sit --version
61
+ buddy-cli-sit update --check
62
+ buddy-cli-sit update
48
63
  ```
49
64
 
50
- `--version`（也可写作 `-v`）显示当前运行的 CLI 版本，无需联网。`update --check` 查询公共 npm 的 `latest` 版本，只检查、不安装；`update` 有新版本时安装检查到的准确版本，完成后核验安装结果。版本相同或本机版本更高时不安装、不降级。这三个用法均无需登录搭搭账号或进入搭子工程，从 CLI 0.8.0 开始支持。旧版用户先用上面的 npm 命令升级。
65
+ `--version`（也可写作 `-v`）显示当前运行的 CLI 版本，无需联网。`update --check` 查询 `@my-life-buddies/cli` 的 npm `dev` 版本，只检查、不安装；`update` 有新版本时安装检查到的准确版本，完成后核验安装结果。版本相同或本机版本更高时不安装、不降级。这三个用法均无需登录搭搭账号或进入搭子工程，从 CLI 0.8.0 开始支持。旧版用户先用上面的 npm 命令升级。
51
66
 
52
- 从 CLI 0.17.0 起，每条正常命令（含 `guide` 和无参数入口）先查询公共 npm `latest`，当前版本落后时自动更新，并由新版执行原命令。无需手动先运行 `update`，等待当前命令完成即可。更新发生在创建工程、领取凭据、启动 DEV 或上传之前；保留参数、工作目录、终端输入输出和退出状态，一次调用最多自动切换一次。版本相同或更高时继续执行，不降级；已经运行的 DEV 不因新版本发布而中断。
67
+ 从 CLI 0.17.0 起，每条正常命令（含 `guide` 和无参数入口）先查询 CLI 的公共 npm `dev` 标签，当前版本落后时自动更新，并由新版执行原命令。无需手动先运行 `update`，等待当前命令完成即可。更新发生在创建工程、领取凭据、启动 DEV 或上传之前；保留参数、工作目录、终端输入输出和退出状态，一次调用最多自动切换一次。版本相同或更高时继续执行，不降级；已经运行的 DEV 不因新版本发布而中断。
53
68
 
54
- 全局安装更新当前 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`。
69
+ 全局安装及通过 `--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`。
55
70
 
56
71
  更新只针对 CLI，已有工程的 Runtime 依赖、锁文件和业务适配仍需另行修改与验证。旧 CLI 不会自动获得自检能力，需要先用 npm 安装命令升级一次。
57
72
 
58
73
  可追加 `--json` 供 Coding Agent 或脚本读取，例如：
59
74
 
60
75
  ```bash
61
- buddy-cli update --check --json
76
+ buddy-cli-sit update --check --json
62
77
  ```
63
78
 
64
79
  检查结果包含 `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
70
85
  ```bash
71
86
  npm run release:check
72
87
  npm run release # 完整验证与演练
73
- npm run release -- --publish # 显式发包，PROD 验收记录为空时禁止发布
88
+ npm run release -- --publish # 显式发布当前 dev 分支到 npm dev
74
89
  ```
75
90
 
76
- 流程、CHANGELOG、tag 和 dev 合入规则见 [维护者发布规则](../../docs/releases.md)。当前 PROD 候选尚未发布；发布前须完成实际 PROD 验收。
77
-
78
- `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`。
91
+ `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`。
79
92
 
80
93
  版本维护：每批修改 CLI 发布内容时递增一次版本，默认 patch；根包和内部工作区版本、依赖引用、锁文件一起更新。Agent 工程自己的项目版本独立。Runtime 版本由创建时动态查询并锁定；发布前验证真实 Runtime 的动态解析和独立安装，不向空白模板写入基准版本。
81
94
 
82
- 正式版 CLI 固定连接 PROD `https://buddies.dots.chat`，无需配置地址：
95
+ SIT CLI 固定连接 SIT `https://buddies.sit.dots.chat`，无需配置地址：
83
96
 
84
97
  ```bash
85
- buddy-cli login
98
+ buddy-cli-sit login
86
99
  ```
87
100
 
88
- 这是实际的 PROD 环境，使用 HTTPS；不能改为其他平台或本机网关。手机 App 需要连接同一环境。
101
+ 这是实际的 SIT 环境，使用 HTTPS；不能改为其他平台或本机网关。手机 App 需要连接同一环境。
89
102
 
90
103
  CLI 会打开搭搭创作者平台网页完成登录和授权。浏览器已有有效 Cookie 时，页面直接显示当前账号，开发者确认后即可返回终端；没有登录时，先在同一网页完成短信登录，再确认授权。CLI 不读取浏览器 Cookie，也拿不到短信验证码，只通过本机回调收到一次性授权码，再换取自己的会话。
91
104
 
@@ -100,10 +113,12 @@ CLI 会把换取到的会话保存到 macOS Keychain。有效会话会复用，
100
113
  | `--version [--json]` | 不需要，也不登录 | 显示当前运行的 CLI 版本，无需联网 |
101
114
  | `update [--check] [--json]` | 不需要，也不登录 | 检查公共 npm 最新版，或更新 npm 全局 CLI |
102
115
  | `login`、`logout` | 不需要 | 管理账号会话 |
103
- | `models` | 不需要，也不登录 | 始终联网读取 npm 最新 Runtime 的模型目录，提示工程版本差异；支持 `--directory`、`--json` |
116
+ | `models` | 不需要，也不登录 | 始终联网读取 npm dev 最新 Runtime 的模型目录，提示工程版本差异；支持 `--directory`、`--json` |
104
117
  | `init` | 目标目录可以是空目录或已有官方工程 | 登记或恢复云端身份，准备本地文件 |
105
118
  | `dev`、`preview`、`push` | 需要有效清单和完整工程文件 | 运行、调试或打包该工程 |
106
119
  | `status` | 需要含 `buddyId` 的 `package.json` | 查询该搭子的云端状态；创作尚未完成时也可使用 |
120
+ | `products submit` | 需要含 `buddyId` 的 `package.json` | 对明确的已有搭子版本补提或单独提交选中商品 |
121
+ | `release` | 需要含 `buddyId` 的 `package.json` | 从原上传／补提回执确认发布，或显式只发布代码；查询、恢复、重试和取消原发布任务 |
107
122
  | `avatar` | 从工程读取身份，或用 `--buddy-id` 指定 | 上传本地图片或清除搭子头像，保留其他资料；无需 Runtime |
108
123
  | `datasets` | 不需要，也不登录 | 与 models 使用同一 Runtime 来源，读取它的数据目录；支持 `--directory`、`--json` |
109
124
 
@@ -117,13 +132,13 @@ CLI 会把换取到的会话保存到 macOS Keychain。有效会话会复用，
117
132
 
118
133
  `init --mode create` 和 `init --mode direct` 都先保存本地资料草稿。Coding Agent 读取 CLI 返回的 `.buddy/meta/HANDOFF.md`，完整读取独立下载的 `@my-life-buddies/avatar-creator-skill/SKILL.md` 和配套规范，用宿主图片生成能力生成、检查并展示头像。开发者确认实际头像及名称、一句话介绍、详细介绍后，才调用 Meta 创建接口。
119
134
 
120
- 只有需要生成头像时才下载 `@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 负责确认与上传。
135
+ 只有需要生成头像时才下载 `@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 负责确认与上传。
121
136
 
122
137
  Skill 维护者可本地联调（无需发布）：
123
138
 
124
139
  ```bash
125
140
  BUDDY_AVATAR_SKILL_PATH=/absolute/path/avatar-creator-skill \
126
- buddy-cli init --mode create --directory ./my-buddy
141
+ buddy-cli-sit init --mode create --directory ./my-buddy
127
142
  ```
128
143
 
129
144
  本地来源会记录在头像 Skill 锁中；切回 npm 时清除环境变量，并显式传入 `--avatar-skill-version`。首次下载失败会保留草稿，可在同目录重试，也可提供已有图片完成登记。
@@ -132,14 +147,14 @@ BUDDY_AVATAR_SKILL_PATH=/absolute/path/avatar-creator-skill \
132
147
  普通终端不会执行 skill，也不要求安装 Coding Agent：选择本地图片后会打开资料与头像预览，再询问是否确认登记。没有图片或暂不确认时保留草稿，退出码为 2，稍后在原目录继续。
133
148
 
134
149
  ```bash
135
- buddy-cli init --mode direct --directory "<搭子工程目录>" --avatar "<头像文件路径>"
150
+ buddy-cli-sit init --mode direct --directory "<搭子工程目录>" --avatar "<头像文件路径>"
136
151
  ```
137
152
 
138
153
  非交互调用必须由宿主先取得开发者明确确认，再传 `--avatar "<已确认图片路径>" --confirm-meta`。该标志声明开发者确认了本次资料和实际图片；不能把“帮我创建搭子”当作头像确认。CLI 不生成图片、不推断对话授权，也不以示例图替代新头像。
139
154
 
140
155
  `.buddy/meta/` 保存草稿、候选图片、预览与接续说明，push 不上传。上传失败保留已创建的 buddyId，重试复用原身份；已有云端头像不会在恢复中被覆盖。Meta 创建响应丢失时会明确暂停，核对后台身份后用 `--buddy-id` 恢复，避免重复创建。
141
156
 
142
- 基础资料和头像的确认不等于 Creator 需求手册已确认。已有搭子的恢复沿用原身份和云端头像；明确需要更换头像时使用 `buddy-cli meta update --avatar`。
157
+ 基础资料和头像的确认不等于 Creator 需求手册已确认。已有搭子的恢复沿用原身份和云端头像；明确需要更换头像时使用 `buddy-cli-sit meta update --avatar`。
143
158
 
144
159
  ## 需求明确时，直接开发
145
160
 
@@ -148,7 +163,7 @@ buddy-cli init --mode direct --directory "<搭子工程目录>" --avatar "<头
148
163
  直接生成官方 Runtime 工程：
149
164
 
150
165
  ```bash
151
- buddy-cli init --mode direct --directory ./study-buddy \
166
+ buddy-cli-sit init --mode direct --directory ./study-buddy \
152
167
  --name "学习搭子" --tagline "把学习目标拆成每天能完成的小步骤" \
153
168
  --intro "根据学习目标与每日反馈，帮助用户安排练习并复盘。"
154
169
  ```
@@ -200,11 +215,11 @@ widgets/
200
215
 
201
216
  `schema.json` 的顶层是 `{ "description": "...", "modules": { ... } }`，各模块包含 `description` 和 `record`；`record` 才是该模块记录的 JSON Schema。不要直接把一份普通 JSON Schema 当作整个类型定义。
202
217
 
203
- CLI 将 HTML 和 Schema 随工程源码打包。工程安装的 Runtime 在 BuddyServer 启动时读取 `widgets/`，通过 `PUT /internal/v1/widget-types/:typeId` 一起上传 Schema 与 HTML；CLI 同时等待初始化完成与平台在线，才报告 DEV 就绪。缺文件、无效 JSON 或平台拒绝上传会使启动失败，具体原因可在终端或 Preview 日志中查看。平台需要已部署该接口。
218
+ CLI 将 HTML 和 Schema 随工程源码打包。工程安装的 Runtime 在 BuddyServer 启动时读取 `widgets/`，通过 `PUT /internal/v1/widget-types/:typeId` 一起上传 Schema 与 HTML；先连接事件流，再完成这些上传；全部成功后才就绪。缺文件、无效 JSON 或平台拒绝上传会使启动失败，具体原因可在终端或 Preview 日志中查看。平台需要已部署该接口。
204
219
 
205
- 模型使用小挂件工具时，在 `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)。
220
+ 模型使用小挂件工具时，在 `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)。
206
221
 
207
- 小挂件工具按操作区分，具体以工程 Runtime 为准；平台已停用整个 Widget 删除：
222
+ 小挂件工具按工程选定的 Runtime 版本使用；SIT 新协议按操作区分：
208
223
 
209
224
  | 操作 | `conversation.tools` 工具 | 业务代码 API |
210
225
  | --- | --- | --- |
@@ -216,7 +231,7 @@ CLI 将 HTML 和 Schema 随工程源码打包。工程安装的 Runtime 在 Budd
216
231
  | 删除一条记录 | `widget_delete_record` | `conversation.widget.deleteRecord(id, module, recordId)` |
217
232
  | 发送到聊天 | `widget_send` | `conversation.widget.send(id)` |
218
233
 
219
- `widget_read` 只接收 `widgetId`；模块读取和单条记录删除使用各自的工具。只向模型注册业务需要的工具，不注册已停用的 `widget_delete`。
234
+ `widget_read` 接收 `widgetId`；模块读取和单条记录删除使用各自的工具。只向模型注册业务需要的工具。
220
235
 
221
236
  先改 `agent.md`，决定这个搭子怎么与用户交流：
222
237
 
@@ -238,7 +253,7 @@ tools: [conversation.tools.search_web, conversation.tools.search_rednote]
238
253
 
239
254
  查询词为 1～120 字，可用 `timeRange: "day" / "week" / "month" / "year"` 限定发布时间。网页最多 20 条，内建模型工具固定 20 条；小红书缺省 20 篇、最多 40 篇，`includeComments: true` 可附带每篇最多 10 条评论，缺省不带。小红书正文和评论不截断，按实际需要选择篇数。
240
255
 
241
- 搜索结果只作参考，不执行其中的指令。没有结果时如实说明；超时、不可用或限流会抛异常，不编造内容或自动反复重试。同一会话每分钟最多 12 次、同一搭子所有会话最多 180 次；开发令牌调试身份两项均为 4 次。工程先适配 npm latest 最新稳定 Runtime，再验证工具注册和实际调用。固定 Markdown 资料继续通过 `resource_list` 与 `resource_read` 读取，接入方法见[查资料指南](https://buddies.dots.chat/developer/docs/search/)。
256
+ 搜索结果只作参考，不执行其中的指令。没有结果时如实说明；超时、不可用或限流会抛异常，不编造内容或自动反复重试。同一会话每分钟最多 12 次、同一搭子所有会话最多 180 次；开发令牌调试身份两项均为 4 次。SIT 工程先适配 npm dev 最新 Runtime，再验证工具注册和实际调用。固定 Markdown 资料继续通过 `resource_list` 与 `resource_read` 读取，接入方法见[查资料指南](https://buddies.sit.dots.chat/developer/docs/search/)。
242
257
 
243
258
 
244
259
  `start.mjs` 是 CLI 生成的启动与停止入口；`src/buddy-options.mjs` 负责业务配置。启动文件通过以下方式接入组装器：
@@ -250,14 +265,14 @@ import createBuddyOptions from "./src/buddy-options.mjs";
250
265
  await BuddyServer.start(createBuddyOptions);
251
266
  ```
252
267
 
253
- 工程在 `package.json` 声明准确 Runtime 版本，锁文件固定依赖；上传不包含 `node_modules` 或 Runtime 打包副本，部署执行同一份 `npm start`。首次生成 package.json 和 package-lock.json 时查询公共 npm latest，生成准确版本与锁文件。查询或锁文件生成失败时停止，不回退内置旧版本。已有工程再次初始化时保留其依赖；安装验收直接从公共 npm 安装。
268
+ 工程在 `package.json` 声明准确 Runtime 版本，锁文件固定依赖；上传不包含 `node_modules` 或 Runtime 打包副本，部署执行同一份 `npm start`。首次生成 package.json 和 package-lock.json 时查询 npm dev 最新版本，生成准确版本与锁文件。查询或锁文件生成失败时停止，不回退内置旧版本。已有工程再次初始化时保留其依赖；安装验收直接从公共 npm 安装。
254
269
 
255
270
  ## 想法还模糊时，先梳理需求
256
271
 
257
272
  确认用于登记的基础资料后，再执行下面的命令；这里的文案只是示例，不是通用默认值。
258
273
 
259
274
  ```bash
260
- buddy-cli init --mode create --directory ./study-buddy \
275
+ buddy-cli-sit init --mode create --directory ./study-buddy \
261
276
  --name "学习搭子" --tagline "帮助用户建立学习习惯" \
262
277
  --intro "与用户一起明确目标，形成可以坚持的学习安排。"
263
278
  ```
@@ -277,7 +292,7 @@ buddy-cli init --mode create --directory ./study-buddy \
277
292
  → 基础技术自测 → 打开真实预览 → 开发者体验并反馈
278
293
  ```
279
294
 
280
- 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。
295
+ CLI 0.15.0 起，Creator 使用独立 npm 包 `@my-life-buddies/buddy-creator-skill`。每次进入或恢复创作都查询公共 npm latest 最新正式版，校验后缓存到 `~/.cache/buddy-cli-sit/creator-skills/buddy-creator-skill/<版本>/`，在 `.buddy/creator/skill-lock.json` 记录本次准确版本与完整性摘要。只有查证缓存对应最新版后才复用；版本记录不会阻止升级，恢复时也需要联网。Skill 负责人独立发包，不再要求重发 CLI。
281
296
 
282
297
  不再提供 `--creator-version` 固定版本入口。CLI 查询 latest 后验证协议及完整性，保留原始背景、身份与作品。未改动的旧版生成接续说明会备份后迁移；开发者自定义说明不覆盖。查询、下载或协议校验失败都会报错，不退回旧缓存；已有资料和登记身份保留，可在同目录重试。
283
298
 
@@ -285,7 +300,7 @@ CLI 0.15.0 起，Creator 使用独立 npm 包 `@my-life-buddies/buddy-creator-sk
285
300
 
286
301
  ```bash
287
302
  BUDDY_CREATOR_SKILL_PATH=/absolute/path/buddy-creator-skill \
288
- buddy-cli init --mode create --directory ./study-buddy
303
+ buddy-cli-sit init --mode create --directory ./study-buddy
289
304
  ```
290
305
 
291
306
  本地来源同样记录在项目中，仅用于显式 Skill 联调，不要求发布。每次联调都需要提供该环境变量；清除后会查询公共 npm latest，不因旧的本地版本记录继续使用本地目录。Python 执行仍需 3.9+，不安装 Python 第三方依赖。阶段与创作规则由 Skill 的 `references/cli-workflow.md` 管理，CLI 只处理身份、目录和有效交付后的开发接续。
@@ -299,7 +314,7 @@ BUDDY_CREATOR_SKILL_PATH=/absolute/path/buddy-creator-skill \
299
314
  手册完成后，Coding Agent 用下面的命令补齐官方 Runtime 工程，再据手册实现功能；这不是 Creator Skill 自己执行的操作：
300
315
 
301
316
  ```bash
302
- buddy-cli init --mode direct --directory ./study-buddy
317
+ buddy-cli-sit init --mode direct --directory ./study-buddy
303
318
  ```
304
319
 
305
320
  创作阶段的 `package.json` 只有顶层 `buddyId`；CLI 用它从平台读取最新资料并重新校验归属，不另建搭子。创作中断后在原目录重试 `--mode create`，检查最新 Creator 后接续原作品；手册完成后执行 `--mode direct`，保留已有业务代码与数据声明，补齐 npm 字段和缺失的工程文件；缺失 `data-access.json` 时生成空 requirements 数组。旧 `--mode interview` 已停止使用。
@@ -323,10 +338,10 @@ Creator 例外保留首次创作背景快照，用于接续同一作品；恢复
323
338
  登记后用 `meta` 查看云端资料，用 `meta update` 修改名称、介绍或替换头像：
324
339
 
325
340
  ```bash
326
- buddy-cli meta
327
- buddy-cli meta update --name "川大厨" --tagline "帮你安排每天吃什么"
328
- buddy-cli meta update --intro "根据食材、人数和口味推荐菜谱"
329
- buddy-cli meta update --avatar ./avatar.png
341
+ buddy-cli-sit meta
342
+ buddy-cli-sit meta update --name "川大厨" --tagline "帮你安排每天吃什么"
343
+ buddy-cli-sit meta update --intro "根据食材、人数和口味推荐菜谱"
344
+ buddy-cli-sit meta update --avatar ./avatar.png
330
345
  ```
331
346
 
332
347
  `meta` 只读，修改时必须带 `update` 并至少提供一个字段。多个修改参数可以组合，未传字段保持原样，包括云端已有的扩展资料。文字字段不能为空，名称最多 60 字，一句话介绍最多 200 字，完整介绍最多 10000 字。头像只上传替换，不提供清除选项；支持静态 PNG、JPEG、WebP，最大 5 MiB。Server 校验图片并生成地址，处理失败时保留原头像。
@@ -334,8 +349,8 @@ buddy-cli meta update --avatar ./avatar.png
334
349
  默认向上寻找 `package.json.buddyId`，也可用 `--directory ./cooking-buddy` 指定工程；图片路径始终相对执行命令的当前目录。创作阶段只有身份清单时也能使用，无需安装或启动 Runtime。工程外可直接指定平台 ID：
335
350
 
336
351
  ```bash
337
- buddy-cli meta --buddy-id b_example
338
- buddy-cli meta update --buddy-id b_example --name "川大厨" --avatar ./avatar.png
352
+ buddy-cli-sit meta --buddy-id b_example
353
+ buddy-cli-sit meta update --buddy-id b_example --name "川大厨" --avatar ./avatar.png
339
354
  ```
340
355
 
341
356
  `--buddy-id` 和 `--directory` 不能同时使用。命令复用 CLI 登录态，由 Server 校验搭子归属。CLI 先通过 `GET /cli/buddies/:id` 获取最新资料，合并指定修改，再通过 `PUT /cli/buddies/:id/meta` 更新；含头像时使用 multipart，文字和图片通过校验后一起提交。头像地址由平台生成，文字更新不提交原头像 URL。
@@ -346,17 +361,17 @@ buddy-cli meta update --buddy-id b_example --name "川大厨" --avatar ./avatar.
346
361
 
347
362
  ## 为这个搭子选一个模型
348
363
 
349
- 进入工程开发时，新业务工厂必须由开发者明确选择模型。交互终端会展示工程 Runtime 的模型目录；Coding Agent 先列出可用模型并询问开发者，再用 `buddy-cli init --mode direct --model <已确认模型 ID>` 继续。非交互缺少选择或模型不受支持时，CLI 停止，不登记新身份或生成工程。create 路线在手册完成、进入 direct 开发时确认模型。
364
+ 进入工程开发时，新业务工厂必须由开发者明确选择模型。交互终端会展示工程 Runtime 的模型目录；Coding Agent 先列出可用模型并询问开发者，再用 `buddy-cli-sit init --mode direct --model <已确认模型 ID>` 继续。非交互缺少选择或模型不受支持时，CLI 停止，不登记新身份或生成工程。create 路线在手册完成、进入 direct 开发时确认模型。
350
365
 
351
366
  已有 `src/buddy-options.mjs` 保留原模型，恢复时不传 `--model`；如需更换，先确认，再修改业务工厂。明确确认过的同一选择不重复询问。
352
367
 
353
368
  ```bash
354
- buddy-cli models
369
+ buddy-cli-sit models
355
370
  ```
356
371
 
357
- 不必先创建工程。无论是否在工程内，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。
372
+ 无论工程内外，均读取公共 npm dev 最新 Runtime 的目录。缓存按准确版本保存，命令不修改工程依赖。JSON 中 `latestRuntimeVersion` 表示 dev 标签的最新版本，`projectRuntimeVersion` 为工程版本；不匹配时 `adaptationRequired` 为 true。
358
373
 
359
- 在已有工程执行 `buddy-cli`、`init` 或打开 `preview` 时检查更新并提示适配，但允许继续编辑工程。正式包中，`dev`、Preview 中每次启动 DEV、文件自动重载，以及 `push` 必须联网查询 npm 最新稳定版，工程声明及实际安装版本必须与本次查询结果完全一致；不接受旧版、超前版、预发布版或范围依赖。查询失败即停止，不使用缓存冒充最新，也没有跳过检查参数。已有 npm 锁文件需与目标版本一致，push 还会按本次查询结果校验实际上传快照及其中的 npm 锁文件。失败信息包含原因和适配提示，CLI 不自动修改工程依赖、模型或数据权限。修复后重新启动；自动重载失败后保存文件可重试。帮助、登录、status、meta 和兼容命令 avatar 不查询 Runtime。
374
+ 在已有工程执行 `buddy-cli-sit`、`init` 或打开 `preview` 时检查 npm dev 最新 Runtime。`dev`、Preview 启动 DEV、自动重载和 `push` 要求准确声明、实际安装和锁文件与最新 dev 版本一致；npm 查询失败时停止。CLI 不自动修改依赖、模型和数据权限。工程版本不匹配时，安装提示中的准确版本、完成适配后重试。帮助、登录、status、meta 和兼容命令 avatar 不查询 Runtime。
360
375
 
361
376
  此限制由本版 CLI 执行，不修改服务端策略或已部署进程；直接运行工程 `npm start`、旧 CLI 或服务端发布入口不受本版 CLI 检查约束。
362
377
 
@@ -387,43 +402,43 @@ initialState: {
387
402
  }
388
403
  ```
389
404
 
390
- 新工程生成 `{ "requirements": [] }`。最多 32 项，ID 不能重复；`id`、`purpose` 会去除首尾空白，用途必须为 1～200 字。完整选项由 `buddy-cli datasets [--json]` 按当前环境的版本规则读取，DEV 与 push 使用工程安装的 SDK 校验 ID。
405
+ 新工程生成 `{ "requirements": [] }`。最多 32 项，ID 不能重复；`id`、`purpose` 会去除首尾空白，用途必须为 1～200 字。完整选项由 `buddy-cli-sit datasets [--json]` 按当前环境的版本规则读取，DEV 与 push 使用工程安装的 SDK 校验 ID。
391
406
 
392
407
  Runtime 0.17.0 启动时自动读取该文件，通过 `PUT /internal/v1/data-access/requirements` 登记；文件缺失或空数组会上传空声明，清除旧声明。登记失败阻止启动，不会带着未同步的配置上线。DEV 监听该文件，保存后重启 Runtime 并重新登记。部署环境需提供对应登记接口。
393
408
 
394
409
  CLI 将文件原样放入源码包，启动入口只调用 `BuddyServer.start(createBuddyOptions)`。Runtime 0.23.0 起，健康、位置和日历都通过 Dataset 查询，所需项目都要放入 `requirements`；声明不代表用户已授权，也不会自动启用工具。
395
410
 
396
- 在 `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 项数据。
411
+ 在 `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 项数据。
397
412
 
398
413
  只有 `available` 携带数据；`notDeclared` 要修正工程声明，`systemPermissionDenied` 需要用户检查 App 的系统权限，`unavailable` 表示暂无可用结果，不代表用户拒绝。位置与日历的快照过期时由平台尝试请求在线 App 刷新；浏览器模拟器提示去 App 处理授权，CLI 不采集设备数据。
399
414
 
400
415
  ## 在模拟器里聊一次
401
416
 
402
- 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` 混用。
417
+ 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` 混用。
403
418
 
404
419
  CLI 校验工程身份，后台验证账号与搭子归属。同一电脑、同一工程已有连接时，新命令复用它并退出，由原 CLI 继续维持连接；请保持原终端运行。连接其他电脑或工程前，请先退出原 CLI。
405
420
 
406
421
  后台显示「未连接本地工程」「已连接但 DEV 未启动」「DEV 运行中」。CLI 主动发起 HTTPS 连接，后台通过受限调试接口控制本机 Runtime，浏览器不需访问 localhost。工程路径用于显示连接身份，源码不会经调试通道上传。连接每 500 ms 交换待处理请求；持续中断 10 秒停止 DEV，后台最迟约 17 秒显示断开；短暂断网恢复后手动启动 DEV；若后台已结束或撤销连接，CLI 会退出，需要重新执行连接指令。页面刷新只恢复状态，CLI 退出停止 DEV 并断开。
407
422
 
408
- 后台暂不可用时，用 `buddy-cli preview --local` 打开独立本地备用预览，可加 `--port`。后台模式不使用固定本地端口，不需要公网隧道。预览不会提审或发布。
423
+ 后台暂不可用时，用 `buddy-cli-sit preview --local` 打开独立本地备用预览，可加 `--port`。后台模式不使用固定本地端口，不需要公网隧道。预览不会提审或发布。
409
424
 
410
425
  以下两个命令按需选择，不必同时启动同一个工程：
411
426
 
412
427
  ```bash
413
- buddy-cli dev --directory ./study-buddy
414
- buddy-cli preview --directory ./study-buddy
428
+ buddy-cli-sit dev --directory ./study-buddy
429
+ buddy-cli-sit preview --directory ./study-buddy
415
430
  ```
416
431
 
417
432
  ### 停止 DEV 与强制断连（CLI 0.18.0 起）
418
433
 
419
434
  - `dev` 运行本机 Runtime；`preview` 维持后台与工程的连接，在页面启动 DEV 后才运行 Runtime。
420
- - 「停止 DEV」或在工程目录执行 `buddy-cli dev stop`：停止 Runtime 和文件监听，已有 preview 连接保留，不重新启动。
435
+ - 「停止 DEV」或在工程目录执行 `buddy-cli-sit dev stop`：停止 Runtime 和文件监听，已有 preview 连接保留，不重新启动。
421
436
  - Ctrl+C、SIGTERM 或关闭终端（SIGHUP）：停止 CLI 管理的 Runtime 进程组，释放锁并断开后台连接。
422
437
  - 后台「强制断连」：先阻止新的调试操作，尝试停止该工程的 DEV，再撤销连接；旧 CLI 不能自动接回。页面会明确显示本机是否已确认停止。
423
438
  - CLI 被强杀、电脑离线或旧版进程无法响应时，网页不能保证本机进程已退出。到原电脑的工程目录执行后台提供的停止指令，例如：
424
439
 
425
440
  ```bash
426
- buddy-cli dev stop --buddy-id b_example --app-server https://buddies.dots.chat
441
+ buddy-cli-sit dev stop --buddy-id b_example --app-server https://buddies.sit.dots.chat
427
442
  ```
428
443
 
429
444
  `dev stop` 无需登录、查询 npm 或访问平台，支持 `--directory`；按平台和工程 buddyId 查找本机进程。原 CLI 存活时通知它停止监听与 Runtime，原 CLI 已退出时核对进程身份后清理残留；不能确认身份时保留锁并报错，不误杀其他进程。同一搭子从其他目录启动时，应在提示的原工程目录执行。其他电脑的进程需到那台电脑停止。清理后如需调试，重新执行连接指令，再在页面启动 DEV；不会提审或发布。
@@ -456,28 +471,28 @@ Preview 展示平台对话记录、发送与流式输出耗时、会话状态和
456
471
 
457
472
  ### 正式包的平台与 Runtime
458
473
 
459
- 正式包固定连接 PROD：`https://buddies.dots.chat`，后台为 `https://buddies.dots.chat/developer/`。无需手动设置 `MLB_GATEWAY_URL`，也不询问开发或发布环境。
474
+ SIT 包固定连接 SIT：`https://buddies.sit.dots.chat`，后台为 `https://buddies.sit.dots.chat/developer/`。无需手动设置 `MLB_GATEWAY_URL`，也不询问开发或发布环境。
460
475
 
461
476
  - 登录、API、凭据领取、预览与上传均使用固定目标；CLI 将该网关及开发 Token 写入工程 `.env` 给 Runtime 使用。
462
477
  - `--app-server`、`--developer-web` 仅接受同一固定目标，兼容已有后台连接指令，不能切换环境。
463
478
  - `MLB_GATEWAY_URL`、`BUDDY_APP_SERVER_URL`、`BUDDY_DEV_APP_SERVER_URL`、`BUDDY_DEVELOPER_WEB_URL` 任一冲突都会报错；显式正确参数不能掩盖其他冲突配置。按提示移除终端及 shell 配置里的旧值，重新打开 Coding Agent 或终端后重试。
464
- - 创建或恢复工程、读取或修改工程资料、预览、DEV 和上传都会检查工程 `.env`。已知 ECS 工程按下述规则自动连接 PROD；SIT 或其他环境使用对应 CLI，不复制 `.env`、buddyId 或凭据。`--refresh-token` 仅刷新同一环境的开发凭据。
479
+ - 创建或恢复工程、读取或修改工程资料、预览、DEV 和上传都会检查工程 `.env`。其他环境工程请使用对应 CLI；迁移到公共平台需在新目录重新登记搭子后复制业务代码，不复制 `.env`、buddyId 或凭据。`--refresh-token` 仅刷新同一环境的开发凭据。
465
480
  - 登录态按平台 origin 保存，开发 Token 与本地实例锁继续按平台和搭子隔离。不读取旧的无平台归属登录记录。CLI 地址限制不代替 Server 的账号、归属及凭据环境校验。
466
481
 
467
- 已知 ECS 的 HTTPS 地址及两个旧 HTTP 入口支持自动连接 PROD：先验证原登录态与同一 buddyId 的归属，再在 DEV 启动时更新 `.env`。保留业务配置和注释，身份校验或网络失败时不改文件；登录态过期时需正常登录。详见 [原工程连接 PROD](../../docs/ecs-to-prod.md)。
482
+ 临时保留同一 ECS 的旧入口迁移：`http://47.116.168.81:8788` 和 `http://47.116.168.81` 转为 HTTPS。启动 DEV 时校验归属，取得实例锁后更新 `.env`，保留业务配置与注释；失败不改文件。正式推广完成后可移除此兼容分支。
468
483
 
469
- `models`、`datasets` 和新建工程动态查询公共 npm 的 Runtime `latest`，只接受正式版本；新工程固定准确版本与锁文件。DEV、自动重载及 push 要求工程声明、实际安装和锁文件与本次最新正式版一致；不提供 `--runtime-version` 或测试版选择，不自动修改已有依赖。CLI 与 Runtime 的版本号无需一致。Runtime 发布者须在 PROD 支持对应能力后才更新 `latest`。
484
+ `models`、`datasets` 统一读取 npm dev 最新 Runtime 的目录。新建工程自动解析并固定准确版本，不提供 Runtime 版本选择；已有工程不自动改依赖。DEV 和 push 要求准确声明、安装和锁文件与最新 dev 版本一致，开发者或 Coding Agent 应按提示更新依赖并验证业务兼容性。
470
485
 
471
- 正式 CLI 自动更新也只查询 `latest`；若该标签误指向预发布版本，停止并提示发布者修正，不跨到测试渠道。
486
+ SIT CLI 只查询自身包的 dev 标签，遇到稳定版本或其他预发布命名会拒绝更新；不会安装正式包。
472
487
 
473
488
  ## 上传、商品审核与发布
474
489
 
475
- 先在后台创建商品取得稳定 ID，完善资料后点击“保存”（体验截图选填）。从未上架商品必须随新搭子版本上传提审并一起发布，商品页不提供独立“提交审核”。搭子代码可以引用该 ID；无需创建 `product.json`，平台查询商品元数据的接口本期尚未实现。
490
+ 先在后台创建商品取得稳定 ID，完善资料和截图后点击“保存”。从未上架商品必须随新搭子版本上传提审并一起发布，商品页不提供独立“提交审核”。搭子代码可以引用该 ID；无需创建 `product.json`，平台查询商品元数据的接口本期尚未实现。
476
491
 
477
492
  ```bash
478
- buddy-cli push --directory ./study-buddy --commit "根据完成情况调整练习难度"
479
- buddy-cli push --directory ./study-buddy --commit "增加写作陪伴" --product prd_12345678
480
- buddy-cli status --directory ./study-buddy
493
+ buddy-cli-sit push --directory ./study-buddy --commit "根据完成情况调整练习难度"
494
+ buddy-cli-sit push --directory ./study-buddy --commit "增加写作陪伴" --product prd_12345678
495
+ buddy-cli-sit status --directory ./study-buddy
481
496
  ```
482
497
 
483
498
  `--product` 可以重复，每次仅提交明确选中的商品当前已保存内容。新商品 ID 使用 `prd_` 加八位数字（如 `prd_12345678`），已有 `ps_` 商品 ID 继续兼容；复制后台返回的真实 ID，不要自行生成。未传该参数只上传代码，不扫描代码猜测商品，也不自动提交其他商品修改。CLI 在发送前固定本次上传 ID、源码包、商品审核 ID 和内容版本；平台为该上传生成唯一版本并自动通过代码和商品审核，构建状态单独显示。审核通过不会自动发布。
@@ -487,8 +502,8 @@ buddy-cli status --directory ./study-buddy
487
502
  ### 恢复原上传
488
503
 
489
504
  ```bash
490
- buddy-cli push --status <pushId>
491
- buddy-cli push --resume <pushId>
505
+ buddy-cli-sit push --status <pushId>
506
+ buddy-cli-sit push --resume <pushId>
492
507
  ```
493
508
 
494
509
  网络中断或结果未知时，按终端给出的 ID 查询或恢复原操作。恢复使用原包和原商品版本，不会把后来编辑的内容悄悄提交。代码已上传但商品提交失败时，先修正并保存商品，再对同一待发布版本发起一次补提。首次商品仅允许恢复原上传已明确携带且提交失败的项，由平台核验原上传凭证；不能补入其他首次商品或关联已经上线的版本。
@@ -496,8 +511,8 @@ buddy-cli push --resume <pushId>
496
511
  ### 补提或单独提交商品
497
512
 
498
513
  ```bash
499
- buddy-cli products submit --version <已上传版本> --product prd_12345678
500
- buddy-cli products submit --resume <submissionId>
514
+ buddy-cli-sit products submit --version <已上传版本> --product prd_12345678
515
+ buddy-cli-sit products submit --resume <submissionId>
501
516
  ```
502
517
 
503
518
  提交结果包含准确的审核快照 ID。只有曾上架商品（包括已下架商品）才可独立选择已有版本提交修改；当前线上代码支持本次修改时，可以选择当前已发布版本，之后单独发布修改。首次商品仅可通过此命令恢复原上传的商品提交失败，仍须与关联搭子版本一起发布。
@@ -505,19 +520,19 @@ buddy-cli products submit --resume <submissionId>
505
520
  ### 确认发布
506
521
 
507
522
  ```bash
508
- buddy-cli release --from-push <pushId>
509
- buddy-cli release --from-submission <submissionId>
510
- buddy-cli release --from-submission <submissionId> --products-only
511
- buddy-cli release --version <版本> --code-only
523
+ buddy-cli-sit release --from-push <pushId>
524
+ buddy-cli-sit release --from-submission <submissionId>
525
+ buddy-cli-sit release --from-submission <submissionId> --products-only
526
+ buddy-cli-sit release --version <版本> --code-only
512
527
  ```
513
528
 
514
529
  前两种方式使用原回执中的版本与获批快照。`--products-only` 仅用于曾上架商品的修改，要求目标仍为当前已发布搭子版本；首次商品不能使用此选项，必须随关联搭子版本一起发布。已下架商品发布修改后仍保持下架。只希望更新代码时，明确使用 `--code-only`，商品内容保持原样。读取回执失败或商品提交失败不会被自动当成空商品清单继续发布。也可以到后台“版本与发布”确认本次发布内容。
515
530
 
516
531
  ```bash
517
- buddy-cli release --status <releaseId>
518
- buddy-cli release --resume <releaseId>
519
- buddy-cli release --retry <releaseId>
520
- buddy-cli release --cancel <releaseId>
532
+ buddy-cli-sit release --status <releaseId>
533
+ buddy-cli-sit release --resume <releaseId>
534
+ buddy-cli-sit release --retry <releaseId>
535
+ buddy-cli-sit release --cancel <releaseId>
521
536
  ```
522
537
 
523
538
  发布结果未知时先查询或恢复原任务；明确失败后可重试。取消阻止本任务后续激活商品，但不回滚已经开始的代码部署。仅 `active` 表示本次发布与商品激活完成。状态和恢复记录按平台、账号、搭子隔离，保存在本机私有操作目录；记录不包含登录凭据，恢复使用当前账号重新鉴权。
@@ -557,20 +572,18 @@ buddy-cli release --cancel <releaseId>
557
572
 
558
573
  参考 Creator 已确认的需求、原型和设计说明，在 `widgets/<小挂件类型>/` 中编写 `index.html` 和 `schema.json`，并在搭子业务中接入创建、读写和发送能力。按每项设计确定展示或编辑交互；pageEditing 记录所需操作、字段和目标环境，不授予生产权限。沿用已确认方案，按真实 Schema 和宿主支持接入；旧版作品升级需重新确认受影响设计。
559
574
 
560
- 使用 `buddy-cli preview` 调试页面与交互，修改后重启 DEV；准备上传时运行 `buddy-cli push`。Runtime 启动时读取小挂件文件并上传平台。开发步骤见仓库 `docs/widgets/design-delivery.md`。
561
-
562
- 后台的 Widget 编辑需配套 Server 和 Web 部署，只开放 `operations.userUI` 授权的记录操作，并遵守字段只读限制；409 冲突需重读核对，不能自动覆盖。图片上传与关闭后的聚合通知、API 和错误处理见 [Widget 指南](../../docs/preview/widgets.md)。目标 App 仍需提供编辑桥接并单独验收，后台预览成功不代表手机端已支持。记录编辑不代表多人实时同步、玩家身份认证或同一 Widget 内的玩家私有数据隔离；付费服务不在此范围。
575
+ 使用 `buddy-cli-sit preview` 调试页面与交互，修改后重启 DEV；准备上传时运行 `buddy-cli-sit push`。Runtime 启动时读取小挂件文件并上传平台。开发步骤见仓库 `docs/widgets/design-delivery.md`。
563
576
 
564
577
  ## 查看数据集，不依赖 Coding Agent
565
578
 
566
579
  工程内外均可直接查询最新目录，不要求先安装工程依赖：
567
580
 
568
581
  ```bash
569
- buddy-cli datasets
570
- buddy-cli datasets --directory ./my-buddy --json
582
+ buddy-cli-sit datasets
583
+ buddy-cli-sit datasets --directory ./my-buddy --json
571
584
  ```
572
585
 
573
- 正式包的目录来自 npm 最新稳定版 Runtime 的 `DATA_ACCESS_CAPABILITIES`，包括 ID、名称、来源和 Schema 版本。JSON 返回版本信息、适配状态和 `datasets` 数组（字段见上方模型目录说明）。命令不登录、不启动搭子、不申请权限，也不修改配置；从子目录运行会向上找到工程。每次都需要联网检查 latest，下载失败时明确报错，不把旧缓存称为最新版。
586
+ 目录来自npm dev 最新 Runtime 的 `DATA_ACCESS_CAPABILITIES`，包括 ID、名称、来源和 Schema 版本。JSON 返回版本信息、适配状态和 `datasets` 数组（字段见上方模型目录说明）。命令不登录、不启动搭子、不申请权限，也不修改配置；从子目录运行会向上找到工程。每次都需要联网查询 dev 最新版本，下载失败时明确报错，不把旧缓存称为最新版。
574
587
 
575
588
  开发者将实际选择的 ID 和用途写进 `data-access.json.requirements`。JSON Schema 检查形状与用途；DEV 和上传预检按工程安装的 Runtime 检查所选模型与非空数据声明。目录缺失、依赖未安装或版本不匹配时明确报错。Runtime 0.12.2 有 10 项，但单次数据查询仍最多 8 项。
576
589
 
@@ -582,13 +595,13 @@ Preview 文本发送采用 App WebSocket 的 `messages` 数组，并校验逐项
582
595
 
583
596
  同一个搭子的开发者共享开发 Token 和 `<buddyId>-dev` 身份；同一开发身份仍只能保持一条 Runtime 事件流。正式身份使用另一把 Token，两者互不顶替。开发凭据没有自动过期时间，Server 重置或删除搭子后才失效。
584
597
 
585
- 开发 Token 被平台重置后，停止当前 CLI，再运行 `buddy-cli dev --refresh-token` 或 `buddy-cli preview --refresh-token`。这会跳过本地开发凭据，重新领取服务端当前的开发 Token 并更新 `.env`，不在 Server 生成新密钥。工程启动不再从旧版 Keychain 的开发 Token 缓存领取凭据。
598
+ 开发 Token 被平台重置后，停止当前 CLI，再运行 `buddy-cli-sit dev --refresh-token` 或 `buddy-cli-sit preview --refresh-token`。这会跳过本地开发凭据，重新领取服务端当前的开发 Token 并更新 `.env`，不在 Server 生成新密钥。工程启动不再从旧版 Keychain 的开发 Token 缓存领取凭据。
586
599
 
587
600
  账号登录凭据仍保存在 macOS Keychain，不写入工程。开发 Token 保存在权限为 `0600` 的工程 `.env`，不传给 Web，也不进入上传包或命令行参数。
588
601
 
589
602
  ### 本地身份与连接配置
590
603
 
591
- 首次启动 DEV 时，CLI 将开发版 `BUDDY_TOKEN` 和 `MLB_GATEWAY_URL` 写入工程 `.env`，保留其他配置和注释，移除旧 `BUDDY_ID` 赋值。身份始终来自 `package.json.buddyId`；只配置 Token 的 `.env` 也可使用。后续复用前向 Server 核对 Token；`--refresh-token` 重新领取后更新此文件。开发者登录凭据仍使用系统凭据存储。`.env` 加入 Git 忽略，且始终排除在上传包之外。
604
+ 首次启动 DEV 时，CLI 将开发版 `BUDDY_TOKEN` 和 `MLB_GATEWAY_URL` 写入工程 `.env`，保留其他配置和注释，移除旧 `BUDDY_ID` 赋值。身份始终来自 `package.json.buddyId`；只有 Token 而没有网关的旧配置不会复用 Token，将重新校验搭子归属并领取当前环境凭据。后续复用前向 Server 核对 Token；`--refresh-token` 重新领取后更新此文件。开发者登录凭据仍使用系统凭据存储。`.env` 加入 Git 忽略，且始终排除在上传包之外。
592
605
 
593
606
  CLI、Preview 与标准 `npm start` 均由 Node 的 `--env-file-if-exists=.env` 加载本地配置，Runtime 从 `package.json.buddyId` 读取身份、从环境变量读取 Token 和网关；托管时平台注入的同名环境变量优先。已有工程显式升级 Runtime 后，CLI 只自动迁移能精确识别的生成入口及标准启动命令，自定义业务代码和脚本保留。
594
607
 
@@ -610,4 +623,22 @@ Runtime 0.19.0 支持在 `schema.json.openTargets` 声明入口。业务通过 `
610
623
 
611
624
  ## CLI 0.20：MLB 统一提供服务
612
625
 
613
- 正式包入口固定与 PROD 网页同源，使用 HTTPS。CLI 的一次性浏览器授权走 `/cli/web/authorizations`、`/cli/web/exchange`，预览连接走 `/cli/preview/*`。不调用独立 Web 服务，不支持地址覆盖；预览不触发上传或发布。
626
+ 正式包入口固定与 SIT 网页同源，使用 HTTPS。CLI 的一次性浏览器授权走 `/cli/web/authorizations`、`/cli/web/exchange`，预览连接走 `/cli/preview/*`。不调用独立 Web 服务，不支持地址覆盖；预览不触发上传或发布。
627
+
628
+ ## SIT 包与准确版本复现
629
+
630
+ ```sh
631
+ npm install --global --prefix "$HOME/.local/share/buddy-cli/sit" @my-life-buddies/cli@dev --registry=https://registry.npmjs.org/
632
+ export PATH="$HOME/.local/share/buddy-cli/sit/bin:$PATH"
633
+ buddy-cli-sit --version
634
+ # 复现某一版（必须与已安装版本完全匹配）
635
+ export BUDDY_CLI_PIN_VERSION=0.23.0-dev.2
636
+ buddy-cli-sit preview
637
+ unset BUDDY_CLI_PIN_VERSION
638
+ ```
639
+
640
+ SIT 平台固定为 `https://buddies.sit.dots.chat`。CLI 地址约束是客户端防误连机制；服务端仍须独立校验身份、Token 和权限，不是完整的服务端安全隔离。
641
+
642
+ SIT `push` 触发异步构建，显示 `building/ready/failed` 及失败原因，最多等待一分钟；仍在构建时用 `buddy-cli-sit status` 查询，不能重复上传当作查询。审核通过、构建就绪和线上发布是不同状态；确认上传回执中的版本与商品快照后，可在后台发布，或执行 `buddy-cli-sit release --from-push <pushId>`，仅 `active` 表示发布生效。
643
+
644
+ DEV 要同时看到 Runtime 初始化完成和服务端在线后才就绪。后台的 Widget 编辑需配套 Server 和 Web 部署，只开放 `operations.userUI` 授权的记录操作，并遵守字段只读限制；409 冲突需重读核对，不能自动覆盖。图片上传与关闭后的聚合通知、API 和错误处理见 [Widget 指南](../../docs/preview/widgets.md)。目标 App 仍需提供编辑桥接并单独验收，后台预览成功不代表手机端已支持。记录编辑不代表多人实时同步、玩家身份认证或同一 Widget 内的玩家私有数据隔离；付费服务不在此范围。