Agent2Canoe

让 Claude Code、Codex 与其他 AI 智能体安全、可验证地驱动 Vector CANoe

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

快速开始 · AI / MCP · 自动化指南 · 集成文档 · 开发状态 · 变更记录 · English

为什么是 Agent2Canoe

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

🔎 先发现，再执行

读取当前工程中的网络、数据库、信号、系统变量、诊断、测试与 CAPL 能力，避免 AI 凭空假设。

🛡️ 副作用可控

写信号、改网络、运行诊断和测试前生成计划；危险步骤需要明确确认，并支持 dry-run。

📊 结果可审计

返回结构化状态、测试统计、报告路径和执行证据，让智能体能够继续判断，而不是只得到一行日志。

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。

当前稳定版能做什么

能力域	已集成能力	可用入口
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 设备回归，不打包第三方二进制。

AI 执行闭环

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

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

快速开始

1. 准备环境

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

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

2. 用 Python 控制 CANoe

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 先验证

# 查看命令行入口
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：

{
  "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 智能体集成指南。多个 AI 客户端共用同一 CANoe 时，请同时参见多会话租约与并发协调。 ASC 离线回放的调用顺序、真实回归证据和 CANoe 12 Graphics 自动化边界见 MCP 离线源与 Graphics 边界。

REST API

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
`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。令牌绑定运行时会话、动作、参数哈希和有效期，且只能使用一次；详细协议见短时确认令牌。 REST 可启用 API Key 摘要认证和 mTLS，MCP stdio 可指定进程主体与最小角色；完整配置见身份认证、角色权限与 mTLS。 REST 与 MCP 命令行入口默认把审计、计划、幂等结果和检查点保存到本地 SQLite；可选 JSONL 镜像及恢复流程见持久化审计、幂等与恢复。多网络变更应使用预览与提交两阶段接口；完整协议见可验证网络事务。版本识别、兼容状态和分区探针语义见 CANoe 版本兼容与能力探针。自由自然语言的两阶段 Schema、能力指纹和 Provider 接口见 LLM 结构化规划适配器。

项目结构

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。

开发与质量门禁

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；精确清单以自动化工作流和静态检查工作流为准，避免把旧核心已知债务误报成当前发布面已清零。

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

$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 为准。

真实 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 枚举与硬件实验台验证	🧭 规划中

进一步的风险、技术债与能力增强建议见当前开发状态、 v0.2.0 历史工程审计和硬件通道映射独立审计。

文档导航

许可证

Agent2Canoe 采用 MIT License。Vector、CANoe 及相关产品名称归其各自权利人所有；本项目不随包分发 CANoe、Vector SDK 或驱动二进制文件。

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
examples		examples
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
README_EN.md		README_EN.md
SECURITY.md		SECURITY.md
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml

Navigation Menu

Repository files navigation

Agent2Canoe

为什么是 Agent2Canoe

🔎 先发现，再执行

🛡️ 副作用可控

📊 结果可审计

v0.4.0 当前稳定版

当前稳定版能做什么

AI 执行闭环

快速开始

1. 准备环境

2. 用 Python 控制 CANoe

3. 不连接 CANoe 先验证

AI / MCP 接入

MCP 工具一览

REST API

项目结构

开发与质量门禁

版本路线

文档导航

许可证

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Agent2Canoe

为什么是 Agent2Canoe

🔎 先发现，再执行

🛡️ 副作用可控

📊 结果可审计

v0.4.0 当前稳定版

当前稳定版能做什么

AI 执行闭环

快速开始

1. 准备环境

2. 用 Python 控制 CANoe

3. 不连接 CANoe 先验证

AI / MCP 接入

MCP 工具一览

REST API

项目结构

开发与质量门禁

版本路线

文档导航

许可证

About

Topics

Resources

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages