# arkts-lsp

**Repository Path**: Duke_Bit/arkts-lsp

## Basic Information

- **Project Name**: arkts-lsp
- **Description**: 适配Opencode的ArkTS的LSP，同步Deveco的版本，仅跟最新的校验
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-16
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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. 设置环境变量

```bash
# 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`）：

```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` 中直接配置：

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

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

### 全局安装

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

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

### 本地安装到项目

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

## 跨平台支持

| 平台 | 默认安装路径 | 二进制名 | 说明 |
|------|-------------|---------|------|
| **Windows** | `D:\Application\Huawei\DevEco Studio`<br>`C:\Program Files\Huawei\DevEco Studio`<br>`%LOCALAPPDATA%\Huawei\DevecoStudio` | `node.exe`<br>`ohpm.bat` | 扁平目录结构 |
| **macOS** | `/Applications/DevEco-Studio.app`<br>`~/Applications/DevEco-Studio.app` | `node`<br>`ohpm` | `.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 测试套件
```

## 测试

```bash
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 已成功运行过。