precis-cli 0.1.3__py3-none-any.whl

app/shared/services/ai/streaming/event_journal.py

@@ -0,0 +1,197 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview 流式事件日志（EventJournal）
+
+持久化流式事件序列，支持断线重连时通过 Last-Event-ID 续传。
+
+存储结构: {journal_dir}/{job_id}.journal，每行一个 JSON 对象（追加写入）:
+    {"id": 1, "event": "delta", "data": {"text": "你好"}, "ts": 1706000000.123}
+
+设计要点:
+- 文件而非内存: 刷新页面/后端重启后任务状态不丢；多请求共享同一事件源
+- 追加写入 + 文件锁: 保证并发追加时 id 递增且不丢失
+- 启动时扫描已有文件恢复 _next_id: 支持重连续传
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+from typing import Any
+
+from .types import TERMINAL_EVENTS
+
+logger = logging.getLogger(__name__)
+
+
+class EventJournal:
+    """@classdesc 流式事件日志
+
+    按 job_id 维度持久化事件序列，支持追加、续传读取、终止判定、清理。
+    """
+
+    def __init__(self, job_id: str, journal_dir: str):
+        """
+        @methoddesc 初始化事件日志
+
+        参数:
+            job_id: 任务 ID
+            journal_dir: 日志目录路径（由调用方决定，通常复用项目本地 .precis 目录）
+        """
+        self.job_id = job_id
+        self.journal_dir = journal_dir
+        self.journal_path = os.path.join(journal_dir, f"{job_id}.journal")
+        self._lock = threading.Lock()
+        self._ensure_dir()
+        # 从已有 journal 文件恢复下一个 id（支持服务重启后续传）
+        self._next_id = self._recover_next_id()
+
+    def _ensure_dir(self) -> None:
+        """确保日志目录存在。"""
+        try:
+            os.makedirs(self.journal_dir, exist_ok=True)
+        except OSError as e:
+            logger.warning(f"创建 journal 目录失败 {self.journal_dir}: {e}")
+
+    def _recover_next_id(self) -> int:
+        """扫描已有 journal 文件，返回下一个可用 id（已有最大 id + 1）。
+
+        无文件或为空时返回 1。
+        """
+        if not os.path.exists(self.journal_path):
+            return 1
+        max_id = 0
+        try:
+            with open(self.journal_path, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        entry = json.loads(line)
+                        eid = entry.get("id", 0)
+                        if isinstance(eid, int) and eid > max_id:
+                            max_id = eid
+                    except json.JSONDecodeError:
+                        continue
+        except OSError as e:
+            logger.warning(f"恢复 journal next_id 失败 {self.journal_path}: {e}")
+        return max_id + 1
+
+    def append(self, event: str, data: dict[str, Any], *, force_fsync: bool = False) -> int:
+        """
+        @methoddesc 追加一个事件，返回分配的递增 id
+
+        线程安全（文件锁 + 实例锁）。
+
+        性能优化：默认只 flush 不 fsync（避免每个 delta 字符阻塞事件循环）。
+        终止事件（completed/error/cancelled）应传 force_fsync=True 确保持久化。
+        force_fsync=True 的非终止事件（如 apply_pending）也建议 fsync。
+
+        参数:
+            event: 事件类型（见 types.py 常量）
+            data: 事件数据（需可 JSON 序列化）
+            force_fsync: 是否强制 fsync（终止事件/关键事件设 True）
+
+        返回:
+            分配的事件 id（从 1 开始递增）
+        """
+        entry: dict[str, Any] = {"id": 0, "event": event, "data": data, "ts": time.time()}
+        with self._lock:
+            entry["id"] = self._next_id
+            eid: int = self._next_id
+            self._next_id += 1
+            line = json.dumps(entry, ensure_ascii=False)
+            try:
+                # 追加写入，newline 分隔
+                with open(self.journal_path, "a", encoding="utf-8") as f:
+                    f.write(line + "\n")
+                    f.flush()
+                    # 仅终止/关键事件 fsync，避免高频 delta 阻塞事件循环（性能优化）
+                    if force_fsync:
+                        os.fsync(f.fileno())
+            except OSError as e:
+                logger.warning(f"追加 journal 事件失败 {self.journal_path}: {e}")
+        return eid
+
+    def _read_all_unlocked(self) -> list[tuple[int, str, dict[str, Any]]]:
+        """读取全部事件（不加锁，调用方自行加锁或保证无并发写）。"""
+        if not os.path.exists(self.journal_path):
+            return []
+        events: list[tuple[int, str, dict[str, Any]]] = []
+        try:
+            with open(self.journal_path, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        entry = json.loads(line)
+                        events.append((entry["id"], entry["event"], entry["data"]))
+                    except (json.JSONDecodeError, KeyError):
+                        continue
+        except OSError as e:
+            logger.warning(f"读取 journal 失败 {self.journal_path}: {e}")
+        return events
+
+    def read_all(self) -> list[tuple[int, str, dict[str, Any]]]:
+        """@methoddesc 读取全部事件，返回 (id, event, data) 元组列表（按 id 升序）。"""
+        with self._lock:
+            return self._read_all_unlocked()
+
+    def read_since(self, last_id: int) -> list[tuple[int, str, dict[str, Any]]]:
+        """
+        @methoddesc 读取 id > last_id 的所有事件（用于断线续传）
+
+        参数:
+            last_id: 客户端最后收到的事件 id（Last-Event-ID）
+
+        返回:
+            (id, event, data) 元组列表，仅含 id > last_id 的事件
+        """
+        with self._lock:
+            all_events = self._read_all_unlocked()
+        return [(eid, ev, data) for eid, ev, data in all_events if eid > last_id]
+
+    def is_terminated(self) -> bool:
+        """@methoddesc 判断最后一条事件是否为终止事件（completed/error/cancelled）。
+
+        返回:
+            True 表示任务已结束（用于已完成任务的重连场景，直接回放后关闭）
+        """
+        with self._lock:
+            events = self._read_all_unlocked()
+        if not events:
+            return False
+        last_event = events[-1][1]
+        return last_event in TERMINAL_EVENTS
+
+    def cleanup(self) -> None:
+        """@methoddesc 删除 journal 文件（任务完成 24h 后由调用方触发）。"""
+        with self._lock:
+            try:
+                if os.path.exists(self.journal_path):
+                    os.remove(self.journal_path)
+            except OSError as e:
+                logger.warning(f"清理 journal 文件失败 {self.journal_path}: {e}")
+
+    @property
+    def path(self) -> str:
+        """journal 文件绝对路径（供测试与调试使用）。"""
+        return self.journal_path

app/shared/services/ai/streaming/orchestrator.py

@@ -0,0 +1,262 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview 流式编排器（StreamingOrchestrator）
+
+把现有的 ChatAgentRunner / ConfigGenerationService / ConfigMigrationService
+包装成统一的事件流（StreamEvent 序列），落盘到 EventJournal 并推给 SSE 队列。
+
+设计原则（可维护性 + 健壮性）:
+- 业务逻辑零改动: 通过回调注入桥接 service 输出，不重写 service
+- emit 是唯一事件出口: 同时落盘 EventJournal（支持续传）+ 推给内存队列（实时 SSE）
+- finally 注销取消信号: 无论成功/取消/失败都清理，防止内存泄漏
+- 终止事件携带完整快照: 即使中途 delta 丢失，前端也能渲染完整结果
+- apply_actions 两阶段确认: 创建 ConfirmController 注册 store，桥接 apply_* 事件
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from app.shared.services.ai.agent.chat_tools.apply_actions import ApplyCallbacks
+from app.shared.services.ai.agent.chat_tools.ask_user import AskCallbacks
+from app.shared.services.ai.agent.types import ToolResult
+from app.shared.services.ai.chat_agent_runner import ChatAgentRunner
+from app.shared.services.ai.streaming.pending_interaction_store import (
+    ConfirmController,
+    InteractionController,
+    get_global_pending_interaction_store,
+)
+
+from .event_journal import EventJournal
+from .types import (
+    EVENT_APPLY_CONFIRMED,
+    EVENT_APPLY_PENDING,
+    EVENT_APPLY_REJECTED,
+    EVENT_CANCELLED,
+    EVENT_COMPLETED,
+    EVENT_DELTA,
+    EVENT_ERROR,
+    EVENT_FRONTEND_INSTRUCTION,
+    EVENT_STARTED,
+    EVENT_TOOL_CALL,
+    EVENT_TOOL_RESULT,
+    EVENT_TURN_START,
+    EVENT_USER_INPUT_REQUESTED,
+    EVENT_USER_RESPONDED,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class StreamingOrchestrator:
+    """@classdesc 流式编排器
+
+    包装底层 service 为事件流。每个实例对应一个 job_id 的完整生命周期。
+    """
+
+    def __init__(
+        self,
+        job_id: str,
+        journal: EventJournal,
+        cancel_event: asyncio.Event,
+        event_queue: asyncio.Queue[dict[str, Any]] | None = None,
+    ):
+        """
+        @methoddesc 初始化流式编排器
+
+        参数:
+            job_id: 任务 ID
+            journal: 事件日志（持久化续传）
+            cancel_event: 取消信号（由 cancel 端点 set）
+            event_queue: 可选的实时事件队列，推送给 SSE 响应。None 时只落盘不推队列。
+        """
+        self.job_id = job_id
+        self.journal = journal
+        self.cancel_event = cancel_event
+        self.event_queue = event_queue
+
+    def emit(self, event: str, data: dict[str, Any]) -> int:
+        """@methoddesc 追加一个事件到 journal（并推给队列，若有）。
+
+        参数:
+            event: 事件类型
+            data: 事件数据
+
+        返回:
+            分配的事件 id
+        """
+        # 终止事件 + apply_pending 强制 fsync（保证关键状态持久化，delta 等高频事件不 fsync）
+        from .types import TERMINAL_EVENTS
+
+        force_fsync = event in TERMINAL_EVENTS or event == EVENT_APPLY_PENDING
+        eid = self.journal.append(event, data, force_fsync=force_fsync)
+        if self.event_queue is not None:
+            try:
+                self.event_queue.put_nowait({"id": eid, "event": event, "data": data})
+            except asyncio.QueueFull:
+                logger.warning(f"事件队列已满，丢弃实时事件 {event} (job={self.job_id})")
+        return eid
+
+    def _emit_apply(self, event: str, payload: dict[str, Any]) -> None:
+        """@methoddesc 桥接 apply 事件回调（丢弃 emit 返回值以匹配 Callable[..., None]）。"""
+        self.emit(event, payload)
+
+    async def run_chat(
+        self,
+        message: str,
+        history: list[dict[str, str]] | None,
+        provider: Any,
+        project_path: str,
+        context_nodes: list[dict[str, Any]],
+        canvas_nodes: list[dict[str, Any]] | None = None,
+    ) -> None:
+        """@methoddesc 包装 ChatAgentRunner 为流式事件流
+
+        流程: started → (delta/turn_start/tool_call/tool_result 经回调) → completed/cancelled/error
+        新增: apply_pending → await 用户确认 → apply_confirmed/apply_rejected
+
+        参数:
+            message: 用户消息
+            history: 对话历史
+            provider: Provider 实例
+            project_path: 项目配置目录
+            context_nodes: 选中上下文节点
+            canvas_nodes: 画布全部业务节点快照（供 read_canvas 工具查询）
+        """
+        self.emit(EVENT_STARTED, {"job_id": self.job_id, "kind": "chat"})
+
+        # apply 的确认控制器现在由 ApplyActionsTool 每次 apply 时独立创建（按 apply_id 键控），
+        # 不再在 job 级创建单一控制器（避免第 2 个 apply 复用旧决策）。
+
+        # 创建 apply 事件桥接回调
+        apply_callbacks = ApplyCallbacks(
+            on_apply_pending=lambda payload: self._emit_apply(EVENT_APPLY_PENDING, payload),
+            on_apply_confirmed=lambda payload: self._emit_apply(EVENT_APPLY_CONFIRMED, payload),
+            on_apply_rejected=lambda payload: self._emit_apply(EVENT_APPLY_REJECTED, payload),
+            on_frontend_instruction=lambda payload: self._emit_apply(EVENT_FRONTEND_INSTRUCTION, payload),
+        )
+
+        # ask_user 事件桥接回调（与 apply_callbacks 平行）
+        ask_callbacks = AskCallbacks(
+            on_user_input_requested=lambda payload: self._emit_apply(EVENT_USER_INPUT_REQUESTED, payload),
+            on_user_responded=lambda payload: self._emit_apply(EVENT_USER_RESPONDED, payload),
+        )
+
+        runner = ChatAgentRunner(
+            provider=provider,
+            project_path=project_path,
+            context_nodes=context_nodes,
+            apply_callbacks=apply_callbacks,
+            ask_callbacks=ask_callbacks,
+            dry_run_enabled=True,
+            job_id=self.job_id,
+            canvas_nodes=canvas_nodes,
+        )
+
+        # 工具 label 映射（与 ChatAgentRunner._TOOL_LABELS 一致，供 tool_call 事件使用）
+        tool_labels = dict(ChatAgentRunner._TOOL_LABELS)
+
+        # 桥接回调：把 service 输出转为事件
+        def on_chunk(text: str) -> None:
+            self.emit(EVENT_DELTA, {"text": text})
+
+        def on_turn(turn: int) -> None:
+            self.emit(EVENT_TURN_START, {"turn": turn})
+
+        def on_tool_call(name: str, call_id: str, turn: int) -> None:
+            label = tool_labels.get(name, name)
+            self.emit(EVENT_TOOL_CALL, {"tool": name, "call_id": call_id, "turn": turn, "label": label})
+
+        def on_tool_result(tr: ToolResult) -> None:
+            self.emit(
+                EVENT_TOOL_RESULT,
+                {
+                    "call_id": tr.call_id,
+                    "name": tr.name,
+                    "success": tr.success,
+                    "label": tool_labels.get(tr.name, tr.name),
+                    "error": tr.error,
+                },
+            )
+
+        def cancelled() -> bool:
+            return self.cancel_event.is_set()
+
+        runner.configure_callbacks(
+            on_chunk=on_chunk,
+            on_turn=on_turn,
+            on_tool_call=on_tool_call,
+            on_tool_result=on_tool_result,
+            cancelled=cancelled,
+        )
+
+        try:
+            result = await runner.run(message, history)
+        except Exception as e:
+            logger.exception(f"StreamingOrchestrator run_chat 失败 (job={self.job_id})")
+            self.emit(EVENT_ERROR, {"message": f"Agent 执行失败: {e}", "code": "RUNNER_ERROR"})
+            return
+        finally:
+            # 兜底清理：拒绝该 job 下所有未决议的 apply 控制器（每次 apply 各自独立，可能有多个）
+            # 注意：apply 挂起时 finally 不可达（await 未返回），由 await_decision 超时兜底
+            pending_store = get_global_pending_interaction_store()
+            for controller in pending_store.pop_by_job_prefix(self.job_id):
+                if not controller.is_resolved:
+                    # store 同时持有 apply（ConfirmController）和 ask（InteractionController），
+                    # 两类 resolve 签名不同：apply 接 str（confirm/reject），ask 接 dict。
+                    if isinstance(controller, ConfirmController):
+                        logger.warning(
+                            f"run_chat finally 兜底 resolve reject (job={self.job_id}, apply={controller.request_id})"
+                        )
+                        await controller.resolve("reject")
+                    elif isinstance(controller, InteractionController):
+                        logger.warning(
+                            f"run_chat finally 兜底 resolve skip (job={self.job_id}, ask={controller.request_id})"
+                        )
+                        await controller.resolve({"skipped": True, "reason": "cancelled"})
+
+        # 终态判定：用 result.cancelled 显式字段（而非 success+iterations 启发式）
+        # cancel_event.is_set() 覆盖外部取消信号；result.cancelled 覆盖 executor 内部取消
+        if self.cancel_event.is_set() or getattr(result, "cancelled", False):
+            # 软取消：已落盘的 apply_actions 改动保留，轨迹如实显示
+            self.emit(
+                EVENT_CANCELLED,
+                {
+                    "completed_turns": getattr(result, "iterations", 0),
+                    "partial": True,
+                    "tool_steps": getattr(result, "tool_steps", []),
+                    "reply": getattr(result, "reply", ""),
+                },
+            )
+        elif not getattr(result, "success", True):
+            # 失败（非取消）
+            self.emit(
+                EVENT_ERROR,
+                {"message": getattr(result, "error", "未知错误"), "code": "AGENT_FAILED"},
+            )
+        else:
+            # 成功：终止事件携带完整快照（容错兜底）
+            self.emit(
+                EVENT_COMPLETED,
+                {
+                    "reply": getattr(result, "reply", ""),
+                    "frontend_instructions": getattr(result, "frontend_instructions", []),
+                    "tool_steps": getattr(result, "tool_steps", []),
+                    "iterations": getattr(result, "iterations", 0),
+                },
+            )

app/shared/services/ai/streaming/pending_interaction_store.py

@@ -0,0 +1,227 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview 交互门控控制器与挂起交互存储
+
+提供 apply_actions 两阶段确认与 ask_user 交互问答所需的核心组件：
+- ConfirmController: apply 确认门（二元 confirm/reject，向后兼容，apply 代码仍用）
+- InteractionController: 通用交互门（任意 dict response，ask_user 用）
+- PendingInteractionStore Protocol: 存储接口（apply + ask 共用）
+- InMemoryPendingInteractionStore: 进程内 dict 实现（默认）
+- get_global_pending_interaction_store: 全局单例
+
+设计要点:
+- 两类 controller 共存于同一 store，靠 key 前缀区分：
+  apply = "{job_id}#apply#{seq}"，ask = "{job_id}#ask#{seq}"
+- resolve() 幂等 + 原子（asyncio.Lock 保护 check-then-set）
+- await_decision() / await_response() 带超时，超时自动返回默认值（防死锁）
+- 全局 store 使用 threading.Lock 保护并发安全
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from typing import Any, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+# apply 确认超时时间（秒）：超时后自动 reject，防止协程永久挂起
+_APPLY_CONFIRM_TIMEOUT = 300.0
+
+# ask 交互超时时间（秒）：超时后自动返回 {skipped: true, reason: timeout}
+_INTERACTION_TIMEOUT = 300.0
+
+
+class ConfirmController:
+    """@classdesc apply 确认门控制器（向后兼容，apply_actions 专用）
+
+    在 apply_actions 协程内创建，调用 await_decision() 挂起协程。
+    确认端点调用 resolve() 唤醒协程。超时未决策则自动返回 reject。
+    """
+
+    def __init__(self, request_id: str, pending_payload: dict[str, Any] | None = None) -> None:
+        self.request_id = request_id
+        self.pending_payload = pending_payload
+        self._gate = asyncio.Event()
+        self._decision: str | None = None
+        self._resolve_lock = asyncio.Lock()
+
+    async def await_decision(self) -> str:
+        """阻塞等待用户决策，返回 decision 字符串("confirm" 或 "reject")。
+
+        带 5 分钟超时：超时自动返回 "reject"。
+        """
+        try:
+            await asyncio.wait_for(self._gate.wait(), timeout=_APPLY_CONFIRM_TIMEOUT)
+        except TimeoutError:
+            logger.warning(
+                "apply 确认超时(%ds)，自动 reject: request_id=%s",
+                int(_APPLY_CONFIRM_TIMEOUT),
+                self.request_id,
+            )
+            return "reject"
+        return self._decision or "reject"
+
+    async def resolve(self, decision: str) -> None:
+        """唤醒协程并写入决策。已决议则忽略(幂等)。"""
+        async with self._resolve_lock:
+            if self._gate.is_set():
+                return
+            self._decision = decision
+            self._gate.set()
+
+    @property
+    def is_resolved(self) -> bool:
+        return self._gate.is_set()
+
+    @property
+    def decision(self) -> str | None:
+        return self._decision
+
+
+class InteractionController:
+    """@classdesc 通用交互门控制器（ask_user 专用）
+
+    与 ConfirmController 的区别：
+    - ConfirmController: 二元 confirm/reject，await_decision() 返回固定字符串
+    - InteractionController: 任意 dict response，await_response() 返回 dict
+
+    在 ask_user 协程内创建，调用 await_response() 挂起协程。
+    /respond 端点调用 resolve(response) 唤醒协程。
+    超时自动返回 {skipped: true, reason: timeout}。
+    """
+
+    def __init__(self, request_id: str, pending_payload: dict[str, Any] | None = None) -> None:
+        self.request_id = request_id
+        self.pending_payload = pending_payload  # question schema（发给前端的提问内容）
+        self._gate = asyncio.Event()
+        self._response: dict[str, Any] | None = None
+        self._resolve_lock = asyncio.Lock()
+
+    async def await_response(self) -> dict[str, Any]:
+        """阻塞等待用户回答，返回 response dict。
+
+        带 5 分钟超时：超时返回 {skipped: true, reason: timeout}，
+        让 LLM 统一按 skip 处理（无需区分超时和主动跳过）。
+        """
+        try:
+            await asyncio.wait_for(self._gate.wait(), timeout=_INTERACTION_TIMEOUT)
+        except TimeoutError:
+            logger.warning(
+                "ask 等待超时(%ds)，自动 skip: request_id=%s",
+                int(_INTERACTION_TIMEOUT),
+                self.request_id,
+            )
+            return {"skipped": True, "reason": "timeout"}
+        return self._response or {"skipped": True, "reason": "empty"}
+
+    async def resolve(self, response: dict[str, Any]) -> None:
+        """唤醒协程并写入回答。已决议则忽略(幂等)。"""
+        async with self._resolve_lock:
+            if self._gate.is_set():
+                return
+            self._response = response
+            self._gate.set()
+
+    @property
+    def is_resolved(self) -> bool:
+        return self._gate.is_set()
+
+    @property
+    def response(self) -> dict[str, Any] | None:
+        return self._response
+
+
+@runtime_checkable
+class PendingInteractionStore(Protocol):
+    """挂起交互存储接口(Protocol，功能 C 可替换为持久化实现)。
+
+    apply 和 ask controller 共用此接口，靠 key 前缀区分类型。
+    @runtime_checkable 让 isinstance 检查可用（用于依赖注入与测试断言）。
+    """
+
+    def put(self, interaction_id: str, controller: ConfirmController | InteractionController) -> None: ...
+    def get(self, interaction_id: str) -> ConfirmController | InteractionController | None: ...
+    def pop(self, interaction_id: str) -> ConfirmController | InteractionController | None: ...
+    def get_all_by_job(self, job_id: str) -> list[ConfirmController | InteractionController]: ...
+    def pop_by_job_prefix(self, job_id: str) -> list[ConfirmController | InteractionController]: ...
+
+
+class InMemoryPendingInteractionStore:
+    """进程内 dict 实现（apply + ask 共用）。
+
+    键命名（统一加类型前缀）：
+    - apply: "{job_id}#apply#{seq}"
+    - ask:   "{job_id}#ask#{seq}"
+
+    兼容回退：get/pop 传入 job_id 时，找该 job 下唯一未决议项
+    （匹配 f"{job_id}#" 前缀，覆盖 apply 和 ask 两类）。
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[str, ConfirmController | InteractionController] = {}
+        self._lock = threading.Lock()
+
+    def put(self, interaction_id: str, controller: ConfirmController | InteractionController) -> None:
+        with self._lock:
+            self._store[interaction_id] = controller
+
+    def get(self, interaction_id: str) -> ConfirmController | InteractionController | None:
+        with self._lock:
+            # 精确匹配 interaction_id（apply_id 或 ask_id）
+            if interaction_id in self._store:
+                return self._store[interaction_id]
+            # 兼容回退：传入的是 job_id，找该 job 下唯一未决议项
+            pending = [
+                c for aid, c in self._store.items() if aid.startswith(f"{interaction_id}#") and not c.is_resolved
+            ]
+            return pending[0] if len(pending) == 1 else None
+
+    def pop(self, interaction_id: str) -> ConfirmController | InteractionController | None:
+        with self._lock:
+            if interaction_id in self._store:
+                return self._store.pop(interaction_id)
+            # 兼容回退
+            matches = [
+                (aid, c) for aid, c in self._store.items() if aid.startswith(f"{interaction_id}#") and not c.is_resolved
+            ]
+            if len(matches) == 1:
+                return self._store.pop(matches[0][0])
+            return None
+
+    def get_all_by_job(self, job_id: str) -> list[ConfirmController | InteractionController]:
+        """获取某 job 下所有挂起的 controller（apply + ask，用于 cancel 时批量清理）。"""
+        with self._lock:
+            prefix = f"{job_id}#"
+            return [c for aid, c in self._store.items() if aid.startswith(prefix)]
+
+    def pop_by_job_prefix(self, job_id: str) -> list[ConfirmController | InteractionController]:
+        """弹出某 job 下所有挂起的 controller。"""
+        with self._lock:
+            prefix = f"{job_id}#"
+            matched = [(aid, c) for aid, c in self._store.items() if aid.startswith(prefix)]
+            for aid, _ in matched:
+                self._store.pop(aid, None)
+            return [c for _, c in matched]
+
+
+_global_store: PendingInteractionStore = InMemoryPendingInteractionStore()
+
+
+def get_global_pending_interaction_store() -> PendingInteractionStore:
+    """获取全局 PendingInteractionStore 单例。"""
+    return _global_store