weaver-work-cli 0.1.8 → 0.1.21

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

@@ -0,0 +1,173 @@
+---
+name: weaver-file-collection
+description: "泛微E10采知连文件服务 FTP/SFTP 文件采集技能。用于选择仅采集文件或采集到档案、按需选择全宗、查询或创建 FTP/SFTP 资源、检索并校验已有动作流、动态新建动作流、创建或维护采集任务，以及校验、扫描、运行和查看文件级结果。"
+license: Proprietary
+compatibility: 泛微E10采知连配套使用，内部可自由使用与修改，禁止对外分发
+metadata:
+  maintainer: unknown
+  type: capability
+  version: 1.0.0
+  updated: 2026-08-19
+  tags: [文件采集, FTP, SFTP, 动作流, 采集任务, 全宗, 档案]
+---
+
+# 文件采集 FTP/SFTP
+
+本 Skill 通过 `scripts/collection_cli_tool.py` 管理文件采集生命周期。正式 API 请求、动作流设计物化和任务 Payload 均由脚本生成，不手写正式结构。
+
+## 前置依赖
+
+### 认证前置（必须）
+
+本模块通过 CLI 托管的认证获取凭证（base_url + Cookie + eteamsid + User-Agent），凭证契约见共享规则 [`../../weaver-e10-shared/SKILL.md`](../../weaver-e10-shared/SKILL.md)，不依赖手动配置文件，Agent 不得自己读取或输出凭证。
+
+**使用前必须确保**：
+1. CLI 已安装：`weaver-work-cli --version` 能正常输出版本号
+2. 已完成登录：`weaver-work-cli auth status` 显示已登录
+
+**首次登录**：
+```text
+# OAuth2.0 浏览器授权（推荐）
+weaver-work-cli auth login
+
+# 或手动写入 ETEAMSID（从浏览器 DevTools 复制）
+weaver-work-cli auth set --eteamsid "PCACCOUNT_xxx"
+```
+
+**凭证过期处理**：操作返回认证错误时，提示用户通过 `weaver-work-cli auth login` 或 `weaver-work-cli auth set` 重新登录。
+
+## First Move
+
+1. 读取 `rule-index.md`。
+2. 确认 CLI 已完成登录（`weaver-work-cli auth status` 显示已登录）。
+3. 任务分支和阶段门禁读取 `task-workflow.md`。
+4. 动作流检索、检测与动态创建读取 `action-flow.md`。
+5. 只有用户选择采集到档案时，才读取 `fonds-selection.md`。
+6. 宿主执行还必须读取 `host-executor-prompt.md` 和 `host-platform-integration.md`。
+
+## Hard Rules
+
+- 认证凭证统一由 CLI 托管（`weaver-work-cli auth ...`）；不得写死域名或输出 Cookie。
+- `init-session` 后先执行 `choose-file-only` 或 `choose-archive`。仅归档分支查询和确认全宗；仅文件分支不得要求或写入 `fondsId`。
+- 新建任务前选择已有或新建 FTP/SFTP 资源，再选择已有或新建动作流。
+- 新建任务时先确定是否维持原目录结构；该值必须原样传给动作流 inspect/create 和 `save-task`。维持模式使用动态 `folderId` 动作流，非维持模式使用固定目录动作流，二者不得混用。
+- `search-action-flows` 的候选仅用于展示。用户确认 ID 后必须执行 `inspect-action-flow`，回读应用、活动版本和设计并通过兼容性检测，才能生成关联凭据。
+- `create-action-flow` 使用 `file_collection_action_flow_design.v1` 动态创建；禁止上传、迁入或依赖固定动作流包。
+- 标准 `create-action-flow` 由 CLI 生成仅文件/归档两种完整草稿；普通执行不得让 Agent 手写触发字段或设计文件，`--design-file` 仅用于明确的高级定制。
+- 标准 `create-ftp-resource` 在未传 `systemPk` 时自动生成连接器元数据并创建 FTP 连接器；不得通过失败重试发现确定性参数。
+- 初始化后的命令携带同一 `chatId`；阶段会原子保存，重复初始化恢复进度，只有显式 `--restart` 才重新开始。
+- `save-task` 和 `update-task-workflow` 只接受 `inspect-action-flow` 或 `create-action-flow` 生成的 `file_collection_workflow_selection.v1` 文件。归档凭据还必须绑定归档兼容检测，并携带已确认全宗。
+- 默认任务名按 UTC+8 生成 `文件采集（yyyyMMdd HHmmss）`。
+- `scan` 默认增量；只有用户明确要求全量时使用 `--full-coll`。
+- `run` 只证明启动。只有 `file_collection_result.v1` 为 `collection_succeeded`、`file_collection_ok=true` 且失败数为 0，才能报告采集成功。
+- 用户可见输出不展示长 ID、完整 Cookie、明文 FTP 密码或大段请求体。
+
+## Workflow
+
+1. 确认 CLI 已完成登录（`weaver-work-cli auth status`），然后执行 init-session --chat-id <chatId>。
+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]`。
+6. 用相同目录选项和关联凭据执行 `save-task --retain-dir-struct <0|1> --source-id ... --workflow-selection-file ...`；归档分支额外传全宗确认文件。
+7. 依次执行 `check-storage`、`scan --wait`、`run`；需要等待文件级结果时使用 `run --wait` 或 `run-progress`。
+
+## References
+
+| Need | Read |
+| --- | --- |
+| 规则与 owner | `rule-index.md` |
+| 认证 | `auth-and-session.md` |
+| 主流程 | `task-workflow.md` |
+| 动作流合同 | `action-flow.md` |
+| 可选全宗 | `fonds-selection.md` |
+| API 路由 | `api_docs.md` |
+| API 端点 | `api-endpoints.md` |
+| Payload | `api-payloads.md` |
+| 宿主提示词 | `host-executor-prompt.md` |
+| 宿主集成 | `host-platform-integration.md` |
+
+# API Endpoints
+
+## Connector And Resource
+
+| Operation | Method | Path |
+| --- | --- | --- |
+| Save connector | POST | `/api/bs/esb/setting/systemPool/save` |
+| Query connectors | GET | `/api/bs/esb/setting/connector/getConnectorListPage` |
+| Query resources | GET | `/api/bs/esb/setting/resource/getResourceListPage` |
+| Save FTP/SFTP resource | POST | `/api/bs/esb/setting/resource/ftp/save` |
+
+The selected resource `id` becomes `taskSourceId`.
+
+## Action Flow
+
+| Operation | Method | Path |
+| --- | --- | --- |
+| Search applications | POST | `/api/bs/esb/setting/application/getApplicationListPage` |
+| Read application | GET | `/api/bs/esb/setting/application/getAppById/{appId}` |
+| Read versions | GET | `/api/bs/esb/setting/application/version/versionList/{appId}` |
+| Read design | GET | `/api/bs/esb/setting/flow/design/getDesignBySceneId/{sceneId}` |
+| Create application | POST | `/api/bs/esb/setting/application/save` |
+| Register optional variable | POST | `/api/bs/esb/setting/application/variable/addVariable` |
+| Check design | POST | `/api/bs/esb/setting/flow/design/check` |
+| Save design | POST | `/api/bs/esb/setting/flow/design/saveDesign` |
+| Enable application | GET | `/api/bs/esb/setting/application/startUseApp/{appId}` |
+
+Search results are not association credentials. Inspect or create must complete full read-back validation.
+
+## File Collection Task
+
+| Operation | Method | Path | Result |
+| --- | --- | --- | --- |
+| List tasks | GET | `/api/file/coll/taskTable` | candidates |
+| Read form | GET | `/api/file/coll/taskForm` | task form |
+| Save task | POST | `/api/file/coll/save` | task ID |
+| Save as | POST | `/api/file/coll/saveAs` | copied task |
+| Check storage | GET | `/api/file/coll/checkStorageConnect` | connection result |
+| Scan | POST | `/api/file/coll/scan` | runtime ID |
+| Scan progress | GET | `/api/file/coll/scan/progress` | scan state |
+| Run or pause | POST | `/api/file/coll/run` | accepted state |
+| Run progress | GET | `/api/file/coll/run/progress` | execution state |
+| Detail | GET | `/api/file/coll/detailTable` | successful or failed rows |
+| Cancel | POST | `/api/file/coll/cancel` | cancelled task |
+| Delete | POST | `/api/file/coll/delete` | boolean result |
+
+`scan` is 默认增量 and sends `fullColl=false`; `--full-coll` is explicit. `finish=true` is not file success. Read `detailType=true` and `detailType=false`, then normalize `file_collection_result.v1`.
+
+## CLI 操作
+
+### 新建采集任务
+
+使用 `caizhilian.file-collection.task.save.prepare/apply` 创建新的采集任务：
+
+**参数**：
+- `source_id`（必填）：FTP/SFTP 资源 ID
+- `workflow_id`（必填）：动作流 ID
+- `task_name`（可选）：任务名称，不传时自动生成
+- `retain_dir_struct`（可选）：是否维持原目录结构，默认 true
+- `task_file_path`（可选）：采集路径，默认 /
+
+**示例**：
+
+Windows PowerShell：
+```powershell
+weaver-work-cli --json caizhilian run caizhilian.file-collection.task.save.prepare --input-json '{"source_id":"123","workflow_id":"456","task_name":"测试采集任务"}'
+```
+
+macOS/Linux（bash/zsh）：
+```bash
+weaver-work-cli --json caizhilian run caizhilian.file-collection.task.save.prepare --input-json '{"source_id":"123","workflow_id":"456","task_name":"测试采集任务"}'
+```
+
+### 其他操作
+
+| 操作 | CLI 命令 |
+| --- | --- |
+| 列出任务 | `caizhilian.file-collection.task.list` |
+| 查看任务详情 | `caizhilian.file-collection.task.form` |
+| 检查存储连接 | `caizhilian.file-collection.storage.check` |
+| 扫描任务 | `caizhilian.file-collection.scan.prepare/apply` |
+| 运行任务 | `caizhilian.file-collection.run.prepare/apply` |
+| 取消任务 | `caizhilian.file-collection.cancel.prepare/apply` |
+| 删除任务 | `caizhilian.file-collection.delete.prepare/apply` |

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

@@ -0,0 +1,309 @@
+---
+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
+
+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.
+
+## 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.
+
+## 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>']
+```
+
+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`
+
+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": "..."
+}
+```
+
+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.

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

