Skill: lixiang1076/agent-swarm-ex (version 1.0.0)

--- name: agent-swarm description: 创建和编排多智能体集群完成复杂任务。当用户需要将复杂任务拆解给多个专业智能体并行或串行执行时使用此技能。适用场景：(1) 复杂项目需要多角色协作（规划、调研、编码、写作、设计、分析、审核）(2) 需要并行执行多个独立子任务以提高效率 (3) 需要专业分工以优化成本和质量。关键词：多智能体、Agent集群、任务编排、并行执行、智能体团队。 --- # Agent Swarm - 多智能体集群编排 ## 概述 此技能使你成为**智能体团队的指挥官**，能够根据任务复杂度智能调度多个专业智能体协同完成工作。 核心流程：分析任务 → 拆解子任务 → 选择合适的 Agent → 并行/串行执行 → 整合结果 ## 可用智能体团队 | Agent ID | Emoji | 角色定位 | 核心能力 | 可用工具 | |----------|-------|----------|----------|----------| | `pm` | 📋 | 规划者 | 需求分析、任务拆解、优先级排序 | read, write, edit, web_search, web_fetch, memory | | `researcher` | 🔍 | 信息猎手 | 广度搜索、交叉验证、结构化输出 | web_search, web_fetch, read, write, memory | | `coder` | 👨‍💻 | 代码工匠 | 编码、调试、测试、重构 | read, write, edit, exec, process | | `writer` | ✍️ | 文字工匠 | 文档、报告、文案、翻译 | read, write, edit, memory | | `designer` | 🎨 | 视觉创作者 | 配图、插画、数据可视化 | read, write | | `analyst` | 📊 | 数据侦探 | 数据处理、统计分析、趋势预测 | read, write, edit, exec | | `reviewer` | 🔎 | 质量守门人 | 代码审查、内容审核、合规检查 | read, memory | | `assistant` | 💬 | 沟通桥梁 | 简单问答、消息转发、提醒 | message, read, sessions_send | | `automator` | 🤖 | 效率大师 | 定时任务、网页自动化、脚本 | exec, process, cron, browser, read, write | ### 智能体人格速览 | 智能体 | 一句话定位 | 核心原则 | |--------|------------|----------| | 📋 pm | 把模糊需求变成清晰方案 | 用户视角、目标导向、优先级思维 | | 🔍 researcher | 找到别人找不到的资料 | 广度优先、多源验证、标注来源 | | 👨‍💻 coder | 写出优雅高效的程序 | 先理解再动手、简单优于复杂、可读性优先 | | ✍️ writer | 把信息变成有价值的内容 | 读者优先、结构清晰、言之有物 | | 🎨 designer | 让想法变成图像 | 目的明确、简洁清晰、风格一致 | | 📊 analyst | 从数字中发现故事 | 数据质量、假设驱动、洞察导向 | | 🔎 reviewer | 确保输出达到标准 | 客观公正、建设性反馈、不直接修改 | | 💬 assistant | 传递信息、快速响应 | 简洁明了、知道边界、友好礼貌 | | 🤖 automator | 让重复的事自动化 | ROI思维、稳定可靠、有监控 | ### 模型分配参考 | 智能体 | 模型 | 用于 | 说明 | |------|------|------|------| | main | AWS Claude Opus 4.6 | 任务编排中心 | 最强推理能力 | | pm | Azure GPT-5 | 规划、分析 | 综合能力强 | | researcher | Azure GPT-5-Mini | 搜索、调研 | 快速响应，成本低 | | coder | Azure GPT-5-Codex | 编程、调试 | 编程专用模型 | | writer | Azure GPT-5 | 写作、文档 | 语言能力强 | | designer | Bailian Qwen3-VL-Plus | 图像、配图 | 视觉生成模型 | | analyst | Azure GPT-5-Codex | 数据分析 | 数据处理+编程 | | reviewer | Azure O3 | 审查、审核 | 推理模型，逻辑严密 | | assistant | Azure GPT-5-Mini | 消息转发 | 快速响应 | | automator | Azure GPT-5-Codex | 自动化脚本 | 编程能力 | **成本优化原则**：简单任务用 Mini 模型，编程用 Codex，推理用 O3，视觉用 VL。 ## 编排流程 ### Step 1: 任务分析 ``` 收到任务 → 判断复杂度 ├── 简单任务 → 直接执行 └── 复杂任务 → 进入编排模式 ``` ### Step 2: 任务拆解 将复杂任务分解为独立子任务，明确： - 每个子任务的目标和输出格式 - 输入数据和上下文 - 依赖关系（哪些可并行，哪些需串行） ### Step 3: Agent 选择 根据子任务性质选择最合适的 Agent： | 任务类型 | 推荐智能体 | 说明 | |----------|------------|------| | 项目规划、需求分析 | 📋 pm | 输出任务列表和优先级 | | 信息搜集、资料整理 | 🔍 researcher | 多源搜索，结构化输出 | | 写代码、修bug、脚本 | 👨‍💻 coder | 可执行 shell 命令 | | 写文章、文档、报告 | ✍️ writer | 基于资料进行创作 | | 配图、插画、图表 | 🎨 designer | 图像生成 | | 数据分析、统计 | 📊 analyst | 可执行数据处理脚本 | | 代码审查、内容审核 | 🔎 reviewer | 只读，给出建议 | | 消息转发、简单问答 | 💬 assistant | 快速响应 | | 定时任务、自动化 | 🤖 automator | 可设置 cron | ### Step 4: 执行调度 使用 `sessions_spawn` 调度子智能体。spawn 是异步的，子任务完成后会自动回报结果。 **并行执行示例**（多个 spawn 同时派发，各自独立执行）： ```javascript // 在同一个回合内连续 spawn，这些任务会并行执行 // 子任务完成后各自回报，主 Agent 收集结果后汇总 // 方式 1: 直接连续 spawn sessions_spawn({ task: "搜索 LangChain 资料...", agentId: "researcher", label: "research-langchain" }) sessions_spawn({ task: "搜索 AutoGPT 资料...", agentId: "researcher", label: "research-autogpt" }) sessions_spawn({ task: "搜索 CrewAI 资料...", agentId: "researcher", label: "research-crewai" }) // 三个任务并行执行，分别回报结果 // 方式 2: 循环派发（更清晰） const frameworks = ["LangChain", "AutoGPT", "CrewAI"] frameworks.forEach(name => { sessions_spawn({ task: `搜索 ${name} 框架的特点、优缺点、适用场景，输出结构化总结到 /workspace/research/${name.toLowerCase()}.md`, agentId: "researcher", label: `research-${name.toLowerCase()}` }) }) // 子任务完成后自动回报，主 Agent 汇总所有结果 ``` **串行执行示例**（等待上一步结果再继续）： ```javascript // 串行需要等待前序任务完成，收到回报后再 spawn 下一个 // 流程：调研 → (等待回报) → 写作 → (等待回报) → 配图 → (等待回报) → 审核 // Step 1: 先派发调研任务 sessions_spawn({ task: "调研 AI Agent 框架...", agentId: "researcher" }) // 等待 researcher 回报结果... // Step 2: 收到调研结果后，派发写作任务 sessions_spawn({ task: "基于 /workspace/research/ 的调研资料，撰写对比分析文章...", agentId: "writer" }) // 等待 writer 回报... // Step 3: 文章完成后，派发配图任务 sessions_spawn({ task: "为文章生成配图...", agentId: "designer" }) ``` **混合编排示例**（先并行，后串行）： ```javascript // Phase 1: 并行调研（同时派发） sessions_spawn({ task: "搜索 LangChain...", agentId: "researcher", label: "r1" }) sessions_spawn({ task: "搜索 AutoGPT...", agentId: "researcher", label: "r2" }) sessions_spawn({ task: "搜索 CrewAI...", agentId: "researcher", label: "r3" }) // 等待 3 个调研任务都完成... // Phase 2: 串行处理（基于汇总结果） sessions_spawn({ task: "整合调研资料，撰写报告...", agentId: "writer" }) // 等待 writer 完成... sessions_spawn({ task: "审核报告质量...", agentId: "reviewer" }) ``` ### Step 5: 结果整合 - 收集所有子 Agent 的输出 - 整合、去重、格式化 - 输出最终交付物 - **必须输出执行统计**（见下方模板） ## 编排示例 ### 示例 1: 技术调研报告 ``` 用户: "调研主流 AI Agent 框架，写一篇对比分析文章" 编排方案: ├── 🔍 researcher × 3 (并行) │ ├── 搜索 LangChain - 整理功能、优缺点、案例 │ ├── 搜索 AutoGPT - 整理功能、优缺点、案例 │ └── 搜索 CrewAI - 整理功能、优缺点、案例 ├── ✍️ writer (串行，等调研完成) │ └── 整合资料，撰写对比分析文章 ├── 🎨 designer (串行) │ └── 生成框架对比图/架构图 └── 🔎 reviewer (串行) └── 审核文章质量，提出改进建议 ``` ### 示例 2: 代码项目 ``` 用户: "帮我重构这个项目的认证模块" 编排方案: ├── 📋 pm (可选) │ └── 分析需求，拆解重构步骤 ├── 👨‍💻 coder │ └── 分析现有代码，实现重构 └── 🔎 reviewer (串行) └── 代码审查，确保质量 ``` ### 示例 3: 数据分析报告 ``` 用户: "分析这份销售数据，生成月度报告" 编排方案: ├── 📊 analyst │ └── 数据清洗、统计分析、发现洞察 ├── ✍️ writer (串行) │ └── 撰写分析报告 └── 🎨 designer (串行) └── 生成数据可视化图表 ``` ### 示例 4: 自动化任务 ``` 用户: "帮我设置每天早上自动检查 GitHub trending" 编排方案: ├── 🤖 automator │ └── 编写脚本 + 设置 cron 定时任务 ``` ## 编排原则 1. **简单任务不过度编排** — 能直接做的就直接做，不要为了用而用 2. **合理并行** — 无依赖的任务并行执行，提高效率 3. **明确交接** — 子任务输出要清晰完整，便于下游使用 4. **失败处理** — 某个子任务失败时，决定重试还是跳过 5. **结果整合** — 最终输出要连贯，不是简单拼接 6. **成本意识** — 优先用便宜模型，复杂任务才用贵模型 ## 调用语法 ```javascript sessions_spawn({ task: "具体任务描述，包含必要的上下文和期望的输出格式", agentId: "researcher", // 指定 Agent ID model: "glm", // 可选，覆盖 Agent 默认模型 label: "task-name", // 可选，便于追踪 runTimeoutSeconds: 300 // 可选，超时时间（秒） }) ``` ### Task 描述最佳实践 ```markdown 好的 task 描述应包含： 1. 明确的目标 - 要做什么 2. 必要的上下文 - 背景信息 3. 输出要求 - 格式、保存位置 4. 约束条件 - 限制和注意事项 示例： "搜索 LangChain 框架的最新资料，整理以下内容： 1. 核心功能和架构 2. 优点和缺点 3. 典型使用案例 4. 与其他框架的对比 输出格式：Markdown 保存到：/workspace/research/langchain.md 语言：中文" ``` ## 任务完成统计 完成智能体团队协作任务后，**必须**输出统计信息： ```markdown ## 📊 智能体团队执行统计 ### 执行明细 | 智能体 | 任务 | 耗时 | Tokens (in/out) | 状态 | |--------|------|------|-----------------|------| | 🔍 researcher | LangChain调研 | 2m30s | 8k/1.2k | ✅ | | 🔍 researcher | AutoGPT调研 | 2m45s | 9k/1.0k | ✅ | | ✍️ writer | 撰写报告 | 3m12s | 15k/2.5k | ✅ | | 🎨 designer | 生成配图 | 45s | 2k/- | ✅ | ### 成本汇总 - **总耗时**: 9m12s（并行优化后实际: 6m30s） - **总 Tokens**: 34k input / 4.7k output - **实际成本**: $0.12 - **全用主模型成本**: $0.29 - **节省**: 59% ### 效率分析 - **并行任务数**: 2个 researcher 并行 - **串行节省**: 通过并行节省 ~2m45s ``` 详细模板见 [references/statistics-template.md](references/statistics-template.md) ## 智能体工作目录 每个智能体有独立的工作目录，包含其人格配置： ``` /workspace/agents/ ├── pm/ # 📋 产品经理 │ ├── SOUL.md # 人格定义 │ └── AGENTS.md # 工作规范 ├── researcher/ # 🔍 研究员 ├── coder/ # 👨‍💻 程序员 ├── writer/ # ✍️ 写作者 ├── designer/ # 🎨 设计师 ├── analyst/ # 📊 分析师 ├── reviewer/ # 🔎 审核员 ├── assistant/ # 💬 助手 └── automator/ # 🤖 自动化 ``` ## 智能体配置管理 使用 `agent_manager.py` 脚本管理智能体集群： ```bash # 列出所有智能体 python3 scripts/agent_manager.py list # 查看智能体详情 python3 scripts/agent_manager.py show researcher # 添加新智能体（使用模板） python3 scripts/agent_manager.py add my_agent --template researcher --name "我的智能体" --emoji "🚀" # 删除智能体（默认会备份） python3 scripts/agent_manager.py remove my_agent # 更新智能体配置 python3 scripts/agent_manager.py update my_agent --name "新名称" ``` ### 可用模板 | 模板 | 说明 | 默认模型 | |------|------|----------| | `default` | 通用智能体 | claude-opus-4 | | `researcher` | 研究调研 | glm-4 | | `coder` | 编程开发 | claude-opus-4 | | `writer` | 内容写作 | gemini-2.5-pro | ## 智能体经验记忆 每个智能体可以积累任务经验，用于提升后续任务的执行质量。 ### 经验记录结构 ``` /workspace/agents/<agent_id>/ └── memory/ ├── experience.md # 人类可读的经验记录 └── experience.json # 结构化经验数据 ``` ### 使用 experience_logger.py ```bash # 记录一条经验 python3 scripts/experience_logger.py log researcher "搜索技术资料时，英文关键词效果更好" --task "LangChain调研" # 查看智能体经验 python3 scripts/experience_logger.py show researcher --limit 10 # 生成经验摘要 python3 scripts/experience_logger.py summary researcher # 输出可注入 prompt 的经验（用于 spawn 时注入） python3 scripts/experience_logger.py inject researcher --limit 5 ``` ### 在任务中使用经验 **方法 1: 在 task 描述中注入经验** ```python # 获取历史经验 import subprocess result = subprocess.run( ["python3", "scripts/experience_logger.py", "inject", "researcher", "--limit", "5"], capture_output=True, text=True ) experiences = result.stdout # 在 spawn 时注入 sessions_spawn({ task: f"""搜索 xxx 资料... {experiences} """, agentId: "researcher" }) ``` **方法 2: 智能体主动读取经验** 在智能体的 AGENTS.md 中添加指引： ```markdown ## 任务前准备 执行任务前，先读取 memory/experience.md 中的历史经验。 ## 任务后总结 完成任务后，总结 1-3 条有效经验，记录到 memory/experience.md。 ``` ### 经验记录最佳实践 ✅ **好的经验记录**： - 具体可操作："搜索 GitHub 时加 language:python 过滤更精准" - 有因果关系："JSON 输出比纯文本更便于下游处理" - 针对性强："处理大文件时分块读取，避免内存溢出" ❌ **避免的记录**： - 太笼统："要认真工作" - 太具体："用户 A 喜欢蓝色"（除非是个性化智能体） - 重复已有的："要输出 Markdown 格式"（已在 AGENTS.md 中） ### 经验自动总结（推荐） 在每个智能体的 AGENTS.md 末尾添加： ```markdown ## 任务完成后 1. 检查输出是否符合要求 2. 总结本次任务中的有效经验（1-3 条） 3. 将经验追加到 memory/experience.md，格式： - [YYYY-MM-DD] 经验描述 (任务名称) ``` 这样智能体在完成任务后会自动总结经验，无需手动干预。 ## 配置与部署 如需配置新的智能体团队或添加新模型，请参阅 [references/setup-guide.md](references/setup-guide.md) 使用初始化脚本快速创建工作目录： ```bash python3 scripts/init_agents.py --base-path /workspace/agents ```

