日志桥接 desanv01/dsh-plugin-log-bridge

dsh-plugin-log-bridge

一个 DeepSeek Harness 插件，把 harness 自身的运行时警告和错误写到 stderr，这样启动之后失败的引导过程就能说明原因。

harness 把日志记录保存在内存环形缓冲区里，不导出到任何地方。启动之后发生的错误——会话无法激活、预设挂载失败——进程一退出就不留痕迹，于是监管进程的一方只能报告引导失败了，说不出为什么。警告更糟：默认导出级别会把它们从环形缓冲区里整个过滤掉。

这个插件挂上一个导出器，把每条 error 和 warn 写到 stderr，任何监管进程本来就会捕获它，并用同样的方式记录会话激活失败。

项目状态： 1.0.0。已在编写时针对的 DeepSeek Harness 0.1.x 组合上验证，并在打包它的桌面应用中实际跑过。尚未在官方 DeepSeek Harness 桌面应用（0.2.0-rc.2）中验证——这项验证还在等待。插件没有 UI，也不依赖其他包，所以它触及的面很小。

为什么需要它

harness 启动失败的时候，恰恰是最不能没有诊断信息的时候。当它在就绪行之后失败——会话无法激活，或某个插件行抛错——进程退出，把日志环形缓冲区一起带走。唯一的记录就是父进程选择捕获的内容。

Node 自己的 stderr 能在进程结束后留存，这使它成为不引入日志依赖时唯一可用的持久通道。插件只用它：模块作用域内不导入任何东西，所以加载器没有东西要解析，也没有东西会安装失败。

它做什么

- 把 error 和 warn 记录桥接到 stderr，每条记录一行带前缀，堆栈跟踪缩进在首行下面。
- 重放插件加载前已缓冲的错误。那个窗口里的警告已经没了——默认级别在这个插件存在之前就把它们从环形缓冲区里过滤掉了——README 如实说明这一点，不假装不是。
- 记录会话激活失败，来自 api-session/error，这些根本到不了日志器。
- 自我限流：每 60 秒窗口 100 条消息，之后用一行说明丢弃了多少条。循环里的错误不会刷爆日志。
- 每次启动写一行就绪行，所以没有这行的日志可以读作早于桥接。
- 不会弄坏引导。每个挂载步骤都包了保护。一个能拖垮它本要解释的启动过程的桥接，还不如没有桥接。

工作原理

apply(ctx) 做三件事，每件事各占一个 try：

1. 如果 ctx.logger.buffer 是数组，就重放缓冲区里的 error 记录。
2. 给 ctx.logger 挂一个导出器，levels: { default: 2 }（Cordis 级别：error 0、info 1、warn 2）。
3. 订阅 api-session/error，处理会话激活失败。

所有写入都走同一个限流写入器。每行都带前缀 [harness-log]，这个前缀很关键：loader 会检查 stderr 来判断哪个插件搞坏了启动，它能跳过带前缀的行，所以桥接过来的运行时杂音永远不会改变恢复流程归咎的插件。

模块把格式化和限流辅助函数（formatMessage、bridgeLines、createLimitedWriter）导出为纯函数，时钟可注入，因此不用 harness 也能测试。

环境要求

- Node.js 22 或更高版本（harness 自带，不需要单独安装）。
- 一个能加载插件 bundle 的 DeepSeek Harness 配置档 —— 0.1.x 或 0.2.x。
- 一个能捕获子进程 stderr 的父进程。在终端里运行 dsh 就满足。

快速开始

从 npm 安装

dsh plugin --profile web add dsh-plugin-log-bridge

安装到桌面应用

用 --add-plugin <path> 让应用指向这个文件夹，或者用官方应用的插件管理器安装 npm 包。安装会加上 bundle 行；之后导出的行会出现在 stderr 上，和 harness 自己的输出并排。

从源码构建

没有需要构建的东西。这个包就是两个源文件加一个补丁：

git clone https://github.com/desanv01/dsh-plugin-log-bridge.git
cd dsh-plugin-log-bridge
dsh plugin --profile web add .

