journal_organizer/README.md

# Obsidian 智能日记整理 Agent

**版本**: 0.1.0

这是一个基于 Agent 架构的智能日记整理系统，专为 Obsidian 用户设计。它能够自动分析您的每日日记，提取关键信息（如经验、待办事项、问题等），并将其智能地整理到您的知识库中的指定位置。

该系统采用 Command + Skill 架构，具有高度的可扩展性和灵活性，并支持通过命令行触发，方便与 Obsidian 或其他工具集成。

## 系统特性

- **智能分析**：集成 Claude 3.5 Sonnet 模型，深度理解日记内容并提取结构化信息。
- **自动化整理**：自动将提取的内容创建为新的笔记，并放置在预设的文件夹中。
- **双向链接**：在生成的笔记中自动添加指向原始日记的链接，方便溯源。
- **Agent 架构**：采用 Command + Skill 模式，逻辑清晰，易于扩展新功能。
- **命令行驱动**：通过标准命令行接口（CLI）操作，易于集成和自动化。
- **高度可配置**：所有关键参数（如 API 密钥、文件夹路径、分析规则）均可通过配置文件管理。
- **通用性设计**：核心框架与具体实现分离，可兼容 Claude Code、OpenCode 等多种 Agent 环境。

## 系统架构

系统由以下核心组件构成：

1.  **Agent Core**：定义了 `Agent`、`Command` 和 `Skill` 的基础接口和交互逻辑。
2.  **Skills**：原子化的功能单元，负责执行具体任务，如 `ObsidianReadSkill`（读取笔记）和 `ClaudeAnalyzeSkill`（分析内容）。
3.  **Commands**：用户可执行的命令，负责编排一个或多个 Skill 来完成复杂任务，如 `OrganizeCommand`。
4.  **CLI 入口**：提供一个命令行界面，用于接收用户指令并驱动 Agent 执行相应命令。
5.  **配置文件**：使用 YAML 文件管理所有配置，实现代码与配置分离。

```mermaid
graph TD
    subgraph User Interface
        CLI[命令行接口]
        Obsidian[Obsidian (via shell command)]
    end

    subgraph Agent System
        AgentCore[Agent Core]
        CLI --> AgentCore
        Obsidian --> AgentCore

        AgentCore -- dispatches --> Commands
        subgraph Commands
            OrganizeCmd[Organize Command]
        end

        Commands -- orchestrates --> Skills
        subgraph Skills
            ReadNote[Obsidian Read Skill]
            AnalyzeNote[Claude Analyze Skill]
            WriteNote[Obsidian Write Skill]
        end
    end

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

    ReadNote -- HTTP --> ObsidianAPI
    WriteNote -- HTTP --> ObsidianAPI
    AnalyzeNote -- HTTP --> ClaudeAPI
```

## 安装指南

### 1. 先决条件

- **Python 3.8+**
- **Obsidian**
- **Obsidian 插件**: `Local REST API`

### 2. 安装 Local REST API 插件

1.  在 Obsidian 中，进入 `设置` > `第三方插件`。
2.  关闭 `安全模式`。
3.  点击 `浏览社区插件`，搜索 `Local REST API` 并安装。
4.  启用插件，并在插件设置页面生成一个 API 密钥。请妥善保管此密钥。

### 3. 安装 Agent

1.  克隆或下载本项目到您的本地计算机。

    ```bash
    git clone <repository_url> journal_organizer
    cd journal_organizer
    ```

2.  安装 Python 依赖。

    ```bash
    pip install -r requirements.txt
    ```

## 配置指南

1.  **复制配置文件**

    将 `config.example.yaml` 复制为 `config.yaml`。

    ```bash
    cp config.example.yaml config.yaml
    ```

2.  **编辑配置文件**

    打开 `config.yaml` 并根据您的环境填写以下关键信息：

    -   `obsidian.vault_path`: 您的 Obsidian vault 在计算机上的绝对路径。
    -   `obsidian.rest_api.api_key`: 您在 `Local REST API` 插件中生成的 API 密钥。
    -   `claude.api_key`: 您的 Anthropic API 密钥。建议使用环境变量 `ANTHROPIC_API_KEY` 来设置。
    -   `journal` 和 `output` 部分的文件夹路径，确保它们在您的 vault 中存在。

    **安全提示**: 请勿将包含敏感密钥的 `config.yaml` 文件提交到公共代码仓库。

## 使用方法

您可以通过命令行在项目根目录下运行 Agent。

### 整理今天的日记

```bash
python -m journal_organizer organize
```

### 整理指定日期的日记

```bash
python -m journal_organizer organize --date 2025-12-31
```

### 在 Obsidian 中调用

您可以使用 `Templater` 或 `QuickAdd` 等插件，通过执行 Shell 命令来调用 Agent。

例如，在 `Templater` 中可以这样设置：

```javascript
<%*
const command = `cd /path/to/journal_organizer && python -m journal_organizer organize --date ` + tp.file.title;
const result = await tp.user.exec(command);
tp.obsidian.Notice.now(result, 10000);
%>
```

### 查看帮助

```bash
# 查看所有命令
python -m journal_organizer --help

# 查看特定命令的帮助
python -m journal_organizer organize --help
```

## 项目结构

```
journal_organizer/
├── commands/                # Command 模块
│   ├── __init__.py
│   └── organize_command.py  # 日记整理命令
├── skills/                  # Skill 模块
│   ├── __init__.py
│   ├── claude_skill.py      # Claude AI 相关 Skill
│   └── obsidian_skill.py    # Obsidian API 相关 Skill
├── __init__.py
├── agent_core.py            # Agent 核心框架
├── main.py                  # 命令行入口和 Agent 初始化
├── config.example.yaml      # 配置文件示例
├── requirements.txt         # Python 依赖
└── README.md                # 本文档
```

## 如何扩展

本系统基于 Command + Skill 架构，您可以轻松地添加新的功能。

### 添加一个新的 Skill

1.  在 `skills/` 目录下创建一个新的 Python 文件，例如 `my_new_skill.py`。
2.  在该文件中，创建一个继承自 `Skill` 的类。
3.  实现 `execute` 方法，该方法是 Skill 的核心逻辑。

    ```python
    from ..agent_core import Skill, SkillType, SkillResult, CommandContext

    class MyNewSkill(Skill):
        def __init__(self):
            super().__init__(name="my_new_skill", skill_type=SkillType.TRANSFORM, description="我的新技能")

        async def execute(self, context: CommandContext, **kwargs) -> SkillResult:
            # 在这里实现您的逻辑
            return SkillResult(success=True, data="新技能执行成功")
    ```

### 添加一个新的 Command

1.  在 `commands/` 目录下创建一个新的 Python 文件。
2.  创建一个继承自 `Command` 的类。
3.  在 `__init__` 方法中注册所需的 Skills。
4.  实现 `execute` 方法，编排 Skills 来完成任务。
5.  在 `main.py` 的 `_register_commands` 方法中注册您的新命令。

## 许可证

本项目采用 MIT 许可证。