Arch Lens v0.1.0

[0.1.0] - 2026-09-07

Added

• 「📄 一键生成文档」V1 章节管线（重做回归，替代早前的开关式下线）：host 侧按认知
  主干顺序串行生成 7 章（目录 / 概念 / 依赖 / 时序 / 流程 / ER / 交互），每章独立 LLM
  调用、独立版本化信封缓存、独立失败重试：
  • 同一份事实快照同时喂 prompt 与零 LLM 幻觉门禁：拦截编造的带 scope 包名（给最近
    真包建议）、不存在的文件路径、调用边表中的虚构/反向边；违规退回恰好一轮修复，仍不过
    关的章节带 ⚠️ 落地但不写缓存（下次重试）；
  • 图驱动章节是纯消费者：概念/时序/流程/交互四章缺图即跳过并提示先补图，从不暗中
    触发出图（一次点击的费用面完全确定）；依赖/ER/目录三章只靠代码事实即可写；
  • 落地与复用：每章独立写 docs/architecture-<章>.generated.md（带 .generated
    后缀，永不覆盖手写文档），正文后附零 LLM 的「## 图示」一节（从对应图缓存确定性渲染）；
    版本化缓存与图缓存同一套 factsVersion 机制——代码没变时重复点击只补缺、只重试
    失败章（幂等）。
• V2 演进清单（记录后续方向，非本次实现）：① 每章细粒度 deps 失效（已落地，见
  Changed）；② 提示词编辑器接入文档风格（当前章节 prompt 内置）；③ 逐章 diff/合并的
  落盘交互（当前直接覆盖）；④ withDescriptions 图说明作为章节可选增强；⑤ 隔离会话
  生成选项（当前宿主直连，不进会话历史）；⑥ 裸标识符/短名实体白名单校验（V1 已知放行
  面）；⑦ 图驱动章节缺图时可选"顺手补图"模式；⑧（探讨中）章节来源演进——全图讲解
  版本化：讲解回答埋令牌、宿主捕获落版本信封（deps=该图 deps，图失效连带讲解失效），
  章节优先消费新鲜讲解（零二次 LLM），缺失回落宿主直连；把出文档成本摊进学习时间；
  ⑨ docs 类调用思考档下调/并行化（⑨已落地下调，见 Changed；并行化与⑧正交可叠加）
• scripts/toggle-arch-lens.ps1：DSH profile 挂载开关（on/off 重写 cordis.patch.yml，
  自动备份、保留无关行）；scripts/scripts.md 脚本手册；pnpm typecheck:tests 收编
  测试类型检查（vitest 只转译不查类型，此前 tests 从不被 tsc 审查）

Changed

• 图与章节生成顺序重排为认知序（设计备忘 docs/design-comprehension-spine.md）：
  图 = 职责（词汇表）→ 概念 → 核心（主角）→ 时序 → 流程×2 → 交互；章节 = 目录 → 概念
  → 依赖 → 时序 → 流程 → ER → 交互。缓存文件名与失效只认文件名不认顺序，重排仅改
  生成顺序，消除"词汇表没建、图提示词先造句"的历史错位。
• 过期缓存降级为「先前稿」的增量修订链：代码变动后章节/时序/交互/流程/核心/概念
  六条归纳链不再整篇重写——旧产物作为底稿喂回，只修订与新事实不符的部分（更快、更稳，
  门禁照常复审防"旧错误锚定"）。逃生门不变：🔁 全量重建（force）永远跳过 prior；章节
  侧删除信封文件即同时移除缓存与 prior。
• requires 信封账 + 级联失效：章节信封记录其消费的图缓存种类；图就地重生
  （事实版本未变）时级联失效嵌入它的章节信封，杜绝"新鲜缓存服务过时正文"。
• 级联语境：上游结论作为事实段注入下游章节——主干核心包进 ER/目录章、黄金路径
  （时序消息序列）进流程/交互章，照受幻觉门禁复核；消费即依赖（注入即扩 requires，
  账实相符）；黄金路径触及的实体同步注入 ER 章。
• 讲解版本化（学习过的章节，文档白得）：学习桌六入口的讲解按文档语体撰写并落章节
  信封（deps 随对应图失效）；一键生成时新鲜且过门禁的讲解零二次 LLM 直接落地，
  过期/缺失/违规一律回落宿主直连链。
• 章节细粒度包依赖（V2①，替代"任何代码变动使全部章节失效"的粗粒度）：章节事实块
  与信封 deps 同源收窄（时序→消息端点包、交互→事件∪黄金路径包、依赖→核心 ids、
  ER→实体所属包∪核心），无关包变动只重盖章保留正文；正文引用的真实包一律并入
  deps（确定性防欠失效兜底）。
• 文档声称 → 合成：概念树 doc 阶段只认文档明写的「概念层级」节逐字提取（零 LLM）；
  声称类文档（design/overview/architecture 等中英关键词）的标题大纲作【文档声称】注入
  概念树与架构概览归纳（预期非结论、代码事实为准），声称存在即跳过共享档案；概念/
  流程/时序三链统一排除 README.md（使用目录≠架构声称；其链接的图文档作为额外候选
  显式加入，doc 能力不丢）。
