Cognitive Agent

面向车载执行器的认知编排 Agent 单仓工程。系统把自然语言请求转换为可校验的语义配置，再由确定性的领域插件编译为 CAN 命令计划，最后经安全策略和执行器下发。

启动前端:PYTHONPATH=src:domains/seat/src .omx/python311-venv/bin/python -m cognitive_agent.server

建设阶段

• 阶段一：每个领域独立完成能力定义、功能配置生成、配置校验、CAN 编译和单执行器测试。
• 阶段二：由中央编排器生成 SceneConfig，引用多份 FunctionConfig，按依赖关系、时间偏移和失败策略组合执行。
• 最终形态：Web 控制台接收一句话请求，展示结构化决策摘要、配置文件、校验结果和执行状态。

核心约束

1. LLM 只能生成 IntentIR、FunctionConfig 或 SceneConfig，不能直接生成或发送原始 CAN 帧。
2. FunctionConfig 只允许包含一个 domain；跨域需求必须使用 SceneConfig 引用多份领域配置。
3. CAN 编译必须是确定性的：相同配置、相同平台标定和相同插件版本必须生成相同 CommandPlan。
4. DBC、通道定义和安全标定由集成人员在 platforms/ 统一维护；领域成员只维护语义信号映射。
5. 所有真实执行必须经过公共 Schema 校验、领域校验、安全策略、dry-run 和审计记录。
6. UI 展示可审计的决策摘要和阶段事件，不展示模型私有思维链。

目录

.
├── apps/                    # API 服务、Web 控制台和内置手势模型资源
├── artifacts/               # 每次请求的生成物和执行记录（不入库）
├── config/                  # 全局环境和策略配置
├── contracts/               # 冻结的公共 Schema、示例和版本规则
├── deploy/                  # 容器及部署资源
├── docs/                    # 架构、流程、治理和 ADR
├── firmware/t2g/            # 仓库内统一座椅 IAR 工程与可烧录产物
├── domains/                 # 可独立开发、测试、交付的领域插件
│   ├── _template/           # 新领域模板
│   ├── seat/                # 座椅
│   ├── climate/             # 空调
│   ├── ambient_light/       # 氛围灯
│   └── roof/                # 天幕/遮阳帘/调光玻璃
├── platforms/               # 车型、DBC、总线和安全标定
├── src/cognitive_agent/     # 中央 Agent、编排器、运行时和基础设施
├── tests/                   # 跨域契约、集成和端到端测试
└── tools/                   # 脚手架、校验和开发工具

完整依赖关系和处理链路见 总体架构，成员交付步骤见 领域交付流程，修改边界见 所有权规则。 整体排期和阶段准入条件见 集成路线。

配置处理链路

用户文本
  -> GPT + Capability Registry + 当前会话状态
  -> 通用能力请求（领域、能力、作用域、操作和参数）
  -> IntentIR（意图抽取、领域识别、歧义与置信度）
  -> 单领域：FunctionConfig
  -> 多领域：SceneConfig + N 个 FunctionConfig
  -> 公共 Schema 校验 + 领域语义校验
  -> 领域 Compiler -> CommandPlan
  -> 平台安全校验 -> 调度 -> CAN Gateway
  -> 回读/超时/结果 -> 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、完整隐私文本或未脱敏的车辆标识。

可执行领域

座椅与空调等车身设备使用同一 ZLG CAN 盒双通道联动时，参见 T2G 座椅与车身双通道 CAN 联动。

当前已接入四个相互隔离的可执行领域：

• 座椅：所有热管理、位置移动和姿态预设能力仅面向副驾；未指定座位时默认副驾，显式主驾请求拒绝执行。
• 空调：基于 空调-天幕-氛围灯CAN信号矩阵表.xlsx 的电源、18–32℃ 分区温度、0–7 档风量、A/C、内外循环、风向和前除霜。
• 天幕：基于同一矩阵的 0–100% 透光率、后遮阳帘绝对位置和自动调光。
• 氛围灯：基于同一矩阵的总开关、24-bit RGB、0–100% 亮度和 ECU 场景模式。

一句话只涉及一个领域时直接生成一份 FunctionConfig；涉及多个领域时生成一份 SceneConfig 引用各领域独立的 FunctionConfig，并由各自编译器产生 CommandPlan。三份新增矩阵仍缺少车型适用性、完整计数器、校验和和发送周期，因此与座椅演示一样只允许虚拟执行。

make validate
make test
make dev

