KDL_WORK/working1/01-项目功能内容.md

01-项目功能内容

版本：0.1 日期：2026-06-27

1. 总体需求

以 ABB IRB120 3/58 的 URDF fixture 为真实 6 轴工业机器人基准，构建一套端到端全面测试能力：

1. 编写通用机器人语言 GRL 测试程序，覆盖运动、路径、IO、等待、工艺、报警和异常。
2. 在项目运行时加载 ABB120 URDF，执行 FK、IK、Jacobian、限位、轨迹规划、虚拟控制器运行和调试。
3. 将同一 GRL/IR 输出为 ABB RAPID、FANUC LS 风格和 KUKA KRL 风格程序，并生成转换报告。
4. 建立离线编程全面测试，包括资源建模、路径生成、可达性、节拍、碰撞、IO/Wait、品牌导入导出、报告和客户交付包。
5. 用 HTML 实现本项目虚拟控制器界面，对标 ABB RobotStudio 的 Station、Controller、RAPID、Simulation、Virtual FlexPendant 等工作流。
6. 补齐 GRL 运算表达式能力，覆盖 ABB、FANUC、KUKA 三类机器人语言共同具备的算术、比较、逻辑和常用数学函数，并能在运动参数编译期求值。

2. ABB120 URDF 基准

基准机器人来自 /home/meswork/kdl_work/kdl-wasm/web/tests/fixtures/abbIrb120.ts 中的 ABB_IRB120_3_58_URDF。

项	值
robotId	abb_irb120_3_58
baseLink	base_link
tipLink	tool0
DOF	6
active joints	joint_1 到 joint_6
fixed links	base、flange、tool0
URDF 来源	ROS-Industrial ABB IRB120 3/58 xacro 派生，当前 fixture 省略 mesh、material、inertial、xacro-only 元素

关节限位以 fixture 为准：

关节	lower rad	upper rad	velocity rad/s
joint_1	-2.87979	2.87979	4.36332
joint_2	-1.91986	1.91986	4.36332
joint_3	-1.91986	1.22173	4.36332
joint_4	-2.79253	2.79253	5.58505
joint_5	-2.094395	2.094395	5.58505
joint_6	-6.98132	6.98132	7.33038

标准测试关节位：

名称	rad
home	[0, 0, 0, 0, 0, 0]
pick	[0.2, -0.35, 0.45, 0.1, -0.2, 0.3]
place	[-0.35, -0.25, 0.35, -0.25, 0.15, -0.4]
approach	[0, -0.4, 0.5, 0, 0.2, 0]

3. 通用机器人测试程序集

测试程序以 GRL 为主，命名建议为 A120_XX_*.grl。所有程序必须能解析为 AST、编译为 Semantic IR、进入 KDL bridge，并保留 source map。

3.1 A120_00_Smoke.grl

目标：最小链路冒烟测试。

覆盖点：

1. 语言头、module、speed、zone、target。
2. movej home。
3. FK、限位检查、轨迹规划和 ABB 后处理。

验收：程序运行完成，无 error diagnostic；ABB/FANUC/KUKA 输出均非空。

3.2 A120_10_JointPickPlace.grl

目标：关节空间 pick/place 主流程。

基准程序：

language grl 0.1
module A120JointPickPlace
  const speed v_fast = joint(40 %)
  const speed v_slow = joint(20 %)
  const zone z10 = z(10 mm)

  target home = joint_target { joints: [0 deg, 0 deg, 0 deg, 0 deg, 0 deg, 0 deg] }
  target approach = joint_target { joints: [0 deg, -22.918312 deg, 28.647890 deg, 0 deg, 11.459156 deg, 0 deg] }
  target pick = joint_target { joints: [11.459156 deg, -20.053523 deg, 25.783101 deg, 5.729578 deg, -11.459156 deg, 17.188734 deg] }
  target place = joint_target { joints: [-20.053523 deg, -14.323945 deg, 20.053523 deg, -14.323945 deg, 8.594367 deg, -22.918312 deg] }

  path pick_place {
    defaults { speed: v_fast, zone: z10 }
    point p_home movej home zone fine
    point p_approach movej approach
    event before p_pick io.do[1] = true
    point p_pick movej pick speed v_slow zone fine
    point p_place movej place
    event after p_place io.do[1] = false
  }

  proc main()
    run_path pick_place
  end
end

验收：planPath 产生 4 段 MOVEJ，终点关节等于 place，IO 事件进入 trace。

3.3 A120_20_CartesianBlend.grl

目标：笛卡尔运动和 blend 规则测试。

覆盖点：

