@yosai/cli 0.0.0-stage → 0.2.1-test.0

package/dist/skills/yos/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: yos
+description: YOS 企业 AI 能力总入口：公司知识库检索、文档管理、录音转写、帮助手册、客户端升级与反馈。用户问公司制度/流程/资料、要查或整理知识库文档、要看会议录音转写、需要 YOS 客户端帮助时使用；不确定该用哪个 YOS 能力时先读本文件
+---
+
+# YOS 能力总入口
+
+YOS 是企业 AI 底座：公司知识、会议录音、帮助手册等能力都可通过本机 `yos` 命令查询与操作。本文件只做**路由与前置判断**，每个命令的参数、返回字段、报错都在对应领域 skill 里，执行前务必读那一本。
+
+## 0. 开工前先确认环境（30 秒）
+
+```bash
+yos doctor      # 七项 ✓ 才继续：配置文件 / 服务端点 / 访问令牌 / 服务连通（回显身份）/ Skill 安装 / CLI 版本 / Skill 同步
+yos ping        # 只要探活，退出码即结论（0 通 / 3 网络 / 4 鉴权）
+```
+
+- `command not found: yos` 或 `yos doctor` 报「未找到配置文件」→ 按 `yos-install` skill 引导用户装 CLI 与登录，不要继续猜命令
+- 已装但七项没全 ✓ → 先修环境再执行任务；`yos doctor` 的失败项自带修复提示
+- 查版本用 `yos version`（或 `yos --version`）；升级到 npmjs 最新版用 `yos update`
+
+## 1. 意图路由
+
+| 用户在问什么 | 用哪个命令 | 先读哪本 skill |
+|---|---|---|
+| 「公司制度/流程/规范/报销标准/产品资料」等**要一个公司里的答案** | `retrieve search` → `retrieve grep` 定位 → `retrieve read` 读原文 | yos-retrieval |
+| 「有哪些文档 / 共几份 / 文档目录结构」 | `retrieve outline`（检索层）或 `docs tree`（管理层） | yos-retrieval / yos-kb |
+| 找**配套/相关**材料、跨文档关系 | `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 |
+| 会议录音转写、纪要、逐句发言 | `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 |
+
+五个领域共 28 个命令（kb 4 / docs 11 / retrieve 5 / support 6 / transcript 2）。服务端工具清单以 `yos tool list` 动态获取为准，命令与工具基本 1:1，例外是 `docs download` 与 `kb upload`——两者因需读写本地文件而单独实现（后者走开放接口上传通道，不对应 MCP 工具）。`yos <领域> --help` 列出该域全部命令，`yos <领域> <动作> --help` 给出用法、参数说明与风险标注（只读 / 写入 / 高危）。
+
+**新建与删除知识库都不在 CLI 与服务端工具集内**：用户提到建库或删库时，引导其到 YOS 客户端手动操作，不要尝试 `yos kb create` / `yos kb delete`（会被拒绝，exit=2）。建好库之后用 `yos kb list` 取知识库编码即可继续上传与整理。
+
+## 2. 七条硬规则（违反必出错）
+
+1. **`--json` 是双层包装**：外层 `{"text":"<JSON 字符串>","isError":false}`，要拿字段必须对 `text` 再 `JSON.parse` 一次；`isError:true` 时 `text` 是错误文案而非数据
+2. **参数错误一律 exit=2 且不发请求**：非法枚举、越界 `--size`、日期格式非法或区间倒置、URN 非法、必填缺失都由 CLI 本地拦下，照 `提示:` 改参数即可，不要重试原命令。exit=0 仍需自行校验内容的场景见 yos-shared
+3. **引用作答必须读原文**：`retrieve search` 的 `snippet` 只是线索，不能作为引用依据；未 `retrieve read` 之前不下结论
+4. **写操作先复述再执行**：`kb update`、`docs create/update/mkdir/rename/move`、`kb upload`、`support feedback` 都要让用户确认最终文案；`docs update` 是**整体覆盖**（正文传什么就替换什么）
+5. **删除必须两步**：`yos docs count <node_code>` 查受影响文档数 → 展示给用户 → 用户明确同意后才 `yos docs delete`。未经确认不得调用
+6. **令牌不出现在任何输出里**：不写进日志、命令、对用户的回复；只以掩码形式（`xxxxxxxx****xxxx`，即前 8 位 + `****` + 后 4 位）引用
+7. **日期参数分两类，别混用**：`transcript list --start/--end`、`support upgrade-log --start/--end` **只收 `yyyy-MM-dd`**，中文表达由 CLI 本地拒绝（`错误: --start 日期格式应为 yyyy-MM-dd：本周`，exit 2），须自己换算；`retrieve search/outline` 的 `--occurred-*`/`--effective-*` **收自然语言**（`上季度`、`8 月` 直接传，由服务端解析），`retrieve search` 还会把 `--query` 文本里的时间表达解析为时间窗并在 `time_window` 回显
+
+## 3. 登录与配置
+
+1. 用户在 YOS 客户端「个人设置-访问令牌」页创建并复制令牌（40 位小写 hex）
+2. `yos login` 交互粘贴（不回显）；Agent 代执行时用 `yos login --key <令牌>`（注意令牌会进入 shell 历史，优先让用户自己在终端执行，或用 `YOS_API_KEY`）
+3. 配置文件 `~/.config/yos/config.json`（0600）。三个环境变量**优先于配置文件**：`YOS_CONFIG_DIR`（换配置目录）、`YOS_API_KEY`（换令牌）、`YOS_ENDPOINT`（换端点）
+4. 端点缺省生产环境 `https://yos-bff.linkduoo.com`，切换用 `yos login --endpoint <url>`（本地联调 `http://localhost:8080`）；临时切换可用 `YOS_ENDPOINT`，`yos doctor` 会显示当前生效端点及其来源
+5. 退出码 4 = 令牌无效/已吊销/已过期 → 引导重新 `yos login`，不要反复重试同一命令
+
+## 4. 常用编排（已实测）
+
+```bash
+# 回答公司制度类问题
+yos kb list --scope created --json                        # 需要 kbCode 时
+yos retrieve search '报销标准' --kb KB20261009000001        # 语义检索拿候选与命中行号
+yos retrieve read 'cortex://kb/KB20261009000001/doc/ND20261009000012:1-60'  # 读原文再作答
+
+# 整理知识库
+yos docs tree KB20261009000001                            # 目录树（资源编码字段是 resourceCode）
+yos docs mkdir '会议纪要' --kb KB20261009000001             # 返回新节点编码
+yos kb upload ./报告.pdf --kb KB20261009000001             # 单文件上传（≤20MB，同名时按 --on-conflict 处理）
+yos docs download ND20261009000012 --out ./归档/            # 取回上传的原文件（仅 docType=file）
+yos docs count ND20261009000012                            # 删除前查影响范围
+
+# 会议内容
+yos transcript list --json                                 # 取 transcriptionUserId（不是 TT 开头编码）
+yos transcript detail 2105108032979103745 --json           # 取 summary / sentences
+
+# 帮助与版本
+yos support manual-search '登录'                            # 手册检索
+yos support upgrade --platform MAC_ARM64                    # 客户端最新版
+```
+
+## 5. 输出与兜底
+
+- 默认输出人类可读文本；需要字段时**加 `--json` 再解析**，不要正则刮文本
+- 分页壳不统一：`kb list` / `support upgrade-log` 为 `records` / `total` / `page` / `size`；`transcript list` 为 `list` / `current` / `size` / `pages` / `total`（转写域解析细则见 yos-transcript）
+- 命令报错时先看退出码：`2` 用法错误（CLI 本地拦截，未发请求，按 `提示:` 改参数）、`1` 业务失败（服务端结论，文案里带具体编码，可直接引给用户）、`3` 网络、`4` 鉴权
+- 领域命令找不到对应能力时，`yos tool list` 看全量工具，`yos tool schema <name> --json` 拿完整参数说明（不带 `--json` 会截断描述），再 `yos tool call`

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

