weaver-work-cli 0.1.20 → 0.1.22

package/docs/e10-auth.md

@@ -10,6 +10,10 @@ E10 适配模块刻意与核心 CLI 框架隔离，避免平台逻辑污染通
 - Keychain service/account：`weaver-work-cli` / `auth-key`
 - 发票业务 Token Keychain service：`cn.weaver.weaver-work-cli.invoice-token`
 
+发票业务 Token 的 Keychain 缓存是可选的性能优化。在没有系统密钥环的
+Web/Linux 环境中，CLI 不会把 Token 写入明文文件，而是仅在当前命令进程内保存并
+继续完成业务请求；下一次命令会重新向 E10 获取 Token。
+
 `weaver-work-cli` 默认不读取、不迁移 `e10-login` / `e10-cli` 的旧 `.e10-cli`
 登录态，避免用户安装本插件后因为历史登录状态被自动授权。确需复用外部 auth
 文件时，可以显式传 `--auth <path>` 或设置 `E10_AUTH_PATH`。
@@ -38,9 +42,11 @@ weaver-work-cli auth export-weaver-env
 环境变量推断当前宿主，最后回落为 `weaver-work-cli`。浏览器授权地址会同时携带
 `agent_type=<value>` 和 `from=<value>`，其中 `from` 用于 E10 授权确认页展示客户端名称。
 
-XiaoE 宿主环境中，`auth login` / `auth oidc` / `auth xiaoe` 先使用平台注入的 `XIAOE_USER_TOKEN` + `XIAOE_DOMAIN` 换取 ETEAMSID（沙箱/Linux 环境唯一可用来源）；拿不到时再读宿主 `xiaoeUserData/tokens.py`；仍不可用时改用内置的原生等价实现读取桌面 XiaoE 客户端本地会话（macOS `~/Library/Application Support/XiaoE/Robots/<id>/user_settings.json`，Windows `%LOCALAPPDATA%/XiaoE/Robots/<id>/user_settings.json`），该链路不依赖本机 Python 环境；仍没有可用凭证时，再从 `WEAVER_XIAOE_*` 环境变量读取当前域名对应的统一登录凭证。宿主只注入 `XIAOE_DOMAIN` 等域名变量和 `XIAOE_USER_TOKEN` 凭证变量，不会注入 ETEAMSID 环境变量，CLI 也不读取 `XIAOE_ETEAMSID`。凭证可用时，CLI 直接保存登录态，保存的 `agentType` 固定为 `XiaoE`；凭证只返回 `eteamId` 时，会优先使用凭证中的域名或宿主注入的 `XIAOE_DOMAIN`（支持省略 `https://` 前缀），没有时才用资料包默认域名 `https://www.e-cology.com.cn`；仍没有可用凭证时才考虑当前 profile 配置。业务命令在未显式指定 `--auth` / `--profile` 时，也会自动优先尝试 XiaoE 统一登录。XiaoE 凭证校验失败、当前域名不在支持范围内，或用户切换了访问域名时，`auth xiaoe` 会先反馈未拿到登录信息的原因，再自动降级到原浏览器 OAuth2.0 登录。
+XiaoE 宿主环境中，`auth login` / `auth oidc` / `auth xiaoe` 先使用平台注入的 `XIAOE_USER_TOKEN` + `XIAOE_DOMAIN` 换取 ETEAMSID（沙箱/Linux 环境唯一可用来源）。这里的 `XIAOE_DOMAIN` 是 XiaoE/erpa 换票服务地址，不是 E10 登录地址。Node 主路径调用与 `xiaoe_env.py` / `tokens.py` 相同的接口，校验业务 `code`（`"0000"` 或 `200`）及 `data.eteamId`，保留系统 CA 校验，并只跟随同源重定向或同主机 HTTP→HTTPS 升级。Node 路径失败时，CLI 会在内部执行 npm 包自带的 `scripts/xiaoe_env.py` 兼容路径；它只依赖 Python 标准库，凭证 stdout 由 CLI 内部消费，不进入 Agent 上下文，也不会关闭 TLS 证书校验。之后才依次读取宿主 `xiaoeUserData/tokens.py`、桌面 XiaoE 客户端本地会话（macOS `~/Library/Application Support/XiaoE/Robots/<id>/user_settings.json`，Windows `%LOCALAPPDATA%/XiaoE/Robots/<id>/user_settings.json`）和 `WEAVER_XIAOE_*` ETEAMSID 映射。宿主不会注入 ETEAMSID 环境变量，CLI 也不读取 `XIAOE_ETEAMSID`。
+
+E10 目标地址按“显式 `--base-url` → 专用 `WEAVER_XIAOE_*` E10 配置/映射 → 当前 profile → `https://www.e-cology.com.cn`”解析，绝不会把 `XIAOE_DOMAIN` 当作 E10 地址。凭证可用时，CLI 直接保存登录态，保存的 `agentType` 固定为 `XiaoE`；业务命令在未显式指定 `--auth` / `--profile` 时，也会自动优先尝试 XiaoE 统一登录。统一登录失败后，`auth xiaoe` 仅在 macOS/Windows 桌面宿主自动降级浏览器 OAuth；Web/Linux 环境直接返回 `authentication/xiaoe_web_credential_unavailable`，不再启动无法回调的 localhost 登录。用户明确希望浏览器授权且宿主能够接收本地回调时，可以显式运行 `auth login`。
 
