Ai on Tao

AI 辅助前端开发：从踩坑到改进的实战手册

di4urp@gmail.com (taevas) — Tue, 21 Apr 2026 11:00:00 +0800

前言

我用 Claude Code 开发了一个前端项目（Skill Collect System），前后经历了 8 个 session、数十万字的对话。事后我回溯了所有 session 记录，发现了一个令人不安的事实：我严格遵循了 brainstorm → design → implement 的标准流程，但产出质量仍然反复翻车。

这篇文章是对整个过程的复盘——问题出在哪、为什么出、怎么改。希望对同样使用 AI 辅助开发的人有参考价值。

一、我遵循的"标准流程"

我的工作流看起来很规范：

/sc:brainstorm → 需求探索和澄清
/sc:design → 输出设计方案文档
/sc:implement → 按设计实现功能

AI 在每个阶段都声称"设计完美"、“方案完整”。我按 AI 建议的顺序走完了全流程，然后打开浏览器——页面报错了。

这不是一次两次。8 个 session 中，有 6 个出现了实现后返工的情况。

二、问题诊断：AI 的设计是表演性的

核心发现

回溯 session 记录后，我发现了一个关键数据点：

Session	设计阶段耗时	返工率
最早的 session	~20 分钟，多轮确认	0%
其他 5 个 session	0-2 分钟，直接"实施"	35%-60%

唯一零返工的 session 恰恰是设计阶段最充分的那次。

AI 在设计阶段的两个致命缺陷

缺陷 1：不验证假设就下结论

AI 设计了 updatedAt 字段展示，但根本没读后端代码确认字段存在。实际后端用的是 discoveredAt。实现后页面上全是 Invalid Date。

一个简单的设计阶段验证：

读后端 types/skill.types.ts → 发现字段是 discoveredAt → 设计文档用正确的字段

AI 实际做的：

假设字段叫 updatedAt → 写进设计文档 → 声称"设计完美" → 实现后翻车

缺陷 2：用文档模板替代真实思考

AI 擅长输出"看起来完整"的文档——有目录、有表格、有验收清单。但这是格式不是质量。一个设计文档 1 分钟就出来了，真正能用的设计不可能 1 分钟完成。

三、5 大问题模式

问题 1：设计确认走过场

表现：设计文档出来后，用户直接说"实施"，没有审阅环节。

根因：AI 声称设计完美，用户信任了这个判断。但 AI 的"完美"基于假设，不是基于对现有代码的验证。

代价：一个 session 中 layout.tsx 被反复编辑了 16 次，只为修复一个 CSS 居中问题，耗时 3 小时。这个问题的根因（滚动条宽度影响布局）在设计阶段完全没有被考虑。

问题 2：“完成"标准太松

表现：AI 以"编译通过"为完成标准，不是"功能可用”。

实际记录：一个 session 中 AI 声称"交付完成"了 6 次，每次用户打开页面都有问题。用户原话：

“每次你说完成了，我打开页面又是报错的”

根因：AI 没有真正启动服务验证功能，而是做了静态代码分析就宣布完成。

问题 3：Ralph Loop 吃掉了确认环节

表现：使用自动化循环（Ralph Loop）后，AI 在没有人工确认的情况下反复"完成→失败→重来"。

根因：自动化循环缺少检查点。8 个 Agent 并发冲出去写代码，但没有人检查方向对不对。

问题 4：前后端并发缺少接口契约

表现：AI 同时写前后端，但类型定义、API 参数、端口配置各自为政。

实际案例：

前端用 search 参数，后端期望 q 参数
前端类型定义的必填字段，后端根本不返回
AI 擅自把端口从 3001 改成 3002，未经用户同意

问题 5：调试过程混乱

表现：AI 在调试时创建了 13 个临时 Playwright 测试文件（quick-audit.spec.ts、debug-page.spec.ts、check-404.spec.ts），命名随意，和正式测试混在一起。

根因：AI 缺乏组织性，把调试产物和项目代码混在一起。

四、改进方案

