# @reneturcios/loglens 中文文档

规范地址：https://npmcn.com/package/%40reneturcios/loglens/

版本：0\.1\.0
npm 元数据更新时间：2026-11-02T06:43:22.754Z
中文译文更新时间：2026-11-02T08:19:24.505Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40reneturcios/loglens
原文对照：https://npmcn.com/package/%40reneturcios/loglens/?lang=original
项目主页：https://github.com/CloudCorpRecords/loglens#readme
源码仓库：https://github.com/CloudCorpRecords/loglens

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：52.9 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-11-02T06:42:06.476Z
- 最新版本发布：2026-11-02T06:43:22.548Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

Homelab对本地JSONL日志文件的日志调查：状态、尾部、错误、子字符串搜索、每小时或每天的时间表，以及周围的上下文。一个bin提供一个小型CLI和一个studio MCP服务器，提供单个操作分派工具。

## 安装

```sh
npm install @reneturcios/loglens
```

也可以使用：`pnpm add @reneturcios/loglens`、`yarn add @reneturcios/loglens`、`bun add @reneturcios/loglens`

## README

# loglens

Loglens调查了保存在本地文件中的homelab日志 存储，最近到达的，错误的，提到的 一个术语，体积是如何随时间分布的，以及A的周围是什么 的时刻。一个二进制文件提供命令行接口和工作室MCP 服务器公开单个操作分派工具； `cortex`.

这是一个标记的核心子集。它被模仿的工具 调度60个目录操作；Loglens实现了其中的7个 `status`， `tail`， `errors`， `search`， `timeline`， `context`, `help` -并省略了其他53个（舰队和拓扑视图，人工智能） 会话分析，相关性和异常分析，错误 确认、通知和管理)。这个 `help` Action列出了实现的子集和省略的操作 运行时。

## 日志文件

记录保存在JSONL文件中：每行一个JSON对象，每个对象都有 `ts` （ISO-8601时间戳）， `level`， `source`, `message`：

```json
{"ts":"2026-10-26T09:15:00.000Z","level":"info","source":"docker/web","message":"container started"}
{"ts":"2026-10-26T09:16:12.000Z","level":"error","source":"syslog","message":"disk almost full"}
```

路径来自 `--file` 设置为 `LOGLENS_LOG_FILE` 那么，是环境变量 `./loglens.jsonl`. 格式错误的行（错误的JSON，缺少字段，无法解析的时间戳） 被跳过和计算，从不致命。丢失的文件是一个清理 数据操作错误； `status` 相反，报告存储状态 与 `exists: false`, `help` 根本不需要储存。所有的逻辑 是本地的和确定的-没有网络访问，永远。

## 安装

```bash
npx @reneturcios/loglens status
```

或者运行容器镜像：

```bash
docker run -i ghcr.io/cloudcorprecords/loglens
```

容器默认为MCP服务器（见下文）。通过CLI 参数将其用作CLI。挂载日志文件并设置 `LOGLENS_LOG_FILE` 到它的容器内路径。

## 命令行界面

```bash
export LOGLENS_LOG_FILE=/var/log/homelab.jsonl

loglens status
loglens tail --limit 5 --source docker/web
loglens errors --limit 10
loglens search "disk" --since 2026-10-26T00:00:00.000Z
loglens timeline --bucket day
loglens context 2026-10-26T09:16:12.000Z --window-minutes 5
loglens context 12 --limit 3
loglens help

loglens --version
```

命令打印JSON结果。 `tail`， `errors`, `search` 优先返回记录最新的； `context` 在文件中返回它们 秩序。 `context` 接受时间戳(记录在 `--window-minutes` 它的，或者 `--limit` 最近的记录 最接近的一个)或一个裸记录索引( `--limit` 记录 立场的任何一方)。退出代码: `0` 成功, `1` 当操作失败（包括丢失日志文件）时， `2` 用于 使用错误。

## MCP服务器

一个箱子能同时满足两个人的需要。这个 `mcp` subcommand启动stdio MCP 服务器:

```bash
npx -y @reneturcios/loglens mcp
```

MCP客户端配置：

```json
{
  "mcpServers": {
    "loglens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/loglens", "mcp"],
      "env": { "LOGLENS_LOG_FILE": "/absolute/path/to/logs.jsonl" }
    }
  }
}
```

### 工具

| 工具 | 输入 | 它返回什么 |
| --- | --- | --- |
| `cortex` | `action` (必需的，其中之一 `status`， `tail`， `errors`， `search`， `timeline`， `context`， `help`)，加上可选 `query`， `source`， `level`， `limit`， `since`， `until`， `bucket` （`hour` 或者 `day`)， `timestamp`， `window_minutes` | 每个操作：存储摘要、最新匹配记录、每小时/每天的量桶、某个时刻的记录或子集帮助文本。 |

一个有用的第一个电话是 `{"action":"status"}`，然后缩小到 `tail`， `errors`， `search`， `timeline`，或者 `context`.

## 开发

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, real temp JSONL files, no network
npm run dev     # run the CLI from source via tsx
```

## 许可证

MIT -见 `LICENSE`.

## 常见问题

### @reneturcios/loglens 是什么？

Homelab对本地JSONL日志文件的日志调查：状态、尾部、错误、子字符串搜索、每小时或每天的时间表，以及周围的上下文。一个bin提供一个小型CLI和一个studio MCP服务器，提供单个操作分派工具。

### 如何安装 @reneturcios/loglens？

在项目目录运行 npm install @reneturcios/loglens，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 loglens，可以用 npx loglens 直接运行。

### @reneturcios/loglens 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/reneturcios\_\_loglens 是否存在。

### @reneturcios/loglens 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @reneturcios/loglens 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @reneturcios/loglens 可以商用吗？

@reneturcios/loglens 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @reneturcios/loglens 还在维护吗？

最新版本 0\.1\.0 发布于 2026/11/02（1 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。