# 更新日志

[English](CHANGELOG.en.md) | 中文

`dsh-jev-tools` 的重要变更，采用 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) 格式，
版本号遵循[语义化版本](https://semver.org/spec/v2.0.0.html)。本项目处于 1.0 之前：次版本号
可能包含破坏性变更，真发生时下面的 `Removed` / `Changed` 小节会写明。

## 版本现状

| 版本 | 日期 | 状态 | 摘要 |
|---|---|---|---|
| `0.1.3` | 2026-09-21 | **已发布** | README 重写；能力与 `0.1.2` 相同。 |
| `0.1.2` | 2026-09-21 | **已发布** | 源码安装可用；能力与 `0.1.1` 相同。 |
| `0.1.1` | 2026-09-21 | **已发布** | 文档修正；能力与 `0.1.0` 相同。 |
| `0.1.0` | 2026-09-20 | **已发布** | 首个版本，包含下面描述的全部内容。 |

已发布到 npm：`npm i dsh-jev-tools`。也可以直接从仓库检出目录安装。

## [0.1.3] — 2026-09-21

### Changed

- README 改为更精简的结构：能力、安装、配置、数据边界、设置、排查、已知局限、台账、开发。
  删掉了 Jev 教程式的长篇介绍与路线图部分，关键事实一条没少。

### Fixed

- `cordis.patch.yml` 的头部注释此前只列了部分能力，现在按实际能力列全。

## [0.1.2] — 2026-09-21

### Fixed

- 从 GitHub 源码安装现在会自动构建：`package.json` 增加了 `prepare` 脚本。在此之前源码安装能装上，
  但 `lib/` 是构建产物、不在仓库里，装完没有入口文件可加载。从 npm 安装不受影响。

## [0.1.1] — 2026-09-21

### Fixed

- README 与 CHANGELOG 里与发布状态有关的表述已改为与实际情况一致（此前写的是"尚未发布"），
  README 顶部补上 npm 版本与许可证徽章。
- README 中"只有两项能力"的旧描述改为按当前实际能力陈述。

## [0.1.0] — 2026-09-20

### Added

- **超长工具结果的语义剪枝**（`tools/post-execute`），作用于
  `read` / `grep` / `glob` / `web_fetch` / `web_search`。Jev 逐段判断与当前任务的相关性，
  丢掉不相关的段落，并留下一条可见提示。它**只排序、不卡阈值**，保留确定性的首尾保底，
  且**纯 fail-open**。真实 API 实测：`read: 4613 → 2624 tokens`。
- **试运行模式**（`prune.shadow`）：判定与记账完全照常，但一个字都不改——每个 payload
  会报告它**本来会**削掉什么。它存在的意义是让取舍在**被信任之前**先被看清；它的记录
  不计入削减总量，因为什么都没被削减。
- **注入筛查**（抓取内容，`web_fetch` / `web_search`）：判定一个页面里"存在针对 AI 的指令"
  的概率，并附加一条提醒。**仅提醒**——它绝不拦截调用，也绝不改写内容。它跑在剪枝阈值
  **之下**（最危险的页面是短的那个），并且在有剪枝请求可以搭车时搭同一次请求。
- **技能推荐**（`agent/pre-step`）：每轮至多一条建议，低于置信度下限时保持沉默，且是严格
  意义上的建议——它从不拒绝任何 step。
- **`jev_ask`** —— 面向模型的工具，可提任意带类型的问题（`noul` / `choice` / `score`）；
  在内容离开本机之前，逐条校验官方文档写明的每一项限制。
- **`jev_gate`** —— 面向模型的工具，在宣布做完之前核对交付：用**实际提供的证据**逐条判定
  完成声明（`verified` / `contradicted` / `not_addressed`），并给出整个交付的一个动作
  （`auto` / `review` / `escalate`）。这是本插件唯一一处**把自己那条 fail-open 规矩倒过来**
  的能力：每一条含糊的路径都落到 `escalate`，因为闸门 fail-open 就等于 fail 到「通过」。
- **判定台账**，只含元数据；累计计数器与有上限的记录集**分开存放**，所以淘汰不会让累计
  数字变小。它同时记录「确定性基线会保留多少」与「语义选择实际保留多少」，使净增量成为
  一个**被测出来的数字**而不是一种说法。profile 提供 `storageDomain` 时持久化，否则留在内存。
- **`/jev-status`** —— 启用状态、key 来源、判定次数、台账存放位置，以及**每一次跳过的原因**。
- **双语输出**，覆盖一切给人看的东西：设置卡片跟随 DSH 界面语言，会话提示、`/jev-status`
  与工具报告跟随对话语言。
- **度量工具**：`scripts/trigger-rate.ts`（从本地会话日志统计触发率；无需 key、无网络）与
  `scripts/measure.ts`（标注集标定，或台账自身的增量报告）。
- **192 个测试**，覆盖剪枝管线与每一条跳过守卫、重试/退避矩阵、请求校验、凭据策略、
  台账持久化与重启连续性、注入筛查、闸门的决策矩阵，以及架构分层（分层由测试强制，
  而非靠约定）。

### 默认值及其依据

下面每一个都来自对 72 个真实会话、4653 条真实工具结果的测量，而不是偏好。
数字在 `docs/s0-trigger-rate.md`。

| 配置项 | 默认值 | 依据 |
|---|---|---|
| `prune.minTokens` | `2000` | 延迟由配额支配而非阈值；在超长结果中，此值保留 31.9% 的可节省量 |
| `prune.perTurnLimit` | `3` | 不设上限时最坏一个 turn 增加 8.1 秒；限 3 后 0.9 秒 |
| `prune.toolAllowlist` | `read` `grep` `glob` `web_fetch` `web_search` | 覆盖 76% 的超长结果；**刻意不含 `pwsh`** |
| `prune.headLines` / `tailLines` | `40` / `40` | 确定性保底，不可协商 |
| `prune.keepHigh` | `0.5` | 达到此相关度的段落无条件保留 |
| `prune.minKeepRatio` | `0.2` | 绝不把结果削成空壳 |
| `prune.minSaving` | `0.15` | 低于此值，失真不值得那点 token |
| `prune.minTaskChars` | `12` | 拿"继续吧"去判相关性只会得到噪声 |
| `screen.minTokens` | `300` | 低于此长度，文本承载不了注入指令 |
| `screen.threshold` | `0.75` | 附加提醒的注入概率阈值 |
| `suggest.minCatalogSize` | `15` | 实测目录：最小 27、中位 29 |
| `suggest.minConfidence` | `0.3` | 低于此值不注入任何建议 |
| `sessionCallLimit` | `200` | 成本与内容出境的硬上限 |

### 已知局限

- **不存在准确率数字。** 唯一的质量证据是 8 条自造中文三分类样本上的 8/8，而且
  **从未与宿主模型做过对照**。项目自己的计划要求过这项对照，它没有被完成。
- **概率不是标定概率。** 实测：在简单输入上饱和到 `1.000`，在困难输入上又系统偏低。
  可以当排序用，绝不能当"正确率"用，也不要在简单区间上按固定置信度设闸门。
- **标定是一条就绪但未接线的回路。** `src/calibrate.ts` 没有任何运行时代码调用它：拟合曲线
  需要每条判定的概率与后来可观察的对错，而 `noul` 答案不含 confidence 字段，同时也没有
  任何机制报告"被剪掉的那段后来是否真的需要"。
- **`/jev-status` 与技能推荐从未在真实会话中被观察到。** 两者都有逻辑层测试，但都没有在
  harness 里被亲眼看见工作。
- **完成度闸门是判断，不是证明。** 它不跑测试、不应用补丁；它对输入有上限（截断即禁止
  `auto`）；它的字段隔离只是指令层面的——diff 里藏着的提示注入靠措辞缓解，而不是靠硬边界。
- **两个 harness 进程共用一个存储根**时，累计计数器是最后写入者胜；域设施的"单次打开"
  保证只在进程内生效。

## 兼容性

| 对象 | 要求 |
|---|---|
| DSH 版本 | `0.1.6-alpha.2`，声明在 `package.json` 的 `dsh.compatibility` 里 |
| Node.js | `>= 20`（`engines`）；开发与测试使用 24 |
| 必需的 DSH 服务 | 无。所有服务都是软注入的，缺少任何一个插件仍会挂载并可见地降级 |
| 可选的 DSH 服务 | `credentials`、`settings`、`tools`、`commands`、`skills`、`storageDomain`、`toolResultPruner` |
| 包依赖 | 只有 `@deepseek-ai/schemastery`。DSH 各包是**可选** peer 依赖：npm 上发布的那些严重滞后于部署，因此刻意不 import 它们的类型 |