Skip to main content
Glama
suzike

py-canoe

by suzike
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local
README.md
<p align="center">
  <img src="https://raw.githubusercontent.com/suzike/Agent2Canoe/main/docs/assets/agent2canoe-hero.png" alt="Agent2Canoe：AI 驱动的 CANoe 自动化开发工具包" width="100%">
</p>

<h1 align="center">Agent2Canoe</h1>

<p align="center">
  <strong>让 Claude Code、Codex 与其他 AI 智能体安全、可验证地驱动 Vector CANoe</strong>
</p>

<p align="center">
  从自然语言意图到能力发现、执行计划、人工确认、CANoe 操作与结构化证据，<br>
  为汽车电子自动化开发提供统一的 Python、REST 与 MCP 接口。
</p>

<p align="center">
  <a href="https://github.com/suzike/Agent2Canoe/actions/workflows/automation-tests.yml"><img alt="自动化测试" src="https://github.com/suzike/Agent2Canoe/actions/workflows/automation-tests.yml/badge.svg"></a>
  <a href="https://github.com/suzike/Agent2Canoe/actions/workflows/pylint.yml"><img alt="静态检查" src="https://github.com/suzike/Agent2Canoe/actions/workflows/pylint.yml/badge.svg"></a>
  <img alt="Python 3.10-3.14" src="https://img.shields.io/badge/Python-3.10--3.14-3776AB?logo=python&logoColor=white">
  <a href="https://github.com/suzike/Agent2Canoe/releases/tag/v0.4.0"><img alt="版本 0.4.0" src="https://img.shields.io/badge/version-0.4.0-7C3AED"></a>
  <img alt="Windows" src="https://img.shields.io/badge/platform-Windows-0078D4?logo=windows">
  <img alt="许可证 MIT" src="https://img.shields.io/badge/license-MIT-22C55E">
</p>

<p align="center">
  <a href="#快速开始">快速开始</a> ·
  <a href="#ai--mcp-接入">AI / MCP</a> ·
  <a href="docs/automation.md">自动化指南</a> ·
  <a href="docs/ai-agent-integration.md">集成文档</a> ·
  <a href="docs/development-status.md">开发状态</a> ·
  <a href="CHANGELOG.md">变更记录</a> ·
  <a href="README_EN.md">English</a>
</p>

---

## 为什么是 Agent2Canoe

传统 CANoe 自动化解决了“脚本如何调用工具”，Agent2Canoe 进一步解决“AI 如何理解工程、约束操作并证明结果”。

<table>
  <tr>
    <td width="33%" valign="top">
      <h3>🔎 先发现，再执行</h3>
      读取当前工程中的网络、数据库、信号、系统变量、诊断、测试与 CAPL 能力，避免 AI 凭空假设。
    </td>
    <td width="33%" valign="top">
      <h3>🛡️ 副作用可控</h3>
      写信号、改网络、运行诊断和测试前生成计划；危险步骤需要明确确认，并支持 dry-run。
    </td>
    <td width="33%" valign="top">
      <h3>📊 结果可审计</h3>
      返回结构化状态、测试统计、报告路径和执行证据，让智能体能够继续判断，而不是只得到一行日志。
    </td>
  </tr>
</table>

## v0.4.0 当前稳定版

`v0.4.0` 把“可治理的 AI 自动化平台”推进到真实 CANoe 离线工程闭环。当前稳定版包含
**30 个受策略约束的计划动作、58 个 MCP 工具和 53 个业务 REST 路由**，既保留
`v0.3.0` 的能力发现、确认令牌、身份权限、跨进程租约、持久化审计和测试证据，也新增
空白工程创建、数据库挂载、ASC/BLF/MDF 离线源管理、模式切换、保存退出重开验证以及
默认 CAN1 通道所有权保护。

