Skip to content

v0.2.0

Choose a tag to compare

@github-actions github-actions released this 09 Nov 08:55
· 14 commits to main since this release

v0.2.0 — 语义决策、冷 lead 恢复与 worktree 验收

0.2.0 把上一轮全量审计留下的六个"待决策"项全部按正确语义落地(minor 版本,允许 breaking),
并修复通知泵与损坏日志恢复路径上的缺陷。核心目标:一次损坏的持久记录不再永久锁死一个会话,
Host 重启后 DevLead 不再静默失聪,watch/唤醒的失败路径不留下半应用状态。

详见 审计记录 §10 与
设计说明。

Breaking changes(升级前必读)

  1. useWorkspace 改为 live lead Agent 调用(core 与 tool 语义统一)。
    • 旧:useWorkspace(path, { title?, create?, signal? }),Host 级 caller-free API;
      create 默认 true,可以 mkdir 任意可写目录。
    • 新:useWorkspace(agent, { path, title?, create? }, signal?);要求 live lead Agent 且
      DevLead 模式开启(否则 DEVLEAD_AGENT_NOT_LIVE / DEVLEAD_NOT_ENABLED),
      create 默认 false:默认绝不创建目录,缺失目录报 DEVLEAD_DIRECTORY_MISSING;
      只有显式 create: true 才允许 mkdir -p。
    • 迁移:直接调用 core 的宿主插件改为传 Agent;需要建目录的模型调用显式传 create: true。
  2. promptSession 的自动 watch 变为可补偿语义。admission/resume 失败或取消时,本次调用
    新增的 watch 会被补偿移除(已有显式 watch 不受影响),不再留下"watch 了但没投递"的
    半应用状态。watch: false 语义不变。
  3. wakeColdSession 默认改为 true(冷 lead 自动 resume 投递)。配合冷 lead 索引重建:
    Host 重启 / 插件重载后,hub 从持久化 projection cache(零 I/O 预筛)+ Session 日志
    (精确折叠)重建 watch 索引;被 watch 会话的 turn/end 仍会写入持久通知并在合并窗口
    结束后唤醒 lead(冷 lead 先 resume)。进程内 agent/disposed 不再移除索引,因此 dispose
    之后仍继续观察、继续写持久通知。不希望后台自动 resume 的部署显式设置
    wakeColdSession: false(此时通知进入内存队列,等人类打开 lead 时补写并投递)。
  4. DevLeadCreatedSession.isolation 正式声明为必填字段(0.2.0 breaking)。
    tool 的 value 层保留对旧 core 缺失该字段的防御性回退
    ({ requested: 'none', status: 'none' }),但混装旧 core + 新 tool 不再是被支持的发版组合;
    请整体升级 6 个包(bundle 会保证版本一致)。
  5. 损坏 fold 的恢复路径:新增人类专属 /devlead reset(丢弃该会话的全部 DevLead 持久
    状态:模式、watch 集合、通知 digest、冻结失败标记),且 /devlead off 在 fold 冻结时也会
    强制关闭并清理冻结状态。/devlead on 在冻结状态下会拒绝并提示先 reset(避免隐式丢弃数据)。
    旧版本的 projection 会把新 reset 记录当作未知插件记录忽略,不会崩溃,但无法执行恢复。
  6. hasQueuedNotice 不再丢弃新 batch 的唤醒:inbox 里仍有未投递 notice 时,新 batch 保持
    在待投递队列,notice 被消费/取消后立刻(或最迟 1s 重检后)投递,不再出现"持久记录已写、
    但永远不会再唤醒"的丢唤醒。持久 digest 仍是权威。

