@max-null/dsh-allostasis 0.1.1 → 0.2.1

package/dist/tail.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 回合末步的产出形态判定（空回合检测的判据）。
+ *
+ * 落点：`assistant/message` 事件的 `message.content` —— 与 `thinking.ts` 读同一个事件的
+ * 另一个字段（那边读 `stream` 里的 `reasoning-chunks`，这里读 `content` 的块构成）。
+ *
+ * 判据 = **本 turn 最后一条助手消息里没有非空 text 块**。
+ *
+ * 实测依据（2026-09-30，14 天内 1202 个 `completed` 回合）：完成态结尾沉默 34 轮
+ * （2.8%），其中 **32 轮的末步只有 `reasoning`** —— 判据纯度 94%，误报面小。
+ * `aborted` / `interrupted` 的沉默另有 15 轮，但那是用户中止的预期结果，**不在判据内**：
+ * 调用方按 `signal.aborted` 排除，见 `index.ts` 的 turn-stopping 监听。
+ *
+ * 为什么读 `content` 而不是 `stream`：`stream` 里的 `text-chunks` 回答「模型有没有生成过
+ * 文本」，`content` 回答「这一步最终产出了什么」。判据要的是后者，前者只在排查时用来
+ * 交叉验证（设计文档 §2.2）。
+ *
+ * 设计出处：`docs/设计/2026-09-30-空回合检测与可见化.md` §二
+ * @module @max-null/dsh-allostasis/tail
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** 空回合兜底的档位：`off` 不判定，`observe` 判定并留痕，`steer` 额外补一次生成。 */
+export type SilentTurnMode = 'off' | 'observe' | 'steer';
+/** 全部档位，供配置校验枚举。 */
+export declare const SILENT_TURN_MODES: readonly SilentTurnMode[];
+/**
+ * 空回合兜底的档位缺省值。
+ *
+ * `observe` 而不是 `off`：判定与留痕必须先跑起来，否则「这个现象有多频繁、判据准不准」
+ * 永远没有数据。补生成（`steer`）要等到有数据说明它值得开之后再加。
+ */
+export declare const SILENT_TURN_MODE: SilentTurnMode;
+/** 判定只需要块的类型与文本；用最小形状接收，判据模块因此不依赖会话包的内容类型。 */
+export interface TailBlock {
+    /** 块类型：`reasoning` / `text` / `tool-call`。 */
+    readonly type: string;
+    /** 文本与推理块的正文；工具调用块没有这个字段。 */
+    readonly text?: string;
+}
+/** 一条助手消息的产出形态。 */
+export interface TailShape {
+    /** 该消息所属的 turn。 */
+    readonly turn: number;
+    /** 该消息所属的 step。 */
+    readonly step: number;
+    /** 非空 `text` 块的总字符数。空回合恒为 0。 */
+    readonly textChars: number;
+    /** `reasoning` 块的总字符数——区分「想了很久没说」与「完全没输出」。 */
+    readonly reasoningChars: number;
+    /** 按类型的块计数。 */
+    readonly blocks: {
+        readonly reasoning: number;
+        readonly text: number;
+        readonly toolCalls: number;
+    };
+}
+/**
+ * 三态判定。`unknown` 用于「本回合没有助手消息」——比如用户消息刚落下、助手还没产出，
+ * 此时既不能说它说了话，也不能说它是空回合。
+ */
+export type TailVerdict = 'spoke' | 'silent' | 'unknown';
+/**
+ * 统计一条助手消息的块构成。
+ *
+ * `text` 按去掉首尾空白后的长度计入：只含空白的文本块在界面上不产生任何可见内容，
+ * 把它算作「说了话」会让判据漏掉真实的空回合。
+ * @param turn - 该消息所属的 turn。
+ * @param step - 该消息所属的 step。
+ * @param content - 助手消息的内容块，按出现顺序。
+ * @returns 该消息的产出形态。
+ */
+export declare function shapeOf(turn: number, step: number, content: readonly TailBlock[]): TailShape;
+/** 从会话事件里取出的助手消息样本：判定只读这三个字段。 */
+export interface TailSample {
+    /** 该消息所属的 turn。 */
+    readonly turn: number;
+    /** 该消息所属的 step。 */
+    readonly step: number;
+    /** 内容块，按出现顺序。 */
+    readonly content: readonly TailBlock[];
+}
+/**
+ * 把会话事件收窄成判定样本。
+ *
+ * 与 {@link measureTail} 分成两步，是为了让判定完全落在纯函数上：`SessionEvent` 是
+ * 所有事件的联合，拿它当参数就得在测试里伪造整个事件（含 `usage` / `stream`），
+ * 或者用类型断言把缺口盖掉。收窄只在这里做一次。
+ * @param events - 会话事件，按 seq 升序。
+ * @returns 助手消息样本，保持原顺序；其它类型的事件被跳过。
+ */
+export declare function tailSamples(events: readonly SessionEvent[]): TailSample[];
+/**
+ * 取本 turn **最后一条**助手消息的产出形态。
+ *
+ * 倒扫而不是取「最后一条样本」：会话里可能夹着别的 turn 的助手消息（中断后的残留、
+ * 子代理的投递），而判定要问的是「这一轮结束时用户看到了什么」。
+ * @param samples - {@link tailSamples} 的产出。
+ * @param turn - 要检查的 turn。
+ * @returns 末条助手消息的形态；该 turn 没有助手消息时返回 `undefined`。
+ */
+export declare function measureTail(samples: readonly TailSample[], turn: number): TailShape | undefined;
+/**
+ * 对一次测量下判定。
+ *
+ * 只有「有助手消息且它没有非空文本」才算空回合。工具调用**不**改变判定：一个以
+ * `tool-call` 结尾的完成态回合同样是异常（工具执行完还会再走一步，除非回合已经结束）。
+ * @param shape - 末条助手消息的形态；没有助手消息时传 `undefined`。
+ * @returns 三态判定。
+ */
+export declare function tailVerdict(shape: TailShape | undefined): TailVerdict;

