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、完整隐私文本或未脱敏的车辆标识。

可执行领域

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

• 座椅：基于 座椅部分功能CAN矩阵表.xlsx 的主/副驾通风和加热，以及明确标识为 synthetic 的五轴位置电机演示。
• 空调：基于 空调-天幕-氛围灯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 或 auto 模式调用失败时的显式降级路径。模型由 OPENAI_MODEL=gpt-5.6-sol 指定；兼容 OpenAI Responses API 的服务可通过 OPENAI_BASE_URL 指定。无论使用哪种解析器，配置校验、CAN 编译和虚拟执行均为同一确定性路径。

一句话、快捷模式与手势控制

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

顶部“手势控制”打开同页抽屉。浏览器在本机完成 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 模式只应在可信网络内临时演示。

认证与公网体验

公网演示必须启用 .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/Seat_Controller_demo，并提供一条默认锁定的真实 HIL 路径。主驾与副驾目前映射到同一物理座椅；硬件请求会先做固件身份握手，可在明确启用后通过 IAR C-SPY 自动烧录，再发送 CAN 并等待真实回读。固件拓扑、IAR 构建、ZLG 32 位 bridge、CAN 接线、安全门禁和上电步骤见 T2G 座椅真实硬件台架接入。