specmodule 0.1.0__py3-none-any.whl

module_harness/translator.py

@@ -0,0 +1,314 @@
+"""翻译器：TasklistValidator + TemplateLoader + Translator。"""
+
+from __future__ import annotations
+
+import contextlib
+import inspect
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+from tickflow import Failure, parse as parse_graph
+from tickflow.views import DictView, Resolved
+
+from .config import HarnessConfig
+from .harness import Harness
+from .spec import Spec, Tasklist, TasklistTemplate, TaskDefinition
+from .registry import HarnessRegistry
+
+# Regex to find the first node name in a flow line.
+_FIRST_NODE = re.compile(r"^[ \t]*\[?(?P<name>[A-Za-z_][A-Za-z0-9_]*)")
+
+
+@contextlib.contextmanager
+def _suppress_parse_noise():
+    """构建/校验期暂时抑制 ``tickflow.parser`` 的结构性假阳性 warning。
+
+    ModuleHarness 在 ``parse`` **之后**才附加节点 body（isolated 名含 ``:``，
+    DSL body 声明无法表达），故 parse 期所有 producer 被判为 body-less，触发
+    ``node X reads input from Y which has no body`` 假阳性（submodule 漏斗
+    会放大到每条输入边）。真实结构错误仍以 ``ParseError`` 抛出，不受影响。
+    作用域限定在调用方，退出即恢复原日志级别。
+    """
+    parser_log = logging.getLogger("tickflow.parser")
+    prev = parser_log.level
+    parser_log.setLevel(logging.ERROR)
+    try:
+        yield
+    finally:
+        parser_log.setLevel(prev)
+
+
+def prepare_flow(flow: str) -> str:
+    """Ensure the flow text is valid tickflow DSL.
+
+    The tasklist ``flow`` field uses a tickflow-like syntax but allows
+    bare task names as the whole flow (meaning that task is both the
+    start and the only node).  This function:
+      * wraps a bare name as ``[name]``, and
+      * wraps the first token in ``[...]`` when no start marker exists
+        (only one start is added for the simplest case).
+    """
+    stripped = flow.strip()
+
+    # Single bare name -> start node.
+    if "--> " not in stripped and "-->[" not in stripped and stripped.startswith("[") is False:
+        if _FIRST_NODE.fullmatch(stripped):
+            return f"[{stripped}]"
+
+    # Multi-node flow with no ``[start]`` marker at all.
+    if "[" not in stripped:
+        m = _FIRST_NODE.match(stripped)
+        if m:
+            first = m.group("name")
+            idx = m.end("name")
+            return f"[{first}]{stripped[idx:]}"
+
+    return stripped
+
+
+class TasklistValidator:
+    """校验 tasklist 的结构合法性与引用完整性。"""
+
+    @staticmethod
+    def validate(
+        tasklist: Tasklist,
+        registry: HarnessRegistry,
+        modules: dict[str, Any] | None = None,
+    ) -> list[str]:
+        """返回问题列表，空列表 = 合法。``modules`` 为 submodule 名解析表
+        （None = 跳过名字校验，向后兼容）。"""
+        errors: list[str] = []
+
+        for key, task in tasklist.tasks.items():
+            errors.extend(TasklistValidator._check_task(key, task, registry, modules))
+
+        errors.extend(TasklistValidator._check_flow(tasklist, registry))
+        return errors
+
+    @staticmethod
+    def _check_task(
+        key: str,
+        task: TaskDefinition,
+        registry: HarnessRegistry,
+        modules: dict[str, Any] | None = None,
+    ) -> list[str]:
+        errors: list[str] = []
+
+        if task.type == "harness":
+            if not task.harness:
+                errors.append(f"Task '{key}': type='harness' 但缺少 'harness' 字段")
+            elif not registry.is_harness(task.harness) and not registry.has_body(task.harness):
+                errors.append(f"Task '{key}': harness '{task.harness}' 未在 registry 中注册")
+        elif task.type == "script":
+            if not task.script:
+                errors.append(f"Task '{key}': type='script' 但缺少 'script' 字段")
+            elif not registry.is_script(task.script) and not registry.has_body(task.script):
+                errors.append(f"Task '{key}': script '{task.script}' 未在 registry 中注册")
+        elif task.type == "command":
+            if not task.command:
+                errors.append(f"Task '{key}': type='command' 但缺少 'command' 字段")
+            elif not registry.is_command(task.command) and not registry.has_body(task.command):
+                errors.append(f"Task '{key}': command '{task.command}' 未在 registry 中注册")
+        elif task.type == "submodule":
+            if not task.submodule:
+                errors.append(f"Task '{key}': type='submodule' 但缺少 'submodule' 字段")
+            elif modules is not None and task.submodule not in modules:
+                errors.append(f"Task '{key}': submodule '{task.submodule}' 未在 modules 中声明")
+        else:
+            errors.append(f"Task '{key}': 未知 type '{task.type}'")
+
+        return errors
+
+    @staticmethod
+    def _check_flow(tasklist: Tasklist, registry: HarnessRegistry) -> list[str]:
+        errors: list[str] = []
+        task_keys = set(tasklist.tasks.keys())
+
+        # 解析 flow 得到 node 名（简单正则提取 mermaid 中的节点）
+        # 匹配 A --> B, [A]-->B, A--|g|-->B 等
+        node_names: set[str] = set()
+        flow = prepare_flow(tasklist.flow)
+        # 匹配 start marker [X]
+        for m in re.finditer(r'\[(\w+)\]', flow):
+            node_names.add(m.group(1))
+        # 匹配 X--|...|-->Y 和 X-->Y
+        for m in re.finditer(r'(\w+)\s*(?:--\|?\w*\|?)?-->', flow):
+            node_names.add(m.group(1))
+        for m in re.finditer(r'-->\s*(\w+)', flow):
+            node_names.add(m.group(1))
+
+        # 检查 flow 中出现但不在 tasks 中的节点
+        for node in node_names:
+            if node not in task_keys:
+                errors.append(f"Flow 中引用了未定义的节点 '{node}'")
+
+        # 检查 tasks 中定义了但不在 flow 中的孤立节点
+        for key in task_keys:
+            if key not in node_names:
+                errors.append(f"Task '{key}' 在 Flow 中未被引用（孤立节点）")
+
+        # 尝试 tickflow parse 检测语法问题（与 graph_builder 使用相同的 prepare_flow 预处理）
+        try:
+            with _suppress_parse_noise():
+                parse_graph(prepare_flow(flow), registry=registry)
+        except Exception as e:
+            errors.append(f"Flow 解析失败: {e}")
+
+        return errors
+
+
+class TemplateLoader:
+    """加载与管理 tasklist 模板。"""
+
+    def __init__(self) -> None:
+        self._templates: dict[str, TasklistTemplate] = {}
+
+    def register(self, name: str, data: dict[str, Any]) -> None:
+        """注册一个模板（代码调用或文件加载）。data 直接过 from_json。"""
+        self._templates[name] = TasklistTemplate.from_json(data)
+
+    def get(self, name: str) -> TasklistTemplate | None:
+        return self._templates.get(name)
+
+    def list_names(self) -> list[str]:
+        return list(self._templates.keys())
+
+    def load_directory(self, path: str | Path) -> int:
+        """从目录加载 .json 模板文件。返回加载数量。"""
+        p = Path(path)
+        count = 0
+        if p.is_dir():
+            for f in sorted(p.glob("*.json")):
+                try:
+                    data = json.loads(f.read_text(encoding="utf-8"))
+                    self.register(data["name"], data)
+                    count += 1
+                except (json.JSONDecodeError, KeyError, ValueError):
+                    pass  # 跳过无效文件
+        return count
+
+    def load_builtins(self) -> int:
+        """加载内置模板（module_harness/templates/builtin/）。"""
+        builtin_dir = Path(__file__).parent / "templates" / "builtin"
+        return self.load_directory(builtin_dir)
+
+
+class Translator:
+    """spec -> tasklist 翻译器。直接调 body/script，不走 tickflow runner。"""
+
+    def __init__(self, registry: HarnessRegistry) -> None:
+        self.reg = registry
+
+    async def translate(self, spec: Spec, template: TasklistTemplate) -> Tasklist:
+        """执行翻译并返回校验通过的 Tasklist。"""
+        ts = template.translation
+
+        if ts.type == "script":
+            tasks_dict = await self._call_script_translator(ts.script, spec)
+        elif ts.type == "harness":
+            tasks_dict = await self._call_harness_translator(ts.harness, ts.prompt, spec, prompt_core=ts.prompt_core)
+        else:
+            raise ValueError(f"不支持的 translation type: {ts.type}")
+
+        # 检测 LLM 返回的包装格式 {"Tasks": {...}, "Flow": "..."}
+        flow = template.tasklist.flow
+        if isinstance(tasks_dict, dict) and "Tasks" in tasks_dict:
+            flow = tasks_dict.get("Flow", flow)
+            tasks_dict = tasks_dict["Tasks"]
+
+        # 兼容 LLM 将 Tasks 输出为数组：转为 {A: ..., B: ...} 格式
+        if isinstance(tasks_dict, list):
+            import string
+            tasks_dict = {
+                string.ascii_uppercase[i]: td
+                for i, td in enumerate(tasks_dict)
+            }
+        # 兼容 LLM 将 Flow 输出为数组：["A","B"] → "A --> B"
+        if isinstance(flow, list):
+            flow = " --> ".join(str(n) for n in flow)
+        # 规范化 Flow 语法：容忍 LLM 常见的格式偏差
+        if isinstance(flow, str):
+            flow = flow.replace("→", "-->")           # unicode → ASCII
+            flow = flow.replace("--->", "-->")         # 防止已经含 --> 的再替换
+            if "-->" not in flow:
+                flow = flow.replace("->", "-->")
+
+        # 构建 tasklist 并校验
+        tasklist = Tasklist(tasks={
+            key: TaskDefinition.from_dict(td) if isinstance(td, dict) else td
+            for key, td in tasks_dict.items()
+        }, flow=flow)
+
+        errors = TasklistValidator.validate(tasklist, self.reg)
+        if errors:
+            raise ValueError(f"翻译结果校验失败:\n" + "\n".join(f"  - {e}" for e in errors))
+
+        return tasklist
+
+    async def _call_script_translator(self, script_name: str, spec: Spec) -> dict:
+        """直接调用已注册的 script 函数。"""
+        body = self.reg.get_body(script_name)
+        view = DictView(
+            {"spec": Resolved(value=spec.to_dict(), k=None)},
+            node="__translator__",
+        )
+        result = body(view)
+        if inspect.isawaitable(result):
+            result = await result
+        return result
+
+    async def _call_harness_translator(
+        self,
+        harness_name: str,
+        prompt_extra: str,
+        spec: Spec,
+        prompt_core: str | None = None,
+    ) -> dict:
+        """调用 harness body（异步 LLM），parse 返回的 JSON 为 task dict。
+
+        如果提供 *prompt_core*，则覆盖原 harness 配置的核心提示词模板。
+        """
+        if prompt_core is not None:
+            existing = self.reg.harness_config(harness_name)
+            if existing is not None:
+                overridden = HarnessConfig(
+                    prompt_core=prompt_core,
+                    prompt_modes=dict(existing.prompt_modes),
+                    output_format=existing.output_format,
+                    notdo=list(existing.notdo),
+                    model=existing.model,
+                    temperature=existing.temperature,
+                    think=existing.think,
+                    api_params=dict(existing.api_params),
+                )
+                h = Harness(overridden, self.reg._llm_client, self.reg._event_bus)
+                body = h.build_body()
+            else:
+                raise ValueError(
+                    f"Translation harness '{harness_name}' not found in registry"
+                )
+        else:
+            body = self.reg.get_body(harness_name)
+
+        view_data: dict[str, Resolved] = {"spec": Resolved(value=spec.to_dict(), k=None)}
+        if prompt_extra:
+            view_data["prompt_extra"] = Resolved(value=prompt_extra, k=None)
+        view = DictView(view_data, node="__translator__")
+        result = await body(view)
+
+        if isinstance(result, Failure):
+            raise ValueError(f"翻译 harness 返回 Failure: {result.error}")
+
+        if isinstance(result, str):
+            try:
+                return json.loads(result)
+            except json.JSONDecodeError as e:
+                raise ValueError(f"翻译结果不是合法 JSON: {e}") from e
+
+        if isinstance(result, dict):
+            return result
+
+        raise ValueError(f"翻译结果类型异常: {type(result).__name__}")

