@litingwei621/test-deveco-cli-common 1.3.7 → 1.3.10-Test.1

package/README.md

@@ -161,6 +161,7 @@ devecocli init --path D:\work\ARKTS\NewData
 | `devecocli docs update`   | 更新 HarmonyOS 文档到最新兼容版本                   |
 | `devecocli init`          | 安装内置技能或配置 `MCP`                           |
 | `devecocli skills`        | 管理 HarmonyOS 技能市场中的技能                     |
+| `devecocli plugin`        | 管理白名单内的 AI 智能体插件（npm 包形式，装/卸/更新行为由插件定义） |
 | `devecocli signature generate` | 自动生成调试签名材料并配置到项目     |
 | `devecocli check compat`  | 扫描源代码在两个 `SDK` 版本之间的 `API` 变更         |
 
@@ -1395,8 +1396,8 @@ devecocli run --module <m1> [m2...] --device <device> --product <product> --buil
 | --ability    | 可选，待启动的 `Ability` ，默认：模块 `module.json5` 中的`mainElement`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | --uninstall  | 可选，安装前先卸载已有应用                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | --skip-build | 可选，跳过构建操作，直接安装应用 。\*\*说明：\*\*使用该参数时，需确保对应模块已有构建产物                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| --apply \<fileName\> | 可选，快速增量部署。仅重编改动文件并安装，比全量 `run` 快。`<fileName>` 为 `.hvigor/` 下的改动文件清单（每行一个相对工程根路径）。前提：DevEco Studio ≥6.1.1，且先跑过一次 `devecocli run` |
-| --hotreload [action] | 可选，使用热重载功能。使用热重载时，该命令需持续存活，以使热重载构建可以快速响应。当不需要时，执行 `devecocli run --hotreload stop` 去停止进程，释放资源 |
+| --apply \<fileName\> | 可选，快速增量部署。仅重编改动文件并安装，比全量 `run` 快。`<fileName>` 为 `.hvigor/` 下的改动文件清单（每行一个相对工程根路径）。前提：DevEco Studio ≥6.1.1，且先跑过一次 `devecocli run`。注意：不要与活跃的 `--hotreload` 会话混用（两者共用模块级 `buildConfig.json`），先 `devecocli run --hotreload stop` 停止会话 |
+| --hotreload [action] | 可选，使用热重载功能。使用热重载时，该命令需持续存活，以使热重载构建可以快速响应。当不需要时，执行 `devecocli run --hotreload stop` 去停止进程，释放资源。会话存活期间不要对该工程执行 `--apply` 或普通 `run`/`build`（会清掉会话依赖的 `buildConfig.json`），需要时先停止会话再重启 |
 | --hotreload-apply \<fileName\> | 可选，热重载（不重启应用即生效）。读取 `.hvigor/<fileName>` 改动清单，经编译安装使改动生效。前提：后台 `--hotreload` 进程在跑。范围：仅单个模块（`--module` 必填），且只支持 `.ets` 文件 |
 
 **示例：**
@@ -1423,12 +1424,19 @@ devecocli run --module entry --hotreload-apply changes.txt
 
 ### `log`
 
-查看`hilog`普通日志或崩溃日志
+查看`hilog`普通日志或崩溃日志，或对本地故障日志/采样栈文件做结构化分析
 
 **命令格式：**
 
 ```bash
+# 设备日志流
 devecocli log --device <device> --crash --level <level> --bundle-name <bundle-name> --keyword <keyword> --tail <num> --from <start> --to <end> --follow
+
+# 本地故障日志分析（cpp_crash / js_error / app_freeze）
+devecocli log --crash --path <file|dir> --format default|json|report|hilog
+
+# 本地采样栈分析（freeze-cpuinfo-ext 增强日志）
+devecocli log --stack --path <file> --format default|json|report --limit <num>
 ```
 
 **参数：**
@@ -1436,7 +1444,11 @@ devecocli log --device <device> --crash --level <level> --bundle-name <bundle-na
 | 参数名           | 说明                                                                                                                         |
 | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
 | --device      | 设备名称或设备序列号，单设备时可选，多设备时必选                                                                                                   |
-| --crash       | 可选，查看崩溃日志                                                                                                                  |
+| --crash       | 可选，查看崩溃日志；与`--path`搭配时改为分析本地故障日志文件或目录（自动识别日志类型，目录模式选取置信度/完整性/时间最优的候选）                                      |
+| --stack       | 可选，分析本地采样栈文件（`--path`必选，不可与`--crash`同时使用）                                                                             |
+| --path        | 可选，本地故障日志/采样栈的文件路径或目录路径；不可与设备日志流参数（`--device`、`--level`、`--bundle-name`、`--keyword`、`--tail`、`--from`、`--to`、`--follow`）同时使用 |
+| --format      | 可选，本地分析输出格式：`default`（来源信息+中文报告）、`json`（结构化结果）、`report`（纯中文报告）；`--crash`另支持`hilog`（提取日志中的 HiLog 流水区段）。默认`default` |
+| --limit       | 可选，`--stack`展示的热点数量上限，取值为正整数，默认`20`                                                                                  |
 | --level       | 可选，日志级别，取值包括`D`（ `Debug` ）、`I`（ `Info` ）、`W`（ `Warn` ）、`E`（ `Error` ）、`F`（ `Fatal` ）                                       |
 | --bundle-name | 可选，根据包名查看日志                                                                                                                |
 | --keyword     | 可选，根据关键词查看日志，关键词区分大小写                                                                                                      |
