1. 项目概述：从“定时提醒”到“后台工人”的跨越

去年，当Claude Code Desktop推出定时任务功能时，我和很多开发者一样，立刻把它用在了那些重复性的“提醒”工作上。每天早上自动汇总前一天的提交记录，为站会做准备；下班前生成PR摘要；每周自动检查一次依赖更新。这些简单的、基于固定提示词的循环任务，在初期确实带来了便利。它就像一个贴心的助手，在你需要的时候，准时递上一份简报。

然而，当我试图构建更复杂的自动化流程时，内置调度器的局限性就暴露无遗了。我的需求很简单：一个能在每天工作开始前自动运行的“晨间简报”任务。它需要审查所有开放的PR，总结夜间发生的变化，并标记出任何需要我立即关注的事项。本质上，这就是一个 cron 作业，只不过执行任务的“工人”从 bash 脚本换成了Claude。但实现起来，却遇到了两个核心障碍。

首先， 应用必须常驻 。Claude Code Desktop本身是一个资源消耗不小的图形化应用。为了让一个每天只运行几分钟的定时任务能够执行，我需要让这个“庞然大物”7x24小时在后台运行，这无疑是一种巨大的资源浪费，也违背了自动化“省心省力”的初衷。

其次， 执行环境的不确定性 。我发现在交互式会话中运行良好的提示词和技能（Skills），在定时任务中可能会行为不一致甚至直接失败。这两种模式的运行环境存在微妙的差异，我不得不花费大量时间去调试“为什么手动可以，自动就不行”，而不是专注于构建自动化逻辑本身。

那一刻我意识到，我需要的不是一个“提示词定时器”，而是一个 可靠的、后台化的“任务运行器” 。它应该像操作系统运行任何其他后台服务（如日志轮转、备份）一样运行Claude Code任务：持久、可观测、不受图形界面束缚。于是，我动手构建了 claude-code-scheduler 。它的目标不是取代内置调度器，而是填补“交互式提醒”与“生产级后台自动化”之间的鸿沟。

2. 核心设计哲学：让专业的人做专业的事

在设计 claude-code-scheduler 时，我坚持一个核心原则： 不重复造轮子 。操作系统的调度系统（macOS的 launchd 和Linux的 cron ）经过数十年演化，在可靠性、持久性和资源管理上已经近乎完美。我们的目标不是构建一个更好的调度器，而是构建一座坚固的桥梁，将Claude Code的执行能力无缝接入这套成熟的基建中。

2.1 调度职责完全委派给操作系统

这是项目最重要的架构决策。插件本身 没有守护进程，也没有运行时调度器 。所有定时逻辑都交给 launchd 或 crontab 来管理。

带来的直接好处是显而易见的：

• 真正的持久化 ：任务注册到系统服务后，将完全独立于Claude Code Desktop应用。无论你是关闭应用、重启电脑还是注销登录，任务都会在预设的时间点准时触发。你设定一个凌晨3点的代码分析任务，就可以安心睡觉，不用担心因为忘了开软件而错过。
• 确定性的调度语义 ： cron 表达式在这里的行为与在其它任何地方完全一致。没有抽象层引入的“抖动”、“批处理”或“近似时间窗口”。 0 9 * * 1-5 就是每个工作日上午9点整，分秒不差。这种确定性对于构建可靠的自动化流程至关重要。
• 资源零开销 ：插件本身只是一个命令行工具集和配置文件管理器。在任务非执行期间，它不占用任何CPU或内存。调度由操作系统内核管理，这是最轻量、最高效的方式。

为了实现这一点，我编写了平台特定的模块： schedulers/darwin.ts 负责生成符合规范的 launchd plist 文件，而 schedulers/linux.ts 则管理 crontab 条目。它们共同的核心工作，就是将用户定义的任务，翻译成操作系统能理解并忠实执行的“契约”。

2.2 配置即代码：版本化与协作的基础

自动化任务的配置不应该藏在图形界面的数据库里，而应该像项目代码一样可版本化、可评审、可复制。因此， claude-code-scheduler 采用了基于纯文本JSON文件的配置方式。

配置分为两个层级，清晰定义了作用域和权限：

