chore: trim README stale facts and tighten examples section (#126)
* chore: trim README of stale facts and tighten examples section - Drop the "41 source files" tagline. The count drifts every time we add a file, and lower-bound trivia is not what someone reading the README needs in the first 10 lines. - Update the coverage badge to 85% to match the actual `vitest run --coverage` output (was 88%, written by hand and stale). - Rebalance the Examples highlights from 8 lines to 7. The previous list listed three providers individually (`minimax`, `deepseek`, `groq`) which read like a wall, replaced with one umbrella bullet pointing at `examples/providers/`. The standalone Ollama bullet is now covered by the same umbrella. - Replaced "Examples" in the Contributing section with a more specific "Production examples" pointer to the new `examples/production/README.md` acceptance criteria, so the new category has a real entry point for would-be contributors. Both English and Chinese READMEs updated in parallel. * chore: de-AI README prose and strip em-dashes Remove em-dashes from both READMEs and rewrite the Chinese version's translation-ese sections (vs. comparisons, philosophy paragraph, bold feature-benefit bullets) with more natural phrasing.
This commit is contained in:
JackChen
GitHub
parent
ffec13e915
commit
7adb065ea3
39
README.md
39
README.md
|
|
@ -4,12 +4,10 @@ The lightweight multi-agent orchestration engine for TypeScript. Three runtime d
|
|||
|
||||
CrewAI is Python. LangGraph makes you draw the graph by hand. `open-multi-agent` is the `npm install` you drop into an existing Node.js backend when you need a team of agents to work on a goal together. Nothing more, nothing less.
|
||||
|
||||
3 runtime dependencies · 41 source files · Deploys anywhere Node.js runs
|
||||
|
||||
[](https://github.com/JackChen-me/open-multi-agent/stargazers)
|
||||
[](./LICENSE)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](https://github.com/JackChen-me/open-multi-agent/actions)
|
||||
[](https://github.com/JackChen-me/open-multi-agent/actions)
|
||||
|
||||
**English** | [中文](./README_zh.md)
|
||||
|
||||
|
|
@ -65,20 +63,20 @@ Requires Node.js >= 18.
|
|||
npm install @jackchen_me/open-multi-agent
|
||||
```
|
||||
|
||||
Set the API key for your provider. Local models via Ollama require no API key — see [`providers/ollama`](examples/providers/ollama.ts).
|
||||
Set the API key for your provider. Local models via Ollama require no API key. See [`providers/ollama`](examples/providers/ollama.ts).
|
||||
|
||||
- `ANTHROPIC_API_KEY`
|
||||
- `OPENAI_API_KEY`
|
||||
- `GEMINI_API_KEY`
|
||||
- `XAI_API_KEY` (for Grok)
|
||||
- `MINIMAX_API_KEY` (for MiniMax)
|
||||
- `MINIMAX_BASE_URL` (for MiniMax — optional, selects endpoint)
|
||||
- `MINIMAX_BASE_URL` (for MiniMax, optional, selects endpoint)
|
||||
- `DEEPSEEK_API_KEY` (for DeepSeek)
|
||||
- `GITHUB_TOKEN` (for Copilot)
|
||||
|
||||
**CLI (`oma`).** For shell and CI, the package exposes a JSON-first binary. See [docs/cli.md](./docs/cli.md) for `oma run`, `oma task`, `oma provider`, exit codes, and file formats.
|
||||
|
||||
Three agents, one goal — the framework handles the rest:
|
||||
Three agents, one goal. The framework handles the rest:
|
||||
|
||||
```typescript
|
||||
import { OpenMultiAgent } from '@jackchen_me/open-multi-agent'
|
||||
|
|
@ -105,7 +103,7 @@ const team = orchestrator.createTeam('api-team', {
|
|||
sharedMemory: true,
|
||||
})
|
||||
|
||||
// Describe a goal — the framework breaks it into tasks and orchestrates execution
|
||||
// Describe a goal. The framework breaks it into tasks and orchestrates execution
|
||||
const result = await orchestrator.runTeam(team, 'Create a REST API for a todo list in /tmp/todo-api/')
|
||||
|
||||
console.log(`Success: ${result.success}`)
|
||||
|
|
@ -133,7 +131,7 @@ Tokens: 12847 output tokens
|
|||
|
||||
| Mode | Method | When to use |
|
||||
|------|--------|-------------|
|
||||
| Single agent | `runAgent()` | One agent, one prompt — simplest entry point |
|
||||
| Single agent | `runAgent()` | One agent, one prompt. Simplest entry point |
|
||||
| Auto-orchestrated team | `runTeam()` | Give a goal, framework plans and executes |
|
||||
| Explicit pipeline | `runTasks()` | You define the task graph and assignments |
|
||||
|
||||
|
|
@ -141,16 +139,15 @@ For MapReduce-style fan-out without task dependencies, use `AgentPool.runParalle
|
|||
|
||||
## Examples
|
||||
|
||||
[`examples/`](./examples/) is organized by category — basics, providers, patterns, integrations, and production. See [`examples/README.md`](./examples/README.md) for the full index. Highlights:
|
||||
[`examples/`](./examples/) is organized by category: basics, providers, patterns, integrations, and production. See [`examples/README.md`](./examples/README.md) for the full index. Highlights:
|
||||
|
||||
- [`basics/team-collaboration`](examples/basics/team-collaboration.ts): `runTeam()` coordinator pattern.
|
||||
- [`providers/ollama`](examples/providers/ollama.ts): Ollama and Claude in one pipeline via `baseURL`.
|
||||
- [`patterns/structured-output`](examples/patterns/structured-output.ts): any agent returns Zod-validated JSON.
|
||||
- [`patterns/agent-handoff`](examples/patterns/agent-handoff.ts): synchronous sub-agent delegation via `delegate_to_agent`.
|
||||
- [`integrations/trace-observability`](examples/integrations/trace-observability.ts): `onTrace` spans for LLM calls, tools, and tasks.
|
||||
- [`integrations/mcp-github`](examples/integrations/mcp-github.ts): expose an MCP server's tools to an agent via `connectMCPTools()`.
|
||||
- [`providers/minimax`](examples/providers/minimax.ts), [`providers/deepseek`](examples/providers/deepseek.ts), [`providers/groq`](examples/providers/groq.ts): three-agent teams on each provider.
|
||||
- [`integrations/with-vercel-ai-sdk`](examples/integrations/with-vercel-ai-sdk/): Next.js app — OMA `runTeam()` + AI SDK `useChat` streaming.
|
||||
- [`integrations/with-vercel-ai-sdk`](examples/integrations/with-vercel-ai-sdk/): Next.js app combining OMA `runTeam()` with AI SDK `useChat` streaming.
|
||||
- **Provider examples**: eight three-agent teams (one per supported provider) under [`examples/providers/`](examples/providers/).
|
||||
|
||||
Run scripts with `npx tsx examples/basics/team-collaboration.ts`.
|
||||
|
||||
|
|
@ -284,7 +281,7 @@ const agent: AgentConfig = {
|
|||
|
||||
Long tool outputs can blow up conversation size and cost. Two controls work together.
|
||||
|
||||
**Truncation** — cap an individual tool result to a head + tail excerpt with a marker in between:
|
||||
**Truncation.** Cap an individual tool result to a head + tail excerpt with a marker in between:
|
||||
|
||||
```typescript
|
||||
const agent: AgentConfig = {
|
||||
|
|
@ -299,7 +296,7 @@ const bigQueryTool = defineTool({
|
|||
})
|
||||
```
|
||||
|
||||
**Post-consumption compression** — once the agent has acted on a tool result, compress older copies in the transcript so they stop costing input tokens on every subsequent turn. Error results are never compressed.
|
||||
**Post-consumption compression.** Once the agent has acted on a tool result, compress older copies in the transcript so they stop costing input tokens on every subsequent turn. Error results are never compressed.
|
||||
|
||||
```typescript
|
||||
const agent: AgentConfig = {
|
||||
|
|
@ -372,9 +369,9 @@ Pairs well with `compressToolResults` and `maxToolOutputChars` above.
|
|||
| DeepSeek | `provider: 'deepseek'` | `DEEPSEEK_API_KEY` | Verified |
|
||||
| GitHub Copilot | `provider: 'copilot'` | `GITHUB_TOKEN` | Verified |
|
||||
| Gemini | `provider: 'gemini'` | `GEMINI_API_KEY` | Verified |
|
||||
| Ollama / vLLM / LM Studio | `provider: 'openai'` + `baseURL` | — | Verified |
|
||||
| Ollama / vLLM / LM Studio | `provider: 'openai'` + `baseURL` | none | Verified |
|
||||
| Groq | `provider: 'openai'` + `baseURL` | `GROQ_API_KEY` | Verified |
|
||||
| llama.cpp server | `provider: 'openai'` + `baseURL` | — | Verified |
|
||||
| llama.cpp server | `provider: 'openai'` + `baseURL` | none | Verified |
|
||||
|
||||
Gemini requires `npm install @google/genai` (optional peer dependency).
|
||||
|
||||
|
|
@ -406,7 +403,7 @@ const localAgent: AgentConfig = {
|
|||
|
||||
**Troubleshooting:**
|
||||
- Model not calling tools? Ensure it appears in Ollama's [Tools category](https://ollama.com/search?c=tools). Not all models support tool-calling.
|
||||
- Using Ollama? Update to the latest version (`ollama update`) — older versions have known tool-calling bugs.
|
||||
- Using Ollama? Update to the latest version (`ollama update`). Older versions have known tool-calling bugs.
|
||||
- Proxy interfering? Use `no_proxy=localhost` when running against local servers.
|
||||
|
||||
### LLM Configuration Examples
|
||||
|
|
@ -420,7 +417,7 @@ const grokAgent: AgentConfig = {
|
|||
}
|
||||
```
|
||||
|
||||
(Set your `XAI_API_KEY` environment variable — no `baseURL` needed.)
|
||||
(Set your `XAI_API_KEY` environment variable, no `baseURL` needed.)
|
||||
|
||||
```typescript
|
||||
const minimaxAgent: AgentConfig = {
|
||||
|
|
@ -453,8 +450,8 @@ Set `DEEPSEEK_API_KEY`. Available models: `deepseek-chat` (DeepSeek-V3, recommen
|
|||
|
||||
Issues, feature requests, and PRs are welcome. Some areas where contributions would be especially valuable:
|
||||
|
||||
- **Examples** — Real-world workflows and use cases.
|
||||
- **Documentation** — Guides, tutorials, and API docs.
|
||||
- **Production examples.** Real-world end-to-end workflows. See [`examples/production/README.md`](./examples/production/README.md) for the acceptance criteria and submission format.
|
||||
- **Documentation.** Guides, tutorials, and API docs.
|
||||
|
||||
## Contributors
|
||||
|
||||
|
|
@ -474,7 +471,7 @@ Issues, feature requests, and PRs are welcome. Some areas where contributions wo
|
|||
|
||||
## Translations
|
||||
|
||||
Help translate this README — [open a PR](https://github.com/JackChen-me/open-multi-agent/pulls).
|
||||
Help translate this README. [Open a PR](https://github.com/JackChen-me/open-multi-agent/pulls).
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
154
README_zh.md
154
README_zh.md
|
|
@ -1,61 +1,56 @@
|
|||
# Open Multi-Agent
|
||||
|
||||
面向 TypeScript 的轻量多智能体编排引擎。3 个运行时依赖，零配置，一次 `runTeam()` 调用从目标到结果。
|
||||
TypeScript 里的轻量多智能体编排引擎。3 个运行时依赖，零配置，一次 `runTeam()` 从目标拿到结果。
|
||||
|
||||
CrewAI 是 Python。LangGraph 需要你自己画图。`open-multi-agent` 是你现有 Node.js 后端里 `npm install` 一下就能用的那一层。当你需要让一支 agent 团队围绕一个目标协作时，只提供这个，不多不少。
|
||||
|
||||
3 个运行时依赖 · 41 个源文件 · Node.js 能跑的地方都能部署
|
||||
CrewAI 是 Python。LangGraph 要你自己画图。`open-multi-agent` 是你现有 Node.js 后端里 `npm install` 一下就能用的那一层：一支 agent 团队围绕一个目标协作，就这些。
|
||||
|
||||
[](https://github.com/JackChen-me/open-multi-agent/stargazers)
|
||||
[](./LICENSE)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](https://github.com/JackChen-me/open-multi-agent/actions)
|
||||
[](https://github.com/JackChen-me/open-multi-agent/actions)
|
||||
|
||||
[English](./README.md) | **中文**
|
||||
|
||||
## 你真正得到的三件事
|
||||
## 核心能力
|
||||
|
||||
- **一次调用从目标到结果。** `runTeam(team, "构建一个 REST API")` 启动一个协调者 agent，把目标拆成任务 DAG，解析依赖，独立任务并行执行，最终合成输出。不需要画图，不需要手动连任务。
|
||||
- **TypeScript 原生，3 个运行时依赖。** `@anthropic-ai/sdk`、`openai`、`zod`。这就是全部运行时。可嵌入 Express、Next.js、Serverless 函数或 CI/CD 流水线。没有 Python 运行时，没有子进程桥接，没有云端 sidecar。
|
||||
- **多模型团队。** Claude、GPT、Gemini、Grok、MiniMax、DeepSeek、Copilot，或任何 OpenAI 兼容的本地模型（Ollama、vLLM、LM Studio、llama.cpp）可以在同一个团队中使用。让架构师用 Opus 4.6，开发者用 GPT-5.4，评审用本地的 Gemma 4，一次 `runTeam()` 调用全部搞定。Gemini 作为 optional peer dependency 提供：使用前需 `npm install @google/genai`。
|
||||
- `runTeam(team, "构建一个 REST API")` 下去，协调者 agent 会把目标拆成任务 DAG，独立任务并行跑，再把结果合起来。不用画图，不用手动连依赖。
|
||||
- 运行时依赖就三个：`@anthropic-ai/sdk`、`openai`、`zod`。能直接塞进 Express、Next.js、Serverless 或 CI/CD，不起 Python 进程，也不跑云端 sidecar。
|
||||
- 同一个团队里的 agent 能挂不同模型：架构师用 Opus 4.6、开发用 GPT-5.4、评审跑本地 Gemma 4 都行。支持 Claude、GPT、Gemini、Grok、MiniMax、DeepSeek、Copilot，以及 OpenAI 兼容的本地模型（Ollama、vLLM、LM Studio、llama.cpp）。用 Gemini 要额外装 `@google/genai`。
|
||||
|
||||
其他能力（MCP 集成、上下文策略、结构化输出、任务重试、人机协同、生命周期钩子、循环检测、可观测性）在下方章节和 [`examples/`](./examples/) 里。
|
||||
还有 MCP、上下文策略、结构化输出、任务重试、human-in-the-loop、生命周期 hook、循环检测、可观测性等，下面章节或 [`examples/`](./examples/) 里都有。
|
||||
|
||||
## 哲学：我们做什么，不做什么
|
||||
## 做什么，不做什么
|
||||
|
||||
我们的目标是做 TypeScript 生态里最简单的多智能体框架。简单不等于封闭。框架的长期价值不在于功能清单的长度，而在于它连接的网络有多大。
|
||||
|
||||
**我们做：**
|
||||
**做的事：**
|
||||
- 一个协调者，把目标拆成任务 DAG。
|
||||
- 一个任务队列，独立任务并行执行，失败级联到下游。
|
||||
- 一个任务队列，独立任务并行跑，失败级联到下游。
|
||||
- 共享内存和消息总线，让 agent 之间能看到彼此的输出。
|
||||
- 多模型团队，每个 agent 可以用不同的 LLM provider。
|
||||
- 多模型团队，每个 agent 可以挂不同的 LLM provider。
|
||||
|
||||
**我们不做：**
|
||||
- **Agent Handoffs。** 如果 agent A 需要把对话中途交接给 agent B，去用 [OpenAI Agents SDK](https://github.com/openai/openai-agents-python)。在我们的模型里，每个 agent 完整负责自己的任务，不会中途交接。
|
||||
- **状态持久化 / 检查点。** 短期内不做。加存储后端会打破 3 个依赖的承诺，而且我们的工作流执行时间是秒到分钟级，不是小时级。如果真实使用场景转向长时间工作流，我们会重新评估。
|
||||
**不做的事：**
|
||||
- **Agent handoffs**：agent A 对话中途把控制权交给 agent B 这种模式不做。要这个用 [OpenAI Agents SDK](https://github.com/openai/openai-agents-python)。我们这边一个 agent 从头到尾负责一个任务。
|
||||
- **状态持久化 / 检查点**：暂时不做。加存储后端会破坏 3 个依赖的承诺，而且我们的工作流是秒到分钟级，不是小时级。真有长时间工作流的需求再说。
|
||||
|
||||
**正在跟踪：**
|
||||
- **A2A 协议。** 观望中，等生产级采纳到位再行动。
|
||||
A2A 协议在跟踪，观望中，等有人真用再跟。
|
||||
|
||||
完整理由见 [`DECISIONS.md`](./DECISIONS.md)。
|
||||
|
||||
## 和 X 有什么不同？
|
||||
## 和其他框架怎么选
|
||||
|
||||
**vs. [LangGraph JS](https://github.com/langchain-ai/langgraphjs)。** LangGraph 是声明式图编排：你定义节点、边、条件路由，然后 `compile()` + `invoke()`。`open-multi-agent` 是目标驱动：你声明团队和目标，协调者在运行时把目标拆成任务 DAG。LangGraph 给你完全的拓扑控制（适合固定的生产工作流）。这个框架代码更少、迭代更快（适合探索型多智能体协作）。LangGraph 还有成熟的检查点能力，我们没有。
|
||||
如果你在看 [LangGraph JS](https://github.com/langchain-ai/langgraphjs)：它是声明式图编排，自己定义节点、边、路由，`compile()` + `invoke()`。`open-multi-agent` 反过来，目标驱动：给一个团队和一个目标，协调者在运行时拆 DAG。想完全控拓扑、流程定下来的用 LangGraph；想写得少、迭代快、还在探索的选这个。LangGraph 有成熟 checkpoint，我们没做。
|
||||
|
||||
**vs. [CrewAI](https://github.com/crewAIInc/crewAI)。** CrewAI 是成熟的 Python 选择。如果你的技术栈是 Python，用 CrewAI。`open-multi-agent` 是 TypeScript 原生：3 个运行时依赖，直接嵌入 Node.js，不需要子进程桥接。编排能力大致相当，按语言契合度选。
|
||||
Python 栈直接用 [CrewAI](https://github.com/crewAIInc/crewAI) 就行，编排层能力差不多。`open-multi-agent` 的定位是 TypeScript 原生：3 个依赖、直接进 Node.js、不用子进程桥接。按语言选。
|
||||
|
||||
**vs. [Vercel AI SDK](https://github.com/vercel/ai)。** AI SDK 是 LLM 调用层：统一的 TypeScript 客户端，支持 60+ provider，带流式、tool calls、结构化输出。它不做多智能体编排。`open-multi-agent` 需要多 agent 时叠在它之上。两者互补：单 agent 用 AI SDK，需要团队用这个。
|
||||
和 [Vercel AI SDK](https://github.com/vercel/ai) 不冲突。AI SDK 是 LLM 调用层，统一的 TypeScript 客户端，60+ provider，带流式、tool call、结构化输出，但不做多智能体编排。要多 agent，把 `open-multi-agent` 叠在 AI SDK 上面就行。单 agent 用 AI SDK，多 agent 用这个。
|
||||
|
||||
## 谁在用
|
||||
|
||||
`open-multi-agent` 是一个新项目（2026-04-01 发布，MIT 许可，5,500+ stars）。生态还在成形，下面这份列表很短，但都真实：
|
||||
项目 2026-04-01 发布，目前 5,500+ stars，MIT 协议。目前能确认在用的：
|
||||
|
||||
- **[temodar-agent](https://github.com/xeloxa/temodar-agent)**（约 50 stars）。WordPress 安全分析平台，作者 [Ali Sünbül](https://github.com/xeloxa)。在 Docker runtime 里直接使用我们的内置工具（`bash`、`file_*`、`grep`）。已确认生产环境使用。
|
||||
- **家用服务器 Cybersecurity SOC。** 本地完全离线运行 Qwen 2.5 + DeepSeek Coder（通过 Ollama），在 Wazuh + Proxmox 上构建自主 SOC 流水线。早期用户，未公开。
|
||||
- **[temodar-agent](https://github.com/xeloxa/temodar-agent)**（约 50 stars）。WordPress 安全分析平台，作者 [Ali Sünbül](https://github.com/xeloxa)。在 Docker runtime 里直接用我们的内置工具（`bash`、`file_*`、`grep`）。已确认生产环境使用。
|
||||
- **家用服务器 Cybersecurity SOC。** 本地完全离线跑 Qwen 2.5 + DeepSeek Coder（通过 Ollama），在 Wazuh + Proxmox 上搭自主 SOC 流水线。早期用户，未公开。
|
||||
|
||||
你在生产环境或 side project 里用 `open-multi-agent` 吗？[开一个 Discussion](https://github.com/JackChen-me/open-multi-agent/discussions)，我们会把你列上来。
|
||||
如果你在生产或 side project 里用了 `open-multi-agent`，[请开个 Discussion](https://github.com/JackChen-me/open-multi-agent/discussions)，我加上来。
|
||||
|
||||
## 快速开始
|
||||
|
||||
|
|
@ -65,20 +60,20 @@ CrewAI 是 Python。LangGraph 需要你自己画图。`open-multi-agent` 是你
|
|||
npm install @jackchen_me/open-multi-agent
|
||||
```
|
||||
|
||||
根据使用的 Provider 设置对应的 API key。通过 Ollama 使用本地模型无需 API key — 参见 [`providers/ollama`](examples/providers/ollama.ts)。
|
||||
根据用的 provider 设对应 API key。通过 Ollama 跑本地模型不用 key，见 [`providers/ollama`](examples/providers/ollama.ts)。
|
||||
|
||||
- `ANTHROPIC_API_KEY`
|
||||
- `OPENAI_API_KEY`
|
||||
- `GEMINI_API_KEY`
|
||||
- `XAI_API_KEY`（Grok）
|
||||
- `MINIMAX_API_KEY`（MiniMax）
|
||||
- `MINIMAX_BASE_URL`（MiniMax — 可选，用于选择接入端点）
|
||||
- `MINIMAX_BASE_URL`（MiniMax，可选，选接入端点）
|
||||
- `DEEPSEEK_API_KEY`（DeepSeek）
|
||||
- `GITHUB_TOKEN`（Copilot）
|
||||
|
||||
**CLI (`oma`)。** 面向 shell 和 CI，包自带一个 JSON-first 的二进制。`oma run`、`oma task`、`oma provider`、退出码和文件格式见 [docs/cli.md](./docs/cli.md)。
|
||||
包里还自带一个叫 `oma` 的命令行工具，给 shell 和 CI 场景用，输出都是 JSON。`oma run`、`oma task`、`oma provider`、退出码、文件格式都在 [docs/cli.md](./docs/cli.md) 里。
|
||||
|
||||
三个智能体，一个目标——框架处理剩下的一切：
|
||||
下面用三个 agent 协作做一个 REST API：
|
||||
|
||||
```typescript
|
||||
import { OpenMultiAgent } from '@jackchen_me/open-multi-agent'
|
||||
|
|
@ -105,7 +100,7 @@ const team = orchestrator.createTeam('api-team', {
|
|||
sharedMemory: true,
|
||||
})
|
||||
|
||||
// 描述一个目标——框架将其拆解为任务并编排执行
|
||||
// 描述一个目标，框架负责拆解成任务并编排执行
|
||||
const result = await orchestrator.runTeam(team, 'Create a REST API for a todo list in /tmp/todo-api/')
|
||||
|
||||
console.log(`Success: ${result.success}`)
|
||||
|
|
@ -133,26 +128,25 @@ Tokens: 12847 output tokens
|
|||
|
||||
| 模式 | 方法 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| 单智能体 | `runAgent()` | 一个智能体，一个提示词——最简入口 |
|
||||
| 单智能体 | `runAgent()` | 一个智能体，一个提示词，最简入口 |
|
||||
| 自动编排团队 | `runTeam()` | 给一个目标，框架自动规划和执行 |
|
||||
| 显式任务管线 | `runTasks()` | 你自己定义任务图和分配 |
|
||||
|
||||
如果需要 MapReduce 风格的扇出而不涉及任务依赖，直接使用 `AgentPool.runParallel()`。参见 [`patterns/fan-out-aggregate`](examples/patterns/fan-out-aggregate.ts)。
|
||||
要 MapReduce 风格的 fan-out 但不需要任务依赖，直接用 `AgentPool.runParallel()`。例子见 [`patterns/fan-out-aggregate`](examples/patterns/fan-out-aggregate.ts)。
|
||||
|
||||
## 示例
|
||||
|
||||
[`examples/`](./examples/) 按类别组织——basics、providers、patterns、integrations、production。完整索引见 [`examples/README.md`](./examples/README.md)。推荐起步：
|
||||
[`examples/`](./examples/) 按类别分了 basics、providers、patterns、integrations、production。完整索引见 [`examples/README.md`](./examples/README.md)，几个值得先看的：
|
||||
|
||||
- [`basics/team-collaboration`](examples/basics/team-collaboration.ts)：`runTeam()` 协调者模式。
|
||||
- [`providers/ollama`](examples/providers/ollama.ts)：通过 `baseURL` 把 Ollama 和 Claude 放在同一条管线。
|
||||
- [`patterns/structured-output`](examples/patterns/structured-output.ts)：任意 agent 产出 Zod 校验过的 JSON。
|
||||
- [`patterns/agent-handoff`](examples/patterns/agent-handoff.ts)：`delegate_to_agent` 同步子智能体委派。
|
||||
- [`integrations/trace-observability`](examples/integrations/trace-observability.ts)：`onTrace` 回调，为 LLM 调用、工具、任务发出结构化 span。
|
||||
- [`integrations/mcp-github`](examples/integrations/mcp-github.ts)：通过 `connectMCPTools()` 把 MCP 服务器的工具暴露给 agent。
|
||||
- [`providers/minimax`](examples/providers/minimax.ts)、[`providers/deepseek`](examples/providers/deepseek.ts)、[`providers/groq`](examples/providers/groq.ts)：各 provider 的三智能体团队。
|
||||
- [`integrations/with-vercel-ai-sdk`](examples/integrations/with-vercel-ai-sdk/)：Next.js 应用 — OMA `runTeam()` + AI SDK `useChat` 流式输出。
|
||||
- [`integrations/trace-observability`](examples/integrations/trace-observability.ts)：`onTrace` 回调，给 LLM 调用、工具、任务发结构化 span。
|
||||
- [`integrations/mcp-github`](examples/integrations/mcp-github.ts)：用 `connectMCPTools()` 把 MCP 服务器的工具暴露给 agent。
|
||||
- [`integrations/with-vercel-ai-sdk`](examples/integrations/with-vercel-ai-sdk/)：Next.js 应用，OMA `runTeam()` 配合 AI SDK `useChat` 流式输出。
|
||||
- **Provider 示例**：8 个三智能体团队示例，每个 provider 一个，见 [`examples/providers/`](examples/providers/)。
|
||||
|
||||
用 `npx tsx examples/basics/team-collaboration.ts` 运行脚本示例。
|
||||
跑脚本用 `npx tsx examples/basics/team-collaboration.ts`。
|
||||
|
||||
## 架构
|
||||
|
||||
|
|
@ -203,20 +197,20 @@ Tokens: 12847 output tokens
|
|||
|
||||
| 工具 | 说明 |
|
||||
|------|------|
|
||||
| `bash` | 执行 Shell 命令。返回 stdout + stderr。支持超时和工作目录设置。 |
|
||||
| `file_read` | 读取指定绝对路径的文件内容。支持偏移量和行数限制以处理大文件。 |
|
||||
| `bash` | 跑 Shell 命令。返回 stdout + stderr。支持超时和工作目录设置。 |
|
||||
| `file_read` | 按绝对路径读文件。支持偏移量和行数限制，能读大文件。 |
|
||||
| `file_write` | 写入或创建文件。自动创建父目录。 |
|
||||
| `file_edit` | 通过精确字符串匹配编辑文件。 |
|
||||
| `grep` | 使用正则表达式搜索文件内容。优先使用 ripgrep，回退到 Node.js 实现。 |
|
||||
| `file_edit` | 按精确字符串匹配改文件。 |
|
||||
| `grep` | 用正则搜文件内容。优先走 ripgrep，没有就 fallback 到 Node.js。 |
|
||||
| `glob` | 按 glob 模式查找文件。返回按修改时间排序的匹配路径。 |
|
||||
|
||||
## 工具配置
|
||||
|
||||
可以通过预设、白名单和黑名单对 agent 的工具访问进行精细控制。
|
||||
三层叠起来用：preset（预设）、tools（白名单）、disallowedTools（黑名单）。
|
||||
|
||||
### 工具预设
|
||||
|
||||
为常见场景预定义的工具组合：
|
||||
三种内置 preset：
|
||||
|
||||
```typescript
|
||||
const readonlyAgent: AgentConfig = {
|
||||
|
|
@ -240,8 +234,6 @@ const fullAgent: AgentConfig = {
|
|||
|
||||
### 高级过滤
|
||||
|
||||
将预设与白名单、黑名单组合，实现精确控制：
|
||||
|
||||
```typescript
|
||||
const customAgent: AgentConfig = {
|
||||
name: 'custom',
|
||||
|
|
@ -256,9 +248,9 @@ const customAgent: AgentConfig = {
|
|||
|
||||
### 自定义工具
|
||||
|
||||
两种方式给 agent 装一个不在内置工具集里的工具。
|
||||
装一个不在内置集里的工具，有两种方式。
|
||||
|
||||
**配置时注入**：通过 `AgentConfig.customTools` 传入。适合编排层统一挂工具的场景。这里定义的工具会绕过 preset / 白名单过滤，但仍受 `disallowedTools` 约束。
|
||||
**配置时注入。** 通过 `AgentConfig.customTools` 传入。编排层统一挂工具的时候用这个。这里定义的工具会绕过 preset 和白名单，但仍受 `disallowedTools` 限制。
|
||||
|
||||
```typescript
|
||||
import { defineTool } from '@jackchen_me/open-multi-agent'
|
||||
|
|
@ -278,13 +270,13 @@ const agent: AgentConfig = {
|
|||
}
|
||||
```
|
||||
|
||||
**运行时注册**：`agent.addTool(tool)`。这种方式添加的工具始终可用，不受任何过滤规则影响。
|
||||
**运行时注册。** `agent.addTool(tool)`。这种方式加的工具始终可用，不受任何过滤规则影响。
|
||||
|
||||
### 工具输出控制
|
||||
|
||||
工具返回过长会迅速撑大对话体积和成本。两个控制点互相配合。
|
||||
工具返回太长会快速撑大对话和成本。两个开关配合着用。
|
||||
|
||||
**截断** — 把单次工具结果压到 head + tail 摘要（中间放一个标记）：
|
||||
**截断。** 把单次工具结果压成 head + tail 摘要（中间放一个标记）：
|
||||
|
||||
```typescript
|
||||
const agent: AgentConfig = {
|
||||
|
|
@ -299,7 +291,7 @@ const bigQueryTool = defineTool({
|
|||
})
|
||||
```
|
||||
|
||||
**消费后压缩** — agent 在后续轮次已经用完某个工具结果后，把历史副本压缩，避免每轮都重复消耗输入 token。错误结果永不压缩。
|
||||
**消费后压缩。** agent 用完某个工具结果之后，把历史副本压缩掉，后续每轮就不再重复消耗输入 token。错误结果不压缩。
|
||||
|
||||
```typescript
|
||||
const agent: AgentConfig = {
|
||||
|
|
@ -311,7 +303,7 @@ const agent: AgentConfig = {
|
|||
|
||||
### MCP 工具（Model Context Protocol）
|
||||
|
||||
`open-multi-agent` 可以连接任意 MCP 服务器，并把它的工具直接暴露给 agent。
|
||||
可以连任意 MCP 服务器，把它的工具直接给 agent 用。
|
||||
|
||||
```typescript
|
||||
import { connectMCPTools } from '@jackchen_me/open-multi-agent/mcp'
|
||||
|
|
@ -329,15 +321,15 @@ await disconnect()
|
|||
```
|
||||
|
||||
注意事项：
|
||||
- `@modelcontextprotocol/sdk` 是 optional peer dependency，只在用 MCP 时才需要装。
|
||||
- 当前仅支持 stdio transport。
|
||||
- MCP 的入参校验交给 MCP 服务器自身（`inputSchema` 是 `z.any()`）。
|
||||
- `@modelcontextprotocol/sdk` 是 optional peer dependency，只在用 MCP 时才要装。
|
||||
- 当前只支持 stdio transport。
|
||||
- MCP 的入参校验交给 MCP 服务器自己（`inputSchema` 是 `z.any()`）。
|
||||
|
||||
完整可运行示例见 [`integrations/mcp-github`](examples/integrations/mcp-github.ts)。
|
||||
完整例子见 [`integrations/mcp-github`](examples/integrations/mcp-github.ts)。
|
||||
|
||||
## 上下文管理
|
||||
|
||||
长时间运行的 agent 很容易撞上输入 token 上限。在 `AgentConfig` 上设置 `contextStrategy` 来控制对话在成长过程中如何收缩：
|
||||
长时间运行的 agent 很容易撞上输入 token 上限。在 `AgentConfig` 里设 `contextStrategy`，控制对话变长时怎么收缩：
|
||||
|
||||
```typescript
|
||||
const agent: AgentConfig = {
|
||||
|
|
@ -354,11 +346,11 @@ const agent: AgentConfig = {
|
|||
| 策略 | 什么时候用 |
|
||||
|------|------------|
|
||||
| `sliding-window` | 最省事。只保留最近 N 轮，其余丢弃。 |
|
||||
| `summarize` | 把老对话交给一个摘要模型，用摘要替代原文。 |
|
||||
| `summarize` | 老对话发给摘要模型，用摘要替代原文。 |
|
||||
| `compact` | 基于规则：截断过长的 assistant 文本块和 tool 结果，保留最近若干轮。不额外调用 LLM。 |
|
||||
| `custom` | 传入自己的 `compress(messages, estimatedTokens, ctx)` 函数。 |
|
||||
|
||||
搭配上面的 `compressToolResults` 和 `maxToolOutputChars` 使用效果更好。
|
||||
和上面的 `compressToolResults`、`maxToolOutputChars` 搭着用效果更好。
|
||||
|
||||
## 支持的 Provider
|
||||
|
||||
|
|
@ -372,25 +364,25 @@ const agent: AgentConfig = {
|
|||
| DeepSeek | `provider: 'deepseek'` | `DEEPSEEK_API_KEY` | 已验证 |
|
||||
| GitHub Copilot | `provider: 'copilot'` | `GITHUB_TOKEN` | 已验证 |
|
||||
| Gemini | `provider: 'gemini'` | `GEMINI_API_KEY` | 已验证 |
|
||||
| Ollama / vLLM / LM Studio | `provider: 'openai'` + `baseURL` | — | 已验证 |
|
||||
| Ollama / vLLM / LM Studio | `provider: 'openai'` + `baseURL` | 无 | 已验证 |
|
||||
| Groq | `provider: 'openai'` + `baseURL` | `GROQ_API_KEY` | 已验证 |
|
||||
| llama.cpp server | `provider: 'openai'` + `baseURL` | — | 已验证 |
|
||||
| llama.cpp server | `provider: 'openai'` + `baseURL` | 无 | 已验证 |
|
||||
|
||||
Gemini 需要 `npm install @google/genai`（optional peer dependency）。
|
||||
|
||||
已验证支持 tool-calling 的本地模型：**Gemma 4**（见 [`providers/gemma4-local`](examples/providers/gemma4-local.ts)）。
|
||||
|
||||
任何 OpenAI 兼容 API 均可通过 `provider: 'openai'` + `baseURL` 接入（Mistral、Qwen、Moonshot、Doubao 等）。Groq 已在 [`providers/groq`](examples/providers/groq.ts) 中验证。**Grok、MiniMax 和 DeepSeek 现已原生支持**，分别使用 `provider: 'grok'`、`provider: 'minimax'` 和 `provider: 'deepseek'`。
|
||||
OpenAI 兼容的 API 都能用 `provider: 'openai'` + `baseURL` 接（Mistral、Qwen、Moonshot、Doubao 等）。Groq 在 [`providers/groq`](examples/providers/groq.ts) 里验证过。Grok、MiniMax、DeepSeek 直接用 `provider: 'grok'`、`provider: 'minimax'`、`provider: 'deepseek'`，不用配 `baseURL`。
|
||||
|
||||
### 本地模型 Tool-Calling
|
||||
|
||||
框架支持通过 Ollama、vLLM、LM Studio 或 llama.cpp 运行的本地模型进行 tool-calling。Tool-calling 由这些服务通过 OpenAI 兼容 API 原生处理。
|
||||
Ollama、vLLM、LM Studio、llama.cpp 跑的本地模型也能 tool-calling，走的是这些服务自带的 OpenAI 兼容接口。
|
||||
|
||||
**已验证模型：** Gemma 4、Llama 3.1、Qwen 3、Mistral、Phi-4。完整列表见 [ollama.com/search?c=tools](https://ollama.com/search?c=tools)。
|
||||
|
||||
**兜底提取：** 如果本地模型以文本形式返回工具调用，而非使用 `tool_calls` 协议格式（常见于 thinking 模型或配置不当的服务），框架会自动从文本输出中提取。
|
||||
**兜底提取：** 本地模型如果以文本形式返回工具调用，而不是 `tool_calls` 协议格式（thinking 模型或配置不对的服务常见），框架会自动从文本里提取。
|
||||
|
||||
**超时设置：** 本地推理可能较慢。使用 `AgentConfig` 上的 `timeoutMs` 防止无限等待：
|
||||
**超时设置。** 本地推理可能慢。在 `AgentConfig` 里设 `timeoutMs`，避免一直卡住：
|
||||
|
||||
```typescript
|
||||
const localAgent: AgentConfig = {
|
||||
|
|
@ -405,9 +397,9 @@ const localAgent: AgentConfig = {
|
|||
```
|
||||
|
||||
**常见问题：**
|
||||
- 模型不调用工具？确保该模型出现在 Ollama 的 [Tools 分类](https://ollama.com/search?c=tools)中。并非所有模型都支持 tool-calling。
|
||||
- 使用 Ollama？更新到最新版（`ollama update`）——旧版本有已知的 tool-calling bug。
|
||||
- 代理干扰？本地服务使用 `no_proxy=localhost`。
|
||||
- 模型不调用工具？先确认它在 Ollama 的 [Tools 分类](https://ollama.com/search?c=tools) 里，不是所有模型都支持。
|
||||
- 把 Ollama 升到最新版（`ollama update`），旧版本有 tool-calling bug。
|
||||
- 代理挡住了？本地服务用 `no_proxy=localhost` 跳过代理。
|
||||
|
||||
### LLM 配置示例
|
||||
|
||||
|
|
@ -420,7 +412,7 @@ const grokAgent: AgentConfig = {
|
|||
}
|
||||
```
|
||||
|
||||
（设置 `XAI_API_KEY` 环境变量即可，无需 `baseURL`。）
|
||||
（设好 `XAI_API_KEY` 就行，不用配 `baseURL`。）
|
||||
|
||||
```typescript
|
||||
const minimaxAgent: AgentConfig = {
|
||||
|
|
@ -431,12 +423,12 @@ const minimaxAgent: AgentConfig = {
|
|||
}
|
||||
```
|
||||
|
||||
设置 `MINIMAX_API_KEY`。适配器通过 `MINIMAX_BASE_URL` 选择接入端点：
|
||||
设好 `MINIMAX_API_KEY`。端点用 `MINIMAX_BASE_URL` 选：
|
||||
|
||||
- `https://api.minimax.io/v1` 全球端点，默认
|
||||
- `https://api.minimaxi.com/v1` 中国大陆端点
|
||||
|
||||
也可在 `AgentConfig` 中直接传入 `baseURL` 覆盖环境变量。
|
||||
也可以直接在 `AgentConfig` 里传 `baseURL`，覆盖环境变量。
|
||||
|
||||
```typescript
|
||||
const deepseekAgent: AgentConfig = {
|
||||
|
|
@ -447,14 +439,14 @@ const deepseekAgent: AgentConfig = {
|
|||
}
|
||||
```
|
||||
|
||||
设置 `DEEPSEEK_API_KEY`。可用模型：`deepseek-chat`（DeepSeek-V3，推荐用于编码任务）和 `deepseek-reasoner`（思考模式）。
|
||||
设好 `DEEPSEEK_API_KEY`。两个模型：`deepseek-chat`（DeepSeek-V3，写代码选这个）和 `deepseek-reasoner`（思考模式）。
|
||||
|
||||
## 参与贡献
|
||||
|
||||
欢迎提 Issue、功能需求和 PR。以下方向的贡献尤其有价值：
|
||||
Issue、feature request、PR 都欢迎。特别想要：
|
||||
|
||||
- **示例** — 真实场景的工作流和用例。
|
||||
- **文档** — 指南、教程和 API 文档。
|
||||
- **生产级示例。** 端到端跑通的真实场景工作流。收录条件和提交格式见 [`examples/production/README.md`](./examples/production/README.md)。
|
||||
- **文档。** 指南、教程、API 文档。
|
||||
|
||||
## 贡献者
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue