specmodule 0.1.0__py3-none-any.whl

module_harness/harness.py

@@ -0,0 +1,181 @@
+"""Harness 类 — 配置持有 + async body 生成。"""
+
+from __future__ import annotations
+
+import dataclasses
+import time
+from typing import Any
+
+from tickflow import Failure
+from tickflow.views import DictView, Missing
+
+from .config import HarnessConfig
+from .prompt import PromptRenderer
+from .outputfmt import OutputValidator
+from .events import (
+    EventBus,
+    PromptRendered,
+    LlmCallStarted,
+    LlmToken,
+    LlmCallCompleted,
+    OutputValidated,
+    HarnessFailed,
+)
+
+
+class Harness:
+    """持有 HarnessConfig + LLM 客户端 + EventBus。
+
+    由 HarnessRegistry 管理，用户不直接使用。
+    """
+
+    def __init__(
+        self,
+        config: HarnessConfig,
+        llm_client: Any,
+        event_bus: EventBus,
+    ) -> None:
+        self.config = config
+        self.llm = llm_client
+        self.bus = event_bus
+        self._renderer = PromptRenderer(config)
+
+    def build_body(
+        self,
+        *,
+        promptmode: str | None = None,
+        prompt_extra: str | None = None,
+        spec_inputs: dict[str, Any] | None = None,
+        input_aliases: dict[str, str] | None = None,
+    ):
+        """返回一个 async body callable。
+
+        ``spec_inputs``：spec 字段常量（{field_name: value}），
+        渲染时作为占位符兜底值（graph_builder 解析 ``{spec.xxx}`` 后注入）。
+
+        ``input_aliases``：跨节点输入别名（{field_name: producer}）。
+        task.inputs 的 field 名在 view 中解析为 Missing（field 不是节点名），
+        运行时把 producer 的实际值合并进 extra_values，使 prompt 的
+        ``{field}`` 占位符能渲染（与 {spec.xxx} 兜底同一机制）。
+
+        body 执行流程：
+          1. 渲染三层 prompt
+          2. 调 LLM（流式 token 经 on_token 发射）
+          3. 校验输出格式
+          4. 发事件
+        """
+        config = self.config
+        llm = self.llm
+        bus = self.bus
+        renderer = self._renderer
+        validator = OutputValidator(config.output_format) if config.output_format else None
+
+        async def body(view: DictView) -> Any:
+            node = view.node
+            now = time.monotonic()
+            # view.state 可为 None（bare DictView）；写入后自动进入 NodeState.mutable_state 审计
+            state = view.state
+
+            # 1. 渲染 prompt
+            extra = dict(spec_inputs) if spec_inputs else {}
+            if input_aliases:
+                for field, producer in input_aliases.items():
+                    if field in extra:
+                        continue
+                    try:
+                        val = view[producer].value
+                    except (KeyError, AttributeError):
+                        continue
+                    if val is not Missing:
+                        extra[field] = val
+            rendered = renderer.render(
+                view,
+                promptmode=promptmode,
+                prompt_extra=prompt_extra,
+                extra_values=extra,
+            )
+            if state is not None:
+                state["_prompt"] = rendered
+            bus.emit(PromptRendered(
+                timestamp=time.monotonic(), node=node, tick=0,
+                rendered=rendered,
+            ))
+
+            # 2. 调用 LLM
+            bus.emit(LlmCallStarted(
+                timestamp=time.monotonic(), node=node, tick=0,
+                model=config.model or "default",
+                prompt_chars=len(rendered),
+            ))
+
+            def on_token(chunk: str) -> None:
+                bus.emit(LlmToken(
+                    timestamp=time.monotonic(), node=node, tick=0,
+                    chunk=chunk,
+                ))
+
+            try:
+                from llm.client import LLMError
+
+                # 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,
+                    api_params=config.api_params if config.api_params else None,
+                )
+            except LLMError as e:
+                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")
+
+            # 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 not None:
+                result = validator.validate(response.content)
+                if isinstance(result, Failure):
+                    bus.emit(OutputValidated(
+                        timestamp=time.monotonic(), node=node, tick=0,
+                        passed=False,
+                        extracted=False,
+                        error=result.error,
+                    ))
+                    return result
+                bus.emit(OutputValidated(
+                    timestamp=time.monotonic(), node=node, tick=0,
+                    passed=True,
+                    extracted=_was_extracted(response.content, result),
+                    error=None,
+                ))
+                return result
+
+            return response.content
+
+        return body
+
+
+def _was_extracted(raw: str, result: Any) -> bool:
+    """简单判断原始内容是否经过了提取处理（内容不直接相等）。"""
+    if not isinstance(result, str):
+        return True  # JSON 解析必然是提取
+    return raw.strip() != result.strip()