path: references/chj-private-config-template.json
content: {
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "workspace": "/workspace",
        "model": { "primary": "chj-private/aws-claude-opus-4-6" },
        "identity": {
          "name": "主智能体",
          "emoji": "🎯"
        },
        "subagents": {
          "allowAgents": [
            "pm", "researcher", "coder", "writer", "designer",
            "analyst", "reviewer", "assistant", "automator"
          ]
        }
      },
      {
        "id": "pm",
        "workspace": "/workspace/agents/pm",
        "model": { "primary": "chj-private/azure-gpt-5" },
        "identity": { "name": "产品经理", "emoji": "📋" },
        "tools": {
          "allow": ["read", "write", "edit", "web_search", "web_fetch", "memory_search", "memory_get"],
          "deny": ["exec", "process", "gateway", "browser", "message", "cron"]
        }
      },
      {
        "id": "researcher",
        "workspace": "/workspace/agents/researcher",
        "model": { "primary": "chj-private/azure-gpt-5-mini" },
        "identity": { "name": "研究员", "emoji": "🔍" },
        "tools": {
          "allow": ["web_search", "web_fetch", "read", "write", "memory_search", "memory_get"],
          "deny": ["exec", "process", "gateway", "browser", "message", "cron", "edit"]
        }
      },
      {
        "id": "coder",
        "workspace": "/workspace/agents/coder",
        "model": { "primary": "chj-private/azure-gpt-5-codex" },
        "identity": { "name": "程序员", "emoji": "👨‍💻" },
        "tools": {
          "allow": ["read", "write", "edit", "exec", "process"],
          "deny": ["web_search", "web_fetch", "browser", "message", "gateway", "cron"]
        }
      },
      {
        "id": "writer",
        "workspace": "/workspace/agents/writer",
        "model": { "primary": "chj-private/azure-gpt-5" },
        "identity": { "name": "写作者", "emoji": "✍️" },
        "tools": {
          "allow": ["read", "write", "edit", "memory_search", "memory_get"],
          "deny": ["exec", "process", "browser", "gateway", "message", "cron", "web_search", "web_fetch"]
        }
      },
      {
        "id": "designer",
        "workspace": "/workspace/agents/designer",
        "model": { "primary": "chj-private/bailian-qwen3-vl-plus" },
        "identity": { "name": "设计师", "emoji": "🎨" },
        "tools": {
          "allow": ["read", "write"],
          "deny": ["exec", "process", "browser", "gateway", "message", "edit", "cron", "web_search", "web_fetch"]
        }
      },
      {
        "id": "analyst",
        "workspace": "/workspace/agents/analyst",
        "model": { "primary": "chj-private/azure-gpt-5-codex" },
        "identity": { "name": "分析师", "emoji": "📊" },
        "tools": {
          "allow": ["read", "write", "edit", "exec"],
          "deny": ["browser", "gateway", "message", "web_search", "web_fetch", "cron", "process"]
        }
      },
      {
        "id": "reviewer",
        "workspace": "/workspace/agents/reviewer",
        "model": { "primary": "chj-private/azure-o3" },
        "identity": { "name": "审核员", "emoji": "🔎" },
        "tools": {
          "allow": ["read", "memory_search", "memory_get"],
          "deny": ["write", "edit", "exec", "process", "browser", "gateway", "message", "cron", "web_search", "web_fetch"]
        }
      },
      {
        "id": "assistant",
        "workspace": "/workspace/agents/assistant",
        "model": { "primary": "chj-private/azure-gpt-5-mini" },
        "identity": { "name": "助手", "emoji": "💬" },
        "tools": {
          "allow": ["message", "read", "sessions_send"],
          "deny": ["write", "edit", "exec", "process", "browser", "gateway", "cron", "web_search", "web_fetch"]
        }
      },
      {
        "id": "automator",
        "workspace": "/workspace/agents/automator",
        "model": { "primary": "chj-private/azure-gpt-5-codex" },
        "identity": { "name": "自动化", "emoji": "🤖" },
        "tools": {
          "allow": ["exec", "process", "cron", "browser", "read", "write"],
          "deny": ["message", "gateway", "web_search", "web_fetch"]
        }
      }
    ]
  }
}


