Metadata-Version: 2.4
Name: finnie
Version: 0.0.7
Summary: Finnie is a **personal assistant** that runs in your own environment. It talks to you over multiple channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.) and runs scheduled tasks according to your configuration. **What it can do is driven by Skills — the possibilities are open-ended.** Built-in skills include cron, PDF/Office handling, news digest, file reading, and more; you can add custom skills. All data and tasks run on your machine; no third-party hosting.
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: discord-py>=2.3
Requires-Dist: dingtalk-stream>=0.24.3
Requires-Dist: uvicorn>=0.40.0
Requires-Dist: apscheduler<4,>=3.11.2
Requires-Dist: playwright>=1.49.0
Requires-Dist: questionary>=2.1.1
Requires-Dist: mss>=9.0.0
Requires-Dist: reme-ai==0.3.0.0
Requires-Dist: transformers>=4.30.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-socks>=2.5.3
Requires-Dist: onnxruntime<1.24
Requires-Dist: lark-oapi>=1.5.3
Requires-Dist: langchain>=1.2
Requires-Dist: langgraph>=1.0
Requires-Dist: langchain-openai>=1.1
Requires-Dist: mcp>=1.26
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20
Requires-Dist: googleapis-common-protos>=1.62
Provides-Extra: dev
Requires-Dist: pytest>=8.3.5; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pre-commit>=4.2.0; extra == "dev"
Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
Provides-Extra: ollama
Requires-Dist: ollama>=0.4.0; extra == "ollama"
Provides-Extra: local
Requires-Dist: huggingface_hub>=0.20.0; extra == "local"
Provides-Extra: llamacpp
Requires-Dist: finnie[local]; extra == "llamacpp"
Requires-Dist: llama-cpp-python>=0.3.0; extra == "llamacpp"
Provides-Extra: mlx
Requires-Dist: finnie[local]; extra == "mlx"
Requires-Dist: mlx-lm>=0.10.0; extra == "mlx"

# Finnie — 自托管 AI 个人助手

> **Finnie** 是一个运行在你自己设备上的 AI 个人助手。它通过多种聊天渠道（钉钉、飞书、QQ、Discord、iMessage、Web 控制台）与你对话，还能执行定时任务。所有能力由 **Skills（技能）** 驱动 —— 一套可扩展的模块系统，既有内置技能也支持用户自建。全部数据保存在本地，无需第三方托管。

---

## 📋 目录

