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

package/dist/skills/yos-doc/scripts/yos-doc.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * yos-doc — DocDraft schema / validate CLI（Node ≥ 18）
+ * 实现：./validate-runtime-doc.mjs（同步自 @yos/doc-editor@0.0.41）
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  AGENT_ALLOWED_MARKS,
+  AGENT_FORBIDDEN_MARKS,
+  AGENT_FORBIDDEN_NODES,
+  AGENT_TIER_A_NODES,
+  AGENT_TIER_B_NODES,
+  validateDocDraft,
+} from "./validate-runtime-doc.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REFERENCES_DIR = resolve(__dirname, "..", "references");
+
+function printHelp() {
+  process.stdout.write(`yos-doc — YOS DocDraft 工具（Agent / CI）
+
+用法:
+  yos-doc schema [--tier A|B]
+  yos-doc validate <draft.json> [--tier A|B]
+  yos-doc paths
+
+命令:
+  schema    打印当前档位白名单（JSON）
+  validate  校验 DocDraft JSON 文件；通过 exit 0，失败 exit 1
+  paths     打印 AGENT_SCHEMA / few-shot / 全量文档路径
+
+选项:
+  --tier A|B   默认 A；B 额外允许 columnBlock / column / image
+  -h, --help   帮助
+`);
+}
+
+function parseTier(argv) {
+  const index = argv.indexOf("--tier");
+  if (index === -1) {
+    return "A";
+  }
+  const value = argv[index + 1];
+  if (value === "A" || value === "B") {
+    return value;
+  }
+  process.stderr.write(`无效 --tier: ${String(value)}（仅 A|B）\n`);
+  process.exit(2);
+}
+
+function cmdSchema(tier) {
+  const payload = {
+    tier,
+    root: {
+      title: "string",
+      content: { type: "doc", content: [] },
+      attachments: [],
+    },
+    nodes: {
+      A: [...AGENT_TIER_A_NODES],
+      B: tier === "B" ? [...AGENT_TIER_B_NODES] : [],
+      forbidden: [...AGENT_FORBIDDEN_NODES],
+    },
+    marks: {
+      allowed: [...AGENT_ALLOWED_MARKS],
+      forbidden: [...AGENT_FORBIDDEN_MARKS],
+    },
+    docs: {
+      agentSchema: "references/AGENT_SCHEMA.doc.md",
+      fewShot: "references/few-shot.draft.json",
+      fullApi: "references/DOC_DATA_API.md",
+    },
+  };
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function cmdPaths() {
+  const paths = {
+    agentSchema: join(REFERENCES_DIR, "AGENT_SCHEMA.doc.md"),
+    fewShot: join(REFERENCES_DIR, "few-shot.draft.json"),
+    fullApi: join(REFERENCES_DIR, "DOC_DATA_API.md"),
+    template: join(REFERENCES_DIR, "doc-draft.template.json"),
+  };
+  process.stdout.write(`${JSON.stringify(paths, null, 2)}\n`);
+}
+
+function cmdValidate(fileArg, tier) {
+  if (!fileArg) {
+    process.stderr.write("validate 需要 <draft.json> 路径\n");
+    process.exit(2);
+  }
+  const filePath = resolve(process.cwd(), fileArg);
+  let raw;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch (error) {
+    process.stderr.write(`无法读取: ${filePath}\n${String(error)}\n`);
+    process.exit(2);
+  }
+  let draft;
+  try {
+    draft = JSON.parse(raw);
+  } catch (error) {
+    process.stderr.write(`JSON 解析失败: ${String(error)}\n`);
+    process.exit(1);
+  }
+  if (typeof draft !== "object" || draft === null || Array.isArray(draft)) {
+    process.stderr.write("根必须是对象（DocDraft）\n");
+    process.exit(1);
+  }
+  const result = validateDocDraft(draft, { tier });
+  if (result.ok) {
+    process.stdout.write(`OK (${filePath}) tier=${tier}\n`);
+    process.exit(0);
+  }
+  process.stderr.write(
+    `FAIL (${filePath}) tier=${tier} — ${result.issues.length} issue(s)\n`,
+  );
+  for (const issue of result.issues) {
+    process.stderr.write(`  - ${issue.path}: ${issue.message}\n`);
+  }
+  process.exit(1);
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
+    printHelp();
+    process.exit(argv.length === 0 ? 2 : 0);
+  }
+  const command = argv[0];
+  const tier = parseTier(argv);
+  if (command === "schema") {
+    cmdSchema(tier);
+    return;
+  }
+  if (command === "paths") {
+    cmdPaths();
+    return;
+  }
+  if (command === "validate") {
+    const fileArg = argv.find(
+      (item, index) =>
+        index > 0 && !item.startsWith("-") && argv[index - 1] !== "--tier",
+    );
+    cmdValidate(fileArg, tier);
+    return;
+  }
+  process.stderr.write(`未知命令: ${String(command)}\n`);
+  printHelp();
+  process.exit(2);
+}
+
+main();

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