path: references/chj-private-guide.md
content: # CHJ-Private 模型配置指南

本指南专门针对使用 **chj-private** 提供商的用户，提供最优的模型选择方案。

## 模型选择策略

我们根据每个智能体的核心任务特点，从 chj-private 提供商中精心挑选了最适合的模型：

| 智能体 | 模型 ID | 选择理由 |
|--------|---------|----------|
| 🎯 **main** (主智能体) | `aws-claude-opus-4-6` | 最强推理和编排能力，适合复杂任务分解 |
| 📋 **pm** (规划者) | `azure-gpt-5` | 综合能力强，适合需求分析和项目规划 |
| 🔍 **researcher** (研究员) | `azure-gpt-5-mini` | 快速响应，成本低，适合信息搜索和整理 |
| 👨‍💻 **coder** (程序员) | `azure-gpt-5-codex` | 编程专用模型，代码质量高 |
| ✍️ **writer** (写作者) | `azure-gpt-5` | 语言能力强，适合文档写作 |
| 🎨 **designer** (设计师) | `bailian-qwen3-vl-plus` | 视觉生成模型，支持图像处理 |
| 📊 **analyst** (分析师) | `azure-gpt-5-codex` | 数据处理+编程能力，适合数据分析 |
| 🔎 **reviewer** (审核员) | `azure-o3` | 推理模型，逻辑严密，适合代码审查 |
| 💬 **assistant** (助手) | `azure-gpt-5-mini` | 快速响应，适合简单问答和消息转发 |
| 🤖 **automator** (自动化) | `azure-gpt-5-codex` | 编程能力强，适合编写自动化脚本 |

## 快速配置步骤

### 步骤 1: 复制配置模板

将 `chj-private-config-template.json` 中的 `agents.list` 配置复制到你的 `~/.openclaw/openclaw.json` 文件中。

```bash
# 查看模板配置
cat /workspace/.agents/skills/agent-swarm/references/chj-private-config-template.json

# 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

# 编辑配置文件
# 将模板中的 agents.list 部分合并到你的 openclaw.json
```

### 步骤 2: 确认 chj-private 提供商配置

确保你的 `openclaw.json` 中已经配置了 `chj-private` 提供商：

```json
{
  "models": {
    "providers": {
      "chj-private": {
        "baseUrl": "http://127.0.0.1:8765/v1",
        "api": "openai-completions",
        "apiKey": "proxy-handled",
        "models": [
          // ... 你的模型列表
        ]
      }
    }
  }
}
```

### 步骤 3: 创建智能体工作目录

```bash
# 使用初始化脚本创建目录
python3 /workspace/.agents/skills/agent-swarm/scripts/init_agents.py --base-path /workspace/agents

# 脚本会自动创建以下目录：
# /workspace/agents/pm/
# /workspace/agents/researcher/
# /workspace/agents/coder/
# /workspace/agents/writer/
# /workspace/agents/designer/
# /workspace/agents/analyst/
# /workspace/agents/reviewer/
# /workspace/agents/assistant/
# /workspace/agents/automator/
```

### 步骤 4: 重启 Gateway

```bash
openclaw gateway restart
```

### 步骤 5: 验证配置

```bash
# 查看智能体列表
openclaw agents list

# 应该显示所有 9 个智能体及其配置的模型
```

## 模型能力对照表

| 模型系列 | 适用场景 | 特点 |
|---------|----------|------|
| **Azure GPT-5** | 通用任务 | 综合能力强，平衡性好 |
| **Azure GPT-5-Codex** | 编程任务 | 代码生成、数据处理、自动化脚本 |
| **Azure GPT-5-Mini** | 快速任务 | 响应快，成本低，适合简单任务 |
| **Azure O3** | 推理任务 | 逻辑严密，适合审查、复杂推理 |
| **Bailian Qwen3-VL-Plus** | 视觉任务 | 图像理解和生成 |
| **AWS Claude Opus 4.6** | 复杂编排 | 最强推理能力，任务编排 |

