refactor: deprecate private _advance_pointer in favor of public advance_pointer method

Author: JohnRichard4096

docs/guide/advanced/built-in_instruction_set/jump_clause.md

@@ -24,7 +24,7 @@ That means:
 1. **Address resolution** (`_pre_check`): resolve alias names through the alias table, or validate raw addresses.
 2. **Jump marker**: call `pc.jump_to(addr)`, which is guarded by `@markup` and sets `_jump_marked=True`.
 3. **Pointer replacement**: replace `_pointer` completely with the target address vector.
-4. **Interpreter response**: the main loop sees `_jump_marked` and skips normal `_advance_pointer()`, continuing from the jump target.
+4. **Interpreter response**: the main loop sees `_jump_marked` and skips normal `advance_pointer()`, continuing from the jump target.
 
 ### Key characteristics
 

docs/reference/api/runtime.md

@@ -120,6 +120,34 @@ Find a node or rendered composition by absolute address.
 
 Resolve an alias and return the corresponding node object.
 
+#### `advance_pointer(ptr: PointerVector | None = None) -> bool`
+
+Advance the execution pointer to the next node in the workflow graph. This method implements the logic for navigating through nested workflow structures, handling both sequential execution and hierarchical traversal.
+
+**Parameters**
+
+- `ptr`: Optional external pointer vector to advance. When provided, the method advances this pointer **without modifying the interpreter's own `_pointer`**. Defaults to `None`, in which case `self._pointer` is advanced. This enables external systems to preview pointer advancement paths without disturbing interpreter state.
+
+**Returns**
+
+- `True` if the pointer was successfully advanced to the next node.
+- `False` if the end of the workflow has been reached.
+
+**Algorithm**
+
+1. Starting from `ptr` (or `self._pointer`), traverse `base_addr` layer-by-layer to locate the container of the current node.
+2. If the current node is a **non-empty `NodeComposeRendered`** → enter the nested container (`append(0)`), return `True`.
+3. If the current node has a **next sibling**:
+   - Sibling is a non-empty `NodeComposeRendered` → enter that nested container, return `True`.
+   - Otherwise → move to the sibling node, return `True`.
+4. If no next sibling → **backtrack up** the pointer stack layer-by-layer, looking for a parent container's next sibling.
+5. If a next sibling is found during backtracking → apply the same logic, return `True`.
+6. If backtracking reaches the top level with no more siblings → return `False` (end of workflow).
+
+**Deprecation**
+
+The `_advance_pointer` property is deprecated since v0.3.0. Use `advance_pointer()` instead. The old property exists only as a compatibility shim and will be removed in a future version.
+
 ### Execution behavior
 
 `WorkflowInterpreter` preserves execution atomicity by holding `_interpret_lock` while a single node is executed. It only checks suspend points at safe boundaries:

docs/zh/guide/advanced/built-in_instruction_set/jump_clause.md

@@ -24,7 +24,7 @@
 1. **地址解析**（`_pre_check` 阶段）：将别名查表解析为 `list[int]` 绝对地址，或直接验证裸地址的有效性
 2. **跳转标记**：调用 `pc.jump_to(addr)`，该方法受 `@markup` 保护，设置 `_jump_marked=True`
 3. **指针替换**：`_pointer` 被完整替换为目标地址向量
-4. **解释器响应**：主循环检测到 `_jump_marked`，跳过常规的 `_advance_pointer()` 步进，下一轮迭代从跳转目标开始执行
+4. **解释器响应**：主循环检测到 `_jump_marked`，跳过常规的 `advance_pointer()` 步进，下一轮迭代从跳转目标开始执行
 
 ### 关键特性
 

docs/zh/reference/api/runtime.md

