用于在鸿蒙设备上运行 Obsidian 笔记,管理本地 Vault、安装插件主题并同步笔记。项目构建 Electron 兼容层,以 ArkTS 适配器和 C++ 桥接接入系统能力,集成华为账号、云同步、多窗口与状态栏扩展。【此简介由AI生成】
Access rate limit exceeded. Please log in to continue.
ObsidianHM
Obsidian for HarmonyOS
中文 | English
Run the Obsidian note-taking experience you know and love on HarmonyOS devices — with multi-window support and comprehensive native system integration.
Table of Contents
- Overview
- Architecture
- Features
- Module Structure
- Adapter Layer
- Customization
- Build & Run
- Project Structure
- Dependencies
- Documentation
- License
- Acknowledgments
Overview
ObsidianHM is an unofficial port of the Obsidian note-taking application for the HarmonyOS (HongMeng) platform. It provides an Electron compatibility layer so the official release build of Obsidian (obsidian.asar) runs directly on the HarmonyOS native runtime.
At its core, ObsidianHM provides the Electron API using HarmonyOS native capabilities. A C++ native library (libadapter.so), an ArkTS adapter layer, and a JSBind bridge work together to make Obsidian's Node.js/Electron runtime operate on HarmonyOS.
| Project Info | |
|---|---|
| App ID | com.mikannqaq.obsidian |
| Version | 1.14.4.2 (versionCode: 11404002) |
| Target SDK | HarmonyOS 6.0.2(22) / API 22 |
| Target Devices | 2in1 (foldable/tablet), Tablet |
| Language | ArkTS (TypeScript) |
| Build System | Hvigor |
| Obsidian Engine | 1.14.4 (obsidian.asar, byte-for-byte official release) |
Architecture
flowchart TB A["Obsidian 1.14.4<br/>obsidian.asar (byte-for-byte official)"] B["Outer bootstrap script<br/>app/main.js"] C["Renderer injection<br/>app/inject/preload.js, dom-ready.js, hcs-channels.js"] D["Electron API compatibility<br/>@electron/remote + Node.js runtime"] E["JSBind bridge"] F["C++ native library<br/>libadapter.so"] G["ArkTS adapter layer<br/>47 adapters"] H["HarmonyOS native runtime<br/>Ability, ArkUI"] A --> B B --> C B --> D D --> E E --> F E --> G F --> H G --> H
Layers:
- Obsidian layer —
obsidian.asar, byte-for-byte the official release. File count, size, and md5 can be verified with the script bundled in this repo, see "Customization" - Outer bootstrap script —
app/main.js. Loads the asar and carries the version-floor short circuit, early remote enable, tray, close-to-tray, font compatibility, trash compatibility, the deeplink queue, and renderer injection - Renderer injection — three scripts under
app/inject/, applied before page scripts run or once the page is ready, also carrying the Huawei Cloud Sync channels - Electron compatibility layer —
@electron/remoteprovides the remote module API;libadapter.soprovides Node.js and system-level APIs - JSBind bridge — connects the JS runtime to the ArkTS native layer, forwarding Electron API calls to the matching adapter
- ArkTS adapter layer — 47 adapters wrapping HarmonyOS APIs as Electron-compatible interfaces
- HarmonyOS foundation — Ability components, ArkUI, and other system-native capabilities
Features
Obsidian Core Experience
- Full Obsidian 1.14.4 note editing and management
- Full compatibility with community plugins and themes
- Creating, managing, and browsing local Vaults
- Live Markdown preview and editing
- Graph view, backlinks, and other advanced features
Multi-Window Support
- Main, child, embedded, and floating windows
- Window position and size persistence
- Isolated renderer processes (via
ChildProcess) - Status bar extension window
Native System Integration
| Category | Coverage |
|---|---|
| File system | File manager, file picker, native dialogs, trash compatibility layer |
| Input | IME framework, drag and drop, multi-touch |
| Display | Multi-monitor management, dark/light theme following, custom cursors |
| Notifications | System notifications, screen lock event monitoring |
| Device | Bluetooth (classic + BLE), screen capture, power management, wake lock |
| Security | Certificate management, biometric authentication, clipboard access |
| Other | Printing, text-to-speech, shape detection, system sharing, external protocol handling |
Auto-Update
The HarmonyOS port disables desktop auto-update. The outer bootstrap script short-circuits the update check at startup and keeps the toggle on the About page disabled through the disable-update channel. The download and verification logic (RSA-SHA256 signature, SHA256 hash) remains in app/main.js and is currently unreachable.
Module Structure
The project uses the standard two-module HarmonyOS layout:
web_engine (HAR static library)
The core engine module, providing all Electron compatibility features and the adapter layer.
// Public exports (Index.ets)
export { WebAbilityStage } from './src/main/ets/application/WebAbilityStage';
export { WebAbility } from './src/main/ets/ability/WebAbility';
export { WebEmbeddedAbility } from './src/main/ets/ability/WebEmbeddedAbility';
export { WebWindow } from './src/main/ets/components/WebWindow';
export { WebSubWindow } from './src/main/ets/components/WebSubWindow';
export { WebEmbeddedWindow } from './src/main/ets/components/WebEmbeddedWindow';
export { WebWindowNode } from './src/main/ets/components/WebWindowNode';
export { WebNodeHandleWindow } from './src/main/ets/components/WebNodeHandleWindow';
export { WebNodeHandleSubWindow } from './src/main/ets/components/WebNodeHandleSubWindow';
export { VerifyLog } from './src/main/ets/utils/VerifyLog';
export { DeeplinkPusher } from './src/main/ets/adapter/DeeplinkPusher';
export { default as Inject } from './src/main/ets/common/InjectModule';
childProcess.ets separately exports WebChildProcess.
Dependency injection — InversifyJS manages adapter singletons; registration lives in common/CommonModule.ets and common/AdapterModule.ets.
electron (HAP entry module)
The executable application module containing all UI pages and application logic.
Ability components:
| Ability | Type | Purpose |
|---|---|---|
EntryAbility |
UIAbility | Main entry, handles deeplinks |
BrowserAbility |
UIAbility | Browser process window |
StatelessAbility |
UIAbility | Stateless window |
StatusBarEntryAbility |
ExtensionAbility (statusBarView) |
Status bar extension |
BrowserEmbeddedAbility |
ExtensionAbility (embeddedUI) |
Embedded window |
UI pages:
| Page | Description |
|---|---|
Index.ets |
Main interface hosting the WebWindow component |
WindowNode.ets |
Browser window node, loaded by BrowserAbility |
SubWindow.ets |
Child windows (popups, settings) |
EmbeddedWindow.ets |
Embedded window, loaded by WebEmbeddedAbility |
StatusBarPage.ets |
Status bar page |
WebPage.ets |
WebView pages for agreement display |
Adapter Layer
The adapter layer is ObsidianHM's most important infrastructure — it wraps HarmonyOS native APIs as Electron-compatible call interfaces.
Adapter Inventory
Every adapter extends BaseAdapter, is registered as a singleton through InversifyJS, and has a matching JSBind class:
web_engine/src/main/ets/adapter/
├── AccessibilityAdapter.ets # Accessibility
├── AppLifecycleAdapter.ets # Application lifecycle
├── AppWindowAdapter.ets # Application window operations
├── AutoUpdaterAdapter.ets # Update checking
├── BluetoothAdapter.ets # Bluetooth classic
├── BluetoothLowEnergyAdapter.ets # Bluetooth low energy
├── BrowserPolicyAdapter.ets # Browser security policy
├── CertManagerAdapter.ets # Certificate management
├── ContextAdapter.ets # Application context
├── ContextPathAdapter.ets # File path resolution
├── CursorAdapter.ets # Custom cursors
├── DeeplinkPusher.ets # Deeplink forwarding
├── DefaultApplicationAdapter.ets # Default application lookup
├── DeviceAdapter.ets # Device information
├── DeviceInfoAdapter.ets # Hardware information
├── DeviceUserAuthAdapter.ets # Biometric authentication
├── DialogAdapter.ets # Native dialogs
├── DisplayAdapter.ets # Display management
├── DragDropAdapter.ets # Drag and drop
├── ElectronAppAdapter.ets # Electron App API
├── EtsBridgeAdapter.ets # ArkTS two-way bridge
├── ExternalProtocolAdapter.ets # External protocol handling
├── FileManagerAdapter.ets # File management
├── FilePickerAdapter.ets # File picker
├── FontAdapter.ets # System font enumeration
├── I18nAdapter.ets # Internationalization
├── IMFAdapter.ets # Input method framework
├── MediaAdapter.ets # Media playback
├── MimeTypeAdapter.ets # MIME types
├── MultiInputAdapter.ets # Multi-window input
├── NativeThemeAdapter.ets # System theme
├── NotificationAdapter.ets # System notifications
├── PasteBoardApadter.ets # Clipboard
├── PermissionManagerAdapter.ets # Permission management
├── PopupWindowAdapter.ets # Popup windows
├── PrintAdapter.ets # Printing
├── ProcessAdapter.ets # Process management
├── RunningLockAdapter.ets # Wake lock
├── ScreenshotAdapter.ets # Screen capture
├── ShapeDetectionAdapter.ets # Shape detection
├── ShareAdapter.ets # System sharing
├── SpeechAdapter.ets # Text-to-speech
├── StatusBarManager.ets # Status bar control
├── SubWindowAdapter.ets # Child window management
├── SystemFloatingWindowAdapter.ets # System floating windows
├── UpdateChecker.ets # Update check channel
└── WebAppAdapter.ets # Web app metadata
JSBind Registration
Each adapter has a Bind class that registers its methods into the JS runtime:
// Example: clipboard adapter JSBind registration
JsBindingUtils.bindFunction('PasteBoardAdapter.ReadPasteBoardText', readPasteBoardText);
JsBindingUtils.bindFunction('PasteBoardAdapter.WriteData', writeData);
JsBindingUtils.bindFunction('PasteBoardAdapter.ReadImageBuff', readImageBuff);
// ...
All bindings are activated at startup through jsbindings/JsBindingMethod.ets. There are currently 292 bindings across 44 Bind classes.
Customization
obsidian.asar stays byte-for-byte the official release, with no patches applied. When official behavior needs to change, the change goes into the outer runtime instead:
| Location | What it carries |
|---|---|
app/main.js |
All main-process changes. Version-floor short circuit, early remote enable, tray, close-to-tray, font compatibility, trash compatibility, the deeplink queue, the log channel, PATH additions |
app/inject/preload.js |
Earliest renderer injection. i18n lookup wrapping, log forwarding |
app/inject/dom-ready.js |
Post-ready injection. Huawei Cloud Sync settings page, the exit-to-tray toggle, About page update entries, starter window titlebar text, window buttons and right margin |
app/inject/hcs-channels.js |
Handler functions for the 12 Huawei Cloud Sync hcs-* channels, loaded and registered by main.js |
Three constraints apply when changing injection code. Violating any of them builds successfully but fails at runtime:
- remote must be enabled when the WebContents is created. Call
remote.enable(contents)fromapp.on('web-contents-created', ...), registered before the asar is loaded - Overriding an official channel requires
removeAllListenersfirst, and the code must run afterloadApp(). The officialipcMain.oncalls all live inside the function that the asar'smodule.exportsinvokes - Do not override
window.close. The override applies to every renderer process and breaks three things: closing the starter window, switching vaults, and closing the settings popup
The only required patch is the version field in the outer package.json, which determines the installer version shown on the About page.
Verify asar purity:
node .agents/skills/obsidian-asar-upgrade/scripts/verify-asar.mjs \
web_engine/src/main/resources/resfile/resources/app/obsidian.asar 1.14.4
Per-item decisions are recorded in docs/asar-customization-runtime.md.
Build & Run
Requirements
| Tool | Notes |
|---|---|
| DevEco Studio | 5.0.0+ |
| HarmonyOS SDK | API 22 (6.0.2) |
| Node.js | 18.x+ |
Build and Install
devecocli build
devecocli run --skip-build --device <device-serial>
If devecocli is not on PATH, use /storage/Users/currentUser/npm/bin/devecocli.
Build output lands in electron/build/default/outputs/default/; the signed HAP is electron-default-signed.hap.
Signing Configuration
build-profile.json5 contains signing credentials and is gitignored. Copy the template and fill in your own values:
cp build-profile.example.json5 build-profile.json5
Debugging
Diagnostic output from the injection scripts is written to obsidian.log in the application data directory. On device, console.log reaches neither the log file nor hilog, so injection code writes through the ohsidian-log channel to the main process instead.
hdc shell "tail -n 60 /data/app/el2/100/base/com.mikannqaq.obsidian/files/obsidian.log"
Log timestamps are UTC; Beijing time is UTC+8. If the newest log entry predates the process start time, the running process has not written any log.
Project Structure
ObsidianHM/
├── AppScope/ # Global application config
│ ├── app.json5 # bundleName, version, multi-instance mode
│ └── resources/base/
│ ├── element/string.json # Application name "Obsidian"
│ ├── media/ # App icons (app_icon, startIcon, tray)
│ └── profile/configuration.json
│
├── web_engine/ # HAR static library (core engine)
│ ├── Index.ets # Public API exports
│ ├── childProcess.ets # WebChildProcess export
│ ├── oh-package.json5 # Deps: inversify, reflect-metadata
│ ├── hvigorfile.ts # harTasks build
│ └── src/main/
│ ├── ets/
│ │ ├── ability/ # WebAbility, WebEmbeddedAbility base classes
│ │ ├── adapter/ # 47 system adapters
│ │ ├── application/ # WebAbilityStage
│ │ ├── common/ # DI container, BaseAdapter, managers
│ │ ├── components/ # WebWindow, WebSubWindow, and other UI components
│ │ ├── interface/ # TypeScript interface definitions
│ │ ├── jsbindings/ # JSBind registration (44 Bind classes)
│ │ ├── process/ # WebChildProcess
│ │ └── utils/ # Logging and utilities
│ ├── cpp/types/libadapter/ # Type declarations for libadapter.so
│ └── resources/resfile/resources/app/ # Outer runtime (Electron app directory)
│ ├── main.js # Outer bootstrap script
│ ├── inject/ # Renderer injection scripts
│ ├── node_modules/ # @electron/remote, shipped with the package
│ ├── obsidian.asar # Official engine (tracked by Git LFS)
│ ├── package.json # Outer manifest; version must match the engine
│ ├── icon.png
│ └── tray.png # Tray icon
│
├── electron/ # HAP entry module
│ ├── oh-package.json5 # Deps: web_engine
│ ├── hvigorfile.ts # hapTasks build
│ ├── libs/arm64-v8a/ # libadapter.so
│ └── src/
│ ├── main/
│ │ ├── module.json5 # Module manifest (abilities, pages, permissions)
│ │ ├── ets/
│ │ │ ├── Application/ # AbilityStage
│ │ │ ├── entryability/ # Entry, Browser, Stateless, StatusBar
│ │ │ ├── extensionAbility/ # BrowserEmbeddedAbility
│ │ │ ├── pages/ # UI pages
│ │ │ ├── process/ # CustomChildProcess
│ │ │ └── utils/ # DeeplinkBridge
│ │ └── resources/
│ │ ├── base/element/ # String resources
│ │ ├── base/profile/ # main_pages routing config
│ │ ├── rawfile/ # Raw resources shipped with the package
│ │ └── zh_CN|en_US/element/
│ └── ohosTest/ # Test templates from the DevEco scaffold
│
├── tools/ # Symbol resolver: locates injection points in the official asar
├── docs/ # Project documentation, see "Documentation"
├── .agents/skills/ # Engine upgrade skill
├── build-profile.example.json5 # Signing config template
├── hvigor/ # Hvigor build config
├── hvigorfile.ts # Root build file (appTasks)
└── oh-package.json5 # Root package config
Dependencies
Runtime Dependencies
| Dependency | Version | Notes |
|---|---|---|
inversify |
^6.0.1 | IoC container managing adapter injection |
reflect-metadata |
^0.1.13 | TypeScript decorator metadata |
libadapter.so |
— | C++ native adapter library (local reference, prebuilt) |
btime / get-fonts |
— | Node dependencies shipped with the package under app/node_modules/, with prebuilt binding.node binaries |
@electron/remote |
2.1.3 | Electron remote compatibility, under app/node_modules/ |
Development Dependencies
| Dependency | Version | Notes |
|---|---|---|
@ohos/hypium |
1.0.6 | HarmonyOS test framework |
Documentation
| Document | Contents |
|---|---|
docs/obsidian-internals.md |
Official internals: the 46 channels, global objects, i18n lookup, settings page structure, titlebar, platform differences |
docs/asar-customization-runtime.md |
Per-item customization decisions and their basis |
docs/asar-upgrade.md |
Engine upgrade procedure and the recorded differences between versions |
docs/runtime-inject-verification.md |
On-device verification records |
docs/runtime-upgrade-34.md |
The full runtime upgrade to v34.8.5: version baseline, replacement scope, customization migration, sync approach, pitfalls |
docs/runtime-inject-plan.md |
Historical record of the runtime injection plan |
docs/licensing-audit.md |
Licensing audit: provenance and license status of the code and binaries, plus the open issues |
.agents/skills/obsidian-asar-upgrade/SKILL.md |
The full engine upgrade procedure, including the injection-point reference table |
AGENTS.md |
Repository-level working conventions |
License
Source Code of This Repository
The source code of this project is licensed under the BSD 3-Clause License; see the root LICENSE for the full text.
The ArkTS side mainly comes from the HarmonyOS Electron template contributed by Huawei Device Co., Ltd., totaling 149 files whose headers carry a three-line BSD-style reference pointing to that LICENSE:
// Copyright (c) 2024 Huawei Device Co., Ltd. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
The 11 files added by this project — the injection scripts, the symbol resolver tools, and others — carry Copyright (c) 2026 HandwerSTD headers. Provenance, byte-for-byte comparisons, and open issues are recorded in docs/licensing-audit.md.
Third-Party Licenses
- Obsidian —
obsidian.asaris the byte-for-byte official release; the officialpackage.jsondeclaresUNLICENSED, granting no redistribution rights. Obsidian and its trademarks belong to their respective owners - Electron (runtime binaries
libelectron.so,libffmpeg.so) — MIT License, full text shipped atresfile/LICENSE.electron.txt - @electron/remote — MIT License, full text shipped at
app/node_modules/@electron/remote/LICENSE - InversifyJS / reflect-metadata — MIT License
- Chromium runtime (the pak, blob, and locale files under
resfile/) — BSD-family licenses; the third-party license compilation is shipped atresfile/LICENSES.chromium.html - btime / get-fonts — Obsidian-proprietary native addons; the official
package.jsondeclaresUNLICENSED
Acknowledgments
This project stands on the shoulders of giants:
- Obsidian — the note-taking app that changed knowledge management
- Electron — the cross-platform desktop application framework
- HarmonyOS — the all-scenario distributed operating system
- InversifyJS — a powerful TypeScript IoC container
- OHSidian — the original project this work is based on
ObsidianHM is a community project, unaffiliated with Obsidian officially.
Introduction
用于在鸿蒙设备上运行 Obsidian 笔记,管理本地 Vault、安装插件主题并同步笔记。项目构建 Electron 兼容层,以 ArkTS 适配器和 C++ 桥接接入系统能力,集成华为账号、云同步、多窗口与状态栏扩展。【此简介由AI生成】
Customize your domain