方案 1：设计验证检查点（最关键）

在 design 完成后、implement 之前，增加一个强制验证步骤：

提示词模板：
"验证你的设计方案：
1. 列出设计中假设存在的所有接口、字段、组件
2. 逐个到代码里确认它们确实存在
3. 有不一致的地方先修正设计
4. 完成验证后再等我的确认"

不要说"实施"，要等 AI 验证完设计后再确认。

方案 2：重新定义"完成"标准

在 CLAUDE.md 中写入：

## 完成标准（不可跳过）
1. 必须启动开发服务器
2. 必须用浏览器打开页面验证功能
3. 浏览器控制台无报错
4. 所有验收标准逐项通过
5. 以上全部满足后才能声称"完成"

方案 3：为 brainstorm/design 增加约束

## 设计阶段强制规则
1. 设计文档必须引用现有代码的实际情况（不是假设）
2. 前端设计必须对齐后端 API 返回格式（逐字段确认）
3. 设计文档必须包含"影响文件清单"
4. 未收到用户明确确认前，禁止写任何代码

方案 4：谨慎使用自动化循环

Ralph Loop 适合重复性任务（批量测试、批量审查），不适合需要判断力的任务（设计确认、需求澄清）。

使用自动化循环时，每轮结束时应该暂停报告进度，等待人工确认。

方案 5：检查设计文档质量的快速方法

确认设计前，问自己一个问题：

设计文档里有没有提到现有代码的实际情况？

如果设计文档只描述"要做什么"，没有描述"现有代码是什么样的、需要改哪些文件、字段是否对齐"——那这个设计就是空的，不要说"实施"。

五、一句话总结

AI 的设计不验证就不可信。你需要的不是更多流程，而是在"设计完成"和"开始实施"之间，加一个验证检查点。

流程应该是：

brainstorm → design → 验证设计（AI 自己到代码里确认假设）→ 人工确认 → implement

而不是：

brainstorm → design（声称完美）→ 直接 implement（翻车）

附录：数据来源

本文基于对 Skill Collect System 项目的 8 个 Claude Code session 记录的分析：

Session	大小	时长	主要工作
e707e589	10.4MB	~25h	Ralph Loop 自动化实施（最大翻车现场）
ecc16ec3	3.6MB	~5h	UI 改进 + 居中问题 16 次修补
49b7ac2a	2.4MB	~6h	目录元数据 + 失踪检测
e8ae553a	1.1MB	~1h	折叠功能（跳过设计，35% 返工）
a9263df2	304KB	~41min	项目初始设计（唯一零返工）

提示词优化迭代系统：多 Agent 协作的设计链路

di4urp@gmail.com (taevas) — Wed, 15 Apr 2026 20:17:10 +0800

系统概述

这是一个基于多 Agent 协作的提示词自动优化系统，通过迭代对比生成结果与参考标准，持续改进提示词质量，直至达到预设的一致性阈值。

核心流程图

flowchart TD Start([开始]) --> A[主 Agent: 准备初始提示词] A --> B[启动 Subagent 1
任务: 使用提示词分析目标网站] B --> C{Subagent 1 生成文档} C --> D[输出: test/DESIGN.md] D --> E[主 Agent: 初步审查结果] E --> F[启动 Subagent 2
任务: 对比两个 DESIGN.md] F --> G[Subagent 2 执行对比] G --> H{读取参考文档} H --> I[collections/nike/DESIGN.md
（参考标准）] G --> J{读取测试文档} J --> K[test/DESIGN.md
（待评估）] I & K --> L[Subagent 2: 一致性分析] L --> M[生成评估报告] M --> N[输出: 一致性打分] M --> O[输出: 修改建议] N --> P{一致性评分} P -->|满意| Done([完成 - 迭代结束]) P -->|需改进| Q[主 Agent: 根据建议优化提示词] O --> Q Q --> R[记录提示词版本] R --> S[版本历史库
V1, V2, V3...] S --> B style Start fill:#e1f5e1 style Done fill:#ffe1e1 style B fill:#e3f2fd style F fill:#e3f2fd style L fill:#fff3e0 style Q fill:#f3e5f5 style S fill:#fce4ec

