journal_organizer/TROUBLESHOOTING.md

# 故障排除指南

本指南提供 Obsidian 智能日记整理 Agent 常见问题的解决方案和调试技巧。

## 快速诊断

运行以下命令进行快速系统检查：

```bash
# 检查依赖项状态
python -m journal_organizer check-deps

# 测试基本功能
python -m journal_organizer --help

# 验证配置文件
python -c "
import json
with open('config.yaml', 'r') as f:
    print('配置文件存在且可读')
"
```

## 常见问题分类

### 🚀 启动问题

#### 问题 1: 模块导入错误
```
ImportError: attempted relative import with no known parent package
```

**解决方案**:
```bash
# ✅ 正确方式：作为模块运行
python -m journal_organizer --help

# ❌ 错误方式：直接运行脚本
python main.py
```

**原因**: 项目使用相对导入，必须作为 Python 包运行。

#### 问题 2: 找不到模块规范
```
ValueError: __main__.__spec__ is None
```

**解决方案**:
确保在项目根目录运行命令，并且 `__init__.py` 文件存在：
```bash
ls -la __init__.py
pwd  # 确认在正确目录
```

### ⚙️ 配置问题

#### 问题 3: 配置文件不存在
```
ConfigurationError: Configuration file not found
```

**解决方案**:
1. 复制示例配置文件：
```bash
cp config.example.yaml config.yaml
```

2. 编辑配置文件，填入正确的值：
```yaml
obsidian:
  vault_path: "/path/to/your/vault"
  rest_api:
    api_key: "your-obsidian-api-key"

claude:
  api_key: "${ANTHROPIC_API_KEY}"
```

#### 问题 4: 环境变量未设置
```
EnvironmentVariableError: Environment variable 'ANTHROPIC_API_KEY' is not set
```

**解决方案**:
1. 设置必需的环境变量：
```bash
# 设置 Claude API 密钥（必需）
export ANTHROPIC_API_KEY="sk-ant-your-api-key-here"

# 设置 Obsidian API 密钥（必需）
export OBSIDIAN_API_KEY="your-obsidian-api-key"

# 设置可选的环境变量
export OBSIDIAN_VAULT_PATH="/path/to/your/vault"
export CLAUDE_API_URL="https://api.anthropic.com"
export CLAUDE_MODEL="claude-3-5-sonnet-20241022"

# 验证设置
echo $ANTHROPIC_API_KEY
echo $OBSIDIAN_API_KEY
```

2. 永久设置环境变量：
```bash
# 添加到 ~/.bashrc 或 ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-ant-your-api-key-here"' >> ~/.bashrc
echo 'export OBSIDIAN_API_KEY="your-obsidian-api-key"' >> ~/.bashrc

# 重新加载配置
source ~/.bashrc
```

3. 使用 .env 文件（可选）：
```bash
# 创建 .env 文件
cat > .env << EOF
ANTHROPIC_API_KEY=sk-ant-your-api-key-here
OBSIDIAN_API_KEY=your-obsidian-api-key
OBSIDIAN_VAULT_PATH=/path/to/your/vault
CLAUDE_API_URL=https://api.anthropic.com
CLAUDE_MODEL=claude-3-5-sonnet-20241022
EOF

# 加载 .env 文件
set -a; source .env; set +a
```

#### 问题 4a: 环境变量格式错误
```
EnvironmentVariableError: Environment variable expansion failed
```

**解决方案**:
检查配置文件中的环境变量语法：
```yaml
# ✅ 正确的环境变量语法
claude:
  api_key: "${ANTHROPIC_API_KEY}"                    # 必需变量
  api_url: "${CLAUDE_API_URL:-https://api.anthropic.com}"  # 带默认值
  model: "${CLAUDE_MODEL:?请设置 CLAUDE_MODEL 环境变量}"    # 带错误消息

# ❌ 错误的语法
claude:
  api_key: "$ANTHROPIC_API_KEY"          # 缺少大括号
  api_url: "${CLAUDE_API_URL-default}"   # 错误的默认值语法
  model: "${CLAUDE_MODEL?error}"         # 错误的错误消息语法
```

