@my-life-buddies/cli 0.16.0 → 0.17.1

package/README.md

@@ -31,7 +31,7 @@ buddy-cli init --help
 buddy-cli guide
 ```
 
-`--help` 列出命令，`<命令> --help` 说明当前命令的参数、限制和示例。`guide` 输出 Coding Agent 的完整开发指引，包括资料确认、Skill 接续、实现和交付规则；无需工程、登录或联网，不写文件。让 Agent 开始工作前先读取 `guide`，再按 CLI 返回的 `HANDOFF.md` 继续当前工程。`guide --help` 只显示该命令的简短用法。
+`--help` 列出命令，`<命令> --help` 说明当前命令的参数、限制和示例。`guide` 输出 Coding Agent 的完整开发指引，包括资料确认、Skill 接续、实现和交付规则；无需工程或登录，先联网自检并按需自动更新 CLI，再输出新版指引，不修改工程文件。让 Agent 开始工作前先读取 `guide`，再按 CLI 返回的 `HANDOFF.md` 继续当前工程。HANDOFF 只包含当前工程、Skill 路径和接续方式，通用规则以 guide 为准；已生成文件在正常恢复创作时校验、备份并更新，CLI 升级不会直接覆盖工程里的 HANDOFF。`guide --help` 只显示该命令的简短用法。
 
 命令执行结果只提示当前状态和下一步；完整规则不再重复出现在顶层帮助和成功输出中。后台同一份入口说明见 [CLI 使用指南](../web/web/docs/cli/index.html)。
 
@@ -45,7 +45,11 @@ buddy-cli update
 
 `--version`（也可写作 `-v`）显示当前运行的 CLI 版本，无需联网。`update --check` 查询公共 npm 的 `latest` 版本，只检查、不安装；`update` 有新版本时安装检查到的准确版本，完成后核验安装结果。版本相同或本机版本更高时不安装、不降级。这三个用法均无需登录搭搭账号或进入搭子工程，从 CLI 0.8.0 开始支持。旧版用户先用上面的 npm 命令升级。
 
-自动更新支持 npm 全局安装。源码、`npm link`、局部安装和 `npx` 请沿用原来的安装方式更新；使用 nvm 时先切换到安装该 CLI 的 Node.js 环境。更新只针对 CLI，已有工程的 Runtime 依赖和锁文件需要另行修改与验证。
+从 CLI 0.17.0 起，每条正常命令（含 `guide` 和无参数入口）先查询公共 npm `latest`，当前版本落后时自动更新，并由新版执行原命令。无需手动先运行 `update`，等待当前命令完成即可。更新发生在创建工程、领取凭据、启动 DEV 或上传之前；保留参数、工作目录、终端输入输出和退出状态，一次调用最多自动切换一次。版本相同或更高时继续执行，不降级；已经运行的 DEV 不因新版本发布而中断。
+
+全局安装更新当前 npm 环境中对应的 CLI；源码、`npm link`、项目内安装和 `npx` 自动下载准确版本到 `~/.cache/buddy-cli/updates/releases/`，从缓存运行，不改写原安装或工程依赖。并发更新共用安装锁。手动 `update` 仍只用于 npm 全局安装。查询最多等待 10 秒，安装最多等待 180 秒；失败或取消时停止原业务命令，不回退旧版。帮助、各命令 `--help` 和 `--version` 不联网。自动更新进度写入 stderr，不混入业务命令的 stdout 或 JSON；更新失败时 `--json` 返回 `code=CLI_UPDATE_FAILED` 和 `error`。
+
+更新只针对 CLI，已有工程的 Runtime 依赖、锁文件和业务适配仍需另行修改与验证。旧 CLI 不会自动获得自检能力，需要先用 npm 安装命令升级一次。
 
 可追加 `--json` 供 Coding Agent 或脚本读取，例如：
 
@@ -86,7 +90,7 @@ CLI 会把换取到的会话保存到 macOS Keychain。有效会话会复用，
 | 命令 | 是否需要 Agent 目录 | 会发生什么 |
 | --- | --- | --- |
 | `help`、`--help` | 不需要，也不登录 | 列出命令；参数见 `<命令> --help` |
-| `guide` | 不需要，也不登录 | 离线输出 Coding Agent 开发指引，不写文件 |
+| `guide` | 不需要，也不登录 | 自检并按需更新 CLI 后输出当前 Coding Agent 开发指引，不修改工程 |
 | `--version [--json]` | 不需要，也不登录 | 显示当前运行的 CLI 版本，无需联网 |
 | `update [--check] [--json]` | 不需要，也不登录 | 检查公共 npm 最新版，或更新 npm 全局 CLI |
 | `login`、`logout` | 不需要 | 管理账号会话 |
@@ -438,11 +442,10 @@ CLI 不提供 `release`、`publish`、`disable`、`enable` 或 `unpublish`。最
 
 ## 官方工程如何在云端启动
 
-平台在部署阶段解包、准备依赖，再执行 `npm start`。官方模板的启动入口读取：
+平台在部署阶段解包、准备依赖，再执行 `npm start`。Runtime 从包内 `package.json.buddyId` 读取身份；Server 收包时校验它与上传目标一致。连接凭据从环境变量读取：
 
 | 环境变量 | 作用 |
 | --- | --- |
-| `BUDDY_ID` | 平台部署的搭子身份，须与工程匹配 |
 | `BUDDY_TOKEN` | CLI 注入的共享开发 Token；平台托管时由 Server 注入正式 Token |
 | `MLB_GATEWAY_URL` | 平台网关，由部署环境显式注入；未设置时沿用 Runtime 的默认地址 |
 
@@ -479,19 +482,19 @@ Preview 文本发送采用 App WebSocket 的 `messages` 数组，并校验逐项
 
 ## 开发凭据复用
 
-CLI 0.14.1 起，开发 Token 优先从工程 `.env` 读取；首次启动时可迁移旧版 macOS Keychain 中的开发凭据，或通过 `GET /cli/buddies/:id` 领取，再写入 `.env`。更换工程目录不会生成新 Token。新电脑登录并取得搭子开发权限后，可以领取同一把开发 Token。
+开发 Token 从工程 `.env` 读取，并通过 `GET /cli/buddies/:id` 与 Server 返回的当前搭子开发 Token 比对；不匹配时停止启动，确认工程后可用 `--refresh-token` 重新领取。首次启动时直接领取，再写入 `.env`。更换工程目录不会生成新 Token。新电脑登录并取得搭子开发权限后，可以领取同一把开发 Token。
 
 同一个搭子的开发者共享开发 Token 和 `<buddyId>-dev` 身份；同一开发身份仍只能保持一条 Runtime 事件流。正式身份使用另一把 Token，两者互不顶替。开发凭据没有自动过期时间，Server 重置或删除搭子后才失效。
 
-开发 Token 被平台重置后，停止当前 CLI，再运行 `buddy-cli dev --refresh-token` 或 `buddy-cli preview --refresh-token`。这会跳过本地开发凭据，重新领取服务端当前的开发 Token 并更新 `.env`，不在 Server 生成新密钥。读取旧版 Keychain 凭据失败时会明确报错，不将读取失败当成没有凭据。
+开发 Token 被平台重置后，停止当前 CLI，再运行 `buddy-cli dev --refresh-token` 或 `buddy-cli preview --refresh-token`。这会跳过本地开发凭据，重新领取服务端当前的开发 Token 并更新 `.env`，不在 Server 生成新密钥。工程启动不再从旧版 Keychain 的开发 Token 缓存领取凭据。
 
 账号登录凭据仍保存在 macOS Keychain，不写入工程。开发 Token 保存在权限为 `0600` 的工程 `.env`，不传给 Web，也不进入上传包或命令行参数。
 
-### Runtime 0.17.0 本地配置
+### 本地身份与连接配置
 
-首次启动 DEV 时，CLI 将 `BUDDY_ID`、开发版 `BUDDY_TOKEN` 和 `MLB_GATEWAY_URL` 写入工程 `.env`，保留其他配置和注释。后续优先复用；`--refresh-token` 重新领取后更新此文件。开发者登录凭据仍使用系统凭据存储。`.env` 加入 Git 忽略，且始终排除在上传包之外。
+首次启动 DEV 时，CLI 将开发版 `BUDDY_TOKEN` 和 `MLB_GATEWAY_URL` 写入工程 `.env`，保留其他配置和注释，移除旧 `BUDDY_ID` 赋值。身份始终来自 `package.json.buddyId`；只配置 Token 的 `.env` 也可使用。后续复用前向 Server 核对 Token；`--refresh-token` 重新领取后更新此文件。开发者登录凭据仍使用系统凭据存储。`.env` 加入 Git 忽略，且始终排除在上传包之外。
 
-CLI、Preview 与标准 `npm start` 均由 Node 的 `--env-file-if-exists=.env` 加载本地配置，Runtime 自行读取环境变量；托管时平台注入的同名环境变量优先。已有工程显式升级 Runtime 后，CLI 只自动迁移能精确识别的生成入口及标准启动命令，自定义业务代码和脚本保留。
+CLI、Preview 与标准 `npm start` 均由 Node 的 `--env-file-if-exists=.env` 加载本地配置，Runtime 从 `package.json.buddyId` 读取身份、从环境变量读取 Token 和网关；托管时平台注入的同名环境变量优先。已有工程显式升级 Runtime 后，CLI 只自动迁移能精确识别的生成入口及标准启动命令，自定义业务代码和脚本保留。
 
 ### CLI 0.15.1 的 Skill 包名
 
@@ -501,4 +504,10 @@ Creator 使用 `@my-life-buddies/buddy-creator-skill`，头像使用 `@my-life-b
 
 新工程以 `package.json.buddyId` 作为唯一工程绑定，不生成 `buddy.agent.json`，也不需要工程配置的 `schemaVersion`。创建阶段先保存 `{ "buddyId": "平台返回的 ID" }`，生成代码时在同一文件补齐 npm 字段，不覆盖已有工程配置。模型直接维护在业务工厂中，数据声明独立放在 `data-access.json`。本次不提供旧工程自动迁移。
 
