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

package/skill/reference/_conventions.md

@@ -0,0 +1,76 @@
+# API 文档约定
+
+本目录包含 fnos-cli 支持的 fnOS API 模块参考文档。
+
+## 文档结构
+
+每个模块文档包含：
+
+1. **模块概述**：模块功能和用途
+2. **模块约定**：模块级别的共享规则和注意事项
+3. **端点索引**：模块包含的所有端点列表
+4. **端点详情**：每个端点的完整说明
+5. **注意事项**：使用中需要关注的行为差异或限制
+
+## 端点详情格式
+
+每个端点包含以下部分（按顺序）：
+
+### Endpoint
+端点的完整名称（如 `appcgi.file.ls`）
+
+### Purpose
+端点的功能说明
+
+### Trim CLI Mapping
+对应的 fnos-cli 命令形式；如果未实现则标注 `Not implemented in fnos-cli yet`
+
+### Request
+请求参数表格：
+
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+
+**Location 取值：**
+- `body`：JSON 请求体顶层字段
+- `query`：URL 查询参数
+- `path`：URL 路径变量
+- `header`：协议头字段
+- `wrapped body`：嵌套在请求体内的字段（如 `data.body.*`）
+
+### Response
+响应字段表格：
+
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+
+### Protocol Notes
+影响自动化的协议行为：
+- 认证要求（token / session / signature）
+- 数据包终止行为（`result`、多包流式响应）
+- 签名格式：当 session 中存在 `secret` 且端点不在直通集合中时，使用 HMAC-SHA256 签名
+- 签名载荷格式：`<base64-hmac-signature><json-body>`
+- 签名密钥：session `secret` 的 base64 解码值
+- 签名前会在 JSON 中注入 `si`（如可用）
+- 特殊封装结构（如嵌套 `data.body`）
+
+### Field Semantics
+字段语义的详细说明和约束
+
+### Errors
+常见错误码和错误信息
+
+## 路径约定
+
+fnOS 文件路径使用 canonical 格式：`/vol{v}/...`
+
+示例：
+- `/vol1/downloads`
+- `/vol3/1000/media`
+
+## 通用响应信封
+
+大多数端点响应包含以下通用字段：
+- `result`：终态标记，`succ` 或 `fail`
+- `errno`：数值错误码（失败时出现）
+- `errmsg`：错误描述（失败时出现）

package/skill/reference/_index.md