1. 全局配置 ( ~/.claude/schedules.json )：存放用户级别的、跨项目的任务。例如，一个每晚备份所有项目笔记的通用任务。
2. 项目级配置 ( <project_root>/.claude/schedules.json )：存放与特定代码仓库相关的任务。例如，针对当前项目的每日依赖安全审计或代码风格检查。

一个任务定义包含了所有必要信息：

{
  “name”: “morning-pr-digest”,
  “prompt”: “Review all open PRs in the current repository. Summarize changes since yesterday, flag any PRs that are blocked or need my review, and list any new comments or discussions.”,
  “schedule”: “0 8 * * 1-5”, // 工作日早上8点
  “projectPath”: “/Users/me/code/my-project”,
  “memory”: {
    “enabled”: true,
    “strategy”: “inject” // 启用跨运行记忆
  },
  “worktree”: {
    “enabled”: true // 在独立工作树中运行
  }
}

这种设计带来了强大的工作流优势：

• 版本控制 ：项目级的 schedule.json 可以提交到Git。团队可以通过Pull Request来评审和修改自动化任务，就像评审源代码一样。
• 环境一致性 ：新成员克隆项目后，无需手动配置，就能获得一套预定义的、与项目配套的自动化任务。
• 安全边界 ：通过保留 skipPermissions 等敏感标志仅限全局配置使用，防止了从外部仓库克隆的配置可能带来的权限提升风险。

2.3 执行器：连接系统触发与Claude会话

当操作系统的调度器触发任务时，需要有一个组件来负责“启动一个Claude Code会话并执行特定提示词”。这就是 cli/executor.ts 共享执行器的职责。

它的工作流程是：

1. 环境准备 ：根据配置，决定是在项目主目录还是新建的独立Git工作树中运行。
2. 会话启动 ：以非交互、后台模式调用Claude Code CLI，加载指定的项目上下文。
3. 提示词注入 ：将任务配置中的 prompt ，连同可能存在的“记忆”（前一次运行的输出）一起，发送给Claude。
4. 结果捕获与记录 ：忠实记录Claude执行过程的 stdout 和 stderr ，并将执行元数据（时间、状态、任务ID）写入历史日志。

这个执行器是插件的“引擎”，它确保了无论在何种系统调度下，Claude Code任务的执行环境都是可控、可重复的。

3. 关键特性深度解析：超越简单的定时

如果只是把提示词定时运行，那价值有限。 claude-code-scheduler 的多个核心特性，共同将“自动化”提升到了“智能进程”的层面。

3.1 跨运行记忆：从孤立任务到有状态的进程

这是我最常使用，也是最能体现“智能自动化”价值的特性。它允许将一次任务运行的输出，作为上下文注入到下一次运行的提示词中。

没有记忆的任务是“失忆的” ：一个每晚分析代码库坏味道的任务，每次运行都从头开始，告诉你同样的一长串问题。你很难看出哪些是新问题，哪些是历史遗留的老问题。

启用记忆后，任务变成了“有状态的” ：

• 增量分析 ：今晚的任务在运行时，会收到昨晚任务输出的摘要。它的提示词可以变为：“这是截至昨晚的代码问题列表。请分析今日新的提交，更新列表，并特别标出新增或已解决的问题。”
• 持续汇总 ：一个文档生成任务可以每次只处理当天的提交，但同时携带一个不断增长的“总摘要”，最终生成一份完整的、增量更新的周报或发布说明。
• 迭代收敛 ：对于复杂分析，可以设计多轮任务。第一轮进行广度扫描，输出潜在关注点；第二轮任务读取第一轮结果，进行深度聚焦分析；第三轮进行验证。通过记忆串联，让AI的分析逐次深化。

实现上，这通过在每次任务成功后，将其关键输出序列化并存储在一个与任务绑定的 memory.json 文件中来实现。下次任务启动时，执行器会先读取这个文件，并将其作为系统提示的一部分或上下文文件传递给Claude。

3.2 Git工作树隔离：安全地进行自动化变更

让AI在后台修改你的代码库，听起来很强大，但也令人担忧：万一它改坏了东西怎么办？万一它运行的时候，你正在同一个分支上工作怎么办？

