pyquipu-cli 0.1.0__tar.gz

pyquipu_cli-0.1.0/.gitignore

@@ -0,0 +1,75 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# tmpfiles
+o.md
+a.md
+a
+o
+t
+tmpfile
+
+# Scaffoldings
+context_builder.yml
+context_builder.py
+current_prompts
+
+# Distribution / Packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environments
+venv/
+env/
+.env
+.venv/
+
+# Testing
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Project Specific
+*.log
+axon.log
+# Ignore test vaults or scratchpads if created in root
+vault/
+temp/
+scratch/
+# --- Quipu Dev Infra ---
+.envs/
+.uv/
+sandbox/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.coverage
+htmlcov/

pyquipu_cli-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: pyquipu-cli
+Version: 0.1.0
+Summary: The command-line interface for Quipu.
+Author-email: doucx <doucxldh@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: pyquipu-application~=0.1.0
+Requires-Dist: pyquipu-bus~=0.1.0
+Requires-Dist: pyquipu-common~=0.1.0
+Requires-Dist: pyquipu-engine~=0.1.0
+Requires-Dist: pyquipu-interfaces~=0.1.0
+Requires-Dist: pyquipu-runtime~=0.1.0
+Requires-Dist: textual>=0.58.0
+Requires-Dist: typer>=0.9.0

pyquipu_cli-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyquipu-cli"
+version = "0.1.0"
+authors = [{ name="doucx", email="doucxldh@gmail.com" }]
+description = "The command-line interface for Quipu."
+requires-python = ">=3.10"
+license = "Apache-2.0"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pyquipu-interfaces ~= 0.1.0",
+    "pyquipu-engine ~= 0.1.0",
+    "pyquipu-runtime ~= 0.1.0",
+    "pyquipu-common ~= 0.1.0",
+    "pyquipu-application ~= 0.1.0",
+    "pyquipu-bus ~= 0.1.0",
+    "typer >= 0.9.0",
+    "textual >= 0.58.0",
+]
+
+[tool.uv.sources]
+pyquipu-interfaces = { workspace = true }
+pyquipu-engine = { workspace = true }
+pyquipu-runtime = { workspace = true }
+pyquipu-common = { workspace = true }
+pyquipu-application = { workspace = true }
+pyquipu-bus = { workspace = true }
+
+[project.scripts]
+quipu = "quipu.cli.main:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quipu"]
+# Hatch 默认会自动包含 package_data，如果需要显式包含：
+# include = ["/src/quipu/cli/*.css"]

pyquipu_cli-0.1.0/src/quipu/__init__.py

@@ -0,0 +1,3 @@
+# This allows this package to coexist with other distribution packages
+# that contribute to the 'quipu' namespace.
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

pyquipu_cli-0.1.0/src/quipu/cli/commands/axon.py

