specmodule 0.1.0__py3-none-any.whl

module_harness/command.py

@@ -0,0 +1,115 @@
+# module_harness/command.py
+"""Command 节点 — 一行 shell 命令即一个 tickflow body。"""
+
+from __future__ import annotations
+
+import dataclasses
+import subprocess
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from tickflow import Failure
+from tickflow.views import DictView
+
+from .events import (
+    EventBus,
+    CommandStarted,
+    CommandCompleted,
+    CommandFailed,
+)
+
+
+@dataclass
+class CommandConfig:
+    """shell 命令配置。"""
+
+    command: str                        # shell 命令字符串
+    timeout: float = 60.0               # 超时秒数
+    cwd: str | None = None              # 工作目录
+    env: dict[str, str] | None = None   # 额外环境变量
+    capture_output: bool = True
+    shell: bool = True
+
+    name: str | None = None
+    """注册名。submodule 的 commands 列表中必须提供。"""
+
+    def to_dict(self) -> dict[str, Any]:
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "CommandConfig":
+        return cls(**d)
+
+
+class Command:
+    """持有 CommandConfig + EventBus，类似 Harness 类。"""
+
+    def __init__(self, config: CommandConfig, event_bus: EventBus) -> None:
+        self.config = config
+        self.bus = event_bus
+
+    def build_body(self, *, timeout: float | None = None, cwd: str | None = None):
+        """返回一个 sync body callable。
+
+        body 执行流程：
+          1. emit CommandStarted
+          2. subprocess.run(command, ...)
+          3. 成功 → emit CommandCompleted → return {"stdout", "stderr", "returncode"}
+          4. 异常 → emit CommandFailed → return Failure(type="llm")
+        """
+        config = self.config
+        bus = self.bus
+        final_timeout = timeout if timeout is not None else config.timeout
+        final_cwd = cwd if cwd is not None else config.cwd
+
+        def body(view: DictView):
+            node = view.node
+            bus.emit(CommandStarted(
+                timestamp=time.monotonic(), node=node, tick=0,
+            ))
+
+            try:
+                result = subprocess.run(
+                    config.command,
+                    shell=config.shell,
+                    timeout=final_timeout,
+                    cwd=final_cwd,
+                    env=config.env,
+                    capture_output=config.capture_output,
+                    text=True,
+                    # 显式 UTF-8 + replace：不依赖 locale 默认编码，非 UTF-8 控制台
+                    # （中文 Windows GBK）的子进程输出不炸 reader 线程（D1）
+                    encoding="utf-8",
+                    errors="replace",
+                )
+            except subprocess.TimeoutExpired as e:
+                error_msg = f"命令超时 ({final_timeout}s): {e}"
+                bus.emit(CommandFailed(
+                    timestamp=time.monotonic(), node=node, tick=0,
+                    error=error_msg,
+                ))
+                return Failure(error_msg, type="llm")
+            except Exception as e:
+                error_msg = f"命令执行失败: {e}"
+                bus.emit(CommandFailed(
+                    timestamp=time.monotonic(), node=node, tick=0,
+                    error=error_msg,
+                ))
+                return Failure(error_msg, type="llm")
+
+            stdout = result.stdout or ""
+            stderr = result.stderr or ""
+
+            bus.emit(CommandCompleted(
+                timestamp=time.monotonic(), node=node, tick=0,
+                stdout=stdout, stderr=stderr, returncode=result.returncode,
+            ))
+
+            return {
+                "stdout": stdout,
+                "stderr": stderr,
+                "returncode": result.returncode,
+            }
+
+        return body

module_harness/config.py