@@ -1453,6 +1465,9 @@ devecocli log --crash --bundle-name com.example.app
 devecocli log --device 127.0.0.1:5555 --level W --keyword Init
 devecocli log --tail 100 --from 5m --to 2m
 devecocli log --follow --bundle-name com.example.app
+devecocli log --crash --path ./faultlogs --format report
+devecocli log --crash --path cppcrash-com.example.app-1234-20260901100000 --format hilog
+devecocli log --stack --path sample_stacks.txt --limit 20 --format json
 ```
 
 ### `verify`
@@ -1672,6 +1687,45 @@ devecocli skills remove --skill skillname  # skillname需替换成实际的Skill
 devecocli skills remove --skill skillname --agent agentname  # skillname需替换成实际的Skill名称
 ```
 
+### `plugin`
+
+管理白名单内的 AI 智能体插件。插件以 npm 包形式分发，版本取白名单 `npmPackage` 坐标上可选 `@tag` 后缀指定的 dist-tag（如 `@scope/pkg@cli` 用 `cli` 标签；未写后缀默认 `latest`），CLI 负责白名单校验、包下载与完整性校验、契约加载和生命周期编排；安装、卸载、更新的具体行为完全由各插件的 `install` / `uninstall` / `update` hook 定义。
+
+**CLI 不保存任何安装状态**：`<数据目录>/plugins/store/<插件名>/<版本>/` 中的包缓存是唯一状态，`plugin list` 通过扫描这些目录判定"已下载"。install/update 每次都会重新执行 hook（幂等性由插件保证）；`plugin uninstall` 不会删除包缓存（`<数据目录>/plugins/store/<插件名>/`）与插件私有数据（`<数据目录>/plugins/data/<插件名>/`），需要清理时请手动删除。
+
+- `plugin list [-l|--long]`：以表格列出白名单插件及本地已下载版本（列 `Name / Version / Status`，每个版本一行、升序，无版本显示 `not installed`）；`--long` 追加 `NpmPackage` 与 `Desc` 列。
+- `plugin install <name> [--agent <a,b…>] [--project <path>] [-f|--force]`：下载最新包后，对"检测到的智能体 ∩ 插件支持的智能体"逐个执行 `install` hook；`--force` 先用本地最高旧版本执行 `uninstall` hook。目标全部失败时回滚删除本次新建的版本目录。显式 `--agent` + `--project` 时与 `init --project --agent` 一致——缺失的目标 skills 目录（含 `.<agent>` 根目录）会在 hook 前自动创建。
+- `plugin update <name> [--agent <a,b…>] [--project <path>]`：拉取最新版本并执行 `update` hook（携带 `from`/`to`，`from` 为下载前快照的最高版本；`from === to` 表示无本地版本或最新版已缓存，按修复/补装处理，不要求本地已有版本）；显式 `--agent` + `--project` 时与 install 一致，缺失的目标 skills 目录（含 `.<agent>` 根目录）会在 hook 前自动创建。
+- `plugin uninstall <name> [--agent <a,b…>] [--project <path>]`：以本地最高可加载版本执行 `uninstall` hook。
+
+白名单之外的插件名一律拒绝安装。汇总按目标计 `Success / Skipped / Failed`：不受插件支持的智能体记为 skipped（不执行 hook；显式 `--agent` 指定不支持项时直接报错，install/update/uninstall 报错一致）；`--project` 作用域未显式指定 `--agent` 时与 `init --project` 一致——仅入口为共享 `.agents/skills` 的智能体直通，其余智能体要求项目内已存在对应 `.<agent>` 目录，否则同样记为 skipped（`agent-project-root-missing`，不执行 hook，不会在项目内新建 `.<agent>` 目录）。任一目标失败时以非零状态退出。hook 单次执行上限默认 120 秒，可用环境变量 `DEVECO_CLI_PLUGIN_HOOK_TIMEOUT_MS` 调整。操作完成后需重启智能体以加载插件。
+
+**命令格式：**
+
+```bash
+devecocli plugin list --long
+devecocli plugin install <name> --agent <agents> --project <path> --force
+devecocli plugin update <name> --agent <agents> --project <path>
+devecocli plugin uninstall <name> --agent <agents> --project <path>
+```
+
+**参数：**
+
+| 参数名       | 说明                                                       |
+| --------- | -------------------------------------------------------- |
+| name      | 必选（install/update/uninstall），白名单内的插件名              |
+| --agent   | 可选，智能体名称，多个以英文逗号分隔；缺省时对检测到的全部智能体中受支持者执行 |
+| --project | 可选，工程根目录，切换到项目作用域；相对路径按当前目录解析          |
+| --force   | 可选（仅 install），先执行旧版本的 uninstall hook 再安装         |
+| --long    | 可选（仅 list），显示插件描述与 npm 包坐标                      |
+
+**示例：**
+
+```bash
+devecocli plugin list
+devecocli plugin install example-plugin --agent opencode --project ./my-app
+```
+
 ### `serve mcp`
 
 启动本地 `MCP` 服务。智能体配置 `MCP` 服务后，可通过 `MCP` 协议调用下方列出的代码分析与语言特性工具。不同智能体平台配置 `MCP` 服务的界面不一样，一个智能体平台的配置示例如下。