specmodule 0.1.0__py3-none-any.whl

module_harness/module.py

@@ -0,0 +1,452 @@
+"""Module 编排器 — spec + template/tasklist → tasklist → runner。"""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import json
+import logging
+import os
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+from tickflow.async_runner import AsyncRunner
+from tickflow.persistence import NullBackend, SqliteBackend
+
+from .spec import Spec, Tasklist
+from .consistency import ConsistencyError, ConsistencyReport, ConsistencyReviewer
+from .translator import Translator, TemplateLoader, TasklistValidator
+from .graph_builder import TasklistTranslator
+from .registry import HarnessRegistry
+from .events import EventBus, ConsistencyReviewed
+from .checkpoint import (
+    ModuleInputStore,
+    ResumeError,
+    check_resume_compat,
+    tasklist_from_dict,
+    tasklist_to_dict,
+)
+
+log = logging.getLogger(__name__)
+
+
+def _persist_dir(module_id: str) -> Path:
+    """``<工作目录>/.specmodule/runs/<run_id>/run.sqlite``（D9）。
+
+    run_id = module_id：一个任务一次运行一个子目录、一个独立 SQLite 数据库。
+    """
+    return Path.cwd() / ".specmodule" / "runs" / module_id / "run.sqlite"
+
+
+def _status_path(module_id: str) -> Path:
+    """``<工作目录>/.specmodule/runs/<module_id>/status.json``（roadmap #7）。
+
+    阶段级运行状态文件：与 run.sqlite 同目录，跨进程查询的轻量通道。
+    """
+    return Path.cwd() / ".specmodule" / "runs" / module_id / "status.json"
+
+
+class Module:
+    """SpecModule 的核心编排器。
+
+    spec + template → 翻译 → tasklist → tickflow Graph + registry → AsyncRunner
+    或 spec + tasklist（自定义）→ 校验 + 一致性审核 → AsyncRunner。
+    """
+
+    def __init__(
+        self,
+        spec: dict[str, Any],
+        *,
+        template_name: str | None = None,
+        tasklist: Tasklist | None = None,
+        llm_client: Any,
+        event_bus: EventBus | None = None,
+        template_loader: TemplateLoader | None = None,
+        module_id: str | None = None,
+        registry: HarnessRegistry | None = None,
+        review_harness: str | None = "spec_tasklist_review",
+        keep_records: bool = True,
+        persist: bool = True,
+        status_file: bool = True,
+        modules: dict[str, Any] | None = None,
+        hooks: dict | None = None,
+    ) -> None:
+        if (template_name is None) == (tasklist is None):
+            raise ValueError("template_name 与 tasklist 必须且只能传一个")
+        self.spec = Spec(spec)
+        self.template_name = template_name
+        self.tasklist = tasklist
+        self.review_harness = review_harness
+        self.keep_records = keep_records
+        # True（默认）：构造 .specmodule/runs/<run_id>/run.sqlite 持久 backend（D9）
+        # False：快速模式——NullBackend 全内存，零落盘零 I/O（D7 语义正式化）
+        self.persist = persist
+        # True（默认）：写 .specmodule/runs/<module_id>/status.json
+        # （阶段级，跨进程查询通道）；False：零残留（快速模式可用）
+        self.status_file = status_file
+        self.review_result: ConsistencyReport | None = None
+        self.module_id = module_id or f"mod_{uuid.uuid4().hex[:8]}"
+        self._llm_client = llm_client
+        # submodule 引用解析表 {tasklist 名: SubModule 类}：TasklistValidator 校验
+        # submodule 节点（T2）与 TasklistTranslator 构建嵌套子图（T6）共用
+        self._modules = dict(modules or {})
+        # runner hooks 透传（观察通道）：{hook名: async/sync 回调}，构造
+        # runner 后注册。CLI 实时显示使用 on_tick_start/on_fire。
+        self._hooks = dict(hooks or {})
+
+        if registry is not None:
+            self._reg = registry
+        else:
+            self._reg = HarnessRegistry(
+                llm_client=llm_client,
+                event_bus=event_bus or EventBus.null(),
+            )
+        self._loader = template_loader or TemplateLoader()
+        self._translator = Translator(self._reg)
+        self._write_phase("idle")
+
+        # roadmap #5：runner 由 _build_runner_async 持有；快照/回滚 API 依赖它
+        self._runner: AsyncRunner | None = None
+        self._last_tasklist: Tasklist | None = None
+        self._input_store: ModuleInputStore | None = None
+
+    # ------------------------------------------------------------------
+    # 运行状态（roadmap #7）
+    # ------------------------------------------------------------------
+
+    def _write_phase(self, phase: str, error: str | None = None) -> None:
+        """原子写 status.json（tmp + os.replace）。失败仅 log，不阻断运行。
+
+        phase 取值：idle/translating/reviewing/building/ready/running/
+        done/aborted/cancelled。status_file=False 时不写盘（零残留）。
+        """
+        if not self.status_file:
+            return
+        path = _status_path(self.module_id)
+        tmp = path.with_suffix(".json.tmp")
+        try:
+            tmp.parent.mkdir(parents=True, exist_ok=True)
+            tmp.write_text(
+                json.dumps({
+                    "module_id": self.module_id,
+                    "phase": phase,
+                    "error": error,
+                    "updated_at": time.time(),
+                }, ensure_ascii=False),
+                encoding="utf-8",
+            )
+            os.replace(tmp, path)
+        except OSError:
+            log.exception("写 status.json 失败（不阻断运行）: %s", path)
+
+    def build_runner(self) -> AsyncRunner:
+        """执行翻译 → 构建 graph → 返回 AsyncRunner。
+
+        Note: 这是一个同步方法。在 async 上下文中直接使用
+        await module._build_runner_async() 或 await module.run()。
+        """
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(self._build_runner_async())
+        except Exception as e:
+            self._write_phase("aborted", error=str(e))
+            raise
+        finally:
+            loop.close()
+
+    async def _build_runner_async(self) -> AsyncRunner:
+        """异步版 build_runner。"""
+        if self.tasklist is not None:
+            self._write_phase("reviewing")
+            tasklist = self.tasklist
+            errors = TasklistValidator.validate(tasklist, self._reg, self._modules)
+            if errors:
+                raise ValueError(
+                    "tasklist 校验失败:\n" + "\n".join(f"  - {e}" for e in errors)
+                )
+            if self.review_harness is not None:
+                report = await ConsistencyReviewer(
+                    self._reg, self.review_harness
+                ).review(self.spec, tasklist)
+                self.review_result = report
+                self._reg._event_bus.emit(ConsistencyReviewed(
+                    timestamp=time.monotonic(), node="__review__", tick=0,
+                    consistent=report.consistent,
+                    suggestions=report.suggestions,
+                    raw=report.raw,
+                ))
+                if not report.consistent:
+                    raise ConsistencyError(report)
+        else:
+            self._write_phase("translating")
+            template = self._loader.get(self.template_name)
+            if template is None:
+                raise ValueError(f"模板 '{self.template_name}' 未找到")
+            tasklist = await self._translator.translate(self.spec, template)
+        self._write_phase("building")
+        builder = TasklistTranslator(
+            self._reg, self.module_id,
+            modules=self._modules, llm_client=self._llm_client,
+        )
+        graph, reg = builder.build(tasklist, spec=self.spec)
+        self._last_tasklist = tasklist
+        backend = (
+            SqliteBackend(_persist_dir(self.module_id))
+            if self.persist
+            else NullBackend()
+        )
+        self._write_phase("ready")
+        runner = AsyncRunner(
+            graph,
+            registry=reg,
+            keep_records=self.keep_records,
+            backend=backend,
+            session_id=self.module_id,
+        )
+        self._runner = runner
+        for _hook_name, _cb in self._hooks.items():
+            _register = getattr(runner, _hook_name, None)
+            if callable(_register):
+                _register(_cb)
+            else:
+                log.warning("Module hooks: 未知 runner hook '%s'（忽略）", _hook_name)
+        return runner
+
+    # ------------------------------------------------------------------
+    # 快照/回滚（roadmap #5）
+    # ------------------------------------------------------------------
+
+    def _require_runner(self) -> AsyncRunner:
+        """快照/回滚 API 前置守卫：runner 未构建时抛错。"""
+        if self._runner is None:
+            raise RuntimeError("尚未构建 runner——请先 build_runner() 或 run()")
+        return self._runner
+
+    def close(self) -> None:
+        """释放 Module 持有的 SQLite 连接（``_input_store``，懒创建）。
+
+        run()/resume() 结束后可调用；幂等（重复调用安全）。再次 run()/resume()
+        会按需重新创建 store（``_archive_module_inputs`` 懒重建）。
+
+        注：runner 持有的 SqliteBackend 连接属于 runner 生命周期，由调用方
+        管理（与既有行为一致），本方法只关闭 Module 自己创建的
+        ModuleInputStore 连接，不触碰 runner。
+        """
+        if self._input_store is not None:
+            self._input_store.close()
+            self._input_store = None
+
+    def snapshot(self) -> dict:
+        """进程内全量快照：{spec, tasklist, runner_snapshot} 三件套。
+
+        深拷贝语义：修改返回的 dict 不影响 Module 状态。
+        """
+        runner = self._require_runner()
+        assert self._last_tasklist is not None
+        snap = {
+            "spec": self.spec.to_dict(),
+            "tasklist": tasklist_to_dict(self._last_tasklist),
+            "runner": runner.snapshot(),
+        }
+        # to_dict/runner 快照均为浅拷贝（嵌套结构共享引用）——整体深拷贝
+        # 兑现 docstring 的深拷贝承诺（零 tickflow 修改）。
+        return copy.deepcopy(snap)
+
+    def restore(self, snap: dict) -> None:
+        """回滚 runner 到快照，并恢复 spec/tasklist 字段。"""
+        runner = self._require_runner()
+        self.spec = Spec(snap["spec"])
+        self.tasklist = tasklist_from_dict(snap["tasklist"])
+        self._last_tasklist = self.tasklist
+        # 与 __init__ 的"template/tasklist 二选一"不变量一致：restore 后
+        # 走 tasklist 通道，template_name 不再持有
+        self.template_name = None
+        runner.restore(snap["runner"])
+
+    def checkpoint(self, label: str) -> None:
+        """手动检查点（backend 表，永久保留）。透传 runner。"""
+        runner = self._require_runner()
+        if not self.persist:
+            raise RuntimeError("检查点需要 persist=True（fast mode 零持久化）")
+        runner.checkpoint(label)
+
+    def rollback_to(self, label: str) -> None:
+        """进程内回退到命名检查点。透传 runner。"""
+        runner = self._require_runner()
+        if not self.persist:
+            raise RuntimeError("检查点需要 persist=True（fast mode 零持久化）")
+        runner.rollback_to(label)
+
+    def list_checkpoints(self) -> list[tuple[int, str | list[str], str]]:
+        """全部检查点 (tick, fired 或 label, kind)，按 tick 升序。
+
+        kind ∈ {"tick", "manual"}：tick = snapshots 表每 tick 最小快照
+        （fired 节点列表，历史审阅雏形）；manual = checkpoint() 手动检查点
+        （label）。不依赖 runner——跨进程场景（新 Module 实例）也可查询。
+        """
+        out: list[tuple[int, str | list[str], str]] = []
+        if self.persist:
+            backend = SqliteBackend(_persist_dir(self.module_id))
+            try:
+                for tick in backend.list_snapshots(self.module_id):
+                    snap = backend.load_snapshot(self.module_id, tick)
+                    if snap is None:
+                        continue
+                    out.append((tick, list(snap.get("fired", [])), "tick"))
+                out.extend(
+                    (tick, label, "manual")
+                    for label, tick in backend.list_checkpoints(self.module_id)
+                )
+            except Exception:
+                log.exception("检查点列表读取失败（忽略）")
+            finally:
+                backend.close()
+        return sorted(out, key=lambda item: item[0])
+
+    @staticmethod
+    def _resolve_target(backend: SqliteBackend, module_id: str, rollback_to: int | str) -> dict | None:
+        """解析回退目标：tick 号 → snapshots 表；manual:xxx → checkpoints 表。
+
+        其他（非数字、非 manual 前缀）返回 None——调用方抛 KeyError。
+        """
+        if isinstance(rollback_to, int) or (
+            isinstance(rollback_to, str) and rollback_to.isdigit()
+        ):
+            return backend.load_snapshot(module_id, int(rollback_to))
+        if isinstance(rollback_to, str) and rollback_to.startswith("manual:"):
+            return backend.load_checkpoint(module_id, rollback_to)
+        return None
+
+    async def run(self, max_ticks: int = 100):
+        """执行翻译 → 构建 → 运行。一步跑完。
+
+        persist=True 时：每 tick 由 tickflow ``_persist_tick`` 落盘最小快照，
+        并归档本次 spec/tasklist 到 module_inputs 表（``_archive_module_inputs``）。
+        """
+        try:
+            runner = await self._build_runner_async()
+        except Exception as e:
+            self._write_phase("aborted", error=str(e))
+            raise
+        return await self._run_with_phases(runner, max_ticks)
+
+    async def _run_with_phases(self, runner: AsyncRunner, max_ticks: int) -> list:
+        """归档本次输入 → 运行 → 按结果映射终态 phase（run/resume 共用）。"""
+        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)
+        return firings
+
+    def _archive_module_inputs(self) -> None:
+        """归档本次运行的 spec/tasklist 到 module_inputs 表（警告 1 对比源）。
+
+        run()/resume() 共用（_run_with_phases 开头调用）；resume 中位于
+        兼容性校验与 restore 之后——先读旧存档再覆盖，顺序正确。
+        """
+        if not self.persist:
+            return
+        if self._input_store is None:
+            self._input_store = ModuleInputStore(self.module_id)
+        assert self._last_tasklist is not None
+        self._input_store.save_module_inputs(
+            self.spec.to_dict(), self._last_tasklist.to_dict()
+        )
+
+    def _finalize_phase(self, runner: AsyncRunner) -> None:
+        """按 runner.status 映射终态 phase（run/resume 共用）。"""
+        from tickflow.runner import RunStatus
+        if runner.status == RunStatus.ABORTED:
+            self._write_phase("aborted", error=runner.cancel_reason or "aborted")
+        elif runner.status == RunStatus.CANCELLED:
+            self._write_phase("cancelled", error=runner.cancel_reason or "cancelled")
+        elif runner.status == RunStatus.FAILED:
+            self._write_phase("aborted", error="all nodes failed")
+        elif runner.status == RunStatus.RUNNING:
+            self._write_phase("running")   # max_ticks 截断：仍在运行
+        else:
+            self._write_phase("done")
+
+    async def resume(self, rollback_to: int | str, max_ticks: int = 100):
+        """跨进程续跑：从 tick 号/手动检查点恢复 + 用当前 spec/tasklist 重建未执行部分。
+
+        流程：回退目标解析（tick 号 → snapshots 表；manual:xxx → checkpoints
+        表）→ 新图全量重建 → 兼容性校验（硬错误拒绝，不触碰 runner）→
+        restore → 归档新输入 → 续跑。
+
+        要求 persist=True（快照依赖 SQLite backend）。
+
+        max_ticks 是绝对 tick 上限：从 restore 的 tick 起继续计数（如
+        restore 于 tick 95，则默认 100 只剩 5 个 tick 可跑）。
+        """
+        if not self.persist:
+            raise RuntimeError(
+                "resume 需要 persist=True（快照依赖 SQLite backend）"
+            )
+
+        # 1. 回退目标解析 + 已执行节点（同一连接，避免多次打开 run.sqlite）
+        backend = SqliteBackend(_persist_dir(self.module_id))
+        try:
+            snap = self._resolve_target(backend, self.module_id, rollback_to)
+            if snap is None:
+                ticks = backend.list_snapshots(self.module_id)
+                manual = [label for label, _ in backend.list_checkpoints(self.module_id)]
+                raise KeyError(
+                    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))
+            }
+        finally:
+            backend.close()
+
+        # 2. 旧输入存档（警告 1 对比源；覆盖前读取）
+        store = ModuleInputStore(self.module_id)
+        try:
+            old_inputs = store.load_module_inputs()
+        finally:
+            store.close()
+
+        # 3. 新 spec/tasklist 全量重建（含校验 + 一致性审核）
+        try:
+            runner = await self._build_runner_async()
+        except Exception as e:
+            self._write_phase("aborted", error=str(e))
+            raise
+
+        # 4. 兼容性校验（构造 runner 后、restore 前；硬错误拒绝且不触碰状态）
+        marking = snap.get("marking") or {}
+        old_tl = tasklist_from_dict(old_inputs["tasklist"]) if old_inputs else None
+        check = check_resume_compat(
+            self._last_tasklist, runner.graph, executed_nodes,
+            old_tasklist=old_tl,
+            marking_slots=marking.get("slots"),
+            armed_starts=marking.get("armed_starts"),
+        )
+        for w in check.warnings:
+            log.warning("resume 兼容性警告: %s", w)
+        if check.hard_errors:
+            self._write_phase("aborted", error="resume 兼容性校验失败")
+            raise ResumeError(check.hard_errors)
+
+        # 5. restore + 续跑（phase 写盘与 run() 共用；不再 remap_graph——
+        #    restore 已设好 marking，同图 remap 是 no-op，C2）
+        runner.restore(snap)
+        return await self._run_with_phases(runner, max_ticks)

