Nội bộ Cron

Hệ thống con cron cung cấp khả năng thực thi tác vụ theo lịch trình — từ độ trễ một lần đơn giản đến các tác vụ biểu thức cron định kỳ với tính năng chèn kỹ năng và phân phối đa nền tảng.

Tệp chính

Tập tin	Mục đích
`cron/jobs.py
`	Mô hình công việc, lưu trữ, đọc/ghi nguyên tử vào
`jobs.JSON
`
`cron/scheduler.py
`	Vòng lặp lập lịch trình - phát hiện công việc đến hạn, thực hiện, theo dõi lặp lại
`tools/cronjob_tools.py
`	Đăng ký và xử lý công cụ
`cronjob
` đối diện với mô hình
`gateway/run.py
`	Tích hợp cổng - tích tắc cron trong vòng lặp chạy dài
`Hermes_CLI/cron.py
`	Lệnh con CLI
`Hermes cron
`

Mô hình lập kế hoạch

Bốn định dạng lịch trình được hỗ trợ:

Định dạng	Ví dụ	Hành vi
Độ trễ tương đối

30m

, `2h

, 1d | Một phát, bắn sau thời gian quy định | | Khoảng thời gian |

every 2h

, every 30m | Định kỳ, cháy đều đặn | | Biểu thức cron |

0 9 * * * ` | Cú pháp cron 5 trường tiêu chuẩn (phút, giờ, ngày, tháng, ngày trong tuần) | | Dấu thời gian ISO |

2025-01-15T09:00:00 ` | Một phát, bắn đúng thời điểm |

Bề mặt đối diện với mô hình là một công cụ cronjob duy nhất với các thao tác kiểu hành động: `create

, `list

, `update

, `pause

, `resume

, `run

, `remove

.

Lưu trữ công việc

Các công việc được lưu trữ trong

~/.Hermes/cron/jobs.JSON ` với ngữ nghĩa ghi nguyên tử (ghi vào tệp tạm thời, sau đó đổi tên). Mỗi bản ghi công việc bao gồm:

{
  "id": "a1b2c3d4e5f6",
  "name": "Daily briefing",
  "prompt": "Summarize today's AI news and funding rounds",
  "schedule": {
    "kind": "cron",
    "expr": "0 9 * * *",
    "display": "0 9 * * *"
  },
  "skills": ["ai-funding-daily-report"],
  "deliver": "Telegram:-1001234567890",
  "repeat": {
    "times": null,
    "completed": 42
  },
  "state": "scheduled",
  "enabled": true,
  "next_run_at": "2025-01-16T09:00:00Z",
  "last_run_at": "2025-01-15T09:00:00Z",
  "last_status": "ok",
  "created_at": "2025-01-01T00:00:00Z",
  "model": null,
  "provider": null,
  "script": null
}

`

### Trạng thái Vòng đời Công việc

| Tiểu bang | Ý nghĩa |
|-------|----------|
| 
`scheduled
` | Đang hoạt động, sẽ kích hoạt vào thời gian dự kiến ​​tiếp theo |
| 
`paused
` | Bị đình chỉ - sẽ không kích hoạt cho đến khi tiếp tục |
| 
`completed
` | Số lần lặp lại đã hết hoặc một phát đã bắn |
| 
`running
` | Hiện đang thực thi (trạng thái tạm thời) |

### Khả năng tương thích ngược

Các công việc cũ hơn có thể có một trường 
`skill
` thay vì mảng 
`skills

. Bộ lập lịch bình thường hóa điều này khi tải - 
`skill
` đơn lẻ được thăng cấp thành 
`skills: [skill]

.

## Thời gian chạy của bộ lập lịch

### Chu kỳ đánh dấu

Bộ lập lịch chạy theo chu kỳ (mặc định: 60 giây một lần):

`text
tick()

  1. Acquire scheduler lock (prevents overlapping ticks)
  2. Load all jobs from jobs.JSON
  3. Filter to due jobs (next_run <= now AND state == "scheduled")
  4. For each due job:
     a. Set state to "running"
     b. Create fresh AIAgent session (no conversation history)
     c. Load attached skills in order (injected as user messages)
     d. Run the job prompt through the agent
     e. Deliver the response to the configured target
     f. Update run_count, compute next_run
     g. If repeat count exhausted → state = "completed"
     h. Otherwise → state = "scheduled"
  5. Write updated jobs back to jobs.JSON
  6. Release scheduler lock

`

### Tích hợp cổng