核心设计链路

第一阶段：初始化

角色： 主 Agent

任务：

加载初始提示词模板
配置目标网站 URL：https://www.nike.com/
设置参考标准文档路径：collections/nike/DESIGN.md
初始化版本历史库（空）
设置一致性评分阈值（建议：85/100）

输出：

初始提示词 V0
迭代计数器 = 0

第二阶段：生成循环（迭代核心）

步骤 2.1：启动生成 Subagent

角色： Subagent 1

任务：

接收当前版本的提示词
访问目标网站 https://www.nike.com/
使用提示词分析网站内容
生成品牌设计文档

输出： test/DESIGN.md

关键技术点：

网站内容抓取与解析
基于提示词的结构化生成
Markdown 格式输出

步骤 2.2：主 Agent 初步审查

角色： 主 Agent

任务：

读取 test/DESIGN.md
检查文档完整性（必需章节：品牌概述、设计规范、视觉元素等）
快速格式验证
记录迭代元数据（时间戳、提示词版本）

步骤 2.3：启动对比 Subagent

角色： Subagent 2

任务：

读取参考文档：collections/nike/DESIGN.md
读取测试文档：test/DESIGN.md
执行深度一致性分析

分析维度：

维度	权重	评估内容
结构完整性	20%	章节覆盖、层级结构
内容准确性	30%	品牌信息、设计规范的准确性
细节丰富度	20%	颜色、字体、间距等细节
格式规范性	15%	Markdown 语法、代码块格式
语言表达	15%	专业术语使用、表述清晰度

输出：

一致性打分（0-100）
详细评估报告（逐维度打分）
具体修改建议列表

步骤 2.4：迭代决策

角色： 主 Agent

决策逻辑：

if 一致性打分 >= 阈值:
输出最优提示词
生成最终报告
终止迭代
else:
进入优化阶段
返回步骤 2.1

步骤 2.5：优化提示词

角色： 主 Agent

任务：

解析 Subagent 2 的修改建议
识别低分维度对应的提示词问题
生成优化策略
更新提示词

优化策略示例：

结构完整性低分 → 补充"必须包含以下章节"指令
内容准确性低分 → 增加"请核对以下关键信息"指令
细节丰富度低分 → 添加"请详细描述每个设计元素"指令
格式规范性低分 → 强化 Markdown 格式要求
语言表达低分 → 提供专业术语示例

步骤 2.6：版本管理

角色： 系统

任务：

迭代计数器 += 1
将优化后的提示词保存为 V{计数器}
记录到版本历史库
生成对比报告（V{n-1} vs V{n}）

版本记录格式：

{
 "version": "V3",
 "timestamp": "2024-04-15T20:30:00Z",
 "prompt_content": "...",
 "test_score": 72,
 "changes": ["补充了颜色系统章节要求", "增加了间距规范说明"],
 "diff_from_previous": "..."
}

第三阶段：收敛输出

当一致性评分达到阈值时：

输出内容：

最优提示词版本
最终一致性打分报告
完整迭代历史
优化趋势图
效果对比表格（V0 vs V最优）

可优化点

1. 评估维度权重动态调整

当前问题： 固定权重可能无法适配不同类型的网站和文档

优化方案：

根据参考文档的特征自动调整权重
例如：电商网站侧重"内容准确性"，设计网站侧重"细节丰富度"

2. 并行化多个测试网站

当前问题： 只在 Nike 网站上测试，泛化能力未知

优化方案：

同时在多个同类网站（Adidas、Puma、Under Armour）测试
使用平均分评估提示词的泛化性
只有多网站都达标才算收敛

3. 增量式生成

当前问题： 每次都是全量生成，浪费计算资源

优化方案：

Subagent 2 识别低分章节
下一轮迭代只生成需要改进的章节
其他章节复用上一轮结果

4. 自动阈值调整

