Konbu

konbu

由 AI 管家打理的个人数字规划工具。
命令行 · MCP · 可自托管 · 原生支持 AI

一个 Go 二进制文件，将备忘、待办事项、日程和表格整合到一个规划工具中——所有内容都能在一处搜索，并由 AI 打理。
连接 Claude、Cursor 或任何 MCP 客户端，管理你的数据。

日本語 | 英语

---

立即体验

• 云端 -- 在 konbu-cloud.codenica.dev 即刻使用（免费，无需设置）
• 自托管 -- 使用 Docker 在自己的服务器上运行（见下文）

什么是 konbu？

konbu 是一款个人数字规划工具——将 Filofax 风格的系统规划本数字化。它是一个可自托管的 Go 二进制文件，可将备忘、待办事项、日程和结构化表格整合到一个笔记本中，由 AI 管家打理，并通过统一的搜索界面呈现所有内容。它只属于你——绝不会与他人共享。它并非 Notion + Todoist + Calendar 的替代品，而是替代为了找到一件事而在四个应用间来回搜索的行为。

特色：

• 原生 MCP 服务 + CLI 客户端 -- 为 AI 管家（Claude / Cursor / 任何 MCP 客户端）或 Shell / 脚本提供两种并行方式来操作规划工具。
• 跨资源全文搜索 -- 一次查询即可搜索备忘、待办事项、事件和结构化表格。这是核心体验，而非附加功能。
• 结构化表格（= 表格备忘，计划中） -- 追踪血压、家庭预算或库存。Markdown 无法表达这些内容，表格可以。
• 自带密钥的 AI 聊天 -- 使用你自己的 OpenAI/Anthropic API 密钥，也可使用内置的免费套餐。
• 专为个人使用而设计 -- 一本只属于你的笔记本。可从外部导入内容（Google Calendar），但不会向外泄露。
• 可自托管 -- 可使用单个 Go 二进制文件、Docker compose 运行，也可使用托管版本。

告别每天的安排散落在四个不同应用中的状态。

功能

• 跨资源全文搜索 -- 一次查询即可搜索备忘、待办事项、事件和结构化表格（核心体验）
• CLI 和 MCP 服务 -- 内置 CLI 客户端和 MCP 服务。Claude、Cursor 等 AI Agent 可直接读取和写入你的数据
• AI Agent 聊天 -- 用自然语言说“把杂货加到我的待办事项里”或“我明天有什么安排？”。支持自带密钥，并包含免费套餐
• 备忘 -- 支持标签和实时预览的 Markdown 笔记
• 待办事项 -- 可内联创建任务，并添加截止日期、标签和备注
• 日历 -- 月视图，支持事件的增删改查和 iCal 导入（个人专用，仅所有者可访问）
• 结构化表格（= 表格备忘，计划中） -- 以行 × 列的形式追踪结构化数据（血压、家庭预算、库存）
• 导出/导入 -- JSON 导出、Markdown ZIP 导出、iCal 导入
• 国际化 -- 支持英语和日语

快速开始

cp .env.example .env
docker compose up -d

打开 http://localhost:8080 并创建账户。开发用 compose 文件会设置 DEV_USER=dev@local，以跳过注册。

生产环境（使用 Traefik）

# Edit .env with real credentials and your domain
docker compose -f docker-compose.prod.yml up -d

原生运行（不使用 Docker）

# Prerequisites: Go 1.25+, Node.js 22+, PostgreSQL 16+

# Build frontend
cd web/frontend && npm ci && npm run build && cd ../..

# Build server
go build -o bin/server ./cmd/server

# Start (runs all SQL migrations automatically on boot)
DATABASE_URL="postgres://..." SESSION_SECRET="..." ./bin/server

配置

变量	必填	默认值	说明
DATABASE_URL	是	--	PostgreSQL 连接字符串
SESSION_SECRET	是	dev fallback	会话签名密钥
PORT	否	8080	服务端口
DEV_USER	否	--	以此电子邮件地址自动登录（仅限开发环境）
OPEN_REGISTRATION	否	--	设置为 true 以允许任何人注册（适用于 Cloud）
BASE_URL	否	--	用于 OAuth 回调的公开应用 URL
GOOGLE_CLIENT_ID	否	--	启用 Google OAuth 登录
GOOGLE_CLIENT_SECRET	否	--	启用 Google OAuth 登录
WEBHOOK_SECRET	否	--	GitHub Sponsors Webhook 密钥
STRIPE_SECRET_KEY	否	--	启用 Stripe 结账和订阅计费
STRIPE_WEBHOOK_SECRET	否	--	验证传入的 Stripe Webhook 事件
STRIPE_PRICE_MONTHLY	否	--	用于按月 Pro 结账的 Stripe Price ID
STRIPE_PRICE_YEARLY	否	--	用于按年 Pro 结账的 Stripe Price ID
GITHUB_FEEDBACK_TOKEN	否	--	用于创建匿名反馈议题的 GitHub 令牌
GITHUB_FEEDBACK_REPO	否	--	接收反馈议题的仓库，例如 krtw00/konbu
GITHUB_FEEDBACK_LABELS	否	--	添加到转发的反馈议题中的逗号分隔标签
AI_ENCRYPTION_KEY	否	--	用于加密 BYOK AI 密钥的 64 位十六进制字符
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 中继端口（通常 STARTTLS 使用 587）
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 路由的域名

CLI

CLI 是一个独立客户端，通过 API 连接到远程 konbu 服务。CLI 二进制文件不包含服务端代码。

