@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/creative/kanban-video-orchestrator/scripts/bootstrap_pipeline.py

@@ -0,0 +1,499 @@
+#!/usr/bin/env python3
+"""
+Bootstrap a video production kanban from a structured plan JSON.
+
+Reads a plan.json describing the team + brief, expands templates from
+../assets/, and writes a setup.sh that creates Hermes profiles and fires the
+initial kanban task.
+
+Profile-config patching, SOUL.md-per-profile, TEAM.md task-graph convention,
+and the `hermes kanban create --workspace dir:` initial-task pattern are
+adapted from alt-glitch's NousResearch/kanban-video-pipeline.
+
+Usage:
+    bootstrap_pipeline.py plan.json [--out setup.sh]
+
+The plan.json schema is documented inline below — see the `validate_plan`
+function. A minimal example:
+
+    {
+      "title": "Q3 Product Teaser",
+      "slug": "q3-product-teaser",
+      "tenant": "q3-product-teaser",
+      "duration_s": 30,
+      "aspect": "1:1",
+      "resolution": "1080x1080",
+      "fps": 30,
+      "team": [
+        {
+          "profile": "director",
+          "role": "director",
+          "toolsets": ["kanban", "terminal", "file"],
+          "skills": [],
+          "responsibilities": "...",
+          "inputs": "brief.md, TEAM.md, taste/",
+          "outputs": "kanban tasks for the team"
+        },
+        ...
+      ],
+      "scenes": [
+        {"n": 1, "time": "0:00-0:08", "content": "...", "tool": "renderer-ascii"},
+        ...
+      ],
+      "audio": {"approach": "voiceover + music bed", "vo": "ElevenLabs Lily",
+                "music": "license-free", "sfx": "n/a"},
+      "deliverables": [
+        {"format": "mp4", "resolution": "1080x1080", "notes": "primary"}
+      ],
+      "api_keys_required": ["ELEVENLABS_API_KEY", "OPENROUTER_API_KEY"],
+      "brief_extra": {
+        "concept_one_liner": "...",
+        "emotional_north_star": "...",
+        "visual_refs": "...",
+        "tone": "...",
+        "brand_constraints": "..."
+      }
+    }
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+ASSETS_DIR = Path(__file__).resolve().parent.parent / "assets"
+
+
+def load_template(name: str) -> str:
+    return (ASSETS_DIR / name).read_text()
+
+
+PROFILE_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]+$")
+
+
+def validate_plan(plan: dict) -> list[str]:
+    """Return a list of validation error strings; empty list = valid."""
+    errors = []
+    required_top = ["title", "slug", "tenant", "duration_s", "aspect",
+                    "resolution", "fps", "team", "scenes", "audio",
+                    "deliverables"]
+    for k in required_top:
+        if k not in plan:
+            errors.append(f"missing required key: {k}")
+
+    if "team" in plan:
+        if not isinstance(plan["team"], list) or not plan["team"]:
+            errors.append("team must be a non-empty list")
+        else:
+            roles = [t.get("role") for t in plan["team"]]
+            if "director" not in roles:
+                errors.append("team must include a director role")
+            seen_profiles = set()
+            for i, t in enumerate(plan["team"]):
+                for k in ["profile", "role", "toolsets", "skills",
+                          "responsibilities"]:
+                    if k not in t:
+                        errors.append(f"team[{i}] missing {k}")
+                # Profile 名称必须匹配 Hermes 的正则表达式（小写
+                # 字母数字 + 连字符 + 下划线，最多 64 个字符）。
+                if "profile" in t:
+                    if not PROFILE_NAME_RE.match(t["profile"]):
+                        errors.append(
+                            f"team[{i}].profile {t['profile']!r} must match "
+                            f"[a-z0-9][a-z0-9_-]{{0,63}} per Hermes profile rules"
+                        )
+                    if t["profile"] in seen_profiles:
+                        errors.append(
+                            f"team[{i}].profile {t['profile']!r} is duplicated"
+                        )
+                    seen_profiles.add(t["profile"])
+                # 工具集 / 技能必须是列表，而不是字符串。
+                if "toolsets" in t and not isinstance(t["toolsets"], list):
+                    errors.append(
+                        f"team[{i}].toolsets must be a list of strings"
+                    )
+                if "skills" in t and not isinstance(t["skills"], list):
+                    errors.append(
+                        f"team[{i}].skills must be a list of strings"
+                    )
+
+    if "slug" in plan:
+        if not SLUG_RE.match(plan["slug"]):
+            errors.append("slug must be lowercase, hyphenated, "
+                          "starting with [a-z0-9]")
+
+    return errors
+
+
+def render_brief(plan: dict) -> str:
+    """Render brief.md from the plan."""
+    tmpl = load_template("brief.md.tmpl")
+    extra = plan.get("brief_extra", {})
+
+    # 场景表行
+    scene_rows = []
+    for s in plan["scenes"]:
+        scene_rows.append(
+            f"| {s.get('n', '?')} | {s.get('time', '?')} | "
+            f"{s.get('content', '')} | {s.get('tool', '')} | "
+            f"{s.get('audio', '')} | {s.get('notes', '')} |"
+        )
+    scene_table = "\n".join(scene_rows) if scene_rows else "_(none yet)_"
+
+    # 交付物行
+    deliv_rows = []
+    for d in plan["deliverables"]:
+        deliv_rows.append(
+            f"| {d.get('format', '?')} | {d.get('resolution', '?')} | "
+            f"{d.get('notes', '')} |"
+        )
+    deliv_table = "\n".join(deliv_rows) if deliv_rows else "_(none)_"
+
+    # 替换（单次处理）
+    replacements = {
+        "TITLE": plan["title"],
+        "SLUG": plan["slug"],
+        "TENANT": plan["tenant"],
+        "WORKSPACE": f"~/projects/video-pipeline/{plan['slug']}",
+        "ONE_LINE_PITCH": extra.get("concept_one_liner", "_(TBD)_"),
+        "EMOTIONAL_NORTH_STAR": extra.get("emotional_north_star", "_(TBD)_"),
+        "DURATION_S": str(plan["duration_s"]),
+        "ASPECT": plan["aspect"],
+        "RESOLUTION": plan["resolution"],
+        "FPS": str(plan["fps"]),
+        "PLATFORMS": extra.get("platforms", "_(TBD)_"),
+        "DEADLINE": extra.get("deadline", "_(none)_"),
+        "QUALITY_BAR": extra.get("quality_bar", "polished"),
+        "VISUAL_REFS": extra.get("visual_refs", "_(none)_"),
+        "TONE": extra.get("tone", "_(TBD)_"),
+        "BRAND_CONSTRAINTS": extra.get("brand_constraints", "_(none)_"),
+        "AESTHETIC_RULES": extra.get("aesthetic_rules", "_(TBD)_"),
+        "AUDIO_APPROACH": plan["audio"].get("approach", "_(TBD)_"),
+        "VO_DETAILS": plan["audio"].get("vo", "_(n/a)_"),
+        "MUSIC_DETAILS": plan["audio"].get("music", "_(n/a)_"),
+        "SFX_DETAILS": plan["audio"].get("sfx", "_(n/a)_"),
+        "PRIMARY_FORMAT": plan["deliverables"][0]["format"],
+        "PRIMARY_RES": plan["deliverables"][0]["resolution"],
+        "ALT_FORMAT_1": (plan["deliverables"][1]["format"]
+                          if len(plan["deliverables"]) > 1 else "_(none)_"),
+        "ALT_RES_1": (plan["deliverables"][1]["resolution"]
+                       if len(plan["deliverables"]) > 1 else ""),
+        "ALT_NOTES_1": (plan["deliverables"][1].get("notes", "")
+                         if len(plan["deliverables"]) > 1 else ""),
+        "API_KEYS_REQUIRED": ", ".join(plan.get("api_keys_required", [])) or "none",
+        "EXT_DEPS": extra.get("ext_deps", "ffmpeg, Python 3.11+"),
+        "SOURCE_ASSETS": extra.get("source_assets", "_(none)_"),
+    }
+    out = tmpl
+    for k, v in replacements.items():
+        out = out.replace("{{" + k + "}}", str(v))
+
+    # 场景 + 交付物表：替换模板中的占位行
+    out = re.sub(
+        r"\|\s*1\s*\|\s*0:00–0:0X.+?\n\|\s*2\s*\|.+?\n",
+        scene_table + "\n",
+        out, flags=re.DOTALL,
+    )
+    return out
+
+
+def render_team_md(plan: dict) -> str:
+    """Render TEAM.md from the team list + scene → tool mapping."""
+    lines = [f"# Team & Task Graph — {plan['title']}", "", "## Team", ""]
+    for t in plan["team"]:
+        skills = (
+            f"loads `{', '.join(t['skills'])}`"
+            if t["skills"] else "no skills required"
+        )
+        lines.append(
+            f"- `{t['profile']}` — {t['responsibilities']} ({skills})"
+        )
+    lines.extend(["", "## Task Graph", "", "```"])
+
+    # 根据约定构建一个简单的任务图
+    profiles_by_role = {t["role"]: t["profile"] for t in plan["team"]}
+    director = profiles_by_role.get("director", "director")
+    lines.append(f"T0  {director} — decompose")
+
+    next_id = 1
+    parents_for_renderer: list[str] = ["T0"]
+
+    if "cinematographer" in profiles_by_role:
+        cid = f"T{next_id}"
+        lines.append(
+            f"{cid:5} {profiles_by_role['cinematographer']} — visual spec for all scenes (parent: T0)"
+        )
+        parents_for_renderer = [cid]
+        next_id += 1
+
+    if "music-supervisor" in profiles_by_role:
+        cid = f"T{next_id}"
+        lines.append(
+            f"{cid:5} {profiles_by_role['music-supervisor']} — track analysis + beats.json (parent: T0)"
+        )
+        next_id += 1
+        ms_id = cid
+    else:
+        ms_id = None
+
+    # 场景
+    scene_ids = []
+    for s in plan["scenes"]:
+        cid = f"T{next_id}"
+        renderer_profile = s.get("tool") or "renderer"
+        # 查找实际的 profile 名称
+        for t in plan["team"]:
+            if t["role"] == renderer_profile or t["profile"] == renderer_profile:
+                renderer_profile = t["profile"]
+                break
+        parents = parents_for_renderer + ([ms_id] if ms_id else [])
+        parent_str = ", ".join(parents)
+        lines.append(
+            f"{cid:5} {renderer_profile} — scene {s.get('n', '?')}: "
+            f"{s.get('content', '')[:50]} (parents: {parent_str})"
+        )
+        scene_ids.append(cid)
+        next_id += 1
+
+    # VO + 音频混合
+    if "voice-talent" in profiles_by_role:
+        vo_id = f"T{next_id}"
+        lines.append(f"{vo_id:5} {profiles_by_role['voice-talent']} — narration (parent: T0)")
+        next_id += 1
+    else:
+        vo_id = None
+
+    if "audio-mixer" in profiles_by_role:
+        am_id = f"T{next_id}"
+        am_parents = [p for p in [ms_id, vo_id] if p]
+        lines.append(
+            f"{am_id:5} {profiles_by_role['audio-mixer']} — mix audio (parents: {', '.join(am_parents)})"
+        )
+        next_id += 1
+    else:
+        am_id = None
+
+    # 编辑器
+    if "editor" in profiles_by_role:
+        ed_id = f"T{next_id}"
+        ed_parents = scene_ids + [p for p in [am_id, vo_id, ms_id] if p and p not in scene_ids]
+        lines.append(
+            f"{ed_id:5} {profiles_by_role['editor']} — assemble + mux (parents: {', '.join(ed_parents)})"
+        )
+        next_id += 1
+    else:
+        ed_id = None
+
+    # 字幕生成器
+    if "captioner" in profiles_by_role and ed_id:
+        cap_id = f"T{next_id}"
+        lines.append(
+            f"{cap_id:5} {profiles_by_role['captioner']} — SRT + burn (parent: {ed_id})"
+        )
+        next_id += 1
+        last = cap_id
+    else:
+        last = ed_id
+
+    # 审阅者
+    if "reviewer" in profiles_by_role and last:
+        rv_id = f"T{next_id}"
+        lines.append(
+            f"{rv_id:5} {profiles_by_role['reviewer']} — final QA (parent: {last})"
+        )
+
+    lines.append("```")
+    lines.extend([
+        "",
+        "## Per-task workspace requirement",
+        "",
+        f"All `kanban_create` calls MUST pass:",
+        f"```",
+        f'workspace_kind="dir"',
+        f'workspace_path="$HOME/projects/video-pipeline/{plan["slug"]}"',
+        f'tenant="{plan["tenant"]}"',
+        f"```",
+    ])
+    return "\n".join(lines)
+
+
+def render_setup_sh(plan: dict, brief_md: str, team_md: str) -> str:
+    """Render setup.sh from the plan."""
+    tmpl = load_template("setup.sh.tmpl")
+
+    # API 密钥检查
+    key_checks = []
+    for key in plan.get("api_keys_required", []):
+        key_checks.append(f'check_key {key} hermes {key} || exit 1')
+    key_checks_str = "\n".join(key_checks) if key_checks else "# (no API keys required)"
+
+    # 场景目录
+    scene_dir_lines = []
+    for s in plan["scenes"]:
+        n = s.get("n", "?")
+        scene_dir_lines.append(f'mkdir -p "$WORKSPACE/scenes/scene-{n:02d}"/checkpoints')
+    scene_dirs = "\n".join(scene_dir_lines) if scene_dir_lines else ""
+
+    # 创建 Profile
+    profile_creates = []
+    for t in plan["team"]:
+        profile_creates.append(
+            f'hermes profile create {t["profile"]} --clone 2>/dev/null || true'
+        )
+
+    # Profile 配置 — 输出 JSON 数组，以便 bash 函数能将它们
+    # 安全地传递给 Python YAML 修补程序。
+    profile_configs = []
+    for t in plan["team"]:
+        ts_json = json.dumps(t["toolsets"])
+        sk_json = json.dumps(t["skills"])
+        # 使用单引号 bash 字符串；JSON 只包含 "/[/] ，不包含单
+        # 引号，因此这是安全的。
+        profile_configs.append(
+            f"configure_profile {t['profile']!r} {ts_json!r} {sk_json!r}"
+        )
+
+    # SOUL 写入 — 每个 profile 使用 heredoc
+    soul_writes = []
+    for t in plan["team"]:
+        soul_writes.append(
+            f'cat > "$HOME/.hermes/profiles/{t["profile"]}/SOUL.md" <<\'SOUL_EOF\'\n'
+            f"{render_soul_md(t, plan)}\n"
+            f"SOUL_EOF\n"
+            f'echo "  ✓ SOUL.md for {t["profile"]}"'
+        )
+
+    # Taste 写入（占位符；实际内容可选）
+    taste_writes = (
+        'cat > "$WORKSPACE/taste/brand-guide.md" <<\'TASTE_EOF\'\n'
+        '# Brand Guide\n\n'
+        '_(Populate with project-specific colors, typography, motion rules)_\n'
+        'TASTE_EOF\n'
+        'cat > "$WORKSPACE/taste/emotional-dna.md" <<\'DNA_EOF\'\n'
+        '# Emotional DNA\n\n'
+        '_(What this piece should FEEL like — populate from the brief.)_\n'
+        'DNA_EOF'
+    )
+
+    # 资源副本 — 默认留空；由用户填写
+    asset_copies = "# Add cp/rsync commands here for any provided assets"
+
+    out = tmpl
+    out = out.replace("{{TITLE}}", plan["title"])
+    out = out.replace("{{SLUG}}", plan["slug"])
+    out = out.replace("{{TENANT}}", plan["tenant"])
+    out = out.replace("{{WORKSPACE}}", f"~/projects/video-pipeline/{plan['slug']}")
+    out = out.replace("{{KEY_CHECKS}}", key_checks_str)
+    out = out.replace("{{SCENE_DIRS}}", scene_dirs)
+    out = out.replace("{{PROFILE_CREATE_COMMANDS}}", "\n".join(profile_creates))
+    out = out.replace("{{PROFILE_CONFIG_COMMANDS}}", "\n".join(profile_configs))
+    out = out.replace("{{SOUL_WRITES}}", "\n".join(soul_writes))
+    out = out.replace("{{BRIEF_CONTENTS}}", brief_md)
+    out = out.replace("{{TEAM_CONTENTS}}", team_md)
+    out = out.replace("{{TASTE_WRITES}}", taste_writes)
+    out = out.replace("{{ASSET_COPIES}}", asset_copies)
+
+    return out
+
+
+def render_soul_md(team_member: dict, plan: dict) -> str:
+    """Render a profile's SOUL.md from a team member dict + plan context."""
+    tmpl = load_template("soul.md.tmpl")
+    role = team_member["role"]
+
+    common_rules = (
+        "- **Read the brief and team graph** before doing anything else.\n"
+        "- **Pass `workspace_kind=\"dir\"` and `workspace_path` on every "
+        "`kanban_create` call.** This keeps the team in one shared workspace.\n"
+        f"- **Use tenant `{plan['tenant']}`** on every kanban call.\n"
+        "- **Write outputs to predictable paths.** Other profiles depend on "
+        "your filename conventions.\n"
+        "- **Emit heartbeats** during long-running work. Renderers should "
+        "report frame counts; editors should report assembly progress.\n"
+    )
+
+    if role == "director":
+        common_rules += (
+            "- **Do not execute the work yourself.** For every concrete task, "
+            "create a kanban task and assign it to the appropriate profile.\n"
+            "- **Decompose, route, comment, approve — that's the whole job.**\n"
+            "- **Read TEAM.md** for the canonical task graph. Do not invent "
+            "new roles unless the brief truly demands it.\n"
+        )
+
+    common_commands = (
+        "```bash\n"
+        "# Inspect a clip\n"
+        "ffprobe -v quiet -show_entries format=duration -show_entries "
+        "stream=codec_name,width,height,r_frame_rate <file.mp4>\n"
+        "\n"
+        "# Extract a frame for QA\n"
+        "ffmpeg -y -i <input.mp4> -vf \"select='eq(n,30)'\" -vsync vfr <out.png>\n"
+        "```"
+    )
+
+    out = tmpl
+    out = out.replace("{{ROLE_NAME}}", role)
+    out = out.replace("{{ROLE_RESPONSIBILITIES}}", team_member["responsibilities"])
+    out = out.replace("{{INPUTS_READ}}", team_member.get("inputs", "_(see brief)_"))
+    out = out.replace("{{OUTPUTS_PRODUCED}}", team_member.get("outputs", "_(see brief)_"))
+    out = out.replace("{{TOOLSETS}}", ", ".join(team_member["toolsets"]))
+    out = out.replace(
+        "{{SKILLS}}",
+        ", ".join(team_member["skills"]) if team_member["skills"] else "(none)"
+    )
+    out = out.replace(
+        "{{EXTERNAL_TOOLS}}",
+        team_member.get("external_tools", "ffmpeg, ffprobe (via terminal)")
+    )
+    out = out.replace(
+        "{{ROLE_RULES}}",
+        team_member.get("role_rules", "_(see TEAM.md and brief.md)_")
+    )
+    out = out.replace("{{COMMON_RULES}}", common_rules)
+    out = out.replace("{{COMMON_COMMANDS}}", common_commands)
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                  formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("plan_json", help="Path to plan.json")
+    ap.add_argument("--out", default="setup.sh",
+                    help="Output path for setup.sh (default: ./setup.sh)")
+    ap.add_argument("--brief-out", default=None,
+                    help="Write brief.md alongside (default: skipped)")
+    ap.add_argument("--team-out", default=None,
+                    help="Write TEAM.md alongside (default: skipped)")
+    args = ap.parse_args()
+
+    plan = json.loads(Path(args.plan_json).read_text())
+    errors = validate_plan(plan)
+    if errors:
+        print("Plan validation failed:", file=sys.stderr)
+        for e in errors:
+            print(f"  - {e}", file=sys.stderr)
+        sys.exit(2)
+
+    brief = render_brief(plan)
+    team = render_team_md(plan)
+    setup = render_setup_sh(plan, brief, team)
+
+    Path(args.out).write_text(setup)
+    os.chmod(args.out, 0o755)
+    print(f"Wrote {args.out}")
+
+    if args.brief_out:
+        Path(args.brief_out).write_text(brief)
+        print(f"Wrote {args.brief_out}")
+    if args.team_out:
+        Path(args.team_out).write_text(team)
+        print(f"Wrote {args.team_out}")
+
+
+if __name__ == "__main__":
+    main()