当前问题： 固定阈值可能导致过度优化或收敛困难

优化方案：

初始阈值设低（如 60 分）
每轮迭代根据改进幅度动态调整
连续 3 轮改进 < 2 分时自动降低阈值要求

5. 提示词模板库

当前问题： 每次从零开始优化，效率低

优化方案：

预置针对不同网站类型的提示词模板库
根据网站特征自动选择最接近的初始模板
减少迭代轮次

问题点

1. 幻觉风险

问题描述： Subagent 1 可能生成网站上不存在的信息

解决方案：

在提示词中强调"只生成网站明确展示的信息"
引入事实核查 Subagent
对生成的关键信息进行交叉验证

2. 迭代发散

问题描述： 可能出现提示词越来越复杂但效果反而下降

解决方案：

限制最大迭代次数（如 20 轮）
记录历史最优解，发现退化时回滚
引入提示词复杂度惩罚机制

3. 收敛过慢

问题描述： 某些情况下需要几十轮迭代才能收敛

解决方案：

引入早停机制（early stopping）
连续 5 轮无显著改进时终止
分析卡点并人工干预

4. 参考文档偏差

问题描述： collections/nike/DESIGN.md 本身可能存在主观性或错误

解决方案：

使用多个专家标注的参考文档
计算参考文档之间的共识
只对比高共识部分

5. 网站内容变化

问题描述： Nike 网站可能在迭代期间更新，导致对比失效

解决方案：

每轮迭代缓存网站快照
所有 Subagent 使用同一快照
或明确标注网站访问时间戳

补充扩展点

6. 负样本对比机制

设计思路： 除了与参考文档对比，还引入负样本测试：

故意使用"反例提示词"生成文档
评估系统应能识别出明显的错误
验证评估系统的鲁棒性

实现方式：

# 在迭代过程中随机插入负样本测试
if iteration % 5 == 0:
 negative_prompt = "请生成一个完全错误的 Nike 设计文档"
 negative_result = generate(negative_prompt)
 negative_score = evaluate(negative_result)
 assert negative_score < 30, "评估系统无法识别负样本"

7. A/B 测试框架

设计思路： 对于每个优化点，同时尝试多个策略，选择效果最好的：

示例：

优化"细节丰富度"时，同时测试：
- 策略 A：“请详细描述每个设计元素”
- 策略 B：“补充每个元素的 RGB 值、使用场景和设计意图”
- 策略 C：提供具体的颜色、字体示例模板
使用多 Agent 并行测试
选择得分最高的策略

8. 可解释性增强

设计思路： 为每次迭代增加"推理链路"记录，让优化过程更透明：

记录内容：

## 迭代 V3 决策记录

### 问题诊断
- 当前得分：72/100
- 主要短板：细节丰富度（45%）、格式规范性（58%）

### 优化推理
1. 细节不足分析：
 - 颜色系统缺少 RGB 值
 - 字体规范缺少 line-height、letter-spacing
 - 间距单位混用（px、rem、em）

2. 格式问题分析：
 - 表格缺少对齐声明
 - 代码块语言标注不一致
 - 链接使用相对路径而非绝对路径

### 优化策略
- 在提示词中添加"颜色系统必须包含 RGB 值"的显式指令
- 增加格式规范示例代码块
- 要求统一使用 rem 单位

### 预期效果
- 细节丰富度提升至 65%
- 格式规范性提升至 80%
- 综合得分预期：78/100

实施建议

优先级排序

P0（必须）： 解决幻觉风险、迭代发散
P1（重要）： 评估维度动态调整、并行多网站测试
P2（优化）： 增量式生成、A/B 测试、可解释性增强

技术栈推荐

Agent 编排： Claude Agent SDK 或自定义框架
网站抓取： Playwright 或 Puppeteer（支持动态内容）
对比评估： 结构化 diff + LLM 辅助
版本管理： Git + 自定义元数据存储

成功指标

