mtor：面向AI编码智能体的Temporal工作流调度器\n\n## 背景：AI编码智能体的编排挑战\n\n随着大型语言模型能力的提升，AI编码智能体（如Goose、Zhipu、Droid等）正在从概念验证走向实际应用。这些智能体能够自动完成代码编写、调试、重构等任务，为软件开发带来了新的可能性。\n\n然而，当多个AI编码任务需要协调执行时，开发者面临一系列编排挑战：\n\n任务分发：如何根据任务特性选择最合适的AI提供商？不同智能体在不同类型的任务上表现各异，手动选择既繁琐又容易出错。\n\n状态管理：长时间运行的编码任务需要可靠的状态跟踪。任务可能因网络中断、资源限制或智能体故障而中断，如何确保任务能够恢复或重试？\n\n结果审查：AI生成的代码需要审查才能合并。如何自动化这一过程，同时确保代码质量？\n\n风险控制：某些操作（如删除文件、修改配置）具有较高风险，如何实施适当的管控措施？\n\n实验管理：当需要尝试新的实现方案时，如何在不污染主分支的情况下进行实验？\n\n## mtor的解决方案\n\nmtor（发音类似"motor"）是一个智能体优先的编码任务调度器，基于Temporal工作流引擎构建。它将AI编码任务视为可编排的工作流，提供了从任务分发到结果合并的完整生命周期管理。\n\n## 核心设计理念\n\n### 智能体优先的CLI设计\n\nmtor的CLI设计充分考虑了AI智能体的使用场景。每个命令都返回结构化的JSON响应，包含ok状态、执行结果、错误信息和建议的下一步操作。这种设计使得智能体能够轻松解析输出并做出决策。\n\n退出码也经过精心设计：\n- 0：成功\n- 1：通用错误\n- 2：用法错误（缺少必要参数）\n- 3：Temporal不可达\n- 4：工作流未找到\n\n智能体可以根据退出码快速判断问题类型并采取相应措施。\n\n### 基于Temporal的可靠执行\n\nTemporal是一个开源的持久化执行平台，专门用于编排微服务和无服务器函数。mtor利用Temporal提供：\n\n- 持久化状态：即使进程崩溃，工作流状态也能恢复\n- 自动重试：失败的操作可以按配置自动重试\n- 幂等性保证：相同的提示词生成相同的工作流ID，Temporal天然防止重复执行\n- 可观测性：完整的工作流历史便于调试和审计\n\n## 功能特性详解\n\n### 智能提供商路由\n\nmtor内置了基于关键词的智能路由机制，根据任务描述自动选择最合适的AI提供商：\n\n- 探索性查询 → droid：适合需要广泛搜索和探索的任务\n- Bug修复 → goose：在诊断和修复代码问题方面表现出色\n- 构建任务 → zhipu（默认）：通用的代码生成和构建任务\n\n用户也可以显式覆盖路由决策：\n\nmtor \"Fix the login bug\" --provider goose\n\n\n这种设计既提供了智能的默认行为，又保留了用户控制权。\n\n### 风险分级与管控\n\nmtor自动对任务进行风险分级（低/中/高）：\n\n- 高风险任务：包括删除操作、配置文件修改等，在分发响应中会被特别标记\n- 审批门控：高风险任务可以配置为需要人工审批后才能继续执行\n\n审批命令：\n\nmtor approve ribosome-zhipu-abc123\nmtor deny ribosome-zhipu-abc123\n\n\n这种分级机制在自动化和安全性之间取得了平衡。\n\n### Markdown提示词支持\n\nmtor支持从Markdown文件读取提示词，自动去除YAML frontmatter：\n\nmtor path/to/spec.md\n\n\n这对于复杂任务特别有用——可以将详细的需求说明、代码示例、约束条件等组织在Markdown文档中，而不是挤在命令行参数里。\n\n### 多任务规格拆分\n\n当Markdown文件包含多个任务部分（以## Task 1、## Task 2等标记）时，mtor会自动将其拆分为独立的工作流，同时共享相同的序言部分。这使得批量任务的提交变得简单高效。\n\n### 实验模式\n\nmtor提供了专门的实验模式，用于尝试新的实现方案：\n\nmtor -x \"Try a new approach to caching\"\n\n\n实验任务的特点：\n- 不自动合并到主分支\n- 保留在独立分支上供手动审查\n- 适合原型验证和方案对比\n\n这为AI辅助的代码实验提供了安全的环境。\n\n## 命令体系\n\nmtor提供了丰富的命令集，覆盖工作流的完整生命周期：\n\n### 核心命令\n\n- mtor "prompt"：分发任务\n- mtor list：列出最近的工作流\n- mtor status <id>：获取工作流详情\n- mtor logs <id>：获取最近30行输出\n- mtor cancel <id>：取消工作流\n\n### 审批命令\n\n- mtor approve <id>：批准延迟任务\n- mtor deny <id>：拒绝延迟任务\n\n### 运维命令\n\n- mtor doctor：健康检查\n- mtor deploy：同步并重启工作进程\n- mtor history：从JSONL日志查看近期运行历史\n- mtor checkpoints：列出失败运行的保存点\n- mtor schema：输出所有命令的JSON Schema\n\n这种分层设计既满足了日常使用的简洁性，又提供了深度运维的能力。\n\n## 架构与依赖\n\n### 系统要求\n\n- Python ≥ 3.11\n- 运行中的Temporal服务器\n- 执行编码任务的工作进程（如ribosome + translocase）\n\n### 配置方式\n\nmtor采用环境变量进行配置：\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| TEMPORAL_HOST | ganglion:7233 | Temporal服务器地址 |\n\n其他设置（任务队列、输出路径等）在代码中配置。这种设计简化了部署，同时保留了必要的灵活性。\n\n## 应用场景\n\n### 自动化代码维护\n\n将mtor集成到CI/CD流程中，自动执行常规的代码维护任务：\n- 依赖更新\n- 代码格式化\n- 文档生成\n- 简单的重构\n\n### AI辅助开发\n\n开发者可以通过自然语言描述需求，让mtor协调AI智能体完成实现：\n\nmtor \"Add user authentication with JWT tokens\"\n\n\n### 批量代码迁移\n\n利用多任务规格功能，可以批量提交代码迁移任务：\nmarkdown\n## Task 1\nMigrate auth module from CommonJS to ES modules\n\n## Task 2\nMigrate database module from CommonJS to ES modules\n\n## Task 3\nMigrate API routes from CommonJS to ES modules\n\n\n### 代码审查自动化\n\n结合Temporal的持久化能力，可以构建长时间运行的代码审查工作流，AI智能体审查代码后，根据预设规则自动合并或标记供人工审查。\n\n## 局限与展望\n\n### 当前局限\n\n- 依赖Temporal：需要部署和维护Temporal基础设施\n- 工作进程依赖：需要配套的工作进程（ribosome/translocase）实际执行编码任务\n- 提供商锁定：当前主要支持特定的AI提供商，扩展新提供商需要代码修改\n\n### 未来方向\n\n- 更多提供商支持：通过插件机制支持更多AI编码智能体\n- 可视化仪表板：提供Web界面查看工作流状态和结果\n- 智能重试策略：根据错误类型自动选择重试策略\n- 代码质量评分：集成静态分析工具，为AI生成代码自动评分\n\n## 结语\n\nmtor为AI编码智能体的编排提供了一个实用且可靠的解决方案。通过基于Temporal的持久化执行、智能的提供商路由、完善的风险管控和实验支持，它解决了将AI编码从玩具项目推向生产环境的关键障碍。对于正在探索AI辅助开发的团队来说，mtor是一个值得关注的工具。