#### 问题 5: 配置格式错误
```
yaml.scanner.ScannerError: mapping values are not allowed here
```

**解决方案**:
1. 检查 YAML 语法：
```bash
python -c "
import yaml
with open('config.yaml', 'r') as f:
    yaml.safe_load(f)
print('YAML 格式正确')
"
```

2. 常见 YAML 错误：
```yaml
# ❌ 错误：缩进不一致
obsidian:
  vault_path: "/path"
    rest_api:  # 缩进错误
      api_key: "key"

# ✅ 正确：一致的缩进
obsidian:
  vault_path: "/path"
  rest_api:
    api_key: "key"
```

### 🌐 API 连接问题

#### 问题 6: Claude API 连接失败
```
APIError: Failed to connect to Claude API
```

**诊断步骤**:
1. 验证 API 密钥格式：
```bash
echo $ANTHROPIC_API_KEY | grep -E "^sk-ant-"
```

2. 检查 API URL 配置：
```bash
# 检查配置文件中的 API URL
grep -A 5 "claude:" config.yaml
```

3. 测试网络连接：
```bash
# 测试默认 API 端点
curl -I https://api.anthropic.com

# 测试自定义端点（如果使用）
curl -I https://your-custom-endpoint.com
```

#### 问题 6a: Claude API URL 配置错误
```
ClaudeAPIURLError: Invalid URL format: not-a-url
```

**解决方案**:
1. 检查 API URL 格式：
```yaml
claude:
  # ✅ 正确格式
  api_url: "https://api.anthropic.com"
  api_url: "https://proxy.example.com:8080"
  api_url: "http://localhost:3128"
  
  # ❌ 错误格式
  api_url: "not-a-url"
  api_url: "ftp://api.anthropic.com"
  api_url: "api.anthropic.com"  # 缺少协议
```

2. 常见 API URL 配置：
```yaml
# 官方 API
api_url: "https://api.anthropic.com"

# 代理服务器
api_url: "https://your-proxy.example.com"
api_url: "https://claude-proxy.internal:8080"

# 本地开发
api_url: "http://localhost:3128"
api_url: "https://localhost:8080"
```

#### 问题 6b: Claude 模型名称无效
```
ClaudeModelValidationError: Invalid model name: invalid-model
```

**解决方案**:
1. 使用支持的模型名称：
```yaml
claude:
  # ✅ 当前支持的模型
  model: "claude-3-5-sonnet-20241022"  # 推荐
  model: "claude-3-5-haiku-20241022"   # 快速
  model: "claude-3-opus-20240229"      # 最强
  model: "claude-3-sonnet-20240229"    # 平衡
  model: "claude-3-haiku-20240307"     # 经济
  
  # ✅ 最新别名
  model: "claude-3-5-sonnet-latest"
  model: "claude-3-5-haiku-latest"
  
  # ❌ 无效模型名称
  model: "gpt-4"
  model: "claude-4"
  model: "invalid-model"
```

2. 检查模型可用性：
```bash
# 查看配置中的模型
grep "model:" config.yaml
```

#### 问题 6c: Claude API 密钥格式错误
```
ClaudeAPIKeyError: Claude API key should start with 'sk-ant-'
```

**解决方案**:
1. 验证 API 密钥格式：
```bash
# 检查密钥格式
echo $ANTHROPIC_API_KEY | head -c 20
# 应该显示: sk-ant-api03-...

# 检查密钥长度
echo $ANTHROPIC_API_KEY | wc -c
# 应该大于 50 个字符
```

2. 获取正确的 API 密钥：
   - 访问 https://console.anthropic.com/
   - 创建新的 API 密钥
   - 确保密钥以 `sk-ant-` 开头

#### 问题 6d: Claude API 连接超时或网络错误
```
ClaudeConnectionError: Connection error to https://api.anthropic.com
```

