@gavinc-cn/touchstone-dsh 0.1.0 → 0.2.0

package/dsh-plugin/src/client.js

@@ -105,20 +105,103 @@ function toggleByKey(e) {
 /** 宿主页 keydown 监听体(capture 阶段; 函数引用稳定, 便于 dispose 时精确解绑)。 */
 function onHostKey(e) { toggleByKey(e); }
 
+// ── 侧栏入口按钮的配色与几何(2026-10-09 修) ──────────────────────────────────
+// 血案: 原先写 color:'var(--dsw-alias-text-l1, #e8e8e8)' —— dsh **没有** text-l1 这族
+// token(真实族是 --dsw-alias-label-primary/secondary/tertiary/caption/dimmed), var() 取不到
+// 就一直吃 fallback: 浅色档在 #f9fafb 的侧栏底上画 #e8e8e8 的字(实测对比度 1.17, 同排的
+// 「插件」「设置」是 18.08), 只有深色档碰巧能看。教训: 引用宿主 token 一律先核实名字。
+// 现行口径(明暗两档都跟宿主走):
+//   · 颜色**只取 dsh 语义 token 且不写死 fallback** —— token 缺席时该声明失效并回落到继承
+//     (侧栏根 .hHd-Xa_root 已设 label-primary), 而不是钉死一个只对某一档成立的灰;
+//   · 尺寸/圆角/gap/行高逐条对齐 dsh 自己的 .SidebarRoot_panelRow(min-height 36 / 内边距
+//     7px 8px / margin 0 2px / gap 8 / line-height 22 / --dsw-radius-md), 收起态对齐
+//     .hHd-Xa_collapsed .panelRow(36x36 居中);
+//   · 图标盒 16x16 —— 与 dsh 侧栏 SVG 图标同尺寸; 文字继承侧栏根的 14px。
+const ENTRY_TITLE = 'Touchstone 测试平台（Alt+T 开关）';
+const ENTRY_GLYPH_STYLE = {
+  flex: '0 0 16px', width: 16, height: 16, display: 'inline-flex',
+  alignItems: 'center', justifyContent: 'center', fontSize: 16, lineHeight: '16px',
+};
+const ENTRY_LABEL_STYLE = {
+  minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
+};
+
+// 交互态样式(悬停/开合/键盘聚焦环): 伪类没法写在 inline style 里, 落一张最小样式表。
+// 取值逐条对齐 dsh 侧栏行(.hHd-Xa_panelRow:hover 与 :focus-visible)。
+const ENTRY_CSS = [
+  '.ts-sb-entry{background:transparent}',
+  '.ts-sb-entry:hover,.ts-sb-entry.ts-sb-on{background:'
+    + 'var(--dsw-alias-interactive-bg-hover,color-mix(in srgb,currentColor 8%,transparent))}',
+  '.ts-sb-entry:focus-visible{outline-width:var(--dsw-focus-ring-width,2px);outline-style:solid;'
+    + 'outline-color:var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary));'
+    + 'outline-offset:-2px}',
+].join('');
+const ENTRY_CSS_ID = 'touchstone/sidebar-entry.css';
+
+/** 幂等挂上入口行交互态样式表(形态与 dsh 插件自身的注入方式一致)。
+ *  **失败一律吞掉**: 挂不上只是少了悬停/聚焦环的观感, 绝不能让侧栏入口或面板受影响
+ *  (桩 DOM 自检环境里 document 面本就不全, 真机异常同理)。
+ * @returns 摘除函数(插件卸载时调用; 已存在/挂不上时返回空操作)。 */
+function mountEntryStyle() {
+  try {
+    if (typeof document === 'undefined' || !document.head
+        || typeof document.createElement !== 'function'
+        || typeof document.querySelector !== 'function') {
+      return () => {};
+    }
+    if (document.querySelector('style[data-plugin-css=' + JSON.stringify(ENTRY_CSS_ID) + ']')) {
+      return () => {};
+    }
+    const tag = document.createElement('style');
+    tag.dataset.plugin = 'touchstone';
+    tag.dataset.pluginCss = ENTRY_CSS_ID;
+    tag.textContent = ENTRY_CSS;
+    document.head.appendChild(tag);
+    return () => tag.remove();
+  } catch (error) {
+    console.warn('[touchstone] 侧栏入口样式注入失败（只影响悬停/聚焦观感）:', error);
+    return () => {};
+  }
+}
+
 // 侧栏入口按钮(footer.action 槽; wide=侧栏展开态显示文字)
 function Toggle(props) {
-  const wide = props && props.wide;
+  const wide = !!(props && props.wide);
   const isOpen = useOpen();
+  const style = {
+    boxSizing: 'border-box', display: 'flex', alignItems: 'center',
+    border: 'none', cursor: 'pointer', textAlign: 'left',
+    color: 'var(--dsw-alias-label-primary)', // 无 fallback: 取不到即回落继承(见上注)
+    borderRadius: 'var(--dsw-radius-md, 8px)',
+    fontSize: 'inherit', // 侧栏根是 14px, 不再自带 13px
+  };
+  if (wide) {
+    style.gap = 8;
+    style.margin = '0 2px';
+    style.padding = '7px 8px';
+    style.minHeight = 36;
+    style.lineHeight = '22px';
+    style.flex = '1 1 auto';
+    style.minWidth = 0;
+  } else {
+    style.width = 36;
+    style.height = 36;
+    style.margin = 0;
+    style.padding = 0;
+    style.flex = 'none';
+    style.justifyContent = 'center';
+  }
   return h('button', {
-    style: {
-      display: 'flex', alignItems: 'center', gap: 6, width: '100%', boxSizing: 'border-box',
-      padding: '6px 12px', margin: '2px 0', borderRadius: 8, cursor: 'pointer', border: 'none',
-      color: 'var(--dsw-alias-text-l1, #e8e8e8)', fontSize: 13, textAlign: 'left',
-      background: 'transparent',
-    },
-    title: 'Touchstone 测试平台（Alt+T 开关）',
+    type: 'button',
+    className: 'ts-sb-entry' + (isOpen ? ' ts-sb-on' : ''),
+    style,
+    title: ENTRY_TITLE,
+    'aria-label': ENTRY_TITLE,
+    'aria-expanded': isOpen,
     onClick: () => setOpen(!isOpen),
-  }, wide ? (isOpen ? '🧪 关闭 Touchstone' : '🧪 Touchstone') : '🧪');
+  },
+  h('span', { style: ENTRY_GLYPH_STYLE, 'aria-hidden': 'true' }, '🧪'),
+  wide ? h('span', { style: ENTRY_LABEL_STYLE }, isOpen ? '关闭 Touchstone' : 'Touchstone') : null);
 }
 
 // 关闭按钮自动隐藏(2026-10-03): 常显会盖住被嵌 SPA 侧栏底部的用户名, 所以平时完全隐藏,
