企业官网建设流程全解析

导读：在 Harness Engineering 实践中，代码库不仅服务于人类工程师，还需要被 Agent 快速、准确地理解。quality-document.md（质量文档）正是为此设计的轻量级快照工具：它以统一评分体系为每个产品领域与架构层打分，让人与 Agent 一眼看清代码库"哪里强、哪里需要返工"。本文以仓库中的质量文档模板（docs/de/resources/templates/quality-document.md，同构英文版见 docs/en/resources/templates/quality-document.md）为骨架，结合 project-06 结业项目 的真实填充示例与底层源码，完整讲解该模板的结构、评分标准、填写方法与验证闭环。读完本文，你将掌握如何在任意 Agent 协作项目中落地一份可维护、可验证、可被 Agent 引用的质量文档。

一、模板定位：面向 Agent 与人类的"质量快照"

模板开篇即定义了它的核心作用：

一份针对每个产品领域（product domain）与架构层（architectural layer）的质量快照。Agent 与人类都可以使用这份文档，快速理解代码库哪里强、哪里需要改进。

这决定了质量文档的三个特性：

1. 快照而非报告：它不追求冗长的过程叙述，而是某一时刻对代码库质量的浓缩定格；
2. 双读者：既要人类可读，也要 Agent 可读（agent-legible），因此表格结构统一、评分标准明确、字段语义稳定；
3. 高频更新：模板明确规定了更新节奏——每次重要的 Agent 会话之后，或开始新一阶段工作之前。这与仓库中 session-handoff.md、claude-progress.md 等会话留痕文件的定位一致：让"上一阶段的质量认知"能够无损传递给"下一阶段的工作者"，无论它是人类还是 Agent。

二、评分体系：A 到 D 的判定标准

模板定义了四级评分（德语版原文与英文版语义一致），这是整个文档的量化基础：

注意等级判定中反复出现的两个关键词：Verification（验证）与agent-legible（Agent 可读性）。这并非偶然——质量文档的评分不是凭感觉，而是要求"有验证动作作为证据支撑"；同时"Agent 能否读懂这段代码"被提升为与"测试是否稳定"并列的一等公民指标，这正是 Harness 工程区别于传统软件质量评估的核心视角。

从仓库的实际实现看，"验证"并非虚设。在 project-06 的评估者评分标准 中，每一项能力都以 1-5 分给出可核查的证据描述；而 clean-state-checklist.md 则把验证拆解为 30 个可勾选的检查项，横跨 Build、Architecture、Runtime、Logging、Data Integrity、Performance、Repository、Scripts 八类。质量文档中的"验证"列，指向的正是这类可以实际执行的检查动作。

三、产品领域表：按业务域横向打分

模板的第一张核心表格是产品领域表，固定列出五个领域：

这张表回答的是**"每个业务能力现在处于什么状态"**。六列含义如下：

• Grade（等级）：A-D 之一；
• Verification（验证）：该领域通过哪些检查验证过（对应构建、脚本、运行验证）；
• Agent Legibility（Agent 可读性）：代码/文档是否容易被 Agent 理解；
• Test Stability（测试稳定性）：相关测试是否稳定通过；
• Key Gaps（关键缺口）：当前已知的短板；
• Last Updated（最后更新）：该行评分的时间戳。

这五个领域并非模板作者凭空罗列，而是与项目真实功能一一对应。以 project-06 结业项目 的 15 项 feature 为例：文档导入对应document-import（含文件校验、10MB 大小限制、元数据创建）；文档索引对应text-indexing（段落边界感知的分块、单文档/批量两种模式）；Q&A 流程与有依据的回答对应grounded-qa（关键词检索、引用与置信度评分）。换言之，模板中的每一行领域，都应当能在 feature 清单中找到其功能实现与之映射，这样评分才有据可依。

四、架构层表：按分层纵向检查

第二张核心表格是架构层表，固定四层：