冒烟测试

纯辅助函数完全不需要 harness 就能测：

node --input-type=module -e "import('./index.js').then(m => {
console.log(m.formatMessage({ args: ['hello', new Error('boom')] }));
console.log(m.bridgeLines('error', 'harness', 'line one\nline two').join('|'));
})"

预期输出一条格式化消息和两行带前缀的行，第二行缩进。

配置

没有配置。桥接没有 Config schema，也不接受任何选项，这是故意的 —— 启动出问题时，你需要的是不用配置的诊断工具，而不是需要配置的那种。

可以合理调整的常量放在 index.js 顶部，故意不暴露：

| 常量 | 值 | 含义 |
| EXPORT_LEVEL | 2 | 最高放行到 warn（error 0、info 1、warn 2） |
| WINDOW_MS | 60_000 | 限流窗口 |
| WINDOW_LIMIT | 100 | 每个窗口丢弃前的行数上限 |

使用的插槽

无。这是纯宿主插件；不提供 UI，也不注册到任何插槽。

文件位置

| 部分 | 路径 |
| 宿主部分 | index.js |
| Bundle 补丁 | cordis.patch.yml —— 插入行 desktop-log-bridge |
| 桥接的行 | 在 harness 的 stderr 上，每行前缀 [harness-log] |
| 就绪行 | 输出到 stdout，每次启动输出一次 |

故障排查

| 现象 | 原因 | 处理 |
| 完全没有 [harness-log] 行 | 还没有记录过任何错误或警告 | 故意弄坏一个插件，强制触发一条；或者检查配置档里有没有这一行 |
| 没有就绪行 | 插件没有加载 | 检查配置档的 cordis.patch.yml 里有没有 desktop-log-bridge 这一行，或者确认 bundle 已经添加 |
| 行被截断 | 守护进程缓冲了 stderr | 去看守护进程的日志，不要看终端 |
| 出现 dropped N message(s) 行 | 触发了限流 | 循环场景下属于正常现象；这里会报出丢弃数量，不会静默丢掉 |
| 加载之前的警告不见了 | 默认导出级别把它们从环形缓冲里过滤掉了 | 无法恢复——环形缓冲里从来没有这些记录 |

当前状态

可用，而且小到可以坐下来一次审完：宿主代码 144 行，无依赖，无 UI。

已验证：格式化和限流作为纯函数；缓冲错误的回放；会话错误的桥接；以及附件路径出错时启动流程依然完好。在最早打包它的桌面应用里实际跑过。

尚未验证：插件在官方 DeepSeek Harness 桌面应用（0.2.0-rc.2）里运行。它用到的宿主接口——ctx.logger、ctx.on('api-session/error')——属于有文档的组装方式，不是私有 API，所以移植预计不会出问题。但预计不等于证据。

路线图

- [x] 把 error 和 warn 导出到 stderr，带固定前缀
- [x] 回放加载前缓冲的错误
- [x] 记录会话激活失败
- [x] 限流，并显式输出丢弃计数行
- [x] 绝不弄坏它要解释的启动流程
- [ ] 在官方桌面应用（0.2.0-rc.2）里验证
- [ ] 发布到 npm（包还没上 registry）

安全

这个插件把 harness 日志输出写到 stderr。这些输出可能包含提示词文本、文件路径、工具参数和错误消息——凡是 harness 或某个插件选择按错误或警告记录的内容，都可能出现在里面。它不做脱敏。对待捕获的 stderr 要像对待会话日志本身一样小心，没读过之前不要贴进公开 issue。

它不发起网络请求，不读取凭据，不写文件。

报告漏洞请走 SECURITY.md 里的流程。

贡献

见 CONTRIBUTING.md。插件很小，评审标准就两条：它是否不挡启动流程，它对自己能看见什么、看不见什么是否诚实？

许可证与署名

MIT——见 LICENSE。

从 desanv01/deepseek-harness-desktop-app 中抽出，原本作为内置日志桥随该应用发布。