浏览器访问 http://127.0.0.1:8000。设置 OPENAI_API_KEY 后，GPT Structured Outputs 会基于各领域的 config/capabilities.yaml 和当前会话状态直接生成通用能力请求；后端只做结构校验、领域路由和确定性执行适配，不用本地语义规则改写 GPT 动作。本地解析器用于未配置 GPT，或 GPT/auto 模式因 API Key、模型权限、网络或结构化响应异常而失败时的安全降级；结果会明确标记 local_rules_fallback。模型由 OPENAI_MODEL=gpt-5.6-sol 指定；兼容 OpenAI Responses API 的服务可通过 OPENAI_BASE_URL 指定。无论使用哪种解析器，配置校验、CAN 编译和虚拟执行均为同一确定性路径。

一句话、语音听写、快捷模式与手势控制

首页左侧提供一句话控制，可同时描述座椅、空调、天幕和氛围灯目标；Enter 直接执行，Shift+Enter 换行。观影、午休和零重力是可直接调用的快捷模式，“保存当前”可把当前副驾驶姿态保存为命名模式。复杂跨域自然语言优先使用 GPT 解析，本地规则用于已明确覆盖的离线指令。

输入框右侧的麦克风按钮提供本地中文语音听写：优先选择 TAKSTAR V2 输入设备，AudioWorklet 在音频线程采集（旧浏览器才降级到 ScriptProcessor），浏览器端静音检测负责自动停录，16 kHz PCM WAV 发送到同源 /api/speech/transcribe。服务端再使用 Silero VAD 做权威分段并保留句首/句尾保护区，SenseVoiceSmall 只负责声学识别；统一 TranscriptAssembler 负责 final commit、顺序、重复回调和保守的相邻重叠消除。

声学 raw_text 永远保留。独立的 UnderstandingTranscriptProcessor 根据工程能力目录生成 clean_text、结构化 commands、cancelled_fragments 和 uncertain，区分“然后”的正常多指令与“不对、改成、算了”等修正/撤销。无关聊天与否定不会激活控制；超出工程参数范围或表达残缺的结果会显示但禁止直接提交，用户修改确认后才能执行。听写本身不自动执行控制命令，也不保存录音。首次部署：

python -m pip install -e ".[speech]"
python tools/install_sensevoice_model.py

安装脚本同时校验并部署 artifacts/models/silero-vad/silero_vad.onnx。默认使用完整精度 SenseVoice、language=zh、ITN 和最多 8 个 CPU 线程；VAD 针对短车控语句使用阈值 0.45、最短语音 0.16s、结束静音 0.65s、最长分段 12s、前置 0.25s、后置 0.35s。可通过 SPEECH_MODEL_*、SPEECH_LANGUAGE、SPEECH_USE_ITN、SPEECH_NUM_THREADS、SPEECH_PROVIDER 与 SPEECH_VAD_* 覆盖。

当前 sherpa-onnx 版本支持 SenseVoice 的 hr_lexicon/hr_rule_fsts，只有同时提供经过验证的文件时才会启用：SPEECH_HR_LEXICON 和 SPEECH_HR_RULE_FSTS。未对非 transducer 的 SenseVoice 使用 hotword decoding。可插拔 RecoveryRecognizer 默认关闭，只为将来让 uncertain case 使用二次识别，不会下载大型模型。

诊断时设置 SPEECH_DEBUG=1 输出按 utteranceId、segment 边界、raw final、拼接前后、理解结果、Intent 与阶段耗时组织的 JSON 日志；只有额外设置 SPEECH_DEBUG_RESPONSE=1 才把 trace 返回浏览器。前端访问参数 ?speechDebug=1（或 localStorage 同名值）启用控制台日志，生产默认不打印。回归与指标基准：

pytest tests/unit/test_speech_transcription.py tests/unit/test_transcript_assembler.py
python tools/benchmark_speech_pipeline.py --audio-dir artifacts/tmp/speech-regression-audio

麦克风仅可用于安全来源：本机使用 http://127.0.0.1:8000，远程使用 HTTPS。

顶部“手势控制”打开同页抽屉。浏览器在本机完成 MediaPipe 推理，识别结果仍通过同一自然语言编排、安全校验与执行链路处理。运行必需资源已经纳入本工程：

apps/web-console/assets/gesture/gesture_recognizer.task
config/gesture/default.yaml

因此源码打包和容器构建不依赖相邻的 seat_gesture_control 目录。模型文件只保留一份，不包含原工程的测试视频、日志或验证输出。浏览器摄像头要求安全来源，本地使用 http://127.0.0.1:8000，远程部署使用 HTTPS；首次使用仍需浏览器授予摄像头权限。MediaPipe Web 运行时从 jsDelivr 按需加载，视频帧不上传到后端。

手势安全状态机采用张掌保持 1 秒激活、动作保持 600 ms 且至少 8 帧确认、单次运动 1.5 秒上限、连续 3 秒无有效动作自动锁止。换动作不需要重新张掌；握拳立即停止当前动作但保持激活；多手画面不执行动作。手势映射可在抽屉内自定义并保存在当前浏览器。

