Finnie — 自托管 AI 个人助手

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

---

📋 目录

• 功能特性
• 环境要求
• 快速开始
  • 1. 克隆仓库
  • 2. 安装 Python 环境
  • 3. 初始化工作区
  • 4. 启动 Finnie
• 配置指南
  • 选择 LLM 模型
  • 配置聊天渠道
  • 管理技能
  • 配置定时任务
  • MCP 服务集成
• Web 控制台
• 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. 克隆仓库

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

2. 安装 Python 环境

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

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

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

可选依赖

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

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

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

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

3. 初始化工作区

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

finnie init

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

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

4. 启动 Finnie

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

或通过 Python 模块启动：

python -m finnie run

启动后：

• 🌐 Web 控制台：http://localhost:80
• 🔌 后端 API：http://localhost:8088

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

---

⚙️ 配置指南

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

选择 LLM 模型

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

# 查看当前模型配置
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 本地推理	❌

配置聊天渠道

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

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

各渠道的配置要求：

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

管理技能

# 安装/启用技能
finnie skills install

# 查看已安装的技能
finnie skills

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

配置定时任务

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

# 管理定时任务
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 并清理工作区

全局选项：

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 控制台的前端开发：

# 进入前端项目目录
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

---

✅ 代码质量与测试

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

# Lint 检查
flake8 src/finnie/

# 类型检查
mypy src/finnie/

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

# 运行全部测试
pytest

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

---

❓ 常见问题

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

使用自定义端口启动：

finnie --port 9090 run

Q: 如何切换语言？

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

Q: 如何使用本地模型？

1. 安装对应的本地推理后端：

   pip install ".[llamacpp]"   # 或 ".[mlx]"（仅 macOS）
   

2. 通过 finnie models 命令切换到本地模型供应商
3. 选择或下载要使用的模型

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

有两种方式：

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

Q: 数据存储在哪里？

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

---

📄 许可证

详见 LICENSE 文件。