- [功能特性](#-功能特性)
- [环境要求](#-环境要求)
- [快速开始](#-快速开始)
  - [1. 克隆仓库](#1-克隆仓库)
  - [2. 安装 Python 环境](#2-安装-python-环境)
  - [3. 初始化工作区](#3-初始化工作区)
  - [4. 启动 Finnie](#4-启动-finnie)
- [配置指南](#-配置指南)
  - [选择 LLM 模型](#选择-llm-模型)
  - [配置聊天渠道](#配置聊天渠道)
  - [管理技能](#管理技能)
  - [配置定时任务](#配置定时任务)
  - [MCP 服务集成](#mcp-服务集成)
- [Web 控制台](#-web-控制台)
- [CLI 命令参考](#-cli-命令参考)
- [内置技能一览](#-内置技能一览)
- [工作区目录结构](#-工作区目录结构)
- [系统架构](#-系统架构)
- [前端开发](#-前端开发)
- [代码质量与测试](#-代码质量与测试)
- [常见问题](#-常见问题)
- [许可证](#-许可证)

---

## ✨ 功能特性

| 特性 | 说明 |
|------|------|
| **多渠道支持** | 钉钉、飞书、QQ、Discord、iMessage、Web 控制台，一个助手多端连接 |
| **可扩展技能系统** | 内置 PDF/Office 处理、定时任务、新闻摘要、浏览器自动化、邮件管理等技能；支持用户自定义创建技能 |
| **多 LLM 供应商** | OpenAI、DashScope（阿里千问）、Ollama、本地模型（LLaMA-CPP、MLX）等 |
| **MCP 集成** | 支持 Model Context Protocol 服务接入，热加载 |
| **定时任务** | 基于 APScheduler 的 Cron 任务管理，让助手自动执行周期性工作 |
| **本地优先** | 所有配置、记忆、数据存储在 `~/.finnie/`，数据不离开你的设备 |

---

## 🔧 环境要求

在开始之前，请确保你的系统满足以下条件：

| 依赖 | 版本要求 | 说明 |
|------|---------|------|
| **Python** | 3.10 – 3.13 | 推荐使用 3.12 |
| **Node.js** | 18+ | 仅在需要前端开发时安装 |
| **操作系统** | macOS / Linux / Windows | 均支持，macOS 可额外使用 MLX 本地推理 |

---

## 🚀 快速开始

### 1. 克隆仓库

```bash
git clone git@git.woa.com:orcakit/finnie.git
cd finnie
```

### 2. 安装 Python 环境

```bash
# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
# macOS / Linux:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# 安装 Finnie
pip install ".[dev]"
```

#### 可选依赖

根据你的需求安装额外的本地推理后端：

```bash
# LLaMA-CPP 本地推理（支持 macOS / Linux / Windows）
pip install ".[llamacpp]"

# MLX 本地推理（仅 macOS Apple Silicon）
pip install ".[mlx]"

# Ollama 集成
pip install ".[ollama]"
```

### 3. 初始化工作区

首次使用时需要执行初始化，该命令会在 `~/.finnie/` 下创建配置文件和目录结构：

```bash
finnie init
```

初始化过程中，CLI 将以**交互式向导**引导你完成以下配置：

1. **选择语言**：中文 / English
2. **选择 LLM 供应商**：OpenAI、DashScope（阿里千问）、Ollama、本地模型等
3. **填写 API Key**：根据选择的供应商输入对应的密钥
4. **选择模型**：从供应商的可用模型列表中选择

### 4. 启动 Finnie

```bash
# 启动应用（后端 + Web 控制台）
finnie run
```

或通过 Python 模块启动：

```bash
python -m finnie run
```

启动后：
- 🌐 **Web 控制台**：`http://localhost:80`
- 🔌 **后端 API**：`http://localhost:8088`

你现在可以打开浏览器访问 Web 控制台，开始与 Finnie 对话了！

---

## ⚙️ 配置指南

所有配置存储在 `~/.finnie/config.json` 中，你可以通过 CLI 命令或直接编辑文件来修改配置。

### 选择 LLM 模型

Finnie 支持多种 LLM 供应商，使用以下命令管理：

```bash
# 查看当前模型配置
finnie models

# 交互式切换供应商/模型
finnie models switch
```

支持的供应商：

| 供应商 | 说明 | 需要 API Key |
|--------|------|:----------:|
| OpenAI | GPT-4o、GPT-4、GPT-3.5 等 | ✅ |
| DashScope | 阿里千问系列 | ✅ |
| Ollama | 本地 Ollama 服务 | ❌ |
| LLaMA-CPP | 本地 GGUF 模型推理 | ❌ |
| MLX | macOS Apple Silicon 本地推理 | ❌ |

### 配置聊天渠道

使用以下命令安装和配置聊天渠道：

```bash
# 安装渠道（交互式选择）
finnie channels install
```

各渠道的配置要求：

| 渠道 | 需要的凭证 |
|------|-----------|
| **钉钉** | App Key、App Secret |
| **飞书** | App ID、App Secret |
| **QQ** | Bot AppID、Token |
| **Discord** | Bot Token |
| **iMessage** | macOS 本地 iMessage（无需额外配置） |
| **Web 控制台** | 默认启用，无需配置 |

### 管理技能

```bash
# 安装/启用技能
finnie skills install

# 查看已安装的技能
finnie skills
```

技能安装后会存放在 `~/.finnie/active_skills/` 目录中。你也可以在 `~/.finnie/customized_skills/` 中创建自定义技能。

### 配置定时任务

Finnie 支持定时让助手自动执行任务，例如"每天早上 8 点发送新闻摘要"：

```bash
# 管理定时任务
finnie crons

# 查看已有定时任务
finnie crons list

# 添加新定时任务
finnie crons add
```

定时任务定义存储在 `~/.finnie/jobs.json` 中。

### MCP 服务集成

Finnie 支持通过 Model Context Protocol（MCP）接入外部工具服务，配置方法：

1. 在 `~/.finnie/config.json` 中的 `mcp_servers` 字段添加 MCP 服务配置
2. Finnie 支持 MCP 服务的**热加载**，修改配置后无需重启即可生效

---

## 🖥️ Web 控制台

启动 Finnie 后，在浏览器中访问 `http://localhost:80` 即可使用 Web 控制台。

Web 控制台提供以下功能：
- 💬 **对话界面**：与 Finnie 进行实时对话
- ⚙️ **配置管理**：在线修改供应商、模型、渠道等设置
- 🧩 **技能管理**：查看、启用、禁用技能
- ⏰ **定时任务**：可视化管理 Cron 任务
- 🔗 **MCP 服务**：管理已接入的 MCP 工具服务
- 📊 **环境变量**：管理持久化的环境变量

---

## 📖 CLI 命令参考

| 命令 | 说明 |
|------|------|
| `finnie init` | 初始化 `~/.finnie/` 工作区，引导完成首次配置 |
| `finnie run` | 启动 Finnie（后端 API + Web 控制台 + 所有已配置渠道） |
| `finnie channels install` | 安装并配置聊天渠道 |
| `finnie skills install` | 安装技能 |
| `finnie models` | 管理 LLM 模型供应商与模型选择 |
| `finnie crons` | 管理定时任务 |
| `finnie chats` | 管理对话历史 |
| `finnie env` | 管理持久化环境变量 |
| `finnie clean` | 清理临时文件和缓存 |
| `finnie uninstall` | 卸载 Finnie 并清理工作区 |

全局选项：

```bash
finnie --host 0.0.0.0 --port 9090 run   # 自定义主机和端口
finnie -h                                 # 查看帮助信息
```

---

## 🧩 内置技能一览

| 技能 | 功能说明 |
|------|---------|
| `cron` | 创建和管理定时任务，让 Finnie 定期自动执行指定工作 |
| `pdf` | PDF 文档的提取、编辑、合并 |
| `xlsx` | Excel 电子表格的读取和写入 |
| `pptx` | PowerPoint 演示文稿的读取和创建 |
| `docx` | Word 文档的读取和编辑 |
| `file_reader` | 读取文本、JSON、YAML 等格式的文件 |
| `news` | 获取新闻并生成摘要 |
| `browser_visible` | 浏览器自动化操作与网页截图 |
| `himalaya` | 基于 IMAP 协议的邮件管理 |
| `skill-creator` | 帮助你创建自定义技能的内置工具 |
| `find-skills` | 搜索和发现更多可用技能 |

> 💡 **提示**：你可以通过 `skill-creator` 技能让 Finnie 帮你创建全新的自定义技能，无需手动编写代码。

---

## 📁 工作区目录结构

`finnie init` 执行后会在用户目录下创建以下结构：

```
~/.finnie/
├── config.json              # 核心配置文件（供应商、模型、渠道凭证等）
├── jobs.json                # 定时任务定义
├── chats.json               # 对话历史记录
├── envs.json                # 持久化环境变量
├── active_skills/           # 已启用的技能
├── customized_skills/       # 用户自定义技能
├── custom_channels/         # 自定义渠道插件
└── memory/
    ├── MEMORY.md            # 长期记忆（Finnie 从对话中学到的信息）
    ├── PROFILE.md           # 用户画像（你的偏好和习惯）
    └── YYYY-MM-DD.md        # 每日笔记
```

### 关键文件说明

- **`config.json`**：最核心的配置文件，包含 LLM 供应商设置、API Key、模型选择、渠道凭证等。建议通过 CLI 命令修改，也可以直接编辑。
- **`memory/`**：Finnie 的记忆系统。MEMORY.md 存储长期记忆，PROFILE.md 存储用户画像，每日笔记自动记录。
- **`active_skills/`**：将技能文件夹放入此目录即可启用对应技能。
- **`customized_skills/`**：你自己创建的技能存放在这里。

---

## 🏗️ 系统架构

```
┌──────────────────────────────────────────────────────┐
│                   Finnie 应用                         │
│                                                      │
│  React 控制台 (端口 80) ◄── REST ──► FastAPI (8088)  │
│                                                      │
│  渠道集成 (钉钉、飞书、QQ、Discord、iMessage…)        │
│                                                      │
│  Agent 引擎: ReAct Agent → 技能中心 → LLM            │
│                                                      │
│  配置 / 记忆 / 任务 (存储在 ~/.finnie/)               │
└──────────────────────────────────────────────────────┘
```

**请求处理流程：**

```
用户 (通过渠道) → ChannelManager → Runner → ReAct Agent
                                                 ↓
                                          LLM 供应商
                                                 ↓
                                          技能执行器
                                                 ↓
                                       响应 → 返回渠道
```

---

## 🖥️ 前端开发

如果你需要参与 Web 控制台的前端开发：

```bash
# 进入前端项目目录
cd console

# 安装依赖
npm install

# 启动开发服务器（访问 http://localhost:80）
npm run dev

# 构建生产版本
npm run build

# 代码检查（ESLint + TypeScript）
npm run lint

# 代码格式化（Prettier）
npm run format
```

前端技术栈：React + TypeScript + Vite + Ant Design

---

## ✅ 代码质量与测试

```bash
# 代码格式化（行宽 79 字符）
python -m black src/finnie/

# Lint 检查
flake8 src/finnie/

# 类型检查
mypy src/finnie/

# 运行 pre-commit 钩子
pre-commit run --all-files

# 运行全部测试
pytest

# 详细模式运行，遇到首个失败即停止
pytest -xvs
```

---

## ❓ 常见问题

### Q: 启动时端口被占用怎么办？

使用自定义端口启动：

```bash
finnie --port 9090 run
```

### Q: 如何切换语言？

重新运行初始化命令，或直接编辑 `~/.finnie/config.json` 中的 `language` 字段。

### Q: 如何使用本地模型？

1. 安装对应的本地推理后端：
   ```bash
   pip install ".[llamacpp]"   # 或 ".[mlx]"（仅 macOS）
   ```
2. 通过 `finnie models` 命令切换到本地模型供应商
3. 选择或下载要使用的模型

### Q: 如何创建自定义技能？

有两种方式：
1. **让 Finnie 帮你创建**：在对话中告诉 Finnie 你需要什么技能，内置的 `skill-creator` 会自动生成
2. **手动创建**：在 `~/.finnie/customized_skills/` 目录下创建技能文件夹，包含 `SKILL.md` 描述文件

### Q: 数据存储在哪里？

所有数据都存储在本地的 `~/.finnie/` 目录下，不会上传到任何第三方服务器。你可以随时备份或迁移这个目录。

---

## 📄 许可证

详见 [LICENSE](LICENSE) 文件。
