@khorsheed/dsh-message-timeline 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 变更记录
+
+## 0.1.0（2026-08-22）
+
+首个公开发布。
+
+- 会话左缘一条悬浮时间轴，每行一条用户消息（steering 消息可配置关闭）
+- 环境化静止态：日常只显示压淡的刻度细线，悬停或聚焦才展开文字预览
+- 阅读位置跟踪：当前位置的刻度保持高亮，停在超长回复中时锚定在所回答的用户消息上
+- 点击行直接把会话滚动到对应消息，列表跟随阅读位置
+- 长历史友好：更早历史在面板滚动到顶部时按需翻页加载

package/README.en.md

@@ -0,0 +1,79 @@
+# dsh-message-timeline
+
+English | [中文](README.md)
+
+A jump-to-message timeline for the dsh web GUI: a floating rail on the chat's left edge with one row per user message. Hover to reveal previews, click to scroll the transcript straight to that message.
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-timeline1.png" width="480" alt="floating message timeline along the chat's left edge">
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-timeline2.png" width="480" alt="the timeline rests as a thin rail out of sight, expanding on hover">
+
+## Features
+
+- **One row per user message** — tick plus ellipsized one-line preview; steering messages count too (configurable off).
+- **Ambient rest state** — only dimmed ticks show until you hover the strip or focus the list.
+- **Reading position tracking** — the current position's tick stays lit blue, anchoring to the user message a long answer is replying to.
+- **Click to jump** — a row scrolls the transcript to that message; the list follows the reading position.
+- **Long-history friendly** — a short list centers vertically; a long one scrolls and pages older history at its top.
+
+## Install
+
+```sh
+dsh plugin --profile web add @khorsheed/dsh-message-timeline
+```
+
+Then restart the web instance. Uninstall:
+
+```sh
+dsh plugin --profile web remove @khorsheed/dsh-message-timeline
+```
+
+## Config
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Master switch; false hides the panel entirely. |
+| `includeSteering` | `true` | Count steering messages (user text admitted mid-turn) as rows. |
+| `panelWidth` | `360` | Panel width in px (clamped 120–640); shrinks to fit a narrow column, hides entirely when the gutter is too small. |
+| `initialPages` | `5` | History pages (50 events each) prefetched on open; older pages load when the panel is scrolled to its top (clamped 1–20). |
+
+## Compatibility
+
+- npm release line (`@deepseek-ai/dsh@0.1.1-rc.2`): ✅ full — the rc.8→0.1.1-rc.1 API audit (2026-08-21) confirms every surface this plugin consumes is unchanged or additive (the ProjectionDefinition restructure, cacheHitPercent return-type change, and the credentials/updated event rename do not touch this package); no source change was needed; re-audited for rc.2 (2026-08-22): consumed surface unchanged, full build+test green.
+- source line (deepseek-harness master): ✅
+
+## Known Limitations
+
+- **DOM probe coupling** — the panel targets official row attributes and the `[data-conversation-scroll]` scrollport; if the official DOM changes, it hides itself (one `console.warn`) until the probe is updated.
+- **Single rendered session** — rows and jumps address only the currently rendered conversation.
+- **Loaded history only** — rows cover materialized nodes; older messages arrive one page at a time when the panel is scrolled to its top.
+- **No full index view yet** — a searchable message-index tab is planned.
+
+## How it works
+
+<details>
+<summary>Internals (click to expand)</summary>
+
+The plugin is purely additive and modifies no official code.
+
+- `src/client/index.ts` — plugin body (`apply`/`inject`)
+- `src/client/rail-tracker.ts` — the only DOM the plugin touches: read-only probes plus the jump's scroll write
+- `src/client/TimelineRail.tsx` — the panel component
+- `src/client/preview.ts` — message content to one-line preview text
+- `src/index.ts` — empty host `apply`, anchors the plugin into the host Loader
+
+**Mount & data** — one entry in the official `conversation.session.header.utilities` slot anchors the plugin into the session scope; the panel renders through a body portal with fixed geometry measured from the official scrollport. Rows derive from the framework `useSession` chat snapshot (`s.chat.order` / `s.chat.nodes`), filtered to `user` / `steering` nodes — no store outside the session, no event registration.
+
+**Jump & degradation** — clicking a row finds the transcript row by the official `data-chat-anchor-key` attribute and writes `scrollTop`; the official ChatView treats that as a normal reader move (bottom-follow and scroll memory keep working). The probed attributes are official render output, not a declared API: when they change, the panel hides itself with one `console.warn`; nothing throws and the boot never fails.
+
+**Model experience: none.** The panel reads the session snapshot and scrolls the transcript; it never sends prompts, appends session events, or enters the session log. KV cache effect: none. The `enabled` config turns the plugin off entirely; removing it from cordis.yml removes every surface it adds.
+
+</details>
+
+## Development
+
+Part of the [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo (`packages/message-timeline`). Issues and contributions welcome there.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record: the git blob hash of each side as of the
+# last confirmed-consistent state. Both languages carry equal authority; after
+# editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/message-timeline/README.en.md
+packages/message-timeline/README.en.md: 6c23db63db34214d844f5db121fb8e87b9565a05
+packages/message-timeline/README.md: da68ead740c42b8ceb770047aefdb8f61ce733d2

package/README.md

@@ -0,0 +1,79 @@
+# dsh-message-timeline
+
+[English](README.en.md) | 中文
+
+dsh web GUI 的历史消息导览:会话左缘的一条悬浮时间轴,每行一条用户消息。悬停显示预览,点击直接把会话滚动到对应消息。
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-timeline1.png" width="480" alt="会话左缘的悬浮消息时间轴">
+
+<img src="https://raw.githubusercontent.com/Khorsheed/dsh-web-basic/main/docs/screenshots/message-timeline2.png" width="480" alt="时间轴日常收成一条细线不占视线,悬停才展开">
+
+## 特性
+
+- **每行一条用户消息**——竖刻度加单行省略预览;steering 消息也计入(可配置关闭)。
+- **环境化静止态**——只显示压淡的刻度,悬停刻度条或聚焦列表才展开文字。
+- **阅读位置跟踪**——当前位置的刻度保持蓝色高亮,停在超长回复中时锚定在所回答的用户消息上。
+- **点击跳转**——点击行把会话滚动到对应消息;列表跟随阅读位置。
+- **长历史友好**——列表短时垂直居中,长时隐形滚动并在顶部翻页加载更早历史。
+
+## 安装
+
+```sh
+dsh plugin --profile web add @khorsheed/dsh-message-timeline
+```
+
+然后重启 web 实例。卸载:
+
+```sh
+dsh plugin --profile web remove @khorsheed/dsh-message-timeline
+```
+
+## 配置
+
+| 字段 | 默认 | 含义 |
+| --- | --- | --- |
+| `enabled` | `true` | 总开关;false 时面板完全不渲染。 |
+| `includeSteering` | `true` | 回合中插入的用户消息(steering)是否也算行。 |
+| `panelWidth` | `360` | 面板宽度(px,限 120–640);窄列自动收缩,左缘沟槽放不下时整条隐藏。 |
+| `initialPages` | `5` | 面板打开时预取的历史页数(每页 50 条事件);更早历史在面板滚动到顶部时按需加载(限 1–20)。 |
+
+## Compatibility
+
+- npm 发布线（`@deepseek-ai/dsh@0.1.1-rc.2`）：✅ 完整——rc.8→0.1.1-rc.1 API 审计（2026-08-21）确认本插件消费的所有面无变化或纯增量（ProjectionDefinition 重构、cacheHitPercent 返回值变更、credentials/updated 事件改名均不涉及本包），无需改动源码；rc.1→rc.2 复核（2026-08-22）：消费面无变化，全量构建测试通过。
+- 源码线(deepseek-harness master):✅
+
+## 已知限制
+
+- **依赖官方 DOM 探针** —— 面板针对官方行属性与 `[data-conversation-scroll]` 滚动区;官方结构变化时面板自行隐藏(console.warn 一次)直到探针更新。
+- **单会话渲染** —— 行与跳转只作用于当前渲染的会话。
+- **仅已加载历史** —— 行覆盖已物化的节点;更早消息在面板滚动到顶部时逐页加载。
+- **暂无整页导览** —— 可搜索的消息索引标签页在计划中。
+
+## 实现原理
+
+<details>
+<summary>内部结构(点击展开)</summary>
+
+插件纯增量、不改任何官方代码。
+
+- `src/client/index.ts` —— 插件主体(`apply`/`inject`)
+- `src/client/rail-tracker.ts` —— 插件唯一接触的 DOM:只读探针加跳转时的滚动写入
+- `src/client/TimelineRail.tsx` —— 面板组件
+- `src/client/preview.ts` —— 消息内容转单行预览文本
+- `src/index.ts` —— 空的宿主 `apply`,只负责把插件锚定进宿主 Loader
+
+**挂载与数据** —— 一个条目注册进官方 `conversation.session.header.utilities` 槽位,把插件锚定进会话作用域;面板通过 body portal 以固定几何渲染,数据从官方滚动区实测。行取自框架 `useSession` 会话快照(`s.chat.order` / `s.chat.nodes`),过滤 `user` / `steering` 节点——不持有会话外状态,不注册事件。
+
+**跳转与降级** —— 点击行按官方 `data-chat-anchor-key` 属性找到会话行并写 `scrollTop`;官方 ChatView 把这种程序化滚动当正常读者移动处理(底部跟随与滚动记忆照常工作)。探测的属性是官方渲染产物而非契约 API:官方改结构时面板自行隐藏并 console.warn 一次,不抛错、boot 永不失败。
+
+**模型体验:无。** 面板只读会话快照并滚动会话,不发送提示词、不追加会话事件、不进会话日志。KV 缓存影响:无。`enabled` 配置可整体关闭插件;从 cordis.yml 移除本插件即移除它添加的所有界面。
+
+</details>
+
+## 开发
+
+隶属 [dsh-plugins](https://github.com/Khorsheed/dsh-plugins) monorepo(`packages/message-timeline`)。问题与贡献请移步该仓库。
+
+## 变更记录
+
+见 [CHANGELOG.md](CHANGELOG.md)。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# message-timeline bundle patch: inserts the plugin row into the composing profile.
+# The browser half is discovered through the package.json dsh.client block; the
+# node half is the empty apply that makes the row a real loader entry.
+- insert:
+    - id: message-timeline
+      name: '@khorsheed/dsh-message-timeline'