# Changelog

## 1.7.2 - 2026-10-24

适配 dsh `0.2.1-rc.3`。rc.3 发布说明仅 UI 改进（侧栏「更多」菜单）与草稿修复，
**官方插件规范与 rc.2 字节相同**；本轮做完整链路复核 + 声明对齐。

### 变更

- **声明对齐 rc.3**：`engines.dsh` 升 `^0.2.1-rc.3`；peers/devDeps 的
  `dsh-agent-preset-registry`、`dsh-llm` 升 `^0.2.1-rc.3`（cordis 保持 `^4.0.5`）。
- **完整作用链路复核（rc.3 实测全部未变）**：
  - 门禁 `unmetRequirements`：`engines.dsh` 优先、peer 被忽略；
  - icon：`iconOf` 顶层 `icon` 优先、回退 `./icon` 导出；
  - locale：`${specifier}/locale/en.json` 子路径解析；
  - client：`dsh.client.platform:"web"` + `exports["./client"]` 扫描条件；
  - API：`agentPresets`（服务名 + resolve/mount/serviceFor）、`agents.create(options)`、
    `workspaceRegistry` 三件套、`compactNow(agent, signal, commandId)`、
    `commands.register`、`requestHeader/deriveMessages`、seed 四类事件词表、
    `BlockAssembler/createUserMessage`。
- **真机端到端验证**（隔离 profile）：npm 安装 → 门禁 0 跳过 → entry 进组合树 →
  `[fresh-start] installed: /fresh command registered` → client 组合脚本 200 →
  `readPluginMeta` 双语元数据 + icon 无 error。
- 66 断言（57+9）ALL PASS。

### 排障记录：`pending (waiting for services)` 的真实成因

首次验证时 entry 报 `pending (waiting for services: agentPresets, workspaceRegistry)`。
排查确认**不是 rc.3 兼容性问题**，而是该测试 profile 的
`dsh.profile.bundles` 只有 `["@deepseek-ai/dsh-base", "dsh-fresh-start"]`——
缺少 `@deepseek-ai/dsh-web-app`（这两个服务由它提供）。补上 web-app 后立即正常激活。
`--from-default-profile web` 初始化被中断时可能留下不完整的 bundles 列表，遇到此类
pending 应先核对 bundles 是否含 web-app。

## 1.7.1 - 2026-10-17

适配 dsh `0.2.1-rc.2`。rc.2 本身是模型/Search API 适配的小版本，**官方插件规范与
rc.1 完全一致**（`cordis-plugin-development` skill 文件字节相同）；本轮做完整链路
复核 + 声明对齐。

### 变更

- **声明对齐 rc.2**：`engines.dsh` 升 `^0.2.1-rc.2`；peers/devDeps 的
  `dsh-agent-preset-registry`、`dsh-llm` 升 `^0.2.1-rc.2`（cordis 保持 `^4.0.5`）。
- **完整作用链路复核（0.2.1-rc.2 实测）**：
  - 门禁 `unmetRequirements`：`engines.dsh` 优先、peer 被忽略的规则未变；
  - icon：`iconOf` 仍优先顶层 `icon`、回退 `./icon` 导出，路径/大小/格式校验未变；
  - locale：仍经 `${specifier}/locale/en.json` 子路径解析；
  - client：`dsh.client.platform:"web"` + `exports["./client"]` 扫描条件未变；
  - API：`agentPresets`（服务名与 resolve/mount/serviceFor）、`agents.create(options)`、
    `workspaceRegistry` 三件套、`compactNow(agent, signal, commandId)`、
    `commands.register`、`requestHeader/deriveMessages`、seed 三 knob 事件词表、
    `BlockAssembler/createUserMessage` 全部健在。
- **真机端到端验证**（隔离 profile）：npm 安装 → 门禁 0 跳过 → entry 进组合树 →
  启动日志 `[fresh-start] installed: /fresh command registered` → client 组合脚本
  200 → `readPluginMeta` 双语元数据 + icon 无 error。
- 66 断言（57+9）ALL PASS。

### 0.2.1-rc.2 的插件管理相关变化

- 发布说明层面：新增 DeepSeek-V4.1-Flash-1017 模型适配、DeepSeek Search 与 Fetch
  API 支持；无插件规范破坏性变更。
- **实测发现：pnpm 新版本冷却策略**（0.2.1 起）——`dsh plugin add <pkg>` 默认不会
  安装刚发布不久的版本（1.7.0 发布约 8 小时后仍解析到 1.6.1）。需要最新版时用
  **精确版本** `dsh plugin add <pkg>@<version>`，插件管理器会把它写入
  `pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude`。这是预期行为，非插件缺陷。

## 1.7.0 - 2026-10-17

