aacf 0.8.0__py3-none-any.whl

aacf/__init__.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: GPL-3.0
+# Copyright (C) 2026 AACF Contributors
+#
+# AACF — Agentic AI Compiler Framework / 智能体编译器框架
+#
+# AI workflow pre-compilation and highly controllable scheduling execution engine.
+# AI 工作流预编译与高度可控的调度执行引擎。
+#
+# Exports / 导出:
+#     AACF: Application registry with @app.node() decorator / 应用注册表与节点装饰器
+#     LLMConfig: LLM call configuration / 大模型调用配置
+#     NodeStatus: Node execution status enum / 节点执行状态枚举
+#     AtomicNodeConfig: Atomic node execution configuration / 原子节点执行配置
+#     ExecutionResult: Rust-style execution result / Rust 风格的执行结果
+#     AACFError: Base error class / 基础错误类
+#     CircularDependencyError: Circular dependency error / 循环依赖错误
+#     NodeExecutionError: Node execution error / 节点执行错误
+#     PipelineError: Pipeline-level error / 管道级错误
+#     DAGCache: Incremental cache for DAG execution / DAG 执行增量缓存
+#     DAGVisualizer: Interactive HTML visualization / 交互式 HTML 可视化
+
+from aacf.core import AACF, LLMConfig
+from aacf.compiler import (
+    AtomicNodeConfig, NodeStatus,
+    ExecutionResult,
+    AACFError, CircularDependencyError, NodeExecutionError, PipelineError,
+    DAGCache,
+)
+
+try:
+    from aacf.visualize import DAGVisualizer
+except ImportError:
+    # pyvis not installed / pyvis 未安装
+    DAGVisualizer = None  # type: ignore
+
+__all__ = [
+    "AACF", "LLMConfig",
+    "NodeStatus", "AtomicNodeConfig",
+    "ExecutionResult",
+    "AACFError", "CircularDependencyError", "NodeExecutionError", "PipelineError",
+    "DAGCache", "DAGVisualizer",
+]