与产品领域表相比，这里把"测试稳定性"换成了Boundary Enforcement（边界执行），这是一个更偏架构的指标：检查分层边界是否被严格执行。从源码结构可以印证这一点：

• src/main/ipc-handlers.ts 与 src/main/main.ts 属于主进程层；
• src/preload/preload.ts 是唯一的 IPC 桥接层；
• src/renderer/ 下是 React 组件；
• src/services/ 下是 document、indexing、qa、persistence、logger 五个服务。

"边界执行"的检查内容在 clean-state-checklist.md 中被明确为四条架构红线：

• 渲染进程代码（src/renderer/）不得 importfs或path；
• 服务层（src/services/）不得直接使用 Electron IPC；
• 服务与主进程不得引入 React；
• 所有 IPC 通道统一在 src/shared/types.ts 中定义，所有新 API 必须在 preload 中暴露。

这些红线恰好解释了模板中"边界执行"这一列要回答的问题：每一层是否只通过约定好的方式与相邻层通信？若某层出现越界依赖（如 Renderer 直接读写文件系统），即构成边界违规，该层评分应被下调。

五、变更历史：让质量演化可追溯

模板末尾是变更历史（Änderungsverlauf / Change History）区块，按日期组织，固定五个记录维度：

• Changes（变更）：本次会话的整体改动；
• Domains promoted（领域升级）：哪些领域评分上调；
• Demoted（降级）：哪些领域/层评分下调；
• New gaps identified（新缺口）：新暴露的问题；
• Gaps closed（已关闭缺口）：本次修复的问题。

这个区块与 claude-progress.md 形成互补：进度日志记录"做了什么"，变更历史则沉淀"质量认知发生了什么变化"。它让多会话协作中的质量走向可回看——新会话的 Agent 不必重新推断整个代码库的优劣，只需读取最近的变更历史即可建立起点认知。

六、从模板到实践：project-06 的完整填充示例

模板的价值在于被认真填写。仓库中 projects/project-06/solution/quality-document.md 给出了一个高质量的实战范例，恰好对应模板中"产品领域 × 架构层"的量化框架，只是在结业场景下细化为 15 个能力维度。我们可以对照学习模板的填写思路：

6.1 评分摘要：逐维度打分

示例将每个能力独立成行，给出等级与一句话依据：

这种"维度 + 等级 + 一句话证据"的写法，正是模板产品领域表的实战化变体——每一行都必须能被一句话说清"凭什么给这个分"。

6.2 质量证据：验证必须可执行

示例文档专门列出Evidence of Quality（质量证据）区块，分四类给出可复现的验证动作：

• Build（构建）：npm run check干净通过；npm run build输出正确；bash init.sh校验所有文件齐备；
• Runtime（运行时）：窗口以 1200x800 启动且安全项配置正确；结构化 JSON 日志从首次启动即可见；文档导入生成元数据并存储内容；批量索引处理全部文档并输出指标；Q&A 返回带引用的有依据回答；
• Observability（可观测性）：每个 IPC 通道调用都被记录；导入日志携带 documentId、filename、sizeBytes；索引日志携带 chunkCount、durationMs、throughput；Q&A 日志携带 confidence、citationCount、answerLength、durationMs；干净状态重置以 WARN 级别记录；
• Performance（性能）：以示例数据为基准，导入 3 份文档 <200ms、批量索引 3 份 <100ms、带引用查询 <300ms、干净状态重置 <20ms。

这些"证据"并非形容词，而是指向可重复执行的命令与脚本。例如 scripts/benchmark.sh 就是性能证据的直接来源：它定义 4 个基准任务（Import、Indexing、Query、Verify），对示例文档逐文件计时、统计关键词匹配数、校验文件大小一致性，最后汇总PASS/FAIL计数并输出结构化结果。质量文档中的性能数据，正是这类脚本的产物。

6.3 验证依据：与检查清单形成闭环

示例结尾的Verified Against区块展示了质量文档与周边 harness 文件的引用关系：

