---
name: weaver-setting-backup
description: "对话式管理 weapp 后台\"文件设置 → 备份设置\"页面：开关本地备份、列出备份规则、 调整规则路径/周期/启停、删除规则。`backup on` 一句话开启、`backup update --id N --period 720` 一句话调整。覆盖 `POST /api/file/tenant/setting/save`（开关 `sysLocalFileBackup`）+ `FileBackupController` 全部 5 个 CRUD 端点。Use for 备份设置、本地备份、附件备份、备份规则、backupRule、backupPath、备份周期、 文件设置备份、eteams-file 备份、<your-e10-domain>/info/fileSet/backup."
license: Proprietary
compatibility: 泛微E10采知连配套使用，内部可自由使用与修改，禁止对外分发
metadata:
  maintainer: unknown
  type: capability
  version: 1.0.0
  updated: 2026-08-19
  tags: [备份设置, 本地备份, 备份规则, backupRule, 备份周期]
---

# weaver-setting-backup

让"文件设置 → 备份设置"页面**用一句话就能管**。背后调两类接口：
- `POST /api/file/tenant/setting/save`（开关 `sysLocalFileBackup`）
- `FileBackupController` 全部 5 个 CRUD 端点（list/get/update/delete/enable）

修改前先 diff，写操作必走对话确认。

## 前置依赖

### 认证前置（必须）

本模块通过 CLI 托管的认证获取凭证（base_url + Cookie + eteamsid + User-Agent），凭证契约见同级 `weaver-e10-shared` 技能的共享规则，不依赖手动配置文件，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

- 用户说"把本地备份打开""关掉本地备份""备份周期改成 720 分钟"
  "列出所有备份规则""禁用规则 id=1""删除规则 id=2"等
- 改 weapp 后台的"备份设置"页（`<your-e10-domain>/info/fileSet/backup`）
- 调试 eteams-file 备份策略

**不适用**：附件设置（见 `weaver-setting-attach`）、加解密设置（见
`weaver-setting-encrypt`）、存储设置、文件采集设置、预览编辑设置、
文件深度清理、页面设置——这 6 个 Tab 走的接口各不相同，**不在本 skill 范围**。

## 命令清单

CLI 软链名 `setting-backup`（用全名避开与 `weaver-setting-attach` 的
`setting-attach`、`weaver-setting-encrypt` 的 `setting-encrypt` 软链冲突）。

| 命令 | 作用 |
|---|---|
| `backup on` | 开启本地备份（无规则时自动建默认规则） |
| `backup off` | 关闭本地备份 |
| `backup show` | 显示开关状态 + 默认规则详情 |
| `backup list` | 列出所有备份规则（表格） |
| `backup update --id <N> [--name] [--org-path] [--backup-path] [--period] [--enable/--disable]` | 调整某条规则 |
| `backup enable --id <N>` | 启用某条规则 |
| `backup disable --id <N>` | 禁用某条规则 |
| `backup delete --id <N> [--yes]` | 删除某条规则（prod 必须 `--yes`） |

## 一句话用法

```text
# 开启本地备份
backup on

# 调整周期（720 分钟 = 12 小时）
backup update --id 1 --period 720

# 改备份路径
backup update --id 1 --backup-path /nfs/data/backup

# 禁用某条规则
backup disable --id 1

# 删规则（prod 必须 --yes）
backup delete --id 2 --yes
```

## 硬性门禁

1. **写操作必须先 diff**——`on/off/update/enable/disable/delete` 不带 `--yes` 时
   把 diff/影响打到 stdout 并等 stdin `y` 才发请求；EOF / `n` 视为取消。
   **对话式 agent 流程**：即使 CLI 已带 `--yes`，**仍必须先在对话里走
   "改前值 / 改后影响 / 明确询问" 三步**（见对话式规则 3），得到
   "改 / 确认 / 好的" 之类回复后才调 CLI。
2. **`prod` 必须 --yes**——防手滑。
3. **不开开关不能调规则**——`backup update/enable/disable/delete` 在
   `sysLocalFileBackup=false` 时拒绝（关着的备份调规则没意义）。
4. **period 范围 60-1440 分钟**（后端校验）；
   CLI 也做同样校验。
5. **新建规则不能走 CLI**——后端没 `/api/file/create/backup/rule` 端点（前端 bug）；
   唯一新建路径是 `backup on` 在无规则时自动建默认。
6. **保存后校验**——`on/off/update/enable/disable` 后调一次 GET 拉回确认。

## 对话式交互规则

> 这些是 **agent 在对话中使用本 skill 时**的硬约束，跟底层 CLI 脚本无关。命令行直接跑
> `backup` 可以绕过，但任何经由本 skill 的 agent 流程都必须遵守。

