weaver-work-cli 0.1.7 → 0.1.20

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

@@ -0,0 +1,118 @@
+# 采知连文件夹：创建、虚拟文件夹、默认共享与权限设置
+
+## 何时使用
+
+- 用户要在公共/个人知识库里建文件夹，或按名称找文件夹 ID。
+- 用户要查/改文件夹的默认设置：默认共享人、默认参与人、文档权限（下载、复制、移动、删除、新建文档、新建文件夹、设置）。
+- 用户要按权限反查「哪些文件夹对某人/某部门开放了某项权限」。
+- 创建文档前需要拿 `folder_id`，或需要确认目标文件夹允许创建的文档类型。
+
+## 输入要点
+
+### 只读查询
+
+| operation | 必填 | 关键可选 |
+| --- | --- | --- |
+| `caizhilian.folder.query-by-name` | `folder_name` | `kb_type`（`company`/`privy`/`sys`，默认 `company`） |
+| `caizhilian.folder.search-virtual` | 无 | `name`、`page_no`、`page_size`（默认 50） |
+| `caizhilian.folder.get-settings` | `folder_id` | 无 |
+| `caizhilian.folder.list-default-shares` | `folder_id` | 旧名字段 `folderId`（源参数名）仍兼容；与新名同时出现且取值不一致会报 `alias_conflict` |
+| `caizhilian.folder.default-share.form` | `folder_id`、`category`（`creator`/`generic`） | 无 |
+| `caizhilian.folder.default-share.list` | `folder_id` | 无 |
+| `caizhilian.folder.permission.form` | `folder_id`、`permission_type` | 无 |
+| `caizhilian.folder.permission.list` | `folder_id`、`permission_type` | 无 |
+| `caizhilian.folder.permission.get-auth` | `folder_id`、`permission_type` | 无 |
+| `caizhilian.folder.permission.detail` | `folder_id`、`setting_type` | 无 |
+| `caizhilian.folder.permission.query` | `folder_ids`（数组） | 无 |
+| `caizhilian.folder.query-by-permission` | `permission_key`、`permissions` | `page_no`、`page_size`（默认 20） |
+
+枚举取值（**拼写 1:1 沿用源接口，注意 `Premisstion` 是源的拼写，不要自行改成 `Permission`**）：
+
+- `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`）
+
+`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`。
+
+### 写操作
+
+| operation | 必填 | 关键可选 |
+| --- | --- | --- |
+| `caizhilian.folder.create` | `name`、`parent_id`、`parent_type`（`company`/`privy`） | `sequence`（-9999~99999，默认 0）、`inherit_parent`（默认 false） |
+| `caizhilian.folder.default-share.add` | `folder_id`、`obj_type`、`share_level` | 11 个 `obj_id*` 数组 + `download`、`department_attribute`、`role_level`、`position_level`、`position_attribute`、`virtualCompany`、`createrPositionLevel`、`seclevel_min`、`seclevel_max` |
+| `caizhilian.folder.default-share.delete` | `folder_id`、`ids` | 无 |
+| `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`） | 无 |
+
+- `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`。
+- `download` 在 `share_level != 1` 且未传时默认按 `["download"]` 处理（源行为）。
+- `set-auth` 的 `value=user` 表示「按人员白名单」，此时白名单条目由 `permission.list` / `permission.add` 维护；`permission_auth_not_user` 表示当前权限类型不是 `user` 模式，需要先 `set-auth`。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json caizhilian run caizhilian.folder.query-by-name --input-json '{"folder_name":"财务","kb_type":"company"}'
+weaver-work-cli --json caizhilian run caizhilian.folder.get-settings --input-json '{"folder_id":"456"}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.list --input-json '{"folder_id":"456","permission_type":"downloadPremisstion"}'
+weaver-work-cli --json caizhilian run caizhilian.folder.create.prepare --input-json '{"name":"2026 合同","parent_id":"456","parent_type":"company","inherit_parent":true}'
+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"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json caizhilian run caizhilian.folder.query-by-name --input-json '{"folder_name":"财务","kb_type":"company"}'
+weaver-work-cli --json caizhilian run caizhilian.folder.get-settings --input-json '{"folder_id":"456"}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.list --input-json '{"folder_id":"456","permission_type":"downloadPremisstion"}'
+weaver-work-cli --json caizhilian run caizhilian.folder.create.prepare --input-json '{"name":"2026 合同","parent_id":"456","parent_type":"company","inherit_parent":true}'
+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"}'
+```
+
+## 输出处理
+
+- `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`），创建文档时的兜底来源。
+- `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`，不要自己拼。
+- `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 }`。
+- 权限/共享类写操作的 `prepare` 返回请求体预览 + `continuation`；向用户摘要时必须写清「哪个文件夹、哪项权限、给谁、什么级别」，并说明删除类操作不可撤销。
+- 列表类结果默认用 Markdown 表格摘要（文件夹名/路径/权限类型/对象/级别），不要原样贴 JSON。
+
+## 注意
+
+- 文件夹权限与默认共享是**影响面很大的配置**：改错会导致整个知识库的下载、复制、新建权限对全员开放或全部收紧。`permission.set-auth` 从 `user` 改成 `true` 等于放开给所有人，确认摘要里必须显式写出这一后果。
+- `folder.create` 会在服务端产生新节点；`inherit_parent=true` 会连带继承父文件夹的权限与默认设置，必须在确认摘要里说明。
+- 删除类（`default-share.delete` / `permission.delete`）必须先做一次对应 `list` 只读查询，把待删条目的可读信息展示给用户后再 prepare。
+- 本 reference 只覆盖文件夹与权限；文档级共享/参与人/标签见 `collaboration.md`。
+
+## 失败处理
+
+| error.subtype | 触发场景 | 处理 |
+| --- | --- | --- |
+| `enum_invalid` | `parent_type` / `permission_type` / `setting_type` / `permission_key` / `value` 取值非法 | 按上面的枚举修正，注意源的 `Premisstion` 拼写 |
+| `alias_conflict` | 同义的新旧字段（如 `folder_id` 与 `folderId`）同时出现且取值不一致 | 只保留 `folder_id` 后重试，不要两个都传 |
+| `folder_no_create_folder_permission` | 目标父文件夹不允许新建文件夹 | 转述给用户，提示需要文件夹管理权限 |
+| `permission_fields_required` | `obj_type` 要求的对象字段没传 | 先查 `*.form`，补齐对应 `obj_id*` |
+| `obj_type_not_configured` / `obj_type_not_supported` | `obj_type` 未在表单中配置或不被该接口支持 | 用 `form` 返回的 `obj_types[].id` 重新选 |
+| `permission_auth_not_user` | 权限类型不是 `user` 模式却维护白名单 | 先 `permission.set-auth` 设为 `user` |
+| `entries_not_found` | 待删除的 `ids` 在列表中不存在 | 重新 `list` 后取真实 ID |
+| `number_out_of_range` | ID 等大整数用 JSON 数字传入且超出安全整数范围 | 改成字符串重新传，不要原样重试（数字传入时已经被截断） |
+| `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` 只读回查，禁止自动重放 |

package/skills/weaver-e10-caizhilian/references/org-browser.md

@@ -0,0 +1,104 @@
+# 采知连组织人员浏览器：人员/部门/分部/岗位/角色/客户检索
+
+## 何时使用
+
+- 用户说的是人名、部门名、分部名，但共享、参与人、文件夹权限、作者变更都要 **ID**：先用本 reference 的浏览器检索把名称解析成 ID，再传给写操作。
+- 需要确认「当前登录人是谁」（个人知识库 `folder_id=300`、个人标签 `type=1`、创建人过滤 `creator_user_id` 都依赖它）。
+- `folder.default-share.form` / `folder.permission.form` / `share.form` 返回的 `obj_types[].id` 指明了要传哪一类对象，用对应的浏览器操作取该类对象的真实 ID。
+
+## 输入要点
+
+8 个浏览器检索操作入参完全一致，全部只读、无写操作：
+
+| operation | 源 operation | 解析对象 | 输出列表键 |
+| --- | --- | --- | --- |
+| `caizhilian.org.search-user` | `search_user` | 内部人员 | `users[]` |
+| `caizhilian.org.search-department` | `search_department` | 部门 | `departments[]` |
+| `caizhilian.org.search-subcompany` | `search_subcompany` | 分部/子公司 | `subcompanies[]` |
+| `caizhilian.org.search-external` | `search_external` | 外部人员 | `externals[]` |
+| `caizhilian.org.search-position` | `search_position` | 岗位 | `positions[]` |
+| `caizhilian.org.search-role` | `search_role` | 角色 | `roles[]` |
+| `caizhilian.org.search-customer` | `search_customer` | CRM 客户 | `customers[]` |
+| `caizhilian.org.search-customer-type` | `search_customer_type` | CRM 客户类型字典 | `customer_types[]` |
+
+公共入参：
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `keyword` | 否 | 快搜关键词。源按对象类型用不同的快搜字段（人员 `username`、角色 `role_name`、客户 `customer_name`、其余 `name`），CLI 已封装，调用方只传 `keyword` |
+| `page_no` | 否 | 页码，1-indexed，默认 `1` |
+| `page_size` | 否 | 每页条数，默认 `50` |
+
+另有 `caizhilian.user.current`（源 `fetch_current_user_info`）：**无入参**，返回 `{ employeeId, employeeName }`。
+
+`keyword` 留空等于「不按名称过滤」，服务端会返回该浏览器的默认首页数据，可用于让用户从列表里挑。
+
+## 命令
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json caizhilian run caizhilian.org.search-user --input-json '{"keyword":"张三","page_size":20}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-department --input-json '{"keyword":"财务"}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-subcompany --input-json '{"keyword":"上海"}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-position --input-json '{"keyword":"经理"}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-role --input-json '{"keyword":"文档管理员"}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-customer --input-json '{"keyword":"泛微"}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-customer-type --input-json '{"keyword":"重点"}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-external --input-json '{"keyword":"顾问"}'
+weaver-work-cli --json caizhilian run caizhilian.user.current
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json caizhilian run caizhilian.org.search-user --input-json '{"keyword":"张三","page_size":20}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-department --input-json '{"keyword":"财务"}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-subcompany --input-json '{"keyword":"上海"}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-position --input-json '{"keyword":"经理"}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-role --input-json '{"keyword":"文档管理员"}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-customer --input-json '{"keyword":"泛微"}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-customer-type --input-json '{"keyword":"重点"}'
+weaver-work-cli --json caizhilian run caizhilian.org.search-external --input-json '{"keyword":"顾问"}'
+weaver-work-cli --json caizhilian run caizhilian.user.current
+```
+
+## 输出处理
+
+- 统一分页外壳：`{ page_no, page_size, has_next, <列表键>: [...] }`。
+- `has_next` 的判定是**本页条数 >= page_size**（源行为；服务端 `total` 不可信，不要用它算总页数）。要翻页就 `page_no + 1` 再查一次，直到 `has_next=false`。
+- 各列表元素字段（源 `response_templates` 归一后的结果）：
+
+| 列表键 | 元素字段 |
+| --- | --- |
+| `users` | `id`、`name`、`department` |
+| `departments` | `id`、`name`、`sup_department`（上级部门名）、`parent_id`、`has_sub` |
+| `subcompanies` | `id`、`name`、`parent_id`、`sup_department` |
+| `externals` | `id`、`name` |
+| `positions` | `id`、`name`、`code` |
+| `roles` | `id`、`name` |
+| `customers` | `id`、`name` |
+| `customer_types` | `id`、`name` |
+
+- 回复用户时用 Markdown 表格摘要「名称 + 所属部门/上级 + ID」，**同名必须全部列出让用户选**，不要默认取第一条：同名人员、同名部门在不同分部下非常常见。
+- `caizhilian.user.current` 返回 `{ employeeId, employeeName }`，这就是当前登录人的 `user_id`，可直接用于 `document.search` 的 `creator_user_id`、`share.add` 的 `obj_id`、`tag.search` 的个人标签查询。
+- 解析出的 ID 一律按**字符串**传递（`obj_id`、`obj_ids`、`creator_user_id`、`user_id` 的 schema 都是 `^\d+$`）。
+
+## 注意
+
+- 本 reference 全是只读检索，不产生服务端副作用，可以放心多查几次；但**不要把整页 50 条原始 JSON 贴给用户**，只摘要前若干条 + 总数提示。
+- 浏览器检索结果受当前登录人的数据权限限制：查不到不等于不存在，可能是无权可见。此时应提示用户换一个更精确的关键词，或改由有权限的账号操作，不要反复重试。
+- `search-customer` / `search-customer-type` 走 CRM 接口，未启用 CRM 的环境会返回业务错误，转述给用户即可，不要当成「客户不存在」。
+- 不要把这些 ID 当成永久有效：组织架构调整后 ID 可能失效，写操作失败提示对象不存在时应重新检索。
+- 解析 ID 只是准备步骤；真正的共享/参与人/权限写入仍必须走 `prepare -> apply` 确认链，见 `write-protocol.md`。
+
+## 失败处理
+
+| error.subtype | 触发场景 | 处理 |
+| --- | --- | --- |
+| `field_empty` / `field_invalid` | `keyword` 传了非字符串 | 改成字符串或整条省略 |
+| `number_invalid` | `page_no` / `page_size` 不是正整数 | 用正整数重试一次 |
+| `empty_response` / `response_shape` | 服务端返回结构与预期不符 | 停止，把原始 message 交给用户 |
+| `session_unavailable` / `session_expired` | 未登录或登录态失效 | 按 `agent-entry.md` 引导重新登录，不要在业务侧猜 |
+| `http_error` / `business_error` | 接口返回非成功码 | 转述服务端 message，不要重试写操作 |
+| `network` (retryable) | 网络抖动 | 最多重试一次，仍失败则停止并告知用户 |

