HarmonyOS-Support

🚀 为鸿蒙 ArkTS / ETS 开发提供极致性能的原生语言支持 — Rust 驱动的 LSP 服务器

这是什么？

一个VSCode插件，用于鸿蒙ArkTS开发提供极致性能的原生语言支持。

它用 Rust 从零实现了一个完整的 LSP（语言服务器协议）服务器，从解析到补全到诊断全部原生实现，仅在需要 TypeScript 类型检查时通过子进程桥接调用 ohos-typescript 引擎。

核心设计理念

理念	说明
Rust 主导	LSP 协议、解析、补全、诊断、格式化、重命名等全部用 Rust 实现
TS 辅助	仅类型检查委托给 `ohos-typescript`，通过 JSON-RPC 子进程通信
并发优先	DashMap 并发索引 + tokio 异步运行时 + rayon 数据并行
增量更新	文件级增量解析，只重新分析变更部分，大项目也能秒级响应
跨模块感知	自动解析 `oh-package.json5` 依赖图，支持 `[module].type.name` 引用

功能一览

LSP 协议方法（19 个 handler）

功能	LSP 方法	说明
🔍 自动补全	`textDocument/completion`	资源引用 `$r()`、跨模块 `[module].string.xxx`、符号补全、关键字补全、DSL 补全、代码片段
⚡ 诊断	`textDocument/publishDiagnostics`	资源引用错误、语法错误、ArkTS 规范检查（4 条规则）
🎯 跳转定义	`textDocument/definition`	资源定义跳转、符号跳转
💡 悬停提示	`textDocument/hover`	资源信息、类型信息、装饰器信息
📝 格式化	`textDocument/formatting`	ETS 代码格式化（缩进、装饰器、DSL 块、行尾空白）
🔄 重命名	`textDocument/rename`	符号重命名预览与执行
🏗️ 语义高亮	`textDocument/semanticTokens/full`	基于语义的语法高亮
🔗 查找引用	`textDocument/references`	查找符号的所有引用位置
✍️ 签名帮助	`textDocument/signatureHelp`	函数参数提示
📌 文档高亮	`textDocument/documentHighlight`	高亮当前符号的所有出现
🔭 工作区符号	`workspace/symbol`	全工作区符号搜索
📐 折叠范围	`textDocument/foldingRange`	代码折叠区域
🔗 文档链接	`textDocument/documentLink`	文档中的可点击链接
📊 Code Lens	`textDocument/codeLens`	代码内联信息
🎚️ 选择范围	`textDocument/selectionRange`	逐步扩大选择范围
📞 调用层次	`textDocument/prepareCallHierarchy`	函数调用关系
📋 文档符号	`textDocument/documentSymbol`	文件内符号大纲
🔧 代码动作	`textDocument/codeAction`	快速修复建议
🏷️ 重命名准备	`textDocument/prepareRename`	重命名前置检查

引擎能力

引擎	能力
资源索引	O(1) DashMap 查找，支持 `app.` / `sys.` / `[module].*` 三类引用
ETS 解析器	基于 oxc，支持装饰器（`@Entry`/`@Component`/`@State` 等）、DSL 语法块、资源引用
语义模型	符号表 + 作用域树，支持跨文件符号解析
增量解析	DashMap AST 缓存，仅重新解析变更文件
项目检测	自动识别 `oh-package.json5`、`build-profile.json5`，构建模块依赖图（拓扑排序）
ArkTS 规范	4 条规则：`@Entry` 必须 `@Component`、`@State` 必须 `@Component`、`build()` 必需、入口组件检查
格式化引擎	缩进对齐、装饰器格式化、DSL 块格式化、空行规整、行尾空白清理
类型桥接	JSON-RPC over stdio 子进程通信，支持 `ohos-typescript` 和标准 `typescript` 回退
文件监听	notify crate 实时监听 `.ets` / `.ts` / `.json5` / `.json` 文件变更

与其他方案对比

