HarmonyOS 7智能体Skill开发实战：契约设计与调度模拟器

鸿蒙专家

在HDC 2026上，HarmonyOS 7正式将智能体（Agent）提升为操作系统的一等公民。对开发者而言，最大的范式变化不再是“多一个AI入口”，而是开发重心从“写功能”转向“定义可被智能体调用的能力”。本文基于小艺开放平台与鸿蒙智能体框架（Agent Framework）的实踩经验，拆解智能体开发、Skill构建、能力接入与场景落地的关键做法，并附一份可直接运行的智能体调度模拟器。

一、框架认知：智能体=编排层+一组Skill
鸿蒙智能体框架向上承接小艺的意图框架（Intent Framework），向下通过工具调用（Tool Use）调度开发者注册的能力。智能体本身不“懂业务”，它负责规划、记忆与编排；真正落地的是被封装成一个个能力包（Skill）的企业能力。理解这一点是写好Skill的前提——你不是在写一个聊天机器人，而是在为智能体准备“可被信任调用的确定性工具”。一句话结论：智能体的“聪明”来自模型，智能体的“可靠”来自Skill。把确定性留给Skill，把不确定性的理解/生成留给模型，是鸿蒙Agent实践的核心心智。

二、Skill构建：先写“契约”，再写实现
一个有含金量的Skill，第一性原则是契约先行。一个Skill至少包含五个要素：name、description、params_schema、handler、domain。其中description是给模型看的语义说明（决定能否被准确路由），params_schema是给框架看的参数契约（决定能否被安全校验），handler才是真正的业务实现。三者分离，Skill才能被复用、被评测、被治理。
下面是一份金融域还款Skill的能力清单（JSON Manifest），它和代码里的Skill数据类一一对应：

2. {
3.   "skill": "repay_credit",
4.   "domain": "finance",
5.   "description": "为信用卡还款，需用户显式授权",
6.   "params": {
7.     "card_last4": { "type": "string", "required": true },
8.     "amount": { "type": "number", "required": true }
9.   },
10.   "auth": { "scope": "payment.write", "consent": "explicit" },
11.   "risk": "high"
12. }

复制代码

在鸿蒙应用中，用ArkTS声明并注册Skill的写法示意如下（对接真实后端Ability/REST）：

2. // OrderQuerySkill.ets —— 在鸿蒙应用中注册一个Skill（示意）
3. import { agentFramework } from '@kit.AgentFrameworkKit';
5. export class OrderQuerySkill {
6.   name = 'query_order';
7.   description = '查询用户订单状态与预计送达时间';
8.   params = [{ name: 'order_id', type: 'string', required: true }];
10.   async invoke(args: Record<string, Object>): Promise<Object> {
11.     const orderId = args['order_id'] as string;
12.     // 调用订单中心Ability或企业REST接口
13.     return await orderCenter.query(orderId);
14.   }
15. }
17. // 注册到小艺开放平台的智能体运行时
18. agentFramework.registerSkill(new OrderQuerySkill());

复制代码

三、能力接入：把企业系统“包”成可被调用的能力
能力接入的本质，是把既有系统（订单中心、支付网关、IoT中台、知识库）封装成带契约的Skill。常见反模式是直接在handler里写一堆业务分支——这会让Skill变成“第二个单体应用”。正确做法是：handler只做参数归一、授权校验、调用后端、结果结构化，复杂逻辑留在后端系统。这样Skill薄、稳定、可审计。

四、可执行的智能体调度模拟器
没有鸿蒙设备也能验证Skill设计与调度逻辑。下面这份Python脚本已实际运行通过，用纯Python复刻了框架的核心抽象：Skill数据类（含参数契约与校验）、HarmonyAgentFramework（注册+意图路由+调度兜底）。把它保存为harmony_agent_sim.py直接python harmony_agent_sim.py即可运行。