适配 dsh `0.2.1-rc.1`，按 0.2.1 更新后的官方插件规范（`cordis-plugin-development`
skill）升级。插件代码零改动。

### 变更

- **兼容性声明改用 `engines.dsh`**（0.2.1 首选形式）：0.2.1 的
  `unmetRequirements` 规定「own `engines.dsh` 存在时单独决定兼容性，
  `peerDependencies` 被完全忽略」；此前只有 peer 一条路。现声明
  `engines: { node: ">=22", dsh: "^0.2.1-rc.1" }`，语义更明确且不再受
  peer 列表逐项比对影响（peer 保留供包管理器使用）。
- **`exports` 新增 `./icon`**：0.2.1 规范的 display checklist 要求导出
  `./locale/*.json` 与 `./icon`。宿主 `iconOf` 优先读顶层 `icon` 字段、缺失时
  回退 `./icon` 导出——两条路径现已都指向 `./icon.svg`。
- **依赖线对齐 0.2.1**：peers/devDeps 升 `@deepseek-ai/dsh-llm@^0.2.1-rc.1`、
  `@deepseek-ai/dsh-agent-preset-registry@^0.2.1-rc.1`、cordis `^4.0.5`
  （宿主树为 4.0.5）。
- **API 面核对（0.2.1 全绿）**：`agentPresets` 服务名与 `resolve/mount/serviceFor`
  不变；`agents.create(options)`；`workspaceRegistry` 的
  `archiveSession/resolveByPath/attachSession`；`compaction.compactNow(agent,
  signal, commandId)`；`commands.register`；`session.requestHeader/deriveMessages`；
  seed 三 knob 事件词表；`BlockAssembler/createUserMessage`；
  `dsh.client.platform:"web"` 与组合脚本交付。
- **真机验证**（隔离 profile，生产 profile 未动）：门禁 0 跳过、entry 进组合树；
  启动日志 `[fresh-start] installed: /fresh command registered`；client 组合脚本
  200；宿主 `readPluginMeta` 读出双语标题/描述与 icon data URI，无 error；
  66 断言（57+9）ALL PASS。

### 0.2.1 的插件管理变化（背景）

- 新增自定义插件索引源（`dsh-experimental-plugin-market-bundle`），可从第三方源
  发现与安装插件；
- 插件启用/停用/卸载/更新后自动同步依赖，HMR 开启时可替换插件直接生效；
- 可选插件支持极简模式，官方插件列表支持按需安装；
- 新增实验性 Session 状态记录接口供插件读写自身会话记录。

## 1.6.1 - 2026-10-11

npm 发布准备：按 dsh 官方 bundle 规范与权威插件（dsh-better-sidebar /
dsh-checkpoint-rewind / dsh-rules-manager）形态补齐发布元数据。

### 变更

- **新增 Plugin Manager 显示元数据**（官方 `cordis-plugin-development` skill
  「Display metadata and icon」规范）：`locale/en.json` + `locale/zh.json`
  （`meta.title` / `meta.description`）与 `icon.svg`；`package.json` 增加顶层
  `icon` 字段、`exports` 暴露 `./locale/*.json` 与 `./cordis.patch.yml`
  （宿主 `readPluginMeta` 经 `${specifier}/locale/en.json` 子路径解析，缺则卡片
  退化为默认文案）。已用宿主 `readPluginMeta` 实测：双语标题描述与 icon
  data URI 均正确读出。
- **发布元数据**：`engines.node >= 22`、`publishConfig.access: "public"`、
  `prepublishOnly` 自动跑测试、`files` 补 `locale/*.json` / `icon.svg` /
  `README.md` / `LICENSE` / `CHANGELOG.md`。
- **发布物验证**：`npm pack --dry-run` 产出 10 文件 / 23.0 kB；tarball 装入隔离
  profile 实测——门禁 0 跳过、`[fresh-start] installed: /fresh command registered`
  正常输出、locale 与 icon 就位。
- README 安装节新增 npm 渠道（`dsh plugin --profile web add dsh-fresh-start`）与
  Plugins 页说明；新增「发布」章节记录发布物与官方规范对应关系。

## 1.6.0 - 2026-09-30

适配 dsh `0.2.0-rc.2`（大版本更新）。**唯一破坏点是 0.2.0 新增的 peer 版本门禁**，
插件代码零改动；peer 声明升级即可恢复加载。

### 变更

