specmodule 0.1.3__tar.gz → 0.1.4__tar.gz

{specmodule-0.1.3/specmodule.egg-info → specmodule-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specmodule
-Version: 0.1.3
+Version: 0.1.4
 Summary: 可审计、可调试、可完全掌控的 LLM 使用框架（tickflow + llm + module_harness）
 License: MIT
 Keywords: llm,workflow,petri-net,agent

{specmodule-0.1.3 → specmodule-0.1.4}/module_harness/__init__.py

@@ -24,6 +24,7 @@ from .events import (
 )
 from .command import Command, CommandConfig
 from .harness import Harness
+from .call import HarnessCallError, HarnessCallResult, call_harness
 from .registry import HarnessRegistry
 from .spec import (
     Spec,
@@ -57,6 +58,7 @@ from .query import (
     ReviewTimeline,
     build_checkpoints,
     build_timeline,
+    check_resume_compat_from_run,
     checkpoints_to_dict,
     create_checkpoint,
     filter_failed,
@@ -95,6 +97,10 @@ from .store import (
     validate_pack_dir,
 )
 
+# 嵌入者最小面（用法见 docs/guides/embedding.md）：
+#   task 级 = call_harness / HarnessCallResult / HarnessCallError
+#   图级   = Module / HarnessRegistry + HarnessConfig / OutputFormat / EventBus
+#             + TemplateLoader + register_builtin_harnesses
 __all__ = [
     # 配置
     "HarnessConfig",
@@ -118,6 +124,10 @@ __all__ = [
     "ScriptFailed",
     # 核心
     "Harness",
+    # task 级 API 地板（嵌入者消费面，docs/dev/superpowers/specs/2026-09-01-embedder-face-design.md）
+    "HarnessCallResult",
+    "HarnessCallError",
+    "call_harness",
     "HarnessRegistry",
     "Command",
     "CommandConfig",
@@ -168,6 +178,7 @@ __all__ = [
     "ResumeCheck",
     "ResumeError",
     "check_resume_compat",
+    "check_resume_compat_from_run",
     # 模块入口（roadmap Phase 0：CLI 使用）
     "ModuleEntry",
     "discover_modules",

specmodule-0.1.4/module_harness/call.py

@@ -0,0 +1,89 @@
+# module_harness/call.py
+"""task 级 API 地板 —— 独立调用 harness（嵌入者消费面）。
+
+API 金字塔自此 task → graph → run：嵌入者一次函数调用即得 harness 节点的
+全部执行语义（三层 prompt / 输出校验 / 事件），不经图与 run。
+零新执行语义：内部即 Harness.build_body + 一次 body 调用，仅一份执行配方。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from tickflow import Failure
+from tickflow.views import DictView, Resolved
+
+from .config import HarnessConfig
+from .events import EventBus
+from .harness import Harness
+
+
+@dataclass
+class HarnessCallResult:
+    """独立调用结果：校验后输出 + LLM 原始输出 + token 用量。"""
+
+    value: Any  # 校验后的输出（json_object → 解析值；text → str）
+    raw: str    # LLM 原始输出（审计链）
+    usage: dict[str, int]  # token 用量
+
+
+class HarnessCallError(RuntimeError):
+    """独立调用失败（LLM 错误 / 输出不合法）。异常即审计：携带诊断链。"""
+
+    def __init__(
+        self,
+        failure: Failure,
+        *,
+        prompt: str | None = None,
+        raw: str | None = None,
+        usage: dict[str, int] | None = None,
+    ) -> None:
+        self.failure = failure
+        self.prompt = prompt
+        self.raw = raw
+        self.usage = usage
+        super().__init__(failure.error)
+
+
+async def call_harness(
+    config: HarnessConfig,
+    values: dict[str, Any],
+    *,
+    llm_client: Any,
+    promptmode: str | None = None,
+    prompt_extra: str | None = None,
+    event_bus: EventBus | None = None,
+) -> HarnessCallResult:
+    """独立调用一个 harness：一次函数调用拿到校验后的输出。
+
+    ``values``：prompt 占位符取值 {key: value}。task 层的占位符兜底就是它
+    （无 spec_inputs / input_aliases —— 那些是图概念）。
+
+    ``event_bus``：传则收全套 harness 事件（PromptRendered / LlmToken /
+    OutputValidated / ...），不传零开销（EventBus.null()）。
+
+    失败（LLM 错误 / 输出校验不通过）抛 HarnessCallError，携带 failure 与
+    渲染 prompt / 原始输出 / usage 诊断链。task 层没有"下游跳过"概念，
+    Failure 一律翻译为异常；promptmode 缺 key → KeyError 原样冒出。
+    """
+    bus = event_bus or EventBus.null()
+    body = Harness(config, llm_client, bus).build_body(
+        promptmode=promptmode,
+        prompt_extra=prompt_extra,
+    )
+    state: dict[str, Any] = {}
+    view = DictView(
+        {key: Resolved(value=val, k=None) for key, val in values.items()},
+        state=state,
+        node="__call__",
+    )
+    result = await body(view)
+
+    prompt = state.get("_prompt")
+    raw = state.get("_llm_raw")
+    usage = state.get("_usage")
+
+    if isinstance(result, Failure):
+        raise HarnessCallError(result, prompt=prompt, raw=raw, usage=usage)
+    return HarnessCallResult(value=result, raw=raw, usage=usage)

{specmodule-0.1.3 → specmodule-0.1.4}/module_harness/consistency.py

@@ -1,18 +1,16 @@
 # module_harness/consistency.py
 """一致性审核 — spec + tasklist 语义一致性检查。
 
-独立于翻译通道：审核不经过模板，直接调用注册的审核 harness body（不走 tickflow）。
+独立于翻译通道：审核不经过模板，经 call_harness 直接调用注册的审核
+harness 配置（不走 tickflow 图）。
 """
 
 from __future__ import annotations
 
 import json
 from dataclasses import dataclass
-from typing import Any
-
-from tickflow import Failure
-from tickflow.views import DictView, Resolved
 
+from .call import HarnessCallError, call_harness
 from .config import HarnessConfig
 from .outputfmt import OutputFormat
 from .registry import HarnessRegistry
@@ -60,7 +58,14 @@ def register_review_harness(
 
 
 class ConsistencyReviewer:
-    """调用审核 harness body，返回 ConsistencyReport。"""
+    """调用审核 harness，返回 ConsistencyReport。
+
+    审核走 call_harness（task 级地板）：不传 bus，内部中间事件静默
+    （ConsistencyReviewed 领域事件由 Module 直接发射，不经此处）。
+    按 register_review_harness 契约，审核 harness 只带 config 注册
+    （注册期 promptmode/prompt_extra/spec_inputs/input_aliases 对审核器无意义，
+    call_harness 路径不传）。
+    """
 
     def __init__(
         self, registry: HarnessRegistry, harness_name: str = "spec_tasklist_review"
@@ -70,41 +75,32 @@ class ConsistencyReviewer:
 
     async def review(self, spec: Spec, tasklist: Tasklist) -> ConsistencyReport:
         """执行一致性审核。审核失败（LLM 错误/输出不合法）抛 ValueError。"""
-        if self.reg.harness_config(self.harness_name) is None:
+        config = self.reg.harness_config(self.harness_name)
+        if config is None:
             raise ValueError(
                 f"审核 harness '{self.harness_name}' 未注册。"
                 f"请先调用 register_review_harness(reg) 注册内置审核器，"
                 f"或自行 reg.harness('{self.harness_name}', ...)。"
             )
-        body = self.reg.get_body(self.harness_name)
-
-        tasklist_dict = tasklist.to_dict()
-        state: dict[str, Any] = {}
-        view = DictView(
-            {
-                "spec": Resolved(value=spec.to_dict(), k=None),
-                "tasklist": Resolved(
-                    value=json.dumps(tasklist_dict, ensure_ascii=False), k=None
-                ),
-            },
-            state=state,
-            node="__review__",
-        )
-        result = await body(view)
 
-        if isinstance(result, Failure):
-            raise ValueError(f"审核 harness 返回 Failure: {result.error}")
+        try:
+            call = await call_harness(
+                config,
+                {
+                    "spec": spec.to_dict(),
+                    "tasklist": json.dumps(tasklist.to_dict(), ensure_ascii=False),
+                },
+                llm_client=self.reg.llm_client,
+            )
+        except HarnessCallError as e:
+            raise ValueError(f"审核 harness 返回 Failure: {e.failure.error}") from e
 
-        if isinstance(result, str):
+        data = call.value
+        if isinstance(data, str):
             try:
-                data = json.loads(result)
+                data = json.loads(data)
             except json.JSONDecodeError as e:
                 raise ValueError(f"审核输出不是合法 JSON: {e}") from e
-        elif isinstance(result, dict):
-            data = result
-        else:
-            raise ValueError(f"审核输出类型异常: {type(result).__name__}")
-
         if not isinstance(data, dict):
             raise ValueError(f"审核输出必须是 JSON 对象: {data!r}")
 
@@ -115,9 +111,6 @@ class ConsistencyReviewer:
         if not isinstance(suggestions, str):
             raise ValueError(f"审核输出 'suggestions' 必须是字符串: {data!r}")
 
-        raw = state.get("_llm_raw")
-        if raw is None:
-            raw = result if isinstance(result, str) else json.dumps(data, ensure_ascii=False)
         return ConsistencyReport(
-            consistent=consistent, suggestions=suggestions, raw=raw
+            consistent=consistent, suggestions=suggestions, raw=call.raw
         )

{specmodule-0.1.3 → specmodule-0.1.4}/module_harness/module.py

@@ -20,7 +20,14 @@ from .consistency import ConsistencyError, ConsistencyReport, ConsistencyReviewe
 from .translator import Translator, TemplateLoader, TasklistValidator
 from .graph_builder import TasklistTranslator
 from .registry import HarnessRegistry
-from .events import EventBus, ConsistencyReviewed
+from .events import (
+    EventBus,
+    ConsistencyReviewed,
+    HarnessFailed,
+    LlmCallCompleted,
+    LlmCallStarted,
+    LlmToken,
+)
 from .checkpoint import (
     ModuleInputStore,
     ResumeError,
@@ -28,7 +35,9 @@ from .checkpoint import (
     tasklist_from_dict,
     tasklist_to_dict,
 )
+from .query import _executed_nodes
 from .control import clear_control, control_tick_end, control_tick_start
+from .stream import StreamLogWriter, stream_log_path
 
 log = logging.getLogger(__name__)
 
@@ -74,6 +83,10 @@ class Module:
         persist: bool = True,
         status_file: bool = True,
         control: bool = True,
+        # True（默认）：LLM 流式输出落盘 stream.log（跨进程流式观测，见
+        # stream.py）。EventBus.null() 场景只有 run_start 记录（事件被
+        # null bus 吞掉，属预期）。
+        stream_log: bool = True,
         modules: dict[str, Any] | None = None,
         hooks: dict | None = None,
     ) -> None:
@@ -93,6 +106,11 @@ class Module:
         # True（默认）：注册控制文件 hook（control.json → cancel/pause，
         # 见 control.py）。跨进程取消/暂停的协作式通道；False 关闭。
         self.control = control
+        self.stream_log = stream_log
+        # stream.log 接线状态：订阅只挂一次（防多次执行重复订阅记录翻倍）；
+        # writer 每次执行重建（_run_with_phases 生命周期），事件回调读当前属性
+        self._stream_subscribed = False
+        self._stream_writer: StreamLogWriter | None = None
         self.review_result: ConsistencyReport | None = None
         self.module_id = module_id or f"mod_{uuid.uuid4().hex[:8]}"
         self._base_dir = base_dir or Path.cwd()
@@ -128,7 +146,7 @@ class Module:
         """原子写 status.json（tmp + os.replace）。失败仅 log，不阻断运行。
 
         phase 取值：idle/translating/reviewing/building/ready/running/
-        done/aborted/cancelled。status_file=False 时不写盘（零残留）。
+        done/aborted/cancelled/truncated。status_file=False 时不写盘（零残留）。
         """
         if not self.status_file:
             return
@@ -358,19 +376,66 @@ class Module:
             # 位于写 running phase 之前——监控方看到 running 才放开控制按钮，
             # 此时清场已完成，清场与首请求的竞态窗口关闭。
             clear_control(self.module_id, base_dir=self._base_dir)
-        self._archive_module_inputs()
-        self._write_phase("running")
+        writer = self._open_stream_log(max_ticks)
         try:
-            firings = await runner.run_until_idle(max_ticks=max_ticks)
-        except asyncio.CancelledError:
-            self._write_phase("cancelled", error="cancelled")
-            raise
-        except Exception as e:
-            self._write_phase("aborted", error=str(e))
-            raise
-        else:
-            self._finalize_phase(runner)
-        return firings
+            self._archive_module_inputs()
+            self._write_phase("running")
+            try:
+                firings = await runner.run_until_idle(max_ticks=max_ticks)
+            except asyncio.CancelledError:
+                self._write_phase("cancelled", error="cancelled")
+                raise
+            except Exception as e:
+                self._write_phase("aborted", error=str(e))
+                raise
+            else:
+                self._finalize_phase(runner, max_ticks)
+            return firings
+        finally:
+            self._close_stream_log(writer)
+
+    def _open_stream_log(self, max_ticks: int) -> StreamLogWriter | None:
+        """stream_log=True 时开本次执行的 writer 并写 run_start 边界。
+
+        run_start 先于 running phase 写入——监控方见到 running 时锚点记录
+        必已存在（status.json 原子写在同一执行线程、顺序在后）。事件订阅
+        只挂一次（守卫 flag），回调经 Module 当前 writer 属性落盘。
+        """
+        if not self.stream_log:
+            return None
+        if not self._stream_subscribed:
+            bus = self._reg._event_bus
+            for evt in (LlmCallStarted, LlmToken, LlmCallCompleted, HarnessFailed):
+                bus.subscribe(evt, self._on_stream_event)
+            self._stream_subscribed = True
+        writer = StreamLogWriter(stream_log_path(self.module_id, self._base_dir))
+        self._stream_writer = writer
+        writer.write({"type": "run_start", "pid": os.getpid(), "max_ticks": max_ticks})
+        return writer
+
+    def _close_stream_log(self, writer: StreamLogWriter | None) -> None:
+        """执行结束（含异常路径）摘除当前 writer 并关闭。"""
+        self._stream_writer = None
+        if writer is not None:
+            writer.close()
+
+    def _on_stream_event(self, event: Any) -> None:
+        """EventBus → stream.log 记录（四类事件 → 四种记录，见 stream.py）。"""
+        w = self._stream_writer
+        if w is None:
+            return
+        if isinstance(event, LlmCallStarted):
+            w.write({"type": "call_start", "node": event.node,
+                     "model": event.model, "prompt_chars": event.prompt_chars})
+        elif isinstance(event, LlmToken):
+            w.write({"type": "token", "node": event.node, "chunk": event.chunk})
+        elif isinstance(event, LlmCallCompleted):
+            w.write({"type": "call_end", "node": event.node,
+                     "content_chars": event.content_chars,
+                     "finish_reason": event.finish_reason})
+        elif isinstance(event, HarnessFailed):
+            w.write({"type": "call_error", "node": event.node,
+                     "reason": event.reason, "failure_type": event.failure_type})
 
     def _archive_module_inputs(self) -> None:
         """归档本次运行的 spec/tasklist 到 module_inputs 表（警告 1 对比源）。
@@ -387,7 +452,7 @@ class Module:
             self.spec.to_dict(), self._last_tasklist.to_dict()
         )
 
-    def _finalize_phase(self, runner: AsyncRunner) -> None:
+    def _finalize_phase(self, runner: AsyncRunner, max_ticks: int) -> None:
         """按 runner.status 映射终态 phase（run/resume 共用）。"""
         from tickflow.runner import RunStatus
         if runner.status == RunStatus.ABORTED:
@@ -397,7 +462,11 @@ class Module:
         elif runner.status == RunStatus.FAILED:
             self._write_phase("aborted", error="all nodes failed")
         elif runner.status == RunStatus.RUNNING:
-            self._write_phase("running")   # max_ticks 截断：仍在运行
+            # max_ticks 耗尽（pause 挂起发生在 run_until_idle 内部不返回，
+            # RUNNING 是唯一来源）→ 真终态：监控方拿到可 resume 的确定性信号
+            self._write_phase(
+                "truncated", error=f"max_ticks={max_ticks} 截断（可 resume 续跑）"
+            )
         else:
             self._write_phase("done")
 
@@ -434,15 +503,7 @@ class Module:
                     f"回退目标 {rollback_to!r} 不存在"
                     f"（可用 tick: {ticks or '无'}；manual: {manual or '无'}）"
                 )
-            # 已执行节点：firings 表中 tick < 快照 tick 的去重节点（S3 后
-            # 快照不再含 edges 窗口）。快照 tick N 在 tick N-1 结束后落盘，
-            # tick == N 的 firing 属于 restore 后会被重跑的部分，不算已执行。
-            # 注：firings 表按 module_id 累积（跨多次 run），前一轮 run 的
-            # 记录也会计入——仅影响提示性警告 1/3 的准确性，不影响硬错误。
-            executed_nodes = {
-                d["node"] for d in backend.list_firings(self.module_id)
-                if d.get("node") and int(d.get("tick", 0)) < int(snap.get("tick", 0))
-            }
+            executed_nodes = _executed_nodes(backend, self.module_id, int(snap.get("tick", 0)))
         except KeyError as e:
             self._write_phase("aborted", error=str(e))
             raise

{specmodule-0.1.3 → specmodule-0.1.4}/module_harness/query.py

@@ -8,11 +8,14 @@ CLI（host + 查询形态）、MCP、Web 三形态共同消费本模块——形
 
 from __future__ import annotations
 
+import json
 import logging
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
+from .stream import stream_log_path
+
 log = logging.getLogger(__name__)
 
 
@@ -46,6 +49,65 @@ def run_db_path(module_id: str, base_dir: Path | None = None) -> Path:
     return base / ".specmodule" / "runs" / module_id / "run.sqlite"
 
 
+def read_stream(
+    run_id: str, *, offset: int = 0, base_dir: Path | None = None
+) -> dict[str, Any] | None:
+    """增量读 stream.log（LLM 流式观测共享读端；Web WS 追尾/未来 TUI 共用）。
+
+    二进制 seek(offset) 读到 EOF，按完整行切分；每条记录附行首字节偏移
+    ``off``（锚定策略——只显示最近一次执行——由消费方据 off 自行定位，展示
+    策略不进库）。末尾不完整行不消费（next_offset 停在其行首，等补齐后
+    下次读出）；JSON 解析失败的行跳过（崩溃瞬间可能出半行）；
+    ``offset > file_size``（文件被替换/重建）钳回 0 自愈。文件缺失 → None。
+
+    返回 ``{"records": [...], "next_offset": int, "file_size": int}``。
+    """
+    path = stream_log_path(run_id, base_dir)
+    if not path.exists():
+        return None
+    try:
+        size = path.stat().st_size
+        start = offset if offset <= size else 0
+        with path.open("rb") as fh:
+            fh.seek(start)
+            data = fh.read()
+    except OSError:
+        log.exception("读 stream.log 失败（返回 None）: %s", path)
+        return None
+    nl = data.rfind(b"\n")
+    if nl < 0:
+        return {"records": [], "next_offset": start, "file_size": size}
+    pos = start
+    records: list[dict[str, Any]] = []
+    for line in data[:nl].split(b"\n"):
+        line_off = pos
+        pos += len(line) + 1
+        if not line.strip():
+            continue
+        try:
+            rec = json.loads(line.decode("utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            log.warning("跳过损坏的 stream.log 行（off=%d）", line_off)
+            continue
+        rec["off"] = line_off
+        records.append(rec)
+    return {"records": records, "next_offset": start + nl + 1, "file_size": size}
+
+
+def _executed_nodes(backend: Any, module_id: str, tick: int) -> set[str]:
+    """firings 表中 tick < 快照 tick 的去重节点（resume 已执行判定，单一事实源）。
+
+    快照 tick N 在 tick N-1 结束后落盘，tick == N 的 firing 属 restore 后
+    会被重跑的部分，不算已执行。firings 按 module_id 累积（跨多次 run），
+    前一轮 run 的记录也会计入——仅影响提示性警告 1/3 的准确性，不影响硬错误。
+    """
+    return {
+        d["node"]
+        for d in backend.list_firings(module_id)
+        if d.get("node") and int(d.get("tick", 0)) < tick
+    }
+
+
 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=base_dir)
@@ -319,6 +381,140 @@ def read_module_inputs(
         store.close()
 
 
+def check_resume_compat_from_run(
+    module_name: str,
+    run_id: str,
+    *,
+    new_tasklist: Any = None,
+    target: int | str | None = None,
+    base_dir: Path | None = None,
+) -> dict[str, Any] | None:
+    """恢复预检：从运行产物组合材料跑兼容性校验——不 spawn、不写状态。
+
+    resume（module.py）内联组合的第二消费端收编：目标快照解析 →
+    executed_nodes（_executed_nodes）→ 旧输入存档（read_module_inputs）→
+    建图（build_run_graph 同款 Mock registry 通道，零 LLM；new_tasklist
+    给出时走直渲染通道）→ check_resume_compat（marking.slots / armed_starts
+    取自目标快照）。
+
+    - ``new_tasklist``：dict 或 Tasklist；None = 用归档 tasklist（纯续跑预检）。
+    - ``target``：tick 号 / ``"manual:<label>"`` / None（最新快照）。
+
+    错误契约：run.sqlite 缺失/读失败 → None（查询容错，调用方映射 404）；
+    tasklist 非法 / 建图失败 → ValueError（消息可直接面向用户，调用方映射
+    400）；目标解析失败**不 raise**——作为 ``hard_errors[0]`` 返回（消息与
+    module.py 的 KeyError 文案一致并附可用清单），``target``/``target_tick``
+    为 None。
+
+    返回 ``{"target": str | None, "target_tick": int | None,
+    "executed_nodes": [str], "hard_errors": [str], "warnings": [str]}``。
+    """
+    from .checkpoint import check_resume_compat, tasklist_from_dict
+
+    db_path = run_db_path(run_id, base_dir)
+    if not db_path.exists():
+        return None
+    try:
+        from tickflow.persistence import SqliteBackend
+
+        backend = SqliteBackend(db_path)
+        try:
+            hard_errors: list[str] = []
+            snap: dict[str, Any] | None = None
+            target_tick: int | None = None
+            ticks = backend.list_snapshots(run_id)
+            manual = [lbl for lbl, _ in backend.list_checkpoints(run_id)]
+            if not ticks and not manual:
+                hard_errors.append(f"无可恢复快照: {run_id}（运行未产生任何 tick 快照）")
+            elif isinstance(target, int) or (
+                isinstance(target, str) and target.isdigit()
+            ):
+                t = int(target)
+                if t in ticks:
+                    snap = backend.load_snapshot(run_id, t)
+                    if snap is None:
+                        hard_errors.append(f"快照 tick {t} 读取失败（数据损坏？）")
+                    else:
+                        target_tick = t
+                else:
+                    hard_errors.append(
+                        f"回退目标 {target!r} 不存在"
+                        f"（可用 tick: {ticks or '无'}；manual: {manual or '无'}）"
+                    )
+            elif isinstance(target, str) and target.startswith("manual:"):
+                snap = backend.load_checkpoint(run_id, target)
+                if snap is None:
+                    hard_errors.append(
+                        f"回退目标 {target!r} 不存在"
+                        f"（可用 tick: {ticks or '无'}；manual: {manual or '无'}）"
+                    )
+                else:
+                    target_tick = int(snap.get("tick", 0))
+            elif target is not None:
+                hard_errors.append(
+                    f"回退目标 {target!r} 不存在"
+                    f"（可用 tick: {ticks or '无'}；manual: {manual or '无'}）"
+                )
+            else:
+                if not ticks:
+                    hard_errors.append(
+                        f"无可恢复快照: {run_id}（运行未产生任何 tick 快照）"
+                    )
+                else:
+                    target_tick = max(ticks)
+                    snap = backend.load_snapshot(run_id, target_tick)
+                    if snap is None:
+                        hard_errors.append(
+                            f"快照 tick {target_tick} 读取失败（数据损坏？）"
+                        )
+
+            executed: set[str] = set()
+            if snap is not None:
+                executed = _executed_nodes(backend, run_id, int(snap.get("tick", 0)))
+        finally:
+            backend.close()
+    except Exception:
+        log.exception("读取 run.sqlite 失败（返回 None）: %s", db_path)
+        return None
+
+    if hard_errors:
+        return {"target": None, "target_tick": None, "executed_nodes": [],
+                "hard_errors": hard_errors, "warnings": []}
+
+    old_tl = None
+    old_inputs = read_module_inputs(run_id, base_dir=base_dir)
+    if old_inputs is not None:
+        old_tl = tasklist_from_dict(old_inputs["tasklist"])
+
+    try:
+        built = build_run_graph(module_name, run_id, base_dir=base_dir,
+                                tasklist=new_tasklist)
+    except ValueError:
+        raise
+    except Exception as e:
+        raise ValueError(f"预检建图失败: {e}") from e
+    if built is None:
+        raise ValueError("无 tasklist 可预检（无归档且未传 new_tasklist）")
+    graph, new_tl = built
+
+    marking = (snap or {}).get("marking") or {}
+    check = check_resume_compat(
+        new_tl, graph, executed,
+        old_tasklist=old_tl,
+        marking_slots=marking.get("slots"),
+        armed_starts=marking.get("armed_starts"),
+    )
+    target_str = target if isinstance(target, str) else (
+        str(target) if target is not None else str(target_tick))
+    return {
+        "target": target_str,
+        "target_tick": target_tick,
+        "executed_nodes": sorted(executed),
+        "hard_errors": list(check.hard_errors),
+        "warnings": list(check.warnings),
+    }
+
+
 def timeline_to_dict(timeline: ReviewTimeline) -> dict[str, Any]:
     """JSON 出口（MCP/Web 直接消费同一函数）。"""
     return {

{specmodule-0.1.3 → specmodule-0.1.4}/module_harness/registry.py

@@ -155,6 +155,15 @@ class HarnessRegistry(Registry):
 
     # ── 查询 ──────────────────────────────────────────────────────
 
+    @property
+    def llm_client(self) -> Any:
+        """注册表持有的 LLM 客户端（只读）。
+
+        供不经图独立调用 harness 的场景使用（如 ConsistencyReviewer
+        走 call_harness）。
+        """
+        return self._llm_client
+
     def is_harness(self, name: str) -> bool:
         """name 是否通过 harness() 注册。"""
         return name in self._harness_cfgs

{specmodule-0.1.3 → specmodule-0.1.4}/module_harness/status.py

@@ -25,7 +25,7 @@ class ModuleStatus:
     """Module 运行状态静态快照。"""
 
     module_id: str
-    phase: str                 # idle/translating/reviewing/building/ready/running/done/aborted/cancelled
+    phase: str                 # idle/translating/reviewing/building/ready/running/done/aborted/cancelled/truncated
     status: str | None = None  # tickflow RunStatus（"running"/"idle"/...；无 DB 时为 None）
     tick: int | None = None    # 最新快照 tick（无 DB 时为 None）
     fireable: list[str] = field(default_factory=list)

specmodule-0.1.4/module_harness/stream.py

@@ -0,0 +1,65 @@
+# module_harness/stream.py
+"""LLM 流式输出落盘——stream.log（跨进程流式观测通道）。
+
+Harness 每个LLM chunk 经 EventBus 发 ``LlmToken``，但 EventBus 是进程内的——
+独立消费进程（Web/TUI）看不到。本模块把流式事件序列化为 JSONL 追加写
+``.specmodule/runs/<run_id>/stream.log``（与 status.json/run.sqlite 同目录），
+跨进程可读。写失败仅 log 不抛（观测不阻断运行，同 _write_phase 哲学）。
+
+记录格式（``ts`` 由写入方统一打 wall-clock——harness 事件的 timestamp 是
+``time.monotonic()``，进程本地时钟，不落盘、不跨进程比较）::
+
+    {"type": "run_start",  "ts", "pid", "max_ticks"}
+    {"type": "call_start", "ts", "node", "model", "prompt_chars"}
+    {"type": "token",      "ts", "node", "chunk"}
+    {"type": "call_end",   "ts", "node", "content_chars", "finish_reason"}
+    {"type": "call_error", "ts", "node", "reason", "failure_type"}
+
+append-only：每次执行以 ``run_start`` 开边界，不截断旧执行（崩溃残留可事后
+查看）。不带 tick 字段——harness 事件恒为 tick=0，落盘假数据不如不写。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+__all__ = ["StreamLogWriter", "stream_log_path"]
+
+
+def stream_log_path(module_id: str, base_dir: Path | None = None) -> Path:
+    """``<base_dir>/.specmodule/runs/<module_id>/stream.log``。"""
+    return (base_dir or Path.cwd()) / ".specmodule" / "runs" / module_id / "stream.log"
+
+
+class StreamLogWriter:
+    """stream.log 追加写器：懒开句柄、逐记录 flush（无 fsync）、close 幂等。"""
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._fh: Any = None
+
+    def write(self, record: dict[str, Any]) -> None:
+        """单条 JSONL 记录落盘（ts 在此统一打 wall-clock）。失败仅 log。"""
+        record = {"ts": time.time(), **record}
+        try:
+            if self._fh is None:
+                self._path.parent.mkdir(parents=True, exist_ok=True)
+                self._fh = self._path.open("a", encoding="utf-8")
+            self._fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+            self._fh.flush()
+        except OSError:
+            log.exception("写 stream.log 失败（不阻断运行）: %s", self._path)
+
+    def close(self) -> None:
+        if self._fh is not None:
+            try:
+                self._fh.close()
+            except OSError:
+                log.exception("关闭 stream.log 失败: %s", self._path)
+            self._fh = None

{specmodule-0.1.3 → specmodule-0.1.4}/module_harness/submodule.py

@@ -175,8 +175,9 @@ class SubModule:
         - 事件投递与 records/persist 解耦：构造传入 event_bus 时事件始终投递
           （与 audit 取值无关）；未传则静默 EventBus.null()（嵌入零开销）。宿主
           需失败原因等现场反馈时，传 event_bus 选择性订阅即可，无需开启审计
-        - persist：False = 快速模式（NullBackend 全内存 + 无 status.json，
-          零落盘零 I/O）；None = 按 mode 决定（"fast" → False，否则 True）
+        - persist：False = 快速模式（NullBackend 全内存 + 无 status.json +
+          无 stream.log，零落盘零 I/O）；None = 按 mode 决定（"fast" → False，
+          否则 True）
         - llm_client/event_bus：覆盖实例级注入（宿主进程传入）；None 用实例值
         - hooks：runner hooks 透传（观察通道，与 Module hooks 同语义）
         """
@@ -204,6 +205,12 @@ class SubModule:
             keep_records=audit,
             persist=use_persist,
             status_file=use_persist,
+            # fast 模式 = 零残留模式：三个落盘通道（run.sqlite /
+            # status.json / stream.log）由 mode 一并关闭。stream_log 的
+            # 默认 True 是刻意的（CLI 拉起的子进程零接线即可流式观测），
+            # 故只在具名模式侧统一关——直接构造 Module 无"模式"概念，
+            # 每个通道由调用方逐个点名。
+            stream_log=use_persist,
             modules=self.modules,
             hooks=hooks,
         )

{specmodule-0.1.3 → specmodule-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specmodule"
-version = "0.1.3"
+version = "0.1.4"
 description = "可审计、可调试、可完全掌控的 LLM 使用框架（tickflow + llm + module_harness）"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -41,4 +41,12 @@ include = ["llm*", "module_harness*"]
 exclude = ["module_harness.tests*", "llm.tests*"]
 
 [tool.setuptools.package-data]
-module_harness = ["templates/builtin/*.json"]
+module_harness = ["templates/builtin/*.json"]
+
+[tool.pytest.ini_options]
+# smoke = 真实 LLM 冒烟（活 API 调用：慢、耗额度、非确定性 flake）。
+# 默认全量排除；要看时 pytest -m smoke 显式 opt-in（CLI 的 -m 覆盖 addopts）。
+markers = [
+    "smoke: 真实 LLM 冒烟测试（活 API 调用，非确定性；默认排除，pytest -m smoke 显式运行）",
+]
+addopts = "-m 'not smoke'"

{specmodule-0.1.3 → specmodule-0.1.4/specmodule.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specmodule
-Version: 0.1.3
+Version: 0.1.4
 Summary: 可审计、可调试、可完全掌控的 LLM 使用框架（tickflow + llm + module_harness）
 License: MIT
 Keywords: llm,workflow,petri-net,agent

{specmodule-0.1.3 → specmodule-0.1.4}/specmodule.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ llm/mock.py
 module_harness/__init__.py
 module_harness/align.py
 module_harness/builtins.py
+module_harness/call.py
 module_harness/checkpoint.py
 module_harness/cli.py
 module_harness/command.py
@@ -29,6 +30,7 @@ module_harness/scaffold.py
 module_harness/spec.py
 module_harness/status.py
 module_harness/store.py
+module_harness/stream.py
 module_harness/submodule.py
 module_harness/translator.py
 module_harness/templates/builtin/codereview.json