1. 由 home/pick/place FK 自动生成 reachable pose targets。
2. movel 接近点、工件点和离开点。
3. movec 中间点和终点。
4. zone fine 与 z(10 mm) 对比。

验收：每个 pose target 通过 IK；笛卡尔段输出最大 TCP 直线误差和圆弧误差。

3.4 A120_30_IOWaitPulse.grl

目标：IO、等待、脉冲和 timeout。

覆盖点：

1. io.do[n] = true/false。
2. wait io.di[n] == true timeout 2 s。
3. pulse io.do[n] duration 100 ms。
4. timeout 后 alarm 或 fallback path。
5. IO script 驱动 DI 上升沿、下降沿和 changed。

验收：虚拟控制器可显示 wait 表达式、已等待时间、剩余 timeout、相关 IO 最近变化和脚本状态。

3.5 A120_40_ErrorDiagnostics.grl

目标：故障路径和诊断稳定性。

覆盖点：

1. 超出关节限位目标。
2. 明确不可达 pose target。
3. 奇异姿态或接近奇异姿态。
4. 未定义 target/path/operation。
5. wait timeout。

验收：每类故障都有稳定 code、severity、source map 和报告条目。

3.6 A120_50_OperationProcess.grl

目标：工艺 operation 和离线编程对象闭环。

覆盖点：

1. path、operation、run_operation。
2. start/end action，如夹爪、吹气、扫码、视觉等待。
3. 工艺参数进入报告和交付包。
4. OLP 对象模型可反向生成 GRL。

验收：operation 展开为 action + path + action，报告包含工艺步骤、节拍和 IO 事件。

4. GRL 运算功能需求

目标：将“运算功能”作为 GRL 语言和语义基础能力补齐，而不是只让 parser 能读。首版按 ABB RAPID、FANUC LS/KAREL、KUKA KRL 的公共数学子集建模，保证同一 GRL 程序可以稳定编译到统一 IR，再由后处理器输出三品牌程序。

4.1 语法范围

GRL 表达式必须支持：

1. 算术：一元 +、一元 -、+、-、*、/、mod。
2. 比较：==、!=、<、<=、>、>=。
3. 逻辑：and、or、not，可兼容 &&、||、! 作为输入别名，IR 中统一为 GRL 关键字。
4. 括号：(...) 明确优先级。
5. 函数调用：沿用当前 callee(args...) 形式。
6. 现有结构表达式：array、object、call、identifier、offset 表达式必须继续兼容。

优先级从高到低：