@@ -0,0 +1,162 @@
+---
+name: yos-install
+description: 引导用户在本机安装并配置 YOS CLI（环境检查 → npm 全局安装 → 登录访问令牌 → 安装内置 Skill → doctor 验证）。当 yos 命令不存在、yos doctor 未通过、用户说"帮我装 YOS CLI / 配置令牌 / 装不上"时使用。本文件自包含，可单独放到发布仓库供用户下载后完成引导
+---
+
+# YOS CLI 安装与配置引导
+
+目标：让用户本机具备可用的 `yos` 命令，并把 YOS 内置 Skill 装进他正在使用的 AI 工具目录。全程 5 步，用户只需配合一处（在 YOS 客户端取访问令牌）。
+
+本文件**自包含**：不依赖其它 YOS skill 就能完成安装；安装成功后再由 `yos skill install` 把领域能力（知识库、检索、转写、帮助）落到本机。
+
+## 0. 引导纪律
+
+- 一次只执行一步，把该步命令的**输出原文**给用户，再决定下一步；不要连跑多条命令后统一汇报
+- 需要访问令牌时：优先让用户自己在终端输入（`yos login` 的输入不回显）；确需 Agent 代跑时用 `--key`/环境变量，并提醒用户该命令会进入 shell 历史
+- **凭据零外泄**：访问令牌不写进代码仓库、日志、聊天正文或文档；引用时一律掩码（形如 `xxxxxxxx****xxxx`，即原令牌前 8 位 + `****` + 后 4 位）
+- 不擅自改用户的全局配置：写 `~/.npmrc`、改 `npm prefix`、删 skill 目录这类动作先取得用户同意
+- 全程不需要 `sudo`。权限报错按第 7 节处置，不要 `sudo npm install -g`（会把 root 拥有的文件混进全局目录，后续更难维护）
+
+## 1. 环境检查
+
+```bash
+node -v          # 需要 >= 18（package.json engines: ">=18"；低版本会因 ESM/parseArgs 报错）
+npm -v
+command -v yos   # 已有 yos → 跳到第 3 步（登录），不要重复安装
+```
+
+- Node 缺失或 < 18：让用户先装 Node 18+（LTS 均可），装完重开终端确认 `node -v`
+- 已有 `yos` 但版本旧：走第 6 节
+
+## 2. 安装 CLI
+
+```bash
+npm install -g @yosai/cli
+```
+
+装完立刻验证：
+
+```bash
+command -v yos            # 全局 bin 路径
+yos --version             # 输出「yos CLI 0.2.0」即安装成功（等价 yos version）
+yos --help                # 输出「yos - YOS 能力的 Agent 执行入口」
+```
+
+## 3. 登录（唯一需要用户配合的动作）
+
+1. 让用户在 **YOS 客户端「个人设置-访问令牌」页**创建并复制访问令牌：40 位小写十六进制字符串
+2. 用户自己在终端执行（推荐，输入不回显）：
+
+```bash
+yos login
+```
+
+Agent 代跑时改用：
+
+```bash
+yos login --key '<40 位令牌>'
+```
+
+3. 成功输出（原样回给用户即可，`key` 已是掩码）：
+
+```
+已保存配置：endpoint=https://yos-bff.linkduoo.com，key=xxxxxxxx****xxxx，身份 张三（U00000001）
+```
+
+关键语义：
+
+- `login` 会**先调服务端校验身份再落盘**，校验失败不写配置 → 报网络或令牌错时无需清理"半成品"配置，改对参数重跑即可
+- 端点缺省为生产环境 `https://yos-bff.linkduoo.com`。切环境用 `yos login --endpoint <url>`（本地联调 `http://localhost:8080`）；`--endpoint` 不传时沿用配置文件里已有的值
+- 配置文件 `~/.config/yos/config.json`（目录 0700、文件 0600）
+- CI/容器可完全跳过 `login`：`export YOS_API_KEY=<令牌>`、`export YOS_ENDPOINT=<端点>`（两者都优先于配置文件）；`YOS_CONFIG_DIR` 可换配置目录（多环境隔离用）
+
+## 4. 安装内置 Skill 到 AI 工具
+
+```bash
+yos skill install
+```
+
+- 自动探测下列目录，**只对已存在的目录写入**（一台机器可能同时命中多个）：`~/.claude/skills`、`~/.workbuddy/skills`、`~/.cursor/skills`、`~/.codex/skills`、`~/.qoder/skills`、`~/.qoder-cn/skills`、`~/.agentskill`
+- 成功输出（数字随内置 Skill 数量变化）：
+
+```
+已安装 7 个 Skill 到：
+~/.claude/skills
+...
+提示：重启 Agent 工具以确保 Skill 加载
+```
+
+- 没探测到任何目录时：
+
+```
+错误: 未发现已安装的 Agent 技能目录
+提示: 请用 --target <dir> 指定（如 ~/.claude/skills）
+```
+
+  → 问清用户用的是哪个 AI 工具，显式指定：`yos skill install --target ~/.claude/skills`
+- **必须重启该 AI 工具**才会加载 Skill；重启后建议用户问一句「YOS 能帮我做什么」确认已生效
+- 重复执行安全：按目录覆盖同名 Skill，幂等
+- 安装记录写进配置的 `installedSkillDirs`，`yos doctor` 的 Skill 项读的就是这份记录
+
+## 5. 验证
+
+```bash
+yos doctor            # 七项全 ✓ 才算装好
+yos doctor --json     # 需要机器可读结果时（{checks:[{name,ok,detail}]}）
+yos kb list --json    # 端到端实跑一条只读命令收尾
+```
+
+`doctor` 七项与样例：
+
+```
+✓ 配置文件: 已找到
+✓ 服务端点: https://yos-bff.linkduoo.com（来自 内置缺省）
+✓ 访问令牌: xxxxxxxx****xxxx
+✓ 服务连通: 身份 张三（U00000001）
+✓ Skill 安装: ~/.claude/skills
+✓ CLI 版本: 0.2.0（endpoint=https://yos-bff.linkduoo.com）
+✗ Skill 同步: 缺少版本状态（Skill 目录 1 个），执行 yos update 重同步
+```
+
+- 退出码：七项全过 `0`；服务连通失败沿用底层错误（`3` 网络不可达 / `4` 鉴权失败）；其余未通过项为 `2`
+- 「Skill 同步」读的是版本状态文件与 CLI 版本是否一致：`yos update` 或 `yos skill install` 任一跑过即刷新，`✗` 时按 detail 提示执行 `yos update`
+- Skill 项判定读的是**配置里的安装记录**，不是磁盘探测：手工删过 Skill 目录时 `doctor` 仍显示 ✓，有疑问就 `ls ~/.claude/skills/yos/SKILL.md`
+
+## 6. 升级与卸载
+
+```bash
+yos update                            # 推荐：升级到 npmjs 最新版并自动重同步 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` 升级）
+
+卸载（破坏性，逐项取得用户确认后再动手）：
+
+```bash
+npm uninstall -g @yosai/cli
+rm -rf ~/.config/yos                                  # 含访问令牌，删前告知用户
+ls ~/.claude/skills | grep -E '^yos'                   # 先看要删哪些，再删对应目录
+```
+
+## 7. 故障对照表（原文报错 → 处置）
+
+| 看到的原文 | 原因 | 处置 |
+|---|---|---|
+| `command not found: yos` | 未安装，或全局 bin 不在 PATH | 先 `npm ls -g @yosai/cli` 判断是否装上；装上了就查 `npm prefix -g` 的 `/bin` 是否在 PATH，改 `~/.zshrc` 后重开终端 |
+| `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 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` |
+| 装完 Skill 后 AI 工具不认 YOS 能力 | 没重启工具，或 Skill 装到了别的工具目录 | 重启对应工具；`ls` 确认该工具目录下有 `yos/SKILL.md`，必要时 `--target` 重装 |
+
+## 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 doctor`；退出码 `4` 一律重新登录，`3` 先查端点与网络

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

