耗时自省 JularDepick/dsh-time-introspect

dsh-time-introspect

面向 dsh 的耗时反思插件：上一轮实际耗时超出模型预估时，把完整的耗时分布以 JSON 注入下一轮，由模型自己决定是否反思。反思的开始与结束都由模型显式调用工具，插件只负责计时与记账；插件不自动冷却，不自动休眠，是否让插件安静由模型决定。

支持 dsh 0.2.0-rc.2、0.2.1-rc.1 与 0.2.1-rc.2

特性

- 超时触发：仅当上一轮有预估记录，且实际耗时同时超过比例阈值（minOverrunRatio，默认 20%）与绝对下限（minOverrunMs，默认 5000 毫秒）时，在下一轮 step 1 注入一次
- 完整 JSON：注入内容是结构化 JSON，包含总账、工具耗时、模型自身处理与反思内部明细；全部工具逐个列出，不做 top N 合并
- PTC 兼容：run_code 程序内嵌套调用的工具同样被识别，预估、反思、休眠与工具明细都按真实工具名入账
- 显式反思边界：模型调用 time_introspect_start 开始，time_introspect_stop 结束；插件按两次调用的位置计时，模型不需要整理或上报任何耗时数据
- 反思自计费：反思窗口内的全部耗时计入反思开销，窗口内的工具单独列在 introspect 明细里，帮助模型判断反思本身是否值得
- 模型控制休眠：time_introspect_shut 让插件休眠，time_introspect_waken 恢复；没有自动冷却与自动休眠
- 对话内红点气泡：每次模型调用本插件工具，都在该工具调用位置显示红点；新调用展开一行简要提示，3 秒后收起，红点保留；点击红点可展开或收起详细信息
- 逐轮归档：每一轮结束都静默生成与注入 JSON 同结构的归档记录，不进入模型上下文；未触发注入的轮次 estimate_ms、overrun_ms、overrun_ratio 为 null
- 会话内 Tab：会话区域新增「耗时自省」页，上半部分逐轮展示归档，下半部分按注入展示反思结果；details 数组默认收起，点击展开
- profile 落盘：每个会话在 profile 下写一个归档 JSON，最近保留 200 轮
- 状态可查：time_introspect_status 只读返回状态、最近一轮总账与三类耗时合计
- 仅主会话：子代理会话不注入，六个工具在子代理中完全隐藏
- 可回放：状态由会话投影从官方事件折叠，进程重启自动重建；不写自定义会话事件
- 双语文案：locale 可选中文（zh-CN，默认）或英文（en-US）

模型看到什么

{
"type": "time_introspect",
"desc": "本 JSON 由 dsh-time-introspect 插件自动统计生成, 内容是上一轮任务的耗时分布报告. 是否据此反思由你决定; 如需反思, 调用 time_introspect_start 开始, 完成后调用 time_introspect_stop.", "turn": 3,
"waken": { "reason": "连续三轮工具调用冗余, 工作越来越难推进" },
"estimate_ms": 100000,
"overrun_ms": 30000,
"overrun_ratio": 0.3,
"time_consume_total_ms": 130000,
"time_consume_details": {
"tool": {
"desc": "本层是反思窗口外的工具耗时, 不含反思窗口内调用的工具; 含反思窗口外的本插件工具(包括开始与结束边界工具)的调用耗时.", "ratio": 0.0769, "total_ms": 10000,
"details": [
{ "name": "bash", "calls": 3, "ms": 4000, "ratio": 0.4 },
{ "name": "read", "calls": 2, "ms": 2000, "ratio": 0.2 },
{ "name": "write", "calls": 4, "ms": 3000, "ratio": 0.3 },
{ "name": "time_introspect_start", "calls": 1, "ms": 300, "ratio": 0.03 },
{ "name": "time_introspect_stop", "calls": 1, "ms": 700, "ratio": 0.07 }
]
},
"model": { "desc": "本层是反思窗口外的模型自身处理与等待耗时, 不含反思窗口内的模型耗时, 也不含任何工具耗时.", "ratio": 0.7693, "total_ms": 100000 },
"introspect": {
"desc": "本层是反思窗口内的全部耗时, 含窗口内调用的工具(包括本插件工具)与模型处理; 开始与结束工具本身在窗口外, 不计入本层.", "ratio": 0.1538, "total_ms": 20000,
"details": {
"tool": {
"desc": "本层是反思窗口内调用的工具耗时, 含窗口内调用的本插件工具; 开始与结束工具本身在窗口外, 不计入本层.", "ratio": 0.3, "total_ms": 6000,
"details": [json
{ "name": "bash", "calls": 10, "ms": 5000, "ratio": 0.8333 },
{ "name": "read", "calls": 2, "ms": 1000, "ratio": 0.1667 }
]
},
"model": { "desc": "本层是反思窗口内的模型处理与等待耗时, 不含窗口内工具耗时.", "ratio": 0.7, "total_ms": 14000 }
}
}
}
}

