你的 App，该给小艺"打工"了：几十行 ArkTS 把功能变成 HarmonyOS 7 Skill

鸿蒙开发热点系列 · 第 01 篇 ｜ 基于 HarmonyOS 7（API 26.0.0）

10 月 30 日，HarmonyOS 7 开始在 Mate 80、Pura 90、nova 16 等机型上全网推送 [1]。这一版最大的变化不是 3D 壁纸，而是小艺升级成了系统智能体：官方说它能调用 2100+ 系统能力和 500+ 生态 Skills，一句话就能完成复杂任务 [2]。

问题来了：用户对小艺说"帮我记一下明天交周报"，被调起来的是你的 App，还是别人的？

这篇只讲一件事：怎么用 API 26 新增的 Skill 框架，把你 App 里现成的功能开放给小艺调用。

一、核心点 1：Skill = 一份"说明书" + 一层"薄适配"

API 26 在 Ability Kit 里新增了方舟智能开发框架 ArkAF，提供三种把应用能力开放给系统智能体的方式：意图、Skill、端侧 A2A [3]。其中 Skill 适合"复杂场景功能"，从 API 版本 26.0.0 开始支持 [4]。

一个 Skill 由两样东西构成 [4]：

• SKILL.md：描述文件，写清楚"什么时候调我、参数长什么样、会返回什么"。官方原话是，它是系统智能体做"意图—能力"匹配的唯一依据。
• ArkTS 入口脚本：一层薄适配，把小艺传来的字符串参数交给你已有的业务代码，再把结果按约定回传。

官方特别强调：不需要改造现有业务实现。目录结构是固定的：

entry/
├── skills/                      <- 固定目录名
│   └── example-org-todo/        <- Skill 名，需与 SKILL.md 的 name 一致
│       ├── scripts/
│       │   └── TodoSkill.ets    <- 入口脚本
│       └── SKILL.md
└── src/main/
    ├── ets/service/TodoStore.ets  <- 你已有的业务代码
    └── module.json5

在 module.json5 的 module 节点下注册（仅支持 Stage 模型）[4]：

{
  "module": {
    // ...
    "skillProfiles": [
      {
        "name": "example-org-todo",
        "abilityName": "EntryAbility",
        "srcEntries": ["../../skills/example-org-todo/scripts/TodoSkill.ets"],
        "version": "1.0.0"
      }
    ]
  }
}

二、核心点 2：入口脚本只做三件事——校验、调用、回传

我们用一个"记待办"的例子。假设你的 App 里已经有这样一个业务类：

// entry/src/main/ets/service/TodoStore.ets（演示用，真实项目请换成首选项或关系型数据库）
export interface TodoItem {
  id: number;
  title: string;
}

export class TodoStore {
  private static items: TodoItem[] = [];

  static add(title: string): TodoItem {
    const item: TodoItem = { id: TodoStore.items.length + 1, title: title };
    TodoStore.items.push(item);
    return item;
  }
}

Skill 入口脚本按官方约定来写：export default 一个类，每个 public async 方法对应 SKILL.md 里的一项能力，方法名与 functionName 严格一致，第一个参数固定为 ArkTSScriptInfo，结果通过 scriptManager.completeArkTSScriptInApp 回传 [4]：

// entry/skills/example-org-todo/scripts/TodoSkill.ets
import { scriptManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { TodoStore, TodoItem } from '../../../src/main/ets/service/TodoStore';

export default class TodoSkill {
  public async addTodo(info: scriptManager.ArkTSScriptInfo, ...argv: string[]): Promise<void> {
    // 1. 校验：按位置取参数，对照 SKILL.md 的 Schema
    const title: string = argv.length > 0 ? argv[0].trim() : '';
    if (title.length === 0) {
      const payload: Record<string, Object> = {
        'type': 'result',
        'status': 'failed',
        'errCode': 'ERR_INVALID_PARAMS',
        'errMsg': 'title is empty',
        'suggestion': '要帮你记下什么事呢？'
      };
      await this.report(info, { code: -1, result: payload });
      return;
    }

    try {
      // 2. 调用：直接复用已有业务代码
      const item: TodoItem = TodoStore.add(title);
      const data: Record<string, Object> = { 'id': item.id, 'title': item.title };
      const payload: Record<string, Object> = { 'type': 'result', 'status': 'success', 'data': data };
      await this.report(info, { code: 0, result: payload });
    } catch (e) {
      const err = e as BusinessError;
      const payload: Record<string, Object> = {
        'type': 'result',
        'status': 'failed',
        'errCode': 'ERR_INTERNAL',
        'errMsg': `${err.message}`,
        'suggestion': '没记上，稍后再试试'
      };
      await this.report(info, { code: -1, result: payload });
    }
  }

  // 3. 回传：唯一出口
  private async report(info: scriptManager.ArkTSScriptInfo, result: scriptManager.ExecuteResult): Promise<void> {
    try {
      await scriptManager.completeArkTSScriptInApp(info.context, info.requestCode, result);
    } catch (e) {
      const err = e as BusinessError;
      console.error(`completeArkTSScriptInApp failed, code: ${err.code}, message: ${err.message}`);
    }
  }
}

对应的 SKILL.md 骨架（完整写法还需要为每项能力补上参数和返回值的 JSON Schema，见官方指南 [4]）：

---
name: example-org-todo
description: 记录待办事项，响应"帮我记一下""提醒我做某事"等指令
---

## 触发场景
当用户明确要求**新增一条待办**时调用。典型话术：
- "帮我记一下明天交周报"
- "加个待办：买牛奶"
不调用的情况：
- "我今天有哪些待办"——意图是查询，本 Skill 只负责新增。

### 场景1：新增待办（addTodo）
执行参数：
```
exec-cli(command: ohos-arkTSScript --skillName 'example-org-todo' --scriptPath 'scripts/TodoSkill.ets' --functionName 'addTodo' --args '{"arg1": "明天交周报"}')
```

三、三个容易踩的坑

1. 三处名字必须一致：Skill 目录名、SKILL.md 的 name、module.json5 里 skillProfiles[].name [4]。名字建议加公司或组织前缀，防止冲突。
2. "不调用的情况"别偷懒：SKILL.md 是匹配的唯一依据，写清边界才能减少误触发。
3. 返回值要和契约一一对应：成功、参数错误、内部错误……每个分支都要在 SKILL.md 里声明，suggestion 字段会直接影响小艺怎么回复用户。

写完以后，按官方文档先"导入 Skill"上传 HAP，再上真机调试 [4]。

写在最后

HarmonyOS 6/7 设备已突破 8500 万，注册开发者超过 1100 万 [5]。当越来越多用户习惯"跟小艺说一句"，系统级智能入口可能就是下一个流量入口。好消息是，接入成本比想象中低：业务代码一行不改，加一份说明书、一层薄适配就行。

下一篇我们聊：意图、Skill、端侧 A2A，到底该接哪个？ 关注这个系列，跟上鸿蒙的每一次大版本更新。

参考来源

1. IT之家，《华为鸿蒙 HarmonyOS 7 系统最新适配进度公开》，2026-10-30
2. 华为官网，《关于 HarmonyOS 7 公共问题的相关说明》
3. 华为开发者文档，《方舟智能开发框架概述》
4. 华为开发者文档，《基于 ArkTS 脚本的应用 Skill 开发指导》（更新于 2026-09-30）
5. 华为新闻，《Agentic 时代，鸿蒙以系统级底座与 AI 开发平台，激活开发者创新盛放》，2026-09-19