English version: Agent Harness: A Portable Context System for Local AI Agents.

Agent Harness：为本地 AI 助手构建可迁移的上下文系统

AI 编程助手真正有用的时候，往往不是因为它“知道很多通用知识”，而是因为它能稳定理解一个人的工作方式、项目边界、常用工具、历史决策和安全约束。Agent Harness 的目标，就是把这些长期上下文从一次性的聊天记录里抽出来，整理成一个本地优先、可版本化、可迁移、可被不同 Agent 读取的工作环境。

它不是一个单一应用，也不是一个云端知识库。更准确地说，它是一套文件系统约定、Git 同步方式、技能文档、项目简报、工作流和本地知识层的组合。它让 AI 助手在开始工作前能先读到正确的上下文，在执行过程中能遵守清晰的边界，在任务结束后又能把值得复用的经验沉淀下来。

为什么需要 Agent Harness

许多 AI Agent 的默认工作方式是“会话中心化”的：一次会话里探索了大量信息，解决了一个复杂问题，但下次会话重新开始时，这些上下文大多不会自然保留。即使某些工具有记忆能力，也常常缺少明确的组织边界：哪些是用户偏好，哪些是项目事实，哪些是操作手册，哪些是硬性规则，哪些只是一次性的临时观察？

Agent Harness 解决的是这个结构化问题。它把上下文拆成几个稳定层次：

• 用户层：沟通偏好、常用环境、长期事实。
• 规则层：所有 Agent 都应该遵守的硬规则。
• 项目层：每个项目的架构、边界、常见命令和危险点。
• 技能层：可复用的操作能力，例如部署、备份、发布、同步。
• 工作流层：跨多个工具和系统的步骤化流程。
• 知识层：从长期内容中提炼出的 LLM Wiki。

这种拆分的价值在于：Agent 不需要一次性读取所有内容，而是根据任务读取对应层次。项目任务先读项目简报；发布任务先读发布工作流；涉及长期知识时再进入 LLM Wiki。

基础架构

Agent Harness 使用一个 bare Git 仓库管理用户目录中的少量 allowlist 文件。典型结构如下：

~/.agent-harness.git        # bare repo
~/.agents/                  # 可移植的 agent 上下文
~/.claude/CLAUDE.md         # user-level dispatcher
~/README.md                 # harness 自说明
~/.gitignore                # allowlist + 安全排除规则

这种模式有几个好处：

1. 工作树仍然是用户目录，不需要把上下文复制到另一个项目目录。
2. Git 只跟踪显式 allowlist 的文件，默认忽略绝大多数本地状态。
3. 敏感文件、缓存、日志、临时状态和工具数据库不会被误提交。
4. 同一套上下文可以被多个本地 Agent 复用。

关键点不是“把整个家目录放进 Git”，而是反过来：默认忽略一切，只显式纳入需要长期维护的上下文文件。

目录分层

~/.agents/ 是 Agent Harness 的核心。一个较稳妥的结构包括：

~/.agents/
  USER.md
  SOUL.md
  projects/
  skills/
  workflows/
  rules/
  tools/
  knowledge/
  journal/
  workspaces/

USER.md 保存事实性用户画像，例如常用技术栈、语言、操作系统和主要服务。SOUL.md 保存沟通风格和协作偏好。projects/ 下每个项目一个 OVERVIEW.md，用于让 Agent 在改代码前先理解架构。skills/ 是能力单元，定义何时触发、读哪些文件、怎么操作。workflows/ 则记录跨系统、多步骤的过程。

这种结构让上下文的“归属”更清楚。项目事实不应该散落在聊天记录里；可复用操作不应该写进单个项目说明；硬规则也不应该混在临时任务总结里。

Dispatcher：让 Agent 先读对文件

许多 AI 工具会自动读取某个用户级规则文件。Agent Harness 可以利用这个入口放一个短小的 dispatcher，而不是把所有知识都塞进去。

dispatcher 的职责很有限：

