@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/skills/llm-wiki-skill/workbench/docs/stage-4.5-design.md

@@ -0,0 +1,195 @@
+# 阶段 4.5 设计文档：图谱可用性收尾
+
+> 状态：**设计完成，待作者审定后实施**
+> 日期：2026-06-13
+> 来源：阶段四交付后作者实测反馈 + 验收发现（离线 HTML 功能减配裁决），经 2026-06-13 三轮设计讨论沉淀。
+> 与 [stage-4-design.md](stage-4-design.md) 的关系：本文档修订其 D6（选区动作映射）并补全其遗漏（画布导航）；冲突处以本文档为准。
+
+---
+
+## §0 背景：五个实测问题 + 一个验收裁决
+
+阶段四验收通过后，作者实际使用暴露以下问题（按根因分类）：
+
+| # | 问题 | 根因 |
+|---|---|---|
+| 1 | 画布不能缩放、不能平移 | **plan 盲区**：视口数学（`zoomAtlasViewport` 等）Phase 1 已搬进引擎，但渲染器从未接交互——有发动机没装油门 |
+| 2 | 点击节点弹出选区悬浮窗，看不懂、有废话信息（单节点显示"1页/0链接/1社区/0孤立"）、动作错位（单节点出现"探索潜在联系"）、悬浮窗还遮住所选节点 | **设计盲区**：stage-4 D6 动作映射表没有"单节点"行，单节点内部链接恒为 0 被误判进"无链接多选"剧本；且点击语义被"提问"独占，**阅读路径消失** |
+| 3 | Shift 多选按了没反应 | 代码存在（`static-renderer.ts:581` 监听 shiftKey），疑似失效待排查；且**零可发现性**——界面无任何提示 |
+| 4 | 无图谱内搜索、社区颜色无图例、无聚焦入口 | 阶段四验收裁决项：离线 HTML 功能减配，作者选定"补核心、缓其余" |
+| 5 | 节点默认卡片三行（类型文字/标题/权重数字）过胖 | 密度策略已接线（大库自动降级），但"卡片档"本身信息冗余：类型已由左边条颜色编码，文字行重复；权重数字对用户无含义 |
+
+**验收裁决**（作者拍板）：搜索 + 社区聚焦补回；**学习系统三件套（学习队列、"从这里开始"学习路径、札记笔记）不做**，等真实使用后在工作台语境重新设计，不照搬旧版。
+
+---
+
+## §1 核心决策（D4.5-1 ~ D4.5-9）
+
+### D4.5-1 画布导航（P0，最高优先级）——丝滑规格
+
+> 作者用旧版（发布版 Skill）生成真实库图谱实测"缩放不够丝滑"。诊断：旧版方向正确（指数缩放/指针锚点/单层 transform 都有），病根在四个工程细节——无帧合并（触控板每秒上百事件逐个触发完整渲染）、高频路径混入重活（SVG 边层属性重算+小地图重绘）、不区分鼠标/触控板 delta、内容层未提升 GPU 合成。本节规格以"丝滑"为验收目标，不止"有"。
+
+**交互行为**：
+- 滚轮缩放，**以鼠标指针位置为缩放中心**；ctrl+wheel（浏览器捏合约定）同路支持
+- 空白处拖拽 = 平移画布（节点上拖拽 = 移动节点，按事件目标区分，互不冲突）
+- 双击空白处 = 回到全图（fit）；小地图与视口实时联动（接视口矩形）
+- 缩放范围夹紧：fit 的 0.5× ~ 4×
+
+**丝滑六条（实现规格，❗ 逐条进验收）**：
+1. **单层合成变换**：节点/边/团块挂同一内容层，缩放平移只改该层一条 CSS transform（translate+scale），节点 DOM 与样式零触碰；层声明 `will-change: transform` 提升 GPU 合成层——帧成本与节点数无关
+2. **rAF 帧合并**：wheel/pointermove 只更新目标视口数值，写 DOM 仅发生在 requestAnimationFrame 回调，每帧至多一次
+3. **设备归一化**：按 `deltaMode` 区分鼠标（行）与触控板（像素），各自缩放系数；指数缩放 `s' = s·exp(-Δ·k)` 保持手感线性
+4. **跟手零动画，跳转才有动画**：滚轮/拖拽逐帧直接应用，**禁止加过渡**（wheel 上加缓动 = 橡皮筋延迟感的来源）；双击回全图 / 图例飞行 / 搜索命中飞行用 ~200ms ease-out
+5. **语义缩放**：密度档位与缩放联动——节点屏幕投影小于阈值自动降为紧凑标签/圆点，放大长回卡片，档位切换 ~150ms 交叉淡入；现有密度策略从"按节点总数定档"升级为"按屏幕有效密度定档"
+6. **高频期降载**：缩放/平移进行中暂停团块重晕染与小地图精绘（沿用"拖动中团块淡化"惯例），交互停止 ~150ms 后恢复精绘
+
+**其余约束**：
+- **引擎层实现**，工作台与离线 HTML 同享；作者手中旧版生成的 HTML 不修，4.5 完成后重新生成即得新版
+- ❗ 与钉扎无冲突：钉扎存**模型坐标**，视口只是观察矩阵，两者正交——实现时不得把视口偏移混进节点坐标
+- 不做：惯性滚动（基础做对优先）
+
+### D4.5-2 点击语义重构："点击即阅读，选区即升级"
+
+**选区悬浮窗取消。** 右抽屉统一承载，一个容器两种状态：
+
+```
+单击节点          → 右抽屉【阅读态】（页面正文），节点在图上高亮，无浮窗
+Shift+点第二节点  → 抽屉切【选区态】（结构事实 + 动作）
+点社区团块/图例    → 直接进入【选区态】（整簇）
+阅读态点"+邻居"   → 升级为【选区态】（该节点+一跳邻居）
+Esc / 关闭抽屉    → 清空选区，回到纯画布
+```
+
+理由：用户点一个节点，心里的问题是"这是什么"（阅读），不是"你想执行什么操作"（提问）。提问是阅读后的升级动作，不是点击的默认答案。抽屉不遮画布（解决悬浮窗盖住所选节点）、复用工作台既有抽屉基建与用户心智（引用预览/产物预览同款容器）、宽度可拖与移动端全屏适配都是现成的。
+
+### D4.5-3 抽屉【阅读态】蓝图（瘦身定稿）
+
+```
+┌──────────────────────────────┐
+│ Pi Agent SDK                 │  ← 标题
+│ 来源 · 2026-06-10 · 查看原文  │  ← 元信息一行：类型中文 · 更新日期 ·（仅 source 页）原文链接
+│ [ 问这一页 ]  [ + 邻居 ]      │  ← 动作条，仅此两个；孤岛节点额外显示 [ 帮它链入知识库 ]
+├──────────────────────────────┤
+│ 正文 markdown                 │  ← wikilink 可点：抽屉内换页 + 图谱 focusNode 联动高亮
+│ （置信度标注随正文自然呈现）    │
+└──────────────────────────────┘
+```
+
+**去除清单**（对照旧版札记栏，逐项有理由）：
+
+| 旧版元素 | 处置 | 理由 |
+|---|---|---|
+| 学习队列 / "从这里开始" / 札记笔记 | 去（作者拍板） | 学习系统三件套整体不做 |
+| "摘要"区块 | **迁移至 hover 预览卡**（见 D4.5-7） | 摘要的价值在"读前决策"（图上扫视时判断要不要点开），不在"阅读中"（正文第一段就在眼前）。旧版的别扭是住错了房间，不是摘要无价值——抽屉内不设摘要区，摘要搬到悬停预览 |
+| 置信度独立列表 | 去区块 | 置信度标注本就写在页面正文里，渲染时自然呈现；单独列表是又一个派生重复区。**不是砍特色，是去重复** |
+| 相邻节点列表 | 去 | 关系归图谱管：正文 wikilink 可点 + "+邻居"一键扩选区 + 左边整张图就是关系视图 |
+| "查看来源"大按钮 | 收纳 | 溯源保留（数据可信的根基），收成元信息行小链接 |
+| `kind · sourcePath` 技术化 meta | 改写 | 类型改中文（实体/主题/来源），完整文件路径藏进"查看原文"，补更新日期 |
+
+设计原则一句话：**抽屉负责内容，图谱负责关系，凡从正文派生的信息不重复展示。**
+
+- 不做抽屉内浏览历史栈（wikilink 点击直接换内容，避免抽屉变浏览器）。
+- 离线 HTML 内置 reader 同步微调 meta 行（中文类型 + 日期），保持两端一致；离线 reader 其余结构已是瘦身版，不动。
+
+### D4.5-4 选区态修订 + 动作映射表完整版（修订 stage-4 D6）
+
+| 选区类型 | 统计卡显示 | 动作 |
+|---|---|---|
+| **单节点（新增行）** | **不显示统计卡** | 总结这一页 / 它和谁有关 / 在对话中引用 |
+| 单节点且为孤岛 | 不显示 | 上述 + 帮它链入知识库 |
+| 单社区 | N 页 · M 条内链 | 总结这一簇 / 找知识缺口 / 生成主题页 |
+| 两社区 | 两簇间 K 条链接 | 为什么（没）联系 / 找潜在桥梁 / 对比这两块 |
+| ≥2 节点多选，互有内链 | N 页 · M 条内链 | 总结这一组 / 探索它们的关系 |
+| ≥2 节点多选，零内链 | N 页 · 无相互链接 | 探索潜在联系 / 对比异同 |
+
+修订要点：
+
+1. ❗ **修复 unlinked 误触发**：单节点选区不得落入"零内链多选"剧本（这就是"探索潜在联系"出现在单节点上的 bug 根源）
+2. 统计卡仅在 ≥2 节点时显示；"孤立"计数仅在 >0 时出现（不显示恒零项）
+3. 自由输入框降权：占位文案改"补充说明（可选）"，视觉弱化，动作按钮是主路径
+4. **可发现性**：选区态首行常驻浅字提示 "Shift+点击 增删节点"
+5. Shift 失效排查：实施第一步先在真实浏览器复现作者"按了没反应"的场景，修复后补回归断言（具体原因实施时查明并记录）
+
+### D4.5-5 图谱搜索（两端）
+
+- `Cmd/Ctrl + F`（图谱视图聚焦时）浮出搜索框；输入即时：命中节点高亮、其余淡化；`Enter` 视口飞向下一个命中（依赖 D4.5-1 先行）；`Esc` 退出恢复
+- 复用引擎既有 helper（`buildSearchIndex` / `applySearchToNodeIds` / `buildSearchHaystack`——6.2 的测试至今保护着它们）
+- ❗ 测试反转说明：`tests/graph-html-search.regression-1.sh` 在阶段四被改写为断言"旧搜索 UI 不存在"，本阶段需再次改写为断言**新搜索 UI 存在**——这是预期内的轮回，不是反复
+
+### D4.5-6 社区聚焦列表（兼图例，两端）
+
+- 画布左上角小图例：每社区一行 = 色块 + 社区名 + 页数
+- 一物三用：解释团块颜色含义（当前用户全靠猜）/ hover 高亮整簇 / 点击 = 选中该社区（接 D4.5-4 选区态）+ 视口飞至该簇
+- 折叠为小图标可收起，状态存本机（浏览状态不入库文件，沿用 stage-4 D9 原则）
+
+### D4.5-7 节点默认态瘦身 + hover 预览卡（配套设计）
+
+- 默认态：**一行标题 + 类型色条**（左边条颜色已编码类型——ENTITY 红、SOURCE 绿等——文字行直接删）
+- 权重数字（`priority/weight`）从默认态移除，hover/选中展开完整卡片时显示
+- **hover 预览卡**（瘦身的另一半：瘦下去的信息从悬停里长回来）：悬停节点浮出小卡——标题 + 类型中文 + **摘要两三行**。摘要来源：❗ graph-data 节点**无 summary 字段**（已查证，字段仅 content/label/type/community/source_path），从 `content` 现场提取首个有效正文段落截断，复用引擎已有正文清洗函数（`stripAtlasMarkdown`，A 级搬运已在 model 模块）；content 为空则只显示标题+类型。预览卡是只读浮层，不可交互、跟随移开即逝、有 ~300ms 延迟防误触
+- hover/选中态（节点本体）：展开为现有完整卡片
+- 密度策略保持不动（大库自动降级到紧凑标签/圆点的逻辑已在），本条只是把"卡片档"瘦一号；**点状/紧凑档的节点同样有 hover 预览卡**（大库下预览卡价值更高）
+- 验收用 `graph-interactive-dense` fixture 确认密度降级路径不受影响
+- 两端同享（离线 HTML 白拿预览卡）；AI 生成真摘要（消化时写入页面元数据、管线优先读取）是内容质量升级，**本阶段不做**，记入 D4.5-9
+
+### D4.5-8 工作台抽屉阅读态的数据来源
+
+复用阶段二引用预览的页面读取 API（`/api/refs` 体系），不新增后端端点。GraphPanel 因 d5a83f8 后体量偏大，允许拆分子组件文件（GraphReader / GraphSelection），属于本阶段直接产生的合理拆分，不算顺手重构。
+
+### D4.5-9 明确不做
+
+| 不做 | 原因 |
+|---|---|
+| 学习队列 / 学习路径 / 札记笔记 | 作者拍板：等真实使用后按工作台语境重新设计，不照搬旧版 |
+| 抽屉内浏览历史栈（前进/后退） | 抽屉不是浏览器；wikilink 直接换页够用 |
+| 缩放惯性 / 动画曲线调优 | 先把基础导航做对 |
+| AI 生成真摘要（消化时写入页面元数据） | 内容管线改动，不混进 UI 收尾；hover 预览卡先用正文首段，管线升级后自动变好 |
+| 移动端触控全套手势 | 桌面优先；wheel 事件天然覆盖触控板，触屏完整支持留 Tauri 阶段 |
+
+---
+
+## §2 实施面
+
+```
+packages/graph-engine/
+├── render/   视口交互接线（wheel/drag/dblclick + 小地图联动）、节点默认态瘦身、
+│             搜索 UI、社区图例、离线 reader meta 微调
+├── select/   动作映射表修订（单节点行 + unlinked 修复 + 统计卡条件）
+└── index.ts  视口控制 API 暴露（fitView / focusNode 带飞行）
+
+workbench/web/
+├── GraphPanel 拆分：GraphReader（阅读态）+ GraphSelection（选区态），悬浮窗删除
+└── 右抽屉接线：阅读态复用引用预览的 markdown 渲染与页面读取
+
+tests/
+├── 引擎单测：映射表六行剧本、视口数学接线、瘦身 DOM、搜索高亮
+└── 回归：graph-html-search 反转为"新搜索 UI 存在"；图例/导航钩子断言
+```
+
+后端：**零改动**。离线 HTML：引擎升级自动获得导航/搜索/图例（两端红利）。
+
+## §3 验收剧本（给实施 plan 引用）
+
+1. **导航**：滚轮以指针为中心缩放；空白拖拽平移；双击空白回全图（带缓动）；小地图框联动；**离线 HTML 双击打开后同样全部可用**。**丝滑判据**：①缩放平移期间 DOM 断言节点元素的内联样式不变化（只有内容层 transform 变）；②对 dense fixture（200+ 节点）连续滚轮 3 秒，帧率不低于 50fps（Playwright trace 或性能面板取证，环境不支持则标 manual）；③触控板与鼠标滚轮各自体感正常（manual）；④zoom out 节点自动降档、zoom in 长回卡片，切换无闪跳
+2. **点击**：单击节点 → 右抽屉阅读态（标题/元信息/双动作/正文），无悬浮窗；抽屉内**不存在**队列/摘要/置信度列表/邻居区块；正文 wikilink 点击换页且图上高亮跟随
+3. **选区**：Shift+点第二节点 → 抽屉切选区态且首行有 Shift 提示；单节点无统计卡、动作为单节点剧本、**"探索潜在联系"不出现**；点社区 → 统计与动作正确；孤岛单节点出现"帮它链入知识库"
+4. **搜索**：Cmd+F → 输入 → 命中高亮其余淡化 → Enter 飞向命中 → Esc 恢复；离线 HTML 同样可用
+5. **图例**：左上角社区列表与团块颜色一致；点击 → 选中整簇 + 视口飞至
+6. **节点**：默认一行 + 色条；hover 节点本体展开完整卡，同时浮出预览卡（标题/类型中文/正文首段摘要 2-3 行）；content 为空的节点预览卡无摘要不报错；dense fixture 下密度降级正常且点状档同样有预览卡
+7. **主题**：以上全部在山水 / 墨夜两主题下正常
+8. **自动化**：主仓库 JS 测试 / regression / typecheck / 引擎测试 / 双产物构建全绿
+
+## §4 风险
+
+| 风险 | 对策 |
+|---|---|
+| 视口变换混进节点坐标，破坏钉扎 | D4.5-1 已写死"模型坐标与观察矩阵正交"；引擎单测断言：缩放平移后钉位模型坐标不变 |
+| Shift 失效根因未知 | 实施第一步真实浏览器复现，根因记录进 progress decision_log |
+| graph-html-search 测试二次反转引起困惑 | D4.5-5 已注明轮回原因，commit message 同步说明 |
+| GraphPanel 拆分引入回归 | 拆分是纯移动 + 接线，现有 web 测试（selection prompt / api / wiki-link）必须保持绿 |
+
+## Changelog
+
+- 2026-06-13 v3（导航丝滑规格）：作者用旧版生成真实库图谱实测"缩放不丝滑"——D4.5-1 从"有缩放"升级为"丝滑规格"：诊断旧版四病根（无 rAF 帧合并 / 高频路径混重活 / 设备 delta 不区分 / 无 GPU 合成层），定丝滑六条（单层合成变换、帧合并、设备归一化、跟手零动画+跳转缓动、语义缩放、高频降载），验收剧本第 1 条补丝滑判据（含 dense fixture 50fps 基准）。
+- 2026-06-13 v2（摘要处置修订）：作者反馈摘要应保留——修正 v1 把"摘要"与"摘要区"混为一谈的判断。摘要的价值在读前决策（图上扫视），不在阅读中（正文在眼前）：抽屉内仍无摘要区，摘要迁移至 **hover 预览卡**（D4.5-7，与节点瘦身配套：瘦下去的信息从悬停长回来）。已查证 graph-data 无 summary 字段，预览卡从 content 现场提取首段（复用 stripAtlasMarkdown），零数据层改动；AI 真摘要管线列入明确不做（留内容质量升级阶段）。验收剧本第 6 条同步。
+- 2026-06-13 v1：首版。来源：作者实测五问题 + 阶段四验收裁决；含 D4.5-1~9、动作映射表完整版（修订 stage-4 D6）、抽屉瘦身去留表、实施面与验收剧本。

