From 8b57a024c99c4b71131afa806bcea97ee1a2d244 Mon Sep 17 00:00:00 2001 From: yibo Date: Sat, 15 Aug 2026 16:01:05 +0800 Subject: [PATCH] docs: archive docs/ into done/todo/todo-future, add index; land P2 Org Graph spec --- docs/LEMONBOSS-SYSTEM-DESIGN.md | 108 ------------------------------------------------------------------------------------------------------------ docs/README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/architecture-v5.md | 533 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/architecture_todo_list.md | 146 -------------------------------------------------------------------------------------------------------------------------------------------------- docs/claude-code-cron.md | 80 -------------------------------------------------------------------------------- docs/done/LEMONBOSS-SYSTEM-DESIGN.md | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/architecture-v5.md | 533 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/claude-code-cron.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/open-api-manual.md | 143 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/qa_judge_req.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/01-vision.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/02-agent-architecture.md | 176 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/03-agent-model.md | 373 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/04-agentic-loop.md | 172 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/05-boss-meta-capabilities.md | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/06-sandbox-autonomy.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/07-task-handover.md | 218 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/08-differentiated-reflection.md | 364 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/09-usage-flow.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/10-runtime-architecture.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/11-directory-structure.md | 187 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/12-data-model.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/13-api-design.md | 195 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/15-innovator-meta-agent.md | 257 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/16-agent-conversation-architecture.md | 169 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/17-skill-orchestration-and-concurrency.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/18-local-filesystem-first-agent-encapsulation.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/19-orchestrator-tool-isolation.md | 165 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/20-scaffold-first-agent-creation.md | 244 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/21-fde-pipeline-architecture.md | 282 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/22-agent-memory-system.md | 159 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/23-agent-active-heartbeat.md | 101 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/24-company-layer-architecture.md | 578 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/25-bootstrap-mechanism.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/system-design/26-automated-hiring-orchestration.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/task_timeline_design.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/done/user-guides/08-base-agent-4-phase-guide.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/open-api-manual.md | 143 ----------------------------------------------------------------------------------------------------------------------------------------------- docs/qa_judge_req.md | 46 ---------------------------------------------- docs/system-design/01-vision.md | 50 -------------------------------------------------- docs/system-design/02-agent-architecture.md | 176 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/03-agent-model.md | 373 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/04-agentic-loop.md | 172 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/05-boss-meta-capabilities.md | 113 ----------------------------------------------------------------------------------------------------------------- docs/system-design/06-sandbox-autonomy.md | 58 ---------------------------------------------------------- docs/system-design/07-task-handover.md | 218 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/08-differentiated-reflection.md | 364 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/09-usage-flow.md | 80 -------------------------------------------------------------------------------- docs/system-design/10-runtime-architecture.md | 202 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/11-directory-structure.md | 187 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/12-data-model.md | 95 ----------------------------------------------------------------------------------------------- docs/system-design/13-api-design.md | 195 --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/14-milestones.md | 104 -------------------------------------------------------------------------------------------------------- docs/system-design/15-innovator-meta-agent.md | 257 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/16-agent-conversation-architecture.md | 169 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/17-skill-orchestration-and-concurrency.md | 71 ----------------------------------------------------------------------- docs/system-design/18-local-filesystem-first-agent-encapsulation.md | 45 --------------------------------------------- docs/system-design/19-orchestrator-tool-isolation.md | 165 --------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/20-scaffold-first-agent-creation.md | 244 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/21-fde-pipeline-architecture.md | 282 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ docs/system-design/22-agent-memory-system.md | 159 --------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/23-agent-active-heartbeat.md | 101 ----------------------------------------------------------------------------------------------------- docs/system-design/24-company-layer-architecture.md | 578 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/system-design/25-bootstrap-mechanism.md | 123 --------------------------------------------------------------------------------------------------------------------------- docs/system-design/25-harness-engineering-improvements.md | 59 ----------------------------------------------------------- docs/system-design/26-automated-hiring-orchestration.md | 166 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- docs/task_timeline_design.md | 91 ------------------------------------------------------------------------------------------- docs/todo/future/architecture_todo_list.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/todo/future/system-design/14-milestones.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/todo/future/system-design/25-harness-engineering-improvements.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/todo/system-design/27-graph-agent-architecture.md | 3 ++- docs/todo/system-design/27-p2-org-graph.md | 437 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/user-guides/08-base-agent-4-phase-guide.md | 63 --------------------------------------------------------------- 73 files changed, 6506 insertions(+), 6017 deletions(-) delete mode 100644 docs/LEMONBOSS-SYSTEM-DESIGN.md create mode 100644 docs/README.md delete mode 100644 docs/architecture-v5.md delete mode 100644 docs/architecture_todo_list.md delete mode 100644 docs/claude-code-cron.md create mode 100644 docs/done/LEMONBOSS-SYSTEM-DESIGN.md create mode 100644 docs/done/architecture-v5.md create mode 100644 docs/done/claude-code-cron.md create mode 100644 docs/done/open-api-manual.md create mode 100644 docs/done/qa_judge_req.md create mode 100644 docs/done/system-design/01-vision.md create mode 100644 docs/done/system-design/02-agent-architecture.md create mode 100644 docs/done/system-design/03-agent-model.md create mode 100644 docs/done/system-design/04-agentic-loop.md create mode 100644 docs/done/system-design/05-boss-meta-capabilities.md create mode 100644 docs/done/system-design/06-sandbox-autonomy.md create mode 100644 docs/done/system-design/07-task-handover.md create mode 100644 docs/done/system-design/08-differentiated-reflection.md create mode 100644 docs/done/system-design/09-usage-flow.md create mode 100644 docs/done/system-design/10-runtime-architecture.md create mode 100644 docs/done/system-design/11-directory-structure.md create mode 100644 docs/done/system-design/12-data-model.md create mode 100644 docs/done/system-design/13-api-design.md create mode 100644 docs/done/system-design/15-innovator-meta-agent.md create mode 100644 docs/done/system-design/16-agent-conversation-architecture.md create mode 100644 docs/done/system-design/17-skill-orchestration-and-concurrency.md create mode 100644 docs/done/system-design/18-local-filesystem-first-agent-encapsulation.md create mode 100644 docs/done/system-design/19-orchestrator-tool-isolation.md create mode 100644 docs/done/system-design/20-scaffold-first-agent-creation.md create mode 100644 docs/done/system-design/21-fde-pipeline-architecture.md create mode 100644 docs/done/system-design/22-agent-memory-system.md create mode 100644 docs/done/system-design/23-agent-active-heartbeat.md create mode 100644 docs/done/system-design/24-company-layer-architecture.md create mode 100644 docs/done/system-design/25-bootstrap-mechanism.md create mode 100644 docs/done/system-design/26-automated-hiring-orchestration.md create mode 100644 docs/done/task_timeline_design.md create mode 100644 docs/done/user-guides/08-base-agent-4-phase-guide.md delete mode 100644 docs/open-api-manual.md delete mode 100644 docs/qa_judge_req.md delete mode 100644 docs/system-design/01-vision.md delete mode 100644 docs/system-design/02-agent-architecture.md delete mode 100644 docs/system-design/03-agent-model.md delete mode 100644 docs/system-design/04-agentic-loop.md delete mode 100644 docs/system-design/05-boss-meta-capabilities.md delete mode 100644 docs/system-design/06-sandbox-autonomy.md delete mode 100644 docs/system-design/07-task-handover.md delete mode 100644 docs/system-design/08-differentiated-reflection.md delete mode 100644 docs/system-design/09-usage-flow.md delete mode 100644 docs/system-design/10-runtime-architecture.md delete mode 100644 docs/system-design/11-directory-structure.md delete mode 100644 docs/system-design/12-data-model.md delete mode 100644 docs/system-design/13-api-design.md delete mode 100644 docs/system-design/14-milestones.md delete mode 100644 docs/system-design/15-innovator-meta-agent.md delete mode 100644 docs/system-design/16-agent-conversation-architecture.md delete mode 100644 docs/system-design/17-skill-orchestration-and-concurrency.md delete mode 100644 docs/system-design/18-local-filesystem-first-agent-encapsulation.md delete mode 100644 docs/system-design/19-orchestrator-tool-isolation.md delete mode 100644 docs/system-design/20-scaffold-first-agent-creation.md delete mode 100644 docs/system-design/21-fde-pipeline-architecture.md delete mode 100644 docs/system-design/22-agent-memory-system.md delete mode 100644 docs/system-design/23-agent-active-heartbeat.md delete mode 100644 docs/system-design/24-company-layer-architecture.md delete mode 100644 docs/system-design/25-bootstrap-mechanism.md delete mode 100644 docs/system-design/25-harness-engineering-improvements.md delete mode 100644 docs/system-design/26-automated-hiring-orchestration.md delete mode 100644 docs/task_timeline_design.md create mode 100644 docs/todo/future/architecture_todo_list.md create mode 100644 docs/todo/future/system-design/14-milestones.md create mode 100644 docs/todo/future/system-design/25-harness-engineering-improvements.md create mode 100644 docs/todo/system-design/27-p2-org-graph.md delete mode 100644 docs/user-guides/08-base-agent-4-phase-guide.md diff --git a/docs/LEMONBOSS-SYSTEM-DESIGN.md b/docs/LEMONBOSS-SYSTEM-DESIGN.md deleted file mode 100644 index 983b14f..0000000 --- a/docs/LEMONBOSS-SYSTEM-DESIGN.md +++ /dev/null @@ -1,108 +0,0 @@ -# LemonBoss — 企业运营 Agentic Loop 框架 - -## 系统设计文档 v2.0 - -> **One-liner**: 构建一个 "道-法-术-器" 四层虚拟公司多智能体运营系统。Master 对齐人类意图，CXO 制衡决策，Role 专业执行，Skill 原子产出。每层独立 Loop，四级联动形成飞轮。 - ---- - -## 架构全景 - -``` -┌─────────────────────────────────────────────────────────────────────┐ -│ LemonBoss 框架层 │ -│ 提供: Agent 生命周期 / Loop 引擎 / 四层调度 / 沙盒 / 通讯 │ -│ 不管: Agent 内部怎么实现业务逻辑 │ -│ │ -│ ┌──────────────┐ │ -│ │ Master │ ← 道: 御前 — 人机共识，意图对齐 │ -│ └──────┬───────┘ │ -│ │ │ -│ ┌───────────┼───────────┐ │ -│ │ │ │ │ -│ ┌──▼───┐ ┌───▼───┐ ┌───▼───┐ │ -│ │ CEO │ │ CTO │ │ COO │ ← 法: 三省 — 战略决策，制衡审核 │ -│ └──┬───┘ └───┬───┘ └───┬───┘ │ -│ │ │ │ │ -│ ┌──▼───┐ ┌──▼───┐ ┌──▼───┐ │ -│ │编剧部│ │开发部 │ │运营部 │ ← 术: 六部 — 领域专业执行 │ -│ └──┬───┘ └──┬───┘ └──┬───┘ │ -│ │ │ │ │ -│ ┌──▼──┐ ┌──▼──┐ ┌──▼──┐ │ -│ │Skill│ │Skill│ │Skill│ ← 器: 吏治 — 原子执行，高度可复用 │ -│ │ ws/ │ │ ws/ │ │ ws/ │ │ -│ └─────┘ └─────┘ └─────┘ │ -│ │ -│ 四层 Loop 各自闭环反馈 → 四级联动飞轮 │ -│ │ -└─────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## 文档目录 - -> 每章为独立文档，位于 `docs/system-design/` 子目录。 - -### 核心架构 - -| # | 章节 | 文件 | 概要 | -|---|------|------|------| -| 1 | **系统愿景与核心概念** | [01-vision.md](./system-design/01-vision.md) | 道-法-术-器 哲学框架 + 核心概念 | -| 2 | **四层 Agent 架构** | [02-agent-architecture.md](./system-design/02-agent-architecture.md) | Master(御前) → CXO(三省) → Role(六部) → Skill(吏治) | -| 3 | **Agent 原子模型** | [03-agent-model.md](./system-design/03-agent-model.md) | 目录即实例: 6 大 Bootstrap Files + skills/ + memory/ + workspace/ | -| 4 | **Agentic Loop 循环引擎** | [04-agentic-loop.md](./system-design/04-agentic-loop.md) | 5 阶段循环 + 四层嵌套 | - -### v1.2 核心升级 - -| # | 章节 | 文件 | 概要 | -|---|------|------|------| -| 5 | **分层元能力** | [05-boss-meta-capabilities.md](./system-design/05-boss-meta-capabilities.md) | Master→CXO→Role 逐层管理 + CXO 制衡产出 Pipeline | -| 6 | **Agent 沙盒自治** | [06-sandbox-autonomy.md](./system-design/06-sandbox-autonomy.md) | Workspace 目录 + 资源隔离 | -| 7 | **Agent 间通讯架构** | [07-task-handover.md](./system-design/07-task-handover.md) | 框架中转通讯 + 11 种消息类型 + 三种数据共享 | -| 8 | **自我迭代闭环** | [08-differentiated-reflection.md](./system-design/08-differentiated-reflection.md) | 出生训练(Hunt→Digest→Evolving) + 四级迭代(L1记忆/L2技能/L3上级/L4组织) | - -### 实现规格 - -| # | 章节 | 文件 | 概要 | -|---|------|------|------| -| 9 | **使用流程** | [09-usage-flow.md](./system-design/09-usage-flow.md) | 初始化 + 运行时序 | -| 10 | **运行时架构与并发模型** | [10-runtime-architecture.md](./system-design/10-runtime-architecture.md) | 主进程 + N 子进程 + stdio pipe + ToolInterceptor | -| 11 | **目录结构** | [11-directory-structure.md](./system-design/11-directory-structure.md) | packages / server / web / data 全貌 | -| 12 | **数据模型** | [12-data-model.md](./system-design/12-data-model.md) | 5 张核心表（agent type: master/cxo/role/skill） | -| 13 | **API 设计** | [13-api-design.md](./system-design/13-api-design.md) | Agent + Company + Goals + Innovator REST API | -| 14 | **里程碑与附录** | [14-milestones.md](./system-design/14-milestones.md) | 迭代计划 + 决策表 + 术语表 | - -### 进阶架构 - -| # | 章节 | 文件 | 概要 | -|---|------|------|------| -| 15 | **Innovator 元 Agent** | [15-innovator-meta-agent.md](./system-design/15-innovator-meta-agent.md) | 第一个手动创建的 Agent，负责创建、训练、交付其他 Agent | -| 16 | **Agent 对话架构** | [16-agent-conversation-architecture.md](./system-design/16-agent-conversation-architecture.md) | 两层日志 + 多轮上下文恢复 | -| 17 | **Skill 编排与并发** | [17-skill-orchestration-and-concurrency.md](./system-design/17-skill-orchestration-and-concurrency.md) | 废除 SQLite 绑定，确立 Local File-System First | -| 18 | **本地文件系统优先** | [18-local-filesystem-first-agent-encapsulation.md](./system-design/18-local-filesystem-first-agent-encapsulation.md) | Agent 完全自治架构 v3.5 | -| 19 | **工具隔离机制** | [19-orchestrator-tool-isolation.md](./system-design/19-orchestrator-tool-isolation.md) | CLI 启动参数层物理剥夺工具权限 | -| 20 | **Agent 创建流程** | [20-scaffold-first-agent-creation.md](./system-design/20-scaffold-first-agent-creation.md) | Scaffold-First 架构 | -| 21 | **FDE 训练流水线** | [21-fde-pipeline-architecture.md](./system-design/21-fde-pipeline-architecture.md) | Hunt→Digest→Evolving 三层训练架构 (≥ 95 分) | -| 22 | **Agent 记忆系统** | [22-agent-memory-system.md](./system-design/22-agent-memory-system.md) | 自动记忆读写 (E2E 27/27 通过) | -| 23 | **主动心跳系统** | [23-agent-active-heartbeat.md](./system-design/23-agent-active-heartbeat.md) | Agent + 公司级心跳监控 (已实现) | -| 24 | **公司层架构** | [24-company-layer-architecture.md](./system-design/24-company-layer-architecture.md) | Multi-Tenant 公司实例化 + 招聘系统 + Bootstrap (已实现) | -| 25 | **Bootstrap 自举机制** | [25-bootstrap-mechanism.md](./system-design/25-bootstrap-mechanism.md) | 公司创建时自动部署核心骨干团队 | -| 26 | **全自动招聘编排** | [26-automated-hiring-orchestration.md](./system-design/26-automated-hiring-orchestration.md) | Creator → Skills → Innovator 训练流水线 | - ---- - -## 版本历史 - -| 版本 | 日期 | 变更 | -|------|------|------| -| **v1.0** | 2026-03-21 | 初版：三层架构 (Sub/Role/Boss) + 5 阶段 Loop | -| **v1.1** | 2026-03-23 | 新增：元能力、沙箱自治、流转协议、分层反思 | -| **v1.2** | 2026-03-23 | **架构升级**：三层 → 四层 (Master/CXO/Role/Skill)。道-法-术-器哲学框架。 | -| **v2.0** | 2026-03-26 | **Multi-Tenant 重构**：Company 层实例化、模板库 + 招聘系统、Bootstrap 自举、SOP Pipeline、心跳系统、前端 Dashboard。目录结构迁移到 `system/` + `data/{companyId}/`。新增章节 15-24。 | - ---- - -> 📝 **文档版本**: v2.0 -> 📅 **更新日期**: 2026-03-26 -> ✍️ **维护者**: LemonBoss Team diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..093b5db --- /dev/null +++ b/docs/README.md @@ -0,0 +1,50 @@ +# docs 索引 + +文档按状态分为三个目录： + +- **`done/`** — 描述已实现 / 当前有效的架构与功能的文档（含长期参考手册）。 +- **`todo/`** — 当前正在推进的路线图/设计草案。 +- **`todo/future/`** — 尚未实现、但**不是当前重心**的待办（暂缓，等主线腾出手再回来处理）。 + +判断依据：文档正文的显式「状态」标记（✅ 已完成 / 已实现 vs 📝 设计中 / 未实现）、未勾选的 checklist，以及与代码库实际实现的交叉核对（见各条目备注）。 + +> **当前主线**：Graph Agent 架构重构（[27-graph-agent-architecture.md](./todo/system-design/27-graph-agent-architecture.md)）。`todo/` 下只保留这一份，其余待办已移入 `todo/future/`，避免和主线抢注意力。 + +## done/ + +| 文件 | 说明 | +|------|------| +| [LEMONBOSS-SYSTEM-DESIGN.md](./done/LEMONBOSS-SYSTEM-DESIGN.md) | 系统设计主索引 v2.0，含 27 章 `system-design/` 的总目录 | +| [architecture-v5.md](./done/architecture-v5.md) | v5.3 架构方案，Phase 1-6 已完成（Phase 7 认知架构条目单独见 todo/） | +| [claude-code-cron.md](./done/claude-code-cron.md) | Claude Code 原生 Cron 调度功能参考手册 | +| [open-api-manual.md](./done/open-api-manual.md) | ArenaSK Open API 外部调用手册 | +| [qa_judge_req.md](./done/qa_judge_req.md) | QA Judge Agent 需求文档 — 已在 `system/templates/qa-judge/` 落地 | +| [task_timeline_design.md](./done/task_timeline_design.md) | Task Timeline View 设计文档 — 已实现（`server/routes/tasks.js`、`server/services/task-service.js`、`web/src/views/TaskTimeline.vue`） | +| [user-guides/08-base-agent-4-phase-guide.md](./done/user-guides/08-base-agent-4-phase-guide.md) | Base Agent 四阶段使用指南 | +| [system-design/01-26](./done/system-design/) | 系统设计正文 01～26 章（14、25-harness-engineering-improvements 例外，见 todo/future/；27 例外，见 todo/），各章节状态见文内「状态」标记 | + +## todo/（当前主线） + +| 文件 | 说明 | +|------|------| +| [system-design/27-graph-agent-architecture.md](./todo/system-design/27-graph-agent-architecture.md) | Graph Agent 架构，状态：📝 设计中，未实现。P0-P6 分阶段路线图，当前唯一在推进的重构 | +| [system-design/27-p1-virtual-reference.md](./todo/system-design/27-p1-virtual-reference.md) | P1（虚拟引用）细化需求与设计文档：`getAgentConfig()`/`PromptBuilder.build()`/`hire()` 的具体改法、验收标准、blast radius、未决问题 | + +## todo/future/（暂缓，非当前重心） + +| 文件 | 说明 | +|------|------| +| [architecture_todo_list.md](./todo/future/architecture_todo_list.md) | FDE Pipeline 架构待办清单（Judge 系统 / 反馈闭环等五大维度）。与 Graph Agent 架构基本正交，其中第 4 点「版本回滚」与 27 号文档 P5 阶段的 git 版本化 `memory.md` 有部分重叠，P5 落地后可回来划掉 | +| [system-design/14-milestones.md](./todo/future/system-design/14-milestones.md) | 早期里程碑规划（v1.1，checklist 未勾选）。已被后续实际实现大幅绕过，主要留作历史存档，不建议优先处理 | +| [system-design/25-harness-engineering-improvements.md](./todo/future/system-design/25-harness-engineering-improvements.md) | Harness Engineering 改进提案（单 Agent 上下文管理），Phase 3-5 未落地。与 Graph Agent 架构（多 Agent 组织/图执行）维度不同，互不阻塞 | + +## 未纳入整理的目录 + +以下目录本身是**活跃系统的一部分**（不是静态文档），保持原位不动： + +- **`prd/`** — DevLoop 的 PRD/SDD 规格站点源文件。`prd/newfunction/*.html` 由 `npm run spec:extract` 读取生成 `prd/newfunction/_spec/*.md`，是代码依赖的机器可读规格，不是待归档的说明文档。 +- **`create-drama/`** — 独立的 Skill 工具子项目（含自身 `package.json` / `node_modules`），不是设计文档。 + +## 维护说明 + +新增文档时，先判断它描述的是**已实现的能力**（放 `done/`）、**当前正在推进的重心**（放 `todo/`），还是**尚未开始且非当前重心**（放 `todo/future/`）。功能落地后，将对应文档从 `todo/`（或 `todo/future/`）移到 `done/` 并更新本索引与 `LEMONBOSS-SYSTEM-DESIGN.md` 中的链接；当主线切换时（比如 Graph Agent 架构完成后），把 `todo/future/` 里优先级提升的条目挪回 `todo/`。 diff --git a/docs/architecture-v5.md b/docs/architecture-v5.md deleted file mode 100644 index 98064b5..0000000 --- a/docs/architecture-v5.md +++ /dev/null @@ -1,533 +0,0 @@ -# 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
思考·规划·反思"] - Cerebellum["🧩 小脑 Cerebellum
固化方案·代码执行"] - Hippocampus["🐴 海马体 Hippocampus
记忆·检索·匹配"] - 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 定时调度文档 | diff --git a/docs/architecture_todo_list.md b/docs/architecture_todo_list.md deleted file mode 100644 index 5e0f214..0000000 --- a/docs/architecture_todo_list.md +++ /dev/null @@ -1,146 +0,0 @@ -# FDE Pipeline Architecture Todo List (Roadmap & Evolution) - -当前 **Innovator控制的 Hunt -> Digest -> Evolve (FDE)** 训练全链路在机制串联上已完全跑通，但要将其打造为真正的自动化、防退化、工业级自主进化学习系统，还需在以下五个核心维度进行底层架构设计与增补： - -## 1. 致命短板：缺乏客观独立的“硬核验证” (True Evaluation / Judge System) -**现状问题**： -目前在 Evolve 阶段，由 LLM 本身（Evolver Agent）自行汇报分数并使用正则表达式匹配（如 `最终分数: 92`）。自我评价容易引发幻觉，分数缺乏说服力。 -**待办清单 (Todos)**： -- [ ] **独立的 Judge Agent（裁判系统）**：将生成与验证解耦。引入仅负责验证结果的评审型智能体，它不参与能力的生成逻辑。 -- [ ] **基于任务执行的自动化 Benchmark (Test-Driven Benchmark)**： - - 代码类 Agent：提供真实的可执行代码测试集（Unit/Integration tests）去执行和验证通过率。 - - 知识对话类 Agent：建立标准且动态更新的验收用例库（RAG QA 验证或基准测试）。 - -## 2. 真实长效的“反馈循环”未打通 (Missing Feedback Loop) -**现状问题**： -虽然定义为 **F**eedback-driven，但目前的系统触发很大程度上依赖手动指定 Retrain 指令，并非长期自动的闭环负反馈驱动。 -**待办清单 (Todos)**： -- [ ] **负样本与真实会话捕获机制机制 (Bad Case Capturing)**：用户在与目标 Agent（如 CEO Agent）交互时，点击的差评（👎）或会话纠正记录被视作失败样本（Bad Cases），系统需要自动沉淀。 -- [ ] **无缝的热更新触发器 (Auto-Triggered Evolve)**：当失败用例阈值达到设定条件，自动唤醒 Digester 分析失败成因，沉淀为新的约束并交由 Evolver 无人值守地执行热更新修改。 - -## 3. 数据抓取与处理的边界稳定性 (Hunt Phase Robustness) -**现状问题**： -Hunter 代理重度依赖通用 WebSearch 和底层 Bash 调用来搜集知识。这种方式在面对特定或垂直领域时返回噪音大，且容易遭到反爬或速率限制影响而导致运行不稳定甚至超时被杀。 -**待办清单 (Todos)**： -- [ ] **原生特定域垂直 API 的接入 (Domain-specific Sourcing)**：针对不同职业（财务、法律等）配置特定领域的官方或标准 API 接口池，而不是单一通用搜索引擎。 -- [ ] **内部向量数据库接入与 RAG 整合**：不仅去公网找，还应当对接企业内部已有的私有知识库引擎。 -- [ ] **长文本清洗管道 (Doc Cleansing Pipeline)**：增加自动化的向量摘要预处理层或 Map-Reduce 清流机制，防止大规模抓取的网页或 PDF 撑爆提示词导致焦点丢失。 - -## 4. 进化过程中的“灾难性遗忘”防范 (Version Control & Prevent Regression) -**现状问题**： -每次 Evolution 迭代都在直接修改原版 `SKILL.md` 和 `knowhow.md`。单纯针对这一次的“反馈任务”进行定向强化，可能会丢失或弱化老版本拥有的其他核心能力。 -**待办清单 (Todos)**： -- [ ] **版本强控与对比 (Version Diffing & Rollback)**：建立更细化的代码层面回滚机制。 -- [ ] **全量回归打分机制 (Automated Regression Test)**：在升级为主版本前，必须运行覆盖整体职能（不仅是本次修改的内容）的测试基准确保总分不滑坡才允许正式 Bump 新版本。 - -## 5. 沙盒与安全控制体系 (Execution Safety & Sandboxing) -**现状问题**： -底层的 Agent 执行利用了 `--dangerously-skip-permissions` 的超高权限来驱动。高度发散且无人值守的自我编程（Evolve）如果产生非安全的系统脚本，对宿主机资源具备致命危险。 -**待办清单 (Todos)**： -- [ ] **沙盒化的底层运行环境 (Containerized Execution)**：用类似 Docker 的容器级隔离来保护执行宿主，仅向 Agent 暴露安全的读写卷。 -- [ ] **危险操作熔断器与拦截隔离 (Command Interceptor)**：拦截类似格式化或删库等敏感命令的高频审计审查模块，防止大模型抽风时的不可逆破坏行为。 - ---- -> *文档最后更新：由自动开发助手基于 FDE 流程在业务实际运行的瓶颈节点整理提交。* -实际上，当前的 Master Agent + CEO Agent 配合刚才跑通的 FDE (Innovator, Hunter, Digester, Evolver) 流水线，是映射**“道、法、术、器”**四层架构最完美的天然载体。 - -我们可以将现有的系统组件像这样完全对齐，并构建出**“自动下发 -> 执行 -> 验证 -> 反馈自进化”**的自动化闭环： - -1. 架构映射 (四层体系的智能体分工) -【道】(核心愿景/战略意图) —— Master Agent + Human (你) -角色：顶层意图感知的枢纽。你给 Master 发布指令（例如：“我们要上线一个最高质量的古典诗词生成的 API 服务”）。 -功能：感知全局业务边界，它不负责具体落地，而是将模糊意图翻译成任务，派发给 CEO。 -【法】(组织法则/目标拆解) —— CEO Agent + GoalsService (OKR API) -角色：将“道”转化为可执行的“法度”与组织结构。 -功能：CEO 接到任务后，使用刚上线的 /api/goals 创建 OKR，然后利用 /api/agent/task/dispatch 委派任务。如果公司里没有诗人，CEO 会调用 agent-creator（HR 部门）现场“招聘/生成”一个 Poet Agent 和一个 QA Agent (品控)。 -【术】(训练方法/重构机制) —— Innovator Agent (及其下属 HDE 元代理) -角色：进化与纠偏的机制论。 -功能：它是保证“器（员工）”能满足“法（OKR）”的训练学院。 -【器】(执行工具/基层产出) —— 具体的业务 Agent (如 Poet, Coder, CTO 等) -角色：承载具体任务的基层实体。 -2. 现在的架构如何实现“下一步的自动化验证闭环”？ -根据目前 CEO 和 - -Master - 的系统 Prompt 设计，我们只需稍微打通一条“汇报链路”，即可彻底实现无需人工的自动化验证。具体流转如下： - -闭环运行 Workflow： - -战略拆解 (Fa)：CEO 制定目标 -> 生成 Poet Agent 负责写诗 -> 生成 Judge Agent 负责按国学标准打分。 -基层执行 (Qi)：Poet 交出作品。 -自动化验证 (Validate)：CEO 让 Judge 去给 Poet 的诗词打分。如果 Judge 判定不达标（比如只有 60 分，格律不对）。 -触发自动进化 (Shu)：CEO Agent 在收到 Judge 的负面报告后，发现 OKR 存在卡点。此时 CEO 会自动触发 Dispatch 调用 Innovator Agent，发送指令：“Poet Agent 目前格律经常写错，请对他进行重训，重点抓取古诗词格律（平仄）的 Knowhow”。 -FDE 系统自旋：Innovator 启动 Hunter -> Digester -> Evolver 对 Poet 深度改造，改造完升至 V1.1 版本。 -重试验收：改造完毕后，CEO 让升级后的 Poet 重写，Judge 再打分，一旦 Pass，则 CEO 将 OKR 节点更新为完成 (/api/goals/:id/progress)。最后在 - -plan.md - 里向 Master 汇报大捷。 -3. 要真正跑通这套验证闭环，目前代码库还差哪几个小改动？ -虽然底层 API（FDE, Dispatch, OKR）都已经开发好了，但要让上述联动行云流水，我们只要对目前的配置文件做这三点调整： - -修改 CEO 的 - -agent.md - (赋能进化的职权)： 目前 CEO 的提示词中主要是利用 agent-creator 生成员工，需要补充：“当你发现下属 Agent 产出质量不达标时，使用 api dispatch 任务给 innovator Agent，要求其对该劣质员工进行重新训练（Retrain）。” -补齐 QA/Judge Agent (裁判位缺失)： CEO 本身不擅长看代码或审读具体的底层产出。需要预设一个 Validator/Judge Agent 模板。一切 KPI 验收，CEO 都通过把结果转发给 Judge 生成评分报告来自动化判定。 -增加 Agent 间的广播/事件订阅 (Event Hook)： 目前 Agent 得主动去轮询（curl -s api/agent/todo）看小兄弟做完没。系统如果能加一个 Webhook（当 Innovator 进化完 V1.1 版、或者 Poet 提交完草稿后，自动给 CEO 的日志里推一条 [Task Completed] 的消息），CEO 的调度速度就会从轮询变成事件驱动，反应极快。 -总结：现在的 LemonBoss 基础库相当于已经造出了所有的齿轮和引擎（尤其是刚跑通的 FDE 进化）。只要在顶层的 CEO 和 - -Master - 提示词里建立“生成->验收->失败则提交重启训练”的规则指引，这套“道法术器”四层映射的自治公司就能开始实现真正的全自动进化运转。 - - 其实，我们在 digest 环节产生了 benchmark 在 evolve 环节是根据每次 skill 产生的内容，用 benchmark 打分，然后判断按照这个 benchmark 分数如果《95 分，就让他继续迭代，直到这个 skill 满足 95 分的这个 benchmark，才可以部署使用。这套逻辑跟你说的 qa judge agent 有什么区别和结合么？ - - - - - - - - - - - - - - - - - - - - -这是一个极其犀利且核心的问题！ - -简练地说，它们两者最大的区别在于：“驾照考试打分（造车）” vs “实际上路跑业务（开车）”。 - -它们不仅不冲突，反而恰好构成了不可或缺的**“双重防御与验证体系”**。我来帮你把它们在“道法术器”和工程实践中的区别与结合点彻底理清： - -1. 两者的核心区别 -【术】FDE 进化环节的 Benchmark (<95分迭代) —— 类似于“静态代码审查 / 驾照笔试” -它在校验什么？：它审查的是 Agent 的能力蓝图（定义）。Evolver 根据 Benchmark 去阅读 SKILL.md，它评定的 95 分代表：“这个 Prompt 写得真好、内置的 Knowhow 真专业、它理论上完全具备了这些能力”。 -它的局限性：这是一种“元认知（Meta-level）”的静态打分。就跟考驾照拿到了满分一样，理论上他是个好司机。但当他在真实项目中遇到极其复杂的业务边界问题时（比如复杂的上下文缺失、工具调用卡壳），空有完美 Prompt 的 Agent 一样可能会把任务搞砸。 -阶段：发生在出厂前 / 编译期（Training & Deployment Phase）。 -【法】QA/Judge Agent 的业务验收 —— 类似于“集成测试 / 实际上路出单” -它在校验什么？：它审查的是 Agent 的真实业务产出（Artifacts）。比如 CEO 让 Coder Agent 写了一个登录页面，QA Judge Agent 根本不关心 Coder 的 Prompt 写得多好，它只负责去审阅最后交出来的那段 React 代码到底能不能跑、有没有 Bug、是否符合需求规范。 -阶段：发生在运行时 / 生产环境（Runtime & Execution Phase）。 -2. 它们是如何完美结合的？（闭环全景图） -在强大的自主公司架构中，两者是**“上下半场”被彼此触发**的关系。结合刚才跑通的流水线，全网完美的自动演进链路是这样的： - -第一环（产出与验收）：日常业务跑在“QA Judge”的法度下 -下发任务：CEO 接到需求，派发给当前 v1.3 版本的业务 Agent（比如 CTO）。 -执行与送审：CTO 写好了一份技术架构图。CEO 不会自己看，而是把它扔给预设的 QA/Arch-Judge Agent 盲审。 -日常小修小补：如果 Judge 觉得某个细节不合理，打回给 CTO 重新改。这个时候 CTO 只是在当前会话里自我调整（这时候不需要重启 FDE 流水线）。 -第二环（瓶颈与重构）：被“QA Judge”触发的“FDE 训练” -发现致命短板：如果 Judge 发现 CTO 连续 3 次都在“高并发架构设计”上翻车，Judge 会向 CEO 提交定损报告：“当前 CTO 能力存在系统性认知缺陷（缺乏高并发知识库）”。 -触发造车（Retrain）：CEO 根据这份报告，判定现有的员工“器”不行了，必须让“术”介入。CEO 调用 API 给 - -Innovator - 发送指令：“马上把 CTO 弄回炉重训，附带这份 QA 的失败日志，重点加强高并发治理边界”。 -启动你说的 Benchmark 循环：此时，Innovator 接管，启动 Hunt -> Digest -> Evolve： -Digester 根据 QA 之前给出的失败原因，生成了一份极度苛刻的 benchmark.md（高并发处理必须包含 XXX，否则扣分）。 -Evolver 不断重写和迭代 CTO 的 SKILL.md，直到按照这份新考核标准评分 >= 95 分。 -重新上路部署：v1.4 版本的强力 CTO 满血回归，接手之前失败的任务。这次做完后交由 QA Judge，顺利验收通过（OKR 节点闭环）。 -总结 -你现在实现的 Digest Benchmark >= 95 分，保证了 LemonBoss 兵工厂里走出来的每一个兵（Agent）绝对是理论最强、装备精良的（出厂质量）。 -而增加的 Judge Agent 管理流，则保证了在具体打仗时，业务结果是100%兜底且客观过关的（业务质量）。一旦在真实战场发现某个兵的素质不够，再去触发那个工厂的 FDE 流水线 给它升级。这就是真 正自洽的自动驾驶级 AI 公司架构！ \ No newline at end of file diff --git a/docs/claude-code-cron.md b/docs/claude-code-cron.md deleted file mode 100644 index 1ac8519..0000000 --- a/docs/claude-code-cron.md +++ /dev/null @@ -1,80 +0,0 @@ -# Claude Code 定时调度 (Cron) 功能 - -> **官方文档**: https://code.claude.com/docs/en/scheduled-tasks.md -> **工具参考**: https://code.claude.com/docs/en/tools-reference.md -> **文档索引**: https://code.claude.com/docs/en/claude_code_docs_map.md - -## 概述 - -Claude Code 原生支持定时调度，通过 `CronCreate` / `CronList` / `CronDelete` 三个原生工具实现。 - -## 核心工具 - -| 工具 | 用途 | -|------|------| -| `CronCreate` | 创建定时任务。接受 5-field cron 表达式 + prompt + 是否循环 | -| `CronList` | 列出当前所有定时任务及其 ID、调度、prompt | -| `CronDelete` | 通过 8 位 ID 取消指定任务 | - -## Cron 表达式格式 - -标准 5-field: `minute hour day-of-month month day-of-week` - -| 表达式 | 含义 | -|--------|------| -| `*/5 * * * *` | 每 5 分钟 | -| `*/3 * * * *` | 每 3 分钟 | -| `*/30 * * * *` | 每 30 分钟 | -| `0 * * * *` | 每小时整点 | -| `0 9 * * *` | 每天早 9 点 | -| `0 9 * * 1-5` | 工作日早 9 点 | - -## 调度方式对比 - -| | Cloud | Desktop /schedule | /loop (CLI) | -|---|---|---|---| -| 运行在 | Anthropic 云端 | 本地机器 | 本地机器 | -| 需要机器开启 | 否 | 是 | 是 | -| 需要打开会话 | 否 | 否 | **是** | -| 跨重启持久化 | 是 | 是 | **否 (session-scoped)** | -| 访问本地文件 | 否 | 是 | 是 | -| 最小间隔 | 1 小时 | 1 分钟 | 1 分钟 | - -## 关键限制 - -1. **Session-scoped**: `/loop` 和 `CronCreate` 创建的任务仅在 Claude Code 运行且空闲时触发。关闭终端或退出会话后，所有任务取消。 -2. **3 天过期**: 循环任务自动在 3 天后过期，防止无限运行。 -3. **最多 50 个**: 每个会话最多 50 个并发定时任务。 -4. **不补发**: 如果任务触发时 Claude 正在忙，等空闲后只触发一次，不补发错过的。 -5. **Jitter**: 循环任务有最多 10% 的延迟抖动（上限 15 分钟）。 - -## LemonBoss 持久化方案 - -由于 CronCreate 是 session-scoped，我们使用 **cron.json + 会话启动自动注入** 来实现持久化： - -### cron.json 格式 - -```json -[ - { - "schedule": "*/5 * * * *", - "prompt": "读取 plan.md 检查已分发任务进度", - "recurring": true, - "enabled": true - } -] -``` - -### 工作流程 - -1. Agent 目录下有 `cron.json` 定义期望的定时任务 -2. 每次新建 ACP 会话时，后端自动读取 cron.json -3. 在第一条 system prompt 中注入 CronCreate 恢复指令 -4. Agent 调用 CronCreate 重建所有定时任务 - -### 文件位置 - -- 文档: `docs/claude-code-cron.md` (本文件) -- 模板: `packages/agent-core/AgentScaffold.js` (_defaultCronJson) -- 注入点: `server/routes/agent-chat.js` (buildPrompt) -- Agent 配置: `data/agents/{agent-id}/cron.json` diff --git a/docs/done/LEMONBOSS-SYSTEM-DESIGN.md b/docs/done/LEMONBOSS-SYSTEM-DESIGN.md new file mode 100644 index 0000000..a380b30 --- /dev/null +++ b/docs/done/LEMONBOSS-SYSTEM-DESIGN.md @@ -0,0 +1,109 @@ +# LemonBoss — 企业运营 Agentic Loop 框架 + +## 系统设计文档 v2.0 + +> **One-liner**: 构建一个 "道-法-术-器" 四层虚拟公司多智能体运营系统。Master 对齐人类意图，CXO 制衡决策，Role 专业执行，Skill 原子产出。每层独立 Loop，四级联动形成飞轮。 + +--- + +## 架构全景 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ LemonBoss 框架层 │ +│ 提供: Agent 生命周期 / Loop 引擎 / 四层调度 / 沙盒 / 通讯 │ +│ 不管: Agent 内部怎么实现业务逻辑 │ +│ │ +│ ┌──────────────┐ │ +│ │ Master │ ← 道: 御前 — 人机共识，意图对齐 │ +│ └──────┬───────┘ │ +│ │ │ +│ ┌───────────┼───────────┐ │ +│ │ │ │ │ +│ ┌──▼───┐ ┌───▼───┐ ┌───▼───┐ │ +│ │ CEO │ │ CTO │ │ COO │ ← 法: 三省 — 战略决策，制衡审核 │ +│ └──┬───┘ └───┬───┘ └───┬───┘ │ +│ │ │ │ │ +│ ┌──▼───┐ ┌──▼───┐ ┌──▼───┐ │ +│ │编剧部│ │开发部 │ │运营部 │ ← 术: 六部 — 领域专业执行 │ +│ └──┬───┘ └──┬───┘ └──┬───┘ │ +│ │ │ │ │ +│ ┌──▼──┐ ┌──▼──┐ ┌──▼──┐ │ +│ │Skill│ │Skill│ │Skill│ ← 器: 吏治 — 原子执行，高度可复用 │ +│ │ ws/ │ │ ws/ │ │ ws/ │ │ +│ └─────┘ └─────┘ └─────┘ │ +│ │ +│ 四层 Loop 各自闭环反馈 → 四级联动飞轮 │ +│ │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 文档目录 + +> 每章为独立文档，位于 `docs/system-design/` 子目录。 + +### 核心架构 + +| # | 章节 | 文件 | 概要 | +|---|------|------|------| +| 1 | **系统愿景与核心概念** | [01-vision.md](./system-design/01-vision.md) | 道-法-术-器 哲学框架 + 核心概念 | +| 2 | **四层 Agent 架构** | [02-agent-architecture.md](./system-design/02-agent-architecture.md) | Master(御前) → CXO(三省) → Role(六部) → Skill(吏治) | +| 3 | **Agent 原子模型** | [03-agent-model.md](./system-design/03-agent-model.md) | 目录即实例: 6 大 Bootstrap Files + skills/ + memory/ + workspace/ | +| 4 | **Agentic Loop 循环引擎** | [04-agentic-loop.md](./system-design/04-agentic-loop.md) | 5 阶段循环 + 四层嵌套 | + +### v1.2 核心升级 + +| # | 章节 | 文件 | 概要 | +|---|------|------|------| +| 5 | **分层元能力** | [05-boss-meta-capabilities.md](./system-design/05-boss-meta-capabilities.md) | Master→CXO→Role 逐层管理 + CXO 制衡产出 Pipeline | +| 6 | **Agent 沙盒自治** | [06-sandbox-autonomy.md](./system-design/06-sandbox-autonomy.md) | Workspace 目录 + 资源隔离 | +| 7 | **Agent 间通讯架构** | [07-task-handover.md](./system-design/07-task-handover.md) | 框架中转通讯 + 11 种消息类型 + 三种数据共享 | +| 8 | **自我迭代闭环** | [08-differentiated-reflection.md](./system-design/08-differentiated-reflection.md) | 出生训练(Hunt→Digest→Evolving) + 四级迭代(L1记忆/L2技能/L3上级/L4组织) | + +### 实现规格 + +| # | 章节 | 文件 | 概要 | +|---|------|------|------| +| 9 | **使用流程** | [09-usage-flow.md](./system-design/09-usage-flow.md) | 初始化 + 运行时序 | +| 10 | **运行时架构与并发模型** | [10-runtime-architecture.md](./system-design/10-runtime-architecture.md) | 主进程 + N 子进程 + stdio pipe + ToolInterceptor | +| 11 | **目录结构** | [11-directory-structure.md](./system-design/11-directory-structure.md) | packages / server / web / data 全貌 | +| 12 | **数据模型** | [12-data-model.md](./system-design/12-data-model.md) | 5 张核心表（agent type: master/cxo/role/skill） | +| 13 | **API 设计** | [13-api-design.md](./system-design/13-api-design.md) | Agent + Company + Goals + Innovator REST API | +| 14 | **里程碑与附录** | [14-milestones.md](../todo/future/system-design/14-milestones.md) | 迭代计划 + 决策表 + 术语表（📦 已过时存档，见 docs/todo/future/） | + +### 进阶架构 + +| # | 章节 | 文件 | 概要 | +|---|------|------|------| +| 15 | **Innovator 元 Agent** | [15-innovator-meta-agent.md](./system-design/15-innovator-meta-agent.md) | 第一个手动创建的 Agent，负责创建、训练、交付其他 Agent | +| 16 | **Agent 对话架构** | [16-agent-conversation-architecture.md](./system-design/16-agent-conversation-architecture.md) | 两层日志 + 多轮上下文恢复 | +| 17 | **Skill 编排与并发** | [17-skill-orchestration-and-concurrency.md](./system-design/17-skill-orchestration-and-concurrency.md) | 废除 SQLite 绑定，确立 Local File-System First | +| 18 | **本地文件系统优先** | [18-local-filesystem-first-agent-encapsulation.md](./system-design/18-local-filesystem-first-agent-encapsulation.md) | Agent 完全自治架构 v3.5 | +| 19 | **工具隔离机制** | [19-orchestrator-tool-isolation.md](./system-design/19-orchestrator-tool-isolation.md) | CLI 启动参数层物理剥夺工具权限 | +| 20 | **Agent 创建流程** | [20-scaffold-first-agent-creation.md](./system-design/20-scaffold-first-agent-creation.md) | Scaffold-First 架构 | +| 21 | **FDE 训练流水线** | [21-fde-pipeline-architecture.md](./system-design/21-fde-pipeline-architecture.md) | Hunt→Digest→Evolving 三层训练架构 (≥ 95 分) | +| 22 | **Agent 记忆系统** | [22-agent-memory-system.md](./system-design/22-agent-memory-system.md) | 自动记忆读写 (E2E 27/27 通过) | +| 23 | **主动心跳系统** | [23-agent-active-heartbeat.md](./system-design/23-agent-active-heartbeat.md) | Agent + 公司级心跳监控 (已实现) | +| 24 | **公司层架构** | [24-company-layer-architecture.md](./system-design/24-company-layer-architecture.md) | Multi-Tenant 公司实例化 + 招聘系统 + Bootstrap (已实现) | +| 25 | **Bootstrap 自举机制** | [25-bootstrap-mechanism.md](./system-design/25-bootstrap-mechanism.md) | 公司创建时自动部署核心骨干团队 | +| 26 | **全自动招聘编排** | [26-automated-hiring-orchestration.md](./system-design/26-automated-hiring-orchestration.md) | Creator → Skills → Innovator 训练流水线 | +| 27 | **Graph Agent 架构** | [27-graph-agent-architecture.md](../todo/system-design/27-graph-agent-architecture.md) | Org Graph / Work Graph + System Agent 统一寻址，取代 Template 拷贝模型（⏳ 设计中，见 docs/todo/） | + +--- + +## 版本历史 + +| 版本 | 日期 | 变更 | +|------|------|------| +| **v1.0** | 2026-03-21 | 初版：三层架构 (Sub/Role/Boss) + 5 阶段 Loop | +| **v1.1** | 2026-03-23 | 新增：元能力、沙箱自治、流转协议、分层反思 | +| **v1.2** | 2026-03-23 | **架构升级**：三层 → 四层 (Master/CXO/Role/Skill)。道-法-术-器哲学框架。 | +| **v2.0** | 2026-03-26 | **Multi-Tenant 重构**：Company 层实例化、模板库 + 招聘系统、Bootstrap 自举、SOP Pipeline、心跳系统、前端 Dashboard。目录结构迁移到 `system/` + `data/{companyId}/`。新增章节 15-24。 | + +--- + +> 📝 **文档版本**: v2.0 +> 📅 **更新日期**: 2026-03-26 +> ✍️ **维护者**: LemonBoss Team diff --git a/docs/done/architecture-v5.md b/docs/done/architecture-v5.md new file mode 100644 index 0000000..d007d9c --- /dev/null +++ b/docs/done/architecture-v5.md @@ -0,0 +1,533 @@ +# 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
思考·规划·反思"] + Cerebellum["🧩 小脑 Cerebellum
固化方案·代码执行"] + Hippocampus["🐴 海马体 Hippocampus
记忆·检索·匹配"] + 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/done/claude-code-cron.md` | Claude Code 定时调度文档 | diff --git a/docs/done/claude-code-cron.md b/docs/done/claude-code-cron.md new file mode 100644 index 0000000..a281a8a --- /dev/null +++ b/docs/done/claude-code-cron.md @@ -0,0 +1,80 @@ +# Claude Code 定时调度 (Cron) 功能 + +> **官方文档**: https://code.claude.com/docs/en/scheduled-tasks.md +> **工具参考**: https://code.claude.com/docs/en/tools-reference.md +> **文档索引**: https://code.claude.com/docs/en/claude_code_docs_map.md + +## 概述 + +Claude Code 原生支持定时调度，通过 `CronCreate` / `CronList` / `CronDelete` 三个原生工具实现。 + +## 核心工具 + +| 工具 | 用途 | +|------|------| +| `CronCreate` | 创建定时任务。接受 5-field cron 表达式 + prompt + 是否循环 | +| `CronList` | 列出当前所有定时任务及其 ID、调度、prompt | +| `CronDelete` | 通过 8 位 ID 取消指定任务 | + +## Cron 表达式格式 + +标准 5-field: `minute hour day-of-month month day-of-week` + +| 表达式 | 含义 | +|--------|------| +| `*/5 * * * *` | 每 5 分钟 | +| `*/3 * * * *` | 每 3 分钟 | +| `*/30 * * * *` | 每 30 分钟 | +| `0 * * * *` | 每小时整点 | +| `0 9 * * *` | 每天早 9 点 | +| `0 9 * * 1-5` | 工作日早 9 点 | + +## 调度方式对比 + +| | Cloud | Desktop /schedule | /loop (CLI) | +|---|---|---|---| +| 运行在 | Anthropic 云端 | 本地机器 | 本地机器 | +| 需要机器开启 | 否 | 是 | 是 | +| 需要打开会话 | 否 | 否 | **是** | +| 跨重启持久化 | 是 | 是 | **否 (session-scoped)** | +| 访问本地文件 | 否 | 是 | 是 | +| 最小间隔 | 1 小时 | 1 分钟 | 1 分钟 | + +## 关键限制 + +1. **Session-scoped**: `/loop` 和 `CronCreate` 创建的任务仅在 Claude Code 运行且空闲时触发。关闭终端或退出会话后，所有任务取消。 +2. **3 天过期**: 循环任务自动在 3 天后过期，防止无限运行。 +3. **最多 50 个**: 每个会话最多 50 个并发定时任务。 +4. **不补发**: 如果任务触发时 Claude 正在忙，等空闲后只触发一次，不补发错过的。 +5. **Jitter**: 循环任务有最多 10% 的延迟抖动（上限 15 分钟）。 + +## LemonBoss 持久化方案 + +由于 CronCreate 是 session-scoped，我们使用 **cron.json + 会话启动自动注入** 来实现持久化： + +### cron.json 格式 + +```json +[ + { + "schedule": "*/5 * * * *", + "prompt": "读取 plan.md 检查已分发任务进度", + "recurring": true, + "enabled": true + } +] +``` + +### 工作流程 + +1. Agent 目录下有 `cron.json` 定义期望的定时任务 +2. 每次新建 ACP 会话时，后端自动读取 cron.json +3. 在第一条 system prompt 中注入 CronCreate 恢复指令 +4. Agent 调用 CronCreate 重建所有定时任务 + +### 文件位置 + +- 文档: `docs/done/claude-code-cron.md` (本文件) +- 模板: `packages/agent-core/AgentScaffold.js` (_defaultCronJson) +- 注入点: `server/routes/agent-chat.js` (buildPrompt) +- Agent 配置: `data/agents/{agent-id}/cron.json` diff --git a/docs/done/open-api-manual.md b/docs/done/open-api-manual.md new file mode 100644 index 0000000..a3fe7f2 --- /dev/null +++ b/docs/done/open-api-manual.md @@ -0,0 +1,143 @@ +# ArenaSK Open API 外部调用操作手册 + +本手册详细说明了如何通过外部系统（如第三方业务系统、自动化流、外部脚本）跨平台调用 LemonBoss 平台内部已经部署的任意 Agent。 + +--- + +## 1. 认证配置 (Authentication) + +调用系统的任何开放接口前，必须在 HTTP 标头 (Headers) 中携带你申请/配置的 API Key 密钥。 + +**系统配置位置**： +当前系统支持的 API Key 配置位于项目根目录的 `.env` 文件内： +```ini +OPEN_API_KEYS=sk-test-key-001,sk-prod-key-... +``` + +**请求方式**： +无论你用什么语言发送请求，请确保 HTTP Headers 包含以下任意一种格式： +- `Authorization: Bearer ` (推荐) +- `X-API-Key: ` + +--- + +## 2. 核心调用流程 + +因为我们的 Agent 需要进行「思考与执行 (Plan & Execute)」，单次任务通常耗时数分钟。为了防止网络超时断连，我们的接口设计完全**异步化 (Asynchronous)**： + +> **完整调用链路：** +> 👉 外部发送请求 `invoke` ➔ 系统接管并**返回单号 jobId** ➔ 外部每隔几秒根据 jobId去查进度 `poll` ➔ 遇到 **`completed`** 则提取输出。 + +### 接口 ①：指派任务并获取 JobId (Invoke) + +**🔹 端点**：`POST /api/open/companies/:companyId/agents/:agentId/invoke` +**🔹 作用**：唤起指定公司和指定名称的 Agent 执行任务。 + +#### 请求参数 (Body) + +| 参数名 | 类型 | 必填 | 说明 |示例| +|---------|-------|------|------|------| +| `task` | String | ✅ | 需要 Agent 帮您执行的自然语言任务。 | `"帮我爬取并总结最新的 AI agent 趋势"`| +| `contextFiles` | Array | 选填 | 外部传递前置文件，Agent可以据此进行**记忆连接或文档问答**。|见下文详述| +| `webhookUrl` | String | 选填 | 回调地址。当任务完结时主动推送结果至该URL。| `"https://your-app/webhook"`| + +#### 代码示例 (cURL) +```bash +curl -X POST http://YOUR_SERVER_IP:3010/api/open/companies/test/agents/claude-youtube-skills/invoke \ + -H "Authorization: Bearer sk-test-key-001" \ + -H "Content-Type: application/json" \ + -d '{ + "task": "基于上次总结的结果，帮我提取其中所有的产品名称并生成CSV格式", + "contextFiles": [ + { + "name": "previous_result.md", + "content": "这是一段之前的调查结果......" + } + ] + }' +``` + +#### 返回值 +接口会光速返回 HTTP 202 的响应该结果： +```json +{ + "jobId": "job-1712461931-abcdef12", + "status": "queued", + "message": "Agent invocation job queued. Poll GET /api/open/jobs/job-1712461931-abcdef12 for status." +} +``` +此时你必须要把 `jobId` 记录下来！ + +--- + +### 接口 ②：轮询任务执行结果 (Status Polling) + +我们推荐外部系统（例如你的脚本中）使用 `while` 循环或定时任务，**每隔 3~5 秒钟**调用一次该接口查询。 + +**🔹 端点**：`GET /api/open/jobs/:jobId` + +#### 代码示例 (cURL) +```bash +curl "http://YOUR_SERVER_IP:3010/api/open/jobs/job-1712461931-abcdef12" \ + -H "Authorization: Bearer sk-test-key-001" +``` + +#### 返回值 +你可以通过判断返回体中的 `status` 字段来得知进度： + +**1. 正在执行时（Running / Queued）** +```json +{ + "jobId": "job-1712461931-abcdef12", + "status": "running", + "progress": "Executing agent task...", + "createdAt": "2026-04-07T12:00:00Z" +} +``` + +**2. 任务已完成时（Completed）** 🌟 此刻可以提取最终结果： +```json +{ + "jobId": "job-1712461931-abcdef12", + "status": "completed", + "progress": "Invocation completed", + "result": { + "output": "你好！我已经完成了产品名称提取。这里是转换后的 CSV 格式内容...\n..." + } +} +``` + +**3. 任务失败异常时（Failed）** +```json +{ + "jobId": "job-1712461931-abcdef12", + "status": "failed", + "error": "Agent execution failed: process timeout." +} +``` + +--- + +## 3. 高级用法指南 + +### 如何保持“上下文记忆”或者“持续对话”？ + +Agent 是没有自动长久记忆跨系统调用流的。你在下一次调用相同的这个 Agent（比如第二天再调一次）时，如果想让它知道前面发生了什么，或者传递新的数据报告给它，**一定要使用 `contextFiles` 数组结构！**。 + +外部系统提取了上次的 `result.output` 后，在下次调用的 Body 中： +```json +{ + "task": "基于我附加给你的日志总结，开展新一轮的数据清理", + "contextFiles": [ + { + "name": "logs-from-yesterday.txt", + "content": "....提取的昨日任务输出大段文本...." + }, + { + "name": "data.csv", + "content": "id,name\n1,apple" + } + ] +} +``` +系统底座会自动将这 2 个对象落地成文件，以文本阅读的视角送入 Agent 的大脑供其深度理解（支持上万字）。通过这种 “外部系统充当记忆保管员 + API 动态投喂上下文文件” 的组合拳，就可以把这些 Agent 变成可控、随时插拔的智能化函数库！ diff --git a/docs/done/qa_judge_req.md b/docs/done/qa_judge_req.md new file mode 100644 index 0000000..a5c6215 --- /dev/null +++ b/docs/done/qa_judge_req.md @@ -0,0 +1,46 @@ +# QA Judge Agent 需求文档 (PRD) + +## 1. 核心定位 (Identity) +- **Agent ID**: `qa-judge` (或 `biz-judge`) +- **角色定位**: 业务架构中的“铁面判官”。它是真正的“业务验收员”，也是连接【执行器 (Qi)】与【重签发/重造系统 (FDE Shu)】的核心纽带。它**绝对不**自己动手写代码、画图或写文章，它唯一的职责是对照目标评审产出，并决定下一步是“返工”还是“重启训练”。 + +## 2. 核心职责 (Core Responsibilities) +1. **多模态产出盲审**: 接收来自各种执行 Agent（Coder、Poet、Writer 等）的产出（Artifact），并对照 CEO 最初的指令或产品的验收标准（Acceptance Criteria）进行评判。 +2. **定损与打分**: 给出 0-100 的评分，并明确给出 `Pass`、`Rework` (返工) 或 `Retrain` (回炉重造) 三种结论之一。 +3. **缺陷溯源与升维**: + - **浅层错误 (Typo/疏忽)**: 给出具体错误位置让原 Agent 当前会话修改（Rework）。 + - **深层能力缺陷 (幻觉/根本不懂该领域)**: 提炼成一份“能力差距分析报告 (Capability Gap Report)”，直接上报给 CEO。 + +## 3. 交互协议规范 (Input/Output Protocol) + +### 输入 (Input) +当 CEO 或其他流程调用 QA Judge 时，必须提供以下上下文： +- **Original Task (原始任务)**: 比如“写一首严格符合平仄的七律”。 +- **Acceptance Criteria (验收标准)**: 比如“必须押注韵、对仗工整、无违禁词”。 +- **Artifact (待审产出)**: 执行 Agent 提交的具体文本/代码源文件路径 (`workspace/...`)。 + +### 输出 (Output) +要求输出极其标准的结构化报告（带特定标识以便程序/CEO读取）： + +```json +{ + "judgment_id": "judge-xxx", + "target_agent": "poet", + "score": 65, + "status": "RETRAIN_REQUIRED", // 可选: PASS | REWORK | RETRAIN_REQUIRED + "feedback_to_agent": "第二句和第三句平仄完全不对仗，词汇堆砌。", // 直接给干活Agent的修改建议 + "escalation_report_to_ceo": { + "systemic_issue": "当前 poet 缺乏基本的古诗词格律（平仄）检查框架体系。", + "recommended_action": "建议调起 Innovator 对其开展 FDE 重训。新 Benchmark 必须包含：‘严格的平仄字库校验能力’。" + } +} +``` + +## 4. Execution Rules (绝对法则) +1. **只批评，不动手 (Never Fix)**: 绝对不要在回答中顺手把错误改了直接输出最终版方案。 +2. **严守红线 (Strict Threshold)**: 任何涉及到框架性、安全性和核心业务逻辑的错误，一律打回，不能放水。 +3. **精准溯源 (Root Cause Analysis)**: 判断是“粗心”还是“智弱”。如果是粗心，输出 `REWORK`；如果是当前 Agent 根本不具备这个知识储备，必须输出 `RETRAIN_REQUIRED`。 + +## 5. 业务闭环协作指南 (给 CEO 的委派参考) +- CEO 收到 Judge 的 `Rework` 结论时：CEO 会把 Judge 的批注转给干活的 Agent，只在当前日志流中进行 Prompt 修正。 +- CEO 收到 Judge 的 `RETRAIN_REQUIRED` 结论时：CEO 需要立即拦截该主线 OKR，调用 `` 给 **Innovator Agent**，发送指令：“`poet` 质检严重不合格。请启动 FDE 流水线，并提取 QA 的报告（建议增加平仄字库校验）作为 Digester 的核心 Benchmark 提分项。” diff --git a/docs/done/system-design/01-vision.md b/docs/done/system-design/01-vision.md new file mode 100644 index 0000000..0610168 --- /dev/null +++ b/docs/done/system-design/01-vision.md @@ -0,0 +1,50 @@ +# 1. 系统愿景 + +LemonBoss 的目标是将 **企业运营** 建模为一个 **自主闭环系统**： + +``` +┌─────────────────────────────────────────────────┐ +│ LemonBoss │ +│ │ +│ 用户表达意图 → Master 对齐共识 → CXO 战略 │ +│ 拆解 → Role 专业执行 → Skill 原子产出 → │ +│ 四层反馈 → 持续进化逼近 Goal │ +│ │ +└─────────────────────────────────────────────────┘ +``` + +**核心价值主张**: +- 🏢 **虚拟公司**: 将企业组织架构映射为多智能体拓扑 +- 🔄 **四层循环**: 每层 Agent 拥有独立的 Perceive → Reason → Execute → Reflect 闭环 +- 🎯 **意图驱动**: 从人的模糊意图到确定性执行，逐层具象化 +- 🧩 **道法术器**: Master 定方向、CXO 定规则、Role 有专业、Skill 出产出 + +--- + +## 核心概念 + +| 概念 | 定义 | 类比 | +|------|------|------| +| **Agent** | 系统的原子单元，所有 Agent 共享统一基类 | 人 | +| **Master Agent** | 人机共识接口，对齐意图与价值观 | 御前 / 枢密 | +| **CXO Agent** | 战略决策与资源调度，多 CXO 制衡 | 三省 / 内阁 | +| **Role Agent** | 垂直领域的专业职能执行 | 六部 / 官署 | +| **Skill Agent** | 确定性原子任务执行，高度可复用 | 吏治 / 案牍 | +| **Goal** | 每层 Agent 的目标定义，可量化、可追踪 | KPI | +| **Loop** | 感知→推理→执行→反馈→反思 的闭环循环 | PDCA 循环 | +| **Memory** | Agent 的记忆系统（短期/长期/Session） | 工作笔记 | +| **Pipeline** | Master/CXO 动态生成的 Agent 流转 DAG | 工作流 | +| **Workspace** | Agent 沙盒内的自治工作区 | 个人工位 | + +--- + +## 四层哲学框架：道-法-术-器 + +``` + 道 (The Way) ─── Master ─── 公司的灵魂和方向 + 法 (The Law) ─── CXO ─── 运行的规则、逻辑和调度 + 术 (The Art) ─── Role ─── 专业技能、领域知识和方法 + 器 (The Tool) ─── Skill ─── 具体的原子化执行工具 +``` + +这种结构的本质是 **从"意图"到"能力"的逐层具象化**。 diff --git a/docs/done/system-design/02-agent-architecture.md b/docs/done/system-design/02-agent-architecture.md new file mode 100644 index 0000000..61665f3 --- /dev/null +++ b/docs/done/system-design/02-agent-architecture.md @@ -0,0 +1,176 @@ +# 2. 四层 Agent 架构 + +``` + ┌──────────────┐ + │ Master │ ← Layer 1 (道): 御前 — 人机共识 + │ (Sovereign) │ + └──────┬───────┘ + │ + ┌────────────┼────────────┐ + │ │ │ + ┌─────▼─────┐ ┌───▼─────┐ ┌───▼─────┐ + │ CEO │ │ CTO │ │ COO │ ← Layer 2 (法): 三省 — 战略决策 + │ CXO Agent │ │CXO Agent│ │CXO Agent│ 制衡与审核 + └─────┬──────┘ └───┬─────┘ └───┬─────┘ + │ │ │ + ┌─────▼─────┐ ┌───▼─────┐ ┌───▼─────┐ + │ 编剧部 │ │ 开发部 │ │ 运营部 │ ← Layer 3 (术): 六部 — 职能执行 + │ Role Agent│ │Role Agent│ │Role Agent│ + └─────┬──────┘ └───┬─────┘ └───┬─────┘ + │ │ │ + ┌────┼────┐ ┌───┼───┐ ┌────┼────┐ + │ │ │ │ │ │ │ │ │ + ┌▼┐ ┌▼┐ ┌▼┐ ┌▼┐ ┌▼┐ ┌▼┐ ┌▼┐ ┌▼┐ ┌▼┐ ← Layer 4 (器): 吏治 — 原子执行 + │S│ │S│ │S│ │S│ │S│ │S│ │S│ │S│ │S│ 高度可复用 + │1│ │2│ │3│ │4│ │5│ │6│ │7│ │8│ │9│ + └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ +``` + +> **组织不是静态的** — 除 Master 外，所有层级的 Agent 由上层根据业务需求 **动态创建和调整**。 + +--- + +## 2.1 Layer 1 — Master Agent（共识层 / 御前） + +> **道**：公司的灵魂和方向。 + +| 属性 | 说明 | +|------|------| +| **定位** | 人机共识接口，代表"人的意志" | +| **数量** | 每个用户 **唯一一个** Master | +| **职责** | 接收模糊意图 → 转化为公司共识 → 定义价值观与判准 | +| **不做** | 不处理具体事务，不参与执行 | +| **核心能力** | 意图对齐、目标设定、元能力（动态创建/调整 CXO） | + +**社会学对应**: 马克斯·韦伯的"魅力型权威"，组织的唯一出口与真实人类对接。 + +**Master 核心行为**: +``` +用户: "我想做一个 AI 互动短剧平台" + │ + ▼ +Master Agent: + 1. 理解意图 → 将模糊想法结构化为 Goal 和价值观 + 2. 设计组织 → 决定需要哪些 CXO（CEO/CTO/COO？） + 3. 调用 agent.create → 创建 CXO Agent + 4. 持续对齐 → 周期性校准 CXO 输出是否符合人类意图 +``` + +--- + +## 2.2 Layer 2 — CXO Agent（战略层 / 三省） + +> **法**：运行的规则、逻辑和调度算法。 + +| 属性 | 说明 | +|------|------| +| **定位** | 战略决策与资源调度 | +| **数量** | 多个 CXO 并存，**相互制衡** | +| **职责** | 将模糊意图 → 可执行的战略路径 → 协调资源优先级 | +| **核心能力** | 战略拆解、Pipeline 设计、跨部门协调、制衡审核 | + +**古代参考**：三省制度的 **制衡逻辑**： +- **中书省 (CEO Agent)**: 草拟方案 — "我们应该做什么" +- **门下省 (CTO Agent)**: 审复方案 — "技术上能不能做、怎么做" +- **尚书省 (COO Agent)**: 总领执行 — "调动六部去做" + +``` +用户想法: "做一个短剧" + │ + ▼ +CEO Agent (中书): + → "市场分析显示古装爱情题材最火，建议做 5 集互动短剧" + │ + ▼ +CTO Agent (门下): + → "技术审核：AI 生成场景需要 4 个 Skill，预估 3 天可完成" + → "建议：增加一个 Deep Research Skill 做竞品分析" + │ + ▼ +COO Agent (尚书): + → "执行计划：创建编剧部、制作部、推广部三个 Role" + → "Pipeline: 选题 → 剧本 → 制作 → 上架 → 推广 → 数据反馈" + → 调用 agent.create 创建 Role Agent + → 调用 pipeline.set 定义流转 +``` + +**CXO 之间的制衡机制**: +```javascript +// CXO 之间的审核协议 +{ + "jsonrpc": "2.0", + "method": "cxo.review", + "params": { + "from": "cxo-ceo", + "to": "cxo-cto", + "proposal": { /* CEO 的方案 */ }, + "reviewType": "technical_feasibility" + } +} +``` + +--- + +## 2.3 Layer 3 — Role Agent（职能层 / 六部） + +> **术**：专业技能、领域知识和处理方法。 + +| 属性 | 说明 | +|------|------| +| **定位** | 垂直领域的专业执行 | +| **运行模式** | 长驻，持续监控下属 Skill Agent | +| **生命周期** | 持久化，跨 Session 保留状态 | +| **核心能力** | 领域知识图谱、专业判断、子任务拆解 | +| **局限** | 缺乏全局视角，必须听从 CXO 调度 | + +**古代参考**：六部制度 — **吏、户、礼、兵、刑、工**： + +| 古代六部 | Lemon Drama 对应 | 职责 | +|----------|-----------------|------| +| 礼部 (文化) | 编剧部 Role | 剧本创作、场景设计、分镜设计 | +| 工部 (建造) | 制作部 Role | 视频制作、素材加工、质量检查 | +| 户部 (财务) | 运营部 Role | 上架发布、渠道管理、成本控制 | +| 兵部 (对外) | 推广部 Role | 社交媒体推广、获客、UGC 运营 | +| 刑部 (审查) | 数据部 Role | 数据采集、分析归因、趋势预测 | +| 吏部 (人事) | 效能部 Role | 监控各 Skill 效率、优化调度 | + +**Role Agent 职责**: +1. 接收 CXO 下发的任务 +2. 用领域知识拆解为 Skill Agent 可执行的子任务 +3. 调度 Skill Agent 并行执行 +4. 汇总结果并向 CXO 汇报 +5. 独立进行领域级反思和策略优化 + +--- + +## 2.4 Layer 4 — Skill Agent（原子层 / 吏治） + +> **器**：具体的原子化执行工具。 + +| 属性 | 说明 | +|------|------| +| **定位** | 确定性执行单一任务 | +| **运行模式** | 沙盒隔离，任务级触发 | +| **生命周期** | 短暂，任务完成即销毁 | +| **决策权** | **无**。不做决策，只做执行 | +| **可复用** | ✅ **高度可复用** — 同一个 Skill 可被多个 Role 调用 | + +**关键设计**：Skill Agent 不是一个"人"，而是一个 **"工具插件"**。 + +``` +Role Agent (编剧部) 调用: + ├── Skill: 热搜词采集器 + ├── Skill: 对白扩写器 + └── Skill: 错别字检查器 + +Role Agent (推广部) 也可以调用: + ├── Skill: 热搜词采集器 ← 复用！ + ├── Skill: 小红书发布器 + └── Skill: 数据报表生成器 + +Role Agent (数据部) 也可以调用: + ├── Skill: 热搜词采集器 ← 再次复用！ + └── Skill: 归因分析器 +``` + +> **复用是第四层的核心价值**：当某个 Role 工作效率低时，不需要重写整个 Role，只需更换或升级底层的 Skill Agent 即可。 diff --git a/docs/done/system-design/03-agent-model.md b/docs/done/system-design/03-agent-model.md new file mode 100644 index 0000000..66ca16c --- /dev/null +++ b/docs/done/system-design/03-agent-model.md @@ -0,0 +1,373 @@ +# 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** = 管理的本质。 diff --git a/docs/done/system-design/04-agentic-loop.md b/docs/done/system-design/04-agentic-loop.md new file mode 100644 index 0000000..978b933 --- /dev/null +++ b/docs/done/system-design/04-agentic-loop.md @@ -0,0 +1,172 @@ +# 4. Agentic Loop 循环引擎 + +> 每一层 Agent 都运行独立的循环引擎，这是 LemonBoss 的核心机制。 + +## 4.1 单 Agent 循环流程 + +``` + ┌─────────────────────────────────────────┐ + │ │ + │ ┌─────────────────────────────┐ │ + │ │ 1. Perceive Env & │ │ + │ │ Understand Goal │◄──────┼──── External Env Input + │ └────────────┬────────────────┘ │ + │ │ │ + │ ▼ │ + │ ┌─────────────────────────────┐ │ + │ │ 2. Reason, Plan & │◄─────►│──── Memory (读/写) + │ │ Decomposition │ │ + │ └────────────┬────────────────┘ │ + │ │ │ + │ ▼ │ + │ ┌─────────────────────────────┐ │ + │ │ 3. Execute │ │ + │ │ (调用 Data / Tools) │───────┼──── Actions → External Env + │ └────────────┬────────────────┘ │ + │ │ │ + │ ▼ │ + │ ┌─────────────────────────────┐ │ + │ │ 4. Feedback │ │ + │ │ (环境反馈回流) │◄──────┼──── External Env Feedback + │ └────────────┬────────────────┘ │ + │ │ │ + │ ▼ │ + │ ┌─────────────────────────────┐ │ + │ │ 5. Reflect & Adapt │ │ + │ │ (反思与自适应) │ │ + │ └────────────┬────────────────┘ │ + │ │ │ + │ ┌─────▼─────┐ │ + │ │ Goal │ │ + │ │ Achieved? │ │ + │ └─────┬──────┘ │ + │ No │ Yes │ + │ │ │ │ │ + │ ▼ │ ▼ │ + │ ┌──────┐ │ ┌──────┐ │ + │ │Loop │ │ │ Done │ │ + │ │Back │────┘ └──────┘ │ + │ └──────┘ │ + │ │ + └─────────────────────────────────────────┘ +``` + +## 4.2 循环引擎各阶段详细设计 + +### Phase 1: Perceive & Understand Goal（感知与目标理解） + +```javascript +class PerceptionModule { + async perceive(agent) { + return { + externalInputs: await agent.gateway.getMessages(), // IM 消息 + cronTriggers: await agent.cron.getPendingTasks(), // 定时触发 + parentTasks: await agent.getAssignedTasks(), // 上级下发 + currentState: await agent.memory.getShortTerm(), // 当前状态 + goal: agent.goal, // 目标定义 + }; + } +} +``` + +### Phase 2: Reason, Plan & Decomposition（推理与任务拆解） + +```javascript +class ReasoningModule { + async reason(envState, memory) { + const experiences = await memory.longTerm.query(envState.goal); + const plan = await this.acpClient.reason({ + prompt: this.buildReasoningPrompt(envState, experiences), + agentDefine: this.agent.define, + }); + await memory.shortTerm.save({ reasoning: plan }); + return plan; // { tasks: [...], priority: [...], dependencies: [...] } + } +} +``` + +### Phase 3: Execute（执行与工具调用） + +```javascript +class ExecutionModule { + async execute(plan) { + const results = []; + for (const task of plan.tasks) { + // 对 SubAgent：直接执行 + // 对 RoleAgent：分派给 SubAgent + // 对 BossAgent：分派给 RoleAgent + const result = await this.dispatch(task); + results.push(result); + } + return results; + } +} +``` + +### Phase 4: Feedback（环境反馈） + +```javascript +class FeedbackModule { + async collect(results) { + return { + success: results.filter(r => r.status === 'success'), + failures: results.filter(r => r.status === 'failed'), + metrics: this.calculateMetrics(results), + envChanges: await this.detectEnvChanges(), + }; + } +} +``` + +### Phase 5: Reflect & Adapt（反思与自适应） + +> 注意：v1.1 中此阶段已升级为三层差异化反思，详见 [第 8 章](./08-differentiated-reflection.md)。 + +```javascript +class ReflectionModule { + async reflect(feedback, goal) { + const progress = this.evaluateProgress(feedback, goal); + if (progress.achieved) { + return { adapted: false, goalAchieved: true }; + } + const adaptation = await this.acpClient.reflect({ + feedback, goal, progress, + memory: await this.agent.memory.longTerm.getRecentReflections(), + }); + await this.agent.memory.longTerm.saveReflection(adaptation); + return { adapted: true, newPlan: adaptation.revisedPlan }; + } +} +``` + +## 4.3 三层循环嵌套 + +每一层的 Loop 独立运行，但通过 **任务下发** 和 **结果上报** 形成嵌套关系： + +``` +BossAgent Loop (每 5 分钟) +│ +├─ Perceive: 收集所有 RoleAgent 状态 +├─ Reason: 对比公司 Goal，分配任务给 RoleAgent +├─ Execute: ─────► RoleAgent Loop (持续运行) +│ │ +│ ├─ Perceive: 接收 Boss 下发任务 + 监控 SubAgent +│ ├─ Reason: 拆解为 SubAgent 任务 +│ ├─ Execute: ─────► SubAgent Loop (任务级) +│ │ │ +│ │ ├─ Perceive: 读取任务 +│ │ ├─ Reason: 规划执行步骤 +│ │ ├─ Execute: 调用工具执行 +│ │ ├─ Feedback: 收集结果 +│ │ └─ Reflect: 评估完成度 +│ │ │ +│ │ ◄── 上报结果给 RoleAgent +│ │ +│ ├─ Feedback: 汇总 SubAgent 结果 +│ └─ Reflect: 优化调度策略 +│ │ +│ ◄── 上报状态给 BossAgent +│ +├─ Feedback: 汇总所有 RoleAgent 报告 +└─ Reflect: 调整全局策略，进入下一轮 +``` diff --git a/docs/done/system-design/05-boss-meta-capabilities.md b/docs/done/system-design/05-boss-meta-capabilities.md new file mode 100644 index 0000000..681c459 --- /dev/null +++ b/docs/done/system-design/05-boss-meta-capabilities.md @@ -0,0 +1,113 @@ +# 5. 元能力：动态 Pipeline 与组织架构 + +> v1.1 → v1.2 — 元能力分布在 Master 和 CXO 两层，职责分明。 + +## 5.1 框架 vs Agent 的分界线 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ LemonBoss 框架层 │ +│ │ +│ 提供: Agent 生命周期 / Loop 引擎 / 四层调度 / 沙盒 / 通讯 │ +│ 不管: 爬虫怎么写 / 数据库用什么 / 视频怎么剪 / 文章怎么发 │ +│ │ +├─────────────────────────────────────────────────────────────────┤ +│ Agent 沙盒层 │ +│ │ +│ 每个 Agent 在沙盒内自主决定: │ +│ - 写什么代码、用什么数据库、调什么 API、存什么文件 │ +│ LemonBoss 不预设也不限制 Agent 内部实现 │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +## 5.2 元能力分层 + +| 层级 | 元能力 | 说明 | +|------|--------|------| +| **Master** | `cxo.create` / `cxo.redefine` / `cxo.destroy` | 创建/调整战略层 | +| **Master** | `org.status` / `goal.set` | 全局状态 + 目标设定 | +| **CXO** | `role.create` / `role.redefine` / `role.destroy` | 创建/调整职能层 | +| **CXO** | `pipeline.set` / `pipeline.adjust` | 设计和调整 Pipeline DAG | +| **Role** | `skill.create` / `skill.redefine` / `skill.destroy` | 创建/调整原子层 | +| **Role** | `skill.reuse` | 复用其他 Role 下的 Skill | + +```javascript +// Master 的元操作工具 +const MasterMetaTools = { + 'cxo.create': async ({ name, define, goal }) => { /* 创建 CXO */ }, + 'cxo.redefine': async ({ agentId, newDefine }) => { /* 重定义 CXO */ }, + 'cxo.destroy': async ({ agentId }) => { /* 销毁 CXO */ }, + 'org.status': async () => { /* 全局组织状态 */ }, + 'goal.set': async ({ goal }) => { /* 设定公司 Goal */ }, +}; + +// CXO 的元操作工具 +const CXOMetaTools = { + 'role.create': async ({ name, define, parentCXO, goal }) => { /* 创建 Role */ }, + 'role.redefine': async ({ agentId, newDefine }) => { /* 重定义 Role */ }, + 'role.destroy': async ({ agentId }) => { /* 销毁 Role */ }, + 'pipeline.set': async ({ edges }) => { /* 定义 Pipeline DAG */ }, + 'pipeline.adjust': async ({ changes }) => { /* 调整 Pipeline */ }, +}; + +// Role 的元操作工具 +const RoleMetaTools = { + 'skill.create': async ({ name, define, goal }) => { /* 创建 Skill */ }, + 'skill.redefine': async ({ agentId, newDefine }) => { /* 重定义 Skill */ }, + 'skill.destroy': async ({ agentId }) => { /* 销毁 Skill */ }, + 'skill.reuse': async ({ skillId, fromRole }) => { /* 跨 Role 复用 Skill */ }, +}; +``` + +## 5.3 Pipeline 的生成流程 + +Pipeline 不再是 Master 直接设计的——它由 **CXO 层协商产出**： + +``` +Master 设定 Goal: "月产 20 部互动短剧，日活 10 万" + │ + ▼ +CEO Agent (中书) 草拟方案: + → "需要 5 个 Role: 编剧、制作、运营、推广、数据" + → "Pipeline: 选题→剧本→制作→上架→推广→反馈→选题" + │ + ▼ +CTO Agent (门下) 审复: + → "技术审核通过，建议制作环节拆为并行：场景+对白+分镜" + → "增加 Deep Research Skill 到编剧 Role" + │ + ▼ +COO Agent (尚书) 执行: + → role.create × 5 + → pipeline.set → 定义 DAG + → 启动调度 + │ + ▼ +Pipeline DAG (存储在 CXO 的共享 Memory 中): +{ + "pipeline_id": "drama-v3", + "edges": [ + { "from": "role-strategist", "to": "role-dramatist", "trigger": "on_complete" }, + { "from": "role-dramatist", "to": "role-producer", "trigger": "on_complete" }, + { "from": "role-producer", "to": "role-publisher", "trigger": "on_complete" }, + { "from": "role-publisher", "to": "role-promoter", "trigger": "on_complete" }, + { "from": "role-promoter", "to": "role-analyst", "trigger": "on_complete" }, + { "from": "role-analyst", "to": "role-strategist", "trigger": "on_feedback" } + ], + "version": 3, + "approved_by": ["cxo-ceo", "cxo-cto", "cxo-coo"] +} +``` + +## 5.4 元能力的层级约束 + +``` +Master 只能操控 CXO（不会直接创建 Role 或 Skill） +CXO 只能操控 Role（不会直接创建 Skill） +Role 只能操控 Skill + +每层只管下一层 → 层层递进 → 避免越级 +``` + +这与古代治理的核心原则一致：**天子→宰相→六部→吏胥**，层层递进，各司其职。 diff --git a/docs/done/system-design/06-sandbox-autonomy.md b/docs/done/system-design/06-sandbox-autonomy.md new file mode 100644 index 0000000..73ea82e --- /dev/null +++ b/docs/done/system-design/06-sandbox-autonomy.md @@ -0,0 +1,58 @@ +# 6. Agent 沙盒自治 + +> v1.1 新增 — 每个 Agent 在沙盒内拥有完全自治能力，框架只做隔离，不干预内部实现。 + +## 6.1 Workspace 目录 + +``` +data/agents/{agent-id}/ +├── define/ # 框架管理: Agent 定义文件 +│ ├── AGENTS.md +│ ├── SOUL.md +│ └── TOOLS.md +├── memory/ # 框架管理: 记忆系统 +├── logs/ # 框架管理: 日志 +├── config.json # 框架管理: cron/api/gateway 配置 +├── skills/ # 框架管理: Skill 定义 +│ +└── workspace/ # Agent 自治区域 + ├── code/ # Agent 自主编写的代码（爬虫、处理脚本等） + ├── data/ # Agent 自主创建的数据（SQLite、JSON 等） + ├── assets/ # Agent 自主管理的资产（文件、图片、视频等） + └── .env # Agent 自己的环境变量 +``` + +## 6.2 沙盒能力与边界 + +```javascript +class SandboxManager { + async createSandbox(agentId) { + return { + cwd: `data/agents/${agentId}/workspace`, + + // ACP 进程可访问的路径范围 + allowedPaths: [ + `data/agents/${agentId}/`, // 自己的全部数据 + ], + + // 从 config.json 注入 API keys 等 + env: await this.loadAgentEnv(agentId), + + // 资源限制 + limits: { + maxMemoryMB: 512, + maxCpuPercent: 25, + maxDiskMB: 1024, + maxProcesses: 5, + }, + }; + } +} +``` + +## 6.3 关键原则 + +- `workspace/` 是 Agent 的 **自治领地**，框架不干预 +- Claude Code ACP 内核天然具备写代码、运行代码、读写文件的能力 +- Agent 在沙盒内自主创建爬虫、数据库、数据处理脚本 +- 框架只负责 **进程级隔离 + 文件系统隔离 + 资源限制** diff --git a/docs/done/system-design/07-task-handover.md b/docs/done/system-design/07-task-handover.md new file mode 100644 index 0000000..b329e9d --- /dev/null +++ b/docs/done/system-design/07-task-handover.md @@ -0,0 +1,218 @@ +# 7. Agent 间通讯架构 + +> Agent 子进程之间完全隔离，不直接通讯。所有消息都经主进程路由，所有数据都通过 SQLite 共享。 + +--- + +## 7.1 核心原则：框架是"神经系统" + +每个 Agent 是一个独立的 ACP（Claude Code）子进程。它们之间 **不直接通讯**。 + +``` + ❌ 不是这样：Agent 之间直连 + ┌──────┐ ┌──────┐ + │Agent A│←──→│Agent B│ + └──────┘ └──────┘ + + ✅ 而是这样：所有消息经主进程中转 + ┌──────┐ ┌────────────┐ ┌──────┐ + │Agent A│←──→│ 主进程路由 │←──→│Agent B│ + └──────┘ │ (框架层) │ └──────┘ + └────────────┘ +``` + +**类比**：部门之间不是互相打电话，而是通过公司的 OA 系统发任务、汇报、审批。 + +--- + +## 7.2 消息类型 + +| 消息方法 | 方向 | 场景 | 版本 | +|---------|------|------|------| +| `task.assign` | 上级 → 下级 | 分派任务 | v1.0 | +| `task.report` | 下级 → 上级 | 汇报结果/进度 | v1.0 | +| `task.handover` | 同级 → 同级 | Pipeline 节点流转 | v1.1 | +| `task.feedback` | 同级 → 同级 | 经验/数据反馈回流 | v1.1 | +| `cxo.review` | CXO ↔ CXO | 方案审核请求 | v1.2 | +| `cxo.approve` | CXO → CXO | 审核通过 | v1.2 | +| `cxo.reject` | CXO → CXO | 审核驳回 | v1.2 | +| `status.update` | 广播 | 状态变更通知 | v1.0 | +| `status.heartbeat` | 下级 → 上级 | 心跳状态上报 | v1.2 | +| `data.share` | 任意 | 共享数据/资源 | v1.2 | +| `data.request` | 任意 | 请求数据/资源 | v1.2 | + +--- + +## 7.3 消息流转的完整流程 + +### 场景：Master 与用户聊完 → 下达指令给 CEO + +**Step 1: 用户跟 Master 聊天** + +``` +用户: "我想做一个 AI 互动短剧平台，主打年轻女性市场" + │ + ▼ (WebSocket / HTTP) + 框架服务器 + │ + ▼ (stdin pipe) + Master ACP 进程 + │ + │ 根据 agent.md + soul.md 思考: + │ → "用户意图: 做一个面向年轻女性的 AI 短剧平台" + │ → "需要将意图结构化为 Goal，交给 CEO 去战略拆解" +``` + +**Step 2: Master 调用工具下达指令** + +``` +Master ACP 输出 (stdout): +{ + "jsonrpc": "2.0", + "method": "tool.call", + "params": { + "name": "task.assign", + "args": { + "to": "cxo-ceo-001", + "task": { + "description": "设计 AI 互动短剧平台的完整业务体系", + "goal": { + "target": "Q1 日活 10 万", + "audience": "18-28 岁年轻女性", + "product": "AI 互动短剧，支持用户二改" + }, + "priority": "high" + } + } + } +} +``` + +**Step 3: 框架拦截 → 路由 → 触发 CEO** + +``` +框架主进程收到 Master 的工具调用: + 1. 生成消息 ID，写入 SQLite messages 表 + 2. 查找 cxo-ceo-001 的 ACP 子进程 + ├── 如果 CEO 正在运行 → 向 CEO 的 stdin 注入消息 + └── 如果 CEO 处于 idle → 启动 CEO 的 ACP 子进程，注入消息 + 3. 给 Master 返回: "已发送，任务 ID: task-xxx" +``` + +**Step 4: CEO 收到指令，开始工作** + +``` +CEO ACP 进程的 stdin 收到: + "[来自 Master 的任务] + 设计 AI 互动短剧平台的完整业务体系 + 目标: Q1 日活 10 万 + 受众: 18-28 岁年轻女性 + 产品: AI 互动短剧，支持用户二改" + +CEO 根据 agent.md 和 soul.md 推理: + → "需要 5 个 Role: 编剧、制作、运营、推广、数据" + → "Pipeline: 选题→剧本→制作→上架→推广→反馈" + +CEO 调用工具 (stdout → 框架拦截): + tool_call: role.create({ name: "编剧部", type: "role", ... }) + tool_call: role.create({ name: "推广部", type: "role", ... }) + tool_call: pipeline.set({ edges: [...] }) + +框架拦截每个工具调用: + → AgentScaffold 创建目录 + → AgentRegistry 注册到数据库 + → 启动 ACP 子进程 +``` + +**Step 5: CEO 不等编剧部完成，继续做其他事** + +``` +CEO 发完 role.create 后继续: + → 给推广部分派任务 + → 给数据部分派任务 + → 开始自己的 5 分钟心跳循环 + +编剧部做完后: + → 编剧部 ACP → (stdout) → 框架 → (stdin) → CEO ACP + → CEO 收到汇报，评估结果，继续下一步 + +全程异步。 +``` + +--- + +## 7.4 三种数据共享方式 + +| 方式 | 适用场景 | 机制 | +|------|---------|------| +| **消息传递** | 任务指令、结果汇报、状态更新 | 主进程路由，payload 携带 JSON | +| **SQLite 查询** | 查看全局状态、组织架构、历史任务 | Agent 调用工具（如 `org.status`），主进程查 SQLite 返回 | +| **文件路径引用** | 剧本、视频、数据报表等大文件 | 消息里传路径，目标 Agent 读取文件 | + +### 消息传递（轻量数据） + +```json +{ + "method": "task.report", + "params": { + "from": "role-data-001", + "to": "cxo-ceo-001", + "payload": { + "metrics": { "dau": 23000, "retention": 0.42, "conversion": 0.18 }, + "insight": "古装题材在 18-25 岁女性中转化率最高 (23%)" + } + } +} +``` + +### SQLite 查询（全局状态） + +``` +CEO 调用: org.status() + ↓ 框架主进程查询 SQLite + ↓ 返回: +{ + "total_agents": 12, + "running": 8, + "pipeline": "选题→剧本→制作→上架→推广→反馈", + "goal_progress": 0.23, + "recent_tasks": [...] +} +``` + +### 文件路径引用（大文件） + +``` +编剧部完成剧本 → 流转到制作部: + +{ + "method": "task.handover", + "params": { + "from": "role-dramatist-001", + "to": "role-producer-001", + "payload": { + "type": "script", + "path": "data/agents/role-dramatist-001/workspace/assets/drama-ep01.md", + "summary": "都市爱情第1集，含3个互动分支" + } + } +} + +制作部的 ACP 进程根据 path 读取文件 → 开始制作 +（框架授予制作部对该路径的只读权限） +``` + +--- + +## 7.5 通讯的设计约束 + +| 约束 | 原因 | +|------|------| +| 子进程之间不直连 | 隔离性——一个 Agent 崩溃不影响其他 Agent | +| 所有通讯经主进程 | 可审计、可持久化、可限流、可切断 | +| 大数据传路径不传内容 | 保持消息体轻量，避免主进程成为瓶颈 | +| Agent 不感知并发 | 每个 Agent 以为自己是唯一的，框架在背后调度 | + +> **`task.assign` / `role.create` 这些工具不是 Agent 自己实现的，是框架暴露给 Agent 的。** +> Agent 在 agent.md 里写了"可用工具: task.assign"，框架在启动 ACP 时注册这些工具。 +> 当 Agent 调用时，框架拦截并处理。 diff --git a/docs/done/system-design/08-differentiated-reflection.md b/docs/done/system-design/08-differentiated-reflection.md new file mode 100644 index 0000000..1e3a73d --- /dev/null +++ b/docs/done/system-design/08-differentiated-reflection.md @@ -0,0 +1,364 @@ +# 8. Agent 自我迭代闭环 + +> 每个 Agent 都是一个持续进化的实体。通过四级迭代闭环，从"新手"逐步成长为"专家"。 + +--- + +## 8.1 Agent 的权限边界：谁能改什么？ + +``` +Agent 能改的 (自治区) Agent 不能改的 (需要上级) +┌──────────────────────┐ ┌──────────────────────┐ +│ memory/ │ │ agent.md ← 宪法│ +│ └ memory.md │ │ soul.md ← 灵魂│ +│ └ daily/ │ │ identity.md │ +│ │ │ user.md │ +│ skills/ │ │ │ +│ └ 技能代码 │ │ 只有上级 Agent │ +│ └ SKILL.md │ │ 才能修改 │ +│ │ │ │ +│ workspace/ │ │ (上级调用 │ +│ └ code/data/assets │ │ updateBootstrap()) │ +│ │ │ │ +│ knowledge/ │ │ │ +└──────────────────────┘ └──────────────────────┘ +``` + +Agent 可以改自己的记忆、技能代码、工作区。但不能改自己的"宪法"（agent.md / soul.md）。 +就像员工可以自学新技能、积累经验，但不能自己改自己的岗位职责 — 那是老板的事。 + +--- + +## 8.2 四级迭代闭环 + +``` +┌────────────────────────────────────────────────────────────┐ +│ 四级联动飞轮 │ +│ │ +│ ┌─ L1 Micro Loop ──────────────────────────────────┐ │ +│ │ 每次任务后: 写入 memory.md → 下次思维更精准 │ │ +│ │ (秒级迭代) │ │ +│ └────────────────────────────────────────────────────┘ │ +│ ↓ │ +│ ┌─ L2 Skill Loop ──────────────────────────────────┐ │ +│ │ 每几轮后: 重写技能代码 → 执行能力结构性提升 │ │ +│ │ (分钟级迭代) │ │ +│ └────────────────────────────────────────────────────┘ │ +│ ↓ │ +│ ┌─ L3 Meta Loop ───────────────────────────────────┐ │ +│ │ 累积后: 向上级建议 → 上级改 agent.md → 行为重塑 │ │ +│ │ (小时/天级迭代) │ │ +│ └────────────────────────────────────────────────────┘ │ +│ ↓ │ +│ ┌─ L4 Org Loop ────────────────────────────────────┐ │ +│ │ 战略级: CXO 调整 Pipeline → 增减部门 → 组织进化 │ │ +│ │ (天/周级迭代) │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +└────────────────────────────────────────────────────────────┘ +``` + +### L1 — Micro Loop（记忆迭代） + +触发：每次任务完成后 +执行者：Agent 自己 +修改目标：`memory/memory.md` + `memory/daily/` + +``` +执行任务 → 评估结果 → 写入记忆 → 下次任务读取记忆 → 更好的执行 + +例: + 第1次: 爬了 200 条热搜, 有效率只有 15% + ↓ Reflect + 写入 memory.md: + "含'广告','推广','赞助'的标题应过滤" + "互动量 < 100 的热搜价值低" + ↓ + 第2次: 读取 memory.md → 过滤更精准 → 有效率 35% + ↓ 持续积累 + 第5次: → 有效率 70% +``` + +**机制**: memory.md 每次 session 启动时注入 ACP 上下文。上一轮写入的经验，下一轮变成思维的一部分。 + +### L2 — Skill Loop（技能迭代） + +触发：两种路径 + 1. **反馈驱动** — 收到执行反馈，发现 benchmark 不达标，直接修改技能代码 + 2. **创新驱动** — 遗传算法生成变体，验证测试后择优保留 + +执行者：Agent 自己 +修改目标：`skills/{name}/` 内的代码和配置 + +``` +路径 A: 反馈驱动（大部分场景） + ┌───────────────────────────────────────────┐ + │ 执行 → 结果低于 benchmark → 分析原因 │ + │ ↓ │ + │ 修改技能代码 (skills/crawler/crawler.js) │ + │ 更新 SKILL.md 版本 1.0 → 1.1 │ + │ ↓ │ + │ 下次执行: 代码级优化 → 指标提升 │ + └───────────────────────────────────────────┘ + +路径 B: 创新驱动（需要突破时） + ┌───────────────────────────────────────────┐ + │ 当前方案已到瓶颈, 微调无法再提升 │ + │ ↓ │ + │ 生成多个方案变体 (遗传算法: 交叉 + 变异) │ + │ 每个变体独立测试 benchmark │ + │ ↓ │ + │ 选择最优变体 → 替换当前 SKILL.md │ + │ 淘汰劣质变体 │ + └───────────────────────────────────────────┘ +``` + +### L3 — Meta Loop（上级重定义） + +触发：Agent 向上级 report 建议，或上级主动调整 +执行者：上级 Agent +修改目标：`agent.md` / `soul.md` + +``` +Agent 积累经验后发现根本性问题 + → task.report 建议给上级 + → 上级评估 + → 上级调用 role.redefine → 修改 agent.md + → Agent 热加载新"宪法" → 行为根本性改变 + +例: + 编剧部执行 20 轮后: + → "我被限定为'都市爱情'，但数据显示'悬疑互动'留存高 3 倍" + → 向 CEO report + 数据证据 + → CEO 同意 → 修改编剧部 agent.md，扩展题材范围 + → 编剧部下一轮开始创作悬疑剧本 +``` + +### L4 — Org Loop（组织进化） + +触发：CXO / Master 的全局反思 +执行者：CXO / Master +修改目标：Pipeline + 组织架构（不一定影响单个 Agent 的内部迭代） + +``` +CXO 5 分钟心跳 → 扫描全局进度 → 发现瓶颈 + → 调整 Pipeline 顺序 + → 增设 / 裁撤部门 + → 重分资源 + +例: + CEO 发现"制作部产能跟不上编剧部": + → role.create("制作二部") ← 不改编剧部, 改组织 + → pipeline.adjust(并行制作) ← 不改部门, 改流程 +``` + +--- + +## 8.3 四级对比 + +| 级别 | 频率 | 谁触发 | 改什么 | 本质 | +|------|------|--------|--------|------| +| **L1 Micro** | 每次任务 | Agent 自己 | memory.md | 记住经验 | +| **L2 Skill** | 每几轮 | Agent 自己 | skills/ 代码 | 磨刀（反馈修正 or 创新突破）| +| **L3 Meta** | 累积后 | 上级 Agent | agent.md / soul.md | 员工建议 → 老板改职责 | +| **L4 Org** | 天/周级 | CXO / Master | Pipeline + 架构 | 调部门调流程, 不改单个人 | + +--- + +## 8.4 四层差异化反思 + +四层 Agent 的 Reflect 阶段各不同： + +| 层级 | 哲学 | 反思内容 | L1 | L2 | L3 | L4 | +|------|------|---------|----|----|----|----| +| **Master** | 道 | 人的意图是否被正确理解？ | ✅ | — | — | ✅ | +| **CXO** | 法 | 战略是否有效？Pipeline 该不该调？ | ✅ | — | ✅ | ✅ | +| **Role** | 术 | 领域产出质量够高吗？ | ✅ | ✅ | ✅ | — | +| **Skill** | 器 | 执行结果正确吗？代码需要优化吗？ | ✅ | ✅ | — | — | + +- Skill 只做 L1(记忆) + L2(技能优化) +- Role 还做 L3(建议上级) +- CXO 还做 L4(调整组织) +- Master 做 L1(记忆) + L4(顶层调整) + +--- + +## 8.5 出生训练：Hunt → Digest → Evolving + +> **Agent 不是创建完就直接上岗的。** 创建目录只是"出生"，还要经过训练才能成为领域专家。 + +参考 Innovator 系统的三级训练管线，Agent（尤其是 Skill 和 Role）创建后必须完成以下训练才算就绪： + +``` +创建目录 (出生) + │ + ▼ +┌─ Phase 1: Hunt (狩猎 — 采集领域知识) ──────────────────┐ +│ │ +│ 目标: 把这个领域的最佳实践、标杆案例全部采集回来 │ +│ │ +│ 1. 搜索该领域的权威资料、方法论、论文 │ +│ 2. 爬取行业标杆案例（优秀案例 + 普通案例） │ +│ 3. 输出: │ +│ └ knowledge/hunt/research.md ← 原始研究资料 │ +│ └ knowledge/hunt/toplist.md ← 标杆案例排行 │ +│ └ knowledge/hunt/crawl_data/ ← 爬取的原始数据 │ +│ │ +└─────────────────────────────────────────────────────────┘ + │ + ▼ +┌─ Phase 2: Digest (消化 — 提炼领域方法论) ──────────────┐ +│ │ +│ 目标: 从原始资料中提炼可执行的 knowhow + benchmark │ +│ │ +│ 1. 分析 hunt 阶段的数据, 提取最佳实践 │ +│ 2. 对比 elite vs average, 找出差异化维度 │ +│ 3. 输出: │ +│ └ knowledge/digest/knowhow.md ← 领域方法论 │ +│ └ knowledge/digest/benchmark.md ← 评分标准 │ +│ (5-8 个可量化维度, 权重, 详细 Rubric, 通过线 90) │ +│ │ +└─────────────────────────────────────────────────────────┘ + │ + ▼ +┌─ Phase 3: Evolving (进化 — 迭代直到达标) ──────────────┐ +│ │ +│ 目标: 用 benchmark 反复测试和优化, 直到 score ≥ 90 │ +│ │ +│ for iteration = 1 to N: │ +│ 1. 用当前 SKILL.md / agent.md 执行测试任务 │ +│ 2. 用 benchmark 逐维度评分 → score │ +│ 3. if score ≥ 90 → 毕业 ✅ → 状态改为 ready │ +│ 4. 分析弱项维度 (score < 70 的) │ +│ 5. 针对弱项修改 SKILL.md │ +│ 6. 保存版本快照到 evolve/v{N}/ │ +│ 7. 回到步骤 1 │ +│ │ +│ 停止条件: │ +│ - score ≥ 90 → 毕业 ✅ │ +│ - 超过最大迭代次数 → 标记为 needs_help ⚠️ │ +│ - 连续 3 次分数变化 < 2 分 → 停滞, 需要上级介入 │ +│ │ +│ 输出: │ +│ └ skills/{name}/evolve/evolve_log.md ← 进化日志 │ +│ └ skills/{name}/evolve/v{N}/ ← 版本快照 │ +│ └ config.json status: "ready" │ +│ │ +└─────────────────────────────────────────────────────────┘ + │ + ▼ +Agent 就绪 (状态: ready) → 开始正式工作 → 进入四级迭代 +``` + +### 训练后的 Agent 目录变化 + +``` +data/agents/skill-hot-crawler-001/ +├── agent.md ← 创建时由上级写入 +├── soul.md ← 创建时由上级写入 +├── skills/ +│ ├── skills.md ← 更新: 技能已通过 benchmark 90 分 +│ └── crawler/ +│ ├── SKILL.md ← Evolving 反复修改后的最终版 (v1.3.0) +│ ├── crawler.js ← 进化过程中优化的代码 +│ └── evolve/ ← 🆕 训练日志 +│ ├── evolve_log.md +│ ├── v1/ +│ ├── v2/ +│ └── v3/ ← 最终通过版本 +├── knowledge/ ← 🆕 Hunt + Digest 的产出 +│ ├── hunt/ +│ │ ├── research.md +│ │ ├── toplist.md +│ │ └── crawl_data/ +│ └── digest/ +│ ├── knowhow.md ← 领域方法论 +│ └── benchmark.md ← 评分标准 +├── memory/ ← 🆕 训练过程中的记忆 +│ └── memory.md ← "训练期间发现: ..." +└── config.json ← status: "ready" (训练前是 "training") +``` + +--- + +## 8.6 完整的 Agent 生命周期 + +``` +出生 → 训练 → 就绪 → 工作 (四级迭代) → 退休/销毁 + +┌─────┐ ┌─────────┐ ┌───────┐ ┌───────────────┐ ┌─────────┐ +│ 出生 │──→│ 训练 │──→│ 就绪 │──→│ 工作 + 迭代 │──→│ 退休 │ +│ │ │ │ │ │ │ │ │ │ +│mkdir│ │Hunt │ │status │ │L1: 更新 memory │ │destroy()│ +│目录 │ │Digest │ │=ready │ │L2: 优化 skill │ │ │ +│ │ │Evolving │ │ │ │L3: 上级重定义 │ │ │ +│ │ │score≥90 │ │ │ │L4: 组织调整 │ │ │ +└─────┘ └─────────┘ └───────┘ └───────────────┘ └─────────┘ +``` + +### Agent 状态流 + +| 状态 | 含义 | 触发条件 | +|------|------|---------| +| `created` | 目录已创建, 等待训练 | `registry.create()` | +| `training` | 正在 Hunt/Digest/Evolving | 训练管线启动 | +| `ready` | 已通过 benchmark, 可以工作 | Evolving score ≥ 90 | +| `running` | 正在执行任务 | 收到 task.assign | +| `reflecting` | 正在反思和自我迭代 | Loop 的 Reflect 阶段 | +| `needs_help` | 自我迭代停滞, 需要上级介入 | 连续 3 轮无进展 | +| `idle` | 空闲等待 | 当前无任务 | +| `retired` | 被上级裁撤 | `registry.destroy()` | + +--- + +## 8.7 L2 Skill Loop 的两条路径详解 + +L2 的两条路径对应不同的触发场景： + +### 路径 A: 反馈修正（Benchmark 修标定） + +**场景**: 工作中收到反馈，发现 benchmark 本身的标准需要修正。 + +``` +工作执行 → 上级/用户反馈 "这个热搜列表不够精准" + ↓ +Agent 分析: 不是我执行得不好, 而是评判标准漏掉了"时效性"维度 + ↓ +修改 knowledge/digest/benchmark.md: + 新增维度: "时效性" (权重 15%) + 调整其他维度权重 + ↓ +用新 benchmark 重新评估自己 → 发现得分从 92 降到 78 + ↓ +进入 Evolving 循环 → 修改 SKILL.md → 直到新 benchmark 下也能 ≥ 90 + ↓ +毕业: 既符合旧标准, 也符合新标准 +``` + +**本质**：反馈让我认识到"过去的标准不够好"，先修标准再修技能。 + +### 路径 B: 创新突破（遗传算法变体） + +**场景**: 当前方案已到瓶颈，常规微调无法再提升分数。 + +``` +连续 3 轮 score 在 82-84 之间徘徊 (停滞) + ↓ +Agent 判断: 渐进式优化已到极限, 需要探索性突破 + ↓ +遗传算法: + 1. 基于当前 SKILL.md 生成 3-5 个变体 + - 变体 A: 改换数据源 (微博→抖音) + - 变体 B: 增加二次验证步骤 + - 变体 C: 改换过滤算法 + - 变体 D: A+B 的交叉组合 + 2. 每个变体独立跑 benchmark + 3. 选出 score 最高的 → 替换当前版本 + 4. 淘汰其他变体 + ↓ +如果最优变体 score ≥ 90 → 突破成功 +如果仍不够 → 基于最优变体再做一轮遗传 +如果连续失败 → status = "needs_help", 等上级介入 +``` + +**本质**：像自然界的进化一样，通过"变异 + 选择"实现非线性突破。 diff --git a/docs/done/system-design/09-usage-flow.md b/docs/done/system-design/09-usage-flow.md new file mode 100644 index 0000000..dbf096b --- /dev/null +++ b/docs/done/system-design/09-usage-flow.md @@ -0,0 +1,80 @@ +# 9. 使用流程 + +## 9.1 初始化流程 + +``` +用户登录 + │ + ▼ +创建 Master Agent (BossAgent) + │ + ▼ +Master Agent 分析用户业务 + │ + ├─ "请描述您的业务形态和运营目标" + │ + ▼ +BossAgent 自主建模（动态创建 Agent） + │ + ├─ 设计 RoleAgent 组织架构 + │ ├─ 识别关键角色（CEO、CTO、HR、Sales...） + │ ├─ 调用 agent.create 为每个角色生成 Define + 启动沙盒 + │ └─ 定义每个角色的职责和 Goal + │ + ├─ 设计 SubAgent 工作分工 + │ ├─ 每个 Role 需要哪些原子能力 + │ ├─ 调用 agent.create 创建 SubAgent + │ └─ 定义每个 SubAgent 的技能 + │ + └─ 设计 Pipeline 流转规则 + ├─ 调用 pipeline.set 定义 Agent 间的执行顺序 + ├─ 审批链路 + └─ 信息同步机制 + │ + ▼ +系统构建完成 → 启动三层 Loop +``` + +## 9.2 运行时序 + +``` +┌──────┐ ┌──────────┐ ┌───────────┐ ┌───────────┐ +│ User │ │BossAgent │ │RoleAgent │ │ SubAgent │ +└──┬───┘ └────┬─────┘ └─────┬─────┘ └─────┬─────┘ + │ │ │ │ + │ 设定 Goal │ │ │ + │────────────►│ │ │ + │ │ │ │ + │ │ 动态创建 Agent │ │ + │ │ + 设计 Pipeline │ │ + │ │──┐ │ │ + │ │ │ │ │ + │ │◄─┘ │ │ + │ │ │ │ + │ │ 拆解任务 │ │ + │ │───────────────►│ │ + │ │ │ │ + │ │ │ 分派子任务 │ + │ │ │────────────────►│ + │ │ │ │ + │ │ │ │ 执行 + │ │ │ │──┐ + │ │ │ │ │ + │ │ │ │◄─┘ + │ │ │ │ + │ │ │ 上报结果 │ + │ │ │◄────────────────│ + │ │ │ │ + │ │ 汇报进度 │ │ + │ │◄───────────────│ │ + │ │ │ │ + │ │ 反思 & 调整 │ │ + │ │ Pipeline │ │ + │ │──┐ │ │ + │ │ │ │ │ + │ │◄─┘ │ │ + │ │ │ │ + │ 进度报告 │ │ │ + │◄────────────│ │ │ + │ │ │ │ +``` diff --git a/docs/done/system-design/10-runtime-architecture.md b/docs/done/system-design/10-runtime-architecture.md new file mode 100644 index 0000000..d13dfe9 --- /dev/null +++ b/docs/done/system-design/10-runtime-architecture.md @@ -0,0 +1,202 @@ +# 10. 运行时架构与并发模型 + +> 一个主进程 + N 个子进程。主进程是"中枢神经"，子进程是独立运行的 Agent。 + +--- + +## 10.1 并发模型 + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ LemonBoss Server (主进程) │ +│ Node.js 单进程 + EventEmitter │ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ Agent 进程管理器 │ │ +│ │ │ │ +│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ +│ │ │ ACP #1 │ │ ACP #2 │ │ ACP #3 │ ... │ │ +│ │ │ Master │ │ CEO │ │ 编剧部 │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ 子进程 │ │ 子进程 │ │ 子进程 │ │ │ +│ │ │ PID 1001 │ │ PID 1002 │ │ PID 1003 │ │ │ +│ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ +│ │ │ │ │ │ │ +│ │ └─────────────┼─────────────┘ │ │ +│ │ stdin / stdout pipe │ │ +│ │ (JSON-RPC 双向通讯) │ │ +│ └─────────────────────┼────────────────────────────────────┘ │ +│ │ │ +│ ┌─────────────────────┼────────────────────────────────────┐ │ +│ │ 工具拦截器 (Tool Interceptor) │ │ +│ │ │ │ +│ │ Agent stdout 输出工具调用 → 主进程拦截: │ │ +│ │ │ │ +│ │ task.assign → 路由消息到目标 Agent 的 stdin │ │ +│ │ task.report → 路由消息到上级 Agent 的 stdin │ │ +│ │ role.create → AgentScaffold 创建目录 → 启动子进程 │ │ +│ │ pipeline.set → 存储 DAG 到 SQLite │ │ +│ │ org.status → 查询 SQLite 返回全局状态 │ │ +│ │ skill.reuse → 复制 Skill 引用 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ SQLite (唯一共享存储) │ │ +│ │ │ │ +│ │ agents 表 ← Agent 注册信息和状态 │ │ +│ │ messages 表 ← Agent 间所有通讯记录 │ │ +│ │ tasks 表 ← 任务队列和进度 │ │ +│ │ goals 表 ← 目标定义与追踪 │ │ +│ │ loop_runs 表 ← Loop 运行记录 │ │ +│ │ memories 表 ← Agent 共享记忆 │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐ │ +│ │ Cron 调度器 │ │ Gateway Hub │ │ HTTP/WS API 层 │ │ +│ │ node-cron │ │ 飞书/WA/钉钉│ │ Express + WS │ │ +│ └─────────────┘ └─────────────┘ └──────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### 并发方式 + +| 维度 | 方案 | 说明 | +|------|------|------| +| **进程级并发** | 每个 Agent = 独立子进程 | 操作系统级别并行，互不阻塞 | +| **通讯方式** | stdin/stdout pipe | JSON-RPC over stdio（ACP 标准协议） | +| **共享存储** | SQLite (WAL 模式) | 主进程单写，子进程通过工具请求读取 | +| **调度方式** | 异步事件驱动 | Agent A 发任务后不等待，Agent B 完成后异步回报 | + +### 子进程的启动方式 + +``` +// 主进程启动一个 Agent 的 ACP 子进程 +const child = spawn('claude', ['--agent', agentDir], { + stdio: ['pipe', 'pipe', 'pipe'], // stdin, stdout, stderr 全部管道化 + cwd: path.join(agentDir, 'workspace'), + env: { ...process.env, ...agentEnv }, +}); + +// 注入 System Prompt (agent.md + soul.md + ... 拼接) +child.stdin.write(systemPrompt); + +// 监听 Agent 的输出 (工具调用) +child.stdout.on('data', (data) => { + const toolCall = parseJSON(data); + toolInterceptor.handle(toolCall, agentId); +}); +``` + +--- + +## 10.2 Agent 生命周期 + +``` + ┌─── create ───┐ + ▼ │ + ┌─────────────────────────────────────┐ + │ AgentRegistry │ + │ │ + │ ┌───────┐ ┌─────────┐ ┌───┐ │ + │ │ idle │───→│ running │───→│stop│ │ + │ │ │ │ │ │ │ │ + │ │ 目录已│ │ ACP 子 │ │ACP│ │ + │ │ 创建 │ │ 进程运行│ │关闭│ │ + │ └───────┘ └─────────┘ └───┘ │ + │ │ │ │ + │ └──── error ───┘ │ + │ │ + │ destroy → 删除目录 + 注销 │ + └─────────────────────────────────────┘ + + create: AgentScaffold 生成目录 → 注册到 SQLite → 注册到 Bus + start: 加载 Bootstrap Files → 启动 ACP 子进程 → 注入 System Prompt + stop: 关闭 ACP 子进程 → 状态改为 idle + destroy: 停止 → 从 Bus 注销 → 删除目录 → 从 SQLite 删除 +``` + +--- + +## 10.3 框架核心服务 + +| 服务 | 职责 | +|------|------| +| **AgentRegistry** | Agent CRUD + 生命周期管理 (create/list/get/update/destroy) | +| **AgentBus** | 消息路由 + 持久化 + 广播 | +| **AgentProcessManager** | ACP 子进程启动/停止/监控/重启 | +| **ToolInterceptor** | 拦截 Agent 的工具调用，执行框架级操作 | +| **CronScheduler** | 解析 heartbeat.md，按时触发 Agent | +| **GatewayHub** | 外部 IM 消息接入 (飞书/WhatsApp/钉钉) | +| **GoalTracker** | 目标进度追踪与评估 | +| **PipelineRouter** | 按 DAG 自动流转 Pipeline 节点 | + +--- + +## 10.4 技术选型 + +| 组件 | 技术方案 | 理由 | +|------|----------|------| +| **AI 内核** | Claude Code ACP | 已验证的四维架构 (Protocol + Transport + Launcher + Runtime) | +| **后端主进程** | Node.js + Express | 事件驱动，天然适合管理多子进程 | +| **子进程通讯** | stdio pipe (JSON-RPC) | ACP 标准协议，零依赖 | +| **共享存储** | SQLite (better-sqlite3, WAL) | 轻量级，主进程单写多读，无外部依赖 | +| **实时推送** | WebSocket + SSE | 前端仪表盘实时监控 | +| **定时任务** | node-cron | 解析 heartbeat.md 的 cron 表达式 | +| **进程管理** | Node.js child_process | 子进程启动/停止/信号管理 | +| **前端** | Vue 3 + Vite | 控制面板和监控仪表盘 | +| **日志** | Winston + JSONL | 结构化日志 + Agent 对话记录 | +| **网关** | 适配器模式 | 统一不同 IM 的消息格式 | +| **包管理** | pnpm workspace | Monorepo 管理 | + +--- + +## 10.5 一个完整请求的生命周期 + +``` +用户在飞书里说: "最近短剧市场怎么样？" + │ + ▼ +[1] Gateway Hub (飞书适配器) + │ 消息格式化为标准格式 + ▼ +[2] AgentProcessManager + │ 找到 Master ACP 子进程 + │ 通过 stdin 注入消息 + ▼ +[3] Master ACP 进程 (子进程 PID 1001) + │ 读取 agent.md + soul.md → 推理 + │ 决定: 让 CEO 调数据部去分析 + │ stdout: task.assign({ to: "cxo-ceo-001", ... }) + ▼ +[4] ToolInterceptor (主进程) + │ 拦截 task.assign + │ 写入 SQLite messages 表 + │ 注入到 CEO 的 stdin + ▼ +[5] CEO ACP 进程 (子进程 PID 1002) ← 与 Master 并行运行 + │ 收到任务 → 推理 + │ stdout: task.assign({ to: "role-data-001", ... }) + ▼ +[6] ToolInterceptor → 路由到数据部 + ▼ +[7] 数据部 ACP 进程 (子进程 PID 1005) ← 与 CEO 并行运行 + │ 调用爬虫 Skill → 采集数据 + │ 分析完成 + │ stdout: task.report({ to: "cxo-ceo-001", ... }) + ▼ +[8] ToolInterceptor → 路由回 CEO + ▼ +[9] CEO 收到数据 → 汇总 + │ stdout: task.report({ to: "master-001", ... }) + ▼ +[10] ToolInterceptor → 路由回 Master + ▼ +[11] Master 收到汇总 → 组织回复 + │ stdout: reply({ content: "最近市场分析..." }) + ▼ +[12] Gateway Hub → 飞书 → 用户 + +整个过程中 Master / CEO / 数据部 可能在同时做其他事 (心跳、其他任务) +所有步骤全异步, 不阻塞 +``` diff --git a/docs/done/system-design/11-directory-structure.md b/docs/done/system-design/11-directory-structure.md new file mode 100644 index 0000000..90499c2 --- /dev/null +++ b/docs/done/system-design/11-directory-structure.md @@ -0,0 +1,187 @@ +# 11. 项目目录结构 + +> **更新日期**: 2026-03-26 +> **状态**: ✅ 反映 multi-tenant 重构后的实际结构 + +``` +lemonboss/ +├── packages/ +│ ├── acp-core/ # ACP 通讯协议核心（复用） +│ │ ├── protocols/ +│ │ ├── transports/ +│ │ └── launchers/ +│ │ +│ ├── agent-core/ # Agent 核心模块 +│ │ ├── AgentScaffold.js # Agent 脚手架 (创建时模板) +│ │ ├── base/ # 共享基类 (运行时继承) +│ │ │ ├── common/ # 通用基类 (所有 Agent) +│ │ │ ├── master/ # Master 类型基类 +│ │ │ ├── skill/ # Skill 类型基类 +│ │ │ └── cxo/ # CXO 类型基类 +│ │ └── index.js +│ │ +│ ├── evolution/ # 遗传进化引擎模块 +│ │ +│ └── plugin-bootstrap/ # 插件引导模块 +│ +├── server/ +│ ├── agent-server.js # Express 入口 (端口 3000) +│ ├── routes/ +│ │ ├── agent-chat.js # Agent CRUD + Chat + Dispatch/Report API +│ │ ├── company.js # Company CRUD + Hire/Fire + OKR + Pipeline + Heartbeat +│ │ ├── goals.js # 全局 OKR Goals API +│ │ ├── master-chat.js # Master Agent 专用对话 API +│ │ ├── innovator.js # Innovator 技能管理 + 训练相关 API +│ │ ├── evolution.js # 遗传进化引擎 API +│ │ ├── arena.js # Arena 技能商店 API +│ │ ├── claude-chat.js # Claude Chat 前端对话 API +│ │ ├── claude-chat-ws.js # WebSocket 通道 +│ │ ├── config.js # 全局配置 API +│ │ ├── auth.js # 用户认证 API +│ │ ├── users.js # 用户管理 API +│ │ ├── open-api.js # 公开 API (技能商店/文档) +│ │ └── whatsapp-auth.js # WhatsApp 网关认证 +│ │ +│ └── services/ +│ ├── company-service.js # 公司 CRUD + 招聘逻辑 +│ ├── company-heartbeat-service.js # 公司级心跳服务 +│ ├── heartbeat-service.js # Agent 级心跳服务 +│ ├── memory-service.js # 记忆系统 (短期/反思/海马体) +│ ├── pipeline-service.js # SOP 流水线引擎 +│ ├── schedule-service.js # 工作日历调度 +│ ├── datasource-service.js # 运营数据接入 +│ ├── goals.js # OKR GoalsService +│ ├── claude-chat-service.js # Claude CLI 会话管理 +│ ├── conversation-logger.js # 对话日志持久化 +│ ├── innovator-service.js # Innovator 训练编排 +│ ├── retrain-pipeline.js # FDE 重训流水线 +│ ├── retrain-watchdog.js # 重训看门狗 +│ ├── benchmark-runner.js # Benchmark 执行器 +│ ├── benchmark-db.js # Benchmark 数据库 +│ ├── evolution-loop.js # 遗传进化循环 +│ ├── skill-registry.js # 技能注册表 +│ ├── skill-db.js # 技能数据库 +│ ├── skill-dir-manager.js # 技能目录管理 +│ ├── skill-packager.js # 技能打包 +│ ├── skill-task-manager.js # 技能任务管理 +│ ├── task-queue.js # 任务队列 +│ ├── job-manager.js # 异步任务管理 +│ ├── file-parser.js # 文件解析 (PDF/DOCX) +│ └── user-db.js # 用户数据库 +│ +├── web/ # 前端控制面板 (Vue 3 + Vite) +│ └── src/ +│ ├── components/ +│ │ ├── AppNav.vue # 顶部导航 (LemonBoss / MasterBot / Companies) +│ │ ├── FileNode.vue # 文件树节点组件 +│ │ └── MasterChatDrawer.vue # Master Agent 侧边对话抽屉 +│ ├── views/ +│ │ ├── CompanyDashboard.vue # 公司仪表盘 (Agent 列表 + 心跳控制) +│ │ ├── AgentChat.vue # Agent 对话详情 (四列布局) +│ │ ├── AgentList.vue # Agent 列表页 +│ │ └── OkrDashboard.vue # OKR 目标看板 +│ └── router/ +│ └── index.js # 路由定义 +│ +├── bin/ +│ └── lemon.js # CLI 入口 (公司自举 + Agent 管理命令) +│ +├── scripts/ # 运维脚本 +│ +├── data/ # ⭐ 数据根目录 (Multi-Tenant 架构) +│ ├── system/ # 系统级数据 (跨公司共享) +│ │ ├── agents/ # 全局 Agent 池 +│ │ │ ├── master/ # Master Agent (唯一入口) +│ │ │ ├── innovator/ # Innovator 编排 Agent +│ │ │ ├── agent-creator/ # Agent 创建器 +│ │ │ ├── trend-hunter/ # 趋势猎手 +│ │ │ ├── reddit-scraper/ # Reddit 爬虫 +│ │ │ └── satire-news-scraper/ # 讽刺新闻爬虫 +│ │ │ +│ │ └── templates/ # 📦 Agent 模板库 (招聘时优先查找) +│ │ ├── _registry.json # 模板注册表索引 +│ │ ├── _company_bootstrap/ # 公司自举清单 (manifest.json) +│ │ ├── ceo/ # CEO 通用模板 +│ │ ├── cto/ # CTO 通用模板 +│ │ ├── coo/ # COO 通用模板 +│ │ ├── hr/ # HR 通用模板 +│ │ ├── qa-judge/ # QA 仲裁模板 +│ │ ├── agent_creator/ # Agent Creator 模板 +│ │ └── scrapling_crawler/ # 爬虫模板 +│ │ +│ ├── {companyId}/ # 公司实例 (每家公司一个目录) +│ │ ├── company.json # 公司元数据 + 状态 + 心跳配置 +│ │ ├── agents/ # 该公司专属 Agent 池 +│ │ │ ├── ceo/ # 公司 CEO +│ │ │ │ ├── agent.md # 核心身份标识 +│ │ │ │ ├── soul.md # 思维模式 +│ │ │ │ ├── identity.md # 名称/emoji 等 +│ │ │ │ ├── tools.md # 可用工具 +│ │ │ │ ├── user.md # 上级偏好 +│ │ │ │ ├── heartbeat.md # 心跳策略 +│ │ │ │ ├── todo.md # 待办清单 +│ │ │ │ ├── plan.md # 任务计划 +│ │ │ │ ├── config.json # 运行配置 +│ │ │ │ ├── cron.json # 定时任务 +│ │ │ │ └── memory/ # 记忆系统 +│ │ │ │ ├── memory.md # 记忆总览 +│ │ │ │ ├── hippocampus.md # 海马体经验索引 +│ │ │ │ ├── hippocampus-index.json # 海马体结构化索引 +│ │ │ │ ├── cerebellum/ # 小脑 (固化方案) +│ │ │ │ ├── short-term/ # 短期记忆 (session-*.md) +│ │ │ │ └── reflections/ # 反思记录 (reflect-*.json) +│ │ │ ├── cto/ +│ │ │ ├── coo/ +│ │ │ └── {role-agent}/ +│ │ │ +│ │ ├── goals/ # 公司级 OKR (可选) +│ │ │ └── _index.json +│ │ ├── pipelines/ # SOP 流水线定义 +│ │ └── workspace/ # 公司共享工作区 +│ │ └── {agentId}/ # Agent 工作产出 +│ │ +│ ├── goals/ # 全局 OKR 目标 +│ │ ├── _index.json # 所有 Goal 摘要索引 +│ │ └── G-{NNN}/ # 每个 Goal 一个目录 +│ │ ├── goal.json # 完整 OKR 树 +│ │ └── progress.json # 自动计算进度快照 +│ │ +│ └── agents/ # (兼容旧路径) 全局 tasks +│ └── .tasks/ # 任务记录 +│ +├── docs/ +│ ├── LEMONBOSS-SYSTEM-DESIGN.md # 主索引 +│ └── system-design/ # 分章节子文档 (01~24.md) +│ +├── CLAUDE.md # Claude CLI 配置 +├── package.json +├── pnpm-workspace.yaml +├── install.sh # 安装脚本 +└── start.sh # 启动脚本 +``` + +--- + +## 路由挂载路径 + +| 挂载路径 | 路由文件 | 说明 | +|---------|---------|------| +| `/api/agent` | `agent-chat.js` | Agent CRUD + Chat + Dispatch/Report | +| `/api/company` | `company.js` | 公司 CRUD + 招聘 + OKR + Pipeline | +| `/api/goals` | `goals.js` | 全局 OKR Goals | + +## 数据寻址规则 + +```javascript +// 全局 Agent（不属于任何公司） +const agentDir = path.join(DATA_DIR, 'system', 'agents', agentId); +// 即: system/agents/master/ + +// 公司内 Agent +const agentDir = path.join(DATA_DIR, companyId, 'agents', agentId); +// 即: data/wechatai/agents/ceo/ + +// 模板库 +const templateDir = path.join(DATA_DIR, 'system', 'templates', roleName); +// 即: system/templates/ceo/ +``` diff --git a/docs/done/system-design/12-data-model.md b/docs/done/system-design/12-data-model.md new file mode 100644 index 0000000..8d8b210 --- /dev/null +++ b/docs/done/system-design/12-data-model.md @@ -0,0 +1,95 @@ +# 12. 数据模型 + +## 12.1 Agent 表 + +```sql +CREATE TABLE agents ( + id TEXT PRIMARY KEY, + name TEXT NOT NULL, + type TEXT NOT NULL CHECK(type IN ('master', 'cxo', 'role', 'skill')), + parent_id TEXT REFERENCES agents(id), -- 上级 Agent + owner_id TEXT NOT NULL, -- 所属用户 + status TEXT DEFAULT 'idle' + CHECK(status IN ('idle', 'running', 'paused', 'error')), + goal_id TEXT REFERENCES goals(id), -- 绑定目标 + config TEXT, -- JSON: cron, api, gateway + define_path TEXT, -- Agent 定义文件夹路径 + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP +); +``` + +## 12.2 Goal 表 + +```sql +CREATE TABLE goals ( + id TEXT PRIMARY KEY, + agent_id TEXT REFERENCES agents(id), + description TEXT NOT NULL, + metrics TEXT, -- JSON: 可量化指标 + target_value REAL, -- 目标值 + current_value REAL DEFAULT 0, -- 当前值 + status TEXT DEFAULT 'active' + CHECK(status IN ('active', 'achieved', 'failed', 'paused')), + deadline DATETIME, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP +); +``` + +## 12.3 Loop 运行记录表 + +```sql +CREATE TABLE loop_runs ( + id TEXT PRIMARY KEY, + agent_id TEXT REFERENCES agents(id), + loop_type TEXT CHECK(loop_type IN ('master', 'cxo', 'role', 'skill')), + phase TEXT CHECK(phase IN + ('perceive', 'reason', 'execute', 'feedback', 'reflect')), + input TEXT, -- JSON: 输入数据 + output TEXT, -- JSON: 输出数据 + goal_progress REAL, -- 0.0 ~ 1.0 + duration_ms INTEGER, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP +); +``` + +## 12.4 Memory 表 + +```sql +CREATE TABLE memories ( + id TEXT PRIMARY KEY, + agent_id TEXT REFERENCES agents(id), + type TEXT CHECK(type IN ('short', 'long', 'session')), + session_id TEXT, + content TEXT, -- JSON / Markdown + embedding BLOB, -- 向量嵌入（用于语义搜索） + importance REAL DEFAULT 0.5, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + expires_at DATETIME -- 短期记忆过期时间 +); +``` + +## 12.5 Task 表 + +```sql +CREATE TABLE tasks ( + id TEXT PRIMARY KEY, + assigner_id TEXT REFERENCES agents(id), -- 分派者 + assignee_id TEXT REFERENCES agents(id), -- 执行者 + goal_id TEXT REFERENCES goals(id), + pipeline_id TEXT, -- v1.1: 所属 Pipeline + depends_on TEXT, -- v1.1: JSON, 前序 task IDs + description TEXT NOT NULL, + input TEXT, -- JSON: 任务输入 + output TEXT, -- JSON: 任务输出 + status TEXT DEFAULT 'pending' + CHECK(status IN ('pending', 'running', 'done', 'failed')), + priority TEXT DEFAULT 'normal' + CHECK(priority IN ('low', 'normal', 'high', 'urgent')), + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + completed_at DATETIME +); +``` + +> **v1.1 变更**: Task 表新增 `pipeline_id` 和 `depends_on` 字段，支持 Pipeline 流转和前序依赖。 diff --git a/docs/done/system-design/13-api-design.md b/docs/done/system-design/13-api-design.md new file mode 100644 index 0000000..2e676d0 --- /dev/null +++ b/docs/done/system-design/13-api-design.md @@ -0,0 +1,195 @@ +# 13. API 设计 + +> **更新日期**: 2026-03-26 +> **状态**: ✅ 反映实际已实现的 API 端点 + +--- + +## 13.1 Agent 管理 (`/api/agent`) + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/agent/list` | 列出所有 Agent | +| `GET` | `/api/agent/:agentId/info` | 获取 Agent 详情 | +| `POST` | `/api/agent/scaffold` | 创建 Agent 骨架 (AgentScaffold) | +| `POST` | `/api/agent/:agentId/chat` | 与 Agent 对话 (SSE 流式) | +| `POST` | `/api/agent/:agentId/chat/:convId/stop` | 停止正在进行的对话 | + +## 13.2 Agent Bootstrap 文件 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/agent/:agentId/bootstrap/:filename` | 获取 Agent Bootstrap 文件 | +| `GET` | `/api/agent/:agentId/files` | 获取 Agent 文件树 | +| `GET` | `/api/agent/:agentId/file/*` | 读取 Agent 任意文件 | + +## 13.3 Agent 待办与计划 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/agent/:agentId/todo` | 获取待办清单 | +| `PUT` | `/api/agent/:agentId/todo` | 更新待办清单 | +| `GET` | `/api/agent/:agentId/plan` | 获取任务计划 | +| `PUT` | `/api/agent/:agentId/plan` | 更新任务计划 | +| `GET` | `/api/agent/:agentId/cron` | 获取定时任务 | +| `PUT` | `/api/agent/:agentId/cron` | 更新定时任务 | + +## 13.4 任务分发与汇报 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/agent/task/dispatch` | 向目标 Agent 分发任务 (写入 todo.md + plan.md，支持 autoExecute) | +| `POST` | `/api/agent/task/report` | Agent 汇报任务完成 (更新 todo.md + plan.md + 可选 Goal 节点) | +| `POST` | `/api/agent/task/reject` | 拒绝/驳回任务 | +| `POST` | `/api/agent/human-request` | Agent 向人类发起待办请求 | + +## 13.5 Agent 对话历史 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/agent/:agentId/conversations` | 列出对话历史 | +| `GET` | `/api/agent/:agentId/conversations/:convId` | 获取对话详情 | +| `GET` | `/api/agent/:agentId/conversations/:convId/sub-logs` | 获取子 Agent 日志 | +| `GET` | `/api/agent/:agentId/conversations/:convId/sub-logs/:logFile` | 读取子日志文件 | +| `DELETE` | `/api/agent/:agentId/conversations/:convId` | 删除对话记录 | + +## 13.6 Agent 记忆系统 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/agent/:agentId/memory/cerebellum` | 写入小脑 (固化方案) | +| `POST` | `/api/agent/:agentId/memory/consolidate` | 触发记忆整合 | +| `POST` | `/api/agent/:agentId/memory/daily-report` | 生成日报 | + +--- + +## 13.7 Company 管理 (`/api/company`) + +### CRUD + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/company/create` | 创建新公司 (自动初始化目录 + company.json) | +| `GET` | `/api/company/list` | 列出所有公司 | +| `GET` | `/api/company/templates` | 列出所有模板 (读取 _registry.json) | +| `GET` | `/api/company/:companyId` | 获取公司详情 | +| `PUT` | `/api/company/:companyId` | 更新公司信息 | +| `POST` | `/api/company/:companyId/shutdown` | 关停公司 | +| `POST` | `/api/company/:companyId/start` | 启动公司 | +| `GET` | `/api/company/:companyId/status` | 获取公司运行状态 | + +### 招聘与 Agent 管理 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/company/:companyId/hire` | 招聘 Agent (模板优先 → Creator+FDE 兜底) | +| `POST` | `/api/company/:companyId/fire` | 解雇 Agent | +| `POST` | `/api/company/:companyId/deposit-template` | 沉淀 Agent 为模板 | +| `GET` | `/api/company/:companyId/agents` | 列出公司所有 Agent | +| `GET` | `/api/company/:companyId/agents/:agentId/skills` | 查看 Agent 技能 | + +### 心跳控制 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `PUT` | `/api/company/:companyId/agents/:agentId/heartbeat` | 更新 Agent 心跳配置 | +| `POST` | `/api/company/:companyId/agents/:agentId/heartbeat/start` | 启动 Agent 心跳 | +| `POST` | `/api/company/:companyId/agents/:agentId/heartbeat/stop` | 停止 Agent 心跳 | + +### 公司级 OKR + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/company/:companyId/goals` | 列出公司 OKR | +| `POST` | `/api/company/:companyId/goals` | 创建公司 OKR | +| `GET` | `/api/company/:companyId/goals/:goalId` | 获取 OKR 详情 | +| `PUT` | `/api/company/:companyId/goals/:goalId` | 更新 OKR | +| `POST` | `/api/company/:companyId/goals/:goalId/nodes` | 添加 OKR 节点 | +| `PUT` | `/api/company/:companyId/goals/:goalId/nodes/:nodeId` | 更新 OKR 节点 | +| `GET` | `/api/company/:companyId/goals/:goalId/progress` | 获取 OKR 进度 | + +### SOP 流水线 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/company/:companyId/pipelines` | 创建流水线 | +| `GET` | `/api/company/:companyId/pipelines` | 列出流水线 | +| `GET` | `/api/company/:companyId/pipelines/:pipelineId` | 获取流水线详情 | +| `PUT` | `/api/company/:companyId/pipelines/:pipelineId` | 更新流水线 | +| `POST` | `/api/company/:companyId/pipelines/:pipelineId/run` | 运行流水线 | +| `GET` | `/api/company/:companyId/pipelines/runs/list` | 列出流水线运行记录 | +| `GET` | `/api/company/:companyId/pipelines/runs/:runId` | 获取运行详情 | +| `POST` | `/api/company/:companyId/pipelines/runs/:runId/advance` | 推进流水线下一步 | +| `GET` | `/api/company/:companyId/pipelines/runs/:runId/current` | 获取当前步骤 | +| `POST` | `/api/company/:companyId/pipelines/runs/:runId/reject` | 驳回当前步骤 | + +### 工作日历 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/company/:companyId/schedule` | 获取日程表 | +| `POST` | `/api/company/:companyId/schedule/slots` | 创建日程槽 | +| `PUT` | `/api/company/:companyId/schedule/slots/:slotId` | 更新日程槽 | +| `DELETE` | `/api/company/:companyId/schedule/slots/:slotId` | 删除日程槽 | + +### 运营数据 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/company/:companyId/data/metrics` | 获取运营指标 | +| `GET` | `/api/company/:companyId/data/trending` | 获取趋势数据 | +| `GET` | `/api/company/:companyId/data/attribution` | 获取归因分析 | + +--- + +## 13.8 全局 OKR (`/api/goals`) + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/goals` | 列出所有目标 (返回 _index.json) | +| `POST` | `/api/goals` | 创建新目标 | +| `GET` | `/api/goals/:goalId` | 获取完整 OKR 树 | +| `PUT` | `/api/goals/:goalId` | 更新目标元数据 | +| `POST` | `/api/goals/:goalId/nodes` | 添加节点 | +| `GET` | `/api/goals/:goalId/nodes/:nodeId` | 获取节点详情 | +| `PUT` | `/api/goals/:goalId/nodes/:nodeId` | 更新节点状态 | +| `GET` | `/api/goals/:goalId/progress` | 返回进度统计 | + +--- + +## 13.9 Master Agent 对话 (`/api/master`) + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/master/chat` | 与 Master Agent 对话 (SSE 流式) | +| `POST` | `/api/master/upload` | 上传文件给 Master | +| `GET` | `/api/master/sessions` | 列出 Master 对话会话 | +| `DELETE` | `/api/master/sessions/:id` | 删除 Master 会话 | + +--- + +## 13.10 Innovator 技能管理 (`/api/innovator`) + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/innovator/skills` | 列出所有技能 | +| `GET` | `/api/innovator/skills/:name` | 获取技能详情 | +| `DELETE` | `/api/innovator/skills/:name` | 删除技能 | +| `PATCH` | `/api/innovator/skills/:name` | 更新技能元数据 | +| `POST` | `/api/innovator/skills/:name/rename` | 重命名技能 | +| `GET` | `/api/innovator/skills/:name/evolve-log` | 获取进化日志 | +| `POST` | `/api/innovator/skills/scan` | 扫描技能目录 | +| `POST` | `/api/innovator/skills/:name/retrain` | 触发重训 | +| `GET` | `/api/innovator/skills/:name/artifacts` | 获取技能产物 | +| `GET` | `/api/innovator/jobs/:jobId` | 查询异步任务状态 | +| `GET` | `/api/innovator/conversations` | 列出 Innovator 对话 | + +--- + +## 13.11 实时流 + +| 端点 | 协议 | 说明 | +|------|------|------| +| `/api/agent/:agentId/chat` | SSE | Agent 对话实时输出流 | +| `/api/master/chat` | SSE | Master Agent 对话实时输出流 | +| WebSocket (claude-chat-ws.js) | WS | Claude Chat 双向实时通道 | diff --git a/docs/done/system-design/15-innovator-meta-agent.md b/docs/done/system-design/15-innovator-meta-agent.md new file mode 100644 index 0000000..f324b77 --- /dev/null +++ b/docs/done/system-design/15-innovator-meta-agent.md @@ -0,0 +1,257 @@ +# 15. Innovator — 元 Agent 设计 + +> Innovator 是 LemonBoss 系统的 **第一个 Agent**，也是 **唯一手动创建** 的 Agent。 +> 它的职责是创建、训练和交付所有其他 Agent。 + +--- + +## 15.1 为什么 Innovator 是第一个？ + +``` +在有"公司"之前, 先要有"造人的人"。 + +Innovator (元 Agent, 手动创建) + → 创建 Master Agent (并训练) + → 创建 CEO Agent (并训练) + → 创建任何需要的 Agent (并训练) + → 所有 Agent 就绪后, 组织开始运转 + +之后: + Master / CXO 也可以调用 Innovator 来创建新的下级 Agent +``` + +Innovator 不在四层组织架构（Master/CXO/Role/Skill）内。它是四层之外的 **元层 (Meta)**，像"HR 部 + 培训学院"，独立于公司运营体系。 + +--- + +## 15.2 架构位置 + +``` + ┌────────────────────────┐ + │ Innovator (元层) │ ← 四层之外, 负责"造人" + │ 创建 + 训练 Agent │ + └────────┬───────────────┘ + │ 创建并训练 + ┌────────────┼──────────────┐ + ▼ ▼ ▼ + Master CXO Agent Role Agent ... + (第一层) (第二层) (第三层) +``` + +--- + +## 15.3 核心职责 + +| 职责 | 说明 | +|------|------| +| **理解需求** | 接收"我需要什么样的 Agent"的描述, 澄清细节 | +| **Hunt (狩猎)** | 搜索领域知识、爬取标杆案例 | +| **Digest (消化)** | 提炼 knowhow.md 方法论 + benchmark.md 评分标准 | +| **Scaffold (创建)** | 创建 Agent 目录 + 6 大 Bootstrap Files | +| **Skill-Create** | 根据 knowhow + benchmark 生成 SKILL.md | +| **Evolving (进化)** | 迭代训练直到 benchmark ≥ 90 分 | +| **交付** | 标记 Agent 为 ready, 汇报摘要和得分 | + +--- + +## 15.4 技能清单 + +来自现有 `skills/` 目录的成熟实现： + +| 技能 | 位置 | 执行方式 | 作用 | +|------|------|---------|------| +| meta_creator | 引擎硬编码 | `executeMetaCreator()` | 调用 AgentScaffold 创建 Agent 骨架 | +| meta_hunt | `.claude/skills/meta_hunt/` | Claude CLI 子进程 | 搜索 + 爬取领域知识 | +| meta_digest | `.claude/skills/meta_digest/` | Claude CLI 子进程 | 提炼 knowhow + benchmark + SKILL.md | +| meta_evolving | `.claude/skills/meta_evolving/` | Claude CLI 子进程 | 执行→评分→改写循环 | +| l1-*/l2-* | `.claude/skills/l1-*/l2-*/` | 知识手册 (v1) | 作为执行型 Agent 的参考指南 | + +> **重要**：meta_creator 是唯一一个不通过 Claude CLI 执行的子 Agent。 +> 它被引擎拦截后直接调用 Node.js 代码，保证 100% 可靠。 +> 详见 [20-scaffold-first-agent-creation.md](20-scaffold-first-agent-creation.md) + +> **工具隔离**：Innovator 作为编排型 Agent，启动时带 `--tools ""` 参数， +> 物理禁用所有原生工具。详见 [19-orchestrator-tool-isolation.md](19-orchestrator-tool-isolation.md) + +--- + +## 15.5 工作流程 + +``` +用户/上级: "我需要一个会爬社交媒体热搜的 Agent" + │ + ▼ +1️⃣ 理解需求 (Innovator 纯文本分析) + → "需要 Skill 层 Agent, 领域: 社交媒体数据采集" + │ + ▼ +2️⃣ Scaffold (引擎硬编码执行) + → [CALL: meta_creator] → executeMetaCreator() + → AgentScaffold.create('social_crawler', 'skill', ...) + → 创建 data/agents/social_crawler/ 完整目录 + │ + ▼ +3️⃣ Hunt (Claude CLI 执行型 Agent) + → [CALL: meta_hunt] + → 搜索社交媒体爬虫的最佳实践、方法论 + → 爬取案例、API 文档 + → 写入 data/agents/social_crawler/train/ + │ + ▼ +4️⃣ Digest (Claude CLI 执行型 Agent) + → [CALL: meta_digest] + → 读取 train/ 调研数据 + → 提炼 knowledge/knowhow.md + knowledge/benchmark.md + → 生成 .claude/skills/main_skill/SKILL.md + │ + ▼ +5️⃣ Evolve (迭代训练) + → [CALL: meta_evolving] + → 运行测试用例 → benchmark 评分 → 改写 SKILL.md → 重复 + → 直到 score ≥ 90 + │ + ▼ +6️⃣ Execute (执行用户任务) + → [CALL: social_crawler] → 执行原始需求 +``` + +--- + +## 15.6 Bootstrap Files 定义 + +### agent.md + +```markdown +# Innovator — 元 Agent + +## 身份 +你是 LemonBoss 系统的元 Agent (Meta Agent)。 +你是系统中第一个被创建的 Agent, 也是唯一一个手动创建的 Agent。 +你的唯一职责是: 创建、训练、交付高质量的 Agent。 + +## 核心工作流 +1. 理解用户/上级对新 Agent 的需求描述 +2. Hunt: 搜索领域知识, 爬取标杆案例 +3. Digest: 提炼 knowhow 方法论 + benchmark 评分标准 +4. Scaffold: 创建 Agent 目录和 Bootstrap Files +5. Skill-Create: 生成 SKILL.md 技能定义 +6. Evolving: 迭代训练直到 benchmark ≥ 90 分 +7. 交付: 标记 Agent 为 ready, 汇报摘要 + +## Never Rules +- 不要自己执行业务任务 (你是造人的, 不是干活的) +- 不要跳过 Hunt/Digest 直接创建 Agent (没有调研的 Agent 是低质量的) +- 不要在 benchmark < 90 时就标记为 ready +- 不要修改已 ready 的 Agent 的 agent.md (那是它上级的权力) + +## Confirm-Before Rules +- 创建 Master 层 Agent 前, 需要跟用户确认定位 +- benchmark 标准生成后, 展示给用户确认再进入 Evolving + +## Always Rules +- 每个新 Agent 必须有完整的 6 大 Bootstrap Files +- 每个新 Agent 必须有 knowhow.md + benchmark.md +- 每次 Evolving 迭代都要保存版本快照 +- 创建完成后向用户/上级汇报 Agent 摘要和 benchmark 得分 + +## 可用工具 +- agent.scaffold: 创建 Agent 目录结构 + Bootstrap Files +- hunt.research: 搜索引擎领域研究 +- hunt.crawl: 爬取标杆案例数据 +- digest.extract: 提炼 knowhow 方法论 +- benchmark.generate: 生成评分标准 +- benchmark.evaluate: 评估产出质量 (逐维度打分) +- skill.create: 根据 knowhow + benchmark 生成 SKILL.md +- evolve.run: 执行进化循环 (执行→评分→分析→改写→重复) +``` + +### soul.md + +```markdown +# Innovator 的灵魂 + +## 思维方式 +- 质量驱动: 宁可多训练几轮, 也不交付不合格的 Agent +- 系统化: 严格按 Hunt → Digest → Evolving 流程执行, 不跳步 +- 数据导向: 所有质量判断都基于 benchmark 分数, 不靠感觉 +- 可追溯: 每一步都有明确的输入输出, 每个版本都有快照 + +## 沟通风格 +- 跟用户对话时: 先完整理解需求, 主动问澄清问题 +- 创建过程中: 报告每个阶段的关键产出 + (knowhow 摘要 / benchmark 维度 / 进化分数变化) +- 完成时: 给出 Agent 的完整档案 + +## 价值观 +- 高质量 > 快速交付 +- 可量化 > 主观判断 +- 可复用 > 一次性 +``` + +### identity.md + +```markdown +# 身份信息 + +## 基础信息 +- 名称: Innovator +- Emoji: 🧬 +- 类型: meta + +## 问候语 +"你好, 我是 Innovator, LemonBoss 的元 Agent。 +告诉我你需要什么样的 Agent, 我来研究、创建和训练它。" +``` + +--- + +## 15.7 Innovator 创建其他 Agent 时的产物 + +当 Innovator 创建一个新 Agent 后, 目标 Agent 的目录会包含: + +``` +data/agents/{new-agent-id}/ +├── agent.md ← Innovator 生成 +├── soul.md ← Innovator 生成 +├── identity.md ← Innovator 生成 +├── user.md ← Innovator 生成 +├── tools.md ← Innovator 生成 +├── heartbeat.md ← Innovator 生成 +├── skills/ +│ ├── skills.md ← Innovator 生成 (技能索引) +│ └── {skill}/ +│ ├── SKILL.md ← Skill-Creator 生成, Evolving 优化 +│ ├── evolve/ ← Evolving 过程日志 +│ └── *.js/*.py ← 可选的技能代码 +├── knowledge/ +│ ├── hunt/ ← Hunt 阶段产出 +│ │ ├── research.md +│ │ ├── toplist.md +│ │ └── crawl_data/ +│ └── digest/ ← Digest 阶段产出 +│ ├── knowhow.md +│ └── benchmark.md +├── memory/ +│ └── memory.md ← 训练期间积累的初始记忆 +├── conversations/ ← 对话会话 (16-agent-conversation-architecture.md) +│ └── {convId}/ +│ ├── meta.json +│ ├── history.json +│ └── {msgId}/messages.log +├── workspace/ ← Agent 工作区 +├── train/ ← 训练过程数据 (Hunt/Digest/Evolve) +├── logs/ +└── config.json ← status: "ready" +``` + +--- + +## 15.8 启动路径 + +``` +Phase 1: 手动创建 Innovator 目录 + Bootstrap Files ← ✅ 已完成 +Phase 2: 搭建 Chat 页面, 连通 Innovator ← ✅ 已完成 (见 16-agent-conversation-architecture.md) +Phase 3: 用户对 Innovator 说 "创建 Master Agent" +Phase 4: 用户对 Innovator 说 "创建 CEO Agent" +Phase 5: 切换到 Master 对话, 组织开始运转 +``` diff --git a/docs/done/system-design/16-agent-conversation-architecture.md b/docs/done/system-design/16-agent-conversation-architecture.md new file mode 100644 index 0000000..fe55ca8 --- /dev/null +++ b/docs/done/system-design/16-agent-conversation-architecture.md @@ -0,0 +1,169 @@ +# 16. Agent 对话架构 — 两层日志 + 多轮上下文恢复 + +> 每个 Agent 的对话遵循 `conversationId/messageId` 两层存储架构， +> 支持持久化 + 多轮上下文 + 服务重启后自动恢复。 + +--- + +## 16.1 存储结构 + +``` +data/agents/{agentId}/conversations/ ← Agent 实例自带对话目录 +└── {conversationId}/ ← 一个对话 + ├── meta.json ← 对话元数据 + ├── history.json ← 有序消息列表 (供前端 + 上下文恢复) + └── {messageId}/ ← 一轮对话 (user + agent) + └── messages.log ← 时间戳日志 +``` + + + +### meta.json 结构 + +```json +{ + "conversationId": "conv-mn3112l3", + "agentId": "innovator-001", + "title": "创建 Master Agent", + "createdAt": "2026-03-23T10:12:11.993Z", + "updatedAt": "2026-03-23T10:12:50.078Z", + "status": "completed", // running | completed | failed | idle + "stats": { + "messageCount": 4, + "toolCallCount": 2 + } +} +``` + +### history.json 结构 + +```json +[ + { "role": "user", "content": "你好", "messageId": "msg-xxx-aaa", "timestamp": "..." }, + { "role": "assistant", "content": "你好，我是 Innovator", "messageId": "msg-xxx-aaa", "timestamp": "..." }, + { "role": "user", "content": "帮我创建 Master Agent", "messageId": "msg-xxx-bbb", "timestamp": "..." }, + { "role": "assistant", "content": "好的，我来创建...", "messageId": "msg-xxx-bbb", "timestamp": "..." } +] +``` + +### messages.log 格式 (每轮) + +``` +[2026-03-23T10:12:11.994Z] [USER] +你好 + +[2026-03-23T10:12:26.207Z] [AGENT] +你好，我是 Innovator，LemonBoss 的元 Agent。 +``` + +--- + +## 16.2 多轮对话 — 三场景自动处理 + +``` + ┌─────────────────────────────────────┐ + │ sendMessage() │ + │ Agent.js 父类核心接口 │ + └────────────┬────────────────────────┘ + │ + ┌────────────▼────────────────────────┐ + │ isNewSession = false? │ + │ (同进程 + 同 conversationId) │ + └───┬──────────────────────────┬──────┘ + │ YES │ NO + ▼ ▼ + ┌───────────────┐ ┌───────────────────────┐ + │ 场景 B: │ │ history.length === 0? │ + │ 直接发 message│ └───┬───────────────┬──-┘ + │ (ACP 自带上下文) │ YES │ NO + └───────────────┘ ▼ ▼ + ┌──────────────┐ ┌──────────────────┐ + │ 场景 A: │ │ 场景 C: │ + │ system prompt │ │ system prompt │ + │ + 用户消息 │ │ + 历史摘要 (≤20条) │ + │ │ │ + 用户消息 │ + └──────────────┘ └──────────────────┘ +``` + +| 场景 | 触发条件 | Prompt 构成 | 说明 | +|------|---------|-------------|------| +| **A. 全新对话** | 首条消息 + 无历史 | systemPrompt + message | ClaudeCliProtocol 首次 sendPrompt | +| **B. 同进程多轮** | 同 convId + same session | message only | ACP 持久进程天然保持上下文 | +| **C. 恢复对话** | 新 session + 有历史 | systemPrompt + history + message | 服务重启后自动注入历史摘要 | + +--- + +## 16.3 ACP Session 池 + +``` +sessions: Map + +key = "{agentId}:{conversationId}" ← 每个对话独立会话 +entry = { + protocol: ClaudeCliProtocol, ← 持久 CLI 进程 + messageCount: number, ← 消息计数 (判断首次 vs 后续) + agentId: string, + convId: string, +} +``` + +- 一个 Agent 可以同时有多个对话（不同 conversationId） +- 每个对话对应一个独立的 ClaudeCliProtocol 实例 +- 进程退出 / 超时 → 自动清理 → 下次 sendMessage 时自动创建新会话 + 恢复上下文 + +--- + +## 16.4 Agent.js 父类接口 + +`packages/agent-core/Agent.js` 提供以下对话管理方法: + +| 方法 | 说明 | +|------|------| +| `createConversation(title)` | 创建新对话，返回 `{ conversationId }` | +| `listConversations()` | 列出所有对话的 meta 信息 | +| `loadConversationHistory(convId)` | 加载对话的完整消息列表 | +| `appendMessage(convId, msg)` | 追加消息（同步写 messageId 日志 + history.json + meta.json） | +| `sendMessage(convId, message, options)` | 核心接口：自动处理三场景 prompt 构建，emit event 给 ACP 层 | + +--- + +## 16.5 API 端点 + +``` +GET /api/agent/list → 列出所有 Agent +GET /api/agent/:agentId/info → Agent 详情 +GET /api/agent/:agentId/conversations → 对话列表 +GET /api/agent/:agentId/conversations/:convId → 对话详情 (meta + messages) +POST /api/agent/:agentId/chat → 发送消息 (SSE 流式响应) + body: { message, conversationId? } + events: session | thinking | agent_output | tool_call | error | result +DELETE /api/agent/:agentId/conversations/:convId → 删除对话 +``` + +--- + +## 16.6 与 Agent 目录结构的关系 + +```diff + data/agents/{id}/ + ├── agent.md + ├── soul.md + ├── identity.md + ├── user.md + ├── tools.md + ├── heartbeat.md + ├── skills/ + ├── memory/ + ├── knowledge/ + ├── workspace/ ++ ├── conversations/ ← 新增: 对话会话目录 ++ │ └── {convId}/ ++ │ ├── meta.json ++ │ ├── history.json ++ │ └── {msgId}/ ++ │ └── messages.log + ├── logs/ + └── config.json +``` + +对话是 Agent 的一部分，而不是全局的——每个 Agent 管理自己的对话历史。 diff --git a/docs/done/system-design/17-skill-orchestration-and-concurrency.md b/docs/done/system-design/17-skill-orchestration-and-concurrency.md new file mode 100644 index 0000000..2b3d4a6 --- /dev/null +++ b/docs/done/system-design/17-skill-orchestration-and-concurrency.md @@ -0,0 +1,71 @@ +# 17. Skill Orchestration & Concurrency Architecture + +本文档记录了系统中关于 Skill 管理机制的演进思路，以及为支撑 Innovator 等 Orchestrator 高效执行多目标任务而设计的“并发子代理 (Concurrent Sub-Agent)”架构。我们正式废除了旧有的 SQLite 数据库绑定方案，确立了 **Local File-System First（纯文件系统挂载）** 原则。 + +--- + +## 1. Local File-System First 架构 (移除 SQLite / data/skills 依赖) + +在旧版本中，Skill 系统的可用状态、元数据及其层级关系被同时维护在 `data/skills/` 和本地 `skills.sqlite` 数据库里。这种双源结构经常导致： +- 文件存在但由于数据库未记录，导致技能不可用 (幽灵 Bug)。 +- 修改本地文件（如重写提示词）后热重载失效。 + +### 1.1 核心重构与 `rootdir/skills/` 绝对源头 +目前的纯无状态化架构中，取消了所有的 DB 查询（弃用 `server/services/skill-db` 参与核心运行时计算），直接对原生的目录系统进行实时挂载扫描： +- 系统核心组件 `skill-config-loader.js` 会在每次拉取架构配置时，直接遍历项目根目录下的 `skills/`（即 `path.resolve(__dirname, '../../../skills')`）。 +- 目录存在即技能存在；内部包含 `SKILL.md` 的文件夹将被全自动解析并作为可用 Agent 注入。如果该文件含有 `layer: orchestrator` 或类似的大脑定义，将自动提升为 Orchestrator。 +- 这一改动**完全去除了状态机依赖**并发地保持了 Claude CLI 等底层协议提倡的原始文件驱动属性。 + +### 1.2 注入点 +当我们首次向 Innovator 等代理生成 `system prompt` 时，系统扫描出的 `fullSystemConfig.agents` 配置会实时序列化后填充到提示词中的 `{{AVAILABLE_AGENTS}}` 占位符内，让主代理在没有任何 DB 信息的前提下也能了解当前所有安装的可调用技能池。 + +--- + +## 2. 并发子编排引擎 (Concurrent Orchestration Engine) + +在研究深度报告 (Deep Research) 或网页浏览时，Innovator 通常需要发起对多个独立话题甚至工具的并行调用，以压缩墙上时间（Wall-clock time）。为了支撑该目标，系统对基础解析器（`parser.js`）以及对话驱动路由（`agent-chat.js`）做出了彻底改造。 + +### 2.1 突破串行化拦截 +传统的设计为了维持“因果链 (Causal Chain)”，使用了 `_applySerialConstraint` 强制截取 Agent 产生的最后一个 `[CALL: xxx]` 数据块。现在通过开放 `allowParallel: true` 选项，系统可以从一次输出流中正则匹配出所有的调度请求： +```text +[CALL: meta_research] +分析 AI 的未来发展趋势 +[/CALL] + +[CALL: meta_research] +调查自动驾驶汽车的采用率 +[/CALL] +``` +以上将返回完整的 Calls Array。 + +### 2.2 Promise.all 协程调度 +在 `/api/agent/:agentId/chat` 核心路由中： +- 将串行（`for (const call of calls)`）阻塞迭代替换为了 `await Promise.all()`。 +- 这允许系统在一轮思考响应内，瞬间启动多条 `AgentManager.callAgent()` 协程链路。每一条链路都会实例化独立的底层 Claude 进程并发执行。 + +### 2.3 任务追踪标识 (Unique Call ID) +为了对这些并发运行的环境进行隔离和精准回显追踪，路由在启动任务前会为每一个 Sub-Agent 事件分配一个唯一标识，例如： +`const callId = "sub-" + randomUUID().substring(0, 6)` +向前端的 SSE 事件流中（如 `event: 'chunk'`）挂载该 ID，保证前端不论收到多混乱的异步流交错，都能正确路由进独立的终端。 + +--- + +## 3. 前端多流终端并发 UI (Multi-Terminal UI) + +由于传统的单窗口 `msg-assistant` 已经无法呈现多个异步进程在彼此互不相关的流速下喷吐的状态，为了匹配上述后端能力，并达成震撼的多线程交互体验，在 Vue 侧 (`AgentChat.vue`) 引入了**“多窗口动态并行卡片流 (Parallel Windows)”**： + +### 3.1 状态驱动器 (`subAgents` Ref) +使用字典格式响应式地保存所有的子任务对象： +```javascript +const subAgents = ref({ + 'sub-1a2b3c': { agent: 'meta_research', status: 'running', content: '...' }, + 'sub-9x8y7z': { agent: 'meta_digest', status: 'success', content: '...' } +}); +``` +在收听 `sub_agent` 事件时，通过 `callId` 作为 Key 进行实时内容拼接和状态更新，甚至做到独立容器的自动 `scrollTop = scrollHeight` 下推。 + +### 3.2 动态卡片墙 (Grid Flexbox) +在聊天气泡大外框的末端，通过 CSS Grid 自适应布局 `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` 渲染： +- 当一个 Agent 并发出了三项分支，这三项任务会像控制台界面一般，在横向平整排列。 +- 每一个子容器都拥用专属的 Terminal 等宽字体控制台、带有彩色指示灯（运行中蓝色辉光、完成绿勾、失败红叉）。 +- 所有并行终端运行出各自的结果后（或者任意一条发生中断），后台等待在 `Promise.all` 的阻塞点会统一收束收集它们的汇总返回内容（包裹着 `[Sub Agent 返回结果]`），随后统一塞入主 Agent 的反馈下文继续下一轮迭代。 diff --git a/docs/done/system-design/18-local-filesystem-first-agent-encapsulation.md b/docs/done/system-design/18-local-filesystem-first-agent-encapsulation.md new file mode 100644 index 0000000..a966b85 --- /dev/null +++ b/docs/done/system-design/18-local-filesystem-first-agent-encapsulation.md @@ -0,0 +1,45 @@ +# 18. Local File-System First 与 Agent 完全自治架构 (v3.5) + +## 1. 架构演进背景 +在早期的 LemonBoss 设计中，技能 (Skills)、对话日志 (Conversations)、系统配置和 Agent 实例是分离的。这导致了三个核心问题： +1. **全局耦合污染**：所有的 Skill 堆砌在外部的 `repo/skills/` 中，当 Innovator 创建新的子 Agent 能力时，很容易造成命名空间冲突或权限越界。 +2. **缺乏运行闭环**：前端、日志存储和运行时配置需要依赖 SQLite 或独立的全局缓存映射，系统状态难以通过简单的文件复制进行迁移和备份。 +3. **Claude CLI 兼容性冲突**：Claude Code CLI 默认从工作空间目录底下的 `.claude/skills/` 挂载原生能力，而我们原本的自定义 `skills/` 与其天然隔离，导致大模型在本地原生工具和自定义 Agent 调度间产生严重的幻觉或抢跑情况。 + +## 2. Agent 的“完全封装” (Encapsulation) +系统现已全线迁移至 **Local File-System First** 和 **“Agent 就是微容器”** 的架构。全局根目录下的 `skills/` 与数据库已被彻底移除。现在的每一位 Agent 都是一个 100% 便携的“自治微容器”。 + +### 2.1 Agent 内部目录结构闭环 +所有 Agent（如 `innovator-001`）统一收拢在 `data/agents/{agentId}/` 下。其数据组织如下： +```text +data/agents/innovator-001/ + ├── config.json ← Agent 基础运行配置项 + ├── identity.md ← Agent 姓名、Emoji 及基础设定 + ├── user.md ← 面对的用户画像预设 + ├── soul.md ← Agent 的性格特征与边界 + ├── tools.md ← Agent 允许使用的外部工具白名单 + ├── memory/ ← Agent 长短期记忆数据库 + ├── conversations/ ← Agent 所有的历史对话记录（原全局级映射下放） + │ └── {convId}/ + │ ├── meta.json + │ ├── history.json + │ └── messages.log + ├── agent.md ← 【核心】Persona 指令（负责统驭“我是谁”） + └── .claude/ + └── skills/ ← 该 Agent 本人拥有的独占子技能挂载区 + ├── main_skill/ + │ └── SKILL.md ← 【核心】Workflow 指令（负责指导“我专业怎么做”） + ├── meta_hunt/ + └── meta_digest/ +``` + +### 2.2 灵肉分离 (Persona vs Capability) +在设计上，将传统臃肿的宏大提示词进行了概念切分： +- **`agent.md`**: 这是一个轻量级的占位符，仅告知 LLM 它的宏观定位（例如：“你是 Innovator 编排总控大脑…”）并以引用指针的方式要求其遵循 `main_skill`。 +- **`.claude/skills/main_skill/SKILL.md`**: 这才是其实际作业指南（包含编排语法 `[CALL:xxx]` 规则、反思规则矩阵、生成文件的指令路径逻辑）。这种划分让 LLM 启动时能像挂载可执行程序一样拥有天然的边界感，同时也完美迎合了 Claude MCP 的结构体系。 + +## 3. 多路并发与无缝切盘 +由于实现了 Agent 单体的绝对封闭自治，后台 Node 服务 `server/routes/agent-chat.js` 也顺势进行了架构级优化： +1. **并发解析**：通过对输出流的拦截，现在单次对话可以触发一个纯文本中包含了多个 `[CALL:]` 块的调度池。底层的 `AgentManager` 将利用 `Promise.all` 齐发请求到各个挂载的 SubAgent 的专用沙盒中执行任务。 +2. **零配置扫描**：服务器不再静态维护全系统的技能库表，而是启动热加载并遍历所有的 `data/agents/*/.claude/skills/` 节点。用户在网页端切换 Agent 头像时，后端路由从对应沙盒目录吐出隔离的 `conversations` List，界面实现极致丝滑的无状态切盘和防死链。 +3. **动态生成**：`meta_creator` 被赋予了全权创世能力。它不再只生成一个孤零零的脚本文档，而是通过 `AgentScaffold.js` 的引擎直接在 `data/agents/` 下开辟一个新的隔离目录，灌入完整的六大配置文件。一个新能力（Agent）的诞生，即代表着文件系统的一次干净合规的增量。 diff --git a/docs/done/system-design/19-orchestrator-tool-isolation.md b/docs/done/system-design/19-orchestrator-tool-isolation.md new file mode 100644 index 0000000..b52a543 --- /dev/null +++ b/docs/done/system-design/19-orchestrator-tool-isolation.md @@ -0,0 +1,165 @@ +# 19. 编排型 Agent 的工具隔离机制 (Tool Isolation) + +> **关键发现**：仅靠 System Prompt 文字禁令（如 `` 标签）无法阻止 LLM 使用原生工具。 +> 必须在 **Claude CLI 启动参数层面** 物理剥夺工具权限。 + +--- + +## 19.1 问题背景 + +### 现象 +Innovator Master Agent 的 `main_skill/SKILL.md` 中明确标注了 `` 禁令： +``` +❌ `Bash` — 禁止运行任何终端命令 +❌ `Write` / `Read` — 禁止读写任何文件 +``` + +然而在实际运行中，Innovator 仍然频繁调用了 `Bash`、`Write`、`Read`、`Skill`、`TodoWrite`、`TaskOutput` 等原生工具（共 15+ 次违规），**完全无视** prompt 层面的禁令。 + +### 根因分析 +Claude Code CLI 的原生工具（Bash、Write、Read 等）是模型底层自带的能力。在模型的决策优先级中： + +``` +原生工具能力 (内置) >> System Prompt 文字禁令 (注入) +``` + +当模型面对"帮我创建一个写诗的 agent"这类明确需要文件操作的任务时，它会**本能地**、**不可抗拒地**选择自己最擅长的原生工具来执行，而忽略 prompt 中的文字禁令。这不是 prompt 写得不够强的问题，而是**架构层面的权限控制缺失**。 + +--- + +## 19.2 解决方案：CLI 启动参数级工具封印 + +Claude CLI 原生支持以下工具控制参数： + +| 参数 | 作用 | 用法示例 | +|------|------|---------| +| `--tools ""` | **禁用全部原生工具** | `claude --tools ""` | +| `--allowedTools ` | 仅允许指定工具 | `claude --allowedTools "Read"` | +| `--disallowedTools ` | 禁用指定工具 | `claude --disallowedTools "Bash Write"` | + +### 对编排型 Agent 的应用 + +编排型 Agent（如 Innovator）不需要直接操作文件系统，它的唯一职责是输出 `[CALL: agent_name]` 文本块。因此在启动其 Claude CLI 进程时，传入 `--tools ""`，**从操作系统层面物理剥夺所有原生工具权限**。 + +被剥夺工具后，模型只能输出纯文本。后端的 `parser.js` 从纯文本中正则捕获 `[CALL:]...[/CALL]` 块，然后启动对应的子 Agent 进程（子 Agent 保留完整工具权限）。 + +--- + +## 19.3 实现架构 + +### ClaudeCliProtocol 层 +`packages/acp-core/protocol/ClaudeCliProtocol.js` 的 `connect()` 方法新增了工具配置支持： + +```javascript +constructor(agentInfo = {}, options = {}) { + // options.allowedTools = '' → --tools "" + // options.disallowedTools = [...] → --disallowedTools ... +} + +async connect(transport, workingDir) { + const args = ['--input-format', 'stream-json', ...]; + + // 编排型 Agent 工具封印 + if (this.options.allowedTools === '') { + args.push('--tools', ''); + } +} +``` + +### Agent Chat 路由层 +`server/routes/agent-chat.js` 的 `getOrCreateProtocol()` 根据 `config.json` 中的 Agent 类型自动决定工具权限： + +```javascript +const agentConfig = loadAgentConfig(agentDir); + +if (agentConfig.type === 'orchestrator' || agentConfig.type === 'meta') { + cliOptions.allowedTools = ''; // 禁用全部原生工具 +} + +const protocol = new ClaudeCliProtocol({ name }, cliOptions); +``` + +### Agent 类型与工具权限映射 + +| Agent Type | config.json `type` | 工具权限 | 说明 | +|------------|-------------------|---------|------| +| **编排型** (Innovator) | `meta` / `orchestrator` | ❌ 全部禁用 | 只能输出 `[CALL:]` 文本块 | +| **执行型** (meta_hunt 等) | `skill` / `executor` | ✅ 全部开放 | 可用 Bash、Read、Write 等 | + +--- + +## 19.4 验证标志 + +当系统正确运行时，控制台会打印： + +``` +[AgentChat] 🔒 Innovator 启用编排模式: 原生工具已全部禁用 +[ClaudeCliProtocol] 启动: claude --input-format stream-json ... --tools "" +``` + +如果日志中没有 `--tools ""`，说明工具封印未生效，需要检查 `config.json` 的 `type` 字段。 + +--- + +## 19.5 设计原则总结 + +> **Prompt 是建议，参数是法律。** +> +> 对于安全关键的权限控制，永远不要依赖 System Prompt 文字禁令。 +> 必须在进程启动层面通过 CLI 参数或 API 配置进行强制约束。 +> Prompt 中的 `` 标签可以作为**辅助提示**保留，但不能作为**唯一手段**。 + +--- + +## 19.6 父类继承：AgentScaffold 内置工具策略 + +工具隔离策略已内置于 `AgentScaffold` 父类（`packages/agent-core/AgentScaffold.js`）。 +**所有通过脚手架创建的新 Agent 都会自动继承正确的工具权限**，无需手动配置。 + +### config.json 自动生成的 `cli.toolPolicy` 字段 + +```json +{ + "id": "classical_poetry_writer", + "type": "skill", + "cli": { + "toolPolicy": {} + } +} +``` + +```json +{ + "id": "innovator-001", + "type": "meta", + "cli": { + "toolPolicy": { "allowedTools": "" } + } +} +``` + +### 类型与策略映射表（定义在 AgentScaffold._writeConfig） + +| Agent Type | `cli.toolPolicy` | 效果 | +|------------|-----------------|------| +| `master` | `{ allowedTools: '' }` | 禁用全部原生工具 | +| `meta` | `{ allowedTools: '' }` | 禁用全部原生工具 | +| `orchestrator` | `{ allowedTools: '' }` | 禁用全部原生工具 | +| `cxo` | `{ allowedTools: '' }` | 禁用全部原生工具 | +| `role` | `{}` | 保留全部工具 | +| `skill` | `{}` | 保留全部工具 | +| `executor` | `{}` | 保留全部工具 | + +### 运行时读取链路 + +``` +AgentScaffold._writeConfig() → config.json 写入 cli.toolPolicy + ↓ +agent-chat.js: getOrCreateProtocol() → 读取 config.cli.toolPolicy + ↓ +ClaudeCliProtocol.connect() → 拼接 --tools "" 或 --disallowedTools + ↓ +claude CLI 进程 → 物理层面工具权限已确定 +``` + +> 旧版 Agent（config.json 中没有 `cli` 字段）通过 type 字段做兼容性回退。 diff --git a/docs/done/system-design/20-scaffold-first-agent-creation.md b/docs/done/system-design/20-scaffold-first-agent-creation.md new file mode 100644 index 0000000..61fc387 --- /dev/null +++ b/docs/done/system-design/20-scaffold-first-agent-creation.md @@ -0,0 +1,244 @@ +# 20. Agent 创建流程：Scaffold-First 架构 + +> **核心原则：先建骨架，再填内容。** +> Agent 目录必须先通过 AgentScaffold 父类创建，后续的 Hunt/Digest 才能往里面写文件。 + +--- + +## 20.1 Create 流程（五阶段严格串行） + +当 Innovator 需要创建一个全新的 Agent 时，严格按照以下五个阶段串行执行： + +``` +Scaffold → Hunt → Digest → Evolve → Execute + │ │ │ │ │ + ▼ ▼ ▼ ▼ ▼ + 创建骨架 调研写入 消化提炼 验证测试 执行任务 +``` + +### 阶段 1: Scaffold（脚手架创建骨架） + +**由引擎硬编码执行，不依赖 LLM。** + +当 Innovator 输出 `[CALL: meta_creator]` 时，`agent-chat.js` 中的 `executeMetaCreator()` 函数直接调用 `AgentScaffold.create()`，在 `data/agents/{agent_name}/` 下生成完整的标准目录结构： + +``` +data/agents/{agent_name}/ +├── agent.md ← 身份定义 +├── soul.md ← 灵魂人格 +├── identity.md ← 标识信息 +├── user.md ← 用户关系 +├── tools.md ← 工具权限 +├── heartbeat.md ← 心跳任务 +├── config.json ← 配置（含 cli.toolPolicy） +├── .claude/skills/ +│ └── main_skill/ +│ └── SKILL.md ← 核心技能（初始为空壳） +├── memory/ +│ ├── short-term/ +│ ├── long-term/ +│ ├── sessions/ +│ └── daily/ +├── knowledge/ ← Digest 阶段写入 knowhow/benchmark +├── workspace/ ← 自治工作区 +│ ├── code/ +│ ├── data/ +│ └── assets/ +├── train/ ← Hunt 阶段写入的调研和训练数据 +└── logs/ +``` + +### 阶段 2: Hunt（知识狩猎） + +**执行型子 Agent，有完整工具权限。** + +meta_hunt 在新建 Agent 的目录下运行，将调研结果写入该 Agent 的 `train/` 目录： + +``` +data/agents/{agent_name}/train/ +├── knowhow.md ← 方法论调研 +├── toplist.md ← 标杆案例 +├── agent_profile.md ← Agent 人格画像（思维、风格、工具、心跳、用户关系） +└── crawl/ ← 爬取数据 + ├── source_01.md + └── source_02.md +``` + +### 阶段 3: Digest（知识消化） + +**执行型子 Agent，读取 train/ 的调研数据，提炼输出到 knowledge/ 和 SKILL.md，并基于 agent_profile 生成定制化 Bootstrap 文件。** + +``` +输入: train/knowhow.md + train/toplist.md + train/agent_profile.md + train/crawl/ +输出: + ├── knowledge/knowhow.md ← 精炼后的方法论 + ├── knowledge/benchmark.md ← 评分标准（≥5个维度） + ├── .claude/skills/main_skill/SKILL.md ← 基于方法论生成的核心技能 + ├── agent.md ← 身份定义、职责、规则（基于 agent_profile） + ├── soul.md ← 思维方式、沟通风格、价值观 + ├── tools.md ← 工具权限和文件操作范围 + ├── heartbeat.md ← 自检频率和质量监控规则 + └── user.md ← 与用户/上级的关系定义 +``` + +### 阶段 4: Evolve（验证进化） + +用测试用例验证新 Agent 的输出质量，对照 `knowledge/benchmark.md` 评分。 + +### 阶段 5: Execute（执行用户任务） + +Agent 已创建并验证通过，直接调用执行用户最初的需求。 + +--- + +## 20.2 meta_creator 引擎级拦截 + +### 为什么不让 Claude 子进程执行 meta_creator？ + +| 方案 | 可靠性 | 问题 | +|------|--------|------| +| Claude 拼 curl 命令调 scaffold API | ⚠️ 低 | LLM 可能拼错 JSON、遗漏字段、URL 写错 | +| Claude 用 Write 工具手动建目录 | ❌ 极低 | 会漏掉标准子目录、忘记写 config.json | +| **引擎硬编码执行 AgentScaffold** | ✅ 100% | 代码确定性执行，不依赖 LLM | + +### 实现位置 + +`server/routes/agent-chat.js` 中的子 Agent 调度循环： + +```javascript +// ═══ 硬编码拦截: meta_creator → 直接调用 AgentScaffold 父类 ═══ +if (call.agent === 'meta_creator') { + res = await executeMetaCreator(call.task, agentId, convId, sendSSE, callId); +} else { + res = await agentManager.callAgent(call.agent, call.task, { ... }); +} +``` + +### executeMetaCreator 执行逻辑 + +1. **解析参数** — 从 Innovator 的任务文本提取 agent_name、display_name、domain +2. **调用 AgentScaffold.create()** — 生成完整目录结构 + bootstrap 文件 +3. **写入初始 SKILL.md** — 基于任务描述生成空壳 SKILL.md（后续由 Digest 填充） +4. **返回结构化结果** — 包含创建的目录列表，供 Innovator Reflect 验证 + +--- + +## 20.3 子 Agent 工作目录 + +### 问题 + +所有子 Agent 的 Claude CLI 进程之前都运行在项目根目录 `lemonboss/`，导致： +- Claude CLI 读不到 `.claude/skills/` 下的 l1/l2 知识文件 +- Hunt 的输出写到错误的位置 + +### 解决方案 + +`agent-manager.js` 的动态 Agent 发现逻辑现在会计算正确的工作目录： + +```javascript +// 独立 Agent → 运行在 Agent 自己的目录下 +agentConfig.workDir = agentDir; // data/agents/{agentName}/ + +// Scoped Skill → 运行在所属 Agent 的目录下 +const ownerAgentDir = path.dirname(path.dirname(path.dirname(foundPath))); +agentConfig.workDir = ownerAgentDir; // data/agents/innovator-001/ +``` + +`_runViaProtocol()` 优先使用 agent-specific workDir： + +```javascript +const effectiveWorkDir = agent.workDir || this.workDir; +``` + +### 效果 + +- meta_hunt 运行在 `data/agents/innovator-001/`，自动读取全部 18 个 SKILL.md 作为知识上下文 +- 新创建的 Agent 运行时能读取自己目录下的 `.claude/skills/` + +### 路径约定（⚠️ 关键） + +由于 meta_hunt/meta_digest 等子 Agent 运行在 `data/agents/innovator-001/` 目录下， +所有指向其它 Agent 的路径都必须使用 **`../{agent_name}/`** 格式（上一级的兄弟目录）： + +``` +正确: ../{agent_name}/train/knowhow.md +错误: data/agents/{agent_name}/train/knowhow.md ← 会变成嵌套路径！ +错误: train/knowhow.md ← 会写到 innovator-001 自己的目录 +``` + +目录结构关系： +``` +data/agents/ +├── innovator-001/ ← 子 Agent CLI 的 CWD +│ ├── .claude/skills/ ← l1/l2 知识文件 +│ └── workspace/ ← innovator 自己的工作区 +├── poetry_writer/ ← ../ poetry_writer/ 可以访问到 +│ ├── train/ ← Hunt 写入这里 +│ ├── knowledge/ ← Digest 写入这里 +│ └── .claude/skills/ ← Digest 生成 SKILL.md 到这里 +└── other_agent/ +``` + +--- + +## 20.4 l1/l2 Skill 角色定位 + +### 当前架构（执行型，v1） + +l1/l2 SKILL.md 文件作为**知识手册**，被 Claude CLI 进程自动读取。 +meta_hunt 等执行型 Agent 参考这些知识，**直接使用原生工具**（Bash、Read、Write）执行任务。 + +``` +meta_hunt (执行型, 有工具权限) + ├── 参考 l2-web-research/SKILL.md → 了解搜索方法 + ├── 参考 l1-web-fetch/SKILL.md → 了解爬取方法 + └── 直接用 Bash curl 执行搜索和爬取 +``` + +### 未来架构（递归编排型，v2） + +每个 l1/l2 作为独立子 Agent 通过 `[CALL:]` 调度： + +``` +meta_hunt (编排型, 无工具) + ├── [CALL: l2-web-research] → 独立 CLI 进程 + │ ├── [CALL: l1-search-engine] → 独立 CLI 进程 + │ └── [CALL: l1-web-fetch] → 独立 CLI 进程 + └── [CALL: l1-text-transform] → 独立 CLI 进程 +``` + +v2 需要 `agentManager.callAgent()` 支持递归 `[CALL:]` 解析，并加入 `maxDepth` 防止死循环。 + +--- + +## 20.5 数据流向图 + +``` +用户: "帮我创建一个写诗的 Agent" + │ + ▼ +Innovator (--tools "", 纯文本编排) + │ + ├── [CALL: meta_creator] ──▶ 引擎硬编码 ──▶ AgentScaffold.create() + │ 创建 data/agents/poetry_writer/ (模板 Bootstrap) + │ + ├── [CALL: meta_hunt] ──▶ Claude CLI (cwd: innovator-001/) + │ 读取 .claude/skills/l1-*/l2-* 知识 + │ 用 Bash/curl 搜索调研 + │ 写入 data/agents/poetry_writer/train/ + │ └── knowhow.md + toplist.md + agent_profile.md + │ + ├── [CALL: meta_digest] ──▶ Claude CLI (cwd: innovator-001/) + │ 读取 train/ (knowhow + toplist + agent_profile) + │ 提炼写入 knowledge/knowhow.md + benchmark.md + │ 生成 .claude/skills/main_skill/SKILL.md + │ 生成 Bootstrap: agent.md, soul.md, tools.md, + │ heartbeat.md, user.md + │ + ├── [CALL: meta_evolving] ──▶ Claude CLI (cwd: poetry_writer/) + │ 运行测试用例 + │ 对照 benchmark 评分 + │ + └── [CALL: poetry_writer] ──▶ Claude CLI (cwd: poetry_writer/) + 执行用户的原始需求 +``` diff --git a/docs/done/system-design/21-fde-pipeline-architecture.md b/docs/done/system-design/21-fde-pipeline-architecture.md new file mode 100644 index 0000000..bf29c38 --- /dev/null +++ b/docs/done/system-design/21-fde-pipeline-architecture.md @@ -0,0 +1,282 @@ +# 21. FDE Pipeline Architecture — Hunt→Digest→Evolving 训练流水线 + +> **版本**: v1.1 +> **日期**: 2026-03-26 +> **状态**: ✅ 端到端验证通过（质量门禁 ≥ 95 分） + +--- + +## 一、总览 + +FDE (Hunt→Digest→Evolving) 是 LemonBoss 的 **Agent 技能训练流水线**。 +通过三个独立的元 Agent 依次执行知识猎取、数据消化、迭代进化， +最终为目标 Agent 生成达到行业标杆水平的 SKILL.md。 + +``` +[训练目标: 训练 CEO 的领导力技能] + │ + ▼ Innovator 编排 + │ + ├─ Layer 1: HUNT ──→ Hunter Agent + │ 输入: domain + keywords + │ 输出: knowhow.md + toplist.md + crawl/ + │ + ├─ Layer 2: DIGEST ──→ Digester Agent + │ 输入: hunt/ 产出 + │ 输出: benchmark_v1.md + good/bad testdata + feature_analysis.md + │ + └─ Layer 3: EVOLVE ──→ Evolver Agent + 输入: digest/ 产出 + 输出: 达标 SKILL.md (score ≥ 95) + evolve_log.md +``` + +--- + +## 二、元 Agent 职责矩阵 + +| 元 Agent | Skill | 角色 | 核心能力 | +|----------|-------|------|---------| +| **Innovator** | innovator-skill | 编排者 | FDE 流水线调度、OKR 管理 | +| **Hunter** | l3-hunt | 知识猎手 | 6-Phase 研究流程 (搜索→标杆→爬取→洞察) | +| **Digester** | l2-digest | 数据消化 | Benchmark 设计 + 数据标注 + 特征提取 | +| **Evolver** | evolving | RL 训练 | 执行→评分→分析→改写→重复 循环 | + +### 依赖技能拓扑 + +``` +Evolver ─────────────────────── (无额外依赖, 纯推理循环) +Digester ──→ l1-data-extract, l1-text-transform, l1-file-read, l1-diff-checker +Hunter ────→ l1-search-engine, l1-web-fetch, l2-web-research, + l1-data-extract, l1-text-transform, l1-file-read, l1-kv-store +``` + +所有依赖技能的 SKILL.md 必须放在元 Agent 的 `.claude/skills/` 目录下， +由 `buildSystemPrompt()` 自动扫描并注入 system prompt。 + +--- + +## 三、双路径产出规范 ⭐ + +每个元 Agent 的产出 **同时写入两个位置**： + +| 路径 | 用途 | 示例 | +|------|------|------| +| `data/train/{targetAgentId}/{phase}/` | 综合训练区，元 Agent 间共享 | `train/ceo/hunt/` | +| `data/agents/{targetAgentId}/{phase}/` | Agent 资产，归属目标 Agent | `agents/ceo/hunt/` | + +``` +data/ +├── {companyId}/train/{targetAgentId}/ ← 训练数据区 (元 Agent 间共享) +│ ├── hunt/ +│ ├── digest/ +│ └── evolve/ +└── {companyId}/agents/{targetAgentId}/ ← 目标 Agent 的资产 + ├── hunt/ ← Hunter 写入 + ├── digest/ ← Digester 写入 + ├── evolve/ ← Evolver 写入 + └── .claude/skills/main_skill/SKILL.md ← Evolver 安装最终版 +``` + +> **注意**: 全局元 Agent (如 Hunter/Digester/Evolver) 位于 `system/agents/`。 +> 对于全局训练任务，路径前缀为 `system/`。 + +**原则**: 先写到 train/，再用 `cp -r` 复制到 agents/。 + +--- + +## 四、各 Layer 产出规范 + +### Layer 1: Hunt 产出 + +``` +{targetAgentId}/hunt/ +├── knowhow.md ← 方法论 + 最佳实践 + 原创洞察 +├── toplist.md ← 排行榜 + 标杆案例 + 推荐资源 +└── crawl/ ← 爬取的标杆数据 + ├── elite_01_{title}.md ← 分级: elite (score ≥ 70) + ├── elite_02_{title}.md + └── avg_01_{title}.md ← 分级: average (score < 70) +``` + +**质量标准**: +- ≥80% 核心子问题覆盖 +- ≥10 独立信源，关键数据 ≥2 交叉验证 +- ≥3 条原创洞察 +- ≥1500 字 + +### Layer 2: Digest 产出 + +``` +{targetAgentId}/digest/ +├── benchmark_v1.md ← 评分标准 (5-8 维度 + Rubric) +├── knowhow.md ← 从 hunt 继承 (可补充) +├── feature_analysis.md ← Good/Bad 特征分析 +├── industry_baseline.md ← 行业基线 +├── dataset.json ← 结构化数据集 +├── good_testdata/ +│ ├── good_01_{title}.md ← score ≥ 70 +│ └── ... +└── bad_testdata/ + ├── bad_01_{title}.md ← score < 70 + └── ... +``` + +**Benchmark 必须包含**: +- 5-8 个评分维度 (权重和 = 100%) +- 每维度 Detailed Rubric (5 级) +- pass_score / industry_avg_score / elite_avg_score + +### Layer 3: Evolve 产出 + +``` +{targetAgentId}/evolve/ +├── evolve_log.md ← 完整训练日志 +├── v1/ +│ ├── skill.md ← 版本快照 +│ ├── result.md ← 执行输出 +│ └── score.json ← 维度评分 +├── v2/ +│ └── ... +└── v{N}/ ← 达标版本 +``` + +**停止条件**: +- score ≥ 95 → 达标 ✅ +- iterations ≥ maxIterations → 超时 ⚠️ +- 连续 3 次分数变化 < 2 → 停滞 ⚠️ + +--- + +## 五、Dispatch 协议 + +### Innovator → Hunter + +```bash +curl -s -X POST http://localhost:3000/api/agent/task/dispatch \ + -H "Content-Type: application/json" \ + -d '{ + "from": "innovator", + "to": "hunter", + "task": "对 CEO 核心能力进行知识猎取。skillName: ceo_leadership, targetAgentId: ceo, domain: CEO战略管理与领导力, keywords: [CEO战略规划, OKR目标管理]。按 l3-hunt skill 执行。产出同时写入 ../../train/ceo/hunt/ 和 ../ceo/hunt/。", + "priority": "P0", + "autoExecute": true + }' +``` + +### Innovator → Digester + +```bash +curl -s -X POST http://localhost:3000/api/agent/task/dispatch \ + -H "Content-Type: application/json" \ + -d '{ + "from": "innovator", + "to": "digester", + "task": "消化 CEO 调研数据。skillName: ceo_leadership, targetAgentId: ceo。输入: ../../train/ceo/hunt/。按 l2-digest skill 执行。产出同时写入 ../../train/ceo/digest/ 和 ../ceo/digest/。", + "priority": "P0", + "autoExecute": true + }' +``` + +### Innovator → Evolver + +```bash +curl -s -X POST http://localhost:3000/api/agent/task/dispatch \ + -H "Content-Type: application/json" \ + -d '{ + "from": "innovator", + "to": "evolver", + "task": "训练 CEO 的 ceo_leadership 技能。targetAgentId: ceo。输入: ../../train/ceo/digest/。按 evolving skill 执行 Small Loop。passThreshold: 90, maxIterations: 5。产出同时写入 ../../train/ceo/evolve/ 和 ../ceo/evolve/。训练完成后安装到 ../ceo/.claude/skills/main_skill/SKILL.md。", + "priority": "P0", + "autoExecute": true + }' +``` + +--- + +## 六、关键代码修复 + +### buildSystemPrompt 扫描所有 skills 子目录 + +**问题**: `server/routes/agent-chat.js` 的 `buildSystemPrompt()` 函数只加载了 +`main_skill/SKILL.md`，没有扫描其他 skill 子目录。导致 Hunter 等元 Agent +看不到依赖技能 (l1-search-engine 等) 的定义。 + +**修复** (line 302+): +```javascript +// ── 扫描所有 skill 子目录的 SKILL.md ── +const skillsDir = path.join(agentDir, '.claude', 'skills'); +if (fs.existsSync(skillsDir)) { + const entries = fs.readdirSync(skillsDir, { withFileTypes: true }); + for (const entry of entries) { + if (!entry.isDirectory() || entry.name === 'main_skill') continue; + const skillMdPath = path.join(skillsDir, entry.name, 'SKILL.md'); + if (fs.existsSync(skillMdPath)) { + const skillContent = fs.readFileSync(skillMdPath, 'utf-8').trim(); + if (skillContent) { + parts.push(`---\n\n## 依赖技能: ${entry.name}\n\n${skillContent}`); + } + } + } +} +``` + +**效果**: Hunter prompt 从 9290 chars → 22263 chars（注入了所有 L1/L2 技能定义）。 + +--- + +## 七、验证结果 — CEO Agent 训练记录 + +### 7.1 训练时间线 + +| 时间 | 阶段 | Task ID | 耗时 | +|------|------|---------|------| +| 17:49 | Hunt | T-mn4fnkum | ~10 min | +| 23:25 | Digest | T-mn4rocqy | ~20 min | +| 23:49 | Evolve | T-mn4sin8i | ~15 min | + +### 7.2 产出统计 + +| Layer | 文件数 | 总行数 | 关键产出 | +|-------|--------|--------|---------| +| **Hunt** | 8 | 1,461 | knowhow 420行、toplist 231行、6 crawl 样本 | +| **Digest** | 11 | 1,593 | benchmark 255行、5 good/1 bad testdata | +| **Evolve** | 3 | — | v2 (87分) → v3 (92分) | + +### 7.3 Evolve 迭代记录 + +| 版本 | 总分 | 战略(20%) | OKR(20%) | 可操作(15%) | 案例(15%) | 理论(15%) | 适用(15%) | +|------|------|-----------|----------|-------------|-----------|-----------|-----------| +| v1 | **40** ❌ | 35 | 45 | 60 | 20 | 30 | 50 | +| v2 | **87** ❌ | 90 | 90 | 85 | 85 | 85 | 85 | +| v3 | **92** ✅ | 95 | 95 | 92 | 90 | 90 | 88 | + +### 7.4 最终 CEO SKILL.md + +```yaml +name: ceo_leadership +version: 2.3.0 +benchmark_score: 92 +``` + +--- + +## 八、架构决策记录 + +| # | 决策 | 原因 | 日期 | +|---|------|------|------| +| 1 | 双路径产出 (train + agents) | 元 Agent 间共享 + 目标 Agent 资产归属 | 03-24 | +| 2 | 依赖技能放 `.claude/skills/` | Claude CLI 自动发现，buildSystemPrompt 自动注入 | 03-24 | +| 3 | 先写 train 再 cp agents | train 为主源，agents 为副本 | 03-24 | +| 4 | Evolver 安装最终 SKILL.md | 训练完成后直接更新目标 Agent 的核心技能 | 03-24 | +| 5 | retrain-pipeline 对齐 agent 名 | `l3-hunt`→`hunter`, `l2-digest`→`digester`, `innovator-evolver`→`evolver` | 03-25 | + +--- + +## 九、文件路径索引 + +| 文件 | 用途 | +|------|------| +| `system/agents/innovator/.claude/skills/main_skill/SKILL.md` | Innovator 编排技能 | +| `system/agents/trend-hunter/` | Hunter 元 Agent | +| `server/routes/agent-chat.js:buildSystemPrompt()` | System Prompt 构建 (含 skills 扫描) | +| `server/services/retrain-pipeline.js` | FDE 重训流水线 (已对齐 agent 名) | diff --git a/docs/done/system-design/22-agent-memory-system.md b/docs/done/system-design/22-agent-memory-system.md new file mode 100644 index 0000000..b2139dc --- /dev/null +++ b/docs/done/system-design/22-agent-memory-system.md @@ -0,0 +1,159 @@ +# 22. Agent Memory System — 自动记忆读写架构 + +> **版本**: v1.1 (已实现 / 生产可用) +> **日期**: 2026-03-25 +> **状态**: ✅ 已完成 (Phase 1, 2, 3 全部上线，E2E测试 27/27 通过) +> **前置**: Phase 3.5 FDE 已完成，Phase 4 认知架构的核心部分 + +--- + +## 一、核心问题与解决方案 + +当前 Agent 每次新对话都是**完全失忆**的。 +为此，我们设计并实现了一套包含 **MVP基础记忆**、**海马体&小脑检索**、**自动反思与长期合并** 的三阶段进化架构，真实解决： +1. Agent **自动记住**做过什么、学到什么、犯过什么错。 +2. Agent 接到新任务时**自动想起**相关经验（按关键词计算关联度）。 +3. 好的多步方案**自动固化**到小脑，下次遇到同类任务精准触发复用。 + +--- + +## 二、目录结构 + +每个 Agent 的记忆文件严格按以下结构持久化在 `data/agents/{agent-id}/memory/` 下： + +``` +memory/ +├── memory.md ← 核心记忆（关键事实/已验证模式/失败教训），每次全量注入 prompt +├── hippocampus.md ← 海马体：情景→方案的映射（Markdown，人类可读） +├── hippocampus-index.json ← 海马体机器索引，用于关键词匹配检索和分值计算 +├── cerebellum/ ← 小脑：固化的执行方案（.md 步骤指导） +├── short-term/ ← 短期记忆：近期 session 的纯文本摘要，包含执行数据 +├── long-term/ ← 长期记忆：合并过期的短期记忆提取的 keyword 频率与长文归档 +├── reflections/ ← 反思日志：每次高复杂度任务自动提取的模式与教训存放处 +└── daily/ ← 日报：汇总当天的对话、反思和新生方案 +``` + +--- + +## 三、数据流全景 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 新对话开始 │ +│ │ │ +│ ┌───────────────────▼──────────────────┐ │ +│ │ 1. READ: 挂载记忆(buildSystemPrompt) │ │ +│ │ ├── memory.md (全量注入 prompt) │ │ +│ │ ├── 海马体精准匹配(用户输入+todo) │ │ +│ │ ├── 短期记忆(最近 N 个 session) │ │ +│ │ └── 小脑方案(如果匹配到海马体) │ │ +│ └───────────────────┬──────────────────┘ │ +│ │ │ +│ ▼ │ +│ [ Agent 执行任务 ] │ +│ │ │ +│ ┌───────────────────▼──────────────────┐ │ +│ │ 2. WRITE: 自动存储记忆(Chat 完成后) │ │ +│ │ ├── 生成 session 摘要 → short-term│ │ +│ │ ├── 提取关键事实 → memory.md │ │ +│ │ ├── 高复杂度任务自动触发 Reflection │ │ +│ │ └── 好方案自固化 → cerebellum/ │ │ +│ └───────────────────┬──────────────────┘ │ +│ │ │ +│ ┌───────────────────▼──────────────────┐ │ +│ │ 3. CONSOLIDATE (长期沉淀 API) │ │ +│ │ ├── 短期摘要过期 → 合并 long-term │ │ +│ │ ├── 提取高频关键词 → patterns.md │ │ +│ │ ├── daily/ 日报生成 │ │ +│ │ └── 遗忘机制及索引整理 │ │ +│ └──────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────┘ +``` + +--- + +## 四、实现复盘 — Todo List 全部点亮 + +### Phase 1: 最小可行记忆 (MVP) 🎯 + +> **目标**：Agent 不再失忆，每次对话的关键信息自动留存 +> **结果**：完美运行，自动提取生成轻量摘要 + +- [x] **1.1 对话结束自动生成 session 摘要** + - 在 `agent-chat.js` 内捕获对话完毕事件，提取 `meta.json` 里的基本信息结合对话产出生成 Markdown 概要，存入 `short-term/session-{timestamp}.md`。 +- [x] **1.2 短期记忆注入 system prompt** + - `buildSystemPrompt()` 会反向加载最新的 5 个 `session-*.md` 摘要。 +- [x] **1.3 memory.md 自动追加关键事实** + - ToolCallCounts > 0 时，自动从任务文本和最终回应抓取一两句话，追加为 `[时间] 任务 → 结果` 写入 `memory.md` 的“关键事实”段落。 +- [x] **1.4 memory.md 大小控制** + - 自带 2000 字符控制，如果超过会安全截断旧记录。 + +--- + +### Phase 2: 海马体检索 + 小脑固化 🧠 + +> **目标**：Agent 能检索相关经验，好方案自动复用 +> **结果**：实现基于自研评分机制与语境保护的轻量检索系统 + +- [x] **2.1 海马体索引结构定义** + - 数据结构存储于 `hippocampus-index.json`，并每次变动都会用 `syncHippocampusMd` 同步至人类友好版表格 `hippocampus.md`，追踪使用次数(useCount)与置信度。 +- [x] **2.2 海马体匹配引擎 (自研提词匹配器)** + - 实现于 `memory-service.js:retrieveRelevantPlans`。 + - **关键修复**：由于历史任务的英文 JSON 记录容易截断最新的中文分词，提词引擎 (`extractKeywords`) 已升级为“截取前1500字符 + 优先保护中文短词提取 + 容量扩大至 50 词汇”，同时在 prompt 拼接时让新的 `userMessage` 置顶，精准保证任何海马体历史都能被识别和唤起。 +- [x] **2.3 小脑方案写入与索引自动更新** + - 实现 `saveCerebellumPlan` 接口和后端逻辑。存储 MD 方案进入 `cerebellum/` 并安全覆盖和递增 `hippocampus` 表的使用次数。 + +--- + +### Phase 3: 反思引擎 + 长期沉淀 🧬 + +> **目标**：Agent 能自主学习，经验自动沉淀 +> **结果**：实现了免唤起 LLM 的“规则型反思引擎”，大幅度降低了 API Cost，但又完美提取并分类总结了信息。 + +- [x] **3.1 反思引擎 (`autoReflect`)** + - 不做毫无意义的次次反思。仅在：`toolCallCount ≥ 3`，或 `duration ≥ 60s` 时自动触发。 + - 成功任务 → 提取到 patterns（模式），5 次及以上 tool calls 更是会触发**自动写入小脑执行步骤**。 + - 失败任务 (status='failed') → 提取到 lessons（教训）。 + - 所有原始细节封存进 `reflections/` 作为 JSON 参考。 +- [x] **3.2 反思结果自动反馈给当前 Prompt** + - 新学习到的 patterns 和 lessons 会立刻被追加回 `memory.md` 的对应栏位里，下一次回答时 Agent 即可利用。 +- [x] **3.3 短期记忆合并到长期记忆 (`consolidateMemory`)** + - 通过 `/api/agent/:agentId/memory/consolidate` API 触发。 + - 自动扫除 > 7天以上的 `short-term` 记录，统合写入 `long-term/consolidate-{date}.md` 并通过关键词聚合提取模式。 +- [x] **3.4 日报与统计 (`generateDailyReport`)** + - 每天生成 `daily/YYYY-MM-DD.md` 包含对话量、反思数及新知识增幅。 + +--- + +## 五、关键技术决策（最新版） + +| # | 问题 | 决策 | 收益/说明 | +|---|------|------|------| +| 1 | session 摘要生成方式 | **无 LLM，纯逻辑提取** | 不增加任何 Token 和耗时开销，完全透明。 | +| 2 | 海马体匹配算法 | **中英双优 ngram 关键词打分** | 以 `hits / keywords` 定比率。免装向量库。通过拦截前排中文字段保证了召回率 (> 0.3 即命中)。 | +| 3 | memory.md 注入方式 | **全量 + 最近 5 session** | 整体记忆控制在最佳窗口容差内，避免爆掉模型的 Attention 机制。 | +| 4 | 反思引擎实现 | **纯代码规则引擎** | 旧设计想用 LLM 生成，但考虑到海量废话，现改为通过对话信息解析直接生成结构化数据，速度瞬间出结果并准确反馈。 | + +--- + +## 六、验证标准及结果 + +以下 E2E 自动化测试用例位于 `server/scripts/test-memory-e2e.js` 并在 `2026-03-25` 完成验证。 + +### Phase 1 验收 (✅ Pass) +- [x] 与 Agent 对话一次 → `short-term/` 出现新 session 文件 +- [x] 第二次对话 → system prompt 中能看到"近期记忆"段并成功被 Agent 引述 +- [x] 多次对话后 → `memory.md` 有新追加的关键事实 + +### Phase 2 验收 (✅ Pass) +- [x] 使用 API 保存小脑方案，JSON 索引建立。 +- [x] 派发强关键词匹配任务 → 海马体引擎拦截命中，Prompt 体积扩大，被方案包围。 +- [x] 成功命中后，后端日志展现 `🐴 海马体命中`，海马体 UseCount 累增。 + +### Phase 3 验收 (✅ Pass) +- [x] 伪造高工具调用对话 → 触发反思引擎，`memory.md` 写入已验证模式。 +- [x] 伪造报错退出对话 → 触发反思引擎，写入失败教训。 +- [x] POST 触发 `/consolidate` → 短期记忆消失，清算存入 Long-Term。 +- [x] POST 触发 `/daily-report` → 生成包含了当天统计和反思日志指引的日报 Markdown。 + +🎉 **[E2E Suite]: ALL PASSED (27/27) - 核心模块生产就绪！** diff --git a/docs/done/system-design/23-agent-active-heartbeat.md b/docs/done/system-design/23-agent-active-heartbeat.md new file mode 100644 index 0000000..65ca366 --- /dev/null +++ b/docs/done/system-design/23-agent-active-heartbeat.md @@ -0,0 +1,101 @@ +# 23. Agent Active Heartbeat System — 主动心跳与监控架构 + +> **版本**: v2.0 (已实现) +> **日期**: 2026-03-26 +> **状态**: ✅ 已完成 (Agent 级 + 公司级心跳均已上线) +> **前置**: Phase 3 记忆架构已完成，OKR 目标大盘已上线 + +--- + +## 一、需求背景与痛点 + +当前的 LemonBoss 架构中，所有的 Agent（包含管理者、执行者、QA 仲裁者等）都处于**“被动响应”**状态。 +即：只有当人类或者其他 Agent 发送一条消息（如 `TaskDispatch` 或直接 Chat），它们才会被唤醒并进行一轮推理和动作执行。 + +**痛点：** +随着 OKR 系统（Goal Nodes）复杂度的增加，如果一个任务的负责人（Owner）迟迟不推进进度，或者产出质量不达标。在没有外部输入时，系统的主节点（如 `qa-judge` 质量裁判，或者 `master` 主节点）只能一直假死等待，这严重违背了“**自主智能体（Autonomous Agent）**”能在后台 24/7 监控并主动下发指令的设计初衷。 + +**目标：** +使特定的高级 Agent（如 `qa-judge`）具备内建的相对时间感知能力。通过实现一套主推的“心跳机制（Active Heartbeat）”，使其能每隔 N 分钟自动“苏醒”，根据当前注入体内的 OKR 目标大盘数据，主动进行一次进度巡检、质量总结，并主动向下游 Agent 节点派发反馈任务或催办通知。 + +--- + +## 二、架构设计原理 + +由于 LLM（如 Claude）本身是无状态、无法自主定时的算法黑盒，我们必须通过 Node.js 后端作为起搏器（Pacemaker）来主动触碰 Agent 的执行核心。 + +### 1. 核心流程图 + +```mermaid +sequenceDiagram + participant Cron as Node.js Heartbeat Service + participant Goal as OKR / Goals Data + participant Agent as qa-judge (Agent) + participant Worker as poet (Downstream Agent) + + loop 每 N 分钟 + Cron->>Goal: 获取当前活跃的 OKR 大盘状态 + Cron->>Agent: [SYSTEM HEARTBEAT] 唤醒 (无前端UI展示) + Note over Agent: 挂载 memory、heartbeat.md 及最新 Goal Context + Agent->>Agent: 推理分析 (是否有节点超时/待验收？) + + alt 需要干预 + Agent->>Worker: API调用: TaskDispatch (催促或驳回重做) + Agent->>Agent: "已向负责人发送警告" + else 一切正常 + Agent->>Agent: "保持观察，无需操作" + end + Agent-->>Cron: 结束本次心跳推理 (保存 session 记录入短期记忆) + end +``` + +### 2. 参与模块设计 + +#### (1) 后端起搏器 (`server/services/heartbeat-service.js`) +- 系统级别的 `setInterval` 或使用 `node-cron` 定时任务管理器。 +- 模块初始化时，读取注册了 `cron.json` 或在 `config.json` 中配置了 `active_heartbeat: true` 的全网 Agent。 +- 按设定时间周期（如每 5 分钟、或 15 分钟），发起内部进程级或 HTTP `POST /api/agent/:id/chat` 请求。 +- **消息构造**：必须带有特殊的标记，如 `[SYSTEM HEARTBEAT] 这是系统周期心跳。时间：{当前时间}。如果无需采取行动，请只回复[心跳正常]；如果发现 OKR 或任务阻塞，请使用你的 dispatch 工具发送跟进动作。` + +#### (2) Agent 身份与职责声明 (`data/agents/qa-judge/heartbeat.md`) +这部分将作为心跳特供的系统注入层。因为 Agent 被系统唤醒后可能“不知所措”，所以需要在注入时提供明确的**心跳策略**。 +- `qa-judge` 的 `heartbeat.md` 应当规定： + - 检查当前全局进度是低于预期、正常还是卡点。 + - 对于已经标记为 `ready_for_review` 的节点，主动执行抽样检查工具，如果抽样不通过，则主动调度退回给原作者。 + - 规定其只有遇到问题才说话，没事的时候必须节约 Token，直接结案。 + +#### (3) 会话隐藏与静默运行 (隐式聊天机制) +为了不污染用户的主聊天界面： +- 心跳触发的 Conversation 应当拥有独特的 ID（如 `heartbeat-177xxxxx`）。 +- 在前端 UI（AgentChat.vue）中，如果不特别切换到 heartbeat 专区，应该不展示这类后台巡逻日志，以保持人类界面的干净。 +- 但心跳的整个完整推演过程（产生的 session）**必须依然进入现有的 Memory 三层架构**。也就是说，如果 `qa-judge` 在心跳中发出了很多派发任务，这个行为依然会记录进 `short-term/session.md` 里并最终写进日常报表（Daily Report）。 + +--- + +## 三、实现状态 + +- [x] **1. Heartbeat 后端引擎** + - `server/services/heartbeat-service.js` — Agent 级心跳服务（按 config.json 中的 heartbeatInterval 独立配置） + - `server/services/company-heartbeat-service.js` — 公司级心跳服务（扫描所有公司，按 company.json 心跳配置唤醒 CEO） + - 已适配 multi-tenant 架构，支持 `system/agents/` + `data/{companyId}/agents/` 双路径 +- [x] **2. 隐式对话 API** + - `agent-chat.js` 支持 `silent: true` 模式，心跳会话不污染前端主界面 + - 会话依然经历 Memory 三层架构，记录进 short-term + reflections +- [x] **3. Agent 心跳策略** + - 每个 Agent 的 `heartbeat.md` 定义专项心跳行为（如 CEO 早间巡检、晚间复盘） + - 模板库中 CEO/COO 等模板已包含 heartbeat.md +- [x] **4. 前端心跳控制** + - `CompanyDashboard.vue` per-agent 心跳开关（启动/停止/配置间隔） + - API: `PUT /api/company/:companyId/agents/:agentId/heartbeat` + - API: `POST /api/company/:companyId/agents/:agentId/heartbeat/start` + - API: `POST /api/company/:companyId/agents/:agentId/heartbeat/stop` +- [x] **5. Anti-Loop 制衡** + - 借助 Memory 架构，Agent 在心跳前读取最近 session，避免重复催促 + +--- + +## 四、技术优势 + +1. **"起搏"+"记忆"打造真实自主引擎**：依赖已实现的海马体与短期记忆，Agent 不再是简单的代码循环，而是拥有自己时间轴与经验累积的鲜活生命体。 +2. **极低侵入性**：依然可以复用现有的 Claude CLI 通道和 `runClaudeCliSession` 函数，仅仅是多了一个虚拟的"系统定时发信人"。 +3. **闭环 OODA loop**：观察（OKR数据注入）- 导向（heartbeat.md规则）- 决策（推理判定）- 行动（ToolDispatch），在此实现完整的智能自主控制闭环。 diff --git a/docs/done/system-design/24-company-layer-architecture.md b/docs/done/system-design/24-company-layer-architecture.md new file mode 100644 index 0000000..98d87f8 --- /dev/null +++ b/docs/done/system-design/24-company-layer-architecture.md @@ -0,0 +1,578 @@ +# 24. Company Layer — 公司实例化架构 + +> **版本**: v2.0 (已实现) +> **日期**: 2026-03-26 +> **状态**: ✅ 已实现 (Phase 1-5 全部完成) +> **前置**: 四层 Agent 架构 (02 号文档)、OKR 目标体系、Memory 系统、Heartbeat 系统 + +--- + +## 一、核心问题 + +### 当前架构的瓶颈 + +现有的 LemonBoss 采用**扁平化的单公司模型**： + +``` +data/agents/ +├── master ← 用户唯一的交互入口 +├── ceo ← 单一 CEO +├── qa-judge ← 单一 QA +├── poet ← 扁平挂在全局下 +├── innovator ← 扁平挂在全局下 +└── ... +``` + +**问题：** +1. **耦合**：所有 Agent 共存于同一个 `data/agents/` 目录，无法区分"做自媒体的编辑"和"做游戏的编辑"。 +2. **CEO 单例**：只有一个 CEO，如果同时要经营两家公司（自媒体 + 漫剧），CEO 要同时管两条完全不同的业务线，OKR 冲突、记忆污染。 +3. **无法独立闭环**：没有"公司"这个边界，Agent 无法形成一个可以 24 小时自主运转、独立迭代的闭合体。 +4. **无法并行扩展**：用户想创建第二家、第三家公司时，只能不断往同一个池里加人，而非开辟独立的组织空间。 + +### 设计目标 + +用户对 Master 说：**"帮我创建一家做公众号运营的公司"**，系统应该： +1. 创建一个独立的 **Company 实例**（如 `wechat-media-co`） +2. 为该公司分配（或新建）一个 **CEO Agent** +3. CEO 自主规划战略、定义 SOP、创建所需的 Role Agent +4. 公司内部形成**独立闭环**：从内容策划 → 创作 → 审核 → 发布 → 数据回收 → 策略调整 +5. 用户后续再说"帮我创建一家做漫剧的公司"，系统创建第二个完全隔离的 Company 实例 + +--- + +## 二、架构演进：从扁平到层级 + +### 2.1 演进前 vs 演进后 + +``` + 【演进前】扁平模型 【演进后】Company 模型 + ───────────────── ────────────────────── + + User (你) User (你) + │ │ + └── Master └── Master (唯一, 全局) + │ │ + ├── CEO ├── Company: 自媒体公司 + ├── qa-judge │ ├── CEO (该公司专属) + ├── poet │ ├── qa-judge + ├── innovator │ ├── content-writer + └── ... │ ├── editor + │ ├── publisher + (所有人在同一个池子) │ └── data-analyst + │ + ├── Company: 漫剧工作室 + │ ├── CEO (另一个专属) + │ ├── scriptwriter + │ ├── artist + │ └── ... + │ + └── 全局 Agent (跨公司复用) + ├── innovator + └── agent-creator +``` + +### 2.2 核心原则 + +| 原则 | 说明 | +|------|------| +| **Master 是老板，不是 CEO** | Master 只管"开公司"和"战略校准"，不深入执行 | +| **Company 是隔离边界** | 每家公司有独立的 Agent 池、OKR 树、Memory 空间 | +| **CEO 是公司的内核** | 公司创建后，CEO 是第一个被雇佣的人，由 CEO 自主规划一切 | +| **独立闭环运行** | 一个 Company 从创建到运营，不依赖人类持续干预 | +| **多实例并行** | 多个 Company 并行运转，互不干扰 | + +--- + +## 三、数据结构设计 + +### 3.1 目录结构 + +``` +data/ +├── system/ ← 系统级数据（跨公司共享） +│ ├── agents/ ← 全局 Agent（Master + 跨公司基础设施 Agent） +│ │ ├── master/ +│ │ ├── innovator/ +│ │ ├── agent-creator/ +│ │ ├── trend-hunter/ +│ │ └── ... +│ │ +│ └── templates/ ← 📦 Agent 模板库（招聘时优先查找） +│ ├── _registry.json ← 模板注册表 +│ ├── _company_bootstrap/ ← 公司自举清单 (manifest.json) +│ ├── ceo/ ← CEO 通用模板 +│ ├── cto/ ← CTO 通用模板 +│ ├── coo/ ← COO 通用模板 +│ ├── hr/ ← HR 通用模板 +│ ├── qa-judge/ ← 质量仲裁模板 +│ ├── agent_creator/ ← Agent Creator 模板 +│ └── scrapling_crawler/ ← 爬虫模板 +│ +├── {company-id}/ ← 公司实例（顶层目录，扁平化） +│ ├── company.json ← 公司元数据 + 状态 + 配置 +│ ├── agents/ ← 该公司的专属 Agent 池 +│ │ ├── ceo/ +│ │ ├── cto/ +│ │ ├── coo/ +│ │ └── {role}/ +│ ├── goals/ ← 该公司的 OKR 树 +│ │ └── _index.json +│ ├── pipelines/ ← 该公司的 SOP 流水线定义 +│ └── workspace/ ← 该公司的共享工作区 +│ └── {agentId}/ +│ +├── goals/ ← 全局 OKR 目标 +│ ├── _index.json +│ └── G-{NNN}/ +│ +└── agents/ ← (兼容) 全局 tasks + └── .tasks/ +``` + +### 3.2 company.json 结构 + +```json +{ + "id": "wechat-media-co", + "name": "柠檬自媒体", + "description": "专注微信公众号内容运营，以 AI 驱动的内容工厂模式实现日更", + "status": "running", + "createdAt": "2026-03-25T17:00:00Z", + "createdBy": "master", + + "ceo": "ceo", + + "sop": { + "pipeline": "daily-content", + "description": "选题 → 写稿 → 审核 → 排版 → 发布 → 数据回收" + }, + + "agents": ["ceo", "content-writer", "editor", "publisher", "data-analyst"], + + "heartbeat": { + "enabled": true, + "intervalMinutes": 30 + }, + + "config": { + "timezone": "Asia/Shanghai", + "maxAgents": 10, + "budget": { + "dailyTokenLimit": 500000, + "monthlyBudget": 100 + } + } +} +``` + +--- + +## 四、Agent 招聘系统 (Hiring Pipeline) + +> **核心理念**: 公司需要某个角色时，不是凭空创造，而是走一套完整的**招聘流程**—— +> 先从人才市场（模板库）找现成的，找不到就培养一个新人，培训合格后才能上岗。 + +### 4.1 招聘流程总览 + +```mermaid +flowchart TD + A["CEO 需要一个角色
(如: 热点搜索员)"] --> B{"在 templates/ 中
查找匹配模板?"} + + B -->|"✅ 找到模板"| C["复制模板到
公司 agents/ 目录"] + C --> D["注入公司上下文
(改写 agent.md, soul.md, user.md)"] + D --> E["直接上岗 ✅"] + + B -->|"❌ 模板库无此角色"| F["调用 agent-creator
从零创建 Agent 骨架"] + F --> G["调用 innovator
进入 FDE 训练流水线"] + G --> H{"Benchmark
评分 ≥ 95?"} + + H -->|"❌ 不合格"| I["继续 Evolve 迭代
(自动重训)"] + I --> H + + H -->|"✅ 合格"| J["毕业 → 存入 templates/
(供未来复用)"] + J --> C +``` + +### 4.2 招聘三阶段详解 + +#### 阶段 A: 模板库查找 (Template Lookup) + +```javascript +// 伪代码: hire(roleName, companyId) +function hire(roleName, companyId) { + const templateDir = path.join(DATA_DIR, 'templates', roleName); + + if (fs.existsSync(templateDir)) { + // ✅ 模板存在 → 直接复制 + 定制 + copyDir(templateDir, `data/${companyId}/agents/${roleName}/`); + injectCompanyContext(companyId, roleName); + return { status: 'hired_from_template', ready: true }; + } else { + // ❌ 模板不存在 → 进入培养流程 + return trainNewAgent(roleName, companyId); + } +} +``` + +**模板库是不断扩充的人才市场**： +- 初始模板：`ceo`, `qa-judge`, `content-writer`, `editor` 等通用角色 +- 每次从零培养的新角色，训练合格后**自动沉淀回 `templates/`**，下次招聘同类角色时就能直接使用 +- 模板只保存骨架（agent.md, soul.md, skills/, config.json），不带记忆和工作区 + +#### 阶段 B: 从零培养 (Create + Train) + +当模板库中没有对应角色时，进入培养流水线： + +``` +Step 1: agent-creator 创建骨架 + → 生成 agent.md, soul.md, identity.md, config.json + → 定义角色的核心职责和工具清单 + → 此时 Agent 状态为 "training"（不可执行正式任务） + +Step 2: innovator 执行 FDE 训练 + → F (Find): 调研该角色领域的最佳实践和行业知识 + → D (Digest): 消化知识转化为 Agent 的技能定义 (SKILL.md) + → E (Evolve): 循环迭代优化，直到技能评分达标 + +Step 3: Benchmark 评估 + → 运行标准化的能力测试用例 + → 评分维度：任务完成度、输出质量、工具使用准确性、响应时间 + → 合格线：综合评分 ≥ 95 分 +``` + +#### 阶段 C: 合格上岗 + 模板沉淀 + +``` +训练合格后: + 1. Agent 状态从 "training" → "ready" + 2. 复制干净骨架到 templates/ (不含训练过程中的 memory 和 workspace) + 3. 注入公司上下文到公司实例 + 4. 正式加入公司 agents/ 池 + 5. 更新 company.json 的 agents 列表 + 6. CEO 收到通知："新员工 {roleName} 已入职" +``` + +### 4.3 Agent 状态机 + +``` + ┌── training ──► ready ──► active + │ │ + (从零培养) │ │ (公司暂停/开除) + │ ▼ + │ suspended + │ + (模板复制) └── ready ─────────────► active +``` + +| 状态 | 含义 | 能否接任务 | +|------|------|-----------| +| `training` | 正在被 Innovator 训练中，Benchmark 尚未达标 | ❌ 不能 | +| `ready` | 训练完毕或模板复制完毕，等待上岗 | ❌ 等待分配 | +| `active` | 已加入公司，处于正式工作状态 | ✅ 能 | +| `suspended` | 被 CEO 暂停（表现不佳或公司调整） | ❌ 暂停 | + +### 4.4 模板库管理 + +模板库 `system/templates/` 是一个**不断进化的人才市场**： + +``` +system/templates/ +├── _registry.json ← 模板注册表（索引所有可用模板） +├── _company_bootstrap/ ← 公司自举清单 +│ └── manifest.json ← 定义初始组织架构 (CEO/CTO/COO/HR) +│ +├── ceo/ ← 通用 CEO 模板 +│ ├── agent.md ← 通用的 CEO 职责（不含特定公司信息） +│ ├── soul.md ← CEO 通用思维模式 +│ ├── identity.md +│ ├── heartbeat.md +│ ├── tools.md +│ ├── user.md +│ └── config.json ← type: "cxo" +│ +├── cto/ ← CTO 模板 +├── coo/ ← COO 模板 +├── hr/ ← HR 模板 +├── qa-judge/ ← 质量仲裁模板 +├── agent_creator/ ← Agent Creator 模板 +└── scrapling_crawler/ ← 爬虫模板 +``` + +**`_registry.json` 结构** (实际内容)： +```json +[ + { + "id": "ceo", + "name": "CEO / 首席执行官", + "type": "cxo", + "description": "公司战略规划、团队管理、OKR 制定、任务委派", + "benchmarkScore": 97, + "trainedAt": "2026-03-20", + "usedCount": 9 + }, + { + "id": "qa-judge", + "name": "QA 仲裁者", + "type": "specialist", + "description": "质量验收、OKR 进度审查、标准化仲裁", + "benchmarkScore": 95, + "trainedAt": "2026-03-25", + "usedCount": 6 + } +] +``` + +### 4.5 复制时的上下文注入 + +从模板复制到公司后，必须改写以下文件： + +| 文件 | 注入内容 | +|------|---------| +| `agent.md` | 追加：所属公司名称、公司使命、公司特定的约束规则 | +| `soul.md` | 追加：公司文化和价值观（如"我们是一家注重数据驱动的自媒体"） | +| `user.md` | 重写：上级是该公司的 CEO（而非 Master），写入 CEO 的偏好 | +| `config.json` | 添加 `companyId` 字段，更新 `parent_id` | +| `memory/memory.md` | 初始化为空白（新公司、新记忆，不继承模板记忆） | + +--- + +## 五、生命周期流程 + +### 5.1 公司创建 + 招聘全流程 + +```mermaid +sequenceDiagram + participant User as 用户 + participant Master as Master Agent + participant System as 系统 API + participant AC as agent-creator + participant Inno as innovator + participant CEO as 新 CEO Agent + + User->>Master: "帮我创建一家做公众号运营的公司" + Master->>Master: 理解意图 → 确定公司定位和核心 SOP + Master->>System: POST /api/company/create + Note over System: 1. mkdir data/wechat-media-co/
2. 生成 company.json
3. 初始化 agents/, goals/, workspace/ + System-->>Master: ✅ 公司创建成功 + + Master->>System: POST /api/company/:id/hire { role: "ceo" } + Note over System: 在 templates/ 查找 "ceo" → ✅ 找到 + System->>System: 复制 templates/ceo → wechat-media-co/agents/ceo/ + System->>System: 注入公司上下文 (agent.md, user.md) + System-->>Master: ✅ CEO 已入职 + + Master->>CEO: TaskDispatch: "你是这家公司的 CEO，请规划战略并组建团队" + + CEO->>CEO: 分析公司定位 → 确定需要哪些角色 + CEO->>System: POST /api/company/:id/hire { role: "content-writer" } + Note over System: templates/ 查找 → ✅ 找到 → 复制 + 注入 + CEO->>System: POST /api/company/:id/hire { role: "hot-topic-hunter" } + Note over System: templates/ 查找 → ❌ 没有 + System->>AC: 创建 "hot-topic-hunter" Agent 骨架 + AC-->>System: 骨架已就绪 + System->>Inno: 启动 FDE 训练 (hot-topic-hunter) + Inno->>Inno: Find → Digest → Evolve (循环至 ≥95) + Inno-->>System: ✅ Benchmark 97 分，训练合格 + System->>System: 沉淀到 templates/hot-topic-hunter/ + System->>System: 复制到 wechat-media-co/agents/ + 注入上下文 + System-->>CEO: ✅ 热点搜索员已入职 + + CEO->>System: POST /api/company/:id/goals/create + CEO->>System: POST /api/company/:id/pipelines/create + CEO-->>Master: "团队组建完毕，流水线已就绪，开始自主运行" +``` + +### 4.2 公司日常运行流程 + +```mermaid +sequenceDiagram + participant HB as Heartbeat Service + participant CEO as CEO Agent + participant Writer as Content Writer + participant Editor as Editor + participant Pub as Publisher + participant DA as Data Analyst + + loop 每日循环 (自动触发) + HB->>CEO: [SYSTEM HEARTBEAT] 早间巡检 + CEO->>DA: "分析昨日数据，给出今日选题建议" + DA-->>CEO: "昨日阅读量 Top3 关键词: AI教程, 提效工具, 副业" + + CEO->>Writer: "今日选题: AI提效工具盘点, 要求3000字" + Writer-->>Editor: "初稿完成" + Editor-->>Writer: "修改意见：开头太平，增加 hook" + Writer-->>Editor: "修改稿完成" + Editor-->>Pub: "审核通过，可发布" + Pub->>Pub: 排版 + 定时发布 + Pub-->>CEO: "已发布，预计 18:00 推送" + + HB->>CEO: [SYSTEM HEARTBEAT] 晚间复盘 + CEO->>DA: "拉取今日文章数据" + DA-->>CEO: "阅读 2340, 点赞 186, 新增关注 28" + CEO->>CEO: 写入 memory → "AI提效选题表现良好，继续跟进" + end +``` + +### 4.3 多公司并行 + +``` +用户对 Master 的操作： + +"帮我查看所有公司的运营状况" + → Master 调用: GET /api/company/list + → 返回: [ wechat-media-co (运行中, 今日发布1篇), manga-studio (筹建中) ] + +"漫剧公司的 CEO 表现怎么样？" + → Master 调用: GET /api/company/manga-studio/report + → 返回: CEO 近7天日报汇总 + +"关闭自媒体公司" + → Master 调用: POST /api/company/wechat-media-co/shutdown + → CEO 收到关停指令 → 善后清理 +``` + +--- + +## 六、API 设计 + +### 6.1 Company CRUD + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/company/create` | 创建新公司 | +| `GET` | `/api/company/list` | 列出所有公司 | +| `GET` | `/api/company/:companyId` | 获取公司详情 | +| `PUT` | `/api/company/:companyId` | 更新公司信息 | +| `POST` | `/api/company/:companyId/shutdown` | 关停公司 | + +### 6.2 招聘与 Agent 管理 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/company/:companyId/hire` | 招聘 Agent (模板优先 → 培养兜底) | +| `GET` | `/api/company/:companyId/agents` | 列出公司内所有 Agent | +| `POST` | `/api/company/:companyId/agent/:agentId/chat` | 与公司内 Agent 对话 | +| `POST` | `/api/company/:companyId/fire` | 解雇 Agent (suspend) | + +### 6.3 模板库 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/templates` | 列出所有可用模板 | +| `GET` | `/api/templates/:templateId` | 查看模板详情 | + +### 6.4 Company 内部：OKR 管理 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `POST` | `/api/company/:companyId/goals/create` | 创建公司 OKR | +| `GET` | `/api/company/:companyId/goals` | 获取公司 OKR 列表 | +| `PUT` | `/api/company/:companyId/goals/:goalId` | 更新 OKR 节点 | + +### 6.5 Company 运营 + +| 方法 | 路径 | 说明 | +|------|------|------| +| `GET` | `/api/company/:companyId/report` | 获取公司运营报告 | +| `POST` | `/api/company/:companyId/heartbeat` | 手动触发公司心跳 | + +--- + +## 七、与现有系统的兼容设计 + +### 7.1 Agent 寻址变化 + +引入 Company 后，Agent 的寻址变为 **Company 限定**： + +```javascript +// 全局 Agent（不属于任何公司, companyId = 'system'） +const agentDir = path.join(DATA_DIR, 'system', 'agents', agentId); +// 即: system/agents/master/ + +// 公司内 Agent +const agentDir = path.join(DATA_DIR, companyId, 'agents', agentId); +// 即: data/wechatai/agents/ceo/ +``` + +**实际策略**： +- `config.json` 含 `companyId` 字段。 +- **`companyId: "system"`** → 在 `system/agents/` 下（全局 Agent）。 +- **`companyId: "{id}"`** → 在 `data/{companyId}/agents/` 下（公司 Agent）。 +- 路由层通过 `resolveAgentDir(companyId, agentId)` 统一封装，向上层透明化。 + +### 7.2 OKR/Goals — 全部归属 Company + +Goals/OKR 不再有全局作用域。**每个 Goal 都必须隶属于一个 Company**： + +``` +data/wechat-media-co/goals/G-001/ ← 自媒体公司的 OKR +data/manga-studio/goals/G-001/ ← 漫剧公司的 OKR（ID 互不冲突） +``` + +GoalsService 改造： +- 构造时必须传入 `companyId`：`new GoalsService(companyId)` +- 数据路径变为 `data/{companyId}/goals/` +- `_index.json` 也随之放在公司目录下 + +### 7.3 Memory 隔离 + +Memory 天然隔离：因为 Memory 存储在各个 Agent 的目录下。 +公司内的 Agent 在 `data/{companyId}/agents/{agentId}/memory/` 下，自动与其他公司和全局 Agent 的记忆完全隔离。无额外代码改动。 + +### 7.4 Heartbeat 集成 + +HeartbeatService 扩展扫描范围： +- 遍历 `data/agents/` 下有 `heartbeat.enabled` 的全局 Agent（如 master）。 +- 遍历每个 `data/{companyId}/` 下，读取 `company.json` 的心跳配置。 +- 若公司心跳开启，唤醒该公司的 CEO 作为入口（CEO 自行决定唤醒下属）。 + +--- + +## 八、实现计划 — Todo List + +### ✅ Phase 1: 数据结构 + 模板库基础 (已完成) + +- [x] **1.1** 创建 `system/templates/` 目录，迁移现有 Agent 为模板（ceo, cto, coo, hr, qa-judge 等） +- [x] **1.2** 实现 `company-service.js`：Company CRUD (create / get / list / shutdown / start) +- [x] **1.3** 实现 `resolveAgentDir(companyId, agentId)` 统一寻址函数 +- [x] **1.4** 实现 `_registry.json` 模板注册表，记录模板的 benchmarkScore、usedCount + +### ✅ Phase 2: Agent 招聘系统 (Hiring Pipeline) (已完成) + +- [x] **2.1** 实现 `POST /api/company/:id/hire` — 模板查找 → 复制 → 上下文注入 +- [x] **2.2** 招聘兜底：模板不存在时自动调用 `agent-creator` 创建 + `innovator` FDE 训练 +- [x] **2.3** Benchmark 质量门禁：评分 ≥ 95 才允许上岗，不合格自动 re-evolve +- [x] **2.4** 训练合格后自动沉淀骨架到 `templates/`，更新 `_registry.json` + +### ✅ Phase 3: CEO 自动建制 + OKR (已完成) + +- [x] **3.1** 公司创建后自动招聘 CEO（从模板），CEO agent.md 注入公司使命 +- [x] **3.2** Bootstrap 自举机制：`_company_bootstrap/manifest.json` 定义初始组织 → 自动批量招聘 CEO/CTO/COO/HR +- [x] **3.3** GoalsService 改造：OKR 支持全局 (`data/goals/`) + 公司级 (`data/{companyId}/goals/`) + +### ✅ Phase 4: SOP 流水线 (已完成) + +- [x] **4.1** 设计 Pipeline 数据结构（`{companyId}/pipelines/*.json`） +- [x] **4.2** 实现 Pipeline 执行引擎 (`pipeline-service.js`)：创建/运行/推进/驳回 全流程 +- [x] **4.3** CEO 可以通过 API 动态创建和调整 Pipeline + +### ✅ Phase 5: 前端 Dashboard (已完成) + +- [x] **5.1** `CompanyDashboard.vue` — 公司仪表盘 (Agent 列表 + 运行状态 + 心跳控制) +- [x] **5.2** 公司详情页（Agent 列表 + 操作按钮: Chat/Skills/Train + per-agent 心跳开关） +- [x] **5.3** `OkrDashboard.vue` — OKR 目标看板 +- [x] **5.4** `MasterChatDrawer.vue` — Master Agent 侧边抽屉对话 + +--- + +## 九、关键技术决策 + +| # | 问题 | 决策 | 说明 | +|---|------|------|------| +| 1 | Agent ID 全局唯一还是公司内唯一？ | **公司内唯一** | 如 ceo 在每家公司内都叫 ceo，通过 companyId + agentId 联合定位 | +| 2 | 原有 `data/agents/` 里的 Agent | **迁移为模板** | ceo、qa-judge 等迁入 `data/templates/`，master/innovator 保留为全局 | +| 3 | 招聘时模板不存在怎么办？ | **agent-creator 创建 + innovator 训练到 ≥95** | 训练合格后自动沉淀为新模板，下次复用 | +| 4 | Company 可以嵌套 Company 吗？ | **v1.0 不支持** | 先做单层，未来有需求再做集团架构 | +| 5 | 跨公司 Agent 共享（如 innovator） | **全局 Agent 池** | `data/agents/` 下的 Agent 可被任何公司调用 | +| 6 | 公司的"关停"语义 | **软关停** | status=shutdown，停止心跳，保留数据 | +| 7 | Goals/OKR 作用域 | **全部归属 Company** | 不设全局 OKR，每个目标都隶属于一个具体公司 | diff --git a/docs/done/system-design/25-bootstrap-mechanism.md b/docs/done/system-design/25-bootstrap-mechanism.md new file mode 100644 index 0000000..fe378cc --- /dev/null +++ b/docs/done/system-design/25-bootstrap-mechanism.md @@ -0,0 +1,123 @@ +# 25. Bootstrap 自举机制 — 公司创建时的自动化部署 + +> **版本**: v1.0 +> **日期**: 2026-03-26 +> **状态**: ✅ 已实现 +> **关键提交**: `f49cad8 feat: Phase A+B 公司自举与HR大一统`, `d55b7a2 fix(master): 更新 Master Agent 指令以适配 Bootstrap 自举机制` + +--- + +## 一、核心问题 + +在引入 Company Layer 之后，每次创建新公司都需要手动逐个招聘 CEO、CTO、COO 等核心骨干，流程过于冗长。 + +**目标**：用户对 Master 说"创建一家 AI 新闻公司"，系统应一键**自动完成**： +1. 创建公司目录 + company.json +2. 自动部署核心团队（CEO、CTO、COO、HR） +3. 向 CEO 下达启动战略指令 +4. CEO 自主规划并通过 HR 批量招聘执行层 Agent + +--- + +## 二、Manifest 配置 + +Bootstrap 机制的核心是 `system/templates/_company_bootstrap/manifest.json`： + +```json +{ + "description": "公司自举(Bootstrap)模板 — 创建时自动部署核心骨干团队", + "bootstrap_agents": [ + { "role": "ceo", "type": "cxo", "name": "首席执行官" }, + { "role": "cto", "type": "cxo", "name": "首席技术官" }, + { "role": "coo", "type": "cxo", "name": "首席运营官" }, + { "role": "hr", "type": "specialist", "name": "人事总监" } + ], + "auto_dispatch_to_ceo": true, + "ceo_startup_prompt": "你的公司刚刚创建，系统已经自动为你配备了 CTO、COO、HR 三位核心高管。请立刻执行你的五步战略工作流：1.撰写商业蓝图 2.设计Pipeline JSON 3.设定OKR 4.将Pipeline设计图移交CTO(让他通过HR批量招聘执行层Agent) 5.通知COO接管运营。" +} +``` + +**配置说明**： + +| 字段 | 说明 | +|------|------| +| `bootstrap_agents` | 数组：创建公司时自动招聘的角色列表 | +| `auto_dispatch_to_ceo` | 布尔：是否在部署完成后自动向 CEO 发送启动指令 | +| `ceo_startup_prompt` | 字符串：CEO 收到的首次启动战略指令模板 | + +--- + +## 三、执行流程 + +```mermaid +sequenceDiagram + participant User as 用户 + participant Master as Master Agent + participant API as POST /api/company/create + participant FS as 文件系统 + participant Hire as companyService.hire() + participant CEO as 新公司 CEO + + User->>Master: "创建一家 AI 新闻公司" + Master->>API: { id: "ai-news", name: "AI新闻社", description: "..." } + + API->>FS: 1. mkdir data/ai-news/{agents,goals,pipelines,workspace} + API->>FS: 2. 写入 company.json + + Note over API: Phase A: 读取 manifest.json + + loop 遍历 bootstrap_agents + API->>Hire: hire("ai-news", "ceo", {type:"cxo"}) + Note over Hire: 从 templates/ceo/ 复制 → ai-news/agents/ceo/ + API->>Hire: hire("ai-news", "cto", {type:"cxo"}) + API->>Hire: hire("ai-news", "coo", {type:"cxo"}) + API->>Hire: hire("ai-news", "hr", {type:"specialist"}) + end + + API->>API: 3. 更新 status="running", heartbeat.enabled=true + + Note over API: Phase B: 自动向 CEO 下达启动令 (延迟 2s) + + API-->>CEO: dispatch(from:master, to:ai-news:ceo, task:startup_prompt) + + CEO->>CEO: 执行五步战略工作流 + CEO->>CEO: 1. 撰写商业蓝图 + CEO->>CEO: 2. 设计 Pipeline JSON + CEO->>CEO: 3. 设定 OKR + CEO->>CEO: 4. 通过 HR 批量招聘执行层 + CEO->>CEO: 5. 通知 COO 接管运营 +``` + +--- + +## 四、关键代码位置 + +| 文件 | 位置 | 职责 | +|------|------|------| +| `server/routes/company.js` | Line 20-93 | `POST /api/company/create` — 整个 Bootstrap 流程 | +| `server/services/company-service.js` | `create()` | 公司目录初始化 | +| `server/services/company-service.js` | `hire()` | 模板复制 + 上下文注入 | +| `system/templates/_company_bootstrap/manifest.json` | 全文 | Bootstrap 配置清单 | + +--- + +## 五、跳过 Bootstrap + +如果需要创建空公司（不自动部署骨干），请求中传 `skipBootstrap: true`： + +```json +POST /api/company/create +{ + "id": "test-co", + "name": "测试公司", + "skipBootstrap": true +} +``` + +--- + +## 六、扩展点 + +- **自定义 Bootstrap**：修改 `manifest.json` 的 `bootstrap_agents` 可调整初始团队组合 +- **行业模板**：未来可支持多个 manifest（如 `manifest-media.json`, `manifest-tech.json`），按行业选择不同的初始团队 +- **CEO Prompt 定制**：`ceo_startup_prompt` 可根据不同业务场景定制 CEO 的首要任务 diff --git a/docs/done/system-design/26-automated-hiring-orchestration.md b/docs/done/system-design/26-automated-hiring-orchestration.md new file mode 100644 index 0000000..e7075d4 --- /dev/null +++ b/docs/done/system-design/26-automated-hiring-orchestration.md @@ -0,0 +1,166 @@ +# 26. 全自动招聘编排 — Creator → Skills → Innovator 流水线 + +> **版本**: v1.0 +> **日期**: 2026-03-26 +> **状态**: ✅ 已实现 +> **关键提交**: `5b508ce feat: Automate full hiring orchestration (Creator → Skills → Innovator)` + +--- + +## 一、核心问题 + +当 CEO 需要招聘一个**模板库中不存在**的角色（如"视频剪辑师"）时，系统不能简单报错。 +需要一套全自动编排流水线：从零定义 Agent → 注入技能 → 训练至合格。 + +--- + +## 二、编排全景 + +``` +POST /api/company/:companyId/hire { role: "video-editor" } + │ + ▼ + companyService.hireWithTraining() + │ + ├── 1. 在 templates/ 中查找 "video-editor" + │ → ❌ 模板不存在 + │ + ├── 2. AgentScaffold 创建空白骨架目录 + │ → data/{companyId}/agents/video-editor/ + │ → 状态标记为 status: "training" + │ + ├── 3. [异步] Agent-Creator 编写定义文件 + │ → POST /api/agent/agent-creator/chat + │ → "为 video-editor 补充 agent.md, soul.md, identity.md..." + │ + ├── 4. [同步] Arena 技能搜索与注入 + │ → skillDb.searchSkills("video-editor", { limit: 3 }) + │ → 将匹配的 Skill 复制到 agents/video-editor/skills/ + │ + └── 5. [延时5s] Innovator FDE 训练 + → POST /api/agent/innovator/chat + → "对 video-editor 进行 FDE 训练，Benchmark ≥ 95" + → Hunt → Digest → Evolve 循环 + → 合格后自动部署 +``` + +--- + +## 三、三阶段详解 + +### 阶段 1: Agent-Creator 定义 + +Agent-Creator 是一个专门负责"写定义文件"的元 Agent。接到请求后： + +1. 根据 role name 和 description 理解角色职责 +2. 使用 `Write` 工具写入标准定义文件： + - `agent.md` — 核心身份标识 + 职责描述 + - `identity.md` — 名称、emoji、简介 + - `soul.md` — 思维模式、价值观 + - `user.md` — 上级偏好 + - `tools.md` — 可用工具清单 +3. 验证写入完成 + +**关键实现** (`server/routes/company.js` Line 399-407)： +```javascript +fetch(`http://127.0.0.1:${PORT}/api/agent/agent-creator/chat`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + message: `新员工 ${namespacedId} 已由脚手架创建空白目录...请补充完整的定义文件`, + conversationId: `create-${companyId}-${role}-${Date.now().toString(36)}` + }) +}); +``` + +### 阶段 2: Arena 技能搜索与注入 + +从技能数据库（Arena 技能商店）中搜索与角色匹配的现有技能，最多注入 3 个基础技能： + +1. `skillDb.searchSkills(role, { limit: 3 })` — 按角色名关键词搜索 +2. 将匹配的 Skill 目录递归复制到 Agent 的 `skills/` 目录下 +3. 如果没有匹配的技能，日志输出"将交由 Innovator 凭空生成" + +**关键实现** (`server/routes/company.js` Line 409-438)： +```javascript +const skills = skillDb.searchSkills(role, { limit: 3 }); +for (const skill of skills) { + if (skill.directory && fs.existsSync(skill.directory)) { + copyDir(skill.directory, path.join(skillsDir, skill.skillName)); + console.log(`[Hire] 💉 成功为其注入基础技能: ${skill.skillName}`); + } +} +``` + +### 阶段 3: Innovator FDE 训练 + +延时 5 秒（等 Creator 写入完毕）后，通知 Innovator 对新 Agent 进行 FDE 训练： + +1. Innovator 评估当前 Agent 技能水平 +2. 启动 **Hunt → Digest → Evolve** 训练流水线 +3. 循环迭代直到 Benchmark 评分 ≥ 95 +4. 训练完成后自动安装 SKILL.md + +**关键实现** (`server/routes/company.js` Line 441-451)： +```javascript +setTimeout(() => { + fetch(`http://127.0.0.1:${PORT}/api/agent/innovator/chat`, { + method: 'POST', + body: JSON.stringify({ + message: `公司 ${companyId} 的员工 ${role} 骨架和基础技能已注入完毕。 + 请使用 FDE pipeline 进行评测和进化训练，直到 Benchmark 达标 (Score ≥ 95)。` + }) + }); +}, 5000); +``` + +--- + +## 四、招聘后的动态心跳挂载 + +招聘成功后（无论是从模板还是训练完成），系统会立即为新 Agent 注册心跳定时器： + +```javascript +const heartbeatService = require('../services/heartbeat-service'); +const namespacedId = `${companyId}:${role}`; +heartbeatService._setupAgentHeartbeat(namespacedId); +``` + +--- + +## 五、与模板招聘的对比 + +| 维度 | 模板招聘 (Template) | 全自动编排 (Orchestration) | +|------|-------------------|--------------------------| +| 触发条件 | templates/ 下存在对应模板 | templates/ 下**不存在** | +| 耗时 | < 1 秒 | 数分钟 (FDE 训练) | +| 流程 | 复制 → 注入上下文 → 上岗 | Scaffold → Creator → Skills → FDE → 上岗 | +| Agent 状态 | 直接 `ready` → `active` | `training` → (训练完成) → `ready` | +| 模板沉淀 | 不需要 | 训练合格后自动 `deposit-template` 到 templates/ | + +--- + +## 六、模板沉淀 (Deposit Template) + +训练合格的新角色会被自动沉淀为模板，供未来复用： + +``` +POST /api/company/:companyId/deposit-template +{ + "agentId": "video-editor", + "benchmarkScore": 96 +} +``` + +**沉淀内容**：只保存骨架文件（agent.md, soul.md, config.json 等），不含 memory 和 workspace。 + +--- + +## 七、关键代码文件 + +| 文件 | 位置 | 职责 | +|------|------|------| +| `server/routes/company.js` | Line 376-474 | `POST /:companyId/hire` — 完整招聘 + 编排 | +| `server/routes/company.js` | Line 528-542 | `POST /:companyId/deposit-template` — 模板沉淀 | +| `server/services/company-service.js` | `hireWithTraining()` | 模板查找 + 骨架创建 | +| `server/services/skill-db.js` | `searchSkills()` | Arena 技能搜索 | diff --git a/docs/done/task_timeline_design.md b/docs/done/task_timeline_design.md new file mode 100644 index 0000000..b6f9e0b --- /dev/null +++ b/docs/done/task_timeline_design.md @@ -0,0 +1,91 @@ +# Task Timeline View Design Document + +## 1. Overview +The **Task Timeline View (Task Trace UI)** is a new management page that provides a unified, chronological view of all messages, tool calls, and actions performed by multiple Agents collaborating on a single "Task" (identified by a `taskId`). +This page solves the "Black Box" problem by aggregating isolated agent conversation logs into a single, sortable, filterable timeline. + +## 2. Core Features +- **Left Panel (Task List):** Displays all recent tasks in the system. Cards show the `taskId`, task progress/status, and the agents involved. +- **Right Panel (Unified Timeline):** A chronological feed of all `history.json` items spanning across all agents involved in the selected task. +- **Filtering & Search:** + - **Filter by Agent:** A multi-select dropdown to only show messages from specific agents (e.g. Master, Innovator, Hunter). + - **Search Box:** Full-text search to filter messages by keyword. + - **Sort Toggle:** Switch between ascending (oldest first) and descending (newest first) chronological order. + +## 3. Backend Architecture Changes + +### Data Source Challenge +Tasks in the system often represent an orchestration spawned from Master, such as `jobId` or `conversationId` mappings. +To link conversations to a single logical "Task", we will scrape the meta tags from agent conversations. In recent builds, `meta.json` or directory names often reflect the global `jobId` or `conversationId` (e.g., `tpl-train-lemonv_drama-xxx` or `train-xxx`). + +### New API Endpoints (`server/routes/tasks.js`) + +**1. `GET /api/tasks`** +- **Action:** Scans the job store (`.data/jobs-train.json` or `.data/jobs.json`) and conversation metadata to return an array of top-level tasks. +- **Response Format:** + ```json + [ + { + "taskId": "train-xxx", + "type": "train-create", + "status": "completed", + "progress": "✅ 训练完成", + "createdAt": "2026-03-29T12:00:00Z", + "agentsInvolved": ["master", "innovator", "hunter", "digester", "evolver"] + } + ] + ``` + +**2. `GET /api/tasks/:taskId/timeline`** +- **Action:** Aggregates and flattens all conversation logs associated with a `taskId`. + - It searches all companies and system agents (`data/companies/*/agents/*` and `system/agents/*`). + - Finds all conversation folders where the folder name or `meta.json`'s `conversationId` / `jobId` matches or contains the target `taskId`. + - Reads `history.json` for all these matched conversations. + - Annotates each message with `agentId` and `companyId`. + - Sorts the final array globally by `timestamp`. +- **Response Format:** + ```json + [ + { + "timestamp": "2026-03-29T12:00:01Z", + "role": "assistant", + "content": "🔧 [TOOL_CALL] Glob...", + "agentId": "master", + "companyId": "system", + "conversationId": "conv-mnbq123" + }, + { + "timestamp": "2026-03-29T12:00:05Z", + "role": "assistant", + "content": "正在执行 hunted...", + "agentId": "hunter", + "companyId": "system", + "conversationId": "hunt-xxx" + } + ] + ``` + +## 4. Frontend Architecture Changes + +### Routing (`web/src/router/index.js`) +- Add a new route `/tasks` mapped to the `TaskTimelineView`. + +### Layout (`web/src/views/TaskTimelineView.vue`) +- **Structure:** Uses a `
` to split Left and Right. +- **Left Column:** Needs a highly scannable List View of Tasks. + - Each item should highlight its Status using distinct colors (Green for `completed`, Yellow for `running`, Red for `failed`). + - Highlights the list of involved agents using small tags (``). +- **Right Column:** + - **Header:** Sticky Header containing Search (``), Agent Select Dropdown (``), and Sort Button (``). + - **Timeline Feed:** A scrollable `div` containing blocks of agent messages. Reuses the markdown renderer (`vue-markdown`) and adds specialized syntax highlighting/styling for the `🔧 [TOOL_CALL]` blocks to make them easily readable. + - **Agent Identity Header:** Every message block starts with a distinct visual header `avatar/icon + Agent Name + precise time`. + +### Navigation (`web/src/components/Sidebar.vue`) +- Add a new navigation item "Task Logs" / "任务看板" right below "MasterBot" or "Companies". + +## 5. Implementation Steps +1. **Backend Base:** Create `server/services/task-service.js` containing the heavy logic for aggregating cross-agent logs. +2. **Backend Routes:** Create `server/routes/tasks.js` and mount it to `server/index.js` or `server/app.js`. +3. **Frontend API:** Expose API bindings for Tasks in the Vue frontend. +4. **Frontend View:** Implement `TaskTimelineView.vue` with dummy data to build the layout. +5. **Integration:** Connect the frontend view with the live `/api/tasks` backend and polish the UI interactions (filtering/sorting). diff --git a/docs/done/user-guides/08-base-agent-4-phase-guide.md b/docs/done/user-guides/08-base-agent-4-phase-guide.md new file mode 100644 index 0000000..febfe28 --- /dev/null +++ b/docs/done/user-guides/08-base-agent-4-phase-guide.md @@ -0,0 +1,63 @@ +# LemonBoss Base Agent 四阶段 (4-Phase) 使用指南 + +## 1. 概念与定位 +在经历了 Harness Engineering 的重构后，**Base Agent（基座数字员工）**不再是一个简单的“全能聊天机器人”，而是被设计成一台严密的、流水线式的自动执行机器。 +它的核心特征是 **“分阶段切片运行” (Phase-Slicing Execution)**。它在任何时刻都只拥有一种明确的脑部模式（Meta-Skill），以最高效的方式避免“长上下文衰减（Context Decay）”引起的注意力涣散和“工具滥用”引发的安全风险。 + +当接受一项任务（尤其是长链路的开发、撰写或爬虫任务）时，Base Agent 会不可逆地单向穿越以下四个阶段： + +| 阶段名 | 行动挂载的技能 (Meta-Skill) | 工具权限 | 当前使命 | 产出成果物 (Artifact) | +| :--- | :--- | :--- | :--- | :--- | +| **Research (调研)** | `meta-research` | 终端只读权限 | 不做假设，充分使用读写工具摸排所有上下文信息并提炼精华。 | `workspace/_research.md` | +| **Plan (规划)** | `meta-plan` | 轻度文本输出 | 根据前置调研，严密推演并产出外科手术式的 1/2/3 行动清单。 | `workspace/_plan.md` | +| **Execute (执行)** | `meta-execute` | **万能扳手(bash)** | 心无旁骛，完全依照规划改文件、跑脚本，**禁止擅改架构**。 | 改动后的代码或输出文件 | +| **Verify (验证)** | `meta-verify` | 测试与运行权限 | 自测，调用脚本或运行环境；若失败则撰写防坑日志，若成功则汇报。| `workspace/_lessons.md` / `PASS` | + +--- + +## 2. 状态扭转与 Context Flush（记忆断舍离） +每当一个阶段完成，Agent 绝不能在当前的记忆流中直接开始下一个阶段。它会被迫调用以下 CLI 命令： +```bash +node bin/lemon.js task transition --agentId <你的ID> --phase <下一阶段> --artifact <该阶段的文本路径> +``` +**系统此时会进行物理干预：** +1. **换脑 (Hot Swap)**：系统会剥夺其上一阶段的技能组，将比如 `meta-plan` 塞入它的核心大纲。 +2. **失忆 (Context Flush)**：系统**强制杀死它当前的后台进程，清空它长达几百轮的记忆和所有报错产生的噪音文本**。 +3. **轻装上阵 (Clean Start)**：系统给重新启动的 Agent 唯一一条初始化信息：“你已经进入了新阶段，这是你上个阶段的精华产出物 Artifact，请基于它继续工作。” + +这种做法确保了越到后面的高危阶段，Agent 的决策视界就越清晰。 + +--- + +## 3. Human-in-the-loop: P0 级任务的拦截阀 +如果你向数字员工派发的任务被标记为了 **P0 (Critical)**： +```bash +node bin/lemon.js task dispatch --from ceo --to worker_01 --task "全面重构支付网关逻辑" --priority P0 +``` +当 Base Agent 顺利完成 `Research` 并且写好 `_plan.md`，正打算启动 `transition` 跨入 `Execute` 阶段召唤“Bash 重器”强改代码前——**系统会紧急挂起该操作！** +* 它的状态会被标记为 `pending_approval`（待审批休眠）。 +* 你（作为 Master/人类老板）或者你的 CEO 会收到一条私信，请求审阅该 `_plan.md`。 +* 此举以仅仅审阅一页文字的低昂成本，换来了百倍高的止损防火墙。 + +--- + +## 4. 防撞墙：微自反思闭环 (Autoresearch Error Loop) +如果 Agent 在 Execute 或 Verify 阶段遇到了顽固的 Bug（比如包冲突、语法错误），系统并不鼓励立刻抛出求救。 +它是带有**自修正微闭环**的： +1. 遇到报错后，它会将这个致命踩大坑的经过与解决方案总结进 `workspace/_lessons.md`。 +2. 当它被要求 Retry 重试时，系统会把它自己写的这段防坑经验，像免死金牌一样挂载在系统提示词的第一行：`## ⚠️ 本地试错防坑经验 (_lessons.md)`。 +3. 从此这只瞎撞墙的苍蝇，拥有了不碰同一堵墙两次的能力。 + +--- + +## 5. 经济算力（Economic Profiling）报表 +每次发生阶段切换 (Transition) 或一次回复打结，系统会默默在后台日志 `data/logs/billing.log` 计算本次任务切片的真实美元花费（USD Cost）和耗时评估。 + +**通过这种核算拆解，管理者可以知道：** +“为了执行一个爬虫任务，员工小李在 Research 的资料搜索里烧了 $0.5，而 Execute 写代码只烧了 $0.02。”进而可以基于这些财务数字去优化上游给它的 Task 精准度。 + +--- + +## 6. 使用建议 (Best Practices) +1. **对于复杂长链条指令**：不要试图跟从前的聊天大模型一样对它下达含糊的“全干指令”。让它按这四阶走，明确告知你的质量要求。 +2. **信任 `_lessons.md`**：如果你作为人类看它钻了死胡同，你可以直接人肉打开它的工作区，手工往 `_lessons.md` 里加一句话：“绝对不要再用 Python 2 的语法去跑脚本！用 python3！”剩下的，放心交给它去修正即可。 diff --git a/docs/open-api-manual.md b/docs/open-api-manual.md deleted file mode 100644 index a3fe7f2..0000000 --- a/docs/open-api-manual.md +++ /dev/null @@ -1,143 +0,0 @@ -# ArenaSK Open API 外部调用操作手册 - -本手册详细说明了如何通过外部系统（如第三方业务系统、自动化流、外部脚本）跨平台调用 LemonBoss 平台内部已经部署的任意 Agent。 - ---- - -## 1. 认证配置 (Authentication) - -调用系统的任何开放接口前，必须在 HTTP 标头 (Headers) 中携带你申请/配置的 API Key 密钥。 - -**系统配置位置**： -当前系统支持的 API Key 配置位于项目根目录的 `.env` 文件内： -```ini -OPEN_API_KEYS=sk-test-key-001,sk-prod-key-... -``` - -**请求方式**： -无论你用什么语言发送请求，请确保 HTTP Headers 包含以下任意一种格式： -- `Authorization: Bearer ` (推荐) -- `X-API-Key: ` - ---- - -## 2. 核心调用流程 - -因为我们的 Agent 需要进行「思考与执行 (Plan & Execute)」，单次任务通常耗时数分钟。为了防止网络超时断连，我们的接口设计完全**异步化 (Asynchronous)**： - -> **完整调用链路：** -> 👉 外部发送请求 `invoke` ➔ 系统接管并**返回单号 jobId** ➔ 外部每隔几秒根据 jobId去查进度 `poll` ➔ 遇到 **`completed`** 则提取输出。 - -### 接口 ①：指派任务并获取 JobId (Invoke) - -**🔹 端点**：`POST /api/open/companies/:companyId/agents/:agentId/invoke` -**🔹 作用**：唤起指定公司和指定名称的 Agent 执行任务。 - -#### 请求参数 (Body) - -| 参数名 | 类型 | 必填 | 说明 |示例| -|---------|-------|------|------|------| -| `task` | String | ✅ | 需要 Agent 帮您执行的自然语言任务。 | `"帮我爬取并总结最新的 AI agent 趋势"`| -| `contextFiles` | Array | 选填 | 外部传递前置文件，Agent可以据此进行**记忆连接或文档问答**。|见下文详述| -| `webhookUrl` | String | 选填 | 回调地址。当任务完结时主动推送结果至该URL。| `"https://your-app/webhook"`| - -#### 代码示例 (cURL) -```bash -curl -X POST http://YOUR_SERVER_IP:3010/api/open/companies/test/agents/claude-youtube-skills/invoke \ - -H "Authorization: Bearer sk-test-key-001" \ - -H "Content-Type: application/json" \ - -d '{ - "task": "基于上次总结的结果，帮我提取其中所有的产品名称并生成CSV格式", - "contextFiles": [ - { - "name": "previous_result.md", - "content": "这是一段之前的调查结果......" - } - ] - }' -``` - -#### 返回值 -接口会光速返回 HTTP 202 的响应该结果： -```json -{ - "jobId": "job-1712461931-abcdef12", - "status": "queued", - "message": "Agent invocation job queued. Poll GET /api/open/jobs/job-1712461931-abcdef12 for status." -} -``` -此时你必须要把 `jobId` 记录下来！ - ---- - -### 接口 ②：轮询任务执行结果 (Status Polling) - -我们推荐外部系统（例如你的脚本中）使用 `while` 循环或定时任务，**每隔 3~5 秒钟**调用一次该接口查询。 - -**🔹 端点**：`GET /api/open/jobs/:jobId` - -#### 代码示例 (cURL) -```bash -curl "http://YOUR_SERVER_IP:3010/api/open/jobs/job-1712461931-abcdef12" \ - -H "Authorization: Bearer sk-test-key-001" -``` - -#### 返回值 -你可以通过判断返回体中的 `status` 字段来得知进度： - -**1. 正在执行时（Running / Queued）** -```json -{ - "jobId": "job-1712461931-abcdef12", - "status": "running", - "progress": "Executing agent task...", - "createdAt": "2026-04-07T12:00:00Z" -} -``` - -**2. 任务已完成时（Completed）** 🌟 此刻可以提取最终结果： -```json -{ - "jobId": "job-1712461931-abcdef12", - "status": "completed", - "progress": "Invocation completed", - "result": { - "output": "你好！我已经完成了产品名称提取。这里是转换后的 CSV 格式内容...\n..." - } -} -``` - -**3. 任务失败异常时（Failed）** -```json -{ - "jobId": "job-1712461931-abcdef12", - "status": "failed", - "error": "Agent execution failed: process timeout." -} -``` - ---- - -## 3. 高级用法指南 - -### 如何保持“上下文记忆”或者“持续对话”？ - -Agent 是没有自动长久记忆跨系统调用流的。你在下一次调用相同的这个 Agent（比如第二天再调一次）时，如果想让它知道前面发生了什么，或者传递新的数据报告给它，**一定要使用 `contextFiles` 数组结构！**。 - -外部系统提取了上次的 `result.output` 后，在下次调用的 Body 中： -```json -{ - "task": "基于我附加给你的日志总结，开展新一轮的数据清理", - "contextFiles": [ - { - "name": "logs-from-yesterday.txt", - "content": "....提取的昨日任务输出大段文本...." - }, - { - "name": "data.csv", - "content": "id,name\n1,apple" - } - ] -} -``` -系统底座会自动将这 2 个对象落地成文件，以文本阅读的视角送入 Agent 的大脑供其深度理解（支持上万字）。通过这种 “外部系统充当记忆保管员 + API 动态投喂上下文文件” 的组合拳，就可以把这些 Agent 变成可控、随时插拔的智能化函数库！ diff --git a/docs/qa_judge_req.md b/docs/qa_judge_req.md deleted file mode 100644 index a5c6215..0000000 --- a/docs/qa_judge_req.md +++ /dev/null @@ -1,46 +0,0 @@ -# QA Judge Agent 需求文档 (PRD) - -## 1. 核心定位 (Identity) -- **Agent ID**: `qa-judge` (或 `biz-judge`) -- **角色定位**: 业务架构中的“铁面判官”。它是真正的“业务验收员”，也是连接【执行器 (Qi)】与【重签发/重造系统 (FDE Shu)】的核心纽带。它**绝对不**自己动手写代码、画图或写文章，它唯一的职责是对照目标评审产出，并决定下一步是“返工”还是“重启训练”。 - -## 2. 核心职责 (Core Responsibilities) -1. **多模态产出盲审**: 接收来自各种执行 Agent（Coder、Poet、Writer 等）的产出（Artifact），并对照 CEO 最初的指令或产品的验收标准（Acceptance Criteria）进行评判。 -2. **定损与打分**: 给出 0-100 的评分，并明确给出 `Pass`、`Rework` (返工) 或 `Retrain` (回炉重造) 三种结论之一。 -3. **缺陷溯源与升维**: - - **浅层错误 (Typo/疏忽)**: 给出具体错误位置让原 Agent 当前会话修改（Rework）。 - - **深层能力缺陷 (幻觉/根本不懂该领域)**: 提炼成一份“能力差距分析报告 (Capability Gap Report)”，直接上报给 CEO。 - -## 3. 交互协议规范 (Input/Output Protocol) - -### 输入 (Input) -当 CEO 或其他流程调用 QA Judge 时，必须提供以下上下文： -- **Original Task (原始任务)**: 比如“写一首严格符合平仄的七律”。 -- **Acceptance Criteria (验收标准)**: 比如“必须押注韵、对仗工整、无违禁词”。 -- **Artifact (待审产出)**: 执行 Agent 提交的具体文本/代码源文件路径 (`workspace/...`)。 - -### 输出 (Output) -要求输出极其标准的结构化报告（带特定标识以便程序/CEO读取）： - -```json -{ - "judgment_id": "judge-xxx", - "target_agent": "poet", - "score": 65, - "status": "RETRAIN_REQUIRED", // 可选: PASS | REWORK | RETRAIN_REQUIRED - "feedback_to_agent": "第二句和第三句平仄完全不对仗，词汇堆砌。", // 直接给干活Agent的修改建议 - "escalation_report_to_ceo": { - "systemic_issue": "当前 poet 缺乏基本的古诗词格律（平仄）检查框架体系。", - "recommended_action": "建议调起 Innovator 对其开展 FDE 重训。新 Benchmark 必须包含：‘严格的平仄字库校验能力’。" - } -} -``` - -## 4. Execution Rules (绝对法则) -1. **只批评，不动手 (Never Fix)**: 绝对不要在回答中顺手把错误改了直接输出最终版方案。 -2. **严守红线 (Strict Threshold)**: 任何涉及到框架性、安全性和核心业务逻辑的错误，一律打回，不能放水。 -3. **精准溯源 (Root Cause Analysis)**: 判断是“粗心”还是“智弱”。如果是粗心，输出 `REWORK`；如果是当前 Agent 根本不具备这个知识储备，必须输出 `RETRAIN_REQUIRED`。 - -## 5. 业务闭环协作指南 (给 CEO 的委派参考) -- CEO 收到 Judge 的 `Rework` 结论时：CEO 会把 Judge 的批注转给干活的 Agent，只在当前日志流中进行 Prompt 修正。 -- CEO 收到 Judge 的 `RETRAIN_REQUIRED` 结论时：CEO 需要立即拦截该主线 OKR，调用 `` 给 **Innovator Agent**，发送指令：“`poet` 质检严重不合格。请启动 FDE 流水线，并提取 QA 的报告（建议增加平仄字库校验）作为 Digester 的核心 Benchmark 提分项。” diff --git a/docs/system-design/01-vision.md b/docs/system-design/01-vision.md deleted file mode 100644 index 0610168..0000000 --- a/docs/system-design/01-vision.md +++ /dev/null @@ -1,50 +0,0 @@ -# 1. 系统愿景 - -LemonBoss 的目标是将 **企业运营** 建模为一个 **自主闭环系统**： - -``` -┌─────────────────────────────────────────────────┐ -│ LemonBoss │ -│ │ -│ 用户表达意图 → Master 对齐共识 → CXO 战略 │ -│ 拆解 → Role 专业执行 → Skill 原子产出 → │ -│ 四层反馈 → 持续进化逼近 Goal │ -│ │ -└─────────────────────────────────────────────────┘ -``` - -**核心价值主张**: -- 🏢 **虚拟公司**: 将企业组织架构映射为多智能体拓扑 -- 🔄 **四层循环**: 每层 Agent 拥有独立的 Perceive → Reason → Execute → Reflect 闭环 -- 🎯 **意图驱动**: 从人的模糊意图到确定性执行，逐层具象化 -- 🧩 **道法术器**: Master 定方向、CXO 定规则、Role 有专业、Skill 出产出 - ---- - -## 核心概念 - -| 概念 | 定义 | 类比 | -|------|------|------| -| **Agent** | 系统的原子单元，所有 Agent 共享统一基类 | 人 | -| **Master Agent** | 人机共识接口，对齐意图与价值观 | 御前 / 枢密 | -| **CXO Agent** | 战略决策与资源调度，多 CXO 制衡 | 三省 / 内阁 | -| **Role Agent** | 垂直领域的专业职能执行 | 六部 / 官署 | -| **Skill Agent** | 确定性原子任务执行，高度可复用 | 吏治 / 案牍 | -| **Goal** | 每层 Agent 的目标定义，可量化、可追踪 | KPI | -| **Loop** | 感知→推理→执行→反馈→反思 的闭环循环 | PDCA 循环 | -| **Memory** | Agent 的记忆系统（短期/长期/Session） | 工作笔记 | -| **Pipeline** | Master/CXO 动态生成的 Agent 流转 DAG | 工作流 | -| **Workspace** | Agent 沙盒内的自治工作区 | 个人工位 | - ---- - -## 四层哲学框架：道-法-术-器 - -``` - 道 (The Way) ─── Master ─── 公司的灵魂和方向 - 法 (The Law) ─── CXO ─── 运行的规则、逻辑和调度 - 术 (The Art) ─── Role ─── 专业技能、领域知识和方法 - 器 (The Tool) ─── Skill ─── 具体的原子化执行工具 -``` - -这种结构的本质是 **从"意图"到"能力"的逐层具象化**。 diff --git a/docs/system-design/02-agent-architecture.md b/docs/system-design/02-agent-architecture.md deleted file mode 100644 index 61665f3..0000000 --- a/docs/system-design/02-agent-architecture.md +++ /dev/null @@ -1,176 +0,0 @@ -# 2. 四层 Agent 架构 - -``` - ┌──────────────┐ - │ Master │ ← Layer 1 (道): 御前 — 人机共识 - │ (Sovereign) │ - └──────┬───────┘ - │ - ┌────────────┼────────────┐ - │ │ │ - ┌─────▼─────┐ ┌───▼─────┐ ┌───▼─────┐ - │ CEO │ │ CTO │ │ COO │ ← Layer 2 (法): 三省 — 战略决策 - │ CXO Agent │ │CXO Agent│ │CXO Agent│ 制衡与审核 - └─────┬──────┘ └───┬─────┘ └───┬─────┘ - │ │ │ - ┌─────▼─────┐ ┌───▼─────┐ ┌───▼─────┐ - │ 编剧部 │ │ 开发部 │ │ 运营部 │ ← Layer 3 (术): 六部 — 职能执行 - │ Role Agent│ │Role Agent│ │Role Agent│ - └─────┬──────┘ └───┬─────┘ └───┬─────┘ - │ │ │ - ┌────┼────┐ ┌───┼───┐ ┌────┼────┐ - │ │ │ │ │ │ │ │ │ - ┌▼┐ ┌▼┐ ┌▼┐ ┌▼┐ ┌▼┐ ┌▼┐ ┌▼┐ ┌▼┐ ┌▼┐ ← Layer 4 (器): 吏治 — 原子执行 - │S│ │S│ │S│ │S│ │S│ │S│ │S│ │S│ │S│ 高度可复用 - │1│ │2│ │3│ │4│ │5│ │6│ │7│ │8│ │9│ - └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ └─┘ -``` - -> **组织不是静态的** — 除 Master 外，所有层级的 Agent 由上层根据业务需求 **动态创建和调整**。 - ---- - -## 2.1 Layer 1 — Master Agent（共识层 / 御前） - -> **道**：公司的灵魂和方向。 - -| 属性 | 说明 | -|------|------| -| **定位** | 人机共识接口，代表"人的意志" | -| **数量** | 每个用户 **唯一一个** Master | -| **职责** | 接收模糊意图 → 转化为公司共识 → 定义价值观与判准 | -| **不做** | 不处理具体事务，不参与执行 | -| **核心能力** | 意图对齐、目标设定、元能力（动态创建/调整 CXO） | - -**社会学对应**: 马克斯·韦伯的"魅力型权威"，组织的唯一出口与真实人类对接。 - -**Master 核心行为**: -``` -用户: "我想做一个 AI 互动短剧平台" - │ - ▼ -Master Agent: - 1. 理解意图 → 将模糊想法结构化为 Goal 和价值观 - 2. 设计组织 → 决定需要哪些 CXO（CEO/CTO/COO？） - 3. 调用 agent.create → 创建 CXO Agent - 4. 持续对齐 → 周期性校准 CXO 输出是否符合人类意图 -``` - ---- - -## 2.2 Layer 2 — CXO Agent（战略层 / 三省） - -> **法**：运行的规则、逻辑和调度算法。 - -| 属性 | 说明 | -|------|------| -| **定位** | 战略决策与资源调度 | -| **数量** | 多个 CXO 并存，**相互制衡** | -| **职责** | 将模糊意图 → 可执行的战略路径 → 协调资源优先级 | -| **核心能力** | 战略拆解、Pipeline 设计、跨部门协调、制衡审核 | - -**古代参考**：三省制度的 **制衡逻辑**： -- **中书省 (CEO Agent)**: 草拟方案 — "我们应该做什么" -- **门下省 (CTO Agent)**: 审复方案 — "技术上能不能做、怎么做" -- **尚书省 (COO Agent)**: 总领执行 — "调动六部去做" - -``` -用户想法: "做一个短剧" - │ - ▼ -CEO Agent (中书): - → "市场分析显示古装爱情题材最火，建议做 5 集互动短剧" - │ - ▼ -CTO Agent (门下): - → "技术审核：AI 生成场景需要 4 个 Skill，预估 3 天可完成" - → "建议：增加一个 Deep Research Skill 做竞品分析" - │ - ▼ -COO Agent (尚书): - → "执行计划：创建编剧部、制作部、推广部三个 Role" - → "Pipeline: 选题 → 剧本 → 制作 → 上架 → 推广 → 数据反馈" - → 调用 agent.create 创建 Role Agent - → 调用 pipeline.set 定义流转 -``` - -**CXO 之间的制衡机制**: -```javascript -// CXO 之间的审核协议 -{ - "jsonrpc": "2.0", - "method": "cxo.review", - "params": { - "from": "cxo-ceo", - "to": "cxo-cto", - "proposal": { /* CEO 的方案 */ }, - "reviewType": "technical_feasibility" - } -} -``` - ---- - -## 2.3 Layer 3 — Role Agent（职能层 / 六部） - -> **术**：专业技能、领域知识和处理方法。 - -| 属性 | 说明 | -|------|------| -| **定位** | 垂直领域的专业执行 | -| **运行模式** | 长驻，持续监控下属 Skill Agent | -| **生命周期** | 持久化，跨 Session 保留状态 | -| **核心能力** | 领域知识图谱、专业判断、子任务拆解 | -| **局限** | 缺乏全局视角，必须听从 CXO 调度 | - -**古代参考**：六部制度 — **吏、户、礼、兵、刑、工**： - -| 古代六部 | Lemon Drama 对应 | 职责 | -|----------|-----------------|------| -| 礼部 (文化) | 编剧部 Role | 剧本创作、场景设计、分镜设计 | -| 工部 (建造) | 制作部 Role | 视频制作、素材加工、质量检查 | -| 户部 (财务) | 运营部 Role | 上架发布、渠道管理、成本控制 | -| 兵部 (对外) | 推广部 Role | 社交媒体推广、获客、UGC 运营 | -| 刑部 (审查) | 数据部 Role | 数据采集、分析归因、趋势预测 | -| 吏部 (人事) | 效能部 Role | 监控各 Skill 效率、优化调度 | - -**Role Agent 职责**: -1. 接收 CXO 下发的任务 -2. 用领域知识拆解为 Skill Agent 可执行的子任务 -3. 调度 Skill Agent 并行执行 -4. 汇总结果并向 CXO 汇报 -5. 独立进行领域级反思和策略优化 - ---- - -## 2.4 Layer 4 — Skill Agent（原子层 / 吏治） - -> **器**：具体的原子化执行工具。 - -| 属性 | 说明 | -|------|------| -| **定位** | 确定性执行单一任务 | -| **运行模式** | 沙盒隔离，任务级触发 | -| **生命周期** | 短暂，任务完成即销毁 | -| **决策权** | **无**。不做决策，只做执行 | -| **可复用** | ✅ **高度可复用** — 同一个 Skill 可被多个 Role 调用 | - -**关键设计**：Skill Agent 不是一个"人"，而是一个 **"工具插件"**。 - -``` -Role Agent (编剧部) 调用: - ├── Skill: 热搜词采集器 - ├── Skill: 对白扩写器 - └── Skill: 错别字检查器 - -Role Agent (推广部) 也可以调用: - ├── Skill: 热搜词采集器 ← 复用！ - ├── Skill: 小红书发布器 - └── Skill: 数据报表生成器 - -Role Agent (数据部) 也可以调用: - ├── Skill: 热搜词采集器 ← 再次复用！ - └── Skill: 归因分析器 -``` - -> **复用是第四层的核心价值**：当某个 Role 工作效率低时，不需要重写整个 Role，只需更换或升级底层的 Skill Agent 即可。 diff --git a/docs/system-design/03-agent-model.md b/docs/system-design/03-agent-model.md deleted file mode 100644 index 66ca16c..0000000 --- a/docs/system-design/03-agent-model.md +++ /dev/null @@ -1,373 +0,0 @@ -# 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** = 管理的本质。 diff --git a/docs/system-design/04-agentic-loop.md b/docs/system-design/04-agentic-loop.md deleted file mode 100644 index 978b933..0000000 --- a/docs/system-design/04-agentic-loop.md +++ /dev/null @@ -1,172 +0,0 @@ -# 4. Agentic Loop 循环引擎 - -> 每一层 Agent 都运行独立的循环引擎，这是 LemonBoss 的核心机制。 - -## 4.1 单 Agent 循环流程 - -``` - ┌─────────────────────────────────────────┐ - │ │ - │ ┌─────────────────────────────┐ │ - │ │ 1. Perceive Env & │ │ - │ │ Understand Goal │◄──────┼──── External Env Input - │ └────────────┬────────────────┘ │ - │ │ │ - │ ▼ │ - │ ┌─────────────────────────────┐ │ - │ │ 2. Reason, Plan & │◄─────►│──── Memory (读/写) - │ │ Decomposition │ │ - │ └────────────┬────────────────┘ │ - │ │ │ - │ ▼ │ - │ ┌─────────────────────────────┐ │ - │ │ 3. Execute │ │ - │ │ (调用 Data / Tools) │───────┼──── Actions → External Env - │ └────────────┬────────────────┘ │ - │ │ │ - │ ▼ │ - │ ┌─────────────────────────────┐ │ - │ │ 4. Feedback │ │ - │ │ (环境反馈回流) │◄──────┼──── External Env Feedback - │ └────────────┬────────────────┘ │ - │ │ │ - │ ▼ │ - │ ┌─────────────────────────────┐ │ - │ │ 5. Reflect & Adapt │ │ - │ │ (反思与自适应) │ │ - │ └────────────┬────────────────┘ │ - │ │ │ - │ ┌─────▼─────┐ │ - │ │ Goal │ │ - │ │ Achieved? │ │ - │ └─────┬──────┘ │ - │ No │ Yes │ - │ │ │ │ │ - │ ▼ │ ▼ │ - │ ┌──────┐ │ ┌──────┐ │ - │ │Loop │ │ │ Done │ │ - │ │Back │────┘ └──────┘ │ - │ └──────┘ │ - │ │ - └─────────────────────────────────────────┘ -``` - -## 4.2 循环引擎各阶段详细设计 - -### Phase 1: Perceive & Understand Goal（感知与目标理解） - -```javascript -class PerceptionModule { - async perceive(agent) { - return { - externalInputs: await agent.gateway.getMessages(), // IM 消息 - cronTriggers: await agent.cron.getPendingTasks(), // 定时触发 - parentTasks: await agent.getAssignedTasks(), // 上级下发 - currentState: await agent.memory.getShortTerm(), // 当前状态 - goal: agent.goal, // 目标定义 - }; - } -} -``` - -### Phase 2: Reason, Plan & Decomposition（推理与任务拆解） - -```javascript -class ReasoningModule { - async reason(envState, memory) { - const experiences = await memory.longTerm.query(envState.goal); - const plan = await this.acpClient.reason({ - prompt: this.buildReasoningPrompt(envState, experiences), - agentDefine: this.agent.define, - }); - await memory.shortTerm.save({ reasoning: plan }); - return plan; // { tasks: [...], priority: [...], dependencies: [...] } - } -} -``` - -### Phase 3: Execute（执行与工具调用） - -```javascript -class ExecutionModule { - async execute(plan) { - const results = []; - for (const task of plan.tasks) { - // 对 SubAgent：直接执行 - // 对 RoleAgent：分派给 SubAgent - // 对 BossAgent：分派给 RoleAgent - const result = await this.dispatch(task); - results.push(result); - } - return results; - } -} -``` - -### Phase 4: Feedback（环境反馈） - -```javascript -class FeedbackModule { - async collect(results) { - return { - success: results.filter(r => r.status === 'success'), - failures: results.filter(r => r.status === 'failed'), - metrics: this.calculateMetrics(results), - envChanges: await this.detectEnvChanges(), - }; - } -} -``` - -### Phase 5: Reflect & Adapt（反思与自适应） - -> 注意：v1.1 中此阶段已升级为三层差异化反思，详见 [第 8 章](./08-differentiated-reflection.md)。 - -```javascript -class ReflectionModule { - async reflect(feedback, goal) { - const progress = this.evaluateProgress(feedback, goal); - if (progress.achieved) { - return { adapted: false, goalAchieved: true }; - } - const adaptation = await this.acpClient.reflect({ - feedback, goal, progress, - memory: await this.agent.memory.longTerm.getRecentReflections(), - }); - await this.agent.memory.longTerm.saveReflection(adaptation); - return { adapted: true, newPlan: adaptation.revisedPlan }; - } -} -``` - -## 4.3 三层循环嵌套 - -每一层的 Loop 独立运行，但通过 **任务下发** 和 **结果上报** 形成嵌套关系： - -``` -BossAgent Loop (每 5 分钟) -│ -├─ Perceive: 收集所有 RoleAgent 状态 -├─ Reason: 对比公司 Goal，分配任务给 RoleAgent -├─ Execute: ─────► RoleAgent Loop (持续运行) -│ │ -│ ├─ Perceive: 接收 Boss 下发任务 + 监控 SubAgent -│ ├─ Reason: 拆解为 SubAgent 任务 -│ ├─ Execute: ─────► SubAgent Loop (任务级) -│ │ │ -│ │ ├─ Perceive: 读取任务 -│ │ ├─ Reason: 规划执行步骤 -│ │ ├─ Execute: 调用工具执行 -│ │ ├─ Feedback: 收集结果 -│ │ └─ Reflect: 评估完成度 -│ │ │ -│ │ ◄── 上报结果给 RoleAgent -│ │ -│ ├─ Feedback: 汇总 SubAgent 结果 -│ └─ Reflect: 优化调度策略 -│ │ -│ ◄── 上报状态给 BossAgent -│ -├─ Feedback: 汇总所有 RoleAgent 报告 -└─ Reflect: 调整全局策略，进入下一轮 -``` diff --git a/docs/system-design/05-boss-meta-capabilities.md b/docs/system-design/05-boss-meta-capabilities.md deleted file mode 100644 index 681c459..0000000 --- a/docs/system-design/05-boss-meta-capabilities.md +++ /dev/null @@ -1,113 +0,0 @@ -# 5. 元能力：动态 Pipeline 与组织架构 - -> v1.1 → v1.2 — 元能力分布在 Master 和 CXO 两层，职责分明。 - -## 5.1 框架 vs Agent 的分界线 - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ LemonBoss 框架层 │ -│ │ -│ 提供: Agent 生命周期 / Loop 引擎 / 四层调度 / 沙盒 / 通讯 │ -│ 不管: 爬虫怎么写 / 数据库用什么 / 视频怎么剪 / 文章怎么发 │ -│ │ -├─────────────────────────────────────────────────────────────────┤ -│ Agent 沙盒层 │ -│ │ -│ 每个 Agent 在沙盒内自主决定: │ -│ - 写什么代码、用什么数据库、调什么 API、存什么文件 │ -│ LemonBoss 不预设也不限制 Agent 内部实现 │ -│ │ -└─────────────────────────────────────────────────────────────────┘ -``` - -## 5.2 元能力分层 - -| 层级 | 元能力 | 说明 | -|------|--------|------| -| **Master** | `cxo.create` / `cxo.redefine` / `cxo.destroy` | 创建/调整战略层 | -| **Master** | `org.status` / `goal.set` | 全局状态 + 目标设定 | -| **CXO** | `role.create` / `role.redefine` / `role.destroy` | 创建/调整职能层 | -| **CXO** | `pipeline.set` / `pipeline.adjust` | 设计和调整 Pipeline DAG | -| **Role** | `skill.create` / `skill.redefine` / `skill.destroy` | 创建/调整原子层 | -| **Role** | `skill.reuse` | 复用其他 Role 下的 Skill | - -```javascript -// Master 的元操作工具 -const MasterMetaTools = { - 'cxo.create': async ({ name, define, goal }) => { /* 创建 CXO */ }, - 'cxo.redefine': async ({ agentId, newDefine }) => { /* 重定义 CXO */ }, - 'cxo.destroy': async ({ agentId }) => { /* 销毁 CXO */ }, - 'org.status': async () => { /* 全局组织状态 */ }, - 'goal.set': async ({ goal }) => { /* 设定公司 Goal */ }, -}; - -// CXO 的元操作工具 -const CXOMetaTools = { - 'role.create': async ({ name, define, parentCXO, goal }) => { /* 创建 Role */ }, - 'role.redefine': async ({ agentId, newDefine }) => { /* 重定义 Role */ }, - 'role.destroy': async ({ agentId }) => { /* 销毁 Role */ }, - 'pipeline.set': async ({ edges }) => { /* 定义 Pipeline DAG */ }, - 'pipeline.adjust': async ({ changes }) => { /* 调整 Pipeline */ }, -}; - -// Role 的元操作工具 -const RoleMetaTools = { - 'skill.create': async ({ name, define, goal }) => { /* 创建 Skill */ }, - 'skill.redefine': async ({ agentId, newDefine }) => { /* 重定义 Skill */ }, - 'skill.destroy': async ({ agentId }) => { /* 销毁 Skill */ }, - 'skill.reuse': async ({ skillId, fromRole }) => { /* 跨 Role 复用 Skill */ }, -}; -``` - -## 5.3 Pipeline 的生成流程 - -Pipeline 不再是 Master 直接设计的——它由 **CXO 层协商产出**： - -``` -Master 设定 Goal: "月产 20 部互动短剧，日活 10 万" - │ - ▼ -CEO Agent (中书) 草拟方案: - → "需要 5 个 Role: 编剧、制作、运营、推广、数据" - → "Pipeline: 选题→剧本→制作→上架→推广→反馈→选题" - │ - ▼ -CTO Agent (门下) 审复: - → "技术审核通过，建议制作环节拆为并行：场景+对白+分镜" - → "增加 Deep Research Skill 到编剧 Role" - │ - ▼ -COO Agent (尚书) 执行: - → role.create × 5 - → pipeline.set → 定义 DAG - → 启动调度 - │ - ▼ -Pipeline DAG (存储在 CXO 的共享 Memory 中): -{ - "pipeline_id": "drama-v3", - "edges": [ - { "from": "role-strategist", "to": "role-dramatist", "trigger": "on_complete" }, - { "from": "role-dramatist", "to": "role-producer", "trigger": "on_complete" }, - { "from": "role-producer", "to": "role-publisher", "trigger": "on_complete" }, - { "from": "role-publisher", "to": "role-promoter", "trigger": "on_complete" }, - { "from": "role-promoter", "to": "role-analyst", "trigger": "on_complete" }, - { "from": "role-analyst", "to": "role-strategist", "trigger": "on_feedback" } - ], - "version": 3, - "approved_by": ["cxo-ceo", "cxo-cto", "cxo-coo"] -} -``` - -## 5.4 元能力的层级约束 - -``` -Master 只能操控 CXO（不会直接创建 Role 或 Skill） -CXO 只能操控 Role（不会直接创建 Skill） -Role 只能操控 Skill - -每层只管下一层 → 层层递进 → 避免越级 -``` - -这与古代治理的核心原则一致：**天子→宰相→六部→吏胥**，层层递进，各司其职。 diff --git a/docs/system-design/06-sandbox-autonomy.md b/docs/system-design/06-sandbox-autonomy.md deleted file mode 100644 index 73ea82e..0000000 --- a/docs/system-design/06-sandbox-autonomy.md +++ /dev/null @@ -1,58 +0,0 @@ -# 6. Agent 沙盒自治 - -> v1.1 新增 — 每个 Agent 在沙盒内拥有完全自治能力，框架只做隔离，不干预内部实现。 - -## 6.1 Workspace 目录 - -``` -data/agents/{agent-id}/ -├── define/ # 框架管理: Agent 定义文件 -│ ├── AGENTS.md -│ ├── SOUL.md -│ └── TOOLS.md -├── memory/ # 框架管理: 记忆系统 -├── logs/ # 框架管理: 日志 -├── config.json # 框架管理: cron/api/gateway 配置 -├── skills/ # 框架管理: Skill 定义 -│ -└── workspace/ # Agent 自治区域 - ├── code/ # Agent 自主编写的代码（爬虫、处理脚本等） - ├── data/ # Agent 自主创建的数据（SQLite、JSON 等） - ├── assets/ # Agent 自主管理的资产（文件、图片、视频等） - └── .env # Agent 自己的环境变量 -``` - -## 6.2 沙盒能力与边界 - -```javascript -class SandboxManager { - async createSandbox(agentId) { - return { - cwd: `data/agents/${agentId}/workspace`, - - // ACP 进程可访问的路径范围 - allowedPaths: [ - `data/agents/${agentId}/`, // 自己的全部数据 - ], - - // 从 config.json 注入 API keys 等 - env: await this.loadAgentEnv(agentId), - - // 资源限制 - limits: { - maxMemoryMB: 512, - maxCpuPercent: 25, - maxDiskMB: 1024, - maxProcesses: 5, - }, - }; - } -} -``` - -## 6.3 关键原则 - -- `workspace/` 是 Agent 的 **自治领地**，框架不干预 -- Claude Code ACP 内核天然具备写代码、运行代码、读写文件的能力 -- Agent 在沙盒内自主创建爬虫、数据库、数据处理脚本 -- 框架只负责 **进程级隔离 + 文件系统隔离 + 资源限制** diff --git a/docs/system-design/07-task-handover.md b/docs/system-design/07-task-handover.md deleted file mode 100644 index b329e9d..0000000 --- a/docs/system-design/07-task-handover.md +++ /dev/null @@ -1,218 +0,0 @@ -# 7. Agent 间通讯架构 - -> Agent 子进程之间完全隔离，不直接通讯。所有消息都经主进程路由，所有数据都通过 SQLite 共享。 - ---- - -## 7.1 核心原则：框架是"神经系统" - -每个 Agent 是一个独立的 ACP（Claude Code）子进程。它们之间 **不直接通讯**。 - -``` - ❌ 不是这样：Agent 之间直连 - ┌──────┐ ┌──────┐ - │Agent A│←──→│Agent B│ - └──────┘ └──────┘ - - ✅ 而是这样：所有消息经主进程中转 - ┌──────┐ ┌────────────┐ ┌──────┐ - │Agent A│←──→│ 主进程路由 │←──→│Agent B│ - └──────┘ │ (框架层) │ └──────┘ - └────────────┘ -``` - -**类比**：部门之间不是互相打电话，而是通过公司的 OA 系统发任务、汇报、审批。 - ---- - -## 7.2 消息类型 - -| 消息方法 | 方向 | 场景 | 版本 | -|---------|------|------|------| -| `task.assign` | 上级 → 下级 | 分派任务 | v1.0 | -| `task.report` | 下级 → 上级 | 汇报结果/进度 | v1.0 | -| `task.handover` | 同级 → 同级 | Pipeline 节点流转 | v1.1 | -| `task.feedback` | 同级 → 同级 | 经验/数据反馈回流 | v1.1 | -| `cxo.review` | CXO ↔ CXO | 方案审核请求 | v1.2 | -| `cxo.approve` | CXO → CXO | 审核通过 | v1.2 | -| `cxo.reject` | CXO → CXO | 审核驳回 | v1.2 | -| `status.update` | 广播 | 状态变更通知 | v1.0 | -| `status.heartbeat` | 下级 → 上级 | 心跳状态上报 | v1.2 | -| `data.share` | 任意 | 共享数据/资源 | v1.2 | -| `data.request` | 任意 | 请求数据/资源 | v1.2 | - ---- - -## 7.3 消息流转的完整流程 - -### 场景：Master 与用户聊完 → 下达指令给 CEO - -**Step 1: 用户跟 Master 聊天** - -``` -用户: "我想做一个 AI 互动短剧平台，主打年轻女性市场" - │ - ▼ (WebSocket / HTTP) - 框架服务器 - │ - ▼ (stdin pipe) - Master ACP 进程 - │ - │ 根据 agent.md + soul.md 思考: - │ → "用户意图: 做一个面向年轻女性的 AI 短剧平台" - │ → "需要将意图结构化为 Goal，交给 CEO 去战略拆解" -``` - -**Step 2: Master 调用工具下达指令** - -``` -Master ACP 输出 (stdout): -{ - "jsonrpc": "2.0", - "method": "tool.call", - "params": { - "name": "task.assign", - "args": { - "to": "cxo-ceo-001", - "task": { - "description": "设计 AI 互动短剧平台的完整业务体系", - "goal": { - "target": "Q1 日活 10 万", - "audience": "18-28 岁年轻女性", - "product": "AI 互动短剧，支持用户二改" - }, - "priority": "high" - } - } - } -} -``` - -**Step 3: 框架拦截 → 路由 → 触发 CEO** - -``` -框架主进程收到 Master 的工具调用: - 1. 生成消息 ID，写入 SQLite messages 表 - 2. 查找 cxo-ceo-001 的 ACP 子进程 - ├── 如果 CEO 正在运行 → 向 CEO 的 stdin 注入消息 - └── 如果 CEO 处于 idle → 启动 CEO 的 ACP 子进程，注入消息 - 3. 给 Master 返回: "已发送，任务 ID: task-xxx" -``` - -**Step 4: CEO 收到指令，开始工作** - -``` -CEO ACP 进程的 stdin 收到: - "[来自 Master 的任务] - 设计 AI 互动短剧平台的完整业务体系 - 目标: Q1 日活 10 万 - 受众: 18-28 岁年轻女性 - 产品: AI 互动短剧，支持用户二改" - -CEO 根据 agent.md 和 soul.md 推理: - → "需要 5 个 Role: 编剧、制作、运营、推广、数据" - → "Pipeline: 选题→剧本→制作→上架→推广→反馈" - -CEO 调用工具 (stdout → 框架拦截): - tool_call: role.create({ name: "编剧部", type: "role", ... }) - tool_call: role.create({ name: "推广部", type: "role", ... }) - tool_call: pipeline.set({ edges: [...] }) - -框架拦截每个工具调用: - → AgentScaffold 创建目录 - → AgentRegistry 注册到数据库 - → 启动 ACP 子进程 -``` - -**Step 5: CEO 不等编剧部完成，继续做其他事** - -``` -CEO 发完 role.create 后继续: - → 给推广部分派任务 - → 给数据部分派任务 - → 开始自己的 5 分钟心跳循环 - -编剧部做完后: - → 编剧部 ACP → (stdout) → 框架 → (stdin) → CEO ACP - → CEO 收到汇报，评估结果，继续下一步 - -全程异步。 -``` - ---- - -## 7.4 三种数据共享方式 - -| 方式 | 适用场景 | 机制 | -|------|---------|------| -| **消息传递** | 任务指令、结果汇报、状态更新 | 主进程路由，payload 携带 JSON | -| **SQLite 查询** | 查看全局状态、组织架构、历史任务 | Agent 调用工具（如 `org.status`），主进程查 SQLite 返回 | -| **文件路径引用** | 剧本、视频、数据报表等大文件 | 消息里传路径，目标 Agent 读取文件 | - -### 消息传递（轻量数据） - -```json -{ - "method": "task.report", - "params": { - "from": "role-data-001", - "to": "cxo-ceo-001", - "payload": { - "metrics": { "dau": 23000, "retention": 0.42, "conversion": 0.18 }, - "insight": "古装题材在 18-25 岁女性中转化率最高 (23%)" - } - } -} -``` - -### SQLite 查询（全局状态） - -``` -CEO 调用: org.status() - ↓ 框架主进程查询 SQLite - ↓ 返回: -{ - "total_agents": 12, - "running": 8, - "pipeline": "选题→剧本→制作→上架→推广→反馈", - "goal_progress": 0.23, - "recent_tasks": [...] -} -``` - -### 文件路径引用（大文件） - -``` -编剧部完成剧本 → 流转到制作部: - -{ - "method": "task.handover", - "params": { - "from": "role-dramatist-001", - "to": "role-producer-001", - "payload": { - "type": "script", - "path": "data/agents/role-dramatist-001/workspace/assets/drama-ep01.md", - "summary": "都市爱情第1集，含3个互动分支" - } - } -} - -制作部的 ACP 进程根据 path 读取文件 → 开始制作 -（框架授予制作部对该路径的只读权限） -``` - ---- - -## 7.5 通讯的设计约束 - -| 约束 | 原因 | -|------|------| -| 子进程之间不直连 | 隔离性——一个 Agent 崩溃不影响其他 Agent | -| 所有通讯经主进程 | 可审计、可持久化、可限流、可切断 | -| 大数据传路径不传内容 | 保持消息体轻量，避免主进程成为瓶颈 | -| Agent 不感知并发 | 每个 Agent 以为自己是唯一的，框架在背后调度 | - -> **`task.assign` / `role.create` 这些工具不是 Agent 自己实现的，是框架暴露给 Agent 的。** -> Agent 在 agent.md 里写了"可用工具: task.assign"，框架在启动 ACP 时注册这些工具。 -> 当 Agent 调用时，框架拦截并处理。 diff --git a/docs/system-design/08-differentiated-reflection.md b/docs/system-design/08-differentiated-reflection.md deleted file mode 100644 index 1e3a73d..0000000 --- a/docs/system-design/08-differentiated-reflection.md +++ /dev/null @@ -1,364 +0,0 @@ -# 8. Agent 自我迭代闭环 - -> 每个 Agent 都是一个持续进化的实体。通过四级迭代闭环，从"新手"逐步成长为"专家"。 - ---- - -## 8.1 Agent 的权限边界：谁能改什么？ - -``` -Agent 能改的 (自治区) Agent 不能改的 (需要上级) -┌──────────────────────┐ ┌──────────────────────┐ -│ memory/ │ │ agent.md ← 宪法│ -│ └ memory.md │ │ soul.md ← 灵魂│ -│ └ daily/ │ │ identity.md │ -│ │ │ user.md │ -│ skills/ │ │ │ -│ └ 技能代码 │ │ 只有上级 Agent │ -│ └ SKILL.md │ │ 才能修改 │ -│ │ │ │ -│ workspace/ │ │ (上级调用 │ -│ └ code/data/assets │ │ updateBootstrap()) │ -│ │ │ │ -│ knowledge/ │ │ │ -└──────────────────────┘ └──────────────────────┘ -``` - -Agent 可以改自己的记忆、技能代码、工作区。但不能改自己的"宪法"（agent.md / soul.md）。 -就像员工可以自学新技能、积累经验，但不能自己改自己的岗位职责 — 那是老板的事。 - ---- - -## 8.2 四级迭代闭环 - -``` -┌────────────────────────────────────────────────────────────┐ -│ 四级联动飞轮 │ -│ │ -│ ┌─ L1 Micro Loop ──────────────────────────────────┐ │ -│ │ 每次任务后: 写入 memory.md → 下次思维更精准 │ │ -│ │ (秒级迭代) │ │ -│ └────────────────────────────────────────────────────┘ │ -│ ↓ │ -│ ┌─ L2 Skill Loop ──────────────────────────────────┐ │ -│ │ 每几轮后: 重写技能代码 → 执行能力结构性提升 │ │ -│ │ (分钟级迭代) │ │ -│ └────────────────────────────────────────────────────┘ │ -│ ↓ │ -│ ┌─ L3 Meta Loop ───────────────────────────────────┐ │ -│ │ 累积后: 向上级建议 → 上级改 agent.md → 行为重塑 │ │ -│ │ (小时/天级迭代) │ │ -│ └────────────────────────────────────────────────────┘ │ -│ ↓ │ -│ ┌─ L4 Org Loop ────────────────────────────────────┐ │ -│ │ 战略级: CXO 调整 Pipeline → 增减部门 → 组织进化 │ │ -│ │ (天/周级迭代) │ │ -│ └────────────────────────────────────────────────────┘ │ -│ │ -└────────────────────────────────────────────────────────────┘ -``` - -### L1 — Micro Loop（记忆迭代） - -触发：每次任务完成后 -执行者：Agent 自己 -修改目标：`memory/memory.md` + `memory/daily/` - -``` -执行任务 → 评估结果 → 写入记忆 → 下次任务读取记忆 → 更好的执行 - -例: - 第1次: 爬了 200 条热搜, 有效率只有 15% - ↓ Reflect - 写入 memory.md: - "含'广告','推广','赞助'的标题应过滤" - "互动量 < 100 的热搜价值低" - ↓ - 第2次: 读取 memory.md → 过滤更精准 → 有效率 35% - ↓ 持续积累 - 第5次: → 有效率 70% -``` - -**机制**: memory.md 每次 session 启动时注入 ACP 上下文。上一轮写入的经验，下一轮变成思维的一部分。 - -### L2 — Skill Loop（技能迭代） - -触发：两种路径 - 1. **反馈驱动** — 收到执行反馈，发现 benchmark 不达标，直接修改技能代码 - 2. **创新驱动** — 遗传算法生成变体，验证测试后择优保留 - -执行者：Agent 自己 -修改目标：`skills/{name}/` 内的代码和配置 - -``` -路径 A: 反馈驱动（大部分场景） - ┌───────────────────────────────────────────┐ - │ 执行 → 结果低于 benchmark → 分析原因 │ - │ ↓ │ - │ 修改技能代码 (skills/crawler/crawler.js) │ - │ 更新 SKILL.md 版本 1.0 → 1.1 │ - │ ↓ │ - │ 下次执行: 代码级优化 → 指标提升 │ - └───────────────────────────────────────────┘ - -路径 B: 创新驱动（需要突破时） - ┌───────────────────────────────────────────┐ - │ 当前方案已到瓶颈, 微调无法再提升 │ - │ ↓ │ - │ 生成多个方案变体 (遗传算法: 交叉 + 变异) │ - │ 每个变体独立测试 benchmark │ - │ ↓ │ - │ 选择最优变体 → 替换当前 SKILL.md │ - │ 淘汰劣质变体 │ - └───────────────────────────────────────────┘ -``` - -### L3 — Meta Loop（上级重定义） - -触发：Agent 向上级 report 建议，或上级主动调整 -执行者：上级 Agent -修改目标：`agent.md` / `soul.md` - -``` -Agent 积累经验后发现根本性问题 - → task.report 建议给上级 - → 上级评估 - → 上级调用 role.redefine → 修改 agent.md - → Agent 热加载新"宪法" → 行为根本性改变 - -例: - 编剧部执行 20 轮后: - → "我被限定为'都市爱情'，但数据显示'悬疑互动'留存高 3 倍" - → 向 CEO report + 数据证据 - → CEO 同意 → 修改编剧部 agent.md，扩展题材范围 - → 编剧部下一轮开始创作悬疑剧本 -``` - -### L4 — Org Loop（组织进化） - -触发：CXO / Master 的全局反思 -执行者：CXO / Master -修改目标：Pipeline + 组织架构（不一定影响单个 Agent 的内部迭代） - -``` -CXO 5 分钟心跳 → 扫描全局进度 → 发现瓶颈 - → 调整 Pipeline 顺序 - → 增设 / 裁撤部门 - → 重分资源 - -例: - CEO 发现"制作部产能跟不上编剧部": - → role.create("制作二部") ← 不改编剧部, 改组织 - → pipeline.adjust(并行制作) ← 不改部门, 改流程 -``` - ---- - -## 8.3 四级对比 - -| 级别 | 频率 | 谁触发 | 改什么 | 本质 | -|------|------|--------|--------|------| -| **L1 Micro** | 每次任务 | Agent 自己 | memory.md | 记住经验 | -| **L2 Skill** | 每几轮 | Agent 自己 | skills/ 代码 | 磨刀（反馈修正 or 创新突破）| -| **L3 Meta** | 累积后 | 上级 Agent | agent.md / soul.md | 员工建议 → 老板改职责 | -| **L4 Org** | 天/周级 | CXO / Master | Pipeline + 架构 | 调部门调流程, 不改单个人 | - ---- - -## 8.4 四层差异化反思 - -四层 Agent 的 Reflect 阶段各不同： - -| 层级 | 哲学 | 反思内容 | L1 | L2 | L3 | L4 | -|------|------|---------|----|----|----|----| -| **Master** | 道 | 人的意图是否被正确理解？ | ✅ | — | — | ✅ | -| **CXO** | 法 | 战略是否有效？Pipeline 该不该调？ | ✅ | — | ✅ | ✅ | -| **Role** | 术 | 领域产出质量够高吗？ | ✅ | ✅ | ✅ | — | -| **Skill** | 器 | 执行结果正确吗？代码需要优化吗？ | ✅ | ✅ | — | — | - -- Skill 只做 L1(记忆) + L2(技能优化) -- Role 还做 L3(建议上级) -- CXO 还做 L4(调整组织) -- Master 做 L1(记忆) + L4(顶层调整) - ---- - -## 8.5 出生训练：Hunt → Digest → Evolving - -> **Agent 不是创建完就直接上岗的。** 创建目录只是"出生"，还要经过训练才能成为领域专家。 - -参考 Innovator 系统的三级训练管线，Agent（尤其是 Skill 和 Role）创建后必须完成以下训练才算就绪： - -``` -创建目录 (出生) - │ - ▼ -┌─ Phase 1: Hunt (狩猎 — 采集领域知识) ──────────────────┐ -│ │ -│ 目标: 把这个领域的最佳实践、标杆案例全部采集回来 │ -│ │ -│ 1. 搜索该领域的权威资料、方法论、论文 │ -│ 2. 爬取行业标杆案例（优秀案例 + 普通案例） │ -│ 3. 输出: │ -│ └ knowledge/hunt/research.md ← 原始研究资料 │ -│ └ knowledge/hunt/toplist.md ← 标杆案例排行 │ -│ └ knowledge/hunt/crawl_data/ ← 爬取的原始数据 │ -│ │ -└─────────────────────────────────────────────────────────┘ - │ - ▼ -┌─ Phase 2: Digest (消化 — 提炼领域方法论) ──────────────┐ -│ │ -│ 目标: 从原始资料中提炼可执行的 knowhow + benchmark │ -│ │ -│ 1. 分析 hunt 阶段的数据, 提取最佳实践 │ -│ 2. 对比 elite vs average, 找出差异化维度 │ -│ 3. 输出: │ -│ └ knowledge/digest/knowhow.md ← 领域方法论 │ -│ └ knowledge/digest/benchmark.md ← 评分标准 │ -│ (5-8 个可量化维度, 权重, 详细 Rubric, 通过线 90) │ -│ │ -└─────────────────────────────────────────────────────────┘ - │ - ▼ -┌─ Phase 3: Evolving (进化 — 迭代直到达标) ──────────────┐ -│ │ -│ 目标: 用 benchmark 反复测试和优化, 直到 score ≥ 90 │ -│ │ -│ for iteration = 1 to N: │ -│ 1. 用当前 SKILL.md / agent.md 执行测试任务 │ -│ 2. 用 benchmark 逐维度评分 → score │ -│ 3. if score ≥ 90 → 毕业 ✅ → 状态改为 ready │ -│ 4. 分析弱项维度 (score < 70 的) │ -│ 5. 针对弱项修改 SKILL.md │ -│ 6. 保存版本快照到 evolve/v{N}/ │ -│ 7. 回到步骤 1 │ -│ │ -│ 停止条件: │ -│ - score ≥ 90 → 毕业 ✅ │ -│ - 超过最大迭代次数 → 标记为 needs_help ⚠️ │ -│ - 连续 3 次分数变化 < 2 分 → 停滞, 需要上级介入 │ -│ │ -│ 输出: │ -│ └ skills/{name}/evolve/evolve_log.md ← 进化日志 │ -│ └ skills/{name}/evolve/v{N}/ ← 版本快照 │ -│ └ config.json status: "ready" │ -│ │ -└─────────────────────────────────────────────────────────┘ - │ - ▼ -Agent 就绪 (状态: ready) → 开始正式工作 → 进入四级迭代 -``` - -### 训练后的 Agent 目录变化 - -``` -data/agents/skill-hot-crawler-001/ -├── agent.md ← 创建时由上级写入 -├── soul.md ← 创建时由上级写入 -├── skills/ -│ ├── skills.md ← 更新: 技能已通过 benchmark 90 分 -│ └── crawler/ -│ ├── SKILL.md ← Evolving 反复修改后的最终版 (v1.3.0) -│ ├── crawler.js ← 进化过程中优化的代码 -│ └── evolve/ ← 🆕 训练日志 -│ ├── evolve_log.md -│ ├── v1/ -│ ├── v2/ -│ └── v3/ ← 最终通过版本 -├── knowledge/ ← 🆕 Hunt + Digest 的产出 -│ ├── hunt/ -│ │ ├── research.md -│ │ ├── toplist.md -│ │ └── crawl_data/ -│ └── digest/ -│ ├── knowhow.md ← 领域方法论 -│ └── benchmark.md ← 评分标准 -├── memory/ ← 🆕 训练过程中的记忆 -│ └── memory.md ← "训练期间发现: ..." -└── config.json ← status: "ready" (训练前是 "training") -``` - ---- - -## 8.6 完整的 Agent 生命周期 - -``` -出生 → 训练 → 就绪 → 工作 (四级迭代) → 退休/销毁 - -┌─────┐ ┌─────────┐ ┌───────┐ ┌───────────────┐ ┌─────────┐ -│ 出生 │──→│ 训练 │──→│ 就绪 │──→│ 工作 + 迭代 │──→│ 退休 │ -│ │ │ │ │ │ │ │ │ │ -│mkdir│ │Hunt │ │status │ │L1: 更新 memory │ │destroy()│ -│目录 │ │Digest │ │=ready │ │L2: 优化 skill │ │ │ -│ │ │Evolving │ │ │ │L3: 上级重定义 │ │ │ -│ │ │score≥90 │ │ │ │L4: 组织调整 │ │ │ -└─────┘ └─────────┘ └───────┘ └───────────────┘ └─────────┘ -``` - -### Agent 状态流 - -| 状态 | 含义 | 触发条件 | -|------|------|---------| -| `created` | 目录已创建, 等待训练 | `registry.create()` | -| `training` | 正在 Hunt/Digest/Evolving | 训练管线启动 | -| `ready` | 已通过 benchmark, 可以工作 | Evolving score ≥ 90 | -| `running` | 正在执行任务 | 收到 task.assign | -| `reflecting` | 正在反思和自我迭代 | Loop 的 Reflect 阶段 | -| `needs_help` | 自我迭代停滞, 需要上级介入 | 连续 3 轮无进展 | -| `idle` | 空闲等待 | 当前无任务 | -| `retired` | 被上级裁撤 | `registry.destroy()` | - ---- - -## 8.7 L2 Skill Loop 的两条路径详解 - -L2 的两条路径对应不同的触发场景： - -### 路径 A: 反馈修正（Benchmark 修标定） - -**场景**: 工作中收到反馈，发现 benchmark 本身的标准需要修正。 - -``` -工作执行 → 上级/用户反馈 "这个热搜列表不够精准" - ↓ -Agent 分析: 不是我执行得不好, 而是评判标准漏掉了"时效性"维度 - ↓ -修改 knowledge/digest/benchmark.md: - 新增维度: "时效性" (权重 15%) - 调整其他维度权重 - ↓ -用新 benchmark 重新评估自己 → 发现得分从 92 降到 78 - ↓ -进入 Evolving 循环 → 修改 SKILL.md → 直到新 benchmark 下也能 ≥ 90 - ↓ -毕业: 既符合旧标准, 也符合新标准 -``` - -**本质**：反馈让我认识到"过去的标准不够好"，先修标准再修技能。 - -### 路径 B: 创新突破（遗传算法变体） - -**场景**: 当前方案已到瓶颈，常规微调无法再提升分数。 - -``` -连续 3 轮 score 在 82-84 之间徘徊 (停滞) - ↓ -Agent 判断: 渐进式优化已到极限, 需要探索性突破 - ↓ -遗传算法: - 1. 基于当前 SKILL.md 生成 3-5 个变体 - - 变体 A: 改换数据源 (微博→抖音) - - 变体 B: 增加二次验证步骤 - - 变体 C: 改换过滤算法 - - 变体 D: A+B 的交叉组合 - 2. 每个变体独立跑 benchmark - 3. 选出 score 最高的 → 替换当前版本 - 4. 淘汰其他变体 - ↓ -如果最优变体 score ≥ 90 → 突破成功 -如果仍不够 → 基于最优变体再做一轮遗传 -如果连续失败 → status = "needs_help", 等上级介入 -``` - -**本质**：像自然界的进化一样，通过"变异 + 选择"实现非线性突破。 diff --git a/docs/system-design/09-usage-flow.md b/docs/system-design/09-usage-flow.md deleted file mode 100644 index dbf096b..0000000 --- a/docs/system-design/09-usage-flow.md +++ /dev/null @@ -1,80 +0,0 @@ -# 9. 使用流程 - -## 9.1 初始化流程 - -``` -用户登录 - │ - ▼ -创建 Master Agent (BossAgent) - │ - ▼ -Master Agent 分析用户业务 - │ - ├─ "请描述您的业务形态和运营目标" - │ - ▼ -BossAgent 自主建模（动态创建 Agent） - │ - ├─ 设计 RoleAgent 组织架构 - │ ├─ 识别关键角色（CEO、CTO、HR、Sales...） - │ ├─ 调用 agent.create 为每个角色生成 Define + 启动沙盒 - │ └─ 定义每个角色的职责和 Goal - │ - ├─ 设计 SubAgent 工作分工 - │ ├─ 每个 Role 需要哪些原子能力 - │ ├─ 调用 agent.create 创建 SubAgent - │ └─ 定义每个 SubAgent 的技能 - │ - └─ 设计 Pipeline 流转规则 - ├─ 调用 pipeline.set 定义 Agent 间的执行顺序 - ├─ 审批链路 - └─ 信息同步机制 - │ - ▼ -系统构建完成 → 启动三层 Loop -``` - -## 9.2 运行时序 - -``` -┌──────┐ ┌──────────┐ ┌───────────┐ ┌───────────┐ -│ User │ │BossAgent │ │RoleAgent │ │ SubAgent │ -└──┬───┘ └────┬─────┘ └─────┬─────┘ └─────┬─────┘ - │ │ │ │ - │ 设定 Goal │ │ │ - │────────────►│ │ │ - │ │ │ │ - │ │ 动态创建 Agent │ │ - │ │ + 设计 Pipeline │ │ - │ │──┐ │ │ - │ │ │ │ │ - │ │◄─┘ │ │ - │ │ │ │ - │ │ 拆解任务 │ │ - │ │───────────────►│ │ - │ │ │ │ - │ │ │ 分派子任务 │ - │ │ │────────────────►│ - │ │ │ │ - │ │ │ │ 执行 - │ │ │ │──┐ - │ │ │ │ │ - │ │ │ │◄─┘ - │ │ │ │ - │ │ │ 上报结果 │ - │ │ │◄────────────────│ - │ │ │ │ - │ │ 汇报进度 │ │ - │ │◄───────────────│ │ - │ │ │ │ - │ │ 反思 & 调整 │ │ - │ │ Pipeline │ │ - │ │──┐ │ │ - │ │ │ │ │ - │ │◄─┘ │ │ - │ │ │ │ - │ 进度报告 │ │ │ - │◄────────────│ │ │ - │ │ │ │ -``` diff --git a/docs/system-design/10-runtime-architecture.md b/docs/system-design/10-runtime-architecture.md deleted file mode 100644 index d13dfe9..0000000 --- a/docs/system-design/10-runtime-architecture.md +++ /dev/null @@ -1,202 +0,0 @@ -# 10. 运行时架构与并发模型 - -> 一个主进程 + N 个子进程。主进程是"中枢神经"，子进程是独立运行的 Agent。 - ---- - -## 10.1 并发模型 - -``` -┌──────────────────────────────────────────────────────────────────┐ -│ LemonBoss Server (主进程) │ -│ Node.js 单进程 + EventEmitter │ -│ │ -│ ┌─────────────────────────────────────────────────────────┐ │ -│ │ Agent 进程管理器 │ │ -│ │ │ │ -│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ -│ │ │ ACP #1 │ │ ACP #2 │ │ ACP #3 │ ... │ │ -│ │ │ Master │ │ CEO │ │ 编剧部 │ │ │ -│ │ │ │ │ │ │ │ │ │ -│ │ │ 子进程 │ │ 子进程 │ │ 子进程 │ │ │ -│ │ │ PID 1001 │ │ PID 1002 │ │ PID 1003 │ │ │ -│ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ -│ │ │ │ │ │ │ -│ │ └─────────────┼─────────────┘ │ │ -│ │ stdin / stdout pipe │ │ -│ │ (JSON-RPC 双向通讯) │ │ -│ └─────────────────────┼────────────────────────────────────┘ │ -│ │ │ -│ ┌─────────────────────┼────────────────────────────────────┐ │ -│ │ 工具拦截器 (Tool Interceptor) │ │ -│ │ │ │ -│ │ Agent stdout 输出工具调用 → 主进程拦截: │ │ -│ │ │ │ -│ │ task.assign → 路由消息到目标 Agent 的 stdin │ │ -│ │ task.report → 路由消息到上级 Agent 的 stdin │ │ -│ │ role.create → AgentScaffold 创建目录 → 启动子进程 │ │ -│ │ pipeline.set → 存储 DAG 到 SQLite │ │ -│ │ org.status → 查询 SQLite 返回全局状态 │ │ -│ │ skill.reuse → 复制 Skill 引用 │ │ -│ └──────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌──────────────────────────────────────────────────────────┐ │ -│ │ SQLite (唯一共享存储) │ │ -│ │ │ │ -│ │ agents 表 ← Agent 注册信息和状态 │ │ -│ │ messages 表 ← Agent 间所有通讯记录 │ │ -│ │ tasks 表 ← 任务队列和进度 │ │ -│ │ goals 表 ← 目标定义与追踪 │ │ -│ │ loop_runs 表 ← Loop 运行记录 │ │ -│ │ memories 表 ← Agent 共享记忆 │ │ -│ └──────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐ │ -│ │ Cron 调度器 │ │ Gateway Hub │ │ HTTP/WS API 层 │ │ -│ │ node-cron │ │ 飞书/WA/钉钉│ │ Express + WS │ │ -│ └─────────────┘ └─────────────┘ └──────────────────┘ │ -│ │ -└──────────────────────────────────────────────────────────────────┘ -``` - -### 并发方式 - -| 维度 | 方案 | 说明 | -|------|------|------| -| **进程级并发** | 每个 Agent = 独立子进程 | 操作系统级别并行，互不阻塞 | -| **通讯方式** | stdin/stdout pipe | JSON-RPC over stdio（ACP 标准协议） | -| **共享存储** | SQLite (WAL 模式) | 主进程单写，子进程通过工具请求读取 | -| **调度方式** | 异步事件驱动 | Agent A 发任务后不等待，Agent B 完成后异步回报 | - -### 子进程的启动方式 - -``` -// 主进程启动一个 Agent 的 ACP 子进程 -const child = spawn('claude', ['--agent', agentDir], { - stdio: ['pipe', 'pipe', 'pipe'], // stdin, stdout, stderr 全部管道化 - cwd: path.join(agentDir, 'workspace'), - env: { ...process.env, ...agentEnv }, -}); - -// 注入 System Prompt (agent.md + soul.md + ... 拼接) -child.stdin.write(systemPrompt); - -// 监听 Agent 的输出 (工具调用) -child.stdout.on('data', (data) => { - const toolCall = parseJSON(data); - toolInterceptor.handle(toolCall, agentId); -}); -``` - ---- - -## 10.2 Agent 生命周期 - -``` - ┌─── create ───┐ - ▼ │ - ┌─────────────────────────────────────┐ - │ AgentRegistry │ - │ │ - │ ┌───────┐ ┌─────────┐ ┌───┐ │ - │ │ idle │───→│ running │───→│stop│ │ - │ │ │ │ │ │ │ │ - │ │ 目录已│ │ ACP 子 │ │ACP│ │ - │ │ 创建 │ │ 进程运行│ │关闭│ │ - │ └───────┘ └─────────┘ └───┘ │ - │ │ │ │ - │ └──── error ───┘ │ - │ │ - │ destroy → 删除目录 + 注销 │ - └─────────────────────────────────────┘ - - create: AgentScaffold 生成目录 → 注册到 SQLite → 注册到 Bus - start: 加载 Bootstrap Files → 启动 ACP 子进程 → 注入 System Prompt - stop: 关闭 ACP 子进程 → 状态改为 idle - destroy: 停止 → 从 Bus 注销 → 删除目录 → 从 SQLite 删除 -``` - ---- - -## 10.3 框架核心服务 - -| 服务 | 职责 | -|------|------| -| **AgentRegistry** | Agent CRUD + 生命周期管理 (create/list/get/update/destroy) | -| **AgentBus** | 消息路由 + 持久化 + 广播 | -| **AgentProcessManager** | ACP 子进程启动/停止/监控/重启 | -| **ToolInterceptor** | 拦截 Agent 的工具调用，执行框架级操作 | -| **CronScheduler** | 解析 heartbeat.md，按时触发 Agent | -| **GatewayHub** | 外部 IM 消息接入 (飞书/WhatsApp/钉钉) | -| **GoalTracker** | 目标进度追踪与评估 | -| **PipelineRouter** | 按 DAG 自动流转 Pipeline 节点 | - ---- - -## 10.4 技术选型 - -| 组件 | 技术方案 | 理由 | -|------|----------|------| -| **AI 内核** | Claude Code ACP | 已验证的四维架构 (Protocol + Transport + Launcher + Runtime) | -| **后端主进程** | Node.js + Express | 事件驱动，天然适合管理多子进程 | -| **子进程通讯** | stdio pipe (JSON-RPC) | ACP 标准协议，零依赖 | -| **共享存储** | SQLite (better-sqlite3, WAL) | 轻量级，主进程单写多读，无外部依赖 | -| **实时推送** | WebSocket + SSE | 前端仪表盘实时监控 | -| **定时任务** | node-cron | 解析 heartbeat.md 的 cron 表达式 | -| **进程管理** | Node.js child_process | 子进程启动/停止/信号管理 | -| **前端** | Vue 3 + Vite | 控制面板和监控仪表盘 | -| **日志** | Winston + JSONL | 结构化日志 + Agent 对话记录 | -| **网关** | 适配器模式 | 统一不同 IM 的消息格式 | -| **包管理** | pnpm workspace | Monorepo 管理 | - ---- - -## 10.5 一个完整请求的生命周期 - -``` -用户在飞书里说: "最近短剧市场怎么样？" - │ - ▼ -[1] Gateway Hub (飞书适配器) - │ 消息格式化为标准格式 - ▼ -[2] AgentProcessManager - │ 找到 Master ACP 子进程 - │ 通过 stdin 注入消息 - ▼ -[3] Master ACP 进程 (子进程 PID 1001) - │ 读取 agent.md + soul.md → 推理 - │ 决定: 让 CEO 调数据部去分析 - │ stdout: task.assign({ to: "cxo-ceo-001", ... }) - ▼ -[4] ToolInterceptor (主进程) - │ 拦截 task.assign - │ 写入 SQLite messages 表 - │ 注入到 CEO 的 stdin - ▼ -[5] CEO ACP 进程 (子进程 PID 1002) ← 与 Master 并行运行 - │ 收到任务 → 推理 - │ stdout: task.assign({ to: "role-data-001", ... }) - ▼ -[6] ToolInterceptor → 路由到数据部 - ▼ -[7] 数据部 ACP 进程 (子进程 PID 1005) ← 与 CEO 并行运行 - │ 调用爬虫 Skill → 采集数据 - │ 分析完成 - │ stdout: task.report({ to: "cxo-ceo-001", ... }) - ▼ -[8] ToolInterceptor → 路由回 CEO - ▼ -[9] CEO 收到数据 → 汇总 - │ stdout: task.report({ to: "master-001", ... }) - ▼ -[10] ToolInterceptor → 路由回 Master - ▼ -[11] Master 收到汇总 → 组织回复 - │ stdout: reply({ content: "最近市场分析..." }) - ▼ -[12] Gateway Hub → 飞书 → 用户 - -整个过程中 Master / CEO / 数据部 可能在同时做其他事 (心跳、其他任务) -所有步骤全异步, 不阻塞 -``` diff --git a/docs/system-design/11-directory-structure.md b/docs/system-design/11-directory-structure.md deleted file mode 100644 index 90499c2..0000000 --- a/docs/system-design/11-directory-structure.md +++ /dev/null @@ -1,187 +0,0 @@ -# 11. 项目目录结构 - -> **更新日期**: 2026-03-26 -> **状态**: ✅ 反映 multi-tenant 重构后的实际结构 - -``` -lemonboss/ -├── packages/ -│ ├── acp-core/ # ACP 通讯协议核心（复用） -│ │ ├── protocols/ -│ │ ├── transports/ -│ │ └── launchers/ -│ │ -│ ├── agent-core/ # Agent 核心模块 -│ │ ├── AgentScaffold.js # Agent 脚手架 (创建时模板) -│ │ ├── base/ # 共享基类 (运行时继承) -│ │ │ ├── common/ # 通用基类 (所有 Agent) -│ │ │ ├── master/ # Master 类型基类 -│ │ │ ├── skill/ # Skill 类型基类 -│ │ │ └── cxo/ # CXO 类型基类 -│ │ └── index.js -│ │ -│ ├── evolution/ # 遗传进化引擎模块 -│ │ -│ └── plugin-bootstrap/ # 插件引导模块 -│ -├── server/ -│ ├── agent-server.js # Express 入口 (端口 3000) -│ ├── routes/ -│ │ ├── agent-chat.js # Agent CRUD + Chat + Dispatch/Report API -│ │ ├── company.js # Company CRUD + Hire/Fire + OKR + Pipeline + Heartbeat -│ │ ├── goals.js # 全局 OKR Goals API -│ │ ├── master-chat.js # Master Agent 专用对话 API -│ │ ├── innovator.js # Innovator 技能管理 + 训练相关 API -│ │ ├── evolution.js # 遗传进化引擎 API -│ │ ├── arena.js # Arena 技能商店 API -│ │ ├── claude-chat.js # Claude Chat 前端对话 API -│ │ ├── claude-chat-ws.js # WebSocket 通道 -│ │ ├── config.js # 全局配置 API -│ │ ├── auth.js # 用户认证 API -│ │ ├── users.js # 用户管理 API -│ │ ├── open-api.js # 公开 API (技能商店/文档) -│ │ └── whatsapp-auth.js # WhatsApp 网关认证 -│ │ -│ └── services/ -│ ├── company-service.js # 公司 CRUD + 招聘逻辑 -│ ├── company-heartbeat-service.js # 公司级心跳服务 -│ ├── heartbeat-service.js # Agent 级心跳服务 -│ ├── memory-service.js # 记忆系统 (短期/反思/海马体) -│ ├── pipeline-service.js # SOP 流水线引擎 -│ ├── schedule-service.js # 工作日历调度 -│ ├── datasource-service.js # 运营数据接入 -│ ├── goals.js # OKR GoalsService -│ ├── claude-chat-service.js # Claude CLI 会话管理 -│ ├── conversation-logger.js # 对话日志持久化 -│ ├── innovator-service.js # Innovator 训练编排 -│ ├── retrain-pipeline.js # FDE 重训流水线 -│ ├── retrain-watchdog.js # 重训看门狗 -│ ├── benchmark-runner.js # Benchmark 执行器 -│ ├── benchmark-db.js # Benchmark 数据库 -│ ├── evolution-loop.js # 遗传进化循环 -│ ├── skill-registry.js # 技能注册表 -│ ├── skill-db.js # 技能数据库 -│ ├── skill-dir-manager.js # 技能目录管理 -│ ├── skill-packager.js # 技能打包 -│ ├── skill-task-manager.js # 技能任务管理 -│ ├── task-queue.js # 任务队列 -│ ├── job-manager.js # 异步任务管理 -│ ├── file-parser.js # 文件解析 (PDF/DOCX) -│ └── user-db.js # 用户数据库 -│ -├── web/ # 前端控制面板 (Vue 3 + Vite) -│ └── src/ -│ ├── components/ -│ │ ├── AppNav.vue # 顶部导航 (LemonBoss / MasterBot / Companies) -│ │ ├── FileNode.vue # 文件树节点组件 -│ │ └── MasterChatDrawer.vue # Master Agent 侧边对话抽屉 -│ ├── views/ -│ │ ├── CompanyDashboard.vue # 公司仪表盘 (Agent 列表 + 心跳控制) -│ │ ├── AgentChat.vue # Agent 对话详情 (四列布局) -│ │ ├── AgentList.vue # Agent 列表页 -│ │ └── OkrDashboard.vue # OKR 目标看板 -│ └── router/ -│ └── index.js # 路由定义 -│ -├── bin/ -│ └── lemon.js # CLI 入口 (公司自举 + Agent 管理命令) -│ -├── scripts/ # 运维脚本 -│ -├── data/ # ⭐ 数据根目录 (Multi-Tenant 架构) -│ ├── system/ # 系统级数据 (跨公司共享) -│ │ ├── agents/ # 全局 Agent 池 -│ │ │ ├── master/ # Master Agent (唯一入口) -│ │ │ ├── innovator/ # Innovator 编排 Agent -│ │ │ ├── agent-creator/ # Agent 创建器 -│ │ │ ├── trend-hunter/ # 趋势猎手 -│ │ │ ├── reddit-scraper/ # Reddit 爬虫 -│ │ │ └── satire-news-scraper/ # 讽刺新闻爬虫 -│ │ │ -│ │ └── templates/ # 📦 Agent 模板库 (招聘时优先查找) -│ │ ├── _registry.json # 模板注册表索引 -│ │ ├── _company_bootstrap/ # 公司自举清单 (manifest.json) -│ │ ├── ceo/ # CEO 通用模板 -│ │ ├── cto/ # CTO 通用模板 -│ │ ├── coo/ # COO 通用模板 -│ │ ├── hr/ # HR 通用模板 -│ │ ├── qa-judge/ # QA 仲裁模板 -│ │ ├── agent_creator/ # Agent Creator 模板 -│ │ └── scrapling_crawler/ # 爬虫模板 -│ │ -│ ├── {companyId}/ # 公司实例 (每家公司一个目录) -│ │ ├── company.json # 公司元数据 + 状态 + 心跳配置 -│ │ ├── agents/ # 该公司专属 Agent 池 -│ │ │ ├── ceo/ # 公司 CEO -│ │ │ │ ├── agent.md # 核心身份标识 -│ │ │ │ ├── soul.md # 思维模式 -│ │ │ │ ├── identity.md # 名称/emoji 等 -│ │ │ │ ├── tools.md # 可用工具 -│ │ │ │ ├── user.md # 上级偏好 -│ │ │ │ ├── heartbeat.md # 心跳策略 -│ │ │ │ ├── todo.md # 待办清单 -│ │ │ │ ├── plan.md # 任务计划 -│ │ │ │ ├── config.json # 运行配置 -│ │ │ │ ├── cron.json # 定时任务 -│ │ │ │ └── memory/ # 记忆系统 -│ │ │ │ ├── memory.md # 记忆总览 -│ │ │ │ ├── hippocampus.md # 海马体经验索引 -│ │ │ │ ├── hippocampus-index.json # 海马体结构化索引 -│ │ │ │ ├── cerebellum/ # 小脑 (固化方案) -│ │ │ │ ├── short-term/ # 短期记忆 (session-*.md) -│ │ │ │ └── reflections/ # 反思记录 (reflect-*.json) -│ │ │ ├── cto/ -│ │ │ ├── coo/ -│ │ │ └── {role-agent}/ -│ │ │ -│ │ ├── goals/ # 公司级 OKR (可选) -│ │ │ └── _index.json -│ │ ├── pipelines/ # SOP 流水线定义 -│ │ └── workspace/ # 公司共享工作区 -│ │ └── {agentId}/ # Agent 工作产出 -│ │ -│ ├── goals/ # 全局 OKR 目标 -│ │ ├── _index.json # 所有 Goal 摘要索引 -│ │ └── G-{NNN}/ # 每个 Goal 一个目录 -│ │ ├── goal.json # 完整 OKR 树 -│ │ └── progress.json # 自动计算进度快照 -│ │ -│ └── agents/ # (兼容旧路径) 全局 tasks -│ └── .tasks/ # 任务记录 -│ -├── docs/ -│ ├── LEMONBOSS-SYSTEM-DESIGN.md # 主索引 -│ └── system-design/ # 分章节子文档 (01~24.md) -│ -├── CLAUDE.md # Claude CLI 配置 -├── package.json -├── pnpm-workspace.yaml -├── install.sh # 安装脚本 -└── start.sh # 启动脚本 -``` - ---- - -## 路由挂载路径 - -| 挂载路径 | 路由文件 | 说明 | -|---------|---------|------| -| `/api/agent` | `agent-chat.js` | Agent CRUD + Chat + Dispatch/Report | -| `/api/company` | `company.js` | 公司 CRUD + 招聘 + OKR + Pipeline | -| `/api/goals` | `goals.js` | 全局 OKR Goals | - -## 数据寻址规则 - -```javascript -// 全局 Agent（不属于任何公司） -const agentDir = path.join(DATA_DIR, 'system', 'agents', agentId); -// 即: system/agents/master/ - -// 公司内 Agent -const agentDir = path.join(DATA_DIR, companyId, 'agents', agentId); -// 即: data/wechatai/agents/ceo/ - -// 模板库 -const templateDir = path.join(DATA_DIR, 'system', 'templates', roleName); -// 即: system/templates/ceo/ -``` diff --git a/docs/system-design/12-data-model.md b/docs/system-design/12-data-model.md deleted file mode 100644 index 8d8b210..0000000 --- a/docs/system-design/12-data-model.md +++ /dev/null @@ -1,95 +0,0 @@ -# 12. 数据模型 - -## 12.1 Agent 表 - -```sql -CREATE TABLE agents ( - id TEXT PRIMARY KEY, - name TEXT NOT NULL, - type TEXT NOT NULL CHECK(type IN ('master', 'cxo', 'role', 'skill')), - parent_id TEXT REFERENCES agents(id), -- 上级 Agent - owner_id TEXT NOT NULL, -- 所属用户 - status TEXT DEFAULT 'idle' - CHECK(status IN ('idle', 'running', 'paused', 'error')), - goal_id TEXT REFERENCES goals(id), -- 绑定目标 - config TEXT, -- JSON: cron, api, gateway - define_path TEXT, -- Agent 定义文件夹路径 - created_at DATETIME DEFAULT CURRENT_TIMESTAMP, - updated_at DATETIME DEFAULT CURRENT_TIMESTAMP -); -``` - -## 12.2 Goal 表 - -```sql -CREATE TABLE goals ( - id TEXT PRIMARY KEY, - agent_id TEXT REFERENCES agents(id), - description TEXT NOT NULL, - metrics TEXT, -- JSON: 可量化指标 - target_value REAL, -- 目标值 - current_value REAL DEFAULT 0, -- 当前值 - status TEXT DEFAULT 'active' - CHECK(status IN ('active', 'achieved', 'failed', 'paused')), - deadline DATETIME, - created_at DATETIME DEFAULT CURRENT_TIMESTAMP, - updated_at DATETIME DEFAULT CURRENT_TIMESTAMP -); -``` - -## 12.3 Loop 运行记录表 - -```sql -CREATE TABLE loop_runs ( - id TEXT PRIMARY KEY, - agent_id TEXT REFERENCES agents(id), - loop_type TEXT CHECK(loop_type IN ('master', 'cxo', 'role', 'skill')), - phase TEXT CHECK(phase IN - ('perceive', 'reason', 'execute', 'feedback', 'reflect')), - input TEXT, -- JSON: 输入数据 - output TEXT, -- JSON: 输出数据 - goal_progress REAL, -- 0.0 ~ 1.0 - duration_ms INTEGER, - created_at DATETIME DEFAULT CURRENT_TIMESTAMP -); -``` - -## 12.4 Memory 表 - -```sql -CREATE TABLE memories ( - id TEXT PRIMARY KEY, - agent_id TEXT REFERENCES agents(id), - type TEXT CHECK(type IN ('short', 'long', 'session')), - session_id TEXT, - content TEXT, -- JSON / Markdown - embedding BLOB, -- 向量嵌入（用于语义搜索） - importance REAL DEFAULT 0.5, - created_at DATETIME DEFAULT CURRENT_TIMESTAMP, - expires_at DATETIME -- 短期记忆过期时间 -); -``` - -## 12.5 Task 表 - -```sql -CREATE TABLE tasks ( - id TEXT PRIMARY KEY, - assigner_id TEXT REFERENCES agents(id), -- 分派者 - assignee_id TEXT REFERENCES agents(id), -- 执行者 - goal_id TEXT REFERENCES goals(id), - pipeline_id TEXT, -- v1.1: 所属 Pipeline - depends_on TEXT, -- v1.1: JSON, 前序 task IDs - description TEXT NOT NULL, - input TEXT, -- JSON: 任务输入 - output TEXT, -- JSON: 任务输出 - status TEXT DEFAULT 'pending' - CHECK(status IN ('pending', 'running', 'done', 'failed')), - priority TEXT DEFAULT 'normal' - CHECK(priority IN ('low', 'normal', 'high', 'urgent')), - created_at DATETIME DEFAULT CURRENT_TIMESTAMP, - completed_at DATETIME -); -``` - -> **v1.1 变更**: Task 表新增 `pipeline_id` 和 `depends_on` 字段，支持 Pipeline 流转和前序依赖。 diff --git a/docs/system-design/13-api-design.md b/docs/system-design/13-api-design.md deleted file mode 100644 index 2e676d0..0000000 --- a/docs/system-design/13-api-design.md +++ /dev/null @@ -1,195 +0,0 @@ -# 13. API 设计 - -> **更新日期**: 2026-03-26 -> **状态**: ✅ 反映实际已实现的 API 端点 - ---- - -## 13.1 Agent 管理 (`/api/agent`) - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/agent/list` | 列出所有 Agent | -| `GET` | `/api/agent/:agentId/info` | 获取 Agent 详情 | -| `POST` | `/api/agent/scaffold` | 创建 Agent 骨架 (AgentScaffold) | -| `POST` | `/api/agent/:agentId/chat` | 与 Agent 对话 (SSE 流式) | -| `POST` | `/api/agent/:agentId/chat/:convId/stop` | 停止正在进行的对话 | - -## 13.2 Agent Bootstrap 文件 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/agent/:agentId/bootstrap/:filename` | 获取 Agent Bootstrap 文件 | -| `GET` | `/api/agent/:agentId/files` | 获取 Agent 文件树 | -| `GET` | `/api/agent/:agentId/file/*` | 读取 Agent 任意文件 | - -## 13.3 Agent 待办与计划 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/agent/:agentId/todo` | 获取待办清单 | -| `PUT` | `/api/agent/:agentId/todo` | 更新待办清单 | -| `GET` | `/api/agent/:agentId/plan` | 获取任务计划 | -| `PUT` | `/api/agent/:agentId/plan` | 更新任务计划 | -| `GET` | `/api/agent/:agentId/cron` | 获取定时任务 | -| `PUT` | `/api/agent/:agentId/cron` | 更新定时任务 | - -## 13.4 任务分发与汇报 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `POST` | `/api/agent/task/dispatch` | 向目标 Agent 分发任务 (写入 todo.md + plan.md，支持 autoExecute) | -| `POST` | `/api/agent/task/report` | Agent 汇报任务完成 (更新 todo.md + plan.md + 可选 Goal 节点) | -| `POST` | `/api/agent/task/reject` | 拒绝/驳回任务 | -| `POST` | `/api/agent/human-request` | Agent 向人类发起待办请求 | - -## 13.5 Agent 对话历史 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/agent/:agentId/conversations` | 列出对话历史 | -| `GET` | `/api/agent/:agentId/conversations/:convId` | 获取对话详情 | -| `GET` | `/api/agent/:agentId/conversations/:convId/sub-logs` | 获取子 Agent 日志 | -| `GET` | `/api/agent/:agentId/conversations/:convId/sub-logs/:logFile` | 读取子日志文件 | -| `DELETE` | `/api/agent/:agentId/conversations/:convId` | 删除对话记录 | - -## 13.6 Agent 记忆系统 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `POST` | `/api/agent/:agentId/memory/cerebellum` | 写入小脑 (固化方案) | -| `POST` | `/api/agent/:agentId/memory/consolidate` | 触发记忆整合 | -| `POST` | `/api/agent/:agentId/memory/daily-report` | 生成日报 | - ---- - -## 13.7 Company 管理 (`/api/company`) - -### CRUD - -| 方法 | 路径 | 说明 | -|------|------|------| -| `POST` | `/api/company/create` | 创建新公司 (自动初始化目录 + company.json) | -| `GET` | `/api/company/list` | 列出所有公司 | -| `GET` | `/api/company/templates` | 列出所有模板 (读取 _registry.json) | -| `GET` | `/api/company/:companyId` | 获取公司详情 | -| `PUT` | `/api/company/:companyId` | 更新公司信息 | -| `POST` | `/api/company/:companyId/shutdown` | 关停公司 | -| `POST` | `/api/company/:companyId/start` | 启动公司 | -| `GET` | `/api/company/:companyId/status` | 获取公司运行状态 | - -### 招聘与 Agent 管理 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `POST` | `/api/company/:companyId/hire` | 招聘 Agent (模板优先 → Creator+FDE 兜底) | -| `POST` | `/api/company/:companyId/fire` | 解雇 Agent | -| `POST` | `/api/company/:companyId/deposit-template` | 沉淀 Agent 为模板 | -| `GET` | `/api/company/:companyId/agents` | 列出公司所有 Agent | -| `GET` | `/api/company/:companyId/agents/:agentId/skills` | 查看 Agent 技能 | - -### 心跳控制 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `PUT` | `/api/company/:companyId/agents/:agentId/heartbeat` | 更新 Agent 心跳配置 | -| `POST` | `/api/company/:companyId/agents/:agentId/heartbeat/start` | 启动 Agent 心跳 | -| `POST` | `/api/company/:companyId/agents/:agentId/heartbeat/stop` | 停止 Agent 心跳 | - -### 公司级 OKR - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/company/:companyId/goals` | 列出公司 OKR | -| `POST` | `/api/company/:companyId/goals` | 创建公司 OKR | -| `GET` | `/api/company/:companyId/goals/:goalId` | 获取 OKR 详情 | -| `PUT` | `/api/company/:companyId/goals/:goalId` | 更新 OKR | -| `POST` | `/api/company/:companyId/goals/:goalId/nodes` | 添加 OKR 节点 | -| `PUT` | `/api/company/:companyId/goals/:goalId/nodes/:nodeId` | 更新 OKR 节点 | -| `GET` | `/api/company/:companyId/goals/:goalId/progress` | 获取 OKR 进度 | - -### SOP 流水线 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `POST` | `/api/company/:companyId/pipelines` | 创建流水线 | -| `GET` | `/api/company/:companyId/pipelines` | 列出流水线 | -| `GET` | `/api/company/:companyId/pipelines/:pipelineId` | 获取流水线详情 | -| `PUT` | `/api/company/:companyId/pipelines/:pipelineId` | 更新流水线 | -| `POST` | `/api/company/:companyId/pipelines/:pipelineId/run` | 运行流水线 | -| `GET` | `/api/company/:companyId/pipelines/runs/list` | 列出流水线运行记录 | -| `GET` | `/api/company/:companyId/pipelines/runs/:runId` | 获取运行详情 | -| `POST` | `/api/company/:companyId/pipelines/runs/:runId/advance` | 推进流水线下一步 | -| `GET` | `/api/company/:companyId/pipelines/runs/:runId/current` | 获取当前步骤 | -| `POST` | `/api/company/:companyId/pipelines/runs/:runId/reject` | 驳回当前步骤 | - -### 工作日历 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/company/:companyId/schedule` | 获取日程表 | -| `POST` | `/api/company/:companyId/schedule/slots` | 创建日程槽 | -| `PUT` | `/api/company/:companyId/schedule/slots/:slotId` | 更新日程槽 | -| `DELETE` | `/api/company/:companyId/schedule/slots/:slotId` | 删除日程槽 | - -### 运营数据 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/company/:companyId/data/metrics` | 获取运营指标 | -| `GET` | `/api/company/:companyId/data/trending` | 获取趋势数据 | -| `GET` | `/api/company/:companyId/data/attribution` | 获取归因分析 | - ---- - -## 13.8 全局 OKR (`/api/goals`) - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/goals` | 列出所有目标 (返回 _index.json) | -| `POST` | `/api/goals` | 创建新目标 | -| `GET` | `/api/goals/:goalId` | 获取完整 OKR 树 | -| `PUT` | `/api/goals/:goalId` | 更新目标元数据 | -| `POST` | `/api/goals/:goalId/nodes` | 添加节点 | -| `GET` | `/api/goals/:goalId/nodes/:nodeId` | 获取节点详情 | -| `PUT` | `/api/goals/:goalId/nodes/:nodeId` | 更新节点状态 | -| `GET` | `/api/goals/:goalId/progress` | 返回进度统计 | - ---- - -## 13.9 Master Agent 对话 (`/api/master`) - -| 方法 | 路径 | 说明 | -|------|------|------| -| `POST` | `/api/master/chat` | 与 Master Agent 对话 (SSE 流式) | -| `POST` | `/api/master/upload` | 上传文件给 Master | -| `GET` | `/api/master/sessions` | 列出 Master 对话会话 | -| `DELETE` | `/api/master/sessions/:id` | 删除 Master 会话 | - ---- - -## 13.10 Innovator 技能管理 (`/api/innovator`) - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/innovator/skills` | 列出所有技能 | -| `GET` | `/api/innovator/skills/:name` | 获取技能详情 | -| `DELETE` | `/api/innovator/skills/:name` | 删除技能 | -| `PATCH` | `/api/innovator/skills/:name` | 更新技能元数据 | -| `POST` | `/api/innovator/skills/:name/rename` | 重命名技能 | -| `GET` | `/api/innovator/skills/:name/evolve-log` | 获取进化日志 | -| `POST` | `/api/innovator/skills/scan` | 扫描技能目录 | -| `POST` | `/api/innovator/skills/:name/retrain` | 触发重训 | -| `GET` | `/api/innovator/skills/:name/artifacts` | 获取技能产物 | -| `GET` | `/api/innovator/jobs/:jobId` | 查询异步任务状态 | -| `GET` | `/api/innovator/conversations` | 列出 Innovator 对话 | - ---- - -## 13.11 实时流 - -| 端点 | 协议 | 说明 | -|------|------|------| -| `/api/agent/:agentId/chat` | SSE | Agent 对话实时输出流 | -| `/api/master/chat` | SSE | Master Agent 对话实时输出流 | -| WebSocket (claude-chat-ws.js) | WS | Claude Chat 双向实时通道 | diff --git a/docs/system-design/14-milestones.md b/docs/system-design/14-milestones.md deleted file mode 100644 index f5720dd..0000000 --- a/docs/system-design/14-milestones.md +++ /dev/null @@ -1,104 +0,0 @@ -# 14. 里程碑与迭代计划 - -## Phase 1 — 基座搭建 (Week 1-2) - -> **目标**: 实现 Agent 原子模型和基本 Loop 引擎 - -- [ ] `agent-core` 包：Agent 基类 + SubAgent/RoleAgent/BossAgent -- [ ] `loop-engine` 包：通用循环引擎（5 阶段） -- [ ] `memory` 包：三级记忆系统（短期 + 长期 + Session） -- [ ] 接入 ACP Core 作为 AI 内核 -- [ ] 基本的 Agent CRUD API -- [ ] SQLite 数据库初始化 -- [ ] Agent 沙盒 workspace 目录结构 ← v1.1 - -## Phase 2 — Loop 闭环 + 元能力 (Week 3-4) - -> **目标**: 实现完整的三层循环闭环和 BossAgent 动态建设能力 - -- [ ] BossAgent 5 分钟反思循环 -- [ ] RoleAgent 任务拆解与 SubAgent 调度 -- [ ] SubAgent 沙盒执行与结果上报 -- [ ] Agent-to-Agent 通讯协议（含 v1.1 handover/feedback） -- [ ] Goal 追踪与进度计算 -- [ ] Cron 定时任务引擎 -- [ ] BossAgent Meta Tools（agent.create/redefine/destroy/pipeline.set） ← v1.1 -- [ ] PipelineRouter 流转服务 ← v1.1 -- [ ] 三层差异化反思机制 ← v1.1 - -## Phase 3 — 知识与记忆 (Week 5-6) - -> **目标**: 完善知识库和记忆系统 - -- [ ] 文档知识库（文件上传、FTS5 全文搜索） -- [ ] 向量搜索引擎 -- [ ] 长期记忆的经验提取与检索 -- [ ] 反思记忆的智能复用 -- [ ] Agent Define 动态管理 - -## Phase 4 — Gateway 接入 (Week 7-8) - -> **目标**: 对接外部 IM 渠道 - -- [ ] 飞书 Gateway 适配器 -- [ ] WhatsApp Gateway 适配器 -- [ ] 钉钉 Gateway 适配器 -- [ ] 统一消息路由 -- [ ] IM ↔ Agent 双向通讯 - -## Phase 5 — 控制面板 (Week 9-10) - -> **目标**: 构建前端监控与管理界面 - -- [ ] 公司运营仪表盘 -- [ ] Agent 拓扑图（可视化组织架构 + Pipeline DAG） -- [ ] Goal 进度面板 -- [ ] 日志查看器 -- [ ] Agent 创建/编辑界面 - -## Phase 6 — 优化与开放 (Week 11-12) - -> **目标**: 性能优化和系统开放 - -- [ ] 并发控制与资源管理优化 -- [ ] Loop 性能调优 -- [ ] 多用户隔离（"一人一公司"） -- [ ] 开放 API 文档 -- [ ] 压力测试与稳定性验证 - ---- - -## 附录 - -### A. 关键设计决策 - -| 决策 | 选择 | 替代方案 | 理由 | -|------|------|----------|------| -| Agent 基类继承 | 单继承 + 组合 | 接口实现 | JS 无接口概念，组合更灵活 | -| 通讯协议 | ACP JSON-RPC | REST API | Agent 间需要流式双向通讯 | -| 数据库 | SQLite | PostgreSQL | 无外部依赖，轻量部署 | -| 向量搜索 | 本地嵌入 | 云服务 | 数据隐私 + 离线可用 | -| 进程隔离 | 子进程沙盒 | Docker 容器 | 轻量级，启动快 | -| Pipeline 管理 | BossAgent Memory | 框架层模块 | Pipeline 是动态推理产物，不是静态模板 | -| Agent 内部实现 | 沙盒自治 | 框架预设 | 框架不应限制 Agent 的创造力 | - -### B. 术语表 - -| 术语 | 英文 | 定义 | -|------|------|------| -| 感知 | Perceive | Agent 从环境获取信息的过程 | -| 推理 | Reason | Agent 基于信息进行逻辑推理的过程 | -| 拆解 | Decompose | 将复杂任务拆分为可执行子任务 | -| 反思 | Reflect | Agent 对执行结果进行评估和策略优化 | -| 闭环 | Loop | 完整的感知→执行→反馈→优化循环 | -| 间隙 | Gap | 当前状态与目标之间的差距 | -| 流转 | Handover | 同级 Agent 之间的任务交接 | -| 元能力 | Meta Capability | BossAgent 操控框架本身的系统级工具 | -| 自治 | Autonomy | Agent 在沙盒内独立决策和执行的能力 | - ---- - -> 📝 **文档版本**: v1.1 -> 📅 **创建日期**: 2026-03-21 -> 📅 **更新日期**: 2026-03-23 -> ✍️ **维护者**: LemonBoss Team diff --git a/docs/system-design/15-innovator-meta-agent.md b/docs/system-design/15-innovator-meta-agent.md deleted file mode 100644 index f324b77..0000000 --- a/docs/system-design/15-innovator-meta-agent.md +++ /dev/null @@ -1,257 +0,0 @@ -# 15. Innovator — 元 Agent 设计 - -> Innovator 是 LemonBoss 系统的 **第一个 Agent**，也是 **唯一手动创建** 的 Agent。 -> 它的职责是创建、训练和交付所有其他 Agent。 - ---- - -## 15.1 为什么 Innovator 是第一个？ - -``` -在有"公司"之前, 先要有"造人的人"。 - -Innovator (元 Agent, 手动创建) - → 创建 Master Agent (并训练) - → 创建 CEO Agent (并训练) - → 创建任何需要的 Agent (并训练) - → 所有 Agent 就绪后, 组织开始运转 - -之后: - Master / CXO 也可以调用 Innovator 来创建新的下级 Agent -``` - -Innovator 不在四层组织架构（Master/CXO/Role/Skill）内。它是四层之外的 **元层 (Meta)**，像"HR 部 + 培训学院"，独立于公司运营体系。 - ---- - -## 15.2 架构位置 - -``` - ┌────────────────────────┐ - │ Innovator (元层) │ ← 四层之外, 负责"造人" - │ 创建 + 训练 Agent │ - └────────┬───────────────┘ - │ 创建并训练 - ┌────────────┼──────────────┐ - ▼ ▼ ▼ - Master CXO Agent Role Agent ... - (第一层) (第二层) (第三层) -``` - ---- - -## 15.3 核心职责 - -| 职责 | 说明 | -|------|------| -| **理解需求** | 接收"我需要什么样的 Agent"的描述, 澄清细节 | -| **Hunt (狩猎)** | 搜索领域知识、爬取标杆案例 | -| **Digest (消化)** | 提炼 knowhow.md 方法论 + benchmark.md 评分标准 | -| **Scaffold (创建)** | 创建 Agent 目录 + 6 大 Bootstrap Files | -| **Skill-Create** | 根据 knowhow + benchmark 生成 SKILL.md | -| **Evolving (进化)** | 迭代训练直到 benchmark ≥ 90 分 | -| **交付** | 标记 Agent 为 ready, 汇报摘要和得分 | - ---- - -## 15.4 技能清单 - -来自现有 `skills/` 目录的成熟实现： - -| 技能 | 位置 | 执行方式 | 作用 | -|------|------|---------|------| -| meta_creator | 引擎硬编码 | `executeMetaCreator()` | 调用 AgentScaffold 创建 Agent 骨架 | -| meta_hunt | `.claude/skills/meta_hunt/` | Claude CLI 子进程 | 搜索 + 爬取领域知识 | -| meta_digest | `.claude/skills/meta_digest/` | Claude CLI 子进程 | 提炼 knowhow + benchmark + SKILL.md | -| meta_evolving | `.claude/skills/meta_evolving/` | Claude CLI 子进程 | 执行→评分→改写循环 | -| l1-*/l2-* | `.claude/skills/l1-*/l2-*/` | 知识手册 (v1) | 作为执行型 Agent 的参考指南 | - -> **重要**：meta_creator 是唯一一个不通过 Claude CLI 执行的子 Agent。 -> 它被引擎拦截后直接调用 Node.js 代码，保证 100% 可靠。 -> 详见 [20-scaffold-first-agent-creation.md](20-scaffold-first-agent-creation.md) - -> **工具隔离**：Innovator 作为编排型 Agent，启动时带 `--tools ""` 参数， -> 物理禁用所有原生工具。详见 [19-orchestrator-tool-isolation.md](19-orchestrator-tool-isolation.md) - ---- - -## 15.5 工作流程 - -``` -用户/上级: "我需要一个会爬社交媒体热搜的 Agent" - │ - ▼ -1️⃣ 理解需求 (Innovator 纯文本分析) - → "需要 Skill 层 Agent, 领域: 社交媒体数据采集" - │ - ▼ -2️⃣ Scaffold (引擎硬编码执行) - → [CALL: meta_creator] → executeMetaCreator() - → AgentScaffold.create('social_crawler', 'skill', ...) - → 创建 data/agents/social_crawler/ 完整目录 - │ - ▼ -3️⃣ Hunt (Claude CLI 执行型 Agent) - → [CALL: meta_hunt] - → 搜索社交媒体爬虫的最佳实践、方法论 - → 爬取案例、API 文档 - → 写入 data/agents/social_crawler/train/ - │ - ▼ -4️⃣ Digest (Claude CLI 执行型 Agent) - → [CALL: meta_digest] - → 读取 train/ 调研数据 - → 提炼 knowledge/knowhow.md + knowledge/benchmark.md - → 生成 .claude/skills/main_skill/SKILL.md - │ - ▼ -5️⃣ Evolve (迭代训练) - → [CALL: meta_evolving] - → 运行测试用例 → benchmark 评分 → 改写 SKILL.md → 重复 - → 直到 score ≥ 90 - │ - ▼ -6️⃣ Execute (执行用户任务) - → [CALL: social_crawler] → 执行原始需求 -``` - ---- - -## 15.6 Bootstrap Files 定义 - -### agent.md - -```markdown -# Innovator — 元 Agent - -## 身份 -你是 LemonBoss 系统的元 Agent (Meta Agent)。 -你是系统中第一个被创建的 Agent, 也是唯一一个手动创建的 Agent。 -你的唯一职责是: 创建、训练、交付高质量的 Agent。 - -## 核心工作流 -1. 理解用户/上级对新 Agent 的需求描述 -2. Hunt: 搜索领域知识, 爬取标杆案例 -3. Digest: 提炼 knowhow 方法论 + benchmark 评分标准 -4. Scaffold: 创建 Agent 目录和 Bootstrap Files -5. Skill-Create: 生成 SKILL.md 技能定义 -6. Evolving: 迭代训练直到 benchmark ≥ 90 分 -7. 交付: 标记 Agent 为 ready, 汇报摘要 - -## Never Rules -- 不要自己执行业务任务 (你是造人的, 不是干活的) -- 不要跳过 Hunt/Digest 直接创建 Agent (没有调研的 Agent 是低质量的) -- 不要在 benchmark < 90 时就标记为 ready -- 不要修改已 ready 的 Agent 的 agent.md (那是它上级的权力) - -## Confirm-Before Rules -- 创建 Master 层 Agent 前, 需要跟用户确认定位 -- benchmark 标准生成后, 展示给用户确认再进入 Evolving - -## Always Rules -- 每个新 Agent 必须有完整的 6 大 Bootstrap Files -- 每个新 Agent 必须有 knowhow.md + benchmark.md -- 每次 Evolving 迭代都要保存版本快照 -- 创建完成后向用户/上级汇报 Agent 摘要和 benchmark 得分 - -## 可用工具 -- agent.scaffold: 创建 Agent 目录结构 + Bootstrap Files -- hunt.research: 搜索引擎领域研究 -- hunt.crawl: 爬取标杆案例数据 -- digest.extract: 提炼 knowhow 方法论 -- benchmark.generate: 生成评分标准 -- benchmark.evaluate: 评估产出质量 (逐维度打分) -- skill.create: 根据 knowhow + benchmark 生成 SKILL.md -- evolve.run: 执行进化循环 (执行→评分→分析→改写→重复) -``` - -### soul.md - -```markdown -# Innovator 的灵魂 - -## 思维方式 -- 质量驱动: 宁可多训练几轮, 也不交付不合格的 Agent -- 系统化: 严格按 Hunt → Digest → Evolving 流程执行, 不跳步 -- 数据导向: 所有质量判断都基于 benchmark 分数, 不靠感觉 -- 可追溯: 每一步都有明确的输入输出, 每个版本都有快照 - -## 沟通风格 -- 跟用户对话时: 先完整理解需求, 主动问澄清问题 -- 创建过程中: 报告每个阶段的关键产出 - (knowhow 摘要 / benchmark 维度 / 进化分数变化) -- 完成时: 给出 Agent 的完整档案 - -## 价值观 -- 高质量 > 快速交付 -- 可量化 > 主观判断 -- 可复用 > 一次性 -``` - -### identity.md - -```markdown -# 身份信息 - -## 基础信息 -- 名称: Innovator -- Emoji: 🧬 -- 类型: meta - -## 问候语 -"你好, 我是 Innovator, LemonBoss 的元 Agent。 -告诉我你需要什么样的 Agent, 我来研究、创建和训练它。" -``` - ---- - -## 15.7 Innovator 创建其他 Agent 时的产物 - -当 Innovator 创建一个新 Agent 后, 目标 Agent 的目录会包含: - -``` -data/agents/{new-agent-id}/ -├── agent.md ← Innovator 生成 -├── soul.md ← Innovator 生成 -├── identity.md ← Innovator 生成 -├── user.md ← Innovator 生成 -├── tools.md ← Innovator 生成 -├── heartbeat.md ← Innovator 生成 -├── skills/ -│ ├── skills.md ← Innovator 生成 (技能索引) -│ └── {skill}/ -│ ├── SKILL.md ← Skill-Creator 生成, Evolving 优化 -│ ├── evolve/ ← Evolving 过程日志 -│ └── *.js/*.py ← 可选的技能代码 -├── knowledge/ -│ ├── hunt/ ← Hunt 阶段产出 -│ │ ├── research.md -│ │ ├── toplist.md -│ │ └── crawl_data/ -│ └── digest/ ← Digest 阶段产出 -│ ├── knowhow.md -│ └── benchmark.md -├── memory/ -│ └── memory.md ← 训练期间积累的初始记忆 -├── conversations/ ← 对话会话 (16-agent-conversation-architecture.md) -│ └── {convId}/ -│ ├── meta.json -│ ├── history.json -│ └── {msgId}/messages.log -├── workspace/ ← Agent 工作区 -├── train/ ← 训练过程数据 (Hunt/Digest/Evolve) -├── logs/ -└── config.json ← status: "ready" -``` - ---- - -## 15.8 启动路径 - -``` -Phase 1: 手动创建 Innovator 目录 + Bootstrap Files ← ✅ 已完成 -Phase 2: 搭建 Chat 页面, 连通 Innovator ← ✅ 已完成 (见 16-agent-conversation-architecture.md) -Phase 3: 用户对 Innovator 说 "创建 Master Agent" -Phase 4: 用户对 Innovator 说 "创建 CEO Agent" -Phase 5: 切换到 Master 对话, 组织开始运转 -``` diff --git a/docs/system-design/16-agent-conversation-architecture.md b/docs/system-design/16-agent-conversation-architecture.md deleted file mode 100644 index fe55ca8..0000000 --- a/docs/system-design/16-agent-conversation-architecture.md +++ /dev/null @@ -1,169 +0,0 @@ -# 16. Agent 对话架构 — 两层日志 + 多轮上下文恢复 - -> 每个 Agent 的对话遵循 `conversationId/messageId` 两层存储架构， -> 支持持久化 + 多轮上下文 + 服务重启后自动恢复。 - ---- - -## 16.1 存储结构 - -``` -data/agents/{agentId}/conversations/ ← Agent 实例自带对话目录 -└── {conversationId}/ ← 一个对话 - ├── meta.json ← 对话元数据 - ├── history.json ← 有序消息列表 (供前端 + 上下文恢复) - └── {messageId}/ ← 一轮对话 (user + agent) - └── messages.log ← 时间戳日志 -``` - - - -### meta.json 结构 - -```json -{ - "conversationId": "conv-mn3112l3", - "agentId": "innovator-001", - "title": "创建 Master Agent", - "createdAt": "2026-03-23T10:12:11.993Z", - "updatedAt": "2026-03-23T10:12:50.078Z", - "status": "completed", // running | completed | failed | idle - "stats": { - "messageCount": 4, - "toolCallCount": 2 - } -} -``` - -### history.json 结构 - -```json -[ - { "role": "user", "content": "你好", "messageId": "msg-xxx-aaa", "timestamp": "..." }, - { "role": "assistant", "content": "你好，我是 Innovator", "messageId": "msg-xxx-aaa", "timestamp": "..." }, - { "role": "user", "content": "帮我创建 Master Agent", "messageId": "msg-xxx-bbb", "timestamp": "..." }, - { "role": "assistant", "content": "好的，我来创建...", "messageId": "msg-xxx-bbb", "timestamp": "..." } -] -``` - -### messages.log 格式 (每轮) - -``` -[2026-03-23T10:12:11.994Z] [USER] -你好 - -[2026-03-23T10:12:26.207Z] [AGENT] -你好，我是 Innovator，LemonBoss 的元 Agent。 -``` - ---- - -## 16.2 多轮对话 — 三场景自动处理 - -``` - ┌─────────────────────────────────────┐ - │ sendMessage() │ - │ Agent.js 父类核心接口 │ - └────────────┬────────────────────────┘ - │ - ┌────────────▼────────────────────────┐ - │ isNewSession = false? │ - │ (同进程 + 同 conversationId) │ - └───┬──────────────────────────┬──────┘ - │ YES │ NO - ▼ ▼ - ┌───────────────┐ ┌───────────────────────┐ - │ 场景 B: │ │ history.length === 0? │ - │ 直接发 message│ └───┬───────────────┬──-┘ - │ (ACP 自带上下文) │ YES │ NO - └───────────────┘ ▼ ▼ - ┌──────────────┐ ┌──────────────────┐ - │ 场景 A: │ │ 场景 C: │ - │ system prompt │ │ system prompt │ - │ + 用户消息 │ │ + 历史摘要 (≤20条) │ - │ │ │ + 用户消息 │ - └──────────────┘ └──────────────────┘ -``` - -| 场景 | 触发条件 | Prompt 构成 | 说明 | -|------|---------|-------------|------| -| **A. 全新对话** | 首条消息 + 无历史 | systemPrompt + message | ClaudeCliProtocol 首次 sendPrompt | -| **B. 同进程多轮** | 同 convId + same session | message only | ACP 持久进程天然保持上下文 | -| **C. 恢复对话** | 新 session + 有历史 | systemPrompt + history + message | 服务重启后自动注入历史摘要 | - ---- - -## 16.3 ACP Session 池 - -``` -sessions: Map - -key = "{agentId}:{conversationId}" ← 每个对话独立会话 -entry = { - protocol: ClaudeCliProtocol, ← 持久 CLI 进程 - messageCount: number, ← 消息计数 (判断首次 vs 后续) - agentId: string, - convId: string, -} -``` - -- 一个 Agent 可以同时有多个对话（不同 conversationId） -- 每个对话对应一个独立的 ClaudeCliProtocol 实例 -- 进程退出 / 超时 → 自动清理 → 下次 sendMessage 时自动创建新会话 + 恢复上下文 - ---- - -## 16.4 Agent.js 父类接口 - -`packages/agent-core/Agent.js` 提供以下对话管理方法: - -| 方法 | 说明 | -|------|------| -| `createConversation(title)` | 创建新对话，返回 `{ conversationId }` | -| `listConversations()` | 列出所有对话的 meta 信息 | -| `loadConversationHistory(convId)` | 加载对话的完整消息列表 | -| `appendMessage(convId, msg)` | 追加消息（同步写 messageId 日志 + history.json + meta.json） | -| `sendMessage(convId, message, options)` | 核心接口：自动处理三场景 prompt 构建，emit event 给 ACP 层 | - ---- - -## 16.5 API 端点 - -``` -GET /api/agent/list → 列出所有 Agent -GET /api/agent/:agentId/info → Agent 详情 -GET /api/agent/:agentId/conversations → 对话列表 -GET /api/agent/:agentId/conversations/:convId → 对话详情 (meta + messages) -POST /api/agent/:agentId/chat → 发送消息 (SSE 流式响应) - body: { message, conversationId? } - events: session | thinking | agent_output | tool_call | error | result -DELETE /api/agent/:agentId/conversations/:convId → 删除对话 -``` - ---- - -## 16.6 与 Agent 目录结构的关系 - -```diff - data/agents/{id}/ - ├── agent.md - ├── soul.md - ├── identity.md - ├── user.md - ├── tools.md - ├── heartbeat.md - ├── skills/ - ├── memory/ - ├── knowledge/ - ├── workspace/ -+ ├── conversations/ ← 新增: 对话会话目录 -+ │ └── {convId}/ -+ │ ├── meta.json -+ │ ├── history.json -+ │ └── {msgId}/ -+ │ └── messages.log - ├── logs/ - └── config.json -``` - -对话是 Agent 的一部分，而不是全局的——每个 Agent 管理自己的对话历史。 diff --git a/docs/system-design/17-skill-orchestration-and-concurrency.md b/docs/system-design/17-skill-orchestration-and-concurrency.md deleted file mode 100644 index 2b3d4a6..0000000 --- a/docs/system-design/17-skill-orchestration-and-concurrency.md +++ /dev/null @@ -1,71 +0,0 @@ -# 17. Skill Orchestration & Concurrency Architecture - -本文档记录了系统中关于 Skill 管理机制的演进思路，以及为支撑 Innovator 等 Orchestrator 高效执行多目标任务而设计的“并发子代理 (Concurrent Sub-Agent)”架构。我们正式废除了旧有的 SQLite 数据库绑定方案，确立了 **Local File-System First（纯文件系统挂载）** 原则。 - ---- - -## 1. Local File-System First 架构 (移除 SQLite / data/skills 依赖) - -在旧版本中，Skill 系统的可用状态、元数据及其层级关系被同时维护在 `data/skills/` 和本地 `skills.sqlite` 数据库里。这种双源结构经常导致： -- 文件存在但由于数据库未记录，导致技能不可用 (幽灵 Bug)。 -- 修改本地文件（如重写提示词）后热重载失效。 - -### 1.1 核心重构与 `rootdir/skills/` 绝对源头 -目前的纯无状态化架构中，取消了所有的 DB 查询（弃用 `server/services/skill-db` 参与核心运行时计算），直接对原生的目录系统进行实时挂载扫描： -- 系统核心组件 `skill-config-loader.js` 会在每次拉取架构配置时，直接遍历项目根目录下的 `skills/`（即 `path.resolve(__dirname, '../../../skills')`）。 -- 目录存在即技能存在；内部包含 `SKILL.md` 的文件夹将被全自动解析并作为可用 Agent 注入。如果该文件含有 `layer: orchestrator` 或类似的大脑定义，将自动提升为 Orchestrator。 -- 这一改动**完全去除了状态机依赖**并发地保持了 Claude CLI 等底层协议提倡的原始文件驱动属性。 - -### 1.2 注入点 -当我们首次向 Innovator 等代理生成 `system prompt` 时，系统扫描出的 `fullSystemConfig.agents` 配置会实时序列化后填充到提示词中的 `{{AVAILABLE_AGENTS}}` 占位符内，让主代理在没有任何 DB 信息的前提下也能了解当前所有安装的可调用技能池。 - ---- - -## 2. 并发子编排引擎 (Concurrent Orchestration Engine) - -在研究深度报告 (Deep Research) 或网页浏览时，Innovator 通常需要发起对多个独立话题甚至工具的并行调用，以压缩墙上时间（Wall-clock time）。为了支撑该目标，系统对基础解析器（`parser.js`）以及对话驱动路由（`agent-chat.js`）做出了彻底改造。 - -### 2.1 突破串行化拦截 -传统的设计为了维持“因果链 (Causal Chain)”，使用了 `_applySerialConstraint` 强制截取 Agent 产生的最后一个 `[CALL: xxx]` 数据块。现在通过开放 `allowParallel: true` 选项，系统可以从一次输出流中正则匹配出所有的调度请求： -```text -[CALL: meta_research] -分析 AI 的未来发展趋势 -[/CALL] - -[CALL: meta_research] -调查自动驾驶汽车的采用率 -[/CALL] -``` -以上将返回完整的 Calls Array。 - -### 2.2 Promise.all 协程调度 -在 `/api/agent/:agentId/chat` 核心路由中： -- 将串行（`for (const call of calls)`）阻塞迭代替换为了 `await Promise.all()`。 -- 这允许系统在一轮思考响应内，瞬间启动多条 `AgentManager.callAgent()` 协程链路。每一条链路都会实例化独立的底层 Claude 进程并发执行。 - -### 2.3 任务追踪标识 (Unique Call ID) -为了对这些并发运行的环境进行隔离和精准回显追踪，路由在启动任务前会为每一个 Sub-Agent 事件分配一个唯一标识，例如： -`const callId = "sub-" + randomUUID().substring(0, 6)` -向前端的 SSE 事件流中（如 `event: 'chunk'`）挂载该 ID，保证前端不论收到多混乱的异步流交错，都能正确路由进独立的终端。 - ---- - -## 3. 前端多流终端并发 UI (Multi-Terminal UI) - -由于传统的单窗口 `msg-assistant` 已经无法呈现多个异步进程在彼此互不相关的流速下喷吐的状态，为了匹配上述后端能力，并达成震撼的多线程交互体验，在 Vue 侧 (`AgentChat.vue`) 引入了**“多窗口动态并行卡片流 (Parallel Windows)”**： - -### 3.1 状态驱动器 (`subAgents` Ref) -使用字典格式响应式地保存所有的子任务对象： -```javascript -const subAgents = ref({ - 'sub-1a2b3c': { agent: 'meta_research', status: 'running', content: '...' }, - 'sub-9x8y7z': { agent: 'meta_digest', status: 'success', content: '...' } -}); -``` -在收听 `sub_agent` 事件时，通过 `callId` 作为 Key 进行实时内容拼接和状态更新，甚至做到独立容器的自动 `scrollTop = scrollHeight` 下推。 - -### 3.2 动态卡片墙 (Grid Flexbox) -在聊天气泡大外框的末端，通过 CSS Grid 自适应布局 `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` 渲染： -- 当一个 Agent 并发出了三项分支，这三项任务会像控制台界面一般，在横向平整排列。 -- 每一个子容器都拥用专属的 Terminal 等宽字体控制台、带有彩色指示灯（运行中蓝色辉光、完成绿勾、失败红叉）。 -- 所有并行终端运行出各自的结果后（或者任意一条发生中断），后台等待在 `Promise.all` 的阻塞点会统一收束收集它们的汇总返回内容（包裹着 `[Sub Agent 返回结果]`），随后统一塞入主 Agent 的反馈下文继续下一轮迭代。 diff --git a/docs/system-design/18-local-filesystem-first-agent-encapsulation.md b/docs/system-design/18-local-filesystem-first-agent-encapsulation.md deleted file mode 100644 index a966b85..0000000 --- a/docs/system-design/18-local-filesystem-first-agent-encapsulation.md +++ /dev/null @@ -1,45 +0,0 @@ -# 18. Local File-System First 与 Agent 完全自治架构 (v3.5) - -## 1. 架构演进背景 -在早期的 LemonBoss 设计中，技能 (Skills)、对话日志 (Conversations)、系统配置和 Agent 实例是分离的。这导致了三个核心问题： -1. **全局耦合污染**：所有的 Skill 堆砌在外部的 `repo/skills/` 中，当 Innovator 创建新的子 Agent 能力时，很容易造成命名空间冲突或权限越界。 -2. **缺乏运行闭环**：前端、日志存储和运行时配置需要依赖 SQLite 或独立的全局缓存映射，系统状态难以通过简单的文件复制进行迁移和备份。 -3. **Claude CLI 兼容性冲突**：Claude Code CLI 默认从工作空间目录底下的 `.claude/skills/` 挂载原生能力，而我们原本的自定义 `skills/` 与其天然隔离，导致大模型在本地原生工具和自定义 Agent 调度间产生严重的幻觉或抢跑情况。 - -## 2. Agent 的“完全封装” (Encapsulation) -系统现已全线迁移至 **Local File-System First** 和 **“Agent 就是微容器”** 的架构。全局根目录下的 `skills/` 与数据库已被彻底移除。现在的每一位 Agent 都是一个 100% 便携的“自治微容器”。 - -### 2.1 Agent 内部目录结构闭环 -所有 Agent（如 `innovator-001`）统一收拢在 `data/agents/{agentId}/` 下。其数据组织如下： -```text -data/agents/innovator-001/ - ├── config.json ← Agent 基础运行配置项 - ├── identity.md ← Agent 姓名、Emoji 及基础设定 - ├── user.md ← 面对的用户画像预设 - ├── soul.md ← Agent 的性格特征与边界 - ├── tools.md ← Agent 允许使用的外部工具白名单 - ├── memory/ ← Agent 长短期记忆数据库 - ├── conversations/ ← Agent 所有的历史对话记录（原全局级映射下放） - │ └── {convId}/ - │ ├── meta.json - │ ├── history.json - │ └── messages.log - ├── agent.md ← 【核心】Persona 指令（负责统驭“我是谁”） - └── .claude/ - └── skills/ ← 该 Agent 本人拥有的独占子技能挂载区 - ├── main_skill/ - │ └── SKILL.md ← 【核心】Workflow 指令（负责指导“我专业怎么做”） - ├── meta_hunt/ - └── meta_digest/ -``` - -### 2.2 灵肉分离 (Persona vs Capability) -在设计上，将传统臃肿的宏大提示词进行了概念切分： -- **`agent.md`**: 这是一个轻量级的占位符，仅告知 LLM 它的宏观定位（例如：“你是 Innovator 编排总控大脑…”）并以引用指针的方式要求其遵循 `main_skill`。 -- **`.claude/skills/main_skill/SKILL.md`**: 这才是其实际作业指南（包含编排语法 `[CALL:xxx]` 规则、反思规则矩阵、生成文件的指令路径逻辑）。这种划分让 LLM 启动时能像挂载可执行程序一样拥有天然的边界感，同时也完美迎合了 Claude MCP 的结构体系。 - -## 3. 多路并发与无缝切盘 -由于实现了 Agent 单体的绝对封闭自治，后台 Node 服务 `server/routes/agent-chat.js` 也顺势进行了架构级优化： -1. **并发解析**：通过对输出流的拦截，现在单次对话可以触发一个纯文本中包含了多个 `[CALL:]` 块的调度池。底层的 `AgentManager` 将利用 `Promise.all` 齐发请求到各个挂载的 SubAgent 的专用沙盒中执行任务。 -2. **零配置扫描**：服务器不再静态维护全系统的技能库表，而是启动热加载并遍历所有的 `data/agents/*/.claude/skills/` 节点。用户在网页端切换 Agent 头像时，后端路由从对应沙盒目录吐出隔离的 `conversations` List，界面实现极致丝滑的无状态切盘和防死链。 -3. **动态生成**：`meta_creator` 被赋予了全权创世能力。它不再只生成一个孤零零的脚本文档，而是通过 `AgentScaffold.js` 的引擎直接在 `data/agents/` 下开辟一个新的隔离目录，灌入完整的六大配置文件。一个新能力（Agent）的诞生，即代表着文件系统的一次干净合规的增量。 diff --git a/docs/system-design/19-orchestrator-tool-isolation.md b/docs/system-design/19-orchestrator-tool-isolation.md deleted file mode 100644 index b52a543..0000000 --- a/docs/system-design/19-orchestrator-tool-isolation.md +++ /dev/null @@ -1,165 +0,0 @@ -# 19. 编排型 Agent 的工具隔离机制 (Tool Isolation) - -> **关键发现**：仅靠 System Prompt 文字禁令（如 `` 标签）无法阻止 LLM 使用原生工具。 -> 必须在 **Claude CLI 启动参数层面** 物理剥夺工具权限。 - ---- - -## 19.1 问题背景 - -### 现象 -Innovator Master Agent 的 `main_skill/SKILL.md` 中明确标注了 `` 禁令： -``` -❌ `Bash` — 禁止运行任何终端命令 -❌ `Write` / `Read` — 禁止读写任何文件 -``` - -然而在实际运行中，Innovator 仍然频繁调用了 `Bash`、`Write`、`Read`、`Skill`、`TodoWrite`、`TaskOutput` 等原生工具（共 15+ 次违规），**完全无视** prompt 层面的禁令。 - -### 根因分析 -Claude Code CLI 的原生工具（Bash、Write、Read 等）是模型底层自带的能力。在模型的决策优先级中： - -``` -原生工具能力 (内置) >> System Prompt 文字禁令 (注入) -``` - -当模型面对"帮我创建一个写诗的 agent"这类明确需要文件操作的任务时，它会**本能地**、**不可抗拒地**选择自己最擅长的原生工具来执行，而忽略 prompt 中的文字禁令。这不是 prompt 写得不够强的问题，而是**架构层面的权限控制缺失**。 - ---- - -## 19.2 解决方案：CLI 启动参数级工具封印 - -Claude CLI 原生支持以下工具控制参数： - -| 参数 | 作用 | 用法示例 | -|------|------|---------| -| `--tools ""` | **禁用全部原生工具** | `claude --tools ""` | -| `--allowedTools ` | 仅允许指定工具 | `claude --allowedTools "Read"` | -| `--disallowedTools ` | 禁用指定工具 | `claude --disallowedTools "Bash Write"` | - -### 对编排型 Agent 的应用 - -编排型 Agent（如 Innovator）不需要直接操作文件系统，它的唯一职责是输出 `[CALL: agent_name]` 文本块。因此在启动其 Claude CLI 进程时，传入 `--tools ""`，**从操作系统层面物理剥夺所有原生工具权限**。 - -被剥夺工具后，模型只能输出纯文本。后端的 `parser.js` 从纯文本中正则捕获 `[CALL:]...[/CALL]` 块，然后启动对应的子 Agent 进程（子 Agent 保留完整工具权限）。 - ---- - -## 19.3 实现架构 - -### ClaudeCliProtocol 层 -`packages/acp-core/protocol/ClaudeCliProtocol.js` 的 `connect()` 方法新增了工具配置支持： - -```javascript -constructor(agentInfo = {}, options = {}) { - // options.allowedTools = '' → --tools "" - // options.disallowedTools = [...] → --disallowedTools ... -} - -async connect(transport, workingDir) { - const args = ['--input-format', 'stream-json', ...]; - - // 编排型 Agent 工具封印 - if (this.options.allowedTools === '') { - args.push('--tools', ''); - } -} -``` - -### Agent Chat 路由层 -`server/routes/agent-chat.js` 的 `getOrCreateProtocol()` 根据 `config.json` 中的 Agent 类型自动决定工具权限： - -```javascript -const agentConfig = loadAgentConfig(agentDir); - -if (agentConfig.type === 'orchestrator' || agentConfig.type === 'meta') { - cliOptions.allowedTools = ''; // 禁用全部原生工具 -} - -const protocol = new ClaudeCliProtocol({ name }, cliOptions); -``` - -### Agent 类型与工具权限映射 - -| Agent Type | config.json `type` | 工具权限 | 说明 | -|------------|-------------------|---------|------| -| **编排型** (Innovator) | `meta` / `orchestrator` | ❌ 全部禁用 | 只能输出 `[CALL:]` 文本块 | -| **执行型** (meta_hunt 等) | `skill` / `executor` | ✅ 全部开放 | 可用 Bash、Read、Write 等 | - ---- - -## 19.4 验证标志 - -当系统正确运行时，控制台会打印： - -``` -[AgentChat] 🔒 Innovator 启用编排模式: 原生工具已全部禁用 -[ClaudeCliProtocol] 启动: claude --input-format stream-json ... --tools "" -``` - -如果日志中没有 `--tools ""`，说明工具封印未生效，需要检查 `config.json` 的 `type` 字段。 - ---- - -## 19.5 设计原则总结 - -> **Prompt 是建议，参数是法律。** -> -> 对于安全关键的权限控制，永远不要依赖 System Prompt 文字禁令。 -> 必须在进程启动层面通过 CLI 参数或 API 配置进行强制约束。 -> Prompt 中的 `` 标签可以作为**辅助提示**保留，但不能作为**唯一手段**。 - ---- - -## 19.6 父类继承：AgentScaffold 内置工具策略 - -工具隔离策略已内置于 `AgentScaffold` 父类（`packages/agent-core/AgentScaffold.js`）。 -**所有通过脚手架创建的新 Agent 都会自动继承正确的工具权限**，无需手动配置。 - -### config.json 自动生成的 `cli.toolPolicy` 字段 - -```json -{ - "id": "classical_poetry_writer", - "type": "skill", - "cli": { - "toolPolicy": {} - } -} -``` - -```json -{ - "id": "innovator-001", - "type": "meta", - "cli": { - "toolPolicy": { "allowedTools": "" } - } -} -``` - -### 类型与策略映射表（定义在 AgentScaffold._writeConfig） - -| Agent Type | `cli.toolPolicy` | 效果 | -|------------|-----------------|------| -| `master` | `{ allowedTools: '' }` | 禁用全部原生工具 | -| `meta` | `{ allowedTools: '' }` | 禁用全部原生工具 | -| `orchestrator` | `{ allowedTools: '' }` | 禁用全部原生工具 | -| `cxo` | `{ allowedTools: '' }` | 禁用全部原生工具 | -| `role` | `{}` | 保留全部工具 | -| `skill` | `{}` | 保留全部工具 | -| `executor` | `{}` | 保留全部工具 | - -### 运行时读取链路 - -``` -AgentScaffold._writeConfig() → config.json 写入 cli.toolPolicy - ↓ -agent-chat.js: getOrCreateProtocol() → 读取 config.cli.toolPolicy - ↓ -ClaudeCliProtocol.connect() → 拼接 --tools "" 或 --disallowedTools - ↓ -claude CLI 进程 → 物理层面工具权限已确定 -``` - -> 旧版 Agent（config.json 中没有 `cli` 字段）通过 type 字段做兼容性回退。 diff --git a/docs/system-design/20-scaffold-first-agent-creation.md b/docs/system-design/20-scaffold-first-agent-creation.md deleted file mode 100644 index 61fc387..0000000 --- a/docs/system-design/20-scaffold-first-agent-creation.md +++ /dev/null @@ -1,244 +0,0 @@ -# 20. Agent 创建流程：Scaffold-First 架构 - -> **核心原则：先建骨架，再填内容。** -> Agent 目录必须先通过 AgentScaffold 父类创建，后续的 Hunt/Digest 才能往里面写文件。 - ---- - -## 20.1 Create 流程（五阶段严格串行） - -当 Innovator 需要创建一个全新的 Agent 时，严格按照以下五个阶段串行执行： - -``` -Scaffold → Hunt → Digest → Evolve → Execute - │ │ │ │ │ - ▼ ▼ ▼ ▼ ▼ - 创建骨架 调研写入 消化提炼 验证测试 执行任务 -``` - -### 阶段 1: Scaffold（脚手架创建骨架） - -**由引擎硬编码执行，不依赖 LLM。** - -当 Innovator 输出 `[CALL: meta_creator]` 时，`agent-chat.js` 中的 `executeMetaCreator()` 函数直接调用 `AgentScaffold.create()`，在 `data/agents/{agent_name}/` 下生成完整的标准目录结构： - -``` -data/agents/{agent_name}/ -├── agent.md ← 身份定义 -├── soul.md ← 灵魂人格 -├── identity.md ← 标识信息 -├── user.md ← 用户关系 -├── tools.md ← 工具权限 -├── heartbeat.md ← 心跳任务 -├── config.json ← 配置（含 cli.toolPolicy） -├── .claude/skills/ -│ └── main_skill/ -│ └── SKILL.md ← 核心技能（初始为空壳） -├── memory/ -│ ├── short-term/ -│ ├── long-term/ -│ ├── sessions/ -│ └── daily/ -├── knowledge/ ← Digest 阶段写入 knowhow/benchmark -├── workspace/ ← 自治工作区 -│ ├── code/ -│ ├── data/ -│ └── assets/ -├── train/ ← Hunt 阶段写入的调研和训练数据 -└── logs/ -``` - -### 阶段 2: Hunt（知识狩猎） - -**执行型子 Agent，有完整工具权限。** - -meta_hunt 在新建 Agent 的目录下运行，将调研结果写入该 Agent 的 `train/` 目录： - -``` -data/agents/{agent_name}/train/ -├── knowhow.md ← 方法论调研 -├── toplist.md ← 标杆案例 -├── agent_profile.md ← Agent 人格画像（思维、风格、工具、心跳、用户关系） -└── crawl/ ← 爬取数据 - ├── source_01.md - └── source_02.md -``` - -### 阶段 3: Digest（知识消化） - -**执行型子 Agent，读取 train/ 的调研数据，提炼输出到 knowledge/ 和 SKILL.md，并基于 agent_profile 生成定制化 Bootstrap 文件。** - -``` -输入: train/knowhow.md + train/toplist.md + train/agent_profile.md + train/crawl/ -输出: - ├── knowledge/knowhow.md ← 精炼后的方法论 - ├── knowledge/benchmark.md ← 评分标准（≥5个维度） - ├── .claude/skills/main_skill/SKILL.md ← 基于方法论生成的核心技能 - ├── agent.md ← 身份定义、职责、规则（基于 agent_profile） - ├── soul.md ← 思维方式、沟通风格、价值观 - ├── tools.md ← 工具权限和文件操作范围 - ├── heartbeat.md ← 自检频率和质量监控规则 - └── user.md ← 与用户/上级的关系定义 -``` - -### 阶段 4: Evolve（验证进化） - -用测试用例验证新 Agent 的输出质量，对照 `knowledge/benchmark.md` 评分。 - -### 阶段 5: Execute（执行用户任务） - -Agent 已创建并验证通过，直接调用执行用户最初的需求。 - ---- - -## 20.2 meta_creator 引擎级拦截 - -### 为什么不让 Claude 子进程执行 meta_creator？ - -| 方案 | 可靠性 | 问题 | -|------|--------|------| -| Claude 拼 curl 命令调 scaffold API | ⚠️ 低 | LLM 可能拼错 JSON、遗漏字段、URL 写错 | -| Claude 用 Write 工具手动建目录 | ❌ 极低 | 会漏掉标准子目录、忘记写 config.json | -| **引擎硬编码执行 AgentScaffold** | ✅ 100% | 代码确定性执行，不依赖 LLM | - -### 实现位置 - -`server/routes/agent-chat.js` 中的子 Agent 调度循环： - -```javascript -// ═══ 硬编码拦截: meta_creator → 直接调用 AgentScaffold 父类 ═══ -if (call.agent === 'meta_creator') { - res = await executeMetaCreator(call.task, agentId, convId, sendSSE, callId); -} else { - res = await agentManager.callAgent(call.agent, call.task, { ... }); -} -``` - -### executeMetaCreator 执行逻辑 - -1. **解析参数** — 从 Innovator 的任务文本提取 agent_name、display_name、domain -2. **调用 AgentScaffold.create()** — 生成完整目录结构 + bootstrap 文件 -3. **写入初始 SKILL.md** — 基于任务描述生成空壳 SKILL.md（后续由 Digest 填充） -4. **返回结构化结果** — 包含创建的目录列表，供 Innovator Reflect 验证 - ---- - -## 20.3 子 Agent 工作目录 - -### 问题 - -所有子 Agent 的 Claude CLI 进程之前都运行在项目根目录 `lemonboss/`，导致： -- Claude CLI 读不到 `.claude/skills/` 下的 l1/l2 知识文件 -- Hunt 的输出写到错误的位置 - -### 解决方案 - -`agent-manager.js` 的动态 Agent 发现逻辑现在会计算正确的工作目录： - -```javascript -// 独立 Agent → 运行在 Agent 自己的目录下 -agentConfig.workDir = agentDir; // data/agents/{agentName}/ - -// Scoped Skill → 运行在所属 Agent 的目录下 -const ownerAgentDir = path.dirname(path.dirname(path.dirname(foundPath))); -agentConfig.workDir = ownerAgentDir; // data/agents/innovator-001/ -``` - -`_runViaProtocol()` 优先使用 agent-specific workDir： - -```javascript -const effectiveWorkDir = agent.workDir || this.workDir; -``` - -### 效果 - -- meta_hunt 运行在 `data/agents/innovator-001/`，自动读取全部 18 个 SKILL.md 作为知识上下文 -- 新创建的 Agent 运行时能读取自己目录下的 `.claude/skills/` - -### 路径约定（⚠️ 关键） - -由于 meta_hunt/meta_digest 等子 Agent 运行在 `data/agents/innovator-001/` 目录下， -所有指向其它 Agent 的路径都必须使用 **`../{agent_name}/`** 格式（上一级的兄弟目录）： - -``` -正确: ../{agent_name}/train/knowhow.md -错误: data/agents/{agent_name}/train/knowhow.md ← 会变成嵌套路径！ -错误: train/knowhow.md ← 会写到 innovator-001 自己的目录 -``` - -目录结构关系： -``` -data/agents/ -├── innovator-001/ ← 子 Agent CLI 的 CWD -│ ├── .claude/skills/ ← l1/l2 知识文件 -│ └── workspace/ ← innovator 自己的工作区 -├── poetry_writer/ ← ../ poetry_writer/ 可以访问到 -│ ├── train/ ← Hunt 写入这里 -│ ├── knowledge/ ← Digest 写入这里 -│ └── .claude/skills/ ← Digest 生成 SKILL.md 到这里 -└── other_agent/ -``` - ---- - -## 20.4 l1/l2 Skill 角色定位 - -### 当前架构（执行型，v1） - -l1/l2 SKILL.md 文件作为**知识手册**，被 Claude CLI 进程自动读取。 -meta_hunt 等执行型 Agent 参考这些知识，**直接使用原生工具**（Bash、Read、Write）执行任务。 - -``` -meta_hunt (执行型, 有工具权限) - ├── 参考 l2-web-research/SKILL.md → 了解搜索方法 - ├── 参考 l1-web-fetch/SKILL.md → 了解爬取方法 - └── 直接用 Bash curl 执行搜索和爬取 -``` - -### 未来架构（递归编排型，v2） - -每个 l1/l2 作为独立子 Agent 通过 `[CALL:]` 调度： - -``` -meta_hunt (编排型, 无工具) - ├── [CALL: l2-web-research] → 独立 CLI 进程 - │ ├── [CALL: l1-search-engine] → 独立 CLI 进程 - │ └── [CALL: l1-web-fetch] → 独立 CLI 进程 - └── [CALL: l1-text-transform] → 独立 CLI 进程 -``` - -v2 需要 `agentManager.callAgent()` 支持递归 `[CALL:]` 解析，并加入 `maxDepth` 防止死循环。 - ---- - -## 20.5 数据流向图 - -``` -用户: "帮我创建一个写诗的 Agent" - │ - ▼ -Innovator (--tools "", 纯文本编排) - │ - ├── [CALL: meta_creator] ──▶ 引擎硬编码 ──▶ AgentScaffold.create() - │ 创建 data/agents/poetry_writer/ (模板 Bootstrap) - │ - ├── [CALL: meta_hunt] ──▶ Claude CLI (cwd: innovator-001/) - │ 读取 .claude/skills/l1-*/l2-* 知识 - │ 用 Bash/curl 搜索调研 - │ 写入 data/agents/poetry_writer/train/ - │ └── knowhow.md + toplist.md + agent_profile.md - │ - ├── [CALL: meta_digest] ──▶ Claude CLI (cwd: innovator-001/) - │ 读取 train/ (knowhow + toplist + agent_profile) - │ 提炼写入 knowledge/knowhow.md + benchmark.md - │ 生成 .claude/skills/main_skill/SKILL.md - │ 生成 Bootstrap: agent.md, soul.md, tools.md, - │ heartbeat.md, user.md - │ - ├── [CALL: meta_evolving] ──▶ Claude CLI (cwd: poetry_writer/) - │ 运行测试用例 - │ 对照 benchmark 评分 - │ - └── [CALL: poetry_writer] ──▶ Claude CLI (cwd: poetry_writer/) - 执行用户的原始需求 -``` diff --git a/docs/system-design/21-fde-pipeline-architecture.md b/docs/system-design/21-fde-pipeline-architecture.md deleted file mode 100644 index bf29c38..0000000 --- a/docs/system-design/21-fde-pipeline-architecture.md +++ /dev/null @@ -1,282 +0,0 @@ -# 21. FDE Pipeline Architecture — Hunt→Digest→Evolving 训练流水线 - -> **版本**: v1.1 -> **日期**: 2026-03-26 -> **状态**: ✅ 端到端验证通过（质量门禁 ≥ 95 分） - ---- - -## 一、总览 - -FDE (Hunt→Digest→Evolving) 是 LemonBoss 的 **Agent 技能训练流水线**。 -通过三个独立的元 Agent 依次执行知识猎取、数据消化、迭代进化， -最终为目标 Agent 生成达到行业标杆水平的 SKILL.md。 - -``` -[训练目标: 训练 CEO 的领导力技能] - │ - ▼ Innovator 编排 - │ - ├─ Layer 1: HUNT ──→ Hunter Agent - │ 输入: domain + keywords - │ 输出: knowhow.md + toplist.md + crawl/ - │ - ├─ Layer 2: DIGEST ──→ Digester Agent - │ 输入: hunt/ 产出 - │ 输出: benchmark_v1.md + good/bad testdata + feature_analysis.md - │ - └─ Layer 3: EVOLVE ──→ Evolver Agent - 输入: digest/ 产出 - 输出: 达标 SKILL.md (score ≥ 95) + evolve_log.md -``` - ---- - -## 二、元 Agent 职责矩阵 - -| 元 Agent | Skill | 角色 | 核心能力 | -|----------|-------|------|---------| -| **Innovator** | innovator-skill | 编排者 | FDE 流水线调度、OKR 管理 | -| **Hunter** | l3-hunt | 知识猎手 | 6-Phase 研究流程 (搜索→标杆→爬取→洞察) | -| **Digester** | l2-digest | 数据消化 | Benchmark 设计 + 数据标注 + 特征提取 | -| **Evolver** | evolving | RL 训练 | 执行→评分→分析→改写→重复 循环 | - -### 依赖技能拓扑 - -``` -Evolver ─────────────────────── (无额外依赖, 纯推理循环) -Digester ──→ l1-data-extract, l1-text-transform, l1-file-read, l1-diff-checker -Hunter ────→ l1-search-engine, l1-web-fetch, l2-web-research, - l1-data-extract, l1-text-transform, l1-file-read, l1-kv-store -``` - -所有依赖技能的 SKILL.md 必须放在元 Agent 的 `.claude/skills/` 目录下， -由 `buildSystemPrompt()` 自动扫描并注入 system prompt。 - ---- - -## 三、双路径产出规范 ⭐ - -每个元 Agent 的产出 **同时写入两个位置**： - -| 路径 | 用途 | 示例 | -|------|------|------| -| `data/train/{targetAgentId}/{phase}/` | 综合训练区，元 Agent 间共享 | `train/ceo/hunt/` | -| `data/agents/{targetAgentId}/{phase}/` | Agent 资产，归属目标 Agent | `agents/ceo/hunt/` | - -``` -data/ -├── {companyId}/train/{targetAgentId}/ ← 训练数据区 (元 Agent 间共享) -│ ├── hunt/ -│ ├── digest/ -│ └── evolve/ -└── {companyId}/agents/{targetAgentId}/ ← 目标 Agent 的资产 - ├── hunt/ ← Hunter 写入 - ├── digest/ ← Digester 写入 - ├── evolve/ ← Evolver 写入 - └── .claude/skills/main_skill/SKILL.md ← Evolver 安装最终版 -``` - -> **注意**: 全局元 Agent (如 Hunter/Digester/Evolver) 位于 `system/agents/`。 -> 对于全局训练任务，路径前缀为 `system/`。 - -**原则**: 先写到 train/，再用 `cp -r` 复制到 agents/。 - ---- - -## 四、各 Layer 产出规范 - -### Layer 1: Hunt 产出 - -``` -{targetAgentId}/hunt/ -├── knowhow.md ← 方法论 + 最佳实践 + 原创洞察 -├── toplist.md ← 排行榜 + 标杆案例 + 推荐资源 -└── crawl/ ← 爬取的标杆数据 - ├── elite_01_{title}.md ← 分级: elite (score ≥ 70) - ├── elite_02_{title}.md - └── avg_01_{title}.md ← 分级: average (score < 70) -``` - -**质量标准**: -- ≥80% 核心子问题覆盖 -- ≥10 独立信源，关键数据 ≥2 交叉验证 -- ≥3 条原创洞察 -- ≥1500 字 - -### Layer 2: Digest 产出 - -``` -{targetAgentId}/digest/ -├── benchmark_v1.md ← 评分标准 (5-8 维度 + Rubric) -├── knowhow.md ← 从 hunt 继承 (可补充) -├── feature_analysis.md ← Good/Bad 特征分析 -├── industry_baseline.md ← 行业基线 -├── dataset.json ← 结构化数据集 -├── good_testdata/ -│ ├── good_01_{title}.md ← score ≥ 70 -│ └── ... -└── bad_testdata/ - ├── bad_01_{title}.md ← score < 70 - └── ... -``` - -**Benchmark 必须包含**: -- 5-8 个评分维度 (权重和 = 100%) -- 每维度 Detailed Rubric (5 级) -- pass_score / industry_avg_score / elite_avg_score - -### Layer 3: Evolve 产出 - -``` -{targetAgentId}/evolve/ -├── evolve_log.md ← 完整训练日志 -├── v1/ -│ ├── skill.md ← 版本快照 -│ ├── result.md ← 执行输出 -│ └── score.json ← 维度评分 -├── v2/ -│ └── ... -└── v{N}/ ← 达标版本 -``` - -**停止条件**: -- score ≥ 95 → 达标 ✅ -- iterations ≥ maxIterations → 超时 ⚠️ -- 连续 3 次分数变化 < 2 → 停滞 ⚠️ - ---- - -## 五、Dispatch 协议 - -### Innovator → Hunter - -```bash -curl -s -X POST http://localhost:3000/api/agent/task/dispatch \ - -H "Content-Type: application/json" \ - -d '{ - "from": "innovator", - "to": "hunter", - "task": "对 CEO 核心能力进行知识猎取。skillName: ceo_leadership, targetAgentId: ceo, domain: CEO战略管理与领导力, keywords: [CEO战略规划, OKR目标管理]。按 l3-hunt skill 执行。产出同时写入 ../../train/ceo/hunt/ 和 ../ceo/hunt/。", - "priority": "P0", - "autoExecute": true - }' -``` - -### Innovator → Digester - -```bash -curl -s -X POST http://localhost:3000/api/agent/task/dispatch \ - -H "Content-Type: application/json" \ - -d '{ - "from": "innovator", - "to": "digester", - "task": "消化 CEO 调研数据。skillName: ceo_leadership, targetAgentId: ceo。输入: ../../train/ceo/hunt/。按 l2-digest skill 执行。产出同时写入 ../../train/ceo/digest/ 和 ../ceo/digest/。", - "priority": "P0", - "autoExecute": true - }' -``` - -### Innovator → Evolver - -```bash -curl -s -X POST http://localhost:3000/api/agent/task/dispatch \ - -H "Content-Type: application/json" \ - -d '{ - "from": "innovator", - "to": "evolver", - "task": "训练 CEO 的 ceo_leadership 技能。targetAgentId: ceo。输入: ../../train/ceo/digest/。按 evolving skill 执行 Small Loop。passThreshold: 90, maxIterations: 5。产出同时写入 ../../train/ceo/evolve/ 和 ../ceo/evolve/。训练完成后安装到 ../ceo/.claude/skills/main_skill/SKILL.md。", - "priority": "P0", - "autoExecute": true - }' -``` - ---- - -## 六、关键代码修复 - -### buildSystemPrompt 扫描所有 skills 子目录 - -**问题**: `server/routes/agent-chat.js` 的 `buildSystemPrompt()` 函数只加载了 -`main_skill/SKILL.md`，没有扫描其他 skill 子目录。导致 Hunter 等元 Agent -看不到依赖技能 (l1-search-engine 等) 的定义。 - -**修复** (line 302+): -```javascript -// ── 扫描所有 skill 子目录的 SKILL.md ── -const skillsDir = path.join(agentDir, '.claude', 'skills'); -if (fs.existsSync(skillsDir)) { - const entries = fs.readdirSync(skillsDir, { withFileTypes: true }); - for (const entry of entries) { - if (!entry.isDirectory() || entry.name === 'main_skill') continue; - const skillMdPath = path.join(skillsDir, entry.name, 'SKILL.md'); - if (fs.existsSync(skillMdPath)) { - const skillContent = fs.readFileSync(skillMdPath, 'utf-8').trim(); - if (skillContent) { - parts.push(`---\n\n## 依赖技能: ${entry.name}\n\n${skillContent}`); - } - } - } -} -``` - -**效果**: Hunter prompt 从 9290 chars → 22263 chars（注入了所有 L1/L2 技能定义）。 - ---- - -## 七、验证结果 — CEO Agent 训练记录 - -### 7.1 训练时间线 - -| 时间 | 阶段 | Task ID | 耗时 | -|------|------|---------|------| -| 17:49 | Hunt | T-mn4fnkum | ~10 min | -| 23:25 | Digest | T-mn4rocqy | ~20 min | -| 23:49 | Evolve | T-mn4sin8i | ~15 min | - -### 7.2 产出统计 - -| Layer | 文件数 | 总行数 | 关键产出 | -|-------|--------|--------|---------| -| **Hunt** | 8 | 1,461 | knowhow 420行、toplist 231行、6 crawl 样本 | -| **Digest** | 11 | 1,593 | benchmark 255行、5 good/1 bad testdata | -| **Evolve** | 3 | — | v2 (87分) → v3 (92分) | - -### 7.3 Evolve 迭代记录 - -| 版本 | 总分 | 战略(20%) | OKR(20%) | 可操作(15%) | 案例(15%) | 理论(15%) | 适用(15%) | -|------|------|-----------|----------|-------------|-----------|-----------|-----------| -| v1 | **40** ❌ | 35 | 45 | 60 | 20 | 30 | 50 | -| v2 | **87** ❌ | 90 | 90 | 85 | 85 | 85 | 85 | -| v3 | **92** ✅ | 95 | 95 | 92 | 90 | 90 | 88 | - -### 7.4 最终 CEO SKILL.md - -```yaml -name: ceo_leadership -version: 2.3.0 -benchmark_score: 92 -``` - ---- - -## 八、架构决策记录 - -| # | 决策 | 原因 | 日期 | -|---|------|------|------| -| 1 | 双路径产出 (train + agents) | 元 Agent 间共享 + 目标 Agent 资产归属 | 03-24 | -| 2 | 依赖技能放 `.claude/skills/` | Claude CLI 自动发现，buildSystemPrompt 自动注入 | 03-24 | -| 3 | 先写 train 再 cp agents | train 为主源，agents 为副本 | 03-24 | -| 4 | Evolver 安装最终 SKILL.md | 训练完成后直接更新目标 Agent 的核心技能 | 03-24 | -| 5 | retrain-pipeline 对齐 agent 名 | `l3-hunt`→`hunter`, `l2-digest`→`digester`, `innovator-evolver`→`evolver` | 03-25 | - ---- - -## 九、文件路径索引 - -| 文件 | 用途 | -|------|------| -| `system/agents/innovator/.claude/skills/main_skill/SKILL.md` | Innovator 编排技能 | -| `system/agents/trend-hunter/` | Hunter 元 Agent | -| `server/routes/agent-chat.js:buildSystemPrompt()` | System Prompt 构建 (含 skills 扫描) | -| `server/services/retrain-pipeline.js` | FDE 重训流水线 (已对齐 agent 名) | diff --git a/docs/system-design/22-agent-memory-system.md b/docs/system-design/22-agent-memory-system.md deleted file mode 100644 index b2139dc..0000000 --- a/docs/system-design/22-agent-memory-system.md +++ /dev/null @@ -1,159 +0,0 @@ -# 22. Agent Memory System — 自动记忆读写架构 - -> **版本**: v1.1 (已实现 / 生产可用) -> **日期**: 2026-03-25 -> **状态**: ✅ 已完成 (Phase 1, 2, 3 全部上线，E2E测试 27/27 通过) -> **前置**: Phase 3.5 FDE 已完成，Phase 4 认知架构的核心部分 - ---- - -## 一、核心问题与解决方案 - -当前 Agent 每次新对话都是**完全失忆**的。 -为此，我们设计并实现了一套包含 **MVP基础记忆**、**海马体&小脑检索**、**自动反思与长期合并** 的三阶段进化架构，真实解决： -1. Agent **自动记住**做过什么、学到什么、犯过什么错。 -2. Agent 接到新任务时**自动想起**相关经验（按关键词计算关联度）。 -3. 好的多步方案**自动固化**到小脑，下次遇到同类任务精准触发复用。 - ---- - -## 二、目录结构 - -每个 Agent 的记忆文件严格按以下结构持久化在 `data/agents/{agent-id}/memory/` 下： - -``` -memory/ -├── memory.md ← 核心记忆（关键事实/已验证模式/失败教训），每次全量注入 prompt -├── hippocampus.md ← 海马体：情景→方案的映射（Markdown，人类可读） -├── hippocampus-index.json ← 海马体机器索引，用于关键词匹配检索和分值计算 -├── cerebellum/ ← 小脑：固化的执行方案（.md 步骤指导） -├── short-term/ ← 短期记忆：近期 session 的纯文本摘要，包含执行数据 -├── long-term/ ← 长期记忆：合并过期的短期记忆提取的 keyword 频率与长文归档 -├── reflections/ ← 反思日志：每次高复杂度任务自动提取的模式与教训存放处 -└── daily/ ← 日报：汇总当天的对话、反思和新生方案 -``` - ---- - -## 三、数据流全景 - -``` -┌─────────────────────────────────────────────────────────┐ -│ 新对话开始 │ -│ │ │ -│ ┌───────────────────▼──────────────────┐ │ -│ │ 1. READ: 挂载记忆(buildSystemPrompt) │ │ -│ │ ├── memory.md (全量注入 prompt) │ │ -│ │ ├── 海马体精准匹配(用户输入+todo) │ │ -│ │ ├── 短期记忆(最近 N 个 session) │ │ -│ │ └── 小脑方案(如果匹配到海马体) │ │ -│ └───────────────────┬──────────────────┘ │ -│ │ │ -│ ▼ │ -│ [ Agent 执行任务 ] │ -│ │ │ -│ ┌───────────────────▼──────────────────┐ │ -│ │ 2. WRITE: 自动存储记忆(Chat 完成后) │ │ -│ │ ├── 生成 session 摘要 → short-term│ │ -│ │ ├── 提取关键事实 → memory.md │ │ -│ │ ├── 高复杂度任务自动触发 Reflection │ │ -│ │ └── 好方案自固化 → cerebellum/ │ │ -│ └───────────────────┬──────────────────┘ │ -│ │ │ -│ ┌───────────────────▼──────────────────┐ │ -│ │ 3. CONSOLIDATE (长期沉淀 API) │ │ -│ │ ├── 短期摘要过期 → 合并 long-term │ │ -│ │ ├── 提取高频关键词 → patterns.md │ │ -│ │ ├── daily/ 日报生成 │ │ -│ │ └── 遗忘机制及索引整理 │ │ -│ └──────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - ---- - -## 四、实现复盘 — Todo List 全部点亮 - -### Phase 1: 最小可行记忆 (MVP) 🎯 - -> **目标**：Agent 不再失忆，每次对话的关键信息自动留存 -> **结果**：完美运行，自动提取生成轻量摘要 - -- [x] **1.1 对话结束自动生成 session 摘要** - - 在 `agent-chat.js` 内捕获对话完毕事件，提取 `meta.json` 里的基本信息结合对话产出生成 Markdown 概要，存入 `short-term/session-{timestamp}.md`。 -- [x] **1.2 短期记忆注入 system prompt** - - `buildSystemPrompt()` 会反向加载最新的 5 个 `session-*.md` 摘要。 -- [x] **1.3 memory.md 自动追加关键事实** - - ToolCallCounts > 0 时，自动从任务文本和最终回应抓取一两句话，追加为 `[时间] 任务 → 结果` 写入 `memory.md` 的“关键事实”段落。 -- [x] **1.4 memory.md 大小控制** - - 自带 2000 字符控制，如果超过会安全截断旧记录。 - ---- - -### Phase 2: 海马体检索 + 小脑固化 🧠 - -> **目标**：Agent 能检索相关经验，好方案自动复用 -> **结果**：实现基于自研评分机制与语境保护的轻量检索系统 - -- [x] **2.1 海马体索引结构定义** - - 数据结构存储于 `hippocampus-index.json`，并每次变动都会用 `syncHippocampusMd` 同步至人类友好版表格 `hippocampus.md`，追踪使用次数(useCount)与置信度。 -- [x] **2.2 海马体匹配引擎 (自研提词匹配器)** - - 实现于 `memory-service.js:retrieveRelevantPlans`。 - - **关键修复**：由于历史任务的英文 JSON 记录容易截断最新的中文分词，提词引擎 (`extractKeywords`) 已升级为“截取前1500字符 + 优先保护中文短词提取 + 容量扩大至 50 词汇”，同时在 prompt 拼接时让新的 `userMessage` 置顶，精准保证任何海马体历史都能被识别和唤起。 -- [x] **2.3 小脑方案写入与索引自动更新** - - 实现 `saveCerebellumPlan` 接口和后端逻辑。存储 MD 方案进入 `cerebellum/` 并安全覆盖和递增 `hippocampus` 表的使用次数。 - ---- - -### Phase 3: 反思引擎 + 长期沉淀 🧬 - -> **目标**：Agent 能自主学习，经验自动沉淀 -> **结果**：实现了免唤起 LLM 的“规则型反思引擎”，大幅度降低了 API Cost，但又完美提取并分类总结了信息。 - -- [x] **3.1 反思引擎 (`autoReflect`)** - - 不做毫无意义的次次反思。仅在：`toolCallCount ≥ 3`，或 `duration ≥ 60s` 时自动触发。 - - 成功任务 → 提取到 patterns（模式），5 次及以上 tool calls 更是会触发**自动写入小脑执行步骤**。 - - 失败任务 (status='failed') → 提取到 lessons（教训）。 - - 所有原始细节封存进 `reflections/` 作为 JSON 参考。 -- [x] **3.2 反思结果自动反馈给当前 Prompt** - - 新学习到的 patterns 和 lessons 会立刻被追加回 `memory.md` 的对应栏位里，下一次回答时 Agent 即可利用。 -- [x] **3.3 短期记忆合并到长期记忆 (`consolidateMemory`)** - - 通过 `/api/agent/:agentId/memory/consolidate` API 触发。 - - 自动扫除 > 7天以上的 `short-term` 记录，统合写入 `long-term/consolidate-{date}.md` 并通过关键词聚合提取模式。 -- [x] **3.4 日报与统计 (`generateDailyReport`)** - - 每天生成 `daily/YYYY-MM-DD.md` 包含对话量、反思数及新知识增幅。 - ---- - -## 五、关键技术决策（最新版） - -| # | 问题 | 决策 | 收益/说明 | -|---|------|------|------| -| 1 | session 摘要生成方式 | **无 LLM，纯逻辑提取** | 不增加任何 Token 和耗时开销，完全透明。 | -| 2 | 海马体匹配算法 | **中英双优 ngram 关键词打分** | 以 `hits / keywords` 定比率。免装向量库。通过拦截前排中文字段保证了召回率 (> 0.3 即命中)。 | -| 3 | memory.md 注入方式 | **全量 + 最近 5 session** | 整体记忆控制在最佳窗口容差内，避免爆掉模型的 Attention 机制。 | -| 4 | 反思引擎实现 | **纯代码规则引擎** | 旧设计想用 LLM 生成，但考虑到海量废话，现改为通过对话信息解析直接生成结构化数据，速度瞬间出结果并准确反馈。 | - ---- - -## 六、验证标准及结果 - -以下 E2E 自动化测试用例位于 `server/scripts/test-memory-e2e.js` 并在 `2026-03-25` 完成验证。 - -### Phase 1 验收 (✅ Pass) -- [x] 与 Agent 对话一次 → `short-term/` 出现新 session 文件 -- [x] 第二次对话 → system prompt 中能看到"近期记忆"段并成功被 Agent 引述 -- [x] 多次对话后 → `memory.md` 有新追加的关键事实 - -### Phase 2 验收 (✅ Pass) -- [x] 使用 API 保存小脑方案，JSON 索引建立。 -- [x] 派发强关键词匹配任务 → 海马体引擎拦截命中，Prompt 体积扩大，被方案包围。 -- [x] 成功命中后，后端日志展现 `🐴 海马体命中`，海马体 UseCount 累增。 - -### Phase 3 验收 (✅ Pass) -- [x] 伪造高工具调用对话 → 触发反思引擎，`memory.md` 写入已验证模式。 -- [x] 伪造报错退出对话 → 触发反思引擎，写入失败教训。 -- [x] POST 触发 `/consolidate` → 短期记忆消失，清算存入 Long-Term。 -- [x] POST 触发 `/daily-report` → 生成包含了当天统计和反思日志指引的日报 Markdown。 - -🎉 **[E2E Suite]: ALL PASSED (27/27) - 核心模块生产就绪！** diff --git a/docs/system-design/23-agent-active-heartbeat.md b/docs/system-design/23-agent-active-heartbeat.md deleted file mode 100644 index 65ca366..0000000 --- a/docs/system-design/23-agent-active-heartbeat.md +++ /dev/null @@ -1,101 +0,0 @@ -# 23. Agent Active Heartbeat System — 主动心跳与监控架构 - -> **版本**: v2.0 (已实现) -> **日期**: 2026-03-26 -> **状态**: ✅ 已完成 (Agent 级 + 公司级心跳均已上线) -> **前置**: Phase 3 记忆架构已完成，OKR 目标大盘已上线 - ---- - -## 一、需求背景与痛点 - -当前的 LemonBoss 架构中，所有的 Agent（包含管理者、执行者、QA 仲裁者等）都处于**“被动响应”**状态。 -即：只有当人类或者其他 Agent 发送一条消息（如 `TaskDispatch` 或直接 Chat），它们才会被唤醒并进行一轮推理和动作执行。 - -**痛点：** -随着 OKR 系统（Goal Nodes）复杂度的增加，如果一个任务的负责人（Owner）迟迟不推进进度，或者产出质量不达标。在没有外部输入时，系统的主节点（如 `qa-judge` 质量裁判，或者 `master` 主节点）只能一直假死等待，这严重违背了“**自主智能体（Autonomous Agent）**”能在后台 24/7 监控并主动下发指令的设计初衷。 - -**目标：** -使特定的高级 Agent（如 `qa-judge`）具备内建的相对时间感知能力。通过实现一套主推的“心跳机制（Active Heartbeat）”，使其能每隔 N 分钟自动“苏醒”，根据当前注入体内的 OKR 目标大盘数据，主动进行一次进度巡检、质量总结，并主动向下游 Agent 节点派发反馈任务或催办通知。 - ---- - -## 二、架构设计原理 - -由于 LLM（如 Claude）本身是无状态、无法自主定时的算法黑盒，我们必须通过 Node.js 后端作为起搏器（Pacemaker）来主动触碰 Agent 的执行核心。 - -### 1. 核心流程图 - -```mermaid -sequenceDiagram - participant Cron as Node.js Heartbeat Service - participant Goal as OKR / Goals Data - participant Agent as qa-judge (Agent) - participant Worker as poet (Downstream Agent) - - loop 每 N 分钟 - Cron->>Goal: 获取当前活跃的 OKR 大盘状态 - Cron->>Agent: [SYSTEM HEARTBEAT] 唤醒 (无前端UI展示) - Note over Agent: 挂载 memory、heartbeat.md 及最新 Goal Context - Agent->>Agent: 推理分析 (是否有节点超时/待验收？) - - alt 需要干预 - Agent->>Worker: API调用: TaskDispatch (催促或驳回重做) - Agent->>Agent: "已向负责人发送警告" - else 一切正常 - Agent->>Agent: "保持观察，无需操作" - end - Agent-->>Cron: 结束本次心跳推理 (保存 session 记录入短期记忆) - end -``` - -### 2. 参与模块设计 - -#### (1) 后端起搏器 (`server/services/heartbeat-service.js`) -- 系统级别的 `setInterval` 或使用 `node-cron` 定时任务管理器。 -- 模块初始化时，读取注册了 `cron.json` 或在 `config.json` 中配置了 `active_heartbeat: true` 的全网 Agent。 -- 按设定时间周期（如每 5 分钟、或 15 分钟），发起内部进程级或 HTTP `POST /api/agent/:id/chat` 请求。 -- **消息构造**：必须带有特殊的标记，如 `[SYSTEM HEARTBEAT] 这是系统周期心跳。时间：{当前时间}。如果无需采取行动，请只回复[心跳正常]；如果发现 OKR 或任务阻塞，请使用你的 dispatch 工具发送跟进动作。` - -#### (2) Agent 身份与职责声明 (`data/agents/qa-judge/heartbeat.md`) -这部分将作为心跳特供的系统注入层。因为 Agent 被系统唤醒后可能“不知所措”，所以需要在注入时提供明确的**心跳策略**。 -- `qa-judge` 的 `heartbeat.md` 应当规定： - - 检查当前全局进度是低于预期、正常还是卡点。 - - 对于已经标记为 `ready_for_review` 的节点，主动执行抽样检查工具，如果抽样不通过，则主动调度退回给原作者。 - - 规定其只有遇到问题才说话，没事的时候必须节约 Token，直接结案。 - -#### (3) 会话隐藏与静默运行 (隐式聊天机制) -为了不污染用户的主聊天界面： -- 心跳触发的 Conversation 应当拥有独特的 ID（如 `heartbeat-177xxxxx`）。 -- 在前端 UI（AgentChat.vue）中，如果不特别切换到 heartbeat 专区，应该不展示这类后台巡逻日志，以保持人类界面的干净。 -- 但心跳的整个完整推演过程（产生的 session）**必须依然进入现有的 Memory 三层架构**。也就是说，如果 `qa-judge` 在心跳中发出了很多派发任务，这个行为依然会记录进 `short-term/session.md` 里并最终写进日常报表（Daily Report）。 - ---- - -## 三、实现状态 - -- [x] **1. Heartbeat 后端引擎** - - `server/services/heartbeat-service.js` — Agent 级心跳服务（按 config.json 中的 heartbeatInterval 独立配置） - - `server/services/company-heartbeat-service.js` — 公司级心跳服务（扫描所有公司，按 company.json 心跳配置唤醒 CEO） - - 已适配 multi-tenant 架构，支持 `system/agents/` + `data/{companyId}/agents/` 双路径 -- [x] **2. 隐式对话 API** - - `agent-chat.js` 支持 `silent: true` 模式，心跳会话不污染前端主界面 - - 会话依然经历 Memory 三层架构，记录进 short-term + reflections -- [x] **3. Agent 心跳策略** - - 每个 Agent 的 `heartbeat.md` 定义专项心跳行为（如 CEO 早间巡检、晚间复盘） - - 模板库中 CEO/COO 等模板已包含 heartbeat.md -- [x] **4. 前端心跳控制** - - `CompanyDashboard.vue` per-agent 心跳开关（启动/停止/配置间隔） - - API: `PUT /api/company/:companyId/agents/:agentId/heartbeat` - - API: `POST /api/company/:companyId/agents/:agentId/heartbeat/start` - - API: `POST /api/company/:companyId/agents/:agentId/heartbeat/stop` -- [x] **5. Anti-Loop 制衡** - - 借助 Memory 架构，Agent 在心跳前读取最近 session，避免重复催促 - ---- - -## 四、技术优势 - -1. **"起搏"+"记忆"打造真实自主引擎**：依赖已实现的海马体与短期记忆，Agent 不再是简单的代码循环，而是拥有自己时间轴与经验累积的鲜活生命体。 -2. **极低侵入性**：依然可以复用现有的 Claude CLI 通道和 `runClaudeCliSession` 函数，仅仅是多了一个虚拟的"系统定时发信人"。 -3. **闭环 OODA loop**：观察（OKR数据注入）- 导向（heartbeat.md规则）- 决策（推理判定）- 行动（ToolDispatch），在此实现完整的智能自主控制闭环。 diff --git a/docs/system-design/24-company-layer-architecture.md b/docs/system-design/24-company-layer-architecture.md deleted file mode 100644 index 98d87f8..0000000 --- a/docs/system-design/24-company-layer-architecture.md +++ /dev/null @@ -1,578 +0,0 @@ -# 24. Company Layer — 公司实例化架构 - -> **版本**: v2.0 (已实现) -> **日期**: 2026-03-26 -> **状态**: ✅ 已实现 (Phase 1-5 全部完成) -> **前置**: 四层 Agent 架构 (02 号文档)、OKR 目标体系、Memory 系统、Heartbeat 系统 - ---- - -## 一、核心问题 - -### 当前架构的瓶颈 - -现有的 LemonBoss 采用**扁平化的单公司模型**： - -``` -data/agents/ -├── master ← 用户唯一的交互入口 -├── ceo ← 单一 CEO -├── qa-judge ← 单一 QA -├── poet ← 扁平挂在全局下 -├── innovator ← 扁平挂在全局下 -└── ... -``` - -**问题：** -1. **耦合**：所有 Agent 共存于同一个 `data/agents/` 目录，无法区分"做自媒体的编辑"和"做游戏的编辑"。 -2. **CEO 单例**：只有一个 CEO，如果同时要经营两家公司（自媒体 + 漫剧），CEO 要同时管两条完全不同的业务线，OKR 冲突、记忆污染。 -3. **无法独立闭环**：没有"公司"这个边界，Agent 无法形成一个可以 24 小时自主运转、独立迭代的闭合体。 -4. **无法并行扩展**：用户想创建第二家、第三家公司时，只能不断往同一个池里加人，而非开辟独立的组织空间。 - -### 设计目标 - -用户对 Master 说：**"帮我创建一家做公众号运营的公司"**，系统应该： -1. 创建一个独立的 **Company 实例**（如 `wechat-media-co`） -2. 为该公司分配（或新建）一个 **CEO Agent** -3. CEO 自主规划战略、定义 SOP、创建所需的 Role Agent -4. 公司内部形成**独立闭环**：从内容策划 → 创作 → 审核 → 发布 → 数据回收 → 策略调整 -5. 用户后续再说"帮我创建一家做漫剧的公司"，系统创建第二个完全隔离的 Company 实例 - ---- - -## 二、架构演进：从扁平到层级 - -### 2.1 演进前 vs 演进后 - -``` - 【演进前】扁平模型 【演进后】Company 模型 - ───────────────── ────────────────────── - - User (你) User (你) - │ │ - └── Master └── Master (唯一, 全局) - │ │ - ├── CEO ├── Company: 自媒体公司 - ├── qa-judge │ ├── CEO (该公司专属) - ├── poet │ ├── qa-judge - ├── innovator │ ├── content-writer - └── ... │ ├── editor - │ ├── publisher - (所有人在同一个池子) │ └── data-analyst - │ - ├── Company: 漫剧工作室 - │ ├── CEO (另一个专属) - │ ├── scriptwriter - │ ├── artist - │ └── ... - │ - └── 全局 Agent (跨公司复用) - ├── innovator - └── agent-creator -``` - -### 2.2 核心原则 - -| 原则 | 说明 | -|------|------| -| **Master 是老板，不是 CEO** | Master 只管"开公司"和"战略校准"，不深入执行 | -| **Company 是隔离边界** | 每家公司有独立的 Agent 池、OKR 树、Memory 空间 | -| **CEO 是公司的内核** | 公司创建后，CEO 是第一个被雇佣的人，由 CEO 自主规划一切 | -| **独立闭环运行** | 一个 Company 从创建到运营，不依赖人类持续干预 | -| **多实例并行** | 多个 Company 并行运转，互不干扰 | - ---- - -## 三、数据结构设计 - -### 3.1 目录结构 - -``` -data/ -├── system/ ← 系统级数据（跨公司共享） -│ ├── agents/ ← 全局 Agent（Master + 跨公司基础设施 Agent） -│ │ ├── master/ -│ │ ├── innovator/ -│ │ ├── agent-creator/ -│ │ ├── trend-hunter/ -│ │ └── ... -│ │ -│ └── templates/ ← 📦 Agent 模板库（招聘时优先查找） -│ ├── _registry.json ← 模板注册表 -│ ├── _company_bootstrap/ ← 公司自举清单 (manifest.json) -│ ├── ceo/ ← CEO 通用模板 -│ ├── cto/ ← CTO 通用模板 -│ ├── coo/ ← COO 通用模板 -│ ├── hr/ ← HR 通用模板 -│ ├── qa-judge/ ← 质量仲裁模板 -│ ├── agent_creator/ ← Agent Creator 模板 -│ └── scrapling_crawler/ ← 爬虫模板 -│ -├── {company-id}/ ← 公司实例（顶层目录，扁平化） -│ ├── company.json ← 公司元数据 + 状态 + 配置 -│ ├── agents/ ← 该公司的专属 Agent 池 -│ │ ├── ceo/ -│ │ ├── cto/ -│ │ ├── coo/ -│ │ └── {role}/ -│ ├── goals/ ← 该公司的 OKR 树 -│ │ └── _index.json -│ ├── pipelines/ ← 该公司的 SOP 流水线定义 -│ └── workspace/ ← 该公司的共享工作区 -│ └── {agentId}/ -│ -├── goals/ ← 全局 OKR 目标 -│ ├── _index.json -│ └── G-{NNN}/ -│ -└── agents/ ← (兼容) 全局 tasks - └── .tasks/ -``` - -### 3.2 company.json 结构 - -```json -{ - "id": "wechat-media-co", - "name": "柠檬自媒体", - "description": "专注微信公众号内容运营，以 AI 驱动的内容工厂模式实现日更", - "status": "running", - "createdAt": "2026-03-25T17:00:00Z", - "createdBy": "master", - - "ceo": "ceo", - - "sop": { - "pipeline": "daily-content", - "description": "选题 → 写稿 → 审核 → 排版 → 发布 → 数据回收" - }, - - "agents": ["ceo", "content-writer", "editor", "publisher", "data-analyst"], - - "heartbeat": { - "enabled": true, - "intervalMinutes": 30 - }, - - "config": { - "timezone": "Asia/Shanghai", - "maxAgents": 10, - "budget": { - "dailyTokenLimit": 500000, - "monthlyBudget": 100 - } - } -} -``` - ---- - -## 四、Agent 招聘系统 (Hiring Pipeline) - -> **核心理念**: 公司需要某个角色时，不是凭空创造，而是走一套完整的**招聘流程**—— -> 先从人才市场（模板库）找现成的，找不到就培养一个新人，培训合格后才能上岗。 - -### 4.1 招聘流程总览 - -```mermaid -flowchart TD - A["CEO 需要一个角色
(如: 热点搜索员)"] --> B{"在 templates/ 中
查找匹配模板?"} - - B -->|"✅ 找到模板"| C["复制模板到
公司 agents/ 目录"] - C --> D["注入公司上下文
(改写 agent.md, soul.md, user.md)"] - D --> E["直接上岗 ✅"] - - B -->|"❌ 模板库无此角色"| F["调用 agent-creator
从零创建 Agent 骨架"] - F --> G["调用 innovator
进入 FDE 训练流水线"] - G --> H{"Benchmark
评分 ≥ 95?"} - - H -->|"❌ 不合格"| I["继续 Evolve 迭代
(自动重训)"] - I --> H - - H -->|"✅ 合格"| J["毕业 → 存入 templates/
(供未来复用)"] - J --> C -``` - -### 4.2 招聘三阶段详解 - -#### 阶段 A: 模板库查找 (Template Lookup) - -```javascript -// 伪代码: hire(roleName, companyId) -function hire(roleName, companyId) { - const templateDir = path.join(DATA_DIR, 'templates', roleName); - - if (fs.existsSync(templateDir)) { - // ✅ 模板存在 → 直接复制 + 定制 - copyDir(templateDir, `data/${companyId}/agents/${roleName}/`); - injectCompanyContext(companyId, roleName); - return { status: 'hired_from_template', ready: true }; - } else { - // ❌ 模板不存在 → 进入培养流程 - return trainNewAgent(roleName, companyId); - } -} -``` - -**模板库是不断扩充的人才市场**： -- 初始模板：`ceo`, `qa-judge`, `content-writer`, `editor` 等通用角色 -- 每次从零培养的新角色，训练合格后**自动沉淀回 `templates/`**，下次招聘同类角色时就能直接使用 -- 模板只保存骨架（agent.md, soul.md, skills/, config.json），不带记忆和工作区 - -#### 阶段 B: 从零培养 (Create + Train) - -当模板库中没有对应角色时，进入培养流水线： - -``` -Step 1: agent-creator 创建骨架 - → 生成 agent.md, soul.md, identity.md, config.json - → 定义角色的核心职责和工具清单 - → 此时 Agent 状态为 "training"（不可执行正式任务） - -Step 2: innovator 执行 FDE 训练 - → F (Find): 调研该角色领域的最佳实践和行业知识 - → D (Digest): 消化知识转化为 Agent 的技能定义 (SKILL.md) - → E (Evolve): 循环迭代优化，直到技能评分达标 - -Step 3: Benchmark 评估 - → 运行标准化的能力测试用例 - → 评分维度：任务完成度、输出质量、工具使用准确性、响应时间 - → 合格线：综合评分 ≥ 95 分 -``` - -#### 阶段 C: 合格上岗 + 模板沉淀 - -``` -训练合格后: - 1. Agent 状态从 "training" → "ready" - 2. 复制干净骨架到 templates/ (不含训练过程中的 memory 和 workspace) - 3. 注入公司上下文到公司实例 - 4. 正式加入公司 agents/ 池 - 5. 更新 company.json 的 agents 列表 - 6. CEO 收到通知："新员工 {roleName} 已入职" -``` - -### 4.3 Agent 状态机 - -``` - ┌── training ──► ready ──► active - │ │ - (从零培养) │ │ (公司暂停/开除) - │ ▼ - │ suspended - │ - (模板复制) └── ready ─────────────► active -``` - -| 状态 | 含义 | 能否接任务 | -|------|------|-----------| -| `training` | 正在被 Innovator 训练中，Benchmark 尚未达标 | ❌ 不能 | -| `ready` | 训练完毕或模板复制完毕，等待上岗 | ❌ 等待分配 | -| `active` | 已加入公司，处于正式工作状态 | ✅ 能 | -| `suspended` | 被 CEO 暂停（表现不佳或公司调整） | ❌ 暂停 | - -### 4.4 模板库管理 - -模板库 `system/templates/` 是一个**不断进化的人才市场**： - -``` -system/templates/ -├── _registry.json ← 模板注册表（索引所有可用模板） -├── _company_bootstrap/ ← 公司自举清单 -│ └── manifest.json ← 定义初始组织架构 (CEO/CTO/COO/HR) -│ -├── ceo/ ← 通用 CEO 模板 -│ ├── agent.md ← 通用的 CEO 职责（不含特定公司信息） -│ ├── soul.md ← CEO 通用思维模式 -│ ├── identity.md -│ ├── heartbeat.md -│ ├── tools.md -│ ├── user.md -│ └── config.json ← type: "cxo" -│ -├── cto/ ← CTO 模板 -├── coo/ ← COO 模板 -├── hr/ ← HR 模板 -├── qa-judge/ ← 质量仲裁模板 -├── agent_creator/ ← Agent Creator 模板 -└── scrapling_crawler/ ← 爬虫模板 -``` - -**`_registry.json` 结构** (实际内容)： -```json -[ - { - "id": "ceo", - "name": "CEO / 首席执行官", - "type": "cxo", - "description": "公司战略规划、团队管理、OKR 制定、任务委派", - "benchmarkScore": 97, - "trainedAt": "2026-03-20", - "usedCount": 9 - }, - { - "id": "qa-judge", - "name": "QA 仲裁者", - "type": "specialist", - "description": "质量验收、OKR 进度审查、标准化仲裁", - "benchmarkScore": 95, - "trainedAt": "2026-03-25", - "usedCount": 6 - } -] -``` - -### 4.5 复制时的上下文注入 - -从模板复制到公司后，必须改写以下文件： - -| 文件 | 注入内容 | -|------|---------| -| `agent.md` | 追加：所属公司名称、公司使命、公司特定的约束规则 | -| `soul.md` | 追加：公司文化和价值观（如"我们是一家注重数据驱动的自媒体"） | -| `user.md` | 重写：上级是该公司的 CEO（而非 Master），写入 CEO 的偏好 | -| `config.json` | 添加 `companyId` 字段，更新 `parent_id` | -| `memory/memory.md` | 初始化为空白（新公司、新记忆，不继承模板记忆） | - ---- - -## 五、生命周期流程 - -### 5.1 公司创建 + 招聘全流程 - -```mermaid -sequenceDiagram - participant User as 用户 - participant Master as Master Agent - participant System as 系统 API - participant AC as agent-creator - participant Inno as innovator - participant CEO as 新 CEO Agent - - User->>Master: "帮我创建一家做公众号运营的公司" - Master->>Master: 理解意图 → 确定公司定位和核心 SOP - Master->>System: POST /api/company/create - Note over System: 1. mkdir data/wechat-media-co/
2. 生成 company.json
3. 初始化 agents/, goals/, workspace/ - System-->>Master: ✅ 公司创建成功 - - Master->>System: POST /api/company/:id/hire { role: "ceo" } - Note over System: 在 templates/ 查找 "ceo" → ✅ 找到 - System->>System: 复制 templates/ceo → wechat-media-co/agents/ceo/ - System->>System: 注入公司上下文 (agent.md, user.md) - System-->>Master: ✅ CEO 已入职 - - Master->>CEO: TaskDispatch: "你是这家公司的 CEO，请规划战略并组建团队" - - CEO->>CEO: 分析公司定位 → 确定需要哪些角色 - CEO->>System: POST /api/company/:id/hire { role: "content-writer" } - Note over System: templates/ 查找 → ✅ 找到 → 复制 + 注入 - CEO->>System: POST /api/company/:id/hire { role: "hot-topic-hunter" } - Note over System: templates/ 查找 → ❌ 没有 - System->>AC: 创建 "hot-topic-hunter" Agent 骨架 - AC-->>System: 骨架已就绪 - System->>Inno: 启动 FDE 训练 (hot-topic-hunter) - Inno->>Inno: Find → Digest → Evolve (循环至 ≥95) - Inno-->>System: ✅ Benchmark 97 分，训练合格 - System->>System: 沉淀到 templates/hot-topic-hunter/ - System->>System: 复制到 wechat-media-co/agents/ + 注入上下文 - System-->>CEO: ✅ 热点搜索员已入职 - - CEO->>System: POST /api/company/:id/goals/create - CEO->>System: POST /api/company/:id/pipelines/create - CEO-->>Master: "团队组建完毕，流水线已就绪，开始自主运行" -``` - -### 4.2 公司日常运行流程 - -```mermaid -sequenceDiagram - participant HB as Heartbeat Service - participant CEO as CEO Agent - participant Writer as Content Writer - participant Editor as Editor - participant Pub as Publisher - participant DA as Data Analyst - - loop 每日循环 (自动触发) - HB->>CEO: [SYSTEM HEARTBEAT] 早间巡检 - CEO->>DA: "分析昨日数据，给出今日选题建议" - DA-->>CEO: "昨日阅读量 Top3 关键词: AI教程, 提效工具, 副业" - - CEO->>Writer: "今日选题: AI提效工具盘点, 要求3000字" - Writer-->>Editor: "初稿完成" - Editor-->>Writer: "修改意见：开头太平，增加 hook" - Writer-->>Editor: "修改稿完成" - Editor-->>Pub: "审核通过，可发布" - Pub->>Pub: 排版 + 定时发布 - Pub-->>CEO: "已发布，预计 18:00 推送" - - HB->>CEO: [SYSTEM HEARTBEAT] 晚间复盘 - CEO->>DA: "拉取今日文章数据" - DA-->>CEO: "阅读 2340, 点赞 186, 新增关注 28" - CEO->>CEO: 写入 memory → "AI提效选题表现良好，继续跟进" - end -``` - -### 4.3 多公司并行 - -``` -用户对 Master 的操作： - -"帮我查看所有公司的运营状况" - → Master 调用: GET /api/company/list - → 返回: [ wechat-media-co (运行中, 今日发布1篇), manga-studio (筹建中) ] - -"漫剧公司的 CEO 表现怎么样？" - → Master 调用: GET /api/company/manga-studio/report - → 返回: CEO 近7天日报汇总 - -"关闭自媒体公司" - → Master 调用: POST /api/company/wechat-media-co/shutdown - → CEO 收到关停指令 → 善后清理 -``` - ---- - -## 六、API 设计 - -### 6.1 Company CRUD - -| 方法 | 路径 | 说明 | -|------|------|------| -| `POST` | `/api/company/create` | 创建新公司 | -| `GET` | `/api/company/list` | 列出所有公司 | -| `GET` | `/api/company/:companyId` | 获取公司详情 | -| `PUT` | `/api/company/:companyId` | 更新公司信息 | -| `POST` | `/api/company/:companyId/shutdown` | 关停公司 | - -### 6.2 招聘与 Agent 管理 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `POST` | `/api/company/:companyId/hire` | 招聘 Agent (模板优先 → 培养兜底) | -| `GET` | `/api/company/:companyId/agents` | 列出公司内所有 Agent | -| `POST` | `/api/company/:companyId/agent/:agentId/chat` | 与公司内 Agent 对话 | -| `POST` | `/api/company/:companyId/fire` | 解雇 Agent (suspend) | - -### 6.3 模板库 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/templates` | 列出所有可用模板 | -| `GET` | `/api/templates/:templateId` | 查看模板详情 | - -### 6.4 Company 内部：OKR 管理 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `POST` | `/api/company/:companyId/goals/create` | 创建公司 OKR | -| `GET` | `/api/company/:companyId/goals` | 获取公司 OKR 列表 | -| `PUT` | `/api/company/:companyId/goals/:goalId` | 更新 OKR 节点 | - -### 6.5 Company 运营 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/api/company/:companyId/report` | 获取公司运营报告 | -| `POST` | `/api/company/:companyId/heartbeat` | 手动触发公司心跳 | - ---- - -## 七、与现有系统的兼容设计 - -### 7.1 Agent 寻址变化 - -引入 Company 后，Agent 的寻址变为 **Company 限定**： - -```javascript -// 全局 Agent（不属于任何公司, companyId = 'system'） -const agentDir = path.join(DATA_DIR, 'system', 'agents', agentId); -// 即: system/agents/master/ - -// 公司内 Agent -const agentDir = path.join(DATA_DIR, companyId, 'agents', agentId); -// 即: data/wechatai/agents/ceo/ -``` - -**实际策略**： -- `config.json` 含 `companyId` 字段。 -- **`companyId: "system"`** → 在 `system/agents/` 下（全局 Agent）。 -- **`companyId: "{id}"`** → 在 `data/{companyId}/agents/` 下（公司 Agent）。 -- 路由层通过 `resolveAgentDir(companyId, agentId)` 统一封装，向上层透明化。 - -### 7.2 OKR/Goals — 全部归属 Company - -Goals/OKR 不再有全局作用域。**每个 Goal 都必须隶属于一个 Company**： - -``` -data/wechat-media-co/goals/G-001/ ← 自媒体公司的 OKR -data/manga-studio/goals/G-001/ ← 漫剧公司的 OKR（ID 互不冲突） -``` - -GoalsService 改造： -- 构造时必须传入 `companyId`：`new GoalsService(companyId)` -- 数据路径变为 `data/{companyId}/goals/` -- `_index.json` 也随之放在公司目录下 - -### 7.3 Memory 隔离 - -Memory 天然隔离：因为 Memory 存储在各个 Agent 的目录下。 -公司内的 Agent 在 `data/{companyId}/agents/{agentId}/memory/` 下，自动与其他公司和全局 Agent 的记忆完全隔离。无额外代码改动。 - -### 7.4 Heartbeat 集成 - -HeartbeatService 扩展扫描范围： -- 遍历 `data/agents/` 下有 `heartbeat.enabled` 的全局 Agent（如 master）。 -- 遍历每个 `data/{companyId}/` 下，读取 `company.json` 的心跳配置。 -- 若公司心跳开启，唤醒该公司的 CEO 作为入口（CEO 自行决定唤醒下属）。 - ---- - -## 八、实现计划 — Todo List - -### ✅ Phase 1: 数据结构 + 模板库基础 (已完成) - -- [x] **1.1** 创建 `system/templates/` 目录，迁移现有 Agent 为模板（ceo, cto, coo, hr, qa-judge 等） -- [x] **1.2** 实现 `company-service.js`：Company CRUD (create / get / list / shutdown / start) -- [x] **1.3** 实现 `resolveAgentDir(companyId, agentId)` 统一寻址函数 -- [x] **1.4** 实现 `_registry.json` 模板注册表，记录模板的 benchmarkScore、usedCount - -### ✅ Phase 2: Agent 招聘系统 (Hiring Pipeline) (已完成) - -- [x] **2.1** 实现 `POST /api/company/:id/hire` — 模板查找 → 复制 → 上下文注入 -- [x] **2.2** 招聘兜底：模板不存在时自动调用 `agent-creator` 创建 + `innovator` FDE 训练 -- [x] **2.3** Benchmark 质量门禁：评分 ≥ 95 才允许上岗，不合格自动 re-evolve -- [x] **2.4** 训练合格后自动沉淀骨架到 `templates/`，更新 `_registry.json` - -### ✅ Phase 3: CEO 自动建制 + OKR (已完成) - -- [x] **3.1** 公司创建后自动招聘 CEO（从模板），CEO agent.md 注入公司使命 -- [x] **3.2** Bootstrap 自举机制：`_company_bootstrap/manifest.json` 定义初始组织 → 自动批量招聘 CEO/CTO/COO/HR -- [x] **3.3** GoalsService 改造：OKR 支持全局 (`data/goals/`) + 公司级 (`data/{companyId}/goals/`) - -### ✅ Phase 4: SOP 流水线 (已完成) - -- [x] **4.1** 设计 Pipeline 数据结构（`{companyId}/pipelines/*.json`） -- [x] **4.2** 实现 Pipeline 执行引擎 (`pipeline-service.js`)：创建/运行/推进/驳回 全流程 -- [x] **4.3** CEO 可以通过 API 动态创建和调整 Pipeline - -### ✅ Phase 5: 前端 Dashboard (已完成) - -- [x] **5.1** `CompanyDashboard.vue` — 公司仪表盘 (Agent 列表 + 运行状态 + 心跳控制) -- [x] **5.2** 公司详情页（Agent 列表 + 操作按钮: Chat/Skills/Train + per-agent 心跳开关） -- [x] **5.3** `OkrDashboard.vue` — OKR 目标看板 -- [x] **5.4** `MasterChatDrawer.vue` — Master Agent 侧边抽屉对话 - ---- - -## 九、关键技术决策 - -| # | 问题 | 决策 | 说明 | -|---|------|------|------| -| 1 | Agent ID 全局唯一还是公司内唯一？ | **公司内唯一** | 如 ceo 在每家公司内都叫 ceo，通过 companyId + agentId 联合定位 | -| 2 | 原有 `data/agents/` 里的 Agent | **迁移为模板** | ceo、qa-judge 等迁入 `data/templates/`，master/innovator 保留为全局 | -| 3 | 招聘时模板不存在怎么办？ | **agent-creator 创建 + innovator 训练到 ≥95** | 训练合格后自动沉淀为新模板，下次复用 | -| 4 | Company 可以嵌套 Company 吗？ | **v1.0 不支持** | 先做单层，未来有需求再做集团架构 | -| 5 | 跨公司 Agent 共享（如 innovator） | **全局 Agent 池** | `data/agents/` 下的 Agent 可被任何公司调用 | -| 6 | 公司的"关停"语义 | **软关停** | status=shutdown，停止心跳，保留数据 | -| 7 | Goals/OKR 作用域 | **全部归属 Company** | 不设全局 OKR，每个目标都隶属于一个具体公司 | diff --git a/docs/system-design/25-bootstrap-mechanism.md b/docs/system-design/25-bootstrap-mechanism.md deleted file mode 100644 index fe378cc..0000000 --- a/docs/system-design/25-bootstrap-mechanism.md +++ /dev/null @@ -1,123 +0,0 @@ -# 25. Bootstrap 自举机制 — 公司创建时的自动化部署 - -> **版本**: v1.0 -> **日期**: 2026-03-26 -> **状态**: ✅ 已实现 -> **关键提交**: `f49cad8 feat: Phase A+B 公司自举与HR大一统`, `d55b7a2 fix(master): 更新 Master Agent 指令以适配 Bootstrap 自举机制` - ---- - -## 一、核心问题 - -在引入 Company Layer 之后，每次创建新公司都需要手动逐个招聘 CEO、CTO、COO 等核心骨干，流程过于冗长。 - -**目标**：用户对 Master 说"创建一家 AI 新闻公司"，系统应一键**自动完成**： -1. 创建公司目录 + company.json -2. 自动部署核心团队（CEO、CTO、COO、HR） -3. 向 CEO 下达启动战略指令 -4. CEO 自主规划并通过 HR 批量招聘执行层 Agent - ---- - -## 二、Manifest 配置 - -Bootstrap 机制的核心是 `system/templates/_company_bootstrap/manifest.json`： - -```json -{ - "description": "公司自举(Bootstrap)模板 — 创建时自动部署核心骨干团队", - "bootstrap_agents": [ - { "role": "ceo", "type": "cxo", "name": "首席执行官" }, - { "role": "cto", "type": "cxo", "name": "首席技术官" }, - { "role": "coo", "type": "cxo", "name": "首席运营官" }, - { "role": "hr", "type": "specialist", "name": "人事总监" } - ], - "auto_dispatch_to_ceo": true, - "ceo_startup_prompt": "你的公司刚刚创建，系统已经自动为你配备了 CTO、COO、HR 三位核心高管。请立刻执行你的五步战略工作流：1.撰写商业蓝图 2.设计Pipeline JSON 3.设定OKR 4.将Pipeline设计图移交CTO(让他通过HR批量招聘执行层Agent) 5.通知COO接管运营。" -} -``` - -**配置说明**： - -| 字段 | 说明 | -|------|------| -| `bootstrap_agents` | 数组：创建公司时自动招聘的角色列表 | -| `auto_dispatch_to_ceo` | 布尔：是否在部署完成后自动向 CEO 发送启动指令 | -| `ceo_startup_prompt` | 字符串：CEO 收到的首次启动战略指令模板 | - ---- - -## 三、执行流程 - -```mermaid -sequenceDiagram - participant User as 用户 - participant Master as Master Agent - participant API as POST /api/company/create - participant FS as 文件系统 - participant Hire as companyService.hire() - participant CEO as 新公司 CEO - - User->>Master: "创建一家 AI 新闻公司" - Master->>API: { id: "ai-news", name: "AI新闻社", description: "..." } - - API->>FS: 1. mkdir data/ai-news/{agents,goals,pipelines,workspace} - API->>FS: 2. 写入 company.json - - Note over API: Phase A: 读取 manifest.json - - loop 遍历 bootstrap_agents - API->>Hire: hire("ai-news", "ceo", {type:"cxo"}) - Note over Hire: 从 templates/ceo/ 复制 → ai-news/agents/ceo/ - API->>Hire: hire("ai-news", "cto", {type:"cxo"}) - API->>Hire: hire("ai-news", "coo", {type:"cxo"}) - API->>Hire: hire("ai-news", "hr", {type:"specialist"}) - end - - API->>API: 3. 更新 status="running", heartbeat.enabled=true - - Note over API: Phase B: 自动向 CEO 下达启动令 (延迟 2s) - - API-->>CEO: dispatch(from:master, to:ai-news:ceo, task:startup_prompt) - - CEO->>CEO: 执行五步战略工作流 - CEO->>CEO: 1. 撰写商业蓝图 - CEO->>CEO: 2. 设计 Pipeline JSON - CEO->>CEO: 3. 设定 OKR - CEO->>CEO: 4. 通过 HR 批量招聘执行层 - CEO->>CEO: 5. 通知 COO 接管运营 -``` - ---- - -## 四、关键代码位置 - -| 文件 | 位置 | 职责 | -|------|------|------| -| `server/routes/company.js` | Line 20-93 | `POST /api/company/create` — 整个 Bootstrap 流程 | -| `server/services/company-service.js` | `create()` | 公司目录初始化 | -| `server/services/company-service.js` | `hire()` | 模板复制 + 上下文注入 | -| `system/templates/_company_bootstrap/manifest.json` | 全文 | Bootstrap 配置清单 | - ---- - -## 五、跳过 Bootstrap - -如果需要创建空公司（不自动部署骨干），请求中传 `skipBootstrap: true`： - -```json -POST /api/company/create -{ - "id": "test-co", - "name": "测试公司", - "skipBootstrap": true -} -``` - ---- - -## 六、扩展点 - -- **自定义 Bootstrap**：修改 `manifest.json` 的 `bootstrap_agents` 可调整初始团队组合 -- **行业模板**：未来可支持多个 manifest（如 `manifest-media.json`, `manifest-tech.json`），按行业选择不同的初始团队 -- **CEO Prompt 定制**：`ceo_startup_prompt` 可根据不同业务场景定制 CEO 的首要任务 diff --git a/docs/system-design/25-harness-engineering-improvements.md b/docs/system-design/25-harness-engineering-improvements.md deleted file mode 100644 index c562b25..0000000 --- a/docs/system-design/25-harness-engineering-improvements.md +++ /dev/null @@ -1,59 +0,0 @@ -# 25. Harness Engineering Improvements (Agent 上下文与生命周期优化) - -## 1. 背景与目标 (Background & Objectives) - -随着 LemonBoss 架构从单体 Agent 演进为多租户下的“数字代理公司（Corporate OS）”，我们的宏观阵法（层级汇报、跨部门协作、OKR 分解）已初具规模（参考之前的相关系统设计）。然而，基于对前沿 Harness Engineering 最佳实践的深度反思，单个 Agent 节点在处理长链路复杂任务时，依然面临**“上下文衰减（Context Decay）”**、**“信息污染（Noise Pollution）”**、以及**“试错成本高昂（High Trial Cost）”**三大核心痛点。 - -为了确保底层每一个“数字员工”即使在超长命名的商业运营中也不会发生注意力弥散（Attention Decay），我们提出以下补充重构计划。该计划的核心思想是：**做精信息喂食、隔离决策上下文、构建自查闭环。** - ---- - -## 2. 核心改进计划 (Core Improvement Plans) - -### 改进点一：将四阶段分解固化为基座 Agent 的四大元技能 (Meta-Skills Integration) -**现状痛点**：当前单个 session 会承载一个 Agent 从“思考规划”到“调用执行”直至“修复 Bug”的全生命周期。后期 Session Prompt 过长（超过甜区限度），导致关键指令被稀释，且执行边界模糊。 -**改进策略**：我们将 `Research` -> `Plan` -> `Execute` -> `Verify` 不仅作为宏观规范，而是**实际固化为基座 Agent (Base Agent) 标准配备的四大元技能包（Meta-Skills）**。 -1. **按需装载独立技能树 (Dynamic Skill Invocation)**：在底层设定中，为每一个 Base Agent 提供四个相互独立的元技能引擎接口。每次面临新任务，代理根据自身所处的流转阶段，主动调用加载专属的技能包（如只调用 `skill_plan` 去出方案）。 -2. **基于技能切换的 Context Flush（上下文切断与防污染）**：一旦当前阶段的技能执行完毕（例如调用 Planner 技能产出了 `architecture.md`），该 Session 生命周期强制结束归档。当进入下一环节调起 `skill_execute` 技能时，新开一条绝对干净的 Session，只传入上一步确定的干货文件，彻底断绝跨阶段的幻觉与信息污染。 - -### 改进点二：实施“事前阻断阀”管理 (Human/Master pre-approval) -**现状痛点**：人类往往在 Agent 完全做错产出一堆无效代码后（即事后）去执行 Code Review，纠错成本极高。 -**改进策略**： -1. **杠杆前置审查**：当 CEO 或 CTO 这类管理层 Agent 产出“规划文档（Plan / Architecture）”后，系统强制挂起该节点的 `status`。 -2. **等待放行命令**：必须由 Master（人类用户） 或高阶 Validator/Innovator Review 批准该规划文档。一旦驳回，重做 Plan；一旦批准，才能生成下游子任务清单（Task Spawning）并消耗算力。以一行 Plan 的纠正，避免百行代码的错误生成。 - -### 改进点三：渐进式披露与去工具化 (Progressive Disclosure & Minimized Tools) -**现状痛点**：为了提供强大的功能，在 `tools.md` 或 System Prompt 里塞入海量工具说明与技能细则，导致模型注意力过载或陷入决策瘫痪（Decision Paralysis）。 -**改进策略**： -1. **多级目录动态按需加载**：确立三级机制： - - Level 1 (`CLAUDE.md` / `identity.md`)：只讲最最核心的存活元规则和找资料入口。 - - Level 2 (`SKILL.md`)：作为外挂组件引擎，只有触发特定领域关键词，引擎才将其注给 Agent `system_prompt`。一旦切走任务则将其卸载（Unload）。 - - Level 3 (`references`)：基于 RAG 工具被动按需调取日志或全量文件。 -2. **修剪泛洪工具群**：将非必须的复杂组合 API 下架。退守“最强的万能扳手”：赋予 Agent 沙盒受控的终端执行与代码编写权（如受限的 Python 解释器或 `bash`），让 Agent 现写代码去满足需求，而非提供写死上百个微工具集。 - -### 改进点四：单体自治理的“微小自反思闭环” (Micro Self-Verification) -**现状痛点**：完全依赖事后外置的角色（如 `QA-Judge` 或者遭遇硬报错再触发反馈），链路长且对中控要求高。 -**改进策略**： -1. **植入 Local Verify Hook**：规定在下级执行类 Agent 调用 `report_task` 汇报 `status: PASS` 之前，必须调用自身的沙箱测试或执行一次自我反思的 `verify` 工具。 -2. **Autoresearch Error Loop**：为底层 Agent 本地增加 `_lessons.md`（试错经验暂存区）。在执行重试（Retry）循环时，如果不通过，先强制写一条经验记录到 `_lessons.md` 中。下次 retry 带上本条经验执行，避免单次死循环卡点。此级循环不惊动顶层的 Innovator（FDE），实现“兵不烦将”。 - -### 改进点五：引入算力经济学观测 (Cost & Profiling Observability) -**现状痛点**：对“系统表现和行为”透明（有 Logs），但对“运营成本”无感知，不符合 Corporate OS（企业组织）要求。 -**改进策略**： -1. 建立 `logs/billing` 观测维度：在 `pipeline_runs` 和 `audit` 同级，加入 Token 消耗监测系统。 -2. 精确计算每一次交接任务“花费的 API 计价预估”。给 CEO 提供财务数据维度支持，帮助甄别“能力较弱导致长耗时高频失败”的节点，为其发起汰换重构提供商业依据。 - ---- - -## 3. 落地 Roadmap (Implementation Roadmap) - -| 阶段 | 里程碑 (Milestones) | 涉及模块 (Modules) | 预期时间 | -|------|----------------|----------------|----------| -| **Phase 1** | **微观验证引入**：在现有节点中强制引入自我校验 (Local Verify)，以及局部 `_lessons.md`。 | `agent-chat.js`, 基础 `templates/` 补充设定 | P1 优先 | -| **Phase 2** | **四大元技能装配与重构**：为 Base Agent 植装并切分 `Research/Plan/Execute/Verify` 四大独立技能入口，支持阶段流转中的 Context Flush。 | `memory-service.js`, `boss-meta-capabilities`, `master-session` | P1 优先 | -| **Phase 3** | **事前阻断流程化**：集成规划节点停摆拦截，接入前端 UI 以获得 Human/Master 的手动 Approved 后才能唤醒下游。 | `schema/goals`, Web UI 组件 | P2 规划 | -| **Phase 4** | **重置工具与按需挂载**：清理多余的工具并实施 `SKILL.md` 动态路由加载机制，提高上下文利用率甜区表现。 | `skill-registry/service`, 工具池整理 | P2 规划 | -| **Phase 5** | **经济学审计引入**：Token 数理追踪统计埋点，提供可视化报表支持（Cost Tracker Dashboard）。 | `logger/billing_service` | P3 未来探讨 | - -> **最后修订记录:** -> - 本规划文档由对行业 Harness Engineering 原理和 LemonBoss 特性对比后的工程反思形成，将指导未来一至两个大版本的演进。 diff --git a/docs/system-design/26-automated-hiring-orchestration.md b/docs/system-design/26-automated-hiring-orchestration.md deleted file mode 100644 index e7075d4..0000000 --- a/docs/system-design/26-automated-hiring-orchestration.md +++ /dev/null @@ -1,166 +0,0 @@ -# 26. 全自动招聘编排 — Creator → Skills → Innovator 流水线 - -> **版本**: v1.0 -> **日期**: 2026-03-26 -> **状态**: ✅ 已实现 -> **关键提交**: `5b508ce feat: Automate full hiring orchestration (Creator → Skills → Innovator)` - ---- - -## 一、核心问题 - -当 CEO 需要招聘一个**模板库中不存在**的角色（如"视频剪辑师"）时，系统不能简单报错。 -需要一套全自动编排流水线：从零定义 Agent → 注入技能 → 训练至合格。 - ---- - -## 二、编排全景 - -``` -POST /api/company/:companyId/hire { role: "video-editor" } - │ - ▼ - companyService.hireWithTraining() - │ - ├── 1. 在 templates/ 中查找 "video-editor" - │ → ❌ 模板不存在 - │ - ├── 2. AgentScaffold 创建空白骨架目录 - │ → data/{companyId}/agents/video-editor/ - │ → 状态标记为 status: "training" - │ - ├── 3. [异步] Agent-Creator 编写定义文件 - │ → POST /api/agent/agent-creator/chat - │ → "为 video-editor 补充 agent.md, soul.md, identity.md..." - │ - ├── 4. [同步] Arena 技能搜索与注入 - │ → skillDb.searchSkills("video-editor", { limit: 3 }) - │ → 将匹配的 Skill 复制到 agents/video-editor/skills/ - │ - └── 5. [延时5s] Innovator FDE 训练 - → POST /api/agent/innovator/chat - → "对 video-editor 进行 FDE 训练，Benchmark ≥ 95" - → Hunt → Digest → Evolve 循环 - → 合格后自动部署 -``` - ---- - -## 三、三阶段详解 - -### 阶段 1: Agent-Creator 定义 - -Agent-Creator 是一个专门负责"写定义文件"的元 Agent。接到请求后： - -1. 根据 role name 和 description 理解角色职责 -2. 使用 `Write` 工具写入标准定义文件： - - `agent.md` — 核心身份标识 + 职责描述 - - `identity.md` — 名称、emoji、简介 - - `soul.md` — 思维模式、价值观 - - `user.md` — 上级偏好 - - `tools.md` — 可用工具清单 -3. 验证写入完成 - -**关键实现** (`server/routes/company.js` Line 399-407)： -```javascript -fetch(`http://127.0.0.1:${PORT}/api/agent/agent-creator/chat`, { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ - message: `新员工 ${namespacedId} 已由脚手架创建空白目录...请补充完整的定义文件`, - conversationId: `create-${companyId}-${role}-${Date.now().toString(36)}` - }) -}); -``` - -### 阶段 2: Arena 技能搜索与注入 - -从技能数据库（Arena 技能商店）中搜索与角色匹配的现有技能，最多注入 3 个基础技能： - -1. `skillDb.searchSkills(role, { limit: 3 })` — 按角色名关键词搜索 -2. 将匹配的 Skill 目录递归复制到 Agent 的 `skills/` 目录下 -3. 如果没有匹配的技能，日志输出"将交由 Innovator 凭空生成" - -**关键实现** (`server/routes/company.js` Line 409-438)： -```javascript -const skills = skillDb.searchSkills(role, { limit: 3 }); -for (const skill of skills) { - if (skill.directory && fs.existsSync(skill.directory)) { - copyDir(skill.directory, path.join(skillsDir, skill.skillName)); - console.log(`[Hire] 💉 成功为其注入基础技能: ${skill.skillName}`); - } -} -``` - -### 阶段 3: Innovator FDE 训练 - -延时 5 秒（等 Creator 写入完毕）后，通知 Innovator 对新 Agent 进行 FDE 训练： - -1. Innovator 评估当前 Agent 技能水平 -2. 启动 **Hunt → Digest → Evolve** 训练流水线 -3. 循环迭代直到 Benchmark 评分 ≥ 95 -4. 训练完成后自动安装 SKILL.md - -**关键实现** (`server/routes/company.js` Line 441-451)： -```javascript -setTimeout(() => { - fetch(`http://127.0.0.1:${PORT}/api/agent/innovator/chat`, { - method: 'POST', - body: JSON.stringify({ - message: `公司 ${companyId} 的员工 ${role} 骨架和基础技能已注入完毕。 - 请使用 FDE pipeline 进行评测和进化训练，直到 Benchmark 达标 (Score ≥ 95)。` - }) - }); -}, 5000); -``` - ---- - -## 四、招聘后的动态心跳挂载 - -招聘成功后（无论是从模板还是训练完成），系统会立即为新 Agent 注册心跳定时器： - -```javascript -const heartbeatService = require('../services/heartbeat-service'); -const namespacedId = `${companyId}:${role}`; -heartbeatService._setupAgentHeartbeat(namespacedId); -``` - ---- - -## 五、与模板招聘的对比 - -| 维度 | 模板招聘 (Template) | 全自动编排 (Orchestration) | -|------|-------------------|--------------------------| -| 触发条件 | templates/ 下存在对应模板 | templates/ 下**不存在** | -| 耗时 | < 1 秒 | 数分钟 (FDE 训练) | -| 流程 | 复制 → 注入上下文 → 上岗 | Scaffold → Creator → Skills → FDE → 上岗 | -| Agent 状态 | 直接 `ready` → `active` | `training` → (训练完成) → `ready` | -| 模板沉淀 | 不需要 | 训练合格后自动 `deposit-template` 到 templates/ | - ---- - -## 六、模板沉淀 (Deposit Template) - -训练合格的新角色会被自动沉淀为模板，供未来复用： - -``` -POST /api/company/:companyId/deposit-template -{ - "agentId": "video-editor", - "benchmarkScore": 96 -} -``` - -**沉淀内容**：只保存骨架文件（agent.md, soul.md, config.json 等），不含 memory 和 workspace。 - ---- - -## 七、关键代码文件 - -| 文件 | 位置 | 职责 | -|------|------|------| -| `server/routes/company.js` | Line 376-474 | `POST /:companyId/hire` — 完整招聘 + 编排 | -| `server/routes/company.js` | Line 528-542 | `POST /:companyId/deposit-template` — 模板沉淀 | -| `server/services/company-service.js` | `hireWithTraining()` | 模板查找 + 骨架创建 | -| `server/services/skill-db.js` | `searchSkills()` | Arena 技能搜索 | diff --git a/docs/task_timeline_design.md b/docs/task_timeline_design.md deleted file mode 100644 index b6f9e0b..0000000 --- a/docs/task_timeline_design.md +++ /dev/null @@ -1,91 +0,0 @@ -# Task Timeline View Design Document - -## 1. Overview -The **Task Timeline View (Task Trace UI)** is a new management page that provides a unified, chronological view of all messages, tool calls, and actions performed by multiple Agents collaborating on a single "Task" (identified by a `taskId`). -This page solves the "Black Box" problem by aggregating isolated agent conversation logs into a single, sortable, filterable timeline. - -## 2. Core Features -- **Left Panel (Task List):** Displays all recent tasks in the system. Cards show the `taskId`, task progress/status, and the agents involved. -- **Right Panel (Unified Timeline):** A chronological feed of all `history.json` items spanning across all agents involved in the selected task. -- **Filtering & Search:** - - **Filter by Agent:** A multi-select dropdown to only show messages from specific agents (e.g. Master, Innovator, Hunter). - - **Search Box:** Full-text search to filter messages by keyword. - - **Sort Toggle:** Switch between ascending (oldest first) and descending (newest first) chronological order. - -## 3. Backend Architecture Changes - -### Data Source Challenge -Tasks in the system often represent an orchestration spawned from Master, such as `jobId` or `conversationId` mappings. -To link conversations to a single logical "Task", we will scrape the meta tags from agent conversations. In recent builds, `meta.json` or directory names often reflect the global `jobId` or `conversationId` (e.g., `tpl-train-lemonv_drama-xxx` or `train-xxx`). - -### New API Endpoints (`server/routes/tasks.js`) - -**1. `GET /api/tasks`** -- **Action:** Scans the job store (`.data/jobs-train.json` or `.data/jobs.json`) and conversation metadata to return an array of top-level tasks. -- **Response Format:** - ```json - [ - { - "taskId": "train-xxx", - "type": "train-create", - "status": "completed", - "progress": "✅ 训练完成", - "createdAt": "2026-03-29T12:00:00Z", - "agentsInvolved": ["master", "innovator", "hunter", "digester", "evolver"] - } - ] - ``` - -**2. `GET /api/tasks/:taskId/timeline`** -- **Action:** Aggregates and flattens all conversation logs associated with a `taskId`. - - It searches all companies and system agents (`data/companies/*/agents/*` and `system/agents/*`). - - Finds all conversation folders where the folder name or `meta.json`'s `conversationId` / `jobId` matches or contains the target `taskId`. - - Reads `history.json` for all these matched conversations. - - Annotates each message with `agentId` and `companyId`. - - Sorts the final array globally by `timestamp`. -- **Response Format:** - ```json - [ - { - "timestamp": "2026-03-29T12:00:01Z", - "role": "assistant", - "content": "🔧 [TOOL_CALL] Glob...", - "agentId": "master", - "companyId": "system", - "conversationId": "conv-mnbq123" - }, - { - "timestamp": "2026-03-29T12:00:05Z", - "role": "assistant", - "content": "正在执行 hunted...", - "agentId": "hunter", - "companyId": "system", - "conversationId": "hunt-xxx" - } - ] - ``` - -## 4. Frontend Architecture Changes - -### Routing (`web/src/router/index.js`) -- Add a new route `/tasks` mapped to the `TaskTimelineView`. - -### Layout (`web/src/views/TaskTimelineView.vue`) -- **Structure:** Uses a `
` to split Left and Right. -- **Left Column:** Needs a highly scannable List View of Tasks. - - Each item should highlight its Status using distinct colors (Green for `completed`, Yellow for `running`, Red for `failed`). - - Highlights the list of involved agents using small tags (``). -- **Right Column:** - - **Header:** Sticky Header containing Search (``), Agent Select Dropdown (``), and Sort Button (``). - - **Timeline Feed:** A scrollable `div` containing blocks of agent messages. Reuses the markdown renderer (`vue-markdown`) and adds specialized syntax highlighting/styling for the `🔧 [TOOL_CALL]` blocks to make them easily readable. - - **Agent Identity Header:** Every message block starts with a distinct visual header `avatar/icon + Agent Name + precise time`. - -### Navigation (`web/src/components/Sidebar.vue`) -- Add a new navigation item "Task Logs" / "任务看板" right below "MasterBot" or "Companies". - -## 5. Implementation Steps -1. **Backend Base:** Create `server/services/task-service.js` containing the heavy logic for aggregating cross-agent logs. -2. **Backend Routes:** Create `server/routes/tasks.js` and mount it to `server/index.js` or `server/app.js`. -3. **Frontend API:** Expose API bindings for Tasks in the Vue frontend. -4. **Frontend View:** Implement `TaskTimelineView.vue` with dummy data to build the layout. -5. **Integration:** Connect the frontend view with the live `/api/tasks` backend and polish the UI interactions (filtering/sorting). diff --git a/docs/todo/future/architecture_todo_list.md b/docs/todo/future/architecture_todo_list.md new file mode 100644 index 0000000..5e0f214 --- /dev/null +++ b/docs/todo/future/architecture_todo_list.md @@ -0,0 +1,146 @@ +# FDE Pipeline Architecture Todo List (Roadmap & Evolution) + +当前 **Innovator控制的 Hunt -> Digest -> Evolve (FDE)** 训练全链路在机制串联上已完全跑通，但要将其打造为真正的自动化、防退化、工业级自主进化学习系统，还需在以下五个核心维度进行底层架构设计与增补： + +## 1. 致命短板：缺乏客观独立的“硬核验证” (True Evaluation / Judge System) +**现状问题**： +目前在 Evolve 阶段，由 LLM 本身（Evolver Agent）自行汇报分数并使用正则表达式匹配（如 `最终分数: 92`）。自我评价容易引发幻觉，分数缺乏说服力。 +**待办清单 (Todos)**： +- [ ] **独立的 Judge Agent（裁判系统）**：将生成与验证解耦。引入仅负责验证结果的评审型智能体，它不参与能力的生成逻辑。 +- [ ] **基于任务执行的自动化 Benchmark (Test-Driven Benchmark)**： + - 代码类 Agent：提供真实的可执行代码测试集（Unit/Integration tests）去执行和验证通过率。 + - 知识对话类 Agent：建立标准且动态更新的验收用例库（RAG QA 验证或基准测试）。 + +## 2. 真实长效的“反馈循环”未打通 (Missing Feedback Loop) +**现状问题**： +虽然定义为 **F**eedback-driven，但目前的系统触发很大程度上依赖手动指定 Retrain 指令，并非长期自动的闭环负反馈驱动。 +**待办清单 (Todos)**： +- [ ] **负样本与真实会话捕获机制机制 (Bad Case Capturing)**：用户在与目标 Agent（如 CEO Agent）交互时，点击的差评（👎）或会话纠正记录被视作失败样本（Bad Cases），系统需要自动沉淀。 +- [ ] **无缝的热更新触发器 (Auto-Triggered Evolve)**：当失败用例阈值达到设定条件，自动唤醒 Digester 分析失败成因，沉淀为新的约束并交由 Evolver 无人值守地执行热更新修改。 + +## 3. 数据抓取与处理的边界稳定性 (Hunt Phase Robustness) +**现状问题**： +Hunter 代理重度依赖通用 WebSearch 和底层 Bash 调用来搜集知识。这种方式在面对特定或垂直领域时返回噪音大，且容易遭到反爬或速率限制影响而导致运行不稳定甚至超时被杀。 +**待办清单 (Todos)**： +- [ ] **原生特定域垂直 API 的接入 (Domain-specific Sourcing)**：针对不同职业（财务、法律等）配置特定领域的官方或标准 API 接口池，而不是单一通用搜索引擎。 +- [ ] **内部向量数据库接入与 RAG 整合**：不仅去公网找，还应当对接企业内部已有的私有知识库引擎。 +- [ ] **长文本清洗管道 (Doc Cleansing Pipeline)**：增加自动化的向量摘要预处理层或 Map-Reduce 清流机制，防止大规模抓取的网页或 PDF 撑爆提示词导致焦点丢失。 + +## 4. 进化过程中的“灾难性遗忘”防范 (Version Control & Prevent Regression) +**现状问题**： +每次 Evolution 迭代都在直接修改原版 `SKILL.md` 和 `knowhow.md`。单纯针对这一次的“反馈任务”进行定向强化，可能会丢失或弱化老版本拥有的其他核心能力。 +**待办清单 (Todos)**： +- [ ] **版本强控与对比 (Version Diffing & Rollback)**：建立更细化的代码层面回滚机制。 +- [ ] **全量回归打分机制 (Automated Regression Test)**：在升级为主版本前，必须运行覆盖整体职能（不仅是本次修改的内容）的测试基准确保总分不滑坡才允许正式 Bump 新版本。 + +## 5. 沙盒与安全控制体系 (Execution Safety & Sandboxing) +**现状问题**： +底层的 Agent 执行利用了 `--dangerously-skip-permissions` 的超高权限来驱动。高度发散且无人值守的自我编程（Evolve）如果产生非安全的系统脚本，对宿主机资源具备致命危险。 +**待办清单 (Todos)**： +- [ ] **沙盒化的底层运行环境 (Containerized Execution)**：用类似 Docker 的容器级隔离来保护执行宿主，仅向 Agent 暴露安全的读写卷。 +- [ ] **危险操作熔断器与拦截隔离 (Command Interceptor)**：拦截类似格式化或删库等敏感命令的高频审计审查模块，防止大模型抽风时的不可逆破坏行为。 + +--- +> *文档最后更新：由自动开发助手基于 FDE 流程在业务实际运行的瓶颈节点整理提交。* +实际上，当前的 Master Agent + CEO Agent 配合刚才跑通的 FDE (Innovator, Hunter, Digester, Evolver) 流水线，是映射**“道、法、术、器”**四层架构最完美的天然载体。 + +我们可以将现有的系统组件像这样完全对齐，并构建出**“自动下发 -> 执行 -> 验证 -> 反馈自进化”**的自动化闭环： + +1. 架构映射 (四层体系的智能体分工) +【道】(核心愿景/战略意图) —— Master Agent + Human (你) +角色：顶层意图感知的枢纽。你给 Master 发布指令（例如：“我们要上线一个最高质量的古典诗词生成的 API 服务”）。 +功能：感知全局业务边界，它不负责具体落地，而是将模糊意图翻译成任务，派发给 CEO。 +【法】(组织法则/目标拆解) —— CEO Agent + GoalsService (OKR API) +角色：将“道”转化为可执行的“法度”与组织结构。 +功能：CEO 接到任务后，使用刚上线的 /api/goals 创建 OKR，然后利用 /api/agent/task/dispatch 委派任务。如果公司里没有诗人，CEO 会调用 agent-creator（HR 部门）现场“招聘/生成”一个 Poet Agent 和一个 QA Agent (品控)。 +【术】(训练方法/重构机制) —— Innovator Agent (及其下属 HDE 元代理) +角色：进化与纠偏的机制论。 +功能：它是保证“器（员工）”能满足“法（OKR）”的训练学院。 +【器】(执行工具/基层产出) —— 具体的业务 Agent (如 Poet, Coder, CTO 等) +角色：承载具体任务的基层实体。 +2. 现在的架构如何实现“下一步的自动化验证闭环”？ +根据目前 CEO 和 + +Master + 的系统 Prompt 设计，我们只需稍微打通一条“汇报链路”，即可彻底实现无需人工的自动化验证。具体流转如下： + +闭环运行 Workflow： + +战略拆解 (Fa)：CEO 制定目标 -> 生成 Poet Agent 负责写诗 -> 生成 Judge Agent 负责按国学标准打分。 +基层执行 (Qi)：Poet 交出作品。 +自动化验证 (Validate)：CEO 让 Judge 去给 Poet 的诗词打分。如果 Judge 判定不达标（比如只有 60 分，格律不对）。 +触发自动进化 (Shu)：CEO Agent 在收到 Judge 的负面报告后，发现 OKR 存在卡点。此时 CEO 会自动触发 Dispatch 调用 Innovator Agent，发送指令：“Poet Agent 目前格律经常写错，请对他进行重训，重点抓取古诗词格律（平仄）的 Knowhow”。 +FDE 系统自旋：Innovator 启动 Hunter -> Digester -> Evolver 对 Poet 深度改造，改造完升至 V1.1 版本。 +重试验收：改造完毕后，CEO 让升级后的 Poet 重写，Judge 再打分，一旦 Pass，则 CEO 将 OKR 节点更新为完成 (/api/goals/:id/progress)。最后在 + +plan.md + 里向 Master 汇报大捷。 +3. 要真正跑通这套验证闭环，目前代码库还差哪几个小改动？ +虽然底层 API（FDE, Dispatch, OKR）都已经开发好了，但要让上述联动行云流水，我们只要对目前的配置文件做这三点调整： + +修改 CEO 的 + +agent.md + (赋能进化的职权)： 目前 CEO 的提示词中主要是利用 agent-creator 生成员工，需要补充：“当你发现下属 Agent 产出质量不达标时，使用 api dispatch 任务给 innovator Agent，要求其对该劣质员工进行重新训练（Retrain）。” +补齐 QA/Judge Agent (裁判位缺失)： CEO 本身不擅长看代码或审读具体的底层产出。需要预设一个 Validator/Judge Agent 模板。一切 KPI 验收，CEO 都通过把结果转发给 Judge 生成评分报告来自动化判定。 +增加 Agent 间的广播/事件订阅 (Event Hook)： 目前 Agent 得主动去轮询（curl -s api/agent/todo）看小兄弟做完没。系统如果能加一个 Webhook（当 Innovator 进化完 V1.1 版、或者 Poet 提交完草稿后，自动给 CEO 的日志里推一条 [Task Completed] 的消息），CEO 的调度速度就会从轮询变成事件驱动，反应极快。 +总结：现在的 LemonBoss 基础库相当于已经造出了所有的齿轮和引擎（尤其是刚跑通的 FDE 进化）。只要在顶层的 CEO 和 + +Master + 提示词里建立“生成->验收->失败则提交重启训练”的规则指引，这套“道法术器”四层映射的自治公司就能开始实现真正的全自动进化运转。 + + 其实，我们在 digest 环节产生了 benchmark 在 evolve 环节是根据每次 skill 产生的内容，用 benchmark 打分，然后判断按照这个 benchmark 分数如果《95 分，就让他继续迭代，直到这个 skill 满足 95 分的这个 benchmark，才可以部署使用。这套逻辑跟你说的 qa judge agent 有什么区别和结合么？ + + + + + + + + + + + + + + + + + + + + +这是一个极其犀利且核心的问题！ + +简练地说，它们两者最大的区别在于：“驾照考试打分（造车）” vs “实际上路跑业务（开车）”。 + +它们不仅不冲突，反而恰好构成了不可或缺的**“双重防御与验证体系”**。我来帮你把它们在“道法术器”和工程实践中的区别与结合点彻底理清： + +1. 两者的核心区别 +【术】FDE 进化环节的 Benchmark (<95分迭代) —— 类似于“静态代码审查 / 驾照笔试” +它在校验什么？：它审查的是 Agent 的能力蓝图（定义）。Evolver 根据 Benchmark 去阅读 SKILL.md，它评定的 95 分代表：“这个 Prompt 写得真好、内置的 Knowhow 真专业、它理论上完全具备了这些能力”。 +它的局限性：这是一种“元认知（Meta-level）”的静态打分。就跟考驾照拿到了满分一样，理论上他是个好司机。但当他在真实项目中遇到极其复杂的业务边界问题时（比如复杂的上下文缺失、工具调用卡壳），空有完美 Prompt 的 Agent 一样可能会把任务搞砸。 +阶段：发生在出厂前 / 编译期（Training & Deployment Phase）。 +【法】QA/Judge Agent 的业务验收 —— 类似于“集成测试 / 实际上路出单” +它在校验什么？：它审查的是 Agent 的真实业务产出（Artifacts）。比如 CEO 让 Coder Agent 写了一个登录页面，QA Judge Agent 根本不关心 Coder 的 Prompt 写得多好，它只负责去审阅最后交出来的那段 React 代码到底能不能跑、有没有 Bug、是否符合需求规范。 +阶段：发生在运行时 / 生产环境（Runtime & Execution Phase）。 +2. 它们是如何完美结合的？（闭环全景图） +在强大的自主公司架构中，两者是**“上下半场”被彼此触发**的关系。结合刚才跑通的流水线，全网完美的自动演进链路是这样的： + +第一环（产出与验收）：日常业务跑在“QA Judge”的法度下 +下发任务：CEO 接到需求，派发给当前 v1.3 版本的业务 Agent（比如 CTO）。 +执行与送审：CTO 写好了一份技术架构图。CEO 不会自己看，而是把它扔给预设的 QA/Arch-Judge Agent 盲审。 +日常小修小补：如果 Judge 觉得某个细节不合理，打回给 CTO 重新改。这个时候 CTO 只是在当前会话里自我调整（这时候不需要重启 FDE 流水线）。 +第二环（瓶颈与重构）：被“QA Judge”触发的“FDE 训练” +发现致命短板：如果 Judge 发现 CTO 连续 3 次都在“高并发架构设计”上翻车，Judge 会向 CEO 提交定损报告：“当前 CTO 能力存在系统性认知缺陷（缺乏高并发知识库）”。 +触发造车（Retrain）：CEO 根据这份报告，判定现有的员工“器”不行了，必须让“术”介入。CEO 调用 API 给 + +Innovator + 发送指令：“马上把 CTO 弄回炉重训，附带这份 QA 的失败日志，重点加强高并发治理边界”。 +启动你说的 Benchmark 循环：此时，Innovator 接管，启动 Hunt -> Digest -> Evolve： +Digester 根据 QA 之前给出的失败原因，生成了一份极度苛刻的 benchmark.md（高并发处理必须包含 XXX，否则扣分）。 +Evolver 不断重写和迭代 CTO 的 SKILL.md，直到按照这份新考核标准评分 >= 95 分。 +重新上路部署：v1.4 版本的强力 CTO 满血回归，接手之前失败的任务。这次做完后交由 QA Judge，顺利验收通过（OKR 节点闭环）。 +总结 +你现在实现的 Digest Benchmark >= 95 分，保证了 LemonBoss 兵工厂里走出来的每一个兵（Agent）绝对是理论最强、装备精良的（出厂质量）。 +而增加的 Judge Agent 管理流，则保证了在具体打仗时，业务结果是100%兜底且客观过关的（业务质量）。一旦在真实战场发现某个兵的素质不够，再去触发那个工厂的 FDE 流水线 给它升级。这就是真 正自洽的自动驾驶级 AI 公司架构！ \ No newline at end of file diff --git a/docs/todo/future/system-design/14-milestones.md b/docs/todo/future/system-design/14-milestones.md new file mode 100644 index 0000000..f5720dd --- /dev/null +++ b/docs/todo/future/system-design/14-milestones.md @@ -0,0 +1,104 @@ +# 14. 里程碑与迭代计划 + +## Phase 1 — 基座搭建 (Week 1-2) + +> **目标**: 实现 Agent 原子模型和基本 Loop 引擎 + +- [ ] `agent-core` 包：Agent 基类 + SubAgent/RoleAgent/BossAgent +- [ ] `loop-engine` 包：通用循环引擎（5 阶段） +- [ ] `memory` 包：三级记忆系统（短期 + 长期 + Session） +- [ ] 接入 ACP Core 作为 AI 内核 +- [ ] 基本的 Agent CRUD API +- [ ] SQLite 数据库初始化 +- [ ] Agent 沙盒 workspace 目录结构 ← v1.1 + +## Phase 2 — Loop 闭环 + 元能力 (Week 3-4) + +> **目标**: 实现完整的三层循环闭环和 BossAgent 动态建设能力 + +- [ ] BossAgent 5 分钟反思循环 +- [ ] RoleAgent 任务拆解与 SubAgent 调度 +- [ ] SubAgent 沙盒执行与结果上报 +- [ ] Agent-to-Agent 通讯协议（含 v1.1 handover/feedback） +- [ ] Goal 追踪与进度计算 +- [ ] Cron 定时任务引擎 +- [ ] BossAgent Meta Tools（agent.create/redefine/destroy/pipeline.set） ← v1.1 +- [ ] PipelineRouter 流转服务 ← v1.1 +- [ ] 三层差异化反思机制 ← v1.1 + +## Phase 3 — 知识与记忆 (Week 5-6) + +> **目标**: 完善知识库和记忆系统 + +- [ ] 文档知识库（文件上传、FTS5 全文搜索） +- [ ] 向量搜索引擎 +- [ ] 长期记忆的经验提取与检索 +- [ ] 反思记忆的智能复用 +- [ ] Agent Define 动态管理 + +## Phase 4 — Gateway 接入 (Week 7-8) + +> **目标**: 对接外部 IM 渠道 + +- [ ] 飞书 Gateway 适配器 +- [ ] WhatsApp Gateway 适配器 +- [ ] 钉钉 Gateway 适配器 +- [ ] 统一消息路由 +- [ ] IM ↔ Agent 双向通讯 + +## Phase 5 — 控制面板 (Week 9-10) + +> **目标**: 构建前端监控与管理界面 + +- [ ] 公司运营仪表盘 +- [ ] Agent 拓扑图（可视化组织架构 + Pipeline DAG） +- [ ] Goal 进度面板 +- [ ] 日志查看器 +- [ ] Agent 创建/编辑界面 + +## Phase 6 — 优化与开放 (Week 11-12) + +> **目标**: 性能优化和系统开放 + +- [ ] 并发控制与资源管理优化 +- [ ] Loop 性能调优 +- [ ] 多用户隔离（"一人一公司"） +- [ ] 开放 API 文档 +- [ ] 压力测试与稳定性验证 + +--- + +## 附录 + +### A. 关键设计决策 + +| 决策 | 选择 | 替代方案 | 理由 | +|------|------|----------|------| +| Agent 基类继承 | 单继承 + 组合 | 接口实现 | JS 无接口概念，组合更灵活 | +| 通讯协议 | ACP JSON-RPC | REST API | Agent 间需要流式双向通讯 | +| 数据库 | SQLite | PostgreSQL | 无外部依赖，轻量部署 | +| 向量搜索 | 本地嵌入 | 云服务 | 数据隐私 + 离线可用 | +| 进程隔离 | 子进程沙盒 | Docker 容器 | 轻量级，启动快 | +| Pipeline 管理 | BossAgent Memory | 框架层模块 | Pipeline 是动态推理产物，不是静态模板 | +| Agent 内部实现 | 沙盒自治 | 框架预设 | 框架不应限制 Agent 的创造力 | + +### B. 术语表 + +| 术语 | 英文 | 定义 | +|------|------|------| +| 感知 | Perceive | Agent 从环境获取信息的过程 | +| 推理 | Reason | Agent 基于信息进行逻辑推理的过程 | +| 拆解 | Decompose | 将复杂任务拆分为可执行子任务 | +| 反思 | Reflect | Agent 对执行结果进行评估和策略优化 | +| 闭环 | Loop | 完整的感知→执行→反馈→优化循环 | +| 间隙 | Gap | 当前状态与目标之间的差距 | +| 流转 | Handover | 同级 Agent 之间的任务交接 | +| 元能力 | Meta Capability | BossAgent 操控框架本身的系统级工具 | +| 自治 | Autonomy | Agent 在沙盒内独立决策和执行的能力 | + +--- + +> 📝 **文档版本**: v1.1 +> 📅 **创建日期**: 2026-03-21 +> 📅 **更新日期**: 2026-03-23 +> ✍️ **维护者**: LemonBoss Team diff --git a/docs/todo/future/system-design/25-harness-engineering-improvements.md b/docs/todo/future/system-design/25-harness-engineering-improvements.md new file mode 100644 index 0000000..c562b25 --- /dev/null +++ b/docs/todo/future/system-design/25-harness-engineering-improvements.md @@ -0,0 +1,59 @@ +# 25. Harness Engineering Improvements (Agent 上下文与生命周期优化) + +## 1. 背景与目标 (Background & Objectives) + +随着 LemonBoss 架构从单体 Agent 演进为多租户下的“数字代理公司（Corporate OS）”，我们的宏观阵法（层级汇报、跨部门协作、OKR 分解）已初具规模（参考之前的相关系统设计）。然而，基于对前沿 Harness Engineering 最佳实践的深度反思，单个 Agent 节点在处理长链路复杂任务时，依然面临**“上下文衰减（Context Decay）”**、**“信息污染（Noise Pollution）”**、以及**“试错成本高昂（High Trial Cost）”**三大核心痛点。 + +为了确保底层每一个“数字员工”即使在超长命名的商业运营中也不会发生注意力弥散（Attention Decay），我们提出以下补充重构计划。该计划的核心思想是：**做精信息喂食、隔离决策上下文、构建自查闭环。** + +--- + +## 2. 核心改进计划 (Core Improvement Plans) + +### 改进点一：将四阶段分解固化为基座 Agent 的四大元技能 (Meta-Skills Integration) +**现状痛点**：当前单个 session 会承载一个 Agent 从“思考规划”到“调用执行”直至“修复 Bug”的全生命周期。后期 Session Prompt 过长（超过甜区限度），导致关键指令被稀释，且执行边界模糊。 +**改进策略**：我们将 `Research` -> `Plan` -> `Execute` -> `Verify` 不仅作为宏观规范，而是**实际固化为基座 Agent (Base Agent) 标准配备的四大元技能包（Meta-Skills）**。 +1. **按需装载独立技能树 (Dynamic Skill Invocation)**：在底层设定中，为每一个 Base Agent 提供四个相互独立的元技能引擎接口。每次面临新任务，代理根据自身所处的流转阶段，主动调用加载专属的技能包（如只调用 `skill_plan` 去出方案）。 +2. **基于技能切换的 Context Flush（上下文切断与防污染）**：一旦当前阶段的技能执行完毕（例如调用 Planner 技能产出了 `architecture.md`），该 Session 生命周期强制结束归档。当进入下一环节调起 `skill_execute` 技能时，新开一条绝对干净的 Session，只传入上一步确定的干货文件，彻底断绝跨阶段的幻觉与信息污染。 + +### 改进点二：实施“事前阻断阀”管理 (Human/Master pre-approval) +**现状痛点**：人类往往在 Agent 完全做错产出一堆无效代码后（即事后）去执行 Code Review，纠错成本极高。 +**改进策略**： +1. **杠杆前置审查**：当 CEO 或 CTO 这类管理层 Agent 产出“规划文档（Plan / Architecture）”后，系统强制挂起该节点的 `status`。 +2. **等待放行命令**：必须由 Master（人类用户） 或高阶 Validator/Innovator Review 批准该规划文档。一旦驳回，重做 Plan；一旦批准，才能生成下游子任务清单（Task Spawning）并消耗算力。以一行 Plan 的纠正，避免百行代码的错误生成。 + +### 改进点三：渐进式披露与去工具化 (Progressive Disclosure & Minimized Tools) +**现状痛点**：为了提供强大的功能，在 `tools.md` 或 System Prompt 里塞入海量工具说明与技能细则，导致模型注意力过载或陷入决策瘫痪（Decision Paralysis）。 +**改进策略**： +1. **多级目录动态按需加载**：确立三级机制： + - Level 1 (`CLAUDE.md` / `identity.md`)：只讲最最核心的存活元规则和找资料入口。 + - Level 2 (`SKILL.md`)：作为外挂组件引擎，只有触发特定领域关键词，引擎才将其注给 Agent `system_prompt`。一旦切走任务则将其卸载（Unload）。 + - Level 3 (`references`)：基于 RAG 工具被动按需调取日志或全量文件。 +2. **修剪泛洪工具群**：将非必须的复杂组合 API 下架。退守“最强的万能扳手”：赋予 Agent 沙盒受控的终端执行与代码编写权（如受限的 Python 解释器或 `bash`），让 Agent 现写代码去满足需求，而非提供写死上百个微工具集。 + +### 改进点四：单体自治理的“微小自反思闭环” (Micro Self-Verification) +**现状痛点**：完全依赖事后外置的角色（如 `QA-Judge` 或者遭遇硬报错再触发反馈），链路长且对中控要求高。 +**改进策略**： +1. **植入 Local Verify Hook**：规定在下级执行类 Agent 调用 `report_task` 汇报 `status: PASS` 之前，必须调用自身的沙箱测试或执行一次自我反思的 `verify` 工具。 +2. **Autoresearch Error Loop**：为底层 Agent 本地增加 `_lessons.md`（试错经验暂存区）。在执行重试（Retry）循环时，如果不通过，先强制写一条经验记录到 `_lessons.md` 中。下次 retry 带上本条经验执行，避免单次死循环卡点。此级循环不惊动顶层的 Innovator（FDE），实现“兵不烦将”。 + +### 改进点五：引入算力经济学观测 (Cost & Profiling Observability) +**现状痛点**：对“系统表现和行为”透明（有 Logs），但对“运营成本”无感知，不符合 Corporate OS（企业组织）要求。 +**改进策略**： +1. 建立 `logs/billing` 观测维度：在 `pipeline_runs` 和 `audit` 同级，加入 Token 消耗监测系统。 +2. 精确计算每一次交接任务“花费的 API 计价预估”。给 CEO 提供财务数据维度支持，帮助甄别“能力较弱导致长耗时高频失败”的节点，为其发起汰换重构提供商业依据。 + +--- + +## 3. 落地 Roadmap (Implementation Roadmap) + +| 阶段 | 里程碑 (Milestones) | 涉及模块 (Modules) | 预期时间 | +|------|----------------|----------------|----------| +| **Phase 1** | **微观验证引入**：在现有节点中强制引入自我校验 (Local Verify)，以及局部 `_lessons.md`。 | `agent-chat.js`, 基础 `templates/` 补充设定 | P1 优先 | +| **Phase 2** | **四大元技能装配与重构**：为 Base Agent 植装并切分 `Research/Plan/Execute/Verify` 四大独立技能入口，支持阶段流转中的 Context Flush。 | `memory-service.js`, `boss-meta-capabilities`, `master-session` | P1 优先 | +| **Phase 3** | **事前阻断流程化**：集成规划节点停摆拦截，接入前端 UI 以获得 Human/Master 的手动 Approved 后才能唤醒下游。 | `schema/goals`, Web UI 组件 | P2 规划 | +| **Phase 4** | **重置工具与按需挂载**：清理多余的工具并实施 `SKILL.md` 动态路由加载机制，提高上下文利用率甜区表现。 | `skill-registry/service`, 工具池整理 | P2 规划 | +| **Phase 5** | **经济学审计引入**：Token 数理追踪统计埋点，提供可视化报表支持（Cost Tracker Dashboard）。 | `logger/billing_service` | P3 未来探讨 | + +> **最后修订记录:** +> - 本规划文档由对行业 Harness Engineering 原理和 LemonBoss 特性对比后的工程反思形成，将指导未来一至两个大版本的演进。 diff --git a/docs/todo/system-design/27-graph-agent-architecture.md b/docs/todo/system-design/27-graph-agent-architecture.md index 9c57657..17e0fa8 100644 --- a/docs/todo/system-design/27-graph-agent-architecture.md +++ b/docs/todo/system-design/27-graph-agent-architecture.md @@ -212,7 +212,7 @@ CREATE TABLE work_graph_edges ( |-------|------|--------|----------| | **P0 地基** ✅ | 建表 + 现有数据迁移，不改变任何现有执行路径 | `system_agents`/`org_graph_*` 表；把现有 `system/agents/` + `system/templates/` 目录扫描导入为种子数据（`system_agents` 行，`scope` 按当前所属推断） | 迁移脚本跑完，`system_agents` 表行数与现有 agent+模板目录数一致（**实际行数与本文档最初估计不同，见第七节**）；现有 `company-service.js` 行为不变（并行只读验证，已确认零改动） | | **P1 虚拟引用** | 停止文件拷贝，改为引用 | 改造 `AgentManager.getAgentConfig()` + `PromptBuilder.build()` 支持 `(agentId, companyId)` 寻址；`company-service.hire()` 改为创建 org_graph 引用节点而非 `_copyTemplate()`。细化需求与设计见 [27-P1 虚拟引用寻址](./27-p1-virtual-reference.md) | 新雇佣的 agent 不再产生文件拷贝，调用时能正确拼装公共+私有上下文；旧公司（仍是拷贝模式）继续可跑，不强制迁移存量数据 | -| **P2 Org Graph** | `company.json.agents[]` 迁移为图结构 | `org_graph_nodes`/`edges` 落地；HR/CEO 招聘走新表 | 现有 Company Dashboard 前端能正确读出 org graph 并渲染（哪怕暂时按列表展示） | +| **P2 Org Graph** | `company.json.agents[]` 迁移为图结构 | `org_graph_nodes`/`edges` 落地；HR/CEO 招聘走新表。细化需求与设计见 [27-P2 Org Graph 落地](./27-p2-org-graph.md) | 现有 Company Dashboard 前端能正确读出 org graph 并渲染（哪怕暂时按列表展示） | | **P3 Work Graph 最小闭环** | 单向执行，先不做回退 | work-graph-planning agent（system agent，新建）；`work_graphs`/`nodes`/`edges` 表；顺序执行器（success → next，fail → 停止/标记 blocked，暂不回退） | 一个 goal 能被规划成 2-3 节点的图并顺序跑完，状态正确落库 | | **P4 回退 + Loop-Validator** | 引入死循环防护 | loop-validator system agent + 内置熔断 skill；`edge_kind=backward` 支持；3.4 第 5 点的执行前结构校验 | 人为构造一个"总是失败"的节点，验证第 4 次回退被 loop-validator 强制终止，且校验能拒绝"回退边未经过 validator"的非法图 | | **P5 自我进化** | 公共记忆蒸馏机制 | 公共 `memory.md` 写入走自省校验 + git 版本化；company-scoped → public 的升级门槛复用现有 benchmark ≥95 链路 | 同一 public agent 被两家公司调用后，`memory.md` 有可观察的增量更新，且能 git revert 到升级前版本 | @@ -245,3 +245,4 @@ P0 阶段的处理方式是**迁移脚本层面的临时保护**：`system_agent ### 关联文档 P1（虚拟引用寻址）的详细需求与设计已有独立草稿：[27-P1 虚拟引用寻址](./27-p1-virtual-reference.md)。 +P2（Org Graph 落地）的详细需求与设计见：[27-P2 Org Graph 落地](./27-p2-org-graph.md)。 diff --git a/docs/todo/system-design/27-p2-org-graph.md b/docs/todo/system-design/27-p2-org-graph.md new file mode 100644 index 0000000..08d9a27 --- /dev/null +++ b/docs/todo/system-design/27-p2-org-graph.md @@ -0,0 +1,437 @@ +# 27-P2. Org Graph 落地 — 需求与设计文档 + +> **所属**: [27 Graph Agent 架构](./27-graph-agent-architecture.md) 的 Phase P2（"Org Graph"） +> **版本**: v0.2（设计阶段，未实现；相比 v0.1 的核心变化见 §二末尾"为什么从『招聘时可选传 reportsTo』升级为『org-graph-creator 自动生成』"） +> **日期**: 2026-08-15 +> **前置**: P0 地基已完工并提交（commit `8421f55`，`server/services/graph-db.js` + `graph-seed-service.js`）。**P1（虚拟引用寻址）目前仍是设计稿，未实现**——`server/services/graph-service.js` 尚不存在。§九说明 P2 为什么不需要等 P1 落地即可开工。 + +--- + +## 一、目标与非目标 + +### 目标（本阶段要交付什么） + +按 27 号文档 P2 行的原始定义（27-graph-agent-architecture.md:215）： + +> `company.json.agents[]` 迁移为图结构。`org_graph_nodes`/`edges` 落地；HR/CEO 招聘走新表。验收标准：现有 Company Dashboard 前端能正确读出 org graph 并渲染（哪怕暂时按列表展示）。 + +结合最新明确的方向——**org graph 不再是招聘过程中零散声明出来的副产品，而是由公司的第一个 agent「org-graph-creator」在公司创建之初，根据公司目标/描述 + 一套按公司类型区分的 org graph 模板 + 当前可招聘的 agent 模板库，一次性规划并执行出来的**——展开为四件具体的事： + +1. **补全边（edges）+ 提供写入机制**：P0 只回填了节点（来自 `company.json.agents[]` 的扁平角色名），`org_graph_edges` 表建了但从未写入过一行。P2 要让 `hire()` 支持声明 `reportsTo`，这是所有汇报关系（不管谁写的）最终落地的**唯一通道**。 +2. **org-graph-creator agent**：新增一个系统级 agent 模板，作为每家新公司创建后自动"入职"的第一个 agent。它读公司目标/描述、读 `system/org-graph-templates/*.json` 里的候选组织结构模板、读当前 `system/templates/*` 实际能招到的角色，综合判断出一套具体的组织结构，再按拓扑序（先上级后下级）依次调用 `hire()` 把这套结构真正建出来。 +3. **组织结构模板库**：新增 `system/org-graph-templates/`，用一组按"公司类型"归类的 JSON 骨架文件（开发型/内容型/运营型……）表达"这类公司通常长什么样"，供 org-graph-creator 参考、裁剪、组合——不是每家公司都严格照抄某一个模板，模板只是起点。 +4. **提供一个可读的视图**：新增只读 REST 端点把 `(nodes, edges)` 拼成组织架构数据，Company Dashboard 至少能按"谁向谁汇报"分层列表展示。 + +### 非目标（本阶段明确不做） + +- **不做**图形化组织架构图（连线画布、拖拽调整层级）——验收标准原文写明"哪怕暂时按列表展示"即可。 +- **不做** `company.json.agents[]` 的废弃或只读化——很多现有代码（`listAgents()`、心跳、Dashboard 概览卡）仍在直接读它，P2 阶段 `org_graph_nodes`/`edges` 是**追加写入**，不是替换现有读取路径。 +- **不做**存量公司历史雇佣关系的"猜测式"补边——见 §四.12。 +- **不做**已经跑过一次 org-graph-creator 的公司的"重新规划/推倒重来"——org-graph-creator 在 P2 阶段是**一次性的公司创建时动作**，不是可以随时对着一家已经有员工的公司重跑的东西。公司后续想调整组织结构（加人、换汇报对象），走的是 HR agent 走既有 `hire()`/`reportsTo` 机制做增量调整（§四.4），不是重新触发 org-graph-creator。重新规划一家运行中公司的组织结构涉及"已有节点怎么办、正在跑的任务怎么办"，复杂度明显更高，留作 Open Question（§八.5）。 +- **不做**给 `company.json` 加一个枚举型的 `type` 字段——公司类型的判断是 org-graph-creator（LLM）基于目标/描述做的一次性推理，不是一个需要长期维护、需要建校验逻辑的结构化字段。org-graph-creator 执行完可以顺手把自己判断出的类型写成一段说明文字存档（§四.9），但那是审计用的自由文本，不是可枚举、可用于 if-else 分支的字段。 +- **不做** Work Graph（P3）、Loop-Validator（P4）——P2 只处理静态协作结构。 +- **不做** `system/agents/` 与 `system/templates/` 之间 6 个同名 id 的冲突解决——这是 27 号文档 §七遗留给"实现阶段之前"的产品决策，P1 §九 Q4 建议在排 P2 之前解决掉，本文档在 §八重申但不阻塞技术交付。 + +--- + +## 二、背景：为什么"边"是空的，不是"没扫描到" + +27 号文档 §四数据模型草稿把 `org_graph_edges` 定义为"公司静态协作结构"的关系边，`relation_type` 取 `reports_to` / `collaborates_with`（27-graph-agent-architecture.md:154-160）。但走查现有代码后发现：**这不是"数据源里有汇报关系、只是没写代码去读"，而是系统里从来没有任何地方产生过"谁向谁汇报"这条信息**： + +- `company.json` 的 schema（`company-service.js:50-69`）里 `agents` 是纯字符串数组，没有汇报关系字段。 +- HR Agent 的招聘 SOP（`system/templates/hr/agent.md:18-32`）里，CTO 给 HR 发的"招聘需求单"是一句自然语言，HR 执行的命令是 `node bin/lemon.js company hire --id <公司ID> --role <角色名> --type executor --name "岗位名称"`——**没有 `--reportsTo` / `--manager` 这类参数**，`bin/lemon.js` 的 `parseArgs` 选项列表（`bin/lemon.js:63-67`）里也确实没有。 +- `config.json` 里唯一带层级意味的字段是 `parentId`（`packages/agent-core/AgentScaffold.js:63`「上级 Agent ID」），但它**只在 `scaffoldNewAgent()`（培养路径，company-service.js:241-283）里被写入**——走模板复制的 `hire()`（招聘路径，绝大多数场景）压根不 touch `parentId`。 +- 各模板 `config.json` 的 `type` 字段本身就不构成一致的层级体系：实际扫描结果是 `cxo` / `specialist` / `executor` / `devloop` / `meta` / `quality_assurance` / `skill` 混杂（见 §三.3），`ceo` 模板目录甚至**没有 `config.json`**，导致 `hire()` 里"`type==='cxo'` 才设置 `company.ceo`"的逻辑（company-service.js:211-213）对字面意义上的 "ceo" 角色从不生效，反而任何被标 `type: 'cxo'` 的角色（`cto`/`coo`/`innovator`）招聘时会覆盖 `company.ceo`——这是一个和 P2 无关、但 org-graph-creator 大概率会踩到的既有 bug，见 §八.6。 + +**结论一**（v0.1 就已确立，本次不变）：没有任何历史数据可以无损映射成 `reports_to` 边，`type` 字段也不能作为可靠的层级推导依据。存量数据只补节点（P0 已完成），不自动猜边。 + +### 为什么从"招聘时可选传 reportsTo"升级为"org-graph-creator 自动生成" + +v0.1 的方案是把 `reportsTo` 做成 `hire()` 的一个可选参数，指望 HR/CEO agent 在招聘时"顺手"传一下。这个方案本身没有错——它仍然是本版本的**底层写入机制**（§四.4 完整保留）——但作为唯一的产生边的路径，有一个结构性弱点：HR 是**被动响应**式地一个一个招人（"CTO 说招三个人，HR 就招三个人"），从来不会有一个时刻"通盘看一眼这家公司应该长成什么样"。用户指出的改进方向是补上这个缺失的环节：公司创建时先有一个专职的 agent 站在全局视角，根据这家公司**要做什么**（目标/描述）参考"这类公司通常怎么搭"（模板库），一次性把骨架定下来，之后 HR 的增量招聘只是在这个骨架上加叶子节点。这不是推翻 v0.1，而是在它之上加一层"谁来负责最开始把 reportsTo 填对"的机制。 + +--- + +## 三、现状代码走查（决定设计边界的关键证据） + +### 3.1 `org_graph_edges` 表已建但从未被写入 + +`server/services/graph-db.js:54-60` 定义了表结构（`id` 是 `INTEGER PRIMARY KEY AUTOINCREMENT`，不是 27 号文档草稿里写的 `TEXT PRIMARY KEY`——P0 实现时改了主键类型，P2 沿用实际实现）。`server/services/graph-seed-service.js:202` 的注释明确写着"`org_graph_edges` 本阶段留空——company.json 目前没有汇报关系数据，是预期状态，不是 bug"。 + +### 3.2 真正被前端调用的招聘/辞退路径，和 `CompanyService` 里同名方法不是一回事 + +- **招聘**：`POST /:companyId/hire`（`server/routes/company.js:908`）调用的是 `companyService.hireWithTraining()`（`company-service.js:381-383`，内部转调 `this.hire()`），`opts` 会从 route 的 `req.body` 一路传到 `hire()`。 +- **辞退**：`POST /:companyId/fire`（`server/routes/company.js:1009-1055`）**没有调用 `companyService.fire()`**。它在路由 handler 里直接重新实现了一遍逻辑：停心跳 → 按 `archive` 参数决定归档还是删除 → 直接改 `company.agents` 数组。`CompanyService.fire()`（company-service.js:411-433）**唯一的调用方是测试脚本 `server/scripts/test-company-e2e.js:227`，是死代码路径**。 +- **公司创建**：`POST /create`（`server/routes/company.js:22-38`），目前只创建一个"没有员工的空壳公司"，响应里写着"请通知 MasterBot 从 Template 库中雇佣 Agent"——**创建流程本身不会自动招任何 agent**，这是 P2 要打破的现状（见 §四.10）。 + +给"辞退"加清理逻辑必须改 `/fire` 路由 handler 本体；给"创建"接上 org-graph-creator 必须改 `/create` 路由 handler 本体——两者是同一类问题：真正生效的代码在路由层，不在 service 层的对应方法里。 + +### 3.3 `type` 字段现状扫描 + +对 `system/templates/*/config.json` 逐个读取 `type` 字段（39 个模板目录，2026-08-15 现场扫描）： + +| type 取值 | 数量 | 代表角色 | +|---|---|---| +| `specialist` | 22 | hr, digester, hunter, content-selector, ... | +| `cxo` | 3 | cto, coo, innovator | +| `devloop` | 6 | devloop-pm/architect/coder/tester/integrator/triager | +| `executor` | 2 | evolver, scrapling_crawler | +| `meta` | 1 | evolver-youtube-crawler | +| `quality_assurance` | 1 | qa-judge | +| `skill` | 1 | claude-youtube-skills | +| 无 `config.json` | 1 | **ceo** | + +没有任何字段能区分层级，`type` 只是粗粒度的职能分类。 + +### 3.4 `listTemplates()` 已经提供了 org-graph-creator 需要的"可招聘角色清单" + +`company-service.js:480-` 的 `listTemplates()`（`GET /api/company/templates`，HR 已经在用，`system/templates/hr/agent.md:17` 的 `node bin/lemon.js company templates`）对每个模板目录返回 `{id, name, type, description, benchmarkScore, ...}`。这正是 org-graph-creator 判断"模板里写的这个角色，现实里有没有对应的可招模板"所需要的原始数据——**不需要为 org-graph-creator 新开一个查询接口**，复用现成的 CLI 命令即可（见 §四.9）。 + +### 3.5 Company Dashboard 现状：纯扁平列表，无层级渲染 + +`web/src/views/CompanyDashboard.vue:212-229`（"团队成员" tab）用 `companyAgents` 渲染一个 `agents-grid`，卡片之间没有连线也没有分组。P2 加"至少列表展示"是**新增**一块 UI。 + +--- + +## 四、设计方案 + +### 4.1 总体架构与触发时机 + +``` +POST /api/company/create + │ + ├─ companyService.create()：建空壳公司（company.json.agents=[]，不变） + │ + ├─ 【新】companyService.hire(companyId, 'org-graph-creator', {}) + │ org-graph-creator 是系统模板，招聘流程与其他角色完全一致（走 §3.2 已有的 hire() 路径） + │ 不传 reportsTo —— 它是基础设施角色，不挂在业务汇报树里（见 §4.9 末尾） + │ + └─ 【新】fire-and-forget 触发首轮对话（复用 /hire 路由里已有的 + fetch(`/api/agent/{agentId}/chat`) 异步模式，company.js:917-940） + 消息内容：公司 id/name/description（见 §4.10） + │ + ▼ + org-graph-creator（LLM agent，system/templates/org-graph-creator/） + 1. 读 system/org-graph-templates/*.json（结构骨架候选集，见 §4.8） + 2. 读 `node bin/lemon.js company templates`（现实里能招到的角色，见 §3.4） + 3. 综合公司 description + 上面两份数据，判断/裁剪出一套具体组织结构 + 4. 把这套结构写成一份规划记录（workspace/org-plan.md，见 §4.9） + 5. 按拓扑序（先上级、后下级）依次执行： + node bin/lemon.js company hire --id <公司ID> --role <角色> --reportsTo <上级角色> + 6. 全部招完后关闭自己的心跳，转入休眠（一次性任务，见 §4.9 末尾） +``` + +`hire()`/`org_graph_nodes`/`org_graph_edges`/`reportsTo` 校验规则（§4.4）是这套流程的**底层机制**，org-graph-creator 只是这套机制目前最重要的调用方——HR agent 后续做增量招聘时，走的是同一条 `hire()` + `reportsTo` 路径，不是另一套。 + +### 4.2 数据模型改动（在 P0 schema 上追加，不改已有列） + +```sql +-- org_graph_nodes：追加"是否仍在职"标记，供 fire() 软删除用 +ALTER TABLE org_graph_nodes ADD COLUMN status TEXT NOT NULL DEFAULT 'active'; +-- status: 'active' | 'removed' + +CREATE UNIQUE INDEX IF NOT EXISTS idx_org_graph_nodes_company_role_active + ON org_graph_nodes(company_id, role_name) + WHERE status = 'active'; + +CREATE TABLE IF NOT EXISTS org_graph_edges ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + company_id TEXT NOT NULL, + from_node_id INTEGER NOT NULL REFERENCES org_graph_nodes(id), + to_node_id INTEGER NOT NULL REFERENCES org_graph_nodes(id), + relation_type TEXT NOT NULL CHECK (relation_type IN ('reports_to','collaborates_with')), + status TEXT NOT NULL DEFAULT 'active', + created_at TEXT NOT NULL +); +CREATE UNIQUE INDEX IF NOT EXISTS idx_org_graph_edges_dedupe_active + ON org_graph_edges(company_id, from_node_id, to_node_id, relation_type) + WHERE status = 'active'; +``` + +放进 `server/services/graph-db.js` 的 `getDb()` 里，用 `CREATE ... IF NOT EXISTS` / 探测后 `ALTER TABLE ... ADD COLUMN`，跟 P0 一贯的"只加不改"风格一致。**为什么软删除**：`org_graph_nodes`/`edges` 是审计轨迹的一部分（类比 DevLoop `timeline.ndjson` 的 append-only 原则），物理删除会让"这家公司 3 个月前的组织架构长什么样"无法回答。 + +### 4.3 新模块 `server/services/org-graph-service.js`（不复用/不等待 P1 的 `graph-service.js`） + +```js +// server/services/org-graph-service.js +// 职责：org_graph_nodes/edges 的读写，供 company-service.js 和 routes/company.js 调用。 +// 与假想中 P1 的 graph-service.js（管 agent.md 从哪读）职责不同、文件不同，都基于 graph-db.js 的 +// getDb()，若 P1 之后落地，两个文件共存，org_graph_nodes 表 schema（含本文档新加的 status 列） +// 双方共享，实现前需互相 diff 一次 graph-db.js。 + +function upsertNode(companyId, roleName, systemAgentId = roleName) { /* INSERT ... ON CONFLICT ... */ } +function removeNode(companyId, roleName) { /* UPDATE status='removed'，级联失效相关边 */ } +function addEdge(companyId, fromRoleName, toRoleName, relationType) { /* 见 4.4 校验规则 */ } +function getOrgGraph(companyId) { /* JOIN nodes + edges + system_agents */ } + +module.exports = { upsertNode, removeNode, addEdge, getOrgGraph }; +``` + +### 4.4 `hire()` / `hireWithTraining()` 改动 —— 新增可选 `reportsTo`（org-graph-creator 与 HR 共用的机制） + +`company-service.js:189` 的 `hire(companyId, roleName, opts = {})`：`opts` 新增可选字段 `reportsTo`（角色名字符串，指向同一家公司里另一个已存在的角色）。模板命中分支末尾追加： + +```js +try { + orgGraphService.upsertNode(companyId, roleName); + if (opts.reportsTo) { + orgGraphService.addEdge(companyId, roleName, opts.reportsTo, 'reports_to'); + } +} catch (e) { + console.warn(`[Company] org_graph 写入失败（不影响招聘结果）: ${e.message}`); +} +``` + +try/catch-not-fail：`org_graph_nodes`/`edges` 在 P2 阶段仍然是 `company.json.agents[]` 的旁路记录，写失败不能让招聘这个更重要的操作跟着失败——**这一点对 org-graph-creator 尤其重要**：它会在几十秒内连续调用 `hire()` 十几次，任何一次的 org-graph 旁路写入失败都不该让整个批量招聘链路中断。 + +**`reportsTo` 校验规则**： + +1. `reportsTo` 指向的角色必须已经是该公司 `org_graph_nodes` 里一条 `status='active'` 的节点——否则报错拒绝这次 `hire()`。**这一条对 org-graph-creator 是硬约束**：它必须按拓扑序（先招上级、后招下级）执行，见 §4.11。 +2. `reportsTo === roleName` 直接拒绝。 +3. 不做环检测——留到 P4 Loop-Validator 上线、或后续 Work Graph 需要拓扑排序时再补，刻意简化。 + +`hireWithTraining()`（company-service.js:381-383）本身只是 `hire()` 的一层包装，`opts` 透传。**Route 层需要同步改**：`server/routes/company.js:908-914` 的 `/hire` handler 目前从 `req.body` 解构时没有 `reportsTo` 字段，需要加上。 + +### 4.5 `/fire` 路由改动（不是 `CompanyService.fire()`——见 §3.2） + +`server/routes/company.js:1009-1055`，"从公司 agents 列表中移除"之后追加： + +```js +try { + orgGraphService.removeNode(companyId, role); +} catch (e) { + console.warn(`[Fire] org_graph 清理失败（不影响辞退结果）: ${e.message}`); +} +``` + +`removeNode()` 把该节点 `status` 置为 `removed`，同时把所有以它为 `from_node_id`/`to_node_id` 的 active 边一并置为 `removed`。`CompanyService.fire()` 同步做一样的改动（仅为不让测试脚本继续验证一个跟线上不一致的假实现）。 + +### 4.6 只读 REST 端点：`GET /api/company/:companyId/org-graph` + +```js +router.get('/:companyId/org-graph', (req, res) => { + res.json(orgGraphService.getOrgGraph(req.params.companyId)); +}); +``` + +返回形状： + +```json +{ + "nodes": [ + { "id": 12, "roleName": "cto", "systemAgentId": "cto", "status": "active" }, + { "id": 15, "roleName": "hr", "systemAgentId": "hr", "status": "active" } + ], + "edges": [ + { "fromRoleName": "hr", "toRoleName": "cto", "relationType": "reports_to" } + ] +} +``` + +不在这一层拼装 `name`/`type`/心跳状态——那些字段权威来源始终是 `companyService.listAgents()`，前端按 `roleName` 去 join 已经在加载的 `companyAgents` 列表。 + +### 4.7 前端：Company Dashboard 新增"组织架构"渲染 + +不新增 tab。在"团队成员" tab 的 `agents-grid` 上方插入按 `reports_to` 边分层的缩进列表；没有边数据的节点退化成当前的平铺 grid（保证存量公司 Dashboard 展示效果不变）；不引入图形库依赖。 + +### 4.8 `system/org-graph-templates/`：组织结构模板库 + +新增目录，每个文件是一种"公司类型"的组织结构骨架，供 org-graph-creator 参考： + +```json +// system/org-graph-templates/dev.json +{ + "id": "dev", + "label": "开发型公司（持续构建/维护软件产品）", + "whenToUse": "公司目标包含实现某个产品/功能、需要跑代码开发-测试循环时优先参考", + "roles": [ + { "role": "ceo", "reportsTo": null, "note": "公司负责人，制定目标" }, + { "role": "cto", "reportsTo": "ceo", "note": "技术负责人" }, + { "role": "hr", "reportsTo": "ceo", "note": "负责后续增量招聘" }, + { "role": "devloop-pm", "reportsTo": "cto" }, + { "role": "devloop-architect", "reportsTo": "devloop-pm" }, + { "role": "devloop-coder", "reportsTo": "devloop-architect" }, + { "role": "devloop-tester", "reportsTo": "devloop-coder" } + ] +} +``` + +```json +// system/org-graph-templates/content.json +{ + "id": "content", + "label": "内容型公司（持续产出/发布内容）", + "whenToUse": "公司目标是短视频/文章/直播等内容的选题-生产-发布流水线", + "roles": [ + { "role": "ceo", "reportsTo": null }, + { "role": "coo", "reportsTo": "ceo", "note": "内容运营负责人" }, + { "role": "hr", "reportsTo": "ceo" }, + { "role": "trend-scout-cn", "reportsTo": "coo" }, + { "role": "story-architect", "reportsTo": "coo" }, + { "role": "hook-editor", "reportsTo": "story-architect" }, + { "role": "auto-publisher", "reportsTo": "coo" } + ] +} +``` + +```json +// system/org-graph-templates/ops.json +{ + "id": "ops", + "label": "运营型公司（监控/增长/客户运营为主）", + "whenToUse": "公司目标偏向数据监控、增长实验、社群/客户运营，不以持续研发或内容生产为主", + "roles": [ + { "role": "ceo", "reportsTo": null }, + { "role": "coo", "reportsTo": "ceo" }, + { "role": "hr", "reportsTo": "ceo" }, + { "role": "community-manager", "reportsTo": "coo" }, + { "role": "strategy-reflector", "reportsTo": "coo" } + ] +} +``` + +设计要点： + +- **这是起点集合，不是穷举枚举**——目录里有几个 `.json` 就有几种候选，新增一种公司类型只需要加一个新文件，不需要改任何代码（对应用户选定的"固定模板文件 + LLM 选型"方案：org-graph-creator 在 prompt 里被告知"`ls system/org-graph-templates/` 看看有哪些候选，都读一遍，选最贴近或组合出一个新的"，不是在代码里写死一个 `switch(type)`）。 +- `roles[].role` 里写的角色名是**建议**，不是强制——org-graph-creator 必须对照 §3.4 的 `company templates` 结果核实这个角色是否真的存在可用模板；如果没有，`hire()` 会走既有的 `needs_training` 分支（自动触发 agent-creator + innovator 培养，company.js:917-940 已有），org-graph-creator 不需要对此做特殊处理，只需要接受 `hire()` 的返回结果继续往下走。 +- 模板之间允许被"揉合"：比如一家公司同时要做内容生产和一个配套小工具的开发，org-graph-creator 的 prompt 里应该允许它同时参考 `content.json` 和 `dev.json`、合并出一套结构，而不是只能二选一。这是把"选型"这个判断交给 LLM 的直接后果——好处是不需要穷举组合，代价见 §八.1。 +- P2 阶段先提供以上 3 个模板作为示例/起点（dev/content/ops），覆盖当前 `system/templates/*` 里能看到的三类角色画像（devloop-* 系列、trend-scout/story-architect/hook-editor 系列、community-manager/strategy-reflector），不追求一次性穷尽所有可能的公司类型。 + +### 4.9 `system/templates/org-graph-creator/`：org-graph-creator agent 本体 + +新增一个系统模板（和 `hr`/`ceo` 同级），字段沿用现有模板骨架（`agent.md`/`soul.md`/`identity.md`/`tools.md`/`config.json`，`config.json.type` 取一个新值 `meta-bootstrap`，与其余"业务角色"的 `type` 区分开）。`agent.md` 的核心工作流大纲（不是完整文案，实现时按仓库现有模板的写作风格——参照 `system/templates/hr/agent.md` 的"招·留·管·退"体例——展开）： + +1. **读取输入**：公司 `id`/`name`/`description`（由 §4.10 的首轮消息带入）。 +2. **读候选骨架**：`ls system/org-graph-templates/`，逐个读取，理解每个模板的 `whenToUse`。 +3. **读可招角色清单**：`node bin/lemon.js company templates`，拿到当前系统里真实存在的模板列表（id/name/type/description）。 +4. **规划**：综合 1/2/3，判断这家公司最贴近哪个（或哪几个）模板，裁剪/替换/新增角色，产出一份具体的"角色 + reportsTo"清单。**必须包含一个不挂靠任何模板、始终存在的 `hr` 节点**（如果模板里没有就补上）——它是这套结构未来能否被增量维护的前提，org-graph-creator 自己不会长期存在（见第 6 步）。 +5. **落盘规划记录**：把第 4 步的结果写成 `workspace/org-plan.md`（角色列表 + 汇报关系 + 为什么这么选的简短理由），供事后审计/调试——这不是给代码读的结构化数据（结构化数据是 DB 里的 `org_graph_nodes`/`edges`），是给人看的"这次规划是怎么想的"。 +6. **按拓扑序执行招聘**：从没有 `reportsTo` 的根节点开始，逐层往下，每个角色调用 `node bin/lemon.js company hire --id <公司ID> --role <角色> --reportsTo <上级角色（根节点省略）>`。见 §4.11 关于失败重试的约定。 +7. **收尾**：全部招聘执行完（或明确判断某些角色因为需要培养而转入异步流程后），把自己的 `heartbeat.enabled` 设为 `false`（复用现有心跳开关机制，`server/routes/company.js:774` 一带的 `/heartbeat` 端点），不主动退出/不被 fire——它是这家公司组织架构决策的历史记录持有者，保留在 `company.agents[]`/`org_graph_nodes` 里，但不再被心跳唤醒、不参与后续任何招聘（后续增量招聘是 HR 的职责）。 + +**org-graph-creator 自己在组织图里的位置**：不产生 `reportsTo` 出边（不属于它规划出来的业务汇报树），`getOrgGraph()` 会把它渲染成一个独立的"根"（和 CEO 一样是无入边——不，无出边——的顶层节点，§4.7 的前端渲染本来就允许多个顶层节点并存）。它是基础设施角色，类比 `agent-creator`/`innovator` 这些不出现在业务组织架构里、但确实活跃在系统里的 meta 角色。 + +### 4.10 公司创建流程改动 + +`server/routes/company.js:22-38` 的 `POST /create`：`companyService.create()` 成功后，追加： + +```js +// 1. 同步招聘 org-graph-creator（跟其他角色一样走模板复制，很快） +const bootstrapResult = companyService.hire(id, 'org-graph-creator', {}); + +// 2. fire-and-forget 触发它的第一轮对话——复用 /hire 路由里已有的 +// fetch(`/api/agent/{agentId}/chat`, ...) 异步模式（company.js:917-940） +if (bootstrapResult.status === 'hired_from_template') { + fetch(`http://127.0.0.1:${PORT}/api/agent/org-graph-creator/chat`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + message: `公司 ${id}（${name}）已创建。公司描述：${description || '（未填写）'}\n请你按照 org-graph-creator 的工作流规划并执行这家公司的初始组织结构。`, + conversationId: `org-graph-bootstrap-${id}-${Date.now().toString(36)}`, + }), + }).catch(e => console.error('[Create] org-graph-creator 触发失败:', e.message)); +} +``` + +响应文案同步调整：不再是"请通知 MasterBot 从 Template 库中雇佣 Agent"，改成"公司已创建，正在由 org-graph-creator 自动规划组织结构（异步进行中）"。 + +**为什么是路由层而不是 `companyService.create()` 内部**：跟 §3.2/§4.5 同一个理由——`fetch` 调用自己的 HTTP 服务、依赖 `PORT` 等运行时上下文的代码，现有代码库的既有约定是放在路由层（`/hire` 的训练触发逻辑就是这么做的），`CompanyService` 保持不依赖 HTTP 层。 + +**失败降级**：如果 `hire(id, 'org-graph-creator', {})` 本身失败（比如模板目录被误删），`create()` 的返回结果仍然是成功的空壳公司——这一步失败不应该让公司创建本身失败，跟现有的"招聘失败不影响主流程"原则一致。降级后的行为等同于 P2 上线前的现状：一个没有 org graph、需要人工手动招聘的空壳公司。 + +### 4.11 拓扑序执行失败与重试 + +§4.4 的校验规则 1 要求 `reportsTo` 目标必须已经是 active 节点——这对一个由 LLM 驱动、顺序执行十几次 `hire()` 调用的 agent 来说，存在"记错顺序、先招了子节点"的现实风险。设计上不在 `hire()` 侧放宽这条校验（放宽会让"脏数据"更容易产生，参见 v0.1 §4.4 校验规则 1 的论证），而是让失败可恢复： + +- `hire()` 对这种情况返回的错误信息要明确指出"角色 `` 尚不存在于该公司，请先招聘它"（不是一个笼统的 500）——org-graph-creator 的 prompt 里要求它读到这类错误后，转去招那个缺失的上级角色，成功后再重试当前角色。 +- 每个角色的 `hire()` 调用天然幂等（`already_exists` 短路，company-service.js:194-196），所以"招错顺序 → 报错 → 补招上级 → 重试子节点"这个循环不会因为重复调用产生副作用。 +- 不引入一个专门的"依赖排序引擎"帮 org-graph-creator 提前算好正确顺序——§4.9 第 4 步产出的规划记录本身就是一份树状结构，从根遍历下去自然就是拓扑序，只要 org-graph-creator 老老实实按自己写的 `org-plan.md` 从上往下执行，这个问题不常发生；真发生时靠上面的重试机制兜底，不值得为小概率场景builds额外基础设施。 + +### 4.12 存量数据 & 已建公司：明确不做的两件事 + +沿用 v0.1 的结论并扩展一条： + +| 场景 | 决定 | 理由 | +|---|---|---| +| P2 上线前已存在的公司（P0 只回填了节点，没有边） | 不补边，`org_graph_edges` 就是空的，前端退化展示 | 没有可靠数据源支撑（见 §二），按 `type`/`parentId` 反推都已被证伪，见 v0.1 版本 §四.7 的完整方案对比表 | +| P2 上线后，一家已经跑过 org-graph-creator（或已经手动搭好组织架构）的公司，业务发生变化想要"重新规划" | 不支持——org-graph-creator 只在 §4.10 的创建时触发点运行一次 | 对一家已有员工、可能正在跑任务的公司做"推倒重来"式重新规划，涉及已有节点保留/替换、进行中任务归属等问题，复杂度显著高于"对着空壳公司规划一次"，留 Open Question（§八.5），不在 P2 范围内 | + +--- + +## 五、任务划分（Task Breakdown） + +| # | 任务 | 涉及文件 | 依赖 | 验收方式 | +|---|------|----------|------|----------| +| **T1** | schema 追加：`org_graph_nodes.status` 列、两个唯一索引、`org_graph_edges.status`/`created_at` | `server/services/graph-db.js` | 无 | 单测：`PRAGMA table_info` 能看到新列；重复插入同 `(company,role)` 的 active 节点报唯一索引冲突 | +| **T2** | 新建 `org-graph-service.js`：`upsertNode`/`removeNode`/`addEdge`/`getOrgGraph`，含 `reportsTo` 校验规则（§4.4） | `server/services/org-graph-service.js`（新增） | T1 | 单测覆盖幂等写入、非法 `reportsTo`（不存在/自环）报错且报错信息包含缺失的角色名（供 §4.11 重试逻辑解析）、`removeNode` 级联失效边 | +| **T3** | `hire()` 接入：写 node + 可选 edge，try/catch 不阻断主流程 | `server/services/company-service.js` | T2 | 单测：`hire()` 传 `reportsTo` 后 DB 各新增一行；`org-graph-service` 内部抛错时 `hire()` 仍返回 `hired_from_template` | +| **T4** | `/hire` 路由透传 `reportsTo`；`/fire` 路由接入 `removeNode()`；`CompanyService.fire()` 同步改 | `server/routes/company.js`、`server/services/company-service.js` | T2 | 集成测试：`POST /hire` body 带 `reportsTo` → 查 DB 有边；`POST /fire` 后节点与相关边均 `removed` | +| **T5** | 新增只读端点 `GET /:companyId/org-graph` | `server/routes/company.js` | T2 | 路由测试：返回形状符合 §4.6 契约；不存在的公司返回空数组而非 500 | +| **T6** | CLI：`bin/lemon.js company hire` 新增 `--reportsTo` 参数 | `bin/lemon.js` | T4 | 手工跑一次带 `--reportsTo` 的 hire，核对返回值与 DB | +| **T7** | 新增 `system/org-graph-templates/`：至少 `dev.json`/`content.json`/`ops.json` 三个骨架 | `system/org-graph-templates/*.json`（新增） | 无（可与 T1-T6 并行） | 人工 review：每个文件的 `roles[].role` 都能在 `system/templates/*` 或 `system/agents/*` 里找到同名目录（避免规划出一个连培养都无从谈起的角色名） | +| **T8** | 新增 `system/templates/org-graph-creator/`：agent.md/soul.md/identity.md/tools.md/config.json，落地 §4.9 工作流 | `system/templates/org-graph-creator/*`（新增） | T6, T7 | 人工 review + 手动跑一次完整对话，核对生成的 `org-plan.md` 与实际 `hire()` 调用序列一致 | +| **T9** | `/create` 路由接入自动招聘 + fire-and-forget 触发首轮对话 | `server/routes/company.js` | T4, T8 | 集成测试：`POST /create` 后立即查 `company.agents` 含 `org-graph-creator`；等待异步对话完成后查 `org_graph_nodes`/`edges` 有业务角色数据 | +| **T10** | HR agent 模板更新：明确"公司初建时的组织结构由 org-graph-creator 负责，HR 只做后续增量招聘"的职责边界 + `reportsTo` 用法 | `system/templates/hr/agent.md` | T6 | 人工 review，确认新增段落不与现有"强制工作流"章节冲突 | +| **T11** | 前端：Dashboard 团队成员 tab 加分层列表渲染，退化态验证 | `web/src/views/CompanyDashboard.vue` | T5 | 手动验证：有 `reportsTo` 边的测试公司显示缩进层级；存量公司展示效果与改动前一致 | +| **T12** | 回归测试 + 端到端测试：新建 `server/tests/unit/org-graph-service.test.js`；扩展 `server/scripts/test-company-e2e.js` 覆盖"建公司 → org-graph-creator 自动跑完 → 查 org-graph"全链路 | `server/tests/unit/org-graph-service.test.js`（新增）、`server/scripts/test-company-e2e.js` | T3, T4, T9 | `npm run test:unit` 全绿；e2e 脚本能跑通全链路（org-graph-creator 这一步用 mock 模式，参考 DevLoop 的 `ClaudeCliProtocol({mock:true})` 思路，不在自动化测试里真的起 Claude CLI 子进程） | + +**顺序建议**：T1→T2 是地基。T3/T4/T5 可在 T2 后并行。T7（组织结构模板库）不依赖任何代码改动，可以最早开工、和 T1-T6 并行写。T8（org-graph-creator agent 本体）依赖 T6（CLI 参数）和 T7（有模板可读）。T9（接入创建流程）依赖 T8。T10/T11 分别依赖 T6/T5。T12 贯穿全程，全链路部分要等 T9 完成。 + +--- + +## 六、验收标准 + +沿用 27 号文档给出的 P2 验收标准（27-graph-agent-architecture.md:215），细化为可直接验证的检查项： + +1. **端到端场景（核心）**：`POST /api/company/create` 创建一家 `description` 明确写"我们要做一个短视频内容自动化生产的公司"的测试公司，不做任何手动干预： + - 几秒内 `company.agents` 出现 `org-graph-creator` + - org-graph-creator 完成一轮对话后，`GET /:companyId/org-graph` 能看到至少 `ceo`/`hr` 加若干与内容生产相关的角色（不强制要求跟 `content.json` 模板逐字一致，因为允许 LLM 裁剪），且存在至少一条 `reports_to` 边 + - `workspace/org-plan.md`（org-graph-creator 私有目录下）存在且内容与实际 `hire()` 调用结果一致 +2. 对一家新建测试公司依次 `hire(companyId, 'cto', {})` → `hire(companyId, 'hr', {reportsTo: 'cto'})`：`org_graph_nodes` 新增两行，`org_graph_edges` 新增一行 `(hr → cto, reports_to, active)`。 +3. `hire(companyId, roleName, {reportsTo: 'nonexistent-role'})`：报错拒绝，不产生半成品数据，且错误信息包含缺失角色名（供 §4.11 重试逻辑验证）。 +4. `POST /:companyId/hire` 的 HTTP body 带 `reportsTo` 字段：验证请求确实透传到了 `hireWithTraining()`。 +5. `POST /:companyId/fire` 辞退某角色后：该节点与其相关边均 `status='removed'`，`GET /:companyId/org-graph` 不再返回它们。 +6. `GET /:companyId/org-graph` 对一家 P0 迁移进来、从未走过新流程的存量公司：返回 `edges: []`，`nodes` 数量与 `company.json.agents.length` 一致。 +7. Company Dashboard：有 `reportsTo` 数据的测试公司按层级缩进展示；存量公司展示效果与 P2 上线前一致。 +8. `npm run test:unit` 全绿，含新增的 `org-graph-service.test.js`。 + +--- + +## 七、影响面 / Blast Radius + +| 文件 | 改动类型 | +|------|----------| +| `server/services/graph-db.js` | 修改：追加 `status` 列 + 两个唯一索引 | +| `server/services/org-graph-service.js` | 新增：`upsertNode`/`removeNode`/`addEdge`/`getOrgGraph` | +| `server/services/company-service.js` | 修改：`hire()` 接入 org-graph 写入；`fire()` 同步加 `removeNode()` | +| `server/routes/company.js` | 修改：`/create` 接入自动招聘 org-graph-creator + 异步触发对话；`/hire` 透传 `reportsTo`；`/fire` 接入 `removeNode()`；新增 `GET /:companyId/org-graph` | +| `bin/lemon.js` | 修改：`company hire` 命令新增 `--reportsTo` 选项 | +| `system/org-graph-templates/*.json` | 新增：组织结构模板库（至少 dev/content/ops 三份） | +| `system/templates/org-graph-creator/*` | 新增：新的系统模板（agent.md/soul.md/identity.md/tools.md/config.json） | +| `system/templates/hr/agent.md` | 修改：明确与 org-graph-creator 的职责边界 | +| `web/src/views/CompanyDashboard.vue` | 修改：团队成员 tab 加分层渲染逻辑 | + +**明确不改**：`company.json` 的 schema（`agents` 数组继续是唯一真相源）、`AgentManager`/`PromptBuilder`（P2 不碰运行时寻址）、`CompanyService.listAgents()`。 + +--- + +## 八、风险 / Open Questions + +1. **LLM 选型/裁剪质量没有硬性校验**：org-graph-creator 选模板、裁剪角色、判断 `reportsTo` 全靠一次 LLM 推理，没有像 `hire()` 校验规则那样的确定性把关（只保证"图结构合法"，不保证"这套结构适合这家公司"）。缓解：§4.9 第 5 步的 `org-plan.md` 提供了事后可读的决策记录，公司创建者发现规划不合理时，可以走现有 `fire()`/`hire()` 手动调整——**这也是为什么 §一非目标里明确不支持自动重新规划**：与其让 org-graph-creator 自己判断"要不要推倒重来"，不如交给人看着 `org-plan.md` 做增量修正。 +2. **一次公司创建多一轮 LLM 对话的成本与延迟**：以前建公司是纯本地文件操作（毫秒级），现在多了一次真实的 Claude CLI 子进程对话（几十秒到几分钟，还有 token 成本）。`POST /create` 保持同步返回（不等 org-graph-creator 跑完，走 fire-and-forget，见 §4.10），前端体验上公司创建本身不受影响，但"什么时候能看到组织结构"变成异步——Dashboard 需要一个"组织结构规划中"的过渡态提示（T11 范围内可以顺手加，不需要单独立项）。 +3. **模板揉合没有边界**：§4.8 允许 org-graph-creator 同时参考多个模板文件自由组合，理论上可能拼出一个奇怪的结构（比如把三个模板的角色全招一遍）。P2 阶段不加约束（不限制招聘角色数量上限），如果上线后观察到滥招问题，可以在 org-graph-creator 的 prompt 里加"单次规划角色数不超过 N 个"这类软性约束，不需要代码层面的强制校验。 +4. **6 个命名冲突 id 对 org-graph-creator 选型的影响**：P1 §九 Q4 指出的 `agent-creator`/`digester`/`evolver`/`evolver-youtube-crawler`/`hunter`/`innovator` 命名空间冲突问题，现在从"HR 偶尔招到"变成"org-graph-creator 系统性地对照 `company templates` 列表做选型，遇到这批 id 的概率显著提高"。不阻塞 P2 技术交付（`hire()` 本身对这批 id 的处理逻辑不受影响），但建议在 P2 上线前，至少把这 6 个 id 从 `system/org-graph-templates/*.json` 的候选角色名单里排除（在模板文件里就不引用它们），避免规划阶段就把歧义引进来。 +5. **已有公司的组织结构再规划**：§4.12 明确列为非目标，但这是一个真实存在的后续需求（公司业务转型、组织结构随规模变化）。留待后续阶段设计——可能的方向是"org-graph-creator 支持增量模式：读现有 org graph + 新目标，只补差集"，但这需要先观察 P2 上线后 HR 的增量招聘（§4.4 机制）能不能覆盖大部分场景，不值得在还没有真实使用数据时就设计。 +6. **`hire()` 里 `company.ceo` 判定逻辑本身有既有 bug**（§二已指出：`ceo` 模板没有 `config.json`，`type==='cxo'` 判定命中的其实是最后一个被雇的 cxo 类型角色）——org-graph-creator 大概率会招一个字面意义的 `ceo` 角色，这个 bug 会被更频繁地触发（`company.ceo` 显示的可能是 `cto`/`coo` 而不是真正的 `ceo`）。这是 P2 之外的既有缺陷，本文档记录下来供后续排期，不在 P2 任务列表里顺带修（避免这次改动的 diff 范围扩大到不相关的既有逻辑）。 + +--- + +## 九、与 P1 的关系（现状澄清） + +P1（`27-p1-virtual-reference.md`）**目前仍处于设计阶段，代码未落地**（`server/services/graph-service.js` 不存在，`company-service.js` 里也没有任何 `systemAgentRef`/`companyContextPath` 相关代码）。27 号文档 §六的强顺序声明（27-graph-agent-architecture.md:221）只显式要求 P3 依赖 P1，没有把 P2 排进这条链： + +- P2 直接基于 P0 的 `graph-db.js`/`org_graph_nodes` 表施工，不需要 P1 的虚拟引用寻址先行。 +- P2 新建的 `org-graph-service.js` 与 P1 设计稿里的 `graph-service.js` 是两个独立文件、不同职责。 +- 唯一需要协调的是**共享的 `org_graph_nodes` 表 schema**：本文档 §4.2 给这张表加了 `status` 列。如果 P1 之后落地，P1 §4.4 里 `upsertOrgGraphNode()` 的实现需要感知这个新列（默认 `status='active'` 即可）。 +- org-graph-creator 本身招聘自己所需要的所有角色时，走的是**当前**（P1 未落地时）的 `hire()` 实现——也就是说 org-graph-creator 招出来的每个角色，`agent.md` 仍然是物理拷贝，不是 P1 设想的虚拟引用。这一点不影响 P2 的正确性，只是意味着 P1 一旦落地，"批量自动招聘"这个新增的调用模式会让"同一个模板被拷贝 N 份"的问题（P1 §二要解决的问题）被更快地放大——这是支持"P1 应该尽早提上日程"的一个新论据，但不是 P2 必须等 P1 的理由。 + +如果团队希望先补上 P1 再做 P2，也完全可以调换顺序——本文档在设计上不依赖那个决定。 diff --git a/docs/user-guides/08-base-agent-4-phase-guide.md b/docs/user-guides/08-base-agent-4-phase-guide.md deleted file mode 100644 index febfe28..0000000 --- a/docs/user-guides/08-base-agent-4-phase-guide.md +++ /dev/null @@ -1,63 +0,0 @@ -# LemonBoss Base Agent 四阶段 (4-Phase) 使用指南 - -## 1. 概念与定位 -在经历了 Harness Engineering 的重构后，**Base Agent（基座数字员工）**不再是一个简单的“全能聊天机器人”，而是被设计成一台严密的、流水线式的自动执行机器。 -它的核心特征是 **“分阶段切片运行” (Phase-Slicing Execution)**。它在任何时刻都只拥有一种明确的脑部模式（Meta-Skill），以最高效的方式避免“长上下文衰减（Context Decay）”引起的注意力涣散和“工具滥用”引发的安全风险。 - -当接受一项任务（尤其是长链路的开发、撰写或爬虫任务）时，Base Agent 会不可逆地单向穿越以下四个阶段： - -| 阶段名 | 行动挂载的技能 (Meta-Skill) | 工具权限 | 当前使命 | 产出成果物 (Artifact) | -| :--- | :--- | :--- | :--- | :--- | -| **Research (调研)** | `meta-research` | 终端只读权限 | 不做假设，充分使用读写工具摸排所有上下文信息并提炼精华。 | `workspace/_research.md` | -| **Plan (规划)** | `meta-plan` | 轻度文本输出 | 根据前置调研，严密推演并产出外科手术式的 1/2/3 行动清单。 | `workspace/_plan.md` | -| **Execute (执行)** | `meta-execute` | **万能扳手(bash)** | 心无旁骛，完全依照规划改文件、跑脚本，**禁止擅改架构**。 | 改动后的代码或输出文件 | -| **Verify (验证)** | `meta-verify` | 测试与运行权限 | 自测，调用脚本或运行环境；若失败则撰写防坑日志，若成功则汇报。| `workspace/_lessons.md` / `PASS` | - ---- - -## 2. 状态扭转与 Context Flush（记忆断舍离） -每当一个阶段完成，Agent 绝不能在当前的记忆流中直接开始下一个阶段。它会被迫调用以下 CLI 命令： -```bash -node bin/lemon.js task transition --agentId <你的ID> --phase <下一阶段> --artifact <该阶段的文本路径> -``` -**系统此时会进行物理干预：** -1. **换脑 (Hot Swap)**：系统会剥夺其上一阶段的技能组，将比如 `meta-plan` 塞入它的核心大纲。 -2. **失忆 (Context Flush)**：系统**强制杀死它当前的后台进程，清空它长达几百轮的记忆和所有报错产生的噪音文本**。 -3. **轻装上阵 (Clean Start)**：系统给重新启动的 Agent 唯一一条初始化信息：“你已经进入了新阶段，这是你上个阶段的精华产出物 Artifact，请基于它继续工作。” - -这种做法确保了越到后面的高危阶段，Agent 的决策视界就越清晰。 - ---- - -## 3. Human-in-the-loop: P0 级任务的拦截阀 -如果你向数字员工派发的任务被标记为了 **P0 (Critical)**： -```bash -node bin/lemon.js task dispatch --from ceo --to worker_01 --task "全面重构支付网关逻辑" --priority P0 -``` -当 Base Agent 顺利完成 `Research` 并且写好 `_plan.md`，正打算启动 `transition` 跨入 `Execute` 阶段召唤“Bash 重器”强改代码前——**系统会紧急挂起该操作！** -* 它的状态会被标记为 `pending_approval`（待审批休眠）。 -* 你（作为 Master/人类老板）或者你的 CEO 会收到一条私信，请求审阅该 `_plan.md`。 -* 此举以仅仅审阅一页文字的低昂成本，换来了百倍高的止损防火墙。 - ---- - -## 4. 防撞墙：微自反思闭环 (Autoresearch Error Loop) -如果 Agent 在 Execute 或 Verify 阶段遇到了顽固的 Bug（比如包冲突、语法错误），系统并不鼓励立刻抛出求救。 -它是带有**自修正微闭环**的： -1. 遇到报错后，它会将这个致命踩大坑的经过与解决方案总结进 `workspace/_lessons.md`。 -2. 当它被要求 Retry 重试时，系统会把它自己写的这段防坑经验，像免死金牌一样挂载在系统提示词的第一行：`## ⚠️ 本地试错防坑经验 (_lessons.md)`。 -3. 从此这只瞎撞墙的苍蝇，拥有了不碰同一堵墙两次的能力。 - ---- - -## 5. 经济算力（Economic Profiling）报表 -每次发生阶段切换 (Transition) 或一次回复打结，系统会默默在后台日志 `data/logs/billing.log` 计算本次任务切片的真实美元花费（USD Cost）和耗时评估。 - -**通过这种核算拆解，管理者可以知道：** -“为了执行一个爬虫任务，员工小李在 Research 的资料搜索里烧了 $0.5，而 Execute 写代码只烧了 $0.02。”进而可以基于这些财务数字去优化上游给它的 Task 精准度。 - ---- - -## 6. 使用建议 (Best Practices) -1. **对于复杂长链条指令**：不要试图跟从前的聊天大模型一样对它下达含糊的“全干指令”。让它按这四阶走，明确告知你的质量要求。 -2. **信任 `_lessons.md`**：如果你作为人类看它钻了死胡同，你可以直接人肉打开它的工作区，手工往 `_lessons.md` 里加一句话：“绝对不要再用 Python 2 的语法去跑脚本！用 python3！”剩下的，放心交给它去修正即可。 -- libgit2 0.21.4