weaver-work-cli 0.1.23 → 0.1.25

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.26
+version: 1.1.33
 author: 泛微网络科技股份有限公司
 agent_created: true
 requires:
@@ -16,7 +16,7 @@ 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 拒绝或剥离。
+认证与登录态只能按共享规则通过 `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`）。
 
@@ -38,7 +38,7 @@ cliHelp: "weaver-work-cli caizhilian --help"
 - 文档权限 / 下载权限 / 复制权限 / 移动权限 / 删除权限 / 新建文档权限 / 新建文件夹权限 / 设置权限 / 按权限反查
 - 文档共享 / 共享给某人某部门 / 取消共享 / 共享级别
 - 标签 / 公共标签 / 个人标签 / 参与人 / 协作者
-- 附件 / 上传附件 / 替换附件 / 下载附件 / 附件转 PDF / 封面 / 封面图
+- 附件 / 上传附件 / 替换附件 / 下载附件 / 附件转 PDF / 附件历史版本 / 封面 / 封面图
 - 文档比对 / 比对链接 / 左右文件对比
 
 **判定规则：** 只要最终动作是对采知连文档或知识库文件夹做查询、创建、编辑、共享、权限设置、标签/参与人维护、附件与封面处理或文档比对，就归 `weaver-e10-caizhilian`。用户处理的是 E10 流程表单、人事、财务、邮件、会议等非文档中心业务时，不使用本 Skill。
@@ -53,11 +53,14 @@ cliHelp: "weaver-work-cli caizhilian --help"
 | 创建文档（HTML / Markdown / Office / 批量上传） | `caizhilian run caizhilian.document.create-html｜create-markdown｜create-office｜create-by-upload.prepare/apply` | [`document.md`](references/document.md) |
 | 改文档基础字段 / 改作者 / 存正文 / 替换正文 | `caizhilian run caizhilian.document.update-field｜update-author｜update-html｜replace-content.prepare/apply` | [`document.md`](references/document.md) |
 | 建文件夹 / 查虚拟文件夹 / 查文件夹设置 | `caizhilian run caizhilian.folder.create.prepare/apply`、`.search-virtual`、`.get-settings`、`.query-by-name` | [`folder.md`](references/folder.md) |
