内容
1 align="center">CANarchy</h1>
<p align="center">
<strong>面向分析师、安全研究人员和人工智能代理的、以流为优先的CAN总线工具包。</strong><br>
每个命令都会发出类型化的、机器可读的事件，您可以将其管道化、脚本化或交给代理 — 具有J1939重型车辆支持作为一等公民。
</p>
<p align="center">
<a href="https://pypi.org/project/canarchy/"><img alt="PyPI" src="https://img.shields.io/pypi/v/canarchy"></a>
<a href="https://pypi.org/project/canarchy/"><img alt="Python versions" src="https://img.shields.io/pversions/canarchy"></a>
<a href="https://github.com/hexsecs/canarchy/actions/workflows/test.yml"><img alt="Tests" src="https://github.com/hexsecs/canarchy/actions/workflows/test.yml/badge.svg"></a>
<a href="https://github.com/hexsecs/canarchy/actions/workflows/lint.yml"><img alt="Lint" src="https://github.com/hexsecs/canarchy/actions/workflows/lint.yml/badge.svg"></a>
<a href="LICENSE"><img alt="License" src="https://img.shields.io/pypi/l/canarchy"></a>
<a href="https://hexsecs.github.io/canarchy/"><img alt="Docs" src="https://img.shields.io/badge/docs-hexsecs.github.io-blue"></a>
</p>
<p align="center">
<img src="docs/assets/tui.svg" alt="CANarchy 的全屏 TUI 流式传输实时 CAN 流量、J1939和 DM1 故障" width="920">
</p>
什么是 CANarchy？
CANarchy 是一个以 CLI 为优先的运行时，用于捕获、解码和操作 CAN 和 CAN-FD 流量。 大多数 CAN 工具都强制进行权衡：交互式但难以自动化，可脚本化但过于原始，或协议感知但在接口之间不一致。 CANarchy 围绕着约束构建 - **每个输出都是您 can 解析、管道或转发给 LLM 代理的类型的事件流** (`--json`, `--jsonl`, `--text`)。
您是：
安全研究人员**，逆向未知总线，模糊 ECU，或 diff 捕获异常。
- **重型车辆 / J1939 工程师**，需要 PGN/SPN 解码，TP 重组和 DM1 故障解析，而无需降原始 ID。
- **构建自动化或 AI 代理**，稳定、可机器读取的 CAN 接口，而不是刮取的文本。
## 安装
```bash
pipx install canarchy # 隔离，在 PATH 上 everywhere
# 或：pip install --user canarchy
```
需要 Python 3.12+。实时传输使用 [`python-can`](https://python-can.readthedocs.io/) （socketcan，虚拟总线，UDP 多播等）。
## 在 60 秒内试用 - 无需硬件
```bash
canarchy --version
canarchy doctor --text # 8 个离线健康检查；全绿 = 安装良好
# 从确定性脚手架后端流式传输类型化事件 —
#，无装置，无网络。这是 JSONL 合同：
CANARCHY_TRANSPORT_BACKEND canarchy capture can0 --jsonl
```
指向接口：
```basharchy capture can0 --candump # 人类友好的实时视图
canarchy capture can0 --jsonl . # 类型化行一个
```
更喜欢探索？启动 **全UI** （上并实时查看总线```bash
canarchy tui # /capture <iface式传输；/filter，/sort，
```
## 为什么选择 CANarchy？
[事件模式](docs/event-schema.md)契约；CLI 包装它。 这个设计选择使 CANarchy 与大多数开源 CAN ：
- **输出是契约，而不是事后想法。** 每个命令 — 捕获、解码、逆向工程 — 都发出相同的规范 JSON 信封。 解析一次，在任何地方重用。
- **管道优先。** `--jsonl` 流式传输一个类型化的事件每行，因此 `| jq` 、 `| grep` 或下游脚本直接有效。
- **J1939 是首要的。** PGN 解码、SPN 提取、TP 会话重组和 故障解析从 SAE 目录中 — 而不是原始仲裁- **代理就** 内置的 [](https://modelcontextprotocol.io通过 CLI 使用结构化契约包暴露给 Claude 和 客户端，因此代理 CAN 分析。
| | CANarchy | 典型的 CAN CLI 工具 |
|---|:---:|:---:|
| 结构化输出作为核心 | ✅ | ✗ |
| 管道事件流 | ✅ | 部分 |
| 提供者支持的 DBC 发现和缓存 | ✅ | ✗ |
1939 首要操作工作流 | ✅ | 部分 MCP / 代理集成 | ✅ | ✗ |
参见完整的 [CAN 工具功能矩阵-matrix.md便与 can-utils、CAN、Caring Caribou、TruckDevil 等其他工具进行诚实、并排的比较。
## 您做什么？
```bash
# 使用 DBC 解码捕获
canarchy decode --file trace.candump --dbc vehicle.dbc --jsonl
# J1939 重型车辆分析
canarchy j1939 decode --file trace.candump --text
canarchy j1939 spn 110 --file trace.candump --text # 引擎冷却液温度
canarchy j1939 dm1 --file trace.candump --text # 活动故障代码
逆向工程未知总线：排名可能的信号、计数器、异常
re signals --file trace.candump --jsonlarchy re anomalies --file trace.candump --baseline known_good.candump --jsonl
# 两个捕获的仲裁 ID（速率/时间/熵增量）
canarchy compare before.candump after.candump --json
# 活动工作流（由主动传输安全模型控制；--dry-run 计划安全）
canarchy generate --count 10 --gap 50 --id 7DF --jsonl
canarchy replay --file trace.candump --rate 2 --json
# 将事件直接输送到下游工具
canarchy j1939 110 --file traceump --jsonl \
| jq '[., .payload.units, .payload.timestamp]'
```
## 代理（MCP）驱动它
CANarchy [Model Context Protocol://modelcontextprotocol 服务器，因此 LLM 代理可以通过 CLI 使用的相同结构化契约捕获、解码和分析 CAN 流量。
```bash
canarchy mcp install --client claude-desktop # 或：--client claude-code
canarchy mcp serve # 或直接运行_stdio服务器
```
主动传输工具需要明确的确认，因此代理不能意外地将帧放到实时总线上。参见 [主动传输安全设计](docs/design/active-transmit-safety.md)。
## 全屏 TUI
`canarchy tui` 打开一个交互式、全屏仪表盘，实时流式传输总线：
- **实时窗格：** 实时流量、解码信号、J1939（汇总功能区 + 最新表格）、UDS 事务和追加日志。
- **后台捕获：** `/capture <iface>` 开始流式传输；`/stop` （或 `x`）结束它。
- **交互式：** `/filter <pane> <text>`、`/sort <pane> <column>`、箭头键行导航、`space` 暂停馈送、`[`/`]` 调整后备大小、`ctrl+f` 最大化窗格。
- 在提示符下键入任何实际的 CANarchy 命令 — 它通过共享解析器运行并折叠到窗格中。
<details>
<summary><strong>完整命令目录</strong>（点击展开）</summary>
...
## 结构化契约
每个成功的命令都返回一个稳定的信封：
```json
{ "ok": true, "command": "capture", "data": {}, "warnings": [], "errors": [] }
```
失败时返回带有可操作提示的结构化错误（和记录的 [错误代码目录](docs/troubleshooting.md)）：
```json
{
"ok": false,
"command": "decode",
"data": {},
"warnings": [],
": [
{ "code": "DBC_LOAD_FAILED", "message": "Failed to parse DBC file.", "hint": "Validate the DBC syntax and line endings." }
]
}
```
使用 `--candump` 获取面向人类的实时视图；使用 `--jsonl` 馈送脚本或代理 - 每行都是来自 [规范模式](docs/event-schema.md) 的类型化事件。设置 `CANARCHY_PYTHON_CAN_INTERFACE` 以选择接口类型，或设置 `CANARCHY_TRANSPORT_BACKEND=scaffold` 以获取确定性的离线行为。
## 文档
- [快速入门](docs/getting_started.md) · [烹饪书](docs/cookbook/index.md) - 任务导向的配方
- [事件模式](docs/event-schema.md) - 所有结构化输出的规范信封
- [命令规范](docs/command_spec.md) · [架构](docs/architecture.md)
- [CAN 工具功能矩阵](docs/feature-matrix.md) - 与其他 OSS CAN 工具的比较
- [J1939 重型车辆演示](docs/tutorials/j1939_heavy_vehicle.md) · [故障排除](docs/troubleshooting.md)
- 完整文档站点：secs.github.io/canarchy](https://hexsecs.github.io/canarchy/)**
## 从源代码安装（开发）
CANarchy 使用 [`uv`](https://docs.astral.sh/uv/) 进行环境、依赖和打包工作流。
```bash
git clone https://github.com/hexsecs/canarchy && cd canarchy
uv sync # 创建 venv 并从 checkout 安装
uv run canarchy
uv tool install --editable . # 可选： 将 `canarchy` 放在您的 PATH 上；编辑立即生效
```
运行测试套件端到端：
```bash
uv run python -m unittest discover -s tests -v
```
bash、zsh 和 shell 补全来自 `canarchy completion <shell>` - 参见 [快速入门](docs/getting_started.md-shell-completion)。
## 社区和贡献
CANarchy 采用 GPL-3.0 许可，并欢迎贡献。
- ⭐ **如果它对您有帮助，请给仓库加星** - 它确实有助于其他人找到它。
- [贡献指南](CONTRIBUTING.md) - 本地开发、分支流程和 PR 门控
- [行为准则](CODE_OF_CONDUCT.md)
- [安全政策](SECURITY.md) - 报告问题和安全的活动总线操作
> ⚠️ CANarchy 可以在实时总线上传输。仅在您拥有或被明确授权测试的车辆、ECU 和网络上操作。主动传输命令通过设计需要明确的确认。
## 哲学
- CLI 是契约。
- 协议语义优于原始帧。
- 结构化输出优于格式化文本。
- 可重复的工作流优于临时交互。