- **peer 版本门禁（0.2.0 新增，已用官方 0.1.7 app-boot 比对确认）**：宿主启动时经
  `dsh-app-boot` 的 `evaluatePluginCompatibility` 校验每个 profile bundle 的
  `peerDependencies` 中所有 `@deepseek-ai/dsh` / `@deepseek-ai/dsh-*` 范围是否满足
  运行时版本（预发布参与比较，`includePrerelease: true`）；不满足则
  `skipping profile bundle` 并整体跳过（旧版静默加载）。1.5.1 的 `^0.1.7-rc.2` 对
  `0.2.0-rc.2` 不成立 → 被跳过。**修复**：两个 dsh peer 升 `^0.2.0-rc.2`；
  `@deepseek-ai/cordis` 无 `dsh-` 前缀，不参与校验（保持 `^4.0.4`）。
- **client 半边交付形式变化（不影响本插件，但排障须知）**：0.2.0 起 client 脚本
  由「每包一个 `/plugins/<pkg>/client.js`」改为**组合脚本**
  `plugins/??pkg1/client.js,pkg2/client.js&rev=<hash>`；裸包路径不再响应（404 属
  正常），排障时须带 `?rev=`。本插件的 `dsh.client.platform:"web"` +
  `exports["./client"]` 声明满足新扫描条件，实测已被正确组合。
- **真机端到端验证（隔离测试 profile，未触碰生产 web profile）**：
  - 门禁放行：`dsh --dump-config` 中 `dsh-fresh-start` 无 `skipping` 行，patch 层
    `- id: fresh-start` 进入组合树；`dsh plugin add` 还自动将其加入
    `dsh.profile.bundles`（0.2.0「安装即启用」）；
  - 宿主激活：真实 web 结构 profile 启动日志输出
    `[fresh-start] installed: /fresh command registered`（`/fresh` 注册成功）；
  - client 交付：`plugins/??dsh-fresh-start/client.js&rev=…` 返回 **200 / 3420 B**，
    内容含 `__ModuleLoader__` 注册与 `host/archived-sessions-changed` / `parentId` /
    `sessions.open` 全部逻辑；
  - headless profile 下 entry 为 `pending (waiting for services: agentPresets,
    workspaceRegistry)` —— 这两个服务由 **web-app bundle** 提供，headless/base 不含，
    属 profile 差异（cordis inject 等待机制正常），非兼容性问题。
- **插件管理机制重构（不影响本插件形态）**：新增 `dsh-plugin-manager`（服务 +
  Web 侧边栏 Plugins 页），bundle 启用/禁用改为 profile `cordis.patch.yml` 的
  `disabled` 覆盖行，安装/移除走 `pnpm add` 且含 registry 回退与 Git 预检。本插件的
  `dsh.bundle.patch` + `dsh.client.platform` 声明与 `- insert:` patch 形态在新机制下
  仍有效（与在用的第三方 bundle 一致），无需改动。
- **其余 API 在 0.2.0 下逐一核对全部健在**：`agentPresets`（仍由
  `dsh-agent-preset-registry` 提供，服务名与 `resolve/mount/serviceFor` 不变）、
  `agents.create(options)`（`dsh-agent` 的 `AgentRegistry`）、`workspaceRegistry`
  （`dsh-workspace` 提供 `archiveSession / resolveByPath / attachSession`）、
  `compaction.compactNow(agent, signal, commandId)`、`commands.register`、
  `session.requestHeader / deriveMessages`、seed 三 knob 事件词表、
  `BlockAssembler / createUserMessage`、`dsh.client.platform:"web"`。
- 依赖图简化：0.2.0 下 clean install 后无需 `--no-save` 辅助闭包；
  66 断言（57+9）ALL PASS。
- README 徽章与兼容性节更新（含门禁机制说明）。

## 1.5.1 - 2026-09-13

兼容性验证轮：dsh `0.1.7-rc.2`（rc.1 → rc.2，同线收敛），无破坏性变更，
**零代码改动**，仅依赖声明与文档对齐。

### 变更

- **逐包发布产物比对（0.1.7-rc.1 → 0.1.7-rc.2）**：
  - dsh-llm：纯增量（`createDeveloperMessage`、`projectToolUpdates`、tool 声明/
    工具历史助手）；`BlockAssembler` / `createUserMessage` 不变；
  - dsh-agent-preset-registry：服务名与 `resolve / mount / serviceFor` 不变；
    `list()` 默认选中策略简化（移除 `modeSelectionEnabled`，回退
    `selectedDefault ?? default`）——本插件不消费；
  - dsh-session：新增 tool-history 折叠与类型；核心 API 与 seed knob 事件词表未变；
  - dsh-permission-presets：Auto preset approval 策略 `never` → `ask`（及匹配逻辑）；
    本插件 seed 预置 `workspace-write`/`ask`，seeded 分支不变，无影响；
  - dsh-compaction / dsh-client-modules / dsh-command-compact：仅 package.json 重指。
