RailWise KB已发布

知识库导航与文档分类体系

RailWise 知识库的分类结构、文档命名规范、版本管理及检索策略，帮助用户高效定位所需技术文档。

复核 2026-07-09入门公开可引用RailWise 技术团队

learning-path

知识库导航与文档分类体系

本文档面向： 知识库使用者、文档贡献者、技术写作团队

分类体系总览

RailWise 知识库采用 四级分类 + 标签 的混合组织方式，兼顾结构化浏览与灵活检索。

知识库
├── 00-快速入门
│   ├── CLI 快速入门
│   ├── TSM 平台快速部署
│   ├── WorkWise 安装指南
│   └── RAILWISE-OS 快速配置
├── 01-核心场景指南
│   ├── 深基坑监测
│   ├── 盾构隧道
│   ├── 轨道交通保护区
│   ├── 桥梁健康监测
│   ├── 边坡稳定性
│   ├── 地下管廊
│   ├── 危旧房屋
│   ├── 文物保护
│   └── 无人机巡检
├── 02-产品使用手册
│   ├── RAILWISE-CLI
│   │   ├── 命令参考
│   │   ├── 插件开发
│   │   └── CI/CD 集成
│   ├── RAILWISE-TSM
│   │   ├── Web 控制台
│   │   ├── 监测方案配置
│   │   ├── 告警规则
│   │   └── 数据管理
│   ├── WorkWise
│   │   ├── 界面操作
│   │   ├── 数据可视化
│   │   ├── AI 助手
│   │   └── 报告模板
│   └── RAILWISE-OS
│       ├── 项目管理
│       ├── 客户协同
│       ├── 合同与财务
│       └── 报表中心
├── 03-技术标准与规范
│   ├── 国家标准解读
│   │   ├── GB 50026 工程测量标准
│   │   ├── GB 50497 基坑监测标准
│   │   ├── GB 50911 地铁监测规范
│   │   └── JGJ 8 变形测量规范
│   └── 行业最佳实践
│       ├── 监测方案设计模板
│       ├── 报告编制规范
│       └── 质量控制 checklist
├── 04-开发者与集成
│   ├── API 文档
│   ├── Webhook 集成
│   ├── 数据格式规范
│   ├── SDK 开发指南
│   └── 第三方系统对接
│       ├── 钉钉
│       ├── 企业微信
│       ├── 飞书
│       └── 自建 OA
├── 05-运维与部署
│   ├── Docker 部署
│   ├── Kubernetes 部署
│   ├── 高可用架构
│   ├── 备份与恢复
│   ├── 监控告警
│   └── 性能调优
├── 06-常见问题
│   ├── CLI 常见问题
│   ├── TSM 常见问题
│   ├── WorkWise 常见问题
│   ├── 仪器连接问题
│   └── 数据异常问题
└── 07-发布说明
    ├── 版本发布说明
    ├── 迁移指南
    ├── 弃用功能公告
    └── 路线图

文档命名规范

文件命名规则

采用 kebab-case（短横线连接的小写字母）：

<主题>-<细分>-<类型>.md

组成部分	说明	示例
`主题`	核心主题词	`cli`, `tsm`, `workwise`, `os`
`细分`	功能或场景	`quickstart`, `deploy`, `config`
`类型`	文档类型	`guide`, `reference`, `faq`

示例：

文档内容	文件名
CLI 快速入门	`cli-quickstart.md`
TSM Docker 部署	`tsm-docker-deploy.md`
WorkWise 安装指南	`workwise-install-guide.md`
GB 50026 标准解读	`gb50026-guide.md`
基坑监测方案	`deep-foundation-monitoring.md`
API 参考文档	`api-reference.md`
Webhook 集成	`webhook-integration.md`

目录命名规则

批次1/          # 批次编号，用于文档发布计划
├── index.md    # 该批次索引页
├── cli-quickstart.md
└── tsm-quick-deploy.md

YAML Frontmatter 规范

每份文档必须以 YAML Frontmatter 开头，包含以下字段：

---
title: "文档标题（中文）"
description: "文档摘要，120 字以内，用于 SEO 与搜索结果展示"
category_primary: "一级分类"
category_secondary: "二级分类"
tags: ["标签1", "标签2", "标签3"]
author: "RailWise 技术文档团队"
date: "YYYY-MM-DD"
version: "x.y.z"
---

字段说明

字段	必填	说明	示例值
`title`	是	文档标题	`"CLI 快速入门"`
`description`	是	摘要描述	`"RAILWISE-CLI 的安装、配置..."`
`category_primary`	是	一级分类	`"快速入门"`
`category_secondary`	是	二级分类	`"CLI"`
`tags`	是	标签数组	`["CLI", "安装", "Bun"]`
`author`	是	作者/团队	`"RailWise 技术文档团队"`
`date`	是	发布/更新日期	`"2025-06-05"`
`version`	是	文档版本	`"1.0.0"`

