# 按优先级修复记录 · 2026-10-25

## v1.8.4（2026-10-26，同步后的可靠性维护）

- 基于 GitHub v1.8.3 的 22 个后续提交复查，保留 Windows 锁修复、附件导入和知识库分享功能。
- 移动条目完整保留 front matter 与正文，更新文件大小与相关库时间；读取、写入与索引更新持有同一把锁，避免覆盖并发编辑或复活已删除笔记。
- 移动时若索引提交失败，在释放锁前恢复原 Markdown；回滚也失败时保留原错误与回滚错误。此补偿不等同于断电恢复事务。
- Owner state 补齐共享 readers 和按 Host 路径规则解析的工作区 ID，修复删除人数误报为 0，以及 Linux 大小写不同工作区被误认为已共享的问题。模型搜索仍隐藏发布工作区路径。
- 分享卡片复用公共状态，取消重复的 listShares 读取；分享与模型权限操作按工作区独立标记进行中，阻止重复点击与旧响应回滚。
- 移动成功后重新读取完整条目，保证预览、复制、编辑使用新 front matter；回读失败时禁用旧内容操作；切换条目清空待移动目标。
- 旧版 Office 附件接入 Harness 的 office-to-PDF 服务，与工作区文档复用转换入口，保留附件边界、大小限制及取消信号。
- 锁在重试前与取得锁后检查等待期限，超期不会进入临界区，并保留零等待预算的一次即时尝试；补 owner 标记 unlink 暂时失败的回归。
- 文档路径扫描覆盖 Windows 单/双反斜杠和正斜杠，保留通用工具路径；语法检查重新包含 test 目录，清理 v1.2 测试未回仓时期的过期说明。
- 本地回归 152/152、语法 22 文件及发布检查通过。新版本 Windows/macOS/Linux CI 待推送后确认；真实 Harness GUI 全流程需另行验收，详见 [验证记录](VERIFICATION.md)。

## 原始审查修复（2026-10-25）

本轮完成原始审查列出的 13 组确定性问题，并补上安全索引恢复、模型选择保留与基础 UI 可访问性。保留零第三方运行时依赖、Markdown 正文格式和当时已有的三个模型工具；会话附件工具由后续版本加入。

## 已完成

| 原审查项 | 修复结果 | 验证位置 |
| --- | --- | --- |
| P1 详情串页/误删 | 请求取消与身份校验；读取期间禁用动作；保存及回读期间禁止导航 | test/client-behavior.test.mjs |
| P1 RPC 错误取消 | 区分正常请求体结束、未完整请求和响应中途断连，并清理监听器 | test/host.test.mjs |
| P1 空搜索协议冲突 | 空查询与关键词查询统一输出 ISO 时间字符串 | test/host.test.mjs |
| P1 嵌套工作区授权 | 会话按最具体注册工作区鉴权；子工作区独立授权；普通子目录仍归所属工作区 | test/host.test.mjs |
| P1 共享索引丢更新 | 初始化、读取恢复及整个读改写使用同一跨进程锁；不按时间强夺活锁 | test/lock.test.mjs、test/host.test.mjs |
| P2 文档提取错误 | 修复 PDF UTF-16BE、hex/TJ，XLSX 空列与列坐标，PPTX 实际展示顺序 | test/extract.test.mjs |
| P2 无界解压 | 仅提取需要的 OOXML；单项 16 MiB、累计 64 MiB 预算；检查头部边界与声明大小；PDF 同样限额 | test/extract.test.mjs |
| P2 扫描工作区串用 | 扫描取消、请求标识和工作区绑定；生成前再次校验扫描批次与所选路径 | test/client-behavior.test.mjs |
| P2 来源去重错误 | 规范点路径与分隔符；拒绝绝对路径及工作区外路径；Markdown 保留相对来源 | test/paths.test.mjs、test/host.test.mjs |
| P2 删除库后孤立写入 | 提交时重验目标库存在及所属工作区，并检查取消信号 | test/host.test.mjs |
| P2 不完整输出覆盖 | 非正常 finish、token 上限或缺失 finish 都拒绝入库，保留原知识 | test/host.test.mjs |
| P2 搜索分叉/YAML 干扰 | UI 与 Agent 共用 Host 检索核心；正文排除 front matter，来源单独加权；加入中文词切分 | test/host.test.mjs、test/client-behavior.test.mjs |
| P2 编辑草稿丢失 | 渲染预览使用草稿；返回/取消时提供保存、放弃、继续编辑；复制下载保留草稿内容 | test/client-behavior.test.mjs |

