Routines and headless

🤖 Cloud Code 核心概念学习笔记

一、 自动化执行模式 (Execution Modes)

• Routine (例程):
• 定义: 最直接的自动化方式，无需脚本或服务器。
• 构成: 提示词 (prompt) + 仓库 (repository) + 连接器 (connectors) 的打包。
• 运行环境: 在 Anthropix 管理的基础设施上运行。
• 触发方式: 触发器 (trigger)，如定时任务 (cron schedule)、API 端点 (HTTP post) 或 GitHub 事件 (e. g. , 新的 Pull Request)。
• 优势: 无需维护自己的机器或工作流文件。
• 适用场景: 适合重复性工作（Repeat work）。
• Headless Mode (无头模式):
• 定义: 允许用户在自己的脚本或应用程序中运行 Cloud Code。
• 使用方式: 通过命令行使用 -P 标志 (flag) 或别名。
• 特点: 作为一次性命令运行，无交互 (no interactive)，读取标准输入 (stdin)，写入标准输出 (stdout)，可像其他 Shell 工具一样通过管道 (pipe) 使用。
• 适用场景: 当任务需要用户自己的环境或外部逻辑时。
• Agent SDK:
• 定义: 一套库，允许将 Cloud Code 嵌入到用户自己的 TypeScript 或 Python 应用中。
• 特点: 暴露查询函数 (query function) 和与 Schema 相同的原语 (primitives)。
• 适用场景: 当工作需要集成到用户自己的产品中时。

二、 关键功能与限制 (Features & Constraints)

• Routine 限制 (Research Preview):
• 行为和限制仍在不断变化。
• 定时任务最长每小时运行一次。
• 每次运行都从默认分支的新克隆开始。
• 默认只能推送到 cloud/prefix 分支，以防止自主运行重写主分支（除非修改仓库级别的保护规则）。
• Headless Mode 优化 (Bear):
• --bear 标志跳过对钩子 (hooks)、技能 (skills)、插件 (plugins)、MCP 服务器和 Cloud MD 文件的自动发现。
• 只使用明确允许的工具，启动速度更快。
• 结构化输出 (Structured Output):
• 可以将 JSON Schema 与输出格式 (output format) JSON 配对。
• Cloud Code 会约束输出结构以匹配指定的 Schema。
• 多步自动化: 可以从 JSON 输出中捕获会话 ID (session's ID) 以实现任务的恢复和上下文传递。
• Agent SDK 扩展:
• 支持将 Schema 匹配对象 (schema matching object) 落地到 SQL 中。
• 用户可以传递提示词、工具允许选项、系统提示词和权限模式，并迭代 Cloud 串流回的消息。

三、 总结对比 (Summary)

• Routine: 适合重复性、托管在 Anthropix 基础设施上的工作。
• Headless Mode: 适合需要通过脚本管道传递数据或依赖本地环境的单次任务。
• Agent SDK: 适合需要将 AI 能力深度集成到用户自有产品中的场景。

Takeaways

• Routine 模式适用于托管在 Anthropix 基础设施上的重复性工作，通过触发器（如定时任务）驱动。
• Headless Mode 适用于需要通过脚本管道传递数据或依赖本地环境的单次任务，可作为一次性命令运行。
• Agent SDK 允许将 Cloud Code 深度嵌入到用户自己的 TypeScript 或 Python 应用中，实现 AI 能力集成。
• 支持结构化输出，通过 JSON Schema 约束结果，并可捕获会话 ID 实现多步自动化和上下文传递。