DBC CRUD Agent Skill

本项目提供结构化命令行 Skill，用于创建、查看、更新、删除、验证和比较 CAN DBC 数据库，以及在 DBC 与 Excel 工作簿之间转换。支持节点、报文、信号、Classic CAN 与 CAN FD 帧元数据、标准及扩展多路复用、JSON 输出，以及确定性的节点/报文/信号比较。

环境要求与安装

Python 3.9+
requirements.txt 中固定的依赖（cantools==40.7.1、openpyxl==3.1.5）

在仓库根目录执行：

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
source .venv/bin/activate

安装 Skill 时请保留仓库目录结构：SKILL.md、references/、examples/ 和 scripts/ 之间使用相对路径。所有命令均从仓库根目录执行。

npm 命令与 DeepSeek Harness 插件

最低 Python 3.9 来自固定依赖 cantools==40.7.1 的要求；openpyxl==3.1.5 最低要求 Python 3.8。降低版本需要更换并重新验证 DBC 引擎，因此保留 Python 3.9+。npm 包装器要求 Node.js 22+。

包发布到 npm 后可执行：

# 首次使用：创建隔离的 Python 环境并安装依赖。
npx --yes dsh-plugin-dbc setup
# 在任意目录运行，相对文件路径以当前工作目录为准。
npx --yes dsh-plugin-dbc --json summary ./example.dbc
npx --yes dsh-plugin-dbc --json excel export ./example.dbc ./example.xlsx
npx --yes dsh-plugin-dbc --json excel import ./example.xlsx ./roundtrip.dbc
npx --yes dsh-plugin-dbc --json compare ./example.dbc ./roundtrip.dbc

# 安装原生 Harness 插件（验证 CLI 版本：0.2.1-rc.2）。
npx --yes @deepseek-ai/dsh web --help
npx --yes @deepseek-ai/dsh plugin --profile web add dsh-plugin-dbc
npx --yes @deepseek-ai/dsh web

插件注册 dbc 工具，接收独立参数数组，返回 JSON 结果。Python 在宿主机运行，每次调用需要通过 Harness 的用户审批；没有审批支持的界面会拒绝调用。Agent 工具调用应使用绝对路径。包不包含模型或 API Key，也不把 DBC 上传到外部转换服务；Agent 配置的模型仍会收到工具参数与结果。

setup 默认使用 ~/.dbc-skill/venv-v1，可通过 DBC_SKILL_VENV 指定环境目录。安装 npm 包不会自动安装 Python 依赖，只有主动运行 setup 才会安装。已有环境可通过 DBC_SKILL_PYTHON 指定 Python 可执行文件，并安装两项固定版本依赖。系统需预装 Python，npx 不会安装 Python 本身。

发布前本地验证：

npm ci
node bin/dbc-skill.js setup
npm test
npm pack
npx --yes @deepseek-ai/dsh plugin --profile web add ./dsh-plugin-dbc-0.1.0.tgz

快速开始

# 创建并验证空数据库。
python3 scripts/dbc_crud.py --json init demo.dbc
python3 scripts/dbc_crud.py --json validate demo.dbc

# 添加节点、报文和信号。
python3 scripts/dbc_crud.py --json node add demo.dbc ECU_A --comment "车身控制器"
python3 scripts/dbc_crud.py --json message add demo.dbc 0x123 Status --length 8 --sender ECU_A
python3 scripts/dbc_crud.py --json signal add demo.dbc Status State --start 0 --length 8

# 检查结果并再次验证。
python3 scripts/dbc_crud.py --json signal show demo.dbc Status State
python3 scripts/dbc_crud.py --json summary demo.dbc
python3 scripts/dbc_crud.py --json validate demo.dbc

报文引用可以使用名称、十进制帧 ID 或 0x 十六进制帧 ID。全局选项必须放在命令之前，例如 python3 scripts/dbc_crud.py --json --encoding utf-8 summary demo.dbc。

安全修改与规范化

node、message 和 signal 的新增、更新、删除操作都通过 cantools 保存。默认原地保存会创建包含原始字节的 PATH.bak；检查结果期间请保留该备份。
--output OTHER.dbc 写入独立文件并保持输入不变，是删除或实验性修改的优先选择。
--no-backup 会在原地保存时禁用 .bak。仅对临时文件或已有其他备份的文件使用。
保存会规范化 DBC 文本，并不保证逐字节无损保留注释、格式或 cantools 未建模的构造。CLI 会先写临时文件、严格重新加载并检查所有受支持实体的元数据，然后替换目标文件。
默认编码为 UTF-8。可用全局 --encoding 指定源文件和目标文件编码，例如兼容旧文件时使用 cp936。

CAN 与 DBC 能力

标准帧 ID 范围为 0 至 0x7FF；使用 --extended 的扩展帧 ID 范围为 0 至 0x1FFFFFFF。
Classic CAN 报文长度为 1–8 字节；使用 --fd 的 CAN FD 报文长度为 1–64 字节。
标准多路复用使用根选择器和分支值。扩展多路复用支持嵌套选择器以及多个值/范围，并按需使用 DBC SG_MUL_VAL_ 元数据。
信号最小值和最大值必须同时存在或同时缺省。整数 0|0 被保留为“无边界”；浮点零可以表示。清除或设置边界前请阅读字段参考。
比较时，节点按名称识别，报文按帧 ID 加帧类型识别，信号按父报文身份加信号名识别。有效输入无论相等或不同都返回退出码 0。

Excel 转换

python3 scripts/dbc_crud.py --json excel export INPUT.dbc OUTPUT.xlsx
python3 scripts/dbc_crud.py --json excel import INPUT.xlsx OUTPUT.dbc

导出会生成五个工作表（Metadata、Nodes、Messages、Signals、Choices），布尔列和字节序列列带下拉校验；已有目标文件会被原子替换，不创建备份。
导入只接受 .xlsx 文件，并拒绝包含公式的单元格——导入前请先把计算结果粘贴为数值。整个工作簿先完成校验才会写入，导入失败不会改动 OUTPUT.dbc；成功导入会原子替换目标文件，且 backup 始终为 null。
五个文档化工作表以外的额外工作表会被忽略，并列在 result.warnings 中。
用语义方式验证往返：导出、导入到新 DBC，然后 compare 两个文件并检查 result.equal。

完整的工作簿结构、列清单和单元格语法见 CLI 参考；结果字段见字段参考。

文档

两个工作流都使用临时副本，并通过 --output 将每次修改写入新文件，覆盖 CRUD、比例修改、标准和扩展多路复用、安全删除、比较、Excel 语义往返、最终检查与验证。

测试

.venv/bin/python -m unittest tests.test_docs -v
.venv/bin/python -m unittest discover -s tests -v
git diff --check

许可证

基于 MIT License 发布。

dsh-plugin-dbc

Install

Source

Tags

Readme