|
|
4 tuần trước cách đây | |
|---|---|---|
| docs | 4 tuần trước cách đây | |
| extension | 4 tuần trước cách đây | |
| public | 4 tuần trước cách đây | |
| scripts | 4 tuần trước cách đây | |
| src | 4 tuần trước cách đây | |
| tests | 4 tuần trước cách đây | |
| .env.example | 4 tuần trước cách đây | |
| .gitignore | 4 tuần trước cách đây | |
| README.md | 4 tuần trước cách đây | |
| package-lock.json | 4 tuần trước cách đây | |
| package.json | 4 tuần trước cách đây | |
| start.ps1 | 4 tuần trước cách đây |
一个可运行的 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 调整并重启服务。
提供通用 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 接收与配置。
支持从 HAR 读取已验证格式的消息、聊天列表、日历列表、详情及历史消息分页接口,并写入本地数据库。日常从本地面板发起登录,完成一次微软登录后关闭窗口;已有 HAR 也可以直接使用:
npm run capture:sync -- data/captures/teams.har --watch
每轮结束后等待 30 秒,属于轮询,非即时推送。新版服务在后台继续补历史,并按实例自动续期;原始 capture:sync 命令只做增量采集,独立历史命令为 capture:history,这两个独立命令不运行服务的续期调度。范围限于已发现会话的接口可见历史及抓到的日历窗口,不保证账号全部会话。操作与限制见 网页抓包 API 模式。
需要 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 命令即可,无需调整系统策略。
已有旧版本进程需要重启服务才能使用新按钮;扩展无需安装。默认 Edge 登录,也可运行 npm run capture:login -- --browser=chrome。工具登录仍由微软处理身份验证,不在本工具中收集密码。
edge://extensions(Chrome 使用 chrome://extensions),开启开发人员模式,点击「加载解压缩的扩展」,选择本项目的 extension 文件夹。4318。保持服务和 Teams 标签页打开。页面变化通常在约 0.6 秒防抖后触发采集,另有 20 秒心跳;后台标签页节流、网络重试和内容加载会影响延迟。这是页面观察式采集,不保证全量或秒级实时同步。
扩展详细设置、选择器调试和故障说明见 extension/README.md。
已经能手动采集的用户,只需在 Edge/Chrome 扩展管理页重新加载本扩展,确认版本 0.2.0。本次自动聊天功能兼容 0.1.1 的本地服务接口,不需要重新配对或重启已运行的 0.1.1 服务。
自动打开聊天可能改变未读状态或触发已读回执,启用按钮旁也有提示。微软已读回执说明。
该方式仍依赖网页加载,后台标签节流会延迟执行;不会自动获取全部历史或遍历日历。若提示未识别聊天列表/稳定标识,可在设置中点击「预览能发现的聊天」,再根据实际页面调整聊天行、聊天列表和消息列表选择器。无法确认消息区已经切换时会暂停,避免把消息记入错误的聊天。
配对测试只证明扩展可以访问本地服务。页面采集还需要扩展脚本在 Teams 标签页中运行。
如果从 0.1.0 升级:
Ctrl+C,再执行 npm start。0.1.0 在保存设置时忽略了向现有标签页发送消息的失败,无法补加载采集脚本;控制台也把“未收到页面心跳”统一显示成“等待配对”。0.1.1 修复这些状态与恢复流程。它不能保证所有组织的 Teams 页面结构都能由默认选择器识别。
| 内容 | 默认 API 方式 | 可选浏览器扩展 | 可选 Graph 方式 |
|---|---|---|---|
| 登录 | 工具临时打开微软窗口,验证后关闭 | Teams 官方页面,沿用浏览器会话 | MSAL + 授权码 PKCE,需自己的 Entra 应用 |
| 聊天 | 已发现聊天的增量同步及历史分页,支持断点恢复 | 已加载且被选择器识别的消息 | 当前用户聊天列表、私聊/群聊/会议聊天消息,完整分页 |
| 日历 | 已捕获的日历窗口和详情查询 | 当前页面可识别的日程卡片 | 默认日历指定窗口,包含实例和例外,delta 跟踪 |
| 活动 | 跳过活动通知流 | 实验性活动页条目,默认关闭 | 本地消息/日程变更记录,不是 Teams 通知 Feed |
| 历史更新 | 按账号及会话保存版本;较旧历史不覆盖新正文 | 有稳定页面 ID 时保存修订 | 按账号、聊天、消息 ID 保存修订和删除标记 |
| 后台运行 | Node 独立轮询并自动续期,必要时短时恢复登录会话 | 仍需 Teams 页面与服务运行 | 已授权且本地进程运行时轮询,默认 30 秒 |
浏览器限制:
如果以后获得应用注册权限:
http://localhost:4318/auth/callback。不要使用 Web confidential client,不需要 client secret。User.Read、Chat.Read、Calendars.Read。组织可能需要管理员同意。.env.example 复制为 .env,填写 MS_CLIENT_ID;单租户应用把 MS_TENANT_ID 改为真实 tenant ID。默认每 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 工具、数据源适配器或事件类型。