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

dsh-session-insights

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

它主要回答：

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

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

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

报告里有什么

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

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

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

安装 Bundle

俄语（--locale ru）目前仅在源码中提供，尚未发布。使用俄语时，请按下方源码安装步骤选择包含该功能的已审查提交。已发布的 0.6.1 包及标签支持 zh-CN 和 en。

0.6.1 Bundle 需要 DSH >=0.2.1-rc.2 和 Node.js ^22.19.0 || >=24.0.0，无需 Python。可选的文件日志 CLI 仍需要 Python 3.11+。从 0.6.0 升级后请开始新的分析运行。

DSH 兼容性： 软件包要求 >=0.2.1-rc.2——0.2.1-rc.3 是本版本主验收宿主，0.2.1-rc.2 保留兼容覆盖。DSH 0.2.0-rc.2 与 0.2.1-rc.1 低于支持下限；范围内未来版本按声明准入但尚未实测。契约与服务测试覆盖合成 V4 输入；源码与合成检查保留在 0.6.0 开发记录；原生、模型与 UI 结果由各精确发布制品的附带验收回执分别记录。范围准入不代表未来宿主已经过实测。详见 DSH 兼容性。

已知上游安全缺口： DSH rc.2/rc.3 固定使用的 zod@4.4.3 存在内存耗尽漏洞（GHSA-mrhx-c7xc-m3w5 / CVE-2023-54404）。0.6.1 接受了这项尚未修复的特定风险，日用触发概率未经验证；下次升级 DSH 时必须重新评估。安装前请阅读风险与例外范围。

下方 registry 命令需要 0.6.1 已发布。验收候选时，请安装已审查的 tgz 或源码版本；使用 registry 命令前，请先在 GitHub Releases 核实版本：

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

从源码安装时，请把 REVIEWED_REF 替换为发布后的 v0.6.1，或候选制品清单中记录的完整提交号。安装前先选择该版本；仅克隆仓库会检出默认分支，它可能还是其他版本：

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

随后在 DSH 输入框中运行：

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

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

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

官方 Desktop

Desktop 共用 Node 分析实现，其插件 profile 由官方 Electron 应用管理；npm CLI 会拒绝 --profile desktop。请通过应用内的插件管理或应用自带的命令 carrier 安装或卸载 Bundle。macOS carrier 位于 /Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh，安装调用为 plugin --profile desktop add <package>。各平台的实测结果请查看该精确发布制品的附带验收回执。Windows 如因文件占用出现 EPERM，应在重装前关闭主程序及其 child host。命令返回 HTML 路径后，可用本地浏览器查看；传入 --no-open 时只返回路径，不附查看提示。

获取渠道

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

权限与依赖

Bundle 在 Node.js worker 中分析 sessionQuery 快照，不再启动 Python 或 Shell。worker 使用空环境，也不继承 Node 启动参数；DSH_SESSION_INSIGHTS_PYTHON、PYTHONPATH 和 Python 启动文件不再影响原生分析。可选 Python CLI 仍作为独立流程保留。

| 能力 | 使用范围 |
| 会话与文件 | 在内存中读取选中的快照，将报告、有界证据和通过校验的模型输出写入 $DSH_HOME/insights/runs 下带管理标记的目录。不保存原始快照，不创建共享语义缓存。 |
| 路径保护 | 仅接受带标记的直接运行子目录；逐次检查产物路径，拒绝链接和特殊文件。批次 ID 必须属于本次运行清单。新建目录和文件使用仅所有者可访问的 POSIX 权限；Windows 访问权限由父目录 ACL 决定。 |
| 环境与凭据 | 宿主仅用 DSH_HOME 或操作系统用户目录定位存储。原生分析不探测解释器、不转发环境变量、不需要独立 API Key，也不调用凭据库。会话内容仍可能含有秘密，脱敏不能保证适合公开。 |
| 网络与模型 | 确定性分析可离线运行。默认语义流程经当前 DSH agent 把清洗并限制范围的证据交给配置的模型提供方，遵循该提供方的数据处理规则和计费方式。添加 --deterministic 可跳过此阶段。 |

Bundle 需要 Node.js ^22.19.0 || >=24.0.0，以及 DSH 的 commands、tools 和 sessionQuery 服务，并使用声明的 >=0.2.1-rc.2 DSH peer 依赖（含官方消息 helper）。服务缺失、worker 失败、不安全路径或无效语义输出都会使相关操作停止。模型输出先在内存校验再写入；无效的替换请求不会覆盖已有合法结果。显式回退会生成标记为降级的确定性报告。

