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

package/skill/reference/log.md

@@ -0,0 +1,224 @@
+# log 模块
+
+## 模块概述
+日志中心模块，涵盖日志查询、模块枚举、日志清除、导出和归档策略管理。
+
+## 模块约定
+- 操作日志、审计日志和日志服务控制应区分处理。
+- 当前 fnos-cli 实现的端点属于 `appcgi.eventlogger.common.*` 命名空间。
+
+## 端点索引
+- 已实现：
+  - `appcgi.eventlogger.common.list`
+  - `appcgi.eventlogger.common.moduleList`
+  - `appcgi.eventlogger.common.clear`
+  - `appcgi.eventlogger.common.export`
+  - `appcgi.eventlogger.common.archive`（设置归档策略）
+  - `appcgi.eventlogger.common.archive.get`（查询归档策略）
+  - `appcgi.eventlogger.debuglog.copyStart`（开始复制诊断日志）
+  - `appcgi.eventlogger.debuglog.copyStop`（取消复制诊断日志）
+- 未实现：
+  - `log.*`（旧版日志查询家族）
+
+## 端点详情
+
+### appcgi.eventlogger.common.list
+
+#### Endpoint
+`appcgi.eventlogger.common.list`
+
+#### Purpose
+按页查询日志中心记录，支持按级别和模块过滤。
+
+#### Trim CLI Mapping
+```
+fnos-cli logger list [--page <n>] [--page-size <n>] [--level <n>] [--module <n>] [--locale <locale>]
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.eventlogger.common.list` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `pageSize` | body | no | number | 每页条数 | 正整数 | `50` |
+| `page` | body | no | number | 页码 | 正整数 | `1` |
+| `level` | body | no | number | 日志级别过滤 | 数值型级别标识 | `3` |
+| `module` | body | no | number | 日志模块过滤 | 数值型模块标识 | `1` |
+| `locale` | body | no | string | 语言/区域 | 影响返回文本的语言 | `zh-CN` |
+
+#### Response
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+| `data` | no | object | 日志数据 | 包含日志条目和分页信息 | `{...}` |
+| `result` | no | string | Terminal marker | `succ`/`fail` | `succ` |
+| `errno` | no | number | 错误码 | 失败时出现 | `65534` |
+| `errmsg` | no | string | 错误描述 | 失败时出现 | `invalid filter` |
+
+### appcgi.eventlogger.common.moduleList
+
+#### Endpoint
+`appcgi.eventlogger.common.moduleList`
+
+#### Purpose
+列出可用的日志模块。
+
+#### Trim CLI Mapping
+```
+fnos-cli logger modules [--locale <locale>]
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.eventlogger.common.moduleList` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `locale` | body | no | string | 语言/区域 | 影响模块名称的语言 | `zh-CN` |
+
+### appcgi.eventlogger.common.clear
+
+#### Endpoint
+`appcgi.eventlogger.common.clear`
+
+#### Purpose
+按日志级别和模块清空日志记录。
+
+#### Trim CLI Mapping
+```
+fnos-cli logger clear --level <level> --module <module> --yes
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.eventlogger.common.clear` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `level` | body | yes | number | 日志级别 | 必填 | `3` |
+| `module` | body | yes | number | 日志模块 | 必填 | `1` |
+
+### appcgi.eventlogger.common.export
+
+#### Endpoint
+`appcgi.eventlogger.common.export`
+
+#### Purpose
+按日志级别和模块导出日志记录。
+
+#### Trim CLI Mapping
+```
+fnos-cli logger export --level <level> --module <module> [--locale <locale>] --yes
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.eventlogger.common.export` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `level` | body | yes | number | 日志级别 | 必填 | `3` |
+| `module` | body | yes | number | 日志模块 | 必填 | `1` |
+| `locale` | body | no | string | 语言/区域 | 影响导出内容的语言 | `zh-CN` |
+
+### appcgi.eventlogger.common.archive
+
+#### Endpoint
+`appcgi.eventlogger.common.archive`
+
+#### Purpose
+设置日志归档策略。
+
+#### Trim CLI Mapping
+```
+fnos-cli logger archive set --switch <0|1> --file-path <path> [--size-gt <n>] [--date-unit <n>] [--date-before <n>] --yes
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.eventlogger.common.archive` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `switch` | body | yes | number | 归档开关 | `0` 关闭，`1` 开启 | `1` |
+| `filePath` | body | yes | string | 归档文件路径 | 禁用归档时可传空字符串 | `/vol1/logs` |
+| `sizeGt` | body | no | number | 文件大小阈值 | 可选 | `1024` |
+| `dateUnit` | body | no | number | 日期单位 | `0` 天，`1` 周，`2` 月，`3` 年 | `2` |
+| `dateBefore` | body | no | number | 日期偏移量 | 可选 | `3` |
+
+#### Field Semantics
+- `switch` 为 `0` 时表示关闭归档，此时 `filePath` 可传空字符串。
+- `dateUnit` 定义时间粒度：`0` 天、`1` 周、`2` 月、`3` 年。
+
+### appcgi.eventlogger.common.archive.get
+
+#### Endpoint
+`appcgi.eventlogger.common.archive.get`
+
+#### Purpose
+查询当前日志归档配置。
+
+#### Trim CLI Mapping
+```
+fnos-cli logger archive query
+```
+
+#### Protocol Notes
+- 响应包含当前归档配置，CLI 直接打印后端返回的 payload。
+- 响应中 `validPath` 字段（如存在）表示路径有效性状态。
+
+### appcgi.eventlogger.debuglog.copyStart
+
+#### Endpoint
+`appcgi.eventlogger.debuglog.copyStart`
+
+#### Purpose
+复制后端诊断日志（Debug Log）到指定输出目录，并返回任务进度。
+
+#### Trim CLI Mapping
+```
+fnos-cli logger debuglog copy-start --output-dir <path> [--srv-type <0|1|2>]... --yes
+fnos-cli diagnostic-log export --output-dir <path> [--srv-type <0|1|2>]... --yes
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.eventlogger.debuglog.copyStart` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `outputDir` | body | yes | string | 输出目录 | CLI 要求已挂载存储空间或外挂盘路径，格式如 `/vol1/<dir>` 或 `/vol00/<mount>/<dir>`；不要使用系统目录如 `/tmp`、`/var/tmp`、`/home/...` | `/vol00/RemovableDisk/debug-log` |
+| `srvType` | body | no | number[] | 复制类别 | `0` 系统，`1` 内置应用，`2` 内置服务；未传时后端按全部类别处理。CLI 支持重复传入或逗号分隔，并按顺序去重。 | `[0,1,2]` |
+
+#### Response
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+| `taskId` | no | string | 复制任务 ID | doing/success 进度帧的 `data` 中返回 | `ftask_1` |
+| `fileNumTotal` | no | number | 需要复制的文件总数 | 进度帧返回 | `51` |
+| `fileNumDone` | no | number | 已复制文件数 | 进度帧返回 | `2` |
+
+#### Protocol Notes
+- 后端可能先返回 `result:"doing"` 进度帧，再返回终态帧。CLI 会优先展示带 `taskId` 的进度 payload，方便后续执行 `diagnostic-log stop`。
+- `outputDir` 必须预先存在于设备侧已挂载的存储空间或外挂盘下。普通存储常见路径是 `/volN/<uid>/...`；外挂盘常见路径是 `/vol00/<mount-name>/...`。
+
+#### Errors
+- 常见错误包括缺少 `outputDir`、目录不存在、创建目录失败、目录不可写、磁盘空间不足、重复任务、任务不存在等。
+
+### appcgi.eventlogger.debuglog.copyStop
+
+#### Endpoint
+`appcgi.eventlogger.debuglog.copyStop`
+
+#### Purpose
+取消正在进行的诊断日志复制任务。
+
+#### Trim CLI Mapping
+```
+fnos-cli logger debuglog copy-stop --task-id <taskId> --yes
+fnos-cli diagnostic-log stop --task-id <taskId> --yes
+```
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value | `appcgi.eventlogger.debuglog.copyStop` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+| `taskId` | body | yes | string | 复制任务 ID | CLI 要求非空且不包含空白字符 | `ftask_1` |
+
+## 注意事项
+- 旧版 `log.*` 家族端点和当前 `appcgi.eventlogger.common.*` 端点可能在不同固件版本上共存。
+- `logger debuglog copy-start` / `diagnostic-log export` 的 `outputDir` 需要选择已挂载存储空间或外挂盘路径；系统盘路径不是有效诊断日志导出目标。