-脚本链路按 `python3`、`/usr/bin/python3`、`python` 顺序探测可用解释器；可用 `WEAVER_XIAOE_TOKEN_SCRIPT_PYTHON` 指定解释器，用 `WEAVER_XIAOE_TOKEN_SCRIPT_PATH` 指定脚本路径（旧名 `XIAOE_TOKEN_SCRIPT_PYTHON` / `XIAOE_TOKEN_SCRIPT_PATH` 仍兼容）。`XIAOE_` 是平台保留前缀，本 CLI 的自定义变量统一使用 `WEAVER_XIAOE_*`。
+脚本兼容链路会先自动发现桌面 XiaoE 客户端内置 Python（macOS 应用包与 Windows 按用户/全局安装均支持），再回退到系统 `python3`、`/usr/bin/python3`、`python`；Windows 的系统回退顺序为 `python`、`python3`、`py`。可用 `WEAVER_XIAOE_TOKEN_SCRIPT_PYTHON` 精确指定解释器，用 `WEAVER_XIAOE_TOKEN_SCRIPT_PATH` 指定桌面宿主脚本路径（旧名 `XIAOE_TOKEN_SCRIPT_PYTHON` / `XIAOE_TOKEN_SCRIPT_PATH` 仍兼容）。CLI 自带的 `xiaoe_env.py` 位于 npm 包 `scripts/`，不会放入 `weaver-e10-shared` Skill；Skill 包禁止携带或直接执行 Token 脚本。`XIAOE_` 是平台保留前缀，本 CLI 的自定义变量统一使用 `WEAVER_XIAOE_*`。
 
 无法使用浏览器回调时，可以用 `auth set` 直接写入浏览器中复制到的
 `ETEAMSID`。命令会调用 `teamsCheck` 解析当前用户、租户和组织信息，并写入

package/docs/hrm.md

@@ -17,7 +17,8 @@ weaver-work-cli --json hrm run <operation> --input -
 | `src/shortcuts/hrm/index.ts` | 命令注册与 JSON envelope |
 | `src/shortcuts/hrm/manifest.ts` | `schema` 契约与禁用边界声明 |
 | `src/shortcuts/hrm/host.ts` | E10 会话桥接、HRM 页面上下文 Referer、JSON 请求、响应归一化 |
-| `src/shortcuts/hrm/operations/` | 按业务域拆分的 operation 实现（employee / org / position） |
+| `src/shortcuts/hrm/operations/` | 按业务域拆分的 operation 实现（employee / org / position / resolve） |
+| `src/shortcuts/hrm/operations/resolve.ts` | 多维（虚拟组织维度）解析：取全量多维 → 名称精确/模糊匹配 → 带 `companyId` 查部门/分部 → 回候选 |
 | `src/shortcuts/hrm/operations/registry.ts` | operation 注册表与去重校验 |
 
 ## 认证
