# LemonBoss v5 架构方案

> **版本**: v5.3 — "大脑·小脑·海马体 + OKR + Multi-Tenant Company"
> **日期**: 2026-03-26
> **状态**: Phase 1-6 已完成，Phase 7 认知架构待开始

> [!IMPORTANT]
> **已确认决策**（2026-03-24/25）
> - 海马体：先关键词匹配 MVP，后加向量检索
> - 小脑：简单用 .md 步骤，复杂用 .js 脚本
> - Hunter/Digester/Evolver：由 agent-creator 创建后，成为其上级的 todo 任务
> - 运行时继承：共享基类 `packages/agent-core/base/`，修改基类所有子类立即生效
> - 定时调度：使用 Claude Code 原生 CronCreate + cron.json 持久化
> - **OKR 目标系统**：`data/goals/` 集中管理，点分层级 ID，全局可追溯
> - **FDE 流水线**：Hunt→Digest→Evolving 三层训练架构，已经端到端验证通过
> - **双路径产出**：元 Agent 产出同时写入 train/ + agents/ 两个位置
> - **Skills 扫描注入**：buildSystemPrompt 扫描所有 .claude/skills/ 子目录

---

## 一、总览：从"工具人"到"有记忆的组织"

当前 v4.x 的 Agent 是**无状态执行器** —— 接到任务、做完、走人。v5 要解决的核心问题是：

> **Agent 如何像一个真正的员工一样：接任务、排优先级、执行、汇报、学习、记住？**

```mermaid
graph TB
    subgraph "v5 核心三层"
        Cerebrum["🧠 大脑 Cerebrum<br>思考·规划·反思"]
        Cerebellum["🧩 小脑 Cerebellum<br>固化方案·代码执行"]
        Hippocampus["🐴 海马体 Hippocampus<br>记忆·检索·匹配"]
    end

    subgraph "任务流"
        Task["📋 Task"] --> TodoMd["todo.md"]
        TodoMd --> Cerebrum
        Cerebrum -->|"新问题"| Think["思考+执行"]
        Cerebrum -->|"熟悉问题"| Cerebellum
        Think --> Reflect["反思"]
        Cerebellum --> Result["结果"]
        Reflect -->|"好方案"| Cerebellum
        Reflect -->|"更新记忆"| Hippocampus
        Hippocampus -->|"检索经验"| Cerebrum
    end
```

---

## 二、OKR 目标管理系统 ⭐ 新增

### 2.1 核心问题

多个 Agent 各自有 todo.md / plan.md，但：
- **谁也看不到全局视图** — 要逐个检查每个 Agent 的文件
- **无法追溯到上层目标** — taskId 只是流水号，不知道属于哪个大项目
- **进度无法自动计算** — 靠人工统计完成比例

### 2.2 ID 设计：点分层级命名

**核心原则**：从任何 ID 就能一眼看出它在哪一层、谁是父级。

```
G-001              ← Goal      (第1层, 顶级目标)
G-001.1            ← Objective  (第2层, 关键路径)
G-001.1.1          ← Key Result (第3层, 可衡量交付物)
G-001.1.1.1        ← Sub-Task   (第4层, 可无限嵌套)
```

**层级判断规则**：

| ID | 层级 | 判断方法 | 父级 | Goal |
|----|------|---------|------|------|
| `G-001` | Goal | `.split('.').length === 1` | 无 | 自身 |
| `G-001.2` | Objective | `.split('.').length === 2` | `G-001` | `G-001` |
| `G-001.2.1` | Key Result | `.split('.').length === 3` | `G-001.2` | `G-001` |
| `G-001.2.1.3` | Sub-Task | `.split('.').length === 4` | `G-001.2.1` | `G-001` |

**解析代码**：
```javascript
function parseNodeId(nodeId) {
  const parts = nodeId.split('.');
  return {
    goalId: parts[0],                           // G-001
    level: parts.length,                         // 1=Goal, 2=Obj, 3=KR, 4+=Sub
    parentId: parts.slice(0, -1).join('.') || null,  // G-001.2.1 → G-001.2
    levelName: ['Goal', 'Objective', 'KeyResult', 'SubTask'][parts.length - 1] || 'SubTask',
  };
}
```

