Cerbur/clutch-dsh#clutch-dsh-title

English | 简体中文

@cerbur/clutch-dsh-title

@cerbur/clutch-dsh-title 为新的 DSH Session 提供可配置、易浏览的标题。在 DSH Web 中打开 设置 → 会话标题，可以选择内置或已保存的模板，也可以创建自己的模板。

标题可以组合会话日期、固定文字、受控分类和首条 prompt 的简短描述，例如 0912 | 🚀 | add token statistics。生成结果仍显示在 DSH 原生 Session 列表中；本 package 增加标题 provider 和设置管理器，不会替换原生列表。

安装

从 npm 安装

在已安装 DSH CLI 的环境中，将 package 加入 Web profile 并启动 DSH Web：

dsh plugin --profile web add @cerbur/clutch-dsh-title
dsh web

如果使用 DeepSeek Harness 源码 checkout 且没有独立的 dsh 命令，可使用等价的 pnpm dsh 形式。

如果安装时 DSH 已在运行，请在安装后重启 DSH Desktop，或重启 DSH Web 服务后刷新浏览器页面。 仅刷新页面无法应用 host 变更。插件客户端已加载但 host 服务尚不可用时，会通过原生 toast 提醒重启，每次客户端加载只提示一次；host 正常时不会提示。

从本地 checkout 安装

package 的 lib/ 目录由构建生成，不会提交到仓库。先构建 workspace package 和 DSH 源码 checkout，再通过绝对路径添加 package：

cd /absolute/path/to/clutch-dsh
pnpm install
pnpm --filter @cerbur/clutch-dsh-title build

cd /absolute/path/to/deepseek-harness
pnpm install
pnpm run build
pnpm dsh plugin --profile web add /absolute/path/to/clutch-dsh/packages/clutch-dsh-title
pnpm dsh web

修改源码、package 元数据或 cordis.patch.yml 后，需要重新构建 package，并再次执行绝对路径 添加命令。

功能

功能	预览	作用
原生 Session 标题		选中的模板会自动组合日期、分类、固定文字和首条 prompt 摘要，生成紧凑标题。标题仍位于 DSH 原生 Session 列表中；plugin 不会接管该列表。
模板管理器		设置 → 会话标题支持预览、复制、编辑、保存、激活和删除，也可以在同一页面启用或关闭自定义标题生成。
灵活的模板字段	—	datetime 和 literal 字段以确定性方式解析，不使用模型。llm-enum 和 llm-text 是模型字段；当前模板引用的 LLM 字段会在一次结构化请求中提取。
生成统计	—	累计成功调用与有消耗的失败调用次数，查看累计输入/输出/总 Token，以及可用时的最近一次模型调用明细。确认后可以重置已保存的统计。
输出修复与错误日志	—	展开 Token 统计中的「重试设置」，选择 0–3 次额外调用并查看计数、最后一次修复时间和最近 10 条异常，并在确认后重置。

使用

选择标题模板

1. 使用 dsh web 启动 DSH Web。
2. 打开设置 → 会话标题。
3. 保持使用标题模板开启，选择一行并点击激活。
4. 创建新的 Session，或对已有 Session 使用 DSH 原生的标题刷新操作。

新设置文件默认选中只读的 default 模板。新选择的格式不会改写已有标题，除非 DSH 显式 生成或刷新标题。

管理模板

全新的设置包含可编辑的 emoji 模板，其描述最多 64 个 Unicode 字符，同时保持内置 default 模板处于选中状态。emoji 模板可以编辑或删除；删除后，在之后重新注册设置时不会自动重新出现。

• 可以复制任意一行（包括 default），打开可编辑副本。
• 为副本填写唯一名称，编辑 YAML 并点击保存。保存不会自动激活。
• 需要让已保存模板生效时，点击激活。
• 可以查看或选择 default，但不能编辑或删除。
• 删除当前激活的自定义模板后，会选择 default。
• 每一行在编辑时都会展示示例标题。示例不调用模型。

创建自定义模板

编辑器接受 template 和可选的 fields。模板中的 ${daytime} 会从 fields.daytime 解析，${desc} 会从 fields.desc 解析：

每个 ${fieldName} 引用都会由 fields. 解析；它只是字段替换，不是指令或表达式。

template: '${daytime} | ${desc}'
fields:
  daytime:
    kind: datetime
    source: session.createdAt
    format: MMDD
    timezone: Asia/Shanghai
  desc:
    kind: llm-text
    instruction: Summarize the first prompt in a few words
    maxCharacters: 32

确定性值使用 datetime 或 literal；受控的模型分类使用 llm-enum；简短的模型生成文本使用 llm-text。保存时会先校验 YAML 和字段定义，校验通过后模板才可以被激活。

刷新 / 重新生成标题

