AstrBot 4.13.2__py3-none-any.whl → 4.14.1__py3-none-any.whl

astrbot/core/pipeline/scheduler.py

@@ -85,6 +85,4 @@ class PipelineScheduler:
         if isinstance(event, WebChatMessageEvent | WecomAIBotMessageEvent):
             await event.send(None)
 
-        event.trace.record("event_end")
-
         logger.debug("pipeline 执行完毕。")

astrbot/core/platform/astr_message_event.py

@@ -22,6 +22,7 @@ from astrbot.core.message.components import (
 from astrbot.core.message.message_event_result import MessageChain, MessageEventResult
 from astrbot.core.platform.message_type import MessageType
 from astrbot.core.provider.entities import ProviderRequest
+from astrbot.core.agent.tool import ToolSet
 from astrbot.core.utils.metrics import Metric
 from astrbot.core.utils.trace import TraceSpan
 
@@ -73,9 +74,6 @@ class AstrMessageEvent(abc.ABC):
         self.span = self.trace
         """事件级 TraceSpan(别名: span)"""
 
-        self.trace.record("umo", umo=self.unified_msg_origin)
-        self.trace.record("event_created", created_at=self.created_at)
-
         self._has_send_oper = False
         """在此次事件中是否有过至少一次发送消息的操作"""
         self.call_llm = False
@@ -358,6 +356,7 @@ class AstrMessageEvent(abc.ABC):
         self,
         prompt: str,
         func_tool_manager=None,
+        tool_set: ToolSet | None = None,
         session_id: str = "",
         image_urls: list[str] | None = None,
         contexts: list | None = None,
@@ -380,7 +379,7 @@ class AstrMessageEvent(abc.ABC):
 
         contexts: 当指定 contexts 时，将会使用 contexts 作为上下文。如果同时传入了 conversation，将会忽略 conversation。
 
-        func_tool_manager: 函数工具管理器，用于调用函数工具。用 self.context.get_llm_tool_manager() 获取。
+        func_tool_manager: [Deprecated] 函数工具管理器，用于调用函数工具。用 self.context.get_llm_tool_manager() 获取。已过时，请使用 tool_set 参数代替。
 
         conversation: 可选。如果指定，将在指定的对话中进行 LLM 请求。对话的人格会被用于 LLM 请求，并且结果将会被记录到对话中。
 
@@ -396,7 +395,8 @@ class AstrMessageEvent(abc.ABC):
             prompt=prompt,
             session_id=session_id,
             image_urls=image_urls,
-            func_tool=func_tool_manager,
+            # func_tool=func_tool_manager,
+            func_tool=tool_set,
             contexts=contexts,
             system_prompt=system_prompt,
             conversation=conversation,

astrbot/core/platform/platform.py

@@ -90,6 +90,14 @@ class Platform(abc.ABC):
     def get_stats(self) -> dict:
         """获取平台统计信息"""
         meta = self.meta()
+        meta_info = {
+            "id": meta.id,
+            "name": meta.name,
+            "display_name": meta.adapter_display_name or meta.name,
+            "description": meta.description,
+            "support_streaming_message": meta.support_streaming_message,
+            "support_proactive_message": meta.support_proactive_message,
+        }
         return {
             "id": meta.id or self.config.get("id"),
             "type": meta.name,
@@ -105,6 +113,7 @@ class Platform(abc.ABC):
             if self.last_error
             else None,
             "unified_webhook": self.unified_webhook(),
+            "meta": meta_info,
         }
 
     @abc.abstractmethod

astrbot/core/platform/platform_metadata.py

@@ -19,3 +19,5 @@ class PlatformMetadata:
 
     support_streaming_message: bool = True
     """平台是否支持真实流式传输"""
+    support_proactive_message: bool = True
+    """平台是否支持主动消息推送（非用户触发）"""

astrbot/core/platform/sources/dingtalk/dingtalk_adapter.py

@@ -99,6 +99,7 @@ class DingtalkPlatformAdapter(Platform):
             description="钉钉机器人官方 API 适配器",
             id=cast(str, self.config.get("id")),
             support_streaming_message=True,
+            support_proactive_message=False,
         )
 
     async def create_message_card(

astrbot/core/platform/sources/qqofficial/qqofficial_platform_adapter.py

@@ -136,6 +136,7 @@ class QQOfficialPlatformAdapter(Platform):
             name="qq_official",
             description="QQ 机器人官方 API 适配器",
             id=cast(str, self.config.get("id")),
+            support_proactive_message=False,
         )
 
     @staticmethod

