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

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

@@ -1,13 +1,13 @@
 ---
 name: yos-install
-description: 引导用户在本机安装并配置 YOS CLI（环境检查 → npm 全局安装 → 登录访问令牌 → 安装内置 Skill → doctor 验证）。当 yos 命令不存在、yos doctor 未通过、用户说"帮我装 YOS CLI / 配置令牌 / 装不上"时使用。本文件自包含，可单独放到发布仓库供用户下载后完成引导
+description: 引导用户在本机安装并配置 YOS CLI（环境检查 → npm 全局安装 → 登录访问令牌 → 安装内置 Skill → doctor 验证）。用户提到 yos/YOS 且需要安装或修复 CLI 环境（yos 命令不存在、yos doctor 未通过、要装 CLI / 配置令牌 / 装不上）时使用。本文件自包含，可单独放到发布仓库供用户下载后完成引导
 ---
 
 # YOS CLI 安装与配置引导
 
 目标：让用户本机具备可用的 `yos` 命令，并把 YOS 内置 Skill 装进他正在使用的 AI 工具目录。全程 5 步，用户只需配合一处（在 YOS 客户端取访问令牌）。
 
-本文件**自包含**：不依赖其它 YOS skill 就能完成安装；安装成功后再由 `yos skill install` 把领域能力（知识库、检索、转写、帮助）落到本机。
+本文件**自包含**：不依赖其它 YOS skill 就能完成安装；安装成功后再由 `yos skill install` 把领域能力（知识库、检索、云文档编写、转写、帮助）落到本机。
 
 ## 0. 引导纪律
 
@@ -60,13 +60,13 @@ yos login --key '<40 位令牌>'
 3. 成功输出（原样回给用户即可，`key` 已是掩码）：
 
 ```
-已保存配置：环境=生产，key=xxxxxxxx****xxxx，身份 张三（U00000001）
+已保存配置：key=xxxxxxxx****xxxx，身份 张三（U00000001）
 ```
 
 关键语义：
 
 - `login` 会**先调服务端校验身份再落盘**，校验失败不写配置 → 报网络或令牌错时无需清理"半成品"配置，改对参数重跑即可
-- 服务环境缺省为生产。切换环境用 `yos login --env test`（临时切换可先 `export YOS_ENV=test`）；地址由 CLI 内置映射，无需关心。不指定时沿用已保存的环境
+- 切换服务环境（测试/开发装机用）：`yos login --env test`（临时切换可先 `export YOS_ENV=test`），本地服务 `--env dev`
 - 配置文件 `~/.config/yos/config.json`（目录 0700、文件 0600）
 - CI/容器可完全跳过 `login`：`export YOS_API_KEY=<令牌>`、`export YOS_ENV=test` 指定服务环境（两者都优先于配置文件）；`YOS_CONFIG_DIR` 可换配置目录（多环境隔离用）
 
@@ -80,7 +80,7 @@ yos skill install
 - 成功输出（数字随内置 Skill 数量变化）：
 
 ```
-已安装 7 个 Skill 到：
+已安装 8 个 Skill 到：
 ~/.claude/skills
 ...
 提示：重启 Agent 工具以确保 Skill 加载
@@ -101,38 +101,37 @@ yos skill install
 ## 5. 验证
 
 ```bash
-yos doctor            # 七项全 ✓ 才算装好
+yos doctor            # 全部 ✓ 才算装好
 yos doctor --json     # 需要机器可读结果时（{checks:[{name,ok,detail}]}）
 yos kb list --json    # 端到端实跑一条只读命令收尾
 ```
 
-`doctor` 七项与样例：
+`doctor` 样例：
 
 ```
 ✓ 配置文件: 已找到
-✓ 服务环境: 生产（来自 内置缺省）
 ✓ 访问令牌: xxxxxxxx****xxxx
 ✓ 服务连通: 身份 张三（U00000001）
 ✓ Skill 安装: ~/.claude/skills
