matrix-for-agents 0.1.2__py3-none-any.whl

agentmatrix/db/vector_db.py

@@ -0,0 +1,213 @@
+
+import asyncio
+import chromadb
+from chromadb.config import Settings
+from concurrent.futures import ThreadPoolExecutor
+from typing import List, Dict, Optional
+from contextlib import asynccontextmanager
+from ..core.log_util import AutoLoggerMixin
+from chromadb.utils import embedding_functions
+import os
+
+# ==========================================
+# 1. 手写一个 Async ReadWriteLock (写优先)
+# ==========================================
+class AsyncReadWriteLock:
+    def __init__(self):
+        self._readers = 0
+        self._writers = 0           # 当前活跃的写者（0或1）
+        self._waiting_writers = 0   # 正在排队的写者（用于防止写饥饿）
+        self._condition = asyncio.Condition()
+
+    @asynccontextmanager
+    async def read_lock(self):
+        """读锁上下文管理器：允许多个Reader，除非有Writer在写或在等"""
+        async with self._condition:
+            # 如果有活跃写者 OR 有写者在排队，读者必须等（写优先策略）
+            while self._writers > 0 or self._waiting_writers > 0:
+                await self._condition.wait()
+            self._readers += 1
+        
+        try:
+            yield
+        finally:
+            async with self._condition:
+                self._readers -= 1
+                # 如果没有读者了，唤醒所有等待者（包括写者）
+                if self._readers == 0:
+                    self._condition.notify_all()
+
+    @asynccontextmanager
+    async def write_lock(self):
+        """写锁上下文管理器：独占，需要等待所有Reader和Writer退出"""
+        async with self._condition:
+            self._waiting_writers += 1
+            # 等待直到没有活跃写者 且 没有活跃读者
+            while self._writers > 0 or self._readers > 0:
+                await self._condition.wait()
+            self._waiting_writers -= 1
+            self._writers = 1
+        
+        try:
+            yield
+        finally:
+            async with self._condition:
+                self._writers = 0
+                self._condition.notify_all()
+
+# ==========================================
+# 2. 改进后的 VectorDB
+# ==========================================
+class VectorDB(AutoLoggerMixin):
+    _instance = None
+    _init_lock = asyncio.Lock() # 仅用于单例创建的简单锁
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self, persist_directory, collection_names):
+        """
+        collection_names: 必须在初始化时传入所有需要管理的集合名称列表
+        """
+        if hasattr(self, '_initialized') and self._initialized:
+            return
+
+        self.persist_directory = persist_directory
+
+        
+        # 初始化 Chroma Client
+        try:
+            # 设置 SQLite WAL 模式有助于并发，但 Python 层仍需控制
+            settings = Settings(anonymized_telemetry=False, allow_reset=False, )
+            self.client = chromadb.PersistentClient(path=persist_directory, settings=settings)
+            
+            # --- 关键策略：读写分离线程池 ---
+            # 1. 读线程池：并发数设为 CPU 核心数 x 2 或固定值，用于 Query
+            self.read_executor = ThreadPoolExecutor(max_workers=8, thread_name_prefix="ChromaReader")
+            # 2. 写线程池：必须是 1，用于 Add/Update/Delete
+            self.write_executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="ChromaWriter")
+            
+            # --- 关键组件：读写锁 ---
+            self.rw_lock = AsyncReadWriteLock()
+            self.echo(">>> Loading Embedding Function...")
+            os.environ["HF_HUB_OFFLINE"] = "1"  # 完全离线模式
+            os.environ["TRANSFORMERS_OFFLINE"] = "1"  # transformers 库离线模式
+            self.embedding_function = embedding_functions.SentenceTransformerEmbeddingFunction(model_name="BAAI/bge-large-zh-v1.5")
+            self.echo(">>> Embedding Function Loaded.")
+            # --- 预加载 Collections ---
+            self.collections = {}
+            if collection_names:
+                for name in collection_names:
+                    # 同步获取，初始化时不需要异步，保证启动即就绪
+                    self.collections[name] = self.client.get_or_create_collection(name=name, embedding_function=self.embedding_function)
+                    self.logger.info(f"Collection '{name}' loaded.")
+            
+            self._initialized = True
+            self.logger.info("VectorDB initialized with ReadWrite separation.")
+            
+        except Exception as e:
+            self.logger.exception(f"Initialization failed: {e}")
+            raise
+
+    def get_collection(self, collection_name: str):
+        """获取已加载的 Collection"""
+        return self.collections.get(collection_name, None)
+
+    # 辅助：获取 EventLoop
+    def _get_loop(self):
+        try:
+            return asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.get_event_loop()
+
+    # ==========================
+    # 写操作 (串行，独占)
+    # ==========================
+    async def add_documents(self, collection_name: str, documents: List[str], metadatas=None, ids=None):
+        if collection_name not in self.collections:
+            self.logger.error(f"Collection {collection_name} not found in pre-loaded list.")
+            return
+
+        # 1. 获取应用层写锁 (会等待所有正在进行的读操作结束)
+        async with self.rw_lock.write_lock():
+            loop = self._get_loop()
+            collection = self.collections[collection_name]
+            
+            def _sync_add():
+                # 这里运行在单线程池中
+                collection.add(documents=documents, metadatas=metadatas, ids=ids)
+
+            # 2. 扔到 写线程池 执行
+            await loop.run_in_executor(self.write_executor, _sync_add)
+            self.logger.info(f"Write complete: {len(documents)} docs to {collection_name}")
+
+    # ==========================
+    # 读操作 (并行，共享)
+    # ==========================
+    async def query(self, collection_name: str, query_texts: List[str],where, n_results=10):
+        if collection_name not in self.collections:
+            raise ValueError(f"Collection {collection_name} does not exist")
+
+        # 1. 获取应用层读锁 (允许多个 Query 同时进入，但如果有 Writer 排队则等待)
+        async with self.rw_lock.read_lock():
+            loop = self._get_loop()
+            collection = self.collections[collection_name]
+            
+            def _sync_query():
+                # 这里运行在多线程池中，真正的并行读取
+                return collection.query(query_texts=query_texts,where=where, n_results=n_results)
+
+            # 2. 扔到 读线程池 执行
+            results = await loop.run_in_executor(self.read_executor, _sync_query)
+            return results
+
+    async def close(self):
+        self.logger.info("Shutting down executors...")
+        self.read_executor.shutdown(wait=False)
+        self.write_executor.shutdown(wait=True) # 写操作最好等待完成
+        self.logger.info("Shutdown complete.")
+
+    
+
+# ==========================
+# 验证代码
+# ==========================
+async def main():
+    # 初始化：明确指定需要的集合
+    db = VectorDB(collection_names=["knowledge_base", "user_logs"])
+
+    # 1. 写入数据 (独占)
+    print("--- Start Writing ---")
+    await db.add_documents(
+        "knowledge_base", 
+        documents=["Python is cool", "Asyncio is tricky"], 
+        ids=["id1", "id2"]
+    )
+
+    # 2. 并发读取测试
+    print("--- Start Concurrent Reading ---")
+    async def simulate_query(idx):
+        print(f"Query {idx} starting...")
+        # 这里的 query 会并行执行
+        res = await db.query("knowledge_base", ["Python"], n_results=1)
+        print(f"Query {idx} finished. Result ID: {res['ids'][0]}")
+
+    # 模拟 5 个并发查询
+    tasks = [simulate_query(i) for i in range(5)]
+    
+    # 模拟在查询中间插入一个写入，验证写锁是否能阻断读
+    async def delayed_write():
+        await asyncio.sleep(0.01) # 让读先跑一点
+        print("!!! Urgent Write Trying to acquire lock !!!")
+        await db.add_documents("knowledge_base", ["Interrupted"], ids=["id3"])
+        print("!!! Urgent Write Finished !!!")
+
+    tasks.append(delayed_write())
+    
+    await asyncio.gather(*tasks)
+    await db.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentmatrix/docs/Design.md