**解决方案**:
1. 检查网络连接：
```bash
# 测试基本连接
ping api.anthropic.com

# 测试 HTTPS 连接
curl -I https://api.anthropic.com

# 检查防火墙设置
telnet api.anthropic.com 443
```

2. 代理服务器配置：
```bash
# 如果使用代理，设置环境变量
export https_proxy=http://proxy.company.com:8080
export http_proxy=http://proxy.company.com:8080
```

3. 自定义端点配置：
```yaml
claude:
  # 对于自定义端点，确保服务正在运行
  api_url: "https://your-proxy.example.com"
  
  # 对于本地端点，可能需要禁用 SSL 验证
  api_url: "http://localhost:3128"
```

#### 问题 7: Obsidian API 连接失败
```
APIError: Failed to connect to Obsidian Local REST API
```

**解决方案**:
1. 确认 Obsidian Local REST API 插件已安装并启用
2. 检查 API 服务状态：
```bash
curl -k -H "Authorization: Bearer $OBSIDIAN_API_KEY" \
     https://localhost:27123/
```

3. 验证配置：
```yaml
obsidian:
  rest_api:
    url: "https://localhost:27123"  # 确认端口正确
    verify_ssl: false  # 本地开发时禁用 SSL 验证
```

### 📦 依赖项问题

#### 问题 8: 缺少依赖项
```
ModuleNotFoundError: No module named 'aiohttp'
```

**解决方案**:
```bash
# 安装所有依赖项
pip install -r requirements.txt

# 或单独安装缺失的包
pip install aiohttp pyyaml anthropic

# 检查安装状态
python -m journal_organizer check-deps
```

#### 问题 9: 版本冲突
```
ImportError: cannot import name 'xxx' from 'yyy'
```

**解决方案**:
```bash
# 升级到兼容版本
pip install --upgrade aiohttp anthropic

# 或使用虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows
pip install -r requirements.txt
```

### 🤖 Claude API 配置问题

#### 问题 12: Claude API 配置迁移
```
INFO: Migrated model 'claude-3-sonnet' to 'claude-3-sonnet-20240229'
```

**说明**: 这是正常的迁移信息，不是错误。系统自动将旧的模型名称迁移到新格式。

**常见迁移**:
- `claude-3-sonnet` → `claude-3-sonnet-20240229`
- `claude-3-opus` → `claude-3-opus-20240229`
- `claude-3-haiku` → `claude-3-haiku-20240307`
- `sonnet` → `claude-3-5-sonnet-20241022`
- `opus` → `claude-3-opus-20240229`
- `haiku` → `claude-3-haiku-20240307`

#### 问题 13: 自定义 API 端点配置
```
WARNING: Using custom API endpoint: https://proxy.example.com
```

**解决方案**:
1. 验证自定义端点：
```bash
# 测试端点可用性
curl -I https://proxy.example.com

# 测试 API 兼容性
curl -X POST https://proxy.example.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'
```

2. 常见自定义端点配置：
```yaml
# 企业代理服务器
claude:
  api_url: "https://claude-proxy.company.com"
  api_key: "${ANTHROPIC_API_KEY}"

# 本地开发环境
claude:
  api_url: "http://localhost:8080"
  api_key: "local-dev-key"

# 区域端点（如果可用）
claude:
  api_url: "https://api-eu.anthropic.com"
  api_key: "${ANTHROPIC_API_KEY}"
```

#### 问题 14: 配置验证失败
```
ConfigurationError: Claude configuration validation failed
```

**诊断步骤**:
1. 检查配置完整性：
```bash
# 验证配置文件语法
python -c "
import yaml
with open('config.yaml', 'r') as f:
    config = yaml.safe_load(f)
    claude_config = config.get('claude', {})
    print('API Key:', 'present' if claude_config.get('api_key') else 'missing')
    print('API URL:', claude_config.get('api_url', 'default'))
    print('Model:', claude_config.get('model', 'default'))
"
```

