# 本地采集器架构
第一版使用 Node.js 24、ES modules 和 `node:sqlite`。浏览器扩展是默认数据源,Graph 是可选数据源;内部字段和接口约定见 [CONTRACTS.md](CONTRACTS.md)。
```mermaid
flowchart LR
Teams["Teams 网页
微软登录与 MFA"] --> DOM["扩展 DOM 解析器
仅已加载可见内容"]
DOM --> Worker["扩展后台
配对令牌与账号标签"]
Worker -->|回环 HTTP 提交| API["本地服务
验证与规范化"]
Entra[可选 Entra 登录] --> Graph["Graph provider
约 30 秒轮询"]
Graph --> Store[统一 Store]
API --> Store
Store --> DB[(本地 SQLite)]
DB --> UI["本地面板
查询、历史、NDJSON 导出"]
```
## 模块边界
| 模块 | 职责 | 边界 |
| --- | --- | --- |
| 浏览器 DOM 解析器 | 从页面提取规范化聊天、消息、日历和实验性活动条目 | 不发送网络请求、不读取登录凭据;选择器可独立用 DOM fixture 测试 |
| 聊天自动遍历器 | 专用标签内发现稳定聊天行、加载最新与有限历史、周期重复 | 默认关闭;只采集验证过的消息区;用户操作或传输失败时暂停;可能改变已读状态 |
| 扩展后台 | 用户启停、账号标签、登录入口、本地配对和批量提交 | 本地服务令牌不传给 Teams 页面;关闭页面后无全量数据来源 |
| 本地 HTTP 服务 | 静态面板、入口校验、查询和导出、调度 provider | 向 Store 写入前验证输入;浏览器提交不能自报成 Graph 来源 |
| Graph provider | MSAL 登录、分页、同步水位、日历增量、重试和状态 | 缺少 client ID 时保持未配置状态,不影响扩展路线 |
| Store | 稳定身份、幂等 upsert、版本快照、同步状态、运行日志 | 不依赖 Teams DOM 或 OAuth;存储来源提供的普通数据 |
| 本地面板 | 展示来源、账号、覆盖度、记录和状态 | 使用纯文本渲染;不执行聊天 HTML、网页片段或 raw 内容 |
provider 只负责获取和规范化数据,Store 是持久化入口。Graph 生命周期为 `status / beginLogin / completeLogin / logout / sync / start / stop`;扩展通过 ingestion 接口接入同一记录模型。
## 统一记录与身份
记录包含 `source`、`accountId`、`kind`、`externalId` 和可选 `parentId/title/text/occurredAt/updatedAt/webUrl/deleted/removedFromView/raw`。唯一键为:
```text
(source, accountId, kind, externalId)
```
`kind` 支持 `chat`、`message`、`event`、`activity`。浏览器账号由用户显式填写标签,本地服务加 `browser:` 前缀;标签不等同于经过微软验证的账号 ID。Graph 使用已授权账号身份,两个来源保持独立,避免相似正文被误合并。Graph 消息的 `externalId` 为编码后的聊天 ID 与消息 ID 的组合,原始消息 ID 保存在 `raw.id`;不能直接把仅在聊天内唯一的 ID 用作整个账号的消息键。演示数据使用独立 `demo` 来源。
`raw` 保存经过限制的来源字段与 provenance,便于后续解析升级;不保存完整页面、表单输入或认证信息。网页原始 ID 缺失时,派生标识只能支持尽力去重。观察不到某条数据不能推断它已删除。
## SQLite 与版本
| 表 | 用途 |
| --- | --- |
| `records` | 每个来源实体的当前版本、首次/最近观察时间、内容 hash |
| `versions` | 实体首次写入及内容变化时的规范化快照 |
| `state` | provider 同步游标、水位和其他非秘密状态 |
| `logs` | 有界运行日志,避免写入聊天正文或令牌 |
| `change_log` | 与版本同时提交的新增/更新快照;供 MCP 按游标读取 |
| `message_live_observations` | 每条消息首次被实时采集确认的快照;解决历史请求先发现新消息的竞争 |
| `webhook_subscriptions` | 提醒条件、目标、签名密钥、消费游标和配置版本 |
| `webhook_deliveries` | 持久投递队列、重试时间、租约与脱敏结果 |
Store 使用 WAL、事务和参数化 SQL。规范化 JSON hash 忽略 `observedAt/capturedAt/collectedAt/fetchedAt` 等采集时间,避免每次观察都生成内容版本;内容无变化时仅更新 `lastSeenAt`。历史版本记录“本工具观察到的变化”,不是 Teams 服务端完整修订历史。
`deleted` 与 `removedFromView` 有不同含义。消息的明确删除标记可保留已归档正文并记录删除;日历 delta 的 `@removed` 只标记 `removedFromView=true`,不标记 `deleted=true`。已知日程保留标题与正文,显示“从同步视图移除”;未知日程的移除 tombstone 忽略,不制造空白删除记录。派生变更日志使用相同的谨慎语义,之后重新观察到正常事件可恢复其视图状态。见 [调研中的日历 delta 说明](RESEARCH.md#增量同步与推送边界)。
当前 schema 标记为 `PRAGMA user_version=3`;0.4.0 增加上述变更与提醒表,保留原记录和历史版本,并通过事务内的迁移标记处理提醒游标。不会把升级前的所有版本重新制造成新变化。首次同步和后续变化都会计入历史,因此数据目录需要用户自行管理容量与备份。
## MCP 与提醒扩展
`ai-service.js` 负责参数化、分页和有界查询,输出显式字段白名单;`mcp-server.js` 将同一查询服务映射为 stdio / Streamable HTTP 工具、资源和提示模板。MCP 不暴露任意 SQL 或采集会话文件。HTTP 使用独立的本地 Bearer 密钥,沿用 Host/Origin 与请求体校验。
消息来源携带 sender、mention 和明确聊天类型证据,`message-signals.js` 据此识别本人、@我和私聊。缺失证据返回未知。`webhook-service.js` 按订阅过滤首次实时确认,生成持久队列;后台发送器使用签名、退避和租约,接收端通过稳定事件 ID 去重。stdio 进程仅管理订阅,后台主服务负责投递,避免重复启动发送器。
增加数据源时显式选择 `live`、`history`、`import` 或 `unknown` 入库模式;新增 MCP 功能复用查询层的白名单投影和输出限制。新增提醒类型应单独定义事件与筛选语义,不能把历史数据当作新消息回放。配置和协议见 [MCP](MCP.md) 与 [WebHook](WEBHOOKS.md)。
活动记录分两类:浏览器条目是实验性页面观察;仅 Graph 的消息/事件变更生成 `raw.derived=true` 的本地日志。两者均不能承诺与微软完整 Activity Feed 相同。
## 登录、权限与本地接口
浏览器路线的登录在微软页面完成;扩展默认关闭采集,用户配置标签和配对后启用。活动采集开关也默认关闭。DOM 登录状态是提示信息,不是令牌校验结果。
Graph 路线使用 public-client 授权码 + PKCE,回调验证 `state` 和有效期;令牌默认只在内存保存,重启后重新登录。Graph 同意只申请读取当前用户资料、聊天与日历所需权限。没有应用注册时不启动 Graph 登录。
本地服务默认监听 `127.0.0.1:4318`,数据文件为 `data/teams.sqlite`、配对配置为 `data/pairing.json`。配置可调整数据目录、端口、轮询间隔和日历窗口;默认 Graph 日历范围为过去 30 天至未来 90 天。
- 扩展 `POST /api/extension/events` 使用独立 bearer 配对令牌,最多 200 条记录、1 MiB;空记录请求也可作为心跳。`POST /api/extension/ping` 用于测试配对。
- 服务强制浏览器来源,验证账号标签、字段类型和页面来源。扩展 endpoint 仅允许回环 HTTP 地址及端口配置。
- 面板状态与查询受精确 Host/端口和来源规则约束;改变本地状态的请求另需 `X-Local-Token`。配对令牌只授权扩展提交和 ping,不授权读取记录。
- 轮换配对令牌后需要更新扩展配置。Graph token、浏览器会话和本地配对令牌用途不同,不互相替代。
此设计保护本地服务免于任意网页直接操作,不提供多用户服务隔离。SQLite 与配对配置默认存为本地文件,数据库内容没有应用层加密;本机用户和文件系统权限仍是数据保护边界。本地面板应始终把来源内容当作不可信文本。
## 同步、故障与可扩展性
浏览器只提交当前页面观察,覆盖范围随打开的视图和已加载内容变化。0.2.0 的 `chat-crawler.js` 在后台拥有的专用标签内按限额遍历聊天;拥有关系存于扩展 session storage,普通标签保持被动采集。专用标签停止后不会退回未经验证的被动扫描。内容运行时只将已确认消息区的 DOM 引用与稳定会话上下文交给解析器,避免侧栏或正在切换的旧正文混入其他会话;DOM 引用不进入网络或存储。下一次切换前必须成功排空队列。详见 [自动遍历契约](AUTOMATION-CONTRACT.md)。
服务使用心跳报告最后观察状态,心跳存在不表示历史完整。自动进度在扩展设置/弹窗显示,自动采集继续使用既有事件接口,兼容运行中的 0.1.1 服务。消息编辑、相对时间和无稳定 ID 的 DOM 仍需要真实页面验证。
Graph 默认约 30 秒轮询。分页和水位必须与持久化成功协调:未完整同步的 chat 不前移水位;失败重试依赖幂等 upsert。日历 delta 保存完整链接,重建窗口时不能把窗口外旧记录自动视为删除;返回的 `@removed` 也仅采用视图移除语义。429/暂时失败使用服务端建议等待和退避;认证失败应提示重新登录而不是无限密集请求。
未来扩展优先沿现有边界增加能力:
1. 在 DOM 解析器添加特定 Teams 页面版本的选择器和 fixtures,输出覆盖度与解析版本。
2. 新增来源 adapter,继续使用统一记录键;若要跨来源关联,另建显式关联表,不重写原始身份。
3. 接入 Graph webhook 时单独增加公网通知适配层、验证、续期与补偿同步,Store 不需了解网络推送协议。
4. 引入增量 schema migration、加密存储、保留策略和备份导入;版本快照仍保留来源与采集语义。
5. 桌面端只有在找到可维护的受支持入口后再新增 provider,不复用或提取 Teams 内部登录令牌。
## 验证边界
`npm test` 的离线验证目标包括 Store 幂等与历史、账号/来源隔离、跨聊天同消息 ID 隔离、日历视图移除与真实删除区分、DOM 解析、入口拒绝、Graph 分页/游标/失败恢复和 OAuth 回调校验。`npm run check` 用于静态与语法检查;具体通过结果以实际运行输出为准。模拟数据或 fixture 只验证代码路径。
用户已确认打开聊天详情后能记录数据。自动聊天遍历、日历兼容性、Graph 同意、完整性与修订仍未在真实账号下验收,不能据离线测试声称完整实时采集已验证。自动模式现场验收应确认:聊天列表预览 → 专用标签巡检进度 → 多个聊天入库 → 最新消息与历史范围 → 暂停/恢复 → 重复采集与账号隔离。活动页可以后续单独验收。