-✓ CLI 版本: 0.2.0（环境=生产）
+✓ CLI 版本: 0.2.0
 ✗ Skill 同步: 缺少版本状态（Skill 目录 1 个），执行 yos update 重同步
 ```
 
-- 退出码：七项全过 `0`；服务连通失败沿用底层错误（`3` 网络不可达 / `4` 鉴权失败）；其余未通过项为 `2`
+- 退出码：全部通过 `0`；服务连通失败沿用底层错误（`3` 网络不可达 / `4` 鉴权失败）；其余未通过项为 `2`
 - 「Skill 同步」读的是版本状态文件与 CLI 版本是否一致：`yos update` 或 `yos skill install` 任一跑过即刷新，`✗` 时按 detail 提示执行 `yos update`
 - Skill 项判定读的是**配置里的安装记录**，不是磁盘探测：手工删过 Skill 目录时 `doctor` 仍显示 ✓，有疑问就 `ls ~/.claude/skills/yos/SKILL.md`
 
 ## 6. 升级与卸载
 
-CLI 平时无需手动升级：每次命令执行后会在后台自动检查对应通道并静默更新（升级后自动重同步 Skill），下次运行生效。升级通道跟随服务环境：生产跟 latest 正式版，测试环境（`login --env test`）自动跟 test 通道，dev 不自动更新。
+CLI 平时无需手动检查升级：每次命令执行后会在后台检查对应通道最新版，落后时以 stderr 提示（Agent 按提示先执行 `yos update` 升级再继续任务）。升级通道自动跟随服务环境（测试环境跟 test 通道）。
 
 ```bash
-yos update                            # 需要立即升级时执行（到当前通道最新版并自动重同步 Skill）
+yos update                            # 看到落后提示或需要立即升级时执行（到当前通道最新版并自动重同步 Skill）
 yos update --check                    # 只查是否有新版本，不安装
 npm install -g @yosai/cli@latest        # 等价手动写法（正式版）；走这条路后需再跑 yos skill install 刷新 Skill
 ```
 
-（0.2.0 之前的版本没有 `yos update`，直接用 `npm install -g @yosai/cli@latest` 升级；如需关闭后台自动更新，设置环境变量 `YOS_NO_AUTO_UPDATE=1`）
+（0.2.0 之前的版本没有 `yos update`，直接用 `npm install -g @yosai/cli@latest` 升级）
 
 卸载（破坏性，逐项取得用户确认后再动手）：
 
@@ -150,7 +149,7 @@ ls ~/.claude/skills | grep -E '^yos'                   # 先看要删哪些，
 | `npm error code E404` / `'@yosai/cli' is not in this registry` | 包名拼错、该版本尚未发布到 npmjs，或 npm 镜像未同步 | 核对包名 `@yosai/cli`；已发布仍 404 多为镜像未同步，加 `--registry=https://registry.npmjs.org` 重试；仍有问题联系维护者 |
 | `npm error code EACCES`（写全局目录失败） | npm 全局前缀指向了 root 目录 | 让用户同意后再改前缀：`npm config set prefix ~/.npm-global`，把 `~/.npm-global/bin` 加进 PATH，重开终端重装。**不要 sudo** |
 | `错误: 令牌格式不正确（应为 40 位小写 hex）` + `提示: 请在客户端「个人设置-访问令牌」页创建并复制完整令牌` | 令牌长度不对 / 大写 / 粘了空格或前缀 | 让用户重新整段复制（40 位、仅 `0-9a-f`）；不要让用户逐字补 |
-| `错误: 无法连接 YOS 服务（生产），原因：fetch failed` | 服务不可达（环境选错、网络受限、服务异常） | 先 `yos doctor` 看「服务环境」项确认环境与来源；环境选错用 `yos login --env <环境>` 重配；网络问题找运维确认 |
+| `错误: 无法连接 YOS 服务，原因：fetch failed` | 服务不可达（网络受限、服务异常；测试/开发装机也可能环境未切换） | 先 `yos ping` 复测并检查网络；测试/开发装机环境选错用 `yos login --env test` 重配；网络问题找运维确认 |
 | `未配置访问令牌` + `请执行 yos login 或设置环境变量 YOS_API_KEY` | 没配置也没 env | 回第 3 步 |
 | `错误: 未发现已安装的 Agent 技能目录` | 本机没有已知的 AI 工具 Skill 目录 | `yos skill install --target <该工具 skills 目录>`，见第 4 步 |
 | `yos --version` 无输出或报未知命令 | 装的是 0.2.0 之前的旧版本（旧版没有 version/update 命令） | 先 `npm install -g @yosai/cli@latest` 升到最新版（≥0.2.0），之后即可用 `yos version` / `yos update` |
@@ -158,8 +157,9 @@ ls ~/.claude/skills | grep -E '^yos'                   # 先看要删哪些，
 
 ## 8. 装好之后
 