2. 测试配置加载：
```python
# 测试配置验证
from config import Config
try:
    config = Config('config.yaml')
    print('配置加载成功')
    print(f'Claude API URL: {config.claude.api_url}')
    print(f'Claude Model: {config.claude.model}')
except Exception as e:
    print(f'配置错误: {e}')
```

#### 问题 15: 向后兼容性问题
```
WARNING: Legacy configuration detected, migration applied
```

**说明**: 系统检测到旧版本的配置格式，自动进行了迁移。这是正常行为。

**迁移内容**:
- 添加缺失的 `api_url` 字段（默认为 `https://api.anthropic.com`）
- 更新旧的模型名称格式
- 添加缺失的配置节（如 `journal`、`output` 等）

**验证迁移结果**:
```bash
# 查看迁移后的配置
python -c "
from config import Config
config = Config('config.yaml')
print('迁移后的配置:')
print(f'  API URL: {config.claude.api_url}')
print(f'  Model: {config.claude.model}')
print(f'  Max Tokens: {config.claude.max_tokens}')
"
```

#### 问题 10: 文件权限错误
```
PermissionError: [Errno 13] Permission denied: 'config.yaml'
```

**解决方案**:
```bash
# 检查文件权限
ls -la config.yaml

# 修复权限
chmod 644 config.yaml
chmod 755 .  # 目录权限
```

#### 问题 11: Vault 访问权限
```
PermissionError: Cannot access Obsidian vault
```

**解决方案**:
```bash
# 检查 vault 目录权限
ls -la /path/to/obsidian/vault

# 修复权限（谨慎操作）
chmod -R 755 /path/to/obsidian/vault
```

## 调试技巧

### 1. 启用详细日志

```bash
# 设置调试级别
python -m journal_organizer --log-level DEBUG organize

# 查看日志文件
tail -f logs/journal_organizer.log
```

### 2. 分步调试

```python
# 在代码中添加调试点
import logging
logger = logging.getLogger(__name__)

logger.debug(f"配置内容: {config}")
logger.debug(f"API 响应: {response}")
```

### 3. 测试单个组件

```python
# 测试配置加载
from journal_organizer.main import JournalOrganizerAgent
agent = JournalOrganizerAgent("config.yaml")
print(f"配置加载成功: {bool(agent.config)}")

# 测试 API 连接
import asyncio
from journal_organizer.skills.claude_skill import ClaudeAnalyzeSkill

async def test_claude():
    skill = ClaudeAnalyzeSkill()
    # 测试逻辑
    
asyncio.run(test_claude())
```

### 4. 网络诊断

```bash
# 检查网络连接
ping api.anthropic.com
ping localhost

# 检查端口占用
netstat -an | grep 27123

# 测试 SSL 连接
openssl s_client -connect api.anthropic.com:443
```

## 性能问题

### 内存使用过高

**诊断**:
```python
import psutil
import os

process = psutil.Process(os.getpid())
memory_mb = process.memory_info().rss / 1024 / 1024
print(f"内存使用: {memory_mb:.2f} MB")
```

**解决方案**:
- 检查是否有内存泄漏
- 限制并发操作数量
- 使用 `gc.collect()` 强制垃圾回收

### API 调用缓慢

**诊断**:
```python
import time
import asyncio

async def time_api_call():
    start = time.time()
    result = await api_call()
    duration = time.time() - start
    print(f"API 调用耗时: {duration:.2f} 秒")
    return result
```

**解决方案**:
- 检查网络延迟
- 增加超时设置
- 实现重试机制
- 使用连接池

## 错误代码参考