- **依赖声明对齐**：peers/devDeps 升 `^0.1.7-rc.2`；cordis 保持 `^4.0.4`。
- 测试套件在 rc.2 线依赖下重装实跑：66 断言（57+9）ALL PASS。
- README 徽章与兼容性节更新。

## 1.5.0 - 2026-09-12

适配 dsh `0.1.7-rc.1`：宿主包拆分（agent-presets → agent-preset +
agent-preset-registry）、cordis 升 4.0.4、内置 preset 数据格式迁移。
**零代码改动**（服务名与方法面不变），依赖声明迁移 + 文档。

### 变更

- **宿主包拆分**：`@deepseek-ai/dsh-agent-presets` 拆为 `dsh-agent-preset`（agent
  facet）与 `dsh-agent-preset-registry`（服务提供方）。新 registry 仍以
  `super(ctx, "agentPresets")` 注册服务，`resolve / mount / serviceFor / list`
  签名不变。本插件自 1.3.0 起不再 import 该包（只用注入服务），故代码零改动；
  peer/devDeps 从 `dsh-agent-presets` 迁移到 `dsh-agent-preset-registry ^0.1.7-rc.1`。
- **cordis 4.0.2 → 4.0.4**（dsh-llm peer 声明为 `~4.0.4`）：本插件声明同步 `^4.0.4`。
- **内置 preset 数据迁移**：YAML 组合（`agent.cordis.yml`）→
  `dsh-web-app/presets/*.patch.yml`（cordis/minimal/ptc/standard），preset id 不变，
  `/fresh <preset>` 与别名映射不受影响。
- **compaction 面未变**：实现仍在 `dsh-compaction-basic`，`compactNow(agent, signal,
  commandId)` 调用形状与返回字段同前。
- 其余逐一核对未变：`session.requestHeader / deriveMessages`、seed 三 knob 事件在
  词表、permission seeded 分支、`dsh.client.platform:"web"`、`commands.register`、
  `agents.create`（seed/setup/meta.parentSession）、workspaceRegistry 三件套。
- **依赖图简化**：agent-presets 退出后，测试安装不再需要 11 包 `--no-save` 辅助闭包
  （仅 cordis + dsh-llm）；clean install 后 66 断言（57+9）ALL PASS。

## 1.4.0 - 2026-09-11

移除 dsh-std 轨道（原 1.2.10 双轨制引入的惰性清单）。`/fresh` 功能零影响。

### 变更

- **删除**：`dsh-plugin.json`（Community v0.15 清单）、`lib/std/host.js`（占位宿主
  facet 入口）、`tests/std_manifest_test.mjs`；package.json 同步清除 files/
  keywords（dsh-std、community-v0.15）/devDependencies（`@dsh-std/manifest`）与
  test 脚本项；README 移除 dsh-std 徽章与章节。
- **删除理由**：std 生态自 2026-08-31 后停更（core/composition 停在 0.1.0-rc1）；
  其 `adapter-dsh@0.1.1-rc.2` 的 peer 窗口为 `>=0.1.2-alpha.2 <0.1.3`，与本插件当前
  宿主线（`0.1.5-rc.2`）不兼容——该轨道从未在真实宿主中生效（清单始终惰性，占位入口
  空贡献）。保留仅剩发版同步成本与误导性宣传，故移除。
- **重新评估触发条件**：`@dsh-std/adapter-dsh` 发布支持 0.1.5+ 宿主的版本、且 std
  侧补齐可承载 session/workspace 生命周期能力的协议后。
- 测试套件精简为 smoke（57）+ client（9）共 66 断言：ALL PASS（README 断言数同步校准）。

## 1.3.5 - 2026-09-11

兼容性验证轮：dsh `0.1.5-rc.2`（rc.1 → rc.2），无破坏性变更，**零代码改动**，
仅依赖声明与文档对齐。

### 变更

- **逐包发布产物比对（0.1.5-rc.1 → 0.1.5-rc.2）**：本插件用到的七个包
  （dsh-agent-presets / dsh-llm / dsh-session / dsh-compaction /
  dsh-permission-presets / dsh-client-modules / dsh-command-compact）发布产物
  逐字节比对，**lib 与全部数据目录完全一致**，仅 package.json 版本号与依赖范围重指。
- **依赖声明对齐**：peers/devDeps 升 `^0.1.5-rc.2`；cordis `^4.0.2` 不变。
- 测试套件在 rc.2 线依赖下重装实跑：73 断言（34+9+std）ALL PASS。
- `dsh-plugin.json` 版本同步 1.3.5；README 徽章与兼容性节更新。

## 1.3.4 - 2026-09-10

兼容性验证轮：dsh `0.1.5-rc.1`（0.1.5 线内 alpha.1 → rc.1 收敛），无破坏性变更，
**零代码改动**，仅依赖声明与文档对齐。

