侧栏会话管家 linuxsung/dsh-sidebar-manager

Sidebar Manager

English · 한국어

状态：活跃（v0.1.3）· 最后更新：2026-10-23 · 仓库：linuxsung/dsh-sidebar-manager

目录

| 章节 | 用途 |
| v0.1.3 文档热修复 | 英文默认版与韩文对照版对齐 |
| M1–M4 提升核心 | Type A 注册、Type B-cold、实时交接 API、日志与锁 |
| 实现状态 | P1 UI / P2 Host / P3 管理面板 / M1–M4 |
| 概览 | 插件做什么、不做什么 |
| 布局 | 包内各文件的职责 |
| 安装 | 本地检出与市场安装 |
| 安全规则 | Move/Fork/Delete 事务不变量 |
| 确认关卡 | 风险操作前必须展示什么 |
| UI 文案（i18n） | 面向用户的字符串放在哪里 |

v0.1.3 文档热修复

已发布的 v0.1.2 根目录 README.md 是韩文，而 README.ko.md 里放的是更旧、更短的韩文副本。从 v0.1.3 起，仓库遵循全局文档标准：

- README.md 是英文默认版，并链接到韩文对照版。
- README.ko.md 是完整韩文翻译，并链接回 README.md。
- release-harness 现在每次 run 和 publish 都会校验暂存的文档：英文根文件、本地化对照文件、文件顶部互相切换的链接。根文件不是英文时，会在打包前以退出码 5 中止发布。

本次发布还一并发布了 v0.1.2 之后合入 main 的 M1–M4 提升宿主核心。UI 按钮、快捷键、自动技能触发（M5）仍不在范围内。

M1–M4 提升核心

宿主级项目提升 API。暂不含 UI 按钮、快捷键、自动技能激活（M5）。

重要区别： Type A 目前是注册（目录注册）。它只挂接 cwd 与注册目录匹配的会话；不会移动从其他 cwd 工作的父会话。完整的 Promote 路径需要 existing + sessionId + sessionPolicy(move|handoff|defer) 连接器。正因如此，release-harness 目前声明 sessionIds: []。

POST /api/local/sidebar/promotion/preview
POST /api/local/sidebar/promotion/apply
POST /api/local/sidebar/promotion/status

Type A — 注册已有目录

{ "mode": "existing", "path": "C:\\...\\release-harness", "title": "Universal Release Ops Harness" }

- 规范化 realpath、projectsRoot 包含校验、默认工作区与重名标题拦截。
- 挂接 cwd 相同、尚未归属的会话，最旧的优先。结果按最新优先排序。
- 只使用公开的 workspaceRegistry.create(path, title) API。
- restartRequired=false；workspace.follow 立即反映变更。
- cwd 不同的会话不会挂接。 移动它们需要单独的 sessionPolicy。

Type B-cold —— 临时目录加会话迁移

{ "mode": "scratch-cold", "sessionId": "session-...", "path": "C:\\...\\new-project", "title": "New Project" }

- 仅限冷会话。
- 创建目标目录 → git init -b main → release.manifest.json 模板 → 首次提交。
- 迁移会话日志：先写入暂存区 → buildRelocated → verifyRelocated → 重命名。事件帧逐字节保留，只重写头部的 cwd。
- 写入 prepared → provisioned → log-ready → files-ready 日志，返回 restartRequired=true。
- 下次启动时，finalizer 创建目标工作区，并用 detach → attach 确认归属。
- 若在 log-ready 之前崩溃，恢复原始日志与缓存；若日志停在 files-ready，则继续完成收尾。

Type B-live —— 从最后一个完成的回合交接

{ "mode": "scratch-handoff", "sessionId": "session-...", "path": "C:\\...\\new-project", "title": "New Project" }

- 源会话可以处于活跃状态。只取最后一个 turn/end 之后已完成的前缀作为种子。
- 用 agents.create({ seed, inheritedEventCount, cwd: target, parentSession, isSeeded: true }) 创建新会话，并挂载已有的智能体预设。
- 创建目标工作区，立即挂载新会话。restartRequired=false。
- 源会话 ID 与归属不变，签发新的会话 ID。
- 日志：prepared → workspace-ready → child-created → committed。若进程在 child-created 处崩溃，启动时的 finalizer 只重试挂载。

共用机制

- 路径：stateDir/promotion/pending.json、stateDir/promotion/lock.json。
- 单写者锁，支持回收过期的 PID/TTL。
- 目标路径、标题、Windows 名称校验放在 lib/path-policy.mjs 和 lib/provision.mjs。
- 生成的 release.manifest.json 模板使用 release-harness schema URL，初始版本 0.1.0。

验证：npm test 33/33，隔离 Playwright E2E 83/83。E2E 套件在真实 DSH 上覆盖 Type A 的即时可见、Type B-cold 的重启 finalizer，以及 Type B-live 的新会话/即时 UI 行为。

下一个连接器（尚未实现）

{
"mode": "existing",
"path": "C:\\...\\release-harness",
"title": "Universal Release Ops Harness",
"sessionId": "session-7b2cc3e8-ae1c-4ba6-bdb7-66cc0933366e",
"sessionPolicy": "move"
}

- move：仅冷会话，ID 不变，需重启。
- handoff：允许活跃会话，新 ID，无需重启。
- defer：先切换执行 cwd，等回合结束后再迁移并重启。

实现状态

