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、硬件授权、安全策略、互斥和反馈检查共同决定。

处理链路

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

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

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

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

当前能力边界

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

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）

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

语音识别是可选安装项：

.\.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/ 中的示例配置。不要把密钥提交到仓库。

启动完整本地演示

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

.\.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	只读发布清单和下载

启动前端构建：

.\.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。

健康检查：

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 服务时，可直接运行：

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

前端热更新：

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 脚本。

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

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

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

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

不使用 make 时：

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

仓库配置了 pytest 的 contract、integration 和 hardware markers。默认测试使用虚拟或模拟执行；真实台架测试必须按 T2G 前端测试集 的顺序执行，并显式确认硬件。

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

make can-read-trans
make can-read-trans-test

API 入口

浏览器只访问同源服务。下面是主要集成面，完整路由以 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 使用 dry_run、结构化输出和 artifacts/runs。真实硬件必须同时满足：

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

模拟台架显式使用：

$env:COGNITIVE_AGENT_SIMULATED_HARDWARE_ENABLED = "true"

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

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

make dev-lan

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

代码结构

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/ 统一维护。详见 总体架构、领域交付流程 和 所有权规则。

可选能力

语音

安装 .[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 -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。镜像默认以非 root 用户、只读根文件系统运行，应用只绑定服务器回环地址，再由 Caddy 提供 HTTPS。部署时通过私密环境文件注入认证材料和模型凭据，不把 .env、.env.auth、Codex auth.json 或 API Key 放入镜像和版本库。

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

相关文档

• 总体架构
• T2G 座椅与车身双通道 CAN
• T2G 座椅真实硬件台架
• T2G 座椅前端测试集
• 中文语音控制链路
• 模式卡片与时间轴
• 领域交付流程
• 所有权与变更边界
• 服务器部署
• Web 控制台细节

项目状态

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