## 成本优化建议

1. **分级使用模型**
   - 简单任务（搜索、转发）→ Azure GPT-5-Mini
   - 编程任务（代码、分析、自动化）→ Azure GPT-5-Codex
   - 通用任务（规划、写作）→ Azure GPT-5
   - 推理任务（审查、复杂决策）→ Azure O3
   - 视觉任务（配图、图表）→ Bailian Qwen3-VL-Plus
   - 编排任务（主智能体）→ AWS Claude Opus 4.6

2. **并行执行提高效率**
   - 多个 researcher 同时搜索不同主题
   - 独立的子任务并行处理，缩短总时间

3. **避免过度编排**
   - 简单任务不要分解成多个子任务
   - 能一次完成的不要分两次

## 使用示例

### 示例 1: 技术调研项目

```javascript
// 并行搜索多个框架（使用 azure-gpt-5-mini，快速且便宜）
["LangChain", "AutoGPT", "CrewAI"].forEach(name => {
  sessions_spawn({
    task: `搜索 ${name} 框架的特点、优缺点、适用场景，输出到 /workspace/research/${name.toLowerCase()}.md`,
    agentId: "researcher", // 自动使用 azure-gpt-5-mini
    label: `research-${name.toLowerCase()}`
  })
})

// 等待调研完成后，使用 writer 整合（使用 azure-gpt-5）
sessions_spawn({
  task: "基于 /workspace/research/ 中的资料，撰写框架对比分析文章",
  agentId: "writer" // 自动使用 azure-gpt-5
})

// 最后使用 reviewer 审核（使用 azure-o3，推理能力强）
sessions_spawn({
  task: "审核文章质量，检查逻辑严密性和完整性",
  agentId: "reviewer" // 自动使用 azure-o3
})
```

### 示例 2: 代码重构项目

```javascript
// 使用 coder 重构代码（使用 azure-gpt-5-codex）
sessions_spawn({
  task: "重构 /workspace/src/auth.js，提取公共逻辑，添加错误处理",
  agentId: "coder" // 自动使用 azure-gpt-5-codex
})

// 使用 reviewer 审查代码（使用 azure-o3）
sessions_spawn({
  task: "审查重构后的代码，检查安全性、可读性和最佳实践",
  agentId: "reviewer" // 自动使用 azure-o3
})
```

### 示例 3: 数据分析报告

```javascript
// 使用 analyst 分析数据（使用 azure-gpt-5-codex）
sessions_spawn({
  task: "分析 /workspace/data/sales.csv，计算关键指标，发现趋势",
  agentId: "analyst" // 自动使用 azure-gpt-5-codex
})

// 使用 writer 撰写报告（使用 azure-gpt-5）
sessions_spawn({
  task: "基于分析结果，撰写月度销售分析报告",
  agentId: "writer" // 自动使用 azure-gpt-5
})

// 使用 designer 生成图表（使用 bailian-qwen3-vl-plus）
sessions_spawn({
  task: "生成销售趋势图和数据可视化图表",
  agentId: "designer" // 自动使用 bailian-qwen3-vl-plus
})
```

## 常见问题

### Q: 如何临时覆盖某个智能体的默认模型？

A: 在 `sessions_spawn` 调用时指定 `model` 参数：

```javascript
sessions_spawn({
  task: "特别复杂的代码审查任务",
  agentId: "reviewer",
  model: "chj-private/aws-claude-opus-4-6" // 临时使用更强的模型
})
```

### Q: 如何查看当前智能体使用的模型？

A: 使用命令行工具：

```bash
openclaw agents list
```

### Q: 某个模型不可用怎么办？

A: 检查以下几点：
1. 确认 `chj-private` 提供商的 baseUrl 可访问
2. 确认模型 ID 在 `openclaw.json` 的 `models` 列表中
3. 检查 gateway 日志：`openclaw gateway logs`

### Q: 如何添加新的智能体？

A: 参考 [setup-guide.md](setup-guide.md) 中的智能体管理部分，或使用脚本：

```bash
python3 /workspace/.agents/skills/agent-swarm/scripts/agent_manager.py add my_agent \
  --name "我的智能体" \
  --emoji "🚀" \
  --model "chj-private/azure-gpt-5"
```

## 相关资源

- [完整配置指南](setup-guide.md) - 深入了解智能体配置
- [SKILL.md](../SKILL.md) - 技能使用说明
- [智能体管理脚本](../scripts/agent_manager.py) - 配置管理工具

## 反馈与支持

如果你在使用过程中遇到问题或有改进建议，欢迎反馈。


path: references/setup-guide.md
content: # 多智能体系统配置指南

本指南帮助你配置和部署完整的多智能体团队。

## 一、架构概览

```
主智能体 (main) - 🎯 AWS Claude Opus 4.6 - 任务编排中心
    │ sessions_spawn
    ├── 📋 pm        (Azure GPT-5)       → 规划者
    ├── 🔍 researcher (Azure GPT-5-Mini) → 信息猎手（快速）
    ├── 👨‍💻 coder     (Azure GPT-5-Codex) → 代码工匠（编程专用）
    ├── ✍️ writer    (Azure GPT-5)       → 文字工匠
    ├── 🎨 designer  (Qwen3-VL-Plus)     → 视觉创作者
    ├── 📊 analyst   (Azure GPT-5-Codex) → 数据侦探
    ├── 🔎 reviewer  (Azure O3)          → 质量守门人（推理）
    ├── 💬 assistant (Azure GPT-5-Mini)  → 沟通桥梁（快速）
    └── 🤖 automator (Azure GPT-5-Codex) → 效率大师（编程）
```

## 二、快速配置步骤

### 步骤 1：创建智能体工作目录

```bash
# 使用初始化脚本
python3 /workspace/openclaw/skills/agent-swarm/scripts/init_agents.py --base-path /workspace/agents

# 或手动创建
mkdir -p /workspace/agents/{pm,researcher,coder,writer,designer,analyst,reviewer,assistant,automator}
```

### 步骤 2：更新 openclaw.json 配置

在 `~/.openclaw/openclaw.json` 的 `agents` 部分添加配置：

```json
{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "workspace": "/workspace",
        "identity": {
          "name": "主智能体",
          "emoji": "🎯"
        },
        "subagents": {
          "allowAgents": [
            "pm", "researcher", "coder", "writer", "designer",
            "analyst", "reviewer", "assistant", "automator"
          ]
        }
      },
      {
        "id": "pm",
        "workspace": "/workspace/agents/pm",
        "model": { "primary": "chj-private/azure-gpt-5" },
        "identity": { "name": "产品经理", "emoji": "📋" },
        "tools": {
          "allow": ["read", "write", "edit", "web_search", "web_fetch", "memory_search", "memory_get"],
          "deny": ["exec", "process", "gateway", "browser", "message", "cron"]
        }
      },
      {
        "id": "researcher",
        "workspace": "/workspace/agents/researcher",
        "model": { "primary": "chj-private/azure-gpt-5-mini" },
        "identity": { "name": "研究员", "emoji": "🔍" },
        "tools": {
          "allow": ["web_search", "web_fetch", "read", "write", "memory_search", "memory_get"],
          "deny": ["exec", "process", "gateway", "browser", "message", "cron", "edit"]
        }
      },
      {
        "id": "coder",
        "workspace": "/workspace/agents/coder",
        "model": { "primary": "chj-private/azure-gpt-5-codex" },
        "identity": { "name": "程序员", "emoji": "👨‍💻" },
        "tools": {
          "allow": ["read", "write", "edit", "exec", "process"],
          "deny": ["web_search", "web_fetch", "browser", "message", "gateway", "cron"]
        }
      },
      {
        "id": "writer",
        "workspace": "/workspace/agents/writer",
        "model": { "primary": "chj-private/azure-gpt-5" },
        "identity": { "name": "写作者", "emoji": "✍️" },
        "tools": {
          "allow": ["read", "write", "edit", "memory_search", "memory_get"],
          "deny": ["exec", "process", "browser", "gateway", "message", "cron", "web_search", "web_fetch"]
        }
      },
      {
        "id": "designer",
        "workspace": "/workspace/agents/designer",
        "model": { "primary": "chj-private/bailian-qwen3-vl-plus" },
        "identity": { "name": "设计师", "emoji": "🎨" },
        "tools": {
          "allow": ["read", "write"],
          "deny": ["exec", "process", "browser", "gateway", "message", "edit", "cron", "web_search", "web_fetch"]
        }
      },
      {
        "id": "analyst",
        "workspace": "/workspace/agents/analyst",
        "model": { "primary": "chj-private/azure-gpt-5-codex" },
        "identity": { "name": "分析师", "emoji": "📊" },
        "tools": {
          "allow": ["read", "write", "edit", "exec"],
          "deny": ["browser", "gateway", "message", "web_search", "web_fetch", "cron", "process"]
        }
      },
      {
        "id": "reviewer",
        "workspace": "/workspace/agents/reviewer",
        "model": { "primary": "chj-private/azure-o3" },
        "identity": { "name": "审核员", "emoji": "🔎" },
        "tools": {
          "allow": ["read", "memory_search", "memory_get"],
          "deny": ["write", "edit", "exec", "process", "browser", "gateway", "message", "cron", "web_search", "web_fetch"]
        }
      },
      {
        "id": "assistant",
        "workspace": "/workspace/agents/assistant",
        "model": { "primary": "chj-private/azure-gpt-5-mini" },
        "identity": { "name": "助手", "emoji": "💬" },
        "tools": {
          "allow": ["message", "read", "sessions_send"],
          "deny": ["write", "edit", "exec", "process", "browser", "gateway", "cron", "web_search", "web_fetch"]
        }
      },
      {
        "id": "automator",
        "workspace": "/workspace/agents/automator",
        "model": { "primary": "chj-private/azure-gpt-5-codex" },
        "identity": { "name": "自动化", "emoji": "🤖" },
        "tools": {
          "allow": ["exec", "process", "cron", "browser", "read", "write"],
          "deny": ["message", "gateway", "web_search", "web_fetch"]
        }
      }
    ]
  }
}
```