package/skill/reference/network.md

@@ -0,0 +1,41 @@
+# network 模块
+
+## 模块概述
+
+网络模块用于管理设备网络相关服务开关。当前 CLI 覆盖 SSH 服务开关。
+
+## 端点索引
+
+- 已实现：
+  - `appcgi.network.ssh.switch`（开启或关闭 SSH 服务）
+
+## appcgi.network.ssh.switch
+
+### Endpoint
+
+`appcgi.network.ssh.switch`
+
+### Purpose
+
+开启或关闭设备 SSH 服务。
+
+### Trim CLI Mapping
+
+```bash
+fnos-cli network ssh switch --enable [--yes]
+fnos-cli network ssh switch --disable [--yes]
+```
+
+### Request
+
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | 固定值 | `appcgi.network.ssh.switch` |
+| `reqid` | body | yes | string | Request correlation ID | 每次请求生成 | `69ba...` |
+| `enable` | body | yes | boolean | 是否开启 SSH | `true` 开启，`false` 关闭 | `true` |
+
+### Notes
+
+- `--enable` 与 `--disable` 必须二选一。
+- 开启 SSH 是安全敏感操作，默认需要确认；用户明确授权后才使用 `--yes`。
+- 命令需要已登录 session，并通过认证链执行。

package/skill/reference/oauth.md

