workflow-loop 0.1.0__py3-none-any.whl

workflow_loop/journal.py

@@ -0,0 +1,78 @@
+import json
+import os
+from datetime import datetime, timezone
+
+# journal.jsonl 的相对路径（相对于项目根）
+# 放在 .workflow_loop/ 下，和 state.json、project.json 同级
+JOURNAL_FILE = os.path.join(".workflow_loop", "journal.jsonl")
+
+
+# 往 journal.jsonl 追加一条记录
+# journal 是 append-only 的历史记录（"发生过啥"），不可改
+# 和 state.json（"现在在哪"，可重写）分离：崩溃恢复时可以从 journal 重建 state
+def append_entry(project_root: str, action: str, actor: str, **kwargs) -> None:
+    # 拼出 journal.jsonl 的完整路径
+    path = os.path.join(project_root, JOURNAL_FILE)
+    # 确保目录存在（第一次写时 .workflow_loop/ 可能还没建）
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    # 组装一条 journal 记录：时间戳 + 动作类型 + 执行者 + 额外字段
+    entry = {
+        # ISO 8601 UTC 时间戳，去掉微秒让格式更干净
+        "ts": datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
+        # 动作类型（中文受控词表：工作流启动/提示词加载/门禁讨论完毕/...）
+        "action": action,
+        # 执行者：ai / user / workflow.py（谁触发了这个动作）
+        "actor": actor,
+        # 额外字段（如 stage=xxx, passed=true 等，按 action 类型不同带不同 payload）
+        **kwargs,
+    }
+    # 追加写一行 JSON（不覆盖已有内容），ensure_ascii=False 保留中文
+    with open(path, "a", encoding="utf-8") as f:
+        # 每条记录一行，jsonl 格式（JSON Lines）
+        f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+
+# 读最近 N 条 journal 记录（status 命令用，默认 10 条）
+# 返回 list[dict]，每条是一个 JSON 对象
+def read_recent(project_root: str, count: int = 10) -> list[dict]:
+    # 拼出 journal.jsonl 的完整路径
+    path = os.path.join(project_root, JOURNAL_FILE)
+    # 文件不存在说明还没 start 过，返回空列表
+    if not os.path.exists(path):
+        return []
+    # 收集所有记录
+    entries = []
+    # 逐行读取 jsonl 文件
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            # 去掉行首行尾空白
+            line = line.strip()
+            # 跳过空行
+            if line:
+                # 解析 JSON 行
+                entries.append(json.loads(line))
+    # 只返回最后 count 条（最近的记录）
+    return entries[-count:]
+
+
+# 读所有 journal 记录（调试和审计用）
+# 返回 list[dict]，按时间顺序（从早到晚）
+def read_all(project_root: str) -> list[dict]:
+    # 拼出 journal.jsonl 的完整路径
+    path = os.path.join(project_root, JOURNAL_FILE)
+    # 文件不存在说明还没 start 过，返回空列表
+    if not os.path.exists(path):
+        return []
+    # 收集所有记录
+    entries = []
+    # 逐行读取 jsonl 文件
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            # 去掉行首行尾空白
+            line = line.strip()
+            # 跳过空行
+            if line:
+                # 解析 JSON 行
+                entries.append(json.loads(line))
+    # 返回所有记录（从早到晚）
+    return entries

workflow_loop/path_composer.py

