@mzzsfy/dsh-context-manager 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # dsh-context-manager
 
-对话增强插件:历史输入回溯、插话撤回、对话分叉(家族版本切换/进行中轮分叉/自动重发)。dsh-session-manager 历史输入功能的独立延续包(原包已移除该功能)。
+对话增强插件:历史输入回溯、插话撤回、对话分叉(家族版本切换/进行中轮分叉/自动重发)、标题栏复制 sessionId。dsh-session-manager 历史输入功能的独立延续包(原包已移除该功能)。
 
 ## 功能
 
@@ -8,10 +8,10 @@
 
 输入框按 `Alt+↑` 唤起历史输入浮层:
 
-- 范围导航:`←/→` 切换 workspace / session / global / prompts 四范围,列表时间倒序
+- 范围导航:`←/→` 按 常用(prompts)→ 当前会话(session)→ 本工作区(workspace)→ 全部工作区(global) 依次切换(边界停住),列表时间倒序
 - 搜索:输入即时过滤(IME 组合输入守卫,命中计数),`↑/↓` 选中、`Enter` 回填
-- 回填经宿主公共契约 `inputActions.setDraft`;`Esc` 两级退出(编辑态 → 浮层)
-- 编辑态:收藏(`C`)/重命名/删除常用提示词,数据落全局 `prompts.json`,与自动历史互不覆写
+- 回填经宿主公共契约 `inputActions.setDraft`;`Esc` 两级退出(搜索词非空先清词,再按关闭浮层)
+- 列表行悬停星标收藏/取消常用提示词;常用范围内点「编辑」进入编辑态(重命名/删除/新增),数据落全局 `prompts.json`,与自动历史互不覆写
 
 数据链:Host 聚合工作区缓存(`~/.dsh/historyPrompt/`,产物解压 + stat 指纹增量对齐)→ `/api/context/inputs` → 浮层。
 
@@ -21,7 +21,7 @@
 
 ### 对话分叉(fork,重写式)
 
-用户输入气泡操作排的分叉按钮:分叉出新会话到该轮之前(该轮不带入子会话消息流),该轮的用户输入自动回填子会话输入框供编辑重发——与插话撤回同构,作用于 fork 场景,原会话不动。图标与官方分支按钮同源;官方「在新对话中分支」驻留轮尾操作排(分叉含该轮),两者语义互补、位置不重叠。
+用户输入气泡操作排的分叉按钮:分叉出新会话到该轮之前(该轮不带入子会话消息流),该轮的用户输入自动回填子会话输入框供编辑重发——与插话撤回同构,作用于 fork 场景,原会话消息流不动(进行中轮分叉会停止原会话该轮未完成的回复,见下)。图标与官方分支按钮同源;官方「在新对话中分支」驻留轮尾操作排(分叉含该轮),两者语义互补、位置不重叠。
 
 - 锚点:`remote.session.follow` 开场帧(回溯窗口 2000 事件)建轮号 → { 结束 seq, 该轮首问文本, open } 映射;重试轮 N 的分叉边界取轮 N-1 的 turn/end seq(宿主边界语义 inclusive,轮间切口合法)
 - 轮内插话不误取:文本取本轮首条携带非空文本的用户本人消息(文本块按行拼接),插件注入/纯图/空白轮不注入按钮
@@ -34,16 +34,25 @@
 
 用户输入气泡操作排的家族版本环:当前会话在同源分叉家族(parentSession 链)中的序位/成员数,`‹ ›` 在家族成员间直接跳转(`sessions.open`,纯切换不分叉)。
 
-- 家族判定:`sessions.list` 快照行的 `parentSessionId` 建链投影,断链视为独立根;单成员家族不注入
+- 家族判定:`sessions.list` 快照行的 `parentId` 建链投影(wire 形态字段名为 `parentSessionId`,客户端快照行映射为 `parentId`),断链视为独立根;单成员家族不注入
 - 零新 RPC:数据源为既有会话列表快照,环序按 `updatedAt` 升序(与分叉先后一致)
+- 启停:随「对话分叉」开关一并启停(环由同一 dock 注入),宿主缺 sessions.list 快照面不注入
+
+### 标题栏复制 sessionId
+
+会话标题栏(「标准模式」标签右侧)的复制按钮:点击复制当前会话 id 到剪贴板,便于粘贴给他人排查或脚本引用。
+
+- 平时隐藏(opacity 占位),鼠标悬停标题栏任意位置或键盘聚焦时显示;`prefers-reduced-motion` 下关闭过渡
+- 复制优先走 `navigator.clipboard.writeText`,非安全上下文(如 LAN http 访问)自动回退隐藏文本域 `execCommand`
+- 挂官方 `conversation.session.header.actions` 插槽,成功/失败均经 toast 反馈
 
 ## 启停
 