@@ -0,0 +1,95 @@
+# module_harness/config.py
+"""HarnessConfig — harness 节点的完整配置数据模型。"""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from typing import Any
+
+from .outputfmt import OutputFormat
+
+
+@dataclass
+class HarnessConfig:
+    """harness 节点的完整配置。
+
+    对标 tasklist 中 Task 定义的字段。
+    翻译层使用 :meth:`from_task_definition` 直接构造。
+    """
+
+    # ── 三层 prompt ──
+    prompt_core: str
+    """Layer 1：核心提示词模板，含 {key} 占位符。"""
+
+    prompt_modes: dict[str, str] = field(default_factory=dict)
+    """Layer 2：动态 prompt 选项集。{"formal": "...", "casual": "..."}。"""
+
+    # ── 输出约束 ──
+    output_format: OutputFormat | None = None
+    """输出格式约束（None = 不约束）。"""
+
+    notdo: list[str] = field(default_factory=list)
+    """否定性约束列表，拼入 system prompt。"""
+
+    # ── LLM 参数（Task 可逐项覆盖）──
+    model: str | None = None
+    temperature: float | None = None
+    think: bool | dict | None = None
+
+    # ── SDK 透传参数 ──
+    api_params: dict[str, Any] = field(default_factory=dict)
+    """透传给 LLM SDK 的额外参数。按 API 官方格式写入，如
+    ``{"temperature": 0.3, "thinking": {"type": "enabled"}}``。
+    会与 temperature / think 等独立字段合并（api_params 优先级更高）。"""
+
+    # ── 注册信息（submodule 用）──
+    name: str | None = None
+    """注册名。submodule 的 harnesses 列表中必须提供。"""
+
+    def to_dict(self) -> dict[str, Any]:
+        """序列化为 JSON 可写 dict（含 output_format）。"""
+        return dataclasses.asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "HarnessConfig":
+        """从 to_dict() 输出还原。"""
+        data = dict(d)
+        of = data.pop("output_format", None)
+        if of is not None:
+            data["output_format"] = OutputFormat(**of)
+        return cls(**data)
+
+    @classmethod
+    def from_task_definition(cls, task: dict[str, Any]) -> "HarnessConfig":
+        """从 tasklist Task dict 构造 HarnessConfig。
+
+        task 中预期的键：
+        - prompt_core   → Layer 1
+        - prompt_modes  → Layer 2
+        - outputformat  → 输出格式（dict，含 type/schema/instruction）
+        - notdo         → 否定性约束列表
+        - model         → LLM 模型覆盖
+        - temperature   → 温度覆盖
+        - think         → 扩展思考覆盖
+        - api_params    → SDK 透传参数（dict）
+        """
+        output_format = None
+        of_data = task.get("outputformat")
+        if of_data is not None:
+            output_format = OutputFormat(
+                type=of_data["type"],
+                schema=of_data.get("schema"),
+                instruction=of_data.get("instruction"),
+            )
+
+        return cls(
+            prompt_core=task["prompt_core"],
+            prompt_modes=task.get("prompt_modes", {}),
+            output_format=output_format,
+            notdo=task.get("notdo", []),
+            model=task.get("model"),
+            temperature=task.get("temperature"),
+            think=task.get("think"),
+            api_params=task.get("api_params", {}),
+        )

module_harness/consistency.py

