@yosai/cli 0.2.1-test.3 → 0.2.1-test.7

package/README.md

@@ -10,7 +10,7 @@ YOS 能力的 Agent 执行入口：终端直调 YOS 工具 + 知识库文件上
 ## 快速开始
 
 ```bash
-yos login                          # 配置访问令牌（客户端「个人设置-访问令牌」页创建并复制）与端点
+yos login                          # 配置访问令牌（客户端「个人设置-访问令牌」页创建并复制）与服务环境
 yos doctor                         # 诊断配置与连通（显示当前身份）
 yos ping                           # 探活：连接与令牌有效性（退出码即结论，客户端对接用）
 yos kb list                        # 我的知识库
@@ -27,7 +27,7 @@ yos tool list                      # 底层工具通道（领域命令未覆盖
 
 | 命令 | 说明 |
 |---|---|
-| `yos login` | 配置访问令牌与端点（校验身份后保存） |
+| `yos login` | 配置访问令牌与服务环境（校验身份后保存） |
 | `yos doctor` | 诊断配置、访问令牌、连通、Skill 状态与 CLI 版本 |
 | `yos ping` | 探活：检查连接是否成功、令牌是否有效（退出码 0/2/3/4 即结论，客户端检测对接用） |
 | `yos kb <动作>` | 知识库：`list` / `detail` / `update` / `upload`（建库、删库请到 YOS 客户端） |
@@ -36,11 +36,11 @@ yos tool list                      # 底层工具通道（领域命令未覆盖
 | `yos support <动作>` | 支持：`manual` / `manual-read` / `manual-search` / `upgrade` / `upgrade-log` / `feedback` |
 | `yos transcript <动作>` | 转写：`list` / `detail` |
 | `yos tool list` / `schema` / `call` | 底层工具通道（领域命令未覆盖时兜底） |
-| `yos version [--check]` | CLI 版本（`--check` 比对 npmjs 最新版） |
-| `yos update [--check]` | 升级到 npmjs 最新版并自动重同步 Skill |
+| `yos version [--check]` | CLI 版本（`--check` 比对对应通道最新版） |
+| `yos update [--check]` | 手动升级到对应通道最新版并自动重同步 Skill（平时后台自动更新，一般无需执行） |
 | `yos skill install [--target <dir>]` | 安装内置 Skill |
 
-所有命令支持 `--json` 输出与统一退出码（0 成功 / 1 业务失败 / 2 参数错误 / 3 网络 / 4 鉴权）。
+所有命令支持 `--json` 输出与统一退出码（0 成功 / 1 业务失败 / 2 参数错误 / 3 网络 / 4 鉴权 / 5 版本过低）。
 
 ## 给 Agent 使用
 
@@ -55,13 +55,15 @@ yos skill install      # 安装 7 个内置 Skill（总入口 + 领域 + 安装
 ## 配置
 
 - 配置文件：`~/.config/yos/config.json`（权限 0600；目录可用 `YOS_CONFIG_DIR` 覆盖）
-- 环境变量（均优先于配置文件，适合 CI/容器场景）：`YOS_API_KEY` 访问令牌、`YOS_ENDPOINT` 服务端点
-- 端点：默认生产环境 `https://yos-bff.linkduoo.com`，`yos login --endpoint <url>` 持久切换（本地联调可用 http://localhost:8080）；`yos doctor` 显示当前生效端点及其来源
+- 环境变量（均优先于配置文件，适合 CI/容器场景）：`YOS_API_KEY` 访问令牌、`YOS_ENV` 服务环境（prod / test / dev）
+- 自动更新：命令执行后会在后台检查对应通道并静默更新到最新版（下次运行生效，自动重同步 Skill）；升级通道跟随服务环境——测试环境跟随 test 通道，dev 不自动更新；设置 `YOS_NO_AUTO_UPDATE=1` 可关闭
+- 服务环境：缺省生产；`yos login --env test` 切到测试环境，`--env dev` 指向本机开发服务（http://localhost:8080）；`yos doctor` 显示当前生效环境及其来源
 
 ## 故障排查
 
 - 退出码 4（鉴权失败）：访问令牌无效/已吊销/已过期，重新 `yos login`
 - 退出码 2（参数错误）：CLI 本地拦截、未发请求，按 `提示:` 里的用法改写参数
+- 退出码 5（版本过低）：服务端要求的 CLI 最低版本高于当前版本，执行 `yos update` 升级后重试
 - 上传报 20MB 上限：单文件上限 20MB，更大文件暂不支持
 - 下载报「没有该资源的访问权限：DOWNLOAD.xxx」：只有阅读权限的库不支持下载原文件，需库管理员授权
-- 退出码 3（网络）：确认端点可达；`yos version --check` 报网络错则是 npm 或 registry 不可达
+- 退出码 3（网络）：确认服务地址可达；`yos version --check` 报网络错则是 npm 或 registry 不可达

package/dist/cli.js

@@ -2,6 +2,7 @@ import { parseArgs } from 'node:util';
 import { DOMAIN_META } from './domain-commands.js';
 import { CliError, EXIT, UsageError } from './errors.js';
 import { print, printErr, renderRows } from './output.js';
+import { handleUpdateNotice } from './update-notice.js';
 const registry = [];
 const GROUP_ORDER = ['知识库 kb', '文档 docs', '检索 retrieve', '支持 support', '转写 transcript', '工具通道', 'Agent 接入', '基础'];
 const RISK_LABEL = { read: '只读', write: '写入', danger: '高危' };
@@ -20,13 +21,12 @@ export function renderHelp() {
         '',
         '约定:',
         '  - 输出默认人类可读；--json 输出结构化结果（工具返回原文在 text 字段内）',
-        '  - 退出码：0 成功 / 1 业务失败 / 2 参数错误 / 3 网络错误 / 4 鉴权失败',
+        '  - 退出码：0 成功 / 1 业务失败 / 2 参数错误 / 3 网络错误 / 4 鉴权失败 / 5 版本过低需升级',
         '  - 删除类操作前先用 yos docs count <node_code> 查询影响范围，并取得用户明确确认',
         '',
         '环境变量（均优先于配置文件，便于 CI 免落盘）:',
         '  YOS_API_KEY     访问令牌',
         '  YOS_ENV         服务环境（prod / test / dev；缺省生产）',
-        '  YOS_ENDPOINT    自定义服务地址（CI / 本地联调，一般无需设置）',
         '  YOS_CONFIG_DIR  配置目录（缺省 ~/.config/yos）',
         '',
         '示例:',
@@ -186,4 +186,7 @@ export async function dispatch(argv) {
         printErr(`错误: ${error instanceof Error ? error.message : String(error)}`);
         return EXIT.BUSINESS;
     }
+    finally {
+        handleUpdateNotice(argv, command.name);
+    }
 }