• 流程图 n×n 交叉视角修正：文档声称的流程只锚定实体×事件一格，实体×管道走共享
  档案 pipeline 投影（零额外 LLM）、方法级走各自归纳——不再所有格子渲染同一张 doc 图。
• docs 类调用思考档下调：一键文档的 LLM 调用提案路由广告的最低思考档（实测思考
  token 占墙钟约九成）；探测失败回落默认、绝不阻塞；图类保留默认档。
• 旧「一键生成文档」零 LLM 组装链整体删除（非屏蔽）：docbuild.ts、单节 RPC、
  DOCS_FEATURE_OFF 开关一并移除——模板正文达不到可交付质量是当年下线裁定，V1 章节
  管线回归后该链无存在意义。笔记系 NOTES_FEATURE_OFF 维持退役（裁定：会话记录即笔记）。
• 职责事实 LEGACY 兜底移除：出图职责段唯一来源为 host 侧磁盘态，客户端不再填洞
  （双数据路径归一）。
• 编译期依赖解耦本机 DSH checkout：harness paths 换 npm @deepseek-ai/* 固定
  版本线（运行时仍由宿主 external 提供，不产生双份实例）。
• ⚡ LLM 用量账本按工作区隔离：账本从进程级单例改为按 workspace root 键控——此前
  任一工作区查用量都会把混合了所有工作区的快照写进自己的账本文件。会话驱动的调用按
  回答会话 cwd 归账（与图缓存写入同一解析规则），无法归属的调用一律不记。迁移：隔离前
  的旧文件可能含混合历史，按文件归属原样折叠、不回溯拆分；干净起点 = 删除
  index/.arch-lens-llm-stats.json（gitignored）。
• ⚡ 面板「🔬 全部开启 / 全部关闭」语义打通：一次统一翻转三个粒度状态源（时序
  methodLevels / 流程 flowView / 交互 eventsView，各自持久化，与各 tab 自己的
  开关同源），聚合态按钮高亮 + 切换提示；不重拉当前图——开关是「下次」的粒度（重新
  进入页签 / 重新扫描 / AI 生成 / 追问重画时按新粒度取数，读缓存零 LLM），默认实体级。

Fixed

• 浮动面板「放大/缩小」改为调整窗口尺寸：右下角/边缘可拖拽拉伸，按钮按比例调窗口大小；内容保持自然尺寸重排（原为内容 CSS 缩放，放大后文字与图溢出窗口）。
• 「⏹ 终止」停不下来修复：会话驱动生成以 queue 排队，而平台 cancel 只停当前回合、队列 FIFO 续跑——终止后进入 20s「武装窗口」自动续掐每个续跑回合直到排空，会话忙碌期间新的图/讲解请求拒绝入队并提示（原可无限堆积，停止后仍逐条继续执行）。
• 🎨 动态出图场景按工作区隔离：场景内存表此前是进程级 Map<figureId>，A 工作区画的
  图会出现在 B 工作区的面板与场景列表里（内存读取优先于按 root 的磁盘路径）。现按 root
  嵌套键控（Map<root, Map<figureId>>），dynamic-N 内存 id 也不再跨工作区碰撞；暂存
  槽从单槽改为按 figId 注册（场景归属在暂存时确定），两个工作区并发出图不再互相踩掉
  暂存（此前后画的会顶掉先暂存的槽，导致先画的图丢失捕获）。磁盘保存路径本就按 root
  隔离，不受影响。
• 讲解暂存与会话图缓存同样按会话/工作区隔离：讲解暂存（notePending）此前是进程级
  单槽——任一会话暂存讲解后，另一会话再暂存即顶掉前者，先暂存会话的回答丢失讲解信封
  捕获与用量归账；现按会话 id 键控（带 30 分钟 TTL）。一次工作区的重新扫描此前会清掉
  所有工作区的内存图缓存（graphCaches.clear()），现只失效本 root。其余状态经全量
  审计确认本就按 root/figId 键控（图暂存、生成活动、追问中断、索引/文档 in-flight），
  各 tab 图的磁盘缓存读写始终按 root 隔离。
• 宿主漂移导致的 client bot 编译断裂（改消费结构性镜像，运行时行为不变）；typert 边界
  分析要求的 wire 类型外移（DocChapter*Outcome 迁入公共 ./types）。
• mermaid 渲染三连：dense 多子图互相压叠（nodeSpacing/rankSpacing 放宽至 110/170）、
  节点/子图文字被裁（foreignObject overflow 放开）、最右子图框右缘外文字不可见（根视口
  overflow 放开）。
• 重扫收尾墓碑清扫：物理删除 index/ 下无版本封套、任何读写路径都够不到的缓存残留
  （用户资产与受管墓碑不动）。
• 编辑器里 tests 对 @deepseek-ai/* 的误报红（tests 纳入 tsconfig 项目后消除）。