【HarmonyOS 7新能力｜002】Skill Vibe Coding入门实战：从能力边界到最小可运行链路

贾伟康

14093人浏览 · 2026-09-10 00:10:48

贾伟康 · 2026-09-10 00:10:48 发布

【HarmonyOS 7新能力｜002】Skill Vibe Coding入门实战：从能力边界到最小可运行链路

Skill Vibe Coding 入门实战

HarmonyOS 7 的智能化能力让“用自然语言描述需求，再快速形成 Skill”成为值得关注的开发方式。但真正进入工程阶段后，最容易出现的误解是：把一次生成成功当成一个 Skill 已经可用。生成只能缩短从零到骨架的时间，不能自动证明权限正确、数据安全、异常可控、结果可信，更不能代表已经完成真机验证或平台审核。

本文围绕一个最小示例展开：用户输入一个待办事项，Skill 校验内容后写入应用侧服务，并返回结构化结果。重点不在展示某个尚未核实的官方接口，而在于建立一条可复用、可测试、可审计的工程链路。文中的接口与类型均为应用侧建议设计，不等同于华为平台 API；平台事实以文末官方资料为准。

一、先明确 Skill Vibe Coding 能解决什么

它最适合解决的是“把意图快速变成可讨论的工程骨架”。开发者可以用自然语言表达场景、输入、输出和约束，让工具协助生成配置、数据结构、处理步骤或测试草案。它能减少重复搭架子的工作，但不能替开发者做最终判断。

一个可交付 Skill 至少包含五类信息：它为什么存在、接受什么输入、允许调用什么能力、返回什么结果、失败时如何解释。如果提示词只写“帮我生成一个待办 Skill”，生成器通常只能猜测字段、权限和错误处理方式。猜对一次不等于设计稳定，尤其当需求涉及账号、定位、文件、网络或敏感信息时，模糊描述会直接放大合规风险。

因此，第一条边界是：自然语言负责表达意图，明确的契约负责限制实现。第二条边界是：生成结果只能进入评审，不能直接进入生产。第三条边界是：平台能力是否开放、需要什么配置、支持哪些设备，必须回到当前版本官方文档和开发者控制台核对。

二、把模糊需求改写成可验证任务

“创建待办”看起来简单，实际还缺少大量决定。内容能否为空？最大长度是多少？是否允许重复？保存失败怎样反馈？是否需要网络？用户取消后是否继续写入？如果这些问题不提前回答，代码生成后仍要反复返工。

建议把需求写成下面这种结构：

场景：用户通过系统智能入口创建一条本地待办。
输入：title，去除首尾空格后长度为 1～80 个字符。
输出：taskId、normalizedTitle、createdAt。
依赖：仅调用应用内 TaskService，不直接操作存储。
失败：区分参数错误、重复提交、存储失败、用户取消和超时。
隐私：不上传内容，不记录完整输入日志。
验收：正常、空输入、超长、重复点击、写入失败均有确定结果。

这段说明的价值不是“写得像提示词”，而是把验收条件提前。生成器产生的任何代码都可以逐项对照：字段不一致就修改，越权访问就删除，缺失异常路径就补齐。团队也能用同一份说明评审产品、开发、测试和隐私边界。

从需求到人工验收的六步流程

三、先定义输入输出契约，再生成实现

在 ArkTS 应用侧，建议使用显式类型承载请求与结果。下面是演示用的领域契约，不是平台接口：

interface CreateTaskInput {
  requestId: string
  title: string
  source: 'system_entry' | 'in_app'
}

interface CreateTaskData {
  taskId: string
  normalizedTitle: string
  createdAt: number
}

type SkillErrorCode =
  | 'INVALID_ARGUMENT'
  | 'DUPLICATE_REQUEST'
  | 'USER_CANCELLED'
  | 'TIMEOUT'
  | 'STORAGE_FAILURE'
  | 'UNKNOWN'

interface SkillResult<T> {
  ok: boolean
  data?: T
  errorCode?: SkillErrorCode
  message: string
}

显式契约有三个好处。第一，生成器不能随意改变字段名，页面、编排层和服务层围绕同一结构协作。第二，错误成为稳定数据，而不是散落在异常字符串里。第三，后续对接真实平台入口时，只需要增加适配层，不必重写业务核心。

requestId 不能省略。系统入口、语音交互或用户连续点击都可能产生重复请求，如果没有幂等标识，同一待办可能被写入多次。source 也有价值，它帮助应用区分系统入口和应用内入口，但日志中不应记录用户的完整待办内容。

四、四层结构隔离生成代码与真实能力

推荐把 Skill 链路拆为场景层、编排层、能力层和平台层。场景层只表达用户目标与最终反馈；编排层组织步骤、超时、取消和状态；能力层校验输入并调用领域服务；平台层封装真实运行环境和系统能力。

Skill 的四层建议结构

这种拆分可以防止两个常见问题。其一，生成器把存储、网络或平台调用直接写进页面，导致权限、测试和生命周期混在一起。其二，未来平台接口或开放范围变化时，业务逻辑被迫整体重写。把平台差异放在适配器中，领域服务仍可以用普通单元测试验证。

