specmodule 0.4.0__tar.gz → 0.5.0__tar.gz

{specmodule-0.4.0/specmodule.egg-info → specmodule-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specmodule
-Version: 0.4.0
+Version: 0.5.0
 Summary: 可审计、可调试、可完全掌控的 LLM 使用框架（tickflow + llm + module_harness）
 License: MIT
 Keywords: llm,workflow,petri-net,agent
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: tickflow-py<0.3,>=0.2.0
+Requires-Dist: tickflow-py<0.4,>=0.3.0
 Provides-Extra: anthropic
 Requires-Dist: anthropic; extra == "anthropic"
 Provides-Extra: openai

{specmodule-0.4.0 → specmodule-0.5.0}/module_harness/core/call.py

@@ -24,6 +24,7 @@ class HarnessCallResult:
     """独立调用结果：校验后输出 + LLM 原始输出 + token 用量。
 
     图像模式不产生文本 raw（无 _llm_raw），raw 为 None。
+    validate_retries > 0 时：usage 为各次尝试之和；raw 为最后一次尝试的原始输出。
     """
 
     value: Any  # 校验后的输出（json_object → 解析值；text → str）
@@ -67,8 +68,13 @@ async def call_harness(
     OutputValidated / ...），不传零开销（EventBus.null()）。
 
     失败（LLM 错误 / 输出校验不通过）抛 HarnessCallError，携带 failure 与
-    渲染 prompt / 原始输出 / usage 诊断链。task 层没有"下游跳过"概念，
-    Failure 一律翻译为异常；promptmode 缺 key → KeyError 原样冒出。
+    渲染 prompt / 原始输出 / usage 诊断链。``validate_retries > 0`` 时校验
+    失败在 body 内带反馈重问：``prompt`` 为最后一次尝试的实际 prompt（含
+    反馈段）、``raw`` 为最后一次原始输出、``usage`` 为各次尝试之和。LLM
+    错误路径：``prompt`` 仍为出错尝试的实际 prompt，``raw``/``usage`` 为
+    最后一次有输出的尝试（出错尝试无输出，错误本身见 failure.error）。task
+    层没有"下游跳过"概念，Failure 一律翻译为异常；promptmode 缺 key →
+    KeyError 原样冒出。
     """
     bus = event_bus or EventBus.null()
     body = Harness(config, llm_client, bus).build_body(

{specmodule-0.4.0 → specmodule-0.5.0}/module_harness/core/config.py

@@ -32,6 +32,15 @@ class HarnessConfig:
     notdo: list[str] = field(default_factory=list)
     """否定性约束列表，拼入 system prompt。"""
 
+    validate_retries: int = 0
+    """输出校验失败时的额外重试次数（带校验错误反馈重问）。
+
+    0（缺省）= 不重试，行为与无此字段时逐字节一致。
+    N > 0 = 校验失败后最多再问 N 次，每次 prompt 追加校验错误反馈段；
+    预算耗尽返回最后一次的 Failure(type="llm")。
+    仅作用于输出校验失败；LLMError（传输层）不重试、不消耗预算。
+    """
+
     # ── LLM 参数（Task 可逐项覆盖）──
     model: str | None = None
     temperature: float | None = None
@@ -66,6 +75,14 @@ class HarnessConfig:
             )
         if self.mode == "image" and self.image_dir is None:
             raise ValueError("mode='image' 不接受显式 null 的 image_dir")
+        if isinstance(self.validate_retries, bool) or not isinstance(self.validate_retries, int):
+            raise ValueError(
+                f"validate_retries 须为 int，得到 {type(self.validate_retries).__name__}"
+            )
+        if self.validate_retries < 0:
+            raise ValueError(f"validate_retries 须 >= 0，得到 {self.validate_retries!r}")
+        if self.validate_retries > 0 and self.mode == "image":
+            raise ValueError("mode='image' 无文本输出格式可校验，validate_retries 须为 0")
 
     def to_dict(self) -> dict[str, Any]:
         """序列化为 JSON 可写 dict（含 output_format）。"""
@@ -96,6 +113,7 @@ class HarnessConfig:
         - mode          → 调用形态："text"（默认）| "image"
         - image_size    → 图像尺寸（仅 mode="image"）
         - image_dir     → 图像落盘目录（仅 mode="image"）
+        - validate_retries → 校验失败重试预算（int ≥ 0，缺省 0）
 
         mode/image_size/image_dir：显式 null 的 image_dir 会被拒绝。
         """
@@ -120,4 +138,5 @@ class HarnessConfig:
             mode=task.get("mode", "text"),
             image_size=task.get("image_size"),
             image_dir=task.get("image_dir", "images"),
+            validate_retries=task.get("validate_retries", 0),
         )

{specmodule-0.4.0 → specmodule-0.5.0}/module_harness/core/harness.py

@@ -26,6 +26,13 @@ from ..infra.events import (
 )
 
 
+# 校验失败反馈段（框架契约文案）：重试时追加到原渲染 prompt 末尾重问
+_VALIDATION_FEEDBACK = (
+    "\n\n上一次输出未通过校验：{error}\n"
+    "请修正该问题后重新输出完整结果，不要复述错误内容，不要解释修改过程。"
+)
+
+
 class Harness:
     """持有 HarnessConfig + LLM 客户端 + EventBus。
 
@@ -151,16 +158,22 @@ class Harness:
                 rendered=rendered,
             ))
 
-            # 2. 调用 LLM
-            bus.emit(LlmCallStarted(
-                timestamp=time.monotonic(), node=node, tick=0,
-                model=config.model or "default",
-                prompt_chars=len(rendered),
-            ))
-
+            # 2. 调用 LLM（image 单次；text 带校验重试循环）
             if config.mode == "image":
+                bus.emit(LlmCallStarted(
+                    timestamp=time.monotonic(), node=node, tick=0,
+                    model=config.model or "default",
+                    prompt_chars=len(rendered),
+                ))
                 return await _run_image(view, rendered, state)
 
+            budget = config.validate_retries
+            retrying = budget > 0
+            attempt_prompt = rendered
+            usage_acc: dict[str, int] = {}
+            attempts = 0
+            retry_errors: list[str] = []
+
             def on_token(chunk: str) -> None:
                 bus.emit(LlmToken(
                     timestamp=time.monotonic(), node=node, tick=0,
@@ -173,63 +186,92 @@ class Harness:
                     chunk=chunk,
                 ))
 
-            try:
-                from llm.client import LLMError
+            while True:
+                attempts += 1
+                bus.emit(LlmCallStarted(
+                    timestamp=time.monotonic(), node=node, tick=0,
+                    model=config.model or "default",
+                    prompt_chars=len(attempt_prompt),
+                ))
 
-                # notdo 由 LLM client 内部通过 _build_system() 拼入 system prompt
-                response = await llm.complete(
-                    prompt=rendered,
-                    model=config.model,
-                    temperature=config.temperature,
-                    think=config.think,
-                    output_format=dataclasses.asdict(config.output_format) if config.output_format else None,
-                    notdo=config.notdo if config.notdo else None,
-                    on_token=on_token,
-                    on_thinking=on_thinking,
-                    api_params=config.api_params if config.api_params else None,
-                )
-            except LLMError as e:
+                try:
+                    from llm.client import LLMError
+
+                    # notdo 由 LLM client 内部通过 _build_system() 拼入 system prompt
+                    response = await llm.complete(
+                        prompt=attempt_prompt,
+                        model=config.model,
+                        temperature=config.temperature,
+                        think=config.think,
+                        output_format=dataclasses.asdict(config.output_format) if config.output_format else None,
+                        notdo=config.notdo if config.notdo else None,
+                        on_token=on_token,
+                        on_thinking=on_thinking,
+                        api_params=config.api_params if config.api_params else None,
+                    )
+                except LLMError as e:
+                    # 传输层失败不重试（SDK max_retries 已管）、不消耗校验重试预算
+                    if state is not None:
+                        state["_llm_error"] = str(e)
+                    bus.emit(HarnessFailed(
+                        timestamp=time.monotonic(), node=node, tick=0,
+                        reason=str(e),
+                        failure_type="infrastructure",
+                    ))
+                    return Failure(str(e), type="infrastructure")
+
+                # LLM 原始响应 + usage 写入节点状态（审计链：NodeState.mutable_state）；
+                # 重试开启时 usage 累计、_validation_attempts 记实际调用次数
                 if state is not None:
-                    state["_llm_error"] = str(e)
-                bus.emit(HarnessFailed(
+                    state["_llm_raw"] = response.content
+                    usage_acc = _merge_usage(usage_acc, response.usage)
+                    state["_usage"] = dict(usage_acc)
+                    if retrying:
+                        state["_validation_attempts"] = attempts
+
+                # 3. 校验输出
+                bus.emit(LlmCallCompleted(
                     timestamp=time.monotonic(), node=node, tick=0,
-                    reason=str(e),
-                    failure_type="infrastructure",
+                    content_chars=len(response.content),
+                    usage=response.usage,
+                    finish_reason=response.finish_reason,
                 ))
-                return Failure(str(e), type="infrastructure")
 
-            # 3. LLM 原始响应 + usage 写入节点状态（审计链：NodeState.mutable_state）
-            if state is not None:
-                state["_llm_raw"] = response.content
-                state["_usage"] = dict(response.usage)
-
-            # 3. 校验输出
-            bus.emit(LlmCallCompleted(
-                timestamp=time.monotonic(), node=node, tick=0,
-                content_chars=len(response.content),
-                usage=response.usage,
-                finish_reason=response.finish_reason,
-            ))
+                if validator is None:
+                    return response.content
 
-            if validator is not None:
                 result = validator.validate(response.content)
-                if isinstance(result, Failure):
+                if not isinstance(result, Failure):
                     bus.emit(OutputValidated(
                         timestamp=time.monotonic(), node=node, tick=0,
-                        passed=False,
-                        extracted=False,
-                        error=result.error,
+                        passed=True,
+                        extracted=_was_extracted(response.content, result),
+                        error=None,
                     ))
                     return result
+
                 bus.emit(OutputValidated(
                     timestamp=time.monotonic(), node=node, tick=0,
-                    passed=True,
-                    extracted=_was_extracted(response.content, result),
-                    error=None,
+                    passed=False,
+                    extracted=False,
+                    error=result.error,
                 ))
-                return result
 
-            return response.content
+                if budget <= 0:
+                    return result  # 预算耗尽：最后一次的 Failure(type="llm")
+
+                # 带反馈重问：prompt 追加校验错误反馈段，LLM 参数原样保留
+                budget -= 1
+                retry_errors.append(result.error)
+                if state is not None:
+                    state["_validation_retry_errors"] = list(retry_errors)
+                attempt_prompt = rendered + _VALIDATION_FEEDBACK.format(error=result.error)
+                if state is not None:
+                    state["_prompt"] = attempt_prompt
+                bus.emit(PromptRendered(
+                    timestamp=time.monotonic(), node=node, tick=0,
+                    rendered=attempt_prompt,
+                ))
 
         return body
 
@@ -239,3 +281,15 @@ def _was_extracted(raw: str, result: Any) -> bool:
     if not isinstance(result, str):
         return True  # JSON 解析必然是提取
     return raw.strip() != result.strip()
+
+
+def _merge_usage(acc: dict[str, int], new: dict[str, int]) -> dict[str, int]:
+    """累计多次尝试的 token 用量：数值键求和，单侧缺键取另一侧。"""
+    merged = dict(acc)
+    for key, val in new.items():
+        prev = merged.get(key)
+        if isinstance(prev, int) and isinstance(val, int):
+            merged[key] = prev + val
+        else:
+            merged[key] = val
+    return merged

{specmodule-0.4.0 → specmodule-0.5.0}/module_harness/infra/query.py

@@ -768,6 +768,31 @@ def timeline_to_dict(timeline: ReviewTimeline) -> dict[str, Any]:
     }
 
 
+def node_run_summary(module_id: str, base_dir: Path | None = None) -> dict[str, dict[str, Any]] | None:
+    """按节点累计运行摘要：``{node: {fired_count, last_status, last_tick}}``。
+
+    firings 表全量累计（去重语义与 build_timeline 一致，append 序即 tick 序，
+    末条即最新状态）；未执行节点不在表内，消费方按全节点集叠加 0/None。
+    监控面共用组合（Web 图叠加 + WS status 推送）：推送携带累计结构，客户端
+    纯覆盖即可，无需逐 tick 增量记账（轮询跳拍/断线重连不丢状态）。
+    db 缺失 / 读失败 → None（查询容错）。
+    """
+    tl = build_timeline(module_id, base_dir=base_dir)
+    if tl is None:
+        return None
+    by_node: dict[str, list[ReviewEntry]] = {}
+    for e in tl.entries:
+        by_node.setdefault(e.node, []).append(e)
+    return {
+        node: {
+            "fired_count": len(entries),
+            "last_status": entries[-1].status,
+            "last_tick": entries[-1].tick,
+        }
+        for node, entries in by_node.items()
+    }
+
+
 @dataclass
 class QueryValueResult:
     """细粒度查询结果：tick + 命中值 / 未命中时的可用键（MCP peek 用）。"""

{specmodule-0.4.0 → specmodule-0.5.0}/module_harness/model/module.py

@@ -483,7 +483,19 @@ class Module:
             self._write_phase("cancelled", error=runner.cancel_reason or "cancelled")
             return "cancelled"
         elif runner.status == RunStatus.FAILED:
-            self._write_phase("aborted", error="all nodes failed")
+            # tickflow 0.3：FAILED = 饿死（有 pending 槽位/未触发 start 但无
+            # 可激发节点）。未点火清单由点火历史推导（firings_of 非空 = 点过
+            # 火；勿用 last_output——输出为 None 的已点火节点会误判，也勿用
+            # audit_log——keep_records=False 时为空表）。
+            fired = {
+                n for n in runner.graph.nodes if runner.run_state.firings_of(n)
+            }
+            unfired = sorted(set(runner.graph.nodes) - fired)
+            self._write_phase(
+                "aborted",
+                error="starved: work pending but nothing fireable; unfired: "
+                      + (", ".join(unfired) if unfired else "(none)"),
+            )
             return "aborted"
         elif runner.status == RunStatus.RUNNING:
             # max_ticks 耗尽（pause 挂起发生在 run_until_idle 内部不返回，

{specmodule-0.4.0 → specmodule-0.5.0}/module_harness/model/spec.py

@@ -65,6 +65,7 @@ class TaskDefinition:
     mode: str | None = None             # "image" = 图像生成节点
     image_size: str | None = None       # 图像尺寸覆盖
     image_dir: str | None = None        # 图像落盘目录覆盖
+    validate_retries: int | None = None  # 校验失败重试预算覆盖（None = 沿用注册 config）
     inputs: dict[str, str] | None = None
 
     @classmethod
@@ -89,6 +90,7 @@ class TaskDefinition:
             mode=d.get("mode"),
             image_size=d.get("image_size"),
             image_dir=d.get("image_dir"),
+            validate_retries=d.get("validate_retries"),
             inputs=d.get("inputs"),
         )
 

{specmodule-0.4.0 → specmodule-0.5.0}/module_harness/model/submodule.py

@@ -1,283 +1,285 @@
-# module_harness/submodule.py
-"""SubModule — 类式 submodule 定义 + 嵌入/完整运行 + pack 导出。"""
-
-from __future__ import annotations
-
-import inspect
-import json
-import textwrap
-import uuid
-from dataclasses import asdict
-from pathlib import Path
-from typing import Any, Callable, Literal
-
-from llm import LLMConfig, create_llm_client
-
-from ..core.builtins import register_builtin_harnesses
-from ..cli.command import CommandConfig
-from ..core.config import HarnessConfig
-from ..infra.events import EventBus
-from .module import Module
-from ..core.registry import HarnessRegistry
-from .spec import SpecSchema, SpecValidationError, Tasklist
-
-
-def script(name: str):
-    """类内 script 标记装饰器：标记函数，__init_subclass__ 时收集。
-
-    脚本是类体内普通函数（不绑定 self），与 @reg.script 语义一致。
-    注册名必须与函数名一致（函数名 = 注册名 = 打包文件名）。
-    """
-
-    def deco(fn: Callable) -> Callable:
-        if name != fn.__name__:
-            raise ValueError(
-                f"script 注册名 '{name}' 与函数名 '{fn.__name__}' 不一致"
-            )
-        fn._submodule_script_name = name  # type: ignore[attr-defined]
-        return fn
-
-    return deco
-
-
-class SubModule:
-    """类式 submodule 定义。类属性 = 注册信息，@script 收集脚本。
-
-    run() 内部组合 Module：注册 provides → 构造 Module → 运行。
-    pack() 导出发布目录（module.json + harnesses/ + scripts/ + commands/）。
-    """
-
-    name: str = ""
-    version: str = "0.1.0"
-    description: str = ""
-    spec_schema: SpecSchema = SpecSchema()
-    default_spec: dict[str, Any] | None = None
-    harnesses: list[HarnessConfig] = []
-    commands: list[CommandConfig] = []
-    requires: list[str] = []
-    guards: list[tuple[str, Callable]] = []   # [(名字, 函数)]，名字 = 注册名 = 打包文件名
-    modules: dict[str, type["SubModule"]] = {}  # submodule 节点引用表 {tasklist 名: 类}
-    tasklist: Tasklist | None = None
-    mode: Literal["persist", "fast"] = "persist"
-    # 发布者声明轻量特性："fast" = 快速模式（NullBackend 全内存，零落盘零 I/O，
-    # D11）；默认 "persist" 落盘到 .specmodule/runs/<run_id>/（D9）。
-    _scripts: dict[str, Callable] = {}
-
-    def __init_subclass__(cls, **kwargs: Any) -> None:
-        super().__init_subclass__(**kwargs)
-        inherited = dict(getattr(cls, "_scripts", {}))
-        collected = {
-            n: fn for n, fn in cls.__dict__.items()
-            if callable(fn) and getattr(fn, "_submodule_script_name", None)
-        }
-        cls._scripts = inherited
-        cls._scripts.update(collected)
-        # 列表类属性按子类复制，防止子类就地修改污染父类注册
-        for attr in ("harnesses", "commands", "requires", "guards"):
-            if attr not in cls.__dict__:
-                setattr(cls, attr, list(getattr(cls, attr)))
-        # dict 类属性同理由：按子类复制，防止子类就地修改污染父类注册
-        if "modules" not in cls.__dict__:
-            setattr(cls, "modules", dict(getattr(cls, "modules")))
-
-    def __init__(
-        self,
-        llm_client: Any = None,
-        event_bus: EventBus | None = None,
-    ) -> None:
-        self._llm_client = llm_client
-        self._event_bus = event_bus
-
-    def _ensure_client(self) -> Any:
-        """直接类使用（未注入 client）时从 env 懒创建。"""
-        if self._llm_client is None:
-            self._llm_client = create_llm_client(LLMConfig.from_env())
-        return self._llm_client
-
-    def _module_id(self) -> str:
-        return f"{self.name}_{uuid.uuid4().hex[:6]}"
-
-    def _build_registry(
-        self,
-        audit: bool,
-        harness_overrides: dict[str, Any] | None = None,
-        *,
-        llm_client: Any = None,
-        event_bus: EventBus | None = None,
-    ) -> HarnessRegistry:
-        # 事件投递与 keep_records/persist 解耦：宿主传了 event_bus 就始终投递
-        # （与 audit 无关）；未传则静默 EventBus.null()（嵌入零开销）。audit 只
-        # 在 run() 里映射 keep_records。
-        bus = event_bus if event_bus is not None else (self._event_bus or EventBus.null())
-        client = llm_client if llm_client is not None else self._ensure_client()
-        reg = HarnessRegistry(llm_client=client, event_bus=bus)
-        for hc in self.harnesses:
-            if not hc.name:
-                raise ValueError(f"harnesses 配置缺少 name: {hc}")
-            cfg = (
-                self._apply_harness_overrides(hc, harness_overrides)
-                if harness_overrides else hc
-            )
-            reg.harness(cfg.name, cfg)
-        for cc in self.commands:
-            if not cc.name:
-                raise ValueError(f"commands 配置缺少 name: {cc}")
-            reg.command(cc.name, cc)
-        for sname, fn in self._scripts.items():
-            reg.script(sname)(fn)
-        for gname, gfn in self.guards:
-            reg.guard(gname, gfn)
-        register_builtin_harnesses(reg)
-        return reg
-
-    @staticmethod
-    def _apply_harness_overrides(
-        hc: HarnessConfig, overrides: dict[str, Any]
-    ) -> HarnessConfig:
-        """批量应用 LLM 覆盖（model/temperature/think/api_params）到单个 harness。"""
-        api_params = dict(hc.api_params)
-        if overrides.get("api_params"):
-            api_params.update(overrides["api_params"])
-        return HarnessConfig(
-            name=hc.name,
-            prompt_core=hc.prompt_core,
-            prompt_modes=dict(hc.prompt_modes),
-            output_format=hc.output_format,
-            notdo=list(hc.notdo),
-            model=overrides.get("model", hc.model),
-            temperature=overrides.get("temperature", hc.temperature),
-            think=overrides.get("think", hc.think),
-            api_params=api_params,
-            # 调用形态三字段原样携带——漏掉会让 image 模式在覆盖时静默降级为 text
-            mode=hc.mode,
-            image_size=hc.image_size,
-            image_dir=hc.image_dir,
-        )
-
-    async def run(
-        self,
-        spec: dict[str, Any],
-        *,
-        tasklist: Tasklist | dict[str, Any] | None = None,
-        audit: bool = False,
-        max_ticks: int = 100,
-        harness_overrides: dict[str, Any] | None = None,
-        persist: bool | None = None,
-        llm_client: Any = None,
-        event_bus: EventBus | None = None,
-        hooks: dict | None = None,
-    ) -> list[Any]:
-        """执行 submodule。
-
-        - tasklist=None：用自身固定 tasklist，不触发一致性审核（发布前已验证）
-        - 传入自定义 tasklist：与 Module 一致，校验 + 一致性审核
-        - harness_overrides：{model/temperature/think/api_params} 覆盖，
-          构建 registry 时应用到 submodule 自身的全部 harness（不含内置
-          harness）（submodule 节点 LLM 配置传播）
-        - audit=False（默认）：嵌入模式，keep_records=False；除非 mode="fast"，
-          嵌入模式同样落盘（D11）
-        - audit=True：keep_records 全开（全量审计轨迹）
-        - 事件投递与 records/persist 解耦：构造传入 event_bus 时事件始终投递
-          （与 audit 取值无关）；未传则静默 EventBus.null()（嵌入零开销）。宿主
-          需失败原因等现场反馈时，传 event_bus 选择性订阅即可，无需开启审计
-        - persist：False = 快速模式（NullBackend 全内存 + 无 status.json +
-          无 stream.log，零落盘零 I/O）；None = 按 mode 决定（"fast" → False，
-          否则 True）
-        - llm_client/event_bus：覆盖实例级注入（宿主进程传入）；None 用实例值
-        - hooks：runner hooks 透传（观察通道，与 Module hooks 同语义）
-        """
-        errors = self.spec_schema.validate(spec)
-        if errors:
-            raise SpecValidationError(errors)
-        if self.tasklist is None and tasklist is None:
-            raise ValueError(f"submodule '{self.name}' 未定义 tasklist")
-        use_tasklist = self.tasklist if tasklist is None else tasklist
-        if isinstance(use_tasklist, dict):
-            use_tasklist = Tasklist.from_json(use_tasklist)
-        review = None if tasklist is None else "spec_tasklist_review"
-        use_persist = persist if persist is not None else (self.mode != "fast")
-        use_client = llm_client if llm_client is not None else self._ensure_client()
-        use_bus = event_bus if event_bus is not None else self._event_bus
-        reg = self._build_registry(audit, harness_overrides, llm_client=use_client, event_bus=use_bus)
-        module = Module(
-            spec=spec,
-            tasklist=use_tasklist,
-            llm_client=use_client,
-            event_bus=use_bus,
-            module_id=self._module_id(),
-            module=self.name,  # 溯源：status.json "module" 键（与 entry 路径一致）
-            registry=reg,
-            review_harness=review,
-            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,
-        )
-        return await module.run(max_ticks=max_ticks)
-
-    def pack(self, out_dir: str | Path) -> Path:
-        """导出发布目录：module.json + harnesses/ + scripts/ + commands/。
-
-        scripts/*.py = 函数源码 + 必要 import（含 @script 装饰器行），
-        加载时 exec 后按函数名取注册，pack/load round-trip 无签名改写。
-        """
-        if not self.name:
-            raise ValueError("submodule 缺少 name，无法打包")
-        if self.tasklist is None:
-            raise ValueError(f"submodule '{self.name}' 未定义 tasklist，无法打包")
-        p = Path(out_dir)
-        (p / "harnesses").mkdir(parents=True, exist_ok=True)
-        (p / "scripts").mkdir(exist_ok=True)
-        (p / "commands").mkdir(exist_ok=True)
-        (p / "guards").mkdir(exist_ok=True)
-        (p / "submodules").mkdir(exist_ok=True)
-        manifest = {
-            "name": self.name,
-            "version": self.version,
-            "description": self.description,
-            "submodule": True,
-            "spec_schema": asdict(self.spec_schema),
-            "requires": list(self.requires),
-            "modules": list(self.modules),
-            "tasklist": self.tasklist.to_dict(),
-        }
-        if self.default_spec is not None:
-            manifest["default_spec"] = dict(self.default_spec)
-        (p / "module.json").write_text(
-            json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8"
-        )
-        for hc in self.harnesses:
-            if not hc.name:
-                raise ValueError(f"harnesses 配置缺少 name: {hc}")
-            (p / "harnesses" / f"{hc.name}.json").write_text(
-                json.dumps(hc.to_dict(), ensure_ascii=False, indent=2), encoding="utf-8"
-            )
-        for cc in self.commands:
-            if not cc.name:
-                raise ValueError(f"commands 配置缺少 name: {cc}")
-            (p / "commands" / f"{cc.name}.json").write_text(
-                json.dumps(cc.to_dict(), ensure_ascii=False, indent=2), encoding="utf-8"
-            )
-        for sname, fn in self._scripts.items():
-            src = textwrap.dedent(inspect.getsource(fn))
-            header = "from __future__ import annotations\nfrom module_harness.model.submodule import script\n\n"
-            (p / "scripts" / f"{sname}.py").write_text(header + src, encoding="utf-8")
-        for gname, gfn in self.guards:
-            if gname != gfn.__name__:
-                raise ValueError(
-                    f"guard 注册名 '{gname}' 与函数名 '{gfn.__name__}' 不一致"
-                    "（注册名 = 打包文件名 = 加载键，与 @script 同约定）"
-                )
-            src = textwrap.dedent(inspect.getsource(gfn))
-            header = "from __future__ import annotations\n\n"
-            (p / "guards" / f"{gname}.py").write_text(header + src, encoding="utf-8")
-        for mname, mcls in self.modules.items():
-            mcls().pack(p / "submodules" / mname)
-        return p
+# module_harness/submodule.py
+"""SubModule — 类式 submodule 定义 + 嵌入/完整运行 + pack 导出。"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import textwrap
+import uuid
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any, Callable, Literal
+
+from llm import LLMConfig, create_llm_client
+
+from ..core.builtins import register_builtin_harnesses
+from ..cli.command import CommandConfig
+from ..core.config import HarnessConfig
+from ..infra.events import EventBus
+from .module import Module
+from ..core.registry import HarnessRegistry
+from .spec import SpecSchema, SpecValidationError, Tasklist
+
+
+def script(name: str):
+    """类内 script 标记装饰器：标记函数，__init_subclass__ 时收集。
+
+    脚本是类体内普通函数（不绑定 self），与 @reg.script 语义一致。
+    注册名必须与函数名一致（函数名 = 注册名 = 打包文件名）。
+    """
+
+    def deco(fn: Callable) -> Callable:
+        if name != fn.__name__:
+            raise ValueError(
+                f"script 注册名 '{name}' 与函数名 '{fn.__name__}' 不一致"
+            )
+        fn._submodule_script_name = name  # type: ignore[attr-defined]
+        return fn
+
+    return deco
+
+
+class SubModule:
+    """类式 submodule 定义。类属性 = 注册信息，@script 收集脚本。
+
+    run() 内部组合 Module：注册 provides → 构造 Module → 运行。
+    pack() 导出发布目录（module.json + harnesses/ + scripts/ + commands/）。
+    """
+
+    name: str = ""
+    version: str = "0.1.0"
+    description: str = ""
+    spec_schema: SpecSchema = SpecSchema()
+    default_spec: dict[str, Any] | None = None
+    harnesses: list[HarnessConfig] = []
+    commands: list[CommandConfig] = []
+    requires: list[str] = []
+    guards: list[tuple[str, Callable]] = []   # [(名字, 函数)]，名字 = 注册名 = 打包文件名
+    modules: dict[str, type["SubModule"]] = {}  # submodule 节点引用表 {tasklist 名: 类}
+    tasklist: Tasklist | None = None
+    mode: Literal["persist", "fast"] = "persist"
+    # 发布者声明轻量特性："fast" = 快速模式（NullBackend 全内存，零落盘零 I/O，
+    # D11）；默认 "persist" 落盘到 .specmodule/runs/<run_id>/（D9）。
+    _scripts: dict[str, Callable] = {}
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        inherited = dict(getattr(cls, "_scripts", {}))
+        collected = {
+            n: fn for n, fn in cls.__dict__.items()
+            if callable(fn) and getattr(fn, "_submodule_script_name", None)
+        }
+        cls._scripts = inherited
+        cls._scripts.update(collected)
+        # 列表类属性按子类复制，防止子类就地修改污染父类注册
+        for attr in ("harnesses", "commands", "requires", "guards"):
+            if attr not in cls.__dict__:
+                setattr(cls, attr, list(getattr(cls, attr)))
+        # dict 类属性同理由：按子类复制，防止子类就地修改污染父类注册
+        if "modules" not in cls.__dict__:
+            setattr(cls, "modules", dict(getattr(cls, "modules")))
+
+    def __init__(
+        self,
+        llm_client: Any = None,
+        event_bus: EventBus | None = None,
+    ) -> None:
+        self._llm_client = llm_client
+        self._event_bus = event_bus
+
+    def _ensure_client(self) -> Any:
+        """直接类使用（未注入 client）时从 env 懒创建。"""
+        if self._llm_client is None:
+            self._llm_client = create_llm_client(LLMConfig.from_env())
+        return self._llm_client
+
+    def _module_id(self) -> str:
+        return f"{self.name}_{uuid.uuid4().hex[:6]}"
+
+    def _build_registry(
+        self,
+        audit: bool,
+        harness_overrides: dict[str, Any] | None = None,
+        *,
+        llm_client: Any = None,
+        event_bus: EventBus | None = None,
+    ) -> HarnessRegistry:
+        # 事件投递与 keep_records/persist 解耦：宿主传了 event_bus 就始终投递
+        # （与 audit 无关）；未传则静默 EventBus.null()（嵌入零开销）。audit 只
+        # 在 run() 里映射 keep_records。
+        bus = event_bus if event_bus is not None else (self._event_bus or EventBus.null())
+        client = llm_client if llm_client is not None else self._ensure_client()
+        reg = HarnessRegistry(llm_client=client, event_bus=bus)
+        for hc in self.harnesses:
+            if not hc.name:
+                raise ValueError(f"harnesses 配置缺少 name: {hc}")
+            cfg = (
+                self._apply_harness_overrides(hc, harness_overrides)
+                if harness_overrides else hc
+            )
+            reg.harness(cfg.name, cfg)
+        for cc in self.commands:
+            if not cc.name:
+                raise ValueError(f"commands 配置缺少 name: {cc}")
+            reg.command(cc.name, cc)
+        for sname, fn in self._scripts.items():
+            reg.script(sname)(fn)
+        for gname, gfn in self.guards:
+            reg.guard(gname, gfn)
+        register_builtin_harnesses(reg)
+        return reg
+
+    @staticmethod
+    def _apply_harness_overrides(
+        hc: HarnessConfig, overrides: dict[str, Any]
+    ) -> HarnessConfig:
+        """批量应用 LLM 覆盖（model/temperature/think/api_params）到单个 harness。"""
+        api_params = dict(hc.api_params)
+        if overrides.get("api_params"):
+            api_params.update(overrides["api_params"])
+        return HarnessConfig(
+            name=hc.name,
+            prompt_core=hc.prompt_core,
+            prompt_modes=dict(hc.prompt_modes),
+            output_format=hc.output_format,
+            notdo=list(hc.notdo),
+            model=overrides.get("model", hc.model),
+            temperature=overrides.get("temperature", hc.temperature),
+            think=overrides.get("think", hc.think),
+            api_params=api_params,
+            # 调用形态三字段原样携带——漏掉会让 image 模式在覆盖时静默降级为 text
+            mode=hc.mode,
+            image_size=hc.image_size,
+            image_dir=hc.image_dir,
+            # 校验重试预算原样携带——漏掉会在覆盖时静默归零
+            validate_retries=hc.validate_retries,
+        )
+
+    async def run(
+        self,
+        spec: dict[str, Any],
+        *,
+        tasklist: Tasklist | dict[str, Any] | None = None,
+        audit: bool = False,
+        max_ticks: int = 100,
+        harness_overrides: dict[str, Any] | None = None,
+        persist: bool | None = None,
+        llm_client: Any = None,
+        event_bus: EventBus | None = None,
+        hooks: dict | None = None,
+    ) -> list[Any]:
+        """执行 submodule。
+
+        - tasklist=None：用自身固定 tasklist，不触发一致性审核（发布前已验证）
+        - 传入自定义 tasklist：与 Module 一致，校验 + 一致性审核
+        - harness_overrides：{model/temperature/think/api_params} 覆盖，
+          构建 registry 时应用到 submodule 自身的全部 harness（不含内置
+          harness）（submodule 节点 LLM 配置传播）
+        - audit=False（默认）：嵌入模式，keep_records=False；除非 mode="fast"，
+          嵌入模式同样落盘（D11）
+        - audit=True：keep_records 全开（全量审计轨迹）
+        - 事件投递与 records/persist 解耦：构造传入 event_bus 时事件始终投递
+          （与 audit 取值无关）；未传则静默 EventBus.null()（嵌入零开销）。宿主
+          需失败原因等现场反馈时，传 event_bus 选择性订阅即可，无需开启审计
+        - persist：False = 快速模式（NullBackend 全内存 + 无 status.json +
+          无 stream.log，零落盘零 I/O）；None = 按 mode 决定（"fast" → False，
+          否则 True）
+        - llm_client/event_bus：覆盖实例级注入（宿主进程传入）；None 用实例值
+        - hooks：runner hooks 透传（观察通道，与 Module hooks 同语义）
+        """
+        errors = self.spec_schema.validate(spec)
+        if errors:
+            raise SpecValidationError(errors)
+        if self.tasklist is None and tasklist is None:
+            raise ValueError(f"submodule '{self.name}' 未定义 tasklist")
+        use_tasklist = self.tasklist if tasklist is None else tasklist
+        if isinstance(use_tasklist, dict):
+            use_tasklist = Tasklist.from_json(use_tasklist)
+        review = None if tasklist is None else "spec_tasklist_review"
+        use_persist = persist if persist is not None else (self.mode != "fast")
+        use_client = llm_client if llm_client is not None else self._ensure_client()
+        use_bus = event_bus if event_bus is not None else self._event_bus
+        reg = self._build_registry(audit, harness_overrides, llm_client=use_client, event_bus=use_bus)
+        module = Module(
+            spec=spec,
+            tasklist=use_tasklist,
+            llm_client=use_client,
+            event_bus=use_bus,
+            module_id=self._module_id(),
+            module=self.name,  # 溯源：status.json "module" 键（与 entry 路径一致）
+            registry=reg,
+            review_harness=review,
+            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,
+        )
+        return await module.run(max_ticks=max_ticks)
+
+    def pack(self, out_dir: str | Path) -> Path:
+        """导出发布目录：module.json + harnesses/ + scripts/ + commands/。
+
+        scripts/*.py = 函数源码 + 必要 import（含 @script 装饰器行），
+        加载时 exec 后按函数名取注册，pack/load round-trip 无签名改写。
+        """
+        if not self.name:
+            raise ValueError("submodule 缺少 name，无法打包")
+        if self.tasklist is None:
+            raise ValueError(f"submodule '{self.name}' 未定义 tasklist，无法打包")
+        p = Path(out_dir)
+        (p / "harnesses").mkdir(parents=True, exist_ok=True)
+        (p / "scripts").mkdir(exist_ok=True)
+        (p / "commands").mkdir(exist_ok=True)
+        (p / "guards").mkdir(exist_ok=True)
+        (p / "submodules").mkdir(exist_ok=True)
+        manifest = {
+            "name": self.name,
+            "version": self.version,
+            "description": self.description,
+            "submodule": True,
+            "spec_schema": asdict(self.spec_schema),
+            "requires": list(self.requires),
+            "modules": list(self.modules),
+            "tasklist": self.tasklist.to_dict(),
+        }
+        if self.default_spec is not None:
+            manifest["default_spec"] = dict(self.default_spec)
+        (p / "module.json").write_text(
+            json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+        for hc in self.harnesses:
+            if not hc.name:
+                raise ValueError(f"harnesses 配置缺少 name: {hc}")
+            (p / "harnesses" / f"{hc.name}.json").write_text(
+                json.dumps(hc.to_dict(), ensure_ascii=False, indent=2), encoding="utf-8"
+            )
+        for cc in self.commands:
+            if not cc.name:
+                raise ValueError(f"commands 配置缺少 name: {cc}")
+            (p / "commands" / f"{cc.name}.json").write_text(
+                json.dumps(cc.to_dict(), ensure_ascii=False, indent=2), encoding="utf-8"
+            )
+        for sname, fn in self._scripts.items():
+            src = textwrap.dedent(inspect.getsource(fn))
+            header = "from __future__ import annotations\nfrom module_harness.model.submodule import script\n\n"
+            (p / "scripts" / f"{sname}.py").write_text(header + src, encoding="utf-8")
+        for gname, gfn in self.guards:
+            if gname != gfn.__name__:
+                raise ValueError(
+                    f"guard 注册名 '{gname}' 与函数名 '{gfn.__name__}' 不一致"
+                    "（注册名 = 打包文件名 = 加载键，与 @script 同约定）"
+                )
+            src = textwrap.dedent(inspect.getsource(gfn))
+            header = "from __future__ import annotations\n\n"
+            (p / "guards" / f"{gname}.py").write_text(header + src, encoding="utf-8")
+        for mname, mcls in self.modules.items():
+            mcls().pack(p / "submodules" / mname)
+        return p

{specmodule-0.4.0 → specmodule-0.5.0}/module_harness/model/translator.py

@@ -15,7 +15,13 @@ from tickflow.views import NodeView, Resolved
 
 from ..core.config import HarnessConfig
 from ..core.harness import Harness
-from .spec import Spec, Tasklist, TasklistTemplate, TaskDefinition
+from .spec import (
+    ArtifactDecl,
+    Spec,
+    Tasklist,
+    TasklistTemplate,
+    TaskDefinition,
+)
 from ..core.registry import HarnessRegistry
 
 # Regex to find the first node name in a flow line.
@@ -130,6 +136,17 @@ class TasklistValidator:
         else:
             errors.append(f"Task '{key}': 未知 type '{task.type}'")
 
+        if task.validate_retries is not None:
+            if isinstance(task.validate_retries, bool) or not isinstance(task.validate_retries, int):
+                errors.append(
+                    f"Task '{key}': validate_retries 应为 int，"
+                    f"得到 {type(task.validate_retries).__name__}"
+                )
+            elif task.validate_retries < 0:
+                errors.append(
+                    f"Task '{key}': validate_retries 须 >= 0，得到 {task.validate_retries}"
+                )
+
         return errors
 
     @staticmethod
@@ -225,8 +242,13 @@ class Translator:
 
         # 检测 LLM 返回的包装格式 {"Tasks": {...}, "Flow": "..."}
         flow = template.tasklist.flow
+        artifacts: list[ArtifactDecl] = []
         if isinstance(tasks_dict, dict) and "Tasks" in tasks_dict:
             flow = tasks_dict.get("Flow", flow)
+            # 产物声明随包装格式透传（翻译脚本插值后的具体 glob 串）
+            raw_artifacts = tasks_dict.get("Artifacts", [])
+            if raw_artifacts:
+                artifacts = [ArtifactDecl.from_dict(a) for a in raw_artifacts]
             tasks_dict = tasks_dict["Tasks"]
 
         # 兼容 LLM 将 Tasks 输出为数组：转为 {A: ..., B: ...} 格式
@@ -250,7 +272,7 @@ class Translator:
         tasklist = Tasklist(tasks={
             key: TaskDefinition.from_dict(td) if isinstance(td, dict) else td
             for key, td in tasks_dict.items()
-        }, flow=flow)
+        }, flow=flow, artifacts=artifacts)
 
         errors = TasklistValidator.validate(tasklist, self.reg)
         if errors:
@@ -281,6 +303,8 @@ class Translator:
         if prompt_core is not None:
             existing = self.reg.harness_config(harness_name)
             if existing is not None:
+                # 既有缺口（见 specs/2026-09-30-validation-retry-design.md 非目标）：此处
+                # 重建 config 不携带 mode/image_*/validate_retries——修时四字段一起补
                 overridden = HarnessConfig(
                     prompt_core=prompt_core,
                     prompt_modes=dict(existing.prompt_modes),

{specmodule-0.4.0 → specmodule-0.5.0}/module_harness/orchestrate/graph_builder.py

@@ -211,6 +211,13 @@ class TasklistTranslator:
                 if task.image_dir is not None
                 else existing.image_dir
             ),
+            # 校验重试预算：task 级覆盖，缺省沿用注册 config——漏掉会让
+            # tasklist 想调的预算静默回注册值
+            validate_retries=(
+                task.validate_retries
+                if task.validate_retries is not None
+                else existing.validate_retries
+            ),
         )
 
         # 解析常量引用：promptmode 的 "{spec.xxx}" 与 inputs 的常量 token

