知识关联规范

版本: 1.0
生效日期: 2026-04-04
适用范围: 知识库 V2 所有文档

🎯 目标

建立标准化的知识关联体系，确保知识库：

✅ 文档互联（不孤立）
✅ 导航清晰（不迷路）
✅ 图谱完整（可检索）

1️⃣ 内部链接规则

1.1 链接格式规范

场景	格式	示例
同目录链接	`[文本](./文件名.md)`	`[指南](./cloudflare-access-setup.md)`
上级目录	`[文本](../文件名.md)`	`[首页](../index.md)`
跨目录链接	`[文本](../目录/文件名.md)`	`[协议](../knowledge/protocols/V2-PROTOCOL.md)`
锚点链接	`[文本](./文件名.md#标题)`	`[步骤](./guide.md#步骤 -1)`
绝对路径	`[文本](/目录/文件名.md)`	`[首页](/index.md)`

1.2 必须添加链接的场景

场景	要求	示例
引用其他文档	必须链接	"详见故障排除指南"
前置知识	必须链接	"阅读本文前需了解 V2 协议"
后续知识	建议链接	"下一步：配置访问控制"
同一系列	互相链接	系列文档间添加"上一篇/下一篇"
相关主题	建议链接	"相关文档：标签体系"

1.3 链接质量要求

✅ 准确性 — 链接必须指向正确内容
✅ 有效性 — 链接必须有效（404 禁止）
✅ 描述性 — 链接文本需说明目标内容
❌ 禁止 — "点击这里"等无意义文本

错误示例：

markdown

❌ 点击这里查看详情
❌ 更多信息请点我

正确示例：

markdown

✅ 详见 [Cloudflare Access 配置指南](./cloudflare-access-setup.md)
✅ 参考 [V2 协议架构](./protocols/V2-PROTOCOL.md)

2️⃣ 标签体系

2.1 标签分类框架

标签体系
├── 文档类型 (必选 1 个)
│   ├── guide — 操作指南
│   ├── reference — 参考资料
│   ├── troubleshooting — 故障排除
│   ├── protocol — 协议规范
│   ├── report — 研究报告
│   └── project — 项目文档
│
├── 技术领域 (可选 1-3 个)
│   ├── python — Python 相关
│   ├── cloudflare — Cloudflare 服务
│   ├── git — Git 版本控制
│   ├── venv — 虚拟环境
│   ├── vitepress — VitePress 构建
│   ├── nodejs — Node.js 相关
│   └── docker — Docker 容器
│
├── 项目关联 (可选 1-2 个)
│   ├── nanobot — Nanobot 助手
│   ├── clawteam — ClawTeam 项目
│   ├── knowledge-base — 知识库 V2
│   └── openclaw — OpenClaw 项目
│
└── 优先级 (可选 1 个)
    ├── p0 — 核心文档
    ├── p1 — 重要文档
    └── p2 — 一般文档

2.2 标签使用规则

规则	说明	示例
必选类型标签	每篇文档必须包含 1 个文档类型标签	`tags: ['guide', ...]`
数量限制	每篇文档 2-5 个 tags	最少 2 个，最多 5 个
小写格式	所有 tags 使用小写	`['guide', 'python']` ✅
禁止自创	使用现有标签体系	不随意创建新标签
一致性	相同主题使用相同标签	所有 Cloudflare 文档都用 `cloudflare`

2.3 标签示例

故障排除文档：

yaml

tags: ['troubleshooting', 'python', 'venv', 'p1']

配置指南文档：

yaml

tags: ['guide', 'cloudflare', 'infrastructure', 'p0']

协议规范文档：

yaml

tags: ['protocol', 'knowledge-base', 'architecture', 'p0']

研究报告文档：

yaml

tags: ['report', 'market-research', 'analysis']

3️⃣ 知识图谱构建

3.1 自动构建机制

工具： knowledge_activator.py（ClawTeam V6.0 组件）

工作流程：

1. Git Push 触发 CI/CD
       ↓
2. VitePress 构建
       ↓
3. 运行 knowledge_activator.py
       ↓
4. 扫描所有 .md 文件
       ↓
5. 提取内部链接 → 构建 nodes + edges
       ↓
