内容
<div align="center">
# 智慧日志
**AI 原生错误智能 - 结构化、本地、可查询的错误日志，适用于任何 MCP 助手。**
[](LICENSE)
[](https://www.npmjs.com/package/@all-wits/witslog)
[](https://github.com/all-wits/witslog/actions/workflows/release-node-sdk.yml)
[](https://www.rust-lang.org/)
[](https://sqlite.org/)
**无需嵌入。无需云服务。无需基础设施。**
</div>
---
错误被捕获为**结构化事件**（而非文本行），存储在每个项目的本地 SQLite 数据库中，支持全文搜索，并由确定性分类引擎自动分类，通过 **MCP** （模型上下文协议）暴露给 AI 助手，以便 LLM 可以搜索、关联和推理错误历史，而无需您编写任何查询。
## ✨ 功能
- 🗄️ **每个项目的 SQLite** - 一个 `.witslog/witslog.db`，WAL 模式，无需外部服务。
- 🔍 **全文搜索** - FTS5，bm25 排名，支持前缀/短语/布尔/NEAR 查询。
- 🏷️ **确定性分类** - 基于规则的自动分类，无需模型/嵌入。
- 🔒 **内置数据脱敏** - 在数据写入磁盘之前，移除敏感信息/个人身份信息。
- 🔗 **关联和指纹识别** - 去除重复错误，跟踪因果链。
- 🤖 **MCP 服务器** - 13 个读取工具 + 1 个受控写入工具，适用于任何 MCP 兼容的助手。
- 🌍 **跨语言 SDK** - Node、Python、PHP/Laravel，通过共享的 C ABI。
- ⏱️ **解决跟踪和 MTTR** - 标记错误为已解决，过滤未解决的积压，计算指纹级别的平均解决时间。
- 🔔 **通知器** - 基于文件的（NDJSON）新事件通知，超过严重性阈值，按指纹限流。可通过 `witslog-plugin` 的 `Notifier` 特性扩展。
- 🌐 **浏览器端错误捕获** - 一个零依赖的客户端报告器，将 `window.onerror` / 未处理的拒绝批次发送到一个受保护的服务器端摄入端点，以便客户端和服务器错误进入同一个可查询的数据库。
## 📦 安装
### CLI（Rust）
```bash
# Linux/macOS 安装程序（检测 OS/arch，验证校验和，放置在 PATH 上）
curl -fsSL https://raw.githubusercontent.com/all-wits/witslog/main/install/install.sh | sh
# Windows（PowerShell）
irm https://raw.githubusercontent.com/all-wits/witslog/main/install/install.ps1 | iex
# 从源码编译（开发）
cargo install --path crates/witslog-cli
```
参见 [docs/install.md](docs/install.md) 获取包管理器选项、升级和卸载。
### SDK
| 语言 | 包 | 安装 |
| --- | --- | --- |
| **Node.js** | [`@all-wits/witslog`](bindings/node) | `npm install @all-wits/witslog` · `pnpm add @all-wits/witslog` · `bun add @all-wits/witslog` |
| **Python** | [`witslog`](bindings/python) | `pip install witslog` |
| **PHP / Laravel** | [`witslog/witslog`](bindings/php) | `composer require witslog/witslog` |
每个 SDK 都是一个**框架无关的核心**，位于原生 C ABI（`witslog-ffi`）之上 - 无需云调用，无需遥测。参见每个包的 README 获取框架适配器（Express、FastAPI、Django、Flask、Laravel）和 [SDK↔原生合约](bindings/CONTRACT.md)。
## 🚀 快速开始
### 初始化项目
```bash
witslog init .
```
在当前目录下创建 `./.witslog/witslog.db`。
### 记录事件
```bash
witslog log app "connection timeout" --error-code ETIMEDOUT --severity error
```
### 搜索和检查
```bash
witslog query "timeout*" --severity error
witslog query --unresolved # 仅显示未解决的积压
witslog resolve <event_id> # 标记为已解决（幂等；--force 覆盖）
witslog stats
witslog stats --mttr # 指纹级别的平均解决时间
witslog serve-mcp --stdio # 向 MCP 兼容的 AI 助手公开日志
witslog doctor # 二进制版本，最大支持的模式，数据库健康检查
witslog doctor --verify-audit # 重新计算防篡改审计哈希链
```
### 从应用程序（Node 示例）
```js
const witslog = require('@all-wits/witslog');
witslog.init({ createProject: true }); // 如果缺少，创建 .witslog/，然后挂载
witslog.error('my-app', 'out of memory', { context: { pid: process.pid } });
```
`createProject` 表示仅需 `npm install` 即可开始 - 无需单独的 CLI 安装来启动项目。参见 [bindings/node](bindings/node)、[bindings/python](bindings/python) 和 [bindings/php](bindings/php) 获取 Python/PHP 等价项（目前仍需要 CLI 的 `witslog init`）。
> **⚠️ 使用 Next.js？** 其默认打包会破坏 Node SDK 的原生 `koffi` 插件解析 - 参见 [Node SDK README 的 Next.js 部分](bindings/node/README.md#-works-with-your-nodejs-stack) 获取所需的 `serverExternalPackages` 配置。
### 浏览器端错误捕获
客户端渲染的 JS 错误（`window.onerror`，未处理的 promise 拒绝）通过一个零依赖的报告器 + 一个受保护的服务器端摄入端点加入同一个数据库 - 无需原生/FFI 代码在浏览器中运行。
```html
<script src="witslog-browser.js"></script>
<script>
WitslogBrowser.init({ endpoint: '/__witslog', app: 'my-web-app' });
</script>
```
```js
// Express，服务器端 - 参见 bindings/CONTRACT.md 获取 Python/PHP 配方
const { witslogBrowserIngest } = require('@all-wits/witslog/frameworks/express');
app.use(witslogBrowserIngest({ allowedOrigins: ['https://your-app.example'] }));
```
默认情况下安全关闭：空源允许列表（您必须选择自己的源），除非强制，否则拒绝在 `NODE_ENV=production` 下运行，限流，严重性限制为 `error`/`warn` - 端点接受未经信任的文本，最终存储在 `events.message` 中，MCP 原样提供给 AI 助手。参见 [bindings/browser](bindings/browser) 和 [bindings/CONTRACT.md](bindings/CONTRACT.md) 的“浏览器端错误捕获”部分。
## 🧭 状态
预 1.0。核心日志、存储、分类、搜索、MCP 服务器、SDK、性能强化、可扩展性和 MTTR/通知器/浏览器捕获已发布并测试；打包（P8）正在进行中。
| 阶段 | 内容 | 状态 |
| --- | --- | --- |
| P0 | 存储 + 事件模型，CLI 核心，C ABI | ✅ |
| P1 | 丰富，数据脱敏，异步缓冲 | ✅ |
| P2 | 分类引擎（自动分类） | ✅ |
| P3 | FTS5 + 查询引擎（搜索/聚合/关联） | ✅ |
| P4 | CLI 实用程序（导出/导入/修剪/存档/备份/...） | 🟡 缺少全局 `--json` |
| P5 | MCP 服务器（13 个工具，JSON-RPC/stdio） | ✅ |
| P6 | SDK 绑定（Node/Python/PHP + 框架适配器） | ✅ |
| P7 | 性能基准 + 并发强化 | ✅ |
| P8 | 打包 + 跨平台安装 | 🟡 安装脚本 + 发布 CI + 烟雾测试已发布，在 GitHub Actions 上验证绿色；尚未发布 |
| P9 | 可扩展性（插件）+ 安全性（加密，防篡改审计链） | ✅ |
| P10 | MTTR/解决跟踪，通知器，浏览器端错误捕获 | ✅ |
参见 [CHANGELOG.md](CHANGELOG.md) 获取发行说明，[PHASES.md](PHASES.md) 获取详细的分阶段规格。
## 🏗️ 架构
```
应用程序代码（任何语言）
↓ SDK / 原生 EventBuilder
丰富 → 数据脱敏 → 分类 → 构建
↓
SQLite（WAL 模式，每个项目）
├─ events（仅追加，非规范化 + FTS5）
├─ categories（分类树）
├─ fingerprints（去重/汇总）
├─ error_edges（因果图）
└─ schema_meta + 迁移
↓
只读访问：
├─ CLI（init，query，stats，export，...）
├─ MCP 服务器（用于 AI 助手的 JSON-RPC 工具）
└─ Analytics（趋势，MTTR）
```
**单一真相来源**：本地 SQLite 文件。无需同步，无需云服务，完全控制。
## 🤖 与 AI（MCP）集成
```bash
witslog serve-mcp --stdio
```
作为 stdio JSON-RPC 服务器运行。任何 MCP 兼容的客户端（Claude，其他 LLM）都可以调用：
`search_errors` · `latest_errors` · `summarize_errors` · `classify_error` · `explain_error` ·
`similar_errors` · `list_categories` · `statistics` · `timeline` · `top_failures` · `mttr` ·
`list_traces` · `search_all`（选择加入联合）· `witslog_delete`（受控，写入）
> 没有用于解决的写入工具，刻意为之 - `witslog_delete`（在 `--allow-write` 后台运行）是唯一的写入工具。解决工具将允许代理静默地为 `witslog_delete` 的默认 `resolved_at IS NOT NULL` 过滤器限定事件。
MCP 客户端注册代码段 - 直接生成（填充已解析的二进制路径和项目 `cwd`）：
```bash
witslog serve-mcp --print-mcp-config
```
```json
{
"mcpServers": {
"witslog": {
"command": "witslog",
"args": ["serve-mcp", "--stdio"],
"cwd": "/path/to/your/project"
}
}
}
```
> **⚠️ 使用全局安装的 CLI（[curl/irm](#install)，Homebrew，Scoop 或 `cargo install`）来生成此配置 - 而不是 Node SDK 的 npm 捆绑二进制文件。** 两个原因：
> 1. **macOS Intel 没有 npm 捆绑 CLI。** `release-node-sdk.yml`（npm 的二进制源）删除了 `macos-13`/Intel - 参见 [已知限制](CHANGELOG.md#known-limitations)。`release.yml`（curl/irm/cargo 二进制源）构建它。在 Intel Mac 上，全局安装的 CLI 是获取 `serve-mcp` 的*唯一*方式。
> 2. 生成的 `command` 是绝对路径（`std::env::current_exe()`）- 如果它来自项目的 `node_modules/@all-wits/witslog/_bin/`，则 MCP 配置在项目的 `node_modules` 被删除或重新安装到其他位置时就会中断。全局安装的 CLI 的路径是稳定的，与任何一个项目无关。
## 🏷️ 分类
**内置分类**（基础设施/应用程序/运行时/外部）：
```
infrastructure.network.{dns, timeout, connection}
infrastructure.storage.{disk, database}
infrastructure.compute.{memory, cpu}
application.{error, validation, authentication, authorization}
runtime.{panic, segfault, outofmemory}
external.{api.rate_limit, service}
```
**自动分类规则**（确定性，按顺序）：错误代码映射 → 异常类型映射 → 消息关键词/正则表达式。无匹配 → `category: null`，标记为 `unclassified`。
## ⚡ 性能目标
| 指标 | 目标 |
| --- | --- |
| 缓冲日志调用 | < 100 µs |
| 单写入器吞吐量 | ≥ 10k 事件/秒 |
| 搜索 100k 事件 | < 50 毫秒 |
| 分类 | < 50 µs |
| 空闲 CLI 内存 | < 15 MB |
| 空闲 MCP 服务器内存 | < 30 MB |
（在 P7 中测量；正在进行的目标。）
## 🛠️ 开发
参见 **[CLAUDE.md](CLAUDE.md)** 获取架构、代码库映射和约定。
**[PLAN.md](PLAN.md)** 包含完整规格； **[PHASES.md](PHASES.md)** 包含按阶段划分的需求。
```bash
# 构建所有
cargo build --workspace
# 测试（Rust 代码库）
cargo test --workspace
# 测试 SDK
py -m pytest bindings/python/tests # Python
pnpm --dir bindings/node test # Node
composer test --working-dir=bindings/php # PHP
# 跨语言回归驱动程序
pwsh bindings/e2e/run.ps1
# 校验
cargo clippy --workspace
```
## 📄 许可证
Apache License 2.0。参见 [LICENSE](LICENSE)。
## 🤝 贡献
尚未接受外部 PR（预 1.0）。问题和反馈欢迎。
---
<div align="center">
**了解更多**：[PLAN.md](PLAN.md)（设计文档）· [PHASES.md](PHASES.md)（阶段路线图）·
[CLAUDE.md](CLAUDE.md)（开发指南）· [CHANGELOG.md](CHANGELOG.md)（发行说明）·
[bindings/CONTRACT.md](bindings/CONTRACT.md)（SDK↔原生 ABI）
</div>