@@ -0,0 +1,152 @@
+from .project import is_project_design_initialized
+from .stages import (
+    SpecStage,
+    CodeDesignStage,
+    SpikeStage,
+    ImplStage,
+    AcceptancePlanStage,
+    TestPlanStage,
+    TestCodeStage,
+    TestExecutionStage,
+    TopicAcceptanceStage,
+    RegressionTestStage,
+    OverallAcceptanceStage,
+    UpdateCodeDesignStage,
+    ProjectDesignInitStage,
+    ReviseCodeDesignStage,
+    ReproduceStage,
+)
+from .stages.base import StageStrategy
+
+# from_scratch（从零做）的完整 stage 路径
+# 顺序固定：先产品设计与功能拆分、后初步架构（先定做什么，再定怎么搭）
+# 然后验证技术不确定性 → 验收计划 → 测试计划 → 实施/记录 → 写测试代码 → 执行测试 → 主题验收
+# → 最终全量回归 → 整体验收 → 最终设计同步
+# 共享后半截：acceptance_plan → test_plan → impl → test_code → test_execution
+# → topic_acceptance → regression_test → overall_acceptance → update_code_design
+FROM_SCRATCH_PATH = [
+    # 产品设计阶段：产出 spec/product.md + spec/feature_*.md
+    SpecStage,
+    # 初步架构阶段：产出 spec/architecture_code_design.md（从零做的初步架构）
+    CodeDesignStage,
+    # 穿刺阶段：验证真实场景中的技术不确定性，写清单和每项结论；临时代码按需进入 spike_tmp/
+    # 可选 stage，可通过 gate spike --skip 跳过
+    SpikeStage,
+    # 验收计划阶段：制定什么算完成，产出 traceability.md + acceptance/index.md + acceptance/<topic>_plan.md
+    AcceptancePlanStage,
+    # 测试计划阶段：把验收条件转为可执行测试范围，产出 qa/<topic>_plan.md
+    TestPlanStage,
+    # 实施阶段：先确认全部主题计划，再修改真实代码并记录实施结果
+    ImplStage,
+    # 按验收计划编写测试代码；本阶段不执行测试、不产出测试结果
+    TestCodeStage,
+    # 执行测试代码并记录主题测试结果
+    TestExecutionStage,
+    # 测试通过后，按主题验收计划核对用户结果
+    TopicAcceptanceStage,
+    # 全部主题完成后，对合并代码执行最终全量回归
+    RegressionTestStage,
+    # 最终全量回归通过后，确认整个需求是否完成
+    OverallAcceptanceStage,
+    # 最终设计同步：更新 spec/architecture_code_design.md 反映产品、架构和真实代码映射
+    # 所有意图末环同名，强制不可跳过
+    UpdateCodeDesignStage,
+]
+
+# product_change（改产品）的基础 stage 路径（不含 project_design_init 前置）
+# 和 from_scratch 的差异：用 ReviseCodeDesignStage 替代 CodeDesignStage
+# spec 之后必须经过 revise_code_design（设计期改架构），不能只改产品不改架构
+PRODUCT_CHANGE_BASE = [
+    # 产品设计阶段：基于现状重新设计，可新增/修改/删除功能文档
+    SpecStage,
+    # 设计期架构修订：按变更后的产品设计改架构图
+    # 与末段 update_code_design（详细落地）名称分离，避免同一 Run 内 stage 名冲突
+    ReviseCodeDesignStage,
+    # 穿刺阶段（可选）
+    SpikeStage,
+    # 验收计划阶段
+    AcceptancePlanStage,
+    # 测试计划阶段
+    TestPlanStage,
+    # 实施阶段：先确认全部主题计划，再修改真实代码并记录实施结果
+    ImplStage,
+    # 先编写测试代码，再执行测试，再按主题验收
+    TestCodeStage,
+    TestExecutionStage,
+    TopicAcceptanceStage,
+    # 最终全量回归
+    RegressionTestStage,
+    # 整体验收
+    OverallAcceptanceStage,
+    # 最终设计同步（强制）
+    UpdateCodeDesignStage,
+]
+
+# bugfix（修 bug）的基础 stage 路径（不含 project_design_init 前置）
+# 和 from_scratch 的差异：没有 spec/code_design，先 reproduce，再经过可选 spike；
+# 在共享后半截中使用 impl 制定并执行修复实施计划
+# 末段 update_code_design 即使无架构变化也必须走，在门禁中显式确认"架构未变化"
+BUGFIX_BASE = [
+    # 复现阶段：复现 bug + 根因分析，并确定一份缺陷记录对应的验收主题
+    ReproduceStage,
+    # 穿刺阶段：验证修复仍依赖的真实技术不确定性；没有时由用户确认跳过
+    SpikeStage,
+    # 验收计划阶段
+    AcceptancePlanStage,
+    # 测试计划阶段
+    TestPlanStage,
+    # 实施阶段：先确认全部主题计划，再修改真实代码并记录实施结果
+    ImplStage,
+    # 先编写测试代码，再执行测试，再按主题验收
+    TestCodeStage,
+    TestExecutionStage,
+    TopicAcceptanceStage,
+    # 最终全量回归
+    RegressionTestStage,
+    # 整体验收
+    OverallAcceptanceStage,
+    # 最终设计同步（强制，无架构变化也要显式确认）
+    UpdateCodeDesignStage,
+]
+
+# 正式互斥意图列表（start --intent 的合法值）
+# docs_only 暂不作为正式意图
+INTENT_CHOICES = ["from_scratch", "product_change", "bugfix"]
+
+
+# 根据 intent 和项目事实返回 stage 列表（CONTEXT.md "Path Composer"）
+# 取代旧的四个 Scenario 类并行流水线与 SCENARIO_REGISTRY
+# 在 start --intent 时调一次，结果存入 state.stage_path，后续命令读 state.stage_path
+# 不在每次命令调用时重新跑 PathComposer（条件在 start 时就固定）
+def build_stage_path(intent: str, project_root: str) -> list[StageStrategy]:
+    # 从零做：直接返回 FROM_SCRATCH_PATH 的实例列表
+    # from_scratch 不走 project_design_init（那只有 product_change/bugfix 走）
+    # from_scratch 在 spec + code_design 都 --confirmed 后写 project_design_initialized=true
+    if intent == "from_scratch":
+        # 实例化每个 stage 类
+        return [cls() for cls in FROM_SCRATCH_PATH]
+    # 改产品：先检查 project_design_initialized
+    if intent == "product_change":
+        # 收集 stage 实例
+        stages = []
+        # 如果项目设计未初始化，前置 project_design_init stage
+        # 不能用 architecture_code_design.md 是否存在决定跳过
+        if not is_project_design_initialized(project_root):
+            # 前置项目设计架构初始化 stage
+            stages.append(ProjectDesignInitStage())
+        # 追加 product_change 的基础路径
+        stages.extend(cls() for cls in PRODUCT_CHANGE_BASE)
+        return stages
+    # 修 bug：先检查 project_design_initialized
+    if intent == "bugfix":
+        # 收集 stage 实例
+        stages = []
+        # 如果项目设计未初始化，前置 project_design_init stage
+        if not is_project_design_initialized(project_root):
+            # 前置项目设计架构初始化 stage
+            stages.append(ProjectDesignInitStage())
+        # 追加 bugfix 的基础路径
+        stages.extend(cls() for cls in BUGFIX_BASE)
+        return stages
+    # 未知 intent：报错并提示合法值
+    raise ValueError(f"未知 intent: {intent}，可选值: {INTENT_CHOICES}")