astrbot/core/platform/sources/qqofficial_webhook/qo_webhook_adapter.py

@@ -118,6 +118,7 @@ class QQOfficialWebhookPlatformAdapter(Platform):
             name="qq_official_webhook",
             description="QQ 机器人官方 API 适配器",
             id=cast(str, self.config.get("id")),
+            support_proactive_message=False,
         )
 
     async def run(self):

astrbot/core/platform/sources/webchat/webchat_adapter.py

@@ -86,6 +86,7 @@ class WebChatAdapter(Platform):
             name="webchat",
             description="webchat",
             id="webchat",
+            support_proactive_message=False,
         )
 
     async def send_by_session(

astrbot/core/platform/sources/wecom/wecom_adapter.py

@@ -224,6 +224,7 @@ class WecomPlatformAdapter(Platform):
             "wecom 适配器",
             id=self.config.get("id", "wecom"),
             support_streaming_message=False,
+            support_proactive_message=False,
         )
 
     @override

astrbot/core/platform/sources/wecom_ai_bot/wecomai_adapter.py

@@ -128,6 +128,7 @@ class WecomAIBotAdapter(Platform):
             name="wecom_ai_bot",
             description="企业微信智能机器人适配器，支持 HTTP 回调接收消息",
             id=self.config.get("id", "wecom_ai_bot"),
+            support_proactive_message=False,
         )
 
         # 初始化 API 客户端

astrbot/core/platform/sources/weixin_official_account/weixin_offacc_adapter.py

@@ -228,6 +228,7 @@ class WeixinOfficialAccountPlatformAdapter(Platform):
             "微信公众平台 适配器",
             id=self.config.get("id", "weixin_official_account"),
             support_streaming_message=False,
+            support_proactive_message=False,
         )
 
     @override

astrbot/core/provider/entities.py

@@ -165,7 +165,7 @@ class ProviderRequest:
 
                 result_parts.append(f"{role}: {''.join(msg_parts)}")
 
-        return result_parts
+        return "\n".join(result_parts)
 
     async def assemble_context(self) -> dict:
         """将请求(prompt 和 image_urls)包装成 OpenAI 的消息格式。"""

astrbot/core/skills/skill_manager.py

@@ -62,6 +62,7 @@ def build_skills_prompt(skills: list[SkillInfo]) -> str:
     # Based on openai/codex
     return (
         "## Skills\n"
+        "You have many useful skills that can help you accomplish various tasks.\n"
         "A skill is a set of local instructions stored in a `SKILL.md` file.\n"
         "### Available skills\n"
         f"{skills_block}\n"
@@ -69,21 +70,21 @@ def build_skills_prompt(skills: list[SkillInfo]) -> str:
         "\n"
         "- Discovery: The list above shows all skills available in this session. Full instructions live in the referenced `SKILL.md`.\n"
         "- Trigger rules: Use a skill if the user names it or the task matches its description. Do not carry skills across turns unless re-mentioned\n"
-        "- Unavailable: If a skill is missing or unreadable, say so and fallback.\n"
         "### How to use a skill (progressive disclosure):\n"
-        "  1) After deciding to use a skill, open its `SKILL.md` and read only what is necessary to follow the workflow.\n"
-        "  2) Load only directly referenced files, DO NOT bulk-load everything.\n"
-        "  3) If `scripts/` exist, prefer running or patching them instead of retyping large blocks of code.\n"
-        "  4) If `assets/` or templates exist, reuse them rather than recreating everything from scratch.\n"
+        "  0) Mandatory grounding: Before using any skill, you MUST inspect its `SKILL.md` using shell tools"
+        " (e.g., `cat`, `head`, `sed`, `awk`, `grep`). Do not rely on assumptions or memory.\n"
+        "  1) Load only directly referenced files, DO NOT bulk-load everything.\n"
+        "  2) If `scripts/` exist, prefer running or patching them instead of retyping large blocks of code.\n"
+        "  3) If `assets/` or templates exist, reuse them rather than recreating everything from scratch.\n"
         "- Coordination:\n"
         "  - If multiple skills apply, choose the minimal set that covers the request and state the order in which you will use them.\n"
         "  - Announce which skill(s) you are using and why (one short line). If you skip an obvious skill, explain why.\n"
         "  - Prefer to use `astrbot_*` tools to perform skills that need to run scripts.\n"
         "- Context hygiene:\n"
-        "  - Keep context small: summarize long sections instead of pasting them, and load extra files only when necessary.\n"
         "  - Avoid deep reference chasing: unless blocked, open only files that are directly linked from `SKILL.md`.\n"
-        "  - When variants exist (frameworks, providers, domains), select only the relevant reference file(s) and note that choice.\n"
-        "- Failure handling: If a skill cannot be applied, state the issue and continue with the best alternative."
+        "- Failure handling: If a skill cannot be applied, state the issue and continue with the best alternative.\n"
+        "### Example\n"
+        "When you decided to use a skill, use shell tool to read its `SKILL.md`, e.g., `head -40 skills/code_formatter/SKILL.md`, and you can increase or decrease the number of lines as needed.\n"
     )
 
 