@@ -0,0 +1,78 @@
+# fnos-cli 参考索引
+
+本目录既提供模块 reference，也提供面向 Agent 的任务入口。优先按任务找文档；只有当你已经清楚目标模块时，才直接跳到模块表。
+
+## 按任务找文档
+
+| 任务 | 先看文档 | 何时继续下钻 |
+| --- | --- | --- |
+| 登录、登出、profile session、连接失败、session 回落 | [user.md](user.md) | 需要用户、用户组、登录设备或 profile/raw 认证细节时继续看 `user.md` |
+| 列目录、判断当前用户目录、搜索文件 | [workflows/file-routing.md](workflows/file-routing.md) | 确认命令方向后，再看 [file.md](file.md) |
+| 验证上传、同名策略或大文件断点续传 | [workflows/file-upload-validation.md](workflows/file-upload-validation.md) | 需要请求字段和缓存语义时，再看 [file.md](file.md) |
+| 看共享目录、ACL、别人共享给我的文件 | [workflows/file-routing.md](workflows/file-routing.md) | 需要 `file share.*` 或 `file.getAcl` 细节时，再看 [file.md](file.md) |
+| 查看下载任务、创建下载任务 | [download.md](download.md) | 下载任务路径仍要遵守 canonical `/vol{n}/...` 规则 |
+| 查看或管理应用中心应用、安装 fpk | [app-center.md](app-center.md) | 写操作需要 `--yes`，复杂依赖/向导转 App Center UI |
+| 搜索照片、查看照片详情或预览地址 | [photos.md](photos.md) | 需要先有有效代理 session |
+| AI 搜图、统计匹配数量或生成照片预览链接 | [workflows/photos-routing.md](workflows/photos-routing.md) | 先区分匹配总数、本次返回条数和预览链接 |
+| 查看系统信息、CPU、内存、日志 | [sysinfo.md](sysinfo.md)、[resmon.md](resmon.md)、[log.md](log.md) | 根据具体目标跳到对应模块 |
+| 发送未封装的已认证请求 | [user.md](user.md) | 先确认 session/profile 是否可用，再决定是否使用 `raw <req>` |
+| 开启或关闭 SSH 服务 | [network.md](network.md) | 启用 SSH 属于安全敏感操作，执行前确认授权 |
+| 重启或关闭 NAS | [power.md](power.md) | 高影响写操作，必须确认目标设备和授权 |
+| 查看 Docker 镜像、容器、Compose，或执行启停/删除 | [dockermgr.md](dockermgr.md) | 长耗时和删除类操作先看模块里的高风险提醒 |
+| 查看存储池、磁盘、SMART | [stor.md](stor.md) | 读操作可直接在模块文档中选命令 |
+| 做挂载、卸载、扩容、替盘、格式化、弹出等存储写操作 | [workflows/storage-dangerous-ops.md](workflows/storage-dangerous-ops.md) | 确认顺序后，再看 [stor.md](stor.md) 的字段和端点约束 |
+| 做真机验证 | [workflows/device-validation.md](workflows/device-validation.md) | 具体接口细节再回对应模块文档 |
+
+## workflow 目录
+
+| 文档 | 用途 |
+| --- | --- |
+| [workflows/file-routing.md](workflows/file-routing.md) | 路由文件相关需求，区分 `/`、当前用户目录、具体 `/vol{n}/...`、共享目录和搜索入口 |
+| [workflows/file-upload-validation.md](workflows/file-upload-validation.md) | 验证小文件上传、同名策略、大文件缓存身份和并发续传 |
+| [workflows/photos-routing.md](workflows/photos-routing.md) | 路由相册统计、AI 搜索和抽样预览需求 |
+| [workflows/storage-dangerous-ops.md](workflows/storage-dangerous-ops.md) | 在高风险存储写操作前固定先做只读探测、密码验证和确认 |
+| [workflows/device-validation.md](workflows/device-validation.md) | 统一真机 OAuth、最小探测、写后回归和清理口径 |
+
+## 正式入口目录
+
+| 文档 | 用途 |
+| --- | --- |
+| [../entries/trim-shared.md](../entries/trim-shared.md) | 通用连接、session、wrapper、真机验证规则 |
+| [oauth.md](oauth.md) | OAuth PKCE、pending、refresh、存储预检、401 重试和 profile 锁 |
+| [../entries/trim-file.md](../entries/trim-file.md) | 文件、共享目录、ACL、路径路由 |
+| [../entries/trim-storage.md](../entries/trim-storage.md) | 存储池、磁盘、SMART、高风险写操作 |
+| [../entries/trim-docker.md](../entries/trim-docker.md) | Docker 镜像、容器、Compose 和长耗时操作 |
+| [../entries/trim-user.md](../entries/trim-user.md) | 认证、用户、用户组、权限确认 |
+| [../entries/trim-download.md](../entries/trim-download.md) | 下载任务列表/详情、创建、暂停/恢复/重试/删除、路径校验 |
+| [../entries/trim-app.md](../entries/trim-app.md) | 应用中心应用列表、状态、安装、fpk 手动安装、更新、启动、停用、卸载 |
+| [../entries/trim-log.md](../entries/trim-log.md) | 日志列表、模块过滤、清除/导出/归档、老版本接口提醒 |
+| [../entries/trim-system.md](../entries/trim-system.md) | 静态系统信息、机器类型、版本、身份识别 |
+| [../entries/trim-monitor.md](../entries/trim-monitor.md) | 运行态指标（CPU、内存）和 resmon 指标路由 |
+| [../entries/trim-network.md](../entries/trim-network.md) | 网络服务开关，当前覆盖 SSH 服务 |
+| [../entries/trim-photos.md](../entries/trim-photos.md) | 相册目录、搜索、详情和预览链接 |
+
+## 按模块找文档
+
+| 模块 | 文件 | 说明 |
+| --- | --- | --- |
+| user | [user.md](user.md) | 认证、用户管理、用户组管理、登录设备 |
+| file | [file.md](file.md) | 文件操作、finder 搜索、共享目录、ACL |
+| download | [download.md](download.md) | 下载任务查询、创建、控制 |
+| app-center | [app-center.md](app-center.md) | 应用中心查询、安装、更新、启动、停用、卸载 |
+| stor | [stor.md](stor.md) | 存储池、磁盘、SMART、挂载/弹出、格式化 |
+| dockermgr | [dockermgr.md](dockermgr.md) | Docker 镜像、容器、网络、Compose 管理 |
+| log | [log.md](log.md) | 日志查询、导出、清除、归档策略 |
+| resmon | [resmon.md](resmon.md) | CPU、内存等资源监控 |
+| sysinfo | [sysinfo.md](sysinfo.md) | 系统信息和机器类型 |
+| network | [network.md](network.md) | 网络服务开关 |
+| power | [power.md](power.md) | 重启或关闭 NAS |
+| photos | [photos.md](photos.md) | Photos 认证、搜索、详情和预览 URL |
+
+## 文档约定
+
+所有模块文档遵循 [_conventions.md](_conventions.md) 定义的统一格式。workflow 文档只负责操作顺序、停手条件和常见误判，不重复完整字段表。
+
+补充约定：
+
+- profile/session、`login` / `logout`、`raw` 的共享认证链路统一看 [user.md](user.md)。
+- 输入 guard 遇到控制字符、空值或过长值时会直接报错；skill 示例不要假设 CLI 会帮忙清洗参数。

package/skill/reference/app-center.md

