HarmonyOS API 26 DevEco Code 需求到 ArkTS 骨架的提示词分层

AI Coding 的提效，关键不在于让工具一次生成更多代码，而在于让每一次生成都带着可检查的上下文。把一句"做一个阅读页"直接交给模型，得到的往往是缺少 loading、没有错误回退、状态散落在页面里的代码；把需求拆成约束、数据、界面和验证层，模型才有机会生成可以复核的 ArkTS 骨架。

本文围绕图片中的"AI Coding 提效实战"方向，建立从需求到 ArkTS 骨架的提示词分层模型，并给出一套纯函数检查规则。示例中的 PromptLayers.ts 只负责检查提示词是否具备必要层次，不代表 DevEco Code 会自动生成可编译工程，也不宣称 API 26 已经接入任何未公开的 AI 接口。

一、先还原一次低质量生成

开发者输入"做一个支持手机和平板的阅读页"，模型生成了页面组件、一个数组和几个点击事件。运行到真实需求时才发现：没有空数据状态，网络失败后无法重试，Preferences 迁移没有说明，平板横屏也没有布局策略。返工的时间超过了手写第一版的时间。

问题不是模型不会写 ArkTS，而是提示词没有告诉它什么必须存在、什么不能越过、什么需要验证。提示词分层的目的，是让需求变成一份可审计的输入契约。

二、API26的责任边界

HarmonyOS API 26 的 ArkTS 和 ArkUI 文档可以约束类型、组件和状态写法，Ability Kit 与应用上下文文档可以帮助划分生命周期和平台服务边界，静态检查规则可以帮助发现类型、资源和声明问题。本文把 DevEco Code、CLI、Vibe Coding 和 Skills 视为开发工具链概念，不把它们描述成系统会替应用完成的编译或真机验证。

本文没有执行 HarmonyOS 编译、DevEco Code 生成、ArkUI 联调或真机测试。示例只验证提示词分层和人工复核门槛，接入真实工程时仍需要在 DevEco Studio、CI 和目标设备上完成验证。

三、五层提示词模型

一个可复核的生成请求至少包含五层：需求层说明用户目标和范围；约束层说明 API、设备、权限和架构边界；数据层定义模型、状态、持久化和失败；UI 层定义页面状态和交互；验证层定义静态检查、测试和人工验收。

ts 复制代码

export type PromptLayer = 'requirement' | 'constraint' | 'data' | 'ui' | 'verification'
export type RiskLevel = 'low' | 'medium' | 'high'

层次是输入结构，不是模型内部的隐藏推理。团队可以把每层保存成独立 Markdown 片段，复用到不同页面。

四、每个提示块都要有风险等级

同一句"保存阅读进度"，在内存状态里风险较低，涉及账号同步时风险就更高。给块标注风险等级，可以决定是否要求人工确认、额外测试或平台文档复核。高风险块不应由模型自动合并成最终代码。

ts 复制代码

export interface PromptBlock {
  layer: PromptLayer
  text: string
  required: boolean
  risk: RiskLevel
}

风险等级只是流程信号，不是安全认证。涉及账号、支付、敏感权限和跨应用操作时，还要走项目自己的安全评审。

五、需求层只写目标和不做什么

需求层要回答"给谁用、解决什么问题、成功是什么"，同时写明不在本次范围内的功能。例如阅读页目标是打开文章、显示章节、保存书签；不包含评论、支付和云端同步。范围越清楚，模型越少生成未经授权的附加功能。

ts 复制代码

const requirement = {
  layer: 'requirement',
  text: '阅读页支持章节浏览、书签和本地进度，不包含评论与支付',
  required: true,
  risk: 'low'
} as const

不要在需求层堆叠具体组件名。组件和状态应该在后面的约束和 UI 层定义，方便替换实现而不改变业务目标。

六、约束层锁定ArkTS和设备边界

约束层要说明目标 API、ArkTS 严格类型、页面和服务的依赖方向、手机与平板的布局目标，以及不能虚构的系统能力。它是提示词里最容易缺失、却最能减少返工的一层。

ts 复制代码

const constraint = {
  layer: 'constraint',
  text: 'API 26、ArkTS strict、页面只负责渲染；手机和平板使用同一数据契约',
  required: true,
  risk: 'medium'
} as const

如果项目不需要网络或登录，应明确写出离线边界，避免模型顺手生成 fetch、账号和埋点。新增权限、SDK 或原生桥接前，需要先停下来评估范围。

七、数据层先画出状态转移

