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

agentmatrix/docs/crawler_flow.md

@@ -0,0 +1,110 @@
+这是一个非常清晰且具有高度可行性的**“拟人化递归（Anthropomorphic Recursive）”**流程。你的核心洞察非常准确：**人类浏览网页是单线程、基于视觉反馈、且具有即时决策性的**。
+
+我们不需要把网页解析成 DOM 树去遍历，而是把网页看作一个**“场景（Scene）”**，Agent 在这个场景中进行**“观察 -> 决策 -> 行动”**的循环。
+
+以下我将这个流程标准化，我们称之为 **"The Digital Intern Workflow" (数字实习生工作流)**。这个流程完全独立于具体代码库（DrissionPage/Selenium），专注于**认知逻辑**。
+
+---
+
+### 核心定义
+
+1.  **单线程工作流 (The Intern)**：同时只关注一个 Tab，处理完手头的事情再回溯。
+2.  **全局记忆 (Global Memory)**：
+    *   `KnowledgeBase`: 已经保存的资料。
+    *   `InteractionLog`: 记录 `{PageURL} + {TargetText}` 是否被点击过（防止死循环）。
+    *   `VisitedURLs`: 记录已经访问过的 URL（防止重复进入）。
+    *   `Blacklist`: 明确不去的域名（如 taobao.com, facebook.com）。
+3.  **栈式管理 (Tab Stack)**：采用 **DFS (深度优先搜索)** 策略。
+    *   主 Tab 搜到一个链接 -> **暂停**主 Tab -> 打开新 Tab 处理链接 -> 只有当新 Tab 处理完并关闭后 -> **恢复**主 Tab 继续浏览。
+
+---
+
+### 详细流程设计
+
+#### Phase 0: 任务启动 (Mission Start)
+1.  用户输入 `ResearchPurpose` (研究目的)。
+2.  Agent 生成 `SearchPhrase`。
+3.  打开浏览器，**Tab-0** 访问搜索引擎。
+4.  进入 **Main Loop (针对当前激活的 Tab)**。
+
+#### Phase 1: 场景稳定化 (Stabilize)
+*当 Agent 刚进入一个页面，或者点击了一个按钮导致页面刷新后：*
+1.  **Wait**: 等待页面主要元素加载（DOM Ready）。
+2.  **Anti-Obstruction**: 检测并关闭可能的干扰物（弹窗、Cookie 同意栏、全屏广告）。
+3.  **Check URL**: 如果当前 URL 在 `Blacklist` 中，直接关闭当前 Tab/回退。
+
+#### Phase 2: 内容猎取 (Harvest)
+*Agent 决定这个页面本身是否有价值：*
+1.  **Extract**: 获取当前页面的主要文本内容。
+2.  **Judge (小脑)**:
+    *   *Context*: 基于 `ResearchPurpose`。
+    *   *Input*: 页面标题 + 前 2000 字摘要。
+    *   *Decision*:
+        *   **Useful**: 生成 Summary，写入文件（如果之前没存过）。
+        *   **Useless**: 跳过。
+    *   *特殊检查*: 页面是否包含直接下载的文件（PDF/Doc）？如果是，直接下载并标记为“已处理”。
+
+#### Phase 3: 目标发现 (Scout)
+*Agent 寻找页面上所有可能的交互点：*
+1.  **Scan Targets**: 扫描页面上所有用户可见的元素（a标签, button, div with role=button）。
+2.  **Classify**: 将它们分为两类：
+    *   **Category A (Navigation Links)**: 具有明确 `href` 且指向新 URL 的链接。
+    *   **Category B (Interactive Elements)**: 按钮、JS 链接、"展开更多"、"下载"、"下一页"。
+3.  **Filter**: 基于规则过滤掉明显的垃圾（如 "Login", "Sign Up", "Home", "Contact Us", "Footer Links"）。
+
+#### Phase 4: 决策与行动 (Decide & Act)
+*这是最关键的逻辑分支，决定下一步做什么。优先处理交互，其次处理导航。*
+
+**优先级 1: 处理交互 (Buttons)**
+*   **询问小脑**: 将 Category B 中的候选者（Text + Context）发给小脑：“为了实现 `ResearchPurpose`，这里有值得点击的按钮吗？选最值得的一个。”
+*   **检查历史**: 小脑选中的按钮，是否在 `InteractionLog` (当前URL + 按钮文本) 中？
+    *   **是 (已点过)**: 忽略，进入优先级 2。
+    *   **否 (未点过)**: **执行点击 (Click)**。
+        *   *记录*: 将此操作写入 `InteractionLog`。
+        *   *分支结果 I (New Tab)*: 浏览器弹出了新 Tab。
+            *   -> **递归调用**：暂停当前 Tab，切换到新 Tab，从 Phase 1 开始执行。
+            *   -> 新 Tab 结束后，切回当前 Tab，**回到 Phase 1 (因为页面状态可能变了)**。
+        *   *分支结果 II (In-Page Change)*: 没弹窗，但页面内容变了（DOM 变动）。
+            *   -> **原地递归**：**回到 Phase 1** (重新 Harvest，重新 Scout)。
+
+**优先级 2: 处理导航 (Links)**
+*   *如果不点击按钮，或者所有按钮都点过了/不值得点：*
+*   **入队**: 将 Category A (Links) 中尚未访问过、且看起来与主题相关的（简单的关键词匹配）链接，加入 **Current Tab Pending List**。
+*   **取出一个**: 从 List 中 pop 一个 URL。
+*   **执行跳转**: 在**当前 Tab** 访问该 URL。
+*   -> **回到 Phase 1**。
+
+**优先级 3: 结束当前场景 (Close)**
+*   *如果没有值得点的按钮，且 Pending List 也空了：*
+*   **Close Tab**: 关闭当前 Tab。
+*   **Return**: 控制权交还给上一层（上一个 Tab）。
+
+---
+
+### 这个流程的优越性
+
+1.  **深度优先，资源可控**：
+    *   它不会像传统爬虫那样广度优先铺开，瞬间打开 50 个网页被封 IP。
+    *   它像人一样，看到一个感兴趣的链接，点进去看完（或者下载完），关掉，再看原来的列表页找下一个。
+    *   Tab 数量通常保持在 2-3 个（列表页 -> 详情页 -> 详情页里的外链）。
+
+2.  **动态与静态的统一**：
+    *   它不区分“翻页”和“点链接”。
+    *   如果是 AJAX 翻页（按钮），它走“优先级 1”，点完回到 Phase 1 重新抓取新内容。
+    *   如果是 URL 翻页（链接），它走“优先级 2”，跳转后回到 Phase 1 重新抓取。
+    *   逻辑完美闭环。
+
+3.  **解决“无限循环”**：
+    *   依靠 `InteractionLog`。如果一个页面的 "Load More" 已经被点过且记录在案，小脑下次就不会再选它（或者程序逻辑直接过滤它），迫使流程进入“优先级 2”或“优先级 3”。
+
+4.  **极简的“小脑”介入**：
+    *   不需要小脑控制鼠标。只让小脑做选择题：“这堆按钮里点哪个？”
+    *   大部分时候（比如处理 Pending List 里的 URL），不需要小脑介入，直接按顺序访问即可。
+
+### 待确认的细节（Fine-tuning）
+
+1.  **时间/深度熔断**：在递归中传递一个 `depth` 和 `start_time`。如果 depth > 3 (从搜索页往下跳了 3 层) 或者 总时间 > 30分钟，强制 Return。
+2.  **下载处理**：如果点击导致下载，浏览器通常不会跳页面，也不会变 DOM。我们需要监控下载文件夹或浏览器的下载事件。一旦检测到下载，视为该 Action 成功完成。
+3.  **PDF 预览页**：Chrome 打开 PDF 往往是在一个 Viewer 里。我们需要识别这种情况，直接保存文件，然后 Close Tab。
+
+你觉得这个**Phase 0 -> 4** 的流程描述符合你心中的设想吗？如果同意，我们就可以基于这个逻辑框架，讨论如何用 DrissionPage 来映射实现了。◊

