图谱导航和链接分析手册

版本：v4（2026-10） 工具：build_name_map4.py + link_checker4.py 输出目录：8000/test/ 部署产物：8000/nav.html

一、整体流程

① 规范 HTML 的 <title>
        ↓
② python build_name_map4.py     （抽 title，建中文名表）
        ↓
③ python link_checker4.py       （生成两份图谱）
        ↓
④ 双击 test/link_graph_nav4.html  （本地测试）
        ↓
⑤ 满意后复制到 8000/nav.html      （部署）

二、目录结构

8000/
├── build_name_map4.py              ← 建表脚本
├── link_checker4.py                ← 生成图谱脚本
├── d3.v7.min.js                    ← D3 源文件（被内嵌）
├── index.html                      ← 你的站点首页
├── nav.html                        ← 部署产物（图谱导航）
├── wq/  ICTC/  ncg/  ...           ← 你的站点内容
│
├── _reports/                       ← 旧版产物（保留，不用）
│
└── test/                           ← 新版产物目录（自动创建）
    ├── name_map4.csv               ← 中文名对照表（可手工维护）
    ├── name_map4.json              ← 自动生成，py 读取用
    ├── name_map_report4.txt        ← 质量报告
    ├── link_graph_nav4.html        ← 导航版（双击能跑）
    ├── link_graph_analysis4.html   ← 分析版
    └── report_nav4.txt             ← 链接问题报告

三、<title> 规范

格式

<title>名称 - 牛春国个人主页</title>
<title>名称 | 牛春国个人主页</title>

• 分隔符：-（空格-连字符-空格）或 |（空格-竖线-空格）
• 前后必须有空格
• 名称 部分是你想在图谱上显示的中文名
• 后半部分统一为站点名

示例

关键点

• 名称里可以有 -（无空格），不会被误切
• 名称里尽量别有 - 或 |（带空格），否则会被切成两段
• 没写分隔符 → 整个 <title> 就是名称

四、日常操作

场景 1：新增页面

1. 写 HTML，规范 <title>
2. 跑：

cd C:\Users\niuch\Documents\8000
python build_name_map4.py
python link_checker4.py

3. 双击 test/link_graph_nav4.html 看效果

场景 2：改了某个页面的 <title>

同上，跑两个脚本即可。不用手工改 CSV（因为 manual=no 时自动重新抽取）。

场景 3：某个页面不想改 <title>，但想在图谱上显示别的名字

1. 打开 test/name_map4.csv
2. 找到该行，改 chinese_name 列
3. 把 manual 列改成 yes
4. 保存（保持 UTF-8 BOM 编码）
5. 跑 python build_name_map4.py（同步到 JSON）
6. 跑 python link_checker4.py

注意：manual=yes 的行，以后重跑不会被 <title> 覆盖，但 title 列也不会更新。

场景 4：批量检查 title 质量

跑完 build_name_map4.py 后，看 test/name_map_report4.txt：

• 无 title 的文件：需要补 <title>
• title 为通用标题的文件：含"牛春国"、"个人站点"等关键词，可能是首页或漏改
• 已删除的文件：CSV 里保留但文件已删，可手工清理
• 手工维护的文件：manual=yes 的行

五、两个版本的区别

六、交互功能

左侧面板

注意：文件名和中文名互斥（开一个自动关另一个）。超链接独立。

节点交互

七、配色规则

节点颜色

其他

• 背景：紫 #7f1cad
• 连线：白 #ffffff，宽度 0.85
• 节点描边：白，根 2.5px，目录入口 2px，普通 1.2px

八、过滤规则

边的保留条件

一条边 A → B 保留，当且仅当：

1. B 后缀是 .html / .md / .pdf
2. A 和 B 同目录，或 A 是 index.html
3. A 是 index.html 时，B 必须是目录入口（*/nav.html 或 */index.html）
4. 深度差 ≤ 1

效果

被过滤的链接