waken 只在模型重启后的第一次注入出现，之后省略。每个耗时层都带 desc，说明该层是否包含反思工具与本插件工具。每层 ratio 保留 4 位小数，缺失差值补给该层最大项。

安装 sh
dsh plugin --profile <name> add dsh-time-introspect

<name> 是目标 profile，例如 web、desktop 或专用 profile。

工具

| 工具 | 参数 | 行为 |
| time_introspect_estimate | estimateMs | 登记本轮预估，同轮以最后一次为准 |
| time_introspect_start | 无 | 开始反思；本轮必须先收到注入，已有打开窗口时报错 |
| time_introspect_stop | 无 | 结束反思；没有打开窗口时报错 |
| time_introspect_shut | reason | 休眠；已休眠时幂等返回，丢弃未闭合窗口 |
| time_introspect_waken | reason | 重启；已活动时幂等返回 |
| time_introspect_status | 无 | 只读查询状态与最近一轮总账 |

工具名统一带 time_introspect_ 前缀。插件不阻断任何工具调用，也不检查模型是否真的完成了反思。

配置 yaml
- name: dsh-time-introspect
config:
minOverrunRatio: 0.15
minOverrunMs: 3000
locale: zh-CN

| 字段 | 默认值 | 含义 |
| enabled | true | 总开关；关闭后不注册投影、工具与监听器 |
| minOverrunRatio | 0.20 | 触发注入所需的最小超出比例 |
| minOverrunMs | 5000 | 触发注入所需的最小绝对超出毫秒数 |
| maxTurnHistory | 12 | 投影保留的已完成轮数上限 |
| locale | zh-CN | 模型可见文案语言，可选 zh-CN 或 en-US |

气泡自动展开时长固定为 3 秒，历史调用自动展开窗口固定为 15 秒；归档与注入记录保留最近 200 轮；均不提供配置。

口径与判定

- 实际耗时：turn/end 事件时间减去 turn/start 事件时间
- 工具耗时：原生调用按 callId 配对 tool/call 与 tool/result；PTC 模式下的子调用按 subCallId 配对 tool/ptc-dispatch-start 与 tool/ptc-dispatch
- 嵌套调用：PTC 子调用按真实工具名入账，外层 run_code 只记扣除子调用后的净耗时，总账不重复计数
- 反思窗口：time_introspect_start 的工具结果到 time_introspect_stop 的工具调用开始
- 反思窗口内全部耗时计入反思开销；窗口内的普通工具与插件工具进入 introspect.details.tool，不再进入顶层 tool.details
- 本插件自身工具与其他工具一样进入 tool.details，不单列插件开销
- 顶层关系：time_consume_total_ms = tool.total_ms + model.total_ms + introspect.total_ms
- 每层 ratio 相对该层父级总量，4 位小数，缺失差值补给最大项
- 恢复产生的零时长轮次不参与注入判定

状态

| 状态 | 行为 | 迁入 | 迁出 |
| active | 正常判定并注入 | 初始状态，或模型重启 | 模型调用 time_introspect_shut |
| dormant | 不注入；仍归档每轮耗时 | 模型调用 time_introspect_shut | 模型调用 time_introspect_waken |

没有自动冷却，没有自动休眠。是否让插件安静由模型决定。

