前言¶
长期在 DSH 里跑 Agent 和会话，你很难准确回答几个朴素问题：客户端开了多久、真正有操作的时间是多少、单次任务里模型和工具各占多少。靠目测或外部计时器，口径往往和 DSH 自己的会话边界对不上。
dsh-timespan 是维护者 qwayo 发布在 DSH 插件生态里的一款「记忆」类插件。它在 DSH 进程内记录三类时长，用侧栏入口和仪表盘展示，并支持在对话里用只读工具查询；统计数据只写本机存储，不上传。
这是什么¶
dsh-timespan 面向已安装 DSH（DSH Desktop 或带 Web profile 的环境）的用户。插件分成 Host（随 DSH 运行的后台）和 Client（页面上的侧栏、仪表盘与设置）。页面只上报界面可见、窗口聚焦、会话任务起止等事件；在线、活跃、任务如何判定与汇总，由 Host 统一计算后写入本机，刷新页面或调用 Agent 工具时读的是同一份数据。
项目托管于 GitHub：qwayo/dsh-timespan，npm 包名为 @qwayo/dsh-timespan（资料中版本 0.1.1，许可证 MIT）。目录页见 skillhub.cn 上的 dsh-timespan。
三种时长分别指什么¶
插件统计三类指标，彼此有明确边界：
- 在线：DSH 从启动到退出的全部时间，包含离开电脑的时间。
- 活跃：页面可见且窗口聚焦，并在空闲阈值内有操作，或前台会话正在执行任务的时间。
- 任务：一次任务从
turn/start到turn/end的耗时，拆成模型请求、工具执行、等待用户和其他四部分。
资料说明：没有单独的「空闲时长」指标；任务时长不算活跃时长的一部分。启用后只会回填历史任务时长，不会补出在线和活跃的历史。
核心功能¶
侧栏与仪表盘¶
- 侧栏有常驻入口，实时显示你选定的时长类型（默认在线）和今日构成环；悬停约 200ms 显示说明。
- 日 / 周 / 月仪表盘含概览、趋势、明细、设置；活跃主数字、趋势图、热力图可放大到独立首屏页，趋势页含时段分布与趋势分析。
- 工作区 → 会话明细：展示活跃时长、任务时长、最近活动与当前计时状态；统计范围可选今天、近 3 天、最近一周、近 30 天或全部（选「全部」时分批加载会话）。
Agent 工具与数据管理¶
- 只读工具
timespan_stats：在对话里按日 / 周 / 月或自定义日期查询，与仪表盘同源。 - 支持导出 JSON / CSV；新备份格式为
dsh-timespan-export，旧的chronoscope-export仍可导入，按 ID 去重。清空等破坏性操作会二次确认。 - 首次启用时自动回填已有历史会话的任务时长。
设置项（节选）¶
设置页中的 dsh-timespan 分区包括：界面语言（默认中文，可切英文，仅影响本插件文案）、空闲阈值（1–15 分钟）、周起始（周一 / 周日）、外观与配色（默认跟随系统）、数字格式（默认紧凑单位如 2h 48m）、子代理明细开关，以及侧栏是否显示状态文字和常驻时长类型（默认在线）。
安装与启用¶
前置条件：DSH 已装好，且当前会话可用 plugin_manager 工具（Standard 与 Creator 预设默认开启）。安装、更新、卸载交给 plugin_manager，不要手动改 profile 的 package.json，也不要自行跑 pnpm。
方式一：从 npm 安装¶
在会话里对 Agent 说：
帮我装插件 @qwayo/dsh-timespan
需要固定版本时：
帮我装插件 @qwayo/dsh-timespan@0.1.1
plugin_manager 会从 registry 拉取并默认启用；提示需要重启时，重启 DSH 即可。
方式二：从 GitHub 安装¶
在会话里对 Agent 说：
帮我装插件 github:qwayo/dsh-timespan
适合指定仓库分支或 tag；同样需要重启 DSH 时按提示操作。
方式三：本地目录（开发）¶
- 将仓库放在固定路径，记作
<仓库本地路径>。 - 在会话里说：
用 plugin_manager 把 `<仓库本地路径>` 安装为当前 profile 的 bundle。
按返回值处理：application: applied 表示已激活；restart-required 则重启 DSH；failed 则保留错误信息继续排查。
也可直接让 Agent 调用 plugin_manager，例如：
action: install_bundle
target: github:qwayo/dsh-timespan
装好后核对¶
- 左侧栏出现 dsh-timespan 入口，默认显示今日在线时长（可在设置中改为活跃或任务）。
- 设置页出现 dsh-timespan 分区。
- 对 Agent 说「用 timespan_stats 查一下今天的时长」，应能返回统计结果。
- 可用
plugin_manager的list_bundles/list_plugins确认 bundle@qwayo/dsh-timespan与插件行dsh-timespan已启用。
从旧名 chrono-scope 升级：先移除 @local/chrono-scope bundle，再按上述方式安装；存储域仍为 chrono_scope，历史统计与设置不会丢失。
典型用法¶
在对话里查今日统计¶
安装并启用后，可直接用自然语言让 Agent 调用只读工具，例如：
用 timespan_stats 查一下今天的时长
返回口径与仪表盘一致。
在界面里看周期与构成¶
- 点击侧栏 dsh-timespan 进入仪表盘。
- 切换日 / 周 / 月视图，查看概览、趋势与明细。
- 在 工作区 → 会话明细 中选择统计范围，核对单会话活跃与任务时长。
备份与迁移¶
在设置中使用导出 JSON 或 CSV；导入时使用插件提供的导入入口。资料注明新格式为 dsh-timespan-export，旧 chronoscope-export 备份仍可导入。
适用场景与注意¶
适合谁：希望在 DSH 内闭环看清「挂机时长」「真正操作时长」「Agent 任务耗时构成」的开发者；需要在对话中让模型引用同一套统计而不另建表格的用户。
运行与权限：插件随当前 DSH 进程运行，具备该进程对文件与会话事件的访问能力。安装前应查看 GitHub 仓库 源码与 MIT 许可证，确认符合你的环境策略。
生态说明：DSH 社区插件目录（如 skillhub.cn）为独立站点，与 DeepSeek / 幻方无官方从属关系；安装方式以仓库 README 中的 plugin_manager 为准，不要凭插件名自行拼接未文档化的 CLI。
技术侧补充：运行时无第三方依赖、无需构建；仓库使用 Node.js 24.16.0 开发与测试，engines 要求 node >= 24。持久化存储域内部键名仍为历史遗留的 chrono_scope，对外项目名为 dsh-timespan。
结尾¶
dsh-timespan 把在线、活跃、任务三种口径放在同一套本机统计里，用侧栏、仪表盘和 timespan_stats 统一出口，避免「界面一套数、对话另一套数」。若要查看元信息与配图，可打开 目录页 或 GitHub README。