@@ -1,18 +1,18 @@
 ---
 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. 引导纪律
 
 - 一次只执行一步，把该步命令的**输出原文**给用户，再决定下一步；不要连跑多条命令后统一汇报
-- 需要访问令牌时：优先让用户自己在终端输入（`yos login` 的输入不回显）；确需 Agent 代跑时用 `--key`/环境变量，并提醒用户该命令会进入 shell 历史
+- 需要访问令牌时：优先让用户自己在终端输入（`yos login` 的输入不回显）；确需 Agent 代跑时用 `--key`/环境变量
 - **凭据零外泄**：访问令牌不写进代码仓库、日志、聊天正文或文档；引用时一律掩码（形如 `xxxxxxxx****xxxx`，即原令牌前 8 位 + `****` + 后 4 位）
 - 不擅自改用户的全局配置：写 `~/.npmrc`、改 `npm prefix`、删 skill 目录这类动作先取得用户同意
 - 全程不需要 `sudo`。权限报错按第 7 节处置，不要 `sudo npm install -g`（会把 root 拥有的文件混进全局目录，后续更难维护）
@@ -30,18 +30,38 @@ command -v yos   # 已有 yos → 跳到第 3 步（登录），不要重复安
 
 ## 2. 安装 CLI
 
+先做**落点判定**——`npm install -g` 的落点由**执行它的那个 node** 决定。Agent 工具常自带托管 Node，直接装会把 `yos` 送进 Agent 私有目录（路径含 `.workbuddy`/`.cursor`/`.qoder`/`.claude`/`.trae` 等隐藏目录，或含 `versions/<版本号>`）：你这边能跑、用户终端却 `command not found`，工具升级或清缓存后 CLI 还会无声消失。
+
+macOS / Linux：
+
 ```bash
-npm install -g @yosai/cli
+npm prefix -g                                                          # ① 你这边（Agent）的落点
+env -i HOME="$HOME" TERM=xterm "$SHELL" -l -c 'command -v node; npm prefix -g'   # ② 用户终端视角
+```
+
+- `env -i` 不可省略：普通登录 shell 会继承你进程的 PATH，两边恒等是假阳性；`$SHELL` 为空时改试 `/bin/zsh`、`/bin/bash`；② 查不到 node（nvm 场景）改用 `-i -l`
+- ① ② 一致 → 直接装；不一致，或 ① 落在 Agent 工具目录 → 用 ② 查到的**用户终端 node 绝对路径**装（npm 取同目录），如 `/usr/local/bin/node /usr/local/bin/npm install -g @yosai/cli`
+- ② 查不到 node → 用户机器没有全局 Node：引导用户装 Node 18+ 并重开终端后复检；**不要**退而装进 Agent 私有目录，那样用户终端永远用不了
+
+Windows（PowerShell，读注册表 PATH 才不受你进程 PATH 污染）：
+
+```powershell
+$clean = [Environment]::GetEnvironmentVariable('Path','Machine') + ';' + [Environment]::GetEnvironmentVariable('Path','User')
+$nodeDir = ($clean -split ';' | Where-Object { $_ -and (Test-Path (Join-Path $_ 'node.exe')) } | Select-Object -First 1)
+& (Join-Path $nodeDir 'npm.cmd') install -g '@yosai/cli'
 ```
 
-装完立刻验证：
+装完立刻验证（最后一条是用户终端视角的复查，通过才算真的装好）：
 
 ```bash
 command -v yos            # 全局 bin 路径
 yos --version             # 输出「yos CLI 0.2.0」即安装成功（等价 yos version）
 yos --help                # 输出「yos - YOS 能力的 Agent 执行入口」
+env -i HOME="$HOME" TERM=xterm "$SHELL" -l -c 'command -v yos && yos --version'   # 干净终端同样输出版本号才算装好
 ```
 
+- 干净终端查不到即装进了 Agent 私有目录 → 用 ② 查到的 node 重装；重装后在 Agent 侧清掉私产那份（破坏性操作，先取得用户同意）
+
 ## 3. 登录（唯一需要用户配合的动作）
 
 1. 让用户在 **YOS 客户端「个人设置-访问令牌」页**创建并复制访问令牌：40 位小写十六进制字符串
