会话复盘洞察GreenLv/dsh-session-insights

dsh-session-insights

CI
Release
License: MIT

运行 /session-insights，把 DeepSeek Harness 的会话历史整理成一份本地工作流复盘。Bundle 通过 DSH 的 sessionQuery 服务读取会话，写出可直接打开的 HTML Dashboard 和配套 JSON。

它主要回答：

- 我最近主要让 DSH 做了哪些类型的工作？
- 哪些项目和工作流投入最多？
- 工具失败、重复尝试和未完成任务集中在哪里？
- 哪些做法已经有效，下一步值得尝试什么？

这是行为复盘，不是遥测。它不是实时监控器，不计算账单，也不会替你判断工作质量。

许多分散的会话轨迹经过分析透镜，收束为结构化证据卡片和一份清晰报告

报告里有什么

Dashboard 把同一批证据组织成几个容易浏览的视角：

| 视角 | 可以看懂什么 |
|---|---|
| 总览与时段对比 | 会话数、任务族、token 用量，以及前后两个时段的变化 |
| 工作与流程拆解 | 项目、角色、代表性工作流和完成证据 |
| 使用方式 | 每日活跃时间趋势、会话类型、常用工具、Skill 与插件/MCP 使用、文件类型和本地活跃时段 |
| 亮点与摩擦 | 有证据支持的有效做法，以及失败、重试等值得调查的信号 |
| 建议 | 与测量证据绑定的 DSH 工作方式建议，并附可复制提示词 |

HTML 已内嵌样式和数据，不需要启动服务器；配套 JSON 便于继续处理或审计。

安装 Bundle

需要 DeepSeek Harness 和 Python 3.11 或更高版本。

DSH 兼容性： 当前已验证的支持基线为 0.1.5-rc.2（macOS 原生流程）。其他平台的验证范围见 DSH 兼容性。

先把已发布 Bundle 安装到 DSH profile，再启动该 profile：

dsh plugin --profile web add dsh-session-insights
dsh web

如需从已审查的源码安装：

git clone https://github.com/GreenLv/dsh-session-insights.git
cd dsh-session-insights
dsh plugin --profile web add .
dsh web

随后在 DSH 输入框中运行：

/session-insights --days 30 --locale zh-CN

该命令会准备有界语义批次，让当前 DSH agent 串行分析，并把最终 HTML/JSON 写入 $DSH_HOME/insights/runs/。添加 --deterministic 可跳过模型语义阶段。主命令刻意不占用 /insights，因此可以与已发布的 dsh-insights 共存。

npm 包不含 install/build 生命周期脚本。registry 命令安装已发布 Bundle；dsh plugin ... add . 安装当前本地源码。

获取渠道

- 从 npm 安装已发布 Bundle。
- 从 GitHub Releases 下载版本化发布产物。
- 在 dsh.pub 查看公开目录条目。
- 其他已核验的社区条目统一记录在分发状态表。

三档隐私模式

确定性报告完全离线运行。原生插件把 sessionQuery 返回的完整快照经 stdin 流式交给 Python，不会在运行目录复制原始 transcript。你可以决定报告和可选模型阶段允许保留多少会话内容：

| 模式 | 报告内容 | 语义分析 |
|---|---|---|
| redacted（默认） | 匿名化身份和路径、过滤密钥后，保留有界摘录 | 只有显式运行语义流程时，才使用有界且已脱敏的证据 |
| metrics | 不保留摘录，只输出聚合测量 | 完全禁用，不生成语义批次 |
| local | 过滤密钥后保留有界的本地路径和文本 | 需要显式启用，只应面向可信的本地输出位置和模型提供方 |

本工具本身不会增加上传通道。如果启用可选语义流程，按 --analysis-privacy 清洗并限制范围后的证据，会交给 DSH 当前配置的模型提供方分析。

工具拒绝把报告写入 $DSH_HOME/sessions，避免生成文件混入原始日志目录。

原生命令

/session-insights [--days N] [--project PATH] [--privacy MODE]
[--analysis-privacy MODE] [--analysis-depth LEVEL]
[--locale zh-CN|en] [--deterministic] [--resume] [--no-open]