workflow_loop/process_runner.py

@@ -0,0 +1,176 @@
+"""跨平台受控进程执行器。
+
+主题测试和最终全量回归共用同一套执行行为：只接受命令参数数组和项目内工作目录，
+不经过 Shell；POSIX 新建会话并按进程组先终止后强制结束；Windows 新建进程组并
+使用系统进程树终止能力；所有路径都等待进程完成并收集有界输出。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+# 输出摘要保留的末尾字节数；完整输出只保存哈希和字节数，不落盘
+OUTPUT_TAIL_BYTES = 8 * 1024
+# 超时后先礼貌终止，再等这些秒数才强制结束
+TERMINATE_GRACE_SECONDS = 5
+
+
+@dataclass
+class ProcessRequest:
+    """一次受控执行请求。"""
+
+    argv: list[str]
+    # 项目内工作目录（绝对路径；由调用方校验在项目内）
+    cwd: str
+    timeout_seconds: int
+    # 额外环境变量（在当前环境基础上覆盖）；None 表示原样继承
+    extra_env: dict[str, str] | None = None
+
+
+@dataclass
+class ProcessResult:
+    """一次受控执行的机器事实。"""
+
+    status: str  # passed / failed / timeout / error
+    exit_code: int | None
+    started_at: str
+    finished_at: str
+    duration_seconds: float
+    output_tail: str
+    output_sha256: str
+    output_bytes: int
+    platform: str
+    # argv[0] 解析出的实际可执行文件；无法解析时保留原样
+    executable: str
+    error_message: str = ""
+    argv: list[str] = field(default_factory=list)
+    cwd: str = ""
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def resolve_executable(command: str) -> str:
+    """返回当前环境实际会执行的程序路径；无法解析时保留原参数。"""
+    return shutil.which(command) or command
+
+
+def _kill_process_tree(process: subprocess.Popen) -> None:
+    """按平台清理整个进程组或进程树，不遗留测试子进程。"""
+    if sys.platform.startswith("win"):
+        # Windows：使用系统进程树终止能力（taskkill /T /F）
+        subprocess.run(
+            ["taskkill", "/PID", str(process.pid), "/T", "/F"],
+            capture_output=True,
+            check=False,
+        )
+        return
+    # POSIX：进程在新会话中启动，按进程组先 SIGTERM，宽限后 SIGKILL
+    try:
+        pgid = os.getpgid(process.pid)
+    except ProcessLookupError:
+        return
+    try:
+        os.killpg(pgid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    deadline = time.monotonic() + TERMINATE_GRACE_SECONDS
+    while time.monotonic() < deadline:
+        if process.poll() is not None:
+            break
+        time.sleep(0.1)
+    try:
+        os.killpg(pgid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+
+
+def run_process(request: ProcessRequest) -> ProcessResult:
+    """执行一次命令并返回完整机器事实；超时后清理整个进程组或进程树。"""
+    started_at = _now_iso()
+    start_clock = time.monotonic()
+    platform_name = sys.platform
+    executable = resolve_executable(request.argv[0])
+
+    env = None
+    if request.extra_env:
+        env = dict(os.environ)
+        env.update(request.extra_env)
+
+    popen_kwargs: dict = {
+        "args": request.argv,
+        "cwd": request.cwd,
+        "stdout": subprocess.PIPE,
+        "stderr": subprocess.STDOUT,
+        "shell": False,
+        "env": env,
+    }
+    if sys.platform.startswith("win"):
+        # 新建进程组，供 taskkill /T 清理整棵进程树
+        popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        # 新建会话（同时成为新进程组组长），供 killpg 清理
+        popen_kwargs["start_new_session"] = True
+
+    def _finish(
+        status: str,
+        exit_code: int | None,
+        output: bytes,
+        error_message: str = "",
+    ) -> ProcessResult:
+        finished_at = _now_iso()
+        tail = output[-OUTPUT_TAIL_BYTES:].decode("utf-8", errors="replace")
+        return ProcessResult(
+            status=status,
+            exit_code=exit_code,
+            started_at=started_at,
+            finished_at=finished_at,
+            duration_seconds=round(time.monotonic() - start_clock, 3),
+            output_tail=tail,
+            output_sha256=hashlib.sha256(output).hexdigest(),
+            output_bytes=len(output),
+            platform=platform_name,
+            executable=executable,
+            error_message=error_message,
+            argv=list(request.argv),
+            cwd=request.cwd,
+        )
+
+    try:
+        process = subprocess.Popen(**popen_kwargs)
+    except (OSError, ValueError) as exc:
+        return _finish("error", None, b"", f"无法启动命令: {exc}")
+
+    try:
+        output, _ = process.communicate(timeout=request.timeout_seconds)
+    except subprocess.TimeoutExpired as first_timeout:
+        _kill_process_tree(process)
+        # communicate() 超时后的再次调用会返回从进程启动起的完整累计输出，
+        # 不能再与第一次异常中的部分输出拼接，否则会重复计算摘要、哈希和字节数。
+        try:
+            output, _ = process.communicate(timeout=TERMINATE_GRACE_SECONDS + 5)
+        except subprocess.TimeoutExpired as final_timeout:
+            output = final_timeout.output
+            if output is None:
+                output = first_timeout.output
+        if isinstance(output, str):
+            output = output.encode("utf-8", errors="replace")
+        return _finish(
+            "timeout",
+            None,
+            output or b"",
+            f"超过 {request.timeout_seconds} 秒未完成，已清理整个进程组或进程树",
+        )
+
+    exit_code = process.returncode
+    status = "passed" if exit_code == 0 else "failed"
+    return _finish(status, exit_code, output or b"")