从 SIP 查询
到通话排障

python3 homerctl.py --version
python3 homerctl.py init --url https://homer.example.net --username operator
python3 homerctl.py login
python3 homerctl.py doctor
python3 homerctl.py fields --profile 1_call

login 交互输入密码。doctor 仅验证 API、认证和映射结构；还要用一通在 HOMER 页面可见的已知电话比对 search、trace、message。

python3 homerctl.py search --since 30m \
  --caller 1001 --callee 1002 --transport udp --all

caller / callee 是 SIP From / To 的用户部分；Request-URI 用户用 --ruri-user。CLI 的 count 是消息条数，不是通话数。业务号码可能经过改写，先核对实际字段。

python3 homerctl.py search --since 15m \
  --capture-id 101 --node db-a --status '408;503' --all

capture-id 是 HEP 上报的采集编号，node 是 HOMER 数据库节点。SIP 报文 src-ip / dst-ip 也是另一层概念；三者不能互相替代。

python3 homerctl.py search \
  --from '2026-09-15T16:00:00+08:00' \
  --to '2026-09-15T16:05:00+08:00' \
  --caller 1001 --limit 500 --all --max-requests 64

search 使用 [from,to)；后端按整秒查询，CLI 向外取整后再按返回时间过滤。绝对时间必须带时区，起止同时提供；不要与 --since 混用。日期为教学示例。

python3 homerctl.py search --since 15m --caller 1001 --src-port 5060 --all
python3 homerctl.py search --since 15m --caller 1001 --src-port 5080 --all

当前 CLI 不支持嵌套条件。两次查询分别保留 caller 限制，再在应用层取并集；固定绝对时间能让窗口严格一致。去重用 dbnode、profile、id、timestamp_us，不只用 id。直接加 --logic or 会把 caller 也变成可选条件。

python3 homerctl.py trace --since 1h --call-id 'abc@example.net'
python3 homerctl.py trace --since 1h --call-id 'abc@example.net' --include-raw
python3 homerctl.py message --since 1h \
  --id 123 --node db-a --profile 1_call

123、db-a 及 profile 应替换为 search 返回的 _ref；message 只接受一个节点。trace 默认移除 raw，关联消息可能超出原查询时间窗，并受服务端关联和去重规则影响。

python3 homerctl.py export --since 1h --call-id 'abc@example.net' \
  --format json --output call.json
python3 homerctl.py export --since 1h --call-id 'abc@example.net' \
  --format pcap --output call.pcap
python3 homerctl.py analyze --input call.json --mtu 1500

导出以 Call-ID 的 transaction 为单位，不会复刻 search 的所有筛选条件。JSON 包含 raw；默认不覆盖已有文件。PCAP 来自数据库重建，应按“信令内容导出”理解。[S4]

python3 homerctl.py analyze --input examples/sample-trace.json --mtu 1500
python3 -m unittest discover -s tests -v

本次复测：3 条 raw 记录；3 个 udp_size_risk；1 组 repeated_udp_payload 包含 2 次观察；fragmentation.verdict 仍为 unknown。第三条来自不同采集 ID，未合并进同点重复组。样本为合成数据，不是现网事故。

python3 homerctl.py schema
python3 examples/ai_runner.py search --since 15m --caller 1001 --all

schema 无须连接服务。AI runner 返回 exit_code 和 result，6 仍有结果；它不开放 export 或任意本地输入路径。工程接入时再限制每个任务的总查询次数与日期范围，避免反复补查。

{
  "observation": "同一报告采集点观察到两条相同 UDP 载荷",
  "evidence_refs": [
    {"id": 1, "dbnode": "db-a", "profile": "1_call",
     "timestamp_us": 1789459200100000, "call_id": "call-a@example.net"},
    {"id": 2, "dbnode": "db-a", "profile": "1_call",
     "timestamp_us": 1789459200600000, "call_id": "call-a@example.net"}
  ],
  "coverage": "合成 trace 样本；采集完整性 unknown",
  "hypothesis": "可能是重传，也可能是重复采集",
  "unknown": "是否存在原始 IP 分片和线上丢包",
  "next_check": "检查原始抓包、采集配置与 SIP 事务"
}

这是建议给上层应用使用的报告结构，不是 CLI 新增字段，也不是原生 analyze 输出格式。引用来自包内合成样本。