@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/llm-wiki/AGENTS.md

@@ -0,0 +1,132 @@
+# AGENTS.md
+
+## 🧭 仓库导航（任何人 / AI 进来先读这里）
+
+本仓库是 **llm-wiki monorepo**，含三个区：
+
+| 区 | 位置 | 状态 |
+|---|---|---|
+| **agent 工作台**（开发主线） | `workbench/`（server + web） | 🚧 活跃开发 |
+| **共享图谱引擎** | `packages/graph-engine/` | 🚧 随 agent 演进 |
+| **Skill 形态** | 根目录 `SKILL.md` / `scripts/` / `templates/` / `platforms/` | ❄️ 成熟·维护冻结 |
+
+➡️ **开发 agent 工作台（日常主线）**：先读 [workbench/AGENTS.md](workbench/AGENTS.md) + [workbench/PRODUCT.md](workbench/PRODUCT.md)——当前阶段、ADR、协作规则都在那里。
+
+➡️ **本文件以下内容**：Skill 形态的安装与维护规则，**仅当你在维护 Skill 时才看**（install.sh / SKILL.md / scripts / templates / platforms）。Skill 已功能成熟、进入维护冻结，不再追加新功能。
+
+---
+
+## Skill 形态：安装与维护
+
+这是 llm-wiki 在 Codex 下的入口文件。
+
+先看这三个文件：
+
+- [README.md](README.md)：多平台总说明
+- [platforms/codex/AGENTS.md](platforms/codex/AGENTS.md)：Codex 专属入口提示
+- [SKILL.md](SKILL.md)：核心能力和工作流
+
+## Codex 安装动作
+
+如果当前任务是安装这个 skill，执行：
+
+```bash
+bash install.sh --platform codex
+```
+
+默认安装到 `~/.codex/skills/llm-wiki`。如果用户机器上还是旧的 `~/.Codex/skills`，安装器也会自动兼容。
+
+默认只准备知识库核心主线。如果这次要自动提取网页 / X / 微信公众号 / YouTube / 知乎，再执行：
+
+```bash
+bash install.sh --platform codex --with-optional-adapters
+```
+
+## 重要提醒
+
+- 不要把这个仓库当成 Codex 专属仓库；Claude Code、OpenClaw、Hermes 也共用同一套核心内容
+- 安装完成后，再按 [SKILL.md](SKILL.md) 的工作流继续做事
+- 如果 OpenClaw 使用的是自定义技能目录，可以改用 `--target-dir <你的技能目录>/llm-wiki`
+
+## 分支管理规则
+
+改动代码（非纯文档/注释）时，按以下流程操作：
+
+1. 开新分支：从 main 创建，命名表达用 feat 或 fix 前缀；Codex 环境默认使用 `codex/` 命名空间，例如 `codex/fix-cache-reliability-write-through`
+2. 分步 commit：每完成一个逻辑单元就提交（脚本实现、测试、文档更新分开 commit）
+3. 推送并创建 PR：推到远端后用 `gh pr create` 创建 PR
+4. 合并：确认测试通过后在 GitHub 上合并
+
+不需要开分支的情况：
+
+- 只改了 AGENTS.md、CLAUDE.md、文档、注释
+- 只是探索性阅读代码
+
+设计文档或 plan 写完准备动手改代码时，也先开分支再开始实现。
+
+## 使用顺序
+
+安装完成后，按 [SKILL.md](SKILL.md) 中的工作流继续执行：
+
+1. `init`
+2. `ingest`
+3. `batch-ingest`
+4. `query`
+5. `digest`
+6. `lint`
+7. `status`
+8. `graph`
+
+## 已记录的解决方案
+
+`docs/solutions/` 存放过去解决问题的文档（bug、最佳实践、工作流改进），按类别分目录，每份有 YAML frontmatter（`module`、`tags`、`problem_type`）。涉及已记录领域时（graph、cache、install、lint 等），先搜一下有没有现成经验。
+
+## 推送前测试规则
+
+每次 `git push` 前必须验证，按改动范围选深度：
+
+### 第一层：快速检查（Codex 直接跑，1 分钟内）
+
+不管改了什么都跑这 3 项：
+
+1. `bash install.sh --dry-run --platform codex` — 安装脚本不报错
+2. 改过的脚本如果有 `tests/fixtures/`，跑一下 diff 预期输出
+3. `grep -r '本机用户路径\|真实姓名\|私有素材路径' scripts/ templates/ tests/ SKILL.md` — 没泄露隐私路径
+
+### 第二/三层：工作流测试
+
+- **第二层**（只改了 SKILL.md 里个别工作流）：生成测试提示词写到文件，并用 Codex 跑涉及的工作流
+- **第三层**（多工作流改动 / 版本号升级）：生成全量回归提示词，在 Codex 跑完整流程（init → ingest → lint → digest → graph）
+
+素材复用 `~/Desktop/llm-wiki-cowork-test/raw-input/` 里的 3 篇文章，不用每次重新找。
+
+跑完后生成 `test-report.md`，确认无阻塞问题后才执行 `git push`。
+
+## 推送前文档更新规则
+
+每次 commit 含功能改动（feat/fix）后、`git push` 前，**必须**主动检查并更新以下文档，不需要用户提醒：
+
+1. **CHANGELOG.md**：在顶部加新版本条目（日期、新增/改进/修复分类）
+2. **README.md 功能列表**：新增功能或行为变化时，在"功能"章节补一条
+3. **版本号**：如果改动涉及新功能，在 CHANGELOG 条目里用新版本号（按 v当前+1 递增）
+
+跳过条件：纯文档/排版/注释改动不需要更新。
+
+## Skill routing
+
+当用户请求匹配可用 skill 时，优先使用对应 skill 的工作流。不要直接临时发挥；先打开对应 `SKILL.md`，按里面的流程做。
+
+关键路由规则：
+
+- Product ideas, "is this worth building", brainstorming → 使用 office-hours
+- Bugs, errors, "why is this broken", 500 errors → 使用 investigate
+- Ship, deploy, push, create PR → 使用 ship
+- QA, test the site, find bugs → 使用 qa
+- Code review, check my diff → 使用 review
+- Update docs after shipping → 使用 document-release
+- Weekly retro → 使用 retro
+- Design system, brand → 使用 design-consultation
+- Visual audit, design polish → 使用 design-review
+- Architecture review → 使用 plan-eng-review
+- Save progress, checkpoint, resume → 使用 checkpoint
+- Code quality, health check → 使用 health

