# 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-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ArkTS LSP for OpenCode

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

## 工作原理

```
OpenCode
  │
  ├─ arkts-sync-plugin (插件，OpenCode 启动时加载一次)
  │   ├─ 检测 HarmonyOS 项目
  │   ├─ hvigor --sync（仅一次）
  │   └─ 启动持久化代理
  │
  └─ lsp-wrapper.js (每次打开 .ets 调用)
      ├─ 优先连接已有代理（bridge mode）
      │   └─ 插件已运行 → 直连，无需同步
      └─ 无代理时 fallback（首次或插件未装）
          ├─ hvigor --sync
          └─ 起新代理

index.js (中间层代理)
  ├─ 多客户端支持（UDS 命名管道）
  ├─ ace-server 生命周期管理
  ├─ 心跳检测/自动清理
  └─ 文件变更监听

ace-server（DevEco Studio ArkTS LSP 引擎）
  ├─ textDocument/didOpen → publishDiagnostics
  ├─ textDocument/completion
  ├─ textDocument/hover
  └─ aceProject/* (ArkTS 扩展方法)
```

## 架构优势

| 场景 | 传统方式 | 本方案 |
|------|---------|--------|
| 每次打开 .ets | 跑 hvigor sync（数分钟） | 桥接到已有代理（毫秒级） |
| 多文件编辑 | 每个文件起新进程 | 共享同一个代理 |
| ace-server 冷启动 | 每次都要等初始化 | 插件提前预热 |

## 前置条件

- **DevEco Studio** 已安装（ace-server 随 IDE 分发）
- **Node.js** >= 18
- **OpenCode** >= 1.0.132
- （可选）**oh-my-openagent** >= 4.2.0（若使用 OMO）

## 快速开始

### 方式一：简单配置（不装插件）

编辑 `~/.config/opencode/opencode.json`：

```json
{
  "lsp": {
    "arkts": {
      "command": ["node", "<arkts-lsp-path>/lsp-wrapper.js", "--stdio"],
      "extensions": [".ets", ".d.ets"],
      "env": {
        "DEVECO_HOME": "D:\\Application\\Huawei\\DevEco Studio",
        "ARKTS_LSP_HOME": "<arkts-lsp-path>"
      }
    }
  }
}
```

首次打开 `.ets` 文件时运行 hvigor sync，后续每次连接都会重新 sync。

### 方式二：推荐——安装插件（持久化代理 + 预热）

插件在 OpenCode 启动时加载一次，自动完成同步、启动代理、预热 ace-server。后续 LSP 连接毫秒级响应。

#### 1. 配置 LSP（opencode.json）

```json
{
  "lsp": {
    "arkts": {
      "command": ["node", "<arkts-lsp-path>/lsp-wrapper.js", "--stdio"],
      "extensions": [".ets", ".d.ets"],
      "env": {
        "DEVECO_HOME": "D:\\Application\\Huawei\\DevEco Studio",
        "ARKTS_LSP_HOME": "<arkts-lsp-path>"
      }
    }
  }
}
```

#### 2. 安装插件

将 `arkts-sync-plugin.js` 复制到 OpenCode 插件目录：

```bash
# Windows
copy arkts-sync-plugin.js %USERPROFILE%\.config\opencode\plugins\

# macOS / Linux
cp arkts-sync-plugin.js ~/.config/opencode/plugins/
```

#### 3. 注册插件

编辑 `~/.config/opencode/opencode.json`，在 `plugin` 数组中添加：

```json
{
  "plugin": [
    "oh-my-openagent@latest",
    "./plugins/arkts-sync-plugin.js"
  ]
}
```

#### 4. （可选）配合 oh-my-openagent v4.2.0+

如果使用 OMO v4.2.0+，需要额外配置 LSP 客户端文件，让 OMO 的 `lsp-tools-mcp` 能发现 arkts LSP：

在每个 Harmony 项目的 `.opencode/lsp.json`：

```json
{
  "lsp": {
    "arkts": {
      "command": ["node", "<arkts-lsp-path>/lsp-wrapper.js", "--stdio"],
      "extensions": [".ets", ".d.ets"]
    }
  }
}
```

### 环境变量

| 变量 | 必需 | 说明 |
|------|------|------|
| `DEVECO_HOME` | 推荐 | DevEco Studio 安装根目录。不设置时自动搜索各平台默认路径 |
| `ARKTS_LSP_HOME` | 推荐 | arkts-lsp-server 目录路径（存有 index.js、lsp-wrapper.js） |

## 架构详情

### 插件（arkts-sync-plugin.js）

OpenCode 启动时加载一次：

```
1. 检测当前目录是否为 HarmonyOS 项目（查找 build-profile.json5）
2. 如果否 → 跳过
3. 运行 hvigor --sync（等待完成，最多 10 分钟）
4. 启动 index.js 代理作为持久化守护进程
5. 通过 UDS 连接代理，发送 initialize 请求预热 ace-server
6. 监听 oh-package.json5 变更，自动重新 sync
```

插件函数立即返回（`return {}`），预热在后台异步进行。

### lsp-wrapper.js

每次打开 `.ets` 文件时被 OpenCode 调用：

```
1. 解析 DevEco Studio 路径、SDK、项目根目录
2. 尝试连接已有代理的命名管道（3s 超时）
   - 成功 → bridge mode：stdin/stdout ↔ 命名管道桥接
   - 失败 → fallback：
     a. 运行 hvigor --sync
     b. 启动新的 index.js 代理
```

### index.js（中间层代理）

minified bundle，提供：

- **多客户端支持**：通过 Windows 命名管道 / Unix socket 接受多个 LSP 客户端连接
- **ace-server 管理**：启动、初始化、心跳保活
- **请求路由**：在客户端和 ace-server 之间转发 LSP 消息
- **文件监听**：监听 `oh-package.json5` 和 `build-profile.json5` 变更
- **依赖映射**：监听 `.hvigor/dependencyMap/` 变化并增量加载

## 跨平台支持

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

## 目录结构

```
arkts-lsp-server/
├── package.json               ← npm 包定义 (bin: arkts-lsp)
├── lsp-wrapper.js             ← LSP 入口（桥接 + fallback sync）
├── index.js                   ← 中间层代理（minified bundle）
├── arkts-sync-plugin.js       ← OpenCode 插件（持久化代理 + 预热）
├── README.md                  ← 本文档
└── tests/
    └── test-e2e.js            ← E2E 测试套件
```

## 安装方式

### npx（零安装）

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

### 全局安装

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

### 本地安装

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

## 常见问题

### DevEco Studio not found

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

### ace-server 初始化超时

首次启动 ace-server 需要加载项目依赖和 SDK，约 7-30 秒。安装插件后自动预热，无需等待。

### LSP 诊断不返回结果

确认 hvigor sync 成功完成（`.hvigor/dependencyMap/` 目录存在）。

### 插件加载失败

检查 OpenCode 日志 `~/.local/share/opencode/log/arkts-plugin-*.log` 获取错误详情。