# NiuMaBot

**Repository Path**: border-collie-ai/NiuMaBot

## Basic Information

- **Project Name**: NiuMaBot
- **Description**: 自动化机器人，全天24小时工作
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-21
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NiuMaBot

一个功能完备的 AI Agent 框架，基于 Tauri 2.0 构建。

## 📖 目录

1. [核心功能](#-核心功能)
2. [代码统计](#-代码统计)
3. [数据目录](#-数据目录)
4. [整体架构](#-整体架构)
5. [前端功能](#-前端功能)
6. [后端功能](#-后端功能)
   - [飞书渠道集成架构](#-飞书渠道集成架构)
7. [代码目录](#-代码目录)
8. [开发路线](#-开发路线)

---

## 🎯 核心功能

### 核心特性

- 🤖 **多 LLM 支持** - OpenAI, Anthropic, DeepSeek, Google 等
- 💬 **多渠道接入** - 飞书、钉钉、企业微信、Slack 等
- 👥 **团队协作** - Team + Leader + Members 三层架构
- ⚡ **流式执行** - 实时进度反馈，标准化工具执行事件
- 🧠 **智能协作** - Leader 自动拆解任务，依赖管理，多方对齐
- 🔒 **权限控制** - 基于角色的工具/技能/MCP 访问控制
- 📝 **JSONL 存储** - 会话历史按日期分类存储
- 🔧 **多步工具** - 配置化多步骤任务执行和进度跟踪
- 🖥️ **开发模式 Mock** - Vite 开发环境下 Tauri API mock 支持
- 🏗️ **模块化架构** - 核心 Trait 系统 (LlmClient/ToolHandler/TerminalBackend)
- 🌐 **HTTP API 服务器** - 基于 axum 构建，统一处理 RESTful、SSE、Webhook、定时任务
- ⚙️ **统一设置页面** - 7 标签页集中管理（模型、渠道、环境、技能、MCP、工具、系统）

---

## 📊 代码统计

### 总体规模（截至 2026-04-05）

| 项目 | 代码行数 | 文件数 | 说明 |
|------|----------|--------|------|
| **Rust 后端** | **25,170** | ~100 | src-tauri/src/ |
| **TypeScript/React 前端** | **18,910** | ~50 | src/ |
| **总计** | **44,080** | ~150 | 全栈代码量 |

### Rust 后端三层架构

| 层级 | 代码行数 | 占比 | 说明 |
|------|----------|------|------|
| **Core Layer** | 14,886 | 59.1% | 核心业务逻辑 |
| **Interface Layer** | 5,813 | 23.1% | Tauri Commands + HTTP Server |
| **Infrastructure Layer** | 3,831 | 15.2% | 基础设施支持 |
| **其他** | ~640 | 2.6% | lib.rs, main.rs, error.rs 等 |
| **总计** | **25,170** | 100% | - |

#### Core Layer (14,886 lines) - 核心业务
- **tools/**: 4,107 lines - 工具集合最丰富
- **team/**: 3,525 lines - 团队协作引擎
- **agent/**: 1,533 lines - Agent 循环逻辑
- **config/**: 856 lines - 配置管理
- **skills/**: 748 lines - 技能系统
- **channels/**: 233 lines - 渠道适配器
- **llm/**: 439 lines - LLM 抽象
- **cron/**: 428 lines - 定时任务调度
- **daemon/**: 469 lines - 后台服务
- **sessions/**: 198 lines - 会话管理
- **mcps/**: 169 lines - MCP 协议
- **memdir/**: 241 lines - 记忆目录
- **services/**: 222 lines - 服务层
- **utils/**: 323 lines - 工具函数

#### Interface Layer (5,813 lines) - 对外接口
- **commands/**: 4,822 lines - Tauri Commands（teams, messages, agents, tools 等）
- **http_server/**: 982 lines - HTTP Server（RESTful API, SSE, Webhook）

#### Infrastructure Layer (3,831 lines) - 基础设施
- **utils/**: 1,430 lines - 工具函数
- **types/**: 1,144 lines - 类型定义
- **db/**: 1,125 lines - 数据库封装
- **error.rs**: ~132 lines - 错误处理

### TypeScript/React 前端 (18,910 lines)

| 模块 | 代码行数 | 说明 |
|------|----------|------|
| **pages/** | 9,988 | 页面组件（Chat, Teams, Agents, Tools 等） |
| **components/** | 4,741 | UI 组件（StreamingTaskExecutor, ToolCreateForm 等） |
| **utils/** | 1,273 | 工具函数（EventParser, MessageMerger 等） |
| **types/** | 550 | TypeScript 类型定义 |
| **services/** | 414 | 服务层（feishu-webhook, team API 等） |
| **interface/** | 241 | 接口定义 |
| **contexts/** | 54 | React Context |
| **hooks/** | 34 | 自定义 Hooks |

主要特性：
- **Pages**: Chat, Teams, Agents, Tools, Skills, Sessions, Settings 等
- **Components**: StreamingTaskExecutor, ToolCreateForm, MultiSelectDropdown, MessageMerger 等
- **Types**: TeamTypes, TeamStreamTypes, SessionTypes, ConfigTypes 等
- **Services**: feishu-webhook, team API 等

### 前端显示效果示例

#### 团队任务执行流程

现代的任务执行界面使用专用的 Display Components 提供丰富的视觉体验：

**1. 思考阶段**
```
┌─────────────────────────────────────────┐
│ 💭 思考中...                            │
├─────────────────────────────────────────┤
│ 正在分析用户需求，制定执行计划...       │
└─────────────────────────────────────────┘
```

**2. TODO 列表**
```
### 📋 任务分解：共 3 个 TODO

┌──────────────────────────────────────┐
│ ✅ todo-1 - 创建项目结构             │
├──────────────────────────────────────┤
│ ✅ todo-2 - 编写核心代码             │
├──────────────────────────────────────┤
│ ⏳ todo-3 - 添加单元测试             │
└──────────────────────────────────────┘
```

**3. Task 折叠卡片（展开状态）**
```
┌──────────────────────────────────────┐
│ ✅ Task: todo-1               ▼      │
├──────────────────────────────────────┤
│  💭 正在创建项目目录结构...          │
│  📝 创建了 src/ 和 tests/ 目录       │
│  ✏️ Edit  package.json  +15 -2      │
└──────────────────────────────────────┘
```

**4. 文件操作卡片**
```
┌─────────────────────────────────────────────────┐
│ ✏️ Edit  src/main.ts  +25 -8  ▶ 查看文件        │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ 📖 Read  src/utils/helper.ts  Lines 10-29      │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│ ➕ Create  tests/unit.test.ts  +50             │
└─────────────────────────────────────────────────┘
```

**5. 终端输出**
```
┌─────────────────────────────────────────────────┐
│ 💻 Bash Command                                 │
├─────────────────────────────────────────────────┤
│ $ npm test                                      │
│                                                 │
│ PASS  tests/unit.test.ts                        │
│   ✓ should create project structure             │
│   ✓ should run without errors                   │
│                                                 │
│ Test Suites: 1 passed, 1 total                  │
│ Tests:       2 passed, 2 total                  │
│ Exit Code: 0                                    │
└─────────────────────────────────────────────────┘
```

**6. 最终汇总**
```markdown
# 任务执行完成

团队任务完成，共 3 个子任务

• 创建项目结构 - 初始化 TypeScript 项目
• 编写核心代码 - 实现主要功能模块
• 添加单元测试 - 覆盖率达到 85%

| 项目   | 详情              |
|--------|-------------------|
| 交付物 | src/, tests/      |
| 测试   | ✅ 2/2 通过       |
| 覆盖率 | 85%               |
| 状态   | ✅ 成功           |

使用命令 `npm start` 运行项目
```

### 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Rust + Tauri 2.0 + Tokio + SQLite |
| 前端 | React 18 + TypeScript 5 + Vite |
| 基础设施 | LiteLLM + MCP + WebSocket |

---

## 📂 数据目录

### 配置文件位置

```
~/.niumabot/
├── models.json              # 模型配置：LLM 提供商和模型参数配置
├── builtin/
│   ├── agents.json          # Agent 定义：62 个预定义职位和能力模板
│   └── roles.json           # Role 定义：角色职责和权限配置
├── teams/                   # 团队目录（v1.2.0+）
│   ├── {teamId}/
│   │   ├── team.json        # 团队配置：Leader + Members 结构和权限
│   │   ├── SOUL.md          # Leader 角色文档：角色说明和决策逻辑
│   │   └── qa/              # JSONL 会话存储：按日期分类的对话历史
│   └── ...
├── skills/                  # 技能存储目录（v1.3.0+）：自定义技能和工具
├── channels.json            # 渠道配置：飞书、钉钉等企业 IM 接入配置
├── config.json              # 全局配置：系统级设置和默认值
├── sessions.db              # SQLite 数据库：会话管理、消息存储和技能检索
├── MEMORY.md                # 全局记忆文件：系统级记忆和上下文
└── logs/                    # 日志目录：系统运行日志和错误记录
```


### Sessions 迁移到 SQLite（v2.0+）

为了支持更高效的会话搜索和管理，我们已将 sessions 从文件系统迁移到 SQLite 数据库：

**之前的文件系统存储**（已废弃）:
```
~/.niumabot/sessions/
├── {session_id}/
│   └── YYYY-MM-DD/
│       └── HH-mm-ss-{query_preview}.json
└── ...
```

**现在的 SQLite 存储**:
```sql
-- sessions 表：存储会话元数据
CREATE TABLE sessions (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    model TEXT NOT NULL,
    message_count INTEGER DEFAULT 0,
    token_count INTEGER DEFAULT 0,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL
);

-- messages 表：存储会话消息
CREATE TABLE messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT NOT NULL,
    role TEXT NOT NULL,           -- 'user', 'assistant', 'member'
    content TEXT NOT NULL,        -- JSON 格式的消息内容
    token_count INTEGER DEFAULT 0,
    created_at TEXT NOT NULL,
    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
);
```

**优势**:
- ✅ **高效搜索**: 支持 SQL 查询，快速检索历史会话
- ✅ **事务安全**: ACID 特性保证数据一致性
- ✅ **空间优化**: 相比 JSON 文件更节省存储空间
- ✅ **索引支持**: 可以创建索引加速查询
- ✅ **统一管理**: 与 skills 表共用同一个数据库

**迁移说明**:
- 旧的 `sessions/` 目录不再使用
- 所有会话数据现在存储在 `sessions.db` 中
- 团队任务执行记录仍保存在 `teams/{teamId}/qa/` 目录中（JSONL 格式）

### logs、sessions 和 team-qa 的区别

| 概念 | 维度 | 用途 | 存储位置 | 特点 |
|------|------|------|----------|------|
| **logs** | 系统级 | 存储系统运行日志和错误记录 | `~/.niumabot/logs/` | 系统级别的日志，用于调试和监控 |
| **sessions** | 会话级 | 存储具体的对话历史和会话数据 | `~/.niumabot/sessions.db` | SQLite 数据库，支持高效搜索和管理 |
| **team-qa** | 团队级 | 存储团队任务执行记录 | `~/.niumabot/teams/{teamId}/qa/` | JSONL 格式，按日期分类 |

**详细说明**：
- **logs**：主要用于系统运维和调试，记录系统运行过程中的各种事件和错误信息，帮助开发者和管理员了解系统的运行状态。
- **sessions**：是会话级别的数据存储，使用 SQLite 数据库存储用户与系统的完整对话历史。支持 SQL 查询、索引加速、事务安全等特性。
- **team-qa**：团队任务执行的详细记录，包括内部消息、任务进度、执行结果等，以 JSONL 格式存储，便于分析和回溯。

**使用场景**：
- 当系统出现问题时，查看 `logs` 目录下的日志文件进行调试。
- 当需要查看历史对话记录时，通过 `sessions.db` 数据库查询（支持关键词搜索、时间范围筛选等）。
- 当需要分析团队任务执行情况时，查看 `teams/{teamId}/qa/` 目录中的 JSONL 文件。

### 团队目录结构

```
~/.niumabot/teams/
├── pro-dev-team/
│   ├── team.json            # Leader + Members 配置
│   ├── SOUL.md              # Leader 角色说明（可进化）
│   └── qa/                  # 对话历史
│       ├── 2026-03-17/
│       │   └── session-001.jsonl
│       └── 2026-03-18/
│           └── session-002.jsonl
```

**JSONL 格式示例**：
```jsonl
{"timestamp": 1710672000, "role": "user", "content": "创建脚本", "metadata": {"source": "chat"}}
{"timestamp": 1710672001, "role": "assistant", "content": "好的...", "metadata": {"type": "streaming"}}
```

**优势**：逐行独立、增量追加、高效检索

---

## 🏗️ 整体架构

### Tauri IPC 架构

```
┌─────────────────────┐
│  Frontend (React)   │
│  invoke() + listen()│
└──────────┬──────────┘
           │ Tauri IPC
┌──────────▼──────────┐
│  Backend (Rust)     │
│  Commands + Events  │
└─────────────────────┘
```

**核心特点**：
- ✅ Tauri Command 即网关
- ✅ 双向通信（invoke + listen）
- ✅ 零网络延迟
- ✅ 事件驱动推送

### 三层智能协作架构

```
用户请求
   ↓
SystemAssistant (意图识别 + 路由)
   ├─ 简单任务 → 直接回答
   └─ 复杂任务 → Team Executor
       ↓
   Leader + Members (专业协作)
```

**层级说明**：
- **L1 - SystemAssistant**: 意图识别、路由决策
- **L2 - Team Executor**: 复杂任务分发
- **L3 - Role Workers**: 专业角色协作执行

---

### 🏗️ 模块化架构

项目采用 **Trait 驱动** 的模块化设计，基于四个核心抽象：

| 模块 | 核心 Trait | 作用 |
|------|-----------|------|
| `core/llm.rs` | `LlmClient` | LLM 调用抽象，统一支持 OpenAI/Anthropic/DeepSeek 等 |
| `core/tool.rs` | `ToolHandler` | 工具执行抽象，支持内置工具 + MCP |
| `core/terminal.rs` | `TerminalBackend` | 终端执行抽象，本地命令执行 |
| `core/error.rs` | `Error` | 统一错误类型定义 |

#### 新增功能模块

| 模块 | 功能说明 | 使用场景 |
|------|---------|----------|
| **http_server/** | HTTP API 服务器 | 统一处理 RESTful API、SSE 流式、Webhook、定时任务 |

#### HTTP Server 模块流程
```
请求 → Router → 中间件链 → Handler → 响应
              ↓
        ├─ AuthMiddleware (认证)
        ├─ LoggingMiddleware (日志)
        ├─ RateLimiter (限流)
        └─ MetricsCollector (指标)
```

**应用场景**：飞书/钉钉 Webhook 接入、外部系统 API 调用、SSE 流式对话、定时任务调度

---



**协作流程**：
```
用户问题 → Leader 拆解为 Todos → Members 执行 → 汇总结果
```

### 🔄 模型参数传递数据流

**完整传递链路**：
```
前端 Chat.tsx
   ↓ invoke('execute_team_task_streaming', { modelId })
后端 execute_team_task_streaming(model_id: Option<String>)
   ├─ Some(mid) → 使用并更新全局状态
   └─ None → 从全局状态获取默认值
   ↓ final_model_id
StreamingTaskExecutor::new(final_model_id)
   ↓ 设置到全局状态
execute_task_with_streaming()
   ↓ 从全局状态读取
BaseExecutor::new(..., model_id)
   ↓ 存储在 TeamExecutor.model_id
所有调用 assign_to_member() 的地方
   ↓ 传递 &self.model_id
assign_to_member(member, subtask, model_id: &str)
   ↓ 直接设置到 agent.model
AgentLoop.run_loop() → self.config.model
   ↓ 调用 LLM
LLMClient::from_model_id(model_id)
   ├─ 读取 models.json
   ├─ 查找模型配置
   ├─ 如缺少认证信息，从 providers 中获取
   └─ 创建 LLMClient 实例
使用正确的模型执行任务
```

**优先级顺序**：
1. ✅ **前端传递的 modelId** (最高优先级)
2. ✅ **全局状态中的 default_model**
3. ✅ **常量 DEFAULT_MODEL_ID** ("gpt-4o-mini", 最低优先级/兜底)

**核心设计原则**：
- 🎯 **统一入口**: `execute_team_task_streaming` 统一处理模型参数
- 🔄 **单向传递**: 从顶层一直传递到最底层，避免中间环节自行获取
- 💾 **全局状态**: 通过全局状态管理运行时配置
- 🔧 **灵活切换**: 支持每次对话使用不同模型
- 🛡️ **封装良好**: `LLMClient::from_model_id()` 统一封装模型配置读取和供应商配置

**关键代码位置**：
- 前端调用：`niumabot/src/pages/Chat.tsx` (第 453-456 行)
- 后端接收：`niumabot/src-tauri/src/interface/commands/teams.rs`
- 执行器创建：`niumabot/src-tauri/src/core/team/streaming.rs`
- 任务分配：`niumabot/src-tauri/src/core/team/executor.rs`
- LLM 调用：`niumabot/src-tauri/src/core/llm/client.rs`

**基于角色的权限控制**：
- 每个角色配置可用的工具/技能/MCP 范围
- AgentLoop 调用前自动验证权限
- 防止越权操作，提高安全性

**Todo 管理**：
- 依赖管理：支持任务前后置依赖
- 状态跟踪：Pending/InProgress/Blocked/Completed
- 多方对齐：需要协作时自动发起对齐会议
- 并发执行：独立 Todo 可并行处理

**典型协作场景**：

1. **开发 → 测试（直接协作）**
   ```
   开发完成 → 汇报 Leader → Leader 通知测试 → 测试开始
              ↓
         附带开发成果
   ```

2. **开发 → Leader → 测试（Leader 中转）**
   ```
   开发完成 → Leader 验收 → Leader 转交测试 → 测试开始
              ↓
         验收意见 + 代码
   ```

3. **多成员并行协作**
   ```
   前端开发 ─┐
            ├→ Leader 汇总 → 集成测试
   后端开发 ─┘
   ```

详细文档：[TEAM_COLLABORATION_ENGINE.md](niumabot/src-tauri/TEAM_COLLABORATION_ENGINE.md)

**JSONL 优势**：逐行独立、增量追加、高效检索

**数据迁移**：应用启动时自动从 teams.json 迁移到独立目录

---

## 💻 前端功能

### 核心功能模块

**启动配置**：
- ⚙️ **系统配置** - 人格配置、工作区管理
- 📺 **渠道** - 飞书、钉钉等企业 IM 接入
- 🤖 **模型** - LLM 提供商和模型配置
- 🧩 **Agent** - AI 能力模板定义
- 🔧 **工具** - 内置工具 + MCP 服务器
- 👥 **团队** - Leader + Members 协作单元

**功能服务**：
- 💬 **对话** - 多轮智能对话
- ⏰ **定时任务** - 可视化配置 + AI 执行
- 📝 **会话** - 历史查看、搜索

**其他**：
- ⚙️ **服务配置** - 后台服务参数
- 📋 **日志** - 启动日志、运行日志

### 团队页面原型

**双栏布局**：
```
┌────────────────────────────────────────┐
│ 📊 {团队名称} - 处理历史        [×]   │
├──────────────┬─────────────────────────┤
│ 左侧边栏     │  右侧主区域             │
│ (350px)      │                         │
│              │  ┌───────────────────┐  │
│ 👥 团队成员   │  │ ✅ 代码审查任务   │  │
│ ┌──────────┐ │  │ 2026-03-10 14:30  │  │
│ │👑 张架构师│ │  └───────────────────┘  │
│ │💼 Python │ │                         │
│ │📋 技术总监│ │  ┌───────────────────┐  │
│ ├──────────┤ │  │ 👑 张架构师 | 分析 │  │
│ │👤 李开发  │ │  │ 我来分析一下...   │  │
│ │💼 Java   │ │  └───────────────────┘  │
│ │📋 高级工程师│ │                       │
│ ├──────────┤ │      ┌───────────────┐  │
│ │👤 王测试  │ │      │ 👤 李开发 | 讨论│  │
│ └──────────┘ │      │ 收到！马上处理 │  │
│              │      └───────────────┘  │
│ 任务列表 (3)  │                         │
│              │  ┌───────────────────┐  │
│ ✅ 代码审查   │  │ 📄 执行结果       │  │
│ 2026-03-10   │  │ 查询速度提升 50%  │  │
│              │  └───────────────────┘  │
│ 🔄 Bug 修复   │                         │
│ 2026-03-09   │                         │
│              │                         │
│ ⏳ 功能开发   │                         │
│ 进行中       │                         │
└──────────────┴─────────────────────────┘
```

### 🎨 Display Components UI 效果 (v2.0)

前端使用专用的 Display Components 渲染各种消息类型，提供丰富的视觉体验。

#### Task - 折叠卡片

**折叠状态**:
```
┌──────────────────────────────────────┐
│ ✅ Task: todo-1                      │
└──────────────────────────────────────┘
```

**展开状态**:
```
┌──────────────────────────────────────┐
│ ✅ Task: todo-1               ▼      │
├──────────────────────────────────────┤
│  💭 思考中...                        │
│  📝 文本消息                         │
│  ✏️ Edit  src/App.tsx  +10 -5       │
└──────────────────────────────────────┘
```

#### FileOperationCard - 文件操作卡片

**Edit File**:
```
┌─────────────────────────────────────────────────┐
│ ✏️ Edit  src/App.tsx  +10 -5  ▶ 查看文件        │
└─────────────────────────────────────────────────┘
```

**点击展开后**:
```
┌─────────────────────────────────────────────────┐
│ ✏️ Edit  src/App.tsx  +10 -5  ▼ 折叠文件        │
├─────────────────────────────────────────────────┤
│  [DiffView 左右对比视图]                         │
└─────────────────────────────────────────────────┘
```

**Read File**:
```
┌─────────────────────────────────────────────────┐
│ 📖 Read  src/utils/helper.ts  Lines 10-29      │
└─────────────────────────────────────────────────┘
```

#### TerminalOutput - 终端输出

```
┌─────────────────────────────────────────────────┐
│ 💻 Bash Command                                 │
├─────────────────────────────────────────────────┤
│ $ npm install                                   │
│ added 125 packages in 3s                        │
│ Exit Code: 0                                    │
└─────────────────────────────────────────────────┘
```

#### Thinking - 思考过程

```
┌─────────────────────────────────────────────────┐
│ 💭 思考中...                                    │
├─────────────────────────────────────────────────┤
│ 正在分析用户需求，制定执行计划...               │
└─────────────────────────────────────────────────┘
```

**特性**:
- ✅ 统一的卡片样式
- ✅ 左侧边框颜色表示状态（绿色=成功，蓝色=进行中，红色=失败）
- ✅ 支持展开/折叠交互
- ✅ 显示行数变化 (+xx -xx)
- ✅ 集成 DiffView 左右对比视图
- ✅ 响应式设计，支持移动端

**详细文档**: [DISPLAY_COMPONENTS_UI_SHOWCASE.md](./DISPLAY_COMPONENTS_UI_SHOWCASE.md)

**界面交互特性**：
- **工种智能匹配**：从 roles.json 获取 position，从 agents.json 获取 Agent 名称
- **动态数据加载**：打开历史页面时自动加载团队成员信息
- **视觉效果**：淡入动画、响应式布局、悬停高亮、状态标识

---

## ⚙️ 后端功能

### 核心工作流

**请求 - 响应模式**：
```
前端 → invoke() → Rust Command → 处理逻辑 → 返回结果 → 前端渲染
```

**事件推送模式**：
```
Rust 处理完成 → app.emit() → Tauri 事件系统 → listen() 回调 → 前端更新 UI
```

---

### 📺 飞书渠道集成架构

#### 整体架构

项目采用 **混合架构**：Node.js WebSocket + Rust HTTP Server 协同工作

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   飞书用户   │────▶│  Node.js     │────▶│    Rust      │
│  发送消息    │ WS  │  WebSocket   │ HTTP│  TeamExecutor│
└──────────────┘     └──────────────┘     └──────────────┘
                            ↓                      ↓
                       消息接收              AI 处理 + 回复
```

#### 详细数据流程

1. **飞书用户** → 在飞书客户端发送消息
2. **飞书服务器** → 通过 WebSocket 推送事件到 Node.js 服务
3. **Node.js (feishu-webhook-v2.ts)** 
   - 使用 `@larksuiteoapi/node-sdk` 维持 WebSocket 长连接
   - 监听 `im.message.receive_v1` 事件
   - 解析消息内容（文本、图片、卡片等）
   - HTTP POST 转发到 Rust 后端：`http://localhost:8889/webhook/feishu`
4. **Rust Axum Server (webhook/feishu_server.rs)**
   - 监听端口 8889
   - `/webhook/feishu` endpoint 接收 Node.js 转发的消息
   - 提取消息 ID、聊天 ID、发送者、内容
5. **Rust TeamExecutor**
   - `handle_channel_message()` 函数处理渠道消息
   - 创建团队任务（Leader + Members 模式）
   - 异步执行团队任务，生成响应
6. **Rust FeishuApiClient**
   - 调用飞书开放平台 API
   - 创建流式消息卡片
   - 实时更新卡片内容（每 200ms）
7. **飞书客户端** → 显示流式卡片，用户可见实时进度

#### 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| Node.js 服务 | `@larksuiteoapi/node-sdk` v2.0 | 飞书官方 SDK，WebSocket 长连接 |
| Rust HTTP Server | axum + tokio | 高性能异步 HTTP 服务器 |
| 通信协议 | HTTP POST (JSON) | Node.js → Rust 本地通信 |
| 飞书 API | open.feishu.cn/open-apis | 发送/更新消息卡片 |

#### 启动流程

```bash
# 只需一个命令启动所有服务
cd niumabot
npm run dev

# 自动执行：
# 1. Rust 后端启动 → 自动 spawn Node.js 子进程
# 2. Node.js 飞书服务启动 → WebSocket 连接飞书
# 3. Rust HTTP Server 启动 → 监听端口 8889
# 4. Vite 前端服务启动 → 端口 5173
```

**预期日志**：
```
🚀 [GlobalState] 正在初始化...
🔌 [Feishu Service] 正在启动 Node.js 飞书 WebSocket 服务...
✅ [Feishu Service] Node.js 飞书服务已启动 (PID: xxxxx)
   📝 [Feishu Service] 日志将显示在当前控制台
🚀 [HTTP Server] 启动在端口 8889

============================================================
🚀 [Feishu Service] 飞书长连接服务启动
============================================================
✅ [Feishu Service] 渠道已连接：niumabot
   📊 [Feishu Service] WebSocket 状态：已连接
```

#### 配置要求

**飞书开发者后台配置**：
1. 登录 https://open.feishu.cn/app
2. 进入你的应用
3. **事件与回调** → **订阅方式** → 选择 **使用长连接接收事件/回调**
4. **订阅事件列表** → 勾选 **接收消息** (`im.message.receive_v1`)
5. **机器人配置** → 启用机器人并添加到对话

**本地环境要求**：
- ✅ Node.js 18+ (运行飞书 WebSocket 服务)
- ✅ Rust 1.70+ (Tauri 应用)
- ✅ npm 依赖包：`@larksuiteoapi/node-sdk`, `axios`

#### 架构优势

- **职责分离**：Node.js 专注消息接收，Rust 专注业务处理
- **高性能**：非阻塞 I/O，SSE 流式推送，~1ms 本地通信延迟
- **可扩展**：模块化设计，易于添加其他渠道（钉钉、企业微信）
- **向后兼容**：保持现有 Tauri IPC 架构不变

详细实现文档：~~FINAL_SUMMARY.md~~ (已移除，信息整合到本文档)

### 流式任务执行

**标准事件类型**：

| 类型 | 图标 | 用途 | 样式 |
|------|------|------|------|
| thinking | 🤔 | Leader/成员思考过程 | 灰底白字，斜体小字 |
| todos | 📋 | TODO 列表项 | 白底黑字，蓝色左边框 |
| task | 📨 | 任务开始执行通知 | 浅蓝底深蓝文字，加粗 |
| edit_file | ✏️ | 编辑文件 | 默认样式 |
| delete_file | 🗑️ | 删除文件 | 默认样式 |
| create_file | 📄 | 创建文件 | 默认样式 |
| read_file | 📖 | 读取文件 | 默认样式 |
| bash | 💻 | 终端命令 | 默认样式 |
| search | 🔍 | 网络搜索 | 默认样式 |
| summary | ✅ | 汇总结果 | 默认样式 |
| outputs | 📦 | 产物汇总 | 默认样式 |
| error | ❌ | 错误信息 | 红色警告 |
| done | ✅ | 任务完成 | 默认样式 |

**重要说明** (v1.5.0+)：
- ✅ **已移除通用事件**：`task_analysis`, `task_assigned`, `task_accepted`, `task_result`
- ✅ **使用工具事件**：直接使用 `edit_file`, `bash`, `read_file` 等具体工具事件
- ✅ **标准化格式**：所有消息包含 `status`, `card`, `executor` 字段
- ✅ **智能合并**：相同类型连续消息自动合并 content

**消息样式分层设计** (v1.2.1+)：
```
┌─────────────────────────────────────┐
│ 🤔 思考过程（灰色，斜体，小字）       │ ← 次要信息
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│ 📋 任务分解：共 3 个 TODO             │
├─────────────────────────────────────┤
│ 📋 TODO 1 - 创建文件（白色背景，蓝框）│ ← 主要内容
│ 📋 TODO 2 - 编写代码（白色背景，蓝框）│
│ 📋 TODO 3 - 测试运行（白色背景，蓝框）│
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│ 📨 任务分配：创建文件 → 小李（蓝色）  │ ← 重要操作
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│ ✅ 小李：收到任务（灰色，小字）        │ ← 执行过程
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│ ✅ 执行结果：成功（绿色）             │ ← 结果反馈
└─────────────────────────────────────┘
```

**CSS 类名**：
- `.msg-todo` - TODO 项（主要内容）
- `.msg-action` - 任务分配（重要操作）
- `.msg-execution` - 任务接受/执行过程（次要信息）
- `.msg-thinking` - 思考过程（次要信息）
- `.msg-result.msg-success` - 执行成功（绿色）
- `.msg-result.msg-error` - 执行失败（红色）

**视觉特点**：
- 左侧彩色边框：4px 不同颜色快速区分类型
- 圆角设计：6px 圆角，现代化视觉效果
- 内边距：8px-12px，良好的内容呼吸感
- 字体层次：正常/加粗/斜体，0.85em-1em 字号变化

### 🔄 流式消息合并机制 (v1.5.1+)

前端采用智能消息合并策略，确保流式更新的高效性和用户体验。

#### 核心规则

**1. opr: update - 更新历史消息**
- 相同类型的连续消息自动合并 content
- 字符串直接拼接，对象根据 status 决定替换或深度合并

**2. card: todo_xx - 更新 TODO 任务数据**
- 带 card 的消息归类到对应的 TODO 任务
- TODO 任务内的消息独立合并，不同 TODO 之间互不影响

**3. 相同类型连续消息 - 自动合并**
- 检查最后一条消息的类型是否相同
- 如果相同则合并 content，否则添加新消息

#### 合并效果示例

**输入消息流**：
```json
[
  {"type": "thinking", "content": "正在", "status": "in_progress", "card": null, "executor": "leader_user_0001"},
  {"type": "thinking", "content": "分析", "status": "in_progress", "card": null, "executor": "leader_user_0001"},
  {"type": "todos", "content": {...}, "status": null, "card": null, "executor": "leader_user_0001"},
  {"type": "thinking", "content": "开始", "status": "in_progress", "card": "todo-1", "executor": "member_0001"},
  {"type": "thinking", "content": "执行", "status": "in_progress", "card": "todo-1", "executor": "member_0001"},
  {"type": "edit_file", "content": {"filepath": "test.txt", "add_lines": 10, "remove_lines": 5}, "status": "success", "card": "todo-1", "executor": "member_0001"}
]
```

**输出合并结果**：
```json
[
  {
    "type": "thinking",
    "content": "正在分析",  // ✅ 已合并
    "opr": "update",
    "status": "in_progress",
    "card": null,
    "executor": "leader_user_0001"
  },
  {
    "type": "todos",
    "content": {...},
    "opr": "add",
    "status": null,
    "card": null,
    "executor": "leader_user_0001"
  },
  {
    "type": "todo-1",
    "content": [
      {
        "type": "thinking",
        "content": "开始执行",  // ✅ 已合并
        "opr": "update",
        "status": "in_progress",
        "card": null,
        "executor": "member_0001"
      },
      {
        "type": "edit_file",
        "content": {
          "filepath": "test.txt",
          "add_lines": 10,
          "remove_lines": 5
        },
        "opr": "add",
        "status": "success",
        "card": null,
        "executor": "member_0001"
      }
    ],
    "opr": "update",
    "status": "success",
    "card": null,
    "executor": "member_0001"
  }
]
```

#### 合并策略详解

**字符串合并**：
```typescript
msg1: { type: 'thinking', content: '正在' }
msg2: { type: 'thinking', content: '分析' }
→ { type: 'thinking', content: '正在分析', opr: 'update' }
```

**对象合并（in_progress）**：
```typescript
msg1: { type: 'edit_file', content: { file_path: 'test.txt' }, status: 'in_progress' }
msg2: { type: 'edit_file', content: { add_lines: 10 }, status: 'in_progress' }
→ { type: 'edit_file', content: { file_path: 'test.txt', add_lines: 10 }, opr: 'update' }
```

**对象替换（success/fail）**：
```typescript
msg1: { type: 'edit_file', content: {...}, status: 'in_progress' }
msg2: { type: 'edit_file', content: {完整结果}, status: 'success' }
→ { type: 'edit_file', content: {完整结果}, status: 'success', opr: 'update' }
```

**TODO 任务隔离**：
```typescript
msg1: { type: 'thinking', content: 'A', card: 'todo-1' }
msg2: { type: 'thinking', content: 'B', card: 'todo-2' }
msg3: { type: 'thinking', content: 'C', card: 'todo-1' }
→ 
todo-1: ['A', 'C']  // ✅ C 不与 B 合并
todo-2: ['B']
```

#### 技术实现

**MessageMerger 类** (`niumabot/src/utils/MessageMerger.ts`)：
```typescript
class MessageMerger {
  // 处理新的流式消息
  processMessage(msg: StreamMessage): (MergedMessageRecord | TodoTaskRecord)[];
  
  // 获取所有合并后的消息
  getMessages(): (MergedMessageRecord | TodoTaskRecord)[];
  
  // 重置合并器
  reset(): void;
}
```

**EventParser 集成** (`niumabot/src/utils/EventParser.ts`)：
```typescript
class EventParser {
  // 处理 StreamMessage（使用合并器）
  processStreamMessage(msg: StreamMessage): (MergedMessageRecord | TodoTaskRecord)[];
  
  // 获取所有合并后的消息
  getMergedMessages(): (MergedMessageRecord | TodoTaskRecord)[];
}
```

**使用示例**：
```typescript
import { eventParser } from '../utils/EventParser';

// 接收流式消息
eventSource.onmessage = (event) => {
  const msg: StreamMessage = JSON.parse(event.data);
  
  // ✅ 处理并合并
  eventParser.processStreamMessage(msg);
  
  // ✅ 获取最新的所有消息
  const messages = eventParser.getMergedMessages();
  setMessages(messages);
};
```

详细文档：
- [MESSAGE_MERGER_GUIDE.md](MESSAGE_MERGER_GUIDE.md) - 详细使用指南
- [STREAMING_MESSAGE_MERGER.md](STREAMING_MESSAGE_MERGER.md) - 实现总结

**执行流程**：
```
用户发送任务
    ↓
创建空助手消息占位
    ↓
Leader 分析 → 推送 thinking
    ↓
拆解为 TODO → 推送 todo
    ↓
┌─────────────────────────────┐
│ 执行所有 TODO               │← ✅ 已确认
│ - TODO 1: 成员 A 执行       │
│ - TODO 2: 成员 B 执行       │
│ - TODO 3: 成员 C 执行       │
│ (并行或顺序执行)            │
└──────────────┬──────────────┘
               ↓
       所有 TODO 完成        ← ✅ execute_sequential/parallel/dynamic
               ↓
       成员汇报 → Leader 收集成果
               ↓
┌─────────────────────────────┐
│   Leader 判断是否需要协作？   │ ← ✅ analyze_collaboration_with_llm()
└──────────────┬──────────────┘
               │
     ┌─────────┴───────┐
     │是               │否
     ↓                 ↓
┌─────────┐       ┌──────────┐
│通知相关  │       │Leader 汇总│
│成员协作  │       │所有结果   │
│(开发→测试)│      └────┬─────┘
└────┬────┘            │
     │                 │
     └──────┬──────────┘
            ↓
      Leader 最终汇总
            ↓
      XV|      推送完成 → done
```



### 助手问答执行流程（优化后）

**当前执行架构**：简单本地任务优先走 `SingleAgentMode`，复杂协作任务才进入 `TeamMode`。Leader 不再创建“补齐缺失结果”类 recovery TODO，补救闭环由 Member/AgentLoop 内部完成。

```mermaid
flowchart TD
    A[用户输入 / nm agent 问题] --> B{任务路由}

    B -->|无需工具的普通问答| C[DirectAnswerMode]
    B -->|简单本地事实/统计/读取/检查| D[SingleAgentMode]
    B -->|复杂开发/多角色协作/多交付物| E[TeamMode]

    C --> C1[模型直接回答]
    C1 --> Z[输出 Final Answer]

    D --> D1[单 Agent 接收任务]
    D1 --> D2[检索相关 Skill Contract]
    D2 --> D3[Plan: 生成结构化执行计划]
    D3 --> D4[Plan Review: 工具存在/参数/schema/嵌套 shell 检查]
    D4 -->|不通过| D3
    D4 -->|通过| D5[Execute: 调用结构化工具]
    D5 --> D6[工具结果结构化: parsed / summary / artifact_refs]
    D6 --> D7[Evaluate: 判断是否满足成功标准]
    D7 -->|未完成| D8[Repair: 基于错误类型生成修复计划]
    D8 --> D4
    D7 -->|已完成| D9[Summarize: 生成最终回复]
    D9 --> Z

    E --> E1[Leader 判断目标和边界]
    E1 --> E2[Leader 生成方法论级 TODO]
    E2 --> E3[成员按依赖领取 TODO]
    E3 --> E4[Member 内部执行 AgentLoop 闭环]
    E4 --> E5{还有 TODO?}
    E5 -->|有| E3
    E5 -->|无| E6[Leader 汇总成员结果]
    E6 --> Z
```

---

#### SingleAgentMode 快速路径

适用场景：统计、列出、查看、读取、检查等简单本地事实任务。该模式绕过 Team/Leader，减少模型调用和中间 TODO。

```mermaid
sequenceDiagram
    participant U as User / CLI
    participant R as Router
    participant A as AgentLoop
    participant S as Skill Retriever
    participant V as Plan Reviewer
    participant T as Tool Registry

    U->>R: 统计当前项目代码行数
    R->>R: 判定为简单本地事实任务
    R->>A: 启动 SingleAgentMode
    A->>S: 检索相关 Skill Contract
    S-->>A: 返回项目扫描/统计技能约束
    A->>A: Plan 生成执行计划
    A->>V: 审查工具和参数
    V-->>A: 通过 / 返回问题
    A->>T: Execute 调用 project_scan / shell_command
    T-->>A: 返回结构化结果 parsed/summary/artifact_refs
    A->>A: Evaluate 判断是否完成
    alt 未完成
        A->>A: Repair 生成修复计划
        A->>V: 重新审查
    else 已完成
        A->>A: Summarize 生成最终答复
        A-->>U: Final Answer + Result Data
    end
```

---

#### TeamMode 协作路径

适用场景：复杂开发、多文件修改、多角色协作、需要拆分多个交付物的任务。Leader 只负责方法论级拆解和最终汇总，不负责具体工具调用和 recovery。

```mermaid
flowchart LR
    U[用户任务] --> L1[Leader 分析目标/约束/缺口]
    L1 --> L2[Leader 生成方法论级 TODO]
    L2 --> TQ[TODO 队列]

    TQ --> M1[Member A]
    TQ --> M2[Member B]
    TQ --> M3[Member N]

    M1 --> A1[AgentLoop 闭环]
    M2 --> A2[AgentLoop 闭环]
    M3 --> A3[AgentLoop 闭环]

    A1 --> R[成员结果]
    A2 --> R
    A3 --> R

    R --> L3[Leader 汇总]
    L3 --> D[done]
```

---

#### AgentLoop 状态机

AgentLoop 内部使用固定状态流转，模型不能在任意阶段做任意事情。工具失败、输出不可解析、模型 JSON 错误等都归类为结构化错误，再进入 Repair。

```mermaid
stateDiagram-v2
    [*] --> Plan
    Plan --> PlanReview
    PlanReview --> Plan: 审查失败
    PlanReview --> Execute: 审查通过
    Execute --> Evaluate: 工具成功或失败均结构化返回
    Evaluate --> Repair: 未满足成功标准
    Repair --> PlanReview: 生成修复计划
    Evaluate --> Summarize: 已满足成功标准
    Summarize --> Done
    Plan --> Failed: 模型输出无法修复
    Execute --> Failed: 不可恢复工具错误
    Failed --> [*]
    Done --> [*]
```

---

#### 结构化工具和结果

优先使用结构化专用工具，减少模型手写复杂 shell：

```mermaid
flowchart TD
    A[Agent Plan] --> B{选择工具}
    B -->|项目扫描/统计/计数| C[project_scan]
    B -->|普通本机命令| D[shell_command]
    B -->|文件读写| E[read_file/write_file/edit_file]

    C --> F[结构化 JSON: total_files/total_lines/by_extension]
    D --> G[stdout/stderr + parsed JSON + artifact_refs]
    E --> H[文件操作结构化结果]

    F --> I[Evaluate]
    G --> I
    H --> I
```

---

#### Skill Contract 使用流程

技能不再只是提示词片段，而是可检索、可验证的契约，包含适用场景、推荐工具、输出字段、验收规则和修复建议。

```mermaid
flowchart TD
    A[用户任务] --> B[技能检索]
    B --> C[Top K Skill Contract]
    C --> D[注入 Plan 上下文]
    D --> E[生成执行计划]
    E --> F[执行工具]
    F --> G[根据 Contract 验收 required_fields / success_criteria]
    G -->|失败| H[使用 repair_hints 修复]
    H --> E
    G -->|成功| I[总结输出]
```

---

#### 错误处理与恢复

```mermaid
flowchart TD
    A[执行异常] --> B{错误类型}
    B --> C[ModelOutputParseError]
    B --> D[ToolNotFound]
    B --> E[ToolArgsInvalid]
    B --> F[ToolExecutionFailed]
    B --> G[ToolTimeout]
    B --> H[OutputUnparseable]
    B --> I[CompletionCriteriaNotMet]
    B --> J[ExternalServiceUnavailable]

    C --> C1[JSON 修复/重新要求结构化输出]
    D --> D1[重新选择已注册工具]
    E --> E1[按 schema 修正参数]
    F --> F1[读取 stderr/stdout 后修复计划]
    G --> G1[缩小输出/增加超时/换工具]
    H --> H1[要求工具输出 JSON 或使用 parsed]
    I --> I1[Repair 生成补充动作]
    J --> J1[直接报告外部服务不可用]

    C1 --> K[回到 PlanReview]
    D1 --> K
    E1 --> K
    F1 --> K
    G1 --> K
    H1 --> K
    I1 --> K
    J1 --> L[Failed / 等待重试]
```

---

#### 关键机制详解

**1. Team TODO 只做方法论级拆解**

Leader 负责判断任务边界、拆出可交付 TODO、设置依赖和验收口径；具体怎么调用工具、命令失败后怎么修复，交给 Member 内部的 `AgentLoop`。这样可以避免 Leader 反复添加“补齐缺失结果”这类低质量 recovery TODO。

```rust
pub struct SubTask {
    pub id: String,
    pub title: String,
    pub description: String,
    pub assignee: String,
    pub targets: Vec<String>,
    pub suggestions: Vec<String>,
    pub success_criteria: Vec<String>,
    pub dependencies: Vec<String>,
    pub previous_results: Vec<TaskResult>,
}
```

- `targets`：交付物或要完成的目标。
- `suggestions`：Leader/Skill 给 Member 的执行建议，不是强制命令。
- `success_criteria`：成员完成后用于自检的验收条件。
- `previous_results`：同一会话内前序 TODO 的结果上下文。

**2. AgentLoop 使用阶段化结构，不再依赖松散 next_actions**

新的执行核心按 `Plan -> PlanReview -> Execute -> Evaluate -> Repair -> Summarize` 流转。运行时仍兼容旧的 `next_actions` 响应格式，但优化目标是让每个阶段使用更明确的 schema，减少“夹杂自然语言导致 JSON 解析失败”的问题。

```rust
pub struct ExecutionPlan {
    pub goal: String,
    pub assumptions: Vec<String>,
    pub actions: Vec<PlannedAction>,
    pub success_criteria: Vec<String>,
}

pub struct PlannedAction {
    pub tool: String,
    pub args: serde_json::Value,
    pub purpose: String,
    pub expected_output: Vec<String>,
}

pub struct EvaluationResult {
    pub completed: bool,
    pub evidence: Vec<String>,
    pub missing: Vec<String>,
    pub repair_goal: Option<String>,
}

pub struct RepairPlan {
    pub repair_reason: String,
    pub actions: Vec<PlannedAction>,
}
```

**3. PlanReview 在执行前拦截低质量计划**

Member 生成计划后不会马上执行，而是先做本地审查：

- 工具名必须来自运行时注入的工具注册表，不能凭空使用不存在的工具。
- 工具参数必须匹配 schema，缺少必填字段直接退回修正。
- 系统命令优先使用当前平台可执行的 shell：Windows 使用 PowerShell，Linux/macOS 使用 shell/bash 语义。
- 简单本机任务优先使用结构化专用工具；没有专用工具时再用 `shell_command`。
- 禁止为了“先看看项目结构”而无条件插入无关步骤，计划必须直接服务于用户目标。

**4. 工具结果必须结构化，方便模型判断是否完成**

工具不只返回一段 stdout，而是返回可判断的数据结构：

```rust
pub struct ToolExecutionResult {
    pub tool: String,
    pub success: bool,
    pub parsed: serde_json::Value,
    pub summary: String,
    pub artifact_refs: Vec<String>,
    pub error: Option<String>,
}
```

- `project_scan`：适合项目扫描、文件统计、代码行数等结构化任务。
- `shell_command`：适合没有专用工具时执行本机命令，支持 stdout/stderr、解析结果和长输出 artifact。
- 文件工具：适合读取、写入、编辑明确路径的文件。

**5. JSON 容错只做兼容，不作为主流程依赖**

当前解析器兼容 Markdown JSON 代码块、旧 `[TOOL_CALL]`、多个 `[TOOL_CALL]`、双花括号、控制字符等历史输出形态。它的作用是降低模型输出波动带来的失败率，不鼓励提示词继续要求模型输出混合格式。

推荐输出原则：

- 特定阶段需要结构化数据时，只返回该阶段 schema 对应的 JSON。
- 普通总结阶段返回自然语言，不再强制 JSON。
- 工具调用由 `PlannedAction.tool` 和 `PlannedAction.args` 表达，不把工具调用混进正文。

**6. Skill Contract 从提示词片段升级为执行契约**

Skill Contract 用来约束“何时使用、推荐工具、输出字段、验收条件、修复建议”，避免把某个任务的经验硬编码进通用 prompt。

```rust
pub struct SkillContract {
    pub when_to_use: Vec<String>,
    pub inputs: serde_json::Value,
    pub tools: Vec<String>,
    pub output_schema: serde_json::Value,
    pub validation: SkillValidationContract,
    pub repair_hints: Vec<String>,
}
```

**7. CLI 与 App 共用同一执行链路**

`nm agent "用户问题"` 走和前端会话一致的 Agent 执行能力，并输出：

- `Thinking Trace`：计划、工具、错误、修复、总结过程。
- `Final Answer`：给用户看的最终回复。
- `Result Data`：结构化结果，便于外部模型或脚本验证。

同一会话会带入历史上下文；超过上下文预算时启用压缩，避免重复提问和丢失用户已回答的信息。

---

## 📂 代码目录

### 整体结构

```
NiuMaBot/
├── niumabot/
│   ├── src/                    # 前端源码
│   │   ├── components/         # React 组件
│   │   ├── pages/              # 页面组件
│   │   ├── types/              # TypeScript 类型
│   │   └── App.tsx             # 应用入口
│   └── src-tauri/              # Rust 后端
│       ├── src/
│       │   ├── core/           # Agent / Team / Tools / Skills 核心能力
│       │   ├── interface/      # HTTP / Tauri / 外部接口
│       │   ├── infrastructure/ # 配置、存储、公共类型
│       │   ├── cli.rs          # nm agent CLI 入口
│       │   └── main.rs         # 程序入口
│       └── Cargo.toml          # Rust 依赖
├── scripts/                    # 自动化脚本
└── README.md                   # 项目说明
```

### 核心模块

**前端关键目录**：
- `pages/` - Teams, Chat, Models, Tools 等主要页面
- `components/` - StreamingTaskExecutor, MultiSelectDropdown 等可复用组件
- `types/` - TeamTypes, ConfigTypes 等接口定义

**后端关键目录**：

#### `core/team/` - 团队协作引擎
- **`executor.rs`** - 团队任务执行器 ⭐⭐⭐
  - ✅ 依赖检查与等待机制（`execute_sequential_with_streaming`）
  - ✅ 前序结果收集与传递（`previous_results`）
  - ✅ Leader 方法论级 TODO 拆分（`suggestions` / `success_criteria`）
  - ✅ 成员任务分配与结果汇总
  - ✅ 不再由 Leader 生成 recovery TODO，失败修复下沉到 Member/AgentLoop
  
- **`streaming.rs`** - 流式消息类型定义 ⭐⭐
  - ✅ `StreamMessage` 结构体（包含 executor 字段）
  - ✅ 标准化工具事件类型
  
- **`prompt.rs`** - LLM 提示词管理 ⭐⭐⭐
  - ✅ `LEADER_ANALYSIS_SYSTEM_PROMPT`（方法论级拆分、依赖、建议、验收条件）
  - ✅ `collaboration_task_user_prompt`（支持上下文增强）
  - ✅ 中文提示词 + 运行时工具/技能上下文注入

#### `core/agent/` - AgentLoop 阶段化执行 ⭐⭐⭐
- **`loop.rs`** - AgentLoop 核心执行逻辑
  - ✅ `Plan -> PlanReview -> Execute -> Evaluate -> Repair -> Summarize`
  - ✅ 工具执行失败后基于 stdout/stderr/error kind 自修复
  - ✅ 简单任务支持 `SingleAgentMode` 快速路径
  - ✅ 最终结果由 Member/AgentLoop 判定，Leader 不再追加补齐任务

- **`schema.rs`** - 阶段化结构定义
  - ✅ `ExecutionPlan` / `PlannedAction`
  - ✅ `EvaluationResult` / `RepairPlan` / `FinalAnswer`

- **`plan_review.rs`** - 执行前计划审查
  - ✅ 工具存在性检查
  - ✅ 参数 schema 检查
  - ✅ shell 嵌套与平台命令检查

- **`errors.rs`** - 结构化错误类型
  - ✅ `ModelOutputParseError` / `ToolNotFound` / `ToolArgsInvalid`
  - ✅ `ToolExecutionFailed` / `ToolTimeout` / `CompletionCriteriaNotMet`
  
- **`prompt.rs`** - Agent 提示词
  - ✅ 通用执行策略，不硬编码某个统计/目录场景
  - ✅ 优先使用运行时注入的工具说明和 Skill Contract
  - ✅ 需要工具时输出阶段化结构；总结阶段返回自然语言

#### `core/tools/` - 工具管理系统
- **`dynamic_tool.rs`** - 动态工具注册与管理
- **`command_tools.rs`** - `shell_command` 命令执行工具
  - ✅ 返回 stdout/stderr、parsed、artifact_refs
  - ✅ 长输出自动落 artifact，避免上下文污染
- **`project_tools.rs`** - `project_scan` 项目扫描工具
  - ✅ 文件统计、代码行数、按扩展名聚合
- **工具元数据管理** - 支持运行时注入、前端测试和 PlanReview 校验

#### `core/skills/` - 技能和 Skill Contract
- **`contract.rs`** - 技能契约定义
  - ✅ `when_to_use` / `tools` / `output_schema`
  - ✅ `validation.required_fields` / `success_criteria`
  - ✅ `repair_hints`
- **`parser.rs`** - 技能文件解析，支持把 contract 注入 Agent 上下文

#### `cli.rs` - CLI Agent 入口
- ✅ `nm agent "用户问题"` 命令入口
- ✅ 简单本地任务路由到 `SingleAgentMode`
- ✅ 输出 `Thinking Trace` / `Final Answer` / `Result Data`

#### `interface/` - 外部接口
- **`teams.rs`** - 团队管理 API
- **`messages.rs`** - 消息处理 API
- **HTTP/SSE/Webhook** - 前端、CLI 和外部系统共用后端能力

---

## 🛣️ 开发路线

### 已完成 (✅ P0)

- ✅ 模型管理（多提供商支持）
- ✅ 渠道管理（飞书已实现自动启停）
- ✅ Agent 模板管理
- ✅ 团队管理（Team + Leader + Members）
- ✅ 工具管理（内置工具 + MCP）
- ✅ 会话管理（历史查看、搜索）
- ✅ 定时任务（可视化配置 + AI 执行）
- ✅ 流式任务执行（标准化工具执行事件）
- ✅ 文件操作权限控制
- ✅ 全局状态管理（内存缓存）
- ✅ **团队协作引擎**（Todo 拆解、依赖管理、多方对齐、并发执行）
- ✅ **基于角色的权限控制**（工具/技能/MCP 访问控制）
- ✅ **团队目录结构**（独立目录、SOUL.md、JSONL 会话存储）
- ✅ **数据迁移工具**（自动从 teams.json 迁移到独立目录）
- ✅ **多步骤进度条工具**（配置化任务执行，实时进度跟踪）
- ✅ **Tauri API 开发模式 Mock**（Vite 开发环境兼容）
- ✅ **HTTP API 服务器**（统一处理 RESTful + SSE + Webhook + 定时任务）
- ✅ **SSE 流式事件系统**（标准化工具事件，智能消息合并）
- ✅ **统一设置页面**（7 标签页：模型、渠道、环境、技能、MCP、工具、系统）

### 进行中 (🚧 P1)

- 🚧 钉钉/企业微信/Slack渠道接入
- 🚧 更多内置工具
- 🚧 增强的错误处理和重试机制

### 规划中 (📋 P2)

- 📋 交易功能模块
- 📋 移动端应用
- 📋 插件市场
- 📋 云端同步
- 📋 高级数据分析面板

---


## 📚 更多文档

- **[START_HERE.md](START_HERE.md)** - 5 分钟快速开始 ⭐⭐⭐
- **[TEAM_COLLABORATION_ENGINE.md](niumabot/src-tauri/TEAM_COLLABORATION_ENGINE.md)** - 团队协作引擎详解
- **[DEVELOPMENT_GUIDE.md](DEVELOPMENT_GUIDE.md)** - 开发者指南

---

**最后更新**: 2026-04-05  
**版本**: v1.5.1  
**状态**: ✅ 核心功能完成 + 🧠 智能协作 + 🗂️ 团队目录 + 🔒 权限控制 + 🔄 模型参数统一传递 + 🎨 流式消息样式分层 + 🔧 多步进度条 + 🖥️ 开发模式支持 + 🏗️ 模块化架构 + 🌐 HTTP API 服务器 + ⚙️ 统一设置页面 + 📡 标准化工具事件 + 🔄 智能消息合并