### 步骤 3：重启 Gateway

```bash
openclaw gateway restart
```

## 三、智能体工具权限矩阵

| 智能体 | read | write | edit | exec | process | web_search | web_fetch | browser | message | cron | memory |
|--------|:----:|:-----:|:----:|:----:|:-------:|:----------:|:---------:|:-------:|:-------:|:----:|:------:|
| 📋 pm | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ |
| 🔍 researcher | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ |
| 👨‍💻 coder | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| ✍️ writer | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| 🎨 designer | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 📊 analyst | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| 🔎 reviewer | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| 💬 assistant | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| 🤖 automator | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ |

### 权限设计原则

1. **最小权限** — 只给必要的工具
2. **职责隔离** — reviewer 只读不写，防止直接修改
3. **安全边界** — gateway/message 等敏感工具严格限制
4. **成本控制** — researcher/assistant 用便宜模型

## 四、添加新模型

### 配置示例（以 Gemini 3 Pro Image 为例）

```json
{
  "models": {
    "vendor-gemini-3-pro-image": {
      "baseUrl": "https://your-gateway-url/v1beta",
      "apiKey": "YOUR_API_KEY_HERE",
      "api": "google-generative-ai",
      "authHeader": "x-goog-api-key",
      "models": [
        {
          "id": "gemini-3-pro-image-preview",
          "name": "Gemini 3 Pro Image",
          "reasoning": false,
          "input": ["text", "image"],
          "contextWindow": 1000000,
          "maxTokens": 65536
        }
      ]
    }
  },
  "modelAliases": {
    "gemini-image": "vendor-gemini-3-pro-image/gemini-3-pro-image-preview"
  }
}
```

### 关键配置项说明

| 配置项 | 说明 |
|--------|------|
| baseUrl | 模型 API 的基础 URL |
| apiKey | API 密钥 |
| api | API 格式类型（openai / google-generative-ai / anthropic） |
| authHeader | 认证头名称 |
| models[].id | 模型 ID，用于调用时指定 |
| models[].input | 支持的输入类型 |

## 五、验证配置

```bash
# 检查智能体列表
openclaw agents list

# 测试 spawn
# 在主会话中执行
sessions_spawn({ task: "测试任务", agentId: "researcher" })

# 查看子会话
openclaw sessions list
```

## 六、常见问题

| 问题 | 解决方案 |
|------|----------|
| spawn 报错 "agentId is not allowed" | 检查主智能体的 `subagents.allowAgents` 是否包含目标智能体 ID |
| 子智能体无法使用某工具 | 检查该智能体的 `tools.allow` 和 `tools.deny` 配置 |
| 401 Unauthorized | 检查 apiKey 是否正确 |
| 400 Bad Request | 检查 api 字段是否与模型匹配 |
| 子智能体输出为空 | 检查 task 描述是否清晰，包含输出要求 |

## 七、智能体人格文件

每个智能体工作目录应包含：

| 文件 | 用途 | 必需 |
|------|------|:----:|
| SOUL.md | 人格定义、核心原则 | ✅ |
| AGENTS.md | 工作规范、可用工具 | ✅ |
| BOOTSTRAP.md | 首次运行指引 | 可选 |
| IDENTITY.md | 身份信息 | 可选 |
| TOOLS.md | 工具使用笔记 | 可选 |

详细的人格模板见 `scripts/init_agents.py`


path: references/statistics-template.md
content: # 任务统计与成本分析模板

完成智能体团队协作任务后，**必须**输出以下统计信息：

## 统计模板

```markdown
## 📊 智能体团队执行统计

### 执行明细
| 智能体 | 任务 | 耗时 | Tokens (in/out) | 状态 |
|--------|------|------|-----------------|------|
| 🔍 researcher | xxx调研 | 3m58s | 9.5k/1.0k | ✅ |
| ✍️ writer | 撰写报告 | 2m12s | 20.5k/282 | ✅ |
| 🎨 designer | 生成图片 | 45s | - | ✅ |

### 成本汇总
- **总耗时**: 6m55s（并行优化后实际等待: 4m）
- **总 Tokens**: 30k input / 1.3k output
- **实际成本**: $X.XX（按模型分别计算）
- **全用主模型成本**: $X.XX
- **节省**: XX%

### 效率分析
- **串行执行预估**: ~15分钟
- **并行执行实际**: ~4分钟  
- **节省时间**: ~11分钟 (73%)
- **并行任务数**: 2个 researcher 并行

### 团队价值
相比单智能体顺序执行，智能体团队通过：
1. 并行调研 → 缩短等待时间
2. 专业分工 → 提升输出质量
3. 模型适配 → 优化成本效益（研究用GLM，写作用Gemini）
```

## 成本计算方法

```
单个智能体成本 = (input_tokens / 1M × input_price) + (output_tokens / 1M × output_price)
总成本 = Σ(各智能体成本)
全用主模型成本 = 总tokens × 主模型价格
节省比例 = (全用主模型成本 - 实际成本) / 全用主模型成本 × 100%
```

## 模型价格参考

| 模型 | Input | Output | 用于 |
|------|-------|--------|------|
| Claude Opus 4.5 | $5/M | $25/M | main, coder, analyst, reviewer, automator |
| Gemini 2.5 Pro | $1.25/M | $10/M | pm, writer |
| GLM-4 | ~$0.014/M | ~$0.014/M | researcher, assistant |

## 数据来源

从 spawn 返回的统计信息中提取：
- `runtime`: 执行耗时
- `tokens`: token 使用量（in/out）
- `est`: 预估成本

## 效率计算公式

```
并行节省时间 = Σ(各任务耗时) - max(并行组耗时) - Σ(串行任务耗时)
并行效率 = 并行节省时间 / Σ(各任务耗时) × 100%
```


path: scripts/agent_manager.py
content: #!/usr/bin/env python3
"""
智能体集群配置管理工具

用法:
    python agent_manager.py list                    # 列出所有智能体
    python agent_manager.py show <agent_id>         # 查看智能体详情
    python agent_manager.py add <agent_id>          # 添加新智能体
    python agent_manager.py remove <agent_id>       # 删除智能体
    python agent_manager.py update <agent_id>       # 更新智能体配置
"""