go install github.com/krtw00/konbu/cmd/konbu@latest

设置

# Set environment variables (recommended: add to ~/.zshrc or ~/.bashrc)
export KONBU_API=https://konbu.example.com
export KONBU_API_KEY=your-api-key

# Or pass as flags
konbu --api https://... --api-key your-key memo list

在 Web 界面的 设置 > 安全 中生成 API 密钥。

命令

所有命令都支持 --json 标志，可输出机器可读的内容。

konbu memo list                        # List memos
konbu memo show <id>                   # Show memo content
konbu memo add "title" -c "content"    # Create memo (-c - for stdin)
konbu memo edit <id> --title "new"     # Update memo
konbu memo rm <id>                     # Delete memo

konbu todo list                        # List todos
konbu todo show <id>                   # Show todo details
konbu todo add "task" -t "tag1,tag2"   # Create todo
konbu todo add "task" -d 2025-04-01    # Create with due date
konbu todo edit <id> --desc "notes"    # Update todo
konbu todo done <id>                   # Mark done
konbu todo reopen <id>                 # Reopen
konbu todo rm <id>                     # Delete

konbu event list                       # List events
konbu event show <id>                  # Show event details
konbu event add "title" -s <RFC3339>   # Create event
konbu event edit <id> --title "new"    # Update event
konbu event rm <id>                    # Delete

konbu tag list                         # List tags
konbu tag rm <id>                      # Delete tag

konbu search "query"                   # Cross-search

konbu api-key list                     # List API keys
konbu api-key create "key-name"        # Create API key
konbu api-key rm <id>                  # Delete API key

konbu export json -o backup.json       # Export as JSON
konbu export markdown -o backup.zip    # Export as Markdown ZIP
konbu import ical calendar.ics         # Import iCal file

可使用短 ID（前 8 个字符）代替完整 UUID。

MCP 服务

konbu 可以作为内置 MCP（Model Context Protocol）服务运行，支持两种模式——选择适合的一种。

独立模式（SQLite，无需服务器）

如果你只想将 konbu 用作 Claude Desktop、Cursor 或任何 MCP 客户端的本地 MCP 后端，请安装 CLI 并使用 --standalone 运行。无需 PostgreSQL、无需 Web 服务器、无需 API 密钥——所有数据都存储在本地 SQLite 文件中。

go install github.com/krtw00/konbu/cmd/konbu@latest
konbu mcp --standalone

数据默认保存在 ~/.konbu/konbu.db。如有需要，可使用 --db /path/to/db.sqlite 指定其他路径。

Claude Desktop（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上的 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "konbu": {
      "command": "konbu",
      "args": ["mcp", "--standalone"]
    }
  }
}

Cursor 支持在 ~/.cursor/mcp.json 中使用相同配置（也可通过设置界面配置）。

Docker

一个多架构镜像（linux/amd64、linux/arm64）已发布到 GitHub Container Registry。可直接拉取，无需构建：

docker pull ghcr.io/krtw00/konbu-mcp:latest

为确保环境可复现，请固定到某个发布标签，例如 docker pull ghcr.io/krtw00/konbu-mcp:v0.2.0。

然后将 MCP 客户端指向该镜像。数据会持久保存在命名卷中：

{
  "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）。

独立模式提供备忘录、待办事项、日历事件的增删改查，以及跨资源搜索。标签、附件和 AI 聊天仅限服务器模式使用（请使用下方的连接模式）。

连接模式（连接到 konbu 服务器）

如果你正在运行 konbu 服务器（自托管或 konbu Cloud），请通过 HTTP 将 MCP 服务指向该服务器。这样即可使用完整功能集：标签、附件和 AI 聊天。

1. 安装 konbu CLI 二进制文件（参见上方的 CLI 部分）
2. 在 Web UI 中通过 Settings > Security 生成 API 密钥
3. 在 MCP 客户端配置中添加 konbu：

{
  "mcpServers": {
    "konbu": {
      "command": "konbu",
      "args": ["mcp"],
      "env": {
        "KONBU_API": "http://localhost:8080",
        "KONBU_API_KEY": "your-api-key"
      }
    }
  }
}

使用示例

重启 MCP 客户端后，可用自然语言与 konbu 交互：

• “我明天的日程安排是什么？”
• “下周五下午 1 点添加一个牙医预约”
• “创建一个带有标签 ‘shopping’ 的待办事项，内容是买杂货”
• “显示上周带有标签 ‘meeting’ 的备忘录”
• “将 ‘review 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

开发

# Start PostgreSQL
docker compose up -d postgres

# Frontend dev server
cd web/frontend && npm run dev

# Run server
DEV_USER=dev@local go run ./cmd/server

# Build CLI
go build -o bin/konbu ./cmd/konbu

# Run tests
go test ./...
cd web/frontend && npm test
cd web/frontend && npm run test:e2e

项目结构

cmd/
  server/       # API server
  konbu/        # CLI client
internal/
  handler/      # HTTP handlers
  service/      # Business logic
  repository/   # DB access (sqlc)
  middleware/   # Auth, logging
  client/       # API client (used by CLI)
  mcp/          # MCP server
web/frontend/   # React + Vite SPA
sql/            # Schema and migrations
docker/         # Dockerfile

路线图

• 浏览器推送提醒（配置 SMTP_* 环境变量后，已支持电子邮件提醒）
• 改进移动端 UI
• CI 测试覆盖率
• 增强 AI 聊天功能（改进上下文、支持新模型）

赞助者

如果你觉得 konbu 有用，请考虑赞助该项目。

许可证

MIT