# v0.2.4 — 单次筛选、研究恢复与安全接入管理

这是稳定版源码交付说明，汇总 v0.2.3 之后的 beta.1–beta.9 演进与最终审查修正。Node.js 下限仍为 `>=22.13`。版本提交和面向 `master` 的 PR **不等于** npm 发布；npm dist-tag、GitHub Release 及合并均是独立操作。本次准备不执行 npm publish、不移动 dist-tag、不创建发布标签，也不自动合并。

## 主要变化

- **Adaptive V5**：一个完整问题和研究方向，经一次 Jev 策略选择与一次 fused 检索，对完整声明快照做安全/价值/来源折扣筛选。目标 ≤10 时最多 32 个候选，更大目标按相同比例扩大至最高 160；无数量达标提前停止、关键词扩展、逐材料 constraints 门槛、自动页面补读或自设累计预算。评分、筛选标签、`targetMet` 和数量都不证明事实正确或研究完整。
- **研究保存与恢复**：显式 `save_results:true` 可保存完整选中集合与元数据到私有 v2 文件；`saved_result_id`、cursor 和 CLI `research list` / `research export` 支持离线恢复。历史 v1 快照只读展示原状态，不重新检索、不改写为 V5，不刷新证据日期。工具关闭与 Jev 配置锁仍适用于工具入口的历史读取。
- **网页/PDF 读取**：PDF 转为有界文本，保留取消、大小/页数限制和抽取不足说明；二进制、不可抽取文件及真实网络/策略失败不伪装为正文。可选 PDF 依赖已更新，并有真实离线 PDF 回归。
- **DSH CLI/Desktop**：独立发现与所属运行时校验、锁与事务备份/恢复、载荷与实际来源验证；保留禁用状态。Desktop 支持默认目录、PATH、显式 launcher 和 Windows 注册表元数据发现，以及由用户在 Desktop 界面添加持久本地目录的只读等待流程；无 npm DSH 接管 Desktop 的兜底。
- **接入管理与 TUI**：默认平铺首页，保留文件夹布局、中英切换及损坏配置导航。安装、刷新、卸载分离；软件更新由 npm 负责，刷新只同步当前持久包的已有接入。卸载默认取消，按预览范围执行；Grok 缓存重建需要单独明确同意，普通 `-y` 不授予重建或信任权限。
- **宿主说明与 CI**：MCP/Pi/DSH 共用工具描述，清楚区分 Fused、Adaptive、fetch、X 与研究子任务的职责及配置/权限边界。CI 保留四个平台/Node cell，并统一静态、依赖审计和有毒调用者隔离门禁；生成资产与实际 npm/global/npx 工件独立验收。

## 从 v0.2.3 迁移

实际稳定版本发布后：

```sh
npm install -g search-boost@0.2.4 --prefer-online
search-boost
# 管理 Agent 接入 → 刷新已有接入 → 选择精确范围
# 或刷新全部已有接入：
search-boost refresh -y
# 先仅预览：
search-boost refresh --dry-run
```

- 重启受影响宿主和 MCP 服务。安装目录或插件清单版本不证明已经运行的服务加载了新包；未固定版本的 npx 启动项还需独立核验。
- `upgrade` 和 `--sync-only` 已移除。npm 更新软件后用 `refresh`；`migrate` 仅负责旧全局 `search-boost-mcp` 包更名，不代替日常软件更新或修改 Agent 配置。详见 [迁移说明](migration.md) 与 [接入刷新](host-upgrades.md)。
- `adaptive_search` 不再接受 V3 的 `tasks` / `keywords` 等输入；新研究只接受一个 `questions` 元素与必填 `intent`。非空 `constraints` 明确拒绝，空数组仅兼容忽略并告警。`preferences` 是独立软偏好，而非准入条件。
- 新输出是 `schemaVersion=5`，不再返回 `coverageComplete` / `retrievalSufficient` / `keywordProgress` 等旧字段。用 `selection.incomplete`、`stopReason`、诊断计数及 warnings 判断执行状态；`targetMet` 只表示数量。
- 新运行 cursor 是进程内 `s5:`，历史 v1 读取是 `h1:`；旧裸 UUID.offset 与实验 `s4:` cursor 不兼容。重启后需保存的 ID，而不是旧 cursor。详见 [Adaptive 契约](jev-adaptive-search.md) 与 [筛选迁移](adaptive-screening-migration.md)。

## 最终审查修正

最终审查以 beta.9 的 `4e14650` 为基线，两路独立只读审查覆盖搜索/恢复与安装/刷新安全。以下缺陷均先以隔离回归重现，再修正：

