init

docs/architecture/overview.md

@@ -0,0 +1,77 @@
+# 总体架构
+
+## 设计目标
+
+- 单执行器请求不经过跨域调度器也能独立生成、验证、编译和执行。
+- 多执行器请求复用完全相同的领域插件，不在场景层复制领域逻辑。
+- 生成层、验证层、编译层和执行层分离，使 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` 提供简洁、可验证的决策理由。
+