-设置页「插件」→「对话增强」卡片四开关(历史输入/插话撤回/对话分叉/分叉后自动重发),经宿主 settings 持久,变更刷新页面生效。浮层内 `S` 键或开关行亦可切换。
+设置页「插件」→「对话增强」卡片五开关(历史输入/插话撤回/对话分叉/分叉后自动重发/标题栏复制 sessionId),经宿主 settings 持久,变更刷新页面生效;家族版本环随「对话分叉」开关一并启停。
 
 ## 依赖与门控
 
-- 宿主服务经 inject 声明(`slots`/`sessions`/`workspaces`/`remote`/`remote.session` 点分声明),namespace 未就绪整体保持未激活(干净禁用)
+- client 半区宿主服务经 inject 声明(`slots`/`sessions`/`workspaces`/`remote`/`remote.session` 点分声明),namespace 未就绪整体保持未激活(干净禁用);host 半区 inject 为 `webServer`/`agents`/`sessionQuery`/`sessionPersistence`
 - 公共依赖 `@mzzsfy/dsh-toast` 可选消费(模块缺失通知通道置空)
 - 样式注入带 `data-plugin` 标记,开关为 `cx-switch` 形态(状态选择器锚定 `input[type="checkbox"]`)
 
@@ -57,5 +66,10 @@
 | `/api/context/steer-recall-enabled` | GET/POST | 插话撤回启停 |
 | `/api/context/fork-enabled` | GET/POST | 对话分叉启停 |
 | `/api/context/fork-auto-resend-enabled` | GET/POST | 分叉后自动重发启停 |
+| `/api/context/copy-sid-enabled` | GET/POST | 标题栏复制 sessionId 启停 |
+
+设计文档:仓库根 `docs/上下文管理插件设计.md`
+
+## dsh 版本兼容
 
-设计文档:`docs/上下文管理插件设计.md`
+三版本全部通过:样式注入 data-plugin 契约、Alt+↑ 历史浮层、对话 fork、设置「插件」页对话增强卡四开关、host 半区 API(history-enabled / fork-enabled)。0.1.6 设置分区卡片位于「插件」页,非独立导航项。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-context-manager",
   "description": "对话增强:历史输入浮层(范围导航/搜索/subagent排除)、常用提示词收藏、插话撤回、对话 fork(家族版本切换/进行中轮分叉/自动重发)",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -1,10 +1,12 @@
-// dsh-context-manager Client 半区:「插件」设置页可配置卡片(四启停开关)
-// + 历史输入浮层(Alt+↑ 唤起,范围导航/搜索/收藏回填) + 插话撤回 + 对话 fork。
+// dsh-context-manager Client 半区:「插件」设置页可配置卡片(五启停开关)
+// + 历史输入浮层(Alt+↑ 唤起,范围导航/搜索/收藏回填) + 插话撤回 + 对话 fork
+// + 标题栏复制 sessionId(悬停显隐)。
 // 历史输入挂官方 conversation.input.dock 插槽(渲染为零高度锚点),回填走宿主公共
 // 契约 inputActions.setDraft;插话撤回注入官方 pending steering 气泡操作图标排;
 // fork 注入消息气泡操作排,分叉到该轮之前并把该轮用户输入回填子会话输入框(重试
 // 语义),RPC 走宿主 sessions 服务面(fork+open),锚点经 remote.session.follow
-// 开场帧建立轮号→{ 结束 seq, 首问文本 } 映射。浏览器半区经 webServer 路由
+// 开场帧建立轮号→{ 结束 seq, 首问文本 } 映射;复制 sessionId 挂官方
+// conversation.session.header.actions 插槽。浏览器半区经 webServer 路由
 // ('/api/context/*')访问 Host。打包为单文件自包含格式,无法跨文件 require;
 // 与 src/core.mjs 镜像的纯函数(filterHistoryInputs/forkFailureText/forkRetryText)
 // 修改需两处同步。