@@ -0,0 +1,103 @@
+import inspect
+import logging
+import sys
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from quipu.bus import bus
+
+from ..config import DEFAULT_ENTRY_FILE, DEFAULT_WORK_DIR
+from ..logger_config import setup_logging
+from ..ui_utils import confirmation_handler_for_executor
+
+logger = logging.getLogger(__name__)
+
+
+def register(app: typer.Typer):
+    @app.command(name="axon", help="无状态执行 Plan 文件，绕过 Quipu 引擎。")
+    def axon_command(
+        ctx: typer.Context,
+        file: Annotated[
+            Optional[Path], typer.Argument(help="包含 Markdown 指令的文件路径。", resolve_path=True)
+        ] = None,
+        work_dir: Annotated[
+            Path,
+            typer.Option(
+                "--work-dir", "-w", help="操作执行的根目录（工作区）", file_okay=False, dir_okay=True, resolve_path=True
+            ),
+        ] = DEFAULT_WORK_DIR,
+        parser_name: Annotated[str, typer.Option("--parser", "-p", help="选择解析器语法。默认为 'auto'。")] = "auto",
+        yolo: Annotated[
+            bool, typer.Option("--yolo", "-y", help="跳过所有确认步骤，直接执行 (You Only Look Once)。")
+        ] = False,
+        list_acts: Annotated[bool, typer.Option("--list-acts", "-l", help="列出所有可用的操作指令及其说明。")] = False,
+    ):
+        setup_logging()
+
+        # --list-acts 是一个独立的查询操作，应尽早处理并退出
+        if list_acts:
+            from quipu.application.controller import get_available_acts
+
+            bus.info("axon.listActs.ui.header")
+            acts = get_available_acts(work_dir)
+            for name in sorted(acts.keys()):
+                doc = acts[name]
+                clean_doc = inspect.cleandoc(doc) if doc else "暂无说明"
+                indented_doc = "\n".join(f"   {line}" for line in clean_doc.splitlines())
+                item_header = bus.get("axon.listActs.ui.actItem", name=name)
+                bus.data(f"{item_header}\n{indented_doc}\n")
+            ctx.exit(0)
+
+        logger.debug(f"axon started with file={file}, work_dir={work_dir}, parser={parser_name}, yolo={yolo}")
+
+        # --- 1. 输入处理 (CLI 层职责) ---
+        content = ""
+        source_desc = ""
+        if file:
+            if not file.exists():
+                bus.error("common.error.fileNotFound", path=file)
+                ctx.exit(1)
+            content = file.read_text(encoding="utf-8")
+            source_desc = f"文件 ({file.name})"
+        elif not sys.stdin.isatty():
+            try:
+                stdin_content = sys.stdin.read()
+                if stdin_content:
+                    content = stdin_content
+                    source_desc = "STDIN (管道流)"
+            except Exception:
+                pass
+
+        if not content and not file and DEFAULT_ENTRY_FILE.exists():
+            content = DEFAULT_ENTRY_FILE.read_text(encoding="utf-8")
+            source_desc = f"默认文件 ({DEFAULT_ENTRY_FILE.name})"
+
+        if not content.strip():
+            bus.warning("axon.warning.noInput")
+            ctx.exit(0)
+
+        # --- 2. 委托给应用层服务 (核心重构) ---
+        from quipu.application.controller import run_stateless_plan
+
+        logger.info(f"Axon 启动 | 源: {source_desc} | 工作区: {work_dir}")
+
+        result = run_stateless_plan(
+            content=content,
+            work_dir=work_dir,
+            parser_name=parser_name,
+            yolo=yolo,
+            confirmation_handler=confirmation_handler_for_executor,
+        )
+
+        # --- 3. 渲染结果 (CLI 层职责) ---
+        if result.message:
+            kwargs = result.msg_kwargs or {}
+            if result.exit_code == 2:
+                bus.warning(result.message, **kwargs)
+            elif not result.success:
+                bus.error(result.message, **kwargs)
+            else:
+                bus.success(result.message, **kwargs)
+
+        ctx.exit(result.exit_code)

pyquipu_cli-0.1.0/src/quipu/cli/commands/cache.py

