Add comprehensive user troubleshooting guide (USER_GUIDE_CN.md)

[Copilot]

Created a detailed user-facing troubleshooting guide in Chinese based on comprehensive codebase analysis, covering all credential types, error scenarios, and resolution strategies.

Document Structure

• Project Overview: Core capabilities, credential types (AccessKey, STS, ECS RAM Role, OIDC, etc.), and typical deployment scenarios
• Prerequisites: OS/Python version requirements (≥3.7), dependencies, network/permission requirements
• Quick Start: Installation via pip, configuration examples (env vars, config files), verification with expected outputs
• FAQ (29 items): Problem-cause-solution format covering:
  • Credential type errors and default chain failures
  • Environment variable and config file issues (missing, empty, malformed)
  • ECS metadata service problems (IMDSv1/v2, disabled service, network)
  • RAM Role ARN and OIDC failures (missing params, STS errors, token file issues)
  • Credentials URI response format and connectivity
  • Async operations, Python compatibility, thread safety
  • Network timeouts, proxy configuration, logging
  • Credential refresh/cache mechanics
  • Kubernetes OIDC setup, Windows paths, offline environments
• Best Practices: Security (no hardcoded keys, minimal permissions), performance (singleton pattern, caching), monitoring

FAQ Example

Each item links error messages to specific code paths:

Q8: ECS 元数据服务无法访问

CredentialException: Failed to get RAM session credentials from ECS metadata service. HttpCode=404

Root cause: Instance not bound to RAM role, or metadata service (100.100.100.200) unreachable
Solutions: Verify role binding, check security group rules, test metadata endpoint accessibility, specify role_name to reduce requests

All issues derived from actual exception handling in ecs_ram_role.py, ram_role_arn.py, oidc.py, uri.py, profile.py, cli_profile.py, and test cases.

File

• USER_GUIDE_CN.md: 1,430 lines of troubleshooting documentation

Original prompt

请全面、深入地阅读当前项目的全部源代码（包括但不限于 README、配置文件、脚本、构建文件、测试用例等，不限于 Python，可能包含 JavaScript、Go、Java、C++、Shell、YAML、JSON 等任意语言或格式），准确理解项目的功能逻辑、架构设计、依赖关系、运行机制及使用方式。

基于对代码的完整分析，请撰写一份面向终端用户的说明文档，核心目标是帮助用户在部署、配置和使用该项目时快速识别、理解并解决常见问题。

文档需包含以下部分，并以 Markdown 格式输出：

1. 项目简介
   简要说明项目用途、核心能力及典型应用场景。

2. 使用前提与环境要求
   明确列出运行该项目所必需的：

   • 操作系统要求（如 Linux/macOS/Windows 版本）
   • 运行时环境（如 Node.js、Python、JDK、.NET、Docker 等）及其最低版本
   • 系统依赖（如特定库、命令行工具、内核特性等）
   • 网络或权限要求（如需要外网访问、root 权限、API 密钥等）

3. 快速开始指南
   提供清晰、可复现的步骤，包括：

   • 安装/构建方法（如 npm install、make、go build、docker-compose up 等）
   • 配置说明（如环境变量、配置文件模板）
   • 启动与验证命令（附带预期输出示例）

4. 常见问题解答（FAQ） —— 重点部分
   请基于代码中所有可能引发失败或异常的逻辑路径，主动推断用户在真实使用中可能遇到的问题，并以问答形式详尽列出。每个问题应包含：

   • 问题现象：用户可能看到的错误信息、程序行为异常或日志内容（可引用具体报错）
   • 根本原因：结合代码逻辑说明为何会出现此问题（如：未处理空输入、配置字段缺失、文件路径硬编码、权限检查失败、超时阈值过小、特定平台不兼容等）
   • 解决方案或规避建议：提供具体、可操作的修复步骤或最佳实践

   特别注意：

   • 重点关注所有异常处理分支（如 try/catch、panic/recover、if err != nil、assert、错误码返回、日志警告等）
   • 分析边界条件、非法输入、缺失依赖、环境差异等易错场景
   • 即使官方文档或 README 未提及，只要代码中存在潜在使用陷阱，就必须纳入 FAQ
   • 测试test case通常也是为了验证代码及异常分支，也需要重点分析

文档语言应简洁明了、面向用户，避免堆砌技术细节，重点突出“问题—原因—解决”链条，确保非开发者也能理解并操作。

最终输出必须为结构清晰、排版规范的 Markdown 文档。

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[CodeSpaceiiii]

test