package/extensions/skills/optional/creative/kanban-video-orchestrator/scripts/monitor.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""
+Monitor a running video-production kanban. Polls `hermes kanban list` and
+`events` for a tenant and surfaces issues (stuck tasks, missing heartbeats,
+repeated retries, dependency deadlocks).
+
+Usage:
+    monitor.py --tenant <project-slug> [--interval 30]
+
+Outputs a periodic snapshot to stdout. Sends alerts via stderr when issues
+are detected. Designed to run alongside the kanban — kill with Ctrl-C when
+you're satisfied (or scripted to stop on completion).
+
+This is best-effort observability. It does not auto-restart tasks; intervention
+decisions should remain human/AI-overseen.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import time
+from collections import defaultdict
+from datetime import datetime, timedelta
+
+
+def hermes_available() -> bool:
+    return shutil.which("hermes") is not None
+
+
+def kanban_list(tenant: str) -> list[dict]:
+    """Returns parsed task rows. Falls back to plain stdout parsing if JSON
+    output isn't supported by the installed hermes CLI."""
+    try:
+        out = subprocess.run(
+            ["hermes", "kanban", "list", "--tenant", tenant, "--json"],
+            capture_output=True, text=True, check=False,
+        )
+        if out.returncode == 0 and out.stdout.strip().startswith("["):
+            return json.loads(out.stdout)
+    except (FileNotFoundError, json.JSONDecodeError):
+        pass
+    # 备选方案：解析 `hermes kanban list` 的文本输出
+    out = subprocess.run(
+        ["hermes", "kanban", "list", "--tenant", tenant],
+        capture_output=True, text=True, check=False,
+    )
+    rows = []
+    for line in out.stdout.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "STATUS" in line.upper():
+            continue
+        parts = line.split()
+        if len(parts) >= 4 and parts[0].startswith("t_"):
+            rows.append({
+                "id": parts[0],
+                "status": parts[1] if len(parts) > 1 else "?",
+                "assignee": parts[2] if len(parts) > 2 else "?",
+                "title": " ".join(parts[3:]) if len(parts) > 3 else "",
+                "started_at": None,
+                "heartbeat_at": None,
+                "max_runtime_s": None,
+            })
+    return rows
+
+
+def kanban_show(task_id: str) -> dict | None:
+    out = subprocess.run(
+        ["hermes", "kanban", "show", task_id, "--json"],
+        capture_output=True, text=True, check=False,
+    )
+    if out.returncode != 0:
+        return None
+    try:
+        return json.loads(out.stdout)
+    except json.JSONDecodeError:
+        return None
+
+
+def detect_issues(tasks: list[dict]) -> list[str]:
+    """Return a list of issue strings, one per concern."""
+    now = datetime.now()
+    issues: list[str] = []
+    by_status = defaultdict(list)
+    for t in tasks:
+        by_status[t.get("status", "?")].append(t)
+
+    # 卡住的任务：运行中且 2 分钟内无心跳
+    for t in by_status.get("running", []) + by_status.get("RUNNING", []):
+        hb = t.get("heartbeat_at")
+        if not hb:
+            continue
+        try:
+            hb_dt = datetime.fromisoformat(str(hb).rstrip("Z"))
+        except ValueError:
+            continue
+        if now - hb_dt > timedelta(minutes=2):
+            issues.append(
+                f"STUCK: {t['id']} ({t.get('assignee', '?')}) — "
+                f"no heartbeat in {(now - hb_dt).total_seconds():.0f}s"
+            )
+
+    # 超过最大运行时间的任务
+    for t in by_status.get("running", []) + by_status.get("RUNNING", []):
+        started = t.get("started_at")
+        max_rt = t.get("max_runtime_s")
+        if not started or not max_rt:
+            continue
+        try:
+            started_dt = datetime.fromisoformat(str(started).rstrip("Z"))
+        except ValueError:
+            continue
+        elapsed = (now - started_dt).total_seconds()
+        if elapsed > max_rt:
+            issues.append(
+                f"OVERTIME: {t['id']} ({t.get('assignee', '?')}) — "
+                f"running {elapsed:.0f}s, cap was {max_rt}s"
+            )
+
+    # 反复重试
+    for t in tasks:
+        retries = t.get("retries", 0)
+        if retries and retries >= 2:
+            issues.append(
+                f"FLAPPING: {t['id']} ({t.get('assignee', '?')}) — "
+                f"retried {retries}× — fix root cause before next run"
+            )
+
+    return issues
+
+
+def snapshot(tenant: str) -> tuple[list[dict], list[str]]:
+    tasks = kanban_list(tenant)
+    issues = detect_issues(tasks)
+    return tasks, issues
+
+
+def print_snapshot(tasks: list[dict], issues: list[str]):
+    counts = defaultdict(int)
+    for t in tasks:
+        counts[str(t.get("status", "?")).lower()] += 1
+
+    print(f"\n[{datetime.now().strftime('%H:%M:%S')}] "
+          f"Total: {len(tasks)} | "
+          + " | ".join(f"{k}: {v}" for k, v in sorted(counts.items())))
+
+    for t in tasks:
+        bar = "✓" if str(t.get("status", "")).lower() == "done" else \
+              "▶" if str(t.get("status", "")).lower() == "running" else \
+              "·" if str(t.get("status", "")).lower() == "ready" else \
+              "✗" if str(t.get("status", "")).lower() == "failed" else "?"
+        print(f"  {bar} {t.get('id', '?'):14} {t.get('assignee', '?'):20}  "
+              f"{t.get('title', '')[:60]}")
+
+    if issues:
+        print("\n  ⚠  ISSUES:", file=sys.stderr)
+        for i in issues:
+            print(f"     {i}", file=sys.stderr)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                  formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--tenant", required=True,
+                    help="Project tenant slug to monitor")
+    ap.add_argument("--interval", type=int, default=30,
+                    help="Poll interval in seconds (default: 30)")
+    ap.add_argument("--once", action="store_true",
+                    help="Print one snapshot and exit (no polling loop)")
+    args = ap.parse_args()
+
+    if not hermes_available():
+        print("ERROR: 'hermes' CLI not found in PATH", file=sys.stderr)
+        sys.exit(1)
+
+    if args.once:
+        tasks, issues = snapshot(args.tenant)
+        print_snapshot(tasks, issues)
+        sys.exit(0 if not issues else 2)
+
+    print(f"Monitoring tenant '{args.tenant}' every {args.interval}s. "
+          "Ctrl-C to exit.")
+    try:
+        while True:
+            tasks, issues = snapshot(args.tenant)
+            print_snapshot(tasks, issues)
+            time.sleep(args.interval)
+    except KeyboardInterrupt:
+        print("\nStopped.")
+
+
+if __name__ == "__main__":
+    main()