前言¶
DSH 通过插件扩展 Host 和客户端能力。排查运行时问题时，Host 侧 Cordis logger 的输出如果只存在于进程日志里，查看和回放都不够方便。dsh-logger-panel 把这部分输出接到 Settings > Logs 页面，通过 SSE 提供 live 视图，同时把记录写入有日期和大小限制的 JSONL 文件。
这是什么¶
dsh-logger-panel 是一个 DSH 插件：捕获 Host 的 Cordis logger 输出，在 Web profile 的设置页中实时查看，并持久化到轮转 JSONL 文件。仓库地址为 https://github.com/LingLambda/dsh-logger-panel，许可证为 MIT，package.json 中版本为 0.2.0，packageManager 为 yarn@4.15.0。
它是一个 dsh bundle：package.json 将 dsh.bundle 指向 cordis.patch.yml，并声明 dsh.client，让 Web profile 自动发现浏览器侧 bundle。
运行要求¶
先确认环境满足以下要求：
- DSH 带 Web profile，包括
dsh-client-ui-settings提供的 Settings shell、client module system 和dsh-host-webserver；版本为0.1.0-rc.6或更新。 - Node 版本为
^22.19 || >=24。
核心功能¶
下面介绍插件的主要能力：
- 捕获 Host 的 Cordis logger 输出，并通过 SSE 送到
Settings > Logs页面。 - live 视图使用 snapshot，并按
100 ms批量追加记录。 - 页面把记录渲染为纯文本；原始 logger 参数、Fiber 引用、ANSI escapes 和 executable markup 不会经过浏览器 wire。
- 底部 auto-follow 在向上滚动时暂停，点击
Latest恢复。 - 点击
Load older后，从轮转后的 JSONL 文件中读取历史记录，可跨轮转和日期。 - Host 为连接中的浏览器保留最近
2000条记录。 - 持久化文件名为
YYYY-MM-DD-N.jsonl，按日期和大小轮转；单个文件上限为5 MiB，超过30天的文件会被移除。 - 日志目录默认为
$DSH_HOME/logs/dsh-logger-panel，目录权限为0700，文件权限为0600。 - 磁盘队列上限为
1000条；持久化失败时，面板会报告失败，live stream 继续工作，被省略的记录会被计数。 - 初次创建目录或打开文件失败会拒绝插件激活；后续写入失败会停止持久化，并在面板中报告，同时保留 in-memory/SSE 路径。
安装与启用¶
安装前先确认上面的运行要求。示例使用 demo profile；实际 profile 名称需要按环境调整。
按 npm 安装示例：
dsh plugin --profile demo add dsh-logger-panel
dsh --profile demo
第一条命令把插件加入 profile，第二条命令启动 DSH。经过上面的步骤，可以在 Settings > Logs 中查看日志。
按 git 安装：
dsh plugin --profile demo add github:LingLambda/dsh-logger-panel#<sha>
这里的 <sha> 是 README 示例中的占位符，需要按实际提交填写。安装前还需要在 profile 的 pnpm-workspace.yaml 中授权构建。
本地开发时，可以针对 Harness checkout 使用 overlay：
pnpm dsh web --patch ./cordis.patch.yml --patch /absolute/path/to/dsh-logger-panel/overlay.yml
overlay 示例：
- insert:
- id: logger-panel
name: /absolute/path/to/dsh-logger-panel/src/index.ts
这个 overlay 会插入 logger-panel，并指向本地源码入口。
典型用法¶
打开 Settings > Logs 后，可以直接查看 live 日志。
常用操作：
- 点击
Load older：读取更早的轮转 JSONL 记录。 - 向上滚动：auto-follow 暂停，便于查看当前窗口。
- 点击
Latest：恢复跟随最新日志。
如果需要覆盖默认行为，可以在 profile patch 中修改 logger-panel 的 config。已给出的配置项包括：
root、maxRecords、maxRecordChars、batchMs、maxFileBytes、maxAgeDays、maxPendingRecords、historyPageSize
其中明确给出的默认或限额为：root 默认指向 $DSH_HOME/logs/dsh-logger-panel，maxRecords 为 2000，batchMs 为 100，maxAgeDays 为 30，maxPendingRecords 为 1000，单个 JSONL 文件上限为 5 MiB。
适用场景与注意¶
这个插件适合需要实时查看 DSH Host 日志，并保留一段可回查历史的场景。live 窗口有内存限制，历史分页则从轮转文件读取。
使用前注意：
- 插件以当前 dsh 进程权限运行；安装前应检查源码、构建方式和许可证。
- 日志会写入
$DSH_HOME/logs/dsh-logger-panel；目录权限为0700，文件权限为0600。 - 如果磁盘写入失败，live 查看仍可继续，但历史持久化会停止，面板中会显示失败状态，并且被省略的记录会被计数。
链接¶
DSH 社区目录是独立站点，本文不把它描述为官方应用商店。
- 仓库：
https://github.com/LingLambda/dsh-logger-panel - 目录页：未随文提供固定 URL；可在 DSH 社区目录中按
dsh-logger-panel检索。
