@yosai/cli 0.2.1-test.0 → 0.2.1-test.10

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,16 +36,16 @@ 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] [--version <x.y.z>]` | 升级到对应通道最新版并自动重同步 Skill（命令执行前检测到新版本会有升级提示，照提示执行即可）；`--version` 安装指定版本（可升可降，用于回退或锁定版本） |
 | `yos skill install [--target <dir>]` | 安装内置 Skill |
 
-所有命令支持 `--json` 输出与统一退出码（0 成功 / 1 业务失败 / 2 参数错误 / 3 网络 / 4 鉴权）。
+所有命令支持 `--json` 输出与统一退出码（0 成功 / 1 业务失败 / 2 参数错误 / 3 网络 / 4 鉴权 / 5 版本过低）。
 
 ## 给 Agent 使用
 
 ```bash
-yos skill install      # 安装 7 个内置 Skill（总入口 + 领域 + 安装引导）到 Claude Code / Cursor / Codex / Qoder / WorkBuddy 等技能目录
+yos skill install      # 安装 9 个内置 Skill（总入口 + 领域 + 安装引导）到 Claude Code / Cursor / Codex / Qoder / WorkBuddy 等技能目录
 ```
 
 安装后重启 Agent 工具，即可用自然语言驱动（如「把这份报告上传到知识库」）。`yos` 为能力总入口（何时使用 / 能力地图 / 命令使用方式），Agent 据此路由到各领域细则；`yos-shared` 收录跨领域约定（输出解析、退出码契约、仍需自行校验内容的场景、安全纪律）；`yos-install` 是自包含的安装配置引导，可单独下载到发布仓库供用户引导装机。
@@ -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）
+- 版本检查：命令执行前会检查对应通道最新版（后台进程查询、结果缓存 10 分钟），落后时以 stderr 提示「请先执行 yos update 升级再继续任务」；升级通道自动跟随服务环境（测试环境跟 test 通道）。CLI 不静默安装，升级由用户或 Agent 按提示显式执行
+- 服务环境（测试/开发用）：`yos login --env test` 切到测试环境，`--env dev` 指向本机开发服务（http://localhost:8080）
 
 ## 故障排查
 
 - 退出码 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,12 +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_ENDPOINT    BFF 服务地址',
+        '  YOS_ENV         服务环境（prod / test / dev；缺省生产）',
         '  YOS_CONFIG_DIR  配置目录（缺省 ~/.config/yos）',
         '',
         '示例:',
@@ -170,6 +171,7 @@ export async function dispatch(argv) {
         print(renderCommandHelp(command));
         return EXIT.OK;
     }
+    handleUpdateNotice(command.name);
     try {
         const exitCode = await command.run(parseCommandArgs(command, rest));
         return typeof exitCode === 'number' ? exitCode : EXIT.OK;

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import { register } from '../cli.js';
-import { loadConfig, maskKey, resolveEndpoint, resolveKey } from '../config.js';
+import { loadConfig, maskKey, resolveEnv, resolveKey } from '../config.js';
+import { DEFAULT_ENV, endpointOfEnv, envLabel } from '../endpoints.js';
 import { CliError, EXIT } from '../errors.js';
 import { formatIdentity, OpenApisClient } from '../openapis-client.js';
 import { print, printJson } from '../output.js';
@@ -15,16 +16,20 @@ register({
     async run({ flags }) {
         const checks = [];
         const config = loadConfig();
+        const env = resolveEnv(config);
+        const endpoint = endpointOfEnv(env);
         checks.push({
             name: '配置文件',
             ok: config !== null,
             detail: config ? '已找到' : '未找到，请执行 yos login',
         });
-        checks.push({
-            name: '服务端点',
-            ok: true,
-            detail: `${resolveEndpoint(config)}（来自 ${endpointSource(config)}）`,
-        });
+        if (env !== DEFAULT_ENV) {
+            checks.push({
+                name: '服务环境',
+                ok: true,
+                detail: `${envLabel(env)}（来自 ${endpointSource(config)}）`,
+            });
+        }
         let key = null;
         try {
             key = resolveKey(config);
@@ -39,7 +44,7 @@ register({
         }
         else {
             try {
-                const identity = await new OpenApisClient(`${resolveEndpoint(config)}/open-apis`, key).whoami();
+                const identity = await new OpenApisClient(`${endpoint}/open-apis`, key).whoami();
                 checks.push({ name: '服务连通', ok: true, detail: `身份 ${formatIdentity(identity)}` });
             }
             catch (e) {
@@ -55,10 +60,11 @@ register({
             detail: skillDirs.length > 0 ? skillDirs.join(', ') : '尚未安装，执行 yos skill install',
         });
         const meta = readPackageMeta();
+        const envNote = env === DEFAULT_ENV ? '' : `（环境=${envLabel(env)}）`;
         checks.push({
             name: 'CLI 版本',
             ok: meta !== null,
-            detail: meta ? `${meta.version}（endpoint=${resolveEndpoint(config)}）` : 'unknown（未找到 package.json）',
+            detail: meta ? `${meta.version}${envNote}` : 'unknown（未找到 package.json）',
         });
         const state = loadVersionState();
         checks.push({
@@ -80,10 +86,10 @@ register({
     },
 });
 function endpointSource(config) {
-    if (process.env.YOS_ENDPOINT) {
-        return 'YOS_ENDPOINT';
+    if (process.env.YOS_ENV) {
+        return 'YOS_ENV';
     }
-    return config?.endpoint ? '配置文件' : '内置缺省';
+    return config?.env ? '配置文件' : '内置缺省';
 }
 function skillSyncDetail(meta, state, skillDirs) {
     if (skillDirs.length === 0) {

package/dist/commands/login.js

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

package/dist/commands/ping.js

@@ -1,5 +1,6 @@
 import { register } from '../cli.js';
-import { loadConfig, resolveEndpoint, resolveKey } from '../config.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';
@@ -9,14 +10,15 @@ register({
     usage: 'yos ping [--json]',
     group: '基础',
     options: { json: { type: 'boolean' } },
-    paramNotes: [['--json', '结构化输出（ok / endpoint / userCode / userName / error）']],
+    paramNotes: [['--json', '结构化输出（ok / env / userCode / userName / error）']],
     async run({ flags }) {
         const config = loadConfig();
-        const endpoint = resolveEndpoint(config);
+        const env = resolveEnv(config);
+        const endpoint = endpointOfEnv(env);
         try {
             const identity = await new OpenApisClient(`${endpoint}/open-apis`, resolveKey(config)).whoami();
             if (flags.json) {
-                printJson({ ok: true, endpoint, userCode: identity.userCode, userName: identity.userName });
+                printJson({ ok: true, env, userCode: identity.userCode, userName: identity.userName });
             }
             else {
                 print(`✓ 连接成功，令牌有效：身份 ${formatIdentity(identity)}`);
@@ -26,7 +28,7 @@ register({
         catch (e) {
             const failure = e instanceof CliError ? e : new CliError(String(e), EXIT.BUSINESS);
             if (flags.json) {
-                printJson({ ok: false, endpoint, error: failure.message });
+                printJson({ ok: false, env, error: failure.message });
             }
             else {
                 printErr(`错误: ${failure.message}`);

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,25 +7,34 @@ import { installSkillsTo } from '../skill-sync.js';
 import { saveVersionState } from '../version-state.js';
 register({
     name: 'update',
-    description: '检查并升级 CLI 到 npmjs 最新版（升级后自动重同步 Skill）',
-    usage: 'yos update [--check] [--json]',
+    description: '检查并升级 CLI 到对应通道最新版（升级后自动重同步 Skill）',
+    usage: 'yos update [--check] [--json] [--version <x.y.z>]',
     group: '基础',
     risk: 'write',
-    options: { check: { type: 'boolean' }, json: { type: 'boolean' } },
+    options: { check: { type: 'boolean' }, json: { type: 'boolean' }, version: { type: 'string' } },
     paramNotes: [
         ['--check', '只检查是否有新版本，不安装、不写入状态'],
         ['--json', '结构化输出（仅 --check 生效）'],
+        ['--version <x.y.z>', '安装指定版本（可升可降，用于回退或锁定版本）；与 --check 互斥'],
     ],
     async run({ flags }) {
         const meta = readPackageMeta();
         if (!meta) {
             throw new BusinessError('无法确定包名（未找到 package.json）', '请通过 npm 全局安装后重试');
         }
-        const latest = await fetchLatestVersion(meta.name);
+        if (flags.check && typeof flags.version === 'string') {
+            throw new BusinessError('--check 与 --version 不能同时使用', '查看最新版用 yos update --check；安装指定版本用 yos update --version <x.y.z>');
+        }
+        if (typeof flags.version === 'string') {
+            await installVersion(meta, flags.version);
+            return;
+        }
+        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
@@ -40,25 +49,49 @@ register({
             print(`已是最新（${meta.version}）`);
             return;
         }
-        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} 再全局安装`);
-        }
-        const install = await runNpm(['install', '-g', `${meta.name}@latest`, `--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) || '无输出'}`);
-        }
+        await installGlobally(meta, `${meta.name}@${channel}`);
         syncSkills();
         saveVersionState(latest);
         print(`已升级 ${meta.version} → ${latest}`);
         print('提示：重启 Agent 工具以加载刷新后的 Skill');
     },
 });
