元服务SKILL开发规范

app.json配置SKILLS

ascf/ascf_src/app.json配置skills分包和skills配置。一个元服务可声明多个SKILLs，并且一个独立分包也可以放置多个 SKILLs。

​app.json配置示例：

{
  "subPackages": [
    {
      "root": "skills",
      "pages": []
    }
  ],
  "agent": {
    "skills": [
      {
        "name": "flight-booking-skill",
        "description": "机票预订场景：搜索航班、查看详情、确认订单、支付订单完成预订",
        "path": "skills/flight-booking-skill"
      }
    ]
  }
}

SKILL.md需要带上YAML frontmatter，用于声明name和description：

---
name: flight-booking-skill
description: 机票预订场景：搜索航班、查看详情、确认订单、支付订单完成预订

---

SKILL规范

元服务SKILL需要遵从 HarmonyOS Skill开发规范 。主要有如下差异点：

[h2]SKILL中需对于mcp.json中定义的原子接口做工具调用示例说明

## Function: GetFlightPrice
- **toolName**: GetFlightPrice
- **bundleName**: com.atomicservice.xxx
- **description**: 获取低价航班日历（航班价格趋势卡片）。用户想看某条航线一段时间内每天最低价（如「几天飞最便宜」「未来一个月低价日历」）时调用。仅返回价格日历，不含具体航班明细。
- **参数**: {"type":"object","properties":{"end":{"type":"String","description":"日历结束日期 YYYY-MM-DD，须不早于 start；未传时默认 start 起共7天"},"fromCity":{"type":"String","description":"出发城市名称"},"toCity":{"type":"String","description":"到达城市名称"},"date":{"type":"String","description":"出发日期 YYYY-MM-DD"},"start":{"type":"String","description":"日历开始日期 YYYY-MM-DD；相对时间须先转具体日期；未传时默认明天"}},"required":["fromCity","toCity"]}
- **调用方式**：invoke(functionName:"GetFlightPrice", arguments:{bundleName:"com.atomicservice.xxx", appId:"xxx", skillName:"flight-skill", apiName:"getFlightPrice", renderAtomicCard:true, componentName:"flight-skill_flight-price-card", query:"<用户的语料>", fromCity:"<出发城市>", toCity:"<到达城市>", start:"<YYYY-MM-DD 可选>", end:"<YYYY-MM-DD 可选>"})

[h2]SKILL中支持显示 invoke 调用原子接口

invoke(functionName:"SearchFlights", arguments:{bundleName:"com.atomicservice.xxx", appId:"xxx", skillName:"flight-skill", apiName:"searchFlights", renderAtomicCard:true, componentName:"flight-skill_flight-card", args:{query:"<用户的语料>", departure:"<出发城市，未说明留空>", destination:"<目的城市，无flightNumber时必填>", flightNumber:"<航班号，可选>", departDateTime:"<YYYY-MM-DD>"},query:"<用户的语料>"})

其中renderAtomicCard参数控制是否原子组件，默认为true。

[h2]SKILL中支持renderAtomicCard渲染原子组件

```renderAtomicCard
{"appId": "xxx", "skillName": "flight-skill", "componentName": "flight-skill_flight-card", "abilityDatas": {"structuredContent": <全量原始数据>, "_meta": <插件返回的 _meta 元数据，原样透传>}, "componentPath": "<卡片组件路径>"}
```

为了提升推理性能，需尽量减少structuredContent的内容，可以用关键信息和索引结合。

mcp.json 声明原子接口和关联的原子组件

[h2]原子接口声明

mcp.json 包含所有原子接口的 Schema 声明。