独立Git工作树 特性完美解决了这个问题。当为任务启用此选项后，插件会在执行前，为你的仓库创建一个临时的、完整的工作树（使用 git worktree add ）。任务所有的文件操作——读取、修改、提交——都发生在这个沙盒化的副本中。

这带来了双重好处：

1. 安全性 ：你的主工作目录完全不受影响。你可以放心地继续编码，而不用担心被后台任务干扰或覆盖。
2. 可审查性 ：任务完成后，所有变更都留在了独立工作树的一个分支里。第二天早上，你可以像审查任何其他PR一样， git diff 一下这个分支，查看AI具体改了些什么，确认无误后再合并。
3. 并行化可能 ：多个任务可以针对同一个仓库同时运行，每个任务都有自己的工作树，彼此隔离，互不冲突。

插件通过 vcs/index.ts 模块管理着工作树的全生命周期：创建、使用、清理，确保不会留下垃圾数据。

3.3 可观测性：信任源于透明

不可观测的自动化是危险的。它的失败模式往往不是“大声报错”，而是“静默地做错事，直到几周后酿成后果”。因此，构建一套不亚于CI系统的可观测体系是重中之重。

claude-code-scheduler 从三个层面提供可观测性：

1. 结构化执行历史 每一次任务运行都会在JSONL格式的历史日志中生成一条记录。每条记录包含：

{“timestamp”: “2024-05-27T03:00:01.123Z”, “taskId”: “nightly-scan”, “project”: “my-app”, “status”: “success”, “durationMs”: 45231, “memorySnapshot”: “…”}

你可以通过 scheduler:history 命令，并配合状态、任务名或项目路径进行过滤查询，快速定位成功或失败的任务。

2. 详尽的输出日志 每次运行的 stdout 和 stderr 都会被分别捕获并存储到按日期滚动的日志文件中。当你的夜间代码质量检查突然开始失败时，你可以直接运行 scheduler:logs --task nightly-scan --date 2024-05-27 ，查看Claude当时究竟输出了什么，错误信息是什么。这比“任务失败了”这样一个干巴巴的通知要有用得多。

3. 日志轮转与清理 为了避免日志文件无限膨胀，插件内置了日志管理策略。默认会保留最近30天的详细日志，更早的日志会被自动清理。结构化历史记录则保留更长时间。这些策略都可以通过全局配置进行调整。

3.4 安全边界：为无人值守执行上锁

交互式使用Claude时，你就在电脑前，可以监控每一个命令。但无人值守的定时任务运行在完全不同的信任上下文中。我们必须假设它可能被用于访问敏感文件、执行 shell 命令，因此需要预设严格的安全边界。

插件内置了多层防护：

• 环境变量过滤 ：任务运行环境会被清理，敏感的环境变量（如 AWS_ACCESS_KEY_ID , GITHUB_TOKEN 等）默认会被阻止访问，除非显式允许。
• 敏感文件检测 ：在执行文件操作相关命令时，会尝试检测并警告对已知的凭证文件（如 .env , *.pem , id_rsa ）的访问。
• Shell输入净化 ：所有从任务配置流入shell命令的参数都会经过严格的转义，防止注入攻击。
• 权限标志隔离 ：如前所述，像 skipPermissions 这样的高风险设置只能存在于全局配置中，防止从外部仓库克隆的配置获得过高权限。

这些不是纸上谈兵的安全功能。当你让AI在凌晨自动运行 git commit 、 npm audit fix 甚至自动重构代码时，这些边界就是防止“自动化灾难”的保险丝。

4. 实战：从配置到管理的完整工作流

4.1 安装与初体验

安装过程极其简单，得益于Claude Code的插件系统：

# 在Claude Code的聊天窗口中，直接使用slash command
/scheduler:install

安装后，插件会初始化必要的配置目录和文件。所有功能都通过直观的slash命令来调用。

4.2 核心命令详解

插件提供了10个命令，覆盖了任务的全生命周期管理：

