# dsh-conversation-outline — Implementation Spec

A DeepSeek Harness (DSH) client plugin that adds a **Codex-style conversation outline**:
a floating panel listing every user question in the current conversation, with
search and **click-to-jump** (switches to the Chat view, scrolls to the message,
flashes a highlight). Bilingual zh-CN / en.

This spec is the single source of truth for the team. All paths are relative to
the repo root `/Users/liziqing/Programs/agents/dsh-conversation-outline`.

---

## 1. Facts about DSH (verified against installed rc.6 packages)

Reference material on disk (READ ONLY):
- DSH packages (runtime + types): `/Users/liziqing/.npm/_npx/1e7f6d9597241db0/node_modules/@deepseek-ai/`
- Web profile flat node_modules (symlinks to the above, plus react):
  `/Users/liziqing/.dsh/profiles/node_modules/`
- Working third-party plugin example (published, MIT): `@nanmicoder/dsh-agent-teams`
  installed at `/Users/liziqing/.dsh/profiles/web/node_modules/@nanmicoder/dsh-agent-teams/`
  — its `lib/client.js` shows the exact loader-wrapper shape, panel CSS patterns,
  and `apply(ctx)` portal pattern.
- Authoritative dev skill: `/tmp/dsh-plugin-skill.md` (fetched from
  NanmiCoder/dsh-agent-teams `skills/dsh-plugin-development/SKILL.md`) and
  `/tmp/developing-dsh-plugins.md` (the long-form guide). Read both.

### 1.1 Client plugin contract