层级	运算
1	函数调用、对象、数组、括号、offset
2	一元 +、-、not、!
3	*、/、mod
4	+、-
5	<、<=、>、>=
6	==、!=
7	and、&&
8	or、`

4.2 函数和常量

首版内置常量：

名称	含义
pi	圆周率
e	自然常数

首版内置函数：

类别	函数
三角函数	sin、cos、tan、asin、acos、atan、atan2
数值函数	sqrt、abs、pow、min、max、clamp、floor、ceil、round

三角函数语义：

1. sin/cos/tan 接收角度量；带 deg 或 rad 单位时归一化为弧度，纯数按弧度处理。
2. asin/acos/atan/atan2 返回角度量；在 pose(...) 姿态项或 joint_target.joints 等角度上下文中可直接使用。
3. 函数必须做定义域检查，例如 sqrt(-1)、acos(2) 必须产生 diagnostic。

4.3 编译期求值位置

常量表达式必须在编译阶段求值，并把结果写入 Semantic IR / KDL request，而不是把表达式字符串传到运动规划层。

必须支持的求值位置：

1. 数据声明 initializer：const、persistent、需要静态初值的 var。
2. speed：linear(...)、joint(...)、acc ... 参数。
3. zone：fine、z(...)、cnt(...)。
4. pose(...)、poseq(...)、robot_config(...)。
5. joint_target { joints: [...] }。
6. pose_target { pose: ... }。
7. tool { tcp: ..., mass: ... }。
8. frame { origin: ... }。
9. path defaults/source 属性。
10. path point 内联 speed、zone、tool、frame、via、target 参数。
11. path event 的 distance。
12. wait ... timeout ... 和 pulse ... duration ... 中的时间常量。
13. operation process 中需要数值常量的工艺参数。

比较和逻辑表达式也必须进入 AST。纯常量比较/逻辑可在编译期折叠；依赖 IO、变量或运行态状态的条件先保留为结构化控制表达式，供虚拟控制器和后续品牌映射使用。

4.4 单位和数值语义

数值求值采用统一 SI 归一化：

GRL 输入	IR/KDL 归一化
mm	m
mm/s	m/s
mm/s2	m/s2
deg	rad
rad	rad
%	0 到 1 的比例
s	s
ms	s
kg	kg

规则：

1. 同维度数值可以相加、相减，结果保留该维度并归一化。
2. 纯数可以参与乘除；维度乘除首版只允许编译器明确支持的上下文，避免产生复杂复合单位。
3. 不同维度相加或比较必须报错，例如 10 mm + 2 s。
4. 构造器可以提供默认上下文单位：linear(...) 默认 mm/s，z(...) 默认 mm，pose(...) 前三项默认 mm、后三项默认 deg，joint_target.joints 默认 deg，duration/timeout 默认 s。
5. 因此 linear(100 + 50 mm/s) 在 linear 速度上下文中等价于 linear(150 mm/s)；推荐生成器输出时使用显式单位，减少人工歧义。

4.5 示例

language grl 0.1
module MathMotion
  const num blend_base = 5 + 5
  const speed v_pick = linear(100 + 50 mm/s)
  const speed v_safe = linear(max(50 mm/s, 200 mm/s / 2))
  const zone z_app = z(clamp(blend_base mm, 1 mm, 50 mm))

  target home = joint_target {
    joints: [0 deg, (10 + 5) deg, -90 deg, 0 deg, 0 deg, 0 deg]
  }
  target pick = pose_target {
    pose: pose(400 + 50 mm, 20 * 2 mm, sqrt(90000) mm, 0 deg, 0 deg, atan2(1, 1))
  }

  path main_path {
    defaults { speed: v_pick, zone: z_app }
    point p0 movej home speed linear(100 + 50 mm/s) zone z(clamp(8 mm, 1 mm, 20 mm))
    point p1 movel pick
  }
end

编译期结果要求：

1. v_pick 进入 IR 后为 linear，速度 0.15 m/s。
2. z_app 进入 IR 后为 distance，距离 0.01 m。
3. home.joints[1] 进入 IR 后为 15 deg 对应的弧度值。
4. pick.pose.position[0] 进入 IR 后为 0.45 m。
5. path point 内联 speed/zone 同样求值后进入 KDL request。

4.6 诊断需求

运算功能必须输出稳定 diagnostic：

code	场景
GRL_EXPR_PARSE	表达式语法错误或括号不匹配。
GRL_EXPR_UNKNOWN_SYMBOL	常量求值遇到未知标识符。
GRL_EXPR_UNKNOWN_FUNCTION	未知函数。
GRL_EXPR_ARITY	函数参数数量错误。
GRL_EXPR_DOMAIN	数学定义域错误。
GRL_EXPR_DIV_ZERO	除零。
GRL_EXPR_UNIT_MISMATCH	单位维度不兼容。
GRL_EXPR_NON_CONSTANT	需要常量的位置出现运行时表达式。
GRL_EXPR_UNSUPPORTED_RUNTIME	后续品牌映射暂不支持的复杂运行时表达式。

每个 diagnostic 必须包含 severity、message、source range，并能通过 source map 定位到 GRL 源文件行列。

4.7 跨品牌边界

首版跨品牌输出不直接翻译复杂表达式字符串，而是优先输出编译期折叠后的常量：

1. linear(100 + 50 mm/s) 输出为各品牌可表达的具体速度值。
2. z(clamp(...)) 输出为具体 ABB zone、FANUC CNT 或 KUKA 近似 blend。
3. runtime 条件表达式如果后处理器无法保真映射，必须进入转换报告，不得静默丢失。
4. 品牌专用数学函数或控制器变量不作为首版目标，后续通过 post/import report 增量支持。

5. 程序运行需求

运行器必须支持以下流程：

1. 加载 ABB120 URDF fixture，生成 NormalizedRobotModel 和 RobotHandle。
2. 编译 GRL：Lexer、Parser、Semantic Analyzer、IR、source map。
3. 对每个 target/path/operation 生成 KDL request。
4. 执行 KDL：FK、fkAllLinks、Jacobian、IK、limit、singularity、planMoveJ、planMoveL、planMoveC、planPath、validatePath。
5. 执行虚拟控制器：load、run、pause、step、stop、reset、breakpoint、motion queue、IO、wait、pulse、trace。
6. 输出结构化 job：job_id、输入文件、运行参数、诊断、轨迹、trace、报告、截图路径。

6. 跨品牌程序转换需求

同一 Semantic IR 必须输出：

品牌	输出文件	核心指令
ABB	.mod	MoveJ、MoveL、MoveC、SetDO、WaitUntil、PulseDO
FANUC	.ls	J、L、C、DO[]、WAIT、PULSE
KUKA	.src，必要时 .dat	PTP、LIN、CIRC、$OUT[]、WAIT FOR

转换报告必须记录：

1. 速度、zone、tool、frame 映射。
2. 近似语义，如 ABB zone 到 FANUC CNT、KUKA C_DIS。
3. 不支持语义，如复杂 trap、多任务、品牌专用工艺包。
4. source map：GRL 行列、path point、operation、品牌输出行号。
5. 回读校验：品牌文本重新导入后，target/path/motion 顺序与原 IR 等价或输出差异报告。

7. 离线编程全面测试需求

全面测试必须覆盖：

1. 项目建模：Station、Robot、Tool、Frame、Target、Path、Operation、Program、Report。
2. 工作区：OPFS-like 保存、bundle 导入导出、损坏检测、迁移。
3. 几何和路径：点、边、曲线生成 Path；路径采样和姿态策略。
4. 可达性：单点、批量、路径段、operation。
5. 轨迹：节拍、速度、加速度、采样、重采样、blend 近似。
6. 碰撞：机器人自身、工具、工件、夹具、禁入区的基础碰撞时间点。
7. IO/Wait：脚本、timeout、边沿、trace、报告。
8. 品牌链路：GRL 到三品牌、三品牌导入、交叉品牌再导出。
9. 客户交付：源程序、品牌程序、IO map、校准数据、报告 HTML/PDF、trace、截图。
10. 自动化证据：命令输出、job JSON、report JSON、HTML 页面、截图、PDF。

8. HTML 虚拟控制器需求

8.1 对标范围

对标 ABB RobotStudio 的工作方式，而不是复制视觉资产。公开参考资料包括 ABB RobotStudio Suite 官方页面和 RobotStudio Operating Manual 2026.2。参考点：

1. Station / Graphics：机器人、工具、工件、路径和碰撞对象。
2. Controller：虚拟控制器状态、RobotWare/robot model 信息、权限和运行控制。
3. RAPID / Program Editor：程序树、模块、当前行、诊断、断点。
4. Simulation：播放、暂停、单步、重置、速度倍率、时间轴。
5. Virtual FlexPendant：模式、Motors On、PP to Main、Start、Stop、Hold、Jog、IO、Alarms。

8.2 页面信息架构

首屏必须直接进入工程工作台，不做营销页。

建议 HTML 布局：

1. 顶部命令栏：项目、导入、保存、运行、暂停、停止、单步、导出报告。
2. 左侧对象树：Station、Robot、Tool、Frame、Target、Path、Operation、Program、Reports。
3. 中央工作区：3D/2D station viewport、路径轨迹、机器人姿态、碰撞和选中对象。
4. 右侧虚拟示教器：状态灯、模式、关节/TCP、Jog、速度倍率、程序指针、报警。
5. 底部面板：日志、诊断、IO、Wait、Motion Queue、Trace、报告。
6. 编辑区：GRL/RAPID/FANUC/KUKA 多标签查看，source map 双向定位。

8.3 交互需求

1. 加载 ABB120 测试项目后，页面显示机器人模型、程序树和默认 main 程序。
2. 点击 Run 后，虚拟控制器状态变化，程序指针、motion queue、IO trace 和时间轴同步更新。
3. 点击 Step 时执行单条 IR 指令。
4. 点击 path point 时，编辑器跳转 GRL source map，3D/2D viewport 高亮目标。
5. wait 卡住时，右侧面板显示 wait 条件、当前子表达式值、相关 IO 最近变化、timeout 倒计时和手动置位动作。
6. 后处理导出后，ABB/FANUC/KUKA 代码可在标签页查看并下载。
7. 报告页可打开 HTML 报告，并能导出 PDF 或打印。

8.4 技术边界

1. 首版可以是 HTML + CSS + TypeScript 的静态工作台页面，接入现有 facade 和 runtime。
2. 3D 视图可先使用简化连杆模型；如果引入 Three.js，应验证桌面和移动视口截图非空、机器人正确入框。
3. 不承诺复刻 ABB RobotStudio 的真实 RobotWare、完整 RAPID 解释器、真实安全系统、真实控制器通信。
4. 不复制 ABB 商标、图标、界面皮肤或专有资源。

9. 非目标

1. 不以 FANUC 二进制 TP 为首版输入。
2. 不实现完整 CAD kernel。
3. 不实现品牌控制器 look-ahead 完全复刻。
4. 不将浏览器虚拟控制器声明为真实机器人安全控制器。
5. 不绕过 ABB、FANUC、KUKA 的真实控制器安全、权限和认证流程。