# 3. Agent 原子模型

> **核心理念**: 框架只有 1 个通用 Agent 运行时。每个 Agent 是一个 **配置目录实例**，不是代码子类。
> 创建 Agent = 创建目录 + 写入配置文件。四层的区别不靠代码继承，而靠目录内容不同。

---

## 3.1 Agent = 一个目录

每个 Agent 实例就是 `data/agents/` 下的一个目录。参考 OpenClaw 的 "麻雀虽小五脏俱全" 设计，包含以下标准结构：

```
data/agents/{agent-id}/
│
│ ─── 核心定义文件 (Bootstrap Files) ──────────
│     每次 session 启动时注入 LLM 上下文
│
├── agent.md              # 操作规则: 职责、约束、可用工具、never/always 规则
├── soul.md               # 灵魂定义: 人格、价值观、思维方式、沟通风格
├── identity.md           # 外显身份: 显示名称、头像、问候语、emoji
├── user.md               # 上下文画像: 上层 Agent 或用户的偏好和目标
├── tools.md              # 工具备注: API 使用规范、工具注意事项
├── heartbeat.md          # 心跳任务: 周期性主动执行的检查清单
│
│ ─── 技能系统 ──────────────────────────────
│
├── skills/
│   ├── skills.md         # 技能索引: 当前拥有的技能清单和能力边界
│   ├── {skill-name}/     # 具体技能目录
│   │   ├── SKILL.md      # 技能定义 (YAML frontmatter + 执行指令)
│   │   ├── *.js / *.py   # 技能实现代码
│   │   └── config.json   # 技能配置
│   └── ...
│
│ ─── 记忆系统 ──────────────────────────────
│
├── memory/
│   ├── memory.md         # 长期记忆索引: 关键事实、模式、经验总结
│   ├── short-term/       # 短期记忆 (当前任务上下文)
│   ├── long-term/        # 长期记忆 (持久化 SQLite + 向量)
│   ├── sessions/         # 会话记忆 (对话历史快照)
│   └── daily/            # 每日日志 (YYYY-MM-DD.md)
│
│ ─── 知识库 ──────────────────────────────
│
├── knowledge/            # 参考文档、领域知识、数据资料
│
│ ─── 自治工作区 ──────────────────────────
│
├── workspace/            # Agent 自主读写 (框架不干预)
│   ├── code/             # Agent 自主编写的代码
│   ├── data/             # Agent 自主创建的数据
│   └── assets/           # Agent 自主管理的资产
│
│ ─── 运行数据 ──────────────────────────
│
├── logs/                 # 对话日志 (JSONL) + 运行日志
└── config.json           # 运行配置
```

---

## 3.2 Bootstrap Files — 六大定义文件

Bootstrap Files 是 Agent 的"灵魂文件"，每次 session 启动时注入 ACP 内核的上下文。

### agent.md — "我的规则"

定义 Agent 的职责、约束和可用工具。包含三类规则：

```markdown
# CEO Agent

## 身份
你是 Lemon Drama 公司的 CEO，负责商业战略制定和公司方向把控。

## 职责
- 分析市场趋势，制定季度战略
- 审核 CTO 和 COO 提交的方案
- 拆解公司 Goal 为各部门可执行的子目标

## Never Rules (绝对不做)
- 不要直接管理 Skill 层 Agent
- 不要在未经 CTO 技术审核的情况下推动技术方案

## Confirm-Before Rules (需要确认)
- 裁撤部门前需向 Master 汇报
- 重大资源调整（>30%预算变动）需向 Master 确认

## Always Rules (自动执行)
- 每 5 分钟扫描全局进度
- 发现 Gap 自动向相关 Role 下发修正指令

## 可用工具
- role.create: 创建新的职能部门
- role.redefine: 调整部门职责
- role.destroy: 裁撤部门
- pipeline.set: 设计工作流
- pipeline.adjust: 调整工作流
```

### soul.md — "我的灵魂"

```markdown
# CEO 的灵魂

## 思维方式
- 先看数据，再做判断
- 关注 ROI 和投产比
- 善于从失败中提取教训

## 沟通风格
- 简洁直接，不绕弯
- 用数据说话
- 对下属关键进展给予正面反馈

## 价值观
- 用户价值 > 商业利润
- 长期主义 > 短期爆发
```

### identity.md — "我的名片"

```markdown
# 身份信息

## 基础信息
- 名称: Lemon CEO
- Emoji: 👔
- 类型: cxo

## 问候语
"你好，我是 Lemon Drama 的 CEO。我负责公司的战略方向。有什么需要我决策的？"
```

### user.md — "我上面是谁"

```markdown
# 上层上下文

## 我的上级
- Master Agent (master-001)
- Master 的核心目标: 做一个年轻女性喜欢的 AI 互动短剧平台

## 上级偏好
- 更关注用户增长而非收入
- 喜欢看到数据支撑的结论
- 不喜欢过于保守的方案
```

### tools.md — "我怎么用工具"

```markdown
# 工具使用备注

## API 接口
- 社交媒体 API: 使用 env 变量 SOCIAL_API_KEY，不要硬编码
- 数据分析 API: 每日限额 1000 次调用，注意限流

## 文件操作
- 所有仅限在 workspace/ 内操作
- 数据库文件存放在 workspace/data/

## 安全规则
- 不要在日志中输出 API Key
- 不要在 memory 中存储密码
```

### heartbeat.md — "我的心跳"

```markdown
# 心跳任务

## 每 5 分钟
- [ ] 检查所有 Role Agent 的运行状态
- [ ] 对比 Goal 进度，识别 Gap
- [ ] 扫描最新的 Pipeline 执行情况

## 每小时
- [ ] 汇总过去 1 小时的关键指标
- [ ] 向 Master 提交简要进度报告

## 每日
- [ ] 生成今日工作总结写入 memory/daily/
- [ ] 评估本周目标是否需要调整
```