使用 DSH 原生的 Session 标题刷新操作，显式再次运行当前 provider。刷新使用当前模板和 Session 原始的 createdAt，因此仅刷新标题不会改变日期字段。

关闭自定义标题

在设置 → 会话标题中关闭使用标题模板。已保存的模板和选择会保留，但 DSH 会恢复使用原生 的首条 prompt 标题生成器。

查看生成统计

打开设置 → 会话标题，可以查看纳入统计的标题模型调用次数、输入 Token、输出 Token、总 Token， 以及模型提供时的最近一次模型调用明细。每次成功的模型调用计一次，即使用量为零或未上报用量。 失败调用只要报告了实际 Token 消耗也计一次；仅排除失败且消耗为零或未上报消耗的调用。 重试调用遵循相同规则，因此一次有消耗的失败尝试加一次成功修复计两次。成功且有消耗的同一次 调用不会重复计数。Token 包含所有调用报告的实际消耗。只包含确定性字段的模板不增加生成统计。 重置需要确认。

成功读取当前主机的统计后即可重置，包括本地安装的插件。Token 统计块和计数格在浅色与深色 主题中都继承设置面板的背景。

旧统计缺少重建每次调用结果与消耗所需的完整明细，因此保留历史计数。重置统计后可从零开始 按新规则累计。

设置修复次数并查看错误日志

在 Token 消耗统计块中，展开计数下方默认折叠的「重试设置」，即可访问输出修复设置和错误日志。 使用其中的下拉菜单选择模型输出不可用时额外调用的次数，范围为 0–3，0 表示关闭修复。 计数、重试设置区域和错误日志之间使用分割线分隔。 下拉框使用 DSH 设置选择器的底色，在悬停或展开时高亮。 选择会立即通过 DSH 设置保存，用于后续生成或刷新。所有调用共用标题超时预算；传输错误、 取消或超时不重试。

展开「重试设置」后直接显示错误日志，展示累计异常次数、重试次数、修复成功次数、最后一次 成功修复时间，以及最近 10 条异常的表格，最新记录在前。展开一行的响应详情可以查看消息序号、 拒绝原因和有界的原始响应。重新加载会刷新诊断数据。「重置异常统计」需要确认，并重置整个 错误日志域，包括异常次数、重试次数、修复成功次数、最后一次修复时间和全部异常记录。 Token 统计和模板各自独立。

clutch_title_diagnostics storage domain 仅持久化最近 10 条异常，新增记录时淘汰最旧记录， 不会减少累计计数。旧的 lastIncident 在读取时导入，下次写入时替换为 recentIncidents。 titleStats remote namespace 提供 getDiagnostics 和 resetDiagnostics；每条异常还会输出一条 warning。诊断读取失败时，面板会显示错误，并禁用重置操作，直到读取成功。 即使后续设置刷新挂起，重置结果与错误也会及时返回。 诊断独立刷新，错误日志缓慢或不可用不会延迟模板加载或修复次数保存。 诊断写入在超时后成功时只累计一次；后续到达的记录和重置操作仍保持独立。 更换存储连接时，也会保留这些已完成的写入及后续记录。

模板参考

模板使用简单的字段替换：

字段类型	用途	是否使用模型
datetime	使用 session.createdAt 格式化 Session 时间戳	否
literal	插入固定文字	否
llm-enum	从声明的受控值中选择一个	是
llm-text	生成一段简短文本	是

使用 ${identifier} 形式的占位符。identifier 必须对应已声明的字段。占位符不支持函数、 表达式、条件、循环或任意代码。未知字段、格式错误的 YAML 和非法字段定义会在校验时被 拒绝。

配置

模板设置仍以 DSH profile 中的 clutch-dsh-title 条目为键。DSH 0.1.6 及更早版本将其保存在 $DSH_HOME/settings.yaml；DSH dsh-v0.2.0-rc.1 将相同的启用状态、当前模板和模板映射保存为 活动 Web profile cordis.yml 中的 volatile 字段。DSH 的一次性设置导入器会将已有 $DSH_HOME/settings.yaml 区段迁入 profile，并将旧文件重命名为 settings.yaml.imported。

DSH 通常将 ~/.dsh 用作 $DSH_HOME，但 source of truth 取决于 DSH 版本，始终是 DSH 配置而非 写死的 home 路径。package 不使用 browser storage，也不使用 clutch.yaml。通过外部方式修改 source-of-truth 设置后，DSH 的重新加载路径会读取这些修改。非法模板条目会继续显示在设置中， 便于修复，而不会被静默丢弃。

profile 配置和设置 → 会话标题可以设置：

• repairAttempts：当模型返回不可用输出时，一次标题生成最多额外发起的模型调用次数。默认 1， 可接受 0 到 3，更大的值会被拒绝。这些调用与 timeoutMs 共用同一个预算，并且绝不会用于 传输错误、取消或超时。