@@ -0,0 +1,109 @@
+# AgentMatrix 架构设计文档 (v2.0)
+
+### 1. 核心设计哲学 (Design Philosophy)
+
+*   **拟人化与社会化 (Anthropomorphic & Social)**:
+    *   Agent 是独立的“数字员工”，而非简单的函数接口。
+    *   Agent 之间通过自然语言（邮件）进行社交协作，而非 API 调用。
+    *   系统容忍模糊性，Agent 像人类一样通过沟通来消除歧义。
+
+*   **双脑架构与谈判机制 (Dual-Brain & Negotiation)**:
+    *   **大脑 (Brain/LLM)**: 负责高层认知、推理、人设扮演（Persona）和模糊意图生成。
+    *   **小脑 (Cerebellum/SLM)**: 负责接口适配、参数检查和结构化翻译。
+    *   **谈判 (Negotiation)**: 当大脑意图不清时，小脑不会强行执行，而是发起“内部质询（Internal Query）”，与大脑进行多轮对话以补全信息。
+
+*   **框架嵌入 (Frame Embedding)**:
+    *   **驾驶舱隐喻 (Pilot in the Cockpit)**: 将 Agent 分为“意识（Pilot）”与“躯体（System）”。
+    *   Prompt 不再是指令集，而是“物理法则”。Agent 在一个回合制的世界中，通过操作仪表盘（Output Format）来驱动躯体。
+
+*   **显式意志驱动 (Volition-Driven Flow)**:
+    *   **Action is Sync**: 对大脑而言，所有动作（发邮件、读文件）都是瞬间完成的反馈。
+    *   **Wait is Explicit**: 系统不再自动挂起。挂起（Wait）是一个主动的认知决策。Agent 必须显式决定“我现在没事做了，我要等待外部信号”。
+
+---
+
+### 2. 关键概念定义 (Key Concepts)
+
+#### A. 基础设施 (The World)
+*   **The Matrix**: 运行时容器，提供时间、空间（文件系统沙箱）和通讯设施。
+*   **PostOffice**: 异步消息总线。负责邮件投递、服务发现（Yellow Page）。
+*   **Signals**: 系统内唯一的信息载体。无论是新邮件、文件内容、执行报错还是小脑的提问，统统被封装为统一的 **Signal** 格式投喂给大脑。
+
+#### B. 智能体结构 (Agent Anatomy)
+1.  **Pilot (The Mind)**:
+    *   **System Prompt**: 定义人设（我是谁）。
+    *   **Protocol Constraint**: 定义物理法则（我要怎么动）。
+    *   **Capability Menu**: 只有名字和描述的能力菜单（大脑只看菜单，不看配方）。
+2.  **Cerebellum (The Interface)**:
+    *   持有完整的 **Tools Manifest**（JSON Schema）。
+    *   作为“看门人”，拦截无效意图，发起参数协商。
+3.  **Body (The Execution Unit)**:
+    *   无状态的执行器。负责将小脑输出的 JSON 映射为具体的 Python 函数调用。
+
+#### C. 信号系统 (The Signal System)
+Agent 与世界的交互被抽象为纯粹的 **I/O 流**：
+*   **Input**: `[INCOMING MAIL]`, `[BODY FEEDBACK]`, `[INTERNAL QUERY]`
+*   **Output**: `THOUGHT` (思维链) + `ACTION SIGNAL` (具体指令)
+
+---
+
+### 3. 运行机制 (Runtime Flow)
+
+#### A. The "Turn-Based" Loop (主循环)
+Agent 的生命周期由一系列离散的 **回合 (Turn)** 组成：
+
+1.  **Awake (Signal Received)**:
+    *   Agent 处于冻结状态，直到收到一个 Signal。
+2.  **Reasoning (Thought)**:
+    *   大脑阅读历史上下文和最新信号。
+    *   生成 **THOUGHT**: 进行隐式的思维链推导（例如：分析局势、制定计划、检查遗漏）。
+3.  **Decision (Action Signal)**:
+    *   大脑输出 **ACTION SIGNAL**: 明确下一步要做的一个动作。
+    *   *Rule*: "Pass the Baton" —— 输出动作后，大脑立即停止生成，交出控制权。
+4.  **Negotiation (The Filter)**:
+    *   小脑拦截 Signal。
+    *   **Check**: 参数齐了吗？意图在能力范围内吗？
+    *   **If No**: 小脑生成 `[INTERNAL QUERY]`，回滚到第 1 步（Agent 收到质询信号，被唤醒进行解释）。
+    *   **If Yes**: 生成结构化 JSON。
+5.  **Execution (The Body)**:
+    *   执行具体的 Python 函数。
+6.  **Feedback Loop**:
+    *   **Action Result**: 动作产生结果（如“邮件已发送”或“文件内容”），封装为 `[BODY FEEDBACK]`，**立即** 触发下一回合（回到第 1 步）。
+    *   **Explicit Wait**: 如果动作是 `rest_n_wait`，则系统**挂起** Session，直到有外部新邮件进入。
+
+#### B. 状态机流转
+*   **Active**: 正在处理 Signal，或刚刚执行完动作收到反馈。
+*   **Negotiating**: 正在与小脑进行内部参数对齐。
+*   **Waiting**: 执行了 `rest_n_wait`，处于休眠状态，等待 PostOffice 的唤醒。
+
+---
+
+### 4. 交互契约 (The Protocol)
+
+#### A. 思维链与动作分离
+为了提升智能并保证稳定性，输出被严格分为两块：
+*   **THOUGHT**: 允许 Agent 自言自语。这是“暗知识”，用于推理和决策，小脑不看这一部分。
+*   **ACTION SIGNAL**: 必须是纯净的指令。这是“工单”，小脑只执行这一部分。
+
+#### B. 显式等待 (Explicit Wait)
+*   **Fire-and-Forget**: 发送邮件 (`send_email`) 不会自动结束任务。Agent 会收到“发送成功”的反馈，然后它必须决定是继续工作（如写代码）还是休息。
+*   **Yield**: 只有调用 `rest_n_wait`，Agent 才会交出 CPU 时间片。这使得“连续多步操作”成为可能（如：发信 -> 查文件 -> 再发信 -> 休息）。
+
+#### C. 原子化工具 (Atomic Capabilities)
+*   工具不再包含复杂的业务逻辑（如“回复上一个人”）。
+*   工具回归原子化（如“发给某人”）。
+*   **路由逻辑**（发给谁？）完全由大脑基于上下文在 `THOUGHT` 阶段决定，小脑只负责填空。
+
+---
+
+### 5. 总结
+
+AgentMatrix v2.0 的核心在于**“解放大脑，约束接口”**。
+
+*   我们不再用复杂的代码逻辑去猜测 Agent 发完邮件后想干什么。
+*   我们将“决定权”完全交还给 Agent 的**自由意志**（通过 THOUGHT 和 Explicit Wait）。
+*   同时，利用 **Negotiation** 机制作为安全网，确保这种自由意志不会转化为错误的系统调用。
+
+这是一个**以认知为中心 (Cognition-Centric)** 而非以流程为中心 (Process-Centric) 的系统架构。
+
+