+const INSTALLABLE_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+async function installVersion(meta, version) {
+    if (!INSTALLABLE_VERSION.test(version)) {
+        throw new BusinessError(`版本格式非法：${version}`, '示例：0.2.0 或 0.2.1-test.9；安装通道最新版请直接执行 yos update');
+    }
+    if (compareVersions(version, meta.version) === 0) {
+        syncSkills();
+        saveVersionState(meta.version);
+        print(`已是指定版本（${version}）`);
+        return;
+    }
+    const probe = await runNpm(['view', `${meta.name}@${version}`, 'version', `--registry=${PUBLIC_REGISTRY}`]);
+    if (!probe.ok || probe.stdout.trim() === '') {
+        throw new BusinessError(`npm registry 上不存在版本 ${version}`, `查看可用版本：npm view ${meta.name} versions --registry=${PUBLIC_REGISTRY}`);
+    }
+    await installGlobally(meta, `${meta.name}@${version}`);
+    syncSkills();
+    saveVersionState(version);
+    print(`${compareVersions(version, meta.version) > 0 ? '已升级' : '已回退'} ${meta.version} → ${version}`);
+    print('提示：重启 Agent 工具以加载刷新后的 Skill');
+}
+async function installGlobally(meta, spec) {
+    const shape = await detectGlobalInstall(meta);
+    if (!shape.global) {
+        print(`当前安装不在 npm 全局目录（${meta.dir}），不代跑安装`);
+        throw new BusinessError('非全局安装，已跳过自动安装', `手动安装：npm install -g ${spec} --registry=${PUBLIC_REGISTRY}；或先 npm uninstall -g ${meta.name} 再全局安装`);
+    }
+    const install = await runNpm(['install', '-g', spec, `--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 ${spec} 失败：${firstLine(install.stderr) || firstLine(install.stdout) || '无输出'}`);
+    }
+}
 function syncSkills() {
     const dirs = loadConfig()?.installedSkillDirs ?? [];
     if (dirs.length === 0) {

package/dist/commands/version.js

@@ -1,27 +1,28 @@
 import { register } from '../cli.js';
-import { loadConfig, resolveEndpoint } from '../config.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 config = loadConfig();
+        const env = resolveEnv(config);
         if (!flags.check) {
             if (flags.json) {
                 const installedGlobally = meta ? (await detectGlobalInstall(meta)).global : false;
-                printJson({ version, installedGlobally, endpoint });
+                printJson({ version, installedGlobally, env });
             }
             else {
                 print(`yos CLI ${version}`);
@@ -31,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, endpoint });
+            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 } 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,21 +37,23 @@ export function resolveKey(config) {
     }
     throw new UsageError('未配置访问令牌', '请执行 `yos login` 或设置环境变量 YOS_API_KEY');
 }