@@ -60,6 +61,36 @@ CLI 已把上表差异归一化：**列表类统一输出 envelope 的 `data.row
 
 **长整型 id 一律按字符串传递**；**手机号已脱敏**（3 位前缀 + `****` + 末 4 位）。
 
+## 多维（虚拟组织维度）解析
+
+E10 组织树按多维切分，`department`/`subcompany` 浏览接口不传 `companyId` 时默认落到「行政组织」维度，因此「按名称找部门/分部」需要先定位多维 id。
+
+`hrm.org.resolve` 把这段编排收在 CLI 内（多维全部取自 `/api/bs/hrm/companyVirtual/listCompanyVirtual`），**一次调用完成两级匹配**：维度名称 → `companyId` → 组织名称。名称匹配分三级，**只有前两级会自动往下走**：
+
+| 级别 | 判定 | CLI 行为 |
+| --- | --- | --- |
+| ① 精确 | 忽略大小写/空白的全等（服务端 `eq`/等于） | 唯一 → 继续；多个 → `ambiguous` |
+| ② 包含（模糊） | 名称是关键字子串（服务端 `in`/包含 + 客户端忽略大小写等值优先） | 唯一 → 继续；多个 → `ambiguous` |
+| ③ **近似** | 编辑距离阈值内（打字级差异，如「客服维度」→「客户维度」） | **只回 `suggestions`，`status: not_found`，绝不继续** |
+
+| operation | 关键输入 | 说明 |
+| --- | --- | --- |
+| `hrm.org.resolve` | `virtual` + `name`（首调）；`virtualId` / `orgId`（复调）；`maxCandidates`（候选上限，1~200，默认 20） | 不传 `type` 时先按部门、再按分部自动识别 |
+
+> 多维清单（维度名 + id）**不单独暴露 operation**，由 `hrm.org.resolve` 内部获取与处理（匹配用 + `not_found` 回 `availableVirtuals` 供纠错）。「列出该租户有哪些多维」**暂不支持**，已在 `withheldOperations` 声明；`availableVirtuals` 不得被当作列维度接口（禁止构造不存在的维度名去套取）。
+
+🔴 **结果判定看 `data.status`（不是 `ok`）**，三种结果都 `ok: true`、退出 0：
+
+| `data.status` | 输出 | 调用方动作 |
+| --- | --- | --- |
+| `resolved` | `org`（`id`/`name`/`type`/`fullPath`/`virtualId`/`link`…）、`virtual`、`matchType`；不传 `type` 且存在同名另一类型节点时另回 `alsoMatched[]` | 直接使用 `org`；有 `alsoMatched` 时必须一并告知用户 |
+| `ambiguous` | `stage`（`virtual`/`org`）、`candidates[]`（默认 ≤20，可调）、`candidateTotal`、`truncated`、`message` | 列候选让用户确认，确认后把 `id` 当 `orgId`（维度歧义当 `virtualId`）复调 |
+| `not_found` | `suggestions[]`（近似名称，≤5）/`suggestionTotal`、`availableVirtuals`（`stage=virtual`）、`message` | **原样转述**（含"不存在"），**禁止自行替换名称重试**；用户确认后再用 `virtualId`/`orgId` 复调 |
+
+`data.total` 与「权威总数」的关系同 `org.query`：组织浏览接口的 `data.total` 是上游真值（非本页行数）；本操作调用 `current=1`，上游浏览分页取 `max(100, maxCandidates)`，不做翻页。`fullPath`/`parentPath` 中的层级分隔符已由 CLI 统一为 `/`（部分租户上游用 `|`，如泛微网络租户的 `supDepartment`）。
+
+不传 `type` 时本操作**同时检索部门与分部**（多 1 次浏览请求），因此不会出现「同名部门/分部被静默二选一」：唯一命中时按部门优先返回 `org`，另一类型的同名节点回在 `alsoMatched`；多命中时统一走 `ambiguous`。
+
 ## 详情页卡片链接
 
 查询命中后，回答中一律用 `[名称](link)` 形式输出每个命中实体（`link` 由 CLI 在每行提供）：
@@ -67,7 +98,7 @@ CLI 已把上表差异归一化：**列表类统一输出 envelope 的 `data.row
 | 卡片 | link 路径 | 来源 operation |
 | --- | --- | --- |
 | 人员卡片 | `/sp/hrm/profileInfo/{id}` | `employee.query`/`employee.batch`/`subordinate.*`/`employee.detail` |
-| 组织卡片 | `/sp/hrm/orgCard/{id}` | `org.query`/`org.detail` |
+| 组织卡片 | `/sp/hrm/orgCard/{id}` | `org.query`/`org.detail`/`org.resolve` |
 | 岗位卡片 | `/sp/hrm/positionCard/{id}` | `position.query`/`position.detail`/`position.list` |
 
 ## 调用示例
