dsh-synapse 0.4.0

package/client.js

@@ -0,0 +1,217 @@
+window.__ModuleLoader__.load({
+  id: 'dsh-synapse',
+  factory: () => {
+    const module = { exports: {} }
+    const currentSession = ctx => {
+      const snapshot = ctx.sessions.list.getSnapshot()
+      const id = snapshot.current
+      if (id === undefined) return null
+      const session = snapshot.byId[id]
+      return session === undefined ? null : { id, title: session.displayTitle, cwd: session.cwd ?? null }
+    }
+    const sessionSnapshot = ctx => {
+      const snapshot = ctx.sessions.list.getSnapshot()
+      return snapshot.ids.map(id => {
+        const session = snapshot.byId[id]
+        return session === undefined ? null : { id, title: session.displayTitle, cwd: session.cwd ?? null, parentId: session.parentId ?? null, blank: session.blank }
+      }).filter(Boolean)
+    }
+    const workspaceSnapshot = ctx => {
+      const sessions = ctx.sessions.list.getSnapshot()
+      const snapshot = ctx.workspaces.list.getSnapshot()
+      const accounted = new Set(snapshot.items.flatMap(workspace => workspace.sessionIds))
+      return [
+        ...snapshot.items.map(workspace => ({ id: workspace.workspaceId, title: workspace.title, path: workspace.path, sessionIds: workspace.sessionIds })),
+        { id: 'dsh-ungrouped', title: '未分组', path: null, sessionIds: sessions.ids.filter(id => !accounted.has(id)) },
+      ]
+    }
+
+    module.exports.inject = ['sessions', 'workspaces']
+    module.exports.apply = ctx => {
+      const prompt = async (sessionId, text) => {
+        const scope = ctx.sessions.scope(sessionId)
+        const session = scope === undefined ? undefined : ctx.sessions.sessionOf(scope)
+        if (session === undefined) throw new Error('关联的 DSH 会话已不可用')
+        const result = await session.prompt([{ type: 'text', text }], 'queue')
+        if (!result.ok) throw new Error(result.error?.message ?? 'DSH 未接受这条消息')
+      }
+      const style = document.createElement('style')
+      style.textContent = '.dsh-synapse-switch{position:fixed;z-index:80;top:12px;left:50%;display:flex;gap:2px;transform:translateX(-50%);border:1px solid #d1d5db;border-radius:999px;background:rgba(255,255,255,.96);padding:3px;backdrop-filter:blur(10px)}.dsh-synapse-switch button{height:28px;border:0;border-radius:999px;background:transparent;padding:0 11px;color:#6b7280;font:600 12px Inter,system-ui,sans-serif;cursor:pointer;white-space:nowrap}.dsh-synapse-switch button:hover{background:#f3f4f6;color:#111827}.dsh-synapse-switch button.active{background:#111827;color:#fff}.dsh-synapse-switch button:focus-visible{outline:2px solid #111827;outline-offset:2px}.dsh-synapse-overlay{position:fixed;z-index:100;inset:0;background:#f5f7fa}.dsh-synapse-overlay.is-opening{visibility:hidden}.dsh-synapse-overlay[hidden]{display:none}.dsh-synapse-overlay iframe{display:block;width:100%;height:100%;border:0}'
+      document.head.append(style)
+      const host = document.createElement('div')
+      host.className = 'dsh-synapse-host'
+      host.innerHTML = '<div class="dsh-synapse-switch" role="group" aria-label="视图切换"><button type="button" data-view="dialog" class="active" aria-pressed="true">对话</button><button type="button" data-view="map" aria-pressed="false">会话地图</button></div><section class="dsh-synapse-overlay" hidden><iframe title="会话地图" src="/synapse/"></iframe></section>'
+      document.body.append(host)
+      const dialogButton = host.querySelector('[data-view="dialog"]')
+      const mapButton = host.querySelector('[data-view="map"]')
+      const overlay = host.querySelector('.dsh-synapse-overlay')
+      const frame = host.querySelector('iframe')
+
+      const setView = view => {
+        const showingMap = view === 'map'
+        dialogButton.classList.toggle('active', !showingMap)
+        dialogButton.setAttribute('aria-pressed', String(!showingMap))
+        mapButton.classList.toggle('active', showingMap)
+        mapButton.setAttribute('aria-pressed', String(showingMap))
+      }
+      const close = () => {
+        window.clearTimeout(mapOpenFallback)
+        mapOpening = false
+        overlay.classList.remove('is-opening')
+        overlay.hidden = true
+        setView('dialog')
+      }
+      const send = (type, payload) => { frame.contentWindow?.postMessage({ source: 'dsh-synapse', type, ...payload }, location.origin) }
+      let syncQueued = false
+      let knownSessionIds = new Set()
+      const liveUnsubscribers = new Map()
+      const syncLiveSessions = () => {
+        const snapshot = ctx.sessions.list.getSnapshot()
+        for (const id of snapshot.ids) {
+          if (liveUnsubscribers.has(id)) continue
+          const scope = ctx.sessions.scope(id)
+          const session = scope === undefined ? undefined : ctx.sessions.sessionOf(scope)
+          if (session === undefined) continue
+          const publish = () => {
+            if (overlay.hidden) return
+            const state = session.getSnapshot()
+            const text = state.partial?.blocks.filter(block => block.kind === 'text').map(block => block.text).join('\n') ?? ''
+            send('synapse:live-reply', { sessionId: id, running: state.running, text })
+          }
+          liveUnsubscribers.set(id, session.subscribe(publish))
+          publish()
+        }
+        for (const [id, unsubscribe] of liveUnsubscribers) if (!snapshot.ids.includes(id)) { unsubscribe(); liveUnsubscribers.delete(id) }
+      }
+      const syncSessions = () => {
+        if (syncQueued) return
+        syncQueued = true
+        queueMicrotask(() => {
+          syncQueued = false
+          const sessions = sessionSnapshot(ctx)
+          const sessionIds = new Set(sessions.map(session => session.id))
+          const removedSessionIds = [...knownSessionIds].filter(id => !sessionIds.has(id))
+          knownSessionIds = sessionIds
+          void fetch('/synapse/api/sessions/sync', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ sessions, removedSessionIds }) }).catch(() => {})
+        })
+      }
+      const syncTheme = () => {
+        const dark = document.body?.hasAttribute?.('data-ds-dark-theme') === true
+        send('synapse:theme', { dark })
+      }
+      const syncCurrentSession = () => {
+        syncSessions()
+        syncLiveSessions()
+        syncTheme()
+        if (!overlay.hidden) {
+          send('synapse:workspaces', { workspaces: workspaceSnapshot(ctx) })
+          send('synapse:current-session', { session: currentSession(ctx) })
+        }
+      }
+      let mapOpenFallback = 0
+      let mapOpening = false
+      const showMapOverlay = () => {
+        window.clearTimeout(mapOpenFallback)
+        mapOpening = false
+        overlay.hidden = false
+        overlay.classList.remove('is-opening')
+        syncCurrentSession()
+      }
+      const open = () => {
+        window.clearTimeout(mapOpenFallback)
+        mapOpening = true
+        setView('map')
+        // Keep the iframe laid out while hidden so its canvas can receive a
+        // real scroll offset. display:none would clamp scrollTop back to zero.
+        overlay.hidden = false
+        overlay.classList.add('is-opening')
+        window.requestAnimationFrame(() => {
+          send('synapse:map-opened')
+          syncCurrentSession()
+        })
+        mapOpenFallback = window.setTimeout(showMapOverlay, 300)
+      }
+      const onFrameLoad = () => {
+        syncCurrentSession()
+        if (mapOpening) send('synapse:map-opened')
+      }
+      const onMessage = event => {
+        if (event.origin !== location.origin || event.data?.source !== 'dsh-synapse') return
+        if (event.data.type === 'synapse:close') return close()
+        if (event.data.type === 'synapse:map-ready') return showMapOverlay()
+        if (event.data.type === 'synapse:request-current') {
+          send('synapse:workspaces', { workspaces: workspaceSnapshot(ctx) })
+          return send('synapse:current-session', { session: currentSession(ctx) })
+        }
+        if (event.data.type === 'synapse:open-session') {
+          try { ctx.sessions.open(event.data.sessionId); close() } catch { send('synapse:bridge-error', { message: '关联的 DSH 会话已不可用' }) }
+          return
+        }
+        if (event.data.type === 'synapse:activate-session') {
+          // Bidirectional current-session sync: switch DSH's current session
+          // without closing the map; the sessions-list subscription re-sends
+          // synapse:current-session so the map follows the new highlight.
+          try { ctx.sessions.open(event.data.sessionId) } catch { send('synapse:bridge-error', { message: '关联的 DSH 会话已不可用' }) }
+          return
+        }
+        if (event.data.type === 'synapse:fork-session') {
+          const atSeq = Number.isInteger(event.data.atSeq) ? event.data.atSeq : undefined
+          ctx.sessions.fork({ sessionId: event.data.sessionId, atSeq, increaseTitle: true }).then(id => {
+            const snapshot = ctx.sessions.list.getSnapshot()
+            send('synapse:forked-session', { requestId: event.data.requestId, session: { id, title: snapshot.byId[id]?.displayTitle ?? 'DSH 分支' } })
+          }).catch(() => { send('synapse:bridge-error', { message: 'DSH 分支创建失败，请确认源会话已经完成当前轮次' }) })
+          return
+        }
+        if (event.data.type === 'synapse:send-message') {
+          const text = typeof event.data.text === 'string' ? event.data.text.trim() : ''
+          if (text === '') return send('synapse:bridge-error', { requestId: event.data.requestId, message: '消息不能为空' })
+          prompt(event.data.sessionId, text).then(() => {
+            send('synapse:message-sent', { requestId: event.data.requestId, sessionId: event.data.sessionId })
+          }).catch(error => {
+            send('synapse:bridge-error', { requestId: event.data.requestId, message: error instanceof Error ? error.message : 'DSH 消息发送失败' })
+          })
+          return
+        }
+        if (event.data.type === 'synapse:create-session') {
+          const workspaceId = typeof event.data.workspaceId === 'string' && event.data.workspaceId !== '' && event.data.workspaceId !== 'dsh-ungrouped' ? event.data.workspaceId : undefined
+          const cwd = typeof event.data.cwd === 'string' && event.data.cwd !== '' ? event.data.cwd : undefined
+          const create = workspaceId === undefined ? ctx.sessions.create(cwd === undefined ? {} : { cwd }) : ctx.sessions.create({ workspaceId })
+          create.then(id => {
+            const snapshot = ctx.sessions.list.getSnapshot()
+            send('synapse:created-session', { requestId: event.data.requestId, session: { id, title: snapshot.byId[id]?.displayTitle ?? '新会话', cwd: snapshot.byId[id]?.cwd ?? cwd ?? null } })
+          }).catch(() => { send('synapse:bridge-error', { requestId: event.data.requestId, message: 'DSH 会话创建失败，请先在 DSH 选择工作目录' }) })
+        }
+      }
+      const onKeyDown = event => { if (event.key === 'Escape' && !overlay.hidden) close() }
+      // Follow DSH's live theme switch: body[data-ds-dark-theme] is the web
+      // client's dark-mode signal, mirrored into the map iframe via synapse:theme.
+      const themeObserver = typeof MutationObserver === 'undefined'
+        ? null
+        : new MutationObserver(() => syncTheme())
+      if (themeObserver !== null && document.body) {
+        themeObserver.observe(document.body, { attributes: true, attributeFilter: ['data-ds-dark-theme'] })
+      }
+      const unsubscribeSessions = ctx.sessions.list.subscribe(syncCurrentSession)
+      const unsubscribeWorkspaces = ctx.workspaces.list.subscribe(syncCurrentSession)
+      dialogButton.addEventListener('click', close)
+      mapButton.addEventListener('click', open)
+      frame.addEventListener('load', onFrameLoad)
+      window.addEventListener('message', onMessage)
+      window.addEventListener('keydown', onKeyDown)
+      ctx.effect(() => () => {
+        dialogButton.removeEventListener('click', close)
+        mapButton.removeEventListener('click', open)
+        frame.removeEventListener('load', onFrameLoad)
+        window.removeEventListener('message', onMessage)
+        window.removeEventListener('keydown', onKeyDown)
+        themeObserver?.disconnect()
+        unsubscribeSessions()
+        unsubscribeWorkspaces()
+        for (const unsubscribe of liveUnsubscribers.values()) unsubscribe()
+        host.remove()
+        style.remove()
+      }, 'synapse: web workspace switch')
+    }
+    return module.exports
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# dsh-synapse only extends the Web profile: it reuses the existing DSH server
+# rather than running a second application process.
+- insert:
+    - id: synapse
+      name: dsh-synapse
+      config:
+        # A profile can override this path in its own cordis.patch.yml.
+        dataFile: !!js dshHomePath('synapse/workspaces.json')
+        autoProjection: true
+        projectionWorkspaceTitle: DSH 任务
+        # Extra authorities the /synapse Host check accepts (host or host:port);
+        # localhost and 127.0.0.1 are always allowed.
+        trustedHosts: []

