init

src/cognitive_agent.egg-info/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: cognitive-agent
+Version: 0.1.0
+Summary: Configuration-driven cognitive orchestration agent for in-vehicle actuators
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: pydantic>=2.6
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.110; extra == "api"
+Requires-Dist: uvicorn>=0.27; extra == "api"
+Provides-Extra: can
+Requires-Dist: cantools>=39; extra == "can"
+Requires-Dist: python-can>=4.3; extra == "can"
+Provides-Extra: llm
+Requires-Dist: openai>=1.30; extra == "llm"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"

src/cognitive_agent.egg-info/SOURCES.txt

@@ -0,0 +1,27 @@
+README.md
+pyproject.toml
+src/cognitive_agent/__init__.py
+src/cognitive_agent/auth.py
+src/cognitive_agent/config_loader.py
+src/cognitive_agent/server.py
+src/cognitive_agent.egg-info/PKG-INFO
+src/cognitive_agent.egg-info/SOURCES.txt
+src/cognitive_agent.egg-info/dependency_links.txt
+src/cognitive_agent.egg-info/requires.txt
+src/cognitive_agent.egg-info/top_level.txt
+src/cognitive_agent/application/capability_registry.py
+src/cognitive_agent/application/conversation_state.py
+src/cognitive_agent/application/domain_runtime.py
+src/cognitive_agent/application/gesture_bridge.py
+src/cognitive_agent/application/model_plan_adapter.py
+src/cognitive_agent/application/seat_calibration.py
+src/cognitive_agent/application/seat_service.py
+src/cognitive_agent/infrastructure/can/__init__.py
+src/cognitive_agent/infrastructure/can/gateway.py
+src/cognitive_agent/infrastructure/can/hardware.py
+src/cognitive_agent/infrastructure/can/matrix.py
+src/cognitive_agent/infrastructure/can/zlgcan_bridge.py
+src/cognitive_agent/infrastructure/firmware/__init__.py
+src/cognitive_agent/infrastructure/firmware/t2g_seat.py
+src/cognitive_agent/infrastructure/llm/openai_responses.py
+src/cognitive_agent/runtime/contracts.py

src/cognitive_agent.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

src/cognitive_agent.egg-info/requires.txt

@@ -0,0 +1,22 @@
+jsonschema>=4.21
+pydantic>=2.6
+PyYAML>=6.0
+
+[api]
+fastapi>=0.110
+uvicorn>=0.27
+
+[can]
+cantools>=39
+python-can>=4.3
+
+[dev]
+mypy>=1.9
+ruff>=0.4
+
+[llm]
+openai>=1.30
+
+[test]
+pytest>=8
+pytest-cov>=5

src/cognitive_agent.egg-info/top_level.txt

@@ -0,0 +1 @@
+cognitive_agent

src/cognitive_agent/__init__.py

@@ -0,0 +1,2 @@
+"""Cognitive orchestration agent package."""
+

src/cognitive_agent/agent/README.md

@@ -0,0 +1,6 @@
+# Agent
+
+负责提示词装配、结构化输出、意图抽取和领域路由。输入是用户文本、能力目录和受控上下文；输出是 `IntentIR` 或配置候选。这里不加载 DBC，不访问 CAN，不实现执行器规则。
+
+Prompt 必须版本化并要求结构化输出。模型置信度不能替代 Schema、安全策略或用户确认。
+

src/cognitive_agent/agent/prompts/README.md

@@ -0,0 +1,4 @@
+# Prompts
+
+按任务保存版本化模板，例如 `intent_parser/`、`function_generator/` 和 `scene_planner/`。模板只引用 Registry 提供的能力，不硬编码领域列表或 CAN 信号。
+

src/cognitive_agent/application/README.md

@@ -0,0 +1,4 @@
+# Application
+
+实现面向 API/CLI 的用例：提交请求、确认歧义、生成配置、dry-run、执行、取消和查询结果。负责权限、幂等、任务状态和 artifact 生命周期，不包含具体领域转换规则。
+

src/cognitive_agent/application/capability_registry.py

@@ -0,0 +1,63 @@
+"""Load model-facing capability context from domain-owned catalogs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class CapabilityRegistry:
+    """Expose domain catalogs without embedding domain semantics in prompts or code."""
+
+    def __init__(self, repository_root: Path, executable_domains: set[str]) -> None:
+        self.root = repository_root
+        self.executable_domains = set(executable_domains)
+        self._snapshot = self._load()
+
+    def snapshot(self) -> dict[str, Any]:
+        return self._snapshot
+
+    def _load(self) -> dict[str, Any]:
+        domains = []
+        for catalog_path in sorted(
+            (self.root / "domains").glob("*/config/capabilities.yaml")
+        ):
+            if catalog_path.parts[-3] == "_template":
+                continue
+            catalog = yaml.safe_load(catalog_path.read_text(encoding="utf-8"))
+            domain = catalog["spec"]["domain"]
+            domains.append(
+                {
+                    "domain": domain,
+                    "availability": (
+                        "executable" if domain in self.executable_domains else "catalog_only"
+                    ),
+                    "capabilities": catalog["spec"]["capabilities"],
+                }
+            )
+        return {
+            "interaction_context": {
+                "surface": "driver_console",
+                "speaker_default_scope": "driver",
+            },
+            "execution_policy": {
+                "executable_domains": sorted(self.executable_domains),
+                "catalog_only_behavior": "return_as_deferred_request",
+                "planning_environment": "dry_run_candidate_synthesis",
+                "named_preset_required": False,
+                "fuzzy_goal_behavior": (
+                    "decompose a commonly understood user goal into executable atomic "
+                    "capabilities and infer conservative absolute targets"
+                ),
+                "capability_selection": (
+                    "prefer_executable_when_equally_suitable; never replace a clearly better "
+                    "capability solely because it is executable"
+                ),
+                "executable_request_parameters": (
+                    "resolve relative intent against runtime state and return absolute target values"
+                ),
+            },
+            "domains": domains,
+        }

src/cognitive_agent/application/conversation_state.py

@@ -0,0 +1,346 @@
+"""Thread-safe in-memory conversation and virtual actuator state."""
+
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from datetime import UTC, datetime
+from pathlib import Path
+from threading import RLock
+from typing import Any
+
+from cognitive_agent.application.seat_calibration import position_pct_to_angle
+
+
+TARGETS = ("driver", "passenger")
+THERMAL_FUNCTIONS = ("ventilation", "heating")
+MOTION_INITIAL_POSITIONS = {
+    "longitudinal": 50,
+    "cushion_tilt": 50,
+    "backrest_recline": 20,
+    "legrest_height": 0,
+    "legrest_extension": 0,
+}
+CLIMATE_ZONES = (
+    "vehicle",
+    "front_row",
+    "rear_row",
+    "driver",
+    "passenger",
+    "rear_left",
+    "rear_right",
+)
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+
+
+def _motion_state(axis: str, position: int) -> dict[str, Any]:
+    value: dict[str, Any] = {
+        "position_pct": position,
+        "motion_state": "stopped",
+        "fault": False,
+    }
+    angle = position_pct_to_angle(axis, position)
+    if angle is not None:
+        value["angle_deg"] = angle
+    return value
+
+
+def _new_state(
+    conversation_id: str,
+    presets: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    return {
+        "conversation_id": conversation_id,
+        "turn_count": 0,
+        "last_target": None,
+        "updated_at": _now(),
+        "devices": {
+            target: {
+                **{
+                    function: {"state": "off", "level": 0}
+                    for function in THERMAL_FUNCTIONS
+                },
+                "position": {
+                    axis: _motion_state(axis, position)
+                    for axis, position in MOTION_INITIAL_POSITIONS.items()
+                },
+            }
+            for target in TARGETS
+        },
+        "domain_devices": {
+            "climate": {
+                "power": "off",
+                "ac": "off",
+                "fan_level": 0,
+                "cycle_mode": "external",
+                "front_defrost": "off",
+                "zones": {
+                    zone: {
+                        "power": "off",
+                        "temperature_c": 24,
+                        "outlet_mode": "face",
+                    }
+                    for zone in CLIMATE_ZONES
+                },
+            },
+            "roof": {
+                "shade_position_pct": 0,
+                "transmittance_pct": 100,
+                "automatic_dimming": "off",
+                "motion_state": "stopped",
+                "fault": False,
+            },
+            "ambient_light": {
+                "power": "off",
+                "color_hex": "#74D9FF",
+                "brightness_pct": 0,
+                "mode": "off",
+            },
+        },
+        "presets": list(presets or []),
+        "recent_turns": [],
+    }
+
+
+class ConversationStateStore:
+    """Keep isolated dry-run state for each browser conversation."""
+
+    def __init__(
+        self,
+        max_conversations: int = 256,
+        preset_root: Path | None = None,
+    ) -> None:
+        self._states: dict[str, dict[str, Any]] = {}
+        self._max_conversations = max_conversations
+        self.preset_root = preset_root
+        self._lock = RLock()
+
+    def _preset_path(self, conversation_id: str) -> Path | None:
+        if self.preset_root is None:
+            return None
+        return self.preset_root / f"{conversation_id}.json"
+
+    def _load_presets(self, conversation_id: str) -> list[dict[str, Any]]:
+        path = self._preset_path(conversation_id)
+        if path is None or not path.is_file():
+            return []
+        try:
+            document = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return []
+        presets = document.get("presets", [])
+        return presets if isinstance(presets, list) else []
+
+    def _persist_presets(self, conversation_id: str, presets: list[dict[str, Any]]) -> None:
+        path = self._preset_path(conversation_id)
+        if path is None:
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = path.with_suffix(".json.tmp")
+        temporary.write_text(
+            json.dumps(
+                {
+                    "conversation_id": conversation_id,
+                    "presets": presets,
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+            + "\n",
+            encoding="utf-8",
+        )
+        temporary.replace(path)
+
+    def _state(self, conversation_id: str) -> dict[str, Any]:
+        state = self._states.get(conversation_id)
+        if state is not None:
+            return state
+        if len(self._states) >= self._max_conversations:
+            oldest_id = next(iter(self._states))
+            del self._states[oldest_id]
+        state = _new_state(conversation_id, self._load_presets(conversation_id))
+        self._states[conversation_id] = state
+        return state
+
+    def snapshot(self, conversation_id: str) -> dict[str, Any]:
+        with self._lock:
+            state = self._state(conversation_id)
+            return deepcopy(state)
+
+    def apply_successful_actions(
+        self,
+        conversation_id: str,
+        utterance: str,
+        actions: list[dict[str, Any]],
+        decision_summary: list[str],
+    ) -> dict[str, Any]:
+        with self._lock:
+            state = self._state(conversation_id)
+            for action in actions:
+                if action.get("domain") in {
+                    "climate",
+                    "roof",
+                    "ambient_light",
+                }:
+                    self._apply_domain_action(state, action)
+                    state["last_target"] = action["target"]
+                    continue
+                target = action["target"]
+                if action.get("action_type") == "position":
+                    axis = action["axis"]
+                    position_state = _motion_state(axis, action["position_pct"])
+                    if action.get("angle_deg") is not None:
+                        position_state["angle_deg"] = action["angle_deg"]
+                    if action.get("position_valid") is not None:
+                        position_state["position_valid"] = bool(
+                            action["position_valid"]
+                        )
+                    if action.get("position_estimated") is not None:
+                        position_state["position_estimated"] = bool(
+                            action["position_estimated"]
+                        )
+                    if action.get("feedback_basis") is not None:
+                        position_state["feedback_basis"] = str(
+                            action["feedback_basis"]
+                        )
+                    state["devices"][target]["position"][axis] = position_state
+                    state["last_target"] = target
+                    continue
+                function = action["function"]
+                requested_state = action["state"]
+                previous = state["devices"][target][function]
+                if requested_state == "off":
+                    level = 0
+                else:
+                    level = action.get("requested_level") or previous["level"] or 1
+                state["devices"][target][function] = {
+                    "state": requested_state,
+                    "level": level,
+                }
+                state["last_target"] = target
+
+            state["turn_count"] += 1
+            state["updated_at"] = _now()
+            state["recent_turns"].append(
+                {
+                    "utterance": utterance,
+                    "actions": deepcopy(actions),
+                    "decision_summary": list(decision_summary),
+                }
+            )
+            state["recent_turns"] = state["recent_turns"][-6:]
+            return deepcopy(state)
+
+    @staticmethod
+    def _apply_domain_action(
+        state: dict[str, Any],
+        action: dict[str, Any],
+    ) -> None:
+        domain = action["domain"]
+        capability = action["capability"]
+        target = action["target"]
+        parameters = action["parameters"]
+        device = state["domain_devices"][domain]
+
+        if domain == "climate":
+            if capability == "climate.set_power":
+                device["zones"][target]["power"] = parameters["state"]
+                if target == "vehicle":
+                    device["power"] = parameters["state"]
+                    for zone in device["zones"].values():
+                        zone["power"] = parameters["state"]
+            elif capability == "climate.set_temperature":
+                device["zones"][target]["temperature_c"] = parameters[
+                    "temperature_c"
+                ]
+                if target == "vehicle":
+                    for zone in device["zones"].values():
+                        zone["temperature_c"] = parameters["temperature_c"]
+            elif capability == "climate.set_fan_level":
+                device["fan_level"] = parameters["level"]
+            elif capability == "climate.set_ac":
+                device["ac"] = parameters["state"]
+            elif capability == "climate.set_cycle_mode":
+                device["cycle_mode"] = parameters["mode"]
+            elif capability == "climate.set_front_defrost":
+                device["front_defrost"] = parameters["state"]
+            elif capability == "climate.set_outlet_mode":
+                device["zones"][target]["outlet_mode"] = parameters["mode"]
+            return
+
+        if domain == "roof":
+            if capability == "roof.set_shade_position":
+                device["shade_position_pct"] = parameters["position_pct"]
+            elif capability == "roof.set_transmittance":
+                device["transmittance_pct"] = parameters["transmittance_pct"]
+            elif capability == "roof.set_automatic_dimming":
+                device["automatic_dimming"] = parameters["state"]
+            return
+
+        if capability == "ambient_light.set_power":
+            device["power"] = parameters["state"]
+        elif capability == "ambient_light.set_illumination":
+            device["color_hex"] = parameters["color_hex"]
+            device["brightness_pct"] = parameters["brightness_pct"]
+            device["power"] = "on" if parameters["brightness_pct"] > 0 else "off"
+            device["mode"] = "custom"
+        elif capability == "ambient_light.set_mode":
+            device["mode"] = parameters["mode"]
+            if parameters["mode"] in {"on", "off"}:
+                device["power"] = parameters["mode"]
+
+    def save_preset(
+        self,
+        conversation_id: str,
+        utterance: str,
+        target: str,
+        preset_name: str,
+        function_preset: dict[str, Any],
+        decision_summary: list[str],
+    ) -> dict[str, Any]:
+        with self._lock:
+            state = self._state(conversation_id)
+            entry = {
+                "name": preset_name,
+                "target": target,
+                "saved_at": _now(),
+                "function_preset": deepcopy(function_preset),
+            }
+            expected_name = preset_name.casefold()
+            state["presets"] = [
+                item
+                for item in state["presets"]
+                if not (
+                    item.get("target") == target
+                    and str(item.get("name", "")).casefold() == expected_name
+                )
+            ]
+            state["presets"].append(entry)
+            state["last_target"] = target
+            state["turn_count"] += 1
+            state["updated_at"] = _now()
+            state["recent_turns"].append(
+                {
+                    "utterance": utterance,
+                    "actions": [
+                        {
+                            "action_type": "preset_save",
+                            "target": target,
+                            "preset_name": preset_name,
+                        }
+                    ],
+                    "decision_summary": list(decision_summary),
+                }
+            )
+            state["recent_turns"] = state["recent_turns"][-6:]
+            self._persist_presets(conversation_id, state["presets"])
+            return deepcopy(state)
+
+    def reset(self, conversation_id: str) -> dict[str, Any]:
+        with self._lock:
+            state = _new_state(conversation_id, self._load_presets(conversation_id))
+            self._states[conversation_id] = state
+            return deepcopy(state)

src/cognitive_agent/application/domain_runtime.py

@@ -0,0 +1,307 @@
+"""Configuration generation, deterministic compilation, and dry-run execution."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from cognitive_agent.infrastructure.can import CanMatrix
+
+
+HEX_COLOR = re.compile(r"^#[0-9A-Fa-f]{6}$")
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+
+
+class ConfiguredDomainRuntime:
+    """Domain-isolated runtime backed entirely by domain-owned YAML documents."""
+
+    compiler_version = "1.0.0"
+
+    def __init__(self, repository_root: Path, domain: str):
+        self.domain = domain
+        self.root = repository_root / "domains" / domain
+        self.catalog = yaml.safe_load(
+            (self.root / "config" / "capabilities.yaml").read_text(encoding="utf-8")
+        )
+        self.mapping = yaml.safe_load(
+            (self.root / "can" / "signal-mapping.yaml").read_text(encoding="utf-8")
+        )
+        self.matrix = CanMatrix(self.root / "can" / "can-matrix.yaml")
+        self.capabilities = {
+            item["name"]: item for item in self.catalog["spec"]["capabilities"]
+        }
+
+    def runtime_info(self) -> dict[str, Any]:
+        return {
+            "domain": self.domain,
+            "hardware_execution_allowed": self.matrix.hardware_execution_allowed,
+            "capabilities": self.catalog["spec"]["capabilities"],
+            "matrix": {
+                "messages": len(self.matrix.data["messages"]),
+                "signals": sum(
+                    len(message["signals"])
+                    for message in self.matrix.data["messages"]
+                ),
+                "source": self.matrix.data["source"],
+                "limitations": self.matrix.data["limitations"],
+            },
+        }
+
+    def build_function_config(
+        self,
+        actions: list[dict[str, Any]],
+        request_id: str,
+        provider: str,
+    ) -> dict[str, Any]:
+        operations = []
+        for index, action in enumerate(actions, start=1):
+            capability_suffix = action["capability"].split(".", 1)[1]
+            operation_id = f"{action['target']}_{capability_suffix}_{index}"
+            operations.append(
+                {
+                    "id": operation_id[:63],
+                    "capability": action["capability"],
+                    "target": {
+                        "device": self.capabilities[action["capability"]][
+                            "target_devices"
+                        ][0],
+                        "zone": action["target"],
+                    },
+                    "parameters": dict(action["parameters"]),
+                    "timeout_ms": 8000 if self.domain == "roof" else 4000,
+                    "failure_policy": "abort",
+                }
+            )
+        return {
+            "apiVersion": "cognitive-agent/v1alpha1",
+            "kind": "FunctionConfig",
+            "metadata": {
+                "id": f"{self.domain}-{request_id}",
+                "name": f"{self.domain.replace('_', ' ').title()} function",
+                "version": "1.0.0",
+                "request_id": request_id,
+                "generated_at": _now(),
+                "labels": {
+                    "provider": provider,
+                    "execution_scope": "virtual_only",
+                    "matrix_source": "supplied_xlsx",
+                },
+            },
+            "spec": {
+                "domain": self.domain,
+                "operations": operations,
+                "assumptions": [
+                    "The supplied matrix is partial; this configuration is eligible for virtual execution only.",
+                    "Sub-ID placement and LSB0/Intel encoding are inferred from the workbook byte annotations.",
+                ],
+            },
+        }
+
+    def compile(self, function_config: dict[str, Any]) -> dict[str, Any]:
+        commands: list[dict[str, Any]] = []
+        for operation_index, operation in enumerate(
+            function_config["spec"]["operations"], start=1
+        ):
+            mappings = self._mappings_for(operation)
+            grouped: dict[tuple[str, str], dict[str, Any]] = {}
+            covered_parameters: set[str] = set()
+            completion: dict[str, Any] | None = None
+            for mapping in mappings:
+                parameter = mapping["parameter"]
+                if parameter not in operation["parameters"]:
+                    continue
+                covered_parameters.add(parameter)
+                key = (mapping["bus"], mapping["message"])
+                signals = grouped.setdefault(key, {"signals": {}})["signals"]
+                signals.update(
+                    self._compile_value(
+                        mapping,
+                        operation["parameters"][parameter],
+                    )
+                )
+                if completion is None and mapping.get("feedback_message"):
+                    feedback_value = self._compile_feedback(
+                        mapping,
+                        operation["parameters"][parameter],
+                    )
+                    completion = {
+                        "message": mapping["feedback_message"],
+                        "signal": mapping["feedback_signal"],
+                        "operator": "eq",
+                        "value": feedback_value,
+                        "timeout_ms": int(operation.get("timeout_ms", 4000)),
+                    }
+
+            missing = set(operation["parameters"]) - covered_parameters
+            if missing:
+                raise ValueError(
+                    f"No {self.domain} signal mapping for {operation['capability']} "
+                    f"parameters: {', '.join(sorted(missing))}"
+                )
+            for group_index, ((bus, message), group) in enumerate(
+                grouped.items(), start=1
+            ):
+                command_id = (
+                    f"{self.domain}_{operation_index}_{group_index}_control"
+                )[:63]
+                command: dict[str, Any] = {
+                    "id": command_id,
+                    "operation_ref": operation["id"],
+                    "bus": bus,
+                    "message": message,
+                    "signals": dict(sorted(group["signals"].items())),
+                    "send_offset_ms": (operation_index - 1) * 20,
+                }
+                if completion is not None and group_index == 1:
+                    command["completion"] = completion
+                commands.append(command)
+
+        canonical = json.dumps(
+            function_config, ensure_ascii=False, sort_keys=True
+        ).encode("utf-8")
+        metadata = function_config["metadata"]
+        return {
+            "apiVersion": "cognitive-agent/v1alpha1",
+            "kind": "CommandPlan",
+            "metadata": {
+                "id": f"plan-{self.domain}-{metadata['request_id']}",
+                "name": f"{self.domain.replace('_', ' ').title()} CAN command plan",
+                "version": "1.0.0",
+                "request_id": metadata["request_id"],
+                "labels": {"execution_scope": "virtual_only"},
+            },
+            "spec": {
+                "domain": self.domain,
+                "platform": self.mapping["spec"]["platform"],
+                "source": {
+                    "config_id": metadata["id"],
+                    "config_version": metadata["version"],
+                    "config_sha256": hashlib.sha256(canonical).hexdigest(),
+                    "compiler_version": self.compiler_version,
+                    "mapping_version": self.mapping["metadata"]["version"],
+                },
+                "commands": commands,
+            },
+        }
+
+    def execute(
+        self,
+        command_plan: dict[str, Any],
+        function_config: dict[str, Any],
+    ) -> dict[str, Any]:
+        started_at = _now()
+        operations = {
+            item["id"]: item for item in function_config["spec"]["operations"]
+        }
+        results = []
+        for command in command_plan["spec"]["commands"]:
+            operation = operations[command["operation_ref"]]
+            command_frame = self.matrix.encode(
+                command["message"], command["signals"]
+            )
+            completion = command.get("completion")
+            feedback_frame = None
+            if completion is not None:
+                feedback_frame = self.matrix.encode(
+                    completion["message"],
+                    {completion["signal"]: int(completion["value"])},
+                )
+            results.append(
+                {
+                    "ref": operation["id"],
+                    "domain": self.domain,
+                    "status": "succeeded",
+                    "message": (
+                        f"虚拟 CAN 已执行 {operation['capability']}，"
+                        + ("模拟反馈与目标一致。" if feedback_frame else "矩阵未提供直接结果反馈。")
+                    ),
+                    "telemetry": {
+                        "target": operation["target"]["zone"],
+                        "requested_parameters": operation["parameters"],
+                        "command_frame": command_frame,
+                        "feedback_frame": feedback_frame,
+                        "feedback_available": feedback_frame is not None,
+                        "matrix_source": "supplied_xlsx",
+                        "simulated": True,
+                    },
+                }
+            )
+        request_id = function_config["metadata"]["request_id"]
+        return {
+            "apiVersion": "cognitive-agent/v1alpha1",
+            "kind": "ExecutionReport",
+            "metadata": {
+                "id": f"report-{self.domain}-{request_id}",
+                "name": f"{self.domain.replace('_', ' ').title()} virtual execution report",
+                "version": "1.0.0",
+                "request_id": request_id,
+                "labels": {"simulation": "true"},
+            },
+            "spec": {
+                "mode": "dry_run",
+                "status": "succeeded",
+                "started_at": started_at,
+                "finished_at": _now(),
+                "results": results,
+            },
+        }
+
+    def _mappings_for(self, operation: dict[str, Any]) -> list[dict[str, Any]]:
+        matches = [
+            item
+            for item in self.mapping["spec"]["mappings"]
+            if item["capability"] == operation["capability"]
+            and item.get("target_zone") == operation["target"]["zone"]
+        ]
+        if not matches:
+            raise ValueError(
+                f"No {self.domain} mapping for capability={operation['capability']}, "
+                f"zone={operation['target']['zone']}"
+            )
+        return matches
+
+    @staticmethod
+    def _compile_value(mapping: dict[str, Any], value: Any) -> dict[str, int]:
+        handler = mapping["compiler_handler"]
+        if handler == "compile_enum":
+            try:
+                raw = mapping["value_map"][str(value)]
+            except KeyError as exc:
+                raise ValueError(f"Unmapped enum value: {value!r}") from exc
+            return {mapping["signal"]: int(raw)}
+        if handler == "compile_integer":
+            return {mapping["signal"]: int(value)}
+        if handler == "compile_level_plus_one":
+            return {mapping["signal"]: int(value) + 1}
+        if handler == "compile_hex_rgb":
+            color = str(value)
+            if not HEX_COLOR.fullmatch(color):
+                raise ValueError("color_hex must use #RRGGBB")
+            channels = [int(color[index : index + 2], 16) for index in (1, 3, 5)]
+            return dict(zip(mapping["signals"], channels, strict=True))
+        raise ValueError(f"Unsupported compiler handler: {handler}")
+
+    @staticmethod
+    def _compile_feedback(mapping: dict[str, Any], value: Any) -> int:
+        handler = mapping.get("feedback_handler", mapping["compiler_handler"])
+        if handler == "compile_enum":
+            values = mapping.get("feedback_value_map", mapping.get("value_map", {}))
+            return int(values[str(value)])
+        if handler == "compile_integer":
+            return int(value)
+        if handler == "compile_temperature_feedback":
+            return int(value) - 16
+        if handler == "compile_transmittance_bucket":
+            percentage = int(value)
+            return 1 if percentage == 0 else min(11, math.ceil(percentage / 10) + 1)
+        raise ValueError(f"Unsupported feedback handler: {handler}")

