@deveco-test/deveco-cli-openharmony-arm64 0.1.2

package/README.md

@@ -0,0 +1,837 @@
+<div align="center">
+  <h1>DevEco CLI</h1>
+  <p>一个面向 HarmonyOS 应用开发的统一命令行入口。</p>
+  <p>
+    <a href="https://www.npmjs.com/package/@deveco-test/hmos-deveco-cli"><img src="https://img.shields.io/npm/v/@deveco/deveco-cli.svg" alt="NPM Version" /></a>
+    <a href="https://www.npmjs.com/package/@deveco-test/hmos-deveco-cli"><img src="https://img.shields.io/npm/dm/@deveco-test/hmos-deveco-cli.svg" alt="NPM Downloads" /></a>
+    <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D18-green.svg" alt="Node.js" /></a>
+    <img src="https://img.shields.io/badge/platform-HarmonyOS-blue.svg" alt="Platform" />
+    </a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" /></a>
+  </p>
+</div>
+
+`DevEco CLI` 将 `DevEco Studio` 工具链统一封装为一个 `CLI`，内置 `ohpm`、`hvigor`、`hdc`、`hilog`，同时集成 HarmonyOS 技能安装、项目脚手架、本地  HarmonyOS 文档检索和 `MCP` 服务。
+
+
+## 快速开始
+
+### 前置要求
+
+- 操作系统为 `HarmonyOS`
+- 安装 Command Line Tool 工具
+- 配置环境变量：
+  ```bash
+  export COMMAND_LINE_TOOL_PATH=path/to/deveco_tools
+  export PATH=$PATH:path/to/deveco_tools/node/bin
+  ```
+
+
+### 安装
+
+```bash
+npm install -g @deveco-test/hmos-deveco-cli
+```
+
+安装后可以通过以下命令更新到最新版本：
+
+```bash
+devecocli update
+```
+
+### 最短工作流
+
+```bash
+devecocli create --app-name MyApp
+cd MyApp
+devecocli run
+devecocli log --level E
+```
+
+### 文档检索
+
+```bash
+devecocli docs search List
+devecocli docs read harmonyos-guides/application-models/arkts-page-start-overview
+```
+
+更多命令和参数可通过 `devecocli --help` 或各子命令的 `--help` 查看。
+
+## AI Agent 集成
+
+`DevEco CLI` 支持通过命令行将自身技能添加到 `Agent` 中。下面以 `opencode` 为例展示最短流程：
+
+```bash
+# 1. 给 opencode 安装 deveco-cli 技能
+devecocli init --agent opencode
+
+# 2. 给 opencode 在当前 HarmonyOS 项目配置 MCP
+devecocli init --mcp --agent opencode --project ./MyApp
+
+# 3. 进入项目并启动 opencode
+cd MyApp
+opencode
+```
+
+如果 `Agent` 不在 `--agent` 参数取值范围内，可使用 `--path` 参数进行添加，参考如下命令：
+
+```bash
+devecocli init --path .\work\ARKTS\NewData
+```
+
+进入 `Agent` 后可以直接描述任务，例如：
+
+- `Build this project in release mode and run it on my device`
+- `Tail the last error logs from this app`
+- `Check for syntax errors in src/main/ets/pages/Index.ets`
+
+## 常用命令
+
+| 命令                        | 用途                                        |
+| ------------------------- | ----------------------------------------- |
+| `devecocli create`        | 创建新的 HarmonyOS 项目                         |
+| `devecocli build`         | 构建项目并产出 `.hap` / `.hsp` / `.har` / `.app` |
+| `devecocli check lint`    | 检查代码规范并输出实践建议与报告                      |
+| `devecocli run`           | 安装并运行应用                                   |
+| `devecocli device list`   | 查看当前连接设备                                  |
+| `devecocli log`           | 查看 `hilog` 或崩溃日志                          |
+| `devecocli docs search`   | 搜索本地 HarmonyOS 文档                         |
+| `devecocli init`          | 安装内置技能或配置 `MCP`                           |
+| `devecocli skills`        | 管理 HarmonyOS 技能市场中的技能                     |
+| `devecocli signature generate` | 自动生成调试签名材料并配置到项目     |
+
+## 命令集
+
+### `help`
+
+查看版本、帮助信息以及所有子命令
+
+**命令格式：**
+
+```bash
+devecocli help
+```
+
+```text
+# 返回结果
+Usage: devecocli [options] [command]
+
+HarmonyOS application development command line tool
+
+Options:
+  -V, --version          output the version number
+  -h, --help             display help for command
+
+Commands:
+  build [options]        Build the HarmonyOS project
+  run [options]          Build and run the project on a connected device
+  update                 Update deveco-cli to the latest version
+  device                 Manage connected devices
+  auth                   Authentication commands (login, logout, status, team)
+  ui                     Inspect and interact with UI on a connected device
+  skills                 Manage HarmonyOS skills
+  log [options]          Obtain device application logs
+  create [options]       Scaffold a new HarmonyOS application project
+  init [options]         Install the deveco-cli skill or configure the deveco-mcp server into AI agents
+  serve                  Host bundled auxiliary protocol servers
+  docs [options]         Search and read HarmonyOS documentation from local docs directory
+  check                  Run DevEco project checks
+  signature              Generate application signature
+  help [command]         display help for command
+```
+
+### `init`
+
+将`deveco-cli` `Skill` 或者 `MCP` 服务配置到智能体中
+
+**命令格式：**
+
+```bash
+devecocli init --agent <agents> --project <path> --path <path> --skill --mcp --force
+```
+
+**参数：**
+
+| 参数名         | 说明                                                                                        |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| --agent     | 可选，智能体名称，多个智能体名称以英文逗号分隔。缺省时配置到所有已检测到的智能体中                                                 |
+| --project   | 可选，指定工程路径，将`deveco-cli` `Skill` 或 `MCP` 服务安装到该工程项目中                                       |
+| --path      | 可选，指定 `deveco-cli` `Skill` 的配置路径。不可与 `--project` 、`--agent` 、 `--mcp` 同时使用                |
+| --skill     | 可选，安装 `deveco-cli` `Skill`。不可与 `--mcp` 同时使用。`--mcp` 与 `--skill` 都缺省时，执行 `--skill`         |
+| --mcp       | 可选，配置 `MCP` 服务，与 `--project` 一起使用表示配置工程级 `MCP` 服务，独立使用表示配置用户级 `MCP` 服务。不可与 `--skill` 同时使用 |
+| -f, --force | 可选，当目标位置已存在 `deveco-cli` `Skill` 或 `MCP` 服务时，覆盖重装                                         |
+
+**示例：**
+
+```bash
+# 配置Skill
+devecocli init -f   # 安装或更新deveco-cli Skill
+devecocli init --skill
+devecocli init --agent agentname    # agentname需替换为实际的智能体名称
+devecocli init --path /path/to/project -f
+
+# 配置MCP
+devecocli init --mcp
+devecocli init --mcp --agent agentname    # agentname需替换为实际的智能体名称   
+devecocli init --mcp --project /path/to/project -f
+```
+
+### `docs search`
+
+将关键词搜索版本说明、指南、API参考、最佳实践、`FAQ` 、变更预告等中的内容
+
+**命令格式：**
+
+```bash
+devecocli docs search <keywords...> --catalog <name> --format <fmt> --limit <n>
+```
+
+**参数：**
+
+| 参数名         | 说明                                                                                                                                                                                 |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| keywords... | 必选，搜索关键词，多个关键词用空格隔开                                                                                                                                                                |
+| --catalog   | 可选，文档类别，取值包含`harmonyos-releases`（版本说明）、 `harmonyos-guides`（指南）、`harmonyos-references`（API参考）、`best-practices`（最佳实践）、`harmonyos-faqs`（FAQ）、`harmonyos-roadmap`（变更预告）、`all`（所有分类，默认） |
+| --format    | 可选，控制输出格式，取值包括 `default` 、`json` ，默认为`default` ，输出结果包括文档ID、标题、文档的概括内容                                                                                                              |
+| --limit     | 可选，设置搜索结果返回条数，默认为20                                                                                                                                                                |
+
+**示例：**
+
+```bash
+devecocli docs search 沉浸光感
+devecocli docs search '@State' '@Prop' --catalog best-practices --limit 10
+devecocli docs search Row Column --format json
+```
+
+### `docs read`
+
+按文档ID查询文档的完整内容
+
+**命令格式：**
+
+```bash
+devecocli docs read <documentId> 
+```
+
+**参数：**
+
+| 参数名        | 说明      |
+| ---------- | ------- |
+| documentId | 必选，文档ID |
+
+**示例：**
+
+```bash
+devecocli docs read 开发指南/应用框架/UI_Design_Kit_UI设计套件/沉浸光感/ui-design-hds-component-material
+```
+
+### `docs catalog`
+
+查询文档分类和分类名称
+
+**命令格式：**
+
+```bash
+devecocli docs catalog --format <fmt> 
+```
+
+**参数：**
+
+| 参数名      | 说明                                        |
+| -------- | ----------------------------------------- |
+| --format | 可选，输出格式，`default` 或 `json` ，默认为 `default` |
+
+**示例：**
+
+```bash
+devecocli docs catalog 
+devecocli docs catalog --format json
+```
+
+### `create`
+
+创建 HarmonyOS 应用工程，仅支持创建工程模板中的 `Empty Ability` 模板
+
+**命令格式：**
+
+```bash
+devecocli create --app-name <name> --project-path <path> --bundle-name <bundle> --api-level <level> 
+```
+
+**参数：**
+
+| 参数名            | 说明                                                                |
+| -------------- | ----------------------------------------------------------------- |
+| --app-name     | 必选，应用名称                                                           |
+| --project-path | 可选，工程路径，默认为：`./<appname>`                                         |
+| --bundle-name  | 可选，包名，默认为：`com.example.<appname>` ，`appname` 自动转为小写               |
+| --api-level    | 可选，API级别，最小值为17，最大值从安装的 `Deveco Studio` 的 `HarmonyOS` `SDK` 中自动获取 |
+
+**示例：**
+
+```bash
+devecocli create --project-path ./MyApp --app-name MyApp
+devecocli create --project-path ./MyApp --app-name MyApp --bundle-name com.acme.myapp --api-level 23
+devecocli create --app-name MyApp
+```
+
+### `auth login`
+
+登录华为开发者账号，打开浏览器完成授权。
+
+**命令格式：**
+
+```bash
+devecocli auth login
+```
+
+**说明：**
+
+- 海外账户暂不支持
+
+### `auth logout`
+
+登出并清除本地存储的凭据
+
+**命令格式：**
+
+```bash
+devecocli auth logout
+```
+
+### `auth status`
+
+显示当前登录的用户
+
+**命令格式：**
+
+```bash
+devecocli auth status
+```
+
+### `auth team list`
+
+列出当前用户已加入的团队
+
+**命令格式：**
+
+```bash
+devecocli auth team list
+```
+
+**示例：**
+
+```bash
+devecocli auth team list
+```
+
+### `build`
+
+编译并打包 HarmonyOS 工程或工程中的模块
+
+**命令格式：**
+
+```bash
+devecocli build --product <product> --modules <modules> --build-mode <mode>
+```
+
+**参数：**
+
+| 参数名          | 说明                                                                                                      |
+| ------------ | ------------------------------------------------------------------------------------------------------- |
+| --product    | 可选，产品的名称，默认为 `default`                                                                                  |
+| --modules    | 可选，模块的名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个模块时，可缺省；当工程中存在多个模块，且仅存在一个 `entry` 类型的模块时，可缺省 |
+| --build-mode | 可选，构建模式，默认为 `debug`                                                                                     |
+
+**示例：**
+
+```bash
+devecocli build --build-mode release
+devecocli build --modules entry library
+devecocli build --modules library@phone
+devecocli build --product oversea --modules entry --build-mode release
+```
+
+**说明：**
+
+- 选定模块的依赖会被自动解析和构建
+- 执行`devecocli build --product <name>`命令后，产物为 `.app`
+- 执行`devecocli build --product <name> --modules <m1>`命令后，产物为 `.hap` / `.hsp` / `.har`
+
+### `build clean`
+
+清理 HarmonyOS 项目的构建产物
+
+**命令格式：**
+
+```bash
+devecocli build clean
+```
+
+### `check lint`
+
+检查代码规范并输出实践建议与报告。
+
+**命令格式：**
+
+```bash
+devecocli check lint [path]
+```
+
+**参数：**
+
+| 参数名                        | 说明                                                                  |
+| ---------------------------- | --------------------------------------------------------------------- |
+| `[path]`                     | 可选，待检查的文件或目录；默认使用 `build-profile.json5` 所在的项目根目录，否则使用当前目录 |
+| `--config-path <path>`       | Code Linter 配置文件路径，仅支持 `.json` 或 `.json5`；默认使用待检查项目根目录下的 `code-linter.json5`，显式指定时必须与待检查路径属于同一项目 |
+| `--fix`                      | 自动修复可修复的问题                                                  |
+| `--incremental`              | 仅检查 Git 未提交文件                                                 |
+| `--product <name>`           | `build-profile.json5` 中定义的 product，默认为 `default`              |
+| `--format <default\|json>`   | 完整报告格式；`default` 输出 Markdown，`json` 输出 JSON                |
+| `--output-path <path>`       | 完整报告文件或目录；目录形式会自动生成带时间戳的报告文件               |
+| `--limit <number>`           | 未指定 `--output-path` 时，限制终端显示的问题数量                      |
+
+### `device list`
+
+查询所有已连接的设备
+
+**命令格式：**
+
+```bash
+devecocli device list
+```
+
+### `device view`
+
+查询已连接的设备的详细信息，包括设备序列号、设备名称、设备类型、 `OS` 版本等
+
+**命令格式：**
+
+```bash
+devecocli device view --target <serialOrName>
+```
+
+**参数：**
+
+| 参数名         | 说明                                    |
+| ----------- | ------------------------------------- |
+| -t，--target | 可选，目标设备名称或序列号。多设备缺省时，会列出所有已连接设备序列号和名称 |
+
+**示例：**
+
+```bash
+devecocli device view
+devecocli device view --target 127.0.0.1:5555
+devecocli device view -t "My Device Name"
+```
+
+### `run`
+
+构建应用后，将应用安装到设备上，并启动执行
+
+**命令格式：**
+
+```bash
+devecocli run --module <module> --device <device> --product <product> --build-mode <mode> --ability <ability> --uninstall --skip-build --apply <txtFile>
+```
+
+**参数：**
+
+| 参数名          | 说明                                                                                                     |
+| ------------ | ------------------------------------------------------------------------------------------------------ |
+| --module     | 可选，模块名称。如需指定模块的 `target` 信息，使用 `module@target` 形式。当工程中只有一个可运行模块（ `entry` / `feature` / `shared` ）时，可缺省 |
+| --device     | 设备名称或设备序列号，单设备时可选，多设备时必选                                                                               |
+| --product    | 可选，产品的名称，默认为 `default`                                                                                 |
+| --build-mode | 可选，构建模式名称，默认为 `debug`                                                                                  |
+| --ability    | 可选，待启动的 `Ability` ，默认：模块 `module.json5` 中的`mainElement`                                                |
+| --uninstall  | 可选，安装前先卸载已有应用                                                                                          |
+| --skip-build | 可选，跳过构建操作，直接安装应用 。\*\*说明：\*\*使用该参数时，需确保对应模块已有构建产物                                                      |
+| --apply \<fileName\> | 可选，**快速增量部署**：仅重编改动文件 → signed hqf → `bm quickfix -a -f -o` 安装 → 重启，比全量 `run` 快。`<fileName>` 是工程 `.hvigor/` 目录下的**纯文件名**（调用方把清单写到此目录，文件名做安全校验防穿越）；内容为本轮改动的源文件路径清单（每行一个相对工程根路径；`#`/空行忽略；`.ets`/`.ts`/`.cpp`/资源文件；changeFileList 增量累积，只需列本轮改的，历史文件自动保留）。模块从清单路径自动识别（无需 `--module`）。**前提**：先 `devecocli run` 全量构建部署一次（生成 buildConfig.json 缓存）；**没生效排查**：检查 `<module>/build/config/buildConfig.json` 有无内容（空/无 = 没跑过 `devecocli run`）；**失败兜底**：直接 `devecocli run`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+
+**示例：**
+
+```bash
+devecocli run
+devecocli run --module entry --device 127.0.0.1:5555
+devecocli run --module library@phone --device 127.0.0.1:5555
+devecocli run --product oversea --module entry --ability EntryAbility
+devecocli run --build-mode release
+devecocli run --uninstall
+devecocli run --apply changes.txt
+```
+
+### `log`
+
+查看`hilog`普通日志或崩溃日志
+
+**命令格式：**
+
+```bash
+devecocli log --device <device> --crash --level <level> --bundle-name <bundle-name> --keyword <keyword> --tail <num> --from <start> --to <end> --follow
+```
+
+**参数：**
+
+| 参数名           | 说明                                                                                                                         |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| --device      | 设备名称或设备序列号，单设备时可选，多设备时必选                                                                                                   |
+| --crash       | 可选，查看崩溃日志                                                                                                                  |
+| --level       | 可选，日志级别，取值包括`D`（ `Debug` ）、`I`（ `Info` ）、`W`（ `Warn` ）、`E`（ `Error` ）、`F`（ `Fatal` ）                                       |
+| --bundle-name | 可选，根据包名查看日志                                                                                                                |
+| --keyword     | 可选，根据关键词查看日志，关键词区分大小写                                                                                                      |
+| --tail        | 可选，显示最新的N行日志，取值为正整数                                                                                                        |
+| --from        | 可选，起始时间，单位为`m`和`s`，`m`和`s`为小写，默认为`s`，`start`的取值需要大于等于`end`                                                                 |
+| --to          | 可选，结束时间，单位为`m`和`s`，`m`和`s`为小写，默认为`s` 。不可与--follow同时使用。**说明：** 如当前时间为05：00，`start`设置为30s，`end`设置为10s，则起始时间为04：30，结束时间为04：50 |
+| --follow      | 可选，实时输出日志。不可与--to同时使用                                                                                                      |
+
+**示例：**
+
+```bash
+devecocli log --level E
+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
+```
+
+### `skills list`
+
+查询可用的 `Skill`
+
+**命令格式：**
+
+```bash
+devecocli skills list --long
+```
+
+**参数：**
+
+| 参数名       | 说明                                              |
+| --------- | ----------------------------------------------- |
+| -l，--long | 可选，`Skill` 详情，包括描述和已安装的智能体列表。缺省时，仅显示 `Skill` 名称 |
+
+**示例：**
+
+```bash
+devecocli skills list
+devecocli skills list --long
+devecocli skills list -l
+```
+
+### `skills find`
+
+按关键词搜索 `Skill`
+
+**命令格式：**
+
+```bash
+devecocli skills find <keyword>
+```
+
+**参数：**
+
+| 参数名     | 说明       |
+| ------- | -------- |
+| keyword | 必选，搜索关键词 |
+
+**示例：**
+
+```bash
+devecocli skills find deveco
+```
+
+### `skills add`
+
+将 `Skill` 添加到智能体中
+
+**命令格式：**
+
+```bash
+devecocli skills add --all --agent <agents> --skill <skill-name> --project <path> --path <path> --force
+```
+
+**参数：**
+
+| 参数名        | 说明                                                        |
+| ---------- | --------------------------------------------------------- |
+| --all      | 可选，添加所有可用的 `Skill` ，与 `--skill` 二选一                       |
+| --agent    | 可选，智能体名称，多个智能体时以英文逗号分隔。缺省时，添加到已检测到的智能体中                   |
+| --skill    | 可选，待添加的 `Skill` 名称，与 `--all` 二选一                          |
+| --project  | 可选，指定项目路径，将 `Skill` 添加到该工程项目中                             |
+| --path     | 可选，指定路径，将 `Skill` 添加到该路径，不可与 `--project` 或 `--agent` 同时使用 |
+| -f，--force | 可选，当目标位置已有同名 `Skill` 时，覆盖重添加                              |
+
+**示例：**
+
+```bash
+devecocli skills add --all
+devecocli skills add --skill skillname --agent agentname --force # skillname需替换成实际的Skill名称
+devecocli skills add --skill skillname --project ./my-app  # skillname需替换成实际的Skill名称
+```
+
+### `skills remove`
+
+从智能体中删除已添加的 `Skill`
+
+**命令格式：**
+
+```bash
+devecocli skills remove --skill <skill-name> --agent <agents> --project <path> --path <path>
+```
+
+**参数：**
+
+| 参数名       | 说明                                                       |
+| --------- | -------------------------------------------------------- |
+| --skill   | 必选，待删除的 `Skill` 名称                                       |
+| --agent   | 可选，智能体名称，多个智能体时以英文逗号分隔。缺省时，删除到已检测到的智能体中的 `Skill`         |
+| --project | 可选，指定项目路径，删除该项目中的 `Skill`                                |
+| --path    | 可选，指定路径，删除该项目中的 `Skill`，不可与 `--project` 或 `--agent` 同时使用 |
+
+**示例：**
+
+```bash
+devecocli skills remove --skill skillname  # skillname需替换成实际的Skill名称
+devecocli skills remove --skill skillname --agent agentname  # skillname需替换成实际的Skill名称
+```
+
+### `serve mcp`
+
+启动本地 `MCP` 服务。智能体配置 `MCP` 服务后，可通过 `MCP` 协议调用下方列出的代码分析与语言特性工具。不同智能体平台配置 `MCP` 服务的界面不一样，一个智能体平台的配置示例如下。
+推荐通过 `devecocli init --mcp` 自动配置
+
+```bash
+{
+  "mcp": {
+    "deveco-mcp": {
+      "type": "local",
+      "command": [
+        "devecocli",
+        "serve",
+        "mcp"
+      ],
+      "environment":{
+        "PROJECT_PATH": "/path/to/project", // 工程路径
+        "NODE_MAX_OLD_SPACE_SIZE": "8192", // 可选，设置内部node进程最大的老生代内存大小，默认为8192
+      },
+      "enbale": true
+    }
+  }
+}
+```
+
+#### MCP 工具
+
+`deveco-mcp` 服务遵循 [MCP](https://modelcontextprotocol.io) 规范，通过 `tools/list` 暴露工具、由模型经 `tools/call` 调用。每个工具由**名称**、**描述**和 **JSON Schema 入参**定义；返回值为 `content` 文本数组，`isError: true` 表示执行错误。
+
+**工具总览：**
+
+| 工具名 | 用途 | 支持语言 |
+| --- | --- | --- |
+| `check` | 静态语法分析，返回结构化诊断信息 | ArkTS、C/C++ |
+| `hover` | 获取指定位置的悬浮信息（类型、文档） | ArkTS、C/C++ |
+| `definition` | 查找符号定义位置 | ArkTS、C/C++ |
+| `declaration` | 查找符号声明位置（ArkTS 中可能与定义不同） | ArkTS、C/C++ |
+| `references` | 查找符号在全工程中的所有引用 | ArkTS、C/C++ |
+| `implementation` | 查找符号的实现（如接口实现） | ArkTS、C/C++ |
+| `workspaceSymbol` | 按名称在全工程搜索符号 | ArkTS、C/C++ |
+| `documentSymbol` | 获取单文件的符号树（函数、类、变量及范围） | ArkTS、C/C++ |
+| `callHierarchy` | 查询函数调用关系（incoming=调用方，outgoing=被调用方） | ArkTS 双向、C/C++ 仅 incoming |
+| `restart` | 原地重启（重置状态 + 重新 sync/init），不杀进程、客户端不断开；ERROR 态可用 | ArkTS、C/C++（可按 target 单选） |
+
+**可用性说明：**
+
+- `check` 与 `restart` 始终注册；其余 7 个语言特性工具仅在 DevEco Studio 附带标准 LSP 服务入口（`standardIndex/index.js`）时注册，老版本将不暴露这些工具。
+- 所有语言特性工具需项目进入 `READY` 状态（`ohpm install` + `hvigor sync` + LSP 初始化完成）后才可用；未就绪时返回 `please retry in N seconds`，模型可稍后重试。`restart` 例外：它正是用于把 server 从 `ERROR` 态拉回，调用后返回"约 10 秒后重试"，后台异步重置并重新 sync/init。
+- C/C++ 工具需要工程包含 C++ 模块；无 C++ 代码时返回 `No C++ code`。
+- 支持的文件扩展名：ArkTS 为 `.ets`；C/C++ 为 `.c` `.cc` `.cpp` `.cxx` `.c++` `.h` `.hh` `.hpp` `.hxx` `.h++` `.ipp` `.ixx` `.inl` `.inc` `.tpp`。
+- 不属于当前工程的路径会被拒绝。
+
+**入参定义：**
+
+##### `check`
+
+对传入的源文件进行静态语法分析并返回诊断信息，支持 ArkTS 与 C/C++ 在同一次调用中混合传入。
+
+| 参数 | 类型 | 必选 | 说明 |
+| --- | --- | --- | --- |
+| `files` | string[] | 是 | 待检查的源文件路径列表，相对工程根目录，至少 1 个 |
+
+##### `hover` / `definition` / `declaration` / `references` / `implementation`
+
+位置类语言特性，共享同一入参结构。返回该位置符号的类型/文档信息、定义/声明位置、引用列表或实现列表。
+
+| 参数 | 类型 | 必选 | 说明 |
+| --- | --- | --- | --- |
+| `file` | string | 是 | 源文件路径，相对工程根目录，支持 `.ets` 与 C/C++ 扩展名 |
+| `line` | number | 是 | 行号，0-based |
+| `character` | number | 是 | 列号（字符偏移），0-based |
+
+##### `workspaceSymbol`
+
+按名称在全工程搜索符号，无需打开具体文件。
+
+| 参数 | 类型 | 必选 | 说明 |
+| --- | --- | --- | --- |
+| `query` | string | 是 | 符号名称或片段，非空 |
+
+##### `documentSymbol`
+
+获取单个文件的符号树，适合文件概览、结构化拆解和大文件切片。
+
+| 参数 | 类型 | 必选 | 说明 |
+| --- | --- | --- | --- |
+| `file` | string | 是 | 源文件路径，相对工程根目录，支持 `.ets` 与 C/C++ 扩展名 |
+
+##### `callHierarchy`
+
+查询某位置函数的调用关系。
+
+| 参数 | 类型 | 必选 | 说明 |
+| --- | --- | --- | --- |
+| `file` | string | 是 | 源文件路径，相对工程根目录，支持 `.ets` 与 C/C++ 扩展名 |
+| `line` | number | 是 | 行号，0-based |
+| `character` | number | 是 | 列号（字符偏移），0-based |
+| `direction` | enum | 是 | `incoming`=谁调用了该函数；`outgoing`=该函数调用了谁。ArkTS 支持双向，C/C++（clangd）仅 `incoming` |
+
+##### `restart`
+
+原地重启 MCP server：重置双侧状态并重新 sync/init（ohpm install + hvigor sync + compileNative + LSP 握手），不杀进程、客户端连接保持。用于 sync/init 失败导致 server 停在 `ERROR` 态时（免去退出并重开 agent）。fire-and-forget：立即返回"约 10 秒后重试"，重置在后台异步进行。**注意：`restart` 仅在修复根因后用于恢复，不能修复错误的工程配置。若重启后再次失败，说明是持久性配置问题（oh-package.json5/build-profile.json5 无效、ohpm install 或 hvigor sync 失败、SDK 版本不符等），不要循环调用 `restart`，应请用户排查并修复工程后再重试。**
+
+| 参数 | 类型 | 必选 | 说明 |
+| --- | --- | --- | --- |
+| `target` | enum | 否 | 重启哪一侧：`arkts`（ArkTS ace-server）、`cpp`（C++ clangd）、`all`（双侧，默认）。省略等同 `all` |
+
+### `serve lsp`
+
+启动本地 `LSP` 语言服务。智能体配置 `LSP` 服务后，可通过 `LSP` 协议获取代码补全、跳转定义、悬浮提示、引用查找、诊断等语言特性。当前支持 `ArkTS`和 `clangd`。
+
+```bash
+{
+  "lsp": {
+    "ArkTS": {
+      "command": [
+        "devecocli",
+        "serve",
+        "lsp",
+        "--arkts"
+      ],
+      "extensions": [
+        ".ets"
+      ]
+    },
+    "clangd": {
+      "command": [
+        "devecocli",
+        "serve",
+        "lsp",
+        "--cpp"
+      ],
+      "extensions": [
+        ".c",
+        ".cpp",
+        ".cc",
+        ".cxx",
+        ".h",
+        ".hpp",
+        ".hxx",
+        ".hh"
+      ]
+    }
+  }
+}
+```
+
+**参数：**
+
+| 参数名 | 说明 |
+| --- | --- |
+| `--arkts` | 与 `--cpp` 二选一，启动 ArkTS 语言服务（ace-server） |
+| `--cpp` | 与 `--arkts` 二选一，启动 C/C++ 语言服务（clangd） |
+| `--project-path <path>` | 可选，工程根路径，默认为当前工作目录 |
+| `--auto-detect` | 可选，当前目录向下查找工程根（检查当前目录自身及其子目录，最多 3 层子目录）；适用于 `--arkts` 和 `--cpp`；指定了 `--project-path` 则忽略 |
+
+### `signature generate`
+
+自动生成调试签名材料（包括p12密钥库、csr证书请求文件、p7b配置文件、cer证书文件），并将签名配置写入项目的 `build-profile.json5` 中。
+
+**命令格式：**
+
+```bash
+devecocli signature generate  --product <product> --team-id <team-id> --force --help
+``` 
+
+**参数：**
+
+| 参数名                   | 说明                                      |
+|-----------------------|-----------------------------------------|
+| --product \<product\> | 可选，指定product生成签名，默认为 `default`          |
+| --team-id \<team-id\> | 可选，指定生效的team-id,默认使用自身作为团队信息            |
+| --force               | 可选，强制覆盖已存在的证书文件 |
+| --help,--h            | 可选，查看帮助信息                               |
+
+**示例：**
+
+```bash
+# 自动生成签名并写入工程配置
+devecocli signature generate
+
+# 指定product
+devecocli signature generate --product default
+
+# 指定team-id
+devecocli signature generate --team-id 1222
+
+# 强制覆盖已存在的证书文件
+devecocli signature generate --force
+
+# 查询帮助信息
+devecocli signature generate --help
+```
+
+## 常见问题
+
+### 如何本地推包运行
+
+当没有真机设备连接时，可以通过无线调试实现自连，在本地推包运行应用：
+
+**步骤 1：开启无线调试**
+
+在设备上进入：系统 → 开发者选项 → 无线调试，开启无线调试功能。
+
+**步骤 2：配置 hdc 命令路径**
+
+将 hdc 工具路径添加到环境变量：
+
+```bash
+export PATH=$PATH:path/to/deveco_tools/sdk/default/openharmony/toolchains
+```
+
+**步骤 3：通过 hdc 命令自连**
+
+使用 hdc 命令连接设备的 IP 和端口：
+
+```bash
+hdc tconn IP:端口
+```
+
+连接成功后，即可使用 `devecocli run` 命令推包运行应用。
+
+
+## 开发
+
+```bash
+npm install
+npm run dev
+npm start -- <command>
+npm run lint
+npm run format
+npm run build
+```
+
+- 架构与目录说明见 [`AGENTS.md`](./AGENTS.md)
+- 如需参与维护，建议先阅读 `AGENTS.md` 中的约定与架构说明
+
+## 许可证
+
+[MIT](./LICENSE)