@v587d/capital-generation 2.9.1 → 2.10.0

package/lib/agents/wait-for-agents.js

@@ -0,0 +1,256 @@
+const DEFAULT_WAIT_SLICE_MS = 30_000;
+const MAX_WAIT_SLICE_MS = 60_000;
+const jsonObject = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+function render(_args, value) {
+    return [{ type: 'text', text: JSON.stringify(value) }];
+}
+function sourceKindOf(message) {
+    if (message === null || typeof message !== 'object')
+        return undefined;
+    const source = message.source;
+    if (source === null || typeof source !== 'object')
+        return undefined;
+    const kind = source.kind;
+    return typeof kind === 'string' ? kind : undefined;
+}
+/** Settlement notices are lifecycle noise here; only a human or a relayed result is actionable. */
+function pendingCounts(agent) {
+    const messages = [...(agent.inbox?.nextTurn ?? []), ...(agent.inbox?.nextStep ?? [])];
+    let users = 0;
+    let children = 0;
+    for (const message of messages) {
+        const kind = sourceKindOf(message);
+        if (kind === 'user')
+            users += 1;
+        else if (kind === 'agent-message')
+            children += 1;
+    }
+    return { total: users + children, users, children };
+}
+function resolveSlice(value) {
+    const numeric = typeof value === 'number' && Number.isFinite(value) ? Math.floor(value) : DEFAULT_WAIT_SLICE_MS;
+    return Math.max(1, Math.min(MAX_WAIT_SLICE_MS, numeric));
+}
+function abortReason(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error('wait_for_agents aborted');
+}
+function waitTimer(ms, signal) {
+    let handle;
+    let onAbort;
+    const promise = new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(abortReason(signal));
+            return;
+        }
+        handle = setTimeout(() => resolve('timeout'), ms);
+        onAbort = () => {
+            if (handle !== undefined)
+                clearTimeout(handle);
+            reject(abortReason(signal));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+    return {
+        promise,
+        dispose: () => {
+            if (handle !== undefined)
+                clearTimeout(handle);
+            if (onAbort !== undefined)
+                signal.removeEventListener('abort', onAbort);
+        },
+    };
+}
+async function runningRows(service, agentsOf, sessionId, signal) {
+    if (typeof service.listDescendants !== 'function')
+        return [];
+    let rows;
+    try {
+        rows = await service.listDescendants(sessionId, signal);
+    }
+    catch {
+        return [];
+    }
+    let agents;
+    try {
+        agents = agentsOf?.();
+    }
+    catch {
+        agents = undefined;
+    }
+    const seen = new Set();
+    const running = [];
+    for (const row of rows ?? []) {
+        if (row?.kind !== 'child' || typeof row.id !== 'string' || seen.has(row.id))
+            continue;
+        let live;
+        try {
+            live = agents?.get?.(row.id);
+        }
+        catch {
+            live = undefined;
+        }
+        // A live idle child is not progressing; a catalog row alone is only a historical child.
+        if (live?.status === 'idle')
+            continue;
+        if (row.activity !== 'running' && live?.status !== 'running')
+            continue;
+        seen.add(row.id);
+        const label = typeof row.label === 'string' && row.label.length > 0 ? row.label : undefined;
+        running.push({ id: row.id, ...(label === undefined ? {} : { label }) });
+    }
+    return running;
+}
+function hintFor(status, pending, running) {
+    switch (status) {
+        case 'all_settled':
+            return '所有子 Agent 已结束。现在按对账表逐行核对；收齐后先 present_charts（有图）再写完整最终答复。';
+        case 'message':
+            return `有 ${pending} 条子 Agent 消息待处理，下一步会带上它们；处理完仍有未结算角色就再调用 wait_for_agents。`;
+        case 'user_input':
+            return `用户在等待期间发来消息；当前有 ${pending} 条可执行消息待处理，先处理用户输入，再决定是否继续等待。`;
+        case 'timeout':
+            return running > 0
+                ? `本次等待窗口内未收敛，仍有 ${running} 个子 Agent 在运行；继续调用 wait_for_agents。running 已列出存活子树，不要再调用 list_agents，也不要 send_message 催运行中的子 Agent；只有用户要求进度或无法继续时才说明。`
+                : '本次等待窗口内未收敛，也没有可报告的运行中子 Agent；再调用一次确认，不要调用 list_agents，不要当作完成。';
+    }
+}
+export function waitForAgentsToolDefinition(deps) {
+    const waitSliceMs = resolveSlice(deps.waitSliceMs);
+    const now = deps.now ?? Date.now;
+    const parameters = jsonObject({});
+    const outputSchema = jsonObject({
+        status: { type: 'string', enum: ['all_settled', 'message', 'user_input', 'timeout'] },
+        waited_ms: { type: 'integer' },
+        pending_messages: { type: 'integer' },
+        running: {
+            type: 'array',
+            items: jsonObject({
+                id: { type: 'string' },
+                label: { type: 'string' },
+            }, ['id']),
+        },
+        hint: { type: 'string' },
+    }, ['status', 'waited_ms', 'pending_messages', 'running', 'hint']);
+    return {
+        name: 'wait_for_agents',
+        description: '等待你的子 Agent 树完成当前工作，单次最多 30 秒；把“每个子 Agent 回传/结算各开一轮”收敛成同一轮。'
+            + '创建、复用或 send_message 之后调用它，等待期间不写可见正文，也不要用“请稍候”式正文结束回合。'
+            + '返回 message 或 user_input 时，下一步会带上这些消息；处理完继续调用。'
+            + '返回 all_settled 才进入对账与最终答复；timeout 表示仍未收敛，仍有 running 时继续调用，不要仅因一次超时写等待行。'
+            + '等待期间不要用 list_agents 轮询。只对主 Agent 开放；没有子 Agent 时会立即返回 all_settled。',
+        parameters,
+        output: { schema: outputSchema, render },
+        // Deliberately no isConcurrencySafe: waiting is the ordering barrier between dispatch and synthesis.
+        async execute(_args, exec) {
+            const agent = exec.agent;
+            const sessionId = agent?.session?.id;
+            if (agent === undefined || sessionId === undefined) {
+                throw new Error('wait_for_agents requires a calling agent (exec.agent was undefined)');
+            }
+            // `parentSession` alone is a user fork; only the subagent origin marks a delegated child.
+            if (agent.session?.header?.origin === 'subagent') {
+                throw new Error('wait_for_agents 只对主 Agent 开放：子 Agent 用 send_message 回传结果，不要等待其他 Agent。');
+            }
+            if (exec.signal.aborted)
+                throw abortReason(exec.signal);
+            const service = deps.subagents();
+            if (service?.waitForChildren === undefined) {
+                throw new Error('wait_for_agents 不可用：宿主 subagents 服务未挂载；不要用 list_agents 轮询代替。');
+            }
+            const started = now();
+            const initial = pendingCounts(agent);
+            if (initial.users > 0 || initial.children > 0) {
+                const status = initial.users > 0 ? 'user_input' : 'message';
+                const running = await runningRows(service, deps.agents, sessionId, exec.signal);
+                return {
+                    status,
+                    waited_ms: Math.max(0, Math.round(now() - started)),
+                    pending_messages: initial.total,
+                    running,
+                    hint: hintFor(status, initial.total, running.length),
+                };
+            }
+            let resolveInbox;
+            const inboxEvent = new Promise((resolve) => { resolveInbox = resolve; });
+            const onInserted = (...args) => {
+                const payload = args[0];
+                if (payload?.agent?.session?.id !== sessionId)
+                    return;
+                const kind = sourceKindOf(payload.message);
+                if (kind === 'agent-message')
+                    resolveInbox('message');
+                else if (kind === 'user')
+                    resolveInbox('user_input');
+            };
+            let dispose;
+            if (typeof deps.events?.on === 'function') {
+                try {
+                    dispose = deps.events.on('agent/inbox/inserted', onInserted);
+                }
+                catch {
+                    dispose = undefined;
+                }
+            }
+            let outcome;
+            const slice = waitTimer(waitSliceMs, exec.signal);
+            try {
+                const wait = Promise.resolve(service.waitForChildren(agent));
+                // The loser of the race must not become an unhandled rejection when the slice or a relay wins.
+                wait.catch(() => undefined);
+                outcome = await Promise.race([
+                    wait.then(() => 'settled'),
+                    inboxEvent,
+                    slice.promise,
+                ]);
+            }
+            finally {
+                slice.dispose();
+                if (typeof dispose === 'function')
+                    dispose();
+            }
+            const pending = pendingCounts(agent);
+            const status = pending.users > 0
+                ? 'user_input'
+                : pending.children > 0
+                    ? 'message'
+                    : outcome === 'timeout' ? 'timeout' : 'all_settled';
+            const running = status === 'all_settled'
+                ? []
+                : await runningRows(service, deps.agents, sessionId, exec.signal);
+            return {
+                status,
+                waited_ms: Math.max(0, Math.round(now() - started)),
+                pending_messages: pending.total,
+                running,
+                hint: hintFor(status, pending.total, running.length),
+            };
+        },
+    };
+}
+export function registerWaitForAgentsTool(ctx, options = {}) {
+    const tools = ctx.get('tools');
+    if (tools === undefined)
+        return;
+    const events = ctx;
+    const definition = waitForAgentsToolDefinition({
+        ...options,
+        subagents: () => {
+            try {
+                return ctx.get('subagents');
+            }
+            catch {
+                return undefined;
+            }
+        },
+        events,
+        agents: () => {
+            try {
+                return ctx.get('agents');
+            }
+            catch {
+                return undefined;
+            }
+        },
+    });
+    ctx.effect(() => tools.register(definition), 'capital-generation.tool(wait_for_agents)');
+}

