README.md 11 KB

Teams 浏览器扩展

适用于 Chrome / Microsoft Edge(Chromium 120+)。无需 Entra 应用注册或管理员 Graph 权限,复用浏览器中的正常 Microsoft 登录。此方案读取您在 Teams 网页中打开的可见、已加载 DOM 内容;尚未使用真实公司租户完成页面适配验收。

安装和首次使用

0.2.2 将明确标记的自定义表情显示为 :表情ID:。0.2.1 修复消息正文中以图片显示的表情,包括纯表情消息;保留 alt/可访问说明,无说明的图片用 [图片] 标记。已安装用户需在扩展管理页重新加载扩展并刷新 Teams 页面,使页面解析脚本更新。默认后台 API 路线不需要此操作。图片文件的自动下载由主工具的后台 API 采集提供。

  1. 在项目根目录执行 npm install、npm start,访问 http://127.0.0.1:4318/,复制本地控制台中的扩展配对令牌。
  2. 在 Edge 打开 edge://extensions,或在 Chrome 打开 chrome://extensions;开启“开发人员模式”,选择“加载解压缩的扩展”,选择本目录 extension。如果公司策略禁止加载,请联系管理员;本工具不能绕过浏览器策略。
  3. 打开扩展“设置”:填写唯一账号标签(例如 contoso-work)、配对令牌和本地服务端口,点击“测试连接”。
  4. 点击“打开 Teams 登录”,在 Microsoft 页面完成公司单点登录、密码和 MFA。扩展不接触 Microsoft 密码、Cookie、访问令牌或页面输入框。
  5. 回到扩展设置,勾选“启用此账号的可见页面采集”,保存。默认关闭采集,活动项默认关闭。
  6. 在 Teams 网页打开聊天或日历。保存设置、打开弹窗时,扩展会探测已经打开的 Teams 标签,并在缺少采集脚本时自动连接。打开扩展弹窗观察“就绪页面 / Teams 页面”、可见条目数、成功连接和错误,再到本地控制台查看 browser 来源记录。

升级到 0.2.0 与自动遍历聊天

已运行 0.1.1 本地服务并能记录聊天时,在扩展管理页点击「重新加载」,确认版本 0.2.0 即可;无需重启服务或重新配对。打开设置中的「自动遍历聊天」,点击 「保存并启动自动采集」。

扩展会新建一个不抢焦点的 Teams 采集标签,使用现有浏览器登录会话;如遇登录页或未显示聊天列表,完成登录、打开聊天列表后,再从扩展重新启动。它不会接管原来的 Teams 标签。默认每轮最多 50 个聊天、列表滚动 8 次、每个聊天历史滚动 2 次,完成后等待 120 秒重复;每次打开聊天先加载最新消息,再补历史。设置可调整限额与等待时间。

自动打开聊天可能改变未读状态或触发已读回执。 微软说明。自动模式默认关闭,开启前请阅读设置中的提示。

在采集标签中点击或键盘操作会暂停巡检。使用普通 Teams 标签工作;停止巡检后保留专用标签和待发队列,显式重新启动才继续。关闭采集标签会停止自动模式。修改账号标签后需重新启动,并确认对应浏览器会话正确。

弹窗与设置页显示发现/完成聊天数、下轮时间、覆盖限制和错误。「预览能发现的聊天」只读检查专用标签(没有专用标签时用普通 Teams 页),支持尚未保存的聊天行/列表选择器。聊天行必须带稳定标识,仅显示名称或列表序号不足以区分同名聊天。自动模式无法确认消息区切换、稳定显示或成功交付时会暂停;页面节流会延迟,不能保证全量历史或即时推送。日历仍按用户打开的页面采集。

从 0.1.0 升级

更新项目后,先在运行服务的终端按 Ctrl+C,重新执行 npm start。然后在 edge://extensions 或 chrome://extensions 对本扩展点击“重新加载”,确认版本为 0.2.0。0.1.1 增加的 scripting 权限用于连接安装前已经打开的 Teams 顶层页面;0.2.0 没有新增权限。

打开扩展弹窗或设置,点击 “重新连接页面”。该操作使用已保存配置,并显示就绪页面数量或具体失败原因。通常无需重新输入配对设置。若浏览器仍保留已失效的旧扩展上下文,刷新 Teams 页面,再点击重新连接。

一个浏览器配置只用于一个 Teams 账号。切换 Teams 账号前先暂停采集,再改成不同账号标签并保存;扩展不会自动识别租户/账号,多个同标签账号会混入同一份本地数据。标签更改不会移动历史数据。不同账号建议使用不同浏览器配置。

