@fnnas-labs/fnos-cli 0.0.0-stage → 0.2.1

package/skill/reference/dockermgr.md

@@ -0,0 +1,244 @@
+# dockermgr 模块
+
+## 模块概述
+Docker 管理模块，涵盖 Docker 镜像、容器、网络、Compose 项目和 Docker 守护进程生命周期操作。
+
+## 模块约定
+- 镜像、容器、网络、Compose 和系统级端点分组管理。
+- 区分列表/查询端点和长时间运行的变更端点。
+- 命名空间说明：历史文档使用 `appcgi.dockermgr.*`，部分代码使用 `dockermgr.*`（如 `dockermgr.containerList`）。自动化调用时优先使用 `appcgi.dockermgr.*`。
+
+## 任务路由
+
+先判断是观察类还是变更类：
+
+| 用户意图 | 优先命令 | 说明 |
+| --- | --- | --- |
+| 看 Docker 总体状态 | `fnos-cli docker stats` | 适合作为进入 Docker 模块的只读探测 |
+| 看镜像 | `fnos-cli docker image ls` / `inspect` | 需要镜像详情时再下钻 inspect |
+| 拉镜像 | `fnos-cli docker image pull <imageRef> --yes` | 长耗时写操作，执行后应重新确认状态 |
+| 看容器 | `fnos-cli docker container ls [--all]` / `inspect` / `stats` / `top` | `ls` 默认只列运行中容器；停止或创建态容器需要 `--all` |
+| 启停、重启、强杀、删除容器 | `start/stop/restart/kill/rm` | 变更前建议先 inspect 或 ls |
+| 看 Compose 项目 | `fnos-cli docker compose ls` | 目前优先作为只读入口 |
+
+## 常见误判
+
+- `docker stats` 是聚合统计，不是单容器统计
+- `docker container ls` 默认不包含 stopped/created 容器；判断容器是否消失时使用 `docker container ls --all` 或按 ID 执行 `inspect`
+- 列表接口成功但省略 `data` 时，只能确认请求成功，不能据此断言资源数量为 0；CLI 会保留原始成功信封，避免把后端漏字段伪装成空列表
+- `image pull`、`container stop`、`container restart` 这类操作可能明显长于普通读请求
+- `image pull` 与 `container create/update/start/stop/restart/kill` 必须显式传 `--yes`；删除命令可交互确认，但 Agent 或非交互流程也应传 `--yes`。`--force` 和 `--yes` 不是同一个概念
+- `container update` 可能返回新 ID；CLI 会先 inspect 返回的 ID，确认本次资源字段已生效且网络配置未丢失后再报告成功。旧固件不返回 ID 时，CLI 会对原 ID 执行相同回查。后续操作使用命令输出的 ID
+- 镜像引用和容器 ID 不是同一类标识，不要混传
+
+## 高风险提醒
+
+- 变更前先跑一条只读命令确认目标是否存在、当前状态是否符合预期
+- 长耗时操作后要补一条只读命令确认结果，不要只看启动消息
+- 删除类操作不应和不相关的镜像或容器清理打包在同一轮里
+- 如果用户只说“把 Docker 弄一下”这类模糊目标，应先停下来确认是镜像、容器、网络还是 Compose
+
+## 端点索引
+- 镜像：
+  - `appcgi.dockermgr.imageList`
+  - `appcgi.dockermgr.imagePull`
+  - `appcgi.dockermgr.imageInspect`
+  - `appcgi.dockermgr.imageRemove`
+  - `appcgi.dockermgr.imageDownloadList`（通过 `docker request`）
+  - `appcgi.dockermgr.imageLoad`（通过 `docker request`）
+  - `appcgi.dockermgr.imageSave`（通过 `docker request`）
+  - `appcgi.dockermgr.imageUpgrade`（通过 `docker request`）
+  - `appcgi.dockermgr.imageCancel`（通过 `docker request`）
+- 容器：
+  - `appcgi.dockermgr.containerList`
+  - `appcgi.dockermgr.containerCreate`
+  - `appcgi.dockermgr.containerInspect`
+  - `appcgi.dockermgr.containerTop`
+  - `appcgi.dockermgr.containerStats`
+  - `appcgi.dockermgr.containerStart`
+  - `appcgi.dockermgr.containerStop`
+  - `appcgi.dockermgr.containerRestart`
+  - `appcgi.dockermgr.containerKill`
+  - `appcgi.dockermgr.containerRemove`
+  - `appcgi.dockermgr.containerModify`
+- 网络：
+  - `appcgi.dockermgr.networkCreate`
+  - `appcgi.dockermgr.networkList`
+  - `appcgi.dockermgr.networkRemove`
+  - `appcgi.dockermgr.networkConnect`
+  - `appcgi.dockermgr.networkDisconnect`
+- 系统和 Compose：
+  - `appcgi.dockermgr.stats`
+  - `appcgi.dockermgr.composeList`
+  - `appcgi.dockermgr.systemStart`（通过 `docker request`）
+  - `appcgi.dockermgr.systemStop`（通过 `docker request`）
+  - `appcgi.dockermgr.systemRestart`（通过 `docker request`）
+  - `appcgi.dockermgr.composeContainers`（通过 `docker request`）
+  - `appcgi.dockermgr.composeCreate`（通过 `docker request`）
+  - `appcgi.dockermgr.composeStart`（通过 `docker request`）
+  - `appcgi.dockermgr.composeStop`（通过 `docker request`）
+
+未封装为固定子命令的 `appcgi.dockermgr.*` 端点通过以下入口调用：
+
+```bash
+fnos-cli docker request appcgi.dockermgr.<name> --json '<object>' --yes
+```
+
+`--json` 必须是 JSON object，不能包含 `req` 或 `reqid`。泛化请求必须显式传 `--yes`，缺失时 CLI 会在读取 session 或访问网络前直接拒绝，不会进入交互提示；Docker system、network、Compose 和镜像导入导出类操作可能影响运行中服务，调用前应先执行只读探测。
+
+## 端点详情
+
+### appcgi.dockermgr.containerList
+
+#### Endpoint
+`appcgi.dockermgr.containerList`
+
+#### Purpose
+列出 Docker 容器及其运行时摘要信息。
+
+#### Trim CLI Mapping
+```
+fnos-cli docker container ls [--all]
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.dockermgr.containerList` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `all` | body | no | boolean | 是否包含停止和创建态容器 | 仅 `--all` 时发送 `true`；默认只列运行中容器 | `true` |
+
+#### Response
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+| `data` | no | array / object | 容器列表 | 格式可能因 Docker 版本而异 | `[{"name":"nginx","state":"running"}]` |
+| `result` | no | string | Terminal marker | `succ`/`fail` | `succ` |
+| `errno` | no | number | 错误码 | 失败时出现 | `65534` |
+| `errmsg` | no | string | 错误描述 | | `docker not running` |
+
+#### Protocol Notes
+- 签名请求（当 session secret 可用时）。
+- 历史名称别名：`dockermgr.containerList`。
+- 判断容器在 update/stop 后是否仍存在时，使用 `--all` 或 `container inspect <id>`，不要仅凭默认列表下结论。
+
+### appcgi.dockermgr.stats
+
+#### Endpoint
+`appcgi.dockermgr.stats`
+
+#### Purpose
+返回 Docker 聚合统计信息。
+
+#### Trim CLI Mapping
+```
+fnos-cli docker stats
+```
+
+#### Response
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+| `data` | no | object | 聚合统计 | 包含利用率指标 | `{"cpu":12.5,"mem":47.1}` |
+| `result` | no | string | Terminal marker | `succ`/`fail` | `succ` |
+
+#### Field Semantics
+- 聚合摘要端点；单容器指标使用 `containerStats`。
+
+### appcgi.dockermgr.image.* 家族
+
+#### Endpoint
+`appcgi.dockermgr.imageList`、`imagePull`、`imageInspect`、`imageRemove`
+
+#### Purpose
+管理 Docker 镜像（列表/拉取/检查/删除）。
+
+#### Trim CLI Mapping
+```
+fnos-cli docker image ls
+fnos-cli docker image pull <imageRef> --yes
+fnos-cli docker image inspect <imageRef>
+fnos-cli docker image rm <imageRef> [--force] [--yes]
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | 对应具体操作 | `appcgi.dockermgr.imageList` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `fromImage` | body | conditional | string | 镜像名（imagePull） | 不含 tag 部分 | `nginx` |
+| `tag` | body | conditional | string | 镜像标签（imagePull） | 未指定时默认 `latest` | `latest` |
+| `imageId` | body | conditional | string | 镜像 ID 或引用（inspect/rm） | 可以是后端 ID 或如 `nginx:latest` | `nginx:latest` |
+| `force` | body | no | boolean | 强制删除（imageRemove） | 仅 `--force` 时发送 | `true` |
+
+#### Field Semantics
+- `imagePull` 分割 `<imageRef>` 为 `fromImage` 和 `tag`；保留 registry 端口，如 `registry:5000/ns/app:1.0` → `fromImage="registry:5000/ns/app"`, `tag="1.0"`。
+- `imageRemove` 默认要求确认，`--yes` 跳过确认。
+- Pull/upgrade 可能是长时间运行的操作。
+
+### appcgi.dockermgr.container.* 变更/详情家族
+
+#### Endpoint
+容器创建、生命周期和观察端点
+
+#### Purpose
+容器创建、启动/停止/重启/强杀/删除、检查、进程列表和统计。
+
+#### Trim CLI Mapping
+```
+fnos-cli docker container create --image <imageRef> [--name <name>] [--start] [--restart] [--memory <mb>] [--cpu <shares>] [--env <key=value>] [--cmd <arg>] [--port <host:container[/proto]>] [--mount <source:target[:ro|rw]>] --yes
+fnos-cli docker container update <containerId> [--restart] [--memory <mb>] [--cpu <shares>] --yes
+fnos-cli docker container inspect <containerId>
+fnos-cli docker container top <containerId>
+fnos-cli docker container stats <containerId>
+fnos-cli docker container start <containerId> --yes
+fnos-cli docker container stop <containerId> --yes
+fnos-cli docker container restart <containerId> --yes
+fnos-cli docker container kill <containerId> --yes
+fnos-cli docker container rm <containerId> [--force] [--yes]
+```
+
+#### Field Semantics
+
+**containerCreate：**
+- `--image` 必填，映射到请求中的镜像引用
+- `--name` 可选容器名
+- `--start` 映射到 `startWhenCreated: true`
+- `--restart` 映射到 `restart: true`
+- `--memory <mb>` 将 MB 转换为字节（如 `128` → `134217728`）
+- `--cpu <shares>` 转发正整数 CPU shares
+- `--env <key=value>` 可重复，映射到 `env[]`
+- `--cmd <arg>` 可重复，映射到 `cmd[]`
+- `--port <host:container[/proto]>` 可重复，映射到 `port[]`；协议默认 `tcp`
+- `--mount <source:target[:ro|rw]>` 可重复，映射到 `mount[]`；权限默认 `rw`
+- 默认值：`restart=false`、`privileged=false`、`net=['bridge']`、`cpu=0`、`memory=0`
+- `create/update/start/stop/restart/kill` 必须显式传 `--yes`；`rm` 可交互确认，但 Agent 或非交互流程应传 `--yes`。
+
+**containerModify：** CLI 先读取完整容器配置，将资源变更合并到当前配置后提交。若响应带 `rsp.id`，CLI 会 inspect 该 ID，并核对 `name/image/restart/privileged/gpuEnabled/cpu/memory/env/cmd/capAdd/capDrop/link/mount/port/networks`；全部字段与提交配置一致后才报告成功，其中集合字段按无序内容比较，网络还会核对名称及静态地址。若旧固件省略 `rsp.id`，则对原 ID 执行相同回查。
+
+**containerCreate 成功响应**可能为顶层 `rsp` 对象（Docker 风格大写 key，如 `{"Id":"abcd","Warnings":[]}`），而不是嵌套在 `data.rsp` 中。
+
+**containerInspect/top/stats/start/stop/restart/kill：** 通过 `containerId` 标识。
+
+`container top` 需要目标容器处于运行状态。CLI 会先 inspect；当 `State.Running=false` 时在本地返回明确提示，不再发送会产生设备 errno 的 top 请求。
+
+**containerRemove：** 通过 `containerId` 标识；`force` 仅在 `--force` 时发送；默认要求确认，`--yes` 跳过。
+
+#### Errors
+- 常见错误：容器不存在、无效状态转换、权限不足。
+
+### appcgi.dockermgr.composeList
+
+#### Endpoint
+`appcgi.dockermgr.composeList`
+
+#### Purpose
+列出 Docker Compose 项目。
+
+#### Trim CLI Mapping
+```
+fnos-cli docker compose ls
+```
+
+## 注意事项
+- 镜像拉取/升级和 Compose 操作是长时间运行的，可能涉及进度/取消模式。
+- Docker 守护进程的启动/停止/重启是高影响操作，可能影响运行中的容器。
+- 部分端点的详细请求/响应 schema 尚未完全规范化。

package/skill/reference/download.md

@@ -0,0 +1,357 @@
+# download 模块
+
+## 模块概述
+下载中心模块，映射到 `appcgi.downloadcenter.*` 命名空间。支持通过 URL/磁力链接/种子文件创建下载任务，以及任务查询、控制和统计。
+
+下载中心请求使用与其他 CGI 调用相同的 `{ req, reqid, ...params }` 格式，但部分端点通过 `data.rsp`、`data.body` 或 `data.block.data` 返回业务数据。
+
+## 协议模型
+
+### 请求模型
+
+典型请求格式：
+
+```json
+{
+  "reqid": "250318103000ABCDEF0123456789ABCD",
+  "req": "appcgi.downloadcenter.task.query",
+  "init_flag": true,
+  "state_filter": 65535
+}
+```
+
+注意事项：
+- 部分参数在 API 层使用 camelCase（如 `initFlag`），但 CGI 层使用 snake_case（如 `init_flag`）
+- 多数端点接受可选 `uid` 参数
+- `task.addUris` 的 `save_dir` 在实际使用中是必需的
+
+### 响应模型
+
+响应数据可能嵌套在不同位置：
+
+```json
+{
+  "reqid": "...",
+  "result": "succ",
+  "req": "appcgi.downloadcenter.task.query",
+  "data": {
+    "block": {
+      "id": "20260318160514HlEnuPgC19HGBlXP",
+      "total_size": 41653,
+      "offset": 0,
+      "data": "{\"tasks\":[],\"stats\":{}}"
+    }
+  }
+}
+```
+
+业务数据可能位于 `data.rsp`、`data.body` 或 `data.block.data`（JSON 字符串需解码）。
+
+### 终态和错误处理
+
+终态值：`succ`、`fail`、`cancel`
+
+处理规则：
+- 传输完成和业务成功是独立关注点
+- 保留 `errno`、`errmsg` 和 `extra`
+- 部分控制类端点成功时返回简单的 `"ok"`
+- 部分端点返回 `{ code: 200, body: {} }` 格式
+- 批量创建端点可能返回 `errs[]`（即使请求本身成功）
+
+### 大块传输
+
+- 单包不超过 1 MiB
+- 大载荷使用相同 `reqid` 分块传输
+- 响应包含 `block.id`、`block.total_size`、`block.offset`、`block.data`
+
+## 端点索引
+
+### 查询类（已实现）
+- `appcgi.downloadcenter.task.query` — 任务列表和统计
+- `appcgi.downloadcenter.task.search` — 关键字搜索
+- `appcgi.downloadcenter.task.getInfo` — 任务详情
+- `appcgi.downloadcenter.task.getFiles` — 任务文件列表
+
+### 创建类（已实现）
+- `appcgi.downloadcenter.task.addUris` — 从 URL/磁力链接创建
+- `appcgi.downloadcenter.task.addPaths` — 从 NAS 上的种子文件创建
+
+### 控制类（已实现）
+- `appcgi.downloadcenter.task.pause` — 暂停任务
+- `appcgi.downloadcenter.task.resume` — 恢复任务
+- `appcgi.downloadcenter.task.retry` — 重试任务
+- `appcgi.downloadcenter.task.delete` — 删除任务
+
+### 统计类（已实现）
+- `appcgi.downloadcenter.stat.all` — 汇总统计
+
+### 泛化请求入口
+
+未封装为固定子命令的 `appcgi.downloadcenter.*` 端点通过以下入口调用：
+
+```bash
+fnos-cli download request appcgi.downloadcenter.<name> --json '<object>' --yes
+```
+
+- `--json` 必须是 JSON object，不能包含 `req` 或 `reqid`，CLI 会自动注入。
+- 默认需要交互确认；自动化或确认过风险后用 `--yes`。
+- 响应会按下载中心常见位置解包：`data.rsp`、`data.body`、`data.block.data`。
+
+通过 `download request` 覆盖的端点包括：
+- 创建类：`task.addfnShareLink`、`task.getfnShareLinkStatus`
+- 控制类：`task.pin`、`task.setForceStart`、`task.setFilePriority`、`task.exportTorrentFile`、`task.setDownloadLimit`、`task.setUploadLimit`、`task.setShareLimit`
+- 配置类：`config.getDefaultSaveDir`、`config.setDefaultSaveDir`、`config.getTransferCfg`、`config.setTransferCfg`、`config.getNetworkCfg`、`config.setNetworkCfg`、`config.getAltCfg`、`config.setAltCfg`、`config.getListColumns`、`config.setListColumns`
+- 统计类：`stat.qbittorrent`、`stat.aria2`
+- Tracker 类：`task.getTrackers`、`task.addTrackers`、`task.removeTrackers`、`task.editTracker`、`tracker.query`、`tracker.insert`、`tracker.delete`
+- Peer 类：`task.getPeers`、`task.addPeers`、`transfer.banPeers`
+- 扫描目录：`scanDir.query`、`scanDir.insert`、`scanDir.delete`
+- 工具类：`util.getDirFreeSpace`、`util.isTcpPortInUse`
+- 管理员：`admin.getUsers`
+
+`task.addUploadFile` 涉及上传文件内容和大块传输，不是普通 JSON 参数请求；优先使用文件上传相关命令完成本地文件上传后，再按设备行为调用下载中心端点。
+
+## 端点详情
+
+### appcgi.downloadcenter.task.query
+
+#### Endpoint
+`appcgi.downloadcenter.task.query`
+
+#### Purpose
+查询任务列表、聚合统计和下载引擎错误信息。
+
+#### Trim CLI Mapping
+```
+fnos-cli download ls
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.downloadcenter.task.query` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `engine_types` | body | no | array | 引擎类型过滤 | 可选 | `[1,2]` |
+| `ids` | body | no | array | 指定任务 ID | 可选 | `[42,43]` |
+| `state_filter` | body | no | number | 状态过滤掩码 | CLI 默认 `65535`（所有状态） | `65535` |
+| `type_filter` | body | no | number | 类型过滤 | 可选 | `1` |
+| `init_flag` | body | no | boolean | 初始化标志 | CLI 默认 `true` | `true` |
+| `uid` | body | no | number | 用户 ID | 可选 | `1000` |
+
+#### Response
+主要响应字段（位于 `data.block.data` 解码后）：
+
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+| `tasks` | no | array | 任务列表 | 包含任务摘要信息 | `[...]` |
+| `stats` | no | object | 聚合统计 | 速度和大小统计 | `{...}` |
+| `errors` | no | array | 引擎错误 | 下载引擎报告的错误 | `[...]` |
+
+常见任务字段：`id`、`type`、`name`、`state`、`total_size`、`size`、`dl_speed`、`up_speed`、`save_dir`、`uri`、`addition_time`、`error_code`、`error_message`
+
+### appcgi.downloadcenter.task.search
+
+#### Endpoint
+`appcgi.downloadcenter.task.search`
+
+#### Purpose
+按任务名或文件名搜索下载任务。
+
+#### Trim CLI Mapping
+```
+fnos-cli download ls <keyword>
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.downloadcenter.task.search` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `keyword` | body | yes | string | 搜索关键字 | 按任务名或文件名匹配 | `ubuntu` |
+| `uid` | body | no | number | 用户 ID | 可选 | `1000` |
+
+### appcgi.downloadcenter.task.getInfo
+
+#### Endpoint
+`appcgi.downloadcenter.task.getInfo`
+
+#### Purpose
+获取单个下载任务的详细信息。
+
+#### Trim CLI Mapping
+```
+fnos-cli download info <id>
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.downloadcenter.task.getInfo` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `id` | body | yes | number | 任务 ID | 正整数 | `42` |
+| `uid` | body | no | number | 用户 ID | 可选 | `1000` |
+
+#### Response
+主要响应字段（位于 `body` 中）：
+
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+| `name` | no | string | 任务名称 | | `ubuntu-22.04.iso` |
+| `total_size` | no | number | 总大小（bytes） | | `4194304` |
+| `save_path` | no | string | 保存路径 | | `/vol1/downloads` |
+| `dl_speed` | no | number | 下载速度 | | `1048576` |
+| `up_speed` | no | number | 上传速度 | | `0` |
+| `eta` | no | number | 预计剩余时间 | | `120` |
+| `seeds` | no | number | 种子数 | | `5` |
+| `peers` | no | number | 对等节点数 | | `12` |
+| `share_ratio` | no | number | 分享比 | | `0.5` |
+| `addition_date` | no | number | 添加时间 | | `1710000000` |
+| `completion_date` | no | number | 完成时间 | | `1710100000` |
+
+### appcgi.downloadcenter.task.getFiles
+
+#### Endpoint
+`appcgi.downloadcenter.task.getFiles`
+
+#### Purpose
+获取下载任务的文件列表，对 BT 类任务尤其有用。
+
+#### Trim CLI Mapping
+```
+fnos-cli download files <id>
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.downloadcenter.task.getFiles` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `id` | body | yes | number | 任务 ID | 正整数 | `42` |
+| `mode` | body | no | number | 获取模式 | `1` 表示立即获取 | `1` |
+| `uid` | body | no | number | 用户 ID | 可选 | `1000` |
+
+#### Response
+主要响应字段（位于 `body[]` 中）：
+
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+| `index` | no | number | 文件序号 | | `0` |
+| `name` | no | string | 文件名 | | `readme.txt` |
+| `size` | no | number | 文件大小 | | `1024` |
+| `progress` | no | number | 下载进度 | | `0.75` |
+| `priority` | no | number | 优先级 | `0` 不下载，`1` 正常，`7` 最高 | `1` |
+
+### appcgi.downloadcenter.task.addUris
+
+#### Endpoint
+`appcgi.downloadcenter.task.addUris`
+
+#### Purpose
+从 URL 或磁力链接创建下载任务。
+
+#### Trim CLI Mapping
+```
+fnos-cli download add-uri <uri> <saveDir> --yes
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.downloadcenter.task.addUris` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `uris` | body | yes | string[] | URI 列表 | 支持 http/https/ftp/sftp/magnet | `["magnet:?xt=..."]` |
+| `save_dir` | body | yes | string | 保存目录 | 必须为 `/vol{v}/...` 格式 | `/vol1/downloads` |
+| `select_files` | body | no | array | 选择文件 | BT 类输入时有意义 | `[0,1,2]` |
+| `uris_type` | body | no | number | URI 类型 | `0` 默认，`1` qBittorrent | `0` |
+
+#### Response
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+| `ids` | no | number[] | 创建的任务 ID | | `[42]` |
+| `errs` | no | array | 逐项错误 | 请求成功但部分项失败时出现 | `[{"uri":"...","err":"..."}]` |
+
+### appcgi.downloadcenter.task.addPaths
+
+#### Endpoint
+`appcgi.downloadcenter.task.addPaths`
+
+#### Purpose
+从 NAS 上已有的种子文件创建下载任务。
+
+#### Trim CLI Mapping
+```
+fnos-cli download add-path <path> <saveDir> --yes
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.downloadcenter.task.addPaths` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `paths` | body | yes | string[] | 种子文件路径列表 | 必须为 `/vol{v}/...` 格式 | `["/vol1/torrents/demo.torrent"]` |
+| `save_dir` | body | yes | string | 保存目录 | 必须为 `/vol{v}/...` 格式 | `/vol1/downloads` |
+| `select_files` | body | no | array | 选择文件 | 可选 | `[0,1]` |
+
+#### Response
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+| `ids` | no | number[] | 创建的任务 ID | | `[43]` |
+| `errs` | no | array | 逐项错误 | 请求成功但部分项失败时出现 | `[...]` |
+
+### 控制类端点
+
+#### appcgi.downloadcenter.task.pause / resume / retry / delete
+
+这四个端点共享相同的请求结构。
+
+#### Trim CLI Mapping
+```
+fnos-cli download pause <id...> --yes
+fnos-cli download resume <id...> --yes
+fnos-cli download retry <id...> --yes
+fnos-cli download rm <id...> --yes
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | 对应具体操作 | `appcgi.downloadcenter.task.pause` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `ids` | body | yes | number[] | 任务 ID 列表 | 支持批量操作 | `[42, 43]` |
+| `uid` | body | no | number | 用户 ID | 可选 | `1000` |
+| `delete_files` | body | no | boolean | 是否同时删除文件 | 仅 `delete` 端点可用；CLI 默认不删除文件 | `false` |
+
+#### Response
+成功时通常返回 `"ok"`。
+
+### appcgi.downloadcenter.stat.all
+
+#### Endpoint
+`appcgi.downloadcenter.stat.all`
+
+#### Purpose
+获取下载中心的汇总统计信息。
+
+#### Trim CLI Mapping
+```
+fnos-cli download stat
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.downloadcenter.stat.all` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `uid` | body | no | number | 用户 ID | 可选 | `1000` |
+
+#### Response
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+| `dl_speed` | no | number | 总下载速度 | | `1048576` |
+| `dl_total_size` | no | number | 总下载量 | | `10737418240` |
+| `up_speed` | no | number | 总上传速度 | | `524288` |
+| `up_total_size` | no | number | 总上传量 | | `5368709120` |
+
+## 注意事项
+- 文件上传（`task.addUploadFile`）需要上传内容和大块传输支持，不应当作普通 `download request --json` 调用。
+- `task.addfnShareLink` 是下载中心的导入任务端点，不要与 `appcgi.sharesvr.share.link.*` 的共享链接管理端点混淆。
+- 部分响应数据的具体字段结构可能因后端版本而异。