-- 让用户从 `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` skill（总入口）开始使用；命令细节看各领域 skill：`yos-knowledge`（知识库管理）、`yos-doc-sheet`（云文档/云表格编写）、`yos-retrieval`（检索与引用）、`yos-transcript`（录音转写）、`yos-support`（帮助/版本/反馈）、`yos-shared`（共享约定）
+- **呼出约定（务必转告用户）**：以后需要 YOS 能力时，在需求里带上「yos」最稳（如「用 yos 查一下报销标准」）；提到 yos 时 Agent 一定会走 YOS 技能，不提时可能不会主动使用
+- 本机可用能力：28 个领域命令（kb 4 / docs 11 / retrieve 5 / support 6 / transcript 2）+ `yos tool` 兜底通道，覆盖知识库检索与管理、文档上传下载与云文档/云表格编写、会议转写查询、帮助手册、客户端版本与反馈；新建与删除知识库不在 CLI 内，需到 YOS 客户端手动操作
 - 边界（别过度承诺）：不能实时控制转写、不能申请/变更权限、反馈不带附件、只能看到当前令牌归属用户可见的数据
-- 排查建议：任何失败先跑 `yos doctor`；退出码 `4` 一律重新登录，`3` 先看「服务环境」项与网络
+- 排查建议：任何失败先跑 `yos doctor`；退出码 `4` 一律重新登录，`3` 先复测网络连通
 

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

@@ -1,6 +1,6 @@
 ---
 name: yos-knowledge
-description: YOS 知识库与文档管理（kb list/detail/update/upload + docs tree/content/download/count/mkdir/create/update/rename/move/delete/restore）。用户要查资料在哪、上传或整理知识库文档、下载原文件、改名字/移动/删除/恢复时使用；含每条命令的参数、真实输出与报错修法
+description: YOS 知识库与文档管理（kb list/detail/update/upload + docs tree/content/download/count/mkdir/create/update/rename/move/delete/restore）。用户提到 yos/YOS 且要管理知识库与文档（查资料在哪、上传或整理文档、下载原文件、改名/移动/删除/恢复）时使用；含每条命令的参数、真实输出与报错修法
 ---
 
 # YOS 知识库与文档（kb / docs）
@@ -18,6 +18,7 @@ yos docs tree KB20260921000001           # → 节点的 resourceCode（形如 N
 - 编码规律：库 `KB`+yyyyMMdd+6 位序号，节点 `ND`+yyyyMMdd+6 位序号。示例里的 `KBxxx`/`NDxxx` 都是占位，真实调用必须来自上面三条命令
 - 写操作前先确认 `role`：`edit` 才能建/改内容与改名；`admin`/`owner` 才能移动、删除、恢复、改库名
 - `kb list` 不传 `--scope` 时返回**全部可见库**（含他人所有、自己只有 `read` 的库）。用户说「我的知识库」时要显式加 `--scope created`
+- `kb list` 缺省一次返回 50 条；输出末尾若出现「（共 N 条，还有 M 条；翻页加 --page K）」尾注，说明未拿全，必须继续翻页（判据见 1.1「输出尾部语义」）
 
 ---
 
@@ -30,7 +31,7 @@ yos kb list                                   # 全部可见（实测默认行
 yos kb list --scope created                   # 我创建的
 yos kb list --scope shared                    # 别人分享给我的
 yos kb list --keyword 公司资料                 # 按名称过滤
-yos kb list --page 2 --size 20                 # 翻页（size 上限 50）
+yos kb list --page 2 --size 20                 # 翻页（缺省一次拿 50 条，仅尾注提示还有更多时才需要）
 ```
 
 | flag | 工具参数 | 取值 | 缺省 |
@@ -38,7 +39,7 @@ yos kb list --page 2 --size 20                 # 翻页（size 上限 50）
 | `--scope` | `range` | `created` \| `shared` \| `all` | `all` |
 | `--keyword` | `keyword` | 名称关键词 | 无 |
 | `--page` | `page` | ≥1 整数 | 1 |
-| `--size` | `size` | 每页条数，1~50 | 10 |
+| `--size` | `size` | 每页条数，1~50 | 50 |
 
 非法值与越界值一律 exit=2 且不发请求：`--scope mine` → `错误: --scope 取值非法：mine` + `提示: 可选：created / shared / all`；`--size 1000` → `错误: --size 超过上限 50：1000` + `提示: 取值范围 1~50`。
 
@@ -50,12 +51,16 @@ KB20260928000003  AI智能研发部
 KB20260921000001  公司资料
 ```
 
