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/scripts/airplan.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""
+AirPlan V2 — 统一 CLI 入口。
+V1 的 8 个独立插件合并为一个命令，通过 --mode 参数路由到对应子模式。
+
+用法:
+  airplan --mode arc --project <project-root> [--todo <todo-md>]
+  airplan --mode eng --project <project-root> [--sub enter|status|plan|dispatch|monitor|merge|run|intervene]
+  airplan --mode do  --project <project-root> --task-id <id>
+  airplan --mode dbg --project <project-root> [--task-id <id>]
+  airplan --mode sdb --project <project-root> [--backend cppcheck|clang-tidy|clippy|go-vet|tsc] [--target <path>]
+  airplan --mode ctx --project <project-root> [--sub now|status|pause|init]
+  airplan --mode dep --project <project-root> --task-id <id> --host <host> [--binary <path>]
+  airplan --mode tst --project <project-root> --task-id <id> [--framework <name>]
+  airplan --mode sec --project <project-root> --task-id <id> [--scan-path <path>]
+  airplan --mode rvr --project <project-root> --task-id <id>
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def _add_lib_path() -> None:
+    root = Path(__file__).resolve().parents[1]
+    lib_path = root / "lib"
+    if str(lib_path) not in sys.path:
+        sys.path.insert(0, str(lib_path))
+
+
+_add_lib_path()
+
+from air_runtime.project_bootstrap import ensure_project_bootstrap
+
+
+def _run_arc(args) -> None:
+    from air_runtime.modes.arc_mode import main as arc_main
+    arc_main(args)
+
+
+def _run_eng(args) -> None:
+    from air_runtime.modes.eng_mode import main as eng_main
+    eng_main(args)
+
+
+def _run_do(args) -> None:
+    from air_runtime.modes.do_mode import main as do_main
+    do_main(args)
+
+
+def _run_dbg(args) -> None:
+    from air_runtime.modes.dbg_mode import main as dbg_main
+    dbg_main(args)
+
+
+def _run_xdb(args) -> None:
+    from air_runtime.modes.xdb_mode import main as xdb_main
+    xdb_main(args)
+
+
+def _run_sdb(args) -> None:
+    from air_runtime.modes.sdb_mode import main as sdb_main
+    sdb_main(args)
+
+
+def _run_ndb(args) -> None:
+    from air_runtime.modes.ndb_mode import main as ndb_main
+    ndb_main(args)
+
+
+def _run_ctx(args) -> None:
+    from air_runtime.modes.ctx_mode import main as ctx_main
+    ctx_main(args)
+
+
+def _run_dep(args) -> None:
+    from air_runtime.modes.dep_mode import main as dep_main
+    dep_main(args)
+
+
+def _run_tst(args) -> None:
+    from air_runtime.modes.tst_mode import main as tst_main
+    tst_main(args)
+
+
+def _run_sec(args) -> None:
+    from air_runtime.modes.sec_mode import main as sec_main
+    sec_main(args)
+
+
+def _run_rvr(args) -> None:
+    from air_runtime.modes.rvr_mode import main as rvr_main
+    rvr_main(args)
+
+
+def _run_eng_orchestrator(args) -> None:
+    from air_runtime.modes.eng_orchestrator import main as eng_orch_main
+    eng_orch_main(args)
+
+
+MODE_ROUTER = {
+    "arc": _run_arc,
+    "eng": _run_eng,
+    "do": _run_do,
+    "dbg": _run_dbg,
+    "xdb": _run_xdb,
+    "sdb": _run_sdb,
+    "ndb": _run_ndb,
+    "ctx": _run_ctx,
+    "dep": _run_dep,
+    "tst": _run_tst,
+    "sec": _run_sec,
+    "rvr": _run_rvr,
+    "eng_orchestrator": _run_eng_orchestrator,
+}
+
+MODE_HELP = {
+    "arc": "架构规划器 — 分析依赖、写集冲突、产出执行计划",
+    "eng": "调度引擎 — 波次派发、监控、合并、修复编排",
+    "do": "任务执行器 — 单任务切片执行与结果生成",
+    "dbg": "调试器 — 7步调试工作流、根因分析、修复回滚",
+    "xdb": "GUI验证器 — 截图取证、GUI操作验证",
+    "sdb": "静态分析器 — 多语言静态分析、diff模式",
+    "ndb": "网络调试器 — 抓包分析、TLS解密",
+    "ctx": "上下文管理器 — 压缩、Token估算、锁检测",
+    "dep": "部署器 — SSH远程构建、部署、systemd管理",
+    "tst": "测试运行器 — 统一测试执行与结果报告",
+    "sec": "安全扫描器 — 敏感数据检测与脱敏",
+    "rvr": "需求审查器 — 交付物与需求一致性验证",
+}
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="AirPlan V2 — 统一制品驱动开发调度器",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="\n".join(f"  {k:6s}  {v}" for k, v in MODE_HELP.items()),
+    )
+    parser.add_argument("--mode", choices=list(MODE_ROUTER.keys()), required=True,
+                       help="子模式选择")
+    parser.add_argument("--project", default=".",
+                       help="项目根目录 (默认: .)")
+    parser.add_argument("--sub", default="",
+                       help="子模式内的二级操作（如 eng 的 enter|status|plan 等）")
+    parser.add_argument("--todo", default="",
+                       help="todo.md 路径（arc/eng 使用）")
+    parser.add_argument("--task-id", default="",
+                       help="任务 ID（do/dbg/xdb/sdb/ndb/dep/tst/sec/rvr 使用）")
+    parser.add_argument("--result", default="",
+                       help="Worker result.json 路径（eng merge 使用）")
+    parser.add_argument("--dispatch-group", default="",
+                       help="派发组名（eng dispatch 使用）")
+    parser.add_argument("--host", default="",
+                       help="远程主机（dep 使用）")
+    parser.add_argument("--binary", default="",
+                       help="本地二进制路径（dep 使用）")
+    parser.add_argument("--framework", default="",
+                       help="测试框架（tst 使用）")
+    parser.add_argument("--scan-path", default="",
+                       help="扫描路径（sec 使用）")
+    parser.add_argument("--sec-mode", default="blocking", choices=["advisory", "blocking"],
+                       help="安全扫描模式（sec 使用）: advisory（只报告）/ blocking（阻止合并）")
+    parser.add_argument("--backend", default="",
+                       help="静态分析后端（sdb 使用）: cppcheck|clang-tidy|clippy|go-vet|tsc")
+    parser.add_argument("--target", default="",
+                       help="分析目标路径（sdb 使用）")
+    parser.add_argument("--prefer", default="auto",
+                       help="截图后端偏好（xdb 使用）: kms|xvfb|fallback|auto")
+    parser.add_argument("--output", default="",
+                       help="截图输出文件名（xdb 使用，默认 screenshot.png）")
+    parser.add_argument("--task-text", default="",
+                       help="任务描述文本（do 使用，用于 UI 任务检测和路由）")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = parse_args(argv)
+    project_root = Path(args.project).expanduser().resolve()
+    ensure_project_bootstrap(project_root)
+
+    handler = MODE_ROUTER.get(args.mode)
+    if handler is None:
+        print(f"Unknown mode: {args.mode}", file=sys.stderr)
+        print(f"Available modes: {', '.join(MODE_ROUTER.keys())}", file=sys.stderr)
+        sys.exit(1)
+
+    handler(args)
+
+
+if __name__ == "__main__":
+    main()

AirPlan/docs/spec/AirPlanV2/scripts/install.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# AirPlan V2 安装脚本
+# 自动安装依赖并配置 Claude Code 插件
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_NAME="airplan-v2"
+SKILLS_DIR="$HOME/.claude/skills"
+
+echo "=========================================="
+echo "AirPlan V2 安装脚本"
+echo "=========================================="
+
+# 检查 Python 版本
+echo "[1/6] 检查 Python 版本..."
+python3 --version || { echo "错误: 需要 Python 3"; exit 1; }
+
+# 检查必要工具
+echo "[2/6] 检查必要工具..."
+command -v git >/dev/null 2>&1 || { echo "错误: 需要 git"; exit 1; }
+
+# 创建 skills 目录
+echo "[3/6] 配置插件目录..."
+mkdir -p "$SKILLS_DIR"
+
+# 创建符号链接或克隆
+if [ -L "$SKILLS_DIR/$PLUGIN_NAME" ]; then
+    echo "插件已存在: $SKILLS_DIR/$PLUGIN_NAME"
+elif [ -d "$SKILLS_DIR/$PLUGIN_NAME" ]; then
+    echo "插件目录已存在，更新中..."
+    cd "$SKILLS_DIR/$PLUGIN_NAME"
+    git pull origin master
+else
+    echo "从远程克隆插件..."
+    git clone http://git.airlongdian.fun/admin/AirPlan-V2.git "$SKILLS_DIR/$PLUGIN_NAME"
+fi
+
+# 验证安装
+echo "[4/6] 验证安装..."
+if [ ! -f "$SKILLS_DIR/$PLUGIN_NAME/.claude-plugin/plugin.json" ]; then
+    echo "错误: plugin.json 不存在"
+    exit 1
+fi
+
+if [ ! -f "$SKILLS_DIR/$PLUGIN_NAME/skills/airplan/SKILL.md" ]; then
+    echo "错误: SKILL.md 不存在"
+    exit 1
+fi
+
+# 检查依赖
+echo "[5/6] 检查依赖..."
+# 检查系统依赖（可选）
+command -v xvfb-run >/dev/null 2>&1 && echo "  - xvfb-run: ✓" || echo "  - xvfb-run: ✗ (可选，用于无头 GUI 测试)"
+command -v ffmpeg >/dev/null 2>&1 && echo "  - ffmpeg: ✓" || echo "  - ffmpeg: ✗ (可选，用于视频处理)"
+command -v cmake >/dev/null 2>&1 && echo "  - cmake: ✓" || echo "  - cmake: ✗ (可选，用于 C++ 项目构建)"
+
+echo "[6/6] 安装完成!"
+echo ""
+echo "=========================================="
+echo "使用方法:"
+echo "  /arc    - 架构规划"
+echo "  /eng    - 调度引擎"
+echo "  /do     - 任务执行"
+echo "  /dbg    - 调试模式"
+echo "  /xdb    - GUI 验证"
+echo "  /sdb    - 静态分析"
+echo "  /ndb    - 网络调试"
+echo "  /ctx    - 上下文管理"
+echo "  /dep    - 部署"
+echo "  /tst    - 测试"
+echo "  /sec    - 安全扫描"
+echo "  /rvr    - 需求审查"
+echo "=========================================="
+
+# 提示重启 Claude Code
+echo ""
+echo "提示: 请重启 Claude Code 以加载新插件"

