Brak opisu

iaun fdcfe48e95 Initial import of Teams local collector 4 tygodni temu
docs fdcfe48e95 Initial import of Teams local collector 4 tygodni temu
extension fdcfe48e95 Initial import of Teams local collector 4 tygodni temu
public fdcfe48e95 Initial import of Teams local collector 4 tygodni temu
scripts fdcfe48e95 Initial import of Teams local collector 4 tygodni temu
src fdcfe48e95 Initial import of Teams local collector 4 tygodni temu
tests fdcfe48e95 Initial import of Teams local collector 4 tygodni temu
.env.example fdcfe48e95 Initial import of Teams local collector 4 tygodni temu
.gitignore fdcfe48e95 Initial import of Teams local collector 4 tygodni temu
README.md fdcfe48e95 Initial import of Teams local collector 4 tygodni temu
package-lock.json fdcfe48e95 Initial import of Teams local collector 4 tygodni temu
package.json fdcfe48e95 Initial import of Teams local collector 4 tygodni temu
start.ps1 fdcfe48e95 Initial import of Teams local collector 4 tygodni temu

README.md

Teams 本地采集器

一个可运行的 Microsoft Teams 本地工具:API 后台采集、本地 SQLite 归档、MCP 查询与消息 WebHook,也支持可选浏览器扩展和 Microsoft Graph。

默认 API 路线不需要注册 Entra 应用,适合公司/学校账号暂时无法获得应用注册权限的情况。支持工具发起微软登录、后台轮询和已发现会话的历史分页补采。活动采集是可选实验功能,默认关闭。

0.7.1 支持按实例自动补下载历史聊天图片:开启后处理已有未下载图片及以后补录发现的图片,重启后继续;控制台可查看进度、暂停及批量重试暂时失败的图片。不同实例轮流处理,新消息图片优先,请求间隔和限流等待均持久保存。MCP 新增 configure_image_backfill。

0.7.0 新增聊天图片自动保存:新消息图片在后台写入本机,记录详情可预览和下载;历史图片支持按需补下载,MCP 提供 list_message_images 与 download_message_image。自定义表情统一显示为 :表情ID:(如 :quby-dance:),普通 Emoji 保持原样。详见 图片与表情。

0.6.2 修复自动续期反复失败及状态误报:过期浏览器缓存不再被视为恢复完成,等待微软页面提供可用新凭证再验证;页面跳转造成的临时缓存读取失败会在限时内重试。控制台分别显示续期中、等待重试和正常运行,已完成或取消的静默登录不再让状态一直显示忙碌。

0.6.1 修复会议聊天名称:会话详情中的 threadType=meeting 与普通聊天一样读取已验证的 topic,已有会议消息展示当前会议名并支持按名称搜索。补名不改写消息正文或历史版本;后续发现的会议会沿原有后台补名流程处理。

0.6.0 增加每实例独立的自动续期:优先在 Node 后台通过已捕获的微软刷新流程换取新访问令牌,到期前 5 分钟尝试,并恢复聊天、日历与历史采集器。刷新会话也失效时,用此实例保留的登录资料短时启动无窗口浏览器尝试恢复,完成后关闭;需要密码、MFA 或交互时才提示继续验证。Windows 刷新凭证使用当前系统用户的 DPAPI 加密,不进入业务 HAR、日志、数据库记录或 MCP。旧版会话需各自完成一次工具登录以建立续期材料;详见 自动续期。

0.5.0 增加网页 API 多实例:在「后台 API 采集」新增实例并分别登录,多账号可同时采集。实例名称、会话、采集开关、在线维持与历史进度分别管理;原有账号从默认实例继续使用。MCP 新增 list_instances,支持按实例和时间范围查找消息,关键词可留空。

每个实例的「保持 Teams 在线/可用」默认关闭。它使用登录或抓包中已验证的本人状态接口续期,不需要 Teams 网页常驻;缺少状态接口、凭证过期、限流或用户首选状态冲突时,会显示具体原因。可在登录窗口打开头像状态面板并选择可用,或将状态 HAR 放到 data/captures/ 后通过控制台导入当前实例。导入会验证账号归属并停止该实例,之后由用户手动启动。此功能不会延长 Microsoft 访问令牌的有效期。