@@ -0,0 +1,123 @@
+# module_harness/consistency.py
+"""一致性审核 — spec + tasklist 语义一致性检查。
+
+独立于翻译通道：审核不经过模板，直接调用注册的审核 harness body（不走 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 .config import HarnessConfig
+from .outputfmt import OutputFormat
+from .registry import HarnessRegistry
+from .spec import Spec, Tasklist
+
+
+@dataclass
+class ConsistencyReport:
+    """一致性审核结果。"""
+
+    consistent: bool
+    suggestions: str
+    raw: str  # LLM 原始输出（审计链）
+
+
+class ConsistencyError(ValueError):
+    """一致性审核未通过。携带完整 report，str() 输出问题描述。"""
+
+    def __init__(self, report: ConsistencyReport) -> None:
+        self.report = report
+        super().__init__(f"一致性审核未通过: {report.suggestions}")
+
+
+REVIEW_HARNESS_CONFIG = HarnessConfig(
+    prompt_core=(
+        "你是一致性审核器。判断给定 tasklist 是否能实现 spec 的目标。\n"
+        "审核要点：\n"
+        "1. spec 的每个目标/需求是否被 tasklist 中的任务覆盖\n"
+        "2. task 中引用的字段（{spec.xxx}、inputs）在 spec 中是否存在\n"
+        "3. flow 是否可达、是否有死路或未定义节点\n"
+        "spec: {spec}\n"
+        "tasklist: {tasklist}\n"
+        '输出 JSON：{"consistent": true/false, "suggestions": "..."}'
+    ),
+    output_format=OutputFormat(type="json_object"),
+    temperature=0.1,
+)
+
+
+def register_review_harness(
+    reg: HarnessRegistry, name: str = "spec_tasklist_review"
+) -> None:
+    """注册内置一致性审核 harness（默认名 spec_tasklist_review）。"""
+    reg.harness(name, REVIEW_HARNESS_CONFIG)
+
+
+class ConsistencyReviewer:
+    """调用审核 harness body，返回 ConsistencyReport。"""
+
+    def __init__(
+        self, registry: HarnessRegistry, harness_name: str = "spec_tasklist_review"
+    ) -> None:
+        self.reg = registry
+        self.harness_name = harness_name
+
+    async def review(self, spec: Spec, tasklist: Tasklist) -> ConsistencyReport:
+        """执行一致性审核。审核失败（LLM 错误/输出不合法）抛 ValueError。"""
+        if self.reg.harness_config(self.harness_name) 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}")
+
+        if isinstance(result, str):
+            try:
+                data = json.loads(result)
+            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}")
+
+        consistent = data.get("consistent")
+        suggestions = data.get("suggestions")  # 缺字段 → None → 下方 isinstance 校验抛错
+        if not isinstance(consistent, bool):
+            raise ValueError(f"审核输出缺少合法的 'consistent' 布尔字段: {data!r}")
+        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
+        )

module_harness/entry.py

@@ -0,0 +1,74 @@
+# module_harness/entry.py
+"""模块入口合约：ModuleEntry + 目录发现（roadmap Phase 0，CLI 使用）。
+
+一个 module 一个 py 文件（``modules/<name>.py``），文件内声明模块级
+``entry`` 变量。未来 ``init`` 脚手架可据此生成实例骨架
+（scripts/harnesses/submodules/modules 分目录）。
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+from .events import EventBus
+from .registry import HarnessRegistry
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class ModuleEntry:
+    """模块入口声明：模板 + submodule + registry 构建 + 默认 spec/schema。"""
+
+    name: str
+    description: str
+    templates: dict[str, dict]                                   # {模板名: TasklistTemplate JSON}
+    submodules: dict[str, type] = field(default_factory=dict)    # {tasklist 名: SubModule 类}
+    build_registry: Callable[[Any, str, EventBus], HarnessRegistry] | None = None
+    default_spec: dict[str, Any] | None = None
+    default_template: str | None = None
+    spec_schema: dict[str, str] | None = None                    # {字段: 类型名}
+    review_harness: str | None = "spec_tasklist_review"
+
+    def __post_init__(self) -> None:
+        if self.default_template is not None and self.default_template not in self.templates:
+            raise ValueError(f"default_template '{self.default_template}' 不在 templates 中")
+
+
+def discover_modules(modules_dir: Path | str) -> dict[str, ModuleEntry]:
+    """扫描 ``modules_dir/*.py``，导入后收集模块级 ``entry`` 变量。
+
+    缺 ``entry`` 或类型不符的文件跳过并 log 警告；同名冲突后者覆盖 + 警告；
+    文件导入抛异常跳过 + log exception（不阻断整体发现）。
+    """
+    out: dict[str, ModuleEntry] = {}
+    d = Path(modules_dir)
+    if not d.is_dir():
+        return out
+    for p in sorted(d.glob("*.py")):
+        if p.name.startswith("_"):
+            continue
+        spec = importlib.util.spec_from_file_location(
+            f"specmodule_module_{p.stem}", p
+        )
+        if spec is None or spec.loader is None:
+            log.warning("无法加载模块入口文件（跳过）: %s", p)
+            continue
+        mod = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(mod)
+        except Exception:
+            log.exception("模块入口加载失败（跳过）: %s", p)
+            continue
+        entry = getattr(mod, "entry", None)
+        if not isinstance(entry, ModuleEntry):
+            log.warning("文件 %s 缺少 entry 变量（ModuleEntry）——跳过", p)
+            continue
+        if entry.name in out:
+            log.warning("模块名 '%s' 重复（%s 覆盖）", entry.name, p)
+        out[entry.name] = entry
+    return out