同步优化：

- 三页签共享一个数据源，初始 state 请求由三次减为一次；批量生成结束后统一刷新。
- 搜索采用 200ms 防抖、请求取消和身份检查，显示正文片段及总数；当前最多展示前 30 项。
- 长文提炼在任务开始时固定完整模型选择，保留 reasoningEffort，返回实际使用的模型。
- 删除重复 Owner 搜索实现、未使用的 xmlToText/initError/headings、重复状态刷新和部分无用样式/字典；搜索回包不再携带完整内部索引。
- 补设置成功的翻译、Tab 键盘导航、Tab/panel 关联、编辑器标签、状态播报和进度语义。
- Node 最低版本对齐至 20.3.0；本地与 CI 共用递归语法检查脚本，新增 JS 文件自动纳入。

## Windows 文件锁修复（2026-10-25 补充）

Windows 上曾有 3 项锁测试失败：同进程并发竞争、真实子进程并发写入、持锁子进程退出后的回收。原因不在测试：`lib/lock.js` 把 Windows 的临时共享冲突（`EPERM`/`EACCES`/`EBUSY`）当成永久错误。获取锁时 `rename` 因目标 owner 正在释放而失败，随后目标消失又被误判为无权限；释放锁时 `rmdir` 遇到尚未完成的删除也直接抛错。

现在：

- 获取锁：`EPERM`/`EACCES`/`EBUSY` 与普通争用一样在总 deadline 内有界重试；目标消失不再证明权限错误，持续失败以 `LOCK_TIMEOUT` 报错并把最后一次文件系统错误保留为 cause；`EIO` 等非预期错误仍立即抛出。
- 释放与陈旧空锁清理：只删除本次唯一 owner 标记；`rmdir` 失败后重新读取目录，非空或已消失说明旧清理结束或已被新 owner 接替，立即停止；仍为空则有限重试，持续失败才报错。
- 清理失败不覆盖原始失败：获取失败、operation 抛错或取消时，`finally` 仍分别尝试清理自身 owner 与唯一候选目录，清理诊断附加在原错误上（原错误不可扩展时用 `AggregateError` 保留）；正常释放使用独立清理预算，不跟随已取消的 signal。
- 新增 8 项故障注入回归测试：rename 后目标消失、释放时短暂 EPERM、陈旧空锁恢复、持续访问错误、旧清理遇到新 owner、`process.kill` 返回 EPERM、operation 与清理同时失败、取消原因不被覆盖。

Windows 本机验证结果见 [验证记录](VERIFICATION.md)。

## 大文档与推理预算（2026-10-25 补充）

- 提炼调用单次输出预算从 3000 提到 32k；遇到 `max-tokens` 截断时按 32k → 64k 阶梯重试，仍然截断才把这一次提炼调用的推理强度降为 `high`。因此 `reasoningEffort: max` 下也能产出完整笔记，agent 自身的推理强度不受影响；修复前该配置下普通文档必然截断。
- 文本文件上限从 1 MiB 提到 10 MiB；分片上限从 6 段提到 16 段（约 192k 字符）。超出提炼预算的内容不送模型，并在 front matter 标记 `truncated: true`，不再因为文件大而直接失败。
- 10 MiB 文件不做全量逐段精读：按 12k 字符/段计算需要约 800 次模型调用，因此实现为「接受文件 + 提炼预算内的开头部分 + 显式标记截断」。
- 新增 3 项回归测试：预算阶梯重试、`max` 下的有界 effort 兜底、>1 MiB 文本入库并标记截断。