每次最多分析 2,000 个选中快照，序列化输入上限为 64 MiB；超出时请缩短 --days 或按 --project 筛选。每个插件实例最多同时进行两个分析，更多请求进入可取消的排队队列，slash command 与 tool 并发调用不会无界地倍增 Worker；单个 Worker 的 maxOldGenerationSizeMb 只限制该 Worker 的 V8 old space，不是宿主 RSS 上限。新运行记录完整选择范围（归一化 project、时间窗长度、隐私对、depth、locale）；恢复必须绑定显式 run 且范围完全一致，因此恢复不会选中其他项目或更宽的隐私范围。缺少范围记录、或格式/分析语义身份不符的 manifest 会被拒绝；仅宿主版本号增长不会使语义相同的运行失效。新运行保留自身已验证输出供恢复使用，不跨运行复用语义缓存。

保留与清理

报告和证据会保留到显式删除。session_insights_cleanup 以运行目录 workdir 调用时是只读预览（文件数与字节数）。删除需要宿主的人工审批：携带 confirm: true 时工具会就这一个 run 向部署的审批服务发起一次请求，只有用户在提示中选择允许（allowed-once）才会真正删除——模型自行填写的参数永远不能授权删除，没有审批服务的宿主直接失败关闭。直接键入 DSH 命令 /session-insights --cleanup <run> 为预览、/session-insights --cleanup <run> --confirm 恰好删除一个指定 run——该命令不运行分析、不排队模型工作，是纯人工入口。清理会删除整个带标记的运行目录，包括报告，且不可撤销。未标记的旧目录和带链接的条目会被拒绝；其他运行、原始日志和可选 CLI 的共享缓存会保留。旧 CLI 缓存可用 dsh-session-insights cache 子命令预览，并仅在显式 --delete 时删除确认归属的缓存根。

可选 CLI 仍需要 Python 3.11+；读取压缩日志需要 zstandard>=0.23,<1，jsonschema>=4.23,<5 与 tzdata>=2024.1 仅供开发测试使用。其 bootstrap 安装器会调用 pip，并管理独立的 skill/runtime 目录。具体边界及商城策略限制见安全策略。

三档隐私模式

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

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

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

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

原生命令

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

项目过滤必须使用绝对路径。相对路径会被拒绝并给出可操作错误——插件入口无法可靠获知宿主的调用目录，因此拒绝猜测，也不会输出误导性的空报告。在 Windows 上请使用 /session-insights --project C:/path/to/project 这样的原生路径；如果传入 /path/to/project 这类 POSIX 根路径，插件会明确报错，而不是静默匹配不到会话。可选 Python CLI 会把相对 --project 按你调用命令时的工作目录解析一次。

报告的 date、hour、weekday 共用一个报告时区：默认在请求入口捕获宿主本地时区，也可用 --report-timezone 显式指定（IANA 名称如 Asia/Shanghai，或固定偏移如 UTC+08:00）。时区随请求显式传入分析，并记录在报告 scope 与 run manifest 中，后续 resume 不会漂移；原始时间戳保持 UTC 瞬时值。可选 Python CLI 在 Windows 上缺少 IANA 数据时会明确报错并提示安装 tzdata，不会静默回退 UTC。

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

--no-open 有明确含义：命令只返回报表路径本身——输出保持单行路径、不带查看提示，不打开文件、不启动服务器、不上传任何内容。不带该 flag 时，命令输出会在路径后附一行查看提示。插件自身从不开文件、不启动查看器、不提供 HTTP 服务；无论 Web runtime 还是官方 Desktop，都请用本地浏览器打开返回的 HTML 路径（文件自包含、可离线查看）。--resume 支持显式 --workdir 指定运行目录；不指定时，只有记录范围与请求完全一致的运行才会被恢复，多个运行同时匹配时会报错并列出路径，而不是随机挑选。

兼容 CLI 与 Skill 流程

V4 文件日志 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；aggregate 响应还必须回显 get_aggregate 签发的规范 aggregate_input_identity，响应中其它位置的同类结构按普通内容处理。若语义阶段不能完成，finalize --fallback 会记录降级状态并保留确定性报告。

当前范围与限制

- 原生输入来自可信 DSH sessionQuery 服务；CLI 只读取 $DSH_HOME/sessions 下的 session.v4.jsonl.zstd 或 session.v4.jsonl，旧原始日志需由上游 DSH 迁移。
- 输出遵循 dsh-session-insights/1。
- token 以 (turn, step) 去重；这是使用量口径，不是账单或配额口径。
- Dashboard 与语义提示契约基于同一报告 schema 支持 zh-CN、en 和 ru。
- 报告只能根据现有证据推断模式，不能证明意图、质量、任务验收或安全性。

历史 0.2.0 包身份、CI、macOS 原生验收和限定的 Windows 原生验收记录在 v0.2.0 发布验收记录中。这些历史结果不代表当前版本。v0.1 CLI/Skill 的历史证据保留在 v0.1.0 验收记录。已发布运行时的历史兼容性证据及平台边界记录在 0.1.5-rc.2 验收记录中。

DSH 兼容性