分类值域

一级分类（category_primary）：

快速入门
核心场景指南
产品使用手册
技术标准与规范
开发者与集成
运维与部署
常见问题
发布说明
知识库

二级分类（category_secondary）：

按产品：CLI, TSM, WorkWise, OS
按场景：深基坑, 盾构隧道, 地铁保护区, 桥梁, 边坡, 管廊, 房屋, 文物, 无人机
按类型：API, 部署, 配置, 规范, FAQ

版本管理策略

文档版本号规则

采用 语义化版本（SemVer）：

主版本.次版本.修订版本

版本位	递增条件	示例
主版本	文档结构重大调整、内容重写	`1.0.0` → `2.0.0`
次版本	新增章节、功能覆盖扩展	`1.0.0` → `1.1.0`
修订版本	错误修正、参数更新、链接修复	`1.0.0` → `1.0.1`

版本历史记录

在文档末尾添加版本历史表格：

## 版本历史

| 版本 | 日期 | 更新内容 | 作者 |
|------|------|---------|------|
| 1.0.1 | 2025-06-10 | 修正 Docker 端口映射示例 | 张三 |
| 1.0.0 | 2025-06-05 | 初始发布 | 技术文档团队 |

交叉引用规范

文档内链接

使用相对路径链接同一目录下的文档：

[CLI 快速入门](./cli-quickstart.md)
[TSM 平台快速部署](./tsm-quick-deploy.md)

跨目录链接

使用相对路径向上/向下导航：

[GB 50026 解读](../03-技术标准/gb50026-guide.md)
[API 参考](../04-开发者/api-reference.md)

锚点链接

链接到文档内的特定章节：

[常见问题](#常见问题)
[步骤 2：配置环境变量](#步骤-2配置环境变量)

提示框使用规范

使用 Docusaurus/VitePress 风格的提示框增强可读性：

:::tip 提示标题
提示内容，用于补充有用信息或最佳实践建议。
:::

:::warning 警告标题
警告内容，用于提醒可能导致错误或数据丢失的操作。
:::

:::info 信息标题
信息内容，用于提供背景知识或额外说明。
:::

:::danger 危险标题
危险内容，用于强调严重风险或不可逆操作。
:::

使用频率建议：

每篇文档提示框总数不超过 5 个
tip 与 warning 使用最为频繁
danger 仅在涉及数据删除、系统重置等场景使用

检索策略

站内搜索

知识库支持全文检索，以下元素会被索引：

YAML Frontmatter 所有字段
正文标题（H1-H6）
正文段落文本
代码块内容（用于技术检索）
表格内容

标签检索

通过标签快速筛选同主题文档：

标签类型	示例	用途
产品标签	`#CLI`, `#TSM`, `#WorkWise`	按产品筛选
场景标签	`#深基坑`, `#盾构隧道`, `#地铁保护区`	按场景筛选
技术标签	`#Docker`, `#API`, `#Rust`	按技术栈筛选
类型标签	`#教程`, `#参考`, `#FAQ`	按文档类型筛选

AI 语义标签

每篇文档末尾包含机器可读的语义标签，用于智能推荐与知识图谱构建：

<meta name="ai-tags" content="关键词1,关键词2,关键词3" />
<meta name="ai-intent" content="用户意图描述" />
<meta name="ai-audience" content="目标读者群体" />

文档贡献指南

新建文档流程

确定文档分类与文件名
复制模板文件（template.md）
填写 YAML Frontmatter
撰写正文内容
添加交叉引用链接
本地预览检查格式
提交 Pull Request

文档模板

---
title: "文档标题"
description: "文档摘要"
category_primary: "一级分类"
category_secondary: "二级分类"
tags: ["标签1", "标签2"]
author: "RailWise 技术文档团队"
date: "YYYY-MM-DD"
version: "1.0.0"
---

# 文档标题

> **预计阅读时间：** X 分钟
> **目标：** 一句话描述本文档目标

---

## 章节 1

内容...

### 子章节 1.1

内容...

## 章节 2

内容...

---

## 常见问题

### Q1: 问题描述

**原因：** ...

**解决：** ...

---

## 下一步

- [相关文档 1](./related-doc-1.md)
- [相关文档 2](./related-doc-2.md)

---

## 📋 元数据标签

<meta name="ai-tags" content="关键词" />
<meta name="ai-intent" content="意图" />
<meta name="ai-audience" content="读者" />

---

*本文档最后更新于 YYYY-MM-DD | 版本 vX.Y.Z | 宁波睿威工程技术有限公司 版权所有*

下一步

RailWise 知识库首页 — 返回知识库总览
CLI 快速入门 — 开始产品学习
TSM 平台快速部署 — 部署自动化监测平台