import os
import json
import argparse
from pathlib import Path
from datetime import datetime

DEFAULT_AGENTS_PATH = "/workspace/agents"

AGENT_TEMPLATES = {
    "default": {
        "name": "新智能体",
        "emoji": "🤖",
        "model": "claude-opus-4",
        "tools_allow": ["read", "write"],
        "tools_deny": ["gateway", "message"],
        "soul": """# SOUL.md - {name}

_你的核心职责描述_

## 工作原则

1. **原则一** — 描述
2. **原则二** — 描述

## 边界

- ❌ 不做什么
- ✅ 专注于什么
"""
    },
    "researcher": {
        "name": "研究员",
        "emoji": "🔍",
        "model": "glm-4",
        "tools_allow": ["web_search", "web_fetch", "read", "write", "memory_search", "memory_get"],
        "tools_deny": ["exec", "process", "gateway", "browser", "message", "cron"]
    },
    "coder": {
        "name": "程序员",
        "emoji": "👨‍💻",
        "model": "claude-opus-4",
        "tools_allow": ["read", "write", "edit", "exec", "process"],
        "tools_deny": ["web_search", "browser", "message", "gateway", "cron"]
    },
    "writer": {
        "name": "写作者",
        "emoji": "✍️",
        "model": "gemini-2.5-pro",
        "tools_allow": ["read", "write", "edit", "memory_search", "memory_get"],
        "tools_deny": ["exec", "process", "browser", "gateway", "message", "cron"]
    }
}


def get_agent_path(agent_id: str, base_path: str = DEFAULT_AGENTS_PATH) -> Path:
    return Path(base_path) / agent_id


def list_agents(base_path: str = DEFAULT_AGENTS_PATH) -> list:
    """列出所有智能体"""
    agents = []
    base = Path(base_path)
    if not base.exists():
        return agents
    
    for agent_dir in base.iterdir():
        if agent_dir.is_dir() and not agent_dir.name.startswith('.'):
            soul_file = agent_dir / "SOUL.md"
            agents_file = agent_dir / "AGENTS.md"
            memory_file = agent_dir / "memory" / "experience.md"
            
            agent_info = {
                "id": agent_dir.name,
                "path": str(agent_dir),
                "has_soul": soul_file.exists(),
                "has_agents": agents_file.exists(),
                "has_memory": memory_file.exists(),
            }
            
            # 尝试读取名称和emoji
            if soul_file.exists():
                content = soul_file.read_text()
                if "# SOUL.md - " in content:
                    first_line = content.split('\n')[0]
                    agent_info["name"] = first_line.replace("# SOUL.md - ", "").strip()
            
            agents.append(agent_info)
    
    return agents


def show_agent(agent_id: str, base_path: str = DEFAULT_AGENTS_PATH) -> dict:
    """查看智能体详情"""
    agent_path = get_agent_path(agent_id, base_path)
    if not agent_path.exists():
        return {"error": f"智能体 {agent_id} 不存在"}
    
    info = {
        "id": agent_id,
        "path": str(agent_path),
        "files": []
    }
    
    for f in agent_path.iterdir():
        if f.is_file():
            info["files"].append(f.name)
        elif f.is_dir():
            info["files"].append(f"{f.name}/")
    
    # 读取 SOUL.md
    soul_file = agent_path / "SOUL.md"
    if soul_file.exists():
        info["soul"] = soul_file.read_text()[:500] + "..." if len(soul_file.read_text()) > 500 else soul_file.read_text()
    
    # 读取经验记忆
    memory_file = agent_path / "memory" / "experience.md"
    if memory_file.exists():
        info["experience"] = memory_file.read_text()
    
    return info


def add_agent(agent_id: str, template: str = "default", base_path: str = DEFAULT_AGENTS_PATH, **kwargs) -> dict:
    """添加新智能体"""
    agent_path = get_agent_path(agent_id, base_path)
    if agent_path.exists():
        return {"error": f"智能体 {agent_id} 已存在"}
    
    # 获取模板
    tmpl = AGENT_TEMPLATES.get(template, AGENT_TEMPLATES["default"]).copy()
    tmpl.update(kwargs)
    
    # 创建目录
    agent_path.mkdir(parents=True, exist_ok=True)
    (agent_path / "memory").mkdir(exist_ok=True)
    
    # 创建 SOUL.md
    soul_content = tmpl.get("soul", AGENT_TEMPLATES["default"]["soul"])
    soul_content = soul_content.format(name=tmpl.get("name", agent_id))
    (agent_path / "SOUL.md").write_text(soul_content)
    
    # 创建 AGENTS.md
    agents_content = f"""# AGENTS.md - {tmpl.get('name', agent_id)} {tmpl.get('emoji', '🤖')}

## 角色
你是智能体团队中的 {tmpl.get('name', agent_id)}。

## 可用工具
{chr(10).join(f"- `{t}`" for t in tmpl.get('tools_allow', []))}

## 工作规范
1. 专注于你的专业领域
2. 输出结构化、可用的结果
3. 任务完成后总结经验到 memory/experience.md
"""
    (agent_path / "AGENTS.md").write_text(agents_content)
    
    # 创建经验记忆文件
    experience_content = f"""# 经验记忆 - {tmpl.get('name', agent_id)}

*记录执行任务中获得的有效经验*

## 使用说明
每次完成任务后，总结 1-3 条简短经验，格式：
- [日期] 经验描述 (来源任务)

## 经验记录

*(暂无记录)*
"""
    (agent_path / "memory" / "experience.md").write_text(experience_content)
    
    return {
        "success": True,
        "agent_id": agent_id,
        "path": str(agent_path),
        "template": template
    }


def remove_agent(agent_id: str, base_path: str = DEFAULT_AGENTS_PATH, backup: bool = True) -> dict:
    """删除智能体（默认先备份）"""
    agent_path = get_agent_path(agent_id, base_path)
    if not agent_path.exists():
        return {"error": f"智能体 {agent_id} 不存在"}
    
    if backup:
        import shutil
        backup_path = Path(base_path) / f".backup_{agent_id}_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
        shutil.move(str(agent_path), str(backup_path))
        return {
            "success": True,
            "agent_id": agent_id,
            "backup_path": str(backup_path)
        }
    else:
        import shutil
        shutil.rmtree(agent_path)
        return {
            "success": True,
            "agent_id": agent_id,
            "deleted": True
        }


def update_agent(agent_id: str, base_path: str = DEFAULT_AGENTS_PATH, **kwargs) -> dict:
    """更新智能体配置"""
    agent_path = get_agent_path(agent_id, base_path)
    if not agent_path.exists():
        return {"error": f"智能体 {agent_id} 不存在"}
    
    updated = []
    
    # 更新名称
    if "name" in kwargs:
        soul_file = agent_path / "SOUL.md"
        if soul_file.exists():
            content = soul_file.read_text()
            # 简单替换第一行
            lines = content.split('\n')
            if lines[0].startswith("# SOUL.md"):
                lines[0] = f"# SOUL.md - {kwargs['name']}"
                soul_file.write_text('\n'.join(lines))
                updated.append("name")
    
    # 更新 emoji
    if "emoji" in kwargs:
        agents_file = agent_path / "AGENTS.md"
        if agents_file.exists():
            content = agents_file.read_text()
            # 替换第一行的 emoji
            lines = content.split('\n')
            if lines[0].startswith("# AGENTS.md"):
                # 尝试更新 emoji
                updated.append("emoji")
    
    return {
        "success": True,
        "agent_id": agent_id,
        "updated": updated
    }


