sproutclaw-cron — 定时任务系统

树萌芽的定时任务管理框架。每个任务一目录，共享公共库，统一管理开关与日志。

---

目录结构

/shumengya/project/agent/sproutclaw-cron/
├── cronctl.py                        # 统一管理 CLI（enable/disable/toggle/status）
├── AGENTS.md                         # AI 新建任务规范（必读）
├── _template/                        # 示例任务 + 复制模板（每天 08:00 hello world）
├── lib/
│   └── shumengya_cron/
│       ├── runner.py                 # TaskContext、日志轮转、flock 互斥锁
│       ├── notify.py                 # 飞书 Markdown 通知 + 邮件降级
│       └── ssh.py                    # 远端 SSH 辅助（bash -lc）
├── <task-id>/                        # 任务目录（启用状态）
│   ├── run.py                        # 任务入口（唯一必须文件）
│   ├── schedule.cron                 # 系统 cron 配置（复制到 /etc/cron.d/）
│   ├── switch.sh                     # 一键开关（可用 cronctl 替代）
│   ├── targets.json                  # 可选：任务自定义配置（JSON）
│   ├── logs/<task-id>.log            # 运行日志（自动创建）
│   └── <task-id>.lock                # flock 互斥锁文件（自动创建）
└── .disabled/                        # 禁用任务统一存放目录
    └── <task-id>/                    # 关闭的任务移入此处

任务 ID 命名约定：<主机名>-<功能描述>，例如 bigmengya-docker-image-update。

---

已有任务

任务 ID	状态	说明
_template	开启	示例任务：每天 08:00 输出 hello world，也是新任务复制模板
bigmengya-docker-container-restart	disabled	SSH 重启 bigmengya 上的数据库类容器
bigmengya-docker-image-update	disabled	SSH 拉取并重建 bigmengya 上的 compose 服务
smallmengya-ai-cli-update	disabled	更新本机 codex / claude / opencode
smallmengya-ai-memory-export	disabled	导出 AI 记忆数据
smallmengya-gitea-repo-sync	开启	同步 Gitea 仓库到本地

---

快速上手

查看状态

python3 /shumengya/project/agent/sproutclaw-cron/cronctl.py status

开关任务

python3 /shumengya/project/agent/sproutclaw-cron/cronctl.py enable  <任务名>
python3 /shumengya/project/agent/sproutclaw-cron/cronctl.py disable <任务名>
python3 /shumengya/project/agent/sproutclaw-cron/cronctl.py toggle  <任务名>
python3 /shumengya/project/agent/sproutclaw-cron/cronctl.py enable  all      # 全部开启
python3 /shumengya/project/agent/sproutclaw-cron/cronctl.py disable all      # 全部关闭

手动运行任务

# 推荐：通过 cronctl（自动识别 .disabled/ 下的任务）
python3 /shumengya/project/agent/sproutclaw-cron/cronctl.py run <任务名>

# 也可直接运行（启用或 .disabled/<任务名> 目录均可）
python3 /shumengya/project/agent/sproutclaw-cron/.disabled/<任务名>/run.py

安装到系统 cron

cronctl enable 会将 schedule.cron 复制到 /etc/cron.d/<task-id>；disable 只把任务目录移入 .disabled/<task-id>/，不会删除 /etc/cron.d/ 条目。cron 到点仍会触发，但 run.py 检测到禁用后会直接跳过。

python3 /shumengya/project/agent/sproutclaw-cron/cronctl.py sync-cron all   # 仅同步 cron.d，不改开关

---

开关机制

• 启用：从 .disabled/<task-id>/ 移回 <task-id>/
• 关闭：从 <task-id>/ 移入 .disabled/<task-id>/
• run.py 在入口检查 task_is_disabled(ctx)，若关闭直接 return 0，不写日志、不发通知、不获取锁
• /etc/cron.d/<task-id> 可一直保留；schedule.cron 通过 cronctl.py run <task-id> 调度

---

新建任务（模板）

从 _template/ 复制。_template 本身是可管理的示例任务（每天 08:00 输出 hello world）。

TASK_ID="smallmengya-my-new-task"
CRON_ROOT="/shumengya/project/agent/sproutclaw-cron"

cp -a "$CRON_ROOT/_template" "$CRON_ROOT/$TASK_ID"
sed -i "s/_template/$TASK_ID/g" "$CRON_ROOT/$TASK_ID/schedule.cron"
chmod +x "$CRON_ROOT/$TASK_ID/switch.sh"

# 编辑 run.py 与 schedule.cron 后试跑
python3 "$CRON_ROOT/cronctl.py" run "$TASK_ID"
python3 "$CRON_ROOT/cronctl.py" enable "$TASK_ID"

详细约定见 _template/README.md；AI 代理见根目录 AGENTS.md。

---

公共库 API

runner.py

