specmodule 0.1.2__tar.gz → 0.1.4__tar.gz

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

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

{specmodule-0.1.2 → 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.2 → specmodule-0.1.4}/module_harness/cli.py

@@ -12,6 +12,7 @@
     python -m module_harness.cli snapshot [<tick>] [--run-id xxx] [--json] [--out FILE]
     python -m module_harness.cli rollback <目标> --module <名> [--spec ...]
     python -m module_harness.cli checkpoint <label> [<tick>] [--run-id xxx]
+    python -m module_harness.cli cancel | pause | unpause [--run-id xxx]
     python -m module_harness.cli visualize --module <名> [--tasklist x.json | --run-id xxx] [--out FILE]
 
 场景归属：使用者层面（usage scenario）——第二级用户只写 spec/tasklist，
@@ -430,10 +431,21 @@ def _run_resume_cmd(args: argparse.Namespace, *, require_target: bool) -> int:
         _check_spec_schema(res, spec)
         llm_client = _build_llm_client(args.mock)
         template_name = args.template or res.default_template
+        tasklist = _load_tasklist(args.tasklist) if args.tasklist else None
         if args.tasklist:
             # tasklist 路径：跳过翻译，template_name 置 None（与 Module
             # "template/tasklist 二选一"不变量对齐）
             template_name = None
+        elif template_name is None and tasklist is None:
+            # 流程来源兜底：显式参数 > entry.default_template > module_inputs
+            # 归档 tasklist（续跑语义本该默认沿用原任务书——tasklist 通道
+            # 启动的 run 无模板可回落，此前只能靠显式 --tasklist 续跑）
+            from .query import read_module_inputs
+
+            archived = read_module_inputs(module_id)
+            if archived and archived.get("tasklist"):
+                tasklist = Tasklist.from_json(archived["tasklist"])
+                print("流程来源：沿用 module_inputs 归档 tasklist", file=sys.stderr)
         # 回退目标：显式直传；resume 缺省（None）由库解析为最新 tick 快照
         # （须在 Module 构造前检查——构造即写 status.json idle，会覆盖前次终态）
         rollback_to = args.rollback