采集范围和可靠性

  • 聊天:收集具体消息容器的可见正文,尽力提取作者和明确时间;跳过聊天侧栏、输入框、编辑器、隐藏元素和工具栏。不会读取草稿或自动发送消息。
  • 日历:收集当前页面已加载的事件卡片。不会自动打开其他日期,也不能确保拿到地点、参会者或完整详情。
  • 活动:仅有两个窄范围选择器作为实验性适配;可保持关闭,不影响聊天和日历。
  • 普通页面变化触发约 600 ms 的合并采集,20 秒心跳补采;后台标签页节流会延迟。自动模式在专用标签内按限额遍历、滚动,并只在消息区验证稳定后采集;未发现会话、未加载历史和附件内容不在覆盖范围。
  • 不会通过 UI 消失推断删除;没有读取权限的内容也不会被采集。
  • 有稳定 DOM ID 时可追踪正文变化。无 ID 时以内容、时间原文和会话上下文计算标识,编辑可能生成新条目,相同内容可能合并。这不是完整归档或保证无遗漏的服务。
  • 只有带日期和时区的完整时间才写标准时间;“昨天 10:30”等原文保存在 raw.timeText,标准时间为 null。
  • 本地服务失败时先有限重试 3 次;普通页面随心跳再次尝试,自动巡检暂停等待显式重新启动。只有成功响应才推进去重记录。页面内存最多保留 1000 条待发记录;停止和修改同账号参数会保留队列,关页、刷新、更换扩展上下文或修改账号标签会清空。后台状态不保存消息正文;已送达记录在本地数据库保存。
  • 自动巡检使用经过确认的稳定会话标识;旧记录若使用标题派生标识,可能与自动模式产生的同一消息记录并存,不会按聊天名称强制合并。
  • 每次扫描和请求最多 200 条,实际发送按 150 条 / 750 KB 分批。拥塞或上限在弹窗中显示。稳定 DOM ID 的数据重复发送由本地数据库去重。

页面结构变化和诊断

设置页展开“高级”,点击“预览当前匹配”。预览读取最近使用的 Teams 标签页,显示数量和最多 5 条文本摘要,不会写数据库。自定义选择器必须指向一个消息或日历事件容器,例如 [data-message-id]、[data-event-id];以实际页面为准。不要使用 body、main、整个列表或泛化的 div 选择器。语法错误会显示,留空恢复默认。

先区分连接状态:仅“测试连接”成功表示本地服务可达;“页面脚本已就绪”表示采集脚本已经启动;收到页面心跳后才证明 Teams 页面到本地服务的采集链路已连通。即使没有匹配任何记录,已启用的页面仍会发送空批次心跳。因此“已连接但 0 条”应检查打开的内容和选择器,“页面脚本未连接”则应先点击重新连接,并检查扩展的网站访问权限。

登录状态是根据可见 Teams 内容和应用外壳推断,不是登录令牌校验。没有明确证据时为“未知”(null),不表示账号已退出。Teams 新版可能使用不同 DOM,真实账号下应分别验证一条新消息和一个日历事件是否出现在本地控制台。仅解析 Teams 顶层页面;若新版日历使用独立 Outlook 跨域框架,其内容不可由当前权限读取,此时预览会是 0,需要后续另行适配,不能视为日历没有事件。

本地连接失败先检查服务与端口。401/403 通常需要重新复制令牌;服务轮换配对令牌后必须更新扩展。初次连接时若浏览器提示访问本地网络,请允许连接此本地服务。扩展诊断与页面心跳分别展示,保存配置不再将“设置已保存”当作页面已经连接。诊断接口返回 404 时,请重启本地服务加载新版本。

实现和扩展点

parser.js 是可独立测试的纯 DOM 解析器;queue.js 管理页面中的待发和已成功发送集合。content.js 加载 content-runtime.js,后者以单例管理 MutationObserver、SPA 补采、心跳与错误报告,避免重复注入时创建多个观察器。background.js 启动 background-runtime.js,后者验证消息来源、探测或按需注入 Teams 顶层页面、读取配对令牌并调用固定 127.0.0.1 的接口。PROBE 会等待内容运行时初始化完成;配置通知失败会反馈到设置页。config.js 包含配置、来源和边界验证。扩展页面渲染使用 textContent。

后台通过 /api/extension/status 报告账号标签、扩展版本、开关状态、Teams 标签数量、就绪数量和错误;该接口不发送页面正文。/api/extension/events 接收内容批次及页面心跳,/api/extension/ping 仅用于连接测试。

chrome.storage.local 仅允许受信扩展上下文访问。内容脚本获得的配置不含配对令牌。运行时不接收网页 postMessage,不启用外部消息,不申请 cookies、debugger、webRequest、浏览历史或全站权限。允许的网络主机只有两个 Teams 域名和本机回环地址。若需支持新 DOM,在 DEFAULT_SELECTORS 添加窄范围候选并补真实脱敏 fixture。

离线测试:在项目根目录执行 node --test tests/extension.test.js tests/extension-runtime.test.js tests/extension-bridge.test.js。测试覆盖解析、隐藏节点、输入隔离、身份与时间、消息来源、配置、重试和队列;运行时测试还覆盖已有标签自动注入、初始化等待、重复初始化、错误反馈和恢复,桥接测试验证内容运行时经后台和 HTTP 写入 SQLite、空记录心跳及去重。这些测试不代表已完成真实 Teams 账号验证。

参考官方文档:内容脚本隔离环境、跨域网络请求、扩展消息传递、可访问资源清单。