@@ -60,15 +80,15 @@ yos login --key '<40 位令牌>'
 3. 成功输出（原样回给用户即可，`key` 已是掩码）：
 
 ```
-已保存配置：endpoint=https://yos-bff.linkduoo.com，key=xxxxxxxx****xxxx，身份 张三（U00000001）
+已保存配置：key=xxxxxxxx****xxxx，身份 张三（U00000001）
 ```
 
 关键语义：
 
 - `login` 会**先调服务端校验身份再落盘**，校验失败不写配置 → 报网络或令牌错时无需清理"半成品"配置，改对参数重跑即可
-- 端点缺省为生产环境 `https://yos-bff.linkduoo.com`。切环境用 `yos login --endpoint <url>`（本地联调 `http://localhost:8080`）；`--endpoint` 不传时沿用配置文件里已有的值
+- 切换服务环境（测试/开发装机用）：`yos login --env test`（临时切换可先 `export YOS_ENV=test`），本地服务 `--env dev`
 - 配置文件 `~/.config/yos/config.json`（目录 0700、文件 0600）
-- CI/容器可完全跳过 `login`：`export YOS_API_KEY=<令牌>`、`export YOS_ENDPOINT=<端点>`（两者都优先于配置文件）；`YOS_CONFIG_DIR` 可换配置目录（多环境隔离用）
+- CI/容器可完全跳过 `login`：`export YOS_API_KEY=<令牌>`、`export YOS_ENV=test` 指定服务环境（两者都优先于配置文件）；`YOS_CONFIG_DIR` 可换配置目录（多环境隔离用）
 
 ## 4. 安装内置 Skill 到 AI 工具
 
@@ -76,11 +96,11 @@ 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 数量变化）：
 
 ```
-已安装 7 个 Skill 到：
+已安装 9 个 Skill 到：
 ~/.claude/skills
 ...
 提示：重启 Agent 工具以确保 Skill 加载
@@ -101,37 +121,41 @@ yos skill install
 ## 5. 验证
 
 ```bash
-yos doctor            # 七项全 ✓ 才算装好
+yos doctor            # 全部 ✓ 才算装好
 yos doctor --json     # 需要机器可读结果时（{checks:[{name,ok,detail}]}）
 yos kb list --json    # 端到端实跑一条只读命令收尾
 ```
 
-`doctor` 七项与样例：
+`doctor` 样例：
 
 ```
 ✓ 配置文件: 已找到
-✓ 服务端点: https://yos-bff.linkduoo.com（来自 内置缺省）
 ✓ 访问令牌: xxxxxxxx****xxxx
 ✓ 服务连通: 身份 张三（U00000001）
 ✓ Skill 安装: ~/.claude/skills
-✓ CLI 版本: 0.2.0（endpoint=https://yos-bff.linkduoo.com）
+✓ 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 平时无需手动检查升级：每次命令执行前会检查对应通道最新版（后台进程查询，结果缓存 10 分钟），落后时在命令输出之前以 stderr 提示（Agent 按提示先执行 `yos update` 升级再继续任务）。升级通道自动跟随服务环境（测试环境跟 test 通道）。
+
 ```bash
-yos update                            # 推荐：升级到 npmjs 最新版并自动重同步 Skill
+yos update                            # 看到落后提示或需要立即升级时执行（到当前通道最新版并自动重同步 Skill）
 yos update --check                    # 只查是否有新版本，不安装
-npm install -g @yosai/cli@latest        # 等价手动写法；走这条路后需再跑 yos skill install 刷新 Skill
+yos update --version <x.y.z>          # 安装指定版本（可升可降，用于回退或锁定版本）
+npm install -g @yosai/cli@latest        # 等价手动写法（正式版）；走这条路后需再跑 yos skill install 刷新 Skill
 ```
 
 （0.2.0 之前的版本没有 `yos update`，直接用 `npm install -g @yosai/cli@latest` 升级）
 
+以上所有 `npm install -g`（含 `yos update` 内部调用）同样受第 2 节落点约束：落点不一致时会把新版装进 Agent 私有目录——改用用户终端 node 对应的 npm 重装，装完重跑可达性校验。
+
 卸载（破坏性，逐项取得用户确认后再动手）：
 
 ```bash
@@ -145,10 +169,11 @@ ls ~/.claude/skills | grep -E '^yos'                   # 先看要删哪些，
 | 看到的原文 | 原因 | 处置 |
 |---|---|---|
 | `command not found: yos` | 未安装，或全局 bin 不在 PATH | 先 `npm ls -g @yosai/cli` 判断是否装上；装上了就查 `npm prefix -g` 的 `/bin` 是否在 PATH，改 `~/.zshrc` 后重开终端 |
+| 你这边 `yos --version` 正常，用户终端却 `command not found: yos` | 装进了 Agent 托管 Node 的私有 prefix（路径常带版本号，只在 Agent 进程里进 PATH） | 按第 2 节落点判定，用用户终端 node 对应的 npm 重装；重装后清掉私产那份（破坏性操作，先取得用户同意） |
 | `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 服务：endpoint=http://.../open-apis，原因：fetch failed` | 端点不可达（环境填错、本地服务没起、网络受限） | `yos login --endpoint <正确地址>` 重配；本地联调时确认本地服务已在 8080 端口起来 |