-空结果输出 `（无知识库）`，不是空行。
+输出尾部语义（防漏翻页，按此判断是否拿全）：
+
+- 出现「（共 N 条，还有 M 条；翻页加 --page K）」尾注 → **未拿全**，必须继续用提示的 `--page K` 翻页，直到出现「（共 N 条，已到末页）」
+- 出现「（共 N 条，已到末页）」或无尾注（总数一页装下）→ 已拿全，可以下结论
+- 空结果输出 `（无知识库）`（不是空行）；页码超界输出「（本页无数据：共 N 条，--page X 超出范围）」——有库但页码太大，别当空库上报
 
 `--json` 结构（信封 `text` 需二次解析）：
 
 ```json
-{"records":[{"kbCode":"...","kbName":"...","description":"...","coverType":"preset","coverValue":"cover-tone-5","coverUrl":null,"ownerName":"张三","memberCount":1,"docCount":null,"role":"owner","graphEnabled":true,"ownerUserId":"U00000001","createdBy":"...","createTime":"2026-10-09 09:45:07","updateTime":"...","editedBy":"...","editorName":"...","editedAt":"..."}],"total":16,"page":1,"size":10}
+{"records":[{"kbCode":"...","kbName":"...","description":"...","coverType":"preset","coverValue":"cover-tone-5","coverUrl":null,"ownerName":"张三","memberCount":1,"docCount":null,"role":"owner","graphEnabled":true,"ownerUserId":"U00000001","createdBy":"...","createTime":"2026-10-09 09:45:07","updateTime":"...","editedBy":"...","editorName":"...","editedAt":"..."}],"total":15,"page":1,"size":50}
 ```
 
 **坑**：`records[].docCount` 在 list 里**恒为 `null`**（服务端只 detail 返回）。想知道各库文档数，逐库 `kb detail`，或直接说明拿不到；不要拿 `null` 当「空库」告诉用户。
@@ -270,7 +275,7 @@ yos docs create "方案" --parent ND20261010000028 --file ./plan.md
 | `<标题>` | `title` | 必填，≤128 字 |
 | `--content` / `--file` | `content` | **正文必填且不得为空白，两者互斥**。`--file` 读 UTF-8 文件内容；文件不存在 → `错误: 文件不存在或不可读：<路径>`（exit 2） |
 | `--kb` / `--parent` | `kb_code` / `parent_code` | 至少一个；都不传 → `错误: --kb、--parent 至少传一个`（exit 2） |
-| `--type` | `doc_type` | `md`（缺省）\| `cloud` \| `sheet`。`cloud`/`sheet` 的 `content` 要传对应草稿/快照 JSON，不是普通文本 |
+| `--type` | `doc_type` | `md`（缺省）\| `cloud` \| `sheet`（后两者正文是结构化草稿 JSON，**先读 yos-doc-sheet 技能**） |
 
 成功：`文档创建成功，节点编码：ND20261010000030`
 
@@ -280,6 +285,12 @@ yos docs create "方案" --parent ND20261010000028 --file ./plan.md
 
 多行、含引号或 shell 特殊字符的正文一律写临时文件走 `--file`，不要用 `--content` 拼字符串。
 
+**`--type cloud` / `--type sheet` 的正文是结构化 JSON，不是普通文本**：
+
+- 正文内容（标题、段落、表格数据等）都编码在 JSON 里，只改外层 `--title` 不会改正文；反过来 JSON 结构错了服务端也照样存，**渲染成什么样以客户端打开为准**
+- 编写规范、完整结构定义与真实可跑样例一律见 **`yos-doc-sheet` 技能**：新建（`docs create`）与修改（`docs update`）用的是同一份结构
+- 一般场景的判定：用户上传的办公文件（`kb upload`）与 Markdown 文本（`--type md`）不需要本技能；**往知识库写「在线文档/在线表格」正文**才需要
+
 ### 2.7 `docs update` — 改标题/正文/简介
 
 ```bash
@@ -298,6 +309,8 @@ yos docs content ND20261010000030 --json     # 1. 取当前完整正文
 yos docs update ND20261010000030 --file ./new.md   # 3. 整体回传
 ```
 
