@max-null/dsh-allostasis 0.2.0 → 0.3.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-allostasis",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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,7 +52,7 @@
     "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"
@@ -57,13 +67,16 @@
     "@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"
   }
 }

package/dist/events.d.ts

@@ -1,67 +0,0 @@
-/**
- * 退化触发的会话事件——「插件当时判了什么」的落盘。
- *
- * 判定输入本来就可重放（推理原文在日志的 `reasoning-chunks.texts`，占用与压缩点在
- * `data.usage` / `compaction/start`），所以「如果当时阈值是 X 会怎样」能离线回答。
- * 缺的是**插件实际用过的阈值与判定结果**：只靠重算，复盘的是「按现在的脚本判会怎样」，
- * 不是「插件当时判了什么」，两个口径会随时间漂移。这个事件补的就是这道缝
- * （设计方案 §4.3 选项 A）。
- *
- * `SessionEventMap` 是 merge-extensible 的，内核的会话 invariant 对未知事件类型直接
- * 放行——「Merge-extensible event relations belong to their owning plugin」
- * （`packages/core/session/src/invariant.ts:165-167`），因此这里不需要在内核侧登记。
- *
- * @module @max-null/dsh-allostasis/events
- */
-import type { RepetitionMetrics } from './repetition.ts';
-declare module '@deepseek-ai/dsh-session/types' {
-    interface SessionEventMap {
-        /** 一次退化触发；只记录判定，不记录干预——压缩动作是否发生由压缩事件自己回答。 */
-        'allostasis/degeneration': DegenerationEvent;
-    }
-}
-/** 落盘时每个重复单元的截断长度；够复盘看出重复的是什么，又不让日志被碎片撑大。 */
-export declare const UNIT_SAMPLE_MAX_CHARS = 80;
-/** {@link degenerationEvent} 的输入。 */
-export interface DegenerationTrigger {
-    /** 产出该推理的 turn。 */
-    readonly turn: number;
-    /** 产出该推理的 step。 */
-    readonly step: number;
-    /** 该步的重复度量化结果。 */
-    readonly metrics: RepetitionMetrics;
-    /** 已连续越线的步数。 */
-    readonly consecutive: number;
-    /** 判定所用的重复率阈值。 */
-    readonly threshold: number;
-    /** 触发所需的连续步数。 */
-    readonly required: number;
-}
-/** `allostasis/degeneration` 的 payload：一次触发的完整判定依据。 */
-export interface DegenerationEvent {
-    /** 产出该推理的 turn。 */
-    turn: number;
-    /** 产出该推理的 step。 */
-    step: number;
-    /** 触发时的重复率。 */
-    ratio: number;
-    /** 单元总数，即重复率的样本量。 */
-    units: number;
-    /** 已连续越线的步数。 */
-    consecutive: number;
-    /** 判定所用的重复率阈值。 */
-    threshold: number;
-    /** 触发所需的连续步数。 */
-    required: number;
-    /** 最高频的重复单元，按出现次数降序，单元已截断。 */
-    top: Array<{
-        unit: string;
-        count: number;
-    }>;
-}
-/**
- * 把一次触发整理成事件 payload。
- * @param trigger - 触发时的判定依据。
- * @returns 可直接交给 `session.append` 的 payload。
- */
-export declare function degenerationEvent(trigger: DegenerationTrigger): DegenerationEvent;

package/dist/events.js

@@ -1,40 +0,0 @@
-/**
- * 退化触发的会话事件——「插件当时判了什么」的落盘。
- *
- * 判定输入本来就可重放（推理原文在日志的 `reasoning-chunks.texts`，占用与压缩点在
- * `data.usage` / `compaction/start`），所以「如果当时阈值是 X 会怎样」能离线回答。
- * 缺的是**插件实际用过的阈值与判定结果**：只靠重算，复盘的是「按现在的脚本判会怎样」，
- * 不是「插件当时判了什么」，两个口径会随时间漂移。这个事件补的就是这道缝
- * （设计方案 §4.3 选项 A）。
- *
- * `SessionEventMap` 是 merge-extensible 的，内核的会话 invariant 对未知事件类型直接
- * 放行——「Merge-extensible event relations belong to their owning plugin」
- * （`packages/core/session/src/invariant.ts:165-167`），因此这里不需要在内核侧登记。
- *
- * @module @max-null/dsh-allostasis/events
- */
-/** 落盘时每个重复单元的截断长度；够复盘看出重复的是什么，又不让日志被碎片撑大。 */
-export const UNIT_SAMPLE_MAX_CHARS = 80;
-/**
- * 把一次触发整理成事件 payload。
- * @param trigger - 触发时的判定依据。
- * @returns 可直接交给 `session.append` 的 payload。
- */
-export function degenerationEvent(trigger) {
-    const { metrics } = trigger;
-    return {
-        turn: trigger.turn,
-        step: trigger.step,
-        ratio: metrics.ratio,
-        units: metrics.units,
-        consecutive: trigger.consecutive,
-        threshold: trigger.threshold,
-        required: trigger.required,
-        top: metrics.top.map(entry => ({
-            unit: entry.unit.length <= UNIT_SAMPLE_MAX_CHARS
-                ? entry.unit
-                : `${entry.unit.slice(0, UNIT_SAMPLE_MAX_CHARS)}…`,
-            count: entry.count,
-        })),
-    };
-}