视频教程：RAILWISE-CLI 安装与首条命令

视频教程：RAILWISE-CLI 安装与首条命令

视频时长：约 12 分钟
难度：入门级
目标：完成 RAILWISE-CLI 安装并执行第一条工作流命令

---

视频概述

本视频面向首次接触 RAILWISE-CLI 的测绘工程师与技术人员，演示从环境准备到成功执行首条命令的完整流程。通过本教程，您将在 10 分钟内完成 CLI 环境的搭建并运行第一个水准测量数据处理工作流。

视频内容结构

章节	时间点	内容
开场介绍	00:00 - 00:45	产品定位、适用场景、学习路径
环境准备	00:45 - 03:30	系统要求检查、Bun 安装、验证
CLI 安装	03:30 - 05:00	全局安装、版本验证、镜像源配置
项目初始化	05:00 - 07:30	配置文件生成、项目信息设置
首条命令	07:30 - 10:00	工作流编写、执行、结果查看
常见问题	10:00 - 11:30	安装失败、权限问题、编码问题
课后练习	11:30 - 12:00	练习任务布置与资源链接

---

前置知识

在开始本教程前，请确保具备以下基础：

1. 操作系统基础：熟悉 macOS / Windows / Linux 的基本操作
2. 命令行基础：了解终端/命令提示符的基本使用（cd、ls/dir 等）
3. 文本编辑：能够使用任意文本编辑器（VS Code、记事本、vim 等）
4. 网络环境：可访问互联网（国内用户建议配置镜像源）

本教程面向非程序员用户设计，所有代码均可复制粘贴执行，无需编写程序。

---

步骤详解

步骤 1：检查系统要求（00:45 - 01:30）

视频画面：屏幕录制，展示系统信息查看过程

在开始安装前，请确认您的系统满足最低要求：

项目	最低要求	检查方法
操作系统	macOS 12 / Windows 10 / Linux	系统设置中查看
内存	4 GB	任务管理器/活动监视器
磁盘空间	2 GB 可用	文件管理器查看
网络	可访问 npm registry	浏览器访问 npmjs.com

[截图占位符：系统信息查看界面]

---

步骤 2：安装 Bun 运行时（01:30 - 03:30）

视频画面：终端窗口，逐行执行安装命令

Bun 是 RAILWISE-CLI 的运行时环境，类似于 Java 需要 JRE、Python 需要解释器。

macOS / Linux 安装

# 执行官方安装脚本（约 30 秒）
curl -fsSL https://bun.sh/install | bash

# 安装完成后，根据提示重新加载配置
source ~/.bashrc  # 或 ~/.zshrc（macOS 默认）

Windows 安装（PowerShell）

# 执行官方安装脚本
powershell -c "irm bun.sh/install.ps1|iex"

验证安装

# 检查 Bun 版本
bun --version
# 预期输出：1.1.x 或更高版本

提示

若官方脚本下载缓慢，可配置镜像源：

export BUN_INSTALL_MIRROR="https://bun.sh.cn"
curl -fsSL https://bun.sh/install | bash

[截图占位符：Bun 安装成功后的版本输出]

---

步骤 3：安装 RAILWISE-CLI（03:30 - 05:00）

视频画面：终端窗口，执行 CLI 安装命令

# 全局安装 RAILWISE-CLI
bun install -g @railwise/cli

# 验证安装
railwise --version
# 预期输出：RAILWISE-CLI v1.2.0

安装失败排查

错误现象	可能原因	解决方案
EACCES: permission denied	全局目录权限不足	使用 --prefix ~/.local 或 sudo
package not found	网络/registry 问题	配置国内镜像源后重试
长时间无响应	网络连接超时	检查网络，或使用 --timeout 60000

[截图占位符：CLI 安装成功界面]

---

步骤 4：初始化项目配置（05:00 - 07:30）

视频画面：终端执行初始化命令，展示生成的配置文件结构

# 创建项目目录并初始化
mkdir ~/railwise-projects
cd ~/railwise-projects

# 执行初始化向导
railwise init --project "我的第一个监测项目"

初始化完成后，将生成以下目录结构：

.railwise/
├── config.yaml          # 主配置文件
├── agents/              # 智能体配置
│   ├── surveyor.yaml
│   ├── adjuster.yaml
│   ├── monitor.yaml
│   └── inspector.yaml
├── workflows/           # 工作流模板
│   └── default.yaml
└── templates/           # 报告模板
    └── report.md

配置项目信息

编辑 .railwise/config.yaml：

project:
  name: "宁波地铁3号线保护区监测"
  code: "NB-M3-2025-001"
  client: "宁波市轨道交通集团"
  contractor: "宁波睿威工程技术有限公司"

standards:
  primary: "GB 50497-2019"
  secondary: "GB 50911-2013"

output:
  format: "markdown"
  encoding: "utf-8"
  timezone: "Asia/Shanghai"

请确保原始数据文件、配置文件、终端环境均使用 UTF-8 编码，以避免中文字符乱码导致的数据解析错误。

[截图占位符：配置文件编辑界面，高亮关键字段]

---

步骤 5：执行首条工作流（07:30 - 10:00）

视频画面：工作流文件编写、保存、执行及结果查看

创建工作流文件

创建 workflows/leveling.yaml：

name: "二等水准测量处理"
description: "从原始数据到平差报告的标准化流程"