astrbot/core/star/context.py

@@ -12,6 +12,7 @@ from astrbot.core.agent.tool import ToolSet
 from astrbot.core.astrbot_config_mgr import AstrBotConfigManager
 from astrbot.core.config.astrbot_config import AstrBotConfig
 from astrbot.core.conversation_mgr import ConversationManager
+from astrbot.core.cron.manager import CronJobManager
 from astrbot.core.db import BaseDatabase
 from astrbot.core.knowledge_base.kb_mgr import KnowledgeBaseManager
 from astrbot.core.message.message_event_result import MessageChain
@@ -34,6 +35,7 @@ from astrbot.core.star.filter.platform_adapter_type import (
     ADAPTER_NAME_2_TYPE,
     PlatformAdapterType,
 )
+from astrbot.core.subagent_orchestrator import SubAgentOrchestrator
 
 from ..exceptions import ProviderNotFoundError
 from .filter.command import CommandFilter
@@ -65,6 +67,8 @@ class Context:
         persona_manager: PersonaManager,
         astrbot_config_mgr: AstrBotConfigManager,
         knowledge_base_manager: KnowledgeBaseManager,
+        cron_manager: CronJobManager,
+        subagent_orchestrator: SubAgentOrchestrator | None = None,
     ):
         self._event_queue = event_queue
         """事件队列。消息平台通过事件队列传递消息事件。"""
@@ -86,6 +90,9 @@ class Context:
         """配置文件管理器(非webui)"""
         self.kb_manager = knowledge_base_manager
         """知识库管理器"""
