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