「删除账号的本地记录」先预览再确认,删除该账号的消息、日历、版本、变更和关联提醒投递数据,并停止该实例,防止立即重新补录。其他账号的记录、账号绑定和提醒订阅保留;再次启动采集可能重新补回历史。Teams 云端、原始 HAR 和独立数据库备份不在删除范围内。详见 多实例与在线设置。

0.5.1 补充「本地资料库 → 删除示例 / 浏览器记录」,可直接清理未绑定实例的 demo 与 browser:* 账号。按来源和账号预览、确认后删除,不影响 API 实例;浏览器记录删除前应先暂停扩展,避免再次上传。

0.5.2 修复新账号会话已保存却无法启动的问题:历史补录建立初始请求时移除已观察到的 draftVersion 参数;历史初始化失败时保留实时聊天和日历采集,分别显示历史错误与会话/账号错误,不自动清除历史断点。

0.5.5 增加本地对方名称补全:对包含双方完整身份、且其中一方匹配当前账号的特定会话,校验本地发送者身份后,从同账号、同会话的对方消息中读取姓名作为显示名称。无需请求云端,不使用自己的姓名,不覆盖明确会话标题;仅有显示名称依据时,MCP 与 WebHook 的私聊分类仍保持未知。

0.5.4 修复部分会话漏补名称:同一会话最后一次抓包为空增量时,仍保留早期已验证响应中的会话链接,使用当前请求凭证补名;历史页验证并保存后也会将链接交给补名流程。不会因此重复轮询正文或重新扫描已完成历史。接口返回 401 时仍需在对应实例重新登录。

0.5.3 增加会话名称后台补采:沿已验证消息实际返回的同源 conversationLink 读取详情,从 threadProperties.topic 保存名称,每轮最多读取 3 个,成功后缓存 30 分钟。名称读取失败不影响正文同步。资料库与 MCP 使用当前会话名展示和搜索;原消息的 raw、哈希和历史版本保留,因此 versions[].title 仍可能是当时的「聊天消息」。

0.4.2 将会话名称与消息发送者分开展示。无标题且明确是一对一的聊天,可根据同账号、同会话中已确认的对方身份及姓名补全标题;不会把自己发送消息时的作者名当成对方。既有消息直接使用当前会话名展示,无需重新补录,也不重写消息的旧版本。

0.4.1 修复正文内表情及纯表情消息漏存;图片形式的表情保留 Unicode 或替代文字,无可读说明的图片保存为 [图片]。升级后会对已发现聊天重扫一次历史,补回漏存记录。历史请求默认间隔随机 2–5 秒,限流时遵守 Retry-After;控制台与 MCP 状态可查看等待情况。可用 HISTORY_REQUEST_MIN_DELAY_MS 和 HISTORY_REQUEST_MAX_DELAY_MS 调整并重启服务。

AI 接入:MCP 与消息提醒(0.4.0)

提供通用 stdio 与 Streamable HTTP 两种 MCP 接入。13 个工具可列出实例、搜索中英文消息、读取聊天上下文和历史版本、查询日历、检查采集状态、通过游标读取增量变化,以及管理 WebHook。另提供聊天总结和每日简报两个提示模板。AI 只读取本地已采集的数据,新数据由后台服务继续获取。

默认服务地址为 http://127.0.0.1:4318,MCP 端点为 http://127.0.0.1:4318/mcp;若在 .env 中修改了 PORT,请使用对应端口。生成通用客户端配置:

npm run mcp:config

生成的 data/mcp-clients/stdio.json 可以用于支持 command/args 的客户端,http.json 包含 HTTP 接入地址和专用本地认证密钥。各客户端配置字段可能略有不同,见 MCP 配置与工具说明。stdio 可以在服务停止时查询旧数据;新数据采集和 WebHook 投递需要本地服务保持运行。

提醒支持“全部新消息 / 仅 @我 / 仅私聊 / @我或私聊”,可按账号或聊天过滤,默认排除本人消息。新订阅默认关闭、默认不传正文;明确配置接收端后才会发送。历史补采、重复消息和编辑不触发提醒。队列支持签名、去重、持久化重试及投递记录,详见 WebHook 接收与配置。

不保持 Teams 网页打开:抓包 API 模式