数据层不要只给一个接口字段表，还要写清 loading、content、empty、error、saving 等状态，以及状态之间如何转移。模型生成的数据服务和页面状态才能保持一致。

ts 复制代码

interface ReaderState {
  phase: 'loading' | 'content' | 'empty' | 'error' | 'saving'
  chapterId: string
  progress: number
  errorMessage?: string
}

若使用 Preferences 保存轻量进度，应在数据层写出键名、版本和迁移策略；结构化任务记录则应说明为何需要关系型存储。提示词不能把持久化 API 直接塞进 UI 组件。

八、多设备约束要落到可观测指标

"适配平板"太模糊，应该拆成横屏双栏、折叠展开迁移、最小点击区域和文字不截断等可检查条件。模型可以据此生成布局骨架，人工验收也有明确的观察点。

ts 复制代码

interface DeviceRule {
  name: 'phone' | 'tablet' | 'foldable'
  minWidthVp: number
  columns: 1 | 2
  preserveScroll: boolean
}

设备规则是产品约束，不代表代码已经在对应设备上通过。最终仍需在模拟器或真机上检查旋转、小窗、折叠和深色模式。

九、UI层要列出可见状态

UI 层把数据状态映射成用户可理解的页面状态。空内容要有下一步，错误要有重试或返回，保存中要防止重复点击。模型只看到这些状态，才不会只生成 happy path。

ts 复制代码

const ui = {
  layer: 'ui',
  text: 'loading 显示骨架；empty 提供导入；error 提供重试；saving 禁用重复保存；返回始终可用',
  required: true,
  risk: 'low'
} as const

页面组件不应该直接决定网络重试、存储迁移和权限请求。把这些动作留在 ViewModel 或 Service 层，能让生成结果更接近项目的三层结构。

十、验证层必须写失败条件

验证层不是一句"请保证代码正确"，而是具体写出静态检查、类型检查、纯函数测试、长文本检查、返回路径和失败路径。尤其要写失败条件，否则模型容易把验证写成一句没有动作的注释。

十一、用顺序约束减少上下文漂移

五层的顺序固定为需求、约束、数据、UI、验证。先给组件代码再补需求，模型可能围绕错误的实现继续扩展。固定顺序还便于比较两次提示词的差异。

ts 复制代码

const order: PromptLayer[] = ['requirement', 'constraint', 'data', 'ui', 'verification']
export function missingLayers(blocks: PromptBlock[]): PromptLayer[] {
  const present = new Set(blocks.filter(block => block.required && block.text.trim()).map(block => block.layer))
  return order.filter(layer => !present.has(layer))
}

检查函数只判断必要层是否存在，不判断自然语言是否"足够聪明"。语义质量仍需开发者和产品共同评审。

十二、生成ArkTS骨架时先生成接口

推荐让模型先输出类型、状态和服务接口，再输出页面骨架。接口确认后，页面代码的返工范围更小，静态检查也更早暴露字段错配。要求模型暂时不要添加真实网络、权限和原生桥接调用。

ts 复制代码

interface SkeletonContext {
  targetPage: string
  stateNames: string[]
  actions: string[]
  hasPersistence: boolean
  hasNetwork: boolean
  deviceTypes: string[]
}

骨架阶段可以使用假的数据源或内存适配器，但要在提示词中标记为占位实现，防止误以为已经接通后端。

十三、把缺失层和警告分开

缺失层表示不能开始生成；警告表示可以生成候选，但必须在评审前补齐。例如有网络却没有失败路径属于警告，多设备却没有适配约束也属于警告。二者分开后，团队可以决定是否允许低风险页面先生成。

ts 复制代码

export interface SkeletonDecision {
  accepted: boolean
  missing: PromptLayer[]
  warnings: string[]
  order: PromptLayer[]
}

高风险页面可以把任何警告都当成阻断，低风险页面则可以先生成骨架并把警告写进任务清单。

十四、持久化和网络要有专门警告

有持久化需求却没有迁移说明，后续版本很容易丢数据；有网络需求却没有失败路径，页面会在弱网下失去反馈。检查函数可以用关键词做第一轮提示，最终仍要由开发者确认具体方案。

ts 复制代码