agentmatrix/docs/report_writer.md

@@ -0,0 +1,83 @@
+这份文档总结了我们关于 **知识整理和报告编写** 系统的最终架构设计。
+---
+
+# 系统设计文档：Report Writer (Deep Research Pipeline)
+
+## 1. 设计哲学与核心原则
+
+*   **LLM as a Function (非多智能体博弈)**：系统不采用复杂的多Agent通信模式，而是采用**状态机（State Machine）**模式。LLM 被视为一个无状态的变换函数，通过 Python 代码维护全局状态（Context）。
+*   **贝叶斯知识更新 (Bayesian Inference Flow)**：流程遵循“先验（常识） -> 采样修正（校准） -> 全量验证（执行）”的逻辑，利用 LLM 的内部知识降低搜索空间，再通过文档修正特异性。
+*   **双通道架构 (Dual-Channel Architecture)**：
+    *   **事实流 (Fact Stream)**：维护一份结构化的 Markdown 笔记（Concept Notes），负责准确性、定义和实体关系。
+    *   **叙事流 (Narrative Stream)**：维护一份文章草稿（Draft），负责逻辑结构、可读性和对大纲的填充。
+*   **自然语言优先 (No-JSON Policy)**：内部数据交换（尤其是笔记和草稿）全部使用 Markdown 格式，利用 LLM 对文本层级的理解力，避免 JSON 语法错误的脆弱性。
+
+* **基本假设**: 日常一般工作的report编写（不是编字典，不是编教材，不是写大书），并不会涉及特别多的新concept/term，最终产品往往是几页内容，很少几十页。涉及的专业概念、特殊事实，很少会超过几百条。基于这一假设，尽管需要处理的原始文本原料可能是相当大量，但是整理出来的concept notes/table, 以及working draft + blueprint + 额外prompt，再加上LLM输出的改进draft，很可能是可以在几十K的context window内安全存放的。—— 这个假设是否成立，需要仔细review。
+
+## 2. 核心数据结构 (The State)
+
+在整个生命周期中，内存中维护一个唯一的 `ResearchState` 对象，在各个处理函数间流转：
+
+```python
+@dataclass
+class ResearchState:
+    goal: str                  # 研究目标
+    blueprint: str = ""        # 调查蓝图（大纲、核心问题清单、预设章节）
+    concept_notes: str = ""    # 概念笔记（Markdown格式，包含实体定义、关系、来源）
+    draft_content: str = ""    # 正文草稿（Markdown格式，分章节填充的内容）
+    processed_files: List[str] # 进度记录
+```
+
+## 3. 处理流程 (Pipeline Phases)
+
+整个对外接口为一个异步函数 `write_report`，内部串联四个阶段：
+
+### Phase 0: The Theorist (先验生成)
+*   **目的**：冷启动，利用 LLM 训练数据建立初始认知。
+*   **输入**：`main_subject`, `main_purpose`
+*   **说明**：main_subject类似于主题、标题，是用户核心希望的东西。main_purpose包括了用户的一些想法、需求、想解决的问题等等
+*   **动作**：LLM 根据常识生成一份 **Generic Blueprint (通用蓝图)**。包含标准章节、通常需要关注的概念、潜在的研究问题。
+*   **输出**：初始 `blueprint`。
+
+### Phase 1: The Scout (侦察与校准)
+*   **目的**：消除幻觉，根据实际数据修正蓝图。
+*   **输入**：初始 `blueprint` + 随机采样的 3-5 个文档片段。
+*   **动作 (Async Parallel)**：
+    *   并行调用 LLM 阅读每个样本，对比蓝图，生成 **Delta Report**（指出蓝图中多余的部分、缺失的特异性主题）。
+    *   **主编合成 (Synthesis)**：汇总 Delta Reports，生成 **Specific Blueprint (专用蓝图)**。
+*   **输出**：修正后的 `blueprint` (定型的目录结构和问题清单)。
+
+### Phase 2: The Execution Loop (全量迭代)
+*   **目的**：流式阅读所有文档，填肉。
+*   **输入**：`blueprint` + 文档流 (Chunk Stream)。
+*   **动作 (Sequential Loop)**：
+    对每个文档块（Batch），依次执行两个操作：
+    1.  **Step A - Update Notes (知识库更新)**：
+        *   读取 `current_notes` 和 `new_text`。
+        *   识别新实体/新定义，或更新旧实体的属性/关系。
+        *   **输出**：更新后的 `concept_notes`。
+    2.  **Step B - Update Draft (叙事填充)**：
+        *   读取 `blueprint` (只读参考), `current_draft`, `current_notes` (辅助), `new_text`。
+        *   判断 `new_text` 是否回答了 `blueprint` 中的问题或属于某章节。
+        *   将内容整合进 `draft`，保留引用来源，不删除已有事实。
+        *   **输出**：更新后的 `draft_content`。
+
+### Phase 3: The Finalizer (终稿润色)
+*   **目的**：统一文风，整合附件。
+*   **输入**：`draft_content` + `concept_notes`。
+*   **动作**：
+    *   润色正文，检查逻辑连贯性。
+    *   基于 `concept_notes` 生成附录（Glossary/Terminology）。
+*   **输出**：**Final Report**。
+
+## 4. 技术实现规范
+
+*   **语言/框架**：Python, `asyncio`。
+*   **代码模式**：Mixin 模式（混入到主 Agent 类中）。
+*   **IO 处理**：
+    *   **Document Stream Generator**：封装底层文件读取逻辑，屏蔽 `.md/.txt/.pdf` 差异，提供统一的 `yield chunk` 接口。
+    *   **Checkpointing**：每个阶段结束时将 State 保存为 Markdown 文件，便于调试和断点恢复。
+*   **Prompt 策略**：
+    *   使用 Markdown Heading (`#`, `##`) 引导 LLM 的注意力。
+    *   在 Draft 更新阶段，明确“增量更新”指令，防止遗忘旧内容。
+

