@my-life-buddies/cli 0.1.2

package/README.md

@@ -0,0 +1,314 @@
+# buddy-cli 使用说明
+
+这份说明按一次开发过程展开：登记搭子，准备工程，在本地预览，然后上传程序包。所有搭子统一使用 `@my-life-buddies/buddy-runtime`，业务能力通过 Prompt、`src/buddy.mjs` 和 Tool 实现。
+
+## 准备 CLI 和平台地址
+
+目前只支持 macOS，要求 Node.js 24 或更新版本。
+
+当前 CLI 工程版本为 `0.1.2`，发布到公共 Registry `https://registry.npmjs.org/`。已有仓库源码时，在仓库根目录运行：
+
+```bash
+npm install
+npm run buddy-cli -- --help
+```
+
+下文统一使用 `buddy-cli`。源码运行时替换为 `npm run buddy-cli --`；从公共 npm 安装已发布版本：
+
+```bash
+npm install --global @my-life-buddies/cli@0.1.2 --registry=https://registry.npmjs.org/
+```
+
+维护者需先登录公共 npm，拥有 `@my-life-buddies` scope 的发布权限，并完成 npm 要求的两步验证（2FA）。在仓库根目录完成验证，只发布 CLI：
+
+```bash
+npm run check
+npm run verify:package
+npm publish --workspace @my-life-buddies/cli
+```
+
+对外只有 `@my-life-buddies/cli@0.1.2`，`publishConfig` 已指定公共 npm 和 `public` 访问级别。Core 和 Preview 保留 monorepo 开发边界并标记为 `private`，构建时合入 CLI 的内部模块；Preview 页面、Creator Skill、工程模板资源一同进入 CLI 包。安装不会请求 `@buddy/cli-core` 或 `@buddy/preview`。第三方运行依赖按正常 npm dependencies 安装，构建工具 esbuild 不进入安装依赖。根工作区和 Web 同样保持 `private`。
+
+版本维护：每批修改 CLI 发布内容时递增一次版本，默认 patch；根包和内部工作区版本、依赖引用、锁文件一起更新。Agent 工程自己的项目版本独立。升级 Runtime 时同步模板依赖与模板锁文件，并运行独立安装验收。
+
+CLI 默认连接 MLB 测试环境 `http://47.116.168.81:8788`，不必先配置地址：
+
+```bash
+buddy-cli login
+```
+
+这是实际 test 环境，不是演示数据。当前测试入口使用 HTTP，登录凭证和对话内容未加密传输，仅用于测试；只有这个固定 origin 被允许使用远程 HTTP，不会放开其他 IP、端口或相似域名。后续有 HTTPS 入口时替换默认值。手机 App 需要连接同一环境。
+
+CLI 会打开搭搭创作者平台网页完成登录和授权。浏览器已有有效 Cookie 时，页面直接显示当前账号，开发者确认后即可返回终端；没有登录时，先在同一网页完成短信登录，再确认授权。CLI 不读取浏览器 Cookie，也拿不到短信验证码，只通过本机回调收到一次性授权码，再换取自己的会话。
+
+CLI 会把换取到的会话保存到 macOS Keychain。有效会话会复用，不必每条命令都重新登录；切换服务器 origin（协议、主机或端口）后，使用另一份凭据，不把原服务器的 Token 发过去。开发者平台网页默认使用 `https://47.116.168.81/developer/`；本地联调其他 Web 时可设置 `BUDDY_DEVELOPER_WEB_URL`，远程地址必须使用 HTTPS。
+
+旧版没有标记服务器归属的钥匙串记录不会自动复用或删除；升级后需要重新登录一次。
+
+| 命令 | 是否需要 Agent 目录 | 会发生什么 |
+| --- | --- | --- |
+| `help`、`--help` | 不需要，也不登录 | 显示参数说明 |
+| `login`、`logout`、`models` | 不需要 | 管理账号会话或查询平台模型 |
+| `init` | 目标目录可以是空目录或已有官方工程 | 登记或恢复云端身份，准备本地文件 |
+| `dev`、`preview`、`push` | 需要完整的 `buddy.agent.json` | 运行、调试或打包该工程 |
+| `status` | 需要含 `buddyId` 的 `buddy.agent.json` | 查询该搭子的云端状态；创作尚未完成时也可使用 |
+
+项目命令可从工程子目录向上定位配置，也可用 `--directory` 指定工程。普通目录不会被悄悄初始化；已有官方工程可用 `init --mode direct` 补齐缺失的模板文件，已有文件不会被覆盖。
+
+未配置平台地址时也可以查看总帮助和子命令帮助，不会发起登录。若显式填写了无效地址，CLI 会报错，不会悄悄改连 test。
+
+`logout` 不会为了退出再发起登录；有缓存时先请求平台吊销，再清除本机会话。吊销失败也会清除本机缓存，并明确提示远端操作未成功。
+
+## 登记前，先确定搭子的名称和介绍
+
+两条初始化路线都需要 `name`（名称）、`tagline`（一句话介绍）和 `intro`（详细介绍）。这些内容会随身份创建直接写入平台，不是等待手册完成后才上传的本地草稿。
+
+让 Coding Agent 操作时，先沿用你已经明确提供的资料。缺少的部分可以由它拟稿，再把完整资料放在一起，请你确认后执行 `init`；不要求你自己填写技术字段。你已经确认过，或明确说“名称和介绍由你决定”时，就不重复询问。只说“创建一个跑步搭子”说明了主题，不代表授权它自行决定全部资料并提交；“以后可以改”也不能代替这次确认。
+
+直接在终端操作时，CLI 会询问未通过参数提供的字段；你输入的内容用于本次登记。Coding Agent 和脚本通过参数传值时不会弹出第二轮终端确认，因此 Agent 必须先在主对话完成上述步骤。CLI 能校验参数，不能验证对话中的确认。
+
+基础资料确认只确定这次登记的内容，不等于四册手册已确认，也不恢复已经取消的技术策略问卷。恢复已有创作工程时沿用原 `buddyId` 和平台最新资料；若发现旧资料未经确认，先核对并处理原搭子的资料，不为此重新创建搭子。
+
+## 需求明确时，直接开发
+
+需求明确后，Coding Agent 应先读需求与现有代码，判断哪些能力可以直接复用、哪些需要补齐。例如已经要求学习搭子“根据上次练习继续安排”，它就应实现学习进度的保存和读取，不必再问一遍是否需要记忆。
+
+直接生成官方 Runtime 工程：
+
+```bash
+buddy-cli init --mode direct --directory ./study-buddy \
+  --name "学习搭子" --tagline "把学习目标拆成每天能完成的小步骤" \
+  --intro "根据学习目标与每日反馈，帮助用户安排练习并复盘。"
+```
+
+CLI 只生成工程骨架，不分析手册或自动生成业务代码，也不固定追加一轮 Memory、Context 或其他技术选项的确认。Coding Agent 根据已确认需求完成实现；只有会影响体验、数据使用或权限的关键条件还不明确时，才用日常语言补问。
+
+默认能力满足需求时直接沿用；不满足时要落实到代码，而不是只修改描述。例如新 Runtime 不会自动查询或提炼长期记忆，需要记忆时必须按已确认的数据边界显式实现，并通过 `src/buddy.mjs` 接入相应 Tool 或 Hook。Runtime 会从 MLB 重建会话历史，但持续计划和结构化状态不应只依赖聊天记录。需要不同做法时，Coding Agent 应检查并补齐真实执行路径。
+
+你会得到：
+
+```text
+study-buddy/
+├── buddy.agent.json           平台 buddyId、Runtime 与模型配置
+├── agent.md                   应用 Prompt，只包含自然语言
+├── start.mjs                  本地和云端共用的启动入口
+├── package.json               包含 npm start
+├── package-lock.json          依赖锁文件
+├── src/
+│   ├── buddy.mjs              BuddyFactory，组装工具与回合钩子
+│   ├── tools/                 自定义工具，默认空目录
+│   ├── hooks/                 执行钩子，默认空目录
+│   └── services/              普通业务代码，默认空目录
+├── resources/                 Markdown 参考资料，默认空目录
+└── widgets/                   小挂件类型的页面和 Schema，默认空目录
+```
+
+`src/buddy.mjs` 是每场会话的组装入口，导出 `createBuddy(conversation)`，返回 Runtime 所需的 `BuddyOptions`。它用 `new URL("../agent.md", import.meta.url)` 读取根目录 Prompt，显式导入和注册工具与钩子。
+
+| 目录 | 放什么 |
+| --- | --- |
+| `src/tools/` | 模型可以调用的工具定义：名称、说明、参数 Schema 和执行函数 |
+| `src/hooks/` | 工具调用前后、上下文准备、停止等钩子的实现 |
+| `src/services/` | 供 Tool、Hook 使用的业务逻辑与平台接口封装；Runtime 没有 Service 注册接口 |
+| `resources/` | 固定参考资料，Runtime 启动时递归读取其中的 `.md` 文件 |
+| `widgets/` | 小挂件文件，每个类型一个子目录，包含 `index.html` 和 `schema.json` |
+
+五个目录默认创建为空，不生成占位文件；目录存在不会自动注册工具或启用钩子。简单 Tool 可以自己完成业务操作，复杂或复用的代码再抽到 Service。搭子业务只使用平台提供的服务，不直接调用第三方服务。`tests/` 按需创建，`.buddy/` 和 `node_modules/` 由创作流程或安装依赖生成。模板不生成 README 或 `.gitignore`，也不初始化 Git 仓库。
+
+有小挂件需求时，按类型创建文件：
+
+```text
+widgets/
+└── sleep-record/     稳定的 widget 类型 ID
+    ├── index.html    单文件页面，样式与脚本内联
+    └── schema.json   MLB widget 类型定义
+```
+
+工程命名建议：类型 ID 使用字母开头的小写英文、数字和单个连字符分隔，总长不超过 64 字符，如 `sleep-record`、`training-progress`；平台也支持中文类型名。一级目录名是唯一的 ID 来源，不在配置或文件名里再重复保存。相同 Buddy 内不能重名；不同 Buddy 可以使用同名类型。展示标题可以使用中文。目录改名等于新建类型，已有实例不会自动转到新类型。
+
+`schema.json` 的顶层是 `{ "description": "...", "modules": { ... } }`，各模块包含 `description` 和 `record`；`record` 才是该模块记录的 JSON Schema。不要直接把一份普通 JSON Schema 当作整个类型定义。
+
+CLI 将 HTML 和 Schema 随工程源码打包。模板锁定的 Runtime `0.7.0` 在 BuddyServer 启动时读取 `widgets/`，通过 `PUT /internal/v1/widget-types/:typeId` 一起上传 Schema 与 HTML；全部成功后才连接事件流。缺文件、无效 JSON 或平台拒绝上传会使启动失败，具体原因可在终端或 Preview 日志中查看。平台需要已部署该接口。
+
+模型使用小挂件工具时，在 `src/buddy.mjs` 的 `platformTools` 中显式选择 `widget_create`、`widget_write` 等工具；直接调用 `conversation.widgets` 不受该名单限制。类型按上传进程的 Buddy 身份保存，DEV 分身与正式版隔离。修改文件后重启 Runtime；删除或改名目录不会删除平台上的旧类型。浏览器中的 Widget 渲染预览仍待接入。
+
+先改 `agent.md`，决定这个搭子怎么与用户交流：
+
+```markdown
+你是学习搭子。先了解学习目标，再给一个今天能完成的练习；不要编造用户过去的学习记录。
+```
+
+要增加业务 Tool 时，在 `src/buddy.mjs` 的 `initialState.tools` 注册 `AgentTool`；参数 Schema 的 `Type` 从 `typebox` 导入。Memory 通过 `conversation.memory` 显式读写，授权数据、小挂件和发消息也通过当前会话的 `conversation.memory / dataAccess / widgets / proactive` 调用。平台工具通过 `platformTools` 明确启用。完整契约见 [新 Runtime 说明](https://code.devops.xiaohongshu.com/dada/buddy-runtime)。
+
+
+`start.mjs` 是 CLI 生成的启动与停止入口；`src/buddy.mjs` 负责业务配置。启动文件通过以下方式接入组装器：
+
+```js
+import { BuddyServer } from "@my-life-buddies/buddy-runtime";
+import createBuddy from "./src/buddy.mjs";
+
+await BuddyServer.start({ model, buddy: createBuddy });
+```
+
+新工程在 `package.json` 中固定 Runtime `0.7.0` 并保留锁文件，先运行 `npm ci`，再运行 `buddy-cli dev`。已有工程的依赖不会被 CLI 升级自动覆盖；在该工程运行 `npm install --save-exact @my-life-buddies/buddy-runtime@0.7.0 --registry=https://registry.npmjs.org/`，同步更新依赖和锁文件后重启。上传不包含 `node_modules` 或 Runtime 打包副本；部署端安装依赖后执行同一个 `npm start`。
+
+## 想法还模糊时，先梳理需求
+
+确认用于登记的基础资料后，再执行下面的命令；这里的文案只是示例，不是通用默认值。
+
+```bash
+buddy-cli init --mode create --directory ./study-buddy \
+  --name "学习搭子" --tagline "帮助用户建立学习习惯" \
+  --intro "与用户一起明确目标，形成可以坚持的学习安排。"
+```
+
+这个命令先登录和登记搭子，然后返回 `HANDOFF.md` 的位置。把它交给 Codex 或 Claude Code，Coding Agent 会读取 CLI 内置的 Creator Skill，在主对话里继续询问并展示作品预览。
+
+登记时的名称和介绍会写入 `.buddy/creator/initial-context.json`，随接续命令传给 Skill。例如已经明确要做学习搭子，就从具体的学习问题继续聊，不从“什么是搭子”重新开始。这是平台资料的快照，不是采访回答或四册确认的凭据；具体需求仍以你的真实回答和确认来确定。
+
+此时已确定使用官方 Runtime，但还没有生成完整 Agent 工程：
+
+```text
+登录 → 确定登记资料（Agent 拟稿须确认或获授权代定）
+     → 登记身份 → 准备 Creator Skill → Coding Agent 完成创作
+         → 用户确认 Booklet → Creator 交还控制 → 根据手册落实代码
+         （只对关键缺口补问，不重新采访）
+         → 基础技术自测 → 打开真实预览 → 开发者体验并反馈
+```
+
+当前内置 Creator Skill 1.3.1，随 CLI 安装，不需要运行时从 GitHub 下载或全局注册。执行它的工具需要 Python 3.9+；登录与身份登记仍要联网。Skill 的作品预览不是 Agent 聊天模拟器。已有作品升级后沿用原工作区，让 Coding Agent 重新读取 Skill 和宿主协议即可按新规则接续。
+
+创作资料保存在 `.buddy/creator/`。四册确认完成、手册有效时，Skill 返回 `directive=creator_complete` 和 `completion.manualPath`。Coding Agent 结束采访，重新读取 `HANDOFF.md` 和完整手册。开发已经获准时，它根据手册继续实现，不等你再次问“下一步”，也不要求重新确认整份方案。未明确的实现方式或关键条件才需要补问。若你只想完成设计，则交付手册后停止。
+
+手册中的角色、方法、处理路径和持续服务要求，都是开发依据。Coding Agent 按这些要求判断是否需要工具、专业方法、特定处理步骤、记忆与历史整理，技术选择不逐项交给开发者；完成后向开发者简要说明需求来源、实现位置、检查结果和缺口，不要求额外生成 README。已经明确的直接做，不能实现的如实说明；只有元数据或默认配置，不代表手册要求已经完成。
+
+手册完成后，Coding Agent 用下面的命令补齐官方 Runtime 工程，再据手册实现功能；这不是 Creator Skill 自己执行的操作：
+
+```bash
+buddy-cli init --mode direct --directory ./study-buddy
+```
+
+创作阶段的 `buddy.agent.json` 只有 `schemaVersion` 和 `buddyId`；CLI 用它从平台读取最新资料并重新校验归属，不另建搭子。创作中断后可以在原目录重试 `--mode create`，继续使用原作品；手册完成后执行 `--mode direct`，同一文件会原地补齐 Runtime 等工程字段。旧 `--mode interview` 已停止使用。
+
+两条主线都遵循同一个登记规则：名称、`tagline`（一句话介绍）、`intro`（完整介绍）先同步到平台，返回的 ID 写入 `buddy.agent.json.buddyId`。公开资料不在本地留副本。若平台已创建成功、本地写盘失败，可用 `--buddy-id <平台返回的 ID>` 恢复；它不是自定义 ID 的入口。
+
+Creator 例外保留首次创作背景快照，用于接续同一作品；恢复时使用它校验接续说明，云端后来修改名称或介绍不会因此阻断创作，也不会被首次快照覆盖。
+
+## Coding Agent 做到哪里，交给你体验
+
+如果你委托 Coding Agent 完成整个搭子的开发，它应该做到可体验的真实预览，而不是停在手册或模板生成：完成实现，检查配置、构建和启动，执行已有自动化测试与明确业务规则、安全边界的基础测试，再打开模拟器并确认 DEV 在线、消息能够往返。
+
+没有消息往返证据时，可以发一条不含个人敏感信息的联调消息；已有成功记录就不重复发送。随后保留预览和 DEV，把页面地址、已验证范围与已知限制交给你，等待你亲自试聊。比如跑步搭子的“临时没时间怎么调整计划”“教练说话方式是否合适”，默认由你体验、反馈，再由 Coding Agent 修改；它不自行展开多轮业务试聊和调教，也不代替你验收。
+
+你明确要求自动体验或多场景回归时，Coding Agent 再按指定范围执行。`push` 仍需要明确授权。若你只要求初始化、修改某段代码或完成设计，也不会因为这套默认流程就自动启动预览。
+
+这些规则通过 CLI 帮助、命令输出和 Creator 的 `HANDOFF.md` 交给 Coding Agent；CLI 不会在 `init` 内自动执行采访、编写业务代码或批量调用模型。重试创作时复用当前接续说明和作品，不覆盖开发者修改的文件。已有完整工程无需重新初始化，可从更新后的 CLI 帮助和 `preview` 输出读取交接规则。
+
+## 为这个搭子选一个模型
+
+```bash
+buddy-cli models
+```
+
+CLI 调用 `GET /cli/models` 查询 ID 列表。选择其中一个，写进现有 `buddy.agent.json`；例如平台确实返回了 `deepseek-v4-pro` 时，官方工程可以是：
+
+```json
+{
+  "schemaVersion": 1,
+  "buddyId": "平台返回的搭子 ID",
+  "model": "deepseek-v4-pro",
+  "runtime": { "language": "node" }
+}
+```
+
+其他身份和工程字段要保留，不要整份替换配置。重启开发会话后，主回复固定使用这个模型；新 Runtime 不会自动做 Memory 提炼。
+
+接口没有声明平台默认项。省略 `model` 会沿用当前接入代码的 `kimi-k2.6`；不可用时返回错误，不自动换模型。列表也不等于上游服务实时健康检查。
+
+官方 Runtime 统一通过平台代理调用选定模型，不把外部模型密钥带进项目。
+
+## 在模拟器里聊一次
+
+以下两个命令按需选择，不必同时启动同一个工程：
+
+```bash
+buddy-cli dev --directory ./study-buddy
+buddy-cli preview --directory ./study-buddy
+```
+
+`dev` 启动本地 Agent 并连接 MLB；`preview` 还会打开浏览器模拟器和调试页面。本地进程准备好之后，CLI 通过平台通知接收消息，不需要公网隧道。
+
+平台身份保存在 `buddy.agent.json.buddyId`，模拟器访问的是对应的 `<buddyId>-dev`。MLB 决定当前账号是否可以访问这只开发版搭子。不要把本地 `buddyId` 改成 `-dev`，也不需要传 `x-mlb-dev`。
+
+打开模拟器就会查询 `GET /app/buddies/:buddyId`，不必先启动 DEV。名称来自云端资料，预览标识来自服务端 `isDev`；详情查询不会添加搭子或触发欢迎。
+
+进入私聊时，先复用详情返回的 `privateId`；尚无私聊则调用 `POST /app/privates`，提交开发版 `buddyId` 并取得私聊 ID。历史继续通过 `GET /app/privates/:privateId` 读取；普通消息通过 `/app/ws` WebSocket 的 `message.send` 命令发送，不再调用已经移除的 HTTP `/messages` 路径。WebSocket 命令和事件中的会话 ID 都是私聊 ID，不是本地执行的 `runId`。
+
+页面可以显示聊天历史和真实流式回复。浏览器发送收据不等于 Runtime 回合；只有平台事件提供可验证的关联标识时才展示对应耗时，不按时间或文本猜测。
+
+回合列表按“第几轮、开始时间、状态”显示，默认跟随最新回合。选择历史回合或点击上一轮、下一轮后，会停留在所选回合，并同步切换各调试面板；勾选“跟随最新回合”可恢复跟随。完整执行 ID 可单独复制。编号只表示本次预览服务记录的顺序，不是聊天消息序号；列表保留最近 100 轮，旧记录移出后也不会重新编号。
+
+Preview 展示平台对话记录、发送与流式输出耗时、会话状态和协议事件。调试页中的协议日志也会显示 Runtime 的 stdout/stderr，包括启动失败和工具报错；凭据会遮蔽，超长单行截断，最多保留最近 300 条事件。模型内部上下文、Memory 操作与 Tool 轨迹需要 Runtime 提供结构化调试契约后再接入。
+
+工具执行记录里没有正文时不显示空气泡，有正文时保留可见内容；平台仍处于 replying 时，不会因工具记录或中途正文而提前结束回合。
+
+启动 DEV 后，点击“真机预览”。CLI 本地服务生成二维码，内容为 `mlb://preview?buddyId=<当前搭子ID>-dev`，不含 Token、服务器地址或用户数据。手机需要安装支持此入口的搭搭 App，并登录同一开发者账号；App 再向 MLB 查询开发版详情，权限仍由 MLB 校验。扫码工具必须支持打开自定义 App 链接，不保证任意扫码软件都能直接唤起。
+
+二维码生成已实现并验证解码；手机扫码、App 与实际 MLB 环境的完整链路仍需真机联调。Widget 和终止回复暂未完成。
+
+改完代码后，停止再启动 `dev`，或在 Preview 中重启会话。当前没有源码热重载。原聊天历史从 MLB 读取，不因浏览器刷新就另建一份；服务端数据的保留期限不由 CLI 决定。
+
+### 什么时候需要另一个服务地址
+
+不配置时，所有命令使用上述默认 test 地址。覆盖顺序如下：
+
+| 命令 | 地址优先级（从高到低） |
+| --- | --- |
+| `login`、`init`、`logout`、`models`、`push`、`status` | `BUDDY_APP_SERVER_URL` → `BUDDY_DEV_APP_SERVER_URL` → 默认 test |
+| `dev`、`preview` | `--app-server` → `BUDDY_DEV_APP_SERVER_URL` → `BUDDY_APP_SERVER_URL` → 默认 test |
+
+`BUDDY_DEV_APP_SERVER_URL` 保留为开发会话的专用覆盖。如果希望所有命令连接同一环境，只配置 `BUDDY_APP_SERVER_URL` 即可。
+
+这些是地址配置选项，不表示开发版搭子一定运行在另一套域名或独立数据库里。`models`、`init` 和 `push` 使用平台地址；如果特意配置了不同服务器，需要确认查询的模型和搭子属于目标服务器。除固定 test 入口外，远程服务必须使用 HTTPS；本机 loopback 仍允许 HTTP。
+
+## 上传程序包，不等于发布
+
+```bash
+buddy-cli push --directory ./study-buddy --commit "根据完成情况调整练习难度"
+buddy-cli status --directory ./study-buddy
+```
+
+`push` 收集 `buddy.agent.json`、源码和依赖锁文件，生成 `tar.gz`，上传到 `/cli/buddies/:id/packages/push`。`commit` 是改动说明，与本地 Git 是否提交无关。版本由 MLB 返回，CLI 不上传自己生成的 tag 或提审时间戳。
+
+审核状态以平台响应为准，可能已经是 `approved`，不能仅因命令名叫“提审”就假定一定进入等待审核。`status` 查询搭子资料和最近 5 次程序包记录，显示线上版本、运行状态、审核结果及说明。
+
+CLI 不提供 `release`、`publish`、`disable`、`enable` 或 `unpublish`。最终发布和下架留给 Web。上传成功只说明平台收到了这份包，不说明生产运行已经验证。
+
+### 上传前检查
+
+- 必须包含非空且不超过 64 KiB 的 `agent.md`、业务入口 `src/buddy.mjs`、`start.mjs`，以及 `scripts.start` 为 `node start.mjs`、在 dependencies 中声明准确 Runtime 版本的 `package.json`。
+- 保留一份有效的依赖锁文件（`package-lock.json`、`pnpm-lock.yaml` 或 `yarn.lock`），并确保 `src/buddy.mjs` 与它引用的业务源码实际进入程序包。模板恢复会沿用已有锁文件，不另加一份 npm 锁文件。
+- `.buddy/`、依赖安装目录、常见凭据文件和私钥不会进入包。默认排除包括 `.env`、`.env.*`（含示例）、`*.env`、`.envrc`、`.npmrc`、`.yarnrc`、`.yarnrc.yml`，以及 `.ssh`、`.aws` 等目录；完整规则见 [打包实现](../../packages/cli-core/src/push/preflight.ts)。
+- 排除不依赖 Git，也不继承 `.gitignore`。放进 Git 忽略列表，不代表不会上传。
+- 源码包只收录文件，不保留空目录；`src/tools/`、`src/hooks/`、`src/services/`、`resources/` 和 `widgets/` 有实际文件后会正常收录，不需要占位文件。
+- 文件名过滤不是密钥扫描。写在普通源码里的 Token 不会因此自动消失；Booklet 和创作资料应放在项目外或 `.buddy/` 内。
+- 打包排除不会删除本地原件，出现提示时先确认包里是否仍有启动所需文件。
+
+## 官方工程如何在云端启动
+
+平台在部署阶段解包、准备依赖，再执行 `npm start`。官方模板的启动入口读取：
+
+| 环境变量 | 作用 |
+| --- | --- |
+| `MLB_BUDDY_ID` | 平台部署的搭子身份，须与工程匹配 |
+| `MLB_BUDDY_TOKEN` | 连接 MLB 的 Buddy 凭据 |
+| `MLB_GATEWAY_URL` | 平台网关，由部署环境显式注入；未设置时沿用 Runtime 的默认地址 |
+
+这些值由部署环境提供，不写入提审包。云端安装工程声明的 Runtime 和业务依赖，执行 `npm start`，不需要安装 CLI。Runtime 主动连接网关事件流。
+
+
+## 只想检查工具是否安装完整
+
+维护者可在仓库根目录执行 `npm run verify:package`。它验证 npm 安装、初始化、模板启动和消息链路，MLB 与模型使用测试替身。
+
+`BUDDY_CLI_MOCK_CLOUD=1` 仅用于初始化交互测试，会产生明确标记的 `b_mock_*` 身份。它不提供真实模型目录、push 或 status，不能用来判断平台已打通。