chore: push all design docs, V2 plan specs, and current working state

Includes AirPlan design documents, AircOding-alpha1-plan, AirPlanV2,
AirPlan-ParaV2, AirPlan-Para V1 reference docs, and all working code
changes across packages.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

AirPlan/docs/spec/AirPlanV2/lib/air_runtime/utils.py

@@ -0,0 +1,65 @@
+"""
+公共工具函数 — 消除 V1 中 _ordered_unique、_session_stamp、policy normalization 等
+在各模块中 3~5 份重复定义的代码。
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from typing import Any
+
+
+def ordered_unique(items: list) -> list:
+    """保序去重。支持字符串列表和带 id 字段的字典列表。"""
+    seen: set[str] = 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 now_iso() -> str:
+    """ISO 格式 UTC 时间戳，用于 JSON state 文件。"""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def normalize_policy(defaults: dict[str, Any], overrides: dict[str, Any] | None) -> dict[str, Any]:
+    """通用的策略合并：overrides 覆盖 defaults，类型自动转换。"""
+    merged = {**defaults}
+    if overrides:
+        for k, v in overrides.items():
+            if k in merged:
+                expected_type = type(defaults[k])
+                try:
+                    merged[k] = expected_type(v) if not isinstance(v, expected_type) else v
+                except (ValueError, TypeError):
+                    merged[k] = 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
+
+
+def truncate_history(data: list, max_items: int = 100) -> list:
+    """截断历史列表，防止无界增长（P2-2）。"""
+    return data[-max_items:] if len(data) > max_items else data