1. **操作前必查登录态**
   每次执行业务操作前，确认 CLI 已完成登录：
   - 若 `weaver-work-cli auth status` 显示未登录，提示用户执行 `weaver-work-cli auth login` 或 `weaver-work-cli auth set` 完成登录
   - 登录完成后**立刻**继续用户原本的请求，不要让用户再敲一次命令

2. **查询要简洁**（`show / list` 时的输出格式）
   - **只返回三样**：设置项名（业务中文）、当前值、**当前租户名**
   - **不要**返回：bool 三态展开、enum 解释、字段语义说明、风险提示、
     "建议/可以这么做" 等附加内容 —— 这些只在用户追问时再说
   - `show` 开关状态：单行一行，格式固定

     ```
     <租户名> · <设置项名>：<当前值>
     ```

   - `show` / `list` 规则详情：**按列表逐项展示**（每行一个字段），
     规则名前**不显示** `规则 #<id>`，直接用规则名。格式固定：

     ```
     <租户名> · <规则名>：
     - 状态：<启用 / 禁用>
     - 源目录：<org-path>
     - 备份目录：<backup-path>
     - 周期：<period> 分钟
     ```

     - 多条规则时按顺序依次排列，每条独立一组

3. **修改前必须三步问清**
   - 步骤 a — **改前的值**：说清楚这一项当前是什么（从 GET 里取，不要瞎猜）；
     涉及路径/周期时复述当前值，让客户确认是不是他/她要改的那条
   - 步骤 b — **改后影响**：说清楚改完影响什么业务、触及哪些文件、是否
     **会触发新文件 IO 失败**（路径不可达时）、周期超出 60-1440 范围时
     明确说"会被后端拒"
   - 步骤 c — **明确询问**：用一句话问"要改成 X 吗？"，**得到用户肯定回复
     (y / 改 / 确认 / 好的 之类)才发 POST**，即使 CLI 已带 `--yes` 也不许跳过
   - 三步可以一次消息里说全，但步骤 c 的问句**必须独立成行**，不能藏在
     长段落里让人找不到
   - `on` 操作必须确认开关目标（"现在关着要开 / 现在开着要关"）和**是否
     已经在所有 E10 节点挂载好共享备份目录**（见规则 5 的运维前置）

4. **话术面向客户（非开发）**
   本 skill 的对话对象是**客户/业务人员**，不是开发。所有输出话术：
   - **禁止出现**：CLI key（`--id` / `--period` / `--org-path` 等）、DTO 字段名
     （`sysLocalFileBackup` 等）、布尔字面值（`true` / `false`）、HTTP 术语
     （POST / GET / 200 / 401）、内部流程术语（"步骤 a / 步骤 b / 步骤 c"、
     "diff"、"回 y / 改"、"落库"）
   - **必须使用**：业务中文名（"本地备份"、"备份规则"、"备份周期"）、
     业务状态（"已开启 / 已关闭"、"启用 / 禁用"）、自然语言确认
     （"要打开吗？回 改 / 确认 / 好的"）
   - 需要看技术细节时（用户主动问"用的什么字段" / "接口是啥" / "为什么改不了"），
     **只在该轮回应**展开，平时一律隐藏
   - 身份信息隐藏 `userId` / `tenantKey` 这类内部 ID，只说"当前租户"
   - **路径描述严禁用 E10 内部术语**（如 E10 内部 path 概念），统一用
     业务中文（"源目录" / "备份目录"）