{
  "apis": [
    {
      "name": "SearchFlights",
      "description": "搜索航班",
      "inputSchema": {
        "type": "object",
        "properties": {
          "departure": {
            "type": "string",
            "description": "【位置】出发城市或机场"
          },
          "destination": {
            "type": "string",
            "description": "【位置】目的城市或机场"
          },
          "departDateTime": {
            "type": "string",
            "description": "出发日期，格式 YYYY-MM-DD"
          }
        }
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "flights": {
            "type": "array",
            "description": "航班列表；可基于已返回结果筛选/排序后更新",
            "items": {
              "type": "object",
              "properties": {
                "flightNo": { "type": "string", "description": "航班号" },
                "price": { "type": "number", "description": "票价" }
              }
            }
          },
          "total": {
            "type": "number",
            "description": "航班总数"
          },
          "hasMore": {
            "type": "boolean",
            "description": "是否显示「查看更多」入口；仅 total>3 时为 true；Agent 回复只说明条数，勿引导用户点击「查看更多」"
          }
        }
      },
      "_meta": {
        "ui": {
          "componentPath": "components/flight-card/index"
        }
      }
    }
  ]
}

[h2]原子组件声明

在mcp.json的components字段下可以声明原子组件的额外配置：

[h2]原子接口返回值结构

原子接口的返回值包含以下字段：

其中isError、structuredContent、content三个字段的数据会作为 LLM 的上下文供其理解，而 _meta内容对 LLM 不可见，用于携带私有数据传递给原子组件。

content 目前仅支持1个ITextContent：

interface ITextContent {
  type: "text";
  text: string;
}

[h2]原子接口正常与异常流程

当isError: true时，不进行卡片渲染，structuredContent将被忽略，content常用于异常流程的引导。

当isError: false且该原子接口绑定了原子组件时，智能体将倾向于渲染卡片。structuredContent数据会传给原子组件用来渲染（便于模型理解卡片内容），content用于后续流程引导。

实现示例

在原子接口的内部实现中，可以通过has.request从服务器请求数据，也可以调用项目自身封装的服务获取数据。

async function getStores({ location }) {
  // 原子接口内部实现，此处省略
  // has.request({ url: 'https://www.example.com/xx' })

  return {
    isError: false,
    content: [{ type: "text", text: "已为您查询附近门店" }],
    structuredContent: {
      location: "深圳",
      stores: [
        { name: "坂田 1 店", address: "xxx", code: "001" },
        { name: "坂田 2 店", address: "xxx", code: "002" },
      ]
    },
    _meta: {}
  }
}

[h2]注册原子接口

在SKILL的index.js中通过has.modelContext.registerAPI注册原子接口。当智能体发起调用时，会在注册列表中找到对应的函数入口并执行：

const searchFlights = require('./apis/searchFlights.js');

const skill = has.modelContext.createSkill('skills/flight-booking-skill');

skill.registerAPI('SearchFlights', searchFlights);

[h2]skill.use注册中间件

为方便在项目侧统一封装接口注册、登录校验、埋点上报和错误处理逻辑，避免相同逻辑散落在每个原子接口中，我们提供了中间件能力。

// 1. 创建 skill，需与 app.json 中保持一致
const searchFlights = require('./apis/searchFlights.js');

const skill = has.modelContext.createSkill('skills/flight-booking-skill');

// 2. 可用 skill 注册 API，通过这种方式的注册才会走到中间件
skill.registerAPI('SearchFlights', searchFlights);

// 3. 注册中间件
skill.use(async (ctx, next) => {
  // 登录校验
  const token = has.getStorageSync({ key: 'token'});
  if (!token) {
    // 执行登录操作
    // 也可以直接抛出错误，让 Agent 决定其他操作
    // throw new Error('登录过期，接下来自动执行 login 工具')
  }
  await next()  // 执行实际 handler
});

• 只有通过skill注册API才会走到中间件。
• 中间件ctx类型：

interface IModelContextMiddlewareContext {
  name: string    // 当前执行的原子接口名
  skillPath: string    // 当前中间件执行时的 skillPath
  arguments: Record<string, any>    // 原子接口的入参
}

• next()前接口调用的前置逻辑，next()后是后置逻辑，try/catch包裹可捕获错误。

原子组件

原子组件用于承接原子接口返回的数据和内容展示。使用与元服务的自定义组件相同编码风格。通过has.modelContext.getContext / getViewContext获取渲染所需的尺寸、数据等信息。原子组件与ASCF框架的组件采用类似范式开发，元服务SKILL模式下运行采用了全新的原生渲染机制，能力与ASCF框架普通模式下有差异，需避免兼容性问题。当前支持的基础组件如下：

