内容
<p align="center">
<img src="web/static/favicon.svg" width="64" height="64" alt="konbu">
</p>
<h1 align="center">konbu</h1>
<p align="center">
<strong>您的个人数字计划工具，由 AI 管家管理。</strong><br>
命令行界面 · MCP · 可自行托管 · AI 原生
</p>
<p align="center">
一个 Go 语言编译的二进制文件，将您的备忘录、待办事项、时间表和表格绑定到一个计划工具中 - 可以从一个地方搜索，由 AI 管理。<br>
连接 Claude、Cursor 或任何 MCP 客户端到您的数据。
</p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
<a href="https://github.com/krtw00/konbu/actions"><img src="https://github.com/krtw00/konbu/actions/workflows/deploy.yml/badge.svg" alt="部署"></a>
</p>
<p align="center"><a href="README.ja.md">日本語</a> | <a href="#">简体中文</a></p>
<p align="center"><img src="docs/screenshot.png" width="800" alt="konbu screenshot"></p>
<p align="center"><img src="docs/demo.gif" width="800" alt="AI 聊天演示 - 使用自然语言管理日程和待办事项"></p>
---
## 尝试使用
- **云端** -- 立即在 [konbu-cloud.codenica.dev](https://konbu-cloud.codenica.dev) 使用（免费，无需设置）
- **自行托管** -- 在您的服务器上使用 Docker 运行（参见下方）
## 什么是 konbu？
konbu 是一个 **个人数字计划工具** - 一个类似 Filofax 的系统计划工具的数字化版本。一个可自行托管的 Go 语言二进制文件，将您的备忘录、待办事项、时间表和结构化表格绑定到一个笔记本中，由 AI 管家管理，并通过一个搜索界面显示所有内容。 它是您独有的 - 永远不会与他人共享。 不是 Notion + Todoist + 日历的替代品 - 而是 **搜索四个应用程序以找到一个项目** 的替代品。
不同之处：
- **原生 MCP 服务器 + 命令行客户端** -- 为 AI 管家（Claude / Cursor / 任何 MCP 客户端）或 shell / 脚本提供两个并行路由，以操作您的计划工具。
- **跨资源全文搜索** -- 在备忘录、待办事项、事件和结构化表格中进行一次查询。 这是核心用户体验，而不是侧面功能。
- **结构化表格**（= 表格备忘录，计划）-- 跟踪血压、家庭预算或库存。 Markdown 无法表达这些；表格可以。
- **自带密钥的 AI 聊天** -- 携带您自己的 OpenAI/Anthropic API 密钥，或使用附带的免费层。
- **设计为个人** -- 一个笔记本，仅供您使用。 从外部拉取（Google 日历），但绝不泄露。
- **可自行托管** -- 一个 Go 语言二进制文件，Docker 组合或使用托管版本。
结束将您的日常事务分散在四个不同应用程序中的状态。
## 功能
- **跨资源全文搜索** -- 在备忘录、待办事项、事件和结构化表格中进行一次查询（核心用户体验）
- **命令行界面和 MCP 服务器** -- 内置命令行客户端和 MCP 服务器。像 Claude 和 Cursor 这样的 AI 代理可以直接读取和写入您的数据
- **AI 代理聊天** - “将杂货添加到我的待办事项中” “明天我的日程是什么？” 使用自然语言。 支持自带密钥，包含免费层
- **备忘录** -- 带有标签、实时预览的 Markdown 笔记
- **待办事项** -- 内联任务创建，带有截止日期、标签和备注
- **日历** -- 月视图，带有事件 CRUD 和 iCal 导入（个人，所有者专用）
- **结构化表格**（= 表格备忘录，计划）-- 跟踪结构化数据（血压、家庭预算、库存）为行 × 列
- **导出/导入** -- JSON 导出、Markdown ZIP 导出、iCal 导入
- **国际化** -- 英语和日语
## 快速开始
```bash
cp .env.example .env
docker compose up -d
```
打开 `http://localhost:8080` 并创建您的帐户。 开发组合文件设置 `DEV_USER=dev@local` 以跳过注册。
### 生产环境（使用 Traefik）
```bash
# 编辑 .env 文件，填写真实凭证和您的域名
docker compose -f docker-compose.prod.yml up -d
```
### 原生（无需 Docker）
```bash
# 要求：Go 1.25+，Node.js 22+，PostgreSQL 16+
# 构建前端
cd web/frontend && npm ci && npm run build && cd ../..
# 构建服务器
go build -o bin/server ./cmd/server
# 启动（在启动时自动运行所有 SQL 迁移）
DATABASE_URL="postgres://..." SESSION_SECRET="..." ./bin/server
```
## 配置
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `DATABASE_URL` | 是 | - | PostgreSQL 连接字符串 |
| `SESSION_SECRET` | 是 | 开发环境默认值 | 会话签名密钥 |
| `PORT` | 否 | `8080` | 服务器端口 |
| `DEV_USER` | 否 | - | 自动登录为此电子邮件（仅限开发环境） |
| `OPEN_REGISTRATION` | 否 | - | 设置为 `true` 以允许任何人注册（适用于云端） |
| `BASE_URL` | 否 | - | 用于 OAuth 回调的公共应用程序 URL |
| `GOOGLE_CLIENT_ID` | 否 | - | 启用 Google OAuth 登录 |
| `GOOGLE_CLIENT_SECRET` | 否 | - | 启用 Google OAuth 登录 |
| `WEBHOOK_SECRET` | 否 | - | GitHub Sponsors 网络钩子密钥 |
| `STRIPE_SECRET_KEY` | 否 | - | 启用 Stripe 结账和订阅计费 |
| `STRIPE_WEBHOOK_SECRET` | 否 | - | 验证传入的 Stripe 网络钩子事件 |
| `STRIPE_PRICE_MONTHLY` | 否 | - | 用于每月专业版结账的 Stripe 价格 ID |
| `STRIPE_PRICE_YEARLY` | 否 | - | 用于年度专业版结账的 Stripe 价格 ID |
| `GITHUB_FEEDBACK_TOKEN` | 否 | - | 用于创建匿名反馈问题的 GitHub 令牌 |
| `GITHUB_FEEDBACK_REPO` | 否 | - | 接收反馈问题的存储库，例如 `krtw00/konbu` |
| `GITHUB_FEEDBACK_LABELS` | 否 | - | 添加到转发反馈问题的逗号分隔标签 |
| `AI_ENCRYPTION_KEY` | 否 | - | 64 个十六进制字符，用于加密自带 AI 密钥 |
| `DEFAULT_AI_PROVIDER` | 否 | `openai` | 服务器端免费层 AI 提供商 |
| `DEFAULT_AI_API_KEY` | 否 | - | 服务器端免费层 AI 密钥 |
| `DEFAULT_AI_ENDPOINT` | 否 | - | 覆盖免费层提供商端点 |
| `DEFAULT_AI_MODEL` | 否 | - | 覆盖免费层提供商模型 |
| `R2_ACCESS_KEY_ID` | 否 | - | 附件上传凭证 |
| `R2_SECRET_ACCESS_KEY` | 否 | - | 附件上传凭证 |
| `R2_ENDPOINT` | 否 | Cloudflare R2 默认值 | 附件存储端点 |
| `R2_BUCKET` | 否 | `konbu-attachments` | 附件存储桶 |
| `R2_PUBLIC_URL` | 否 | - | 附件的可选公共基准 URL |
| `SMTP_HOST` | 否 | - | 用于提醒邮件的 SMTP 中继主机（例如 `smtp-relay.brevo.com`）。 除非设置了所有五个 `SMTP_*` 变量，否则通知将被禁用。 |
| `SMTP_PORT` | 否 | - | SMTP 中继端口（通常为 `587`，使用 STARTTLS） |
| `SMTP_USERNAME` | 否 | - | SMTP 中继登录 |
| `SMTP_PASSWORD` | 否 | - | SMTP 中继密码/API 密钥 |
| `SMTP_FROM` | 否 | - | 发出提醒邮件的发件地址 |
| `NOTIFICATION_TICK_INTERVAL` | 否 | `1m` | 通知扫描间隔（Go 时长，例如 `30s`，`2m`） |
### 提醒/通知
当上述 `SMTP_*` 变量全部设置后，服务器会启动一个单独的进程扫描循环，向即将到来的事件和到期的待办事项发送电子邮件提醒。 每个用户通过 **设置** (`user_settings.notifications.enabled = true`) 选择加入并可以覆盖收件人电子邮件、提前时间、到期时间和时区。
通知是 **仅限服务器的功能** - 它们在 API 服务器进程中运行，需要 PostgreSQL。MCP `--standalone` 模式（SQLite） **不** 发送提醒。
### Docker Compose（生产环境）变量
| 变量 | 描述 |
|---|---|
| `POSTGRES_PASSWORD` | PostgreSQL 密码 |
| `KONBU_DOMAIN` | Traefik TLS 路由的域名 |
## 命令行界面
命令行界面是一个独立的客户端，通过 API 连接到远程 konbu 服务器。 服务器代码不包含在命令行界面二进制文件中。
```bash
go install github.com/krtw00/konbu/cmd/konbu@latest
```
### 设置
```bash
# 设置环境变量（推荐：添加到 ~/.zshrc 或 ~/.bashrc）
export KONBU_API=https://konbu.example.com
export KONBU_API_KEY=your-api-key
# 或作为标志传递
konbu --api https://... --api-key your-key memo list
```
在 web UI 的 **设置 > 安全** 中生成 API 密钥。
### 命令
所有命令都支持 `--json` 标志，用于机器可读的输出。
```
konbu memo list # 列出备忘录
konbu memo show <id> # 显示备忘录内容
konbu memo add "title" -c "content" # 创建备忘录（-c - 从标准输入）
konbu memo edit <id> --title "new" # 更新备忘录
konbu memo rm <id> # 删除备忘录
konbu todo list # 列出待办事项
konbu todo show <id> # 显示待办事项详情
konbu todo add "task" -t "tag1,tag2" # 创建待办事项
konbu todo add "task" -d 2025-04-01 # 创建带有截止日期的待办事项
konbu todo edit <id> --desc "notes" # 更新待办事项
konbu todo done <id> # 标记为完成
konbu todo reopen <id> # 重新打开
konbu todo rm <id> # 删除
konbu event list # 列出事件
konbu event show <id> # 显示事件详情
konbu event add "title" -s <RFC3339> # 创建事件
konbu event edit <id> --title "new" # 更新事件
konbu event rm <id> # 删除
konbu tag list # 列出标签
konbu tag rm <id> # 删除标签
konbu search "query" # 跨搜索
konbu api-key list # 列出 API 密钥
konbu api-key create "key-name" # 创建 API 密钥
konbu api-key rm <id> # 删除 API 密钥
konbu export json -o backup.json # 导出为 JSON
konbu export markdown -o backup.zip # 导出为 Markdown ZIP
konbu import ical calendar.ics # 导入 iCal 文件
```
短 ID（前 8 个字符）可用于代替完整的 UUID。
## MCP 服务器
konbu 可以作为内置的 MCP（模型上下文协议）服务器运行在两种模式下 - 选择适合您的模式。
### 独立模式（SQLite，无需服务器）
如果您只需要 konbu 作为本地 MCP 后端用于 Claude Desktop、Cursor 或任何 MCP 客户端，请安装命令行界面并使用 `--standalone` 运行它。 无需 PostgreSQL，无需网络服务器，无需 API 密钥 - 所有内容都存储在本地 SQLite 文件中。
```bash
go install github.com/krtw00/konbu/cmd/konbu@latest
konbu mcp --standalone
```
数据默认保存在 `~/.konbu/konbu.db`。 如果需要，可以使用 `--db /path/to/db.sqlite` 覆盖。
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` 在 macOS 上，`%APPDATA%\Claude\claude_desktop_config.json` 在 Windows 上）：
```json
{
"mcpServers": {
"konbu": {
"command": "konbu",
"args": ["mcp", "--standalone"]
}
}
}
```
**Cursor** 接受相同的配置，位于 `~/.cursor/mcp.json`（或通过设置 UI）。
#### Docker
一个多架构镜像（`linux/amd64`，`linux/arm64`）已发布到 GitHub 容器注册表中。 直接拉取它 - 无需构建步骤：
```bash
docker pull ghcr.io/krtw00/konbu-mcp:latest
```
对于可复制的设置，请固定到发布标签 - 例如 `docker pull ghcr.io/krtw00/konbu-mcp:v0.2.0`。
然后将您的 MCP 客户端指向它。 数据保存在命名卷中：
```json
{
"mcpServers": {
"konbu": {
"command": "docker",
"args": ["run", "--rm", "-i", "-v", "konbu-data:/data", "ghcr.io/krtw00/konbu-mcp:latest"]
}
}
}
```
更喜欢从源代码构建？ `docker build -f docker/Dockerfile.mcp -t konbu-mcp .` 从存储库根目录生成相同的镜像（无 CGO，distroless 静态，~22 MB）。
独立模式公开备忘录/待办事项/日历事件 CRUD 以及跨资源搜索。 标签、附件和 AI 聊天仅限服务器（使用下面的连接模式）。
### 连接模式（与 konbu 服务器通信）
如果您正在运行 konbu 服务器（自行托管或 [konbu Cloud](https://konbu-cloud.codenica.dev)），请将 MCP 服务器指向它通过 HTTP。 您将获得完整的功能集：标签、附件和 AI 聊天。
1. 安装 `konbu` 命令行界面二进制文件（参见上面的 [命令行界面](#命令行界面) 部分）
2. 在 web UI 的 **设置 > 安全** 中生成 API 密钥
3. 将 konbu 添加到您的 MCP 客户端配置中：
```json
{
"mcpServers": {
"konbu": {
"command": "konbu",
"args": ["mcp"],
"env": {
"KONBU_API": "http://localhost:8080",
"KONBU_API_KEY": "your-api-key"
}
}
}
}
```
### 使用示例
重启您的 MCP 客户端后，使用自然语言与 konbu 交互：
- “明天我的日程是什么？”
- “下周五 1 点添加牙医预约”
- “创建带有标签‘购物’的待办事项‘购买杂货’”
- “显示上周标记为‘会议’的笔记”
- “将待办事项‘审查 PR’标记为完成”
## API
基准路径：`/api/v1`
| 资源 | 端点 |
|---|---|
| 认证 | `POST /auth/register`，`POST /auth/login`，`POST /auth/logout`，`GET /auth/setup-status`，`GET /auth/providers`，`GET /auth/google/login`，`GET /auth/google/callback` |
| 用户 | `GET/PUT /auth/me`，`GET/PUT /auth/settings`，`POST /auth/change-password`，`POST /auth/delete-account` |
| API 密钥 | `GET/POST /api-keys`，`DELETE /api-keys/:id` |
| 备忘录 | `GET/POST /memos`，`GET/PUT/DELETE /memos/:id`，`GET/POST /memos/:id/rows`，`POST /memos/:id/rows/batch`，`GET /memos/:id/rows/export`，`PUT/DELETE /memos/:id/rows/:rowId` |
| 待办事项 | `GET/POST /todos`，`GET/PUT/DELETE /todos/:id`，`PATCH /todos/:id/done`，`PATCH /todos/:id/reopen` |
| 事件 | `GET/POST /events`，`GET/PUT/DELETE /events/:id` |
| 日历 | `GET/POST /calendars`，`GET/PUT/DELETE /calendars/:id`（仅限所有者） |
| 标签 | `GET/POST /tags`，`PUT/DELETE /tags/:id` |
| 搜索 | `GET /search?q=...` |
| 聊天 | `GET/POST /chat/sessions`，`GET/PUT/DELETE /chat/sessions/:id`，`POST /chat/sessions/:id/messages`，`GET/PUT /chat/config` |
| 附件 | `POST /attachments`，`GET /attachments/*` |
| 导出 | `GET /export/json`，`GET /export/markdown` |
| 导入 | `POST /import/ical` |
## 开发
```bash
# 启动 PostgreSQL
docker compose up -d postgres
# 前端开发服务器
cd web/frontend && npm run dev
# 运行服务器
DEV_USER=dev@local go run ./cmd/server
# 构建命令行界面
go build -o bin/konbu ./cmd/konbu
# 运行测试
go test ./...
cd web/frontend && npm test
cd web/frontend && npm run test:e2e
```
### 项目结构
```
cmd/
server/ # API 服务器
konbu/ # 命令行界面客户端
internal/
handler/ # HTTP 处理程序
service/ # 业务逻辑
repository/ # 数据库访问（sqlc）
middleware/ # 认证、日志记录
client/ # API 客户端（用于命令行界面）
mcp/ # MCP 服务器
web/frontend/ # React + Vite 单页应用
sql/ # 模式和迁移
docker/ # Dockerfile
```
## 路線圖
- 瀏覽器推送提醒（电子邮件提醒已经支持，当配置了 `SMTP_*` 环境变量时）
- 移动界面改进
- CI 测试覆盖率
- AI 聊天增强（上下文改进、新模型支持）
## 赞助商
如果您觉得 konbu 有用，请考虑 [赞助](https://github.com/sponsors/krtw00) 该项目。
## 许可
[MIT](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器