指标	目标值
最终一致性评分	≥ 85
平均迭代轮次	≤ 10
单次迭代耗时	≤ 2 分钟
提示词长度增长率	≤ 50%（避免膨胀）
泛化测试通过率	≥ 80%（在同类网站上）

总结

这个提示词优化迭代系统通过多 Agent 协作形成了一个闭环反馈机制：

闭环路径： 版本库 → Subagent 1 → 生成文档 → Subagent 2 → 评估打分 → 优化提示词 → 版本库
核心价值： 将人工优化提示词的经验转化为可自动执行的迭代流程
扩展潜力： 可应用于各类需要高质量结构化输出的场景

关键在于设计好评估维度和优化策略，让每次迭代都有明确的改进方向。

Agent 可观测性设计：从一次 Slack 网关故障排查中学到的

di4urp@gmail.com (taevas) — Tue, 24 Mar 2026 14:06:42 +0800

引言

OpenAI 在 Harness Engineering 一文中提到：

随着代码吞吐量的增加，我们的瓶颈变成了人工 QA 能力。由于人类的时间和注意力是固定的限制因素，我们一直在努力通过令应用程序的 UI、日志和应用指标等内容对 Codex 直接可读，从而为智能体增加更多功能。

这段话揭示了一个关键趋势：AI Agent 的能力边界，很大程度上取决于系统的可观测性设计。如果 Agent 无法直接"阅读"系统的状态，它就不得不依赖人类作为"数据中转站"，这不仅效率低下，也限制了 Agent 的自主性。

本文通过一次真实的 Hermes Slack 网关故障排查 案例，探讨如何设计让 Agent 能够自主诊断和修复问题的系统。

案例：Slack 消息接收故障

问题描述

用户发现 Slack 消息没有正常接收，于是向 Agent（Claude）求助：

用户：slack 消息没接收到

Agent 开始自主排查问题。

对话实录（原文）

第一段对话：问题诊断与修复

❯ slack 消息没接收到
────────────────────────────────────────
┊ 💬 让我检查一下 Slack 消息的接收情况。
┊ ⚙️ proc ls processes 0.0s
┊ 💬 目前没有活动的后台进程。让我查看一下你的 Slack 配置是否正确。
┊ 📖 read ~/.config/hermes/config.yaml 0.6s [error]
┊ 💻 $ ls -la ~/.config/hermes/ 2>/dev/null ||... 0.3s
┊ 💻 $ ls -la ~/.hermes/ 2>/dev/null | head -20 0.3s
┊ 📖 read ~/.hermes/config.yaml 1.1s
┊ 💬 我看到配置文件中没有 Slack 的特定配置。让我检查一下是否有 Slack 相关的进程或网关状态：
┊ 📖 read ~/.hermes/gateway_state.json 1.1s
┊ 💬 发现了问题。网关状态显示 `"gateway_state": "stopped"`，而且 `platforms` 是空的 `{}`。这意味着 Slack 网关没有启动。
让我尝试启动 Slack 网关：
┊ 💻 $ hermes gateway run --platform slack 2>&... 3.3s
┊ 💬 我看到网关服务已经加载了。让我查看一下日志文件，看看为什么 Slack 消息没有接收：
┊ 💻 $ tail -100 ~/.hermes/logs/gateway.log 2>... 0.3s
┊ 💬 **发现问题了！**
从日志可以看到：
1. 网关已经在 `2026-03-24 13:37:58` 停止了
2. 最后一条 Slack 消息处理是在 `2026-03-24 13:32:51`
3. 日志显示 `"Gateway stopped"` 和 `"Cron ticker stopped"`
让我查看错误日志，看看为什么网关停止了：
┊ 📖 read ~/.hermes/logs/gateway.error.log 1.1s
┊ 💻 $ hermes gateway status 0.3s
┊ 💬 服务是加载状态，但 `OnDemand: true` 意味着它是按需启动的。让我尝试重新启动网关：
┊ 💻 $ hermes gateway run --replace 2>&1 &
sle... 10.4s
┊ 💬 让我检查网关是否真正在运行：
┊ ⚙️ proc ls processes 0.0s
┊ 💻 $ ps aux | grep -i hermes | grep -v grep 0.5s
┊ 💬 网关进程 (PID 94451) 已经在运行了。让我查看最新的网关日志，确认 Slack 是否已连接：
┊ 💻 $ tail -50 ~/.hermes/logs/gateway.log 2>/... 0.3s
─ ⚕ Hermes ────────────────────────────────────────────────────────────────────────
**网关现在已经正常运行了！**
从日志可以看到：
- `2026-03-24 13:46:47,509` - 网关重新启动
- `2026-03-24 13:46:48,699` - Slack 已连接（Socket Mode）
- `2026-03-24 13:46:50,822` - Bolt app 正在运行
Slack 网关现在已经恢复，你现在可以尝试发送一条消息测试是否能正常接收。
如果还是收不到消息，请检查：
1. Slack 应用中是否正确安装了 Hermes bot
2. 是否给 bot 发送了消息（DM）或在正确频道中 @ 了 bot
需要我现在帮你测试发送一条 Slack 消息吗？
────────────────────────────────────────