### 变更

- **逐包发布产物比对（0.1.5-alpha.1 → 0.1.5-rc.1）**：
  - dsh-session：事件词表与 `lib/index.js` 仅**新增** `deliverables/presented`、
    `subagent/catalog` 两个事件类型；本插件 seed 的 `approval/policy` /
    `permission/preset` / `sandbox/mode` 仍在词表；`canonicalHeader` 仍未含
    `system`（1.3.3 记录的降级路径无变化）；
  - dsh-agent-presets：`lib/index.js` 字节级一致；仅内置 preset 组合数据
    （四个 agent.cordis.yml + minimal/preset.yml）与 typert 协议文件更新；
  - dsh-llm：仅 typert 协议文件；dsh-compaction / dsh-permission-presets /
    dsh-client-modules / dsh-command-compact：仅 package.json 重指。
- **依赖声明对齐**：peers/devDeps 升 `^0.1.5-rc.1`（agent-presets 从 alpha.1
  显式对齐；llm 此前已解析到 rc.1 但签名同步）；cordis `^4.0.2` 不变。
- 测试套件在 rc.1 线依赖下重装实跑：73 断言（34+9+std）ALL PASS。
- `dsh-plugin.json` 版本同步 1.3.4；README 徽章与兼容性节更新。

## 1.3.3 - 2026-09-09

兼容性验证轮：dsh `0.1.5-alpha.1`（v1.3.2 时 llm/session/compaction/command-compact
已在 0.1.5 线上；本轮增量 agent-presets、permission-presets、client-modules），
无破坏性变更，**零代码改动**，仅依赖声明与文档对齐。

### 变更

- **逐包发布产物比对（0.1.3-alpha.2 → 0.1.5-alpha.1）**：
  - dsh-agent-presets：`lib/index.js` 字节级一致；typert 协议类型级演进
    （`SurfaceIntent`（仍含 `surfaceOp`）/`EpochHeader.system` 移除/Inbox 接口化）
    为增量与类型调整，不影响运行时；
  - dsh-permission-presets：仅文档与 package.json（seeded 分支不变）；
  - dsh-client-modules：宿主连线重构（webServer 变可选 carrier），声明与
    `window.__ModuleLoader__` 契约不变；
  - dsh-llm/session/compaction/command-compact：与 v1.3.2 验证版本一致（无变化）。
- **已知行为漂移（上游，记录备用）**：0.1.5 起 `session.requestHeader()` 的
  canonical header 不再含 `system`（系统提示迁移到 `createSystemMessage`/
  `systemPromptUpdate` 通道）。插件条件透传安全降级——总结请求将不含 system 提示；
  若需带 system 总结，可改经新通道提取（列为待办，本次未做）。
- **依赖声明对齐**：peers/devDeps 的 `@deepseek-ai/dsh-agent-presets` 升至
  `^0.1.5-alpha.1`（dsh-llm 仍在 `^0.1.5-alpha.1`，cordis `^4.0.2` 不变）；
  `session.header.{cwd,parentSession,agentPreset}` 校验与 `agents.create` 链路逐一
  核对未变。
- 测试套件在 0.1.5 线依赖下重装实跑：73 断言（34+9+std）ALL PASS。
- `dsh-plugin.json` 版本同步 1.3.3；README 徽章与兼容性节更新。

## 1.3.2 - 2026-09-08

兼容性验证轮：dsh `0.1.3-alpha.2`（子包双线：agent-presets/permission-presets/
client-modules `0.1.3-alpha.2`，dsh-llm/session/compaction/command-compact
`0.1.5-alpha.1`），无破坏性变更，依赖声明与文档对齐，**零代码改动**。

### 变更

- **逐包发布产物比对（rc.1 → 新线）**：
  - dsh-agent-presets：`lib/index.js` 字节级一致；仅 typert 协议增量（file 块 /
    AssistantStreamRecord）与内置 preset 组合模板升级（ptc 等系统提示拆 prefix/suffix）；
  - dsh-session：`SESSION_FORMAT_VERSION` 0→3（宿主迁移链处理，插件只消费 host API）；
    显式事件词表含本插件 seed 全部类型（`approval/policy`/`permission/preset`/
    `sandbox/mode`），surfaceOp `append` 豁免校验——seed 形状仍合法；
  - dsh-llm：纯增量（`createSystemMessage`、assistant-stream 助手），
    `BlockAssembler`/`createUserMessage` 不变；
  - dsh-compaction / dsh-permission-presets / dsh-client-modules /
    dsh-command-compact：仅 package.json 重指（lib 一致）。
