ArkTS LSP Proxy

将 DevEco Studio 内置的 ArkTS 语言服务器（ace-server）桥接出来，让 Claude Code 等支持 LSP 的工具获得 ArkTS 语言智能；同时提供 Codex MCP 适配器，让 Codex 通过工具调用使用 ArkTS hover、definition、symbols 和 diagnostics。

解决什么问题

AI 编码工具把 ArkTS 当成普通 TypeScript，导致：

使用不存在的 Web/Node.js API（如 document.getElementById）
不了解 ArkTS 声明式 UI 语法（@Component、@State、build() 等）
不遵守 ArkTS 静态类型约束（禁止 any、禁止动态属性访问等）

工作原理

Claude Code (LSP Client)
    │ stdio (JSON-RPC)
    ▼
arkts-lsp-proxy (Node.js 进程)
    │
    ├── 1. 发现 DevEco Studio（环境变量 / 自动搜索）
    ├── 2. 推导 SDK、ace-server、工具链路径
    ├── 3. 解析 build-profile.json5，构造 modules 参数
    ├── 4. 启动 ace-server，拦截 initialize 请求注入参数
    └── 5. 后台按需运行 hvigor --sync（刷新依赖映射）
         │
         ▼
    ace-server (DevEco 官方语言服务)
         ├── textDocument/diagnostics
         ├── textDocument/completion
         ├── textDocument/hover
         ├── textDocument/definition
         ├── textDocument/documentSymbol (proxy fallback)
         ├── workspace/symbol (proxy fallback)
         └── @Component/@State/@Prop 语义理解

Codex 侧不使用 Claude Code 的 .lsp.json 自动激活模型，而是通过 arkts-lsp-mcp 启动 MCP server：

Codex
    │ MCP stdio (JSON-RPC lines)
    ▼
arkts-lsp-mcp
    ├── 轻量工具：project_info / document_symbols / workspace_symbols
    └── LSP-backed 工具：hover / definition / references / signature_help / diagnostics
         │
         ▼
    arkts-lsp-proxy → ace-server

代理不实现 ArkTS 语义分析，只做启动适配、消息转发、参数注入和必要的 LSP 结果归一化。比如 DevEco ace-server 会把 hover 内容包成私有 JSON 字符串，代理会转换成标准 Markdown hover，方便 Claude Code 或 Codex 直接消费类型信息。DevEco ace-server 未提供的 symbol 能力由 proxy/MCP 做轻量 fallback。

当前支持的核心能力

textDocument/completion
textDocument/hover，包含类型信息和文档，已转换为标准 Markdown 内容
textDocument/definition
textDocument/references
textDocument/signatureHelp
textDocument/documentSymbol，基于打开文件文本解析 ArkTS/ArkUI 文件结构
workspace/symbol，基于项目根轻量扫描 .ets/.ts/.d.ets/.d.ts
diagnostics，来自 ace-server 的发布诊断
Codex MCP tools：arkts_project_info、arkts_document_symbols、arkts_workspace_symbols、arkts_hover、arkts_definition、arkts_references、arkts_signature_help、arkts_diagnostics

前置条件

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

安装

Claude Code 插件（推荐）

# 注册 marketplace
/plugin marketplace add HelloiOS2014/harmony_arkts_lsp_proxy

# 安装插件（首次使用时自动安装 arkts-lsp-proxy）
/plugin install arkts-lsp

Codex 项目级 MCP

Codex 不使用全局 marketplace 安装。为了避免所有项目都加载 ArkTS MCP 工具，请在需要启用 ArkTS 能力的 Codex 项目目录执行项目级安装脚本：

npx -y --package arkts-lsp-proxy@latest arkts-lsp-codex-install

脚本只负责写入当前项目的 Codex 配置，不会判断该目录是不是 HarmonyOS 项目，也不会扫描子目录。它会写入：

<project>/.codex/config.toml

写入内容等价于：

[mcp_servers.arkts-lsp]
command = "npx"
args = ["-y", "--package", "arkts-lsp-proxy@latest", "arkts-lsp-mcp"]

