Simple Harness — 极简 Agent 设定系统

一套基于纯 Markdown 文件的智能体设定系统，用于与 AI Agent 建立高效、结构化、可演化的沟通协议。通过按需加载索引、智能体设定与技能系统和自进化系统三大机制，在最小化上下文 token 消耗的前提下，实现 Harness Engineering 的全部要求。

---

设计理念

原则	说明
单一入口	Quest.md 是 Agent 唯一入口，一般使用时只需关心这一个文件
索引导航	所有资源通过 INDEX.md 按需加载，禁止遍历目录
多人格	支持多个人格独立记忆（MEM.md）与进化规则（EVO.md）
技能创建与更新	依据每个人格里的 EVO.md 文件定义的规则，动态创建与更新技能
Token 优先	每个设计决策都考虑了对 Agent 上下文窗口的影响

---

快速开始

1. 项目结构

Project/
├── Quest.md                    ← 唯一入口，Agent 启动时只读此文件
├── README.md                   ← 本文件
└── Agent/
    ├── BOOT.md                 ← 启动协议（定义初始化序列）
    ├── INDEX.md                ← 全局索引（禁止遍历，一切通过索引导航）
    ├── RULES.md                ← 全局行为规则（所有任务的通用约束）
    ├── memory/
    │   ├── INDEX.md            ← 智能体设定索引（根据请求内容选择设定的智能体）
    │   └── coder/
    │       ├── MEM.md          ← coder 长期记忆与行为规则
    │       └── EVO.md          ← 自进化规则
    ├── skills/
    │   ├── INDEX.md            ← 技能索引（按需加载入口）
    │   ├── coding/             ← 编程技能
    │   ├── research/           ← 调研技能
    │   ├── envSetup/           ← 环境配置技能
    │   ├── test/               ← 测试/技能
    │   └── planning/           ← 规划技能
    └── templates/              ← 扩展模板

2. 使用方式

用户只需在 Quest.md 中填写需求。Agent 启动后会自动执行：

Quest.md → BOOT.md → INDEX.md → RULES.md → 选择智能体设定 → 加载记忆 → 加载技能索引 → 执行任务

示例 Quest.md 内容：

## 用户请求

请帮我实现一个用户登录模块，需要支持：
- 邮箱 + 密码登录
- JWT token 认证
- 登录失败次数限制

## 补充说明

- 使用 Express.js 框架
- 数据库使用 PostgreSQL
- 遵循项目现有的错误处理模式

3. 管理项目文件时的注意事项

使用 git 管理项目文件时，默认会添加以下 .gitignore 规则：

Quest.md
Agent/

---

核心系统

启动协议（BOOT.md）

Agent 启动时严格按 5 步序列执行，确保每次初始化行为一致：

步骤	动作	目的
1	读取 INDEX.md	建立全局导航认知
2	读取 RULES.md	加载行为约束
3	读取 memory/INDEX.md	选择智能体设定/加载记忆
4	读取 MEM.md	恢复长期记忆
5	读取 skills/INDEX.md	建立技能索引

Skills 系统（Openclaw 风格）

按需加载的技能架构，每个技能包含：

skills/{skill_name}/
├── SKILL.md        ← 技能定义（触发条件 + 工作流 + 准则）
└── RefAndTool/     ← 参考资料与脚本工具（仅在 SKILL.md 引用时读取）

内置技能：

技能	触发条件	典型场景
planning	需要制定计划/分解任务/设计架构	项目启动、架构设计
research	需要查找资料/评估方案/对比技术	技术选型、方案调研
envSetup	需要检查环境/配置环境/安装依赖/设置变量等	检查环境、配置环境
coding	涉及代码编写/修改/重构	功能开发、Bug 修复
test	涉及环境验证/功能测试/性能测试/调试	功能验证、性能优化

技能组合：支持多技能联动，如 planning → research → envSetup → coding → test。下面是融合了 Loop Engineering（闭环重试）与 Graph Engineering（节点协作+记忆共享）的完整流程图：

flowchart TB
    subgraph Loop["🔄 Loop Engineering — 自主持续执行闭环"]
        direction TB

        User(["🗣️ 用户需求<br/>Quest.md"]) --> planning

        planning["📋 planning<br/>任务分解 / 架构设计"]
        planning -->|"产出：任务列表"| research

        research["🔍 research<br/>技术调研 / 方案评估"]
        research -->|"产出：推荐方案"| envSetup

        envSetup["⚙️ envSetup<br/>环境检查 / 依赖安装"]
        envSetup -->|"产出：环境就绪"| coding

        coding["💻 coding<br/>代码编写 / 修改"]
        coding -->|"产出：代码变更"| test

        test["🧪 test<br/>验证 / 测试 / 调试"]
        test -->|"✅ 全部通过"| Done(["🚀 交付完成"])

        test -->|"❌ 失败"| failCheck{"🔎 失败原因分析"}
        failCheck -->|"环境配置问题"| envSetup
        failCheck -->|"方案不适用"| research
        failCheck -->|"代码逻辑错误"| coding
        failCheck -->|"需求理解偏差"| planning
    end

    subgraph Graph["🔗 Graph Engineering — 多节点协作与记忆共享"]
        direction LR

        Mem["🧠 MEM.md<br/>持久化记忆"]

        planning -.->|"写入经验"| Mem
        research -.->|"写入经验"| Mem
        coding -.->|"写入经验"| Mem
        test -.->|"写入经验"| Mem

        Mem -.->|"读取经验<br/>避免重复犯错"| planning
        Mem -.->|"读取经验<br/>复用调研结论"| research
        Mem -.->|"读取经验<br/>参考历史方案"| coding
        Mem -.->|"读取经验<br/>已知边界条件"| test
    end

    Loop -.->|"跨会话持久化"| Graph

