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` 提供简洁、可验证的决策理由。
+

docs/decisions/0001-semantic-config-before-can.md

@@ -0,0 +1,20 @@
+# ADR-0001: 先生成语义配置，再编译 CAN 命令
+
+- 状态：Accepted
+- 日期：2026-07-22
+
+## 背景
+
+自然语言存在歧义，LLM 输出非确定，CAN 控制则要求确定、可验证、可审计。允许模型直接生成帧会跳过单位、范围、互锁、DBC 和车辆状态检查。
+
+## 决策
+
+LLM 输出限制在 `IntentIR`、`FunctionConfig` 和 `SceneConfig`。领域 Compiler 使用版本化能力定义、平台标定和 DBC 映射生成 `CommandPlan`。公共 CAN Gateway 是唯一允许编码和发送 CAN 的组件。
+
+## 结果
+
+- 配置可在无车环境生成、审查和回放。
+- 领域测试可以对命令计划做稳定的 golden comparison。
+- 增加了契约和编译层，但显著缩小模型错误的执行影响面。
+- 平台切换只替换 DBC/标定和映射，不需要重写自然语言层。
+

docs/governance/ownership.md

@@ -0,0 +1,26 @@
+# 所有权与变更边界
+
+| 路径 | 主要负责人 | 领域成员权限 | 变更要求 |
+| --- | --- | --- | --- |
+| `domains/<domain>/` | 对应领域负责人 | 可直接修改本领域 | 本领域评审 + 契约测试 |
+| `contracts/` | 整体开发/架构负责人 | 只读，提变更申请 | 版本评估 + 全领域评审 |
+| `platforms/` | CAN/集成负责人 | 只读，提交映射需求 | DBC/标定评审 + HIL 验证 |
+| `src/cognitive_agent/` | 整体开发负责人 | 只读，提接口需求 | 中央运行时评审 |
+| `apps/` | API/Web 负责人 | 通过公共 API 集成 | API 契约测试 |
+| `tests/contract` | 整体开发负责人 | 可补用例，不改基准语义 | 全领域回归 |
+| `tests/integration`、`tests/e2e` | 整体开发负责人 | 提供领域 fixture | 集成环境验证 |
+
+## 公共契约版本
+
+- 仅增加可选字段：minor 版本。
+- 新增必填字段、改变语义或删除字段：major 版本，并提供迁移窗口。
+- 文档和错误修正且不改变行为：patch 版本。
+- 运行时至少同时支持当前 major 和迁移中的前一个 major；具体周期由发布计划决定。
+
+## 冲突预防
+
+- 能力名采用 `<domain>.<verb_object>`，例如 `seat.set_posture`。
+- operation id 只在单份配置内唯一；跨域唯一性由 request id + domain + operation id 组成。
+- 领域映射不复制 DBC bit layout，只引用中央 message/signal 名称。
+- 跨域规则放在 `src/cognitive_agent/orchestration/` 或平台策略中，不放入任一领域插件。
+

docs/workflows/domain-delivery.md

@@ -0,0 +1,49 @@
+# 领域交付流程
+
+## 首次领取
+
+每位成员复制 `domains/_template/` 为自己的 ASCII 领域名。首批成员已经分配：
+
+| 人员角色 | 唯一主目录 | 领域标识 |
+| --- | --- | --- |
+| 座椅负责人 | `domains/seat/` | `seat` |
+| 空调负责人 | `domains/climate/` | `climate` |
+| 氛围灯负责人 | `domains/ambient_light/` | `ambient_light` |
+| 天幕负责人 | `domains/roof/` | `roof` |
+
+成员不得把本领域代码放入中央 `src/cognitive_agent/`，也不得在其他领域目录建立调用关系。
+
+## 开发顺序
+
+1. 在 `manifest.yaml` 登记插件入口、Schema、能力清单和信号映射路径。
+2. 在 `config/capabilities.yaml` 定义稳定的语义能力名称、参数和目标类型。
+3. 在 `schemas/function-parameters.schema.json` 定义参数类型、单位、必填项和结构约束。
+4. 在 `config/presets/` 定义经产品/控制工程确认的模式默认值。
+5. 在 `can/signal-mapping.yaml` 把能力参数映射到中央 DBC 的 message/signal 名称。
+6. 实现 Generator、Validator、Compiler 和 Telemetry Decoder。
+7. 完成 unit、contract、integration 测试；硬件测试需使用 `hardware` marker。
+
+## 插件职责
+
+- Generator：把已经路由到本领域的 `IntentIR` 转成 `FunctionConfig`，不得产生其他领域操作。
+- Validator：执行超出 JSON Schema 的业务约束，例如参数组合、执行器互锁和模式可用条件。
+- Compiler：使用车型标定把语义目标确定性转换为 `CommandPlan`，不得直接发帧。
+- Telemetry Decoder：把回读信号转成领域状态，供完成条件和前端状态使用。
+- Tests：提供 golden 配置、golden 命令计划、错误用例和模拟总线用例。
+
+## Definition of Done
+
+- 所有能力都有明确参数、单位、范围来源和目标执行器。
+- 每个 preset 均可展开为合法 `FunctionConfig`，且没有隐藏硬编码。
+- 编译结果只引用中央 DBC 中存在的 message/signal。
+- 相同输入重复编译结果一致。
+- 缺字段、错误单位、越界、互锁冲突、超时、回读不一致均有测试。
+- `README.md` 记录未决标定项、HIL/实车前置条件和已知限制。
+
+## 集成提交流程
+
+1. 领域成员提交本领域 PR，并附至少一个自然语言到 dry-run 的演示用例。
+2. CI 运行公共契约测试和该领域测试。
+3. 集成人员审查公共能力命名、平台映射和安全边界。
+4. 合并后运行全部领域回归；第二阶段再把该能力加入跨域场景测试。
+

docs/workflows/integration-roadmap.md

@@ -0,0 +1,77 @@
+# 集成路线
+
+## M0：公共契约冻结
+
+整体开发负责人完成：
+
+- 确认四个领域标识、目标 zone/instance 命名和首个 reference platform。
+- 评审 `IntentIR`、`FunctionConfig`、`FunctionPreset`、`CommandPlan` 和错误模型。
+- 发布 SDK v0.1、虚拟 CAN Gateway 和契约测试基线。
+- 把 `contracts/`、`platforms/` 和中央 `src/` 设置为受保护路径。
+
+准入条件：四位领域负责人能够只在自己的目录中完成一个静态 preset 的公共 Schema 校验。
+
+## M1：单领域闭环（并行开发）
+
+每个领域独立交付：
+
+```text
+一句话 -> IntentIR -> Domain Generator -> FunctionConfig
+       -> Domain Validator -> Compiler -> CommandPlan
+       -> Virtual CAN -> Telemetry -> ExecutionReport
+```
+
+中央团队同期交付 Registry、公共 Runtime、artifact writer、事件流和 API 的 dry-run 接口。领域成员不各自实现 Agent 服务、HTTP 服务或 CAN sender。
+
+合入门槛：
+
+- 至少 1 个 preset 和 3 个自然语言自定义参数用例。
+- 合法、边界、非法、歧义、超时、回读错误用例齐全。
+- 领域配置不能包含其他领域 capability。
+- golden `CommandPlan` 稳定，虚拟 CAN 测试可重复。
+- 映射和标定只有达到相应验证状态后才能进入 HIL/实车环境。
+
+## M1.5：单领域总线集成
+
+集成人员逐个接入真实 DBC 和 HIL，顺序执行而非一次接入全部领域。每接入一个领域：
+
+1. 锁定 DBC hash 和平台标定版本。
+2. 检查 command rate、counter/checksum、session/enable 信号和完成回读。
+3. 验证急停、超时、进程重启、总线断开和 ECU 拒绝。
+4. 将映射状态从 `draft` 提升为 `hil_verified`；实车验证后再提升为 `vehicle_verified`。
+
+准入条件：四个领域均能经同一个 Runtime 和 CAN Gateway 独立 dry-run；需要进入场景的领域至少达到 HIL 可用状态。
+
+## M2：跨域场景编排
+
+整体开发负责人实现：
+
+- 多领域 Router 和 Scene Planner。
+- `SceneConfig` 引用解析、DAG 校验、资源锁和跨域策略。
+- parallel/sequential/DAG 调度、失败传播、取消和补偿。
+- 场景级 artifact、trace 和 ExecutionReport 汇总。
+
+领域插件不增加场景特有代码。一个场景中的四份 `FunctionConfig` 必须仍可脱离场景单独执行。
+
+首批集成场景建议只覆盖：
+
+- 两领域并行且都成功。
+- 一个领域失败导致全场景终止。
+- 非关键领域失败后继续。
+- 有依赖和时间偏移的 DAG。
+- 两个 operation 竞争同一物理资源时拒绝执行。
+
+## M3：一句话 Web 闭环
+
+API/Web 团队实现请求输入、结构化事件流、配置查看、歧义确认、dry-run 和执行报告。页面只展示可审计的事实与决策摘要：识别的领域、采用的能力、默认值来源、验证结论、安全门禁和执行回读。
+
+准入条件：用户可以在一个 request id 下追踪从文本到配置再到 dry-run/执行报告的完整记录；任何硬件执行都需要明确环境标识和二次确认。
+
+## 推荐合入节奏
+
+1. 先合公共契约和虚拟 Runtime 基线。
+2. 四个领域以独立 PR 并行合入，不等待其他领域。
+3. 每次公共契约调整触发四领域契约回归。
+4. M1 完成后冻结 FunctionConfig v1，再开始 SceneConfig 运行时开发。
+5. Web 先消费 mock `TraceEvent`，待 API 稳定后切换真实事件流。
+

docs/workflows/seat-stage1-delivery.md

@@ -0,0 +1,110 @@
+# 座椅阶段一交付
+
+## 已交付链路
+
+```text
+用户文本
+  -> GPT Structured Outputs（Capability Registry + 当前会话状态）
+  -> 通用能力请求 + 领域路由
+  -> IntentIR
+  -> seat Generator
+  -> FunctionConfig
+  -> 公共 Schema + seat 参数 Schema + 语义校验
+  -> SeatCompiler
+  -> CommandPlan（热舒适真实来源信号 / 位置电机虚构信号）
+  -> Safety Guard（强制 dry-run）
+  -> VirtualSeatExecutor
+  -> 位编码 + 模拟位置/运动/故障回读
+  -> TraceEvent + ExecutionReport + Web 展示 + artifacts
+```
+
+## 当前可执行能力
+
+| capability | target | parameter | 0x42A signal |
+| --- | --- | --- | --- |
+| `seat.set_ventilation` | `front_left` | `state: on/off` | `Driver_Seat_Ventilation_S` |
+| `seat.set_heating` | `front_left` | `state: on/off` | `Driver_Seat_Heating_S` |
+| `seat.set_ventilation` | `front_right` | `state: on/off` | `Front_Passenger_Seat_Ventilation_S` |
+| `seat.set_heating` | `front_right` | `state: on/off` | `Front_Passenger_Seat_Heating_S` |
+
+语义值 `on/off` 由 Compiler 确定性映射为矩阵枚举 `1/2`。未出现在请求中的信号不进入 `CommandPlan`；虚拟编码时对应位保持 0（矩阵中的 invalid）。
+
+## 虚构位置电机能力
+
+| capability | 0% | 100% |
+| --- | --- | --- |
+| `seat.set_longitudinal_position` | 最后 | 最前 |
+| `seat.set_cushion_tilt` | 坐垫前端最低 | 坐垫前端最高 |
+| `seat.set_backrest_recline` | 最直立 | 最后仰 |
+| `seat.set_legrest_height` | 完全降下 | 完全升起 |
+| `seat.set_legrest_extension` | 完全收回 | 完全伸出 |
+
+五轴均支持主副驾。模型必须基于会话中的当前位置将相对语句转换为绝对 `position_pct`；适配器不会自行解释“往后、躺一点、再伸长”。能力范围参考了厂商公开车主手册中常见的前后、坐垫倾角、靠背和腿部支撑调节，但 CAN 定义并非来自这些厂商。
+
+靠背和腿托同时接受精确夹角语义：
+
+- `seat.set_backrest_recline.angle_deg`：坐垫表面与靠背中心线夹角，虚构标定范围 `95–140°`。
+- `seat.set_legrest_height.angle_deg`：坐垫表面与腿托表面夹角，虚构标定范围 `95–160°`。
+
+GPT 保留用户指定的原始 `angle_deg`，适配器使用线性演示标定确定性转换为电机 `position_pct`；`FunctionConfig`、模拟反馈和孪生模型同时保留百分比与夹角。该换算只用于验证认知编排和 UI，不代表真实座椅运动学。
+
+`seat-motion-virtual-matrix.yaml` 使用虚构标准帧 `0x550/0x551` 控制主/副驾，用 `0x558/0x559` 反馈。每个命令包含绝对目标、轴使能掩码、计划内命令序号、模式和虚构 checksum；反馈包含实际位置、moving mask、fault mask 和 position-valid mask。`CommandPlan.completion` 要求位置在 `±1%` 内到位，虚拟执行报告保留起点、中间采样和终点。
+
+## 用户姿态预设
+
+`seat.save_posture_preset` 将指定座位当前五轴状态生成公共 `FunctionPreset`，按 `conversation_id + target + preset_name` 持久化。保存属于控制面操作，不生成 CAN 帧。`seat.apply_posture_preset` 只调用上下文中确实存在的同名预设，并在编译前展开为五个已注册的原子位置能力。
+
+典型连续链路：
+
+```text
+精确角度或模糊模式 -> 五轴 FunctionConfig -> 虚拟执行与状态回读
+-> 相对跟进调整 -> 保存当前状态为 FunctionPreset
+-> 后续按名称调用 -> 展开五轴 FunctionConfig -> 虚拟 CAN 执行
+```
+
+预设是当前演示会话拥有的 dry-run 数据，不是经控制工程、人体工学和车型安全验证的出厂模式。
+
+## Excel 归一化结果
+
+`domains/seat/can/seat-thermal-matrix.yaml` 保存 6 个报文、23 个信号：
+
+- `0x42A`：主/副驾通风、加热开关候选控制信号。
+- `0x4FA`：主/副驾通风、加热工作状态。
+- `0x29E`：主驾开关、模式和 1–5 档状态。
+- `0x3CE`：主驾通风/加热控制模式。
+- `0x3D3`：副驾开关、模式和 1–5 档状态。
+- `0x2AA / sub-id 0x01`：主/副驾档位配置状态。
+
+矩阵没有报文名称、Tx/Rx、周期、DLC、正式字节序、counter/checksum 或总线所有权。当前报文名是本地 alias，payload 长度是最高已用 bit 推导的最小长度，LSB0/Intel 编码也只是根据表中 Start Bit 与 Bit 列推断。
+
+因此以下值是演示结果，不是实车发送结论：
+
+```text
+打开主驾通风 + 关闭副驾加热
+0x42A minimum payload: 01 80
+```
+
+## 认知档位与主动阻断项
+
+- 1–3 档目标：写入 `FunctionConfig` 和会话状态，并生成 `LEVEL_COMMAND_SIMULATED` 警告；`0x42A` 仍只包含开关信号。
+- 4–5 档目标：超出当前自动舒适策略和 `0x4FA` 虚拟回读范围，主动阻断。
+- 零重力/姿态：可用虚构五轴、演示夹角标定和用户预设验证模型分解，但没有真实运动学或车型安全标定。
+- 硬件发送：平台、矩阵和映射均未达到 HIL/vehicle verified。
+- 显式控制语句缺目标或开关状态：进入 `needs_confirmation`；舒适反馈可依据会话目标和默认强度策略补全。
+
+## GPT 边界
+
+GPT 返回受动态 JSON Schema 约束的 `domain/capability/target_scope/operation/parameters`。Schema 中的领域、能力、作用域和参数来自各领域自有的 `config/capabilities.yaml`，不在中央 Prompt 中逐条编码用户语句。后端将同一 `conversation_id` 的当前档位和前序成功动作作为模型上下文，模型负责舒适语义、因果、跟进指令和跨域目标的理解。
+
+当 `planning_environment=dry_run_candidate_synthesis` 时，命名 preset 不是执行前提。对“休憩、休息、阅读”等可理解的模式目标，GPT 应使用已注册的原子能力生成保守的绝对位置候选方案，并在 `decision_summary` 中记录推断。“没有同名预设”本身不构成歧义；只有目标座位、期望结果或所需能力确实无法判断时才要求确认。这类百分比是模型推断的 dry-run 候选值，不是人机工程或车型标定结论。
+
+模型结果返回后，本地层只执行能力注册表一致性检查、参数校验、路由与域适配，不使用本地领域规则重新解释或改写 GPT 动作。未安装执行适配器的能力保留为 `deferred_requests`：纯未接入域请求返回 `capability_unavailable`，混合请求则先执行已接入子请求并返回 `partially_succeeded`。本地解析器只作为未配置 GPT 或 `auto` 模式调用失败时的显式降级。UI 展示 `decision_summary`、`model_requests` 和确定性阶段事件，不保存或展示模型私有 chain-of-thought。
+
+## 实车前置条件
+
+1. CAN 负责人确认 0x42A 的发送节点、报文周期、DLC、byte order、counter/checksum 和请求保持策略。
+2. 明确 0x4FA/0x29E/0x3D3 中哪个信号是权威完成回读，以及超时和故障值。
+3. 提供正式 DBC，并让 `signal-mapping.yaml` 通过 DBC 存在性检查。
+4. 增加点火、车速、乘员、温度和 ECU 模式等安全输入。
+5. 完成 virtual -> HIL -> vehicle 三阶段验证并更新 mapping status。
+6. 用车型 DBC 替换全部 `seat-motion-virtual-matrix.yaml` 帧，补齐物理坐标、防夹、电机电流和位置故障诊断。

docs/workflows/t2g-seat-hardware-bench.md

@@ -0,0 +1,102 @@
+# T2G 座椅真实硬件台架接入
+
+本链路把一句话生成的 `FunctionConfig` 确定性编译成统一 IAR 固件的真实经典 CAN 协议，并以开发板反馈作为成功依据。默认仍是 `dry_run`；只有服务端显式启用、请求提供正确授权令牌、固件 profile 匹配且目标通过配置门禁时，才会打开 CAN 适配器。绝对位置还会在发命令前实时检查板端 `Position_Valid`；未标定时仅允许显式、小幅相对指令使用受限定时/Hall 路径。主驾和副驾当前都是 `t2g_primary_seat` 的逻辑别名，两种指令驱动同一组实体电机、加热和通风。
+
+## 固件与拓扑
+
+仓库内的固件接口工程为：
+
+```text
+firmware\t2g\Seat_Controller_demo\IAR\Seat_Controller_demo.ewp
+```
+
+厂商 SDK 只作为外部编译依赖，默认根目录为：
+
+```text
+C:\Users\D30042075206\Desktop\T2G_Sample_Driver_Library_7.9.0
+```
+
+三个已验证 demo 已合并为一个单板统一固件；原工程继续作为能力来源和回归基线：
+
+| 来源 | IAR 工程 | 能力 | CAN |
+| --- | --- | --- | --- |
+| 加热基线 | `Seat_Backrest_Heater_demo` | 主驾靠背加热 | RX `0x3CE/0x29E`，TX `0x4FA` |
+| 通风基线 | `Seat_Fan_demo` | 主驾通风 | RX `0x29E`，TX `0x4FA` |
+| 移动/安全骨架 | `Seat_Move_demo` | 腿托伸缩/升降、靠背；Motor3 暂锁定 | RX `0x300`，TX `0x301/0x302/0x303` |
+| 仓库内单板交付 | `firmware/t2g/Seat_Controller_demo` | 上述能力、共享 CAN4/IRQ/WDT、固件身份握手 | 全部上述报文及 `0x304/0x305` |
+
+真实执行只接受仓库内 `combined` profile 和 `Seat_Controller_demo.hex/.out`。该工程用一个 CAN4 实例接收热管理与移动命令，`0x4FA` 同时填充通风 bits0..2 和加热 bits3..5；移动 ACK/反馈保持 `0x301/0x302/0x303`。三个原始 demo 镜像不再作为 Web 硬件执行入口。
+
+每次真实请求在控制帧发送前先执行不驱动执行器的身份握手：主机向 `0x304` 发送 `53 45 41 54 01 00 00 00`，固件必须在 `0x305` 返回 `53 45 41 54 01 01 00 3F`。该响应表示协议 1、固件 1.1.0 和统一能力掩码。响应缺失或不匹配时，后端不会发送加热、通风或电机命令。
+
+## 构建（不烧录）
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\tools\build_seat_firmware.ps1 -Profile combined
+```
+
+脚本把仓库内工程临时放到与 SDK `common/tviibh8m` 相同的相对拓扑中，调用 IAR EWARM 9.2 的 `iarbuild.exe` 构建 `rev_d`，再把 HEX/OUT 回写到仓库并输出 HEX SHA-256。脚本不包含下载、烧录或电机启动操作。
+
+后端自动烧录与构建脚本相互独立：只有真实台架请求已通过授权、`COGNITIVE_AGENT_SEAT_AUTO_FLASH_ENABLED=true`、身份握手失败且 IAR/C-SPY 依赖完整时，才会关闭 CAN，使用 CMSIS-DAP 和专用 `Seat_Controller_program.mac` 执行一次限时 Download-and-Debug，并以 `--leave_target_running` 把目标交还给新固件，随后重新打开 CAN 并再次验证 `0x305`。不能使用 `--download_only`，因为 IAR 会在下载后保持 CM0+ 停止。该宏在下载前强制关闭电机、风扇和加热输出并清除 program-only 调试标记；新固件从正常复位入口启动。二次验证失败时控制帧仍被阻断；交互调试仍使用原 `Seat_Controller_demo.mac` 的调试脱离故障锁存。
+
+## 物理链路检查
+
+1. 开发板 CAN4 使用 `RX=P3.7`、`TX=P3.6`，`P3.1` 为板载 CAN 收发器使能，高电平有效。
+2. ZLG 适配器、各开发板和执行器控制硬件必须共地；CANH 对 CANH、CANL 对 CANL，禁止反接。
+3. 总线两端各使用一个 120 Ω 终端；断电测量 CANH 与 CANL 之间应约为 60 Ω。短台架也只能保留总线两端的两个终端。
+4. 使用经典标准 CAN、11-bit ID、DLC 8、500 kbit/s；不要把旧版 32-byte CAN-FD 表用于当前 `Seat_Move_demo`。
+5. 先确认急停/断电手段、机械行程、夹伤区域、执行器电源能力和 Hall 接线，再上电。不要依赖 Web 软件替代物理急停。
+6. ZCANPRO 与本服务不能同时独占同一个适配器。启动服务前关闭 ZCANPRO 的在线通道。
+
+## 服务端启用
+
+把 `.env.example` 中相关变量复制到本机 `.env`，至少设置：
+
+```dotenv
+COGNITIVE_AGENT_HARDWARE_EXECUTION_ENABLED=true
+COGNITIVE_AGENT_HARDWARE_APPROVAL_TOKEN=123456
+COGNITIVE_AGENT_SEAT_FIRMWARE_PROFILES=combined
+COGNITIVE_AGENT_SEAT_AUTO_FLASH_ENABLED=true
+COGNITIVE_AGENT_IAR_CSPYBAT=D:\Program Files\IAR Systems\Embedded Workbench 9.2\common\bin\cspybat.exe
+COGNITIVE_AGENT_SEAT_CAN_BACKEND=zlgcan
+COGNITIVE_AGENT_SEAT_CAN_CHANNEL=0
+COGNITIVE_AGENT_SEAT_CAN_BITRATE=500000
+COGNITIVE_AGENT_ENABLE_UNVERIFIED_LONGITUDINAL=false
+```
+
+服务运行在 64 位 Python，ZCANPRO 的 `zlgcan.dll` 和内置 Python 是 32 位，因此主进程会启动 `zlgcan_bridge.py` JSON-line 子进程。运行时页面只显示“令牌已配置”和固件哈希，不返回令牌本身。
+
+可先做不打开设备的 DLL/ABI 自检：
+
+```powershell
+& 'C:\Program Files (x86)\ZCANPRO\python38\python.exe' `
+  '.\src\cognitive_agent\infrastructure\can\zlgcan_bridge.py' `
+  --dll 'C:\Program Files (x86)\ZCANPRO\zlgcan.dll' `
+  --device-type 41 --self-test
+```
+
+## 请求与反馈闭环
+
+前端选择“真实台架”，输入本次授权令牌后再提交。硬件路径只接受 `seat` 单域，`front_left/driver` 和 `front_right/passenger` 都映射到 `t2g_primary_seat`：
+
+- 固件：先执行 `0x304/0x305` 身份握手；必要时自动烧录并二次握手。烧录和身份验证结果写入 `ExecutionReport`，授权令牌不会写入制品。
+
+- 热/风：发送真实 `0x3CE/0x29E`，必须等到 `0x4FA` 的实际档位匹配。
+- 绝对移动：打开适配器后先发 `STOP_ALL` 并用 `0x301` 重同步 sequence；发送 Opcode `1` 前读取目标电机 `0x302.Position_Valid`。未标定时不会发送绝对移动帧，而是返回需要显式端点标定的错误。标定有效时必须收到匹配 sequence 的 ACCEPTED ACK，再等 `0x302` 返回 COMPLETE/OK、位置有效且在容差内。
+- 小幅相对移动：GPT 仍输出解析后的绝对目标，同时 `FunctionConfig.operation.motion` 保留 `increase/decrease`、起点和增量。未标定安全路径编译为 Opcode `3`、50% 定时占空比；时长按仓库内 500 ms 实测 Hall 速度确定，单次增量限制为 15%。成功必须同时满足 ACK、`0x302 COMPLETE/OK` 和固件内部“至少一个原始 Hall 边沿”门禁；后端还记录 `0x303` 的 Hall 前后值并核对可观测方向。
+- 拒绝、安全故障、Hall 未运动、方向不符、位置无效或超时：报告失败，并立即尽力再次发送 `STOP_ALL`；失败的动作不会写入会话状态。未标定相对移动成功时会话中的绝对百分比/角度明确标记为估计值，不能替代端点标定结果。
+
+Opcode `10` 的全行程端点标定会主动运动到两个机械端点，普通一句话请求绝不会静默触发。需要精确绝对角度时，应先在台架无遮挡、急停可用的维护流程中显式完成目标电机标定，并保存 clean 记录。
+
+如果一句话同时要求主驾和副驾对同一能力使用相同目标，编译器只发送一次实体命令，并把同一真实回读投影给两个逻辑目标；如果两侧对同一实体能力提出冲突目标，请求会在打开 CAN 之前被拒绝。真实执行成功后，两侧会话状态保持同步。
+
+Motor0（腿托伸缩）、Motor1（腿托升降）和 Motor2（靠背）已验证。Motor3（座椅前后）仍未接线、未实标，默认强制禁止。`seat.set_cushion_tilt` 在当前固件没有物理电机，始终禁止。只有完成 Motor3 接线、端点标定、方向核对和风险评审后，才能显式设置 `COGNITIVE_AGENT_ENABLE_UNVERIFIED_LONGITUDINAL=true`。
+
+## 建议上电顺序
+
+1. 保持服务为 `dry_run`，运行完整测试。
+2. 从仓库构建 `Seat_Controller_demo`。首次联调建议人工烧录并先用 ZCANPRO 观察周期反馈；确认 CMSIS-DAP、复位和供电链路后再启用自动烧录。
+3. 使用固件文档中的短时测试帧逐电机核对方向、Hall 与急停；Motor3 不参与。
+4. 关闭 ZCANPRO 在线通道，启用服务端环境变量；需要自动烧录时保持 CMSIS-DAP 连接并显式设置自动烧录开关。
+5. 前端先执行加热/通风 OFF，再做低档 ON；移动先从小行程、无遮挡状态开始。
+6. 对每次实际动作核对 `ExecutionReport.spec.mode=hil`、真实反馈帧和固件镜像哈希。