[mcp_servers.arkts-lsp.env]
ARKTS_LSP_SYNC = "auto"

这样 ArkTS MCP 只在该 Codex 项目中生效；其它项目没有这段项目级 .codex/config.toml，不会暴露 ArkTS tools，也不会占用工具上下文。真正的 HarmonyOS 项目识别由 MCP tools 在运行时根据文件路径、projectRoot 或 startPath 完成。

安装脚本会按当前项目状态处理：

场景	行为
没有 `.codex/config.toml`	创建 `.codex/` 目录和新的 `config.toml`
已有 `.codex/config.toml`，但没有 Codex MCP 配置	先备份原文件，再写入 `arkts-lsp` MCP 配置
已有 `.codex/config.toml`，且已有其它配置	先备份原文件，保留其它配置，只新增或替换 `[mcp_servers.arkts-lsp]` 相关配置

备份文件位于同一目录，形如 config.toml.bak-YYYYMMDDTHHMMSSZ。安装脚本只清理自己生成的时间戳备份，默认保留最近 3 份；其它手工备份文件不会被删除。如果只是想预览将要写入的内容，可以先执行：

npx -y --package arkts-lsp-proxy@latest arkts-lsp-codex-install --dry-run

注意：Codex 只会读取 trusted project 的项目级 .codex/config.toml。安装后请在该项目根目录启动 Codex，必要时重启当前 Codex 会话。

npm 全局安装（手动 CLI 使用）

npm install -g arkts-lsp-proxy

配置

环境变量

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

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

# Linux
export DEVECO_HOME=/opt/DevEco-Studio

不设置也可以，会自动搜索各平台默认安装路径。

使用

插件安装后，打开 .ets 文件时 LSP 自动激活。代理会优先启动 LSP 并响应请求；hvigor --sync 只作为后台 metadata refresh，不会阻塞 LSP 初始化。

也可以手动运行（支持直接给出项目路径）：

arkts-lsp-proxy --project-root /path/to/harmonyos/project

也可以手动启动 Codex MCP server：

arkts-lsp-mcp

当从非鸿蒙目录启动时，默认不会立即校验项目；会等到 LSP 初始化请求到来后根据 rootUri/workspaceFolders 自动定位鸿蒙项目路径。

Hvigor metadata sync

arkts-lsp-proxy 不会把 hvigor --sync 作为 LSP 启动前置条件。这个策略和 Claude Code 的其它 LSP 插件一致：插件负责启动 language server，工程 metadata / index refresh 属于 language server 内部增强流程。

环境变量：

# 默认：只有 metadata 缺失或过期时，后台运行 hvigor sync
export ARKTS_LSP_SYNC=auto

# 完全跳过 hvigor sync，启动最快
export ARKTS_LSP_SYNC=off

# 强制后台运行 hvigor sync，即使 metadata 看起来是新鲜的
export ARKTS_LSP_SYNC=force

# 后台 sync 超时，默认 15000
export ARKTS_LSP_SYNC_TIMEOUT_MS=15000

如果 sync 失败或超时，LSP 仍会继续运行。当前文件的 completion、hover、definition、references、diagnostics 应继续可用；跨模块、SDK、依赖相关结果可能降级，直到 metadata 刷新成功。

Metadata debug

排查 SDK / ArkUI / oh_modules 索引问题时，可以打开 metadata debug。默认关闭，避免在普通日志里暴露本地路径。

export ARKTS_LSP_METADATA_DEBUG=1

开启后，代理会在 stderr 输出注入给 ace-server 的关键工程信息，包括项目根、oh_modules、oh-package*.json5、hvigor dependencyMap、SDK 路径、SDK 关键子目录、module 配置、aceLoaderPath、sdkJsPath 和这些路径是否存在。

LSP trace

排查 Claude Code 插件真实链路时，可以打开协议路由 trace：

export ARKTS_LSP_TRACE=1

