Initial project setup: Obsidian intelligent journal organizer
- Add core agent architecture with Command + Skill pattern - Implement Claude API integration for content analysis - Add Obsidian REST API integration for vault operations - Create conversational interface (v2.0) with natural language processing - Add comprehensive configuration management and validation - Include project documentation and developer guides - Set up testing framework with unit, integration, and property tests - Add Kiro specs for Claude API configuration and code quality improvements - Configure project steering files for development guidelines
This commit is contained in:
windyboy
@@ -0,0 +1,30 @@
|
||||
# Product Overview
|
||||
|
||||
## Obsidian 智能日记整理 Agent
|
||||
|
||||
An intelligent journal organization system designed for Obsidian users that automatically analyzes daily journal entries, extracts key information (experiences, tasks, problems, etc.), and intelligently organizes them into designated locations within your knowledge base.
|
||||
|
||||
### Core Features
|
||||
|
||||
- **Intelligent Analysis**: Integrates Claude 3.5 Sonnet model for deep understanding of journal content and structured information extraction
|
||||
- **Automated Organization**: Automatically creates new notes from extracted content and places them in preset folders
|
||||
- **Bidirectional Linking**: Automatically adds links to original journal entries in generated notes for easy traceability
|
||||
- **Conversational Interface**: v2.0 introduces natural language conversation capabilities for intuitive interaction
|
||||
- **Command-Line Driven**: Standard CLI interface for easy integration and automation
|
||||
- **Highly Configurable**: All key parameters manageable through configuration files
|
||||
|
||||
### Architecture
|
||||
|
||||
The system uses a **Command + Skill** architecture with two main versions:
|
||||
|
||||
1. **v1.0**: Direct command execution with CLI interface
|
||||
2. **v2.0**: Conversational agent with natural language understanding
|
||||
|
||||
Both versions share the same execution layer but v2.0 adds a conversational layer for intent understanding and response generation.
|
||||
|
||||
### Target Users
|
||||
|
||||
- Obsidian users who maintain daily journals
|
||||
- Knowledge workers seeking automated content organization
|
||||
- Users who want to extract actionable insights from their daily notes
|
||||
- Teams looking for structured knowledge management workflows
|
||||
@@ -0,0 +1,141 @@
|
||||
# Project Structure
|
||||
|
||||
## Directory Organization
|
||||
|
||||
```
|
||||
journal_organizer/
|
||||
├── __init__.py # Package initialization
|
||||
├── __main__.py # Entry point for python -m execution
|
||||
├── main.py # v1.0 CLI entry and Agent initialization
|
||||
├── chat_main.py # v2.0 conversational interface entry
|
||||
├── agent_core.py # Core Agent framework (Command + Skill)
|
||||
├── config.py # Configuration management utilities
|
||||
├── server.py # Optional server interface
|
||||
├── config.example.yaml # Configuration template
|
||||
├── requirements.txt # Python dependencies
|
||||
├── README.md # v1.0 documentation
|
||||
├── README_V2.md # v2.0 documentation
|
||||
├── DEVELOPER_GUIDE.md # Development guidelines
|
||||
├── OBSIDIAN_INTEGRATION.md # Obsidian integration guide
|
||||
├── commands/ # Command implementations
|
||||
│ ├── __init__.py
|
||||
│ └── organize_command.py # Main journal organization command
|
||||
├── skills/ # Skill implementations
|
||||
│ ├── __init__.py
|
||||
│ ├── obsidian_skill.py # Obsidian API integration skills
|
||||
│ └── claude_skill.py # Claude AI integration skills
|
||||
└── conversation/ # v2.0 conversational layer
|
||||
├── __init__.py
|
||||
├── conversational_agent.py # Main conversational agent
|
||||
├── conversation_state.py # State management
|
||||
├── intent_understanding.py # Natural language understanding
|
||||
└── response_generator.py # Response generation
|
||||
```
|
||||
|
||||
## Core Components
|
||||
|
||||
### Agent Core (`agent_core.py`)
|
||||
- **Agent**: Main orchestrator class
|
||||
- **Command**: Abstract base for high-level operations
|
||||
- **Skill**: Abstract base for atomic operations
|
||||
- **SkillChain**: Sequential skill execution
|
||||
- **SkillResult**: Standardized result format
|
||||
- **CommandContext**: Execution context container
|
||||
|
||||
### Entry Points
|
||||
- **`__main__.py`**: Package entry point (`python -m journal_organizer`)
|
||||
- **`main.py`**: v1.0 CLI with argparse-based command handling
|
||||
- **`chat_main.py`**: v2.0 conversational interface with natural language processing
|
||||
|
||||
### Command Layer (`commands/`)
|
||||
Commands orchestrate multiple Skills to accomplish complex tasks:
|
||||
- **OrganizeCommand**: Main journal analysis and organization workflow
|
||||
- Commands inherit from `Command` base class
|
||||
- Commands register and coordinate Skills
|
||||
- Commands handle parameter validation and error recovery
|
||||
|
||||
### Skill Layer (`skills/`)
|
||||
Skills perform atomic operations:
|
||||
- **ObsidianReadSkill**: Read notes from Obsidian vault
|
||||
- **ObsidianWriteSkill**: Create/update notes in Obsidian
|
||||
- **ObsidianAppendSkill**: Append content to existing notes
|
||||
- **ObsidianListFilesSkill**: List files in vault directories
|
||||
- **ClaudeAnalyzeSkill**: Analyze journal content with Claude
|
||||
- **ClaudeTransformSkill**: Transform content formats with Claude
|
||||
|
||||
### Conversational Layer (`conversation/`)
|
||||
v2.0 natural language interface:
|
||||
- **ConversationalAgent**: Main conversation coordinator
|
||||
- **IntentUnderstanding**: Maps natural language to commands/parameters
|
||||
- **ConversationState**: Manages chat history and context
|
||||
- **ResponseGenerator**: Generates natural language responses
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Files and Modules
|
||||
- Snake_case for Python files: `organize_command.py`
|
||||
- Package names match directory structure
|
||||
- Skills end with `_skill.py`
|
||||
- Commands end with `_command.py`
|
||||
|
||||
### Classes
|
||||
- PascalCase for class names: `OrganizeCommand`, `ClaudeAnalyzeSkill`
|
||||
- Skills inherit from `Skill` base class
|
||||
- Commands inherit from `Command` base class
|
||||
- Result objects use `Result` suffix: `SkillResult`
|
||||
|
||||
### Methods and Variables
|
||||
- Snake_case for methods and variables: `execute_command`, `api_key`
|
||||
- Async methods use `async def` prefix
|
||||
- Private methods start with underscore: `_parse_response`
|
||||
|
||||
### Constants and Enums
|
||||
- UPPER_CASE for constants: `MAX_RETRIES`
|
||||
- PascalCase for Enums: `SkillType`, `TaskStatus`
|
||||
|
||||
## Configuration Structure
|
||||
|
||||
### YAML Configuration (`config.yaml`)
|
||||
```yaml
|
||||
obsidian:
|
||||
vault_path: "/path/to/vault"
|
||||
rest_api:
|
||||
url: "https://localhost:27123"
|
||||
api_key: "your-key"
|
||||
verify_ssl: false
|
||||
|
||||
claude:
|
||||
api_key: "${ANTHROPIC_API_KEY}"
|
||||
model: "claude-3-5-sonnet-20241022"
|
||||
max_tokens: 4096
|
||||
|
||||
journal:
|
||||
daily_notes_folder: "Daily"
|
||||
date_format: "YYYY-MM-DD"
|
||||
|
||||
output:
|
||||
experiences_folder: "Knowledge/Experiences"
|
||||
lessons_folder: "Knowledge/Lessons"
|
||||
# ... other output folders
|
||||
```
|
||||
|
||||
## Extension Patterns
|
||||
|
||||
### Adding New Skills
|
||||
1. Create new file in `skills/` directory
|
||||
2. Inherit from `Skill` base class
|
||||
3. Implement `execute()` method returning `SkillResult`
|
||||
4. Register skill in relevant commands
|
||||
|
||||
### Adding New Commands
|
||||
1. Create new file in `commands/` directory
|
||||
2. Inherit from `Command` base class
|
||||
3. Register required skills in `__init__()`
|
||||
4. Implement `execute()` method with skill orchestration
|
||||
5. Register command in `main.py` or `chat_main.py`
|
||||
|
||||
### Extending Conversational Capabilities
|
||||
1. Add new intent patterns in `intent_understanding.py`
|
||||
2. Update command keyword mappings
|
||||
3. Extend parameter extraction patterns
|
||||
4. Add response templates in `response_generator.py`
|
||||
@@ -0,0 +1,102 @@
|
||||
# Technology Stack
|
||||
|
||||
## Core Technologies
|
||||
|
||||
- **Python 3.8+**: Primary programming language
|
||||
- **asyncio**: Asynchronous programming for concurrent operations
|
||||
- **aiohttp**: HTTP client for API interactions
|
||||
- **PyYAML**: Configuration file management
|
||||
- **Anthropic Claude API**: AI-powered content analysis and understanding
|
||||
- **Obsidian Local REST API**: Integration with Obsidian vault
|
||||
|
||||
## Key Dependencies
|
||||
|
||||
```
|
||||
anthropic>=0.25.0 # Claude API client
|
||||
aiohttp>=3.9.0 # Async HTTP client
|
||||
pyyaml>=6.0 # YAML configuration parsing
|
||||
```
|
||||
|
||||
## Architecture Patterns
|
||||
|
||||
### Command + Skill Pattern
|
||||
- **Commands**: High-level operations that orchestrate multiple Skills
|
||||
- **Skills**: Atomic functional units for specific tasks (READ, WRITE, ANALYZE, TRANSFORM, INTEGRATE)
|
||||
- **Agent Core**: Base framework defining interfaces and interaction logic
|
||||
|
||||
### Async/Await Pattern
|
||||
- All Skills and Commands use async/await for non-blocking operations
|
||||
- HTTP API calls are asynchronous using aiohttp
|
||||
- Supports concurrent execution of multiple operations
|
||||
|
||||
### Configuration-Driven Design
|
||||
- YAML-based configuration files for all settings
|
||||
- Environment variable support for sensitive data
|
||||
- Separation of code and configuration
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Development Setup
|
||||
```bash
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Copy and configure settings
|
||||
cp config.example.yaml config.yaml
|
||||
# Edit config.yaml with your API keys and paths
|
||||
```
|
||||
|
||||
### Running the Application
|
||||
|
||||
#### v1.0 - Direct Commands
|
||||
```bash
|
||||
# Organize today's journal
|
||||
python -m journal_organizer organize
|
||||
|
||||
# Organize specific date
|
||||
python -m journal_organizer organize --date 2025-12-31
|
||||
|
||||
# List available commands
|
||||
python -m journal_organizer list
|
||||
|
||||
# Get help for specific command
|
||||
python -m journal_organizer help organize
|
||||
```
|
||||
|
||||
#### v2.0 - Conversational Interface
|
||||
```bash
|
||||
# Start interactive chat
|
||||
python -m journal_organizer.chat_main
|
||||
|
||||
# Single query mode
|
||||
python -m journal_organizer.chat_main --query "整理今天的日记"
|
||||
```
|
||||
|
||||
### Configuration
|
||||
```bash
|
||||
# Use custom config file
|
||||
python -m journal_organizer --config /path/to/config.yaml organize
|
||||
|
||||
# Set log level
|
||||
python -m journal_organizer --log-level DEBUG organize
|
||||
```
|
||||
|
||||
## API Integration Requirements
|
||||
|
||||
### Obsidian Setup
|
||||
1. Install "Local REST API" plugin in Obsidian
|
||||
2. Generate API key in plugin settings
|
||||
3. Configure API URL (default: https://localhost:27123)
|
||||
4. Disable SSL verification for local development
|
||||
|
||||
### Claude API Setup
|
||||
1. Obtain Anthropic API key
|
||||
2. Set environment variable: `ANTHROPIC_API_KEY`
|
||||
3. Configure model in config.yaml (default: claude-3-5-sonnet-20241022)
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
- All Skills return `SkillResult` objects with success/failure status
|
||||
- Comprehensive logging at DEBUG, INFO, WARNING, ERROR levels
|
||||
- Graceful degradation when external APIs are unavailable
|
||||
- SSL context configuration for local HTTPS endpoints
|
||||
Reference in New Issue
Block a user