企业官网建设流程全解析

导读

这篇技术指南围绕 learn-harness-engineering 仓库中的标准操作流程（SOP）文档 observability-feedback-loop.md 展开，讲解如何为编码 Agent 构建一条"日志—指标—追踪—可重复负载"的本地反馈回路，让 Agent 从"只看代码"升级为"从运行证据推理"。文中将以仓库的实践项目 Project 06 为实例，展示结构化日志、基准脚本、清理扫描器等真实实现，读完你可以直接在自己的 harness 中落地这套可观测性反馈回路，并写出符合 RELIABILITY.md 要求的可靠性文档。

一、为什么要给 Agent 一条可观测性反馈回路

1.1 没有可观测性时，调试为什么这么慢

当出现以下三种症状时，就应该启用这条 SOP：

• 调试很慢：改一行代码要反复猜测、反复重启才能定位问题；
• Agent 反复宣称"成功了"却没有证据：没有日志、没有指标、没有可重复的运行结果，Agent 只能凭代码印象下结论；
• 运行时行为比代码本身更难检查：代码审查只能看到"写的是什么"，运行时追踪才能看到"实际跑的是什么"。

课程 Lecture 11: Making the Agent's Runtime Observable 明确指出：当 Agent 在执行任务时看不到真实的运行时状态，它的每一个决策本质上都是猜测。缺少可观测性会系统性地产生四类问题——无法区分"正确"与"看起来正确"、评估变成主观玄学、重试变成盲目的乱撞、会话交接时新会话要从零开始诊断（据观察这类冗余诊断可能浪费 30%～50% 的会话时间）。

1.2 SOP 的目标

本 SOP 的目标很明确：

给 Agent 一个围绕日志（logs）、指标（metrics）、追踪（traces）和可运行负载（runnable workloads）的本地反馈回路，使它能够从执行结果推理，而不是仅仅从代码检查推理。

也就是说，可观测性不是"多加几行日志"，而是让 Agent 的每次决策都有运行时证据支撑。

二、最小可观测性技术栈（Minimum Stack）

SOP 给出的最小技术栈包含五个组成部分，缺一不可：

其中最后一项"可重复负载"是关键：它把"我修好了"从口头声明变成可复现的事实——同一份负载，在每次改动后重新执行，通过与否一目了然。

三、SOP 执行步骤：七步建立反馈回路

SOP 给出了七步执行流程，每一步都有明确的产出物：

1. 定义最重要的 golden 运行时场景（golden runtime journeys）：确定哪些用户旅程是系统健康的基准。Project 06 的 benchmark.sh 定义了 import（导入吞吐）、index（批量索引速度）、query（问答延迟）、verify（数据完整性）四个黄金场景。
2. 在启动路径和关键路径上加入结构化日志：启动时的服务初始化、关键业务操作都要留痕。
3. 在有用之处加入延迟、失败数或队列深度指标：例如批量索引完成时记录throughput（chunks/sec），Q&A 回答生成时记录durationMs和confidence。
4. 为慢流程或多步流程加入追踪或时间标记：Project 06 用Date.now()记录每个阶段耗时（见 indexing-service.ts 中的startTime/duration），更完整的方案是用 OpenTelemetry 为每个会话建 trace、每个任务建 span。
5. 让信号从本地开发环境可查询：Agent 应能通过命令或 IPC 主动查询运行时状态，而不是只靠被动看终端输出。
6. 给 Agent 一个可重复的负载或场景用于重跑：bash scripts/benchmark.sh就是这样一个可重复负载。
7. 强制要求闭环：查询 -> 关联 -> 推理 -> 实现 -> 重启 -> 重跑 -> 验证。缺少任何一环，反馈回路就不成立。

其中第 7 步的闭环是整个 SOP 的灵魂。它要求 Agent 的每一次修复都走完一圈：先查询信号定位问题，再关联信号与代码层，基于证据推理根因，实现修复后重启应用，重跑同一份负载，最后用新的信号验证修复确实生效。

四、调试会话检查清单（Debug Session Checklist）

当一次调试会话结束时，SOP 要求逐项回答以下六个问题，确保不是"感觉修好了"而是"证据上修好了"：