@@ -0,0 +1,51 @@
+# OAuth 参考
+
+## 固定参数
+
+- `client_id`: `YJNMPJUGA9`
+- `scope`: `trim.user.all trim.file.read trim.file.write trim.download.all trim.appcenter.all trim.photo.all trim.system.all trim.log.all trim.storage.all trim.docker.all`；产品专属 scope 见对应 reference
+- `code_challenge_method`: `S256`
+- device name/model: `trim-cli` / `CLI`
+- 授权 code 有效期：5 分钟
+
+## 登录
+
+```bash
+fnos-cli --profile home --host <host> --port <port> login
+```
+
+生产环境只使用这一条交互式流程：CLI 输出 `/signin` 授权链接并保持运行；用户自行在浏览器
+输入账号密码、确认授权、复制页面显示的一次性 code，再粘贴到 CLI 的
+`Authorization code` 提示。CLI 随后完成 token 交换。
+
+Agent 不代填账号密码、不自动点击授权、不读取页面 code，也不把 code 放进命令参数。CLI 无法
+自动打开浏览器时可添加 `--no-open`，但用户授权和交互式输入步骤不变。
+
+授权 URL 包含 PKCE challenge、client、scope 和 device 参数，不包含 `redirect_uri`。pending
+verifier 按 profile 隔离，过期后必须重新运行完整的交互式 `login`。授权 code 只能交换一次。
+`trim.basic` 不属于当前可申请列表，CLI 不显式申请。旧的 `file photo` scope 或缺少当前模块
+所需 scope 的 session 不再兼容，必须重新登录；refresh token 不能用来扩展原授权范围。
+
+## Refresh
+
+```bash
+fnos-cli --profile home login --refresh
+```
+
+命令开始前 access token 在 60 秒内过期会自动 refresh。代理 `/ogh/ac/w` 或原生 HTTP
+`/ogh/ac/h/*` 返回 401 时，CLI 按 profile 加锁 refresh 并只重试一次；第二次仍 401 时停止。
+refresh 返回新 refresh token 时替换旧值，未返回时保留旧值。刷新前 CLI 会把当前 session 原值
+写回当前 profile，确认真实存储目标可写；预检失败时不会发送 refresh 请求，因此不会消耗可能轮换的 refresh token。
+`ask-file` 的存储选择只会询问一次，并沿用到本次刷新提交。多进程获得锁后会重新读取 session，
+已被其他进程刷新时直接使用新 token，不覆盖较新的 session。
+
+存储仍可能在请求发出后失效。若 refresh 成功但最终 session 写入失败，不要反复使用旧 refresh
+token；服务端可能已完成轮换，应重新执行交互式 OAuth 登录。
+
+## Session 与 logout
+
+session 保存 access/refresh token、过期时间、OAuth client/device/scope 和用户摘要。
+`logout` 清理当前 profile 的 session 和 pending 文件，不承诺远端撤销令牌。
+
+失败时重新执行交互式 OAuth 登录；不回退到 CLI 用户名密码、2FA 或旧 token 恢复流程。授权
+code、code verifier、access token 和 refresh token 不应出现在命令参数、输出、日志或错误信息中。

