bridgeflow 0.1.0__py3-none-any.whl

bridgeflow/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

bridgeflow/binding.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+import secrets
+import string
+
+from bridgeflow.config import PatrolConfig
+
+
+BIND_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
+
+
+def _now() -> datetime:
+    return datetime.now()
+
+
+def _fmt(dt: datetime) -> str:
+    return dt.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _parse(value: str) -> datetime | None:
+    if not value:
+        return None
+    try:
+        return datetime.strptime(value, "%Y-%m-%d %H:%M:%S")
+    except ValueError:
+        return None
+
+
+def _new_code(length: int = 6) -> str:
+    return "".join(secrets.choice(BIND_ALPHABET) for _ in range(length))
+
+
+def has_active_bind_code(config: PatrolConfig) -> bool:
+    if not config.pending_bind_code or not config.pending_bind_expires_at:
+        return False
+    expires_at = _parse(config.pending_bind_expires_at)
+    return expires_at is not None and expires_at >= _now()
+
+
+def public_bind_state(config: PatrolConfig) -> dict:
+    return {
+        "status": config.bind_status,
+        "machine_code": config.machine_code,
+        "bound_mobile_device_id": config.bound_mobile_device_id,
+        "bound_mobile_device_name": config.bound_mobile_device_name,
+        "bound_at": config.bound_at,
+        "has_pending_code": has_active_bind_code(config),
+        "pending_bind_expires_at": config.pending_bind_expires_at if has_active_bind_code(config) else "",
+        "pending_mobile_device_id": config.pending_mobile_device_id,
+        "pending_mobile_device_name": config.pending_mobile_device_name,
+        "bind_code_ttl_seconds": config.bind_code_ttl_seconds,
+    }
+
+
+def private_bind_state(config: PatrolConfig) -> dict:
+    data = public_bind_state(config)
+    data["pending_bind_code"] = config.pending_bind_code if has_active_bind_code(config) else ""
+    data["last_bind_code_issued_at"] = config.last_bind_code_issued_at
+    return data
+
+
+def issue_bind_code(
+    config: PatrolConfig,
+    *,
+    mobile_device_id: str = "",
+    mobile_device_name: str = "",
+) -> dict:
+    now = _now()
+    code = _new_code()
+    expires_at = now + timedelta(seconds=config.bind_code_ttl_seconds)
+    config.update_bind(
+        status="pending",
+        pending_bind_code=code,
+        pending_bind_expires_at=_fmt(expires_at),
+        pending_mobile_device_id=mobile_device_id.strip(),
+        pending_mobile_device_name=mobile_device_name.strip(),
+        last_bind_code_issued_at=_fmt(now),
+    )
+    return private_bind_state(config)
+
+
+def approve_bind(
+    config: PatrolConfig,
+    *,
+    bind_code: str,
+    mobile_device_id: str,
+    mobile_device_name: str,
+) -> dict:
+    bind_code = bind_code.strip().upper()
+    if not bind_code:
+        raise ValueError("绑定码不能为空")
+    if not mobile_device_id.strip():
+        raise ValueError("mobile_device_id 不能为空")
+    if not has_active_bind_code(config):
+        raise ValueError("当前没有可用的绑定码")
+    if bind_code != config.pending_bind_code.strip().upper():
+        raise ValueError("绑定码不正确")
+
+    now = _now()
+    config.update_bind(
+        status="bound",
+        bound_mobile_device_id=mobile_device_id.strip(),
+        bound_mobile_device_name=mobile_device_name.strip(),
+        bound_at=_fmt(now),
+        pending_bind_code="",
+        pending_bind_expires_at="",
+        pending_mobile_device_id="",
+        pending_mobile_device_name="",
+    )
+    return public_bind_state(config)
+
+
+def clear_binding(config: PatrolConfig) -> dict:
+    config.update_bind(
+        status="unbound",
+        bound_mobile_device_id="",
+        bound_mobile_device_name="",
+        bound_at="",
+        pending_bind_code="",
+        pending_bind_expires_at="",
+        pending_mobile_device_id="",
+        pending_mobile_device_name="",
+    )
+    return public_bind_state(config)

