用途与实际影响
这项功能怎样使用
为什么需要它
只看到程序在运行，并不能说明会话或联系人接口可用。自检也不能因为一个健康端点成功就忽略其他必需接口失败。
举个实际例子
“接口是不是坏了？检查结果别打印聊天文字。”只问服务就查 /health；如果确实要检查业务接口，元数据模式会请求会话、联系人等数据，再仅输出汇总形状。缺配置、必需端点失败和可选端点失败会分别说明。
最后我会得到什么
得到各类接口有没有响应、返回了多少及仍缺什么；默认不打印聊天正文。健康入口通过不能证明目标账号或聊天历史完整。
可直接使用
本次明确要求检查的业务入口都返回预期范围，报告只留汇总信息。
需要确认
必要入口失败就报告失败；其他可选入口的缺口另外列出。
当前不可用
缺本地配置或数据访问条件时停止业务检查；单独健康检查仍只能说明服务有响应。
从哪里开始
明确维护 WeFlow 适配时，运行 probe-weflow.ps1 -Json -Mode MetadataOnly -NoMessages；它仍会请求会话等业务元数据，真实正文检查须另选模式与范围。
需要准备什么
- 只要服务健康、业务元数据还是确需消息正文
- 要诊断的故障
从开始到拿到结果
- 1
先确定要查到哪一层
只需要知道服务有没有响应就查健康；需要业务自检时才读会话等元数据，默认不读聊天正文。
- 2
逐类报告结果
告诉本人哪些必需入口成功、哪些失败，不把原始消息打印到报告。
- 3
按缺口继续
元数据通过仍不能证明账号匹配或历史齐全；真实账号和虚构测试各自说明。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
隔离失败分支通过；真实业务自检未执行关键规则与设计选择
MetadataOnly（纯元数据探测）跳过 messages 和 ChatLab 消息正文请求，但会读取 sessions、contacts、群成员和朋友圈统计的响应后做投影。
五个必需项是 GET /health、GET sessions?limit=3、GET sessions?format=chatlab、GET contacts?limit=3 和 GET sns/export/stats。
JSON 输出只记录 shape、count、sync_present 等观察值；脚本不会把响应与完整 OpenAPI Schema（数据结构） 自动逐项比对。
FullProbe（完整探测）默认模式可能请求真实消息，不能为了本页构建无条件执行。
现有公开检查只覆盖它实际枚举和解析的文件，不是 Git 历史全量检查，也不是自动安装的提交钩子。
本模块用到的名词
- MetadataOnly（纯元数据探测）
- 不调用消息正文端点；需要本地配置及数据接口凭据，会接触其他业务响应但不将其原样输出。
- Shape（返回形状）
- 对象最前面的属性名列表；记录它不等于验证这些字段内容符合全部业务约定。
- CI（自动化集成检查）
- 此项目统一用 test-ci-local.ps1 发现并运行 tests/test_*.py，然后执行已有公开边界检查。
专业定义
无消息正文端点、明确必需项、准确退出码与统一测试入口。
解决什么
元数据模式若被理解成“不需要凭据”或“不访问任何私人数据”，就会误判它的真实读取范围。
当前怎样实现
- probe-weflow.ps1 读取本地 .env，JSON 模式使用 Invoke-JsonRequest 收集状态，Get-RequiredEndpointFailures 汇总五个必需项。
- 每个 HTTP 请求设置 8 秒超时，按需顺序探测；不存在已经证明的毫秒级整体完成承诺。
- Get-Shape 最多记录前 10 个属性名，Get-ResultCount 从 count/total 或已知集合取数量；这些是观察，不是内容真实性验证。
- 本地 CI 改为 python -m unittest discover -s tests -p "test_*.py"，覆盖 26 项契约和 5 项快照测试；GitHub Actions 不再重复运行旧的 26 项子集。
- test-public-boundary.ps1 检查当前已跟踪路径、忽略规则、文本和 PowerShell 语法；PDF 文本依赖 pdftotext，可缺失而被脚本跳过，必须单列。
执行流程
- 1
先判断实际问题只需要健康入口还是需要业务自检；本轮选择无鉴权健康入口和虚构接口替身。
- 2
业务自检从本地配置加载地址与 token，不把值写入结果；配置缺失时返回 missing_env。
- 3
健康成功后请求必需业务项及条件可选项；元数据模式跳过消息正文请求。
- 4
输出每个端点结果、模式、凭据是否存在及 required_endpoint_failures，不输出原始响应正文。
- 5
维护源码时先运行全部测试；任一测试失败则退出，成功才继续已有公开边界检查，任何 SKIP（跳过）另行披露。
边界
- 本轮没有运行连接真实业务数据的 MetadataOnly 或 FullProbe；只运行替身探测测试。
- 形状、数量和无正文输出不能证明账号已匹配、所有群可读或真实聊天完整。
- 脚本执行本地检查，不上传检查结果，也不会自动替调用方安装 Git 提交钩子。
失败与恢复
- missing_env
- JSON 报告列出失败和缺失配置，返回 1；没有实际配置时不尝试猜凭据。
- 必需端点失败
- 失败项进入 required_endpoint_failures，总体返回 1。可选 POST 失败不会被混成必需项。
- 新增快照回归失败
- 统一 CI 会发现该测试并返回失败，不再因只跑旧文件而漏过。
- pdftotext 不存在
- 脚本会跳过 PDF 文本检查，不能仅据退出 0 宣称完整；本次相同提交的 GitHub Actions 已实际完成该检查并通过。
真实入口
probe-weflow.ps1探测范围、输出与退出条件。
tests/test_project_contracts.py配置缺失、健康失败、必需失败和可选失败的接口替身。
tools/test-ci-local.ps1 / .github/workflows/contract.yml统一测试入口。
tools/test-public-boundary.ps1已有公开检查及 PDF 跳过条件。
如何验证
- 当前完整 31 项源码测试通过；其中 4 个探测行为场景由 PowerShell 接口替身执行。
- 将虚构 test_private_snapshot_manifest.py 设为失败后，实际本地 CI 退出 1，未执行后续边界脚本。
- GitHub Actions 34180971929 对同一 master 提交执行 31 项测试及 PDF 文本检查并成功完成。
- 真实 /health 为 200；数据接口与账号并未在本轮访问。
与其他模块的关系
为接口维护提供观察和回归验证，不能代替真实任务读取或运行恢复验收。