-| 文件夹默认共享与八类权限、按权限反查、同步管理员权限到子文件夹 | `caizhilian run caizhilian.folder.default-share.*`、`caizhilian.folder.permission.*`、`.query-by-permission`、`.sync-setting` | [`folder.md`](references/folder.md) |
+| 文件夹默认共享与八类权限、按权限反查、同步管理员/维护/下载/删除/复制/新建/移动/默认参与人/默认共享人到子文件夹 | `caizhilian run caizhilian.folder.default-share.*`、`caizhilian.folder.permission.*`、`.query-by-permission`、`.sync-setting`、`.sync-maintain`、`.sync-download`、`.sync-delete`、`.sync-copy`、`.sync-create`、`.sync-move`、`.sync-participant`、`.sync-default-share` | [`folder.md`](references/folder.md) |
 | 标签增删查、参与人增删查、文档共享增删查 | `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) |
@@ -67,6 +70,11 @@ cliHelp: "weaver-work-cli caizhilian --help"
 | 任何写操作的确认链、票据报错、写结果不确定 | `<name>.prepare` -> 用户确认 -> `<name>.apply --continuation TOKEN --yes` | [`write-protocol.md`](references/write-protocol.md) |
 | 环境列表 / 配置查看 / 重载配置 / 切换环境等未暴露能力 | 无 caizhilian 命令，改用框架命令 | [`withheld.md`](references/withheld.md) |
 
+文件上传支持秒传、普通流式上传和分片流式上传；成功必须有非空文件 ID、大小校验与私有回执。
+上传协议的 `lastModified`、`lastModifiedDate` 必须使用相同的整数毫秒值，由 CLI 自动处理；
+小数毫秒可能触发 E10 整数解析错误，详见 [`file-upload.md`](references/file-upload.md) 的时间戳规则与失败处理。
+认证沿用 `weaver-work-cli` 的共享规则；不执行独立文件上传 Skill 的 bundle 或独立浏览器登录。
+
 处理链：
 
 - 检索并阅读：`caizhilian.document.search` -> 用户选条目 -> `caizhilian.document.get` 取详情
@@ -75,6 +83,8 @@ cliHelp: "weaver-work-cli caizhilian --help"
 - 共享给某人：`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.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`）
 

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

@@ -1,309 +1,114 @@
----
-name: weaver-file-upload
-description: >-
-  Upload local files to the Weaver E10/eTeams file service with a bundled
-  single-file Node CLI through the recorded preUploadCheck and module/upload
-  protocol. Supports server-side second-hit, common streaming upload, chunked
-  upload, terminal fileId validation, safe metadata, and session-isolated
-  receipts. Use for Weaver file upload, attachment pre-upload, large-file
-  chunk upload, second upload, or when another workflow needs a verified
-  Weaver fileId from an absolute local path. Login is an explicit provider or
-  standalone-browser choice with no automatic fallback.
----
+# 文件上传
 
-# Weaver File Upload
+本模块把一个本地文件上传到 E10 文件服务，返回经过校验的文件 ID 与本地回执。
+上传协议采用 `weaver-file-upload` 的预检查、秒传、普通上传和分片上传契约。
+文件绑定到文档、附件字段、表单或消息由调用方负责。
 
-This Skill owns one transaction: turn one absolute local file path into one
-business-verified Weaver `fileId`. Binding that file to a form, document,
-message, or other business object belongs to the caller.
+## 运行与认证
 
-The delivery includes `dist/weaver-file-upload.js`, a single Node.js bundle
-containing the upload owner, large-integer JSON handling, WebSocket transport,
-and standalone Chrome/CDP login. It requires Node.js 18.20.0 or newer, does not
-run npm install, and does not download a platform executable on first use.
+- 唯一运行时为 `weaver-work-cli`；源码位于 `src/shortcuts/caizhilian/file-upload/`，
+  操作入口位于 `src/shortcuts/caizhilian/operations/handlers/file-upload.ts`。
+- 安装与登录遵守 `../../weaver-e10-shared/SKILL.md`。认证只使用 CLI 当前身份或连接器注入的身份。
+- 本模块不执行独立 Skill 的 `dist/weaver-file-upload.js`，不复用 `e10-login` 的会话，
+  不启动第二套 Chrome 登录；独立 Skill 的双登录模式不属于本 CLI 上传接口。
+- 缺少会话或登录失效时按共享规则处理，不自行切换账号或环境。
 
-## Runtime Routing
+## 操作与参数
 
-- In a Harness with native Weaver session injection, execute the bundle through
-  the host Skill runner and select `weaver-e10-login`. Do not start standalone
-  browser login or read `.env.local` in that mode.
-- Otherwise execute the bundle directly and pass `--login-mode
-  weaver-e10-login|standalone` to `login` and `upload`.
-- Provider mode calls only the public `e10-login whoami` contract. Standalone
-  mode owns its browser, validator, session, and cleanup. Failure never switches
-  to the other identity source.
+| 操作 | 作用 | 必填 |
+| --- | --- | --- |
+| `caizhilian.file-upload.contract` | 获取完整命令、参数用途、策略和结果证据 | 无 |
+| `caizhilian.file-upload.prepare` | 本地文件/上下文检查与 MD5、SHA256；不登录、不联网、不签发上传票据 | `file_path`、`module` |
+| `caizhilian.file-upload.upload.prepare` | 用户授权检查、本地校验、绑定当前环境和身份的确认票据 | `file_path`、`module`、`user_confirmed=true` |
+| `caizhilian.file-upload.upload.apply` | 校验确认票据和内容未变，再执行上传 | 上述参数、`continuation`、`confirm=true`（CLI 用 `--yes`） |
 
-## First Move
+上传参数来自真实业务上下文，不能因为缺少可选字段阻塞基础上传。
 
-Resolve `SKILL_ROOT` from this file and request the complete machine contract:
-
-```text
-node "$SKILL_ROOT/dist/weaver-file-upload.js" contract \
-  --chat-id '<chatId>'
-```
-
-Use `agent_callable_interface_contract.v1`; do not guess flags or learn them
-through repeated help calls. All flags follow the command. Before requesting
-missing upload inputs, show the contract's complete required, conditionally
-required, and optional lists with their purposes. Reuse an existing host
-attachment path instead of asking for it again.
-
-## Workflow
-
-```text
-contract
--> prepare absolute file + context
--> explicit provider | standalone login
--> current-user upload authorization
--> preUploadCheck
--> second | common | chunk
--> terminal non-empty fileId
--> secret-free 0600 receipt
-```
-
-Standalone login without a saved domain returns `status=requires_input`,
-`channel=agent_conversation`, and `resumeArgument=--base-url`. Ask for the
-non-secret OA/E10 root address in the current conversation, then resume:
-
-```text
-node "$SKILL_ROOT/dist/weaver-file-upload.js" login \
-  --chat-id '<chatId>' --login-mode standalone \
-  --base-url 'https://<runtime-host>'
-```
-
-Provider validation:
-
-```text
-node "$SKILL_ROOT/dist/weaver-file-upload.js" login \
-  --chat-id '<chatId>' --login-mode weaver-e10-login
-```
-
-## Hard Rules
-
-- `--file` and `--context-file` are absolute paths. `--chat-id` isolates
-  receipts under `runs/<chatId>/`, or the resolved private state root.
-- `--module` is mandatory and comes from real caller business context. Never
-  guess `workflow`, `document`, or another module.
-- `upload` requires `--user-confirmed` from the current user request. The CLI
-  rejects a missing confirmation before file, authentication, or network work.
-- Context cannot override protocol-owned fields. File and chunk bodies remain
-  streaming; the complete large file is never buffered in memory.
-- Never print or persist Cookie, ETEAMSID, token, Authorization, ticket,
-  password, signed URL, multipart body, or raw server response.
-- HTTP 200 and `endChunk=true` are insufficient. Success requires a non-empty
-  terminal `fileId`; any nonzero server size must match the local file.
-- A transport failure after an upload POST is
-  `execution_state=unknown`, is not retry-safe, and is never replayed
-  automatically.
-- Use `receipt_ref` and `receipt_sha256` as terminal evidence.
-
-## Resources
-
-| Need | Read |
+| 参数 | 用途 |
 | --- | --- |
-| Protocol, strategy, results, recovery | `references/file-upload-operation-contract.md` |
-| Required and optional parameters | `references/file-upload-input-parameters.md` |
-| Machine invocation contract | `references/file-upload-cli-contract.json` |
-| Rule ownership | `references/file-upload-rule-index.md` |
-| Host executor behavior | `references/file-upload-host-executor-prompt.md` |
-| Host integration | `references/file-upload-host-platform-integration.md` |
-| Source, tests, and packaging | `references/file-upload-maintenance.md` |
-
-<!-- weaver-domain-login:v1 -->
-## 域名与登录方式
-
-- **不得写死域名**；构建和打包时不保存业务域名。
-- 运行时必须由用户显式选择方式 1（`weaver-e10-login`）或方式 2（本
-  Skill 独立浏览器登录）；不得因认证失败自动切换。
-- 方式 1 只调用 Provider 的公开 `whoami`，缺失或未登录时停止，不回退。
-- 方式 2 首次缺少域名时由 Agent 在当前对话中询问，再以 `--base-url`
-  恢复；CLI 不读取 stdin，也不打开交互终端。
-- 方式 2 的核心流程可独立安装和运行，不依赖任何其他 Skill；Provider
-  不打入 bundle。
-<!-- /weaver-domain-login:v1 -->
-
-<!-- weaver-browser-login-capture:v1 -->
-## 登录与会话
-
-- 方式 2 使用本 Skill 的专用 Chrome + CDP，只打开运行时根地址；用户自然
-  完成密码、验证码、SSO 或 MFA。
-- Cookie 候选必须通过真实、无副作用的业务接口
-  `POST /api/baseserver/layout/teamsCheck` 和非空
-  `currentUser.employeeId` 校验。
-- 会话只原子写入权限为 `0600` 的 `.env.local`；不得输出 Cookie、session id、token、ticket 或密码。
-- 页面 target 失效时重新选择 page target。所有退出路径先调用
-  `Browser.close`，再按本次 owned Profile/PID 定向清理，不关闭用户浏览器。
-- 合同位于 `references/file-upload-browser-login-contract.json`。
-<!-- /weaver-browser-login-capture:v1 -->
-# Weaver File Upload Operation Contract
-
-## Scope
-
-The public product is one verified Weaver file-service object. Business-specific
-attachment ordering, form binding, editor nodes, messages, and document changes
-remain downstream operations.
-
-```text
-local regular file
--> POST /api/file/preUploadCheck?sf_request_type=ajax
--> uploadType=second | common | chunk
--> optional POST /api/file/module/upload?sf_request_type=ajax
--> terminal non-empty fileid/fileId
-```
-
-## Public Actions
-
-| Action | Side effect | Login | Success evidence |
-| --- | --- | --- | --- |
-| `contract` | private local contract artifact | no | `agent_callable_interface_contract.v1` |
-| `prepare` | local reads only | no | path, size, hashes, module, safe context summary |
-| `login` | standalone mode starts one owned Chrome | explicit choice | validated runtime session |
-| `upload` | creates or resolves remote file object | yes | terminal file ID, size check, private receipt |
-
-Every command writes one JSON object. A nonzero exit means the action did not
-reach a verified result.
-
-## Canonical Invocation
-
-All flags follow the command:
-
-```text
-node "<skill_root>/dist/weaver-file-upload.js" contract \
-  --chat-id '<chatId>'
-
-node "<skill_root>/dist/weaver-file-upload.js" prepare \
-  --chat-id '<chatId>' --file '<absoluteFilePath>' --module '<module>' \
-  [--context-file '<absoluteJsonObjectPath>']
-
-node "<skill_root>/dist/weaver-file-upload.js" login \
-  --chat-id '<chatId>' \
-  --login-mode '<weaver-e10-login|standalone>' \
-  [--base-url '<runtimeRootUrl>']
-
-node "<skill_root>/dist/weaver-file-upload.js" upload \
-  --chat-id '<chatId>' \
-  --login-mode '<weaver-e10-login|standalone>' \
-  --user-confirmed --file '<absoluteFilePath>' --module '<module>' \
-  [--context-file '<absoluteJsonObjectPath>']
+| `file_path` | 普通文件绝对路径；拒绝符号链接，复用已有宿主附件路径 |
+| `module` | 真实业务模块，1–64 个字母、数字或 `._-`；无默认值，禁止猜测 |
+| `user_confirmed` | 当前用户对本文件上传的明确授权；必须为布尔 `true` |
+| `context_file`（可选） | 可选业务上下文 JSON 对象文件绝对路径，最大 64 KiB、嵌套最多 12 层 |
+| `chat_id`（可选） | 宿主对话标识，隔离回执；1–128 个字母、数字或 `._-`，默认 `cli` |
+| `timeout_seconds`（可选） | 每次请求及响应读取的超时上限，1–3600 秒，默认 300 |
+
+`context_file` 可包含真实业务提供的 `source`（来源场景）、`fieldId`（附件字段）、
+`sourceRefId`（来源对象）、`authModule`（鉴权模块）、`customParam`（模块扩展）、
+`refId`（关联对象）、`commonText`（通用扩展）、`folderId`（目标文件夹）。
+空字符串按原业务语义保留。上下文不得包含凭证或危险对象键，也不能覆盖协议自动字段：
+`sf_request_type`、`compressImg`、`module`、`name`、`size`、`MD5`、`lastModified`、
+`lastModifiedDate`、`preUploadId`、`uploadType`、`uploadShardSize`、`chunk`、`chunks`、`file`。
+
+### 上传时间戳规则
+
+`lastModified` 与 `lastModifiedDate` 是自 Unix epoch 起的**整数毫秒**，两个字段必须一致。
+Node.js `stat().mtimeMs` 可能含小数；CLI 仅在生成协议字段时使用
+`String(Math.floor(file.mtime_ms))`，例如 `1791798507076.7322` 转为 `1791798507076`。
+预检查、普通上传及每个分片都复用该整数值。不能直接提交带小数的 `mtimeMs`，也不能换成秒。
+
+本地用于检测文件变更的修改时间保留原始精度；无需修改源文件的时间属性。
+这些字段由 CLI 生成，不需要用户提供，也不能通过 `context_file` 覆盖。
+移植上传协议或维护其他运行时时，必须保留此归一化规则。
+
+## 上传与结果验证
+
+1. 未确认上传时，在文件读取、认证和网络操作前拒绝 `upload.prepare/apply`。
+2. 票据绑定环境、身份、完整入参、文件 SHA256 和上下文哈希；确认后改变文件或上下文必须重新 prepare。
+3. 执行 `preUploadCheck`，两个上传接口均固定 `sf_request_type=ajax`。
+4. `second` 直接解析已有文件对象；`common` 流式上传整个文件；`chunk` 使用服务端 MiB 分片大小，
+   逐片发送精确切片、零起始编号、总片数与实际片字节数。未知策略和缺少预检字段直接失败。
+5. 中间分片必须明确 `endChunk=false` 且没有终态文件 ID；最终结果必须包含非空文件 ID。
+   服务端返回的非零大小必须与本地一致；HTTP 200 或 `endChunk=true` 本身不能证明成功。
+6. 文件不会整体缓存在内存。multipart 使用精确 `Content-Length`，包含安全文件名和 RFC 5987 UTF-8 文件名。
+   响应最大 4 MiB，保留大整数文件 ID 的字符串精度。
+
+成功结果包含 `version=weaver_file_upload_result.v1`、`business_verified=true`、
+`upload_type`、归一化 `file`、`integrity.md5/sha256`、安全 `request_evidence`、
+`receipt_ref` 与 `receipt_sha256`。同时保留兼容字段 `file_id`、`file_name`、`size`、`ext`。
+
+回执位于 CLI 私有状态目录下的 `caizhilian/file-upload/runs/<chat_id>/receipts/`，
+POSIX 文件权限为 `0600`、回执目录为 `0700`。回执只保存归一化元数据和哈希，
+不保存凭证、签名 URL、业务上下文值、multipart 或原始服务端响应。
+
+## 失败处理
+
+- 上传 POST 后的连接中断、响应读取或协议失败返回 `partial/write_uncertain`，
+  `execution_state=unknown`、`retry_safe=false`，不得自动重放。
+- 文件上传已确认成功但回执写入失败返回 `partial/receipt_write_failed`，携带已上传文件 ID；
+  不得因回执失败重新上传。
+- 服务端明确拒绝、策略无效、分片不一致、文件 ID 缺失或大小不符都是失败；不得报告为上传成功。
+- 若 `/api/file/module/upload` 返回业务 `code=500`（HTTP 可能仍为 200），且错误含
+  `For input string: "1791798507076.7322"` 这类带小数的毫秒时间戳，说明提交值触发整数解析错误。
+  检查所用 CLI 是否包含时间戳归一化修复；维护其他运行时时核对上述两个字段。
+  不能仅凭 500 判定为此问题；结果不确定时仍遵守不得自动重放的规则。
+- 本地准备和预检失败没有上传文件内容的副作用。重新上传必须是用户授权的新事务。
+
+## 命令示例
+
+先读取 contract。下面的 `document` 只示意真实文档业务；使用时必须来自当前调用方场景。
+只有用户已经明确确认后，才传 `user_confirmed=true`，并遵守共享规则的连接器参数要求。
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json caizhilian run caizhilian.file-upload.contract
+weaver-work-cli --json caizhilian run caizhilian.file-upload.prepare --input-json '{"file_path":"C:\\data\\report.pdf","module":"document"}'
+weaver-work-cli --json caizhilian run caizhilian.file-upload.upload.prepare --input-json '{"file_path":"C:\\data\\report.pdf","module":"document","user_confirmed":true,"chat_id":"current-chat"}'
+weaver-work-cli --json caizhilian run caizhilian.file-upload.upload.apply --input-json '{"file_path":"C:\\data\\report.pdf","module":"document","user_confirmed":true,"chat_id":"current-chat"}' --continuation TOKEN --yes
 ```
 
-Call `contract` before the first upload and use its materialized commands.
-`--base-url` is valid only for `login` in standalone mode.
-
-## Input Contract
-
-- `chatId`: 1-128 ASCII letters, digits, dot, underscore, or hyphen.
-- `file`: absolute path to a readable regular, non-symlink file.
-- `module`: 1-64 ASCII letters, digits, dot, underscore, or hyphen.
-- `context-file`: optional absolute path to a UTF-8 JSON object up to 64 KiB.
-  Object keys cannot override protocol fields; nested unsafe object keys and
-  nesting deeper than 12 levels are rejected.
-- `timeout`: optional positive seconds up to 3600.
-- `provider-timeout`: optional positive seconds up to 3600.
-- `user-confirmed`: mandatory for `upload` and valid only for the current user
-  request and file.
-- `login-mode`: `weaver-e10-login` or `standalone`. Failure never changes it.
-
-Reserved fields are published by `references/file-upload-cli-contract.json`. Known optional
-context fields and their purposes are in `references/file-upload-input-parameters.md`.
-
-## Upload Strategies
-
-Every file-bearing multipart request emits a sanitized quoted `filename`
-fallback and an RFC 5987 `filename*=UTF-8''...` value. The extended value
-percent-encodes UTF-8 bytes and the reserved characters `'`, `(`, `)`, and
-`*`, including filenames that combine Chinese text, spaces, and those
-characters.
-
-### `second`
-
-The preflight already returns an existing file object, so no upload body is
-sent. The file ID is resolved from direct data, `uploadModuleDto`,
-`imUploadInfoDto`, or their `fileObj`. A returned nonzero size must equal the
-local size.
-
-### `common`
+macOS/Linux（bash/zsh）：
 
