From 0d6eb1a4bb1a370ebdf6435ae433b211b4762002 Mon Sep 17 00:00:00 2001
From: AirPlan Team <noreply@airlongdian.fun>
Date: Wed, 10 Jun 2026 16:26:00 +0800
Subject: [PATCH] Add design document

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 airplanV2-Qwen3.7-Max设计.md | 1477 ++++++++++++++++++++++++++++++++++
 1 file changed, 1477 insertions(+)
 create mode 100644 airplanV2-Qwen3.7-Max设计.md

diff --git a/airplanV2-Qwen3.7-Max设计.md b/airplanV2-Qwen3.7-Max设计.md
new file mode 100644
index 0000000..1150def
--- /dev/null
+++ b/airplanV2-Qwen3.7-Max设计.md
@@ -0,0 +1,1477 @@
+# AirPlan V2 设计文档
+
+> **版本**: Draft 0.1
+> **日期**: 2026-06-09
+> **基线**: AirPlan V1 (air-suite-20260518, air_runtime ~4,500 行, 8 插件)
+> **状态**: 待评审
+
+---
+
+## 0. 文档目的
+
+本文档记录 AirPlan V1 在真实工程项目（DecodePlayer 系列, AirCoding V1.0.0 Alpha）中暴露的系统性缺陷，并定义 V2 的架构改进方向、新增组件设计和分阶段实施计划。
+
+V2 的核心命题：**V1 证明了制品驱动 + 上下文隔离 + 波次并行的架构方向成立；V2 要解决可靠性、可观测性和规模化问题。**
+
+---
+
+## 1. V1 问题诊断
+
+### 1.1 缺陷分级
+
+#### P0 — 已造成实际损失
+
+| ID | 缺陷 | 位置 | 影响 | 根因 |
+|----|------|------|------|------|
+| P0-1 | AirXDB 假阳性阻塞 | `airxdb_runtime.py` `ensure_xdb_sessions_for_result()` | 11+ 任务触发虚假修复循环，每次需人工覆盖 | 证据门控无任务类型感知 |
+| P0-2 | 部署验证缺口 | `contracts.py` `validate_for_finalize()` | T-028b 发现 4 个 "done" 任务未实际部署，延迟发布一整天 | 验证只检查结构完整性，不检查部署一致性 |
+| P0-3 | 非原子写入 | 全部 `_json_dump` (5 份) | 进程崩溃时 state.json 截断，下次加载 JSONDecodeError | `path.write_text()` 直接覆盖，无 tempfile + rename |
+| P0-4 | 零并发控制 | 整个 `air_runtime/` | 两个 Worker 同时完成时 todo.md 读-改-写竞态 | 无任何锁、互斥量或原子操作 |
+| P0-5 | AirArc 被 plan 模式劫持 | AirArc SKILL.md / 命令文件 | 架构器频繁被 Agent 内置 plan mode 接管，偏离架构规划职责 | 缺乏 plan mode 阻断机制，SKILL.md 指令不够强硬 |
+| P0-6 | AirEng 停下来问而不自主决策 | AirEng SKILL.md / 命令文件 | 调度器用英文反复询问用户确认，而非中文自主推进开发进度 | SKILL.md 未强制"以推进为目标自行决策"，语言未锁定中文 |
+| P0-7 | AirEng 无子线程状态轮询 | `engine.py` `monitor_engine()` | 子线程卡死后调度器无限等待，必须用户手动发现并告知 | 轮询逻辑依赖 Agent 自觉执行，无硬编码的定时轮询循环 |
+| P0-8 | AirDo 不调用 AirDbg | AirDo SKILL.md / `worker.py` `finish_worker()` | 执行器遇到问题或验收时几乎不触发调试，直接报 blocked 或 false-done | 自动路由为建议性而非强制，Worker 倾向于跳过调试直接返回 |
+| P0-9 | 安装器脚本路径错误 | 安装脚本 / 插件注册逻辑 | 安装后插件无法识别，AI 修复后可识别但脚本执行失败，路径不正确 | 安装器未正确解析插件脚本的绝对路径，注册的命令路径与实际文件位置不匹配 |
+| P0-10 | AirEng 偏离调度亲自写代码 | AirEng SKILL.md / 命令文件 | 调度引擎频繁偏离调度职责自己编写代码，破坏隔离架构。极端情况（子代理循环阻塞需接手合并）允许少量修改，但日常调度中不应发生 | SKILL.md 未明确区分"仅调度"与"极端接管"的边界，无工具限制约束 |
+
+#### P1 — 限制可靠性与可维护性
+
+| ID | 缺陷 | 位置 | 影响 |
+|----|------|------|------|
+| P1-1 | 硬编码开发者路径 | `debug_runtime.py:130`, `airxdb_runtime.py:156` | `C:\Users\20392\...` 在其他机器静默失败 |
+| P1-2 | `_json_dump`/`_json_load` 5 份重复 | engine, worker, airxdb, debug, repair | 修一处漏四处 |
+| P1-3 | `_ordered_unique` 4 份重复 | airxdb, debug, repair, contracts | 同上 |
+| P1-4 | policy normalization 3 份重复 | airxdb, debug, repair | 同上 |
+| P1-5 | merge-into-state 3 份重复 | airxdb, debug, repair | 同上 |
+| P1-6 | marker block upsert 2 份（接口不同） | doc_sync, project_bootstrap | 同上 |
+| P1-7 | `_session_stamp` 格式不一致 | airxdb, debug vs engine | 时间戳格式在不同模块产生不同文件名 |
+| P1-8 | todo.md 列索引硬编码 | `doc_sync.py:154-156` | `cells[1]`=status, `cells[6]`=validation, `cells[7]`=adr — 表头变化时全部失效 |
+| P1-9 | 并发度上限硬编码为 3 | `engine.py:527` | 无法根据项目规模调整 |
+| P1-10 | 子进程无超时 | airxdb, debug runtime | 挂死时阻塞整个引擎 |
+| P1-11 | task_id 路径注入 | `worker.py:59` | 无 `../` 遍历校验 |
+| P1-12 | 标记注入风险 | `doc_sync.py` `_replace_marker_block()` | marker 字段含 `-->` 时可注入内容 |
+| P1-13 | 静默吞异常 | session 文件损坏时 `except` 后 `continue` | 损坏文件不可见，无日志 |
+| P1-14 | Arc 重规划后 Eng 无法衔接 | `engine.py` 计划解析 + `todo.md` 同步 | 中途变更需求后 Arc 重新生成规划，Eng 需多轮 AI 迭代才能恢复调度 | 调度引擎基于静态 todo.md 表格，无法增量吸收 Arc 的动态重规划结果 |
+| P1-15 | 同文件无冲突任务被迫串行 | `review.py` 写集冲突检测 | 同文件不同区域（如 Qt 样式 vs 状态机）被判为冲突，被迫串行执行 | 冲突检测粒度为文件级而非区域级，无 worktree 隔离并行能力 |
+| P1-16 | AirArc 跳过需求探讨直接生成规划 | AirArc SKILL.md / 命令文件 | 用户刚说一两句就自顾自生成计划并要求执行，未与用户充分探讨需求和分析架构 | SKILL.md 未强制"先探讨后规划"流程，缺少用户确认架构的门控 |
+| P1-17 | AirDbg 未取证就盲改代码 | AirDbg SKILL.md / `debug_runtime.py` | 调试器不进行任何取证（抓包/截图/代码分析）就猜测原因并修改代码，引入新问题且污染代码库 | 7 步工作流为建议性不强制，无"先读后写"硬性门控——未执行任何取证行为就不允许修改代码 |
+| P1-18 | 项目缺乏标准化日志体系 | 项目引导 / AirArc 规划 | 生成的代码无统一日志输出，debug/release 无法切换，问题排查困难 | 无项目级日志标准要求，AirArc 规划时未强制 spdlog 集成，AirRvr 审查时未检查日志完备性 |
+
+#### P2 — 限制规模化
+
+| ID | 缺陷 | 位置 | 影响 |
+|----|------|------|------|
+| P2-1 | 冲突检测 O(n²) | `review.py` `combinations(active_tasks, 2)` | 100 任务时 ~495,000 次路径比较 |
+| P2-2 | state.json 无界增长 | `engine.py` | `mergedResults` 等列表永不截断 |
+| P2-3 | todo.md 每次操作全量重解析 | engine 多处调用 `parse_tasks()` | 大 todo 表时性能退化 |
+| P2-4 | 零测试覆盖 | 整个 `air_runtime/` | 任何重构都有回归风险 |
+
+#### P3 — 限制用户体验
+
+| ID | 缺陷 | 位置 | 影响 |
+|----|------|------|------|
+| P3-1 | AGENTS.md 膨胀 | AirEng sync 追加无去重 | 同一任务记录重复 2-3 次 |
+| P3-2 | 写集刚性导致级联任务链 | 写集边界设计 | T-028 衍生 fix-001~005 + T-028b + T-028c |
+| P3-3 | 并行 Worker 抢占共享硬件 | 无硬件资源感知 | kmsgrab 锁死、负载 7.59 自发重启 |
+| P3-4 | 环境特定修复不可持久化 | 部署自动化不完整 | MonitorServiceD、cgroup v1 每次重启需手动修复 |
+| P3-5 | 跨项目知识不迁移 | 无模板继承机制 | 每个项目从零积累运维经验 |
+
+### 1.2 插件级差距
+
+| 插件 | V1 差距 | 影响 |
+|------|---------|------|
+| **AirContext** | 压缩质量无监控；Token 估算 `char_div_3.5` 粗糙；续传 prompt 硬编码中文；锁文件无陈旧检测 | 坏摘要静默损坏上下文 |
+| **AirDbg** | 7 步工作流纯建议性不强制；无不可复现 bug 分支；无回滚能力 | 调试质量依赖模型自觉 |
+| **AirXDB** | 无 headless CI；无 DRM/KMS 原生截图；无截图 diff；远程探测不含 ffmpeg | 生产渲染路径无法自动验证 |
+| **AirNDB** | 无 TLS 解密；大 pcap `tail(8000)` 截断；无 pcapng 支持 | 大规模抓包分析能力不足 |
+| **AirSDB** | 仅 C/C++；无 diff 模式；无 compile_commands.json 生成 | 多语言项目零覆盖 |
+| **AirArc** | 无规划质量验证；无增量重规划；无执行→规划反馈 | scope 变更必须全量重新生成 |
+| **AirEng** | 无级联故障保护；无资源耗尽监控；5 分钟固定轮询；无 Worker 总时间上限 | 大规模调度时稳定性不足 |
+
+### 1.3 真实项目痛点汇总
+
+| 痛点 | 频次 | 根因缺陷 |
+|------|------|---------|
+| AirXDB 假阳性阻塞 | 11+ 任务 | P0-1 |
+| 完成但未部署 | 1 次关键事故 | P0-2 |
+| 写集级联任务链 | 5+ 条链 | P3-2 |
+| 并行 Worker 抢占硬件 | 3+ 次 | P3-3 |
+| 空壳修复循环 | 11+ 次 | P0-1 + P3-4 |
+| AGENTS.md 膨胀 | 持续累积 | P3-1 |
+| 环境修复不可持久 | 每次重启 | P3-4 |
+| AirArc 被 plan 模式劫持 | 频繁 | P0-5 |
+| AirEng 反复询问不自主推进 | 每次调度 | P0-6 |
+| AirEng 遗忘轮询导致无限等待 | 频繁 | P0-7 |
+| AirDo 跳过 AirDbg 直接返回 | 频繁 | P0-8 |
+| 安装后插件无法识别或脚本路径错误 | 用户普遍反馈 | P0-9 |
+| 需求变更后调度需多轮迭代恢复 | 每次变更 | P1-14 |
+| 同文件无冲突任务被迫串行 | 频繁 | P1-15 |
+| 实现偏离设计无对照机制 | 持续累积 | AirRvr 设计缺口 |
+| AirArc 跳过需求探讨直接生成规划 | 每次启动 | P1-16 |
+| AirDbg 不取证就猜测修复污染代码 | 频繁 | P1-17 |
+| AirEng 偏离调度亲自写代码 | 频繁 | P0-10 |
+| 项目代码缺乏标准化日志体系 | 所有项目 | P1-18 |
+
+---
+
+## 2. V2 设计目标
+
+### 2.1 核心目标
+
+1. **可靠性**：状态写入不丢失，并发操作不竞态，崩溃后可自愈
+2. **可观测性**：所有引擎操作可追溯，指标可导出，异常主动通知
+3. **智能化**：证据门控感知任务类型，轮询频率自适应，修复模式可学习
+4. **规模化**：支持 100+ 任务、5+ 并行 Worker、多项目知识迁移
+
+### 2.2 不变量
+
+V2 必须保持 V1 的核心不变量：
+
+| 不变量 | V1 定义 | V2 保持方式 |
+|--------|---------|------------|
+| INV-1 制品驱动通信 | 插件间通过 AirPlan/ 文件通信 | 保持，增加事件索引层 |
+| INV-2 上下文隔离 | Worker `fork_context=false` | 保持，增加选择性上下文继承 |
+| INV-3 架构同步强制 | 不更新架构文档不能 DONE | 保持，增加增量同步 |
+| INV-4 证据先于修复 | 截图/抓包/静态分析前置 | 保持，增加任务类型感知 |
+| INV-5 闭环自动修复 | 执行→失败→调试→修复→重执行 | 保持，增加修复模式学习 |
+
+---
+
+## 3. V2 架构改进
+
+### 3.1 基础设施层重构
+
+#### 3.1.1 `air_runtime.io` — 统一 I/O 模块
+
+消除 5 份 `_json_dump`/`_json_load` 重复，统一为原子写入：
+
+```python
+# air_runtime/io.py
+
+def atomic_json_write(path: Path, data: dict) -> None:
+    """POSIX 原子写入：tempfile + os.replace()"""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    try:
+        os.write(fd, json.dumps(data, indent=2, ensure_ascii=False).encode("utf-8"))
+        os.close(fd)
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+
+def safe_json_load(path: Path) -> dict | None:
+    """安全加载：处理损坏文件，自动从 .bak 恢复"""
+    try:
+        return json.loads(path.read_text("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        bak = path.with_suffix(path.suffix + ".bak")
+        if bak.exists():
+            logging.warning("corrupt %s, restoring from %s", path, bak)
+            return json.loads(bak.read_text("utf-8"))
+        logging.error("corrupt %s with no backup", path)
+        return None
+```
+
+每次写入前自动备份旧文件为 `.bak`（单级轮转），保证至少有一次完整的历史版本。
+
+#### 3.1.2 `air_runtime.lock` — 文件级并发控制
+
+```python
+# air_runtime/lock.py
+
+class FileLock:
+    """基于 fcntl.flock 的进程级文件锁"""
+
+    def __init__(self, path: Path, timeout: float = 10.0):
+        self._path = path.with_suffix(path.suffix + ".lock")
+        self._timeout = timeout
+        self._fd = None
+
+    def __enter__(self):
+        self._fd = os.open(self._path, os.O_CREAT | os.O_RDWR)
+        deadline = time.monotonic() + self._timeout
+        while True:
+            try:
+                fcntl.flock(self._fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                return self
+            except OSError:
+                if time.monotonic() >= deadline:
+                    raise TimeoutError(f"lock timeout: {self._path}")
+                time.sleep(0.1)
+
+    def __exit__(self, *exc):
+        fcntl.flock(self._fd, fcntl.LOCK_UN)
+        os.close(self._fd)
+```
+
+所有 `state.json` 和 `todo.md` 的读-改-写操作必须持有对应锁。
+
+#### 3.1.3 `air_runtime.utils` — 消除代码重复
+
+```python
+# air_runtime/utils.py
+
+def ordered_unique(items: list) -> list:
+    """保序去重"""
+    seen = set()
+    result = []
+    for item in items:
+        key = item if isinstance(item, str) else item.get("id", str(item))
+        if key not in seen:
+            seen.add(key)
+            result.append(item)
+    return result
+
+def session_stamp() -> str:
+    """统一的文件系统安全时间戳"""
+    return datetime.now(timezone.utc).isoformat().replace(":", "-").replace(".", "-").replace("+", "-")
+
+def normalize_policy(defaults: dict, overrides: dict | None) -> dict:
+    """通用的策略合并"""
+    merged = {**defaults}
+    if overrides:
+        for k, v in overrides.items():
+            if k in merged:
+                expected_type = type(defaults[k])
+                merged[k] = expected_type(v) if not isinstance(v, expected_type) else v
+    return merged
+
+def sanitize_task_id(task_id: str) -> str:
+    """防止路径注入"""
+    if not re.fullmatch(r"[A-Za-z0-9_\-]+", task_id):
+        raise ValueError(f"invalid task_id: {task_id!r}")
+    return task_id
+
+def sanitize_marker(marker: str) -> str:
+    """防止 HTML 注释注入"""
+    if "-->" in marker or "<!--" in marker:
+        raise ValueError(f"marker contains comment delimiters: {marker!r}")
+    return marker
+```
+
+### 3.2 引擎层改进
+
+#### 3.2.1 任务类型感知的证据门控
+
+```python
+# 替代 airxdb_runtime.py 中的无差别触发
+
+class EvidenceGatePolicy:
+    """基于任务特征的差异化证据要求"""
+
+    GUI_INDICATORS = {"gui", "ui", "render", "layout", "dialog", "osd",
+                      "overlay", "visual", "screenshot", "display",
+                      "widget", "pane", "toolbar", "settings_dialog"}
+
+    NETWORK_INDICATORS = {"network", "rtsp", "http", "tcp", "udp", "tls",
+                          "dns", "proxy", "socket", "stream", "port"}
+
+    def classify(self, task: TaskRecord) -> EvidenceClass:
+        text = f"{task.task} {task.files_dirs} {task.done_when}".lower()
+        has_gui = any(kw in text for kw in self.GUI_INDICATORS)
+        has_net = any(kw in text for kw in self.NETWORK_INDICATORS)
+
+        if has_gui:
+            return EvidenceClass.GUI_REQUIRED
+        elif has_net:
+            return EvidenceClass.NETWORK_REQUIRED
+        else:
+            return EvidenceClass.CODE_ONLY  # 不需要截图/抓包
+```
+
+#### 3.2.2 部署验证强制
+
+```python
+# contracts.py 扩展
+
+class WorkerResult:
+    def validate_for_finalize(self, brief: dict) -> None:
+        # ... 现有验证 ...
+
+        # V2 新增: 部署一致性
+        if brief.get("deploy_required"):
+            deploy_validations = [
+                v for v in self.validations
+                if v.kind in ("remote-deploy-verify", "remote-binary-md5")
+            ]
+            if not deploy_validations:
+                raise ValidationError(
+                    "deploy_required but no deploy verification in validations"
+                )
+            if any(v.status != "passed" for v in deploy_validations):
+                raise ValidationError(
+                    "deploy verification did not pass"
+                )
+```
+
+#### 3.2.3 自适应轮询
+
+```python
+# engine.py 监控循环改进
+
+class AdaptivePoller:
+    """根据 Worker 状态动态调整轮询间隔"""
+
+    def __init__(self, min_interval=30, max_interval=300):
+        self.min_interval = min_interval
+        self.max_interval = max_interval
+        self._worker_phases: dict[str, str] = {}
+
+    def interval_for(self, worker: dict) -> int:
+        age_seconds = (now() - worker["spawnedAt"]).total_seconds()
+
+        # 刚派发: 快速检测早期失败
+        if age_seconds < 120:
+            return self.min_interval
+
+        # Worker 报告接近完成
+        state = self._read_worker_state(worker)
+        if state and state.get("phase") in ("finalizing", "running-validations"):
+            return self.min_interval
+
+        # 稳定执行中
+        return self.max_interval
+```
+
+#### 3.2.4 Worker 超时与级联保护
+
+```python
+# engine.py 新增
+
+WORKER_MAX_WALL_TIME = 7200  # 2 小时硬上限, 可配置
+
+def _check_worker_timeout(self, worker: dict) -> bool:
+    age = (now() - worker["spawnedAt"]).total_seconds()
+    if age > WORKER_MAX_WALL_TIME:
+        self._record_intervention(
+            taskId=worker["taskId"],
+            reason="wall-time-exceeded",
+            action="terminate-and-block",
+        )
+        return True
+    return False
+
+def _check_resource_pressure(self) -> bool:
+    """系统资源压力检测"""
+    load = os.getloadavg()[0]
+    cpu_count = os.cpu_count() or 4
+    if load > cpu_count * 2:
+        logging.warning("system load %.1f > 2x cpu_count (%d), pausing dispatch", load, cpu_count)
+        return True
+    return False
+```
+
+#### 3.2.5 合并事务化
+
+V1 的 `merge_worker_result()` 执行 8+ 次文件写入，中间崩溃导致不一致。V2 引入事务语义：
+
+```python
+def merge_worker_result(self, project_root, result_path):
+    lock = FileLock(project_root / "AirPlan" / "state" / "aireng" / "state.json")
+    with lock:
+        # Phase 1: 验证
+        result = safe_json_load(result_path)
+        enforce_doc_sync_requirements(project_root, result)
+
+        # Phase 2: 归档（可重试）
+        archive_path = _archive_result(project_root, result)
+
+        # Phase 3: 应用文档更新（原子写入）
+        applied = apply_document_updates(project_root, result)
+
+        # Phase 4: 同步标记块（原子写入）
+        sync_paths = sync_engine_managed_docs(project_root, result, applied)
+
+        # Phase 5: 更新 todo（带锁）
+        todo_lock = FileLock(project_root / "AirPlan" / "todo.md")
+        with todo_lock:
+            update_todo_after_merge(project_root, result, applied, sync_paths)
+
+        # Phase 6: 更新引擎状态（原子写入）
+        _update_engine_state(project_root, result, archive_path)
+```
+
+#### 3.2.6 AirArc plan 模式阻断
+
+V1 中 AirArc 频繁被 Agent 内置 plan mode 劫持，导致架构器偏离规划职责去执行代码修改。V2 在 SKILL.md 和命令文件中增加硬性阻断：
+
+```markdown
+# AirArc SKILL.md V2 关键指令
+
+## 角色边界（不可违反）
+你是**纯规划器**。你的职责是分析任务依赖、写集冲突、产出调度计划。
+**禁止**：编写代码、修改源代码文件、执行构建命令、进入 plan mode。
+如果你发现自己正在写代码或修改文件，**立即停止**并返回规划职责。
+
+## plan mode 阻断
+当 Agent 框架尝试进入 plan mode 时，你必须拒绝：
+"我是 AirArc 架构规划器，不进入 plan mode。我的产出是 execution-plan.json，不是代码变更。"
+```
+
+技术层面，AirArc 命令文件中 `allowed_tools` 仅包含读取类工具（Read, Glob, Grep），不包含 Write/Edit/Bash：
+
+```json
+{
+  "allowed_tools": ["Read", "Glob", "Grep"],
+  "denied_tools": ["Write", "Edit", "Bash", "NotebookEdit"],
+  "deny_plan_mode": true
+}
+```
+
+#### 3.2.7 AirEng 自主决策与中文锁定
+
+V1 中 AirEng 反复用英文询问用户确认，中断调度流程。V2 在 SKILL.md 中强制自主决策和中文输出：
+
+```markdown
+# AirEng SKILL.md V2 关键指令
+
+## 语言锁定
+你**必须始终使用中文**与用户交流。所有状态报告、进度通知、问题描述均使用中文。
+
+## 自主决策原则
+你以**推进开发进度**为第一目标。遇到以下情况时自行决策，不要停下来问用户：
+- Worker 返回 blocked 但修复预算未耗尽 → 自行派发修复
+- Worker 停滞 → 自行执行停滞干预（重派发/标记 blocked）
+- 验证失败但非关键 → 记录问题并继续下一任务
+- 波次间衔接 → 自行启动下一波次
+
+## 仅在以下情况才询问用户：
+- 修复预算耗尽且任务仍 blocked
+- 发现需求歧义无法继续
+- 系统资源耗尽无法派发新 Worker
+- 用户显式暂停了调度
+```
+
+#### 3.2.8 AirEng 硬编码轮询循环
+
+V1 中轮询逻辑依赖 Agent "自觉"执行，实际经常遗忘导致无限等待。V2 将轮询指令硬编码到 SKILL.md 的强制循环中：
+
+```markdown
+# AirEng SKILL.md V2 轮询指令
+
+## 强制轮询循环（不可跳过）
+进入调度状态后，你必须执行以下循环，**每 5 分钟**检查一次所有活跃 Worker：
+
+```
+while 存在活跃 Worker:
+  1. 遍历所有 dispatched Worker
+  2. 检查每个 Worker 的 state 文件 mtime
+  3. mtime > 5分钟未更新 → 标记 stalled → 执行停滞干预
+  4. state = done → 执行合并流程
+  5. state = blocked → 检查修复预算 → 派发修复或升级
+  6. 所有 Worker 处理完毕 → 派发下一波次
+  7. 等待 5 分钟后重复
+```
+
+**绝对不允许**：
+- 派发 Worker 后不做轮询就等待
+- 仅检查一次就声称"等待 Worker 完成"
+- 轮询间隔超过 10 分钟
+```
+
+技术补充：引擎 `monitor_engine()` 增加 wall-clock 超时检测，Worker 超过 `WORKER_MAX_WALL_TIME` 自动 terminate。
+
+#### 3.2.8b AirEng 调度职责边界
+
+V1 中 AirEng 频繁偏离调度职责自己编写代码，破坏上下文隔离架构。V2 明确区分"仅调度"与"极端接管"的边界：
+
+```markdown
+# AirEng SKILL.md V2 职责边界指令
+
+## 核心职责：调度，不是编码
+你是**调度引擎**，不是执行器。你的职责是：
+- 解析执行计划，派发 AirDo Worker
+- 轮询 Worker 状态，处理停滞和合并
+- 管理波次衔接和修复预算
+
+**默认禁止**：编写源代码、修改项目文件。这些是 AirDo Worker 的职责。
+
+## 极端接管（唯一例外）
+仅在以下条件**全部满足**时，你才可以少量修改代码：
+1. 子代理陷入循环阻塞，修复预算已耗尽
+2. 问题已通过 AirDbg 定位到明确的根因
+3. 修复范围极小（≤5 行改动，如配置修正、路径修复）
+4. 继续等待 Worker 重派发已无意义（至少尝试过 2 次）
+
+进入极端接管前，必须在引擎日志中记录：
+"EXTREME_TAKEOVER: taskId=X, reason=Y, changes=Z"
+
+## 违规判定
+如果你在以下场景编写代码，视为违规：
+- 正常调度流程中（Worker 可用且未阻塞）
+- 修复预算未耗尽时
+- 改动超过 5 行
+- 未经 AirDbg 定位就猜测修复
+```
+
+#### 3.2.9 AirDo 强制 AirDbg 路由
+
+V1 中 AirDo 遇到问题时倾向直接报 blocked 或 false-done，跳过 AirDbg 调试。V2 将 AirDbg 调用从"建议"升级为"强制"：
+
+```python
+# worker.py finish_worker() V2 改进
+
+def finish_worker(result: WorkerResult, brief: dict) -> RoutingDecision:
+    if result.status == "done":
+        # done 也必须有实质验证，否则路由到 AirDbg
+        if not result.validations and not result.filesChanged:
+            return RoutingDecision(
+                target="airdbg",
+                reason="done without evidence — mandatory debug review",
+                forced=True,
+            )
+        return RoutingDecision(target="merge")
+
+    if result.status in ("blocked", "failed"):
+        # blocked/failed 必须先经 AirDbg，不允许直接返回
+        return RoutingDecision(
+            target="airdbg",
+            reason=f"status={result.status} — AirDbg mandatory before return",
+            forced=True,
+        )
+```
+
+SKILL.md 配合强制指令：
+
+```markdown
+## AirDbg 调用强制规则
+- 任务状态为 blocked 或 failed 时，**必须**先调用 AirDbg 进行调试
+- 任务状态为 done 但无验证证据时，**必须**调用 AirDbg 验证
+- **禁止**直接返回 blocked 而不经过调试
+- **禁止**在没有截图/测试结果的情况下声称 GUI 任务完成
+```
+
+#### 3.2.10 安装器路径修正
+
+V1 安装器存在两个问题：(1) 安装后插件命令不被识别；(2) AI 修复注册后脚本执行路径不正确。
+
+根因：安装器使用相对路径或硬编码路径注册插件命令，未根据实际安装位置动态生成绝对路径。
+
+V2 修正：
+
+```python
+# installer.py V2 改进
+
+def resolve_plugin_paths(install_dir: Path) -> dict[str, str]:
+    """根据实际安装目录动态生成所有插件脚本的绝对路径"""
+    scripts_dir = install_dir / "scripts"
+    return {
+        plugin_name: str(scripts_dir / f"{plugin_name}.py")
+        for plugin_name in PLUGIN_NAMES
+    }
+
+def register_plugin_commands(paths: dict[str, str]) -> None:
+    """注册时使用已解析的绝对路径，并验证文件存在"""
+    for name, path in paths.items():
+        if not Path(path).exists():
+            raise InstallError(f"plugin script not found: {path}")
+        register_command(name, command=path)
+
+def post_install_verify() -> VerifyResult:
+    """安装后自动验证：命令可识别 + 脚本可执行"""
+    errors = []
+    for name in PLUGIN_NAMES:
+        if not is_command_registered(name):
+            errors.append(f"{name}: command not registered")
+        elif not can_execute(name):
+            errors.append(f"{name}: script not executable")
+    return VerifyResult(ok=not errors, errors=errors)
+```
+
+验证标准：安装完成后 `post_install_verify()` 必须全部通过，否则安装器自动报错并输出修复建议，而非让用户自行发现。
+
+#### 3.2.11 动态图调度（替代静态表格）
+
+V1 的 AirArc 产出静态 `todo.md` 表格，AirEng 基于该表格调度。当需求变更时 Arc 重新生成表格，Eng 无法增量吸收差异，需多轮 AI 迭代才能恢复。
+
+V2 将调度结构从表格升级为**动态有向图 (DAG)**：
+
+```python
+# air_runtime/task_graph.py
+
+class TaskGraph:
+    """动态任务依赖图，支持增量更新"""
+
+    def __init__(self):
+        self.nodes: dict[str, TaskNode] = {}
+        self.edges: list[Edge] = []
+
+    def apply_delta(self, delta: PlanDelta) -> None:
+        """增量吸收 Arc 的重规划结果，无需全量重建"""
+        for removed in delta.removed_tasks:
+            self._remove_node(removed)
+        for added in delta.added_tasks:
+            self._add_node(added)
+        for modified in delta.modified_tasks:
+            self._update_node(modified)
+        for edge_change in delta.edge_changes:
+            self._update_edge(edge_change)
+
+    def ready_tasks(self) -> list[str]:
+        """返回当前入度为 0 且未调度的任务"""
+        return [n.id for n in self.nodes.values()
+                if n.in_degree == 0 and n.status == "TODO"]
+
+class PlanDelta:
+    """Arc 重规划产出的增量差异"""
+    removed_tasks: list[str]
+    added_tasks: list[TaskNode]
+    modified_tasks: list[TaskNode]
+    edge_changes: list[EdgeChange]
+```
+
+Arc 重规划时不再全量覆盖 `todo.md`，而是产出 `plan-delta.json`，Eng 调用 `apply_delta()` 增量更新图结构，保持已调度任务不受影响。
+
+#### 3.2.12 Worktree 隔离并行（同文件不同区域）
+
+V1 的冲突检测粒度为文件级。实际场景中，同一文件的不同区域可能互不影响（如 Qt 组件样式 vs 状态机逻辑），可以安全并行。
+
+V2 引入**区域级冲突检测 + git worktree 隔离**：
+
+```python
+# review.py V2 改进
+
+class RegionConflictDetector:
+    """区域级写集冲突检测"""
+
+    def detect(self, task_a: TaskNode, task_b: TaskNode) -> ConflictLevel:
+        file_overlap = set(task_a.write_set) & set(task_b.write_set)
+        if not file_overlap:
+            return ConflictLevel.NONE
+
+        region_overlap = self._check_region_overlap(task_a, task_b, file_overlap)
+        if region_overlap:
+            return ConflictLevel.HARD  # 同区域，必须串行
+        else:
+            return ConflictLevel.SOFT  # 同文件不同区域，可 worktree 隔离
+
+class WorktreeIsolation:
+    """为 SOFT 冲突任务创建 worktree 隔离，完成后合并"""
+
+    def create_worker_worktree(self, task_id: str, base_branch: str) -> Path:
+        wt_path = Path(f".git/worktrees/air-{task_id}")
+        subprocess.run(["git", "worktree", "add", str(wt_path), base_branch],
+                       check=True, capture_output=True)
+        return wt_path
+
+    def merge_back(self, task_id: str, wt_path: Path) -> MergeResult:
+        """worktree 完成后合并回主分支"""
+        subprocess.run(["git", "merge", f"air-{task_id}"], check=True)
+        subprocess.run(["git", "worktree", "remove", str(wt_path)],
+                       check=True, capture_output=True)
+```
+
+调度策略：`NONE` 直接并行，`SOFT` 使用 worktree 隔离并行，`HARD` 强制串行。合并冲突时自动升级到 AirDbg。
+
+#### 3.2.13 AirArc 需求探讨门控
+
+V1 中 AirArc 在用户仅说一两句时就立即生成执行计划，未与用户充分探讨需求和分析架构。V2 强制"先探讨、后确认、再规划"的三阶段流程：
+
+```markdown
+# AirArc SKILL.md V2 流程指令
+
+## 三阶段流程（不可跳过）
+
+### 阶段一：需求探讨
+- 与用户反复讨论需求细节、边界条件、隐含约束
+- 主动提问澄清模糊点，不要假设用户意图
+- 分析现有代码库的结构、技术栈、约束条件
+- 提出多种架构方案及其优劣势对比
+- **此阶段禁止生成 execution-plan.json**
+
+### 阶段二：架构确认
+- 向用户呈现推荐的架构方案（模块划分、依赖关系、技术选型）
+- 明确等待用户确认："请确认此架构方案是否符合预期，确认后我将生成执行规划"
+- 用户有异议时回到阶段一修订
+- **此阶段禁止生成 execution-plan.json**
+
+### 阶段三：生成规划
+- 仅在用户明确确认架构无误后，才生成 execution-plan.json
+- 规划产出必须严格对应用户确认的架构方案
+```
+
+技术门控：AirArc 运行时增加 `phase` 状态追踪，`execution-plan.json` 仅在 `phase == "confirmed"` 时允许写入：
+
+```python
+class ArcPhaseGate:
+    PHASES = ["discussing", "proposing", "confirmed"]
+
+    def can_write_plan(self) -> bool:
+        return self.current_phase == "confirmed"
+
+    def confirm_architecture(self, user_confirmation: str) -> None:
+        if "确认" in user_confirmation or "可以" in user_confirmation:
+            self.current_phase = "confirmed"
+```
+
+#### 3.2.14 项目级 spdlog 日志标准
+
+V1 生成的代码缺乏统一日志体系，debug/release 无法切换，问题排查困难。V2 强制所有项目集成 spdlog 日志库，支持 debug/release 级别切换。
+
+**AirArc 规划阶段强制要求**：
+
+```markdown
+# AirArc SKILL.md V2 日志标准指令
+
+## 项目日志标准（所有 C++ 项目强制）
+- 必须使用 spdlog 作为日志库
+- 如果项目未集成 spdlog，首个任务必须为"集成 spdlog 到项目"
+- 所有生成的代码必须使用 spdlog 输出日志，禁止 std::cout/qDebug 等
+- 必须支持 debug/release 编译开关切换日志级别
+- 关键路径（初始化、网络、文件 I/O、错误）必须有日志输出
+```
+
+**AirRvr 审查阶段检查项**：
+
+```python
+# AirRvr 审查清单扩展
+
+LOGGING_CHECKS = [
+    "spdlog 是否已集成到项目依赖",
+    "代码中是否存在 std::cout / qDebug / printf 等非标准日志",
+    "是否有 CMAKE_BUILD_TYPE 或等效的 debug/release 编译开关",
+    "关键路径（初始化、网络、文件 I/O、错误处理）是否有日志输出",
+    "日志格式是否统一（时间戳 + 级别 + 模块 + 消息）",
+]
+```
+
+**CMake 集成模板**：
+
+```cmake
+# 自动检测并集成 spdlog
+find_package(spdlog QUIET)
+if(NOT spdlog_FOUND)
+    include(FetchContent)
+    FetchContent_Declare(spdlog
+        GIT_REPOSITORY https://github.com/gabime/spdlog.git
+        GIT_TAG v1.14.1)
+    FetchContent_MakeAvailable(spdlog)
+endif()
+
+# debug/release 日志级别切换
+if(CMAKE_BUILD_TYPE STREQUAL "Debug")
+    target_compile_definitions(${PROJECT_NAME} PRIVATE SPDLOG_ACTIVE_LEVEL=SPDLOG_LEVEL_TRACE)
+else()
+    target_compile_definitions(${PROJECT_NAME} PRIVATE SPDLOG_ACTIVE_LEVEL=SPDLOG_LEVEL_INFO)
+endif()
+```
+
+### 3.3 AirContext V2 改进
+
+#### 3.3.1 压缩质量校验
+
+```python
+# compactor.py 新增
+
+class CompressionValidator:
+    """验证压缩摘要保留了关键信息"""
+
+    MUST_PRESERVE_PATTERNS = [
+        r"[A-Za-z0-9_\-/]+\.(py|ts|js|cpp|h|md|json|yaml)",  # 文件路径
+        r"ADR-\d{4}",                                          # ADR 引用
+        r"TODO|FIXME|HACK",                                    # 未完成项
+        r"INV-\d+",                                            # 不变量引用
+    ]
+
+    def validate(self, original_text: str, summary: str) -> ValidationResult:
+        missing = []
+        for pattern in self.MUST_PRESERVE_PATTERNS:
+            original_matches = set(re.findall(pattern, original_text))
+            summary_matches = set(re.findall(pattern, summary))
+            lost = original_matches - summary_matches
+            if len(lost) > len(original_matches) * 0.3:  # 丢失 >30%
+                missing.append({"pattern": pattern, "lost": list(lost)})
+
+        if missing:
+            return ValidationResult(ok=False, missing=missing)
+        return ValidationResult(ok=True, missing=[])
+```
+
+如果校验失败，重试一次压缩（换 prompt 或换模型），仍失败则放弃压缩（保留原始上下文）并通知用户。
+
+#### 3.3.2 Token 估算改进
+
+```python
+# token_estimator.py 改进
+
+class AdaptiveTokenEstimator:
+    """按内容类型分比率"""
+
+    RATIOS = {
+        "chinese": 1.5,    # 中文字符 → token
+        "english": 4.0,    # 英文单词字符 → token
+        "code": 3.0,       # 代码字符 → token
+        "markup": 5.0,     # Markdown/HTML 标记 → token
+    }
+
+    def estimate(self, text: str) -> int:
+        chinese = len(re.findall(r"[\u4e00-\u9fff]", text))
+        code = len(re.findall(r"[{}()\[\];=<>]", text))
+        markup = len(re.findall(r"[#*\-`|]", text))
+        english = len(text) - chinese - code - markup
+
+        tokens = (
+            chinese / self.RATIOS["chinese"]
+            + code / self.RATIOS["code"]
+            + markup / self.RATIOS["markup"]
+            + english / self.RATIOS["english"]
+        )
+        return int(tokens)
+```
+
+#### 3.3.3 陈旧锁检测
+
+```python
+def acquire_compactor_lock(lock_path: Path) -> bool:
+    try:
+        fd = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        os.write(fd, str(os.getpid()).encode())
+        os.close(fd)
+        return True
+    except FileExistsError:
+        # 检查持有锁的进程是否存活
+        try:
+            pid = int(lock_path.read_text().strip())
+            os.kill(pid, 0)  # 不发信号，只检查进程存在
+            return False  # 进程存活，锁有效
+        except (ValueError, ProcessLookupError, PermissionError):
+            # 进程不存在或无法访问 → 陈旧锁，清理
+            logging.warning("stale lock detected (pid=%s), removing", pid)
+            lock_path.unlink(missing_ok=True)
+            return acquire_compactor_lock(lock_path)  # 重试
+```
+
+### 3.4 AirSDB V2：多语言静态分析
+
+```python
+# airsdb 架构扩展
+
+class StaticAnalyzerBackend(Protocol):
+    """静态分析后端协议（类似 AirContext 的 CompressionBackend）"""
+
+    name: str
+
+    def detect(self) -> bool:
+        """检测分析器是否可用"""
+
+    def analyze(self, source_paths: list[str], compile_db: Path | None) -> AnalysisResult:
+        """执行分析"""
+
+    def parse_report(self, report_path: Path) -> list[Finding]:
+        """解析报告为统一格式"""
+
+
+class CppcheckBackend(StaticAnalyzerBackend):
+    """现有 cppcheck 实现"""
+
+class ClangTidyBackend(StaticAnalyzerBackend):
+    """clang-tidy 集成"""
+
+class RustClippyBackend(StaticAnalyzerBackend):
+    """cargo clippy 集成"""
+
+class GoVetBackend(StaticAnalyzerBackend):
+    """go vet + staticcheck 集成"""
+
+class TypeScriptBackend(StaticAnalyzerBackend):
+    """tsc --noEmit 集成"""
+
+class PythonBackend(StaticAnalyzerBackend):
+    """mypy + ruff 集成"""
+```
+
+新增 **diff 模式**：比较两次扫描结果，高亮新增/消除的 finding。
+
+```python
+class AnalysisDiff:
+    def compute(self, baseline: list[Finding], current: list[Finding]) -> DiffReport:
+        baseline_keys = {(f.file, f.line, f.rule_id) for f in baseline}
+        current_keys = {(f.file, f.line, f.rule_id) for f in current}
+
+        return DiffReport(
+            new_findings=[f for f in current if (f.file, f.line, f.rule_id) not in baseline_keys],
+            resolved_findings=[f for f in baseline if (f.file, f.line, f.rule_id) not in current_keys],
+            unchanged_count=len(baseline_keys & current_keys),
+        )
+```
+
+### 3.5 AirDbg V2：工作流强制与模式学习
+
+#### 3.5.1 步骤追踪
+
+```python
+# airdbg_mode.py 新增
+
+class DebugWorkflowTracker:
+    """追踪调试工作流的当前步骤，阻止跳步"""
+
+    STEPS = [
+        "confirm_symptoms",
+        "load_context",
+        "reproduce",         # 可跳过（标记为 non-reproducible）
+        "locate_root_cause",
+        "fix",
+        "verify",
+        "close_out",
+    ]
+
+    def current_step(self, session_id: str) -> str:
+        state = self._load_session_state(session_id)
+        return state.get("currentStep", "confirm_symptoms")
+
+    def advance(self, session_id: str, evidence: dict) -> None:
+        """只有提供了当前步骤要求的证据才能推进"""
+        step = self.current_step(session_id)
+        if not self._validate_step_evidence(step, evidence):
+            raise WorkflowViolation(
+                f"step '{step}' requires {self._required_evidence(step)}"
+            )
+        self._set_step(session_id, self._next_step(step))
+
+    def skip_reproduce(self, session_id: str, reason: str) -> None:
+        """显式标记为不可复现，进入分析路径"""
+        self._set_step(session_id, "locate_root_cause")
+        self._record(session_id, "reproduce_skipped", reason)
+```
+
+#### 3.5.2 修复回滚
+
+```python
+def pre_fix_snapshot(project_root: Path, task_id: str) -> SnapshotRef:
+    """修复前自动创建 git commit 作为回滚点"""
+    ref = f"airdbg/prefix-{task_id}-{session_stamp()}"
+    subprocess.run(["git", "commit", "-am", f"AirDbg pre-fix snapshot: {task_id}",
+                     "--allow-empty"], check=True, capture_output=True)
+    subprocess.run(["git", "tag", ref], check=True, capture_output=True)
+    return SnapshotRef(ref=ref, timestamp=now_iso())
+```
+
+#### 3.5.3 先读后写门控
+
+V1 中 AirDbg 不进行任何取证就猜测原因并修改代码，引入新问题且污染代码库。V2 强制"先读后写"原则：必须至少执行一种取证行为后，才允许修改代码。
+
+```python
+# debug_runtime.py 新增
+
+class EvidenceFirstGate:
+    """取证门控：未执行任何取证行为前，禁止代码修改"""
+
+    EVIDENCE_TYPES = [
+        "screenshot",        # AirXDB 截图
+        "packet_capture",    # AirNDB 抓包
+        "static_analysis",   # AirSDB 静态分析
+        "log_analysis",      # 日志分析
+        "code_trace",        # 代码追踪（读取相关文件、调用链分析）
+        "reproduction",      # 复现步骤执行
+    ]
+
+    def __init__(self, session_id: str):
+        self._session_id = session_id
+        self._collected_evidence: list[str] = []
+
+    def record_evidence(self, evidence_type: str, detail: str) -> None:
+        self._collected_evidence.append(evidence_type)
+        self._log(f"evidence collected: {evidence_type} — {detail}")
+
+    def can_modify_code(self) -> bool:
+        return len(self._collected_evidence) > 0
+
+    def gate_check(self) -> None:
+        if not self.can_modify_code():
+            raise WorkflowViolation(
+                "未执行任何取证行为，禁止修改代码。"
+                "请先至少完成以下一项：截图、抓包、静态分析、日志分析、代码追踪、复现步骤。"
+            )
+```
+
+SKILL.md 配合指令：
+
+```markdown
+## 先读后写原则（不可违反）
+- 修改任何代码之前，必须至少完成一项取证行为
+- 取证行为包括但不限于：截图、抓包、静态分析、日志分析、代码追踪、复现步骤
+- 不要求取证覆盖完整（部分问题确实无法完全取证），但必须有至少一项取证作为依据
+- 取证结果必须记录到 debug-log.md 后方可开始修复
+- **禁止**：未做任何调查就直接修改代码
+```
+
+### 3.6 AirXDB V2：扩展截图能力
+
+#### 3.6.1 DRM/KMS 原生截图
+
+```python
+# airxdb_runtime.py 新增
+
+class KmsGrabCapture(CaptureBackend):
+    """Linux DRM/KMS scanout 截图（ffmpeg -f kmsgrab）"""
+
+    def detect(self) -> bool:
+        result = subprocess.run(["ffmpeg", "-devices"], capture_output=True, text=True, timeout=5)
+        return "kmsgrab" in result.stdout
+
+    def capture(self, output_path: Path, card: str = "/dev/dri/card0") -> CaptureResult:
+        cmd = [
+            "sudo", "ffmpeg", "-y", "-f", "kmsgrab", "-framerate", "1",
+            "-i", card, "-vframes", "1",
+            "-vf", "hwdownload,format=bgr0",
+            "-f", "image2", str(output_path),
+        ]
+        return self._run_with_timeout(cmd, timeout=15)
+```
+
+#### 3.6.2 Headless CI 支持
+
+```python
+class XvfbCapture(CaptureBackend):
+    """Xvfb 虚拟帧缓冲截图"""
+
+    def setup(self) -> None:
+        if not self._display_exists():
+            subprocess.run(["Xvfb", ":99", "-screen", "0", "1920x1080x24"],
+                           check=True, start_new_session=True)
+            os.environ["DISPLAY"] = ":99"
+
+    def capture(self, output_path: Path) -> CaptureResult:
+        return subprocess.run(
+            ["xwd", "-root", "-out", str(output_path.with_suffix(".xwd"))],
+            check=True, capture_output=True, timeout=10,
+        )
+```
+
+### 3.7 新增组件
+
+#### 3.7.1 AirDep — 部署插件
+
+```
+职责: SSH 远程构建 + 部署 + systemd 生命周期管理 + 部署验证
+
+工作流:
+  1. 远程构建 (cmake --build / cargo build / npm build)
+  2. 二进制传输 (scp + MD5 校验)
+  3. systemd 操作 (daemon-reload + restart + is-active 验证)
+  4. 部署产物记录 (binary md5, service status, journal excerpt)
+  5. 冒烟验证 (可选: 运行预定义的 smoke test)
+
+制品:
+  AirPlan/state/airdep/
+    sessions/{session_id}.json    # 部署会话完整记录
+    deploy-log.md                 # 人类可读的部署日志
+```
+
+#### 3.7.2 AirTst — 测试运行器插件
+
+```
+职责: 统一测试执行 + 结构化结果报告
+
+支持:
+  - CTest / GoogleTest (C++)
+  - pytest (Python)
+  - jest / vitest (TypeScript)
+  - go test (Go)
+  - cargo test (Rust)
+
+制品:
+  AirPlan/state/airtst/
+    reports/{task_id}-{ts}.json   # 结构化测试结果
+    test-summary.md               # 人类可读摘要
+
+结果格式:
+  {
+    "framework": "googletest",
+    "totalTests": 128,
+    "passed": 127,
+    "failed": 0,
+    "disabled": 1,
+    "duration": "4.2s",
+    "failures": []
+  }
+```
+
+#### 3.7.3 AirSec — 安全扫描插件
+
+```
+职责: 制品敏感数据扫描 + 自动脱敏
+
+扫描目标:
+  - ADR/debug-log 中的 API 密钥、令牌、密码
+  - pcap 文件中的明文凭据
+  - 截图中的敏感 UI 内容（标注但不自动处理）
+
+集成点:
+  - Worker finalize 前自动扫描 result.json
+  - 引擎 merge 前扫描 documentUpdates
+  - 发现敏感数据时阻止合并并通知用户
+```
+
+#### 3.7.4 AirRvr — 需求审查器插件
+
+```
+职责: 基于原始需求文档对已完成任务进行独立审查，验证交付物与需求的一致性
+
+核心问题:
+  V1 中任务"完成"的判定仅依赖 Worker 自报 + AirEng 结构验证。
+  没有任何组件将交付物与原始需求 (requirements.md / plan.md / 用户指令) 进行
+  独立比对。Worker 可能:
+  - 实现了代码但偏离了需求意图
+  - 满足了 Done When 字面条件但遗漏了隐含需求
+  - 验证通过但解决的是错误的问题
+
+工作流:
+  1. 加载原始需求上下文:
+     - AirPlan/docs/analysis/requirements.md
+     - AirPlan/plan.md
+     - AirPlan/todo.md (含当前任务的 Task/Files/Done When/Validation)
+     - 用户的原始指令 (如果有记录)
+
+  2. 加载交付物:
+     - Worker result.json (summary, filesChanged, validations)
+     - 变更文件的 diff (git diff 或文件内容)
+     - 验证证据 (测试输出、截图、静态分析报告)
+
+  3. 多维度审查:
+     - 需求覆盖度: 原始需求中的每个要求点是否被交付物覆盖
+     - 意图一致性: 交付物是否解决了需求想解决的真正问题
+     - 边界完整性: 是否遗漏了需求的隐含边界条件
+     - 回归风险: 变更是否破坏了需求的已有功能
+     - 代码质量: 复杂度、可读性、重复率、异常处理完备性
+     - 生命周期健壮性: 资源释放、连接管理、超时/重试/降级策略
+     - 运行时稳定性: 内存泄漏风险、竞态条件、崩溃路径、错误传播
+     - 用户影响评估: 变更是否引入用户可感知的崩溃或卡顿风险
+     - **Code-to-Design 一致性（强制）**: 代码实现是否严格遵循设计文档，逐行对照
+
+  4. 产出审查报告:
+     AirPlan/state/airrvr/reviews/{task_id}-{ts}.json
+     AirPlan/docs/reviews/{task_id}-review.md
+
+     报告结构:
+     {
+       "taskId": "T-001",
+       "verdict": "pass | conditional-pass | fail",
+       "coverage": [
+         {"requirement": "...", "status": "covered | partial | missing",
+          "evidence": "具体文件或代码位置"}
+       ],
+       "intentAlignment": "aligned | divergent",
+       "divergenceNotes": "...",
+       "regressionRisk": "none | low | medium | high",
+       "regressionDetails": "...",
+       "codeQuality": {
+         "complexity": "low | medium | high",
+         "readability": "good | acceptable | poor",
+         "duplication": "none | low | high",
+         "errorHandling": "complete | partial | missing"
+       },
+       "lifecycleHealth": {
+         "resourceLeak": "none | suspected | confirmed",
+         "connectionManagement": "proper | improper | missing",
+         "timeoutStrategy": "present | absent",
+         "retryStrategy": "present | absent"
+       },
+       "runtimeStability": {
+         "crashRisk": "none | low | medium | high",
+         "raceCondition": "none | suspected | confirmed",
+         "memoryLeak": "none | suspected | confirmed",
+         "userImpact": "none | minor | major"
+       },
+       "codeToDesignTable": [
+         {"designRef": "ADR-0023: JWT认证", "codeLocation": "auth/jwt.py:L45-78", "status": "aligned | divergent | missing", "notes": "实现了ADR规定的RS256算法"},
+         {"designRef": "C4: 模块边界", "codeLocation": "services/auth_service.py:L12", "status": "aligned", "notes": "依赖方向符合架构约束"},
+         {"designRef": "需求: 登录失败锁定", "codeLocation": "auth/login.py:L89-102", "status": "divergent", "notes": "实现了5次失败锁定，需求要求3次"}
+       ],
+       "recommendations": ["..."]
+     }
+
+  5. 与 AirEng 集成:
+     - AirEng merge 前可选调用 AirRvr 审查
+     - verdict=fail 时阻止合并，要求 Worker 修订
+     - verdict=conditional-pass 时允许合并但记录遗留项
+     - verdict=pass 时正常合并
+
+审查模式:
+  - 逐任务审查: 单个任务完成后立即审查
+  - 波次审查: 一个波次所有任务完成后批量审查
+  - 里程碑审查: 项目阶段结束时全量审查 (比对 requirements.md 全文)
+
+  **Code-to-Design 逐行对照审查**（每次审查必含）:
+    对每个任务的交付代码，与对应的设计文档进行逐行级别的对照：
+    - 实现 ↔ 需求: 代码是否覆盖了需求中的每个功能点
+    - 实现 ↔ ADR: 代码是否遵循了架构决策记录中的约束
+    - 实现 ↔ C4: 代码是否符合模块边界和职责划分
+    - 实现 ↔ Done When: 代码是否满足了完成条件的字面要求
+    - 偏离标记: 发现实现偏离设计时，标记具体行号和偏离类型
+
+    报告结构扩展:
+    {
+      "codeToDesign": [
+        {"designItem": "ADR-0003: 使用 JWT 认证",
+         "implementationStatus": "aligned | divergent | missing",
+         "codeLocation": "src/auth/token.py:45-78",
+         "designLocation": "docs/architecture/adr/ADR-0003-jwt.md",
+         "divergenceDetail": "实现使用了 HS256 而非 ADR 规定的 RS256"}
+      ]
+    }
+
+制品:
+  AirPlan/state/airrvr/
+    reviews/{task_id}-{ts}.json    # 结构化审查报告
+    review-summary.md              # 累积审查摘要
+  AirPlan/docs/reviews/
+    {task_id}-review.md            # 人类可读审查报告
+```
+
+#### 3.7.4 事件索引层
+
+```python
+# air_runtime/events.py
+
+class EventLog:
+    """结构化事件日志 (JSONL)"""
+
+    def __init__(self, path: Path):
+        self._path = path
+
+    def emit(self, event_type: str, payload: dict) -> None:
+        entry = {
+            "ts": now_iso(),
+            "type": event_type,
+            **payload,
+        }
+        with open(self._path, "a") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+# 事件类型:
+# task.dispatched    — 任务派发
+# task.completed     — 任务完成
+# task.blocked       — 任务阻塞
+# merge.started      — 合并开始
+# merge.completed    — 合并完成
+# repair.created     — 修复创建
+# repair.resolved    — 修复解决
+# intervention.stall — 停滞干预
+# xdb.captured       — 截图采集
+# debug.session      — 调试会话
+# context.compacted  — 上下文压缩
+# deploy.completed   — 部署完成
+```
+
+事件日志与 `state.json` 互补：`state.json` 是当前快照，事件日志是完整时间线。
+
+### 3.8 `air_runtime` 模块重组
+
+```
+air_runtime/
+  __init__.py
+  contracts.py       # 数据契约（保持，增加 DeploymentRecord）
+  io.py              # NEW: 原子 I/O (替代 5 份 _json_dump)
+  lock.py            # NEW: 文件锁
+  utils.py           # NEW: 公共工具 (替代重复代码)
+  events.py          # NEW: 事件日志
+  task_graph.py      # NEW: 动态任务依赖图 (替代静态 todo 表格)
+  worktree.py        # NEW: git worktree 隔离并行
+  paths.py           # 路径约定（保持）
+  todo_parser.py     # TODO 解析（保持，修复列索引硬编码）
+  review.py          # 并行审查（保持，优化算法）
+  engine.py          # 调度引擎（重构：事务化合并、自适应轮询、资源检测）
+  worker.py          # Worker 生命周期（保持，增加 task_id 校验）
+  doc_sync.py        # 文档同步（保持，增加去重）
+  project_bootstrap.py  # 项目引导（保持）
+  evidence_gate.py   # NEW: 任务类型感知证据门控 (替代无差别 AirXDB 触发)
+  deploy_runtime.py  # NEW: AirDep 运行时
+  test_runtime.py    # NEW: AirTst 运行时
+  airxdb_runtime.py  # 扩展: kmsgrab, xvfb, 截图 diff
+  debug_runtime.py   # 扩展: 步骤追踪, 回滚
+  repair_runtime.py  # 扩展: 修复模式学习
+  review_runtime.py  # NEW: AirRvr 需求审查运行时
+```
+
+---
+
+## 4. 分阶段实施计划
+
+### Phase 1 — 可靠性基础 (P0 修复)
+
+**目标**：消除已造成实际损失的缺陷
+
+| 任务 | 内容 | 对应缺陷 | 预估工作量 |
+|------|------|---------|-----------|
+| T-1.1 | 实现 `air_runtime.io` (原子写入 + 安全加载) | P0-3 | 0.5d |
+| T-1.2 | 实现 `air_runtime.lock` (文件锁) | P0-4 | 0.5d |
+| T-1.3 | 实现 `air_runtime.utils` (消除重复) | P1-2~P1-7 | 1d |
+| T-1.4 | 实现 `EvidenceGatePolicy` (任务类型感知) | P0-1 | 0.5d |
+| T-1.5 | 实现部署验证强制 | P0-2 | 0.5d |
+| T-1.6 | 消除硬编码路径 | P1-1 | 0.5d |
+| T-1.7 | 子进程超时 | P1-10 | 0.5d |
+| T-1.8 | task_id / marker 注入防护 | P1-11, P1-12 | 0.5d |
+| T-1.9 | 异常处理改进 (不静默吞) | P1-13 | 0.5d |
+| T-1.10 | AirArc plan 模式阻断 + 工具白名单 | P0-5 | 0.5d |
+| T-1.11 | AirEng 中文锁定 + 自主决策指令 | P0-6 | 0.5d |
+| T-1.12 | AirEng 强制轮询循环 (5分钟周期) | P0-7 | 0.5d |
+| T-1.13 | AirDo 强制 AirDbg 路由 | P0-8 | 0.5d |
+| T-1.14 | 安装器路径修正 + 安装后验证 | P0-9 | 1d |
+| T-1.15 | AirArc 需求探讨门控（三阶段流程） | P1-16 | 0.5d |
+| T-1.16 | AirDbg 先读后写门控（取证前置） | P1-17 | 0.5d |
+| T-1.17 | 项目级 spdlog 日志标准（AirArc 强制 + AirRvr 检查） | P1-18 | 0.5d |
+| T-1.18 | AirEng 调度职责边界（仅调度 + 极端接管例外） | P0-10 | 0.5d |
+
+**验证标准**：所有现有项目（DecodePlayer 系列）的 state.json 在 V2 引擎下不损坏；AirXDB 假阳性率降至 0。
+
+### Phase 2 — 引擎增强
+
+**目标**：提升调度质量和可观测性
+
+| 任务 | 内容 | 对应缺陷 |
+|------|------|---------|
+| T-2.1 | 自适应轮询 (`AdaptivePoller`) | P3-3 部分 |
+| T-2.2 | Worker 超时与资源压力检测 | P3-3 |
+| T-2.3 | 合并事务化 | P0-4 深化 |
+| T-2.4 | AGENTS.md 去重与压缩 | P3-1 |
+| T-2.5 | 事件日志 (`EventLog`) | 可观测性 |
+| T-2.6 | todo.md 列索引从表头推导 | P1-8 |
+| T-2.7 | 并发度可配置 | P1-9 |
+| T-2.8 | state.json 历史列表上限 | P2-2 |
+| T-2.9 | 动态图调度 (TaskGraph + PlanDelta) | P1-14 |
+| T-2.10 | 区域级冲突检测 + worktree 隔离并行 | P1-15 |
+
+### Phase 3 — 新插件
+
+**目标**：填补最大的功能空白
+
+| 任务 | 内容 | 对应差距 |
+|------|------|---------|
+| T-3.1 | AirDep 部署插件 | 部署缺口 |
+| T-3.2 | AirTst 测试运行器 | 测试标准化 |
+| T-3.3 | AirSDB 多语言后端 | AirSDB 差距 |
+| T-3.4 | AirXDB kmsgrab + xvfb | AirXDB 差距 |
+| T-3.5 | AirDbg 步骤追踪 + 回滚 | AirDbg 差距 |
+| T-3.6 | AirRvr 需求审查器 | 交付物与需求一致性验证缺失 |
+| T-3.7 | AirSec 安全扫描 | 制品敏感数据泄露风险 |
+
+### Phase 4 — 规模化
+
+**目标**：支持大规模项目和多项目知识迁移
+
+| 任务 | 内容 | 对应缺陷 |
+|------|------|---------|
+| T-4.1 | 冲突检测算法优化 (O(n²) → O(n log n)) | P2-1 |
+| T-4.2 | todo.md 缓存 (避免全量重解析) | P2-3 |
+| T-4.3 | AirContext 压缩质量校验 | AirContext 差距 |
+| T-4.4 | AirContext Token 估算改进 | AirContext 差距 |
+| T-4.5 | AirContext 陈旧锁检测 | AirContext 差距 |
+| T-4.6 | AirArc 增量重规划 | AirArc 差距 |
+| T-4.7 | 跨项目运维模式库 | P3-5 |
+
+### Phase 5 — 测试覆盖
+
+**贯穿所有阶段**，每新增/重构模块必须附带测试：
+
+| 模块 | 测试重点 |
+|------|---------|
+| `todo_parser.py` | Markdown 表格格式变化、缺失列、转义字符 |
+| `review.py` | 依赖环检测、写集冲突正确性、大规模任务性能 |
+| `doc_sync.py` | 标记块嵌套/缺失/重叠、路径遍历防护 |
+| `contracts.py` | from_dict/to_dict 往返、验证边界 |
+| `engine.py` | 状态机转换、派发选择、停滞检测 |
+| `io.py` | 原子写入、损坏恢复、备份轮转 |
+| `lock.py` | 锁超时、陈旧锁清理 |
+| `evidence_gate.py` | 任务分类正确率 |
+| `task_graph.py` | 增量 delta 应用、依赖环检测、ready 任务计算 |
+| `worktree.py` | worktree 创建/合并/清理、冲突升级 |
+
+---
+
+## 5. 迁移策略
+
+### 5.1 向后兼容
+
+V2 必须能读取 V1 的 `state.json`、`todo.md`、`result.json`。迁移方式：
+
+```python
+def migrate_state_v1_to_v2(state: dict) -> dict:
+    """V1 → V2 状态迁移"""
+    v2 = {**state}
+
+    # 新增字段使用默认值
+    v2.setdefault("evidenceGatePolicy", {"guiIndicators": [], "networkIndicators": []})
+    v2.setdefault("deployVerificationRequired", False)
+    v2.setdefault("adaptivePolling", True)
+    v2.setdefault("workerMaxWallTimeSeconds", 7200)
+
+    # 历史列表截断
+    for key in ("mergedResults", "xdbSessions", "debugSessions", "repairAttempts"):
+        if key in v2 and len(v2[key]) > 100:
+            v2[key] = v2[key][-100:]
+
+    return v2
+```
+
+### 5.2 渐进式迁移
+
+不需要一次性迁移所有项目。V2 引擎可以混合运行 V1 插件：
+
+- V2 引擎 + V1 Worker：Worker 不感知证据门控变化，引擎侧过滤
+- V2 AirContext + V1 其他：AirContext 独立运行
+- V1 引擎 + V2 AirDep：AirDep 作为独立插件，不依赖引擎版本
+
+### 5.3 回滚方案
+
+V2 的 `state.json` 保持 V1 的 JSON 结构，新增字段使用 `setdefault` 填充。回滚到 V1 引擎时，V1 忽略不认识的新字段。
+
+---
+
+## 6. 关键设计决策
+
+### 6.1 为什么选择文件锁而非数据库
+
+V1 的核心优势是**所有状态都是人类可读文件**。引入 SQLite 会破坏这一属性——`state.json` 可以直接 `cat` 查看，SQLite 不行。文件锁在保持可检查性的同时提供足够的并发安全。
+
+如果项目规模超过 500+ 任务或 20+ 并行 Worker，再考虑引入嵌入式数据库。
+
+### 6.2 为什么证据门控用关键词匹配而非 LLM 分类
+
+关键词匹配的优势：
+- **确定性**：相同输入总是产生相同输出，可测试
+- **零成本**：不需要额外 API 调用
+- **可解释**：用户可以理解为什么某个任务被分类为 GUI 任务
+- **可覆盖**：用户可以在 todo.md 中用 `[no-xdb]` 标记显式跳过
+
+LLM 分类的优势是更准确，但引入了不确定性和额外成本。在 V2 初期使用关键词匹配，积累足够标注数据后可考虑 LLM 分类作为增强。
+
+### 6.3 为什么新插件不合并到 air_runtime
+
+AirDep/AirTst/AirSec 作为独立插件而非 `air_runtime` 模块：
+- 独立版本和发布节奏
+- 用户可按需安装
+- 保持 `air_runtime` 作为核心库的精简性
+- 遵循 V1 的插件边界不变量
+
+---
+
+## 7. 度量指标
+
+V2 应追踪以下 KPI 以验证改进效果：
+
+| 指标 | V1 基线 | V2 目标 |
+|------|---------|---------|
+| AirXDB 假阳性率 | ~60%（11/18 任务） | < 5% |
+| 状态文件损坏率 | 未量化（已知发生） | 0% |
+| 部署一致性事故 | 1 次关键事故 | 0 次 |
+| 空壳修复循环 | 11+ 次 | 0 次 |
+| 代码重复度 | `_json_dump` 5 份等 | 每函数 1 份 |
+| 测试覆盖率 | 0% | 核心模块 > 80% |
+| AGENTS.md 大小 | 持续膨胀 | 自动去重/压缩 |
+| 平均任务合并耗时 | 未量化 | 量化基线 + 优化 |
+| AirArc plan 模式劫持 | 频繁发生 | 0 次 |
+| AirArc 跳过需求探讨直接生成规划 | 每次启动 | 0 次（三阶段门控强制） |
+| AirEng 非中文输出 | 频繁发生 | 0 次 |
+| AirEng 轮询遗忘 | 频繁发生 | 0 次 |
+| AirEng 偏离调度亲自写代码 | 频繁发生 | 0 次（仅极端接管例外，需日志记录） |
+| AirDo 跳过 AirDbg | 频繁发生 | 0 次 |
+| AirDbg 未取证就修改代码 | 频繁发生 | 0 次（先读后写门控强制） |
+| 项目无标准化日志 | 所有项目 | spdlog 覆盖率 100%（AirArc 强制 + AirRvr 检查） |
+| 需求偏离未检出 | 无审查机制 | AirRvr 覆盖率 > 80% |
+| 实现偏离设计未检出 | 无对照机制 | Code-to-Design 对照覆盖率 100% |
+| 安装后插件不可用 | 用户普遍反馈 | 0 次（安装后自动验证通过） |
+| 需求变更后调度恢复时间 | 多轮 AI 迭代 | < 1 次（增量吸收 delta） |
+| 同文件无冲突任务串行率 | 100% 串行 | < 20%（worktree 并行） |