【听见课堂 HarmonyOS NEXT 实战系列 10】从原型到可审计交付用.agent、Design Spec 和 QA 证据管理项目一个 HarmonyOS 页面“看起来做完了”并不代表项目已经可以交付。设计图存在、ArkTS 能编译、模拟器能打开、真机能运行、系统 Kit 产生真实结果、文章已经提交平台这些是完全不同的证据层级。如果把它们混成一句“已完成”项目越往后走返工和误报就越难控制。听见课堂把需求、视觉源、Design Spec、代码、验证脚本、运行截图和会话记录串成一条可追溯链。本文不讨论某个页面怎么写而是完整拆解怎样让一次 HarmonyOS NEXT 交付能够回答“改了什么、为什么改、在哪验证、哪些没验证、下一位维护者从哪里继续”。一、先把“完成”拆成七种证据听见课堂同时包含 ArkUI 页面、RelationalStore、本地服务、Core Speech、Core Vision、Camera Kit、phone 与 2in1 适配。如果只使用一个“完成”状态最容易发生四种误判设计稿完整被说成页面已经实现HAP 构建通过被说成真机功能已经验证模拟候选能够显示被说成真实 AI 模型已经接入平台出现成功页被说成文章已经公开或审核通过。更稳妥的做法是按证据来源拆分证据层需要回答的问题典型产物需求证据用户到底要什么不做什么需求说明、任务清单设计证据页面结构和视觉基准是什么原始视觉源、Design Spec实现证据哪些源码承载行为ArkTS、Service、Repository契约证据静态规则和状态机是否满足验证脚本、单元测试构建证据工程能否产生目标包HSP、HAP、APP 构建日志运行证据目标设备上是否真实可用安装、前台进程、截图、日志外部状态是否真正提交、审核、公开平台文章 ID、审核状态、公开页这个分类不是为了增加文档而是为了阻止证据越级。例如assembleHap成功只能证明构建层通过不能替代麦克风真实转写或 AGC 审核。二、可追溯链应该长什么样一次可靠变更可以压缩成下面这条链用户目标 - 任务与边界 - 视觉源 / 数据合约 / Kit 合约 - Design Spec 或技术设计 - 最小实现 - 契约与构建 - 设备运行与截图 - QA 结论 - .agent 会话记录 - 对外发布状态链上每个节点都要能回到上一个节点。页面截图要能指出使用了哪份设计基准验证报告要能指出运行了哪个包会话记录要能列出修改文件和未验证项公开文章要能回到本地原稿与图片资产。听见课堂的项目目录把这些材料分开保存docs/ ├─ design/ # Design Spec、视觉修订说明、组件映射 ├─ qa/ # 验收标准、运行报告、问题整改报告 └─ csdn/ # 系列文章、图片、发布计划与平台记录 .agent/ ├─ context/ # 当前架构、能力边界、项目阶段 ├─ evidence/ # 截图、UI 树、运行探针等原始证据 ├─ sessions/ # 每轮任务的完整交付记录 └─ memory/ # 每日摘要、决策和变更索引原始证据和结论必须分开。截图属于证据QA 报告是对证据的解释二者不能互相替代。三、为什么视觉源不能直接代替 Design SpecAI 生成图或 Figma 截图擅长表达氛围与层级却通常不会准确描述安全区、滚动范围、长文本、暗色模式、权限拒绝和响应式断点。直接照图写 ArkUI维护者很难判断某个比例是明确要求还是开发者猜测。听见课堂先将视觉源固化为 Markdown Design Spec至少记录视觉源文件、画布尺寸和目标设备页面区域的层级、占比、滚动边界和安全区卡片、按钮、图标、文字、间距和状态phone、tablet、2in1 的断点策略ArkUI 组件与 theme token 映射截图不可见区域和推测值。以 2in1 背景修正为例系统桌面壁纸、系统标题栏和应用内容区必须先分开。若把窗口外的系统壁纸也算进应用背景差异开发者可能错误地修改 ArkUIDesign Spec 通过明确AppContent裁切范围避免了这种归因错误。四、QA 状态必须使用受控词汇听见课堂的验收记录统一使用四种状态passed在指定环境实际执行并满足验收标准failed实际执行但结果不满足标准not run没有执行必须说明原因blocked存在设备、权限、服务、账号或平台等外部阻塞。它们解决的不是措辞问题而是决策问题。比如“tablet 未验证”和“tablet 验证失败”需要完全不同的后续动作“CSDN 审核中”和“CSDN 已公开”也不能写在同一个完成状态里。一条合格验证记录应包含命令、环境、结果和证据位置# 构建证据.\hvigorw.bat assembleHsp--mode module-p moduleshared_businessdefault.\hvigorw.bat assembleHap--mode module-p moduleentrydefault# 设备预检hdc list targets-v hdc shellecho write_ok /data/local/tmp/codex_write_test cat /data/local/tmp/codex_write_test如果当天没有连接设备正确记录是“构建 passed安装和运行 not run”而不是用以前的截图证明本次运行。五、.agent会话记录怎样写才有用会话记录不应该只是“完成某功能”。一份能交接的记录至少包括Summary本轮实际达成的结果Root Cause问题根因或为什么需要本次工作Plan执行顺序与明确排除项Repair Cycles失败、最小修复和复验过程Files Changed真实修改文件Validationpassed、failed、not run、blockedRisks仍存在的能力或设备边界Handoff下一步从哪个文件、证据或平台状态继续。对发布任务还要单独记录文章 ID、公开 URL、专栏、质量分、图片地址和审核状态。成功页只能作为一个信号不能单独成为“已发布”的结论。六、用 Git 脏状态保护用户已有工作开始任务前执行只读盘点git status--short git rev-parse--is-inside-work-treeGet-ChildItem-Force这一步会告诉维护者哪些文件已经被用户修改哪些是本轮新增哪些目录是其他任务留下的证据。听见课堂长期存在多轮 UI、能力和交付记录如果不先查看工作区状态很容易把用户未提交的实现误当成本轮变更甚至在清理时误删。安全原则是只修改任务范围内的文件不为了让状态“干净”而重置无关改动不把缓存、签名文件和含密钥的配置复制进文章或公开仓库。七、文档与源码不一致时以什么为准持续迭代项目常见一个问题上下文文档仍写 schema v1而当前RelationalClassroomRepository.ets已经把SCHEMA_VERSION提升到 2并实现了迁移。此时不能任选一份材料引用。建议按下面的证据优先级处理当前源码和真实构建输出本轮新鲜的运行与数据库验证与源码同版本的 QA 报告项目上下文和历史会话早期规划或设计提案。文档并非不重要它记录当时的决策但文档带有时间点。发现漂移后应在当前交付记录中明确“旧文档描述的是历史基线本文按当前源码 schema v2 说明”而不是静默覆盖事实。八、能力真实性也需要审计字段多模态项目尤其容易把演示和真实能力混淆。听见课堂将能力标记为 planned、simulated、contract-only、integrated、runtime-proven。例如Core Vision 人体骨骼已经有真实设备运行证据手部 21 点 Provider 已有契约但模型未安装时返回unavailable20 词手语候选仍是显式模拟合成序列只用于契约测试不能进入用户历史或准确率统计。文章、比赛材料、README 和 UI 文案都应使用同一组能力边界。成功构建不能把contract-only自动升级为runtime-proven。九、发布也要做三次回读对外发布至少检查三个阶段阶段检查项提交前标题、正文、标签、封面、图片、账号、专栏提交后成功 URL、文章 ID、管理列表状态公开后标题无乱码、正文图片、专栏、质量分、审核状态cbismb 等平台可能长期显示“审核中”。这只能说明提交成功不能说审核通过。CSDN 页面即使能访问也要继续读取页面上的“公开”或“审核中”标识。十、可复制的交付检查清单在下一次 HarmonyOS 任务收尾时可以使用这组最小清单Git 状态已读取用户原有改动未覆盖需求、排除项和成功标准清楚视觉源与 Design Spec 分开保存Service、Repository、页面职责没有混写验证结果使用 passed、failed、not run、blocked构建、设备、Kit、视觉和发布证据分别记录没有把模拟、合成或契约接口写成真实 AI没有在日志和公开材料中泄露签名、账号或私密内容.agentsession、daily 和 change-log 已同步外部平台状态经过回读而不是只看成功提示。十一、总结可审计交付的核心不是“多写文档”而是让每个结论都有对应证据让每个证据都有适用边界。听见课堂通过 Design Spec、QA 标准、原始运行证据和.agent会话记录把设计、实现、验证与发布拆成可独立检查的层级。当维护者能够准确说出“本次构建通过、phone 运行通过、tablet 未运行、真实手语模型未接入、平台仍在审核中”项目才真正具备持续交付能力。下一篇将进入本地数据层分析为什么应先定义ClassroomRepository接口再决定使用 RelationalStore 还是内存实现。