- A bundle = npm package whose `package.json` has:
  - `dsh.bundle.patch` → `./cordis.patch.yml` (bundle patch layer)
  - `dsh.client` = `{ platform: "web", inject: ["@deepseek-ai/dsh-client-runtime", ...] }`
    (`inject` is informational metadata; the REAL activation deps come from the
    client bundle's exported `inject` array)
  - `exports["./client"]` → the built browser bundle
- `cordis.patch.yml` is a top-level YAML array: `- insert: [{id, name, config}]`.
  `name` MUST equal the package name (roster resolves `require.resolve('<name>/package.json')`).
- The browser bundle is a CJS closure factory:
  ```js
  window.__ModuleLoader__.load({ id: "<package-name>", factory: (require) => {
    var module = { exports: {} }; var exports = module.exports;
    /* ...bundled code... */
    return module.exports;
  } });
  ```
  Built with tsdown@0.22 (cjs, platform browser), `external` = the platform
  module table (see 1.4), everything else inlined, sourcemap on, `clean: false`
  (must not wipe the tsc host output).
- Client plugin entry (`src/client/index.tsx`, MUST be `.tsx` to use JSX) exports:
  ```ts
  export const inject = ['slots', 'sessions', 'locale']  // cordis services to wait for
  export function apply(ctx: ClientContext): void { ... }
  ```
- HMR/dispose: every DOM node, React root, style tag, listener must be owned by
  `ctx.effect(() => disposer, 'label')`.

### 1.2 The host half

Even a client-only plugin needs a host row in the composition (the roster scans
Loader entries for `dsh.client` packages). The host module (`src/index.ts`, tsc
→ `lib/index.js`) must export a plugin body — a function or `{apply}` object
(cordis throws otherwise). Use a minimal:
```ts
import type { Context } from '@deepseek-ai/cordis'
export const name = 'dsh-conversation-outline'
export const inject: string[] = []
export function apply(ctx: Context): void {
  // client-only plugin: nothing to do on the host
}
```
(Keep a `Config` schema optional with a `z.object({})` default so the row config
is valid; follow the agent-teams shape.)

### 1.3 UI seams (verified in rc.6)

- `shell.overlay` — **the** seat for frame-wide floating surfaces:
  `kind: 'list'`, `scope: 'root'`, declared by `@deepseek-ai/dsh-client-ui-layout`.
  The layer is click-through by default; entries opt back into pointer events.
  Register with a fresh `id` (e.g. `dsh-conversation-outline.badge`), no `key`.
  Types: `@deepseek-ai/dsh-client-ui-layout/client` (module augmentation only).
  Render site verified in layout `lib/client.js` line ~236.
- Conversation scrollport: `[data-conversation-scroll]` (ui-conversation).
- Chat flow rows: each row div carries `data-chat-anchor-key=<node.key>` and
  `data-chat-flow-kind=<kind>` (ui-conversation `ChatNodeSeat`).
- Chat view tab id is `"chat"`, registered at `order: 0` (the FIRST tab in
  `[role="tablist"]`); trajectory is `order: 10`. Tab buttons are
  `button[role="tab"]` inside `[role="tablist"]`; clicking one calls
  `setView(id)`.
- Layout phases: the active app column has `[data-phase="active"]`; the CSS var
  `--dsh-sidebar-width` exists. Panel CSS may rely on these (see agent-teams
  panel CSS for the pattern), but do NOT depend on hashed class names of other
  packages.

### 1.4 Platform module table (externals for tsdown)

Verified `require(...)` calls inside official client bundles (rc.6):
`@deepseek-ai/cordis`, `@deepseek-ai/dsh-client-runtime/client`,
`@deepseek-ai/dsh-client-ui-slots`, `@deepseek-ai/dsh-client-ui-primitives`,
`@deepseek-ai/dsh-client-ui-attachment`, `react`, `react/jsx-runtime`,
`react-dom`, `react-dom/client`.

Use these as `external` in tsdown. Do NOT value-import any other cross-plugin
package (purity gate; the browser module table would reject it). Type-only
imports are erased and allowed, e.g.
`import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'` and
`import type {} from '@deepseek-ai/dsh-client-ui-layout/client'` (declaration
merge).

### 1.5 Runtime data (verified)

- `ctx.sessions.list` is an `ObservableSnapshot<SessionListState>`:
  `getSnapshot()` → `{ current: SessionId | undefined, byId, ... }`, `subscribe`.
  (agent-teams passes it into its panel component and subscribes with
  `useSyncExternalStore`.)
- Current session object: `ctx.sessions.binding(sessionId)?.session` → `Session`
  with `subscribe(listener)` (uSES) and `getSnapshot()` →
  `ConversationSnapshot` with:
  - `chat.nodes` — Map-like `ChatNodeStore` (`get(key)`, `values()`)
  - `chat.order` — `readonly string[]` of node keys in flow order
  - `chat.legacy.nodes` — array form
  - `hasMore: boolean`, `loadingOlder: boolean`
  - `running`, `blank`, `openState`, `pending`, `queue`, ...
- `session.loadOlder()` — pages up (returns Promise, guarded by hasMore).
- Chat node shape (from `chatNode()` in ui-conversation):
  `{ key, kind, id, target: 'chat', anchorSeq, location, visibility, data }`.
  - user-message node: `kind: 'user'` (also `'steering'` for mid-turn steers,
    `'context'` for injected context). `data` =
    `{ kind, seq, time (unix ms), content: ContentBlock[], source }` where
    `ContentBlock` is `{ type: 'text', text } | { type: 'image', ... } | ...`.
  - `node.key` = `conversationContextKey(defKind, businessId)` with format
    `<kindLen>:<kind><id>` — e.g. `13:input-message<uuid>` for user messages.
    Use `node.key` verbatim for DOM lookup.
  - `node.location`: `{kind:'turn', turn: TurnLocation} | {kind:'step', turn, step} |
    {kind:'session'} | {kind:'unresolved'}`; turn number =
    `location.kind === 'step' ? location.turn.turn : location.kind === 'turn' ? location.turn.turn : undefined`.
- Locale: `ctx.locale.register(NS, { zh, en })` then `ctx.locale.bind(NS)` → `t(key)`.
- Open a session: `ctx.sessions.open(id)`.

### 1.6 Versions (peerDependencies / devDependencies)

- **peerDependencies: `react` `^18.2.0` ONLY.** The `@deepseek-ai/*` packages are
  deliberately NOT peers (REVISED after the first install report): the registry's
  `latest` tag for the client sub-packages is stale (`0.0.1-rc.1`) while `0.1.0-rc.6`
  lives on `next`, so a `^0.1.0-rc.6` peer makes pnpm fail with
  `ERR_PNPM_NO_MATCHING_VERSION` on a fresh profile. Nothing imports those packages at
  runtime anyway — the browser module loader resolves platform modules from the
  profile's own (channel-matched) installation, and the host half imports nothing.
  `react-dom` is also dropped (unused since the shell.overlay rewrite).
- Typechecking still links the local `@deepseek-ai/*` types via `scripts/link-types.mjs`
  (dev-only symlinks, never shipped — see §1.7).
- devDeps from public npm: `typescript@^5.9.3`, `tsdown@0.22.2`, `lightningcss@^1.33.0`,
  `@types/react@~18.3.1`, `@types/react-dom@^19.2.4`, `react@^18.2.0`,
  `react-dom@^18.2.0` (react needed as devDep for jsx types).
- Node `^22.19.0 || >=24` (engines).

### 1.7 Typecheck strategy (no registry access to @deepseek-ai)

`@deepseek-ai/*` packages are NOT re-installable from the public registry here;
the profile flat dir already has everything. Symlink (do NOT commit):
```sh
mkdir -p node_modules/@deepseek-ai
for p in cordis dsh-client-runtime dsh-client-ui-layout dsh-client-ui-slots dsh-client-ui-primitives dsh-client-locale dsh-client-web-react; do
  ln -sfn /Users/liziqing/.dsh/profiles/node_modules/@deepseek-ai/$p node_modules/@deepseek-ai/$p
done
```
Provide a `scripts/link-types.mjs` that does this (idempotent), and a
`pnpm dev:types` script. `.gitignore` must exclude `node_modules/` so the
symlinks never ship.

Two tsc programs (host and client) — see skill §6.1 / guide §3.1. The client
program compiles `src/client/**` with `lib: ["ES2022","DOM","DOM.Iterable"]`,
`jsx: "react-jsx"`, `types: []`, `allowImportingTsExtensions` +
`rewriteRelativeImportExtensions` (TS 5.7+). Output: host → `lib/`, client →
`lib/client/`. tsdown then bundles `lib/client/index.js` → `lib/client.js`
(with banner/footer wrapper + sourcemap; keep `lib/client/*.js` files — the
verify script imports the pure-logic module from there).

### 1.8 CSS

Keep it simple and HMR-safe: plain CSS string in a `.ts` module, injected in
`apply()` via `ctx.effect` with a `<style data-plugin="dsh-conversation-outline"
data-plugin-css="dsh-conversation-outline/panel.css">` tag (same pattern the
shipped bundles generate; HMR removes owned `style[data-plugin]` tags).
Use stable prefixed class names (`dso_*`) and DSH theme vars (`--dsw-alias-*`,
`--dsw-specific-*`, `--dsh-sidebar-width`) — see agent-teams' injected CSS for
the exact vars. CSS Modules via lightningcss is allowed but optional; the
manual style-tag approach is preferred for lower build risk.

---

## 2. Product spec (the panel)

### 2.1 Surfaces (REVISED — rail + hover panel, no badge)

Per user feedback the top-right capsule badge was replaced: the AgentTeams
plugin already occupies that corner. The outline now lives on the right EDGE.

1. **Rail** (always mounted, `shell.overlay` entry, id
   `dsh-conversation-outline.rail`): a thin fixed strip on the right edge
   (`right: 0`, vertically centered `top: 50%`), one small horizontal bar per
   user question in chronological order top→bottom — a conversation minimap.
   Capped at 60 bars; overflow folds into a top `+N` marker. Bars are real
   `<button>`s with localized `aria-label` (`跳到第 {n} 个问题`); clicking a
   bar jumps. The strip itself is `role="group"` with `aria-label`, focusable
   (focus/Enter opens the panel for keyboard users). Hidden (renders nothing)
   when there is no current session or the session is blank.
2. **Panel** (rendered only while open): fixed right overlay
   (`right: 16px`, vertically centered), `width: min(340px, calc(100vw - 24px))`,
   `max-height: min(70vh, 600px)`, rounded 16px card, internal scroll, backdrop
   blur, DSH theme vars. Sections:
   - Header: title `会话大纲 / Outline` + count + close button (×).
   - Search input (localized placeholder; case-insensitive filter).
   - Question list, **chronological**: one row per user question — `#<turn>`
     badge, **single-line truncated** text preview (the question's opening
     words; longer text ellipsizes), trailing `HH:MM` time, copy button,
     `追问`/`steer` tag for steering messages. Clicking a row = jump (2.2).
   - Footer: `加载更早 / Load older` when `snapshot.hasMore` (disabled while
     `loadingOlder`); calls `session.loadOlder()`.
   - Empty state when no user messages in the loaded window.
3. Behavior rules:
   - **Hover-open**: mouseenter on the rail (or panel) opens the panel;
     mouseleave schedules a collapse after a 240ms grace (canceled on re-enter,
     so the pointer can travel rail→panel). Touch devices: tapping the strip
     (non-bar area) pins/unpins the panel; `Escape` or × closes. The panel is
     a pure OVERLAY — no column yield, no layout shift.
   - Follows `sessions.list.current`; on session change the panel closes and
     pending jump work is canceled (navigate → collapse).
   - While a session is running, new user messages appear live (snapshot
     subscription covers it; the rail grows a bar per question).

### 2.2 Jump-to-message algorithm (core feature)

On row click, given the target `node.key`:

1. Ensure the conversation page is mounted: abort when
   `document.querySelector('[data-conversation-scroll]')` is missing. If a
   conversation-root header tablist exists (found by walking up from
   `scrollport.parentElement` — the scrollport itself may contain other
   tablists such as the trajectory event-details tabs), click its first
   `button[role="tab"]` (chat is `order: 0` — always first; `setView("chat")`
   is idempotent). A profile without extra views has no tablist — fine, the
   rows are already visible.
2. Wait for the target row to render: poll with `requestAnimationFrame` up to
   ~1500ms for `[data-chat-anchor-key="<node.key>"]` inside the chat list. The
   row is guaranteed to be in the loaded window (it comes from the snapshot),
   so this is a render-timing wait.
3. Scroll: `const scrollport = row.closest('[data-conversation-scroll]') ?? document.querySelector('[data-conversation-scroll]')`; compute
   `row.getBoundingClientRect().top - scrollport.getBoundingClientRect().top`
   and set `scrollport.scrollTop += flowTop - 96` (leave ~96px headroom under
   the sticky header/composer area). Use smooth behavior unless
   `prefers-reduced-motion`.
4. Flash highlight: set `row.dataset.dshOutlineFlash = 'true'`; CSS
   `[data-dsh-outline-flash]{ animation: dso-flash 1.8s ease-out }` (a
   background/outline pulse using `--dsw-alias-state-business-primary`);
   remove the attribute after ~1.9s (timeout, cleaned on unmount).
5. Close the panel.

All DOM work must be guarded (elements may be missing) and cleaned up on
dispose (timeouts/RAF cancelled in the effect disposer).

### 2.3 Pure logic module (`src/client/outline.ts`, NO DOM, NO React)

Keep the derivations as importable pure functions so `scripts/verify.mjs` can
test them in Node by importing `lib/client/outline.js`:

- `flattenQuestionText(content: ContentBlock[]): string` — join text blocks,
  image blocks → `[图片]` / `[image]`, trim, collapse whitespace.
- `collectQuestions(snapshot): OutlineItem[]` — walk `snapshot.chat.order`,
  look up `snapshot.chat.nodes.get(key)`, keep `kind === 'user' | 'steering'`,
  skip empty text; item =
  `{ key, kind, seq, time, turn: number | undefined, text }`.
- `filterQuestions(items, query): OutlineItem[]` — case-insensitive substring.
- `formatTime(ms): string` — `HH:MM` local.
- `isJumpTargetRow(row: Element, key: string): boolean` — pure DOM predicate
  (used by the jump loop; testable with a fake object in node).

### 2.4 Localization

Namespace `dsh-conversation-outline`; keys at least: title, count (with
`{count}`), searchPlaceholder, empty, loadOlder, loadingOlder, copy, copied,
steerTag, jumpFailed (console only). zh-CN + en dictionaries, registered via
`ctx.locale.register(NS, { zh, en })`.

---

## 3. Repo layout (create exactly this)

```
dsh-conversation-outline/
├── package.json
├── cordis.patch.yml
├── tsconfig.json            # host program (excludes src/client)
├── tsconfig.client.json     # client program
├── tsdown.config.ts         # client bundle (wrapper banner/footer)
├── .gitignore               # node_modules, lib, *.log, .DS_Store
├── LICENSE                  # MIT (owner placeholder "your name")
├── README.md                # written by docs member
├── docs/
│   ├── implementation-spec.md   # this file
│   └── publishing-guide.md      # written by docs member
├── scripts/
│   ├── link-types.mjs       # symlink @deepseek-ai types (dev-only)
│   └── verify.mjs           # offline smoke: manifest/patch/bundle shape + pure logic
└── src/
    ├── index.ts             # minimal host apply
    ├── event-types.ts       # NOT needed (no custom events) — skip
    └── client/
        ├── index.tsx        # apply(): locale, style tag, shell.overlay registration, badge+panel
        ├── OutlinePanel.tsx # badge + panel components
        ├── outline.ts       # pure logic (2.3)
        ├── locales.ts       # zh/en dictionaries
        └── styles.ts        # CSS string + injectStyle(ctx) helper
```

### 3.1 package.json essentials

```jsonc
{
  "name": "dsh-conversation-outline",
  "version": "0.1.0",
  "type": "module",
  "main": "lib/index.js",
  "types": "lib/types/index.d.ts",
  "exports": {
    ".": { "types": "./lib/types/index.d.ts", "default": "./lib/index.js" },
    "./client": { "types": "./lib/types/client/index.d.ts", "default": "./lib/client.js" },
    "./cordis.patch.yml": "./cordis.patch.yml",
    "./package.json": "./package.json"
  },
  "files": ["lib", "cordis.patch.yml", "README.md", "LICENSE"],
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": { "inject": ["@deepseek-ai/dsh-client-runtime", "@deepseek-ai/dsh-client-ui-layout"], "platform": "web" }
  },
  "scripts": {
    "build": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && tsdown",
    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
    "verify": "node scripts/verify.mjs",
    "dev:types": "node scripts/link-types.mjs"
  },
  "peerDependencies": {
    "@deepseek-ai/cordis": "^4.0.1",
    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
    "@deepseek-ai/dsh-client-ui-layout": "^0.1.0-rc.6",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@types/react": "~18.3.1",
    "@types/react-dom": "^19.2.4",
    "lightningcss": "^1.33.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "tsdown": "0.22.2",
    "typescript": "^5.9.3"
  },
  "engines": { "node": "^22.19.0 || >=24" },
  "license": "MIT",
  "keywords": ["dsh", "dsh-plugin", "deepseek-harness", "conversation", "outline", "navigation"],
  "repository": { "type": "git", "url": "git+https://github.com/<owner>/dsh-conversation-outline.git" }
}
```

### 3.2 cordis.patch.yml

```yaml
- insert:
    - id: dsh-conversation-outline
      name: dsh-conversation-outline
      config: {}
```

### 3.3 tsdown.config.ts

Entry `{ client: 'lib/client/index.js' }`, outDir `lib`, `format: 'cjs'`,
`platform: 'browser'`, `dts: false`, `sourcemap: true`, `clean: false`,
`external` = the platform table (1.4), `define` NODE_ENV production,
`outputOptions`: `entryFileNames: 'client.js'`, `banner: 'window.__ModuleLoader__.load({ id: "dsh-conversation-outline", factory: (require) => {'`,
`footer: 'return module.exports; } });'`,
`intro: 'var module = { exports: {} }; var exports = module.exports;'`.
No CSS-modules plugin needed (manual style tag); keep a simple purity guard
plugin that throws on value-imports of `@deepseek-ai/*` packages outside the
external table.

---

## 4. Verification plan

### 4.1 Offline (engineer, then researcher re-runs)

1. `pnpm dev:types` (symlink), `pnpm install`, `pnpm typecheck`, `pnpm build`.
2. `node scripts/verify.mjs`:
   - manifest/exports/files consistency (every exported path exists);
   - `cordis.patch.yml` parses, first insert id/name match package name;
   - `lib/client.js` starts with the `window.__ModuleLoader__.load` wrapper;
   - no absolute machine paths inside `lib/` (grep `/Users/`);
   - pure-logic assertions from `lib/client/outline.js`: flatten text incl.
     image blocks, collect/filter/sort questions from a fixture snapshot,
     formatTime, turn extraction.

### 4.2 Integration (researcher)

Use a SCRATCH profile + temporary `DSH_HOME` + different port — NEVER touch the
running instance (the user's GUI at 127.0.0.1:3080 serves the current session;
restarting it would kill the session. Also do not start a replacement server on
3080).

1. `pnpm build` in the repo.
2. `tmp=$(mktemp -d)`; `DSH_HOME=$tmp npx -p @deepseek-ai/dsh dsh plugin --profile scratch add /Users/liziqing/Programs/agents/dsh-conversation-outline`
   (network: npm registry reachable for the dsh CLI; if the npx download fails,
   fall back to the already-installed CLI:
   `DSH_HOME=$tmp node /Users/liziqing/.npm/_npx/1e7f6d9597241db0/node_modules/@deepseek-ai/dsh/lib/bin.js plugin --profile scratch add <path>`).
3. `DSH_HOME=$tmp <dsh> --profile scratch --dump-config` — assert the
   `dsh-conversation-outline` row appears with id/name/config.
4. Boot the scratch web instance on a free port (e.g. 3199) in the background:
   `DSH_HOME=$tmp <dsh> --profile scratch --port 3199` (check `--help` flags if
   needed), then `curl http://127.0.0.1:3199/` and assert
   `window.__DSH_BOOT__` contains an entry
   `{"id":"dsh-conversation-outline","url":"/plugins/dsh-conversation-outline/client.js"...}`,
   and `curl http://127.0.0.1:3199/plugins/dsh-conversation-outline/client.js`
   returns 200 with the loader wrapper. Kill the instance afterwards.
5. Report exact commands + outputs in the task output.

### 4.3 Review (reviewer)

Check against the skill checklist (§9 完成标准): minimal surface; manifest/
exports/patch/products consistent; inject boundaries; effect ownership
(dispose of root/DOM/style/listeners/timeouts/RAF); purity of client imports;
no host/client type pollution (two programs); a11y (aria, focus-visible,
Escape, reduced motion); the jump algorithm's failure modes (missing row,
missing tablist, session switched mid-jump, blank session); live updates;
load-older; i18n coverage. Mark findings as must-fix / nice-to-have and hand
back to the engineer for fixes.

### 4.4 Final (captain)

Install into the user's real web profile (`dsh plugin --profile web add <path>`)
— this only edits profile files; the plugin takes effect after the user
restarts their GUI (document this). Keep the scratch instance killed and temp
dirs cleaned.

---

## 5. Order of work

1. engineer: scaffold (3.x) → implement (2.x) → build green (4.1).
2. researcher: 4.2 integration.
3. reviewer: 4.3; engineer fixes must-fix findings.
4. docs: README (install via `dsh plugin --profile web add <pkg|github:...>`,
   usage, dev loop with HMR: `tsdown --watch` + `pnpm run dev:web` note,
   screenshots placeholder) + `docs/publishing-guide.md` (GitHub publish:
   create repo, license choice — MIT recommended, .gitignore, README, release
   workflow: npm publish with `prepublishOnly: pnpm build && pnpm verify`,
   GitHub-only install without npm, versioning, CHANGELOG, issues/PR templates,
   publishing scoped vs unscoped, npm name collision fallback to a scope).
5. captain: final assembly, install into web profile, wrap-up report.