📖 MonkeyBot 新手入门指南
欢迎使用 MonkeyBot！本文档将帮助你快速了解并上手
检测服务状态...
🤖 如何管理机器人？
机器人是 MonkeyBot 的核心，每个机器人都有独特的性格和能力。你可以创建多个机器人用于不同场景。
1机器人工作空间
每个机器人都有独立的工作空间，用于存储文件、配置和运行数据。点击机器人详情页的 "工作空间" 进入。
工作空间目录结构
- skills/ - 技能配置和脚本文件
- sessions/ - 会话历史记录
- tasks/ - 任务执行记录
- repos/ - 代码仓库（机器人可克隆和管理代码）
- sql/ - 机器人专属数据库文件
- downloads/ - 下载文件存储
- home/ - 机器人主目录
- assets/ - 上传的素材目录，例如手机录屏、参考图和待分析文件
- sop/ - SOP 流程文档
工作空间功能
- 文件浏览：查看目录结构，浏览文件内容
- 文件编辑：在线编辑文本文件（代码、配置、Markdown 等）
- 文件上传：上传文档、图片等文件到工作空间
- 文件下载：下载工作空间中的文件
- 新建文件/文件夹：创建新的文件或目录
- 删除文件：删除不需要的文件或目录
💡 使用提示
工作空间文件可以在对话中让机器人直接读取和编辑。例如：
• "读取 skills/ 目录下的文件"
• "帮我修改 config.json 文件"
• "上传的文档内容是什么？"
• "请分析 assets/mobile-recordings/ 里的这段手机录屏"
2沙箱与桌面
机器人在沙箱环境中运行，确保安全隔离。沙箱桌面提供可视化操作界面。
沙箱状态说明
- running - 沙箱正在运行
- stopped - 沙箱已停止
- pending - 正在启动中
沙箱桌面功能
- 打开桌面：启动桌面容器，获得图形化操作界面
- 关闭桌面：关闭桌面容器释放资源
- 重启沙箱：重启整个沙箱环境
桌面环境用途
- 运行需要图形界面的应用程序
- 进行可视化编程和调试
- 操作浏览器进行自动化任务
- 使用桌面软件处理文档、图片等
⚠️ 注意事项
- 桌面环境需要 Docker 支持
- 长时间不使用建议关闭桌面以节省资源
- 沙箱重启会清除临时数据，重要文件请保存到工作空间
🧰 如何给机器人添加技能？
技能是机器人的扩展能力，通过安装技能插件，机器人可以执行更多操作，如搜索文件、生成图片、执行代码等。
1进入技能管理
在机器人详情页，点击 "技能" 标签，可以查看和安装技能。
2安装技能
- 在高级模式中找到需要的技能管理入口（即将上线）
- 点击 "安装" 或 "添加到机器人"
- 根据技能要求配置相关参数（如 API 密钥等）
常用技能介绍
3管理已安装技能
在机器人技能页面可以：
- 查看已安装：查看机器人当前安装的技能
- 启用/禁用：临时开启或关闭某个技能
- 卸载：移除不需要的技能
- 配置技能：根据需要调整技能参数
💬 如何和机器人聊天？
与机器人聊天是 MonkeyBot 最核心的功能。你可以像和朋友发消息一样与 AI 交流。
1选择机器人
在首页点击机器人卡片，或在聊天页面从机器人列表中选择要对话的机器人。
2发送消息
在输入框中输入你的问题或请求，按 Enter 或点击发送按钮即可。
📝 聊天示例
- 问答："什么是机器学习？"
- 写作："帮我写一封辞职信"
- 编程："用 Python 写一个快速排序"
- 搜索："帮我搜索今天有什么科技新闻"
- 文件："读取工作空间的 README.md 文件"
3查看回复
机器人会实时流式输出回复，你可以看到文字逐字出现，就像真人在打字一样。回复中可能包含：
- 文本内容：机器人的回复文本
- 技能执行：机器人调用的技能和执行结果
- 文件链接：生成的文件或图片链接
4对话管理
- 历史记录：首页显示最近的对话记录
- 继续对话：点击历史记录继续之前的对话
- 新建会话：点击"新对话"开始新的对话
💡 聊天技巧
- 描述越具体，回复越准确：尽量详细地描述你的需求
- 利用上下文：可以在同一对话中追问，机器人会记住之前的内容
- 分步执行：复杂任务可以拆分成多个步骤
🧬 机器人记忆与经验
MonkeyBot 具有记忆系统，机器人可以在对话中记住重要信息，越用越智能。
记忆类型
1经验管理
在经验页面可以：
- 查看经验：查看机器人积累的经验
- 添加经验：手动添加重要信息作为经验
- 编辑/删除：管理已有的经验条目
2SOP 流程
SOP（Standard Operating Procedure）是可重复执行的标准化流程：
- 创建 SOP：在工作空间编写 SOP 文档
- 定时执行：设置定时任务自动执行 SOP
- 手动触发：在对话中让机器人执行特定 SOP
🧠 使用建议
- 重要信息不要仅依赖记忆，建议保存到文件
- 定期整理工作空间文件
- 利用 SOP 自动化重复性任务
📱 手机 SOP：录屏生成与真机执行
如果你想让 Robot 根据一段手机操作录屏生成 SOP，并继续在真机上自测、回归和修复，可以直接使用 手机 SOP Builder。这一套流程当前分成两个对象：
- Job：一次“录屏/录制 -> AI 生成草稿”的任务
- Execution：一次“拿当前草稿去真机执行”的运行记录，可能是自动自测、手动执行、回归执行或修复验证
你会看到的入口
- 机器人工作空间：上传录屏文件、查看
assets/ / sop/ / tasks/ 产物
- 手机 SOP Builder：创建 mobile job、预览步骤、审核保存、查看 execution 历史
- 工作空间任务面板：会把真机执行显示为
MobileExecution，并提供 "打开 Job" / "打开 Execution"
1先准备设备或录屏素材
这一步先决定你是走“在线录制”还是“上传现成录屏”：
- 在线录制：适合你现在就拿一台已绑定的 Android 真机现场演示，系统会边录边采集元数据
- 上传录屏：适合已有 MP4，先把视频放进机器人工作空间，再让后端做视频解析生成草稿
📌 建议做法
- 录屏文件优先上传到
assets/mobile-recordings/ 目录，方便后续追踪和复盘
- 在线录制本身主要依赖手机端 recorder 在线，不要求你手动先用 ADB 开始录制；但当前设备在线状态仍沿用 ADB 探测，所以设备列表里最好仍保持 ADB 可连
- 真机执行 / 自测阶段需要 ADB，可先确认设备在线、ADB 可用、目标 App 已安装且能正常打开
- 如果流程依赖登录态，建议先完成一次真实登录，后续审核时再决定是否开启“执行前置注入”
2打开“手机 SOP Builder”创建任务
进入机器人详情页的 SOP 页面后，打开 手机 SOP Builder。页面顶部会按四步走：
- 填写任务标题：例如“北京交警办理进京证”
- 开始录制：选择设备在线录制，或展开高级入口导入已有 session / 上传录屏
- 预览草稿：先看识别出来的步骤、警告和生成方式
- 审核保存：确认 Markdown / YAML 后保存到正式 SOP 列表
3两种生成路径怎么用
路径 A：在线录制生成
- 在 Step 2 选择一台设备
- 点击 "开始手机录制"
- 在手机上按真实业务流程操作
- 结束后点击 "结束录制并生成草稿"
路径 B：上传录屏生成
- 在 Step 2 展开 "高级方式"
- 在 "上传录屏文件" 里选择 MP4
- 点击 "上传录屏并生成草稿"
- 系统会先把文件放到工作空间
assets/mobile-recordings/，再创建一个 video_upload job
⏱️ 生成中会发生什么
生成完成前，Job 会经历“排队 / 处理中 / 已完成或失败”等状态。你不需要一直停留在当前页；后续可以从历史列表重新打开同一个 Job。
4先复核草稿，再决定是否保存
Step 3 的“预览草稿”是最重要的人工检查点。这里建议重点看：
- 步骤顺序：是否真的按你的业务流程排列
- 关键动作：点击、输入、滑动有没有识别出来
- 动态内容：日期、地点、手机号、验证码、搜索词等是否被错误写死
- 应用信息：包名、页面上下文、目标控件描述是否合理
- 警告信息：如果页面提示当前是待人工审核的回退草稿，说明你最好先补全动作再继续执行
确认无误后，在 Step 4 点击保存。保存后，这条记录会进入正式 SOP 列表，同时当前 mobile job 会被标记为已审核。
5怎么看 Job、Execution 和运行产物
生成完成后，你会在页面里看到一组和执行相关的入口：
- "打开 Job"：查看这次生成任务本身，包括来源、草稿、分析结果和状态
- "打开 Execution"：查看某一轮真机执行记录
- "打开运行结果"：查看本轮执行输出的结果文件
- "打开产物目录"：查看截图、运行日志、失败上下文等调试产物
当前版本里，Execution 一般由系统自动自测、Robot 工作流或后端执行接口触发；一旦开始执行，结果会回流到当前页面和工作空间任务面板。
另外，机器人工作空间页的任务面板会把这些执行展示成 MobileExecution。如果某一轮执行已经开始，你可以直接从任务面板点击回到对应 Job 或 Execution。
如何理解执行来源
- 自动自测：系统基于当前草稿自动发起的首轮验证
- 手动执行：通过执行 API 或 Robot 主动发起的一轮执行
- 回归执行：修改草稿后的再次验证
- 修复验证：前一轮失败后，系统基于失败信息修订步骤后再次跑的验证
6执行失败后怎么看、怎么继续
手机 SOP 的执行失败并不等于整条链路失败。正确的排查方式是：
- 先看当前 Execution 的 执行状态、当前步骤 和 结果信息
- 再打开 "运行结果" 和 "产物目录"，检查截图、点击位置、输入前后状态是否合理
- 如果系统已经触发 repair_validation，继续查看新的一轮 Execution，不要只盯着第一轮失败结果
- 如果问题是业务数据写死、文案不稳定、控件描述太弱，返回草稿页补 YAML/Markdown 后重新验证
✅ 当前版本最重要的使用建议
- 模型负责理解录屏，但最终执行稿仍然需要你复核，尤其是输入内容、动态日期和页面分支
- 优先把视频、生成稿、执行产物都留在同一个机器人工作空间里，方便回看
- 如果你只看到 Job，没有看到 Execution，通常表示还没有触发真机执行，或当前设备信息不足以启动自测
- 排查时优先看产物，不要只看一句“执行失败”；很多问题从截图和点击位置能立刻定位
🎯 使用场景示例
以下是机器人结合工作空间、技能和沙箱的典型使用场景：
📁 场景一：代码项目助手
在机器人工作空间的 repos/ 目录中克隆你的代码仓库，机器人可以读取、分析和修改代码。通过代码执行技能，机器人能在沙箱环境中运行测试、执行构建命令。你可以让机器人"帮我检查这个项目的测试覆盖率"、"重构这个函数"、"为新功能编写单元测试"。所有代码修改都保存在独立的工作空间中，不影响宿主机环境。
📊 场景二：数据分析助手
将数据文件上传到机器人工作空间，使用数据库技能在沙箱中执行 SQL 查询分析。机器人可以生成图表、导出分析报告到 downloads/ 目录。支持处理 CSV、JSON、Excel 等格式数据。例如："分析这份销售数据，找出增长最快的产品类别"、"用 SQL 查询上个月的订单统计"。沙箱环境确保数据分析的安全隔离。
🌐 场景三：信息采集助手
配置网页搜索和网页抓取技能，机器人可以自动搜索互联网信息、抓取网页内容并保存到工作空间。结合定时任务，可以定期采集行业新闻、竞品动态等。抓取的内容存储在 downloads/ 或自定义目录，方便后续分析。例如："每天早上抓取科技新闻并生成摘要"、"监控竞品网站的价格变化"。
📝 场景四：文档处理助手
上传文档到工作空间，机器人可以读取、总结、翻译或改写文档内容。支持 Markdown、PDF、Word 等格式。处理后的文档保存回工作空间，可随时下载。结合 SOP 功能，可以定义标准的文档处理流程。例如："将这份技术文档翻译成英文"、"生成这份报告的摘要"、"按照模板格式整理这些会议记录"。
🤖 场景五：自动化运维助手
通过沙箱桌面环境，机器人可以操作浏览器执行自动化任务，如登录系统查看状态、定时检查服务健康、自动化填报等。工作空间中存储脚本和配置文件，定时任务按计划自动执行。安卓设备绑定后，还可以自动化操作手机 APP。例如："每天检查服务器状态并发送报告"、"自动化完成月度报表填报"、"监控 APP 的新版本发布"。
🧠 机器人架构（进阶了解）
MonkeyBot 采用仿生学设计，每个机器人有以下"器官"：
🧠
NeuralCenter
神经中枢，负责安全检查、流量控制和情感分析
🫁
Cerebellum
小脑，负责反射动作（系统1），快速自动响应
🧩
Cerebrum
大脑，负责深度思考（系统2），LLM 推理规划
👄
Mouth
嘴巴，负责输出格式化，将结果呈现给你
📋 状态说明
机器人在不同状态下会有不同表现：
- 🟢 Idle - 空闲状态，随时响应
- 🔵 Reflexing - 反射模式，快速自动回复
- 🟣 Thinking - 思考模式，深度推理中
- 🟠 Acting - 执行模式，正在执行任务
- ⚫ Exhausted - 疲劳状态，需要休息
- ⚪ Rest - 休息中
❓ 常见问题
Q: 如何修改机器人的模型？
进入机器人详情页，点击"编辑"，可以在模型配置中更改使用的 LLM 模型。
Q: 支持哪些模型？
支持 OpenAI (GPT-4/GPT-4o)、Claude、智谱 GLM、通义千问、DeepSeek、月之暗面等主流大语言模型，也支持通过 OpenAI 兼容接口接入本地模型（如 Ollama）。
Q: 为什么回答有时候很慢？
深度思考和执行复杂任务需要更长时间。如果机器人正在执行技能（如搜索、文件操作），响应时间会更长。
Q: 如何提升响应速度？
1. 选择更快的模型（如 GPT-4o-mini）
2. 简化提示词，减少不必要的上下文
3. 减少同时启用的技能数量
Q: 如何配置凭证？
在机器人详情页的"凭证"标签中，可以添加各种 API 密钥。支持多种凭证类型，机器人会根据需要自动使用对应的凭证。
Q: 数据安全吗？
所有对话数据存储在本地数据库中，API 密钥等敏感信息会加密存储。建议不要在对话中透露密码等敏感信息。
Q: 如何接入飞书/微信？
在机器人详情页的"频道绑定"中，可以配置飞书或微信的机器人对接。需要先在飞书/微信开放平台创建应用并获取凭证。
🔧 技术信息
WebSocket 协议
MonkeyBot 使用 ACP (Agent Communication Protocol) 协议进行实时通信。主要方法包括：
ping - 心跳检测robot/ping - 机器人状态检测session/new - 创建新会话session/load - 加载已有会话session/prompt - 发送消息session/cancel - 取消当前任务
机器人运行模式
🐳
沙箱模式
机器人在 Docker 容器中隔离运行
🆘 需要帮助？
如果遇到问题，可以：
1. 查看浏览器控制台日志
2. 检查服务器日志
3. 访问 GitHub 提交 Issue