@@ -0,0 +1,113 @@
+import logging
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from quipu.bus import bus
+
+from ..config import DEFAULT_WORK_DIR
+from ..logger_config import setup_logging
+from .helpers import engine_context
+
+logger = logging.getLogger(__name__)
+
+cache_app = typer.Typer(name="cache", help="管理本地 SQLite 缓存。")
+
+
+@cache_app.command("sync")
+def cache_sync(
+    ctx: typer.Context,
+    work_dir: Annotated[
+        Path,
+        typer.Option(
+            "--work-dir", "-w", help="操作执行的根目录（工作区）", file_okay=False, dir_okay=True, resolve_path=True
+        ),
+    ] = DEFAULT_WORK_DIR,
+):
+    bus.info("cache.sync.info.hydrating")
+    try:
+        with engine_context(work_dir):
+            pass
+        bus.success("cache.sync.success")
+    except Exception as e:
+        logger.error("数据同步失败", exc_info=True)
+        bus.error("cache.sync.error", error=str(e))
+        ctx.exit(1)
+
+
+@cache_app.command("rebuild")
+def cache_rebuild(
+    ctx: typer.Context,
+    force: Annotated[bool, typer.Option("--force", "-f", help="强制执行，跳过确认提示。")] = False,
+    work_dir: Annotated[
+        Path,
+        typer.Option(
+            "--work-dir", "-w", help="操作执行的根目录（工作区）", file_okay=False, dir_okay=True, resolve_path=True
+        ),
+    ] = DEFAULT_WORK_DIR,
+):
+    setup_logging()
+    db_path = work_dir.resolve() / ".quipu" / "history.sqlite"
+    if not db_path.exists():
+        bus.warning("cache.rebuild.info.dbNotFound")
+        cache_sync(ctx, work_dir)
+
+
+@cache_app.command("prune-refs")
+def cache_prune_refs(
+    ctx: typer.Context,
+    work_dir: Annotated[
+        Path,
+        typer.Option(
+            "--work-dir", "-w", help="操作执行的根目录（工作区）", file_okay=False, dir_okay=True, resolve_path=True
+        ),
+    ] = DEFAULT_WORK_DIR,
+):
+    setup_logging()
+
+    with engine_context(work_dir) as engine:
+        bus.info("cache.prune.info.scanning")
+
+        # 1. 获取所有本地 heads
+        local_heads = engine.git_db.get_all_ref_heads("refs/quipu/local/heads/")
+        if not local_heads:
+            bus.success("cache.prune.info.noRedundant")
+            return
+
+        head_commits = {h[0] for h in local_heads}
+
+        # 2. 批量获取这些 commit 的内容以解析 parent
+        commits_content = engine.git_db.batch_cat_file(list(head_commits))
+
+        parents_of_heads = set()
+        for c_hash, content in commits_content.items():
+            text = content.decode("utf-8", errors="ignore")
+            for line in text.splitlines():
+                if line.startswith("parent "):
+                    p_hash = line.split()[1]
+                    parents_of_heads.add(p_hash)
+                elif line == "":
+                    break
+
+        # 3. 计算交集：既是 Head 又是某个 Head 的 Parent -> 冗余
+        redundant_commits = head_commits.intersection(parents_of_heads)
+
+        if not redundant_commits:
+            bus.success("cache.prune.info.noRedundant")
+            return
+
+        # 4. 找出对应的 ref names 并删除
+        refs_to_delete = []
+        for c_hash, ref_name in local_heads:
+            if c_hash in redundant_commits:
+                refs_to_delete.append(ref_name)
+
+        bus.info("cache.prune.info.found", count=len(refs_to_delete), total=len(local_heads))
+
+        deleted_count = 0
+        for ref in refs_to_delete:
+            engine.git_db.delete_ref(ref)
+            deleted_count += 1
+
+        bus.success("cache.prune.success", count=deleted_count)
+        return

pyquipu_cli-0.1.0/src/quipu/cli/commands/cache.stitcher.yaml

@@ -0,0 +1,7 @@
+"cache_prune_refs": |-
+  清理 refs/quipu/local/heads/ 下的冗余引用。
+  只保留分支末端 (Leaves)，删除中间节点的引用。
+"cache_rebuild": |-
+  强制全量重建 SQLite 缓存。
+"cache_sync": |-
+  将 Git 历史增量同步到 SQLite 缓存。

pyquipu_cli-0.1.0/src/quipu/cli/commands/export.py