---

## 3.3 Skills 系统

### skills.md — 技能总索引

```markdown
# 我的技能

## 技能清单
1. **market-analysis** (L1) — 市场趋势分析与竞品调研
2. **strategy-review** (L2) — 战略方案可行性审核，依赖 market-analysis
3. **goal-decomposer** (L1) — 将公司 Goal 拆解为部门子目标

## 技能层级
- L1 原子级: 独立执行，单一职责
- L2 组合级: 组合多个 L1 完成复杂任务
- L3 场景级: 组合多个 L2 解决完整业务场景
```

### SKILL.md — 技能定义规范

```yaml
---
name: market-analysis
description: 社交媒体热点话题采集与市场趋势分析
version: 1.0.0
domain: strategy
scope: market
layer: 1
dependencies: []
keywords: [market, trending, analysis]
---

## 执行流程
1. 采集社交媒体热门话题
2. 分析竞品最新动态
3. 输出结构化市场报告
```

---

## 3.4 Memory 系统

```
memory/
├── memory.md           # 长期记忆索引 (关键事实和经验)
├── short-term/         # 当前任务上下文
│   └── context.json
├── long-term/          # 持久化经验
│   ├── experiences.sqlite
│   └── vectors/
├── sessions/           # 历史对话
│   ├── session-001.json
│   └── session-002.json
└── daily/              # 每日原始日志
    ├── 2026-03-21.md
    ├── 2026-03-22.md
    └── 2026-03-23.md
```

### memory.md — 长期记忆索引

```markdown
# 我的记忆

## 关键事实
- 公司目标: Q1 日活 10 万
- 当前日活: 2.3 万 (3月22日)
- 最有效的拉新渠道: 小红书短视频

## 已验证的模式
- 古装题材在 18-25 岁女性中转化率最高 (23%)
- 周二和周四发布的短剧播放量比其他工作日高 40%

## 失败教训
- 2026-03-15: 同时上线 5 部剧导致服务器过载，以后每批最多 2 部
```

---

## 3.5 config.json — 运行配置

```json
{
  "type": "cxo",
  "parent_id": "master-001",
  "goal_id": "goal-q1-growth",

  "gateway": {
    "channels": ["feishu"]
  },

  "api": {
    "endpoints": [
      {
        "name": "analytics",
        "url": "https://api.lemondrama.com/v1",
        "token_env": "ANALYTICS_API_KEY"
      }
    ]
  },

  "mcp": {
    "servers": []
  },

  "sandbox": {
    "maxMemoryMB": 512,
    "maxDiskMB": 1024,
    "maxProcesses": 5
  }
}
```

---

## 3.6 通用 Agent 运行时

框架代码只有 **1 个 Agent 类**，工作方式：读目录 → 加载配置 → 注入上下文 → 启动 Loop。

```javascript
class Agent {
  constructor(agentDir) {
    this.dir = agentDir;
  }

  async load() {
    // 读取 Bootstrap Files
    this.agentMd    = await readFile(`${this.dir}/agent.md`);
    this.soulMd     = await readFile(`${this.dir}/soul.md`);
    this.identityMd = await readFileOpt(`${this.dir}/identity.md`);
    this.userMd     = await readFileOpt(`${this.dir}/user.md`);
    this.toolsMd    = await readFileOpt(`${this.dir}/tools.md`);
    this.heartbeat  = await readFileOpt(`${this.dir}/heartbeat.md`);
    this.skillsMd   = await readFileOpt(`${this.dir}/skills/skills.md`);
    this.memoryMd   = await readFileOpt(`${this.dir}/memory/memory.md`);
    this.config     = await readJSON(`${this.dir}/config.json`);

    // 组装系统指令 (注入 ACP 上下文)
    this.systemPrompt = [
      this.agentMd, this.soulMd, this.identityMd,
      this.userMd, this.toolsMd, this.skillsMd, this.memoryMd,
    ].filter(Boolean).join('\n\n---\n\n');

    // 初始化 ACP 内核
    this.acp = await launchACP({
      systemPrompt: this.systemPrompt,
      cwd: `${this.dir}/workspace/`,
    });
  }

  async runLoop() { /* 5 阶段通用 Loop */ }
}
```

**四层的区别完全来自目录里的文件内容**：

| 区别 | 实现方式 |
|------|---------|
| Master 能创建 CXO | agent.md 里列出了 `cxo.create` 工具 |
| CXO 能设计 Pipeline | agent.md 里列出了 `pipeline.set` 工具 |
| Skill 只能执行 | agent.md 里 **没有** 管理工具 |
| 各层反思方式不同 | soul.md 里定义了不同的思维模式 |
| 心跳频率不同 | heartbeat.md 里定义了不同的检查频率 |

---

## 3.7 "创建 Agent" = "生成目录"

```
agent.create({ name: "编剧部", type: "role" })
    │
    ▼
框架做的事:
  1. mkdir data/agents/role-dramatist-{uuid}/
  2. 创建子目录: skills/ memory/ workspace/ knowledge/ logs/
  3. 创建子目录: memory/short-term/ memory/long-term/ memory/sessions/ memory/daily/
  4. 创建子目录: workspace/code/ workspace/data/ workspace/assets/
  5. 让上层 Agent 的 ACP 内核生成 6 大 Bootstrap Files
  6. 写入 config.json
  7. 注册到数据库
  8. 启动沙盒 + ACP 进程
```

> **上层 Agent 写下层 Agent 的 agent.md 和 soul.md** = 管理的本质。