package/deepseek-mark.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+  <path fill="currentColor" d="M23.0584 4.95203C22.8129 4.83203 22.7074 5.06103 22.5639 5.17704C22.5149 5.21454 22.4734 5.26354 22.4319 5.30854C22.0734 5.69155 21.6543 5.94306 21.1073 5.91306C20.3073 5.86806 19.6243 6.11957 19.0203 6.73158C18.8918 5.97706 18.4652 5.52655 17.8162 5.23754C17.4767 5.08753 17.1332 4.93703 16.8952 4.61052C16.7292 4.37801 16.6837 4.11901 16.6007 3.8635C16.5477 3.70949 16.4952 3.55199 16.3177 3.52549C16.1252 3.49549 16.0497 3.65699 15.9742 3.792C15.6722 4.34401 15.5552 4.95203 15.5667 5.56805C15.5932 6.95359 16.1782 8.05712 17.3407 8.84215C17.4727 8.93215 17.5067 9.02215 17.4652 9.15366C17.3857 9.42416 17.2917 9.68667 17.2087 9.95718C17.1557 10.1297 17.0767 10.1677 16.8917 10.0922C16.2537 9.82568 15.7027 9.43117 15.2156 8.95465C14.3891 8.15513 13.6416 7.2726 12.7096 6.58158C12.4906 6.42007 12.2716 6.27007 12.045 6.12707C11.094 5.20354 12.1696 4.44502 12.4186 4.35501C12.6791 4.26101 12.5091 3.938 11.6675 3.942C10.826 3.9455 10.056 4.22751 9.07446 4.60302C8.93096 4.65952 8.77995 4.70052 8.62545 4.73452C7.73492 4.56552 6.80989 4.52802 5.84386 4.63702C4.02481 4.83953 2.57177 5.69955 1.50373 7.1676C0.220694 8.93215 -0.0813148 10.9372 0.288196 13.0283C0.676708 15.2323 1.80174 17.0569 3.53029 18.4834C5.32285 19.9625 7.38741 20.6875 9.74298 20.5485C11.1735 20.466 12.7661 20.2745 14.5626 18.7539C15.0156 18.9795 15.4912 19.0695 16.2797 19.137C16.8872 19.1935 17.4722 19.107 17.9252 19.013C18.6347 18.8629 18.5857 18.2059 18.3292 18.0854C16.2497 17.1169 16.7062 17.5109 16.2912 17.1919C17.3477 15.9419 18.9618 13.7198 19.4598 10.6942C19.5088 10.3602 19.5713 9.88968 19.5638 9.61917C19.5598 9.45417 19.5978 9.39016 19.7863 9.37116C20.3073 9.31116 20.8128 9.16866 21.2773 8.91315C22.6249 8.17713 23.1684 6.96809 23.2964 5.51905C23.3154 5.29754 23.2924 5.06853 23.0584 4.95203ZM11.3165 17.9954C9.30097 16.4109 8.32344 15.8894 7.91992 15.9119C7.54241 15.9344 7.61042 16.3664 7.69342 16.6479C7.78042 16.9259 7.89342 17.1174 8.05193 17.3614C8.16143 17.5229 8.23694 17.7629 7.94243 17.9434C7.29341 18.3449 6.16487 17.8084 6.11187 17.7819C4.79833 17.0084 3.7003 15.9874 2.92628 14.5908C2.17875 13.2468 1.74474 11.8047 1.67324 10.2657C1.65424 9.89418 1.76374 9.76267 2.13375 9.69517C2.62077 9.60517 3.12278 9.58617 3.6093 9.65767C5.66636 9.95818 7.41741 10.8777 8.88545 12.3348C9.72348 13.1643 10.3575 14.1558 11.0105 15.1243C11.705 16.1529 12.4521 17.1329 13.4036 17.9364C13.7396 18.2179 14.0076 18.4319 14.2641 18.5899C13.4906 18.6764 12.1996 18.6949 11.3165 17.9964V17.9954ZM12.2826 11.7817C12.2826 11.6167 12.4146 11.4852 12.5806 11.4852C12.6181 11.4852 12.6521 11.4927 12.6826 11.5037C12.7241 11.5187 12.7621 11.5412 12.7921 11.5752C12.8451 11.6277 12.8751 11.7027 12.8751 11.7817C12.8751 11.9467 12.7431 12.0782 12.5771 12.0782C12.4111 12.0782 12.2826 11.9467 12.2826 11.7817ZM15.2831 13.3208C15.0906 13.3998 14.8981 13.4673 14.7131 13.4748C14.4261 13.4898 14.1131 13.3733 13.9431 13.2308C13.6791 13.0093 13.4901 12.8853 13.4111 12.4988C13.3771 12.3338 13.3961 12.0782 13.4261 11.9317C13.4941 11.6162 13.4186 11.4137 13.1961 11.2297C13.0151 11.0797 12.7846 11.0382 12.5316 11.0382C12.4371 11.0382 12.3506 10.9967 12.2861 10.9632C12.1806 10.9107 12.0936 10.7792 12.1766 10.6177C12.2031 10.5652 12.3316 10.4377 12.3616 10.4152C12.7051 10.2197 13.1011 10.2837 13.4676 10.4302C13.8071 10.5692 14.0641 10.8242 14.4336 11.1847C14.8111 11.6202 14.8791 11.7402 15.0941 12.0672C15.2641 12.3228 15.4186 12.5853 15.5247 12.8858C15.5887 13.0733 15.5057 13.2268 15.2831 13.3208Z"/>
+</svg>

