dsh-synapse 0.4.1 → 0.4.2

package/docs/en/README.md

@@ -1,161 +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).
+# 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
+
+- DeepSeek Harness `>= 0.1.7-rc.2`; this revision targets that release's Host session and Client service interfaces.
+- 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).

package/docs/zh-CN/README.md

@@ -1,154 +1,154 @@
-# dsh-synapse 中文指南
-
-`dsh-synapse` 是 DeepSeek Harness（DSH）的 Web 插件。它在 DSH 原生对话界面上增加会话地图，把同一工作区中的会话、追问和分支组织成可浏览、可拖拽和可缩放的画布。
-
-插件不替代 DSH 的模型、工具、会话、权限或 Web 服务；所有对话操作仍由 DSH 完成。
-
-## 前提条件
-
-- 支持 `dsh plugin` profile 插件机制的 DeepSeek Harness（2026-08 或之后版本）。
-- Node.js `>= 22.19.0`。
-- 使用 `web` profile；其他 profile 暂不支持。
-
-## 安装
-
-### 从 npm 安装
-
-```powershell
-corepack pnpm dsh plugin --profile web add dsh-synapse
-```
-
-npm 包分发的是预构建产物，无需任何构建授权——最简单的安装方式。下方 GitHub 与本地 checkout 为备选。
-
-### 从 GitHub 安装
-
-```powershell
-corepack pnpm dsh plugin --profile web add github:liangmianya/dsh-synapse
-```
-
-GitHub 安装会运行本包的 `prepare` 脚本，通过 `node --check` 验证 JavaScript 语法。
-
-### pnpm 10+ 的 allowBuilds
-
-pnpm 10 及之后版本默认可能阻止 Git 依赖执行构建脚本。如果安装被拦截，请将 pnpm 输出的**完整键**复制到 DSH Web profile 的 `pnpm-workspace.yaml`：
-
-```yaml
-allowBuilds:
-  "dsh-synapse@https://codeload.github.com/liangmianya/dsh-synapse/tar.gz/<commit>": true
-```
-
-必须使用包含 tarball URL 和 commit 的完整键，不能只填写裸包名 `dsh-synapse`。上游 commit 变化后，键也会变化；届时使用 pnpm 新输出的值。
-
-### 本地开发安装
-
-```powershell
-corepack pnpm dsh plugin --profile web add link:E:\path\to\dsh-synapse
-```
-
-`link:` 会直接引用本地 checkout，适合开发和调试。普通运行模式下修改代码后，建议重启 `dsh web` 并刷新页面。
-
-## 启动
-
-```powershell
-corepack pnpm dsh web
-```
-
-默认地址：
-
-```text
-http://127.0.0.1:3080/
-```
-
-如果 3080 被占用，可以让 DSH 自动选择端口：
-
-```powershell
-corepack pnpm dsh web --port 0
-```
-
-启动后点击顶部“会话地图”进入 Synapse。不要同时运行两个共享同一 profile 的 `dsh web` 实例。
-
-## 使用方式
-
-1. 在 DSH 中选择工作目录，或打开已有会话。
-2. 发送至少一条消息，使会话进入工作区历史。
-3. 点击顶部“会话地图”。
-4. 点击卡片或侧边栏会话，在地图与原生对话之间同步当前会话。
-5. 使用“分支”从已完成的回答创建替代路径。
-6. 点击卡片底部“详情”查看完整会话记录。
-7. 使用“打开 DSH”或顶部“对话”返回原生对话界面。
-
-画布支持：
-
-- 拖动画布和缩放视图（最高 4×）。
-- 拖动卡片并自动保存位置。
-- 展开或折叠后续对话子树。
-- 一键定位当前会话。
-- 卡片内部平滑滚动和 Markdown 表格渲染。
-- 将工具调用和结果按 `callId` 折叠到对应助手回答中。
-
-## 配置
-
-插件通过 profile 的 `cordis.patch.yml` 注入。可以在自己的 patch 中通过行 id `synapse` 覆盖配置。
-
-> DSH patch 会整体替换该行的 `config`，覆盖时需要重述所有需要保留的键。
-
-| 键 | 默认值 | 说明 |
-|---|---|---|
-| `dataFile` | `$DSH_HOME/synapse/workspaces.json` | 画布元数据持久化文件 |
-| `autoProjection` | `true` | 自动将已提交的 DSH 会话事件投影为卡片 |
-| `projectionWorkspaceTitle` | `DSH 任务` | 自动投影工作区的标题 |
-| `trustedHosts` | `[]` | `/synapse` Host 检查额外允许的主机名或 `主机:端口`；`localhost` 和 `127.0.0.1` 始终允许 |
-
-配置示例：
-
-```yaml
-- id: synapse
-  config:
-    dataFile: !!js dshHomePath('synapse/my-workspaces.json')
-    autoProjection: true
-    projectionWorkspaceTitle: 我的任务
-    trustedHosts: []
-```
-
-局域网访问时，需要将实际访问主机加入 `trustedHosts`。
-
-## 卸载与数据清理
-
-卸载插件：
-
-```powershell
-corepack pnpm dsh plugin --profile web remove dsh-synapse
-```
-
-`remove` 只移除插件依赖和 profile 激活层，不会删除画布数据。重新安装后，旧数据会继续使用并按需迁移。
-
-彻底清理时，手动删除：
-
-```text
-$DSH_HOME/synapse/
-```
-
-`pnpm-workspace.yaml` 中遗留的 `allowBuilds` 键没有副作用，也可以一并移除。
-
-## 数据与运行边界
-
-- DSH session log 保存真实对话内容。
-- Synapse 的 `workspaces.json` 只保存画布元数据、布局和分支锚点。
-- 删除 `workspaces.json` 会丢失画布布局，但不会删除 DSH 会话。
-- 单条消息投影上限为 8000 字符；超出部分在卡片中截断并标注“—…（详情查看全文）”，完整内容仍可在会话详情中查看。
-- 插件不启动第二个 Web 服务，也不创建第二套 Agent。
-- 插件只读取已经提交的会话事件，不修改模型请求、系统提示、工具 schema 或 KV cache 前缀。
-
-更详细的内部说明见[架构与运行边界](../architecture.md)。
-
-## 已知限制
-
-- 仅支持 `web` profile。
-- 两个 DSH Web 实例共享同一个 profile 时会写入同一个 `workspaces.json`。虽然存在跨进程写锁和外部修改警告，仍可能出现最后写入覆盖，请只运行一个实例。
-- v3 数据迁移时，旧工具卡片按顺序将每次调用与下一条结果配对；实时事件使用 `callId`。
-
-## 开发与发布
-
-贡献者命令、GitHub Actions 和 npm 发布流程见[开发与发布指南](../development.md)。
-
-返回[项目主页](../../README.md)。
+# dsh-synapse 中文指南
+
+`dsh-synapse` 是 DeepSeek Harness（DSH）的 Web 插件。它在 DSH 原生对话界面上增加会话地图，把同一工作区中的会话、追问和分支组织成可浏览、可拖拽和可缩放的画布。
+
+插件不替代 DSH 的模型、工具、会话、权限或 Web 服务；所有对话操作仍由 DSH 完成。
+
+## 前提条件
+
+- DeepSeek Harness `>= 0.1.7-rc.2`（本插件依赖该版本的 Host 会话与 Client 服务接口）。
+- Node.js `>= 22.19.0`。
+- 使用 `web` profile；其他 profile 暂不支持。
+
+## 安装
+
+### 从 npm 安装
+
+```powershell
+corepack pnpm dsh plugin --profile web add dsh-synapse
+```
+
+npm 包分发的是预构建产物，无需任何构建授权——最简单的安装方式。下方 GitHub 与本地 checkout 为备选。
+
+### 从 GitHub 安装
+
+```powershell
+corepack pnpm dsh plugin --profile web add github:liangmianya/dsh-synapse
+```
+
+GitHub 安装会运行本包的 `prepare` 脚本，通过 `node --check` 验证 JavaScript 语法。
+
+### pnpm 10+ 的 allowBuilds
+
+pnpm 10 及之后版本默认可能阻止 Git 依赖执行构建脚本。如果安装被拦截，请将 pnpm 输出的**完整键**复制到 DSH Web profile 的 `pnpm-workspace.yaml`：
+
+```yaml
+allowBuilds:
+  "dsh-synapse@https://codeload.github.com/liangmianya/dsh-synapse/tar.gz/<commit>": true
+```
+
+必须使用包含 tarball URL 和 commit 的完整键，不能只填写裸包名 `dsh-synapse`。上游 commit 变化后，键也会变化；届时使用 pnpm 新输出的值。
+
+### 本地开发安装
+
+```powershell
+corepack pnpm dsh plugin --profile web add link:E:\path\to\dsh-synapse
+```
+
+`link:` 会直接引用本地 checkout，适合开发和调试。普通运行模式下修改代码后，建议重启 `dsh web` 并刷新页面。
+
+## 启动
+
+```powershell
+corepack pnpm dsh web
+```
+
+默认地址：
+
+```text
+http://127.0.0.1:3080/
+```
+
+如果 3080 被占用，可以让 DSH 自动选择端口：
+
+```powershell
+corepack pnpm dsh web --port 0
+```
+
+启动后点击顶部“会话地图”进入 Synapse。不要同时运行两个共享同一 profile 的 `dsh web` 实例。
+
+## 使用方式
+
+1. 在 DSH 中选择工作目录，或打开已有会话。
+2. 发送至少一条消息，使会话进入工作区历史。
+3. 点击顶部“会话地图”。
+4. 点击卡片或侧边栏会话，在地图与原生对话之间同步当前会话。
+5. 使用“分支”从已完成的回答创建替代路径。
+6. 点击卡片底部“详情”查看完整会话记录。
+7. 使用“打开 DSH”或顶部“对话”返回原生对话界面。
+
+画布支持：
+
+- 拖动画布和缩放视图（最高 4×）。
+- 拖动卡片并自动保存位置。
+- 展开或折叠后续对话子树。
+- 一键定位当前会话。
+- 卡片内部平滑滚动和 Markdown 表格渲染。
+- 将工具调用和结果按 `callId` 折叠到对应助手回答中。
+
+## 配置
+
+插件通过 profile 的 `cordis.patch.yml` 注入。可以在自己的 patch 中通过行 id `synapse` 覆盖配置。
+
+> DSH patch 会整体替换该行的 `config`，覆盖时需要重述所有需要保留的键。
+
+| 键 | 默认值 | 说明 |
+|---|---|---|
+| `dataFile` | `$DSH_HOME/synapse/workspaces.json` | 画布元数据持久化文件 |
+| `autoProjection` | `true` | 自动将已提交的 DSH 会话事件投影为卡片 |
+| `projectionWorkspaceTitle` | `DSH 任务` | 自动投影工作区的标题 |
+| `trustedHosts` | `[]` | `/synapse` Host 检查额外允许的主机名或 `主机:端口`；`localhost` 和 `127.0.0.1` 始终允许 |
+
+配置示例：
+
+```yaml
+- id: synapse
+  config:
+    dataFile: !!js dshHomePath('synapse/my-workspaces.json')
+    autoProjection: true
+    projectionWorkspaceTitle: 我的任务
+    trustedHosts: []
+```
+
+局域网访问时，需要将实际访问主机加入 `trustedHosts`。
+
+## 卸载与数据清理
+
+卸载插件：
+
+```powershell
+corepack pnpm dsh plugin --profile web remove dsh-synapse
+```
+
+`remove` 只移除插件依赖和 profile 激活层，不会删除画布数据。重新安装后，旧数据会继续使用并按需迁移。
+
+彻底清理时，手动删除：
+
+```text
+$DSH_HOME/synapse/
+```
+
+`pnpm-workspace.yaml` 中遗留的 `allowBuilds` 键没有副作用，也可以一并移除。
+
+## 数据与运行边界
+
+- DSH session log 保存真实对话内容。
+- Synapse 的 `workspaces.json` 只保存画布元数据、布局和分支锚点。
+- 删除 `workspaces.json` 会丢失画布布局，但不会删除 DSH 会话。
+- 单条消息投影上限为 8000 字符；超出部分在卡片中截断并标注“—…（详情查看全文）”，完整内容仍可在会话详情中查看。
+- 插件不启动第二个 Web 服务，也不创建第二套 Agent。
+- 插件只读取已经提交的会话事件，不修改模型请求、系统提示、工具 schema 或 KV cache 前缀。
+
+更详细的内部说明见[架构与运行边界](../architecture.md)。
+
+## 已知限制
+
+- 仅支持 `web` profile。
+- 两个 DSH Web 实例共享同一个 profile 时会写入同一个 `workspaces.json`。虽然存在跨进程写锁和外部修改警告，仍可能出现最后写入覆盖，请只运行一个实例。
+- v3 数据迁移时，旧工具卡片按顺序将每次调用与下一条结果配对；实时事件使用 `callId`。
+
+## 开发与发布
+
+贡献者命令、GitHub Actions 和 npm 发布流程见[开发与发布指南](../development.md)。
+
+返回[项目主页](../../README.md)。