核查日期:2026-09-08。结论依据微软官方文档;DOM 覆盖度、路线取舍属于工程判断,尚未通过用户的真实 Teams 账号验证。
用户随后明确要求通过网页抓包,在关闭 Teams 网页后直接使用 API。当前已改变下面「第一版选择」中的私有接口取舍:完成真实 Teams 消息 GET、聊天增量列表 GET、REST 日历 GET、OWA GetCalendarView/GetCalendarEvent 只读 POST 的重放与 SQLite 入库。接口适配以用户提供的本地 HAR 为证据,不根据名称猜测任意接口或发送未知请求。详见 抓包 API 实现与限制。
HAR 中保留的会话凭证可支持网页关闭后的请求,但本次没有取得与当前采集会话匹配的完整刷新流程,因此没有承诺无交互长期续期。第一版下文中的「不读取认证头、不重放私有请求」仅描述原 DOM 路线,不再代表用户授权后的抓包模式。
0.3.0 进一步加入工具发起的临时微软登录窗口:Playwright 使用独立持久配置目录,捕获通过已有验证器的业务读取请求,保存会话并关闭窗口;Node 进程接管后无需浏览器常驻。登录页仍由微软处理 SSO/MFA,这属于 Teams 网页自身登录,不把微软第一方 client ID 伪装为本工具。是否能通过组织设备/登录策略需要实际认证验证。Playwright 持久配置与关闭行为
历史分页已实测 startTime=0 及响应 backwardLink,消息范围可向前补采。聊天目录仍是已观察/增量发现范围;删除已捕获列表请求的同步头返回 400,没有将该猜测实现为全量目录。刷新令牌绑定用户与客户端、并不绑定单一资源;本次没有验证合法跨资源刷新流程,不能从返回资源不匹配推断其绝对不可行,也不能据此假定可长期自动续期。微软刷新令牌说明
以 Teams 网页 + 浏览器扩展 + 本地 SQLite 为主路线。用户不具备注册 Entra 应用的条件,因此无需先配置 Graph,也可在微软网页完成登录并尝试采集已呈现的数据。聊天、日历为首要目标;活动页捕获为可选实验能力,无法稳定识别时不影响其他数据采集。
| 路线 | 适用范围 | 前置条件和边界 | 本项目取舍 |
|---|---|---|---|
| 网页扩展 | 当前已加载、可见的聊天/消息、日历条目,实验性活动条目 | 用户正常登录 Teams 网页并启用扩展;关闭页面、未加载的历史和虚拟列表外内容无法保证采集 | 默认路线 |
| Microsoft Graph | 登录用户参与的聊天消息、用户日历 | 需要自有 Entra 应用注册和 delegated 授权;聊天接口不支持个人 Microsoft 账号 | 可选模块,默认约 30 秒轮询 |
| Teams 桌面客户端 | 后续可研究受支持的系统集成或 UI 观察 | 未找到向外部采集器开放的稳定客户端数据读取接口 | 后续研究,不作为本版依赖 |
| Teams 私有网页请求 | 可能涉及网页内部数据结构 | 未文档化接口没有可依赖的版本契约 | 不重放私有请求,不提取会话令牌 |
Edge 扩展通过限定 URL 的 host permissions 和 content-script 匹配访问页面,企业策略可能限制安装。新 Teams 客户端基于持续更新的 WebView2;这不意味着外部扩展可以直接安装进 Teams 客户端。扩展匹配规则、企业扩展管理、新 Teams 客户端说明
扩展打开 https://teams.microsoft.com/v2/,用户在微软页面完成账户选择、密码和 MFA。扩展记录页面上的登录可见状态,而不是验证账号凭据;本地配对只授权向本地服务提交观察结果,与 Microsoft OAuth 无关。浏览器仍按自身机制保存 Teams 会话。
扩展只观察 Teams 页面的 DOM,不读取密码、输入框值、cookies、请求认证头或访问令牌。用户为每个账号设置唯一标签;切换 Teams 账号时应同步切换标签,避免把两个账号的数据记在一起。
“持续采集”表示监听页面变化后重复观察,并不承诺后台完整同步或确定的端到端延迟:
这些限制来自网页观察方式本身;静态 DOM 测试通过也不能证明真实账号的覆盖率。
| 数据 | v1.0 请求 | 最低 delegated 权限 |
|---|---|---|
| 聊天列表 | GET /me/chats |
Chat.ReadBasic |
| 消息正文 | GET /chats/{chat-id}/messages |
Chat.Read,同时可用于聊天列表 |
| 时间窗口内的日历实例 | GET /me/calendar/calendarView?startDateTime=...&endDateTime=... |
Calendars.ReadBasic;需要正文使用 Calendars.Read |
| 当前用户资料 | GET /me |
User.Read |
聊天列表和消息接口需要组织账号。日历视图会展开范围内的重复事件实例和例外。第一版 Graph 使用 User.Read、Chat.Read、Calendars.Read,不需要写聊天或写日历权限。聊天列表、聊天消息、日历视图、用户资料
Chat.Read 和 Calendars.Read delegated 权限本身不强制管理员同意,但租户仍能限制用户同意和应用注册;已有 Teams 登录不能替代自有 Graph 应用授权。权限表、用户同意策略
Graph 模块采用 MSAL Node public-client 授权码流程:浏览器授权 URL → 本地回调校验 state 和有效期 → 使用 PKCE verifier 交换令牌 → 后续静默续期。默认回调为 http://localhost:4318/auth/callback,必须与应用注册匹配,不使用 client secret。令牌只保存在服务内存中,服务重启后重新登录。MSAL Node 授权流程、OAuth 授权码与 PKCE
消息接口最大 $top=50。按修改时间增量读取时,应同时使用 $orderby=lastModifiedDateTime desc 和 $filter=lastModifiedDateTime gt ...;两者属性不一致会使过滤失效。必须遍历 @odata.nextLink 后再更新水位,并使用重叠窗口与幂等写入处理边界重复。不能仅看消息创建时间,否则会漏掉较早消息的编辑。消息查询规则
消息 ID 只在所属聊天内保证唯一,不同聊天可能重复。Graph adapter 将编码后的聊天 ID 与消息 ID 组合为 externalId,保留 parentId 和 raw.id,防止跨聊天归档覆盖。消息 ID 的作用域
日历 calendarView/delta 可跟踪指定时间窗口的变化;需保存服务器返回的完整 @odata.deltaLink。窗口推进需重新建立范围。轮询是近实时尝试,受请求耗时和限流影响;遇到 429 应遵守 Retry-After 并退避。日历增量、Graph 限流处理
日历 delta 的 @removed 即使写着 reason=deleted,也可能来自窗口外事件的新增或更新,不能直接证明远端事件已删除。本项目对已归档事件设置 removedFromView=true、deleted=false,保留原有标题和正文,显示“从同步视图移除”;从未归档过的移除 tombstone 忽略,不生成空白日程。真正删除需要另外证据,当前没有把这一标记当作确认删除。日历 delta 响应语义
后续可以增加 Graph change notifications:单个聊天的 /chats/{chat-id}/messages 订阅支持 Chat.Read,但本地端口不能直接接收来自 Graph 的推送,需公网 HTTPS 回调、验证与续期机制。用户级 /users/{user-id}/chats/getAllMessages 的订阅指南示例目前使用 beta,不作为第一版依赖。消息订阅、Webhook 要求
消息订阅最长 3 天,rich notifications 最长不足 1 天;Teams 消息订阅有效期超过 1 小时还需 lifecycleNotificationUrl。官方列出的聊天消息通知平均延迟小于 10 秒、最大 1 分钟,因此推送同样不等于零延迟。订阅有效期和延迟
截至核查日,官方 Teams Activity Feed 文档说明的是发送通知,没有找到读取用户完整活动 Feed 的公开 API。TeamsActivity.Send 不能用于读取。此结论是对现有官方文档的核查结果,不是对未来能力的断言。官方活动通知接口
项目保留两种明确区分的数据:
source=browser, kind=activity:可选、实验性的活动页面已观察条目;不代表完整 Feed。source=graph, kind=activity, raw.derived=true:本地同步发现消息或日历记录变更后生成的变更日志;首次发现不等于刚刚发生,绝不是 Teams 活动通知。优先验证聊天和日历链路,活动页选择器适配可以延后。真实验收应检查登录、账号切换、页面覆盖、编辑与重复采集、离线恢复;本调研没有执行真实账号登录或完成这些线上验证。