欢迎加入开源鸿蒙PC社区： https://harmonypc.csdn.net/

欢迎在PC社区平台申请新建项目： https://atomgit.com/OpenHarmonyPCDeveloper

本文以 ohos_CodeLite 为对象，按“迁移边界、三层架构、路径安全、开发工作流、Git 与调试、测试证据、部署方式”的顺序，记录 HarmonyOS PC IDE 的适配过程。重点不是把桌面端界面逐像素复刻，而是把打开工作区、编辑、构建、运行、Git 和调试组织成一条可验证的主线，并把 Remote Agent 的权限边界写清楚。

一、CodeLite 要迁移的不是 wxWidgets，而是开发工作流

CodeLite 原本依赖 wxWidgets、桌面文件系统、本机编译工具链和原生调试器。把源码直接交叉编译成 HarmonyOS 应用并不可行，项目因此选择保留开发者的工作流，而不是保留桌面实现的每一行代码。

ohos_CodeLite 是非官方迁移版本。它复用固定上游版本的 CodeLite 名称与部分图标，使用 ArkUI、ArkWeb 和 Remote Agent 重新实现编辑器、资源管理器、构建、终端、Git 与调试路径，不移植 wxWidgets 界面和插件 ABI。

CodeLite 能力	HarmonyOS PC 实现	关键约束
桌面工作台	ArkUI 原生菜单、工具栏、侧栏、标签和状态栏	面向键盘、鼠标和 PC 窗口
代码编辑器	ArkWeb 离线加载 Monaco Editor	不在运行时访问 CDN
文件工作区	Remote Agent 授权多根工作区	客户端只提交工作区相对路径
构建与语言智能	Agent 管理任务、工具链、CMake 与 LSP	只能选择管理员已发布配置
终端与 Git	Agent 托管 PTY 和类型化 Git 操作	不接受客户端任意命令或凭据
调试	管理员配置的 LLDB-DAP 适配	调试输入经过 Agent 收敛

衡量适配结果的重点不是界面是否像素级复刻，而是开发者能否在 HarmonyOS PC 上连续完成“打开工作区、编辑、构建、运行、查看 Git、启动调试”这条主线。

二、原生客户端、离线 Web 运行时与 Remote Agent 的三层结构

项目最核心的取舍，是把客户端、Web 运行时和主机工具链拆成三层。ArkUI 处理窗口与工作台，ArkWeb 只承载离线 Monaco Editor 和 xterm.js，Remote Agent 承担所有文件、进程、语言服务和调试能力。任何一层都不需要假装拥有另外两层的权限。

模块	实现	离线与安全设计
原生工作台	ArkTS / ArkUI Stage 模型	面板状态使用 HarmonyOS Preferences，只保存非敏感会话元数据
编辑器	独立 Vite 工程构建 Monaco Editor	产物写入 rawfile/editor/，运行时无 CDN 依赖
终端	独立 Vite 工程构建 xterm.js	产物写入 rawfile/terminal/，前端不持有 Agent Token
主机能力	Node.js Remote Agent	工作区、任务、终端、Git、LSP 和 DAP 都由 Agent 管理

export const REMOTE_PROTOCOL_VERSION: number = 1;

export interface RemoteAgentEnvelope {
  protocolVersion: number;
  requestId: string;
  ok: boolean;
  data?: object;
  error?: RemoteAgentErrorPayload;
}

ArkTS 客户端与 Agent 之间不是“传一段字符串让主机解释”，而是通过请求 ID、协议版本、成功数据和类型化错误码组成信封。编辑器 Bridge 也使用版本校验和字段检查，避免 Web 页面与 ArkTS 在接口升级后静默错位。

三、从工作区到文件保存：类型化协议如何保护路径边界

Remote Agent 的第一条安全边界是工作区。客户端不会发送本机绝对路径，Agent 只接受工作区相对路径，并在每次读写和变更前解析真实路径，确认目标没有越过授权根目录。

function isInside(rootPath: string, candidate: string): boolean {
  const relativePath = relative(rootPath, candidate);
  return relativePath === '' || (relativePath !== '..' &&
    !relativePath.startsWith(`..${sep}`) &&
    !isAbsolute(relativePath));
}

export async function resolveWorkspacePath(
  workspace: WorkspaceConfig, value: string
): Promise<string> {
  const segments = validateRelativePath(value);
  const lexicalPath = resolve(workspace.rootPath, ...segments);
  if (!isInside(workspace.rootPath, lexicalPath)) {
    throw new AgentRequestError(
      AgentErrorCode.PATH_OUTSIDE_WORKSPACE, 403,
      'Path is outside the workspace');
  }
  return realpath(lexicalPath);
}

文件保存又增加了修订号。客户端提交打开文件时看到的 SHA-256 修订，Agent 在写前重新读取当前内容；如果外部程序已经修改文件，就返回冲突，而不是直接覆盖。创建、重命名、移动和删除还会检查符号链接、目录状态和跨根移动，这些错误都有独立的类型化代码。