1. **合法长输入分页失败**：最大长度中文或 JSON 转义输入可能超过 16,000 字节页面元数据预算，造成完成筛选甚至写入私有快照后仍抛异常。现仅缩短页面 `inputSummary` 的 Unicode 完整前缀并告警；真实检索/判断输入、完整私有输入、已审摘录、计数和使用量不变。新增最大输入、完整 160 候选/50 结果、保存/恢复及零网络分页回归。
2. **卸载范围披露与冻结**：Antigravity 原先预览“无工作区”却执行全部已登记工作区卸载。现先读取并展示准确列表，再将该列表传入执行；确认期间新增工作区不会被移除。Grok 原生插件全局注册/缓存移除也在预览中明确披露，不被 project MCP 作用域隐藏；`--skip-grok-plugin` 仍保留原生插件。
3. **精确刷新误报失败**：未选宿主的发现错误保留为跳过说明，不再使已选且成功的范围失败；不可用的已选目标、真实执行失败和全范围刷新中的发现失败仍阻塞。
4. **首次 Desktop dry-run**：已有合法 launcher 但尚未初始化 profile 时允许显示计划，不写入 profile。真实执行仍要求初始化、退出宿主并尊重应用锁；缺失 launcher 仍失败，不回退 npm DSH。

未改变筛选算法、评分系数、宿主信任默认值、网络策略或真实用户配置。

## 审查中的非阻塞边界

- `unreviewed` 是未进入判断或快照外的计数，不是“所有有效判断已完成”的布尔证明；已派发但判断不可用另计，失败/取消原因查看 `stopReason`、`judgeFailures`、不可用计数与 `selection.incomplete`。已澄清文档，不变更历史诊断计数语义。
- DSH 恢复标记和官方 package run 记录有意阻止新写入，不自动清理。先退出宿主、确认前次包管理进程停止并按私有备份恢复/核验，再由维护者处理标记；不能直接删锁/标记后强行重试。已有安全恢复步骤见 [Desktop 接入说明](dsh-desktop.md)。本次不新增自动恢复命令。
- **沿用的 Grok 安装兼容行为**：重新安装时清理本工具 marked 权限块与未标记的旧 `MCPTool(search-boost__...)` 规则；不能仅凭相同文字区分旧注入和用户手写规则。拒绝自动授权可能撤销这些匹配的旧规则，这不是无操作。需要保留手写权限时先备份/审核；刷新已有接入不会执行这项安装迁移。本次不改写旧权限迁移算法。

## 验证义务与限制

本地最终门禁为 `npm run prepublishOnly`：语法、CI 结构/策略、精确依赖锁审计和全部隔离入口，包含生成资产、真实 PDF、适配器、安装/刷新/卸载、研究恢复与实际 npm/global/npx 分发。另审查最终 npm tarball 的版本、文件集合及源码字节。最终提交的 Linux Node 22.13、Windows Node 22、macOS Node 22、Linux Node 24 CI 仍需与准确提交/PR 对应；旧 beta.9 的绿色结果不是新提交的验收。

离线 fixture 与平台 CI不证明真实 Desktop/Electron/ASAR GUI 加载、真实注册表形态、付费 Jev/X、在线覆盖率、筛选语义质量或 Agent 必然遵循提示词。未经这些实际验证，不将它们写成通过。本次不修改用户真实宿主配置、缓存、信任或凭据。

## 回退

保留配置与私有事务备份，必要时显式安装 `search-boost@0.2.4-beta.9`，按该版本的 dry-run 和管理入口审核后刷新，并重启宿主。若回到 `0.2.3`，其 V3 契约和 `upgrade --sync-only` 是旧版行为，不能将 V5 保存文件或新管理命令当作自动逆迁移保证。不要删除 profile/数据、绕过信任或移动 npm dist-tag 来伪造恢复。

## English summary

v0.2.4 brings schema-V5 single-snapshot screening, explicit private research save/offline recovery, bounded PDF text extraction, DSH Desktop integration and scoped integration management. npm owns package updates; `refresh` uses the current durable package, while `migrate` only renames the retired global package. V3 adaptive inputs/outputs and `upgrade --sync-only` are no longer the current contract.

Final review fixes legal long-input page failures without clipping evidence, freezes and discloses removal scopes, scopes refresh failures to selected targets, and allows a first-launch Desktop dry-run without initializing the profile. Scores and quantity never verify truth or completeness. This PR prepares version 0.2.4; npm publication, tags, merging and GitHub Releases are separate actions. Real GUI/paid-service behaviour remains outside offline verification.