@@ -0,0 +1,234 @@
+# App Center reference
+
+## Command overview
+
+| Command | Purpose | Output |
+| --- | --- | --- |
+| `app list` | List installed App Center apps | JSON |
+| `app status <appName>` | Show one installed app record | JSON |
+| `app base-data` | Read App Center sidebar/source/tag base data | JSON |
+| `app store list` | List cloud App Center packages | JSON |
+| `app store search <keyword>` | Search cloud App Center packages | JSON |
+| `app store detail <appName>` | Show cloud package detail | JSON |
+| `app store latest-release` | List latest release packages | JSON |
+| `app check-update` | Check App Center update availability | JSON |
+| `app check-update --post` | Trigger an App Center update check | Success message |
+| `app common volume` | Read remembered App Center volume | JSON |
+| `app common volume --set <volumeId>` | Set remembered App Center volume | Success message |
+| `app config sys/list/detail/auth-paths/wizard` | Read App Center system and app config | JSON |
+| `app config set-sys --fields <json>` | Update App Center system config fields | Success message |
+| `app config set <appName> --fields <json>` | Update one app config payload | Success message |
+| `app config auto-update <appName>` | Enable or disable app auto update | Success message |
+| `app config proxy-access <appName>` | Allow or deny proxy access | Success message |
+| `app config post-wizard <appName> --fields <json>` | Submit app wizard custom parameters | Success message |
+| `app service list` | List service metadata | JSON |
+| `app entry list` | List available application entries | JSON |
+| `app desktop list` | List the current user's desktop layout and entries | JSON |
+| `app guide check-installed <appName...>` | Check whether guide-required apps are installed | JSON |
+| `app guide batch-download-install <volumeId> <appName...>` | Start guide batch download/install tasks | Success message |
+| `app operation settings` | Read operation settings | JSON |
+| `app openapi app-detail <appName>` | Read OpenAPI app detail for authorization flows | JSON |
+| `app openapi allow-user-auth-paths <appName>` | Read whether users may authorize paths to an app | JSON |
+| `app openapi add-user-auth-path <appName> <path>` | Add current-user authorization path for an app | Success message |
+| `app openapi add-user-auth-inherit-file <appName> <path>` | Add inherited-file authorization for an app | Success message |
+| `app sac app-store-list` | Read SAC App Store entry list | JSON |
+| `app task-status <taskId>` | Query an App Center common task | JSON |
+| `app task-cancel <taskId>` | Cancel an App Center common task | Success message |
+| `app download cancel <downloadTaskId>` | Cancel an App Center download task | Success message |
+| `app install-cancel <taskId>` | Cancel an App Center install task | Success message |
+| `app update-cancel <taskId>` | Cancel an App Center update task | Success message |
+| `app install <appName>` | Download and install an App Center package by name and version | Success message |
+| `app install <appName> --dry-run` | Download and inspect an App Center package without starting install | Success message |
+| `app install-fpk <localFile.fpk>` | Upload and install a local fpk package | Success message |
+| `app install-fpk --remote-path /vol.../*.fpk` | Install an fpk package already stored on the NAS | Success message |
+| `app install-fpk <localFile.fpk> --dry-run` / `--remote-path ... --dry-run` | Inspect an fpk package without starting install | JSON plan |
+| `app update <appName>` | Download and update an installed app to a target version | Success message |
+| `app update <appName> --dry-run` | Download and inspect an App Center update without starting update | Success message |
+| `app start <appName>` | Start an installed app | Success message |
+| `app stop <appName>` | Stop an installed app | Success message |
+| `app restart <appName>` | Restart an installed app | Success message |
+| `app uninstall <appName>` | Uninstall an installed app | Success message |
+
+## Endpoints
+
+| Command | Method | Endpoint |
+| --- | --- | --- |
+| `app list` / `app status` | GET | `/app-center/v1/app/installed` |
+| `app base-data` | GET | `/app-center/v2/config/base-data` |
+| `app store list` | GET | `/app-center/v1/app/list` |
+| `app store search` | GET | `/app-center/v1/app/search` |
+| `app store detail` | GET | `/app-center/v1/app/detail` |
+| `app store latest-release` | GET | `/app-center/v1/app/latest-release` |
+| `app check-update` | GET/POST | `/app-center/v1/check-update` |
+| `app common volume` | GET/POST | `/app-center/v1/common/remember-volume` |
+| `app config sys` | GET | `/app-center/v1/sysconfig` |
+| `app config set-sys` | POST | `/app-center/v1/sysconfig` |
+| `app config list/detail/auth-paths/wizard` | GET | `/app-center/v1/config/*` |
+| `app config set` | POST | `/app-center/v1/config` |
+| `app config auto-update` | POST | `/app-center/v1/config/app/auto-update` |
+| `app config proxy-access` | POST | `/app-center/v1/config/proxy-access-allowed` |
+| `app config post-wizard` | POST | `/app-center/v1/config/wizard` |
+| `app service list` | GET | `/app-center/v1/service/list` |
+| `app entry list` | WebSocket CGI | `appcgi.sac.entry.v1.getEntryList` |
+| `app desktop list` | WebSocket CGI | `appcgi.sac.entry.v1.getUserDesktop` |
+| `app guide check-installed` | POST | `/app-center/v1/app/check-installed` |
+| `app guide batch-download-install` | POST | `/app-center/v1/batch-download-install` |
+| `app operation settings` | GET | `/app-center/v1/operation/settings` |
+| `app openapi app-detail` | GET | `/app-center/openapi/v1/app/detail` |
+| `app openapi allow-user-auth-paths` | GET | `/app-center/openapi/v1/app/allow-user-authorization-paths` |
+| `app openapi add-user-auth-path` | POST | `/app-center/openapi/v1/user/authorization-paths` |
+| `app openapi add-user-auth-inherit-file` | POST | `/app-center/openapi/v1/user/authorization-paths/inherit-file` |
+| `app sac app-store-list` | WebSocket CGI | `appcgi.sac.entry.v1.appStoreList` |
+| `app task-status` | POST | `/app-center/v1/common/task-status` |
+| `app task-cancel` | POST | `/app-center/v1/common/task-cancel` |
+| `app download cancel` | POST | `/app-center/v1/download/cancel` |
+| `app install` info | GET | `/app-center/v1/install/info` |
+| `app install` start | POST | `/app-center/v1/install/task` |
+| `app install-cancel` | POST | `/app-center/v1/install/cancel` |
+| `app install-fpk` upload | POST | `/app-center/v1/download/upload` |
+| `app install-fpk --remote-path` package task | POST | `/app-center/v1/download/task` with `packageSourceType=file` and `path` |
+| `app install-fpk` upload status | GET | `/app-center/v1/download/status` |
+| `app update` info | GET | `/app-center/v1/update/info` |
+| `app update` start | POST | `/app-center/v1/update/task` |
+| `app update-cancel` | POST | `/app-center/v1/update/cancel` |
+| `app start` check/start | POST | `/app-center/v1/start/check`, `/app-center/v1/start/start` |
+| `app stop` check/start | POST | `/app-center/v1/stop/check`, `/app-center/v1/stop/start` |
+| `app restart` | POST | `/app-center/v1/restart` |
+| `app uninstall` info/start | GET/POST | `/app-center/v1/uninstall/info`, `/app-center/v1/uninstall/start` |
+
+## Safety behavior
+
+All write commands require `--yes`.
+
+`app store detail` accepts optional `--source-id` and `--version` when the store result includes a source identifier or a specific version is needed.
+
+`app task-cancel` requires `--yes`. The common task status/cancel endpoints use `taskID` in the request body.
+
+`app check-update --post`, `app common volume --set`, `app download cancel`, `app install-cancel`, `app update-cancel`, `app restart`, config writes, and guide batch download/install are write operations and require `--yes`.
+
+OpenAPI user authorization write commands require `--yes` and require a concrete `/vol...` path. These commands model app/user authorization flows rather than global App Center settings.
+
+For config write commands, `--fields` must be a JSON object. `app config set` adds `appName` to that object before sending it. `app config post-wizard` also adds `appName`; include `customParameters` in `--fields`.
+
+`app config set-sys` validates common App Center settings before sending:
+
+- `downloadAndInstallVolumeID` must be `-1` or a positive integer.
+- `globalAutoUpdate.enabled` must be boolean when present.
+- When global auto update is enabled, or either update time is provided, `updateStartTime` and `updateEndTime` are both required, must use `HH:MM`, and the effective window must be at least 60 minutes.
+- `cloudSecuritySync.enabled` must be boolean when present.
+- When cloud security sync is enabled, or `strategy` is provided, `strategy` must be `strict`, `balanced`, or `lenient`.
+- `autoRunNewApp` must be boolean when present.
+- `autoCreateDesktopIcon` is not sent by the current App Center UI payload. CLI refuses it by default and only sends it when `--allow-desktop-icon-field` is passed; when allowed, it must be boolean.
+
+`app install` and `app update` default to `--package-type cloud`. They create and poll an App Center cloud download task before calling install/update info and task endpoints, then wait for the returned install/update task to finish. With `--dry-run`, they still download/parse the cloud package and apply safety guards, but they do not call the install/update task endpoint. `app install-fpk` derives `packageType` from the uploaded or remote package status and commonly uses `file`.
+
+`app install`, `app update`, and `app install-fpk` accept explicit wizard inputs:
+
+- `--custom-parameters '<jsonArray>'` sends App Center `customParameters`.
+- `--api-scope '<jsonObject>'` sends `systemParameters.apiScope`.
+- `--accept-license` explicitly accepts package license confirmation outside App Center UI.
+- `--cancel-on-failure` attempts the matching install/update cancel endpoint if the install/update task reaches a failed status; the original failure context remains in stderr.
+- If App Center reports that custom wizard parameters are required and `--custom-parameters` is not provided, CLI refuses before starting the install/update task.
+
+For `app install`, `app update`, and `app install-fpk`, `--volume-id` is recommended. If omitted, CLI reads App Center sysconfig and uses `downloadAndInstallVolumeID`, with `volumeID` as compatibility fallback. The value must be positive; if no usable default exists, CLI rejects and asks for `--volume-id`.
+
+Use `app install-fpk <localFile.fpk> --volume-id <volumeId> --dry-run --yes` before a risky manual install. Dry-run still uploads a local FPK so App Center can parse it, then reads install info and applies CLI safety guards, but it does not call `/app-center/v1/install/task`.
+
+Use `app install-fpk --remote-path /vol.../*.fpk --dry-run --yes` for an FPK that is already on the NAS. The path must be a concrete `/vol...` path, must end with `.fpk`, and the remote file size must be no larger than 10GB. CLI checks the remote file property before creating the App Center remote package task.
+
+If an install or update task fails, stderr includes the task id plus `appName`, `version`, `packageType`, install/data volume ids, immediate-start flag, status/progress, and any backend `message` or `outputText`. With `--cancel-on-failure`, stderr also says whether the cancel request was attempted or failed.
+
+Known storage errors are diagnosed in addition to the raw backend response. For manual FPK upload, `20001` means the selected storage volume is unavailable; choose a mounted, healthy volume id before retrying.
+
+If start or stop returns `10500`, App Center reports that the status operation is not supported for the current app state/control data. Inspect `app status` or use App Center UI.
+
+For `app install`, pass `--source-id` when the cloud app source identifier is known. `app update` resolves `sourceID` from the installed app list.
+
+The CLI refuses cases that require App Center UI decisions:
+
+- license confirmation without explicit `--accept-license`
+- custom install/update wizard parameters without explicit `--custom-parameters`
+- custom uninstall wizard parameters
+- unsupported install types other than `volume` or `root`
+- Docker unavailable or uninitialized for install/update
+- OS version mismatch
+- dependency app install/update/start changes
+- running dependent apps for stop/uninstall
+
+Root install packages are supported by sending install volume as `0` while keeping data volume as the selected volume, matching App Center behavior.
+
+Uninstall waits until the app no longer appears in the installed app list. This avoids starting a follow-up install while the backend is still removing the previous installation.
+
+## Failure handling matrix
+
+| Condition | CLI behavior | What to do |
+| --- | --- | --- |
+| License confirmation is required and `--accept-license` is missing | Rejects before install/update task | Pass `--accept-license` only after reviewing the license, or use App Center UI |
+| Custom install/update wizard parameters are required and `--custom-parameters` is missing | Rejects before install/update task | Pass explicit wizard JSON or use App Center UI |
+| Custom uninstall wizard parameters are required | Rejects before uninstall task | Use App Center UI |
+| Unsupported install type | Rejects before install/update task | Use App Center UI |
+| Docker is unavailable or uninitialized | Rejects before install/update task | Fix Docker or use App Center UI |
+| OS version is incompatible | Rejects before install/update/start task | Choose a compatible app or OS version |
+| Dependency app changes are required | Rejects before install/update/start task | Use App Center UI to review dependency operations |
+| Running dependent apps would be affected | Rejects stop/uninstall, and install/update where applicable | Stop/review dependent apps in App Center UI |
+| Cloud download fails | Reports cloud download task id plus app/version/source/volume context | Check sourceID, version, network, and App Center availability |
+| Install/update task fails with `--cancel-on-failure` | Reports task failure context and attempts the matching cancel endpoint | Inspect stderr for cancel result, then verify task state in App Center if needed |
+| Cloud install/update dry-run passes | Prints a success message and does not start install/update task | Review app/version/package/volume before running without `--dry-run` |
+| FPK upload fails | Reports upload task id and upload context | Check package validity and target volume |
+| FPK upload returns `20001` | Reports storage-unavailable diagnostic plus raw response | Check that the selected volume exists, is mounted, and is healthy |
+| FPK dry-run passes | Outputs JSON plan and does not start install task | Review app/version/package/volume before running without `--dry-run` |
+| Remote FPK path or size is invalid | Rejects before App Center download task | Use a concrete `/vol.../*.fpk` path and a file no larger than 10GB |
+| Default install volume is missing | Rejects before download/install task | Pass `--volume-id` or configure App Center default download/install volume |
+| `set-sys` field validation fails | Rejects before network request | Fix the field type, enum, volume id, or update time window |
+| Install/update task fails | Reports task id plus app/version/package/volume/status/progress/backend message | Use the context to identify package, version, volume, or backend script failure |
+| Start/stop returns `10500` | Reports status-operation diagnostic plus raw response | Inspect `app status` or use App Center UI |
+| Uninstall does not disappear from installed list | Times out with the app name | Inspect App Center UI or retry after backend task settles |
+
+## Examples
+
+```bash
+./scripts/fnos-cli app list
+./scripts/fnos-cli app status trim.alist
+./scripts/fnos-cli app store list
+./scripts/fnos-cli app store search alist
+./scripts/fnos-cli app store detail trim.alist --source-id 265 --version 3.0.13
+./scripts/fnos-cli app store latest-release
+./scripts/fnos-cli app check-update
+./scripts/fnos-cli app check-update --post --yes
+./scripts/fnos-cli app common volume
+./scripts/fnos-cli app common volume --set 2 --yes
+./scripts/fnos-cli app config sys
+./scripts/fnos-cli app config detail trim.alist
+./scripts/fnos-cli app service list
+./scripts/fnos-cli app entry list --only-hidden
+./scripts/fnos-cli app desktop list
+./scripts/fnos-cli app config set-sys --fields '{"autoRunNewApp":true}' --yes
+./scripts/fnos-cli app config set trim.alist --fields '{"services":[],"extraAuthorizationPath":[]}' --yes
+./scripts/fnos-cli app config auto-update trim.alist --enable --yes
+./scripts/fnos-cli app config proxy-access trim.alist --allowed --yes
+./scripts/fnos-cli app config post-wizard trim.alist --fields '{"customParameters":[]}' --yes
+./scripts/fnos-cli app guide check-installed trim.media trim.photos
+./scripts/fnos-cli app guide batch-download-install 2 trim.media trim.photos --yes
+./scripts/fnos-cli app operation settings
+./scripts/fnos-cli app openapi app-detail trim.alist
+./scripts/fnos-cli app openapi allow-user-auth-paths trim.alist
+./scripts/fnos-cli app openapi add-user-auth-path trim.alist /vol1/1000/docs --yes
+./scripts/fnos-cli app openapi add-user-auth-inherit-file trim.alist /vol1/1000/docs/file.txt --yes
+./scripts/fnos-cli app sac app-store-list
+./scripts/fnos-cli app task-status <taskId>
+./scripts/fnos-cli app task-cancel <taskId> --yes
+./scripts/fnos-cli app download cancel <downloadTaskId> --yes
+./scripts/fnos-cli app install-cancel <taskId> --yes
+./scripts/fnos-cli app update-cancel <taskId> --yes
+./scripts/fnos-cli app install trim.alist --version 3.0.13 --source-id 265 --volume-id 2 --dry-run --yes
+./scripts/fnos-cli app install trim.alist --version 3.0.13 --source-id 265 --volume-id 2 --yes
+./scripts/fnos-cli app install trim.alist --version 3.0.13 --volume-id 2 --custom-parameters '[{"key":"port","value":8080}]' --api-scope '{"API.User.FileAccess":true}' --yes
+./scripts/fnos-cli app install trim.alist --version 3.0.13 --volume-id 2 --accept-license --cancel-on-failure --yes
+./scripts/fnos-cli app install-fpk ~/Downloads/demo.fpk --volume-id 2 --dry-run --yes
+./scripts/fnos-cli app install-fpk ~/Downloads/demo.fpk --volume-id 2 --yes
+./scripts/fnos-cli app update trim.alist --version 3.0.14 --volume-id 2 --dry-run --yes
+./scripts/fnos-cli app update trim.alist --version 3.0.14 --volume-id 2 --yes
+./scripts/fnos-cli app stop trim.alist --yes
+./scripts/fnos-cli app start trim.alist --yes
+./scripts/fnos-cli app uninstall trim.alist --yes
+```