### 2.3 目录结构

```
data/goals/                          ← 集中存储所有 OKR
├── _index.json                      ← 所有 Goal 的摘要索引 (轻量)
├── G-001/                           ← 每个 Goal 一个目录
│   ├── goal.json                    ← 完整 OKR 树 (单一数据源)
│   ├── progress.json                ← 自动计算的进度快照
│   └── history.log                  ← 变更审计日志
├── G-002/
│   └── goal.json
└── ...
```

### 2.4 goal.json 数据结构

```json
{
  "id": "G-001",
  "title": "建设 AI 互动剧公司",
  "description": "从零建设一家能独立运转的 AI 互动剧内容公司",
  "owner": "master-001",
  "status": "in_progress",
  "createdAt": "2026-03-24T03:00:00Z",
  "updatedAt": "2026-03-24T03:25:00Z",
  "nodes": {
    "G-001.1": {
      "title": "公司架构设计",
      "owner": "ceo",
      "status": "in_progress",
      "priority": "P0",
      "children": ["G-001.1.1", "G-001.1.2", "G-001.1.3"]
    },
    "G-001.1.1": {
      "title": "完成组织架构",
      "owner": "ceo",
      "status": "done",
      "taskId": "T-mn41sjv4",
      "output": "workspace/company_charter.md",
      "completedAt": "2026-03-24T03:25:00Z"
    },
    "G-001.1.2": {
      "title": "关键岗位招聘清单",
      "owner": "ceo",
      "status": "pending",
      "children": []
    },
    "G-001.1.3": {
      "title": "运营流程制定",
      "owner": "ceo",
      "status": "pending",
      "children": []
    },
    "G-001.2": {
      "title": "创建核心 Agent",
      "owner": "agent-creator",
      "status": "pending",
      "children": ["G-001.2.1", "G-001.2.2"]
    },
    "G-001.2.1": {
      "title": "创建编剧 Agent",
      "owner": "agent-creator",
      "status": "pending"
    },
    "G-001.2.2": {
      "title": "创建审核 Agent",
      "owner": "agent-creator",
      "status": "pending"
    }
  }
}
```

**设计决策**：使用扁平 `nodes` Map 而非深度嵌套对象。优势：
- O(1) 按 ID 查找任意节点
- 父子关系通过 `children` 数组 + ID 前缀推导
- 无限嵌套深度，数据结构不变

### 2.5 _index.json 索引

```json
[
  {
    "id": "G-001",
    "title": "建设 AI 互动剧公司",
    "owner": "master-001",
    "status": "in_progress",
    "progress": 0.17,
    "nodeCount": 7,
    "doneCount": 1,
    "updatedAt": "2026-03-24T03:25:00Z"
  }
]
```

### 2.6 progress.json 自动计算

```json
{
  "goalId": "G-001",
  "progress": 0.17,
  "total": 6,
  "done": 1,
  "inProgress": 1,
  "pending": 4,
  "byOwner": {
    "ceo": { "total": 3, "done": 1 },
    "agent-creator": { "total": 2, "done": 0 }
  },
  "updatedAt": "2026-03-24T03:25:00Z"
}
```

**进度计算公式**：只统计叶子节点 (没有 children 的节点)：
```javascript
progress = leafNodes.filter(n => n.status === 'done').length / leafNodes.length
```

### 2.7 API 设计

| 端点 | 方法 | 用途 |
|------|------|------|
| `/api/goals` | GET | 列出所有目标 (返回 _index.json) |
| `/api/goals` | POST | 创建新目标 |
| `/api/goals/:goalId` | GET | 获取完整 OKR 树 (返回 goal.json) |
| `/api/goals/:goalId` | PUT | 更新目标元数据 |
| `/api/goals/:goalId/nodes` | POST | 添加节点 (自动分配下一个子 ID) |
| `/api/goals/:goalId/nodes/:nodeId` | PUT | 更新节点状态/内容 |
| `/api/goals/:goalId/progress` | GET | 返回进度统计 |

### 2.8 与任务分发集成

dispatch API 增加 goalId + nodeId：
```json
{
  "from": "master-001",
  "to": "ceo",
  "task": "完成组织架构设计",
  "goalId": "G-001",
  "nodeId": "G-001.1.1",
  "priority": "P0",
  "autoExecute": true
}
```

report API 自动更新 goal.json 中对应节点状态：
```json
{
  "taskId": "T-xxx",
  "from": "ceo",
  "to": "master-001",
  "status": "done",
  "goalId": "G-001",
  "nodeId": "G-001.1.1",
  "summary": "已完成组织架构"
}
```

### 2.9 Agent 上下文注入

新会话的 system prompt 中自动注入当前 Goal 上下文：

```
你当前正在参与目标:
  🎯 G-001「建设 AI 互动剧公司」

你负责的节点:
  📋 G-001.1.2「关键岗位招聘清单」
  层级: Key Result (第3层)
  父级: G-001.1「公司架构设计」
  状态: 进行中

全局进度: 17% (1/6 完成)
```

### 2.10 数据流全景

```
用户: "建设 AI 互动剧公司"
         │
         ▼
    Master Agent
         │
    1. POST /api/goals → 创建 G-001.json
    2. 分解 OKR 树 → G-001.1, G-001.2, ...
    3. dispatch(to=ceo, goalId=G-001, nodeId=G-001.1.1)
         │
         ▼ (CEO 执行)
    4. CEO 完成 → report(nodeId=G-001.1.1, status=done)
         │
         ▼ (自动)
    5. 更新 goal.json 节点状态
    6. 重新计算 progress.json
    7. 更新 _index.json 摘要
         │
         ▼ (Master cron 每 5 分钟)
    8. GET /api/goals/G-001/progress → 17%
    9. 向用户汇报
```

---

## 三、Agent 父类与运行时继承

### 3.1 新增文件到标准目录

```diff
  data/agents/{agent-id}/
  ├── agent.md
  ├── soul.md
  ├── identity.md
  ├── user.md
  ├── tools.md
  ├── heartbeat.md
+ ├── todo.md              # 待办清单（接收到的任务）
+ ├── plan.md              # 计划分解（分配给下级的任务）
+ ├── cron.json             # 定时任务声明（持久化 CronCreate）
  ├── config.json
  ├── .claude/skills/
  ├── memory/
+ │   ├── cerebellum/      # 小脑：固化的执行方案
+ │   ├── hippocampus.md   # 海马体：经验索引
  │   ├── short-term/
  │   ├── long-term/
  │   ├── daily/
  ├── knowledge/
+ ├── conversations/        # 对话持久化
  ├── workspace/
  └── logs/
```

### 3.2 运行时继承架构 ⭐ 新增

修改共享基类，所有 Agent 下次对话立即生效，无需重新创建。

```
packages/agent-core/base/           ← 共享基类 (修改一次，所有继承)
├── common/
│   ├── tools-base.md               ← 安全规则 + dispatch/report API
│   └── capabilities.md             ← CronCreate 用法 + todo/plan 说明
├── master/
│   ├── agent-base.md               ← Master 角色定义
│   └── cron-base.json              ← plan检查(5m) + todo扫描(3m)
├── skill/
│   ├── agent-base.md               ← Skill 角色定义
│   └── cron-base.json              ← todo扫描(10m)
└── cxo/ | role/                     ← 其他类型的基类
```

**System Prompt 构建 = 三层合并**：

```
Layer 1: base/common/*              ← 所有 Agent 通用
Layer 2: base/{type}/*-base.md      ← 类型专属
Layer 3: data/agents/{id}/*         ← 个体专属 (覆盖/扩展)
```

**Cron 构建 = 基类 + Agent 合并**：

```
Layer 1: base/{type}/cron-base.json ← 类型默认定时任务
Layer 2: data/agents/{id}/cron.json ← Agent 追加的定时任务
→ 去重合并, 每次新会话自动注入 CronCreate 恢复指令
```

### 3.3 定时调度：CronCreate + cron.json 持久化

> 官方文档: https://code.claude.com/docs/en/scheduled-tasks.md
> 工具参考: https://code.claude.com/docs/en/tools-reference.md

| 工具 | 用途 |
|------|------|
| `CronCreate` | 创建定时任务 (5-field cron 表达式) |
| `CronList` | 列出当前定时任务 |
| `CronDelete` | 取消定时任务 |