边界	拒绝或处理方式
绝对路径、反斜杠、空字符	返回 INVALID_PATH
解析后位于工作区之外	返回 PATH_OUTSIDE_WORKSPACE
符号链接变更	返回 SYMBOLIC_LINK_MUTATION
文件在编辑期间被外部修改	返回 REVISION_CONFLICT
二进制或超出上限	返回 BINARY_FILE / FILE_TOO_LARGE

这类设计让 ArkTS 侧不需要理解主机路径规范，也让错误能够回到编辑器和资源管理器的正确上下文。路径、修订和符号链接不是“错误提示细节”，而是保证远程 IDE 不误改主机文件的协议基础。

四、编辑、语言服务、构建和终端怎样接到主线

编辑器、语言服务、构建和终端分别解决不同问题，但共享同一条工作区主线。编辑器负责交互和文本状态，语言服务提供诊断、补全、符号和重命名，任务系统执行管理员配置文件中的构建命令，终端则保留开发者熟悉的交互式环境。

能力	实现方式	关键配置
C/C++	clangd	编译数据库、Clang 工具链
JavaScript / TypeScript	TypeScript Language Server	工作区 Node.js 环境
PHP	Phpactor	可选的 PHP 运行时
Python	Pyright Language Server	Python 解释器与包环境
Rust	rust-analyzer	Rust 工具链

Monaco 和 xterm.js 不通过运行时下载，而是在开发电脑上先构建成静态资源。这样 HAP 安装后就没有 CDN、外网包源或网页脚本版本漂移问题：

cd tools/editor-web
npm ci
npm run typecheck
npm test
npm run build

cd ../terminal-web
npm ci
npm run typecheck
npm test
npm run build

构建任务只能来自 Agent 管理员配置。子进程启动时显式使用 shell: false，参数以数组传递，并从环境变量中删除 Agent Token。终端同样是 Agent 托管的 PTY，客户端只能创建、连接、输入、改变尺寸和终止已有会话，不能指定任意 shell、工作目录或附加环境变量。

delete environment['OHOS_CODELITE_TOKEN'];
child = spawn(task.executable, task.args, {
  cwd: task.resolvedWorkingDirectory,
  env: environment,
  shell: false,
  stdio: ['ignore', 'pipe', 'pipe']
});

终端最多同时保留四个编号 PTY 标签，并处理重连、回放缺口和输出订阅。这样即使网络短暂波动，编辑器仍能区分“会话已经结束”和“客户端暂时失去订阅”，不会把两者混成同一种错误。

五、Git 与调试：把高权限能力收回 Agent

Git 和调试直接操作源码、历史、进程和内存，是 IDE 中权限最高的部分。ArkTS 客户端没有把这些能力换成任意 Shell，而是继续沿用类型化路由：Git 只接受工作区限定的操作，调试只接受管理员已发布的配置和受控输入。

工作流	Agent 提供的能力	收紧后的输入
源代码管理	状态、Diff、暂存、提交、分支、历史和同步	工作区相对路径、提交信息和固定操作
历史修复	受控 Revert、Apply Patch、Reset 到当前 HEAD	一次性事务 ID、预览与状态复核
调试控制	LLDB-DAP 启动、附加、继续、暂停和停止	Agent 已公布的配置 ID 或进程 PID
断点	源码、函数、地址和日志点	规范化位置、条件和命中次数
变量与内存	Watch、求值、变量修改、反汇编和内存窗口	默认关闭的管理员策略与不透明 ID

协议为失败预留了细粒度错误码。下面只摘出与 Git 和调试相关的部分，它们让客户端能区分“没有仓库”“工作树不干净”“能力未授权”和“适配器不可用”，而不是统一显示一条未知错误。

GIT_NOT_REPOSITORY
GIT_WORKTREE_DIRTY
GIT_NON_FAST_FORWARD
DEBUG_ADAPTER_UNAVAILABLE
DEBUG_ATTACH_NOT_ALLOWED
DEBUG_EVALUATION_NOT_ALLOWED
DEBUG_MEMORY_WRITE_NOT_ALLOWED
DEBUG_BREAKPOINT_FEATURE_UNAVAILABLE

默认开放

• 只读状态与历史

• 安全范围内的文件与搜索

• 已配置任务的启动

• 普通断点与栈查看

需要显式策略

• 变量与寄存器修改

• 内存写入

• 调试控制台求值

• 协议日志和部分数据断点

调试能力依赖目标主机的 LLDB-DAP、程序权限和 Agent 配置。客户端支持某项界面，不代表任意主机和任意程序都能直接调试。

六、测试数字和真机证据说明了什么

项目提供的验证数字覆盖了客户端、离线 Web 资源、Remote Agent 和 HAP 构建。文中的三张图分别对应工作台调试界面、源代码管理界面和本地目录隔离探针；它们不是把所有功能都跑到真机，而是把“界面证据”和“生命周期证据”分开呈现。读者应结合测试报告判断哪些层已经通过自动化检查，哪些仍处于“代码已实现、设备待验收”。