- **依赖声明对齐**：peers/devDeps 升 `@deepseek-ai/dsh-agent-presets@^0.1.3-alpha.2`、
  `@deepseek-ai/dsh-llm@^0.1.5-alpha.1`（cordis `^4.0.2` 不变）；`agents.create`
  （meta.parentSession/seed/setup）与 `workspaceRegistry` 链路逐一核对未变。
- 测试套件在新线依赖下重装实跑：34+9 断言 + std 清单 ALL PASS（73 断言）。
- `dsh-plugin.json` 版本同步 1.3.2；README 徽章与兼容性节更新。

## 1.3.1 - 2026-09-04

兼容性验证轮：dsh `0.1.2-rc.1`（alpha.5 → rc.1）无破坏性变更，依赖声明与文档对齐。

### 变更

- **逐包发布产物比对（alpha.5 → rc.1）**：本插件用到的七个包（dsh-agent-presets、
  dsh-llm、dsh-session、dsh-compaction、dsh-permission-presets、dsh-client-modules、
  dsh-command-compact）lib 目录**字节级一致**，仅 package.json 版本号与依赖范围重指；
  presets 目录（standard/minimal/ptc/cordis）不变。**零代码改动**。
- **依赖声明对齐**：npm 实测 `^0.1.2-alpha.5` 范围不解析到 rc.1（semver 预发布规则），
  peers/devDeps 升至 `^0.1.2-rc.1`；cordis peer/devDep 对齐宿主树的 `^4.0.2`。
- 测试套件在 rc.1 依赖下重装实跑：34+9 断言 + std 清单 ALL PASS。
- `dsh-plugin.json` 版本同步 1.3.1；README 徽章与兼容性节更新。

## 1.3.0 - 2026-09-03

dsh `0.1.2-alpha.5` 适配轮（跨越式更新）。alpha.5 删除了本插件依赖的
`@deepseek-ai/dsh-agent-presets#resolveSessionPreset`，升级后插件被宿主停用（断点见
dsh 升级执行记录 2026-09-03）；本版为自行适配。

### 变更

- **preset 继承内联实现**：alpha.5 以 `agent-preset/selected` 事件记录挂载变更
  （事件 `data.agentPreset`，投影初始态取 `header.agentPreset`），等价实现为倒序
  扫描取最后一次选择、无事件回退 header，替代已删除的 `resolveSessionPreset`。
- **preset 别名语义反转**：alpha.5 内置 preset 为 standard/minimal/ptc/cordis，
  `code` 更名 `ptc` 且不留别名。`/fresh ptc` 现直接命中内置 id；`/fresh code`
  作为旧输入兼容映射到 `ptc`；`create`/`creator` → `cordis` 不变。
- **Compact-First 走全局压缩 seam**：alpha.5 起 `ctx.compaction` 是全局服务
  （builtin `/compact` 同款，`compactNow(agent, signal, commandId)` 调用形状不变），
  优先使用；`agentPresets.serviceFor(agent,'compaction')` 作为 rc.2 形态兜底保留。
- **移除 dsh-client-runtime 依赖**：该包在 alpha 线已停止发布（宿主树中亦已移除），
  从 peerDependencies 删除；`dsh.client` 声明移除指向它的 `inject`（client 半边
  `lib/client.js` 本就零宿主 import，`window.__ModuleLoader__.load` 注册方式与
  alpha.5 新 client-modules 机制一致）。
- 其余宿主 API 逐一核对 alpha.5 均未变：`agents.create`（seed/meta/setup 形状）、
  `workspaceRegistry.archiveSession/resolveByPath/attachSession`、
  `commands.register`、`session.requestHeader/deriveMessages`、`BlockAssembler`、
  `createUserMessage`、`agentPresets.resolve/mount`、permission seeded 分支。
- peers/devDeps 升 `^0.1.2-alpha.5`；`dsh-plugin.json` 版本同步 1.3.0。

## 1.2.10 - 2026-08-25

依赖对齐轮 + 双轨制：`@deepseek-ai/*` 升至 `0.1.1-rc.2`；新增惰性 dsh-std Community v0.15 清单。

### 变更

- **依赖对齐**：peerDependencies 与 devDependencies 统一升至 `^0.1.1-rc.2`
  （rc.7 → rc.8、rc.1 → rc.2 发布产物逐包比对均为增量变更，本插件所用 API 无变化；
  rc.2 中 `sessions.create` 收窄的参数本插件从未使用）。`@deepseek-ai/cordis` 进入
  devDependencies（测试套件需本地可解析，peer 声明不参与安装）。
