ArkTS LSP for OpenCode

将 DevEco Studio 的 ArkTS 语言服务器（ace-server）集成到 OpenCode，为 .ets 文件提供 LSP 支持（诊断、补全、悬停等）。

工作原理

OpenCode (LSP 客户端)
    │  stdin/stdout
    ▼
lsp-wrapper.js              ← npx @ai-arkts/arkts-lsp
    │
    ├─ 1. 发现 DevEco Studio 路径（环境变量 / 自动搜索）
    ├─ 2. 推导 SDK、ace-server、工具链路径
    ├─ 3. 运行 hvigor --sync（生成依赖映射）
    └─ 4. 启动中间层代理 → ace-server
         │
         ▼
    index.js (代理)          ← 处理多客户端、心跳、消息排队
         │
         ▼
    ace-server               ← DevEco Studio 的 ArkTS LSP 引擎
         │
         ├── textDocument/didOpen → publishDiagnostics
         ├── textDocument/completion
         ├── textDocument/hover
         └── aceProject/* (ArkTS 扩展方法)

前置条件

• DevEco Studio 已安装（ace-server 随 IDE 分发）
• Node.js >= 18

快速开始

1. 设置环境变量

# Windows (cmd)
set DEVECO_HOME=D:\Application\Huawei\DevEco Studio

# Windows (PowerShell)
$env:DEVECO_HOME = "D:\Application\Huawei\DevEco Studio"

# macOS
export DEVECO_HOME=/Applications/DevEco-Studio.app

# Linux
export DEVECO_HOME=/opt/DevEco-Studio

不设置环境变量也可以——脚本会自动搜索各平台的默认安装路径。

2. 配置 OpenCode 全局配置

编辑 OpenCode 全局配置文件（~/.config/opencode.json 或项目下的 opencode.json）：

{
  "lsp": {
    "arkts": {
      "command": ["npx", "--yes", "@ai-arkts/arkts-lsp", "--stdio"],
      "extensions": [".ets", ".d.ets"],
      "env": {
        "DEVECO_HOME": "D:\\Application\\Huawei\\DevEco Studio"
      }
    }
  }
}

env 可选：不配置时自动搜索各平台默认安装路径（C:\Program Files\Huawei\DevEco Studio、/Applications/DevEco-Studio.app、/opt/DevEco-Studio 等）。

3. 重启 OpenCode

打开任意 .ets 文件，LSP 会自动激活。首次激活时会执行 hvigor --sync 初始化项目（可能需要几分钟）。

安装方式

推荐：npx（零安装，开箱即用）

无需安装，opencode.json 中直接配置：

"command": ["npx", "--yes", "@ai-arkts/arkts-lsp", "--stdio"]

首次使用时 npx 会自动从 npm 下载并缓存。

全局安装

npm install -g @ai-arkts/arkts-lsp

# 安装后直接用
arkts-lsp --stdio

本地安装到项目

npm install --save-dev @ai-arkts/arkts-lsp

跨平台支持

| 平台 | 默认安装路径 | 二进制名 | 说明 | |------|-------------|---------|------| | Windows | D:\Application\Huawei\DevEco StudioC:\Program Files\Huawei\DevEco Studio%LOCALAPPDATA%\Huawei\DevecoStudio | node.exeohpm.bat | 扁平目录结构 | | macOS | /Applications/DevEco-Studio.app~/Applications/DevEco-Studio.app | nodeohpm | .app 包，自动处理 Contents/ 层 | | **Linux** | /opt/DevEco-Studio<br>~/DevEco-Studio|node<br>ohpm` | 扁平目录结构 |

macOS .app 包说明

DevEco Studio 在 macOS 上是一个 .app bundle，实际内容在 Contents/ 下：

/Applications/DevEco-Studio.app
└── Contents/
    ├── plugins/openharmony/ace-server/out/index.js    ← LSP 引擎
    ├── sdk/default/sdk-pkg.json                       ← SDK
    └── tools/node/node                                 ← 构建用 Node
         tools/hvigor/bin/hvigorw.js                    ← hvigor 构建工具

脚本自动检测 .app 后缀并补全 Contents/。用户设置 DEVECO_HOME 时只需填 .app 路径，无需手动加 Contents。

初始化流程

1. 发现 DevEco Studio
   ↓
2. 检验 SDK 完整性（检查 sdk/default/sdk-pkg.json）
   ↓
3. 运行 hvigor --sync（10 分钟超时）
   使用 DevEco 自带的 Node.js + hvigorw.js
   生成 .hvigor/dependencyMap/dependencyMap.json5
   ↓
4. 启动中间层代理 (index.js)
   传入项目根目录、SDK 路径、扩展路径
   ↓
5. 代理启动 ace-server
   读取上一步生成的依赖映射
   完成 LSP 初始化

环境变量

| 变量 | 必需 | 说明 | |------|------|------| | DEVECO_HOME | 推荐 | DevEco Studio 安装根目录。不设置时自动搜索默认路径 |

目录结构

arkts-lsp-server/
├── package.json           ← npm 包定义（bin: arkts-lsp）
├── lsp-wrapper.js         ← OpenCode 入口（跨平台、hvigor sync）
├── index.js               ← 中间层代理（minified bundle，不动）
├── README.md              ← 本文档
└── tests/
    └── test-e2e.js        ← E2E 测试套件

测试

node arkts-lsp-server/tests/test-e2e.js

测试覆盖：

• 平台检测逻辑（macOS/Linux/Windows）
• DevEco Studio 路径自动搜索
• Contents/ 层处理（macOS .app bundle）
• 工具二进制名适配（node.exe vs node）
• hvigor sync 参数验证
• LSP 协议初始化验证
• 错误处理

常见问题

DevEco Studio not found

设置 DEVECO_HOME 环境变量指向 DevEco Studio 的安装目录。

hvigor sync 失败

确认项目是有效的 HarmonyOS 项目（有 build-profile.json5 和 hvigorfile.ts）。 hvigor sync 超时时间为 10 分钟，大型项目可能需要更长时间。

ace-server 不返回诊断

ace-server 需要 hvigor sync 生成的依赖映射。确保 sync 步骤成功完成。 如果项目已有 .hvigor/dependencyMap/ 目录，说明 sync 已成功运行过。