@yfwu2020/dsh-selection-explain 0.11.1 → 0.12.0

package/lib/types/host/chat-context.d.ts

@@ -0,0 +1,31 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.js';
+import type { ChatTurn, ContextState, MaterialRef } from '../chat-context.js';
+type Route = {
+    provider: string;
+    model: string;
+};
+export declare function resolveChatCapacity(ctx: Context, config: Config, route: Route): Promise<{
+    budget: number;
+    price: (t: ChatTurn) => number;
+    attachmentPrice: (a: MaterialRef) => number;
+    modelWindow: number | null;
+}>;
+export declare function fitBackground(background: ContextState['background'], tokens: number): ContextState['background'];
+export declare function planChatContext(ctx: Context, route: Route, capacity: Awaited<ReturnType<typeof resolveChatCapacity>>, input: {
+    state: ContextState;
+    history: ChatTurn[];
+    fixedTokens: number;
+    signal: AbortSignal;
+    effort: string;
+}): Promise<{
+    state: ContextState;
+    history: ChatTurn[];
+    estimatedTokens: number;
+    compacted: boolean;
+}>;
+/** Check the actual assembled input, including images and nested tool results. */
+export declare function estimateRequestTokens(messages: readonly {
+    content?: unknown;
+}[], capacity: Awaited<ReturnType<typeof resolveChatCapacity>>, tools: unknown): number;
+export {};

package/lib/types/host/chat-materials.d.ts