行为与限制

• 自动标题只使用首条符合条件的用户 prompt，后续消息不会自动替换标题。
• 首条 prompt 过长时，会在配置的输入字节预算内裁剪，并尽量保留开头和结尾。原始 Session 消息不会被修改。
• 修改模板只影响后续生成或显式刷新，不会批量重写已有标题。
• 当前激活模板缺失或非法时，设置管理器会使用内置 default 模板。
• 如果字段提取、渲染或自定义标题生成失败，DSH 会使用正常的首条 prompt 标题生成器。该 fallback 是 DSH 自己对首条 prompt 的截断结果，因此不遵循模板。
• 模型会被要求只输出一个 JSON 对象：键集合必须精确等于模板引用的 LLM 字段，枚举字段必须使用声明的 字面值之一，并给出字面形状示例。当响应仍不可用时，package 会再发一次有界的纠正轮，把被 拒绝的响应原文引用回去并说明拒绝原因，最多 repairAttempts 次额外调用。
• 不可用的输出（包括 max-tokens 截断和意外的 tool-calls）会在配置的预算内修复。 传输错误、取消或超时耗尽会保留自身错误并立即 fallback；所有 尝试共用同一个 timeoutMs 预算。
• 每个 incident 会记录一次日志（provider、model、消息 seq、拒绝原因，以及截断到 2000 字符的 原始响应），并持久化到 clutch_title_diagnostics storage domain（每个 incident 最多 4 条 被拒绝的响应，仅保留最近 10 条 incident；storage 不可用时，包括打开或写入挂起，内存最多缓存 64 条 incident，缓存满后淘汰最旧的缓存记录）。持久化是 best effort，绝不会延迟或 让标题生成失败。
• 标题长度限制、标题持久化、手动重命名后的 pin、刷新和取消 pin、fork 的标题事件继承、 取消以及过期结果保护，仍由 DSH 负责。
• bundle patch 会先禁用 DSH 默认的 session-title-first-prompt-llm provider，再插入本 provider。DSH 只允许一个 session-title provider：不要重新启用默认 provider，也不要在 同一 profile 中安装另一个 title provider。第二次注册会被 DSH 的单 provider 约束拒绝。

要求

• DSH peer 包括 @deepseek-ai/dsh-settings、@deepseek-ai/dsh-storage-domain、 @deepseek-ai/dsh-typert-protocol、@deepseek-ai/dsh-api-remotes、 @deepseek-ai/dsh-client-locale、@deepseek-ai/dsh-client-ui-settings、 @deepseek-ai/dsh-client-ui-slots、@deepseek-ai/dsh-client-ui-primitives、 @deepseek-ai/dsh-llm、@deepseek-ai/dsh-session、@deepseek-ai/dsh-session-title、 @deepseek-ai/dsh-session-title-llm、@deepseek-ai/dsh-timeout 和 @deepseek-ai/dsh-util-values，全部要求 >=0.2.0-rc.1。
• Cordis：@deepseek-ai/cordis ^4.0.1。
• 运行 DSH dsh-v0.2.0-rc.1 需要 Node.js ^22.19.0 || >=24.0.0。
• Profile：提供 package 所声明的 session、session-title、LLM、settings、storage、remote 和 browser settings service 的 DSH Web profile。

兼容性

通过 Cordis 配置提供的 template 和 fields 仍然兼容。当这些值来自 profile 配置时，设置页面 会将它们显示为可编辑的 legacy 行。当前设置模板管理器和 legacy 配置使用相同的校验规则。

本插件的字段提取包装消息使用 DSH 原生的 dsh-session-title-llm 消息来源类型，以满足会话重新加载时的 format v4 关系校验，同时记录 clutch-dsh-title 作为标题提供者。DSH 0.1.7 还将旧 settings 注册 API 替换为 profile 中的 volatile Config 字段；同一标题编辑器继续使用这些字段，并由 DSH 在 profile 迁移时导入旧 settings。

模型路由和可选的 reasoning 设置属于 profile 级配置，不属于模板字段设置。请保持 DSH 默认 title provider 关闭，也不要将第二个 title provider 与本 package 组合。

开发

在 workspace 根目录构建、类型检查和测试：

pnpm --filter @cerbur/clutch-dsh-title typecheck
pnpm --filter @cerbur/clutch-dsh-title build
pnpm --filter @cerbur/clutch-dsh-title test

package 特有的发布参数和源码安装限制见 docs/RELEASING.md。面向用户的发布历史见 RELEASE-LOG.md。

卸载

使用 DSH CLI：

dsh plugin --profile web remove @cerbur/clutch-dsh-title

如果使用 DeepSeek Harness 源码 checkout，可对同一个 package name 使用 pnpm dsh plugin --profile web remove。

友情链接

• LINUX DO — 新的理想型社区。