# Cognitive Agent 面向车载执行器的认知编排 Agent 单仓工程。系统把自然语言请求转换为可校验的语义配置，再由确定性的领域插件编译为 CAN 命令计划，最后经安全策略和执行器下发。 Web 控制台与同源 API 由同一个 Python 服务提供。本地启动： ```bash .\.venv\Scripts\python.exe .\tools\start_n7web.py ``` Windows PowerShell 未安装 `make` 时可直接运行： ```powershell $env:PYTHONPATH = "src;domains/seat/src" 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 展示可审计的决策摘要和阶段事件，不展示模型私有思维链。 ## 目录 ```text . ├── 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/ # 脚手架、校验和开发工具 ``` 完整依赖关系和处理链路见 [总体架构](docs/architecture/overview.md)，成员交付步骤见 [领域交付流程](docs/workflows/domain-delivery.md)，修改边界见 [所有权规则](docs/governance/ownership.md)。 整体排期和阶段准入条件见 [集成路线](docs/workflows/integration-roadmap.md)。 ## 配置处理链路 ```text 用户文本 -> GPT + Capability Registry + 当前会话状态 -> 通用能力请求（领域、能力、作用域、操作和参数） -> IntentIR（意图抽取、领域识别、歧义与置信度） -> 单领域：FunctionConfig -> 多领域：SceneConfig + N 个 FunctionConfig -> 公共 Schema 校验 + 领域语义校验 -> 领域 Compiler -> CommandPlan -> 平台安全校验 -> 调度 -> CAN Gateway -> 回读/超时/结果 -> TraceEvent + ExecutionReport ``` 运行时产物统一保存在： ```text artifacts/runs// ├── intent.yaml ├── scene.yaml # 仅跨域请求存在 ├── functions/.yaml ├── command-plans/.yaml ├── trace.jsonl └── execution-report.yaml ``` `artifacts/` 中禁止写入 API Key、完整隐私文本或未脱敏的车辆标识。 ## 可执行领域 座椅与空调等车身设备使用同一 ZLG CAN 盒双通道联动时，参见 [T2G 座椅与车身双通道 CAN 联动](docs/workflows/t2g-cabin-dual-channel-can.md)。 当前已接入四个相互隔离的可执行领域： - 座椅：所有热管理、位置移动和姿态预设能力仅面向副驾；未指定座位时默认副驾，显式主驾请求拒绝执行。 - 空调：基于 `空调-天幕-氛围灯CAN信号矩阵表.xlsx` 的电源、18–32℃ 分区温度、0–7 档风量、A/C、内外循环、风向和前除霜。 - 天幕：基于同一矩阵的 0–100% 透光率、后遮阳帘绝对位置和自动调光。 - 氛围灯：基于同一矩阵的总开关、24-bit RGB、0–100% 亮度和 ECU 场景模式。 一句话只涉及一个领域时直接生成一份 `FunctionConfig`；涉及多个领域时生成一份 `SceneConfig` 引用各领域独立的 `FunctionConfig`，并由各自编译器产生 `CommandPlan`。三份新增矩阵仍缺少车型适用性、完整计数器、校验和和发送周期，因此与座椅演示一样只允许虚拟执行。 ```bash 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 编译和虚拟执行均为同一确定性路径。 ### Codex AI 助手 首页 AI 助手以长驻 `codex app-server --stdio` 为会话与推理核心。浏览器仍只连接同源 `/api/assistant/stream`，不会接触 Codex 协议或凭据；后端把 App Server 的 thread、turn 和 item 事件转换为 NDJSON 流。普通问题由 Codex 直接回答。涉及本工程能力时，`/api/assistant/capabilities`、回合上下文和只读 MCP 工具 `n7_vehicle.get_n7web_capabilities` 都从同一个运行时能力注册表生成，座舱模式、NFC 绑定红外外设及 CAN0/CAN1 执行绑定会随实际状态更新，不允许模型凭常识猜测。常见能力询问直接由本地权威目录回答，无需等待模型生成。 显式及复杂车辆需求通过唯一放行的 `n7_vehicle.execute_cockpit_request` MCP 工具进入工程。服务端把一次性工具令牌绑定到本回合原始指令；Codex 可以为原子设备控制提交结构化语义计划，但不能提交新的自然语言指令或原始 CAN。计划必须通过原文证据、能力白名单、目标和参数契约校验，本地确定性解析结果优先，之后仍进入既有 Schema、硬件授权、安全预检、互斥和 CAN 执行链。模型不能扩展用户未请求的控制，也不能覆盖执行模式和硬件授权。 “车上有点热”“车里有点冷”等与受限模式完整匹配、且不包含否定或知识问法的高置信度舒适请求，使用 N7Web 内部快速路由：分别归一化为空调开启、全车 23℃/26℃、2 档风量等确定性指令，绕过模型和 MCP 往返以尽快给出进度与结果。该快速路由只缩短意图理解路径，不绕过能力注册、Schema、执行模式、硬件授权、安全预检、互斥、CAN 编译或反馈确认；其他隐式、复合或含糊请求仍交给 Codex 判断，并受上述 MCP 边界约束。 能力目录中的 `service_surfaces` 仅用于显示语音输入、手势输入、NFC 绑定、座椅自标定和自修复等服务的运行状态，条目固定标记为 `assistant_access=informational`。这里的 `available=true` 只表示对应服务面可用，不表示 AI 助手可以调用它；可执行边界以 `capabilities`、`modes`、`learned_peripherals` 中的 `assistant_callable` 以及服务端再次校验结果为准。 本地运行前需要安装并登录固定兼容版本的 Codex CLI： ```bash npm install --global @openai/codex@0.150.0-alpha.8 codex login status make dev ``` 也可以让 Codex 使用进程环境中的 `OPENAI_API_KEY`。未配置自定义地址时，N7Web 会在 App Server 没有缓存账户的情况下通过 API-key 登录；配置非官方 `OPENAI_BASE_URL` 时，会自动为线程注入完整的 OpenAI-compatible provider，使 Codex 确实请求该地址，而不是回落到 `api.openai.com`。助手默认选择低推理强度的 `gpt-5.6-luna`，可用 `CODEX_ASSISTANT_MODEL` 覆盖；`CODEX_ASSISTANT_REASONING_EFFORT` 默认为 `low`，`CODEX_ASSISTANT_TURN_TIMEOUT_SECONDS` 默认为 300 秒，`CODEX_ASSISTANT_WORKSPACE` 用来指定隔离的只读工作目录。当前工程的常用场景登记在 `config/scene_templates`：明确名称会直接做严格别名匹配；“适合/用于/用来……的功能模式”等用途描述会先通过受限语法提炼为简洁模式名，再做同样的严格匹配，不使用子串或相似度猜测。命中且没有同名已保存模式时，模板会在本地复制为新的待保存草稿，不调用 Codex，也不会修改内置模板；草稿仍会经过实时能力契约、完整性、CAN 编译和 dry-run 校验。未命中的长尾名称继续进入独立的单轮结构化 Scene Composer；该路径默认超时 45 秒，已验证的候选计划在当前进程内按车型和能力契约版本缓存 3600 秒，同场景跨用户并发请求会合并，但每个请求仍会独立经过实时安全校验。可分别通过 `CODEX_ASSISTANT_SCENE_TIMEOUT_SECONDS`、`CODEX_ASSISTANT_SCENE_CACHE_TTL_SECONDS`、`CODEX_ASSISTANT_SCENE_CACHE_MAX_ENTRIES` 和 `CODEX_ASSISTANT_SCENE_MAX_CONCURRENT_PLANS` 调整超时、缓存和并行规划上限（默认 8）。为避免兼容服务的 WebSocket 断流造成长时间重试，自定义 provider 默认关闭 WebSocket，并把模型流重试限制为一次；可通过 `CODEX_ASSISTANT_DISABLE_WEBSOCKETS` 和 `CODEX_ASSISTANT_STREAM_MAX_RETRIES` 调整。 启动采用失败关闭语义：CLI 缺失、App Server 握手失败、模型认证配置缺失/登录失败，或有效 MCP 配置未能收敛并验证为仅启用 `n7_vehicle` 时，`cognitive_agent.server` 会直接启动失败，不会继续提供一个看似可用的降级网页。进程启动后若 App Server 退出，`/api/health` 返回 `503`，`/api/assistant/status` 显示不可用；凭据被服务端撤销、模型权限、网络或生成失败等只有真实模型请求才能发现的问题，则由当前问答流返回 `assistant_model_failed`。这些情况都不会静默回退到旧的正则问答路由；本地能力快答和冷热快速控制仍只按各自严格的确定性条件工作。 App Server 的协议与审批字段以 [Codex App Server 官方文档](https://learn.chatgpt.com/docs/app-server) 和 [Codex 配置参考](https://learn.chatgpt.com/zh-Hans/docs/config-file/config-reference) 为准。线程级 `approvalPolicy=never` 与 MCP 工具级 `default_tools_approval_mode=approve` 作用于不同边界：前者禁止命令/文件修改请求进入交互审批，后者仅避免受限的 N7Web MCP 工具产生前端无法处理的第二次审批；真实执行授权仍完全由 N7Web 的一次性令牌、原文绑定和车辆安全链决定。 ### AI 助手语音输入、快捷模式与手势控制 首页左侧的 Codex AI 助手接受普通问题、工程工作和车辆控制需求；Enter 发送，Shift+Enter 换行。观影、午休和零重力是可直接调用的快捷模式，“保存当前”可把当前副驾驶姿态保存为命名模式。能力快答和高置信度舒适请求走确定性快速链，其他请求由 Codex App Server 理解后再通过工程能力与安全边界执行。 语音入口分为两种明确模式：用户点击输入框右侧的麦克风按钮时，以 `manual` 模式立即开始本地中文录音，不要求也不剥离唤醒词；浏览器已获得麦克风权限、AI 助手处于展开状态且页面可见时，则自动进入低干扰的 `wake` 待机，只在识别到“你好，小迪”后展示并继续接收问题。首次使用仍需通过一次手动点击完成浏览器麦克风授权。前端优先选择 `TAKSTAR V2`，使用 `AudioWorklet` 在音频线程采集（旧浏览器才降级到 `ScriptProcessor`），并通过 `X-Speech-Input-Mode: manual|wake` 将两条链路显式隔离。 累积音频按节流窗口发送到同源 `/api/speech/preview`：手动模式直接把未语义清洗的实时转录显示在输入框，唤醒模式在命中前不改动输入框、命中后只显示唤醒词之后的内容，partial 阶段均不会提交或执行。浏览器检测到静音端点后立即停止音轨，再把 16 kHz PCM WAV 发送到 `/api/speech/transcribe` 生成权威 final。服务端使用 Silero VAD 保留句首/句尾保护区，SenseVoiceSmall 负责声学识别，统一 `TranscriptAssembler` 负责 final commit、顺序、重复回调和保守的相邻重叠消除。 最终响应把不同信任层明确拆开：`captured_text` 保留完整声学识别结果；`raw_text` 在 `manual` 模式保留完整原文，在 `wake` 模式仅剥离已确认的唤醒词；`assistant_text` 在保留普通问答的前提下处理重复、结巴、false start、修正、撤销、否定、多设备、多数字和小数，供 AI 助手输入框使用；`clean_text/control_text`、结构化 `commands`、`cancelled_fragments` 和 `execution_eligible` 继续作为严格车控旁路。未知能力或非车控内容不会被清空，也不会绕过 Codex 助手直接执行。听写本身不自动发送消息、不自动执行控制，也不保存录音。首次部署： ```bash 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_*` 覆盖；`SPEECH_WAKE_WORD_ENABLED` 控制唤醒门，`SPEECH_WAKE_WORDS` 使用 `|` 分隔主唤醒词和别名。 当前 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 同名值）启用控制台日志，生产默认不打印。回归与指标基准： ```bash 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 推理，识别结果仍通过同一自然语言编排、安全校验与执行链路处理。运行必需资源已经纳入本工程： ```text 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 模式只应在可信网络内临时演示。 ### N7 模式卡片局域网目录 服务正常启动时，会把当前车型可见的工程预设模式和用户自定义模式原子同步到相邻目录 `../scenses/demo-scenes.json`，并提供无需登录、只读的 `GET /n7/scenes`。YAML 模式库仍是唯一真源；创建、更新、删除、恢复模式都会刷新 JSON，原有模式执行和安全校验链路不变。JSON 保留 `n7-scenes` v1 的 `id/label/background_time/description/actions` 字段，同时在动作中保留完整的 `domain/capability/target_scope/operation/parameters`，因此座椅、空调、天幕和氛围灯配置不会在导出时丢失。可用 `N7_SCENE_CATALOG_PATH` 或启动参数 `--scene-catalog` 覆盖输出路径。 主项目和客户端只读目录服务可以用一个监督脚本同时启动： ```powershell .\.venv\Scripts\python.exe tools\start_n7web.py ``` 脚本自动设置 `PYTHONPATH`，主页面默认仅监听 `127.0.0.1:8000`，模式卡片 HTTP/UDP 服务监听 `0.0.0.0:8090`。需要让可信局域网内的设备同时访问主页面时，使用 `--host 0.0.0.0`；可通过 `--port`、`--scene-port`、`--catalog` 和 `--server-id` 覆盖其他参数。任一子服务异常退出或按一次 `Ctrl+C` 时，脚本会停止另一个服务。 同步由模式注册表的创建、更新、删除、恢复和显式重载事件触发，不会持续扫描目录。每次变更只重新生成并原子替换一份小型 JSON；独立目录服务在收到 HTTP 请求时才读取它。因此空闲时的额外开销主要是一个等待请求的 Python 进程和一个 UDP 发现线程，而不是持续的 CPU 或磁盘轮询。 如果只需单独启动 UDP 发现和只读目录服务，也可以在另一个 PowerShell 终端运行： ```powershell $env:PYTHONPATH = "src;domains/seat/src" .\.venv\Scripts\python.exe -m cognitive_agent.lan_scene_server --bind 0.0.0.0 --port 8090 ``` 客户端向 UDP `8090` 发送 `N7_SCENES_DISCOVER_V1`，收到 `N7_SCENES_V1` 后访问 `http://<服务端IP>:8090/n7/scenes`。独立服务每次请求都读取最新的 JSON，并为只读接口开放 CORS；它不提供模式创建、修改、删除或执行能力。 Linux 上使用 USBCANFD-200U 被动同步 CH1 车辆状态时，使用 `zlgcan-linux` 后端。USB 权限、60 MHz/500k/2M 位时序、只读配置和状态接口 验证见 [Linux ZLG 车辆状态接入](docs/workflows/linux-zlg-vehicle-state.md)。 有线 ZLG 与本机 NanoMQ 无线链路使用相同的通道角色：CAN0 只对应副驾座椅， CAN1 对应空调、车窗、灯光、遮阳帘、主驾座椅等其余车辆状态和控制。车辆控制 后端不允许回退到 CAN0；MQTT 主题、原始 CAN 帧 JSON 合约和有线/无线共用安全 门禁见同一文档。 需要在终端独立核对双通道状态或下发一条明确的白名单语义命令时，可构建 `can_read_trans`。该程序由同一个 C++ 进程持有 ZLG 设备：CAN0 监听并控制副驾 座椅固件原生协议，CAN1 监听并控制其余车辆矩阵协议；默认只监听、默认不启用 适配器内部终端电阻，也不提供任意原始帧注入入口。`console --execute` 可在同一 设备会话中持续接收状态并交互下发 CAN0/CAN1 白名单命令。构建、命令示例、反馈 判定和安全限制见 [can_read_trans 双通道检测与控制](docs/workflows/can-read-trans.md)。 ## 认证与公网体验 公网演示必须启用 `.env.auth` 中的服务端认证。密码使用 PBKDF2-SHA256 哈希保存；认证成功后签发有有效期的 HMAC 会话 Cookie，Cookie 使用 `HttpOnly` 和 `SameSite=Strict`，经 HTTPS 代理时自动增加 `Secure`。登录失败按来源 IP 限流，GPT 请求按体验账号限制每分钟调用次数。未登录访问页面会跳转 `/login`，未登录 API 请求返回 `401`。 生成认证材料： ```bash 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`](deploy/server/README.md)。本地 `make dev` 与 `make dev-lan` 仍分别用于回环地址和可信局域网开发。 当前 dry-run 规划策略允许 GPT 在没有同名 preset 时，将可理解的模式目标分解为已注册原子能力并生成保守候选参数。候选值只用于模型理解演示，不能替代实车模式标定。 靠背/坐垫与坐垫/腿托支持演示级精确夹角，并可将当前五轴姿态保存为会话持久化的命名 `FunctionPreset`。保存操作不发 CAN；再次调用时先展开为五个原子电机动作，再进入同一编译、校验和虚拟执行链路。 完整能力边界、矩阵解释和验收用例见 [座椅阶段一交付](docs/workflows/seat-stage1-delivery.md)。 已验证的 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 座椅真实硬件台架接入](docs/workflows/t2g-seat-hardware-bench.md) 与 [前端能力测试集](docs/testing/t2g-seat-frontend-test-suite.md)。