**持久化机制**：CronCreate 是 session-scoped (关闭会话即丢失)。
解决方案：`cron.json` 存储期望状态，每次新会话自动注入重建指令。

---

## 四、任务分发协议

### 4.1 API 端点

| API | 用途 |
|-----|------|
| `POST /api/agent/task/dispatch` | 向目标 Agent 分发任务 |
| `POST /api/agent/task/report` | Agent 汇报任务完成 |

### 4.2 Dispatch 流程

```
dispatch API:
1. 写入目标 Agent 的 todo.md
2. 写入发送者的 plan.md
3. 如果有 goalId → 更新 goal.json 节点状态为 in_progress
4. autoExecute=true → 异步 HTTP 自调用触发聊天
```

### 4.3 Report 流程

```
report API:
1. 更新执行者的 todo.md (标记完成)
2. 更新上级的 plan.md (标记完成) — 行级匹配
3. 如果有 goalId + nodeId → 更新 goal.json 节点状态
4. 自动触发 progress 重算
```

---

## 五、大脑·小脑·海马体 认知架构

*(内容与之前相同，此处省略，详见 v5.0 版本)*

```
Task 进入 → 海马体检索 → 命中? → 小脑快速执行
                              → 未命中 → 大脑思考执行
                                          → 反思
                                            → 新方案存小脑
                                            → 更新海马体
```

---

## 六、已完成 & 进行中 & 待办

### ✅ Phase 1: 基础设施 (已完成)

- [x] AgentScaffold 增加 todo.md, plan.md, cerebellum/, hippocampus.md, cron.json
- [x] 新 API: todo/plan/cron CRUD, 文件树, 文件预览
- [x] 运行时继承: base/ 共享模板 + 三层合并
- [x] 定时调度: CronCreate + cron.json 持久化
- [x] 任务分发: dispatch + report API
- [x] Master Agent 配置: 完整管理能力

### ✅ Phase 2: Web 页面 (已完成)

- [x] 四列统一布局 (Agent列表 | Chat/Detail Tab | 消息/文件 | ACP/预览)
- [x] 深色/浅色/自动主题切换
- [x] ACP 事件流实时展示
- [x] 文件树递归展示 + 文件预览

### ✅ Phase 3: OKR 目标系统 (已完成)

- [x] 设计完成: 点分层级 ID + goal.json 结构
- [x] Goals CRUD API (GoalsService + routes)
- [x] dispatch/report 集成 goalId/nodeId
- [x] progress 自动计算
- [x] system prompt 注入 Goal 上下文 (GoalsService.buildGoalContext)
- [x] 前端 OKR 看板 (OkrDashboard.vue)

### ✅ Phase 3.5: FDE 训练流水线 (已完成 ⭐)

- [x] 创建元 Agent: Hunter (l3-hunt), Digester (l2-digest), Evolver (evolving)
- [x] 每个元 Agent 的 SKILL.md 泛化定义 (不硬编码领域知识)
- [x] L1/L2 依赖技能复制到各元 Agent 的 `.claude/skills/`
- [x] buildSystemPrompt 扫描所有 skills 子目录 (关键修复)
- [x] 双路径产出 (train/ + agents/)
- [x] CEO Agent 端到端训练: Hunt(1461行) → Digest(1593行) → Evolve(92/100)
- [x] retrain-pipeline.js 对齐新 agent 名
- 详见: `docs/system-design/21-fde-pipeline-architecture.md`

### ✅ Phase 4: 公司层架构 + 招聘系统 (已完成 ⭐)

- [x] Multi-Tenant 目录重构: `system/` + `data/{companyId}/`
- [x] 模板库: `system/templates/` (ceo, cto, coo, hr, qa-judge 等)
- [x] 公司 CRUD API: create/list/get/start/shutdown
- [x] 招聘系统: 模板优先 → Creator+FDE 兜底 (≥ 95 分质量门禁)
- [x] Bootstrap 自举机制: `_company_bootstrap/manifest.json`
- [x] SOP Pipeline 执行引擎: 创建/运行/推进/驳回
- 详见: `docs/system-design/24-company-layer-architecture.md`

### ✅ Phase 5: 心跳系统 (已完成)