package/dist/commands/doctor.js

@@ -1,6 +1,6 @@
 import { register } from '../cli.js';
-import { loadConfig, maskKey, resolveEndpoint, resolveKey } from '../config.js';
-import { envLabel } from '../endpoints.js';
+import { loadConfig, maskKey, resolveEnv, resolveKey } from '../config.js';
+import { endpointOfEnv, envLabel } from '../endpoints.js';
 import { CliError, EXIT } from '../errors.js';
 import { formatIdentity, OpenApisClient } from '../openapis-client.js';
 import { print, printJson } from '../output.js';
@@ -16,7 +16,8 @@ register({
     async run({ flags }) {
         const checks = [];
         const config = loadConfig();
-        const endpoint = resolveEndpoint(config);
+        const env = resolveEnv(config);
+        const endpoint = endpointOfEnv(env);
         checks.push({
             name: '配置文件',
             ok: config !== null,
@@ -25,7 +26,7 @@ register({
         checks.push({
             name: '服务环境',
             ok: true,
-            detail: `${envLabel(endpoint)}（来自 ${endpointSource(config)}）`,
+            detail: `${envLabel(env)}（来自 ${endpointSource(config)}）`,
         });
         let key = null;
         try {
@@ -60,7 +61,7 @@ register({
         checks.push({
             name: 'CLI 版本',
             ok: meta !== null,
-            detail: meta ? `${meta.version}（环境=${envLabel(endpoint)}）` : 'unknown（未找到 package.json）',
+            detail: meta ? `${meta.version}（环境=${envLabel(env)}）` : 'unknown（未找到 package.json）',
         });
         const state = loadVersionState();
         checks.push({
@@ -82,13 +83,10 @@ register({
     },
 });
 function endpointSource(config) {
-    if (process.env.YOS_ENDPOINT) {
-        return 'YOS_ENDPOINT';
-    }
     if (process.env.YOS_ENV) {
         return 'YOS_ENV';
     }
-    return config?.endpoint || config?.env ? '配置文件' : '内置缺省';
+    return config?.env ? '配置文件' : '内置缺省';
 }
 function skillSyncDetail(meta, state, skillDirs) {
     if (skillDirs.length === 0) {

package/dist/commands/login.js

@@ -1,6 +1,6 @@
 import { register } from '../cli.js';
-import { loadConfig, maskKey, resolveEndpoint, saveConfig } from '../config.js';
-import { envLabel, envNameOf } from '../endpoints.js';
+import { loadConfig, maskKey, resolveEnv, saveConfig } from '../config.js';
+import { endpointOfEnv, envLabel } from '../endpoints.js';
 import { UsageError } from '../errors.js';
 import { formatIdentity, OpenApisClient } from '../openapis-client.js';
 import { print } from '../output.js';
@@ -8,24 +8,20 @@ import { readHiddenLine } from '../prompt.js';
 register({
     name: 'login',
     description: '配置访问令牌与服务环境（校验身份后保存）',
-    usage: 'yos login [--env <name>] [--endpoint <url>] [--key <key>]',
+    usage: 'yos login [--env <name>] [--key <key>]',
     group: '基础',
     options: {
         env: { type: 'string' },
-        endpoint: { type: 'string' },
         key: { type: 'string' },
     },
     paramNotes: [
         ['--env', '服务环境（prod / test / dev；缺省读 YOS_ENV，再缺省生产）'],
-        ['--endpoint', '自定义服务地址（本地联调等；优先于 --env）'],
         ['--key', '访问令牌（40 位小写 hex，缺省读 YOS_API_KEY，否则交互输入）'],
     ],
     async run({ flags }) {
         const config = loadConfig();
-        const endpoint = resolveEndpoint(config, {
-            endpoint: flags.endpoint,
-            env: flags.env,
-        });
+        const env = resolveEnv(config, { env: flags.env });
+        const endpoint = endpointOfEnv(env);
         const key = flags.key
             ?? process.env.YOS_API_KEY
             ?? await readHiddenLine('请粘贴访问令牌（输入不回显，客户端「个人设置-访问令牌」页创建并复制）: ');
@@ -33,8 +29,7 @@ register({
             throw new UsageError('令牌格式不正确（应为 40 位小写 hex）', '请在客户端「个人设置-访问令牌」页创建并复制完整令牌');
         }
         const identity = await new OpenApisClient(`${endpoint}/open-apis`, key).whoami();
-        const envName = envNameOf(endpoint);
-        saveConfig({ ...config, env: envName ?? undefined, endpoint: envName ? undefined : endpoint, apiKey: key });
-        print(`已保存配置：环境=${envLabel(endpoint)}，key=${maskKey(key)}，身份 ${formatIdentity(identity)}`);
+        saveConfig({ ...config, env, apiKey: key });
+        print(`已保存配置：环境=${envLabel(env)}，key=${maskKey(key)}，身份 ${formatIdentity(identity)}`);
     },
 });

package/dist/commands/ping.js

@@ -1,6 +1,6 @@
 import { register } from '../cli.js';
-import { loadConfig, resolveEndpoint, resolveKey } from '../config.js';
-import { envNameOf } from '../endpoints.js';
+import { loadConfig, resolveEnv, resolveKey } from '../config.js';
+import { endpointOfEnv } from '../endpoints.js';
 import { CliError, EXIT } from '../errors.js';
 import { formatIdentity, OpenApisClient } from '../openapis-client.js';
 import { print, printErr, printJson } from '../output.js';
@@ -13,8 +13,8 @@ register({
     paramNotes: [['--json', '结构化输出（ok / env / userCode / userName / error）']],
     async run({ flags }) {
         const config = loadConfig();
-        const endpoint = resolveEndpoint(config);
-        const env = envNameOf(endpoint) ?? endpoint;
+        const env = resolveEnv(config);
+        const endpoint = endpointOfEnv(env);
         try {
             const identity = await new OpenApisClient(`${endpoint}/open-apis`, resolveKey(config)).whoami();
             if (flags.json) {

package/dist/commands/update.js

@@ -1,5 +1,5 @@
 import { register } from '../cli.js';
-import { loadConfig } from '../config.js';
+import { loadConfig, resolveChannel } from '../config.js';
 import { BusinessError } from '../errors.js';
 import { compareVersions, detectGlobalInstall, fetchLatestVersion, PUBLIC_REGISTRY, readPackageMeta, runNpm } from '../npm-meta.js';
 import { print, printJson } from '../output.js';
@@ -7,7 +7,7 @@ import { installSkillsTo } from '../skill-sync.js';
 import { saveVersionState } from '../version-state.js';
 register({
     name: 'update',
-    description: '检查并升级 CLI 到 npmjs 最新版（升级后自动重同步 Skill）',
+    description: '检查并升级 CLI 到对应通道最新版（升级后自动重同步 Skill）',
     usage: 'yos update [--check] [--json]',
     group: '基础',
     risk: 'write',
@@ -21,11 +21,12 @@ register({
         if (!meta) {
             throw new BusinessError('无法确定包名（未找到 package.json）', '请通过 npm 全局安装后重试');
         }
-        const latest = await fetchLatestVersion(meta.name);
+        const channel = resolveChannel(loadConfig()) ?? 'latest';
+        const latest = await fetchLatestVersion(meta.name, channel);
         const outdated = compareVersions(meta.version, latest) < 0;
         if (flags.check) {
             if (flags.json) {
-                printJson({ version: meta.version, latest, outdated });
+                printJson({ version: meta.version, latest, outdated, channel });
             }
             else {
                 print(outdated
@@ -43,15 +44,15 @@ register({
         const shape = await detectGlobalInstall(meta);
         if (!shape.global) {
             print(`当前安装不在 npm 全局目录（${meta.dir}），不代跑升级`);
-            throw new BusinessError('非全局安装，已跳过自动升级', `手动升级：npm install -g ${meta.name}@latest --registry=${PUBLIC_REGISTRY}；或先 npm uninstall -g ${meta.name} 再全局安装`);
+            throw new BusinessError('非全局安装，已跳过自动升级', `手动升级：npm install -g ${meta.name}@${channel} --registry=${PUBLIC_REGISTRY}；或先 npm uninstall -g ${meta.name} 再全局安装`);
         }
-        const install = await runNpm(['install', '-g', `${meta.name}@latest`, `--registry=${PUBLIC_REGISTRY}`]);
+        const install = await runNpm(['install', '-g', `${meta.name}@${channel}`, `--registry=${PUBLIC_REGISTRY}`]);
         if (!install.ok) {
             const output = `${install.stderr}\n${install.stdout}`;
             if (/EACCES|EPERM|permission denied/i.test(output)) {
                 throw new BusinessError('npm 全局目录没有写权限', '把 npm 前缀改到用户目录后重试（npm config set prefix ~/.npm-global 并把其 bin 加入 PATH），不要 sudo npm install -g');
             }
-            throw new BusinessError(`npm install -g ${meta.name}@latest 失败：${firstLine(install.stderr) || firstLine(install.stdout) || '无输出'}`);
+            throw new BusinessError(`npm install -g ${meta.name}@${channel} 失败：${firstLine(install.stderr) || firstLine(install.stdout) || '无输出'}`);
         }
         syncSkills();
         saveVersionState(latest);

package/dist/commands/version.js

@@ -1,25 +1,24 @@
 import { register } from '../cli.js';
-import { loadConfig, resolveEndpoint } from '../config.js';
-import { envNameOf } from '../endpoints.js';
+import { loadConfig, resolveChannel, resolveEnv } from '../config.js';
 import { BusinessError } from '../errors.js';
 import { compareVersions, detectGlobalInstall, fetchLatestVersion, readPackageMeta } from '../npm-meta.js';
 import { print, printJson } from '../output.js';
 register({
     name: 'version',
-    description: '显示 CLI 版本（--check 比对 npmjs 最新版）',
+    description: '显示 CLI 版本（--check 比对对应通道最新版）',
     usage: 'yos version [--json] [--check]',
     group: '基础',
     risk: 'read',
     options: { json: { type: 'boolean' }, check: { type: 'boolean' } },
     paramNotes: [
-        ['--check', '与 npmjs 最新版本比对是否可升级（只读，不写入任何状态）'],
+        ['--check', '与对应通道最新版本比对是否可升级（只读，不写入任何状态）'],
         ['--json', '结构化输出'],
     ],
     async run({ flags }) {
         const meta = readPackageMeta();
         const version = meta?.version ?? 'unknown';
-        const endpoint = resolveEndpoint(loadConfig());
-        const env = envNameOf(endpoint) ?? endpoint;
+        const config = loadConfig();
+        const env = resolveEnv(config);
         if (!flags.check) {
             if (flags.json) {
                 const installedGlobally = meta ? (await detectGlobalInstall(meta)).global : false;
@@ -33,10 +32,11 @@ register({
         if (!meta) {
             throw new BusinessError('无法确定包名（未找到 package.json）', '请通过 npm 全局安装后重试');
         }
-        const latest = await fetchLatestVersion(meta.name);
+        const channel = resolveChannel(config) ?? 'latest';
+        const latest = await fetchLatestVersion(meta.name, channel);
         const outdated = compareVersions(meta.version, latest) < 0;
         if (flags.json) {
-            printJson({ version, latest, outdated, installedGlobally: (await detectGlobalInstall(meta)).global, env });
+            printJson({ version, latest, outdated, installedGlobally: (await detectGlobalInstall(meta)).global, env, channel });
             return;
         }
         print(outdated

package/dist/config.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { DEFAULT_ENDPOINT, DEFAULT_ENV, endpointOfEnv } from './endpoints.js';
+import { channelOfEnv, DEFAULT_ENV, endpointOfEnv } from './endpoints.js';
 import { UsageError } from './errors.js';
 export function configDir() {
     return process.env.YOS_CONFIG_DIR ?? join(homedir(), '.config', 'yos');
@@ -15,7 +15,9 @@ export function loadConfig() {
         return null;
     }
     try {
-        return JSON.parse(readFileSync(path, 'utf8'));
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        delete parsed.endpoint;
+        return parsed;
     }
     catch {
         return null;
@@ -35,29 +37,16 @@ export function resolveKey(config) {
     }
     throw new UsageError('未配置访问令牌', '请执行 `yos login` 或设置环境变量 YOS_API_KEY');
 }
+export function resolveEnv(config, flags) {
+    const env = flags?.env || process.env.YOS_ENV || config?.env || DEFAULT_ENV;
+    endpointOfEnv(env);
+    return env;
+}
 export function resolveEndpoint(config, flags) {
-    if (flags?.endpoint) {
-        return normalizeEndpoint(flags.endpoint);
-    }
-    if (flags?.env) {
-        return endpointOfEnv(flags.env);
-    }
-    if (process.env.YOS_ENDPOINT) {
-        return normalizeEndpoint(process.env.YOS_ENDPOINT);
-    }
-    if (process.env.YOS_ENV) {
-        return endpointOfEnv(process.env.YOS_ENV);
-    }
-    if (config?.endpoint) {
-        return normalizeEndpoint(config.endpoint);
-    }
-    if (config?.env) {
-        return endpointOfEnv(config.env);
-    }
-    return DEFAULT_ENDPOINT;
+    return endpointOfEnv(resolveEnv(config, flags));
 }
-export function normalizeEndpoint(endpoint) {
-    return endpoint.replace(/\/+$/, '');
+export function resolveChannel(config) {
+    return channelOfEnv(resolveEnv(config));
 }
 export function maskKey(key) {
     return key.length <= 12 ? '****' : `${key.slice(0, 8)}****${key.slice(-4)}`;

package/dist/endpoints.js

@@ -5,7 +5,6 @@ export const ENVIRONMENTS = {
     dev: { url: 'http://localhost:8080', label: '开发' },
 };
 export const DEFAULT_ENV = 'prod';
-export const DEFAULT_ENDPOINT = ENVIRONMENTS[DEFAULT_ENV].url;
 export function endpointOfEnv(env) {
     const found = ENVIRONMENTS[env];
     if (!found) {
@@ -13,16 +12,22 @@ export function endpointOfEnv(env) {
     }
     return found.url;
 }
-export function envNameOf(endpoint) {
+const CHANNEL_OF_ENV = {
+    prod: 'latest',
+    test: 'test',
+};
+export function channelOfEnv(env) {
+    return CHANNEL_OF_ENV[env] ?? null;
+}
+export function envLabel(env) {
+    return ENVIRONMENTS[env]?.label ?? env;
+}
+export function labelOfEndpoint(endpoint) {
     const normalized = endpoint.replace(/\/+$/, '');
-    for (const [name, env] of Object.entries(ENVIRONMENTS)) {
+    for (const env of Object.values(ENVIRONMENTS)) {
         if (env.url === normalized) {
-            return name;
+            return env.label;
         }
     }
-    return null;
-}
-export function envLabel(endpoint) {
-    const name = envNameOf(endpoint);
-    return name ? ENVIRONMENTS[name].label : endpoint;
+    return endpoint;
 }

package/dist/errors.js

@@ -4,6 +4,7 @@ export const EXIT = {
     USAGE: 2,
     NETWORK: 3,
     AUTH: 4,
+    UPGRADE: 5,
 };
 export class CliError extends Error {
     exitCode;
@@ -35,3 +36,8 @@ export class AuthError extends CliError {
         super(message, EXIT.AUTH, '请执行 `yos login` 重新配置访问令牌');
     }
 }
+export class UpgradeError extends CliError {
+    constructor(message, hint) {
+        super(message, EXIT.UPGRADE, hint ?? '执行 `yos update` 升级后重试');
+    }
+}

package/dist/npm-meta.js

@@ -1,5 +1,5 @@
 import { execFile } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
@@ -23,6 +23,11 @@ export function readPackageMeta() {
         dir = parent;
     }
 }
+let cliVersionCache;
+export function getCliVersion() {
+    cliVersionCache ??= readPackageMeta()?.version ?? 'unknown';
+    return cliVersionCache;
+}
 export async function runNpm(args) {
     const useCmdWrapper = process.platform === 'win32';
     const command = useCmdWrapper ? (process.env.ComSpec ?? 'cmd.exe') : 'npm';
@@ -45,21 +50,39 @@ export async function runNpm(args) {
         };
     }
 }
-export async function fetchLatestVersion(name) {
-    const result = await runNpm(['view', name, 'version', `--registry=${PUBLIC_REGISTRY}`]);
+export async function fetchLatestVersion(name, channel = 'latest') {
+    const result = await runNpm(['view', `${name}@${channel}`, 'version', `--registry=${PUBLIC_REGISTRY}`]);
     if (!result.ok) {
         const reason = result.stderr.split(/\r?\n/)[0]?.trim() || result.stdout.split(/\r?\n/)[0]?.trim() || '';
-        throw new NetworkError(`无法获知 ${name} 的最新版本：npm view 调用失败`, `${reason ? `${reason}；` : ''}离线或 npm 不可用时，手动升级请执行 npm install -g ${name}@latest`);
+        throw new NetworkError(`无法获知 ${name}（${channel} 通道）的最新版本：npm view 调用失败`, `${reason ? `${reason}；` : ''}离线或 npm 不可用时，手动升级请执行 npm install -g ${name}@${channel}`);
     }
     const latest = result.stdout.split(/\r?\n/)[0]?.trim() ?? '';
     if (!/^\d+\.\d+\.\d+/.test(latest)) {
-        throw new NetworkError(`无法解析 ${name} 的最新版本输出`, `npm view 返回：${result.stdout.slice(0, 120)}`);
+        throw new NetworkError(`无法解析 ${name}（${channel} 通道）的最新版本输出`, `npm view 返回：${result.stdout.slice(0, 120)}`);
     }
     return latest;
 }
 export function compareVersions(a, b) {
-    const left = toSegments(a);
-    const right = toSegments(b);
+    const left = splitVersion(a);
+    const right = splitVersion(b);
+    const coreDiff = compareCoreSegments(left.core, right.core);
+    if (coreDiff !== 0) {
+        return coreDiff;
+    }
+    return comparePreRelease(left.pre, right.pre);
+}
+function splitVersion(version) {
+    const trimmed = version.trim();
+    const dash = trimmed.indexOf('-');
+    const coreText = dash === -1 ? trimmed : trimmed.slice(0, dash);
+    const core = coreText.split('.').map((part) => Number.parseInt(part, 10) || 0);
+    if (dash === -1) {
+        return { core, pre: null };
+    }
+    const pre = trimmed.slice(dash + 1).split('.').filter((part) => part !== '');
+    return { core, pre: pre.length > 0 ? pre : null };
+}
+function compareCoreSegments(left, right) {
     for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
         const diff = (left[i] ?? 0) - (right[i] ?? 0);
         if (diff !== 0) {
@@ -68,20 +91,74 @@ export function compareVersions(a, b) {
     }
     return 0;
 }
+function comparePreRelease(left, right) {
+    if (!left && !right) {
+        return 0;
+    }
+    if (!left) {
+        return 1;
+    }
+    if (!right) {
+        return -1;
+    }
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const l = left[i];
+        const r = right[i];
+        if (l === undefined) {
+            return -1;
+        }
+        if (r === undefined) {
+            return 1;
+        }
+        const diff = comparePreIdentifier(l, r);
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    return 0;
+}
+function comparePreIdentifier(left, right) {
+    const leftNumeric = /^\d+$/.test(left);
+    const rightNumeric = /^\d+$/.test(right);
+    if (leftNumeric && rightNumeric) {
+        const l = Number(left);
+        const r = Number(right);
+        if (l === r) {
+            return 0;
+        }
+        return l < r ? -1 : 1;
+    }
+    if (leftNumeric !== rightNumeric) {
+        return leftNumeric ? -1 : 1;
+    }
+    if (left === right) {
+        return 0;
+    }
+    return left < right ? -1 : 1;
+}
 export async function detectGlobalInstall(meta) {
     const result = await runNpm(['prefix', '-g']);
     if (!result.ok || result.stdout.length === 0) {
         return { global: false, prefix: '' };
     }
     const prefix = stripTrailingSep(resolve(result.stdout));
-    const packageDir = stripTrailingSep(meta.dir);
     return {
-        global: packageDir === prefix || packageDir.startsWith(`${prefix}${sep}`),
+        global: isPackageUnderPrefix(meta.dir, prefix),
         prefix,
     };
 }
-function toSegments(version) {
-    return version.trim().split('-')[0].split('.').map((part) => Number.parseInt(part, 10) || 0);
+export function isPackageUnderPrefix(packageDir, prefix) {
+    const dir = stripTrailingSep(realpathOrSelf(packageDir));
+    const base = stripTrailingSep(realpathOrSelf(prefix));
+    return dir === base || dir.startsWith(`${base}${sep}`);
+}
+function realpathOrSelf(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
 }
 function tryParseJson(path) {
     try {

package/dist/openapis-client.js

@@ -1,8 +1,10 @@
 import { readFile, stat } from 'node:fs/promises';
 import { basename } from 'node:path';
-import { envLabel } from './endpoints.js';
-import { AuthError, BusinessError, NetworkError } from './errors.js';
+import { labelOfEndpoint } from './endpoints.js';
+import { AuthError, BusinessError, NetworkError, UpgradeError } from './errors.js';
+import { getCliVersion } from './npm-meta.js';
 export const MAX_UPLOAD_SIZE_BYTES = 20 * 1024 * 1024;
+export const CLI_VERSION_HEADER = 'X-Yos-Cli-Version';
 export function formatIdentity(identity) {
     return identity.userName ? `${identity.userName}（${identity.userCode}）` : identity.userCode;
 }
@@ -34,6 +36,7 @@ export class OpenApisClient {
                 headers: {
                     'Content-Type': 'application/json',
                     'Authorization': `Bearer ${this.apiKey}`,
+                    [CLI_VERSION_HEADER]: getCliVersion(),
                 },
                 body: JSON.stringify(body ?? {}),
             });
@@ -45,7 +48,7 @@ export class OpenApisClient {
     }
 }
 function envLabelOfBase(base) {
-    return envLabel(base.replace(/\/open-apis$/, ''));
+    return labelOfEndpoint(base.replace(/\/open-apis$/, ''));
 }
 async function parseEnvelope(response) {
     if (response.status === 401) {
@@ -61,7 +64,23 @@ async function parseEnvelope(response) {
         throw new AuthError(`鉴权失败：${reason}`);
     }
     if (response.status === 404) {
-        throw new NetworkError(`HTTP 404：服务端不存在该接口（${response.url}）`, '确认服务端已部署开放接口通道；环境配置有误时用 yos login 重新指定');
+        throw new NetworkError(`HTTP 404：服务端不存在该接口（${response.url}）`, '确认服务端已部署开放接口通道；环境选择有误时用 yos login --env 重新指定');
+    }
+    if (response.status === 426) {
+        let message = 'CLI 版本过低，请升级后重试';
+        let hint;
+        try {
+            const body = await response.json();
+            if (body.error) {
+                message = body.error;
+            }
+            if (body.upgradeCommand) {
+                hint = `执行 \`${body.upgradeCommand}\` 升级后重试`;
+            }
+        }
+        catch {
+        }
+        throw new UpgradeError(message, hint);
     }
     let payload;
     try {
@@ -105,12 +124,12 @@ export async function uploadKnowledgeFile(endpoint, apiKey, filePath, kbCode, pa
     try {
         response = await fetch(`${endpoint}/open-apis/knowledge/file_upload`, {
             method: 'POST',
-            headers: { 'Authorization': `Bearer ${apiKey}` },
+            headers: { 'Authorization': `Bearer ${apiKey}`, [CLI_VERSION_HEADER]: getCliVersion() },
             body: form,
         });
     }
     catch (e) {
-        throw new NetworkError(`无法连接 YOS 服务（${envLabel(endpoint)}），原因：${e.message}`);
+        throw new NetworkError(`无法连接 YOS 服务（${labelOfEndpoint(endpoint)}），原因：${e.message}`);
     }
     return parseEnvelope(response);
 }

package/dist/skill-sync.js

@@ -5,8 +5,8 @@ import { fileURLToPath } from 'node:url';
 import { readPackageMeta } from './npm-meta.js';
 import { updateConfig } from './config.js';
 import { saveVersionState } from './version-state.js';
-export const BUILTIN_SKILLS = ['yos', 'yos-shared', 'yos-kb', 'yos-retrieval', 'yos-transcript', 'yos-support', 'yos-install'];
-const AGENT_SKILL_DIRS = ['.claude/skills', '.workbuddy/skills', '.cursor/skills', '.codex/skills', '.qoder/skills', '.qoder-cn/skills', '.agentskill'];
+export const BUILTIN_SKILLS = ['yos', 'yos-shared', 'yos-knowledge', 'yos-retrieval', 'yos-transcript', 'yos-support', 'yos-install'];
+const AGENT_SKILL_DIRS = ['.claude/skills', '.workbuddy/skills', '.cursor/skills', '.codex/skills', '.qoder/skills', '.qoder-cn/skills', '.agents/skills'];
 export function skillsSourceDir() {
     const here = dirname(fileURLToPath(import.meta.url));
     const distCandidate = join(here, 'skills');

package/dist/skills/yos/SKILL.md

@@ -11,23 +11,23 @@ YOS 是企业 AI 底座：公司知识、会议录音、帮助手册等能力都
 
 ```bash
 yos doctor      # 七项 ✓ 才继续：配置文件 / 服务环境 / 访问令牌 / 服务连通（回显身份）/ Skill 安装 / CLI 版本 / Skill 同步
-yos ping        # 只要探活，退出码即结论（0 通 / 3 网络 / 4 鉴权）
+yos ping        # 只要探活，退出码即结论（0 通 / 3 网络 / 4 鉴权 / 5 版本过低）
 ```
 
 - `command not found: yos` 或 `yos doctor` 报「未找到配置文件」→ 按 `yos-install` skill 引导用户装 CLI 与登录，不要继续猜命令
 - 已装但七项没全 ✓ → 先修环境再执行任务；`yos doctor` 的失败项自带修复提示
-- 查版本用 `yos version`（或 `yos --version`）；升级到 npmjs 最新版用 `yos update`
+- 查版本用 `yos version`（或 `yos --version`）；CLI 会后台自动更新（跟随当前环境通道，无需手动升级），需要立即升级用 `yos update`
 
 ## 1. 意图路由
 
 | 用户在问什么 | 用哪个命令 | 先读哪本 skill |
 |---|---|---|
 | 「公司制度/流程/规范/报销标准/产品资料」等**要一个公司里的答案** | `retrieve search` → `retrieve grep` 定位 → `retrieve read` 读原文 | yos-retrieval |
-| 「有哪些文档 / 共几份 / 文档目录结构」 | `retrieve outline`（检索层）或 `docs tree`（管理层） | yos-retrieval / yos-kb |
+| 「有哪些文档 / 共几份 / 文档目录结构」 | `retrieve outline`（检索层）或 `docs tree`（管理层） | yos-retrieval / yos-knowledge |
 | 找**配套/相关**材料、跨文档关系 | `retrieve neighbors`、`retrieve search --entity/--topic` | yos-retrieval |
-| 浏览/搜索自己的知识库与文档内容 | `kb list` `kb detail` `docs tree` `docs content` | yos-kb |
-| 把知识库里的上传文件取回本地 | `docs download <node_code> --out <路径>` | yos-kb |
-| 上传本地文件或目录、新建文档/文件夹、改名、移动、删除、回收站恢复 | `kb upload` `docs create` `docs mkdir` `docs update` `docs rename` `docs move` `docs delete` `docs restore` | yos-kb |
+| 浏览/搜索自己的知识库与文档内容 | `kb list` `kb detail` `docs tree` `docs content` | yos-knowledge |
+| 把知识库里的上传文件取回本地 | `docs download <node_code> --out <路径>` | yos-knowledge |
+| 上传本地文件或目录、新建文档/文件夹、改名、移动、删除、回收站恢复 | `kb upload` `docs create` `docs mkdir` `docs update` `docs rename` `docs move` `docs delete` `docs restore` | yos-knowledge |
 | 会议录音转写、纪要、逐句发言 | `transcript list` → `transcript detail` | yos-transcript |
 | 「YOS 怎么用」、客户端最新版本、提交问题反馈 | `support manual*` `support upgrade*` `support feedback` | yos-support |
 | 领域命令没覆盖的能力 | `tool list` → `tool schema <name>` → `tool call <name> --params '{...}'` | yos-shared |
@@ -49,9 +49,9 @@ yos ping        # 只要探活，退出码即结论（0 通 / 3 网络 / 4 鉴
 ## 3. 登录与配置
 
 1. 用户在 YOS 客户端「个人设置-访问令牌」页创建并复制令牌（40 位小写 hex）
-2. `yos login` 交互粘贴（不回显）；Agent 代执行时用 `yos login --key <令牌>`（注意令牌会进入 shell 历史，优先让用户自己在终端执行，或用 `YOS_API_KEY`）
+2. `yos login` 交互粘贴（不回显）；Agent 代执行时用 `yos login --key <令牌>`
 3. 配置文件 `~/.config/yos/config.json`（0600）。环境变量**优先于配置文件**：`YOS_CONFIG_DIR`（换配置目录）、`YOS_API_KEY`（换令牌）、`YOS_ENV`（换服务环境，如 test）
-4. 服务环境缺省生产，切换用 `yos login --env test`（临时可用 `YOS_ENV=test`）；`yos doctor` 会显示当前生效环境及其来源。开发者本地调试用 `--env dev`（指向本机 8080 起的服务），其他自定义地址用 `--endpoint <url>` / `YOS_ENDPOINT`，一般无需使用
+4. 服务环境缺省生产，切换用 `yos login --env test`（临时可用 `YOS_ENV=test`）；开发者本地调试用 `--env dev`（指向本机 8080 起的服务）；`yos doctor` 会显示当前生效环境及其来源
 5. 退出码 4 = 令牌无效/已吊销/已过期 → 引导重新 `yos login`，不要反复重试同一命令
 
 ## 4. 常用编排（已实测）
@@ -82,5 +82,5 @@ yos support upgrade --platform MAC_ARM64                    # 客户端最新版
 
 - 默认输出人类可读文本；需要字段时**加 `--json` 再解析**，不要正则刮文本
 - 分页壳不统一：`kb list` / `support upgrade-log` 为 `records` / `total` / `page` / `size`；`transcript list` 为 `list` / `current` / `size` / `pages` / `total`（转写域解析细则见 yos-transcript）
-- 命令报错时先看退出码：`2` 用法错误（CLI 本地拦截，未发请求，按 `提示:` 改参数）、`1` 业务失败（服务端结论，文案里带具体编码，可直接引给用户）、`3` 网络、`4` 鉴权
+- 命令报错时先看退出码：`2` 用法错误（CLI 本地拦截，未发请求，按 `提示:` 改参数）、`1` 业务失败（服务端结论，文案里带具体编码，可直接引给用户）、`3` 网络、`4` 鉴权、`5` 版本过低（先 `yos update` 升级再原样重试）
 - 领域命令找不到对应能力时，`yos tool list` 看全量工具，`yos tool schema <name> --json` 拿完整参数说明（不带 `--json` 会截断描述），再 `yos tool call`

package/dist/skills/yos-install/SKILL.md

@@ -12,7 +12,7 @@ description: 引导用户在本机安装并配置 YOS CLI（环境检查 → npm
 ## 0. 引导纪律
 
 - 一次只执行一步，把该步命令的**输出原文**给用户，再决定下一步；不要连跑多条命令后统一汇报
-- 需要访问令牌时：优先让用户自己在终端输入（`yos login` 的输入不回显）；确需 Agent 代跑时用 `--key`/环境变量，并提醒用户该命令会进入 shell 历史
+- 需要访问令牌时：优先让用户自己在终端输入（`yos login` 的输入不回显）；确需 Agent 代跑时用 `--key`/环境变量
 - **凭据零外泄**：访问令牌不写进代码仓库、日志、聊天正文或文档；引用时一律掩码（形如 `xxxxxxxx****xxxx`，即原令牌前 8 位 + `****` + 后 4 位）
 - 不擅自改用户的全局配置：写 `~/.npmrc`、改 `npm prefix`、删 skill 目录这类动作先取得用户同意
 - 全程不需要 `sudo`。权限报错按第 7 节处置，不要 `sudo npm install -g`（会把 root 拥有的文件混进全局目录，后续更难维护）
@@ -76,7 +76,7 @@ yos login --key '<40 位令牌>'
 yos skill install
 ```
 
-- 自动探测下列目录，**只对已存在的目录写入**（一台机器可能同时命中多个）：`~/.claude/skills`、`~/.workbuddy/skills`、`~/.cursor/skills`、`~/.codex/skills`、`~/.qoder/skills`、`~/.qoder-cn/skills`、`~/.agentskill`
+- 自动探测下列目录，**只对已存在的目录写入**（一台机器可能同时命中多个）：`~/.claude/skills`、`~/.workbuddy/skills`、`~/.cursor/skills`、`~/.codex/skills`、`~/.qoder/skills`、`~/.qoder-cn/skills`、`~/.agents/skills`
 - 成功输出（数字随内置 Skill 数量变化）：
 
 ```
@@ -124,13 +124,15 @@ yos kb list --json    # 端到端实跑一条只读命令收尾
 
 ## 6. 升级与卸载
 
+CLI 平时无需手动升级：每次命令执行后会在后台自动检查对应通道并静默更新（升级后自动重同步 Skill），下次运行生效。升级通道跟随服务环境：生产跟 latest 正式版，测试环境（`login --env test`）自动跟 test 通道，dev 不自动更新。
+
 ```bash
-yos update                            # 推荐：升级到 npmjs 最新版并自动重同步 Skill
+yos update                            # 需要立即升级时执行（到当前通道最新版并自动重同步 Skill）
 yos update --check                    # 只查是否有新版本，不安装
-npm install -g @yosai/cli@latest        # 等价手动写法；走这条路后需再跑 yos skill install 刷新 Skill
+npm install -g @yosai/cli@latest        # 等价手动写法（正式版）；走这条路后需再跑 yos skill install 刷新 Skill
 ```
 
-（0.2.0 之前的版本没有 `yos update`，直接用 `npm install -g @yosai/cli@latest` 升级）
+（0.2.0 之前的版本没有 `yos update`，直接用 `npm install -g @yosai/cli@latest` 升级；如需关闭后台自动更新，设置环境变量 `YOS_NO_AUTO_UPDATE=1`）
 
 卸载（破坏性，逐项取得用户确认后再动手）：
 
@@ -156,7 +158,7 @@ ls ~/.claude/skills | grep -E '^yos'                   # 先看要删哪些，
 
 ## 8. 装好之后
 
-- 让用户从 `yos` skill（总入口）开始使用；命令细节看各领域 skill：`yos-kb`（知识库管理）、`yos-retrieval`（检索与引用）、`yos-transcript`（录音转写）、`yos-support`（帮助/版本/反馈）、`yos-shared`（共享约定）
+- 让用户从 `yos` skill（总入口）开始使用；命令细节看各领域 skill：`yos-knowledge`（知识库管理）、`yos-retrieval`（检索与引用）、`yos-transcript`（录音转写）、`yos-support`（帮助/版本/反馈）、`yos-shared`（共享约定）
 - 本机可用能力：28 个领域命令（kb 4 / docs 11 / retrieve 5 / support 6 / transcript 2）+ `yos tool` 兜底通道，覆盖知识库检索与管理、文档上传下载、会议转写查询、帮助手册、客户端版本与反馈；新建与删除知识库不在 CLI 内，需到 YOS 客户端手动操作
 - 边界（别过度承诺）：不能实时控制转写、不能申请/变更权限、反馈不带附件、只能看到当前令牌归属用户可见的数据
 - 排查建议：任何失败先跑 `yos doctor`；退出码 `4` 一律重新登录，`3` 先看「服务环境」项与网络

package/dist/skills/{yos-kb → yos-knowledge}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: yos-kb
+name: yos-knowledge
 description: YOS 知识库与文档管理（kb list/detail/update/upload + docs tree/content/download/count/mkdir/create/update/rename/move/delete/restore）。用户要查资料在哪、上传或整理知识库文档、下载原文件、改名字/移动/删除/恢复时使用；含每条命令的参数、真实输出与报错修法
 ---
 

package/dist/skills/yos-shared/SKILL.md

@@ -35,9 +35,9 @@ yos doctor      # 七项全 ✓ 才能继续；任一项 ✗ 按下方「未登
 
 配置细节（排障时才需要）：
 
-- 配置文件 `~/.config/yos/config.json`（目录 0700、文件 0600），字段 `{env, apiKey, installedSkillDirs}`；本地联调等自定义地址场景存 `endpoint` 字段替代 `env`
+- 配置文件 `~/.config/yos/config.json`（目录 0700、文件 0600），字段 `{env, apiKey, installedSkillDirs}`
 - 环境变量优先级：`YOS_API_KEY` > 配置文件 `apiKey`；`YOS_ENV` > 配置文件 `env`；`YOS_CONFIG_DIR` 覆盖配置目录（测试隔离用）
-- 服务环境缺省生产，切换用 `yos login --env test`（临时用 `YOS_ENV=test`）；开发者本地调试用 `--env dev`（指向本机 8080 起的服务）；其他自定义地址用 `--endpoint <url>` / `YOS_ENDPOINT`，一般无需使用；`yos doctor` 的「服务环境」项显示当前环境与来源
+- 服务环境缺省生产，切换用 `yos login --env test`（临时用 `YOS_ENV=test`）；开发者本地调试用 `--env dev`（指向本机 8080 起的服务）；`yos doctor` 的「服务环境」项显示当前环境与来源
 - 令牌格式先本地校验：`yos login` 粘贴了非 40 位小写 hex 会直接报 `错误: 令牌格式不正确（应为 40 位小写 hex）`，不会落盘
 
 **安全**：绝不把令牌写进命令历史可见的日志、代码仓库或对用户的回复里；`--key` 传令牌仅用于无交互场景，回复中一律用掩码形式（`xxxxxxxx****xxxx`）。
@@ -88,6 +88,7 @@ CLI 对两套编码原样透出不做映射。遇到 cortex 侧编码时：可
 | 2 | 参数/用法错误（CLI 本地拦截，未发请求） | `错误: 缺少 --kind`<br>`提示: 用法: yos retrieve neighbors <target> --kind <值> ...` | 照 `提示:` 里的用法改写 |
 | 3 | 网络错误/服务不可达 | `错误: 无法连接 YOS 服务（生产），原因：fetch failed` | 确认服务环境与网络连通，`yos ping` 复测 |
 | 4 | 鉴权失败 | `错误: 鉴权失败...`<br>`提示: 请执行 \`yos login\` 重新配置访问令牌` | 令牌无效/吊销/过期 → 让用户重新创建后 `yos login` |
+| 5 | 版本过低（服务端最低版本门槛拒绝，请求未生效） | `错误: CLI 版本过低（当前 0.2.0，最低要求 0.3.0），请升级后重试`<br>`提示: 执行 \`yos update\` 升级后重试` | 先执行 `yos update` 升级再原样重试；不要改参数反复试探 |
 
 `1` 与 `2` 的关键差别：**2 根本没发请求**，改法一定写在 `提示:` 里；**1 是服务端结论**，文案里带具体编码，直接引用给用户。
 

package/dist/update-check-worker.js

@@ -0,0 +1,98 @@
+import { mkdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { configDir, loadConfig, resolveChannel } from './config.js';
+import { compareVersions, detectGlobalInstall, fetchLatestVersion, PUBLIC_REGISTRY, readPackageMeta, runNpm, } from './npm-meta.js';
+import { installSkillsTo } from './skill-sync.js';
+import { saveCheckState } from './update-notice.js';
+import { saveVersionState } from './version-state.js';
+const LOCK_STALE_MS = 10 * 60 * 1000;
+export async function runUpdateCheck() {
+    const meta = readPackageMeta();
+    if (!meta) {
+        return;
+    }
+    const channel = resolveChannel(loadConfig());
+    if (channel === null) {
+        return;
+    }
+    try {
+        const latest = await fetchLatestVersion(meta.name, channel);
+        if (compareVersions(meta.version, latest) < 0 && !autoUpdateDisabled() && acquireUpdateLock()) {
+            try {
+                await silentUpdate(meta, latest, channel);
+            }
+            finally {
+                releaseUpdateLock();
+            }
+        }
+        saveCheckState(latest, channel);
+    }
+    catch {
+    }
+}
+async function silentUpdate(meta, latest, channel) {
+    const shape = await detectGlobalInstall(meta);
+    if (!shape.global) {
+        return;
+    }
+    const install = await runNpm(['install', '-g', `${meta.name}@${channel}`, `--registry=${PUBLIC_REGISTRY}`]);
+    if (!install.ok) {
+        return;
+    }
+    const dirs = loadConfig()?.installedSkillDirs ?? [];
+    if (dirs.length > 0) {
+        installSkillsTo(dirs);
+    }
+    saveVersionState(latest);
+}
+function autoUpdateDisabled() {
+    return Boolean(process.env.YOS_NO_AUTO_UPDATE);
+}
+function updateLockPath() {
+    return join(configDir(), 'update.lock');
+}
+function acquireUpdateLock() {
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    const path = updateLockPath();
+    try {
+        writeFileSync(path, `${Date.now()}`, { flag: 'wx', mode: 0o600 });
+        return true;
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST') {
+            return false;
+        }
+    }
+    try {
+        if (Date.now() - statSync(path).mtimeMs > LOCK_STALE_MS) {
+            rmSync(path, { force: true });
+            writeFileSync(path, `${Date.now()}`, { flag: 'wx', mode: 0o600 });
+            return true;
+        }
+    }
+    catch {
+    }
+    return false;
+}
+function releaseUpdateLock() {
+    try {
+        rmSync(updateLockPath(), { force: true });
+    }
+    catch {
+    }
+}
+export function isDirectRun(argv1, moduleUrl) {
+    if (!argv1) {
+        return false;
+    }
+    try {
+        return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectRun(process.argv[1], import.meta.url)) {
+    await runUpdateCheck();
+}

package/dist/update-notice.js

@@ -0,0 +1,88 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { configDir, loadConfig, resolveChannel } from './config.js';
+import { compareVersions, getCliVersion } from './npm-meta.js';
+import { printErr } from './output.js';
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const SKIP_COMMANDS = new Set(['update', 'version']);
+function checkStatePath() {
+    return join(configDir(), 'update-check.json');
+}
+export function loadCheckState(channel) {
+    const path = checkStatePath();
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (typeof parsed.latest !== 'string' || parsed.latest === '' || parsed.channel !== channel) {
+            return null;
+        }
+        return {
+            latest: parsed.latest,
+            channel: parsed.channel,
+            checkedAt: typeof parsed.checkedAt === 'string' ? parsed.checkedAt : '',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCheckState(latest, channel) {
+    mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    const state = { latest, channel, checkedAt: new Date().toISOString() };
+    writeFileSync(checkStatePath(), `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+}
+export function evaluateNotice(input) {
+    if (input.commandName && SKIP_COMMANDS.has(input.commandName)) {
+        return 'skip';
+    }
+    if (!input.state || !isFresh(input.state, input.now)) {
+        return 'spawn';
+    }
+    if (compareVersions(input.currentVersion, input.state.latest) >= 0) {
+        return 'skip';
+    }
+    return input.tty && !input.argv.includes('--json') ? 'notify' : 'skip';
+}
+export function handleUpdateNotice(argv, commandName) {
+    try {
+        const channel = resolveChannel(loadConfig());
+        if (channel === null) {
+            return;
+        }
+        const currentVersion = getCliVersion();
+        const state = loadCheckState(channel);
+        const decision = evaluateNotice({
+            argv,
+            commandName,
+            state,
+            tty: Boolean(process.stderr.isTTY),
+            now: new Date(),
+            currentVersion,
+        });
+        if (decision === 'spawn') {
+            spawnUpdateCheckWorker();
+            return;
+        }
+        if (decision === 'notify' && state) {
+            printErr(`提示: 有新版本 ${state.latest}（当前 ${currentVersion}），执行 yos update 升级`);
+        }
+    }
+    catch {
+    }
+}
+function isFresh(state, now) {
+    const checkedAt = Date.parse(state.checkedAt);
+    return !Number.isNaN(checkedAt) && now.getTime() - checkedAt < CACHE_TTL_MS;
+}
+function spawnUpdateCheckWorker() {
+    try {
+        const workerPath = fileURLToPath(new URL('./update-check-worker.js', import.meta.url));
+        spawn(process.execPath, [workerPath], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+    }
+    catch {
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yosai/cli",
-  "version": "0.2.1-test.3",
+  "version": "0.2.1-test.7",
   "description": "YOS 能力的 Agent 执行入口：工具调用、知识库管理与文件上传",
   "type": "module",
   "bin": {
@@ -20,7 +20,9 @@
     "build": "tsc && node scripts/copy-assets.mjs && chmod +x dist/index.js",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "release": "node scripts/release.mjs"
+    "release": "node scripts/release.mjs",
+    "publish:test": "node scripts/release.mjs --publish --tag test --bump",
+    "publish:latest": "node scripts/release.mjs --publish --tag latest --bump"
   },
   "license": "Apache-2.0",
   "private": false,