• 告诉 Agent 哪些 companion files 存在。
• 规定项目任务先读 projects/<name>/OVERVIEW.md。
• 规定涉及长期知识时先读 LLM Wiki index。
• 放少量真正“总是适用”的硬规则。

这样可以避免每次会话都加载大量不相关内容，也能保持启动上下文清晰。

技能与工作流

Agent Harness 中的 skill 更像是“能力说明书”。它应该回答三个问题：

1. 什么时候使用这个技能？
2. 使用前应该读哪些文件？
3. 执行时有哪些安全规则和验证步骤？

workflow 则更适合记录一套跨工具流程。例如：从远程数据库导出 hash 状态、在本地检查待处理队列、用本地 Agent 综合 wiki、ack 已处理 source、lint、commit、push。这不是单个工具能解决的问题，所以应该写成 workflow。

这次 Agent Harness 的搭建过程沉淀出一个重要模式：远程只做状态感知，本地做智能综合。远程 GitHub Actions 不需要依赖 LLM API，只需要生成机器可读的变化队列；本地 Agent 在用户环境里读取队列，再进行总结、归纳和文档更新。

LLM Wiki：从内容系统到 Agent 可读知识

Agent Harness 还可以连接一个长期内容系统，把文章、页面和项目记录提炼成 LLM Wiki。这里最重要的原则是：不要把 raw 内容仓库和 compiled knowledge 混为一谈。

比较稳妥的分层是：

• canonical source：数据库、CMS 或文档系统。
• raw staging：本地 ignored 导出目录，用于临时处理。
• remote state：只保存 source key、标题、状态、更新时间和 hash。
• compiled wiki：经过本地 Agent 归纳后的主题页、项目页、概念页、时间线。
• acknowledgement：记录哪些 source hash 已经被综合进 wiki。

这样，远程仓库能感知内容变化，但不需要保存正文，也不需要调用 LLM API。真正的知识综合发生在本地，用户可以审查结果，再把稳定的 wiki 页面提交回 harness。

同步策略

一个实用的同步循环如下：

1. GitHub Action 每周或手动运行一次，只读查询内容正源。
2. Action 生成 remote-state.json 和 sync-queue.json。
3. 本地 Agent 启动时检查 queue。
4. 如果有 pending source，本地导出必要 raw 数据到 ignored staging。
5. 本地 Agent 分批更新 wiki 页面。
6. lint wiki，确认无断链、无缺失 source。
7. ack 已处理 source hash。
8. commit 并 push harness。

这个设计的重点是低耦合：内容系统不依赖 OpenAI API，GitHub Actions 不负责智能总结，Agent Harness 也不替代内容正源。

安全边界

Agent Harness 的安全边界应当从一开始就设计进去：

• 默认忽略所有未 allowlist 的文件。
• 不提交 token、密钥、.env、本地缓存、日志和工具状态数据库。
• remote state 不保存正文和摘要。
• raw 导出默认 ignored。
• 生产数据库写入前先备份。
• 自动化脚本只做可验证的小步骤。
• LLM 生成的内容进入公开站前需要人工审查。

公开文档尤其要注意：不要包含私人路径、真实账户、内部域名、密钥名称、令牌、服务器地址或不可公开的项目细节。可以讲架构模式和工程原则，但不要暴露具体环境。

经验总结

Agent Harness 的核心不是某个工具，而是一种上下文治理方式。它把“Agent 需要知道什么”拆成可维护的层次，把“Agent 可以做什么”写成可执行的技能，把“复杂操作如何复用”沉淀成工作流。

当这些内容进入 Git，AI 助手就不再完全依赖一次性会话记忆。它可以在每次任务开始时读取稳定的项目简报和规则，在遇到重复任务时调用已有 workflow，在处理长期知识时参考 LLM Wiki，并在任务结束后继续改进 harness 本身。

最终效果不是让 Agent 神秘地“更聪明”，而是让它少猜、多读、按边界行动，并把有价值的经验持续留在一个可同步、可审查、可迁移的地方。