@hpyperry/dsh-ref-lib 0.8.0 → 0.10.0

package/lib/client/refresh-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-guard.d.ts","sourceRoot":"","sources":["../../src/client/refresh-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,GAAG,CAAI;IAEf,wBAAwB;IACxB,KAAK,IAAI,MAAM;IAKf;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI/B;;;OAGG;IACH,UAAU,IAAI,IAAI;CAGnB"}

package/lib/client/refresh-guard.js

@@ -0,0 +1,38 @@
+/**
+ * 并发读守卫（竞态控制核心）：只接受"最后发起"的请求结果。
+ *
+ * RefLibDock 有多个并发"拉取列表"来源——挂载预载、打开面板、30s 轮询、操作后的
+ * 刷新——网络返回顺序不保证，旧快照可能覆盖新快照。守卫用递增编号标记每次发起：
+ * 返回时只有仍持有**最新编号**的请求结果才被应用，其余一律丢弃。
+ *
+ * 为什么"最后发起"就代表最新：`list` 返回的是请求发起时刻的服务端快照，发起越晚
+ * 快照越新，所以只信最后发起者 ≈ 只信最新快照。操作后的刷新总是最后发起（操作
+ * 完成后才发起），天然胜出；响应乱序时旧号被丢弃，最终一致。
+ *
+ * 纯 TS、零依赖、零 DOM——node 环境可直接单元测试（tests/refresh-guard.spec.ts）。
+ * @module @hpyperry/dsh-ref-lib/src/client/refresh-guard
+ */
+export class RefreshGuard {
+    seq = 0;
+    /** 发起一次请求，返回本次请求的编号。 */
+    begin() {
+        this.seq += 1;
+        return this.seq;
+    }
+    /**
+     * 该编号是否仍是最新发起者。
+     * @param mine - 发起时 {@link begin} 返回的编号。
+     * @returns true 表示应应用该请求的结果；false 表示期间又有新请求发起，结果已过期。
+     */
+    isLatest(mine) {
+        return mine === this.seq;
+    }
+    /**
+     * 作废所有 in-flight 请求的结果（会话切换 / 组件卸载时调用）：seq 递增后，
+     * 任何旧编号的 {@link isLatest} 都返回 false。
+     */
+    invalidate() {
+        this.seq += 1;
+    }
+}
+//# sourceMappingURL=refresh-guard.js.map

package/lib/client/refresh-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-guard.js","sourceRoot":"","sources":["../../src/client/refresh-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,YAAY;IACf,GAAG,GAAG,CAAC,CAAA;IAEf,wBAAwB;IACxB,KAAK;QACH,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;QACb,OAAO,IAAI,CAAC,GAAG,CAAA;IACjB,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,IAAY;QACnB,OAAO,IAAI,KAAK,IAAI,CAAC,GAAG,CAAA;IAC1B,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;IACf,CAAC;CACF"}

