内容
# symaira-fritz
[](https://github.com/danieljustus/symaira-fritz/actions/workflows/ci.yml)
[](LICENSE)
[](go.mod)
[](https://github.com/danieljustus/symaira-fritz/releases/latest)
[](https://github.com/danieljustus/symaira-fritz#typical-mac-mini-check)
一款用于**管理和控制 FRITZ!Box**的命令行工具 — Symaira 生态系统的一部分。 二进制名称：`symfritz`.
## 为什么选择 symfritz
- **单个二进制文件，无依赖** — 可在 macOS、Linux 和 Windows 上运行
- **仅使用已文档化的接口** （TR-064，AHA-HTTP）— 无需逆向工程
- **一键式诊断** — `symfritz diagnose <host>` 检查盒子入口、活动、LAN/WLAN、DNS 和 TCP 端口
- **安全的凭证处理** — 从环境变量、symvault 或 macOS Keychain 解析；默认情况下不会存储明文
- **MCP 服务器，用于 AI 代理** — 将所有功能公开为 stdio MCP 服务器
它使用 FRITZ!Box 的已文档化接口，无需逆向工程：
| 接口 | 用途 | 端点 |
|-----------|----------|----------|
| **TR-064** （SOAP） | 管理：状态、WAN/IP、WLAN、主机列表、网状网络、重启 | `:49000` / `:49443` |
| **AHA-HTTP** | DECT 智能家居设备（开关、恒温器） | `/webservices/homeautoswitch.lua` |
| **会话登录** | AHA 和（后来的）网页 UI 爬取的身份验证 | `/login_sid.lua` |
> 灵感来自 [`fritzconnection`](https://github.com/kbr/fritzconnection) （Python，
> 最佳 TR-064 参考）和 [`fritzctl`](https://github.com/bpicode/fritzctl)
> （Go，架构蓝图）。
## 状态
当前功能：
- **会话身份验证** — 现代 PBKDF2 （FRITZ!OS 7.24+）*和* 旧 MD5 挑战响应，具有自动重新登录功能。
- **TR-064** — 具有 HTTP 摘要身份验证的通用操作调用，以及 `tr64desc.xml` 服务发现（`symfritz services`）。
- **主机** — 一流主机表：`list`、`active`、`get` 按名称/MAC/IP。
- **检测** — 当 `fritz.box` 解析为公网 IP 时，在本地网络中找到 FRITZ!Box。
- **诊断** — 主机可达性端到端检查（盒子入口 → 活动 → LAN/WLAN → DNS → TCP 端口）。
- **网状网络** — 节点、重复器和链接的拓扑结构。
- **WLAN** — 无线电、关联客户端、访客网络状态/切换。
- **Wake-on-LAN** — 按主机名/IP 或显式 MAC。
- **AHA-HTTP** — DECT 设备列表和开关开启/关闭（`symfritz home`）。
- **凭证** — `auth login/test/store`，从环境变量 → symvault → macOS Keychain → 配置文件中解析。
- **流量** — 实时 WAN 流量监控（按类别划分的下行/上行）。
- **DSL** — 线路统计：噪声裕度、衰减、最大比特率。
- **电话** — 通话列表，类型筛选，拨号，挂断。
- **日志** — 系统事件日志，类别筛选（系统/网络/电话/WLAN/USB）。
- **`status`**、 **`reboot`** 和 **MCP 服务器** （stdio），公开上述功能，配置 + 环境变量加载。
- 查询/诊断命令的 `--json` 用于脚本编写。
仍在计划中：恒温器（HKR）控制、每无线电频段标签和网页 UI `data.lua` 抓取层，用于统计数据 TR-064 未公开的内容（固件脆弱，
将标记为尽力而为）。
## 安装
```bash
make build # → ./symfritz
# 或
go install github.com/danieljustus/symaira-fritz/cmd/symfritz@latest
```
## 配置
```bash
symfritz config init # 写入 ~/.config/symfritz/config.toml
# 编辑文件中的主机/用户，然后安全存储密码：
symfritz auth login # 提示，验证盒子，存储
symfritz auth test # 确认它解析并工作
```
### 密码来源
symfritz 在运行时解析密码，顺序如下（第一个命中获胜）：
1. **`SYMFRITZ_PASSWORD`** 环境变量 — 临时 / CI。
2. **symvault** — 在配置文件中设置 `password_ref = "fritz.password"`；symfritz 调用 `symvault get`，因此磁盘上不存储任何内容。
3. **macOS Keychain** — 设置 `keychain = true`；服务 `symfritz`，账户 = 主机。
4. **配置文件中的 `password`** 明文 — 最不安全，仅用于方便。
`auth login` 捕获密码一次，验证它，并将其存储在 Keychain（macOS 上默认）或 symvault（ `--symvault fritz.password`）中。symvault 和 Keychain 通过它们的 CLI 访问，因此 symfritz **没有构建依赖** 于它们，当它们不存在时也能正常工作。
```bash
symfritz auth login --symvault fritz.password # 存储在 symvault 而不是 Keychain
symfritz auth store --keychain # 存储而不验证（读取 SYMFRITZ_PASSWORD 或提示）
symfritz auth test # 显示源 + 验证网页登录和 TR-064 访问
```
> **提示：** 使用具有您需要的权限的专用 FRITZ!Box 用户，而不是管理员帐户。 TR-064 必须在盒子上启用（家庭网络 → 网络 → 网络设置 → “允许应用程序访问”）。
## 用法
```bash
symfritz status # 型号，固件，连接，外部 IP
symfritz detect # 在本地网络中找到 FRITZ!Box
symfritz detect --json # 机器可读输出
# 主机
symfritz hosts list # 所有已知设备
symfritz hosts active # 仅当前活动设备
symfritz hosts get macmini # 按名称…
symfritz hosts get --mac f0:18:98:f3:64:b5 # …或 MAC…
symfritz hosts get --ip 192.168.188.65 # …或 IP
# 端到端诊断（主要用例）
symfritz diagnose macmini # 盒子入口 → 活动 → LAN/WLAN → DNS → 端口
symfritz diagnose macmini --port 22 --port 5900 --port 8001
symfritz doctor macmini --json # 别名，机器可读
# 网络形状
symfritz mesh # 网状节点 + 链接
symfritz wlan radios # SSID / 频段 / 通道 / 状态
symfritz wlan clients # 关联设备 + 信号/速度
symfritz wlan guest status|on|off
symfritz traffic # 实时 WAN 流量监控
symfritz dsl # DSL 线路统计（噪声，衰减，速率）
# 唤醒 Mac Mini
symfritz wol macmini # 通过主机表解析 MAC
symfritz wol --mac f0:18:98:f3:64:b5
# DECT 智能家居
symfritz home list
symfritz home switch <AIN> on
# 电话（如果 FRITZ!Box 有电话功能）
symfritz calls # 通话列表（--type missed/incoming/outgoing/rejected/all）
symfritz dial <number> # 通过 FRITZ!Box 拨号
symfritz hangup # 挂断活动通话
# 高级用户 / 内省
symfritz services # 发现所有 TR-064 服务（tr64desc.xml）
symfritz call deviceinfo GetInfo # 原始 TR-064 操作
symfritz call WLANConfiguration:2 GetInfo # 任何发现的服务按名称
symfritz log # 系统事件日志（--filter sys/net/fon/wlan/usb）
symfritz reboot --yes
symfritz mcp # 用于 AI 代理的 MCP stdio 服务器
```
### 典型的 Mac Mini 检查
```bash
symfritz diagnose macmini
# 诊断 macmini → 192.168.188.65
# ✓ FRITZ!Box 知道主机 macmini
# ✓ 主机活动
# ✓ IP 地址 192.168.188.65
# ✓ 链路介质 LAN
# ✓ DNS 解析 192.168.188.65
# ✓ TCP 22 （SSH） 开放
# ✗ TCP 5900 （VNC/屏幕共享） 关闭或过滤
# ✓ TCP 8001 （Paperless） 开放
```
### 原始 TR-064 服务名称
快捷方式：`deviceinfo`、`wanip`、`wanppp`、`wancommon`、`hosts`、`wlan1`。其他名称通过 `tr64desc.xml` 发现，因此 `call` 可以访问盒子广告的每个操作。
## MCP 服务器
`symfritz mcp` 启动一个 stdio MCP 服务器，向 AI 代理（如 Hermes）公开 FRITZ!Box 功能。
### 在 Hermes 中注册
在您的 Hermes 配置文件中添加一个服务器块。以下示例假设 Homebrew 安装的二进制文件位于 `/opt/homebrew/bin/symfritz`；请调整路径到您的安装位置：
```yaml
mcp_servers:
symfritz:
command: /opt/homebrew/bin/symfritz
args:
- mcp
env:
SYMFRITZ_HOST: "192.168.188.1"
enabled: true
```
> **注意：** `fritz.box` 可以在某些网络上解析为公网 IP 地址，这会导致 MCP 服务器无法访问盒子。请使用显式本地 IP 或您控制的 DNS 名称，并通过 `SYMFRITZ_HOST` 或配置文件中的 `host` 设置。
### 烟雾测试
注册后，请验证服务器启动并公开预期的工具：
```bash
$ SYMFRITZ_HOST=192.168.188.1 symfritz mcp
initialize: OK
serverInfo.name: symfritz
serverInfo.version: <version>
tools/list: 9 tools
```
预期工具为 `status`、`host_list`、`host_get`、`diagnose`、`mesh`、`wlan_clients`、`wake_on_lan`、`home_list` 和 `home_switch`.
## 架构
```
cmd/symfritz/ Cobra CLI
detect.go FRITZ!Box 网络发现
internal/config/ TOML + 环境变量配置（corekit configkit）
internal/fritz/ 核心库：
client.go 客户端，选项，端点
session.go 登录_sid.lua 身份验证（PBKDF2 + MD5，自动重新登录）
tr064.go SOAP 操作调用
digest.go HTTP 摘要身份验证
discover.go tr64desc.xml 服务发现
hosts.go 主机表，查找，Wake-on-LAN
diagnose.go 端到端可达性检查
errors.go 错误分类和可行的消息
router.go 路由器实用程序
router_gateway.go 网关检测
wlan.go 无线电，客户端，访客网络
mesh.go 网状拓扑
aha.go AHA-HTTP 智能家居
status.go 高级概述
internal/secret/ 凭证解析（环境变量 → symvault → keychain → 配置），
symvault 和 macOS Keychain 通过它们的 CLI（无构建耦合）
internal/mcp/ MCP stdio 服务器：状态，主机列表，主机获取，诊断，
网状网络，wlan_clients，wake_on_lan，home_list，home_switch
```
`internal/fritz` 包是自成体系的，因此其他 Symaira 工具可以稍后嵌入它。
## 注意事项
- TR-064 + AHA 涵盖了大约 80% 的稳定功能。剩余的部分（一些统计数据，某些日志，访客 WLAN 详细信息）仅通过 **网页 UI `data.lua` 爬取** 提供，这取决于 FRITZ!OS 版本，并可能在固件更新时中断。这一层暂时未构建，将明确标记为“尽力而为”。
## 开发
构建：
```bash
make build # → ./symfritz
go install github.com/danieljustus/symaira-fritz/cmd/symfritz@latest
```
测试：
```bash
make test
go test ./... # CGO_ENABLED=0
```
检查：
```bash
make lint # go fmt + go vet
go vet ./...
```
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取完整的贡献指南。
## 许可证
Apache-2.0。参见 [LICENSE](LICENSE)。