开启后，代理会输出客户端请求/通知的方法名，以及每个请求走的是 proxy-fallback、ace-notification 还是 ace-request-forward。启动时也会输出 arkts-lsp-proxy 实际运行版本，便于确认 Claude Code 会话是否已经升级到最新版本。对 workspace/symbol，trace 会额外输出 query 来源字段、query 长度和返回结果数。

平台支持

平台	默认搜索路径
macOS	`/Applications/DevEco-Studio.app`、`~/Applications/DevEco-Studio.app`
Windows	`D:\Application\Huawei\DevEco Studio`、`C:\Program Files\Huawei\DevEco Studio`
Linux	`/opt/DevEco-Studio`、`~/DevEco-Studio`

macOS 自动处理 .app/Contents 层，用户只需设置 .app 路径。

错误处理

场景	行为
DevEco Studio 未安装	stderr 输出安装指引，exit(1)
初始化请求未携带可定位路径或未检测到 `build-profile.json5`	代理返回 LSP 初始化错误，需调整 `rootUri`/`workspaceFolders`
hvigor sync 失败或超时	stderr 输出警告，LSP 继续以现有 metadata / degraded 模式运行
ace-server 启动失败	输出错误信息，exit(1)
ace-server 运行时崩溃	代理将中断当前会话并回传错误

开发

# 安装依赖
npm install

# 构建
npm run build

# 测试
npm test

# 本地链接
npm link

项目结构

src/
├── env.ts          DevEco Studio 环境发现
├── project.ts      HarmonyOS 项目解析 + findProjectRoot 向上搜索
├── hvigor.ts       hvigor metadata 状态、sync 策略与后台执行
├── ace-server.ts   ace-server 子进程生命周期管理（onExit 回调）
├── proxy.ts        LSP 消息代理，拦截 initialize 注入参数
├── arkts-client.ts Codex MCP 侧复用 proxy 的轻量 LSP client
├── mcp-tools.ts    ArkTS MCP tools 的实现
├── mcp.ts          MCP JSON-RPC 协议处理与 stdio server
├── mcp-server.ts   arkts-lsp-mcp 入口
├── codex-install.ts Codex 项目级 MCP 安装脚本
└── index.ts        arkts-lsp-proxy 入口
.claude-plugin/
└── marketplace.json    marketplace 清单 + lspServers 配置
plugins/
└── arkts-lsp/
    ├── .claude-plugin/
    │   └── plugin.json     Claude Code 插件清单
    ├── hooks/
    │   └── hooks.json      SessionStart 自动安装 hook
    ├── package.json        npm 依赖声明（供 hook 自动安装）
    ├── .lsp.json           LSP 服务器配置
    └── README.md           Claude Code 插件文档
test/
├── codex-install.test.ts
├── env.test.ts
├── project.test.ts
├── hvigor.test.ts
├── ace-server.test.ts
├── proxy.test.ts
├── mcp.test.ts
├── mcp-tools.test.ts
├── index.test.ts
└── fixtures/

技术栈

TypeScript
vscode-jsonrpc — LSP 消息解析与传输
json5 — 解析 build-profile.json5
MCP stdio JSON-RPC — Codex 工具入口（零新增运行时依赖）
Vitest — 测试

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
docs/superpowers		docs/superpowers
plugins/arkts-lsp		plugins/arkts-lsp
src		src
test		test
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ArkTS LSP Proxy

解决什么问题

工作原理

当前支持的核心能力

前置条件

安装

Claude Code 插件（推荐）

Codex 项目级 MCP

npm 全局安装（手动 CLI 使用）

配置

环境变量

使用

Hvigor metadata sync

Metadata debug

LSP trace

平台支持

错误处理

开发

项目结构

技术栈

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

ArkTS LSP Proxy

解决什么问题

工作原理

当前支持的核心能力

前置条件

安装

Claude Code 插件（推荐）

Codex 项目级 MCP

npm 全局安装（手动 CLI 使用）

配置

环境变量

使用

Hvigor metadata sync

Metadata debug

LSP trace

平台支持

错误处理

开发

项目结构

技术栈

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages