windy/journal_organizer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
f7e54692a973fc7f3499a24759e198adecd596d3
journal_organizer/DEVELOPER_GUIDE.md
T

964 lines
23 KiB
Markdown
Raw Normal View History

Initial project setup: Obsidian intelligent journal organizer
2025-12-31 17:55:10 +08:00
# 开发者指南
本指南说明如何扩展和自定义日记整理 Agent，包括新的错误处理模式、配置验证功能和故障排除指南。
## 架构概览
Agent 系统基于以下核心概念：
- **Agent**：主控制器，负责管理 Commands 和 Skills
- **Command**：用户可执行的命令，编排多个 Skills
- **Skill**：原子化的功能单元，执行具体任务
- **SkillChain**：多个 Skills 的有序执行链
- **ErrorHandler**：集中式错误处理和日志记录
- **ConfigurationValidator**：配置验证和环境变量扩展
## 核心类
### Agent
```python
from journal_organizer.agent_core import Agent
# 创建 Agent
agent = Agent("MyAgent", config={})
# 注册命令
agent.register_command(my_command)
# 执行命令
result = await agent.execute_command("command_name", args={})
```
### Skill
所有 Skill 都继承自 `Skill` 基类：
```python
from journal_organizer.agent_core import Skill, SkillType, SkillResult, CommandContext
class MySkill(Skill):
def __init__(self):
super().__init__(
name="my_skill",
skill_type=SkillType.ANALYZE,
description="我的自定义 Skill"
)
async def execute(self, context: CommandContext, **kwargs) -> SkillResult:
# 实现您的逻辑
try:
result = do_something(**kwargs)
return SkillResult(
success=True,
data=result,
message="执行成功"
)
except Exception as e:
return SkillResult(
success=False,
error=str(e),
message="执行失败"
)
```
### Command
所有 Command 都继承自 `Command` 基类：
```python
from journal_organizer.agent_core import Command, SkillResult, CommandContext
class MyCommand(Command):
def __init__(self):
super().__init__(
name="my_command",
description="我的自定义命令",
aliases=["mc"]
)
# 注册 Skills
self.register_skill(MySkill())
async def execute(self, context: CommandContext) -> SkillResult:
# 获取参数
param1 = context.args.get('param1')
# 执行 Skill
skill = self.skills['my_skill']
result = await skill.execute(context, param1=param1)
return result
```
## 添加新的 Skill
### 步骤 1: 创建 Skill 类
在 `skills/` 目录下创建一个新文件，例如 `my_skill.py`：
```python
from ..agent_core import Skill, SkillType, SkillResult, CommandContext
class MyCustomSkill(Skill):
def __init__(self):
super().__init__(
name="my_custom_skill",
skill_type=SkillType.TRANSFORM,
description="执行自定义转换"
)
async def execute(self, context: CommandContext, **kwargs) -> SkillResult:
try:
input_data = kwargs.get('input_data')
# 您的自定义逻辑
output_data = self._process(input_data)
return SkillResult(
success=True,
data=output_data,
message="处理完成"
)
except Exception as e:
return SkillResult(
success=False,
error=str(e),
message="处理失败"
)
def _process(self, data):
# 实现处理逻辑
return data
```
### 步骤 2: 在 Command 中使用 Skill
```python
from ..skills.my_skill import MyCustomSkill
class MyCommand(Command):
def __init__(self):
super().__init__(name="my_command")
self.register_skill(MyCustomSkill())
async def execute(self, context: CommandContext) -> SkillResult:
skill = self.skills['my_custom_skill']
return await skill.execute(context, input_data="test")
```
## 添加新的 Command
### 步骤 1: 创建 Command 类
在 `commands/` 目录下创建一个新文件，例如 `my_command.py`：
```python
from ..agent_core import Command, SkillResult, CommandContext
from ..skills.my_skill import MyCustomSkill
class MyCommand(Command):
def __init__(self):
super().__init__(
name="my_command",
description="我的自定义命令",
aliases=["mc", "my-cmd"]
)
self.register_skill(MyCustomSkill())
async def execute(self, context: CommandContext) -> SkillResult:
# 获取参数
param1 = context.args.get('param1')
param2 = context.args.get('param2', 'default')
# 执行 Skill
skill = self.skills['my_custom_skill']
result = await skill.execute(context, input_data=param1)
return result
```
### 步骤 2: 在 Agent 中注册 Command
编辑 `main.py` 的 `_register_commands` 方法：
```python
def _register_commands(self) -> None:
"""注册所有命令"""
self.agent.register_command(OrganizeCommand())
self.agent.register_command(MyCommand()) # 添加新命令
```
### 步骤 3: 测试新命令
```bash
python -m journal_organizer my_command --param1 "value1"
```
## 使用 SkillChain
SkillChain 允许您按顺序执行多个 Skills：
```python
from journal_organizer.agent_core import SkillChain
class MyCommand(Command):
def __init__(self):
super().__init__(name="my_command")
# 创建 Skill 链
chain = SkillChain("my_chain", "执行一系列操作")
chain.add_skill(Skill1(), {"param1": "value1"})
chain.add_skill(Skill2(), {"param2": "value2"})
self.register_skill_chain(chain)
async def execute(self, context: CommandContext) -> SkillResult:
chain = self.skill_chains['my_chain']
return await chain.execute(context)
```
## 异步编程
所有 Skills 和 Commands 都使用异步编程（async/await）。这允许并发执行多个操作。
### 基本示例
```python
async def execute(self, context: CommandContext, **kwargs) -> SkillResult:
# 异步调用外部 API
result = await self.call_external_api()
return SkillResult(success=True, data=result)
async def call_external_api(self):
# 使用 aiohttp 进行异步 HTTP 请求
async with aiohttp.ClientSession() as session:
async with session.get('https://api.example.com/data') as resp:
return await resp.json()
```
## 错误处理
### 新的错误处理框架
系统现在使用集中式错误处理框架，提供一致的错误管理和日志记录：
```python
from journal_organizer.error_handling import (
ErrorHandler,
JournalOrganizerError,
ConfigurationError,
APIError,
ValidationError
)
# 创建错误处理器
import logging
logger = logging.getLogger("MySkill")
error_handler = ErrorHandler(logger)
# 处理 API 错误
try:
result = await api_call()
except Exception as e:
error_result = error_handler.handle_api_error(e, "claude", "analyze_text")
return SkillResult(
success=False,
error=error_result["error"],
message=error_result["message"]
)
```
### 自定义异常类型
使用专门的异常类型来处理不同类型的错误：
```python
from journal_organizer.error_handling import (
JournalOrganizerError,
ConfigurationError,
APIError,
ValidationError
)
# 配置错误
if not api_key:
raise ConfigurationError("API key is required", context={"service": "claude"})
# API 错误
if response.status_code != 200:
raise APIError(
"API request failed",
api_name="obsidian",
status_code=response.status_code
)
# 验证错误
if not validate_input(data):
raise ValidationError("Invalid input format", field="date")
```
### Skill 中的错误处理模式
在 Skill 中实现标准化的错误处理：
```python
from journal_organizer.agent_core import Skill, SkillResult, CommandContext
from journal_organizer.error_handling import ErrorHandler, APIError, ValidationError
class MySkill(Skill):
def __init__(self):
super().__init__(name="my_skill")
self.error_handler = ErrorHandler(self.logger)
async def execute(self, context: CommandContext, **kwargs) -> SkillResult:
try:
# 输入验证
self._validate_inputs(**kwargs)
# 执行主要逻辑
result = await self._perform_operation(**kwargs)
return SkillResult(success=True, data=result, message="操作成功")
except ValidationError as e:
error_result = self.error_handler.handle_validation_error(e, "input_data")
return SkillResult(
success=False,
error=error_result["error"],
message=error_result["message"]
)
except APIError as e:
error_result = self.error_handler.handle_api_error(e, "external_service", "operation")
return SkillResult(
success=False,
error=error_result["error"],
message=error_result["message"]
)
except Exception as e:
# 处理未预期的错误
self.logger.error(f"Unexpected error in {self.name}: {str(e)}", exc_info=True)
return SkillResult(
success=False,
error="Internal error occurred",
message="操作失败，请检查日志"
)
def _validate_inputs(self, **kwargs):
"""验证输入参数"""
required_params = ['param1', 'param2']
for param in required_params:
if param not in kwargs:
raise ValidationError(f"Missing required parameter: {param}", field=param)
async def _perform_operation(self, **kwargs):
"""执行主要操作"""
# 实现您的逻辑
pass
```
## 日志记录
使用内置的 logger 记录信息：
```python
class MySkill(Skill):
async def execute(self, context: CommandContext, **kwargs) -> SkillResult:
self.logger.debug("开始执行")
self.logger.info("处理数据")
self.logger.warning("可能的问题")
self.logger.error("发生错误")
return SkillResult(success=True)
```
## 配置管理
### 新的配置验证系统
系统现在包含强大的配置验证功能，支持类型检查、环境变量扩展和路径验证：
```python
from journal_organizer.config_validation import (
SystemConfig,
ObsidianConfig,
ClaudeConfig,
validate_system_config
)
# 验证配置
try:
config = validate_system_config(raw_config)
print("配置验证成功")
except ValidationError as e:
print(f"配置验证失败: {e}")
```
### 环境变量扩展
配置文件支持环境变量扩展：
```yaml
# config.yaml
claude:
api_key: "${ANTHROPIC_API_KEY}" # 从环境变量读取
model: "${CLAUDE_MODEL:-claude-3-5-sonnet-20241022}" # 带默认值
obsidian:
vault_path: "${OBSIDIAN_VAULT_PATH}"
rest_api:
api_key: "${OBSIDIAN_API_KEY}"
```
### 配置验证示例
```python
from journal_organizer.config_validation import validate_obsidian_config, validate_claude_config
# 验证 Obsidian 配置
obsidian_config = {
"vault_path": "/path/to/vault",
"rest_api": {
"url": "https://localhost:27123",
"api_key": "your-key",
"verify_ssl": False
}
}
try:
validated_config = validate_obsidian_config(obsidian_config)
print("Obsidian 配置有效")
except ValidationError as e:
print(f"Obsidian 配置错误: {e}")
# 验证 Claude 配置
claude_config = {
"api_key": "sk-ant-...",
"model": "claude-3-5-sonnet-20241022",
"max_tokens": 4096
}
try:
validated_config = validate_claude_config(claude_config)
print("Claude 配置有效")
except ValidationError as e:
print(f"Claude 配置错误: {e}")
```
### 在 Skill 中访问配置
```python
async def execute(self, context: CommandContext, **kwargs) -> SkillResult:
config = context.config or {}
# 安全地访问配置
claude_config = config.get('claude', {})
api_key = claude_config.get('api_key')
if not api_key:
raise ConfigurationError("Claude API key not configured")
# 使用配置
return SkillResult(success=True)
```
## 测试
### 单元测试示例
```python
import pytest
from journal_organizer.agent_core import CommandContext
@pytest.mark.asyncio
async def test_my_skill():
skill = MySkill()
context = CommandContext(command_name="test")
result = await skill.execute(context, input_data="test")
assert result.success == True
assert result.data is not None
```
### 运行测试
```bash
pytest tests/
```
## 性能优化
### 并发执行
```python
import asyncio
async def execute(self, context: CommandContext, **kwargs) -> SkillResult:
# 并发执行多个操作
results = await asyncio.gather(
self.operation1(),
self.operation2(),
self.operation3()
)
return SkillResult(success=True, data=results)
```
### 缓存
```python
from functools import lru_cache
class MySkill(Skill):
@lru_cache(maxsize=128)
def expensive_operation(self, key):
# 缓存昂贵的操作
return process(key)
```
## 最佳实践
### 现代 Python 模式
系统现在遵循现代 Python 最佳实践：
#### 1. 使用 f-strings 进行字符串格式化
```python
# ✅ 推荐：使用 f-strings
name = "用户"
message = f"欢迎 {name}，当前时间是 {datetime.now()}"
# ❌ 避免：字符串连接
message = "欢迎 " + name + "，当前时间是 " + str(datetime.now())
```
#### 2. 使用 pathlib 进行文件路径操作
```python
from pathlib import Path
# ✅ 推荐：使用 pathlib
vault_path = Path(config['obsidian']['vault_path'])
daily_folder = vault_path / "Daily"
note_file = daily_folder / f"{date}.md"
# 检查文件是否存在
if note_file.exists():
content = note_file.read_text(encoding='utf-8')
# ❌ 避免：使用 os.path
import os
note_file = os.path.join(vault_path, "Daily", f"{date}.md")
```
#### 3. 使用 dataclasses 定义数据结构
```python
from dataclasses import dataclass, field
from typing import Optional, List
from datetime import datetime
@dataclass
class SkillResult:
success: bool
data: Optional[Dict[str, Any]] = None
error: Optional[str] = None
message: str = ""
timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
def to_dict(self) -> Dict[str, Any]:
return asdict(self)
```
#### 4. 使用类型提示
```python
from typing import Dict, Any, Optional, List, Union
async def execute_skill(
skill_name: str,
context: CommandContext,
**kwargs: Any
) -> SkillResult:
"""
执行指定的 Skill
Args:
skill_name: Skill 名称
context: 命令执行上下文
**kwargs: Skill 参数
Returns:
SkillResult: 执行结果
"""
pass
```
#### 5. 使用异步上下文管理器
```python
from contextlib import asynccontextmanager
import aiohttp
@asynccontextmanager
async def http_client(config: Dict[str, Any]):
"""HTTP 客户端上下文管理器"""
connector = aiohttp.TCPConnector(
ssl=False if not config.get('verify_ssl', True) else None
)
async with aiohttp.ClientSession(connector=connector) as session:
try:
yield session
finally:
await session.close()
# 使用示例
async def call_api():
async with http_client(api_config) as client:
async with client.get(url) as response:
return await response.json()
```
### 通用最佳实践
1. **单一职责**：每个 Skill 只负责一个任务
2. **错误处理**：使用新的错误处理框架
3. **日志记录**：使用 logger 记录重要信息
4. **配置驱动**：使用配置验证系统
5. **异步编程**：充分利用异步特性提高性能
6. **类型安全**：使用类型提示和验证
7. **文档**：为您的 Skills 和 Commands 编写清晰的文档
8. **测试**：编写单元测试和属性测试确保代码质量
9. **版本控制**：使用 git 管理代码版本
10. **代码格式化**：使用 black 和 isort 保持代码风格一致
## 示例：完整的自定义 Skill
```python
"""
自定义 Skill 示例：文本统计
"""
from ..agent_core import Skill, SkillType, SkillResult, CommandContext
class TextStatisticsSkill(Skill):
"""计算文本统计信息的 Skill"""
def __init__(self):
super().__init__(
name="text_statistics",
skill_type=SkillType.ANALYZE,
description="计算文本的字数、词数、句数等统计信息"
)
async def execute(self, context: CommandContext, **kwargs) -> SkillResult:
"""
执行文本统计
Args:
context: 命令执行上下文
**kwargs: 包含 text 参数
Returns:
SkillResult: 包含统计结果的结果
"""
try:
text = kwargs.get('text', '')
if not text:
return SkillResult(
success=False,
error="缺少文本参数",
message="未提供要统计的文本"
)
# 计算统计信息
stats = {
'char_count': len(text),
'word_count': len(text.split()),
'sentence_count': len(text.split('。')),
'line_count': len(text.split('\n')),
'avg_word_length': len(text) / len(text.split()) if text.split() else 0
}
self.logger.info(f"文本统计完成: {stats}")
return SkillResult(
success=True,
data=stats,
message="文本统计完成"
)
except Exception as e:
self.logger.error(f"文本统计失败: {str(e)}")
return SkillResult(
success=False,
error=str(e),
message="文本统计异常"
)
```
## 资源
- [Python 异步编程](https://docs.python.org/3/library/asyncio.html)
- [Anthropic API 文档](https://docs.anthropic.com/)
- [Obsidian API 文档](https://docs.obsidian.md/Obsidian+API)
---
# 故障排除指南
本节提供常见问题的解决方案和调试技巧。
## 常见问题
### 1. 导入错误 (ImportError)
**问题**: `ImportError: attempted relative import with no known parent package`
**解决方案**:
```bash
# 确保以模块方式运行
python -m journal_organizer --help
# 而不是直接运行
python main.py # ❌ 错误方式
```
**原因**: 项目使用相对导入，需要作为包运行。
### 2. 配置文件问题
**问题**: `ConfigurationError: Missing required configuration`
**解决方案**:
1. 检查配置文件是否存在：
```bash
ls -la config.yaml
```
2. 验证配置格式：
```bash
python -c "
import yaml
with open('config.yaml', 'r') as f:
config = yaml.safe_load(f)
print('配置文件格式正确')
"
```
3. 检查环境变量：
```bash
echo $ANTHROPIC_API_KEY
echo $OBSIDIAN_API_KEY
```
### 3. API 连接问题
**问题**: `APIError: Failed to connect to Claude/Obsidian API`
**解决方案**:
**Claude API**:
```bash
# 测试 API 密钥
curl -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
-H "Content-Type: application/json" \
https://api.anthropic.com/v1/messages
```
**Obsidian API**:
```bash
# 检查 Obsidian Local REST API 插件状态
curl -k -H "Authorization: Bearer $OBSIDIAN_API_KEY" \
https://localhost:27123/
```
### 4. 依赖项问题
**问题**: `ModuleNotFoundError: No module named 'xxx'`
**解决方案**:
```bash
# 检查依赖项状态
python -m journal_organizer check-deps
# 安装缺失的依赖项
pip install -r requirements.txt
# 安装可选依赖项
pip install pyyaml aiohttp anthropic
```
### 5. 权限问题
**问题**: `PermissionError: [Errno 13] Permission denied`
**解决方案**:
```bash
# 检查文件权限
ls -la config.yaml
ls -la /path/to/obsidian/vault
# 修复权限
chmod 644 config.yaml
chmod -R 755 /path/to/obsidian/vault
```
### 6. SSL 证书问题
**问题**: `SSL: CERTIFICATE_VERIFY_FAILED`
**解决方案**:
在配置文件中禁用 SSL 验证（仅用于本地开发）：
```yaml
obsidian:
rest_api:
verify_ssl: false
```
## 调试技巧
### 1. 启用详细日志
```bash
# 设置调试级别日志
python -m journal_organizer --log-level DEBUG organize
```
### 2. 使用 Python 调试器
```python
# 在 Skill 中添加断点
import pdb; pdb.set_trace()
# 或使用 ipdb（更友好的界面）
import ipdb; ipdb.set_trace()
```
### 3. 检查配置加载
```python
# 测试配置加载
from journal_organizer.main import JournalOrganizerAgent
agent = JournalOrganizerAgent("config.yaml")
print(f"配置: {agent.config}")
```
### 4. 测试单个 Skill
```python
# 单独测试 Skill
import asyncio
from journal_organizer.skills.claude_skill import ClaudeAnalyzeSkill
from journal_organizer.agent_core import CommandContext
async def test_skill():
skill = ClaudeAnalyzeSkill()
context = CommandContext(command_name="test")
result = await skill.execute(context, text="测试文本")
print(f"结果: {result}")
asyncio.run(test_skill())
```
## 性能问题
### 1. 内存使用过高
**诊断**:
```python
import psutil
import os
process = psutil.Process(os.getpid())
print(f"内存使用: {process.memory_info().rss / 1024 / 1024:.2f} MB")
```
**解决方案**:
- 检查是否有内存泄漏
- 使用 `gc.collect()` 强制垃圾回收
- 限制并发操作数量
### 2. API 调用缓慢
**诊断**:
```python
import time
start_time = time.time()
result = await api_call()
duration = time.time() - start_time
print(f"API 调用耗时: {duration:.2f} 秒")
```
**解决方案**:
- 检查网络连接
- 增加超时设置
- 使用连接池
- 实现重试机制
## 错误代码参考
| 错误代码 | 描述 | 解决方案 |
|---------|------|----------|
| CONFIG_001 | 配置文件不存在 | 创建 config.yaml 文件 |
| CONFIG_002 | 配置格式错误 | 检查 YAML/JSON 语法 |
| CONFIG_003 | 缺少必需配置项 | 添加缺失的配置项 |
| API_001 | API 密钥无效 | 检查并更新 API 密钥 |
| API_002 | API 连接超时 | 检查网络连接和服务状态 |
| API_003 | API 限流 | 减少请求频率或升级 API 计划 |
| SKILL_001 | Skill 执行失败 | 检查 Skill 输入参数和依赖项 |
| SKILL_002 | Skill 超时 | 增加超时设置或优化 Skill 逻辑 |
## 获取帮助
如果问题仍然存在：
1. **检查日志文件**: `logs/journal_organizer.log`
2. **运行诊断命令**: `python -m journal_organizer check-deps`
3. **查看详细错误**: 使用 `--log-level DEBUG`
4. **测试基本功能**: 运行简单的命令如 `list` 或 `help`
## 开发环境设置
### 推荐的开发工具
```bash
# 安装开发依赖
pip install pytest pytest-asyncio black isort mypy
# 代码格式化
black .
isort .
# 类型检查
mypy journal_organizer/
# 运行测试
pytest tests/
```
### 调试配置 (VS Code)
创建 `.vscode/launch.json`:
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug Journal Organizer",
"type": "python",
"request": "launch",
"module": "journal_organizer",
"args": ["--log-level", "DEBUG", "organize"],
"console": "integratedTerminal",
"cwd": "${workspaceFolder}"
}
]
}
```
Reference in New Issue Copy Permalink