前言¶
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檢索。