agentmatrix/docs/Framework Capbilities.md

@@ -0,0 +1,105 @@
+# **机制（Mechanism）与策略（Policy）的分离**。
+
+*   **机制（Framework/Library）**：提供“怎么做”的能力（例如：发信、查人、存状态）。
+*   **策略（Application）**：决定“做什么”（例如：先让Planner做计划，再让Coder写代码）。
+
+虽然业务逻辑千变万化，但为了让 Agent 组织能“转”起来，框架层必须提供比“发邮件”更高一层的**基本原子能力**。
+
+应该沉淀在 **Framework** 层的 5 个核心基础能力（除了 Communication 之外）：
+
+---
+
+### 1. **Service Discovery & Capability Manifest (服务发现与能力清单)**
+
+在现实公司里，你入职第一天，HR 会给你一张表：“这是 IT 部门的小王，修电脑找他；这是财务的小李，报销找他。”
+
+**框架层应实现：**
+*   **动态通讯录 (Directory)**: 不仅仅是 `Name -> Agent实例` 的映射。
+*   **能力描述协议 (Manifest)**: 每个 Agent 注册时，必须通过框架提供的标准格式声明自己的能力。
+    *   例如：`{ "role": "Coder", "skills": ["python", "pandas"], "description": "处理数据清洗" }`
+*   **语义查询接口**: 允许 Agent 向框架（邮局）提问：“谁最擅长画图？”（框架负责做简单的语义匹配返回名字）。
+
+**应用层决定：**
+*   到底有哪些 Agent，他们的人设和具体技能是什么。
+
+---
+
+### 2. **Structured Task Lifecycle (结构化任务生命周期)**
+
+现在的“邮件”只是纯文本。但在正规组织里，任务是有“元数据”的。
+
+**框架层应实现：**
+*   **标准化的工单状态 (Ticket Status)**: 所有的任务交互，除了 Body 之外，框架强制附加一个 `status` 字段：`OPEN` -> `IN_PROGRESS` -> `BLOCKED` -> `RESOLVED` -> `CLOSED`。
+*   **父子任务追踪 (Traceability)**: 框架自动维护 `parent_task_id`。如果 Planner 发起的任务 ID 是 `T-100`，Coder 为了完成它发出的求助信 ID 应该是 `T-100-1`。框架要提供 API 方便地查询 `T-100` 衍生出的所有子任务是否都 `RESOLVED` 了。
+
+**应用层决定：**
+*   什么情况下把状态改为 Blocked，什么算是 Resolved。
+
+---
+
+### 3. **Escalation Mechanism (异常升级/求助机制)**
+
+如果 Coder 卡住了，或者 LLM 崩溃了，或者 Secretary 报错了，Agent 该怎么办？不能只是 Log 一下就死掉了。
+
+**框架层应实现：**
+*   **默认的 `escalate()` 接口**: 每个 Agent 基类都有这个方法。
+*   **Chain of Command (指挥链)**: 框架允许在注册 Agent 时配置 `supervisor`（上级）。
+*   **兜底逻辑**: 当 Agent 调用 `self.escalate("不知道怎么做")` 时，框架自动把这封信转发给它的 `supervisor`（通常是 Planner 或 Human Admin），并附带报错堆栈。
+
+**应用层决定：**
+*   谁是谁的上级？Planner 收到下属的报错后，是重试、换人还是问用户？
+
+---
+
+### 4. **Shared Blackboard / Workspace (公共白板)**
+
+你提到的“Basic Memory”（大家都知道谁是谁，项目进行到哪了）。邮件是一对一的，有时候需要一个“全员可见”的地方。
+
+**框架层应实现：**
+*   **Blackboard 对象**: 一个线程安全的、支持订阅变更的 KV 存储。
+*   **广播机制 (Broadcasting)**: 允许 Planner 发送 `@all` 的通告（例如：“项目需求变更了，大家注意”）。这不同于点对点邮件，它会塞入所有人的 Context 或作为一个高优先级 System Message。
+*   **只读/读写权限控制**: 普通 Agent 可能对白板只有读权限，只有 Planner 有写权限。
+
+**应用层决定：**
+*   白板上写什么？是“项目进度表”，还是“当前分析结论”，还是“全局变量”。
+
+---
+
+### 5. **Standard Output Protocol (标准化输出协议)**
+
+虽然输入输出是自然语言，但为了让流程可控，Agent 的输出**动作**必须被框架标准化，而不是让 LLM 随意发挥。
+
+**框架层应实现：**
+*   **Action Primitive (原子动作定义)**: 框架定义好几种基本的“意图类型”：
+    *   `SEND_MAIL` (发信)
+    *   `CALL_TOOL` (调工具)
+    *   `THINK` (仅记录想法，不发信)
+    *   `FINISH` (当前工单完结)
+    *   `ASK_USER` (请求人类介入)
+*   **Output Parser (强制解析器)**: 框架提供针对不同 LLM 的解析层，强制把 LLM 的输出映射到上述原子动作上。如果解析失败，框架自动驳回给 LLM 重试，不让 Application 层操心格式错误。
+
+---
+
+### 总结：框架 vs 应用
+
+| 功能点 | **框架 (AgentMailOS) 负责** | **应用 (Your Business App) 负责** |
+| :--- | :--- | :--- |
+| **通信** | 邮件传输、路由、死信处理 | 谁给谁发、发什么内容 |
+| **组织** | 维护通讯录、提供群发/公告能力 | 定义组织架构（扁平还是层级） |
+| **记忆** | 提供白板存储、提供数据库归档 | 决定白板上存什么、怎么利用历史 |
+| **流程** | 维护 `Open/Closed` 状态机、父子任务关联 | 决定先分析还是先写代码 (SOP) |
+| **容错** | 提供 `escalate()` 接口、自动重试机制 | 决定遇到困难时是问人还是忽略 |
+| **动作** | 定义标准动作 (Send, Tool, Finish) | Prompt Engineering (人设) |
+
+### “Planner 模式”在这个框架里怎么跑？
+
+在这种设计下，你的 Planner 模式会非常顺畅：
+
+1.  **App 初始化**：在框架的 `Blackboard` 上写上：“项目目标：分析 A 股票”。
+2.  **Planner (App层逻辑)**：读取白板，决定第一步是“收集数据”。
+3.  **框架层**：Planner 发出一封 `OPEN` 状态的邮件给 Researcher。框架记录 `Parent: Project_1, Child: Task_1_1`。
+4.  **Researcher**：干活。
+5.  **框架层**：Researcher 调用 `FINISH` 动作。框架把 `Task_1_1` 标记为 `RESOLVED`，并自动通知 Planner。
+6.  **Planner**：收到通知，读取 Researcher 的成果（更新到白板），然后决定下一步。
+
+这样，**“流程把控”**（Planner 的核心职责）变成了应用层的逻辑，而**“状态跟踪、通知回调、错误兜底”**变成了框架层的免费能力。这就是最理想的封装。