特性	本项目 (Rust LSP)	DevEco Studio	Volar + TS 插件
跨模块资源补全	✅ 原生支持	✅	❌
跨模块资源跳转	✅	✅	❌
启动速度	⚡ < 100ms	🐢 数秒	🐢 数秒
内存占用	🟢 ~50MB	🔴 ~1GB	🟡 ~300MB
诊断延迟	⚡ < 20ms	🟡 ~100ms	🐢 ~500ms
ArkTS 规范检查	✅ 4 条规则	✅	❌
格式化	✅ ETS 专用	✅	❌
增量解析	✅ 文件级	✅	✅
HMS + OHOS SDK	✅ 共存	✅	❌
开源	✅ MIT	❌	部分

快速开始

方式一：从源码构建（推荐）

# 1. 克隆仓库 / Clone
git clone https://github.com/chinokoyuki/HarmonyOS-Support.git
cd HarmonyOS-Support

# 2. 编译 LSP 服务器 / Build LSP server
cargo build -p lsp-server --release

# 3. 编译产物 / Output
# → target/release/arkts-lsp (Linux/macOS)
# → target/release/arkts-lsp.exe (Windows)

方式二：下载预编译二进制

前往 Releases 页面，下载对应平台的二进制文件。

方式三：Docker（计划中）

# 未来支持 / Planned
docker run -v /your/project:/workspace ghcr.io/chinokoyuki/arkts-lsp:latest

在 VSCode 中使用

# 1. 将编译好的 arkts-lsp 放到扩展目录 / Place binary
cp target/release/arkts-lsp vscode-extension/bin/

# 2. 编译 VSCode 扩展 / Build extension
cd vscode-extension
npm install && npm run compile

# 3. 打包安装 / Package & install
npx vsce package
code --install-extension arkts-language-support-1.0.0.vsix

或者开发模式：在 VSCode 中打开 vscode-extension/ 文件夹，按 F5 启动调试。

验证安装

