增量质检报告 · dsh/dsh-todo-sidebar v0.2.3

• 项目：dsh/dsh-todo-sidebar
• 分支：v0.2.3
• 对比区间：4691d3a（v0.2.2） → 7e05236（v0.2.3）
• 变更文件：4 个（lib/client.js、tests/harness.cjs、package.json、README.md）
• 质检数据源：codescan_quality_list（head 版本 58 条）+ codescan_issues_diff（base→head：修复 0 / 新增 1）

一、结论摘要

本次是一个高聚焦的单点运行时修复：把可选服务（jobs / uiSession / uiWorkspace）的探测方式从 ctx[name] 属性访问改为 cordis 4 的 ctx.get(name)，修复实机上「命令区一直为空、跑着的子代理跳转失效」 的长期 bug。改动面极小（lib/client.js 仅 1 行逻辑 + 注释），风险低；配套新增两组桩测试锁定 cordis4 严格 ctx 语义。静态质检无新增功能性缺陷，仅新增 1 条测试文件的重复代码块（Low，可接受）。

二、变更范围

唯一的运行时代码变更（lib/client.js:113）：

// 旧（0.2.2 及之前）
const candidate = ctx[name];
// 新（0.2.3）
const candidate = typeof ctx.get === "function" ? ctx.get(name) : ctx[name];

三、修复的问题

依据 codescan_issues_diff（base=4691d3a → head=7e05236）真实数据：静态质检问题修复 0 条 / 新增 1 条。

• 静态质检问题：修复 0 条。 本次修复的本质是运行时/框架语义缺陷（cordis 4 fiber 只装载 inject 声明过的服务，未声明服务的 ctx[name] 属性访问必抛 cannot get property … without inject），桩测试的假 ctx 不会抛， 因此静态质检工具无法把「修复前/修复后」映射为可对比的 issue 条目——修复 0 条属预期，不代表无修复。

• 功能修复（人工分析确认，diff 自带证据）：

  1. 实机「命令区一直为空」：0.1.7 起后台任务从列表快照 jobsBySession 搬到 ctx.jobs 服务， 而属性访问式探测在 cordis 4 上恒抛错并被 try/catch 吞掉 → 永远回落快照，而快照里已没有 jobsBySession → 两个数据源都取不到 → 命令区为空。改为 ctx.get 后能真正拿到 jobs。
  2. 子代理「进详情」跳转静默失效：uiWorkspace 同样探测不到，openSessionById 只能退回 sessions.open?.()，丢失子代理地址。改为 ctx.get 后带 {parentSessionId, childSessionId, mode} 地址跳转恢复。
  3. 兼容面：ctx.get 不可用时回落 ctx[name]，对 0.1.5 老 harness 行为不变，向后兼容。

四、新增问题

依据 codescan_issues_diff 真实数据，新增 1 条：

• 成因：新增的 strictCtx 桩（第 12 组用例）复制了文件顶部 ctx.slots 的 inject/register 内联定义，形成 4 行重复。
• 评估：位于测试替身（fixture），非产品代码；重复的是 cordis 桩的样板，抽取价值有限， 且测试文件保持「自包含、可直接阅读」反而更利于阅读。建议保留，不阻断发版；如要收敛， 可把 slots 桩提取为一个 makeSlots() 工厂函数供多处复用。

五、核心变更正确性分析

probeService(ctx, name) 的语义：

return () => {
  if (resolved) return value;
  try {
    const candidate = typeof ctx.get === "function" ? ctx.get(name) : ctx[name];
    if (candidate !== undefined && candidate !== null) { value = candidate; resolved = true; }
  } catch { /* 该 harness 没有此服务 */ }
  return value;
};

• ✅ 命中即缓存（resolved）：找到服务后不再重复探测，身份稳定，配合 useServiceSnapshot 的 useCallback 依赖不会造成无谓重订阅。
• ✅ 未命中不缓存：服务晚激活时后续渲染仍能补探测到，符合「运行时探测 + 自动降级」的设计。
• ✅ typeof ctx.get === "function" 守卫：老 harness 无 ctx.get 时回落 ctx[name]，兼容 0.1.5。
• ✅ try/catch 兜底：即便某实现下 ctx.get 或属性访问抛错，也能安全降级到快照数据源，不冒泡到渲染。
• ⚠️ 次要边界（低风险，无需改动）：当 ctx.get 存在但返回 undefined 时，不会再尝试 ctx[name] （三元分支互斥）。这仅在「ctx.get 存在但取不到、而 ctx[name] 能取到」的假想实现下才有影响； 在 cordis 4 语义下 ctx[name] 本就抛错，因此实际无损失。

createSessionOpener / createTodoPane / createTodoHeaderButton 三处对 probeService 的使用一致， jobs / uiSession / uiWorkspace 三个可选服务均已覆盖，修复完整，未见遗漏的属性访问点 （其余 ctx.sessions / ctx.slots / ctx.sidebarRight / ctx.sidebarRightTabs 均在 inject 中声明）。

六、测试覆盖评价

新增用例质量较好，真实还原了 cordis4 语义：

• 第 12 组用 Proxy 模拟 fiber store——未声明服务属性访问必抛、只有 get 能取到， 并先自检「直接读 ctx.jobs 抛错」，再验证 jobs/uiSession/uiWorkspace 经 ctx.get 探测成功 （命令区有数据、watch 正常发出、跳转带地址、头部计数正确）。
• 第 13 组验证「有 ctx.get 但服务缺席」时回落 jobsBySession 快照且不抛错。

这正好补上了此前桩测试「假 ctx 不会抛」导致 0.2.0–0.2.2 缺陷漏网的根因，测试策略方向正确。

七、发版建议

• 可以发版：修复点明确、改动面小、向后兼容、有针对性回归用例。
• 唯一计入的新增问题为测试文件的 Low 级重复代码块，不阻断。
• 提示：本次修复属运行时语义层，静态质检「修复 0 条」是工具口径所致，评审时请以本文第三节的功能 分析为准，避免误读为「本次无任何修复」。