package/lib/client/refresh-triggers.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 会话快照 → UI 刷新触发信号的纯函数派生（v9 交互驱动同步的信号源）。
+ *
+ * 交互驱动刷新依赖两个「从会话快照节点派生」的信号（RefLibDock 内两个 effect 的
+ * 依赖项）：
+ * - `userMessageCount`：`kind: 'user'` 节点计数——普通人类消息落盘后 +1，
+ *   驱动「发消息即刷新」；
+ * - `refLibCommandDone`：`kind: 'command'` 且 `name === 'ref-lib'` 且已结算
+ *   （`outcome !== null`）的节点计数——`/ref-lib` 命令完成后 +1，驱动「命令执行
+ *   即刷新」。
+ *
+ * 派生依据已在 deepseek-harness @ dsh-v0.1.0-rc.7 源码逐条查证（设计文档 §16）：
+ * - dock 槽位 owner 的 `session` 是响应式会话快照：ConversationRoot 经
+ *   `useSession(s => s)` 订阅会话 store，每次发布都重渲染 dock（
+ *   `ui-conversation/src/client/skeleton/ConversationRoot.tsx`）；
+ * - `user/message`（`source.kind === 'user'` 且未被收件箱认领）折叠为
+ *   `kind: 'user'` 节点；goal 轮次等插件注入为 `kind: 'context'`（source 非 user），
+ *   steer 消息为 `kind: 'steering'`——后两者不增本计数
+ *   （`ui-conversation/src/client/conversation-nodes/message.ts`）；
+ * - 宿主命令执行器对每个匹配命令 append log-only `command/run` → `command/done`
+ *   对（运行中 `outcome` 为 null，结算后置值）；命令名是 typed name（无别名机制、
+ *   重名注册 fail loud），故 `name === 'ref-lib'` 过滤精确
+ *   （`interaction/commands/src/index.ts` + `conversation-nodes/command.ts`）。
+ *
+ * 已知信号盲区（设计取舍，见设计文档 §14/§16）：
+ * - steer 打断消息永不产生 `'user'` 节点 → 不触发发消息刷新（无状态变更，可接受）；
+ * - 忙碌期排队消息的 `user/message` 在 step 领取时才落盘 → 计数延迟至消息进入步骤；
+ * - `command/run` 落在窗口外（压缩/截断）时节点 `name` 为 null → 不增
+ *   `refLibCommandDone`（罕见边界）；
+ * - 窗口长度变化（loadOlder/压缩/补拉）会增减计数 → 额外静默刷新（RefreshGuard 吸收）。
+ *
+ * 单次遍历同时派生两个计数（避免每次渲染两趟全量 filter）。
+ * @module @hpyperry/dsh-ref-lib/src/client/refresh-triggers
+ */
+import type { ConversationNode } from '@deepseek-ai/dsh-client-runtime/client';
+/** 一次快照派生的刷新触发计数（RefLibDock 两个 effect 的依赖值）。 */
+export interface RefreshTriggerCounts {
+    /** `kind: 'user'` 节点数（普通人类消息；steer/context 不计）。 */
+    readonly userMessageCount: number;
+    /** 已结算（outcome 非 null）的 `ref-lib` 命令节点数；运行中不计。 */
+    readonly refLibCommandDone: number;
+}
+/**
+ * 从会话快照节点列表派生刷新触发计数。
+ * @param nodes - `session.nodes`（窗口内全部会话节点，结构子集即可）。
+ * @returns 两个计数；空列表返回 `{ userMessageCount: 0, refLibCommandDone: 0 }`。
+ */
+export declare function deriveRefreshTriggers(nodes: readonly ConversationNode[]): RefreshTriggerCounts;
+//# sourceMappingURL=refresh-triggers.d.ts.map

package/lib/client/refresh-triggers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-triggers.d.ts","sourceRoot":"","sources":["../../src/client/refresh-triggers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAA;AAE9E,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;CACnC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,oBAAoB,CAW9F"}

package/lib/client/refresh-triggers.js