+云文档/云表格节点（`docType=cloud`/`sheet`）的正文回传的是**对应草稿 JSON**（`docs content` 读回的 `content` 是 JSON 字符串，二次解析后修改再整体回传；结构与新建时相同，见 `yos-doc-sheet` 技能）。上传的办公文件（`docType=file`）没有内联正文，`docs update` 改不了其内容。
+
 改完会触发 cortex 重新解析，检索索引近实时（实测新文档写完即可被 `retrieve search` 命中并排到首位）。
 
 **文档改名只能用 `docs update --title`**；`docs rename` 只用于文件夹，对文档执行 → `工具执行失败：节点类型不符：ND20261010000018 实际是文档，本操作要求文件夹`（exit 1）。

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

@@ -1,6 +1,6 @@
 ---
 name: yos-retrieval
-description: 用 yos retrieve 五命令检索 YOS 知识库并按带出处的原文作答（search 定位 → read 取原文 → grep/outline/neighbors 辅助，含 URN 规则、全参数表、实测报错）。用户问公司制度/流程/资料、要引用原文、要找某编号或条款、问有哪些文档时使用
+description: 用 yos retrieve 五命令检索 YOS 知识库并按带出处的原文作答（search 定位 → read 取原文 → grep/outline/neighbors 辅助，含 URN 规则、全参数表、实测报错）。用户提到 yos/YOS 且要检索知识库找答案（制度/流程/规范、部门/工作/个人资料、引用原文、找编号条款、问有哪些文档）时使用
 ---
 
 # YOS 知识检索（`yos retrieve`）

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

@@ -1,6 +1,6 @@
 ---
 name: yos-shared
-description: YOS CLI 共享约定（登录配置、--json 双重解析、退出码、报错分类、通用参数规则、安全与权限）。使用任何 yos 命令前读本文件；遇到报错或不确定参数写法也查这里
+description: YOS CLI 共享约定（登录配置、--json 双重解析、退出码、报错分类、通用参数规则、安全与权限）。用户提到 yos/YOS 或使用任何 yos 命令前读本文件；遇到报错或不确定参数写法也查这里
 ---
 
 # YOS CLI 共享约定
@@ -10,18 +10,17 @@ description: YOS CLI 共享约定（登录配置、--json 双重解析、退出
 ## 1. 前置检查（会话内只做一次）
 
 ```bash
-yos doctor      # 七项全 ✓ 才能继续；任一项 ✗ 按下方「未登录/连通失败」处理
+yos doctor      # 全部 ✓ 才能继续；任一项 ✗ 按下方「未登录/连通失败」处理
 ```
 
-`yos doctor` 真实输出（七项检查，退出码即结论）：
+`yos doctor` 真实输出（退出码即结论）：
 
 ```
 ✓ 配置文件: 已找到
-✓ 服务环境: 生产（来自 内置缺省）
 ✓ 访问令牌: xxxxxxxx****xxxx
 ✓ 服务连通: 身份 张三（U00000001）
 ✓ Skill 安装: ~/.claude/skills, ~/.qoder-cn/skills
-✓ CLI 版本: 0.2.0（环境=生产）
+✓ CLI 版本: 0.2.0
 ✓ Skill 同步: 与 CLI 一致（2 个目录）
 ```
 
@@ -30,14 +29,14 @@ yos doctor      # 七项全 ✓ 才能继续；任一项 ✗ 按下方「未登
 | `command not found: yos` | CLI 未安装或全局 bin 不在 PATH，按 `yos-install` skill 引导安装（`npm install -g @yosai/cli` → `yos login` → 验证），不要继续猜命令 |
 | `✗ 配置文件: 未找到，请执行 yos login` | 执行 `yos login --key <令牌>`（令牌由用户在 YOS 客户端「个人设置-访问令牌」页创建并复制，40 位小写 hex） |
 | `✗ 访问令牌: 未配置访问令牌` | 同上；CI/容器可改为设置环境变量 `YOS_API_KEY` |
