--- description: 生成并更新可视化产物 —— Obsidian 图谱配置与 Canvas 知识地图。交互式网页图谱视图位于 SPA 的 app/modules/graph.js（由 tools/serve.py 提供服务）。 argument-hint: [--obsidian] [--canvas] [--focus ] [--depth N] [--types ] [--edge-types ] [--all] --- # /visualize > 为 OmegaWiki 知识图谱生成可视化产物。 > 产出 Obsidian 图谱配置（按实体类型分色组）以及带类型标签边的精选 Canvas 视图。 > 交互式网页探索请使用 SPA 的 Graph 视图（先跑 `tools/serve.py`，然后访问 `#/graph`）。 ## Inputs - `--obsidian`（可选）：生成或更新 `.obsidian/graph.json`，按实体类型分色组 - `--canvas`（可选）：基于图谱数据生成 Obsidian Canvas（`.canvas`），边带类型标签 - `--focus `（可选）：把 Canvas 聚焦到某个具体节点（例如 `methods/my-method`） - `--depth N`（可选）：聚焦 Canvas 的 BFS 深度（默认：2） - `--types `（可选）：把节点过滤到这些 page type，逗号分隔（例如 `papers,concepts`） - `--edge-types `（可选）：把边过滤到这些语义类型，逗号分隔（例如 `builds_on,surveys`） - `--all`（可选，没传任何 flag 时即默认）：生成全部可视化产物 ## Outputs - `wiki/.obsidian/graph.json` —— Obsidian 图谱颜色配置（按实体类型分色组） - `wiki/.obsidian/app.json` —— Obsidian 应用设置（仅当不存在时才创建） - `wiki/canvases/knowledge-map.canvas` —— 完整知识地图 Canvas，边带标签 - `wiki/canvases/idea-evidence.canvas` —— 以 idea 为中心的子图 Canvas - `wiki/canvases/focus-{node-id}.canvas` —— 聚焦 Canvas（使用 `--focus` 时） - 终端输出：Obsidian 插件推荐与设置说明独立 HTML 探索器（`wiki/graph-view.html`）已停产；同样的用法由 SPA Graph 视图（`app/modules/graph.js`，由 `tools/serve.py` 提供服务）覆盖，且与前端其余部分共用同一份代码库。 ## Wiki Interaction ### Reads - `wiki/graph/edges.jsonl` —— 带类型的语义边 - `wiki/graph/citations.jsonl` —— 论文引用 - `wiki/*/` —— 全部 entity 目录的 frontmatter - `config/visualize.json` —— 颜色调色板与可视化偏好 ### Writes - `wiki/.obsidian/graph.json` —— CREATE/OVERWRITE（本地产物，已 gitignore；每次都从 `config/visualize.json` 重生成） - `wiki/.obsidian/app.json` —— 仅在不存在时 CREATE（不覆盖用户自定义；已 gitignore） - `wiki/canvases/*.canvas` —— CREATE/OVERWRITE（本地产物，已 gitignore） ## Workflow **前置条件**：确认当前工作目录是 wiki 项目根（包含 `wiki/`、`raw/`、`tools/`）。设 `WIKI_ROOT=wiki/`。 ### Step 0: 确认图谱数据存在检查 `wiki/graph/edges.jsonl` 存在且非空。若为空，提示尚无图谱数据，建议先运行 `/ingest`。 ### Step 1: 生成 Obsidian 配置（`--obsidian` 或 `--all`） ```bash python3 tools/visualize.py generate-obsidian-config wiki/ ``` 创建 `.obsidian/graph.json`，包含 9 类实体的色组，使用 `path:{entity_type}` 形式的查询。 `.obsidian/app.json` 仅在不存在时才创建。 ### Step 2: 生成 Canvas 视图（`--canvas` 或 `--all`）完整知识地图： ```bash python3 tools/visualize.py generate-canvas wiki/ ``` 聚焦 Canvas（聚焦到某个具体节点）： ```bash python3 tools/visualize.py generate-canvas wiki/ --focus --depth ``` **`--focus` BFS 逻辑**：从目标节点开始，在 `edges.jsonl` + `citations.jsonl` 上做广度优先搜索，收集 `--depth` 跳之内的全部节点和边。只渲染该邻域子图。若 `node_id` 找不到，中止并列出 5 个最相近的 slug 候选。 **Canvas 布局**：按 `page_type` 把节点分到不同列；列内按 `importance` 倒序排序（1–5，默认 3）。跟踪边界框避免重叠。 Canvas 节点 schema： ```json { "id": "", "type": "file", "file": "", "x": , "y": , "width": 200, "height": 60, "color": "" } ``` Canvas 边 schema： ```json { "id": "--", "fromNode": "", "toNode": "", "label": "" } ``` 若设置了 `--types`，丢弃不在列表里的节点，并丢弃 source 或 target 已被丢弃的边。若设置了 `--edge-types`，丢弃不在列表里的边。 ### Step 3: SPA Graph 视图（取代已停产的 generate-html 步）之前的独立 HTML 探索器已停产。如需交互式网页探索，启动 SPA 后端： ```bash python3 tools/serve.py # 然后打开 http://127.0.0.1:8765/#/graph ``` SPA Graph 视图（`app/modules/graph.js`）是真正的 ES module，包含与原单文件生成器一样的 Cytoscape + 力导向布局 + 过滤器 + BFS 搜索，并集成了双击跳转到 SPA Reader 视图的能力。`/visualize` 不再重新生成 `wiki/graph-view.html`。 ### Step 4: 打印推荐 ```bash python3 tools/visualize.py list-recommendations ``` 打印推荐的 Obsidian 插件（Graph Analysis、Dataview、Excalidraw）以及配置说明。 ### Step 5: 日志 ```bash python3 tools/research_wiki.py log wiki/ "visualize | generated: [产物列表]" ``` 标准日志格式： ```markdown ## [YYYY-MM-DD] /visualize | — nodes, edges ``` `` 在使用 `--focus` 时为 ` (focus: , depth )`，否则为空。 ## Color Palette ### 节点颜色（按 page_type） | page_type | HTML hex | Obsidian color ID | | ------------- | --------- | ----------------- | | `papers` | `#4C9BE8` | `"1"` | | `concepts` | `#F4A261` | `"2"` | | `topics` | `#2A9D8F` | `"3"` | | `people` | `#E76F51` | `"4"` | | `ideas` | `#A8DADC` | `"5"` | | `experiments` | `#9B5DE5` | `"6"` | | `methods` | `#84CC16` | `"3"` | | `Summary` | `#90BE6D` | `"4"` | | `foundations` | `#B5B5B5` | `"6"` | ### 边颜色（HTML 模式，按语义类别） | 类别 | 类型 | Hex | | ----------- | --------------------------------------------------------------------- | --------- | | 相似 | `same_problem_as`、`similar_method_to`、`complementary_to` | `#ADB5BD` | | 谱系 | `builds_on`、`extends_concept`、`derived_from`、`inspired_by` | `#4C9BE8` | | 比较 | `compares_against`、`improves_on`、`challenges`、`critiques_concept` | `#E76F51` | | 综述 | `surveys` | `#2A9D8F` | | 概念使用 | `introduces_concept`、`uses_concept` | `#F4A261` | | 证据 | `supports`、`contradicts`、`tested_by`、`invalidates` | `#9B5DE5` | | Gap | `addresses_gap` | `#F9C74F` | | Citation | `cites` | `#B5B5B5` | ## Constraints - 不要手动改 `wiki/graph/` —— 只读 - `config/visualize.json` 是用户拥有的 —— 不要覆盖 - `.obsidian/app.json` 仅在缺失时创建（尊重用户自定义） - Canvas 文件每次运行重生成（幂等覆盖） - 不依赖外部 Python 包（仅用 stdlib） - `wiki/.obsidian/` 与 `wiki/canvases/` 都是已 gitignore 的本地产物；source of truth 是 `config/visualize.json` + `wiki/graph/`。`/init` Step 6 与直接调用 `/visualize` 都会幂等地重生成它们 —— 永远不要 commit 它们。 ## Error Handling - **没有图谱数据**：提醒用户先跑 `/ingest` 建立知识库 - **`config/visualize.json` 缺失**：报错，文件应当存在于 `config/visualize.json` - **`--focus` 节点找不到**：中止并打印 `Error: node "" not found`；列出 5 个最相近的 slug 候选 - **过滤后没有节点**：中止并汇总当前过滤器与可用类型 - **Canvas 节点超过 500 个**：警告大型 Canvas 可能很慢；建议用 `--focus` 或 `--types` 缩小范围 - **entity 目录缺失**：静默跳过，只处理存在的目录 - **JSONL 行格式不正确**：静默跳过，继续处理后续行 - **`wiki/canvases/` 不存在**：写入前先创建目录 ## Dependencies ### Tools（via Bash） - `python3 tools/visualize.py generate-obsidian-config wiki/` —— Obsidian 配置 - `python3 tools/visualize.py generate-canvas wiki/ [--focus ] [--depth N]` —— Canvas 生成 - `python3 tools/visualize.py list-recommendations` —— 插件推荐 - `python3 tools/research_wiki.py log wiki/ ""` —— 追加日志 - `python3 tools/serve.py` —— 本地 SPA 服务器（Graph 视图位于 `#/graph`）

/visualize

Install this skill

Comments