同一局域网的其他电脑需要体验时，使用 make dev-lan 监听全部网络接口。服务启动日志会打印实际 LAN 地址，例如 http://172.20.10.5:8000。前端和 API 使用同源访问，不需要 CORS，也不会把 OPENAI_API_KEY 发送到浏览器。若没有启用 .env.auth，任何可达设备都能触发服务端 GPT 请求，因此未认证的 LAN 模式只应在可信网络内临时演示。

Linux 上使用 USBCANFD-200U 被动同步 CH1 车辆状态时，使用 zlgcan-linux 后端。USB 权限、60 MHz/500k/2M 位时序、只读配置和状态接口 验证见 Linux ZLG 车辆状态接入。 有线 ZLG 与本机 NanoMQ 无线链路使用相同的通道角色：CAN0 只对应副驾座椅， CAN1 对应空调、车窗、灯光、遮阳帘、主驾座椅等其余车辆状态和控制。车辆控制 后端不允许回退到 CAN0；MQTT 主题、原始 CAN 帧 JSON 合约和有线/无线共用安全 门禁见同一文档。

需要在终端独立核对双通道状态或下发一条明确的白名单语义命令时，可构建 can_read_trans。该程序由同一个 C++ 进程持有 ZLG 设备：CAN0 监听并控制副驾 座椅固件原生协议，CAN1 监听并控制其余车辆矩阵协议；默认只监听、默认不启用 适配器内部终端电阻，也不提供任意原始帧注入入口。console --execute 可在同一 设备会话中持续接收状态并交互下发 CAN0/CAN1 白名单命令。构建、命令示例、反馈 判定和安全限制见 can_read_trans 双通道检测与控制。

认证与公网体验

公网演示必须启用 .env.auth 中的服务端认证。密码使用 PBKDF2-SHA256 哈希保存；认证成功后签发有有效期的 HMAC 会话 Cookie，Cookie 使用 HttpOnly 和 SameSite=Strict，经 HTTPS 代理时自动增加 Secure。登录失败按来源 IP 限流，GPT 请求按体验账号限制每分钟调用次数。未登录访问页面会跳转 /login，未登录 API 请求返回 401。

生成认证材料：

PYTHONPATH=src python -m cognitive_agent.auth hash-password
PYTHONPATH=src python -m cognitive_agent.auth generate-secret

固定公网演示部署在 https://511.kendeji.fun。服务器使用 Docker Compose 运行应用，容器端口只绑定 127.0.0.1:8511，由 Caddy 终止 HTTPS 并反向 代理。部署结构、更新和运维命令见 deploy/server/README.md。本地 make dev 与 make dev-lan 仍分别用于回环地址和可信局域网开发。

当前 dry-run 规划策略允许 GPT 在没有同名 preset 时，将可理解的模式目标分解为已注册原子能力并生成保守候选参数。候选值只用于模型理解演示，不能替代实车模式标定。

靠背/坐垫与坐垫/腿托支持演示级精确夹角，并可将当前五轴姿态保存为会话持久化的命名 FunctionPreset。保存操作不发 CAN；再次调用时先展开为五个原子电机动作，再进入同一编译、校验和虚拟执行链路。

完整能力边界、矩阵解释和验收用例见 座椅阶段一交付。

已验证的 T2G 加热、通风、四电机和原生动态模式能力已完整纳入 firmware/t2g，包括 IAR 工程及仓库内 common/tviibh8m 构建依赖。M0/M1/M2/M3 分别对应水平、坐盆、靠背和腿托；revision 13通过0x306反馈带斜向耦合补偿的木马模式与四轴全程联动动态摇篮的阶段/循环状态。木马模式围绕中间姿态在[270,250,460,400]和[370,130,540,460]之间连续俯仰往复：坐盆峰峰行程120 Hall、约18 mm垂直分量，水平峰峰行程100 Hall、90%巡航Duty，用额外水平行程抵消坐盆斜向运动约16.4 mm的反向水平分量；参数集中在seat_dynamic_mode_config.h并由N7长期库镜像。动态模式收到一次启动命令后由ECU连续循环，收到停止/全停命令或累计运行10分钟时停止；目标到位式阶段在底层堵转/无运动保护继续生效的前提下使用独立保护窗口。真实硬件请求先被动核对新版周期反馈与 480/374/917/647 Hall 量程，未检测到匹配固件时默认通过 IAR C-SPY 自动烧写并复验，再发送 CAN 并等待真实回读。当前前端、能力注册、编译、安全门禁和状态反馈只允许副驾 passenger/front_right；固件中的 Driver_Seat_* 仅是板端既有协议字段名。构建、ZLG bridge、接线、安全门禁、前端测试集和已知量程归零见 T2G 座椅真实硬件台架接入 与 前端能力测试集。