package/docs/architecture.md

@@ -0,0 +1,104 @@
+# Architecture and runtime boundaries
+
+## Purpose
+
+`dsh-synapse` is a presentation and organization layer for DeepSeek Harness conversations. It turns existing DSH sessions, turns, and forks into a visual map without replacing the systems that own those conversations.
+
+## Web profile integration
+
+The package contributes `cordis.patch.yml`, which inserts the `dsh-synapse` service into the DSH `web` profile. It reuses the existing DSH Web server and client runtime.
+
+The plugin:
+
+- does not start a second HTTP server;
+- does not create a second model or agent runtime;
+- does not replace DSH authentication or permission checks;
+- does not support non-Web profiles unless those profiles explicitly add the plugin.
+
+## Conversation ownership
+
+DSH session logs remain the source of truth for conversation content and lifecycle. Native DSH operations own:
+
+- creating and opening sessions;
+- sending follow-up messages;
+- forking sessions;
+- archiving sessions;
+- model and tool execution;
+- permission and approval decisions.
+
+Synapse projects committed DSH events into cards and sends user actions back through the native DSH session bridge.
+
+## Canvas metadata
+
+By default, Synapse stores canvas metadata at:
+
+```text
+$DSH_HOME/synapse/workspaces.json
+```
+
+The file contains organizational state such as workspace mapping, card layout, and fork anchors. It does not replace session logs.
+
+Consequences:
+
+- deleting the file resets canvas organization but does not delete conversations;
+- uninstalling the plugin keeps the file, so reinstalling restores the canvas;
+- older schema versions migrate when loaded;
+- two processes sharing the same file can still produce last-writer-wins replacement despite locking and external-change warnings.
+
+Run one `dsh web` instance for each shared profile.
+
+## Projection model
+
+With `autoProjection` enabled, committed DSH session events are grouped by working directory and projected into the corresponding Synapse workspace.
+
+Each user question becomes a conversation card. The following assistant messages are folded into that turn, and the final assistant reply is shown as the answer. Forked sessions connect to the parent turn at the durable DSH seed boundary rather than at an arbitrary canvas coordinate.
+
+Projected card text is capped at 8000 characters. Longer messages receive a truncation marker in the card, while their complete content remains available from the conversation detail view.
+
+Projection writes are coalesced during event bursts, and live updates reuse cached Markdown and patch the active card instead of rebuilding the complete canvas. Card coordinates remain visual metadata only and never determine conversation lineage.
+
+## Tool process folding
+
+Live events pair tool calls and results by `callId` and render them inside the related assistant reply instead of as standalone conversation cards.
+
+Legacy v3 migrations did not always have durable call IDs. Those records pair each tool call with the next tool result by order during migration.
+
+## Browser-local state
+
+Some interaction state, such as dragged card positions and branch anchors, may be cached in browser local storage to keep the canvas responsive. Durable workspace metadata is still written through the Synapse service.
+
+Private-browsing restrictions or local-storage failures must not prevent DSH conversations from operating; they only reduce persistence of visual preferences.
+
+## Host validation
+
+The `/synapse` endpoint always accepts `localhost` and `127.0.0.1`. Additional LAN or proxy authorities must be listed in `trustedHosts` as a host or `host:port` value.
+
+This validation is part of the Web surface and does not replace broader network access controls.
+
+## Model and KV-cache impact
+
+Synapse reads session events only after DSH commits them. It does not add or modify:
+
+- system prompts;
+- user request content;
+- model request headers;
+- tool schemas or registries;
+- provider routing;
+- approval context.
+
+As a result, the plugin has no direct model-experience effect and does not invalidate an otherwise reusable KV-cache prefix.
+
+## Operational limitations
+
+- Only the `web` profile is supported by the bundled patch.
+- Canvas metadata and session content have different owners and backup requirements.
+- A single shared metadata file is not a multi-writer database.
+- Browser state can be cleared independently from DSH Home data.
+- Historical migrations may have less precise tool-call pairing than live projection.
+
+## Related documentation
+
+- [Chinese user guide](zh-CN/README.md)
+- [English user guide](en/README.md)
+- [Development and release guide](development.md)
+- [Project overview](../README.md)

