# 共享 LLM Wiki 接入规格

目标：将 `nashsu/llm_wiki@0.6.13`（commit `e08cfce65aad8b76b13546a081c1a8d4422b70c3`）的共享程序接入认知记忆。主图显示有证据的概念／实体及语义关系，点击后在同屏右栏阅读文章和原文。只安装一份公共程序；员工和团队仅持有自己的资料、快照和索引。

## 接入范围与边界

- 单份 GPL-3.0 上游核心及改造桥接程序放包级 `third_party/llm-wiki/`，单独构建 Node 引擎和沙箱网页。主插件通过 JSON 消息交互，不把上游代码打进现有宿主、原生组件或主插件 UI bundle。
- 复用上游 Louvain 社区计算与分析提示，保留改造后的圆点交互和同屏文章阅读。派生 Markdown 保留 frontmatter 和 Wiki 阅读链接；主图不使用页面链接、共用来源或上游四信号关联评分生成连线。保留现有来源行引用、候选状态、版本校验与原子发布，不运行上游 Tauri 桌面、外部模型账号、自动更新或任意文件操作。
- 双阶段编纂共用 240 秒总预算及同一取消信号；单阶段兼容路径仍为 120 秒。显式 `timeoutMs` 覆盖整个流程的总预算，超时保留上一版知识，不降低已选模型的推理配置。
- 编纂按[严格来源增量规则](incremental-knowledge.md)发送新增／更新全文和必要未变来源的精确行片段，不发送整个旧库。无差异或可本地完成的撤销为零模型调用；图谱计算和阅读不调用模型。模型／规则变更不会被伪装成来源变更并自动全重编。
- 一次插件加载只创建一套共享 Wiki runtime，按需启动至多一个受管子进程，卸载时终止。所有请求包含完整知识空间身份；上游读文件接口仅看本次授权的虚拟页面，不开放本机文件系统。
- 阅读页面包括实体、概念、来源、概览和 B 综合文章；`pages` 保留完整索引及阅读链接，不修改 A 原件或历史 B/C。`graph.kind` 为 `semantic`，`nodes` 只含 `concept/entity`，实体类型只能来自模型明确分类；旧概念默认保持概念。
- `edges` 只来自 `conceptGraph.relations`，按无序端点对合并绘制；`edge.relations` 完整保留各条有向谓词、`explicit/inferred`、文章与精确证据。`weight` 等于该对关系条数，`linkCount` 等于节点参与的原始语义关系数，Louvain 只计算此语义图。没有关系的概念保持孤立，不按共现补线。
- 主图统计显示概念数、实体数和原始语义关系数；来源、文章、概览不作为主图节点或图例。点击概念可读完整 B 文章并回查精确 A；顶部不设“文章”入口；旧快照无 `conceptGraph` 但已有 B 文章时自动打开只读目录，保留文章及概览阅读。
- 默认使用同一画布的同心圆总览，全部概念／实体沿圆环规整排列，真实关联较多的节点位于内圈，不绘制连通组包络或重复标题。没有已记录关系的概念仍保留，两个独立主题之间不会为凑成整网而补线；位置只影响显示，不改变度数、社区或统计。
- 选择概念时突出它的一跳邻居和关系，其他概念保持在总览中并淡化；沿该概念打开完整 B 文章或精确 A 来源时保留焦点。搜索回车定位匹配概念并打开详情；清空搜索、清除选择或切换知识空间时解除焦点。适配图谱返回全图视野。
- 每个知识空间仅保存派生 Wiki 数据和版本；共享引擎、依赖、提示、网页均不复制进去。模板安装的资料快照属于原有数据隔离语义。
- 沙箱网页只接收父界面已获授权的 JSON，不持有凭据、任意本机路径或写接口；所有 Markdown 按不可信内容处理。切换员工、团队、版本时清理旧选择和阅读状态。

## 接口与文件

- `src/knowledge/wiki-types.ts`：数据协议；`src/knowledge/wiki-runtime.ts`：单进程、队列、取消和卸载；知识库已有 API 增加只读 Wiki 数据入口。
- `third_party/llm-wiki/`：固定版本上游源码、GPL 许可、来源哈希、改造记录、只读虚拟文件系统、引擎与网页桥接。
- `scripts/build-llm-wiki.mjs`：独立构建，产物在 `lib/llm-wiki/`，随 npm 包交付对应源码和许可。
- 既有 `KnowledgeLibrary` 保留上方四类及资料管理；主体嵌入共享沙箱网页，默认“知识分组”着色，可切换“节点类别”区分概念／实体，搜索和缩放保持紧凑；切换知识空间恢复默认分组着色。