- P1 客户端 UI 完成 —— 会话悬停垃圾桶、三项 ⋯ 菜单、确认门对话框都在 lib/client.js。
- P2 宿主完成 —— 三个预览路由（session/move、workspace/rename-folder、session/fork-to-workspace）外加 purge/archive/restore/archived/move/rename-folder/fork 路由、journal，以及 lib/transaction.mjs 里的启动 finalizer。
- P3 Manager Panel 完成 —— sidebar.panellist，加上 main 面板作为第三个顶层菜单。行内重命名、include-folder 复选框、rename/archive 按钮，以及文件夹变更门禁。页脚按钮已移除。
- M1–M4 promotion Host 完成 —— Type A 路径策略/journal/锁，Type B-cold 预配与 2PC，Type B-live 交接。包含 preview/apply/status 路由和启动 finalizer。UI 与自动激活仍属后续工作。
- Live E2E 通过 —— 在隔离的 DSH 实例（端口 3099）中，Playwright 83/83 项检查全部通过，覆盖 Move/Rename/Fork 重启 finalizer、Type A、Type B-cold 和交接。

概览

一个本地插件，从 DSH 侧边栏管理会话和工作区。

1. 永久删除 —— 移除已归档冷会话的日志、项目缓存和注册表映射。
2. 工作区归档 —— 归档成员会话，释放工作区注册，并从顶层 Workspace manager 面板恢复。
3. 移动到工作区 —— 重写冷会话 zstd 头部的 cwd，并通过 2PC 更新物理路径和注册表。
4. Fork 到新工作区 —— 创建新项目目录和工作区，然后把源会话日志以新 ID 复制过去，作为它的第一个会话。它不创建活跃子会话，因此重启 finalizer 可以安全挂接。
5. Workspace Manager 面板 —— 第三个顶层菜单。行内编辑行名，按 Enter 保存。只有文件夹被包含时，才会出现真实的目录名输入框和 Confirmation Gate。

目录结构

| 路径 | 作用 |
| lib/index.js | Host 入口。注册 transaction 和 promotion 的 Exact Fetch 路由 |
| lib/transaction.mjs | Move/Archive/Purge/Fork 的 2PC |
| lib/promotion.mjs | Promotion 模式分发、Type A preview/apply/status、启动 finalizer |
| lib/promotion-store.mjs | Promotion journal、原子写入、单写者锁 |
| lib/provision.mjs | Scratch 目标规划、Git 初始化、release.manifest.json 模板 |
| lib/scratch-promotion.mjs | Type B-cold 预配、日志迁移、回滚/finalizer |
| lib/handoff.mjs | Type B-live 边界/种子、智能体预设挂载、子会话挂接 |
| lib/path-policy.mjs | 规范路径、projectsRoot 包含校验、标题/名称校验 |
| lib/session-log.mjs | zstd 帧解析、头部重写/复制、完整性校验 |
| lib/client.js | 浏览器入口。注册官方插槽 |
| cordis.patch.yml | 配置档 bundle 补丁 |
| locale/{en,ko}.json | 插件显示元数据 |
| market/index.json | Marketplace 索引（format 1）模板 |

安装

after an npm release
dsh plugin --profile web add @nolit/dsh-sidebar-manager

local checkout
dsh plugin --profile web add link:<path-to-dsh-sidebar-manager>
做市场分发时，先运行 npm publish，再更新 market/index.json 里的 versions，然后从 Plugins → Discover 添加索引 URL。

安全规则

- Move/Fork 只接受冷会话；活跃或打开的会话会被拒绝。
- Fork 会以新 ID 复制源日志，不调用 sessionController.fork，避免产生活跃子会话。
- finalizer 始终走 detach → attach。如果 attach 失败，会话仍处于未归属状态，journal 会保证重试。
- 回滚不会恢复整个 workspace.json。它只还原事务涉及的日志、缓存和目录，保留并发的注册表改动。
- 只改标题会立即保存，无需重启。真正的目录变更要经过 Confirmation Gate 并重启后才生效。
- 每次文件操作都会把原始文件快照到 ~/.dsh/backup/<txid>/。
- 重写后的 header 文件会写入新位置，通过完整性校验后，才清理旧路径并更新注册表。
- 确认对话框会明确告知：智能体未来的 CWD 将迁移到新工作区。

Confirmation Gate

执行 Move、Fork to New Workspace 或与文件夹关联的 Rename 之前，对话框会在同一屏展示以下内容，并且在你勾选确认复选框之前，执行按钮一直保持禁用：

1. 影响预览 —— 受影响的冷会话数量 N、旧路径 → 新路径、目标工作区标题/ID。
2. CWD 警告 —— 「从现在起，智能体运行的命令和创建的文件都将以 newPath 为根目录。」
3. 重启提示 —— 「文件现在就会迁移，但侧边栏要等 DSH 服务器重启后才会反映变化。」
4. 显式确认 —— 在勾选 [ ] I understand the impact and that a restart is required. 之前，执行按钮保持禁用。

执行按钮的启用条件：

preflight.preview.ok === true
&& confirmCheckbox === true
&& preflight.liveSessionCount === 0
&& (folderRename ? preflight.isDefaultWorkspace === false : true)

preflight.preview 是只读路由，返回 { affectedSessionCount, liveSessionCount, oldPath, newPath, targetExists, workspaceTitle, isDefaultWorkspace, blockers[] }。
blockers 非空时，执行按钮和复选框都会禁用，并显示原因。

UI 文案（i18n）

所有面向用户的字符串都放在 lib/client.js 顶部的同一个 I18N = { ko: {...}, en: {...} } 对象里。不要在其余代码中硬编码 UI 文本。

- ko 和 en 的键结构必须一致；改文案时只改这个对象。
- 语言跟随 navigator.language：ko* 选韩语，其余选英语。
- {count}、{oldPath}、{newPath} 这类占位符由 t(key, vars) 替换。
- 市场标题/描述由 locale/{en,ko}.json 里的 meta 对象单独处理。