feat: 添加 cron_cli 工具管理定时任务

[robscc]

🎯 功能概述

添加 cron_cli 内置工具，支持通过自然语言管理定时任务，完善定时任务系统的用户交互界面。

✨ 主要特性

支持的操作

操作	说明	必需参数
list	列出所有定时任务（含状态、下次执行时间）	无
create	创建新定时任务	name, schedule, task_prompt
update	更新任务配置	job_id + 至少一个更新字段
delete	删除定时任务	job_id
toggle	启用/禁用任务	job_id, enabled
history	查看执行历史（最近 20 条）	job_id (可选)

用户友好特性

• ✅ cron 表达式教学：内置格式说明和示例
  • '0 9 * * *' = 每天 09:00
  • '*/30 * * * *' = 每 30 分钟
  • '0 9 * * 1' = 每周一 09:00
• ✅ 详细错误提示：参数缺失时明确告知
• ✅ 执行状态可视化：✅ 启用 / ⏸️ 禁用 / ⏳ 运行中 / ❌ 失败
• ✅ 结果截断保护：执行历史结果自动截断至 100 字符，避免刷屏

🔧 技术实现

异步代码集成

# 使用 ThreadPoolExecutor 在同步工具中运行异步代码
def _thread_run() -> str:
    loop = asyncio.new_event_loop()
    try:
        return loop.run_until_complete(_run())
    finally:
        loop.close()

with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
    future = pool.submit(_thread_run)
    result_text = future.result(timeout=30)

服务层集成

• 复用 services/cron_scheduler.py 的 CronManager
• 遵循项目规范：Service 层 flush()，API 层 commit()
• 统一错误返回格式：<error>错误信息</error>

参数设计

def cron_cli(
    action: str,
    name: str = "",
    schedule: str = "",
    task_prompt: str = "",
    job_id: str = "",
    enabled: bool = True,
) -> ToolResponse:

📦 文件变更

修改文件:

• backend/agentpal/tools/builtin.py (+192 行)
  • 新增 cron_cli 工具函数
  • 注册到 BUILTIN_TOOLS 列表

🧪 测试建议

待添加：

• 单元测试：参数验证逻辑
• 集成测试：与 CronManager 的交互
• E2E 测试：通过前端调用 cron_cli

手动测试清单：

• list 操作 - 显示任务列表
• create 操作 - 创建新任务
• toggle 操作 - 启用/禁用
• history 操作 - 查看执行历史

📝 使用示例

通过工具调用

# 列出所有任务
cron_cli(action='list')

# 创建每日新闻总结任务
cron_cli(
    action='create',
    name='每日晨间新闻',
    schedule='0 7 * * *',
    task_prompt='请用新闻技能获取并总结最新新闻，100 字以内'
)

# 禁用任务
cron_cli(action='toggle', job_id='abc123', enabled=False)

# 查看执行历史
cron_cli(action='history', job_id='abc123')

前端集成（待实现）

访问 /tools 页面，启用 cron_cli 工具后，用户可在对话中直接使用：

• "创建一个每天早上 7 点的新闻总结任务"
• "列出所有定时任务"
• "禁用黄金价格监控任务"

🔗 相关模块

• services/cron_scheduler.py - CronManager 服务层
• models/cron.py - CronJob / CronJobExecution ORM 模型
• api/v1/endpoints/cron.py - RESTful API 端点
• agents/cron_agent.py - 定时任务执行 Agent

⚠️ 已知限制

1. 超时时间：当前设置为 30 秒，复杂任务可能超时（建议后续增加到 60 秒）
2. 权限控制：暂无用户级权限隔离（单用户场景无影响）
3. 结果截断：执行历史结果截断至 100 字符，可能丢失部分信息

🚀 后续优化

• 增加超时时间配置（根据操作类型动态调整）
• 添加用户权限验证（多用户场景）
• 支持 update 操作修改 enabled 字段
• 执行历史结果支持 --verbose 模式
• 前端 UI 集成（TasksPage 增强）

---

检查清单:

• 代码符合项目规范（async/await 模式）
• 错误处理完善（统一 <error> 格式）
• 用户提示友好（cron 表达式示例）
• 添加单元测试
• 手动测试通过
• 与现有 CronManager 集成正确