NETWORK-CAPTURE.md 11 KB

通过网页抓包使用 API

本模式由本地 Node 进程直接请求已确认的消息、日历接口。运行时不依赖 Teams 网页或扩展,也不需要注册自有 Entra 应用。登录可从本地工具发起,原有 HAR 导入继续支持。

后台采集与工具登录

启动 npm start,打开本地控制台的「后台 API 采集」:

  1. 点击「从工具登录」。工具临时打开独立的 Edge 窗口,由微软页面处理公司 SSO、密码和 MFA;无需扩展,不接管日常浏览器的配置目录。
  2. 等待页面加载;已捕获消息接口即可完成,不必逐个进入聊天。仅消息数为 0 时打开任意聊天;需要日历且尚未捕获时,再打开日历。
  3. 返回本地控制台,点击「完成登录」。工具验证本地 API 请求,将必要的业务请求保存为 data/network-session.har,关闭登录窗口并开始后台采集。
  4. 可以关闭 Teams 窗口和本地控制台标签页;保持本地 Node 服务运行即可。控制台的「停止后台采集」暂停采集,数据与历史进度保留。

0.6.0 起,本地服务按实例自动续期:优先直接刷新访问凭证,必要时短时使用该实例保留的浏览器会话恢复,随后关闭。旧版 HAR 缺少续期材料,需要分别完成一次工具登录。控制台与 MCP 可查看续期状态;详见自动续期说明。

工具默认使用已安装的 Microsoft Edge。命令行入口也支持 Chrome:

npm run capture:login
npm run capture:login -- --browser=chrome

命令行按提示完成微软登录后,按 Enter 验证和保存。该命令只负责登录;使用控制台启动采集,或运行下面的 capture:sync 命令。独立登录配置保存在 data/network-profile/,包含微软会话,供下次短暂登录尝试 SSO;工具不会保存密码输入或导出 OAuth 表单。

采集为每轮结束后等待 30 秒的轮询,实际延迟还包含请求耗时;不是服务器推送。服务每轮优先同步最新消息、日历,再用最多 5 个请求补历史。服务启动后会恢复上次启用的采集;这不等于已安装 Windows 开机启动服务。

首次已有 HAR 可在 .env 配置 NETWORK_HAR_PATH=./data/captures/teams.har;可选 NETWORK_AUTO_START=true。成功完成工具登录后,data/network-session.har 优先。不要同时启动多个采集进程读取同一数据库。

历史聊天

已实测同一消息接口以 startTime=0 开始读取,通过服务器返回的 _metadata.backwardLink 向更早的消息分页。不会把实时同步的 syncState 当作历史分页,也不会用猜测的 endTime 参数。

历史消息与独立历史断点在同一 SQLite 事务保存。达到每轮请求预算后保留下一页,重启可续传;后台新发现的会话也会加入历史计划。较旧消息版本不会覆盖实时采集已保存的较新正文。

0.4.1 的表情适配会使旧版历史断点从起点重扫一次,补回此前跳过的纯表情/图片消息,并更新正文中的表情;已有记录保持同一身份,历史补录不会触发新消息提醒。进度计数表示当前适配版本的扫描范围。

每个历史请求前默认随机等待 2–5 秒,避免连续突发读取。停止操作会立即取消等待;没有待补历史时不等待。可在 .env 设置 HISTORY_REQUEST_MIN_DELAY_MS=2000 和 HISTORY_REQUEST_MAX_DELAY_MS=5000,允许范围为 0–300000 毫秒且最小值不大于最大值,重启后生效。随机间隔用于平滑请求节奏,不保证不被服务端识别。

历史请求遇到 429/503 时结束本轮,按 Retry-After 或退避保存该来源的冷却时间;跨轮和重启继续遵守。较长冷却不会占住实时采集流程,未到期的历史任务延后;控制台与 MCP 采集状态显示等待/冷却。补历史期间每轮最多 5 次短等待会增加轮次耗时。

只有从零开始的有效分页链到达 lastCompleteSegmentStartTime=0 且没有 backwardLink,才标记该会话的接口可见历史完成。无起点证据、循环游标或页数上限均明确报告截断,不冒充完成。

# 单独补采一批,再次运行续传;勿与同一库的后台采集并行
npm run capture:history -- data/captures/teams.har --max-requests=100
# 命令行单次覆盖随机范围;仍需遵守服务端退避
npm run capture:history -- data/network-session.har --max-requests=20 --min-delay-ms=3000 --max-delay-ms=8000

范围是抓包、工具登录及聊天列表接口已发现的会话;当前捕获的列表是增量接口,未证明覆盖账号全部会话。组织已删除、过期或无权限的历史无法恢复,未支持的控制消息、附件本体等仍跳过。面板分别显示已发现会话数、完成数、截断数和累计页数。

验证方法

在自己的账号完成登录后,检查消息、聊天增量列表及所需日历接口的返回状态,并确认记录已经写入本地 SQLite。重复采集未变化的内容不应产生新版本。

验证范围取决于当前账号权限、已发现会话和日历窗口,不代表全部历史或所有会话。真实 HAR、账号诊断与运行记录仅保存在本地,不随仓库发布。

使用

在项目目录执行:

# 分析:只读取 HAR,输出脱敏接口报告
npm run capture:analyze -- data/captures/teams.har

# 单个接口验证:编号来自分析报告,0 为第一条请求
npm run capture:probe -- data/captures/teams.har 0