原子组件的运行环境与原子接口隔离，处于不同的上下文中，可调用的接口能力也有所不同。

功能和约束如下：

• 渲染区域有限：宽度随屏幕变化，需要支持宽度自适应和深色模式适配。

• 初始化时决定卡片高度，后续不可再改变。

• 默认不支持网络请求，需声明为「实时动态组件」。

• 默认不支持定时器接口，如 setTimeout、setInterval，需声明为「实时动态组件」。

• 支持点击后帮用户上行一条文本消息（ModelContext.sendFollowUpMessage），效果等同于用户发送一条文本消息。

• 支持点击后打开半屏页面。

原子组件中的 CSS 仅支持少量选择器：

• 类选择器 .cls {}；

• ID 选择器 #id {}；

• 标签名选择器 view {}；

• 后代选择器（空格分隔）；

[h2]元服务关联页

原子组件渲染出来的卡片左上方是标题栏，右上方提供了进入元服务关联页的按钮。点击按钮默认进入配置关联页面。在mcp.json中声明关联页面。

{
  "apis": [],
  "components": [
    {
      "path": "components/flight-list-card/index",
      "relatedPage": "/pages/index/index",
      "relatedPageLabel": "打开元服务"
    }
  ]
}

关联页接受query参数：

Page({
  onLoad(query) {
    console.info(query);
  }
})

• setRelatedPage 支持path字段，动态指定跳转的关联页面。
• 每次进行setRelatedPage，内部path和query都会进行重置，若不传path，则默认重置为json中配置的关联页。

[h2]适配深色模式

媒体查询仅支持深色模式：

@media (prefers-color-scheme: dark) {
    /* DarkMode 下的样式 */
}

支持onThemeChange 和 offThemeChange监听深色模式切换：

// 注册监听
has.onThemeChange((res) => {
  console.info('主题变化:', res.theme)  // 'light' 或 'dark'
})

// 注销监听
has.offThemeChange()

[h2]适配屏幕宽度

折叠屏场景下，原子组件宽度会动态变化，需监听原子组件宽度变化做适配。尤其是canvas场景必须要适配：

Component({
  pageLifetimes: {
    resize(res) {
      res.size.windowWidth // 新的显示区域宽度
      res.size.windowHeight // 新的显示区域高度
    }
  }
})

[h2]开发原子组件

一般位于skills目录中components下开发组件，监听NotificationType.Result获取数据：

Component({
  lifetimes: {
    created() {
      const { NotificationType } = has.modelContext;
      const ctx = has.modelContext.getContext(this);
      const vCtx = has.modelContext.getViewContext(this);
      ctx.on(NotificationType.Result, (data) => {
        const id = data.result.id;
        // 在原子组件渲染时动态设置 query 参数
        vCtx.setRelatedPage({ query: `id=${id}` });
      });
    }
  },
})

[h2]组件过期

提供两种粒度的过期接口：

方式一：has.modelContext.expireAllCards()

可在原子接口或组件里调用。所有声明了expirable: true的组件将被标记为过期并渲染蒙层。

// 过期所有可过期卡片
has.modelContext.expireAllCards();

// 按 componentPath 过滤
has.modelContext.expireAllCards({
  componentPaths: ['components/flight-list-card/index']
});

// 只过期最近一张匹配的卡片
has.modelContext.expireAllCards({
  componentPaths: ['components/flight-list-card/index'],
  match: 'latest'
});

方式二：vCtx.expirePreviousCards()

只能在原子组件里调用，将当前组件之前渲染过并声明了expirable: true的组件标记为过期。

const viewCtx = has.modelContext.getViewContext(this);

viewCtx.expirePreviousCards()

// 按 componentPath 过滤
viewCtx.expirePreviousCards({
  componentPaths: ['components/flight-list-card/index']
})

// 只过期最近一张匹配的卡片
viewCtx.expirePreviousCards({
  componentPaths: ['components/flight-list-card/index'],
  match: 'latest'
})

[h2]拉起半屏页面

