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

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