dsh-synapse 0.4.0

package/docs/zh-CN/README.md

@@ -0,0 +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)。