specmodule 0.1.2__tar.gz → 0.1.3__tar.gz

{specmodule-0.1.2/specmodule.egg-info → specmodule-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specmodule
-Version: 0.1.2
+Version: 0.1.3
 Summary: 可审计、可调试、可完全掌控的 LLM 使用框架（tickflow + llm + module_harness）
 License: MIT
 Keywords: llm,workflow,petri-net,agent

{specmodule-0.1.2 → specmodule-0.1.3}/module_harness/cli.py

@@ -12,6 +12,7 @@
     python -m module_harness.cli snapshot [<tick>] [--run-id xxx] [--json] [--out FILE]
     python -m module_harness.cli rollback <目标> --module <名> [--spec ...]
     python -m module_harness.cli checkpoint <label> [<tick>] [--run-id xxx]
+    python -m module_harness.cli cancel | pause | unpause [--run-id xxx]
     python -m module_harness.cli visualize --module <名> [--tasklist x.json | --run-id xxx] [--out FILE]
 
 场景归属：使用者层面（usage scenario）——第二级用户只写 spec/tasklist，
@@ -430,10 +431,21 @@ def _run_resume_cmd(args: argparse.Namespace, *, require_target: bool) -> int:
         _check_spec_schema(res, spec)
         llm_client = _build_llm_client(args.mock)
         template_name = args.template or res.default_template
+        tasklist = _load_tasklist(args.tasklist) if args.tasklist else None
         if args.tasklist:
             # tasklist 路径：跳过翻译，template_name 置 None（与 Module
             # "template/tasklist 二选一"不变量对齐）
             template_name = None
+        elif template_name is None and tasklist is None:
+            # 流程来源兜底：显式参数 > entry.default_template > module_inputs
+            # 归档 tasklist（续跑语义本该默认沿用原任务书——tasklist 通道
+            # 启动的 run 无模板可回落，此前只能靠显式 --tasklist 续跑）
+            from .query import read_module_inputs
+
+            archived = read_module_inputs(module_id)
+            if archived and archived.get("tasklist"):
+                tasklist = Tasklist.from_json(archived["tasklist"])
+                print("流程来源：沿用 module_inputs 归档 tasklist", file=sys.stderr)
         # 回退目标：显式直传；resume 缺省（None）由库解析为最新 tick 快照
         # （须在 Module 构造前检查——构造即写 status.json idle，会覆盖前次终态）
         rollback_to = args.rollback
@@ -469,7 +481,7 @@ def _run_resume_cmd(args: argparse.Namespace, *, require_target: bool) -> int:
             mod = res.entry.build_module(
                 spec,
                 template_name=template_name,
-                tasklist=_load_tasklist(args.tasklist) if args.tasklist else None,
+                tasklist=tasklist,
                 llm_client=llm_client,
                 module_id=module_id,
                 hooks=display.hooks(),
@@ -524,6 +536,29 @@ def _latest_run_id() -> str | None:
     return max(dirs, key=lambda d: d.stat().st_mtime).name
 
 
+def _cmd_control(args: argparse.Namespace) -> int:
+    """cancel/pause/unpause 共享实现：写控制文件（运行进程 tick 边界消费）。
+
+    纯数据操作（file 即通道），不接触运行进程；前置只校验目标 run 存在
+    （status.json 落盘）。生效时机取决于运行进程的下一 tick 边界。
+    """
+    from .control import request_control
+
+    module_id = args.run_id or _latest_run_id()
+    if module_id is None or not (
+        _persist_dir(module_id).parent / "status.json"
+    ).exists():
+        print(f"无运行记录: {module_id or '(无任何运行)'}", file=sys.stderr)
+        return 1
+    try:
+        request_control(module_id, args.command, reason=getattr(args, "reason", None))
+    except ValueError as e:
+        print(f"错误: {e}", file=sys.stderr)
+        return 1
+    print(f"已请求 {args.command}: {module_id}（运行进程将在下一 tick 边界生效）")
+    return 0
+
+
 def _cmd_init(args: argparse.Namespace) -> int:
     """生成模块脚手架：--as-dir 目录形态（pack 同构）或单文件形态 + 项目文件补齐。"""
     try:
@@ -1303,6 +1338,17 @@ def main(argv: list[str] | None = None) -> int:
     p_checkpoint.add_argument("--run-id", help="运行 id（默认最近运行）")
     p_checkpoint.set_defaults(func=_cmd_checkpoint)
 
+    for _name, _help in (
+        ("cancel", "请求取消运行（协作式：下一 tick 边界生效，phase→cancelled）"),
+        ("pause", "请求暂停运行（tick 边界挂起，tick 计数不前进）"),
+        ("unpause", "释放暂停，运行继续"),
+    ):
+        _p = sub.add_parser(_name, help=_help)
+        _p.add_argument("--run-id", help="运行 id（默认最近运行）")
+        if _name == "cancel":
+            _p.add_argument("--reason", help="取消原因（透传 runner.cancel）")
+        _p.set_defaults(func=_cmd_control)
+
     p_visualize = sub.add_parser(
         "visualize", help="渲染 tasklist 对应图（mermaid 导出）"
     )

specmodule-0.1.3/module_harness/control.py

@@ -0,0 +1,175 @@
+# module_harness/control.py
+"""跨进程运行控制——控制文件协议（cancel/pause/unpause）。
+
+status.json 的反向通道：status.json 把运行状态带出运行进程，control.json
+把控制请求带进运行进程——文件即协议，任何消费端（CLI/Web/TUI）可写，
+运行进程在 tick 边界协作式消费。零依赖、不触碰运行状态的单写者规则
+（status.json 仍只由运行进程写）。
+
+协议：``.specmodule/runs/<run_id>/control.json``，单发一次性请求::
+
+    {"action": "cancel" | "pause" | "unpause", "reason": str|null,
+     "requested_at": float}
+
+- 写方：``request_control`` 原子写（tmp + os.replace，与 status.json 同款）。
+- 读方：``control_tick_start`` / ``control_tick_end`` 工厂返回 hook 回调，
+  由 Module 注册到 runner（``control=False`` 关闭）：
+  - **cancel 在 ``on_tick_end`` 消费**——引擎每个 tick 结束都会无条件重写
+    ``runner.status``（RUNNING/IDLE），tick_start 期设置的 CANCELLED 终态
+    会被同 tick 末尾的赋值冲掉；tick_end hook 在赋值之后运行，此刻
+    ``runner.cancel()`` 设置的终态能活到 ``run_until_idle`` 的下轮
+    terminal 检查，循环即停。请求写在 tick N 内 → N（或 N+1）末尾生效，
+    即取消有一 tick 延迟（当前 tick 内已开始的 firing 会跑完）。
+  - **pause 在 ``on_tick_start`` 挂起**——即将 fire 的 tick 不启动，tick
+    计数不前进（max_ticks 不消耗），轮询等待 unpause 或 cancel；挂起期间
+    保留文件（文件本身就是"暂停中"状态，监控方 ``read_control`` 可读）。
+    挂起中见到 cancel：不清除文件、直接放行——留给 tick_end 消费（同上
+    冲掉问题），当前 tick 跑完后停。
+- 消费即删（delete-on-consume）：动作执行后删除文件，防重放。
+- 新执行清场：``Module.run()/resume()`` 开始时 ``clear_control``——启动新
+  执行即作废陈旧请求（进程崩溃残留的 pause 不会拖住下一次运行）。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+__all__ = [
+    "ACTIONS",
+    "clear_control",
+    "control_path",
+    "control_tick_end",
+    "control_tick_start",
+    "read_control",
+    "request_control",
+]
+
+#: 合法控制动作。
+ACTIONS: tuple[str, ...] = ("cancel", "pause", "unpause")
+
+#: pause 挂起期间的轮询间隔（秒）。
+POLL_SECONDS = 0.5
+
+
+def control_path(module_id: str, base_dir: Path | None = None) -> Path:
+    """控制文件路径：``<base_dir>/.specmodule/runs/<run_id>/control.json``。"""
+    return (base_dir or Path.cwd()) / ".specmodule" / "runs" / module_id / "control.json"
+
+
+def read_control(module_id: str, base_dir: Path | None = None) -> dict[str, Any] | None:
+    """读当前控制请求；无请求 / 文件损坏 / action 非法 → None（容错读）。"""
+    path = control_path(module_id, base_dir)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        log.warning("control.json 损坏或不可读（忽略）: %s", path)
+        return None
+    if not isinstance(data, dict) or data.get("action") not in ACTIONS:
+        log.warning("control.json 内容非法（忽略）: %s", path)
+        return None
+    return data
+
+
+def request_control(
+    module_id: str,
+    action: str,
+    *,
+    reason: str | None = None,
+    base_dir: Path | None = None,
+) -> dict[str, Any]:
+    """写入控制请求（原子写）。action 非法 → ValueError。返回写入的请求。"""
+    if action not in ACTIONS:
+        raise ValueError(
+            f"未知控制动作: {action!r}（可用: {'/'.join(ACTIONS)}）"
+        )
+    req: dict[str, Any] = {
+        "action": action,
+        "reason": reason,
+        "requested_at": time.time(),
+    }
+    path = control_path(module_id, base_dir)
+    tmp = path.with_suffix(".json.tmp")
+    try:
+        tmp.parent.mkdir(parents=True, exist_ok=True)
+        tmp.write_text(json.dumps(req, ensure_ascii=False), encoding="utf-8")
+        os.replace(tmp, path)
+    except OSError:
+        log.exception("写 control.json 失败: %s", path)
+        raise
+    return req
+
+
+def clear_control(module_id: str, *, base_dir: Path | None = None) -> None:
+    """删除控制文件（消费/清场）。缺失不报错；删除失败仅 log。"""
+    try:
+        control_path(module_id, base_dir).unlink(missing_ok=True)
+    except OSError:
+        log.exception("删除 control.json 失败（忽略）")
+
+
+def control_tick_start(
+    runner: Any,
+    module_id: str,
+    *,
+    base_dir: Path | None = None,
+    poll: float = POLL_SECONDS,
+):
+    """工厂：注册到 ``runner.on_tick_start`` 的 async pause/unpause hook。
+
+    只处理 pause 挂起（cancel 统一由 ``control_tick_end`` 消费——见模块
+    docstring 的终态冲掉说明）。``runner`` 仅用于签名一致性（本 hook 不调
+    runner 方法）；由 Module 在构建 runner 后注册。
+    """
+    async def _on_tick_start(tick: int, fireable: list[str]) -> None:
+        req = read_control(module_id, base_dir=base_dir)
+        if req is None or req["action"] == "cancel":
+            # cancel 留给 tick_end（不清文件）；无请求直接放行
+            return
+        if req["action"] != "pause":
+            return
+        # pause：tick 边界挂起；文件保留 = "暂停中"状态（监控方 read_control 可读）
+        while True:
+            await asyncio.sleep(poll)
+            nxt = read_control(module_id, base_dir=base_dir)
+            if nxt is None:
+                # 挂起期间文件被外部删除（人工清理）→ 视为释放
+                return
+            if nxt["action"] == "cancel":
+                # 不清除、直接放行——tick_end 消费（终态不被本 tick 冲掉）
+                return
+            if nxt["action"] == "unpause":
+                clear_control(module_id, base_dir=base_dir)
+                return
+
+    return _on_tick_start
+
+
+def control_tick_end(
+    runner: Any,
+    module_id: str,
+    *,
+    base_dir: Path | None = None,
+):
+    """工厂：注册到 ``runner.on_tick_end`` 的 cancel 消费 hook。
+
+    在引擎每 tick 末尾的状态赋值**之后**运行——此刻 ``runner.cancel()``
+    设置的 CANCELLED 能活到 ``run_until_idle`` 下轮 terminal 检查。
+    """
+    async def _on_tick_end(tick: int, firings: list) -> None:
+        req = read_control(module_id, base_dir=base_dir)
+        if req is None or req["action"] != "cancel":
+            return
+        runner.cancel(req.get("reason") or "cancelled")
+        clear_control(module_id, base_dir=base_dir)
+
+    return _on_tick_end

{specmodule-0.1.2 → specmodule-0.1.3}/module_harness/module.py

@@ -28,6 +28,7 @@ from .checkpoint import (
     tasklist_from_dict,
     tasklist_to_dict,
 )
+from .control import clear_control, control_tick_end, control_tick_start
 
 log = logging.getLogger(__name__)
 
@@ -72,6 +73,7 @@ class Module:
         keep_records: bool = True,
         persist: bool = True,
         status_file: bool = True,
+        control: bool = True,
         modules: dict[str, Any] | None = None,
         hooks: dict | None = None,
     ) -> None:
@@ -88,6 +90,9 @@ class Module:
         # True（默认）：写 .specmodule/runs/<module_id>/status.json
         # （阶段级，跨进程查询通道）；False：零残留（快速模式可用）
         self.status_file = status_file
+        # True（默认）：注册控制文件 hook（control.json → cancel/pause，
+        # 见 control.py）。跨进程取消/暂停的协作式通道；False 关闭。
+        self.control = control
         self.review_result: ConsistencyReport | None = None
         self.module_id = module_id or f"mod_{uuid.uuid4().hex[:8]}"
         self._base_dir = base_dir or Path.cwd()
@@ -215,6 +220,17 @@ class Module:
                 _register(_cb)
             else:
                 log.warning("Module hooks: 未知 runner hook '%s'（忽略）", _hook_name)
+        if self.control:
+            # 跨进程控制通道（control.json → cancel/pause）：与用户 hooks
+            # 并存——runner 的 hook 注册表是 list，追加不覆盖。cancel 在
+            # tick_end 消费（tick_start 期设终态会被引擎同 tick 赋值冲掉）、
+            # pause 在 tick_start 挂起，见 control.py 模块 docstring。
+            runner.on_tick_start(
+                control_tick_start(runner, self.module_id, base_dir=self._base_dir)
+            )
+            runner.on_tick_end(
+                control_tick_end(runner, self.module_id, base_dir=self._base_dir)
+            )
         return runner
 
     # ------------------------------------------------------------------
@@ -337,6 +353,11 @@ class Module:
 
     async def _run_with_phases(self, runner: AsyncRunner, max_ticks: int) -> list:
         """归档本次输入 → 运行 → 按结果映射终态 phase（run/resume 共用）。"""
+        if self.control:
+            # 新执行清场：作废陈旧控制请求（崩溃残留的 pause 不拖住新执行）。
+            # 位于写 running phase 之前——监控方看到 running 才放开控制按钮，
+            # 此时清场已完成，清场与首请求的竞态窗口关闭。
+            clear_control(self.module_id, base_dir=self._base_dir)
         self._archive_module_inputs()
         self._write_phase("running")
         try:

{specmodule-0.1.2 → specmodule-0.1.3}/module_harness/query.py

@@ -296,6 +296,29 @@ def load_snapshot_summary(
     return out
 
 
+def read_module_inputs(
+    module_id: str, base_dir: Path | None = None
+) -> dict[str, Any] | None:
+    """读运行输入存档（module_inputs 表：本次 run 使用的 spec/tasklist）。
+
+    消费场景：resume/rollback 前端预填上次输入（换 spec/tasklist 重传的
+    编辑起点）。db 缺失 / 无存档 / 读失败 → None（查询容错，同上）。
+    """
+    db_path = run_db_path(module_id, base_dir)
+    if not db_path.exists():
+        return None
+    from .checkpoint import ModuleInputStore
+
+    store = ModuleInputStore(module_id, base_dir)
+    try:
+        return store.load_module_inputs()
+    except Exception:
+        log.exception("读取 module_inputs 失败（返回 None）: %s", db_path)
+        return None
+    finally:
+        store.close()
+
+
 def timeline_to_dict(timeline: ReviewTimeline) -> dict[str, Any]:
     """JSON 出口（MCP/Web 直接消费同一函数）。"""
     return {

{specmodule-0.1.2 → specmodule-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specmodule"
-version = "0.1.2"
+version = "0.1.3"
 description = "可审计、可调试、可完全掌控的 LLM 使用框架（tickflow + llm + module_harness）"
 readme = "README.md"
 requires-python = ">=3.10"

{specmodule-0.1.2 → specmodule-0.1.3/specmodule.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specmodule
-Version: 0.1.2
+Version: 0.1.3
 Summary: 可审计、可调试、可完全掌控的 LLM 使用框架（tickflow + llm + module_harness）
 License: MIT
 Keywords: llm,workflow,petri-net,agent

{specmodule-0.1.2 → specmodule-0.1.3}/specmodule.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ module_harness/cli.py
 module_harness/command.py
 module_harness/config.py
 module_harness/consistency.py
+module_harness/control.py
 module_harness/entry.py
 module_harness/events.py
 module_harness/feed.py