| 本版重点 | 工程价值 |
|:---|:---|
| 模型提出、服务端复核 | LLM 只能提交受 Schema 约束的候选，不能自行确认或直接访问 COM |
| 参数绑定单次令牌 | 防止批准后的参数替换、跨会话使用、过期与重放 |
| SQLite + JSONL 证据链 | 保存计划、主体、审计、幂等结果、恢复检查点和测试历史 |
| 跨进程 FIFO 租约 | 多个 Codex、Claude Code 或服务进程不会同时修改同一 CANoe |
| 可验证工程操作 | 网络修改、日志导出和历史清理均采用预览/确认/回读或冲突检测 |
| 测试统计而非单次结论 | 支持趋势、Fisher/Wilson、分层冲突和显式容差等效性判断 |
| 真实离线工程闭环 | 从空白 CFG 创建到 DBC/ASC 加载、回放结束、保存退出和重开读回 |
| 通道所有权门禁 | Python、REST、MCP 均拒绝抢占已归属的软件通道，避免生成不可测工程 |

发布包、校验清单和完整升级说明见
[Agent2Canoe v0.4.0 Release](https://github.com/suzike/Agent2Canoe/releases/tag/v0.4.0)。

<p align="center">
  <img src="https://raw.githubusercontent.com/suzike/Agent2Canoe/main/docs/assets/agent2canoe-architecture.svg" alt="Agent2Canoe 分层架构：AI 客户端、接入层、编排安全层、CANoe 自动化层和工程资产" width="96%">
</p>

## 当前稳定版能做什么

| 能力域 | 已集成能力 | 可用入口 |
|:---|:---|:---:|
| **CANoe 会话** | 从空白创建/打开/附着配置、启动/停止测量、恢复与受控退出 | Python · REST · MCP |
| **离线回放** | MCP 创建非模板工程、加载 DBC 与 ASC/BLF/MDF、保存重开、模式读回和自动停止对账 | Python · MCP |
| **工程能力发现** | 版本 provider、分区探针、网络、信号、变量、诊断、测试与降级证据 | REST · MCP |
| **网络管理** | 事务预览、快照冲突检测、批量增删、回读验证与失败回滚 | Python · REST · MCP |
| **测试结果工程** | 趋势、分层方向冲突、工程等效性、Fisher/Wilson 统计、JUnit/Allure/HTML 报告与两阶段保留策略 | Python · REST · MCP |
| **AI 安全编排** | 计划预览、短时单次令牌、幂等重试、持久化审计与恢复检查点 | REST · MCP |
| **身份与权限** | API Key 摘要、mTLS、五级角色权限、签发者/执行者审计 | REST · MCP |
| **硬件安全基础层** | XL Driver 运行库探测、Provider 隔离、指纹快照与无副作用映射预览 | Python · REST · MCP |
| **工程环境基线** | 脱敏环境自检、稳定指纹、可版本化基线与漂移比较 | Python · REST · MCP |
| **多智能体协调** | 跨进程独占租约、FIFO 队列、过期接管、心跳续期与并发冲突拒绝 | Python · REST · MCP |
| **诊断安全访问** | 服务端 Provider 注册、外部进程隔离、Seed/Key 全链路脱敏与 `0x27` 绕过拒绝 | Python · REST · MCP |
| **Measurement Setup** | 日志块检查、名称过滤、时间区间、服务端托管导出、非空与 SHA-256 证据 | Python · REST · MCP |

> **硬件安全边界**
>
> 物理硬件通道写映射仍保持关闭。当前稳定版可只读探测 XL Driver、输出硬件快照并
> 预览 CANoe 1-based 软件通道到 XL Driver 0-based 物理通道的映射；原生枚举仍依赖
> 可审计的官方 SDK、ABI 核验和真实 VN 设备回归，不打包第三方二进制。

<p align="center">
  <img src="https://raw.githubusercontent.com/suzike/Agent2Canoe/main/docs/assets/agent2canoe-ai-workbench.png" alt="AI 智能体通过安全编排连接汽车网络测试台架" width="100%">
</p>

## AI 执行闭环

<p align="center">
  <img src="https://raw.githubusercontent.com/suzike/Agent2Canoe/main/docs/assets/agent2canoe-workflow.svg" alt="从自然语言任务到 CANoe 执行与证据回传的七步闭环" width="96%">
</p>

AI 不应直接把一句自然语言变成不可见的 COM 调用。Agent2Canoe 将工作拆成可检查的步骤：

1. 读取 `canoe_status`，确认会话与测量状态。
2. 调用 `describe_agent_capabilities`，了解接口、约束和确认策略。
3. 调用 `discover_capabilities`，发现当前工程真正存在的对象。
4. 受约束命令使用 `plan_task`；自由工程语言读取
   `get_planning_contract` 后通过 `plan_model_output` 提交受 Schema 约束的候选。
5. 用户确认带副作用的步骤；调用 `confirm_plan_steps` 获取参数绑定令牌。
6. 将步骤 ID 与短时单次令牌传给 `execute_plan`。
7. 根据结构化返回值复核实际状态、统计与证据。

## 快速开始

### 1. 准备环境

Agent2Canoe 运行于 Windows。真实自动化需要本机已安装并获得许可的 Vector CANoe；
没有 CANoe 时仍可使用 Mock 后端开发和验证 AI 工作流。

```powershell
git clone https://github.com/suzike/Agent2Canoe.git
cd Agent2Canoe
uv sync --all-extras
```

### 2. 用 Python 控制 CANoe

```python
from agent2canoe import Agent2Canoe

canoe = Agent2Canoe()
canoe.open(r"C:\work\demo.cfg")
canoe.start_measurement()

for network in canoe.list_networks():
    print(network)

canoe.stop_measurement()
```

### 3. 不连接 CANoe 先验证

```powershell
# 查看命令行入口
uv run agent2canoe --version

# 启动 Mock REST 服务
uv run agent2canoe-api --mock --port 8765

# 启动 Mock MCP 服务
uv run agent2canoe-mcp --mock --principal codex-local --roles viewer,operator,approver
```

## AI / MCP 接入

Claude Code、Codex 或其他支持 MCP 的客户端可通过 stdio 启动 Agent2Canoe：

```json
{
  "mcpServers": {
    "Agent2Canoe": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\Agent2Canoe",
        "run",
        "agent2canoe-mcp",
        "--principal",
        "codex-workbench",
        "--roles",
        "viewer,operator,approver"
      ]
    }
  }
}
```

### MCP 工具一览

| 工具组 | 代表工具 | 用途 |
|:---|:---|:---|
| 状态与发现 | `canoe_status` · `describe_agent_capabilities` · `discover_capabilities` | 建立真实工程上下文 |
| 计划契约 | `get_planning_contract` · `plan_model_output` | 约束 LLM 输出并绑定真实能力快照 |
| 计划与执行 | `plan_task` · `execute_plan` | 预览、确认并执行确定性计划 |
| 确认授权 | `request_confirmation_token` · `confirm_plan_steps` | 为已批准的精确参数签发短时单次令牌 |
| 审计与恢复 | `list_audit_records` · `get_recovery_checkpoint` · `restore_recovery_checkpoint` | 查询脱敏证据，先预览再恢复会话 |
| 网络事务 | `preview_network_transaction` · `commit_network_transaction` | 预览差异，确认后批量修改、回读并在失败时回滚 |
| 兼容网络操作 | `list_networks` · `add_network` · `remove_network` | 单项操作也经事务内核执行 |
| 工程操作 | 信号、系统变量、诊断、测试相关工具 | 驱动具体 CANoe 工作 |
| 测试历史 | `compare_test_results` · `export_test_results` · `preview_test_result_retention` · `prune_test_results` | 分层/等效性分析、可视化报告与快照冲突保护清理 |
| 硬件清单与预览 | `audit_hardware_mapping` · `get_hardware_inventory` · `preview_hardware_mapping` | 只读审计、快照和候选映射，不执行写入 |
| 环境与基线 | `inspect_environment` · `get_environment_baseline` · `compare_environment_baseline` | 无副作用自检并阻止环境漂移下的盲目执行 |
| 多会话协调 | `runtime_lease_status` · `request_runtime_lease` · `renew_runtime_lease` · `release_runtime_lease` | 协调多个 AI 客户端对同一 CANoe 的写入时隙 |
| 诊断安全访问 | `describe_security_key_providers` · `run_security_access` | 只选择服务端 Provider，不向 AI 暴露 Seed、Key 或算法命令 |
| Measurement Setup | `list_measurement_logging_blocks` · `inspect_measurement_logging_block` · `export_measurement_log` | 检查日志块并将结果导出到服务端托管目录 |
| 离线回放 | `attach_to_active_canoe` · `list_offline_sources` · `add_offline_source` · `remove_offline_source` · `get_configuration_mode` · `set_configuration_mode` | 附着现有实例，管理 ASC/BLF/MDF 离线源并读回模式；修改操作需要确认令牌 |
| 工程与数据库 | `create_configuration` · `list_databases` · `add_database` · `save_configuration` · `save_configuration_as` · `quit_canoe` | 从空白创建非模板工程，挂载 DBC/ARXML/XML，保存退出并重开校验；修改操作需要确认令牌 |

完整配置、确认语义和调用示例参见
[AI 智能体集成指南](https://github.com/suzike/Agent2Canoe/blob/main/docs/ai-agent-integration.md)。
多个 AI 客户端共用同一 CANoe 时，请同时参见
[多会话租约与并发协调](https://github.com/suzike/Agent2Canoe/blob/main/docs/runtime-leases.md)。
ASC 离线回放的调用顺序、真实回归证据和 CANoe 12 Graphics 自动化边界见
[MCP 离线源与 Graphics 边界](https://github.com/suzike/Agent2Canoe/blob/main/docs/offline-source-mcp.md)。

## REST API

```powershell
uv run agent2canoe-api --mock --port 8765
```

| 方法 | 路径 | 用途 |
|:---:|:---|:---|
| `GET` | `/agent/capabilities` | 返回 AI 能力、约束与接口清单 |
| `GET` | `/security/whoami` | 返回当前主体、角色、权限与认证方式 |
| `GET` | `/capabilities` | 发现当前 CANoe 工程对象 |
| `GET` | `/planning/contract` | 返回能力指纹和严格 LLM 输出 Schema |
| `POST` | `/plans` | 由自然语言或结构化任务生成计划 |
| `POST` | `/plans/model` | 校验 LLM 候选并生成不可绕过安全策略的计划 |
| `POST` | `/confirmations` | 为一个已批准的直接操作签发令牌 |
| `POST` | `/plans/{id}/confirmations` | 为选定计划步骤签发令牌 |
| `POST` | `/plans/{id}/execute` | 在确认策略约束下执行计划 |
| `GET` | `/audit/records` | 按游标、类型或计划查询持久化脱敏审计 |
| `GET/POST` | `/recovery/checkpoint[/{id}]` | 查询、预览或确认执行恢复检查点 |
| `GET/POST/DELETE` | `/networks` | 网络管理 |
| `POST` | `/networks/transactions/preview` | 返回写前快照、差异和确认参数 |
| `POST` | `/networks/transactions/commit` | 校验快照后提交、回读并按需回滚 |
| `GET` | `/tests/results[/trends|/compare|/export]` | 查询趋势、总体/分层统计、工程等效性及标准报告导出 |
| `POST` | `/tests/results/retention/{preview|commit}` | 预览候选，确认后按快照指纹清理历史 |
| `GET` | `/hardware/audit` | 只读硬件映射前提审计 |
| `GET` | `/hardware/inventory` | 返回带稳定指纹的只读硬件快照 |
| `POST` | `/hardware/mappings/preview` | 预览软件通道到物理通道的匹配，不写入 |
| `GET` | `/environment/report` | 返回不含路径和环境变量值的只读环境报告 |
| `GET/POST` | `/environment/baseline[/compare]` | 生成可版本化基线并比较当前环境漂移 |
| `GET/POST/DELETE` | `/coordination/leases[...]` | 申请、轮询、续期、释放租约或取消排队 |
| `GET/POST` | `/diagnostics/security-providers` · `/diagnostics/security-access` | 查询脱敏 Provider 元数据并执行受保护的 UDS 解锁 |
| `GET/POST` | `/measurement/logging-blocks[...]` · `/measurement/exports` | 检查日志配置并以确认令牌执行受限导出 |

直接写操作缺少有效令牌时返回 `HTTP 428`。令牌绑定运行时会话、动作、参数哈希和
有效期，且只能使用一次；详细协议见
[短时确认令牌](https://github.com/suzike/Agent2Canoe/blob/main/docs/confirmation-tokens.md)。
REST 可启用 API Key 摘要认证和 mTLS，MCP stdio 可指定进程主体与最小角色；
完整配置见
[身份认证、角色权限与 mTLS](https://github.com/suzike/Agent2Canoe/blob/main/docs/security-and-identity.md)。
REST 与 MCP 命令行入口默认把审计、计划、幂等结果和检查点保存到本地 SQLite；
可选 JSONL 镜像及恢复流程见
[持久化审计、幂等与恢复](https://github.com/suzike/Agent2Canoe/blob/main/docs/persistence-and-recovery.md)。
多网络变更应使用预览与提交两阶段接口；完整协议见
[可验证网络事务](https://github.com/suzike/Agent2Canoe/blob/main/docs/network-transactions.md)。
版本识别、兼容状态和分区探针语义见
[CANoe 版本兼容与能力探针](https://github.com/suzike/Agent2Canoe/blob/main/docs/canoe-version-compatibility.md)。
自由自然语言的两阶段 Schema、能力指纹和 Provider 接口见
[LLM 结构化规划适配器](https://github.com/suzike/Agent2Canoe/blob/main/docs/llm-planning-adapter.md)。

## 项目结构

```text
Agent2Canoe/
├─ src/
│  ├─ agent2canoe/          # 新品牌公共入口
│  └─ py_canoe/             # CANoe 实现与兼容层
│     └─ automation/        # 发现、计划、安全、REST、MCP、硬件审计
├─ tests/                   # 单元、Mock、接口与显式 opt-in 实机测试
├─ examples/                # 可版本化环境基线与 Provider 配置示例
├─ scripts/                 # 开发和验证辅助脚本
└─ docs/                    # 指南、开发状态、发布说明与 API 参考
```

v0.4.0 的首选导入路径是 `agent2canoe`。底层 `py_canoe` 暂作为兼容层保留，
已有脚本可渐进迁移；新的 CLI、发布包、文档和 MCP 标识统一使用 Agent2Canoe。

## 开发与质量门禁

```powershell
uv run ruff check src/agent2canoe src/py_canoe/automation scripts/real_mcp_offline_replay.py
uv run pytest -q
uv build
uv run mkdocs build --strict
```

CI 还会对维护中的自动化测试文件执行 Ruff；精确清单以
[自动化工作流](https://github.com/suzike/Agent2Canoe/blob/main/.github/workflows/automation-tests.yml)
和[静态检查工作流](https://github.com/suzike/Agent2Canoe/blob/main/.github/workflows/pylint.yml)为准，
避免把旧核心已知债务误报成当前发布面已清零。

真实 CANoe 集成测试不会默认执行，需显式设置：

```powershell
$env:AGENT2CANOE_RUN_INTEGRATION = "1"
uv run pytest -m integration
```

| 当前基线 | 结果 |
|:---|:---:|
| 默认测试套件 | **410 passed · 27 skipped** |
| 自动化维护子集 | **161 passed** |
| Python 版本矩阵 | **3.10 · 3.12 · 3.14** |
| 文档严格构建 | **通过** |
| Wheel 隔离安装与导入 | **通过** |

> 以上为当前 `main` 本地验证结果；发布基线和最新 CI 状态以
> [GitHub Actions](https://github.com/suzike/Agent2Canoe/actions) 为准。

真实 CANoe 12.0.75 已通过 58 工具 stdio MCP 从 `Application.New` 创建非模板工程
`AfterBlow_T109.cfg`，加载真实 EVBUS DBC 和 165 MB `Logging_T109NoTrigger.asc`，完成
Offline 回放自动停止、保存、退出与重开，并再次读回 1 个数据库和 1 个离线源。Mock
结果只作为快速回归，发布前的功能完成结论必须有真实 CANoe、真实工程资产和可重开的
证据；缺少许可证、工程、DBC、Log 或硬件条件时明确标为未验证。

实机也验证了一个关键安全边界：空白配置的 CAN1 已归默认 `CAN` 网络所有时，不可再
创建 `EVBUS/CAN1` 抢占该通道，否则该离线工程无法启动测量。网络事务现会在任何写入前
拒绝这种迁移；智能体应先列举网络，再将 DBC 挂载到拥有目标通道的现有网络。

## 版本路线

| 版本 | 主题 | 状态 |
|:---:|:---|:---:|
| `v0.1.0` | 本地工程基线、基础自动化与中文文档 | ✅ 已完成 |
| `v0.2.0` | Agent2Canoe 品牌、测试统计、网络管理、AI 发现与 MCP | ✅ 已发布 |
| `v0.3.0` | 安全 LLM 规划、身份治理、租约、网络事务、测试证据和受控导出 | ✅ 已发布 |
| `v0.4.0` | 真实离线工程创建、DBC/ASC 回放闭环、COM 稳定性和 CAN1 所有权门禁 | ✅ 已发布 |
| `v0.5.x` | 证据包归档、工程模板、原生 XL Driver 枚举与硬件实验台验证 | 🧭 规划中 |

进一步的风险、技术债与能力增强建议见
[当前开发状态](https://github.com/suzike/Agent2Canoe/blob/main/docs/development-status.md)、
[v0.2.0 历史工程审计](https://github.com/suzike/Agent2Canoe/blob/main/docs/engineering-audit-v0.2.0.md) 和
[硬件通道映射独立审计](https://github.com/suzike/Agent2Canoe/blob/main/docs/hardware-channel-mapping-audit.md)。

## 文档导航

- [自动化平台指南](https://github.com/suzike/Agent2Canoe/blob/main/docs/automation.md)
- [AI 智能体与 MCP 集成](https://github.com/suzike/Agent2Canoe/blob/main/docs/ai-agent-integration.md)
- [LLM 结构化规划适配器](https://github.com/suzike/Agent2Canoe/blob/main/docs/llm-planning-adapter.md)
- [短时确认令牌](https://github.com/suzike/Agent2Canoe/blob/main/docs/confirmation-tokens.md)
- [身份认证、角色权限与 mTLS](https://github.com/suzike/Agent2Canoe/blob/main/docs/security-and-identity.md)
- [持久化审计、幂等与恢复](https://github.com/suzike/Agent2Canoe/blob/main/docs/persistence-and-recovery.md)
- [可验证网络事务](https://github.com/suzike/Agent2Canoe/blob/main/docs/network-transactions.md)
- [测试结果历史、趋势与标准导出](https://github.com/suzike/Agent2Canoe/blob/main/docs/test-result-history.md)
- [CANoe 版本兼容与能力探针](https://github.com/suzike/Agent2Canoe/blob/main/docs/canoe-version-compatibility.md)
- [硬件通道映射独立审计](https://github.com/suzike/Agent2Canoe/blob/main/docs/hardware-channel-mapping-audit.md)
- [诊断 SecurityAccess 密钥提供者](https://github.com/suzike/Agent2Canoe/blob/main/docs/security-access-providers.md)
- [Measurement Setup 日志导出](https://github.com/suzike/Agent2Canoe/blob/main/docs/measurement-setup-exports.md)
- [v0.4.0 当前开发状态与后续路线](https://github.com/suzike/Agent2Canoe/blob/main/docs/development-status.md)
- [v0.4.0 正式发布说明](https://github.com/suzike/Agent2Canoe/blob/main/docs/releases/v0.4.0.md)
- [v0.3.0 正式发布说明](https://github.com/suzike/Agent2Canoe/blob/main/docs/releases/v0.3.0.md)
- [v0.2.0 历史工程审计](https://github.com/suzike/Agent2Canoe/blob/main/docs/engineering-audit-v0.2.0.md)
- [版本变更记录](https://github.com/suzike/Agent2Canoe/blob/main/CHANGELOG.md)
- [安全策略](https://github.com/suzike/Agent2Canoe/blob/main/SECURITY.md)

## 许可证

Agent2Canoe 采用 [MIT License](https://github.com/suzike/Agent2Canoe/blob/main/LICENSE)。Vector、CANoe 及相关产品名称归其各自权利人所有；
本项目不随包分发 CANoe、Vector SDK 或驱动二进制文件。

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources