jarvis-ai-assistant 0.1.222__py3-none-any.whl → 0.7.0__py3-none-any.whl

jarvis/jarvis_agent/edit_file_handler.py

@@ -13,7 +13,11 @@ class EditFileHandler(OutputHandler):
             ot("PATCH file=(?:'([^']+)'|\"([^\"]+)\"|([^>]+))") + r"\s*"
             r"(?:"
             + ot("DIFF")
-            + r"\s*"
+            + r"\s*(?:"
+            # 可选的RANGE标签，限制替换行号范围
+            + r"(?:" + ot("RANGE") + r"(.*?)" + ct("RANGE") + r"\s*)?"
+            + r"(?:"
+            # 单点替换（SEARCH/REPLACE）
             + ot("SEARCH")
             + r"(.*?)"
             + ct("SEARCH")
@@ -21,15 +25,29 @@ class EditFileHandler(OutputHandler):
             + ot("REPLACE")
             + r"(.*?)"
             + ct("REPLACE")
+            + r"|"
+            # 区间替换（SEARCH_START/SEARCH_END/REPLACE）
+            + ot("SEARCH_START")
+            + r"(.*?)"
+            + ct("SEARCH_START")
+            + r"\s*"
+            + ot("SEARCH_END")
+            + r"(.*?)"
+            + ct("SEARCH_END")
             + r"\s*"
+            + ot("REPLACE")
+            + r"(.*?)"
+            + ct("REPLACE")
+            + r")"
+            + r")\s*"
             + ct("DIFF")
             + r"\s*)+"
-            + ct("PATCH"),
-            re.DOTALL,
+            + r"^" + ct("PATCH"),
+            re.DOTALL | re.MULTILINE,
         )
         self.diff_pattern = re.compile(
             ot("DIFF")
-            + r"\s*"
+            + r"\s*(?:" + ot("RANGE") + r"(.*?)" + ct("RANGE") + r"\s*)?"
             + ot("SEARCH")
             + r"(.*?)"
             + ct("SEARCH")
@@ -41,6 +59,24 @@ class EditFileHandler(OutputHandler):
             + ct("DIFF"),
             re.DOTALL,
         )
+        self.diff_range_pattern = re.compile(
+            ot("DIFF")
+            + r"\s*(?:" + ot("RANGE") + r"(.*?)" + ct("RANGE") + r"\s*)?"
+            + ot("SEARCH_START")
+            + r"(.*?)"
+            + ct("SEARCH_START")
+            + r"\s*"
+            + ot("SEARCH_END")
+            + r"(.*?)"
+            + ct("SEARCH_END")
+            + r"\s*"
+            + ot("REPLACE")
+            + r"(.*?)"
+            + ct("REPLACE")
+            + r"\s*"
+            + ct("DIFF"),
+            re.DOTALL,
+        )
 
     def handle(self, response: str, agent: Any) -> Tuple[bool, str]:
         """处理文件编辑响应
@@ -54,17 +90,24 @@ class EditFileHandler(OutputHandler):
         """
         patches = self._parse_patches(response)
         if not patches:
+            # 当响应中存在 PATCH 标签但未能解析出合法的补丁内容时，提示格式错误并给出合法格式
+            has_patch_open = bool(re.search("<PATCH", response))
+            has_patch_close = bool(re.search(ct("PATCH"), response))
+            if has_patch_open and has_patch_close:
+                return False, f"PATCH格式错误。合法的格式如下：\n{self.prompt()}"
             return False, "未找到有效的文件编辑指令"
 
+        # 记录 PATCH 操作调用统计
+        from jarvis.jarvis_stats.stats import StatsManager
+
+        StatsManager.increment("patch", group="tool")
+
         results = []
 
         for file_path, diffs in patches.items():
             file_path = os.path.abspath(file_path)
-            file_patches = [
-                {"SEARCH": diff["SEARCH"], "REPLACE": diff["REPLACE"]} for diff in diffs
-            ]
+            file_patches = diffs
 
-            print(f"📝 正在处理文件 {file_path}...")
             success, result = self._fast_edit(file_path, file_patches)
 
             if success:
@@ -84,7 +127,11 @@ class EditFileHandler(OutputHandler):
         Returns:
             bool: 返回是否能处理该响应
         """
-        return bool(self.patch_pattern.search(response))
+        # 只要检测到 PATCH 标签（包含起止标签），即认为可处理，
+        # 具体合法性由 handle() 内的解析与错误提示负责
+        has_patch_open = bool(re.search("<PATCH", response))
+        has_patch_close = bool(re.search(ct("PATCH"), response))
+        return has_patch_open and has_patch_close
 
     def prompt(self) -> str:
         """获取处理器的提示信息