最低支持宿主与实际测试版本分开记录。声明范围准入 0.2.1-rc.2 及以上版本，包括后续预发布版本；输入格式和 API 检查仍会拒绝不兼容的操作。准入规则不代表未来宿主已经过实测。

本版要求 DSH >=0.2.1-rc.2，拒绝更旧宿主；输入格式仍为 V4（0.2.1 宿主扩展了 V4 事件词汇，但格式号未变）。原生分析读取宿主恢复后的 V4 快照；可选 Python CLI 只读取 session.v4.jsonl 和 session.v4.jsonl.zstd。旧原始日志需先由上游 DSH 迁移。当前文件损坏或存在高于 V4 的代数时，不会回退读取旧文件。

升级后请新建分析运行：旧 manifest 和缓存不符合新输入契约，不能继续 resume。已经输出的 HTML、JSON 和 Markdown 报告保留。单独安装的 CLI/Skill 需从同一版本更新；安装 Bundle 不会更新它们。

工具工作量包含日志记录的程序化工具调用（PTC）内层调用。JSON 的 tool_execution 分别记录外层运输调用、内层执行、失败和未结束调用；每个失败调用结果计一次。若内层调用和外层程序都失败，则保留两个结果，不据此推断它们是否源于同一个原因。权限拒绝不算验证命令执行失败。developer 工具注册消息和定时注入不计人工请求。

DSH 把定时消息写为 user role、source.kind=schedule 的消息；DSH 0.2.0-rc.2 新增异步问答回复，source.kind=user-question-reply。两者都不算用户工作：都单独计入注入上下文、不进入对话证据、纠正/验收信号与完成推断，也不能构成任何授权。只有 source.kind=user 的人类消息才贡献正文证据。官方恢复结果使用结构化错误码 TOOL_OUTCOME_UNKNOWN 和 TOOL_NOT_STARTED，与确认失败分开统计：tool_recovery 按 {outcome_unknown, not_started} 在每个会话和总量中单独计数。TOOL_OUTCOME_UNKNOWN 表示已记录的调用没有持久化的最终结果，工具可能已产生副作用；TOOL_NOT_STARTED 表示日志中没有该调用开始的记录。两者都不计入工具失败或验证失败，也不证明工具执行过或没有执行。仅正文提到恢复码的文本仍按一般结果规则分类。重试可能改变数据的操作前，应先核实外部状态。

DSH 0.2.1-rc.2 仍使用会话格式 4，但新增了必需的 job/registered、job/settled 与 working-directory/change 记录。读取器接受这些记录，并把注册表结算仅视为生产者/注册表结果：它不证明用户任务完成、交付产出或资源已释放。已注册但未结算的 job 记为 pending（包括父轮已结束而子工作仍在运行）；注册缺失的结算按完整性异常计数，而不是让整个会话不可读。Team 名册/任务快照与入站 relay 作为委派证据计数，不算 Lead 的任务完成，也不当作用户提示。工作目录变化形成带标签的轨迹，而不可变的 header cwd 仍是会话来源项目，用于筛选与恢复；跨项目活动会显式呈现，原始路径不进入 redacted/metrics 报告。第三方 plugin: 记录只保留不透明类型/数量覆盖，不进入用户意图、模型上下文或完成证据。web_search 与 web_fetch 按记录的工具调用计数；一次搜索返回多个来源仍只算一次调用。Token 原始分桶为记录值；input_tokens 与 total_tokens 是由记录值派生的和，并已标注。

0.6.0（DSH 0.2.1-rc.2）的源码与合成检查保留在 docs/acceptance/v0.6.0-rc2.1-candidate.md。原生、模型与 UI 结果由各精确发布制品的附带验收回执分别记录。0.5.2 的独立复核记录在 docs/acceptance/v0.5.2-candidate.md。0.5.1 的候选审查范围记录在 docs/acceptance/v0.5.1-candidate.md。0.5.0 发布验收记录和冻结的 0.5.0 候选记录只适用于那个 0.5.0 实现及其注明的宿主。历史验收只适用于各自注明的实现。

会话日志代际

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

| 情况 | 行为 |
| 同一会话目录存在多个规范代际 | 选取版本最高者；该会话只统计一次，迁移后的会话不会被重复相加 |
| 仅有第 0–3 代 | 拒绝分析并提示需要迁移；请使用上游 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 | 记录继承切点；未带标记的结束标记不建立切点 |
| 未知事件类型 | 拒绝必需事件；明确标为可忽略的扩展保留覆盖诊断 |

npm 下载量历史

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

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

开发与项目文档

python3 -m pip install -e '.[dev]'
npm ci --ignore-scripts
npm ci --prefix tests/dsh-runtime --ignore-scripts
DSH_RUNTIME="$PWD/tests/dsh-runtime" python3 -m unittest discover -s tests -v
python3 scripts/build_native_rules.py --check
npm test
python3 scripts/build_fixture.py --check
python3 scripts/audit_public_tree.py --root .

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

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

许可证

MIT