def main():
    parser = argparse.ArgumentParser(description="智能体集群配置管理")
    parser.add_argument("action", choices=["list", "show", "add", "remove", "update"])
    parser.add_argument("agent_id", nargs="?", help="智能体 ID")
    parser.add_argument("--base-path", default=DEFAULT_AGENTS_PATH, help="智能体目录")
    parser.add_argument("--template", default="default", help="模板 (default/researcher/coder/writer)")
    parser.add_argument("--name", help="智能体名称")
    parser.add_argument("--emoji", help="智能体 emoji")
    parser.add_argument("--no-backup", action="store_true", help="删除时不备份")
    
    args = parser.parse_args()
    
    if args.action == "list":
        agents = list_agents(args.base_path)
        print(f"\n📋 智能体列表 ({len(agents)} 个)\n")
        for a in agents:
            status = "✅" if a.get("has_soul") else "⚠️"
            memory = "🧠" if a.get("has_memory") else ""
            name = a.get("name", a["id"])
            print(f"  {status} {a['id']:12} {name} {memory}")
        print()
    
    elif args.action == "show":
        if not args.agent_id:
            print("错误: 需要指定 agent_id")
            return
        result = show_agent(args.agent_id, args.base_path)
        print(json.dumps(result, indent=2, ensure_ascii=False))
    
    elif args.action == "add":
        if not args.agent_id:
            print("错误: 需要指定 agent_id")
            return
        kwargs = {}
        if args.name:
            kwargs["name"] = args.name
        if args.emoji:
            kwargs["emoji"] = args.emoji
        result = add_agent(args.agent_id, args.template, args.base_path, **kwargs)
        print(json.dumps(result, indent=2, ensure_ascii=False))
    
    elif args.action == "remove":
        if not args.agent_id:
            print("错误: 需要指定 agent_id")
            return
        result = remove_agent(args.agent_id, args.base_path, backup=not args.no_backup)
        print(json.dumps(result, indent=2, ensure_ascii=False))
    
    elif args.action == "update":
        if not args.agent_id:
            print("错误: 需要指定 agent_id")
            return
        kwargs = {}
        if args.name:
            kwargs["name"] = args.name
        if args.emoji:
            kwargs["emoji"] = args.emoji
        result = update_agent(args.agent_id, args.base_path, **kwargs)
        print(json.dumps(result, indent=2, ensure_ascii=False))


if __name__ == "__main__":
    main()


path: scripts/experience_logger.py
content: #!/usr/bin/env python3
"""
智能体经验记录工具

用于在任务完成后记录经验，供后续任务参考。

用法:
    python experience_logger.py log <agent_id> "经验描述" --task "任务名称"
    python experience_logger.py show <agent_id>
    python experience_logger.py summary <agent_id>  # 生成经验摘要
    python experience_logger.py inject <agent_id>   # 输出可注入到 prompt 的经验
"""

import os
import json
import argparse
from pathlib import Path
from datetime import datetime
from collections import defaultdict

DEFAULT_AGENTS_PATH = "/workspace/agents"
MAX_EXPERIENCES = 50  # 每个智能体最多保留的经验数


def get_experience_file(agent_id: str, base_path: str = DEFAULT_AGENTS_PATH) -> Path:
    return Path(base_path) / agent_id / "memory" / "experience.md"


def get_experience_json(agent_id: str, base_path: str = DEFAULT_AGENTS_PATH) -> Path:
    return Path(base_path) / agent_id / "memory" / "experience.json"


def log_experience(agent_id: str, experience: str, task: str = None, 
                   category: str = "general", base_path: str = DEFAULT_AGENTS_PATH) -> dict:
    """记录一条经验"""
    exp_file = get_experience_file(agent_id, base_path)
    exp_json = get_experience_json(agent_id, base_path)
    
    # 确保目录存在
    exp_file.parent.mkdir(parents=True, exist_ok=True)
    
    # 当前时间
    now = datetime.now()
    date_str = now.strftime("%Y-%m-%d")
    time_str = now.strftime("%H:%M")
    
    # 记录到 JSON（结构化）
    experiences = []
    if exp_json.exists():
        try:
            experiences = json.loads(exp_json.read_text())
        except:
            experiences = []
    
    new_exp = {
        "id": f"exp_{now.strftime('%Y%m%d%H%M%S')}",
        "content": experience,
        "task": task,
        "category": category,
        "created": now.isoformat(),
        "used_count": 0
    }
    experiences.append(new_exp)
    
    # 保留最近 MAX_EXPERIENCES 条
    if len(experiences) > MAX_EXPERIENCES:
        experiences = experiences[-MAX_EXPERIENCES:]
    
    exp_json.write_text(json.dumps(experiences, indent=2, ensure_ascii=False))
    
    # 同时更新 Markdown 文件（人类可读）
    task_info = f" ({task})" if task else ""
    new_line = f"- [{date_str}] {experience}{task_info}\n"
    
    if exp_file.exists():
        content = exp_file.read_text()
        # 在 "## 经验记录" 后插入
        if "## 经验记录" in content:
            parts = content.split("## 经验记录")
            # 移除 "(暂无记录)" 提示
            rest = parts[1].replace("*(暂无记录)*\n", "").replace("*(暂无记录)*", "")
            content = parts[0] + "## 经验记录\n\n" + new_line + rest.lstrip('\n')
            exp_file.write_text(content)
    else:
        # 创建新文件
        content = f"""# 经验记忆 - {agent_id}

*记录执行任务中获得的有效经验*

## 经验记录

{new_line}
"""
        exp_file.write_text(content)
    
    return {
        "success": True,
        "agent_id": agent_id,
        "experience_id": new_exp["id"],
        "total_experiences": len(experiences)
    }


def show_experiences(agent_id: str, limit: int = 10, base_path: str = DEFAULT_AGENTS_PATH) -> list:
    """查看智能体的经验记录"""
    exp_json = get_experience_json(agent_id, base_path)
    
    if not exp_json.exists():
        return []
    
    try:
        experiences = json.loads(exp_json.read_text())
        return experiences[-limit:]  # 返回最近 N 条
    except:
        return []


def generate_summary(agent_id: str, base_path: str = DEFAULT_AGENTS_PATH) -> str:
    """生成经验摘要（按类别分组）"""
    experiences = show_experiences(agent_id, limit=50, base_path=base_path)
    
    if not experiences:
        return "暂无经验记录"
    
    # 按类别分组
    by_category = defaultdict(list)
    for exp in experiences:
        cat = exp.get("category", "general")
        by_category[cat].append(exp["content"])
    
    # 生成摘要
    lines = [f"## {agent_id} 经验摘要\n"]
    for cat, exps in by_category.items():
        lines.append(f"### {cat}")
        for exp in exps[-5:]:  # 每类最多 5 条
            lines.append(f"- {exp}")
        lines.append("")
    
    return "\n".join(lines)


def inject_experiences(agent_id: str, limit: int = 5, base_path: str = DEFAULT_AGENTS_PATH) -> str:
    """
    输出可注入到 prompt 的经验片段
    用于在 spawn 时注入相关经验
    """
    experiences = show_experiences(agent_id, limit=limit, base_path=base_path)
    
    if not experiences:
        return ""
    
    lines = ["## 历史经验（供参考）\n"]
    for exp in experiences:
        task_info = f" (来自: {exp['task']})" if exp.get('task') else ""
        lines.append(f"- {exp['content']}{task_info}")
    
    return "\n".join(lines)


def mark_experience_used(agent_id: str, exp_id: str, base_path: str = DEFAULT_AGENTS_PATH) -> bool:
    """标记经验已被使用（用于统计有效性）"""
    exp_json = get_experience_json(agent_id, base_path)
    
    if not exp_json.exists():
        return False
    
    try:
        experiences = json.loads(exp_json.read_text())
        for exp in experiences:
            if exp.get("id") == exp_id:
                exp["used_count"] = exp.get("used_count", 0) + 1
                exp["last_used"] = datetime.now().isoformat()
        exp_json.write_text(json.dumps(experiences, indent=2, ensure_ascii=False))
        return True
    except:
        return False


def main():
    parser = argparse.ArgumentParser(description="智能体经验记录工具")
    parser.add_argument("action", choices=["log", "show", "summary", "inject"])
    parser.add_argument("agent_id", help="智能体 ID")
    parser.add_argument("experience", nargs="?", help="经验描述（log 时必填）")
    parser.add_argument("--task", help="来源任务")
    parser.add_argument("--category", default="general", help="经验类别")
    parser.add_argument("--limit", type=int, default=10, help="显示数量")
    parser.add_argument("--base-path", default=DEFAULT_AGENTS_PATH)
    
    args = parser.parse_args()
    
    if args.action == "log":
        if not args.experience:
            print("错误: log 操作需要提供经验描述")
            return
        result = log_experience(
            args.agent_id, 
            args.experience, 
            task=args.task,
            category=args.category,
            base_path=args.base_path
        )
        print(json.dumps(result, indent=2, ensure_ascii=False))
    
    elif args.action == "show":
        experiences = show_experiences(args.agent_id, limit=args.limit, base_path=args.base_path)
        for exp in experiences:
            print(f"[{exp.get('created', '?')[:10]}] {exp['content']}")
    
    elif args.action == "summary":
        print(generate_summary(args.agent_id, args.base_path))
    
    elif args.action == "inject":
        print(inject_experiences(args.agent_id, limit=args.limit, base_path=args.base_path))