-| `✗ 服务连通: ...` | 看错误类型：网络不可达（退出码 3）→ 检查服务环境与网络；鉴权失败（4）→ 令牌失效，重新 `yos login` |
+| `✗ 服务连通: ...` | 看错误类型：网络不可达（退出码 3）→ 检查网络连通（测试/开发装机确认环境未选错）；鉴权失败（4）→ 令牌失效，重新 `yos login` |
 | `✗ Skill 安装: 尚未安装，执行 yos skill install` | 执行 `yos skill install`，未探测到目录时 `--target ~/.claude/skills` |
 
 配置细节（排障时才需要）：
 
 - 配置文件 `~/.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 起的服务）；`yos doctor` 的「服务环境」项显示当前环境与来源
+- 切换服务环境（测试/开发用）：`yos login --env test`（临时用 `YOS_ENV=test`），本地调试 `--env dev`（指向本机 8080 起的服务）
 - 令牌格式先本地校验：`yos login` 粘贴了非 40 位小写 hex 会直接报 `错误: 令牌格式不正确（应为 40 位小写 hex）`，不会落盘
 
 **安全**：绝不把令牌写进命令历史可见的日志、代码仓库或对用户的回复里；`--key` 传令牌仅用于无交互场景，回复中一律用掩码形式（`xxxxxxxx****xxxx`）。
@@ -46,7 +45,7 @@ yos doctor      # 七项全 ✓ 才能继续；任一项 ✗ 按下方「未登
 
 | 形态 | 实际内容 | 解析方式 |
 |---|---|---|
-| 默认（不加 `--json`） | 直接打印服务端返回文本：多数命令是**单行紧凑 JSON**，少数是纯文本提示；`kb list` 特化为两列表格（`KB编码  名称`） | 人读用；给程序处理请改用 `--json` |
+| 默认（不加 `--json`） | 直接打印服务端返回文本：多数命令是**单行紧凑 JSON**，少数是纯文本提示；`kb list` 特化为两列表格（`KB编码  名称`），未拿全时末尾带「（共 N 条，还有 M 条；翻页加 --page K）」尾注 | 人读用；给程序处理请改用 `--json` |
 | `--json` | 固定信封 `{"text": "...", "isError": false}` | **需要二次解析**：`text` 是 JSON **字符串**，业务数据要再 `JSON.parse(text)`；`isError: true` 时 `text` 是错误文案（纯文本，不可 parse） |
 
 ```bash
@@ -86,7 +85,7 @@ CLI 对两套编码原样透出不做映射。遇到 cortex 侧编码时：可
 | 0 | 成功 | — | 继续 |
 | 1 | 业务失败（服务端拒绝/资源不存在） | `工具执行失败：知识库不存在：KB不存在`<br>`节点类型不符：ND... 实际是文档，本操作要求文件夹` | 按文案修参数，不要盲目重试 |
 | 2 | 参数/用法错误（CLI 本地拦截，未发请求） | `错误: 缺少 --kind`<br>`提示: 用法: yos retrieve neighbors <target> --kind <值> ...` | 照 `提示:` 里的用法改写 |
-| 3 | 网络错误/服务不可达 | `错误: 无法连接 YOS 服务（生产），原因：fetch failed` | 确认服务环境与网络连通，`yos ping` 复测 |
+| 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` 升级再原样重试；不要改参数反复试探 |
 
@@ -128,7 +127,7 @@ exit=1 的文案偶有服务端内部字段名（如 `kb_code`、`output_mode`
 不要凭记忆或猜测拼编码，按链路取真值：
 
 ```bash
-yos kb list                          # → kbCode（表格左列）
+yos kb list                          # → kbCode（表格左列；末尾有「还有 M 条」尾注时须先翻页拿全）
 yos docs tree KB20260921000001         # → resourceCode（树里每个节点的编码）
 yos retrieve outline 'cortex://kb/KB20260921000001'   # → 文档 URN（含行号，检索决策用）
 yos transcript list                     # → transcriptionUserId
@@ -176,11 +175,19 @@ yos tool call docs_tree --params '{"kb_code":"KB20260921000001"}'
 - 工具名容忍空格与连字符写法：`yos tool schema docs tree` / `support manual-read` 都会归一化为 `docs_tree` / `support_manual_read`
 - 域命令是工具的一一映射（`kb upload` 除外，走 multipart 直传），能用域命令就别用 `tool call`
 
-## 9. 升级与重装
+## 9. 升级与版本更新约定
 
 ```bash
-npm install -g @yosai/cli     # 公共 npmjs，需 Node >= 18（见 yos-install）
-yos skill install            # 升级后必须重装 Skill，让 Agent 目录里的说明同步
+yos update                   # 升到当前环境通道最新版（升级后自动重同步 Skill）
+npm install -g @yosai/cli    # 手动等价写法（公共 npmjs，需 Node >= 18，见 yos-install）；走这条路后需 yos skill install 刷新 Skill
 ```
 