验证项	结果	说明
Remote Agent	157/157 通过	TypeScript 类型检查和构建通过
ArkTS 本地单元测试	272/272 通过	客户端状态、协议和领域逻辑
Editor Web	16/16 通过	构建与生产资源生成通过
Terminal Web	5/5 通过	构建与生产资源生成通过
HarmonyOS HAP	通过	签名 debug HAP 构建、安装和启动通过
本地目录真机证据	7/7 通过	HAD-W32 / OpenHarmony-6.1.1.130
双语资源	934 / 934	base 与 zh_CN 键集合一致
Node.js 依赖审计	0 漏洞	三个运行时工程生产依赖

其中“本地目录真机证据”验证的是隔离探针中的目录选择、可逆文件操作、应用重启、设备重启、外部修改、清理和撤销策略七个检查点，并不等同于完整 IDE 验收。图 3 的作用是证明授权目录的生命周期边界，而不是证明编辑器已经可以直接打开该目录。正常工作台尚未开放本地目录模式，网络连接、窗口缩放、键盘与输入法、终端、Git、LSP 和 LLDB-DAP 仍需在实际部署环境中完成端到端验证。

**证据结论：**工程、协议、离线资源和 HAP 已经有稳定的自动化基线；真机证据证明关键生命周期方向可行，但还没有到“所有 IDE 工作流均已在 PC 上长期验证”的阶段。

七、编译、部署与连接工作区

工程包含三个 Node.js 构建工程和一个 HarmonyOS HAP。正确顺序是先构建离线 Web 资源和 Remote Agent，再构建客户端，最后部署到 PC 或 2-in-1 设备。

cd tools/editor-web && npm ci && npm run build && cd ../..
cd tools/terminal-web && npm ci && npm run build && cd ../..
cd remote-agent && npm ci && npm run typecheck && npm test && npm run build

Remote Agent 默认监听 http://127.0.0.1:8736。最小启动方式只需要一个工作区和至少 24 个字符的 Token；跨设备访问应优先使用 SSH 隧道或 TLS，只有隔离的可信开发网络才考虑显式监听局域网地址。

export OHOS_CODELITE_TOKEN='replace-with-at-least-24-characters'
npm start -- \
  --workspace sample=/absolute/path/to/project

客户端在 DevEco Studio 中配置签名后构建 HAP，也可以使用 HDC 安装已签名产物。启动应用后，在“远程”视图输入 Agent 地址和 Token，连接后选择已授权工作区，再从资源管理器打开文件。

hdc install -r /absolute/path/to/entry-default-signed.hap

• • 离线 Monaco 与 xterm.js 随 HAP 打包
• • Remote Agent 可独立构建和测试
• • 签名 debug HAP 已完成构建、安装和启动
• • 真实部署环境中的网络、键盘、输入法和完整 IDE 流程验收

八、T0 / T1 / T2 与当前限制

按证据强度划分，CodeLite 项目已经越过“仅能编译界面”的阶段，但还没有把完整 IDE 的所有真实设备路径一起关闭。T0 关注能构建、能启动，T1 关注核心开发工作流，T2 关注真实部署和长期运行。

层级	当前范围	仍需完成
T0	ArkUI 工作台、离线 Monaco/xterm、双语资源、HAP 构建	真实设备上的缩放、输入法和焦点复核
T1	远程工作区、文件、搜索、替换、LSP、任务、终端、Git 和 LLDB-DAP	真实工具链与完整用户流程验收
T2	本地目录隔离探针七项门禁通过	接入正常工作台，完成 PC/2in1 长期运行验证

• • ArkTS 客户端、离线编辑器和终端资源随 HAP 构建
• • Remote Agent 协议、工作区、语言服务、终端、Git 和调试主路径实现
• • 本地目录隔离探针在 HAD-W32 真机通过七项检查
• • 本地目录模式接入正常工作台
• • 网络、输入法、缩放、终端、Git、LSP 和调试完成完整设备验收
• • B17.3 后续工作启动

**本文结论：**ohos_CodeLite 的核心价值是把 CodeLite 的开发工作流拆成可构建、可测试、可审计的 HarmonyOS 原生客户端与 Remote Agent 组合。当前最需要继续补的是正常工作站中的真机全流程，而不是再增加没有真实后端语义的界面控件。

参考资料与源码入口

• ohos_CodeLite 迁移仓库

• CodeLite 上游仓库

• CodeLite 参考提交

项目内主要资料包括 README.OpenHarmony_CN.md、remote-agent/README.md、总体架构设计、CodeLite 功能与 UI 对标矩阵、剩余功能路线图和第三方许可证说明。

条目	值
应用版本	1.0.0
Remote Agent	0.48.0，协议 v1
目标 SDK	HarmonyOS 6.1.1 (API 24)
项目许可证	GPL-2.0
真机证据	HAD-W32 / OpenHarmony-6.1.1.130