@@ -0,0 +1,388 @@
+---
+name: yos-kb
+description: YOS 知识库与文档管理（kb list/detail/update/upload + docs tree/content/download/count/mkdir/create/update/rename/move/delete/restore）。用户要查资料在哪、上传或整理知识库文档、下载原文件、改名字/移动/删除/恢复时使用；含每条命令的参数、真实输出与报错修法
+---
+
+# YOS 知识库与文档（kb / docs）
+
+两域分工：`kb` 管知识库本体（库级），`docs` 管库内文档与文件夹（节点级）。
+
+## 0. 开工前先拿编码（不要猜）
+
+```bash
+yos kb list --keyword 报销            # → 左列 kbCode，形如 KB20260921000001
+yos kb detail KB20260921000001          # → 确认 role（能否写）与 docCount
+yos docs tree KB20260921000001           # → 节点的 resourceCode（形如 ND20260921000307）与类型
+```
+
+- 编码规律：库 `KB`+yyyyMMdd+6 位序号，节点 `ND`+yyyyMMdd+6 位序号。示例里的 `KBxxx`/`NDxxx` 都是占位，真实调用必须来自上面三条命令
+- 写操作前先确认 `role`：`edit` 才能建/改内容与改名；`admin`/`owner` 才能移动、删除、恢复、改库名
+- `kb list` 不传 `--scope` 时返回**全部可见库**（含他人所有、自己只有 `read` 的库）。用户说「我的知识库」时要显式加 `--scope created`
+
+---
+
+## 1. kb 域
+
+### 1.1 `kb list` — 列知识库
+
+```bash
+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）
+```
+
+| flag | 工具参数 | 取值 | 缺省 |
+|---|---|---|---|
+| `--scope` | `range` | `created` \| `shared` \| `all` | `all` |
+| `--keyword` | `keyword` | 名称关键词 | 无 |
+| `--page` | `page` | ≥1 整数 | 1 |
+| `--size` | `size` | 每页条数，1~50 | 10 |
+
+非法值与越界值一律 exit=2 且不发请求：`--scope mine` → `错误: --scope 取值非法：mine` + `提示: 可选：created / shared / all`；`--size 1000` → `错误: --size 超过上限 50：1000` + `提示: 取值范围 1~50`。
+
+真实输出（`kb list` 是唯一做了表格渲染的命令）：
+
+```
+KB20261009000001  CLI测试-改名验证
+KB20260928000003  AI智能研发部
+KB20260921000001  公司资料
+```
+
+空结果输出 `（无知识库）`，不是空行。
+
+`--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[].docCount` 在 list 里**恒为 `null`**（服务端只 detail 返回）。想知道各库文档数，逐库 `kb detail`，或直接说明拿不到；不要拿 `null` 当「空库」告诉用户。
+
+### 1.2 `kb detail` — 库详情（含角色与文档数）
+
+```bash
+yos kb detail KB20260921000001
+yos kb detail KB20260921000001 --json
+```
+
+输出为服务端 JSON 原文（无人类渲染），字段与 list 单条一致，差别是 `docCount` 有值（实测 `29`）、`role` 有值。
+
+报错：`工具执行失败：知识库不存在：KB不存在`（exit 1，编码原样回显）。
+
+### 1.3 建库 / 删库 —— CLI 不支持，请到客户端手动操作
+
+`kb` 域只有 `list` / `detail` / `update` / `upload` 四个动作。**新建知识库与删除知识库都不在 CLI 与 MCP 工具集内**，不要尝试 `yos kb create` 或 `yos kb delete`：
+
+```bash
+yos kb create 项目资料库
+未知子命令: create 项目资料库
+yos kb - 知识库本体：列表 / 详情 / 更新 / 上传（新建知识库请到 YOS 客户端手动操作）   [exit=2]
+```
+
+**Agent 处理规则**：
+
+- 用户要**新建**知识库 → 直接告知「请在 YOS 客户端『知识库』页手动新建（可选封面与归属配置）」，不要试任何命令；用户建好后用 `yos kb list` 取新库编码，再继续后续的上传/建档动作
+- 用户要**删除**知识库 → 同样只能去客户端；删除不可逆，务必先向用户讲清库内全部文档一并进回收站
+- 用户只是想**清理库内内容** → 这个 CLI 支持：`docs delete <node_code>`（级联进回收站，90 天内可 `docs restore` 恢复），删前先 `docs count` 看影响范围
+
+### 1.4 `kb update` — 改库名/简介
+
+```bash
+yos kb update KB20261010000021 --name 新库名
+yos kb update KB20261010000021 --description 新简介
+yos kb update KB20261010000021 --name 新库名 --description 新简介
+```
+
+`--name`（`kb_name`，≤24 字）与 `--description`（≤80 字）**至少传一个**；都不传 → `错误: --name、--description 至少传一个`（exit 2）；新名称超 24 字 → `错误: 知识库名称超长（实际 25 字，上限 24 字）`（exit 2）。成功输出 `知识库更新成功`。需 `admin` 及以上（通常只有 `owner`）。
+
+### 1.5 `kb upload` — 上传本地文件或整个目录
+
+```bash
+yos kb upload ./报告.pdf --kb KB20260921000001                    # 传到库根目录
+yos kb upload ./报告.pdf --kb KB20260921000001 --dir ND2026...      # 传到指定文件夹
+yos kb upload ./会议纪要 --kb KB20260921000001                       # 整目录递归，镜像子文件夹
+yos kb upload ./会议纪要 --kb KB20260921000001 --on-conflict skip     # 同名跳过
+yos kb upload ./会议纪要 --kb KB20260921000001 --on-conflict rename   # 同名加后缀新建
+yos kb upload ./会议纪要 --kb KB20260921000001 --json                 # 结构化汇总
+```
+
+| 参数 | 说明 |
+|---|---|
+| `<本地文件或目录>` | 必填位置参数，相对/绝对路径都可；不存在 → `错误: 文件或目录不存在：./不存在.pdf`（exit 1） |
+| `--kb` | 必填。漏传 → `错误: 缺少 --kb 知识库编码` + `提示: 可用 \`yos kb list\` 查看知识库编码`（exit 2） |
+| `--dir` | 目标**文件夹**编码，缺省库根。传文档编码会失败 |
+| `--on-conflict` | `skip` \| `rename`；非法值 → `错误: --on-conflict 取值非法：xxx` + `提示: 可选：skip（跳过冲突件）/ rename（加后缀新建）`（exit 2） |
+
+单文件成功输出：`已上传：skillprobe.md（75 字节）→ 节点 ND20261010000032`
+
+单文件的同名处理（与目录一致，冲突只看目标文件夹同层同名节点；单文件不会新建包裹目录）：
+
+```
+不传 --on-conflict 且同名 → 目标位置已存在同名文件，已中止（未上传）：dedup-probe.md
+                            提示: 加 --on-conflict skip 跳过，或 --on-conflict rename 加后缀新建   [exit=1]
+--on-conflict skip   → 已跳过（目标位置已存在同名文件）：dedup-probe.md                          [exit=0]
+--on-conflict rename → 已改名上传：dedup-probe.md → dedup-probe (1).md（62 字节）→ 节点 ND2026...  [exit=0]
+```
+
+`--json` 时：中止输出 `{"aborted":true,"reason":"conflict","fileName":"dedup-probe.md"}`，跳过输出 `{"skipped":true,"fileName":"..."}`，成功输出服务端返回对象（`nodeCode`/`fileName`/`fileSize`）。
+
+整目录（三种冲突策略的真实差异，务必按此预期）：
+
+```
+不传 --on-conflict 且有冲突 → 发现 2 个同名冲突，已中止（未上传任何文件）：
+                              - 项目资料/2026Q3/场景报告.md
+                              提示: 加 --on-conflict skip 跳过冲突件，或 --on-conflict rename 加后缀新建   [exit=1]
+--on-conflict skip   → 上传完成：新建文件夹 0、复用文件夹 1、上传 0、改名 0、跳过 2、失败 0
+--on-conflict rename → 上传完成：新建文件夹 0、复用文件夹 1、上传 2、改名 2、跳过 0、失败 0
+首次整目录上传        → 上传完成：新建文件夹 1、复用文件夹 0、上传 2、改名 0、跳过 0、失败 0
+```
+
+`--json` 时汇总为对象，字段：`foldersCreated` / `foldersReused` / `uploaded` / `renamed` / `skipped` / `failed`（数组）；冲突中止时输出 `{aborted:true, reason:"conflict", ...}`。
+
+硬约束与注意点：
+
+- **单文件 ≤20MB**：`错误: 文件超过 20MB 上限：size=22020096，path=...` + `提示: 更大文件请先在客户端上传后共享，或拆分为多个文件`（exit 1）
+- **服务端不做任何同名去重**：落库节点名恒等于本次上传用的文件名，同名副本会真实堆积并放大 `retrieve grep` 的命中数。同名判定与 `rename` 的新名都由 CLI 侧完成，因此绕过 CLI 直传不会有这层保护
+- 目录上传自动跳过隐藏文件（如 `.DS_Store`），并自动创建缺失的子文件夹（单文件上传不会，需先 `docs mkdir`）
+- 支持类型（以服务端返回为准）：doc/docx/xls/xlsx/ppt/pptx/pdf/md/txt/json/csv/html/png/jpg/jpeg
+- 中文、带空格与 `#` 号、超长文件名均可正常上传并在树里原样显示
+- 上传产生的是 `docType=file` 节点，**正文要用 `retrieve read` 读，`docs content` 读不出来**（见 2.2），取回原文件用 `docs download`（见 2.3）
+
+---
+
+## 2. docs 域
+
+### 2.1 `docs tree` — 目录树
+
+```bash
+yos docs tree KB20260921000001
+yos docs tree KB20260921000001 --json
+```
+
+输出为服务端 JSON 原文（无渲染），结构：
+
+```json
+{"kbCode":"KB20260921000001","children":[{"resourceType":"folder","resourceCode":"ND20260921000163","name":"优先级分类-请删除","docType":"","parseStatus":"NONE","createdBy":"U00000001","creatorName":"张三","createTime":"...","editedBy":"...","editorName":"...","editedAt":"...","fileSize":null,"fileSizeText":null,"fileExt":null,"documentCount":0,"pathOnly":false,"role":"owner","children":[]}]}
+```
+
+字段语义（消费时的关键判据）：
+
+| 字段 | 取值 | 用途 |
+|---|---|---|
+| `resourceType` | `folder` / `doc` / `file` | 决定能否作为 `--parent`/`--dir`（只有 `folder` 可以）；`file` 表示上传的原始文件 |
+| `resourceCode` | `ND...` | **节点编码就在这里，字段名不是 `nodeCode`**（`docs content` 里才叫 `nodeCode`） |
+| `docType` | `md` / `cloud` / `sheet` / `file` / `""` | 正文读取方式判据；`file` → 用 `retrieve read` |
+| `parseStatus` | `NONE` / `READY` / 解析中 | 非 `READY` 的文档检索/读取可能拿不到内容 |
+| `documentCount` | 整数 | 文件夹内文档数（删除影响面的粗判，精确值仍用 `docs count`） |
+| `pathOnly` | bool | `true` 表示该文件夹只是为补全祖先路径出现的，本身无访问权限 |
+| `role` | `owner`/`admin`/`edit`/`read`/`null` | 该节点可写性判据 |
+
+时间字段在树里叫 `editedAt`（`docs content` 是 `updateTime`/`editedAt`，检索结果是 `modifiedAt`/`updatedAt`）——不要跨命令复用字段名。
+
+### 2.2 `docs content` — 读文档标题与正文
+
+```bash
+yos docs content ND20260920004859
+yos docs content ND20260920004859 --json
+```
+
+输出结构：
+
+```json
+{"nodeCode":"ND20260920004859","docType":"cloud","title":"未命名文档","description":"87878","content":"{\"content\":{\"type\":\"doc\",...}}","fileName":"","fileSizeText":"157B","creatorName":"张三","createTime":"...","updateTime":"...","editorName":"...","editedAt":"..."}
+```
+
+- `docType=cloud` 时 `content` 是**云文档草稿 JSON 的字符串**（再次二次解析才拿到结构），`docType=md` 时是 Markdown 原文
+- **`docType=file`（上传的文件）时 `content` 为 `null` 且 exit=0**：不代表文档是空的，此时返回体带 `contentHint`：`上传文件类型无内联正文：用 retrieve_read 读取解析后的文本，或用 docs_download 获取原文件下载地址`。读正文用 `retrieve read 'cortex://kb/<kbCode>/doc/<nodeCode>'`，取原文件用 `docs download`（见 2.3）
+- 传文件夹编码 → `工具执行失败：节点类型不符：ND20260921000163 实际是文件夹，本操作要求文档`（exit 1）；编码不存在或传了 cortex 侧编码（`DOCMTMIO6W87DLS`）→ `工具执行失败：文档不存在：<编码>`（exit 1）
+- 「看目录结构找编码」用 `docs tree`，「读整篇正文」用 `docs content`，「读某一段/为引用取原文」用 `retrieve read`（见 yos-retrieval）
+
+### 2.3 `docs download` — 下载原文件到本地
+
+```bash
+yos docs download ND20261010000032                        # 落到当前目录，用原文件名
+yos docs download ND20261010000032 --out ./归档/           # 已存在的目录 → 目录内按原文件名落盘
+yos docs download ND20261010000032 --out ./本地名.pdf       # 不是目录 → 当成目标文件路径（可改名）
+yos docs download ND20261010000032 --json                  # {"nodeCode","fileName","savedPath","size"}
+```
+
+成功输出：`已下载：报告.pdf → ~/报告.pdf（220200 字节）`（缺失目录会自动创建）。
+
+| 参数 | 说明 |
+|---|---|
+| `<node_code>` | 文档节点编码，且必须是 `docType=file`（`kb upload` 传上去的那种） |
+| `--out` | 保存路径。已是目录 → 目录 + 原文件名；否则视为完整目标文件路径。缺省当前目录 + 原文件名 |
+
+只适用于上传文件类型；云文档与 Markdown 文档没有「原文件」，服务端会回 `工具执行失败：文档未关联可下载文件：ND...`（exit 1）——这类节点要正文用 `docs content` 或 `retrieve read`。
+
+其余失败情形（均 exit 1，文案可直接引给用户）：
+
+```
+工具执行失败：节点类型不符：ND20260921000163 实际是文件夹，本操作要求文档    # 传了文件夹编码
+工具执行失败：文档不存在：ND000000000000000000                          # 编码错或已删除
+工具执行失败：没有该资源的访问权限：DOWNLOAD.ND20261010000032            # 只有 read 角色，无下载权限
+文件下载失败：HTTP 403                                                # 预签名地址过期
+提示: 预签名地址有时效，请重新执行 yos docs download 获取新地址
+```
+
+漏节点编码 → `错误: 缺少文档节点编码` + 用法提示（exit 2）。地址由服务端即时签发、**有时效**，不要把 `downloadUrl` 存下来复用，也不要直接贴给用户（含签名参数）；要给用户文件就下载后走本地路径。
+
+### 2.4 `docs count` — 删除前查影响面（强制前置）
+
+```bash
+yos docs count ND20260921000163
+```
+
+输出：`{"affected_document_count":1}`（文档=1，文件夹=全部子孙文档数）。
+
+节点不存在或已删除 → `节点不存在或已删除: ND99999999999999`（exit 1）。
+
+### 2.5 `docs mkdir` — 建文件夹
+
+```bash
+yos docs mkdir 项目资料 --kb KB20260921000001                    # 根目录下
+yos docs mkdir 2026Q3 --kb KB20260921000001 --parent ND2026...     # 某文件夹下（此时 --kb 可省）
+```
+
+| 参数 | 工具参数 | 约束 |
+|---|---|---|
+| `<文件夹名>` | `folder_name` | 必填位置参数 |
+| `--kb` | `kb_code` | 未传 `--parent` 时必填 |
+| `--parent` | `parent_code` | 必须是 `resourceType=folder` 的编码 |
+
+成功：`文件夹创建成功，节点编码：ND20261010000028`（把该编码用于 `--dir`/`--parent`）。
+
+`--kb` 与 `--parent` 都不传 → `错误: --kb、--parent 至少传一个`（exit 2，不发请求）。需 `edit` 及以上；`--parent` 传文档编码 → `工具执行失败：节点类型不符：<编码> 实际是文档，本操作要求文件夹`（exit 1）。
+
+### 2.6 `docs create` — 建文档
+
+```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 "方案" --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，不是普通文本 |
+
+成功：`文档创建成功，节点编码：ND20261010000030`
+
+漏正文：`错误: 缺少正文内容` + `提示: 用 --content '<文本>' 或 --file <本地文件路径> 提供`（exit 2）
+同时传 content 与 file：`错误: --content 与 --file 互斥` + `提示: 二选一：--content '<文本>' 或 --file <本地文件路径>`（exit 2）
+`--parent` 传了文档编码：`工具执行失败：节点类型不符：ND20261009000001 实际是文档，本操作要求文件夹`（exit 1，先 `docs tree` 确认文件夹编码）
+
+多行、含引号或 shell 特殊字符的正文一律写临时文件走 `--file`，不要用 `--content` 拼字符串。
+
+### 2.7 `docs update` — 改标题/正文/简介
+
+```bash
+yos docs update ND20261010000030 --title 新标题
+yos docs update ND20261010000030 --description 新简介                 # ≤100 字
+yos docs update ND20261010000030 --file ./full_body.md                # 整体替换正文
+```
+
+`--title` / `--content` / `--file` / `--description` 至少传一个，都不传 → `错误: --title、--content/--file、--description 至少传一个`（exit 2）。成功输出 `文档更新成功`。需 `edit` 及以上。
+
+**正文是整体覆盖，不是局部替换**（实测：只回传其中一节，其余三节全部丢失，97 字变 22 字）。CLI 无 append 语义。局部修改的安全流程：
+
+```bash
+yos docs content ND20261010000030 --json     # 1. 取当前完整正文
+#                                        2. 本地改目标段落，其余原样保留
+yos docs update ND20261010000030 --file ./new.md   # 3. 整体回传
+```
+
+改完会触发 cortex 重新解析，检索索引近实时（实测新文档写完即可被 `retrieve search` 命中并排到首位）。
+
+**文档改名只能用 `docs update --title`**；`docs rename` 只用于文件夹，对文档执行 → `工具执行失败：节点类型不符：ND20261010000018 实际是文档，本操作要求文件夹`（exit 1）。
+
+### 2.8 `docs rename` — 文件夹改名/改描述
+
+```bash
+yos docs rename ND20261010000028 项目资料-已整理
+yos docs rename ND20261010000028 项目资料-已整理 --description 该目录存放归档资料
+```
+
+位置参数顺序固定 `<node_code> <新名称>`（`folder_name`）。成功输出 `文件夹重命名成功`。需 `edit` 及以上。仅支持文件夹。
+
+### 2.9 `docs move` — 移动节点
+
+```bash
+yos docs move ND20261010000030 --parent ND20261010000028     # 移入某文件夹
+yos docs move ND20261010000030                               # 不传 --parent = 移到库根目录
+yos docs move ND20261010000030 --parent ND... --prev ND...   # --prev 指定目标位置的相邻前驱，控制排序
+```
+
+成功输出 `节点移动成功`。需 `admin` 及以上。仅单节点，批量整理要多次调用（无原子性、无 dry-run）；`--parent` 必须是文件夹编码：传文档编码 → `工具执行失败：节点类型不符：<编码> 实际是文档，本操作要求文件夹`，编码不存在 → `工具执行失败：文件夹不存在：<编码>`（均 exit 1）。
+
+### 2.10 `docs delete` — 删除（高危）
+
+```bash
+yos docs count ND20261010000028      # 1. 必须先看影响面
+yos docs delete ND20261010000028     # 2. 用户明确确认后才执行
+```
+
+级联删除文件夹的**全部子孙**，进回收站，90 天内可恢复。需 `admin` 及以上；`edit` 角色执行会返回 `没有该资源的访问权限：MOVE_DELETE_RESOURCE.ND20261010000018`（exit 1）。
+
+未确认前执行删除属于越权操作，禁止。节点不存在 → `工具执行失败：节点不存在或已删除: ND000000000000000000`。
+
+### 2.11 `docs restore` — 从回收站恢复
+
+```bash
+yos docs restore ND20261010000028                     # 单个
+yos docs restore ND2026...001 ND2026...002 ND2026...003   # 多个（位置参数变参，≤100 个）
+```
+
+变参自动聚合为 `node_codes` JSON 数组，无需自己写 `[...]`。真实输出：
+
+```
+批量恢复完成：成功 2 个，失败 0 个                                    [exit=0]
+批量恢复完成：成功 0 个，失败 1 个
+失败 ND99999999999999：节点不存在                                    [exit=1]
+批量恢复完成：成功 1 个，失败 1 个
+失败 ND99999999999999：节点不存在                                    [exit=0，部分成功]
+```
+
+**一个都没恢复成功时 exit=1**；**部分成功仍是 exit=0**，所以只要传了多个编码就得解析首行「成功 N 个，失败 M 个」与后续 `失败 <编码>：<原因>` 明细，再向用户报结果。规则：只能恢复 90 天内删除的**顶层删除项**；文件夹会整体恢复其同批次删除的全部子孙（不必也传子节点）；文件夹与其子文件同时传入时服务端自动排序。需 `admin` 及以上。
+
+---
+
+## 3. 常用编排（照抄改编码即可）
+
+**把本地一个目录整理进知识库指定文件夹**
+
+```bash
+yos kb list --keyword 项目资料                      # 拿 kbCode
+yos docs tree KB20260921000001                     # 确认目标位置（同名判定由 upload 自己做）
+yos docs mkdir 项目资料-2026Q3 --kb KB20260921000001  # → ND20261010000028
+yos kb upload ./项目资料 --kb KB20260921000001 --dir ND20261010000028 --json
+```
+
+**把知识库里的上传文件取回本地**
+
+```bash
+yos docs tree KB20260921000001 --json              # 找 docType=file 的节点，取 resourceCode
+yos docs download ND20261010000032 --out ./归档/     # → 已下载：报告.pdf → /…/归档/报告.pdf（220200 字节）
+```
+
+**改一篇文档的某一节**
+
+```bash
+yos docs content ND20261010000030 --json           # 取全文
+# 本地编辑，保留未改动部分
+yos docs update ND20261010000030 --file ./edited.md
+```
+
+**删除前影响面确认（对话模板）**
+
+> 「要删的是 X（`ND...`），`docs count` 显示会影响 N 篇文档，删除后进回收站 90 天内可恢复。确认删除吗？」得到明确「确认」再执行 `yos docs delete ND...`。
+
+## 4. CLI 做不到的事（别反复试）
+
+成员/分享/授权管理、库删除、库归档与可见范围设置、库内查重、按时间排序或筛选变更、文档格式转换（Word→在线文档）、批量移动/重命名、整库一键导出（只能 `docs tree` 拿节点后逐个 `docs download` 自行编排）、清空文件夹保留容器。这些要么走客户端，要么用 `yos support feedback '<诉求>'` 记录。