@@ -0,0 +1,53 @@
+/**
+ * 会话快照 → UI 刷新触发信号的纯函数派生（v9 交互驱动同步的信号源）。
+ *
+ * 交互驱动刷新依赖两个「从会话快照节点派生」的信号（RefLibDock 内两个 effect 的
+ * 依赖项）：
+ * - `userMessageCount`：`kind: 'user'` 节点计数——普通人类消息落盘后 +1，
+ *   驱动「发消息即刷新」；
+ * - `refLibCommandDone`：`kind: 'command'` 且 `name === 'ref-lib'` 且已结算
+ *   （`outcome !== null`）的节点计数——`/ref-lib` 命令完成后 +1，驱动「命令执行
+ *   即刷新」。
+ *
+ * 派生依据已在 deepseek-harness @ dsh-v0.1.0-rc.7 源码逐条查证（设计文档 §16）：
+ * - dock 槽位 owner 的 `session` 是响应式会话快照：ConversationRoot 经
+ *   `useSession(s => s)` 订阅会话 store，每次发布都重渲染 dock（
+ *   `ui-conversation/src/client/skeleton/ConversationRoot.tsx`）；
+ * - `user/message`（`source.kind === 'user'` 且未被收件箱认领）折叠为
+ *   `kind: 'user'` 节点；goal 轮次等插件注入为 `kind: 'context'`（source 非 user），
+ *   steer 消息为 `kind: 'steering'`——后两者不增本计数
+ *   （`ui-conversation/src/client/conversation-nodes/message.ts`）；
+ * - 宿主命令执行器对每个匹配命令 append log-only `command/run` → `command/done`
+ *   对（运行中 `outcome` 为 null，结算后置值）；命令名是 typed name（无别名机制、
+ *   重名注册 fail loud），故 `name === 'ref-lib'` 过滤精确
+ *   （`interaction/commands/src/index.ts` + `conversation-nodes/command.ts`）。
+ *
+ * 已知信号盲区（设计取舍，见设计文档 §14/§16）：
+ * - steer 打断消息永不产生 `'user'` 节点 → 不触发发消息刷新（无状态变更，可接受）；
+ * - 忙碌期排队消息的 `user/message` 在 step 领取时才落盘 → 计数延迟至消息进入步骤；
+ * - `command/run` 落在窗口外（压缩/截断）时节点 `name` 为 null → 不增
+ *   `refLibCommandDone`（罕见边界）；
+ * - 窗口长度变化（loadOlder/压缩/补拉）会增减计数 → 额外静默刷新（RefreshGuard 吸收）。
+ *
+ * 单次遍历同时派生两个计数（避免每次渲染两趟全量 filter）。
+ * @module @hpyperry/dsh-ref-lib/src/client/refresh-triggers
+ */
+/**
+ * 从会话快照节点列表派生刷新触发计数。
+ * @param nodes - `session.nodes`（窗口内全部会话节点，结构子集即可）。
+ * @returns 两个计数；空列表返回 `{ userMessageCount: 0, refLibCommandDone: 0 }`。
+ */
+export function deriveRefreshTriggers(nodes) {
+    let userMessageCount = 0;
+    let refLibCommandDone = 0;
+    for (const node of nodes) {
+        if (node.kind === 'user') {
+            userMessageCount += 1;
+        }
+        else if (node.kind === 'command' && node.name === 'ref-lib' && node.outcome !== null) {
+            refLibCommandDone += 1;
+        }
+    }
+    return { userMessageCount, refLibCommandDone };
+}
+//# sourceMappingURL=refresh-triggers.js.map

package/lib/client/refresh-triggers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-triggers.js","sourceRoot":"","sources":["../../src/client/refresh-triggers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAYH;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAkC;IACtE,IAAI,gBAAgB,GAAG,CAAC,CAAA;IACxB,IAAI,iBAAiB,GAAG,CAAC,CAAA;IACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACzB,gBAAgB,IAAI,CAAC,CAAA;QACvB,CAAC;aAAM,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YACvF,iBAAiB,IAAI,CAAC,CAAA;QACxB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,CAAA;AAChD,CAAC"}

package/lib/client/styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../src/client/styles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAmnBH,mDAAmD;AACnD,wBAAgB,kBAAkB,IAAI,IAAI,CAQzC"}
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../src/client/styles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkuBH,mDAAmD;AACnD,wBAAgB,kBAAkB,IAAI,IAAI,CAQzC"}

package/lib/client/styles.js

@@ -92,6 +92,22 @@ const CSS = `
   font-weight: 500;
 }
 
+/* 失效条目计数角标（v9）：红色系，与普通数量徽标区分。 */
+.reflib-chipWarn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 18px;
+  padding: 0 5px;
+  border-radius: 9px;
+  background: var(--dsw-alias-state-error-primary);
+  color: #fff;
+  font-size: 11px;
+  line-height: 18px;
+  font-weight: 500;
+}
+
 /* ── 应用内目录浏览器（browse 后端）── */
 .reflib-browser {
   width: min(460px, 100%);
@@ -307,6 +323,11 @@ const CSS = `
   color: var(--dsw-alias-label-tertiary);
 }
 