package/docs/development.md

@@ -0,0 +1,137 @@
+# Development and release guide
+
+This document covers local validation, package inspection, GitHub Actions, and npm release automation for maintainers.
+
+## Requirements
+
+- Node.js `>= 22.19.0`
+- pnpm through Corepack
+- A checkout of this repository
+
+## Local workflow
+
+Install with the lockfile:
+
+```powershell
+corepack pnpm install --frozen-lockfile
+```
+
+Validate JavaScript syntax:
+
+```powershell
+corepack pnpm run build
+```
+
+Run the full test suite:
+
+```powershell
+corepack pnpm test
+```
+
+Inspect the package archive:
+
+```powershell
+corepack pnpm pack
+npm pack --dry-run --json
+```
+
+The package has no generated build output. `build` runs `node --check` over `index.js`, `client.js`, and `app.js`.
+
+## GitHub Actions
+
+Three workflows live under `.github/workflows/`.
+
+### Pull request tests
+
+`pr-tests.yml` runs for pull requests targeting `main` when they are opened, reopened, updated, or marked ready for review.
+
+The workflow:
+
+1. Checks out the pull request revision.
+2. Installs pnpm 10 and Node.js 22.19.0.
+3. Runs `pnpm install --frozen-lockfile`.
+4. Runs `pnpm run build`.
+5. Runs `pnpm test`.
+
+A per-PR concurrency group cancels obsolete runs after a newer commit arrives.
+
+### Main branch tests
+
+`main-tests.yml` runs for every push to `main`, including direct commits and merged pull requests. It executes the same frozen installation, build validation, and full test suite.
+
+### npm publishing
+
+`npm-publish.yml` runs for pushed tags matching the broad GitHub pattern `v*.*.*`. The job then validates the tag strictly before publishing.
+
+Accepted forms include:
+
+```text
+v0.4.0
+v0.4.0-rc1
+v0.4.0-rc.2
+```
+
+The tag without the leading `v` must exactly equal `package.json.version`. A mismatch fails before installation or publication.
+
+| Version | Git tag | npm dist-tag |
+|---|---|---|
+| `0.4.0-rc1` | `v0.4.0-rc1` | `next` |
+| `0.4.0` | `v0.4.0` | `latest` |
+
+Every release tag reruns installation, build validation, and the complete test suite before calling `pnpm publish`.
+
+## Configure npm authentication
+
+Create a GitHub Actions repository secret named `NPM_TOKEN` in the repository where the tag workflow will run:
+
+```powershell
+gh secret set NPM_TOKEN --repo OWNER/dsh-synapse
+```
+
+The token's npm account must have permission to create or publish the public, unscoped `dsh-synapse` package. The workflow passes the secret to the publish step as `NODE_AUTH_TOKEN`; pull request and ordinary test workflows never receive it.
+
+## Release checklist
+
+1. Confirm the full test suite passes on `main`.
+2. Update `package.json.version` to the intended release version.
+3. Commit and merge the version change.
+4. Create a matching tag on that commit.
+5. Push the tag.
+6. Confirm the **Publish to npm** workflow passes.
+7. Verify the npm dist-tag:
+   - prerelease versions use `next`
+   - stable versions use `latest`
+
+Example stable release:
+
+```powershell
+# package.json already contains 0.4.0
+git tag v0.4.0
+git push origin v0.4.0
+```
+
+Example prerelease:
+
+```powershell
+# package.json already contains 0.4.0-rc1
+git tag v0.4.0-rc1
+git push origin v0.4.0-rc1
+```
+
+## Publication failure conditions
+
+The publish job stops without publishing when:
+
+- the tag is not a supported version form;
+- the tag and `package.json.version` differ;
+- frozen installation fails;
+- syntax validation or tests fail;
+- `NPM_TOKEN` is missing, expired, or lacks package permissions;
+- npm rejects the package name or an already-published version.
+
+## Documentation
+
+- [Chinese user guide](zh-CN/README.md)
+- [English user guide](en/README.md)
+- [Architecture and runtime boundaries](architecture.md)
+- [Project overview](../README.md)