2. """
3. harmony_agent_sim.py —— 鸿蒙智能体框架最小可执行模拟器
4. 演示：Skill注册 → 意图路由 → 参数校验 → 工具调用编排闭环
5. 运行：python harmony_agent_sim.py
6. """
7. from __future__ import annotations
8. import json
9. from dataclasses import dataclass, field
10. from typing import Callable, Dict, Any
12. @dataclass
13. class Skill:
14.     name: str
15.     description: str
16.     domain: str = "general"
17.     params_schema: Dict[str, Any] = field(default_factory=dict)
18.     handler: Callable = lambda **k: None
20.     def validate(self, args: Dict[str, Any]) -> list:
21.         required = self.params_schema.get("required", [])
22.         return [p for p in required if p not in args]
24. class HarmonyAgentFramework:
25.     def __init__(self, agent_name: str = "XiaoYiAgent"):
26.         self.agent_name = agent_name
27.         self.skills: Dict[str, Skill] = {}
29.     def register(self, skill: Skill) -> None:
30.         self.skills[skill.name] = skill
31.         print(f"[注册] Skill '{skill.name}' 域={skill.domain} 已接入框架")
33.     def route(self, intent: str) -> Skill | None:
34.         for name, sk in self.skills.items():
35.             if name.lower() in intent.lower():
36.                 return sk
37.         domain_kw = {
38.             "finance": ["账单", "还款", "理财", "信用卡"],
39.             "retail": ["库存", "下单", "优惠券", "订单"],
40.             "home": ["灯", "空调", "窗帘"],
41.         }
42.         for sk in self.skills.values():
43.             for kw in domain_kw.get(sk.domain, []):
44.                 if kw in intent:
45.                     return sk
46.         return None
48.     def dispatch(self, intent: str, args: Dict[str, Any] | None = None) -> Dict[str, Any]:
49.         args = args or {}
50.         skill = self.route(intent)
51.         if not skill:
52.             return {"ok": False, "error": f"无匹配 Skill: {intent}"}
53.         missing = skill.validate(args)
54.         if missing:
55.             return {"ok": False, "error": f"缺少必填参数: {missing}", "skill": skill.name}
56.         try:
57.             return {"ok": True, "skill": skill.name, "result": skill.handler(**args)}
58.         except Exception as exc:
59.             return {"ok": False, "error": f"执行异常: {exc}", "skill": skill.name}
61. # 业务侧：把企业系统封装为Skill
62. def _query_order(**k):
63.     return {"order_id": k.get("order_id"), "status": "已发货", "eta": "2026-07-23"}
65. def _control_light(**k):
66.     return {"room": k.get("room"), "light": k.get("state"), "confirmed": True}
68. def _repay_credit(**k):
69.     return {"card_last4": k.get("card_last4"), "repaid": k.get("amount"), "channel": "小艺"}
71. def build_framework():
72.     fw = HarmonyAgentFramework()
73.     fw.register(Skill("query_order", "查询订单状态", "retail",
74.                       {"required": ["order_id"]}, _query_order))
75.     fw.register(Skill("control_light", "控制灯光", "home",
76.                       {"required": ["room", "state"]}, _control_light))
77.     fw.register(Skill("repay_credit", "信用卡还款", "finance",
78.                       {"required": ["card_last4", "amount"]}, _repay_credit))
79.     return fw
81. if __name__ == "__main__":
82.     fw = build_framework()
83.     for intent, args in [
84.         ("帮我查一下订单 NO20260722 到哪了", {"order_id": "NO20260722"}),
85.         ("把卧室的灯关掉", {"room": "卧室", "state": "off"}),
86.         ("还信用卡尾号 8821 共 3500 元", {"card_last4": "8821", "amount": 3500}),
87.         ("厨房灯打开但忘给房间", {"state": "on"}),
88.     ]:
89.         print(f"\n意图: {intent}\n → " + json.dumps(fw.dispatch(intent, args), ensure_ascii=False))

复制代码

运行结果：前三条意图分别命中query_order、control_light、repay_credit并返回结构化结果；第四条因缺少必填参数room被框架层校验拦截——这正是“把确定性交给Skill”的体现。

五、场景落地：能力包如何被智能体编排
同一套Skill底座，在不同行业被智能体编排成不同体验。关键不是“做了多少功能”，而是“智能体能否跨Skill完成一个完整任务”。例如金融场景“帮我看看这月账单并还款”，智能体需要先调用账单Skill、再调用还款Skill，并在高风险动作前请求显式授权。

六、避坑经验
description写太粗：模型靠它路由，要写清“何时用、输入输出什么”，避免两个Skill语义重叠导致误调。
参数契约不严格：高风险Skill（支付/设备控制）必须required齐全，并在框架层做类型与范围校验，宁可调人工也不盲动。
handler里塞业务：Skill应薄，逻辑留在后端，否则难以评测与回归。
没有评测集：把每条真实意图与人工修正沉淀为黄金样本，换模型或改提示词后重跑回归。
忽略权限与出境：敏感数据走端侧或授权通道，能力清单标注auth.scope与risk。
实践心法：先把一个Skill做“厚”（契约准、校验严、可回归），再让智能体把它“编排薄”——能力的确定性，才是Agent时代最稀缺的资产。

热心网友3

楼主这个帖子写得很实在，尤其是“先写契约再写实现”和“把确定性留给Skill、不确定性留给模型”这两句话，点到了当前AI+系统集成的核心痛点。很多开发者容易把注意力全放在模型效果上，反而忽略了被调用的能力本身是否可靠、是否可审计。你这份SysAgent模拟器代码也很实用，能给没有鸿蒙设备的开发者一个快速验证的思路。感谢分享！

热心网友3

很认同你提到的“确定性留给Skill”这个核心思想。在企业级开发里，模型理解错了可以重试，但Skill执行出偏差就会出大问题。你列出的那套契约先行、参数独立验证的流程，对金融和IoT这类对安全要求高的场景尤其重要。 另外，那个Python模拟器确实降低了验证Smartill逻辑的门槛——不用开Harmony开发环境就能先把调度链条跑通，对新手理解“编排层+能力包”的分工很有帮助。期待后续能多聊聊多Domain混合调度的契约冲突处理策略。

热心网友3

这份HarmonyOS 7智能体Skill开发的分享非常扎实，尤其是“契约先行”和“把确定性留给Skill”这两点，点出了当前AI能力落地的关键。通过先定义description、params_schema再写handler的思路，能有效避免Skill变成“黑盒”，也方便后续的维护和评测。 那个Python模拟器脚本也很实用，作为没有设备时的验证工具，能帮助快速调试路由和参数校验逻辑，降低了试错成本。文章整体有深度又接地气，对正在接触鸿蒙智能体框架的开发者很有参考价值。