企业官网建设流程全解析

本篇技术指南聚焦 Learn Harness Engineering 课程的收官项目（Capstone）——project-06-runtime-observability-and-debugging。项目要求把前五个项目积累的 harness 组件（初始化、特征清单、会话交接、干净状态、运行时反馈）组装成一个完整、可观测、可维护的 Agent 工作台，用固定任务集完成弱 harness 基线、完整 harness、cleanup 循环与消融实验四阶段对比。读完本文，你将掌握如何用AGENTS.md、feature_list.json、init.sh、session-handoff.md、clean-state-checklist.md、结构化日志与基准/清理脚本构建一个可量化评估、可反复验证的 Agent 工程环境，并能独立复跑仓库内projects/project-06的完整实验流程。

一、项目定位：为什么 Capstone 要“可观测 + 可调试”

project-06与前面五个项目最大的区别在于：产品代码已经基本完整，真正的战场是代码之外的“操作系统”——harness 表面。项目描述（德文项目文档）明确写道：这是收尾项目（Abschlussprojekt），你要把前五个项目学到的所有机制组装起来，运行一次完整基准测试，然后做一轮 cleanup，验证质量是否可维护（wartbar bleibt）。

它对应的两讲理论课是：

• Lektion 11. Runtime beobachtbar machen（让 Agent 运行时可观测）
• Lektion 12. Sauberes Handoff am Ende jeder Session（每次会话结束留下干净交接状态）

核心思想一句话：如果 harness 对自身的运行状态不可观测、对跨会话状态不可恢复，那么再强的 Agent 也会在长任务中失控。本项目的任务集固定覆盖一个完整产品切片：文档导入、索引、带引用的 Q&A、运行时可观测性、以及一个可读可恢复（wiederaufnehmbar）的仓库状态。

二、实验设计：基线 → 完整 harness → 清理 → 消融

原文档给出的实验路径是明确且固定的：

1. 弱 harness 基线运行（schwacher harness-Baseline-Lauf）：先用被刻意弱化的 harness 表面跑一遍任务集；
2. 最强 harness 运行：换上完整 harness 再跑同样的任务集；
3. Cleanup 与重跑（Cleanup und erneuter Lauf）：执行清理扫描、修复问题、再次运行确认；
4. 消融实验（Ablationsexperiment）：每次移除一个 harness 组件，观察哪个组件真正决定成败。

这样的设计让结论可归因：不是“Agent 变强了”，而是“某一块 harness 组件带来了可度量的改进”。

三、仓库对照：starter 与 solution 的差距即 harness 的差距

原文档用一张表格概括了两个目录的分工，仓库根路径下对应实现为projects/project-06/starter与projects/project-06/solution：

项目英文 README 中的 “Exact Task Contract” 给出了更精确的差距表：

结论很直接：starter 与 solution 的产品功能几乎相同，差距全部集中在“围绕代码的操作系统”上。不要指望 starter 里会出现 solution 才有的基准命令——弱 harness 运行要用人工记录基线观察，solution 运行则使用检入的脚本。

四、环境与工具清单

按照原文档的 “Werkzeuge” 部分，完成本项目需要：

• AI Coding Agent：Claude Code 或 Codex（也可用 Cursor、Trae 等，见项目总览）；
• Git：管理仓库状态与版本；
• Node.js + Electron：产品是 TypeScript + React 的 Electron 桌面应用（见projects/project-06/solution/package.json，依赖 React 18、Electron 33、Vite 6、Vitest 2）；
• 质量文档模板：对应 solution 中的quality-document.md；
• 评估者 Rubric：对应evaluator-rubric.md；
• 前五个项目的全部 harness 组件：初始化、特征清单、交接、干净状态、运行时反馈等机制。

五、完整 Harness 的组成：9 个关键文件逐个拆解

solution 目录的顶层就是完整的 harness 资产。下面按“Agent 会话生命周期”顺序逐一说明其作用与源码证据。

5.1 AGENTS.md：启动规则与边界约定

AGENTS.md定义了 Agent 开工前的强制顺序：完整读本文件 → 读CLAUDE.md速查 → 读docs/ARCHITECTURE.md→ 读docs/PRODUCT.md→ 读docs/RELIABILITY.md→ 运行bash init.sh验证构建 → 读feature_list.json查看特征现状。

它还规定了 Electron 四层边界：

• 主进程src/main/：BrowserWindow 生命周期与 IPC 注册，所有文件系统访问；
• Preloadsrc/preload/：唯一的主-渲染桥，用contextBridge.exposeInMainWorld暴露类型化 API；
• 渲染进程src/renderer/：React + TypeScript，只通过window.knowledgeBase通信，绝不导入 Node.js 模块；
• 服务层src/services/：主进程内的纯 TypeScript 业务逻辑，构造函数注入PersistenceService，全部使用logger.forService()输出结构化 JSON。

“Definition of Done” 要求：TypeScript 编译零错误（npm run check）、窗口可见、特征在feature_list.json中标记"pass"且有证据、遵守层边界、结构化日志覆盖所有服务操作、更新对应文档、clean-state-checklist.md全部通过。