当需要展示更多详细信息或需要用户补充信息时，可通过原子组件上按钮引导用户打开半屏页面完成。半屏页面与元服务环境基本一致，不允许任何跳转行为。当完成指定任务，需要进行下一步操作时，可通过半屏里的按钮触发一段上行文本消息，此时会同步关闭半屏页面回到智能体界面，智能体将继续处理新的用户请求。

在原子组件内点击并打开半屏页面：

<view onTap="handleOpenMore">查看更多</view>

Component({
  methods: {
    handleOpenMore() {
      const vCtx = has.modelContext.getViewContext(this);
      vCtx.openDetailPage({
        url: '/pages/detail/index?id=xxx'
      })
    }
  }
})

[h2]ASCF元服务中发送上行消息和更新卡片

在半屏页面中可通过接口代用户以第一人称视角发送一条上行文本消息，之后会自动关闭半屏页面。

Page({
  onTap() {
    const ctx = has.modelContext.getContext();
    ctx.sendFollowUpMessage({
      content: [
        {
          type: 'text',
          text: '选择商品'
        },
        {
          // 指定下一步应调用哪个原子接口
          type: 'api/call',
          data: {
            name: 'selectGoods',
            arguments: {}
          }
        }
      ]
    });
  }
})

[h2]更新卡片

打开半屏页面操作后，有时需要更新卡片，支持通过重新调用对应的原子接口的方式，来重新渲染原子组件。

const ctx = has.modelContext.getContext();

ctx.reapplyApiCall({
  arguments: {
    city: '深圳'
  }
});

[h2]ASCF元服务中H5中发送上行消息和更新卡片

若半屏页面是个web-view加载的H5页面，也可通过相同的方式发送上行。

// html页面中发送消息：
// post sendFollowUpMessage message
has.ascfweb.postMessage({
  options: { mode: 'realtime' },
  data: {
    type: 'sendFollowUpMessage',
    args: {
      content: [
        { type: 'text', text: '选择智利火山酒庄火魂红葡萄酒' },
        { type: 'api/call', data: { name: 'selectProduct', arguments: '{"drinkId":10774}' } }
      ]
    }
  },
});

// post reapplyApiCall message
has.ascfweb.postMessage({
  options: { mode: 'realtime' },
  data: {
    type: 'reapplyApiCall',
    args: {
      arguments: {
        name: 'searchDrinks',
        arguments: '{"keyword": "葡萄酒"}'
      }
    }
  },
});


// 监听h5中的事件
// <web-view src="resource://rawfile/html/index.html" bindmessage="handleMsg"></web-view>
Page({
  handleMsg(e) {
    const ctx = has.modelContext?.getContext?.();
    const data = e.detail?.data?.[0];
    if (!ctx || !data) {
      return;
    }
    // 发送上行消息
    if (data.type === 'sendFollowUpMessage' && data.args) {
      ctx.sendFollowUpMessage(data.args);
    } else if (data.type === 'reapplyApiCall' && data.args) {
      ctx.reapplyApiCall(data.args);
    }
  },
});

[h2]ArkUI元服务以及H5中发送上行消息和更新卡片

对于ArkUI元服务，需要依赖ASCF框架提供的接口能力。

// entry\src\main\ets\entryability\EntryAbility.ets
import { AtomicServiceAI } from '@atomicservice/ascfapi';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    AtomicServiceAI.getInstance().ensureInit(this.context, want);
  }

  onDestroy(): void {
    AtomicServiceAI.getInstance().cleanup();
  }

  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    AtomicServiceAI.getInstance().ensureInit(this.context, want);
  }
}

// 使用说明
import { AtomicServiceAI } from '@atomicservice/ascfapi';

AtomicServiceAI.getInstance().sendFollowUpMessage({
  content: [
    { type: 'text', text: '选择智利火山酒庄火魂红葡萄酒' },
    { type: 'api/call', data: { name: 'selectProduct', arguments: '{"drinkId":10774}' } }
  ]
});

对于ArkUI元服务中的H5页面，通过AtomicServiceEnhancedWeb双向通信机制，可以实现半屏通信功能。详细示例如下：