Loading

图解说明：

• 实线箭头：正常流程，按 planning → research → envSetup → coding → test 逐步推进
• 红色回环：test 失败时自动分析原因，回退到对应阶段重试（Loop Engineering 核心）
• 虚线箭头：每个阶段完成后将经验写入 MEM.md，后续阶段可读取历史经验（Graph Engineering 核心）

记忆系统

分层记忆架构：

层级	文件	内容	生命周期
长期记忆	MEM.md	用户偏好、技术决策、可复用方案	跨会话持久
元规则	EVO.md	记忆更新规则、skill 创建规则、skill 更新规则	随项目演进

记忆条目格式：

### MEM-001
- **类别**：技术决策
- **触发条件**：选择后端框架时
- **内容**：本项目使用 Express.js 作为 HTTP 框架
- **理由**：团队熟悉度高，生态成熟，社区活跃
- **时间**：2026-07-21

MEM.md 文件允许用户自定义行为规则，比如

项目必须有 README.md 文件，用于介绍项目、说明使用方法、展示结果等;
每次完成更新项目时，应更新 README.md 文件，及时说明项目最新状态。

自进化机制（Hermes 风格）

记忆更新机制：

会话结束 → 查阅 EVO.md 文件
        → 对照触发条件（用户偏好/技术决策/可复用方案/错误修正）
        → 对照抑制条件（去重/通用知识/琐碎信息/同类重复）
        → 生成记忆条目 → 用户确认 → 追加到 MEM.md

Skill 创建机制：

会话结束 → 查阅 EVO.md 文件
        → 判断是否要创建新 Skill 如果需要则向用户说明情况并请求创建
        → 用户确认 → 生成 Skill 目录和其下的文件 `SKILL.md` 和 `RefAndTool/` 目录

Skill 更新机制：

会话结束 → 查阅 EVO.md 文件
        → 判断是否要更新现有 Skill 如果需要则向用户说明情况并请求更新
        → 用户确认 → 更新对应 Skill 目录下内容

EVO.md 文件允许用户自定义演化规则

Token 预算管理

系统在每个设计层面都考虑了 token 消耗优化：

策略	实现方式	效果
懒加载	INDEX.md 只存摘要，详情按需读取	避免预加载无关内容
按需技能	每个技能独立文件夹，触发时才加载 SKILL.md	单次最多加载 1-2 个技能
禁止遍历	RULES.md 明确禁止 ls/遍历 Agent/ 目录	防止 Agent 自主探索消耗 token
记忆隔离	只加载当前智能体设定的 MEM.md	不预加载其他智能体设定的记忆
摘要优先	所有 INDEX.md 提供快速导航表	一次读取即可定位所需资源

---

扩展指南

创建新技能

1. 复制 Agent/templates/skill_template.md 到 Agent/skills/{skill_name}/SKILL.md
2. 填写技能 ID、触发条件、工作流和准则
3. 在 Agent/skills/INDEX.md 中注册新技能
4. 在 Agent/INDEX.md 中更新导航链接

创建新智能体设定

1. 复制 Agent/templates/memory_template.md 到 Agent/memory/{persona}/MEM.md
2. 复制 Agent/templates/evolution_template.md 到 Agent/memory/{persona}/EVO.md
3. 在 Agent/memory/INDEX.md 中注册新智能体设定
4. 在 Agent/INDEX.md 中更新导航链接

添加技能参考资料

在对应技能的 RefAndTool/ 目录下放置 .md 参考文件，在 SKILL.md 中通过相对路径引用。Agent 仅在 SKILL.md 明确引用时才读取这些文件。

---

项目约定

• 所有 Agent 记忆文件为 .md 格式，存放于 Agent/ 目录
• 项目入口为 Quest.md，Agent 通过 Agent/BOOT.md 启动
• 遵循 Harness Engineering 原则：意图优先、最小侵入、可逆操作、渐进交付
• Agent 不得遍历目录，所有资源定位通过 INDEX.md 索引完成

---

许可证

本项目为项目初始化模板，使用 MIT 许可证，可自由使用和修改。