journal_organizer/TROUBLESHOOTING.md

故障排除指南

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

快速诊断

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

# 检查依赖项状态
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

解决方案:

# ✅ 正确方式：作为模块运行
python -m journal_organizer --help

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

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

问题 2: 找不到模块规范

ValueError: __main__.__spec__ is None

解决方案: 确保在项目根目录运行命令，并且 __init__.py 文件存在：

ls -la __init__.py
pwd  # 确认在正确目录

⚙️ 配置问题

问题 3: 配置文件不存在

ConfigurationError: Configuration file not found

解决方案:

1. 复制示例配置文件：

cp config.example.yaml config.yaml

2. 编辑配置文件，填入正确的值：

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. 设置必需的环境变量：

# 设置 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. 永久设置环境变量：

# 添加到 ~/.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 文件（可选）：

# 创建 .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

解决方案: 检查配置文件中的环境变量语法：

# ✅ 正确的环境变量语法
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 语法：

python -c "
import yaml
with open('config.yaml', 'r') as f:
    yaml.safe_load(f)
print('YAML 格式正确')
"

2. 常见 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 密钥格式：

echo $ANTHROPIC_API_KEY | grep -E "^sk-ant-"

2. 检查 API URL 配置：

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

3. 测试网络连接：

# 测试默认 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 格式：

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 配置：

# 官方 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. 使用支持的模型名称：

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. 检查模型可用性：

# 查看配置中的模型
grep "model:" config.yaml

问题 6c: Claude API 密钥格式错误

ClaudeAPIKeyError: Claude API key should start with 'sk-ant-'

解决方案:

1. 验证 API 密钥格式：

# 检查密钥格式
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. 检查网络连接：

# 测试基本连接
ping api.anthropic.com

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

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

2. 代理服务器配置：

# 如果使用代理，设置环境变量
export https_proxy=http://proxy.company.com:8080
export http_proxy=http://proxy.company.com:8080

3. 自定义端点配置：

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 服务状态：

curl -k -H "Authorization: Bearer $OBSIDIAN_API_KEY" \
     https://localhost:27123/

3. 验证配置：

obsidian:
  rest_api:
    url: "https://localhost:27123"  # 确认端口正确
    verify_ssl: false  # 本地开发时禁用 SSL 验证

📦 依赖项问题

问题 8: 缺少依赖项

ModuleNotFoundError: No module named 'aiohttp'

解决方案:

# 安装所有依赖项
pip install -r requirements.txt

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

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

问题 9: 版本冲突

ImportError: cannot import name 'xxx' from 'yyy'

解决方案:

# 升级到兼容版本
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. 验证自定义端点：

# 测试端点可用性
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. 常见自定义端点配置：

# 企业代理服务器
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. 检查配置完整性：

# 验证配置文件语法
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. 测试配置加载：

# 测试配置验证
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 等）

验证迁移结果:

# 查看迁移后的配置
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'

解决方案:

# 检查文件权限
ls -la config.yaml

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

问题 11: Vault 访问权限

PermissionError: Cannot access Obsidian vault

解决方案:

# 检查 vault 目录权限
ls -la /path/to/obsidian/vault

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

调试技巧

1. 启用详细日志

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

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

2. 分步调试

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

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

3. 测试单个组件

# 测试配置加载
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. 网络诊断

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

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

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

性能问题

内存使用过高

诊断:

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 调用缓慢

诊断:

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	环境变量展开失败	语法或值错误	检查变量语法和值

日志分析

常见日志模式

# 查找错误
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: 严重错误，系统无法继续

常见配置场景

企业环境配置

使用代理服务器

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 网关

claude:
  api_key: "${COMPANY_CLAUDE_KEY}"
  api_url: "https://api-gateway.internal:8443/claude"
  model: "claude-3-5-sonnet-20241022"

开发环境配置

本地开发设置

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

测试环境配置

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

多环境配置管理

使用环境特定的配置文件

# 开发环境
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

使用环境变量切换配置

# 设置环境特定的变量
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. 使用环境变量存储敏感信息

# ✅ 推荐：使用环境变量
claude:
  api_key: "${ANTHROPIC_API_KEY}"

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

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

2. 设置适当的文件权限

# 限制配置文件访问权限
chmod 600 config.yaml

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

3. 使用 .gitignore 保护敏感文件

# 添加到 .gitignore
echo "config.yaml" >> .gitignore
echo ".env" >> .gitignore
echo "logs/*.log" >> .gitignore

性能优化配置

高性能配置

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"

成本优化配置

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
• 运行内置诊断工具

预防措施

定期维护

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

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

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

监控建议

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