Agent Harness Architect 🏗️#

基于 Anthropic《Effective Harnesses for Long-Running Agents》论文提炼。 把你的 agent 架构描述给它，输出完整 harness 诊断报告 + 可直接部署的 bridge artifact 文件。

---

核心主张#

模型是商品，harness 才是壁垒。

再强的模型，没有好的 harness，长时间运行都会退化——过早宣告完成、环境退化、session 交接信息丢失。这个 skill 把 Anthropic 工程团队踩坑总结的最佳实践，变成你的 agent 可直接执行的升级方案。

---

触发条件#

用户描述中出现以下任意一种：

• "我的 agent 跑着跑着就失败了 / 忘了之前做了什么"
• "每次新 session 都要重新开始"
• "帮我优化 agent 架构"
• "如何让 agent 跨 session 保持状态"
• 用户粘贴了自己的 CLAUDE.md / AGENTS.md / agent 配置

---

执行流程#

Step 1 — 架构摸底（必须先问，不能跳过）#

向用户提以下问题（可一次性发出，不要逐条等待）：

text

要帮你把 agent 架构调到最优，我需要了解几个关键点：

1. **角色分工**：你有几个 agent？每个负责什么？（比如：一个规划、一个执行、一个监控）
2. **运行周期**：任务通常跑多久？是分钟级 session，还是需要跨多天？
3. **当前最大痛点**：session 中断丢进度？agent 以为做完了实际没做好？不知道上次跑到哪？
4. **现有状态管理**：有没有 progress 文件、日志、git commit？还是全靠模型上下文记忆？
5. **平台**：OpenClaw / Claude Code / 其他？操作系统？

Step 2 — Harness 健康度诊断#

根据用户回答，对照以下 8 个维度逐一打分（✅ 已有 / 🟡 部分 / ❌ 缺失）：

维度诊断问题Session Bridge每次新 session 启动时，有没有结构化文件（非纯文本）告知"上次做到哪了"？固定启动序列agent 每次启动是否有强制执行的固定步骤顺序（不可跳过）？Smoke Test执行任务前，有没有先验证环境/依赖是否可用？原子 Checkpoint每完成一个最小单元，是否立即 commit/保存状态？输出自验证agent 报告"完成"之前，有没有机制验证结果真的 OK？状态文件格式状态追踪用 JSON 还是 Markdown checkbox？（JSON 更防 agent 误改）Multi-Agent 编排多个 agent 之间有没有明确的消息传递协议，还是靠文件系统凑合？降级方案某个依赖挂掉时，有没有明确的 fallback 行为？

输出诊断表，标出每个维度的分数和简要原因。

Step 3 — 优先级排序#

根据诊断结果，按 影响 × 实现难度 矩阵输出 P0/P1/P2 改进项：

P0（立刻改，成本低收益高）：通常是 Session Bridge + 固定启动序列 P1（本周改）：Smoke Test + 原子 Checkpoint P2（下阶段）：输出自验证 + Multi-Agent 编排协议

Step 4 — 生成 Bridge Artifacts#

必须生成以下文件内容，用户可直接复制部署：

4a. agent-progress.json（Session 状态桥）

json

{
  "_说明": "Agent Session 状态桥。每次 session 启动时读取，结束时更新。JSON 格式防止 agent 误改结构。",
  "schemaVersion": "1.0",
  "lastSession": {
    "timestamp": null,
    "trigger": null,
    "summary": "首次初始化",
    "smokeTest": null,
    "result": "pending"
  },
  "taskTracking": {
    "_说明": "每完成一个任务后在此更新。status: pending|in_progress|done|failed",
    "recentCompleted": []
  },
  "environmentStatus": {
    "lastChecked": null,
    "result": null,
    "notes": null
  },
  "knownIssues": []
}

4b. Session 恢复协议（插入你的 CLAUDE.md / AGENTS.md）

markdown

