From 01b93d9897133a8804e623866e4188dd0be80165 Mon Sep 17 00:00:00 2001
From: JackChen <jack_ai@qq.com>
Date: Thu, 2 Apr 2026 22:35:45 +0800
Subject: [PATCH] docs: lead Quick Start with runTeam, add output example and
 Node version

---
 README.md    | 63 ++++++++++++++++++++++++++++++----------------
 README_zh.md | 71 ++++++++++++++++++++++++++++++++++------------------
 2 files changed, 88 insertions(+), 46 deletions(-)

diff --git a/README.md b/README.md
index bb0c8f0..cc7400e 100644
--- a/README.md
+++ b/README.md
@@ -20,33 +20,15 @@ Build AI agent teams that decompose goals into tasks automatically. Define agent
 
 ## Quick Start
 
+Requires Node.js >= 18.
+
 ```bash
 npm install @jackchen_me/open-multi-agent
 ```
 
 Set `ANTHROPIC_API_KEY` (and optionally `OPENAI_API_KEY` or `GITHUB_TOKEN` for Copilot) in your environment.
 
-```typescript
-import { OpenMultiAgent } from '@jackchen_me/open-multi-agent'
-
-const orchestrator = new OpenMultiAgent({ defaultModel: 'claude-sonnet-4-6' })
-
-// One agent, one task
-const result = await orchestrator.runAgent(
-  {
-    name: 'coder',
-    model: 'claude-sonnet-4-6',
-    tools: ['bash', 'file_write'],
-  },
-  'Write a TypeScript function that reverses a string, save it to /tmp/reverse.ts, and run it.',
-)
-
-console.log(result.output)
-```
-
-## Multi-Agent Team
-
-This is where it gets interesting. Three agents, one goal:
+Three agents, one goal — the framework handles the rest:
 
 ```typescript
 import { OpenMultiAgent } from '@jackchen_me/open-multi-agent'
@@ -91,6 +73,23 @@ console.log(`Success: ${result.success}`)
 console.log(`Tokens: ${result.totalTokenUsage.output_tokens} output tokens`)
 ```
 
+What happens under the hood:
+
+```
+agent_start coordinator
+task_start architect
+task_complete architect
+task_start developer
+task_start developer              // independent tasks run in parallel
+task_complete developer
+task_start reviewer               // unblocked after implementation
+task_complete developer
+task_complete reviewer
+agent_complete coordinator        // synthesizes final result
+Success: true
+Tokens: 12847 output tokens
+```
+
 ## Three Ways to Run
 
 | Mode | Method | When to use |
@@ -107,6 +106,28 @@ console.log(`Tokens: ${result.totalTokenUsage.output_tokens} output tokens`)
 
 ## More Examples
 
+<details>
+<summary><b>Single Agent</b> — one agent, one prompt</summary>
+
+```typescript
+import { OpenMultiAgent } from '@jackchen_me/open-multi-agent'
+
+const orchestrator = new OpenMultiAgent({ defaultModel: 'claude-sonnet-4-6' })
+
+const result = await orchestrator.runAgent(
+  {
+    name: 'coder',
+    model: 'claude-sonnet-4-6',
+    tools: ['bash', 'file_write'],
+  },
+  'Write a TypeScript function that reverses a string, save it to /tmp/reverse.ts, and run it.',
+)
+
+console.log(result.output)
+```
+
+</details>
+
 <details>
 <summary><b>Task Pipeline</b> — explicit control over task graph and assignments</summary>
 
diff --git a/README_zh.md b/README_zh.md
index 27fc6c4..42129b0 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -20,37 +20,15 @@
 
 ## 快速开始
 
+需要 Node.js >= 18。
+
 ```bash
 npm install @jackchen_me/open-multi-agent
 ```
 
 在环境变量中设置 `ANTHROPIC_API_KEY`（以及可选的 `OPENAI_API_KEY` 或用于 Copilot 的 `GITHUB_TOKEN`）。
 
-```typescript
-import { OpenMultiAgent } from '@jackchen_me/open-multi-agent'
-
-const orchestrator = new OpenMultiAgent({ defaultModel: 'claude-sonnet-4-6' })
-
-// 一个智能体，一个任务
-const result = await orchestrator.runAgent(
-  {
-    name: 'coder',
-    model: 'claude-sonnet-4-6',
-    tools: ['bash', 'file_write'],
-  },
-  'Write a TypeScript function that reverses a string, save it to /tmp/reverse.ts, and run it.',
-)
-
-console.log(result.output)
-```
-
-## 作者
-
-> JackChen — 前 WPS 产品经理，现独立创业者。关注小红书[「杰克西｜硅基杠杆」](https://www.xiaohongshu.com/user/profile/5a1bdc1e4eacab4aa39ea6d6)，持续获取我的 AI Agent 观点和思考。
-
-## 多智能体团队
-
-这才是有意思的地方。三个智能体，一个目标：
+三个智能体，一个目标——框架处理剩下的一切：
 
 ```typescript
 import { OpenMultiAgent } from '@jackchen_me/open-multi-agent'
@@ -95,6 +73,27 @@ console.log(`成功: ${result.success}`)
 console.log(`Token 用量: ${result.totalTokenUsage.output_tokens} output tokens`)
 ```
 
+执行过程：
+
+```
+agent_start coordinator
+task_start architect
+task_complete architect
+task_start developer
+task_start developer              // 无依赖的任务并行执行
+task_complete developer
+task_start reviewer               // 实现完成后自动解锁
+task_complete developer
+task_complete reviewer
+agent_complete coordinator        // 综合所有结果
+Success: true
+Tokens: 12847 output tokens
+```
+
+## 作者
+
+> JackChen — 前 WPS 产品经理，现独立创业者。关注小红书[「杰克西｜硅基杠杆」](https://www.xiaohongshu.com/user/profile/5a1bdc1e4eacab4aa39ea6d6)，持续获取我的 AI Agent 观点和思考。
+
 ## 三种运行模式
 
 | 模式 | 方法 | 适用场景 |
@@ -111,6 +110,28 @@ console.log(`Token 用量: ${result.totalTokenUsage.output_tokens} output tokens
 
 ## 更多示例
 
+<details>
+<summary><b>单智能体</b> — 一个智能体，一个提示词</summary>
+
+```typescript
+import { OpenMultiAgent } from '@jackchen_me/open-multi-agent'
+
+const orchestrator = new OpenMultiAgent({ defaultModel: 'claude-sonnet-4-6' })
+
+const result = await orchestrator.runAgent(
+  {
+    name: 'coder',
+    model: 'claude-sonnet-4-6',
+    tools: ['bash', 'file_write'],
+  },
+  'Write a TypeScript function that reverses a string, save it to /tmp/reverse.ts, and run it.',
+)
+
+console.log(result.output)
+```
+
+</details>
+
 <details>
 <summary><b>任务流水线</b> — 显式控制任务图和分配</summary>