Skip to content

fix: prefer named weekday cron examples #6091

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Soulter merged 1 commit into from
Mar 12, 2026
+16 −1
Merged

fix: prefer named weekday cron examples #6091

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion astrbot/core/tools/cron_tools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ class CreateActiveCronTool(FunctionTool[AstrAgentContext]):
"properties": {
"cron_expression": {
"type": "string",
"description": "Cron expression defining recurring schedule (e.g., '0 8 * * *').",
"description": "Cron expression defining recurring schedule (e.g., '0 8 * * *' or '0 23 * * mon-fri'). Prefer named weekdays like 'mon-fri' or 'sat,sun' instead of numeric day-of-week ranges such as '1-5' to avoid ambiguity across cron implementations.",
Copy link
Contributor

@sourcery-ai sourcery-ai bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: 澄清这里期望使用的是哪种 cron 方言，而不是笼统地依赖“不同实现行为不同”的说法。

关于使用具名工作日的说明是有帮助的，但用户仍然不知道我们实际遵循的是哪种 cron 语义（POSIX、Quartz，还是某个特定库）。请明确写出我们使用的 cron 风格或解析器（例如 "POSIX-style 5-field cron" 或具体库名），这样用户就可以参考正确的外部文档，并避免诸如星期天是 0 还是 7、以及区间行为差异之类的歧义。

建议的实现方式：

                    "description": "Cron expression defining recurring schedule using standard 5-field POSIX-style cron syntax (minute hour day-of-month month day-of-week), as parsed by this service's cron scheduler. For example: '0 8 * * *' or '0 23 * * mon-fri'. Prefer named weekdays like 'mon-fri' or 'sat,sun' instead of numeric day-of-week ranges such as '1-5' to avoid ambiguity around Sunday handling (0 vs 7) and differing cron implementations.",

如果你的项目使用了某个特定的 cron 库（例如 croniter、APScheduler、celery，或自研解析器），应进一步在描述中将其名字写明。比如将 “this service's cron scheduler” 替换为 “the croniter parser” 或 “APScheduler’s cron trigger semantics”，这样用户就可以参考相应的外部文档。

Original comment in English

suggestion: Clarify which cron dialect is expected rather than relying on generic implementation differences.

The note about named weekdays helps, but users still won’t know which cron semantics we follow (POSIX, Quartz, or a specific library). Please explicitly state the cron flavor or parser we use (e.g., "POSIX-style 5-field cron" or the library name) so users can rely on the correct external docs and avoid ambiguities like 0 vs 7 for Sunday or differing range behavior.

Suggested implementation:

                    "description": "Cron expression defining recurring schedule using standard 5-field POSIX-style cron syntax (minute hour day-of-month month day-of-week), as parsed by this service's cron scheduler. For example: '0 8 * * *' or '0 23 * * mon-fri'. Prefer named weekdays like 'mon-fri' or 'sat,sun' instead of numeric day-of-week ranges such as '1-5' to avoid ambiguity around Sunday handling (0 vs 7) and differing cron implementations.",

If your project uses a specific cron library (e.g., croniter, APScheduler, celery, or a bespoke parser), you should further refine the description to name it explicitly. For example, replace “this service's cron scheduler” with “the croniter parser” or “APScheduler’s cron trigger semantics” so users can reference the appropriate external documentation.

},
"run_at": {
"type": "string",
Expand Down
15 changes: 15 additions & 0 deletions tests/unit/test_cron_tools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
"""Tests for cron tool metadata."""

from astrbot.core.tools.cron_tools import CreateActiveCronTool


def test_create_future_task_cron_description_prefers_named_weekdays():
"""The cron tool should steer users toward unambiguous named weekdays."""
tool = CreateActiveCronTool()

description = tool.parameters["properties"]["cron_expression"]["description"]

assert "mon-fri" in description
assert "sat,sun" in description
assert "1-5" in description
assert "avoid ambiguity" in description
Comment on lines +6 to +15
Copy link
Contributor

@sourcery-ai sourcery-ai bot Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion (testing): 建议同时断言原有的通用 cron 示例仍然保留，就像 PR 描述中所说的那样。

PR 描述中说明，原来的通用示例（例如 0 8 * * *）应该在新增具名工作日指引的基础上继续保留，但当前测试只检查了新增的指引。加上一条诸如 assert "0 8 * * *" in description 的断言，可以确保这两个部分的需求都被覆盖，从而更好地防止回归。

Original comment in English

suggestion (testing): Consider also asserting that the original generic cron example is preserved as described in the PR summary.

The PR description specifies that the original generic example (e.g. 0 8 * * *) should remain in addition to the new named weekday guidance, but this test only checks the new guidance. Adding an assertion like assert "0 8 * * *" in description would ensure both parts of the requirement are covered and better protect against regressions.