6. 生成 graph_index.json
       ↓
7. 提交至 main 分支

输出格式：

json

{
  "version": "6.0.0",
  "total_nodes": 9,
  "total_edges": 15,
  "nodes": {
    "node_id": {
      "file_path": "index.md",
      "title": "Nanobot 知识库",
      "outgoing_links": ["./guide.md", "./protocol.md"],
      "incoming_links": ["../other.md"],
      "tags": ["guide", "python"],
      "usage_count": 4,
      "success_rate": 0.75
    }
  }
}

3.2 手动补充关联

文档末尾统一格式：

markdown

---

## 🔗 相关文档

- [前置知识](./prerequisite.md) — 阅读本文前需了解
- [后续步骤](./next-step.md) — 完成本文档后的下一步
- [相关主题](./related.md) — 相关内容
- [参考资料](./reference.md) — 外部参考

3.3 知识图谱质量指标

指标	目标值	说明
总节点数	持续增长	文档总数
总边数	≥ 节点数×1.5	平均每篇文档 1.5 个链接
平均出链	≥ 1.5	每篇文档引用其他文档数
平均入链	≥ 1.0	每篇文档被引用数
孤立节点	0	无链接的文档

4️⃣ 导航增强

4.1 首页导航

docs/index.md 要求：

包含所有主要目录的导航链接
添加"最近更新"自动列表
添加"热门文档"（基于 usage_count）

4.2 目录索引

每个目录需有 index.md：

markdown

# 📁 目录名称

简要说明此目录的用途。

## 文档列表

- [文档 1](./doc1.md) — 说明
- [文档 2](./doc2.md) — 说明

## 相关目录

- [上级目录](../index.md)
- [关联目录](../other-dir/index.md)

4.3 面包屑导航

文档顶部添加：

markdown

[首页](../index.md) > [目录](./index.md) > 当前文档

📋 质量检查清单

新建文档检查

[ ] 包含至少 2 个内部链接（引用其他文档）
[ ] 包含至少 1 个标签（文档类型）
[ ] 包含"相关文档"章节
[ ] 所有链接有效（无 404）
[ ] 链接文本描述清晰

现有文档审查

[ ] 无孤立文档（至少 1 个入链 +1 个出链）
[ ] 标签符合体系规范
[ ] 链接路径正确（无绝对路径错误）
[ ] 锚点链接有效

知识图谱验证

[ ] graph_index.json 已更新
[ ] total_edges ≥ total_nodes × 1.5
[ ] 孤立节点数 = 0
[ ] tags_count > 0

🔗 相关文档

文档生命周期管理规范 — 新建/更新/归档流程
审查周期规范 — 定期审查机制
V2-PROTOCOL.md — 知识库 V2 架构协议

最后更新: 2026-04-04
状态: ✅ 已发布

知识关联规范 ​

🎯 目标 ​

1️⃣ 内部链接规则 ​

1.1 链接格式规范 ​

1.2 必须添加链接的场景 ​

1.3 链接质量要求 ​

2️⃣ 标签体系 ​

2.1 标签分类框架 ​

2.2 标签使用规则 ​

2.3 标签示例 ​

3️⃣ 知识图谱构建 ​

3.1 自动构建机制 ​

3.2 手动补充关联 ​

3.3 知识图谱质量指标 ​

4️⃣ 导航增强 ​

4.1 首页导航 ​

4.2 目录索引 ​

4.3 面包屑导航 ​

📋 质量检查清单 ​

新建文档检查 ​

现有文档审查 ​

知识图谱验证 ​

🔗 相关文档 ​

知识关联规范

🎯 目标

1️⃣ 内部链接规则

1.1 链接格式规范

1.2 必须添加链接的场景

1.3 链接质量要求

2️⃣ 标签体系

2.1 标签分类框架

2.2 标签使用规则

2.3 标签示例

3️⃣ 知识图谱构建

3.1 自动构建机制

3.2 手动补充关联

3.3 知识图谱质量指标

4️⃣ 导航增强

4.1 首页导航

4.2 目录索引

4.3 面包屑导航

📋 质量检查清单

新建文档检查

现有文档审查

知识图谱验证

🔗 相关文档