5.2 CLAUDE.md：速查表与 14 条 IPC 通道

CLAUDE.md是给 Claude Code 的快速参考，包含构建命令（npm install/npm run check/npm run build/npm run dev/npm test）、关键文件索引和完整的 IPC 通道表。通道命名遵循namespace:action模式，全部集中在src/shared/types.ts的IPC_CHANNELS常量中，作为单一事实来源：

对应实现见src/main/ipc-handlers.ts（14 个 handler 全部带日志，写操作用 INFO、读操作用 DEBUG）与src/preload/preload.ts（暴露documents、indexing、qa、feedback、app五个命名空间）。

5.3 feature_list.json：15 项特征的可量化证据

feature_list.json记录了 15 项特征（window-launch、document-list、document-import、document-detail、text-indexing、grounded-qa、conversation-history、feedback-collection、structured-logging、clean-state-reset、persistence、status-bar、benchmark-scripts、cleanup-scanner、full-harness），每项都有status: "pass"与具体的evidence字段。例如：

• text-indexing：IndexingService.chunkDocument()按段落边界切分，CHUNK_SIZE=500；
• grounded-qa：QaService.ask()对问题分词、按关键词重叠打分、返回 top 2 引用，有引用时置信度 0.85、无引用 0.30，内置 8 条 mock 答案模式（见src/services/qa-service.ts）；
• structured-logging：logger.ts提供 DEBUG/INFO/WARN/ERROR 四级、JSON.stringify 输出、forService()子日志工厂，5 个服务全部接入。

5.4 init.sh：开工前的五步验证

init.sh在克隆或恢复工作时运行，五步依次为：npm install→npm run check（类型检查）→npm run build→ 验证 harness 文件存在（AGENTS.md、CLAUDE.md、feature_list.json、clean-state-checklist.md、session-handoff.md、evaluator-rubric.md、quality-document.md、三份 docs、三个脚本）→ 验证示例数据（data/sample-documents/下三个文件）。任何缺失都会以退出码 1 告警。

5.5 session-handoff.md：跨会话的可恢复状态

session-handoff.md记录了上次会话（2026-03-30）完成的工作：结构化日志模块、反馈管线、对话历史组件、干净状态重置、基准脚本与完整 harness 装配；同时记录决策（如“clean state 使用破坏性的 rmSync 而非选择性删除”“基准脚本用 bash 实现零依赖”）与被修改的文件清单。这正是 Lektion 12 “每次会话留下干净交接状态”的落地产物。

5.6 clean-state-checklist.md：30 项检查清单

clean-state-checklist.md覆盖七个类别共 30 项：构建（npm run check/build通过）、架构（渲染进程无fs/path导入、服务层无 Electron IPC、无 React 混入）、运行时（窗口启动、日志出现、导入/批索引/问答事件日志）、日志（JSON 可解析、含 timestamp/level/service/message、关键操作带 data）、数据完整性（无空 chunk、历史与反馈跨重启持久）、性能（3 个文件 1 秒内导入、示例数据 1 秒内完成索引、单问延迟 <1 秒）与仓库卫生（无敏感数据、dist/不入库、交接文档更新）。

六、运行时可观测性：结构化日志是第一等公民

原文档把“Runtime-Beobachtbarkeit（运行时可观测性）”列为任务集核心能力之一，solution 的实现证据集中在src/services/logger.ts与docs/RELIABILITY.md。

6.1 日志格式与级别

每条日志是单行 JSON 对象：

{ "timestamp": "2026-03-30T12:00:00.000Z", "level": "INFO", "service": "document-service", "message": "Document imported successfully", "data": { "documentId": "abc-123", "filename": "design-notes.md", "sizeBytes": 2048 } }

级别使用规则（logger.ts内部用LEVEL_ORDER数组实现过滤，ERROR 走console.error、WARN 走console.warn、其余走console.log）：

6.2 日志级别配置

通过环境变量LOG_LEVEL控制（默认 DEBUG，见logger.ts末尾的new Logger((process.env.LOG_LEVEL as LogLevel) ?? LogLevel.DEBUG)）：

LOG_LEVEL=INFO npm run dev # 仅 INFO、WARN、ERROR LOG_LEVEL=WARN npm run dev # 仅 WARN、ERROR LOG_LEVEL=ERROR npm run dev # 仅 ERROR

6.3 可观测点覆盖

按docs/RELIABILITY.md的约定：DocumentService 记录导入（含 size 与元数据）、删除（含剩余数量）、大小超限；IndexingService 记录单文档/批量索引进度与吞吐指标；QaService 记录答案生成（confidence、citationCount、durationMs）与反馈提交；IPC handlers 记录每次通道调用并在启动时登记全部通道。这意味着从第一条日志就能重建整个文档生命周期——这正是“可调试”的基础。

七、基准测试：benchmark.sh 的四个任务