5. **做不到时正确引导**
   客户要改的项**当前工具/接口改不了**或**前置条件没满足**时，**不要**静默
   截断、**不要**发注定失败的请求。常见场景：
   - **共享备份目录没挂载（硬阻断）** — 调 `on / update / enable` 前必须
     主动问"你那边的运维同事已经把共享备份目录挂到所有 E10 节点了吗？"，
     客户回"挂好了 / 已挂"才继续；客户说不清楚或没挂，**直接停手**并
     解释"没挂载就开后端写文件会失败"，不要静默继续
   - **路径不在 E10 服务器能访问的目录（白话，禁止静默接受）** — 源目录
     和备份目录都必须是 E10 应用服务器能访问的目录（不能是客户本机的
     `/Users/xxx`、不能是某个应用节点临时目录、不能是其他服务器的远程
     路径），否则后端写不进去。改路径时 agent **必须**在话术里复述这个约束
   - **改"备份目录"前必做本地预校验，不发注定失败的请求** — 后端会拒 5 类路径，
     agent 改路径前**必须**在 CLI 端先把目标路径跑一遍
     等价校验，任一不过**直接告诉客户"后端会拒：<原因>"，让客户重新给路径**，
     **不要**静默发请求让后端报错。5 项校验：

     1. 必须以 `/` 开头（Windows 跳过这条）
     2. 不能含 `\` `*` `?` `"` `<` `>` `|`
     3. FILE_PATH 正则不匹配（`\s` 空白 + `\` + `;` + `'` + `*` + `？`(全角) + `?` + `"` + `<` + `>` + `|`）
     4. 不能等于源目录（源目录按 `;` 切分后逐个比较）
     5. 不能是源目录的子目录（源目录末尾补 `/` 后取备份路径前 N 位对比）

     CLI 会在 `--backup-path` 显式传值时自动跑这 5 项校验，不通过直接报错返回，不发请求。常见客户语言：
     - "路径要以 / 开头"（CODE_20080）
     - "路径不能含特殊字符 \* ? \" < > |"（CODE_20078）
     - "路径不能含空白 / 分号 / 单引号 / 全角问号"（FILE_PATH 正则）
     - "备份路径不能和源路径相同"（CODE_20082）
     - "备份路径不能是源路径的子目录"（CODE_20079）
   - **period 超范围（60-1440 分钟）** — 客户想设"30 分钟"或"2880 分钟"，
     直接告诉客户范围是 60-1440 分钟（1-24 小时），**不**静默截断
   - **规则 id 不存在** — `update / enable / disable / delete --id N` 里的 N
     找不到时，先调一次 `list` 把当前 id 列表给客户看，让客户重新指定
   - **只支持 1 条默认规则，不能新增** — 后端业务上只允许存在 1 条"默认
     备份规则"，也没有新建规则端点。客户想"新建第二条规则"时，**直接
     告诉客户后端不支持**（不是 CLI 限制，是产品设计），只能在现有默认
     规则上调路径 / 周期 / 启停。新装环境无规则时，启用本地备份（`on`）
     会自动建这条默认规则
   - **`update` 想开/关的开关没显式传** — 没传 `--enable/--disable` 时
     保持原状态；客户**明确说**"要启用" 时**必须**传 `--enable`
   - **后端返回致命错误**（已知）：不重试，直接告诉客户失败原因 + 正确路径
   - 话术模板：
     "这里改不了：<原因>。需要去<正确路径>那里先做<前置操作>。
      在那边保存后，回到这里再让我帮你改备份设置里的对应项，
      就能改到你想要的值了。"

6. **典型部署模板（默认值参考）**
   客户问"备份能干嘛用" / "本地存储 + 备份服务器" 场景怎么配 / "默认值是多少"，
   直接给两步走 + 默认参考值：
   - **第一步（运维前置）**：运维把共享备份目录挂到所有 E10 节点
   - **第二步（业务配置）**：在 E10 后台 文件设置 → 备份设置 开启 + 配置 + 保存
   - **默认参考值**：源目录 = E10 文件数据目录（如 `/nfs/date`），
     备份目录 = 共享备份目录（如 `/nfs/bakFile`），
     周期 = **1440 分钟（24 小时）**
   - 客户明确想调时，**先报出这个参考值再问**"想调到多少"，别直接问"设多少"

## 宿主

CLI 入口：`weaver-work-cli caizhilian run caizhilian.setting-backup.<operation>`（操作清单见 SKILL.md 路由表）。


## 与 weaver-setting-attach / weaver-setting-encrypt 的关系

三个 skill **互相独立**，可在同一台机器共存：

| | weaver-setting-attach | weaver-setting-encrypt | weaver-setting-backup |
|---|---|---|---|
| 改的页面 | 文件设置 → 附件设置 | 文件设置 → 加解密设置 | 文件设置 → 备份设置 |
| CLI 软链 | `setting-attach` | `setting-encrypt` | `setting-backup` |
| 共享 | 后端 `POST /api/file/tenant/setting/save` 共用一份；凭证统一通过 CLI 托管的认证获取 |
| 不同 | attach 走"逐字段 update"；encrypt 走"整对象 toString"；backup 走"开关字段 + 独立 CRUD 控制器" |

## 版本

版本号规则 `x.y.z`：
- **x 升** — 大重构（接口变化、DTO 结构变化、命令大幅增删）
- **y 升** — 新增命令、新增子模块、新增业务场景
- **z 升** — 文案修正、门禁澄清、不改行为的小修
# 接口协议

## 端点