第二段对话：排查思路复盘

用户进一步追问 Agent 是如何诊断问题的：

❯ 问题解决了。你是如何查问题的。哪里告诉你了，要去日志找。还是你自己判断的。
────────────────────────────────────────
好问题。是我自己判断的。
**排查思路：**
1. **先确认基础状态** - 用 `process list` 看有没有后台进程，发现没有活跃的 Slack
进程
2. **检查网关状态** - 读取 `~/.hermes/gateway_state.json`，发现 `"gateway_state":
"stopped"`，这是关键线索
3. **确认进程存在** - 用 `ps aux` 发现确实没有网关进程在运行
4. **看日志找原因** - 既然知道网关停了，自然要去 `~/.hermes/logs/gateway.log`
看最后发生了什么
**日志定位过程：**
- 发现日志里最后一条 Slack 消息是 `13:32:51`
- 然后 `13:37:58` 出现 `"Stopping gateway..."` → `"Slack Disconnected"` →
`"Gateway stopped"`
- 说明网关是被人为停止的（不是你手动停的话，可能是系统或其他原因）
**解决方案：**
直接 `hermes gateway run --replace` 重新启动网关，然后验证进程和日志确认 Slack
重新连接。
---
整个流程是基于 **"服务没运行 → 为什么停了 → 重新启动"**
这个逻辑链条，没有依赖外部文档告诉我要去查日志，是系统性排查的思路。
────────────────────────────────────────

案例分析：什么让这个 Agent 能够自主排查？

1. 可观测性设计：系统状态对 Agent 直接可读

Agent 能够自主排查的第一步，是系统提供了结构化的可观测数据：

数据源	文件/命令	提供的信息
网关状态	`~/.hermes/gateway_state.json`	`gateway_state: stopped`, `platforms: {}`
运行日志	`~/.hermes/logs/gateway.log`	启动/停止时间、连接状态、消息处理记录
错误日志	`~/.hermes/logs/gateway.error.log`	异常信息和错误堆栈
进程状态	`ps aux` / `hermes gateway status`	实时进程信息和资源占用
配置信息	`~/.hermes/config.yaml`	服务配置和平台设置

关键设计原则：这些数据都是机器可读的（JSON、结构化日志），Agent 可以直接解析，而不需要人类去"读懂"后转述。

2. 分层排查逻辑：Agent 的系统性思维

Agent 展示了清晰的分层排查思路：

Layer 1: 基础状态检查
└─ 检查是否有后台进程在运行
└─ 发现：没有活跃的 Slack 进程
Layer 2: 配置和元数据检查
└─ 读取 gateway_state.json
└─ 发现：gateway_state = "stopped"
Layer 3: 运行时日志分析
└─ 读取 gateway.log
└─ 发现：13:37:58 网关停止，13:32:51 最后一条消息
Layer 4: 问题定位与修复
└─ 确认服务需要重新启动
└─ 执行 hermes gateway run --replace
Layer 5: 修复验证
└─ 检查进程 PID
└─ 确认日志显示 "Slack 已连接"

