ohos-system-app-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenHarmony System App Dev

OpenHarmony System App 开发

Privilege-preflight and inner-loop skill for a standalone SDK project whose HAP may need to run as a system app. This is the middle case between an ordinary application and a platform component: it uses the normal application project structure, but a privileged build must carry

hos_system_app

identity, the required APL, any permitted ACLs, and a certificate chain trusted by the target image.

Use devecocli
for lint, build, device discovery, logs, and UI operations. Use the Full OpenHarmony SDK's

hap-sign-tool.jar

for offline profile/HAP signing. This workflow does not require Huawei-account signing for the SDK development-signing path.

Prereqs: an existing OpenHarmony application project, a Full OpenHarmony SDK matching the project's compile API, a JDK containing
java
and
keytool
, and a development target that trusts the SDK's OpenHarmony development certificate chain. The SDK development key is for local development only, never production distribution.

面向 HAP 可能需要以 system app 身份运行的独立 SDK 项目的权限预检与内层开发闭环 skill。它处于普通应用与平台组件之间的中间形态：使用常规应用项目结构，但特权构建必须携带

hos_system_app

身份、所需 APL、获准的 ACL，以及受目标镜像信任的证书链。

使用 devecocli
执行 lint、构建、设备发现、日志记录和 UI 操作。对于离线 profile/HAP 签名，使用 Full OpenHarmony SDK 的

hap-sign-tool.jar

。在 SDK 开发签名路径中，此工作流不需要 Huawei 账号签名。

前置条件： 一个现有的 OpenHarmony 应用项目、一个与项目 compile API 匹配的 Full OpenHarmony SDK、一个包含
java
和
keytool
的 JDK，以及一个信任 SDK OpenHarmony 开发证书链的开发目标。SDK 开发密钥仅用于本地开发，绝不能用于生产分发。

Routing rule

路由规则

Route by a suspected entitlement requirement, not by the apparent scope of the feature. Select this skill when an API or permission may require system-app identity, an elevated APL, ACL/provisioning, a Full SDK system API, or system-app signing. Product requests for privileged inspection or control of other apps or protected device state are clues that require this preflight even when the user does not say "system app."

Do not classify an application solely because a feature is cross-app or device-wide. Ordinary applications can use public inter-application APIs, while some system APIs operate entirely within one application. Inspect the exact target SDK's API annotations and permission definitions first. If every required capability is available to an ordinary application, continue with

ohos-app-dev

; otherwise continue with this skill.

根据疑似 entitlement 要求进行路由，而不是依据功能表面上的范围。当 API 或权限可能需要 system-app 身份、提升的 APL、ACL/provisioning、Full SDK system API 或 system-app 签名时，选择此 skill。要求对其他应用或受保护设备状态进行特权检查或控制的产品需求，即使用户没有明确提及“system app”，也应视为需要执行此预检的线索。

不要仅因为某项功能是跨应用或设备级功能，就将应用归类到此处。普通应用可以使用公开的跨应用 API，而某些 system API 完全在单个应用内部运行。首先检查目标 SDK 的 API 注解和权限定义。如果普通应用可以获得每项所需能力，则继续使用

ohos-app-dev

；否则继续使用此 skill。

When to use

何时使用

Use this skill when a standalone application:

calls an API that reports
```
Not System App
```
or is declared as a system API;
requests a permission whose definition requires system-app identity, elevated APL, or ACL;
must be installed as
```
isSystemApp: true
```
on a compatible emulator/development device; or
needs an offline, reproducible system-profile experiment without Huawei account services.

Route an ordinary standalone application to ohos-app-dev
. Route SystemUI, launcher, other OHOS source-tree components, and genuinely persistent/reboot-to-reload bundles to ohos-system-dev
. System-app identity does not by itself make a bundle persistent.

当独立应用存在以下情况时，使用此 skill：

调用某个会报告
```
Not System App
```
或被声明为 system API 的 API；
请求某项权限，而该权限的定义要求 system-app 身份、提升的 APL 或 ACL；
必须以
```
isSystemApp: true
```
安装到兼容的模拟器或开发设备；或
需要在不使用 Huawei 账号服务的情况下进行离线、可复现的 system-profile 实验。

将普通独立应用路由至 ohos-app-dev
。将 SystemUI、launcher、其他 OHOS 源码树组件，以及确实需要持久化或重启后重新加载的 bundle 路由至 ohos-system-dev
。仅有 system-app 身份并不会自动使 bundle 持久化。

Tool boundary

工具边界

Scaffold:
```
ohos-app-scaffold
```
/
```
devecocli create
```
, then continue here in a separate development step.
Edit/lint/build/device/UI/logs: use the normal
```
ohos-app-dev
```
guidance and
```
devecocli
```
.
System signing: use
```
scripts/system-app-sign.mjs
```
.
Exact HAP install and launch: use the DevEco toolchain's
```
hdc
```
because
```
devecocli run
```
does not accept an arbitrary post-build signed HAP path.
Custom/OEM signing: read
```
references/signing.md
```
and require user-provided trusted material; never substitute the SDK development identity silently.