bridgeflow/cli.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import hashlib
+import json
+import re
+import socket
+import sys
+import uuid
+from pathlib import Path
+
+from bridgeflow.binding import approve_bind, clear_binding, issue_bind_code, private_bind_state, public_bind_state
+from bridgeflow.config import DEFAULT_CONFIG_NAME, DEFAULT_FIXED_ROLES, load_config
+from bridgeflow.desktop.executor import execute_desktop_action
+from bridgeflow.desktop.patrol import patrol_once, print_doctor_result, run_doctor
+from bridgeflow.desktop.runner import start_desktop_bridge
+from bridgeflow.task_writer import write_admin_task, write_role_reply
+
+
+def _default_project_root() -> Path:
+    return Path.cwd()
+
+
+def _slug(value: str) -> str:
+    clean = re.sub(r"[^A-Za-z0-9_-]+", "-", value.strip())
+    clean = clean.strip("-").lower()
+    return clean or "bridgeflow-pc"
+
+
+def _build_machine_code(hostname: str) -> str:
+    seed = f"{hostname}-{uuid.getnode()}".encode("utf-8", errors="ignore")
+    digest = hashlib.sha1(seed).hexdigest()[:12].upper()
+    return f"BF-{digest}"
+
+
+def _print_bind_state(state: dict) -> None:
+    print(f"绑定状态：{state.get('status', '')}")
+    print(f"机器码：{state.get('machine_code', '')}")
+    if state.get("pending_bind_code"):
+        print(f"一次性绑定码：{state['pending_bind_code']}")
+    if state.get("pending_bind_expires_at"):
+        print(f"绑定码过期时间：{state['pending_bind_expires_at']}")
+    if state.get("pending_mobile_device_id") or state.get("pending_mobile_device_name"):
+        print(f"待确认手机：{state.get('pending_mobile_device_name', '')} {state.get('pending_mobile_device_id', '')}".strip())
+    if state.get("bound_mobile_device_id") or state.get("bound_mobile_device_name"):
+        print(f"已绑定手机：{state.get('bound_mobile_device_name', '')} {state.get('bound_mobile_device_id', '')}".strip())
+    if state.get("bound_at"):
+        print(f"绑定时间：{state['bound_at']}")
+
+
+def _print_action_result(result: dict) -> None:
+    print(f"动作：{result.get('action', '')}")
+    print(f"结果：{'成功' if result.get('ok') else '失败'}")
+    print(f"说明：{result.get('message', '')}")
+    print(f"窗口数：{result.get('window_count', 0)}")
+    print(f"目标窗口：{result.get('target_title', '')}")
+    if result.get("typed_text"):
+        print(f"发送文本：{result['typed_text']}")
+    print(f"dry-run：{result.get('dry_run', False)}")
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    project_root = Path(args.project_root or _default_project_root()).resolve()
+    project_root.mkdir(parents=True, exist_ok=True)
+    target = project_root / DEFAULT_CONFIG_NAME
+    example = Path(__file__).resolve().parents[2] / "examples" / DEFAULT_CONFIG_NAME
+    if target.exists() and not args.force:
+        print(f"配置已存在：{target}")
+        return 0
+
+    hostname = socket.gethostname() or "BridgeFlow-PC"
+    raw = json.loads(example.read_text(encoding="utf-8-sig"))
+    raw["project"]["root_dir"] = str(project_root)
+    raw.setdefault("device", {})
+    raw["device"]["device_id"] = f"{_slug(hostname)}-pc"
+    raw["device"]["device_name"] = f"{hostname} AI执行机"
+    raw["device"].setdefault("owner_role", "PM01")
+    raw["device"]["machine_code"] = _build_machine_code(hostname)
+
+    raw.setdefault("ai_team", {})
+    raw["ai_team"]["fixed_roles"] = DEFAULT_FIXED_ROLES[:]
+    raw["ai_team"]["cursor_only"] = True
+
+    raw.setdefault("bind", {})
+    raw["bind"].setdefault("status", "unbound")
+    raw["bind"].setdefault("bound_mobile_device_id", "")
+    raw["bind"].setdefault("bound_mobile_device_name", "")
+    raw["bind"].setdefault("bound_at", "")
+    raw["bind"].setdefault("bind_code_ttl_seconds", 600)
+    raw["bind"].setdefault("pending_bind_code", "")
+    raw["bind"].setdefault("pending_bind_expires_at", "")
+    raw["bind"].setdefault("pending_mobile_device_id", "")
+    raw["bind"].setdefault("pending_mobile_device_name", "")
+    raw["bind"].setdefault("last_bind_code_issued_at", "")
+
+    raw.setdefault("runtime", {})
+    raw["runtime"].setdefault("runtime_dir", ".bridgeflow/runtime")
+    raw["runtime"].setdefault("status_dir", ".bridgeflow/runtime/status")
+    raw["runtime"].setdefault("task_details_dir", ".bridgeflow/runtime/task_details")
+    raw["runtime"].setdefault("idle_seconds", 180)
+    raw["runtime"].setdefault("stale_task_seconds", 900)
+
+    target.write_text(json.dumps(raw, ensure_ascii=False, indent=2), encoding="utf-8")
+    config = load_config(target)
+    config.ensure_runtime_dirs()
+    print(f"已生成配置：{target}")
+    print(f"设备ID：{config.device_id}")
+    print(f"机器码：{config.machine_code}")
+    print(f"运行态目录：{config.runtime_dir}")
+    return 0
+
+
+def cmd_write_admin_task(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    written = write_admin_task(
+        config,
+        args.text,
+        recipient=args.recipient,
+        priority=args.priority,
+        attachments=args.attachments or [],
+        thread_key=args.thread_key,
+    )
+    print(f"已写入：{written.path}")
+    print(f"线程：{written.thread_key}")
+    return 0
+
+
+def cmd_write_reply(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    written = write_role_reply(
+        config,
+        args.text,
+        sender=args.sender,
+        recipient=args.recipient,
+        priority=args.priority,
+        attachments=args.attachments or [],
+        thread_key=args.thread_key,
+    )
+    print(f"已写入：{written.path}")
+    print(f"线程：{written.thread_key}")
+    return 0
+
+
+def cmd_bind_status(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    _print_bind_state(private_bind_state(config))
+    return 0
+
+
+def cmd_bind_code(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    state = issue_bind_code(
+        config,
+        mobile_device_id=args.mobile_device_id,
+        mobile_device_name=args.mobile_device_name,
+    )
+    _print_bind_state(state)
+    return 0
+
+
+def cmd_approve_bind(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    state = approve_bind(
+        config,
+        bind_code=args.code,
+        mobile_device_id=args.mobile_device_id,
+        mobile_device_name=args.mobile_device_name,
+    )
+    _print_bind_state(state)
+    return 0
+
+
+def cmd_unbind(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    state = clear_binding(config)
+    _print_bind_state(state)
+    return 0
+
+
+def cmd_desktop_action(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    result = execute_desktop_action(config, args.action, dry_run=args.dry_run).to_dict()
+    _print_action_result(result)
+    return 0 if result.get("ok") else 1
+
+
+def cmd_relay_connect(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    asyncio.run(start_desktop_bridge(config))
+    return 0
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    return cmd_relay_connect(args)
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    config.validate_roles()
+    config.ensure_runtime_dirs()
+    result = run_doctor(config)
+    print_doctor_result(result)
+    return 0 if result.tasks_dir_exists and result.reports_dir_exists else 1
+
+
+def cmd_patrol_once(args: argparse.Namespace) -> int:
+    config = load_config(args.config)
+    targets = sorted(patrol_once(config))
+    if not targets:
+        print("本轮未发现需要巡检的目标。")
+        return 0
+    print("本轮目标：")
+    for item in targets:
+        print(f"- {item}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="bridgeflow", description="BridgeFlow 人机协作桥接与团队巡检工具")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init_p = sub.add_parser("init", help="生成默认 bridgeflow_config.json")
+    init_p.add_argument("--project-root", default="")
+    init_p.add_argument("--force", action="store_true")
+    init_p.set_defaults(func=cmd_init)
+
+    bind_status_p = sub.add_parser("bind-status", help="查看当前绑定状态")
+    bind_status_p.add_argument("--config", default=DEFAULT_CONFIG_NAME)
+    bind_status_p.set_defaults(func=cmd_bind_status)
+
+    bind_code_p = sub.add_parser("bind-code", help="生成一次性绑定码")
+    bind_code_p.add_argument("--config", default=DEFAULT_CONFIG_NAME)
+    bind_code_p.add_argument("--mobile-device-id", default="")
+    bind_code_p.add_argument("--mobile-device-name", default="")
+    bind_code_p.set_defaults(func=cmd_bind_code)
+
+    approve_bind_p = sub.add_parser("approve-bind", help="确认手机绑定")
+    approve_bind_p.add_argument("--config", default=DEFAULT_CONFIG_NAME)
+    approve_bind_p.add_argument("--code", required=True)
+    approve_bind_p.add_argument("--mobile-device-id", required=True)
+    approve_bind_p.add_argument("--mobile-device-name", default="")
+    approve_bind_p.set_defaults(func=cmd_approve_bind)
+
+    unbind_p = sub.add_parser("unbind", help="解除当前绑定")
+    unbind_p.add_argument("--config", default=DEFAULT_CONFIG_NAME)
+    unbind_p.set_defaults(func=cmd_unbind)
+
+    action_p = sub.add_parser("desktop-action", help="执行 PC 端桌面动作")
+    action_p.add_argument("--config", default=DEFAULT_CONFIG_NAME)
+    action_p.add_argument("--action", choices=["focus_cursor", "inspect", "start_work"], required=True)
+    action_p.add_argument("--dry-run", action="store_true")
+    action_p.set_defaults(func=cmd_desktop_action)
+
+    write_p = sub.add_parser("write-admin-task", help="直接生成 ADMIN01 -> PM01 任务文件")
+    write_p.add_argument("--config", default=DEFAULT_CONFIG_NAME)
+    write_p.add_argument("--text", required=True)
+    write_p.add_argument("--recipient", default="")
+    write_p.add_argument("--priority", default="")
+    write_p.add_argument("--thread-key", default="")
+    write_p.add_argument("--attachments", nargs="*")
+    write_p.set_defaults(func=cmd_write_admin_task)
+
+    reply_p = sub.add_parser("write-reply", help="直接生成 PM/DEV/QA -> ADMIN01 回执文件")
+    reply_p.add_argument("--config", default=DEFAULT_CONFIG_NAME)
+    reply_p.add_argument("--sender", required=True, help="发送角色，如 PM01/DEV01/QA01")
+    reply_p.add_argument("--recipient", default="ADMIN01")
+    reply_p.add_argument("--text", required=True)
+    reply_p.add_argument("--priority", default="")
+    reply_p.add_argument("--thread-key", default="")
+    reply_p.add_argument("--attachments", nargs="*")
+    reply_p.set_defaults(func=cmd_write_reply)
+
+    relay_p = sub.add_parser("relay-connect", help="连接中继并启动桌面桥接")
+    relay_p.add_argument("--config", default=DEFAULT_CONFIG_NAME)
+    relay_p.set_defaults(func=cmd_relay_connect)
+
+    doctor_p = sub.add_parser("doctor", help="检查目录、模板和 pyautogui 环境")
+    doctor_p.add_argument("--config", default=DEFAULT_CONFIG_NAME)
+    doctor_p.set_defaults(func=cmd_doctor)
+
+    patrol_p = sub.add_parser("patrol-once", help="扫描当前任务/报告并输出本轮巡检目标")
+    patrol_p.add_argument("--config", default=DEFAULT_CONFIG_NAME)
+    patrol_p.set_defaults(func=cmd_patrol_once)
+
+    run_p = sub.add_parser("run", help="启动桌面桥接主循环")
+    run_p.add_argument("--config", default=DEFAULT_CONFIG_NAME)
+    run_p.set_defaults(func=cmd_run)
+
+    return parser
+
+
+def main() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    parser = build_parser()
+    args = parser.parse_args()
+    raise SystemExit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

bridgeflow/config.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_CONFIG_NAME = "bridgeflow_config.json"
+DEFAULT_FIXED_ROLES = ["ADMIN01", "PM01", "DEV01", "QA01"]
+
+
+@dataclass
+class PatrolConfig:
+    raw: dict
+    path: Path
+
+    @property
+    def relay_url(self) -> str:
+        return str(self.raw.get("relay", {}).get("url", "")).strip()
+
+    @property
+    def room_key(self) -> str:
+        return str(self.raw.get("relay", {}).get("room_key", "")).strip()
+
+    @property
+    def shared_secret(self) -> str:
+        return str(self.raw.get("relay", {}).get("shared_secret", "")).strip()
+
+    @property
+    def device_id(self) -> str:
+        return str(self.raw.get("device", {}).get("device_id", "")).strip()
+
+    @property
+    def device_name(self) -> str:
+        return str(self.raw.get("device", {}).get("device_name", "")).strip()
+
+    @property
+    def owner_role(self) -> str:
+        return str(self.raw.get("device", {}).get("owner_role", "")).strip()
+
+    @property
+    def machine_code(self) -> str:
+        return str(self.raw.get("device", {}).get("machine_code", "")).strip()
+
+    @property
+    def device_label(self) -> str:
+        return self.device_name or self.device_id or "未命名设备"
+
+    @property
+    def bind_status(self) -> str:
+        return str(self.raw.get("bind", {}).get("status", "unbound")).strip() or "unbound"
+
+    @property
+    def bound_mobile_device_id(self) -> str:
+        return str(self.raw.get("bind", {}).get("bound_mobile_device_id", "")).strip()
+
+    @property
+    def bound_mobile_device_name(self) -> str:
+        return str(self.raw.get("bind", {}).get("bound_mobile_device_name", "")).strip()
+
+    @property
+    def bound_at(self) -> str:
+        return str(self.raw.get("bind", {}).get("bound_at", "")).strip()
+
+    @property
+    def bind_code_ttl_seconds(self) -> int:
+        return int(self.raw.get("bind", {}).get("bind_code_ttl_seconds", 600))
+
+    @property
+    def pending_bind_code(self) -> str:
+        return str(self.raw.get("bind", {}).get("pending_bind_code", "")).strip()
+
+    @property
+    def pending_bind_expires_at(self) -> str:
+        return str(self.raw.get("bind", {}).get("pending_bind_expires_at", "")).strip()
+
+    @property
+    def pending_mobile_device_id(self) -> str:
+        return str(self.raw.get("bind", {}).get("pending_mobile_device_id", "")).strip()
+
+    @property
+    def pending_mobile_device_name(self) -> str:
+        return str(self.raw.get("bind", {}).get("pending_mobile_device_name", "")).strip()
+
+    @property
+    def last_bind_code_issued_at(self) -> str:
+        return str(self.raw.get("bind", {}).get("last_bind_code_issued_at", "")).strip()
+
+    @property
+    def project_root(self) -> Path:
+        root = self.raw.get("project", {}).get("root_dir", ".")
+        return Path(root).expanduser().resolve()
+
+    @property
+    def tasks_dir(self) -> Path:
+        rel = self.raw.get("project", {}).get("tasks_dir", "docs/agents/tasks")
+        return (self.project_root / rel).resolve()
+
+    @property
+    def reports_dir(self) -> Path:
+        rel = self.raw.get("project", {}).get("reports_dir", "docs/agents/reports")
+        return (self.project_root / rel).resolve()
+
+    @property
+    def issues_dir(self) -> Path:
+        rel = self.raw.get("project", {}).get("issues_dir", "docs/agents/issues")
+        return (self.project_root / rel).resolve()
+
+    @property
+    def templates_dir(self) -> Path:
+        rel = self.raw.get("patrol", {}).get("templates_dir", "ops/patrol_templates")
+        return (self.project_root / rel).resolve()
+
+    @property
+    def runtime_dir(self) -> Path:
+        rel = self.raw.get("runtime", {}).get("runtime_dir", ".bridgeflow/runtime")
+        return (self.project_root / rel).resolve()
+
+    @property
+    def status_dir(self) -> Path:
+        rel = self.raw.get("runtime", {}).get("status_dir", ".bridgeflow/runtime/status")
+        return (self.project_root / rel).resolve()
+
+    @property
+    def task_details_dir(self) -> Path:
+        rel = self.raw.get("runtime", {}).get("task_details_dir", ".bridgeflow/runtime/task_details")
+        return (self.project_root / rel).resolve()
+
+    @property
+    def heartbeat_file(self) -> Path:
+        return self.status_dir / "heartbeat.json"
+
+    @property
+    def device_status_file(self) -> Path:
+        return self.status_dir / "device_status.json"
+
+    @property
+    def task_index_file(self) -> Path:
+        return self.status_dir / "task_index.json"
+
+    @property
+    def last_activity_file(self) -> Path:
+        return self.status_dir / "last_activity.json"
+
+    @property
+    def admin_sender(self) -> str:
+        return str(self.raw.get("admin", {}).get("sender", "ADMIN01")).strip()
+
+    @property
+    def admin_target(self) -> str:
+        return str(self.raw.get("admin", {}).get("target", "PM01")).strip()
+
+    @property
+    def default_priority(self) -> str:
+        return str(self.raw.get("admin", {}).get("default_priority", "P1")).strip()
+
+    @property
+    def patrol_message(self) -> str:
+        return str(self.raw.get("patrol", {}).get("message", "巡检")).strip()
+
+    @property
+    def patrol_poll_interval(self) -> int:
+        return int(self.raw.get("patrol", {}).get("poll_interval", 10))
+
+    @property
+    def patrol_check_delay(self) -> int:
+        return int(self.raw.get("patrol", {}).get("check_delay", 15))
+
+    @property
+    def patrol_max_retry(self) -> int:
+        return int(self.raw.get("patrol", {}).get("max_retry", 3))
+
+    @property
+    def patrol_confidence(self) -> float:
+        return float(self.raw.get("patrol", {}).get("confidence", 0.7))
+
+    @property
+    def all_worker_chats(self) -> list[str]:
+        return list(self.raw.get("patrol", {}).get("all_worker_chats", []))
+
+    @property
+    def role_to_chat(self) -> dict[str, str]:
+        return dict(self.raw.get("patrol", {}).get("role_to_chat", {}))
+
+    @property
+    def roles(self) -> dict[str, dict]:
+        raw_roles = self.raw.get("roles", {})
+        return {str(key).strip(): dict(value) for key, value in raw_roles.items()}
+
+    @property
+    def fixed_roles(self) -> list[str]:
+        raw_roles = self.raw.get("ai_team", {}).get("fixed_roles", DEFAULT_FIXED_ROLES)
+        items = [str(item).strip() for item in raw_roles if str(item).strip()]
+        return items or DEFAULT_FIXED_ROLES[:]
+
+    @property
+    def cursor_only(self) -> bool:
+        return self.raw.get("ai_team", {}).get("cursor_only", True) is not False
+
+    @property
+    def idle_seconds(self) -> int:
+        return int(self.raw.get("runtime", {}).get("idle_seconds", 180))
+
+    @property
+    def stale_task_seconds(self) -> int:
+        return int(self.raw.get("runtime", {}).get("stale_task_seconds", 900))
+
+    @property
+    def sendable_roles(self) -> list[dict[str, str]]:
+        items: list[dict[str, str]] = []
+        for role_name in self.fixed_roles:
+            meta = self.roles.get(role_name, {})
+            if role_name == self.admin_sender:
+                continue
+            display_names = list(meta.get("display_names", []))
+            label = display_names[0] if display_names else role_name
+            items.append({"role": role_name, "label": label})
+        if not any(item["role"] == self.admin_target for item in items):
+            items.insert(0, {"role": self.admin_target, "label": self.admin_target})
+        return items
+
+    def validate_device(self) -> None:
+        missing = []
+        if not self.device_id:
+            missing.append("device.device_id")
+        if not self.device_name:
+            missing.append("device.device_name")
+        if not self.owner_role:
+            missing.append("device.owner_role")
+        if not self.machine_code:
+            missing.append("device.machine_code")
+        if missing:
+            raise ValueError(f"配置缺少设备身份字段: {', '.join(missing)}")
+
+    def validate_roles(self) -> None:
+        missing = [role for role in self.fixed_roles if role not in self.roles]
+        if missing:
+            raise ValueError(f"配置缺少固定角色定义: {', '.join(missing)}")
+
+    def ensure_runtime_dirs(self) -> None:
+        self.tasks_dir.mkdir(parents=True, exist_ok=True)
+        self.reports_dir.mkdir(parents=True, exist_ok=True)
+        self.issues_dir.mkdir(parents=True, exist_ok=True)
+        self.runtime_dir.mkdir(parents=True, exist_ok=True)
+        self.status_dir.mkdir(parents=True, exist_ok=True)
+        self.task_details_dir.mkdir(parents=True, exist_ok=True)
+
+    def save(self, raw: dict[str, Any] | None = None) -> None:
+        self.path.write_text(json.dumps(raw or self.raw, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    def update_bind(self, **kwargs: Any) -> None:
+        bind = dict(self.raw.get("bind", {}))
+        bind.update(kwargs)
+        self.raw["bind"] = bind
+        self.save()
+
+
+def load_config(path: str | Path) -> PatrolConfig:
+    cfg_path = Path(path).expanduser().resolve()
+    raw = json.loads(cfg_path.read_text(encoding="utf-8-sig"))
+    return PatrolConfig(raw=raw, path=cfg_path)