# 通过网页抓包使用 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 可查看续期状态;详见[自动续期说明](AUTO-RENEWAL.md)。 工具默认使用已安装的 Microsoft Edge。命令行入口也支持 Chrome: ```powershell 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`,才标记该会话的**接口可见历史**完成。无起点证据、循环游标或页数上限均明确报告截断,不冒充完成。 ```powershell # 单独补采一批,再次运行续传;勿与同一库的后台采集并行 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、账号诊断与运行记录仅保存在本地,不随仓库发布。 ## 使用 在项目目录执行: ```powershell # 分析:只读取 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 导出说明](https://learn.microsoft.com/en-us/microsoft-edge/devtools/network/reference#save-all-network-requests-to-a-har-file) HAR 保留在 `data/captures/`,目录已经被 Git 忽略;不要上传到公共 HAR 分析网站。原始文件包含聊天数据和登录凭证。工具的报告只保留接口模板、字段名、数量、状态和可读取的凭证到期时间;不把认证值或正文写入日志。认证值只从本地文件加载到进程内存,重放给原来的、受限制的微软服务。 **0.6.0 的本地服务支持按实例自动续期。** 登录期间将严格限制的 Microsoft OAuth 成功响应保存到独立凭证库,沿用实际捕获的客户端、资源/权限和源站参数刷新,不猜测跨资源授权。刷新结果必须匹配原租户、用户、客户端、资源及已有权限;凭证轮换后重建采集器并保留断点。401/403 时先尝试恢复;暂时失败退避重试,明确需要交互时才提示登录。JWT 的 `exp` 仅作提前续期参考,接口也可能提前撤销会话。[微软刷新令牌说明](https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens) 升级前只保存了业务 HAR 的实例需完成一次工具登录以建立续期材料。刷新令牌或浏览器恢复无法继续时,点击「从工具登录」完成微软要求的验证;已有数据和断点保留。独立命令行采集仍需导入新 HAR 后重启,不运行服务的续期流程。完整存储与恢复规则见 [自动续期](AUTO-RENEWAL.md)。 ## 支持的抓包接口 | 用途 | 观察到的接口 | 处理 | | --- | --- | --- | | 聊天增量列表 | `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` 表。