+/* 失效条目行图标（v9）：警示色。 */
+.reflib-rowIconWarn {
+  color: var(--dsw-alias-state-error-primary);
+}
+
 .reflib-rowBody {
   display: flex;
   flex: 1;
@@ -345,6 +366,16 @@ const CSS = `
   white-space: nowrap;
 }
 
+/* 失效条目状态行（v9）：红色警示文案，位于路径之下 */
+.reflib-rowStatus {
+  overflow: hidden;
+  color: var(--dsw-alias-state-error-primary);
+  font-size: 12px;
+  line-height: 16px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .reflib-rowRemove {
   display: inline-flex;
   align-items: center;
@@ -618,6 +649,86 @@ const CSS = `
   color: var(--dsw-alias-label-caption);
 }
 
+/* ── /ref-lib 命令结果卡片（conversation.chat.commandview）── */
+.reflib-cmd {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  min-width: 0;
+}
+
+.reflib-cmdHead {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+
+.reflib-cmdHeadIcon {
+  flex: none;
+}
+
+.reflib-cmdName {
+  flex: none;
+  color: var(--dsw-alias-label-primary);
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 500;
+}
+
+/* 摘要行 = 结果首行；过长单行省略（完整结果见下方 body） */
+.reflib-cmdSummary {
+  min-width: 0;
+  flex: 1 1 auto;
+  overflow: hidden;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 13px;
+  line-height: 20px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.reflib-cmdSummary[data-error] {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.reflib-cmdCopy {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 2px 8px;
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 6px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  font-size: 12px;
+  line-height: 18px;
+  cursor: pointer;
+}
+
+.reflib-cmdCopy:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+/* 完整结果：默认全展开（无 max-height 截断），超宽自动换行 */
+.reflib-cmdBody {
+  margin: 0;
+  padding: 10px 14px;
+  overflow: auto;
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 10px;
+  background: var(--dsw-alias-markdown-code-block);
+  color: var(--dsw-alias-label-primary);
+  font: var(--dsw-font-markdown-code-block-small);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.reflib-cmdBody[data-error] {
+  color: var(--dsw-alias-state-error-primary);
+}
+
 /* 窄视口：路径行换行，输入框占满一行 */
 @media (max-width: 440px) {
   .reflib-addRow {

package/lib/client/styles.js.map

@@ -1 +1 @@
-{"version":3,"file":"styles.js","sourceRoot":"","sources":["../../src/client/styles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,yDAAyD;AACzD,MAAM,SAAS,GAAG,uBAAuB,CAAA;AACzC,0BAA0B;AAC1B,MAAM,YAAY,GAAG,8BAA8B,CAAA;AAEnD,MAAM,GAAG,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0mBX,CAAA;AAED,mDAAmD;AACnD,MAAM,UAAU,kBAAkB;IAChC,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAM;IAC3C,IAAI,QAAQ,CAAC,aAAa,CAAC,yBAAyB,GAAG,YAAY,GAAG,IAAI,CAAC,KAAK,IAAI;QAAE,OAAM;IAC5F,MAAM,GAAG,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;IAC3C,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAA;IAC9B,GAAG,CAAC,OAAO,CAAC,SAAS,GAAG,YAAY,CAAA;IACpC,GAAG,CAAC,WAAW,GAAG,GAAG,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;AAChC,CAAC"}
+{"version":3,"file":"styles.js","sourceRoot":"","sources":["../../src/client/styles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,yDAAyD;AACzD,MAAM,SAAS,GAAG,uBAAuB,CAAA;AACzC,0BAA0B;AAC1B,MAAM,YAAY,GAAG,8BAA8B,CAAA;AAEnD,MAAM,GAAG,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAytBX,CAAA;AAED,mDAAmD;AACnD,MAAM,UAAU,kBAAkB;IAChC,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAM;IAC3C,IAAI,QAAQ,CAAC,aAAa,CAAC,yBAAyB,GAAG,YAAY,GAAG,IAAI,CAAC,KAAK,IAAI;QAAE,OAAM;IAC5F,MAAM,GAAG,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;IAC3C,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAA;IAC9B,GAAG,CAAC,OAAO,CAAC,SAAS,GAAG,YAAY,CAAA;IACpC,GAAG,CAAC,WAAW,GAAG,GAAG,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;AAChC,CAAC"}