dsh-session-title-stamp 0.0.0-stage → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xuedipiaofei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,268 @@
-# Temporary Holding Version
+# dsh-session-title-stamp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/dsh-session-title-stamp.svg)](https://www.npmjs.com/package/dsh-session-title-stamp)
+[![license](https://img.shields.io/npm/l/dsh-session-title-stamp.svg)](./LICENSE)
+[![DSH](https://img.shields.io/badge/DSH-0.2.x-4f46e5.svg)](https://github.com/deepseek-ai/deepseek-harness)
+
+English | [中文](./README.zh.md)
+
+A DeepSeek Harness title provider for a configurable `DATE | CATEGORY | NAME`
+title. Beyond automatic naming:
+
+- **Auto refresh** — after a completed turn, with a 2-minute cooldown and a
+  100-message freeze; forks and user-pinned titles are skipped.
+- **Manual refresh** — the conversation-header ↻ button, the session row's
+  **Regenerate title** menu item, or `/retitle`.
+- **Hover stats** — elapsed time, estimated CNY cost, and token count on the
+  session hover card.
+- **Category language** — `categoryPreset: zh | en`, or your own `categories`.
+- **Failure-safe** — a failed retitle keeps the current title.
+- **Zero build** — pure Host logic plus a small hand-written browser half.
+
+Default format:
+
+```text
+DATE | CATEGORY | NAME
+```
+
+For example, with `categoryPreset: en`:
+
+```text
+1028 | Analysis | Short-drama platform verification
+1027 | Fix | Four-device acceptance rework
+1026 | Deploy | Ubuntu environment setup
+```
+
+Dates are computed by the plugin from the session's creation time, never by the
+model. Categories are chosen from a small configurable taxonomy and validated
+locally. The model only proposes the category and the name; the provider owns
+the final format. The default taxonomy is Chinese; set `categoryPreset: en` for
+the English labels above.
+
+## Why
+
+Long-lived workspaces collect dozens of sessions whose titles are either the
+first few words of the first message or an auto-summary that drifts. A fixed
+`date | category | name` convention makes the sidebar scannable across projects,
+and mirrors conventions used by other coding agents.
+
+## Requirements
+
+- DeepSeek Harness `>=0.2.1-rc.3 <0.3.0`.
+- A working model route for the session; the title request uses the session's
+  current provider/model unless `provider`/`model` are configured.
+
+## Install
+
+### DSH Desktop / Web with Discover
+
+Add this market index source in **Plugins → Discover → Index sources**:
+
+```text
+https://cdn.jsdelivr.net/gh/xuedipiaofei/dsh-session-title-stamp@v0.4.1/market/index.json
+```
+
+Then install **Session title stamp** from the list. The plugin installs as a
+profile bundle and appears in the Plugins page, where it can be enabled or
+disabled like any other bundle.
+
+### CLI
+
+From GitHub:
+
+```sh
+dsh plugin --profile <profile> add github:xuedipiaofei/dsh-session-title-stamp
+```
+
+From npm:
+
+```sh
+dsh plugin --profile <profile> add dsh-session-title-stamp
+```
+
+For a local checkout:
+
+```sh
+dsh plugin --profile <profile> add ./dsh-session-title-stamp
+```
+
+The Electron Desktop profile is managed by the application; use its Plugins
+page rather than `dsh plugin --profile desktop`.
+
+The bundle patch disables the shipped `session-title-llm` row and inserts this
+provider. Do not enable the official
+`@deepseek-ai/dsh-experimental-session-titles-bundle` at the same time: both
+replace the same provider slot, and the title service accepts only one provider.
+If another provider wins the registration race, this plugin logs a warning and
+stays inactive instead of failing startup.
+
+## How it works
+
+- `cordis.patch.yml` disables `session-title-llm` and inserts the
+  `session-title-stamp` row from this package.
+- `lib/index.js` registers a provider through `ctx.sessionTitle.register()` and
+  reuses `@deepseek-ai/dsh-session-title-llm` for route selection, timeouts,
+  cancellation, token limits, and exact auxiliary-request logging.
+- `lib/format.js` is dependency-free: local-time date parts, template rendering,
+  category validation, name sanitizing, and UTF-8 byte truncation.
+
+The provider computes the date from `session.header.createdAt` in the host's
+local time zone, asks the model for `{"category":"...","name":"..."}`, validates
+the category, and renders the template. Empty `{type}` or `{topic}` segments
+remove their neighbouring separator instead of leaving `||`.
+
+### Retitle cadence
+
+The provider is registered as `first-prompt`, so the title service names the
+session once. After that, the plugin refreshes on a completed turn (`turn/end`)
+with two guards:
+
+- **cooldown** — at most one automatic refresh every `refreshMinIntervalMs`
+  (default 2 minutes), so a fast first answer does not generate twice;
+- **freeze** — after `refreshMaxTurns` user messages (default 100), automatic
+  refresh stops; long sessions rarely change their main topic. `/retitle`
+  still works.
+
+Forks and subagent sessions are skipped, as are titles pinned by a manual
+rename. Setting `refreshOnTurnEnd: false` restores the legacy message-count
+mode using `retitleEvery`.
+
+### Header refresh and hover stats
+
+0.4.0 adds a small browser half:
+
+- a **refresh icon** in the conversation header; it runs the same `/retitle`
+  command as typing it, and is disabled while the session is running.
+- a **hover-card line** under the native relative time, for example
+  `Duration 1h 51m · est. ≈¥4.11 · 131.7M tokens`;
+- a **Regenerate title** item at the top of the session row's `···` menu. It
+  runs the same `/retitle` command and adds no dialog.
+
+The hover line is derived from the `sessionStats` and `tokenUsage` projections,
+priced with the current DeepSeek CNY rate table, and labelled as an estimate.
+It is fetched from the host only when the hover card opens; a session that was
+never loaded is not resumed just to show the numbers. Native DSH already shows
+running / pending / completed-unread status (spinner, warning dot, idle line),
+so this plugin does **not** add a second status-color layer.
+
+If the hover line is missing, the browser half could not reach the host stats
+route; the refresh button and automatic titles are unaffected.
+
+### Failures
+
+- A failed retitle **keeps the existing title**: the provider throws, which is
+  the title service's signal to retain the previous revision.
+- Only a session with no title yet gets a local fallback: date, an inferred
+  category, and the first message's leading words.
+- A `max-tokens` finish is still parsed when it contains usable text; only an
+  unusable response counts as a failure.
+
+## Configuration
+
+Override the row in the profile's `cordis.patch.yml`:
+
+```yaml
+- id: session-title-stamp
+  config:
+    refreshOnTurnEnd: true
+    refreshMinIntervalMs: 120000
+    refreshMaxTurns: 100
+    categoryPreset: zh
+    template: '{date} | {type} | {topic}'
+    timeZone: Asia/Shanghai
+    maxNameChars: 20
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `refreshOnTurnEnd` | `true` | Refresh after a completed turn; `false` falls back to `retitleEvery` |
+| `refreshMinIntervalMs` | `120000` | Minimum gap between automatic refreshes; `0` disables the cooldown |
+| `refreshMaxTurns` | `100` | Stop automatic refresh after this many user messages; `0` = no freeze |
+| `retitleEvery` | `10` | Legacy message-count cadence, used only when `refreshOnTurnEnd: false` |
+| `backfillOnStart` | `false` | On startup, refresh live sessions whose title is still the fallback |
+| `backfillMaxSessions` | `30` | Maximum sessions in one backfill pass |
+| `backfillIntervalMs` | `2000` | Delay between backfill refreshes |
+| `template` | `{date} \| {type} \| {topic}` | Title template; see the placeholders below |
+| `dateFormat` | `MMDD` | Used by `{date}`: `MMDD` (`1028`), `YYMM` (`2610`), or `YYYYMMDD` |
+| `timeZone` | host local | IANA zone used for date/time placeholders |
+| `categoryPreset` | `zh` | Built-in category language: `zh` or `en` |
+| `categories` | preset | Explicit category list; overrides `categoryPreset` |
+| `maxNameChars` | `20` | Character cap before the byte cap applies |
+| `maxTitleBytes` | service cap (`80`) | Effective cap is the smaller of this and `session-title`'s cap |
+| `recentMessages` | `8` | First message plus this many recent messages are sent |
+| `maxInputBytes` | `4096` | Input budget for one title request |
+| `maxOutputTokens` | `4096` | Output cap, including reasoning tokens |
+| `timeoutMs` | `90000` | End-to-end title-request deadline |
+| `provider` / `model` | session route | Optional pair to route title generation independently |
+
+### Template placeholders
+
+| Placeholder | Meaning |
+|---|---|
+| `{date}` | Date in `dateFormat` (`1028`, `2610`, `20261028`) |
+| `{YYYY}` `{YY}` `{MM}` `{DD}` `{HH}` `{mm}` `{ss}` | Date/time parts; concatenate freely (`{YYYYMMDD}`, `{HHmm}`) |
+| `{type}` | Category; an empty value removes the segment and its separator |
+| `{topic}` | Name; an empty value removes the segment and its separator |
+
+An unknown placeholder is left verbatim (`{MMDD} {bogus}` keeps `{bogus}`), so a
+typo is visible instead of silently disappearing. The template owns the final
+format; `maxTitleBytes` still clips the result.
+
+The default taxonomy is Chinese. `categoryPreset: en` switches it to
+`Analysis / Build / Fix / Debug / QA / Deploy / Docs / Other`; `categories`
+overrides either preset with any labels you want. The prompt lists the configured
+labels and the local fallback maps common keywords onto them.
+
+## Privacy and cost
+
+- The first eligible user message plus up to `recentMessages - 1` recent
+  messages are sent to the model. Message text is framed as JSON to keep user
+  content from breaking delimiters.
+- The request uses the session's configured provider/model, or the optional
+  `provider`/`model` override. The plugin makes no other network calls and
+  collects no telemetry.
+- One auxiliary request is made for the first title, then at most one per
+  completed turn inside the cooldown, and none after the freeze threshold.
+  Title work is asynchronous and never delays the main agent response;
+  `maxOutputTokens`, `maxInputBytes`, and `timeoutMs` bound it.
+- The resulting title is stored in the session log as a normal `session/title`
+  event. A manual rename pins the title and later automatic revisions do not
+  overwrite it.
+
+## Compatibility notes
+
+- This package targets the DSH 0.2 line. `engines.dsh` refuses to install it on
+  0.3+ until it is updated against the new title API.
+- The bundle assumes the shipped row id `session-title-llm`. If another title
+  provider is registered first, this plugin logs and stays inactive; disable the
+  other provider and reload.
+- `llm`, `commands`, `sessions`, `sessionProjections`, and `connection` are
+  awaited lazily; a composition without one still loads the plugin and degrades
+  only the affected feature.
+- The browser half needs the Web composition's `sidebar.session.row.hover` and
+  `conversation.session.header.actions` seats. A shell that does not expose them
+  simply shows no button/hover line.
+- The provider imports `@deepseek-ai/dsh-session-title-llm` dynamically. A
+  missing or incompatible executor degrades to local naming, but a changed
+  `ctx.sessionTitle` API can prevent registration. Pin the DSH range when
+  publishing a release.
+
+## Development
+
+The repository has no runtime or build dependencies.
+
+```sh
+npm test               # format tests, provider tests with a stubbed executor, metadata/index checks
+npm run validate:index # optional: validate market/index.json with the official validator if installed
+npm run pack:check     # inspect the npm tarball contents
+```
+
+The provider test redirects `@deepseek-ai/dsh-session-title-llm` to
+`test/support/stub-executor.mjs` with Node's `module.registerHooks`, so it
+exercises the real provider without a DSH install or model credentials.
+
+Release steps are in [PUBLISHING.md](./PUBLISHING.md).
+
+## License
+
+MIT © 2026 xuedipiaofei

package/README.zh.md

@@ -0,0 +1,200 @@
+# dsh-session-title-stamp
+
+[English](./README.md) | 中文
+
+给 DSH 会话一个稳定的「日期 | 分类 | 名称」标题。除了自动命名，还包括：
+
+- **自动重算**：回答完成后更新，2 分钟冷却，超过 100 条消息后冻结；fork、子代理和手动固定的标题跳过。
+- **手动刷新**：会话头 ↻ 按钮、会话行 `···` 菜单「重新生成标题」、或 `/retitle`。
+- **悬停统计**：会话行悬停显示耗时、估算 CNY 成本、token 数。
+- **分类语言**：`categoryPreset: zh | en`，也可以用 `categories` 自定义。
+- **失败保护**：重算失败保留当前标题，不被兜底标题覆盖。
+- **零构建**：纯 Host 逻辑 + 小型手写浏览器半边。
+
+默认格式：
+
+```text
+日期 | 分类 | 名称
+```
+
+例如：
+
+```text
+1028 | 分析 | 绿洲短剧平台验证
+1027 | 整改 | 四台设备第十题验收返修
+1026 | 部署 | Ubuntu 环境初始化
+```
+
+日期由插件从**会话创建时间**计算，不交给模型；分类只能从可配置词表中选择，并在本地校验；模型只负责提出分类和名称，最终格式由模板决定。
+
+## 为什么
+
+工作区里的会话一多，侧栏标题要么是首条消息的前几个字，要么是容易漂移的自动摘要。固定成 `日期 | 分类 | 名称` 后，跨项目扫侧栏会快很多，也和其它 coding agent 的命名习惯一致。
+
+## 要求
+
+- DeepSeek Harness `>=0.2.1-rc.3 <0.3.0`。
+- 会话有可用的模型路由；标题请求默认跟随会话当前的 provider/model，也可用 `provider`/`model` 单独指定。
+
+## 安装
+
+### DSH Desktop / Web（Discover）
+
+在 **插件 → 发现（Discover）→ 索引源** 添加：
+
+```text
+https://cdn.jsdelivr.net/gh/xuedipiaofei/dsh-session-title-stamp@v0.4.1/market/index.json
+```
+
+然后在列表里安装 **Session title stamp / 会话标题印章**。插件以 profile bundle 的形式安装，之后可在插件页启停。
+
+### CLI
+
+从 GitHub 安装：
+
+```sh
+dsh plugin --profile <profile> add github:xuedipiaofei/dsh-session-title-stamp
+```
+
+从 npm 安装：
+
+```sh
+dsh plugin --profile <profile> add dsh-session-title-stamp
+```
+
+本地 checkout：
+
+```sh
+dsh plugin --profile <profile> add ./dsh-session-title-stamp
+```
+
+Electron Desktop 的 profile 由应用管理，请在应用的插件页安装，不要用 `dsh plugin --profile desktop`。
+
+bundle 的 patch 会禁用内置的 `session-title-llm` 行并插入本插件。**不要同时启用官方的 `@deepseek-ai/dsh-experimental-session-titles-bundle`**：两者替换的是同一个 provider 槽位，标题服务只接受一个 provider。如果别的插件先注册成功，本插件只打一条 warn 并保持 inactive，不会让启动失败。
+
+## 实现方式
+
+- `cordis.patch.yml` 关闭 `session-title-llm`，插入本包的 `session-title-stamp` 行。
+- `lib/index.js` 通过 `ctx.sessionTitle.register()` 注册提供者，并复用官方的
+  `@deepseek-ai/dsh-session-title-llm` 处理路由、超时、取消、token 上限和请求日志。
+- `client.js` 是手写的浏览器模块：会话头刷新按钮 + 悬停卡片成本/耗时行。
+
+插件从 `session.header.createdAt` 按**本机时区**计算日期，让模型返回
+`{"category":"...","name":"..."}`，校验分类，再按模板拼装。`{type}` 或 `{topic}` 为空时，相邻分隔符会一起消失，不会留下 `||`。
+
+### 重算节奏
+
+provider 注册为 `first-prompt`，首条消息由标题服务自动命名。之后插件在**每次 turn/end（回答完成）**时判断，并有两道闸：
+
+- **冷却**：距上次自动刷新不足 `refreshMinIntervalMs`（默认 2 分钟）就跳过；
+- **冻结**：用户消息数超过 `refreshMaxTurns`（默认 100）后停止自动刷新；`/retitle` 仍可用。
+
+fork 子会话、子代理会话，以及用户手动改名固定的标题都会跳过。`refreshOnTurnEnd: false` 时回退到旧的「每 N 条消息」模式（`retitleEvery`）。
+
+### 会话头按钮与悬停统计
+
+0.4.0 增加了一个很小的浏览器半边：
+
+- 会话头有一个**刷新图标**，效果等同输入 `/retitle`，会话运行中禁用；
+- 鼠标悬停会话行时，在原生相对时间下面多一行：
+  `耗时 1h 51m · 估算 ≈¥4.11 · 131.7M tokens`；
+- 会话行 `···` 菜单最上面多一项「重新生成标题」；同样调用 `/retitle`，
+  不新开弹窗。
+
+数字来自 `sessionStats` / `tokenUsage` 投影，按 DeepSeek 当前 CNY 价格估算，并标注「估算」。只在悬停时向宿主请求，不会为了显示数字去恢复未加载的会话。DSH 原生已经有运行中/待交互/完成未读的状态点与 loader，所以本插件**不再加一层状态颜色**。
+
+如果悬停行不显示，说明浏览器半边没连上宿主统计路由；刷新按钮和自动标题不受影响。
+
+### 失败时
+
+- 已经有标题时，重算失败会**保留旧标题**：provider 抛错，标题服务据此不提交新修订。
+- 只有还没有标题的会话才用本地兜底：日期 + 推断分类 + 首条消息开头。
+- 模型以 `max-tokens` 结束时，只要还能解析出可用文本就继续用；只有完全不可用才算失败。
+
+## 配置
+
+在 profile 的 `cordis.patch.yml` 里覆盖：
+
+```yaml
+- id: session-title-stamp
+  config:
+    refreshOnTurnEnd: true
+    refreshMinIntervalMs: 120000
+    refreshMaxTurns: 100
+    categoryPreset: zh
+    template: '{date} | {type} | {topic}'
+    timeZone: Asia/Shanghai
+    maxNameChars: 20
+```
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `refreshOnTurnEnd` | `true` | 回答完成后刷新；`false` 时回退到 `retitleEvery` |
+| `refreshMinIntervalMs` | `120000` | 自动刷新最小间隔；`0` 关闭冷却 |
+| `refreshMaxTurns` | `100` | 超过多少条用户消息后冻结自动刷新；`0` 不冻结 |
+| `retitleEvery` | `10` | 旧的按消息条数模式，仅在 `refreshOnTurnEnd: false` 时使用 |
+| `backfillOnStart` | `false` | 启动时对仍是 fallback 标题的 live 会话逐个补刷 |
+| `backfillMaxSessions` | `30` | 单次回填最多处理多少个会话 |
+| `backfillIntervalMs` | `2000` | 回填两次刷新之间的间隔 |
+| `template` | `{date} \| {type} \| {topic}` | 标题模板，占位符见下 |
+| `dateFormat` | `MMDD` | `{date}` 使用：`MMDD`（`1028`）/ `YYMM`（`2610`）/ `YYYYMMDD` |
+| `timeZone` | 本机时区 | 日期/时间占位符使用的 IANA 时区 |
+| `categoryPreset` | `zh` | 内置分类语言：`zh` 或 `en` |
+| `categories` | 预设 | 显式分类词表，优先级高于 `categoryPreset` |
+| `maxNameChars` | `20` | 名称字符上限（最终还受字节上限约束） |
+| `maxTitleBytes` | 标题服务上限（`80`） | 实际取它与 `session-title` 的较小值 |
+| `recentMessages` | `8` | 发送首条消息 + 最近 N 条消息 |
+| `maxInputBytes` | `4096` | 单次标题请求输入上限 |
+| `maxOutputTokens` | `4096` | 输出上限（含推理 token） |
+| `timeoutMs` | `90000` | 标题请求超时 |
+| `provider` / `model` | 跟随会话 | 可选，成对设置时用独立模型生成标题 |
+
+### 模板占位符
+
+| 占位符 | 含义 |
+|---|---|
+| `{date}` | 按 `dateFormat` 渲染的日期（`1028`、`2610`、`20261028`） |
+| `{YYYY}` `{YY}` `{MM}` `{DD}` `{HH}` `{mm}` `{ss}` | 日期/时间部件，可任意拼接（`{YYYYMMDD}`、`{HHmm}`） |
+| `{type}` | 分类；为空时整段及相邻分隔符一起消失 |
+| `{topic}` | 名称；为空时整段及相邻分隔符一起消失 |
+
+不认识的占位符会**原样保留**（`{MMDD} {bogus}` 会保留 `{bogus}`），方便一眼看出模板写错，而不是悄悄消失。最终仍受 `maxTitleBytes` 截断。
+
+默认分类是中文。`categoryPreset: en` 可切到
+`Analysis / Build / Fix / Debug / QA / Deploy / Docs / Other`；`categories`
+可以覆盖任意预设。提示词使用配置的标签，本地兜底也会把常见中英文关键词映射过去。
+
+## 隐私与成本
+
+- 发送首条有效用户消息，加上最多 `recentMessages - 1` 条最近消息。消息以 JSON 包裹，避免用户文本破坏分隔符。
+- 请求使用会话当前的 provider/model，或可选的 `provider`/`model` 覆盖。插件没有其它网络请求，也不收集遥测。
+- 首条标题一次辅助请求，之后每个完成的 turn 最多一次（受冷却/冻结约束）。标题生成是异步的，不会阻塞主回复；`maxOutputTokens`、`maxInputBytes`、`timeoutMs` 都会约束它。
+- 标题作为普通 `session/title` 事件写入会话日志。用户手动重命名后标题会被固定，后续自动命名不会覆盖。
+
+## 兼容性
+
+- 本包面向 DSH 0.2 线；`engines.dsh` 会在 0.3+ 上拒绝安装，直到按新 API 更新。
+- bundle 依赖内置行 id `session-title-llm`。如果已有其它标题 provider 先注册，本插件会打 warn 并保持 inactive；先停用另一个再重载。
+- `llm`、`commands`、`sessions`、`sessionProjections`、`connection` 都采用延迟注入；缺少哪个只损失对应能力，不影响插件加载。
+- 浏览器半边依赖 Web 组合的 `sidebar.session.row.hover` 和 `conversation.session.header.actions` 座位；没有这两个座位的 shell 不会显示按钮/悬停行。
+- 插件动态 import `@deepseek-ai/dsh-session-title-llm`。执行器缺失或不兼容时会降级为本地命名；如果 `ctx.sessionTitle` API 本身变化，则可能无法注册。
+
+## 开发
+
+仓库没有运行时依赖，也不需要构建。
+
+```sh
+npm test               # 格式测试、带 stub 执行器的 provider 测试、元数据/索引检查
+npm run validate:index # 可选：用官方校验器校验 market/index.json（需先安装该包）
+npm run pack:check     # 查看 npm tarball 内容
+```
+
+provider 测试用 Node 的 `module.registerHooks` 把
+`@deepseek-ai/dsh-session-title-llm` 重定向到
+`test/support/stub-executor.mjs`，因此不需要安装 DSH 或模型凭据。
+
+发布步骤见 [PUBLISHING.md](./PUBLISHING.md)。
+
+## 许可证
+
+MIT © 2026 xuedipiaofei