AirPlan/docs/spec/AirPlanV2/scripts/test_install.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# AirPlan V2 安装脚本测试
+# 模拟运行安装脚本的关键步骤（不实际克隆）
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_NAME="airplan-v2"
+SKILLS_DIR="$HOME/.claude/skills"
+
+echo "=========================================="
+echo "AirPlan V2 安装脚本测试"
+echo "=========================================="
+
+# 测试1: 检查 Python 版本
+echo "[测试1] 检查 Python 版本..."
+python3 --version || { echo "错误: 需要 Python 3"; exit 1; }
+echo "✓ Python 版本检查通过"
+
+# 测试2: 检查必要工具
+echo "[测试2] 检查必要工具..."
+command -v git >/dev/null 2>&1 || { echo "错误: 需要 git"; exit 1; }
+echo "✓ git 可用"
+
+# 测试3: 创建测试 skills 目录
+echo "[测试3] 测试目录创建..."
+TEST_DIR=$(mktemp -d)
+mkdir -p "$TEST_DIR/test-skills"
+echo "✓ 目录创建成功: $TEST_DIR"
+
+# 测试4: 模拟插件检查
+echo "[测试4] 模拟插件结构检查..."
+# 创建模拟的 plugin.json
+mkdir -p "$TEST_DIR/airplan-v2/.claude-plugin"
+cat > "$TEST_DIR/airplan-v2/.claude-plugin/plugin.json" << 'PLUGIN_JSON'
+{
+  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
+  "name": "airplan-v2",
+  "version": "2.0.0"
+}
+PLUGIN_JSON
+
+# 创建模拟的 SKILL.md
+mkdir -p "$TEST_DIR/airplan-v2/skills/airplan"
+cat > "$TEST_DIR/airplan-v2/skills/airplan/SKILL.md" << 'SKILL_MD'
+# AirPlan V2
+SKILL_MD
+
+if [ ! -f "$TEST_DIR/airplan-v2/.claude-plugin/plugin.json" ]; then
+    echo "错误: plugin.json 不存在"
+    exit 1
+fi
+echo "✓ plugin.json 存在"
+
+if [ ! -f "$TEST_DIR/airplan-v2/skills/airplan/SKILL.md" ]; then
+    echo "错误: SKILL.md 不存在"
+    exit 1
+fi
+echo "✓ SKILL.md 存在"
+
+# 测试5: 检查依赖工具
+echo "[测试5] 检查依赖工具..."
+command -v xvfb-run >/dev/null 2>&1 && echo "  - xvfb-run: ✓" || echo "  - xvfb-run: ✗ (可选)"
+command -v ffmpeg >/dev/null 2>&1 && echo "  - ffmpeg: ✓" || echo "  - ffmpeg: ✗ (可选)"
+command -v cmake >/dev/null 2>&1 && echo "  - cmake: ✓" || echo "  - cmake: ✗ (可选)"
+
+# 清理测试目录
+rm -rf "$TEST_DIR"
+
+echo ""
+echo "=========================================="
+echo "所有测试通过! ✓"
+echo "=========================================="