{specmodule-0.4.0 → specmodule-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specmodule"
-version = "0.4.0"
+version = "0.5.0"
 description = "可审计、可调试、可完全掌控的 LLM 使用框架（tickflow + llm + module_harness）"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -21,9 +21,9 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    # 0.2.0 起依赖 tickflow bind 时代 API（Bind/NodeView/GuardView/保留名约定）；
-    # 0.1 的 DictView 视图时代不满足
-    "tickflow-py>=0.2.0,<0.3",
+    # 0.3.0 起依赖 tickflow FAILED 终态（饿死 run 判 FAILED，phase=aborted）；
+    # 0.2 的空 tick 恒 IDLE 会把饿死 run 误报成 done
+    "tickflow-py>=0.3.0,<0.4",
 ]
 
 [project.optional-dependencies]

{specmodule-0.4.0 → specmodule-0.5.0/specmodule.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specmodule
-Version: 0.4.0
+Version: 0.5.0
 Summary: 可审计、可调试、可完全掌控的 LLM 使用框架（tickflow + llm + module_harness）
 License: MIT
 Keywords: llm,workflow,petri-net,agent
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: tickflow-py<0.3,>=0.2.0
+Requires-Dist: tickflow-py<0.4,>=0.3.0
 Provides-Extra: anthropic
 Requires-Dist: anthropic; extra == "anthropic"
 Provides-Extra: openai

{specmodule-0.4.0 → specmodule-0.5.0}/specmodule.egg-info/requires.txt

@@ -1,4 +1,4 @@
-tickflow-py<0.3,>=0.2.0
+tickflow-py<0.4,>=0.3.0
 
 [anthropic]
 anthropic