接口	说明
TaskContext.from_task_id(task_id, *, log_mode, cron_root)	构造任务上下文（自动识别 .disabled/<task-id>/）
task_is_disabled(ctx)	任务目录位于 .disabled/ 下则返回 True
task_is_enabled(ctx)	同上取反
set_task_enabled(ctx, enabled)	重命名目录切换状态
task_logging(ctx)	上下文管理器，返回 log(msg) 函数；轮转日志、tee 到终端
acquire_cron_lock(lock_file, *, log)	flock 互斥锁，已占用时 yield False
cron_log_rotate(log_file, max_bytes)	超过阈值时轮转日志（默认 10MB）
append_raw_to_log(log_file, text)	将命令原始输出追加到日志
task_output_prefix(task_id)	返回 [smallmengya][AI-CLI-Update] 格式前缀
LogMode.REDIRECT_STD	stdout/stderr 重定向到日志（默认）
LogMode.DIRECT_FILE	仅写文件，不重定向标准流

notify.py

接口	说明
TaskResult	任务结果容器，add_ok/add_skip/add_fail(item) 累积条目，.success / .status_cn / .total 供汇总使用
send_task_summary(ctx, result, start_time, *, log, extra_fields)	发送标准 ok/skip/fail 汇总通知（飞书 + 邮件降级）
send_feishu_markdown(title, markdown, *, log)	发飞书通知；失败自动降级邮件
markdown_list(items)	["a","b"] → "- a\n- b"
markdown_fields(items)	[("key","val")] → "- **key**：val\n..."

ssh.py

接口	说明
ssh_bash_lc(host, remote_cmd)	用 bash -lc 执行远程命令，PATH 与登录 shell 一致

---

环境变量

公共（所有任务）

变量	默认	说明
CRON_LOG_MAX_BYTES	10485760（10MB）	日志轮转阈值
CRON_LOCK_BUSY_MSG	已有任务在运行…	锁冲突时的日志消息
LARK_NOTICE_WEBHOOK	内置默认 webhook	飞书机器人 webhook
LARK_NOTICE_API_SRC	/shumengya/project/python/lark-notice-api/src	lark-notice-api 源码路径
CRON_MAIL_ENABLED	0	设为 1 开启邮件降级通知
MAIL_API_SCRIPT	mengya-mail-api 路径	邮件发送脚本路径
MAIL_TO	mail@smyhub.com	收件人

bigmengya-docker-container-restart

变量	默认	说明
REMOTE_HOST	bigmengya	SSH 目标主机
REMOTE_DOCKER_BIN	docker	远端 docker 命令路径
DB_CONTAINERS	mysql-8 redis-7 …	目标容器名（空格分隔）
DB_PATTERNS	mysql redis mongo …	镜像名匹配模式（空格分隔）

bigmengya-docker-image-update

变量	默认	说明
REMOTE_HOST	bigmengya	SSH 目标主机
PULL_RETRIES	3	pull 失败重试次数
PULL_RETRY_DELAY_SECONDS	15	重试间隔秒数

smallmengya-ai-cli-update

变量	默认	说明
CRON_TASK_PATH	/root/bin:/root/.opencode/bin:…	查找 CLI 工具的 PATH
UPDATE_TIMEOUT_SECONDS	500	单个工具更新超时秒数
CLI_TARGETS	全部	逗号分隔，限制只更新指定工具
HTTP_PROXY / HTTPS_PROXY	socks5://192.168.1.1:7891	代理地址
NPM_REGISTRY_URL	https://registry.npmmirror.com	npm 镜像

smallmengya-gitea-repo-sync

变量	默认	说明
BASE_DIR	/shumengya/project/cloudflare	本地仓库基础目录
SYNC_DELAY_SECONDS	2	每个仓库同步间隔秒数
GIT_SSH_COMMAND	BatchMode=yes …	git SSH 参数

---

剩余可优化方向

以下问题有优化价值，但影响面较小，暂未实施：

1. lib 路径注入样板

每个 run.py 顶部都有 3 行 sys.path.insert 代码，是为了支持 schedule.cron 直接调用 python3 run.py。 若将 schedule.cron 改为调用 cronctl run <task-id>，则 run.py 里的路径注入可以全部删掉。

2. switch.sh 冗余

每个任务目录都有一份 switch.sh，其内部已经是代理调用 cronctl.py，新任务可以不再创建它，直接用 cronctl enable/disable。

---

任务配置文件格式（JSON）

任务自定义配置统一使用 JSON，不存在时任务会自动生成默认内容。

targets.json（bigmengya-docker-image-update）

[
  {"label": "myapp", "workdir": "/shumengya/docker/myapp", "service": "myapp"},
  {"label": "another", "workdir": "/shumengya/docker/another", "service": "web"}
]

字段	说明
label	显示名（日志/通知中使用）
workdir	compose 项目目录（远端路径）
service	compose service 名

repos.json（smallmengya-gitea-repo-sync）

[
  {"repo": "shumengya/my-repo"},
  {"repo": "shumengya/another-repo", "local": "/custom/local/path"}
]

字段	说明
repo	owner/repo（省略 owner 默认 shumengya）
local	本地同步路径（省略时用 BASE_DIR/repo名）

---

依赖说明

这套系统只依赖 Python 3 标准库（fcntl、subprocess、pathlib 等），无需安装任何 PyPI 包。

通知功能依赖两个本地项目（非 PyPI 依赖，可缺失时降级）：

• lark-notice-api：飞书通知，路径 /shumengya/project/python/lark-notice-api/
• mengya-mail-api：邮件降级，路径 /shumengya/project/skills/mengya-mail-skills/

SSH 功能依赖系统 ssh 命令和已配置的 SSH 密钥对。