支持从 HAR 读取已验证格式的消息、聊天列表、日历列表、详情及历史消息分页接口,并写入本地数据库。日常从本地面板发起登录,完成一次微软登录后关闭窗口;已有 HAR 也可以直接使用:

npm run capture:sync -- data/captures/teams.har --watch

每轮结束后等待 30 秒,属于轮询,非即时推送。新版服务在后台继续补历史,并按实例自动续期;原始 capture:sync 命令只做增量采集,独立历史命令为 capture:history,这两个独立命令不运行服务的续期调度。范围限于已发现会话的接口可见历史及抓到的日历窗口,不保证账号全部会话。操作与限制见 网页抓包 API 模式。

启动与使用(Windows)

需要 Node.js 24 或更高版本,Edge 或 Chrome。

git clone https://git.iaun.cn/iaun/ms-teams-tools.git
cd ms-teams-tools
npm ci
npm start

也可以在允许执行本地 PowerShell 脚本的环境中运行 .\start.ps1;首次启动缺少依赖时会运行 npm ci。直接使用上面的 npm 命令即可,无需调整系统策略。

  1. 打开 本地控制台。
  2. 在「后台 API 采集」点击「从工具登录」,在临时微软窗口完成公司 SSO/MFA。
  3. 查看控制台的已捕获接口:已有聊天接口即可尝试「完成登录」,不必进入指定聊天;只有尚未捕获聊天接口时,才需要打开任意聊天。日历可选,若需要采集且尚未捕获日历接口,再打开有日程的一周。
  4. 工具验证 API、保存会话、关闭登录窗口并启动后台采集。可以关闭控制台标签页,保持 Node 服务运行即可。
  5. 在来源筛选中选择「网页 API」,查看消息、日历和历史进度;自动续期需要继续验证时,再从对应实例打开登录窗口。

已有旧版本进程需要重启服务才能使用新按钮;扩展无需安装。默认 Edge 登录,也可运行 npm run capture:login -- --browser=chrome。工具登录仍由微软处理身份验证,不在本工具中收集密码。

可选浏览器扩展方式

  1. 打开 本地控制台,展开「可选:浏览器扩展」。
  2. 在 Edge 地址栏输入 edge://extensions(Chrome 使用 chrome://extensions),开启开发人员模式,点击「加载解压缩的扩展」,选择本项目的 extension 文件夹。
  3. 在控制台点击「复制密钥」。打开扩展的「设置」,填写密钥、唯一账号标签(例如工作邮箱)和端口 4318。
  4. 点击扩展设置中的连接测试,开启采集并保存设置。
  5. 点击「打开 Teams 登录」,在微软官方网页完成账号登录、MFA。扩展不读取密码、Cookie、令牌或输入框内容。
  6. 保存时扩展会自动连接已打开的 Teams 页面。打开需要保存的聊天并滚动加载消息,或打开日历;未收到心跳时点击扩展中的「重新连接页面」。
  7. 在扩展中点击「预览当前 Teams 页面」,确认能识别消息或日程。回到本地控制台查看记录、搜索、按账号筛选、打开历史版本、导出 NDJSON。

保持服务和 Teams 标签页打开。页面变化通常在约 0.6 秒防抖后触发采集,另有 20 秒心跳;后台标签页节流、网络重试和内容加载会影响延迟。这是页面观察式采集,不保证全量或秒级实时同步。

扩展详细设置、选择器调试和故障说明见 extension/README.md。

自动获取聊天(0.2.0)

已经能手动采集的用户,只需在 Edge/Chrome 扩展管理页重新加载本扩展,确认版本 0.2.0。本次自动聊天功能兼容 0.1.1 的本地服务接口,不需要重新配对或重启已运行的 0.1.1 服务。

  1. 打开扩展设置,找到「自动遍历聊天」,点击「保存并启动自动采集」。该功能默认关闭。
  2. 扩展新建一个不抢焦点的 Teams 采集标签。若它停留在登录页或没有显示聊天列表,在该标签完成登录并打开聊天列表,再从扩展点击重新启动;之后保持标签和本地服务运行。
  3. 扩展会依次打开已发现的聊天,先读取最新消息,再向上补充历史。默认每轮最多 50 个聊天、列表滚动 8 次、每个聊天历史滚动 2 次;完成后等待 120 秒再开始下一轮。这些限额均可在设置中调整。
  4. 弹窗和设置页显示本轮进度、下轮时间与错误。在采集标签中操作会暂停自动遍历;使用原来的 Teams 标签处理工作。点击「停止自动采集」保留采集标签和待发队列,重新启动后继续。

