# 总体架构

## 设计目标

- 单执行器请求不经过跨域调度器也能独立生成、验证、编译和执行。
- 多执行器请求复用完全相同的领域插件，不在场景层复制领域逻辑。
- 生成层、验证层、编译层和执行层分离，使 LLM 输出错误不能直接影响总线。
- 领域成员可以并行开发，不修改其他领域目录，不争用 DBC 和公共运行时代码。

## 分层与依赖

```text
apps
  -> application                 用例入口、事务边界、权限和任务状态
      -> agent                   文本到 IntentIR/配置候选
      -> orchestration           跨域场景规划和 DAG 调度
      -> runtime                 校验、编译、安全门禁和执行生命周期
          -> registry            发现领域插件和能力
          -> sdk                 领域插件唯一可依赖的公共接口
          -> infrastructure      LLM、CAN、存储、遥测实现

domains/* -> sdk + contracts     不反向依赖 apps/application/orchestration
platforms/*                      由 infrastructure/can 在运行时加载
```

禁止依赖：

- `domains/seat` 直接导入 `domains/climate` 等其他领域。
- 领域插件直接调用 LLM、Web API 或发送 CAN 帧。
- 场景编排器按 CAN signal 名称编排；它只能按 `FunctionConfig` 和领域能力编排。
- LLM 输出物绕过 Schema、领域约束或平台安全校验。

## 核心对象

| 对象 | 产生者 | 消费者 | 作用 |
| --- | --- | --- | --- |
| `IntentIR` | Agent | Router / Planner | 结构化保存用户意图、目标领域、歧义和置信度 |
| `FunctionConfig` | 领域 Generator | Validator / Compiler | 描述单一领域的目标状态和过渡要求 |
| `SceneConfig` | Scene Planner | Orchestrator | 引用多份功能配置并定义依赖、时序和失败策略 |
| `CommandPlan` | 领域 Compiler | Safety Guard / Executor | 描述已经解析到 DBC message/signal 的确定性命令 |
| `TraceEvent` | 各流水线阶段 | API / Web / Audit | 可审计的摘要、输入输出引用、耗时和状态 |

`contracts/schemas/` 是对象格式的唯一事实来源。Python/TypeScript 模型应由 Schema 生成或通过契约测试保持一致。

## 单领域链路

1. Agent 把文本解析为 `IntentIR`，Router 只识别出一个领域。
2. Registry 获取该领域插件及能力目录。
3. 领域 Generator 使用意图、preset 和当前车辆上下文生成 `FunctionConfig`。
4. Runtime 先做公共 Schema 校验，再调用领域参数 Schema 和语义 Validator。
5. Compiler 结合 `platforms/<vehicle>/` 的映射和标定生成 `CommandPlan`。
6. Safety Guard 检查范围、互锁、权限、车辆状态和速率限制。
7. Executor 先 dry-run；获准后通过公共 CAN Gateway 执行并回读状态。

单领域路径不生成 `SceneConfig`，避免无意义的跨域耦合。

## 跨域链路

1. Router 识别两个及以上领域，Scene Planner 生成 `SceneConfig` 草案。
2. 每个领域仍由自己的 Generator 生成一份 `FunctionConfig`。
3. 各领域独立校验和编译，失败不会污染其他领域配置。
4. Orchestrator 校验引用完整性、依赖 DAG、资源冲突和整体安全策略。
5. Scheduler 根据 `depends_on`、`start_offset_ms` 和 `failure_policy` 执行。
6. 执行报告同时保存每个领域结果和场景汇总结果。

## 安全边界

- 默认环境必须是 `dry_run`；真实下发由部署环境、权限和车辆状态三重控制。
- 领域 `signal-mapping.yaml` 只引用 DBC 中的 message/signal，不保存仲裁 ID 和位定义副本。
- `CommandPlan` 不接受任意 raw payload；编码由 `cantools` 类 DBC 编码器完成。
- 安全限值是平台标定，不由 LLM 或功能 preset 覆盖。
- 执行前保存配置摘要和版本，执行后保存回读、超时、拒绝和补偿结果。

## 前端可观测性

Web 控制台可展示：意图摘要、识别领域、选用能力、歧义/确认项、配置文件、校验结论、安全检查、调度状态和执行结果。不要展示或声称展示 GPT 的私有 chain-of-thought；使用 `TraceEvent.summary` 提供简洁、可验证的决策理由。