aacf/_messages.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: GPL-3.0
+# Copyright (C) 2026 AACF Contributors
+"""
+AACF Messages — Bilingual prompt templates and docstring formats / 双语提示词模板与文档格式
+
+This module centralizes all user-facing text templates for internationalization.
+本模块集中管理所有面向用户的文本模板，用于国际化支持。
+
+Currently supports: Chinese (zh) and English (en)
+当前支持：中文 (zh) 和英文 (en)
+
+Sections / 模块结构:
+    PROMPT_TEMPLATES:   Templates for @app.node() prompt construction / 节点 prompt 构建模板
+    DOCSTRING_TEMPLATES: Templates for docstring injection / Docstring 注入模板
+    CLI_MESSAGES:        Templates for CLI output messages / CLI 输出消息模板
+    get_template():      Helper function to retrieve templates by lang/category/key / 模板获取辅助函数
+"""
+
+# ────────────────────────────────────────────────────────────
+# Prompt Templates for @app.node() / @app.node() 提示词模板
+# ────────────────────────────────────────────────────────────
+
+PROMPT_TEMPLATES = {
+    "zh": {
+        "role": "你是{who}，你在{where}，你是一个{what}。\n",
+        "intent": "操作的意图原因是：{why}。\n",
+        "how": "你有以下操作选项：{how}\n",
+        "routing_header": "\n【重要：智能路由分发模式】\n",
+        "routing_modules": "你有权调用的下级专业子模块/节点有：{modules}\n",
+        "routing_instruction": "请深入分析用户的意图，自主判断应该去调用上述哪个子节点来完成任务。\n",
+        "routing_format": '你只需要输出一个纯 JSON 对象，格式为：\n',
+        "routing_example": '{"target_node": "节点名称", "reason": "调用原因", "inputs": {"参数名": "参数值"}}\n',
+        "routing_fallback": "如果你认为不需要调用任何子模块，请直接完成用户的需求。\n\n",
+        "output_request": "请根据输入内容，按照输出要求生成内容。\n",
+        "output_requirement": "输出要求：{out}\n",
+    },
+    "en": {
+        "role": "You are {who}, working in {where}, and your role is {what}.\n",
+        "intent": "The intent behind this operation is: {why}.\n",
+        "how": "You have the following operational options: {how}\n",
+        "routing_header": "\n[IMPORTANT: Intelligent Routing Mode]\n",
+        "routing_modules": "You have access to the following specialized sub-modules/nodes: {modules}\n",
+        "routing_instruction": "Please analyze the user's intent deeply and autonomously determine which sub-node to invoke.\n",
+        "routing_format": 'Output only a pure JSON object in this format:\n',
+        "routing_example": '{"target_node": "node_name", "reason": "reason_for_call", "inputs": {"param_name": "param_value"}}\n',
+        "routing_fallback": "If you determine no sub-module is needed, please fulfill the user's request directly.\n\n",
+        "output_request": "Please generate content based on the input according to the output requirements.\n",
+        "output_requirement": "Output requirements: {out}\n",
+    },
+}
+
+
+# ────────────────────────────────────────────────────────────
+# Docstring Injection Templates / Docstring 注入模板
+# ────────────────────────────────────────────────────────────
+
+DOCSTRING_TEMPLATES = {
+    "zh": {
+        "header": '🤖 【AACF 智能节点】: {who}\n',
+        "task": ' 核心任务: {what}\n',
+        "env": '📍 执行环境: {where}\n',
+    },
+    "en": {
+        "header": '🤖 [AACF Smart Node]: {who}\n',
+        "task": '🎯 Core Task: {what}\n',
+        "env": '📍 Environment: {where}\n',
+    },
+}
+
+
+# ────────────────────────────────────────────────────────────
+# CLI Messages / CLI 输出消息
+# ────────────────────────────────────────────────────────────
+
+CLI_MESSAGES = {
+    "zh": {
+        "init_start": "正在初始化 AACF 项目：",
+        "init_creating": "正在创建项目结构...",
+        "init_done": "✔ 项目结构已创建。",
+        "init_venv": "✔ 虚拟环境已初始化。",
+        "init_next": "下一步：",
+        "run_start": "▶ 正在运行 AACF 脚本：",
+        "run_error": "✖ 脚本退出，错误码：",
+        "sync_scanning": "▶ 正在扫描 @app.node：",
+        "sync_injecting": "正在注入 docstring...",
+        "sync_success": "✔ 成功为 {count} 个文件注入 docstring。",
+        "sync_hint": "你的 IDE（如 Pylance）现在将显示完整的 docstring 和类型提示。",
+        "sync_none": "ℹ 未找到需要同步的 @app.node 函数。",
+        "doc_start": "▶ 正在启动 AACF 文档服务器：",
+        "doc_serving": "服务地址：http://localhost:{port}",
+        "doc_stop": "按 Ctrl+C 停止。",
+        "doc_missing": "✖ pdoc 未安装。请运行 `pip install pdoc`。",
+        "doc_stopped": "✔ 文档服务器已停止。",
+        "doc_error": "✖ 启动文档服务器时出错：",
+        "watch_start": "▶ 正在监听文件变化：",
+        "watch_stop": "按 Ctrl+C 停止。",
+        "watch_changes": "检测到 {count} 个文件变化，正在同步...",
+        "watch_injected": "✔ 已为 {count} 个文件注入 docstring。",
+        "watch_noop": "无需更新 @app.node。",
+        "watch_stopped": "✔ 监听器已停止。",
+    },
+    "en": {
+        "init_start": "Initializing AACF Project: ",
+        "init_creating": "Creating project structure...",
+        "init_done": "✔ Project structure created.",
+        "init_venv": "✔ Virtual environment initialized.",
+        "init_next": "Next steps:",
+        "run_start": "▶ Running AACF Script: ",
+        "run_error": "✖ Script exited with error code: ",
+        "sync_scanning": "▶ Scanning for @app.node in: ",
+        "sync_injecting": "Injecting docstrings...",
+        "sync_success": "✔ Successfully injected docstrings for {count} files.",
+        "sync_hint": "Your IDE (e.g., Pylance) will now show perfect docstrings and type hints.",
+        "sync_none": " No @app.node functions found to sync.",
+        "doc_start": "▶ Starting AACF Doc Server for: ",
+        "doc_serving": "Serving on http://localhost:{port}",
+        "doc_stop": "Press Ctrl+C to stop.",
+        "doc_missing": "✖ pdoc is not installed. Please run `pip install pdoc`.",
+        "doc_stopped": "✔ Doc server stopped.",
+        "doc_error": "✖ Error starting doc server: ",
+        "watch_start": "▶ Watching for changes in: ",
+        "watch_stop": "Press Ctrl+C to stop.",
+        "watch_changes": "Changes detected in {count} file(s). Syncing...",
+        "watch_injected": "✔ Injected docstrings for {count} file(s).",
+        "watch_noop": "No @app.node updates required.",
+        "watch_stopped": "✔ Watcher stopped.",
+    },
+}
+
+
+# ────────────────────────────────────────────────────────────
+# Helper Functions / 辅助函数
+# ────────────────────────────────────────────────────────────
+
+def get_template(lang: str, category: str, key: str) -> str:
+    """
+    Get a template string by language, category, and key.
+
+    Args:
+        lang: Language code ("zh" or "en")
+        category: Template category ("prompt", "docstring", "cli")
+        key: Template key within the category
+
+    Returns:
+        Template string, falling back to Chinese if language not found
+    """
+    templates = {
+        "prompt": PROMPT_TEMPLATES,
+        "docstring": DOCSTRING_TEMPLATES,
+        "cli": CLI_MESSAGES,
+    }
+
+    category_dict = templates.get(category, {})
+    lang_dict = category_dict.get(lang, category_dict.get("zh", {}))
+    return lang_dict.get(key, "")

