前言¶

用 DSH 做智能體開發時，用量面板能看當週數字，但很難在固定時刻留一份可檢索的歸檔，也不方便在手機上掃一眼「這週動了哪些項目」。手工導出會話、手算費用既費時，又容易和麪板口徑不一致。

下面介紹社區維護者 xkzdwb 發佈的 cordis 插件 DSH-WeeklyReport-WhenOneWeekFinish：掛在 DSH HOST 裏，按你配置的星期與時區定時發一封郵件；統計只讀 DSH 會話日誌，不調模型、不改會話數據。SMTP 與 MIME 用 Node 內置能力自實現，無需 npm install。分類爲工作流，可在 SkillHub 目錄頁 查看條目；源碼與說明見 GitHub 倉庫（截至資料記錄爲 1 star）。

這是什麼¶

插件在每週指定時刻（某天 HH:MM，可指定時區）向配置收件人發送 HTML 與純文本雙格式的週報。郵件主題示例：

[DSH 週報] 2026-10-29 ~ 2026-11-05 · 2.12 億 tokens / ¥149.81

數字來自 DSH 寫入的會話事件日誌；費用由配置中的 currency / pricing 佔位單價重算，與用量面板默認價表對齊，並非聯網詢價。若該周沒有任何模型調用，仍會發信，正文標明「這一週沒有任何模型調用記錄」，便於區分「沒發信」和「本週確實無調用」。

到點 DSH 未運行時可啓用 catchUp，下次啓動補發最近一期；也可在不啓動 DSH 時用 node tools/weekly-report.mjs 本地預覽或測試發信。運行環境要求 Node >=20（見 package.json），許可證 MIT。

核心功能¶

郵件內容與邊界¶

正文大致包含：一句話彙總（含與上週對比）、Token 用量明細、按天 7 行、按 provider/model 拆分、工作彙總（項目 → 會話）、工具調用 Top 5。首條請求摘要默認 140 字；疑似密鑰片段會打碼爲 [已隱去密鑰] 等。HTML 僅用內聯樣式，無外鏈資源。

數據口徑（與面板差異處）¶

統計通過 ctx.sessionQuery.listSessions() 與 readSession(id) 折事件日誌：按事件時間落在發送窗口 [from, to) 內過濾，不是按會話創建時間整段歸檔。四類 token（input / output / cacheRead / cacheWrite）分開計價；子代理計入總量，會話數單獨列出。工作彙總分組鍵是會話工作目錄，不是項目顯示名。

運維與可觀測性¶

插件註冊兩條只讀 HTTP 路由：/plugin-weekly-report/status（排期、上次發送、錯誤等）與 /plugin-weekly-report/preview（渲染完整週報但不發信）。state.json 記錄安裝與發送狀態；dryRun: true 時到點只記賬不發信。

安裝與啓用¶

官方 README 未給出 dsh plugin add 一類命令；啓用方式是把片段寫入 profile 的 cordis.patch.yml。先做下面幾步，再重啓 DSH。

1. 將 examples/cordis.patch.snippet.yml 中的條目加入 ~/.dsh/profiles/<profile>/cordis.patch.yml 的 - insert: 列表，路徑改爲你機器上的絕對路徑：

- id: weekly-report
  name: "/absolute/path/to/DSH-WeeklyReport-WhenOneWeekFinish/src/plugin.js"
  config:
    to: you@example.com
    address: sender@example.com
    secretsFile: "/absolute/path/to/DSH-WeeklyReport-WhenOneWeekFinish/secrets.json"
    weekday: 0        # 0=週日 … 6=週六
    time: "00:00"     # 必須帶引號，否則 YAML 會當成 60 進制整數
    timeZone: Asia/Shanghai
    catchUp: true
    windowDays: 7

「週六 24:00」在實現上等於週日 00:00，故 weekday: 0；若要週六 00:00，將 weekday 改爲 6。

2. 複製 secrets.example.json 爲 secrets.json，填入郵箱服務商的應用專用密碼（163 爲「客戶端授權碼」）：

{ "authCode": "你的授權碼", "user": "sender@example.com" }

也可在 config 中直接寫 authCode，無需文件。默認 SMTP 爲 smtp.163.com:465（SSL），換郵箱時改 smtp 配置。

3. 重啓 DSH。修改 cordis.patch.yml 可自動重載；修改插件源碼 src/*.mjs 需重啓後生效。

4. 確認裝配成功：

curl http://127.0.0.1:1869/plugin-weekly-report/status
curl "http://127.0.0.1:1869/plugin-weekly-report/preview?days=7&format=html" -o preview.html

package.json 中 dsh.bundle.patch 指向 ./cordis.patch.yml，若你使用 DSH 的 bundle 流程，可按倉庫內對應文件一併納入 profile。

典型用法¶

在 HOST 內定時發送¶

裝好並配置 to、weekday、time、timeZone 後，插件按 tickIntervalMs（默認 60000）檢查是否到點。首次安裝不會立刻發信，只會排下一次；錯過時刻且 catchUp: true 時啓動後補發一期，主題帶「（補發）」。SMTP 失敗會 10 分鐘後重試，最多 5 次。

命令行預覽與測試（不依賴 DSH 進程）¶

# 渲染純文本，默認不發信
node tools/weekly-report.mjs --to you@example.com --secrets secrets.json

# 保存 HTML 到本地
node tools/weekly-report.mjs --to you@example.com --secrets secrets.json --html preview.html

# 實際發一封測試信
node tools/weekly-report.mjs --to you@example.com --secrets secrets.json --send --subject-prefix "[DSH 週報測試]"

# 按配置的發送時刻取上一完整週期
node tools/weekly-report.mjs --to you@example.com --secrets secrets.json --end schedule

# 僅探測 SMTP 認證
node tools/probe-mail.mjs secrets.json

命令行讀 ~/.dsh/sessions/*/*/session.v4.jsonl.zstd，與 HOST 內 sessionQuery 共用同一套 collect.mjs / report.mjs 邏輯。

常用配置項摘要¶

完整表格見倉庫 README 第 4 節。

適用場景與注意¶

適合誰： 需要每週固定收到 DSH 用量與工作清單、希望與面板費用口徑一致、又不願引入額外 npm 郵件庫的用戶。適合配合 163 等支持應用密碼的 SMTP；也可改 smtp 適配其他服務商。

權限與安全： 插件以當前 DSH 進程權限運行，能讀本會話日誌與配置的 secretsFile；安裝前請自行審閱 src/plugin.js 等源碼與 MIT 許可證。勿將 secrets.json 提交到版本庫（倉庫已列入 .gitignore）。

已知限制（README 摘錄）： DSH 未運行時無法到點發送，僅能啓動補發；長期關機只補最近一期。「工作彙總」是清單而非語義摘要；跨週會話的會話數口徑與面板按會話歸檔的方式不完全相同；費用爲配置佔位值，中轉或多模型場景需自行維護 pricing。

DSH 社區目錄（SkillHub）爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；插件屬「一切皆插件」生態中的第三方工作流擴展。

結尾¶

經過上面的步驟，你可以在週日零點（或任意 weekday / time）自動收到一封可存檔的週報：token 四類拆分、按模型費用、按目錄的項目與會話摘要，且無第三方郵件依賴。開發與驗證側，倉庫提供 node test/run-tests.mjs（32 條用例，CI 使用 Node 20）。

• 目錄頁：https://www.skillhub.cn/plugins/xkzdwb/DSH-WeeklyReport-WhenOneWeekFinish
• GitHub：https://github.com/xkzdwb/DSH-WeeklyReport-WhenOneWeekFinish