package/docs/en/README.md

@@ -0,0 +1,161 @@
+# dsh-synapse English Guide
+
+`dsh-synapse` is a Web plugin for DeepSeek Harness (DSH). It adds a session map to the native conversation interface and organizes sessions, follow-ups, and forks from the same workspace as a browsable, draggable, and zoomable canvas.
+
+The plugin does not replace DSH models, tools, sessions, permissions, or the Web server. DSH remains responsible for every conversation operation.
+
+## Prerequisites
+
+- A DeepSeek Harness release with the `dsh plugin` profile mechanism (2026-08 or later).
+- Node.js `>= 22.19.0`.
+- The `web` profile; other profiles are not currently supported.
+
+## Installation
+
+### Install from npm
+
+```powershell
+corepack pnpm dsh plugin --profile web add dsh-synapse
+```
+
+The npm package ships prebuilt code, so no build-script permission is needed — the simplest install. GitHub and local-checkout routes below are alternatives.
+
+### Install from GitHub
+
+```powershell
+corepack pnpm dsh plugin --profile web add github:liangmianya/dsh-synapse
+```
+
+GitHub installs run the package `prepare` script, which validates JavaScript syntax with `node --check`.
+
+### pnpm 10+ allowBuilds
+
+pnpm 10 and later may block build scripts for Git dependencies by default. If installation is blocked, copy the **complete key printed by pnpm** into the DSH Web profile's `pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  "dsh-synapse@https://codeload.github.com/liangmianya/dsh-synapse/tar.gz/<commit>": true
+```
+
+Use the complete key containing the tarball URL and commit, not the bare package name `dsh-synapse`. The key changes when the upstream commit changes, so use the newly printed value when upgrading.
+
+### Install a local checkout
+
+```powershell
+corepack pnpm dsh plugin --profile web add link:E:\path\to\dsh-synapse
+```
+
+The `link:` form references the local checkout directly and is recommended for development. In a normal run, restart `dsh web` and refresh the page after editing the plugin.
+
+## Start DSH Web
+
+```powershell
+corepack pnpm dsh web
+```
+
+Default address:
+
+```text
+http://127.0.0.1:3080/
+```
+
+Let DSH choose a free port when 3080 is occupied:
+
+```powershell
+corepack pnpm dsh web --port 0
+```
+
+Open the top **Session Map** switch after startup. Do not run two `dsh web` processes that share the same profile.
+
+## Usage
+
+1. Select a working directory in DSH or open an existing session.
+2. Send at least one message so the session enters workspace history.
+3. Open **Session Map** from the top switch.
+4. Click a card or sidebar session to synchronize the current session between the map and native chat.
+5. Use **Branch** on a completed answer to preserve an alternative path.
+6. Open **Details** from a card to inspect the complete conversation.
+7. Use **Open in DSH** or the top **Dialogue** switch to return to native chat.
+
+The canvas supports:
+
+- Panning and zooming up to 4×.
+- Dragging cards with persisted positions.
+- Expanding or collapsing descendant conversation subtrees.
+- One-click focus on the current session.
+- Smooth card scrolling and Markdown table rendering.
+- Folding tool calls and results into the related assistant answer by `callId`.
+
+## Configuration
+
+The plugin is inserted through the profile's `cordis.patch.yml`. Override it in your own patch by targeting the row id `synapse`.
+
+> A DSH patch replaces the row's complete `config`, so restate every value that must remain active.
+
+| Key | Default | Description |
+|---|---|---|
+| `dataFile` | `$DSH_HOME/synapse/workspaces.json` | Canvas metadata persistence file |
+| `autoProjection` | `true` | Automatically project committed DSH session events into cards |
+| `projectionWorkspaceTitle` | `DSH 任务` | Title of the automatically projected workspace |
+| `trustedHosts` | `[]` | Extra host or `host:port` values accepted by the `/synapse` Host check; `localhost` and `127.0.0.1` are always accepted |
+
+Example:
+
+```yaml
+- id: synapse
+  config:
+    dataFile: !!js dshHomePath('synapse/my-workspaces.json')
+    autoProjection: true
+    projectionWorkspaceTitle: My tasks
+    trustedHosts: []
+```
+
+Add the actual host to `trustedHosts` when exposing DSH on a LAN.
+
+## Uninstall and data cleanup
+
+Remove the plugin:
+
+```powershell
+corepack pnpm dsh plugin --profile web remove dsh-synapse
+```
+
+`remove` deletes the dependency and profile activation layer but keeps canvas data. Reinstalling reuses and migrates the old data when necessary.
+
+For a complete cleanup, manually remove:
+
+```text
+$DSH_HOME/synapse/
+```
+
+A leftover `allowBuilds` key in `pnpm-workspace.yaml` is harmless and may also be removed.
+
+## Data and runtime boundaries
+
+- DSH session logs own the actual conversation content.
+- Synapse `workspaces.json` stores only canvas metadata, layout, and branch anchors.
+- Deleting `workspaces.json` loses canvas layout, never DSH sessions.
+- Projected message text is capped at 8000 characters; longer card text ends with “—…（详情查看全文）”, while the full content remains available in conversation details.
+- The plugin starts no second Web server and creates no second agent system.
+
+See [Architecture and runtime boundaries](../architecture.md) for details.
+
+## Model Experience
+
+None, as dsh-synapse only reads committed session events and renders them; it adds no system-prompt prose, tool schemas, or request-context content to any model request.
+
+### KV Cache effect
+
+Does not invalidate. The plugin never changes request headers, system prompts, or tool registries, so an already-reusable KV prefix stays reusable; canvas projection consumes session logs only after they are committed.
+
+## Known limitations
+
+- Only the `web` profile is supported.
+- Two DSH Web instances sharing one profile write the same `workspaces.json`. A cross-process write lock and external-modification warnings exist, but last-writer-wins replacement remains possible; run one instance.
+- During v3 migration, legacy tool cards pair each call with the next result by order. Live events pair by `callId`.
+
+## Development and releases
+
+Contributor commands, GitHub Actions, and npm publishing are documented in the [Development and release guide](../development.md).
+
+Return to the [project overview](../../README.md).