• /scheduler:add ：交互式地添加一个新任务。它会引导你输入任务名、提示词、调度时间（支持cron表达式或自然语言如“every weekday at 9am”），并设置项目路径、记忆、工作树等选项。
• /scheduler:list ：列出所有已注册的任务（包括全局和当前项目的），并显示其名称、调度表达式、下次运行时间和启用状态。
• /scheduler:run <task-name> ：立即手动运行一个任务，用于测试和调试。
• /scheduler:logs [--task TASK] [--date DATE] ：查看任务的详细输出日志。这是排查问题的首要工具。
• /scheduler:history [--status (success|failed)] ：查看任务执行的历史记录，快速了解整体运行状况。
• 管理命令 ： /scheduler:enable|disable|remove|edit|status 用于对任务进行启停、删除、编辑和状态检查等日常管理。

一个完整的创建流程示例： 假设我想为我的 blog-engine 项目创建一个每周日晚上清理无用图片的任务。

1. 在项目根目录打开Claude Code。
2. 输入 /scheduler:add 。
3. 按照提示：
   • 任务名： weekly-image-cleanup
   • 提示词： Scan the ‘static/images’ directory in this project. Find all image files (.png, .jpg, .gif) that are not referenced in any of the .md or .html files. List them and ask me if I want to delete them. If I confirm, move them to a ‘deleted_images’ backup folder with a timestamp.
   • 调度： 0 22 * * 0 (每周日晚上10点)
   • 启用记忆？ Yes (这样下周运行时，它可以知道上次删除了什么)
   • 使用独立工作树？ Yes (安全第一)
4. 确认后，插件会生成配置，并调用 crontab -e （或 launchctl load ）将任务注册到系统。任务创建完毕。

4.3 调试与故障排查技巧

即使设计再完善，在实际运行中也可能遇到问题。以下是我总结的排查路径：

问题1：任务没有在预定时间运行。

• 检查1：系统调度器状态 。运行 /scheduler:status weekly-image-cleanup 。插件会告诉你这个任务在操作系统层面的注册状态。对于cron，你可以用 crontab -l 查看；对于launchd，用 launchctl list | grep claude 。
• 检查2：系统日志 。在Linux上，查看 /var/log/syslog 或 journalctl ；在macOS上，使用 log show --predicate ‘subsystem == “com.apple.cron”’ --last 1h 。这里能看到cron或launchd是否真的触发了命令。
• 检查3：插件执行器日志 。在 ~/.claude/logs/scheduler.log 中，有插件自身调度逻辑的日志（虽然大部分调度已委派，但仍有心跳和错误记录）。

问题2：任务运行了，但失败了。

• 第一步：查看详细日志 。 /scheduler:logs --task weekly-image-cleanup --date YYYY-MM-DD 。重点看 stderr 的输出，这里通常是权限错误、命令未找到或Claude执行出错的堆栈信息。
• 第二步：手动测试环境 。在任务配置的 projectPath 目录下，手动运行Claude Code，并尝试执行相同的提示词。这能快速区分是环境问题还是调度执行问题。
• 第三步：检查依赖 。确保你的提示词中引用的任何技能（Skills）或工具，在非交互式环境下也是可用的。有时交互式会话会加载更多用户上下文。

问题3：任务输出不符合预期（静默失败）。

• 启用更详细的Claude日志 。在Claude Code的设置中，可以调整日志级别。让Claude输出更多的推理过程，有助于理解为什么AI做出了某种判断。
• 审查“记忆”注入的内容 。检查 ~/.claude/schedules/memory_weekly-image-cleanup.json 文件，看看上一次运行传递给AI的上下文是否正确。记忆污染可能导致连锁错误。
• 简化提示词进行隔离测试 。创建一个新的、极简的任务（例如，只输出当前目录列表），确认基础功能正常，再逐步增加复杂度，定位问题环节。

5. 灵感库：你可以用来自动化什么？

有了可靠的基础设施，我们的思维就可以从“能不能自动”转向“应该自动什么”。以下是一些经过验证的实用场景，希望能激发你的灵感：

5.1 代码仓库的夜间巡检员

• 任务 ： nightly-repo-health-check
• 提示词 ：“分析本仓库主分支的最新状态。1. 运行 npm audit 或 pip-audit ，总结安全漏洞。2. 检查是否有依赖过期（major update）。3. 运行静态分析工具（如ESLint, pyflakes），统计新增的警告/错误。4. 检查CI最近一次构建的状态。将结果汇总为一份不超过10条的简报，按紧急程度排序。”
• 调度 ： 0 2 * * * (每天凌晨2点)
• 记忆 ：启用。对比昨日报告，只高亮新出现的问题。
• 价值 ：每天早上一份清晰的“仓库健康报告”，让你对项目状态一目了然，优先处理真正重要的问题。

