1. 项目概述一个能帮你“跑腿”的自主AI助手如果你和我一样经常在Discord、Slack、iMessage和Signal这几个聊天软件之间来回切换同时电脑上还开着十几个终端窗口处理各种杂事那你肯定幻想过能有一个“数字管家”。它最好能看懂你在聊天软件里随口提的需求比如“查一下服务器日志里最近的错误”、“帮我给团队发个下周会议提醒”然后自己默默去执行最后把结果贴回聊天窗口。今天要聊的Angel就是这样一个从幻想走进现实的项目。它不是一个简单的聊天机器人而是一个拥有“持久记忆”和“多任务执行”能力的自主AI智能体。你可以把它理解为一个24小时在线的全能型个人助理只不过它的“大脑”是GPT等大语言模型而“手脚”则是一套包含了36个内置工具的庞大系统。Angel的核心价值在于它将大语言模型的推理能力与真实世界的操作接口无缝衔接了起来。你不再需要离开熟悉的聊天环境去打开命令行或者写脚本。你只需要像跟同事聊天一样告诉Angel“帮我看看项目根目录下所有.log文件里今天有没有出现ERROR级别的日志有的话把文件名和错误行发给我。”它就能理解你的意图调用bash工具执行grep命令再用glob工具匹配文件最后把整理好的结果发回给你。整个过程是自动的、连贯的。更关键的是它记得住事情。你上次让它关注的服务器你提过的项目命名习惯甚至你偏好用什么格式看报告它都会通过内置的持久化记忆系统记录下来并在后续的对话中作为上下文参考。这使得与它的交互更像是在培养一个逐渐了解你工作习惯的伙伴而不是每次都要从头解释的机器。2. 核心架构与设计哲学为什么Angel不是另一个ChatGPT插件市面上基于大语言模型的自动化工具不少但Angel的设计有几个显著的不同这些不同直接决定了它的实用性和安全性。理解这些设计哲学能帮你更好地判断它是否适合你的场景。2.1 多通道优先与统一抽象层很多AI工具只支持单一平台比如一个Discord机器人或者一个Slack应用。Angel从一开始就采用了多通道适配器架构。在src/channels/目录下每个通讯平台Discord, Slack, iMessage, Signal都有一个独立的适配器模块它们都实现了一个统一的Channel接口。这个设计的好处是核心的AI智能体逻辑在src/agent.ts中完全不需要关心消息来自哪里。它只处理抽象的“消息”对象包含发送者、内容、聊天ID等信息。这意味着你在Slack里给Angel安排的任务稍后可以在Discord里查询进度或者你在iMessage上让它记下的一个想法之后在Signal上让它基于这个想法执行操作。所有通道的对话历史和记忆是打通的形成了一个统一的交互平面。这种设计对开发者也很友好。如果你想为Angel添加对Telegram或钉钉的支持理论上你只需要在channels目录下新建一个适配器文件实现那几个标准的方法发送消息、接收消息、处理连接等核心业务逻辑完全不用动。项目通过src/config.ts统一加载YAML配置动态启用或禁用各个通道实现了高度的可配置性。2.2 工具循环与自主决策引擎Angel的核心工作流程被称为“工具循环”Tool Loop这是它实现“自主性”的关键。这个过程在src/agent.ts的processMessage函数中实现我们可以拆解一下意图解析当收到一条用户消息后Angel首先会结合当前的对话历史和相关的长期记忆使用大语言模型默认是OpenAI的GPT-4系列来分析用户的意图。模型需要判断这是一个简单的问答还是一个需要执行操作的任务工具选择与参数提取如果判断需要执行操作模型会从已注册的工具列表中src/tools/registry.ts选择一个最合适的工具并尝试从用户消息中提取出该工具所需的参数。例如用户说“搜索一下最近关于Rust Web框架的文章”模型可能会选择web_search工具并提取出查询关键词“Rust Web框架”。安全审查与确认在工具执行前Angel会进行多层安全检查。首先是工具本身的守卫逻辑比如bash工具会检查命令是否匹配46种被禁止的危险模式。其次对于高风险操作如写入文件、执行特定shell命令它会触发安全词确认流程。这个流程非常巧妙它不是简单地问“你确定吗”而是会生成一个待处理的确认请求然后通过私聊DM向用户发送一个安全词。用户必须在私聊中回复这个精确的安全词操作才会继续。这有效防止了在群聊中误触发或恶意触发危险命令。工具执行与观察通过安全检查后工具被执行。执行结果成功输出或错误信息会被记录为一个“观察”Observation。循环与总结AI模型会分析这个“观察”决定下一步行动是任务已完成可以给用户最终回复还是需要继续调用另一个工具或者是参数不全需要反问用户这个“思考-行动-观察”的循环会持续进行直到模型认为任务已解决或达到最大迭代次数默认50次。最后Angel会将整个循环的过程和最终结果组织成一条连贯的回复发送给用户。这个循环使得Angel能够处理复杂的、多步骤的指令比如“先下载这个仓库然后找出所有TODO注释整理成一个Markdown文件发给我”。它会自己规划步骤依次调用bashgit clone、grep搜索TODO、write_file生成Markdown全程无需用户分步指导。2.3 持久化记忆系统从失忆症到长期伙伴没有记忆的AI助手就像金鱼每次对话都是新的开始。Angel的持久化记忆系统src/memory.ts是它的另一大亮点。它不仅仅是简单地保存聊天记录而是一个结构化的、可检索的、带反射机制的知识库。存储后端记忆主要存储在SQLite数据库中WAL模式确保性能和数据安全同时也支持将重要的记忆点以文件形式备份通过项目内的AGENTS.md机制。这种混合存储既保证了快速检索也提供了便于人类阅读的存档。记忆的写入与检索当对话产生有价值的信息时例如用户说“我的服务器IP是192.168.1.100”Angel可以通过write_memory工具主动存储。更重要的是它有一个可选的反射器Reflector功能。每隔一段时间默认15分钟反射器会扫描最近的对话自动提炼出关键事实、用户偏好、待办事项等并将其作为结构化的记忆存储起来。当处理新消息时read_memory和search_memory工具会被自动调用将相关的记忆作为上下文提供给AI模型从而实现连贯的对话。置信度评分与去重记忆系统不是简单的堆砌。search_memory工具会为每条检索到的记忆计算一个置信度分数分数低的记忆可能不会被采用。系统还能检测并合并重复或高度相似的记忆避免知识库变得臃肿和矛盾。例如如果你先后提到“我喜欢用VS Code”和“我的编辑器是VS Code”系统可能会将它们合并为一条关于“编辑器偏好”的强化记忆。这个记忆系统让Angel真正具备了学习能力。你教会它一次你的项目结构以后每次让它操作文件时它都能更准确地定位。3. 从零开始部署与深度配置指南纸上谈兵终觉浅我们来实际部署一个Angel。官方推荐使用Bun运行时它的启动速度和与TypeScript的原生兼容性确实是一大优势。3.1 基础环境搭建与初始化首先确保你的系统已经安装了Bun版本1.0以上。如果没有安装非常简便# 在macOS或Linux上 curl -fsSL https://bun.sh/install | bash # 或者通过包管理器如Homebrew brew install oven-sh/bun/bun接下来克隆仓库并安装依赖git clone https://github.com/plyght/angel.git cd angel bun install依赖安装完成后不要急着启动。最关键的一步是运行设置向导bun run setup这个交互式向导会引导你完成所有必要配置。它会询问你的OpenAI API密钥这是Angel的“大脑”然后逐一引导你配置想要启用的通讯通道。我强烈建议即使你熟悉YAML也至少运行一次这个向导因为它能帮你生成一个结构正确的基础配置文件~/.angel/config并验证一些基础连接。注意OpenAI API密钥是付费的请确保你的账户有足够的额度。对于日常个人使用GPT-4级别的模型消耗需要留意你可以在配置中先使用gpt-4o-mini这类成本更低的模型进行功能测试。3.2 通道配置详解与避坑实践配置文件的骨架在向导中已经生成但每个通道都有一些细节需要你特别注意否则很容易卡在连接阶段。Discord配置 向导会引导你创建Discord应用和机器人。这里最容易出错的是权限设置。在Discord开发者门户创建Bot时除了复制好token务必在“Bot”设置页面下的“Privileged Gateway Intents”里开启“Message Content Intent”。如果不开启你的机器人将无法读取消息内容变成一个“聋子”。配置项看起来是这样的channels: discord: enabled: true token: 你的Discord_Bot_TokenSlack配置Socket Mode是精髓 Slack的配置稍复杂但Angel采用了Socket Mode这省去了部署公共服务器和配置ngrok的麻烦极大简化了流程。你需要创建的是“从头开始”的App而不是从模板。在OAuth Permissions页面给Bot Token Scopes添加chat:write,app_mentions:read,im:history,im:read,im:write。这允许机器人发消息、读取提及、读写私信。转到Socket Mode页面点击启用。这会生成一个以xapp-开头的App-Level Token复制它。在Event Subscriptions页面启用事件并订阅message.im私信事件和app_mention提及事件。这里不需要填写Request URL因为Socket Mode不走Webhook。最后在Install App页面将应用安装到工作区获得以xoxb-开头的Bot User OAuth Token。 你的配置应该是channels: slack: enabled: true bot_token: xoxb-... # Bot User OAuth Token app_token: xapp-... # App-Level TokenSignal配置利用Google Voice Signal配置是门槛最高的因为它需要一个真实的手机号来注册Signal账户。对于个人测试一个高性价比的方案是使用Google Voice提供的免费美国电话号码。注册Google Voice并获取一个免费号码。在你的服务器或本地电脑上安装signal-cli一个Signal的命令行客户端。使用signal-cli用Google Voice号码注册Signal。命令执行后验证码会以短信形式发到Google Voice的网页版或App中。signal-cli -a 1你的GoogleVoice号码 register # 在Google Voice中查看短信获得验证码 signal-cli -a 1你的GoogleVoice号码 verify 收到的验证码配置Angel时account字段填这个Google Voice号码allowed_numbers列表里必须填上你个人手机号。这是最重要的安全设置只有列表里的号码发来的消息Angel才会处理。channels: signal: enabled: true account: 1你的GoogleVoice号码 allowed_numbers: - 1你的个人手机号 # 必须配置否则谁也联系不上机器人关键点allowed_numbers是发送者白名单。即使在群聊中如果发言者的号码不在白名单内即使他了Angel消息也会被静默忽略。这确保了控制权牢牢在你手中。iMessage配置仅限macOS 这可能是最“无缝”的体验让Angel直接融入你的苹果生态。前提是需要在macOS上安装imsg这个命令行工具来与系统通讯。通过Homebrew安装brew install imsg。配置相对简单主要是allowed_handles这个白名单。你可以填写联系人的电话号码或Apple ID邮箱。channels: imessage: enabled: true allowed_handles: - 8613901234567 # 手机号 - yourfriendicloud.com # 邮箱如果不配置allowed_handles则默认允许所有联系人。出于隐私考虑建议还是配置上。3.3 高级配置与性能调优基础通道配置好后你可以根据需求调整核心参数这些配置在~/.angel/config的顶层openai_api_key: sk-... # 也可用${OPENAI_API_KEY}环境变量 model: gpt-4o # 模型选择平衡速度、成本与能力 max_tokens: 8192 # 单次请求的最大token数影响上下文长度 max_tool_iterations: 50 # 工具循环最大次数防止死循环 timezone: Asia/Shanghai # 影响定时任务、日志时间等 memory: reflector_enabled: true # 是否启用记忆反射器 reflector_interval_ms: 900000 # 反射器运行间隔15分钟 compaction_threshold: 40 # 对话消息超过此条数时自动总结压缩节省上下文 working_dir_isolation: per_chat # 工作目录隔离策略per_chat表示每个聊天会话有独立目录 data_dir: ~/.angel # 数据存储根目录模型选择gpt-4o是目前性价比和能力的较好平衡。gpt-4-turbo上下文更长但稍慢。对于大量文本处理任务可以尝试gpt-4o-mini以降低成本。你甚至可以通过/model命令在运行时切换。记忆反射器如果觉得Angel“记性”不好可以检查reflector_enabled是否开启并适当缩短reflector_interval_ms比如改为300000即5分钟让它更频繁地整理记忆。工作目录隔离per_chat模式非常有用。当你在不同群聊或私聊中让Angel处理文件时它会为每个聊天创建一个独立的子目录在data_dir下避免文件互相污染。例如~/.angel/working_dirs/discord_123456789/。4. 核心工具链实战与经验技巧Angel的强大根植于其丰富的工具集。官方列出了36个内置工具我们可以将其分为几大类并结合实际场景看看怎么用。4.1 文件与系统操作你的远程终端bash,read_file,write_file,edit_file,glob,grep这几个工具组合起来几乎能覆盖所有本地文件操作。场景一日志分析与报告假设你的应用日志分散在/var/log/myapp/目录下以日期命名。你想快速查看今天有没有发生错误。你可以说“检查一下/var/log/myapp/目录下今天日期命名的日志文件中所有包含ERROR的行把文件名和错误内容摘要发给我。”Angel的思考过程调用glob工具匹配/var/log/myapp/app-$(date %Y%m%d).log这样的模式找到目标文件。对每个找到的文件调用grep工具搜索ERROR关键字。将grep的结果整理调用send_message或直接作为最终回复发给你。场景二代码库批量修改你想在所有Python文件的头部添加一个版权声明。你可以说“遍历当前目录下所有.py文件在文件开头插入一行# Copyright 2024 My Company。”Angel的思考过程调用glob工具匹配**/*.py。对每个文件调用read_file读取内容。在内存中构建新内容 版权声明行 原内容。调用write_file工具写回文件。注意这里会触发安全词确认因为这是批量写操作。实操心得edit_file工具比read_filewrite_file更智能。它利用LLM来理解你的编辑意图如“在函数foo的开头添加一段输入验证”而不是让你精确指定行号和内容。但对于简单的、确定性的插入/替换直接使用write_file指定完整新内容更可靠。4.2 网络、浏览器与搜索信息获取与自动化web_search,web_fetch,browser这三个工具构成了信息获取的闭环。web_search基于DuckDuckGo快速获取网络信息摘要和链接。适合“最近有什么新闻”、“某个概念是什么”这类查询。web_fetch获取特定URL的HTML内容。它有SSRF服务器端请求伪造保护会阻止向本地网络如192.168.*.*,10.*.*.*,127.0.0.1发起的请求这是一个重要的安全特性。browser基于Playwright的无头浏览器。这是功能最强大的工具。当web_fetch无法获取JavaScript渲染的内容时或者你需要与网页交互点击按钮、填写表单、截图时就必须用它。场景竞品价格监控你想每天上午10点检查某个电商网站上的商品价格。你可以先手动教Angel一次“打开浏览器访问https://example.com/product/123找到页面上显示价格的元素把价格文本读出来发给我。”Angel会使用browser工具执行并记录下这个过程。然后你可以使用schedule_task工具创建一个每天10点运行的定时任务任务内容就是上述浏览器操作步骤。从此每天你都会在指定时间收到价格推送。4.3 记忆、调度与子代理高级自动化核心这是Angel从“工具”升级为“智能体”的关键模块。记忆工具除了被动检索你可以主动管理记忆。例如你可以直接命令“记住我的个人博客项目在~/projects/myblog目录下。” 或者“搜索记忆中所有关于‘服务器部署’的记录。” 这让你可以像管理一个知识库一样与Angel互动。调度工具schedule_task支持Cron表达式和一次性任务。一个强大的用法是结合记忆和网络工具。例如创建一个任务“每周一上午9点搜索‘AI weekly news’将前三篇新闻的标题和链接总结后通过send_message工具发送到Discord的#news频道。” 这样你就拥有了一个全自动的资讯聚合机器人。子代理工具spawn_subagent允许Angel创建独立的子任务执行环境。想象一下这个场景你在主聊天中让Angel“帮我分析一下这个开源项目的代码结构”。它可以创建一个子代理专门负责克隆代码、运行代码分析工具、生成报告。而主代理可以继续和你聊别的事情。子代理有独立的对话上下文和工具循环最大深度2层最多并发4个防止资源耗尽。这对于处理耗时任务而不阻塞主交互流非常有用。外部编程代理spawn_coding_agent更进一步它可以调用像Claude Code、Aider、Goose这样的外部专用代码生成/编辑代理。你可以对Angel说“用Claude Code代理在~/project/src/目录下创建一个新的React组件Button.tsx要求是带波纹效果的可访问按钮。” Angel会启动Claude Code代理在后台工作完成后将结果通知你。这相当于为Angel装备了更专业的“编程外脑”。4.4 安全与确认机制把危险关进笼子Angel的安全设计是层层递进的这也是我能放心给它一定系统权限的原因。第一层命令模式黑名单。bash工具内置了46种被禁止的命令模式覆盖了rm -rf /、dd磁盘操作、curl上传敏感文件、安装后门、挖矿脚本等常见危险操作。这一层是静态的、硬性的。第二层文件访问控制。read_file/write_file等文件工具会检查路径禁止访问.ssh/,.aws/,.gnupg/, 包含secret或credential字样的文件、以及Angel自身的配置文件等敏感区域。第三层安全词确认。对于写文件、执行特定shell命令等操作会触发request_confirmation流程。Angel会生成一个随机的安全词如“blue-dragon-42”并通过私聊发送给你。你必须在私聊中原样回复这个词操作才会执行。这确保了任何关键操作都必须经过你本人的二次确认且确认过程在私密频道进行避免了群聊中的误触或恶意模仿。第四层通道级访问控制。每个通道都可以配置用户/号码白名单allowed_numbers,allowed_handles。不在名单上的人根本无法与Angel交互。在Signal群组中即使被非白名单用户Angel也会无视。这种设计哲学很清晰默认拒绝显式允许关键操作双重确认。在实际使用中我建议为安全词设置一个你容易记住但别人猜不到的短语可在配置中设置并定期更换。5. 扩展与定制打造属于你的专属助手Angel的架构是高度可扩展的你不必修改核心代码就能为其增加新能力。5.1 技能文件用自然语言教新本领这是最简单的扩展方式。在~/.angel/skills/目录下创建一个以.md结尾的文件比如git_operations.md。文件内容就是用自然语言描述如何完成一项任务。# Git 常用操作 当用户想要进行Git操作时我可以遵循以下步骤 1. 如果用户没有指定目录默认在当前工作目录或项目根目录如果已知下操作。 2. 对于git status直接执行bash工具运行git status。 3. 对于git pull先执行git fetch再执行git pull并报告是否有冲突。 4. 对于提交代码引导用户提供提交信息。如果用户说“提交所有更改”则执行git add -A git commit -m 用户提供的消息。 5. 记住用户常用的分支名称并在切换分支时进行提示。当Angel启动时它会加载所有技能文件并将其内容作为系统提示词的一部分。这相当于用自然语言给AI写了一份“工作手册”。虽然不像编程那样精确但对于规范复杂任务的流程非常有效。5.2 插件与钩子程序化扩展对于需要精确控制的行为可以使用插件和钩子。插件在~/.angel/plugins/目录下放置一个manifest.json文件可以定义新的工具Tools和聊天命令Commands。工具需要你编写TypeScript/JavaScript函数来实现具体逻辑然后通过manifest注册。这适合添加与特定API如你的内部部署系统、数据库交互的能力。钩子在~/.angel/hooks/目录下的JSON配置文件可以让你在特定事件发生时介入。目前主要支持before_llm钩子即在消息发送给LLM之前你可以修改消息内容或参数。例如你可以写一个钩子自动将所有用户消息翻译成英文后再发给GPT或者给特定用户的请求附加一个“用幽默口吻回答”的系统指令。5.3 集成MCP服务器连接外部工具宇宙模型上下文协议是一个新兴的开放协议旨在标准化LLM与外部工具/数据源的连接。Angel内置了MCP客户端集成src/mcp.ts。这意味着如果你有一个提供了MCP服务器的工具比如一个数据库查询工具、一个日历管理工具你只需要在Angel的配置中声明这个MCP服务器Angel就能在运行时动态加载该服务器提供的所有工具函数。这为Angel的能力扩展打开了无限可能无需等待Angel官方更新任何遵循MCP协议的服务都能即插即用。6. 常见问题、故障排查与优化实录在实际部署和长期使用中你肯定会遇到各种问题。以下是我踩过坑后总结的排查清单。6.1 连接与通信问题问题现象可能原因排查步骤Angel启动后在Slack中它没反应。1. Socket Mode未启用或Token错误。2. 事件订阅未正确配置。3. Bot未被邀请到频道。1. 运行bun run doctor检查Slack连接状态。2. 确认app_token(xapp-) 和bot_token(xoxb-) 无误且未过期。3. 在Slack应用配置页面确保message.im和app_mention事件已订阅。4. 在Slack频道中使用/invite 你的机器人将其加入。Signal消息发不出或收不到。1.signal-cli未正确注册或链接。2.allowed_numbers未配置或配置错误。3. 手机号格式问题。1. 手动运行signal-cli -a YOUR_NUMBER send RECIPIENT -m test测试signal-cli本身是否工作。2. 检查配置文件确保allowed_numbers里包含了你的个人手机号带国家代码如86。3. 国家代码务必正确1美国86中国等。iMessage在macOS上无法使用。1. 未安装imsg命令行工具。2. 没有授予终端“辅助功能”或“自动化”权限。1. 用which imsg检查是否安装。2. 前往“系统设置”-“隐私与安全性”-“自动化”确保终端或iTerm等应用有控制iMessage的权限。可能需要重启应用。Discord机器人能上线但不回复消息。1. 未开启“Message Content Intent”。2. 机器人权限不足。1. 前往Discord开发者门户在Bot设置中确认“MESSAGE CONTENT INTENT”已开启并保存。2. 重新生成Bot Token并更新配置文件。6.2 功能与性能问题问题现象可能原因解决方案Angel处理复杂任务时突然停止回复“达到迭代限制”。max_tool_iterations默认50设置过低任务步骤太多。1. 在配置文件中增加此值例如max_tool_iterations: 100。2. 优化你的指令尝试将其拆分成多个更小的、顺序执行的指令。对话长了之后Angel似乎“忘记”了之前的内容。上下文长度有限较早的消息被“挤”出去了。1. 确保compaction_threshold默认40生效它会自动总结长对话。2. 主动使用/memory命令查看和整理关键记忆点。3. 对于超长对话使用/new命令开启一个新会话。执行bash命令时被拒绝即使命令看起来无害。命令命中了46种禁止模式中的一种例如包含管道符后接curl可能被识别为潜在的数据渗出模式。使用web_fetch访问内网地址失败。SSRF保护机制阻止了对私有IP地址的请求。这是安全特性无法直接禁用。如果需要访问内网服务应通过browser工具如果服务有Web界面或在本机运行一个反向代理让Angel访问localhost上的代理端点。6.3 成本与优化建议使用GPT-4级别的模型成本是需要考虑的因素。以下是一些优化技巧模型降级对于简单的文件操作、信息查询任务在配置中或使用/model命令切换到gpt-4o-mini或gpt-3.5-turbo可以大幅降低成本。精简上下文鼓励Angel使用工具获取信息而不是在上下文中保留大量文本。例如让它“读取report.md文件并总结”而不是把整个文件内容粘贴到对话里。善用记忆把固定的、重要的信息如项目路径、服务器地址、常用命令通过记忆工具存储起来。这样AI在推理时可以直接检索记忆无需在上下文中反复提及节省token。明确指令模糊的指令会导致AI进行多轮思考和工具调用尝试。清晰的指令如“使用grep在/var/log/nginx/中搜索502错误”比“看看Nginx有没有问题”要高效得多。部署并深度使用Angel一段时间后最大的体会是它改变了人机协作的范式。它不再是一个需要精确指令的命令行也不是一个只能聊天的玩具。它成了一个处于模糊指令与精确执行之间的“翻译层”和“执行层”。你负责提出目标和方向它负责拆解、规划、执行并汇报。这种模式尤其适合处理那些琐碎、重复但又不至于完全自动化的工作流。当然赋予一个AI如此多的系统权限安全永远是第一位的。理解并善用其内置的多重安全机制是享受其便利的前提。从今天起试着让Angel成为你数字工作流中的一个沉默而高效的伙伴吧。