export function validateSkeleton(blocks: PromptBlock[], context: SkeletonContext): SkeletonDecision {
  const missing = missingLayers(blocks)
  const warnings: string[] = []
  if (context.hasPersistence && !blocks.some(block => block.layer === 'data' && block.text.includes('迁移'))) warnings.push('持久化需求缺少迁移说明')
  if (context.hasNetwork && !blocks.some(block => block.layer === 'verification' && block.text.includes('失败'))) warnings.push('网络需求缺少失败路径')
  if (context.deviceTypes.length > 1 && !blocks.some(block => block.layer === 'constraint' && block.text.includes('设备'))) warnings.push('多设备需求缺少适配约束')
  return { accepted: missing.length === 0, missing, warnings, order }
}

关键词检查不是自然语言理解，也不能替代架构评审。它的价值在于把常见遗漏变成可见提醒。

十五、静态检查是第一道门

生成骨架后先运行 ArkTS 静态检查和项目已有的 lint、类型检查，再考虑接入真实服务。静态检查可以发现类型、资源和声明问题，但不能证明页面交互、权限流程和设备布局正确。

ts 复制代码

export function codeReviewGate(decision: SkeletonDecision, hasStaticCheck: boolean, hasHumanReview: boolean): boolean {
  return decision.accepted && hasStaticCheck && hasHumanReview && decision.warnings.length === 0
}

这里的 hasStaticCheck 和 hasHumanReview 是流程证据标志，不是代码自己声称"已通过"。CI 应把实际命令输出保存到构建记录。

十六、人工评审要看四个差异

ts 复制代码

const reviewPoints = ['state-complete', 'service-boundary', 'permission-scope', 'back-and-repeat-click'] as const

如果生成结果引入新的依赖、全局状态或原生桥接，应暂停合并并先评估范围。提效的前提是减少返工，而不是增加不可见的复杂度。

十七、VibeCoding适合快速试错

Vibe Coding 可以用来探索页面结构、命名和纯函数，但要把探索分支和交付分支分开。候选代码经过分层提示词、静态检查和人工评审后，才能进入主线。CLI 一键推送到设备也只能说明推送动作完成，不能替代功能验收。

ts 复制代码

type CandidateStage = 'draft' | 'static-passed' | 'human-reviewed' | 'device-checked'
function promotable(stage: CandidateStage): boolean { return stage === 'device-checked' }

本文不宣称执行了 DevEco Code、CLI 推送或真机测试；这些步骤需要在真实项目工具链中运行并记录结果。

十八、生成结果的版本和回滚

每次提示词生成都应保存需求层、约束层和模型版本，代码候选使用独立分支或提交。若新提示词引入了错误状态或破坏多设备布局，能够回滚到上一版提示词和骨架，比手动比较大段生成代码更可靠。

ts 复制代码

interface PromptRevision { id: string; parentId?: string; model: string; changedLayers: PromptLayer[]; createdAt: number }
function changed(revision: PromptRevision, layer: PromptLayer): boolean { return revision.changedLayers.includes(layer) }

版本记录不应包含敏感用户数据和私有密钥。示例只表达结构，不代表项目必须采用某一种代码托管方案。

十九、测试矩阵覆盖分层缺失

纯函数测试至少覆盖完整五层、缺少任一层、空文本、持久化迁移警告、网络失败警告、多设备约束警告和评审门禁。这样可以在模型调用之前拦住明显不完整的输入。

ts 复制代码

const layers = ['requirement', 'constraint', 'data', 'ui', 'verification']
for (const layer of layers) console.log('missing-layer-case', layer)

本篇配套 test-prompt-layers.mjs 共 32 个断言，只验证输入契约和门禁逻辑。它不证明 ArkTS 编译成功，也不证明 DevEco Code 的生成质量。

二十、无障碍与多设备提示词

无障碍和多设备不要放在文章末尾当作补充。提示词中应明确焦点顺序、最小触控区域、长文本截断、深色模式和折叠迁移，模型才会把这些条件带入页面骨架。产品评审要在手机、平板、横屏和小窗中复核。

ts 复制代码

interface AccessibilityRule { label: string; minTouchVp: number; maxLines: number; supportsDarkMode: boolean }

一套提示词可以复用，不代表不同设备可以共用固定宽度。实现仍需使用 layoutWeight、约束尺寸和安全区等项目约定。

二十一、小结：把提效变成可复用的检查流程

需求到 ArkTS 骨架的稳定路径是：先写目标，再锁定边界；先定义数据和状态，再描述 UI；最后列出静态检查、失败路径和人工验收。分层提示词让模型少猜一层，纯函数门禁让团队早发现一层，版本记录让每次优化都能回滚和比较。

本文没有执行 HarmonyOS 编译、DevEco Code 生成、ArkUI 联调或真机验收；相关结果需要在项目环境中单独验证。