打开任意 .ets 文件，在输出面板选择 "ArkTS Language Support"，应看到服务器启动日志。尝试输入 $r("app.string. 触发自动补全。

配置选项

在 VSCode 设置（settings.json）中配置：

{
  // LSP 服务器路径（留空使用内置） / Server binary path
  "arkts.server.path": "",

  // 诊断 / Diagnostics
  "arkts.diagnostics.enable": true,
  "arkts.diagnostics.enableConventionRules": true,  // ArkTS 规范检查

  // 格式化 / Formatting
  "arkts.format.enable": true,
  "arkts.format.indentSize": 2,
  "arkts.format.formatOnSave": false,

  // 补全 / Completion
  "arkts.completion.enableSnippets": true,
  "arkts.completion.enableDsl": true,

  // 类型检查 / Type checking
  "arkts.typeCheck.enable": true,
  "arkts.typeCheck.workerPath": ""  // 自定义 ts-worker.js 路径
}

架构设计

整体架构

┌─────────────────────────────────────────────────────────┐
│                    VSCode 薄扩展                          │
│              (extension.ts, ~150 行 TS)                   │
│              仅负责启动 Rust 进程、注册命令                  │
└────────────────────────┬────────────────────────────────┘
                         │ stdio (JSON-RPC)
┌────────────────────────▼────────────────────────────────┐
│                  Rust LSP 服务器                           │
│                  (tower-lsp 0.20)                         │
│                                                           │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│  │ 补全引擎  │ │ 诊断引擎  │ │ 跳转引擎  │ │ 悬停引擎  │   │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘   │
│       │            │            │            │           │
│  ┌────▼────────────▼────────────▼────────────▼─────┐    │
│  │              资源索引 (DashMap O(1))              │    │
│  └────────────────────┬───────────────────────────┘    │
│                       │                                  │
│  ┌──────────┐ ┌──────▼───┐ ┌──────────┐ ┌──────────┐  │
│  │ VFS      │ │ 语义模型  │ │ 文件监听  │ │ 项目检测  │  │
│  │ (DashMap)│ │ (符号表)  │ │ (notify) │ │ (oh-pkg) │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
└────────────────────────┬────────────────────────────────┘
                         │ JSON-RPC over stdio (子进程)
┌────────────────────────▼────────────────────────────────┐
│              ohos-typescript (类型检查)                    │
│              ts-worker.js (Node.js 工作进程)               │
└─────────────────────────────────────────────────────────┘

数据流

用户输入 → VSCode → LSP 请求 → Rust LSP 服务器
                                        │
                    ┌───────────────────┼───────────────────┐
                    ▼                   ▼                   ▼
              资源索引 (Rust)      语义模型 (Rust)      类型检查 (TS)
              O(1) DashMap         符号表+作用域        子进程 JSON-RPC
                    │                   │                   │
                    └───────────────────┼───────────────────┘
                                        ▼
                              LSP 响应 → VSCode → 用户

为什么是混合架构？

纯 Rust 方案不可行的核心原因：oxc 截至 2026.7 无生产级类型检查器，TypeScript 类型系统约 10 万行代码，ohos-typescript 还附加 ArkTS 定制，用 Rust 重写需 6-12 个月。

混合方案保留 ohos-typescript 做类型检查（完整复用），Rust 主导所有其他功能（LSP 协议、解析、补全、诊断、格式化等热路径），实现 90%+ 延迟降低。

性能

目标性能指标

操作	目标延迟	实现方式
资源查找	< 0.1ms	DashMap O(1) 哈希查找
解析单个 .ets 文件	< 5ms	oxc 解析器（Rust 最快 JS/TS parser）
自动补全	< 10ms	资源索引 + 模糊匹配 + 符号表
诊断	< 20ms	增量解析 + 规则引擎
跳转定义	< 5ms	资源索引直接定位
格式化	< 10ms	AST 遍历 + 规则应用
文件监听响应	< 1ms	notify 内核级事件

基准测试

# 运行基准测试 / Run benchmarks
cargo bench --workspace

基准测试覆盖：解析器性能、资源查找（DashMap vs HashMap）、正则匹配、JSON 序列化等关键路径。

实际表现

在中大型鸿蒙项目（50+ 模块、1000+ .ets 文件）上，相比纯 JS/TS 实现的 Volar 方案：

延迟降低 60-80%
内存占用降低 80%+
启动速度提升 10x+

项目结构

HarmonyOS-Support/
├── crates/                          # Rust workspace
│   ├── core/                        # 共享类型 + trait 定义
│   │   └── src/
│   │       ├── types.rs             # Span, Position, ResourceRef 等核心类型
│   │       ├── traits.rs            # LanguageEngine 等 trait
│   │       ├── backend.rs           # FrontendLanguage + NativeBackend (Cangjie/ohos-rs 预留)
│   │       └── error.rs             # 统一错误类型
│   │
│   ├── language-core/               # ETS 解析器 + 语义模型
│   │   └── src/
│   │       ├── parser/              # ETS 解析器
│   │       │   ├── mod.rs           # 解析器入口
│   │       │   ├── decorators.rs    # @Entry/@Component/@State 等装饰器
│   │       │   ├── dsl_syntax.rs    # DSL 语法块解析
│   │       │   ├── ets_extensions.rs # ETS 扩展语法
│   │       │   └── resource_ref.rs  # $r() 资源引用解析
│   │       ├── semantic/            # 语义模型
│   │       │   ├── builder.rs       # 语义模型构建器
│   │       │   ├── symbol_table.rs  # 符号表 (DashMap)
│   │       │   └── scope_tree.rs    # 作用域树
│   │       ├── typecheck/           # 类型检查桥接
│   │       ├── doc_manager.rs       # 文档管理器
│   │       ├── incremental.rs       # 增量解析器
│   │       ├── references.rs        # 引用查找
│   │       ├── rename.rs            # 重命名引擎
│   │       ├── call_hierarchy.rs    # 调用层次
│   │       └── workspace_symbols.rs # 工作区符号搜索
│   │
│   ├── resource-index/              # 资源索引引擎
│   │   └── src/
│   │       ├── index.rs             # DashMap 并发索引
│   │       ├── parser.rs            # 资源文件解析 (element/string/media...)
│   │       └── watcher.rs           # 资源文件监听
│   │
│   ├── completion-engine/           # 补全引擎
│   │   └── src/
│   │       ├── provider.rs          # 资源补全
│   │       ├── symbol_provider.rs   # 符号补全
│   │       ├── keyword_provider.rs  # 关键字补全
│   │       ├── dsl_provider.rs      # DSL 补全
│   │       ├── snippet_provider.rs  # 代码片段补全
│   │       ├── signature_help.rs    # 签名帮助
│   │       └── context.rs           # 补全上下文
│   │
│   ├── diagnostic-engine/           # 诊断引擎
│   │   └── src/
│   │       ├── provider.rs          # 诊断提供者
│   │       ├── rules.rs             # 诊断规则
│   │       ├── convention.rs        # ArkTS 规范规则 (4 条)
│   │       └── code_action.rs       # 代码动作 (快速修复)
│   │
│   ├── definition-engine/           # 跳转定义引擎
│   ├── hover-engine/                # 悬停引擎
│   ├── format-engine/               # 格式化引擎
│   │   └── src/
│   │       ├── ets_rules.rs         # ETS 格式化规则
│   │       └── ets_formatter.rs     # ETS 格式化器
│   │
│   ├── type-bridge/                 # 类型检查桥接
│   │   └── src/
│   │       ├── subprocess.rs        # JSON-RPC 子进程通信
│   │       ├── bridge.rs            # 桥接管理器
│   │       └── types.rs             # 类型请求/响应
│   │
│   ├── lsp-server/                  # LSP 服务器
│   │   └── src/
│   │       ├── main.rs              # 入口点 (stdio 传输)
│   │       ├── server.rs            # LanguageServer trait 实现
│   │       ├── vfs.rs               # 虚拟文件系统 (DashMap)
│   │       ├── file_watcher.rs      # 文件监听器
│   │       └── handlers/            # 19 个 LSP handler
│   │           ├── completion.rs
│   │           ├── definition.rs
│   │           ├── hover.rs
│   │           ├── diagnostic.rs
│   │           ├── format.rs
│   │           ├── semantic_tokens.rs
│   │           ├── references.rs
│   │           ├── signature_help.rs
│   │           ├── ... (共 19 个)
│   │
│   ├── project-detector/            # 项目检测
│   │   └── src/
│   │       ├── detector.rs          # 项目结构检测
│   │       ├── dep_graph.rs         # 模块依赖图 (拓扑排序)
│   │       └── module_resolver.rs   # 模块解析
│   │
│   ├── ast-traversal/               # AST 遍历 (过渡 crate)
│   └── napi/                        # napi-rs 桥接层
│
├── vscode-extension/                # VSCode 薄扩展
│   ├── extension.ts                 # 扩展入口 (~150 行)
│   ├── package.json                 # 扩展清单
│   └── language-configuration.json  # ETS 语言配置
│
├── .github/                         # CI/CD + 社区文件
│   ├── workflows/
│   │   ├── ci.yml                   # CI: fmt + clippy + test (三平台)
│   │   └── release.yml              # 发布: 构建 + 打包
│   └── ISSUE_TEMPLATE/              # Issue 模板
│
├── Cargo.toml                       # Workspace 根配置
├── CHANGELOG.md                     # 变更日志
├── CONTRIBUTING.md                  # 贡献指南
├── LICENSE                          # MIT 许可证
└── README.md                        # 本文件

Crate 依赖关系

                    ┌─────────┐
                    │  core   │ ← 共享类型
                    └────┬────┘
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
  ┌───────────────┐ ┌─────────┐ ┌──────────────┐
  │ language-core │ │ resource│ │ project      │
  │               │ │ -index  │ │ -detector    │
  └───────┬───────┘ └────┬────┘ └──────────────┘
          │                │
  ┌───────┴────────────────┴───────┐
  │    completion / diagnostic      │
  │    definition / hover / format  │
  └───────────────┬────────────────┘
                  │
          ┌───────┴───────┐
          │   lsp-server   │
          └───────┬───────┘
                  │
          ┌───────┴───────┐
          │  type-bridge   │ → ohos-typescript (子进程)
          └───────────────┘

技术栈

技术	版本	用途
Rust	stable	主体语言，所有核心引擎
oxc	0.30	JavaScript/TypeScript 解析器（Rust 实现，业界最快）
tower-lsp	0.20	LSP 协议实现
lsp-types	0.95	LSP 类型定义
tokio	1.x	异步运行时
DashMap	6.x	并发哈希表（无锁读，分段锁写）
rayon	1.x	数据并行（多核加速）
notify	6.x	跨平台文件系统监听
serde	1.x	序列化/反序列化
napi-rs	2.x	Rust ↔ Node.js 桥接
ohos-typescript	-	鸿蒙 TypeScript 类型检查（子进程调用）
criterion	0.5	性能基准测试

开发指南

环境要求

工具	最低版本
Rust	1.75+
Node.js	18+
Git	2.30+

常用命令

# 编译 / Build
cargo build --workspace

# 测试 / Test
cargo test --workspace          # 全量测试 (507 tests)
cargo test -p resource-index    # 单 crate 测试

# 代码检查 / Lint
cargo clippy --workspace -- -D warnings
cargo fmt --all -- --check

# 基准测试 / Benchmark
cargo bench --workspace

# 运行 LSP 服务器 / Run server
cargo run -p lsp-server

代码规范

格式化：cargo fmt --all
Lint：cargo clippy --workspace -- -D warnings（CI 强制）
注释：中英双语，格式 // 中文 / English
提交：Conventional Commits 格式

详细贡献流程请阅读 CONTRIBUTING.md。

路线图

✅ 已完成

Phase	内容	测试数
Phase 1	基础框架（13 crate workspace、ETS 解析器、LSP 骨架）	273
Phase 2	核心功能（资源索引、补全、诊断、跳转、悬停）	364
Phase 3	LSP 端到端（tower-lsp 完整实现、VFS、文件监听）	383
Phase 4	高级功能（语义模型、规范检查、重命名、增量解析、E2E）	438
Phase 5	类型桥接 + VSCode 扩展 + 文档 + 基准测试	459
Phase 6	LSP 协议补全（13 个新 handler：语义高亮、引用、签名等）	507

🚧 进行中 / 计划中

Phase	内容	预计工期
Phase 7	开发工具链（调试器、HDC 设备管理、Hilog、构建任务）	3-4 周
Phase 8	语言服务增强（全局引用查找、颜色选择器、权限声明）	2 周
Phase 9	打磨发布（性能优化、文档完善、v1.0 发布）	1 周

FAQ

Q: 能否同时引用 HMS 和 OHOS SDK？

可以。 HMS Core SDK 和 OHOS SDK 不互斥。OHOS 是基础系统能力（@ohos.*），HMS Core 是华为增值服务层，通过 agconnect-services.json + build-profile.json5 引入。project-detector 已支持检测两者。

Q: 支持哪些文件类型？

扩展名	说明
`.ets`	ETS 文件（主要支持目标）
`.ts`	TypeScript 文件
`.json5`	oh-package.json5 / build-profile.json5
`.json`	资源文件（resources/*.json）

Q: 如何贡献代码？

请阅读 CONTRIBUTING.md。简要流程：Fork → 创建分支 → 编码（通过 fmt + clippy + test）→ 提交 PR。

社区

🐛 发现 Bug？提交 Issue
💡 有想法？发起讨论
🤝 想贡献？阅读贡献指南
🔒 安全问题？查看安全策略
📜 行为准则？Code of Conduct
💖 赞助项目？查看 FUNDING

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github		.github
benches		benches
crates		crates
vscode-extension		vscode-extension
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md

Folders and files

Latest commit

History

Repository files navigation