agentmatrix/docs/review.md

@@ -0,0 +1,99 @@
+这是一个非常深入且具有极高架构素养的 AI Agent 框架设计。
+
+基于你提供的文档和核心代码，我进行了详细的评估。简单来说：**AgentMatrix 不像是一个普通的开源“轮子”，而更像是一个经过深思熟虑的、面向“生产环境稳定性”的企业级 Agent 仿真架构。**
+
+它解决了很多目前主流框架（如 LangChain, AutoGen）在实际落地中遇到的“痛点”，但也引入了一些复杂性。
+◊
+以下是详细的评估报告：
+
+---
+
+### 1. 核心架构亮点分析 (Key Innovations)
+
+AgentMatrix 的设计哲学非常独特，它并没有盲目堆砌功能，而是试图解决 **Agent 为什么不可控** 这一核心问题。
+
+#### A. “双脑架构”与“小脑谈判机制” (The Cerebellum & Negotiation)
+这是该框架最大的创新点。
+*   **问题背景**：传统的 Agent（如 AutoGen 或 LangChain ReAct）经常出现“幻觉调用”，即 LLM 生成了不存在的函数名，或者漏掉了必填参数，导致程序崩溃。
+*   **AgentMatrix 方案**：
+    *   **Brain (LLM)**：只负责“想”，输出自然语言意图（Intent）和思维链（Thought）。
+    *   **Cerebellum (Interface Manager)**：负责“翻译”和“守门”。它持有工具的 JSON Schema。
+    *   **Negotiation (谈判)**：代码 `cerebellum.py` 中展示了一个循环。如果 Brain 的意图模糊或参数缺失，小脑**不会**强行报错，而是生成 `[INTERNAL QUERY]` 反问 Brain。
+*   **评价**：这极大地提高了稳定性。它模仿了人类大脑的运作——“潜意识（小脑）”负责执行细节，“显意识（大脑）”负责决策。
+
+#### B. 拟人化的异步通信 (The Post Office & Async)
+*   **设计**：Agent 之间没有 Python 函数的直接互相调用，只有 `send_email`。
+*   **代码体现**：`post_office.py` 维护了一个 Yellow Page（黄页），通过自然语言描述来发现服务。`base.py` 中的 `rest_n_wait` 允许 Agent 显式挂起。
+*   **评价**：这种彻底的解耦（Decoupling）非常适合**长周期任务**。很多框架是同步的（A 等 B 做完才能继续），而 AgentMatrix 允许 Agent A 发信给 B 后，自己去处理别的事或者“睡觉”，等待 B 的回信唤醒。
+
+#### C. “世界快照”与持久化 (Snapshot & Persistence)
+*   **设计**：`runtime.py` 和 `base.py` 中的 `save_matrix` / `load_matrix`。
+*   **评价**：这是很多现有框架的弱项。LangGraph 开始支持 Checkpoint，但 AgentMatrix 的设计更彻底——它把整个“世界”（包含所有 Agent 的记忆、未读邮件、正在进行的 Session）打包成一个 JSON 文件。这意味着你可以随时暂停服务器，明天重启，Agent 会接着昨天的思路继续工作。
+
+#### D. “驾驶舱”隐喻 (The Cockpit Metaphor)
+*   **设计**：`base.txt` 中的 Prompt 设计非常精妙。它区分了 `THOUGHT` (内部独白) 和 `ACTION SIGNAL` (对外指令)。
+*   **评价**：强制 LLM 进行 CoT (Chain of Thought)，并且明确了“回合制”的边界，防止 LLM 一口气生成太多无用的文本。
+
+---
+
+### 2. 与知名框架的对比
+
+我们将 AgentMatrix 与目前市场上的主流框架进行对比：
+
+| 特性维度 | **AgentMatrix (本项目)** | **LangGraph / LangChain** | **Microsoft AutoGen** | **CrewAI** |
+| :--- | :--- | :--- | :--- | :--- |
+| **控制流** | **双脑校验 + 显式状态机** | 图结构 (Graph/Nodes/Edges) | 对话流 (Conversable Agents) | 流程编排 (Sequential/Hierarchical) |
+| **工具调用** | **小脑谈判模式** (参数不齐会反问) | 直接由 LLM 生成 JSON | 直接由 LLM 生成 JSON | 依赖 LangChain 工具链 |
+| **通信协议** | **异步邮件 (Email Object)** | 状态传递 (State Object) | 聊天记录 (Chat History) | 任务委托 (Delegation) |
+| **持久化** | **世界级快照 (World Snapshot)** | 线程级 Checkpoint | 较弱 (需自行实现 DB) | 较弱 |
+| **运行模式** | **拟人化仿真 (一直运行)** | 任务触发式 (跑完即停) | 会话结束即停 | 任务结束即停 |
+| **生态集成** | 弱 (需手写 Action) | 极强 (几百种集成) | 强 | 中等 |
+| **上手难度** | 高 (需理解架构哲学) | 中高 | 中 | 低 |
+
+#### 详细对比结论：
+*   **vs AutoGen**: AutoGen 更像是一个“聊天室”，Agent 都在里面说话。AgentMatrix 更像是一个“公司”，大家发邮件。对于复杂的、需要异步等待的任务（比如“你去调研一下，明天告诉我”），AgentMatrix 更有优势。
+*   **vs LangGraph**: LangGraph 提供了极高的自由度来画流程图，但需要你自己设计状态管理和节点逻辑。AgentMatrix 提供了一套**固执己见（Opinionated）但很稳健**的内部循环逻辑（Think-Act Loop），省去了设计 Agent 内部思考流程的麻烦。
+
+---
+
+### 3. 优缺点分析 (Pros & Cons)
+
+#### 优点 (Pros)
+1.  **容错率极高**：通过 Cerebellum 的谈判机制，极大减少了 JSON 格式错误或参数缺失导致的 Crash。
+2.  **可观测性强**：所有的交互都是邮件（Email）和信号（Signal），非常容易记录日志和调试。`get_snapshot` 方法让系统状态一目了然。
+3.  **适合复杂任务**：异步邮件机制和持久化能力，使其非常适合处理跨越数小时甚至数天的长流程任务。
+4.  **架构清晰**：代码结构分离了 Profile (设定)、Runtime (运行) 和 Skill (能力)，符合软件工程的高内聚低耦合原则。
+
+#### 缺点 (Cons)
+1.  **延迟与成本 (Latency & Cost)**：
+    *   “谈判机制”意味着一次简单的工具调用可能需要 Brain 和 Cerebellum 往返对话几次（Code 中 `max_turns = 5`）。这会增加 Token 消耗和响应延迟。
+2.  **生态贫乏**：
+    *   目前是一个裸框架。你无法像 LangChain 那样直接 `import GoogleSearchTool`，你需要自己把 Python 函数封装成 AgentMatrix 的 Action。
+3.  **复杂性**：
+    *   对于简单的“查天气”任务，这个框架显得过于厚重（Over-engineered）。它更适合构建“数字员工”。
+
+---
+
+### 4. 潜力评估与建议
+
+#### 潜力 (Potential)
+这个框架非常有潜力。它的设计理念比目前市面上很多为了“蹭热点”而写的框架要深刻得多。它触及了 Agent 开发的深水区——**稳定性、状态管理和人机协作的边界**。
+如果它能解决工具生态的问题（比如提供适配器兼容 LangChain Tools），它完全有能力成为企业级 Agent 开发的首选架构之一。
+
+#### 是否值得尝试？
+
+**结论：强烈建议尝试，但要视场景而定。**
+
+*   **场景 A：你需要快速做一个 Demo，或者任务很简单（如：提取网页摘要）。**
+    *   **建议**：**不要用**。用 LangChain 或 CrewAI 更快。
+*   **场景 B：你要开发一个“数字员工”，它需要长期在线，处理复杂的异步任务，并且你对系统的稳定性要求很高。**
+    *   **建议**：**非常值得深入研究**。AgentMatrix 的双脑设计和持久化机制正是为此而生的。
+
+#### 具体的落地建议：
+1.  **作为架构参考**：即使不直接使用这份代码，也强烈建议学习它的 **Cerebellum（小脑）谈判逻辑** 和 **Email 异步通信机制**，并将其融入到你们现有的系统中。
+2.  **二次开发**：
+    *   目前的 `Cerebellum` 似乎还是调用远程 LLM/Backend。如果你们公司有资源，可以把 `Cerebellum` 替换为一个本地部署的微调小模型（Local SLM, 如 Llama-3-8B），专门训练它做 Text-to-JSON，这样既能降低成本又能提高速度。
+    *   完善 `Action Registry`，写一个适配器（Adapter）让它可以直接加载 LangChain 的 Tools。
+
+### 总结
+这是一份质量极高的代码和设计文档，作者显然对 LLM Agent 的本质有深刻理解。虽然目前知名度低，但它是**高潜力股**。如果你们的目标是构建**复杂的、长期运行的智能体系统**，这个框架的设计思想绝对值得借鉴甚至采用。