package/skill/reference/baidu-netdisk.md

@@ -0,0 +1,221 @@
+# 百度网盘模块
+
+## 模块概述
+
+`baidu-netdisk` 通过 fnOS HTTP API proxy 访问 NAS 上已经安装的百度网盘应用。它覆盖百度账号授权状态、网盘空间、云端文件操作、百度分享链接保存、NAS 与网盘之间的传输任务，以及定时同步任务。
+
+fnOS OAuth session 必须包含 `trim.baidu_netdisk.all`。旧 session 缺少该权限时需重新执行
+`login`，refresh token 无法扩大原授权范围。
+
+目标 fnOS 的 OAuth gateway 还必须把 `/app-baidu-netdisk` 的 HTTP 路由登记到该 scope。
+授权页能勾选百度网盘权限不代表路由已经登记；路由未登记时请求会在到达应用前返回 HTTP 403。
+
+CLI 不实现百度 OAuth。百度账号未授权或授权失效时，必须由用户在 NAS 的百度网盘应用登录页完成授权，然后重新运行 `status`。
+
+## 模块约定
+
+- 先完成 fnOS 的 `fnos-cli login`，再调用本模块。
+- 百度网盘路径必须以一个 `/` 开头；根路径是 `/`。
+- NAS 写入或读取路径必须是具体 `/vol{n}/...` 路径，不能用聚合根或百度网盘路径代替。
+- 所有写命令都要求 `--yes`。只读命令不要求确认。
+- 后端响应成功条件是 HTTP 2xx 且 `code=0`；百度 XPan 响应成功条件是 HTTP 2xx 且 `errno=0`。
+- 网关刷新重试后仍为 HTTP 401，或响应为 `code=401`、`code=2000`、`errno=-6`，表示百度授权不可用，应回到 NAS 应用登录页处理。
+- HTTP 403 表示 fnOS gateway 拒绝了应用路由。先核对 session 是否含 `trim.baidu_netdisk.all`，再确认设备上的 gateway 版本是否已登记 `/app-baidu-netdisk` 路由；不要误判为百度账号退出。
+- `dlink` 是敏感临时下载 URL，默认输出会脱敏。
+
+## 命令索引
+
+| 命令 | 类型 | 用途 |
+| --- | --- | --- |
+| `baidu-netdisk status` | 读 | 检查应用账号、百度账号和设备权益状态 |
+| `baidu-netdisk quota` | 读 | 查看总空间、已用空间和免费空间 |
+| `baidu-netdisk ls [dir]` | 读 | 浏览目录 |
+| `baidu-netdisk search <keyword>` | 读 | 搜索文件 |
+| `baidu-netdisk info <fsid...>` | 读 | 获取文件元数据 |
+| `baidu-netdisk mkdir <path>` | 写 | 创建目录 |
+| `baidu-netdisk rm <path...>` | 写 | 删除文件或目录 |
+| `baidu-netdisk rename <path> <newName>` | 写 | 重命名 |
+| `baidu-netdisk move <path...> <destDir>` | 写 | 移动，最后一个参数是目标目录 |
+| `baidu-netdisk copy <path...> <destDir>` | 写 | 复制，最后一个参数是目标目录 |
+| `baidu-netdisk upload <targetPath> <localPath...>` | 写 | 从 NAS 上传到网盘 |
+| `baidu-netdisk download <targetPath> <fsid...>` | 写 | 从网盘下载到 NAS |
+| `baidu-netdisk share-save <shareUrl> <targetPath>` | 写 | 把百度分享链接内容保存到 NAS |
+| `baidu-netdisk task ...` | 读/写 | 查询和控制传输任务 |
+| `baidu-netdisk sync ...` | 读/写 | 查询和管理同步任务 |
+
+## 授权、空间和文件读取
+
+### `status`
+
+```bash
+fnos-cli baidu-netdisk status
+```
+
+返回数据包括：
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `authorized` | boolean | 三段授权状态请求均成功时为 `true` |
+| `authorizationPath` | string | NAS 应用授权入口路径 |
+| `appUser.uk` | number | 应用侧百度用户标识 |
+| `appUser.deviceId` | string | NAS 应用绑定的百度设备 ID |
+| `baiduUser.baidu_name` | string | 百度账号名 |
+| `baiduUser.netdisk_name` | string | 网盘显示名 |
+| `baiduUser.vip_type` | number | `0` 普通、`1` VIP、`2` SVIP |
+| `iot.is_iot_svip` | number | NAS 设备权益状态，`1` 有效、`0` 无效 |
+
+### `quota`
+
+```bash
+fnos-cli baidu-netdisk quota
+```
+
+响应常见字段：`total`、`used`、`free`，单位均为 byte；`expire` 表示近期容量到期状态。
+
+### `ls`
+
+```bash
+fnos-cli baidu-netdisk ls [dir] [--order name|size|time|ctime|path] [--ascending] [--page N] [--limit N]
+```
+
+| Option | Required | Default | Meaning |
+| --- | --- | --- | --- |
+| `dir` | no | `/` | 百度网盘目录 |
+| `--order` | no | `time` | 排序字段 |
+| `--ascending` | no | false | 升序；缺省为降序 |
+| `--page` | no | `1` | 页码，从 1 开始 |
+| `--limit` | no | `80` | 每页数量，范围 1 到 1000 |
+
+文件条目常见字段：`fs_id`、`path`、`server_filename`、`isdir`、`category`、`size`、`server_mtime`、`server_ctime`、`thumbs`。
+
+### `search`
+
+```bash
+fnos-cli baidu-netdisk search <keyword> [--dir /] [--category video|audio|image|document|application|other|seed] [--recursive] [--limit N]
+```
+
+响应的 `list[]` 使用与 `ls` 相同的文件字段；`has_more=1` 表示仍有后续结果。
+
+### `info`
+
+```bash
+fnos-cli baidu-netdisk info <fsid...> [--dlink]
+```
+
+`fsid` 必须是正整数。`--dlink` 请求临时下载地址，但 CLI 会对响应中的 `dlink` 值脱敏；该命令适合检查元数据，不适合导出裸下载链接。
+
+## 云端文件写操作
+
+```bash
+fnos-cli baidu-netdisk mkdir <path> --yes
+fnos-cli baidu-netdisk rm <path...> --yes
+fnos-cli baidu-netdisk rename <path> <newName> --yes
+fnos-cli baidu-netdisk move <path...> <destDir> [--ondup fail|newcopy|overwrite|skip] --yes
+fnos-cli baidu-netdisk copy <path...> <destDir> [--ondup fail|newcopy|overwrite|skip] --yes
+```
+
+| Field | Location | Meaning | Constraints |
+| --- | --- | --- | --- |
+| `path` | positional | 源文件或目录 | 绝对网盘路径，不允许 `.` / `..` 段 |
+| `newName` | positional | 新名称 | 单个名称，不能包含 `/` 或 `\\` |
+| `destDir` | final positional | 目标目录 | `move/copy` 的最后一个参数 |
+| `--ondup` | option | 重名策略 | `fail` 失败、`newcopy` 保留副本、`overwrite` 覆盖、`skip` 跳过 |
+
+文件管理响应可能包含 `taskid` 和逐项 `info[]`；即使顶层 `errno=0`，也应检查逐项 `info[].errno`。
+
+## NAS 与网盘传输
+
+### 创建任务
+
+```bash
+fnos-cli baidu-netdisk upload <targetPath> <localPath...> [--conflict fail|rename|overwrite] --yes
+fnos-cli baidu-netdisk download <targetPath> <fsid...> [--conflict fail|rename|overwrite] --yes
+```
+
+| Field | Command | Meaning | Constraints |
+| --- | --- | --- | --- |
+| `targetPath` | upload | 百度网盘目标目录 | `/` 开头的网盘路径 |
+| `localPath` | upload | NAS 源路径 | 一个或多个 `/vol{n}/...` 路径 |
+| `targetPath` | download | NAS 目标目录 | 具体 `/vol{n}/...` 路径 |
+| `fsid` | download | 百度文件 ID | 一个或多个正整数 |
+| `--conflict` | both | 冲突策略 | `fail=0`、`rename=1`、`overwrite=3` |
+
+`uploadToCloud` 成功响应按应用合约返回 `data: null`。CLI 会输出结构化的任务提交确认，
+包括 `accepted: true`、`status: "submitted"`、目标路径、NAS 源路径、冲突策略和后端消息，
+不会把裸 `null` 当作结果，也不会声称传输已经完成。要查看进度或失败原因，继续执行：
+
+```bash
+fnos-cli baidu-netdisk task list --transfer upload --state running
+fnos-cli baidu-netdisk task list --transfer upload --state completed
+fnos-cli baidu-netdisk task info <taskId> --state completed
+```
+
+`task list/info` 默认查询 `running`。这里的 `running` 是应用定义的“未完成任务组”，会包含排队、等待、进行中、暂停和失败任务，因此返回 `status=6` 不是过滤失效。`completed` 组只包含 `status=5` 的已完成任务。
+
+建议在上传大文件前先执行 `baidu-netdisk quota` 检查剩余空间。任务进入 `status=6` 且
+`failCode=42610` 时，表示百度网盘空间不足；这说明提交接口已经创建任务，但异步传输失败。
+先释放百度网盘空间或扩容，再重新提交，不要把它误判为 CLI、OAuth 或网关失败。
+
+### 保存百度分享链接
+
+```bash
+fnos-cli baidu-netdisk share-save '<shareUrlWithPassword>' /vol1/1000/downloads --all --yes
+fnos-cli baidu-netdisk share-save '<shareUrl>' /vol1/1000/downloads --password <code> --fsid <id> [--fsid <id>...] --yes
+```
+
+- `shareUrl` 可传百度分享 URL、22 位分享短码，也可粘贴带“提取码: xxxx”的整段文本；URL 中的 `?pwd=xxxx` 也会自动识别。显式 `--password` 优先。
+- 分享域名必须是 `pan.baidu.com` 或 `yun.baidu.com`；NAS 目标必须是具体 `/vol{n}/...` 目录。
+- `--all` 保存分享根目录中的全部条目；若根条目是目录，百度会递归转存。需要精确选择且已知分享 fsid 时，改为重复传 `--fsid`。两种选择模式不能同时使用。
+- 命令先把选中条目转存到百度网盘固定目录 `/我的资源`，轮询完成后再创建下载到 NAS 的任务；百度端重名保留副本，NAS 端重名自动改名。
+- 命令最多等待百度转存 30 分钟。成功只表示 NAS 下载任务已创建，之后用 `baidu-netdisk task list --transfer download` 查看是否完成。
+- 分享短码、提取码、验证后的 `spwd`、分享 fsid 和中间任务 ID 都不会写入正常输出；Agent 也不得在回复或日志中回显这些值。
+
+### 查询任务
+
+```bash
+fnos-cli baidu-netdisk task list --transfer upload|download [--state running|completed] [--page N] [--page-size N] [--sort-by name|size|status] [--ascending]
+fnos-cli baidu-netdisk task info <taskId> [--state running|completed] [--page N] [--page-size N] [--sort-by name|size|status] [--ascending]
+```
+
+任务字段常见为：`id`、`name`、`targetPath`、`savePath`、`size`、`currentSize`、`speed`、`count`、`status`、`failCode`、`createdAt`、`updatedAt`。状态值：`0` 排队、`1` 等待、`3` 进行中、`4` 暂停、`5` 完成、`6` 失败。失败任务必须同时读取 `failCode`；其中 `42610` 表示百度网盘空间不足。
+
+### 控制任务
+
+```bash
+fnos-cli baidu-netdisk task pause <taskId...> --yes
+fnos-cli baidu-netdisk task resume <taskId...> --yes
+fnos-cli baidu-netdisk task cancel <taskId...> --yes
+fnos-cli baidu-netdisk task clear [--transfer upload|download] --yes
+```
+
+`clear` 只清理已完成任务。未指定 `--transfer` 时，CLI 依次清理上传和下载任务，并分别返回结果。
+
+## 同步任务
+
+```bash
+fnos-cli baidu-netdisk sync list
+fnos-cli baidu-netdisk sync create --direction download|upload --nas-path /vol1/... --netdisk-path /... [--interval 1m|10m|30m] [--conflict fail|rename|overwrite] [--immediate] [--keep-deleted] [--status running|paused] --yes
+fnos-cli baidu-netdisk sync update <id> --status running|paused --interval 1m|10m|30m --conflict fail|rename|overwrite [--immediate] --yes
+fnos-cli baidu-netdisk sync start|pause|delete <id> --yes
+```
+
+| Field | API value | Meaning |
+| --- | --- | --- |
+| `direction=download` | `1` | 百度网盘同步到 NAS |
+| `direction=upload` | `2` | NAS 同步到百度网盘 |
+| `interval=1m/10m/30m` | `1/2/3` | 同步执行频率 |
+| `status=running/paused` | `1/2` | 任务状态 |
+| `--immediate` | `allSyncRightNow=true` | 保存配置后立即全量同步 |
+| `--keep-deleted` | `dontFollowDeleted=true` | 来源删除后保留目的地文件，仅创建时设置 |
+
+同步任务常见响应字段：`id`、`direction`、`nasPath`、`netdiskPath`、`intervalType`、`dontFollowDeleted`、`allSyncRightNow`、`status`、`createdAt`、`updatedAt`。
+
+## 错误与停手条件
+
+- fnOS session 缺失或目标 NAS 不匹配：先重新执行 `fnos-cli login`，不要改用百度账号密码。
+- 百度授权错误：让用户在 NAS 百度网盘应用页面重新授权，然后重试只读 `status`。
+- HTTP 502 通常表示 NAS 上的百度网盘应用未安装、未启动或网关上游不可达；这是服务可用性问题，不应重试成空结果。先用 `app list` 确认应用，再检查应用状态。
+- HTTP 非 2xx、后端 `code != 0`、XPan `errno != 0`：保留响应中的 `msg`、`errmsg` 或 `show_msg`，不要只按退出码判断。
+- 路径校验失败：先确认它是百度网盘路径还是 NAS `/vol{n}/...` 路径，不要自动改写。
+- 分享保存失败：不要跳过验证、轮询或直接拼接下载链接；先根据 `errno` 区分链接失效、提取码错误、无权转存、选中文件无效或任务超限。
+- 写操作没有 `--yes`：停下请求确认，不要绕过门禁。