- **双轨制**：新增 dsh-std Community v0.15 的 `dsh-plugin.json`（id
  `io.github.orangeofcarl0-sys.dsh-fresh-start`）与占位宿主 facet 入口 `lib/std/host.js`；
  `/fresh` 功能仍全部由原生 cordis 入口提供。未装 `@dsh-std/adapter-dsh` 时清单完全惰性；
  `contributes.commands` 刻意留空，避免适配器环境下投影出第二个 `/fresh`。
- `tests/std_manifest_test.mjs`：用 `@dsh-std/manifest@0.1.0-rc1` 的 `parseManifest`
  断言清单结构与 package.json 版本同步；接入 `npm test`；devDep 钉死 `0.1.0-rc1`。
- `README.md`：徽章新增 `dsh-std Community v0.15`（对齐 dsh-large-proj-perf）；新增
  「dsh-std 兼容性」节。

## 1.2.9 - 2026-08-22

Compact-First 总结策略（spec：`docs/COMPACT_FIRST_SPEC.md`，CFS-001/002/003）。

### 变更

- **Compact-First**：`/fresh` 总结前先尝试宿主压缩引擎（`serviceFor(agent,'compaction')` +
  `compactNow`）强制压缩当前会话；压缩成功后 `deriveMessages()` 收紧（surface
  replaceGeneration 递增），对话式总结请求体显著缩小，并复用压缩摘要。
- **安静降级**：无引擎（minimal preset）、agent busy、无可压缩范围或引擎抛错时，
  回退为 v1.2.8 纯对话式总结；所有失败捕获不冒泡。
- **可诊断**：返回文本与日志含 compaction 段（`compacted (shadowed N surface nodes)` /
  `compaction skipped (<原因>)`）。
- `compactNow` 使用 `invocation.commandId` 作为 `sourceCommandId`（审计归属）。
- `tests/smoke_test.mjs`：新增 F-02..F-05（压缩成功/无范围/失败降级/先压后总结）。
- `README.md`：总结流程说明更新。

## 1.2.8 - 2026-08-22

修复轮：极简模式（minimal preset）下 `/fresh` 无法创建新会话；新增 `/fresh <preset>` 参数。

### 修复：seeded 会话创建崩溃（非沙箱 shell）

- **症状**：`/fresh` 报 `new session FAILED (session event "sandbox/mode" carries non-JSON-serializable data)`，新会话建不出来。
- **根因**：seed 会话走 `dsh-permission-presets` 的 `pinInitialPermission()` seeded 分支，因 seed 里没有
  `sandbox/mode` 事件，回填 `ctx.shell.sandboxMode`；在非沙箱 shell（如本地 unconfined-bash hack 下的
  `dsh-bash-local`）上该值为 `undefined`，`setSandboxMode(session, undefined)` 追加的事件无法通过
  `session.append` 的 JSON 序列化校验而抛错。
- **修复**：seed 事件序列前置三个 permission knob 事件（`permission/preset` + `sandbox/mode` +
  `approval/policy`，取值 `workspace-write`/`workspace-write`/`ask`，与 dsh 原生会话头部一致），
  seeded 分支读到有效 sandbox 值后跳过回填。

### 新功能：`/fresh <preset>`

- `/fresh` 后跟 preset id 时，新会话使用指定 preset（覆盖继承值），例如极简模式下
  `/fresh standard` 直接开 standard 新会话并带上摘要。
- 指定不存在的 preset 时命令明确报错（不会静默回退到继承值）。
- 内置四大模式均可用，并支持友好别名：`ptc` → `code`（PTC 模式）、
  `create`/`creator` → `cordis`（创造模式）；`standard`/`minimal` 直接用 id。
- 不带参数行为不变（继承当前会话的 preset）。

### 变更

- `lib/index.js`：seed knob 预置 + preset 参数解析 + 别名映射（ptc/create/creator）；命令描述更新。
- `tests/smoke_test.mjs`：seed 结构断言更新，新增 knob 预置、`/fresh <preset>`、未知 preset、
  `ptc`/`create` 别名用例。
- `README.md`：补充 `/fresh <preset>` 用法与四大模式别名表。

## 1.2.7 - 2026-08-20

兼容性验证轮：确认 dsh 0.1.0-rc.8 无破坏性变更，依赖声明与文档对齐 rc.8。

### 兼容性检查（rc.7 → rc.8 逐包比对 npm 发布产物）

- `dsh-llm`：新增 `interruptedBlocks()`（取消时收尾未完成文本/reasoning 块）、
  图片超限卸载常量 `OFFLOADED_IMAGE_TEXT`、重试默认值 2→5；
  `BlockAssembler.push/finish/blocks()` 与 `createUserMessage` 不变；
- `dsh-session`：仅新增 `turn/end` 可选 `interrupted` 标记与 4 个 team 事件类型，
  `requestHeader()` / `deriveMessages()` 不变；