package/skill/reference/photos.md

@@ -0,0 +1,158 @@
+# Photos reference
+
+## Authentication
+
+Photos 使用当前 profile 的系统 access token，通过 `/ogh/ac/h/*uri` 调用原生 HTTP API。当前命令目标
+必须与该 profile 保存的 session 目标一致。没有有效 session 时先执行 OAuth `login`；Photos
+不需要额外的应用登录或独立签名。
+
+## Command index
+
+| Command | Output |
+| --- | --- |
+| `photos folders` | 已加入相册扫描的目录、扫描状态和照片/视频数量 |
+| `photos search <keyword>` | 条件搜索的匹配项、时间线和总数 |
+| `photos info <id>` | 文件、拍摄、位置、标签和缩略图字段 |
+| `photos preview <id>` | 指定尺寸的绝对预览地址 |
+| `photos request <method> <path>` | 未封装端点的原始 HTTP 与业务响应 |
+
+## Response rules
+
+命名命令会检查 HTTP 状态和业务信封；HTTP 非 2xx、`code != 0` 或缺失 `data` 都会失败。
+命名搜索和详情还会把相对的 `*Url` 字段转换为绝对地址。
+
+`photos request` 用于原始端点，不应用命名命令的业务信封检查，输出固定为：
+
+```json
+{
+  "httpStatus": 200,
+  "response": { "code": 0, "msg": "", "data": {} }
+}
+```
+
+Agent 必须同时确认 `httpStatus` 位于 `200..299` 且 `response.code == 0`。不能只根据 CLI
+退出码判断通用请求成功。
+
+## Watched folders
+
+```bash
+fnos-cli photos folders
+```
+
+请求 `GET /p/api/v1/photo/folder/list`，没有业务参数。输出 `list[]` 的主要字段：
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `folderId` | integer | Photos 扫描目录 ID |
+| `folderPath` | string | fnOS 目录路径 |
+| `photoCount` | integer | 当前索引中的照片数量 |
+| `videoCount` | integer | 当前索引中的视频数量 |
+| `status` | integer | `0` 扫描中，`1` 完成，`2` 目录异常，`4` 未知 |
+| `disable` | integer | 目录是否允许从扫描范围移除 |
+| `hasWriteAccess.hasWriteAccess` | boolean | 当前用户是否有写权限 |
+| `hasWriteAccess.quotaCurr` | integer | 当前已用配额 |
+| `hasWriteAccess.quotaMax` | integer | 最大配额 |
+| `isDefault` | boolean | 是否为默认扫描目录 |
+
+目录处于扫描中时数量仍可能变化；目录异常时不要把当前计数表述为最终值。这里统计的是
+Photos 索引范围，不等于文件系统中全部图片数量。
+
+## Conditional search
+
+```bash
+fnos-cli photos search IMG --limit 20
+fnos-cli photos search 北京 --filter file_type=photo
+fnos-cli photos search 北京 --exclude-filter not_geo=1
+```
+
+请求 `POST /p/api/v2/search/results`。请求字段：
+
+| Field | Required | Type | Meaning |
+| --- | --- | --- | --- |
+| `keyword` | yes | string | 条件搜索关键词；CLI 拒绝空字符串 |
+| `limit` | yes | integer | 返回样本上限，CLI 接受 `1..200`，默认 `20` |
+| `filters` | yes | array | 正向 `{filterName, filterValue}` 条件 |
+| `antiFilters` | no | array | 排除 `{filterName, filterValue}` 条件 |
+
+`--filter` 和 `--exclude-filter` 使用 `name=value`，可以重复。常见过滤名包括
+`file_type`、`is_collect`、`person`、`photo_tag` 和 `file_dir`。`file_type` 常见值包括
+`photo`、`video`、`live_photo`、`gif`、`raw`、`360`、`panorama` 和 `screenshot`；其他过滤值
+取决于设备上的 Photos 版本和索引内容。
+
+响应主要字段：
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `list[]` | array | 当前返回的照片/视频样本 |
+| `timeline[]` | array | 按 `year`、`month`、`day` 聚合的 `itemCount` |
+| `total` | integer | 服务端报告的全部匹配数量，不等于 `list` 长度 |
+| `list[].id` | integer | 详情和预览命令使用的照片 ID |
+| `list[].category` | string | `photo` 或 `video` |
+| `list[].fileName` | string | 文件名 |
+| `list[].filePath` | string | fnOS 文件路径 |
+| `list[].photoUUID` | string | 照片流地址使用的 UUID |
+| `list[].additional.thumbnail.*Url` | string | 已转换为绝对地址的各尺寸预览字段 |
+
+## Photo detail
+
+```bash
+fnos-cli photos info <photoId>
+```
+
+请求 `GET /p/api/v1/gallery/getOne?id=<photoId>`。除搜索条目字段外，详情常见字段包括
+`fileSize`、`width`、`height`、`description`、`photoDateTime`、`timeZoneOffset`、`make`、
+`model`、`fumber`、`exposureTime`、`isoSpeedRatings`、`focalLength`、`latitude`、
+`longitude`、`ownerId`、`ownerName`、`isCollect`、`isLive` 和标签。
+
+## Preview
+
+```bash
+fnos-cli photos preview <photoId> --size m
+fnos-cli photos preview <photoId> --size o --open
+```
+
+预览先读取 `gallery/getOne`，再从 `additional.thumbnail` 选择地址。尺寸支持 `xxs`、`xs`、
+`s`、`m` 和 `o`；`o` 是原图。视频优先返回 `videoUrl`，缺失时回落到 `mUrl`。
+
+输出字段包括 `id`、`fileName`、`category`、`size`、`previewUrl`、`originalUrl`、
+`videoUrl` 和 `requiresAuthenticatedBrowserSession`。地址是绝对 URL，但浏览器通常仍需有
+已登录 fnOS 的 cookie；不要把它描述为免登录公开链接。
+
+## AI semantic search
+
+先检查模型，再发起自然语言搜索：
+
+```bash
+fnos-cli photos request post /api/v1/magic-search/ready --yes
+fnos-cli photos request post /api/v1/magic-search/do \
+  --json '{"keyword":"海边日落","antiFilters":[]}' --yes
+```
+
+| Endpoint | Request | Response |
+| --- | --- | --- |
+| `POST /p/api/v1/magic-search/ready` | 无请求体 | `code == 0` 表示当前模型可用 |
+| `POST /p/api/v1/magic-search/do` | `keyword` 必填；`antiFilters` 可选 | `data.list[]` 为本次 AI 命中 |
+
+通用请求输出中的 AI 列表路径是 `response.data.list`。该接口没有稳定的 `total` 字段，
+因此 `list` 长度只能表述为本次返回条数，不能称为全库精确总数。要提供预览时，从 AI
+结果选择 `id`，再执行 `photos preview <id> --size m`；AI 原始响应中的相对 URL 不应直接
+当作可访问链接。
+
+已知业务码 `4044` 表示当前模型不支持当前语言，需要先切换模型。其他非零业务码也应
+原样报告并停止，不要回退到普通文件名搜索后仍声称是 AI 结果。
+
+## Generic request
+
+```bash
+fnos-cli photos request get /api/v1/server/sys_info
+fnos-cli photos request get /api/v1/gallery/getOne --query id=123
+fnos-cli photos request post /api/v2/search/results \
+  --json '{"filters":[],"keyword":"IMG","limit":5}' --yes
+```
+
+路径只能是 `/api/...` 或 `/p/api/...`，不能包含 origin、查询串或 fragment。查询参数使用
+可重复的 `--query key=value`；请求体使用 JSON object 或 array。非 GET 请求需要交互确认
+或显式传 `--yes`。
+
+典型统计、AI 搜索和抽样预览流程见
+[workflows/photos-routing.md](workflows/photos-routing.md)。

