Cognitive_Agent/README.md

# 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/<request_id>/
├── intent.yaml
├── scene.yaml                  # 仅跨域请求存在
├── functions/<domain>.yaml
├── command-plans/<domain>.yaml
├── trace.jsonl
└── execution-report.yaml
```

`artifacts/` 中禁止写入 API Key、完整隐私文本或未脱敏的车辆标识。

## 可执行领域

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

- 座椅：所有热管理、位置移动和姿态预设能力仅面向副驾；未指定座位时默认副驾，显式主驾请求拒绝执行。
- 空调：基于 `空调-天幕-氛围灯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 编译和虚拟执行均为同一确定性路径。

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

首页左侧提供一句话控制，可同时描述座椅、空调、天幕和氛围灯目标；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`，包括 IAR 工程及仓库内 `common/tviibh8m` 构建依赖。M0/M1/M2/M3 分别对应水平、坐盆、靠背和腿托；真实硬件请求先被动核对新版周期反馈与 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)。