马克墙小组件 GuihaiHU/dsh-widget

DSH 小组件 · macOS 桌面马克墙

一个 macOS 桌面小组件：把每天与 DeepSeek Harness（DSH）的对话使用情况，变成一张 GitHub 风格的贡献墙（马克墙），附带每日 token / 成本 / 会话数统计和 AI 生成的每日总结。

布局示意：头部统计、52 周热力格、图例、详情与总结区

功能

- 12 个月马克墙 — GitHub 风格绿色热力格展示每日 token 消耗（52 周 × 7 天），带月份标签、星期标签和 5 档图例。
- 每日统计 — 点击任意一天，查看该日精确 token、估算成本（¥）和会话数。
- 周/月总览 — 头部显示今日、本周、本月 token 总量。
- AI 每日总结 — 点击某天生成约 200 字的当日沟通总结（DeepSeek API），落盘缓存（过去的天永久、今天 30 分钟 TTL），重复点击零成本。
- 实时刷新 — 15 秒增量轮询（mtime+size 缓存），只重解析有变化的会话。
- 桌面小组件体验 — 半透明圆角卡片贴在桌面（图标之上、普通窗口之下），可拖动并记住位置，右键菜单（置顶 / 刷新 / 退出）。

环境要求

- macOS 13+
- Xcode Command Line Tools（swiftc）；无需 Xcode
- Homebrew zstd：brew install zstd
- DSH Desktop，会话数据在 ~/.dsh/sessions
- 可选：~/.dsh/.credentials.yaml 中的 DEEPSEEK_API_KEY（DSH 配置好即有）——仅每日总结需要

构建与运行

./build.sh # 产出 build/DSH小组件.app 与 build/parser-tests open build/DSH小组件.app

运行解析器测试：

build/parser-tests # 合成数据测试
REAL_SESSION=~/.dsh/sessions///session.jsonl.zstd \
build/parser-tests # 追加真实数据校验

使用方式

| 交互 | 效果 |
| 点击某天格子 | 显示该日 tokens · 成本 · 会话数，随后给出 AI 总结（≤200 字） |
| 再点同一格子 | 取消选中，清除总结 |
| 悬停格子 | 轻微提亮 |
| 拖动卡片 | 移动（位置自动记忆） |
| 右键卡片 | 置顶 / 立即刷新 / 退出 |
| 点击「新对话」 | 启动 DSH Desktop |

数据与隐私

- 会话数据仅本地读取自 ~/.dsh/sessions/...（zstd 压缩的 JSONL）。
- 每日总结只把当天的消息发给 api.deepseek.com（每次点击主动触发，结果本地缓存）。
- API key 从 ~/.dsh/.credentials.yaml 读取，仅用作 DeepSeek API 的鉴权，不上传其他任何内容。

配置

所有可调参数集中在 Sources/AppConfig.swift：

- Pricing — token 成本估算（元/百万 token：输入、缓存读、输出）。这是估算而非账单数据，请按实际套餐调整。
- dshAppPath / dshSessionsBase / credentialsPath — 路径。
- summaryModel / summaryMaxChars / todaySummaryTTL — 总结模型、目标字数、当天缓存 TTL。

项目结构

Sources/ Swift 源码（UI + 数据层） AppConfig.swift 可调配置 UsageParser.swift 会话 JSONL 解析、按天 token/成本归集 SessionReader.swift 增量扫描 + 按天文本抽取 SummaryService.swift DeepSeek API 调用 + 200 字智能截断 SummaryCache.swift 落盘总结缓存 WallView.swift 马克墙 UI 与交互 vendor/ zstd C 桥 + 第三方 zstd 头文件（见 vendor/README.md） Tests/ParserTests.swift 解析/缓存/截断测试 build.sh 一条命令构建打包（无需 Xcode） docs/ 架构文档（中文 / EN）

Roadmap

- Phase 2（规划中）：dsh:// 深链直达具体会话；WidgetKit 系统小组件；Windows 版（Tauri/Electron）。

许可证

MIT