Cognitive_Agent/README.md

# Cognitive Agent

面向车载执行器的认知编排单仓工程。系统把自然语言或结构化请求转换为可校验的语义配置，由领域插件确定性编译为 `CommandPlan`，经过平台安全门禁后以 dry-run、模拟台架或真实 CAN 方式执行，并保存可审计结果。

当前仓库以腾势 N7 / T2G 座舱演示和硬件台架为主。默认环境不会打开真实硬件；气候、天幕和氛围灯领域的矩阵目前也只允许虚拟执行。

## 能做什么

- 同源 Python HTTP 服务与 Vue 3 + Vite Web 控制台。
- 能力目录驱动的自然语言编排、模式卡片、跨域场景和 NDJSON 助手流。
- `IntentIR`、`FunctionConfig`、`SceneConfig`、`CommandPlan`、`TraceEvent` 和 `ExecutionReport` 公共契约。
- 座椅、空调、天幕、氛围灯四个领域插件，以及平台侧门窗、插座、阅读灯等原生 CAN 能力。
- 虚拟 CAN、模拟硬件、T2G ZLG CAN 台架和双通道车身 CAN 接入。
- 语音输入、MediaPipe 手势、NFC/红外外设、模式目录同步和只读固件 OTA 服务。

AI 模型只能提出受契约约束的语义计划，不能生成或发送原始 CAN 帧。真实执行仍由服务端的能力白名单、参数 Schema、硬件授权、安全策略、互斥和反馈检查共同决定。

## 处理链路

```text
用户请求
  -> 能力目录 / 会话状态 / Codex 或本地解析
  -> IntentIR
  -> FunctionConfig（单领域）或 SceneConfig（跨领域）
  -> 公共 Schema + 领域语义校验
  -> 领域 Compiler -> CommandPlan
  -> 平台安全校验 -> dry-run / simulated_hardware / physical CAN
  -> 回读、超时和审计 -> TraceEvent + ExecutionReport
```

运行时产物位于 `artifacts/runs/<request_id>/`，典型结构如下：

```text
intent.yaml
scene.yaml                    # 跨域请求才有
functions/<domain>.yaml
command-plans/<domain>.yaml
trace.jsonl
execution-report.yaml
```

不要在 `artifacts/` 写入 API Key、完整隐私文本或未脱敏车辆标识。

## 当前能力边界

| 能力面 | 当前状态 | 事实来源 |
| --- | --- | --- |
| `seat` | 虚拟矩阵闭环；T2G 台架使用独立硬件映射和校准 | [`domains/seat/`](domains/seat/)、[台架流程](docs/workflows/t2g-seat-hardware-bench.md) |
| `climate` | dry-run；支持分区温度、电源、风量、A/C、循环、风向和前除霜 | [`domains/climate/`](domains/climate/) |
| `roof` | dry-run；支持透光率、后遮阳帘位置和自动调光 | [`domains/roof/`](domains/roof/) |
| `ambient_light` | dry-run；支持开关、RGB、亮度和矩阵场景模式 | [`domains/ambient_light/`](domains/ambient_light/) |
| 原生车身 CAN | 按平台和运行时能力目录启用，不等同于领域插件 | [`config/native_can_capabilities/`](config/native_can_capabilities/)、[`platforms/`](platforms/) |
| 模式卡片 | `config/scene_templates/` 提供内置模板；用户模式持久化到 `artifacts/mode-profiles/` | [模式时间轴](docs/mode-schedules.md) |

`platforms/reference_vehicle` 的 `execution_enabled` 为 `false`。`platforms/t2g_seat_bench` 和 `platforms/t2g_cabin_bench` 才是仓库内允许配置真实执行的台架平台，但仍需硬件开关、授权令牌、总线配置和反馈校验全部满足。

## 快速开始

### 环境要求

- Python 3.11 或更高版本。
- Node.js 与 npm（构建 Web 控制台）。
- Codex CLI `0.150.0-alpha.8`，用于内置 AI 助手。
- 真实台架另需 ZLG 驱动/桥接程序、对应 DBC、IAR 工具链和硬件授权。

### 安装（PowerShell）

```powershell
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[test,dev,api,can,llm,ir]"

cd apps\web-console
npm ci
npm run build
cd ..\..

npm install --global @openai/codex@0.150.0-alpha.8
codex login status
```

语音识别是可选安装项：

```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[speech]"
.\.venv\Scripts\python.exe tools\install_sensevoice_model.py
```

配置模型认证时使用 `OPENAI_API_KEY`，或让 Codex CLI 使用已登录账户。`.env` 和 `.env.auth` 已被 Git 忽略；可参照 [`config/environments/`](config/environments/) 中的示例配置。不要把密钥提交到仓库。

### 启动完整本地演示

推荐使用启动器。它会管理主服务、只读模式卡片服务和只读 OTA 服务：