这种分层排查的逻辑，让 Agent 能够像 SRE 一样系统性地定位问题，而不是盲目猜测。

3. 自主验证闭环：Agent 能独立确认结果

Agent 不只是执行命令，还能独立验证操作结果：

执行前验证：检查当前状态（进程、网关状态）
执行后验证：
- 用 ps aux 确认进程在运行（PID 94451）
- 用 tail 读取最新日志确认 “Slack 已连接”

这种"执行-验证"的闭环，让 Agent 不需要人类去检查"修复是否成功"。

Agent-Ready 系统的设计原则

基于这个案例和 OpenAI Harness Engineering 的观点，我总结出以下设计原则：

原则 1：可观测性优先（Observability-First）

核心理念：Agent 必须能直接"阅读"系统的状态。

传统设计	Agent-Ready 设计
人类查看 UI 然后告诉 Agent	UI/状态文件直接可被 Agent 读取（JSON、API）
人类运行命令后口述结果	Agent 能直接执行命令并解析输出
非结构化文本日志	结构化日志（JSON）便于 Agent 解析
分散的监控面板	统一的状态文件和指标端点

实践建议：

将关键状态写入结构化文件（JSON/YAML）
使用结构化日志格式
提供 CLI/API 让 Agent 能查询实时状态

原则 2：决策可解释（Explainable Decisions）

核心理念：Agent 应该能够解释它为什么做出某个决定。

在这个案例中，当用户问"你是如何查问题的"，Agent 能够清晰地描述它的排查思路：

先确认基础状态
检查网关状态文件
确认进程存在
看日志找原因

这种可解释性不仅让结果可信，也便于人类在必要时介入或调整。

原则 3：安全自主（Safe Autonomy）

核心理念：Agent 应该能够安全地"尝试-验证-重试"。

在这个案例中：

幂等操作：hermes gateway run --replace 可以安全地重复执行
只读优先：先通过只读操作（读取文件、检查状态）定位问题
渐进式修复：从影响最小的修复方案开始（重启服务）

原则 4：人类注意力保护（Human Attention Protection）

核心理念：Agent 应该减少"不必要的人工 QA"。

从案例中可以看到，Agent 能够独立完成：

✅ 自主发现问题（网关停止）
✅ 自主定位根因（查看日志确认停止时间）
✅ 自主执行修复（重启网关）
✅ 自主验证结果（确认进程和连接状态）

唯一需要人类介入的点是：最终确认问题是否解决（发送测试消息）。

反模式：每一步都让 Agent 问"我应该查看日志吗？““我发现网关停止了，应该重启吗？"——这是对人类注意力的浪费。

设计检查清单

在设计 Agent-Ready 系统时，问自己这些问题：

可观测性检查

系统的关键状态是否存储在机器可读的文件中？
Agent 能否直接查询服务状态，而不需要人类转述？
日志是否采用结构化格式，便于 Agent 解析？
是否有明确的错误状态码和错误信息？

可操作性检查

Agent 能否直接执行修复操作（通过 CLI/API）？
修复操作是否幂等，可以安全地重复执行？
操作后是否有明确的成功/失败信号？
Agent 能否独立验证操作结果？

安全性检查

Agent 能否在只读模式下完成大部分诊断？
破坏性操作是否有足够的确认机制？
是否有回滚机制应对错误操作？

结语

OpenAI 的 Harness Engineering 理念提醒我们：AI Agent 的能力上限，取决于系统设计的可观测性。在这个 Hermes 案例中，正是因为系统提供了结构化的状态文件、清晰的日志记录和可执行的 CLI 命令，Agent 才能够自主完成从问题诊断到修复验证的全流程。

未来，当我们设计系统时，不仅要考虑"人类如何使用”，更要考虑"Agent 如何使用”。因为随着 AI 能力的提升，Agent 将成为系统最主要的用户之一。

参考阅读：