自动打开聊天可能改变未读状态或触发已读回执,启用按钮旁也有提示。微软已读回执说明。

该方式仍依赖网页加载,后台标签节流会延迟执行;不会自动获取全部历史或遍历日历。若提示未识别聊天列表/稳定标识,可在设置中点击「预览能发现的聊天」,再根据实际页面调整聊天行、聊天列表和消息列表选择器。无法确认消息区已经切换时会暂停,避免把消息记入错误的聊天。

已配对但没有数据

配对测试只证明扩展可以访问本地服务。页面采集还需要扩展脚本在 Teams 标签页中运行。

如果从 0.1.0 升级:

  1. 在运行服务的终端按 Ctrl+C,再执行 npm start。
  2. 在 Edge/Chrome 扩展管理页,找到「Teams 本地记录助手」并点击重新加载,确认版本为 0.2.0。不需要重新生成密钥或重新安装。
  3. 打开扩展设置,确认采集已开启,点击「重新连接页面」。扩展会检查已打开的 Teams 标签页,并在缺少脚本时自动加载。
  4. 本地控制台会分别显示「已配对」「等待页面」「页面已连接」或具体错误。若页面已连接但没有条目,再使用预览检查聊天/日历选择器。

0.1.0 在保存设置时忽略了向现有标签页发送消息的失败,无法补加载采集脚本;控制台也把“未收到页面心跳”统一显示成“等待配对”。0.1.1 修复这些状态与恢复流程。它不能保证所有组织的 Teams 页面结构都能由默认选择器识别。

当前覆盖范围

内容 默认 API 方式 可选浏览器扩展 可选 Graph 方式
登录 工具临时打开微软窗口,验证后关闭 Teams 官方页面,沿用浏览器会话 MSAL + 授权码 PKCE,需自己的 Entra 应用
聊天 已发现聊天的增量同步及历史分页,支持断点恢复 已加载且被选择器识别的消息 当前用户聊天列表、私聊/群聊/会议聊天消息,完整分页
日历 已捕获的日历窗口和详情查询 当前页面可识别的日程卡片 默认日历指定窗口,包含实例和例外,delta 跟踪
活动 跳过活动通知流 实验性活动页条目,默认关闭 本地消息/日程变更记录,不是 Teams 通知 Feed
历史更新 按账号及会话保存版本;较旧历史不覆盖新正文 有稳定页面 ID 时保存修订 按账号、聊天、消息 ID 保存修订和删除标记
后台运行 Node 独立轮询并自动续期,必要时短时恢复登录会话 仍需 Teams 页面与服务运行 已授权且本地进程运行时轮询,默认 30 秒

浏览器限制:

  • Teams 的虚拟列表不会把全部历史放进页面。自动模式在设定限额内打开聊天、滚动加载内容;列表中未发现的聊天和未加载的消息不在覆盖范围。
  • Teams 界面会更新。内置选择器来自兼容策略和离线页面夹具,真实组织页面可能需要调整;设置页支持自定义 CSS 选择器和预览。
  • 日历若由跨域 Outlook iframe 渲染,当前仅支持 Teams 顶层页面的扩展无法读取该 iframe。预览为 0 时检查页面结构,或改用 Graph。
  • 只有带明确日期与时区的时间才转成时间戳;“今天 09:00”等保留在原始字段中,不伪造日期。
  • 没有稳定 ID 时按内容和会话生成标识,相同重复消息可能合并,编辑可能形成新条目;原始字段会记录身份策略。
  • 账号标签由用户指定;同一浏览器配置只采集一个 Teams 账号。切换租户/账号前暂停采集并修改标签,多个账号请使用独立浏览器配置文件。
  • 断线待传队列保存在当前页面内存,最多 1000 条;关闭/刷新页面、更换扩展上下文或修改账号标签会清空未发送队列。停止巡检和修改同账号参数会保留队列;交付失败会暂停自动切换聊天。
  • 自动模式用验证过的稳定会话标识去重;早期被动采集若只能使用标题派生标识,升级后可能存在同一消息的两种记录。不会按同名聊天强行合并已有数据。
  • 不采集附件文件本体、频道帖子、通话录音或完整通知历史。