package/lib/chart/artifact-ref.d.ts

@@ -11,6 +11,8 @@ export interface ChartArtifactRef {
     dataset_id: string | null;
     source_label: string | null;
     captured_at: number | null;
+    /** Six-digit security/index code parsed from the Dataset envelope or rows, when present. */
+    subject_code: string | null;
     kind: string;
     axis: 'time' | 'index';
     title: string;
@@ -28,7 +30,7 @@ export interface ChartArtifactRegistryOptions {
 }
 /**
  * In-process chart_ref capabilities: session/task/workspace binding and the deliverable owner
- * scope. Process restart invalidates them; chart.html remains the offline fallback.
+ * scope. Process restart invalidates them; the title-named self-contained HTML remains the offline fallback.
  */
 export declare class ChartArtifactRegistry {
     private readonly records;
@@ -44,6 +46,7 @@ export declare class ChartArtifactRegistry {
         dataset_id?: string | null;
         source_label?: string | null;
         captured_at?: number | null;
+        subject_code?: string | null;
         kind: string;
         axis: 'time' | 'index';
         title: string;

package/lib/chart/artifact-ref.js

@@ -18,7 +18,7 @@ export function chartSessionScopeId(session) {
 }
 /**
  * In-process chart_ref capabilities: session/task/workspace binding and the deliverable owner
- * scope. Process restart invalidates them; chart.html remains the offline fallback.
+ * scope. Process restart invalidates them; the title-named self-contained HTML remains the offline fallback.
  */
 export class ChartArtifactRegistry {
     records = new Map();
@@ -57,6 +57,7 @@ export class ChartArtifactRegistry {
             dataset_id: input.dataset_id ?? null,
             source_label: input.source_label ?? null,
             captured_at: input.captured_at ?? null,
+            subject_code: input.subject_code ?? null,
             kind: input.kind,
             axis: input.axis,
             title: input.title,

package/lib/chart/delivery.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Chart delivery at the closing answer.
+ *
+ * DSH's deliverable card only replays `deliverables/presented` events whose seq is before the
+ * turn's closing assistant message, and a turn is final only after the fact. The one place that is
+ * provably before the closing message is the assistant stream's terminal `finish` chunk: the loop
+ * appends the message after the stream ends. So delivery is deferred to that chunk, gated on the
+ * root session being idle (no actionable inbox input, no running direct children), which is exactly
+ * the shape of a closing turn. Waiting/aborted/tool-call responses never flush.
+ *
+ * `subagent-settled` notices are not actionable input: they can arrive while the closing answer is
+ * already streaming. Counting them as pending would strand a card that the model has just selected,
+ * because the follow-up step often has nothing new to say.
+ */
+import type { ChartArtifactRegistry } from './artifact-ref.js';
+import type { ChartTurnEventInput } from './events.js';
+import type { SessionLike } from '../data-collector/store.js';
+/** Structural subset of `@deepseek-ai/dsh-llm` AssistantStreamFrame. */
+export interface AssistantStreamFrameLike {
+    readonly type?: string;
+    readonly attemptId?: string;
+    readonly turn?: number;
+    readonly chunk?: {
+        readonly type?: string;
+        readonly reason?: {
+            readonly kind?: string;
+        };
+        readonly blockType?: string;
+        readonly block?: {
+            readonly type?: string;
+        };
+    };
+}
+/** Live root Agent passed to the closing hook so it can cancel inbox notices before the loop claims them. */
+export interface DeliveryAgentLike {
+    readonly session?: SessionLike;
+    readonly inbox?: {
+        readonly nextTurn?: readonly unknown[];
+        readonly nextStep?: readonly unknown[];
+        remove?(messageId: string): boolean;
+    };
+}
+interface InboxStateLike {
+    'next-turn'?: readonly unknown[];
+    'next-step'?: readonly unknown[];
+}
+export interface ChartDeliveryOptions {
+    artifacts: ChartArtifactRegistry;
+    /** Writes one first-party deliverables/presented batch; must be synchronous (pre-message seq). */
+    publish: (sessionId: string, inputs: ChartTurnEventInput[]) => boolean;
+    /** Durable pending input; synchronous projection read. Absent means "cannot tell" → proceed. */
+    inboxOf?: (session: SessionLike) => InboxStateLike | undefined;
+    /**
+     * Runs on every closing finish, including exchanges with no chart. The wake guard removes
+     * redundant settlement notices here; it must never be allowed to block delivery.
+     */
+    onClosing?: (session: SessionLike, agent: DeliveryAgentLike | undefined, turn: number | undefined) => void;
+    /** Bounded batch; the card collapses past four files and expands on demand. */
+    maxCharts?: number;
+}
+export interface ChartDelivery {
+    /** `present_charts` selection; merged across calls because models often retry in batches. */
+    request(session: SessionLike, inputs: ChartTurnEventInput[]): void;
+    acceptStream(session: SessionLike | undefined, frame: AssistantStreamFrameLike, agent?: DeliveryAgentLike): void;
+    /** A new human message starts a new exchange: old charts must not ride into it. */
+    acceptUserMessage(sessionId: string, time: number): void;
+    acceptSubagentStart(info: {
+        id?: string;
+    }): void;
+    acceptSubagentEnd(info: {
+        id?: string;
+    }): void;
+    /** False until any stream frame was observed: callers fall back to immediate delivery. */
+    streaming(): boolean;
+    /** Diagnostics/tests: explicitly selected inputs for the current exchange. */
+    pending(sessionId?: string): number;
+}
+export declare const DEFAULT_MAX_DELIVERED_CHARTS = 32;
+export declare function createChartDelivery(options: ChartDeliveryOptions): ChartDelivery;
+export {};

package/lib/chart/delivery.js

@@ -0,0 +1,157 @@
+/** Settlement notices race the closing answer; they do not require another model step before the card. */
+function isSettledNotice(value) {
+    return value !== null && typeof value === 'object'
+        && value.source?.kind === 'subagent-settled';
+}
+function inboxMessages(inbox) {
+    return [...(inbox?.['next-turn'] ?? []), ...(inbox?.['next-step'] ?? [])];
+}
+export const DEFAULT_MAX_DELIVERED_CHARTS = 32;
+export function createChartDelivery(options) {
+    const maxCharts = options.maxCharts ?? DEFAULT_MAX_DELIVERED_CHARTS;
+    /** Plugin instances are per root agent, so one session id guards against child streams leaking in. */
+    let sessionId;
+    let explicit = [];
+    const exchangeStarts = new Map();
+    const fallbackStart = Date.now();
+    /** One card per exchange. `turn` is unreliable: a later finish in the same turn may omit it. */
+    let flushed = false;
+    let sawFrame = false;
+    const attempts = new Map();
+    const running = new Map();
+    const owns = (session) => {
+        if (session?.id === undefined)
+            return false;
+        // A leaked child frame must not bind the manager: the card belongs to the user-facing root.
+        if (session.header?.origin === 'subagent')
+            return false;
+        sessionId ??= session.id;
+        return session.id === sessionId;
+    };
+    const autoInputs = (session) => options.artifacts
+        .list({ session })
+        .filter((artifact) => artifact.created_at >= (exchangeStarts.get(session.id) ?? fallbackStart))
+        .map((artifact) => ({
+        ownerSessionId: session.id,
+        chart_id: artifact.chart_id,
+        title: artifact.title,
+        html_path: artifact.html_path,
+    }));
+    /** A settled notice proves the child is done even if the lifecycle edge was missed or the parent
+     * observed it outside its scope. Reconciliating here keeps the stream-time gate synchronous. */
+    const reconcileSettled = (inbox) => {
+        for (const message of inboxMessages(inbox)) {
+            if (!isSettledNotice(message))
+                continue;
+            const childId = message.source?.senderSessionId;
+            if (typeof childId === 'string')
+                running.delete(childId);
+        }
+    };
+    const idle = (inbox) => {
+        if (running.size > 0)
+            return false;
+        if (inbox === undefined)
+            return true;
+        return inboxMessages(inbox).every(isSettledNotice);
+    };
+    const flush = (session, turn, agent) => {
+        // A later step in the same exchange may omit `turn`; it still must not write a second card.
+        if (flushed)
+            return;
+        const inbox = options.inboxOf?.(session);
+        reconcileSettled(inbox);
+        if (!idle(inbox))
+            return;
+        // The wake guard drops notices that would otherwise make the loop open another step after
+        // this answer. Run it even when no chart is selected, and never let it block delivery.
+        try {
+            options.onClosing?.(session, agent, turn);
+        }
+        catch {
+            // A guard failure must not strand an already-selected card.
+        }
+        const inputs = (explicit.length > 0 ? explicit : autoInputs(session)).slice(0, maxCharts);
+        if (inputs.length === 0)
+            return;
+        let written = false;
+        try {
+            written = options.publish(session.id, inputs);
+        }
+        catch {
+            written = false;
+        }
+        // A failed write keeps the exchange open so a later closing finish can retry.
+        if (written)
+            flushed = true;
+    };
+    return {
+        request(session, inputs) {
+            if (!owns(session) || inputs.length === 0)
+                return;
+            const seen = new Set(explicit.map((item) => item.chart_id));
+            for (const input of inputs) {
+                if (seen.has(input.chart_id))
+                    continue;
+                seen.add(input.chart_id);
+                explicit.push(input);
+            }
+            if (explicit.length > maxCharts)
+                explicit = explicit.slice(0, maxCharts);
+        },
+        acceptStream(session, frame, agent) {
+            if (!owns(session) || frame === undefined)
+                return;
+            sawFrame = true;
+            const attemptId = frame.attemptId ?? '__default__';
+            if (frame.type === 'start') {
+                attempts.set(attemptId, { toolCall: false });
+                return;
+            }
+            if (frame.type === 'end') {
+                attempts.delete(attemptId);
+                return;
+            }
+            const chunk = frame.chunk;
+            if (frame.type !== 'chunk' || chunk === undefined)
+                return;
+            const attempt = attempts.get(attemptId) ?? { toolCall: false };
+            attempts.set(attemptId, attempt);
+            if (chunk.type === 'tool-call-delta'
+                || (chunk.type === 'block-start' && chunk.blockType === 'tool-call')
+                || (chunk.type === 'block-end' && chunk.block?.type === 'tool-call')) {
+                attempt.toolCall = true;
+                return;
+            }
+            if (chunk.type !== 'finish' || chunk.reason?.kind !== 'stop' || attempt.toolCall)
+                return;
+            flush(session, frame.turn, agent);
+        },
+        acceptUserMessage(id, time) {
+            exchangeStarts.set(id, time);
+            if (id !== sessionId)
+                return;
+            explicit = [];
+            flushed = false;
+        },
+        acceptSubagentStart(info) {
+            if (typeof info?.id !== 'string' || info.id.length === 0)
+                return;
+            running.set(info.id, 1);
+        },
+        acceptSubagentEnd(info) {
+            if (typeof info?.id !== 'string')
+                return;
+            // One child session runs one activation at a time; deleting also clears duplicate starts.
+            running.delete(info.id);
+        },
+        streaming() {
+            return sawFrame;
+        },
+        pending(id) {
+            if (id !== undefined && id !== sessionId)
+                return 0;
+            return explicit.length;
+        },
+    };
+}

package/lib/chart/events.d.ts

@@ -33,11 +33,13 @@ export interface ChartTurnEventInput {
     ownerSessionId: string;
     chart_id: string;
     title: string;
-    /** Workspace-relative chart.html path; the official preview resolves it against session.cwd. */
+    /** Workspace-relative self-contained HTML path; the official preview resolves it against session.cwd. */
     html_path: string;
 }
 export interface ChartEventPublisher {
     publish(input: ChartTurnEventInput): boolean;
+    /** One first-party event carrying every file; the turn cap counts events, not files. */
+    publishMany(ownerSessionId: string, inputs: ChartTurnEventInput[]): boolean;
     /** Diagnostics: queued charts not yet written. */
     pendingCount?(ownerSessionId?: string): number;
     /** Diagnostics: last publish trace, surfaced in receipts / disk so failures are visible without a terminal. */

package/lib/chart/events.js

@@ -160,7 +160,7 @@ function buildChartEventPublisher(ctx) {
         const key = `${owner.id}:${turn}`;
         const used = perTurn.get(key) ?? 0;
         if (used >= MAX_CHARTS_PER_TURN) {
-            warn(`图表对话流事件跳过：turn ${turn} 已达到 ${MAX_CHARTS_PER_TURN} 张上限`);
+            warn(`图表对话流事件跳过：turn ${turn} 已达到 ${MAX_CHARTS_PER_TURN} 次上限`);
             return false;
         }
         try {
@@ -174,6 +174,31 @@ function buildChartEventPublisher(ctx) {
         note(`图表已登记为本轮交付（owner=${owner.id}，turn=${turn}，${input.chart_id}）`);
         return true;
     };
+    const appendMany = (owner, turn, inputs) => {
+        if (inputs.length === 0)
+            return false;
+        const key = `${owner.id}:${turn}`;
+        const used = perTurn.get(key) ?? 0;
+        if (used >= MAX_CHARTS_PER_TURN) {
+            warn(`图表对话流事件跳过：turn ${turn} 已达到 ${MAX_CHARTS_PER_TURN} 次上限`);
+            return false;
+        }
+        const first = inputs[0];
+        if (first === undefined)
+            return false;
+        const payload = buildChartEventPayload(first, turn);
+        payload.files = inputs.map((item) => ({ path: item.html_path, description: item.title }));
+        try {
+            owner.append(CHART_DELIVERABLE_EVENT, payload);
+        }
+        catch (error) {
+            warn(`图表对话流事件写入失败（图表已落盘）：${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+        perTurn.set(key, used + 1);
+        note(`图表已登记为本轮交付（owner=${owner.id}，turn=${turn}，${inputs.length} 张）`);
+        return true;
+    };
     /** Flush queued charts into a turn; the preferred hook is turn-stopping. */
     const flush = (ownerSessionId, turn) => {
         const queued = pending.get(ownerSessionId);
@@ -308,6 +333,32 @@ function buildChartEventPublisher(ctx) {
             lastPublishTrace = `${trace.join(' ')} 回合打开(turn=${lastTurn}) → ${written ? '已直接登记' : '写入失败'}`;
             return written;
         },
+        publishMany(ownerSessionId, inputs) {
+            const owner = resolveOwnerSession(sessions, ownerSessionId);
+            if (owner === undefined) {
+                lastPublishTrace = `owner 未解析：批量交付缺少可用 owner 会话`;
+                warn('图表对话流事件跳过：找不到批量交付的 owner 会话（图表已落盘，走 html_path 降级）');
+                return false;
+            }
+            const boundary = boundaryOf(owner);
+            const turn = boundary?.lastTurn;
+            if (typeof boundary?.openTurnStartSeq !== 'number' || typeof turn !== 'number' || !Number.isSafeInteger(turn) || turn < 1) {
+                // Between turns: queue each input so the existing flush path still delivers them later.
+                const queued = pending.get(owner.id) ?? [];
+                if (queued.length + inputs.length > MAX_PENDING_CHARTS) {
+                    lastPublishTrace = `owner=${owner.id} 批量寄存超限（${queued.length}+${inputs.length} > ${MAX_PENDING_CHARTS}）→ 未写入`;
+                    warn('图表对话流事件跳过：进程内寄存已超出上限（冲刷链路异常）');
+                    return false;
+                }
+                queued.push(...inputs);
+                pending.set(owner.id, queued);
+                lastPublishTrace = `owner=${owner.id} 回合未打开 → 已寄存 ${inputs.length} 张，等 turn-stopping/turn-start 冲刷`;
+                return true;
+            }
+            const written = appendMany(owner, turn, inputs);
+            lastPublishTrace = `owner=${owner.id} 回合打开(turn=${turn}) → ${written ? `已批量登记 ${inputs.length} 张` : '写入失败'}`;
+            return written;
+        },
         /** Diagnostics/tests: queued charts not yet flushed. */
         pendingCount(ownerSessionId) {
             if (ownerSessionId !== undefined)

package/lib/chart/html.js

@@ -59,7 +59,9 @@ function formatCapturedAt(epochMs) {
 export function buildStandaloneHtml(input) {
     const { payload, library } = input;
     const meta = payload.meta;
+    const kindLabel = payload.kind === 'candlestick' ? 'K 线图' : payload.kind === 'bar' ? 'OHLC 图' : payload.kind === 'column' ? '柱状图' : payload.kind === 'area' ? '面积图' : '折线图';
     const facts = [];
+    facts.push(kindLabel);
     facts.push(`${meta.points} 个数据点`);
     if (meta.downsampled)
         facts.push(`已从 ${meta.original_points} 点下采样（保留极值形状，非全量）`);
@@ -73,6 +75,18 @@ export function buildStandaloneHtml(input) {
         facts.push(`时间字段 ${meta.time_field}`);
     if (meta.axis === 'index')
         facts.push('分类轴（按行序）');
+    const guide = [];
+    guide.push(meta.axis === 'index' ? '横轴为分类，按数据行序排列；纵轴为数值。' : '横轴为时间；纵轴为数值。');
+    if (payload.ohlc)
+        guide.push('K 线红涨绿跌，下方成交量柱按当日涨跌着色。');
+    else if (payload.volume)
+        guide.push('下方成交量柱按涨跌方向着色。');
+    if (payload.series.length > 0)
+        guide.push(`序列：${payload.series.map((item) => item.label).join('、')}。`);
+    if (meta.downsampled)
+        guide.push('曲线为下采样后的形状，数值结论请回到表格/查询结果。');
+    if (meta.warnings.length > 0)
+        guide.push('数据提示见下方 warnings。');
     const warnings = meta.warnings.length > 0
         ? `<ul class="warnings">${meta.warnings.map((warning) => `<li>${escapeHtml(warning)}</li>`).join('')}</ul>`
         : '';
@@ -108,6 +122,7 @@ export function buildStandaloneHtml(input) {
   body { font: 14px/1.6 -apple-system, "PingFang SC", "Microsoft YaHei", system-ui, sans-serif; padding: 16px 20px 24px; }
   h1 { margin: 0 0 4px; font-size: 16px; font-weight: 600; }
   .facts { margin: 0; color: var(--dsw-alias-label-secondary); font-size: 12px; }
+  .guide { margin: 6px 0 0; color: var(--dsw-alias-label-secondary); font-size: 12px; line-height: 1.7; }
   main { margin-top: 12px; height: 460px; min-height: 320px; }
   .warnings { margin: 12px 0 0; padding-left: 18px; color: var(--dsw-alias-label-secondary); font-size: 12px; }
   footer { margin-top: 16px; color: var(--dsw-alias-label-secondary); font-size: 11px; }
@@ -117,6 +132,7 @@ export function buildStandaloneHtml(input) {
 <header>
   <h1>${escapeHtml(payload.title)}</h1>
   <p class="facts">${facts.map((fact) => escapeHtml(fact)).join(' · ')}</p>
+  <p class="guide">${guide.map((line) => escapeHtml(line)).join(' ')}</p>
 </header>
 <main id="chart"></main>
 ${warnings}