kb-visualize

kb-visualize — 将知识包视作图谱

将一个 知识包 渲染为概念的交互式力导向图，让人可以看到它的结构——枢纽、集群、孤立节点，以及概念之间的连接方式。你根据确定性的图模型编写视图，因此它可以根据请求调整（整个知识包的地图，或围绕某个概念的子图），而不是固定模板。

1. 提取图模型

对目标知识包运行随附的提取器（默认是 knowledge/）。这是一个零依赖的 Node 脚本（node >=18）；<skill-dir> 是此技能所在的目录——在 Claude Code 中为 ${CLAUDE_SKILL_DIR}，或者使用宿主为该技能提供的路径：

node "<skill-dir>/scripts/graph.mjs" <bundle-dir>

它会输出 JSON：nodes（包含 id、显示元数据、status、generated、verified、派生的 trust_tier、stale_after、派生的 is_stale、结构化的 sources、证明元数据、body、links 和 cited_by）、不同的 types，以及 edges。反向链接（cited_by）和边已根据概念正文中的交叉链接计算得出。如果用户将请求限定在某个概念／区域，请将模型筛选为该节点及其邻居。

渲染器必须使用本次提取器调用生成的模型。不要复用先前运行缓存的图 JSON，也不要使用硬编码到其他缓存文件名的生成器。如果宿主需要临时文件，请覆盖一个明确指定的模型路径，将同一路径传给渲染器，并在验证后删除该文件。

**完成标准：**已获取图模型，并且（如果限定了范围）已将其筛选为所请求的子图。

2. 根据宿主能力选择输出形式

• 宿主可渲染交互式 UI（例如 Claude Desktop、Codex Desktop、MCP-Apps 宿主）：将图渲染为原生 UI，使其可以在对话中实时交互。
• 宿主仅支持文本／制品（例如 Claude Code、终端）：在知识包旁边或作为制品写入一个自包含 HTML 文件（单文件、无后端、仅使用 CDN 库），并告知用户文件路径。

如果不确定宿主是否可以渲染 UI，默认使用 HTML 文件——它在任何环境中都能运行。

**完成标准：**输出形式符合宿主的能力。

3. 渲染视图

无论采用哪种形式，视图都必须显示（与符合要求的 OKF 查看器保持一致）：

• 力导向图：每个概念对应一个节点，节点按 type 着色；每个交叉链接对应一条有向边。如果用户可以切换布局（例如 cose / concentric / breadth-first / grid），则更佳。
• 所选节点的详情面板：显示其 frontmatter（description、作为链接的 resource、tags、生命周期／新鲜度、来源信息、信任等级，以及存在时的 Attested Computation 合约）和渲染后的 Markdown body。内部概念链接应重新指向视图内的导航（选择该节点），而不是跳转到文件路径。
• 每个节点的 **“引用来源”**列表，取自 cited_by（反向链接图）。
• 搜索框（匹配标题、id、标签）和类型筛选器。

对于 HTML 形式，经过验证的技术组合是 Cytoscape.js（图）+ marked（Markdown），从 CDN 加载，并将图模型作为 JSON 字面量内嵌，使文件自包含且数据不会离开页面。第 1 步中的模型已包含所有节点数据——不要重新读取知识包。

对照最新模型验证输出：节点数和边数必须一致，并且本次运行中新增或被替代的每个概念都必须按 ID 显示。仅仅生成了一个渲染文件并不足够。

**完成标准：**渲染视图显示了按类型着色的图、可用的详情面板及视图内链接导航、反向链接、搜索和类型筛选器；其节点数／边数以及变更概念 ID 均与最新提取的模型一致。

4. 交付

交付结果：对于 UI，交付实时视图；对于 HTML，交付文件路径（并说明可以将其提交到 bundle 旁边、作为工件共享，或托管在任何静态文件服务器上）。这是只读使用方——它不会修改 bundle，因此不会留下日志条目。

**完成标准：**用户已获得视图或其路径。