- `dsh-client-runtime`：`prompt` 新增可选 `signal` 参数与路径缩写辅助函数，
  client 插件接口（`__ModuleLoader__` / `archivedSessionIds` / `parentId` /
  `sessions.open`）不变；
- `dsh-app-boot`：仅新增一个平台常量；`dsh-cordis-client-runner`：仅 slots 契约
  文案与新增 `conversation.hero.brand.mark` 槽位，与本插件使用的
  `sessions` / `workspaces` 注入无关；
- `dsh-agent-presets` / `dsh-agent` / `dsh-scope` / `dsh-base` / `dsh-workspace` /
  `dsh-command-compact`：代码零变化（仅版本号与依赖升级）；
- harness 主包：依赖无移除（新增 `dsh-tool-pwsh-persistent`），preset 配置仅
  注释文案调整，preset id 不变。

### 变更

- **依赖声明**：`peerDependencies` / `devDependencies` 中 dsh 包范围更新为
  `^0.1.0-rc.8`；测试套件在 rc.8 依赖下全部通过（40 断言）。
- **文档**：README 的 dsh badge 与「局限」更新为 rc.8 并记录比对结论；源码注释
  版本引用同步。

## 1.2.6 - 2026-08-18

兼容性验证轮：确认 dsh 0.1.0-rc.7 无破坏性变更，依赖声明与文档对齐 rc.7。

### 兼容性检查（rc.6 → rc.7 逐包比对 npm 发布产物）

- `dsh-llm`：仅新增 `assembled()`（返回 `{blocks, replay}`，统一 max-token 截断
  决策），`BlockAssembler.push/finish/blocks()` 与 `createUserMessage` 不变；
- `dsh-agent-presets` / `dsh-agent` / `dsh-session` / `dsh-scope` / `dsh-base` /
  `dsh-app-boot` / `dsh-workspace` / `dsh-command-compact`：代码零变化
  （仅版本号与依赖升级）；
- `dsh-client-runtime`：仅删除一个 settings 错误码 schema，client 插件接口
  （`__ModuleLoader__` / `archivedSessionIds` / `parentId` / `sessions.open`）不变；
- `dsh-cordis-client-runner`：唯一变更为 `slots` 注入的 keyed 化重构
  （`settings.plugin.item`），与本插件使用的 `sessions` / `workspaces` 注入无关；
- harness 主包（`@deepseek-ai/dsh`）lib 产物与 rc.6 逐字节一致。

### 变更

- **依赖声明**：`peerDependencies` / `devDependencies` 中 dsh 包范围更新为
  `^0.1.0-rc.7`；测试套件在 rc.7 依赖下全部通过（40 断言）。
- **文档**：README 的 dsh badge 与「局限」更新为 rc.7 并记录比对结论；
  行为描述与源码注释对齐「总结请求不传 tools」。

## 1.2.5 - 2026-08-16

代码审查修复轮：补全依赖声明与测试基建，收紧 host/client 两侧的健壮性。

### 修复

- **依赖与测试基建**：`peerDependencies` 补齐 `@deepseek-ai/dsh-llm` 与
  `@deepseek-ai/dsh-agent-presets`（`^0.1.0-rc.6`，来自 npm）；新增 `devDependencies`
  与 `npm test` 脚本。此前新克隆环境下 smoke 测试因缺依赖无法运行。
- **host 侧**（`lib/index.js`）：
  - `deriveMessages()` 返回值改为防御性拷贝，不再可能就地污染会话内部数组；
  - provider/model 严格校验：`header.config` 存在但缺 provider/model 时回退到
    agent 选项，不再以 undefined 字段调用 `ctx.llm.stream`；
  - `session.header` 前置读取容错，异常时返回结构化 `{kind:'error'}` 而非裸 rejection；
  - 新增取消检查点（开新会话前 / 归档前）；归档前取消会保住老会话并在结果文本中说明；
  - 总结请求不再向 LLM 传 `tools`，消除模型发起 tool call 导致总结无文本的失败路径；
  - 删除从未使用的 `disposers` 死代码。
- **client 侧**（`lib/client.js`）：`tryOpenChild` 三态返回
  （`opened` / `missing` / `failed`）；`sessions.open` 抛错后不再于每次会话列表
  更新时无限重试，改为告警一次后放弃。

### 测试与文档

- smoke 测试 31 断言 / client 测试 9 断言，新增用例覆盖全部新行为
  （不改写入保护、config 回退、无目标降级、取消中止、header 异常、open 不重试）；
- README：版本 badge 对齐 package.json、断言数更正、补充 `npm install && npm test` 说明；
- 新增本 CHANGELOG（历史版本未留档，自本文件创建起开始记录）。