用途与实际影响
这项功能怎样使用
为什么需要它
同一句总结，在读错账号或漏掉一条后续回复时就可能完全相反。契约要求先核对来源和完整程度，让读取失败不会被误写成事实。
举个实际例子
“看一下这个群昨天最后怎么定的，别漏掉后面的回复。”调用方查明账号与会话后逐页读取，追踪谁在回答谁；若最新时间对不上、账号不符或重试仍为空，结果中直接说明。
最后我会得到什么
AI 获得带来源、时间范围和上下文关系的材料；公开保存时另生成不含正文的元数据结果。总结本身由消费方完成，这个仓库没有内置分析模型。
可直接使用
当前账号和目标会话吻合，选定时段的消息已按实际页数读取，并保留数量、来源和回复线索。
需要确认
最新消息时间对不上或一次读取为空时先查范围与缺页，不编完整总结。
当前不可用
无法确认账号或目标不在当前库时，只说明这份来源读不到，不替本人切换账号。
从哪里开始
只有明确选择 WeFlow 适配时，在已接通 WeFlow 的 AI 环境中说出目标会话和时间范围；日常默认微信读取仍走 WeChatDirect。
需要准备什么
- 要查的联系人或会话
- 问题与时间范围
- 是否明确使用 WeFlow
从开始到拿到结果
- 1
确认库和会话
先核对账号、目标及可读范围，证据不足就保留未知。
- 2
按问题读取
最新消息查当前列表；历史分段续页并保留时间、引用与媒体线索。
- 3
说明结论和覆盖
AI 分析后给出来源、范围、数量和缺页状态；公开只留契约元数据，私人正文仍在获准环境。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
契约与虚构示例已验证关键规则与设计选择
最新查询用无日期 limit=100，与 sessions.lastTimestamp 比较，避免日期参数造成错误遗漏。
历史查询使用 since/end/offset；保存 hasMore、nextSince、nextOffset 与 watermark，不能只记一个水印就宣称分页完整。
回复、引用和有关媒体可能改变含义，不能只取纯文本摘要。
公开元数据格式和私人运行中的正文是不同产物，不把格式文件说成自动脱敏器。
本模块用到的名词
- ChatLab Pull（按页拉取）
- GET /api/v1/sessions/{id}/messages 返回 chatlab、meta、members、messages、sync；适合指定窗口的历史或增量读取。
- Watermark（游标水印）
- 保存 sync.watermark 作为同步观察；续页位置使用接口规定的 nextSince 与 nextOffset，不把 watermark 虚构为请求参数。
- media_manifest（媒体清单）
- 公开元数据包含 kind、count，可带 timestamp、size、sender_role；原图、语音、视频和本机路径不放入这个公开格式。
- AI Consumer Envelope（AI 消费结果封套）
- 把本次取数范围、来源判断和完整性信息放在结构化结果中，方便消费方核验。
专业定义
最新消息自检、历史续页、回复引用和媒体清单各自保留。
解决什么
一次成功响应只证明取得了这一批数据，不能证明账号正确、历史完整或媒体齐全。
当前怎样实现
- docs/ai_consumer_contract.md 定义账号判断、消息策略、UTC 时间、失败和交接语义。
- JSON Schema（数据结构） Draft 2020-12 定义 18 个属性、17 个必需属性，禁止未知顶层属性；talker 采用公开占位格式，message_content_included 固定 false。
- time_window 可为 latest 或 since/end/offset 对象；endpoint_family 覆盖 messages、chatlab_pull、sessions、contacts、group_members、sns、health。
- 可选 reply_metadata 记录 platformMessageId、replyToMessageId、quote_present 与 quote_message_id；引用正文不写入公开示例。
执行流程
- 1
通过 sessions、必要的 contacts 与目标会话查询判断当前库；证据不足保留 unknown（未知）。
- 2
最新消息走 GET /api/v1/messages?talker=<id>&limit=100，不带 start/end；按 createTime 降序理解，索引 0 为最新并核对会话最后时间。
- 3
历史先 GET /api/v1/sessions?format=chatlab，再按 since/end/limit/offset 请求会话消息，并保留整个 sync 分页信息。
- 4
需要旧格式、关键词或媒体导出参数时才选 legacy（旧式）messages 接口；复杂参数可以 POST JSON，不能把所有 POST 都当成写入。
- 5
保留 platformMessageId、replyToMessageId 和 quote；Unix 时间按 UTC 秒理解，中文时间输出使用 UTC+8，不依据机器当前时区猜。
- 6
消费方完成分析；公开持久结果明确 current_library、library_evidence、target_account、target_conversation、talker、time_window、retry_count、message_count、lastTimestamp_matches_newest、content_scope、request_method、endpoint_family、sync_watermark、media_manifest 等字段，并实际运行 Schema（数据结构） 验证。
边界
- JSON Schema（数据结构） 检查格式，不自动请求接口、重试、排序、还原回复树或生成摘要；这些由调用者遵守契约实现。
- 成功读取和元数据探测都不自动授权全账号归档、后台同步或公开原文。
- 当前默认 wechat-direct 路线使用 WeChatDirect；本模块描述的是显式使用 WeFlow 时的契约。
失败与恢复
- 最新时间对不上
- 记录 lastTimestamp_matches_newest=false，说明这一批可能不完整，再做有界重试或调整参数。
- 目标未找到或仅看到转发 XML
- 只能确认当前库没有定位到目标；转发内容不能证明原群可读取。
- 公开结果不符合 Schema（数据结构）
- 验证器会拒绝不符合字段规则的结果；调用者先纠正产物，不能把验证器未执行说成已经通过。
真实入口
docs/ai_consumer_contract.md完整取数和失败语义。
schemas/ai-consumer-envelope.v2.schema.json公开元数据的机器格式。
docs/examples/ai_consumer_envelope.example.json不含真实数据的格式示例。
如何验证
- 源码 31 项测试中包含契约字段、合法示例和非法格式检查。
- 本轮没有执行真实账号判断、历史读取、回复还原或媒体读取。
与其他模块的关系
使用接口模块中的数据入口，并依靠自检和运行模块确认 WeFlow 是否可服务；分析决定仍由消费方承担。