package/skill/reference/power.md

@@ -0,0 +1,34 @@
+# Power Reference
+
+电源模块用于重启或关闭 NAS。两条命令都会中断当前设备服务和 CLI 连接，执行前必须确认目标地址、当前账号权限和业务影响。
+
+## Commands
+
+| Command | Endpoint | Effect |
+| --- | --- | --- |
+| `fnos-cli power reboot --yes` | `power.reboot` | 请求重启 NAS |
+| `fnos-cli power poweroff --yes` | `power.poweroff` | 请求关闭 NAS |
+
+## Confirmation
+
+默认会弹出交互确认。自动化场景或已经确认目标设备时传 `--yes` 跳过提示。
+
+```
+fnos-cli --host <host> --port <port> power reboot --yes
+fnos-cli --host <host> --port <port> power poweroff --yes
+```
+
+## Session Requirements
+
+执行前需要已经登录并保存 session。CLI 会使用保存的 session 完成签名认证后发送电源请求。
+
+## Output
+
+命令成功发送并被后端接受后输出简短成功信息：
+
+```
+Reboot request accepted
+Poweroff request accepted
+```
+
+后端接受请求通常表示重启或关机已经被安排，不表示设备已经完成重启或已经完全断电。

package/skill/reference/resmon.md

@@ -0,0 +1,160 @@
+# resmon 模块
+
+## 模块概述
+资源监控模块，涵盖 CPU、内存、网络、GPU、磁盘、电池、系统风扇和进程/服务视图。
+
+## 模块约定
+- 区分聚合指标（`gen`）和分类指标（`cpu`、`mem` 等）。
+- 端点使用 `appcgi.resmon.*` 命名空间。
+
+## 端点索引
+- 已实现：
+  - `appcgi.resmon.cpu`
+  - `appcgi.resmon.mem`
+  - `appcgi.resmon.gen`（聚合指标）
+  - `appcgi.resmon.net`（网络）
+  - `appcgi.resmon.disk`（磁盘）
+  - `appcgi.resmon.gpu`（GPU）
+  - `appcgi.resmon.npu`（NPU）
+  - `appcgi.resmon.proc.info`（进程详情）
+  - `appcgi.resmon.proc.list`（进程列表）
+  - `appcgi.resmon.proc.srv`（服务列表）
+  - `appcgi.resmon.sysWarn`（系统告警）
+  - `appcgi.resmon.battery`（电池）
+  - `appcgi.resmon.sysFan`（系统风扇）
+  - `appcgi.resmon.alert.getSupportedBeepEvents`（支持的蜂鸣器事件）
+  - `appcgi.resmon.alert.getBeepEvents`（已配置蜂鸣器事件）
+  - `appcgi.resmon.alert.getBeepReasons`（蜂鸣器触发原因）
+  - `appcgi.resmon.alert.muteBeeper`（静音蜂鸣器）
+  - `appcgi.resmon.*` 泛化请求（通过 `monitor request`）
+- 未实现：
+  - 无独立命令的写操作端点；如需调用，使用 `monitor request` 并确认风险。
+
+## 端点详情
+
+### appcgi.resmon.cpu
+
+#### Endpoint
+`appcgi.resmon.cpu`
+
+#### Purpose
+返回 CPU 监控指标。
+
+#### Trim CLI Mapping
+```
+fnos-cli monitor cpu
+```
+
+CLI 行为：
+- 复用 session 恢复流程。
+- 将端点返回数据以 JSON 格式打印。
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value `appcgi.resmon.cpu` | `appcgi.resmon.cpu` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+
+#### Response
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+| `data` | no | object | CPU 指标数据 | CLI 直接打印此对象 | `{"usage":37,"cores":4}` |
+| `result` | no | string | Terminal marker | `succ`/`fail` | `succ` |
+| `errno` | no | number | 错误码 | 失败时出现 | `5001` |
+| `errmsg` | no | string | 错误描述 | 失败时出现 | `monitor backend unavailable` |
+
+#### Protocol Notes
+- 使用签名请求（当 session secret 可用时）。
+- 签名格式遵循 `_conventions.md` 中定义的规范。
+
+#### Field Semantics
+- 返回数据结构由后端定义，CLI 不做字段重映射。
+
+#### Errors
+- 后端错误通过统一格式化器输出到 stderr，包含 errno。
+- 命令以非零退出码退出。
+
+### appcgi.resmon.mem
+
+#### Endpoint
+`appcgi.resmon.mem`
+
+#### Purpose
+返回内存监控指标。
+
+#### Trim CLI Mapping
+```
+fnos-cli monitor memory
+```
+
+CLI 行为：
+- 复用 session 恢复流程。
+- 将端点返回数据以 JSON 格式打印。
+
+#### Request
+| Field | Location | Required | Type | Meaning | Constraints / Notes | Example |
+| --- | --- | --- | --- | --- | --- | --- |
+| `req` | body | yes | string | Endpoint selector | Fixed value `appcgi.resmon.mem` | `appcgi.resmon.mem` |
+| `reqid` | body | yes | string | Request correlation ID | Generated per request | `69ba...` |
+
+#### Response
+| Field | Always Present | Type | Meaning | Conditions / Notes | Example |
+| --- | --- | --- | --- | --- | --- |
+| `data` | no | object | 内存指标数据 | CLI 直接打印此对象 | `{"total":1024,"used":768}` |
+| `result` | no | string | Terminal marker | `succ`/`fail` | `succ` |
+| `errno` | no | number | 错误码 | 失败时出现 | `5001` |
+| `errmsg` | no | string | 错误描述 | 失败时出现 | `monitor backend unavailable` |
+
+#### Protocol Notes
+- 使用签名请求（当 session secret 可用时）。
+- 签名格式遵循 `_conventions.md` 中定义的规范。
+
+#### Field Semantics
+- 返回数据结构由后端定义，CLI 不做字段重映射。
+
+#### Errors
+- 后端错误通过统一格式化器输出到 stderr，包含 errno。
+- 命令以非零退出码退出。
+
+### 其他只读端点
+
+以下端点均复用已保存 session，执行签名请求，并打印响应 `data` 对象。
+
+| CLI 命令 | Endpoint | Request 参数 | 用途 |
+| --- | --- | --- | --- |
+| `fnos-cli monitor gen --item storeSpeed,netSpeed` | `appcgi.resmon.gen` | `item`: 仅支持 `storeSpeed`、`netSpeed`、`cpuBusy`、`memPercent`；可重复传 `--item` 或用逗号分隔 | 聚合指标查询 |
+| `fnos-cli monitor net` | `appcgi.resmon.net` | 无 | 网络指标 |
+| `fnos-cli monitor disk` | `appcgi.resmon.disk` | 无 | 磁盘指标 |
+| `fnos-cli monitor gpu` | `appcgi.resmon.gpu` | 无 | GPU 指标 |
+| `fnos-cli monitor npu` | `appcgi.resmon.npu` | 无 | NPU 指标 |
+| `fnos-cli monitor proc-info --pids 123,456` | `appcgi.resmon.proc.info` | `pids`: 正整数数组 | 指定进程详情 |
+| `fnos-cli monitor proc-list` | `appcgi.resmon.proc.list` | 无 | 进程列表；响应可能分批返回，CLI 会聚合完整列表 |
+| `fnos-cli monitor proc-srv` | `appcgi.resmon.proc.srv` | 无 | 服务视图 |
+| `fnos-cli monitor sys-warn` | `appcgi.resmon.sysWarn` | 无 | 系统告警 |
+| `fnos-cli monitor battery` | `appcgi.resmon.battery` | 无 | 电池状态 |
+| `fnos-cli monitor sys-fan` | `appcgi.resmon.sysFan` | 无 | 系统风扇 |
+| `fnos-cli monitor beep-supported` | `appcgi.resmon.alert.getSupportedBeepEvents` | 无 | 可支持蜂鸣器事件 |
+| `fnos-cli monitor beep-events` | `appcgi.resmon.alert.getBeepEvents` | 无 | 已配置蜂鸣器事件 |
+| `fnos-cli monitor beep-reasons` | `appcgi.resmon.alert.getBeepReasons` | 无 | 当前或历史触发原因 |
+
+参数约束：
+- `--item` 只支持 `storeSpeed`、`netSpeed`、`cpuBusy`、`memPercent`；空值会被忽略，非法指标会在发送请求前拒绝。
+- `--pids` 只接受正整数，重复 PID 会自动去重。
+- `beep-supported`、`beep-events`、`beep-reasons` 只适用于带蜂鸣器能力的 TRIM 机器。成功响应缺少 `data` 时，CLI 会检查机器类型与 `beep` 能力，仅在明确为非 TRIM 机器或 `beep: false` 时输出 `[]`；能力未知、`beep: true` 或其他 monitor 命令缺少 `data` 时仍报错。
+
+### 写操作和泛化请求
+
+| CLI 命令 | Endpoint | Request 参数 | 风险控制 |
+| --- | --- | --- | --- |
+| `fnos-cli monitor mute-beeper` | `appcgi.resmon.alert.muteBeeper` | 无 | 默认需要确认；可用 `--yes` 跳过 |
+| `fnos-cli monitor request appcgi.resmon.* --json '<object>'` | 用户指定的 `appcgi.resmon.*` 端点 | JSON 对象，不能包含 `req` 或 `reqid` | 默认需要确认；可用 `--yes` 跳过 |
+
+泛化请求约束：
+- endpoint 必须以 `appcgi.resmon.` 开头。
+- `--json` 必须是 JSON object。
+- `req` 和 `reqid` 由 CLI 生成，用户 JSON 中禁止提供这两个字段。
+- `monitor request` 是泛化入口，不区分读写端点，默认统一要求确认。
+
+## 注意事项
+- 读取型命令不会修改设备状态。
+- 写操作或泛化 request 在自动化场景中使用 `--yes` 前，应先明确 endpoint 语义和 JSON 内容。