+**版本提示约定（必须遵守）**：任何 yos 命令执行后，stderr 可能出现
+
+```
+提示: 有新版本 x.y.z（当前 a.b.c），请先执行 yos update 升级再继续任务
+```
+
+含义是本机 CLI 落后于当前升级通道（测试环境为 test 通道）的最新版。正确动作：先执行 `yos update`，完成后回到原任务继续（刚才的命令重试或接着做后续步骤）。`yos update` 失败（权限不足、网络不可达等）时向用户报告失败原因并继续原任务，不要反复重试升级。服务端强制的版本门槛表现为退出码 5（见第 3 节），同样需先升级再重试。
+
 `yos skill install` 会覆盖写入各 Agent 技能目录，装完需**重启 Agent 工具**才生效；`yos doctor` 的「Skill 安装」项可确认已安装目录。

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

@@ -1,6 +1,6 @@
 ---
 name: yos-support
-description: YOS 帮助与支持（manual/manual-read/manual-search 帮助手册，upgrade/upgrade-log 客户端版本，feedback 提交反馈）。用户问 YOS 怎么用、要客户端最新版本、要报问题时使用
+description: YOS 帮助与支持（manual/manual-read/manual-search 帮助手册，upgrade/upgrade-log 客户端版本，feedback 提交反馈）。用户提到 yos/YOS 且要查 YOS 使用手册、客户端最新版本、提交反馈时使用
 ---
 
 # YOS 帮助与支持（support）

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

@@ -1,6 +1,6 @@
 ---
 name: yos-transcript
-description: YOS 录音转写查询（transcript list 列表 / transcript detail 详情，含分段、纪要、思维导图、音频地址与字段坑）。用户想看会议录音转写、要纪要、查某次会议内容时使用
+description: YOS 录音转写查询（transcript list 列表 / transcript detail 详情，含分段、纪要、思维导图、音频地址与字段坑）。用户提到 yos/YOS 且要看会议录音转写、要纪要、查某次会议内容时使用
 ---
 
 # YOS 录音转写（transcript）

package/dist/update-check-worker.js

@@ -1,12 +1,8 @@
-import { mkdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { realpathSync } from 'node:fs';
 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 { loadConfig, resolveChannel } from './config.js';
+import { fetchLatestVersion, readPackageMeta } from './npm-meta.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) {
@@ -18,70 +14,11 @@ export async function runUpdateCheck() {
     }
     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;

package/dist/update-notice.js

@@ -5,7 +5,7 @@ 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 CACHE_TTL_MS = 2 * 60 * 60 * 1000;
 const SKIP_COMMANDS = new Set(['update', 'version']);
 function checkStatePath() {
     return join(configDir(), 'update-check.json');
@@ -45,9 +45,9 @@ export function evaluateNotice(input) {
     if (compareVersions(input.currentVersion, input.state.latest) >= 0) {
         return 'skip';
     }
-    return input.tty && !input.argv.includes('--json') ? 'notify' : 'skip';
+    return 'notify';
 }
-export function handleUpdateNotice(argv, commandName) {
+export function handleUpdateNotice(commandName) {
     try {
         const channel = resolveChannel(loadConfig());
         if (channel === null) {
@@ -56,10 +56,8 @@ export function handleUpdateNotice(argv, commandName) {
         const currentVersion = getCliVersion();
         const state = loadCheckState(channel);
         const decision = evaluateNotice({
-            argv,
             commandName,
             state,
-            tty: Boolean(process.stderr.isTTY),
             now: new Date(),
             currentVersion,
         });
@@ -68,7 +66,7 @@ export function handleUpdateNotice(argv, commandName) {
             return;
         }
         if (decision === 'notify' && state) {
-            printErr(`提示: 有新版本 ${state.latest}（当前 ${currentVersion}），执行 yos update 升级`);
+            printErr(`提示: 有新版本 ${state.latest}（当前 ${currentVersion}），请先执行 yos update 升级再继续任务`);
         }
     }
     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yosai/cli",
-  "version": "0.2.1-test.7",
+  "version": "0.2.1-test.9",
   "description": "YOS 能力的 Agent 执行入口：工具调用、知识库管理与文件上传",
   "type": "module",
   "bin": {