一个建议目录如下：

features/task-skill/
  model/CreateTaskContract.ets
  orchestration/CreateTaskOrchestrator.ets
  service/TaskService.ets
  adapter/SkillRuntimeAdapter.ets
  test/CreateTaskOrchestrator.test.ets

目录名称可以跟随现有项目调整，重要的是依赖方向：场景调用编排，编排调用服务或窄接口，适配器实现平台边界；服务不反向依赖页面。

五、参数校验必须发生在能力调用之前

生成代码常见的坏味道是先调用服务，失败后再判断输入是否合法。正确顺序应当是标准化、校验、幂等检查、执行、映射结果。示例：

class CreateTaskValidator {
  validate(input: CreateTaskInput): SkillResult<string> {
    const title = input.title.trim()
    if (input.requestId.trim().length === 0) {
      return { ok: false, errorCode: 'INVALID_ARGUMENT', message: '缺少请求标识' }
    }
    if (title.length === 0 || title.length > 80) {
      return { ok: false, errorCode: 'INVALID_ARGUMENT', message: '待办标题应为1～80个字符' }
    }
    return { ok: true, data: title, message: '校验通过' }
  }
}

这里还可以根据业务增加控制字符过滤、敏感字段限制或本地化规则，但不要为了“看起来安全”随意删除用户文本。每一条转换都应有明确原因和测试用例。对于身份证号、联系方式、健康数据等敏感信息，应重新评估该 Skill 是否真的需要接收，而不是在日志里简单打码后继续收集。

六、编排层要处理重复、超时和取消

最小链路也不能只有一个 loading 布尔值。系统入口可能在页面尚未打开时发起，用户可能中途取消，存储可能失败，重复请求也可能在第一次完成前到达。建议使用明确状态：

type RunState =
  | 'idle'
  | 'validating'
  | 'running'
  | 'success'
  | 'failed'
  | 'cancelled'
  | 'timeout'

编排器只依赖窄服务接口：

interface TaskWriter {
  create(title: string, requestId: string): Promise<CreateTaskData>
}

class CreateTaskOrchestrator {
  constructor(private readonly writer: TaskWriter) {}

  async run(input: CreateTaskInput): Promise<SkillResult<CreateTaskData>> {
    const checked = new CreateTaskValidator().validate(input)
    if (!checked.ok || !checked.data) return { ok: false, errorCode: checked.errorCode, message: checked.message }

    try {
      const data = await this.writer.create(checked.data, input.requestId)
      return { ok: true, data, message: '待办已创建' }
    } catch (error) {
      return this.mapError(error)
    }
  }

  private mapError(error: Object): SkillResult<CreateTaskData> {
    const message = `${error}`
    if (message.includes('duplicate')) return { ok: false, errorCode: 'DUPLICATE_REQUEST', message: '该请求已处理' }
    return { ok: false, errorCode: 'STORAGE_FAILURE', message: '保存失败，请稍后重试' }
  }
}

示例为了突出结构而简化了超时与取消实现。真实工程中应由统一的任务控制器管理计时和取消信号，避免多个模块各自创建计时器。取消后必须阻止迟到结果覆盖页面状态；超时也不代表底层任务一定停止，因此写入操作仍要具备幂等性。

七、工具调用要使用白名单和最小参数

如果 Skill 可以调用多个应用能力，不要让生成器依据任意字符串动态选择方法。应建立工具白名单，每个工具都有稳定名称、输入类型、权限前提和错误映射。比如待办示例只开放 createTask，不顺便暴露删除全部、导出文件或读取历史记录等能力。

工具适配器还应负责三件事：把平台输入转换为领域契约；只传递业务需要的字段；把平台异常转换为内部错误码。不要把原始异常、令牌、路径或用户内容直接返回到界面，更不能上传到分析服务而不披露。

当 Skill 需要网络、定位、相机、麦克风、文件或账号能力时，必须重新核对模块声明、运行时授权、拒绝路径、隐私政策和实际行为。自然语言生成不会自动保证这些材料一致。

八、测试重点是边界，不是只跑通一次

最小测试集至少包括：正常标题成功写入；空白标题被拒绝；81个字符被拒绝；同一 requestId 重复提交只产生一条记录；服务异常被映射为稳定错误；用户取消后不显示成功；超时后迟到结果不覆盖状态。

可以用假服务验证编排逻辑：

class FakeTaskWriter implements TaskWriter {
  calls: string[] = []

  async create(title: string, requestId: string): Promise<CreateTaskData> {
    if (this.calls.includes(requestId)) throw new Error('duplicate')
    this.calls.push(requestId)
    return { taskId: 'task-001', normalizedTitle: title, createdAt: 1700000000000 }
  }
}

测试数据应固定，断言应围绕契约，而不是依赖当前页面文案。平台适配器另做集成测试，真机再验证入口、权限、前后台切换、重复唤起和异常恢复。没有真机证据时，只能写“静态检查通过”或“本地逻辑测试通过”，不能写成“已完成系统联调”。