dsh-stdio-logger

dsh 桌面壳的日志桥插件（host-only）：注册 cordis logger exporter，把宿主核心与全部插件的结构化日志镜像到进程 stdout（桌面壳管道捕获写入 logs/dsh-plugins.log），并在 $DSH_HOME/logs/dsh-plugins.log 落一份持久文件，让不带壳的裸 dsh web 运行也有完整日志。

快速开始

本插件随桌面壳内置并自动安装（ensureBuiltinPlugins 标准链）。开发调试：

cd packages/dsh-stdio-logger
# 在插件目录内运行，file:$PWD 自动展开为当前绝对路径（必须 file: 而非 link:）：
dsh plugin --profile web add file:$PWD

安装后重启 dsh web 进程生效；启动日志出现 attached; verbosity cap: warn 一行即 exporter 链路已接通。

能力

| 项目 | 说明 | | --- | --- | | 双路输出 | 每行同时写 stdout 与文件；文件在 2 MB 处轮转为 .1.log（保留一份备份）；Windows 上轮转改名失败时退化为原地截断并告警一次，日志始终有界 | | 脱敏 | token= / auth= / key= 等查询参数在写边界统一替换为 <redacted>，壳日志、本插件落盘与裸终端都看不到明文凭据 | | 行格式 | <本地ISO时间> [level] [plugin-name] message，与壳自身日志一致；多行消息（异常堆栈）每行都带完整前缀，避免壳侧重新盖章把堆栈帧误标为 [info] | | 冗长度 | 默认上限 warn（= error + info + warn），debug 需显式开启；exporter 层面抬高内核门禁，由本插件统一裁决 | | 健壮性 | stdout 管道断开（EPIPE）有常驻错误处理不崩进程；单行超过 10240 字符截断；文件/目录权限收紧（0o600 / 0o700）；热路径无每行系统调用 | | 自愈与可诊断 | 日志目录在运行中被删除后，下一行会自动重建目录并重试该行（不再整进程 ENOENT 失败）；写盘失败每进程只告警一次，ENOSPC/EDQUOT 会明确指出「磁盘已满或超额」，stdout 始终不受影响 |

配置

| 环境变量 | 默认 | 说明 | | --- | --- | --- | | DSH_STDIO_LOG_LEVEL | warn | 输出冗长度上限：error / info / warn / debug | | DSH_STDIO_LOG_FILE | 1 | 0/false 关闭文件落盘（仅 stdout）；显式路径则写到该文件；留空等价于未设置（用默认路径） |

原理一句话

通过 ctx.logger.exporter 注册全树唯一的 exporter（levels.default=3 抬高 cordis 内核门禁），每条结构化消息按统一行格式盖章后先脱敏再写两个 sink；实现见 src/index.mjs。

文档

| 文档 | 内容 | | --- | --- | | ../../docs/PACKAGE-TEMPLATE.md | 本仓库插件包统一规范 |

测试

node test/stdio-logger.test.js            # 冗长度/脱敏/多行/截断/占位符/env 语义/目录自愈/磁盘错误（9 条）
node test/integration-plugins-log.test.js # 真实 dsh web 后端全链路冒烟（需沙箱升级）
node test/isolated-install-cycle.test.js  # 隔离 DSH_HOME 安装/卸载循环 + 启动冒烟（需沙箱升级）

版本与兼容

包名 dsh-stdio-logger · MIT · 目标 DSH 0.1.5-rc.2（隔离环境实测：标准链安装/卸载/启动挂载均通过）。

• 0.1.2（当前）：日志目录自愈（运行中目录被删后下一行自动重建并重试，不再整进程 ENOENT 失败）；磁盘类错误（ENOSPC/EDQUOT）在告警里明确指出「磁盘已满或超额」；stdout 错误监听改为每进程只注册一次（重复 apply / 重复 import 不再累积监听器）。
• 0.1.1：默认冗长度上限 info → warn（旧默认把 warn 日志也丢掉）；写边界统一脱敏；async EPIPE 常驻处理；单行 10240 截断；轮转失败原地截断；多行消息每行带统一前缀；热路径去每行系统调用；% 占位符只在首参为字符串时扫描；空 DSH_STDIO_LOG_FILE= 视同未设置；补齐 README/LICENSE。
• 0.1.0：初版（exporter 注册 + stdout/文件双 sink + 2MB 轮转）。

元信息与文档结构遵循 docs/PACKAGE-TEMPLATE.md。