可选:Graph 登录配置

如果以后获得应用注册权限:

  1. 在 Microsoft Entra 注册应用,面向公司或学校账号。
  2. 添加 移动和桌面应用(Public client) 平台,回调地址设置为 http://localhost:4318/auth/callback。不要使用 Web confidential client,不需要 client secret。
  3. 配置 Microsoft Graph 委派权限:User.Read、Chat.Read、Calendars.Read。组织可能需要管理员同意。
  4. 将 .env.example 复制为 .env,填写 MS_CLIENT_ID;单租户应用把 MS_TENANT_ID 改为真实 tenant ID。
  5. 重启服务,在控制台展开 Graph 面板,点击「Microsoft 登录」,完成微软登录后自动返回本地控制台。

默认每 30 秒轮询全部已发现聊天,日历窗口为过去 30 天到未来 90 天。窗口每日按 UTC 重建;同一天内使用 delta 游标。消息采用修改时间水位、两分钟重叠窗口和幂等 upsert;完整翻页成功才提交水位。

Graph 登录缓存仅在进程内存中,服务重启后需要重新登录,数据与同步游标不会丢失。退出本地授权不会退出整个微软浏览器会话,也不会删除已归档数据。

日历 delta 的 @removed 可能表示离开当前视图,不一定是远端删除;本工具保存为「从同步视图移除」,保留旧正文,忽略未知条目的移除通知。后续重新出现时清除该标记。

本地文件与配置

data/teams.sqlite       当前记录、历史版本、游标和运行日志
data/teams.sqlite-wal   SQLite 运行期日志(运行时可能存在)
data/teams.sqlite-shm   SQLite 运行期共享文件(运行时可能存在)
data/pairing.json       扩展配对密钥
data/mcp-auth.json      专用本地 MCP HTTP 认证密钥
data/mcp-clients/       生成的 stdio / HTTP 客户端配置
.env                    可选本机配置

数据含正文和原始字段,以明文存储。默认仅监听 127.0.0.1,使用 Host/Origin 校验、独立扩展上传密钥、本地操作令牌、请求体限制和文本渲染。不要把服务公开到网络。

仓库只包含代码、测试和通用文档;.env、data/、artifacts/、真实账号的本地验证/诊断记录、HAR、数据库及私钥均已加入 .gitignore。需要自定义配置时,将 .env.example 复制为 .env 后填写。若修改 DATA_DIR 或另行导出聊天、截图、MCP 客户端配置,也应将相应目录加入忽略规则;提交前检查暂存内容,避免包含账号信息、消息正文和凭证。

停止服务后,复制整个数据目录即可备份;运行中不要只拷贝 .sqlite 而遗漏 WAL。配对密钥、数据库、.env 已加入 .gitignore。

环境变量 默认值 用途
PORT 4318 本机端口,修改后同步更新扩展和 Entra 回调
DATA_DIR ./data 数据目录
MS_CLIENT_ID 空 可选 Graph 应用 ID
MS_TENANT_ID organizations 租户 ID/域名;单租户应用填写指定 tenant ID
POLL_INTERVAL_SECONDS 30 Graph 每次同步结束后的等待时间
HISTORY_REQUEST_MIN_DELAY_MS 2000 每次历史请求前随机等待的最小毫秒数
HISTORY_REQUEST_MAX_DELAY_MS 5000 每次历史请求前随机等待的最大毫秒数
CALENDAR_PAST_DAYS 30 Graph 日历过去天数
CALENDAR_FUTURE_DAYS 90 Graph 日历未来天数

验证与扩展

npm test
npm run check
npm audit

自动化测试覆盖 DOM 聊天/日历解析、隐私排除项、队列重试与大小限制、OAuth PKCE/state/过期/退出竞争、Graph 分页/限流/游标/账号隔离、SQLite 幂等与历史、本机接口访问控制和导出。真实账号登录、组织权限和 Teams 页面兼容性需要用户配对扩展后验收。

数据源通过统一记录格式入库;src/ai-service.js 提供受限查询,src/mcp-server.js 适配 MCP,src/message-signals.js 识别消息分类,src/webhook-service.js 管理持久投递。后续可增加新的 MCP 工具、数据源适配器或事件类型。