@@ -0,0 +1,120 @@
+# 采知连文件类操作：附件、封面、文档比对
+
+## 何时使用
+
+- 用户要给某篇文档**上传/替换附件**，或把附件**下载到本地**（含转 PDF 版本）。
+- 用户要给文档**设置封面图片**、只上传封面图片拿 `file_id`，或**移除封面**。
+- 用户要做**文档比对**：找可比对的文档、列出文档下可比对的文件对象、上传本地文件参与比对、提交左右两个文件拿比对链接。
+
+> 文件类操作会读写用户本地磁盘，并把本地文件内容上传到 E10。**任何涉及附件、图片的上传/下载，都必须先向用户展示文件路径、文件名、大小，并取得明确确认后再执行**；文件内容不得进入大模型上下文。
+
+## 输入要点
+
+### 附件（attachment）
+
+| operation | risk | 必填 | 可选 |
+| --- | --- | --- | --- |
+| `caizhilian.attachment.upload.prepare` / `.apply` | read-before-write / read-with-upload | `file_path`、`doc_id` | `folder_id` |
+| `caizhilian.attachment.replace.prepare` / `.apply` | read-before-write / read-with-upload | `file_path`、`doc_id`、`attachment_id`、`folder_id` | 无 |
+| `caizhilian.attachment.download` | local-file-write | `attachment_id`、`doc_id` | `save_path` |
+| `caizhilian.attachment.download-as-pdf` | local-file-write | `attachment_id`、`doc_id` | `save_path` |
+
+- `upload` 是新增附件；`replace` 走源 `reUpload`，**保留原附件 ID**（旧文件版本被顶替），所以 `attachment_id` 与 `folder_id` 都是必填，必须先用 `caizhilian.document.get` 或 `caizhilian.compare.list-file-objects` 拿到真实附件 ID。
+- `download` 的 `save_path` 可以是**完整文件路径**，也可以是以 `/` 或 `\` 结尾的**目录**（目录时文件名取自响应头 `content-disposition`，已过滤路径穿越字符）。
+- 未传 `save_path` 且没有配置默认下载目录时直接报 `no_save_path`（源 `assets/config.json` 的 `http.download.default_dir` 为空，CLI 侧不提供默认目录），必须让用户给出保存位置。
+- `download-as-pdf` 会先调 `/api/file/download/toPdf?fileId=<attachment_id>` 预检，服务端返回不支持时报 `pdf_not_supported`；支持时带 `downloadToPdf=true` 下载 PDF 版本。
+- 下载单文件上限 **100MB**，超限报 `file_too_large`；下载/上传超时 **120 秒**（普通接口 12 秒）。
+- 同名文件已存在时按源的 `rename` 策略自动改名为 `名称(1).扩展名`、`名称(2).扩展名`……**不覆盖**已有文件。
+
+### 封面（cover）
+
+| operation | risk | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `caizhilian.cover.upload.prepare` / `.apply` | read-before-write / read-with-upload | `file_path` | 只上传图片拿 `file_id`，**不改任何文档** |
+| `caizhilian.cover.set.prepare` / `.apply` | read-before-write / read-with-upload | `doc_id`、`file_path` | 上传图片后把 `coverPictureId` 写到文档基础字段 |
+| `caizhilian.cover.remove.prepare` / `.apply` | read-before-write / high-risk-write | `doc_id` | 把 `coverPictureId` 置空 |
+
+- 封面图片扩展名白名单（源 `IMAGE_ALLOWED_EXT`）：`.bmp`、`.gif`、`.jpeg`、`.jpg`、`.png`、`.webp`；不在白名单报 `file_type_not_allowed`。
+- `cover.set` 是**两步服务端写入**（先上传、再改文档字段），中途失败可能出现「图片已上传但封面未生效」，此时不要自动重放，先 `document.get` 回查。
+
+### 文档比对（compare）
+
+| operation | risk | 必填 | 可选 |
+| --- | --- | --- | --- |
+| `caizhilian.compare.search-documents` | read | 无 | `name`、`author`、`creator`、`create_time`、`folder`、`page_no`(1)、`page_size`(20) |
+| `caizhilian.compare.list-file-objects` | read | `doc_id` | 无 |
+| `caizhilian.compare.upload-file.prepare` / `.apply` | read-before-write / read-with-upload | `file_path` | 无 |
+| `caizhilian.compare.submit.prepare` / `.apply` | read-before-write / external-artifact | `left_file_id`、`right_file_id` | 无 |
+
+- 典型链路：`search-documents` 或 `list-file-objects` 拿到左右两侧的 `file_id` → （本地文件则 `upload-file` 拿 `file_id`）→ `submit` 得到 `compare_link`。
+- `submit` 的 13 个比对选项在源里**全部固定为 0**，CLI 1:1 沿用，不暴露给用户配置。
+- `compare_link` 是**外部制品**：CLI 只返回链接，不代下载、不代打开。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json caizhilian run caizhilian.attachment.upload.prepare --input-json '{"doc_id":"1234567890","file_path":"C:\\data\\合同.pdf"}'
+weaver-work-cli --json caizhilian run caizhilian.attachment.upload.apply --input-json '{"doc_id":"1234567890","file_path":"C:\\data\\合同.pdf"}' --continuation TOKEN --yes
+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.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"}'
+weaver-work-cli --json caizhilian run caizhilian.compare.submit.prepare --input-json '{"left_file_id":"888","right_file_id":"999"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json caizhilian run caizhilian.attachment.upload.prepare --input-json '{"doc_id":"1234567890","file_path":"/tmp/data/contract.pdf"}'
+weaver-work-cli --json caizhilian run caizhilian.attachment.upload.apply --input-json '{"doc_id":"1234567890","file_path":"/tmp/data/contract.pdf"}' --continuation TOKEN --yes
+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.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"}'
+weaver-work-cli --json caizhilian run caizhilian.compare.submit.prepare --input-json '{"left_file_id":"888","right_file_id":"999"}'
+```
+
+## 输出处理
+
+- **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 表格摘要「文件名/类型/大小/更新时间」。
+- `compare.search-documents` 与 `document.search` 同构（`{ page_no, page_size, has_next, documents[] }`），参见 `document.md`。
+- `compare.submit.apply` 返回 `{ compare_link }`，把链接原样交给用户，不要尝试抓取链接内容。
+
+## 注意
+
+- **附件、图片属于用户私有数据**：上传前必须让用户确认文件路径与目标文档；下载前必须确认保存位置。文件二进制内容**不得读入大模型上下文**，只能引用路径、文件名、大小、MD5 这类元数据。
+- 用户只说「把那个文件传上去」时，**必须先取得明确确认**（哪个文件、传到哪篇文档），不要自行猜测路径或复用上一次的路径。
+- `attachment.replace` 会顶替原附件内容且**不可撤销**，确认摘要里必须写明被替换的 `attachment_id` 与文件名。
+- `cover.remove` 是 high-risk-write：封面移除后需要重新上传才能恢复，确认摘要要说明后果。
+- prepare 之后如果本地文件被改动（MD5 或大小变化），apply 会报 `file_changed`，必须重新 prepare——不要试图绕过。
+- 上传/下载是**长耗时操作**（120 秒超时）：一次只跑一个，不要并发批量上传；批量建文档请用 `document.create-by-upload`（见 `document.md`）。
+- `compare.upload-file` 上传前会走比对模块的上传凭证权限校验（合约中以 `permissions` 标记为 `compare.upload`）；校验失败时原样转述错误，不要重试或改用其他接口绕行。
+- 下载会写本地磁盘，属于 CLI 的 local-file-write 能力：只在用户指定的目录内写入，不要自作主张落到仓库工作区或系统目录。
+
+## 失败处理
+
+| error.subtype | 触发场景 | 处理 |
+| --- | --- | --- |
+| `file_not_found` | 路径不存在或不是文件 | 让用户确认路径，不要猜 |
+| `file_unreadable` | 文件被占用或无读权限 | 提示关闭占用程序后重试一次 |
+| `file_path_invalid` | `file_path` 为空 | 补齐后重试 |
+| `file_type_not_allowed` | 扩展名不在白名单（封面图片、Office 建文档、替换正文各有白名单） | 转述支持的扩展名清单给用户 |
+| `file_too_large` | 下载内容超过 100MB | 告知上限，建议改用 E10 页面下载 |
+| `no_save_path` | 下载未给 `save_path` 且无默认目录 | 向用户索要保存路径 |
+| `pdf_not_supported` | 该附件不支持转 PDF | 改用 `attachment.download` 下原文件 |
+| `file_changed` | prepare 后本地文件被修改 | 重新 prepare |
+| `upload_precheck_invalid` | 预上传检查响应缺 `preUploadId`/`uploadType` | 停止，把 message 交给用户 |
+| `permission_denied` | 预上传检查返回无 `upload` 权限 | 转述给用户，不要重试 |
+| `field_required` | `doc_id` / `attachment_id` / `folder_id` 为空 | 先用只读操作补齐真实 ID |
+| `plan_changed` / `continuation_*` | 请求体指纹或票据校验失败 | 见 `write-protocol.md` |
+| `partial/write_uncertain` | 上传/改字段结果不确定 | 立即停止，最多补一次 `document.get` 或 `compare.list-file-objects` 只读回查，禁止重放 |