@@ -92,17 +139,48 @@ class EditFileHandler(OutputHandler):
         Returns:
             str: 返回处理器的提示字符串
         """
-        return f"""文件编辑指令格式：
-{ot("PATCH file=文件路径")}
-{ot("DIFF")}
+        from jarvis.jarvis_utils.config import get_patch_format
+
+        patch_format = get_patch_format()
+
+        search_prompt = f"""{ot("DIFF")}
+{ot("RANGE")}起止行号(如: 10-50)，可选{ct("RANGE")}
 {ot("SEARCH")}原始代码{ct("SEARCH")}
 {ot("REPLACE")}新代码{ct("REPLACE")}
-{ct("DIFF")}
+{ct("DIFF")}"""
+
+        search_range_prompt = f"""{ot("DIFF")}
+{ot("RANGE")}起止行号(如: 10-50)，可选{ct("RANGE")}
+{ot("SEARCH_START")}起始标记{ct("SEARCH_START")}
+{ot("SEARCH_END")}结束标记{ct("SEARCH_END")}
+{ot("REPLACE")}替换内容{ct("REPLACE")}
+{ct("DIFF")}"""
+
+        if patch_format == "search":
+            formats = search_prompt
+            supported_formats = "仅支持单点替换（SEARCH/REPLACE）"
+            usage_recommendation = ""
+        elif patch_format == "search_range":
+            formats = search_range_prompt
+            supported_formats = "仅支持区间替换（SEARCH_START/SEARCH_END/REPLACE），可选RANGE限定行号范围"
+            usage_recommendation = ""
+        else:  # all
+            formats = f"{search_prompt}\n或\n{search_range_prompt}"
+            supported_formats = "支持两种DIFF块：单点替换（SEARCH/REPLACE）与区间替换（SEARCH_START/SEARCH_END/REPLACE）"
+            usage_recommendation = "\n推荐：优先使用单点替换（SEARCH/REPLACE）模式，除非需要大段修改，否则不要使用区间替换（SEARCH_START/SEARCH_END/REPLACE）模式"
+
+        return f"""文件编辑指令格式：
+{ot("PATCH file=文件路径")}
+{formats}
 {ct("PATCH")}
 
-可以返回多个PATCH块用于同时修改多个文件
-每个PATCH块可以包含多个DIFF块，每个DIFF块包含一组搜索和替换内容。
-搜索文本必须能在文件中唯一匹配，否则编辑将失败。"""
+注意：
+- {ot("PATCH")} 和 {ct("PATCH")} 必须出现在行首，否则不生效（会被忽略）
+- {supported_formats}{usage_recommendation}
+- {ot("RANGE")}start-end{ct("RANGE")} 可用于单点替换（SEARCH/REPLACE）和区间替换（SEARCH_START/SEARCH_END）模式，表示只在指定行号范围内进行匹配与替换（1-based，闭区间）；省略则在整个文件范围内处理
+- 单点替换要求 SEARCH 在有效范围内唯一匹配（仅替换第一个匹配）
+- 区间替换会从包含 {ot("SEARCH_START")} 的行首开始，到包含 {ot("SEARCH_END")} 的行尾结束，替换整个区域
+否则编辑将失败。"""
 
     def name(self) -> str:
         """获取处理器的名称
