weaver-work-cli 0.1.24 → 0.1.26

package/skills/weaver-e10-caizhilian/SKILL.md

@@ -5,7 +5,7 @@ display_name_en: Weaver E10 Document Management
 description: "泛微E10采知连知识管理系统Skill，包含多个功能模块，覆盖文档创建/搜索/编辑/比对、附件管理、文件夹操作、参与人与标签管理、文档共享与权限设置、文件存储/备份/加解密/附件设置、FTP/SFTP文件采集、本地文件上传。"
 description_zh: "泛微E10采知连知识管理系统Skill，包含多个功能模块，覆盖文档创建/搜索/编辑/比对、附件管理、文件夹操作、参与人与标签管理、文档共享与权限设置、文件存储/备份/加解密/附件设置、FTP/SFTP文件采集、本地文件上传。"
 description_en: "Weaver E10 document management Skill with multiple functional modules covering document CRUD, attachments, folders, sharing, permissions, file settings, FTP/SFTP collection, and file upload."
-version: 1.1.30
+version: 1.1.34
 author: 泛微网络科技股份有限公司
 agent_created: true
 requires:
@@ -13,14 +13,29 @@ requires:
 cliHelp: "weaver-work-cli caizhilian --help"
 ---
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若共享规则不存在、CLI 未安装或读取失败，说明本技能的必需依赖缺失，必须调用宿主提供的提问/确认弹框，向用户说明必须补齐 `weaver-work-cli` 与共享 skill `weaver-e10-shared`（不补齐本技能无法执行）及补齐计划，并把下面两条待执行命令原样完整展示在确认信息中；Agent 不能在未确认时自行安装。用户明确确认后，Agent 必须直接代为按顺序执行且每条仅执行一次，不得要求或引导用户手动执行：① 缺 CLI 时执行 `npm install -g weaver-work-cli`；② 再执行 `weaver-work-cli skills install shared --target-dir <SKILLS_ROOT>` 装回共享 skill，`<SKILLS_ROOT>` 取本 SKILL.md 所在目录的上一级绝对目录（即与本技能同级的 skills 根目录），不要省略 `--target-dir`——省略会装进默认目录，导致本技能依然读不到共享规则。命令均成功后重新读取共享规则；仍读不到就停止并把结果报告用户，不得凭猜测继续。**
-**`--is-connector` 判据**：用户明确使用连接器、或上下文要求用连接器完成任务 → 传 `true`；本次任务或上下文直接选择单独技能 → 不传；用户没有明确说明时，按**正在运行的这份 Skill 是哪一级**定——**用户级（条目标 `(user)`）不传，连接器级（标 `(connector)`）传**（同名 Skill 只会运行用户级那一份）。传 `true` 时不要再写 `--profile` / `--base-url`。完整规则见 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)。
-
-认证与登录态只能按共享规则通过 `weaver-work-cli auth ...` 判断：本 Skill 不自行发起 HTTP 请求，请求头凭证由 CLI 统一注入，Agent 不手写、不索取、不转存，也不得直接读取、列出、打印或解析用户主目录下的旧 `.e10-cli`、auth、config 或 Keychain 数据。业务入参里出现认证字段会被 CLI 拒绝或剥离。请求头三件套由 CLI 统一注入、缺一不可：Cookie: <完整原始 Cookie 串>（禁止裁剪/去重/改写）、eteamsid: <ETEAMSID>、User-Agent: AgentType=<agentType>,IsAgent=true。完整契约见共享规则「请求头契约」章节。
-
-所有命令通过 `weaver-work-cli --json caizhilian run <operation>` 执行：简单 JSON 优先传 `--input-json '<json>'`，复杂或多行 JSON 先写入 UTF-8 文件再传 `--input <path>`，只有确认当前 shell 能稳定传管道时才使用 `--input -`。**不要写内联脚本包装调用**——自写脚本在中文与 Windows 环境下容易出现编码、转义问题，且脚本报错时无法判断调用是否已生效，容易导致误判或重复提交。调用前先按需读取 references 下对应的文件查参数结构，不要猜字段；**references 是第一信息源**，`weaver-work-cli caizhilian schema` 是 operation、字段和风险等级的合约来源，`weaver-work-cli caizhilian operations` 是按资源分组的能力目录（含 `withheldOperations`）。
-
-命令示例、提示词和临时说明必须同时兼容 Windows 和 macOS/Linux；涉及 JSON 输入、用户目录、路径分隔符、文件上传下载、目录查看或文件比对时，同时给 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例。Agent 先根据当前系统和 shell 选择对应示例，不确定时用 `node -p "process.platform"` 判断。Windows/PowerShell 下不要使用 `printf`、`$HOME/...`、`~/...`、bash 反斜杠续行、`rm/ls/diff/python3` 等 Unix-only 写法。
+**CRITICAL — 开始前先读共享规则**：同级目录存在 `weaver-e10-shared` 技能时，MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)（安装、E10 认证、JSON 输出和高风险写入规则）。
+若共享规则不存在、CLI 未安装或读取失败，说明本技能的必需依赖缺失，必须调用宿主提供的提问/确认弹框，向用户说明必须补齐 `weaver-work-cli` 与共享 skill `weaver-e10-shared`（不补齐本技能无法执行）及补齐计划，并把下面两条待执行命令原样完整展示在确认信息中；Agent 不能在未确认时自行安装。
+用户明确确认后，Agent 必须直接代为按顺序执行且每条仅执行一次，不得要求或引导用户手动执行：① 缺 CLI 时执行 `npm install -g weaver-work-cli`；② 再执行 `weaver-work-cli skills install shared --target-dir <SKILLS_ROOT>` 装回共享 skill，
+`<SKILLS_ROOT>` 取本 SKILL.md 所在目录的上一级绝对目录（即与本技能同级的 skills 根目录），不要省略 `--target-dir`——省略会装进默认目录，
+导致本技能依然读不到共享规则。
+命令均成功后重新读取共享规则；若环境中确实无法补齐共享规则，按本文内置的最小认证指引继续：用 `weaver-work-cli auth status` 查登录态，未登录或失效时请用户提供 E10 登录域名，再执行 `weaver-work-cli auth login --base-url <域名>`，并在结果中告知用户共享规则缺失。
+**`--is-connector` 判据**：用户明确使用连接器、或上下文要求用连接器完成任务 → 传 `true`；本次任务或上下文直接选择单独技能 → 不传；用户没有明确说明时，按**正在运行的这份 Skill 是哪一级**定——**用户级（条目标 `(user)`）不传，连接器级（标 `(connector)`）传**（同名 Skill 只会运行用户级那一份）。
+传 `true` 时不要再写 `--profile` / `--base-url`。
+完整规则见同级 `weaver-e10-shared` 技能的共享规则。
+
+认证与登录态只能按共享规则通过 `weaver-work-cli auth ...` 判断：本 Skill 不自行发起 HTTP 请求，请求头凭证由 CLI 统一注入，Agent 不手写、不索取、不转存，也不得直接读取、列出、打印或解析用户主目录下的旧 `.e10-cli`、auth、config 或 Keychain 数据。业务入参里出现认证字段会被 CLI 拒绝或剥离。
+请求头三件套由 CLI 统一注入、缺一不可：Cookie: <完整原始 Cookie 串>（禁止裁剪/去重/改写）、eteamsid: <ETEAMSID>、
+User-Agent: AgentType=<agentType>,IsAgent=true。
+完整契约见共享规则「请求头契约」章节。
+
+所有命令通过 `weaver-work-cli --json caizhilian run <operation>` 执行：简单 JSON 优先传 `--input-json '<json>'`，复杂或多行 JSON 先写入 UTF-8 文件再传 `--input <path>`，只有确认当前 shell 能稳定传管道时才使用 `--input -`。
+**不要写内联脚本包装调用**——自写脚本在中文与 Windows 环境下容易出现编码、转义问题，且脚本报错时无法判断调用是否已生效，
+容易导致误判或重复提交。
+调用前先按需读取 references 下对应的文件查参数结构，不要猜字段；**references 是第一信息源**，`weaver-work-cli caizhilian schema` 是 operation、字段和风险等级的合约来源，`weaver-work-cli caizhilian operations` 是按资源分组的能力目录（含 `withheldOperations`）。
+
+命令示例、提示词和临时说明必须同时兼容 Windows 和 macOS/Linux；涉及 JSON 输入、用户目录、路径分隔符、文件上传下载、目录查看或文件比对时，同时给 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例。Agent 先根据当前系统和 shell 选择对应示例，不确定时用 `node -p "process.platform"` 判断。
+Windows/PowerShell 下不要使用 `printf`、`$HOME/...`、`~/...`、bash 反斜杠续行、
+`rm/ls/diff/python3` 等 Unix-only 写法。
 
 涉及附件、封面图片、正文文件、本地文件上传或下载落盘的操作，执行前必须提醒用户：文件内容可能被上传到 E10 采知连文档中心或文件服务器、下载内容会写入本地磁盘，并可能进入当前大模型上下文用于理解和处理；必须等待用户明确确认后才继续。
 
