RAILWISE-CLI 快速入门指南

RAILWISE-CLI 快速入门指南

目标读者：首次接触 RAILWISE-CLI 的测绘工程师、项目技术人员
预计阅读时间：15 分钟
前置要求：已安装 Bun 运行时（≥1.1.0）

---

1. 产品简介

RAILWISE-CLI 是 RailWise 推出的 AI 工程测绘多智能体命令行系统，基于 TypeScript 与 Bun 运行时构建。它将传统分散的测绘数据处理、质量检查、报告生成等流程，整合为可编排的智能体工作流，支持深基坑、盾构隧道、轨道交通保护区等核心场景。

1.1 核心特性

特性	说明
多智能体编排	内置测量、平差、监测、质检四大智能体，支持自定义扩展
一键工作流	通过 YAML 配置文件定义完整作业流程
数据格式兼容	支持徕卡、拓普康、南方、天宝等主流全站仪原始数据格式
标准规范内置	自动校验 GB 50026、GB 50497、GB 50911 等规范要求
AI 辅助决策	集成异常数据识别、趋势预测、预警分级建议

---

2. 环境准备

2.1 系统要求

项目	最低要求	推荐配置
操作系统	macOS 12 / Windows 10 / Linux (glibc 2.31+)	macOS 14 / Windows 11 / Ubuntu 22.04
运行时	Bun 1.1.0	Bun 1.1.20+
内存	4 GB	8 GB
磁盘空间	2 GB	5 GB（含缓存）
网络	可访问 npm registry	稳定互联网连接

2.2 安装 Bun 运行时

提示

若官方安装脚本下载缓慢，可使用镜像源：

export BUN_INSTALL_MIRROR="https://bun.sh.cn"

macOS / Linux：

curl -fsSL https://bun.sh/install | bash

Windows（PowerShell）：

powershell -c "irm bun.sh/install.ps1|iex"

验证安装：

bun --version
# 预期输出：1.1.x 或更高

2.3 安装 RAILWISE-CLI

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

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

---

3. 首次配置

3.1 初始化配置文件

railwise init --project "我的监测项目"

执行后将在当前目录生成 .railwise/ 配置目录：

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

3.2 配置项目信息

编辑 .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"            # 可选：markdown / docx / pdf
  encoding: "utf-8"
  timezone: "Asia/Shanghai"

agents:
  surveyor:
    instrument_brands: ["leica", "topcon"]
    default_precision: "二等"
  monitor:
    alert_threshold_method: "规范法"  # 规范法 / 统计法 / 综合法

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

---

4. 第一个工作流：水准测量数据处理

4.1 准备数据

将全站仪导出的原始数据文件放入项目目录：

mkdir -p data/leveling
cp /path/to/leveling_data.gsi data/leveling/

4.2 编写工作流

创建 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"

4.3 执行工作流

railwise run workflows/leveling.yaml

终端将显示执行进度：

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

---

5. 常用命令速查

命令	功能	示例
railwise --version	查看版本	—
railwise init	初始化项目	railwise init --project "项目名称"
railwise run <file>	执行工作流	railwise run workflow.yaml
railwise check <file>	数据质检	railwise check data.gsi --standard GB50497
railwise adjust <file>	平差计算	railwise adjust data.json --method 间接平差
railwise report	生成报告	railwise report --template default
railwise agent list	列出智能体	—
railwise agent logs <name>	查看智能体日志	railwise agent logs surveyor
railwise config get <key>	读取配置	railwise config get project.name
railwise config set <key> <val>	设置配置	railwise config set output.format docx

---

6. 下一步

• 深入了解智能体配置：cli-agents-configuration.md
• 学习高级工作流编排：cli-workflow-orchestration.md
• 掌握数据格式与导入：cli-data-formats.md
• 排查常见问题：cli-troubleshooting.md

---

元数据标签