@@ -140,6 +142,18 @@ const CSS = [
   // dock 本体零 DOM,仅承载注入逻辑
   '.cx-steer-host { display:none; }',
   '.cx-fork-host { display:none; }',
+  // 标题栏复制 sessionId:与官方 icon 按钮同尺寸,默认隐藏(opacity 保占位,
+  // 隐形盒自身仍可悬停/聚焦),悬停标题栏任一位置或按钮自身/键盘聚焦时显示;
+  // 宿主 CSS module 类名带哈希前缀但名称后缀稳定,子串选择器跨构建匹配,
+  // :has 不可用时自身悬停兜底
+  '.cx-sid { appearance:none; border:0; background:transparent; cursor:pointer; flex:none;',
+  '  display:inline-flex; align-items:center; justify-content:center; width:24px; height:24px; padding:0;',
+  '  border-radius:6px; color:var(--dsw-alias-label-tertiary, rgba(127,127,127,.9));',
+  '  opacity:0; transition:opacity .15s, color .15s; }',
+  '.cx-sid:hover, .cx-sid:focus-visible { opacity:1; color:var(--dsw-alias-label-primary, inherit); }',
+  '.cx-sid:focus-visible { outline:2px solid #1677ff; outline-offset:1px; }',
+  '[class*="_header"]:has(.cx-sid):hover .cx-sid, [class*="_header"]:has(.cx-sid):focus-within .cx-sid { opacity:1; }',
+  '@media (prefers-reduced-motion: reduce) { .cx-sid { transition:none; } }',
 ].join('\n')
 
 const INPUTS_URL = '/api/context/inputs'
@@ -148,6 +162,7 @@ const HISTORY_ENABLED_URL = '/api/context/history-enabled'
 const STEER_ENABLED_URL = '/api/context/steer-recall-enabled'
 const FORK_ENABLED_URL = '/api/context/fork-enabled'
 const FORK_AUTO_RESEND_URL = '/api/context/fork-auto-resend-enabled'
+const COPY_SID_ENABLED_URL = '/api/context/copy-sid-enabled'
 
 // 请求默认超时:host 被批量解压等同步任务阻塞时路由会迟滞数秒,
 // 无超时则浮层停在「正在读取…」假死;超时按错误抛出,由调用方兜底,
@@ -1128,6 +1143,62 @@ const HISTORY_SWITCH_TITLE = '在输入框按 Alt+↑ 唤起历史输入浮层,
 const STEER_SWITCH_TITLE = '插话发送后、尚未被智能体应用期间,在该插话气泡的操作图标排显示撤回按钮,点击撤回并把原文填回输入框(覆盖输入框现有草稿);含附件的插话不可撤回;消息被应用后按钮随气泡消失,恰在应用瞬间点击会提示已应用且不动草稿。停用即不再注入,刷新页面生效。'
 const FORK_SWITCH_TITLE = '消息气泡操作排显示分叉按钮,点击分叉出新会话到该轮之前(该轮不带入子会话),该轮的用户输入自动回填子会话输入框供编辑重发,子会话自动打开且标题尾号递增;进行中的轮(回复尚未完成)同样可分叉,分叉后自动停止本会话该轮未完成的回复;首轮(无更早上下文可继承,新建会话即为同义操作)与无文本输入的轮(纯图等,无从重发)不注入;停用即不再注入,刷新页面生效。'
 const FORK_AUTO_RESEND_SWITCH_TITLE = '分叉成功后自动把该轮原输入发送到子会话立即开跑(重生成语义,相当于原输入重跑一遍);关闭时分叉仅把原输入回填子会话输入框,由你编辑后再手动发送。'
+const COPY_SID_SWITCH_TITLE = '会话标题栏显示复制 sessionId 按钮,平时隐藏,鼠标移到标题栏任意位置时显示,点击复制当前会话 id 到剪贴板(便于粘贴给他人排查或脚本引用);关闭后按钮整体不渲染,刷新页面生效。'
+
+// 复制动作(纯函数,剪贴板与文档依赖注入):clipboard.writeText 优先,缺失或
+// 抛错(LAN http 非安全上下文无 navigator.clipboard)回退隐藏文本域 execCommand;
+// 全部失败返回 false,由调用方 toast 反馈
+async function copySidText(text, clipboard, doc) {
+  if (clipboard && typeof clipboard.writeText === 'function') {
+    try {
+      await clipboard.writeText(text)
+      return true
+    } catch {
+      // 非安全上下文拒绝等,落回退路径
+    }
+  }
+  try {
+    const area = doc.createElement('textarea')
+    area.value = text
+    area.setAttribute('readonly', '')
+    area.style.position = 'fixed'
+    area.style.opacity = '0'
+    doc.body.appendChild(area)
+    try {
+      area.select()
+      return doc.execCommand('copy') === true
+    } finally {
+      // 含会话 id 的临时节点必须无条件清理,异常路径不得残留 DOM
+      area.remove()
+    }
+  } catch {
+    return false
+  }
+}
+
+// 标题栏复制 sessionId 按钮:挂官方 conversation.session.header.actions 插槽
+// (标准模式标签右侧,sessionId 由插槽 standardProps 下发),开关停用即整体
+// 不渲染;启停读取失败按启用兜底(与 HistoryDock/switchRow 一致)
+function CopySidButton({ sessionId }) {
+  const [enabled, setEnabled] = useState(true)
+  useEffect(() => {
+    api(COPY_SID_ENABLED_URL)
+      .then((payload) => setEnabled(payload ? payload.enabled !== false : true))
+      .catch(() => {})
+  }, [])
+  if (!sessionId || !enabled) return null
+  // copySidText 为 async 函数(内部全路径吞异常),必 resolve,失败以 false 表达
+  const copy = () => {
+    copySidText(sessionId, navigator.clipboard, document)
+      .then((ok) => toast(ok ? '已复制 sessionId' : '复制失败', ok ? undefined : { kind: 'error' }))
+  }
+  return h('button', { type: 'button', className: 'cx-sid', title: '复制 sessionId', 'aria-label': '复制 sessionId', onClick: copy },
+    h('svg', { width: 14, height: 14, viewBox: '0 0 16 16', fill: 'none', 'aria-hidden': 'true' },
+      h('rect', { x: 5.75, y: 5.75, width: 7.5, height: 7.5, rx: 1.5, stroke: 'currentColor', 'stroke-width': '1.2' }),
+      h('path', { d: 'M10.25 3.25H4.25a1.5 1.5 0 0 0-1.5 1.5v6', stroke: 'currentColor', 'stroke-width': '1.2', 'stroke-linecap': 'round' }),
+    ),
+  )
+}
 
 // 启停开关行工厂:三个开关同构(受控 checkbox + cx-switch 形态),值存宿主 settings,
 // 切换经本插件路由中转,变更刷新页面生效
