ai-shell/配置管理说明.md

AI Shell 配置管理说明

🔐 敏感配置管理

1. 使用 .env 文件

项目现在使用 .env 文件来管理敏感配置，确保 API 密钥等信息不会被意外提交到代码库。

配置文件结构：

ai-shell/
├── .env                 # 实际配置文件（已在 .gitignore 中排除）
├── .env.example         # 配置模板文件（会被提交到代码库）
└── ai_shell/config.py   # 配置加载逻辑

2. 配置文件内容

.env 文件（实际配置）：

# AI Shell 配置文件
AI_SHELL_API_KEY=f8370a60-fe0a-455f-9167-411d476123d2
AI_SHELL_BASE_URL=https://ark.cn-beijing.volces.com/api/v3/
AI_SHELL_MODEL=deepseek-v3-250324

# 可选配置
AI_SHELL_TIMEOUT=30
AI_SHELL_MAX_RETRIES=3

.env.example 文件（模板）：

# AI Shell 配置文件模板
AI_SHELL_API_KEY=your_api_key_here
AI_SHELL_BASE_URL=https://your-api-endpoint.com/v3/
AI_SHELL_MODEL=your_model_name

# 可选配置
AI_SHELL_TIMEOUT=30
AI_SHELL_MAX_RETRIES=3

🔧 配置加载优先级

配置系统按以下优先级加载配置：

1. 环境变量（最高优先级）
2. 当前目录的 .env 文件
3. 包目录的 .env 文件
4. ~/.ai-shell/.env 文件
5. 默认值（最低优先级）

📋 配置项说明

配置项	环境变量	说明	默认值
API Key	AI_SHELL_API_KEY	API 密钥（必填）	无
Base URL	AI_SHELL_BASE_URL	API 基础 URL	https://api.openai.com/v1/
Model	AI_SHELL_MODEL	模型名称	gpt-3.5-turbo
Timeout	AI_SHELL_TIMEOUT	请求超时时间（秒）	30
Max Retries	AI_SHELL_MAX_RETRIES	最大重试次数	3

🚀 使用方法

1. 查看当前配置

ai --config

输出示例：

AI Shell Configuration:
  Model: deepseek-v3-250324
  Base URL: https://ark.cn-beijing.volces.com/api/v3/
  API Key: f8370a60...123d2
  Timeout: 30s
  Max Retries: 3

Configuration Status: ✅ Valid

Configuration Sources (in priority order):
  1. Environment variables
  2. .env file in current directory
  3. .env file in package directory
  4. ~/.ai-shell/.env file
  5. Default values

2. 修改配置

方法 1：编辑 .env 文件

# 编辑项目目录中的 .env 文件
vim .env

# 或创建全局配置
mkdir -p ~/.ai-shell
cp .env ~/.ai-shell/.env
vim ~/.ai-shell/.env

方法 2：使用环境变量

# 临时设置
export AI_SHELL_API_KEY="new_api_key"
export AI_SHELL_MODEL="gpt-4"

# 永久设置（添加到 shell 配置文件）
echo 'export AI_SHELL_API_KEY="new_api_key"' >> ~/.zshrc

3. 配置验证

程序启动时会自动验证配置：

ai "test command"

如果配置无效，会显示错误信息：

❌ Configuration error: API key not configured.
Please set AI_SHELL_API_KEY in .env file or environment variable.
Run 'ai --config' to see current configuration.

🔄 升级后的配置管理

升级流程：

1. 修改代码
2. 更新版本: python scripts/bump_version.py patch
3. 重新安装: uv build && uv tool install . --force
4. 配置自动保留：.env 文件不会被覆盖

配置迁移：

如果需要迁移配置到新环境：

# 复制配置文件
cp .env /path/to/new/environment/

# 或设置环境变量
export AI_SHELL_API_KEY="your_key"
export AI_SHELL_BASE_URL="your_url"
export AI_SHELL_MODEL="your_model"

🛡️ 安全最佳实践

1. 保护 .env 文件

• ✅ .env 文件已在 .gitignore 中排除
• ✅ 不要将 .env 文件提交到代码库
• ✅ 使用 .env.example 作为模板

2. API 密钥管理

• 🔐 定期轮换 API 密钥
• 🔐 不要在代码中硬编码密钥
• 🔐 使用环境变量或配置文件

3. 权限控制

# 设置 .env 文件权限（仅所有者可读写）
chmod 600 .env

# 检查权限
ls -la .env

🔍 故障排除

常见问题：

1. API 密钥未配置

   # 检查配置
   ai --config
   
   # 设置密钥
   echo 'AI_SHELL_API_KEY=your_key' >> .env
   

2. 配置文件未找到

   # 创建配置文件
   cp .env.example .env
   vim .env
   

3. 权限问题

   # 检查文件权限
   ls -la .env
   
   # 修复权限
   chmod 600 .env
   

---

💡 总结：现在 AI Shell 使用 .env 文件管理敏感配置，确保了安全性和可维护性。配置会在升级时自动保留，无需重新设置。