@@ -469,7 +481,7 @@ def _run_resume_cmd(args: argparse.Namespace, *, require_target: bool) -> int:
             mod = res.entry.build_module(
                 spec,
                 template_name=template_name,
-                tasklist=_load_tasklist(args.tasklist) if args.tasklist else None,
+                tasklist=tasklist,
                 llm_client=llm_client,
                 module_id=module_id,
                 hooks=display.hooks(),
@@ -524,6 +536,29 @@ def _latest_run_id() -> str | None:
     return max(dirs, key=lambda d: d.stat().st_mtime).name
 
 
+def _cmd_control(args: argparse.Namespace) -> int:
+    """cancel/pause/unpause 共享实现：写控制文件（运行进程 tick 边界消费）。
+
+    纯数据操作（file 即通道），不接触运行进程；前置只校验目标 run 存在
+    （status.json 落盘）。生效时机取决于运行进程的下一 tick 边界。
+    """
+    from .control import request_control
+
+    module_id = args.run_id or _latest_run_id()
+    if module_id is None or not (
+        _persist_dir(module_id).parent / "status.json"
+    ).exists():
+        print(f"无运行记录: {module_id or '(无任何运行)'}", file=sys.stderr)
+        return 1
+    try:
+        request_control(module_id, args.command, reason=getattr(args, "reason", None))
+    except ValueError as e:
+        print(f"错误: {e}", file=sys.stderr)
+        return 1
+    print(f"已请求 {args.command}: {module_id}（运行进程将在下一 tick 边界生效）")
+    return 0
+
+
 def _cmd_init(args: argparse.Namespace) -> int:
     """生成模块脚手架：--as-dir 目录形态（pack 同构）或单文件形态 + 项目文件补齐。"""
     try:
@@ -1303,6 +1338,17 @@ def main(argv: list[str] | None = None) -> int:
     p_checkpoint.add_argument("--run-id", help="运行 id（默认最近运行）")
     p_checkpoint.set_defaults(func=_cmd_checkpoint)
 
+    for _name, _help in (
+        ("cancel", "请求取消运行（协作式：下一 tick 边界生效，phase→cancelled）"),
+        ("pause", "请求暂停运行（tick 边界挂起，tick 计数不前进）"),
+        ("unpause", "释放暂停，运行继续"),
+    ):
+        _p = sub.add_parser(_name, help=_help)
+        _p.add_argument("--run-id", help="运行 id（默认最近运行）")
+        if _name == "cancel":
+            _p.add_argument("--reason", help="取消原因（透传 runner.cancel）")
+        _p.set_defaults(func=_cmd_control)
+
     p_visualize = sub.add_parser(
         "visualize", help="渲染 tasklist 对应图（mermaid 导出）"
     )

{specmodule-0.1.2 → 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.4/module_harness/control.py

@@ -0,0 +1,175 @@
+# module_harness/control.py
+"""跨进程运行控制——控制文件协议（cancel/pause/unpause）。
+
+status.json 的反向通道：status.json 把运行状态带出运行进程，control.json
+把控制请求带进运行进程——文件即协议，任何消费端（CLI/Web/TUI）可写，
+运行进程在 tick 边界协作式消费。零依赖、不触碰运行状态的单写者规则
+（status.json 仍只由运行进程写）。
+
+协议：``.specmodule/runs/<run_id>/control.json``，单发一次性请求::
+
+    {"action": "cancel" | "pause" | "unpause", "reason": str|null,
+     "requested_at": float}
+
+- 写方：``request_control`` 原子写（tmp + os.replace，与 status.json 同款）。
+- 读方：``control_tick_start`` / ``control_tick_end`` 工厂返回 hook 回调，
+  由 Module 注册到 runner（``control=False`` 关闭）：
+  - **cancel 在 ``on_tick_end`` 消费**——引擎每个 tick 结束都会无条件重写
+    ``runner.status``（RUNNING/IDLE），tick_start 期设置的 CANCELLED 终态
+    会被同 tick 末尾的赋值冲掉；tick_end hook 在赋值之后运行，此刻
+    ``runner.cancel()`` 设置的终态能活到 ``run_until_idle`` 的下轮
+    terminal 检查，循环即停。请求写在 tick N 内 → N（或 N+1）末尾生效，
+    即取消有一 tick 延迟（当前 tick 内已开始的 firing 会跑完）。
+  - **pause 在 ``on_tick_start`` 挂起**——即将 fire 的 tick 不启动，tick
+    计数不前进（max_ticks 不消耗），轮询等待 unpause 或 cancel；挂起期间
+    保留文件（文件本身就是"暂停中"状态，监控方 ``read_control`` 可读）。
+    挂起中见到 cancel：不清除文件、直接放行——留给 tick_end 消费（同上
+    冲掉问题），当前 tick 跑完后停。
+- 消费即删（delete-on-consume）：动作执行后删除文件，防重放。
+- 新执行清场：``Module.run()/resume()`` 开始时 ``clear_control``——启动新
+  执行即作废陈旧请求（进程崩溃残留的 pause 不会拖住下一次运行）。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+__all__ = [
+    "ACTIONS",
+    "clear_control",
+    "control_path",
+    "control_tick_end",
+    "control_tick_start",
+    "read_control",
+    "request_control",
+]
+
+#: 合法控制动作。
+ACTIONS: tuple[str, ...] = ("cancel", "pause", "unpause")
+
+#: pause 挂起期间的轮询间隔（秒）。
+POLL_SECONDS = 0.5
+
+
+def control_path(module_id: str, base_dir: Path | None = None) -> Path:
+    """控制文件路径：``<base_dir>/.specmodule/runs/<run_id>/control.json``。"""
+    return (base_dir or Path.cwd()) / ".specmodule" / "runs" / module_id / "control.json"
+
+
+def read_control(module_id: str, base_dir: Path | None = None) -> dict[str, Any] | None:
+    """读当前控制请求；无请求 / 文件损坏 / action 非法 → None（容错读）。"""
+    path = control_path(module_id, base_dir)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        log.warning("control.json 损坏或不可读（忽略）: %s", path)
+        return None
+    if not isinstance(data, dict) or data.get("action") not in ACTIONS:
+        log.warning("control.json 内容非法（忽略）: %s", path)
+        return None
+    return data
+
+
+def request_control(
+    module_id: str,
+    action: str,
+    *,
+    reason: str | None = None,
+    base_dir: Path | None = None,
+) -> dict[str, Any]:
+    """写入控制请求（原子写）。action 非法 → ValueError。返回写入的请求。"""
+    if action not in ACTIONS:
+        raise ValueError(
+            f"未知控制动作: {action!r}（可用: {'/'.join(ACTIONS)}）"
+        )
+    req: dict[str, Any] = {
+        "action": action,
+        "reason": reason,
+        "requested_at": time.time(),
+    }
+    path = control_path(module_id, base_dir)
+    tmp = path.with_suffix(".json.tmp")
+    try:
+        tmp.parent.mkdir(parents=True, exist_ok=True)
+        tmp.write_text(json.dumps(req, ensure_ascii=False), encoding="utf-8")
+        os.replace(tmp, path)
+    except OSError:
+        log.exception("写 control.json 失败: %s", path)
+        raise
+    return req
+
+
+def clear_control(module_id: str, *, base_dir: Path | None = None) -> None:
+    """删除控制文件（消费/清场）。缺失不报错；删除失败仅 log。"""
+    try:
+        control_path(module_id, base_dir).unlink(missing_ok=True)
+    except OSError:
+        log.exception("删除 control.json 失败（忽略）")
+
+
+def control_tick_start(
+    runner: Any,
+    module_id: str,
+    *,
+    base_dir: Path | None = None,
+    poll: float = POLL_SECONDS,
+):
+    """工厂：注册到 ``runner.on_tick_start`` 的 async pause/unpause hook。
+
+    只处理 pause 挂起（cancel 统一由 ``control_tick_end`` 消费——见模块
+    docstring 的终态冲掉说明）。``runner`` 仅用于签名一致性（本 hook 不调
+    runner 方法）；由 Module 在构建 runner 后注册。
+    """
+    async def _on_tick_start(tick: int, fireable: list[str]) -> None:
+        req = read_control(module_id, base_dir=base_dir)
+        if req is None or req["action"] == "cancel":
+            # cancel 留给 tick_end（不清文件）；无请求直接放行
+            return
+        if req["action"] != "pause":
+            return
+        # pause：tick 边界挂起；文件保留 = "暂停中"状态（监控方 read_control 可读）
+        while True:
+            await asyncio.sleep(poll)
+            nxt = read_control(module_id, base_dir=base_dir)
+            if nxt is None:
+                # 挂起期间文件被外部删除（人工清理）→ 视为释放
+                return
+            if nxt["action"] == "cancel":
+                # 不清除、直接放行——tick_end 消费（终态不被本 tick 冲掉）
+                return
+            if nxt["action"] == "unpause":
+                clear_control(module_id, base_dir=base_dir)
+                return
+
+    return _on_tick_start
+
+
+def control_tick_end(
+    runner: Any,
+    module_id: str,
+    *,
+    base_dir: Path | None = None,
+):
+    """工厂：注册到 ``runner.on_tick_end`` 的 cancel 消费 hook。
+
+    在引擎每 tick 末尾的状态赋值**之后**运行——此刻 ``runner.cancel()``
+    设置的 CANCELLED 能活到 ``run_until_idle`` 下轮 terminal 检查。
+    """
+    async def _on_tick_end(tick: int, firings: list) -> None:
+        req = read_control(module_id, base_dir=base_dir)
+        if req is None or req["action"] != "cancel":
+            return
+        runner.cancel(req.get("reason") or "cancelled")
+        clear_control(module_id, base_dir=base_dir)
+
+    return _on_tick_end

{specmodule-0.1.2 → 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,6 +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__)
 
@@ -72,6 +82,11 @@ class Module:
         keep_records: bool = True,
         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:
@@ -88,6 +103,14 @@ class Module:
         # True（默认）：写 .specmodule/runs/<module_id>/status.json
         # （阶段级，跨进程查询通道）；False：零残留（快速模式可用）
         self.status_file = status_file
+        # 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()
@@ -123,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
@@ -215,6 +238,17 @@ class Module:
                 _register(_cb)
             else:
                 log.warning("Module hooks: 未知 runner hook '%s'（忽略）", _hook_name)
+        if self.control:
+            # 跨进程控制通道（control.json → cancel/pause）：与用户 hooks
+            # 并存——runner 的 hook 注册表是 list，追加不覆盖。cancel 在
+            # tick_end 消费（tick_start 期设终态会被引擎同 tick 赋值冲掉）、
+            # pause 在 tick_start 挂起，见 control.py 模块 docstring。
+            runner.on_tick_start(
+                control_tick_start(runner, self.module_id, base_dir=self._base_dir)
+            )
+            runner.on_tick_end(
+                control_tick_end(runner, self.module_id, base_dir=self._base_dir)
+            )
         return runner
 
     # ------------------------------------------------------------------
@@ -337,19 +371,71 @@ class Module:
 
     async def _run_with_phases(self, runner: AsyncRunner, max_ticks: int) -> list:
         """归档本次输入 → 运行 → 按结果映射终态 phase（run/resume 共用）。"""
-        self._archive_module_inputs()
-        self._write_phase("running")
+        if self.control:
+            # 新执行清场：作废陈旧控制请求（崩溃残留的 pause 不拖住新执行）。
+            # 位于写 running phase 之前——监控方看到 running 才放开控制按钮，
+            # 此时清场已完成，清场与首请求的竞态窗口关闭。
+            clear_control(self.module_id, base_dir=self._base_dir)
+        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 对比源）。
@@ -366,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:
@@ -376,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")
 
@@ -413,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.2 → 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)
@@ -296,6 +358,163 @@ def load_snapshot_summary(
     return out
 
 
+def read_module_inputs(
+    module_id: str, base_dir: Path | None = None
+) -> dict[str, Any] | None:
+    """读运行输入存档（module_inputs 表：本次 run 使用的 spec/tasklist）。
+
+    消费场景：resume/rollback 前端预填上次输入（换 spec/tasklist 重传的
+    编辑起点）。db 缺失 / 无存档 / 读失败 → None（查询容错，同上）。
+    """
+    db_path = run_db_path(module_id, base_dir)
+    if not db_path.exists():
+        return None
+    from .checkpoint import ModuleInputStore
+
+    store = ModuleInputStore(module_id, base_dir)
+    try:
+        return store.load_module_inputs()
+    except Exception:
+        log.exception("读取 module_inputs 失败（返回 None）: %s", db_path)
+        return None
+    finally:
+        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.2 → 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.2 → 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.2 → 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.2 → specmodule-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specmodule"
-version = "0.1.2"
+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.2 → specmodule-0.1.4/specmodule.egg-info}/PKG-INFO

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

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

@@ -8,11 +8,13 @@ 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
 module_harness/config.py
 module_harness/consistency.py
+module_harness/control.py
 module_harness/entry.py
 module_harness/events.py
 module_harness/feed.py
@@ -28,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