flower-trellis 0.3.1 → 0.4.0-beta.0

package/enhancements/0.6/scripts/auto_loop.py

@@ -0,0 +1,782 @@
+#!/usr/bin/env python3
+"""Trellis auto loop 的可恢复流程控制器。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import socket
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+SCHEMA_VERSION = 1
+DEFAULT_PROFILE = "commit-only"
+MAX_FIX_RECHECK = 3
+VALID_IMPLEMENT_ROUTES = {"inline", "subagent"}
+VALID_CHECK_ROUTES = {"check-all-inline", "check-all-subagent"}
+STEP_ACTIONS = {
+    "refresh_brief": "refresh_brief",
+    "start_task": "start_task",
+    "implement": "run_implement",
+    "check": "run_check_all",
+    "fix": "run_fix",
+    "recheck": "run_recheck",
+    "spec_update": "run_spec_update",
+    "commit_only": "commit_only",
+}
+
+
+def _utc_now() -> str:
+    """返回秒级 UTC 时间字符串。"""
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _repo_root() -> Path | None:
+    """从当前目录向上寻找 Trellis 项目根。"""
+    current = Path.cwd().resolve()
+    while True:
+        if (current / ".trellis").is_dir():
+            return current
+        if current == current.parent:
+            return None
+        current = current.parent
+
+
+def _print(data: dict[str, Any]) -> int:
+    """输出给 agent 消费的紧凑 JSON。"""
+    print(json.dumps(data, ensure_ascii=False, sort_keys=True))
+    return 0
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    """读取 JSON 对象，失败返回空对象。"""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _write_json(path: Path, data: dict[str, Any]) -> None:
+    """写入格式化 JSON。"""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def _rel_path(repo_root: Path, path: Path) -> str:
+    """尽量返回相对项目根的 POSIX 路径。"""
+    try:
+        return path.relative_to(repo_root).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def _auto_dir(repo_root: Path) -> Path:
+    """返回 auto-loop runtime 目录。"""
+    return repo_root / ".trellis/.runtime/auto-loop"
+
+
+def _current_pointer(repo_root: Path) -> Path:
+    """返回当前 auto run 指针文件。"""
+    return _auto_dir(repo_root) / "current.json"
+
+
+def _read_route_prefs(repo_root: Path) -> dict[str, str]:
+    """读取个人 route 默认配置，用于 start gate 判断是否需要 JSONL context。"""
+    path = repo_root / ".trellis/.route-prefs.tmp"
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return {}
+
+    prefs: dict[str, str] = {}
+    for raw in lines:
+        if "=" not in raw:
+            continue
+        key, value = raw.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if key == "implement" and value in VALID_IMPLEMENT_ROUTES:
+            prefs[key] = value
+        elif key == "check" and value in VALID_CHECK_ROUTES:
+            prefs[key] = value
+    return prefs
+
+
+def _effective_route_authorization(repo_root: Path, route_authorization: Any) -> dict[str, str]:
+    """按 route 优先级估算 start gate 需要的 context 类型。"""
+    effective: dict[str, str] = {}
+    if isinstance(route_authorization, dict):
+        implement = route_authorization.get("implement")
+        check = route_authorization.get("check")
+        if implement in VALID_IMPLEMENT_ROUTES:
+            effective["implement"] = str(implement)
+        if check in VALID_CHECK_ROUTES:
+            effective["check"] = str(check)
+
+    # 个人默认优先于 auto 临时授权；start gate 的 JSONL 判断也要遵守同一优先级，
+    # 否则可能在个人 subagent 默认下误放行，或在个人 inline 默认下误阻塞。
+    effective.update(_read_route_prefs(repo_root))
+    return effective
+
+
+def _run_path(repo_root: Path, run_id: str) -> Path:
+    """返回指定 auto run 状态文件。"""
+    return _auto_dir(repo_root) / f"{run_id}.json"
+
+
+def _new_run_id() -> str:
+    """生成短小稳定的 run id。"""
+    return "auto-" + datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+
+
+def _normalize_task_ref(repo_root: Path, task_ref: str) -> str:
+    """把任务引用规范化为 `.trellis/tasks/<dir>`。"""
+    raw = task_ref.strip()
+    path_obj = Path(raw)
+    candidates: list[Path]
+    if path_obj.is_absolute():
+        candidates = [path_obj]
+    elif raw.startswith(".trellis/"):
+        candidates = [repo_root / raw]
+    elif raw.startswith("tasks/"):
+        candidates = [repo_root / ".trellis" / raw]
+    else:
+        candidates = [repo_root / ".trellis/tasks" / raw, repo_root / raw]
+
+    for candidate in candidates:
+        if candidate.is_dir():
+            return _rel_path(repo_root, candidate)
+    raise ValueError(f"任务不存在:{task_ref}")
+
+
+def _task_dir(repo_root: Path, task_ref: str) -> Path:
+    """把规范化任务引用解析为绝对路径。"""
+    if task_ref.startswith(".trellis/"):
+        return repo_root / task_ref
+    return repo_root / ".trellis/tasks" / task_ref
+
+
+def _load_task_json(repo_root: Path, task_ref: str) -> dict[str, Any]:
+    """读取任务 task.json。"""
+    return _read_json(_task_dir(repo_root, task_ref) / "task.json")
+
+
+def _task_status(repo_root: Path, task_ref: str) -> str:
+    """读取任务状态。"""
+    return str(_load_task_json(repo_root, task_ref).get("status") or "unknown")
+
+
+def _has_real_jsonl_entries(path: Path, repo_root: Path) -> bool:
+    """判断 JSONL 上下文清单是否至少有一条真实且存在的 file entry。"""
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return False
+
+    for line in lines:
+        if not line.strip():
+            continue
+        try:
+            data = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        file_path = data.get("file")
+        if not isinstance(file_path, str) or not file_path.strip():
+            continue
+        if (repo_root / file_path).exists():
+            return True
+    return False
+
+
+def _open_questions(text: str) -> list[str]:
+    """提取 PRD 中仍存在的 open question 条目。"""
+    lines = text.splitlines()
+    collecting = False
+    questions: list[str] = []
+    for line in lines:
+        if line.startswith("## "):
+            collecting = line.strip().lower() == "## open questions"
+            continue
+        if collecting and line.strip().startswith("-"):
+            item = line.strip().lstrip("-").strip()
+            if item and item.upper() not in {"TBD", "N/A"}:
+                questions.append(item)
+    return questions
+
+
+def _start_gate(
+    repo_root: Path,
+    task_ref: str,
+    route_authorization: dict[str, Any] | None = None,
+) -> tuple[str, dict[str, Any]]:
+    """检查 planning -> start 前置条件。"""
+    task_dir = _task_dir(repo_root, task_ref)
+    prd = task_dir / "prd.md"
+    if not prd.is_file():
+        return "blocked", {"reason": "missing-prd", "message": "缺少 prd.md"}
+
+    questions = _open_questions(prd.read_text(encoding="utf-8"))
+    if questions:
+        return "blocked", {
+            "reason": "open-questions",
+            "message": "PRD 仍有阻塞性 Open Questions",
+            "questions": questions,
+        }
+
+    design = task_dir / "design.md"
+    implement = task_dir / "implement.md"
+    if design.exists() != implement.exists():
+        missing = "implement.md" if design.exists() else "design.md"
+        return "blocked", {"reason": "incomplete-complex-artifacts", "message": f"复杂任务缺少 {missing}"}
+
+    auth = route_authorization if isinstance(route_authorization, dict) else {}
+    needs_implement_context = auth.get("implement") != "inline"
+    needs_check_context = auth.get("check") != "check-all-inline"
+    if needs_implement_context and not _has_real_jsonl_entries(task_dir / "implement.jsonl", repo_root):
+        return "blocked", {
+            "reason": "missing-implement-context",
+            "message": "implement.jsonl 未 curated（当前 route 可能需要 sub-agent context）",
+        }
+    if needs_check_context and not _has_real_jsonl_entries(task_dir / "check.jsonl", repo_root):
+        return "blocked", {
+            "reason": "missing-check-context",
+            "message": "check.jsonl 未 curated（当前 route 可能需要 sub-agent context）",
+        }
+
+    if not (task_dir / "brief.md").is_file():
+        return "action", {
+            "action": "refresh_brief",
+            "message": "缺少 brief.md，需先用 trellis-task-brief 生成任务摘要",
+        }
+
+    return "ok", {"message": "start gate satisfied"}
+
+
+def _current_session_key(repo_root: Path) -> str | None:
+    """尽力解析当前 session key，用于把 auto run 绑定给 route helper。"""
+    override = os.environ.get("TRELLIS_CONTEXT_ID")
+    if override:
+        return override.strip() or None
+
+    result = subprocess.run(
+        ["python3", str(repo_root / ".trellis/scripts/task.py"), "current", "--source"],
+        cwd=repo_root,
+        check=False,
+        text=True,
+        capture_output=True,
+    )
+    for line in result.stdout.splitlines():
+        if line.startswith("Source: "):
+            source = line.split(": ", 1)[1].strip()
+            if source.startswith(("session:", "session-fallback:")):
+                return source.split(":", 1)[1].strip()
+    return None
+
+
+def _link_session_run(repo_root: Path, run_id: str) -> None:
+    """把当前 auto run 写入 session runtime，方便 route_state.py 精确恢复。"""
+    context_key = _current_session_key(repo_root)
+    if not context_key:
+        return
+    path = repo_root / ".trellis/.runtime/sessions" / f"{context_key}.json"
+    context = _read_json(path)
+    context.setdefault("platform", context_key.split("_", 1)[0] if "_" in context_key else "session")
+    context["last_seen_at"] = _utc_now()
+    context["current_auto_run"] = run_id
+    _write_json(path, context)
+
+
+def _load_current_state(repo_root: Path, run_id: str | None = None) -> tuple[Path, dict[str, Any]]:
+    """加载指定或当前 auto run 状态。"""
+    if run_id:
+        path = _run_path(repo_root, run_id)
+        state = _read_json(path)
+        if not state:
+            raise ValueError(f"auto run 不存在:{run_id}")
+        return path, state
+
+    pointer = _read_json(_current_pointer(repo_root))
+    current = pointer.get("run_id")
+    if isinstance(current, str) and current:
+        path = _run_path(repo_root, current)
+        state = _read_json(path)
+        if state:
+            return path, state
+
+    running: list[tuple[Path, dict[str, Any]]] = []
+    for path in sorted(_auto_dir(repo_root).glob("auto-*.json")):
+        state = _read_json(path)
+        if state.get("status") == "running":
+            running.append((path, state))
+    if len(running) == 1:
+        return running[0]
+    raise ValueError("没有可恢复的唯一 auto run")
+
+
+def _write_state(path: Path, state: dict[str, Any]) -> None:
+    """刷新 auto run 状态和更新时间。"""
+    state["updated_at"] = _utc_now()
+    state["resume_capsule"] = _resume_capsule(state)
+    _write_json(path, state)
+
+
+def _write_pointer(repo_root: Path, run_id: str) -> None:
+    """写入当前 auto run 指针。"""
+    _write_json(_current_pointer(repo_root), {"run_id": run_id, "updated_at": _utc_now()})
+
+
+def _resume_capsule(state: dict[str, Any]) -> dict[str, Any]:
+    """生成短小的人类可读恢复摘要。"""
+    queue = state.get("queue") if isinstance(state.get("queue"), list) else []
+    current = None
+    for item in queue:
+        if isinstance(item, dict) and item.get("status") in {"pending", "running"}:
+            current = item
+            break
+    return {
+        "run_id": state.get("run_id"),
+        "status": state.get("status"),
+        "current_task": current.get("task") if current else None,
+        "next_step": current.get("current_step") if current else "done",
+        "completed": sum(1 for item in queue if isinstance(item, dict) and item.get("status") == "completed"),
+        "blocked": sum(1 for item in queue if isinstance(item, dict) and item.get("status") == "blocked"),
+        "remaining": sum(1 for item in queue if isinstance(item, dict) and item.get("status") in {"pending", "running"}),
+    }
+
+
+def _summary(state: dict[str, Any]) -> dict[str, Any]:
+    """返回队列状态摘要。"""
+    queue = state.get("queue") if isinstance(state.get("queue"), list) else []
+    outstanding_action = None
+    for item in queue:
+        if not isinstance(item, dict) or item.get("status") != "running":
+            continue
+        last_action = item.get("last_action")
+        if isinstance(last_action, dict):
+            outstanding_action = {
+                "task": item.get("task"),
+                "action": last_action.get("action"),
+                "current_step": last_action.get("current_step"),
+                "issued_at": last_action.get("issued_at"),
+            }
+        break
+    return {
+        "run_id": state.get("run_id"),
+        "run_status": state.get("status"),
+        "profile": state.get("profile"),
+        "current_index": state.get("current_index"),
+        "outstanding_action": outstanding_action,
+        "completed": [i.get("task") for i in queue if isinstance(i, dict) and i.get("status") == "completed"],
+        "blocked": [
+            {"task": i.get("task"), "blocked": i.get("blocked")}
+            for i in queue
+            if isinstance(i, dict) and i.get("status") == "blocked"
+        ],
+        "pending": [i.get("task") for i in queue if isinstance(i, dict) and i.get("status") in {"pending", "running"}],
+        "resume_capsule": state.get("resume_capsule"),
+    }
+
+
+def _make_item(repo_root: Path, task_ref: str) -> dict[str, Any]:
+    """构造队列任务项。"""
+    normalized = _normalize_task_ref(repo_root, task_ref)
+    status = _task_status(repo_root, normalized)
+    step = "start_task" if status == "planning" else "implement"
+    return {
+        "task": normalized,
+        "status": "pending",
+        "task_status": status,
+        "current_step": step,
+        "attempts": {"fix_recheck": 0},
+        "last_failure": None,
+        "last_action": None,
+        "commit": None,
+        "blocked": None,
+        "updated_at": _utc_now(),
+    }
+
+
+def _action(action: str, item: dict[str, Any], extra: dict[str, Any] | None = None) -> dict[str, Any]:
+    """构造下一步动作对象。"""
+    task = item.get("task")
+    base: dict[str, Any] = {
+        "status": "action",
+        "action": action,
+        "task": task,
+        "current_step": item.get("current_step"),
+    }
+    if action == "start_task":
+        task_name = Path(str(task)).name
+        base["command"] = f"python3 ./.trellis/scripts/task.py start {task_name}"
+    elif action == "refresh_brief":
+        base["instruction"] = "运行 trellis-task-brief 生成 brief.md，然后 record --result ok。"
+    elif action == "run_implement":
+        base["instruction"] = "进入 Phase 2.1 implement route，并执行实现。"
+    elif action == "run_check_all":
+        base["instruction"] = "进入 Phase 2.2 check route，默认执行 check-all。"
+    elif action == "run_fix":
+        base["instruction"] = "根据最近失败摘要修复问题。"
+    elif action == "run_recheck":
+        base["instruction"] = "修复后重新执行 check-all。"
+    elif action == "run_spec_update":
+        base["instruction"] = "若有代码/测试证据支撑，执行 trellis-update-spec；否则直接 record ok。"
+    elif action == "commit_only":
+        base["instruction"] = "按 trellis-auto-loop / trellis-push commit-only 预授权语义提交当前任务可归属文件，不 push。"
+    if extra:
+        base.update(extra)
+    return base
+
+
+def _remember_action(item: dict[str, Any], action_data: dict[str, Any]) -> dict[str, Any]:
+    """记录 runner 已发出的待回写 action。"""
+    item["last_action"] = {
+        "action": action_data.get("action"),
+        "current_step": action_data.get("current_step"),
+        "issued_at": _utc_now(),
+    }
+    item["updated_at"] = _utc_now()
+    return action_data
+
+
+def _outstanding_action_name(item: dict[str, Any]) -> str | None:
+    """返回当前任务等待 record 回写的 action 名。"""
+    last_action = item.get("last_action")
+    if isinstance(last_action, dict) and isinstance(last_action.get("action"), str):
+        return last_action["action"]
+    return None
+
+
+def _block_item(item: dict[str, Any], reason: str, summary: str, detail: dict[str, Any] | None = None) -> None:
+    """把当前任务标记为 blocked。"""
+    item["status"] = "blocked"
+    item["blocked"] = {
+        "reason": reason,
+        "summary": summary,
+        "detail": detail or {},
+        "blocked_at": _utc_now(),
+    }
+    item["updated_at"] = _utc_now()
+
+
+def _next_item(repo_root: Path, state: dict[str, Any]) -> tuple[dict[str, Any] | None, dict[str, Any]]:
+    """计算并更新队列中的下一步动作。"""
+    queue = state.get("queue") if isinstance(state.get("queue"), list) else []
+    for index, item in enumerate(queue):
+        if not isinstance(item, dict) or item.get("status") not in {"pending", "running"}:
+            continue
+
+        state["current_index"] = index
+        item["status"] = "running"
+        task = str(item.get("task"))
+        item["task_status"] = _task_status(repo_root, task)
+
+        if item["task_status"] == "planning":
+            gate_status, gate = _start_gate(repo_root, task, _effective_route_authorization(repo_root, state.get("route_authorization")))
+            if gate_status == "blocked":
+                _block_item(item, gate["reason"], gate["message"], gate)
+                continue
+            if gate_status == "action":
+                item["current_step"] = "refresh_brief"
+                return item, _remember_action(item, _action("refresh_brief", item, gate))
+            item["current_step"] = "start_task"
+            return item, _remember_action(item, _action("start_task", item))
+
+        step = item.get("current_step") or "implement"
+        if step in {"start_task", "implement"}:
+            item["current_step"] = "implement"
+            return item, _remember_action(item, _action("run_implement", item))
+        if step == "check":
+            return item, _remember_action(item, _action("run_check_all", item))
+        if step == "fix":
+            attempts = item.setdefault("attempts", {}).get("fix_recheck", 0)
+            if attempts >= MAX_FIX_RECHECK:
+                _block_item(item, "retry-budget-exhausted", "fix/recheck 已达到默认 3 轮预算")
+                continue
+            return item, _remember_action(
+                item,
+                _action("run_fix", item, {"attempt": attempts, "max_attempts": MAX_FIX_RECHECK}),
+            )
+        if step == "recheck":
+            return item, _remember_action(item, _action("run_recheck", item))
+        if step == "spec_update":
+            return item, _remember_action(item, _action("run_spec_update", item))
+        if step == "commit_only":
+            return item, _remember_action(item, _action("commit_only", item))
+
+        _block_item(item, "unknown-step", f"未知 current_step:{step}")
+
+    state["status"] = "completed"
+    return None, {"status": "done", "summary": _summary(state)}
+
+
+def cmd_start(args: argparse.Namespace) -> int:
+    """创建 auto run。"""
+    repo_root = _repo_root()
+    if repo_root is None:
+        return _print({"status": "error", "reason": "not-trellis-project"})
+
+    try:
+        current_path, current = _load_current_state(repo_root)
+        if current.get("status") == "running" and not args.force:
+            return _print({
+                "status": "error",
+                "reason": "auto-run-already-running",
+                "run_id": current.get("run_id"),
+                "path": _rel_path(repo_root, current_path),
+            })
+    except ValueError:
+        pass
+
+    route_authorization: dict[str, str] = {}
+    if args.route_implement:
+        route_authorization["implement"] = args.route_implement
+    if args.route_check:
+        route_authorization["check"] = args.route_check
+
+    run_id = args.run_id or _new_run_id()
+    queue = [_make_item(repo_root, task) for task in args.tasks]
+    now = _utc_now()
+    state = {
+        "schema_version": SCHEMA_VERSION,
+        "run_id": run_id,
+        "status": "running",
+        "profile": args.profile,
+        "created_at": now,
+        "updated_at": now,
+        "owner": {"host": socket.gethostname(), "pid": os.getpid()},
+        "current_index": 0,
+        "route_authorization": route_authorization,
+        "queue": queue,
+        "resume_capsule": {},
+    }
+    path = _run_path(repo_root, run_id)
+    _write_state(path, state)
+    _write_pointer(repo_root, run_id)
+    _link_session_run(repo_root, run_id)
+    return _print({"status": "started", "path": _rel_path(repo_root, path), **_summary(state)})
+
+
+def cmd_resume(args: argparse.Namespace) -> int:
+    """恢复 auto run 摘要。"""
+    repo_root = _repo_root()
+    if repo_root is None:
+        return _print({"status": "error", "reason": "not-trellis-project"})
+    try:
+        path, state = _load_current_state(repo_root, args.run_id)
+    except ValueError as exc:
+        return _print({"status": "error", "reason": "resume-failed", "message": str(exc)})
+    _link_session_run(repo_root, str(state.get("run_id")))
+    return _print({"status": "resumed", "path": _rel_path(repo_root, path), **_summary(state)})
+
+
+def cmd_next(args: argparse.Namespace) -> int:
+    """计算下一步动作。"""
+    repo_root = _repo_root()
+    if repo_root is None:
+        return _print({"status": "error", "reason": "not-trellis-project"})
+    try:
+        path, state = _load_current_state(repo_root, args.run_id)
+    except ValueError as exc:
+        return _print({"status": "error", "reason": "next-failed", "message": str(exc)})
+    _link_session_run(repo_root, str(state.get("run_id")))
+    if state.get("status") != "running":
+        output_status = "done" if state.get("status") == "completed" else state.get("status") or "unknown"
+        return _print({"run_id": state.get("run_id"), "status": output_status, "summary": _summary(state)})
+    _, action = _next_item(repo_root, state)
+    _write_state(path, state)
+    if action.get("status") == "done":
+        action["summary"] = _summary(state)
+    return _print({"run_id": state.get("run_id"), **action})
+
+
+def _find_record_item(state: dict[str, Any], task_ref: str | None) -> dict[str, Any] | None:
+    """找到 record 要更新的队列项。"""
+    queue = state.get("queue") if isinstance(state.get("queue"), list) else []
+    if task_ref:
+        for item in queue:
+            if isinstance(item, dict) and item.get("task") == task_ref:
+                return item
+    for item in queue:
+        if isinstance(item, dict) and item.get("status") == "running":
+            return item
+    return None
+
+
+def _advance_after_ok(item: dict[str, Any], action: str, args: argparse.Namespace) -> None:
+    """根据成功动作推进 current_step。"""
+    if action == "refresh_brief":
+        item["current_step"] = "start_task"
+    elif action == "start_task":
+        item["current_step"] = "implement"
+    elif action in {"run_implement", "run_fix"}:
+        item["current_step"] = "check" if action == "run_implement" else "recheck"
+    elif action in {"run_check_all", "run_recheck"}:
+        item["current_step"] = "spec_update"
+    elif action == "run_spec_update":
+        item["current_step"] = "commit_only"
+    elif action == "commit_only":
+        item["status"] = "completed"
+        item["current_step"] = "done"
+        item["commit"] = args.commit
+    item["updated_at"] = _utc_now()
+
+
+def _record_failure(item: dict[str, Any], action: str, args: argparse.Namespace) -> None:
+    """记录失败并决定是否进入 fix 或 blocked。"""
+    item["last_failure"] = {
+        "action": action,
+        "failure_type": args.failure_type,
+        "summary": args.summary,
+        "files": args.files or [],
+        "failed_at": _utc_now(),
+    }
+    if action in {"run_implement", "run_check_all", "run_fix", "run_recheck"}:
+        attempts = item.setdefault("attempts", {})
+        attempts["fix_recheck"] = int(attempts.get("fix_recheck", 0)) + 1
+        if attempts["fix_recheck"] > MAX_FIX_RECHECK:
+            _block_item(item, "retry-budget-exhausted", args.summary or "fix/recheck 达到默认 3 轮预算")
+        else:
+            item["current_step"] = "fix"
+            item["updated_at"] = _utc_now()
+        return
+    _block_item(item, args.failure_type or "action-failed", args.summary or f"{action} 执行失败")
+
+
+def cmd_record(args: argparse.Namespace) -> int:
+    """记录 agent 执行结果。"""
+    repo_root = _repo_root()
+    if repo_root is None:
+        return _print({"status": "error", "reason": "not-trellis-project"})
+    try:
+        path, state = _load_current_state(repo_root, args.run_id)
+    except ValueError as exc:
+        return _print({"status": "error", "reason": "record-failed", "message": str(exc)})
+    if state.get("status") != "running":
+        return _print({
+            "status": "error",
+            "reason": "auto-run-not-running",
+            "run_status": state.get("status"),
+            "summary": _summary(state),
+        })
+
+    task = _normalize_task_ref(repo_root, args.task) if args.task else None
+    item = _find_record_item(state, task)
+    if item is None:
+        return _print({"status": "error", "reason": "no-running-task"})
+
+    if not args.action:
+        return _print({"status": "error", "reason": "missing-action", "message": "record 必须显式传入 --action"})
+    expected_action = _outstanding_action_name(item)
+    if expected_action is None:
+        return _print({
+            "status": "error",
+            "reason": "no-outstanding-action",
+            "message": "没有等待回写的 action；请先运行 next 获取下一步。",
+            "task": item.get("task"),
+            "current_step": item.get("current_step"),
+        })
+    if args.action != expected_action:
+        return _print({
+            "status": "error",
+            "reason": "action-mismatch",
+            "expected_action": expected_action,
+            "actual_action": args.action,
+            "task": item.get("task"),
+            "current_step": item.get("current_step"),
+        })
+
+    action = args.action
+    item["last_action"] = None
+    if args.result == "ok":
+        _advance_after_ok(item, action, args)
+    elif args.result == "failed":
+        _record_failure(item, action, args)
+    else:
+        _block_item(item, args.failure_type or "blocked", args.summary or "agent 标记 blocked")
+
+    _write_state(path, state)
+    return _print({"status": "recorded", "run_id": state.get("run_id"), "task": item.get("task"), "item": item, "summary": _summary(state)})
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    """输出 auto run 状态。"""
+    repo_root = _repo_root()
+    if repo_root is None:
+        return _print({"status": "error", "reason": "not-trellis-project"})
+    try:
+        path, state = _load_current_state(repo_root, args.run_id)
+    except ValueError as exc:
+        return _print({"status": "error", "reason": "status-failed", "message": str(exc)})
+    return _print({"status": "ok", "path": _rel_path(repo_root, path), **_summary(state)})
+
+
+def cmd_stop(args: argparse.Namespace) -> int:
+    """停止 auto run。"""
+    repo_root = _repo_root()
+    if repo_root is None:
+        return _print({"status": "error", "reason": "not-trellis-project"})
+    try:
+        path, state = _load_current_state(repo_root, args.run_id)
+    except ValueError as exc:
+        return _print({"status": "error", "reason": "stop-failed", "message": str(exc)})
+    state["status"] = "stopped"
+    state["stop_reason"] = args.reason
+    _write_state(path, state)
+    return _print({"status": "stopped", "run_id": state.get("run_id"), "path": _rel_path(repo_root, path), "reason": args.reason})
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """构造命令行解析器。"""
+    parser = argparse.ArgumentParser(description="Trellis auto loop runner.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    start = subparsers.add_parser("start", help="create an auto loop run")
+    start.add_argument("--tasks", nargs="+", required=True)
+    start.add_argument("--run-id")
+    start.add_argument("--profile", choices=(DEFAULT_PROFILE,), default=DEFAULT_PROFILE)
+    start.add_argument("--route-implement", choices=sorted(VALID_IMPLEMENT_ROUTES))
+    start.add_argument("--route-check", choices=sorted(VALID_CHECK_ROUTES))
+    start.add_argument("--force", action="store_true")
+    start.set_defaults(func=cmd_start)
+
+    for name, func in (("resume", cmd_resume), ("next", cmd_next), ("status", cmd_status)):
+        sub = subparsers.add_parser(name)
+        sub.add_argument("--run-id")
+        sub.set_defaults(func=func)
+
+    record = subparsers.add_parser("record")
+    record.add_argument("--run-id")
+    record.add_argument("--task")
+    record.add_argument("--action")
+    record.add_argument("--result", choices=("ok", "failed", "blocked"), required=True)
+    record.add_argument("--failure-type")
+    record.add_argument("--summary")
+    record.add_argument("--files", nargs="*")
+    record.add_argument("--commit")
+    record.set_defaults(func=cmd_record)
+
+    stop = subparsers.add_parser("stop")
+    stop.add_argument("--run-id")
+    stop.add_argument("--reason")
+    stop.set_defaults(func=cmd_stop)
+
+    return parser
+
+
+def main() -> int:
+    """脚本入口。"""
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        return args.func(args)
+    except ValueError as exc:
+        return _print({"status": "error", "reason": "invalid-input", "message": str(exc)})
+
+
+if __name__ == "__main__":
+    sys.exit(main())