本地AI开发代理实战：基于Cursor CLI与Jira/GitLab的自动化工作流

1. 项目概述一个运行在你Mac上的“数字替身”想象一下这个场景你正在享受午餐手机震动了一下你瞥了一眼是Telegram上的一条通知“[ACME] MR #42 已创建等待评审”。与此同时你的MacBook在后台悄无声息地打开了Cursor IDE开始分析一个刚刚指派给你的Jira工单它理解需求、编写代码、提交更改、创建合并请求并自动将工单状态更新为“待评审”。整个过程你除了喝了一口咖啡什么都没做。这就是autonomous-dev-agent所构建的现实。它不是一个运行在遥远云端的、需要你付费订阅的SaaS服务而是一个完全运行在你本地MacBook上的、由你掌控的自动化开发代理。它的核心思想极其简单将你日常开发流程中那些重复、机械、但又必须有人去做的“连接性”工作自动化让你能更专注于真正需要创造力和深度思考的部分。这个项目巧妙地扮演了一个“超级接线员”的角色。它监听你项目管理系统如Jira、GitHub Issues的动态驱动强大的AI编程工具Cursor Agent CLI来执行具体的开发任务与代码仓库GitLab、GitHub交互并通过你熟悉的通讯工具Telegram、Slack与你保持沟通。所有逻辑、所有凭证、所有数据流都发生在你的本地机器上~/.cursor/skills/目录就是它的大脑和保险箱。对于任何一位在Mac上进行软件开发、并频繁使用Jira/GitLab/GitHub进行团队协作的工程师来说这个项目都值得深入研究。它代表了一种务实、可控的AI辅助开发范式不追求全知全能而是精准解决“流程自动化”这个痛点将AI的能力无缝嵌入到你已有的、可信的工具链中。2. 核心架构与设计哲学拆解2.1 “本地优先”与“驱动层”架构这个项目的基石是“本地优先”哲学。在AI Agent领域充斥着各种云端服务、复杂中间件的今天autonomous-dev-agent反其道而行之选择了一条极简、可控的路径。所有组件都运行在你的Mac上通过launchdmacOS的系统服务管理器进行托管确保了服务在重启后能自动恢复。你的API令牌、项目配置等敏感信息只存在于本地的config.json和secrets.env文件中永远不会离开你的设备。这种设计带来了几个关键优势隐私与安全完全杜绝了因第三方服务数据泄露导致公司内部信息外流的风险。零延迟所有进程间通信都在本机进行响应速度极快。零额外成本除了你已有的工具Cursor、Jira等的订阅费用外没有新的SaaS支出。完全可控你可以随时查看日志、修改脚本、中断进程一切尽在掌握。为了实现这种灵活性项目采用了“驱动层”架构。你可以把它想象成一个可插拔的适配器系统。核心的Agent逻辑run-agent.sh并不直接与Jira或GitLab对话而是通过抽象的“驱动”接口。tracker驱动负责与任务追踪器如jira-cloud,github-issues交互host驱动负责与代码托管平台如gitlab,github交互chat驱动负责与通讯平台如telegram,slack交互。这种设计意味着混合匹配你可以为项目A配置 Jira GitLab Telegram为项目B配置 GitHub Issues GitHub Slack。易于扩展如果你想接入新的工具例如线性、飞书只需要按照规范实现一个新的驱动即可核心逻辑无需改动。依赖隔离每个驱动只引入自己必需的CLI工具如glab用于GitLabgh用于GitHub保持了整体环境的简洁。2.2 多项目管理从单兵作战到指挥中心v0.3版本引入的多项目支持是这个工具从“有趣的小脚本”升级为“生产力核心组件”的关键。在config.json中projects数组允许你定义多个独立的项目上下文。每个项目可以拥有独立的凭证例如为不同客户的项目使用不同的Telegram Bot Token。独立的AI模型为高优先级项目使用更强大也更昂贵的Claude Opus模型为日常维护项目使用更经济的Sonnet模型。独立的状态跟踪每个项目的Watcher状态、活跃运行记录、工作流缓存都隔离在cache/projects/id/目录下。这种设计完美匹配了现代开发者同时参与多个代码库的常态。通过Telegram命令/project list和/project use id你可以轻松地在不同项目的上下文之间切换。所有通知消息都会以[project-id]为前缀让你一眼就能分辨出当前警报来自哪个战场。实操心得模型成本控制在实际使用中将agent.model配置为claude-sonnet-4-5用于大多数功能开发任务完全足够。仅在处理极其复杂、需要深度推理的架构调整或Bug排查时临时通过Telegram命令切换到claude-opus-4-7-high。这能有效控制使用Cursor Agent CLI产生的成本因为不同模型的计费单位差异很大。2.3 与Cursor生态的深度集成这个项目的“智能”核心完全依赖于Cursor Agent CLI。它并没有自己实现一个AI代码生成或理解模块而是选择成为Cursor生态的“自动化外壳”。这样做的好处是直接站在了巨人的肩膀上即时获得最先进的AI能力Cursor团队对底层大模型如Claude、GPT的调优和工程化封装你直接受益。无缝的IDE上下文通过配置MCP服务器当Agent在Cursor中运行时它能直接读取Jira工单详情、GitLab MR评论、Figma设计稿甚至是公司内部文档库通过Context7。这赋予了Agent接近人类的上下文感知能力。统一的技能系统项目渲染生成的SKILL.md文件本质上是一个超级详细的“岗位描述”它被注入到Cursor Agent的上下文中指导Agent应该如何思考、如何行动、遵循哪些代码规范。这里的关键在于autonomous-dev-agent并不试图“取代”Cursor而是“赋能”它将其从被动的、需要人工触发工具转变为主动的、事件驱动的自动化执行引擎。3. 核心组件与工作流详解3.1 四大守护进程各司其职的自动化流水线安装后你的Mac上会运行四个主要的launchd服务它们共同构成了一个7x24小时不间断的自动化流水线。1. Agent Runner (com.user.autonomous-dev-agent.runner)这是核心的“大脑”执行器。它本身并不持续运行而是由Watcher或Telegram命令触发。当被调用时它会加载特定项目的配置和上下文。准备本次运行的详细提示词由prompts/目录下的模板渲染而成。调用cursor-agentCLI并附上SKILL.md和本次任务的详细指令。监控Cursor Agent的执行过程处理结果如提交代码、创建MR。更新Jira工单状态并通过Chat驱动发送通知。2. Watcher (com.user.autonomous-dev-agent.watcher)这是系统的“眼睛”和“耳朵”一个每2分钟运行一次的定时任务。它的职责是主动轮询发现需要Agent介入的事件Jira触发器检查是否有新的工单被分配给你或者已有工单的状态发生了变化例如从“待办”进入了“进行中”。GitLab/GitHub触发器检查你名下的MR/PR是否有新的评审评论或者CI/CD流水线是否失败了。事件路由一旦发现事件Watcher会根据规则判断是否需要以及如何触发Agent Runner。例如对于CI失败它可能直接通知Telegram等你一键确认后再重跑Agent。3. Telegram Handler (com.user.autonomous-dev-agent.telegram)这是你与Agent系统交互的“控制台”。它是一个长轮询服务持续监听Telegram Bot收到的消息。它解析你的命令并执行相应的操作状态查询/status查看当前所有项目或特定项目的运行状态。队列管理/queue查看等待处理的工单队列。直接控制/run ticket-key手动对某个工单启动一次Agent运行。审批交互当Agent创建的MR收到评论时它会推送卡片到Telegram你可以直接点击“Approve”或“Request Changes”按钮反馈会立刻同步到代码平台。4. Daily Digest (com.user.autonomous-dev-agent.digest)这是系统的“日报秘书”每天在指定时间可配置运行一次。它会汇总过去24小时的活动完成了哪些Jira工单。创建和合并了哪些MR。记录了多长时间的Tempo工作日志如果配置了Tempo驱动。给出一个简洁的摘要帮助你回顾一天的工作成果也为工作汇报提供了便利。这四个服务通过本地文件系统cache/目录下的状态文件和进程间信号进行协作形成了一个松耦合但高效的整体。3.2 关键配置文件解析一切皆可配置项目的可配置性极高几乎所有的行为都由两个文件控制config.json和secrets.env。理解它们的结构是进行高级定制的基础。config.json非敏感的身份与规则这个文件定义了“你是谁”以及“事情该如何做”。它包含几个主要部分owner: 你的基本信息如姓名、邮箱。这会被用于Git提交作者信息和一些通知模板。chat: 全局的聊天配置如默认的Telegram Chat ID。agent: 全局的Agent配置如默认的AI模型、运行超时时间等。projects: 核心的项目数组。每个项目需要详细定义tracker: Jira站点的URL、项目Key。系统会自动发现该项目的状态工作流并缓存。repositories: 一个对象键是仓库别名如web值是本地路径和远程GitLab/GitHub项目标识的映射。这允许一个Jira项目对应多个代码库。workflow.aliases:高级配置项。如果你的团队使用了非标准的Jira状态名称例如把“代码评审”叫做“Peer Review”你需要在这里建立语义意图到实际状态名的映射否则Agent可能无法正确推进工单。secrets.env敏感的凭证所有API令牌、访问密钥都存放在这里。它是一个标准的.env文件格式。安全是关键该文件被.gitignore排除永远不会被意外提交。文件权限应设置为600(chmod 600 secrets.env)确保只有你能读取。每个驱动所需的凭证环境变量名在config.json中通过*Env字段引用如tokenEnv: TELEGRAM_BOT_TOKEN。注意事项凭证管理与安全最小权限原则在Jira、GitLab等平台创建API令牌时只授予该Agent所需的最小权限。例如GitLab的Token可能只需要api、write_repository权限不需要sudo或admin权限。定期轮换像对待密码一样定期更新这些令牌。autonomous-dev-agent的配置更新很简单重新运行bin/install.sh即可。隔离不同项目如果可能为不同的项目使用不同的Bot Token或API Token这能更好地隔离风险。3.3 技能提示词工程如何“教”会Agent做事SKILL.md文件是指导Cursor Agent行为的“宪法”。它不是在代码中硬编码的而是在安装时由SKILL.md.template模板结合你的config.json动态渲染生成的。这确保了每个安装的Agent技能都是为你量身定制的。一个典型的技能文件会包含以下章节你的角色明确告诉AI“你是一个由工程师[你的名字]控制的自动化软件开发助手”。核心工作流分步骤详细描述接到一个Jira工单后应该做什么。例如“1. 仔细阅读Jira描述和评论。2. 在本地代码库的对应分支上工作。3. 实现更改确保通过现有测试。4. 提交代码并推送到远程。5. 创建合并请求填写模板并指派给指定的评审者。”代码规范列出项目必须遵守的编码风格、提交信息格式如Conventional Commits、禁止的模式等。沟通协议规定如何更新Jira状态、如何在GitLab MR描述中引用Jira Key、如何编写有意义的提交信息。边界与限制明确什么不该做。例如“未经明确指示不要修改数据库架构或进行大规模重构。”“如果任务预估超过4小时应暂停并请求人工澄清。”prompts/目录下的模板文件则用于为每次具体的Agent运行生成更具体的指令。例如phase-planning.md.template可能包含“基于Jira工单{{TICKET_KEY}}{{TICKET_SUMMARY}}请制定一个实现计划。” 这些模板在运行时被填充为AI提供了高度情境化的任务简报。为什么这种设计有效因为大语言模型是高度依赖上下文的。一个泛泛的“帮我写代码”指令会导致不可预测的结果。而一个详细、具体、包含大量领域知识和约束条件的技能描述能将AI的输出范围收窄到可预测、可用的方向。这本质上是一种“提示词工程”的最佳实践在自动化领域的应用。4. 从零到一的完整安装与配置实战4.1 基础工具链与Cursor生态搭建安装的第一步是确保你的Mac满足基础条件。项目要求macOS 13并强烈依赖Homebrew作为包管理器。如果你还没有Homebrew安装它是第一步。/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)接下来安装核心依赖jq(JSON处理神器)、python3(用于一些辅助脚本)、curl和git。这些都是轻量级且广泛使用的工具。brew install jq python3 curl gitCursor IDE与CLI的安装是关键一步。这里有一个常见的误区只安装Cursor IDE图形界面是不够的必须同时安装其命令行工具cursor和cursor-agent。安装Cursor IDE通过brew install --cask cursor或从官网下载安装。在IDE内安装cursor命令打开Cursor按下CmdShiftP输入并执行 “Shell Command: Install cursor command in PATH”。这会将cursor命令链接到你的终端。安装Cursor Agent CLI这是驱动AI的核心。运行官方安装脚本curl https://cursor.com/install -fsS | bash这个脚本通常会将cursor-agent安装到~/.local/bin/。请确保该目录在你的PATH环境变量中。你可以通过echo $PATH检查如果没有可以在~/.zshrc或~/.bash_profile中添加export PATH$HOME/.local/bin:$PATH。登录与模型选择运行cursor-agent login进行认证。然后你可以在Cursor的设置中或者通过环境变量CURSOR_AGENT_MODEL来选择默认的AI模型如claude-sonnet-4-5。验证安装cursor --version # 应输出IDE版本 cursor-agent --version # 应输出CLI版本 cursor-agent whoami # 应显示你的Cursor账户信息4.2 驱动选型与凭证配置实战假设我们为一个典型的项目配置使用Jira Cloud作为任务追踪器GitLab作为代码托管平台Telegram作为通知渠道。1. Jira Cloud驱动配置安装无需额外安装使用curl和jq。凭证获取前往id.atlassian.com点击“API tokens”创建一个新令牌。同时准备好你的Jira账户邮箱。在secrets.env文件中添加ATLASSIAN_EMAILyour.emailcompany.com ATLASSIAN_API_TOKENyour_api_token_here在config.json的tracker配置中siteUrl是你的Jira实例地址如https://your-company.atlassian.netproject是项目Key如PROJ。2. GitLab驱动配置安装CLIbrew install glab认证运行glab auth login根据提示选择“GitLab.com”或“Self-hosted GitLab”并完成OAuth流程或使用Personal Access Token登录。验证glab auth status应显示已登录。在config.json的repositories部分gitlabProject的格式通常是namespace/project-name。3. Telegram驱动配置创建Bot在Telegram中搜索BotFather发送/newbot按提示操作最终你会获得一个Bot Token形如1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ。获取Chat ID将你的Bot添加到某个群组或直接与它对话。然后在浏览器中访问https://api.telegram.org/botYourBOTToken/getUpdates。给你Bot发送一条消息刷新页面在返回的JSON中查找message.chat.id字段的值这就是你的Chat ID。在secrets.env中添加TELEGRAM_BOT_TOKEN1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ在config.json的chat部分设置chatId为你获取到的数字ID。4. (可选) Tempo驱动配置如果你使用Tempo进行工时记录可以配置此驱动以实现自动日志建议。获取API Token登录Tempo Cloud进入设置 - API集成创建一个新的API令牌。在secrets.env中添加TEMPO_API_TOKENyour_tempo_token_here4.3 执行安装脚本与初始化向导克隆仓库并运行安装脚本是最后一步也是最关键的一步。git clone https://github.com/surohak/autonomous-dev-agent.git cd autonomous-dev-agent bash bin/install.shinstall.sh脚本会执行一系列有序的操作环境检查验证所有必需的命令行工具python3,jq,cursor,cursor-agent,glab/gh是否已安装并可访问。目录准备将项目文件复制到~/.cursor/skills/autonomous-dev-agent/目录下这是Cursor技能的标准存放位置。交互式初始化运行bin/init.sh。这是一个向导程序它会提示你输入config.json中的关键信息Jira站点、项目Key、你的名字等。引导你确认secrets.env中的各个令牌环境变量是否已正确设置。根据你的选择安装必要的驱动CLI如果尚未安装。模板渲染使用你提供的配置渲染SKILL.md.template和prompts/*.md.template文件生成最终的、包含你个人和项目信息的技能与提示词文件。服务部署根据你的配置尤其是不同的Telegram Token生成一个或多个*.plist文件到~/Library/LaunchAgents/并使用launchctl load命令加载它们使其在后台静默运行。SwiftBar集成如果检测到系统安装了SwiftBar会自动将状态栏插件脚本链接过去。安装完成后强烈建议运行诊断命令bash bin/doctor.sh --fix --smoke--fix参数会尝试自动修复一些常见的小问题如文件权限--smoke参数会对所有已配置的驱动进行一次端到端的连通性测试例如尝试从Jira读取一个工单向Telegram发送一条测试消息确保整个管道是畅通的。5. 高级使用技巧与故障排查实录5.1 自定义工作流与状态映射项目默认会尝试自动发现Jira项目的工作流状态。但很多团队会对标准工作流进行定制。例如你的团队可能将“等待合并”的状态命名为“Ready to Ship”而非“Ready for QA”。当自动发现失败或不符合预期时你需要手动配置workflow.aliases。首先通过bin/doctor.sh运行它通常会警告哪些语义意图intent未能找到对应的状态。然后在项目的config.json中添加如下配置{ id: myproject, tracker: { ... }, workflow: { aliases: { start: In Progress, // Agent开始处理工单时将工单移至此状态 push_review: Code Review, // 创建MR后将工单移至此状态 after_approve: Ready to Ship, // MR被批准后将工单移至此状态 done: Done, // MR合并后将工单关闭 block: Blocked, // 遇到阻碍时将工单移至此状态 unblock: In Progress // 解决阻碍后将工单移回进行中 } } }你需要登录Jira查看你的项目具体有哪些状态并将这些状态名精确地填写到映射中。配置完成后重新运行bin/install.sh使更改生效。5.2 利用MCP服务器增强Agent上下文MCPModel Context Protocol服务器是Cursor的一个强大功能它允许外部工具将数据以结构化的方式提供给AI模型。为autonomous-dev-agent配置MCP服务器能极大提升Agent处理任务时的“智商”。配置方法在Cursor IDE中打开设置Cmd,。导航到“MCP”设置项。点击“ Add new global MCP server”。对于官方插件如Atlassian, GitLab, GitHub, Slack, Figma通常只需点击对应的“Sign in”按钮完成OAuth授权即可。对于像Context7这样的第三方MCP服务器你需要手动编辑~/.cursor/mcp.json文件。例如添加Context7的配置可能如下所示{ mcpServers: { context7: { command: npx, args: [-y, upstash/context7-mcp], env: { CONTEXT7_API_KEY: your_key_here } } } }带来的好处Atlassian MCP当Agent分析Jira工单时它不再仅仅看到标题和描述还能直接读取附件、链接的子任务、相关的Confluence页面。GitLab MCPAgent在解决MR评论时能直接看到代码行级的讨论、CI流水线日志、甚至之前相关的合并请求。Context7 MCP如果你的公司有内部的文档Wiki或API文档站点将其接入Context7后Agent在编写代码时遇到不熟悉的内部库可以实时检索官方文档避免凭空想象。5.3 常见问题排查与解决方案即使安装顺利在实际运行中也可能遇到问题。以下是一些常见故障及其排查思路。问题1Watcher没有触发Agent处理新分配的Jira工单。检查步骤运行launchctl list | grep autonomous查看所有相关服务是否处于0运行中状态。如果状态码是78表示配置文件错误127表示命令未找到。查看Watcher日志tail -f ~/.cursor/skills/autonomous-dev-agent/logs/watcher.log。观察其轮询时是否报错如网络错误、认证失败。检查Jira工单的“经办人”字段是否确实设置为了你的账户与config.json中的owner.email匹配。Watcher只处理指派给“你”的工单。检查工单状态。Watcher可能只监听特定状态如“待办”或“已计划”的工单被指派的事件。查看scripts/lib/jira.sh中的过滤逻辑。解决方案根据日志修复认证或网络问题。确认工单指派和状态符合触发条件。必要时可以手动运行bash scripts/run-agent.sh PROJECT_ID TICKET_KEY测试Agent本身是否工作。问题2Agent运行失败Cursor CLI报错或生成了无意义的代码。检查步骤查看Agent运行日志tail -f ~/.cursor/skills/autonomous-dev-agent/logs/agent-*.log。检查SKILL.md文件内容是否被正确渲染特别是其中的项目路径、分支命名规则等是否准确。检查cursor-agent的模型设置和额度是否充足。运行cursor-agent whoami和cursor-agent usage。检查本次运行的提示词。日志中通常会打印出发送给Cursor Agent的完整提示词。检查其是否清晰、任务是否明确。解决方案凭证问题重新运行cursor-agent login。技能描述问题仔细审查并优化SKILL.md.template文件确保指令清晰、无歧义。可以加入更多具体的“不要做什么”的约束。上下文不足确保相关的MCP服务器已配置并运行为Agent提供更丰富的背景信息。任务过于复杂对于大型任务尝试在Jira中将其拆分为更小的子任务让Agent逐个击破。问题3Telegram Bot没有响应命令或发送通知。检查步骤确认secrets.env中的TELEGRAM_BOT_TOKEN正确无误且Bot未被禁用。确认config.json中的chat.chatId是数字ID且你的用户或群组已添加该Bot。查看Telegram Handler日志tail -f ~/.cursor/skills/autonomous-dev-agent/logs/telegram-handler.log。看是否有连接错误或消息解析错误。尝试在Telegram中直接向Bot发送/start命令看是否有响应。解决方案核对Token和Chat ID。确保网络可以访问Telegram API。检查launchd服务是否正常运行。问题4多项目配置下通知或操作混淆。现象收到了项目A的通知但内容却是项目B的。原因最可能的原因是不同项目配置中引用了同一个Telegram Bot Token和Chat ID但AGENT_PROJECT环境变量在服务运行时未正确隔离。解决方案为每个项目配置独立的Telegram Bot Token并确保在config.json的每个项目块中正确设置了chat.tokenEnv指向不同的环境变量。重新运行bin/install.sh会为每个唯一的Token生成独立的LaunchAgent服务从而实现完美隔离。5.4 性能调优与资源管理这个工具在后台运行多个服务虽然不占用大量CPU但需要注意资源管理。调整轮询间隔默认情况下Watcher每2分钟运行一次。对于项目活动非常频繁的场景这可能会产生较多的API调用。你可以修改scripts/watcher.sh中循环的sleep时间或者更优雅地在对应的LaunchAgent plist模板scripts/launchd/目录下中调整StartInterval的值单位为秒然后重新安装。管理日志大小日志文件默认位于~/.cursor/skills/autonomous-dev-agent/logs/。可以考虑配置日志轮转logrotate或者定期手动清理旧日志。监控Cursor Agent成本频繁或长时间运行复杂的Agent任务会产生费用。定期通过cursor-agent usage查看使用情况。在config.json的agent部分可以为不同项目设置不同的model将成本高的模型留给重要项目。处理“僵尸”进程极少数情况下Cursor Agent进程可能没有正常退出。可以定期检查ps aux | grep cursor-agent并手动结束无用的进程。6. 项目演进思考与扩展可能性使用autonomous-dev-agent一段时间后我最大的体会是它最好的地方不是替代你而是让你从繁琐的流程中解放出来从而更清晰地看到流程本身。你开始更仔细地设计Jira工单的描述因为你知道那是AI代理的“需求文档”你开始规范代码提交和MR模板因为那是自动化流水线的输入标准。这个项目目前处于v0.4驱动层架构已经非常清晰和稳固。它的扩展性主要体现在几个方向1. 开发新的驱动社区可以贡献更多驱动。例如Tracker驱动支持线性、ClickUp、Trello、Asana。Host驱动支持Gitea、Bitbucket Server。Chat驱动支持Discord、Microsoft Teams、飞书、钉钉。专用工具驱动例如一个“Sentinel”驱动当Agent提交的代码被安全扫描工具如Semgrep标记出高危漏洞时自动创建新的修复工单。2. 增强现有逻辑更智能的排程目前的Watcher是简单的轮询。可以引入优先级队列让高优先级或截止日期临近的工单优先被处理。成本监控与预警集成一个驱动当Cursor Agent的月度使用量或成本接近阈值时通过Telegram发送预警。代码质量门禁在Agent创建MR前强制运行一套本地的代码质量检查如静态分析、单元测试只有通过后才允许推送。3. 与本地开发环境更深度的融合IDE插件开发一个Cursor或VSCode插件提供一个GUI面板来查看和管理正在运行的Agent任务、队列状态甚至可以直接在IDE里对Agent生成的代码进行微调。语音交互结合本地的Whisper.cpp实现通过语音命令控制Agent“Hey Siri, 让Agent处理一下PROJ-123这个紧急bug”。这个项目的魅力在于它的“朴素”。它用简单的Bash脚本和清晰的架构证明了一个强大的自动化开发助手不必依赖于复杂的云原生架构。它就在你的笔记本电脑上完全听命于你这或许才是人机协作最踏实、最可控的形态。