package/dist/skills/llm-wiki/CHANGELOG.md

@@ -0,0 +1,459 @@
+# Changelog
+
+## v3.6.6 (2026-06-15)
+
+### 新增
+
+- 工作台对话区新增 `omp` 风格动态工具状态：当前 assistant 回复只显示一个正在执行的工具条，工具切换时原地更新。
+- 历史工具调用改为折叠摘要，按文件、命令、搜索、Skill 等分组展示，并限制长历史明细数量，避免工具流水账刷屏。
+
+### 改进
+
+- 点击停止后，当前工具条会明确显示取消状态；后端停止后不再继续向该次请求写入工具事件。
+
+## v3.6.5 (2026-06-15)
+
+### 修复
+
+- 工作台图谱在社区聚焦后关闭右侧抽屉时，会保留当前社区视图，不再意外回到全图。
+- 在社区聚焦内点击节点打开右侧抽屉时，图谱会稳定当前视野，避免节点明显跳动。
+
+## v3.6.4 (2026-06-14)
+
+### 修复
+
+- 工作台图谱节点保留真实页面路径，旧图谱数据缺少页面路径时会自动重建，避免点击节点或把节点发进对话时读到不存在的页面。
+
+## v3.6.3 (2026-06-13)
+
+### 新增
+
+- 数字山水知识图谱新增搜索、社区图例、悬停预览、点击阅读、Shift 多选和离线选区事实面板。
+- 工作台右侧抽屉支持图谱阅读和图谱选区两种状态，阅读、选区和画布高亮保持同步。
+
+### 改进
+
+- 默认节点显示更轻量，密集图在紧凑标签和点状视图下也保留悬停预览。
+- 离线阅读器显示中文类型、日期和来源规则，并继续支持本地搜索、图例、导航和节点位置记忆。
+- 明暗主题和桌面、平板、手机视口完成回归验证，移动端预览不再越界。
+
+### 修复
+
+- 工作台图谱接口只接受已登记知识库，避免任意本地路径触发布局写入或重建。
+- 工作台服务默认并强制保持本机访问，页面读取也会限制在知识库 `wiki/` 目录内。
+- 新建知识库流程兼容 Codex 的 llm-wiki 安装目录。
+- 补齐 stage 4.5 浏览器回归、可访问性稳定断言和全量回归验证，减少图谱交互改动的漏测风险。
+
+## v3.6.2 (2026-04-28)
+
+### 新增
+
+- 数字山水知识图谱补齐节点视觉语法：普通节点像地图地名，重要节点像索引签条，选中节点像朱砂批注。
+- 首次打开图谱时显示推荐起点预览，不再自动替用户选中节点；点击后才进入阅读态。
+- 新增东方设计合同回归测试，覆盖节点层级、小地图方位图、学习队列书签条、阅读态和首屏预览钩子。
+
+### 改进
+
+- 推荐起点、搜索命中和选中节点在密集视图下保持可识别，避免大图谱重新变成满屏卡片。
+
+## v3.6.1 (2026-04-28)
+
+### 改进
+
+- 数字山水知识图谱支持画布拖拽、滚轮缩放、回到全图和小地图点击定位。
+- 左侧学习队列改为竖向条目，长标题不再撑破侧栏；空队列显示真实提示。
+- 右侧札记栏进入阅读态后拥有更稳定的阅读宽度，长路径、wikilink 和代码块不再造成整页横向滚动。
+
+### 修复
+
+- 阅读态切换时先稳定页面宽度再计算图谱位置，避免节点和连线在初次渲染时错位。
+
+## v3.6.0 (2026-04-28)
+
+### 新增
+
+- 知识图谱改为“东方编辑部 × 数字山水”视觉方向：山水印章、国风副标题、编辑部索引、札记式详情和本地 GitHub 入口。
+- 图谱运行时新增节点密度策略：少量节点显示小卡片，中等节点显示紧凑标签，超过 200 个节点默认压成点状表达，选中、悬停和搜索命中再展开。
+- 右侧详情新增派生摘要区，摘要来自真实正文首个有效段落；正文仍保留 markdown 渲染和站内链接跳转。
+- 新增密度回归测试，覆盖 200、201 和 501 节点下的大图构建、密度规则、标签预算和边预算。
+
+### 改进
+
+- 置信度用户可见文案中文化为“直接提取 / 推断关联 / 存在歧义”，数据层仍保留原始枚举值。
+- 相邻节点首次默认折叠，展开后列表内部可滚动，并继续按 wiki 本地状态恢复。
+- 社区水墨团块会根据当前节点密度降低透明度，避免大图被色块遮住。
+- 移动端详情改为底部抽屉，搜索后可以直接阅读摘要和知识内容。
+- 生成的图谱 HTML 移除在线字体依赖，继续使用本地脚本和离线资源。
+
+### 修复
+
+- 切换社区、聚焦或搜索后，右侧详情会自动同步到当前可见范围，不再显示旧节点。
+- `x: null`、`y: null` 不再被当作左上角坐标，节点会进入自动布局。
+- 手机和桌面上的图谱按钮、队列入口和来源操作都保持足够大的点击区域。
+
+## v3.5.1 (2026-04-25)
+
+### 修复
+
+- Windows PowerShell 5.1 中文编码乱码（issue #16）：
+  - `scripts/shared-config.sh` 自动检测 `python3` / `python` 命令（Windows 默认只有 `python.exe`）
+  - 自动导出 `PYTHONIOENCODING=utf-8`，统一 Python 子进程输出编码
+  - Python 检测增加 3.8+ 版本校验，和错误消息、README 文档对齐
+- `hook-session-start.sh` / `cache.sh` / `delete-helper.sh` 引用 `shared-config.sh`，统一使用 `$PYTHON_CMD`
+
+### 新增
+
+- `install.ps1` Windows PowerShell 安装入口：自动 `chcp 65001` + `$OutputEncoding = UTF8` + 转发 bash 安装流程
+- `install.sh` 的 `MANAGED_ITEMS` 清单加入 `install.ps1`，并新增安装后校验环节，确保清单文件都拷贝到位
+- `README.md` / `README.en.md` 新增 Windows 章节（Python 检测说明 + `install.ps1` 使用流程）
+
+## v3.5.0 (2026-04-24)
+
+### 新增
+
+- `.wiki-schema.md` 新增「别名词表」section：用户维护同义词组（如 `LLM = 大语言模型 = 大模型`），query 和 digest 搜索时自动展开
+- query 工作流搜索前先读取别名词表，展开用户查询关键词的所有同义词，再用全部关键词搜索
+- digest 工作流同步支持别名展开搜索
+- ingest 完成后如果发现新的同义词关系，主动建议用户添加到别名词表
+
+## v3.4.0 (2026-04-24)
+
+### 新增
+
+- source 模板新增 `image_paths` frontmatter 字段，追踪已下载到 `raw/assets/` 的图片路径列表
+- ingest 流程（完整 + 简化）记录图片数量和路径，用户下载图片后可手动或通过 lint 补全
+- `lint-runner.sh` 新增图片资产一致性检查：source 页面声明了 `image_paths` 但文件不存在时报告缺失
+
+## v3.3.1 (2026-04-24)
+
+### 新增
+
+- ingest 完整处理和简化处理均在保存素材后检测图片引用（`![`、`<img`、图片 URL），提醒用户下载到 `raw/assets/` 防止链接失效
+- source 模板新增 `images` frontmatter 字段，记录素材包含的图片数量
+
+## v3.3.0 (2026-04-24)
+
+### 新增
+
+- 学习驾驶舱重构为左侧五段式导航：社区分类、当前主题聚焦、学习搜索、学习队列、推荐起点
+- 新增当前主题聚焦：完整范围、核心节点、一级关联、高置信度，统一汇入可见图谱状态
+- 新增学习队列 MVP：节点收藏、学习笔记、最近条目回跳，浏览器本地按 wiki namespace 隔离持久化
+- 新增 `tests/js/graph-wash-runtime-state.test.js` 与 `tests/js/graph-wash-queue.test.js`，覆盖可见状态联动与队列状态
+- query/digest/ingest 工作流新增单页长度上限规则（2000/3000 字），超长页面只读 frontmatter + 关键段落，避免 token 浪费
+- query 搜索结果按相关性排序：文件名精确命中 > index 条目命中 > 正文关键词命中
+- Step 1 JSON 契约新增 `evidence` 字段：EXTRACTED 应附原文摘录，INFERRED 应附推理依据；校验脚本以 WARN 形式提示缺失
+- 新增 `scripts/lint-fix.sh` 低风险自动修复脚本：按 section 补齐 index.md 中未收录的页面，支持 `--dry-run`
+
+### 改进
+
+- 图谱首次打开回到全局视图，推荐起点降级为左侧底部辅助入口，不再抢占主叙事
+- 顶部搜索移入左侧学习搜索，搜索范围跟随当前社区、聚焦模式和边过滤后的可见快照
+- 洞察、图例、小地图统一归入二级信息入口，小地图与相邻节点折叠状态改为 wiki 级别隔离存储
+- 桌面端收紧三列宽度，新增 1180px 响应式阈值；窄屏左右栏改为 overlay，13 寸屏正文和画布更少互相挤压
+
+### 移除
+
+- 删除右侧抽屉旧学习三段说明和 `drawer.section_order` 旧 contract，不再保留 `dr-learning` 兼容壳
+
+## v3.2.1 (2026-04-24)
+
+### 修复
+
+- `validate-step1.sh` 加强子字段校验：entity 必须有 name/type/confidence，topic 必须有 name，connection 必须有 from/to/confidence，缺失即触发回退
+- `lint-runner.sh` 孤立页检测从仅 `entities/` 扩展到 `entities/`、`topics/`、`sources/` 三个目录
+- `lint-runner.sh` 新增反向 index 一致性检查：文件存在但 index.md 未收录（跳过 derived 页面）
+- `cache.sh` 自愈逻辑收紧：stem 匹配后还需验证 source 页面 frontmatter 的 `source_path` 是否指向当前 raw 文件，不匹配时返回 `MISS:repaired_needs_verify` 而非 `HIT(repaired)`
+
+### 测试
+
+- 更新 lint 回归金文件，新增 source fixture 覆盖孤立页和反向索引检查
+- 更新缓存回归测试 fixture，source 页面补 frontmatter 适配自愈验证逻辑
+- 更新 validate-step1 回归测试，entity JSON 补 `type` 字段适配新校验
+
+## v3.2.0 (2026-04-23)
+
+### 新增
+
+- 学习驾驶舱左侧社区导航面板：桌面端独立三列布局（导航 | 画布 | 抽屉），窄屏（<1024px）自动切换为 overlay
+- 社区榜展示前 3 个社区（按 is_primary + node_count 排序），每个社区显示名称、节点数和来源数，primary 社区带 TOP 标记
+- 点击社区切换到该社区的 community 视图，点击推荐起点进入 path 视图并自动展开抽屉
+- 左中右联动：首次打开、点击社区、点击起点、点击节点、切换模式、切到全局，六种触发动作的完整状态一致性
+- 社区切换后若当前选中节点不在新可见集内，自动关闭抽屉（drawer 漂移修复）
+- 非 top-3 社区节点点击时显示内联提示，左侧高亮不跳转
+- `graph-wash-helpers.js` 新增 `getCommunityNodeIds()` 运行时派生函数，任意社区的可见节点集合不再依赖 primary 预计算
+- 新增 `tests/fixtures/graph-interactive-multicomm/` 多社区测试 fixture（4 社区、20 节点、30 边）
+
+### 改进
+
+- `graph-wash.js` 社区视图改为通过 `activeCommunityId` 运行时派生可见节点，不再复用 `learning.views.community.node_ids`
+- 旧的 `renderLearningPanel()` 拆分为 `renderNavPanel()`（左侧导航）和 `updateInsightsTitle()`（标题同步），职责分离
+- Insights 面板不再隐藏/替换，`#insights-body` 始终可见
+- `focusNode()` 新增 `openDrawer` 参数，社区切换时可保持抽屉状态
+
+### 测试
+
+- 新增 `getCommunityNodeIds()` 3 个单元测试（正常匹配、不存在社区、空 community id）
+- 更新 HTML 回归脚本：新增 nav-panel 相关 DOM hook 断言，删除旧 learning-body 断言
+- `focusNode` 签名变更在两个回归脚本中同步更新
+
+## v3.1.0 (2026-04-23)
+
+### 新增
+
+- 知识图谱新增「学习驾驶舱」：首次打开图谱时，自动展示推荐起点驱动的学习路径，而不是默认的全局视图
+- 新增路径/社区/全局三种学习模式切换，路径模式聚焦推荐起点及其直接邻居，社区模式聚焦最大社区
+- 侧边抽屉新增学习解释区：这是什么、为什么现在看、下一步看什么，引导用户渐进探索
+- Insights 面板在学习模式下切换为学习入口，展示推荐起点和社区概览
+- 搜索、小地图、底栏均适配子图模式，只搜索/显示/统计当前可见节点
+- `graph-analysis.js` 新增 `buildLearning()` 预计算函数，构建时生成完整学习元数据（降级瀑布、社区统计、推荐起点）
+- `graph-wash-helpers.js` 新增 6 个学习辅助函数（defaultLearning、normalizeLearning、resolveInitialMode、getVisibleNodeIds、getVisibleLinks、shouldAutoOpenDrawer）
+
+### 测试
+
+- 新增 `tests/js/graph-wash-learning.test.js`，20 个单元测试覆盖全部学习辅助函数
+- 新增 `tests/graph-html-learning-cockpit.regression-1.sh`，5 个回归测试覆盖 HTML 壳、运行时钩子和既有功能兼容性
+- 更新 `tests/expected/graph-data-sample.json` 和 `graph-data-empty.json` 金文件，反映新增的 learning 字段
+
+## v3.0.7 (2026-04-22)
+
+### 修复
+
+- `graph-wash-helpers.js` 在 `Intl.Segmenter` 不可用时会把 ZWJ emoji、组合附加符和肤色修饰符并回同一段，旧运行时下的长标签截断不再拆坏家庭 emoji
+- `graph-wash-helpers.js` 现在同时导出到浏览器全局和 CommonJS，避免桌面壳或混合运行时里 `graph-wash.js` 拿不到 helper 后整页不启动
+- `build-graph-html.sh` 改为先复制全部 graph 资产，再替换最终 `knowledge-graph.html`，helper 缺失时不再把旧的可用 HTML 覆盖成坏产物
+
+### 测试
+
+- 新增 `tests/js/graph-wash-bootstrap.test.js`，覆盖 helper 缺失和 CommonJS + 浏览器双导出场景
+- `tests/js/graph-wash-helpers.test.js` 补充 `Intl.Segmenter` fallback 下的家庭 emoji 边界断言
+- `tests/graph-build-failures.regression-1.sh` 新增 helper 资产缺失时保留旧 HTML 的失败路径回归，`tests/regression.sh` 同步接入 bootstrap 单测
+
+## v3.0.6 (2026-04-22)
+
+### 新增
+
+- 新增 `templates/graph-styles/wash/graph-wash-helpers.js`，把长标签截断、宽度估算和安全存储封装为可复用 helper，供浏览器运行时和 Node 单测共用
+- 新增 `tests/js/graph-wash-helpers.test.js`，用 `node:test` 覆盖 grapheme 分段、宽度计算、标签截断、卡片尺寸和安全存储边界行为
+
+### 改进
+
+- `graph-wash.js` 改为从共享 helpers 读取 `truncateLabel`、`cardDims` 和 `createSafeStorage`，减少前端运行时里的重复逻辑
+- `graph-wash.js` 在 `graph-wash-helpers.js` 缺失或加载失败时会显式报错并停止初始化，不再因为顶层解构直接抛出难定位的异常
+- `build-graph-html.sh` 与 wash footer 现在会复制并先加载 `graph-wash-helpers.js`，长标签回归不再依赖 `vm` 从浏览器脚本抽函数
+- `tests/regression.sh` 接入 `graph-html-styles`、`graph-html-search`、`graph-html-mobile` 三个遗漏回归，避免全量回归漏跑图谱场景
+
+### 测试
+
+- 新增 `graph-wash-helpers` JS 单测，并把它集成进 `tests/regression.sh`
+- `graph-wash-helpers` 单测补充 `Intl.Segmenter` 不可用时的 fallback 分支和浏览器全局导出分支覆盖
+- 更新 `graph-html-long-label.regression-1.sh` 与 `graph-html-styles.regression-1.sh`，验证 helpers 产物复制、脚本加载顺序和长标签行为
+
+## v3.0.5 (2026-04-22)
+
+### 新增
+
+- 新增 `scripts/lib/source-signal-eligibility.js` 共享模块，统一 6 种页面类型的来源信号（source-signal）资格判定逻辑
+- 新增 `scripts/source-signal-coverage.js` 批量扫描脚本，输出 JSON 格式的覆盖情况汇总
+- lint 报告新增"检查 4：source-signal 覆盖情况"，按原因分组列出未参与页面
+- status 工作流新增覆盖数据汇报步骤，报告模板增加"图谱来源信号覆盖"摘要
+
+### 改进
+
+- 从 `graph-analysis.js` 提取约 115 行重复的 frontmatter 解析和来源解析函数到共享模块，graph 回归测试全部通过
+- README 先决条件更新：来源信号覆盖检查需要 `node`
+
+### 测试
+
+- 新增 31 个 JS 单元/集成测试（`source-signal-eligibility.test.js` 25 个 + `source-signal-coverage.test.js` 6 个），覆盖全部 5 种资格原因
+- 新增 `tests/lint-output.regression-1.sh` lint 输出 golden diff 回归
+- `tests/regression.sh` 集成 JS 单测和 lint 回归
+
+## v3.0.4 (2026-04-22)
+
+### 新增
+
+- 新增根 `HERMES.md` 与 `platforms/hermes/README.md`，让 Hermes 进入仓库时能走自己的安装入口，不再误吃 Codex 专属提示
+- `install.sh` 与 `scripts/runtime-context.sh` 新增 `hermes` 平台支持，默认技能目录为 `~/.hermes/skills/llm-wiki`
+- `README.md`、`README.en.md`、`SKILL.md` 补齐 Hermes 平台说明与 metadata，保持共享核心不分叉
+
+### 测试
+
+- `tests/regression.sh` 新增 Hermes 安装与入口文档断言，继续兜住四平台安装矩阵
+- README 结构断言扩展到 Hermes 安装、升级与根 `HERMES.md` 提示
+
+### 致谢
+
+- 感谢 [Zihan Zhao](https://github.com/ZZXX-bit) 贡献 Hermes 平台支持
+
+## v3.0.3 (2026-04-21)
+
+### 新增
+
+- 图谱 2.0 第一段：`build-graph-data.sh` 现在会生成边权重、来源信号可用性、Louvain 社区和规则 insights，输出稳定写入 `wiki/graph-data.json`
+- wash 图谱前端新增强弱边视觉分层、邻居强度指示和 Insights 面板，离线 HTML 可以直接查看惊人连接 / 知识缺口 / 桥节点
+- 新增 `scripts/graph-analysis.js` 和 3 组 graph 回归，覆盖 helper 算法、Node/helper 失败路径、Insights 面板接线
+
+### 改进
+
+- `templates/source-template.md` 补齐 `sources: []` 契约，图谱权重可用来源重叠信号，不再靠旧的平面连线
+- 图谱搜索改为预计算索引，避免每次输入都重新扫描全文内容
+- 图谱基础构建运行时要求现在显式为 `jq` + `node`
+
+## v3.0.2 (2026-04-21)
+
+### 修复
+
+- 图谱页在缺少小地图或相邻节点区 DOM 片段时不再因空引用中断，折叠状态初始化更稳
+- `cardDims()` 与 `truncateLabel()` 统一使用字素簇宽度计算，长标签和复杂 emoji 的截断结果保持一致
+- `tests/regression.sh` 的升级回归改为在移除 `.git` 的仓库副本里执行，避免安装测试被当前工作区状态干扰
+
+### 测试
+
+- 长标签、小地图、相邻节点折叠回归升级为 Node 运行时断言，覆盖 guard、状态切换和持久化行为
+- 安装总回归补齐显式目标目录升级与 README 结构断言，继续兜住升级路径
+
+## v3.0.1 (2026-04-21)
+
+### 改进
+
+- 图谱页品牌区改成直接链接 GitHub，宽屏工具栏按钮改为“图标 + 文字”，常用操作更容易发现
+- 长标签节点改为安全截断并保留完整标题提示，避免卡片文字溢出
+- 小地图和相邻节点区支持独立折叠，并记住上次展开状态
+- 详情抽屉改成主内容优先、相邻节点辅区受限高度，长内容浏览更稳定
+- 图谱样式补齐 `prefers-reduced-motion`、`aria-expanded`、键盘 Enter / Space 触发等无障碍细节
+
+### 测试
+
+- 新增 graph UX shell 回归：品牌链接、长标签截断、小地图折叠、工具栏标签、邻居区折叠、a11y
+- `tests/regression.sh` 现在会串行执行上述图谱 UX 回归，避免总回归漏跑
+
+## v3.0.0 (2026-04-20)
+
+### 新增
+
+- **水彩卡片风交互式知识图谱**：`build-graph-html.sh` 生成 `wiki/knowledge-graph.html`，使用 d3 + rough.js 水彩卡片风格，离线双击即可查看（搜索、过滤、社区聚类、节点详情抽屉）
+- `templates/graph-styles/wash/`：wash 水彩卡片图谱模板（header / footer / graph-wash.js）
+- `deps/d3.min.js`、`deps/rough.min.js`：本地 vendor，不依赖 CDN
+- `tests/graph-html-styles.regression-1.sh`：回归测试覆盖本地 vendor、模板注入和离线资产复制
+
+### 移除
+
+- classic（vis-network）和 paper（手绘笔记本）图谱风格及相关模板、vendor 资产
+- `--style` 参数和二参数兼容调用方式
+
+### 改进
+
+- `scripts/build-graph-html.sh`：简化为 wash-only 单风格输出，接口更简洁
+- 图谱运行时：读取内嵌 `graph-data` JSON，并对 markdown 详情面板做 DOMPurify 清洗
+
+## v2.6.0 (2026-04-17)
+
+### 新增
+
+- **交互式知识图谱 HTML**：双击 `wiki/knowledge-graph.html` 即可在浏览器中查看交互式知识图谱（搜索、过滤、社区聚类、节点详情抽屉、键盘快捷键）
+- `scripts/build-graph-data.sh`：扫描 wiki 目录生成 `graph-data.json`（节点/边/社区聚类/U2 top-30 算法/2MB 降级保护）
+- `scripts/build-graph-html.sh`：拼接 header + graph-data.json + footer 生成自包含 HTML，复制 vendor 资产
+- `templates/graph-template-header.html`：品牌栏 + 工具条 + 三栏骨架 + CSS 变量 + ARIA
+- `templates/graph-template-footer.html`：vis.js 初始化 + 11 个交互状态 + 键盘快捷键
+- `templates/vis-network.min.js` + `marked.min.js` + `purify.min.js`：vendor 三件套及对应许可证
+- `SKILL.md` 工作流 8 新增 Step 2b（生成 graph-data.json）和 Step 2c（生成 HTML）
+- 14 个回归测试覆盖 build-graph-data.sh 和 build-graph-html.sh 的 13 条代码路径
+
+### 修复
+
+- `build-graph-data.sh`：bash 3.2 全角字符后 `$OUTPUT` 变量名误解析，改用 `${OUTPUT}` 显式定界
+
+## v2.5.0 (2026-04-16)
+
+### 新增
+
+- `scripts/create-source-page.sh`：source 页面写入和缓存更新绑定为原子操作，写入后自动更新 `.wiki-cache.json`，失败时自动回滚
+- `scripts/cache.sh check`：MISS 原因细分（`no_entry` / `hash_changed` / `no_source`），AI 可根据原因给出不同提示
+- `scripts/cache.sh check`：自愈缓存检查，无 cache entry 但 source 页面存在时通过 filename stem 精确匹配自动修复（返回 `HIT(repaired)`）
+
+### 改进
+
+- `SKILL.md` ingest 工作流：source 页面写入改用 `create-source-page.sh`，Step 12 不再单独调用 `cache.sh update`
+
+## v2.4.0 (2026-04-15)
+
+### 新增
+
+- `platforms/claude/companions/llm-wiki-upgrade/SKILL.md`：Claude 安装后随附 `/llm-wiki-upgrade`，以后可以直接从命令入口更新 llm-wiki
+
+### 改进
+
+- `install.sh`：恢复 Claude 专属伴生命令安装与升级同步，GitHub 地址安装和 `/llm-wiki-upgrade` 两条路线现在共享同一套更新边界
+- `README.md`、`CLAUDE.md`、`platforms/claude/CLAUDE.md`：补充 `/llm-wiki-upgrade` 的使用说明，明确默认只更新核心主线
+
+## v2.3.0 (2026-04-15)
+
+### 改进
+
+- `install.sh`：默认安装和默认升级只准备知识库核心主线；网页、X/Twitter、微信公众号、YouTube、知乎提取改为显式追加 `--with-optional-adapters`
+- `README.md`、`AGENTS.md`、`CLAUDE.md`、平台入口：统一补充“核心默认可用、URL 自动提取按需开启”的说明，并澄清 `--target-dir` 需要传最终的 `llm-wiki` 目录
+
+### 修复
+
+- `install.sh`：修复 `--upgrade --target-dir <...>/llm-wiki` 被默认平台目录覆盖的问题，自定义技能目录现在会升级到正确位置
+- `install.sh`：目标目录不存在时，升级命令现在明确失败，不再误报“升级完成”
+- `scripts/adapter-state.sh` + `scripts/runtime-context.sh`：统一源码目录、已安装目录和升级目标目录的判断，避免状态检查在不同运行位置下漂移
+- `tests/regression.sh`、`tests/adapter-state.sh`：回归矩阵改成保护“核心默认可用、可选提取显式开启”的新边界
+
+## v2.2.0 (2026-04-14)
+
+### 新增
+
+- `scripts/lint-runner.sh`：lint 机械检查脚本（孤立页面 / 断链 / index 一致性），独立于 AI 判断
+- `tests/fixtures/lint-sample-wiki/`：lint 脚本回归测试夹具（含 `C++` 特殊字符、别名链接 `[[X|显示]]`、孤立页面等边界情况）
+- `tests/expected/lint-output.txt`：lint 脚本预期输出
+- SKILL.md digest 多格式模板：深度报告、对比表、时间线三种输出格式及文件命名约定
+- SKILL.md digest 路由表：新增"对比/时间线"触发词
+- `templates/schema-template.md` 关系类型词汇表：可选的图谱关系标注词汇（实现/依赖/对比/矛盾/衍生）
+- SKILL.md ingest 隐私自查：首次进入 ingest 必须确认的 y/n 隐私检查流程
+
+### 改进
+
+- SKILL.md lint 工作流：拆分为"Step 0 脚本机械检查 + AI 层面判断"两阶段
+- SKILL.md graph 工作流：明确 AI 默认只画无标注箭头，关系词汇表仅供手动美化
+- CLAUDE.md：新增"推送前测试规则"（三层验证策略），删除与 SKILL.md 重复的使用顺序列表
+
+### 修复
+
+- `lint-runner.sh`：`INDEX_FILE` 路径从 `$WIKI_DIR/index.md` 改为 `$WIKI_ROOT/index.md`（与 schema 约定的目录结构一致）
+- 测试夹具 `lint-sample-wiki`：`index.md` 从 `wiki/` 移到知识库根目录，符合 schema 约定
+
+## v2.1.0 (2026-04-13)
+
+### 新增
+
+- `scripts/validate-step1.sh`：ingest Step 1 JSON 格式验证脚本，检查必需字段和置信度值合法性
+- `templates/synthesis-template.md`：crystallize 结晶化页面模板
+- SKILL.md 置信度赋值规则：明确 EXTRACTED/INFERRED/AMBIGUOUS/UNVERIFIED 的判定标准
+- SKILL.md Step 1 验证流程：Step 1 完成后调用 validate-step1.sh，失败自动回退
+- SKILL.md 工作流 10 crystallize：对话内容沉淀为 wiki/synthesis/sessions/ 页面
+- SKILL.md 路由表：新增 crystallize 关键词路由
+
+### 改进
+
+- `scripts/init-wiki.sh`：创建 `wiki/synthesis/sessions/` 子目录和 `.gitignore`（排除 `.wiki-tmp/`）
+- `tests/regression.sh`：新增 9 个测试覆盖 validate-step1.sh 行为和 SKILL.md 内容锁定
+
+## v2.0.0 (2026-04-11)
+
+### 新增
+
+- `purpose.md` 研究方向模板：初始化后直接生成，给后续整理提供明确方向
+- `.wiki-cache.json` 本地缓存：为重复素材跳过提供基础设施
+- `query` 结果持久化模板：支持把综合回答写回 `wiki/queries/`
+- delete 工作流说明和辅助脚本：支持级联删除素材并扫描引用
+- Claude Code `SessionStart hook` 支持：可在会话开始时注入 wiki 上下文提示
+
+### 改进
+
+- `SKILL.md`：重构 `ingest` 为两步流程，增加缓存检查、置信度标注和降级说明
+- `SKILL.md`：`batch-ingest` 增加无变化跳过统计，`status` 增加 `purpose.md` 状态展示
+- `SKILL.md`：`query` 增加重复检测、`derived: true` 标记和自引用防护
+- `SKILL.md`：`lint` 增加置信度报告和 EXTRACTED 抽查说明
+- `wiki-compat.sh`：兼容旧知识库时同时报告 `purpose.md` 和 `.wiki-cache.json` 状态
+- `install.sh`：支持注册和移除 Claude Code 的 `SessionStart hook`