package/skills/llm-wiki-skill/workbench/docs/superpowers/specs/2026-05-28-resizable-preview-layout-design.md

@@ -0,0 +1,165 @@
+# 可拖动预览区与侧栏折叠设计
+
+状态：已实现并验证
+
+创建日期：2026-05-28
+
+实现日期：2026-05-28
+
+## 背景
+
+当前界面是左侧知识库导航、中间对话、右侧预览的三段式布局。左侧栏固定 270px，右侧预览打开后固定 420px。这个设计稳定，但在直接预览 HTML/PDF/页面产物时，右侧区域偏窄，用户常常需要全屏才能看清内容；全屏又会完全遮住对话上下文。
+
+本设计补强现有产品方向：对话仍是主屏，右侧预览仍是辅助面板，但允许用户在“边聊边看”和“重点看预览”之间快速调整空间。
+
+## 目标
+
+- 右侧预览区可以通过鼠标拖动左边缘变宽或变窄。
+- 左侧知识库栏可以折叠成窄图标栏，释放更多横向空间。
+- 窄图标栏的每个按钮都有悬停文字提示。
+- 用户调整后的侧栏状态和预览宽度会被记住。
+- 保留现有全屏预览按钮，作为只看产物的极端模式。
+
+## 不做什么
+
+- 不把三栏全部做成自由拖动。左侧栏是导航区，折叠已经能解决占空间问题。
+- 不新增 npm 依赖。
+- 不改变知识库、对话、产物的数据结构。
+- 不改变右侧预览的内容渲染方式。
+
+## 方案选择
+
+采用“右侧预览可拖动 + 左侧栏折叠为窄图标栏”。
+
+对比过三个方向：
+
+- 只让右侧预览可拖动：最稳，改动集中，但左侧仍占固定空间。
+- 三栏都可拖动：自由度最高，但容易拖乱界面，状态和边界复杂度更高。
+- 预设宽度 + 全屏：简单，但不如拖动自然。
+
+最终方案在第一个方向上补上左侧栏折叠，既保留清晰心智，又能明显释放预览空间。
+
+## 交互设计
+
+### 左侧栏
+
+完整侧栏保持当前结构：顶部品牌和操作按钮，下面是知识库与对话列表，底部是新建和添加入口。
+
+新增一个“切换侧栏”按钮，放在侧栏顶部，与刷新、设置同级。点击后侧栏在两种状态间切换：
+
+- 完整侧栏：显示知识库、对话、按钮文字。
+- 窄图标栏：只显示核心图标，不显示长文字。
+
+窄图标栏至少包含：
+
+- 展开侧栏
+- 当前知识库入口
+- 新建知识库
+- 添加现有库
+- 设置
+
+所有图标按钮都需要悬停提示，例如“展开侧栏”“当前知识库”“新建知识库”“添加现有库”“设置”。
+
+折叠状态不应该让用户迷路：窄栏始终保留展开按钮，且当前知识库入口要能表达“当前仍在某个库里”。
+
+### 右侧预览
+
+右侧预览打开时，在它的左边缘显示一条细拖动把手。
+
+交互规则：
+
+- 按住把手向左拖，预览区变宽。
+- 按住把手向右拖，预览区变窄。
+- 双击把手，恢复默认宽度。
+- 关闭预览区后释放空间。
+- 再次打开预览区时使用上次宽度。
+- 全屏按钮保留，进入全屏后不显示拖动把手。
+
+### 宽度边界
+
+右侧预览宽度需要限制在合理范围内：
+
+- 默认宽度：420px。
+- 最小宽度：360px，保证预览和标签仍可用。
+- 最大宽度：视口宽度的 70%，但必须给中间对话保留至少 420px。
+
+当窗口太窄时，优先保证对话区可用；移动端沿用现有逻辑，右侧预览占满屏幕，不启用拖动。
+
+### 状态记忆
+
+使用本地浏览器存储记住：
+
+- 侧栏是否折叠。
+- 右侧预览宽度。
+
+刷新页面后恢复上次状态。异常值需要自动回到默认值，避免用户因为窗口变化进入不可用布局。
+
+## 页面结构
+
+整体仍是三段式：
+
+- 左：导航区，完整侧栏或窄图标栏。
+- 中：对话区，占用剩余空间。
+- 右：预览区，打开时显示，宽度可调整。
+
+中间对话区不设置固定宽度，而是随左右两侧变化自动伸缩。这样右侧拉宽时，对话区自然变窄；右侧收窄或关闭时，对话区自然变宽。
+
+## 实现边界
+
+预计改动集中在：
+
+- `web/src/App.tsx`：保存侧栏状态、预览宽度，并传给组件。
+- `web/src/components/Sidebar.tsx`：支持完整侧栏和窄图标栏两种形态。
+- `web/src/components/RightDrawer.tsx`：增加拖动把手和宽度回调。
+- `web/src/index.css`：增加折叠侧栏、拖动把手、宽度状态的样式。
+
+不需要改后端。
+
+## 可访问性与细节
+
+- 侧栏切换按钮需要有明确的 `aria-label`。
+- 拖动把手需要可聚焦，并提供键盘兜底：左右方向键调整宽度，Home 或双击恢复默认宽度。
+- 拖动中避免选中文本。
+- 拖动中给把手明确的 hover/active 状态。
+- 窄图标栏的提示文案使用现有 tooltip 样式。
+
+## 验收标准
+
+1. 点击侧栏切换按钮，侧栏能在完整侧栏和窄图标栏之间切换。
+2. 窄图标栏按钮悬停时都有清楚提示。
+3. 打开右侧预览后，拖动左边缘能改变宽度。
+4. 双击拖动把手能恢复默认预览宽度。
+5. 预览区拉宽时，中间对话不会被挤到无法使用。
+6. 刷新页面后，侧栏折叠状态和预览宽度仍保持。
+7. 移动端或窄屏下不启用拖动，预览继续按现有方式占满屏幕。
+
+## 验证计划
+
+- 运行前端检查。
+- 启动应用。
+- 打开已有 HTML 产物预览。
+- 手动切换侧栏折叠状态。
+- 手动拖动右侧预览宽度并双击恢复。
+- 刷新页面确认状态保持。
+- 缩小窗口确认不会出现不可用布局。
+
+## 实施结果
+
+已按本文档方案实现：
+
+- 左侧栏支持完整侧栏与窄图标栏切换。
+- 窄图标栏保留展开、当前知识库、刷新、新建、添加、设置入口。
+- 窄图标栏按钮均有悬停提示。
+- 右侧预览支持拖动左边缘调整宽度。
+- 双击拖动边缘恢复默认宽度。
+- 侧栏折叠状态和预览宽度会在本地保留。
+- 移动端沿用全屏预览，不显示拖动边缘。
+
+验证结果：
+
+- `npm run typecheck` 通过。
+- 受控浏览器验证默认预览宽度为 420px。
+- 受控浏览器验证拖动后预览区可变宽，并保持对话区可用。
+- 受控浏览器验证双击拖动边缘可恢复默认宽度。
+- 受控浏览器验证侧栏可折叠为 52px 窄图标栏，刷新后仍保持。
+- 受控浏览器验证移动端预览占满屏幕，拖动边缘隐藏。

