内容
# 错误妈妈
<p align="center">
<img src="docs/error-mom-icon.png" alt="错误妈妈" width="200">
</p>
<p align="center">
<strong>您的应用程序崩溃了。妈妈发现了。您的编码代理修复了它。</strong>
</p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
<a href="https://youtube.com/@kenkaidoesai"><img src="https://img.shields.io/badge/YouTube-FF0000?style=for-the-badge&logo=youtube&logoColor=white" alt="YouTube"></a>
<a href="https://skool.com/kenkai"><img src="https://img.shields.io/badge/Skool-Community-7C3AED?style=for-the-badge" alt="Skool"></a>
</p>
**错误妈妈** 是您自己的私人错误跟踪器。您构建的每个应用程序都会向一个仪表板报告崩溃，您的编码代理会读取这些错误并为您修复它们。
无需 Sentry 订阅，无需按席位定价，无需将数据存储在别人的云中。一次部署，所有应用程序，设置只需三个复制粘贴提示。您不需要了解这里的任何代码。
---
## ✨ 它能做什么
### 每个应用程序都有一个仪表板
部署错误妈妈一次。连接任意多个应用程序。每个应用程序都有自己的只写密钥，每个崩溃都进入同一个队列。
### 您的编码代理修复错误
`error-mom` CLI 和内置的 MCP 服务器让 Claude Code、Cursor 或 GG Coder 等代理可以列出未解决的问题，读取堆栈跟踪和面包屑，修复代码，并标记问题已解决，所有这些都来自一个提示。
### 重复次数被统计，不会重复
同一个崩溃发生 500 次，显示为一个问题，计数为 500，加上几个代表性的样本。您的队列保持可读。
### 修复意味着修复，直到不再修复
解决一个问题会记录修复它的版本。如果同一个错误在该版本或更新版本中再次出现，问题会自动重新打开为**回归**。
### 机密永远不会进入数据库
密码、令牌、cookie、授权标头、API 密钥、电子邮件、查询凭证、URL 用户信息、机器人令牌、Webhook 凭证和标记的凭证路径都会被清理两次：在 SDK 发送之前和收集器存储之前。
### AI 提供商失败会自动标记
对 Anthropic、OpenAI、Kimi、GLM、Qwen、Groq、OpenRouter 或其他约 40 个 AI API 的失败调用会显示为其自己的命名问题（例如 `AnthropicApiError`），并标记提供商和状态代码。“Anthropic 宕机”和“我的代码损坏”永远不会混淆在一起。
### 跟踪永远不会破坏您的应用程序
捕获永远不会抛出到您的代码中。离线？浏览器事件会排队到本地存储，Node 事件会写入磁盘，所有事件都会在以后重试。
---
## 🆚 错误妈妈 vs Sentry
| | **错误妈妈** | **Sentry** |
| --------- | --------------------------------------------------------- | ---------------------------------------------------- |
| 成本 | Railway 上约 5 美元/月，无限应用程序 | 免费层，然后从 26 美元/月，按事件数计费 |
| 数据 | 您的服务器，您的 Postgres | 他们的云（存在自托管，但运行成本高） |
| 构建目的 | 编码代理：CLI + MCP 以便代理自行修复错误 | 人类仪表板，警报，大团队工作流程 |
| 设置 | 三个复制粘贴提示 | SDK 配置，DSNs，每个应用程序的项目设置 |
| 范围 | 错误输入，问题输出。有意为之。 | 跟踪，性能分析，会话重放，定时任务监控… |
| 源代码 | 开源（MIT），阅读每一行 | 开源核心（FSL） |
如果您需要跟踪、重放和大团队工作流程，Sentry 是一个很棒的产品。如果您想要一个私人错误队列，您的编码代理可以处理，那么这个产品更简单，而且是您自己的。
---
## ☁️ 您需要首先准备
- 一个 [Railway](https://railway.com) 账户（这是错误妈妈运行的地方，数据库和服务器约 5 美元/月）。
- 一个编码代理（Claude Code、Cursor、GG Coder 等）。
就这样。您永远不需要运行 Docker，永远不需要触摸数据库，永远不需要编写配置。
## 🚀 提示 1：设置错误妈妈（只需一次）
将此内容粘贴到您的编码代理中：
```text
在 Railway 上设置错误妈妈，我的私人错误跟踪器。
1. 如果 Railway CLI 未安装，请安装它（npm install -g @railway/cli
或 brew install railway）。如果我未登录，请运行“railway login”并
等待我完成浏览器登录。
2. 克隆 https://github.com/KenKaiii/error-mom 并从该文件夹运行：
railway init --name error-mom
railway add --database postgres
railway add --service error-mom \
--variables 'DATABASE_URL=${{Postgres.DATABASE_URL}}' \
--variables "ERROR_MOM_ADMIN_TOKEN=$(openssl rand -hex 32)"
railway up --service error-mom --ci
railway domain --service error-mom
3. 不要运行任何迁移或额外设置。数据库会在首次启动时自动配置。
4. 验证它是否有效：不断检查 <打印的域名>/api/health，直到它
返回 {"status":"ok"} （首次启动可能需要一分钟）。
5. 然后清楚地告诉我：
- 我的仪表板网址
- 我的管理员令牌（您生成的 ERROR_MOM_ADMIN_TOKEN 值）
- 您应该将两者安全地保存在密码管理器中。永远不要将令牌提交到 git。
```
完成后，在浏览器中打开仪表板网址并使用管理员令牌登录。空队列 = 正常。
## 🔌 提示 2：将错误跟踪添加到您的应用程序之一
每个应用程序只需执行一次此操作。打开您的应用程序，在编码代理中填写两个占位符，然后粘贴：
```text
使用我的私人错误妈妈服务器为该应用程序添加错误跟踪。
我的服务器：https://MY-ERROR-MOM.up.railway.app
我的管理员令牌：MY_ADMIN_TOKEN
1. 安装 CLI 并登录：
npm install --global error-mom
error-mom login <我的服务器> --token <我的管理员令牌>
2. 从该应用程序的文件夹运行：error-mom init
（如果这是 pnpm 或 yarn 工作区，请运行：error-mom init --skip-install，
然后使用工作区的包管理器将 @kenkaiiii/error-mom 安装到应用程序中）
3. init 检测框架（Next.js、Vite、Tauri、Electron、Astro、
SvelteKit、Nuxt、Remix、Angular、Express、Fastify、Hono、NestJS 或
纯 Node）并生成设置文件。其 JSON 输出包括一个“wiring”字段，其中包含
该框架的官方错误钩子的确切说明。精确遵循它们。
设置文件已将仅写入项目密钥内置（与 Sentry DSN 模型类似）：它只能提交错误，
永远不会读取，因此可以安全地提交，并且生产/CI 构建在没有额外配置的情况下报告。
（对于 Next.js 应用程序，init 还生成 instrumentation.ts，它报告服务器端错误：
API 路由、SSR、服务器操作。保留它。）
4. 覆盖每个进程和每个捕获站点：
- 如果应用程序有多个进程（Electron main + renderer，Tauri webview + Node sidecars，
工作进程），在每个进程中初始化 SDK；浏览器构建用于 UI 进程，
@kenkaiiii/error-mom/node 用于 Node 进程。一个进程被覆盖就足够了。
- 如果应用程序通过中央处理程序或错误广播函数引导捕获的错误，
在其中调用 errorMom.captureError(err)。
- 包装框架捕获错误本身的处理器（队列/定时任务作业，如 Inngest，Webhook 路由，
MCP 工具）：errorMom.wrap(handlerFn, { culprit: "<作业或路由名称>" })。
对 AI 提供商的失败调用（Anthropic、OpenAI、Kimi、GLM 和约 40 个
更多）会自动捕获并在每个覆盖的进程中自动标记。
5. 通过运行 init 打印的确切医生命令，证明它可以端到端工作。
成功 = 响应显示“accepted”: 1 和“synthetic”: 1。医生的测试事件永远不会显示为
真实错误，因此我的仪表板保持干净。
6. 如果应用程序发布压缩构建（Vite、Next.js 等），请使生产堆栈可读：
在构建中启用源映射，然后在 CI/发布脚本中添加上传步骤：
error-mom login <服务器> --token $ERROR_MOM_ADMIN_TOKEN
error-mom sourcemaps <构建目录> --release <应用程序版本> --project <slug>
释放标志必须与 SDK 报告的释放版本匹配。将管理员令牌放入 CI 机密存储中
（例如 ERROR_MOM_ADMIN_TOKEN）- 它永远不应存在于仓库中。源映射上传需要管理员令牌；
仅写入项目密钥无法上传映射。
证明管道有效：error-mom doctor --symbolication
（将合成的压缩堆栈通过服务器循环，存储
无）。上传命令还会在映射缺少 sourcesContent 或版本与任何报告的事件不匹配时打印警告。
7. 提交更改并确认所有操作都已连接。内置的项目密钥可以安全地提交（仅写入），
但我的管理员令牌永远不应出现在 git 中；请在提交前检查。
```
从现在开始，该应用程序中的每个崩溃都会自动显示在您的仪表板上：分组、计数，并附有发生之前的情况说明。
<details>
<summary><strong>已经连接了一个应用程序？升级它的提示</strong></summary>
```text
将此应用程序的错误妈妈集成升级到最新版本。
1. 使用此项目的包管理器将 @kenkaiiii/error-mom 升级到最新版本，并更新 CLI：npm install -g error-mom
2. 重新运行：error-mom init --skip-install
它重用现有的项目，重新生成带有内置仅写入密钥的设置文件（因此生产/CI 构建无需环境配置即可报告），
并为 Next.js 添加 instrumentation.ts 以进行服务器端错误。重新应用旧设置文件的任何自定义。
3. 审计覆盖范围，然后修复每个空白：
- 每个进程初始化 SDK（UI 进程使用浏览器构建，Node 进程/边车/工作进程使用 @kenkaiiii/error-mom/node）。
- 任何中央错误处理程序或错误广播函数调用 errorMom.captureError(err)。
- 包装框架捕获错误本身的处理器（队列/定时任务作业，Webhook 路由，MCP 工具）使用
errorMom.wrap(fn, { culprit: "<名称>" }）。
4. 如果此应用程序发布压缩构建，请在 CI/发布脚本中添加源映射上传步骤：
error-mom login <服务器> --token $ERROR_MOM_ADMIN_TOKEN
error-mom sourcemaps <构建目录> --release <应用程序版本> --project <slug>
使用 CI 机密存储中的管理员令牌（永远不要在仓库中），以便生产堆栈显示原始文件：行帧。
5. 使用 error-mom doctor 验证，确认管理员令牌不在 git 中
（内置项目密钥可以，安全），然后提交。
```
</details>
## 🔧 提示 3：让您的代理修复错误
在任何时候，将此内容粘贴到编码代理中：
```text
连接到我的错误妈妈并修复我的错误。
我的服务器：https://MY-ERROR-MOM.up.railway.app
我的管理员令牌：MY_ADMIN_TOKEN
1. 确保 error-mom CLI 已安装并登录
（npm install -g error-mom，然后 error-mom login <服务器> --token <令牌>）。
2. 运行：error-mom issues
3. 对于该应用程序中的每个未解决的问题，运行 error-mom inspect <id> 以查看堆栈跟踪和导致问题的步骤，
在代码中找到原因并修复它。
4. 在修复后，使用以下命令标记完成：
error-mom resolve <id> --release <包含修复的应用程序版本>
5. 用纯文字告诉我修复了什么，修复了什么。
```
希望您的代理始终可以使用这些信息？将错误妈妈添加为 MCP 服务器，它具有 `list_issues`、`get_issue` 和 `resolve_issue` 作为内置工具：
```json
{
"mcpServers": {
"error-mom": {
"command": "error-mom",
"args": ["mcp"]
}
}
}
```
## 📊 您如何查看错误
- **仪表板**：您的 Railway URL，使用管理员令牌登录。显示每个未解决的错误，最新的在前，带有计数。
- **询问您的代理**：一旦登录或通过 MCP 连接，请说“检查错误妈妈”。
您不必思考的好东西：
- 同一个崩溃发生 500 次，显示为 **1** 个问题，计数为 500。
- 密码、令牌和 API 密钥在存储之前会被清理。
- 已修复的问题从默认视图中消失；如果一个“修复”的错误在新版本中再次出现，它会自动重新打开为 **回归**。
- 如果您的应用程序离线，错误会本地排队并稍后发送。跟踪永远不会崩溃或减慢应用程序。
---
## 👥 社区
- **YouTube**：[@kenkaidoesai](https://youtube.com/@kenkaidoesai)，用于教程和演示
- **Skool**：[skool.com/kenkai](https://skool.com/kenkai)，来这里聊天
---
## 🛠️ 开发者
<details>
<summary>仓库布局、本地开发和手动设置</summary>
### 提供的内容
- `apps/web`：Next.js 仪表板、摄入 API、代理 API、身份验证、自动 PostgreSQL 架构设置。
- `packages/sdk` (`@kenkaiiii/error-mom`）：自动浏览器和 Node.js 捕获，带有编辑、面包屑、重试、持久队列。
- `packages/cli` (`error-mom`）：项目设置、诊断、问题操作、MCP stdio 服务器。
- `packages/protocol`：收集器和 SDK 共享的验证事件合约。
### 本地运行
```bash
cp .env.example apps/web/.env.local
# 将 ERROR_MOM_ADMIN_TOKEN 替换为至少 32 个随机字符。
docker compose up -d
pnpm install
pnpm db:seed # 可选：3 个项目和 9 个现实问题
pnpm dev
```
打开 `http://localhost:3000` 并输入管理员令牌。
### 手动 SDK 设置
浏览器（以 Vite 为例）：
```ts
import { initErrorMom } from "@kenkaiiii/error-mom";
export const errorMom = initErrorMom({
server: import.meta.env.VITE_ERROR_MOM_SERVER,
projectKey: import.meta.env.VITE_ERROR_MOM_PROJECT_KEY,
environment: import.meta.env.MODE,
release: import.meta.env.VITE_APP_VERSION,
});
```
捕获未捕获的错误、未处理的拒绝、`console.error`、失败的网络请求以及发生故障前 50 个面包屑。事件排队到本地存储并重试而不会阻塞应用程序。
Node：
```ts
import { initErrorMom } from "@kenkaiiii/error-mom/node";
export const errorMom = initErrorMom({
server: process.env.ERROR_MOM_SERVER!,
projectKey: process.env.ERROR_MOM_PROJECT_KEY!,
environment: process.env.NODE_ENV,
release: process.env.APP_VERSION,
});
```
节点事件追加到 `~/.error-mom/spool/*.jsonl` 之前上传；中断不会丢弃排队的错误。
### CLI
```bash
error-mom projects
error-mom issues
error-mom inspect issue_123
error-mom resolve issue_123 --release 1.4.2
error-mom doctor --project-key em_ingest_...
```
### 问题生命周期
事件被规范化和指纹识别，从错误类型、消息形状和顶部堆栈帧中获取。工具失败使用其稳定的 `tool.*` 原因而不是编排帧，因此应用程序版本不会将一个失败分成重复项。重复的指纹增加 `quantity` 而不是创建重复的行。
预期配额、瞬时轮询或订阅使用失败以及低容量工具失败首先显示为 `observed`，在第三次出现时保持在默认未解决队列中，样本包括收集器分类标签和重试上下文。解决记录 `fixedInRelease`；在该版本或更新版本中再次出现会将问题重新打开为 `regressed`。
### 安全模型
- 项目摄入密钥仅写入，在 PostgreSQL 中哈希并显示一次。
- 仪表板和读写代理 API 使用单独的私有管理员令牌。
- 密钥字段、电子邮件、查询凭证、URL 用户信息、Telegram 机器人令牌、Discord 和 Slack Webhook 凭证以及标记的凭证路径在 SDK 和收集器中都会被编辑。
- 浏览器摄入允许跨源写入，因为发布的浏览器密钥本质上是公开的；这些密钥无法读取或解决问题的。
- 医生合成事件被验证并限速，但永远不会持久为问题。
### 验证
```bash
pnpm check
pnpm test
pnpm build
pnpm format:check
```
</details>
## 📄 许可证
MIT
---
<p align="center">
<strong>崩溃，修复。妈妈有你。 👩🔧</strong>
</p>