项目脚手架： 使用
```
ohos-app-scaffold
```
/
```
devecocli create
```
，然后在单独的开发步骤中继续使用此工作流。
编辑/lint/构建/设备/UI/日志： 使用常规的
```
ohos-app-dev
```
指导和
```
devecocli
```
。
系统签名： 使用
```
scripts/system-app-sign.mjs
```
。
精确安装和启动 HAP： 使用 DevEco toolchain 的
```
hdc
```
，因为
```
devecocli run
```
不接受任意构建后已签名 HAP 的路径。
自定义/OEM 签名： 阅读
```
references/signing.md
```
，并要求用户提供可信材料；绝不能悄悄改用 SDK 开发签名身份。

Privilege preflight

特权预检

Before signing or changing configuration:

Read
```
build-profile.json5
```
and confirm
```
compileSdkVersion
```
,
```
targetSdkVersion
```
,
```
compatibleSdkVersion
```
, and
```
runtimeOS
```
. Use a Full OpenHarmony SDK when the API is not part of the public SDK.
Read every requested permission's definition from that exact SDK. Record its grant mode, permission APL, system-app restriction, and whether ACL/provisioning is allowed. Adding a name to
```
allowed-acls
```
cannot make an ineligible permission grantable.
Treat
```
202 Not System App
```
,
```
9568289 grant request permissions failed
```
, and signing failures as different gates. Do not infer from an emulator's Release label that all elevated applications are rejected.
Ensure the signing work directory and generated HAPs are gitignored. Never edit an SDK template or SDK keystore in place, copy a private key into the project, or print passwords.
If the project already has custom signing configuration or material, preserve it. The post-build workflow below does not require adding or replacing
```
signingConfigs
```
.

在签名或更改配置之前：

读取
```
build-profile.json5
```
，确认
```
compileSdkVersion
```
、
```
targetSdkVersion
```
、
```
compatibleSdkVersion
```
和
```
runtimeOS
```
。当 API 不属于公共 SDK 时，使用 Full OpenHarmony SDK。
从该确切 SDK 中读取每项所请求权限的定义。记录其授权模式、权限 APL、system-app 限制，以及是否允许 ACL/provisioning。仅将名称加入 allowed-acls 并不能让原本不符合条件的权限变为可授予。
将
```
202 Not System App
```
、
```
9568289 grant request permissions failed
```
和签名失败视为不同的验证关卡。不要因为模拟器带有 Release 标签，就推断所有提升权限的应用都会遭到拒绝。
确保签名工作目录和生成的 HAP 已被 gitignore 忽略。绝不能原地编辑 SDK 模板或 SDK keystore、将私钥复制到项目中，或打印密码。
如果项目已有自定义签名配置或材料，则予以保留。下面的构建后工作流不要求新增或替换
```
signingConfigs
```
。

Inner-loop workflow

内层开发闭环工作流

Edit the standalone application using the normal ArkTS/ArkUI architecture guidance.
Lint with
```
devecocli check lint
```
and treat zero checked files as weak evidence.
Build with
```
devecocli build
```
; require
```
BUILD SUCCESSFUL
```
and exit code
```
0
```
.
Select the exact unsigned HAP. Never sign "the newest HAP" or guess among modules.

Sign and verify the selected artifact with the helper:

powershell

node <skill-dir>/scripts/system-app-sign.mjs `
  --project-dir <project-dir> `
  --sdk-dir <full-sdk-api-dir> `
  --hap <exact-unsigned-hap> `
  --apl system_basic `
  --acl ohos.permission.EXAMPLE

Repeat

--acl

for each required ACL. Supply the complete set in one invocation because the generated profile contains exactly the requested list.

Device gate: run
```
devecocli device list
```
. Resolve multiple targets explicitly.
Install the exact verified HAP:
powershell
```
hdc -t <serial> install -r <signed-hap>
```
On
```
9568332
```
, stop before uninstalling and request explicit approval to replace the differently signed package. On
```
9568289
```
, return to the privilege/profile audit.
Verify Bundle Manager state:
powershell
```
hdc -t <serial> shell bm dump -n <bundle-name>
```
Require
```
isSystemApp: true
```
and the expected requested permission state.
Launch separately; a standalone system app is not assumed to be persistent:
powershell
```
hdc -t <serial> shell aa start -b <bundle-name> -a <ability-name>
```
Observe with
```
devecocli log
```
,
```
devecocli ui layout
```
, and
```
devecocli ui screenshot
```
. Completion requires visible/runtime evidence in addition to signer and installer success.

按照常规 ArkTS/ArkUI 架构指导编辑独立应用。
使用
```
devecocli check lint
```
执行 lint，并将零个文件被检查视为弱证据。
使用
```
devecocli build
```
构建；要求出现
```
BUILD SUCCESSFUL
```
且退出码为
```
0
```
。
选择确切的无签名 HAP。 绝不能签署“最新的 HAP”，也不得在多个模块之间猜测。

使用 helper 对选定产物进行签名和验证：

powershell

node <skill-dir>/scripts/system-app-sign.mjs `
  --project-dir <project-dir> `
  --sdk-dir <full-sdk-api-dir> `
  --hap <exact-unsigned-hap> `
  --apl system_basic `
  --acl ohos.permission.EXAMPLE