@@ -0,0 +1,16 @@
+import type { ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { Context } from '@deepseek-ai/cordis';
+import type { ChatMaterial, MaterialRef } from '../chat-context.js';
+export declare function readMaterialCatalog(raw: unknown): ChatMaterial[];
+export declare const MATERIAL_TOOL: ToolSchema;
+export declare function materialIndex(catalog: ChatMaterial[], through: number, all?: boolean): string;
+export declare function restoreMaterial(ctx: Context, catalog: ChatMaterial[], parsed: unknown, options: {
+    through: number;
+    key: string;
+    maxChars: number;
+    readMessage: (key: string, index: number) => Promise<string | null>;
+}): Promise<{
+    content: ContentBlock[];
+    isError: boolean;
+    restored?: MaterialRef;
+}>;

package/lib/types/host/config.d.ts

@@ -12,8 +12,9 @@ export declare const Config: z<Schemastery.ObjectS<{
     translationReasoningEffort: z<string, string>;
     /**
      * 小窗对话历史（A′）：把整段对话落到插件自己的目录，重划同一个词直接回放。
-     * 0 = 关闭历史。只留最近 N 个「划词条目」（每个条目内含它自己的全部追问轮次）。
+     * 0 = 停止保存新历史，不清空已有记录。所有条目（含已升格）统一保留最近 N 个。
      */
+    chatContextTokens: z<number, number>;
     historyMaxEntries: z<number, number>;
     /** 采样温度。**默认 -1 = 不传**（交给供应商默认，与主会话一致）。0~2 之间才真的传。 */
     temperature: z<number, number>;
@@ -82,8 +83,9 @@ export declare const Config: z<Schemastery.ObjectS<{
     translationReasoningEffort: z<string, string>;
     /**
      * 小窗对话历史（A′）：把整段对话落到插件自己的目录，重划同一个词直接回放。
-     * 0 = 关闭历史。只留最近 N 个「划词条目」（每个条目内含它自己的全部追问轮次）。
+     * 0 = 停止保存新历史，不清空已有记录。所有条目（含已升格）统一保留最近 N 个。
      */
+    chatContextTokens: z<number, number>;
     historyMaxEntries: z<number, number>;
     /** 采样温度。**默认 -1 = 不传**（交给供应商默认，与主会话一致）。0~2 之间才真的传。 */
     temperature: z<number, number>;

package/lib/types/host/history-attachments.d.ts

@@ -1,36 +1,9 @@
-/**
- * 小窗历史里的附件：**持久化的引用**怎么进模型请求，以及图片预算怎么降级。
- *
- * 为什么要单独一个模块：这段逻辑全是**纯函数**（形状收敛 / 预算规划 / 内容块重建），
- * 它决定了"第 N 轮还能不能看见第 1 轮那张图"，是最容易写错、又最难人工发现的地方 ——
- * 单独放出来才测得动（见 tests/unit/history-attachments.test.mjs）。
- *
- * ── 三条设计约束 ──
- *
- * ① **只回传引用，不回传字节**。历史里存的是 `/api/attach` 给的持久引用
- *    （`{attachmentId:'sha256:…', name, bytes, mediaType, width, height}`），
- *    和主会话往会话事件里写的是同一套形状。字节只在附件服务里存一份。
- *
- * ② **图片有预算，超了退化成一行文字**。小窗直接调 `ctx.llm.stream()`，不走 agent loop，
- *    所以吃不到 `dsh-compaction-image-offload`（它挂在 `agent/request-error` 这个
- *    agent-loop 才派发的 waterfall 上）。历史里的图要是不管，每多问一轮就重发一遍，
- *    token 会一路涨上去 —— 所以这里自己卡预算：**从最近往前数**，新图优先，
- *    超出的老图换成一行为模型可读的说明（照 dsh-llm 那句 offloaded 措辞的风格写，
- *    模型在别处见过同款说法）。
- *
- * ③ **文件不占图片预算**。文件本来就不进请求体：dsh-llm 会把它投影成
- *    "名字 + 字节数 + 只读路径"一行文字，模型需要时用文件工具按路径去读。
- *    这行的成本很低，而且"能读回来"正是持久化它的全部意义 —— 所以文件只要限个条数就行。
+/** Durable attachment validation and stable block reconstruction.
+ * The context planner owns the token budget and compaction boundary. Every
+ * image/file in its selected segment stays unchanged until that boundary moves.
+ * Binary data lives in the host attachment library; history stores only refs.
  */
 import type { ContentBlock } from '@deepseek-ai/dsh-llm';
-/** 历史里最多回带几张**图片**（当前这一轮的附件也算在这个额度里）。 */
-export declare const HISTORY_IMAGE_MAX = 2;
-/** 历史回带图片的总字节上限（规范化后的字节，取自引用里的 bytes）。 */
-export declare const HISTORY_IMAGE_BYTES: number;
-/** 历史里最多回带几个**文件**引用（每个只投影成一行路径文字）。 */
-export declare const HISTORY_FILE_MAX = 8;
-/** 单轮最多认几件附件（客户端被改坏、或有人手写请求时的护栏）。 */
-export declare const HISTORY_ATTACHMENTS_PER_TURN_MAX = 10;
 /** 附件引用里我们**只**认这几个字段 —— 其余一律丢掉。 */
 export interface AttachmentRefLike {
     attachmentId: string;
@@ -85,15 +58,9 @@ export declare function omittedImageText(ref: AttachmentRefLike): string;
 /** 文件引用被条数上限挤掉时的那行文字。 */
 export declare function omittedFileText(ref: AttachmentRefLike): string;
 /**
- * 把客户端传来的历史轮次重建成**每轮一份内容块**，并按预算决定图片是回带还是降级。
- *
- * @param turns - 客户端给的历史（`[{role, text, attachments?}]`），顺序 = 从旧到新。
- * @param current - **当前这一轮**的附件；它已经占了额度（用户刚附上的图必须发出去，
- *                  但总张数仍要封顶，否则"历史 2 张 + 本轮 1 张"会逐轮往上叠）。
- * @returns 与 `turns` 等长（下标对齐）的内容块，外加几个计数。
- *
- * 返回 `[]` 表示"这一轮没有可进模型的内容"（既没文字也没附件）—— 调用方据此跳过它，
- * 与从前的 `if (!text) continue` 等价。
+ * Rebuild every selected historical attachment in request order.
+ * Capacity planning happens before this function; current attachments are
+ * counted for diagnostics and never cause older occurrences to be rewritten.
  */
 export declare function historyContentBlocks(turns: readonly unknown[], current?: readonly HistoryAttachment[]): HistoryContentPlan;
 /**

package/lib/types/host/history-store.d.ts

@@ -10,4 +10,5 @@ export declare function createHistoryStore(ctx: Context, config: Config, models:
     handleHistory: (req: IncomingMessage, res: ServerResponse) => void;
     handlePanelSize: (req: IncomingMessage, res: ServerResponse) => void;
     handlePillPos: (req: IncomingMessage, res: ServerResponse) => void;
+    readMessage: (key: string, index: number) => Promise<string | null>;
 };

package/lib/types/host/types.d.ts

@@ -34,6 +34,10 @@ export interface AnalyzeBody {
     question?: unknown;
     /** 追问模式下的历史轮次：[{ role: 'user' | 'assistant', text }]。 */
     history?: unknown;
+    historyStart?: unknown;
+    contextState?: unknown;
+    materials?: unknown;
+    initialExplanation?: unknown;
     /**
      * 这一轮追问带的附件：[{ kind: 'image' | 'file', ref }]，ref 是 /api/attach 存好之后的持久引用。
      * 图片 → ImageBlock（模型直接看）；文件 → FileBlock（dsh-llm 投影成"名字 + 字节数 + 只读路径"一行）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yfwu2020/dsh-selection-explain",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "DSH 划词解读：选中文字浮出按钮，点击弹窗流式显示专业中英翻译 + 该文字在当前上下文中的含义详解",
   "type": "module",
   "main": "./lib/index.js",