specmodule-0.1.0.dist-info/METADATA

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: specmodule
+Version: 0.1.0
+Summary: 可审计、可调试、可完全掌控的 LLM 使用框架（tickflow + llm + module_harness）
+License: MIT
+Keywords: llm,workflow,petri-net,agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tickflow-py>=0.1.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai; extra == "openai"
+Provides-Extra: validate
+Requires-Dist: jsonschema; extra == "validate"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# SpecModule
+
+可审计、可调试、可完全掌控的 LLM 使用框架。
+
+将 LLM 调用拆分为可组合的 Petri 网节点，每个节点是最小执行单元——翻译、审查、shell 命令、Python 函数。节点通过有向边连接（支持 AND/OR 汇合、循环），引擎以同步步进执行，所有状态集中记录。**每 tick 落盘轻量快照**，快照、暂停、精确回退（tick 号）都是低开销的。
+
+## 架构
+
+```
+SpecModule/
+├── tickflow                # Petri 网工作流引擎（外部 pip 依赖 tickflow-py，import 名 tickflow）
+├── llm/                    # LLM 客户端（Anthropic + OpenAI 兼容）
+│   ├── client.py
+│   └── config.py
+├── module_harness/        # Module 上层抽象
+│   ├── module.py          #   Module 编排器（run/resume/snapshot/rollback）
+│   ├── registry.py        #   HarnessRegistry（harness / script / command 注册）
+│   ├── harness.py         #   Harness 类（LLM 调用节点，三层 prompt）
+│   ├── command.py         #   Command 节点（shell 子进程）
+│   ├── prompt.py          #   三层 prompt 渲染
+│   ├── outputfmt.py       #   输出格式校验 + 自动提取
+│   ├── spec.py            #   Spec, Tasklist, TasklistTemplate 数据模型
+│   ├── translator.py      #   spec → tasklist 翻译 + 校验 + 模板加载
+│   ├── graph_builder.py   #   tasklist → tickflow Graph
+│   ├── consistency.py     #   spec + tasklist 一致性审核
+│   ├── align.py           #   对齐检查 harness
+│   ├── checkpoint.py      #   运行输入存档 + resume 兼容性校验
+│   ├── status.py          #   跨进程运行状态查询
+│   ├── submodule.py       #   类式 module 定义 + 打包发布
+│   ├── loader.py          #   module 加载 + 依赖校验
+│   ├── builtins.py        #   内置 harness 集
+│   ├── events.py          #   EventBus + 类型化事件
+│   ├── entry.py           #   ModuleEntry 入口合约 + 目录发现
+│   ├── scaffold.py        #   init 脚手架生成（单文件 + --as-dir 目录形态）
+│   ├── store.py           #   store 共享层（家目录/搜索路径/枚举/安装管理）
+│   ├── feed.py            #   零依赖运行 feed（http.server，CLI feed 命令）
+│   ├── query.py           #   共享查询层（时间线/检查点，CLI/MCP/Web 复用）
+│   ├── cli.py             #   specmodule CLI（18 子命令，argparse 零依赖）
+│   ├── templates/         #   内置任务模板
+│   └── tests/             #   pytest 测试套件（含真实 LLM smoke）
+└── docs/                  # 设计文档、实现计划、路线图
+```
+
+## 安装依赖
+
+```bash
+# 库：pip 安装（pyproject.toml + console script `specmodule`）
+pip install specmodule
+
+# 开发（本仓库）：源码 + 测试依赖
+pip install -r requirements.txt
+```
+
+| 包 | 用途 | 必需 |
+|----|------|------|
+| **`specmodule`** | 库本体（PyPI 名；`pyproject.toml` 打包：`llm` + `module_harness` + CLI `specmodule`） | ✅ 必需 |
+| **`tickflow-py`** | Petri 网工作流引擎。⚠️ PyPI 包名为 `tickflow-py`，**import 名仍为 `tickflow`**（`import tickflow`，不是 `import tickflow_py`）。上游仓库：https://github.com/MountLynx/tickflow- | ✅ 必需 |
+| `anthropic` | Claude 后端（`provider=anthropic` 时） | 按 provider 选装 |
+| `openai` | OpenAI 及兼容后端（`provider=openai` / `openai-compatible` 时） | 按 provider 选装 |
+| `jsonschema` | `json_schema` 输出格式校验（未安装则跳过 schema 校验，仅保证是 JSON） | 推荐 |
+| `pytest` | 测试套件（`python -m pytest module_harness/tests/ -q`） | 仅开发 |
+
+安装后 CLI 即用（`specmodule run/status/review/...`，18 个子命令，见 `docs/cli-usage.md`）；不写 module 的使用者走 store 闭环：`specmodule setup` 配 key → `install` 装模块 → `list`/`run` → `update`/`uninstall`。
+
+## 快速开始
+
+```python
+from module_harness import Module, HarnessRegistry, HarnessConfig, EventBus
+from module_harness import TemplateLoader, OutputFormat
+from llm import create_llm_client, LLMConfig
+
+# 1. 准备 LLM 客户端（LLM_PROVIDER / API key 从环境或 .env 读取）
+config = LLMConfig.from_env()
+client = create_llm_client(config)
+bus = EventBus()
+
+# 2. 注册 harness 和 script
+reg = HarnessRegistry(llm_client=client, event_bus=bus)
+
+reg.harness("translate", HarnessConfig(
+    prompt_core="将以下文本翻译为中文：{text}",
+    output_format=OutputFormat(type="json_object"),
+    notdo=["不要添加解释"],
+    temperature=0.3,
+))
+
+@reg.script("format_output")
+def format_output(view):
+    data = view.A.value
+    return {"result": data["translation"].strip()}
+
+# 3. 加载内置模板（spec only → 翻译通道）
+loader = TemplateLoader()
+loader.load_builtins()
+
+# 4. 运行（persist=True 时每 tick 落盘轻量快照，可精确回退）
+module = Module(
+    spec={"source_text": "Hello world", "style": "formal"},
+    template_name="translate",
+    llm_client=client,
+    event_bus=bus,
+    template_loader=loader,
+)
+
+firings = await module.run()
+for f in firings:
+    print(f"{f.node}: {f.output}")
+
+# 5. 续跑与回退（跨进程）
+await module.resume(rollback_to=3)          # 精确回退到 tick 3 后重跑
+module.list_checkpoints()                    # [(tick, fired 节点列表, kind), ...]
+
+# 6. 封装打包：类式定义 → pack 发布 → 加载运行
+from module_harness import SubModule, SpecSchema, TaskDefinition, ModuleLoader, script
+
+class Translator(SubModule):
+    """带风格选择的翻译 module（类式定义 + spec_schema 输入契约）。"""
+    name = "my_translator"
+    version = "1.0.0"
+    description = "带风格选择的翻译 module"
+    spec_schema = SpecSchema(
+        input={"source_text": "str", "style": "str"},
+        output={"translation": "str"},
+    )
+    harnesses = [HarnessConfig(
+        name="translate",
+        prompt_core="翻译：{text}",
+        prompt_modes={"formal": "正式", "casual": "随意"},
+        output_format=OutputFormat(type="json_object"),
+    )]
+    tasklist = Tasklist(
+        tasks={
+            "A": TaskDefinition(
+                type="harness", harness="translate",
+                promptmode="{spec.style}",          # spec 字段驱动 promptmode
+                inputs={"text": "{spec.source_text}"},
+                outputformat={"type": "json_object"},
+            ),
+            "B": TaskDefinition(
+                type="script", script="format_output", inputs={"data": "A"},
+            ),
+        },
+        flow="A --> B",
+    )
+
+    @script("format_output")
+    def format_output(view):
+        return {"translation": view.A.value["translation"].strip()}
+
+# 直接运行（spec 经 spec_schema 契约校验）
+await Translator(llm_client=client).run({"source_text": "Hello", "style": "formal"})
+
+# 打包发布：导出 module.json + harnesses/ + scripts/ + commands/
+dist = Translator().pack("dist/my_translator")
+
+# 另一进程/项目加载运行（requires 依赖校验，无需重新定义）
+loaded = ModuleLoader().load(dist)
+await loaded.run({"source_text": "Hello", "style": "casual"})
+```
+
+## 嵌入式使用（宿主项目 import 库）
+
+`pip install specmodule` 后另建项目直接 `import` 库面编程 API，把 SpecModule
+当 LLM 工具套件嵌入自己的服务/IDE 插件/Web 后端。最小 demo 见
+[`examples/embed_minimal/`](examples/embed_minimal/main.py)（包含 `--mock`
+免 key 冒烟，可直接运行验证）：
+
+```bash
+pip install specmodule
+cd examples/embed_minimal && python main.py --mock
+```
+
+```python
+from module_harness import (
+    EventBus, HarnessConfig, HarnessRegistry, Module,
+    TemplateLoader, OutputFormat, register_builtin_harnesses,
+)
+from llm import LLMConfig, create_llm_client
+
+client = create_llm_client(LLMConfig.from_env())   # .env / 环境变量
+bus = EventBus()
+
+reg = HarnessRegistry(llm_client=client, event_bus=bus)
+register_builtin_harnesses(reg)                    # spec_to_tasklist 等内置集
+reg.harness("translate", HarnessConfig(
+    prompt_core="将以下文本翻译为中文：{text}",
+    output_format=OutputFormat(type="json_object"),
+))
+
+loader = TemplateLoader(); loader.load_builtins()
+module = Module(
+    spec={"source_text": "Hello world", "style": "formal"},
+    template_name="translate",
+    llm_client=client, event_bus=bus, registry=reg, template_loader=loader,
+    persist=False, status_file=False, keep_records=False,   # 嵌入方零落盘/零残留
+)
+await module.run()
+```
+
+嵌入要点：
+
+- **事件与 records 解耦**（`decouple-embed-events`）——宿主传 `event_bus` 即收
+  `OutputValidated` / `HarnessFailed` 等事件做反馈，不拖审计与落盘；不传则静默零开销。
+- **零残留可选**——`persist=False` + `status_file=False` + `keep_records=False`
+  时嵌入方磁盘上不留任何 `.specmodule/` 产物。
+- **内置 harness 显式注册**——翻译/审核/对齐 harness 不走隐式加载，
+  宿主对 `HarnessRegistry` 调 `register_builtin_harnesses(reg)` 注册。
+- 库面 = `module_harness` 顶层导出（`Module / HarnessRegistry / SubModule /
+  Translator / query` 共享层……），导入勿触达内部子模块。
+
+## 核心概念
+
+### 三种节点类型
+
+| 类型 | 用途 | 注册方式 |
+|------|------|----------|
+| **harness** | LLM 调用 — 三层 prompt、输出校验、流式 token | `reg.harness("name", config)` |
+| **script** | 纯 Python 函数 — 处理、计算、IO | `@reg.script("name")` |
+| **command** | Shell 命令 — 一行字符串即节点 | `reg.command("name", CommandConfig(...))` |
+
+### spec 与 tasklist
+
+- **spec** — 结构化键值对，描述"想要什么"。无预定义 schema，字段由模板设计者定义。
+- **tasklist** — `{Tasks: {A: {...}, B: {...}}, Flow: "A --> B"}`。描述"如何做"，每个 Task 映射为一个 tickflow 节点。
+- **两种输入**：① 只传 spec（通过模板翻译为 tasklist）② 传 spec + tasklist（一致性审核后直入 graph builder）。
+
+### 快照与回滚（roadmap #5）
+
+- **每 tick 轻量快照**：persist=True 时由引擎逐 tick 落盘（剥离审计 records，O(节点+边) 恒定大小），任意 tick 可回退
+- **精确 tick 号回退**：`resume(tick)` 跨进程续跑，只重跑未执行部分（已执行节点输出保留）；手动检查点 `checkpoint("label")` / `rollback_to("label")` 永久保留
+- **`list_checkpoints()`**：显示 `(tick, fired 节点列表, kind)`——tick ↔ 节点轨迹，历史审阅的雏形
+- **进程内** `snapshot()` / `restore()` 全量快照，任意分支/回退
+
+### 运行状态查询（roadmap #7）
+
+跨进程查询：`status.json`（阶段机：idle → translating → reviewing → ... → done）+ `run.sqlite` 最新快照（tick 级：status/tick/fireable/fired + 每节点最新输出）。任何进程可查，不依赖 Module 实例。
+
+```python
+from module_harness import query_run_status
+st = query_run_status("my_module")     # ModuleStatus：phase/tick/fired/outputs/node_states
+```
+
+### submodule — 类式 module + 打包发布
+
+```python
+from module_harness import SubModule, script, SpecSchema
+
+class Dig(SubModule):
+    name = "dig"
+    spec_schema = SpecSchema(input={"url": "str"})
+    tasklist = Tasklist(tasks={...}, flow="...")
+
+    @script("fetch")
+    def fetch(view):
+        return {"html": ...}
+```
+
+`SubModule` 类式声明（含 `spec_schema` 输入契约）→ `pack()` 导出可发布清单 → `ModuleLoader` 加载（`requires` 依赖校验）。`mode = "fast"` 零落盘运行。
+
+### 一致性审核与对齐检查
+
+- **一致性审核** — 自定义 tasklist 通道默认经内置审核 harness（`spec_tasklist_review`）做 spec↔tasklist 语义一致性 LLM 审核，不通过抛 `ConsistencyError` 阻塞
+- **对齐检查** — 内置 `align_check` 节点，对比 spec 目标与产出，输出对齐/偏离分析 + 建议
+
+### 事件系统
+
+EventBus 提供两层事件——流程级（tickflow hooks：`on_fire`、`on_tick_end`）和节点内部事件（EventBus：prompt 渲染、token 流、命令执行、校验结果）。消费者按需订阅。
+
+### 命名空间隔离
+
+多个 Module 可在同一进程中共存，body 以 `{module_id}:{key}` 前缀隔离注册。
+
+## 当前状态
+
+**库核心框架能力已完成**（18 项）；**库自身主线已完成**（2026-08-22）：打包接线
+（`pyproject.toml` + `specmodule` CLI 随库分发）、module-user-store 全系列
+（store 家目录 / 配置回退链 / 统一枚举 run 打通 / CLI 管理面 setup-install-list-info-
+uninstall-publish-update / init 目录形态）、独立线（嵌入式验证 demo + stdlib 可视化
+feed）。待做：M2 实践线（store 真实验收）、收口 API 稳定化、生态项目（TUI/MCP/Web）。
+完整进度与路线图见 [module-roadmap.md](docs/progress/module-roadmap.md)。
+
+## 开发原则
+
+- **tickflow 零修改（有条件的）** — tickflow 是外部依赖（PyPI 包 `tickflow-py`，import 名 `tickflow`，上游仓库 https://github.com/MountLynx/tickflow-），仓库内无 tickflow 代码。修改前先判断：改动是否有普适性、是否真正有助于优化 tickflow 本身？**没有 → 不碰**（模块层功能一律通过 `Registry` 子类扩展）；**有 → 在上游改**，发布新版 `tickflow-py` 并升级安装版本
+- **两级用户定位** — 框架服务两类用户：**开发者用户**（写 module 并发布）与**使用者用户**（只写 spec/tasklist）。边界不硬——开发者也是使用者，使用者也能按需修改。本质是两个使用场景（**开发场景** vs **使用场景**），新功能开发时明确主要为哪个场景服务
+- **完全掌控** — 无隐式行为，promptmode 选错直接 KeyError，框架不兜底
+- **审计即设计** — 所有状态记录在 RunState 中，快照与回滚是内置能力
+- **SDK 先行** — 新功能实现前先设计所需的数据查询接口，消费形态（CLI/agent/Web）只是 SDK 的薄封装
+- **YAGNI** — 每项功能有明确使用场景才加入
+
+## 许可证
+
+MIT