+        self.cron_manager = cron_manager
+        """Cron job manager, initialized by core lifecycle."""
+        self.subagent_orchestrator = subagent_orchestrator
 
     async def llm_generate(
         self,
@@ -463,6 +470,7 @@ class Context:
                     _parts.append(part)
                     if part in flags and i + 1 < len(module_part):
                         _parts.append(module_part[i + 1])
+                        module_part.append("main")
                         break
                 tool.handler_module_path = ".".join(_parts)
                 module_path = tool.handler_module_path

astrbot/core/star/filter/custom_filter.py

@@ -37,9 +37,9 @@ class CustomFilter(HandlerFilter, metaclass=CustomFilterMeta):
 class CustomFilterOr(CustomFilter):
     def __init__(self, filter1: CustomFilter, filter2: CustomFilter):
         super().__init__()
-        if not isinstance(filter1, CustomFilter | CustomFilterAnd | CustomFilterOr):
+        if not isinstance(filter1, (CustomFilter, CustomFilterAnd, CustomFilterOr)):
             raise ValueError(
-                "CustomFilter lass can only operate with other CustomFilter.",
+                "CustomFilter class can only operate with other CustomFilter.",
             )
         self.filter1 = filter1
         self.filter2 = filter2
@@ -51,7 +51,7 @@ class CustomFilterOr(CustomFilter):
 class CustomFilterAnd(CustomFilter):
     def __init__(self, filter1: CustomFilter, filter2: CustomFilter):
         super().__init__()
-        if not isinstance(filter1, CustomFilter | CustomFilterAnd | CustomFilterOr):
+        if not isinstance(filter1, (CustomFilter, CustomFilterAnd, CustomFilterOr)):
             raise ValueError(
                 "CustomFilter lass can only operate with other CustomFilter.",
             )

astrbot/core/star/register/star_handler.py

@@ -150,7 +150,7 @@ def register_custom_filter(custom_type_filter, *args, **kwargs):
         if args:
             raise_error = args[0]
 
-    if not isinstance(custom_filter, CustomFilterAnd | CustomFilterOr):
+    if not isinstance(custom_filter, (CustomFilterAnd, CustomFilterOr)):
         custom_filter = custom_filter(raise_error)
 
     def decorator(awaitable):

astrbot/core/subagent_orchestrator.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Any
+
+from astrbot import logger
+from astrbot.core.agent.agent import Agent
+from astrbot.core.agent.handoff import HandoffTool
+from astrbot.core.persona_mgr import PersonaManager
+from astrbot.core.provider.func_tool_manager import FunctionToolManager
+
+
+class SubAgentOrchestrator:
+    """Loads subagent definitions from config and registers handoff tools.
+
+    This is intentionally lightweight: it does not execute agents itself.
+    Execution happens via HandoffTool in FunctionToolExecutor.
+    """
+
+    def __init__(self, tool_mgr: FunctionToolManager, persona_mgr: PersonaManager):
+        self._tool_mgr = tool_mgr
+        self._persona_mgr = persona_mgr
+        self.handoffs: list[HandoffTool] = []
+
+    async def reload_from_config(self, cfg: dict[str, Any]) -> None:
+        from astrbot.core.astr_agent_context import AstrAgentContext
+
+        agents = cfg.get("agents", [])
+        if not isinstance(agents, list):
+            logger.warning("subagent_orchestrator.agents must be a list")
+            return
+
+        handoffs: list[HandoffTool] = []
+        for item in agents:
+            if not isinstance(item, dict):
+                continue
+            if not item.get("enabled", True):
+                continue
+
+            name = str(item.get("name", "")).strip()
+            if not name:
+                continue
+
+            persona_id = item.get("persona_id")
+            persona_data = None
+            if persona_id:
+                try:
+                    persona_data = await self._persona_mgr.get_persona(persona_id)
+                except StopIteration:
+                    logger.warning(
+                        "SubAgent persona %s not found, fallback to inline prompt.",
+                        persona_id,
+                    )
+
+            instructions = str(item.get("system_prompt", "")).strip()
+            public_description = str(item.get("public_description", "")).strip()
+            provider_id = item.get("provider_id")
+            if provider_id is not None:
+                provider_id = str(provider_id).strip() or None
+            tools = item.get("tools", [])
+            begin_dialogs = None
+
+            if persona_data:
+                instructions = persona_data.system_prompt or instructions
+                begin_dialogs = persona_data.begin_dialogs
+                tools = persona_data.tools
+                if public_description == "" and persona_data.system_prompt:
+                    public_description = persona_data.system_prompt[:120]
+            if tools is None:
+                tools = None
+            elif not isinstance(tools, list):
+                tools = []
+            else:
+                tools = [str(t).strip() for t in tools if str(t).strip()]
+
+            agent = Agent[AstrAgentContext](
+                name=name,
+                instructions=instructions,
+                tools=tools,  # type: ignore
+            )
+            agent.begin_dialogs = begin_dialogs
+            # The tool description should be a short description for the main LLM,
+            # while the subagent system prompt can be longer/more specific.
+            handoff = HandoffTool(
+                agent=agent,
+                tool_description=public_description or None,
+            )
+
+            # Optional per-subagent chat provider override.
+            handoff.provider_id = provider_id
+
+            handoffs.append(handoff)
+
+        for handoff in handoffs:
+            logger.info(f"Registered subagent handoff tool: {handoff.name}")
+
+        self.handoffs = handoffs

astrbot/core/tools/cron_tools.py

@@ -0,0 +1,174 @@
+from datetime import datetime
+
+from pydantic import Field
+from pydantic.dataclasses import dataclass
+
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.agent.tool import FunctionTool, ToolExecResult
+from astrbot.core.astr_agent_context import AstrAgentContext
+
+
+@dataclass
+class CreateActiveCronTool(FunctionTool[AstrAgentContext]):
+    name: str = "create_future_task"
+    description: str = (
+        "Create a future task for your future. Supports recurring cron expressions or one-time run_at datetime. "
+        "Use this when you or the user want scheduled follow-up or proactive actions."
+    )
+    parameters: dict = Field(
+        default_factory=lambda: {
+            "type": "object",
+            "properties": {
+                "cron_expression": {
+                    "type": "string",
+                    "description": "Cron expression defining recurring schedule (e.g., '0 8 * * *').",
+                },
+                "run_at": {
+                    "type": "string",
+                    "description": "ISO datetime for one-time execution, e.g., 2026-02-02T08:00:00+08:00. Use with run_once=true.",
+                },
+                "note": {
+                    "type": "string",
+                    "description": "Detailed instructions for your future agent to execute when it wakes.",
+                },
+                "name": {
+                    "type": "string",
+                    "description": "Optional label to recognize this future task.",
+                },
+                "run_once": {
+                    "type": "boolean",
+                    "description": "If true, the task will run only once and then be deleted. Use run_at to specify the time.",
+                },
+            },
+            "required": ["note"],
+        }
+    )
+
+    async def call(
+        self, context: ContextWrapper[AstrAgentContext], **kwargs
+    ) -> ToolExecResult:
+        cron_mgr = context.context.context.cron_manager
+        if cron_mgr is None:
+            return "error: cron manager is not available."
+
+        cron_expression = kwargs.get("cron_expression")
+        run_at = kwargs.get("run_at")
+        run_once = bool(kwargs.get("run_once", False))
+        note = str(kwargs.get("note", "")).strip()
+        name = str(kwargs.get("name") or "").strip() or "active_agent_task"
+
+        if not note:
+            return "error: note is required."
+        if run_once and not run_at:
+            return "error: run_at is required when run_once=true."
+        if (not run_once) and not cron_expression:
+            return "error: cron_expression is required when run_once=false."
+        if run_once and cron_expression:
+            cron_expression = None
+        run_at_dt = None
+        if run_at:
+            try:
+                run_at_dt = datetime.fromisoformat(str(run_at))
+            except Exception:
+                return "error: run_at must be ISO datetime, e.g., 2026-02-02T08:00:00+08:00"
+
+        payload = {
+            "session": context.context.event.unified_msg_origin,
+            "sender_id": context.context.event.get_sender_id(),
+            "note": note,
+            "origin": "tool",
+        }
+
+        job = await cron_mgr.add_active_job(
+            name=name,
+            cron_expression=str(cron_expression) if cron_expression else None,
+            payload=payload,
+            description=note,
+            run_once=run_once,
+            run_at=run_at_dt,
+        )
+        next_run = job.next_run_time or run_at_dt
+        suffix = (
+            f"one-time at {next_run}"
+            if run_once
+            else f"expression '{cron_expression}' (next {next_run})"
+        )
+        return f"Scheduled future task {job.job_id} ({job.name}) {suffix}."
+
+
+@dataclass
+class DeleteCronJobTool(FunctionTool[AstrAgentContext]):
+    name: str = "delete_future_task"
+    description: str = "Delete a future task (cron job) by its job_id."
+    parameters: dict = Field(
+        default_factory=lambda: {
+            "type": "object",
+            "properties": {
+                "job_id": {
+                    "type": "string",
+                    "description": "The job_id returned when the job was created.",
+                }
+            },
+            "required": ["job_id"],
+        }
+    )
+
+    async def call(
+        self, context: ContextWrapper[AstrAgentContext], **kwargs
+    ) -> ToolExecResult:
+        cron_mgr = context.context.context.cron_manager
+        if cron_mgr is None:
+            return "error: cron manager is not available."
+        job_id = kwargs.get("job_id")
+        if not job_id:
+            return "error: job_id is required."
+        await cron_mgr.delete_job(str(job_id))
+        return f"Deleted cron job {job_id}."
+
+
+@dataclass
+class ListCronJobsTool(FunctionTool[AstrAgentContext]):
+    name: str = "list_future_tasks"
+    description: str = "List existing future tasks (cron jobs) for inspection."
+    parameters: dict = Field(
+        default_factory=lambda: {
+            "type": "object",
+            "properties": {
+                "job_type": {
+                    "type": "string",
+                    "description": "Optional filter: basic or active_agent.",
+                }
+            },
+        }
+    )
+
+    async def call(
+        self, context: ContextWrapper[AstrAgentContext], **kwargs
+    ) -> ToolExecResult:
+        cron_mgr = context.context.context.cron_manager
+        if cron_mgr is None:
+            return "error: cron manager is not available."
+        job_type = kwargs.get("job_type")
+        jobs = await cron_mgr.list_jobs(job_type)
+        if not jobs:
+            return "No cron jobs found."
+        lines = []
+        for j in jobs:
+            lines.append(
+                f"{j.job_id} | {j.name} | {j.job_type} | run_once={getattr(j, 'run_once', False)} | enabled={j.enabled} | next={j.next_run_time}"
+            )
+        return "\n".join(lines)
+
+
+CREATE_CRON_JOB_TOOL = CreateActiveCronTool()
+DELETE_CRON_JOB_TOOL = DeleteCronJobTool()
+LIST_CRON_JOBS_TOOL = ListCronJobsTool()
+
+__all__ = [
+    "CREATE_CRON_JOB_TOOL",
+    "DELETE_CRON_JOB_TOOL",
+    "LIST_CRON_JOBS_TOOL",
+    "CreateActiveCronTool",
+    "DeleteCronJobTool",
+    "ListCronJobsTool",
+]

astrbot/core/utils/history_saver.py

@@ -0,0 +1,31 @@
+import json
+
+from astrbot import logger
+from astrbot.core.conversation_mgr import ConversationManager
+from astrbot.core.platform.astr_message_event import AstrMessageEvent
+from astrbot.core.provider.entities import ProviderRequest
+
+
+async def persist_agent_history(
+    conversation_manager: ConversationManager,
+    *,
+    event: AstrMessageEvent,
+    req: ProviderRequest,
+    summary_note: str,
+) -> None:
+    """Persist agent interaction into conversation history."""
+    if not req or not req.conversation:
+        return
+
+    history = []
+    try:
+        history = json.loads(req.conversation.history or "[]")
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Failed to parse conversation history: %s", exc)
+    history.append({"role": "user", "content": "Output your last task result below."})
+    history.append({"role": "assistant", "content": summary_note})
+    await conversation_manager.update_conversation(
+        event.unified_msg_origin,
+        req.conversation.cid,
+        history=history,
+    )

astrbot/core/utils/trace.py

@@ -50,6 +50,10 @@ class TraceSpan:
         self.started_at = time.time()
 
     def record(self, action: str, **fields: Any) -> None:
+        # Check if trace recording is enabled
+        if not astrbot_config.get("trace_enable", True):
+            return
+
         payload = {
             "type": "trace",
             "level": "TRACE",

astrbot/dashboard/routes/__init__.py

@@ -5,6 +5,7 @@ from .chatui_project import ChatUIProjectRoute
 from .command import CommandRoute
 from .config import ConfigRoute
 from .conversation import ConversationRoute
+from .cron import CronRoute
 from .file import FileRoute
 from .knowledge_base import KnowledgeBaseRoute
 from .log import LogRoute
@@ -15,6 +16,7 @@ from .session_management import SessionManagementRoute
 from .skills import SkillsRoute
 from .stat import StatRoute
 from .static_file import StaticFileRoute
+from .subagent import SubAgentRoute
 from .tools import ToolsRoute
 from .update import UpdateRoute
 
@@ -26,6 +28,7 @@ __all__ = [
     "CommandRoute",
     "ConfigRoute",
     "ConversationRoute",
+    "CronRoute",
     "FileRoute",
     "KnowledgeBaseRoute",
     "LogRoute",
@@ -35,6 +38,7 @@ __all__ = [
     "SessionManagementRoute",
     "StatRoute",
     "StaticFileRoute",
+    "SubAgentRoute",
     "ToolsRoute",
     "SkillsRoute",
     "UpdateRoute",