Harrison Chase 那篇 Harness Design 发布后，Av1dlive 花了三个月搭建了一套完整实现。这篇文章是 4,000 字的工程复盘，附完整源码和 folder structure。

核心洞察

薄 harness、厚文件层。

Harness 不思考，它只读文件、调工具、写日志、跑钩子。所有智能住在 skill 文件和 memory 文件里，protocols 执行边界约束。

这意味着：

  • 明天换掉 harness，什么都不丢
  • 明天换掉模型，什么都不丢
  • 唯一积累价值的是 skills、memory、protocols——都是 git 仓库里的 markdown 和 JSON

Folder Structure

.agent/ ├── AGENTS.md # 根配置，harness 第一个读 ├── harness/ │ ├── conductor.py # 薄循环（~200行） │ ├── context_budget.py # token 分配管理 │ └── hooks/ │ ├── pre_tool_call.py # 权限执行 │ ├── post_execution.py # 自动写记忆 │ └── on_failure.py # 升级 + 反思触发 ├── memory/ │ ├── working/ # 当前任务状态，易失 │ │ ├── WORKSPACE.md │ │ └── ACTIVE_PLAN.md │ ├── episodic/ # 历次运行发生了什么 │ │ ├── AGENT_LEARNINGS.jsonl │ │ └── snapshots/ │ ├── semantic/ # 超越 episode 的抽象 │ │ ├── LESSONS.md │ │ ├── DECISIONS.md │ │ └── DOMAIN_KNOWLEDGE.md │ ├── personal/ # 用户个人偏好 │ │ └── PREFERENCES.md │ └── auto_dream.py # 夜间压缩 + 整合 ├── skills/ │ ├── _index.md # 发现注册表 │ ├── _manifest.jsonl # 机器可读元数据 │ └── [各技能目录...] ├── protocols/ │ ├── tool_schemas/ # 每个工具的 typed 接口 │ ├── permissions.md # agent 能/不能做什么 │ └── delegation.md # sub-agent 交接规则 └── tools/ ├── memory_reflect.py ├── skill_loader.py # 渐进式加载引擎 └── budget_tracker.py

四层记忆详解

Working Memory

  • WORKSPACE.md + ACTIVE_PLAN.md
  • 每次任务开始加载，结束时清除

Episodic Memory

  • AGENT_LEARNINGS.jsonl：原始经验日志，每次交互追加
  • snapshots/：定期全量快照
  • 用途：告诉 agent "上次在这件事上你是怎么处理的"

Semantic Memory

  • LESSONS.md：提炼出的模式
  • DECISIONS.md：重大决策及理由（含日期、考虑过的替代方案、状态）
  • DOMAIN_KNOWLEDGE.md：领域知识
  • 用途：做决定前读，训练的是判断力而非过程

Personal Memory

  • PREFERENCES.md
  • 你的代码风格偏好、工作习惯、沟通方式
  • 是上下文，不是指令——告诉 agent 你是什么样的人，不是教它怎么做

自动梦境压缩循环

每天凌晨 3 点运行 .agent/memory/auto_dream.py：

  • 压缩记忆
  • 将有价值的经验晋升到 LESSONS
  • 归档过时内容
  • git commit 结果

日志示例：

dream cycle: promoted 2, decayed 7, kept 31

这就是 agent 的自传——每一行都是一夜的学习。

失败处理钩子

on_failure.py 在每次失败时记录：

  • 时间戳、skill 名称、错误类型
  • 疼痛分数（自动给 8 分）
  • 上下文（前 300 字符）

如果 14 天内同一 skill 失败 3 次以上，标记为需要重写，疼痛分数升到 10。

常见反模式

问题表现解法
上下文膨胀加载 90K tokens 才能思考渐进式加载，只加载匹配 skill
技能过时API 变了，skill 还在自信跑旧指令manifest 每条加版本日期，60 天未触碰的标审
不安全组合两个安全 skill 合成危险操作约束放 pre_tool_call，不放在 skill 内部
教条执行agent 照着步骤做，哪怕已经不合理写目标和边界，不写驾驶指令
工作区过期WORKSPACE.md 任务结束后没清零梦境循环归档 2 天以上的工作区

Protocol 层

  • permissions.md：读在任何工具调用之前，被禁止就是被禁止
  • tool_schemas/：每个外部工具的 typed 接口
  • delegation.md：何时交给 sub-agent，交给谁

对于个人编程 agent，薄心跳 + 一个 permissions 文件就够了。在生产系统上跑 agent，最终你会需要完整的 tool schemas 和审批钩子——但先跑几个星期的薄版本，它会告诉你 guardrail 具体要加在哪里。

架构核心原则

这套系统的 thesis：

模型可以随时换。skills 和 memory 换不了。它们编码了你的特定错误、你的特定决策、你的特定工作方式。

拥有你的记忆。拥有你的 skills。放在任何人都拿不走的 plain files 和 git 里。