steps:
  - name: "数据导入"
    agent: "surveyor"
    action: "import"
    input: "data/leveling/leveling_data.gsi"
    params:
      format: "gsi"
      instrument: "leica_ls15"

  - name: "数据质检"
    agent: "inspector"
    action: "check"
    params:
      checks: ["限差", "闭合差", "粗差探测"]
      standard: "GB 50026-2020"

  - name: "平差计算"
    agent: "adjuster"
    action: "adjust"
    params:
      method: "间接平差"
      weight_scheme: "按距离定权"

  - name: "生成报告"
    agent: "surveyor"
    action: "report"
    output: "output/leveling_report.md"
    template: "templates/leveling.md"

执行工作流

# 执行工作流
railwise run workflows/leveling.yaml

预期输出：

[2025-06-15T09:30:00+08:00] INFO  开始执行工作流：二等水准测量处理
[2025-06-15T09:30:01+08:00] INFO  [1/4] 数据导入 — 读取 42 个测站，156 个观测值
[2025-06-15T09:30:02+08:00] INFO  [2/4] 数据质检 — 限差检查通过，闭合差 +2.1mm（限差 ±4.0mm）
[2025-06-15T09:30:03+08:00] INFO  [3/4] 平差计算 — 单位权中误差 ±0.8mm，最弱点高程中误差 ±1.2mm
[2025-06-15T09:30:04+08:00] INFO  [4/4] 生成报告 — 输出至 output/leveling_report.md
[2025-06-15T09:30:04+08:00] INFO  工作流执行完成，耗时 4.2s

[截图占位符：工作流执行成功后的终端输出]

---

关键操作要点

要点 1：环境变量持久化

Bun 安装后，若关闭终端后 bun 命令不可用，需将 Bun 添加到系统 PATH：

# macOS / Linux（Zsh）
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Windows
# 安装程序已自动添加，如未生效请手动添加 %USERPROFILE%\.bun\bin 到 PATH

要点 2：镜像源配置

国内用户建议永久配置镜像源：

# Bun 镜像源
bun config set registry https://registry.npmmirror.com

# 或 RailWise 私有 registry
bun config set registry https://npm.railwise.cn

要点 3：工作流文件语法

YAML 文件对缩进敏感，请严格遵循以下规则：

• 使用空格缩进，禁止使用 Tab
• 同级元素缩进量必须一致
• 冒号后必须有空格：key: value

要点 4：数据文件准备

工作流中的 input 路径需指向实际存在的数据文件。首次练习可使用示例数据：

# 下载示例数据
mkdir -p data/leveling
curl -o data/leveling/leveling_data.gsi https://docs.railwise.cn/samples/leveling_data.gsi

---

常见问题（FAQ）

Q1: bun 命令找不到？

原因：Bun 未正确添加到 PATH。

解决：

# 检查 Bun 安装位置
ls ~/.bun/bin/bun

# 手动添加 PATH
export PATH="$HOME/.bun/bin:$PATH"

# 永久生效（写入配置文件）
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc

Q2: 安装 CLI 时提示权限不足？

原因：全局 npm 目录需要管理员权限。

解决：

# 方案一：用户级安装（推荐）
bun install -g @railwise/cli --prefix ~/.local
export PATH="$HOME/.local/bin:$PATH"

# 方案二：使用 sudo（macOS/Linux）
sudo bun install -g @railwise/cli

Q3: 工作流执行报错 “YAML parse error”？

原因：YAML 文件缩进或语法错误。

解决：

1. 检查是否使用了 Tab 缩进（应使用空格）
2. 检查冒号后是否有空格
3. 使用在线验证工具：https://www.yamllint.com/

Q4: 数据导入后显示乱码？

原因：文件编码与系统编码不一致。

解决：

# 转换文件编码
iconv -f GBK -t UTF-8 data.gsi > data_utf8.gsi

# 重新导入
railwise run workflows/leveling.yaml --input data_utf8.gsi

Q5: 如何更新 CLI 到最新版本？

# 全局更新
bun update -g @railwise/cli

# 验证版本
railwise --version

---

课后练习

练习 1：更换项目名称

修改 .railwise/config.yaml 中的 project.name 为您当前负责的监测项目名称，重新执行初始化。

练习 2：尝试不同数据格式

下载 CSV 格式示例数据，修改工作流中的 format 参数为 csv，重新执行工作流。

练习 3：查看帮助文档

在终端中执行以下命令，探索 CLI 的更多功能：

railwise --help
railwise agent list
railwise workflow --help

练习 4：阅读进阶文档

• CLI 智能体配置详解
• CLI 工作流编排指南
• CLI 数据格式与导入

---

相关文档链接

• RAILWISE-CLI 快速入门指南 — 更详细的图文版入门指南
• CLI 常见问题与故障排查 — 更全面的故障排查手册
• CLI 智能体配置详解 — 深入了解四大智能体
• CLI 工作流编排 — 学习高级工作流设计

---

视频资源

• 视频文件：video-cli-01-installation.mp4
• 配套数据：sample-leveling-data.gsi
• 讲义下载：handout-cli-01.pdf
• 字幕文件：video-cli-01-installation.srt

---

元数据标签

---

本文档最后更新于 2025-06-15 | 版本 v1.0.0 | 宁波睿威工程技术有限公司 版权所有