```powershell
.\.venv\Scripts\python.exe tools\start_n7web.py --skip-web-build
```

默认端口：

| 服务 | 地址 | 说明 |
| --- | --- | --- |
| 主服务和 Web 控制台 | `http://127.0.0.1:8000` | API、控制台、助手和车控入口 |
| 模式卡片目录 | `http://127.0.0.1:8090/n7/scenes` | HTTP/UDP 只读目录服务 |
| 固件 OTA | `http://127.0.0.1:8012` | 只读发布清单和下载 |

启动前端构建：

```powershell
.\.venv\Scripts\python.exe tools\start_n7web.py
```

启动器支持 `--host`、`--port`、`--scene-port`、`--ota-port`、`--catalog`、`--server-id`、`--python` 和 `--dry-run`。使用 `--host 0.0.0.0` 前请确认网络可信，并为公网部署启用认证和 HTTPS。

健康检查：

```powershell
Invoke-RestMethod http://127.0.0.1:8000/api/health
Invoke-RestMethod http://127.0.0.1:8000/api/assistant/status
```

`/api/health` 依赖 Codex App Server 就绪；助手进程不可用时返回 HTTP `503`，不会伪装成可用服务。

### 只启动主服务

需要自行运行前端开发服务器或不需要模式目录/OTA 服务时，可直接运行：

```powershell
$env:PYTHONPATH = "src;domains/seat/src"
.\.venv\Scripts\python.exe -m cognitive_agent.server
```

前端热更新：

```powershell
cd apps\web-console
npm run dev
```

Vite 使用 `http://127.0.0.1:5173`，并把 `/api` 与 `/artifacts` 代理到 `http://127.0.0.1:8000`。生产构建输出为 `apps/web-console/dist`，主服务检测到该目录后优先提供构建产物。

在已安装 GNU Make 的环境中，`make dev` 等价于启动主服务；Windows PowerShell 推荐使用上面的显式 Python 命令，以确保使用仓库的 `.venv`。

## 开发与验证

先激活 `.venv`，或把下面的 `python` 替换为 `.\.venv\Scripts\python.exe`。仓库的 `Makefile` 使用 POSIX 风格环境变量，在 Windows 上也可以直接调用 Python 脚本。

```bash
# 公共 Schema、领域清单、平台资源和生成 CAN 协议
make validate

# 全量 Python、前端契约和 CAN 协议回归
make test

# 仅前端运行时契约
make test-frontend

# 生成或检查共享 CAN 语义协议
make can-protocol-generate
make can-protocol-check
```

不使用 `make` 时：

```powershell
.\.venv\Scripts\python.exe tools\validate_repository.py
.\.venv\Scripts\python.exe -m pytest
```

仓库配置了 `pytest` 的 `contract`、`integration` 和 `hardware` markers。默认测试使用虚拟或模拟执行；真实台架测试必须按 [T2G 前端测试集](docs/testing/t2g-seat-frontend-test-suite.md) 的顺序执行，并显式确认硬件。

构建双通道 CAN 读取工具需要 CMake 和外部 CANFD SDK：

```bash
make can-read-trans
make can-read-trans-test
```

## API 入口

浏览器只访问同源服务。下面是主要集成面，完整路由以 [`src/cognitive_agent/server.py`](src/cognitive_agent/server.py) 为准：

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/api/health` | 服务与助手健康状态 |
| `GET` | `/api/runtime` | 当前运行时、平台和执行模式摘要 |
| `GET` | `/api/assistant/status` | Codex App Server 状态 |
| `GET` | `/api/assistant/capabilities` | 权威能力目录快照 |
| `POST` | `/api/requests` | 提交自然语言或结构化车控请求 |
| `POST` | `/api/requests/preview` | 只规划/校验，不执行 |
| `POST` | `/api/assistant/stream` | AI 助手 NDJSON 流 |
| `GET` | `/api/hardware/seat-state` | 座椅状态快照 |
| `GET` | `/api/hardware/vehicle-state` | 车身状态快照 |
| `GET` | `/api/vehicle-display-sync` | 网页与车机任务同步 |
| `GET` | `/n7/scenes` | 只读模式目录 |

`/api/internal/codex/vehicle-control` 仅供本机 Codex MCP 回调使用，需要一次性令牌和原始请求绑定，不是浏览器或第三方 API。语音、手势、NFC、固件工作台和自修复接口也由服务端权限门禁保护。

## 配置与安全

默认 [`config/default.yaml`](config/default.yaml) 使用 `dry_run`、结构化输出和 `artifacts/runs`。真实硬件必须同时满足：

1. 平台 manifest 的 `execution_enabled: true`。
2. 对应 CAN 后端、通道、DBC 和校准可用。
3. 服务端硬件开关、授权令牌和安全策略通过校验。
4. 领域映射明确允许硬件执行，并收到真实反馈。

模拟台架显式使用：

```powershell
$env:COGNITIVE_AGENT_SIMULATED_HARDWARE_ENABLED = "true"
```

模拟结果会标记为 `simulated_hardware`，不会打开真实 CAN、ZLG 或 IAR。真实 T2G 座椅需要参考 [`config/environments/t2g_seat_bench.example.yaml`](config/environments/t2g_seat_bench.example.yaml) 和 [硬件台架流程](docs/workflows/t2g-seat-hardware-bench.md)；不要仅通过前端按钮声称已经获得硬件权限。

语音和摄像头只在安全来源工作：本机使用 `http://127.0.0.1:8000`，远程部署必须使用 HTTPS。局域网开发命令如下：