module_harness/outputfmt.py

@@ -0,0 +1,139 @@
+"""OutputFormat 输出格式约束定义 + OutputValidator 校验器。"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any, Callable, Literal
+
+from tickflow import Failure
+
+
+@dataclass
+class OutputFormat:
+    """输出格式约束定义。
+
+    ``type`` 为 "json_object" 时要求合法 JSON；
+    "json_schema" 时还需 ``schema`` 校验通过；
+    "text" 时不做校验，直接返回原文本。
+    """
+    type: Literal["json_object", "json_schema", "text"]
+    schema: dict[str, Any] | None = None
+    instruction: str | None = None
+
+
+# ── 内置提取器 ──────────────────────────────────────────────────
+
+def _strip_markdown_fences(raw: str) -> str | None:
+    """去除 ```json ... ``` 包裹。"""
+    pattern = r'```(?:json)?\s*\n?(.*?)\n?```'
+    m = re.search(pattern, raw, re.DOTALL)
+    if m:
+        return m.group(1).strip()
+    return None
+
+
+def _extract_first_json(raw: str) -> str | None:
+    """匹配第一个完整 JSON 对象或数组。"""
+    # 先尝试 match 对象
+    m = re.search(r'\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}', raw, re.DOTALL)
+    if m:
+        return m.group(0)
+    # 再尝试 match 数组
+    m = re.search(r'\[[^\[\]]*(?:\[[^\[\]]*\][^\[\]]*)*\]', raw, re.DOTALL)
+    if m:
+        return m.group(0)
+    return None
+
+
+def _strip_trailing_junk(raw: str) -> str | None:
+    """从末尾逐步截断非 JSON 字符，尝试解析。"""
+    s = raw.strip()
+    while s:
+        try:
+            json.loads(s)
+            return s
+        except json.JSONDecodeError:
+            pass
+        s = s[:-1]
+    return None
+
+
+# ── OutputValidator ──────────────────────────────────────────────
+
+class OutputValidator:
+    """输出格式校验器。
+
+    校验流程：先直接解析，失败则逐个尝试提取器；提取再失败 → Failure(type="llm")。
+    """
+
+    def __init__(self, fmt: OutputFormat) -> None:
+        self.fmt = fmt
+        self._extractors: list[Callable[[str], str | None]] = [
+            _strip_markdown_fences,
+            _extract_first_json,
+            _strip_trailing_junk,
+        ]
+
+    def prompt_instruction(self) -> str:
+        """生成注入到 user prompt 的格式约束文本。"""
+        if self.fmt.instruction is not None:
+            return self.fmt.instruction
+        if self.fmt.type == "text":
+            return ""
+        if self.fmt.type == "json_object":
+            return "请输出合法 JSON，不要包含任何解释或其他文本。"
+        if self.fmt.type == "json_schema":
+            schema_text = json.dumps(self.fmt.schema, ensure_ascii=False, indent=2)
+            return (
+                "请严格按照以下 JSON Schema 输出，不要包含任何解释或其他文本：\n"
+                f"```json\n{schema_text}\n```"
+            )
+        return ""
+
+    def validate(self, raw: str) -> Any:
+        """校验并返回解析值，或 Failure(type="llm")。"""
+        if self.fmt.type == "text":
+            return raw
+
+        # Step 1: 直接解析
+        parsed, error = self._try_parse(raw)
+        if parsed is not None and error is None:
+            return parsed
+
+        # Step 2: 逐个尝试提取器
+        for extractor in self._extractors:
+            extracted = extractor(raw)
+            if extracted is not None:
+                parsed, error = self._try_parse(extracted)
+                if parsed is not None and error is None:
+                    return parsed
+
+        return Failure(
+            f"输出格式校验失败：{error or '所有提取器均未能修复输出'}",
+            type="llm",
+        )
+
+    def register_extractor(self, fn: Callable[[str], str | None]) -> None:
+        """注册自定义提取策略。插入到内置提取器之前（优先尝试）。"""
+        self._extractors.insert(0, fn)
+
+    def _try_parse(self, text: str) -> tuple[Any, str | None]:
+        """尝试 json.loads + 可选的 schema 校验。返回 (parsed, error)。"""
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError as e:
+            return None, str(e)
+
+        if self.fmt.type == "json_schema" and self.fmt.schema is not None:
+            try:
+                import jsonschema
+                jsonschema.validate(parsed, self.fmt.schema)
+            except ImportError:
+                # jsonschema 未安装时跳过 schema 校验，仅保证是 JSON
+                pass
+            except jsonschema.ValidationError as e:
+                return None, str(e)
+
+        return parsed, None

module_harness/prompt.py

@@ -0,0 +1,84 @@
+# module_harness/prompt.py
+"""三层 prompt 渲染 + 关键词替换。"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from tickflow.views import DictView, Missing
+
+from .config import HarnessConfig
+
+# 常量正则模块级编译一次（render 每 harness 节点每 tick 调用）。
+_PLACEHOLDER_RE = re.compile(r"\{(\w+)\}")
+
+
+class PromptRenderer:
+    """三层 prompt 拼接 + 关键词替换。
+
+    数据来源：
+      Layer 1: config.prompt_core       — 核心提示词模板，含 {key} 占位符
+      Layer 2: config.prompt_modes[mode]  — 由 Task promptmode 选出的动态 prompt
+      Layer 3: prompt_extra             — Task prompt 字段，人工注入部分
+
+    关键词替换：模板中的 {key} 从 DictView 取值（view.key.value）。
+    未匹配的 key 保留原样（不隐藏问题）。
+    """
+
+    def __init__(self, config: HarnessConfig) -> None:
+        self.config = config
+
+    def render(
+        self,
+        view: DictView,
+        *,
+        promptmode: str | None = None,
+        prompt_extra: str | None = None,
+        extra_values: dict[str, Any] | None = None,
+    ) -> str:
+        """渲染最终 user prompt。
+
+        ``extra_values``：占位符兜底值（如 spec 字段常量），
+        view 中缺失的 key 从该 dict 取值。
+        """
+        parts: list[str] = []
+
+        # Layer 1: 核心提示词
+        parts.append(self.config.prompt_core)
+
+        # Layer 2: 由 promptmode 选出的动态 prompt
+        if promptmode is not None:
+            mode_text = self.config.prompt_modes[promptmode]
+            parts.append(mode_text)
+
+        # Layer 3: 人工注入
+        if prompt_extra:
+            parts.append(prompt_extra)
+
+        combined = "\n\n".join(parts)
+        return self._substitute(combined, view, extra_values)
+
+    def _substitute(
+        self,
+        template: str,
+        view: DictView,
+        extra_values: dict[str, Any] | None = None,
+    ) -> str:
+        """替换模板中的 {key} 占位符为 view 中的值。"""
+
+        def _replacer(m: re.Match) -> str:
+            key = m.group(1)
+            try:
+                val = view[key].value
+            except (KeyError, AttributeError):
+                if extra_values and key in extra_values:
+                    return str(extra_values[key])
+                return m.group(0)  # 保留原样
+            if val is Missing:
+                if extra_values and key in extra_values:
+                    return str(extra_values[key])
+                return m.group(0)
+            return str(val)
+
+        return _PLACEHOLDER_RE.sub(_replacer, template)