html页面中发送消息：

// post sendFollowUpMessage message
has.asWeb.postMessage({
  options: { mode: 'realtime' },
  data: {
    type: 'sendFollowUpMessage',
    args: {
      content: [
        { type: 'text', text: '选择智利火山酒庄火魂红葡萄酒' },
        { type: 'api/call', data: { name: 'selectProduct', arguments: '{"drinkId":10774}' } }
      ]
    }
  },
});

// post reapplyApiCall message
has.asWeb.postMessage({
  options: { mode: 'realtime' },
  data: {
    type: 'reapplyApiCall',
    args: {
      arguments: {
        name: 'searchDrinks',
        arguments: '{"keyword": "葡萄酒"}'
      }
    }
  },
});

webview中监听消息并且处理：

AtomicServiceEnhancedWeb({
  src: $rawfile("html/index.html"),
  controller: this.controller,
  onMessage: (event: OnMessageEvent) => {
    const payload = event.data?.[0] as Record<string, object>; // 注意转换类型
    if (payload?.type === 'sendFollowUpMessage') {
      AtomicServiceAI.getInstance().sendFollowUpMessage(payload.args);
    } else if (payload?.type === 'reapplyApiCall') {
      AtomicServiceAI.getInstance().reapplyApiCall(payload.args);
    }
  }
})

原子接口和原子组件 API 支持列表

在元服务SKILL下，原子接口、原子组件、半屏详情页都有一定的限制。

[h2]原子接口新增 API

• 创建 Skill：has.modelContext.createSkill(skillPath)
• 注册原子接口：skill.registerAPI(name, handler)
• 注册中间件：skill.use(async (ctx, next) => {})

[h2]原子组件新增 API

Context

• 获取上下文：has.modelContext.getContext(this)
• 支持Result。
• 移除监听：ctx.off(type, callback?)
• callback非必传，此时将移除该类型下所有监听。
• 发送上行消息：ctx.sendFollowUpMessage({ content })

ViewContext

• 获取视图上下文：has.modelContext.getViewContext(this)
• 支持Overflow、Resize、Expire。
• 移除监听：viewCtx.off(type, callback?)
• callback非必传，此时将移除该类型下所有监听。
• 获取卡片尺寸：viewCtx.getDimensions()
• 打开半屏详情页：viewCtx.openDetailPage({ url })

[h2]原有 API 支持情况

原有元服务 API 在元服务SKILL下并不是全部可用，不同运行环境支持的接口有所不同，支持情况如下表。

若某个分类下的API都支持，细分API则不会全部列出，请跳转到接口文档查看。

[h2]半屏页面能力支持列表

选择联系人或者收货地址等功能，可以直接基于元服务的页面通过半屏嵌入运行，实现功能闭环。

半屏页面运行环境基本等价于元服务环境，但是也有一些区别，半屏页面不建议路由跳出，建议直接完成任务后关闭返回。半屏可以通过has.modelContext与对话流直接交互，例如获取上下文：has.modelContext.getContext()，上行消息 ctx.sendFollowUpMessage({ content }) 、更新卡片ctx.reapplyApiCall({ arguments })。

当前半屏页面页面暂时没有做接口能力约束，后续可能会变更。

[h2]实现账号登录与隐私授权

元服务SKILL中账号体系与元服务是互通，支持使用has.login和has.getPhoneNumber实现 静默登录功能。暂不支持使用storage互通数据。

has.login和 has.getPhoneNumber等接口会自动触发隐私弹框授权，当用户授权通过后才会继续执行，否则会接口调用异常，走异常处理流程。为了实现更好的交互体验，建议非必要情况下提供游客模式接口，避免登录后触发权限授权弹框。可以参考如下示例处理：

// 可以根据是否需要隐私授权状态判断，是否已经授权过，当前调用 has.login 才会触发授权
if (has.getPrivacySetting().needAuthorization) {
  // 调用游客模式接口，避免触发隐私弹框授权
} else {
  // 已授权后 has.login 静默登录
  // 非必要情况下，不要额外获取手机号，让半屏进入到元服务后处理
}