+| `错误: 无法连接 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` |
@@ -156,7 +181,9 @@ ls ~/.claude/skills | grep -E '^yos'                   # 先看要删哪些，
 
 ## 8. 装好之后
 
-- 让用户从 `yos` skill（总入口）开始使用；命令细节看各领域 skill：`yos-kb`（知识库管理）、`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`（云文档编写）、`yos-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-kb → yos-knowledge}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: yos-kb
-description: YOS 知识库与文档管理（kb list/detail/update/upload + docs tree/content/download/count/mkdir/create/update/rename/move/delete/restore）。用户要查资料在哪、上传或整理知识库文档、下载原文件、改名字/移动/删除/恢复时使用；含每条命令的参数、真实输出与报错修法
+name: yos-knowledge
+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` 当「空库」告诉用户。
@@ -261,7 +266,7 @@ yos docs mkdir 2026Q3 --kb KB20260921000001 --parent ND2026...     # 某文件
 ```bash
 yos docs create "周报 2026-W40" --kb KB20260921000001 --content "## 本周进展\n完成了 X"
 yos docs create "会议纪要" --kb KB20260921000001 --file ./minutes.md         # 多行/长正文首选 --file
-yos docs create "空表格" --kb KB20260921000001 --type sheet --content '{"id":"","sheetOrder":[],"sheets":{}}'
+yos docs create "排期表" --kb KB20260921000001 --type sheet --file ./draft.sheet.json   # 云文档/云表格正文为结构化 JSON，先读 yos-doc / yos-sheet 技能
 yos docs create "方案" --parent ND20261010000028 --file ./plan.md
 ```
 
@@ -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，**cloud 先读 yos-doc、sheet 先读 yos-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`（云文档）/ `yos-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` / `yos-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` 真实输出（退出码即结论）：
 
 ```
 ✓ 配置文件: 已找到
-✓ 服务端点: https://yos-bff.linkduoo.com（来自 内置缺省）
 ✓ 访问令牌: xxxxxxxx****xxxx
 ✓ 服务连通: 身份 张三（U00000001）
 ✓ Skill 安装: ~/.claude/skills, ~/.qoder-cn/skills
-✓ CLI 版本: 0.2.0（endpoint=https://yos-bff.linkduoo.com）
+✓ 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），字段 `{endpoint, apiKey, installedSkillDirs}`
-- 环境变量优先级：`YOS_API_KEY` > 配置文件 `apiKey`；`YOS_ENDPOINT` > 配置文件 `endpoint`；`YOS_CONFIG_DIR` 覆盖配置目录（测试隔离用）
-- 端点缺省 `https://yos-bff.linkduoo.com`，切换用 `yos login --endpoint <url>`（本地联调 `http://localhost:8080`）；实际请求基址为 `<endpoint>/open-apis`
+- 配置文件 `~/.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 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,8 +85,9 @@ CLI 对两套编码原样透出不做映射。遇到 cortex 侧编码时：可
 | 0 | 成功 | — | 继续 |
 | 1 | 业务失败（服务端拒绝/资源不存在） | `工具执行失败：知识库不存在：KB不存在`<br>`节点类型不符：ND... 实际是文档，本操作要求文件夹` | 按文案修参数，不要盲目重试 |
 | 2 | 参数/用法错误（CLI 本地拦截，未发请求） | `错误: 缺少 --kind`<br>`提示: 用法: yos retrieve neighbors <target> --kind <值> ...` | 照 `提示:` 里的用法改写 |
-| 3 | 网络错误/服务不可达 | `错误: 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` 升级再原样重试；不要改参数反复试探 |
 
 `1` 与 `2` 的关键差别：**2 根本没发请求**，改法一定写在 `提示:` 里；**1 是服务端结论**，文案里带具体编码，直接引用给用户。
 
@@ -127,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
@@ -175,11 +175,20 @@ 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）
+yos update --version <x.y.z> # 安装指定版本（可升可降，用于回退或锁定版本）
+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 安装」项可确认已安装目录。