项目过滤路径遵循宿主操作系统语法。在 Windows 上请使用 /session-insights --project C:/path/to/project 这样的原生路径；如果传入 /path/to/project 这类 POSIX 根路径，插件会明确报错，而不是静默匹配不到会话。

语义复盘是默认流程。模型输出无效时最多修复一次，仍失败则明确降级并保留确定性报告。当前复盘会话计入覆盖范围，但标记为元分析，不进入建议生成。

兼容 CLI 与 Skill 流程

v0.1 的文件日志 CLI 与 Skill 继续保留，适合自动化或未挂载 Bundle 的环境：

DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
python3 scripts/bootstrap.py install --dsh-home "$DSH_HOME"
CLI="$DSH_HOME/tools/dsh-session-insights/venv/bin/dsh-session-insights"

复盘最近 30 天并打开中文 Dashboard
"$CLI" report --dsh-home "$DSH_HOME" --days 30 --locale zh-CN \
--format html --output ./dsh-insights.html --open

在 macOS 或 Linux 上只看一个项目
"$CLI" report --dsh-home "$DSH_HOME" \
--project /path/to/project --format html --output ./project-insights.html

不保留摘录，也不生成语义批次
"$CLI" report --dsh-home "$DSH_HOME" --privacy metrics \
--format json --output ./dsh-metrics.json

检查安装状态
"$CLI" doctor --dsh-home "$DSH_HOME"

Windows PowerShell 应使用受管的 Windows 启动器和 Windows 原生项目路径：

$Cli = Join-Path $env:DSH_HOME 'tools\dsh-session-insights\venv\Scripts\dsh-session-insights.exe'
& $Cli report --dsh-home $env:DSH_HOME --project 'C:\path\to\project' --format html --output .\project-insights.html

只卸载本项目管理的目录：

python3 scripts/bootstrap.py uninstall --dsh-home "$DSH_HOME"

安装器只管理：

- $DSH_HOME/skills/dsh-session-insights
- $DSH_HOME/tools/dsh-session-insights

它会拒绝符号链接目标、相互重叠的根目录，以及已有但不带本项目标记的目录，不会覆盖其他 Skill。

手动语义复盘

原生命令默认编排语义复盘。CLI 也暴露每个阶段，便于调试或自动化：

dsh-session-insights semantic prepare --dsh-home "$DSH_HOME" --days 30 --workdir /safe/workdir
dsh-session-insights semantic validate-batch --workdir /safe/workdir --batch batch-001
dsh-session-insights semantic prepare-aggregate --workdir /safe/workdir
dsh-session-insights semantic validate-aggregate --workdir /safe/workdir
dsh-session-insights semantic finalize --workdir /safe/workdir --output report.html

模型生成的每个 JSON 都必须先通过验证，才能进入最终报告。未知证据 ID、禁止的完成声明、错误枚举或隐私泄漏都会 fail closed。若语义阶段不能完成，finalize --fallback 会记录降级状态并保留确定性报告。

当前范围与限制

- 原生输入来自可信 DSH sessionQuery 服务；兼容 CLI 读取 $DSH_HOME/sessions 下的当前会话日志代际：第 0 代为 session.jsonl.zstd，第 N 代为 session.vN.jsonl.zstd，未启用压缩的 DSH_HOME 则为对应的明文 .jsonl 形式。
- 输出遵循 dsh-session-insights/1。
- token 以 (turn, step) 去重；这是使用量口径，不是账单或配额口径。
- Dashboard 与语义提示契约基于同一报告 schema 支持 zh-CN 和 en。
- 报告只能根据现有证据推断模式，不能证明意图、质量、任务验收或安全性。

精确包身份、CI、macOS 原生验收和限定的 Windows 原生验收记录在 v0.2.0 发布验收记录中。Windows 尚未原生验证确定性斜杠命令分发和英文 DOM 渲染。v0.1 CLI/Skill 的历史证据保留在 v0.1.0 验收记录。本次兼容性证据及平台边界记录在 0.1.5-rc.2 验收记录中。

DSH 兼容性

默认只支持明确验证过的最低基线，或经验证的 DSH 最新版本。不再维护历史 DSH 版本，不承诺中间版本连续兼容，也不会在新版发布后自动将其视为已支持。使用旧版宿主时，请升级到已验证的基线。

