附录 A：模块地图
这张地图按责任而非字母排序。每组先读头文件，再读主实现；平台后端和兼容文件按需进入。
1. 运行时与公共 API
| 模块 | 核心文件 | 责任 | 上游/下游 |
|---|---|---|---|
| 公共 API | transmission.h、api-compat.* | Session/Torrent/Ctor C API，旧协议转换 | 前端 → 内核 |
| Session | session.h/.cc | 全局所有权、设置、监听、定时任务 | 拥有绝大多数子系统 |
| 事件线程 | session-thread.*、timer-ev.* | libevent loop、跨线程队列、timer | UI/worker → 核心序列 |
| Torrent 容器 | torrents.* | 按 id/hash 查询、recently removed | Session → Torrent |
| Torrent | torrent.h/.cc | 生命周期、完成度、目录、统计、信号 | Session/Peer/I/O 汇合点 |
| 构造器 | torrent-ctor.* | 合并添加参数、解析 metainfo | RPC/UI → Torrent |
| 队列 | torrent-queue.* | queue position 与持久化 | Session queue timer |
2. 元数据与动态值
| 模块 | 核心文件 | 责任 |
|---|---|---|
| 动态值树 | variant.* | Null/标量/Vector/Map 共用表示 |
| JSON | variant-json.cc | RapidJSON streaming parse/write |
| Bencode | benc.h、variant-benc.cc | torrent/resume/LTEP 编解码 |
| Key 驻留 | quark.* | 字符串字段名 ↔ TR_KEY_* id |
| 强类型序列化 | serializer.* | Settings/value 与 variant 转换 |
| Torrent metainfo | torrent-metainfo.* | 文件、piece hash、tracker、webseed |
| Magnet metainfo | magnet-metainfo.* | magnet URI parse/build |
| Metadata 下载 | torrent-magnet.* | ut_metadata 分片与 hash 验证 |
| 创建 torrent | makemeta.* | 扫描文件并生成 .torrent |
3. Peer 发现
| 模块 | 核心文件 | 输入 | 输出 |
|---|---|---|---|
| Tracker 调度 | announcer.*、announce-list.* | tracker tiers、torrent event | announce/scrape request |
| HTTP Tracker | announcer-http.cc | HTTP(S) URL | normalized response |
| UDP Tracker | announcer-udp.cc | UDP URL/datagram | transaction response |
| DHT | tr-dht.* | info hash、UDP packet | compact Peer 列表 |
| LPD | tr-lpd.* | LAN multicast | local Peer |
| PEX | peer-msgs.cc | ut_pex | added/dropped Peer |
| Peer 地址 | peer-mgr.* 中 tr_pex | compact v4/v6 | candidate atom |
4. 连接与协议
| 模块 | 核心文件 | 责任 |
|---|---|---|
| 网络值类型 | net.* | address/port/socket address、DNS |
| Peer socket | peer-socket.*、peer-socket-tcp.*、peer-socket-utp.* | TCP/µTP 统一流接口 |
| Peer I/O | peer-io.* | buffer、回调、加密 filter、带宽 |
| MSE | peer-mse.*、tr-arc4.h | DH 与消息流混淆 |
| Handshake | handshake.* | torrent 身份、peer id、扩展位、加密协商 |
| Peer messages | peer-msgs.* | Peer Wire、Fast、LTEP、request pipeline |
| Peer 公共事件 | peer-common.h | 协议层到 Swarm 的事件对象 |
| Peer Manager | peer-mgr.* | swarm、Peer 池、连接、rechoke、调度 |
| Wishlist | peer-mgr-wishlist.* | piece/block 排序与请求分配 |
5. 数据与完整性
| 模块 | 核心文件 | 关键不变量 |
|---|---|---|
| Block 坐标 | block-info.* | byte/piece/block 转换无越界 |
| 文件映射 | file-piece-map.* | file 与 piece 多对多边界 |
| Bitfield | bitfield.* | have/wanted/request 集合 |
| Completion | completion.* | block/piece/wanted 完成度 |
| I/O | inout.* | 一次逻辑操作可跨多个文件 |
| 文件池 | open-files.* | 32 项 LRU、读写模式正确 |
| 文件集合 | torrent-files.* | .part、move/remove/rename |
| Verify | verify.* | 独立 worker，hash 决定真相 |
| Resume | resume.* | 状态快照、字段优先级与 mtime |
| 本地数据 | local-data.* | 本地路径/存在性相关辅助 |
6. 资源与网络服务
| 模块 | 核心文件 | 责任 |
|---|---|---|
| Bandwidth | bandwidth.* | 层级统计、额度分配、clamp |
| Web fetch | web.*、web-utils.* | libcurl multi、HTTP 结果、URL 工具 |
| Webseed | webseed.* | 从 HTTP seed 获取 piece 数据 |
| Blocklist | blocklist.* | 地址范围编译、查询 |
| Port forwarding | port-forwarding* | NAT-PMP/UPnP 状态机 |
| UDP core | tr-udp.*、tr-utp.* | DHT/Tracker/µTP UDP 分发 |
| IP cache | ip-cache.* | 公网地址发现与缓存 |
7. RPC 与产品外壳
| 目录/模块 | 关键文件 | 模式 |
|---|---|---|
| RPC HTTP | rpc-server.* | libevent HTTP + Web assets |
| RPC 方法 | rpcimpl.* | JSON-RPC/legacy dispatch |
| daemon | daemon/daemon.cc | 本地 Session + 远程服务 |
| GTK | gtk/Application.cc、gtk/Session.cc | 直接 C API |
| Qt | qt/Session.cc、qt/RpcClient.cc | local/remote RPC |
| macOS | macosx/Controller.mm、macosx/Torrent.mm | Objective-C++ C API |
| Web | web/src/remote.js、transmission.js | Browser JSON-RPC |
| Remote CLI | utils/remote.cc | libcurl JSON-RPC |
| Utilities | utils/create/edit/show.cc | torrent 文件工具 |
8. 平台适配
| 能力 | 接口 | 实现 |
|---|---|---|
| 文件 | file.h | file-posix.cc / file-win32.cc |
| 子进程 | subprocess.h | subprocess-posix.cc / subprocess-win32.cc |
| Watchdir | watchdir.h | inotify / kqueue / win32 / generic |
| Crypto | crypto-utils.h | ccrypto / openssl / mbedtls / wolfssl / fallback |
| 平台目录 | platform.* | OS 默认 config/download 路径 |
| 字符串桥 | string-utils.* | 通用实现 + macOS .mm |
9. 依赖方向红线
阅读或修改时警惕反向依赖：
- 核心不应依赖 GTK/Qt/Cocoa 类型；
- Peer parser 不应直接调用 UI；
- 平台文件实现不应知道 Torrent queue；
- Web UI 不应猜内部字段，必须以 RPC spec 为准；
- 子系统优先通过 Mediator 获取少量能力，而不是拿整个 Session 任意访问。