Penpal (No Man Nayeem)

\# 笔友：写作天地

一个融合了温馨书信往来式体验的混合内容创作平台。此单一仓库托管了Next.js 15网页客户端、Tauri 2桌面外壳以及基于Python的MCP服务器。

项目布局

apps/
  web/        # Next.js 15 + shadcn/ui brand experience & workspace UI
  desktop/    # Tauri 2 wrapper for the static web build
packages/
  python-mcp/ # FastMCP server with async SQLite + LiteLLM pipeline

先决条件

• Node.js 18+（节点23已测试）
• pnpm（注：pnpm是一个包管理器，全称为Performance Packaged Node Modules，用于JavaScript项目依赖管理，直接翻译为“pnpm”即可，因其本身已是专有名词） 10+（建议使用v10.17.1版本）
• Rust + Cargo（可译为“Rust语言及其包管理工具Cargo”） （针对Tauri桌面构建 - 最新稳定版）
• python 3.10+（建议使用3.10、3.11或3.12版本）

快速入门

1. 克隆并安装：

git clone https://github.com/NoManNayeem/Penpal.git
cd "Penpal - The Write Spot"
pnpm install

2. 启动MCP服务器：

cd packages/python-mcp
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

pip install -e .[dev]
cp .env.example .env
python -m penpal_mcp.server

3. 在新终端中启动Web应用：

pnpm --filter web dev

4. 打开 http://localhost:3000 在您的浏览器中

5. 访问工作区： 导航至 http://localhost:3000/workspace 开始编写！

常用脚本

pnpm install                 # install workspace deps
pnpm dev                     # run all dev scripts via Turborepo
pnpm --filter web dev        # start Next.js app only (http://localhost:3000)
pnpm --filter desktop dev    # launch Tauri desktop (spawns Next dev server)

MCP服务器

cd packages/python-mcp
python -m venv .venv
. .venv/Scripts/Activate.ps1  # Windows example
pip install -e .[dev]
cp .env.example .env
python -m penpal_mcp.server

MCP服务器提供了用于生成大纲、文档存储、列出和导出的工具。OpenAI/Anthropic/Google/xAI的API密钥是可选的——如果没有这些密钥，服务器将返回确定性的示例数据，以便在开发期间UI可以端到端运行。

MCP 环境变量

MCP服务器从（某个位置）读取配置 .env 或者设置包含环境变量的 PENPAL_ 前缀：

• PENPAL_DATABASE_URL - SQLite数据库路径（默认： sqlite+aiosqlite:///./penpal_write_spot.db)
• PENPAL_MCP_PORT - HTTP服务器端口（默认： 7337)
• PENPAL_LLM_DEFAULT_MODEL - 默认的大型语言模型（默认： openai/gpt-4o-mini)
• OPENAI_API_KEY - 可选：用于实时AI功能的OpenAI API密钥
• ANTHROPIC_API_KEY 可选：Anthropic Claude API密钥
• GOOGLE_API_KEY - 可选：Google Gemini API密钥
• XAI_API_KEY - 可选：xAI Grok API密钥

Docker 工作流程

使用 Docker Compose 一起启动网络客户端和 MCP 服务器：

docker compose up --build

服务：

• web → Next.js 开发服务器运行在 http://localhost:3000
• mcp → FastMCP 服务器在 http://localhost:7337 上运行

该组合配置将仓库挂载到容器中，以便在容器内实时热加载代码编辑。命名卷缓存了 pnpm 存储和 node 模块，以保持重建速度快。

注Tauri 桌面壳不是 Docker 堆栈的一部分，因为它需要一个原生的窗口环境。一旦网络应用导出，就可以使用 Rust/Cargo 在本地进行构建。

访问工作区用户界面

一旦堆栈运行起来，打开 http://localhost:3000/workspace 即可启动 Penpal 编辑器体验：

• 左侧边栏列出了通过MCP服务器存储的文档。
• 舞台中央是富文本编辑器（TipTap）和保存操作。
• 右侧导轨表面轮廓显示通过MCP工具生成的建议。

网页客户端通过与MCP传输层通信来 /api/mcp，将请求代理到已配置的 NEXT_PUBLIC_MCP_URL （默认为 http://127.0.0.1:7337）。

构建桌面应用程序

pnpm --filter web build
pnpm exec tauri build --target x86_64-pc-windows-msvc