软件包将 0.1.5-rc.2 声明为当前 DSH 要求。DSH 插件市场也会显示这一精确范围，并在安装时执行该约束。

| 范围 | DSH 版本 | 状态 |
| --- | --- | --- |
| 当前支持基线 | 0.1.5-rc.2 | 已按下列范围完成验证 |
| 源码与自动化测试审查 | 0.1.5-rc.2 | 已按本机安装的包完成核对与适配；本机测试通过 |
| 宿主原生验收 | 0.1.5-rc.2 | macOS 隔离宿主：确定性、完整语义、metrics 跳过、fallback 与 Skill 发现通过 |

0.3.2 保留 0.3.1 引入的第 0–3 代会话日志支持。本次仅更新元数据，没有改变平台专属启动器或宿主接口，因此不重复 Windows/Linux 的完整原生模型流程；现有三平台 CI 检查共用代码与路径行为，不能代替这些平台的原生验收。这些结果仅适用于表中所列的 DSH 版本和验证范围。历史验收记录保留为当时的发布证据，不代表持续支持承诺。

会话日志代际

同一个逻辑会话可以保留多个不可变日志代际。读取方只选取其中一个，依据规范文件名而非文件修改时间。

| 情况 | 行为 |
| --- | --- |
| 同一会话目录存在多个规范代际 | 选取版本最高者；该会话只统计一次，迁移后的会话不会被重复相加 |
| 仅有第 0 代（session.jsonl[.zstd]） | 读取保留的日志格式；不代表支持旧版 DSH 宿主 |
| 非规范名称（临时文件、大写、前导零、.v0、session.lock） | 永不选取；写入中的文件不会被误认为已提交代际 |
| 高于本读取方支持的代际 | 记录诊断并跳过，同时给出警告；不会静默按旧代际输出报告 |
| 当前代际损坏或无法解压 | 记为不可读文件；不会回退到旧代际 |
| 同一目录混用两种压缩编码 | 记为歧义并跳过该会话 |
| 多个工程目录声称同一会话 ID | 各会话目录独立计数 |

工具和用量统计保留历史事件；语义证据则排除已被替换的消息。DSH 根据事件日志维护模型可见的有序对话（surface），替换操作以该对话中的位置为准，不能按事件序号大小推断。

| 事件 | 行为 |
| --- | --- |
| system/message | 记为系统内容；绝不算作用户工作，不进入摘录，不泄露到标题或语义证据 |
| source.kind == "user" 的 user/message | 真人直接输入：计入用户工作，可作为标题来源 |
| 其他 source.kind 的 user/message | 合成注入上下文（plugin、goal、skill 目录、子代理报告等）：单独计数，排除在用户工作与语义证据之外 |
| assistant/attempt | 记为未产出可见回复的模型尝试；不会伪造成 assistant 消息，其 Token 用量如实标记为不可得而非估算 |
| assistant/message | 携带该步用量；用量按 (turn, step) 去重，stream 字段不会造成重复相加 |
| surfaceOp: "append" | 表面正常增长 |
| surfaceOp: {op: "replace", startSeq, endSeq} | 被压缩的对话退出语义摘要；历史工具与 Token 事件统计保留 |
| 带 data.inherited: true 的 session/end-seed | 记录继承切点；未带标记的结束标记不建立切点 |
| 未知事件类型 | 计入 coverage.unknown_record_types 并给出报告，绝不静默忽略 |

npm 下载量历史

dsh-session-insights 的累计 npm 下载量增长

该累计图每天根据 npm Downloads API 自动生成。npm 下载量统计的是 registry 请求次数，不等于独立用户数或已确认的真实安装人数。如果 GitHub 延迟或停用定时任务，也可以手动触发工作流。

开发与项目文档

python3 -m pip install -e '.[dev]'
python3 -m unittest discover -s tests -v
python3 scripts/build_fixture.py --check
python3 scripts/audit_public_tree.py --root .

- 更新记录
- 安全策略
- 参与贡献
- 分发说明

测试 fixture 全部为合成数据，并可确定性重建。

许可证

MIT