### Session 恢复协议（每次会话强制执行，顺序不可跳过）

**Step 1 — 读状态桥**：读 `agent-progress.json`，了解上次 session 执行到哪、哪些成功、哪些失败。

**Step 2 — 读任务队列**：读当前待办任务列表，确认优先级。

**Step 3 — Smoke Test**：验证核心环境可用（服务在线？API 可达？依赖存在？）。
不通过 → 先修复环境，不执行任何业务任务。

**Step 4 — 逐任务执行**：每次只执行一个任务，完成后立即：
  - 更新 agent-progress.json 中该任务状态为 done
  - git commit 一次（message 用任务编号）
  - 再执行下一个任务

**Step 5 — Session 结束**：更新 agent-progress.json 的 lastSession 字段，记录本次执行摘要。

4c. Output Self-Verification Gate（输出自检，插入消息处理流程末尾）

markdown

【output-gate】——准备发出任何内容前，内部思考检查（不输出）：
  ├── 是否包含应对外保密的系统内部术语？→ 有则重写
  ├── 是否把思考过程当成了结论发出？→ 有则删除过程只保留结论
  └── 当前上下文是否应该静默（规则明确不该回复的场景）？→ 是则 NO_REPLY
结论: 发出 / NO_REPLY / 已修改后发出

Step 5 — 针对用户平台的定制建议#

根据用户平台输出具体命令/配置，例如：

OpenClaw 用户：

powershell

# 检查 gateway 状态（Smoke Test）
openclaw status

# 每个任务完成后立即 commit
git add -A && git commit -m "done: [任务编号] [任务描述]"

Claude Code 用户：

bash

# 在 CLAUDE.md 中添加 session 恢复协议
# 使用 JSON 格式跟踪任务状态，而非 Markdown checkbox

通用建议：

• 状态文件用 JSON，不用 Markdown（agent 更不容易意外破坏结构）
• 每个 session 的前 N 步必须是固定的，写进系统提示，不可跳过
• "完成"报告前必须有端到端验证，不能只看代码改了

---

自动优化循环（Self-Improvement Protocol）#

此 skill 内置进化机制：

触发条件#

以下情况发生时，自动写入 capability-radar 或等效的学习日志：

• 用户描述的问题在本 skill 覆盖范围外 → 记录为功能缺口
• 用户反馈生成的方案不够具体 → 记录为精度缺口
• 同类架构问题出现 3 次以上 → 触发模式提炼，更新此 skill

版本演进规则#

触发条件动作新平台适配需求 ≥ 2 次新增 Step 5 平台适配分支某维度诊断误判 ≥ 2 次优化该维度的诊断问题描述生成的 artifact 被用户大幅修改分析修改模式，更新模板

---

使用示例#

输入：

我有一个 Claude Code agent，每天晚上 10 点自动跑，扫描 memory 文件、生成日记、检查 gateway 状态。但经常跑到一半挂掉，下次启动不知道上次做到哪了，重复做已经做过的事。

输出：

1. 诊断报告（Session Bridge ❌、固定启动序列 ❌、Smoke Test 🟡、Checkpoint ❌）
2. P0 改进：立即创建 agent-progress.json + 写固定 5 步启动协议
3. 生成完整的 agent-progress.json 初始文件
4. 生成可粘贴的 Session 恢复协议段落
5. 针对 Claude Code / Windows 的具体 PowerShell 命令

---

设计来源#

核心模式来自：

• Anthropic 工程博客《Effective Harnesses for Long-Running Agents》（2025）
• OpenClaw 三引擎架构实战（2026）：Engine A 战略层 + Engine C 全执行层 + session bridge 落地经验

核心洞察：创造清晰的"上下文桥梁文件"（bridge artifacts），让每个新 session 能在最少 token 消耗内理解当前状态。这是模型无关的架构原则——无论用什么模型，harness 设计决定了 agent 能跑多远。