specmodule 0.1.0__py3-none-any.whl

module_harness/query.py

@@ -0,0 +1,216 @@
+# module_harness/query.py
+"""共享查询层：review 历史时间线组合（roadmap Phase 0）。
+
+CLI（host + 查询形态）、MCP、Web 三形态共同消费本模块——形态只 import，
+绝不重实现。数据源：run.sqlite 的 firings 表；容错哲学同 query_run_status
+（DB 读失败返回 None，监控方绝不被 DB 锁搞崩）。
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class ReviewEntry:
+    """单个节点 firing 的审阅记录。"""
+
+    tick: int
+    node: str
+    status: str          # ok | failed | aborted
+    output: Any = None
+    error: str | None = None
+
+
+@dataclass
+class ReviewTimeline:
+    """完整审阅时间线：firings 顺序，同 (tick, node) 去重 keep-first。"""
+
+    module_id: str
+    entries: list[ReviewEntry] = field(default_factory=list)
+    latest_tick: int | None = None
+
+
+def _run_db_path(module_id: str, base_dir: Path | None) -> Path:
+    """``<base>/.specmodule/runs/<module_id>/run.sqlite``（与 Module 对齐）。"""
+    base = base_dir if base_dir is not None else Path.cwd()
+    return base / ".specmodule" / "runs" / module_id / "run.sqlite"
+
+
+def build_timeline(module_id: str, base_dir: Path | None = None) -> ReviewTimeline | None:
+    """从 run.sqlite 构建审阅时间线。无 DB / 读失败 → None。"""
+    db_path = _run_db_path(module_id, base_dir)
+    if not db_path.exists():
+        return None
+    try:
+        from tickflow.persistence import SqliteBackend
+
+        backend = SqliteBackend(db_path)
+        try:
+            rows = backend.list_firings(module_id)
+        finally:
+            backend.close()
+    except Exception:
+        log.exception("读取 run.sqlite 失败（返回 None）: %s", db_path)
+        return None
+
+    entries: list[ReviewEntry] = []
+    seen: set[tuple[int, str]] = set()
+    latest: int | None = None
+    for d in rows:
+        node = d.get("node")
+        if not node:
+            continue          # 空 node 行跳过（损坏/异常行不阻断时间线）
+        try:
+            tick = int(d.get("tick", 0))
+        except (TypeError, ValueError):
+            log.warning("跳过损坏的 firing 行（tick 非法）: %r", d)
+            continue
+        if (tick, node) in seen:
+            continue          # 与 tickflow audit() 去重语义一致（restore 重放兼容）
+        seen.add((tick, node))
+        entries.append(
+            ReviewEntry(
+                tick=tick,
+                node=node,
+                status=str(d.get("status", "ok")),
+                output=d.get("output"),
+                error=d.get("error"),
+            )
+        )
+        latest = tick if latest is None else max(latest, tick)
+    return ReviewTimeline(module_id=module_id, entries=entries, latest_tick=latest)
+
+
+def _latest_of(entries: list[ReviewEntry]) -> int | None:
+    """过滤后子集中最新 tick（无条目 → None）。"""
+    return max((e.tick for e in entries), default=None)
+
+
+def filter_failed(timeline: ReviewTimeline) -> ReviewTimeline:
+    """只看失败/中止节点（定位问题 tick 的核心路径）。
+
+    latest_tick 重算为过滤子集中的最新 tick（避免过滤后仍报全局 tick 误导）。
+    """
+    entries = [e for e in timeline.entries if e.status != "ok"]
+    return ReviewTimeline(
+        module_id=timeline.module_id,
+        entries=entries,
+        latest_tick=_latest_of(entries),
+    )
+
+
+def filter_tick(timeline: ReviewTimeline, tick: int) -> ReviewTimeline:
+    """只看指定 tick。"""
+    entries = [e for e in timeline.entries if e.tick == tick]
+    return ReviewTimeline(
+        module_id=timeline.module_id,
+        entries=entries,
+        latest_tick=_latest_of(entries),
+    )
+
+
+def filter_node(timeline: ReviewTimeline, node: str) -> ReviewTimeline:
+    """只看指定节点的全部 firing（含 loop 多轮）。"""
+    entries = [e for e in timeline.entries if e.node == node]
+    return ReviewTimeline(
+        module_id=timeline.module_id,
+        entries=entries,
+        latest_tick=_latest_of(entries),
+    )
+
+
+@dataclass
+class CheckpointEntry:
+    """单个回退点（tick 快照或 manual 检查点）。"""
+
+    target: str            # resume/rollback 直传的目标（"3" 或 "manual:xxx"）
+    tick: int
+    kind: str              # "tick"（snapshots 表每 tick 快照）| "manual"（checkpoint() 命名点）
+    fired: list[str] = field(default_factory=list)  # tick 快照本 tick fire 的节点；manual 为空
+    label: str | None = None                         # manual label；tick 快照为 None
+
+
+@dataclass
+class CheckpointList:
+    """全部回退点，按 tick 升序（同 tick 的 manual 排 tick 快照后）。"""
+
+    module_id: str
+    entries: list[CheckpointEntry] = field(default_factory=list)
+
+
+def build_checkpoints(module_id: str, base_dir: Path | None = None) -> CheckpointList | None:
+    """列出可用回退点（snapshots 表 tick 快照 + checkpoints 表 manual 检查点）。
+
+    数据源：run.sqlite；无 DB / 读失败 → None（容错哲学同 build_timeline——
+    监控方绝不被 DB 锁搞崩）。`resume <target>` / `rollback <target>` 的
+    target 即条目 ``target`` 字段。
+    """
+    db_path = _run_db_path(module_id, base_dir)
+    if not db_path.exists():
+        return None
+    try:
+        from tickflow.persistence import SqliteBackend
+
+        backend = SqliteBackend(db_path)
+        try:
+            entries: list[CheckpointEntry] = []
+            for tick in backend.list_snapshots(module_id):
+                snap = backend.load_snapshot(module_id, tick)
+                fired = list(snap.get("fired", [])) if snap else []
+                entries.append(
+                    CheckpointEntry(
+                        target=str(tick), tick=tick, kind="tick", fired=fired
+                    )
+                )
+            entries.extend(
+                CheckpointEntry(target=label, tick=tick, kind="manual", label=label)
+                for label, tick in backend.list_checkpoints(module_id)
+            )
+        finally:
+            backend.close()
+    except Exception:
+        log.exception("读取 run.sqlite 失败（返回 None）: %s", db_path)
+        return None
+    entries.sort(key=lambda e: (e.tick, 0 if e.kind == "tick" else 1))
+    return CheckpointList(module_id=module_id, entries=entries)
+
+
+def checkpoints_to_dict(cl: CheckpointList) -> dict[str, Any]:
+    """JSON 出口（MCP/Web 直接消费同一函数）。"""
+    return {
+        "module_id": cl.module_id,
+        "checkpoints": [
+            {
+                "target": e.target,
+                "tick": e.tick,
+                "kind": e.kind,
+                "fired": list(e.fired),
+                "label": e.label,
+            }
+            for e in cl.entries
+        ],
+    }
+
+
+def timeline_to_dict(timeline: ReviewTimeline) -> dict[str, Any]:
+    """JSON 出口（MCP/Web 直接消费同一函数）。"""
+    return {
+        "module_id": timeline.module_id,
+        "latest_tick": timeline.latest_tick,
+        "entries": [
+            {
+                "tick": e.tick,
+                "node": e.node,
+                "status": e.status,
+                "output": e.output,
+                "error": e.error,
+            }
+            for e in timeline.entries
+        ],
+    }

module_harness/registry.py

@@ -0,0 +1,180 @@
+# module_harness/registry.py
+"""HarnessRegistry — tickflow Registry 子类，管理 harness/script 注册。"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import time
+from typing import Any, Callable
+
+from tickflow import Registry
+from tickflow.views import DictView
+
+from .config import HarnessConfig
+from .command import Command, CommandConfig
+from .harness import Harness
+from .events import (
+    EventBus,
+    ScriptStarted,
+    ScriptCompleted,
+    ScriptFailed,
+)
+
+
+class HarnessRegistry(Registry):
+    """tickflow Registry 子类。tickflow 零修改。
+
+    Runner 只调 ``get_body()``，不感知 harness/script/body 的区别。
+    """
+
+    def __init__(
+        self,
+        *,
+        llm_client: Any,
+        event_bus: EventBus | None = None,
+    ) -> None:
+        super().__init__()
+        self._llm_client = llm_client
+        self._event_bus = event_bus or EventBus.null()
+        self._harness_cfgs: dict[str, HarnessConfig] = {}
+        self._script_names: set[str] = set()
+        self._command_cfgs: dict[str, CommandConfig] = {}
+
+    # ── harness 注册 ──────────────────────────────────────────────
+
+    def harness(
+        self,
+        name: str,
+        config: HarnessConfig,
+        *,
+        promptmode: str | None = None,
+        prompt_extra: str | None = None,
+        spec_inputs: dict[str, Any] | None = None,
+        input_aliases: dict[str, str] | None = None,
+    ) -> "HarnessRegistry":
+        """注册一个 harness body。
+
+        ``name`` 是 graph 中 ``node.body`` 引用的名称。
+        ``spec_inputs``：spec 字段常量，渲染时作为占位符兜底值。
+        ``input_aliases``：跨节点输入别名 {field_name: producer}，
+        prompt 的 {field} 占位符在运行时解析 producer 的输出值。
+        返回 self，支持链式调用。
+        """
+        h = Harness(config, self._llm_client, self._event_bus)
+        body = h.build_body(
+            promptmode=promptmode,
+            prompt_extra=prompt_extra,
+            spec_inputs=spec_inputs,
+            input_aliases=input_aliases,
+        )
+        self.body(name, body)
+        self._harness_cfgs[name] = config
+        return self
+
+    # ── script 注册 ───────────────────────────────────────────────
+
+    def script(self, name: str):
+        """装饰器：``@reg.script('name')`` — 包裹事件发射后注册为 body。
+
+        body 执行时自动发射 ScriptStarted / ScriptCompleted / ScriptFailed。
+        支持 sync 和 async 用户函数。
+        """
+        bus = self._event_bus
+
+        def deco(fn: Callable) -> Callable:
+            is_async = inspect.iscoroutinefunction(fn)
+
+            if is_async:
+                @functools.wraps(fn)
+                async def wrapped(view: DictView) -> Any:
+                    node = view.node
+                    bus.emit(ScriptStarted(
+                        timestamp=time.monotonic(), node=node, tick=0,
+                    ))
+                    try:
+                        result = await fn(view)
+                    except Exception as e:
+                        bus.emit(ScriptFailed(
+                            timestamp=time.monotonic(), node=node, tick=0,
+                            error=str(e),
+                        ))
+                        raise
+                    bus.emit(ScriptCompleted(
+                        timestamp=time.monotonic(), node=node, tick=0,
+                        output_type=type(result).__name__,
+                    ))
+                    return result
+            else:
+                @functools.wraps(fn)
+                def wrapped(view: DictView) -> Any:
+                    node = view.node
+                    bus.emit(ScriptStarted(
+                        timestamp=time.monotonic(), node=node, tick=0,
+                    ))
+                    try:
+                        result = fn(view)
+                    except Exception as e:
+                        bus.emit(ScriptFailed(
+                            timestamp=time.monotonic(), node=node, tick=0,
+                            error=str(e),
+                        ))
+                        raise
+                    bus.emit(ScriptCompleted(
+                        timestamp=time.monotonic(), node=node, tick=0,
+                        output_type=type(result).__name__,
+                    ))
+                    return result
+
+            self.body(name, wrapped)
+            self._script_names.add(name)
+            return wrapped
+
+        return deco
+
+    # ── command 注册 ───────────────────────────────────────────────
+
+    def command(
+        self,
+        name: str,
+        config: CommandConfig,
+        *,
+        timeout: float | None = None,
+        cwd: str | None = None,
+    ) -> "HarnessRegistry":
+        """注册一个 command body。
+
+        ``name`` 是 graph 中 ``node.body`` 引用的名称。
+        返回 self，支持链式调用。
+        """
+        cmd = Command(config, self._event_bus)
+        body = cmd.build_body(timeout=timeout, cwd=cwd)
+        self.body(name, body)
+        self._command_cfgs[name] = config
+        return self
+
+    # ── 查询 ──────────────────────────────────────────────────────
+
+    def is_harness(self, name: str) -> bool:
+        """name 是否通过 harness() 注册。"""
+        return name in self._harness_cfgs
+
+    def is_script(self, name: str) -> bool:
+        """name 是否通过 script() 注册。"""
+        return name in self._script_names
+
+    def is_command(self, name: str) -> bool:
+        """name 是否通过 command() 注册。"""
+        return name in self._command_cfgs
+
+    def harness_config(self, name: str) -> HarnessConfig | None:
+        """返回 harness 的配置，若不是 harness 返回 None。"""
+        return self._harness_cfgs.get(name)
+
+    def command_config(self, name: str) -> CommandConfig | None:
+        """返回 command 的配置，若不是 command 返回 None。"""
+        return self._command_cfgs.get(name)
+
+    def guard_names(self) -> list[str]:
+        """已注册 guard 名列表（publish 单文件转化枚举用）。"""
+        return list(getattr(self, "_guards", {}).keys())