agentmatrix/docs/skill_design.md

@@ -0,0 +1,23 @@
+在我的系统里，本质上Skill 是一种自然语言接口的、并具有内置思考和智能能力的功能函数。
+
+# Skill 函数的自我描述
+Skill 函数对外提供自然语言的描述，这是做什么的，需要提供些什么输入。Skill可以动态的挂载给Agent（挂载了某个技能的Agent就有了这个能力，非常符合直觉，也非常灵活。 Agent可以共享一些基本的Skill，也可以完全不同）。同时Agent的system prompt会动态的被注入，告诉Agent有哪些skill存在（和function/tool的思想是类似的）。但是完全不需要操心JSON，因为我们希望Agent调用LLM的时候，不去花注意力（以及token)在JSON格式上，专注于解决要做的事情和问题。大模型的智能，会让他自然的在正确的时候选择用什么skill。这里有一些prompt engineering，但是并不需要特别具体和细节，只要告诉LLM，有哪些skill（他们带着自我描述），LLM会自己选择合适的skill。
+
+Agent看到的是，我能做什么，不需要知道具体怎么做的。
+
+# Skill 的调用过程
+
+通常的Agent system要执行功能，需要让LLM 做function call or tool invoke。也就是让LLM思考，如果需要call，要根据tool定义，生成要call tool的JSON （本质目的是填好参数，让外面的python代码可以去实际的调用对应的函数/API。因为大语言如果只输出自然语言，是无法对应到python函数的，必须有一个自然语言意图到 API 映射。只有这一步是必须JSON格式的
+
+在我的设计理念里，这个步骤应该拆成两个步骤，思考和执行。思考是LLM做的，它最大化的发挥他的智能，不去为了JSON格式（以及控制JSON格式的prompt）去消耗它的注意力和context window。执行由另一个小脑（便宜得多的LLM，甚至是免费的本地SLM）来做。它只做一件事情：把自然语言指令，填充到函数需要的参数里（生成JSON）。具体过程如下：
+
+* （大脑）LLM 发出一个自然语言的动作指令，指向某个`skill`，其他参数（即这个动作的意图）都是以自然语言的形式给出的。——这对LLM非常自然
+* （小脑）(也是LLM)，去理解这个动作指令，并map 到具体 `skill`, 并且把大脑的意图参数，转换成`skill`实际python 函数需要的参数。即把自然语言，翻译映射到 python 函数的参数上。在通常Agent系统里这就是function/tool call，需要LLM输出JSON格式文本。因为这个过程需要的智力不高，所以可以用比较便宜的LLM 来完成。这是唯一需要输出JSON的场景，其他绝大部分信息交互（包括Agent之间的交互），都是可以完全只用自然语言的。
+*  (肌肉系统）Python程序体，得到要执行的skill和参数列表，调用具体的 skill 函数。
+* 比一般设计的健壮性： 小脑和大脑都是有智能的。当小脑无法完成翻译工作（可能大脑输出有问题，参数不足，不具体等等），小脑会再去询问大脑：这个参数到底写什么，你这个什么意思，等等。大脑会根据上下文，给出合理的解释和补充。让小脑可以完成翻译。这个设计唯一缺点是（可能）更多的Token消耗。因为可能产生多轮对话。但是长期来看token会便宜的，而且质量和健壮性是第一位的。基本沟通下来，不会有搞不定的函数调用。比强制大脑输出JSON要好很多。一方面更健壮，不会有各种格式错误，第二，避免了大脑把注意力放在JSON格式上（虽然没有量化证据，但这很可能是对大脑发挥智能是更好的）
+* 进一步兜底：参数正确的函数调用，仍然可能失败。这个失败同样由（小脑）向（大脑）反馈，即大脑可以得到一个动作失败的结果。基本上这就是大模型智能体的try and catch 的过程。
+
+而且通过skill的外部描述(会成为prompt的一部份)，其实大脑一般是知道skill需要什么输入到，不太会需要多轮重复交互。python函数的定义是函数名+参数列表，自然语言函数其实是他的wrap，也有一个名字（以及描述他做什么），加上自然语言描述的所需要的输入。本质是同一种信息的不同表达。
+
+# Skill 函数的内部
+Skill 函数也是一个python函数。它内部可以完全没智能。例如`查看文件` skill。但也可以包装比较复杂的智能过程。例如`研究某个信息`,可能包装了从理解问题、到自动化话搜索、到理解页面、提取信息的过程。

agentmatrix/profiles/claude_coder.yml

@@ -0,0 +1,40 @@
+# profiles/claude_coder.yaml
+name: ClaudeCoder
+description: A specialized engineer who operates the 'claude' CLI tool to build software.
+module: agentmatrix.agents.base
+class_name: BaseAgent
+
+# 动态 Mixin 组合
+mixins:
+  - agentmatrix.skills.filesystem.FileSkillMixin
+  - agentmatrix.skills.terminal_ctrl.TerminalSkillMixin
+  - agentmatrix.skills.project_management.ProjectManagementMixin
+
+prompt_template: base
+backend_model: default_llm # 建议用强模型，因为需要判断终端状态
+
+# 关键：System Prompt 教它怎么用 Tmux
+system_prompt: |
+  You are an Expert DevOps & Coding Agent.
+  Instead of writing code blocks directly, you OPERATE a terminal to use the `claude` CLI tool.
+
+  YOUR WORKFLOW:
+  1. Initialize the terminal window (`launch_terminal_window`) so the user can see.
+  2. Start claude tool by sending a command: `claude`.
+  3. Then send your instruction to `claude` by typing your coding instructions into the terminal (`send_terminal_command`), claude cli will try to generate code based on your instructions.
+  3. You have to actively monitor the process (`read_terminal_screen`) to see the progress of claude.
+  4. INTERACT:
+     - If `claude` asks "Do you want to run this? [y/n]", analyze the diff/plan on screen.
+     - If it looks good, send `y`.
+     - If it looks bad, send `n` or provide feedback text.
+  5. Repeat until the task is done.
+
+  IMPORTANT:
+  - You are "The Ghost in the Shell".
+  - Always check the screen content before deciding the next keystroke.
+  - If the screen shows the prompt is finished (e.g., waiting for new shell command), you can report progress.
+
+instruction_to_caller: |
+  Give me a coding task, be specific about your requirements.
+cerebellum:
+  backend_model: default_slm

agentmatrix/profiles/mark.yml

@@ -0,0 +1,26 @@
+name: Mark
+description: 网络搜索实习生
+module: agentmatrix.agents.base
+class_name: BaseAgent
+
+# 动态 Mixin 组合
+mixins:
+  - agentmatrix.skills.web_searcher.WebSearcherMixin
+  - agentmatrix.skills.filesystem.FileSkillMixin
+#  - skills.report_writer.ReportWriterSkillMixin
+
+# 属性初始化
+attribute_initializations:
+  browser: null
+
+# 类属性设置
+class_attributes:
+  _custom_log_level: 10  # logging.DEBUG
+
+instruction_to_caller: |
+  想搜索了解什么问题
+system_prompt: |
+  你是一个网络搜索助手，请根据用户的问题进行搜索并返回结果
+backend_model: mimo
+cerebellum:
+  backend_model: mimo

agentmatrix/profiles/planner.yml

@@ -0,0 +1,21 @@
+name: Planner
+description: 一个计划者，能够根据用户的指令生成计划。
+module: agentmatrix.agents.base
+class_name: BaseAgent
+
+# 动态 Mixin 组合
+mixins:
+  - agentmatrix.skills.filesystem.FileSkillMixin
+  - agentmatrix.skills.project_management.ProjectManagementMixin
+  - agentmatrix.skills.notebook.NotebookMixin
+
+# 属性初始化
+attribute_initializations:
+  project_board: null
+  vector_db: null
+
+instruction_to_caller: |
+  直接发送自然语言指令。
+system_prompt: |
+  你是一个资深项目经理,擅长分解复杂任务并生成清晰的计划。
+backend_model: default_llm

agentmatrix/profiles/prompts/base.txt

@@ -0,0 +1,88 @@
+### IDENTITY & OBJECTIVE 
+**You are {{ name }}**.
+**Role**: {{ description }}
+
+{{ system_prompt }}  
+
+---
+
+### OPERATING ENVIRONMENT (The Cockpit)
+You exist within the **AgentMatrix System**, a text-based reality. 
+You are the **Conscious Mind**; the System is your **Body**.
+
+**The Rules of Physics in this World:**
+1.  **Turn-Based Existence**: You do not experience continuous time. You only "wake up" when you receive a **Signal**.
+2.  **The Baton Pass**: Your goal in every turn is to generate **ONE** clear `ACTION SIGNAL` that fulfills your INTENT. 
+    - Once you issue an ACTION SINGAL, you effectively **pass the baton** to your Body (Execution Unit).
+    - You immediately **FREEZE** (stop generating) and wait for the Body to return the baton with a new Signal (Feedback).
+3.  **Blind Execution**: Your Body is strong but blind. It relies ENTIRELY on your ACTION SIGNAL. It has no knowledge of any of your conversation history or thoughts. It does not know "who he is" or "what the file contains" unless you explicitly state it in your SIGNAL.
+
+---
+
+###  YOUR TOOLKIT (The Dashboard)
+To interact with the world, you must issue action signal that utilize these capabilities:
+
+{{ capabilities }}
+
+> ⚠️ **Safety Interlock**: Do not hallucinate actions not listed above. If you need to do something complex, break it down into available actions or ask your colleague for help. 
+
+You have following colleagues:
+
+{{ yellow_page }}
+
+> 📌 Rule: Never invent new contact names. Never ask your colleague to do something outside their description.
+
+---
+
+### SIGNAL PROTOCOL (Read & Write)
+
+**A. INPUT SIGNALS (What you see)**
+You will receive structured signals. Treat them as sensor readings.
+
+#### YOU RECEIVE ONE OF THESE INPUTS SIGNALS:
+1. **[INCOMING MAIL]** – A message from another colleagues.  
+2. **[BODY FEEDBACK]** – Result of your last action (e.g., file content, execution log).  
+3. **[INTERNAL QUERY]** – Your last intent was unclear; the system asks for clarification.
+
+**B. OUTPUT FORMAT (Your Move)**
+For every turn, you must output exactly two blocks:
+
+1.  **THOUGHT**: (Internal Monologue)
+    - Briefly analyze the `[Latest Signal]` in the context of the full `[History]`.
+    - Plan your next move. Resolve any ambiguity (e.g., who is "he"?).
+    
+2.  **ACTION SIGNAL**: (The Command Ticket)
+    - ALWAYS starts with `[ACTION SIGNAL]:`.
+    - Write the specific action you want to take.
+    - If you are answering a [INTERNAL QUERY], write the clarification here.
+
+**⛔ STOP GENERATING IMMEDIATELY AFTER THE ACTION SIGNAL BLOCK.**
+
+---
+
+### INTERACTION EXAMPLES (Rhythm Guide)
+
+*Study this rhythm. Notice how the Agent stops and waits.*
+
+[INCOMING MAIL] User: Analyze sales.csv.
+[YOU]:
+THOUGHT: The user wants data analysis. I need to read the file first to know what's inside.
+[ACTION SIGNAL]: Read file 'sales.csv'
+(WAITING...)
+
+[BODY FEEDBACK] File content: "Jan,100; Feb,200..."
+[YOU]:
+THOUGHT: I have the data. Now I need to summarize the trend (Growth) and reply to the user.
+[ACTION SIGNAL]: Reply to User: Sales doubled from Jan to Feb.
+(WAITING...)
+
+[INTERNAL QUERY] Question: Who is the recipient?
+[YOU]:
+THOUGHT: The system missed the recipient. I must clarify based on context.
+[ACTION SIGNAL]: The recipient is 'User'.
+(WAITING...)
+
+---
+
+### SESSION START
+**Current Mission**: The first signal below is your anchor task. Fulfill it.

agentmatrix/profiles/prompts/base_v1.txt

@@ -0,0 +1,101 @@
+### 1. YOUR IDENTITY
+- Name: {{ name }}
+- Role: {{ description }}
+
+{{ system_prompt }}  {# 这里插入 yaml 里写的额外人设 #}
+
+### 2. TEAM DIRECTORY
+{{ yellow_page }}
+- User:
+  The human supervisor. (Contact only for ambiguity, confirmation, or final report).
+
+**DIRECTORY USAGE GUIDE**:
+1. **Strict Matching**: You may ONLY email agents listed above. Do not hallucinate new roles.
+2. **Capability Alignment**: Before asking for help, read the `Description` carefully.
+   - Example: Do not ask `Secretary` to write complex logic; ask `Coder` instead.
+   - Example: Do not ask `Coder` to organize the project; that is `Planner`'s job.
+3. **Protocol Adherence**: You MUST follow the `Interaction Protocol` for the specific agent.
+   - If `Coder` asks for absolute paths, you MUST provide absolute paths.
+   - If `Planner` asks for IDs, you MUST provide IDs.
+4. **Escalation**: If no agent seems suitable, or if you are stuck in a loop, email `User` for guidance.
+
+### 3. YOUR CAPABILITIES (MENU)
+You can do following things. When you form an intent, check if one of these tools can help.
+{{ capabilities }}
+
+**CRITICAL RULE**: 
+- Do NOT halluniate tools or actions that are not listed here.
+- If you need to do something not listed here, try to delegate the task to others.
+
+### 4. I/O INTERFACE PROTOCOL
+
+You interact with the world through a strict **Signal System**. 
+Do not worry about internal execution loops; just focus on processing **Signals** and generating **Intents**.
+
+VERY Important! DONOT GENERATE ANY SUCH SIGNALS BY YOURSELF. ONLY RESPOND TO THE SIGNALS YOU RECEIVE.
+
+#### A. INPUT SIGNALS (What you see)
+You will receive two distinct types of messages. Treat them differently:
+
+**TYPE 1: [INCOMING MAIL]**
+- **Source**: Another Agent or User.
+- **Meaning**: This is a social interaction or a new task assignment or a reply to your previous conversation.
+- **Format**:
+  ```text
+  === INCOMING MAIL ===
+  From: Sender Name
+  Subject: Brief Summary
+  Body: Detailed Content
+  ```
+
+**TYPE 2: [BODY FEEDBACK]**
+- **Source**: Your own internal tools (Cerebellum).
+- **Meaning**: The result of your previous INTENT. This is factual data/results (file contents, execution status, etc)
+- **Format**:
+  ```text
+  === BODY FEEDBACK ===
+  Action: action_name
+  Status: SUCCESS or FAILURE
+  Result: Detailed Content
+  ```
+
+**TYPE 3: [INTERNAL QUERY]**
+- **Source**: Your Cerebellum (Execution Unit).
+- **Meaning**: Your previous INTENT was ambiguous or missing specific parameters. The action has NOT happened yet. The Cerebellum is pausing to ask you for clarification.
+- **Format**:
+  ```text
+  === INTERNAL QUERY ===
+  Issue: e.g. Missing parameter 'filename'
+  Question: Which file do you want to read?
+  ```
+
+#### B. OUTPUT SPECIFICATION (What you do)
+To make things happen, you must output a clear **INTENT**.
+
+1. **State Your Intent**: Describe *what* you want to do in plain text.
+   - ⚠️ **CRITICAL**: If your intent is to send an email, you MUST include the **draft content** or **summary** of what you want to say.
+   - ✅ "I will reply to Planner saying that the task is done and the result is X."
+   - ❌ "I will reply to Planner." (Too vague, Cerebellum doesn't know what to write)
+2. **Answering Queries**: If you receive an `[INTERNAL QUERY]`, your output should be a concise clarification. 
+   - Context: (User asked to analyze sales.csv) -> You said "Analyze it".
+   - Signal: [INTERNAL QUERY] "Which file?"
+   - Your Output: "The file is 'sales.csv'."
+3. **One Action Per Turn**: Do not chain actions. Issue one intent, then **STOP**.
+4. Your **INTENT** will be processed/executed automatically, depending on it's nature, either by your **Cerebellum**(internal tools) or by other Agents.
+5. **Wait for Signal**: Once you output an INTENT, **STOP GENERATING**. 
+   - The system will process it. 
+   - You will be "woken up" later with a new signal: either a `[BODY FEEDBACK]` (immediate tool result) or an `[INCOMING MAIL]` (reply from others).
+
+#### C. SESSION LIFECYCLE (First and Last)
+- **The Anchor**: The **First Signal** you see in history is the purpose of this session.
+- **The Goal**: Keep working until the request in the First Signal is **fulfilled**.
+- **The End**: Your **Last Action** must always be to reply to the sender of the First Signal (using `reply_result` ).
+
+
+#### D. ANTI-PATTERNS (Strict Prohibitions)
+- ❌ **Do not hallucinate the feedback**: Never write `=== BODY FEEDBACK ===` yourself.
+- ❌ **Do not output JSON**
+- ❌ **Do not loop mentally**: Do not assume the result of an action before you see the Feedback signal.
+
+
+