@@ -89,6 +120,7 @@ printf '%s\n' '{"keyword":"张三"}' | weaver-work-cli --json hrm run hrm.employ
 `withheldOperations` 中声明的能力不实现，也不要绕过：
 
 - **代理商查询**（`hrm.employee.dls`）：`containsDls=true` 仅泛微自用系统域名支持（自用域名白名单），客户/其他环境禁止触发。
+- **列多维**（`hrm.org.virtuals`）：已下线并入 `hrm.org.resolve`；「列出该租户有哪些多维」暂不支持，不得构造假查询绕取 `availableVirtuals`。
 
 ## 测试
 

package/docs/invoice.md

@@ -21,6 +21,9 @@ weaver-work-cli auth status --no-check
 2. 调用或复用 `/api/inc/proxy/getToken?appType=1` 取得发票业务 Token。
 3. 业务请求同时携带 E10 Cookie/ETEAMSID 和 `token` Header。
 
+系统 Keychain/Secret Service 不可用时，发票 Token 只保存在当前命令进程内，
+安全缓存失败不会阻断票夹查询；CLI 不会降级为明文 Token 文件。
+
 Agent 不得在业务 JSON 中传 `access_token`、`app_key`、`app_secret`、Cookie、ETEAMSID 或发票 Token。
 
 ## Agent 入口

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weaver-work-cli",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "面向泛微工作工具链的可扩展 TypeScript CLI 基础框架（E10 业票通等能力）",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,4 +49,4 @@
     "tsx": "^4.19.0",
     "typescript": "^5.6.0"
   }
-}
+}