agentmatrix/docs/Planner Design.md

@@ -0,0 +1,148 @@
+# 对于最顶端的Planner，它需要维护的对话可能非常长，应该如何设计？
+
+这是Agent 系统的**核心瓶颈**：**Context Window Management（上下文窗口管理）** 与 **Information Abstraction（信息抽象）** 的矛盾。
+
+1.  **底层员工（Coder/Secretary）**：任务明确、生命周期短。处理完一个具体函数或查询，Context 就可以丢弃。
+2.  **顶层管理者（Planner）**：生命周期极长（贯穿整个项目），信息密度极大。
+
+如果简单地把所有下属的汇报邮件（包含大量代码、报错日志、数据片段）都堆进 Planner 的 Context 里，无论多大的 Context Window 都会很快爆掉，而且噪音太大，LLM 会变笨。
+
+为了解决这个问题，我们需要引入一种**通用机制**，我称之为 **“动态文档（Living Artifact）”模式**，或者叫 **“状态驱动（State-Driven）”模式**，而不是传统的“对话驱动（History-Driven）”。
+
+---
+
+### 1. 核心理念：Planner 不是 Chatbot，是“状态维护者”
+
+对于 Planner，我们不能让它依赖线性的 `List<Message>` 来记忆。我们必须**强制**它维护一份 **“项目状态文档（Project State Document）”**。
+
+*   **传统模式 (Chat)**:
+    *   Input: `[User: 做A, Planner: 让Coder做A, Coder: 报错xxx, Planner: 试一下y, Coder: 好了, output is Z]`
+    *   *问题：Coder 的报错细节和调试过程，对 Planner 的长期记忆是垃圾信息。*
+
+*   **动态文档模式 (State-Driven)**:
+    *   Planner 不记忆“对话流”，只记忆一个 **JSON/Markdown 对象**（我们称之为 **The Plan**）。
+    *   每次收到新邮件，Planner 的工作不是“回复”，而是 **“更新文档”**，然后基于文档决定下一步。
+
+---
+
+### 2. 机制设计：双循环结构 (The Update-Act Loop)
+
+为了在框架层面支持这种能力，我们需要给 Planner 这种特殊的 Agent 设计一种**双步骤**的思考流。
+
+当 Planner 收到一封邮件（比如 Coder 的汇报）时：
+
+#### 第一步：Reflect & Update (消化与更新)
+*   **输入**：当前的项目文档（The Plan） + 新收到的邮件（The Email）。
+*   **System Prompt**：“你是一个项目经理。这是当前的项目计划状态。这是刚收到的下属汇报。请根据汇报内容，**更新**项目计划（标记完成、添加新步骤、记录关键结果）。不要回复邮件，只输出更新后的计划。”
+*   **输出**：新的项目文档（The New Plan）。
+*   **动作**：框架用“New Plan”替换掉内存里的“Old Plan”。
+
+#### 第二步：Act & Dispatch (决策与分发)
+*   **输入**：更新后的项目文档（The New Plan）。
+*   **System Prompt**：“这是当前最新的项目计划。请检查还有哪些未完成的任务。决定下一步该给谁发邮件，发什么指令。”
+*   **输出**：一封或多封发给下属的邮件。
+*   **动作**：投递邮件。
+
+#### 第三步：Garbage Collection (关键！丢弃上下文)
+*   **动作**：**直接丢弃** 刚才那封 Coder 发来的原始邮件和第一步的思考过程。
+*   **保留**：只保留 **最新的 Project Plan** 作为下一轮的 Context。
+
+---
+
+### 3. 这个机制解决了什么问题？
+
+1.  **无限的生命周期**：
+    *   因为 Planner 每次只需要看“最新的 Plan”，而不需要看“过去 100 轮的邮件”。Plan 的大小通常是可控的（几 KB），而邮件历史是无限增长的。
+    *   Planner 永远处于 **Context 几乎为空** 的清爽状态，只关注当下状态。
+
+2.  **自动的信息压缩（Compression）**：
+    *   Coder 发来：“我试了库 A 报错，试了库 B 报错，最后用库 C 成功了，结果是 X。”
+    *   Planner 在“第一步”更新文档时，只会把 Plan 更新为：`Task 1: Completed. Result: X. (Note: Library C used)`。
+    *   中间的报错过程被自动过滤掉了。这就是**抽象**。
+
+---
+
+### 4. 框架内如何实现？(Framework Implementation)
+
+这不应该是 Application 层的瞎写，而应该是 Framework 提供的标准能力。
+
+我们给 `BaseAgent` 扩展一个子类 `StatefulAgent`（专门给 Planner 用）。
+
+```python
+# agents/stateful.py 
+
+class StatefulAgent(BaseAgent):
+    def __init__(self, name, backend):
+        super().__init__(name, backend)
+        # 这就是那个“动态文档”，可以是 JSON，也可以是 Markdown
+        self.project_state = {
+            "objective": "",
+            "tasks": [],
+            "key_findings": []
+        }
+
+    async def step(self, session: TaskSession):
+        # 获取最新的一封信（导致这次激活的那封）
+        incoming_mail = session.history[-1]['content']
+        
+        # === Phase 1: State Update (只更新记忆，不发信) ===
+        update_prompt = f"""
+        当前状态: {json.dumps(self.project_state)}
+        收到消息: {incoming_mail}
+        
+        任务:
+        1. 根据消息更新任务状态 (TODO -> DONE)。
+        2. 将关键结果摘要写入 key_findings。
+        3. 如果有新问题，添加到 tasks。
+        
+        输出: 仅输出更新后的 JSON 状态。
+        """
+        new_state_json = await self.brain.think(self.name, [{"role": "user", "content": update_prompt}])
+        
+        # 更新内存
+        try:
+            self.project_state = json.loads(new_state_json)
+            # 存入数据库快照，方便回溯
+            self.save_state_snapshot() 
+        except:
+            print("State update failed")
+
+        # === Phase 2: Action Decision (只看状态，不看历史邮件) ===
+        action_prompt = f"""
+        当前项目状态: {json.dumps(self.project_state)}
+        
+        任务:
+        基于当前状态，判断下一步该做什么？
+        - 如果所有任务完成，回复用户。
+        - 如果有 OPEN 的任务，给相应的 Worker 发邮件。
+        
+        输出: [Action: EMAIL] ...
+        """
+        response = await self.brain.think(self.name, [{"role": "user", "content": action_prompt}])
+        
+        # ... 解析 response 并发信 (同 WorkerAgent) ...
+        
+        # === Phase 3: Context Clearing ===
+        # 极其激进的策略：清空 Session History，只保留最新的状态
+        # 因为所有必要信息都已经“沉淀”到 project_state 里了
+        session.history = [] 
+```
+
+### 5. 对比总结：Planner vs Secretary
+
+这下角色的差异就非常明显了：
+
+| 特性 | **Secretary (工具人)** | **Worker (Coder/Analyst)** | **Planner (管理者)** |
+| :--- | :--- | :--- | :--- |
+| **核心机制** | Function Calling | ReAct / Standard Chat | **State Update Loop** |
+| **记忆类型** | 无记忆 (Stateless) | 短期会话 (Session History) | **长期结构化状态 (Artifact)** |
+| **Context策略**| 用完即弃 | 任务结束即弃 | **不断重写与覆盖** |
+| **主要能力** | 翻译 (NL $\to$ Code) | 执行 (NL $\to$ Output) | **归纳与调度 (Info $\to$ State)** |
+
+
+
+*   **Planner** 必须继承自 `StatefulAgent`。
+*   它的 System Prompt 不再是“你是一个助手”，而是定义 **State Schema（状态的结构）**。
+    *   例如：“你的内存由 `Plan List` 和 `Data Summary` 组成。你永远不要相信你的聊天记录，只相信你的内存。”
+
+这种设计让 Planner 即使运行了一个月，处理了 1000 封邮件，它每次发令时发给 LLM 的 Token 数可能依然只有 2k (Current State)，而不是 200k (Full History)。这才是能够长期稳定运行的关键。