后端前端协同办公即时通讯企业应用CRMAI Agent人工智能【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址https://gitcode.com/GitHub_Trending/macro3/macro点击查看免费下载本文基于routinescrate 及其 AGENTS.md 指南拆解 Macro 中agent 定时任务routine功能的完整技术链路如何定义并校验RoutineTarget/RoutineSchedule等命令模型如何把六个 AI 工具注册进 MCP 与嵌入式 agent 的工具集以及RoutineClient如何以内部鉴权方式调用 scheduled-action 服务完成 CRUD 与即时执行。读完你将掌握该 crate 的职责边界、校验规则、HTTP 协议契约以及向其中新增一个 routine 工具的标准流程。1. 定位routines 在 Macro 中的角色routinescratecrates/routines/AGENTS.md是 Macro agent sessions 功能的一部分。它提供经过校验的 routinescheduled-action命令以及供 agent 使用的 AI 工具让 agent 能够为自己或另一个 persona/模型排定稍后运行的工作。AGENTS.md 对职责边界Scope给出了明确切分本 crate 拥有routine 命令的校验validation以及 agent 侧创建/管理 routine 的工具本 crate 不拥有cron 引擎与持久化的调度存储 —— 这些属于本 crateoutbound所调用的 scheduled-action 服务对应 crates/scheduled_action crate它拥有 scheduled-action 与 event-trigger 的 CRUD、dispatch、运行历史实际宿主进程在services/agent_harness_service的 scheduling 模块中。依赖与使用方在 Cargo.toml 与 AGENTS.md 的 Boundaries 一节中一致依赖ai_toolset、macro_authorizationaxumfeature、macro_user_id以及chrono、chrono-tz、cron、reqwest、schemars、serde、uuid等 workspace 依赖使用方是ai_tools。crate 的模块地图见 lib.rsdomain命令与RoutineService能力接口、inboundAI 工具、outboundHTTP 实现。2. 领域模型RoutineTarget 与 RoutineSchedule核心命令形状定义在 domain.rs 中两者都实现了Serialize/Deserialize/JsonSchema用于生成工具参数 schema并采用#[serde(tag type, rename_all snake_case)]的带标签枚举编码。2.1 RoutineTarget谁来执行/// Who executes the routine. Agent IDs refer to personas, never conversation IDs. pub enum RoutineTarget { /// A model running as Macro. Model { /// Runtime model ID. model: String, }, /// An agent with its configured runtime, tools and default model. Agent { /// Persona/bot UUID (bot.botId) from ListAgents. #[serde(rename agentId)] agent_id: Uuid, }, }domain.rs#L14-L28要点Model变体只接受一个运行时模型 IDroutine 以 Macro 身份 运行该模型Agent变体使用 persona/bot 的 UUID来自ListAgents的bot.botId文档注释明确警告agent ID 指的是 persona绝不是会话 ID想给自己排期就把自己的 persona ID 作为 agent target。2.2 RoutineSchedule一次性与周期性pub enum RoutineSchedule { /// Execute once at a future timestamp, even if the creating session has ended. Once { /// RFC3339 timestamp including UTC offset. at: DateTimeUtc, }, /// Repeat using a six-field cron expression and an IANA time zone. Cron { /// Seconds, minutes, hours, day-of-month, month, weekday (optional year). expression: String, /// IANA time zone, e.g. America/New_York. timezone: String, }, }domain.rs#L30-L45变体字段约束onceatRFC3339含 UTC 偏移必须严格晚于当前时间否则报错Choose a one-off time in the future.cronexpression六字段 cron、timezoneIANA 时区cron 必须可解析秒 分 时 日 月 周可选年份时区必须是合法 IANA 名称且cron.after(now)在目标时区下必须还有未来触发点否则报This schedule has no future runs.文件头注释点明了设计决策Commands use the schedulers existing cron engine, including single-year one-off schedules.—— 一次性任务不是单独机制而是复用调度器现有的 cron 引擎把Once转写成单年份的六字段 cron。RoutineSchedule::cron(now)domain.rs#L46-L86完成这一翻译返回(schedule, timezone)元组Once { at }断言at now后格式化为{sec} {min} {hour} {day} {month} * {year}年份放在第 6 字段时区统一归一为UTCCron先解析 cron 表达式再解析chrono_tz::Tz最后确认在now.with_timezone(zone)之后仍有触发点。domain/test.rs 用两个测试锁定了这些语义once_has_exactly_one_future_firing_and_normalizes_offsets输入2026-10-03T09:15:00-04:00断言时区归一为 UTC、从now起恰好只有一次触发2026-10-03T13:15:00Z且对已过去的时刻再调cron()返回错误recurring_schedules_validate_timezone_and_future_runs0 0 9 * * MON-FRIAmerica/New_York合法非法时区imaginary报错带过期单年份的0 0 9 1 1 * 2000因无未来运行而报错。2.3 RoutineConfiguration 与校验RoutineConfigurationdomain.rs#L88-L128是完整、用户可编辑的配置与执行簿记解耦字段为 camelCase字段说明name简短描述性名称必填非空instructions每次运行传给模型/agent 的指令必填非空target显式的模型或 agent 选择scheduleOnce或Cronrequired_apps每次运行需要的 Pipedream 应用列表app_slug 展示名在目标自身配置之外叠加用户必须已连接这些应用更新语义是整体替换想保留必须重新列出全部validate(now)的校验链是名称非空 → 指令非空 → 若为Model目标则模型 ID 非空 → 委托schedule.cron(now)完成调度校验。这个校验在两个时机生效outbound构造请求体之前见第 4 节以及服务端的最终权限检查AGENTS.md 注明target accessibility is checked server-side。2.4 返回形状与 RoutineService 能力接口domain 层还定义了返回结构RoutineInfoid/name/enabled/trigger/task/next_run_at其中trigger与task按调度器存储形态透传为serde_json::Value、RoutineList有界列表 总匹配数、RoutineDetails配置 至多 50 条最近运行记录、RoutineRunStarted即时运行启动确认含运行写入的 chat/agent session 引用。抽象能力由RoutineServicetrait 表达domain.rs#L173-L203注释强调authorization remains in the scheduler, never the tools方法语义create(user, config)为认证用户创建目标可访问性在服务端检查list(user)列出用户的 routine含指派给 agent 的read(user, id)读取可访问 routine 及其历史update(user, id, config)整体替换配置激活状态enabled保留set_enabled(user, id, enabled)独立于配置的暂停/恢复delete(user, id)永久删除 routine 与其调度run_now(user, id)立即启动一次计划外运行3. inbound暴露给 MCP 与嵌入式 agent 的六个 AI 工具inbound.rs 用routine_toolset()注册全部工具inbound.rs#L38-L46并定义了工具宿主注入的上下文/// Routine capability injected by each tool host; default is explicitly unavailable for test hosts. pub struct RoutineToolContext { /// Owning-service client. pub service: OptionArcdyn RoutineService, }service()在缺失时统一报错Routine tools are unavailable in this host.—— 默认测试宿主显式不可用身份request.user_id由宿主提供绝不来自模型参数。工具参数输出注解ToolAnnotationsCreateRoutineconfiguration: RoutineConfigurationRoutineInfoadditiveListRoutinesquery?匹配 name/instructions、enabled?RoutineListread_onlyReadRoutineroutine_idRoutineDetailsread_onlyUpdateRoutineroutine_id 恰好一个RoutineChangeRoutineInfodestructiveRunRoutineroutine_idRoutineRunStartedadditiveDeleteRoutineroutine_idDeletedRoutinedestructive idempotent注解对应 MCP 的readOnlyHint/destructiveHint/idempotentHint其语义定义在 annotations.rsReadOnly客户端可免逐次确认Additive只增不改不删Destructive覆盖或删除数据客户端必须先向用户提示。3.1 CreateRoutine工具描述即行为规范CreateRoutine的 schemars 描述inbound.rs#L47-L74本身就是一段写给模型的行为规范值得逐条理解排期给谁想排给自己用自己的 persona/bot ID 作为 agent target想委派从ListAgents中挑选可访问的 agent用其bot.botId以谁的身份运行Routines run as the authenticated user after this session ends—— 会话结束后仍以认证用户身份运行使用所选 agent 的工具与配置选哪种调度单次运行用Once 未来 RFC3339 时间戳重复用Cron回复中如何引用这也是 AGENTS.md 特别点出的一条在 Macro 应用内回复中把新建的 routine 写为m-document-mention{documentId:ID,documentName:NAME,blockName:routine}/m-document-mentionID/NAME 替换为返回的 ID 与名称外部 MCP 回复则遵循 MCP item-linking 说明反滥用约束不要用 reminder 去做本该执行的工作不要在某 routine 每次运行时自动再创建新 routine。3.2 ListRoutines客户端侧过滤 有界返回ListRoutinesinbound.rs#L91-L118拉取全部匹配项后在工具内做过滤enabled精确匹配 小写化子串匹配 name 与 task随后take(50)截断同时通过RoutineList.total返回截断前的完整匹配数描述中要求若被截断请收窄查询。历史细节则引导模型转用ReadRoutine。3.3 UpdateRoutine一次恰好一个变更意图为避免配置与激活状态被部分应用UpdateRoutine用带标签枚举RoutineChangeinbound.rs#L148-L162强制单次调用表达恰好一个意图Enabled { enabled }不重写配置地暂停/恢复走service.set_enabledConfiguration { configuration }整体替换 name/instructions/target/schedule走service.update激活状态保留描述要求先 ReadRoutine 再替换且*运行中的 routine 可以暂停但在结束前不能重新配置*。DeleteRoutine标记为 destructive 且幂等描述限定仅当用户明确要求删除 routine 时使用临时停止应改用UpdateRoutine暂停。4. outbound调用 scheduled-action 服务的受控 HTTP 客户端outbound.rs 实现了RoutineService的 HTTP 版本RoutineClient其设计在注释中概括为Authenticated, bounded HTTP calls to the scheduled-action service4.1 构造期约束RoutineClient::new(base, key)outbound.rs#L25-L49base URL 必须是http/https、有 host且不含用户名/密码/query/fragment否则报Invalid routine service URL内部密钥不能为空且被设为 sensitive header不出现在日志中传输层约束连接超时 5s、总超时 30s、禁用重定向、禁用自动重试retry(never())—— 对写操作不盲目重试重试语义交由上层错误信息提示Check ListRoutines before retrying a creation; the write may have succeeded。4.2 鉴权头与响应边界每个请求携带两个内部头常量定义见 macro_authorizationx-internal-auth-key内部 API 密钥来自应用配置而非模型参数x-internal-macro-user-id认证用户的MacroUserIdStr同样由宿主注入。响应侧做了双重体积防护outbound.rs#L76-L94先检查Content-Length再在流式读取中累计超过 2 MiB 即报Routine response is too large.。4.3 状态码到可操作错误信息的映射request_bytes将调度器状态码翻译成面向 agent 的可操作建议outbound.rs#L95-L107状态码转述给 agent 的信息200–299正常解析WireRoutine等400配置无效或模型/agent 不可用检查 schedule用ListAgents的bot.botId选可访问 agent422配置无效或requiredApps中的某个应用未连接/对所选 agent 不可用请用户用DiscoverConnectors给的链接连接或移除该项401 / 403 / 404routine 或目标对该用户不可用402用户的 AI 额度已用尽routine 当前无法运行409routine 正在运行或已被改动重新读取后再编辑其他服务不可用重试创建前先查ListRoutines4.4 与调度器服务的 Wire 契约RoutineService各方法对应的端点均相对 base即 scheduled-action 服务能力HTTP 请求createPOST scheduled-actionsbody 附加enabled: truelistGET scheduled-actions?include_eventstrue结果按最近优先反转readGET scheduled-actions/{id}GET scheduled-actions/{id}/historytake(50)updatePUT scheduled-actions/{id}set_enabledPUT scheduled-actions/{id}/enabledbody 仅{enabled: bool}deleteDELETE scheduled-actions/{id}run_nowPOST scheduled-actions/{id}/execute返回{action_id, resource?}真正的翻译器是configuration_bodyoutbound.rs#L241-L263先config.validate(now)再schedule.cron(now)然后组装调度器契约 ——kind: Agent、trigger: { type: cron, schedule, timezone }以及task{ prompt: , user_prompt: instructions, mcp_servers: [{ app_slug: linear, server_name: Linear }], model: model id // Model 目标时 // 或 agent: { bot_id: uuid } // Agent 目标时 }注意required_apps被映射为task.mcp_servers—— 这与 scheduled_action 的 AGENTS.md 中 Gotchas 一节互相印证A tasksmcp_serversare apps the routine requires保存时由TargetValidation检查、每次运行由RoutineSessions::prepare复查并只允许 agent 使用所选应用。outbound/test.rs 用真实 TCP socket 上的伪服务器验证了这些契约agent_tasks_do_not_silently_become_model_tasks_or_override_defaultsagent 目标的请求体只出现task.agent.bot_id与mcp_servers不含model也不夹带enabled/owner字段requests_forward_authenticated_identity_and_preserve_target_and_activation断言每个请求都携带x-internal-auth-key与x-internal-macro-user-id头创建请求以POST .../scheduled-actions开头且 body 含enabled: true更新不重发enabledset_enabled的 body 恰为{enabled: false}delete_and_run_now_call_the_owner_routes/run_now_explains_an_exhausted_ai_allowanceDELETE 204 成功、/execute返回的resource透传、402 时错误信息含 allowance。5. 接入 ai_tools工具如何进入各个宿主routinescrate 本身不决定宿主接线由ai_tools完成工具集注册ai_tools/src/lib.rs#L294 在tools_for_inner中通过.add_subtoolset::RoutineToolContext(routines::inbound::routine_toolset())把 routine 工具加入基础工具集因此Chat、AgentSession、ChannelBot、Mcp 四类宿主都能拿到这六个工具与 AGENTS.md 所称the AI toolset exposed to MCP and embedded agents一致客户端构建tool_context.rs#L1961-L1976 中build_routine_tool_context()用macro_service_urls::ScheduledActionServiceUrl::new()?按环境解析的服务 URL见 macro_service_urls与macro_auth::InternalApiKey::new()?构造RoutineClient测试宿主no_op_schedule_context()返回RoutineToolContext::default()service: None工具调用会得到本宿主不可用的明确错误而不是 panic。从源码结构看这套RoutineToolContext { service: OptionArcdyn RoutineService }的注入式设计使得同一份inbound工具实现可以面向不同的RoutineService实现生产用 HTTPRoutineClient测试用内存实现鉴权与凭据始终留在宿主与服务端工具参数中不存在任何秘密。6. 向 routines 新增一个工具AGENTS.md 的标准配方AGENTS.md 的 Recipes 一节给出了三步流程Add a routine tool:src/domain.rs(command/schema) →src/outbound.rs(HTTP call) →src/inbound.rs(tool registration)。结合现有代码落地清单为domain.rs定义/扩展命令与返回 schema#[derive(JsonSchema)]生成工具参数带标签枚举用rename_all保持 snake_case 线格式并把新操作加进RoutineServicetraitoutbound.rs在RoutineService for RoutineClient中实现 HTTP 调用复用request::T以获得鉴权头、体积上限与统一错误转述若引入新 wire 结构仿照WireRoutine/WireExecution写From转换inbound.rs定义工具结构体Deserialize JsonSchema#[schemars(title, description)]实现ToolAnnotated按实际影响选择read_only/additive/destructive与AsyncTool并在routine_toolset()中.add_tool::X, RoutineToolContext()注册。验证命令为cargo test -p routinesAGENTS.md 要求SQLX_OFFLINE未设置。相关规则文档指向create-ai-tool技能与 Rust 架构规则。7. 小结这套设计的关键取舍校验前置、授权后置domain层保证用户意图合法时间在未来、cron 可解析、时区合法而身份与目标可访问性检查全部留在调度器服务trait 注释authorization remains in the scheduler, never the tools复用而非新造调度机制Once被归一为单年份六字段 cron直接骑在现有 cron 引擎上避免双套调度语义面向 agent 的错误信息每个 HTTP 状态码都被翻译成下一步行动建议查ListRoutines再重试创建、用DiscoverConnectors连接应用、402 时说明额度问题让模型能自主纠错传输安全默认值禁重定向、禁自动重试、5s/30s 超时、2 MiB 响应上限、sensitive 内部密钥头、身份由宿主注入 —— 这些约束集中体现在RoutineClient::new与request_bytes中并有 socket 级集成测试逐条锁死。对希望深入实现的读者建议按 crates/routines/AGENTS.md 的 Start here 顺序阅读domain.rs命令形状与校验→ inbound.rs工具注册→ outbound.rsHTTP 契约再对照 domain/test.rs 与 outbound/test.rs 理解每条约束背后的测试证据调度器侧则继续读 crates/scheduled_action/AGENTS.md。赞分享后端前端协同办公即时通讯企业应用CRMAI Agent人工智能【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址https://gitcode.com/GitHub_Trending/macro3/macro点击查看免费下载相关推荐OpenBot定时任务Routines详解如何让你的AI同事自动按时工作OpenBot定时任务Routines详解如何让你的AI同事自动按时工作 OpenBot 是一个开源的 AI 同事AI Coworkers平台每个 AIClawe自动化定时任务全指南Routines让AI小队7x24小时自动开工Clawe自动化定时任务全指南Routines让AI小队7x24小时自动开工 Clawe 是一个多 Agent 协调系统就像给 OpenClaw 智能体用的AI Agent多智能体人工智能AI 应用任务调度前端后端ADK Long Horizon Harness 定时任务指南用 routine 工具编排无人值守的隔离沙箱任务ADK Long Horizon Harness 定时任务指南用 routine 工具编排无人值守的隔离沙箱任务 本篇技术指南聚焦 ADKAgent Dev示例工程人工智能AI Agent上一篇libwebsockets 深入解析用 minimal-mqtt-client-multi 构建多路并发 MQTT 客户端下一篇RuoYi-Vue-Plus 多租户后台管理系统把租户隔离、幂等与分布式调度写进声明式配置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
后端前端协同办公即时通讯企业应用CRMAI Agent人工智能【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址https://gitcode.com/GitHub_Trending/macro3/macro点击查看免费下载本文基于routinescrate 及其 AGENTS.md 指南拆解 Macro 中agent 定时任务routine功能的完整技术链路如何定义并校验RoutineTarget/RoutineSchedule等命令模型如何把六个 AI 工具注册进 MCP 与嵌入式 agent 的工具集以及RoutineClient如何以内部鉴权方式调用 scheduled-action 服务完成 CRUD 与即时执行。读完你将掌握该 crate 的职责边界、校验规则、HTTP 协议契约以及向其中新增一个 routine 工具的标准流程。1. 定位routines 在 Macro 中的角色routinescratecrates/routines/AGENTS.md是 Macro agent sessions 功能的一部分。它提供经过校验的 routinescheduled-action命令以及供 agent 使用的 AI 工具让 agent 能够为自己或另一个 persona/模型排定稍后运行的工作。AGENTS.md 对职责边界Scope给出了明确切分本 crate 拥有routine 命令的校验validation以及 agent 侧创建/管理 routine 的工具本 crate 不拥有cron 引擎与持久化的调度存储 —— 这些属于本 crateoutbound所调用的 scheduled-action 服务对应 crates/scheduled_action crate它拥有 scheduled-action 与 event-trigger 的 CRUD、dispatch、运行历史实际宿主进程在services/agent_harness_service的 scheduling 模块中。依赖与使用方在 Cargo.toml 与 AGENTS.md 的 Boundaries 一节中一致依赖ai_toolset、macro_authorizationaxumfeature、macro_user_id以及chrono、chrono-tz、cron、reqwest、schemars、serde、uuid等 workspace 依赖使用方是ai_tools。crate 的模块地图见 lib.rsdomain命令与RoutineService能力接口、inboundAI 工具、outboundHTTP 实现。2. 领域模型RoutineTarget 与 RoutineSchedule核心命令形状定义在 domain.rs 中两者都实现了Serialize/Deserialize/JsonSchema用于生成工具参数 schema并采用#[serde(tag type, rename_all snake_case)]的带标签枚举编码。2.1 RoutineTarget谁来执行/// Who executes the routine. Agent IDs refer to personas, never conversation IDs. pub enum RoutineTarget { /// A model running as Macro. Model { /// Runtime model ID. model: String, }, /// An agent with its configured runtime, tools and default model. Agent { /// Persona/bot UUID (bot.botId) from ListAgents. #[serde(rename agentId)] agent_id: Uuid, }, }domain.rs#L14-L28要点Model变体只接受一个运行时模型 IDroutine 以 Macro 身份 运行该模型Agent变体使用 persona/bot 的 UUID来自ListAgents的bot.botId文档注释明确警告agent ID 指的是 persona绝不是会话 ID想给自己排期就把自己的 persona ID 作为 agent target。2.2 RoutineSchedule一次性与周期性pub enum RoutineSchedule { /// Execute once at a future timestamp, even if the creating session has ended. Once { /// RFC3339 timestamp including UTC offset. at: DateTimeUtc, }, /// Repeat using a six-field cron expression and an IANA time zone. Cron { /// Seconds, minutes, hours, day-of-month, month, weekday (optional year). expression: String, /// IANA time zone, e.g. America/New_York. timezone: String, }, }domain.rs#L30-L45变体字段约束onceatRFC3339含 UTC 偏移必须严格晚于当前时间否则报错Choose a one-off time in the future.cronexpression六字段 cron、timezoneIANA 时区cron 必须可解析秒 分 时 日 月 周可选年份时区必须是合法 IANA 名称且cron.after(now)在目标时区下必须还有未来触发点否则报This schedule has no future runs.文件头注释点明了设计决策Commands use the schedulers existing cron engine, including single-year one-off schedules.—— 一次性任务不是单独机制而是复用调度器现有的 cron 引擎把Once转写成单年份的六字段 cron。RoutineSchedule::cron(now)domain.rs#L46-L86完成这一翻译返回(schedule, timezone)元组Once { at }断言at now后格式化为{sec} {min} {hour} {day} {month} * {year}年份放在第 6 字段时区统一归一为UTCCron先解析 cron 表达式再解析chrono_tz::Tz最后确认在now.with_timezone(zone)之后仍有触发点。domain/test.rs 用两个测试锁定了这些语义once_has_exactly_one_future_firing_and_normalizes_offsets输入2026-10-03T09:15:00-04:00断言时区归一为 UTC、从now起恰好只有一次触发2026-10-03T13:15:00Z且对已过去的时刻再调cron()返回错误recurring_schedules_validate_timezone_and_future_runs0 0 9 * * MON-FRIAmerica/New_York合法非法时区imaginary报错带过期单年份的0 0 9 1 1 * 2000因无未来运行而报错。2.3 RoutineConfiguration 与校验RoutineConfigurationdomain.rs#L88-L128是完整、用户可编辑的配置与执行簿记解耦字段为 camelCase字段说明name简短描述性名称必填非空instructions每次运行传给模型/agent 的指令必填非空target显式的模型或 agent 选择scheduleOnce或Cronrequired_apps每次运行需要的 Pipedream 应用列表app_slug 展示名在目标自身配置之外叠加用户必须已连接这些应用更新语义是整体替换想保留必须重新列出全部validate(now)的校验链是名称非空 → 指令非空 → 若为Model目标则模型 ID 非空 → 委托schedule.cron(now)完成调度校验。这个校验在两个时机生效outbound构造请求体之前见第 4 节以及服务端的最终权限检查AGENTS.md 注明target accessibility is checked server-side。2.4 返回形状与 RoutineService 能力接口domain 层还定义了返回结构RoutineInfoid/name/enabled/trigger/task/next_run_at其中trigger与task按调度器存储形态透传为serde_json::Value、RoutineList有界列表 总匹配数、RoutineDetails配置 至多 50 条最近运行记录、RoutineRunStarted即时运行启动确认含运行写入的 chat/agent session 引用。抽象能力由RoutineServicetrait 表达domain.rs#L173-L203注释强调authorization remains in the scheduler, never the tools方法语义create(user, config)为认证用户创建目标可访问性在服务端检查list(user)列出用户的 routine含指派给 agent 的read(user, id)读取可访问 routine 及其历史update(user, id, config)整体替换配置激活状态enabled保留set_enabled(user, id, enabled)独立于配置的暂停/恢复delete(user, id)永久删除 routine 与其调度run_now(user, id)立即启动一次计划外运行3. inbound暴露给 MCP 与嵌入式 agent 的六个 AI 工具inbound.rs 用routine_toolset()注册全部工具inbound.rs#L38-L46并定义了工具宿主注入的上下文/// Routine capability injected by each tool host; default is explicitly unavailable for test hosts. pub struct RoutineToolContext { /// Owning-service client. pub service: OptionArcdyn RoutineService, }service()在缺失时统一报错Routine tools are unavailable in this host.—— 默认测试宿主显式不可用身份request.user_id由宿主提供绝不来自模型参数。工具参数输出注解ToolAnnotationsCreateRoutineconfiguration: RoutineConfigurationRoutineInfoadditiveListRoutinesquery?匹配 name/instructions、enabled?RoutineListread_onlyReadRoutineroutine_idRoutineDetailsread_onlyUpdateRoutineroutine_id 恰好一个RoutineChangeRoutineInfodestructiveRunRoutineroutine_idRoutineRunStartedadditiveDeleteRoutineroutine_idDeletedRoutinedestructive idempotent注解对应 MCP 的readOnlyHint/destructiveHint/idempotentHint其语义定义在 annotations.rsReadOnly客户端可免逐次确认Additive只增不改不删Destructive覆盖或删除数据客户端必须先向用户提示。3.1 CreateRoutine工具描述即行为规范CreateRoutine的 schemars 描述inbound.rs#L47-L74本身就是一段写给模型的行为规范值得逐条理解排期给谁想排给自己用自己的 persona/bot ID 作为 agent target想委派从ListAgents中挑选可访问的 agent用其bot.botId以谁的身份运行Routines run as the authenticated user after this session ends—— 会话结束后仍以认证用户身份运行使用所选 agent 的工具与配置选哪种调度单次运行用Once 未来 RFC3339 时间戳重复用Cron回复中如何引用这也是 AGENTS.md 特别点出的一条在 Macro 应用内回复中把新建的 routine 写为m-document-mention{documentId:ID,documentName:NAME,blockName:routine}/m-document-mentionID/NAME 替换为返回的 ID 与名称外部 MCP 回复则遵循 MCP item-linking 说明反滥用约束不要用 reminder 去做本该执行的工作不要在某 routine 每次运行时自动再创建新 routine。3.2 ListRoutines客户端侧过滤 有界返回ListRoutinesinbound.rs#L91-L118拉取全部匹配项后在工具内做过滤enabled精确匹配 小写化子串匹配 name 与 task随后take(50)截断同时通过RoutineList.total返回截断前的完整匹配数描述中要求若被截断请收窄查询。历史细节则引导模型转用ReadRoutine。3.3 UpdateRoutine一次恰好一个变更意图为避免配置与激活状态被部分应用UpdateRoutine用带标签枚举RoutineChangeinbound.rs#L148-L162强制单次调用表达恰好一个意图Enabled { enabled }不重写配置地暂停/恢复走service.set_enabledConfiguration { configuration }整体替换 name/instructions/target/schedule走service.update激活状态保留描述要求先 ReadRoutine 再替换且*运行中的 routine 可以暂停但在结束前不能重新配置*。DeleteRoutine标记为 destructive 且幂等描述限定仅当用户明确要求删除 routine 时使用临时停止应改用UpdateRoutine暂停。4. outbound调用 scheduled-action 服务的受控 HTTP 客户端outbound.rs 实现了RoutineService的 HTTP 版本RoutineClient其设计在注释中概括为Authenticated, bounded HTTP calls to the scheduled-action service4.1 构造期约束RoutineClient::new(base, key)outbound.rs#L25-L49base URL 必须是http/https、有 host且不含用户名/密码/query/fragment否则报Invalid routine service URL内部密钥不能为空且被设为 sensitive header不出现在日志中传输层约束连接超时 5s、总超时 30s、禁用重定向、禁用自动重试retry(never())—— 对写操作不盲目重试重试语义交由上层错误信息提示Check ListRoutines before retrying a creation; the write may have succeeded。4.2 鉴权头与响应边界每个请求携带两个内部头常量定义见 macro_authorizationx-internal-auth-key内部 API 密钥来自应用配置而非模型参数x-internal-macro-user-id认证用户的MacroUserIdStr同样由宿主注入。响应侧做了双重体积防护outbound.rs#L76-L94先检查Content-Length再在流式读取中累计超过 2 MiB 即报Routine response is too large.。4.3 状态码到可操作错误信息的映射request_bytes将调度器状态码翻译成面向 agent 的可操作建议outbound.rs#L95-L107状态码转述给 agent 的信息200–299正常解析WireRoutine等400配置无效或模型/agent 不可用检查 schedule用ListAgents的bot.botId选可访问 agent422配置无效或requiredApps中的某个应用未连接/对所选 agent 不可用请用户用DiscoverConnectors给的链接连接或移除该项401 / 403 / 404routine 或目标对该用户不可用402用户的 AI 额度已用尽routine 当前无法运行409routine 正在运行或已被改动重新读取后再编辑其他服务不可用重试创建前先查ListRoutines4.4 与调度器服务的 Wire 契约RoutineService各方法对应的端点均相对 base即 scheduled-action 服务能力HTTP 请求createPOST scheduled-actionsbody 附加enabled: truelistGET scheduled-actions?include_eventstrue结果按最近优先反转readGET scheduled-actions/{id}GET scheduled-actions/{id}/historytake(50)updatePUT scheduled-actions/{id}set_enabledPUT scheduled-actions/{id}/enabledbody 仅{enabled: bool}deleteDELETE scheduled-actions/{id}run_nowPOST scheduled-actions/{id}/execute返回{action_id, resource?}真正的翻译器是configuration_bodyoutbound.rs#L241-L263先config.validate(now)再schedule.cron(now)然后组装调度器契约 ——kind: Agent、trigger: { type: cron, schedule, timezone }以及task{ prompt: , user_prompt: instructions, mcp_servers: [{ app_slug: linear, server_name: Linear }], model: model id // Model 目标时 // 或 agent: { bot_id: uuid } // Agent 目标时 }注意required_apps被映射为task.mcp_servers—— 这与 scheduled_action 的 AGENTS.md 中 Gotchas 一节互相印证A tasksmcp_serversare apps the routine requires保存时由TargetValidation检查、每次运行由RoutineSessions::prepare复查并只允许 agent 使用所选应用。outbound/test.rs 用真实 TCP socket 上的伪服务器验证了这些契约agent_tasks_do_not_silently_become_model_tasks_or_override_defaultsagent 目标的请求体只出现task.agent.bot_id与mcp_servers不含model也不夹带enabled/owner字段requests_forward_authenticated_identity_and_preserve_target_and_activation断言每个请求都携带x-internal-auth-key与x-internal-macro-user-id头创建请求以POST .../scheduled-actions开头且 body 含enabled: true更新不重发enabledset_enabled的 body 恰为{enabled: false}delete_and_run_now_call_the_owner_routes/run_now_explains_an_exhausted_ai_allowanceDELETE 204 成功、/execute返回的resource透传、402 时错误信息含 allowance。5. 接入 ai_tools工具如何进入各个宿主routinescrate 本身不决定宿主接线由ai_tools完成工具集注册ai_tools/src/lib.rs#L294 在tools_for_inner中通过.add_subtoolset::RoutineToolContext(routines::inbound::routine_toolset())把 routine 工具加入基础工具集因此Chat、AgentSession、ChannelBot、Mcp 四类宿主都能拿到这六个工具与 AGENTS.md 所称the AI toolset exposed to MCP and embedded agents一致客户端构建tool_context.rs#L1961-L1976 中build_routine_tool_context()用macro_service_urls::ScheduledActionServiceUrl::new()?按环境解析的服务 URL见 macro_service_urls与macro_auth::InternalApiKey::new()?构造RoutineClient测试宿主no_op_schedule_context()返回RoutineToolContext::default()service: None工具调用会得到本宿主不可用的明确错误而不是 panic。从源码结构看这套RoutineToolContext { service: OptionArcdyn RoutineService }的注入式设计使得同一份inbound工具实现可以面向不同的RoutineService实现生产用 HTTPRoutineClient测试用内存实现鉴权与凭据始终留在宿主与服务端工具参数中不存在任何秘密。6. 向 routines 新增一个工具AGENTS.md 的标准配方AGENTS.md 的 Recipes 一节给出了三步流程Add a routine tool:src/domain.rs(command/schema) →src/outbound.rs(HTTP call) →src/inbound.rs(tool registration)。结合现有代码落地清单为domain.rs定义/扩展命令与返回 schema#[derive(JsonSchema)]生成工具参数带标签枚举用rename_all保持 snake_case 线格式并把新操作加进RoutineServicetraitoutbound.rs在RoutineService for RoutineClient中实现 HTTP 调用复用request::T以获得鉴权头、体积上限与统一错误转述若引入新 wire 结构仿照WireRoutine/WireExecution写From转换inbound.rs定义工具结构体Deserialize JsonSchema#[schemars(title, description)]实现ToolAnnotated按实际影响选择read_only/additive/destructive与AsyncTool并在routine_toolset()中.add_tool::X, RoutineToolContext()注册。验证命令为cargo test -p routinesAGENTS.md 要求SQLX_OFFLINE未设置。相关规则文档指向create-ai-tool技能与 Rust 架构规则。7. 小结这套设计的关键取舍校验前置、授权后置domain层保证用户意图合法时间在未来、cron 可解析、时区合法而身份与目标可访问性检查全部留在调度器服务trait 注释authorization remains in the scheduler, never the tools复用而非新造调度机制Once被归一为单年份六字段 cron直接骑在现有 cron 引擎上避免双套调度语义面向 agent 的错误信息每个 HTTP 状态码都被翻译成下一步行动建议查ListRoutines再重试创建、用DiscoverConnectors连接应用、402 时说明额度问题让模型能自主纠错传输安全默认值禁重定向、禁自动重试、5s/30s 超时、2 MiB 响应上限、sensitive 内部密钥头、身份由宿主注入 —— 这些约束集中体现在RoutineClient::new与request_bytes中并有 socket 级集成测试逐条锁死。对希望深入实现的读者建议按 crates/routines/AGENTS.md 的 Start here 顺序阅读domain.rs命令形状与校验→ inbound.rs工具注册→ outbound.rsHTTP 契约再对照 domain/test.rs 与 outbound/test.rs 理解每条约束背后的测试证据调度器侧则继续读 crates/scheduled_action/AGENTS.md。赞分享后端前端协同办公即时通讯企业应用CRMAI Agent人工智能【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址https://gitcode.com/GitHub_Trending/macro3/macro点击查看免费下载相关推荐OpenBot定时任务Routines详解如何让你的AI同事自动按时工作OpenBot定时任务Routines详解如何让你的AI同事自动按时工作 OpenBot 是一个开源的 AI 同事AI Coworkers平台每个 AIClawe自动化定时任务全指南Routines让AI小队7x24小时自动开工Clawe自动化定时任务全指南Routines让AI小队7x24小时自动开工 Clawe 是一个多 Agent 协调系统就像给 OpenClaw 智能体用的AI Agent多智能体人工智能AI 应用任务调度前端后端ADK Long Horizon Harness 定时任务指南用 routine 工具编排无人值守的隔离沙箱任务ADK Long Horizon Harness 定时任务指南用 routine 工具编排无人值守的隔离沙箱任务 本篇技术指南聚焦 ADKAgent Dev示例工程人工智能AI Agent上一篇libwebsockets 深入解析用 minimal-mqtt-client-multi 构建多路并发 MQTT 客户端下一篇RuoYi-Vue-Plus 多租户后台管理系统把租户隔离、幂等与分布式调度写进声明式配置创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
