# 可信状态文案规范

本规范用于 MCP连接器的页面、教程、验收记录和问题反馈。目标不是把状态写得更乐观，而是让用户分清“服务商声明”“插件观察”“Host 观察”和“真实调用证据”。没有证据时显示“未知/待验收”，不能用连接保存、工具缓存、下载量或演示截图代替。

## 一条状态必须回答什么

按以下顺序展示；字段不可得时保留“未知”，不要隐藏整项：

| 维度 | 可采用的文案 | 证据要求 |
|---|---|---|
| 账号/组织 | `账号：已确认（脱敏）`、`组织：已确认（脱敏）`、`账号/组织：当前连接无法确认` | 仅使用服务商或 Host 明确返回且允许展示的脱敏身份；不得从 Token、邮箱片段或连接名猜测 |
| 授权 | `已授权`、`需重新授权`、`自动重试中`、`授权状态未知` | OAuth/凭据校验的当前观察；授权回调成功不等于工具已注册 |
| 发现/注册 | `发现成功`、`发现失败（仍显示最后成功缓存）`、`尚未发现`、`Host 注册状态未知` | 最近一次 `tools/list`/Host 注册观察及时间；缓存只能证明过去成功发现 |
| 调用 | `只读调用已验收`、`调用失败`、`调用：无证据/待验收` | 正常 DSH 会话经 Host 审批的具体调用证据；MCP连接器当前不应自行推断或新增隐性调用遥测 |
| 权限/管理员前提 | `需要当前账号具备…权限`、`可能需要组织管理员批准`、`管理员前提：待服务商确认` | 服务商公开说明或真实租户返回；不能把个人账号成功外推到企业组织 |
| 运行位置 | `远程 MCP Server`、`本机 stdio 进程`、`本机进程 + 远程处理` | 来自连接配置；“本机进程”不自动等于“数据不离开本机” |
| 数据去向 | `参数发送到 <服务商/域名>`、`本机文件由本机 Agent 读取后上传到 <服务商>`、`数据去向：待服务商确认` | 配置与服务商资料；不得只写“本地”而省略随后上传或远程处理 |
| 费用 | `可能计费，以服务商套餐/配额为准`、`本次费用：无法由插件确认`、`公开资料明确免费（附来源和日期）` | 只有服务商明确、带日期的依据才能写免费；免密不等于免费 |
| 时间/证据 | `检查时间：YYYY-MM-DD HH:mm:ss ±HH:mm`、`证据：插件观察 / Host 观察 / 人工只读验收` | 时间需含时区；历史成功时间与当前检查时间分别显示 |

## 分层状态模板

```text
连接：<已保存 / 未保存 / 状态未知>；范围：<项目 / 全局 / 未知>
账号/组织：<脱敏确认值 / 当前连接无法确认>
授权：<已授权 / 需重新授权 / 自动重试中 / 未知>
发现/注册：<成功 / 失败，显示最后成功缓存 / 尚未发现 / Host 状态未知>
调用：<只读调用已验收 / 调用失败 / 无证据，待验收>
权限/管理员前提：<已知要求 / 待服务商确认>
运行与数据去向：<远程 / 本机 stdio / 本机读取后上传到远程>
费用：<已知依据 / 无法由插件确认>
检查时间：<带时区时间>；证据：<插件 / Host / 人工验收>
```

“整体可用”只有在配置、发现/注册、调用三层都有当前证据时才能使用，并且必须限定到本次账号、组织、工具和验证时间。部分 Server 成功时写“部分异常”，不能把连接器整体写成“已连接且可用”。

## 状态变化时的固定表达

- 配置已保存但尚未发现：`连接已保存；尚无工具发现/Host 注册证据，暂不能判断可调用。`
- 最近发现失败但存在缓存：`最近发现失败；正在显示 <时间> 的最后成功缓存。缓存不代表服务当前可调用。`
- OAuth 临时刷新失败：`授权刷新暂时失败，正在按退避重试；尚无永久失效证据，不需要立即重复授权。`
- 明确永久授权失败：`服务商已拒绝或 Grant 已失效，需要重新授权；原有工具缓存不能作为当前授权证据。`
- 未完成真实调用：`配置和工具发现已通过；真实只读调用无证据/待验收。`
- 缺少账号、组织或费用信息：`当前连接无法确认账号/组织/本次费用，请在服务商侧核对。`

