@dsh-workbench/shared 0.3.5 → 0.3.7

package/dist/components/LongTaskRow.css

@@ -45,4 +45,56 @@
   margin: var(--wb-len-4) 0 0;
   max-height: var(--wb-len-220);
   overflow: auto;
+}
+
+.wb-longTaskStop {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  align-self: center;
+  justify-content: center;
+  width: var(--wb-len-20);
+  height: var(--wb-len-20);
+  padding: 0;
+  margin-left: auto;
+  border: 0.5px solid var(--dsw-alias-border-l2);
+  border-radius: var(--dsw-radius-sm);
+  background: var(--dsw-specific-menu);
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+}
+
+.wb-longTaskStop:hover:not(:disabled),
+.wb-longTaskStop:focus-visible {
+  border-color: color-mix(in srgb, var(--dsw-alias-state-error-primary) 45%, transparent);
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.wb-longTaskStop:disabled {
+  cursor: default;
+}
+
+.wb-longTaskStopArmed,
+.wb-longTaskStopArmed:hover:not(:disabled),
+.wb-longTaskStopArmed:focus-visible {
+  gap: var(--wb-len-4);
+  width: auto;
+  padding: 0 var(--wb-len-7);
+  border-color: color-mix(in srgb, var(--dsw-alias-state-error-primary) 45%, transparent);
+  background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 12%, transparent);
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.wb-longTaskStopLabel {
+  white-space: nowrap;
+  font-size: var(--dsw-font-xxxs-11-font-size);
+  line-height: var(--wb-line-18);
+}
+
+.wb-longTaskStopWhy {
+  margin: 0;
+  font-size: var(--dsw-font-xxxs-11-font-size);
+  line-height: var(--wb-line-16);
+  color: var(--dsw-alias-state-error-primary);
+  overflow-wrap: anywhere;
 }

package/dist/components/LongTaskRow.d.ts

@@ -8,7 +8,21 @@ export interface LongTaskRowLink {
     readonly text: string;
 }
 /**
- * `LongTaskRow` 的契约：状态、标题、问题、链接，与两处可展开的原始输出。
+ * `LongTaskRow` 那颗两按停止钮的契约：确认之后真发的那一下、三句词、在飞与失败两态。
+ * `label` 是没上膛时那颗钮的 aria-label（dsh 的词：`停止任务 {label}`）；`askLabel` 是上膛时那颗钮上显示的字（`确认停止`）；
+ * `armedLabel` 是上膛时的 aria-label，不给就用 `askLabel`（`再次点击确认停止`）；`busy` = 这一趟正在被停、钮禁用；
+ * `failed` 给了才在问题那行后面再画一行。
+ */
+export interface LongTaskRowStop {
+    readonly onStop: () => void;
+    readonly label: string;
+    readonly askLabel: string;
+    readonly armedLabel?: string | undefined;
+    readonly busy?: boolean | undefined;
+    readonly failed?: string | null | undefined;
+}
+/**
+ * `LongTaskRow` 的契约：状态、标题、问题、链接，两处可展开的原始输出，与最右边那颗可选的停止钮。
  */
 export interface LongTaskRowProps {
     readonly status: LongTaskStatus;
@@ -21,11 +35,12 @@ export interface LongTaskRowProps {
     readonly rawTitle?: string | undefined;
     readonly copyLabel?: string | undefined;
     readonly copiedLabel?: string | undefined;
+    readonly stop?: LongTaskRowStop | undefined;
 }
 /**
  * 长任务那一行：状态点 + 标题 + 链接，跑失败时把步骤与原始输出收在两处可展开里。
  * 发布、扫描、迁移这类跑得久的事都用它，别自己画进度。
- * @param props.status - `longTaskDot` 认的四态之一，决定状态点颜色与要不要画"失败"那两块。
+ * @param props.status - `longTaskDot` 认的五态之一，决定状态点颜色与要不要画"失败"那两块。
  * @param props.headline - 这一行在干什么（一句话）。
  * @param props.problem - 失败原因；不给不画。
  * @param props.links - 行尾的链接，通常指向产物或日志。
@@ -33,6 +48,7 @@ export interface LongTaskRowProps {
  * @param props.raw - 原始输出；只在失败时画，且要同时给 `rawTitle` 才成一块可展开。
  * @param props.stepsTitle - 步骤那块展开行的标题；`rawTitle` 同理是原始输出那块。
  * @param props.copyLabel - 复制钮文案：给了才画复制钮；`copiedLabel` 是复制成功后那句。
+ * @param props.stop - 给了才在最右边画那颗两按停止钮；**不给就一个像素都不变**。只在生产方认 `signal` 时给。
  * @returns 一行长任务。
  */
 export declare function LongTaskRow(props: LongTaskRowProps): JSX.Element;

package/dist/components/LongTaskRow.js

@@ -1,7 +1,7 @@
-import { longTaskDot } from '../api/long-task.js';
+import { longTaskDot, longTaskStopPress, longTaskStopStage, LONG_TASK_STOP_ARM_MS } from '../api/long-task.js';
 import { Link } from './Link.js';
-import { Fragment, h, useState } from '../lib/react.js';
-import { CodeBlock, DisclosureRow, IconCodeOutlineRegular, IconFlatListOutlineRegular, StateDot, } from '@deepseek-ai/dsh-client-ui-primitives';
+import { Fragment, h, useEffect, useState } from '../lib/react.js';
+import { CodeBlock, DisclosureRow, IconCodeOutlineRegular, IconFlatListOutlineRegular, IconStopFillRegular, StateDot, } from '@deepseek-ai/dsh-client-ui-primitives';
 import './LongTaskRow.css';
 function RowLink({ href, text }) {
     return (h(Link, { href: href, className: "wb-longTaskLink" }, text));
@@ -9,7 +9,7 @@ function RowLink({ href, text }) {
 /**
  * 长任务那一行：状态点 + 标题 + 链接，跑失败时把步骤与原始输出收在两处可展开里。
  * 发布、扫描、迁移这类跑得久的事都用它，别自己画进度。
- * @param props.status - `longTaskDot` 认的四态之一，决定状态点颜色与要不要画"失败"那两块。
+ * @param props.status - `longTaskDot` 认的五态之一，决定状态点颜色与要不要画"失败"那两块。
  * @param props.headline - 这一行在干什么（一句话）。
  * @param props.problem - 失败原因；不给不画。
  * @param props.links - 行尾的链接，通常指向产物或日志。
@@ -17,21 +17,49 @@ function RowLink({ href, text }) {
  * @param props.raw - 原始输出；只在失败时画，且要同时给 `rawTitle` 才成一块可展开。
  * @param props.stepsTitle - 步骤那块展开行的标题；`rawTitle` 同理是原始输出那块。
  * @param props.copyLabel - 复制钮文案：给了才画复制钮；`copiedLabel` 是复制成功后那句。
+ * @param props.stop - 给了才在最右边画那颗两按停止钮；**不给就一个像素都不变**。只在生产方认 `signal` 时给。
  * @returns 一行长任务。
  */
 export function LongTaskRow(props) {
     const [stepsOpen, setStepsOpen] = useState(false);
     const [rawOpen, setRawOpen] = useState(false);
+    const [armed, setArmed] = useState(false);
     const failed = props.status === 'failed';
     const problem = props.problem ?? '';
     const raw = (props.raw ?? '').trim();
     const steps = props.steps ?? [];
+    const stop = props.stop;
+    const busy = stop?.busy === true;
+    const stopWhy = stop?.failed ?? '';
+    useEffect(() => {
+        if (!armed)
+            return undefined;
+        const timer = setTimeout(() => setArmed(false), LONG_TASK_STOP_ARM_MS);
+        return () => clearTimeout(timer);
+    }, [armed]);
+    const onStopPress = () => {
+        if (stop === undefined)
+            return;
+        const press = longTaskStopPress(longTaskStopStage({ armed, busy }));
+        if (press === 'ignore')
+            return;
+        if (press === 'arm') {
+            setArmed(true);
+            return;
+        }
+        setArmed(false);
+        stop.onStop();
+    };
     return (h("div", { className: "wb-longTask" },
         h("p", { className: "wb-longTaskHead" },
             h(StateDot, { state: longTaskDot(props.status), size: 10 }),
             h("span", { className: "wb-longTaskHeadline" }, props.headline),
-            (props.links ?? []).map((link) => (h(RowLink, { href: link.href, key: `${link.text}@${link.href}`, text: link.text })))),
+            (props.links ?? []).map((link) => (h(RowLink, { href: link.href, key: `${link.text}@${link.href}`, text: link.text }))),
+            stop === undefined ? null : (h("button", { type: "button", className: `wb-longTaskStop${armed ? ' wb-longTaskStopArmed' : ''}`, "data-stop-state": longTaskStopStage({ armed, busy }), "aria-label": armed ? stop.armedLabel ?? stop.askLabel : stop.label, disabled: busy, onClick: onStopPress, onBlur: () => setArmed(false) },
+                h(IconStopFillRegular, { size: 12 }),
+                armed ? h("span", { className: "wb-longTaskStopLabel" }, stop.askLabel) : null))),
         problem === '' ? null : h("p", { className: "wb-longTaskProblem" }, problem),
+        stopWhy === '' ? null : h("p", { className: "wb-longTaskStopWhy" }, stopWhy),
         !failed ? null : (h(Fragment, null,
             steps.length === 0 || props.stepsTitle === undefined ? null : (h(DisclosureRow, { className: "wb-longTaskDump", icon: h(IconFlatListOutlineRegular, { size: 14 }), title: props.stepsTitle, open: stepsOpen, expandable: true, expandOnRowClick: true, previewChevron: true, onToggle: () => setStepsOpen(!stepsOpen) },
                 h(CodeBlock, { code: steps.join('\n'), className: "wb-longTaskDump", showHeader: props.copyLabel !== undefined, copyLabel: props.copyLabel ?? '', copiedLabel: props.copiedLabel ?? '' }))),

package/dist/components/MockStrip.css

@@ -36,4 +36,14 @@
   border-color: transparent;
   background: var(--dsw-alias-brand-primary);
   color: var(--dsw-alias-label-primary-foreground);
-}
+}
+
+.wb-mockChipOn:hover {
+  border-color: transparent;
+  background: var(--dsw-alias-brand-primary);
+  color: var(--dsw-alias-label-primary-foreground);
+}
+
+.wb-panelBody.wb-panelMany .wb-mockStrip {
+  display: none;
+}

package/dist/components/StateDot.d.ts

@@ -0,0 +1,5 @@
+export type DotState = 'ongoing' | 'warning' | 'done' | 'idle' | string;
+export declare function StateDot({ state, size }: {
+    state: DotState;
+    size: number;
+}): JSX.Element;

package/dist/components/StateDot.js

@@ -0,0 +1,10 @@
+import { h } from '../lib/react.js';
+export function StateDot({ state, size }) {
+    if (state === 'ongoing') {
+        return (h("svg", { className: "wb-loading", viewBox: "0 0 24 24", width: size, height: size, "aria-hidden": "true", style: { display: 'block' } },
+            h("g", { className: "wb-loadingMotion" },
+                h("circle", { className: "wb-loadingTrack", cx: 12, cy: 12, r: 9.5 }),
+                h("circle", { className: "wb-loadingArc", cx: 12, cy: 12, r: 9.5 }))));
+    }
+    return (h("span", { className: "wb-stateDot", "data-state": state, style: { width: size, height: size }, "aria-hidden": "true" }));
+}

package/dist/config/constants.d.ts

@@ -48,6 +48,8 @@ export declare const OPENCLI_TIMEOUT_MS = 120000;
 export declare const OPENCLI_MAX_CONCURRENT = 4;
 /** 启动预热站点那一跳的超时（毫秒）；超时按未热对待，不挡面板。 */
 export declare const WARM_TIMEOUT_MS = 20000;
+/** 体检结果算「还新鲜」的时长（毫秒）：期内再来的强制体检直接回上一次那份快照。 */
+export declare const PREFLIGHT_FRESH_MS = 30000;
 /** 装 / 卸模块包的超时（毫秒）：pnpm 与取包内容都按它算。 */
 export declare const INSTALL_TIMEOUT_MS = 300000;
 /** 查 registry 版本那一次请求的超时（毫秒）。 */

package/dist/config/constants.js

@@ -51,6 +51,8 @@ export const OPENCLI_TIMEOUT_MS = 120_000;
 export const OPENCLI_MAX_CONCURRENT = 4;
 /** 启动预热站点那一跳的超时（毫秒）；超时按未热对待，不挡面板。 */
 export const WARM_TIMEOUT_MS = 20_000;
+/** 体检结果算「还新鲜」的时长（毫秒）：期内再来的强制体检直接回上一次那份快照。 */
+export const PREFLIGHT_FRESH_MS = 30_000;
 /** 装 / 卸模块包的超时（毫秒）：pnpm 与取包内容都按它算。 */
 export const INSTALL_TIMEOUT_MS = 300_000;
 /** 查 registry 版本那一次请求的超时（毫秒）。 */

package/dist/host/__tests__/fakes.d.ts

@@ -0,0 +1,41 @@
+import type { DshShell } from '../../api/dsh.js';
+import type { Opencli } from '../../host/opencli.js';
+export interface ShellCall {
+    command: string;
+    workdir?: string;
+    timeoutMs?: number;
+    onExpiry?: string;
+    stdoutMaxBytes?: number;
+}
+export interface ShellReply {
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number | null;
+    timedOut?: boolean;
+    aborted?: boolean;
+    failWith?: Error;
+}
+export declare function createFakeShell(replies?: ShellReply[] | ((call: ShellCall, index: number) => ShellReply)): {
+    shell: DshShell;
+    calls: ShellCall[];
+    peak: () => number;
+    commands: () => string[];
+};
+export interface OpencliCall {
+    args: readonly string[];
+    key?: string;
+    workdir?: string;
+    refresh?: boolean;
+}
+export declare function createFakeOpencli(replies?: Array<unknown | Error> | ((call: OpencliCall, index: number) => unknown | Error)): {
+    opencli: Opencli;
+    calls: OpencliCall[];
+    keys: () => (string | undefined)[];
+};
+export declare function createFakeLogger(): {
+    logger: {
+        info: () => void;
+        warn: (message: string) => void;
+    };
+    warnings: string[];
+};

package/dist/host/__tests__/fakes.js

@@ -0,0 +1,76 @@
+import { setTimeout as delay } from 'node:timers/promises';
+const tick = () => delay(0);
+export function createFakeShell(replies = []) {
+    const calls = [];
+    let running = 0;
+    let peak = 0;
+    const replyAt = (index) => typeof replies === 'function' ? replies(calls[index], index) : (replies[index] ?? {});
+    const shell = {
+        resolve(request) {
+            calls.push(request);
+            return request;
+        },
+        async execute() {
+            const index = calls.length - 1;
+            const reply = replyAt(index);
+            if (reply.failWith !== undefined)
+                throw reply.failWith;
+            running += 1;
+            peak = Math.max(peak, running);
+            return {
+                async result() {
+                    await tick();
+                    running -= 1;
+                    return {
+                        exitCode: reply.exitCode ?? 0,
+                        timedOut: reply.timedOut ?? false,
+                        aborted: reply.aborted ?? false,
+                        stdout: { text: reply.stdout ?? '', truncated: false },
+                        stderr: { text: reply.stderr ?? '', truncated: false },
+                    };
+                },
+            };
+        },
+    };
+    return {
+        shell,
+        calls,
+        peak: () => peak,
+        commands: () => calls.map((call) => call.command),
+    };
+}
+export function createFakeOpencli(replies = []) {
+    const calls = [];
+    const opencli = {
+        async json(args, options = {}) {
+            const call = {
+                args,
+                ...(options.key === undefined ? {} : { key: options.key }),
+                ...(options.workdir === undefined ? {} : { workdir: options.workdir }),
+            };
+            calls.push(call);
+            const index = calls.length - 1;
+            const reply = typeof replies === 'function' ? replies(call, index) : (replies[index] ?? []);
+            if (reply instanceof Error)
+                throw reply;
+            return { value: reply, at: Date.now() };
+        },
+    };
+    return {
+        opencli,
+        calls,
+        keys: () => calls.map((call) => call.key),
+    };
+}
+export function createFakeLogger() {
+    const warnings = [];
+    return {
+        logger: {
+            info: () => { },
+            warn: (message) => {
+                warnings.push(message);
+            },
+        },
+        warnings,
+    };
+}

package/dist/host/__tests__/preflight-fixtures.d.ts

@@ -0,0 +1,19 @@
+import { createFakeShell } from './fakes';
+export declare const GOOD_BRIDGE_REPORT: string;
+export declare const ALL_OK: {
+    stdout: string;
+}[];
+export declare const STALE_DAEMON_BRIDGE: string;
+export declare const BROKEN_BRIDGE: string;
+export declare function build(replies: Parameters<typeof createFakeShell>[0], install?: () => Promise<{
+    ok: boolean;
+    detail: string;
+}>, warmReads?: () => readonly (readonly string[])[]): {
+    fake: {
+        shell: import("../..").DshShell;
+        calls: import("./fakes").ShellCall[];
+        peak: () => number;
+        commands: () => string[];
+    };
+    preflight: import("../preflight").Preflight;
+};

package/dist/host/__tests__/preflight-fixtures.js

@@ -0,0 +1,47 @@
+import { createPreflight } from '../preflight';
+import { createFakeShell } from './fakes';
+export const GOOD_BRIDGE_REPORT = [
+    'opencli v1.8.7 doctor (node v24.15.0)',
+    '',
+    '[OK] Daemon: running on port 19825 (v1.8.7)',
+    '[OK] Extension: connected (v1.0.24)',
+    '[OK] Connectivity: connected in 0.0s',
+    '',
+    'Everything looks good!',
+].join('\n');
+export const ALL_OK = [{ stdout: '1.8.8\n' }, { stdout: GOOD_BRIDGE_REPORT }];
+export const STALE_DAEMON_BRIDGE = [
+    'opencli v1.8.7 doctor (node v24.15.0)',
+    '',
+    '[STALE] Daemon: running on port 19825 (v1.8.8 != CLI v1.8.7)',
+    '[OK] Extension: connected (v1.0.24)',
+    '[OK] Connectivity: connected in 0.0s',
+    '',
+    'Issues:',
+    '  • Stale daemon detected: daemon v1.8.8 != CLI v1.8.7.',
+    '  Run: opencli daemon restart',
+].join('\n');
+export const BROKEN_BRIDGE = [
+    'opencli v1.8.7 doctor (node v24.15.0)',
+    '',
+    '[MISSING] Daemon: not running',
+    '[MISSING] Extension: not connected',
+    '[FAIL] Connectivity: failed (daemon not reachable)',
+    '',
+    'Issues:',
+    "  • Daemon is not running. It should start automatically when you run an opencli browser command.",
+    '  • Daemon is running but the Chrome/Chromium extension is not connected.',
+    'If the extension is not installed:',
+    '  1. Download from https://github.com/jackwener/opencli/releases',
+    '  2. Open chrome://extensions/ → Enable Developer Mode',
+    '  3. Click "Load unpacked" → select the extension folder',
+].join('\n');
+export function build(replies, install, warmReads) {
+    const fake = createFakeShell(replies);
+    const preflight = createPreflight({
+        shell: fake.shell,
+        ...(install === undefined ? {} : { install }),
+        ...(warmReads === undefined ? {} : { warmReads }),
+    });
+    return { fake, preflight };
+}

package/dist/host/board-fact.d.ts

@@ -0,0 +1,8 @@
+import { type BoardFactState, type BoardProbe } from '../lib/board-fact.js';
+/**
+ * 把一次探针读数归成椅面归属。
+ * @param probe - 探针读数。
+ * @param workshop - 当前工作区根路径；`null` 表示还不知道当前是哪个工作区。
+ * @returns 外壳不在、或板路径与工作区缺一 → `unknown`；右栏没开或没画出来 → `hidden`；板在本工作区 → `workshop`，否则 `other`。
+ */
+export declare function boardFactOf(probe: BoardProbe, workshop: string | null): BoardFactState;

package/dist/host/board-fact.js

@@ -0,0 +1,16 @@
+import { insideWorkshop } from '../lib/board-fact.js';
+/**
+ * 把一次探针读数归成椅面归属。
+ * @param probe - 探针读数。
+ * @param workshop - 当前工作区根路径；`null` 表示还不知道当前是哪个工作区。
+ * @returns 外壳不在、或板路径与工作区缺一 → `unknown`；右栏没开或没画出来 → `hidden`；板在本工作区 → `workshop`，否则 `other`。
+ */
+export function boardFactOf(probe, workshop) {
+    if (!probe.workbench)
+        return 'unknown';
+    if (!probe.bar || !probe.open || !probe.drawn)
+        return 'hidden';
+    if (probe.board === '' || workshop === null)
+        return 'unknown';
+    return insideWorkshop(workshop, probe.board) ? 'workshop' : 'other';
+}

package/dist/host/browser-read.js

@@ -1,4 +1,5 @@
-import { parseJsonLoose, tailLines } from '../lib/text.js';
+import { parseJsonLoose } from '../lib/text.js';
+import { tailLines } from './shell-text.js';
 import { backgroundLine } from './opencli-window.js';
 import { runShell } from './shell.js';
 export const BROWSER_SCREEN_SESSION = 'workbench';

package/dist/host/context-inject.d.ts

@@ -0,0 +1,24 @@
+import { type ContextRef } from '@dsh-workbench/shared';
+import type { ContextRenderer } from './unit-face';
+export declare const CONTEXT_SOURCE_KIND = "workbench";
+export interface ScannableMessage {
+    readonly source?: {
+        readonly kind?: string;
+    };
+    readonly content?: readonly {
+        readonly type?: string;
+        readonly text?: string;
+    }[];
+}
+export type { ContextRenderer };
+export declare function collectContextRefs(messages: readonly ScannableMessage[]): ContextRef[];
+export declare function buildContextMessage(text: string, summary: string): unknown;
+export interface ContextInjector {
+    inject(messages: readonly ScannableMessage[], agent: unknown): Promise<unknown | undefined>;
+}
+export declare function createContextInjector(options: {
+    renderers: ReadonlyMap<string, ContextRenderer>;
+    logger?: {
+        warn?(message: string): void;
+    } | undefined;
+}): ContextInjector;

package/dist/host/context-inject.js

@@ -0,0 +1,74 @@
+import { randomUUID } from 'node:crypto';
+import { encodeRef, parseMarkers } from '@dsh-workbench/shared';
+export const CONTEXT_SOURCE_KIND = 'workbench';
+export function collectContextRefs(messages) {
+    const seen = new Set();
+    const refs = [];
+    for (const message of messages) {
+        if (message.source?.kind !== 'user')
+            continue;
+        for (const block of message.content ?? []) {
+            if (block.type !== 'text' || typeof block.text !== 'string')
+                continue;
+            for (const ref of parseMarkers(block.text)) {
+                const key = encodeRef(ref);
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                refs.push(ref);
+            }
+        }
+    }
+    return refs;
+}
+export function buildContextMessage(text, summary) {
+    return {
+        role: 'user',
+        id: randomUUID(),
+        content: [{ type: 'text', text }],
+        source: { kind: CONTEXT_SOURCE_KIND, form: 'notice', summary },
+    };
+}
+export function createContextInjector(options) {
+    const done = new WeakMap();
+    return {
+        async inject(messages, agent) {
+            const refs = collectContextRefs(messages);
+            if (refs.length === 0)
+                return undefined;
+            const key = typeof agent === 'object' && agent !== null ? agent : undefined;
+            const seen = key === undefined ? undefined : (done.get(key) ?? new Set());
+            if (key !== undefined && seen !== undefined)
+                done.set(key, seen);
+            const fresh = [];
+            for (const ref of refs) {
+                const encoded = encodeRef(ref);
+                if (seen?.has(encoded) === true)
+                    continue;
+                seen?.add(encoded);
+                fresh.push(ref);
+            }
+            if (fresh.length === 0)
+                return undefined;
+            const texts = [];
+            for (const ref of fresh) {
+                const render = options.renderers.get(ref.kind);
+                if (render === undefined)
+                    continue;
+                let text;
+                try {
+                    text = await render(ref);
+                }
+                catch (error) {
+                    options.logger?.warn?.(`[dsh-workbench] 渲染对话引用失败：${String(error)}`);
+                    text = `工作台面板引用了一条内容（${encodeRef(ref)}），但当前渲染不出来（项目未选中或数据源不可用）。`;
+                }
+                if (text !== '')
+                    texts.push(text);
+            }
+            if (texts.length === 0)
+                return undefined;
+            return buildContextMessage(texts.join('\n\n'), `工作台引用：${fresh.length} 条`);
+        },
+    };
+}

package/dist/host/context-ref.d.ts

@@ -0,0 +1,13 @@
+import { type ContextRef } from '../api/context-ref.js';
+/**
+ * 把 kind:part/part 文本读回引用。
+ * @param text 待解析文本。
+ * @returns 没冒号、冒号在首尾、种类不是小写字母开头、或冒号后为空时给 undefined；不抛异常。
+ */
+export declare function decodeRef(text: string): ContextRef | undefined;
+/**
+ * 从一段文本里按出现顺序捞出所有标记引用，同一个引用只留第一次。
+ * @param text 任意文本；null / undefined 当空串。
+ * @returns 解析不出来的标记会被丢掉，所以结果只含合法引用，可能为空数组。
+ */
+export declare function parseMarkers(text: string): ContextRef[];

package/dist/host/context-ref.js

@@ -0,0 +1,41 @@
+import { CONTEXT_MARKER_NAME, encodeRef } from '../api/context-ref.js';
+const MARKER = new RegExp(`@${CONTEXT_MARKER_NAME}:([a-z][a-z0-9-]*:[A-Za-z0-9._~%#/-]+)`, 'g');
+const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
+/**
+ * 把 kind:part/part 文本读回引用。
+ * @param text 待解析文本。
+ * @returns 没冒号、冒号在首尾、种类不是小写字母开头、或冒号后为空时给 undefined；不抛异常。
+ */
+export function decodeRef(text) {
+    const at = text.indexOf(':');
+    if (at <= 0 || at === text.length - 1)
+        return undefined;
+    const kind = text.slice(0, at);
+    if (!/^[a-z][a-z0-9-]*$/.test(kind))
+        return undefined;
+    const parts = text.slice(at + 1).split('/').filter((part) => part !== '');
+    if (parts.length === 0)
+        return undefined;
+    return { kind, parts };
+}
+/**
+ * 从一段文本里按出现顺序捞出所有标记引用，同一个引用只留第一次。
+ * @param text 任意文本；null / undefined 当空串。
+ * @returns 解析不出来的标记会被丢掉，所以结果只含合法引用，可能为空数组。
+ */
+export function parseMarkers(text) {
+    const seen = new Set();
+    const refs = [];
+    for (const match of String(text ?? '').matchAll(MARKER)) {
+        const raw = match[1].replace(TRAILING_PUNCTUATION, '');
+        const ref = decodeRef(raw);
+        if (ref === undefined)
+            continue;
+        const key = encodeRef(ref);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        refs.push(ref);
+    }
+    return refs;
+}