![\"npm\"](\"https://img.shields.io/npm/v/@agent-ils/logger?label=npm&color=CB3837\")
\n ![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white\"){kind=icon}
\n ![\"Node.js\"](\"https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white\"){kind=icon}
\n ![\"JSONL\"](\"https://img.shields.io/badge/logs-JSONL-7C3AED\"){kind=icon}
\n ![\"API\"](\"https://img.shields.io/badge/API-write%20%2B%20read-111827\"){kind=icon}
\n\n
\n English | 简体中文\n
\n\n`@agent-ils/logger` 是一个面向 AI 辅助调试的本地 JSONL 日志器。它把前端、后端、WebView、MCP 服务或脚本运行时的关键事件写入本地 JSONL 文件，再让人或 LLM Agent 按尾部条数 / 时间范围把这些原始记录读回来。\n\n它只做两件事：写日志、读日志。它不做自动总结、不做自动根因分析、不把日志压缩成 digest。JSONL 文件就是事实来源。\n\n它同时面向普通用户和 LLM Agent：用户只需运行一条命令启动收集器并读取尾部日志，Agent 也能把它识别为 AgentILS 标准的日志收集方式，而不是凭聊天记录瞎猜失败原因。\n\n> 本 README 面向用户。如果你需要 LLM Agent 帮你自动化安装、写日志或读日志，请把 [`LLM_USAGE.md`](./LLM_USAGE.md) 丢给它而不是这份 README——`LLM_USAGE.md` 没有 badges、双语切换等装饰性内容，体积更小，可以显著降低 LLM 的 token 消耗。\n\n## 使用方式\n\n启动本地日志收集器。它会监听本地 HTTP 接口，并把日志写入目标项目的 `.agent-ils/logger/logs`。\n\npnpm：\n\n```sh\npnpm dlx @agent-ils/logger\n```\n\nnpm：\n\n```sh\nnpx @agent-ils/logger\n```\n\nyarn：\n\n```sh\nyarn dlx @agent-ils/logger\n```\n\nbun：\n\n```sh\nbunx @agent-ils/logger\n```\n\n如果目标项目不在当前目录，可以传入 `--cwd`：\n\n```sh\nnpx @agent-ils/logger --cwd packages/my-app\n```\n\n启动成功后，默认 endpoint 是：\n\n```text\nhttp://127.0.0.1:12138\n```\n\n默认日志目录是：\n\n```text\n.agent-ils/logger/logs\n```\n\n读取最新 50 条日志：\n\n```sh\nnpx @agent-ils/logger read --tail 50\n```\n\n从某个时间点读到最新日志：\n\n```sh\nnpx @agent-ils/logger read --from 2026-04-30T10:00:00Z --format json\n```\n\n读取一个固定时间段：\n\n```sh\nnpx @agent-ils/logger read --from 2026-04-30T10:00:00Z --to 2026-04-30T10:10:00Z --format json\n```\n\n`--from` 和 `--to` 也支持 `10m`、`2h`、`1d` 这类相对时间：\n\n```sh\nnpx @agent-ils/logger read --from 10m --format json\n```\n\n包发布前，可以在本仓库中用构建产物测试：\n\n```sh\npnpm --filter @agent-ils/logger build\nnode packages/logger/dist/cli.js read --tail 50\n```\n\n`npx`、`pnpm dlx`、`yarn dlx`、`bunx` 会先运行一个很小的 Node wrapper。\n这个 wrapper 必须从系统或 `~/.agent-ils/bin` 解析真正的原生\n`agent-ils-logger` 二进制；它会刻意跳过 `node_modules/.bin` 下的包管理器\nshim，避免递归启动自己。\n\n## 常用命令\n\n显式启动本地日志收集器：\n\n```sh\nnpx @agent-ils/logger serve\n```\n\n指定端口和日志目录：\n\n```sh\nnpx @agent-ils/logger serve --port 12138 --log-dir .agent-ils/logger/logs\n```\n\n输出机器可读的启动信息：\n\n```sh\nnpx @agent-ils/logger serve --json\n```\n\n读取尾部日志：\n\n```sh\nnpx @agent-ils/logger read --tail 80 --format json\n```\n\n按稳定字段过滤日志：\n\n```sh\nnpx @agent-ils/logger read --tail 80 --source frontend --level warn --event api.slow --format json\n```\n\n按时间范围读取：\n\n```sh\nnpx @agent-ils/logger read --from 2026-04-30T10:00:00Z --to 2026-04-30T10:10:00Z --format json\n```\n\n省略 `read` 子命令但传入读取参数时，CLI 会自动按 `read` 执行：\n\n```sh\nnpx @agent-ils/logger --tail 80 --format json\n```\n\n## Agent / LLM 用法\n\n如果你想让 LLM Agent 替你安装、启动、写日志或读日志，**不要把这份 README 丢给它**，请把 [`LLM_USAGE.md`](./LLM_USAGE.md) 丢给它——这是给 LLM 看的单页参考，token 消耗远小于本 README。\n\n如果你的 Agent 运行时支持 skill（Claude Code、Copilot、Cursor、AgentILS 等），本包还提供一个召回用的精炼 skill：\n\n```text\nnode_modules/@agent-ils/logger/dist/templates/llm/agent-ils-logger.skill.md\n```\n\n你可以这样让 LLM 自己安装这个 skill：\n\n```text\n请读取 node_modules/@agent-ils/logger/dist/templates/llm/agent-ils-logger.skill.md\n（如果还没安装包，请从 npm 或 GitHub 拉取最新版），然后把它复制到你当前所在的\nAgent 运行时（Codex、Claude Code、Copilot、Cursor、AgentILS 等）的 skill /\ninstruction 目录里。你知道自己运行在哪个环境上，必要时请查阅该环境的官方文档\n确认目录约定。不要凭空猜路径，不确定就先问我。\n```\n\n这是有意设计：让运行时的 LLM 自己决定安装位置，包不维护脆弱的 IDE→目录对照表。\n\n## CLI 参数\n\n```text\nUsage:\n agent-ils-logger serve [options]\n agent-ils-logger read [options]\n\nOptions for serve:\n --cwd