每项所需 ACL 都重复使用一次

--acl

。应在一次调用中提供完整集合，因为生成的 profile 恰好包含所请求的列表。

设备关卡： 运行
```
devecocli device list
```
。存在多个目标时，必须明确指定目标。
安装确切且已验证的 HAP：
powershell
```
hdc -t <serial> install -r <signed-hap>
```
遇到
```
9568332
```
时，停止卸载操作，并请求明确批准后再替换签名不同的包。遇到
```
9568289
```
时，返回特权/profile 审核步骤。
验证 Bundle Manager 状态：
powershell
```
hdc -t <serial> shell bm dump -n <bundle-name>
```
要求显示
```
isSystemApp: true
```
，并具有预期的权限请求状态。
单独启动； 不要假定独立 system app 具有持久性：
powershell
```
hdc -t <serial> shell aa start -b <bundle-name> -a <ability-name>
```
使用
```
devecocli log
```
、
```
devecocli ui layout
```
和
```
devecocli ui screenshot
```
进行观察。除了签名器和安装器执行成功外，完成任务还必须具备可见界面或运行时证据。

Signing helper contract

签名 helper 契约

scripts/system-app-sign.mjs

performs the fragile work deterministically:

reads bundle/version information without changing the project;
copies the unsigned release profile template to a project-local work directory;
exports the SDK root and application CA certificates as DER
```
.cer
```
files;
generates a CA-issued certificate chain for the SDK's Application Release key;
writes
```
hos_system_app
```
, the requested APL, and the complete ACL set into the copied profile;
signs and verifies the profile;
signs the exact input HAP and runs
```
verify-app
```
with accepted
```
.cer
```
/
```
.p7b
```
outputs; and
checks the embedded profile before emitting the signed HAP path and SHA-256 as JSON.

The helper refuses to overwrite generated outputs unless

--force

is supplied.

--force

applies only to its named outputs inside the selected work directory; it does not delete project source, SDK files, installed packages, or arbitrary directories.

scripts/system-app-sign.mjs

以确定性方式执行容易出错的工作：

读取 bundle/version 信息，而不修改项目；
将未签名的 release profile 模板复制到项目本地工作目录；
将 SDK 根证书和 application CA 证书导出为 DER 格式的
```
.cer
```
文件；
为 SDK 的 Application Release key 生成由 CA 签发的证书链；
将
```
hos_system_app
```
、所请求的 APL 和完整 ACL 集合写入复制后的 profile；
对 profile 进行签名和验证；
对确切输入的 HAP 进行签名，并使用已接受的
```
.cer
```
/
```
.p7b
```
输出运行
```
verify-app
```
；以及
在输出已签名 HAP 路径和 SHA-256 JSON 之前，检查嵌入的 profile。

除非提供

--force

，否则 helper 会拒绝覆盖已生成的输出。

--force

仅适用于所选工作目录内其明确指定的输出；它不会删除项目源文件、SDK 文件、已安装包或任意目录。

Proof required

必须提供的验证证据

Do not report success from a build or install message alone. Keep four independent gates:

```
verify-app
```
and embedded-profile verification pass.
Installation exits successfully.
```
bm dump
```
reports system identity and expected permissions.
The intended system API or behavior succeeds at runtime.

不要仅凭 build 或 install 消息就报告成功。必须保留四道相互独立的验证关卡：

```
verify-app
```
和嵌入 profile 的验证通过。
安装成功退出。
```
bm dump
```
报告 system 身份和预期权限。
目标 system API 或行为在运行时执行成功。

Reference

参考

```
references/signing.md
```
- profile fields, failure routing, development-signing limits, and custom/OEM signing boundaries.
ArkTS strictness, application architecture, and ordinary UI/debug operations remain in ohos-app-dev
; this skill adds only the standalone system-identity workflow.

```
references/signing.md
```
——profile 字段、失败路由、开发签名限制，以及自定义/OEM 签名边界。
ArkTS 严格性、应用架构和常规 UI/调试操作仍由 ohos-app-dev
负责；此 skill 仅添加独立的 system-app 身份工作流。