PR-Agent鸿蒙PC适配全记录：从Python服务端代理到ArkTS原生评审客户端
在代码评审逐渐智能化的今天,AI已经不只是“辅助写代码”的工具,也开始真正进入代码质量、变更分析和协作评审流程.但当现有的智能评审能力需要迁移到鸿蒙 PC 平台时,问题就不再只是“把界面做出来”这么简单：服务端能力如何复用？评审请求如何在不同技术栈之间传递？Python 侧的智能代理怎样与 ArkTS 原生应用协同？又该如何在保证体验的同时,完成一套真正可落地的原生评审客户端？这次,我尝试将 PR-Agent 的代码评审能力适配到鸿蒙 PC,整体方案从 Python 服务端代理 出发,通过接口层完成能力封装与数据交互,再由 ArkTS 原生客户端 承担评审发起、结果展示和交互操作,最终形成一条较完整的智能代码评审链路.整个适配过程涉及的不只是技术栈转换,还包括架构拆分、接口设计、数据结构适配、异步请求处理、原生界面交互以及评审结果呈现等多个环节.本文将按照实际实现过程,完整记录从服务端代理到鸿蒙 PC 原生客户端的适配思路、关键技术点、踩坑过程和实现方案,希望能够为正在探索 AI 代码评审、Python 与 ArkTS 协同、鸿蒙 PC 原生开发 的开发者提供一些可复用的实践参考.
目录
欢迎加入开源鸿蒙PC社区：(https://harmonypc.csdn.net/)
欢迎在PC社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper
适配开源地址：https://atomgit.com/OpenHarmonyPCDeveloper/ohos_pr-agent
环境搭建文章：本项目不是 Electron 或 Qt 工程,鸿蒙端采用Stage模型、ArkTS 与 ArkUI,主要依赖DevEco Studio、HarmonyOS SDK、Hvigor、调试签名和真机安装环境,因此不引用 Electron/Qt 环境搭建文章.
一、为什么要适配PR-Agent
代码评审的难点很少只是“有没有人看过代码”.在真实团队中,评审者还要先读懂 Pull Request 的目标、梳理文件改动、判断测试是否覆盖关键路径,再从大量差异中找出值得集中讨论的风险.PR-Agent 把这部分准备工作组织成 /review、/describe、/improve、/ask 等命令,并以结构化评论返回审查重点、PR 描述和可执行的代码建议.
选择 PR-Agent 进行 HarmonyOS PC 适配,首先是因为开发者工具本身就是 PC 生态的重要组成部分.随着越来越多的代码编辑、版本管理和构建工作迁移到鸿蒙 PC,Pull Request 阅读与辅助评审也应当拥有一条可以在本机完成的使用路径.其次,PR-Agent 同时连接 Git 托管平台、模型服务和结果展示,它比单纯移植一个静态桌面界面更能检验鸿蒙 PC 在网络访问、异步任务、配置持久化和复杂数据渲染方面的能力.
原项目以 Python 实现,主要面向 CLI、Webhook、GitHub App 和 CI 服务.若只把 Python 源码复制进 HAP,应用并不会自然获得可用的解释器、动态模块和子进程环境.适配的核心问题因此不是“怎样把入口图标放到桌面”,而是怎样在 HarmonyOS 应用沙箱允许的边界内保留 PR-Agent 的使用语义.
当前鸿蒙版本的应用 BundleName 为 ai.pr.agent,版本为 1.0.0,设备类型为 2in1.客户端支持 GitHub 与 GitLab PR 地址,通过 OpenAI 兼容 Chat Completions 服务执行分析,并在本机渲染 Reviewer Guide、PR Description 和 Code Suggestions 等结果卡片.
二、先确定适配边界：保留命令语义,不强行内嵌 CPython
适配早期曾尝试将 CPython 3.12 和依赖交叉编译到 OHOS AArch64.交叉编译本身能够生成 ELF 和 Python 运行目录,但真机应用处于 untrusted_app 沙箱：任意 ELF 的 posix_spawn 会被拒绝,未注册第三方共享库的 dlopen 也无法作为稳定运行方案.设备没有 su,调试 Shell 与普通应用进程又属于不同安全域,因此“在 HDC Shell 中能看到文件”并不代表 HAP 能启动同一程序.
项目对五类方案做过真机诊断,包括从沙箱启动 Python、从应用文件目录加载 libpython3.12.so、从打包库目录加载共享库、加载最小探针库以及在 HDC Shell 域直接执行目标程序.结果表明,继续围绕嵌入式 Python 叠加启动器和兼容补丁,只会把应用交付建立在不可控的系统策略上.
最终采用的路线是“ArkTS 原生客户端 + Git REST + OpenAI 兼容模型服务”：
HarmonyOS PC Stage HAP
├── ArkUI 命令工作台
│ ├── /review、/describe、/improve
│ ├── /ask、/ask_line、/add_docs
│ ├── /generate_labels、/update_changelog
│ └── /similar_issue、/help、/config
├── GitClient
│ ├── GitHub REST：PR、文件、提交、Issue
│ └── GitLab REST：MR 与 changes
├── PromptEngine + LlmClient
│ └── OpenAI 兼容 /v1/chat/completions
├── PrAgentService
│ └── 命令调度、JSON 解析、Markdown 发布内容
└── ResultViews
├── Reviewer Guide
├── PR Description / File Walkthrough
└── Code Suggestions / Similar Issues
这不是把原项目改写成另一套无关产品.PR 地址、斜杠命令、提示词输入、结构化结果和复制 Markdown 的工作流仍然沿用 PR-Agent;改变的是运行载体和数据获取方式.历史 CPython 交叉编译产物继续保留在 ohos/cross/,供非应用沙箱的研究或 CLI 场景使用,但不再进入当前 HAP 的用户运行链路.
三、适配后的工程结构
原项目的 Python 源码继续位于 pr_agent/,鸿蒙 PC 相关实现集中在 ohos/,避免平台代码侵入上游命令与 Provider 模块.
ohos_pr-agent/
├── pr_agent/ # 上游 Python CLI、工具与 Provider
├── tests/ # Python 单元、端到端与健康测试
├── README.OpenHarmony_CN.md # 鸿蒙适配说明
└── ohos/
├── README.md # 鸿蒙客户端使用与能力矩阵
├── ON_DEVICE_DIAGNOSIS.md # CPython 真机沙箱诊断
├── SIGNING_GUIDE.md # 调试签名与安装说明
├── app/
│ ├── AppScope/app.json5 # BundleName 与应用版本
│ ├── build-profile.json5 # 产品、SDK 与签名配置
│ └── entry/src/main/
│ ├── module.json5 # 2in1 与 INTERNET 权限
│ └── ets/
│ ├── pages/Index.ets # 命令侧栏与主工作区
│ ├── components/ResultViews.ets
│ ├── model/Types.ets
│ ├── service/GitClient.ets
│ ├── service/LlmClient.ets
│ ├── service/PromptEngine.ets
│ ├── service/PrAgentService.ets
│ ├── service/SettingsStore.ets
│ └── util/HttpUtil.ets
├── dist/ # 签名与未签名 HAP
├── evidence/ # 仓库内真机验证材料
├── cross/ # 历史 CPython 交叉编译产物
└── scripts/ # 交叉编译与依赖处理脚本
当前签名 HAP 大小约 488 KiB.应用运行时只声明 ohos.permission.INTERNET,不要求本地仓库目录、系统级 Git 命令或后台常驻权限,功能边界比较清楚.
四、关键适配实现
1.将 Provider行为收敛到PR快照
原版 PR-Agent 的 Provider 层面向多种服务端部署形态,包含评论发布、标签、提交、差异、代码行和仓库设置等大量接口.鸿蒙客户端先把当前命令真正需要的数据收敛为 PrSnapshot：Provider、仓库、PR 编号、标题、描述、分支、标签、提交摘要、变更文件和 diff 都进入同一个数据模型.
GitClient.ets 根据 URL 识别 GitHub Pull Request 或 GitLab Merge Request.GitHub 路径依次读取 PR 元数据、变更文件和提交列表;GitLab 路径读取 MR 与 changes.公开 GitHub PR 可以不配置 token,但会受到匿名 API 速率限制;私有仓库必须在 /config 中设置对应平台令牌.
这种收敛减少了 ArkTS 页面与平台接口的直接耦合.后续命令只接收统一快照,不需要在每一种 Prompt 中重复处理 Provider 分支.
2.为长差异设置明确上限
Pull Request 的 patch 大小变化很大.客户端按文件拼接路径、状态、增删行数和 patch,并将本轮模型输入的 diff 上限设为 60000 个字符.达到上限后添加截断标记,避免移动端网络请求和模型上下文在没有提示的情况下失控.
这里保留了一个需要继续优化的边界：字符截断不等同于上游完整的 token 感知压缩策略.当前版本能处理常见 PR,但超大改动仍应拆分提交,或在后续版本中加入按语言、文件重要性和 token 预算进行的选择机制.
3.用结构化输出稳定结果卡片
/review、/describe 和 /improve 的提示词要求模型只返回 JSON.Review 数据包括评审工作量、测试相关性、安全关注点、分数和重点问题;Describe 数据包括标题、类型、摘要、标签和文件导览;Improve 数据则包含建议类别、影响分、文件与行号、现有代码和改进代码.
模型返回内容可能被 Markdown 代码围栏包裹,也可能带有额外文本.JsonUtil 与 PrAgentService 负责提取 JSON 对象、读取字段并转换为强类型模型.解析之后,页面不再直接展示一整段不可控的模型文本,而是将字段交给固定卡片组件.这一步既提高了可读性,也让复制 Markdown 和后续发布评论使用同一份结果数据.
4.重新组织桌面端命令工作区
ArkUI 页面采用左侧命令导航和右侧工作区./review、/describe 和 /improve 共用 PR 地址输入与 Run/Copy 操作;/ask 增加问题输入;/ask_line 再增加文件路径和起止行;/similar_issue 使用可选搜索词;/config 单独呈现模型和 Git 平台设置.
结果区按原版评论的阅读方式组织.Reviewer Guide 使用表格汇总工作量、测试与安全信息;Description 将总体描述和 File Walkthrough 分开;Code Suggestions 同时给出问题说明、影响级别以及修改前后代码.相比把模型原始文本直接塞进一个多行输入框,这种布局更适合评审者快速扫读和定位文件.
5.将模型服务作为可配置依赖
客户端通过标准 POST /v1/chat/completions 调用模型服务,Base URL 和模型名都可以修改,因此不绑定单一云厂商.默认值为 https://api.openai.com 与 gpt-4o-mini,也可以切换到实现相同接口的企业网关或本地服务.
API key、GitHub token、GitLab token、Base URL、模型名和是否发布评论由 SettingsStore 写入应用沙箱内的 Preferences.密码字段在界面中以隐藏形式呈现.本地保存并不等于可以公开这些值：构建配置、文章、截图和仓库都不应出现真实 token,生产环境还应结合组织安全要求评估是否需要硬件级密钥存储.
6.区分生成结果、复制结果和发布评论
生成结果只需要读取 PR 和调用模型;Copy 将格式化 Markdown 写入系统剪贴板;“Publish result as a GitHub PR comment”则会对远端仓库产生写操作,需要具备相应权限的 GitHub token.三个动作没有被合并成一个按钮,默认也不启用发布,避免用户只想本地查看时意外向 PR 写入评论.
五、构建、签名与安装
本项目不是 Qt 或 Electron 应用.开发机需要准备 DevEco Studio、HarmonyOS SDK、DevEco JBR、Hvigor,以及与目标设备匹配的调试签名.
当前工程主要配置如下：
| 项目 | 当前值 |
|---|---|
| BundleName | ai.pr.agent |
| Version | 1.0.0 |
| DeviceTypes | 2in1 |
| Runtime OS | HarmonyOS |
| Compatible SDK | 5.0.0(12) |
| 真机 Target API | 6.0.2(22) |
| 应用权限 | ohos.permission.INTERNET |
| 签名 HAP | ohos/dist/entry-default-signed.hap |
使用命令行构建：
export JAVA_HOME=/Applications/DevEco-Studio.app/Contents/jbr/Contents/Home
export PATH="$JAVA_HOME/bin:/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin:$PATH"
export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
cd ohos/app
hvigorw assembleHap --mode module \
-p product=default \
-p buildMode=debug \
--no-daemon
构建产物位于：
ohos/app/entry/build/default/outputs/default/entry-default-signed.hap
签名材料与证书密码属于本机敏感配置,不应复制到文章或提交到公共仓库.可以在 DevEco Studio 中为目标设备自动生成调试签名,再安装并启动：
hdc install -r ohos/dist/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b ai.pr.agent -m entry
安装成功后,HDC 返回 install bundle successfully,桌面窗口标题为 PR-Agent.
六、HarmonyOS PC真机运行
以下五张截图均在 2026 年 8 月 25 日重新安装当前签名 HAP 后,从 HarmonyOS PC 真机直接取得,原始分辨率为 3120×2080.验证设备为 HUAWEI MateBook Pro(HAD-W32),系统内核为 HongMeng Kernel 1.12.0,架构为 AArch64.本轮公开截图没有向设备写入 LLM key、GitHub token 或 GitLab token;需要模型推理的命令必须由使用者在自己的设备上配置兼容服务.
1.应用启动与命令总览
应用启动后默认进入 /review.左侧列出 11 个当前客户端命令,右侧保留 PR 地址、Run 和 Copy 操作.默认示例地址指向 PR-Agent 上游公开 PR,页面同时提示先完成 /config 再执行需要模型的评审命令.
这一屏验证了签名 HAP 安装、EntryAbility 启动、2in1 全屏窗口、ArkUI 资源加载和命令路由.侧栏并不是静态说明图,点击不同命令后,右侧输入区会根据命令参数即时变化.
2.内置帮助列出可用命令
选择 /help 后,应用在本机直接生成帮助卡片,不需要访问模型服务.卡片列出 Review、Describe、Improve、Ask、行级问答、文档生成、标签、CHANGELOG、相似 Issue 和配置入口.
帮助结果沿用评论卡片外壳,并且 Copy 按钮在有结果时变为可用.它既用于新用户确认命令,也能在模型服务不可用时检查客户端 UI 和结果渲染链路.
3.本机配置模型与 Git Provider
/config 页面分别提供 LLM API key、Base URL、模型、GitHub token、GitLab token和发布评论开关.公开 PR 不强制填写 GitHub token;私有仓库、较高 API 配额或发布评论则需要相应权限.
截图刻意保持所有敏感字段为空.Base URL 和模型名使用默认值,说明客户端既可以连接默认服务,也能切换到 OpenAI 兼容网关.发布开关默认关闭,本地生成与远端写入由用户明确区分.
4.对公开PR执行相似Issue搜索
/similar_issue 基础版不调用 LLM,而是先读取真实 PR,再使用 GitHub Search API 在同一仓库检索 Issue.本轮输入 label,真机返回 8 条开放 Issue,包括编号、标题、状态和原始链接.
这张图不是预置数据.运行状态显示 Finished /similar_issue,结果中包含当时仓库的 Issue #2605、#2759、#2609 等.该功能当前属于关键词搜索基础版,不使用向量库,因此结果相关性取决于搜索词和 GitHub 索引,不能与语义检索混为一谈.
5.为具体文件和行号准备问题上下文
行级问答需要同时给出问题、文件路径和行号范围.截图使用同一个公开 PR 的真实变更文件 pr_agent/tools/pr_generate_labels.py,关注 174 至 181 行的标签大小写恢复逻辑.
这一屏验证 /ask_line 的参数路由和桌面输入布局.Run 会先拉取 PR 文件列表,从指定文件中提取相关 patch,再将问题与代码上下文交给已配置的模型服务.本轮截图没有配置 LLM key,因此只记录真实参数工作区,不把未执行的模型回答伪装成验收结果.
七、适配过程中最棘手的问题
难点一：能交叉编译,不代表能在应用沙箱中执行
CPython 和依赖能够生成 AArch64 OHOS 产物,只能证明编译工具链成立.应用是否允许创建子进程、动态加载共享库以及访问打包后的路径,是另一层问题.适配初期最大的成本正是区分“文件格式正确”和“应用安全域允许执行”,最终真机诊断促使项目停止继续堆叠嵌入式 Python 方案.
难点二：不能把上游服务端对象原样搬进桌面应用
原版 Provider 的生命周期与 Webhook、评论事件、仓库权限和服务端配置紧密相关.鸿蒙客户端需要的是一次前台交互：输入 PR 地址、读取必要上下文、执行命令并展示结果.若机械复刻全部 Provider 接口,不但工程庞大,也会引入客户端根本不需要的部署状态.因此适配先建立 PR 快照,再让各命令围绕同一份数据工作.
难点三：模型输出必须能稳定进入固定UI
LLM 即使被要求返回 JSON,也可能附加代码围栏、缺少字段或返回空数组.页面不能假设每次响应都完全一致.当前实现为字段提供默认值,并允许 Review 没有重点问题、Improve 没有建议、Describe 缺少可选标签.后续仍需要继续加强 JSON Schema 校验、重试策略和异常响应测试.
难点四：秘密信息与可发布截图必须彻底分离
评审客户端天然涉及 LLM key 和 Git Provider token.调试时最容易出现的问题不是功能失败,而是日志、配置文件或截图意外带出凭据.当前日志只记录模型名、URL、HTTP 状态和公开 PR 信息,不应记录 Authorization 内容;文章截图统一使用空密码字段,发布前还需检查构建配置中是否存在本机签名信息.
难点五：本地查看和远端写入必须是两个权限级别
公开 PR 读取可以匿名完成,但发布评论属于仓库写操作.若应用在 Run 后自动发布,测试一次模型配置就可能污染真实 PR.当前版本将 Publish 设为独立开关且默认关闭,Copy 也只操作系统剪贴板.对于开发者工具而言,这种默认行为比减少一次点击更重要.
难点六：相似 Issue 基础版需要如实标注能力上限
GitHub Search API 可以快速提供有用结果,也能在没有模型 key 时形成完整网络验证,但它不是上游可能采用的向量语义检索.当前实现支持自定义搜索词,并排除当前 PR 编号;对同义词、上下文和多语言描述的理解仍有限.文章和界面都应把它称为基础版,而不是泛化为完整智能检索.
八、当前能力与限制
| 能力 | 当前状态 | 说明 |
|---|---|---|
| HAP 构建、签名、安装与启动 | 可用 | 已在 MateBook Pro 真机重新安装并启动 |
/review | 已实现，需模型配置 | Reviewer Guide：工作量、测试、安全、分数与重点问题 |
/describe | 已实现，需模型配置 | 标题、类型、摘要、标签与 File Walkthrough |
/improve | 已实现，需模型配置 | 建议类别、影响分、文件行号与修改前后代码 |
/ask、/ask_line | 已实现，需模型配置 | 整体问答和指定文件行范围问答 |
/add_docs、/generate_labels | 已实现，需模型配置 | 文档生成与标签建议 |
/update_changelog | 已实现，需模型配置 | 读取现有 CHANGELOG 并生成 Unreleased 草稿 |
/similar_issue | 可用，基础版 | GitHub 关键词搜索；本轮真机返回 8 条结果 |
/help、/config | 可用 | 本机帮助与 Preferences 配置 |
| GitHub 公开 PR | 可用 | 可匿名读取，受 API 速率限制 |
| GitHub 私有 PR / 发布评论 | 需 token | 发布操作默认关闭 |
| GitLab MR | 已接入 | 支持 MR 元数据与 changes；私有项目需 token |
| Copy Markdown | 已实现 | 将格式化结果写入系统剪贴板 |
| Bitbucket、Azure DevOps、Gitea | 未适配 | 当前客户端只接入 GitHub 与 GitLab |
| Webhook、GitHub App、CI Action | 不在客户端范围 | 仍属于原项目的服务端部署形态 |
| 嵌入式 CPython CLI | 不采用 | 受 untrusted_app 子进程与动态库策略限制 |
| 向量化相似 Issue | 未实现 | 当前为 GitHub Search API 基础版 |
| 超大 PR 完整压缩策略 | 待增强 | 当前 diff 输入上限为 60000 字符 |
需要特别说明,界面中的命令入口“已实现”不等于任何设备开箱即用.Review、Describe、Improve 和问答类命令都依赖使用者提供可访问的模型服务;网络、模型配额、Provider 权限和返回格式都会影响最终结果.真机验收应当分别记录客户端链路、Provider 读取和模型推理,而不是用一张成功卡片概括所有外部依赖.
九、总结
PR-Agent 的鸿蒙 PC 适配最终没有选择最直观的“把 Python 装进 HAP”,因为真机安全域已经证明这条路线不能形成稳定产品.项目保留了上游 Python 源码和历史交叉编译材料,同时把用户侧核心流程重组为 ArkTS 原生客户端：Git REST 负责读取 PR,PromptEngine 保留命令语义,OpenAI 兼容接口承接模型推理,ResultViews 将结构化结果恢复成适合代码评审的卡片.
本轮真机复验完成了签名 HAP 重装、应用启动、命令帮助、配置页面、公开 PR 的 GitHub 数据访问、相似 Issue 实时检索以及行级问答参数路由.五张截图只记录实际出现的界面和结果,没有向截图环境注入秘密信息,也没有将未运行的模型回答作为完成证据.
从后续演进看,最值得继续投入的是超大 PR 的 token 感知压缩、结构化输出校验、GitLab 全流程复验、受保护的凭据存储,以及带自有模型服务的 Review/Describe/Improve 连续验收.当前版本已经建立可安装、可操作、边界清楚的鸿蒙 PC 评审工作台;在此基础上逐步补齐可靠性,远比继续绕过应用沙箱强行启动完整 Python 服务更可维护.
敬请期待下一篇文章内容
每日心灵鸡汤: 顺境决定你走得多舒服,逆境决定你能走多远!
顺境让人获得资源、信心和安全感;逆境却会逼一个人重新认识自己、理解人性、看清规则,并建立真正属于自己的能力.很多人的成熟,不是因为知道得更多,而是在一次次失去依赖之后,终于学会了独立判断、承担结果.所以,顺境决定一个人能走得多舒服,逆境往往决定一个人最终能走多远.
作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。
更多推荐
1
0- 0
已为社区贡献3条内容
所有评论(0)