package/skills/weaver-e10-caizhilian/references/setting-attach.md

@@ -0,0 +1,410 @@
+---
+name: weaver-setting-attach
+description: "对话式修改\"文件设置 → 附件设置\"页面的 15 个配置项（上传最大、上传格式控制 方式、附件打开方式、批量下载、禁止移动端下载、附加提示、图片压缩、版本清理、 打印转 PDF 等）。通过自然语言 / `setting set --item key=value` 即可完成 GET 全量 → modify（保留原值） → diff 让用户确认 → POST 落库，无需打开 浏览器逐项点击。覆盖 weapp 端 `POST /api/file/tenant/setting` 与 `POST /api/file/tenant/setting/save` 两条接口。Use for 改附件设置、改上传 最大、改附件打开方式、改白名单黑名单、附件批量下载、禁止移动端下载、附加 提示、文件设置、文件上传、格式限制、图片压缩、版本清理、清理文件版本、 打印转 PDF、eteams-file 后台、<your-e10-domain>/info/fileSet/attach."
+license: Proprietary
+compatibility: 泛微E10采知连配套使用，内部可自由使用与修改，禁止对外分发
+metadata:
+  maintainer: unknown
+  type: capability
+  version: 1.0.0
+  updated: 2026-08-19
+  tags: [附件设置, 上传最大, 格式控制, 批量下载, 图片压缩, 版本清理, 打印转PDF]
+---
+
+# weaver-setting-attach
+
+让"文件设置 → 附件设置"页面**用对话就能改**。背后只调两条 HTTP 接口
+（`POST /api/file/tenant/setting` 拉全量 / `POST /api/file/tenant/setting/save`
+保存），改之前先 diff 让用户确认，**绝不会**误清空未指定字段。
+
+## 前置依赖
+
+### 认证前置（必须）
+
+本模块通过 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` 重新登录。
+
+## When to use
+
+- 用户说「把附件批量下载关了」「上传最大改成 2G」「白名单改成 png,jpg」
+  「禁止移动端下载附件打开」「图片音视频在新页签打开」等
+- 改 weapp 后台的"附件设置"页（`<your-e10-domain>/info/fileSet/attach`）
+- 需要批量修附件设置但不想打开浏览器一项项点
+- 调试 eteams-file 后台设置项
+- 出现「附件设置 / 上传设置 / 打开方式 / 批量下载 / 禁止移动端 / 附加提示 /
+  格式白名单黑名单 / 上传分片」等关键词
+
+不适用：存储设置、备份设置、文件采集设置、加解密设置、预览编辑设置、文件
+深度清理、页面设置——这些 Tab 走的是另一套接口（多数要 `POST /papi/file/...`），
+**不在本 skill 范围**。
+
+## 命令清单
+
+| 命令 | 作用 |
+|---|---|
+| `setting show` | 拉全量设置并以表格打印 |
+| `setting set --item <key=value> [--item ...] [--dry-run] [--yes]` | GET → 合并 → diff → 询问 → POST |
+| `setting diff --item ...` | 只打印 diff，不调任何接口 |
+
+## 15 个支持字段
+
+字段别名（中文 / 英文 / DTO 字段名）三选一即可：
+
+| 别名（key） | DTO 字段 | 类型 | 备注 |
+|---|---|---|---|
+| `upload-max` | `sysMaxSingleUploadSize` | 数字 + 单位（KB/MB/GB） | 不可超过 `sysMaxSingleUploadLimitSize` |
+| `shard-size` | `uploadShardSize` | 整数 MB | 1 ≤ n ≤ 50 |
+| `format-mode` | `sysFormatWhitesEnable` | `whitelist` / `blacklist` | 切换模式后会自动迁移 `format-list` |
+| `format-list` | `sysFormatWhites` 或 `sysFormatBlacks` | 逗号/分号分隔扩展名 | 自动按当前 mode 写到正确字段 |
+| `non-image-open` | `sysNonImageMediaOpenType` | `newTab` / `popupWindow` | 后端实际只有这两个值（v0.1.0 表格写的 dialog/directDownload 是错的，已纠正） |
+| `image-open` | `sysImageMediaOpenType` | `newTab` / `previewComponent` | |
+| `show-attach-list` | `sysPreviewShowAttachmentList` | bool | |
+| `attach-expand` | `sysAttachmentListDefaultExpand` | bool | |
+| `custom-msg` | `sysUploadCustomMsgEnable` (+ `sysUploadCustomMsg`) | bool (+ 文本) | 写 `custom-msg=true::安全提示文本` 一次性带上 |
+| `batch-download` | `sysBatchDownload` | bool | |
+| `mobile-block` | `sysAppDownload` | bool | 自然语义"禁止移动端下载"为 true（CLI true ↔ DTO true） |
+| `download-pdf-types` | `sysDownloadToPdfFileTypes` | 逗号分隔扩展名 | |
+| `img-compress` | `sysImgCompressEnable` | bool | 图片压缩总开关（关闭时子项 img-compress-quality 不生效） |
+| `img-compress-quality` | `sysImgCompressQuality` | `low` / `medium` / `high` | 压缩质量（仅在 img-compress 开启时生效） |
+| `auto-clear-version` | `sysAutoClearFileVersion` | bool | 文件版本自动清理总开关（关闭时子项 version-size / version-time 不生效） |
+| `version-size` | `sysFileVersionSize` | 整数(1-500) / `-1`(不限) | 每个文件最多保留多少个历史版本 |
+| `version-time` | `sysFileVersionTime` | 整数(1-1095) / `-1`(永久) | 每个文件的历史版本保留多少天 |
+| `print-pdf-types` | `sysPrintToPdfFileTypes` | 逗号分隔扩展名 | 打印时需要转 PDF 的扩展名（空 = 未启用，独立项） |
+| `version-clean-type` | `sysAutoClearFileVersionType` | `versionSize` / `versionTime` | 版本清理方式（按份数 / 按时间）—— v0.2.0 补 |
+| `version-size-type` | `sysFileVersionSizeType` | `selected` / `custom` | 份数那一行 UI 状态（selected = 选下拉 / custom = 自定义）—— v0.2.0 补 |
+| `version-time-type` | `sysFileVersionTimeType` | `selected` / `custom` | 时间那一行 UI 状态（selected = 选下拉 / custom = 自定义）—— v0.2.0 补 |
+
+完整别名表见 [setting-attach-field-map.md](setting-attach-field-map.md)。
+
+## 硬性门禁
+
+1. **写操作必须先 diff**——`set` 不带 `--dry-run` 也不带 `--yes` 时，强制把 diff
+   打到 stdout 并等用户在 stdin 输入 `y` 才发 POST；EOF / `n` / 非 `y` 全部视为取消。
+2. **`prod` 必加 --yes**——生产环境操作时必须同时带 `--yes` 才会发 POST，
+   防止手滑改生产。
+3. **只 POST changed 字段，不透传全量**——后端 `fileSettingSave` 是**逐字段 update**（遍历
+   DTO，非 null 字段调 `FileSetItemServiceProxy.updateSysFileItem`），且会用每个字段名
+   调 `FileobjTenantPermissionEnum.valueOf(key)`；**只读/虚拟字段**（如
+   `sysMaxSingleUploadLimitSize`、`id` 等）不在 enum 里，会抛
+   `IllegalArgumentException` 让整笔事务回滚。`set` 只把 diff 出的字段 POST 上去。
+4. **保存后再次 GET 校验**——POST 完调一次 `tenant/setting` 比对 diff，不一致立即
+   报错并打印服务端返回值。
+5. **不写日志到 home 之外**——所有凭证 / 日志只落在 `~/.minimax/skills/weaver-setting-attach/`
+   下，不写系统级。
+
+## 对话式交互规则
+
+> 这些是 **agent 在对话中使用本 skill 时**的硬约束,跟底层 CLI 脚本无关。
+> 命令行直接跑 `setting.py` 可以绕过,但任何经由本 skill 的 agent 流程都必须遵守。
+
+1. **操作前必查登录态**
+   每次执行业务操作前，确认 CLI 已完成登录：
+   - 若 `weaver-work-cli auth status` 显示未登录，提示用户执行 `weaver-work-cli auth login` 或 `weaver-work-cli auth set` 完成登录
+   - 登录完成后**立刻**继续用户原本的请求，不要让用户再敲一次命令
+
+2. **查询要简洁**(`show` / 读设置时的输出格式)
+   - **只返回三样**:**设置项名**(中文别名或 DTO 字段名)、
+     当前值、**当前租户名**
+   - **不要**返回:bool 三态展开、enum 解释、字段语义说明、风险提示、
+     "建议/可以这么做" 等附加内容 —— 这些只在用户追问时再说
+   - 多项查询时一行一项,格式固定:
+
+     ```
+     <租户名> · <设置项名>：<当前值>
+     ```
+
+3. **修改前必须三步问清**
+   - 步骤 a — **改前的值**:说清楚这一项当前是什么(从 GET 里取,不要瞎猜)
+   - 步骤 b — **改后影响**:说清楚改完会影响什么业务、放行/禁止哪些格式、
+     触及哪些用户,以及是否会**间接影响其他字段**(如 `format-mode` 切换会
+     迁移 `format-list` 到另一个 DTO 字段)
+   - 步骤 c — **明确询问**:用一句话问"要改成 X 吗?",**得到用户肯定回复
+     (y / 改 / 确认 / 好的 之类)才发 POST**,即使 CLI 已带 `--yes` 也不许跳过
+   - 三步可以一次消息里说全,但步骤 c 的问句**必须独立成行**,不能藏在
+     长段落里让人找不到
+
+4. **话术面向客户(非开发)**
+   本 skill 的对话对象是**客户/业务人员**,不是开发。所有输出话术:
+   - **禁止出现**:CLI key(`mobile-block`、`upload-max`、`format-list` 等)、
+     DTO 字段名(`sysAppDownload`、`sysMaxSingleUploadSize` 等)、布尔字面值
+     (`true` / `false`)、HTTP 术语(POST / GET / 200 / 401)、内部流程术语
+     ("步骤 a / 步骤 b / 步骤 c"、"diff"、"回 y / 改"、"落库"、"diff 让用户确认")
+   - **必须使用**:业务中文名("移动端禁止下载" 开关、"上传单文件最大"、
+     "黑白名单")、业务状态("已开启 / 已关闭 / 允许 / 禁止"、
+     "顶到上限 / 不会真生效")、自然语言确认("要打开吗?回 改 / 确认 / 好的")
+   - 需要看技术细节时(用户主动问"用的什么字段" / "接口是啥" / "为什么改不了"),
+     **只在该轮回应**展开,平时一律隐藏
+   - 身份信息隐藏 `userId` / `tenantKey` 这类内部 ID,只说"当前租户"
+
+5. **超上限引导**(以"上传单文件最大" 为典型场景;其他带硬上限的字段同款处理)
+   客户要把某项值改成**超过该租户硬上限**的数(常见就是"上传单文件最大"
+   超过当前租户的上限,比如上限 1 GB、客户要 2 GB):
+   - **不要**静默截断、**不要**自动改,直接告诉客户改不了 + 给出正确路径
+   - 口语化提示(无开发词):
+     "你要改成 X 已经超过你们租户的上限了(当前上限 Y),附件设置里调不了,
+     需要去『**租户平台 → 租户详情**』那里把上限先调高"
+   - 用口语化文字告知客户操作步骤(三步走):
+     1. 打开『**租户平台 → 租户管理**』,在列表里找到并点击要设置的租户
+     2. 进入租户详情页,点击右上角"编辑"
+     3. 在编辑页找到"单文件最大上传"输入框,填入需要的值,点击右上角"保存"
+   - 引导话术末尾加一句:
+     "在租户平台那里保存后,回到这里再让我帮你改附件设置里的对应项,
+     就能设到你想要的值了"
+
+## 宿主
+
+CLI 入口：
+
+```text
+python3 scripts/attach_setting.py <cmd> [args]
+```
+
+装好后 `setting show / set ...` 即可直接调用。
+
+
+## 与 weaver-im 的关系
+
+两者**不共享凭证**（`auth_opt2` 决策）。现在统一通过 CLI 托管的认证获取凭证。
+
+## 版本
+
+- 0.1.0（2026-08-06）首次创建。覆盖 eteams-file 截图"附件设置" Tab 的 11 字段。
+- 0.2.0（2026-08-09）补 6 字段：图片压缩(`img-compress` / `img-compress-quality`)、
+  版本清理(`auto-clear-version` / `version-size` / `version-time`)、
+  打印转 PDF(`print-pdf-types`)。这 3 类功能实际也在附件设置同一页
+  (`AttachSet/index.tsx`),0.1.0 时只覆盖 11 项漏了。同时修 `mobile-block`
+  alias 的 `invert=True` 方向写反 bug(CLI true 现在直接对应 DTO true)。
+# 接口协议
+
+## 端点
+
+| 操作 | 方法 | URL | 入参 | 出参 |
+|---|---|---|---|---|
+| 拉全量 | `POST` | `{baseUrl}/api/file/tenant/setting` | `{}`（body 留空对象） | `{status, data: FileSettingDto}` |
+| 保存 | `POST` | `{baseUrl}/api/file/tenant/setting/save` | `FileSettingDto`（全量） | `{status, data: FileSettingDto}` |
+
+`{baseUrl}` 例：`https://<your-e10-domain>`
+
+## 鉴权
+
+走 `Cookie: ETEAMSID=<id>`，与前端 `axios` 默认 cookie 行为一致。
+
+CLI 自动从 `.env.local` / ENV 读取并塞进 Cookie。
+
+## FileSettingDto 节选（11 字段 + 只读）
+
+完整 DTO 见 eteams-file 仓库 `BaseSetDto.java`。下面只列本 skill 关心的字段：
+
+```json
+{
+  "sysMaxSingleUploadSize": "1000",          // str (数字+单位)
+  "sysMaxSingleUploadLimitSize": "2048",     // str, 只读回传，写时透传
+  "uploadShardSize": 5,                      // int
+  "sysFormatWhitesEnable": true,             // bool, true=白名单
+  "sysFormatWhites": "*",                    // str, 逗号/分号分隔
+  "sysFormatBlacks": "",                     // str
+  "sysNonImageMediaOpenType": "dialog",      // enum: newTab/dialog/directDownload
+  "sysImageMediaOpenType": "previewComponent", // enum: newTab/previewComponent
+  "sysPreviewShowAttachmentList": true,      // bool
+  "sysAttachmentListDefaultExpand": true,    // bool
+  "sysUploadCustomMsgEnable": false,         // bool
+  "sysUploadCustomMsg": "",                  // str
+  "sysBatchDownload": true,                  // bool
+  "sysAppDownload": true,                    // bool (true=允许移动端下载)
+  "sysDownloadToPdfFileTypes": ""            // str
+}
+```
+
+未指定字段透传：CLI 先 GET 全量 → 把你传的字段 merge 进去 → POST 回去。**绝不会**清空未指定字段。
+
+## 错误码
+
+| HTTP | 业务 status | 含义 |
+|---|---|---|
+| 200 | `0` | 成功 |
+| 200 | 非 0 | 业务异常，看 `msg` 字段 |
+| 401/403 | — | ETEAMSID 失效/没权限，重跑 `setting login --config <name>` |
+| 5xx | — | 后端挂了，看日志 |
+
+## 后端实现位置（参考）
+
+- Controller：`eteams-file/src/main/java/com/weaver/teams/file/e10/mvc/web/FileSettingController.java`
+- DTO：`com.weaver.teams.file.e10.dto.FileSettingDto` / `BaseSetDto`
+- 设置项注册：`com.weaver.teams.file.e10.manager.set.FileSetFactory`
+- 前端调用：`weapp-file/src/api/fileSetApi.ts` 中 `fileSetDatas` / `fileSetSave`
+
+## POST 注意事项
+
+1. **保存是逐字段 update，不是覆盖式全量**。后端 `fileSettingSave` 遍历 DTO，对**非 null**
+   字段调 `FileSetItemServiceProxy.updateSysFileItem(...)`；null 字段跳过不处理。
+   意味着：未指定字段**不会被清空**（因为后端根本不动它们）。
+2. **但绝对不能透传只读/虚拟字段**——后端用每个字段名 `FileobjTenantPermissionEnum.valueOf(key)`，
+   `sysMaxSingleUploadLimitSize` 等虚拟字段不在 enum 里，会抛
+   `IllegalArgumentException: No enum constant ...` 让整笔事务回滚。
+3. **只 POST 改了的字段**。CLI 用 `field_map.diff` 算出 changed 字段后只发这一份。
+4. **服务端会校验范围**：传超范围值会返回业务异常（status=false / code=500），
+   CLI 会原样打印 `detailErrorMessage`。
+5. **操作日志**：`FileOpLogManager` 会记一条 `fileSetting` 日志（管理员可在"操作日志"里看到）。
+# 字段对照表（11 项）
+
+> 对应 eteams-file 后端 `BaseSetDto` / `FileSettingDto`。
+> 任意字段用 CLI key、中文别名、或 DTO 字段名（最后一个）都接受。
+
+## 1. 上传最大
+
+- **CLI key**：`upload-max`
+- **中文**：`上传最大` / `最大上传`
+- **DTO 字段**：`sysMaxSingleUploadSize`
+- **类型**：整数 + 单位
+- **单位**：`B / KB / MB / GB / TB`（单字母简写也行：`2G` ≡ `2GB`）
+- **示例**：
+  ```text
+  --item upload-max=2G         # 2048 MB
+  --item upload-max=2048MB
+  --item upload-max=512KB      # 1 MB（< 1MB 自动取整为 1）
+  ```
+- **校验**：不可超过 `sysMaxSingleUploadLimitSize`（GET 时带回），否则拒绝保存。
+
+## 2. 上传分片大小
+
+- **CLI key**：`shard-size`
+- **中文**：`上传分片大小` / `分片大小`
+- **DTO 字段**：`uploadShardSize`
+- **类型**：整数 MB
+- **范围**：1 ≤ n ≤ 50
+- **示例**：`--item shard-size=8`
+
+## 3. 上传格式控制方式
+
+- **CLI key**：`format-mode`
+- **中文**：`格式控制方式` / `黑白名单模式`
+- **DTO 字段**：`sysFormatWhitesEnable`（Boolean：true = 白名单）
+- **值**：`whitelist` / `blacklist`（也支持中文：`白名单` / `黑名单`）
+- **示例**：`--item format-mode=whitelist`
+
+## 4. 格式列表
+
+- **CLI key**：`format-list`
+- **中文**：`格式列表` / `白名单` / `黑名单` / `格式白名单` / `格式黑名单`
+- **DTO 字段**：按当前 mode 自动写到 `sysFormatWhites`（白名单 mode）或 `sysFormatBlacks`（黑名单 mode）
+- **类型**：字符串，扩展名列表
+- **分隔符**：`,` 或 `;` 都接受
+- **示例**：
+  ```text
+  --item format-mode=whitelist --item format-list='png,jpg,jpeg'
+  --item format-list='*'             # 全部（白名单下"*" = 允许所有）
+  --item format-list='exe,bat,sh'    # 黑名单下禁止这些
+  ```
+
+## 5. 非图片/音视频打开方式
+
+- **CLI key**：`non-image-open`
+- **中文**：`非图片音视频打开方式` / `非图片打开方式`
+- **DTO 字段**：`sysNonImageMediaOpenType`
+- **后端 enum**：`FileMediaOpenTypeEnum`（`newTab` / `popupWindow` 两个值，没有"直接下载"）
+- **值**：
+  | 英文 | 中文 | 含义 |
+  |---|---|---|
+  | `newTab` | 新页签 / 新窗口 | 浏览器新标签打开 |
+  | `popupWindow` | 弹出窗口 / 弹窗 | 弹出预览层 |
+- **示例**：`--item non-image-open=新页签`
+
+## 6. 图片/音视频打开方式
+
+- **CLI key**：`image-open`
+- **中文**：`图片音视频打开方式` / `图片打开方式`
+- **DTO 字段**：`sysImageMediaOpenType`
+- **后端 enum**：`FileMediaOpenTypeEnum`（`newTab` / `previewComponent` 两个值）
+- **值**：
+  | 英文 | 中文 | 含义 |
+  |---|---|---|
+  | `newTab` | 新页签 | 浏览器新标签打开 |
+  | `previewComponent` | 预览组件 / 预览 | 前端内置预览组件 |
+- **示例**：`--item image-open=预览组件`
+
+## 7. 预览时显示附件列表
+
+- **CLI key**：`show-attach-list`
+- **中文**：`预览显示附件列表` / `显示附件列表`
+- **DTO 字段**：`sysPreviewShowAttachmentList`
+- **类型**：Boolean
+- **值**：`true` / `false` / `1` / `0` / `开` / `关` / `启用` / `禁用`
+
+## 8. 附件列默认展开
+
+- **CLI key**：`attach-expand`
+- **中文**：`附件列默认展开` / `附件列表展开`
+- **DTO 字段**：`sysAttachmentListDefaultExpand`
+- **类型**：Boolean
+
+## 9. 附件附加提示
+
+- **CLI key**：`custom-msg`
+- **中文**：`附加提示` / `上传附加提示`
+- **DTO 字段**：`sysUploadCustomMsgEnable`（Boolean）+ `sysUploadCustomMsg`（String）
+- **复合写法**：`custom-msg=true::<文本>` 一次性写两个
+- **只改 bool 不改文本**：`--item custom-msg=true`
+- **示例**：
+  ```text
+  --item custom-msg=true::请勿上传公司机密文件
+  --item custom-msg=false   # 关闭附加提示（不抹掉原 msg 字段）
+  ```
+- **注意**：单独写 bool 时，旧 msg 文本**会保留**（merge 时透传 current 里的值）；要清空 msg 需显式：
+  ```text
+  --item custom-msg=false --item sysUploadCustomMsg=
+  ```
+  （第二个写法直接用 DTO 字段名也能接受，**逃生口**。）
+
+## 10. 附件批量下载
+
+- **CLI key**：`batch-download`
+- **中文**：`附件批量下载` / `批量下载`
+- **DTO 字段**：`sysBatchDownload`
+- **类型**：Boolean
+
+## 11. 禁止移动端下载附件
+
+- **CLI key**：`mobile-block`
+- **中文**：`禁止移动端下载` / `移动端禁止下载`
+- **DTO 字段**：`sysAppDownload`（**语义取反**：CLI true → DTO false）
+- **类型**：Boolean
+- **示例**：
+  ```text
+  --item mobile-block=true    # 禁止移动端下载
+  --item mobile-block=false   # 允许移动端下载
+  ```
+
+## 12. 下载需要转 PDF 的文件格式
+
+- **CLI key**：`download-pdf-types`
+- **中文**：`下载转PDF格式` / `下载转pdf`
+- **DTO 字段**：`sysDownloadToPdfFileTypes`
+- **类型**：字符串，逗号分隔扩展名
+- **示例**：`--item download-pdf-types='doc,docx,xls,xlsx'`
+
+---
+
+## 逃生口
+
+任意字段也支持直接用 DTO 字段名（snake case 必须小写）作为 key。
+不推荐，仅供复杂场景使用——CLI 会**完全信任**你的值不做校验（除了 merge 时的范围检查）。
+
+```text
+--item sysMaxSingleUploadSize=2048
+--item sysAppDownload=false
+--item sysUploadCustomMsg=   # 清空 msg
+```