package/skills/llm-wiki-skill/workbench/docs/superpowers/specs/2026-05-28-settings-panel-scroll-fix.md

@@ -0,0 +1,50 @@
+# 设置面板滚动修复
+
+状态：已实现并验证
+
+创建日期：2026-05-28
+
+实现日期：2026-05-28
+
+## 背景
+
+设置面板已经承载认证状态、API key、环境变量、模型角色和 Skill 加载。内容高度超过部分屏幕时，弹窗本身没有限制高度，内容区也没有独立滚动，导致底部设置不可见。
+
+## 目标
+
+- 设置面板在普通桌面窗口和较矮窗口里都能看完整内容。
+- 标题和关闭按钮始终保留在弹窗顶部。
+- 设置项在弹窗内部滚动，不影响背后的工作台布局。
+- 不改变设置项的数据逻辑，不新增依赖。
+
+## 方案
+
+采用“弹窗外框限高 + 内容区内部滚动”：
+
+- 弹窗最高不超过屏幕高度，并保留上下边距。
+- 弹窗分成顶部标题区和内容区。
+- 内容区独立滚动，确保底部 Skill 加载设置可达。
+
+暂不改成独立设置页，也暂不拆分设置标签。当前设置仍是辅助操作，用弹窗更符合工作台心智；等设置项继续增多后，再考虑拆成“认证 / 模型 / Skill”等页签。
+
+## 验收标准
+
+1. 打开设置后，底部 Skill 加载区可见或可通过滚动到达。
+2. 设置内容滚动时，标题和关闭按钮仍在顶部。
+3. 不影响 API key 输入、模型角色选择和 Skill 开关。
+4. 前端检查和构建通过。
+
+## 实施结果
+
+已按本文方案实现：
+
+- 设置弹窗增加屏幕高度上限。
+- 弹窗内部采用标题区 + 可滚动内容区。
+- 内容区增加最小高度保护，避免矮窗口下滚动区域被撑开。
+
+验证结果：
+
+- `npm run typecheck` 通过。
+- `npm run build --workspace=@llm-wiki-agent/web` 通过。
+- `npm run lint --workspace=@llm-wiki-agent/web` 通过。
+- Chrome 中打开设置面板，确认底部 Skill 加载区可见，窗口不再遮挡底部内容。

package/skills/llm-wiki-skill/workbench/server/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@llm-wiki-agent/server",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "description": "llm-wiki-agent 后端：Hono + pi-coding-agent SDK",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "scripts": {
+    "prebuild": "npm run build -w @llm-wiki/graph-engine",
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "pretypecheck": "npm run build -w @llm-wiki/graph-engine",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@earendil-works/pi-agent-core": "^0.79.4",
+    "@earendil-works/pi-ai": "^0.79.4",
+    "@earendil-works/pi-coding-agent": "^0.79.4",
+    "@hono/node-server": "^1.13.0",
+    "@llm-wiki/graph-engine": "0.0.0",
+    "hono": "^4.6.0",
+    "typebox": "^1.1.38"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}