@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/skills/llm-wiki-skill/docs/spark/2026-06-22-chat-auto-scroll-design.md

@@ -0,0 +1,185 @@
+# 对话自动跟随设计
+
+日期：2026-06-22
+状态：设计已确认，待实现
+当前分支：`codex/fix-chat-auto-scroll`
+
+## 目的
+
+这份设计用于解决 llm-wiki-agent 对话区在发送消息后不会自动向下推进的问题。
+
+当前现象是：用户发送消息后，AI 回复已经开始生成，但对话内容不会自动滚到最新位置。用户需要手动用滚轮向下滚，才能看到新回复或回复后续内容。这会打断对话连续性，尤其在长回复和工具调用之后更明显。
+
+目标体验是一句话：
+
+**用户在看最新回复时，对话自动跟随；用户主动上翻看历史时，界面尊重用户，不强行拉回底部。**
+
+## 背景依据
+
+llm-wiki-agent 的产品定位是“以对话为中心的本地知识库工作台”。对话主区是核心入口，自动跟随最新回复属于基础对话体验。
+
+本设计不是新增复杂功能，也不是改变对话模型、消息协议或会话存储。它只收口一件事：对话区应该在正确的时候展示最新内容。
+
+已确认的现状：
+
+- 对话消息区本身是可滚动区域。
+- 发送消息会立即新增用户消息和空的 AI 回复气泡。
+- AI 回复是流式生成的，内容会持续变长。
+- 当前没有专门的“是否跟随底部”的状态管理。
+
+## 设计结论
+
+采用“智能跟随 + 向下箭头按钮”的方案。
+
+1. 用户发送消息后，对话区立即滚到最新消息位置。
+2. AI 回复生成过程中，如果用户仍在底部附近，对话区持续跟随最新内容。
+3. 如果用户主动上翻历史，对话区暂停自动跟随。
+4. 暂停跟随后，显示向下箭头按钮，提醒用户有最新内容可回到。
+5. 用户点击向下箭头按钮，或自己手动滚回底部附近后，恢复自动跟随。
+
+这里的“底部附近”指用户距离消息区底部很近，已经是在看最新内容。实现时可使用一个固定容差，例如 80-120 px；具体数值以不误判用户上翻为优先。
+
+不采用以下方案：
+
+- 不做“永远强制滚到底部”，因为会打断用户阅读历史消息。
+- 不做“只在发送时滚一次”，因为 AI 回复流式变长时仍可能看不到后续内容。
+
+## 用户体验规则
+
+### 1. 发送消息
+
+用户点击发送或使用快捷键发送后：
+
+- 输入框清空。
+- 新的用户消息和 AI 回复占位出现在对话尾部。
+- 对话区自动滚到尾部。
+- 自动跟随状态开启。
+
+这样用户能立即看到“消息已发出，AI 正在回复”。
+
+### 2. 回复生成中
+
+AI 回复逐步生成时：
+
+- 如果用户没有上翻，最新回复始终保持在可见范围内。
+- 回复内容变长、工具状态出现、工具状态完成、Markdown 表格展开等情况，都应继续跟随。
+- 跟随不需要动画夸张，重点是稳定地看到最新内容。
+
+### 3. 用户主动上翻
+
+如果用户把对话区往上滚，离开底部一段距离：
+
+- 自动跟随暂停。
+- 后续 AI 回复继续生成，但不强行滚动页面。
+- 显示向下箭头按钮。
+
+这里的产品原则是：一旦用户主动查看历史，系统不能替用户夺回滚动位置。
+
+### 4. 恢复跟随
+
+有两种方式恢复：
+
+- 用户点击向下箭头按钮。
+- 用户自己滚回底部附近。
+
+恢复后：
+
+- 对话区滚到最新内容。
+- 向下箭头按钮消失。
+- 如果 AI 仍在生成，继续自动跟随。
+
+### 5. 切换会话或知识库
+
+切换会话或知识库后，新的对话面板应按当前会话历史展示：
+
+- 如果进入的是已有长对话，默认展示底部最新消息。
+- 如果是空会话，展示空状态。
+- 切换动作不继承上一个会话的“暂停跟随”状态。
+
+## 界面边界
+
+回到底部入口采用类似 Codex 的向下箭头图标按钮，不使用文字按钮。
+
+按钮规则：
+
+- 使用单个向下箭头表达“回到底部”。
+- 按钮为轻量圆形或近圆形，视觉上像悬浮的小控制点。
+- 放在对话区底部中间附近，悬浮在输入区上方，不遮挡消息正文。
+- 样式跟随当前主题，使用柔和背景、细边框和轻微阴影；暗色和浅色模式都要自然。
+- 鼠标悬停时只做轻微强调，不做夸张动画。
+- 只在用户离开底部且有必要回到底部时出现。
+- 按钮本身不显示文字，但可访问名称应是“回到底部”。
+- 本次不增加未读数量；如果以后需要未读计数，另开设计，不混入本次实现。
+
+本次不做：
+
+- 未读消息数量。
+- 跳转到某一条消息。
+- 对话搜索定位。
+- 历史消息虚拟列表。
+- 全局页面滚动重构。
+
+## 组件与数据流
+
+实现应集中在对话面板内部完成，不改变后端接口。
+
+需要维护的前端状态：
+
+- 当前是否处于自动跟随状态。
+- 当前是否离底部足够近。
+- 是否需要显示向下箭头按钮。
+
+主要数据流：
+
+1. 用户发送消息，消息列表新增内容，开启自动跟随。
+2. AI 流式回复更新消息内容。
+3. 消息内容变化后，如果自动跟随开启，则滚到尾部。
+4. 用户滚动消息区时，判断是否离开底部。
+5. 离开底部则暂停自动跟随并显示向下箭头按钮。
+6. 用户点击向下箭头按钮或滚回底部，则恢复自动跟随。
+
+## 异常与边界
+
+需要覆盖以下情况：
+
+- 对话为空时不显示向下箭头按钮。
+- 只有图标按钮时，键盘和读屏仍能识别它是“回到底部”。
+- 回复出错时，如果用户在底部附近，错误提示也应可见。
+- 用户停止生成时，滚动状态不应乱跳。
+- 工具调用状态展开或收起时，如果用户在底部附近，应继续跟随。
+- 大段 Markdown、表格、代码块渲染后高度变化时，仍能保持跟随。
+- 用户正在上翻时，即使回复继续增长，也不能强行滚回底部。
+
+## 验收标准
+
+实现完成后至少验证以下场景：
+
+1. 发出一条普通消息后，不需要滚轮就能看到 AI 回复开始。
+2. 长回复生成过程中，页面持续停在最新内容附近。
+3. 回复生成时用户上翻历史，页面不再被自动拉到底部。
+4. 用户上翻后看到符合当前主题的向下箭头按钮，而不是文字按钮。
+5. 用户点击向下箭头按钮后，立即回到最新回复，并恢复自动跟随。
+6. 用户自己滚回底部后，向下箭头按钮消失，后续回复继续自动跟随。
+7. 切换到已有长会话时，默认看到最新消息。
+8. 回复出错或停止生成时，界面没有异常跳动。
+
+## 验证方式
+
+推荐验证分三层：
+
+1. 增加前端组件测试，覆盖发送、流式更新、用户上翻、向下箭头按钮显示与恢复。
+2. 运行现有前端测试和类型检查，确认没有破坏输入框、导出按钮、消息气泡和工具状态。
+3. 启动本地应用，在浏览器里真实发送一条长回复请求，手动验证自动跟随和上翻暂停。
+
+## 后续实现范围
+
+后续实现应只修改对话面板和必要样式。
+
+不改：
+
+- 后端流式协议。
+- 会话存储格式。
+- 知识库选择逻辑。
+- 图谱、右抽屉、搜索、导出等无关模块。
+
+如果实现过程中发现对话区滚动容器和页面布局有冲突，应先优先修正对话区内部滚动边界，不扩大为整体布局重构。

