[docs] 澄清 OpenCode 持久化认证状态与环境变量并存时的部署排障边界

[liujuanjuan1984]

背景

在以发布包方式部署 opencode-a2a 时，运维侧给 opencode serve 显式注入了 Google provider 相关环境变量，但运行中的实例仍然命中了部署用户目录下的 OpenCode 持久化认证状态，最终表现为环境变量中的凭证没有达到预期覆盖效果。由于该现象发生在真实部署场景中，容易让操作者误判为 opencode-a2a 本身或发布包安装方式存在问题。

复现步骤

1. 使用发布包安装并以某个独立系统用户启动 OpenCode / opencode-a2a 实例。
2. 在启动脚本里给 opencode serve 注入 provider 相关环境变量，并指定模型。
3. 该部署用户的 HOME/XDG 配置目录下已经存在 OpenCode 持久化认证文件（例如 auth.json）。
4. 运行请求后，实例仍然命中该用户目录下的持久化认证状态，而不是操作者预期中的“仅依赖启动脚本环境变量”。
5. 最终出现上游 provider 认证失败，且问题会与“当前用户下源码启动实例可正常工作”形成对比。

期望行为

1. 仓库文档应明确说明：provider auth 与默认模型属于 OpenCode 侧运行时状态。
2. 文档应提醒操作者：部署用户的 HOME/XDG 目录及其中的 OpenCode 持久化认证文件会影响实际认证结果。
3. 文档应明确指出：仅在启动脚本中注入环境变量，并不应被想当然地视为一定覆盖既有持久化认证状态。
4. 文档应给出最小排查方向，例如检查部署用户的 auth.json / opencode.json / HOME / XDG 环境。

实际行为

当前 README / guide 只说明“provider auth 在 OpenCode side 配置”，但没有明确提示部署用户的持久化认证状态及其与环境变量并存时可能造成的偏差，导致实际排障成本偏高。

验收标准

• README 或 guide 中新增对 OpenCode 持久化认证状态的明确提醒。
• 文档中补充部署用户 HOME/XDG 目录、auth.json、opencode.json 等排查方向。
• 文档避免暴露任何真实凭证、密钥或敏感路径细节。
• 对于该现象与 opencode-a2a 责任边界的关系表述清晰，避免误导为 A2A 适配层 bug。

HEAD 快照

• git rev-parse HEAD: 6d73c71d08848b6e3d334e7b6e32ea69cc113e0e

[liujuanjuan1984]

当前进展同步：

• 已从最新 main 切出专属分支：docs/opencode-auth-precedence-283
• 已提交并推送文档修正：0ad9e3d docs: clarify OpenCode auth state precedence in deployments (#283)
• 已在 README 与 guide 中补充说明：
  • 部署用户的 HOME/XDG 目录及其中的 OpenCode 持久化认证/配置文件属于实际运行时输入
  • 仅在启动脚本中注入 provider 环境变量，不应被想当然地视为一定覆盖既有持久化认证状态
  • 排障时应优先检查部署用户侧的 auth.json、opencode.json、HOME/XDG 与有效工作目录
• 本次落地范围是英文文档澄清与部署排障边界说明，不涉及 opencode-a2a 适配层运行逻辑变更