5.2 渐进式的文档撰写助手

• 任务 ： incremental-doc-updater
• 提示词 ：“获取自上次运行此任务以来，本仓库 src/ 目录下的所有提交。针对每个涉及公共API或核心逻辑修改的提交，在 docs/api-updates.md 文件中，以日期为标题，增补相应的变更说明。保持文档的连贯性。”
• 调度 ： 0 20 * * * (每天晚8点)
• 记忆 ：启用。记录已处理过的提交哈希，避免重复劳动。
• 工作树 ：启用。让它在独立分支上修改文档，生成PR供你合并。
• 价值 ：文档与代码同步不再是噩梦。AI将日常琐碎的文档更新工作消化在后台，你只需定期审查和合并PR。

5.3 智能的代码“园丁”

• 任务 ： weekly-refactor-gardener
• 提示词 ：“扫描 src/components/ 目录下所有React组件。识别出：1. 重复的、可提取的工具函数。2. 过于庞大（>200行）的组件。3. 使用已弃用API的代码。对于前两类，在独立工作树中尝试进行安全的、局部的重构，并提交到 refactor/auto-garden-{date} 分支。对于第三类，仅在报告中列出。”
• 调度 ： 0 4 * * 6 (每周六凌晨4点)
• 工作树 ：启用（必须）。
• 价值 ：将代码库的“日常维护”自动化。每周一早上，你会收到一个包含自动化重构建议的分支，大大减轻技术债的累积压力。

5.4 跨运行的分析与收敛

• 任务 ： multi-pass-performance-audit
• 提示词（第一轮） ：“快速扫描项目代码，找出所有可能存在性能瓶颈的地方（如大型循环、未分页的数据库查询、重复计算）。输出一个优先级列表。”
• 调度 ： 0 22 * * 1 (周一晚10点)
• 记忆 ：启用。
• 任务 ： multi-pass-performance-audit-deep
• 提示词（第二轮） ：“这是第一轮扫描发现的潜在性能热点列表：[此处注入第一轮记忆]。请对列表中‘高优先级’的条目进行深入分析，给出具体的代码片段和优化建议。”
• 调度 ： 0 22 * * 2 (周二晚10点，依赖第一轮完成)
• 记忆 ：启用。
• 价值 ：将复杂的分析任务分解为多轮、渐进的自动化过程。第一轮广度扫描，第二轮深度聚焦，最终产出高质量、可执行的优化报告。

6. 定位与思考：选择合适的工具

最后，我想澄清一下 claude-code-scheduler 与Claude Code Desktop内置调度器的关系。它们并非竞争关系，而是服务于不同场景的互补工具。

Claude Code Desktop内置调度器 的优势在于 即时性与交互性 。它运行在你的活跃会话中，结果直接显示在UI里。它非常适合那些你希望在办公时 看到并可能交互 的周期性任务。比如，每30分钟检查一次收件箱并摘要重要邮件，或者在你编码时，每隔一小时自动运行一次单元测试并给你反馈。它是你 交互式工作流 的延伸。

claude-code-scheduler 则专注于 可靠性与后台化 。它的任务是“无论你在不在，都按时保质完成工作”。它不关心UI，只关心执行、日志和状态持久化。它适合那些 在后台默默运行 的工作：深夜的代码分析、定期的依赖更新、持续的文档同步、每周的数据清洗。它是你 自动化基础设施 的一部分。

我构建这个插件，正是为了填补从“交互式助手”到“后台智能进程”之间的空白。调度本身是个早已被操作系统解决的古老问题。 launchd 和 cron 久经考验。我们所缺的，只是一个将它们与Claude Code这个强大的AI执行引擎连接起来的、可靠的桥梁。 claude-code-scheduler 就是这座桥。它让开发者能够以软件工程中熟悉的方式——配置即代码、日志可观测、运行可重复——来编排AI的能力，从而创造出真正持久、可靠且强大的自动化工作流。