@@ -135,18 +213,77 @@ class EditFileHandler(OutputHandler):
                 }
         """
         patches: Dict[str, List[Dict[str, str]]] = {}
+
         for match in self.patch_pattern.finditer(response):
             # Get the file path from the appropriate capture group
             file_path = match.group(1) or match.group(2) or match.group(3)
-            diffs = []
-            for diff_match in self.diff_pattern.finditer(match.group(0)):
-                # 完全保留原始格式（包括所有空白和换行）
-                diffs.append(
-                    {
-                        "SEARCH": diff_match.group(1),  # 原始SEARCH内容
-                        "REPLACE": diff_match.group(2),  # 原始REPLACE内容
+            diffs: List[Dict[str, str]] = []
+
+            # 逐块解析，保持 DIFF 顺序
+            diff_block_pattern = re.compile(ot("DIFF") + r"(.*?)" + ct("DIFF"), re.DOTALL)
+            for block_match in diff_block_pattern.finditer(match.group(0)):
+                block_text = block_match.group(1)
+
+                # 提取可选的行号范围
+                range_scope = None
+                range_scope_match = re.match(
+                    r"^\s*" + ot("RANGE") + r"(.*?)" + ct("RANGE") + r"\s*",
+                    block_text,
+                    re.DOTALL,
+                )
+                if range_scope_match:
+                    range_scope = range_scope_match.group(1).strip()
+                    # 仅移除块首部的RANGE标签，避免误删内容中的同名标记
+                    block_text = block_text[range_scope_match.end():]
+                # 统一按 all 解析：无视配置，始终尝试区间替换
+                range_match = re.search(
+                    ot("SEARCH_START")
+                    + r"(.*?)"
+                    + ct("SEARCH_START")
+                    + r"\s*"
+                    + ot("SEARCH_END")
+                    + r"(.*?)"
+                    + ct("SEARCH_END")
+                    + r"\s*"
+                    + ot("REPLACE")
+                    + r"(.*?)"
+                    + ct("REPLACE"),
+                    block_text,
+                    re.DOTALL,
+                )
+                if range_match:
+                    diff_item: Dict[str, str] = {
+                        "SEARCH_START": range_match.group(1),  # 原始SEARCH_START内容
+                        "SEARCH_END": range_match.group(2),  # 原始SEARCH_END内容
+                        "REPLACE": range_match.group(3),  # 原始REPLACE内容
                     }
+                    if range_scope:
+                        diff_item["RANGE"] = range_scope
+                    diffs.append(diff_item)
+                    continue
+
+                # 解析单点替换（统一按 all 解析：无视配置，始终尝试单点替换）
+                single_match = re.search(
+                    ot("SEARCH")
+                    + r"(.*?)"
+                    + ct("SEARCH")
+                    + r"\s*"
+                    + ot("REPLACE")
+                    + r"(.*?)"
+                    + ct("REPLACE"),
+                    block_text,
+                    re.DOTALL,
                 )
+                if single_match:
+                    diff_item = {
+                        "SEARCH": single_match.group(1),  # 原始SEARCH内容
+                        "REPLACE": single_match.group(2),  # 原始REPLACE内容
+                    }
+                    # SEARCH 模式支持 RANGE，如果存在则添加
+                    if range_scope:
+                        diff_item["RANGE"] = range_scope
+                    diffs.append(diff_item)
+
             if diffs:
                 if file_path in patches:
                     patches[file_path].extend(diffs)
@@ -190,102 +327,258 @@ class EditFileHandler(OutputHandler):
             failed_patches: List[Dict[str, Any]] = []
             successful_patches = 0
 
-            for patch in patches:
-                patch_count += 1
-                search_text = patch["SEARCH"]
-                replace_text = patch["REPLACE"]
-
-                # 精确匹配搜索文本（保留原始换行和空格）
-                exact_search = search_text
+            # 当存在RANGE时，确保按行号从后往前应用补丁，避免前面补丁影响后续RANGE的行号
+            ordered_patches: List[Dict[str, str]] = []
+            range_items: List[Tuple[int, int, int, Dict[str, str]]] = []
+            non_range_items: List[Tuple[int, Dict[str, str]]] = []
+            for idx, p in enumerate(patches):
+                r = p.get("RANGE")
+                if r and str(r).strip():
+                    m = re.match(r"\s*(\d+)\s*-\s*(\d+)\s*$", str(r))
+                    if m:
+                        start_line = int(m.group(1))
+                        end_line = int(m.group(2))
+                        range_items.append((start_line, end_line, idx, p))
+                    else:
+                        # RANGE格式无效的补丁保持原有顺序
+                        non_range_items.append((idx, p))
+                else:
+                    # 无RANGE的补丁保持原有顺序
+                    non_range_items.append((idx, p))
+            # 先应用RANGE补丁：按start_line、end_line、原始索引逆序
+            range_items.sort(key=lambda x: (x[0], x[1], x[2]), reverse=True)
+            ordered_patches = [item[3] for item in range_items] + [item[1] for item in non_range_items]
+
+            patch_count = len(ordered_patches)
+            for patch in ordered_patches:
                 found = False
 
-                if exact_search in modified_content:
-                    # 直接执行替换（保留所有原始格式）
-                    modified_content = modified_content.replace(
-                        exact_search, replace_text
-                    )
-                    print(f"✅ 补丁 #{patch_count} 应用成功")
-                    found = True
-                else:
-                    # 如果匹配不到，并且search与replace块的首尾都是换行，尝试去掉第一个和最后一个换行
+                # 处理可选的RANGE范围：格式 "start-end"（1-based, 闭区间）
+                scoped = False
+                prefix = suffix = ""
+                base_content = modified_content
+                if "RANGE" in patch and str(patch["RANGE"]).strip():
+                    m = re.match(r"\s*(\d+)\s*-\s*(\d+)\s*$", str(patch["RANGE"]))
+                    if not m:
+                        error_msg = "RANGE格式无效，应为 'start-end' 的行号范围（1-based, 闭区间）"
+                        failed_patches.append({"patch": patch, "error": error_msg})
+                        # 不进行本补丁其它处理
+                        continue
+                    start_line = int(m.group(1))
+                    end_line = int(m.group(2))
+
+                    # 拆分为三段
+                    lines = modified_content.splitlines(keepends=True)
+                    total_lines = len(lines)
                     if (
-                        search_text.startswith("\n")
-                        and search_text.endswith("\n")
-                        and replace_text.startswith("\n")
-                        and replace_text.endswith("\n")
+                        start_line < 1
+                        or end_line < 1
+                        or start_line > end_line
+                        or start_line > total_lines
                     ):
-                        stripped_search = search_text[1:-1]
-                        stripped_replace = replace_text[1:-1]
-                        if stripped_search in modified_content:
-                            modified_content = modified_content.replace(
-                                stripped_search, stripped_replace
-                            )
-                            print(f"✅ 补丁 #{patch_count} 应用成功 (自动去除首尾换行)")
-                            found = True
-
-                    if not found:
-                        # 尝试增加缩进重试
-                        current_search = search_text
-                        current_replace = replace_text
+                        error_msg = f"RANGE行号无效（文件共有{total_lines}行）"
+                        failed_patches.append({"patch": patch, "error": error_msg})
+                        continue
+                    # 截断end_line不超过总行数
+                    end_line = min(end_line, total_lines)
+
+                    prefix = "".join(lines[: start_line - 1])
+                    base_content = "".join(lines[start_line - 1 : end_line])
+                    suffix = "".join(lines[end_line:])
+                    scoped = True
+
+                # 单点替换
+                if "SEARCH" in patch:
+                    search_text = patch["SEARCH"]
+                    replace_text = patch["REPLACE"]
+
+                    # 精确匹配搜索文本（保留原始换行和空格）
+                    exact_search = search_text
+
+                    def _count_occurrences(haystack: str, needle: str) -> int:
+                        if not needle:
+                            return 0
+                        return haystack.count(needle)
+
+                    # 1) 精确匹配，要求唯一
+                    cnt = _count_occurrences(base_content, exact_search)
+                    if cnt == 1:
+                        base_content = base_content.replace(exact_search, replace_text, 1)
+                        found = True
+                    elif cnt > 1:
+                        # 提供更详细的错误信息，帮助调试
+                        range_info = f"（RANGE: {patch.get('RANGE', '无')}）" if "RANGE" in patch else ""
+                        base_preview = base_content[:200] + "..." if len(base_content) > 200 else base_content
+                        error_msg = (
+                            f"SEARCH 在指定范围内出现多次，要求唯一匹配{range_info}。"
+                            f"匹配次数: {cnt}。"
+                            f"搜索内容: {repr(exact_search[:50])}。"
+                            f"范围内容预览: {repr(base_preview)}"
+                        )
+                        failed_patches.append({"patch": patch, "error": error_msg})
+                        # 不继续尝试其它变体
+                        continue
+                    else:
+                        # 2) 若首尾均为换行，尝试去掉首尾换行后匹配，要求唯一
                         if (
-                            current_search.startswith("\n")
-                            and current_search.endswith("\n")
-                            and current_replace.startswith("\n")
-                            and current_replace.endswith("\n")
+                            search_text.startswith("\n")
+                            and search_text.endswith("\n")
+                            and replace_text.startswith("\n")
+                            and replace_text.endswith("\n")
                         ):
-                            current_search = current_search[1:-1]
-                            current_replace = current_replace[1:-1]
-
-                        for space_count in range(1, 17):
-                            indented_search = "\n".join(
-                                " " * space_count + line if line.strip() else line
-                                for line in current_search.split("\n")
-                            )
-                            indented_replace = "\n".join(
-                                " " * space_count + line if line.strip() else line
-                                for line in current_replace.split("\n")
-                            )
-                            if indented_search in modified_content:
-                                modified_content = modified_content.replace(
-                                    indented_search, indented_replace
-                                )
-                                print(
-                                    f"✅ 补丁 #{patch_count} 应用成功 (自动增加 {space_count} 个空格缩进)"
+                            stripped_search = search_text[1:-1]
+                            stripped_replace = replace_text[1:-1]
+                            cnt2 = _count_occurrences(base_content, stripped_search)
+                            if cnt2 == 1:
+                                base_content = base_content.replace(
+                                    stripped_search, stripped_replace, 1
                                 )
                                 found = True
-                                break
+                            elif cnt2 > 1:
+                                error_msg = "SEARCH 在指定范围内出现多次（去掉首尾换行后），要求唯一匹配"
+                                failed_patches.append({"patch": patch, "error": error_msg})
+                                continue
+
+                        # 3) 尝试缩进适配（1..16个空格），要求唯一
+                        if not found:
+                            current_search = search_text
+                            current_replace = replace_text
+                            if (
+                                current_search.startswith("\n")
+                                and current_search.endswith("\n")
+                                and current_replace.startswith("\n")
+                                and current_replace.endswith("\n")
+                            ):
+                                current_search = current_search[1:-1]
+                                current_replace = current_replace[1:-1]
+
+                            for space_count in range(1, 17):
+                                indented_search = "\n".join(
+                                    " " * space_count + line if line.strip() else line
+                                    for line in current_search.split("\n")
+                                )
+                                indented_replace = "\n".join(
+                                    " " * space_count + line if line.strip() else line
+                                    for line in current_replace.split("\n")
+                                )
+                                cnt3 = _count_occurrences(base_content, indented_search)
+                                if cnt3 == 1:
+                                    base_content = base_content.replace(
+                                        indented_search, indented_replace, 1
+                                    )
+                                    found = True
+                                    break
+                                elif cnt3 > 1:
+                                    error_msg = "SEARCH 在指定范围内出现多次（缩进适配后），要求唯一匹配"
+                                    failed_patches.append({"patch": patch, "error": error_msg})
+                                    # 多匹配直接失败，不再继续尝试其它缩进
+                                    found = False
+                                    break
+
+                        if not found:
+                            # 未找到任何可用的唯一匹配
+                            failed_patches.append({"patch": patch, "error": "未找到唯一匹配的SEARCH"})
+
+                # 区间替换
+                elif "SEARCH_START" in patch and "SEARCH_END" in patch:
+                    search_start = patch["SEARCH_START"]
+                    search_end = patch["SEARCH_END"]
+                    replace_text = patch["REPLACE"]
+
+                    # 范围替换（包含边界），命中第一个起始标记及其后的第一个结束标记
+                    start_idx = base_content.find(search_start)
+                    if start_idx == -1:
+                        error_msg = "未找到SEARCH_START"
+                        failed_patches.append({"patch": patch, "error": error_msg})
+                    else:
+                        # 从 search_start 之后开始查找 search_end
+                        end_idx = base_content.find(search_end, start_idx + len(search_start))
+                        if end_idx == -1:
+                            error_msg = "在SEARCH_START之后未找到SEARCH_END"
+                            failed_patches.append({"patch": patch, "error": error_msg})
+                        else:
+                            # 将替换范围扩展到整行
+                            # 找到 start_idx 所在行的行首
+                            line_start_idx = base_content.rfind("\n", 0, start_idx) + 1
+
+                            # 找到 end_idx 所在行的行尾
+                            match_end_pos = end_idx + len(search_end)
+                            line_end_idx = base_content.find("\n", match_end_pos)
+
+                            if line_end_idx == -1:
+                                # 如果没有找到换行符，说明是最后一行
+                                end_of_range = len(base_content)
+                            else:
+                                # 包含换行符
+                                end_of_range = line_end_idx + 1
+
+                            final_replace_text = replace_text
+                            original_slice = base_content[line_start_idx:end_of_range]
+
+                            # 如果原始片段以换行符结尾，且替换内容不为空且不以换行符结尾，
+                            # 则为替换内容添加换行符以保持格式
+                            if (
+                                final_replace_text
+                                and original_slice.endswith("\n")
+                                and not final_replace_text.endswith("\n")
+                            ):
+                                final_replace_text += "\n"
+
+                            base_content = (
+                                base_content[:line_start_idx]
+                                + final_replace_text
+                                + base_content[end_of_range:]
+                            )
+                            found = True
 
-                if found:
-                    successful_patches += 1
                 else:
-                    error_msg = "搜索文本在文件中不存在"
-                    PrettyOutput.print(
-                        f"{error_msg}：\n{search_text}",
-                        output_type=OutputType.WARNING,
-                    )
+                    error_msg = "不支持的补丁格式"
                     failed_patches.append({"patch": patch, "error": error_msg})
 
+                # 若使用了RANGE，则将局部修改写回整体内容
+                if found:
+                    if scoped:
+                        modified_content = prefix + base_content + suffix
+                    else:
+                        modified_content = base_content
+                    successful_patches += 1
+
             # 写入修改后的内容
             with open(file_path, "w", encoding="utf-8") as f:
                 f.write(modified_content)
 
             if failed_patches:
-                error_details = [
-                    f"  - 失败的补丁: \n{p['patch']['SEARCH']}\n    错误: {p['error']}"
-                    for p in failed_patches
-                ]
-                summary = (
-                    f"文件 {file_path} 修改部分成功。\n"
-                    f"成功: {successful_patches}/{patch_count}, "
-                    f"失败: {len(failed_patches)}/{patch_count}.\n"
-                    f"失败详情:\n" + "\n".join(error_details)
-                )
-                print(f"❌ {summary}")
+                error_details = []
+                for p in failed_patches:
+                    patch = p["patch"]
+                    if "SEARCH" in patch:
+                        patch_desc = patch["SEARCH"]
+                    else:
+                        patch_desc = (
+                            "SEARCH_START:\n"
+                            + (patch.get("SEARCH_START", ""))
+                            + "\nSEARCH_END:\n"
+                            + (patch.get("SEARCH_END", ""))
+                        )
+                    error_details.append(f"  - 失败的补丁: \n{patch_desc}\n    错误: {p['error']}")
+                if successful_patches == 0:
+                    summary = (
+                        f"文件 {file_path} 修改失败（全部失败）。\n"
+                        f"失败: {len(failed_patches)}/{patch_count}.\n"
+                        f"失败详情:\n" + "\n".join(error_details)
+                    )
+                else:
+                    summary = (
+                        f"文件 {file_path} 修改部分成功。\n"
+                        f"成功: {successful_patches}/{patch_count}, "
+                        f"失败: {len(failed_patches)}/{patch_count}.\n"
+                        f"失败详情:\n" + "\n".join(error_details)
+                    )
+                PrettyOutput.print(summary, OutputType.ERROR)
                 return False, summary
 
-            print(f"✅ 文件 {file_path} 修改完成，应用了 {patch_count} 个补丁")
             return True, modified_content
 
         except Exception as e:
-            print(f"❌ 文件修改失败: {str(e)}")
+            PrettyOutput.print(f"文件修改失败: {str(e)}", OutputType.ERROR)
             return False, f"文件修改失败: {str(e)}"

jarvis/jarvis_agent/event_bus.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""
+事件总线（EventBus）
+
+目标（阶段一，最小变更）：
+- 提供简单可靠的发布/订阅机制
+- 回调异常隔离，避免影响主流程
+- 不引入额外依赖，便于在 Agent 中渐进集成
+"""
+from collections import defaultdict
+from typing import Callable, DefaultDict, List, Any
+
+
+
+class EventBus:
+    """
+    简单的同步事件总线。
+    - subscribe(event, callback): 订阅事件
+    - emit(event, **kwargs): 广播事件
+    - unsubscribe(event, callback): 取消订阅
+    """
+
+    def __init__(self) -> None:
+        self._listeners: DefaultDict[str, List[Callable[..., None]]] = defaultdict(list)
+
+    def subscribe(self, event: str, callback: Callable[..., None]) -> None:
+        if not callable(callback):
+            raise TypeError("callback must be callable")
+        self._listeners[event].append(callback)
+
+    def unsubscribe(self, event: str, callback: Callable[..., None]) -> None:
+        if event not in self._listeners:
+            return
+        try:
+            self._listeners[event].remove(callback)
+        except ValueError:
+            pass
+
+    def emit(self, event: str, **payload: Any) -> None:
+        """
+        广播事件。回调中的异常将被捕获并忽略，以保证主流程稳定。
+        """
+        for cb in list(self._listeners.get(event, [])):
+            try:
+                cb(**payload)
+            except Exception:
+                # 避免回调异常中断主流程
+                continue