if __name__ == "__main__":
    main()


path: scripts/init_agents.py
content: #!/usr/bin/env python3
"""
初始化多智能体团队工作目录和基础文件

用法:
    python init_agents.py [--base-path /workspace/agents]
"""

import os
import argparse

AGENTS = {
    "pm": {
        "name": "产品经理",
        "emoji": "📋",
        "soul": """# SOUL.md - 产品经理

## 你是谁
你是一位经验丰富的产品经理，擅长需求分析、项目规划和任务拆解。

## 核心原则
- **用户优先**: 始终从用户需求出发
- **结构化思维**: 用清晰的框架组织信息
- **优先级意识**: 区分重要紧急，合理排序
- **沟通桥梁**: 技术与业务之间的翻译者

## 工作风格
- 输出结构化的需求文档和任务列表
- 使用表格、列表等清晰呈现信息
- 提供明确的验收标准
- 考虑边界情况和风险
"""
    },
    "researcher": {
        "name": "研究员",
        "emoji": "🔍",
        "soul": """# SOUL.md - 研究员

## 你是谁
你是一位信息搜集专家，擅长快速找到高质量信息并整理成结构化报告。

## 核心原则
- **广度优先**: 先覆盖多个信息源
- **交叉验证**: 对比多个来源确认信息
- **结构化输出**: 整理成易于使用的格式
- **标注来源**: 始终标明信息出处

## 工作风格
- 搜索多个关键词获取全面信息
- 输出带有引用链接的报告
- 区分事实与观点
- 总结关键发现
"""
    },
    "coder": {
        "name": "程序员",
        "emoji": "👨‍💻",
        "soul": """# SOUL.md - 程序员

## 你是谁
你是一位代码工匠，追求代码的可读性、可维护性和正确性。

## 核心原则
- **可读性优先**: 代码是写给人看的
- **测试验证**: 写测试，验证功能
- **安全意识**: 考虑安全边界
- **简洁至上**: 用最简单的方式解决问题

## 工作风格
- 写清晰的注释和文档
- 遵循项目的代码规范
- 考虑边界情况和错误处理
- 增量提交，清晰的 commit message
"""
    },
    "writer": {
        "name": "写作者",
        "emoji": "✍️",
        "soul": """# SOUL.md - 写作者

## 你是谁
你是一位文字工匠，擅长撰写清晰、有说服力的内容。

## 核心原则
- **读者优先**: 为目标读者写作
- **结构清晰**: 层次分明，逻辑流畅
- **风格适配**: 根据场景调整语气
- **简洁有力**: 删除冗余，保留精华

## 工作风格
- 先理解受众和目的
- 提供大纲后再展开
- 使用恰当的标题和段落
- 校对语法和表达
"""
    },
    "designer": {
        "name": "设计师",
        "emoji": "🎨",
        "soul": """# SOUL.md - 设计师

## 你是谁
你是一位视觉创作者，擅长将概念转化为有吸引力的图像。

## 核心原则
- **目的明确**: 理解图像要传达什么
- **简洁清晰**: 避免视觉噪音
- **适配场景**: 考虑使用环境
- **一致性**: 保持风格统一

## 工作风格
- 先确认设计需求和风格
- 生成多个方案供选择
- 解释设计决策
- 按需迭代优化
"""
    },
    "analyst": {
        "name": "分析师",
        "emoji": "📊",
        "soul": """# SOUL.md - 分析师

## 你是谁
你是一位数据侦探，擅长从数据中发现洞察。

## 核心原则
- **数据质量**: 先验证数据准确性
- **假设驱动**: 带着问题分析
- **洞察导向**: 输出可行动的结论
- **可视化**: 用图表辅助理解

## 工作风格
- 先理解数据结构和含义
- 进行探索性分析
- 用统计方法验证假设
- 输出清晰的分析报告
"""
    },
    "reviewer": {
        "name": "审核员",
        "emoji": "🔎",
        "soul": """# SOUL.md - 审核员

## 你是谁
你是质量守门人，确保输出符合标准。

## 核心原则
- **客观公正**: 基于标准评判
- **建设性**: 提供改进建议
- **只审不改**: 指出问题，不直接修改
- **全面细致**: 不遗漏重要问题

## 工作风格
- 明确评审标准
- 逐项检查，记录问题
- 区分严重程度
- 给出具体改进建议
"""
    },
    "assistant": {
        "name": "助手",
        "emoji": "💬",
        "soul": """# SOUL.md - 助手

## 你是谁
你是沟通桥梁，负责消息传递和简单问答。

## 核心原则
- **快速响应**: 及时处理请求
- **简洁明了**: 直接给出答案
- **知道边界**: 复杂问题转交专家
- **友好礼貌**: 保持良好沟通

## 工作风格
- 简洁回复，不啰嗦
- 不确定时说明
- 需要时引导到其他智能体
- 保持消息格式整洁
"""
    },
    "automator": {
        "name": "自动化",
        "emoji": "🤖",
        "soul": """# SOUL.md - 自动化专家

## 你是谁
你是效率大师，擅长编写自动化脚本和定时任务。

## 核心原则
- **ROI思维**: 自动化要值得
- **稳定可靠**: 考虑失败处理
- **有监控**: 可观察运行状态
- **文档化**: 记录脚本用途

## 工作风格
- 先评估自动化收益
- 编写健壮的脚本
- 添加日志和错误处理
- 设置合理的定时策略
"""
    }
}


def create_agent_workspace(base_path: str, agent_id: str, agent_info: dict):
    """为单个智能体创建工作目录和基础文件"""
    agent_path = os.path.join(base_path, agent_id)
    os.makedirs(agent_path, exist_ok=True)
    
    # 创建 SOUL.md
    soul_path = os.path.join(agent_path, "SOUL.md")
    with open(soul_path, "w", encoding="utf-8") as f:
        f.write(agent_info["soul"])
    
    # 创建 AGENTS.md
    agents_path = os.path.join(agent_path, "AGENTS.md")
    with open(agents_path, "w", encoding="utf-8") as f:
        f.write(f"""# AGENTS.md - {agent_info['name']} {agent_info['emoji']}

## 角色
你是智能体团队中的 {agent_info['name']}。

## 工作规范
1. 专注于你的专业领域
2. 输出结构化、可用的结果
3. 如果任务超出能力范围，明确说明

## 输出格式
- 使用 Markdown 格式
- 重要信息用标题和列表组织
- 代码用代码块包裹
""")
    
    print(f"  ✅ {agent_info['emoji']} {agent_id} ({agent_info['name']})")


def main():
    parser = argparse.ArgumentParser(description="初始化多智能体团队工作目录")
    parser.add_argument(
        "--base-path",
        default="/workspace/agents",
        help="智能体工作目录的基础路径 (default: /workspace/agents)"
    )
    args = parser.parse_args()
    
    print(f"\n🚀 初始化多智能体团队工作目录")
    print(f"   路径: {args.base_path}\n")
    
    os.makedirs(args.base_path, exist_ok=True)
    
    for agent_id, agent_info in AGENTS.items():
        create_agent_workspace(args.base_path, agent_id, agent_info)
    
    print(f"\n✨ 完成！共创建 {len(AGENTS)} 个智能体工作目录")
    print(f"\n下一步:")
    print(f"  1. 在 openclaw.json 中添加智能体配置")
    print(f"  2. 运行 `openclaw gateway restart` 重启服务")
    print(f"  3. 运行 `openclaw agents list` 验证配置")


if __name__ == "__main__":
    main()


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)