新特性

  • 冷 lead 索引重建(cold rehydration):Host 启动/插件重载时 [Service.init] await
    一个 corpus-readiness barrier(有界 2s:用可选 sessionPersistence.list() 的完整存储会话
    集合与 sessionQuery 的 persisted 语料做比对;全新 Host 无存储会话时立即通过,稳定 Host
    只付一次语料比对),然后执行唯一一次权威冷扫描:用 sessionQuery 列出持久会话,以
    sessionProjectionCache 的 devLead 值做零 I/O 预筛,再对候选会话精确折叠持久
    plugin:devlead/* 记录得到权威 watch 集合;损坏记录单会话 warning 一次并跳过。无分类
    候选的全量日志读取有固定上限(64),避免 Host 重启扫描无界历史;没有 projection cache
    的宿主仍可基于 live 会话恢复,冷会话需要该能力(默认 Web/Desktop 组合都有)。
    watch 索引可重复重建(幂等),dispose/reopen 不再丢失观察;仅插件卸载期间结束的 turn
    无法补发(插件重新加载时索引会从持久记录重建)。
  • /devlead reset:人类专属恢复命令;同时清空 summary 级 devLeadMode 标记。
  • 通知记录立即 flush:通知写入 lead 日志后主动发起 durability flush,缩短崩溃丢记录窗口。
  • warnedFailures 每 Host 生命周期只警告一次(有界集合,不再因 dispose/reopen 重复刷屏)。
  • 客户端样式注入引用计数:ensureStyleTag 改为跨模块实例 refcount,HMR 新旧实例交替时
    不会提前移除仍在使用的 <style>。
  • React 组件/hook 渲染测试:新增 react-test-renderer(devDependency,仅测试用,纯 node、
    无 jsdom),覆盖两个 UI 入口的分支、a11y live region、pending/失败文案与准入 hook 的
    单击/双击/卸载/reset 行为。
  • 多阶段 E2E(含冷 lead 重启验收与实验组合 worktree happy path):pnpm e2e 分多个
    阶段 —— 阶段 1 默认 profile 全量断言(含 Worktree isolation: unavailable);阶段 1b 用
    同一加载流、同一一次性 scratch home 重启,验证冷 lead 索引重建:冷 lead 从持久日志折叠
    状态、冷子会话被 resume、重启后的 turn/end 产生新通知,D2 由此获得真实 Host 端到端证据;
    阶段 2 在同一 scratch profile 中叠加 @deepseek-ai/dsh-experimental-forge-bundle 重启,
    验证 devlead_create_session({ isolation: 'worktree' }) 端到端:返回 status: 'worktree'
    • path/branch/baseCommit、子会话有效工作目录确实切换、Session 仍归属原 Workspace。
      patch 与 installed 两条加载流都跑完整多阶段,各 61/61(阶段 1 27 + 阶段 1b 12 +
      阶段 2 22);--no-worktree 跳过阶段 2(39/39,阶段 1 + 1b),仅供调试。

修复

  • 冷 / 已 dispose lead 不再停止观察 watch 的会话:dispose 保留索引;Host 重启/插件重载后
    索引从持久记录重建(冷 lead 默认 resume 投递)。
  • promptSession 失败/取消后的半 watch。
  • inbox 已有 notice 时新 batch 的丢唤醒。
  • 损坏 fold 无法恢复(/devlead off 恢复 + /devlead reset)。
  • 通知记录在 crash 窗口内可能未落盘。
  • 命令并发(on/off、watch/unwatch 与另一个并发命令)时状态行标题与正文可能不一致。
  • 单 Session 损坏日志在 dispose/reopen 后重复 warning。

验证

在本工作树(未提交状态)上的最终结果:

pnpm verify                      # typecheck + tests + build
pnpm test
node scripts/check-packages.mjs  # OK (6 packages)
node scripts/e2e-smoke.mjs --no-build --flow patch
node scripts/e2e-smoke.mjs --no-build --flow installed
  • 单元测试:22 文件 / 558 tests(含 fold reset、冷 lead 重建与就绪屏障、promptSession 补偿、reset 命令、
    并发标题、React 渲染、样式 refcount)。
  • E2E:多阶段(默认 profile 断言 + 重启验证冷 lead 索引重建 + 叠加
    @deepseek-ai/dsh-experimental-forge-bundle 的 worktree happy path),patch 与 installed
    两条加载流各 61/61(阶段 1 = 27、阶段 1b = 12、阶段 2 = 22;--no-worktree 跳过阶段 2
    时为 39/39)。
  • 版本:根 package.json 与 6 个可发布包均为 0.2.0;check-packages 校验版本锁步。

兼容性

  • DeepSeek Harness:>=0.2.2-rc.1 <0.3.0(engines.dsh 不变)。
  • Node.js:>=24.9(仅构建与发布工具链)。
  • 持久记录:只新增 plugin:devlead/reset;旧记录格式不变,fold 的 stateVersion 不变。
  • 升级方式:dsh plugin --profile <p> add @yankeguo/dsh-devlead-bundle@0.2.0(或更新现有
    profile),刷新 Web 页面;6 个包必须整体升级。