@@ -1166,6 +1237,7 @@ const HistorySwitchRow = switchRow(HISTORY_ENABLED_URL, '历史输入浮层(Alt+
 const SteerSwitchRow = switchRow(STEER_ENABLED_URL, '插话撤回', STEER_SWITCH_TITLE, '插话撤回')
 const ForkSwitchRow = switchRow(FORK_ENABLED_URL, '对话 fork', FORK_SWITCH_TITLE, '对话 fork')
 const ForkAutoResendSwitchRow = switchRow(FORK_AUTO_RESEND_URL, '分叉后自动重发', FORK_AUTO_RESEND_SWITCH_TITLE, '分叉后自动重发')
+const CopySidSwitchRow = switchRow(COPY_SID_ENABLED_URL, '标题栏复制 sessionId', COPY_SID_SWITCH_TITLE, '标题栏复制 sessionId')
 
 // 「插件」设置页卡片:与官方 PluginCard 同款折叠卡(header 展开/收起 + body),
 // 视觉值取自宿主实测(见 CSS 注释),组件因缺宿主 i18n/表单状态而自绘
@@ -1189,6 +1261,7 @@ function ContextPanel() {
       h(SteerSwitchRow),
       h(ForkSwitchRow),
       h(ForkAutoResendSwitchRow),
+      h(CopySidSwitchRow),
     ),
   )
 }
@@ -1354,6 +1427,20 @@ function ContextPanel() {
             console.warn('[context-manager] 对话 fork 入口未注册(宿主无 conversation.input.dock 插槽)', error)
           }
         }
+
+        // 标题栏复制 sessionId 入口:官方 conversation.session.header.actions 插槽
+        // (list,order -9 紧随官方 agent-preset 标签 -10,即「标准模式」右侧);
+        // sessionId 由该插槽 standardProps 自动下发(与官方 agent-preset 标签同源),
+        // 组件缺失时自行判空不渲染。宿主缺该插槽时仅禁用本功能,不阻塞其余能力
+        try {
+          ctx.slots.inject('conversation.session.header.actions', () =>
+            ctx.slots.register(
+              { name: 'conversation.session.header.actions', id: 'context-manager-copy-sid', order: -9 },
+              CopySidButton,
+            ))
+        } catch (error) {
+          console.warn('[context-manager] 复制 sessionId 入口未注册(宿主无 conversation.session.header.actions 插槽)', error)
+        }
       },
     }
   },

package/src/index.js

@@ -1,5 +1,6 @@
-// dsh-context-manager Host 半区:历史输入工作区缓存对齐 + 五条路由
-// (inputs / prompts/toggle / history-enabled / steer-recall-enabled / fork-enabled)。
+// dsh-context-manager Host 半区:历史输入工作区缓存对齐 + 启停/数据路由
+// (inputs / prompts/toggle 与 history/steer-recall/fork/fork-auto-resend/copy-sid
+// 五条启停)。
 // 浮层请求直接读缓存文件立即返回;对齐在后台解压范围内会话产物与缓存合并写回,
 // 运行中会话也参与(实时追加其新输入)。fork 分叉动作走 client 服务面,
 // host 侧只有其启停路由。
