# Paprwork V2：基于 TypeScript 和 Mastra 重构的本地优先 AI 桌面助手

> Paprwork 是一个本地优先的 AI 桌面助手应用，V2 版本使用 TypeScript 和 Mastra 框架完全重写，支持多模型提供商、工具系统、子代理、定时任务和智能记忆系统。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-05T21:14:33.000Z
- 最近活动: 2026-04-05T21:21:53.172Z
- 热度: 152.9
- 关键词: AI assistant, desktop app, TypeScript, Electron, Mastra, local-first, multi-provider, sub-agents, automation
- 页面链接: https://www.zingnex.cn/forum/thread/paprwork-v2-typescript-mastra-ai
- Canonical: https://www.zingnex.cn/forum/thread/paprwork-v2-typescript-mastra-ai
- Markdown 来源: ingested_event

---

## 项目概述与演进历程\n\nPaprwork 是一个定位为"本地优先"的 AI 桌面助手应用，它的核心理念是让 AI 代理能够安全地访问用户的计算机、记住上下文、从交互中学习，并自动化工作流程。这个项目经历了重大演进——V1 版本积累了大量技术债务，而 V2 则是一次彻底的重写，目标是构建一个真正生产就绪的架构。\n\nV1 版本的问题相当典型：超过 3 万行的单体文件、90% 的代码在进程间重复、工具调用需要 10 多个补丁才能稳定工作、缺乏类型安全。这些问题在快速原型阶段或许可以接受，但对于一个需要长期维护的产品来说，已经成为严重阻碍。\n\nV2 的解决方案是彻底推倒重来，采用现代技术栈和架构原则，从零构建一个可维护、可扩展的代码库。\n\n## 技术架构：从混乱到清晰\n\nV2 的架构设计深受 OpenClaw 启发，采用模块化、分层的设计理念：\n\n```\npaprwork-v2/\n├── src/\n│   ├── core/          # 共享库（零重复代码）\n│   │   ├── agents/    # MastraAgent, SessionManager\n│   │   ├── tools/     # 工具实现\n│   │   └── types/     # 类型定义\n│   ├── electron/      # Electron 主进程\n│   ├── gateway/       # 子代理和任务调度网关\n│   └── resources/     # 代理文档、技能、模板\n├── ui/                # React UI (Vite + TypeScript)\n├── docs/              # 文档\n└── tests/             # 测试套件\n```\n\n这种结构的关键改进在于 `core/` 目录——它是一个真正的共享库，被 Electron 主进程、Gateway 进程和 UI 共同使用，彻底消除了 V1 中 90% 代码重复的问题。所有组件都是 100% TypeScript，零 `any` 类型，文件严格控制在 500 行以内（CI 强制执行）。\n\n## 核心功能特性\n\nPaprwork V2 提供了一套完整的 AI 助手功能：\n\n**多提供商 AI 支持**：无缝切换 Claude、GPT 和 Gemini 模型，用户可以根据任务需求选择最适合的模型。\n\n**流式响应**：实时 AI 响应配合正确的工具执行，提供流畅的交互体验。\n\n**可扩展工具系统**：包括 Bash 执行、文件系统操作、文档处理等基础工具，同时支持自定义工具开发。\n\n**并行聊天会话**：支持多个并发的 AI 对话，方便多任务处理。\n\n**定时任务与自动化**：支持 Python、Node、Swift 编写的任务，配合 cron 调度实现自动化工作流。\n\n**智能记忆系统**：与 Papr Memory 集成，实现上下文感知的对话，AI 能够记住用户偏好和历史交互。\n\n**Mini-Apps**：支持 TypeScript 编写的微型应用，可访问 SQLite 数据库。\n\n**子代理**：专门的 AI 代理用于研究、代码审查等特定任务，可以委派复杂工作。\n\n**安全自定义密钥**：用户可以使用自己的 API 密钥，加密存储，保护隐私。\n\n## Mastra 框架的引入\n\nV2 最大的架构决策之一是引入 Mastra 框架作为 AI 编排层。Mastra 是一个多提供商 AI 框架，它解决了 V1 中工具调用脆弱的问题，提供可靠的跨模型支持。\n\nMastra 的引入带来了几个关键好处：一是统一的 Agent 抽象，无论底层是 Claude、GPT 还是 Gemini，上层代码保持一致；二是健壮的工具调用机制，不再需要为不同模型打补丁；三是内置的流式处理和错误恢复能力。\n\n## 开发体验优化\n\nPaprwork V2 在开发工具链上做了大量投资，使用 Rust 编写的工具替代传统 Node.js 工具：\n\n**oxlint**：替代 ESLint，速度快 50-100 倍\n**oxfmt**：替代 Prettier，速度快 30 倍\n\n这些工具不仅提升了开发效率，也缩短了 CI 时间。配合 TypeScript 的严格类型检查，代码质量得到了系统性保障。\n\n开发工作流支持热重载，可以同时运行 Gateway 进程、UI Vite HMR 和 Electron 应用，修改代码后几乎即时看到效果。\n\n## 隐私与数据收集策略\n\n作为一个本地优先的应用，Paprwork 对隐私的重视体现在多个层面：\n\n**遥测数据**：应用会发送匿名的粗略使用事件（如应用启动/退出），用于了解采用情况。这些数据从不包含聊天内容、提示词、文件路径、API 密钥或个人数据。遥测默认对打包安装开启，从源码运行时关闭，用户可以在设置中随时关闭。\n\n**自定义端点**：用户可以通过设置 `PAPRWORK_TELEMETRY_URL` 使用自己的遥测代理，或设置为空字符串完全阻止遥测网络调用。\n\n**API 密钥管理**：用户密钥使用加密存储，应用本身不嵌入任何 API 密钥。\n\n## 快速开始\n\nPaprwork 需要 Node.js v24+（Electron 40 的要求）和 npm v10+。安装过程相对标准：\n\n```bash\ngit clone https://github.com/Papr-ai/paprwork.git\ncd paprwork\nnvm use 24\nnpm install\ncp .env.example .env.local\n# 编辑 .env.local 添加 API 密钥\nnpm start\n```\n\n项目使用 npm workspaces，根目录的 `npm install` 会自动安装主应用和 `ui/` 工作区的依赖，无需单独运行。\n\n## 测试策略\n\nV2 建立了全面的测试体系，包括：\n\n- 单元测试（后端和 UI 分离）\n- 集成测试\n- E2E 测试\n- 类型检查\n- 代码格式化检查\n- 代码行数限制检查\n\n所有检查可以通过 `npm run check` 一键运行，确保代码质量。\n\n## 与 OpenClaw 的关系\n\nPaprwork V2 明确提到其架构灵感来自 OpenClaw。两者都是 AI 助手类应用，但定位有所不同：OpenClaw 是终端优先的 CLI 工具，而 Paprwork 是桌面 GUI 应用。Paprwork 借鉴了 OpenClaw 的模块化架构思想，但针对桌面环境做了相应调整，比如引入 Electron 和 React 构建用户界面。\n\n这种借鉴是开源社区的典型模式——学习成功项目的架构经验，结合自身场景进行创新。\n\n## 应用场景\n\nPaprwork 适合以下场景：\n\n**个人知识管理**：利用智能记忆系统构建个人知识库，AI 能够基于历史交互提供个性化建议。\n\n**自动化工作流**：通过定时任务和子代理，自动化重复性工作，如定期整理文件、生成报告等。\n\n**多模型对比**：在同一个界面中对比不同模型的回答，选择最适合当前任务的 AI。\n\n**隐私优先的 AI 交互**：所有数据本地处理，敏感信息不会上传到第三方。\n\n## 总结\n\nPaprwork V2 代表了一个项目从原型到产品的成熟转变。通过彻底重写，它解决了 V1 的技术债务，引入了 Mastra 框架、Rust 工具链和严格的代码规范，构建了一个可维护、可扩展的架构。对于寻求本地优先 AI 助手解决方案的用户，或者想了解如何从混乱代码库重构到清晰架构的开发者，Paprwork V2 都是一个值得关注的项目。