• 什么失败了？（What failed?）
• 哪个信号证明了失败？（Which signal proves the failure?）——必须有具体的日志条目、指标或追踪片段作证；
• 失败属于哪一层？（Which layer owns the failure?）——是 UI、IPC、服务层还是持久化层？Project 06 的架构分层见 ARCHITECTURE.md 与 AGENTS.md 中的 Electron 层边界；
• 修复后什么发生了变化？（What changed after the fix?）——对比修复前后的信号差异；
• 应用是否干净地重启了？（Did the app restart cleanly?）——启动日志是否无 ERROR；
• 同一份负载重跑后是否通过？（Did the same workload pass after rerun?）——重跑 benchmark 确认。

这套清单把"调试完成"的定义从主观感受切换为可验证证据，与课程 Lecture 09 强调的"过早宣布胜利"问题直接对应。

五、Definition of Done：什么时候这条 SOP 算落地

SOP 给出了四条完成标准：

1. Agent 能基于运行时证据解释故障模式——能指出具体是哪条日志、哪个指标证明了失败；
2. 同一份负载能在每次改动后重跑——benchmark 脚本随时可执行；
3. 重启和重跑是普通任务循环的一部分——不是额外步骤，而是默认流程；
4. 可靠性信号被记录在docs/RELIABILITY.md中——把信号源、验证命令、golden journeys 固化进文档。

第四点正是仓库中 repo-template 的 RELIABILITY.md 模板所要求的：它规定了标准路径（bootstrap/verification/run/debug 四条命令）、强制运行时信号（结构化日志、健康检查、追踪/计时数据、用户可见的错误状态）、golden journeys 列表，以及三条可靠性规则——"没有任何功能在系统不能干净重启后算完成"、"运行时故障必须能用仓库本地信号诊断"、"反复出现的故障模式要加 benchmark 或限制器"。

六、仓库实践：Project 06 的完整可观测性落地

Project 06 是本仓库的实践项目（Capstone），其 solution 目录完整实现了上述 SOP 的每一项要求，是理解"反馈回路长什么样"的最佳样例。

6.1 结构化日志：从console.log到机器可解析 JSON

日志系统的实现在 src/services/logger.ts：

• 定义DEBUG / INFO / WARN / ERROR四个级别，由LEVEL_ORDER数组决定过滤规则（shouldLog）；
• 每条日志输出为单行 JSON：{ "timestamp", "level", "service", "message", "data" }；
• 通过logger.forService('document-service')得到按服务隔离的子 Logger，保证日志带统一的服务标签；
• 单例logger从环境变量LOG_LEVEL读取最低级别，默认DEBUG。

典型的 JSON 日志条目（见 RELIABILITY.md）：