module_harness/loader.py

@@ -0,0 +1,215 @@
+# module_harness/loader.py
+"""ModuleLoader — 加载发布目录为 SubModule 实例（第二层用户入口）。"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from llm import LLMConfig, create_llm_client
+
+from .builtins import BUILTIN_HARNESS_NAMES
+from .command import CommandConfig
+from .config import HarnessConfig
+from .events import EventBus
+from .spec import SpecSchema, Tasklist
+from .submodule import SubModule
+
+
+class ModuleRequirementError(Exception):
+    """requires 声明的名字无法在「内置集 ∪ provides」中解析。"""
+
+    def __init__(self, missing: list[str], available: list[str]) -> None:
+        self.missing = missing
+        self.available = available
+        super().__init__(
+            "requires 无法解析: " + ", ".join(missing)
+            + "\n可用: " + ", ".join(available)
+        )
+
+
+class ModuleManifestError(Exception):
+    """module.json 缺失、损坏或缺少必需字段。"""
+
+
+class ModuleLoader:
+    """第二层用户入口：加载发布目录，返回可运行的 SubModule 实例。
+
+    llm_client 优先（测试/注入用）；否则由 llm_config（None → from_env）创建。
+    """
+
+    def __init__(
+        self,
+        llm_config: LLMConfig | None = None,
+        *,
+        llm_client: Any = None,
+        event_bus: EventBus | None = None,
+    ) -> None:
+        self._llm_client = llm_client
+        self._llm_config = llm_config
+        self._event_bus = event_bus
+
+    def _ensure_client(self) -> Any:
+        """llm_client 优先；否则由 llm_config（None → from_env）惰性创建。"""
+        if self._llm_client is None:
+            if self._llm_config is None:
+                self._llm_config = LLMConfig.from_env()
+            self._llm_client = create_llm_client(self._llm_config)
+        return self._llm_client
+
+    def load(self, path: str | Path, *, lazy_client: bool = False) -> SubModule:
+        """解析 module.json → 注册 provides → 校验 requires → 返回 SubModule。
+
+        ``lazy_client=True``：校验/解析阶段不实例化 LLM client（D6——校验
+        无网络/key 需求）；SubModule 构造传 None，运行期惰性 from_env 或
+        由调用方经 ``run(llm_client=...)`` 注入。默认 False 保持旧语义。
+        """
+        p = Path(path)
+        manifest_path = p / "module.json"
+        if not manifest_path.is_file():
+            raise ModuleManifestError(f"缺少 module.json: {manifest_path}")
+        try:
+            manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as e:
+            raise ModuleManifestError(f"module.json 解析失败: {e}") from e
+        if not isinstance(manifest, dict):
+            raise ModuleManifestError("module.json 顶层必须是对象")
+
+        name = manifest.get("name")
+        tasklist_data = manifest.get("tasklist")
+        if not name:
+            raise ModuleManifestError("module.json 缺少 'name'")
+        if tasklist_data is None:
+            raise ModuleManifestError("module.json 缺少 'tasklist'")
+        try:
+            tasklist = Tasklist.from_json(tasklist_data)
+        except (ValueError, TypeError) as e:
+            raise ModuleManifestError(f"tasklist 无效: {e}") from e
+
+        harnesses = self._load_harnesses(p)
+        commands = self._load_commands(p)
+        scripts = self._load_scripts(p)
+        guards = self._load_guards(p)
+        submodules = self._load_submodules(p)
+
+        modules_raw = manifest.get("modules", []) or []
+        if not isinstance(modules_raw, list) or not all(
+                isinstance(m, str) for m in modules_raw):
+            raise ModuleManifestError("modules 必须是字符串列表")
+        missing_mods = [m for m in modules_raw if m not in submodules]
+        if missing_mods:
+            raise ModuleManifestError(
+                "modules 缺少子模块目录: " + ", ".join(missing_mods))
+        extra_mods = [m for m in submodules if m not in modules_raw]
+        if extra_mods:
+            raise ModuleManifestError(
+                "submodules/ 目录未在 manifest 声明: " + ", ".join(sorted(extra_mods)))
+
+        schema_data = manifest.get("spec_schema", {}) or {}
+        spec_schema = SpecSchema(
+            input=schema_data.get("input", {}) or {},
+            output=schema_data.get("output", {}) or {},
+        )
+        requires_raw = manifest.get("requires", []) or []
+        if not isinstance(requires_raw, list) or not all(
+                isinstance(r, str) for r in requires_raw):
+            raise ModuleManifestError("requires 必须是字符串列表")
+        requires = list(requires_raw)
+
+        provides = {h.name for h in harnesses} | {c.name for c in commands} | set(scripts)
+        all_names = [h.name for h in harnesses] + [c.name for c in commands] + list(scripts)
+        dups = {n for n in all_names if all_names.count(n) > 1}
+        if dups:
+            raise ModuleManifestError("provides 名称重复: " + ", ".join(sorted(dups)))
+        missing = [r for r in requires if r not in BUILTIN_HARNESS_NAMES and r not in provides]
+        if missing:
+            raise ModuleRequirementError(missing, sorted(BUILTIN_HARNESS_NAMES | provides))
+
+        cls = type(name, (SubModule,), {
+            "name": name,
+            "version": manifest.get("version", "0.1.0"),
+            "description": manifest.get("description", ""),
+            "spec_schema": spec_schema,
+            "requires": requires,
+            "tasklist": tasklist,
+            "harnesses": harnesses,
+            "commands": commands,
+            "_scripts": scripts,
+            "guards": list(guards.items()),
+            "modules": submodules,
+        })
+        client = None if lazy_client else self._ensure_client()
+        return cls(llm_client=client, event_bus=self._event_bus)
+
+    def _load_harnesses(self, p: Path) -> list[HarnessConfig]:
+        result: list[HarnessConfig] = []
+        for f in sorted((p / "harnesses").glob("*.json")):
+            try:
+                data = json.loads(f.read_text(encoding="utf-8"))
+                cfg = HarnessConfig.from_dict(data)
+            except (json.JSONDecodeError, TypeError, ValueError) as e:
+                raise ModuleManifestError(f"{f} 无效: {e}") from e
+            if not cfg.name:
+                raise ModuleManifestError(f"{f} 缺少 'name'")
+            result.append(cfg)
+        return result
+
+    def _load_commands(self, p: Path) -> list[CommandConfig]:
+        result: list[CommandConfig] = []
+        for f in sorted((p / "commands").glob("*.json")):
+            try:
+                data = json.loads(f.read_text(encoding="utf-8"))
+                cfg = CommandConfig.from_dict(data)
+            except (json.JSONDecodeError, TypeError, ValueError) as e:
+                raise ModuleManifestError(f"{f} 无效: {e}") from e
+            if not cfg.name:
+                raise ModuleManifestError(f"{f} 缺少 'name'")
+            result.append(cfg)
+        return result
+
+    def _load_scripts(self, p: Path) -> dict[str, Any]:
+        """加载 scripts/*.py 为可调用函数（exec 执行——加载目录视为可信代码）。"""
+        result: dict[str, Any] = {}
+        for f in sorted((p / "scripts").glob("*.py")):
+            ns: dict[str, Any] = {}
+            try:
+                exec(compile(f.read_text(encoding="utf-8"), str(f), "exec"), ns)
+            except Exception as e:  # 脚本自身报错视为清单错误
+                raise ModuleManifestError(f"{f} 加载失败: {e}") from e
+            fn = ns.get(f.stem)
+            if not callable(fn):
+                raise ModuleManifestError(f"{f} 未定义函数 {f.stem}")
+            result[f.stem] = fn
+        return result
+
+    def _load_guards(self, p: Path) -> dict[str, Any]:
+        """加载 guards/*.py 为可调用函数（exec 执行——与 scripts 同机制）。"""
+        result: dict[str, Any] = {}
+        for f in sorted((p / "guards").glob("*.py")):
+            ns: dict[str, Any] = {}
+            try:
+                exec(compile(f.read_text(encoding="utf-8"), str(f), "exec"), ns)
+            except Exception as e:  # 函数自身报错视为清单错误
+                raise ModuleManifestError(f"{f} 加载失败: {e}") from e
+            fn = ns.get(f.stem)
+            if not callable(fn):
+                raise ModuleManifestError(f"{f} 未定义函数 {f.stem}")
+            result[f.stem] = fn
+        return result
+
+    def _load_submodules(self, p: Path) -> dict[str, SubModule]:
+        """递归加载 submodules/*/（每个是完整子包）→ {目录名: 实例}。
+
+        目录名为引用键（pack 时以父模块 modules 的键命名），与子模块
+        自身 name 无关。guard 名不进入 provides/requires（边引用，不参与
+        重复名检测）；子模块实例是父的 modules 值，加载时同样解析。"""
+        result: dict[str, SubModule] = {}
+        base = p / "submodules"
+        if not base.is_dir():
+            return result
+        for d in sorted(base.iterdir()):
+            if not (d / "module.json").is_file():
+                raise ModuleManifestError(f"{d} 缺少 module.json（submodule 目录无效）")
+            result[d.name] = self.load(d)
+        return result