@@ -38,7 +53,7 @@ cliHelp: "weaver-work-cli caizhilian --help"
 - 文档权限 / 下载权限 / 复制权限 / 移动权限 / 删除权限 / 新建文档权限 / 新建文件夹权限 / 设置权限 / 按权限反查
 - 文档共享 / 共享给某人某部门 / 取消共享 / 共享级别
 - 标签 / 公共标签 / 个人标签 / 参与人 / 协作者
-- 附件 / 上传附件 / 替换附件 / 下载附件 / 附件转 PDF / 封面 / 封面图
+- 附件 / 上传附件 / 替换附件 / 下载附件 / 附件转 PDF / 附件历史版本 / 封面 / 封面图
 - 文档比对 / 比对链接 / 左右文件对比
 
 **判定规则：** 只要最终动作是对采知连文档或知识库文件夹做查询、创建、编辑、共享、权限设置、标签/参与人维护、附件与封面处理或文档比对，就归 `weaver-e10-caizhilian`。用户处理的是 E10 流程表单、人事、财务、邮件、会议等非文档中心业务时，不使用本 Skill。
@@ -57,7 +72,10 @@ cliHelp: "weaver-work-cli caizhilian --help"
 | 标签增删查、参与人增删查、文档共享增删查 | `caizhilian run caizhilian.tag.*`、`caizhilian.participant.*`、`caizhilian.share.*` | [`collaboration.md`](references/collaboration.md) |
 | 把人名/部门/分部/岗位/角色/客户解析成 ID | `caizhilian run caizhilian.org.search-*`、`caizhilian.user.current` | [`org-browser.md`](references/org-browser.md) |
 | 附件上传/替换/下载（含 PDF 版）、封面上传/设置/移除、文档比对 | `caizhilian run caizhilian.attachment.*`、`caizhilian.cover.*`、`caizhilian.compare.*` | [`files.md`](references/files.md) |
+| 查附件历史版本（按附件 ID 列出该附件的全部历史版本） | `caizhilian run caizhilian.attachment.list-versions` | [`files.md`](references/files.md) |
 | 附件设置（上传最大、格式控制、批量下载等） | `caizhilian run caizhilian.setting-attach.get` / `.set.prepare` / `.set.apply` | [`setting-attach.md`](references/setting-attach.md) |
+| 查某个审批流程的附件上传到哪些文件夹（含各附件字段与通用设置的目录，去重合并） | `caizhilian run caizhilian.setting-attach.list-upload-folders` | [`setting-attach.md`](references/setting-attach.md) |
+| 按名称搜索审批流程（拿流程 ID，供查附件上传目录用） | `caizhilian run caizhilian.setting-attach.search-workflows` | [`setting-attach.md`](references/setting-attach.md) |
 | 备份设置（开关、规则 CRUD、启停） | `caizhilian run caizhilian.setting-backup.get` / `.set.prepare` / `.set.apply` / `.rule.*` | [`setting-backup.md`](references/setting-backup.md) |
 | 加解密设置（8 项配置） | `caizhilian run caizhilian.setting-encrypt.get` / `.set.prepare` / `.set.apply` | [`setting-encrypt.md`](references/setting-encrypt.md) |
 | 存储设置（实例与规则管理） | `caizhilian run caizhilian.setting-storage.instance.*` / `.rule.*` | [`setting-storage.md`](references/setting-storage.md) |
@@ -79,7 +97,10 @@ cliHelp: "weaver-work-cli caizhilian --help"
 - 改文档：`caizhilian.document.get` 取现状 -> `caizhilian.document.update-*.prepare` -> 用户确认 -> `.apply` -> 必要时 `.get` 复核
 - 共享给某人：`caizhilian.org.search-user`（或 department/subcompany/...）取 `id` -> `caizhilian.share.form` 取 `obj_types[].id` 与 `share_level` 合法值 -> `caizhilian.share.add.prepare` -> 用户确认 -> `.apply`
 - 文件夹权限：`caizhilian.folder.permission.form` 取级联参数 -> `caizhilian.folder.permission.list` 看现状 -> `.add` / `.delete` / `.set-auth` 的 prepare -> 用户确认 -> `.apply`
-- 附件：`caizhilian.document.get` 或 `caizhilian.compare.list-file-objects` 取 `attachment_id` -> `caizhilian.attachment.upload｜replace.prepare` -> 用户确认 -> `.apply`；下载用 `caizhilian.attachment.download`（需要 PDF 版用 `.download-as-pdf`）
+- 附件：`caizhilian.document.get` 或 `caizhilian.compare.list-file-objects` 取 `attachment_id` -> `caizhilian.attachment.upload｜replace.prepare` -> 用户确认 -> `.apply`；
+  下载用 `caizhilian.attachment.download`（需要 PDF 版用 `.download-as-pdf`）
+- 附件历史版本：`caizhilian.attachment.list-versions` 直接按 `attachment_id` 查询（`doc_id` 可选）
+- 查流程附件上传目录：用户只给流程名称时先 `caizhilian.setting-attach.search-workflows` 拿流程 ID，再 `caizhilian.setting-attach.list-upload-folders` 查目录
 - 文档比对：`caizhilian.compare.search-documents` / `.list-file-objects`（本地文件用 `.upload-file`）取左右 `file_id` -> `caizhilian.compare.submit.prepare` -> 用户确认 -> `.apply` -> 把 `compare_link` 交给用户
 - 写操作通用：只读定位 -> `prepare` -> 向用户摘要并取得明确确认 -> `apply`（入参与 prepare 逐字一致 + `--continuation` + `--yes`）
 
@@ -114,7 +135,9 @@ cliHelp: "weaver-work-cli caizhilian --help"
 - 失败后先看进程退出码、`error.type`、`error.subtype` 和 `error.message`。
 - **除非错误明确提示可恢复或需要补充参数，否则不要重复刷同一个 operation。**
 - 写请求已经发出后遇到结果不确定必须停止；不要把 `.apply` 当成可重试的读操作。
-- **错误为 `authentication` 或 `session_expired` 时：立即停止当前操作，不要用示例占位域名或自行猜域名登录，也不要盲目重试。** 先读取共享规则 `../weaver-e10-shared/references/e10-auth-and-session.md`，按其中流程让用户输入 E10 登录域名或选择已有 profile，完成登录后再从 `prepare` 重新开始。
+- **错误为 `authentication` 或 `session_expired` 时：立即停止当前操作，不要用示例占位域名或自行猜域名登录，也不要盲目重试。** 先按共享规则的认证流程处理（同级 `weaver-e10-shared` 技能）：让用户输入 E10 登录域名或选择已有 profile，完成登录后再从 `prepare` 重新开始；共享规则不可用时，
+  直接请用户提供 E10 登录域名，
+  用 `weaver-work-cli auth login --base-url <域名>` 完成登录。
 - `continuation_*` / `plan_changed` / `file_changed` 一律重新 prepare，不要试图修改票据或只改 apply 入参。
 - **明确的业务错误直接转达，不要深挖**：服务端返回的业务提示（如「该附件不支持转为 PDF」「无该文档的共享权限」）是权威结论，直接转述给用户并给出应对建议；不要翻查源码、写调试脚本或追查原始响应找「为什么」。只有错误提示本身含糊（空 message、`INTERNAL_ERROR`）时才进一步诊断。
 - **不要编造失败原因**：不了解真实原因时，直接说明并请用户联系文档负责人或管理员确认；禁止推测平台行为、杜撰因果关系（如「加了附件后权限会变」），也不要替用户断言其本地环境或文件状态。转达时用用户能理解的自然语言，不要把技术字段名、状态码原样抛给用户。
@@ -122,7 +145,9 @@ cliHelp: "weaver-work-cli caizhilian --help"
 
 ### 5) 附件、图片和文件解析确认
 
-- 执行 `caizhilian.attachment.upload｜replace`、`caizhilian.attachment.download｜download-as-pdf`、`caizhilian.cover.upload｜set`、`caizhilian.compare.upload-file`、`caizhilian.document.create-office｜create-by-upload｜replace-content`，或任何会读取本地文件、上传文件内容、下载落盘、解析图片/PDF/Office 的步骤前，必须先提醒用户：文件内容可能进入大模型上下文，也可能发送到 E10 采知连文档中心或文件服务器，或写入本地磁盘。
+- 执行 `caizhilian.attachment.upload｜replace`、`caizhilian.attachment.download｜download-as-pdf`、`caizhilian.cover.upload｜set`、`caizhilian.compare.upload-file`、
+  `caizhilian.document.create-office｜create-by-upload｜replace-content`，或任何会读取本地文件、上传文件内容、下载落盘、解析图片/PDF/Office 的步骤前，必须先提醒用户：文件内容可能进入大模型上下文，也可能发送到 E10 采知连文档中心或文件服务器，
+  或写入本地磁盘。
 - 用户未明确确认前，不要运行上传、下载或解析命令；确认摘要必须包含文件路径、文件名与大小。
 - 下载只在用户指定路径写入，同名文件按 `名称(1).扩展名` 自动改名，不覆盖已有文件。
 
