# 4torm — 多 Agent 协作平台

4torm 是一个本地部署的 AI Agent 协作平台。你可以创建多个 Agent，让它们独立对话、组队群聊、按工作流协作，或按时间表自动执行任务。所有数据存储在本地文件系统，不依赖外部服务（除 LLM API）。

## 一、设计哲学

4torm 的出发点很简单：感觉Agent更可以像一种员工，而不是一个又一个用完就扔的对话窗口。

正如一个公司的组织方式——老板招了一帮人，每个人有自己的专长、自己的工位、自己的工作习惯。有的活儿一个人干就行，有的得拉几个人开会讨论，有的得按流程一步步接力，有的得每天定时巡查。人是固定的那批人，变的只是"今天用什么方式协作"。

因此我也希望让 AI Agent 也这样工作。

4torm 里的 Agent 不是某次任务里临时捏出来的角色——它是你认真配好提示词、选好模型、装好工具之后长期存在的一个"人"。今天它在对话里帮你查资料，明天同一个它被拉进工作流做审校，后天它被定时任务唤醒写日报。能力配一次，哪里需要往哪里调。

这就是我说的**复用**。

另一个是**灵活**。我不想把所有问题都塞进一种范式里。简单的事情一对一聊就行，需要多角度的就开群聊，有明确流程的就画工作流，重复性的就挂自动化。四种模式不是四个产品，是组织同一批人的四种方式。你按任务性质选最合适的就行。

相比市面上各类聊天或 vibe coding 框架，总觉得有种"不灵活"——不是它们不好，而是各自只解决一种场景的问题。聊天的只能聊天，编排的只能编排，自动化的只能自动化。但真实的工作不只一种形态，不可能所有事都靠一个对话窗口搞定，也不可能所有事都画成流程图。4torm 想做的就是把这些能力收拢到同一套 Agent 体系下：同一批人，按需切换协作方式，仅此而已。

## 二、平台定位

- **本地优先**：数据全部落盘，无云端依赖
- **多 Agent**：不止一个 Agent——它们可以分工、讨论、委托
- **多模式**：从简单对话到复杂工作流，按需选择协作深度
- **可扩展**：工具和技能系统允许 Agent 获得新能力

## 三、四大协作模式

| 模式 | 代号 | 适用场景 | 引导文档 |
|------|------|----------|----------|
| **对话** | 季风（Chat） | 单 Agent 多轮对话，工具调用，子任务委托 | `chat-guide` |
| **群聊** | 对流（Convection） | 多 Agent 圆桌讨论，人类主持，会长参谋 | `convection-guide` |
| **工作流** | 信风（TradeWind） | 可视化画布编排 DAG，Agent 节点串/并联执行 | `tradewind-guide` |
| **自动化** | 潮汐（Tide） | 定时触发，Agent 按节奏自主执行，滚动归档 | `tide-guide` |

### 模式选择建议

```
需要 Agent 帮你做一件事？         → 季风（对话）
需要多个 Agent 讨论出结论？       → 对流（群聊）
需要多个 Agent 按顺序接力完成？   → 信风（工作流）
需要 Agent 定时自动巡检/汇报？    → 潮汐（自动化）
```

## 四、核心概念

### Agent

Agent 是平台的基本工作单元。每个 Agent 拥有：

- **角色提示词**（role-prompt.md）：定义身份、能力边界、行为规范
- **模型配置**：指定 LLM 提供商和模型
- **工具列表**：可调用的工具集合
- **技能列表**：可按需加载的专业知识模块
- **独立工作区**：文件读写的沙箱目录

### ReAct 循环

所有模式共享同一套执行引擎：

```
接收任务 → 思考(think) → 行动(action/工具调用) → 观察(result) → 循环
         → 直到输出最终回答(answer)
```

### 工具（Tool）

Agent 与外部世界交互的能力。内置工具包括文件读写、目录浏览、命令执行、网页抓取等。支持自定义扩展。详见 `tools-reference`。

### 技能（Skill）

Agent 的领域专长模块。通过 `use_skill` 工具按需加载专业提示词，不占用常驻上下文。支持携带专属工具。详见 `skills-reference`。

## 五、技术架构

```
┌─────────────────────────────────────────────────┐
│                  浏览器 (Vite + React 19)         │
│                                                   │
│  季风页面 │ 对流页面 │ 信风画布 │ 潮汐面板 │ 控制台  │
└────────────────────────┬────────────────────────┘
                         │ HTTP / SSE
┌────────────────────────┴────────────────────────┐
│              服务端 (Fastify + TypeScript)        │
│                                                   │
│  路由层: /api/chat, /api/convection,              │
│          /api/tradewind, /api/tide                │
│                                                   │
│  引擎层: SessionRunner, ReAct Loop,              │
│          WorkflowRunner, TideScheduler            │
│                                                   │
│  共享层: agent-lock, llm-bridge, tool-executor   │
└────────────────────────┬────────────────────────┘
                         │
┌────────────────────────┴────────────────────────┐
│              LLM 提供商 (OpenAI 兼容接口)         │
│              DeepSeek / OpenAI / Claude / 本地    │
└─────────────────────────────────────────────────┘
```