aacf/cli.py

@@ -0,0 +1,408 @@
+# SPDX-License-Identifier: GPL-3.0
+# Copyright (C) 2026 AACF Contributors
+"""
+AACF CLI — 命令行工具 / Command Line Interface
+
+提供 aacf init / run / sync / watch / doc 等 CLI 子命令。
+Provides CLI subcommands: init / run / sync / watch / doc.
+"""
+import ast
+import importlib.util
+import inspect
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+if sys.stdout.encoding and sys.stdout.encoding.lower() != "utf-8":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except AttributeError:
+        pass
+if sys.stderr.encoding and sys.stderr.encoding.lower() != "utf-8":
+    try:
+        sys.stderr.reconfigure(encoding="utf-8")
+    except AttributeError:
+        pass
+
+app = typer.Typer(
+    name="aacf",
+    help="AACF: Agentic AI Compiler Framework CLI / 智能体编译器框架命令行工具",
+    add_completion=False,
+)
+console = Console()
+
+
+# ────────────────────────────────────────────
+# Docstring 注入工具（供 sync / watch 使用）/ Docstring injection tool (for sync/watch)
+# ────────────────────────────────────────────
+
+def inject_docstrings_for_file(filepath: str) -> bool:
+    """
+    通过反射读取 Python 文件中的 @app.node 节点，并将 Docstring 注入到源码中。
+    Read Python file via reflection to find @app.node nodes and inject docstrings into source.
+
+    供 ``aacf sync`` 和 ``aacf watch`` 命令调用。
+    Called by ``aacf sync`` and ``aacf watch`` commands.
+
+    Args:
+        filepath: 目标 Python 文件路径 / Target Python file path
+
+    Returns:
+        True 如果成功注入 / True if injection succeeded, False otherwise
+    """
+    def _inject_docstrings_to_py(filepath, nodes):
+        """
+        将 docstring 注入到单个 Python 文件中 / Inject docstrings into a single Python file.
+
+        Args:
+            filepath: 目标文件路径 / Target file path
+            nodes: (函数对象, 元数据字典, 签名) 的列表 / List of (func, meta_dict, signature) tuples
+
+        Returns:
+            True 如果实际修改了文件 / True if the file was actually modified
+        """
+        try:
+            with open(filepath, 'r', encoding='utf-8') as f:
+                source_lines = f.readlines()
+            tree = ast.parse(''.join(source_lines))
+            docstring_ranges = {}
+            for node in ast.walk(tree):
+                if isinstance(node, ast.FunctionDef):
+                    doc = ast.get_docstring(node)
+                    if doc and 'AACF' in doc:
+                        expr_node = node.body[0]
+                        docstring_ranges[node.name] = (expr_node.lineno, expr_node.end_lineno)
+        except Exception:
+            return False
+
+        funcs_to_inject = []
+        for func, meta, sig in nodes:
+            name = func.__name__
+            # 如果源码中已有 AACF docstring，跳过（幂等性）
+            # If source already has AACF docstring, skip (idempotent)
+            if name in docstring_ranges:
+                continue
+            try:
+                _, start_lineno = inspect.getsourcelines(func)
+            except Exception:
+                continue
+            funcs_to_inject.append((start_lineno, func, meta))
+
+        if not funcs_to_inject:
+            return False
+
+        funcs_to_inject.sort(key=lambda x: x[0], reverse=True)
+
+        for start_lineno, func, meta in funcs_to_inject:
+            name = func.__name__
+            if name in docstring_ranges:
+                start, end = docstring_ranges[name]
+                del source_lines[start - 1:end]
+
+            idx = start_lineno - 1
+            paren_count = 0
+            in_def = False
+            colon_idx = idx
+            def_indent = 0
+            for i in range(idx, len(source_lines)):
+                line = source_lines[i]
+                if not in_def and line.lstrip().startswith('def '):
+                    in_def = True
+                    def_indent = len(line) - len(line.lstrip())
+                paren_count += line.count('(') - line.count(')')
+                if in_def and paren_count == 0 and ':' in line:
+                    colon_idx = i
+                    break
+
+            indent_str = " " * (def_indent + 4)
+            who = meta.get("who", "未命名智能体 / AI Agent")
+            what = meta.get("what", "未定义任务 / Task undefined")
+            where = meta.get("where", "未知环境 / Environment unknown")
+
+            docstring_lines = [
+                f'{indent_str}"""\n',
+                f'{indent_str}🤖 【AACF 智能节点 / Smart Node】: {who}\n',
+                f'{indent_str}🎯 核心任务 / Core Task: {what}\n',
+                f'{indent_str}📍 执行环境 / Environment: {where}\n',
+                f'{indent_str}"""\n',
+            ]
+
+            line = source_lines[colon_idx]
+            colon_pos = line.find(':', line.rfind(')'))
+            if colon_pos != -1:
+                before_colon = line[:colon_pos + 1]
+                after_colon = line[colon_pos + 1:].strip()
+                source_lines[colon_idx] = before_colon + '\n'
+                if after_colon:
+                    docstring_lines.append(f'{indent_str}{after_colon}\n')
+
+            source_lines = source_lines[:colon_idx + 1] + docstring_lines + source_lines[colon_idx + 1:]
+
+        try:
+            with open(filepath, 'w', encoding='utf-8') as f:
+                f.writelines(source_lines)
+            return True
+        except Exception:
+            return False
+
+    target_path = Path(filepath).resolve()
+    if not target_path.exists() or target_path.suffix != '.py':
+        return False
+
+    module_name = target_path.stem
+    parent_dir = str(target_path.parent)
+    sys.path.insert(0, parent_dir)
+
+    try:
+        spec = importlib.util.spec_from_file_location(module_name, str(target_path))
+        if spec is None or spec.loader is None:
+            return False
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+    except Exception as e:
+        print(f"Failed to import {filepath}: {e}")
+        sys.path.pop(0)
+        return False
+
+    sys.path.pop(0)
+
+    has_nodes = False
+    nodes = []
+    for name, obj in inspect.getmembers(module):
+        if inspect.isfunction(obj) and hasattr(obj, '__aacf_meta__'):
+            # 仅处理定义在当前文件中的函数，跳过从其他文件导入的函数
+            # Only process functions defined in the current file, skip imported ones
+            # 使用 inspect.unwrap 追溯 @wraps 包装链，获取原始函数的源文件
+            # Use inspect.unwrap to follow @wraps chain to get original function's source file
+            try:
+                original_func = inspect.unwrap(obj)
+                func_file = inspect.getsourcefile(original_func)
+                if func_file and Path(func_file).resolve() != target_path:
+                    continue
+            except (OSError, TypeError):
+                continue
+            has_nodes = True
+            meta = obj.__aacf_meta__
+            sig = inspect.signature(obj)
+            nodes.append((obj, meta, sig))
+
+    if not has_nodes:
+        return False
+
+    return _inject_docstrings_to_py(filepath, nodes) or False
+
+
+# ────────────────────────────────────────────
+# CLI Commands / 命令行命令
+# ─────────────────────────────────────────────
+
+@app.command()
+def init(
+    project_name: str = typer.Argument(..., help="The name of your new AACF project / 新项目名称"),
+):
+    """Initialize a new AACF project with the recommended directory structure.
+    初始化一个新的 AACF 项目，包含推荐的目录结构。"""
+    console.print(Panel.fit(
+        f"[bold blue]Initializing AACF Project / 初始化项目:[/] [green]{project_name}[/]",
+        border_style="blue",
+    ))
+    project_dir = Path.cwd() / project_name
+    if project_dir.exists():
+        console.print(f"[bold red]✖[/] Directory '{project_name}' already exists / 目录 '{project_name}' 已存在。")
+        raise typer.Exit(code=1)
+
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}"), transient=True) as progress:
+        progress.add_task(description="Creating project structure / 创建项目结构...", total=None)
+        # 创建项目目录 / Create project directory
+        project_dir.mkdir(parents=True)
+        (project_dir / "src").mkdir()
+        # 创建 main.py 模板 / Create main.py template
+        main_py = project_dir / "main.py"
+        main_py.write_text(
+            'from aacf import AACF, LLMConfig\n\n'
+            'app = AACF(__name__, config=LLMConfig(\n'
+            '    model="qwen2.5-7b-instruct",\n'
+            '    url="http://127.0.0.1:8080/v1/chat/completions",\n'
+            '))\n\n\n'
+            '@app.node("hello").who("助手").what("打招呼").build()\n'
+            'def hello(name: str):\n'
+            '    pass\n\n\n'
+            'if __name__ == "__main__":\n'
+            '    print(hello(name="World"))\n',
+            encoding="utf-8",
+        )
+        # 创建 __init__.py / Create __init__.py
+        (project_dir / "src" / "__init__.py").write_text("", encoding="utf-8")
+        # 初始化虚拟环境 / Initialize virtual environment
+        try:
+            subprocess.check_call(
+                [sys.executable, "-m", "venv", ".venv"],
+                cwd=str(project_dir),
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        except (subprocess.CalledProcessError, Exception):
+            pass  # 虚拟环境创建失败不影响项目初始化 / venv failure is non-fatal
+
+    console.print("[bold green]✔[/] Project structure created / 项目结构已创建。")
+    console.print("[bold green]✔[/] Virtual environment initialized / 虚拟环境已初始化。")
+    console.print(f"\n[bold]Next steps / 下一步:[/]\n  cd {project_name}\n  aacf run main.py")
+
+
+@app.command()
+def run(
+    script: str = typer.Argument(..., help="The Python script to run (e.g., main.py) / 要运行的 Python 脚本"),
+):
+    """Execute an AACF python script with enhanced AI logging.
+    执行 AACF Python 脚本，增强 AI 日志输出。"""
+    console.print(f"[bold magenta]▶ Running AACF Script / 运行脚本:[/] {script}")
+    try:
+        subprocess.check_call([sys.executable, script])
+    except subprocess.CalledProcessError as e:
+        console.print(f"[bold red]✖ Script exited with error code / 脚本退出错误码 {e.returncode}[/]")
+        raise typer.Exit(code=e.returncode)
+
+
+@app.command()
+def sync(
+    path: str = typer.Argument(".", help="Directory or file to scan for @app.node functions / 扫描目录或文件"),
+):
+    """Scan Python files and inject docstrings to source code for perfect IDE support.
+    扫描 Python 文件并向源码注入 docstring，提供完美的 IDE 支持。"""
+    console.print(f"[bold magenta]▶ Scanning for @app.node in / 扫描:[/] {path}")
+    target_path = Path(path).resolve()
+
+    files_to_scan = []
+    if target_path.is_file():
+        if target_path.suffix == '.py':
+            files_to_scan.append(target_path)
+    else:
+        files_to_scan = list(target_path.rglob("*.py"))
+
+    count = 0
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}"), transient=True) as progress:
+        task = progress.add_task(description="Injecting docstrings / 注入文档...", total=len(files_to_scan))
+        for py_file in files_to_scan:
+            if inject_docstrings_for_file(str(py_file)):
+                count += 1
+            progress.advance(task)
+
+    if count > 0:
+        console.print(f"[bold green]✔[/] Successfully injected docstrings for [bold]{count}[/] files / 成功注入 {count} 个文件。")
+        console.print("[dim]Your IDE (e.g., Pylance) will now show perfect docstrings and type hints. / IDE 现在将显示完整的文档和类型提示。[/]")
+    else:
+        console.print("[bold yellow]ℹ[/] No @app.node functions found to sync / 未找到需要同步的 @app.node 函数。")
+
+
+@app.command()
+def doc(
+    module: str = typer.Argument("aacf", help="The Python module or directory to document / 要生成文档的模块或目录"),
+    port: int = typer.Option(8080, "--port", "-p", help="Port to serve the documentation on / 文档服务端口"),
+):
+    """Zero-config API documentation server. (Inspired by Rust's cargo doc)
+    零配置 API 文档服务器。（灵感来自 Rust 的 cargo doc）"""
+    console.print(f"[bold magenta]▶ Starting AACF Doc Server for / 启动文档服务器:[/] {module}")
+    console.print(f"[dim]Serving on / 服务地址: http://127.0.0.1:{port}[/]")
+    console.print("[dim]Press Ctrl+C to stop / 按 Ctrl+C 停止。[/]")
+
+    try:
+        import pdoc  # type: ignore
+    except ImportError:
+        console.print("[bold red]✖ pdoc is not installed. Please run `pip install pdoc`. / pdoc 未安装，请运行 `pip install pdoc`。[/]")
+        raise typer.Exit(code=1)
+
+    try:
+        import webbrowser
+        import threading
+        from pdoc.web import DocServer, open_browser
+
+        def launch():
+            time.sleep(1)
+            open_browser(f"http://127.0.0.1:{port}")
+
+        threading.Thread(target=launch, daemon=True).start()
+        with DocServer(("127.0.0.1", port), [module]) as httpd:
+            console.print(f"[bold green]✔[/] Doc server running / 文档服务器运行中: http://127.0.0.1:{port}")
+            httpd.serve_forever()
+    except KeyboardInterrupt:
+        console.print("\n[bold green]✔[/] Doc server stopped / 文档服务器已停止。")
+    except Exception as e:
+        console.print(f"[bold red]✖ Error starting doc server / 启动文档服务器出错:[/] {e}")
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def watch(
+    path: str = typer.Argument(".", help="Directory to watch for changes / 监听变化的目录"),
+    interval: float = typer.Option(1.0, "--interval", "-i", help="Polling interval in seconds / 轮询间隔（秒）"),
+):
+    """Watch Python files for changes and automatically inject docstrings.
+    监听 Python 文件变化并自动注入 docstring。"""
+    console.print(f"[bold magenta]▶ Watching for changes in / 监听:[/] {path}")
+    console.print("[dim]Press Ctrl+C to stop / 按 Ctrl+C 停止。[/]")
+
+    target_path = Path(path).resolve()
+    last_mtimes = {}
+
+    def get_py_files():
+        if target_path.is_file():
+            return [target_path] if target_path.suffix == '.py' else []
+        return list(target_path.rglob("*.py"))
+
+    for py_file in get_py_files():
+        if "typings" in py_file.parts:
+            continue
+        try:
+            last_mtimes[py_file] = os.path.getmtime(py_file)
+        except OSError:
+            pass
+
+    try:
+        while True:
+            time.sleep(interval)
+            changed_files = []
+
+            for py_file in get_py_files():
+                if "typings" in py_file.parts:
+                    continue
+                try:
+                    mtime = os.path.getmtime(py_file)
+                    if py_file not in last_mtimes or mtime > last_mtimes[py_file]:
+                        changed_files.append(py_file)
+                        last_mtimes[py_file] = mtime
+                except OSError:
+                    pass
+
+            if changed_files:
+                console.print(f"\n[bold cyan]Changes detected in {len(changed_files)} file(s). Syncing... / 检测到 {len(changed_files)} 个文件变化，正在同步...[/]")
+                count = 0
+                for py_file in changed_files:
+                    if inject_docstrings_for_file(str(py_file)):
+                        count += 1
+                if count > 0:
+                    console.print(f"[bold green]✔[/] Injected docstrings for [bold]{count}[/] file(s) / 已注入 {count} 个文件。")
+                    # 注入后更新 mtime，避免自身写入触发下一轮检测（防止死循环）
+                    # Update mtime after injection to prevent self-write from triggering next detection
+                    for py_file in changed_files:
+                        try:
+                            last_mtimes[py_file] = os.path.getmtime(py_file)
+                        except OSError:
+                            pass
+                else:
+                    console.print("[dim]No @app.node updates required / 无需更新 @app.node。[/]")
+
+    except KeyboardInterrupt:
+        console.print("\n[bold green]✔[/] Watcher stopped / 监听器已停止。")
+
+
+if __name__ == "__main__":
+    app()