【HarmonyOS 7新能力｜027】Skill Vibe Coding工程封装：把接入逻辑放进可维护的分层结构

用自然语言快速描述一个 Skill 很容易，难的是把它变成可预测、可调测、可审核的产品能力。若意图边界模糊、槽位缺失时直接执行、权限声明与代码行为不一致，演示中的“聪明”就会在真实使用中变成误触发和越权风险。

本文把 Skill 开发拆成场景、契约、编排、能力、治理和交付六层，贯通开发、调测、审核与上架准备。文中的清单、类型和目录是应用侧工程示例，不代表 HarmonyOS 7 Skill Vibe Coding 的官方接口或上架字段；实际能力、审核规则和材料要求应以当前工具链及华为官方文档为准。本文只讨论准备流程，不执行真实上架。

一、从单一可验证场景开始

不要用“帮用户处理日常事务”作为第一版目标。它无法确定何时触发、需要哪些数据以及怎样算成功。更好的定义是“用户明确要求查询一条本地记录时，按日期和分类筛选并返回最多五项结果”。

第一版验收条件包括：典型表达能命中；相似但不属于本能力的表达不会误触发；必填槽位缺失时追问；无权限时停止；结果结构固定；取消后不继续执行；异常时提供可恢复提示。

二、把意图写成机器可检验契约

契约包含意图名、触发表达、负样本、槽位、输出和权限。自然语言描述只帮助理解，运行时仍需结构化约束。

interface IntentContract {
  name: string
  version: number
  requiredSlots: ReadonlyArray<string>
  optionalSlots: ReadonlyArray<string>
  permissions: ReadonlyArray<string>
  risk: 'read' | 'write' | 'external'
}

const queryContract: IntentContract = {
  name: 'queryLocalRecord', version: 1,
  requiredSlots: ['dateRange'], optionalSlots: ['category', 'limit'],
  permissions: [], risk: 'read'
}

契约版本进入测试用例和交付包，避免代码变化后仍沿用旧测试结论。

三、槽位必须有来源和置信边界

同一个值可能来自用户原话、上下文推断或默认值。执行前应记录来源，并对高风险槽位要求显式确认。

type SlotSource = 'explicit' | 'context' | 'default'

interface SlotValue<T> {
  value: T
  source: SlotSource
  confidence: number
}

interface QuerySlots {
  dateRange?: SlotValue<string>
  category?: SlotValue<string>
  limit?: SlotValue<number>
}

必填槽位不存在或置信度不足时进入追问状态，而不是猜一个值后执行。默认值需要在结果中可解释。

四、用状态机编排多轮对话

Skill 不应靠多个布尔值判断进度。状态机明确区分识别、补槽、确认、执行、完成、失败和取消。

type SkillState =
  | 'recognizing'
  | 'collecting-slots'
  | 'confirming'
  | 'executing'
  | 'completed'
  | 'failed'
  | 'cancelled'

interface SkillSession {
  id: string
  state: SkillState
  revision: number
  startedAt: number
  deadlineAt: number
}

每次用户修改条件都增加 revision。旧请求返回时若版本不匹配，结果被丢弃，防止上一轮查询覆盖新一轮条件。

五、能力适配器隔离平台与业务

编排层不直接调用数据库、网络或系统 Kit，而是依赖窄接口。适配器完成权限、参数转换、错误映射和取消传递。

interface RecordQuery {
  startAt: number
  endAt: number
  category?: string
  limit: number
}

interface RecordItem {
  id: string
  title: string
  occurredAt: number
}

interface RecordPort {
  query(input: RecordQuery, signal: AbortSignal): Promise<ReadonlyArray<RecordItem>>
}

这样沙箱可注入假适配器复现空数据、超时和权限失败，无需依赖真实用户数据。

六、分层架构约束副作用

场景层描述用户任务与入口；契约层定义意图、槽位、输出和权限；编排层管理确认、取消、重试；能力层接入领域服务；治理层执行安全和隐私检查；交付层生成报告与材料。

依赖只能朝向抽象：页面不持有平台能力对象，契约不依赖具体 UI，审核材料从版本化事实生成，不能与实际代码各写一套。

七、输出也必须经过契约校验

能力调用成功不等于 Skill 可以直接回复。输出需要检查类型、数量、敏感字段和用户可理解性。

interface SkillResult {
  status: 'ok' | 'empty' | 'partial'
  items: ReadonlyArray<RecordItem>
  explanation: string
}

function validateResult(result: SkillResult): boolean {
  return result.items.length <= 5 && result.items.every((item) => item.id.length > 0 && item.title.length > 0)
}

禁止把内部路径、令牌、异常栈或未声明字段放入回复。部分成功要明确标记，不能伪装成完整结果。

八、重试只处理真正的瞬时失败

网络抖动或暂时不可用可以有限重试；槽位缺失、权限拒绝、参数非法和审核策略拦截不应重试。写操作只有具备幂等键时才允许自动重试。

interface RetryRule {
  maxAttempts: number
  retryableCodes: ReadonlySet<string>
  baseDelayMs: number
}

function canRetry(rule: RetryRule, code: string, attempt: number): boolean {
  return attempt < rule.maxAttempts && rule.retryableCodes.has(code)
}

达到上限后返回可解释失败，并保留用户重新发起的入口。

九、沙箱调测覆盖正负样本

每个意图至少准备典型命中、口语变体、槽位缺失、歧义表达、相邻意图和明确负样本。只测试“标准问法”会高估识别效果。

interface IntentCase {
  utterance: string
  expectedIntent: string | null
  expectedMissingSlots: ReadonlyArray<string>
  shouldConfirm: boolean
}

测试结果记录契约版本、模型或运行环境版本、实际意图、实际槽位和失败原因，使回归差异可定位。

十、安全与隐私审查前置

权限必须与真实代码行为一致。能不收集的数据不收集，能在本地处理的数据不外发，日志不记录完整原话、凭据和个人内容。任何外部提交、删除、支付等动作都要有明确用户确认。

interface GovernanceDecision {
  allowed: boolean
  reasonCode: 'OK' | 'NO_PERMISSION' | 'CONSENT_REQUIRED' | 'DATA_EXCESSIVE' | 'POLICY_BLOCKED'
  requiredAction?: string
}

治理结果是执行门禁，而不是事后报告。未通过时能力适配器不得启动。

十一、交付材料从事实生成

Skill 名称、版本、意图、权限、数据用途、测试范围和已知限制应来自同一份版本化清单。截图和示例对话必须对应真实可复现行为，不夸大能力。

interface ReleaseEvidence {
  contractVersion: number
  testCaseCount: number
  passedCount: number
  permissionDiffClean: boolean
  privacyReviewPassed: boolean
  knownLimitations: ReadonlyArray<string>
}

生成包不等于已上架，提交审核也不等于审核通过。每个阶段要单独记录，本文不执行不可逆提交。

十二、用失败注入完成验收

最终回归覆盖：歧义误触发、必填槽位缺失、上下文过期、用户中途改口、取消后迟到结果、权限拒绝、敏感数据外发拦截、适配器超时、重复执行、输出结构异常、测试环境与交付版本不一致。

同时核对能力说明、权限声明、隐私文本和实际行为是否一致。只有契约、实现、测试、审核材料和版本包相互对应，才算完成工程交付准备。

Skill Vibe Coding 提高的是表达和搭建效率，但质量仍来自清晰契约与严格验证。把自然语言创意落到状态机、适配器、正负样本、安全门禁和版本证据上，才能让 Skill 从一次演示成长为可维护、可审核的长期能力。