```bash
make dev-lan
```

该模式会监听全部网络接口，任何可达设备都可能触发服务端请求，只适合可信网络临时演示。

## 代码结构

```text
apps/web-console/       Vue 入口、兼容运行层、静态资源和 PWA
src/cognitive_agent/    HTTP 服务、应用编排、运行时、基础设施和助手适配
domains/*/              领域插件：能力、Schema、映射、编译器和测试
platforms/*/            车型、DBC、总线和校准；定义执行边界
contracts/schemas/      冻结的公共 JSON Schema
config/                 环境、策略、车辆、模式和原生能力配置
tests/                  跨域契约、集成、端到端和前端测试
tools/                  启动器、仓库校验、协议生成、HIL 和诊断工具
firmware/t2g/           T2G 固件工程和可烧录依赖
deploy/                 Docker Compose、服务器和 Kubernetes 占位配置
docs/                   架构、决策、治理、工作流和测试说明
artifacts/              本地运行产物、模型、HIL 报告和持久化数据
```

依赖边界：领域插件只依赖 SDK 和公共契约，不直接调用 LLM、HTTP 或 CAN；编排层只组合语义配置，不按 CAN signal 编排；DBC 和安全标定由 `platforms/` 统一维护。详见 [总体架构](docs/architecture/overview.md)、[领域交付流程](docs/workflows/domain-delivery.md) 和 [所有权规则](docs/governance/ownership.md)。

## 可选能力

### 语音

安装 `.[speech]` 并运行 `tools/install_sensevoice_model.py` 后，控制台支持手动录音和唤醒词待机。预览和最终识别接口为 `/api/speech/preview` 与 `/api/speech/transcribe`；录音不持久化。调试使用 `SPEECH_DEBUG=1`，默认不向浏览器返回 trace。

### 手势

手势模型随仓库提供：`apps/web-console/assets/gesture/gesture_recognizer.task`。推理在浏览器完成，视频帧不上传；需要摄像头权限和安全来源。

### NFC / 红外外设

安装 `.[ir]` 后运行主服务。NFC、GSCU1B TCP 网关、红外槽位目录和 MQTT 回退由 `/api/extension/*` 管理；学习、绑定和发射均受服务端能力目录与持久 NFC 绑定约束。

### Android PAD

```powershell
powershell -ExecutionPolicy Bypass -File .\tools\android_pad_dev.ps1
powershell -ExecutionPolicy Bypass -File .\tools\android_pad_dev.ps1 -Stop
```

脚本使用模拟台架，不打开真实硬件执行。

## 部署

服务器 Docker Compose 和 Caddy 反向代理说明见 [`deploy/server/README.md`](deploy/server/README.md)。镜像默认以非 root 用户、只读根文件系统运行，应用只绑定服务器回环地址，再由 Caddy 提供 HTTPS。部署时通过私密环境文件注入认证材料和模型凭据，不把 `.env`、`.env.auth`、Codex `auth.json` 或 API Key 放入镜像和版本库。

`deploy/docker/` 记录后续拆分 API/worker/Web 的边界；`deploy/k8s/` 目前是 Kubernetes 资源占位文档。真实 CAN 设备只能挂载到明确授权的执行器环境。

## 相关文档

- [总体架构](docs/architecture/overview.md)
- [T2G 座椅与车身双通道 CAN](docs/workflows/t2g-cabin-dual-channel-can.md)
- [T2G 座椅真实硬件台架](docs/workflows/t2g-seat-hardware-bench.md)
- [T2G 座椅前端测试集](docs/testing/t2g-seat-frontend-test-suite.md)
- [中文语音控制链路](docs/speech-recognition.md)
- [模式卡片与时间轴](docs/mode-schedules.md)
- [领域交付流程](docs/workflows/domain-delivery.md)
- [所有权与变更边界](docs/governance/ownership.md)
- [服务器部署](deploy/server/README.md)
- [Web 控制台细节](apps/web-console/README.md)

## 项目状态

这是面向演示、集成和受控台架验证的工程，不是未经适配即可部署到任意车型的通用车控产品。提交修改前至少运行 `validate` 和相关领域测试；涉及 DBC、平台标定、硬件执行或公共 Schema 的变更，需要同时更新对应专题文档与回归用例。