-Require `preUploadId`, then stream the complete file once to
-`/api/file/module/upload`. The file is not loaded into one in-memory byte array.
-The response must contain a terminal file ID.
-
-### `chunk`
-
-Require `preUploadId` and a positive `chunkDto.chunkSize`, interpreted as MiB.
-Calculate local chunk count; if the server supplies `chunkCount`, it must match.
-Send zero-based slices with exact `uploadShardSize`, `chunk`, and `chunks`.
-Intermediate responses must be explicitly nonterminal. The final response must
-contain the terminal file ID.
-
-Unknown or empty upload types stop before an upload body is sent.
-
-## Business Validation
-
-- HTTP status is exactly 200 and redirects are rejected.
-- HTML and non-object JSON responses are rejected.
-- `status=false`, `success=false`, `fail=true`, or a non-success code is a
-  business failure.
-- Preflight data is an object; network branches include `preUploadId`.
-- Final file ID is nonempty; returned nonzero size equals local size.
-- `endChunk=true` without a file ID is not terminal success.
-
-Responses are bounded to 4 MiB. Raw responses, credentials, signed URLs, and
-multipart bodies are neither returned nor saved.
-
-## Result Contract
-
-Successful upload returns `weaver_file_upload_result.v1`:
-
-```json
-{
-  "status": "completed",
-  "business_verified": true,
-  "upload_type": "second|common|chunk",
-  "file": {
-    "file_id": "...",
-    "name": "...",
-    "size": 123,
-    "mime_type": "...",
-    "extension": "...",
-    "is_image": false
-  },
-  "integrity": {"md5": "...", "sha256": "..."},
-  "request_evidence": {
-    "module": "...",
-    "context_keys": [],
-    "context_sha256": "...",
-    "environment_identity_sha256": "...",
-    "login_mode": "weaver-e10-login|standalone",
-    "automatic_fallback": false
-  },
-  "receipt_ref": "/absolute/private/path.json",
-  "receipt_sha256": "..."
-}
+```bash
+weaver-work-cli --json caizhilian run caizhilian.file-upload.contract
+weaver-work-cli --json caizhilian run caizhilian.file-upload.prepare --input-json '{"file_path":"/data/report.pdf","module":"document"}'
+weaver-work-cli --json caizhilian run caizhilian.file-upload.upload.prepare --input-json '{"file_path":"/data/report.pdf","module":"document","user_confirmed":true,"chat_id":"current-chat"}'
+weaver-work-cli --json caizhilian run caizhilian.file-upload.upload.apply --input-json '{"file_path":"/data/report.pdf","module":"document","user_confirmed":true,"chat_id":"current-chat"}' --continuation TOKEN --yes
 ```
 
-Downstream consumers use only the normalized file object and receipt evidence.
-
-## Authentication Boundary
-
-Provider mode resolves only `e10-login whoami`. Its raw output remains in the
-child process boundary. The Node adapter bounds stdout, drains stderr, validates
-domain/session/identity fields, and calls the same business validator before
-use.
-
-Standalone mode resolves a runtime root from explicit input, environment, or
-this Skill's `.env.local`. Missing domain returns an Agent-conversation handoff.
-It launches an isolated Chrome, reads `DevToolsActivePort`, obtains same-origin
-cookies through CDP, and requires `ETEAMSID` plus a successful side-effect-free
-`teamsCheck` identity. It then atomically writes a `0600` session and closes the
-owned browser and process tree.
-
-## Failure And Recovery
+## 验证范围
 
-- Local validation and preflight rejection have no upload side effect.
-- A network error after common/chunk POST dispatch returns
-  `TRANSPORT_RESULT_UNKNOWN`, `execution_state=unknown`, and `retry_safe=false`.
-- Do not replay an outcome-unknown upload. A later user-authorized attempt begins
-  with a new `preUploadCheck` and is a separate transaction.
-- Missing terminal ID, early terminal chunk, inconsistent count, or size mismatch
-  is a hard failure with safe diagnostics only.
+`test/business/caizhilian-file-upload.test.ts` 使用本机 HTTP 服务验证真实 multipart 传输、
+三种上传策略、带小数毫秒的文件修改时间归一化、内容变更保护、授权门禁、回执和失败恢复。
+此验证不等于真实 E10 租户验证。

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"}'
@@ -87,6 +101,7 @@ weaver-work-cli --json caizhilian run caizhilian.compare.submit.prepare --input-
 - **下载类返回**：`{ 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

@@ -46,7 +46,15 @@
 | `caizhilian.folder.permission.add` | `folder_id`、`permission_type`、`obj_type` | `obj_id`、`obj_id_department`、`obj_id_subcompany`、`obj_id_role`、`obj_id_position`、`obj_id_customer`、`obj_id_customer_type`、`department_attribute`、`role_level`、`position_level`、`position_attribute`、`position_level_department`、`position_level_subcompany` |
 | `caizhilian.folder.permission.delete` | `folder_id`、`permission_type`、`ids` | 无 |
 | `caizhilian.folder.permission.set-auth` | `folder_id`、`permission_type`、`value`（`true`/`user`/`false`） | 无 |
-| `caizhilian.folder.permission.sync-setting` | `id`（文件夹 ID） | `keepOldSettingForAllFolders`（默认 false） |
+| `caizhilian.folder.permission.sync-setting` | `id`（文件夹 ID）、`keepOldSettingForAllFolders` | 无 |
+| `caizhilian.folder.permission.sync-maintain` | `id`（文件夹 ID）、`keepOldSettingForAllFolders` | 无 |
+| `caizhilian.folder.permission.sync-download` | `id`（文件夹 ID） | `keepOldSettingForAllFolders`（仅当下载权限为"允许以下人员下载"时必填） |
+| `caizhilian.folder.permission.sync-delete` | `id`（文件夹 ID） | `keepOldSettingForAllFolders`（仅当删除权限为"允许以下人员删除文档"时必填） |
+| `caizhilian.folder.permission.sync-copy` | `id`（文件夹 ID）、`keepOldSettingForAllFolders` | 无 |
+| `caizhilian.folder.permission.sync-create` | `id`（文件夹 ID）、`keepOldSettingForAllFolders` | 无 |
+| `caizhilian.folder.permission.sync-move` | `id`（文件夹 ID）、`keepOldSettingForAllFolders` | 无 |
+| `caizhilian.folder.permission.sync-participant` | `id`（文件夹 ID）、`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） |
+| `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`。
@@ -65,6 +73,14 @@ weaver-work-cli --json caizhilian run caizhilian.folder.create.prepare --input-j
 weaver-work-cli --json caizhilian run caizhilian.folder.create.apply --input-json '{"name":"2026 合同","parent_id":"456","parent_type":"company","inherit_parent":true}' --continuation TOKEN --yes
 weaver-work-cli --json caizhilian run caizhilian.folder.permission.set-auth.prepare --input-json '{"folder_id":"456","permission_type":"downloadPremisstion","value":"user"}'
 weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-setting.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-maintain.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-download.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-delete.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-copy.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-create.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-move.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-participant.prepare --input-json '{"id":"456","sync_to_all_folders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-default-share.prepare --input-json '{"id":"456","sync_to_all_folders":true}'
 ```
 
 macOS/Linux（bash/zsh）：
@@ -77,6 +93,14 @@ weaver-work-cli --json caizhilian run caizhilian.folder.create.prepare --input-j
 weaver-work-cli --json caizhilian run caizhilian.folder.create.apply --input-json '{"name":"2026 合同","parent_id":"456","parent_type":"company","inherit_parent":true}' --continuation TOKEN --yes
 weaver-work-cli --json caizhilian run caizhilian.folder.permission.set-auth.prepare --input-json '{"folder_id":"456","permission_type":"downloadPremisstion","value":"user"}'
 weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-setting.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-maintain.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-download.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-delete.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-copy.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-create.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-move.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-participant.prepare --input-json '{"id":"456","sync_to_all_folders":true}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-default-share.prepare --input-json '{"id":"456","sync_to_all_folders":true}'
 ```
 
 ## 输出处理
@@ -92,7 +116,7 @@ weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-setting.
 - `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 }`。
+- 写操作 `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。
 
@@ -101,7 +125,11 @@ weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-setting.
 - 文件夹权限与默认共享是**影响面很大的配置**：改错会导致整个知识库的下载、复制、新建权限对全员开放或全部收紧。`permission.set-auth` 从 `user` 改成 `true` 等于放开给所有人，确认摘要里必须显式写出这一后果。
 - `folder.create` 会在服务端产生新节点；`inherit_parent=true` 会连带继承父文件夹的权限与默认设置，必须在确认摘要里说明。
 - 删除类（`default-share.delete` / `permission.delete`）必须先做一次对应 `list` 只读查询，把待删条目的可读信息展示给用户后再 prepare。
-- `permission.sync-setting` 会将当前文件夹的管理员权限设置同步到所有下级子文件夹，**执行前必须提醒用户此操作对系统性能可能有一定影响**。`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`。
 
 ## 失败处理