-本地 CLI 校验绑定与 `.env.BUDDY_ID`，准备开发凭据；托管身份由 MLB Server 注入环境变量。生成的 `start.mjs` 不读取 `package.json` 或比较 ID。Server 对包中 ID 的部署校验由 Server 实现，CLI 不代替服务端鉴权。
+CLI 与 Runtime 统一使用 `package.json.buddyId`。CLI 启动前校验本地 Token 与 Server 返回的当前搭子 Token 一致；Server 托管只注入正式 Token，收包时比对包内 ID 与上传目标。`start.mjs` 直接调用 Runtime，不重复读取或比较 ID。
+
+### Widget 卡片打开目标
+
+Runtime 0.19.0 支持在 `schema.json.openTargets` 声明入口。业务通过 `conversation.widget.send(id, { idempotencyKey, openTarget })` 或模型工具发送 `version: 1`、`entry` 以及可选 `resource`、`state`；记录必须已经存在。H5 读取 `window.widget.openTarget` 定位，无目标时显示默认页。
+
+后台和本地模拟器保留每条消息的目标，通过 `POST /app/widgets/:widgetId/presentation` 获取鉴权页面；列表入口不传目标。同一 Widget 的不同卡片、加载重试与 DEV 重载分别保留自己的目标；目标记录删除或权限变化时显示打开失败，不回退默认页。

