feat: add system tools and state updates

backend/services/brains/prompt_brain.py

@@ -43,14 +43,14 @@ from services.message_stage import (
     MessageStageRunner,
     MessageStageSpec,
 )
-from services.runtime_variables import DynamicVariableStore
+from services.runtime_variables import DynamicVariableError, DynamicVariableStore
+from services.system_tools import SYSTEM_TOOL_KINDS, state_update_properties
 from services.tool_executor import ToolExecutionError, ToolExecutor
 from services.tool_policy import policy_for_tool
 
 
 PREFLIGHT_TIMEOUT_SECONDS = 30
 
-
 class PromptBrain(BaseBrain):
     spec = BrainSpec(
         type="prompt",
@@ -123,22 +123,37 @@ class PromptBrain(BaseBrain):
             set(cfg.llm_tool_ids) if cfg.llm_tool_ids is not None else None
         )
         schemas: list[FunctionSchema] = []
+        registered_names: set[str] = set()
         for tool in cfg.tools:
             if llm_tool_ids is not None and tool.id not in llm_tool_ids:
                 continue
-            if tool.type == "end_call":
+            if tool.type == "system":
                 schema, handler = self._make_end_call_tool(tool, runtime)
             elif tool.type in {"http", "mcp", "client"}:
                 schema, handler = self._make_remote_tool(tool, runtime)
             else:
                 continue
             schemas.append(schema)
+            registered_names.add(schema.name)
             policy = policy_for_tool(tool)
             runtime.llm.register_function(
                 tool.function_name,
                 handler,
                 cancel_on_interruption=policy.cancel_on_interruption,
             )
+        for kind in cfg.system_tools or []:
+            if kind not in SYSTEM_TOOL_KINDS:
+                logger.warning(f"忽略未知系统工具: {kind}")
+                continue
+            schema, handler = self._make_system_tool(kind, runtime)
+            if schema.name in registered_names:
+                logger.warning(
+                    f"跳过系统工具 {schema.name}: 与已绑定工具函数名冲突"
+                )
+                continue
+            registered_names.add(schema.name)
+            schemas.append(schema)
+            runtime.llm.register_function(schema.name, handler)
         runtime.set_tools(schemas)
 
     async def run_preflight(self) -> None:
@@ -582,3 +597,162 @@ class PromptBrain(BaseBrain):
             required=["reason"] if capture_reason else [],
         )
         return schema, end_call
+
+    # ---------- 内置系统工具(助手配置 system_tools 开关) ----------
+
+    def _make_system_tool(self, kind: str, runtime: BrainRuntime):
+        if kind == "end_conversation":
+            return self._make_end_conversation_tool(runtime)
+        if kind == "update_state":
+            return self._make_update_state_tool(runtime)
+        if kind == "skip_turn":
+            return self._make_skip_turn_tool()
+        if kind == "request_human_handoff":
+            return self._make_handoff_tool(runtime)
+        raise ValueError(f"未知系统工具: {kind}")
+
+    def _make_end_conversation_tool(self, runtime: BrainRuntime):
+        """结束本次对话,等待模型已生成的告别语播完后再挂断。"""
+
+        async def end_conversation(params: FunctionCallParams) -> None:
+            reason = str(
+                params.arguments.get("reason") or "end_conversation"
+            ).strip()
+            self._waiting_for_generated_end_speech = True
+            runtime.call_end.begin(reason)
+            await params.result_callback(
+                {"status": "success", "action": "ending_call"},
+                properties=FunctionCallResultProperties(run_llm=False),
+            )
+
+        schema = FunctionSchema(
+            name="end_conversation",
+            description=(
+                "礼貌地结束本次对话。当用户明确告别、表示任务已完成"
+                "或要求挂断时调用。"
+            ),
+            properties={
+                "reason": {
+                    "type": "string",
+                    "description": "结束对话的简短原因。",
+                }
+            },
+            required=[],
+        )
+        return schema, end_conversation
+
+    def _make_update_state_tool(self, runtime: BrainRuntime):
+        """更新已声明的动态变量(会话状态),并让模型继续当前回答。"""
+
+        writable = state_update_properties(self._cfg.dynamic_variable_definitions)
+
+        async def update_state(params: FunctionCallParams) -> None:
+            state = dict(params.arguments or {})
+            try:
+                changed = self._store.assign_declared_many(state)
+            except DynamicVariableError as exc:
+                await params.result_callback(
+                    {"status": "error", "message": f"状态更新失败: {exc}"}
+                )
+                return
+            if changed:
+                self._refresh_prompt()
+                await runtime.queue_frame(
+                    OutputTransportMessageUrgentFrame(
+                        message={
+                            "type": "session-variables",
+                            "reason": "update_state",
+                            "variables": self._store.public_values(),
+                            "changed": changed,
+                        }
+                    )
+                )
+            await params.result_callback(
+                {
+                    "status": "success",
+                    "changed": changed,
+                    "variables": self._store.public_values(),
+                }
+            )
+
+        schema = FunctionSchema(
+            name="update_state",
+            description=(
+                "静默更新本次对话中已经声明并明确列出的动态变量。"
+                "只提交本轮获得或确认的信息，更新后继续当前回答。"
+            ),
+            properties=writable,
+            required=[],
+        )
+        return schema, update_state
+
+    def _make_skip_turn_tool(self):
+        """跳过当前轮次,不生成任何语音回复。"""
+
+        async def skip_turn(params: FunctionCallParams) -> None:
+            reason = str(params.arguments.get("reason") or "").strip()
+            result = {"status": "success", "action": "skip_turn"}
+            if reason:
+                result["reason"] = reason
+            await params.result_callback(
+                result,
+                properties=FunctionCallResultProperties(run_llm=False),
+            )
+
+        schema = FunctionSchema(
+            name="skip_turn",
+            description=(
+                "跳过当前轮次,不生成任何语音回复。"
+                "仅当用户明确要求稍等、话还没说完，或输入可确认只是噪音时调用。"
+            ),
+            properties={
+                "reason": {
+                    "type": "string",
+                    "description": "跳过本轮的原因(可选)。",
+                }
+            },
+            required=[],
+        )
+        return schema, skip_turn
+
+    def _make_handoff_tool(self, runtime: BrainRuntime):
+        """提交人工接管请求；请求完成前保持当前 AI 会话可用。"""
+
+        async def request_human_handoff(params: FunctionCallParams) -> None:
+            reason = str(
+                params.arguments.get("reason") or "human_handoff"
+            ).strip()
+            await runtime.queue_frame(
+                OutputTransportMessageUrgentFrame(
+                    message={
+                        "type": "handoff-requested",
+                        "source": "prompt-system-tool",
+                        "reason": reason,
+                        "message": "用户请求转接人工服务。",
+                    }
+                )
+            )
+            await params.result_callback(
+                {
+                    "status": "requested",
+                    "action": "human_handoff_requested",
+                    "message": "人工接管请求已提交，请告知用户正在等待人工响应。",
+                }
+            )
+
+        schema = FunctionSchema(
+            name="request_human_handoff",
+            description=(
+                "提交人工接管请求。当用户明确要求人工服务、投诉升级或 AI 无法"
+                "解决时调用。该工具只提交请求，不代表人工已经接通；调用后继续"
+                "回复用户并说明正在等待人工响应。"
+            ),
+            properties={
+                "reason": {
+                    "type": "string",
+                    "description": "转接人工的原因。",
+                }
+            },
+            required=[],
+        )
+        return schema, request_human_handoff