企业官网建设流程全解析

【听见课堂 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 模型已经接入；
• 平台出现成功页，被说成文章已经公开或审核通过。

更稳妥的做法是按证据来源拆分：

这个分类不是为了增加文档，而是为了阻止证据越级。例如，assembleHap成功只能证明构建层通过，不能替代麦克风真实转写或 AGC 审核。

二、可追溯链应该长什么样

一次可靠变更可以压缩成下面这条链：

用户目标 -> 任务与边界 -> 视觉源 / 数据合约 / Kit 合约 -> Design Spec 或技术设计 -> 最小实现 -> 契约与构建 -> 设备运行与截图 -> QA 结论 -> .agent 会话记录 -> 对外发布状态

链上每个节点都要能回到上一个节点。页面截图要能指出使用了哪份设计基准；验证报告要能指出运行了哪个包；会话记录要能列出修改文件和未验证项；公开文章要能回到本地原稿与图片资产。

听见课堂的项目目录把这些材料分开保存：

docs/ ├─ design/ # Design Spec、视觉修订说明、组件映射 ├─ qa/ # 验收标准、运行报告、问题整改报告 └─ csdn/ # 系列文章、图片、发布计划与平台记录 .agent/ ├─ context/ # 当前架构、能力边界、项目阶段 ├─ evidence/ # 截图、UI 树、运行探针等原始证据 ├─ sessions/ # 每轮任务的完整交付记录 └─ memory/ # 每日摘要、决策和变更索引

原始证据和结论必须分开。截图属于证据，QA 报告是对证据的解释；二者不能互相替代。

三、为什么视觉源不能直接代替 Design Spec

AI 生成图或 Figma 截图擅长表达氛围与层级，却通常不会准确描述安全区、滚动范围、长文本、暗色模式、权限拒绝和响应式断点。直接照图写 ArkUI，维护者很难判断某个比例是明确要求还是开发者猜测。

听见课堂先将视觉源固化为 Markdown Design Spec，至少记录：

• 视觉源文件、画布尺寸和目标设备；
• 页面区域的层级、占比、滚动边界和安全区；
• 卡片、按钮、图标、文字、间距和状态；
• phone、tablet、2in1 的断点策略；
• ArkUI 组件与 theme token 映射；
• 截图不可见区域和推测值。

以 2in1 背景修正为例，系统桌面壁纸、系统标题栏和应用内容区必须先分开。若把窗口外的系统壁纸也算进应用背景差异，开发者可能错误地修改 ArkUI；Design Spec 通过明确AppContent裁切范围，避免了这种归因错误。

四、QA 状态必须使用受控词汇

听见课堂的验收记录统一使用四种状态：

• passed：在指定环境实际执行，并满足验收标准；
• failed：实际执行，但结果不满足标准；
• not run：没有执行，必须说明原因；
• blocked：存在设备、权限、服务、账号或平台等外部阻塞。

它们解决的不是措辞问题，而是决策问题。比如“tablet 未验证”和“tablet 验证失败”需要完全不同的后续动作；“CSDN 审核中”和“CSDN 已公开”也不能写在同一个完成状态里。

一条合格验证记录应包含命令、环境、结果和证据位置：

# 构建证据.\hvigorw.bat assembleHsp--mode module-p module=shared_business@default.\hvigorw.bat assembleHap--mode module-p module=entry@default# 设备预检hdc list targets-v hdc shell"echo write_ok > /data/local/tmp/codex_write_test && cat /data/local/tmp/codex_write_test"

如果当天没有连接设备，正确记录是“构建 passed，安装和运行 not run”，而不是用以前的截图证明本次运行。

五、.agent会话记录怎样写才有用

会话记录不应该只是“完成某功能”。一份能交接的记录至少包括：

1. Summary：本轮实际达成的结果；
2. Root Cause：问题根因或为什么需要本次工作；
3. Plan：执行顺序与明确排除项；
4. Repair Cycles：失败、最小修复和复验过程；
5. Files Changed：真实修改文件；
6. Validation：passed、failed、not run、blocked；
7. Risks：仍存在的能力或设备边界；
8. Handoff：下一步从哪个文件、证据或平台状态继续。

对发布任务，还要单独记录文章 ID、公开 URL、专栏、质量分、图片地址和审核状态。成功页只能作为一个信号，不能单独成为“已发布”的结论。

六、用 Git 脏状态保护用户已有工作

开始任务前执行只读盘点：

git status--short git rev-parse--is-inside-work-treeGet-ChildItem-Force

这一步会告诉维护者：哪些文件已经被用户修改，哪些是本轮新增，哪些目录是其他任务留下的证据。听见课堂长期存在多轮 UI、能力和交付记录，如果不先查看工作区状态，很容易把用户未提交的实现误当成本轮变更，甚至在清理时误删。

安全原则是：只修改任务范围内的文件，不为了让状态“干净”而重置无关改动，不把缓存、签名文件和含密钥的配置复制进文章或公开仓库。

七、文档与源码不一致时，以什么为准

持续迭代项目常见一个问题：上下文文档仍写 schema v1，而当前RelationalClassroomRepository.ets已经把SCHEMA_VERSION提升到 2，并实现了迁移。此时不能任选一份材料引用。

建议按下面的证据优先级处理：

1. 当前源码和真实构建输出；
2. 本轮新鲜的运行与数据库验证；
3. 与源码同版本的 QA 报告；
4. 项目上下文和历史会话；
5. 早期规划或设计提案。

文档并非不重要，它记录当时的决策；但文档带有时间点。发现漂移后，应在当前交付记录中明确：“旧文档描述的是历史基线，本文按当前源码 schema v2 说明”，而不是静默覆盖事实。

八、能力真实性也需要审计字段

多模态项目尤其容易把演示和真实能力混淆。听见课堂将能力标记为 planned、simulated、contract-only、integrated、runtime-proven。例如：

• Core Vision 人体骨骼已经有真实设备运行证据；
• 手部 21 点 Provider 已有契约，但模型未安装时返回unavailable；
• 20 词手语候选仍是显式模拟；
• 合成序列只用于契约测试，不能进入用户历史或准确率统计。

文章、比赛材料、README 和 UI 文案都应使用同一组能力边界。成功构建不能把contract-only自动升级为runtime-proven。

九、发布也要做三次回读

对外发布至少检查三个阶段：

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 还是内存实现。