• bigsize/ 目录下的链接
• njr/photo/yey、njr/video/s0、njr/video/_ 前缀
• 图片、视频等多媒体（不画边）

九、部署流程

本地测试

cd C:\Users\niuch\Documents\8000
python build_name_map4.py
python link_checker4.py

双击 test/link_graph_nav4.html 测试。

此时节点链接失效（因为 test/ 下没有 wq/ 等子目录），这是预期的。测试时主要看结构、配色、开关。

部署

copy 8000\test\link_graph_nav4.html 8000\nav.html

（或你习惯的其他名字）

上传到服务器后：

• D3：d3.v7.min.js 已内嵌，不依赖外部
• 节点链接：以 8000/ 为根，正常访问

部署后验证

浏览器打开 https://你的域名/nav.html：

• 图谱能显示
• 节点点击能打开页面
• 中文名开关正常

十、脚本配置

build_name_map4.py

SITE_ROOT = Path(r"C:\Users\niuch\Documents\8000")
OUTPUT_DIRNAME = "test"

link_checker4.py

SITE_ROOT = Path(r"C:\Users\niuch\Documents\8000")
OUTPUT_DIRNAME = "test"
D3_PATH = SITE_ROOT / "d3.v7.min.js"

常用配置项

# title 分隔符（抽取时取前面部分）
TITLE_SEPARATORS = [" - ", " – ", " — ", " | ", "｜", "·", "-", "–", "—"]

# 过滤的目录
EXCLUDE_DIRNAMES = {"bigsize", "_gsdata_", "_reports", ..., "test"}

# 过滤的目标前缀
BLOCK_PREFIX = ["bigsize/", "njr/photo/yey", "njr/video/s0", "njr/video/_"]

# 单元定义（配色用）
UNIT_DIRS = {
    "personal": ["ncg", "sh", "huiyilu", "xianhuashenghuo"],
    "tech":     ["ICTC", "tixi", "jishu", "my-store"],
    "wq":       ["wq"],
    "njr":      ["njr"],
}

十一、常见问题

Q1：中文名没显示

检查：

1. test/name_map4.json 存在吗？
2. 里面有你想要的条目吗？
3. HTML 里勾了"显示中文名"吗？（和"显示文件名"互斥）

Q2：图谱是鸟窝

• 看 nav 版（link_graph_nav4.html），不是 analysis 版
• nav 版过滤严格，不会鸟窝
• analysis 版本就是"全图"，正常

Q3：双击 HTML 打不开

• D3 已内嵌，应该能打开
• 如果还是不行，看浏览器控制台报错

Q4：节点链接失效

• 测试时在 test/ 下，链接以 test/ 为根，正常失效
• 部署到 8000/ 根目录后就正常

Q5：改了 CSV 没生效

• 检查 manual 列是否改成 yes
• 检查 CSV 保存编码是否是 UTF-8 BOM
• 重跑 python build_name_map4.py（同步到 JSON）
• 重跑 python link_checker4.py

Q6：某个文件被误判为断链

• 看 test/report_nav4.txt 的断链列表
• 检查目标文件是否存在、路径大小写是否正确
• 检查是否是查询参数（?file=xxx）导致的

Q7：想改配色

改 link_checker4.py 里的 UNIT_COLORS、COLOR_ROOT_STAR 等常量。

Q8：想改过滤规则

改 link_checker4.py 里的 link_allowed_py 函数。

十二、快捷命令

# 进入工作目录
cd C:\Users\niuch\Documents\8000

# 建表
python build_name_map4.py

# 生成图谱
python link_checker4.py

# 一条命令搞定
python build_name_map4.py && python link_checker4.py

十三、文件清单

十四、工作原则

1. 规范 <title> 是根本，manual 列尽量不用
2. 每改一批内容，重跑两个脚本，图谱自动更新
3. nav 版部署，analysis 版本地诊断，两者互补
4. 发现问题先看 report，再决定改 HTML 还是改配置
5. 测试产物在 test/，部署产物在 8000/，互不干扰

手册结束。有疑问随时问。