Windows 本机验证结果见 [验证记录](VERIFICATION.md)。

## v1.2.0：max 推理与 10MB 文档（2026-10-25 补充）

- 提炼调用输出预算 32000 → 截断时 64000 → 仍截断才把该次调用的推理强度降为 `high`；实际生效的 effort 写进 front matter（`distillEffort`）与条目元数据，降级不再不可见。
- `knowledge_read` 工具输出补上 `truncated` / `sourceChars` / `distillEffort`，模型能看到「这篇笔记只覆盖了源文档的一部分」。
- 文本上限 10 MiB，分片 16 段（约 192k 字符），超出预算标 `truncated`。
- 发布前完整套件连续 3 轮 113/113；随后按发版要求移除测试目录，`npm run check` 保留语法与包清单/本地化校验。

## 索引恢复与数据边界

每次索引更新前，将已验证的上一份索引原子写入 `index.json.bak`。主索引损坏或缺失时，仅从有效备份恢复，并关闭所有工作区模型授权；界面显示恢复提示和重新授权入口。备份可能早于最近操作，且不包含知识正文。

没有有效备份而存在知识文件、损坏索引或其他存储痕迹时，明确报错并保留原文件，不会创建空库。普通 I/O 错误同样不会触发重置。若初始化已失败，恢复有效索引后需要重启 Harness。

这不是完整版本历史：正文与索引仍是分别写入的文件，索引备份无法回滚正文。请将完整数据目录备份、来源快照、正文 revision 与一致性恢复作为后续存储阶段处理。

## 验证与生效

测试方法、实际结果和待验证范围见 [验证记录](VERIFICATION.md)。

Host 与 lib 代码修改需重启 Harness；Client 修改需刷新页面。

## 后续产品阶段

按顺序推进：来源 hash 与增量更新 → 正文版本及人工修改保护 → 持久生成任务 → chunk 引用和新鲜度 → 经验候选、反馈与固定评测集。宽屏列表/详情双栏与完整 Markdown 语义可在独立 UI 阶段验证。

本轮没有增加向量服务、训练任务或更新模型权重。PDF 回退解析仍是受限实现：冲突字体映射会明确报错，复杂 PDF 建议使用 pdftotext，扫描件仍需 OCR。

## v1.3.0：共享底座（2026-10-25）

- 索引版本门与迁移：高版本拒绝写入，v1 原地升级并留副本与收据；备份恢复同样升级。
- S1 收口：模型工具不能把知识写进全局库或其他工作区库，只能写当前工作区库；owner RPC 保持原语义。
- 测试回归本地资产：`test/` 进入 `.gitignore`，用例、运行方式与结果统一记录在 [test.md](../test.md)。

## v1.4.0：会话附件提炼（2026-10-25）

- 新增附件来源类型（内容寻址 sha256），工具 `knowledge_ingest_attachment` 从当前会话收集 file 块并复用同一套提取器与提炼管线。
- 附件默认落当前工作区库，共享/全局仍由 owner 控制；附件路径必须落在 `$DSH_HOME/attachments` 内。
- PDF 提取新增 winget Poppler 与 Git mingw64 的自动探测，无需手工配置 PATH。

## v1.5.0：库级共享（2026-10-25）

- 新 scope `shared` + readers 列表；共享/撤销只走 owner RPC 并追加审计记录；模型工具只能写当前工作区库。
- 索引升级到 v3，沿用副本与迁移收据。

## v1.8.0：push 前 hardening（2026-10-25）

- 恢复测试与 CI 执行；test.md 脱敏并补本地路径扫描。
- 共享授权：恢复备份清空 readers/shares；可见性精确匹配；移动查重并同步 front matter。
- 提炼与附件：merge 输入 60k 上限；附件来源内容寻址；共享默认失败关闭。

### v1.8.1

- agent 搜索隐藏来源路径；共享库 scope 标签修正。