src/cognitive_agent/application/gesture_bridge.py

@@ -0,0 +1,64 @@
+"""Expose the gesture model and safety configuration bundled with this project."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+DEFAULT_ACTION_COPY = {
+    "POINT_UP": {"action": "SEAT_UP", "utterance": "副驾驶座椅坐垫前端升高一点"},
+    "POINT_DOWN": {"action": "SEAT_DOWN", "utterance": "副驾驶座椅坐垫前端降低一点"},
+    "POINT_RIGHT": {"action": "SEAT_FORWARD", "utterance": "副驾驶座椅向前移动一点"},
+    "POINT_LEFT": {"action": "SEAT_BACKWARD", "utterance": "副驾驶座椅向后移动一点"},
+    "THUMB_UP": {"action": "BACKREST_FORWARD", "utterance": "副驾驶靠背向前调一点"},
+    "THUMB_DOWN": {"action": "BACKREST_BACKWARD", "utterance": "副驾驶靠背向后调一点"},
+    "GUN_UP": {"action": "LEGREST_EXTEND", "utterance": "副驾驶腿托伸出一点"},
+    "GUN_DOWN": {"action": "LEGREST_RETRACT", "utterance": "副驾驶腿托收回一点"},
+    "VICTORY_RIGHT": {"action": "LEGREST_EXTEND", "utterance": "副驾驶腿托伸出一点"},
+    "VICTORY_LEFT": {"action": "LEGREST_RETRACT", "utterance": "副驾驶腿托收回一点"},
+}
+
+
+class GestureCapabilityBridge:
+    """Expose the repository-owned gesture assets to the browser runtime."""
+
+    def __init__(self, repository_root: Path, asset_root: Path | None = None) -> None:
+        self.repository_root = repository_root.resolve()
+        self.asset_root = (
+            asset_root or self.repository_root / "apps" / "web-console" / "assets" / "gesture"
+        ).resolve()
+        self.config_path = self.repository_root / "config" / "gesture" / "default.yaml"
+        self.model_path = self.asset_root / "gesture_recognizer.task"
+
+    @property
+    def available(self) -> bool:
+        return self.config_path.is_file() and self.model_path.is_file()
+
+    def runtime_info(self) -> dict[str, Any]:
+        recognition: dict[str, Any] = {}
+        if self.config_path.is_file():
+            try:
+                payload = yaml.safe_load(self.config_path.read_text(encoding="utf-8")) or {}
+                recognition = dict(payload.get("recognition", {}))
+            except (OSError, TypeError, ValueError, yaml.YAMLError):
+                recognition = {}
+        defaults = {
+            "action_hold_ms": 600,
+            "min_action_frames": 8,
+            "arm_hold_ms": 1000,
+            "armed_idle_timeout_ms": 3000,
+            "max_continuous_motion_ms": 1500,
+            "neutral_release_ms": 350,
+        }
+        safety = {name: int(recognition.get(name, value)) for name, value in defaults.items()}
+        return {
+            "available": self.available,
+            "model_available": self.model_path.is_file(),
+            "source": "cognitive-agent-bundled-assets",
+            "asset_strategy": "bundled",
+            "safety": safety,
+            "actions": DEFAULT_ACTION_COPY,
+        }

src/cognitive_agent/application/model_plan_adapter.py

@@ -0,0 +1,532 @@
+"""Translate a generic model plan into domain adapter inputs without semantic rewriting."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+import re
+from typing import Any
+
+from cognitive_agent.application.seat_calibration import (
+    ANGLE_CALIBRATIONS,
+    angle_to_position_pct,
+)
+
+
+SEAT_CAPABILITIES = {
+    "seat.set_ventilation": "ventilation",
+    "seat.set_heating": "heating",
+}
+SEAT_MOTION_CAPABILITIES = {
+    "seat.set_longitudinal_position": "longitudinal",
+    "seat.set_cushion_tilt": "cushion_tilt",
+    "seat.set_backrest_recline": "backrest_recline",
+    "seat.set_legrest_height": "legrest_height",
+    "seat.set_legrest_extension": "legrest_extension",
+}
+SAVE_PRESET_CAPABILITY = "seat.save_posture_preset"
+APPLY_PRESET_CAPABILITY = "seat.apply_posture_preset"
+HEX_COLOR = re.compile(r"^#[0-9A-Fa-f]{6}$")
+
+
+class ModelPlanAdapter:
+    """Perform structural capability routing; user-intent decisions remain model-owned."""
+
+    def __init__(self, capability_context: dict[str, Any]) -> None:
+        self.capabilities: dict[str, tuple[str, str, dict[str, Any]]] = {}
+        for domain in capability_context.get("domains", []):
+            for capability in domain.get("capabilities", []):
+                self.capabilities[capability["name"]] = (
+                    domain["domain"],
+                    domain["availability"],
+                    capability,
+                )
+
+    def adapt(
+        self,
+        plan: dict[str, Any],
+        context: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        actions: list[dict[str, Any]] = []
+        domain_actions: list[dict[str, Any]] = []
+        deferred: list[dict[str, Any]] = []
+        preset_actions: list[dict[str, Any]] = []
+        preset_events: list[dict[str, Any]] = []
+        ambiguities = list(plan.get("ambiguities", []))
+        context = context or {}
+
+        for index, request in enumerate(plan.get("requests", [])):
+            capability_name = str(request.get("capability"))
+            registered = self.capabilities.get(capability_name)
+            if registered is None or registered[0] != request.get("domain"):
+                ambiguities.append(
+                    {
+                        "field": f"requests[{index}].capability",
+                        "question": "模型请求的领域与能力注册表不一致。",
+                    }
+                )
+                continue
+
+            domain, availability, capability = registered
+            parameters = {
+                str(item["name"]): item.get("value")
+                for item in request.get("parameters", [])
+            }
+            allowed_parameters = {item["name"] for item in capability.get("parameters", [])}
+            unknown_parameters = set(parameters) - allowed_parameters
+            if unknown_parameters:
+                ambiguities.append(
+                    {
+                        "field": f"requests[{index}].parameters",
+                        "question": (
+                            f"能力 {capability_name} 不支持参数 "
+                            f"{', '.join(sorted(unknown_parameters))}。"
+                        ),
+                    }
+                )
+                continue
+
+            if availability != "executable":
+                values = [value for value in parameters.values() if value is not None]
+                deferred.append(
+                    {
+                        "domain": domain,
+                        "capability": capability_name,
+                        "target_scope": request["target_scope"],
+                        "desired_change": request["operation"],
+                        "requested_value": values[0] if len(values) == 1 else None,
+                        "parameters": parameters,
+                        "reason": request["reason"],
+                    }
+                )
+                continue
+
+            if domain != "seat":
+                generic_action = self._generic_action(
+                    index,
+                    request,
+                    parameters,
+                    capability,
+                    ambiguities,
+                )
+                if generic_action is not None:
+                    domain_actions.append(generic_action)
+                continue
+            if capability_name == SAVE_PRESET_CAPABILITY:
+                preset_action = self._preset_action(
+                    index, request, parameters, ambiguities
+                )
+                if preset_action is not None:
+                    preset_actions.append(preset_action)
+                continue
+            if capability_name == APPLY_PRESET_CAPABILITY:
+                preset_action = self._preset_action(
+                    index, request, parameters, ambiguities
+                )
+                if preset_action is None:
+                    continue
+                preset = self._find_preset(
+                    context.get("presets", []),
+                    preset_action["target"],
+                    preset_action["preset_name"],
+                )
+                if preset is None:
+                    available = [
+                        str(item.get("name"))
+                        for item in context.get("presets", [])
+                        if item.get("target") == preset_action["target"]
+                    ]
+                    suffix = (
+                        f"当前可用预设：{', '.join(available)}。"
+                        if available
+                        else "当前座位尚未保存任何预设。"
+                    )
+                    ambiguities.append(
+                        {
+                            "field": f"requests[{index}].parameters.preset_name",
+                            "question": (
+                                f"未找到 {preset_action['target']} 的预设"
+                                f"“{preset_action['preset_name']}”。{suffix}"
+                            ),
+                        }
+                    )
+                    continue
+                for operation in preset["function_preset"]["spec"]["operations"]:
+                    operation_parameters = dict(operation["parameters"])
+                    action = self._seat_action(
+                        index,
+                        {
+                            "capability": operation["capability"],
+                            "target_scope": preset_action["target"],
+                            "operation": "set",
+                        },
+                        operation_parameters,
+                        ambiguities,
+                        context,
+                    )
+                    if action is not None:
+                        actions.append(action)
+                preset_events.append(
+                    {
+                        "action": "apply",
+                        "target": preset_action["target"],
+                        "preset_name": preset_action["preset_name"],
+                    }
+                )
+                continue
+            action = self._seat_action(
+                index, request, parameters, ambiguities, context
+            )
+            if action is not None:
+                actions.append(action)
+
+        return {
+            "detected_domains": list(plan.get("detected_domains", ["seat"])),
+            "actions": actions,
+            "domain_actions": domain_actions,
+            "preset_actions": preset_actions,
+            "preset_events": preset_events,
+            "deferred_requests": deferred,
+            "ambiguities": ambiguities,
+            "decision_summary": list(plan.get("decision_summary", [])),
+            "confidence": float(plan.get("confidence", 0)),
+            "model_requests": deepcopy(plan.get("requests", [])),
+        }
+
+    @staticmethod
+    def _generic_action(
+        index: int,
+        request: dict[str, Any],
+        parameters: dict[str, Any],
+        capability: dict[str, Any],
+        ambiguities: list[dict[str, str]],
+    ) -> dict[str, Any] | None:
+        target = request.get("target_scope")
+        if target not in capability.get("target_scopes", []):
+            ambiguities.append(
+                {
+                    "field": f"requests[{index}].target_scope",
+                    "question": (
+                        f"{request['capability']} 不支持目标范围 {target!r}。"
+                    ),
+                }
+            )
+            return None
+
+        parameter_specs = {
+            item["name"]: item for item in capability.get("parameters", [])
+        }
+        state_spec = parameter_specs.get("state")
+        if state_spec is not None and parameters.get("state") is None:
+            inferred_state = {
+                "activate": "on",
+                "deactivate": "off",
+            }.get(request.get("operation"))
+            if inferred_state is not None:
+                parameters["state"] = inferred_state
+
+        for name, spec in parameter_specs.items():
+            value = parameters.get(name)
+            if spec.get("required") and value is None:
+                ambiguities.append(
+                    {
+                        "field": f"requests[{index}].parameters.{name}",
+                        "question": (
+                            f"{request['capability']} 需要模型给出参数 {name} 的绝对目标值。"
+                        ),
+                    }
+                )
+                return None
+            if value is None:
+                continue
+            expected_type = spec.get("type")
+            numeric = (
+                isinstance(value, (int, float))
+                and not isinstance(value, bool)
+            )
+            type_valid = {
+                "number": numeric,
+                "integer": numeric and float(value).is_integer(),
+                "string": isinstance(value, str),
+                "boolean": isinstance(value, bool),
+                "object": isinstance(value, dict),
+                "array": isinstance(value, list),
+            }.get(str(expected_type), False)
+            if not type_valid:
+                ambiguities.append(
+                    {
+                        "field": f"requests[{index}].parameters.{name}",
+                        "question": f"参数 {name} 的类型必须是 {expected_type}。",
+                    }
+                )
+                return None
+            if numeric and (
+                ("minimum" in spec and float(value) < float(spec["minimum"]))
+                or ("maximum" in spec and float(value) > float(spec["maximum"]))
+            ):
+                ambiguities.append(
+                    {
+                        "field": f"requests[{index}].parameters.{name}",
+                        "question": (
+                            f"参数 {name} 必须位于 "
+                            f"{spec.get('minimum', '-∞')} 到 {spec.get('maximum', '+∞')} 之间。"
+                        ),
+                    }
+                )
+                return None
+            if spec.get("allowed_values") and value not in spec["allowed_values"]:
+                ambiguities.append(
+                    {
+                        "field": f"requests[{index}].parameters.{name}",
+                        "question": (
+                            f"参数 {name} 必须是 "
+                            f"{', '.join(map(str, spec['allowed_values']))} 之一。"
+                        ),
+                    }
+                )
+                return None
+            if name == "color_hex" and not HEX_COLOR.fullmatch(str(value)):
+                ambiguities.append(
+                    {
+                        "field": f"requests[{index}].parameters.color_hex",
+                        "question": "氛围灯颜色必须是 #RRGGBB 格式。",
+                    }
+                )
+                return None
+
+        normalized = {}
+        for name, value in parameters.items():
+            spec = parameter_specs[name]
+            normalized[name] = (
+                int(value)
+                if spec.get("type") == "integer"
+                else value.upper()
+                if name == "color_hex"
+                else value
+            )
+        return {
+            "domain": request["domain"],
+            "capability": request["capability"],
+            "target": str(target),
+            "parameters": normalized,
+            "operation": request.get("operation", "set"),
+            "reason": request.get("reason", ""),
+        }
+
+    @staticmethod
+    def _preset_action(
+        index: int,
+        request: dict[str, Any],
+        parameters: dict[str, Any],
+        ambiguities: list[dict[str, str]],
+    ) -> dict[str, str] | None:
+        target = request.get("target_scope")
+        if target not in {"driver", "passenger"}:
+            ambiguities.append(
+                {
+                    "field": f"requests[{index}].target_scope",
+                    "question": "座椅姿态预设需要明确主驾或副驾。",
+                }
+            )
+            return None
+        preset_name = parameters.get("preset_name")
+        if (
+            not isinstance(preset_name, str)
+            or not preset_name.strip()
+            or len(preset_name.strip()) > 64
+        ):
+            ambiguities.append(
+                {
+                    "field": f"requests[{index}].parameters.preset_name",
+                    "question": "保存或调用座椅姿态预设需要提供 1-64 个字符的名称。",
+                }
+            )
+            return None
+        return {"target": target, "preset_name": preset_name.strip()}
+
+    @staticmethod
+    def _find_preset(
+        presets: list[dict[str, Any]],
+        target: str,
+        preset_name: str,
+    ) -> dict[str, Any] | None:
+        expected = preset_name.casefold()
+        return next(
+            (
+                preset
+                for preset in presets
+                if preset.get("target") == target
+                and str(preset.get("name", "")).casefold() == expected
+            ),
+            None,
+        )
+
+    @staticmethod
+    def _seat_action(
+        index: int,
+        request: dict[str, Any],
+        parameters: dict[str, Any],
+        ambiguities: list[dict[str, str]],
+        context: dict[str, Any],
+    ) -> dict[str, Any] | None:
+        target = request.get("target_scope")
+        if target not in {"driver", "passenger"}:
+            ambiguities.append(
+                {
+                    "field": f"requests[{index}].target_scope",
+                    "question": "座椅执行适配器需要 driver 或 passenger 目标。",
+                }
+            )
+            return None
+
+        capability = request["capability"]
+        if capability in SEAT_MOTION_CAPABILITIES:
+            axis = SEAT_MOTION_CAPABILITIES[capability]
+            angle = parameters.get("angle_deg")
+            if angle is not None and capability in ANGLE_CALIBRATIONS:
+                calibration = ANGLE_CALIBRATIONS[capability]
+                if (
+                    not isinstance(angle, (int, float))
+                    or isinstance(angle, bool)
+                    or not calibration.minimum_deg <= float(angle) <= calibration.maximum_deg
+                ):
+                    ambiguities.append(
+                        {
+                            "field": f"requests[{index}].parameters.angle_deg",
+                            "question": (
+                                f"{capability} 的夹角必须在 "
+                                f"{calibration.minimum_deg:g}-{calibration.maximum_deg:g} 度之间。"
+                            ),
+                        }
+                    )
+                    return None
+                exact_angle: int | float = (
+                    int(angle) if float(angle).is_integer() else float(angle)
+                )
+                action = {
+                    "action_type": "position",
+                    "target": target,
+                    "axis": axis,
+                    "position_pct": angle_to_position_pct(capability, float(angle)),
+                    "angle_deg": exact_angle,
+                }
+                return ModelPlanAdapter._preserve_relative_motion(
+                    index, request, action, context, ambiguities
+                )
+            position = parameters.get("position_pct")
+            if (
+                not isinstance(position, (int, float))
+                or isinstance(position, bool)
+                or not float(position).is_integer()
+                or not 0 <= float(position) <= 100
+            ):
+                ambiguities.append(
+                    {
+                        "field": f"requests[{index}].parameters.position_pct",
+                        "question": "座椅位置动作需要模型给出 0-100 的绝对整数目标。",
+                    }
+                )
+                return None
+            action = {
+                "action_type": "position",
+                "target": target,
+                "axis": axis,
+                "position_pct": int(position),
+            }
+            return ModelPlanAdapter._preserve_relative_motion(
+                index, request, action, context, ambiguities
+            )
+
+        state = parameters.get("state")
+        if state is None:
+            state = {"activate": "on", "deactivate": "off"}.get(request.get("operation"))
+        if state not in {"on", "off"}:
+            ambiguities.append(
+                {
+                    "field": f"requests[{index}].parameters.state",
+                    "question": "座椅动作需要明确的 on/off 目标状态。",
+                }
+            )
+            return None
+
+        level = parameters.get("level")
+        return {
+            "target": target,
+            "function": SEAT_CAPABILITIES[capability],
+            "state": state,
+            "requested_level": (
+                int(level)
+                if isinstance(level, (int, float)) and not isinstance(level, bool)
+                else None
+            ),
+        }
+
+    @staticmethod
+    def _preserve_relative_motion(
+        index: int,
+        request: dict[str, Any],
+        action: dict[str, Any],
+        context: dict[str, Any],
+        ambiguities: list[dict[str, str]],
+    ) -> dict[str, Any] | None:
+        """Keep the model's relative intent after it resolves an absolute target.
+
+        The absolute target remains the public capability value.  This context is
+        also needed by the hardware compiler to choose the bounded timed/Hall path
+        when the controller has not yet acquired an absolute endpoint calibration.
+        """
+
+        requested_operation = str(request.get("operation", "set"))
+        if requested_operation not in {"increase", "decrease"}:
+            return action
+
+        target = str(action["target"])
+        axis = str(action["axis"])
+        previous = (
+            context.get("devices", {})
+            .get(target, {})
+            .get("position", {})
+            .get(axis)
+        )
+        if not isinstance(previous, dict):
+            return action
+        start_position = previous.get("position_pct")
+        if not isinstance(start_position, (int, float)) or isinstance(
+            start_position, bool
+        ):
+            return action
+
+        target_position = int(action["position_pct"])
+        signed_delta = target_position - int(start_position)
+        expected_sign = 1 if requested_operation == "increase" else -1
+        if signed_delta * expected_sign < 0:
+            ambiguities.append(
+                {
+                    "field": f"requests[{index}].operation",
+                    "question": (
+                        "模型给出的相对移动方向与其解析出的绝对目标相互矛盾，"
+                        "无法安全生成电机方向。"
+                    ),
+                }
+            )
+            return None
+
+        motion_intent: dict[str, Any] = {
+            "mode": "relative",
+            "direction": requested_operation,
+            "start_position_pct": int(start_position),
+            "delta_position_pct": abs(signed_delta),
+        }
+        start_angle = previous.get("angle_deg")
+        target_angle = action.get("angle_deg")
+        if (
+            isinstance(start_angle, (int, float))
+            and not isinstance(start_angle, bool)
+            and isinstance(target_angle, (int, float))
+            and not isinstance(target_angle, bool)
+        ):
+            motion_intent["start_angle_deg"] = float(start_angle)
+            motion_intent["delta_angle_deg"] = abs(
+                float(target_angle) - float(start_angle)
+            )
+        action["motion_intent"] = motion_intent
+        return action

src/cognitive_agent/application/seat_calibration.py

@@ -0,0 +1,51 @@
+"""Virtual seat posture calibration shared by planning and state handling."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AngleCalibration:
+    axis: str
+    minimum_deg: float
+    maximum_deg: float
+
+
+ANGLE_CALIBRATIONS = {
+    "seat.set_backrest_recline": AngleCalibration(
+        axis="backrest_recline",
+        minimum_deg=95,
+        maximum_deg=140,
+    ),
+    "seat.set_legrest_height": AngleCalibration(
+        axis="legrest_height",
+        minimum_deg=95,
+        maximum_deg=160,
+    ),
+}
+AXIS_ANGLE_CALIBRATIONS = {
+    calibration.axis: calibration for calibration in ANGLE_CALIBRATIONS.values()
+}
+
+
+def angle_to_position_pct(capability: str, angle_deg: float) -> int:
+    calibration = ANGLE_CALIBRATIONS[capability]
+    normalized = (
+        (float(angle_deg) - calibration.minimum_deg)
+        / (calibration.maximum_deg - calibration.minimum_deg)
+    )
+    return round(normalized * 100)
+
+
+def position_pct_to_angle(axis: str, position_pct: float) -> float | None:
+    calibration = AXIS_ANGLE_CALIBRATIONS.get(axis)
+    if calibration is None:
+        return None
+    return round(
+        calibration.minimum_deg
+        + (calibration.maximum_deg - calibration.minimum_deg)
+        * float(position_pct)
+        / 100,
+        1,
+    )

src/cognitive_agent/auth.py

@@ -0,0 +1,226 @@
+"""Authentication and abuse controls for the public demo server."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import getpass
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import time
+from collections import defaultdict, deque
+from dataclasses import dataclass
+from threading import RLock
+
+
+PASSWORD_SCHEME = "pbkdf2_sha256"
+PASSWORD_ITERATIONS = 600_000
+
+
+def _b64encode(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).decode("ascii").rstrip("=")
+
+
+def _b64decode(value: str) -> bytes:
+    return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
+
+
+def hash_password(
+    password: str,
+    *,
+    salt: bytes | None = None,
+    iterations: int = PASSWORD_ITERATIONS,
+) -> str:
+    if len(password) < 12:
+        raise ValueError("demo password must contain at least 12 characters")
+    salt = salt or secrets.token_bytes(16)
+    digest = hashlib.pbkdf2_hmac(
+        "sha256",
+        password.encode("utf-8"),
+        salt,
+        iterations,
+    )
+    return f"{PASSWORD_SCHEME}${iterations}${_b64encode(salt)}${_b64encode(digest)}"
+
+
+def verify_password(password: str, encoded: str) -> bool:
+    try:
+        scheme, iteration_text, salt_text, digest_text = encoded.split("$", 3)
+        if scheme != PASSWORD_SCHEME:
+            return False
+        iterations = int(iteration_text)
+        if not 100_000 <= iterations <= 2_000_000:
+            return False
+        expected = _b64decode(digest_text)
+        actual = hashlib.pbkdf2_hmac(
+            "sha256",
+            password.encode("utf-8"),
+            _b64decode(salt_text),
+            iterations,
+        )
+        return hmac.compare_digest(actual, expected)
+    except (ValueError, TypeError):
+        return False
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+@dataclass(frozen=True)
+class AuthConfig:
+    enabled: bool
+    username: str
+    password_hash: str
+    session_secret: bytes
+    session_ttl_seconds: int
+    login_attempts: int
+    login_window_seconds: int
+    requests_per_minute: int
+    trust_proxy_headers: bool
+    cookie_name: str = "cognitive_agent_session"
+
+    @classmethod
+    def from_env(cls) -> AuthConfig:
+        enabled = _env_bool("DEMO_AUTH_ENABLED")
+        username = os.getenv("DEMO_AUTH_USERNAME", "").strip()
+        password_hash = os.getenv("DEMO_AUTH_PASSWORD_HASH", "").strip()
+        secret_text = os.getenv("DEMO_AUTH_SESSION_SECRET", "").strip()
+        if enabled:
+            if not username or len(username) > 64:
+                raise RuntimeError("DEMO_AUTH_USERNAME must contain 1-64 characters")
+            if not password_hash.startswith(f"{PASSWORD_SCHEME}$"):
+                raise RuntimeError("DEMO_AUTH_PASSWORD_HASH is missing or unsupported")
+            if len(secret_text) < 43:
+                raise RuntimeError("DEMO_AUTH_SESSION_SECRET must contain at least 43 characters")
+        return cls(
+            enabled=enabled,
+            username=username,
+            password_hash=password_hash,
+            session_secret=secret_text.encode("utf-8"),
+            session_ttl_seconds=max(
+                300,
+                min(int(os.getenv("DEMO_AUTH_SESSION_TTL_SECONDS", "28800")), 604800),
+            ),
+            login_attempts=max(
+                1,
+                min(int(os.getenv("DEMO_AUTH_LOGIN_ATTEMPTS", "5")), 20),
+            ),
+            login_window_seconds=max(
+                60,
+                min(int(os.getenv("DEMO_AUTH_LOGIN_WINDOW_SECONDS", "300")), 3600),
+            ),
+            requests_per_minute=max(
+                1,
+                min(int(os.getenv("DEMO_REQUESTS_PER_MINUTE", "10")), 120),
+            ),
+            trust_proxy_headers=_env_bool("DEMO_TRUST_PROXY_HEADERS"),
+        )
+
+
+class SessionCodec:
+    def __init__(self, config: AuthConfig) -> None:
+        self.config = config
+
+    def issue(self, username: str, now: int | None = None) -> str:
+        now = int(time.time()) if now is None else now
+        payload = {
+            "sub": username,
+            "iat": now,
+            "exp": now + self.config.session_ttl_seconds,
+            "nonce": secrets.token_urlsafe(12),
+        }
+        encoded = _b64encode(
+            json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
+        )
+        signature = _b64encode(
+            hmac.new(self.config.session_secret, encoded.encode("ascii"), hashlib.sha256).digest()
+        )
+        return f"{encoded}.{signature}"
+
+    def verify(self, token: str, now: int | None = None) -> str | None:
+        if not token or len(token) > 2048:
+            return None
+        try:
+            encoded, signature = token.split(".", 1)
+            expected = _b64encode(
+                hmac.new(
+                    self.config.session_secret,
+                    encoded.encode("ascii"),
+                    hashlib.sha256,
+                ).digest()
+            )
+            if not hmac.compare_digest(signature, expected):
+                return None
+            payload = json.loads(_b64decode(encoded))
+            current_time = int(time.time()) if now is None else now
+            if payload.get("sub") != self.config.username:
+                return None
+            if not int(payload.get("iat", 0)) <= current_time < int(payload.get("exp", 0)):
+                return None
+            return str(payload["sub"])
+        except (ValueError, TypeError, json.JSONDecodeError):
+            return None
+
+
+class SlidingWindowLimiter:
+    def __init__(self, limit: int, window_seconds: int) -> None:
+        self.limit = limit
+        self.window_seconds = window_seconds
+        self._events: dict[str, deque[float]] = defaultdict(deque)
+        self._lock = RLock()
+
+    def retry_after(self, key: str, now: float | None = None) -> int:
+        current = time.monotonic() if now is None else now
+        with self._lock:
+            events = self._events[key]
+            cutoff = current - self.window_seconds
+            while events and events[0] <= cutoff:
+                events.popleft()
+            if len(events) < self.limit:
+                return 0
+            return max(1, int(self.window_seconds - (current - events[0]) + 0.999))
+
+    def record(self, key: str, now: float | None = None) -> None:
+        current = time.monotonic() if now is None else now
+        with self._lock:
+            self._events[key].append(current)
+
+    def clear(self, key: str) -> None:
+        with self._lock:
+            self._events.pop(key, None)
+
+
+class AuthRuntime:
+    def __init__(self, config: AuthConfig) -> None:
+        self.config = config
+        self.sessions = SessionCodec(config)
+        self.login_failures = SlidingWindowLimiter(
+            config.login_attempts,
+            config.login_window_seconds,
+        )
+        self.api_requests = SlidingWindowLimiter(config.requests_per_minute, 60)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Cognitive Agent authentication utilities")
+    parser.add_argument("command", choices=["hash-password", "generate-secret"])
+    args = parser.parse_args()
+    if args.command == "generate-secret":
+        print(secrets.token_urlsafe(48))
+        return
+    password = getpass.getpass("Demo password: ")
+    confirmation = getpass.getpass("Confirm password: ")
+    if password != confirmation:
+        raise SystemExit("Passwords do not match")
+    print(hash_password(password))
+
+
+if __name__ == "__main__":
+    main()

src/cognitive_agent/config_loader.py

@@ -0,0 +1,23 @@
+"""Load local development environment variables without external dependencies."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def load_local_env(path: Path) -> None:
+    if not path.is_file():
+        return
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if value[:1] == value[-1:] and value.startswith(("'", '"')):
+            value = value[1:-1]
+        if key:
+            os.environ.setdefault(key, value)
+

src/cognitive_agent/infrastructure/README.md

@@ -0,0 +1,4 @@
+# Infrastructure
+
+中央外部适配器实现。这里可以依赖供应商 SDK、文件系统、网络和硬件驱动，但通过 application/runtime 定义的端口向内提供能力。
+

src/cognitive_agent/infrastructure/can/README.md

@@ -0,0 +1,5 @@
+# CAN Infrastructure
+
+公共 CAN Gateway 负责加载 DBC、编码 message/signal、选择总线、限速、发送、订阅回读和记录审计。默认实现使用虚拟总线；只有平台 manifest、部署环境和权限同时允许时才能启用硬件 backend。
+
+T2G 座椅台架新增 `PythonCanBus` 和 `ZlgCanBridgeBus`。后者使用 ZCANPRO 自带的 32 位 Python 隔离加载 `zlgcan.dll`，主服务仍运行在 64 位 Python。硬件执行要求环境开关、请求授权令牌、固件 profile、适配器依赖、目标座椅和标定状态全部通过；详见 [T2G 台架接入](../../../docs/workflows/t2g-seat-hardware-bench.md)。

src/cognitive_agent/infrastructure/can/__init__.py

@@ -0,0 +1,17 @@
+"""CAN matrix infrastructure shared by executable domain adapters."""
+
+from .matrix import CanMatrix, MatrixError
+from .gateway import CanBus, CanFrame, CanGatewayError, PythonCanBus, ZlgCanBridgeBus
+from .hardware import HardwareSafetyError, SeatHardwareSettings
+
+__all__ = [
+    "CanBus",
+    "CanFrame",
+    "CanGatewayError",
+    "CanMatrix",
+    "HardwareSafetyError",
+    "MatrixError",
+    "PythonCanBus",
+    "SeatHardwareSettings",
+    "ZlgCanBridgeBus",
+]

src/cognitive_agent/infrastructure/can/gateway.py

@@ -0,0 +1,209 @@
+"""Small CAN transport abstraction used by approved hardware executors."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+
+class CanGatewayError(RuntimeError):
+    """Raised when a CAN adapter cannot be opened or used safely."""
+
+
+@dataclass(frozen=True)
+class CanFrame:
+    arbitration_id: int
+    data: bytes
+    timestamp: float | None = None
+
+    def public(self) -> dict[str, Any]:
+        return {
+            "frame_id": f"0x{self.arbitration_id:03X}",
+            "payload_size": len(self.data),
+            "data_hex": " ".join(f"{byte:02X}" for byte in self.data),
+            "timestamp": self.timestamp,
+        }
+
+
+class CanBus(Protocol):
+    def send(self, arbitration_id: int, data: bytes) -> CanFrame: ...
+
+    def receive(self, timeout_ms: int) -> CanFrame | None: ...
+
+    def close(self) -> None: ...
+
+
+class PythonCanBus:
+    """Adapter for SocketCAN, PCAN and Vector through the optional python-can package."""
+
+    def __init__(self, interface: str, channel: str, bitrate: int):
+        try:
+            import can  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise CanGatewayError(
+                "python-can is not installed; install the project 'can' extra"
+            ) from exc
+        self._can = can
+        try:
+            self._bus = can.Bus(
+                interface=interface,
+                channel=channel,
+                bitrate=bitrate,
+                fd=False,
+            )
+        except Exception as exc:  # noqa: BLE001 - normalize vendor exceptions
+            raise CanGatewayError(f"cannot open {interface} CAN channel {channel}: {exc}") from exc
+
+    def send(self, arbitration_id: int, data: bytes) -> CanFrame:
+        if len(data) > 8:
+            raise CanGatewayError("the T2G bench accepts classic CAN frames of at most 8 bytes")
+        message = self._can.Message(
+            arbitration_id=arbitration_id,
+            data=data,
+            is_extended_id=False,
+            is_fd=False,
+        )
+        try:
+            self._bus.send(message, timeout=0.5)
+        except Exception as exc:  # noqa: BLE001
+            raise CanGatewayError(f"CAN transmit failed: {exc}") from exc
+        return CanFrame(arbitration_id, bytes(data))
+
+    def receive(self, timeout_ms: int) -> CanFrame | None:
+        try:
+            message = self._bus.recv(max(0, timeout_ms) / 1000)
+        except Exception as exc:  # noqa: BLE001
+            raise CanGatewayError(f"CAN receive failed: {exc}") from exc
+        if message is None:
+            return None
+        return CanFrame(
+            int(message.arbitration_id),
+            bytes(message.data),
+            float(message.timestamp) if message.timestamp is not None else None,
+        )
+
+    def close(self) -> None:
+        self._bus.shutdown()
+
+
+class ZlgCanBridgeBus:
+    """Use the installed 32-bit ZLG driver from the 64-bit application process."""
+
+    def __init__(
+        self,
+        python_executable: Path,
+        bridge_script: Path,
+        dll_path: Path,
+        device_type: int,
+        device_index: int,
+        channel: int,
+        bitrate: int,
+    ):
+        command = [
+            str(python_executable),
+            str(bridge_script),
+            "--dll",
+            str(dll_path),
+            "--device-type",
+            str(device_type),
+            "--device-index",
+            str(device_index),
+            "--channel",
+            str(channel),
+            "--bitrate",
+            str(bitrate),
+        ]
+        try:
+            self._process = subprocess.Popen(  # noqa: S603 - paths are trusted server config
+                command,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                bufsize=1,
+            )
+        except OSError as exc:
+            raise CanGatewayError(f"cannot start ZLG CAN bridge: {exc}") from exc
+        self._lock = threading.Lock()
+        ready = self._read_response()
+        if ready.get("event") != "ready":
+            self.close()
+            raise CanGatewayError(str(ready.get("message", "ZLG CAN bridge did not start")))
+
+    def _read_response(self) -> dict[str, Any]:
+        if self._process.stdout is None:
+            raise CanGatewayError("ZLG CAN bridge stdout is unavailable")
+        line = self._process.stdout.readline()
+        if not line:
+            error = ""
+            if self._process.stderr is not None:
+                error = self._process.stderr.read().strip()
+            raise CanGatewayError(error or "ZLG CAN bridge exited unexpectedly")
+        try:
+            response = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise CanGatewayError(f"invalid ZLG CAN bridge response: {line!r}") from exc
+        if response.get("ok") is False:
+            raise CanGatewayError(str(response.get("message", "ZLG CAN operation failed")))
+        return response
+
+    def _request(self, payload: dict[str, Any]) -> dict[str, Any]:
+        with self._lock:
+            if self._process.poll() is not None or self._process.stdin is None:
+                raise CanGatewayError("ZLG CAN bridge is not running")
+            self._process.stdin.write(json.dumps(payload, separators=(",", ":")) + "\n")
+            self._process.stdin.flush()
+            return self._read_response()
+
+    def send(self, arbitration_id: int, data: bytes) -> CanFrame:
+        response = self._request(
+            {
+                "operation": "send",
+                "arbitration_id": arbitration_id,
+                "data_hex": data.hex(),
+            }
+        )
+        return CanFrame(
+            int(response["arbitration_id"]),
+            bytes.fromhex(response["data_hex"]),
+        )
+
+    def receive(self, timeout_ms: int) -> CanFrame | None:
+        response = self._request(
+            {"operation": "receive", "timeout_ms": max(0, int(timeout_ms))}
+        )
+        frame = response.get("frame")
+        if frame is None:
+            return None
+        return CanFrame(
+            int(frame["arbitration_id"]),
+            bytes.fromhex(frame["data_hex"]),
+            float(frame["timestamp_us"]) / 1_000_000,
+        )
+
+    def close(self) -> None:
+        process = getattr(self, "_process", None)
+        if process is None or process.poll() is not None:
+            return
+        try:
+            if process.stdin is not None:
+                process.stdin.write('{"operation":"close"}\n')
+                process.stdin.flush()
+            process.wait(timeout=2)
+        except (OSError, subprocess.TimeoutExpired):
+            process.terminate()
+            try:
+                process.wait(timeout=1)
+            except subprocess.TimeoutExpired:
+                process.kill()
+
+    def __enter__(self) -> "ZlgCanBridgeBus":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()

src/cognitive_agent/infrastructure/can/hardware.py

@@ -0,0 +1,391 @@
+"""Configuration and fail-closed gates for the T2G seat hardware bench."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from cognitive_agent.infrastructure.firmware import (
+    EXPECTED_IDENTITY_PAYLOAD,
+    FirmwareProgrammingError,
+    T2GFirmwareGuard,
+    T2GSeatProgrammer,
+)
+
+from .gateway import CanBus, CanGatewayError, PythonCanBus, ZlgCanBridgeBus
+
+
+TRUE_VALUES = {"1", "true", "yes", "on"}
+VALID_PROFILES = {"combined"}
+SHARED_PHYSICAL_TARGETS = {
+    ("front_left", "driver"),
+    ("front_right", "passenger"),
+}
+CAPABILITY_PROFILE = {
+    "seat.set_heating": "combined",
+    "seat.set_ventilation": "combined",
+    "seat.set_longitudinal_position": "combined",
+    "seat.set_backrest_recline": "combined",
+    "seat.set_legrest_height": "combined",
+    "seat.set_legrest_extension": "combined",
+}
+
+
+class HardwareSafetyError(ValueError):
+    """Raised before any CAN device is opened when a safety gate fails."""
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    return default if value is None else value.strip().lower() in TRUE_VALUES
+
+
+def _env_int(name: str, default: int) -> int:
+    value = os.getenv(name)
+    if value is None or not value.strip():
+        return default
+    try:
+        return int(value, 0)
+    except ValueError as exc:
+        raise HardwareSafetyError(f"{name} must be an integer") from exc
+
+
+def _profiles_from_env() -> frozenset[str]:
+    raw = os.getenv(
+        "COGNITIVE_AGENT_SEAT_FIRMWARE_PROFILES",
+        os.getenv("COGNITIVE_AGENT_SEAT_FIRMWARE_PROFILE", ""),
+    )
+    profiles = frozenset(
+        item.strip().lower() for item in raw.replace(";", ",").split(",") if item.strip()
+    )
+    invalid = profiles - VALID_PROFILES
+    if invalid:
+        raise HardwareSafetyError(
+            "unknown seat firmware profile(s): " + ", ".join(sorted(invalid))
+        )
+    return profiles
+
+
+@dataclass(frozen=True)
+class SeatHardwareSettings:
+    """Environment-owned hardware configuration; secrets are never made public."""
+
+    repository_root: Path
+    enabled: bool
+    approval_token: str
+    profiles: frozenset[str]
+    backend: str
+    bitrate: int
+    channel: str
+    interface: str
+    device_type: int
+    device_index: int
+    zlg_python: Path
+    zlg_dll: Path
+    bridge_script: Path
+    sdk_root: Path
+    cspybat: Path
+    auto_flash_enabled: bool
+    firmware_probe_timeout_ms: int
+    firmware_boot_wait_ms: int
+    firmware_program_timeout_ms: int
+    allow_unverified_longitudinal: bool
+    thermal_timeout_ms: int
+    ack_timeout_ms: int
+    firmware_images: dict[str, Path]
+    firmware_debug_files: dict[str, Path]
+    firmware_macro_files: dict[str, Path]
+
+    @classmethod
+    def from_env(cls, repository_root: Path) -> "SeatHardwareSettings":
+        sdk_root = Path(
+            os.getenv(
+                "COGNITIVE_AGENT_T2G_SDK_ROOT",
+                r"C:\Users\D30042075206\Desktop\T2G_Sample_Driver_Library_7.9.0",
+            )
+        ).expanduser()
+        backend = os.getenv("COGNITIVE_AGENT_SEAT_CAN_BACKEND", "zlgcan").strip().lower()
+        if backend not in {"zlgcan", "python-can"}:
+            raise HardwareSafetyError(
+                "COGNITIVE_AGENT_SEAT_CAN_BACKEND must be zlgcan or python-can"
+            )
+        firmware_root = (
+            repository_root / "firmware" / "t2g" / "Seat_Controller_demo"
+        )
+        images = {
+            "combined": firmware_root
+            / "IAR"
+            / "rev_d"
+            / "Exe"
+            / "Seat_Controller_demo.hex",
+        }
+        debug_files = {
+            "combined": firmware_root
+            / "IAR"
+            / "rev_d"
+            / "Exe"
+            / "Seat_Controller_demo.out",
+        }
+        macro_files = {
+            "combined": firmware_root / "IAR" / "Seat_Controller_program.mac",
+        }
+        return cls(
+            repository_root=repository_root,
+            enabled=_env_bool("COGNITIVE_AGENT_HARDWARE_EXECUTION_ENABLED"),
+            approval_token=os.getenv("COGNITIVE_AGENT_HARDWARE_APPROVAL_TOKEN", ""),
+            profiles=_profiles_from_env(),
+            backend=backend,
+            bitrate=_env_int("COGNITIVE_AGENT_SEAT_CAN_BITRATE", 500_000),
+            channel=os.getenv("COGNITIVE_AGENT_SEAT_CAN_CHANNEL", "0").strip(),
+            interface=os.getenv("COGNITIVE_AGENT_SEAT_CAN_INTERFACE", "socketcan").strip(),
+            device_type=_env_int("COGNITIVE_AGENT_ZLGCAN_DEVICE_TYPE", 41),
+            device_index=_env_int("COGNITIVE_AGENT_ZLGCAN_DEVICE_INDEX", 0),
+            zlg_python=Path(
+                os.getenv(
+                    "COGNITIVE_AGENT_ZLGCAN_PYTHON",
+                    r"C:\Program Files (x86)\ZCANPRO\python38\python.exe",
+                )
+            ),
+            zlg_dll=Path(
+                os.getenv(
+                    "COGNITIVE_AGENT_ZLGCAN_DLL",
+                    r"C:\Program Files (x86)\ZCANPRO\zlgcan.dll",
+                )
+            ),
+            bridge_script=repository_root
+            / "src"
+            / "cognitive_agent"
+            / "infrastructure"
+            / "can"
+            / "zlgcan_bridge.py",
+            sdk_root=sdk_root,
+            cspybat=Path(
+                os.getenv(
+                    "COGNITIVE_AGENT_IAR_CSPYBAT",
+                    r"D:\Program Files\IAR Systems\Embedded Workbench 9.2\common\bin\cspybat.exe",
+                )
+            ),
+            auto_flash_enabled=_env_bool("COGNITIVE_AGENT_SEAT_AUTO_FLASH_ENABLED"),
+            firmware_probe_timeout_ms=_env_int(
+                "COGNITIVE_AGENT_SEAT_FIRMWARE_PROBE_TIMEOUT_MS", 750
+            ),
+            firmware_boot_wait_ms=_env_int(
+                "COGNITIVE_AGENT_SEAT_FIRMWARE_BOOT_WAIT_MS", 1_500
+            ),
+            firmware_program_timeout_ms=_env_int(
+                "COGNITIVE_AGENT_SEAT_FIRMWARE_PROGRAM_TIMEOUT_MS", 120_000
+            ),
+            allow_unverified_longitudinal=_env_bool(
+                "COGNITIVE_AGENT_ENABLE_UNVERIFIED_LONGITUDINAL"
+            ),
+            thermal_timeout_ms=_env_int(
+                "COGNITIVE_AGENT_SEAT_THERMAL_TIMEOUT_MS", 2_000
+            ),
+            ack_timeout_ms=_env_int("COGNITIVE_AGENT_SEAT_ACK_TIMEOUT_MS", 1_500),
+            firmware_images=images,
+            firmware_debug_files=debug_files,
+            firmware_macro_files=macro_files,
+        )
+
+    @property
+    def adapter_configured(self) -> bool:
+        if self.bitrate != 500_000:
+            return False
+        if self.backend == "zlgcan":
+            return (
+                self.zlg_python.is_file()
+                and self.zlg_dll.is_file()
+                and self.bridge_script.is_file()
+            )
+        return bool(self.interface and self.channel)
+
+    @property
+    def configured(self) -> bool:
+        return bool(
+            self.enabled
+            and self.approval_token
+            and self.profiles
+            and self.adapter_configured
+            and all(self.firmware_images[item].is_file() for item in self.profiles)
+            and (not self.auto_flash_enabled or self.programmer_configured)
+        )
+
+    @property
+    def programmer_configured(self) -> bool:
+        if not self.profiles:
+            return False
+        try:
+            return all(self._programmer(item).configured for item in self.profiles)
+        except (FirmwareProgrammingError, OSError):
+            return False
+
+    def authorize(self, supplied_token: str | None) -> None:
+        if not self.enabled:
+            raise HardwareSafetyError(
+                "hardware execution is disabled; set COGNITIVE_AGENT_HARDWARE_EXECUTION_ENABLED=true"
+            )
+        if not self.approval_token:
+            raise HardwareSafetyError(
+                "COGNITIVE_AGENT_HARDWARE_APPROVAL_TOKEN is not configured"
+            )
+        if not supplied_token or not hmac.compare_digest(
+            supplied_token, self.approval_token
+        ):
+            raise HardwareSafetyError("hardware approval token is invalid")
+        if not self.profiles:
+            raise HardwareSafetyError(
+                "the combined IAR seat-controller firmware profile is not selected"
+            )
+        if self.bitrate != 500_000:
+            raise HardwareSafetyError("the verified T2G seat protocol requires 500000 bit/s")
+        if not self.adapter_configured:
+            raise HardwareSafetyError("the configured CAN adapter runtime is not ready")
+        missing = [
+            str(self.firmware_images[item])
+            for item in self.profiles
+            if not self.firmware_images[item].is_file()
+        ]
+        if missing:
+            raise HardwareSafetyError(
+                "selected IAR firmware image is missing: " + ", ".join(missing)
+            )
+        if self.auto_flash_enabled and not self.programmer_configured:
+            raise HardwareSafetyError(
+                "automatic seat-firmware programming is enabled but IAR C-SPY, "
+                "the repository OUT image, or the C-SPY macro is unavailable"
+            )
+
+    def validate_function_config(self, function_config: dict[str, Any]) -> None:
+        operations = function_config.get("spec", {}).get("operations", [])
+        if not operations:
+            raise HardwareSafetyError("hardware execution requires at least one seat operation")
+        physical_requests: dict[str, dict[str, Any]] = {}
+        for operation in operations:
+            capability = str(operation.get("capability", ""))
+            target = operation.get("target", {})
+            target_key = (str(target.get("zone", "")), str(target.get("instance", "")))
+            if target_key not in SHARED_PHYSICAL_TARGETS:
+                raise HardwareSafetyError(
+                    "the T2G bench accepts driver/front_left and passenger/front_right; "
+                    "both aliases operate the same physical seat actuators"
+                )
+            try:
+                profile = CAPABILITY_PROFILE[capability]
+            except KeyError as exc:
+                raise HardwareSafetyError(
+                    f"the T2G IAR firmware does not implement {capability}"
+                ) from exc
+            if profile not in self.profiles:
+                raise HardwareSafetyError(
+                    f"{capability} requires the '{profile}' firmware profile"
+                )
+            parameters = dict(operation.get("parameters", {}))
+            previous = physical_requests.get(capability)
+            if previous is not None and previous != parameters:
+                raise HardwareSafetyError(
+                    f"driver and passenger requests conflict for shared physical capability {capability}"
+                )
+            physical_requests[capability] = parameters
+            if (
+                capability == "seat.set_longitudinal_position"
+                and not self.allow_unverified_longitudinal
+            ):
+                raise HardwareSafetyError(
+                    "longitudinal Motor3 is unwired/unverified; explicitly set "
+                    "COGNITIVE_AGENT_ENABLE_UNVERIFIED_LONGITUDINAL=true only after calibration"
+                )
+
+    def bus_factory(self) -> Callable[[], CanBus]:
+        if self.backend == "zlgcan":
+            try:
+                numeric_channel = int(self.channel, 0)
+            except ValueError as exc:
+                raise CanGatewayError(
+                    "ZLG CAN channel must be an integer such as 0"
+                ) from exc
+
+            def create_zlg_bus() -> CanBus:
+                return ZlgCanBridgeBus(
+                    python_executable=self.zlg_python,
+                    bridge_script=self.bridge_script,
+                    dll_path=self.zlg_dll,
+                    device_type=self.device_type,
+                    device_index=self.device_index,
+                    channel=numeric_channel,
+                    bitrate=self.bitrate,
+                )
+
+            return create_zlg_bus
+
+        def create_python_can_bus() -> CanBus:
+            return PythonCanBus(
+                interface=self.interface,
+                channel=self.channel,
+                bitrate=self.bitrate,
+            )
+
+        return create_python_can_bus
+
+    def _programmer(self, profile: str = "combined") -> T2GSeatProgrammer:
+        return T2GSeatProgrammer(
+            cspybat=self.cspybat,
+            debug_file=self.firmware_debug_files[profile],
+            hex_image=self.firmware_images[profile],
+            macro_file=self.firmware_macro_files[profile],
+            timeout_ms=self.firmware_program_timeout_ms,
+        )
+
+    def firmware_guard(self) -> T2GFirmwareGuard:
+        return T2GFirmwareGuard(
+            self.bus_factory(),
+            self._programmer() if self.auto_flash_enabled else None,
+            auto_flash=self.auto_flash_enabled,
+            probe_timeout_ms=self.firmware_probe_timeout_ms,
+            boot_wait_ms=self.firmware_boot_wait_ms,
+        )
+
+    def public_info(self) -> dict[str, Any]:
+        images = {}
+        for profile, path in self.firmware_images.items():
+            exists = path.is_file()
+            images[profile] = {
+                "exists": exists,
+                "filename": path.name,
+                "sha256": (
+                    hashlib.sha256(path.read_bytes()).hexdigest() if exists else None
+                ),
+            }
+        return {
+            "enabled": self.enabled,
+            "configured": self.configured,
+            "approval_required": True,
+            "approval_configured": bool(self.approval_token),
+            "platform": "t2g_seat_bench",
+            "backend": self.backend,
+            "adapter_configured": self.adapter_configured,
+            "channel": self.channel,
+            "bitrate": self.bitrate,
+            "frame_format": "classic_can_11_bit",
+            "firmware_profiles": sorted(self.profiles),
+            "firmware_images": images,
+            "firmware_status": "identity_verified_before_each_hardware_request",
+            "firmware_identity": EXPECTED_IDENTITY_PAYLOAD.hex(" ").upper(),
+            "firmware_source": "repository",
+            "auto_flash_enabled": self.auto_flash_enabled,
+            "programmer_configured": self.programmer_configured,
+            "programmer_backend": "iar_cspy_cmsisdap",
+            "supported_targets": ["front_left", "front_right"],
+            "physical_target": "t2g_primary_seat",
+            "target_aliasing": "driver_and_passenger_share_one_physical_actuator_group",
+            "unverified_longitudinal_enabled": self.allow_unverified_longitudinal,
+            "limitations": [
+                "hardware execution requires the unified Seat_Controller_demo image on one development board",
+                "driver and passenger commands are aliases for the same physical motor/heater/fan group",
+                "Motor3 longitudinal motion stays blocked until explicitly enabled after wiring and calibration",
+                "cushion tilt has no physical actuator in Seat_Move_demo",
+            ],
+        }

src/cognitive_agent/infrastructure/can/matrix.py

@@ -0,0 +1,69 @@
+"""Load and encode a normalized virtual CAN matrix."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class MatrixError(ValueError):
+    """Raised when a signal cannot be represented by a normalized matrix."""
+
+
+class CanMatrix:
+    """Small LSB0/Intel encoder used only by the dry-run execution path."""
+
+    def __init__(self, matrix_path: Path):
+        self.path = matrix_path
+        self.data = yaml.safe_load(matrix_path.read_text(encoding="utf-8"))
+        self.messages = {item["name"]: item for item in self.data["messages"]}
+
+    @property
+    def hardware_execution_allowed(self) -> bool:
+        return self.data.get("hardware_execution_allowed") is True
+
+    def message(self, name: str) -> dict[str, Any]:
+        try:
+            return self.messages[name]
+        except KeyError as exc:
+            raise MatrixError(f"Unknown matrix message: {name}") from exc
+
+    def signal(self, message_name: str, signal_name: str) -> dict[str, Any]:
+        for signal in self.message(message_name)["signals"]:
+            if signal["name"] == signal_name:
+                return signal
+        raise MatrixError(f"Unknown signal {signal_name} in {message_name}")
+
+    def encode(self, message_name: str, values: dict[str, int]) -> dict[str, Any]:
+        message = self.message(message_name)
+        encoded_values = dict(message.get("fixed_signals", {}))
+        encoded_values.update(values)
+        raw_value = 0
+        for signal_name, value in encoded_values.items():
+            signal = self.signal(message_name, signal_name)
+            width = int(signal["bit_length"])
+            if (
+                not isinstance(value, int)
+                or isinstance(value, bool)
+                or value < 0
+                or value >= 1 << width
+            ):
+                raise MatrixError(
+                    f"Value {value!r} does not fit {signal_name}[{width}]"
+                )
+            start_bit = int(signal["start_bit"])
+            mask = ((1 << width) - 1) << start_bit
+            raw_value = (raw_value & ~mask) | (value << start_bit)
+
+        payload_size = int(message["minimum_payload_bytes"])
+        payload = raw_value.to_bytes(payload_size, byteorder="little", signed=False)
+        return {
+            "message": message_name,
+            "frame_id": f"0x{int(message['frame_id']):03X}",
+            "payload_size": payload_size,
+            "data_hex": " ".join(f"{byte:02X}" for byte in payload),
+            "signals": encoded_values,
+            "encoding": "lsb0/intel inferred for virtual execution",
+        }

src/cognitive_agent/infrastructure/can/zlgcan_bridge.py

@@ -0,0 +1,309 @@
+"""32-bit JSON-line bridge for the ZLG zlgcan.dll API.
+
+This module deliberately has no project or third-party imports so it can run under
+the 32-bit Python bundled with ZCANPRO while the web service uses 64-bit Python.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ctypes
+import json
+import sys
+
+
+ZCAN_TYPE_CANFD = 1
+ZCAN_STATUS_OK = 1
+
+
+class ZcanClassicInit(ctypes.Structure):
+    _fields_ = [
+        ("acc_code", ctypes.c_uint32),
+        ("acc_mask", ctypes.c_uint32),
+        ("reserved", ctypes.c_uint32),
+        ("filter", ctypes.c_uint8),
+        ("timing0", ctypes.c_uint8),
+        ("timing1", ctypes.c_uint8),
+        ("mode", ctypes.c_uint8),
+    ]
+
+
+class ZcanFdInit(ctypes.Structure):
+    _fields_ = [
+        ("acc_code", ctypes.c_uint32),
+        ("acc_mask", ctypes.c_uint32),
+        ("abit_timing", ctypes.c_uint32),
+        ("dbit_timing", ctypes.c_uint32),
+        ("brp", ctypes.c_uint32),
+        ("filter", ctypes.c_uint8),
+        ("mode", ctypes.c_uint8),
+        ("pad", ctypes.c_uint16),
+        ("reserved", ctypes.c_uint32),
+    ]
+
+
+class ZcanInitUnion(ctypes.Union):
+    _fields_ = [("can", ZcanClassicInit), ("canfd", ZcanFdInit)]
+
+
+class ZcanChannelInit(ctypes.Structure):
+    _anonymous_ = ("config",)
+    _fields_ = [("can_type", ctypes.c_uint32), ("config", ZcanInitUnion)]
+
+
+class ZcanFrame(ctypes.Structure):
+    _fields_ = [
+        ("can_id", ctypes.c_uint32),
+        ("can_dlc", ctypes.c_uint8),
+        ("pad", ctypes.c_uint8),
+        ("reserved0", ctypes.c_uint8),
+        ("reserved1", ctypes.c_uint8),
+        ("data", ctypes.c_uint8 * 8),
+    ]
+
+
+class ZcanTransmitData(ctypes.Structure):
+    _fields_ = [("frame", ZcanFrame), ("transmit_type", ctypes.c_uint32)]
+
+
+class ZcanReceiveData(ctypes.Structure):
+    _fields_ = [("frame", ZcanFrame), ("timestamp", ctypes.c_uint64)]
+
+
+class ZcanChannelErrorInfo(ctypes.Structure):
+    _fields_ = [
+        ("error_code", ctypes.c_uint32),
+        ("passive_error_data", ctypes.c_uint8 * 3),
+        ("arbitration_lost_error_data", ctypes.c_uint8),
+    ]
+
+
+def emit(value):
+    print(json.dumps(value, ensure_ascii=False, separators=(",", ":")), flush=True)
+
+
+class Driver:
+    def __init__(self, args):
+        self.transmit_type = args.transmit_type
+        self.dll = ctypes.WinDLL(args.dll)
+        self._declare_functions()
+        self.device = self.dll.ZCAN_OpenDevice(
+            args.device_type, args.device_index, 0
+        )
+        if not self.device:
+            raise RuntimeError(
+                "ZCAN_OpenDevice failed; connect the adapter and close ZCANPRO first"
+            )
+        self.channel = None
+        try:
+            bitrate = str(args.bitrate).encode("ascii")
+            channel_prefix = str(args.channel)
+            path = (channel_prefix + "/canfd_abit_baud_rate").encode("ascii")
+            if self.dll.ZCAN_SetValue(self.device, path, bitrate) != ZCAN_STATUS_OK:
+                raise RuntimeError("ZCAN_SetValue(canfd_abit_baud_rate) failed")
+            data_path = (channel_prefix + "/canfd_dbit_baud_rate").encode("ascii")
+            if self.dll.ZCAN_SetValue(self.device, data_path, b"2000000") != ZCAN_STATUS_OK:
+                raise RuntimeError("ZCAN_SetValue(canfd_dbit_baud_rate) failed")
+            init = ZcanChannelInit()
+            # USBCANFD devices require a CANFD channel handle even when the
+            # application only transmits classic CAN frames through ZCAN_Transmit.
+            init.can_type = ZCAN_TYPE_CANFD
+            init.canfd.acc_code = 0
+            init.canfd.acc_mask = 0xFFFFFFFF
+            init.canfd.filter = 0
+            init.canfd.mode = 0
+            self.channel = self.dll.ZCAN_InitCAN(
+                self.device, args.channel, ctypes.byref(init)
+            )
+            if not self.channel:
+                raise RuntimeError("ZCAN_InitCAN failed")
+            if self.dll.ZCAN_StartCAN(self.channel) != ZCAN_STATUS_OK:
+                raise RuntimeError("ZCAN_StartCAN failed")
+            self.dll.ZCAN_ClearBuffer(self.channel)
+        except Exception:
+            self.close()
+            raise
+
+    def _declare_functions(self):
+        handle = ctypes.c_void_p
+        self.dll.ZCAN_OpenDevice.argtypes = [
+            ctypes.c_uint32,
+            ctypes.c_uint32,
+            ctypes.c_uint32,
+        ]
+        self.dll.ZCAN_OpenDevice.restype = handle
+        self.dll.ZCAN_CloseDevice.argtypes = [handle]
+        self.dll.ZCAN_CloseDevice.restype = ctypes.c_uint32
+        self.dll.ZCAN_SetValue.argtypes = [handle, ctypes.c_char_p, ctypes.c_char_p]
+        self.dll.ZCAN_SetValue.restype = ctypes.c_uint32
+        self.dll.ZCAN_InitCAN.argtypes = [
+            handle,
+            ctypes.c_uint32,
+            ctypes.POINTER(ZcanChannelInit),
+        ]
+        self.dll.ZCAN_InitCAN.restype = handle
+        self.dll.ZCAN_StartCAN.argtypes = [handle]
+        self.dll.ZCAN_StartCAN.restype = ctypes.c_uint32
+        self.dll.ZCAN_ResetCAN.argtypes = [handle]
+        self.dll.ZCAN_ResetCAN.restype = ctypes.c_uint32
+        self.dll.ZCAN_ClearBuffer.argtypes = [handle]
+        self.dll.ZCAN_ClearBuffer.restype = ctypes.c_uint32
+        self.dll.ZCAN_ReadChannelErrInfo.argtypes = [
+            handle,
+            ctypes.POINTER(ZcanChannelErrorInfo),
+        ]
+        self.dll.ZCAN_ReadChannelErrInfo.restype = ctypes.c_uint32
+        self.dll.ZCAN_Transmit.argtypes = [
+            handle,
+            ctypes.POINTER(ZcanTransmitData),
+            ctypes.c_uint32,
+        ]
+        self.dll.ZCAN_Transmit.restype = ctypes.c_uint32
+        self.dll.ZCAN_Receive.argtypes = [
+            handle,
+            ctypes.POINTER(ZcanReceiveData),
+            ctypes.c_uint32,
+            ctypes.c_int32,
+        ]
+        self.dll.ZCAN_Receive.restype = ctypes.c_uint32
+
+    def send(self, arbitration_id, data):
+        if not 0 <= arbitration_id <= 0x7FF:
+            raise ValueError("only 11-bit standard CAN identifiers are allowed")
+        if len(data) > 8:
+            raise ValueError("classic CAN payload exceeds 8 bytes")
+        transmit = ZcanTransmitData()
+        transmit.frame.can_id = arbitration_id
+        transmit.frame.can_dlc = len(data)
+        for index, byte in enumerate(data):
+            transmit.frame.data[index] = byte
+        transmit.transmit_type = self.transmit_type
+        if self.dll.ZCAN_Transmit(self.channel, ctypes.byref(transmit), 1) != 1:
+            error = ZcanChannelErrorInfo()
+            read_ok = self.dll.ZCAN_ReadChannelErrInfo(
+                self.channel, ctypes.byref(error)
+            )
+            detail = (
+                f"; channel_error=0x{error.error_code:08X}"
+                if read_ok == ZCAN_STATUS_OK
+                else "; channel error info unavailable"
+            )
+            raise RuntimeError("ZCAN_Transmit did not accept the frame" + detail)
+
+    def receive(self, timeout_ms):
+        receive = ZcanReceiveData()
+        count = self.dll.ZCAN_Receive(
+            self.channel, ctypes.byref(receive), 1, int(timeout_ms)
+        )
+        if count == 0:
+            return None
+        if count != 1:
+            raise RuntimeError("ZCAN_Receive returned an unexpected frame count")
+        frame = receive.frame
+        return {
+            "arbitration_id": int(frame.can_id & 0x1FFFFFFF),
+            "data_hex": bytes(frame.data[: frame.can_dlc]).hex(),
+            "timestamp_us": int(receive.timestamp),
+        }
+
+    def close(self):
+        if self.channel:
+            self.dll.ZCAN_ResetCAN(self.channel)
+            self.channel = None
+        if self.device:
+            self.dll.ZCAN_CloseDevice(self.device)
+            self.device = None
+
+
+def parse_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dll", required=True)
+    parser.add_argument("--device-type", type=int, required=True)
+    parser.add_argument("--device-index", type=int, default=0)
+    parser.add_argument("--channel", type=int, default=0)
+    parser.add_argument("--bitrate", type=int, default=500000)
+    parser.add_argument(
+        "--transmit-type",
+        type=int,
+        choices=(0, 2),
+        default=0,
+        help="0 for normal transmission; 2 is diagnostic self-reception",
+    )
+    parser.add_argument("--self-test", action="store_true")
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+    if args.self_test:
+        dll = ctypes.WinDLL(args.dll)
+        required = (
+            "ZCAN_OpenDevice",
+            "ZCAN_CloseDevice",
+            "ZCAN_SetValue",
+            "ZCAN_InitCAN",
+            "ZCAN_StartCAN",
+            "ZCAN_Transmit",
+            "ZCAN_Receive",
+        )
+        missing = [name for name in required if not hasattr(dll, name)]
+        emit(
+            {
+                "ok": not missing,
+                "pointer_bits": ctypes.sizeof(ctypes.c_void_p) * 8,
+                "missing_exports": missing,
+                "structure_sizes": {
+                    "init": ctypes.sizeof(ZcanChannelInit),
+                    "frame": ctypes.sizeof(ZcanFrame),
+                    "tx": ctypes.sizeof(ZcanTransmitData),
+                    "rx": ctypes.sizeof(ZcanReceiveData),
+                    "error": ctypes.sizeof(ZcanChannelErrorInfo),
+                },
+            }
+        )
+        return 0 if not missing else 1
+
+    driver = None
+    try:
+        driver = Driver(args)
+        emit({"ok": True, "event": "ready"})
+        for line in sys.stdin:
+            try:
+                request = json.loads(line)
+                operation = request.get("operation")
+                if operation == "send":
+                    arbitration_id = int(request["arbitration_id"])
+                    data = bytes.fromhex(request["data_hex"])
+                    driver.send(arbitration_id, data)
+                    emit(
+                        {
+                            "ok": True,
+                            "arbitration_id": arbitration_id,
+                            "data_hex": data.hex(),
+                        }
+                    )
+                elif operation == "receive":
+                    emit(
+                        {
+                            "ok": True,
+                            "frame": driver.receive(int(request.get("timeout_ms", 0))),
+                        }
+                    )
+                elif operation == "close":
+                    emit({"ok": True})
+                    break
+                else:
+                    raise ValueError("unknown bridge operation")
+            except Exception as exc:
+                emit({"ok": False, "message": str(exc)})
+    except Exception as exc:
+        emit({"ok": False, "event": "error", "message": str(exc)})
+        return 1
+    finally:
+        if driver is not None:
+            driver.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/cognitive_agent/infrastructure/firmware/__init__.py

@@ -0,0 +1,19 @@
+"""Firmware verification and programming infrastructure."""
+
+from .t2g_seat import (
+    EXPECTED_IDENTITY_PAYLOAD,
+    FIRMWARE_IDENTITY_REQUEST_ID,
+    FIRMWARE_IDENTITY_RESPONSE_ID,
+    FirmwareProgrammingError,
+    T2GFirmwareGuard,
+    T2GSeatProgrammer,
+)
+
+__all__ = [
+    "EXPECTED_IDENTITY_PAYLOAD",
+    "FIRMWARE_IDENTITY_REQUEST_ID",
+    "FIRMWARE_IDENTITY_RESPONSE_ID",
+    "FirmwareProgrammingError",
+    "T2GFirmwareGuard",
+    "T2GSeatProgrammer",
+]

src/cognitive_agent/infrastructure/firmware/t2g_seat.py

@@ -0,0 +1,246 @@
+"""Verify and, when explicitly enabled, program the unified T2G seat firmware."""
+
+from __future__ import annotations
+
+import hashlib
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable
+
+from cognitive_agent.infrastructure.can.gateway import CanBus
+
+
+FIRMWARE_IDENTITY_REQUEST_ID = 0x304
+FIRMWARE_IDENTITY_RESPONSE_ID = 0x305
+FIRMWARE_IDENTITY_REQUEST_PAYLOAD = bytes.fromhex("53 45 41 54 01 00 00 00")
+EXPECTED_IDENTITY_PAYLOAD = bytes.fromhex("53 45 41 54 01 01 00 3F")
+
+
+class FirmwareProgrammingError(RuntimeError):
+    """Raised when firmware identity or an approved programming step fails."""
+
+
+@dataclass(frozen=True)
+class T2GSeatProgrammer:
+    """Run the repository-owned image through IAR C-SPY and CMSIS-DAP."""
+
+    cspybat: Path
+    debug_file: Path
+    hex_image: Path
+    macro_file: Path
+    timeout_ms: int = 120_000
+    launch_handoff_ms: int = 3_000
+
+    @property
+    def iar_root(self) -> Path:
+        try:
+            return self.cspybat.resolve().parents[2]
+        except IndexError as exc:
+            raise FirmwareProgrammingError(
+                f"cannot derive IAR root from {self.cspybat}"
+            ) from exc
+
+    def required_files(self) -> tuple[Path, ...]:
+        arm_root = self.iar_root / "arm"
+        return (
+            self.cspybat,
+            self.debug_file,
+            self.hex_image,
+            self.macro_file,
+            arm_root / "bin" / "armPROC.dll",
+            arm_root / "bin" / "armJET.dll",
+            arm_root / "bin" / "armbat.dll",
+            arm_root / "config" / "debugger" / "Infineon" / "CYT4BF_M0.dmac",
+            arm_root / "config" / "debugger" / "Infineon" / "CYTVII_M0.dmac",
+            arm_root / "config" / "debugger" / "Infineon" / "CYTVII_Common.dmac",
+            arm_root / "config" / "debugger" / "Infineon" / "CYT4BF_M0+.ddf",
+            arm_root / "config" / "debugger" / "Infineon" / "CYT4.ProbeConfig",
+            arm_root
+            / "config"
+            / "flashloader"
+            / "Infineon"
+            / "FlashCYT4_CF8M_WF256K.board",
+        )
+
+    @property
+    def configured(self) -> bool:
+        return all(path.is_file() for path in self.required_files())
+
+    def command(self) -> list[str]:
+        missing = [str(path) for path in self.required_files() if not path.is_file()]
+        if missing:
+            raise FirmwareProgrammingError(
+                "IAR/C-SPY programming dependency is missing: " + ", ".join(missing)
+            )
+        arm_root = self.iar_root / "arm"
+        arm_bin = arm_root / "bin"
+        debugger = arm_root / "config" / "debugger" / "Infineon"
+        return [
+            str(self.cspybat),
+            str(arm_bin / "armPROC.dll"),
+            str(arm_bin / "armJET.dll"),
+            str(self.debug_file),
+            f"--plugin={arm_bin / 'armbat.dll'}",
+            f"--device_macro={debugger / 'CYT4BF_M0.dmac'}",
+            f"--device_macro={debugger / 'CYTVII_M0.dmac'}",
+            f"--device_macro={debugger / 'CYTVII_Common.dmac'}",
+            f"--macro={self.macro_file}",
+            "--flash_loader="
+            + str(
+                arm_root
+                / "config"
+                / "flashloader"
+                / "Infineon"
+                / "FlashCYT4_CF8M_WF256K.board"
+            ),
+            "--leave_target_running",
+            "--silent",
+            "--timeout",
+            str(self.launch_handoff_ms),
+            "--backend",
+            "--endian=little",
+            "--cpu=Cortex-M0+",
+            "--fpu=None",
+            "-p",
+            str(debugger / "CYT4BF_M0+.ddf"),
+            "--semihosting",
+            "--device=CYT4BF_M0+",
+            "--drv_mtb_regbase=0xF0003000",
+            "--drv_mtb_minramaddr=0xF0010000",
+            "--drv_mtb_maxramaddr=0xF0010FFF",
+            "--multicore_nr_of_cores=1",
+            "--jet_probe=cmsisdap",
+            "--jet_standard_reset=4,0,0",
+            "--reset_style=0,-,0,Disabled__no_reset_",
+            "--reset_style=1,-,0,Software",
+            "--reset_style=2,-,0,Hardware",
+            "--reset_style=4,-,1,System",
+            "--reset_style=7,Traveo2_CM0p_ResetAndAcquireDevice,0,Reset_and_halt_after_bootloader",
+            "--drv_interface=SWD",
+            "--drv_catch_exceptions=0xff0",
+            f"--jet_board_cfg={debugger / 'CYT4.ProbeConfig'}",
+        ]
+
+    def program(self) -> dict[str, Any]:
+        command = self.command()
+        try:
+            completed = subprocess.run(  # noqa: S603 - all paths are trusted bench config
+                command,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=max(1, self.timeout_ms // 1000 + 10),
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            raise FirmwareProgrammingError(f"IAR C-SPY programming failed: {exc}") from exc
+        if completed.returncode != 0:
+            detail = (completed.stderr or completed.stdout or "").strip()[-1000:]
+            raise FirmwareProgrammingError(
+                f"IAR C-SPY returned {completed.returncode}: {detail or 'no diagnostic output'}"
+            )
+        return {
+            "backend": "iar_cspy_cmsisdap",
+            "programmed": True,
+            "target_started": True,
+            "image": self.hex_image.name,
+            "image_sha256": hashlib.sha256(self.hex_image.read_bytes()).hexdigest(),
+        }
+
+
+class T2GFirmwareGuard:
+    """Return a CAN bus only after the matching unified firmware has answered."""
+
+    def __init__(
+        self,
+        bus_factory: Callable[[], CanBus],
+        programmer: T2GSeatProgrammer | None,
+        *,
+        auto_flash: bool,
+        probe_timeout_ms: int = 750,
+        boot_wait_ms: int = 1_500,
+    ):
+        self.bus_factory = bus_factory
+        self.programmer = programmer
+        self.auto_flash = auto_flash
+        self.probe_timeout_ms = probe_timeout_ms
+        self.boot_wait_ms = boot_wait_ms
+
+    def _probe(self, bus: CanBus) -> bytes | None:
+        bus.send(FIRMWARE_IDENTITY_REQUEST_ID, FIRMWARE_IDENTITY_REQUEST_PAYLOAD)
+        deadline = time.monotonic() + self.probe_timeout_ms / 1000
+        observed: bytes | None = None
+        while True:
+            remaining_ms = round((deadline - time.monotonic()) * 1000)
+            if remaining_ms <= 0:
+                return observed
+            frame = bus.receive(remaining_ms)
+            if frame is None:
+                return observed
+            if frame.arbitration_id != FIRMWARE_IDENTITY_RESPONSE_ID:
+                continue
+            observed = bytes(frame.data)
+            if observed == EXPECTED_IDENTITY_PAYLOAD:
+                return observed
+
+    def prepare_bus(self) -> tuple[CanBus, dict[str, Any]]:
+        bus = self.bus_factory()
+        probe_error: Exception | None = None
+        try:
+            observed = self._probe(bus)
+        except Exception as exc:  # an unprogrammed target may not ACK the probe
+            observed = None
+            probe_error = exc
+        if observed == EXPECTED_IDENTITY_PAYLOAD:
+            return bus, {
+                "firmware_verified": True,
+                "programmed_this_request": False,
+                "identity_frame_id": f"0x{FIRMWARE_IDENTITY_RESPONSE_ID:03X}",
+                "identity_data_hex": observed.hex(" ").upper(),
+            }
+
+        bus.close()
+        if not self.auto_flash:
+            if probe_error is not None:
+                raise FirmwareProgrammingError(
+                    "Seat_Controller_demo firmware probe failed "
+                    f"({probe_error}); automatic programming is disabled"
+                ) from probe_error
+            actual = observed.hex(" ").upper() if observed is not None else "no response"
+            raise FirmwareProgrammingError(
+                "matching Seat_Controller_demo firmware was not detected "
+                f"({actual}); automatic programming is disabled"
+            )
+        if self.programmer is None:
+            raise FirmwareProgrammingError(
+                "automatic programming is enabled but no IAR programmer is configured"
+            )
+
+        programming = self.programmer.program()
+        time.sleep(self.boot_wait_ms / 1000)
+        verified_bus = self.bus_factory()
+        try:
+            verified = self._probe(verified_bus)
+            if verified != EXPECTED_IDENTITY_PAYLOAD:
+                actual = verified.hex(" ").upper() if verified is not None else "no response"
+                raise FirmwareProgrammingError(
+                    "programming completed but firmware identity verification failed: "
+                    + actual
+                )
+        except Exception as exc:
+            verified_bus.close()
+            if isinstance(exc, FirmwareProgrammingError):
+                raise
+            raise FirmwareProgrammingError(
+                "programming completed but firmware identity probe failed: " + str(exc)
+            ) from exc
+        return verified_bus, {
+            **programming,
+            "firmware_verified": True,
+            "programmed_this_request": True,
+            "identity_frame_id": f"0x{FIRMWARE_IDENTITY_RESPONSE_ID:03X}",
+            "identity_data_hex": EXPECTED_IDENTITY_PAYLOAD.hex(" ").upper(),
+        }

src/cognitive_agent/infrastructure/llm/README.md

@@ -0,0 +1,4 @@
+# LLM Infrastructure
+
+实现模型客户端、结构化输出、超时/重试、模型路由、token/成本度量和脱敏。API Key 只从 Secret/环境变量读取，不写入配置或 artifact。
+

src/cognitive_agent/infrastructure/llm/openai_responses.py

@@ -0,0 +1,363 @@
+"""OpenAI Responses API adapter for capability-grounded intent planning."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+
+def build_intent_schema(capability_context: dict[str, Any]) -> dict[str, Any]:
+    domains = [item["domain"] for item in capability_context.get("domains", [])] or ["seat"]
+    capabilities = [
+        capability["name"]
+        for domain in capability_context.get("domains", [])
+        for capability in domain.get("capabilities", [])
+    ] or ["seat.set_ventilation", "seat.set_heating"]
+    target_scopes = sorted(
+        {
+            scope
+            for domain in capability_context.get("domains", [])
+            for capability in domain.get("capabilities", [])
+            for scope in capability.get("target_scopes", [])
+        }
+        | {"unknown"}
+    )
+    return {
+        "type": "object",
+        "additionalProperties": False,
+        "required": [
+            "detected_domains",
+            "requests",
+            "ambiguities",
+            "decision_summary",
+            "confidence",
+        ],
+        "properties": {
+            "detected_domains": {
+                "type": "array",
+                "minItems": 1,
+                "items": {"type": "string", "enum": domains},
+            },
+            "requests": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "additionalProperties": False,
+                    "required": [
+                        "domain",
+                        "capability",
+                        "target_scope",
+                        "operation",
+                        "parameters",
+                        "reason",
+                    ],
+                    "properties": {
+                        "domain": {"type": "string", "enum": domains},
+                        "capability": {"type": "string", "enum": capabilities},
+                        "target_scope": {"type": "string", "enum": target_scopes},
+                        "operation": {
+                            "type": "string",
+                            "enum": [
+                                "activate",
+                                "deactivate",
+                                "increase",
+                                "decrease",
+                                "set",
+                                "save",
+                                "apply",
+                            ],
+                        },
+                        "parameters": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "additionalProperties": False,
+                                "required": ["name", "value"],
+                                "properties": {
+                                    "name": {"type": "string"},
+                                    "value": {"type": ["string", "number", "boolean", "null"]},
+                                },
+                            },
+                        },
+                        "reason": {"type": "string"},
+                    },
+                },
+            },
+            "ambiguities": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "additionalProperties": False,
+                    "required": ["field", "question"],
+                    "properties": {
+                        "field": {"type": "string"},
+                        "question": {"type": "string"},
+                    },
+                },
+            },
+            "decision_summary": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 6,
+                "items": {"type": "string"},
+            },
+            "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+        },
+    }
+
+SYSTEM_PROMPT = """You are the intent planner for an in-vehicle cognitive orchestration agent.
+
+The capability registry is the source of truth for available domains, capabilities, parameters,
+target scopes, and execution availability. The runtime conversation context is the source of truth
+for current actuator state and prior successful actions.
+
+Interpret the user's goal semantically. Consider causal language, explicit scope, current state,
+follow-up references, and simultaneous compatible goals. Do not classify by isolated keywords.
+Prefer the smallest reversible action that addresses the goal when the user leaves intensity open.
+An explicit scope in the current utterance overrides conversation history.
+When multiple capabilities address the goal equally well, prefer one whose domain is executable.
+Never substitute a materially less suitable capability merely because it is executable.
+
+When execution_policy.planning_environment is dry_run_candidate_synthesis, a named preset is not
+required. For a commonly understood mode, activity, or comfort goal, decompose the goal into the
+registered atomic capabilities and infer conservative absolute targets from their normalized ranges
+and current state. The absence of a named preset is never, by itself, an ambiguity. State inferred
+assumptions in decision_summary. Safety validation and hardware eligibility are downstream concerns;
+do not withhold a dry-run candidate merely because a capability is marked high risk.
+
+Return every understood goal in requests using an exact capability name from the registry. Use
+target_scope and operation to preserve the user's intent. Put concrete capability parameters in the
+parameters list when they are known or defensibly inferred. Do not drop catalog_only requests; the
+runtime router, not the model, decides which domain adapter can execute them.
+For executable capabilities, resolve follow-up and relative intent against runtime state and return
+absolute target parameter values that the adapter can execute. Do not delegate that semantic decision
+to downstream code. Catalog-only requests may remain relative when their current state is unavailable.
+Do not generate CAN frames or signal values.
+When a requested setting requires an inactive device to operate, include its registered power-on
+capability as a separate request. For a cross-domain scene, emit every required atomic request and
+keep each request in its owning domain; do not collapse a scene into a named mode unless the registry
+contains that exact mode capability.
+
+When the user specifies an included angle, preserve that exact semantic value in angle_deg rather
+than replacing it with a guessed motor percentage. The registered angle description defines the two
+surfaces forming the angle and its valid calibration range. Use position_pct for relative motion when
+no exact angle is requested.
+
+Use seat.save_posture_preset only when the user explicitly asks to save, remember, or overwrite the
+current seat posture. Use seat.apply_posture_preset only when the exact named preset exists for that
+target in runtime context. A new named comfort mode without a saved preset must still be synthesized
+from atomic motion capabilities; it must not be treated as an apply request. Saved preset expansion
+and angle-to-position calibration are deterministic downstream operations.
+
+Use ambiguities only when the target scope, requested outcome, or required capability is genuinely
+indeterminate after applying the interaction context. Do not ask the user for motor names, percentages,
+or confirmation of an inferred common-mode decomposition when a conservative dry-run plan is possible.
+decision_summary must contain short auditable facts and defaults, not hidden reasoning or chain-of-thought.
+Return only the requested structured object."""
+
+
+class OpenAIIntentError(RuntimeError):
+    """Safe error raised when the hosted intent adapter cannot return structured output."""
+
+
+class OpenAIIntentInterpreter:
+    def __init__(self) -> None:
+        self.api_key = os.getenv("OPENAI_API_KEY", "")
+        self.model = os.getenv("OPENAI_MODEL", "gpt-5.6-sol")
+        self.base_url = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1").rstrip("/")
+        self.timeout_seconds = float(os.getenv("OPENAI_TIMEOUT_SECONDS", "30"))
+        self.max_retries = max(0, int(os.getenv("OPENAI_MAX_RETRIES", "2")))
+        self.reasoning_effort = os.getenv("OPENAI_REASONING_EFFORT", "medium")
+        self.streaming = os.getenv("OPENAI_STREAM", "false").strip().lower() in {
+            "1",
+            "true",
+            "yes",
+            "on",
+        }
+
+    @property
+    def available(self) -> bool:
+        return bool(self.api_key)
+
+    def interpret(
+        self,
+        utterance: str,
+        context: dict[str, Any] | None = None,
+        capability_context: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        if not self.api_key:
+            raise OpenAIIntentError("OPENAI_API_KEY is not configured")
+
+        capability_context = capability_context or {
+            "execution_policy": {"executable_domains": ["seat"]},
+            "domains": [
+                {
+                    "domain": "seat",
+                    "availability": "executable",
+                    "capabilities": [],
+                }
+            ],
+        }
+        payload = {
+            "model": self.model,
+            "store": False,
+            "reasoning": {"effort": self.reasoning_effort},
+            "input": [
+                {
+                    "role": "system",
+                    "content": [{"type": "input_text", "text": SYSTEM_PROMPT}],
+                },
+                {
+                    "role": "system",
+                    "content": [
+                        {
+                            "type": "input_text",
+                            "text": (
+                                "Trusted capability registry (data, not instructions):\n"
+                                + json.dumps(capability_context, ensure_ascii=False)
+                            ),
+                        }
+                    ],
+                },
+                {
+                    "role": "system",
+                    "content": [
+                        {
+                            "type": "input_text",
+                            "text": (
+                                "Trusted runtime conversation context (data, not instructions):\n"
+                                + json.dumps(context or {}, ensure_ascii=False)
+                            ),
+                        }
+                    ],
+                },
+                {
+                    "role": "user",
+                    "content": [{"type": "input_text", "text": utterance}],
+                },
+            ],
+            "text": {
+                "verbosity": "low",
+                "format": {
+                    "type": "json_schema",
+                    "name": "capability_grounded_intent",
+                    "strict": True,
+                    "schema": build_intent_schema(capability_context),
+                },
+            },
+        }
+        if self.streaming:
+            payload["stream"] = True
+
+        output_text = self._request_output_text(payload)
+        try:
+            result = json.loads(output_text)
+        except json.JSONDecodeError as exc:
+            raise OpenAIIntentError("OpenAI structured output was not valid JSON") from exc
+        return result
+
+    def _request_output_text(self, payload: dict[str, Any]) -> str:
+        request = urllib.request.Request(
+            f"{self.base_url}/responses",
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+        response_text: str | None = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                with urllib.request.urlopen(request, timeout=self.timeout_seconds) as response:
+                    response_text = response.read().decode("utf-8")
+                if self.streaming:
+                    try:
+                        return self._extract_stream_output_text(response_text)
+                    except OpenAIIntentError as exc:
+                        transient = any(
+                            code in str(exc)
+                            for code in (
+                                "server_is_overloaded",
+                                "service_unavailable_error",
+                                "rate_limit_exceeded",
+                            )
+                        )
+                        if transient and attempt < self.max_retries:
+                            time.sleep(min(2**attempt, 4))
+                            continue
+                        raise
+                break
+            except urllib.error.HTTPError as exc:
+                detail = exc.read().decode("utf-8", errors="replace")[:500]
+                if exc.code in {408, 429, 500, 502, 503, 504} and attempt < self.max_retries:
+                    time.sleep(min(2**attempt, 4))
+                    continue
+                raise OpenAIIntentError(
+                    f"OpenAI API returned HTTP {exc.code}: {detail}"
+                ) from exc
+            except (urllib.error.URLError, TimeoutError) as exc:
+                if attempt < self.max_retries:
+                    time.sleep(min(2**attempt, 4))
+                    continue
+                raise OpenAIIntentError(f"OpenAI intent request failed: {exc}") from exc
+
+        if response_text is None:
+            raise OpenAIIntentError("OpenAI intent request exhausted all retries")
+
+        try:
+            body = json.loads(response_text)
+        except json.JSONDecodeError as exc:
+            raise OpenAIIntentError("OpenAI response was not valid JSON") from exc
+        output_text = body.get("output_text") or self._extract_output_text(body)
+        if not output_text:
+            raise OpenAIIntentError("OpenAI response did not contain structured output text")
+        return output_text
+
+    @classmethod
+    def _extract_stream_output_text(cls, response_text: str) -> str:
+        chunks: list[str] = []
+        completed_text: str | None = None
+
+        for line in response_text.splitlines():
+            if not line.startswith("data:"):
+                continue
+            data = line.removeprefix("data:").strip()
+            if not data or data == "[DONE]":
+                continue
+            try:
+                event = json.loads(data)
+            except json.JSONDecodeError as exc:
+                raise OpenAIIntentError("OpenAI stream contained invalid JSON") from exc
+
+            event_type = event.get("type")
+            if event_type == "response.output_text.delta":
+                chunks.append(str(event.get("delta", "")))
+            elif event_type == "response.output_text.done":
+                completed_text = str(event.get("text", ""))
+            elif event_type == "response.completed":
+                completed_text = cls._extract_output_text(event.get("response", {})) or completed_text
+            elif event_type in {"error", "response.failed", "response.incomplete"}:
+                detail = event.get("error") or event.get("response", {}).get("error") or event
+                raise OpenAIIntentError(f"OpenAI stream failed: {detail}")
+
+        output_text = completed_text if completed_text is not None else "".join(chunks)
+        if not output_text:
+            raise OpenAIIntentError("OpenAI stream did not contain structured output text")
+        return output_text
+
+    @staticmethod
+    def _extract_output_text(body: dict[str, Any]) -> str | None:
+        for item in body.get("output", []):
+            if item.get("type") != "message":
+                continue
+            for content in item.get("content", []):
+                if content.get("type") == "output_text":
+                    return content.get("text")
+                if content.get("type") == "refusal":
+                    raise OpenAIIntentError(content.get("refusal", "OpenAI request was refused"))
+        return None

src/cognitive_agent/infrastructure/persistence/README.md

@@ -0,0 +1,4 @@
+# Persistence Infrastructure
+
+保存任务状态、版本化配置、artifact 索引和审计元数据。运行目录只用于开发；生产环境应使用具备保留和访问控制策略的存储。
+

src/cognitive_agent/infrastructure/telemetry/README.md

@@ -0,0 +1,4 @@
+# Telemetry Infrastructure
+
+统一日志、指标、trace 和前端 `TraceEvent` 输出。事件必须脱敏，并区分模型摘要、确定性校验结论和实际执行回读。
+

src/cognitive_agent/orchestration/README.md

@@ -0,0 +1,6 @@
+# Orchestration
+
+阶段二跨域逻辑所在位置：生成/校验 `SceneConfig`、解析 FunctionConfig 引用、检查 DAG、识别资源冲突、应用跨域策略、调度和补偿。
+
+单领域请求应绕过本层的场景规划，直接进入 FunctionConfig runtime。跨域逻辑不得导入任何具体 `*_domain` 包，只通过 Registry/SDK 调用插件。
+

src/cognitive_agent/registry/README.md

@@ -0,0 +1,4 @@
+# Registry
+
+扫描 `domains/*/manifest.yaml` 并注册插件、能力、参数 Schema 和平台支持情况。启动时发现重复 domain、重复 capability、无效 entrypoint 或缺失资源必须失败，不能采用最后写入覆盖。
+

src/cognitive_agent/runtime/README.md

@@ -0,0 +1,11 @@
+# Runtime
+
+实现统一流水线和状态机：
+
+```text
+load -> public_validate -> domain_validate -> compile
+     -> platform_validate -> safety_check -> dry_run/execute -> observe -> report
+```
+
+Runtime 负责超时、取消、幂等键、重试边界、审计和 artifact 写入。真实发送只通过 `infrastructure/can` 的 Gateway；领域插件不能绕过。
+

src/cognitive_agent/runtime/contracts.py

@@ -0,0 +1,76 @@
+"""Runtime validation against the repository's canonical JSON Schemas."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator, FormatChecker, RefResolver
+
+
+KIND_TO_SCHEMA = {
+    "IntentIR": "intent-ir.schema.json",
+    "FunctionConfig": "function-config.schema.json",
+    "FunctionPreset": "function-preset.schema.json",
+    "SceneConfig": "scene-config.schema.json",
+    "CommandPlan": "command-plan.schema.json",
+    "ExecutionReport": "execution-report.schema.json",
+    "TraceEvent": "trace-event.schema.json",
+}
+
+
+class ContractValidator:
+    def __init__(self, repository_root: Path):
+        self.root = repository_root
+        schema_dir = repository_root / "contracts" / "schemas"
+        self.schemas = {
+            path.name: json.loads(path.read_text(encoding="utf-8"))
+            for path in schema_dir.glob("*.json")
+        }
+        self.store = {schema["$id"]: schema for schema in self.schemas.values()}
+        self.format_checker = FormatChecker()
+
+    def validate(self, document: dict[str, Any]) -> list[dict[str, str]]:
+        kind = document.get("kind")
+        schema_name = KIND_TO_SCHEMA.get(str(kind))
+        if schema_name is None:
+            return [
+                {
+                    "severity": "error",
+                    "code": "UNKNOWN_DOCUMENT_KIND",
+                    "path": "kind",
+                    "message": f"No runtime schema registered for {kind!r}",
+                }
+            ]
+        issues = self._validate_with_schema(document, self.schemas[schema_name], "PUBLIC_SCHEMA")
+
+        if kind in {"FunctionConfig", "FunctionPreset"}:
+            domain = document.get("spec", {}).get("domain")
+            domain_path = (
+                self.root / "domains" / str(domain) / "schemas" / "function-parameters.schema.json"
+            )
+            if domain_path.is_file():
+                domain_schema = json.loads(domain_path.read_text(encoding="utf-8"))
+                issues.extend(self._validate_with_schema(document, domain_schema, "DOMAIN_SCHEMA"))
+        return issues
+
+    def _validate_with_schema(
+        self, document: dict[str, Any], schema: dict[str, Any], code: str
+    ) -> list[dict[str, str]]:
+        resolver = RefResolver.from_schema(schema, store=self.store)
+        validator = Draft202012Validator(
+            schema, resolver=resolver, format_checker=self.format_checker
+        )
+        issues = []
+        for error in sorted(validator.iter_errors(document), key=lambda item: list(item.path)):
+            path = ".".join(str(part) for part in error.absolute_path) or "<root>"
+            issues.append(
+                {
+                    "severity": "error",
+                    "code": code,
+                    "path": path,
+                    "message": error.message,
+                }
+            )
+        return issues

src/cognitive_agent/sdk/README.md

@@ -0,0 +1,14 @@
+# Domain SDK
+
+领域插件唯一允许依赖的中央接口。后续在此提供稳定 Protocol 和生成的契约模型：
+
+```text
+DomainPlugin
+├── generate(intent, generation_context) -> FunctionConfig
+├── validate(config, validation_context) -> list[ValidationIssue]
+├── compile(config, compile_context) -> CommandPlan
+└── decode_telemetry(frames, telemetry_context) -> DomainState
+```
+
+接口只传递不可变上下文和契约对象。SDK major 版本变化必须提供领域迁移说明和全量契约测试。
+

src/cognitive_agent/server.py

@@ -0,0 +1,444 @@
+"""Dependency-light HTTP server for the cabin orchestration demo."""
+
+from __future__ import annotations
+
+import argparse
+import hmac
+import ipaddress
+import json
+import mimetypes
+import os
+import re
+import socket
+from http.cookies import CookieError, SimpleCookie
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import quote, unquote, urlparse
+
+from cognitive_agent.config_loader import load_local_env
+
+
+REPOSITORY_ROOT = Path(__file__).resolve().parents[2]
+load_local_env(REPOSITORY_ROOT / ".env")
+load_local_env(REPOSITORY_ROOT / ".env.auth")
+
+from cognitive_agent.auth import AuthConfig, AuthRuntime, verify_password  # noqa: E402
+from cognitive_agent.application.seat_service import SeatDemoService  # noqa: E402
+from cognitive_agent.application.gesture_bridge import GestureCapabilityBridge  # noqa: E402
+from cognitive_agent.infrastructure.can.hardware import HardwareSafetyError  # noqa: E402
+from cognitive_agent.infrastructure.llm.openai_responses import OpenAIIntentError  # noqa: E402
+
+
+STATIC_ROOT = REPOSITORY_ROOT / "apps" / "web-console"
+REQUEST_ID_PATTERN = re.compile(r"^req-[a-z0-9-]+$")
+PUBLIC_AUTH_PATHS = {
+    "/login",
+    "/login.html",
+    "/login.css",
+    "/login.js",
+    "/api/auth/status",
+    "/api/auth/login",
+}
+
+
+def _lan_ipv4_address() -> str | None:
+    """Return the IPv4 address selected by the host's default route."""
+    probe = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        probe.connect(("192.0.2.1", 80))
+        address = str(probe.getsockname()[0])
+        return None if address.startswith("127.") else address
+    except OSError:
+        return None
+    finally:
+        probe.close()
+
+
+class SeatDemoHandler(BaseHTTPRequestHandler):
+    service = SeatDemoService()
+    gesture = GestureCapabilityBridge(REPOSITORY_ROOT)
+    auth = AuthRuntime(AuthConfig.from_env())
+    server_version = "CognitiveAgentCabinDemo/2.0"
+
+    def do_GET(self) -> None:  # noqa: N802 - stdlib handler API
+        path = unquote(urlparse(self.path).path)
+        if path == "/favicon.ico":
+            self.send_response(HTTPStatus.NO_CONTENT)
+            self._send_security_headers()
+            self.end_headers()
+            return
+        if path == "/api/auth/status":
+            username = self._session_username()
+            self._json(
+                {
+                    "enabled": self.auth.config.enabled,
+                    "authenticated": not self.auth.config.enabled or username is not None,
+                    "username": username,
+                    "session_ttl_seconds": self.auth.config.session_ttl_seconds,
+                    "requests_per_minute": self.auth.config.requests_per_minute,
+                }
+            )
+            return
+        if path in {"/login", "/login.html"}:
+            if self.auth.config.enabled and self._session_username() is not None:
+                self._redirect("/")
+                return
+            self._serve_static_file("login.html")
+            return
+        if not self._authorize(path):
+            return
+        if path == "/api/health":
+            self._json({"status": "ok", "service": "cabin-cognitive-orchestrator"})
+            return
+        if path == "/api/runtime":
+            self._json(self.service.runtime_info())
+            return
+        if path == "/api/gesture/runtime":
+            self._json(self.gesture.runtime_info())
+            return
+        if path == "/api/gesture/model":
+            self._serve_gesture_model()
+            return
+        if path.startswith("/api/requests/"):
+            self._serve_request(path.removeprefix("/api/requests/"))
+            return
+        self._serve_static(path)
+
+    def do_POST(self) -> None:  # noqa: N802 - stdlib handler API
+        path = unquote(urlparse(self.path).path)
+        if path == "/api/auth/login":
+            self._login()
+            return
+        if path == "/api/auth/logout":
+            self._logout()
+            return
+        if not self._authorize(path):
+            return
+        if path != "/api/requests":
+            self._json({"error": "not_found"}, HTTPStatus.NOT_FOUND)
+            return
+
+        try:
+            username = self._session_username() or "local"
+            retry_after = self.auth.api_requests.retry_after(username)
+            if self.auth.config.enabled and retry_after:
+                self._json(
+                    {
+                        "error": "rate_limited",
+                        "message": "请求过于频繁，请稍后再试。",
+                    },
+                    HTTPStatus.TOO_MANY_REQUESTS,
+                    {"Retry-After": str(retry_after)},
+                )
+                return
+            if self.auth.config.enabled:
+                self.auth.api_requests.record(username)
+            content_length = int(self.headers.get("Content-Length", "0"))
+            if content_length <= 0 or content_length > 32768:
+                raise ValueError("request body must be between 1 and 32768 bytes")
+            payload = json.loads(self.rfile.read(content_length).decode("utf-8"))
+            if not isinstance(payload, dict):
+                raise ValueError("request body must be a JSON object")
+            result = self.service.process(
+                str(payload.get("utterance", "")),
+                str(payload.get("provider", "auto")),
+                str(payload["conversation_id"]) if payload.get("conversation_id") else None,
+                str(payload.get("execution_mode", "dry_run")),
+                str(payload["approval_token"])
+                if payload.get("approval_token")
+                else None,
+            )
+            self._json(result, HTTPStatus.CREATED)
+        except HardwareSafetyError as exc:
+            self._json(
+                {"error": "hardware_safety_gate", "message": str(exc)},
+                HTTPStatus.FORBIDDEN,
+            )
+        except (ValueError, json.JSONDecodeError) as exc:
+            self._json({"error": "invalid_request", "message": str(exc)}, HTTPStatus.BAD_REQUEST)
+        except OpenAIIntentError as exc:
+            self.log_error("OpenAI intent request failed: %s", exc)
+            self._json(
+                {
+                    "error": "openai_request_failed",
+                    "message": "GPT 意图解析失败，请检查 API Key、模型权限或网络状态。",
+                },
+                HTTPStatus.BAD_GATEWAY,
+            )
+        except Exception as exc:  # noqa: BLE001 - keep the demo API responsive
+            self.log_error("request failed: %s", exc)
+            self._json(
+                {
+                    "error": "internal_error",
+                    "message": "请求处理失败，请查看服务端日志。",
+                },
+                HTTPStatus.INTERNAL_SERVER_ERROR,
+            )
+
+    def _authorize(self, path: str) -> bool:
+        if not self.auth.config.enabled or path in PUBLIC_AUTH_PATHS:
+            return True
+        if self._session_username() is not None:
+            return True
+        if path.startswith("/api/"):
+            self._json(
+                {
+                    "error": "authentication_required",
+                    "message": "请登录后访问。",
+                },
+                HTTPStatus.UNAUTHORIZED,
+            )
+        else:
+            requested = path if path.startswith("/") else "/"
+            self._redirect(f"/login?next={quote(requested, safe='/')}")
+        return False
+
+    def _login(self) -> None:
+        if not self.auth.config.enabled:
+            self._json({"enabled": False, "authenticated": True})
+            return
+        client_key = self._client_key()
+        retry_after = self.auth.login_failures.retry_after(client_key)
+        if retry_after:
+            self._json(
+                {
+                    "error": "login_rate_limited",
+                    "message": "登录尝试过多，请稍后再试。",
+                },
+                HTTPStatus.TOO_MANY_REQUESTS,
+                {"Retry-After": str(retry_after)},
+            )
+            return
+        try:
+            content_length = int(self.headers.get("Content-Length", "0"))
+            if content_length <= 0 or content_length > 4096:
+                raise ValueError("invalid login body")
+            payload = json.loads(self.rfile.read(content_length).decode("utf-8"))
+            if not isinstance(payload, dict):
+                raise ValueError("invalid login body")
+            username = str(payload.get("username", ""))[:128]
+            password = str(payload.get("password", ""))[:1024]
+        except (ValueError, json.JSONDecodeError):
+            self._json(
+                {"error": "invalid_request", "message": "登录请求格式无效。"},
+                HTTPStatus.BAD_REQUEST,
+            )
+            return
+
+        password_valid = verify_password(password, self.auth.config.password_hash)
+        username_valid = hmac.compare_digest(
+            username.encode("utf-8"),
+            self.auth.config.username.encode("utf-8"),
+        )
+        if not (username_valid and password_valid):
+            self.auth.login_failures.record(client_key)
+            self._json(
+                {"error": "invalid_credentials", "message": "用户名或密码错误。"},
+                HTTPStatus.UNAUTHORIZED,
+            )
+            return
+
+        self.auth.login_failures.clear(client_key)
+        token = self.auth.sessions.issue(self.auth.config.username)
+        attributes = [
+            f"{self.auth.config.cookie_name}={token}",
+            "Path=/",
+            "HttpOnly",
+            "SameSite=Strict",
+            f"Max-Age={self.auth.config.session_ttl_seconds}",
+        ]
+        if self._is_https():
+            attributes.append("Secure")
+        self._json(
+            {
+                "authenticated": True,
+                "username": self.auth.config.username,
+            },
+            headers={"Set-Cookie": "; ".join(attributes)},
+        )
+
+    def _logout(self) -> None:
+        attributes = [
+            f"{self.auth.config.cookie_name}=",
+            "Path=/",
+            "HttpOnly",
+            "SameSite=Strict",
+            "Max-Age=0",
+        ]
+        if self._is_https():
+            attributes.append("Secure")
+        self._json(
+            {"authenticated": False},
+            headers={"Set-Cookie": "; ".join(attributes)},
+        )
+
+    def _session_username(self) -> str | None:
+        if not self.auth.config.enabled:
+            return None
+        cookie_header = self.headers.get("Cookie", "")
+        if not cookie_header or len(cookie_header) > 4096:
+            return None
+        try:
+            cookies = SimpleCookie()
+            cookies.load(cookie_header)
+            morsel = cookies.get(self.auth.config.cookie_name)
+            return self.auth.sessions.verify(morsel.value if morsel else "")
+        except (CookieError, ValueError):
+            return None
+
+    def _client_key(self) -> str:
+        address = self.client_address[0]
+        direct_address = ipaddress.ip_address(address)
+        if self.auth.config.trust_proxy_headers and direct_address.is_loopback:
+            forwarded = (
+                self.headers.get("CF-Connecting-IP")
+                or self.headers.get("X-Forwarded-For", "").split(",", 1)[0]
+            ).strip()
+            try:
+                address = str(ipaddress.ip_address(forwarded))
+            except ValueError:
+                pass
+        return address
+
+    def _is_https(self) -> bool:
+        if not self.auth.config.trust_proxy_headers:
+            return False
+        if self.headers.get("X-Forwarded-Proto", "").lower() == "https":
+            return True
+        return '"scheme":"https"' in self.headers.get("CF-Visitor", "").replace(" ", "")
+
+    def _serve_request(self, request_id: str) -> None:
+        if not REQUEST_ID_PATTERN.fullmatch(request_id):
+            self._json({"error": "invalid_request_id"}, HTTPStatus.BAD_REQUEST)
+            return
+        result_path = self.service.artifact_root / request_id / "result.json"
+        if not result_path.is_file():
+            self._json({"error": "not_found"}, HTTPStatus.NOT_FOUND)
+            return
+        self._json(json.loads(result_path.read_text(encoding="utf-8")))
+
+    def _serve_static(self, path: str) -> None:
+        relative_path = "index.html" if path in {"", "/"} else path.lstrip("/")
+        self._serve_static_file(relative_path)
+
+    def _serve_static_file(self, relative_path: str) -> None:
+        candidate = (STATIC_ROOT / relative_path).resolve()
+        try:
+            candidate.relative_to(STATIC_ROOT.resolve())
+        except ValueError:
+            self._json({"error": "not_found"}, HTTPStatus.NOT_FOUND)
+            return
+        if not candidate.is_file():
+            candidate = STATIC_ROOT / "index.html"
+        content_type, _ = mimetypes.guess_type(candidate.name)
+        content = candidate.read_bytes()
+        self.send_response(HTTPStatus.OK)
+        self.send_header("Content-Type", f"{content_type or 'application/octet-stream'}; charset=utf-8")
+        self.send_header("Content-Length", str(len(content)))
+        self.send_header("Cache-Control", "no-store")
+        self._send_security_headers()
+        self.end_headers()
+        self.wfile.write(content)
+
+    def _serve_gesture_model(self) -> None:
+        path = self.gesture.model_path
+        if not path.is_file():
+            self._json(
+                {"error": "gesture_model_unavailable", "message": "手势模型文件不可用。"},
+                HTTPStatus.NOT_FOUND,
+            )
+            return
+        content = path.read_bytes()
+        self.send_response(HTTPStatus.OK)
+        self.send_header("Content-Type", "application/octet-stream")
+        self.send_header("Content-Length", str(len(content)))
+        self.send_header("Cache-Control", "private, max-age=3600")
+        self._send_security_headers()
+        self.end_headers()
+        self.wfile.write(content)
+
+    def _json(
+        self,
+        payload: object,
+        status: HTTPStatus = HTTPStatus.OK,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        content = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(content)))
+        self.send_header("Cache-Control", "no-store")
+        for name, value in (headers or {}).items():
+            self.send_header(name, value)
+        self._send_security_headers()
+        self.end_headers()
+        self.wfile.write(content)
+
+    def _redirect(self, location: str) -> None:
+        self.send_response(HTTPStatus.SEE_OTHER)
+        self.send_header("Location", location)
+        self.send_header("Cache-Control", "no-store")
+        self._send_security_headers()
+        self.end_headers()
+
+    def _send_security_headers(self) -> None:
+        self.send_header("X-Content-Type-Options", "nosniff")
+        self.send_header("X-Frame-Options", "DENY")
+        self.send_header("Referrer-Policy", "no-referrer")
+        self.send_header(
+            "Permissions-Policy",
+            "camera=(self), microphone=(), geolocation=(), payment=(), usb=()",
+        )
+        self.send_header(
+            "Content-Security-Policy",
+            "default-src 'self'; "
+            "script-src 'self' 'wasm-unsafe-eval' https://unpkg.com https://cdn.jsdelivr.net; "
+            "style-src 'self'; "
+            "img-src 'self' data:; "
+            "connect-src 'self' https://cdn.jsdelivr.net; "
+            "object-src 'none'; base-uri 'none'; frame-ancestors 'none'",
+        )
+        if self._is_https():
+            self.send_header(
+                "Strict-Transport-Security",
+                "max-age=31536000; includeSubDomains",
+            )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run the cabin orchestration demo")
+    parser.add_argument("--host", default=os.getenv("HOST", "127.0.0.1"))
+    parser.add_argument("--port", type=int, default=int(os.getenv("PORT", "8000")))
+    args = parser.parse_args()
+    server = ThreadingHTTPServer((args.host, args.port), SeatDemoHandler)
+    if args.host in {"0.0.0.0", "::"}:
+        lan_address = _lan_ipv4_address()
+        print(f"Cabin orchestration demo (local): http://127.0.0.1:{args.port}", flush=True)
+        if lan_address:
+            print(
+                f"Cabin orchestration demo (LAN):   http://{lan_address}:{args.port}",
+                flush=True,
+            )
+        print(
+            "LAN mode: devices on reachable networks can use the GPT-backed API.",
+            flush=True,
+        )
+    else:
+        print(f"Cabin orchestration demo: http://{args.host}:{args.port}", flush=True)
+    hardware = SeatDemoHandler.service.hardware_settings
+    print(
+        "Execution modes: dry_run + hardware "
+        f"({'configured' if hardware.configured else 'locked'})",
+        flush=True,
+    )
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+if __name__ == "__main__":
+    main()