Back to Details

kb-visualize

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

kb-visualize — see the bundle as a graph

kb-visualize——将知识包可视化为图谱

Render a bundle as an interactive force-directed graph of its concepts, so a human can see its shape — hubs, clusters, orphans, and how concepts connect. You author the view from a deterministic graph model, so it can adapt to the request (a whole-bundle map, or a subgraph around one concept); it is not a fixed template.
将bundle渲染为其概念的交互式力导向图谱，以便人们可以直观看到它的结构——核心节点、集群、孤立节点，以及概念之间的关联方式。你可以基于确定性图谱模型定制视图，使其适配不同需求（完整知识包图谱，或围绕单个概念的子图谱）；它并非固定模板。

1. Extract the graph model

1. 提取图谱模型

Run the bundled extractor against the target bundle (default 
knowledge/
). It is a zero-dependency Node script (
node >=18
); 
<skill-dir>
is this skill's directory — 
${CLAUDE_SKILL_DIR}
under Claude Code, or whatever path your host exposes for the skill:
node "<skill-dir>/scripts/graph.mjs" <bundle-dir>
It prints JSON: 
nodes
(including 
id
, display metadata, 
status
, 
generated
, 
verified
, derived 
trust_tier
, 
stale_after
, derived 
is_stale
, structured 
sources
, attestation metadata, 
body
, 
links
, and 
cited_by
), the distinct 
types
, and 
edges
. Backlinks (
cited_by
) and edges are already computed from the cross-links in concept bodies. If the user scoped the request to one concept/area, filter the model to that node plus its neighbors.
The renderer MUST consume the model produced by this extractor invocation. Do not reuse a previous run's cached graph JSON or a generator hard-coded to another cache filename. If the host requires scratch files, overwrite one explicit model path, pass that same path to the renderer, and remove it after verification.
Completion criterion: you have the graph model, and (if scoped) filtered it to the requested subgraph.
针对目标知识包（默认路径为
knowledge/
）运行内置的提取器。这是一个零依赖的Node脚本（要求
node >=18
）；
<skill-dir>
是本skill的目录——在Claude Code环境下为
${CLAUDE_SKILL_DIR}
，或宿主暴露的该skill的任意路径：
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. Choose the output form by host capability

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

  • Host renders interactive UI (e.g. Claude Desktop, Codex Desktop, an MCP-Apps host): render the graph as native UI so it's live in the conversation.
  • Host is text/artifact only (e.g. Claude Code, a terminal): write a self-contained HTML file (single file, no backend, CDN libs only) next to the bundle or as an artifact, and give the user the path.
If unsure whether the host renders UI, default to the HTML file — it works everywhere.
Completion criterion: the output form matches the host's capability.
  • 宿主支持渲染交互式UI（如Claude Desktop、Codex Desktop、MCP-Apps宿主）：将图谱渲染为原生UI，使其在对话中实时展示。
  • 宿主仅支持文本/文件输出（如Claude Code、终端）：在知识包旁或作为文件生成独立HTML文件（单文件，无后端依赖，仅使用CDN库），并告知用户文件路径。
若不确定宿主是否支持UI渲染，默认选择HTML文件形式——它可在所有环境中运行。
完成标准： 输出形式与宿主能力匹配。

3. Render the view

3. 渲染视图

Whichever form, the view must show (mirroring a conformant OKF viewer):
  • A force-directed graph: one node per concept, colored by 
    type
    , directed edges from each cross-link. A layout the user can switch (e.g. cose / concentric / breadth-first / grid) is a plus.
  • A detail panel for the selected node: its frontmatter (
    description
    , 
    resource
    as a link, 
    tags
    , lifecycle/freshness, provenance, trust tier, and Attested Computation contract when present) and its rendered markdown 
    body
    , with internal concept links rewired to navigate within the view (select that node) rather than following a file path.
  • A "Cited by" list per node, from 
    cited_by
    (the reverse link graph).
  • A search box (matches title, id, tags) and a type filter.
For the HTML form, a proven stack is Cytoscape.js (graph) + marked (markdown) from a CDN, with the graph model inlined as a JSON literal so the file is self-contained and nothing leaves the page. All node data is already in the model from step 1 — do not re-read the bundle.
Verify the output against the fresh model: node and edge counts match, and every concept added or superseded in the current run appears by ID. A rendered file that merely exists is not sufficient.
Completion criterion: the rendered view shows the graph (colored by type), a working detail panel with in-view link navigation, backlinks, search, and type filter; its node/edge counts and changed concept IDs match the freshly extracted model.
无论采用哪种形式，视图必须展示（符合标准OKF查看器的特性）：
  • 力导向图谱：每个概念对应一个节点，按
    type
    着色    ，每条交叉链接对应一条有向边。若支持用户切换布局（如cose/同心圆/广度优先/网格布局）则更佳。
  • 详情面板：选中节点的前置元数据（
    description
    、作为链接的
    resource
    、
    tags
    、生命周期/新鲜度、来源、信任等级，以及存在时的Attested Computation合约）和渲染后的markdown
    body
    ，内部概念链接需重定向为在视图内导航（选中对应节点）而非跳转至文件路径。
  • 每个节点的“被引用”列表：来自
    cited_by
    （反向链接图谱）。
  • 搜索框（匹配标题、id、标签）和类型过滤器。
对于HTML形式，成熟的技术栈是使用CDN提供的Cytoscape.js（图谱）+ marked（markdown），将图谱模型内联为JSON字面量，确保文件独立且所有数据无需离开页面即可加载。所有节点数据已在步骤1的模型中获取——无需重新读取知识包。
根据最新生成的模型验证输出：节点和边的数量匹配，当前运行中新增或替换的每个概念均按ID显示。仅生成渲染文件并不足够。
完成标准： 渲染视图展示了按类型着色的图谱、可正常工作的详情面板（支持视图内链接导航）、反向链接、搜索和类型过滤器；其节点/边数量及变更的概念ID与最新提取的模型一致。

4. Deliver

4. 交付结果

Hand over the result: for UI, the live view; for HTML, the file path (and note it can be committed next to the bundle, shared as an artifact, or hosted on any static file server). This is a read-only consumer — it never modifies the bundle, so no log entry.
Completion criterion: the user has the view or its path.
交付结果：若为UI形式，提供实时视图；若为HTML形式，提供文件路径（并说明可将其提交至知识包旁、作为文件共享或部署在任何静态文件服务器上）。这是一个只读工具——它永远不会修改知识包，因此无需记录日志。
完成标准： 用户已获取视图或其文件路径。