@@ -53,6 +54,8 @@ const SETTINGS_SCHEMA = schemastery.object({
     .description('消息气泡操作排的分叉按钮,关闭后按钮整体不渲染;变更刷新页面生效'),
   forkAutoResendEnabled: schemastery.boolean().default(false)
     .description('分叉成功后自动把该轮原输入发送到子会话(重生成语义);关闭时仅回填子会话输入框供编辑重发'),
+  copySidEnabled: schemastery.boolean().default(true)
+    .description('会话标题栏的复制 sessionId 按钮,平时隐藏,鼠标悬停标题栏时显示,点击复制当前会话 id;关闭后按钮整体不渲染;变更刷新页面生效'),
 })
 
 function sendJson(res, status, payload) {
@@ -79,6 +82,7 @@ function readSettings(ctx) {
     steerRecallEnabled: !value || value.steerRecallEnabled !== false,
     forkEnabled: !value || value.forkEnabled !== false,
     forkAutoResendEnabled: Boolean(value && value.forkAutoResendEnabled === true),
+    copySidEnabled: !value || value.copySidEnabled !== false,
   }
 }
 
@@ -539,6 +543,31 @@ export function apply(ctx, config) {
         }
       },
     },
+    {
+      // 标题栏复制 sessionId 启停:与历史浮层开关同构,读走 settings,写经 settings.update
+      path: '/api/context/copy-sid-enabled',
+      handler: async (req, res) => {
+        try {
+          if (req.method === 'GET') {
+            sendJson(res, 200, { enabled: readSettings(ctx).copySidEnabled })
+            return
+          }
+          if (!rejectMethod(req, res, 'POST')) return
+          let body
+          try {
+            body = JSON.parse(await readBody(req))
+          } catch {
+            throw new Error(MESSAGES.badJsonBody)
+          }
+          const settings = ctx.get('settings')
+          if (!settings) throw new Error('宿主设置服务不可用')
+          await settings.update(NAMESPACE, { copySidEnabled: Boolean(body && body.enabled) })
+          sendJson(res, 200, { enabled: readSettings(ctx).copySidEnabled })
+        } catch (error) {
+          respondError(ctx, res, error)
+        }
+      },
+    },
   ]
 
   for (const route of routes) {

package/test/client-copy-sid.test.mjs

@@ -0,0 +1,252 @@
+// 标题栏复制 sessionId:接线与门控测试。加载真实 src/client.js,断言 header.actions
+// 插槽注册、inject 契约、开关门控(停用不渲染)与复制动作(toast 反馈);
+// 复制本体 copySidText 为纯函数切片(剪贴板/文档依赖注入)。
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const CLIENT_SRC = readFileSync(join(PKG_ROOT, 'src', 'client.js'), 'utf8')
+
+// fetch 桩:按 URL 返回预设 payload;未预设的 URL 抛错(暴露意外请求)
+function withFetchStub(routes, run) {
+  const original = globalThis.fetch
+  globalThis.fetch = async (url) => {
+    const hit = routes.find((route) => String(url).startsWith(route.path))
+    if (!hit) throw new Error('意外请求: ' + String(url))
+    if (hit.reject) throw new Error('network down')
+    return { ok: true, status: 200, json: async () => hit.body }
+  }
+  return Promise.resolve()
+    .then(run)
+    .finally(() => { globalThis.fetch = original })
+}
+
+// client.js 装载:react 桩为可驱动微型模拟(useState 槽位 / useEffect 收集 /
+// createElement 记录),apply 后返回捕获的插槽注册表
+function loadClientHarness({ documentStub } = {}) {
+  const modules = []
+  const registered = []
+  const toasts = []
+  const elements = []
+  const hookSlots = []
+  const effects = []
+  // hook 游标:每次渲染前置 0,useState 按调用序读写槽位(模拟 React hook 链)
+  let hookCursor = 0
+  const reactStub = {
+    useState: (init) => {
+      let cell = hookSlots[hookCursor]
+      if (!cell) {
+        cell = { value: init }
+        hookSlots[hookCursor] = cell
+      }
+      hookCursor += 1
+      return [cell.value, (next) => { cell.value = typeof next === 'function' ? next(cell.value) : next }]
+    },
+    useEffect: (fn) => { effects.push(fn) },
+    useRef: (value) => ({ current: value }),
+    createElement: (type, props, ...children) => {
+      const element = { type, props: props || {}, children }
+      elements.push(element)
+      return element
+    },
+  }
+  const requireStub = (name) => {
+    if (name === '@mzzsfy/dsh-toast/client') return { show: (text, opts) => toasts.push({ text, opts }) }
+    return reactStub
+  }
+  const document = documentStub || {
+    createElement: () => ({ style: {}, remove() {} }),
+    head: { appendChild: () => {} },
+    body: { appendChild: () => {} },
+  }
+  const factory = new Function('window', 'require', 'document', CLIENT_SRC + '\n;return null')
+  factory({ __ModuleLoader__: { load: (module) => modules.push(module) }, addEventListener: () => {} }, requireStub, document)
+  assert.equal(modules.length, 1, 'client.js 模块未被捕获')
+  const mod = modules[0].factory(requireStub)
+  const sessions = { binding: () => undefined, fork: () => Promise.resolve('child-1'), open: () => {} }
+  const ctx = {
+    get: (name) => (name === 'sessions' ? sessions : {}),
+    effect: () => {},
+    slots: {
+      inject: (name, register) => register(),
+      register: (options, component) => registered.push({ options, component }),
+    },
+    remote: { session: { follow: () => (async function* () { yield { type: 'snapshot', cursor: 0, records: [] }; await new Promise(() => {}) })() } },
+  }
+  mod.apply(ctx)
+  return {
+    registered,
+    toasts,
+    // 首渲染:清空 hook 槽位与效果队列后跑组件(全新挂载);效果同步执行
+    render(component, props) {
+      effects.length = 0
+      elements.length = 0
+      hookSlots.length = 0
+      hookCursor = 0
+      const output = component(props)
+      for (const effect of effects.splice(0)) effect()
+      return output
+    },
+    // 重渲染:保留 hook 槽位(setter 已写入的状态生效),不重跑效果——忠实
+    // React 空 deps effect 只跑一次的语义
+    rerender(component, props) {
+      elements.length = 0
+      hookCursor = 0
+      return component(props)
+    },
+    async settle() { await new Promise((resolve) => setTimeout(resolve, 0)) },
+  }
+}
+
+function findCopySidEntry(harness) {
+  const entry = harness.registered.find((item) => item.options.id === 'context-manager-copy-sid')
+  assert.ok(entry, '未注册 id=context-manager-copy-sid 的标题栏条目')
+  return entry
+}
+
+test('Given client.js 装载, When apply, Then header.actions 注册复制条目', () => {
+  const harness = loadClientHarness()
+  const entry = findCopySidEntry(harness)
+  assert.equal(entry.options.name, 'conversation.session.header.actions', '应注册进标题栏 actions 插槽')
+  assert.equal(entry.options.order, -9, '应紧随官方 agent-preset 标签(-10)之后')
+  assert.equal(typeof entry.component, 'function', '条目缺组件')
+  assert.equal(entry.options.inject, undefined, 'sessionId 由插槽 standardProps 下发,不需 inject')
+})
+
+test('Given 开关启用, When 渲染, Then 渲染 cx-sid 复制按钮', async () => {
+  const harness = loadClientHarness()
+  const { component } = findCopySidEntry(harness)
+  let output
+  await withFetchStub([{ path: '/api/context/copy-sid-enabled', body: { enabled: true } }], async () => {
+    output = harness.render(component, { sessionId: 's1' })
+    await harness.settle()
+  })
+  output = harness.rerender(component, { sessionId: 's1' })
+  assert.equal(output.type, 'button', '启用时应渲染按钮')
+  assert.equal(output.props.className, 'cx-sid')
+  assert.equal(output.props.title, '复制 sessionId')
+  assert.equal(output.props['aria-label'], '复制 sessionId')
+})
+
+test('Given 开关停用, When 渲染, Then 不渲染(整体 null)', async () => {
+  const harness = loadClientHarness()
+  const { component } = findCopySidEntry(harness)
+  let output
+  await withFetchStub([{ path: '/api/context/copy-sid-enabled', body: { enabled: false } }], async () => {
+    output = harness.render(component, { sessionId: 's1' })
+    await harness.settle()
+  })
+  output = harness.rerender(component, { sessionId: 's1' })
+  assert.equal(output, null, '停用后按钮整体不渲染')
+})
+
+test('Given 启停读取失败, When 渲染, Then 按启用兜底(fail-open,与既有开关一致)', async () => {
+  const harness = loadClientHarness()
+  const { component } = findCopySidEntry(harness)
+  await withFetchStub([{ path: '/api/context/copy-sid-enabled', reject: true }], async () => {
+    harness.render(component, { sessionId: 's1' })
+    await harness.settle()
+  })
+  const output = harness.rerender(component, { sessionId: 's1' })
+  assert.equal(output.type, 'button', '读取失败应按启用兜底')
+})
+
+test('Given 无 sessionId, When 渲染, Then 不渲染', () => {
+  const harness = loadClientHarness()
+  const { component } = findCopySidEntry(harness)
+  const output = harness.render(component, {})
+  assert.equal(output, null, '无会话 id 应不渲染')
+})
+
+// ── 纯函数切片:copySidText(剪贴板优先,execCommand 回退) ──
+
+const PURE_START = CLIENT_SRC.indexOf('async function copySidText(')
+const PURE_END = CLIENT_SRC.indexOf('function CopySidButton(')
+assert.ok(PURE_START >= 0 && PURE_END > PURE_START, 'client.js copySidText 切片定位失败')
+const { copySidText } = new Function(CLIENT_SRC.slice(PURE_START, PURE_END) + '; return { copySidText }')()
+
+const FAKE_DOC = (execResult, execThrows) => {
+  const appended = []
+  return {
+    appended,
+    createElement: () => ({ style: {}, value: '', setAttribute() {}, select() {}, remove() { appended.push('removed') } }),
+    body: { appendChild: (node) => appended.push(node) },
+    execCommand: () => { if (execThrows) throw new Error('exec down'); return execResult },
+  }
+}
+
+test('copySidText:clipboard.writeText 可用即成功', async () => {
+  const writes = []
+  const done = await copySidText('s1', { writeText: async (text) => { writes.push(text) } }, FAKE_DOC(true))
+  assert.equal(done, true)
+  assert.deepEqual(writes, ['s1'])
+})
+
+test('copySidText:writeText 抛错回退 execCommand 成功', async () => {
+  const doc = FAKE_DOC(true)
+  const done = await copySidText('s1', { writeText: async () => { throw new Error('denied') } }, doc)
+  assert.equal(done, true)
+  // 临时文本域被 append 且随后移除(无残留)
+  assert.equal(doc.appended.filter((node) => typeof node === 'string' && node === 'removed').length, 1, '回退路径应清理临时文本域')
+  assert.equal(doc.appended.length, 2, 'append 后必须紧跟 remove')
+})
+
+test('copySidText:无 clipboard 时走 execCommand 回退', async () => {
+  assert.equal(await copySidText('s1', undefined, FAKE_DOC(true)), true)
+  assert.equal(await copySidText('s1', undefined, FAKE_DOC(false)), false)
+  const throwing = FAKE_DOC(null, true)
+  assert.equal(await copySidText('s1', undefined, throwing), false)
+  // finally 清理语义:execCommand 抛错路径临时节点同样必须移除,不得残留 DOM
+  assert.deepEqual(
+    throwing.appended.filter((entry) => entry === 'removed').length,
+    throwing.appended.filter((entry) => typeof entry !== 'string').length,
+    '每个 append 的临时节点都必须紧跟一次 remove',
+  )
+})
+
+// ── 点击动作:toast 反馈 ──
+
+test('Given 点击按钮, When 复制成功, Then toast 已复制 sessionId', async () => {
+  const harness = loadClientHarness({ documentStub: FAKE_DOC(true) })
+  const { component } = findCopySidEntry(harness)
+  let output
+  await withFetchStub([{ path: '/api/context/copy-sid-enabled', body: { enabled: true } }], async () => {
+    output = harness.render(component, { sessionId: 's1' })
+    await harness.settle()
+  })
+  output = harness.rerender(component, { sessionId: 's1' })
+  output.props.onClick()
+  await harness.settle()
+  assert.deepEqual(harness.toasts, [{ text: '已复制 sessionId', opts: undefined }])
+})
+
+test('Given 点击按钮, When 复制失败, Then toast 复制失败(error)且不误报成功', async () => {
+  const harness = loadClientHarness({ documentStub: FAKE_DOC(false) })
+  const { component } = findCopySidEntry(harness)
+  let output
+  await withFetchStub([{ path: '/api/context/copy-sid-enabled', body: { enabled: true } }], async () => {
+    output = harness.render(component, { sessionId: 's1' })
+    await harness.settle()
+  })
+  output = harness.rerender(component, { sessionId: 's1' })
+  output.props.onClick()
+  await harness.settle()
+  assert.deepEqual(harness.toasts, [{ text: '复制失败', opts: { kind: 'error' } }])
+})
+
+// ── 源码契约:显隐 CSS 与设置卡开关行 ──
+
+test('CSS 显隐契约:默认隐藏,整行悬停/自身悬停/键盘聚焦显示,reduced-motion 关过渡', () => {
+  assert.match(CLIENT_SRC, /\.cx-sid \{[^}]*opacity:0/, '按钮默认必须隐藏')
+  assert.match(CLIENT_SRC, /\[class\*="_header"\]:has\(\.cx-sid\):hover \.cx-sid/, '标题栏整行悬停应显示按钮')
+  assert.match(CLIENT_SRC, /\.cx-sid:hover, \.cx-sid:focus-visible \{ opacity:1/, '自身悬停与键盘聚焦必须兜底显示')
+  assert.match(CLIENT_SRC, /@media \(prefers-reduced-motion: reduce\) \{ \.cx-sid \{ transition:none/, 'reduced-motion 应关闭过渡')
+})
+
+test('设置卡契约:第五开关行走 switchRow 工厂,挂 copy-sid-enabled 路由', () => {
+  assert.ok(CLIENT_SRC.includes("switchRow(COPY_SID_ENABLED_URL, '标题栏复制 sessionId'"), '设置卡缺复制 sessionId 开关行')
+  assert.ok(CLIENT_SRC.includes('h(CopySidSwitchRow)'), 'ContextPanel 未挂载第五开关行')
+})

package/test/index.test.mjs

@@ -661,12 +661,12 @@ test('常用提示词:超长截断、上限裁剪、空 text 拒绝', skipMissin
 
 // ── 路由层横切守卫:方法白名单 / JSON 体 / 系统级错误收敛 / 非字符串 text ──
 
-test('横切守卫:5 条路由方法白名单,白名单外一律 405', skipMissingDeps, async () => {
+test('横切守卫:6 条路由方法白名单,白名单外一律 405', skipMissingDeps, async () => {
   await withHistoryCacheDir(async () => {
     const { handlers } = makeCtx({ headers: [{ id: 's1', cwd: 'C:\\x', createdAt: 0 }], agents: new Map() })
     const getOnly = '/api/context/inputs'
     const postOnly = '/api/context/prompts/toggle'
-    const dualMethods = ['/api/context/history-enabled', '/api/context/steer-recall-enabled', '/api/context/fork-enabled']
+    const dualMethods = ['/api/context/history-enabled', '/api/context/steer-recall-enabled', '/api/context/fork-enabled', '/api/context/copy-sid-enabled']
     // GET-only 路由:POST 拒绝
     const inputsPost = response()
     await handlers.get(getOnly)(request('s1'), inputsPost)
@@ -684,10 +684,10 @@ test('横切守卫:5 条路由方法白名单,白名单外一律 405', skipMissi
   })
 })
 
-test('横切守卫:4 条 POST 路由的非法 JSON 请求体统一 400(badJsonBody)', skipMissingDeps, async () => {
+test('横切守卫:5 条 POST 路由的非法 JSON 请求体统一 400(badJsonBody)', skipMissingDeps, async () => {
   await withHistoryCacheDir(async () => {
     const { handlers } = makeCtx({ headers: [{ id: 's1', cwd: 'C:\\x', createdAt: 0 }], agents: new Map() })
-    const postPaths = ['/api/context/prompts/toggle', '/api/context/history-enabled', '/api/context/steer-recall-enabled', '/api/context/fork-enabled']
+    const postPaths = ['/api/context/prompts/toggle', '/api/context/history-enabled', '/api/context/steer-recall-enabled', '/api/context/fork-enabled', '/api/context/copy-sid-enabled']
     for (const routePath of postPaths) {
       const res = await postRaw(handlers, routePath, '{oops')
       assert.equal(res.status, 400, routePath + ' 非法 JSON 应回 400')
@@ -788,3 +788,19 @@ test('fork 启停:GET 默认启用,POST 切换经 settings 持久,GET 反映新
   await handlers.get('/api/context/fork-enabled')(getRequest2('/api/context/fork-enabled', 'GET'), restored)
   assert.equal(restored.body.enabled, true)
 })
+
+test('标题栏复制 sessionId 启停:GET 默认启用,POST 切换经 settings 持久,GET 反映新值', skipMissingDeps, async () => {
+  const { handlers } = makeCtx({ headers: [{ id: 's1', cwd: 'C:\\x', createdAt: 0 }], agents: new Map() })
+  const initial = response()
+  await handlers.get('/api/context/copy-sid-enabled')(getRequest2('/api/context/copy-sid-enabled', 'GET'), initial)
+  assert.equal(initial.body.enabled, true, '默认启用')
+  const off = await postJson(handlers, '/api/context/copy-sid-enabled', { enabled: false })
+  assert.equal(off.body.enabled, false)
+  const reread = response()
+  await handlers.get('/api/context/copy-sid-enabled')(getRequest2('/api/context/copy-sid-enabled', 'GET'), reread)
+  assert.equal(reread.body.enabled, false, 'settings 持久化关闭态')
+  await postJson(handlers, '/api/context/copy-sid-enabled', { enabled: true })
+  const restored = response()
+  await handlers.get('/api/context/copy-sid-enabled')(getRequest2('/api/context/copy-sid-enabled', 'GET'), restored)
+  assert.equal(restored.body.enabled, true)
+})