| 错误代码 | 描述 | 常见原因 | 解决方案 |
|---------|------|----------|----------|
| CONFIG_001 | 配置文件不存在 | 未创建配置文件 | 复制 config.example.yaml |
| CONFIG_002 | 配置格式错误 | YAML 语法错误 | 检查缩进和语法 |
| CONFIG_003 | 缺少必需配置项 | 配置不完整 | 添加缺失的配置项 |
| CONFIG_004 | 环境变量未设置 | 环境变量缺失 | 设置相应的环境变量 |
| CONFIG_005 | 环境变量格式错误 | 语法错误 | 检查 ${VAR} 语法 |
| API_001 | API 密钥无效 | 密钥错误或过期 | 检查并更新 API 密钥 |
| API_002 | API 连接超时 | 网络问题 | 检查网络连接 |
| API_003 | API 限流 | 请求过于频繁 | 减少请求频率 |
| API_004 | SSL 证书错误 | 证书验证失败 | 禁用 SSL 验证（仅本地） |
| API_005 | API URL 格式错误 | URL 格式无效 | 使用正确的 URL 格式 |
| API_006 | 模型名称无效 | 不支持的模型 | 使用支持的模型名称 |
| API_007 | API 密钥格式错误 | 密钥格式不正确 | 使用 sk-ant- 开头的密钥 |
| CLAUDE_001 | Claude 配置错误 | Claude 特定配置问题 | 检查 Claude 配置节 |
| CLAUDE_002 | Claude 连接错误 | Claude API 连接失败 | 检查网络和端点 |
| CLAUDE_003 | Claude 模型错误 | 模型不可用 | 更换可用的模型 |
| CLAUDE_004 | Claude 迁移警告 | 配置需要迁移 | 允许自动迁移 |
| SKILL_001 | Skill 执行失败 | 输入参数错误 | 检查参数格式 |
| SKILL_002 | Skill 超时 | 操作耗时过长 | 增加超时设置 |
| IMPORT_001 | 模块导入错误 | 相对导入问题 | 使用模块方式运行 |
| IMPORT_002 | 依赖项缺失 | 包未安装 | 安装缺失的依赖项 |
| ENV_001 | 环境变量缺失 | 必需变量未设置 | 设置环境变量 |
| ENV_002 | 环境变量展开失败 | 语法或值错误 | 检查变量语法和值 |

## 日志分析

### 常见日志模式

```bash
# 查找错误
grep -i error logs/journal_organizer.log

# 查找 API 调用
grep -i "api" logs/journal_organizer.log

# 查找配置问题
grep -i "config" logs/journal_organizer.log

# 实时监控
tail -f logs/journal_organizer.log | grep -i error
```

### 日志级别说明

- **DEBUG**: 详细的调试信息
- **INFO**: 一般信息，正常操作
- **WARNING**: 警告信息，可能的问题
- **ERROR**: 错误信息，操作失败
- **CRITICAL**: 严重错误，系统无法继续

## 常见配置场景

### 企业环境配置

#### 使用代理服务器
```yaml
claude:
  api_key: "${ANTHROPIC_API_KEY}"
  api_url: "https://claude-proxy.company.com"
  model: "claude-3-5-sonnet-20241022"

# 可能需要设置代理环境变量
# export https_proxy=http://proxy.company.com:8080
# export http_proxy=http://proxy.company.com:8080
```

#### 使用内部 API 网关
```yaml
claude:
  api_key: "${COMPANY_CLAUDE_KEY}"
  api_url: "https://api-gateway.internal:8443/claude"
  model: "claude-3-5-sonnet-20241022"
```

### 开发环境配置

#### 本地开发设置
```yaml
claude:
  api_key: "${ANTHROPIC_API_KEY}"
  api_url: "${CLAUDE_API_URL:-https://api.anthropic.com}"
  model: "${CLAUDE_MODEL:-claude-3-5-sonnet-20241022}"
  max_tokens: 4096
  temperature: 0.7

obsidian:
  vault_path: "${OBSIDIAN_VAULT_PATH:-./test_vault}"
  rest_api:
    url: "${OBSIDIAN_API_URL:-https://localhost:27123}"
    api_key: "${OBSIDIAN_API_KEY}"
    verify_ssl: false
```