@@ -330,6 +413,8 @@ function Panel() {
 
 // cordis 客户端插件入口: 等 slots 服务就位后注册两个 UI 槽, 再挂快捷键
 function apply(ctx) {
+  // 侧栏入口的交互态样式表(悬停/开合/聚焦环), 与本插件同生命周期
+  ctx.effect(() => mountEntryStyle(), 'touchstone: 侧栏入口样式');
   const slots = ctx.get('slots');
   if (!slots) return;
   slots.inject('sidebar.footer.action', () => slots.register(

package/dshdriver.py

@@ -143,9 +143,30 @@ def available(timeout=HEALTH_TIMEOUT):
         return False
 
 
+def live_snapshot(timeout=10):
+    """`/live` 的**原始响应**：`{sessions: [...], complete?: bool}`。
+
+    `complete`（A 批 2026-10-08 起真插件会上报）＝插件是否已枚举宿主已有会话：
+    只有它为 true，**空表**才具备「宿主里确实没有会话」的语义（见 dshevents._align）。
+    旧装机副本没有该字段 ⇒ `complete` 缺省按未声明处理（空表＝未知）。
+
+    为什么单列一个读口（2026-10-08 修正）：`live()` 返回的是**行表**（历史调用点
+    server.py 直接迭代），而中枢对齐需要「行表 + 完整性声明」两件东西。旧写法拿
+    `live()` 的返回值当 dict 取 `.get("sessions")` ⇒ `/live` 非空时必抛
+    AttributeError，被 `except` 吞掉后中枢**永久「未对齐」**（`aligned()` 恒 False ⇒
+    看板 recover 不搬列、调和器缺席归位不触发）。契约由
+    `tests/test_session_visibility.py::test_live_readers_contract` 钉死。
+    """
+    return _request("GET", "/live", timeout=timeout) or {}
+
+
 def live():
-    """当前可见会话表（含外部直跑会话）：替代逐会话 REST 探测的实时态来源。"""
-    return _request("GET", "/live", timeout=10).get("sessions", [])
+    """当前可见会话表（含外部直跑会话）：替代逐会话 REST 探测的实时态来源。
+
+    返回**行表 list**（历史契约：server.py 的外部会话汇总直接迭代）；需要「完整性
+    声明」的调用方（dshevents._align）用 `live_snapshot()`。
+    """
+    return list((live_snapshot() or {}).get("sessions") or [])
 
 
 def status(session_id):
@@ -245,9 +266,17 @@ def fork(session_id, at_seq=None):
     return _request("POST", "/fork", payload, timeout=60)
 
 
-def rename(session_id, title):
-    """改会话标题（与 dsh 侧栏同一份标题）。返回 `{title}`。"""
-    return _request("POST", "/rename", {"session_id": session_id, "title": title})
+def rename(session_id, title, timeout=REQUEST_TIMEOUT):
+    """改会话标题（与 dsh 侧栏同一份标题）。返回 `{title, [external]}`。
+
+    `title` 是**宿主接受值**（可能被 `normalizeSessionTitle` 规范化/按 UTF-8 字节预算
+    截断），调用方据此回写卡面可保证两侧逐字一致（见 board.rename_card_session）。
+
+    `timeout` 可缩短：卡面改名是 best-effort 的同步链路（`PATCH /board/cards/<cid>`），
+    不能让驱动侧僵死把 HTTP worker 拖满默认 120s。
+    """
+    return _request("POST", "/rename", {"session_id": session_id, "title": title},
+                    timeout=timeout)
 
 
 def set_model(session_id, model, provider="", reasoning_effort=""):
@@ -355,6 +384,46 @@ def unarchive(session_id, timeout=30):
     return archive(session_id, archived=False, timeout=timeout)
 
 
+# ---------- 看管声明（外部会话投递通道，C 批 T5 2026-10-10） ----------
+
+# 看管声明超时（秒）：`/watch` 是驱动侧**纯内存写**，正常毫秒级返回；而投递前置闸
+# （`chat._external_preflight`）是在 HTTP 请求线程上同步调用它的——不能沿用普通请求
+# 的 120s，否则驱动僵死会把用户的一次「发送」卡住两分钟。2s 与「声明不成功即拒投」
+# 的语义相称（设计 §5.1）。
+WATCH_TIMEOUT = 2
+
+# 旧插件没有 `/watch` 端点时的状态码（未知驱动端点，见插件 _serve 的兜底 404）。
+# 平台据此把「外部会话投递」降级为拒投并给「插件过旧」文案，池内一切功能不受影响。
+WATCH_UNSUPPORTED = 404
+
+
+def watch_session(session_id, on=True):
+    """声明 / 撤销「平台看管该会话」（驱动 `POST /watch`，幂等）。返回看管是否生效。
+
+    为什么需要（C 批设计 §3.1）：外部会话（用户在 dsh GUI 里直跑/接管、`/live` 里
+    `owned:false`）既不在驱动池、也没有平台持有者，驱动侧因此不可能靠「在不在池内」
+    推断平台是否有意投递——**范围必须由平台显式划定**（宿主里与 Touchstone 无关的
+    会话多得是，无差别放开等于允许平台向任意会话注入消息与答案）。平台只对**平台确实
+    要投递的**会话声明看管：有看板卡的会话由 `board._ensure_watch` 常态声明；任务侧
+    会话在宿主上报为外部态（`owned:false`）时，由消息前置闸 `chat._external_preflight`
+    与作答/审批送达前的 `board._watch_before_delivery` 补声明。驱动据此放行 `/prompt`·
+    `/steer`·`/answer`·`/approval` 的池外分支。
+
+    幂等：重复声明同一 sid 不报错，驱动回执给的是 `watched` 的**当前实际状态**
+    （而非「这次有没有改动」），故本函数返回 `bool(resp["watched"])`——调用方按
+    「True 才算声明成功」处置。`on=False` 撤销（卡删除/归档后的回收，见
+    `board._watch_prune`）。
+
+    失败语义：**异常照抛**（`DshDriverError`：旧插件 404 / 驱动不可达 / 令牌错），
+    「是否吞异常降级」由调用方决定——`board._ensure_watch` 选择留痕 + 返回 False
+    且不重试（看管失败 ⇒ 投递前置闸拒投，见 `chat._external_preflight`）。
+    """
+    resp = _request("POST", "/watch",
+                    {"session_id": session_id, "on": bool(on)},
+                    timeout=WATCH_TIMEOUT)
+    return bool((resp or {}).get("watched"))
+
+
 def apply_session_defaults(session_id, model="", provider="",
                            reasoning_effort="", permission_mode="", log=None):
     """把项目级默认（思考等级 / 权限档）应用到刚建或刚续的会话上（best-effort）。

package/dshevents.py

@@ -61,6 +61,11 @@ class EventHub:
         # 与 `_sessions` 同样遵守「断连=未知」不变量——None 时调用方一律不动作。
         self._archived = None
         self._connected = False
+        # 快照对齐是否**可信**（2026-10-08 批次，B）：只有「(重)连时拿到过权威快照」
+        # 才置 True——空快照且插件未声明完整时保留旧表但置 False（见 `_align`）。
+        # 读口 `aligned()` = connected ∧ _aligned：调用方据此决定「能否按缺席推断
+        # 会话已结束」（`board._iw_once`）与「能否按实况搬列」（`board.recover`）。
+        self._aligned = False
         self._last_seq = 0
         self._frames = 0
         self._reconnects = 0
@@ -101,11 +106,29 @@ class EventHub:
         with self._cond:
             return self._connected
 
+    def aligned(self):
+        """注册表是否**可信**（= 链路在线 ∧ 曾用插件权威快照对齐过）。
+
+        为什么需要它（2026-10-08 批次 B，bug_report/20261008_1935）：
+        插件重新 apply（热重载）时驱动实例重建、`/live` 会短暂返回空表——旧实现
+        `self._sessions = fresh` 直接清空注册表，调用方随即把「未知」当成
+        「会话已结束/空闲」：`board.recover()` 把**正在运行的卡**搬去待审核，
+        且调和器此后再也读不到该会话 ⇒ 不自愈。现在空快照保留旧表并置
+        `_aligned=False`，本读口给出「是否可信」的单点判据：
+          - False ⇒ 一律不据实况写列（未知 ≠ 空闲，同「断连=未知」不变量）；
+          - True ⇒ 会话不在注册表即可判「已结束」（`board._iw_once` 的补口）。
+        插件半（A 批次）在 `/live` 里声明 `complete` 后，真·零会话的宿主也能可信。
+        """
+        with self._cond:
+            return bool(self._connected and self._aligned)
+
     def get(self, sid):
         """单会话实时态；未连接或未知会话返回 None（＝未知，不是空闲）。
 
-        字段：`session_id/status/cwd/task/owned/interaction/last_turn_reason/
-        updated_at`——与 `dshdriver.status()` 同形，供 board 直接替换读口。
+        字段：`session_id/status/cwd/task/owned/origin/interaction/
+        last_turn_reason/updated_at`——与 `dshdriver.status()` 同形，供 board 直接
+        替换读口。`origin`（2026-10-07 增）：`"subagent"` = dsh 子代理会话，
+        `""` = 未知（旧插件未上报，board 侧另有磁盘兜底判据）。
         """
         if not sid:
             return None
@@ -144,6 +167,7 @@ class EventHub:
         """诊断信息（/api 健康与测试断言用）。"""
         with self._cond:
             return {"connected": self._connected, "sessions": len(self._sessions),
+                    "aligned": bool(self._connected and self._aligned),
                     "last_seq": self._last_seq, "frames": self._frames,
                     "reconnects": self._reconnects, "changed": self._changed,
                     "archived": None if self._archived is None else len(self._archived),
@@ -174,6 +198,24 @@ class EventHub:
             self._cond.wait(timeout)
             return self._changed != before
 
+    def wait_connected(self, timeout):
+        """等（首）次连接就绪：就绪返回 True，超时返回 False。
+
+        启动补跑用（server 在 `dshevents.start()` 之后等它就绪，再对账 ext 行
+        ——2026-10-07 僵尸占用修复）：`board.recover()` 执行时中枢尚未 start，
+        那次 ext 对账必然「探测不可用」而保行，需要一次连接就绪后的补跑。
+        未配置驱动/宿主不可达时至多等满 timeout；绝不把「未连接」当成就绪
+        （不变量 1「断连=未知」）。
+        """
+        deadline = time.monotonic() + max(0.0, float(timeout))
+        with self._cond:
+            while not self._connected:
+                remain = deadline - time.monotonic()
+                if remain <= 0:
+                    return False
+                self._cond.wait(remain)
+            return True
+
     # ---------- 内部：连接与折叠 ----------
 
     def _run(self):
@@ -206,8 +248,20 @@ class EventHub:
         新的状态轮询」。归档集取不到时保持「未知」（None），调用方一律不动作。
         """
         try:
-            rows = (dshdriver.live() or {}).get("sessions") or []
-        except Exception:                          # noqa: BLE001 — 对齐失败不阻断重连
+            # 用 live_snapshot()（原始 dict）而不是 live()（行表 list）——2026-10-08 修正：
+            # 旧写法 `dshdriver.live() or {}` 把行表当 dict 取 `.get("sessions")`，
+            # `/live` 非空时必抛 AttributeError 被下面 except 吞掉 ⇒ 中枢**永久未对齐**
+            # （aligned() 恒 False，C/D 两处补口在真机等于失效）。契约见
+            # tests/test_session_visibility.py::test_live_readers_contract。
+            resp = dshdriver.live_snapshot() or {}
+            rows = resp.get("sessions") or []
+            # 插件完整声明（A 批次后新增，旧插件缺省 None＝未声明）：只有它才让
+            # 「空表」具备「宿主里确实没有会话」的语义，否则空表一律按未知处理。
+            complete = resp.get("complete") is True
+        except Exception as exc:                   # noqa: BLE001 — 对齐失败不阻断重连
+            self._set_aligned(False)               # 取不到快照＝不能确认任何事
+            print(f"[dshevents] /live 对齐失败（{exc}）：保留 {len(self._sessions)} 条"
+                  f"既有会话、标记未对齐", flush=True)
             return
         try:
             archived = {str(s) for s in (dshdriver.archived() or []) if s}
@@ -227,6 +281,9 @@ class EventHub:
                     "cwd": row.get("cwd") or old.get("cwd") or "",
                     "task": row.get("task") or old.get("task") or "",
                     "owned": bool(row.get("owned", old.get("owned", False))),
+                    # origin 是会话固有属性（subagent / 空＝未知）：快照没带就保留
+                    # 事件里学到的值，别把已认出的子代理会话在重连对齐时又变成未知
+                    "origin": str(row.get("origin") or old.get("origin") or ""),
                     # /live 的 interaction 可能为 None（此刻无等待）；已挂起的
                     # interaction 若快照里没带，保留事件里学到的值，避免抖动
                     "interaction": row.get("interaction", old.get("interaction")),
@@ -242,11 +299,34 @@ class EventHub:
                     "inbox": old.get("inbox") or [],
                     "updated_at": now,
                 }
-            self._sessions = fresh
+            # —— 快照可信判定（2026-10-08 批次 B）——
+            # 非空快照 = 权威整表；空快照只有插件声明完整（complete）才算权威空。
+            # 其余情况（热重载后驱动实例重建、不重枚举已有会话 ⇒ 空表）＝**未知**：
+            # 旧表原样保留（宁可多等不可误放行），只把可信标志置 False——
+            # 调用方一律不据此推断忙/闲，也绝不据「缺席」判会话已结束。
+            trusted = bool(fresh) or complete
+            if trusted:
+                self._sessions = fresh
+            kept = len(self._sessions)
+            self._aligned = trusted
             if archived is not None:
                 self._archived = archived
             self._changed += 1
             self._cond.notify_all()
+        if not trusted and kept:
+            # 留痕（插件形态落 <库目录>/plugin-backend.log）：这是可诊断的降级态，
+            # 不是静默——旧表保留期间看板列不做忙/闲写入，直到下一次权威快照。
+            print(f"[dshevents] /live 空快照且插件未声明完整：保留 {kept} 条既有会话、"
+                  f"标记未对齐（热重载后驱动实例重建的已知形态，见 "
+                  f"bug_report/20261008_1935）", flush=True)
+
+    def _set_aligned(self, value):
+        """置「快照可信」标志（变更才唤醒订阅者；调用方持锁外语义同 `_set_connected`）。"""
+        with self._cond:
+            if self._aligned != bool(value):
+                self._aligned = bool(value)
+                self._changed += 1
+                self._cond.notify_all()
 
     def _set_connected(self, value):
         with self._cond:
@@ -293,7 +373,8 @@ class EventHub:
                 item = self._sessions.get(sid)
                 if item is None:
                     item = {"session_id": sid, "status": "", "cwd": "", "task": "",
-                            "owned": False, "interaction": None,
+                            "owned": False, "origin": "",
+                            "interaction": None,
                             "last_turn_reason": None, "last_seq": 0,
                             "usage": None, "permission": None, "inbox": [],
                             "updated_at": time.time()}
@@ -345,6 +426,9 @@ class EventHub:
                                      "cache_read": int(data.get("cache_read") or 0)}
                 elif typ == "session/created":
                     item["cwd"] = data.get("cwd") or item["cwd"]
+                    # 子代理会话标记（2026-10-07）：插件在 `session/created` 里上报
+                    # 会话头行的 origin。缺字段保持旧值/空串＝未知，绝不推断。
+                    item["origin"] = str(data.get("origin") or item.get("origin") or "")
                 elif typ == "session/disposed":
                     self._sessions.pop(sid, None)
             self._changed += 1
@@ -374,6 +458,11 @@ def connected():
     return HUB.connected()
 
 
+def aligned():
+    """注册表可信读口（在线 ∧ 曾用权威快照对齐）；未对齐 ⇒ 调用方不写列、不推断。"""
+    return HUB.aligned()
+
+
 def get(sid):
     return HUB.get(sid)
 
@@ -430,6 +519,11 @@ def wait(timeout):
     return HUB.wait(timeout)
 
 
+def wait_connected(timeout):
+    """等中枢（首）次连接就绪（单例薄壳）：就绪 True / 超时 False。"""
+    return HUB.wait_connected(timeout)
+
+
 def subscribe(callback):
     return HUB.subscribe(callback)