Ở chế độ cổng, bộ lập lịch chạy trong một luồng nền chuyên dụng (
`_start_cron_ticker
` trong 
`gateway/run.py

) gọi 
`scheduler.tick()
` cứ sau 60 giây cùng với việc xử lý tin nhắn.

Ở chế độ CLI, công việc định kỳ chỉ kích hoạt khi các lệnh 
`Hermes cron
` được chạy hoặc trong các phiên CLI đang hoạt động.

### Cách ly phiên mới

Mỗi công việc định kỳ chạy trong một phiên tác nhân hoàn toàn mới:
- Không có lịch sử hội thoại từ lần chạy trước
- Không có bộ nhớ về các lần thực thi cron trước đó (trừ khi được lưu vào bộ nhớ/tệp)
- Lời nhắc phải khép kín — công việc định kỳ không thể đặt câu hỏi làm rõ
- Bộ công cụ 
`cronjob
` bị vô hiệu hóa (bảo vệ đệ quy)

## Công việc hỗ trợ kỹ năng

Một công việc định kỳ có thể đính kèm một hoặc nhiều kỹ năng thông qua trường 
`skills

. Tại thời điểm thực hiện:
1. Kỹ năng được nạp theo thứ tự quy định
2. Nội dung SKILL.md của mỗi kỹ năng được đưa vào dưới dạng ngữ cảnh
3. Lời nhắc công việc được thêm vào dưới dạng hướng dẫn nhiệm vụ
4. Tác nhân xử lý bối cảnh kỹ năng kết hợp + lời nhắc

Điều này cho phép các quy trình công việc được thử nghiệm và tái sử dụng mà không cần dán hướng dẫn đầy đủ vào lời nhắc cron. Ví dụ:

`
Create a daily funding report → attach "ai-funding-daily-report" skill

`

### Công việc dựa trên tập lệnh

Công việc cũng có thể đính kèm tập lệnh Python thông qua trường 
`script

. Tập lệnh chạy *trước* mỗi lượt tác nhân và thiết bị xuất chuẩn của nó được đưa vào dấu nhắc dưới dạng ngữ cảnh. Điều này cho phép thu thập dữ liệu và thay đổi mẫu phát hiện:

``` python

# ~/.Hermes/scripts/check_competitors.py
 import requests, JSON
# Fetch competitor release notes, diff against last run
# Print summary to stdout — agent analyzes and reports

`
``Thời gian chờ của tập lệnh mặc định là 120 giây. 
`_get_script_timeout()
` giải quyết giới hạn thông qua chuỗi ba lớp:
1. **Ghi đè cấp mô-đun** — 
`_SCRIPT_TIMEOUT
` (dành cho kiểm tra/vá khỉ). Chỉ được sử dụng khi nó khác với mặc định.
2. **Biến môi trường** — 
`Hermes_CRON_SCRIPT_TIMEOUT

3. **Cấu hình** — 
`cron.script_timeout_seconds
` trong 
`config.yaml
` (đọc qua 
`load_config()

)
4. **Mặc định** — 120 giây

### Khôi phục nhà cung cấp``run_job()
` chuyển các nhà cung cấp dự phòng và nhóm thông tin xác thực đã định cấu hình của người dùng vào phiên bản 
`AIAgent

:- **Nhà cung cấp dự phòng** — đọc 
`fallback_providers
` (danh sách) hoặc 
`fallback_model
` (lệnh kế thừa) từ 
`config.yaml

, khớp với mẫu 
`_load_fallback_model()
` của cổng. Được chuyển dưới dạng 
`fallback_model=
` thành 
`AIAgent.__init__

, chuẩn hóa cả hai định dạng thành chuỗi dự phòng.
- **Nhóm thông tin xác thực** — tải qua 
`load_pool(provider)
` từ 
`agent.credential_pool
` bằng cách sử dụng tên nhà cung cấp thời gian chạy đã phân giải. Chỉ được thông qua khi nhóm có thông tin xác thực (
`pool.has_credentials()

). Cho phép xoay vòng khóa của cùng một nhà cung cấp đối với các lỗi 429/giới hạn tỷ lệ.

Điều này phản ánh hành vi của cổng — nếu không có nó, tác nhân cron sẽ không đạt được giới hạn tốc độ nếu không cố gắng khôi phục.

## Mô hình giao hàng

Kết quả công việc định kỳ có thể được gửi đến bất kỳ nền tảng được hỗ trợ nào:

| Mục tiêu | Cú pháp | Ví dụ |
|--------|--------|---------|
| Trò chuyện gốc |

origin
` | Gửi đến cuộc trò chuyện nơi công việc được tạo |
| Tệp cục bộ |

local
` | Lưu vào 

~/.Hermes/cron/output/
` |
| Telegram |

Telegram
` hoặc 
`Telegram:<chat_id
` | 
`Telegram:-1001234567890
` |
| Discord |

Discord
` hoặc 
`Discord:#channel
` | 
`Discord:#engineering
` |
| Chần chừ |

Slack
` | Gửi tới kênh chủ Slack |
| WhatsApp |

WhatsApp
` | Giao hàng tới nhà WhatsApp |
| Tín hiệu |

Signal
` | Giao hàng tới Signal |
| Ma trận |

Matrix
` | Giao hàng tận phòng Matrix home |
| Quan trọng nhất |

Mattermost
` | Giao hàng tận nhà Matter Extreme |
| Email |

email
` | Gửi qua email |
| SMS |

sms
` | Gửi qua SMS |
| Trợ lý tại nhà |

homeassistant
` | Đưa đến cuộc trò chuyện HA |
| DingTalk |

DingTalk
` | Giao hàng cho DingTalk |
| Feishu |

Feishu
` | Giao hàng đến Feishu |
| WeCom |

WeCom
` | Giao hàng tới WeCom |
| Weixin |

weixin
` | Giao hàng tới Weixin (WeChat) |
| BlueBubble |

BlueBubbles
` | Gửi tới iMessage qua BlueBubbles |
| QQ Bot |

qqbot
` | Gửi tới QQ (Tencent) qua API chính thức v2 |

Đối với các chủ đề Telegram, hãy sử dụng định dạng 
`Telegram:<chat_id:<thread_id
` (ví dụ: 
`Telegram:-1001234567890:17585

).