#### 测试环境配置
```yaml
claude:
  api_key: "${TEST_CLAUDE_KEY}"
  api_url: "https://test-api.example.com"
  model: "claude-3-haiku-20240307"  # 使用更便宜的模型进行测试
  max_tokens: 1024
  temperature: 0.0  # 确定性输出用于测试
```

### 多环境配置管理

#### 使用环境特定的配置文件
```bash
# 开发环境
cp config.example.yaml config.dev.yaml
# 编辑 config.dev.yaml

# 生产环境
cp config.example.yaml config.prod.yaml
# 编辑 config.prod.yaml

# 运行时指定配置文件
python -m journal_organizer --config config.dev.yaml organize
```

#### 使用环境变量切换配置
```bash
# 设置环境特定的变量
export ENV=development
export CLAUDE_API_URL="https://dev-api.example.com"
export CLAUDE_MODEL="claude-3-haiku-20240307"

# 或者生产环境
export ENV=production
export CLAUDE_API_URL="https://api.anthropic.com"
export CLAUDE_MODEL="claude-3-5-sonnet-20241022"
```

### 安全配置最佳实践

#### 1. 使用环境变量存储敏感信息
```yaml
# ✅ 推荐：使用环境变量
claude:
  api_key: "${ANTHROPIC_API_KEY}"

obsidian:
  rest_api:
    api_key: "${OBSIDIAN_API_KEY}"

# ❌ 不推荐：直接在配置文件中存储密钥
claude:
  api_key: "sk-ant-actual-key-here"
```

#### 2. 设置适当的文件权限
```bash
# 限制配置文件访问权限
chmod 600 config.yaml

# 确保日志目录权限正确
chmod 755 logs/
chmod 644 logs/*.log
```

#### 3. 使用 .gitignore 保护敏感文件
```bash
# 添加到 .gitignore
echo "config.yaml" >> .gitignore
echo ".env" >> .gitignore
echo "logs/*.log" >> .gitignore
```

### 性能优化配置

#### 高性能配置
```yaml
claude:
  api_key: "${ANTHROPIC_API_KEY}"
  api_url: "https://api.anthropic.com"
  model: "claude-3-5-sonnet-20241022"  # 最新最强模型
  max_tokens: 8192  # 更大的输出空间
  temperature: 0.7

# 启用详细日志以监控性能
logging:
  level: "DEBUG"
  file: "logs/performance.log"
```

#### 成本优化配置
```yaml
claude:
  api_key: "${ANTHROPIC_API_KEY}"
  api_url: "https://api.anthropic.com"
  model: "claude-3-haiku-20240307"  # 更经济的模型
  max_tokens: 2048  # 限制输出长度
  temperature: 0.5

# 减少日志输出
logging:
  level: "WARNING"
  file: "logs/journal_organizer.log"
```

### 自助诊断清单

在寻求帮助前，请完成以下检查：

- [ ] 运行 `python -m journal_organizer check-deps`
- [ ] 检查配置文件格式和内容
- [ ] 验证环境变量设置
- [ ] 查看日志文件中的错误信息
- [ ] 测试网络连接和 API 访问
- [ ] 确认文件和目录权限

### 报告问题时请提供

1. **错误信息**: 完整的错误堆栈跟踪
2. **配置文件**: 脱敏后的配置内容
3. **环境信息**: Python 版本、操作系统
4. **日志文件**: 相关的日志片段
5. **重现步骤**: 导致问题的具体操作

### 联系方式

- 查看项目文档
- 检查 GitHub Issues
- 运行内置诊断工具

## 预防措施

### 定期维护

```bash
# 定期更新依赖项
pip list --outdated
pip install --upgrade package_name

# 清理日志文件
find logs/ -name "*.log" -mtime +30 -delete

# 备份配置文件
cp config.yaml config.yaml.backup
```

### 监控建议

- 设置日志轮转
- 监控内存和 CPU 使用
- 定期测试 API 连接
- 备份重要配置和数据