package/dist/tail.js

@@ -0,0 +1,111 @@
+/**
+ * 回合末步的产出形态判定（空回合检测的判据）。
+ *
+ * 落点：`assistant/message` 事件的 `message.content` —— 与 `thinking.ts` 读同一个事件的
+ * 另一个字段（那边读 `stream` 里的 `reasoning-chunks`，这里读 `content` 的块构成）。
+ *
+ * 判据 = **本 turn 最后一条助手消息里没有非空 text 块**。
+ *
+ * 实测依据（2026-09-30，14 天内 1202 个 `completed` 回合）：完成态结尾沉默 34 轮
+ * （2.8%），其中 **32 轮的末步只有 `reasoning`** —— 判据纯度 94%，误报面小。
+ * `aborted` / `interrupted` 的沉默另有 15 轮，但那是用户中止的预期结果，**不在判据内**：
+ * 调用方按 `signal.aborted` 排除，见 `index.ts` 的 turn-stopping 监听。
+ *
+ * 为什么读 `content` 而不是 `stream`：`stream` 里的 `text-chunks` 回答「模型有没有生成过
+ * 文本」，`content` 回答「这一步最终产出了什么」。判据要的是后者，前者只在排查时用来
+ * 交叉验证（设计文档 §2.2）。
+ *
+ * 设计出处：`docs/设计/2026-09-30-空回合检测与可见化.md` §二
+ * @module @max-null/dsh-allostasis/tail
+ */
+/** 全部档位，供配置校验枚举。 */
+export const SILENT_TURN_MODES = ['off', 'observe', 'steer'];
+/**
+ * 空回合兜底的档位缺省值。
+ *
+ * `observe` 而不是 `off`：判定与留痕必须先跑起来，否则「这个现象有多频繁、判据准不准」
+ * 永远没有数据。补生成（`steer`）要等到有数据说明它值得开之后再加。
+ */
+export const SILENT_TURN_MODE = 'observe';
+/**
+ * 统计一条助手消息的块构成。
+ *
+ * `text` 按去掉首尾空白后的长度计入：只含空白的文本块在界面上不产生任何可见内容，
+ * 把它算作「说了话」会让判据漏掉真实的空回合。
+ * @param turn - 该消息所属的 turn。
+ * @param step - 该消息所属的 step。
+ * @param content - 助手消息的内容块，按出现顺序。
+ * @returns 该消息的产出形态。
+ */
+export function shapeOf(turn, step, content) {
+    let textChars = 0;
+    let reasoningChars = 0;
+    const blocks = { reasoning: 0, text: 0, toolCalls: 0 };
+    for (const block of content) {
+        if (block.type === 'reasoning') {
+            blocks.reasoning += 1;
+            reasoningChars += block.text?.length ?? 0;
+        }
+        else if (block.type === 'text') {
+            blocks.text += 1;
+            textChars += block.text?.trim().length ?? 0;
+        }
+        else if (block.type === 'tool-call') {
+            blocks.toolCalls += 1;
+        }
+    }
+    return { turn, step, textChars, reasoningChars, blocks };
+}
+/**
+ * 把会话事件收窄成判定样本。
+ *
+ * 与 {@link measureTail} 分成两步，是为了让判定完全落在纯函数上：`SessionEvent` 是
+ * 所有事件的联合，拿它当参数就得在测试里伪造整个事件（含 `usage` / `stream`），
+ * 或者用类型断言把缺口盖掉。收窄只在这里做一次。
+ * @param events - 会话事件，按 seq 升序。
+ * @returns 助手消息样本，保持原顺序；其它类型的事件被跳过。
+ */
+export function tailSamples(events) {
+    const samples = [];
+    for (const event of events) {
+        if (event.type !== 'assistant/message')
+            continue;
+        samples.push({
+            turn: event.data.turn,
+            step: event.data.step,
+            content: event.data.message.content,
+        });
+    }
+    return samples;
+}
+/**
+ * 取本 turn **最后一条**助手消息的产出形态。
+ *
+ * 倒扫而不是取「最后一条样本」：会话里可能夹着别的 turn 的助手消息（中断后的残留、
+ * 子代理的投递），而判定要问的是「这一轮结束时用户看到了什么」。
+ * @param samples - {@link tailSamples} 的产出。
+ * @param turn - 要检查的 turn。
+ * @returns 末条助手消息的形态；该 turn 没有助手消息时返回 `undefined`。
+ */
+export function measureTail(samples, turn) {
+    for (let index = samples.length - 1; index >= 0; index -= 1) {
+        const sample = samples[index];
+        if (sample === undefined || sample.turn !== turn)
+            continue;
+        return shapeOf(sample.turn, sample.step, sample.content);
+    }
+    return undefined;
+}
+/**
+ * 对一次测量下判定。
+ *
+ * 只有「有助手消息且它没有非空文本」才算空回合。工具调用**不**改变判定：一个以
+ * `tool-call` 结尾的完成态回合同样是异常（工具执行完还会再走一步，除非回合已经结束）。
+ * @param shape - 末条助手消息的形态；没有助手消息时传 `undefined`。
+ * @returns 三态判定。
+ */
+export function tailVerdict(shape) {
+    if (shape === undefined)
+        return 'unknown';
+    return shape.textChars > 0 ? 'spoke' : 'silent';
+}

