用途与实际影响
这项功能怎样使用
为什么需要它
查一个群的成员、看指定窗口的消息、看朋友圈时间线是不同问题。仅说“微信 API”会掩盖输入和结果差异，也容易误把导出或删除当成查询。
举个实际例子
“这个群有哪些成员？顺便确认我需要的讨论能从哪里读取。”群成员接口提供成员及可用角色信息，聊天历史走独立消息接口；如果要看朋友圈，另选时间线或统计，不把它们拼成一套未经验证的完整社交档案。
最后我会得到什么
得到当前版本的接口说明，供已接通的调用方选择正确请求。文档本身不会代发请求，也不替服务端拦截越界操作。
可直接使用
调用方按目标选择对应接口，实际返回目标资料及明确范围。
需要确认
版本或返回结果与文档不一致时先查来源服务，不拿旧文档保证新版本。
当前不可用
普通 AI 读取不包含删除和原始实时流；文档上的标记不会自动限制服务端。
从哪里开始
在已接通本机 WeFlow 的 AI 环境中按问题选择会话、联系人、群成员、消息或朋友圈只读接口；普通查询不顺带导出、删除或发送。
需要准备什么
- 想查会话、联系人、群成员、消息还是朋友圈
- 目标与时间范围
从开始到拿到结果
- 1
AI 定位对应接口
先用会话索引找到目标，再依问题读取联系人、群成员、消息或朋友圈；接口失败就说清是哪一类。
- 2
按范围取页
最新与历史走对应端点，返回不全就继续分页而非声称全量。
- 3
交回边界
解释哪些是本地可读、哪些仍未知；推送未启用或接口变化时停在实际结果。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
26.7.3 接口文档与标记已验证关键规则与设计选择
/health 无需鉴权，数据接口需要本地有效 token；健康通过不等于数据访问通过。
只读查询有些支持 GET 和 POST 两种参数形式；POST 本身不等于更改微信数据。
x-weflowbridge-ai-preferred 是推荐标记，x-weflowbridge-ai-allowed:false 是消费约定；调用方负责执行约定，本仓库没有网络拦截器。
SSE（服务器推送事件）是实时原始流，不是默认 AI 元数据封套；上游需打开主动推送开关。
本模块用到的名词
- OpenAPI 3.1
- 描述服务地址、端点、参数、鉴权和响应结构的机器文档；不自动实现服务功能。
- Bearer token（请求凭据）
- 数据请求推荐使用 Authorization（用户授权）: Bearer <token>；具体值只由本地配置或凭据入口提供。
- SSE（服务器推送事件）
- WeFlow 的 message.new / message.revoke 实时流；浏览器 EventSource 通过查询参数携带凭据，不能将带值 URL 写进公开日志。
专业定义
接口用途、鉴权、读取参数、写操作和推流边界一并说明。
解决什么
同一服务既有只读查询也有产生副作用的操作，不能只根据 GET/POST 或一个成功状态就判断任务含义。
当前怎样实现
- docs/openapi.yaml 以默认 http://127.0.0.1:5031 为服务地址，声明 bearerAuth 与数据模型。
- 会话、联系人、messages、group-members 包含 GET/POST 形式；ChatLab 历史消息单独定义 since/end/limit/offset。
- 四类写操作标记为 x-weflowbridge-ai-allowed:false：sns/export、sns/post/{id} 删除、block-delete/install、block-delete/uninstall；push 也标为非默认 AI 入口。
执行流程
- 1
查会话用 /api/v1/sessions，可按 keyword 和 limit 定位；format=chatlab 返回 AI 友好的会话索引。
- 2
查联系人用 /api/v1/contacts；查群成员用 /api/v1/group-members?talker=<group>，可包含 isOwner、messageCount 等字段，不能把字段存在视为已完成角色分析。
- 3
查最新消息用 /api/v1/messages；查历史或增量用 /api/v1/sessions/{id}/messages，读取策略见 AI 消费契约。
- 4
朋友圈查询分 /api/v1/sns/timeline 与 /api/v1/sns/export/stats，前者给时间线，后者给统计；它们不证明远端所有历史都在本机可读。
- 5
明确需要实时流时查看 /api/v1/push/messages；上游未启用会返回 403。导出、删除和防删钩子是有副作用的不同操作，不在普通查询中附带执行。
边界
- 本仓库维护已登记的版本化接口面，不保证上游未来新增端点或全部内部接口都已覆盖。
- 默认本机回环；项目没有公网代理、穿透服务或发送消息实现。
- 文档不替代实际授权与客户端执行，不能声称标记已经禁止网络访问。
失败与恢复
- 返回 401
- 核对本地鉴权配置，保留失败状态，不因为 /health 成功就宣布数据接口可用。
- 推流返回 403
- 上游可能没有开启主动推送；普通消息查询不需要为此自动改设置。
- 响应或端点与旧基线不同
- 重新探测所需接口并更新所属契约；不能把未观察的新行为写成兼容保证。
真实入口
docs/openapi.yaml版本化接口、参数与标记。
AGENTS.md / README.md上游实测注意事项和入口用途。
project_manifest.json版本基线与职责声明。
如何验证
- 自动化测试覆盖必需端点、写操作标记和推流非默认语义。
- 本轮只请求两个 /health；没有验证上述真实业务响应。
与其他模块的关系
为 AI 取数契约和 probe 脚本提供接口定义，实际数据访问和服务端行为归 WeFlow。