| 操作 | 方法 | URL | 入参 | 出参 |
|---|---|---|---|---|
| 拉 settings（含开关） | POST | `{base}/api/file/tenant/setting` | `{}` | `{code, data: {sysLocalFileBackup: ...}}` |
| 改开关 | POST | `{base}/api/file/tenant/setting/save` | `{sysLocalFileBackup: true/false}` | `{code, data: ...}` |
| 列规则 | POST | `{base}/api/file/get/backup/rule/list` | `{pageNo, pageSize}` | `{code, data: FileBackupListDto}` |
| 单个规则详情 | GET | `{base}/api/file/get/backup/rule?id=N` | `?id=N` | `{code, data: FileBackupFormDto}` |
| 更新规则 | POST | `{base}/api/file/update/backup/rule` | `BackupRuleUpdateParam` | `{code, data: null}` |
| 删除规则 | POST | `{base}/api/file/delete/backup/rule` | `{ids: [N]}` | `{code, data: null}` |
| 启停规则 | POST | `{base}/api/file/enable/backup/rule` | `{id, enableStatus}` | `{code, data: null}` |

## 鉴权

`Cookie: ETEAMSID=<id>`，与前端一致。

## POST 注意事项

1. **开关是逐字段 update**：只传 `sysLocalFileBackup` 一个字段，后端不会清空
   其它字段（参考 agent memory 中 weaver-setting-attach 的同款经验）。
2. **开开关 + 无规则 = 自动建默认规则**：
   ```java
   getInitFileBackup(tenantKey, newValue)
   → 取第一个 LOCAL_STORE 实例 → 构造 BackupRuleCreateParam
     （backupName=默认备份规则, backupPath=orgPath/backup, enableStatus=true）
   → fileBackupManager.createFileBackup(...)
   ```
3. **新建规则的端点不存在**——前端 `createBackupRule` 调的是
   `/api/file/create/backup/rule`，后端 `FileBackupController` 里**没有**这个
   端点。前端 bug，CLI 不暴露 `create`。
4. **period 范围 60-1440 分钟**——后端校验。
5. **delete 是批量**——body 是 `{ids: [N1, N2, ...]}`；CLI 一次只支持一个
   id，多个需要循环。
6. **enable 接口的字段是 `enableStatus`（Boolean），不是 `enabled`**——后端
   `BackupRuleEnableParam` 用 `enableStatus` 字段。

# 字段说明

## 顶层：本地备份开关

- **DTO 字段**：`sysLocalFileBackup`（Boolean）
- **GET 端点**：`POST /api/file/tenant/setting`
- **SAVE 端点**：`POST /api/file/tenant/setting/save`（只传这一个字段）
- **特殊行为**：开时如果当前无规则，**自动建默认规则**（用第一个本地存储实例的 path）

## 备份规则字段

| CLI flag | 后端字段 | 类型 | 必填 | 备注 |
|---|---|---|---|---|
| `--id` | `id` | Long | update/enable/disable/delete 必填 | 规则主键 |
| `--name` | `backupName` | String | update 必填 | 规则名称，< 255 字符 |
| `--org-path` | `orgPath` | String | update 可选 | 源路径 |
| `--backup-path` | `backupPath` | String | update 必填 | 备份路径 |
| `--period` | `period` | Long (分钟) | update 必填 | **60-1440**（1 小时 - 24 小时） |
| `--enable` | `enableStatus=true` | Boolean | update 可选（与 --disable 互斥） | 启用 |
| `--disable` | `enableStatus=false` | Boolean | 同上 | 禁用 |
| — | `backupConfig` | String | update 可选 | 高级配置（CLI 暂不暴露） |

> 列表接口 (`POST /api/file/get/backup/rule/list`) 返回 `FileBackupListDto`：
> ```json
> {
>   "columns": [...],
>   "list": [
>     {
>       "id": 1,
>       "backupName": "默认备份规则",
>       "orgPath": "/nfs/data",
>       "backupPath": "/nfs/data/backup",
>       "period": 1440,
>       "enableStatus": 1,
>       "backupConfig": "..."
>     }
>   ],
>   "pageNo": 1, "pageSize": 50,
>   "totalCount": 1, "totalPages": 1, "nextPage": null
> }
> ```
> `enableStatus` 后端用 0/1 整数表示；CLI 自动翻译成"启用/禁用"。

## ⚠️ 已知坑

1. **没有"新建规则"接口**——后端没有新建规则端点（前端页面调了但后端没实现，是个**前端 bug**）。
   CLI 不暴露 `create` 子命令。
2. **唯一新建路径**：`backup on` 开启本地备份时如果无规则会自动建默认
   （用第一个本地存储实例的 path）。如果租户没有本地存储实例，
   后端会报"没有可用的本地存储"错误。
3. **规则操作需要本地备份开启**——CLI 在 `update/enable/disable/delete` 前
   会 GET 一次 settings 检查 `sysLocalFileBackup`，没开会拒绝并提示先 `on`。
4. **period 范围 60-1440**（后端校验），
   CLI 也做同样校验；非整数倍数的"1440"会被四舍五入（按分钟）。