architecture-v5.md 17.4 KB

Edit Raw Blame History


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 产出同时写入 workspace/ + agents/ 两个位置
Skills 扫描注入：buildSystemPrompt 扫描所有 .claude/skills/ 子目录


一、总览：从"工具人"到"有记忆的组织"
当前 v4.x 的 Agent 是无状态执行器 —— 接到任务、做完、走人。v5 要解决的核心问题是：


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

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


解析代码：
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 数据结构
{
  "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 索引
[
  {
    "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 自动计算
{
  "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 的节点)：
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：
{
  "from": "master-001",
  "to": "ceo",
  "task": "完成组织架构设计",
  "goalId": "G-001",
  "nodeId": "G-001.1.1",
  "priority": "P0",
  "autoExecute": true
}


report API 自动更新 goal.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 新增文件到标准目录
  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] 双路径产出 (workspace/ + 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 双路径产出
workspace/(共享) + 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 定时调度文档