@@ -175,7 +200,8 @@ cliHelp: "weaver-work-cli caizhilian --help"
    - 多步写入（`cover.set` = 上传 + 改字段，`document.replace-content` = 上传 + 替换 + 通知，`document.create-by-upload` = 批量上传）可能只完成了前几步；
    - 批量类操作可能部分成功，`data.summary` 与 `warnings` 里已有成功/失败计数；
    - continuation、目标对象、本地文件或登录上下文可能已经变化。
-3. 如需确认，只补 **一次** 只读查询（`document.search` / `document.get` / `folder.query-by-name` / `permission.list` / `tag.list` / `participant.list` / `share.list` / `compare.list-file-objects`），不要陷入 query/write 循环。
+3. 如需确认，只补 **一次** 只读查询（`document.search` / `document.get` / `folder.query-by-name` / `permission.list` / `tag.list` / `participant.list` / `share.list` / `compare.list-file-objects`），
+  不要陷入 query/write 循环。
 4. 最终给用户明确结论、已知状态、成功/失败项和下一步人工确认建议；未生效且需要重做时，从 `prepare` 重新开始并再次取得确认。
 
 **特别注意：** 附件上传与文档创建最容易因重复提交造成重复入库，更要严格执行上述规则。
@@ -216,7 +242,8 @@ weaver-work-cli --json caizhilian run caizhilian.attachment.download --input-jso
 - 禁止 curl、fetch、浏览器自动化或直接访问 E10 `/api/doc/**`、`/api/file/**`、`/api/hrm/**`、`/api/crm/**`。
 - 禁止读取或复制 CLI runtime 内部 Token、Cookie、ETEAMSID。
 - 禁止读取、列出、打印或解析用户主目录下的旧 `.e10-cli`、auth、config 或 Keychain 数据。
-- 环境列表、配置快照、配置重载、环境切换（源 `list_systems` / `get_loaded_config` / `reload_config` / `switch_config`）不在本模块，改用 `weaver-work-cli config ...` 与 `weaver-work-cli e10 auth ...`，详见 [`withheld.md`](references/withheld.md)。
-- 源 Skill 目录内的系统设置（备份/加密/附件全局设置/存储）、文件收集、文件上传等模块已纳入本 CLI。
+- 环境列表、配置快照、配置重载、环境切换不在本模块（属 withheld 能力），改用 `weaver-work-cli config ...` 与 `weaver-work-cli e10 auth ...`，
+  详见 [`withheld.md`](references/withheld.md)。
+- 系统设置（备份/加密/附件全局设置/存储）、文件收集、文件上传等模块已纳入本 CLI。
 - 文档版本回滚、文档审批流转、全文检索高级语法、回收站还原等能力当前未纳入 CLI manifest，需要在 E10 页面操作。
 - 非文档中心类 E10 能力（流程、人事、财务、邮件、会议等）不由本 Skill 承载。

package/skills/weaver-e10-caizhilian/references/agent-entry.md

@@ -13,7 +13,8 @@
 - 简单 JSON 优先 `--input-json '<json>'`；多行或含中文引号的复杂 JSON 先写成 UTF-8 文件再 `--input <path>`；只有确认当前 shell 管道稳定时才用 `--input -`。
 - `--input` 与 `--input-json` 不能同时传，否则 `validation/input_conflict`。
 - 字段名必须与 `caizhilian schema` 完全一致：多传字段报 `validation/unknown_field`，入参不是对象报 `validation/input_not_object`，出现 `__proto__` / `constructor` / `prototype` 报 `validation/forbidden_key`。
-- ID 类字段（`doc_id`、`folder_id`、`user_id` 等）统一是纯数字字符串，**一律用字符串传**（如 `"5818986505368959471"`）：19 位 ID 写成 JSON 数字会在解析阶段被截断，查不到却看不出原因；超出安全整数范围的数字入参直接报 `validation/number_out_of_range`。不是数字报 `validation/id_invalid`。
+- ID 类字段（`doc_id`、`folder_id`、`user_id` 等）统一是纯数字字符串，**一律用字符串传**（如 `"5818986505368959471"`）：19 位 ID 写成 JSON 数字会在解析阶段被截断，查不到却看不出原因；超出安全整数范围的数字入参直接报 `validation/number_out_of_range`。
+  不是数字报 `validation/id_invalid`。
 - 分页统一 `page_no`（1 起）+ `page_size`；`<=0` 报 `validation/number_invalid`。返回的 `has_next` 按「本页条数 >= page_size」判定，不要依赖 `total`。
 - 业务入参禁止携带 Cookie、ETEAMSID、Token、Authorization 或任何内部控制字段；认证只通过 `weaver-work-cli auth ...`，CLI 运行时会剥离保留请求头。
 - 写操作 `.apply` 额外必须传 `confirm: true`（CLI 用 `--yes`）与 `continuation`（CLI 用 `--continuation <token>`）。
