agent-harness-architect
# 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 — 架构摸底（必须先问，不能跳过）
向用户提以下问题（可一次性发出，不要逐条等待）：
```
要帮你把 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 能跑多远。
标签
skill
ai
