minddy

minddy

在一个开源工作区中管理问题、产品知识和 Numo。

minddy 是一款面向小型产品团队的开源问题跟踪工具。它将日常工作集中在一处：项目、问题、目标、已保存的视图、协作页面、公开反馈板，以及一个 MCP 服务，让编码 Agent 能与团队使用同一份待办列表。

该应用基于 Next.js、React、Tailwind CSS 和 Supabase 构建。它还提供可选的 macOS、Linux 和 Microsoft Store Windows 桌面端，以及 GitHub、 GitLab、Stripe 和 OpenRouter 集成。

产品导览

使用 Numo 跟踪工作

从 Numo 页面或上下文浮动按钮发起对话。Numo 会结合项目背景作答，并直接更新 Minddy：创建和分类问题、填充周期、编写页面，以及运行定时例程。编码工作由你自己的 Agent 负责：将问题复制为提示词，然后在 Minddy 中查看关联的拉取请求。

将持久知识与待办列表放在一起

在嵌套的项目维基中编写规格说明、决策、操作手册和会议记录。页面支持富文本 Markdown、问题提及、附件、历史记录和只读共享，让团队成员和已连接的 Agent 都能使用同一份权威信息源。

将客户反馈与交付工作关联起来

发布反馈板，让用户提交需求并投票。团队可以对帖子进行分类、公开回复、合并重复项，并将反馈关联到问题，让公开状态随交付工作同步更新。

## 本地运行

要求：Node.js 24.22.1 或更高版本的 24.x 版本，以及 pnpm 10（CI 使用的版本）；交互式应用还需要一个 Supabase 项目。

corepack enable
corepack prepare [email protected] --activate
pnpm install --frozen-lockfile
cp .env.example .env
pnpm dev

.env.example 记录了所有可选集成和 Supabase 控制面板 设置。若要运行可访问自身数据的本地 应用，至少要设置 MINDDY_PUBLIC_SUPABASE_URL、 MINDDY_PUBLIC_SUPABASE_ANON_KEY 和 SUPABASE_SERVICE_ROLE_KEY。切勿提交 .env 或生产环境凭据。

开发命令会先构建 page-markdown 包，再启动 Next.js。运行来自不可信拉取请求的代码前，请参阅 CONTRIBUTING.md：安装依赖、运行测试和开发命令都会执行仓库代码。

Minddy Cloud 是由 Minddy 托管和运营的选项。可自托管版本是在你控制的基础设施上运行的相同公开核心：无需 Minddy 账户、Stripe、 PostHog 或托管服务提供商。版本指南 集中说明了选择、数据流、责任和成本。 若要安装自己的实例，请从适用于这台计算机或共享服务器的 分步自托管安装程序开始。在自己的计算机上，桌面应用的 自托管 minddy › 在这台计算机上安装会为你完成整个本地 安装。有关拓扑、配置和可复现 Supabase 引导流程的技术参考，请使用 docs/self-hosting.md。在全新的本地克隆中，请在运行 pnpm dev 前运行 pnpm bootstrap:supabase，而不要在 Supabase 控制面板中手动应用 SQL。安装完成后，请参阅 自托管运维手册，了解升级、 Postgres 和 Storage 协同备份、灾难恢复和回滚。 发布验收通过隔离的 洁净环境自托管场景记录。 官方多架构 OCI 镜像、其标签策略和验证 命令记录在 docs/container-image.md 中。

常用命令

pnpm dev          # run the web app locally
pnpm lint         # lint
pnpm typecheck    # type-check
pnpm test         # run the test suite
pnpm build        # production build
pnpm desktop:dev  # run the optional desktop shell

架构和部署

开发遵循基于主干的分支约定：短期工作分支通过拉取请求合并到 main，它是集成分支和预览候选版本。CI 通过并获得明确的生产环境批准后，自动化流程会将 production 快进到选定的 main SHA。项目没有长期存在的 develop 或发布分支，也不会由人工直接写入 production。

• **Web 应用：**Next.js App Router、React、Tailwind CSS，以及 Minddy 自有的 UI 组件（components/ui/，基于 Radix）。
• **数据和身份验证：**Supabase Postgres、Auth、Storage 和 Realtime。
• **Numo 和 Agent 集成：**统一的 Numo 对话、定时例程，以及面向外部 Agent 的 OAuth 2.1 MCP 端点。
• 部署：pnpm deploy 是维护者交互式入口。它会检测是否需要发布公共核心、部署 Minddy Cloud Web 应用，以及为 macOS、Linux 和 Windows 发布桌面应用，并支持自动、全部、自定义和仅 Windows 模式。仅 Windows 模式会复用现有的核心版本，避免启动 macOS 或 Linux 运行器。助手会等待 CI，通过批准的快进操作将 main 更新到 production，验证 Vercel Production 部署，并且只为已部署的 SHA 创建标签。构建和生产环境密钥不会来自维护者的计算机。自托管用户应根据自己的托管环境调整其中的 production/Vercel 约定。

公共版本发布与部署有所区别。SemVer/标签策略、构件、校验和、迁移、CI 来源证明、桌面应用分发和回滚流程，详见 docs/releases.md。Linux 安装、GPG 验证、XDG 路径和更新行为，详见 docs/linux-desktop.md。每次发布后在公共注册表中注册 MCP 服务的流程，详见 docs/mcp-registry-publication.md。

CI 工作流是检查项目的事实依据。它会运行公共仓库检查、lint、类型检查、桌面应用包构建、测试和依赖项审计。贡献和评审指南请参阅 CONTRIBUTING.md，安全模型和漏洞报告方式请参阅 SECURITY.md。

社区和治理

• 通过仓库的结构化 Issue 表单提出 Bug 和改进建议；创建拉取请求前，请阅读 CONTRIBUTING.md。
• 请在 GitHub Discussions 中提出使用和自托管问题。尽力提供的社区帮助与商业支持之间的界限，详见 SUPPORT.md。
• 项目角色、决策、评审、受保护分支和依赖项政策，详见 GOVERNANCE.md。
• 参与项目须遵守行为准则。请按照 SECURITY.md 中的说明私下报告漏洞。

许可证

minddy 根据 GNU AGPL v3.0 only 发布。如果你通过网络向用户提供修改后的版本，就必须向这些用户提供相应的源代码。请参阅许可政策，其中也说明了 minddy 名称和徽标的使用限制。