@@ -0,0 +1,209 @@
+import logging
+import re
+import shutil
+from pathlib import Path
+from typing import Annotated, Dict, List, Optional, Set
+
+import typer
+import yaml
+from quipu.bus import bus
+from quipu.engine.state_machine import Engine
+from quipu.interfaces.models import QuipuNode
+
+from ..config import DEFAULT_WORK_DIR
+from ..ui_utils import prompt_for_confirmation
+from .helpers import engine_context, filter_nodes, filter_reachable_nodes
+
+logger = logging.getLogger(__name__)
+
+
+def _sanitize_summary(summary: str) -> str:
+    if not summary:
+        return "no-summary"
+    sanitized = re.sub(r"[\\/:#\[\]|]", "_", summary)
+    sanitized = re.sub(r"[\s_]+", "_", sanitized)
+    return sanitized[:60]
+
+
+def _generate_filename(node: QuipuNode) -> str:
+    ts = node.timestamp.strftime("%y%m%d-%H%M")
+    short_hash = node.commit_hash[:7]
+    sanitized_summary = _sanitize_summary(node.summary)
+    return f"{ts}-{short_hash}-{sanitized_summary}.md"
+
+
+def _format_frontmatter(node: QuipuNode) -> str:
+    data = {
+        "commit_hash": node.commit_hash,
+        "output_tree": node.output_tree,
+        "input_tree": node.input_tree,
+        "timestamp": node.timestamp.isoformat(),
+        "node_type": node.node_type,
+    }
+    if node.owner_id:
+        data["owner_id"] = node.owner_id
+    yaml_str = yaml.dump(data, Dumper=yaml.SafeDumper, default_flow_style=False, sort_keys=False)
+    return f"---\n{yaml_str}---"
+
+
+def _generate_navbar(
+    current_node: QuipuNode,
+    exported_hashes_set: Set[str],
+    filename_map: Dict[str, str],
+    hidden_link_types: Set[str],
+) -> str:
+    nav_links = []
+
+    # 1. 总结节点 (↑)
+    if "summary" not in hidden_link_types:
+        ancestor = current_node.parent
+        while ancestor:
+            if ancestor.input_tree == ancestor.output_tree and ancestor.commit_hash in exported_hashes_set:
+                nav_links.append(f"> ↑ [总结节点]({filename_map[ancestor.commit_hash]})")
+                break
+            ancestor = ancestor.parent
+
+    # 2. 上一分支点 (↓)
+    if "branch" not in hidden_link_types:
+        ancestor = current_node.parent
+        found_branch_point = None
+        while ancestor:
+            if len(ancestor.children) > 1 and ancestor.commit_hash in exported_hashes_set:
+                found_branch_point = ancestor
+                break
+            ancestor = ancestor.parent
+        if (
+            found_branch_point
+            and current_node.parent
+            and found_branch_point.commit_hash != current_node.parent.commit_hash
+        ):
+            nav_links.append(f"> ↓ [上一分支点]({filename_map[found_branch_point.commit_hash]})")
+
+    # 3. 父节点 (←)
+    if "parent" not in hidden_link_types:
+        if current_node.parent and current_node.parent.commit_hash in exported_hashes_set:
+            nav_links.append(f"> ← [父节点]({filename_map[current_node.parent.commit_hash]})")
+
+    # 4. 子节点 (→)
+    if "child" not in hidden_link_types:
+        for child in current_node.children:
+            if child.commit_hash in exported_hashes_set:
+                nav_links.append(f"> → [子节点]({filename_map[child.commit_hash]})")
+
+    if not nav_links:
+        return ""
+
+    return "\n\n" + "> [!nav] 节点导航\n" + "\n".join(nav_links)
+
+
+def _generate_file_content(
+    node: QuipuNode,
+    engine: Engine,
+    no_frontmatter: bool,
+    no_nav: bool,
+    exported_hashes_set: Set[str],
+    filename_map: Dict[str, str],
+    hidden_link_types: Set[str],
+) -> str:
+    parts = []
+    if not no_frontmatter:
+        parts.append(_format_frontmatter(node))
+
+    public_content = engine.reader.get_node_content(node) or ""
+    parts.append("# content.md")
+    parts.append(public_content.strip())
+
+    private_content = engine.reader.get_private_data(node.commit_hash)
+    if private_content:
+        parts.append("# 开发者意图")
+        parts.append(private_content.strip())
+
+    content_str = "\n\n".join(parts)
+
+    if not no_nav:
+        navbar_str = _generate_navbar(node, exported_hashes_set, filename_map, hidden_link_types)
+        content_str += navbar_str
+
+    return content_str
+
+
+def register(app: typer.Typer):
+    @app.command(name="export", help="将历史图谱中的节点导出为 Markdown 文件。")
+    def export_command(
+        ctx: typer.Context,
+        work_dir: Annotated[
+            Path, typer.Option("--work-dir", "-w", help="工作区根目录", resolve_path=True)
+        ] = DEFAULT_WORK_DIR,
+        output_dir: Annotated[Path, typer.Option("--output-dir", "-o", help="导出目录", resolve_path=True)] = Path(
+            "./.quipu/export"
+        ),
+        limit: Annotated[Optional[int], typer.Option("--limit", "-n", help="限制最新节点数量")] = None,
+        since: Annotated[Optional[str], typer.Option("--since", help="起始时间戳 (YYYY-MM-DD HH:MM)")] = None,
+        until: Annotated[Optional[str], typer.Option("--until", help="截止时间戳 (YYYY-MM-DD HH:MM)")] = None,
+        zip_output: Annotated[bool, typer.Option("--zip", help="压缩导出目录")] = False,
+        no_nav: Annotated[bool, typer.Option("--no-nav", help="禁用导航栏")] = False,
+        no_frontmatter: Annotated[bool, typer.Option("--no-frontmatter", help="禁用 Frontmatter")] = False,
+        hide_link_type: Annotated[
+            Optional[List[str]],
+            typer.Option(
+                "--hide-link-type", help="禁用特定类型的导航链接 (可多次使用: summary, branch, parent, child)"
+            ),
+        ] = None,
+        reachable_only: Annotated[
+            bool, typer.Option("--reachable-only", help="仅导出与当前工作区状态直接相关的节点。")
+        ] = False,
+    ):
+        hidden_types = set(hide_link_type) if hide_link_type else set()
+
+        with engine_context(work_dir) as engine:
+            if not engine.history_graph:
+                bus.info("export.info.emptyHistory")
+                ctx.exit(0)
+
+            nodes_to_process = sorted(engine.history_graph.values(), key=lambda n: n.timestamp, reverse=True)
+
+            if reachable_only:
+                nodes_to_process = filter_reachable_nodes(engine, nodes_to_process)
+
+            try:
+                # filter_nodes returns preserving input order (reverse chrono),
+                # but export expects chronological order for file generation/processing
+                filtered = filter_nodes(nodes_to_process, limit, since, until)
+                nodes_to_export = list(reversed(filtered))
+            except typer.BadParameter as e:
+                bus.error("export.error.badParam", error=str(e))
+                ctx.exit(1)
+
+            if not nodes_to_export:
+                bus.info("export.info.noMatchingNodes")
+                ctx.exit(0)
+
+            if output_dir.exists() and any(output_dir.iterdir()):
+                prompt = bus.get("export.prompt.overwrite", path=output_dir)
+                if not prompt_for_confirmation(prompt, default=False):
+                    bus.warning("common.prompt.cancel")
+                    raise typer.Abort()
+                shutil.rmtree(output_dir)
+            output_dir.mkdir(parents=True, exist_ok=True)
+
+            bus.info("export.info.starting", count=len(nodes_to_export), path=output_dir)
+
+            # 预计算文件名和节点集合以供导航栏使用
+            filename_map = {node.commit_hash: _generate_filename(node) for node in nodes_to_export}
+            exported_hashes_set = {node.commit_hash for node in nodes_to_export}
+
+            with typer.progressbar(nodes_to_export, label="导出进度") as progress:
+                for node in progress:
+                    filename = filename_map[node.commit_hash]
+                    content = _generate_file_content(
+                        node, engine, no_frontmatter, no_nav, exported_hashes_set, filename_map, hidden_types
+                    )
+                    (output_dir / filename).write_text(content, encoding="utf-8")
+
+            if zip_output:
+                bus.info("export.info.zipping")
+                zip_path = shutil.make_archive(str(output_dir), "zip", output_dir)
+                shutil.rmtree(output_dir)
+                bus.success("export.success.zip", path=zip_path)
+            else:
+                bus.success("export.success.dir")

