repo_description: Multi-Agent System Framework For Complex Tasks
repo_topics: agents ai llm manus muilt-agents workflow
code: // 文档生成脚本
  // 运行: node generate-docs.js
  
  const fs = require('fs');
  const path = require('path');
  
  // 文档结构定义
  const docsStructure = {
    'agent/index.md': `# 智能体概述
  
  智能体是 Sage 的核心功能，它是 AI 助手的配置单元。
  
  ## 什么是智能体？
  
  智能体是一个配置了特定系统提示词和工具的 AI 助手。每个智能体可以：
  
  - 拥有独立的系统提示词
  - 使用特定的工具集合
  - 维护独立的对话历史
  - 拥有专属的工作空间
  
  ## 智能体列表
  
  在智能体列表页面，你可以：
  
  - 查看所有智能体
  - 创建新智能体
  - 编辑智能体配置
  - 删除智能体
  - 导入/导出智能体
  
  ![智能体列表截图占位]
  
  ## 创建方式
  
  ### 手动创建
  
  适合有明确需求的用户，可以精确配置每个参数。
  
  ### 自动生成
  
  适合快速原型，只需描述需求，AI 会自动生成配置。
  
  ## 相关功能
  
  - [创建智能体](./create.md)
  - [编辑配置](./edit.md)
  - [聊天对话](./chat.md)
  - [工作空间](./workspace.md)
  `,
  
    'agent/create.md': `# 创建智能体
  
  Sage 提供两种创建智能体的方式：手动创建和自动生成。
  
  ## 手动创建
  
  ### 步骤
  
  1. 点击 **"创建智能体"** 按钮
  2. 选择 **"手动创建"**
  3. 填写基本信息：
     - **名称** - 智能体的显示名称
     - **描述** - 简要说明用途（可选）
  4. 编写系统提示词
  5. 选择工具
  6. 点击 **"创建"**
  
  ### 系统提示词
  
  系统提示词定义了智能体的角色和行为。例如：
  
  \`\`\`
  你是一位专业的 Python 开发助手，擅长：
  - 代码审查和优化
  - 调试和错误排查
  - 最佳实践建议
  
  回答要简洁明了，代码要符合 PEP8 规范。
  \`\`\`
  
  ### 选择工具
  
  勾选智能体可以使用的工具：
  
  - **基础工具** - Sage 内置的工具
  - **MCP 工具** - 通过 MCP 协议接入的工具
  - **自定义工具** - 你自己创建的工具
  
  ![选择工具截图占位]
  
  ## 自动生成
  
  ### 步骤
  
  1. 点击 **"创建智能体"** 按钮
  2. 选择 **"自动生成"**
  3. 描述你需要的智能体：
  
  \`\`\`
  我需要一个数据分析助手，能够：
  - 读取 CSV 和 Excel 文件
  - 进行数据清洗和统计分析
  - 生成可视化图表
  - 提供数据洞察报告
  \`\`\`
  
  4. 点击 **"生成"**
  5. AI 会生成：
     - 智能体名称
     - 系统提示词
     - 建议的工具列表
  6. 确认或修改后点击 **"创建"**
  
  ![自动生成截图占位]
  
  ## 最佳实践
  
  - **命名规范** - 使用有意义的名称，如 "Python代码审查助手"
  - **提示词清晰** - 明确说明智能体的角色和能力边界
  - **工具精简** - 只选择必要的工具，避免功能冗余
  `,
  
    'agent/edit.md': `# 编辑智能体
  
  创建智能体后，你可以随时修改其配置。
  
  ## 编辑入口
  
  1. 在智能体列表中找到要编辑的智能体
  2. 点击 **"编辑"** 按钮或卡片上的设置图标
  3. 进入编辑页面
  
  ## 可编辑项
  
  ### 基本信息
  
  - **名称** - 修改显示名称
  - **描述** - 更新描述信息
  - **图标** - 更换智能体图标（如支持）
  
  ### 系统提示词
  
  点击提示词编辑框，修改后保存。
  
  ::: tip 提示
  修改系统提示词不会影响已有的对话历史，但会影响新的对话。
  :::
  
  ### 工具配置
  
  - **添加工具** - 勾选要添加的工具
  - **移除工具** - 取消勾选要移除的工具
  - **调整顺序** - 拖拽调整工具优先级（如支持）
  
  ![工具配置截图占位]
  
  ### 高级设置
  
  部分智能体可能支持高级配置：
  
  - **温度参数** - 控制输出的随机性
  - **最大令牌数** - 限制单次响应长度
  - **上下文窗口** - 设置保留的对话历史长度
  
  ## 保存更改
  
  修改完成后，点击 **"保存"** 按钮。
  
  ::: warning 注意
  某些更改可能需要重新启动对话才能生效。
  :::
  `,
  
    'agent/chat.md': `# 聊天对话
  
  与智能体进行交互的主要方式。
  
  ## 聊天界面
  
  ![聊天界面截图占位]
  
  界面组成：
  
  1. **顶部栏** - 显示智能体名称和操作按钮
  2. **消息区域** - 显示对话历史
  3. **输入框** - 输入消息
  4. **工具面板** - 显示可用工具（可收起）
  5. **工作空间** - 文件管理面板（可收起）
  
  ## 发送消息
  
  1. 在底部输入框输入文字
  2. 按 **Enter** 发送
  3. 支持 **Shift + Enter** 换行
  
  ## 消息类型
  
  ### 文本消息
  
  普通文本对话，支持 Markdown 格式。
  
  ### 工具调用
  
  当智能体使用工具时，会显示工具调用卡片：
  
  ![工具调用截图占位]
  
  你可以：
  - 查看工具名称和参数
  - 查看执行结果
  - 展开/收起详情
  
  ### 文件消息
  
  支持发送和接收文件：
  
  - 点击输入框的附件图标
  - 选择要发送的文件
  - 文件会显示在对话中
  
  ## 功能按钮
  
  ### 中断生成
  
  当智能体正在生成回复时，可以点击 **"停止"** 按钮中断。
  
  ### 重新生成
  
  对某个回复不满意，可以点击 **"重新生成"** 按钮。
  
  ### 复制消息
  
  点击消息上的复制按钮，复制消息内容。
  
  ### 删除消息
  
  点击消息上的删除按钮，删除该消息及后续消息。
  
  ## 快捷操作
  
  - **Ctrl/Cmd + /** - 聚焦到输入框
  - **Esc** - 取消输入或关闭面板
  - **↑** - 编辑上一条消息（自己发送的）
  `,
  
    'agent/workspace.md': `# 工作空间
  
  每个智能体拥有独立的工作空间，用于存储和管理文件。
  
  ## 什么是工作空间？
  
  工作空间是智能体的专属文件存储区域，用于：
  
  - 存储上传的文件
  - 保存生成的文件
  - 作为工具操作的文件根目录
  
  ## 访问工作空间
  
  在聊天界面，点击右侧的 **"工作空间"** 按钮展开面板。
  
  ![工作空间面板截图占位]
  
  ## 文件操作
  
  ### 上传文件
  
  1. 点击 **"上传"** 按钮
  2. 选择本地文件
  3. 文件会显示在工作空间列表中
  
  ### 下载文件
  
  1. 找到要下载的文件
  2. 点击文件右侧的下载图标
  3. 文件会保存到本地下载目录
  
  ### 删除文件
  
  1. 找到要删除的文件
  2. 点击文件右侧的删除图标
  3. 确认删除
  
  ::: warning 注意
  删除操作不可恢复，请谨慎操作。
  :::
  
  ### 预览文件
  
  点击文件名可以预览文件内容（支持文本、图片等格式）。
  
  ## 工具与工作空间
  
  智能体的工具可以访问工作空间中的文件：
  
  - **读取文件** - 工具可以读取工作空间内的文件
  - **写入文件** - 工具可以将结果保存到工作空间
  - **列出文件** - 工具可以获取文件列表
  
  ## 文件权限
  
  - 智能体只能访问自己的工作空间
  - 不同智能体的工作空间相互隔离
  - 删除智能体时会清空其工作空间
  `,
  
    'tools/index.md': `# 工具概述
  
  工具让智能体能够执行各种操作，从简单的计算到复杂的文件处理。
  
  ## 工具类型
  
  Sage 支持三种类型的工具：
  
  ### 基础工具
  
  Sage 内置的工具，开箱即用：
  
  - 文件读写
  - 代码执行
  - 网页搜索
  - 计算器
  
  ### MCP 工具
  
  通过 MCP（模型上下文协议）接入的外部工具：
  
  - 数据库查询
  - API 调用
  - 文件系统操作
  - 第三方服务集成
  
  ### 自定义工具
  
  用户自己创建的工具，满足特定需求。
  
  ## 工具管理
  
  在 **"工具"** 页面，你可以：
  
  - 查看所有可用工具
  - 按来源筛选（基础/MCP/自定义）
  - 测试工具
  - 管理 MCP 服务器
  
  ![工具列表截图占位]
  
  ## 为智能体配置工具
  
  创建或编辑智能体时，可以勾选该智能体可以使用的工具。
  
  ::: tip 建议
  只为智能体配置必要的工具，过多的工具可能影响性能和准确性。
  :::
  `,
  
    'tools/mcp.md': `# MCP 工具
  
  MCP（模型上下文协议）允许你连接外部工具服务器，无限扩展智能体能力。
  
  ## 什么是 MCP？
  
  MCP 是一种开放协议，标准化了 AI 模型与外部工具的交互方式。通过 MCP，你可以：
  
  - 连接文件系统
  - 查询数据库
  - 调用外部 API
  - 执行代码
  
  ## 添加 MCP 服务器
  
  ### 步骤
  
  1. 进入 **"工具"** 页面
  2. 点击 **"添加 MCP 服务器"**
  3. 选择添加方式：
     - **从市场安装** - 选择预设的 MCP 服务器
     - **自定义配置** - 手动输入配置
  
  ### 自定义配置
  
  输入 MCP 服务器的 JSON 配置：
  
  \`\`\`json
  {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      }
    }
  }
  \`\`\`
  
  ![MCP 配置截图占位]
  
  ## 常用 MCP 服务器
  
  ### 文件系统
  
  \`\`\`json
  {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
      }
    }
  }
  \`\`\`
  
  ### SQLite 数据库
  
  \`\`\`json
  {
    "mcpServers": {
      "sqlite": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/db.sqlite"]
      }
    }
  }
  \`\`\`
  
  ### Brave 搜索
  
  \`\`\`json
  {
    "mcpServers": {
      "brave-search": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-brave-search"],
        "env": {
          "BRAVE_API_KEY": "your-api-key"
        }
      }
    }
  }
  \`\`\`
  
  ## 管理 MCP 服务器
  
  ### 启用/禁用
  
  点击开关按钮可以快速启用或禁用 MCP 服务器。
  
  ### 刷新连接
  
  如果连接出现问题，点击 **"刷新"** 按钮重新连接。
  
  ### 删除
  
  点击 **"删除"** 按钮移除 MCP 服务器配置。
  
  ::: warning 注意
  删除后，使用该服务器的智能体将无法调用相关工具。
  :::
  `,
  
    'im/index.md': `# IM 渠道概述
  
  将智能体接入即时通讯平台，让团队成员可以通过熟悉的工具与 AI 交互。
  
  ## 支持的渠道
  
  Sage 支持以下 IM 平台：
  
  | 平台 | 接收消息 | 发送消息 | 备注 |
  |------|---------|---------|------|
  | 钉钉 | ✅ | ✅ | 完整支持 |
  | 飞书 | ✅ | ✅ | 完整支持 |
  | 企业微信 | ✅ | ✅ | 完整支持 |
  | iMessage | ✅ | ✅ | macOS  only |
  
  ## 配置流程
  
  1. 在 IM 平台创建应用/机器人
  2. 获取必要的凭证（AppID、AppSecret 等）
  3. 在 Sage 中配置 IM 渠道
  4. 测试连接
  
  ## 白名单
  
  为了安全，可以配置白名单限制哪些用户可以访问：
  
  - 钉钉：员工 ID
  - 飞书：用户 OpenID
  - 企业微信：成员 ID
  - iMessage：手机号或邮箱
  
  ![IM 配置截图占位]
  
  ## 消息格式
  
  智能体在 IM 渠道中支持：
  
  - 纯文本回复
  - Markdown 格式（部分平台支持）
  - 图片（需平台支持）
  - 文件（需平台支持）
  `,
  
    'im/dingtalk.md': `# 钉钉接入
  
  将智能体接入钉钉，让团队成员在钉钉中与 AI 对话。
  
  ## 前置条件
  
  - 钉钉企业管理员权限
  - 企业内部应用开发权限
  
  ## 配置步骤
  
  ### 1. 创建钉钉应用
  
  1. 登录 [钉钉开放平台](https://open.dingtalk.com/)
  2. 进入 **"应用开发"** → **"企业内部应用"**
  3. 点击 **"创建应用"**
  4. 填写应用名称和描述
  5. 记录 **AgentId**、**AppKey**、**AppSecret**
  
  ![钉钉创建应用截图占位]
  
  ### 2. 配置权限
  
  1. 进入应用详情页
  2. 点击 **"权限管理"**
  3. 添加以下权限：
     - 通讯录管理
     - 群会话管理
     - 机器人管理
  
  ### 3. 创建机器人
  
  1. 进入 **"机器人"** 标签
  2. 点击 **"添加机器人"**
  3. 选择 **"自定义机器人"**
  4. 记录 **Webhook URL**
  
  ### 4. 在 Sage 中配置
  
  1. 打开 Sage，进入 **"IM 渠道"** 设置
  2. 选择 **"钉钉"**
  3. 填写配置信息：
     - **AppKey**
     - **AppSecret**
     - **AgentId**
     - **Webhook URL**
  4. 设置白名单（可选）
  5. 点击 **"保存并测试"**
  
  ![钉钉配置截图占位]
  
  ## 白名单配置
  
  在 **"允许的用户"** 中填写钉钉员工的 **UserID**，每行一个。
  
  留空表示允许所有用户。
  
  ## 测试
  
  1. 在钉钉中找到机器人
  2. 发送一条测试消息
  3. 智能体应该回复
  
  ## 故障排除
  
  ### 无法接收消息
  
  - 检查机器人是否在群聊中
  - 检查权限是否配置正确
  - 查看 Sage 日志
  
  ### 无法发送消息
  
  - 检查 Webhook URL 是否正确
  - 检查网络连接
  - 确认没有触发频率限制
  `,
  
    'faq.md': `# 常见问题
  
  ## 安装与启动
  
  ### Q: 支持哪些操作系统？
  
  目前仅支持 macOS。Windows 和 Linux 版本正在开发中。
  
  ### Q: 启动时提示"无法打开应用"？
  
  1. 右键点击应用图标
  2. 选择 **"打开"**
  3. 在弹出的对话框中点击 **"打开"**
  
  或者：
  
  1. 打开 **"系统设置"** → **"隐私与安全性"**
  2. 找到 **"已阻止使用 Sage"**
  3. 点击 **"仍要打开"**
  
  ## 模型提供商
  
  ### Q: 支持哪些模型？
  
  - OpenAI（GPT-4、GPT-3.5）
  - Anthropic（Claude 系列）
  - Ollama（本地模型）
  - 任何兼容 OpenAI API 的提供商
  
  ### Q: 可以使用本地模型吗？
  
  可以。安装 Ollama 后，Sage 会自动检测到本地模型。
  
  ### Q: API 密钥保存在哪里？
  
  API 密钥安全存储在 macOS 钥匙串中，不会上传到任何服务器。
  
  ## 智能体
  
  ### Q: 可以创建多少个智能体？
  
  没有数量限制，但建议根据实际需求合理创建。
  
  ### Q: 智能体之间可以共享数据吗？
  
  每个智能体有独立的工作空间，数据默认不共享。但可以通过文件系统工具访问相同目录。
  
  ### Q: 如何导出智能体配置？
  
  在智能体列表中，点击智能体卡片上的 **"导出"** 按钮，会生成 JSON 配置文件。
  
  ## 工具
  
  ### Q: MCP 工具安全吗？
  
  MCP 工具在本地运行，不会将数据发送到外部服务器（除非工具本身需要）。
  
  ### Q: 工具执行失败怎么办？
  
  1. 检查工具配置是否正确
  2. 查看错误日志
  3. 尝试重启 MCP 服务器
  
  ## IM 渠道
  
  ### Q: 为什么收不到消息？
  
  - 检查 IM 平台配置是否正确
  - 确认机器人在群聊中
  - 检查白名单设置
  - 查看网络连接
  
  ### Q: 白名单怎么配置？
  
  填写用户的唯一标识：
  - 钉钉：UserID
  - 飞书：OpenID
  - 企业微信：成员 ID
  - iMessage：手机号或邮箱
  
  ## 性能
  
  ### Q: 占用内存过大？
  
  - 关闭不用的智能体对话
  - 清理历史记录
  - 减少同时运行的 MCP 服务器
  
  ### Q: 响应速度慢？
  
  - 检查网络连接
  - 选择响应更快的模型
  - 减少工具数量
  `,
  
    'troubleshooting.md': `# 故障排除
  
  ## 应用无法启动
  
  ### 症状
  
  点击应用图标后没有反应，或闪退。
  
  ### 解决方案
  
  1. **检查系统版本**
     - 确保 macOS 版本 >= 12.0
  
  2. **重新安装**
     - 删除应用
     - 重新下载安装
  
  3. **查看日志**
     - 打开 **"控制台"** 应用
     - 搜索 Sage 相关日志
  
  ## 无法连接模型
  
  ### 症状
  
  发送消息后一直显示"连接中"，或提示连接错误。
  
  ### 解决方案
  
  1. **检查 API 密钥**
     - 进入 **"模型提供商"** 设置
     - 确认密钥正确且未过期
  
  2. **检查网络**
     - 确认可以访问互联网
     - 如果使用代理，检查代理设置
  
  3. **测试连接**
     - 点击提供商卡片上的 **"测试"** 按钮
  
  ## 工具调用失败
  
  ### 症状
  
  智能体尝试使用工具时失败。
  
  ### 解决方案
  
  1. **检查工具配置**
     - 确认参数正确
     - 检查环境变量
  
  2. **重启 MCP 服务器**
     - 在工具页面点击 **"刷新"**
  
  3. **查看日志**
     - 打开开发者工具（如有）
     - 查看错误信息
  
  ## IM 渠道无响应
  
  ### 症状
  
  在钉钉/飞书等平台发送消息，智能体没有回复。
  
  ### 解决方案
  
  1. **检查配置**
     - 确认 AppID、AppSecret 正确
     - 检查 Webhook URL
  
  2. **检查白名单**
     - 确认发送者在白名单中
     - 或白名单为空（允许所有人）
  
  3. **查看日志**
     - 在 Sage 中查看 IM 相关日志
  
  4. **重新授权**
     - 在 IM 平台重新授权应用
  
  ## 性能问题
  
  ### 症状
  
  应用卡顿、内存占用高。
  
  ### 解决方案
  
  1. **清理历史记录**
     - 删除不需要的历史对话
  
  2. **关闭不用的 MCP**
     - 禁用暂时不需要的 MCP 服务器
  
  3. **重启应用**
     - 完全退出后重新启动
  
  ## 获取帮助
  
  如果以上方法无法解决问题：
  
  1. 查看 [常见问题](/faq)
  2. 在 GitHub 提交 Issue
  3. 加入社区讨论群
  `
  };
  
  // 创建目录
  const dirs = ['agent', 'chat', 'tools', 'skills', 'history', 'tasks', 'providers', 'im', 'settings'];
  dirs.forEach(dir => {
    const dirPath = path.join(__dirname, dir);
    if (!fs.existsSync(dirPath)) {
      fs.mkdirSync(dirPath, { recursive: true });
      console.log(`Created directory: ${dir}`);
    }
  });
  
  // 生成文件
  Object.entries(docsStructure).forEach(([filePath, content]) => {
    const fullPath = path.join(__dirname, filePath);
    const dir = path.dirname(fullPath);
    
    if (!fs.existsSync(dir)) {
      fs.mkdirSync(dir, { recursive: true });
    }
    
    fs.writeFileSync(fullPath, content);
    console.log(`Created: ${filePath}`);
  });
  
  console.log('\n✅ 文档生成完成！');
  console.log('\n使用方法：');
  console.log('1. cd /Users/zhangzheng/zavixai/Sage/app/docs');
  console.log('2. npm install');
  console.log('3. npm run dev');
  