- [x] Agent 级心跳: `heartbeat-service.js`
- [x] 公司级心跳: `company-heartbeat-service.js`
- [x] 前端 per-agent 心跳控制 (CompanyDashboard.vue)
- 详见: `docs/system-design/23-agent-active-heartbeat.md`

### ✅ Phase 6: 前端 Dashboard (已完成)

- [x] CompanyDashboard.vue (Agent 列表 + 心跳控制 + 操作按钮)
- [x] OkrDashboard.vue (OKR 目标看板)
- [x] MasterChatDrawer.vue (侧边抽屉对话)
- [x] Agent Action Controls (chat, skills panel, train trigger)

- [x] CompanyDashboard Goals Tab 升级为完整 OKR 树视图 (2026-03-27)

### ⬜ Phase 7: 认知架构 (待开始)

- [ ] 海马体检索 (关键词匹配 MVP)
- [ ] 小脑执行 (.md 步骤 + .js 脚本)
- [ ] 反思引擎
- [ ] 全流程端到端测试

---

## 七、关键架构决策记录

| # | 问题 | 决策 | 日期 |
|---|------|------|------|
| 1 | 海马体匹配算法 | 关键词匹配 MVP，后加向量检索 | 03-24 |
| 2 | 小脑方案格式 | .md 步骤 + .js 脚本混合 | 03-24 |
| 3 | 心跳机制 | Claude Code CronCreate (原生) | 03-24 |
| 4 | cron 持久化 | cron.json + session 启动注入 | 03-24 |
| 5 | Agent 继承模型 | 运行时三层合并 (common→type→agent) | 03-24 |
| 6 | OKR ID 命名 | 点分层级 `G-001.2.1` (自描述层级) | 03-24 |
| 7 | OKR 数据结构 | 扁平 nodes Map (O(1) 查找) | 03-24 |
| 8 | OKR 进度算法 | 叶子节点完成率 | 03-24 |
| 9 | plan.md 更新 | 行级匹配 + 列拆分 (兼容粗体等格式) | 03-24 |
| 10 | FDE 双路径产出 | train/(共享) + agents/(资产) 同时写入 | 03-24 |
| 11 | 元 Agent 依赖技能加载 | buildSystemPrompt 扫描所有 .claude/skills/ 子目录 | 03-24 |
| 12 | retrain-pipeline 对齐 | l3-hunt→hunter, l2-digest→digester, innovator-evolver→evolver | 03-25 |
| 13 | Thinking 控制 | `--effort low` 禁用 extended thinking，config.json `cli.effort` 按 Agent 配置 | 03-27 |

---

## 八、关键文件路径索引

| 文件 | 用途 |
|------|------|
| `packages/agent-core/AgentScaffold.js` | Agent 脚手架 (创建时模板) |
| `packages/agent-core/base/` | 共享基类 (运行时继承) |
| `server/routes/agent-chat.js` | 核心 API (chat, dispatch, report, CRUD) |
| `server/routes/company.js` | 公司管理 API (hire, fire, OKR, Pipeline, Heartbeat) |
| `server/routes/goals.js` | OKR Goals API |
| `server/services/company-service.js` | 公司 CRUD + 招聘逻辑 |
| `server/services/company-heartbeat-service.js` | 公司级心跳服务 |
| `server/services/heartbeat-service.js` | Agent 级心跳服务 |
| `server/services/pipeline-service.js` | SOP 流水线引擎 |
| `server/services/retrain-pipeline.js` | FDE 重训流水线 (已对齐 agent 名) |
| `web/src/views/CompanyDashboard.vue` | 公司仪表盘 |
| `web/src/views/OkrDashboard.vue` | OKR 目标看板 |
| `web/src/views/AgentChat.vue` | Agent 对话详情 (四列布局) |
| `system/agents/innovator/` | Innovator 编排 Agent |
| `system/templates/` | Agent 模板库 |
| `data/goals/` | 全局 OKR 目标数据 |
| `docs/system-design/21-fde-pipeline-architecture.md` | FDE 流水线架构文档 |
| `docs/system-design/24-company-layer-architecture.md` | 公司层架构文档 |
| `docs/claude-code-cron.md` | Claude Code 定时调度文档 |