package/scripts/xiaoe_env.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Exchange XiaoE platform credentials for an E10 eteamId.
+
+This compatibility helper is executed only by weaver-work-cli. It uses the
+Python standard library, writes one JSON result to stdout, keeps TLS certificate
+verification enabled, and refuses redirects that could leak Authorization to a
+different origin.
+"""
+
+import json
+import os
+import ssl
+import sys
+import urllib.error
+import urllib.request
+from urllib.parse import urljoin, urlsplit
+
+
+MAX_REDIRECTS = 5
+ETEAM_ID_PATH = "/spec-apps/api/app/rpachat/skill/extend/eteamId"
+
+
+def _effective_port(parts):
+    if parts.port is not None:
+        return parts.port
+    return 443 if parts.scheme == "https" else 80
+
+
+def _same_origin(left, right):
+    return (
+        left.scheme == right.scheme
+        and left.hostname == right.hostname
+        and _effective_port(left) == _effective_port(right)
+    )
+
+
+class _SafeRedirectHandler(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        current = urlsplit(req.full_url)
+        target_url = urljoin(req.full_url, newurl)
+        target = urlsplit(target_url)
+        safe_upgrade = (
+            current.scheme == "http"
+            and target.scheme == "https"
+            and current.hostname == target.hostname
+        )
+        if target.scheme not in ("http", "https") or target.username or target.password:
+            raise urllib.error.HTTPError(target_url, 403, "unsafe XiaoE redirect", headers, fp)
+        if not _same_origin(current, target) and not safe_upgrade:
+            raise urllib.error.HTTPError(target_url, 403, "cross-origin XiaoE redirect", headers, fp)
+
+        redirects = getattr(req, "_xiaoe_redirects", 0) + 1
+        if redirects > MAX_REDIRECTS:
+            raise urllib.error.HTTPError(target_url, 310, "too many XiaoE redirects", headers, fp)
+
+        redirected = urllib.request.Request(
+            target_url,
+            data=req.data,
+            headers=dict(req.header_items()),
+            method=req.get_method(),
+        )
+        redirected._xiaoe_redirects = redirects
+        return redirected
+
+
+def _post_json(url, token, domain):
+    body = json.dumps({"domain": domain}).encode("utf-8")
+    request = urllib.request.Request(
+        url,
+        data=body,
+        headers={
+            "authorization": token,
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+    opener = urllib.request.build_opener(
+        _SafeRedirectHandler(),
+        urllib.request.HTTPSHandler(context=ssl.create_default_context()),
+    )
+    try:
+        with opener.open(request, timeout=15) as response:
+            raw = response.read().decode("utf-8")
+    except urllib.error.HTTPError as error:
+        detail = error.read().decode("utf-8", "ignore")[:200]
+        raise RuntimeError(f"HTTP {error.code}: {detail}") from error
+    return json.loads(raw)
+
+
+def main():
+    domain = sys.argv[1].strip() if len(sys.argv) > 1 else "https://www.e-cology.com.cn"
+    token = os.getenv("XIAOE_USER_TOKEN", "").strip()
+    erpa = os.getenv("XIAOE_DOMAIN", "").strip()
+    if not token or not erpa:
+        raise RuntimeError("missing XIAOE_USER_TOKEN or XIAOE_DOMAIN")
+
+    endpoint = f"{erpa.rstrip('/')}{ETEAM_ID_PATH}"
+    data = _post_json(endpoint, token, domain)
+    business_code = data.get("code")
+    business_data = data.get("data") or {}
+    eteam_id = business_data.get("eteamId") if isinstance(business_data, dict) else None
+    if business_code not in ("0000", 200) or not eteam_id:
+        raise RuntimeError(f"XiaoE exchange failed with business code {business_code}")
+
+    print(json.dumps({
+        "eteamId": eteam_id,
+        "code": business_code,
+        "msg": data.get("msg"),
+    }, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as error:
+        print(json.dumps({"code": "ERROR", "msg": str(error)}, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)

package/skill-template/domains/hrm.md

@@ -1,7 +1,7 @@
 本业务域用于泛微 E10 组织管理（员工查询 / 组织架构 / 岗位查询，全部只读）。入口 `SKILL.md` 先路由到 `weaver-e10-shared/SKILL.md`，再给出跨模块约定、Reference 路由表和安全边界。具体用法拆到 `references/`：
 
 - `employee.md`：按工号/姓名/手机/邮箱查员工、批量人员、资料名片、下属查询（当前登录人 + 按 id）、部门成员。
-- `org.md`：分部/部门浏览、组织详情、多级路径 drill-down 编排。
+- `org.md`：分部/部门浏览、组织详情、多级路径 drill-down 编排、多维（虚拟组织维度）解析（`org.resolve`，含"维度名不存在时只给近似提示"的三级匹配）。
 - `position.md`：岗位浏览、岗位详情、岗位批量（岗位地址簿）。
 - `source-manifest.json`：源资料清单与 sha256 指纹，用于源资料更新检测。
 
@@ -12,5 +12,6 @@
 - 长整型 id 一律按字符串传递；手机号已由 CLI 脱敏。
 - **无条件禁止全量拉取**：`employee.query`/`org.query`/`position.query` 必须带收敛条件；`position.list` 无过滤需显式 `all=true`；`employee.query` 的 `status` 不能单独使用。
 - 姓名/工号/名称模糊匹配多人命中时必须列候选让用户选择，不得自动取第一条；部门重名改传组织 id。
+- 组织树按**多维**切分，同名部门在不同多维下是不同节点；`org.resolve` 已把「多维名称+部门/分部名称」的两级匹配收在 CLI 内，**只调一次**，结果看 `data.status`（`resolved`/`ambiguous`/`not_found`），`ambiguous` 必须问用户后再用 `orgId`/`virtualId` 复调。
 - 批量查询禁止循环单查：批量人员走 `employee.batch`，岗位批量走 `position.list`。
 - 代理商查询（`containsDls=true`）属禁用边界，直接说明不可用，不引导用户绕过。

package/skill-template/skill-template.md

@@ -13,7 +13,7 @@ requires:
 cliHelp: "weaver-work-cli {{command}} --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 不能自行安装——必须先取得用户明确确认后再执行。用户确认后按顺序执行且仅执行一次：① 缺 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`——省略会装进默认目录，导致本技能依然读不到共享规则。安装或读取失败时必须停止执行；命令均成功后重新读取共享规则，仍读不到就停止并把结果报告用户，不得凭猜测继续。**
+**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`——省略会装进默认目录，导致本技能依然读不到共享规则。安装或读取失败时必须停止执行；命令均成功后重新读取共享规则，仍读不到就停止并把结果报告用户，不得凭猜测继续。**
 认证和登录态只能按共享规则通过 `weaver-work-cli auth ...` 命令判断；禁止直接读取、列出、打印或解析用户主目录下的旧 `.e10-cli`、auth、config 或 Keychain 数据。
 所有命令通过 `weaver-work-cli --json {{command}} run <operation>` 执行：简单 JSON 优先传 `--input-json '<json>'`，复杂或多行 JSON 先写入 UTF-8 文件再传 `--input <path>`，只有确认当前 shell 能稳定传管道时才使用 `--input -`。调用前先按需读取 references 下对应的文件，查参数结构，不要猜字段；**references 是第一信息源**，`weaver-work-cli {{command}} schema` 是 operation、字段和风险等级的合约来源。
 若 `schema` 或 reference 提供 `inputExamples`，优先复用其中和当前意图最接近的样例并只替换用户明确给出的值；标记为 `synthetic` 的样例需要业务复核，不能当作源资料事实。若 operation 标记了 `missingExamples` 或参数覆盖矩阵中的 `needs-confirmation` 字段，先向用户说明缺少哪些入参事实并索取补充，不要通过反复尝试不同 JSON 格式来猜。

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

@@ -15,7 +15,7 @@ cliHelp: "weaver-work-cli blog --help"
 
 # weaver-work-cli 日报助手
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若共享规则不存在、CLI 未安装或读取失败，说明本技能的必需依赖缺失，必须先提示用户先补齐 `weaver-work-cli` 与共享 skill `weaver-e10-shared`（不补齐本技能无法执行），并把下面两条待执行命令原样完整展示给用户；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`——省略会装进默认目录，导致本技能依然读不到共享规则。命令均成功后重新读取共享规则；仍读不到就停止并把结果报告用户，不得凭猜测继续。**
+**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 ...` 命令判断；禁止直接读取、列出、打印或解析用户主目录下的旧 `.e10-cli`、auth、config 或 Keychain 数据。

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.23
+version: 1.1.26
 author: 泛微网络科技股份有限公司
 agent_created: true
 requires:
@@ -13,7 +13,7 @@ requires:
 cliHelp: "weaver-work-cli caizhilian --help"
 ---
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)，其中包含安装、E10 认证、JSON 输出和高风险写入规则。若共享规则不存在、CLI 未安装或读取失败，说明本技能的必需依赖缺失，必须先提示用户先补齐 `weaver-work-cli` 与共享 skill `weaver-e10-shared`（不补齐本技能无法执行），并把下面两条待执行命令原样完整展示给用户；Agent 不能自行安装——必须先取得用户明确确认后再执行。用户确认后按顺序执行且仅执行一次：① 缺 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`——省略会装进默认目录，导致本技能依然读不到共享规则。命令均成功后重新读取共享规则；仍读不到就停止并把结果报告用户，不得凭猜测继续。**
+**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 拒绝或剥离。
@@ -53,7 +53,7 @@ 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` | [`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.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) |
@@ -62,6 +62,7 @@ cliHelp: "weaver-work-cli caizhilian --help"
 | 加解密设置（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) |
 | 文件采集（FTP/SFTP 任务管理） | `caizhilian run caizhilian.file-collection.task.*` / `.scan.*` / `.run.*` / `.cancel.*` / `.delete.*` | [`file-collection.md`](references/file-collection.md) |
+| 新建采集任务 | `caizhilian run caizhilian.file-collection.task.save.prepare/apply` | [`file-collection.md`](references/file-collection.md) |
 | 文件上传（本地文件上传到文件服务） | `caizhilian run caizhilian.file-upload.contract` / `.prepare` / `.upload.prepare` / `.upload.apply` | [`file-upload.md`](references/file-upload.md) |
 | 任何写操作的确认链、票据报错、写结果不确定 | `<name>.prepare` -> 用户确认 -> `<name>.apply --continuation TOKEN --yes` | [`write-protocol.md`](references/write-protocol.md) |
 | 环境列表 / 配置查看 / 重载配置 / 切换环境等未暴露能力 | 无 caizhilian 命令，改用框架命令 | [`withheld.md`](references/withheld.md) |
@@ -211,6 +212,6 @@ weaver-work-cli --json caizhilian run caizhilian.attachment.download --input-jso
 - 禁止读取或复制 CLI runtime 内部 Token、Cookie、ETEAMSID。
 - 禁止读取、列出、打印或解析用户主目录下的旧 `.e10-cli`、auth、config 或 Keychain 数据。
 - 环境列表、配置快照、配置重载、环境切换（源 `list_systems` / `get_loaded_config` / `reload_config` / `switch_config`）不在本模块，改用 `weaver-work-cli config ...` 与 `weaver-work-cli e10 auth ...`，详见 [`withheld.md`](references/withheld.md)。
-- 源 Skill 目录内的系统设置（备份/加密/附件全局设置/存储）、文件收集、文件上传等模块不属于采知连文档中心，未纳入本 CLI；需要时按 `weaver-e10-skill-maker` 单独生成模块。
+- 源 Skill 目录内的系统设置（备份/加密/附件全局设置/存储）、文件收集、文件上传等模块已纳入本 CLI。
 - 文档版本回滚、文档审批流转、全文检索高级语法、回收站还原等能力当前未纳入 CLI manifest，需要在 E10 页面操作。
 - 非文档中心类 E10 能力（流程、人事、财务、邮件、会议等）不由本 Skill 承载。

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

@@ -134,3 +134,40 @@ Search results are not association credentials. Inspect or create must complete
 | 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/folder.md

@@ -46,6 +46,7 @@
 | `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） |
 
 - `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`。
@@ -63,6 +64,7 @@ weaver-work-cli --json caizhilian run caizhilian.folder.permission.list --input-
 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"}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-setting.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
 ```
 
 macOS/Linux（bash/zsh）：
@@ -74,6 +76,7 @@ weaver-work-cli --json caizhilian run caizhilian.folder.permission.list --input-
 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"}'
+weaver-work-cli --json caizhilian run caizhilian.folder.permission.sync-setting.prepare --input-json '{"id":"456","keepOldSettingForAllFolders":true}'
 ```
 
 ## 输出处理
@@ -89,7 +92,7 @@ weaver-work-cli --json caizhilian run caizhilian.folder.permission.set-auth.prep
 - `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 }`。
+- 写操作 `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 }`。
 - 权限/共享类写操作的 `prepare` 返回请求体预览 + `continuation`；向用户摘要时必须写清「哪个文件夹、哪项权限、给谁、什么级别」，并说明删除类操作不可撤销。
 - 列表类结果默认用 Markdown 表格摘要（文件夹名/路径/权限类型/对象/级别），不要原样贴 JSON。
 
@@ -98,6 +101,7 @@ weaver-work-cli --json caizhilian run caizhilian.folder.permission.set-auth.prep
 - 文件夹权限与默认共享是**影响面很大的配置**：改错会导致整个知识库的下载、复制、新建权限对全员开放或全部收紧。`permission.set-auth` 从 `user` 改成 `true` 等于放开给所有人，确认摘要里必须显式写出这一后果。
 - `folder.create` 会在服务端产生新节点；`inherit_parent=true` 会连带继承父文件夹的权限与默认设置，必须在确认摘要里说明。
 - 删除类（`default-share.delete` / `permission.delete`）必须先做一次对应 `list` 只读查询，把待删条目的可读信息展示给用户后再 prepare。
+- `permission.sync-setting` 会将当前文件夹的管理员权限设置同步到所有下级子文件夹，**执行前必须提醒用户此操作对系统性能可能有一定影响**。`keepOldSettingForAllFolders=true` 表示保留原有管理员设置，`false` 表示不保留。
 - 本 reference 只覆盖文件夹与权限；文档级共享/参与人/标签见 `collaboration.md`。
 
 ## 失败处理

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

@@ -81,13 +81,30 @@ weaver-work-cli auth set --eteamsid "PCACCOUNT_xxx"
 | `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`(永久) | 每个文件的历史版本保留多少天 |
+| `version-size` | `sysFileVersionSize` | 整数(1-500) / `-1`(不限) | 每个文件最多保留多少个历史版本。**与 `version-time` 互斥**，由 `version-clean-type` 决定生效哪个 |
+| `version-time` | `sysFileVersionTime` | 整数(1-1095) / `-1`(永久) | 每个文件的历史版本保留多少天。**与 `version-size` 互斥**，由 `version-clean-type` 决定生效哪个 |
 | `print-pdf-types` | `sysPrintToPdfFileTypes` | 逗号分隔扩展名 | 打印时需要转 PDF 的扩展名（空 = 未启用，独立项） |
-| `version-clean-type` | `sysAutoClearFileVersionType` | `versionSize` / `versionTime` | 版本清理方式（按份数 / 按时间）—— v0.2.0 补 |
+| `version-clean-type` | `sysAutoClearFileVersionType` | `versionSize` / `versionTime` | 版本清理方式（按份数 / 按时间）—— v0.2.0 补。**决定 `version-size` 和 `version-time` 哪个生效** |
 | `version-size-type` | `sysFileVersionSizeType` | `selected` / `custom` | 份数那一行 UI 状态（selected = 选下拉 / custom = 自定义）—— v0.2.0 补 |
 | `version-time-type` | `sysFileVersionTimeType` | `selected` / `custom` | 时间那一行 UI 状态（selected = 选下拉 / custom = 自定义）—— v0.2.0 补 |
 
+### 版本清理设置规则（强制）
+
+设置版本清理时，**必须同时设置以下 6 个字段**才能让前端正确生效：
+
+```json
+{
+  "auto-clear-version": true,
+  "version-size": <数量>,
+  "version-time": <天数>,
+  "version-clean-type": "versionSize",
+  "version-size-type": "custom",
+  "version-time-type": "custom"
+}
+```
+
+**单独设置 `version-size` 或 `version-time` 不会生效**，必须同时设置 `version-size-type` 和 `version-time-type` 为 `custom`。
+
 完整别名表见 [setting-attach-field-map.md](setting-attach-field-map.md)。
 
 ## 硬性门禁
@@ -105,6 +122,9 @@ weaver-work-cli auth set --eteamsid "PCACCOUNT_xxx"
    报错并打印服务端返回值。
 5. **不写日志到 home 之外**——所有凭证 / 日志只落在 `~/.minimax/skills/weaver-setting-attach/`
    下，不写系统级。
+6. **版本清理必须一次到位**——设置版本清理时，必须同时设置 6 个字段（`auto-clear-version`、
+   `version-size`、`version-time`、`version-clean-type`、`version-size-type`、`version-time-type`），
+   其中 `version-size-type` 和 `version-time-type` 必须为 `custom`，否则前端不生效。
 
 ## 对话式交互规则
 
@@ -137,6 +157,16 @@ weaver-work-cli auth set --eteamsid "PCACCOUNT_xxx"
    - 三步可以一次消息里说全,但步骤 c 的问句**必须独立成行**,不能藏在
      长段落里让人找不到
 
+   **互斥字段必须主动引导**：当用户同时设置互斥字段时，必须在执行前说明
+   互斥关系并让用户选择，不能先执行再提醒。典型场景：
+
+   - **版本清理**：`version-size`（按份数）和 `version-time`（按时间）互斥，
+     由 `version-clean-type` 决定生效哪个。用户同时设置两个值时，必须先问
+     「你想按份数保留（如最多保留 4 个版本），还是按时间保留（如保留 12 天）？」，
+     确认后再设置对应的清理方式和数值
+   - **格式控制**：`format-mode` 切换会迁移 `format-list` 到另一个字段，
+     必须说明迁移影响
+
 4. **话术面向客户(非开发)**
    本 skill 的对话对象是**客户/业务人员**,不是开发。所有输出话术:
    - **禁止出现**:CLI key(`mobile-block`、`upload-max`、`format-list` 等)、
@@ -224,7 +254,7 @@ CLI 自动从 `.env.local` / ENV 读取并塞进 Cookie。
   "sysUploadCustomMsgEnable": false,         // bool
   "sysUploadCustomMsg": "",                  // str
   "sysBatchDownload": true,                  // bool
-  "sysAppDownload": true,                    // bool (true=允许移动端下载)
+  "sysAppDownload": true,                    // bool (true=禁止移动端下载)
   "sysDownloadToPdfFileTypes": ""            // str
 }
 ```
@@ -380,7 +410,7 @@ CLI 自动从 `.env.local` / ENV 读取并塞进 Cookie。
 
 - **CLI key**：`mobile-block`
 - **中文**：`禁止移动端下载` / `移动端禁止下载`
-- **DTO 字段**：`sysAppDownload`（**语义取反**：CLI true → DTO false）
+- **DTO 字段**：`sysAppDownload`（CLI true ↔ DTO true，禁止移动端下载）
 - **类型**：Boolean
 - **示例**：
   ```text