pyquipu_cli-0.1.0/src/quipu/cli/commands/export.stitcher.yaml

@@ -0,0 +1,10 @@
+"_format_frontmatter": |-
+  生成 YAML Frontmatter 字符串。
+"_generate_file_content": |-
+  构建单个 Markdown 文件的完整内容。
+"_generate_filename": |-
+  根据规范生成文件名。
+"_generate_navbar": |-
+  生成导航栏 Markdown 字符串。
+"_sanitize_summary": |-
+  净化摘要以用作安全的文件名部分。

pyquipu_cli-0.1.0/src/quipu/cli/commands/helpers.py

@@ -0,0 +1,86 @@
+import logging
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Generator, List, Optional
+
+import typer
+from quipu.application.factory import create_engine
+from quipu.bus import bus
+from quipu.engine.state_machine import Engine
+from quipu.interfaces.models import QuipuNode
+
+from ..logger_config import setup_logging
+
+logger = logging.getLogger(__name__)
+
+
+@contextmanager
+def engine_context(work_dir: Path) -> Generator[Engine, None, None]:
+    setup_logging()
+    engine = None
+    try:
+        engine = create_engine(work_dir)
+        yield engine
+    finally:
+        if engine:
+            engine.close()
+
+
+def _find_current_node(engine: Engine, graph: Dict[str, QuipuNode]) -> Optional[QuipuNode]:
+    current_hash = engine.git_db.get_tree_hash()
+    # 修复：直接从 graph 中通过 output_tree hash 查找
+    for node in graph.values():
+        if node.output_tree == current_hash:
+            return node
+
+    bus.warning("navigation.warning.workspaceDirty")
+    bus.info("navigation.info.saveHint")
+    return None
+
+
+def _execute_visit(ctx: typer.Context, engine: Engine, target_hash: str, msg_id: str, **kwargs):
+    bus.info(msg_id, **kwargs)
+    try:
+        engine.visit(target_hash)
+        bus.success("navigation.success.visit", short_hash=target_hash[:7])
+    except Exception as e:
+        logger.error(f"导航操作失败 (目标哈希: {target_hash[:12]})", exc_info=True)
+        bus.error("navigation.error.generic", error=str(e))
+        ctx.exit(1)
+
+
+def filter_nodes(
+    nodes: List[QuipuNode], limit: Optional[int], since: Optional[str], until: Optional[str]
+) -> List[QuipuNode]:
+    filtered = nodes
+    if since:
+        try:
+            since_dt = datetime.fromisoformat(since.replace(" ", "T"))
+            filtered = [n for n in filtered if n.timestamp >= since_dt]
+        except ValueError:
+            raise typer.BadParameter("无效的 'since' 时间戳格式。请使用 'YYYY-MM-DD HH:MM'。")
+    if until:
+        try:
+            until_dt = datetime.fromisoformat(until.replace(" ", "T"))
+            filtered = [n for n in filtered if n.timestamp <= until_dt]
+        except ValueError:
+            raise typer.BadParameter("无效的 'until' 时间戳格式。请使用 'YYYY-MM-DD HH:MM'。")
+    if limit is not None and limit > 0:
+        filtered = filtered[:limit]
+    return filtered
+
+
+def filter_reachable_nodes(engine: Engine, nodes: List[QuipuNode]) -> List[QuipuNode]:
+    current_node = _find_current_node(engine, engine.history_graph)
+    if not current_node:
+        # 如果工作区是脏的，无法确定起点，返回所有节点
+        return nodes
+
+    current_hash = current_node.output_tree
+    ancestors = engine.reader.get_ancestor_output_trees(current_hash)
+    descendants = engine.reader.get_descendant_output_trees(current_hash)
+    reachable_set = ancestors.union(descendants)
+    reachable_set.add(current_hash)
+
+    return [node for node in nodes if node.output_tree in reachable_set]

pyquipu_cli-0.1.0/src/quipu/cli/commands/helpers.stitcher.yaml

@@ -0,0 +1,10 @@
+"_execute_visit": |-
+  辅助函数：执行 engine.visit 并处理结果
+"_find_current_node": |-
+  在图中查找与当前工作区状态匹配的节点
+"engine_context": |-
+  Context manager to set up logging, create, and automatically close a Quipu engine.
+"filter_nodes": |-
+  根据时间戳和数量过滤节点列表。
+"filter_reachable_nodes": |-
+  仅保留与当前工作区状态直接相关的节点（祖先和后代）。