### 技术栈

| 层 | 技术 |
|----|------|
| 前端 | React 19 + Vite + XY Flow（画布） |
| 服务端 | Fastify 5 + TypeScript + tsx（热重载） |
| LLM 通信 | 原生 fetch，OpenAI Chat Completions 兼容格式 |
| 数据存储 | 文件系统 JSON（无数据库） |
| 进程模型 | 单进程，前后端 `concurrently` 并发启动 |

## 六、数据目录结构

```
data/
├── agents/
│   ├── registry.json              ← Agent 注册表（元数据 + 状态）
│   └── {agentId}/
│       ├── .workspace/
│       │   ├── config.json        ← 模型、温度、工具、技能配置
│       │   └── role-prompt.md     ← 角色提示词
│       ├── sessions/              ← 季风对话历史
│       └── sessions-tide/         ← 潮汐专用会话（按任务隔离）
│
├── convection/
│   └── sessions/                  ← 对流群聊会话
│
├── tradewind/
│   ├── workflows/                 ← 工作流定义（graph.json + meta.json）
│   └── runs/                      ← 运行归档（events + 节点消息 + 输出）
│
├── tide/
│   ├── tasks.json                 ← 潮汐任务配置
│   └── runs/                      ← 运行记录（每次一个 JSON）
│
├── tools/
│   ├── registry.json              ← 工具定义注册表
│   ├── executors/                 ← 工具执行器（.js）
│   └── permissions.json           ← 工具权限
│
├── skills/
│   └── {skillId}/
│       ├── config.json            ← 技能元数据
│       ├── SKILL.md               ← 专业提示词
│       ├── tools.json             ← （可选）专属工具
│       └── executors/             ← （可选）专属执行器
│
└── providers.json                 ← LLM 提供商配置（含 API key，已 gitignore）
```

## 七、快速开始

### 环境要求

- Node.js 18+
- npm（随 Node 附带）

### 启动

```bash
# 安装依赖
npm install
cd server && npm install && cd ..

# 启动开发服务器（前端 + 后端同时启动）
npm run dev
```

浏览器访问 `http://localhost:5173`。

### 首次配置

1. **添加提供商**：进入控制台 → 提供商管理 → 填入 API endpoint 和 key
2. **创建 Agent**：控制台 → 新建 Agent → 选模型、写提示词、勾选工具
3. **开始对话**：侧栏切到「季风」→ 选 Agent → 发消息

## 八、模块间关系

```
                    ┌──────────┐
                    │  Agent   │  ← 所有模式共享同一套 Agent 实体
                    └────┬─────┘
         ┌───────────────┼───────────────┐
         │               │               │
    ┌────▼────┐    ┌─────▼─────┐   ┌─────▼─────┐
    │  季风   │    │   对流    │   │   信风    │
    │ (1对1)  │    │ (多Agent) │   │ (工作流) │
    └────┬────┘    └───────────┘   └─────┬─────┘
         │                               │
         │         ┌───────────┐         │
         └────────►│   潮汐    │◄────────┘
                   │ (定时驱动) │
                   └───────────┘
```

- **季风**是基础——所有模式的 Agent 执行都复用 `SessionRunner` + ReAct 循环
- **对流**是季风的多人版——多个 Agent 共享公共上下文
- **信风**是编排层——通过 DAG 定义 Agent 间的数据流转顺序
- **潮汐**是时间驱动层——复用季风的执行能力，加上调度器和归档

### 共享基础设施

| 组件 | 职责 |
|------|------|
| `agent-lock` | Agent 互斥锁，防止同一 Agent 被并发驱动 |
| `llm-bridge` | 统一的 LLM 调用层（流式/非流式，token 统计） |
| `tool-executor` | 工具执行派发（注册表查找 → 执行器加载 → 沙箱校验） |
| `prompt-builder` | 系统提示词构建（角色 + 工具列表 + 输出模板） |

## 九、安全与隔离

- **沙箱级别**：Agent 文件操作受沙箱限制（strict / relaxed / unrestricted）
- **工具权限**：危险工具（写文件、执行命令）可配置 always / ask / never
- **API key 隔离**：`providers.json` 在 `.gitignore` 中，不入仓库
- **Agent 互斥锁**：防止同一 Agent 被多个任务/会话同时驱动导致状态污染
- **LLM 并发限制**：全局最大 3 路并发调用（信号量队列）

## 十、文档索引

| 文档 | 内容 |
|------|------|
| `chat-guide` | 季风对话操作：创建 Agent、对话、委托、会话管理 |
| `convection-guide` | 对流群聊操作：创建会话、发言、会长私聊、动态管理 |
| `tradewind-guide` | 信风工作流操作：画布编排、节点配置、运行、会议室 |
| `tide-guide` | 潮汐自动化操作：任务创建、调度、自循环、归档策略 |
| `tools-reference` | 工具构建：ToolDef 接口、执行器编写、权限系统 |
| `skills-reference` | 技能构建：SKILL.md 编写、专属工具、加载机制 |