前提条件：Rust 工具链（rustup)，Windows C++ 构建工具，以及通过（某种方式）启用的 pnpm corepack安装程序和二进制输出文件位于 apps/desktop/src-tauri/target/release/bundle （例如 bundle/msi/penpal-desktop_*.msi）。 发布时，将“下载桌面构建版”的行动号召（CTA）链接到该发布制品。

特点

✨（闪闪发光的星星或类似意象，具体含义根据上下文而定） 富文本编辑器 - 由TipTap驱动的编辑器，支持全面格式化功能 📝（便签/笔记） AI驱动的概要/大纲 - 使用多个大型语言模型（LLM）提供商生成内容大纲 💾 代表“软盘”或“存储设备” 文档管理 - 保存、列出并管理文档的版本 📤 表示“放（物品）出去”或“投递（邮件）”，在中文里可以翻译为“投递”或“送出”，具体根据上下文而定。 多格式导出 - 导出为PDF、DOCX、PPTX、HTML和Markdown格式 🌓 暗黑模式 - 系统感知的主题切换 🖥️ 桌面应用程序 - 基于Tauri的原生桌面应用程序 🐳 这个表情符号在中文里通常被理解为“海豚”，或者根据上下文有时也被用来表示“萌萌哒”、“可爱”等含义，但直接翻译就是“海豚”。 Docker 支持 - 容器化开发工作流程

技术栈

前端

• Next.js 15 - 带有App Router的React框架
• React 19 - 最新版本的React，具备并发特性
• TipTap（注：这是一个专有名词，直接翻译为中文可能无法准确传达其原意，通常保持原样或根据具体语境进行意译。在此处，由于“TipTap”可能是一个特定品牌或应用的名称，因此直接保留原样。） - 可扩展的富文本编辑器
• shadcn/ui（可翻译为“shadcn用户界面库”或根据具体语境简化为“shadcn UI”） - 可访问的组件库
• Tailwind CSS 版本 4 - 实用性优先的样式设计
• 状态 - 状态管理
• next-themes - 支持深色模式

后端

• FastMCP - 模型上下文协议服务器框架
• SQLAlchemy 2.0 - 带 SQLite 的异步 ORM
• LiteLLM - 多供应商大型语言模型（LLM）集成
• WeasyPrint - 生成PDF文件
• python-docx（用于处理Word文档的Python库） - Word文档生成
• python-pptx（可直接作为中文使用，表示用于操作PPT的Python库） - PowerPoint制作

桌面

• Tauri 2.0 - 原生桌面封装器
• Rust（一种编程语言） - 高性能后端

文档

📚 书籍 完整建筑指南： GitAssets/Penpal_The_Write_Spot.md - 整个平台的品牌体系、技术架构及实施细节。

GitHub Pages 登录页面（或：GitHub Pages 陆地页，但“Landing”在此上下文中更常翻译为“登录页面”或“着陆页”，具体取决于网站设计的意图）

一个独立的静态着陆页，与Penpal品牌形象相呼应，位于（或：以下方提供） GitAssets/直接将其部署到GitHub Pages，方法是指定Pages构建文件夹为 /GitAssets使用以下方式在本地预览：

cd GitAssets
python -m http.server 4100
# Visit http://localhost:4100

故障排除

MCP服务器连接问题

• 确保MCP服务器正在端口7337上运行
• 检查 NEXT_PUBLIC_MCP_URL 在 apps/web/.env.local
• 验证没有防火墙阻止端口7337

构建错误

• 清除 node_modules： rm -rf node_modules apps/*/node_modules && pnpm install
• 清除 Next.js 缓存： rm -rf apps/web/.next
• 确保 Python 3.10+ 已添加到您的系统路径中

桌面应用程序无法启动

• 确保已安装Rust工具链： rustup --version
• 先构建网页应用： pnpm --filter web build
• 检查Tauri依赖项是否已安装

做出贡献

1. 为仓库创建分支（或“克隆仓库”）
2. 创建一个特性分支（git checkout -b feature/amazing-feature)
3. 提交您的更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature)
5. 打开一个拉取请求

许可证

麻省理工学院（MIT）

支持

对于问题和疑问：

• GitHub Issues（GitHub问题）
• 文档： GitAssets/Penpal_The_Write_Spot.md