使用现有 TypeScript 风格，例如 `build(request: WikiBuildRequest, signal?: AbortSignal): Promise<WikiLibraryView>`；边界验证输入和第三方结果，内部使用类型契约。

## 实施与验证顺序

1. 锁定上游来源，保留许可，建立共享核心、受限虚拟文件系统和 JSON 边界。
2. 接入单例生命周期、Wiki 读 API、派生数据，以及使用官方 `ctx.llm.stream` 的两步编纂；不复制模型密钥。
3. 接入圆点图谱及同屏文章阅读，保持四类布局和专业资料管理。
4. 单元/集成验证：至少两个员工和一个团队复用同一引擎，数据不串库；恶意路径、Markdown、跨空间响应被拒绝；来源与旧快照完整；关闭后无子进程残留。
5. 运行 `npm run build`、`npm test`、`node tests/ui/employee-settings.e2e.mjs`，在官方独立临时 profile 验证图谱、阅读、深浅色、窄屏和卸载清理，核对宿主未变。实际本地页面截图与在线编纂另行记录。

## 验收条件

- 三个知识空间引用同一套包级代码和至多一个引擎进程，空间目录内没有引擎、node_modules、上游源码副本。
- 主图只有语义概念／实体和带证据的关系，默认颜色区分由语义关系聚合的知识分组，可切换节点类别；点击后图谱和正文同屏，旧无图快照自动展示已有文章的只读目录，不造点、不补边。
- 多个互不相连的概念组同时在一张圆形总览中可见，布局不计入节点和关系。选择概念、阅读文章与原始证据时一跳焦点保留；右侧统一展示真实关系与依据，画布不再显示关系浮框。搜索能定位节点，清除搜索与换库能解除旧焦点。
- 阅读页数量不决定语义节点和关系数；新增 A/B/C 页面不改变语义度数和社区。同端点多谓词完整保留方向；孤立概念不因共享文章或来源而相连。
- 关闭插件停止引擎、监听与待处理工作，普通卸载保留资料，完全清理沿用插件专属知识根的归属检查。
- 记录实际复用模块、上游版本、修改、许可及限制，不声称接入了全部上游桌面、Agent、研究或多模态能力。

新归档仍须绑定版本和 SHA-256，执行 ADR-001 的完整生命周期验收，不能用开发页面演示替代。

## 0.22.0 网络与逐层关联探索

所有概念和实体使用一次完整语义图布局，取消矩形分组包络与重复标题，保留按知识分组或节点类别着色。真实连通分量只保留为元数据，不再按分组盒单独缩放排布；没有关系的节点仍显示，不新增文章节点或虚构连接。

点击节点保留一跳聚焦，右侧显示概念说明、关联正文入口与证据。首次“展开关联”把起点与其可见真实邻居组成探索集合并适配画布；继续点击沿集合中的已有关系向外扩一层。扩展过程只在内存中执行，不请求模型、重建知识或写入存储。无新邻居时禁用按钮；孤立节点显示“暂无关联”。集合保留真实关系的全部方向、谓词、依据与精确引用。

探索绑定知识空间、快照版本和起点，切换这些内容时重置。关联文章、原始资料阅读、颜色模式和语言切换保留上下文；搜索与类型筛选退出当前探索，且扩展不得穿过被隐藏的桥接节点。“返回全图”关闭阅读/焦点、清除筛选并恢复相机。Sigma与SVG备用渲染共用可见集合和真实关系，扩展只移动相机，保留拖动后坐标，不重建拓扑。

## 0.23.0 圆形布局与统一关系详情

默认布局改为确定性同心圆，圆环均匀安排节点，并按真实连接度分配内外层。图谱与阅读器宽度变化时只重新适配相机，不能覆盖用户拖动的坐标。选择、展开、搜索、着色与中英切换继续沿用原有语义与上下文规则；没有生成新的分类节点或关系。

画布左上角的关系浮框移除，右侧“语义关系”显示完整的源概念、谓词和目标概念，每条折叠项可查原文明确／模型推断、关联知识正文和精确来源。概念定义优先显示，关系列表位于定义后、相关文章前；阅读相关文章或来源时整体折叠并保留图谱起点的关系上下文，选择一条边时仍阅读该边的全部方向与证据。不增加新的写入接口、模型请求、宿主扩展点或共享程序副本。