🌏 English · 中文
dsh-session-reattach
把游离（未分组）会话按 cwd 送回它该在的工作区
只改归属记录 · 不碰会话文件 · 默认 dry-run
特性 ·
用法 ·
安装 ·
快速上手 ·
判定规则 ·
安全边界 ·
与同类插件 ·
常见问题 ·
开发
会话被移动过、或在工作区还不存在时就创建过之后，它可能永远回不到任何工作区分组里 ——
侧边栏里只剩一个「未分组」。这个插件补上那个缺失的入口：把会话拖进它该在的工作区文件夹。
名字
reattach（重新归属）：会话文件一个字节都不动，只把 workspace.json 里那份归属记录改对。
之所以叫「归位」而不是「移动」，是因为它做不到任意移动 —— 见判定规则：
DSH 只接受 cwd 与工作区目录完全一致的归属，所以这个插件能把会话送回它本来就在的那个目录，
但不能把它迁到别的目录去。
特性
- 补的是 DSH 的一个真实空白 ——
Workspace.attachSession 只在新建会话 / 新建子代理时被调用；历史会话的自动收养在 WorkspaceRegistry 初始化时只跑一次（initialized 落盘即永不再跑）；而全部 @Remote(...) 端点里没有任何 attach 类方法。于是「会话移动过 ⇒ 永久游离」没有任何修复入口，本插件就是那个入口。
- 只改归属，不碰会话文件 —— 不做任何文件写入，会话日志（
session.jsonl.zstd）与首帧 cwd 都不动。与「改会话首帧 cwd 把自己挂到别处」是两条路。
- 写入权威只有 DSH —— 归属校验与落盘全部走
Workspace.attachSession / detachSession；插件自己不做路径判定以外的任何决定，也不直接写 workspace.json。
- 先清后挂 —— 归位前先从其余工作区清掉该会话的陈旧槽位。这不是洁癖：
attachSession 不复核别的工作区，而 registry 启动校验会因为同一会话被两个工作区记账而直接抛错、整个工作区域不可用；顺序错了就会踩这个坑（审计已证实）。
- 同 canon 判定 —— 用
fs.realpath 把会话 cwd 与工作区 path 归一到同一套 canon 再比较：尾斜杠、..、符号链接、大小写差异都不会误判；判定结果与真实 WorkspaceEntity 逐条一致（审计逐条比对过）。
- 默认 dry-run —— 只有显式
"dryRun": false（或命令里写 apply）才写入；"false" 字符串、0、null、[] 一律仍是 dry-run。
- 拖拽时只高亮合法落点 —— 开始拖动的那一刻就算出该会话唯一能去的工作区（浏览器侧用
SessionSummary.cwd 预筛），只有那个分组接受放置；其余分组显示禁止光标。判断只作提示，最终以宿主判定为准。
- 失败关闭 —— 清槽位失败就放弃 attach（绝不冒双归属的险）；会话数量超上限会明说「还有 N 个更早的会话未参与判定」，不假装看全了；上游改了侧边栏结构就整体静默（什么都不做，绝不写错数据）。
- 零运行时依赖 —— 不 import 任何 DSH 包，也不装任何第三方包，只用
ctx 上的服务；纯 JS 全平台可用。
用法
| 入口 | 作用 | 怎么触发 |
|---|
| 拖拽 | 把「未分组」里的会话拖进它该在的工作区分组 | 侧边栏里直接拖；cwd 匹配的分组会亮虚线框 |
/reattach | 只报告：将归位哪些会话、哪些不能归位及原因 | 输入框敲，不经过模型 |
/reattach apply | 执行归位 | 同上 |
/reattach apply subagents | 连带处理子代理会话（默认跳过） | 同上，参数可任意顺序 |
拖到别的分组不会被写入（禁止光标）。若该会话本来就不在可归位集合里（cwd 已失效、没有对应工作区、已归档……），插件不猜原因，而是放行落点、请宿主给出准确结论，再用右下角提示条显示 —— 所以你看到的一定是真实原因。
/reattach 是纯宿主命令：不消耗 token、不受模型判断影响，也是拖拽万一失效时的兜底通道。
下面是示例（分类口径与数字取自一次真实 dry-run：78 个会话、10 个工作区）：
会话归位 · dry-run（未写入任何内容）
可归位 2 个：
• session-xxxx → 「team-manage」（/Users/me/Project/team-manage）
• session-yyyy → 「dsh-palimpsest」（/Users/me/Project/dsh-palimpsest）
无匹配工作区 1 个：
• session-zzzz：/Users/me/Downloads
cwd 无法校验 1 个：
• session-wwww：cwd 已失效（目录被移动、改名或不可访问）（/Users/me/old-project）
跳过：已归档 39 个、子代理会话 11 个
已归属、无需动作：26 个
执行：/reattach apply，或把会话直接拖进侧边栏里对应的工作区分组。
安装
从 npm / GitHub
dsh plugin --profile web add dsh-session-reattach
# 或
dsh plugin --profile web add github:cnkids/dsh-session-reattach
从本地路径（开发中）
在插件目录下执行（link: 会让源码改动直接生效，不必每次重装）：
dsh plugin --profile web add "link:$(pwd)"
安装命令会把依赖写进 profile 的 package.json，并把声明了 dsh.bundle 的包追加进 dsh.profile.bundles。
装完必须重启 dsh web —— 宿主插件由 cordis loader 在启动时装配，本机 profile 没有开 patchReload: live，hmr 在 dsh-base 里默认 disabled: true。
本插件是 web profile 专用：宿主半边需要 webServer 与 connection 两个服务（后者由 dsh-client-connection 的宿主半边提供）。缺任意一个，cordis 会把插件停在「等待依赖」而不启用 —— 这是刻意的失败关闭，不会留下一个没有守卫的写入端点。
快速上手
装好重启后，先看一眼有没有要修的（这一步不写任何东西）：
/reattach
确认列表没问题再执行：
/reattach apply
日常更省事的是直接拖：在侧边栏展开「未分组」，按住某个会话行开始拖动，cwd 匹配的那个工作区分组会立刻亮起虚线框，拖进去松手即可 —— 右下角提示条会告诉你结果，侧边栏自动刷新。
判定规则
匹配 = realpath(会话头 cwd) === workspace.path
工作区 path 在建记录时就已是 fs.realpath 的结果（无尾斜杠、无 ..、符号链接已解开），所以两端都走 realpath 才是同 canon 比较。以下写法都算匹配（会被归一掉）：/work/、/work/.、/work/sub/..、指向同一目录的符号链接，以及大小写不敏感卷上目录名的大小写差异。
匹配不上的五种成因，各有独立文案：
| # | 成因 | 归类与提示 |
|---|
| 1 | 会话头没有 cwd | 跳过：无法校验 |
| 2 | cwd 不是绝对路径 | 跳过：非绝对路径 |
| 3 | 目录已删 / 改名 / 不可访问 | 跳过：cwd 已失效 |
| 4 | 路径存在但不是目录 | 跳过：不是目录 |
| 5 | 能解析、是目录，但与该分组的 path 不同 | 拖错分组：该目录属于另一个工作区就点名「只能归位到 X」；没有任何工作区记录该目录则提示先在侧边栏为它创建工作区 |
为什么不做任意迁移：DSH 的 attachSession 会拒绝 cwd 与工作区目录不一致的归属，这是宿主的硬校验，不是本插件的限制。所以拖拽在这里的语义是「把它送回它本来就在的那个文件夹」。
安全边界（请如实理解）
这是一条会写工作区归属的通道，所以边界要说清楚，而不是笼统说「安全」：
- 请求信任 —— 路由与
/api 用的是同一套守卫：Host 必须是回环或受信、Origin 存在时必须与 Host 同源、Sec-Fetch-Site: cross-site 直接拒，之后还要过浏览器认证。实测未认证 / 跨源 / Origin: null / 伪造 Host 一律 401/403，且先拒绝、后不解析业务体（审计对运行中的宿主实测）。
- 默认不写 —— 只有显式
"dryRun": false 才落盘；类型混淆打不开这个开关。
- 失败关闭 —— 清槽位失败就放弃 attach；计划数据形状不对时前端不猜落点；上游改了侧边栏 DOM，拖拽整体静默。
- 不越权 —— 只用
attachSession / detachSession，不写文件、不起子进程、不联网。
说清楚代价与做不到什么：
- 它会 mutate 非目标工作区：归位一条会话时，插件对每个非目标工作区调用一次
detachSession；DSH 的 mutate 会顺带持久剪枝该工作区里「已索引 cwd 与记录不符」的候选。剪枝判据是持久事实（会话头没有 cwd、或 cwd 解析到别处），不是「目录暂时不可达」，所以外置卷临时卸载不会掉归属；而被剪掉的会话在目录恢复后会被本插件重新归位。不这么做的替代方案是留下双归属，让下次启动 validateStoredState 直接抛错。
- 它靠侧边栏的结构工作：会话行锚点
[role="treeitem"][aria-selected]、工作区分组行锚点 [role="treeitem"][aria-expanded][draggable="true"]，以及内置 onDragStart 把会话 id 写进 dataTransfer 的 text/plain 这一行为。上游改了其中任何一处，拖拽会静默失效（识别不到就什么都不做），/reattach 命令不受影响。
- 分组靠标题匹配：DOM 行不携带工作区 id，只能按可见标题匹配。标题重复时可能高亮到同名的另一个分组 —— 那种情况下宿主仍会拒绝并给出「只能归位到 X」，最坏结果是一句明确报错。
/state 的成本与调用方相同源：每次请求对每个会话做 realpath + stat（本机 78 会话约 10 ms 量级）。宿主侧刻意不加缓存（缓存会把刚变化的归属喂给写入判定，让一次合法归位变成失败）；调用方必须已认证，而同源脚本本就能调 /api 做成本更高的事。
与同类插件的差异
这个方向上的常见做法是「会话移动器」（拖拽迁移、批量操作、回收站、分组合并），本插件的取舍是只做归位：
| 本插件 | 移动器类插件 |
|---|
| 能力 | 只重新归属：把 cwd 有效但没被记账的会话挂回匹配的工作区 | 任意跨工作区迁移、批量、回收站、分组 |
| 会话文件 | 不碰（不重写首帧 cwd） | 常需改写会话首帧或搬动会话目录 |
| 允许的落点 | 只有 cwd 与工作区目录完全一致的那一个（宿主硬校验） | 由插件自己定义，通常任意 |
| 写入面 | 两个已存在的宿主 API（attachSession / detachSession） | 自建存储 / 索引与迁移逻辑 |
| 运行时依赖 | 零（不 import 任何 DSH 包） | 常见对 DSH 内部包的直接依赖 |
| 安全审计 | 有（8 条 PoC：真 socket、真实 WorkspaceEntity、运行中宿主的守卫探测；产物不随仓库分发） | 未见 |
与 dsh-palimpsest 的关系（一处常见误判）：palimpsest 的硬范围只比对会话头 cwd，候选来自 sessionQuery.listSessions()（live + 全部持久化会话），与工作区归属无关。所以一个「未分组」会话只要 cwd 等于当前会话的 cwd，palimpsest 今天就能读到它 —— 本插件修的是侧边栏分组与工作区记账，不是 palimpsest 的可见性。两者解耦，不需要为彼此改一行代码。
常见问题
装完没反应？ 必须重启 dsh web（宿主插件只在启动时装配）。重启后 /reattach 应出现在命令面板里。
拖不动 / 拖进去没反应？ 先确认那个会话的 cwd 对应的目录存在且是目录；目录已删的会话只能在报告里看到「cwd 已失效」。如果是上游改了侧边栏导致拖拽整体失效，用 /reattach（功能不受影响），并在 issue 里带上你的 DSH 版本。
拖错分组会怎样？ 不会写错。cwd 不匹配的分组不接收放置；万一同名标题让它放行了，宿主仍会拒绝并提示「只能归位到 X」。
会不会动我的会话？ 不会。插件只调用 attachSession / detachSession 改归属，会话日志与首帧 cwd 一个字节都不改。
为什么不能把会话移到别的项目？ 因为 DSH 只接受 cwd 与工作区目录完全一致的归属。想换项目，得先改会话首帧 cwd（那是另一类工具的事），本插件刻意不碰文件。
子代理会话要不要一起归位？ 默认跳过（它们嵌在父会话下，单独归位收益低）。需要时用 /reattach apply subagents。
已归档的会话为什么不动？ 归档会话在侧边栏本就不可见，而且归档不会摘掉归属槽位，所以没有补写的必要。
没有对应工作区的会话怎么办？ 插件只报告、不创建（职责边界就是「归位」）。按提示先在侧边栏为那个目录创建工作区，再归位。
会不会拖慢 DSH 启动？ 不会。插件不做任何启动期扫描或索引。
连不上网能用吗？ 可以。插件不联网、零运行时依赖。
为什么叫 reattach？ 见名字。
开发
npm test # 121 个用例：纯逻辑单测 + 宿主装配 + HTTP 真 socket + 浏览器半边行为
npm run coverage # 同上，并生成 coverage/lcov.infonode scripts/build-client.mjs # 改了 client-core.js / client-dom.js 后必须重新生成
覆盖率（Node 内置统计）：行 99.60%、函数 99.13%、分支 96.24%。
改了 lib/client-core.js 或 scripts/client-dom.js 一定要重新生成 lib/client.js；忘记生成会让 test/client.test.mjs 的漂移检查失败。浏览器端 bundle 必须是 classic script（内置模块系统用 <script src> 加载），既不能写 import / export，也不能被 Node 直接 import —— 这就是「纯逻辑单独成模块 + 生成」的原因。
安全审计：8 条可独立运行的 PoC（真 socket 的 413/HTTP 语义、与真实 WorkspaceEntity 的逐条比对、以及针对运行中宿主的守卫探测）在仓库外维护，不随仓库分发；结论已并入上文「安全边界」。
SonarQube：
npm run coverage # 先产出 coverage/lcov.info，否则覆盖率是空的
npm run sonar # = ./scripts/sonar-check.sh，分支自动取当前 git 分支
npm run sonar -- main # 显式指定分支
令牌绝不写进仓库。本机约定是在 ~/.zshrc 里按项目放一个变量：
export SONAR_TOKEN_DSH_SESSION_REATTACH=sqp_xxxxxxxx
scripts/sonar-check.sh 会优先取它并映射成 SONAR_TOKEN，未设置时回退通用 SONAR_TOKEN；脚本还负责分支与版本号（不带 sonar.branch.name 时结果会写进 SonarQube 主分支）。
代码结构：lib/core/ 是不依赖 DSH 的纯逻辑（路径 canon、计划、执行、渲染），lib/host.js 是与 ctx 的唯一接触面，lib/http.js 与 lib/command.js 是两个入口，lib/index.js 是插件入口；浏览器半边是 lib/client-core.js + scripts/client-dom.js（生成 lib/client.js）。
HTTP 契约（供二次开发与排查）：
| 方法 | 路径 | 说明 |
|---|
GET | /session-reattach/state | 工作区清单 +「可归位会话 → 目标工作区」映射，供前端预筛落点 |
POST | /session-reattach | 体 {dryRun?, sessionId?, workspaceId?, includeSubagents?}；不写 dryRun 即 dry-run |
single.code 取值：ok / already-accounted / cwd-invalid / no-workspace / workspace-mismatch / workspace-not-found / session-live / session-archived / session-subagent / session-not-found；内部故障一律 internal-error（细节只进宿主日志）。
发布（npm + GitHub Actions）
v* tag 由 .github/workflows/release.yml 接管：校验 tag 与 package.json 版本一致 → npm ci → npm audit → npm test → npm publish --provenance（OIDC，无需任何 token secret）→ 建 GitHub Release 并附 .tgz；main 推送与 PR 由 ci.yml 跑同一套测试与审计。
首次发布必须先手工做一次：npm 没有 pending publisher，包在 registry 上不存在时无法配置 Trusted Publisher（会得到误导性的 404 … is not in this registry）。顺序是：
# ① 手工首发（会要 2FA 或一个启用了 bypass-2fa 的 granular token）
npm login
npm publish --access public
# ② 到 npmjs.com 的包设置里配置 Trusted Publisher → GitHub Actions：
# 组织/用户 = cnkids 仓库 = dsh-session-reattach
# 工作流文件名 = release.yml
# 环境 = 留空（发布 job 不引用 environment，两边必须一致，否则 OIDC 声明不匹配）
# ③ 推仓库与 tag；首个 tag 会在「已存在同版本」时**跳过** npm 步骤并照常建 Release
git remote add origin git@github.com:cnkids/dsh-session-reattach.git
git push -u origin main
git tag v0.1.1 && git push origin v0.1.1
从下一个版本开始，trusted publishing 才真正接管：改 package.json 版本 → 同步本文件版本记录 → 提交 → git tag vX.Y.Z && git push origin vX.Y.Z，CI 直接发布（provenance 自动附带）。
三个容易踩的点（都是实测教训，不是理论）：
npm ci 需要 package-lock.json —— 本仓库零运行时依赖，所以 lockfile 很小，但必须有（poc8 会断言它在）。- Trusted Publishing 要求 npm ≥ 11.5.1，而 Node 22 自带 npm 10.x；版本不够时
npm publish 会返回误导性的 404。发布 job 因此固定 npm install -g npm@11.5.1。
- 发布 job 不引用受保护环境：
environment 的审批门在 GitHub 侧故障时会卡死发布；npm 侧的 Environment 也必须留空才能与之一致。发布靠 OIDC 短时令牌 + provenance 兜底。
版本记录
| 版本 | 变更 |
|---|
| 0.1.2 | 只改文档与仓库形态：安全审计产物（报告 + 8 条 PoC）移出仓库改为本地维护，README 不再指向仓库内路径、CI 取消审计步骤；测试夹具里的真实会话 id 换成合成 UUID。lib/ 无改动；相对 0.1.1，发布物只差 README 与版本号 |
| 0.1.1 | 安全审计落地：体积超限不再拆连接（413 必达）、路由加错误边界（宿主故障回可诊断的 JSON 500 而不是空 400）、会话数量截断如实上报（不再谎报「没有可归位的会话」）；完成安全审计（8 条 PoC：真 socket、真实 WorkspaceEntity、运行中宿主的守卫探测；产物不随仓库分发）；README 按 dsh-palimpsest 版式重排并补安全边界；用例 105 → 121 |
| 0.1.0 | 首个版本：宿主侧归位核心（realpath 同 canon 判定、五类分类、先 detach 后 attach）、HTTP 路由（复用 /api 守卫、默认 dry-run）、/reattach [apply] [subagents] 命令、浏览器半边拖拽落点（预筛高亮 + 提示条）、零运行时依赖 |
许可证
MIT