{ "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 } }

日志级别使用约定：

6.2 指标：关键路径上的量化信号

指标不是独立设施，而是从日志的data字段中携带的量化值。从源码可以看到指标埋点：

• indexing-service.ts 在批量索引完成时记录durationMs与throughput（chunks/sec）；
• qa-service.ts 在回答生成时记录durationMs、confidence（置信度）、citationCount、answerLength——其中confidence: citations.length > 0 ? 0.85 : 0.3直接量化了"回答有没有依据"；
• document-service.ts 在导入时记录sizeBytes、contentLength、totalDocuments。

6.3 追踪/时间标记：慢路径与多步流程

Project 06 目前用Date.now()计时器作为轻量追踪（例如导入、索引、问答三个阶段各记录startTime与duration），这对应 SOP 第 4 步的"时间标记"。

课程 Lecture 11 给出了更标准化的升级路径：用OpenTelemetry为每个 harness 会话建一个 trace，每个任务建一个 span，每个验证步骤建子 span，并用标准属性标注关键信息，使可观测性数据能接入 Jaeger、Zipkin 等标准工具链。这与 SOP 的最小栈一脉相承——先有时间标记，再平滑演进到标准追踪。

6.4 查询接口：让信号可被"问"

Project 06 通过 Electron IPC 提供 14 个查询通道（定义在 src/shared/types.ts 的IPC_CHANNELS常量，注册于 ipc-handlers.ts）：

• 读类操作（DEBUG 级别）：documents:list、documents:get、indexing:status、indexing:chunks、qa:history、feedback:list、app:status；
• 写类操作（INFO 级别）：documents:import、documents:delete、indexing:start、qa:ask、qa:clear-history、feedback:submit、app:reset。

值得注意的是 ipc-handlers.ts 中每个 handler 都以结构化日志记录自己的调用（例如logger.info(SERVICE, 'IPC: IMPORT_DOCUMENT', { filePath })），且RESET_DATA使用 WARN 级别提示这是破坏性操作——这本身就演示了"让 Agent 的每次交互也变成可观测信号"。

6.5 可重复负载：benchmark.sh

scripts/benchmark.sh 是 SOP 第 6 步的完整实现——一个不依赖 Electron 窗口、直接用文件模拟服务层操作的可重复负载：

运行方式：

bash scripts/benchmark.sh

示例输出：

=== Benchmark Results === [import] 3 files: 120ms (25.0 files/sec) [index] 3 documents: 80ms (175.0 chunks/sec) [query] 5 questions: 1250ms (250.0ms avg) [verify] Data integrity: PASS === Summary: 4/4 tasks passed ===

这就是 SOP 要求的"同一份负载可以反复重跑"：每次 Agent 改动后重跑 benchmark，用量化结果代替口头宣称。

6.6 清理扫描器：反馈回路的卫生保障

scripts/cleanup-scanner.sh 对应 RELIABILITY.md 中的规则"清理是可靠性的一部分，而不是独立事项"。它检查六类数据一致性问题：

运行方式：bash scripts/cleanup-scanner.sh [data-dir]（未提供参数时使用 Electron 默认 userData 路径，如 Linux 的~/.config/knowledge-base/knowledge-base-data）。输出类似：

=== Cleanup Scanner === [OK] No orphaned content files [OK] No dangling chunk files [OK] No missing content files [OK] All indexed documents have chunk files [OK] No stale Q&A references === Result: CLEAN (0 issues) ===

七、落地清单：在你自己 harness 中启用本 SOP

参考 Project 06 的 AGENTS.md 启动规则（在写任何代码前先读文档、跑init.sh验证构建、读feature_list.json了解功能状态），以及 RELIABILITY.md 的三块内容，落地本 SOP 的检查顺序是：

1. 日志：所有服务统一走结构化 JSON 日志，带level、service、data字段；LOG_LEVEL环境变量可调节输出（LOG_LEVEL=INFO npm run dev只显示 INFO/WARN/ERROR）；
2. 指标/追踪：在启动、关键路径、慢流程处埋点（至少是时间标记，最好是 OpenTelemetry span）；
3. 查询接口：提供可编程查询通道（如 IPC 或 CLI 命令），让 Agent 能主动"问"运行时；
4. 可重复负载：准备一个 benchmark 脚本或用户旅程脚本，每次改动后重跑；
5. 清理与干净状态：调试后运行清理扫描器，必要时走RESET_DATA通道重置数据，再验证 clean-state-checklist.md；
6. 文档化：把标准路径命令、强制运行时信号、golden journeys 和可靠性规则写进docs/RELIABILITY.md。

八、关键要点回顾

• 可观测性是 harness 的架构属性，不是事后补的功能——它必须从设计之初就内建；
• 反馈回路要求"信号可查询 + 负载可重跑"两者齐备，缺一 Agent 就只能回到猜代码；
• 闭环七步（查询 → 关联 → 推理 → 实现 → 重启 → 重跑 → 验证）是调试质量的下限保障；
• 结构化日志是地基：单行 JSON、级别分层、按服务打标签，才能支撑后续的关联与查询；
• 可靠性文档是收尾：把 golden journeys 和验证命令固化进docs/RELIABILITY.md，让"健康"有明确定义、可复现、可传承。

延伸阅读

• 更完整的可观测性理论：本 SOP 所属的 OpenAI Advanced SOPs 目录，以及课程 Lecture 11: Making the Agent's Runtime Observable（含 sprint contract、evaluator rubric、Anthropic 三 Agent 架构实验的详细数据）；
• 可靠性模板：RELIABILITY.md 模板；
• 完整实践：Project 06 解决方案目录，重点阅读 docs/RELIABILITY.md、src/services/logger.ts、scripts/benchmark.sh 与 scripts/cleanup-scanner.sh。