## Schema 变化警示

Schema 比较必须写明比较对象，不能只显示“已更新”。Draft PR #105 的候选最小实现只比较**同一连接签名下前后两份安全裁剪的发现缓存**；在该 PR 完成实际 Host UI 验收、合并并随正式版本发布前，本节只作为设计与验收口径，不得宣传为已上线能力。即使实现上线，它也不证明当前 Host 执行 Schema 一致，更不会自动触发或通过审批。只有目录声明时写“目录声明”，不得冒充运行时结果。

Draft PR #105 候选页面文案如下；未合并发布时不得写成“当前页面已显示”：

- `缓存参数结构已变化，可能影响既有调用；使用前请核对参数，并按 Host 要求重新确认。`
- `Schema 不完整或缺少历史记录，无法判断兼容性。`
- `仅为发现缓存；调用：无证据/待验收。`

当前发现检查时间与最后成功缓存时间应在邻近字段分别展示，不塞入上述固定句。以下更细分类是后续设计口径；没有已发布实现与实际 Host UI 验收证据时，不得宣称已经完成 Schema 变化提示、完整破坏性判定或审批绑定。

| 状态 | 推荐文案 | 后续动作 |
|---|---|---|
| 无历史基线 | `Schema：首次观察，暂无可比较基线。` | 查看当前必填项、类型和约束后再审批调用 |
| 未检测到变化 | `Schema：与 <时间> 的最后成功缓存相比未检测到变化。` | 仍按当前 Host 审批执行；不等于服务业务语义永不变化 |
| 仅新增可选项 | `Schema：检测到新增可选参数/工具；现有必填参数未检测到破坏性变化。` | 展示差异；新工具或新参数不自动扩大 allow 规则或授权 |
| 可能破坏兼容 | `Schema 变化：检测到工具移除、必填参数新增、类型/枚举收窄或其他不兼容差异；调用前请重新查看参数并确认审批。` | 暂停自动复用旧参数；由 Host/用户重新确认，不自动重试写入或付费调用 |
| 当前 Schema 不可得 | `当前 Schema 无法确认；正在显示 <时间> 的最后成功安全缓存，不能据此判断当前可调用。` | 检查连接/重新发现；保留未知，不把缓存标绿 |
| 副作用不明确 | `工具副作用：服务未提供或 Host 未传递可靠标记；不能据此认定只读。` | 结合工具说明和服务商文档人工确认；不从名称猜测 |

判定“可能破坏兼容”至少包括：工具被移除/重命名、原可选字段变必填、输入类型改变、枚举值删除、允许范围收窄，或明确的副作用/权限要求变化。MCP annotations 缺失不能证明工具只读；描述文本变化只能提示人工复核，不能单独判定安全性。比较失败时写“无法确认”，不得写“无变化”。

## 交给 P0 的实现边界

1. 优先复用现有诊断的 `stage`、稳定 `code`、`checkedAt`、最近成功时间和 Host 状态；不为文案新增隐性用户跟踪。
2. 将“当前检查”与“最后成功缓存”分开，不用同一个绿色状态覆盖两者。
3. 账号/组织、费用和管理员要求没有可靠接口时保持未知；不要解析 Token 或自动调用付费/有副作用工具来补齐。
4. 调用证据应来自 Host 已有执行/审批契约或用户明确提供的脱敏验收记录。本轮不在连接器页面增加旁路试运行。
5. Schema 差异只对实际可观察的同一连接签名/Server/工具缓存生效；大范围调用前刷新、完整破坏性判定、Schema 变化审批绑定和受控写操作属于后续设计，文案不能暗示它们已经实现。

场景记录格式见[三个首次成功场景包](FIRST-SUCCESS-SCENARIOS.md)。