package/dist/bin/buddy.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 // apps/cli/src/bin/buddy.ts
-import { execFile as execFile2 } from "node:child_process";
-import { promisify as promisify2 } from "node:util";
+import { execFile as execFile3 } from "node:child_process";
+import { promisify as promisify3 } from "node:util";
 import { stdin, stderr, stdout } from "node:process";
 import { createRequire } from "node:module";
-import { dirname } from "node:path";
+import { dirname as dirname2 } from "node:path";
 import { createInterface } from "node:readline/promises";
 import {
   PromptCancelledError,
@@ -101,7 +101,9 @@ var PREVIEW_COMMAND_HELP = `\u7528\u6CD5:
   \u4FDD\u6301\u7EC8\u7AEF\u8FD0\u884C\uFF1B\u9000\u51FA CLI \u4F1A\u505C\u6B62 DEV \u5E76\u65AD\u5F00\u8FDE\u63A5\uFF0C\u5237\u65B0\u540E\u53F0\u4E0D\u4F1A\u81EA\u52A8\u542F\u52A8 DEV\u3002
   \u672A\u914D\u7F6E\u5730\u5740\u65F6\u8FDE\u63A5 MLB \u6D4B\u8BD5\u73AF\u5883 ${DEFAULT_MLB_TEST_URL}\uFF08HTTP \u4EC5\u9650\u6D4B\u8BD5\uFF09\u3002
   CLI \u7EDF\u4E00\u542F\u52A8\u5E76\u7BA1\u7406\u5DE5\u7A0B\u4E2D\u7684\u5B98\u65B9 Runtime\uFF1B\u6BCF\u6B21\u542F\u52A8\u6216\u91CD\u8F7D\u5FC5\u987B\u901A\u8FC7 npm \u6700\u65B0\u7A33\u5B9A\u7248\u68C0\u67E5\u3002
+  \u8EAB\u4EFD\u8BFB\u53D6 package.json.buddyId\uFF1B.env \u4FDD\u5B58 Token\uFF0C\u542F\u52A8\u524D\u5411 Server \u6821\u9A8C\u6240\u5C5E\u642D\u5B50\u3002
   --refresh-token \u91CD\u65B0\u9886\u53D6\u5DF2\u6709\u5F00\u53D1 Token\uFF0C\u66F4\u65B0\u5DE5\u7A0B .env\uFF1B\u4E0D\u4F1A\u751F\u6210\u65B0\u5BC6\u94A5\u3002
+  Widget \u6D88\u606F\u5361\u7247\u4FDD\u7559\u6307\u5B9A\u8BB0\u5F55\u7684\u6253\u5F00\u76EE\u6807\uFF0C\u5C0F\u6302\u4EF6\u5217\u8868\u6253\u5F00\u9ED8\u8BA4\u89C6\u56FE\u3002
   \u6A21\u62DF\u5668\u4F7F\u7528\u5F53\u524D\u5F00\u53D1\u8005\u8D26\u53F7\u8BBF\u95EE <buddyId>-dev \u8C03\u8BD5\u5206\u8EAB\u3002`;
 function valueAfter(args, index, flag) {
   const value = args[index + 1];
@@ -438,9 +440,42 @@ function assertSupportedDeveloperPlatform(platform = process.platform) {
 // apps/cli/src/self-update.ts
 import { execFile } from "node:child_process";
 import { lstat, readFile, realpath } from "node:fs/promises";
-import { homedir } from "node:os";
-import { isAbsolute, join } from "node:path";
+import { homedir as homedir2 } from "node:os";
+import { isAbsolute, join as join2 } from "node:path";
 import { promisify } from "node:util";
+
+// apps/cli/src/update-lock.ts
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { createHash as createHash2 } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+var defaultUpdateCache = () => join(homedir(), ".cache", "buddy-cli", "updates");
+var globalUpdateLock = (cache, prefix) => join(cache, "locks", createHash2("sha256").update(prefix).digest("hex"));
+async function withUpdateLock(path, signal, action) {
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  const deadline = Date.now() + 2e5;
+  for (; ; ) {
+    signal?.throwIfAborted();
+    try {
+      await mkdir(path, { mode: 448 });
+      break;
+    } catch (cause) {
+      if (cause.code !== "EEXIST") throw cause;
+      if (Date.now() >= deadline) throw new Error(`\u7B49\u5F85\u5176\u4ED6 CLI \u66F4\u65B0\u8D85\u65F6\u3002\u8BF7\u786E\u8BA4\u66F4\u65B0\u8FDB\u7A0B\u5DF2\u9000\u51FA\uFF0C\u518D\u6E05\u7406\u9501\u76EE\u5F55\u5E76\u91CD\u8BD5\uFF1A${path}`);
+      await delay(100, void 0, { signal });
+    }
+  }
+  try {
+    await writeFile(`${path}/owner.json`, JSON.stringify({ pid: process.pid, startedAt: Date.now() }), { mode: 384 });
+    signal?.throwIfAborted();
+    return await action();
+  } finally {
+    await rm(path, { recursive: true, force: true });
+  }
+}
+
+// apps/cli/src/self-update.ts
 var PACKAGE = "@my-life-buddies/cli";
 var REGISTRY = "https://registry.npmjs.org/";
 var MANUAL_UPDATE = `npm install --global ${PACKAGE}@latest --registry=${REGISTRY}`;
@@ -455,9 +490,12 @@ var HELP = `\u7528\u6CD5:
 --json     \u8F93\u51FA JSON\uFF0C\u4F9B Coding Agent \u6216\u811A\u672C\u8BFB\u53D6
 
 \u65E0\u9700\u767B\u5F55\u642D\u642D\u8D26\u53F7\uFF0C\u4E5F\u65E0\u9700\u8FDB\u5165\u642D\u5B50\u5DE5\u7A0B\u3002
-update \u66F4\u65B0\u5F53\u524D npm \u5168\u5C40\u5B89\u88C5\u7684 CLI\uFF0C\u4E0D\u4FEE\u6539\u642D\u5B50\u5DE5\u7A0B\u7684 Runtime \u4F9D\u8D56\u3002
+\u6B63\u5E38\u547D\u4EE4\uFF08\u542B guide\uFF09\u4F1A\u5148\u8054\u7F51\u81EA\u68C0\uFF0C\u81EA\u52A8\u66F4\u65B0\u540E\u7531\u65B0\u7248\u7EE7\u7EED\u6267\u884C\uFF1B\u7B49\u5F85\u5B8C\u6210\u5373\u53EF\u3002
+--help\u3001\u5404\u547D\u4EE4 --help \u4E0E --version \u79BB\u7EBF\u53EF\u7528\uFF1B\u67E5\u8BE2\u6216\u66F4\u65B0\u5931\u8D25\u65F6\u505C\u6B62\u4E1A\u52A1\u64CD\u4F5C\u3002
+update \u7528\u4E8E\u5355\u72EC\u66F4\u65B0\u5F53\u524D npm \u5168\u5C40\u5B89\u88C5\u7684 CLI\uFF0C\u4E0D\u4FEE\u6539\u642D\u5B50\u5DE5\u7A0B\u7684 Runtime \u4F9D\u8D56\u3002
 \u5DF2\u7ECF\u662F\u6700\u65B0\u7248\u6216\u5F53\u524D\u7248\u672C\u66F4\u9AD8\u65F6\u4E0D\u5B89\u88C5\u3001\u4E0D\u964D\u7EA7\u3002
-\u6E90\u7801\u3001npm link\u3001\u5C40\u90E8\u5B89\u88C5\u6216 npx \u8FD0\u884C\u65F6\uFF0C\u8BF7\u4F7F\u7528\u539F\u6765\u7684\u5B89\u88C5\u65B9\u5F0F\u66F4\u65B0\u3002
+\u6E90\u7801\u3001npm link\u3001\u5C40\u90E8\u5B89\u88C5\u6216 npx \u7684\u6B63\u5E38\u547D\u4EE4\u4F7F\u7528\u7F13\u5B58\u7684\u65B0\u7248\u6267\u884C\uFF0C\u4E0D\u8986\u76D6\u6E90\u7801\u6216\u5DE5\u7A0B\u4F9D\u8D56\u3002
+\u4E0A\u8FF0\u5B89\u88C5\u65B9\u5F0F\u4E0D\u80FD\u7528 update \u5355\u72EC\u4FEE\u6539\u539F\u5B89\u88C5\uFF0C\u8BF7\u6CBF\u7528\u539F\u6765\u7684\u5B89\u88C5\u65B9\u5F0F\u66F4\u65B0\u3002
 \u65E7\u7248 CLI \u5C1A\u65E0 update \u547D\u4EE4\u65F6\uFF0C\u8FD0\u884C\uFF1A
   ${MANUAL_UPDATE}`;
 function parseVersion(version) {
@@ -510,11 +548,11 @@ async function latestVersion(options) {
 }
 async function installUpdate(version, options) {
   const runNpm = options.runNpm ?? ((args, settings2) => execute("npm", args, { ...settings2, encoding: "utf8", maxBuffer: 4 * 1024 * 1024 }));
-  const settings = { cwd: homedir(), signal: options.signal, timeout: 1e4 };
+  const settings = { cwd: homedir2(), signal: options.signal, timeout: 1e4 };
   const { stdout: stdout2 } = await runNpm(["prefix", "--global"], settings);
   const prefix = stdout2.trim();
   if (!isAbsolute(prefix) || /[\r\n]/u.test(prefix)) throw new Error("\u65E0\u6CD5\u786E\u5B9A npm \u5168\u5C40\u5B89\u88C5\u76EE\u5F55\u3002");
-  const installedRoot = join(prefix, "lib", "node_modules", PACKAGE);
+  const installedRoot = join2(prefix, "lib", "node_modules", PACKAGE);
   let sameInstallation = false;
   try {
     sameInstallation = !(await lstat(installedRoot)).isSymbolicLink() && await realpath(installedRoot) === await realpath(options.packageRoot);
@@ -523,28 +561,33 @@ async function installUpdate(version, options) {
   if (!sameInstallation) {
     throw new Error("\u5F53\u524D CLI \u4E0D\u662F\u8FD9\u4E2A npm \u73AF\u5883\u7684\u5168\u5C40\u5B89\u88C5\uFF0C\u4E0D\u80FD\u76F4\u63A5\u66F4\u65B0\u3002\u8BF7\u7528\u539F\u6765\u7684\u5B89\u88C5\u65B9\u5F0F\u66F4\u65B0\uFF1B\u82E5\u4F7F\u7528 nvm\uFF0C\u8BF7\u5148\u5207\u6362\u5230\u5B89\u88C5\u8BE5 CLI \u7684 Node.js \u73AF\u5883\u3002");
   }
-  try {
-    await runNpm([
-      "install",
-      "--global",
-      `${PACKAGE}@${version}`,
-      "--prefix",
-      prefix,
-      `--registry=${REGISTRY}`,
-      `--@my-life-buddies:registry=${REGISTRY}`,
-      "--engine-strict",
-      "--no-audit",
-      "--no-fund"
-    ], { ...settings, timeout: 18e4 });
-  } catch (cause) {
-    if (options.signal?.aborted) throw new Error("\u66F4\u65B0\u5DF2\u53D6\u6D88\uFF0C\u8BF7\u8FD0\u884C buddy-cli --version \u68C0\u67E5\u5B89\u88C5\u72B6\u6001\u3002");
-    const code = cause && typeof cause === "object" && "code" in cause ? String(cause.code) : "unknown";
-    throw new Error(`npm \u5B89\u88C5\u672A\u5B8C\u6210\uFF08${code}\uFF09\u3002\u8BF7\u68C0\u67E5\u7F51\u7EDC\u548C\u5168\u5C40\u76EE\u5F55\u6743\u9650\uFF0C\u7136\u540E\u91CD\u8BD5\uFF1A${MANUAL_UPDATE}`);
-  }
-  const installed = JSON.parse(await readFile(join(installedRoot, "package.json"), "utf8"));
-  if (installed.name !== PACKAGE || installed.version !== version) {
-    throw new Error(`npm \u5DF2\u7ED3\u675F\uFF0C\u4F46\u672A\u786E\u8BA4\u5B89\u88C5\u5230 ${version}\u3002\u8BF7\u8FD0\u884C buddy-cli --version \u68C0\u67E5\uFF0C\u5FC5\u8981\u65F6\u91CD\u8BD5\uFF1A${MANUAL_UPDATE}`);
-  }
+  await withUpdateLock(globalUpdateLock(options.cacheDirectory ?? defaultUpdateCache(), prefix), options.signal, async () => {
+    const current = JSON.parse(await readFile(join2(installedRoot, "package.json"), "utf8"));
+    if (current.name === PACKAGE && current.version === version) return;
+    if (current.name === PACKAGE && compareVersions(current.version, version) > 0) throw new Error("\u53E6\u4E00\u4E2A\u8FDB\u7A0B\u5DF2\u5B89\u88C5\u66F4\u65B0\u7684 CLI\uFF0C\u8BF7\u91CD\u65B0\u6267\u884C\u547D\u4EE4\u3002");
+    try {
+      await runNpm([
+        "install",
+        "--global",
+        `${PACKAGE}@${version}`,
+        "--prefix",
+        prefix,
+        `--registry=${REGISTRY}`,
+        `--@my-life-buddies:registry=${REGISTRY}`,
+        "--engine-strict",
+        "--no-audit",
+        "--no-fund"
+      ], { ...settings, timeout: 18e4 });
+    } catch (cause) {
+      if (options.signal?.aborted) throw new Error("\u66F4\u65B0\u5DF2\u53D6\u6D88\uFF0C\u8BF7\u8FD0\u884C buddy-cli --version \u68C0\u67E5\u5B89\u88C5\u72B6\u6001\u3002");
+      const code = cause && typeof cause === "object" && "code" in cause ? String(cause.code) : "unknown";
+      throw new Error(`npm \u5B89\u88C5\u672A\u5B8C\u6210\uFF08${code}\uFF09\u3002\u8BF7\u68C0\u67E5\u7F51\u7EDC\u548C\u5168\u5C40\u76EE\u5F55\u6743\u9650\uFF0C\u7136\u540E\u91CD\u8BD5\uFF1A${MANUAL_UPDATE}`);
+    }
+    const installed = JSON.parse(await readFile(join2(installedRoot, "package.json"), "utf8"));
+    if (installed.name !== PACKAGE || installed.version !== version) {
+      throw new Error(`npm \u5DF2\u7ED3\u675F\uFF0C\u4F46\u672A\u786E\u8BA4\u5B89\u88C5\u5230 ${version}\u3002\u8BF7\u8FD0\u884C buddy-cli --version \u68C0\u67E5\uFF0C\u5FC5\u8981\u65F6\u91CD\u8BD5\uFF1A${MANUAL_UPDATE}`);
+    }
+  });
 }
 async function runSelfUpdateCommand(args, io, options) {
   const versionOnly = args[0] === "--version" || args[0] === "-v";
@@ -599,6 +642,143 @@ async function runSelfUpdateCommand(args, io, options) {
   }
 }
 
+// apps/cli/src/auto-update.ts
+import { execFile as execFile2, spawn } from "node:child_process";
+import { lstat as lstat2, mkdir as mkdir2, mkdtemp, readFile as readFile2, realpath as realpath2, rename, rm as rm2, writeFile as writeFile2 } from "node:fs/promises";
+import { constants, homedir as homedir3 } from "node:os";
+import { isAbsolute as isAbsolute2, join as join3 } from "node:path";
+import { promisify as promisify2 } from "node:util";
+var PACKAGE2 = "@my-life-buddies/cli";
+var REGISTRY2 = "https://registry.npmjs.org/";
+var execute2 = promisify2(execFile2);
+var HANDOFF_ENV = "BUDDY_CLI_UPDATE_HANDOFF";
+async function installedVersion(root) {
+  try {
+    const pkg = JSON.parse(await readFile2(join3(root, "package.json"), "utf8"));
+    return pkg.name === PACKAGE2 && typeof pkg.version === "string" ? pkg.version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function checkedEntry(root, version) {
+  if (await installedVersion(root) !== version) throw new Error(`CLI \u5B89\u88C5\u7ED3\u679C\u4E0E\u672C\u6B21\u8981\u6C42\u7684 ${version} \u4E0D\u4E00\u81F4\uFF0C\u8BF7\u91CD\u8BD5\u3002`);
+  const entry = join3(root, "dist", "bin", "buddy.js");
+  if (!(await lstat2(entry)).isFile()) throw new Error("\u65B0\u7248 CLI \u7F3A\u5C11\u6709\u6548\u7684\u6267\u884C\u5165\u53E3\u3002");
+  return entry;
+}
+async function prepareLatest(version, options) {
+  const cache = options.cacheDirectory ?? defaultUpdateCache();
+  const runNpm = options.runNpm ?? ((args, settings2) => execute2("npm", args, { ...settings2, encoding: "utf8", maxBuffer: 4 * 1024 * 1024 }));
+  const settings = { cwd: homedir3(), signal: options.signal, timeout: 1e4 };
+  const { stdout: stdout2 } = await runNpm(["prefix", "--global"], settings);
+  const prefix = stdout2.trim();
+  if (!isAbsolute2(prefix) || /[\r\n]/u.test(prefix)) throw new Error("\u65E0\u6CD5\u786E\u5B9A npm \u5168\u5C40\u5B89\u88C5\u76EE\u5F55\u3002");
+  const globalRoot = join3(prefix, "lib", "node_modules", PACKAGE2);
+  let isGlobal = false;
+  try {
+    isGlobal = !(await lstat2(globalRoot)).isSymbolicLink() && await realpath2(globalRoot) === await realpath2(options.packageRoot);
+  } catch {
+  }
+  if (isGlobal) {
+    await installUpdate(version, options);
+    return checkedEntry(globalRoot, version);
+  }
+  const destination = join3(cache, "releases", version);
+  return withUpdateLock(join3(cache, "locks", `release-${version}`), options.signal, async () => {
+    const root = join3(destination, "node_modules", PACKAGE2);
+    try {
+      return await checkedEntry(root, version);
+    } catch {
+    }
+    await mkdir2(join3(cache, "releases"), { recursive: true, mode: 448 });
+    const temporary = await mkdtemp(join3(cache, "releases", ".install-"));
+    try {
+      await writeFile2(join3(temporary, "package.json"), JSON.stringify({ private: true }));
+      try {
+        await runNpm(
+          [
+            "install",
+            "--prefix",
+            temporary,
+            "--save-exact",
+            `${PACKAGE2}@${version}`,
+            `--registry=${REGISTRY2}`,
+            `--@my-life-buddies:registry=${REGISTRY2}`,
+            "--engine-strict",
+            "--no-audit",
+            "--no-fund"
+          ],
+          { cwd: temporary, signal: options.signal, timeout: 18e4 }
+        );
+      } catch (cause) {
+        const code = cause && typeof cause === "object" && "code" in cause ? String(cause.code) : "unknown";
+        throw new Error(`\u65B0\u7248 CLI \u7F13\u5B58\u5B89\u88C5\u5931\u8D25\uFF08${code}\uFF09\uFF0C\u8BF7\u68C0\u67E5\u7F51\u7EDC\u3001Node.js \u7248\u672C\u548C\u76EE\u5F55\u6743\u9650\u540E\u91CD\u8BD5\u3002`);
+      }
+      await checkedEntry(join3(temporary, "node_modules", PACKAGE2), version);
+      options.signal?.throwIfAborted();
+      await rm2(destination, { recursive: true, force: true });
+      await rename(temporary, destination);
+      return checkedEntry(root, version);
+    } finally {
+      await rm2(temporary, { recursive: true, force: true });
+    }
+  });
+}
+async function runUpdatedCli(entry, args, options) {
+  options.signal?.throwIfAborted();
+  return new Promise((resolve2, reject) => {
+    const child = spawn(process.execPath, [entry, ...args], { cwd: options.cwd, env: options.env, stdio: "inherit" });
+    let killTimer;
+    const abort = () => {
+      const signal = options.signal?.reason?.message === "SIGINT" ? "SIGINT" : "SIGTERM";
+      child.kill(signal);
+      killTimer ??= setTimeout(() => child.kill("SIGKILL"), 5e3);
+      killTimer.unref();
+    };
+    const cleanup = () => {
+      options.signal?.removeEventListener("abort", abort);
+      clearTimeout(killTimer);
+    };
+    child.once("error", (error) => {
+      cleanup();
+      reject(error);
+    });
+    child.once("exit", (code, signal) => {
+      cleanup();
+      resolve2({ exitCode: code ?? 128 + (signal ? constants.signals[signal] : 1) });
+    });
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted) abort();
+  });
+}
+async function runAutoUpdate(args, io, options) {
+  if (args[0] === "help" || args[0] === "update" || args[0] === "--version" || args[0] === "-v" || args.includes("--help") || args.includes("-h")) return void 0;
+  try {
+    const env = { ...options.env ?? process.env };
+    const handoff = env[HANDOFF_ENV];
+    if (handoff !== void 0) {
+      delete env[HANDOFF_ENV];
+      if (!options.env) delete process.env[HANDOFF_ENV];
+      const expected = JSON.parse(handoff);
+      const entry2 = await realpath2(join3(options.packageRoot, "dist", "bin", "buddy.js"));
+      if (expected.parent !== process.ppid || expected.version !== options.version || expected.entry !== entry2 || JSON.stringify(expected.args) !== JSON.stringify(args)) throw new Error("CLI \u81EA\u52A8\u66F4\u65B0\u63A5\u7EED\u6821\u9A8C\u5931\u8D25\uFF0C\u8BF7\u91CD\u65B0\u8FD0\u884C\u547D\u4EE4\u3002");
+      return void 0;
+    }
+    const latest = await latestVersion(options);
+    if (compareVersions(latest, options.version) <= 0) return void 0;
+    io.writeError(`CLI \u81EA\u52A8\u66F4\u65B0\uFF1A${options.version} \u2192 ${latest}\u3002\u5B8C\u6210\u540E\u7EE7\u7EED\u5F53\u524D\u547D\u4EE4\uFF0C\u8BF7\u52FF\u91CD\u590D\u6267\u884C\u3002`);
+    const entry = await realpath2(await prepareLatest(latest, options));
+    options.signal?.throwIfAborted();
+    env[HANDOFF_ENV] = JSON.stringify({ parent: process.pid, version: latest, entry, args });
+    return await (options.runCli ?? runUpdatedCli)(entry, args, { cwd: options.cwd ?? process.cwd(), env, signal: options.signal });
+  } catch (cause) {
+    const error = options.signal?.aborted ? "CLI \u81EA\u52A8\u66F4\u65B0\u5DF2\u53D6\u6D88\uFF0C\u539F\u547D\u4EE4\u672A\u6267\u884C\u3002" : `CLI \u81EA\u68C0\u6216\u66F4\u65B0\u5931\u8D25\uFF0C\u539F\u547D\u4EE4\u672A\u6267\u884C\uFF1A${cause instanceof Error ? cause.message : String(cause)}`;
+    if (args.includes("--json")) io.write(JSON.stringify({ code: "CLI_UPDATE_FAILED", error }));
+    else io.writeError(error);
+    return { exitCode: 1 };
+  }
+}
+
 // apps/cli/src/bin/buddy.ts
 import { latestRuntimeTemplate, scaffoldPlatformAgent } from "./core.js";
 var TerminalIO = class {
@@ -616,7 +796,7 @@ var TerminalIO = class {
   }
   async openMetaPreview(path) {
     try {
-      await promisify2(execFile2)("open", [path]);
+      await promisify3(execFile3)("open", [path]);
     } catch {
       this.write(`\u8BF7\u6253\u5F00\u672C\u5730\u5934\u50CF\u9884\u89C8\u540E\u518D\u786E\u8BA4\uFF1A${path}`);
     }
@@ -683,11 +863,12 @@ try {
   const args = process.argv.slice(2);
   const require2 = createRequire(import.meta.url);
   const manifestPath = require2.resolve("@my-life-buddies/cli/package.json");
-  const maintenance = await runSelfUpdateCommand(args, terminal, {
+  const updateOptions = {
     version: require2(manifestPath).version,
-    packageRoot: dirname(manifestPath),
+    packageRoot: dirname2(manifestPath),
     signal: lifecycle.signal
-  });
+  };
+  const maintenance = await runSelfUpdateCommand(args, terminal, updateOptions) ?? await runAutoUpdate(args, terminal, updateOptions);
   const command = args[0];
   let platformHost;
   const host = () => platformHost ??= new BuddyPlatformHost({ signal: lifecycle.signal });