@coze/cli 0.3.1 → 0.3.2-alpha.77ac1a

package/README.md

@@ -8,7 +8,17 @@ Coze CLI — A command-line tool for interacting with [Coze](https://www.coze.cn
 npm install -g @coze/cli
 ```
 
-After installation the CLI silently runs `coze self skill install`, which installs the bundled skills to your local AI agents (Claude Code, Trae, Comate, ...). If that step is skipped or fails, run it manually:
+After installation the CLI silently runs `coze self skill install`, which installs the bundled skills to your local AI agents (Claude Code, Trae, Comate, ...). On a first install this sync can take up to a minute (it detects every AI agent on your machine and copies/links the skills), so the install may appear to pause near the end — this is expected.
+
+> npm 7+ hides lifecycle-script output by default, so you won't see the sync progress. To watch it, install with `--foreground-scripts`:
+>
+> ```bash
+> npm install -g @coze/cli --foreground-scripts
+> ```
+>
+> (pnpm and yarn classic show the progress without any extra flag.)
+
+If that step is skipped or fails, run it manually:
 
 ```bash
 coze self skill install
@@ -809,6 +819,23 @@ coze upgrade --tag beta
 | `--force`     | Force upgrade even if already on the latest version    |
 | `--tag <tag>` | Specify the dist-tag to upgrade to (default: `latest`) |
 
+#### Auto-Upgrade
+
+By default Coze CLI keeps itself up to date: it checks for new versions in the background (throttled, never blocking the current command) and, in `auto` mode, installs the update silently so it takes effect on your **next run**. Behavior is controlled via `coze config set`:
+
+| Config            | Values                          | Default  | Description                                                                                          |
+| ----------------- | ------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
+| `upgrade.mode`    | `auto` / `notify` / `off`       | `auto`   | `auto`: silent background upgrade; `notify`: only prompt to run `coze upgrade`; `off`: disable checks |
+| `upgrade.channel` | `latest` / `beta` / `alpha` / … | `latest` | npm dist-tag to track                                                                               |
+
+```bash
+coze config set upgrade.mode notify    # only prompt, don't auto-install
+coze config set upgrade.mode off       # disable upgrade checks entirely
+coze config set upgrade.channel beta   # track the beta channel
+```
+
+Upgrade checks are automatically skipped in CI (the `CI` env var is set), for dev/local builds, and when `COZE_CLI_NO_UPDATE_NOTIFIER` is set. Version checks are throttled to at most once every **4 hours**; a failed background upgrade is retried at most once every **10 minutes**. In JSON output the hint is attached as `_notice.update` with a ready-to-run `command` field. See [`docs/design/auto-upgrade-and-skill-sync.md`](docs/design/auto-upgrade-and-skill-sync.md) for the full auto-upgrade and bundled-skill design.
+
 ### Other Commands
 
 | Command      | Description                                                       |
@@ -855,7 +882,9 @@ The CLI reads configuration from multiple sources with the following priority (h
 | `COZE_PROJECT_ID`        | Default Project ID (used by `message` commands)     |
 | `COZE_CONFIG_FILE`       | Custom configuration file path                      |
 | `COZE_CONFIG_SCOPE`      | Config write scope: `global` or `local`             |
-| `COZE_AUTO_CHECK_UPDATE` | Enable/disable auto update check: `true` or `false` |
+| `COZE_CLI_NO_UPDATE_NOTIFIER` | Set to any non-empty value to skip the upgrade check for this run (overrides `upgrade.mode`) |
+| `COZE_CLI_NO_SKILL_NOTIFIER`  | Set to any non-empty value to suppress the bundled-skill version-mismatch notice            |
+| `CI`                     | When set (to any value other than `false`/`0`), auto-skips upgrade checks and skill notices |
 
 ## Exit Codes
 

package/bin/postinstall.js

@@ -18,7 +18,7 @@ try {
   const { spawnSync } = require('child_process');
 
   // CI 环境不执行同步（不可控环境不写家目录）
-  // 开发仓库内的安装（rush update / pnpm install）也跳过：发布包不含 src/
+  // 开发仓库内的依赖更新（rush update / pnpm add 等）也跳过：发布包不含 src/
   if (process.env.CI || existsSync(join(__dirname, '..', 'src'))) {
     process.exit(0);
   }
@@ -26,8 +26,16 @@ try {
   const useColor = !process.env.NO_COLOR;
   const cyan = text => (useColor ? `[36m${text}[0m` : text);
 
+  // 同步前先给一行"正在进行、请稍候"的预期文案：扇出会探测本机所有 AI agent 并
+  // 拷贝/软链 skill，首次安装可能耗时近 1 分钟。注意 npm >= 7 默认丢弃 postinstall
+  // 输出（需 --foreground-scripts 才可见），故此提示主要服务 pnpm / yarn / 旧版 npm。
+  process.stdout.write(
+    `\n${cyan('Coze CLI')}: syncing bundled skills to your AI agents ` +
+      '(first install can take up to a minute)...\n',
+  );
+
   // 通过包内 CLI 入口走真实的 `coze self skill install` 代码路径（skipAuth，纯本地：
-  // 释放 bundled skills 到 ~/.coze/cli/skills 并软链到已安装的 AI agents）。
+  // 委托 skills 工具把 bundled skills 拷入中心池 ~/.agents/skills 并软链到已安装的 AI agents）。
   // 用户改过的 skill 不会被覆盖（sync 默认不带 --force 即阻止）。
   const result = spawnSync(
     process.execPath,