package/dist/throttle.d.ts

@@ -1,5 +1,5 @@
 /**
- * 锚定注入的节流。
+ * 提醒注入的节流：**同一 turn 至多一次**。
  *
  * 实测（2026-09-21，会话 `session-502b3e2b`，记录见设计方案 §12.4）：漂移持续时**每个
  * step 都会判定为漂移**，于是同一个 turn 内会连着注入多条几乎一样的提醒——观测到 3 连注，
@@ -8,13 +8,16 @@
  * 所以收紧到「同一 turn 至多一次」：turn 是用户能感知的自然边界，重试留到下一轮，
  * 而不是在一步之内反复催促。上限写成常数而不是配置项，是因为**没有数据支撑别的取值**；
  * 等无对抗的自然漂移样本出来，再决定要不要放宽（设计方案 §八 第 9 条）。
+ *
+ * 退化提醒复用同一契约、独立一份状态：两类提醒的判据无关，共用状态会让先说的那类
+ * 把另一类挡在门外。
  * @module @max-null/dsh-allostasis/throttle
  */
-/** 锚定在单个 turn 内的注入上限。 */
-export declare const MAX_ANCHORS_PER_TURN = 1;
+/** 同一 turn 内的提醒注入上限。 */
+export declare const MAX_PER_TURN = 1;
 /** 节流状态。不可变——每次放行都返回一份新状态。 */
