journal_organizer/README_V2.md

# Obsidian 智能日记整理 Agent v2.0 - 对话式

**版本**: 2.0.0

这是一个基于 **对话式 Agent 架构** 的智能日记整理系统，专为 Obsidian 用户设计。它能够通过自然语言对话，理解您的需求，自动分析每日日记，提取关键信息，并将其智能地整理到您的知识库中。

## v2.0 新特性：对话式交互

- **自然语言理解**：您可以直接用自然语言与 Agent 对话，例如“帮我整理一下昨天的日记”。
- **多轮对话**：支持上下文感知，可以进行多轮对话来澄清和确认您的需求。
- **智能建议**：根据您的使用习惯，主动推荐可能的操作。
- **交互式界面**：提供一个命令行聊天界面，支持实时交互和反馈。

## 系统架构

系统采用分层架构，将对话逻辑与业务执行分离：

1.  **对话层** (`conversation/`)
    - **意图理解** (`intent_understanding.py`)：使用 Claude API 理解用户意图。
    - **对话状态管理** (`conversation_state.py`)：管理对话历史和上下文。
    - **响应生成** (`response_generator.py`)：生成自然语言响应。
    - **对话式 Agent** (`conversational_agent.py`)：协调对话层的所有模块。

2.  **执行层** (Command + Skill)
    - 沿用 v1.0 的 Command + Skill 架构，负责执行具体的业务逻辑。

```mermaid
graph TD
    subgraph User Interface
        ChatCLI[命令行聊天界面]
        ObsidianPlugin[Obsidian 插件]
    end

    subgraph Conversational Layer
        ConvAgent[对话式 Agent]
        ChatCLI --> ConvAgent
        ObsidianPlugin --> ConvAgent

        ConvAgent -- uses --> IntentUnderstanding[意图理解]
        ConvAgent -- uses --> ConversationState[对话状态管理]
        ConvAgent -- uses --> ResponseGenerator[响应生成]
    end

    subgraph Execution Layer
        CommandAgent[Command Agent]
        ConvAgent -- dispatches to --> CommandAgent

        CommandAgent -- orchestrates --> Skills[Skills]
    end

    subgraph External Services
        ClaudeAPI[Claude API]
        ObsidianAPI[Obsidian Local REST API]
    end

    IntentUnderstanding -- HTTP --> ClaudeAPI
    ResponseGenerator -- HTTP --> ClaudeAPI
    Skills -- HTTP --> ObsidianAPI
```

## 安装与配置

安装和配置过程与 v1.0 相同。请参考 [README.md](README.md)。

## 使用方法

### 启动交互式对话

```bash
python -m journal_organizer.chat_main
```

启动后，您将进入一个交互式的命令行聊天界面：

```
============================================================
Obsidian 智能日记整理 Agent - 对话模式
============================================================

🤖 助手: 👋 欢迎使用 Obsidian 日记整理助手！我可以帮您整理日记、分析内容、导出总结等。请告诉我您想要做什么？

👤 您: 
```

### 示例对话

```
👤 您: 帮我整理一下昨天的日记

⏳ 处理中...

🤖 助手: ✓ 已成功整理您昨天的日记。提取了 5 条经验、3 条待办事项和 2 个问题。

💡 您可以尝试:
   1. 分析本周的主题
   2. 导出月度总结

👤 您: 分析一下这周的主题

⏳ 处理中...

🤖 助手: ✓ 分析完成！本周的主题主要集中在项目管理和技术学习两个方面。
```

### 系统命令

在对话界面中，您可以使用以下系统命令：

- `help` / `帮助`：显示帮助信息
- `history` / `历史`：显示对话历史
- `status` / `状态`：显示当前状态
- `clear` / `清除`：清除对话历史
- `exit` / `quit` / `退出`：退出程序

### 处理单个查询

```bash
python -m journal_organizer.chat_main --query "整理今天的日记"
```

此命令将直接输出 JSON 格式的结果，方便脚本调用。

## 项目结构

```
journal_organizer/
├── conversation/            # 对话层模块
│   ├── __init__.py
│   ├── conversational_agent.py
│   ├── conversation_state.py
│   ├── intent_understanding.py
│   └── response_generator.py
├── commands/
├── skills/
├── agent_core.py
├── main.py
├── chat_main.py             # 对话式 Agent 入口
├── ... (其他文件)
```

## 开发者指南

### 扩展对话能力

1.  **添加新的意图**：在 `intent_understanding.py` 的 `command_keywords` 中添加新的命令和关键词。
2.  **添加新的参数提取**：在 `parameter_patterns` 中添加新的正则表达式。
3.  **自定义响应**：修改 `response_generator.py` 中的提示来改变响应风格。

### 集成到 Obsidian 插件

您可以使用 Obsidian 插件的 `Modal` 来创建一个对话窗口，并通过 `child_process` 调用 `chat_main.py` 来与 Agent 交互。

```typescript
// Obsidian 插件示例
import { App, Modal, Plugin } from 'obsidian';
import { spawn } from 'child_process';

class ChatModal extends Modal {
    constructor(app: App) {
        super(app);
    }

    onOpen() {
        // 创建对话界面
        // ...
    }

    async sendMessage(message: string) {
        const agentProcess = spawn('python', ['-m', 'journal_organizer.chat_main', '--query', message]);

        agentProcess.stdout.on('data', (data) => {
            const response = JSON.parse(data.toString());
            // 显示响应
        });

        agentProcess.stderr.on('data', (data) => {
            // 处理错误
        });
    }
}
```

## 许可证

本项目采用 MIT 许可证。