### Gói phản hồi

Theo mặc định (
`cron.wrap_response: true

), việc phân phối cron được gói bằng:
- Tiêu đề xác định tên và tác vụ cron job
- Chân trang lưu ý rằng nhân viên không thể nhìn thấy tin nhắn đã gửi trong cuộc trò chuyện

Tiền tố 

[SILENT]
` trong phản hồi cron sẽ ngăn chặn hoàn toàn việc phân phối — hữu ích cho các công việc chỉ cần ghi vào tệp hoặc thực hiện các tác dụng phụ.

### Cách ly phiên

Việc phân phối Cron KHÔNG được phản ánh vào lịch sử hội thoại phiên cổng. Chúng chỉ tồn tại trong phiên riêng của công việc định kỳ. Điều này ngăn chặn các hành vi vi phạm luân phiên tin nhắn trong cuộc trò chuyện của cuộc trò chuyện mục tiêu.

## Bảo vệ đệ quy

Các phiên chạy cron đã tắt bộ công cụ 
`cronjob

. Điều này ngăn cản:
- Một công việc được lên lịch từ việc tạo các công việc định kỳ mới
- Lập kế hoạch đệ quy có thể làm bùng nổ việc sử dụng mã thông báo
- Sự đột biến ngẫu nhiên của lịch trình công việc từ bên trong công việc

## Khóa

Bộ lập lịch sử dụng khóa dựa trên tệp quy trình chéo (
`fcntl.flock
` trên Unix, 
`msvcrt.locking
` trên Windows) để ngăn các dấu tích chồng chéo thực thi cùng một lô công việc đến hạn hai lần — ngay cả giữa mã đánh dấu đang xử lý của cổng và lệnh gọi 
`Hermes cron
` / thủ công 
`tick()
` độc lập. Nếu không lấy được khóa, 
`tick()
` sẽ trả về 0 ngay lập tức.`##Giao diện CLI``Hermes cron
` CLI cung cấp khả năng quản lý công việc trực tiếp:

``` bash
Hermes cron list                    # Show all jobs
Hermes cron create                  # Interactive job creation (alias: add)
Hermes cron edit <job_id           # Edit job configuration
Hermes cron pause <job_id          # Pause a running job
Hermes cron resume <job_id         # Resume a paused job
Hermes cron run <job_id            # Trigger immediate execution
Hermes cron remove <job_id         # Delete a job

`

## Tài liệu liên quan
- [Cron Feature Guide](/docs/user-guide/features/cron)

- [Gateway Internals](./gateway-internals.md)
- [Agent Loop Internals](./agent-loop.md)