-export interface AnchorThrottleState {
-    /** 最近一次注入所针对的 turn（产出那段漂移思考的 turn）。 */
+export interface PerTurnThrottleState {
+    /** 最近一次注入所针对的 turn（产出那段异常输出的 turn）。 */
     lastTurn: number;
     /** 该 turn 内已经注入了几次。 */
     inTurn: number;
@@ -24,10 +27,10 @@ export interface AnchorThrottleState {
 /**
  * 判定本次是否放行，并推进状态。
  *
- * `sampledTurn` 是**产出那段被判定漂移的思考**的 turn，不是当前 turn——锚定的措辞
+ * `sampledTurn` 是**产出那段被判定异常的输出的 turn**，不是当前 turn——提醒的措辞
  * 指向「你上一步在想什么」，节流的计次也应当跟着它走。
  * @param state - 上一次的状态；首次调用传 `undefined`。
- * @param sampledTurn - 产出该思考的 turn。
+ * @param sampledTurn - 产出该输出的 turn。
  * @returns 放行时返回新状态；应当跳过时返回 `undefined`。
  */
-export declare function admitAnchor(state: AnchorThrottleState | undefined, sampledTurn: number): AnchorThrottleState | undefined;
+export declare function admitPerTurn(state: PerTurnThrottleState | undefined, sampledTurn: number): PerTurnThrottleState | undefined;

package/dist/throttle.js

@@ -1,5 +1,5 @@
 /**
- * 锚定注入的节流。
+ * 提醒注入的节流：**同一 turn 至多一次**。
  *
  * 实测（2026-09-21，会话 `session-502b3e2b`，记录见设计方案 §12.4）：漂移持续时**每个
  * step 都会判定为漂移**，于是同一个 turn 内会连着注入多条几乎一样的提醒——观测到 3 连注，
@@ -8,23 +8,26 @@
  * 所以收紧到「同一 turn 至多一次」：turn 是用户能感知的自然边界，重试留到下一轮，
  * 而不是在一步之内反复催促。上限写成常数而不是配置项，是因为**没有数据支撑别的取值**；
  * 等无对抗的自然漂移样本出来，再决定要不要放宽（设计方案 §八 第 9 条）。
+ *
+ * 退化提醒复用同一契约、独立一份状态：两类提醒的判据无关，共用状态会让先说的那类
+ * 把另一类挡在门外。
  * @module @max-null/dsh-allostasis/throttle
  */
-/** 锚定在单个 turn 内的注入上限。 */
-export const MAX_ANCHORS_PER_TURN = 1;
+/** 同一 turn 内的提醒注入上限。 */
+export const MAX_PER_TURN = 1;
 /**
  * 判定本次是否放行，并推进状态。
  *
- * `sampledTurn` 是**产出那段被判定漂移的思考**的 turn，不是当前 turn——锚定的措辞
+ * `sampledTurn` 是**产出那段被判定异常的输出的 turn**，不是当前 turn——提醒的措辞
  * 指向「你上一步在想什么」，节流的计次也应当跟着它走。
  * @param state - 上一次的状态；首次调用传 `undefined`。
- * @param sampledTurn - 产出该思考的 turn。
+ * @param sampledTurn - 产出该输出的 turn。
  * @returns 放行时返回新状态；应当跳过时返回 `undefined`。
  */
-export function admitAnchor(state, sampledTurn) {
+export function admitPerTurn(state, sampledTurn) {
     const current = state ?? { lastTurn: Number.NaN, inTurn: 0, count: 0 };
     const inTurn = current.lastTurn === sampledTurn ? current.inTurn : 0;
-    if (inTurn >= MAX_ANCHORS_PER_TURN)
+    if (inTurn >= MAX_PER_TURN)
         return undefined;
     return { lastTurn: sampledTurn, inTurn: inTurn + 1, count: current.count + 1 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-allostasis",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "应变（allostasis）：会话状态的自我调节。第一期：中文思考的漂移检测与近因锚定",
   "license": "MIT",
   "publishConfig": {
@@ -13,16 +13,26 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./client": "./dist/client.js"
   },
   "files": [
     "dist",
     "cordis.patch.yml",
-    "tools"
+    "tools",
+    "docs/shots"
   ],
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-chat",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
     }
   },
   "keywords": [
@@ -42,28 +52,31 @@
     "url": "git+https://github.com/Max-Null/dsh-allostasis.git"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && tsdown",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "zod": "^4.4.3"
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.7-rc.2"
+    "@deepseek-ai/dsh-agent": ">=0.1.7-rc.1 <0.3.0",
+    "@deepseek-ai/dsh-llm": ">=0.1.7-rc.1 <0.3.0",
+    "@deepseek-ai/dsh-session": ">=0.1.7-rc.1 <0.3.0"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
-    "tsx": "^4.0.0",
-    "typescript": "^5.5.0",
-    "vitest": "^2.1.0",
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-agent": "^0.1.7-rc.2",
     "@deepseek-ai/dsh-llm": "^0.1.7-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.7-rc.2"
+    "@deepseek-ai/dsh-session": "^0.1.7-rc.2",
+    "@types/node": "^26.2.0",
+    "@types/react": "~18.3.31",
+    "react": "^18.3.1",
+    "tsdown": "^0.22.14",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
   }
 }