• clean-state-checklist.md：30 项检查全部通过；
• evaluator-rubric.md：总分 5.0/5；
• feature_list.json：15/15 项功能状态为 pass；
• bash scripts/benchmark.sh：全部任务完成；
• bash scripts/cleanup-scanner.sh：无残留产物。

这构成了一个完整的质量验证链：功能清单（feature_list.json）→ 检查清单（clean-state-checklist.md）→ 评分标准（evaluator-rubric.md）→ 自动化脚本（benchmark.sh / cleanup-scanner.sh）→ 质量文档（quality-document.md）。质量文档不是孤立的表格，而是这条链的"汇总出口"。

七、反面对照：从 D+ 到 A 的演化路径

projects/project-06/starter/quality-document.md 提供了同一份文档的"起点形态"，与 solution 版形成鲜明对照：

• 起点总体等级D+：构建有未使用导入警告（C）、缺少反馈收集/干净状态/基准测试（D）、会话历史只是无样式的平面列表（D）、结构化日志未覆盖全部服务（C）、测试覆盖为零（F）；
• 终点总体等级A：15 个维度中 14 个达到 A，1 个（测试覆盖）为 B。

更值得注意的是起点文档的Action Items（行动项）区块：7 条待办以复选框形式列出（新增 FeedbackEntry 类型与反馈服务、通过 IPC 实现干净状态重置、编写 benchmark.sh、会话历史增强为聊天气泡、为全部服务增加结构化 JSON 日志、为服务编写测试、补齐完整 harness 文件）。这揭示了质量文档的另一重用法：它不仅是状态快照，还是下一阶段工作的路线图——评分低的维度，直接映射为待办行动项。

从源码看，这些行动项在 solution 中逐一落地：结构化日志由 src/services/logger.ts 实现（LogLevel 枚举、forService()子日志器、JSON 序列化输出）；反馈收集由qa-service.ts的submitFeedback()与FeedbackEntry类型支撑；干净状态重置由PersistenceService.resetAll()与IPC_CHANNELS.RESET_DATA通道实现。质量文档中每个被勾除的缺口，都能在源码中找到对应的实现证据。

八、模板落地要点与使用建议

综合模板设计意图与仓库实践，使用质量文档时有几点建议（以下基于仓库现有结构推断总结）：

1. 每次会话结束必须触碰：模板明确要求"每次重要会话后、开始新阶段前"更新。宁可更新一行"Last Updated"，也不要在多阶段工作中放任文档过期；
2. 评分必须附带验证动作：等级旁边写清"通过什么检查得到的结论"，让人类和 Agent 都能复现验证过程，避免主观打分；
3. 领域行与功能清单保持映射：产品领域表中的每个领域，都应能在 feature_list.json 或对应功能文档中找到实现，评分才有落点；
4. 架构层行与分层红线联动：评分前先跑架构边界检查（如scripts/check-architecture.sh与 clean-state-checklist 中的四条红线），再用结果填充"Boundary Enforcement"列；
5. 变更历史逐条对应缺口：每次"Domains promoted"都应在变更历史中注明依据，新缺口要及时登记，形成完整的质量演化档案；
6. 与周边 harness 文件配合使用：质量文档应与其他 harness 文件保持一致性——feature_list.json 的功能状态、clean-state-checklist.md 的勾选结果、evaluator-rubric.md 的评分，都应与质量文档中的等级互相印证。

结语

一份被认真维护的 quality-document 让代码库的质量状态从"隐性知识"变成"显性数据"：人类工程师可以快速定位返工区域，Agent 可以在会话开始时用几秒钟建立对代码库质量的完整认知，评估者可以用统一尺度横向比较不同模块。模板本身极其精简——两张表格、一套 A-D 评分、一段变更历史——但正如 project-06 从 D+ 到 A 的演化所证明的，它的价值完全取决于填写者是否以可验证的方式持续记录。让质量文档成为每个 Agent 会话的固定收尾动作，你的代码库质量轨迹将第一次变得清晰、可量化、可传承。