traffic-analysis-plugin

帮助大模型（DSH / zcode 等 harness 中的 agent）理解 pcap/pcapng 网络抓包文件的插件。

核心边界：

Plugin 负责「看见什么、怎么查、证据从哪里来」；LLM 负责「这些观测意味着什么」。 工具只输出 observation（可下钻到 frame），不输出「拥塞/攻击/网站慢」类结论。

PCAP ──确定性索引/抽取──▶ Traffic Observation IR ──受约束 Query──▶ 有界 Observation ──▶ LLM 下钻推理 ──▶ Packet-level Evidence

v0.2 能力（围绕三大目的）

目的	机制
省上下文	紧凑默认投影、12k 渲染预算（砍行不砍列）、traffic_timeseries 服务端分箱聚合替代全量帧转储；实测同等分析深度比 v0.1 的 bash 路径省 ~23x（scripts/context-report.mjs）
结构化输入	5 族 11 种事件（tcp.analysis 家族 + HTTP 事务）、metrics v2（rtt/吞吐/缺失段）、attr.* 按类型校验的查询白名单
可检验证据	traffic_evidence 返回固定字段集的帧级原始记录（≤200 帧/次）供模型复核 claim；全部观测携带 frame 级 evidence + audit（backend 版本、query_hash、render_chars）

仓库结构

packages/
├── traffic-core/     # 纯 TS 库：指纹/轻索引/IR/事件抽取/Query/Backend（不依赖 harness）
└── dsh-plugin/       # DeepSeek Harness 插件：6 个 defineTool 的薄胶水
fixtures/             # 确定性测试 pcap（web-session / mid-capture / edge-cases）
docs/                 # 设计文档（见下）与样例规范
scripts/              # generate-samples / verify-pinned-download / dsh-runtime-smoke / context-report

工具面（DSH）

工具	语义
traffic_open(path)	Capture Identity：指纹、格式、包数、时长。不解析包
traffic_overview(capture_id)	轻索引概览：协议分布、会话计数、top 会话
traffic_query(capture_id, query)	通用 AST 查询：scope∈{conversation,event}，AND-only，字段白名单 + attr.*
traffic_inspect(capture_id, conversation_id)	单会话下钻：metrics + 事件时间线 + frame 证据
traffic_evidence(capture_id, frames|event_ids)	帧级原始记录（固定字段集）复核，≤200 帧/次
traffic_timeseries(capture_id, conv, metric, bin_ms)	bytes/packets/window/rtt 双向分箱，bin∈[10,5000]ms，>500 箱自动加宽