@@ -73,7 +74,10 @@ weaver-work-cli --json caizhilian run caizhilian.document.search --input ./searc
 ```
 
 - `data` 是业务结果；`meta` 只在有上下文时出现（例如 prepare 的 `status: "PREPARED"`、下载的 `doc_id` / `attachment_id`、`health` 的 `profile` / `tenantKey`）。
-- `caizhilian health`（`caizhilian.system.health`）返回 `{ environment, healthy, base_url, url, status_code, business_code, diagnosis, elapsed_ms, message? }`：`healthy=false` 时按 `diagnosis` 定位原因（`network_error` / `http_error` / `http_status_mismatch` / `business_code_mismatch` / `request_failed`，多项用逗号连接），`ok` 表示各项正常；未登录时改为报 `authentication/session_unavailable`，先按共享规则完成登录。
+- `caizhilian health`（`caizhilian.system.health`）返回 `{ environment, healthy, base_url, url, status_code, business_code, diagnosis, elapsed_ms, message? }`：
+  `healthy=false` 时按 `diagnosis` 定位原因（`network_error` / `http_error` / `http_status_mismatch` / `business_code_mismatch` / `request_failed`，多项用逗号连接），
+  `ok` 表示各项正常；
+  未登录时改为报 `authentication/session_unavailable`，先按共享规则完成登录。
 - `warnings` 是非阻断提醒（共享兜底被覆盖、只读回查发现差异、批量上传部分失败等），必须原样转述给用户，不要静默丢弃。
 - 当前输出层只有完整 JSON，没有 `--jq` / `--format table` / `--page-all`。回复时不要原样贴完整 JSON：先摘要关键字段与条数，列表默认小页（`page_size=10`），需要完整内容时落本地文件再给路径。
 
@@ -103,4 +107,4 @@ weaver-work-cli --json caizhilian run caizhilian.document.search --input ./searc
 | `api/http_error` | HTTP 非 2xx | 把 `code` 与 message 交给用户，写操作不要重复提交 |
 | `api/business_error` | 业务失败（code != 200） | 原样转述服务端 message，判断是否需要换参数 |
 | `confirmation/required` | apply 缺 `confirm` | 先向用户摘要并确认，再加 `--yes` |
-| `partial/write_uncertain` | 写结果不确定 | 立即停止，最多补一次只读回查，禁止自动重放 |
+| `partial/write_uncertain` | 写结果不确定 | 立即停止，最多补一次只读回查，禁止自动重放 |

package/skills/weaver-e10-caizhilian/references/collaboration.md

@@ -78,11 +78,13 @@ weaver-work-cli --json caizhilian run caizhilian.share.add.prepare --input-json
 
 - `tag.search` / `tag.list` 返回归一后的 `{ id, name, privacy }`，回复时只展示标签名，`id` 留给后续 `tag.add` / `tag.remove`。
 - `tag.add.apply` / `tag.remove.apply` 返回 `{ doc_id, tag_ids, count }`；标签是**批量两次请求**（公共组 + 个人组），部分组失败会抛错，此时不要自动重放，先用 `tag.list` 回查实际结果。
-- `participant.list` 返回 `{ participants[] }`，每项含 `share_entry_id`、`user_id`、`user_name`、`can_delete`；`participant.add.apply` 返回 `{ share_entry_id, doc_id, user_id, user_name }`，`participant.remove.apply` 返回 `{ share_entry_id, doc_id }`。
+- `participant.list` 返回 `{ participants[] }`，每项含 `share_entry_id`、`user_id`、`user_name`、`can_delete`；`participant.add.apply` 返回 `{ share_entry_id, doc_id, user_id, user_name }`，
+  `participant.remove.apply` 返回 `{ share_entry_id, doc_id }`。
 - `share.list` → `{ add_visible, shares[] }`，条目含 `id`、`object_type`、`object_name`、`share_level`、`sec_level`、`download`、`can_delete`；`share.delete.apply` 返回 `{ deleted: true, shares[] }`。
 - `share.form` → `{ obj_types[], param_options }`，`obj_types[].id` 是 `obj_type` 的合法取值。
 - `participant.list` / `share.list` 默认用 Markdown 表格摘要（姓名/类型/是否可下载/是否可删除），条目 ID 只作为入参。
-- `share.add.apply` 有两种成功形态：`{ added: true, shares: [...] }`（新增成功并回读列表）与 `{ added: false, message: "..." }`（服务端判定「已存在」，源用 `code=500 + status=true` 表达）。`added:false` 不是失败，必须把 message 转述给用户；其他业务失败会抛 `api/business_error`。
+- `share.add.apply` 有两种成功形态：`{ added: true, shares: [...] }`（新增成功并回读列表）与 `{ added: false, message: "..." }`（服务端判定「已存在」，源用 `code=500 + status=true` 表达）。`added:false` 不是失败，必须把 message 转述给用户；
+  其他业务失败会抛 `api/business_error`。
 - `share.add.apply` 成功后回读共享列表失败时仍算成功，只是 `shares` 为空数组——这种情况要提示用户稍后自行复核。
 - 所有 prepare 返回 `continuation` + `expires_in_ms` + `hint`，`meta.status = "PREPARED"`。
 
@@ -109,4 +111,4 @@ weaver-work-cli --json caizhilian run caizhilian.share.add.prepare --input-json
 | `empty_response` / `response_shape` | 服务端返回结构与预期不符 | 停止，把原始 message 交给用户，不要重放写请求 |
 | `plan_changed` | prepare 与 apply 之间请求体指纹变化（表单级联或共享条目已变） | 重新 prepare |
 | `continuation_*` | 票据缺失/过期/串用/入参漂移 | 见 `write-protocol.md` |
-| `partial/write_uncertain` | 写结果不确定 | 立即停止，最多补一次 `tag.list` / `participant.list` / `share.list` 只读回查 |
+| `partial/write_uncertain` | 写结果不确定 | 立即停止，最多补一次 `tag.list` / `participant.list` / `share.list` 只读回查 |

package/skills/weaver-e10-caizhilian/references/document.md

@@ -18,7 +18,9 @@
 
 - `folder_id` 的根节点约定：`100`=系统、`200`=公共、`300`=个人；具体子文件夹 ID 用 `caizhilian.folder.query-by-name` 查。
 - `include_sub_folder` 只在传了 `folder_id` 时才写入请求体，不传 `folder_id` 时该字段无效。
-- `create_time` 支持枚举 `today` / `yesterday` / `this_week` / `last_week` / `this_month` / `last_month` / `this_year` / `last_year` / `last_7_days` / `last_30_days` / `last_90_days`，也支持 `last_<N>_days` 和显式区间 `YYYY-MM-DD HH:MM~YYYY-MM-DD HH:MM`；无法解析报 `validation/time_range_invalid`。区间按东八区计算。
+- `create_time` 支持枚举 `today` / `yesterday` / `this_week` / `last_week` / `this_month` / `last_month` / `this_year` / `last_year` / `last_7_days` / `last_30_days` / `last_90_days`，
+  也支持 `last_<N>_days` 和显式区间 `YYYY-MM-DD HH:MM~YYYY-MM-DD HH:MM`；
+  无法解析报 `validation/time_range_invalid`。区间按东八区计算。
 - `caizhilian.user.current` 返回当前登录人的 `employeeId` / `employeeName`，创建文档缺 `author_id` 时可先取它。
 
 ### 创建文档
@@ -30,12 +32,15 @@
 | `caizhilian.document.create-office` | `file_path`、`folder_id`、`folder_type`、`author_id` | 只接受 `.doc/.docx/.xls/.xlsx/.ppt/.pptx`；`name` 缺省取文件名（不含扩展名） |
 | `caizhilian.document.create-by-upload` | `file_paths`、`folder_id`、`folder_type` | `author_id` 缺省取当前登录人；`file_paths` 接受字符串或数组，去重保序，最多并发 8 个 |
 
-公共可选字段：`participant_ids`、`abstract_text`、`keywords`、`auto_invalidate_date`（`YYYY-MM-DD`）、`tags`、`virtual_folder_ids`、`doc_category`（`0`=普通，`1`=重要）、`cover_picture_id`（`create-by-upload` 无 `cover_picture_id`）。
+公共可选字段：`participant_ids`、`abstract_text`、`keywords`、`auto_invalidate_date`（`YYYY-MM-DD`）、`tags`、`virtual_folder_ids`、`doc_category`（`0`=普通，`1`=重要）、
+`cover_picture_id`（`create-by-upload` 无 `cover_picture_id`）。
 
 - `folder_type` 枚举：`company`=公共、`privy`=个人、`sys`=系统。
 - `tags` 元素是对象，形如 `{"id":"1","privacy":false}`；`id` 用 `caizhilian.tag.search` 查。
 - Markdown 文件按 UTF-8 严格解码，失败回退 GBK，两者都失败报 `validation/file_encoding_unknown`。
-- **1:1 保留源行为（重要）**：`create-html` / `create-markdown` / `create-office` 的 prepare 会并发做「文件夹创建权限校验 + 文件夹默认值兜底 + 默认共享兜底」，但源逻辑让**共享兜底结果覆盖文件夹兜底结果**，所以这三个操作实际不会把文件夹默认的 `participant_ids` / `virtual_folder_ids` 回填进请求体；被丢弃时 prepare 会在 `warnings` 里明确提示。需要生效请显式传这两个字段，或改用 `caizhilian.document.create-by-upload`（不做共享兜底，文件夹默认值会回填）。
+- **1:1 保留源行为（重要）**：`create-html` / `create-markdown` / `create-office` 的 prepare 会并发做「文件夹创建权限校验 + 文件夹默认值兜底 + 默认共享兜底」，但源逻辑让**共享兜底结果覆盖文件夹兜底结果**，
+  所以这三个操作实际不会把文件夹默认的 `participant_ids` / `virtual_folder_ids` 回填进请求体；
+  被丢弃时 prepare 会在 `warnings` 里明确提示。需要生效请显式传这两个字段，或改用 `caizhilian.document.create-by-upload`（不做共享兜底，文件夹默认值会回填）。
 
 ### 编辑文档
 
@@ -76,16 +81,33 @@ weaver-work-cli --json caizhilian run caizhilian.document.update-field.prepare -
 
 ## 输出处理
 
-- `document.search` 返回 `{ total, page_no, page_size, has_next, documents[] }`；每条含 `id`、`name`、`docCreateTime`、`docLastUpdateTime`、`docAuthorId/Name`、`docCreatorId/Name`、`folderPathName`、`belongFolderIds`、`type`、`size`、`docStatus`、`docStatusName`。回复默认用 Markdown 表格展示序号/标题/作者/所属文件夹/更新时间，`id` 只作为后续 operation 入参，不当作展示内容。
-- `document.get` 返回文档基础信息：`docName`（名称）、`abstractText`（摘要）、`authorId`/`authorName`（负责人）、`creatorId`/`creatorName`（创建者）、`docStatus`（状态码）、`keywords`、`summary`（HTML 正文摘要）、`createTime`、`lastUpdateTime`、`contentMainType`/`content`（正文文件 ID）/`contentType`（如 WORD / EXCEL / PPT / PDF）、`coordinate`（1=协同文档）、`parentFolders[]`（`id`/`name`/`namePath`/`type`）、`attachments[]`（`id`/`name`/`extName`/`size`（bytes）/`createTime`）、`permission`（操作权限标志：`withEditPermission`、`canEditTitle`、`canEditContent`、`canDelete`、`canDownload`、`canMove`、`canUploadFile`、`maxSize`（MB）、`replaceMainText` 等）、`operateMenuSettings[]`（可用操作菜单，仅保留 `show=true` 且 `openStatus=1` 的项）。字段较多时只摘要用户关心的部分；写操作前可用 `permission` 判断当前用户是否被允许，不要凭猜测。
-- 创建类 `prepare` 返回 `data` 里的预览（`doc_type`、`content_type`、`name`、`folder_id`、`folder_type`、`author_id`、`content_length`、`tags_count`、`participant_ids`、`virtual_folder_ids`、`doc_share_list_count`、`request`）+ `continuation` + `expires_in_ms` + `hint`，`meta.status = "PREPARED"`。向用户摘要时给出标题、目标文件夹、作者、正文长度和将要产生的副作用。
-- 创建类 `apply` 返回 `{ doc_id }`（新文档 ID，可用 `document.get` 复核）；`create-office.apply` 额外带 `file_id`；`create-by-upload.apply` 批量时返回 `{ results[], summary: { total, success, failed } }`，单文件时返回 `{ doc_id, file_id, name, size, ext_name }`（`meta.batch=false`）；单个文件失败会写进 `results[].error` 和 `warnings`，不要当成整体失败重试。
-- 编辑类 `apply` 返回变更回显：`update-field` → `{ doc_id, <field 对应字段名>: 新值 }`（`name` / `keywords` / `abstract_text` / `auto_invalidate_date`）；`update-author` → `{ doc_id, user_id }`；`update-html` → `{ doc_id, summary }`；`replace-content` → 上传结果 `{ file_id, name, size, ext_name, version }`（`meta` 带 `doc_id` / `content_type`）。
+- `document.search` 返回 `{ total, page_no, page_size, has_next, documents[] }`；每条含 `id`、`name`、`docCreateTime`、`docLastUpdateTime`、`docAuthorId/Name`、`docCreatorId/Name`、`folderPathName`、
+  `belongFolderIds`、`type`、`size`、`docStatus`、
+  `docStatusName`。
+  回复默认用 Markdown 表格展示序号/标题/作者/所属文件夹/更新时间，`id` 只作为后续 operation 入参，不当作展示内容。
+- `document.get` 返回文档基础信息：`docName`（名称）、`abstractText`（摘要）、`authorId`/`authorName`（负责人）、`creatorId`/`creatorName`（创建者）、`docStatus`（状态码）、`keywords`、`summary`（HTML 正文摘要）、`createTime`、`lastUpdateTime`、
+  `contentMainType`/`content`（正文文件 ID）/`contentType`（如 WORD / EXCEL / PPT / PDF）、`coordinate`（1=协同文档）、`parentFolders[]`（`id`/`name`/`namePath`/`type`）、
+  `attachments[]`（`id`/`name`/`extName`/`size`（bytes）/`createTime`）、`permission`（操作权限标志：`withEditPermission`、`canEditTitle`、`canEditContent`、`canDelete`、`canDownload`、`canMove`、`canUploadFile`、
+  `maxSize`（MB）、`replaceMainText` 等）、`operateMenuSettings[]`（可用操作菜单，
+  仅保留 `show=true` 且 `openStatus=1` 的项）。
+  字段较多时只摘要用户关心的部分；写操作前可用 `permission` 判断当前用户是否被允许，不要凭猜测。
+- 创建类 `prepare` 返回 `data` 里的预览（`doc_type`、`content_type`、`name`、`folder_id`、`folder_type`、`author_id`、`content_length`、`tags_count`、`participant_ids`、`virtual_folder_ids`、`doc_share_list_count`、
+  `request`）+ `continuation` + `expires_in_ms` + `hint`，
+  `meta.status = "PREPARED"`。
+  向用户摘要时给出标题、目标文件夹、作者、正文长度和将要产生的副作用。
+- 创建类 `apply` 返回 `{ doc_id }`（新文档 ID，可用 `document.get` 复核）；`create-office.apply` 额外带 `file_id`；`create-by-upload.apply` 批量时返回 `{ results[], summary: { total, success, failed } }`，
+  单文件时返回 `{ doc_id, file_id, name, size, ext_name }`（`meta.batch=false`）；
+  单个文件失败会写进 `results[].error` 和 `warnings`，不要当成整体失败重试。
+- 编辑类 `apply` 返回变更回显：`update-field` → `{ doc_id, <field 对应字段名>: 新值 }`（`name` / `keywords` / `abstract_text` / `auto_invalidate_date`）；`update-author` → `{ doc_id, user_id }`；
+  `update-html` → `{ doc_id, summary }`；
+  `replace-content` → 上传结果 `{ file_id, name, size, ext_name, version }`（`meta` 带 `doc_id` / `content_type`）。
 
 ## 注意
 
-- 创建和编辑文档都是服务端写操作：`create-html` / `create-markdown` / `update-field` / `update-author` / `update-html` 是 `high-risk-write`，`create-office` / `create-by-upload` / `replace-content` 是 `read-with-upload`（会读本地文件并上传）。
-- 创建文档前，服务端会校验**目标文件夹的新建文档权限与允许的文档类型**（合约中以 `permissions` 标记为 `folder.create-document`）：无权限或类型不允许时返回 `folder_no_create_permission` / `doc_type_not_allowed`，原样转述给用户，不要重试；需要提前确认时用 `caizhilian.folder.permission.query`。
+- 创建和编辑文档都是服务端写操作：`create-html` / `create-markdown` / `update-field` / `update-author` / `update-html` 是 `high-risk-write`，
+  `create-office` / `create-by-upload` / `replace-content` 是 `read-with-upload`（会读本地文件并上传）。
+- 创建文档前，服务端会校验**目标文件夹的新建文档权限与允许的文档类型**（合约中以 `permissions` 标记为 `folder.create-document`）：无权限或类型不允许时返回 `folder_no_create_permission` / `doc_type_not_allowed`，原样转述给用户，不要重试；
+  需要提前确认时用 `caizhilian.folder.permission.query`。
 - 执行任何读本地文件、上传文件、替换正文的操作前，必须先提醒用户：文件内容会被上传到 E10 采知连文档中心或文件服务器，并可能进入大模型上下文用于理解和处理；必须等用户明确确认后再继续。
 - `update-html` 会生成新版本，`replace-content` 会替换正文文件；两者都不可撤销，确认摘要里必须写明目标 `doc_id` 与文档标题。
 - 不要为了「补全信息」自动多查一遍：用户已给 `doc_id` 时直接 `document.get` 或对应 `prepare`。
@@ -108,4 +130,4 @@ weaver-work-cli --json caizhilian run caizhilian.document.update-field.prepare -
 | `doc_info_unavailable` | 目标文档信息取不到 | 用 `document.get` 复核 `doc_id` |
 | `plan_changed` | prepare 与 apply 之间文件内容/元信息变化 | 重新 prepare |
 | `api/business_error` | 服务端业务失败 | 转述 message，不要重复提交写请求 |
-| `partial/write_uncertain` | 创建/替换结果不确定 | 立即停止，最多补一次 `document.search` 或 `document.get` 只读回查，禁止自动重放 |
+| `partial/write_uncertain` | 创建/替换结果不确定 | 立即停止，最多补一次 `document.search` 或 `document.get` 只读回查，禁止自动重放 |

package/skills/weaver-e10-caizhilian/references/file-collection.md

@@ -13,13 +13,13 @@ metadata:
 
 # 文件采集 FTP/SFTP
 
-本 Skill 通过 `scripts/collection_cli_tool.py` 管理文件采集生命周期。正式 API 请求、动作流设计物化和任务 Payload 均由脚本生成，不手写正式结构。
+本模块通过 CLI 管理文件采集生命周期。正式 API 请求、动作流设计物化和任务 Payload 均由 CLI 生成，不手写正式结构。
 
 ## 前置依赖
 
 ### 认证前置（必须）
 
-本模块通过 CLI 托管的认证获取凭证（base_url + Cookie + eteamsid + User-Agent），凭证契约见共享规则 [`../../weaver-e10-shared/SKILL.md`](../../weaver-e10-shared/SKILL.md)，不依赖手动配置文件，Agent 不得自己读取或输出凭证。
+本模块通过 CLI 托管的认证获取凭证（base_url + Cookie + eteamsid + User-Agent），凭证契约见同级 `weaver-e10-shared` 技能的共享规则，不依赖手动配置文件，Agent 不得自己读取或输出凭证。
 
 **使用前必须确保**：
 1. CLI 已安装：`weaver-work-cli --version` 能正常输出版本号
@@ -68,7 +68,8 @@ weaver-work-cli auth set --eteamsid "PCACCOUNT_xxx"
 2. 执行 `choose-file-only --phase collection_target_selection`；或执行 `choose-archive`，再调用全宗工具、`normalize-fonds` 和 `confirm-fonds`。
 3. 执行 `choose-new-task` 或 `choose-existing-task`。已有任务的全宗更新仅适用于归档分支。
 4. 新建任务时执行 `choose-existing-resource` 或 `create-new-resource`；标准新建直接调用 `create-ftp-resource`，缺少 `systemPk` 时 CLI 内部创建连接器并返回 `taskSourceId`。
-5. 确定 `retainDirStruct=0|1`；执行 `choose-existing-workflow` 后 `search-action-flows`、用户确认、`inspect-action-flow --retain-dir-struct <0|1>`；或执行 `create-new-workflow` 后直接调用标准 `create-action-flow --retain-dir-struct <0|1> [--archive]`。
+5. 确定 `retainDirStruct=0|1`；执行 `choose-existing-workflow` 后 `search-action-flows`、用户确认、`inspect-action-flow --retain-dir-struct <0|1>`；
+  或执行 `create-new-workflow` 后直接调用标准 `create-action-flow --retain-dir-struct <0|1> [--archive]`。
 6. 用相同目录选项和关联凭据执行 `save-task --retain-dir-struct <0|1> --source-id ... --workflow-selection-file ...`；归档分支额外传全宗确认文件。
 7. 依次执行 `check-storage`、`scan --wait`、`run`；需要等待文件级结果时使用 `run --wait` 或 `run-progress`。
 

package/skills/weaver-e10-caizhilian/references/file-upload.md

@@ -6,9 +6,8 @@
 
 ## 运行与认证
 
-- 唯一运行时为 `weaver-work-cli`；源码位于 `src/shortcuts/caizhilian/file-upload/`，
-  操作入口位于 `src/shortcuts/caizhilian/operations/handlers/file-upload.ts`。
-- 安装与登录遵守 `../../weaver-e10-shared/SKILL.md`。认证只使用 CLI 当前身份或连接器注入的身份。
+- 唯一运行时为 `weaver-work-cli`，全部操作由 CLI 提供。
+- 安装与登录遵守同级 `weaver-e10-shared` 技能的共享规则。认证只使用 CLI 当前身份或连接器注入的身份。
 - 本模块不执行独立 Skill 的 `dist/weaver-file-upload.js`，不复用 `e10-login` 的会话，
   不启动第二套 Chrome 登录；独立 Skill 的双登录模式不属于本 CLI 上传接口。
 - 缺少会话或登录失效时按共享规则处理，不自行切换账号或环境。

package/skills/weaver-e10-caizhilian/references/files.md

@@ -26,6 +26,18 @@
 - 下载单文件上限 **100MB**，超限报 `file_too_large`；下载/上传超时 **120 秒**（普通接口 12 秒）。
 - 同名文件已存在时按源的 `rename` 策略自动改名为 `名称(1).扩展名`、`名称(2).扩展名`……**不覆盖**已有文件。
 
+### 附件历史版本（attachment.list-versions）
+
+| operation | risk | 必填 | 可选 |
+| --- | --- | --- | --- |
+| `caizhilian.attachment.list-versions` | read | `attachment_id` | `doc_id`、`page_no`(1)、`page_size`(10) |
+
+- 按附件 ID 查询该附件的**全部历史版本**（每次替换/新建产生的版本都在列表里，含当前最新版本）。
+- `attachment_id` 来自 `caizhilian.document.get` 或 `caizhilian.compare.list-file-objects`；`doc_id` 可传可不传（不传时按空处理），需要时可同时给。
+- 返回每个版本的 `id`（版本 ID）、`name`（文件名）、`versionNumber`（版本号）、`updateTime`、`describe`（版本说明，如「新建」「替换」）、`extName`（扩展名）。
+- `updateTime` 自动转为东八区 `YYYY-MM-DD HH:MM:SS`：毫秒/秒时间戳均可，已是时间格式的字符串原样透传，无法识别的值原样保留。
+- 结果超过一页时 `has_next=true`，用 `page_no` 翻页；不要拿返回计数推断总量。
+
 ### 封面（cover）
 
 | operation | risk | 必填 | 说明 |
@@ -60,6 +72,7 @@ weaver-work-cli --json caizhilian run caizhilian.attachment.upload.apply --input
 weaver-work-cli --json caizhilian run caizhilian.attachment.replace.prepare --input-json '{"doc_id":"1234567890","attachment_id":"888","folder_id":"456","file_path":"C:\\data\\合同v2.pdf"}'
 weaver-work-cli --json caizhilian run caizhilian.attachment.download --input-json '{"doc_id":"1234567890","attachment_id":"888","save_path":"C:\\data\\out\\合同.pdf"}'
 weaver-work-cli --json caizhilian run caizhilian.attachment.download-as-pdf --input-json '{"doc_id":"1234567890","attachment_id":"888","save_path":"C:\\data\\out"}'
+weaver-work-cli --json caizhilian run caizhilian.attachment.list-versions --input-json '{"attachment_id":"888"}'
 weaver-work-cli --json caizhilian run caizhilian.cover.set.prepare --input-json '{"doc_id":"1234567890","file_path":"C:\\data\\cover.png"}'
 weaver-work-cli --json caizhilian run caizhilian.cover.remove.prepare --input-json '{"doc_id":"1234567890"}'
 weaver-work-cli --json caizhilian run caizhilian.compare.list-file-objects --input-json '{"doc_id":"1234567890"}'
@@ -74,6 +87,7 @@ weaver-work-cli --json caizhilian run caizhilian.attachment.upload.apply --input
 weaver-work-cli --json caizhilian run caizhilian.attachment.replace.prepare --input-json '{"doc_id":"1234567890","attachment_id":"888","folder_id":"456","file_path":"/tmp/data/contract-v2.pdf"}'
 weaver-work-cli --json caizhilian run caizhilian.attachment.download --input-json '{"doc_id":"1234567890","attachment_id":"888","save_path":"/tmp/data/out/contract.pdf"}'
 weaver-work-cli --json caizhilian run caizhilian.attachment.download-as-pdf --input-json '{"doc_id":"1234567890","attachment_id":"888","save_path":"/tmp/data/out/"}'
+weaver-work-cli --json caizhilian run caizhilian.attachment.list-versions --input-json '{"attachment_id":"888"}'
 weaver-work-cli --json caizhilian run caizhilian.cover.set.prepare --input-json '{"doc_id":"1234567890","file_path":"/tmp/data/cover.png"}'
 weaver-work-cli --json caizhilian run caizhilian.cover.remove.prepare --input-json '{"doc_id":"1234567890"}'
 weaver-work-cli --json caizhilian run caizhilian.compare.list-file-objects --input-json '{"doc_id":"1234567890"}'
@@ -82,11 +96,18 @@ weaver-work-cli --json caizhilian run caizhilian.compare.submit.prepare --input-
 
 ## 输出处理
 
-- **prepare 返回**：`data` 含本地文件预览 `{ file_name, file_size, file_md5, ext_name }` + `upload` 预览块（`path`、`extra_body`、`allowed_ext`、`required_permission`、`deferred_to_apply: true`），外加 `continuation`、`expires_in_ms`、`hint`，`meta.status = "PREPARED"`。向用户摘要时必须写清「哪个文件、多大、传到哪篇文档/做什么」。
-- **上传类 apply 返回**：`{ file_id, name, size, ext_name, ... }`（`attachment.upload` 额外把源的 `uploadTime` 改名为 `upload_time` 放在最后；`attachment.replace` 与 `document.replace-content` 额外带 `version`（新版本号））。命中服务端 MD5 秒传时不会真正传文件，但返回结构一致。
+- **prepare 返回**：`data` 含本地文件预览 `{ file_name, file_size, file_md5, ext_name }` + `upload` 预览块（`path`、`extra_body`、`allowed_ext`、`required_permission`、`deferred_to_apply: true`），外加 `continuation`、
+  `expires_in_ms`、`hint`，
+  `meta.status = "PREPARED"`。
+  向用户摘要时必须写清「哪个文件、多大、传到哪篇文档/做什么」。
+- **上传类 apply 返回**：`{ file_id, name, size, ext_name, ... }`（`attachment.upload` 额外把源的 `uploadTime` 改名为 `upload_time` 放在最后；`attachment.replace` 与 `document.replace-content` 额外带 `version`（新版本号））。
+  命中服务端 MD5 秒传时不会真正传文件，
+  但返回结构一致。
 - **下载类返回**：`{ file_path, file_name, file_size }`，`meta` 带 `{ doc_id, attachment_id }`。回复用户时给出**绝对路径 + 文件大小**，并提示已存在同名文件时被自动改名。
 - `cover.upload.apply` 返回 `{ file_id, name, size, ext_name }`；`cover.set.apply` 返回 `{ doc_id, file_id, name }`；`cover.remove.apply` 返回 `{ doc_id, cover_picture_id }`（`cover_picture_id` 为删除后的空串）。
 - `compare.list-file-objects` 返回 `{ attachments: [{ docId, file_id, ext_name, file_name, size, updateTime }] }`，其中 `file_id` 就是 `compare.submit` 需要的 ID；用 Markdown 表格摘要「文件名/类型/大小/更新时间」。
+- `attachment.list-versions` 返回 `{ versions: [{ id, name, versionNumber, updateTime, describe, extName }], has_next }`；`updateTime` 已转为东八区时间字符串。用 Markdown 表格摘要「版本号/文件名/更新时间/版本说明」，`id` 作为后续操作入参，
+  不作为展示主体。
 - `compare.search-documents` 与 `document.search` 同构（`{ page_no, page_size, has_next, documents[] }`），参见 `document.md`。
 - `compare.submit.apply` 返回 `{ compare_link }`，把链接原样交给用户，不要尝试抓取链接内容。
 

package/skills/weaver-e10-caizhilian/references/folder.md

@@ -28,13 +28,21 @@
 
 枚举取值（**拼写 1:1 沿用源接口，注意 `Premisstion` 是源的拼写，不要自行改成 `Permission`**）：
 
-- `permission_type`（8 项）：`copyPermission`、`deletePremisstion`、`downloadPremisstion`、`folderDefaultParticipants`、`movePermission`、`newCreateDocPremisstion`、`newCreateFolderPremisstion`、`settingPermission`
+- `permission_type`（8 项）：`copyPermission`、`deletePremisstion`、`downloadPremisstion`、`folderDefaultParticipants`、`movePermission`、`newCreateDocPremisstion`、`newCreateFolderPremisstion`、
+  `settingPermission`
 - `setting_type`（9 项）：上面 8 项 + `defaultShares`
-- `permission_key`（9 项）：上面 8 项，但把 `folderDefaultParticipants` 之外再加 `folderDefaultShareNew`（即 `copyPermission`、`deletePremisstion`、`downloadPremisstion`、`folderDefaultParticipants`、`folderDefaultShareNew`、`movePermission`、`newCreateDocPremisstion`、`newCreateFolderPremisstion`、`settingPermission`）
+- `permission_key`（9 项）：上面 8 项，但把 `folderDefaultParticipants` 之外再加 `folderDefaultShareNew`（即 `copyPermission`、`deletePremisstion`、`downloadPremisstion`、`folderDefaultParticipants`、
+  `folderDefaultShareNew`、`movePermission`、`newCreateDocPremisstion`、`newCreateFolderPremisstion`、
+  `settingPermission`）
 
-`query-by-permission` 的 `permissions` 是对象数组，元素形如 `{"object_type":"all"}` 或 `{"object_type":"resource","object_ids":["123"]}`；`object_type` 必填，`object_ids` 必须是正整数字符串。`page_no` / `page_size` 传 `<=0` 会报 `validation/number_invalid`（源脚本是静默归一，这里选择显式报错）。
+`query-by-permission` 的 `permissions` 是对象数组，元素形如 `{"object_type":"all"}` 或 `{"object_type":"resource","object_ids":["123"]}`；`object_type` 必填，`object_ids` 必须是正整数字符串。
+`page_no` / `page_size` 传 `<=0` 会报 `validation/number_invalid`（源脚本是静默归一，
+这里选择显式报错）。
 
-`object_ids` 必须是**对象的真实 ID**：人员/部门/分部/角色/岗位/客户一律用 `caizhilian.org.search-*` 查出来的 `id`（每个对象都要是字符串，且不要用 JSON 数字传）。**不要用 `default-share.list` / `get-settings` / `permission.list` 返回条目里的 `id`**——那是共享/权限条目的 ID，不是对象 ID，拿它反查只会得到空结果。不带 ID 的对象类型（`all`、`allExternal`、`createrSelf` 等）不传 `object_ids`。
+`object_ids` 必须是**对象的真实 ID**：人员/部门/分部/角色/岗位/客户一律用 `caizhilian.org.search-*` 查出来的 `id`（每个对象都要是字符串，且不要用 JSON 数字传）。
+**不要用 `default-share.list` / `get-settings` / `permission.list` 返回条目里的 `id`**——那是共享/权限条目的 ID，不是对象 ID，
+拿它反查只会得到空结果。
+不带 ID 的对象类型（`all`、`allExternal`、`createrSelf` 等）不传 `object_ids`。
 
 ### 写操作
 
@@ -57,7 +65,8 @@
 | `caizhilian.folder.permission.sync-default-share` | `id`（文件夹 ID）、`sync_to_folder_docs`、`sync_to_all_folders`、`sync_to_all_sub_folder_docs`（至少选一个） | `keep_old_default_share_for_folder_docs`、`keep_old_non_default_share_for_folder_docs`、`keep_old_default_share_for_all_folders`、`keep_old_default_share_for_sub_folder_docs`、`keep_old_non_default_share_for_sub_folder_docs`（默认 true） |
 
 - `folder.create` 的 `parent_type=privy`（个人）时，`sequence` 强制为 `0`、`inherit_parent` 强制为 `false`（源行为）。
-- `obj_type` 与 `share_level` 不要猜：先用 `default-share.form` / `permission.form` 拿到 `obj_types[].id` 和级联参数，再决定要传哪些 `obj_id*` 字段；传了 `obj_type` 未配置的对象字段会报 `validation/obj_type_not_configured` 或 `obj_type_not_supported`。
+- `obj_type` 与 `share_level` 不要猜：先用 `default-share.form` / `permission.form` 拿到 `obj_types[].id` 和级联参数，再决定要传哪些 `obj_id*` 字段；
+  传了 `obj_type` 未配置的对象字段会报 `validation/obj_type_not_configured` 或 `obj_type_not_supported`。
 - `download` 在 `share_level != 1` 且未传时默认按 `["download"]` 处理（源行为）。
 - `set-auth` 的 `value=user` 表示「按人员白名单」，此时白名单条目由 `permission.list` / `permission.add` 维护；`permission_auth_not_user` 表示当前权限类型不是 `user` 模式，需要先 `set-auth`。
 
@@ -107,16 +116,29 @@ weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-default-
 
 - `query-by-name` 返回**展平后的路径列表**（源模板 `FlattenSearchResultFolderTree`），每项含文件夹 ID、名称与完整路径；同名文件夹可能出现在多个路径下，必须让用户确认选哪一个，不要默认取第一条。
 - `search-virtual` 返回 `{ page_no, page_size, has_next, folders[] }`，每项含 `id`、`name`、`path`、`parent_folder_id`（源 `content` 形如 `名称[路径]`，CLI 已拆开）。
-- `get-settings` 返回 `{ defaultVirtualFolder, folderDefaultParticipants, currentFolder, folderDefaultShareNew }`（`currentFolder` 含 `id`/`name`/`title`；参与人每项含 `id`/`content`/`_entityType`，共享对象另含 `canDelete`），创建文档时的兜底来源。
+- `get-settings` 返回 `{ defaultVirtualFolder, folderDefaultParticipants, currentFolder, folderDefaultShareNew }`（`currentFolder` 含 `id`/`name`/`title`；参与人每项含 `id`/`content`/`_entityType`，
+  共享对象另含 `canDelete`），
+  创建文档时的兜底来源。
 - `folder.create.apply` 返回 `{ folder_id, name, type, parent_id }`，新文件夹 ID 可直接用于后续创建文档。
 - 文件夹侧共享/权限条目统一归一为 `{ id, object_type, object_name, share_level, sec_level }`（`sec_level` 空值显示为 `--`）；文档级共享条目（`share.*`）另含 `download`、`can_delete`。
-- `list-default-shares` → `{ defaultShares[] }`；`default-share.list` → `{ default_shares[] }`；`permission.list` → `{ add_visible, shares[] }`（`add_visible=false` 时不要再引导用户添加）。删除前必须从列表里取真实条目 `ids`，不要自己拼。
+- `list-default-shares` → `{ defaultShares[] }`；`default-share.list` → `{ default_shares[] }`；`permission.list` → `{ add_visible, shares[] }`（`add_visible=false` 时不要再引导用户添加）。删除前必须从列表里取真实条目 `ids`，
+  不要自己拼。
 - `default-share.form` → `{ category, obj_types[], param_options }`；`permission.form` → `{ obj_types[], param_options }`。`obj_types[].id` 就是 `obj_type` 的合法取值，`param_options` 给出级联参数。
 - `permission.get-auth` 返回 `{ permission_type, current_value }`（`true` / `user` / `false`）。
 - `permission.detail` 返回 `{ title, current_setting, list_label, items[] }`；`setting_type=defaultShares` 时只返回 `{ title, items[] }`。
-- `permission.query` 返回 `{ permissions }`：以 `folder_id` 为 key 的映射，每个 value 含 `isCreateDoc`、`isCreateFolder`、`canMoveDoc`、`canCopyDoc` 四个布尔标志与 `allowDocumentCreateTypes`（允许创建的文档类型列表，无设置时为空数组）。建文档前可用它确认目标文件夹是否允许创建及允许的文档类型。
-- `query-by-permission` 返回 `{ total, page_no, page_size, has_next, folders[] }`，每项含 `folder_id`、`folder_name`、`folder_type`。返回空数组只表示「没有匹配到」：先按上文核对 `object_ids` 是不是对象的真实 ID，再如实把结果告诉用户；**不要据此断定「反查不支持该权限类型」**。返回里没有文件夹路径，需要展示路径时用 `get-settings` 的 `currentFolder.title` 或 `query-by-name` 补。
-- 写操作 `apply` 返回结果回显：`default-share.add` → `{ added: true, default_shares }` 或 `{ added: false, message }`（服务端判定「已存在」不是失败，必须把 message 转述给用户）；`default-share.delete` → `{ deleted: true, default_shares }`；`permission.add` → `{ added: true, shares }`；`permission.delete` → `{ deleted: true, shares }`；`permission.set-auth` → `{ permission_type, value, current_value }`；`permission.sync-setting` → `{ existChildFolder }`；`permission.sync-maintain` → `{ existChildFolder }`；`permission.sync-download` → `{ existChildFolder }`；`permission.sync-delete` → `{ existChildFolder }`；`permission.sync-copy` → `{ existChildFolder }`；`permission.sync-create` → `{ existChildFolder }`；`permission.sync-move` → `{ existChildFolder }`；`permission.sync-participant` → `{ existChildFolder, existChildDocument, asyncKey }`；`permission.sync-default-share` → `{ existChildFolder, existChildDocument, asyncKey }`。
+- `permission.query` 返回 `{ permissions }`：以 `folder_id` 为 key 的映射，每个 value 含 `isCreateDoc`、`isCreateFolder`、`canMoveDoc`、`canCopyDoc` 四个布尔标志与 `allowDocumentCreateTypes`（允许创建的文档类型列表，无设置时为空数组）。
+  建文档前可用它确认目标文件夹是否允许创建及允许的文档类型。
+- `query-by-permission` 返回 `{ total, page_no, page_size, has_next, folders[] }`，每项含 `folder_id`、`folder_name`、`folder_type`。返回空数组只表示「没有匹配到」：先按上文核对 `object_ids` 是不是对象的真实 ID，再如实把结果告诉用户；
+  **不要据此断定「反查不支持该权限类型」**。
+  返回里没有文件夹路径，需要展示路径时用 `get-settings` 的 `currentFolder.title` 或 `query-by-name` 补。
+- 写操作 `apply` 返回结果回显：`default-share.add` → `{ added: true, default_shares }` 或 `{ added: false, message }`（服务端判定「已存在」不是失败，必须把 message 转述给用户）；
+  `default-share.delete` → `{ deleted: true, default_shares }`；
+  `permission.add` → `{ added: true, shares }`；`permission.delete` → `{ deleted: true, shares }`；`permission.set-auth` → `{ permission_type, value, current_value }`；
+  `permission.sync-setting` → `{ existChildFolder }`；
+  `permission.sync-maintain` → `{ existChildFolder }`；`permission.sync-download` → `{ existChildFolder }`；`permission.sync-delete` → `{ existChildFolder }`；
+  `permission.sync-copy` → `{ existChildFolder }`；
+  `permission.sync-create` → `{ existChildFolder }`；`permission.sync-move` → `{ existChildFolder }`；`permission.sync-participant` → `{ existChildFolder, existChildDocument, asyncKey }`；
+  `permission.sync-default-share` → `{ existChildFolder, existChildDocument, asyncKey }`。
 - 权限/共享类写操作的 `prepare` 返回请求体预览 + `continuation`；向用户摘要时必须写清「哪个文件夹、哪项权限、给谁、什么级别」，并说明删除类操作不可撤销。
 - 列表类结果默认用 Markdown 表格摘要（文件夹名/路径/权限类型/对象/级别），不要原样贴 JSON。
 
@@ -125,11 +147,21 @@ weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-default-
 - 文件夹权限与默认共享是**影响面很大的配置**：改错会导致整个知识库的下载、复制、新建权限对全员开放或全部收紧。`permission.set-auth` 从 `user` 改成 `true` 等于放开给所有人，确认摘要里必须显式写出这一后果。
 - `folder.create` 会在服务端产生新节点；`inherit_parent=true` 会连带继承父文件夹的权限与默认设置，必须在确认摘要里说明。
 - 删除类（`default-share.delete` / `permission.delete`）必须先做一次对应 `list` 只读查询，把待删条目的可读信息展示给用户后再 prepare。
-- `permission.sync-setting`、`permission.sync-maintain`、`permission.sync-copy`、`permission.sync-create`、`permission.sync-move` 的 `keepOldSettingForAllFolders` 是**必填参数**，必须明确传入 `true`（保留原有设置）或 `false`（不保留），否则会报错。执行前必须提醒用户此操作对系统性能可能有一定影响。
-- `permission.sync-participant` 是**异步操作**，支持三种同步范围：同步到当前文件夹内的历史文档（`sync_to_folder_docs`）、同步到所有下级文件夹（`sync_to_all_folders`）、同步到所有下级文件夹内的历史文档（`sync_to_all_sub_folder_docs`），**至少选择一个**。每个选中的范围对应的"原有参与人"参数（`keep_old_for_folder_docs`、`keep_old_for_all_folders`、`keep_old_for_all_sub_folder_docs`）默认为 `true`（保留）。执行后会自动轮询进度，超时时间为 300 秒。
-- `permission.sync-default-share` 是**异步操作**，支持三种同步范围：同步到当前文件夹内的历史文档（`sync_to_folder_docs`）、同步到所有下级文件夹（`sync_to_all_folders`）、同步到所有下级文件夹内的历史文档（`sync_to_all_sub_folder_docs`），**至少选择一个**。每个选中的范围对应的"原有默认共享人"和"原有非默认共享人"参数默认为 `true`（保留）。执行后会自动轮询进度，超时时间为 300 秒。
-- `permission.sync-download` 的行为取决于当前下载权限设置：当下载权限为"允许所有人下载"或"不允许下载"时，直接同步到所有下级文件夹，不需要 `keepOldSettingForAllFolders` 参数；当下载权限为"允许以下人员下载"时，`keepOldSettingForAllFolders` 是**必填参数**，必须明确传入 `true`（保留原有下载权限设置）或 `false`（不保留）。
-- `permission.sync-delete` 的行为取决于当前删除权限设置：当删除权限为"允许完全控制权限人员删除文档"时，直接同步到所有下级文件夹，不需要 `keepOldSettingForAllFolders` 参数；当删除权限为"允许以下人员删除文档"时，`keepOldSettingForAllFolders` 是**必填参数**，必须明确传入 `true`（保留原有删除权限设置）或 `false`（不保留）。
+- `permission.sync-setting`、`permission.sync-maintain`、`permission.sync-copy`、`permission.sync-create`、`permission.sync-move` 的 `keepOldSettingForAllFolders` 是**必填参数**，
+  必须明确传入 `true`（保留原有设置）或 `false`（不保留），
+  否则会报错。
+  执行前必须提醒用户此操作对系统性能可能有一定影响。
+- `permission.sync-participant` 是**异步操作**，支持三种同步范围：同步到当前文件夹内的历史文档（`sync_to_folder_docs`）、同步到所有下级文件夹（`sync_to_all_folders`）、同步到所有下级文件夹内的历史文档（`sync_to_all_sub_folder_docs`），**至少选择一个**。
+  每个选中的范围对应的"原有参与人"参数（`keep_old_for_folder_docs`、`keep_old_for_all_folders`、
+  `keep_old_for_all_sub_folder_docs`）默认为 `true`（保留）。
+  执行后会自动轮询进度，超时时间为 300 秒。
+- `permission.sync-default-share` 是**异步操作**，支持三种同步范围：同步到当前文件夹内的历史文档（`sync_to_folder_docs`）、同步到所有下级文件夹（`sync_to_all_folders`）、同步到所有下级文件夹内的历史文档（`sync_to_all_sub_folder_docs`），**至少选择一个**。
+  每个选中的范围对应的"原有默认共享人"和"原有非默认共享人"参数默认为 `true`（保留）。
+  执行后会自动轮询进度，超时时间为 300 秒。
+- `permission.sync-download` 的行为取决于当前下载权限设置：当下载权限为"允许所有人下载"或"不允许下载"时，直接同步到所有下级文件夹，不需要 `keepOldSettingForAllFolders` 参数；当下载权限为"允许以下人员下载"时，`keepOldSettingForAllFolders` 是**必填参数**，
+  必须明确传入 `true`（保留原有下载权限设置）或 `false`（不保留）。
+- `permission.sync-delete` 的行为取决于当前删除权限设置：当删除权限为"允许完全控制权限人员删除文档"时，直接同步到所有下级文件夹，不需要 `keepOldSettingForAllFolders` 参数；当删除权限为"允许以下人员删除文档"时，`keepOldSettingForAllFolders` 是**必填参数**，
+  必须明确传入 `true`（保留原有删除权限设置）或 `false`（不保留）。
 - 本 reference 只覆盖文件夹与权限；文档级共享/参与人/标签见 `collaboration.md`。
 
 ## 失败处理
@@ -147,4 +179,4 @@ weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-default-
 | `id_invalid` | `folder_id` / `object_ids` 等不是正整数 | 重新查真实 ID；反查的对象 ID 要来自 `org.search-*`，不是共享条目 ID |
 | `range_invalid` / `number_invalid` | `sequence`、`seclevel_min/max`、分页越界 | 按范围修正 |
 | `api/business_error` | 服务端业务失败（含权限不足） | 原样转述 message，不要重复提交 |
-| `partial/write_uncertain` | 写结果不确定 | 立即停止，最多补一次 `permission.list` / `default-share.list` 只读回查，禁止自动重放 |
+| `partial/write_uncertain` | 写结果不确定 | 立即停止，最多补一次 `permission.list` / `default-share.list` 只读回查，禁止自动重放 |