module_harness/events.py

@@ -0,0 +1,149 @@
+# module_harness/events.py
+"""EventBus 与 harness/script 事件类型定义。"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+from typing import Callable
+
+log = logging.getLogger(__name__)
+
+
+# ── Harness 事件基类 ──────────────────────────────────────────────
+
+@dataclass
+class HarnessEvent:
+    timestamp: float
+    node: str
+    tick: int
+
+
+@dataclass
+class PromptRendered(HarnessEvent):
+    rendered: str
+
+
+@dataclass
+class LlmCallStarted(HarnessEvent):
+    model: str
+    prompt_chars: int
+
+
+@dataclass
+class LlmToken(HarnessEvent):
+    chunk: str
+
+
+@dataclass
+class LlmCallCompleted(HarnessEvent):
+    content_chars: int
+    usage: dict[str, int]
+    finish_reason: str | None
+
+
+@dataclass
+class OutputValidated(HarnessEvent):
+    passed: bool
+    extracted: bool
+    error: str | None
+
+
+@dataclass
+class HarnessFailed(HarnessEvent):
+    reason: str
+    failure_type: str  # "llm" | "infrastructure"
+
+
+@dataclass
+class ConsistencyReviewed(HarnessEvent):
+    """一致性审核事件（spec + 自定义 tasklist 通道）。"""
+    consistent: bool
+    suggestions: str
+    raw: str
+
+
+# ── Script 事件基类 ──────────────────────────────────────────────
+
+@dataclass
+class ScriptEvent:
+    timestamp: float
+    node: str
+    tick: int
+
+
+@dataclass
+class ScriptStarted(ScriptEvent):
+    pass
+
+
+@dataclass
+class ScriptCompleted(ScriptEvent):
+    output_type: str
+
+
+@dataclass
+class ScriptFailed(ScriptEvent):
+    error: str
+
+
+# ── Command 事件类型 ────────────────────────────────────────────
+
+@dataclass
+class CommandStarted(HarnessEvent):
+    pass
+
+
+@dataclass
+class CommandCompleted(HarnessEvent):
+    stdout: str
+    stderr: str
+    returncode: int
+
+
+@dataclass
+class CommandFailed(HarnessEvent):
+    error: str
+
+
+# ── EventBus ──────────────────────────────────────────────────────
+
+class EventBus:
+    """同步发布/订阅。
+
+    回调异常 → 记录日志并吞掉（与 tickflow hooks 行为一致）。
+    使用 ``EventBus.null()`` 获取静默实例（嵌入式场景）。
+    """
+
+    def __init__(self) -> None:
+        self._subscribers: dict[type, list[Callable]] = {}
+
+    def subscribe(self, event_type: type, callback: Callable) -> None:
+        """为某个事件类型注册回调。"""
+        self._subscribers.setdefault(event_type, []).append(callback)
+
+    def emit(self, event: HarnessEvent | ScriptEvent) -> None:
+        """发布事件到所有匹配类型的订阅者。"""
+        for event_type, callbacks in self._subscribers.items():
+            if isinstance(event, event_type):
+                for cb in callbacks:
+                    try:
+                        cb(event)
+                    except Exception:
+                        log.exception("EventBus callback raised; swallowed")
+
+    def on(self, event_type: type):
+        """装饰器方式订阅: ``@bus.on(LlmToken) def handle(e): ...``"""
+        def deco(fn: Callable) -> Callable:
+            self.subscribe(event_type, fn)
+            return fn
+        return deco
+
+    @staticmethod
+    def null() -> "EventBus":
+        """返回一个静默 EventBus，emit 无操作。"""
+        bus = EventBus()
+        # 直接替换 emit 方法为 no-op，保留 subscribe 语义但无实际操作
+        bus.emit = lambda event: None  # type: ignore[method-assign]
+        return bus