scripts/benchmark.sh用零依赖的 bash 实现对服务层做文件级模拟（无需启动 Electron 窗口），set -euo pipefail严格模式，四个任务：

1. Import：把data/sample-documents/三个样例文件复制到临时目录并计时，要求 ≥3 个文件；
2. Index：按双换行切段估算 ~500 字符 chunk 数，要求总 chunk ≥5；
3. Query：对 5 个固定问题（“What is the system architecture?” 等）做关键词匹配计数并计时；
4. Verify：核对三个样例文件导入前后字节数一致。

最终输出=== Summary: N/4 tasks passed ===，全部通过则exit 0并打印ALL BENCHMARKS PASSED，否则exit 1。docs/RELIABILITY.md给出了预期目标：导入 3 文件 <1s、索引 14 chunks <1s、单问 <500ms、数据完整性 0 错误；quality-document.md记录的样例实测为：导入 3 文档 <200ms、批量索引 <100ms、带引用的查询 <300ms、干净状态重置 <20ms。

八、Cleanup 扫描：cleanup-scanner.sh 的五项一致性检查

scripts/cleanup-scanner.sh用于检测数据目录（默认~/.config/knowledge-base/knowledge-base-data，macOS 为~/Library/Application Support/knowledge-base/knowledge-base-data，也可传参指定）中的陈旧/不一致产物：

全部通过输出Result: CLEAN (0 issues found)；发现问题时给出建议动作：使用应用内 Reset 按钮 → 从data/sample-documents/重新导入 → 重跑扫描验证。配套的scripts/check-architecture.sh则用 grep 自动校验三层边界：渲染进程无 Node 核心模块导入、服务层无 Electron IPC、services/main 无 React 导入。

九、干净状态机制：可重复实验的前提

docs/ARCHITECTURE.md描述了数据目录布局：documents-meta.json、content/<doc-id>.txt、documents/（原始文件副本）、chunks/<doc-id>.json、index/index-meta.json、qa-history.json、feedback.json。app:reset通道调用PersistenceService.resetAll()删除整个knowledge-base-data/并重建目录结构，随后渲染进程清空 React 状态并刷新。docs/RELIABILITY.md明确何时必须用干净状态：跑基准前、调试会话后、测试新功能前、数据目录损坏时。

十、消融实验：怎么判断哪个组件真正重要

消融（Ablation）是原文档点名要求的收官动作：在完整 harness 基础上每次只移除一个组件，重跑同一套任务集与基准，对比quality-document.md分数变化。可移除的候选组件按前文 5 类划分：feature_list.json（特征可见性）、session-handoff.md（跨会话连续性）、clean-state-checklist.md（质量门禁）、init.sh（启动验证）、基准/清理脚本（可量化反馈）。例如移除cleanup-scanner.sh后，残留的孤儿文件会在下一次基准的 Verify 任务中暴露；移除feature_list.json后，Agent 将失去对 15 项特征完成度的显式追踪，倾向“过早宣布胜利”（对应 Lektion 09 的主题）。这正是把 harness 从“感觉有用”变成“证据可归因”的实验手段。

十一、运行与复现步骤

在仓库根目录按以下顺序复现实验（npm run dev必须从projects/project-06/solution下执行，它会先构建主进程与渲染进程再打开 Electron；若构建报错先修复 TypeScript/Vite 错误，窗口空白但无构建错误通常是缺少桌面会话的显示环境问题而非产品故障）：

# 1) 弱 harness 基线：手动观察 cd projects/project-06/starter npm install # 运行应用，人工记录弱 harness 行为基线（starter 故意不含 benchmark.sh / cleanup-scanner.sh） # 2) 完整 harness：安装并跑同一套基准 cd ../solution npm install npm run dev # 构建并启动 Electron 应用 # 3) 启动验证（init.sh 五步检查） bash init.sh # 4) 架构边界检查 bash scripts/check-architecture.sh # 5) 干净状态检查 bash scripts/cleanup-scanner.sh # 6) 性能基准 bash scripts/benchmark.sh # 7) 对比 quality-document.md 分数变化

每一步都应记录日志输出，最终把feature_list.json的状态、quality-document.md的评分与evaluator-rubric.md（当前 solution 记录为 5.0/5、15/15 特征 pass）作为“完整 harness 优于弱 harness”的证据链。

十二、结果解读与质量证据

quality-document.md是 solution 的最终质量证据：14 个维度中 13 项 A、测试覆盖 B，总评 A；evaluator-rubric.md给出 5.0/5 总分，并逐项核对了 9 个 harness 文件、3 份文档、14 条 IPC 通道。注意：这些分数是仓库内检入的历史评估记录（日期 2026-03-30），复现时应以你自己的实测为准——这恰恰是 harness 的价值：质量不再靠感觉，而是靠可重复的检查清单、可解析的日志与可对比的基准分数。

综上，Project 06 用一套“完整 harness + 可观测性 + 消融研究”的机制回答了课程的核心问题：Agent 的可靠性上限不取决于提示词技巧，而取决于围绕它构建的、可观测、可恢复、可量化、可维护的工程环境。