feat(ports): 新增 ToolDispatchFactory/PromptBuilderFactory Protocol

4 个新 Protocol 类型:
- ToolDispatchFn: 工具调度函数签名
- ToolDispatchFactory: per-version 工具调度工厂
- PromptBuilderFn: Prompt 构建函数签名
- PromptBuilderFactory: per-version prompt 构建工厂

含 runtime_checkable isinstance 测试。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

app/ports.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path  # noqa: TC003 — runtime_checkable Protocol 需运行时可见
-from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
     import numpy as np
@@ -74,3 +74,73 @@ class OCRProvider(Protocol):
     """
 
     async def transcribe_frames(self, frame_paths: list[Path]) -> str: ...
+
+
+@runtime_checkable
+class ToolDispatchFn(Protocol):
+    """工具调度函数签名。
+
+    参数:
+        tool_name: 工具名称。
+        args: 工具参数字典。
+        context: 上下文字典（包含 session_id）。
+
+    返回:
+        工具执行结果文本。
+    """
+
+    async def __call__(
+        self, tool_name: str, args: dict[str, Any], *, context: dict[str, Any]
+    ) -> str: ...
+
+
+@runtime_checkable
+class ToolDispatchFactory(Protocol):
+    """per-version 工具调度工厂。
+
+    通过注入 skills_dir 生产对应版本的 ToolDispatchFn。
+
+    参数:
+        skills_dir: skill 文件目录（None 则不加载 skill）。
+
+    返回:
+        ToolDispatchFn 实例。
+    """
+
+    def __call__(self, *, skills_dir: Path | None = None) -> ToolDispatchFn: ...
+
+
+@runtime_checkable
+class PromptBuilderFn(Protocol):
+    """Prompt 构建函数签名。
+
+    参数:
+        qa: 待构建 prompt 的题目。
+
+    返回:
+        (system_prompt, user_prompt) 二元组。
+    """
+
+    def __call__(self, qa: GeneratedQuestion) -> tuple[str, str]: ...
+
+
+@runtime_checkable
+class PromptBuilderFactory(Protocol):
+    """per-version prompt 构建工厂。
+
+    通过注入 skills_dir 和 prompts_dir 生产对应版本的 PromptBuilderFn。
+
+    参数:
+        skills_dir: skill 文件目录（None 则不加载 skill）。
+        prompts_dir: prompt 文件目录（None 则使用默认目录）。
+
+    返回:
+        PromptBuilderFn 实例。
+    """
+
+    def __call__(
+        self,
+        *,
+        skills_dir: Path | None = None,
+        prompts_dir: Path | None = None,
+    ) -> PromptBuilderFn: ...