# 直接请求并保存一轮
npm run capture:sync -- data/captures/teams.har

# 每轮完成后等待 30 秒继续;Ctrl+C 停止
npm run capture:sync -- data/captures/teams.har --watch --interval=30

单轮默认最多 100 个请求,可用 --max-requests=50 调整。超过限额时按轮次继续,不会永远只读取列表头部。HAR 上限 256 MiB,单个响应上限 2 MiB。

数据库仍是 data/teams.sqlite,也支持 .env 中的 DATA_DIR。现有本地面板刷新后,在来源选择「网页 API」查看数据;现有 0.1.1 HTTP 服务可继续运行,API 采集进程直接通过 SQLite WAL 写入同一数据库。网页 API 与旧 DOM 来源各自去重,不强行合并历史记录。REST 和 OWA 对同一会议可能使用不同 ID,当前也不强制合并。

只需保持采集进程运行;使用本地面板时同时保持原本的 npm start 服务运行。原扩展的自动遍历可以停用,Teams 网页可以关闭。

登录和凭证到期

首次交互登录始终由微软页面完成。日常可以使用工具登录入口;手动 HAR 作为备用:Network 中勾选 Preserve log,触发聊天和有日程的一周;在开发者工具 Settings → Preferences → Network 勾选 Allow to generate HAR with sensitive data,再导出 Export HAR (with sensitive data)。微软 HAR 导出说明

HAR 保留在 data/captures/,目录已经被 Git 忽略;不要上传到公共 HAR 分析网站。原始文件包含聊天数据和登录凭证。工具的报告只保留接口模板、字段名、数量、状态和可读取的凭证到期时间;不把认证值或正文写入日志。认证值只从本地文件加载到进程内存,重放给原来的、受限制的微软服务。

0.6.0 的本地服务支持按实例自动续期。 登录期间将严格限制的 Microsoft OAuth 成功响应保存到独立凭证库,沿用实际捕获的客户端、资源/权限和源站参数刷新,不猜测跨资源授权。刷新结果必须匹配原租户、用户、客户端、资源及已有权限;凭证轮换后重建采集器并保留断点。401/403 时先尝试恢复;暂时失败退避重试,明确需要交互时才提示登录。JWT 的 exp 仅作提前续期参考,接口也可能提前撤销会话。微软刷新令牌说明

升级前只保存了业务 HAR 的实例需完成一次工具登录以建立续期材料。刷新令牌或浏览器恢复无法继续时,点击「从工具登录」完成微软要求的验证;已有数据和断点保留。独立命令行采集仍需导入新 HAR 后重启,不运行服务的续期流程。完整存储与恢复规则见 自动续期。

支持的抓包接口

用途 观察到的接口 处理
聊天增量列表 GET /api/csa/{region}/api/v3/teams/users/me/updates 保存聊天及发现的新会话;空增量不代表账号没有聊天
消息 GET /api/chatsvc/{region}/v1/users/ME/conversations/{id}/messages 校验每条消息属于请求会话;正文与游标事务提交
消息继续同步 响应 _metadata.syncState 只允许同一来源、同一会话路径与已观察参数;不跟随任意链接
REST 日历 抓到的 Graph 日历 GET /v1.0/me/events… 有标题及时间的事件可保存;缺标题的实例查询不冒充完整事件
OWA 日历列表 POST /owa/service.svc?action=GetCalendarView 精确验证动作和原始编码负载,只读重放
OWA 日历详情 POST /owa/service.svc?action=GetCalendarEvent 精确验证动作和原始 JSON 负载,保存详情

日历 POST 是实际观察到的读取 RPC,并未开放任意 POST。请求不跟随重定向,不重放发送消息、修改已读、登录令牌交换或其它未知操作。

消息支持实际观察的 RichText/Html 和 Text 用户正文。HTML 在本地以不执行脚本、不请求资源的解析器转换;图片形式的表情保留 alt 中的 Unicode 或可读代码,缺少时使用 title,再缺少则保留 [图片] 占位。纯表情消息不会因缺少文字节点被丢弃,MCP 可按保留的表情/说明搜索。已识别的 48: 活动通知流不作为聊天采集;通话事件、录制引用、成员变动和控制 XML 跳过。附件本体、消息下方的反应和删除语义仍需独立适配。聊天账号按已认证请求的租户/用户身份分区,允许该用户参加的跨租户会议聊天;每条消息仍须核对会话 ID。

日历范围沿用抓包的日期窗口,尚未自动滚动窗口或补齐全部事件详情。列表摘要不会清空已保存的正文和修改时间;取消仅记为 raw.isCancelled,不会当成删除。未获明确时区时保留原文而不伪造时间。

后续扩展

  1. 扩展自动续期对不可解析令牌和更多资源的适配;这些情况目前依赖本实例的浏览器会话恢复。
  2. 明确聊天列表初始全量同步与分页,历史消息分页已支持,但会话目录尚未证明完整。
  3. 日历滚动日期窗口、实例详情补全,以及 REST/OWA 事件的显式关联。
  4. 适配更多消息类型、编辑和明确删除标记。

纯分析器为 src/network-capture.js,请求验证为 src/network-probe.js,数据规范化为 src/teams-network-records.js,轮询和事务为 src/network-sync.js。凭证不进入记录或同步状态;同步游标单独保存在本地 state 表。