# HelloHarmony

**Repository Path**: lu_yuedong/hello-harmony

## Basic Information

- **Project Name**: HelloHarmony
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hello Harmony

**已集成系统签名，用 Claude Code 或 Codex 开发需要系统权限的鸿蒙应用。**

简体中文 | [English](README.en.md)

Hello Harmony 提供一个已接入系统签名的 ArkTS / ArkUI Stage 工程，以及一份可迁移的鸿蒙系统应用开发 Skill。你可以从这个 Demo 起步，开发调用系统 API、使用系统权限的功能；也可以把 Skill 接入已有工程，让 Coding Agent 结合实际 SDK、权限和签名配置完成开发。

## 仓库里有什么

- **系统签名已接入构建。** HAP 编译完成后由现有 hook 自动执行系统签名，为系统权限应用开发提供签名基础；配套 Skill 指导关联 API、模块权限与 Profile 授权。
- **真实的最小 Demo。** 点击页面中的文字，`Hello World` 会变为 `Welcome`；工程保留完整的 Hvigor 构建入口和已有签名链，适合作为功能开发的起点。
- **一站式开发 Skill。** 覆盖系统 API 选择、权限与 Profile 配置、异步资源管理、环境准备、编译、验签及按需设备调试。
- **Claude Code / Codex 共用的原生入口。** 两个客户端通过目录符号链接读取同一份 Skill，无需额外插件或同步脚本。

Skill 在步骤之外解释判断依据：为什么从目标 SDK 查接口，为什么模块权限与签名身份要一起核对，为什么页面退出后仍需处理迟到的资源。模型据此适配当前任务，具体参数从工程配置取得。

## 从 Demo 开始

### 1. 获取工程

```bash
git clone https://gitee.com/lu_yuedong/hello-harmony.git
cd hello-harmony
```

Windows 克隆时使用 `git -c core.symlinks=true clone` 加上上述仓库地址，并确保系统允许创建符号链接。入口若被检出为普通文本文件，按 [原生入口说明](AGENTS.md#统一-skill-与原生入口)恢复链接。

### 2. 准备工具链

安装与[工程 SDK 配置](build-profile.json5)匹配的 [DevEco Studio](https://developer.huawei.com/consumer/cn/download/deveco-studio) 或 [Command Line Tools](https://developer.huawei.com/consumer/cn/download/command-line-tools-for-hmos)。沿用已有可用环境；使用独立 CLT 时另外配置匹配的 JDK。

[工具链指南](skills/harmonyos-system-app/references/toolchain.md)包含版本与路径核对、Node / Java / SDK 环境配置，以及 POSIX 和 PowerShell 的依赖恢复、构建命令。可以让 Agent 按指南配置，也可以直接手动执行。

### 3. 让 Agent 开始工作

从克隆后的 `hello-harmony` 仓库目录启动客户端，在对话中输入以下请求。

**Codex**

```text
$harmonyos-system-app 读取当前工程配置，完成 debug 构建并验证最终 HAP 的签名，报告结果和产物位置。
```

**Claude Code**

```text
/harmonyos-system-app 读取当前工程配置，完成 debug 构建并验证最终 HAP 的签名，报告结果和产物位置。
```

也可以直接用自然语言描述需求。比如下一步开发任务可以是：

> 在现有页面增加虚拟屏的创建和关闭操作。根据目标 SDK 核对接口与权限，处理重复点击、失败状态和退出页面时的资源释放，完成编译。

这些是交给 Agent 的开发请求。当前 Demo 的功能仍是上面的点击交互；设备安装和运行按你的请求执行。构建与签名产物的位置见 [Demo 构建与签名接入](AGENTS.md#本-demo-的构建与签名接入)。

## 接入已有工程

将本仓库的整个 [`skills/harmonyos-system-app/`](skills/harmonyos-system-app/) 目录复制到目标仓库的同名位置，包含 `SKILL.md` 和 `references/`，再为所用客户端建立发现入口：

```text
skills/harmonyos-system-app/                 ← 唯一 Skill 源
.agents/skills/harmonyos-system-app          → ../../skills/harmonyos-system-app
.claude/skills/harmonyos-system-app           → ../../skills/harmonyos-system-app
```

在目标仓库根目录执行以下 POSIX 命令可创建两个入口；仅使用一个客户端时，创建对应入口即可。若同名入口已存在，先核对其指向。

```bash
mkdir -p .agents/skills .claude/skills
ln -s ../../skills/harmonyos-system-app .agents/skills/harmonyos-system-app
ln -s ../../skills/harmonyos-system-app .claude/skills/harmonyos-system-app
```

保留目标工程已有的 `AGENTS.md`、`CLAUDE.md`、构建配置、签名方式与 CI。迁移内容是 Skill 和发现入口；Demo 的 `hw_sign/` 与项目说明留在本仓库。Skill 会从目标工程定位模块、产品、SDK 和签名入口，鸿蒙工程也可以位于仓库子目录中。

从目标仓库根目录或其子目录启动客户端；新建入口后若当前会话未发现 Skill，重新启动客户端。完整接入约定见 [两种使用方式](AGENTS.md#两种使用方式)。

## 系统签名与系统权限开发

**本 Demo 已配置系统签名，可作为开发系统权限应用的起点。** `Hvigor → SystemSignPlugin → hw_sign/sign.js` 将构建与签名接通，使用 OpenHarmony 公开示例签名材料，Profile 声明了 `system_core`、`hos_system_app` 和 `os_integration`。

开发需要系统权限的功能时，Skill 会引导 Agent 核对目标 SDK 的系统 API，将代码调用、模块权限声明和 Profile 授权对应起来，再完成构建与验签。系统签名提供应用身份基础，权限配置与目标系统共同决定具体能力的可用性。

设备上的系统应用资格由目标系统信任链及 Profile 授权、有效期等共同决定。使用示例签名开发时，结合目标系统核对这些条件；已有工程继续使用自己的签名身份。Demo 的具体材料与脚本适用范围见 [AGENTS.md](AGENTS.md#本-demo-的构建与签名接入)，最终 HAP 的验签与身份核对见 [签名指南](skills/harmonyos-system-app/references/signing.md)。

## 文档导航

| 想了解什么 | 阅读入口 |
| --- | --- |
| Demo 结构、工程参数、签名接入和开发约定 | [AGENTS.md](AGENTS.md) |
| Agent 如何从需求推进到可交付产物 | [SKILL.md](skills/harmonyos-system-app/SKILL.md) |
| 环境配置、依赖恢复、构建与错误定位 | [toolchain.md](skills/harmonyos-system-app/references/toolchain.md) |
| 系统 API、权限、资源生命周期与功能验收 | [system-capabilities.md](skills/harmonyos-system-app/references/system-capabilities.md) |
| HAP 验签、Profile 身份核对与设备调试 | [signing.md](skills/harmonyos-system-app/references/signing.md) |

中英文 README 提供使用导览。项目说明统一维护在 `AGENTS.md`，`CLAUDE.md` 通过 `@AGENTS.md` 导入；Skill 统一维护在 `skills/harmonyos-system-app/`，两个客户端入口指向同一目录。更新工程约定或开发知识时，在对应源文件中修改。