-export function resolveEndpoint(config) {
-    const fromEnv = process.env.YOS_ENDPOINT;
-    if (fromEnv) {
-        return normalizeEndpoint(fromEnv);
-    }
-    return normalizeEndpoint(config?.endpoint ?? DEFAULT_ENDPOINT);
+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) {
+    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)}`;
 }
 export function updateConfig(patch) {
-    const merged = { endpoint: DEFAULT_ENDPOINT, ...loadConfig(), ...patch };
+    const existing = loadConfig();
+    const merged = existing ? { ...existing, ...patch } : { env: DEFAULT_ENV, ...patch };
     saveConfig(merged);
     return merged;
 }

package/dist/domain-commands.js

@@ -24,19 +24,28 @@ export const DOMAIN_COMMANDS = [
             },
             { flag: 'keyword', param: 'keyword', kind: 'string', description: '名称关键词（仅匹配库名，不搜正文）' },
             { flag: 'page', param: 'page', kind: 'number', description: '页码（缺省 1）', min: 1 },
-            { flag: 'size', param: 'size', kind: 'number', description: '每页条数（缺省 10，上限 50）', min: 1, max: 50 },
+            { flag: 'size', param: 'size', kind: 'number', description: '每页条数（缺省 50）', min: 1, max: 50, defaultValue: 50 },
         ],
         render: (result) => {
             const data = parseToolJson(result);
             const records = data.records ?? [];
+            const total = data.total ?? records.length;
+            const page = data.page ?? 1;
             if (records.length === 0) {
-                print('（无知识库）');
+                print(total > 0 ? `（本页无数据：共 ${total} 条，--page ${page} 超出范围）` : '（无知识库）');
                 return;
             }
             print(renderRows(records.map((r) => [
                 String(r.kbCode ?? r.kb_code ?? ''),
                 String(r.kbName ?? r.kb_name ?? r.name ?? ''),
             ])));
+            const shown = (page - 1) * (data.size ?? records.length) + records.length;
+            if (shown < total) {
+                print(`（共 ${total} 条，还有 ${total - shown} 条；翻页加 --page ${page + 1}）`);
+            }
+            else if (page > 1) {
+                print(`（共 ${total} 条，已到末页）`);
+            }
         },
     },
     {
@@ -116,7 +125,7 @@ export const DOMAIN_COMMANDS = [
             {
                 flag: 'type', param: 'doc_type', kind: 'string',
                 description: '文档类型（缺省 md）：md=Markdown 文本 / cloud=云文档 / sheet=表格；'
-                    + 'cloud 与 sheet 的正文须为对应草稿 JSON，一般场景一律用 md',
+                    + 'cloud 与 sheet 的正文为对应草稿 JSON（结构分别见 yos-doc / yos-sheet 技能），一般场景一律用 md',
                 values: ['md', 'cloud', 'sheet'],
             },
             { flag: 'content', param: 'content', kind: 'string', description: '正文文本（与 --file 二选一）' },
@@ -154,7 +163,7 @@ export const DOMAIN_COMMANDS = [
         flags: [
             { flag: 'title', param: 'title', kind: 'string', description: '新标题' },
             { flag: 'content', param: 'content', kind: 'string', description: '新正文，整体覆盖原正文（与 --file 二选一）' },
-            { flag: 'file', param: 'content', kind: 'string', description: '新正文文件路径，整体覆盖原正文（与 --content 二选一）' },
+            { flag: 'file', param: 'content', kind: 'string', description: '新正文文件路径，整体覆盖原正文（与 --content 二选一）；云文档/云表格节点传对应草稿 JSON（结构分别见 yos-doc / yos-sheet 技能）' },
             { flag: 'description', param: 'description', kind: 'string', description: '新简介（≤100 字）' },
         ],
         buildArgs: (context) => {

package/dist/domain-executor.js

@@ -35,6 +35,9 @@ function buildDeclaredArgs(spec, context) {
             if (flag.required) {
                 throw new UsageError(`缺少 --${flag.flag}`, `用法: ${buildUsageForSpec(spec)}`);
             }
+            if (flag.defaultValue !== undefined) {
+                args[flag.param] = flag.defaultValue;
+            }
             continue;
         }
         const values = Array.isArray(raw) ? raw : [raw];

package/dist/endpoints.js

@@ -1 +1,33 @@
-export const DEFAULT_ENDPOINT = 'https://yos-bff.linkduoo.com';
+import { UsageError } from './errors.js';
+export const ENVIRONMENTS = {
+    prod: { url: 'https://yos-bff.linkduoo.com', label: '生产' },
+    test: { url: 'https://yos-bff-test.linkduoo.com', label: '测试' },
+    dev: { url: 'http://localhost:8080', label: '开发' },
+};
+export const DEFAULT_ENV = 'prod';
+export function endpointOfEnv(env) {
+    const found = ENVIRONMENTS[env];
+    if (!found) {
+        throw new UsageError(`无法识别的环境：${env}`, `可用环境：${Object.keys(ENVIRONMENTS).join(' / ')}`);
+    }
+    return found.url;
+}
+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 envNoteOfEndpoint(endpoint) {
+    const normalized = endpoint.replace(/\/+$/, '');
+    for (const [name, env] of Object.entries(ENVIRONMENTS)) {
+        if (env.url === normalized) {
+            return name === DEFAULT_ENV ? '' : `（${env.label}）`;
+        }
+    }
+    return `（${normalized}）`;
+}

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` 升级后重试');
+    }
+}