用 Terraform Plugin Framework…

在实现或审查 Terraform provider 的 Configure 方法与 provider schema、添加认证方式或调试凭证解析失败时，构建可预测的凭证提供者链与用户友好的诊断信息。

适用场景

解决思路

1. 所有认证属性必须设为 Optional，绝不用 Required，否则用户被迫把凭证写进配置，环境变量和凭证文件解析将无法生效。
2. 把密钥类属性标记为 Sensitive，让 Terraform 在 plan 输出中自动脱敏。
3. 在每个属性的 MarkdownDescription 中写明对应的环境变量回退名，使 tfplugindocs 能发布解析规则。
4. 绝不给凭证属性加 Default，也绝不在 provider 中硬编码凭证；默认值应放在解析逻辑里，以便环境变量和文件能覆盖。
5. 按有序来源列表解析凭证，取第一个能提供完整凭证集合的来源，优先级从高到低：静态配置（provider 块中显式设置）> 环境变量 > 共享凭证文件（如 ~/.examplecloud/credentials 中的命名 profile）> 平台身份（实例元数据、工作负载身份或 OIDC token 交换）。
6. 密钥必须作为整体集合解析，不能逐字段解析：若环境变量只提供了 API key 而没有 secret，则该来源视为无贡献，两个值都继续向下一个来源查找，避免混用不同来源导致难以调试的认证失败。
7. 非密钥的连接设置（endpoint、profile、insecure 等）可以逐字段解析，各自独立遵循 config > env > file > default，因为不匹配是可见且无害的。
8. 定义单方法 Provider 接口（Retrieve(ctx) (Credentials, error) 与 Name() string）和哨兵错误 ErrNoCredentials，用于区分“该来源无内容可提供”（继续向下）与“该来源配置有误”（向上暴露）。
9. 实现 Chain 类型（自身也实现 Provider 以便组合），按顺序遍历各 provider，返回第一个完整的凭证集合。
10. 把每个被跳过的来源记录进聚合的 ChainError，其 Error() 列出每个来源及跳过原因，其 Is 方法仅在所有来源都干净地落空时让 errors.Is(err, ErrNoCredentials) 为 true，从而用一次检查区分“什么都没提供”与“提供了但坏了”。
11. 在 Configure 中先调用 req.Config.Get 读取配置，若有诊断错误则直接返回。
12. 对每个认证属性做未知值守卫：若 IsUnknown() 为真，添加属性错误，说明该值依赖 apply 后才可知，并给出环境变量替代方案，然后返回。
13. 在 Configure 中通过 NewDefaultChain 构造凭证链并调用 Retrieve 解析凭证。
14. 若解析失败且 errors.Is(err, ErrNoCredentials)，报错信息中按顺序列出所有尝试过的来源，并给出设置 provider 块、导出环境变量、添加凭证文件 profile 的具体做法及文档 URL；否则报“Failed to Resolve Credentials”并展示原始错误。
15. 用 tflog.Debug 记录胜出的凭证来源名称，但绝不记录密钥值。
16. 在 Configure 中一次性构建客户端，并通过 resp.DataSourceData 和 resp.ResourceData 共享给所有 resource 和 data source。
17. 凭证失败诊断必须列出：按顺序尝试的每个来源及跳过原因、确切的环境变量名、查询过的凭证文件路径与 profile、以及认证指南文档 URL。
18. 对可疑但不致命的情况使用 warning 而非 error，并说明什么优先：例如同时设置了 profile 和环境变量凭证（谁生效），或凭证文件权限为 group/world 可读（建议 chmod 0600）。
19. 给 Credentials 类型实现 String() 和 GoString() 方法以脱敏密钥字段，防止 %v、%+v 或错误包装泄露密钥。
20. 绝不在诊断、日志行或包装错误中包含凭证值，只记录来源名称和非密钥标识符。
21. 当凭证文件权限被其他用户可读时（info.Mode().Perm()&0o077 != 0）发出警告；在 Windows 上跳过此检查，因为 POSIX 权限位无意义。
22. 在 Configure 中立即（eager）解析凭证链，绝不延迟到首次使用 resource 时，使凭证问题在 plan 阶段一次性失败并给出好信息。
23. 若 API 有廉价的身份端点（如 AWS sts:GetCallerIdentity 或 /whoami），在解析凭证后调用它，使无效（而非仅缺失）凭证也在 configure 时失败；用 skip_credentials_validation 属性为隔离或打桩环境提供开关。
24. 凭证链是纯逻辑，用单元测试（Test 前缀，不加 TF_ACC）而非验收测试；让环境可注入（getenv func(string) string 字段默认 os.Getenv，或用 t.Setenv），并把文件 provider 指向 t.TempDir() 的 fixture。
25. 单元测试需覆盖：每个来源在设置时返回凭证、不完整时返回 ErrNoCredentials（有 key 无 secret 即不完整）；优先级（static 胜过 env，env 胜过 file，上层无完整集合时落到 file）；失败聚合（所有来源为空时 errors.Is(err, ErrNoCredentials) 为 true 且消息列出每个来源）；硬错误（格式错误的凭证文件或显式请求但不存在的 profile 应报描述性错误而非静默落空，仅默认 profile 才落空）；脱敏（%v 和 %+v 输出绝不含密钥）。
26. 按检查清单核对：所有认证属性 Optional、密钥 Sensitive；描述写明环境变量回退；Configure 中每个认证属性有未知值守卫；链优先级正确；密钥整体解析、非密钥逐字段解析；哨兵错误区分落空与硬失败；缺失凭证诊断列出所有来源与文档 URL；Credentials 脱敏；凭证文件权限警告（非 Windows）；Configure 中立即解析并可选身份检查；单元测试覆盖各来源、优先级、聚合、脱敏；任何凭证值都不被记录或嵌入错误。
27. 可配合 new-terraform-provider 技能搭建 provider 骨架，并用 provider-resources 技能在 resource 和 data source 中消费已配置的客户端。

适用边界 · 注意事项

• 不适用于非 Terraform Plugin Framework 的 provider 实现（如旧版 SDKv2），其 schema 与 Configure 接口不同。
• 不适用于不需要认证的公开 API provider，或凭证完全由外部代理/网关处理的场景。
• 不适用于无法提供环境变量、凭证文件或平台身份等回退来源的封闭环境，此时链式解析无意义。