用户可见气泡

- 气泡做进对话记录，不覆盖输入框，不阻塞模型或用户操作，随聊天记录滚动
- 每个本插件工具调用位置都有一个红点按钮；红点只是位置标记，不表示调用失败
- 新调用出现时自动展开一行简要提示，3 秒后收起；红点保留
- 只有挂载时距调用时间不超过 15 秒的调用会自动展开；历史记录中的调用只显示红点，避免打开旧会话时同时弹出大量气泡
- 点击红点展开或收起详细信息；展开后不会自动收起，直到再次点击
- 详情包含工具名、阶段、时间、轮次、参数与结果；结束反思会显示本次反思耗时，状态查询会显示结果 JSON
- 文案跟随 Web UI 语言

归档与自省 Tab

- 归档在 turn/end 生成，每一轮一条；结构与注入 JSON 相同，但未触发注入的轮次缺失的总账字段为 null
- 归档只进入会话投影和 profile 文件，不进入模型上下文，不影响注入判定
- 文件路径：$DSH_HOME/profiles/<profile>/time-introspect/<sessionId>.json；内容为 sessionId、updatedAt、archive 数组与 injections 数组，最近 200 轮
- 注入记录逐条保存注入轮次、被统计轮次、预估、实际、超出量、是否开始反思、是否结束反思与反思耗时
- 反思状态分为：
- 已反思：start 与 stop 都完成
- 反思未完成：已 start 但轮次结束前没有 stop
- 未反思：注入后没有 start
- 已中断：反思窗口被 shut 丢弃
- 等待中 / 反思进行中：当前轮次尚未结束时的临时状态
- 会话区域的 Tab 与其他视图标签并列；归档卡片与注入记录默认收起，展开后可继续展开工具 details 数组；Tab 数据随会话投影实时更新，文件是持久化镜像

与时钟插件的关系

本插件不替代 dsh-time-context 或 dsh-time-reminder。那两者负责「让模型知道时间」，本插件负责「在超时后告诉模型时间去了哪，并让反思本身有成本」。三者可以同时挂载。

兼容性

| 项目 | 说明 |
| dsh | 0.2.0-rc.2, 0.2.1-rc.1, 0.2.1-rc.2 |
| Node.js | ^22.19.0 或 >=24.0.0 |
| 判定方式 | engines.dsh 与所有 @deepseek-ai/dsh* peer 声明同一组受支持版本；0.2.1-rc.1 起存在 engines.dsh 时以它为准 |

开发 sh
npm install
npm run typecheck
npm test
npm run build
npm run pack

构建产物在 lib/，入口为 lib/index.js，客户端入口为 lib/client.js。npm run build 同时生成 host 与 client；npm run build:client 只重建客户端。npm run pack 或直接 npm pack 的 tgz 产物都会落入 release/，根目录不保留。机制细节见 docs/mechanism.md。

目录结构： text dsh-time-introspect/ ├── .gitignore # git 忽略规则 ├── COPYRIGHT # 版权声明 ├── LICENSE # Apache-2.0 许可证 ├── README.md # 中文 README ├── README_en-US.md # 英文 README ├── client/ # 浏览器半端: 红点气泡与耗时自省 Tab ├── cordis.patch.yml # 组合包 patch 层 ├── docs/ # 项目文档与官方开发文档快照 ├── package.json # 包清单 ├── scripts/ # 辅助脚本 ├── src/ # 插件源码 ├── test/ # 单元测试 ├── tsconfig.build.json # 构建配置 ├── tsconfig.json # 类型检查配置 └── version.index.md # 版本号出现位置索引

边界

- 不定义「合理耗时」标准，只呈现分布与偏差
- 不用于考核、排名或惩罚，耗时数据只为反馈与审计
- 不修改模型权重，不训练，只做推理时的上下文干预
- 没有预估记录的轮次不触发注入，但仍进入归档
- 不自动冷却，不自动休眠
- 不写自定义会话事件，状态由官方事件日志折叠得到；profile 归档 JSON 只做持久化镜像，不参与判定
- 只对主会话生效

许可证

Apache-2.0