@@ -51,7 +51,7 @@ def __init__(
 - `_graph: NodeComposeRendered`：编译后的只读工作流图，解释器从中读取节点
 - `_pointer: PointerVector`：当前执行位置。解释器主循环始终以它指向的节点作为执行目标
 - `_ret_addr_stack: Stack[PointerVector]`：返回地址栈。`call_sub` 和 `CALL` 指令压入返回地址，执行完毕弹栈恢复
-- `_jump_marked: bool`：跳转标记。当 `True` 时，主循环跳过本次的 `_advance_pointer()` 步进，下一轮直接从跳转目标继续
+- `_jump_marked: bool`：跳转标记。当 `True` 时，主循环跳过本次的 `advance_pointer()` 步进，下一轮直接从跳转目标继续
 - `_interpret_lock: aiologic.Lock`：解释锁。每次迭代获取一次，保证单个节点的执行原子性。同时也是外部安全调用的互斥锁
 - `_ava_args / _ava_kwargs`：执行期可用参数池，供依赖注入系统从中匹配节点的参数签名
 - `_exc_ignored: tuple[type[BaseException], ...]`：运行时自动包含 `InterruptNotice` 和 `BreakLoop`。这些异常不会被任何 `CATCH` 块捕获，直接穿透到顶层
@@ -137,6 +137,36 @@ def __init__(
 
 装饰器的类型注解使用 `fun_T` TypeVar 保留原始方法签名。在 `TYPE_CHECKING` 下，它会返回原始函数以避免混淆静态类型检查器。所有被装饰的方法必须是返回 `None` 的实例方法。
 
+#### 指针推进
+
+**`advance_pointer(ptr: PointerVector | None = None) -> bool`**
+
+推进执行指针到工作流图中的下一个节点。此方法实现了嵌套工作流结构的导航逻辑，处理顺序执行和层级遍历。
+
+**参数**
+
+- `ptr`：可选的外部指针向量。传入后，方法将推进此参数所指的指针，而**不会改变解释器自身的 `_pointer`**。默认为 `None` 时，推进解释器自身的 `_pointer`。此参数使外部系统可以在不破坏解释器状态的前提下，预演指针推进路径。
+
+**返回值**
+
+- `True`：指针成功推进到下一个节点
+- `False`：已到达工作流末尾，无更多节点可执行
+
+**推进算法**
+
+1. 从 `ptr`（或 `self._pointer`）开始，沿 `base_addr` 逐层定位到当前节点所在容器
+2. 若当前节点是**非空 `NodeComposeRendered`** → 指针进入嵌套容器（`append(0)`），返回 `True`
+3. 若当前节点有**后继兄弟节点**：
+   - 兄弟节点是非空 `NodeComposeRendered` → 进入该嵌套容器，返回 `True`
+   - 否则 → 移动到兄弟节点，返回 `True`
+4. 若当前节点无后继 → 沿指针栈**逐层向上回溯**，寻找父容器的下一个兄弟
+5. 回溯中寻得后继 → 按相同逻辑处理，返回 `True`
+6. 回溯到顶层仍未找到 → 返回 `False`（工作流结束）
+
+**弃用说明**
+
+`_advance_pointer` 属性已在 v0.3.0 弃用，请使用 `advance_pointer()` 方法。旧属性仅作为兼容性委托存在，将在未来版本中移除。
+
 ### 执行行为
 
 `WorkflowInterpreter` 通过持有 `_interpret_lock` 保证单个节点的执行原子性。它仅在安全边界检查挂起点：
@@ -185,7 +215,7 @@ await pc.run()
 3. 在 `PC_CHECKPOINT` 断点等待外部挂起
 4. 执行当前节点（`_call()`）
 5. 若 `_jump_marked`，重置标记并跳过指针推进
-6. 否则调用 `_advance_pointer()` 推进指针
+6. 否则调用 `advance_pointer()` 推进指针
 7. 指针推进失败（到达末尾）则退出
 
 外层 `try` 捕获 `InterruptNotice` 后清理调用栈和指针，干净退出。

src/amrita_sense/runtime/workflow.py

@@ -8,6 +8,7 @@
 from typing import TYPE_CHECKING, Any, Generic, TypeVar, cast
 
 import aiologic
+from typing_extensions import deprecated
 
 from amrita_sense.exceptions import (
     BreakLoop,
@@ -129,9 +130,9 @@ def find_addr_alias(self, alias: str) -> list[int]:
         Raises:
             NullPointerException: If the alias does not exist in the graph.
         """
-        if alias not in self._graph.alias2vector_map:
+        if alias not in self.get_graph().alias2vector_map:
             raise NullPointerException(f"{alias} is not a valid alias")
-        return self._graph.alias2vector_map[alias]
+        return self.get_graph().alias2vector_map[alias]
 
     def find_node_alias(self, alias: str) -> BaseNode | NodeComposeRendered:
         """Find a node by its alias and return the node object.
@@ -381,11 +382,12 @@ async def run_step_by(self) -> AsyncGenerator[Any, None]:
                 ):
                     raise RuntimeError("Runtime arguments cannot be resolved")
             self._ava_args = tuple(session_args)
+            graph = self.get_graph()
             while True:
                 await self.object_io._wait_for_continue(PC_CHECKPOINT)
                 async with self._interpret_lock:
                     if not self._pointer:
-                        if not self._graph:
+                        if not graph:
                             break
                         self._pointer.append(0)
                     yield (
@@ -397,7 +399,7 @@ async def run_step_by(self) -> AsyncGenerator[Any, None]:
                         self._jump_marked = False
                         continue
 
-                    if not self._advance_pointer():
+                    if not self.advance_pointer():
                         break
         except InterruptNotice as e:
             logger.info(f"Interrupt notice at {self._pointer} :{e.message}")
@@ -406,24 +408,35 @@ async def run_step_by(self) -> AsyncGenerator[Any, None]:
             self._pointer.clear()
             self._jump_marked = False
 
-    def _advance_pointer(self) -> bool:
-        """Advance the execution pointer to the next node in the workflow.
+    @deprecated(
+        "Method of `_advance_pointer` is now `advance_pointer`, this compile method will be removed in `v0.3.0`",
+        category=DeprecationWarning,
+    )
+    @property
+    def _advance_pointer(self):
+        return self.advance_pointer
+
+    def advance_pointer(self, ptr: PointerVector | None = None) -> bool:
+        """Advance the execution pointer to the next node with ptr arg by the graph.
 
-        This internal method implements the complex logic for navigating through
+        This method implements the logic for navigating through
         nested workflow structures, handling both sequential execution and
         hierarchical traversal.
 
+        Args:
+            ptr (PointerVector, optional): ptr to advance to. If None, advance to the next node in the current container of interpreter.
+
         Returns:
-            True if the pointer was successfully advanced, False if at the end of workflow.
+            bool: True if the pointer was successfully advanced, False if at the end of workflow.
         """
-        if not self._pointer:
+        pointer: PointerVector = ptr if ptr is not None else self._pointer
+        if not pointer:
             logger.debug("Pointer is empty, cannot advance")
             return False
 
-        pointer: PointerVector = self._pointer
         logger.debug(f"Advancing pointer from {pointer}")
-
-        current_container: BaseNode | NodeComposeRendered = self._graph
+        graph: NodeComposeRendered = self.get_graph()
+        current_container: BaseNode | NodeComposeRendered = graph
         for idx in pointer.base_addr[:-1]:
             if isinstance(current_container, NodeComposeRendered):
                 current_container = current_container[idx]
@@ -464,7 +477,7 @@ def _advance_pointer(self) -> bool:
                 return False
 
             parent_path: list[int] = pointer.base_addr[:-1]
-            parent_container: BaseNode | NodeComposeRendered = self._graph
+            parent_container: BaseNode | NodeComposeRendered = graph
             for idx in parent_path:
                 if isinstance(parent_container, NodeComposeRendered):
                     parent_container = parent_container[idx]
@@ -508,7 +521,7 @@ def _find_addr_or_none(
         Returns:
             The node at the specified address, or None if it doesn't exist.
         """
-        graph: NodeComposeRendered = self._graph
+        graph: NodeComposeRendered = self.get_graph()
         current_chunk: NodeComposeRendered | BaseNode = graph
 
         for i, chunk in enumerate(addr):
@@ -570,7 +583,9 @@ async def _call(
         addr_getter = addr_getter or self.find_addr
         node: BaseNode | NodeComposeRendered = addr_getter(self._pointer.base_addr)
         if isinstance(node, NodeComposeRendered):
-            raise RuntimeError("Cannot call a NodeCompose.")
+            raise RuntimeError(
+                f"Cannot call a NodeCompose in addr {self._pointer.base_addr}."
+            )
         await self.object_io._wait_for_continue(node.tag)
 
         node._pre_check(self)