specmodule-0.1.0.dist-info/RECORD

@@ -0,0 +1,38 @@
+llm/__init__.py,sha256=V6j38-2nexAMMhdEbAOov87mMMM4ZJh7Xc0V2ijUQLA,328
+llm/client.py,sha256=qKU6HkLUZtdi03wXq8vivTuqe7Iiw5x0mHwTvu4F_To,26682
+llm/config.py,sha256=LFMo2kb9i0BspNXxDoRDQWq57Ft7PciTctGvwqqqzIk,7512
+module_harness/__init__.py,sha256=9JrtWfwJK2rIEeH5PY0SBJaEicNAhaC301gwy1qrV-Q,4812
+module_harness/align.py,sha256=YIojzfz3ExpVVp4aUc19KVSrY96TtYU3KISznSs9iBM,1420
+module_harness/builtins.py,sha256=RCmSJtAG8SDGYaRp81iJU8hVn3yiPB1JUbG1NR8lj1w,1042
+module_harness/checkpoint.py,sha256=dTewwsmWeDXPNoksx5YoNdLedvs35L9XyrqRiLVUPiM,15759
+module_harness/cli.py,sha256=PCbtloc26VYeg_d6_uIvzB2HadIFmY1fBgiKEyiiI5c,61024
+module_harness/command.py,sha256=s-YlNFhezzgqmQqI_qQlcz9xyGRirdUW7pZ96Hoc9-U,3771
+module_harness/config.py,sha256=cft9-nlavXUG7OMk6dUKBreMXUlJZD_UxkTO4Ac7ta4,3334
+module_harness/consistency.py,sha256=q0UcZaHeNYBL86EjmGo_ULGFY1FhgE_s8FX-8rjftPQ,4452
+module_harness/entry.py,sha256=EOJFjSY2yler-YLzqFpitdXE0uWL-_4XQ8PZ8DEzipg,2890
+module_harness/events.py,sha256=XMxk_FgL3I28wXjtmXTHdKBYY47-ZcgmN_8kO8NRDhM,3752
+module_harness/feed.py,sha256=szKUVcPMRd4Q2FA87avwtWLz5ktwQbtK2NyQqYdWZ-Q,7484
+module_harness/graph_builder.py,sha256=LSsd4F38YR2WJ5AnegxFt4Ijf0xPX5JLYv-_Em5Rkl8,14437
+module_harness/harness.py,sha256=0MUtKSNDpbpsA90q2N1kxtsDHNluS-ihLcJfpezpQFc,6390
+module_harness/loader.py,sha256=O3h_IrpGCYxL2gfalubw3voCyir8aafBRuKxvr2a_2w,9322
+module_harness/module.py,sha256=Tu7vMF-tQOL4rM9SkwjOZWCeQ_AXAjQyjiETV12d9SA,19543
+module_harness/outputfmt.py,sha256=tIQAPcL-Sy3Dame4yytwHYPWvK3pSRwcJ3GgZRuH_50,4763
+module_harness/prompt.py,sha256=htr83VyU79PFuokMR7GYpznsgZnTlhePWp_couYub34,2646
+module_harness/query.py,sha256=xtWchH-Ky-c_HyaUH0qU4NpaytjIQmuU3Nr48kuxHkM,7423
+module_harness/registry.py,sha256=6URtYG8g4xBkyn8tc4fWN8rKfmHpezoL1FAAP1t1iw4,6578
+module_harness/scaffold.py,sha256=fvr-GxSMnCkmemEVt0Fj1TG_7zrX5KPH2qFa3uzbIZA,13792
+module_harness/spec.py,sha256=D3ORh_yPfptrkL2GKJenawt8KJpxmSIn2ZxctgB5EZE,6625
+module_harness/status.py,sha256=BJYUgJpySjhcIirXRYkmue7Go1hkTmNav_s059MumaE,3938
+module_harness/store.py,sha256=c46hEku1BbXCQi8UKjHDMa_GAcvQMqCSTwOOVWOnqYU,17195
+module_harness/submodule.py,sha256=f2P1aG6zPyO2nDyghAR_tQq2ohlWvvKJpdYUtfTMrGI,11712
+module_harness/translator.py,sha256=5A5fNvBsFc53VhJklR9nUto8ngUYp052NZ25rcZEMGw,12423
+module_harness/templates/builtin/codereview.json,sha256=ObWAyo6UY5HabTrgU4dTqmHgfnBhNpyUhytxe3P595M,2026
+module_harness/templates/builtin/docwrite.json,sha256=krj6DVnAwrgsOzM0b800kFvbgt6KRgw2Rx07o-leBnc,740
+module_harness/templates/builtin/summarize.json,sha256=L_1RyozWygDJajyRuniiB8-15afsjus7SaoyILtyQvM,530
+module_harness/templates/builtin/translate.json,sha256=go1SBXzItpfLs5pSYZkubUiFRaaSxAZV-Qns-_wPEdo,1179
+specmodule-0.1.0.dist-info/licenses/LICENSE,sha256=25hjFkQhPrYdWcqDJ_ojqr7c3v1rLiCbOQbLJdA3Bsk,1066
+specmodule-0.1.0.dist-info/METADATA,sha256=6LfSE7WzH99IL8YgefmHaHN_Bdef_MFZ1cWWHA-KOsQ,15672
+specmodule-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+specmodule-0.1.0.dist-info/entry_points.txt,sha256=K1iJZpDfpZ8nTS_fJ1uLo-dlMaXhjDrv7pxkiqeXtr0,55
+specmodule-0.1.0.dist-info/top_level.txt,sha256=IhlN35BKPvk_H0Aqn2zlEl58RmF8xJl45Pma7ubVf8Y,19
+specmodule-0.1.0.dist-info/RECORD,,

specmodule-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+