package/skills/llm-wiki-skill/docs/spark/2026-06-22-graph-community-node-visual-design.md

@@ -0,0 +1,266 @@
+# 社区节点轻量关系地图设计
+
+日期：2026-06-22
+状态：待用户复核
+当前分支：`codex/graph-community-node-visual-design`
+视觉稿：`designs/graph-community-node-map/Community Node Map Prototype.html`
+
+## 目的
+
+这份设计用于优化 llm-wiki 图谱里“进入社区后”的节点呈现。
+
+当前社区内节点更像一组大卡片，卡片体积偏大、节点挨得近，社区背景色块又强化了被框住的感觉。用户进入社区后，本来想看清“这个社区内部有哪些知识点、谁和谁有关”，却容易先看到一片拥挤的卡片。
+
+本次目标不是重做整个图谱，也不是重新定义社区、边或右侧抽屉，而是把社区内部的视觉层级改成一张轻量关系地图：
+
+**社区里默认看地图，悬停临时看关系，点击固定看内容。**
+
+## 强范围边界
+
+本次只聚焦于图谱里的社区节点设计，具体是：用户已经进入某个社区后，社区内部节点、线、标签、社区底色，以及节点悬停/点击后的关系聚焦表现。
+
+本次不改：
+
+- 全局图谱的默认呈现、路由、性能策略和 Sigma 全局规则。
+- 对话、会话列表、知识库创建、消化、检索、导入导出等非图谱功能。
+- 社区入口规则，例如从全局如何选择社区、如何进入社区。
+- 右侧面板的信息结构和内容层级。
+- 现有关系类型、置信度、权重这些图例概念的含义。
+- 节点真实数据、知识库文件结构和图谱构建流程。
+
+允许的联动只有两类：
+
+- 用户点击社区内节点时，沿用现有机制更新右侧面板里的节点内容。
+- 为了让社区内线条表现正确，可以读取并复用现有边字段：关系类型、置信度、权重、节点类型和节点连接关系。
+
+任何超出以上范围的体验调整，都应另开设计，不混进本次实现。
+
+## 已确认现状
+
+代码和图例里已经存在三套边信息表达，本次必须继续沿用：
+
+- 关系类型：实现 / 依赖 / 衍生 / 对比 / 矛盾，用线的颜色表达。
+- 置信度：原文 / 推断 / 待确认，用线的虚实表达。
+- 联系强弱：用线的粗细和透明度表达。
+
+当前实现已有“选中节点后相关边优先”的基础，但还没有把社区内节点明确分成一度、二度和无关三层，也没有把悬停和点击统一成同一套聚焦逻辑。
+
+因此本次设计不推翻原来的边图例，而是在社区视图里补上更清楚的关系距离规则。
+
+## 方案选择
+
+对比过三种方向：
+
+1. 轻量关系地图：节点像地图坐标点，默认留白多、线很细；聚焦时一度关系清晰，二度关系很淡。
+2. 聚焦星图：点中节点后把它变成中心，周围关系强烈围绕它呈现。
+3. 社区知识岛：强化社区边界感，让节点像散落在一个岛上的知识点。
+
+采用方案 1：轻量关系地图。
+
+原因：
+
+- 它最能解决“卡片大、挤、不美观”的问题。
+- 它保留当前视觉稿里已经被认可的空间感。
+- 它不会把社区背景变成新的视觉负担。
+- 它能自然承接现有边图例，而不是发明一套新说明。
+
+## 默认视觉状态
+
+进入社区后，画面不再铺满节点卡片，而是一张轻量关系地图。
+
+节点像散开的坐标点，有明显留白和空间感。普通节点保持小点形态，重点节点才默认显示名字。重点节点包括社区核心节点、结构上更重要的节点、搜索命中、已固定节点，以及当前选中节点。
+
+社区底色保留，但只作为很淡的氛围提示。它说明“你正在这个社区里”，不作为硬边界，也不限制节点位置。节点可以在视觉上更自由地分布，避免被一整块背景色压住。
+
+线在默认状态下很细、很安静，只提示社区内部存在关系，不抢节点层级。默认状态不强调所有边的完整解读，只有用户悬停或点击节点时，关系才进入可读状态。
+
+节点颜色继续区分节点性质，例如主题、实体、来源、对比或综合类节点。颜色必须克制，不和边的颜色抢语义。
+
+## 标签策略
+
+默认只显示重点节点标签。
+
+普通节点默认不显示名字，只保留可见点位。鼠标悬停或节点被聚焦时，才显示对应标签。这样社区第一眼是地图，而不是文字墙。
+
+标签显示必须稳定：
+
+- 悬停时标签出现，但节点本身不能因为标签出现而移位。
+- 标签不应撑大节点的命中区域。
+- 标签应优先避开核心节点和高亮线，不让关键关系被遮住。
+- 标签过长时截断，不把画面横向撑开。
+
+## 悬停与点击
+
+悬停和点击使用同一套关系聚焦逻辑。
+
+区别只在于：
+
+- 悬停是临时聚焦，鼠标移走后恢复。
+- 点击是固定聚焦，会保持住，并同步更新右侧面板。
+
+当没有固定选中节点时，鼠标放到某个节点上，地图立即进入临时聚焦：
+
+- 当前节点最清楚。
+- 一度相关节点清楚显示。
+- 当前节点到一度节点之间的线清楚显示。
+- 二度相关节点保留很淡的背景感。
+- 无关节点和无关线退到几乎不可见。
+- 鼠标移走后恢复默认地图。
+
+点击某个节点后：
+
+- 使用同样的聚焦视觉。
+- 该聚焦状态固定。
+- 右侧面板显示该节点内容。
+- 点击另一个节点时切换固定聚焦。
+- 点击社区画布空白处时，取消固定聚焦，回到默认地图。
+
+当已经有固定选中节点时，再悬停其他节点：
+
+- 临时展示悬停节点的关系。
+- 鼠标移走后回到已固定节点的聚焦状态。
+- 不因为悬停改写右侧面板内容。
+
+## 关系距离规则
+
+以当前被悬停或点击的节点作为焦点节点。
+
+一度相关节点：
+
+- 与焦点节点直接相连。
+- 直接连线清晰可见。
+- 节点标签优先显示。
+- 节点透明度和点尺寸略高于默认。
+
+二度相关节点：
+
+- 与一度节点相连，但不直接连接焦点节点。
+- 只保留很淡的背景存在感。
+- 默认不显示标签。
+- 二度连线通常不完整呈现，只作为极淡的延伸提示。
+
+无关节点：
+
+- 与焦点节点没有一度或二度关系。
+- 退到几乎不可见，但不制造画面跳变。
+- 默认不显示标签。
+- 无关节点之间的线隐藏或接近不可见。
+
+这里的“一度 / 二度”按现有图谱边关系计算，不引入新的语义数据。
+
+## 线条表达
+
+线条继续遵守现有图例：
+
+- 颜色表示关系类型。
+- 虚实表示置信度。
+- 粗细表示联系强弱。
+
+聚焦状态下，一度直接连线应最清楚。它既要保留颜色和虚实语义，也要通过粗细让强关系更容易被看见。
+
+二度关系可以保留轻微线索，但不能抢一度关系。无关线默认隐藏或极淡。
+
+默认状态下，社区内部所有线都应更克制，避免整张社区图变成线团。只有悬停或点击后，用户才需要读具体关系。
+
+## 右侧面板
+
+地图只负责表达关系，右侧面板负责承接内容。
+
+社区地图里的节点不再展开大卡片，也不显示正文摘要。节点旁边最多显示名字。正文、摘要、路径、相关页面、节点详情继续放在右侧面板里。
+
+点击节点会更新右侧面板，这是允许的现有联动。悬停节点只做地图内临时关系预览，不更新右侧面板。
+
+## 社区底色
+
+社区底色应变得更轻。
+
+它的作用是提示当前社区，而不是圈住节点。视觉上更像一层淡淡的纸面水洗背景，而不是一块实心区域。
+
+当节点进入聚焦状态时，社区底色应进一步退后，让当前节点和一度关系成为主视觉。
+
+## 状态优先级
+
+同一时间最多有一个固定焦点节点。
+
+视觉优先级从高到低：
+
+1. 当前悬停节点。
+2. 当前固定选中节点。
+3. 一度相关节点和直接连线。
+4. 二度相关节点。
+5. 默认重点节点。
+6. 普通节点。
+7. 无关节点和无关线。
+
+如果存在固定选中节点，悬停其他节点时可以临时盖过固定焦点；悬停结束后恢复固定焦点。
+
+## 空状态和边界情况
+
+社区没有边：
+
+- 节点仍按轻量地图显示。
+- 默认只显示重点标签。
+- 悬停节点时只强调该节点本身，并提示暂无直接关系。
+
+节点只有一度、没有二度：
+
+- 一度关系正常高亮。
+- 不强行制造二度背景。
+
+节点连接过多：
+
+- 一度节点可以全部参与高亮，但标签仍按重要性控制。
+- 线条可按权重区分强弱，避免全部同等抢眼。
+
+关系类型或置信度缺失：
+
+- 关系类型缺失时走默认关系色。
+- 置信度缺失时走默认实线。
+- 不因为缺字段破坏社区地图整体可读性。
+
+## 体验验收
+
+实现完成后，进入社区的第一眼必须更像关系地图，不像卡片墙。
+
+必须满足：
+
+- 默认状态有留白，有空间感，节点不挤。
+- 普通节点是轻量点位，不是大卡片。
+- 只有重点节点默认显示标签。
+- 社区底色很淡，不压住节点。
+- 默认线条细、轻，不形成线团。
+- 悬停节点时，关系立刻变清楚。
+- 点击节点时，关系固定，并更新右侧面板。
+- 鼠标移走后，悬停关系自动收回。
+- 点击空白处后，固定关系取消。
+- 一度关系清楚，二度关系很淡，无关内容退后。
+- 线的颜色、虚实、粗细与图例一致。
+- 标签出现和消失时，节点不移位。
+- 不改变全局图谱、对话、知识库流程或其他非社区图谱功能。
+
+## 验证建议
+
+实现时至少验证以下场景：
+
+1. 进入一个有 10 个以上节点、关系较密的社区，确认默认状态不是卡片墙。
+2. 悬停一个核心节点，确认一度关系清晰、二度很淡、无关线隐藏或极淡。
+3. 鼠标移走，确认画面恢复默认状态。
+4. 点击节点，确认聚焦固定并更新右侧面板。
+5. 固定节点后悬停另一个节点，确认只是临时预览，移走后回到固定节点。
+6. 点击空白处，确认取消固定聚焦。
+7. 检查图例里的关系类型和置信度，与画布线条颜色和虚实一致。
+8. 检查长标签、密集节点、无边节点，确认节点不会因为标签出现而移位。
+9. 回到全局图谱，确认本次改动没有改变全局图谱行为。
+
+## 后续不在本次做
+
+以下内容不进入本次社区节点视觉优化：
+
+- 全局图谱重新设计。
+- 移动端专项布局。
+- 新增关系类型或置信度体系。
+- 新的右侧面板结构。
+- 自动社区总结。
+- 图谱数据构建流程调整。
+- 新增完整键盘漫游。
+- 新增 Agent 提问入口。

