# 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 展示可审计的决策摘要和阶段事件，不展示模型私有思维链。 ## 目录 ```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、完整隐私文本或未脱敏的车辆标识。 ## 可执行领域 当前已接入四个相互隔离的可执行领域： - 座椅：基于 `座椅部分功能CAN矩阵表.xlsx` 的主/副驾通风和加热，以及明确标识为 synthetic 的五轴位置电机演示。 - 空调：基于 `空调-天幕-氛围灯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 或 `auto` 模式调用失败时的显式降级路径。模型由 `OPENAI_MODEL=gpt-5.6-sol` 指定；兼容 OpenAI Responses API 的服务可通过 `OPENAI_BASE_URL` 指定。无论使用哪种解析器，配置校验、CAN 编译和虚拟执行均为同一确定性路径。 ### 一句话、快捷模式与手势控制 首页左侧提供一句话控制，可同时描述座椅、空调、天幕和氛围灯目标；Enter 直接执行，Shift+Enter 换行。观影、午休和零重力是可直接调用的快捷模式，“保存当前”可把当前副驾驶姿态保存为命名模式。复杂跨域自然语言优先使用 GPT 解析，本地规则用于已明确覆盖的离线指令。 顶部“手势控制”打开同页抽屉。浏览器在本机完成 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 模式只应在可信网络内临时演示。 ## 认证与公网体验 公网演示必须启用 `.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/Seat_Controller_demo`，并提供一条默认锁定的真实 HIL 路径。主驾与副驾目前映射到同一物理座椅；硬件请求会先做固件身份握手，可在明确启用后通过 IAR C-SPY 自动烧录，再发送 CAN 并等待真实回读。固件拓扑、IAR 构建、ZLG 32 位 bridge、CAN 接线、安全门禁和上电步骤见 [T2G 座椅真实硬件台架接入](docs/workflows/t2g-seat-hardware-bench.md)。