package/skills/llm-wiki-skill/docs/spark/2026-06-25-sigma-overlay-refactor-perf-design.md

@@ -0,0 +1,170 @@
+# Sigma 覆盖层重构 + 性能改造 设计文档
+
+- 日期：2026-06-25
+- 分支：`feat/sigma-overlay-refactor-perf`
+- 关联 issue：#64 拆分 `sigma-global-renderer.ts`、#63 第 2 条（DOM 重绘重建节点）
+- 范围：本 spec 覆盖 Phase 1（#64）+ Phase 2（#63.2）两阶段。#63 第 1 条（云层签名全量遍历）与 #65（无障碍）**不在本 spec 范围内**，后续单独处理。
+
+---
+
+## 1. 背景与动机
+
+全局视角的知识图谱用 Sigma 在 canvas 上画点和边，再在上面盖一层 DOM/SVG 覆盖物（社区云团、节点命中框、社区标签）。这层覆盖物的全部逻辑集中在
+`packages/graph-engine/src/render/sigma-global-renderer.ts`，当前 **1386 行**，存在两个已确认的问题：
+
+1. **单文件过大（#64）**：云层几何、SVG 渲染、凸包计算、坐标变换都堆在一个文件里。仓库已把 wash 逻辑拆到
+   `community-wash.ts` / `community-washes.ts`，本文件应顺势拆分。
+2. **每帧重建 DOM（#63 第 2 条）**：`renderSigmaOverlays()` 绑在 Sigma 的 `afterRender` 事件上
+   （`sigma-global-renderer.ts:426`），**平移/缩放的每一帧**都先 `overlayRoot.replaceChildren()` 清空
+   （`:623`），再全量重建所有节点命中框、云层 SVG，并重新绑定 click / pointerdown / mousedown / dragstart
+   监听（`:621-715`）。但相机移动时节点集合并未改变，只有屏幕坐标变了——这是典型的 DOM 抖动热路径。
+
+> 注：PR #60 的 1000 节点回归已通过，当前规模不卡。本改造目标是降低维护成本、消除架构坏味道，为更大规模做准备。
+
+### 设计原则
+
+- 两个 Phase 相互独立、可分别合并。**Phase 1 是纯搬迁（零行为变化），Phase 2 才动行为。**
+- 先拆后优化：在 1000+ 行单文件里直接改性能热路径风险叠加；拆完后 Phase 2 改动面更小、更好测。
+- 依赖单向：`sigma-coordinates` ← `community-cloud-geometry` ← `sigma-overlay-svg` ← 主文件（编排）。
+- 不改对外接口（`SigmaGlobalRenderer`），workbench 侧零感知。
+- 遵循 YAGNI：不做通用 diff 框架、不顺手重构无关代码。
+
+---
+
+## 2. Phase 1（#64）：按职责拆 3 个 helper
+
+从 `sigma-global-renderer.ts` 抽出三组纯函数 / 无状态工厂。主文件只保留编排核心：
+`createSigmaGlobalRenderer`、生命周期、拖拽会话、事件接线、Graphology 属性映射、hit projector、edge style。
+
+| 新文件 | 搬入内容 | 性质 |
+|---|---|---|
+| `render/sigma-coordinates.ts` | `sigmaWorldPointToScreenPoint`、`sigmaScreenPointToWorldPoint`、`overlayPointerScreenPoint` | 坐标变换 |
+| `render/community-cloud-geometry.ts` | `SigmaCommunityCloud` / `SigmaCommunityCloudBasis` 接口、`sigmaCommunityCloudBasisById` + `...WithReuse` + `...WithNodePoint`、`sigmaCommunityCloudSignature`、`sigmaProjectedCloudHullPoints`、`clampPointToWorldEllipse`、`clampPointToScreenEllipse`、`sigmaCommunityCloud`、`convexHull2d` | 几何 / 凸包，多为纯函数 |
+| `render/sigma-overlay-svg.ts` | `SIGMA_OVERLAY_SVG_NS`、`nextSigmaCloudFilterSequence`、`sigmaSharedCloudFilterDef`、`sigmaCloudSvg`，及 overlay 元素工厂 `sigmaOverlayButton` / `sigmaOverlayPassiveElement` / `applyOverlayBox` / `createSigmaOverlayRoot` | DOM / SVG 构造 |
+
+依赖说明：`community-cloud-geometry` 中的投影函数（`sigmaProjectedCloudHullPoints`、`sigmaCommunityCloud`）
+依赖坐标变换，故 import `sigma-coordinates`，单向依赖。
+
+预计主文件从 1386 行降到约 1000 行。
+
+### Phase 1 验收
+
+- 行为零变化。
+- 现有 8 个 graph-engine 测试全绿（`npm test`），`npm run typecheck` 通过。
+- 几何纯函数补独立单测（凸包、签名、clamp、坐标往返）——这些此前埋在主文件内未单独测。
+
+> 这些函数当前均为**模块私有、未对外导出**，搬到新 helper 后由新 helper 各自 `export`（供单测直接
+> import），主文件再 import 回来使用。**公开 API（`SigmaGlobalRenderer` 等）与 `src/index.ts`
+> barrel 不变**，workbench 侧零感知。模块级计数器 `sigmaCloudFilterSequence` 随 SVG 函数整组搬走，
+> 仍是同一个计数器，行为不变。
+
+---
+
+## 3. Phase 2（#63.2）：拆"结构更新"与"位置更新"
+
+把唯一的 `renderSigmaOverlays()`（每帧 `replaceChildren` 全量重建）拆成两条路径。
+
+### `rebuildSigmaOverlays()` — 仅数据 / 选中变化时调用
+
+- 按 id 做 diff：复用已存在元素，新增缺失的、移除多余的；维护三张
+  `Map<id, element>`（节点命中框、社区云层 region、社区标签各一张）。
+- 监听器（click / pointerdown / mousedown / dragstart）**只在元素创建时绑一次**。
+- 处理由数据决定的状态：selected / dim / searchHit / pinned、label 文本等。
+
+> 覆盖层只渲染**这 3 类** DOM 元素。aggregation 容器画在 Sigma canvas 上（走 Graphology
+> 属性），不属于本覆盖层，本改造不涉及。
+
+### `repositionSigmaOverlays()` — 绑 `afterRender` / resize / 拖拽移动，每帧调用
+
+- 遍历已存在元素，只更新屏幕坐标（`applyOverlayBox`）与云层 SVG 的 `points` 属性。
+- **绝不** `replaceChildren` / `createElement` / `addEventListener`。
+
+### 调用点改造
+
+| 位置 | 现状 | 改为 |
+|---|---|---|
+| 初始渲染（`:336`） | `renderSigmaOverlays()` | `rebuildSigmaOverlays()` |
+| 数据更新（`:382`） | `renderSigmaOverlays()` | `rebuildSigmaOverlays()` |
+| `afterRender` 相机移动 | `renderSigmaOverlays()` | `repositionSigmaOverlays()` |
+| resize raf | `renderSigmaOverlays()` | `repositionSigmaOverlays()` |
+| 拖拽提交/取消（`applyNodeDragPoint` 终态） | `renderSigmaOverlays()` | `rebuildSigmaOverlays()` |
+
+选中变化走数据更新路径（触发 rebuild），因此 dim / selected 不进每帧热路径。
+
+> 实现修正（TDD 发现）：原以为"拖拽 → reposition"。实际上拖拽**过程中**的每帧位置更新由
+> `sigma.refresh()` → `afterRender` → reposition 负责；而 `applyNodeDragPoint` 里那处直接调用是
+> 拖拽**提交/取消的终态**，此时 pin 状态与永久坐标已变（数据变化），必须 rebuild 才能刷新
+> `dataset.pinned` 等属性。
+
+### 状态归属与不变量（防止双路径打架）
+
+覆盖层完全自封闭：生产代码里只有本文件操作 `overlayRoot` 与几何/SVG 函数，无第二处
+监听 `afterRender`。因此冲突风险只在文件内部的 rebuild / reposition 之间，必须守住以下不变量：
+
+- **rebuild 是元素生命周期的唯一权威**：只有它能增删元素、维护三张 `Map<id, element>`、绑监听。
+- **reposition 对结构只读、且幂等**：只改已存在元素的位置/box 与云 hull 投影；遇到表里有、
+  但当前 `adapterData` 已无的 id，安全跳过（不报错、不创建）。
+- **reposition 每帧从 `cloudBasisByCommunityId` 重新投影云 hull**：拖拽中 basis 冻结、松手才重算，
+  reposition 必须每次重投影才能让云层跟手（与现有行为一致）。
+- **`update()` 的执行顺序安全前提**：现状 `sigma.refresh()`（`:381`）→ 真实 Sigma 触发 `afterRender`
+  → reposition，**早于** 紧随其后的 rebuild（`:382`）。因 reposition 满足"只读+容忍不同步+幂等"，
+  这次提前的 reposition 至多对旧元素做一次无害定位，rebuild 随后纠正为准。
+- **`afterRender` 与 `cameraUpdated` 都绑同一处理器**（`:425-426`），reposition 一帧可能跑 2 次；
+  因幂等无害，暂不做 rAF 去重（YAGNI，后续按需）。
+
+### 关键风险点
+
+云层每帧的 hull 投影点会变，所以 reposition 必须更新 polygon 的 `points` 属性和容器 box，
+同时保留同一个 shape 元素及其 click 监听。这是整个改造里最需要小心的一处，测试需专门覆盖。
+
+---
+
+## 4. 错误处理与边界
+
+- 两条路径都保留 `destroyed` 守卫。
+- 销毁时清空三张 `Map<id, element>`，避免悬挂引用。
+- diff 按 id 增删；id 不变但内容变（如 label 文本）在 rebuild 内更新属性。
+- 不改对外接口 `SigmaGlobalRenderer`。
+
+---
+
+## 5. 测试方案
+
+### Phase 1
+
+- 现有回归全绿 + 几何纯函数新单测（凸包、签名、clamp、坐标往返）。
+
+### Phase 2（验收标准：可量化性能基线）
+
+在 `test/sigma-global-renderer.test.ts` 复用现有 `fakeContainer()` / `fakeRuntime()` / `sigma.emit()`
+基础设施（fake 元素内部已用 Map 记录子节点与监听，无需引入 jsdom）：
+
+1. **量化基线断言**（核心）：渲染后记录元素引用与 createElement / addEventListener 调用计数 →
+   多次 `sigma.emit("afterRender")` → 断言**元素实例不变、createElement 计数不增、监听计数不增、
+   `replaceChildren` 在 reposition 路径未被调用**。
+2. **行为保持**：点击云层 → 社区选中、点击节点 → 节点选中、拖拽仍生效（沿用现有 emit 用例）。
+3. **结构 diff**：数据更新增 / 删节点后，元素表正确增删。
+4. **需更新的现有断言**：现有 resize 测试（`test/sigma-global-renderer.test.ts:574`）当前断言
+   resize 后覆盖层元素被**新建**（`assert.notEqual`）。Phase 2 后元素改为**复用**，这条须改成
+   `assert.equal`。这是**预期内的行为变更，不是回归**——它恰好验证了"reposition 不再重建元素"。
+5. **第三层手动回归**：在 codex 跑 1000 节点平移 / 缩放，主观确认不卡 + 基线测试通过
+   （按 CLAUDE.md 推送前测试规则）。
+
+---
+
+## 6. 分 Phase 推进计划
+
+- **Phase 0（本次 spark）**：写本 spec，分支 `feat/sigma-overlay-refactor-perf`。
+- **Phase 1**：拆 3 个 helper → 跑回归 → 分步 commit → 可单独开 PR 合入（纯重构、低风险）。
+- **Phase 2**：基于 Phase 1 改双路径 + 量化基线测试 → codex 回归 → commit → PR。
+- **文档**：每个含功能改动的 Phase，按 CLAUDE.md 更新 CHANGELOG / README / 版本号。
+
+---
+
+## 7. 验收清单（汇总）
+
+- [ ] Phase 1：主文件显著瘦身、行为零变化、现有测试与 typecheck 全绿、几何函数有独立单测。
+- [ ] Phase 2：`afterRender` 路径不再销毁 / 重建 DOM、不重绑监听（量化测试断言通过）。
+- [ ] Phase 2：点选社区 / 点选节点 / 拖拽行为与改造前一致。
+- [ ] Phase 2：1000 节点 codex 手动回归平移缩放不卡。
+- [ ] 对外接口 `SigmaGlobalRenderer` 无变化，workbench 无需改动。