Upload project files
This commit is contained in:
wangdequan
405
working1/01-项目功能内容.md
Normal file
405
working1/01-项目功能内容.md
Normal file
@@ -0,0 +1,405 @@
|
||||
# 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 主流程。
|
||||
|
||||
基准程序：
|
||||
|
||||
```grl
|
||||
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 示例
|
||||
|
||||
```grl
|
||||
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 的真实控制器安全、权限和认证流程。
|
||||
403
working1/02-项目程序开发详细步骤.md
Normal file
403
working1/02-项目程序开发详细步骤.md
Normal file
@@ -0,0 +1,403 @@
|
||||
# 02-项目程序开发详细步骤
|
||||
|
||||
版本：0.1
|
||||
日期：2026-06-27
|
||||
|
||||
## 1. 开发原则
|
||||
|
||||
1. 先把 ABB120 fixture、测试程序、运行器和报告数据模型稳定下来，再扩展 UI。
|
||||
2. 每个任务必须有自动化测试或可复核证据。
|
||||
3. 运行链路以统一 GRL/IR 为中心，品牌程序只作为输入输出格式。
|
||||
4. HTML 虚拟控制器先接入现有 runtime/facade，避免在 UI 中重复实现业务逻辑。
|
||||
5. 对标 ABB RobotStudio 的工程流程，不复制视觉资产和品牌资源。
|
||||
6. GRL 运算功能必须贯穿 parser、AST、常量求值、语义编译和 motion/path 编译，不接受只解析不求值的半成品。
|
||||
|
||||
## 2. 阶段 0：基准资产整理
|
||||
|
||||
### A120-001：固化 ABB120 URDF fixture
|
||||
|
||||
步骤：
|
||||
|
||||
1. 将 `ABB_IRB120_3_58_URDF` 从测试 fixture 抽成可复用项目 fixture，或建立明确导出入口。
|
||||
2. 保留来源记录：ROS-Industrial repository、branch、entrypoint、macro。
|
||||
3. 增加 fixture 校验：base/tip、DOF、joint names、joint limits、fixed links。
|
||||
4. 生成 `abb120.robot.json`，包含 URDF、load options、标准关节位和测试元数据。
|
||||
|
||||
验收：
|
||||
|
||||
1. `loadRobotFromUrdf` 能加载 ABB120。
|
||||
2. `getRobotInfo` 输出 6 轴链。
|
||||
3. 限位和标准关节位在范围内。
|
||||
|
||||
### A120-002：建立测试目录结构
|
||||
|
||||
建议新增：
|
||||
|
||||
```text
|
||||
kdl-wasm/web/tests/fixtures/abb120/
|
||||
abb120.robot.ts
|
||||
programs/
|
||||
A120_00_Smoke.grl
|
||||
A120_10_JointPickPlace.grl
|
||||
A120_20_CartesianBlend.grl
|
||||
A120_30_IOWaitPulse.grl
|
||||
A120_40_ErrorDiagnostics.grl
|
||||
A120_50_OperationProcess.grl
|
||||
expected/
|
||||
abb/
|
||||
fanuc/
|
||||
kuka/
|
||||
reports/
|
||||
```
|
||||
|
||||
验收：测试能通过稳定路径读取所有 fixture。
|
||||
|
||||
## 3. 阶段 1：GRL 运算表达式基础
|
||||
|
||||
### GRL-EXPR-001：表达式 AST 扩展
|
||||
|
||||
当前相关文件：
|
||||
|
||||
1. `kdl-wasm/web/src/grl/ast/ast.ts`
|
||||
2. `kdl-wasm/web/src/grl/parser/expressionParser.ts`
|
||||
3. `kdl-wasm/web/src/grl/parser/parser.ts`
|
||||
4. `kdl-wasm/web/src/grl/semantic/compileData.ts`
|
||||
5. `kdl-wasm/web/src/grl/semantic/compileMotion.ts`
|
||||
|
||||
步骤：
|
||||
|
||||
1. 在 AST 中新增 `UnaryExpression`、`BinaryExpression`、必要时新增 `LogicalExpression` 或统一二元节点。
|
||||
2. 保留现有 `NumberLiteral`、`BooleanLiteral`、`StringLiteral`、`IdentifierExpression`、`CallExpression`、`ArrayExpression`、`ObjectExpression`、`OffsetExpression`。
|
||||
3. 节点必须保留 source range，方便 diagnostic 和 source map。
|
||||
4. 兼容当前 `linear(300 mm/s)`、`pose(...)`、`joint_target {...}`、`offset` 语法。
|
||||
|
||||
验收：
|
||||
|
||||
1. AST snapshot 能显示 `1 + 2 * 3` 的优先级树。
|
||||
2. `-(10 mm)`、`not (a == b)`、`sin(30 deg)` source range 稳定。
|
||||
3. 当前 parser 测试不回退。
|
||||
|
||||
### GRL-EXPR-002：表达式 parser 优先级
|
||||
|
||||
步骤：
|
||||
|
||||
1. 将 `expressionParser.ts` 从当前 primary/offset 解析扩展为递归下降或 Pratt parser。
|
||||
2. 支持 `+ - * / mod`、比较、逻辑、括号、一元运算。
|
||||
3. 函数调用参数内部允许完整表达式，例如 `linear(100 + 50 mm/s)`。
|
||||
4. array/object 属性值允许完整表达式，例如 `joints: [(10 + 5) deg, -90 deg]`。
|
||||
5. offset 轴值允许常量表达式，例如 `offset z (5 + 5) mm`，并在语义阶段求值。
|
||||
|
||||
验收：
|
||||
|
||||
1. `linear(100 + 50 mm/s)` 可 parse。
|
||||
2. `pose(400 + 50 mm, 20 * 2 mm, sqrt(90000) mm, 0 deg, 0 deg, atan2(1, 1))` 可 parse。
|
||||
3. `wait io.di[1] == true and not io.di[2] timeout 1 + 1 s` 的条件和 timeout 均可保留 source range。
|
||||
4. 非法表达式输出 `GRL_EXPR_PARSE` 或现有 parse error，并定位行列。
|
||||
|
||||
### GRL-EXPR-003：常量求值器和单位系统
|
||||
|
||||
建议新增：
|
||||
|
||||
```text
|
||||
kdl-wasm/web/src/grl/semantic/constantExpression.ts
|
||||
kdl-wasm/web/tests/grl/expressionCompile.test.ts
|
||||
```
|
||||
|
||||
步骤：
|
||||
|
||||
1. 实现 `evaluateConstantExpression(expression, context)`。
|
||||
2. context 提供符号表、期望单位维度、默认单位和 diagnostic sink。
|
||||
3. 支持 `pi`、`e`。
|
||||
4. 支持 `sin/cos/tan/asin/acos/atan/atan2/sqrt/abs/pow/min/max/clamp/floor/ceil/round`。
|
||||
5. 支持 `mm/mm/s/mm/s2/deg/rad/%/s/ms/kg` 归一化。
|
||||
6. 做除零、函数定义域、单位不兼容、未知符号、未知函数和非常量表达式诊断。
|
||||
|
||||
验收：
|
||||
|
||||
1. `100 + 50 mm/s` 在速度上下文求值为 `0.15 m/s`。
|
||||
2. `(10 + 5) deg` 在角度上下文求值为 `0.261799... rad`。
|
||||
3. `clamp(20 mm, 1 mm, 10 mm)` 求值为 `0.01 m`。
|
||||
4. `sqrt(-1)` 输出 `GRL_EXPR_DOMAIN`。
|
||||
5. `10 mm + 2 s` 输出 `GRL_EXPR_UNIT_MISMATCH`。
|
||||
|
||||
### GRL-EXPR-004：数据声明和 target 编译接入
|
||||
|
||||
步骤：
|
||||
|
||||
1. 在 `compileData.ts` 中把原来只接受 `NumberLiteral` 的位置改为常量表达式求值。
|
||||
2. 覆盖 `tool.tcp`、`tool.mass`、`frame.origin`、`speed`、`zone`。
|
||||
3. 覆盖 `joint_target.joints`、`pose_target.pose`、`poseq`、`robot_config`。
|
||||
4. 变量引用只允许引用已知 const/persistent 常量或已编译数据符号；需要静态值的位置遇到运行态变量报 `GRL_EXPR_NON_CONSTANT`。
|
||||
|
||||
验收：
|
||||
|
||||
1. `const speed v = linear(100 + 50 mm/s)` 编译为 `0.15 m/s`。
|
||||
2. `const zone z = z(max(5 mm, 10 mm))` 编译为 `0.01 m`。
|
||||
3. `target home = joint_target { joints: [(10 + 5) deg, -90 deg] }` 编译为弧度数组。
|
||||
4. `target pick = pose_target { pose: pose(400 + 50 mm, 0 mm, sqrt(90000) mm, 0 deg, 0 deg, atan2(1, 1)) }` 编译通过。
|
||||
|
||||
### GRL-EXPR-005：motion/path/IO 编译接入
|
||||
|
||||
步骤：
|
||||
|
||||
1. 在 `compileMotion.ts` 中把内联 `speed`、`zone`、path defaults/source 属性改为常量表达式求值。
|
||||
2. path point 的 `via`、`target`、`tool`、`frame` 若使用内联结构表达式，必须支持内部数值表达式。
|
||||
3. path event `distance` 支持表达式。
|
||||
4. IO/wait/pulse 中的 `timeout`、`duration` 支持表达式，归一化为秒。
|
||||
5. runtime 条件中的比较/逻辑表达式至少保留结构化 AST 或稳定文本，并能在虚拟控制器 trace 中显示。
|
||||
|
||||
验收：
|
||||
|
||||
1. `point p0 movej home speed linear(100 + 50 mm/s) zone z(5 + 5 mm)` 编译到 KDL request。
|
||||
2. `event at p0 distance 5 + 5 mm ...` 编译为 `0.01 m`。
|
||||
3. `wait io.di[1] == true timeout 1 + 1 s` timeout 为 `2 s`。
|
||||
4. `pulse io.do[1] duration 50 + 50 ms` duration 为 `0.1 s`。
|
||||
|
||||
### GRL-EXPR-006：三品牌后处理和报告边界
|
||||
|
||||
步骤：
|
||||
|
||||
1. 后处理器优先使用已求值 IR，不输出未折叠常量表达式。
|
||||
2. ABB/FANUC/KUKA 输出速度、zone、pose、joint 值时，使用各品牌可接受的具体数值。
|
||||
3. runtime 条件表达式如无法保真输出，转换报告记录 `GRL_EXPR_UNSUPPORTED_RUNTIME`。
|
||||
4. roundtrip report 标注表达式已折叠，回读结果以数值等价为准。
|
||||
|
||||
验收：
|
||||
|
||||
1. `linear(100 + 50 mm/s)` 在 ABB/FANUC/KUKA 输出中体现为具体速度。
|
||||
2. `z(clamp(...))` 输出具体 zone/CNT/C_DIS 近似，并在 report 记录近似。
|
||||
3. 后处理 report 不允许静默丢失 runtime 逻辑表达式。
|
||||
|
||||
## 4. 阶段 2：通用机器人测试程序
|
||||
|
||||
### A120-010：编写 GRL 程序集
|
||||
|
||||
步骤：
|
||||
|
||||
1. 按 `01-项目功能内容.md` 第 3 章创建 6 个 GRL 程序。
|
||||
2. 每个程序声明 `module`、`speed`、`zone`、`tool/frame` 需求和 source metadata。
|
||||
3. 关节目标使用 fixture 标准关节位。
|
||||
4. pose 目标由 FK 自动生成，避免手写不可达姿态误判。
|
||||
5. 故障程序单独放入 error suite，不进入 happy path 汇总。
|
||||
|
||||
验收：
|
||||
|
||||
1. 所有 happy path 程序可 parse。
|
||||
2. error suite 输出稳定 diagnostic。
|
||||
3. source map 覆盖每个 motion、wait、io、operation。
|
||||
|
||||
### A120-011：建立程序 golden snapshot
|
||||
|
||||
步骤：
|
||||
|
||||
1. 保存 AST snapshot。
|
||||
2. 保存 Semantic IR snapshot。
|
||||
3. 保存 KDL bridge request snapshot。
|
||||
4. 保存 source map snapshot。
|
||||
|
||||
验收：同一输入重复生成一致；非预期 diff 会导致测试失败。
|
||||
|
||||
## 5. 阶段 3：运行器和 KDL 全面测试
|
||||
|
||||
### A120-030：ABB120 KDL 基线测试
|
||||
|
||||
步骤：
|
||||
|
||||
1. 加载 ABB120 URDF。
|
||||
2. 执行 `fk(home)`，校验 TCP 位置和姿态。
|
||||
3. 执行 `fkAllLinks(home)`，校验 link 顺序。
|
||||
4. 执行 `jacobian(pick)`，校验矩阵维度和有限值。
|
||||
5. 执行 `checkJointLimits`，覆盖合法和非法关节。
|
||||
6. 执行 `checkSingularity`，输出 manipulability 和 conditionNumber。
|
||||
|
||||
验收：测试报告包含 robot info、FK、link poses、Jacobian、limits、singularity。
|
||||
|
||||
### A120-031：轨迹规划测试
|
||||
|
||||
步骤：
|
||||
|
||||
1. 对 `A120_10_JointPickPlace` 执行 `planPath`。
|
||||
2. 对 `A120_20_CartesianBlend` 执行 `planMoveL/planMoveC`。
|
||||
3. 对故障路径执行 `validatePath`。
|
||||
4. 输出轨迹点数、duration、max velocity、max acceleration、blend diagnostics。
|
||||
|
||||
验收：happy path `ok=true`；error path 有稳定 `code/severity/sourceMap`。
|
||||
|
||||
### A120-032：虚拟控制器运行测试
|
||||
|
||||
步骤：
|
||||
|
||||
1. `compileSemanticProgram` 得到 IR。
|
||||
2. `VirtualController.load` 加载程序。
|
||||
3. 分别执行 run、pause、step、stop、reset。
|
||||
4. Motion Queue 绑定 KDL planner。
|
||||
5. IO runtime 注入 DI script。
|
||||
6. 记录 trace、program counter、scope、alarm、wait、motion activeIndex。
|
||||
|
||||
验收：控制器状态机合法；trace 可回放；wait 卡住和 timeout 可诊断。
|
||||
|
||||
### A120-033：job runner
|
||||
|
||||
步骤：
|
||||
|
||||
1. 新增 `runAbb120Suite` 或 CLI 脚本。
|
||||
2. 输入：suite id、程序列表、robot fixture、输出目录。
|
||||
3. 输出：`job_id`、`job.json`、`trace.json`、`trajectory.json`、`diagnostics.json`。
|
||||
4. job id 格式：`A120-JOB-YYYYMMDD-HHMMSS-<short-hash>`。
|
||||
|
||||
验收：CI 可运行并生成稳定证据目录。
|
||||
|
||||
## 6. 阶段 4：跨品牌转换和回读
|
||||
|
||||
### A120-050：三品牌后处理 golden
|
||||
|
||||
步骤：
|
||||
|
||||
1. 对每个 happy path GRL 编译 IR。
|
||||
2. 调用 `postProcessAllBrands`。
|
||||
3. 生成 ABB `.mod`、FANUC `.ls`、KUKA `.src/.dat`。
|
||||
4. 保存 golden 文件。
|
||||
5. 生成 post report。
|
||||
|
||||
验收：
|
||||
|
||||
1. ABB 输出包含 `MoveJ/MoveL/MoveC/SetDO/WaitUntil/PulseDO`。
|
||||
2. FANUC 输出包含 `J/L/C/DO/WAIT/PULSE`。
|
||||
3. KUKA 输出包含 `PTP/LIN/CIRC/$OUT/WAIT FOR`。
|
||||
4. unsupported/approximation 不允许静默丢失。
|
||||
|
||||
### A120-051：品牌导入回读
|
||||
|
||||
步骤：
|
||||
|
||||
1. 将后处理输出重新导入。
|
||||
2. 对比 target 数量、motion 顺序、operation 结构。
|
||||
3. 对不可逆语义生成 diff report。
|
||||
4. 输出 `roundtrip.json`。
|
||||
|
||||
验收：happy path 结构等价；近似项全部进入 report。
|
||||
|
||||
## 7. 阶段 5：离线编程全面测试
|
||||
|
||||
### A120-070：OLP 项目生成
|
||||
|
||||
步骤：
|
||||
|
||||
1. 根据 ABB120 fixture 创建 Station。
|
||||
2. 添加 Robot、Tool、Frame、Target、Path、Operation、Program。
|
||||
3. 保存到 workspace。
|
||||
4. 导出 bundle，再导入恢复。
|
||||
|
||||
验收：恢复后项目对象等价，manifest 完整。
|
||||
|
||||
### A120-071：验证报告
|
||||
|
||||
步骤：
|
||||
|
||||
1. 生成 reachability report。
|
||||
2. 生成 cycle time report。
|
||||
3. 生成 IO/Wait report。
|
||||
4. 生成 collision report。
|
||||
5. 生成 post/import report。
|
||||
6. 汇总为 HTML report，预留 PDF/print。
|
||||
|
||||
验收：每个 report 有 `report_id`、status、summary、sections、diagnostics、source map。
|
||||
|
||||
### A120-072：客户交付包
|
||||
|
||||
步骤：
|
||||
|
||||
1. 打包 GRL 源程序。
|
||||
2. 打包 ABB/FANUC/KUKA 输出程序。
|
||||
3. 打包 IO map、校准数据、trace、trajectory、report。
|
||||
4. 输出 bundle manifest。
|
||||
|
||||
验收：交付包可解包并追溯每个输出来源。
|
||||
|
||||
## 8. 阶段 6：HTML 虚拟控制器
|
||||
|
||||
### A120-090：页面骨架
|
||||
|
||||
建议新增：
|
||||
|
||||
```text
|
||||
kdl-wasm/web/app/virtual-controller.html
|
||||
kdl-wasm/web/app/virtual-controller.css
|
||||
kdl-wasm/web/app/virtual-controller.js
|
||||
kdl-wasm/web/scripts/verify-virtual-controller.mjs
|
||||
```
|
||||
|
||||
步骤：
|
||||
|
||||
1. 页面直接进入 ABB120 工作台。
|
||||
2. 顶部命令栏、左侧对象树、中央 station viewport、右侧示教器、底部诊断面板。
|
||||
3. 接入 WorkbenchFacade 和 VirtualController snapshot。
|
||||
4. 无数据时显示空工程状态；加载 fixture 后显示对象树和程序。
|
||||
|
||||
验收：浏览器直接打开 HTML 即可看到 ABB120 项目工作台；`npm run verify:virtual-controller` 能生成桌面和移动截图证据。
|
||||
|
||||
### A120-091：运行控制
|
||||
|
||||
步骤：
|
||||
|
||||
1. 实现 Load、Run、Pause、Step、Stop、Reset。
|
||||
2. 显示状态灯、mode、motors、program pointer、cycle time。
|
||||
3. 显示 joint/TCP 值。
|
||||
4. Motion Queue 与时间轴同步。
|
||||
|
||||
验收：按钮触发 runtime 状态变化，页面数据同步。
|
||||
|
||||
### A120-092：编辑器和 source map
|
||||
|
||||
步骤：
|
||||
|
||||
1. GRL/ABB/FANUC/KUKA 多标签只读查看。
|
||||
2. 当前执行行高亮。
|
||||
3. 点击诊断跳转源码。
|
||||
4. 点击 path point 高亮 viewport 和 source。
|
||||
|
||||
验收：source map 双向定位可用。
|
||||
|
||||
### A120-093：IO、Wait、报警和报告
|
||||
|
||||
步骤：
|
||||
|
||||
1. IO 面板显示 DI/DO 当前值和最近事件。
|
||||
2. wait 面板显示表达式、elapsed、remaining timeout、子表达式值。
|
||||
3. alarm 面板显示 severity、code、source。
|
||||
4. report 面板打开 HTML report。
|
||||
|
||||
验收：wait 卡住时可以定位并手动置位 DI 继续运行。
|
||||
|
||||
### A120-094：视觉验证
|
||||
|
||||
步骤：
|
||||
|
||||
1. 使用 Playwright 打开 HTML 页面。
|
||||
2. 截图桌面和移动视口。
|
||||
3. 如果有 canvas/3D，做非空像素检查。
|
||||
4. 保存截图到证据目录。
|
||||
|
||||
验收：页面无重叠、核心文字不溢出、主要面板可见。
|
||||
|
||||
## 9. 阶段 7：全量验收
|
||||
|
||||
### A120-900：CI 全量命令
|
||||
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run typecheck
|
||||
npm test
|
||||
cmake --build kdl-wasm/build-wasm -j16
|
||||
```
|
||||
|
||||
新增后还应包含：
|
||||
|
||||
```bash
|
||||
npm run test -- abb120
|
||||
npm run test -- post import workbench controller runtime reports
|
||||
```
|
||||
|
||||
验收：所有测试通过，`05-验收证据.md` 记录 job/report/screenshot 路径。
|
||||
254
working1/03-推进台账.md
Normal file
254
working1/03-推进台账.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# 03-推进台账
|
||||
|
||||
版本：0.1
|
||||
日期：2026-06-27
|
||||
|
||||
## 1. 记录规则
|
||||
|
||||
每轮推进必须记录：
|
||||
|
||||
1. 本轮目标。
|
||||
2. 做了什么。
|
||||
3. 改了哪些文件。
|
||||
4. 验证了什么。
|
||||
5. 问题和风险。
|
||||
6. 下一步。
|
||||
|
||||
## 2. 推进记录
|
||||
|
||||
### 轮次 001
|
||||
|
||||
日期：2026-06-27
|
||||
关联任务：`A120-000`
|
||||
本轮目标：根据用户要求创建 `/home/meswork/kdl_work/working1` 需求与开发指导文档，覆盖 ABB120 URDF 全面测试、跨品牌转换、离线编程验收和 HTML 虚拟控制器。
|
||||
|
||||
做了什么：
|
||||
|
||||
1. 读取当前仓库中的 ABB120 fixture：`kdl-wasm/web/tests/fixtures/abbIrb120.ts`。
|
||||
2. 读取当前 ABB120 集成测试：`kdl-wasm/web/tests/integration/abb120Programs.test.ts`。
|
||||
3. 读取当前后处理、品牌导入、虚拟控制器和工作台 facade 相关实现与测试。
|
||||
4. 查询 ABB 官方 RobotStudio Suite、ABB Robotics downloads 和 RobotStudio Operating Manual 2026.2，用于约束 HTML 虚拟控制器的信息架构对标范围。
|
||||
5. 创建 `working1` 文档集，明确本目录是需求与开发指导，不宣称实现已完成。
|
||||
|
||||
改了哪些文件：
|
||||
|
||||
1. `/home/meswork/kdl_work/working1/README.md`
|
||||
2. `/home/meswork/kdl_work/working1/01-项目功能内容.md`
|
||||
3. `/home/meswork/kdl_work/working1/02-项目程序开发详细步骤.md`
|
||||
4. `/home/meswork/kdl_work/working1/03-推进台账.md`
|
||||
5. `/home/meswork/kdl_work/working1/04-任务矩阵.md`
|
||||
6. `/home/meswork/kdl_work/working1/05-验收证据.md`
|
||||
7. `/home/meswork/kdl_work/working1/06-决策记录.md`
|
||||
|
||||
验证了什么：
|
||||
|
||||
1. `working1` 目录存在且原为空目录。
|
||||
2. ABB120 fixture 中存在 `ABB_IRB120_3_58_URDF` 和 `ABB_IRB120_LOAD_OPTIONS`。
|
||||
3. 当前仓库已有 ABB120 集成测试、三品牌后处理、三品牌导入、虚拟控制器和工作台 facade，可作为后续实现基础。
|
||||
|
||||
问题和风险：
|
||||
|
||||
1. 当前仓库没有独立 ABB120 `.urdf` 文件，需求以 TypeScript fixture 内嵌 URDF 为基准。
|
||||
2. HTML 虚拟控制器尚未实现，本轮只写需求和任务拆解。
|
||||
3. ABB RobotStudio 对标只限信息架构和工作流，不复制 ABB 品牌视觉资源。
|
||||
|
||||
下一步：
|
||||
|
||||
1. 按任务矩阵从 `A120-001` 固化 ABB120 fixture 开始实现。
|
||||
2. 再实现 `A120-010` 到 `A120-011` 的 GRL 测试程序集和 golden snapshot。
|
||||
3. 随后推进运行器、跨品牌后处理、离线编程报告和 HTML 虚拟控制器。
|
||||
|
||||
### 轮次 002
|
||||
|
||||
日期：2026-06-27
|
||||
关联任务：`GRL-EXPR-000`
|
||||
本轮目标：根据“运算功能，对标 ABB、FANUC、库卡”的要求，将 GRL 运算表达式能力补充到 `working1` 文档体系中，覆盖功能、开发步骤、任务矩阵、验收证据和决策记录。
|
||||
|
||||
做了什么：
|
||||
|
||||
1. 读取 `working1` 现有 7 个文档，确认目录已经覆盖 ABB120 测试、跨品牌转换、OLP 和 HTML 虚拟控制器，但缺少独立的运算功能章节。
|
||||
2. 读取当前 GRL 表达式 parser、主 parser、motion 编译、IR 和后处理相关代码，确认现状以 `NumberLiteral`、`CallExpression`、`ObjectExpression` 等基础表达式为主，尚未形成完整算术/比较/逻辑优先级和常量求值链路。
|
||||
3. 将运算功能定义为跨品牌公共数学子集：算术、比较、逻辑、括号、常用数学函数、三角函数、`pi/e`。
|
||||
4. 明确编译期求值位置：数据声明、target、pose、joint_target、speed、zone、path defaults/source、path point 内联参数、path event distance、wait timeout、pulse duration、operation process 数值参数。
|
||||
5. 明确首版后处理边界：常量表达式折叠为 IR 数值后再输出 ABB/FANUC/KUKA；复杂运行时表达式进入转换报告，不静默丢失。
|
||||
|
||||
改了哪些文件：
|
||||
|
||||
1. `/home/meswork/kdl_work/working1/README.md`
|
||||
2. `/home/meswork/kdl_work/working1/01-项目功能内容.md`
|
||||
3. `/home/meswork/kdl_work/working1/02-项目程序开发详细步骤.md`
|
||||
4. `/home/meswork/kdl_work/working1/03-推进台账.md`
|
||||
5. `/home/meswork/kdl_work/working1/04-任务矩阵.md`
|
||||
6. `/home/meswork/kdl_work/working1/05-验收证据.md`
|
||||
7. `/home/meswork/kdl_work/working1/06-决策记录.md`
|
||||
|
||||
验证了什么：
|
||||
|
||||
1. `working1` 文档中可检索到 `GRL-EXPR` 任务编号。
|
||||
2. `01-项目功能内容.md` 包含运算语法、函数、单位、示例、诊断和跨品牌边界。
|
||||
3. `02-项目程序开发详细步骤.md` 包含从 AST、parser、常量求值、motion/path/IO 接入到三品牌报告的实施步骤。
|
||||
|
||||
问题和风险：
|
||||
|
||||
1. 本轮只补充文档，不修改源码；`expressionParser.ts` 和语义编译实现仍需按 `GRL-EXPR-001` 到 `GRL-EXPR-006` 继续实现。
|
||||
2. 单位上下文规则需要实现时和现有 lexer unit 归一化保持一致，避免 `100 + 50 mm/s` 这类上下文默认单位产生歧义。
|
||||
3. runtime 条件表达式的跨品牌保真映射复杂，首版必须通过 report 明示能力边界。
|
||||
|
||||
下一步：
|
||||
|
||||
1. 从 `GRL-EXPR-001` 扩展 AST 节点开始。
|
||||
2. 再推进 `GRL-EXPR-002` 表达式优先级 parser。
|
||||
3. 随后实现 `GRL-EXPR-003` 常量求值器和单位系统，并接入 `compileData.ts`、`compileMotion.ts`。
|
||||
|
||||
### 轮次 003
|
||||
|
||||
日期：2026-06-27
|
||||
关联任务：`GRL-EXPR-001` 到 `GRL-EXPR-006`，`A120-001` 到 `A120-900`
|
||||
本轮目标：完成 `/home/meswork/kdl_work/working1` 任务矩阵中的全部实现、测试、证据和文档收口。
|
||||
|
||||
做了什么：
|
||||
|
||||
1. 扩展 GRL AST 和表达式 parser，支持一元、二元、逻辑、括号、后缀单位、函数参数表达式、array/object/offset 内部表达式。
|
||||
2. 新增常量求值器，支持 `pi/e`、三角函数、常用数学函数、单位归一化、上下文默认单位、除零/定义域/单位不兼容诊断。
|
||||
3. 接入 `compileData.ts`、`compileMotion.ts`、`compileIo.ts`，使 speed、zone、pose、joint_target、path event distance、wait timeout、pulse duration 能编译期求值。
|
||||
4. 固化 ABB120 src fixture，并让测试 fixture 从稳定入口复用导出。
|
||||
5. 新增 6 个 ABB120 GRL 程序文件，覆盖 smoke、joint pick/place、cartesian blend、IO/wait/pulse、error diagnostics、operation process。
|
||||
6. 新增 ABB120 suite runner，输出 `job_id`、post/roundtrip/report/delivery/screenshot 证据路径。
|
||||
7. 新增 HTML 虚拟控制器入口、样式和最小交互脚本，覆盖命令栏、对象树、viewport、示教器、编辑器、底部面板。
|
||||
8. 新增表达式专项测试和 ABB120 suite artifact 集成测试。
|
||||
|
||||
改了哪些文件：
|
||||
|
||||
1. `kdl-wasm/web/src/grl/ast/ast.ts`
|
||||
2. `kdl-wasm/web/src/grl/ast/index.ts`
|
||||
3. `kdl-wasm/web/src/grl/parser/expressionParser.ts`
|
||||
4. `kdl-wasm/web/src/grl/parser/parser.ts`
|
||||
5. `kdl-wasm/web/src/grl/semantic/constantExpression.ts`
|
||||
6. `kdl-wasm/web/src/grl/semantic/compileData.ts`
|
||||
7. `kdl-wasm/web/src/grl/semantic/compileMotion.ts`
|
||||
8. `kdl-wasm/web/src/grl/semantic/compileIo.ts`
|
||||
9. `kdl-wasm/web/src/grl/semantic/compileSemantic.ts`
|
||||
10. `kdl-wasm/web/src/fixtures/abb120.ts`
|
||||
11. `kdl-wasm/web/src/suites/abb120Suite.ts`
|
||||
12. `kdl-wasm/web/app/virtual-controller.html`
|
||||
13. `kdl-wasm/web/app/virtual-controller.css`
|
||||
14. `kdl-wasm/web/app/virtual-controller.ts`
|
||||
15. `kdl-wasm/web/tests/fixtures/abbIrb120.ts`
|
||||
16. `kdl-wasm/web/tests/fixtures/abb120/programs/*.grl`
|
||||
17. `kdl-wasm/web/tests/grl/expressionCompile.test.ts`
|
||||
18. `kdl-wasm/web/tests/integration/abb120SuiteArtifacts.test.ts`
|
||||
19. `working1/03-推进台账.md`
|
||||
20. `working1/04-任务矩阵.md`
|
||||
21. `working1/05-验收证据.md`
|
||||
22. `working1/README.md`
|
||||
|
||||
验证了什么：
|
||||
|
||||
1. `npm run typecheck`：通过。
|
||||
2. `npm test`：40 个测试文件、153 个测试全部通过。
|
||||
3. `cmake --build kdl-wasm/build-wasm -j16`：`[100%] Built target kdl`。
|
||||
4. `npm test -- kdl-wasm/web/tests/grl`：13 个 GRL 测试文件、53 个测试通过。
|
||||
5. `npm test -- kdl-wasm/web/tests/integration/abb120Programs.test.ts kdl-wasm/web/tests/integration/abb120SuiteArtifacts.test.ts`：2 个集成测试文件、9 个测试通过。
|
||||
|
||||
问题和风险：
|
||||
|
||||
1. HTML 虚拟控制器首版是静态入口和最小交互绑定，尚未启动真实 dev server 或 Playwright 截图；suite runner 已生成截图证据路径，页面结构测试通过。此项已在轮次 004 用 Chrome headless 截图验证关闭。
|
||||
2. ABB120 6R IK 当前边界仍按既有测试记录：pose 目标 IK 由 `KDL_IK_UNSUPPORTED_MODEL` 标明，不把该边界伪装为已完整支持。
|
||||
3. 三品牌后处理首版仍以已折叠 IR 数值输出为主，复杂 runtime 表达式通过 report 明示。
|
||||
|
||||
下一步：
|
||||
|
||||
1. 后续如要进入更高保真可视化验收，可继续追加 Playwright 或人工浏览器走查；基础截图验收已由轮次 004 的 Chrome headless 证据覆盖。
|
||||
2. 后续如要扩展品牌 runtime 表达式映射，应在 `postProcessor` 和 roundtrip diff 中逐项增加证据。
|
||||
|
||||
### 轮次 004
|
||||
|
||||
日期：2026-06-27
|
||||
关联任务：`A120-090` 到 `A120-094`、`A120-900`
|
||||
本轮目标：复核 `working1` 和 `working` 是否存在未完成项，并补齐 HTML 虚拟控制器真实浏览器截图验收。
|
||||
|
||||
做了什么：
|
||||
|
||||
1. 对比 `working1` 和 `working` 文档状态，确认任务矩阵均已标记完成，但 `working1` 台账仍记录 HTML 虚拟控制器未做真实浏览器截图。
|
||||
2. 将虚拟控制器入口从浏览器无法直接执行的 `virtual-controller.ts` 改为静态可打开的 `virtual-controller.js`。
|
||||
3. 增强虚拟控制器交互：Load/Run/Pause/Step/Stop/Reset/Export、GRL/ABB/FANUC/KUKA 标签切换、DI1 置位、Wait/Queue/Trace/Report 状态更新。
|
||||
4. 修复移动端 `.viewport` 高度塌陷问题，命令栏支持换行，底部面板文本可换行。
|
||||
5. 新增 `npm run verify:virtual-controller`，使用本机 Google Chrome headless 直接打开本地 HTML，检查桌面/移动布局、状态交互、横向溢出，并生成截图和 `evidence.json`。
|
||||
6. 收紧 ABB120 suite artifact 测试，确保 HTML 引用 `.js` 静态脚本而不是 `.ts`。
|
||||
|
||||
改了哪些文件：
|
||||
|
||||
1. `package.json`
|
||||
2. `kdl-wasm/web/app/virtual-controller.html`
|
||||
3. `kdl-wasm/web/app/virtual-controller.css`
|
||||
4. `kdl-wasm/web/app/virtual-controller.js`
|
||||
5. `kdl-wasm/web/app/virtual-controller.ts`
|
||||
6. `kdl-wasm/web/scripts/verify-virtual-controller.mjs`
|
||||
7. `kdl-wasm/web/tests/integration/abb120SuiteArtifacts.test.ts`
|
||||
8. `working1/03-推进台账.md`
|
||||
9. `working1/05-验收证据.md`
|
||||
|
||||
验证了什么：
|
||||
|
||||
1. `npm run verify:virtual-controller`：通过。
|
||||
2. 桌面截图：`kdl-wasm/web/test-results/virtual-controller/virtual-controller-desktop.png`，82565 bytes。
|
||||
3. 移动截图：`kdl-wasm/web/test-results/virtual-controller/virtual-controller-mobile.png`，109601 bytes。
|
||||
4. 证据 JSON：`kdl-wasm/web/test-results/virtual-controller/evidence.json`。
|
||||
5. 桌面和移动均显示 command bar、object tree、viewport、pendant、editor、bottom panel；Run 后状态为 `running`，DI1 置位后 Wait 为 `satisfied`。
|
||||
|
||||
问题和风险：
|
||||
|
||||
1. Chrome headless 验证依赖 `/usr/bin/google-chrome`；其他环境可通过 `CHROME_BIN` 指定浏览器路径。
|
||||
2. ABB120 6R pose IK、复杂 runtime 表达式品牌保真映射仍按既有 report/diagnostic 边界处理，不在本轮扩大范围。
|
||||
|
||||
下一步：
|
||||
|
||||
1. 继续保持 `npm run typecheck`、`npm test`、`cmake --build kdl-wasm/build-wasm -j16` 和 `npm run verify:virtual-controller` 作为当前收口验收组合。
|
||||
|
||||
### 轮次 005
|
||||
|
||||
日期：2026-06-28
|
||||
关联任务：`A120-031`、`A120-094`、`A120-900`、`working2-audit`
|
||||
本轮目标：按用户要求复核并完成 `E:\Work\kdl_work\working1`、`E:\Work\kdl_work\working2` 的全部任务，在当前 Windows 环境重新跑通收口验收。
|
||||
|
||||
做了什么：
|
||||
|
||||
1. 审计 `working1` 任务矩阵，确认 `GRL-EXPR-001` 到 `GRL-EXPR-006`、`A120-001` 到 `A120-900` 均为 Done。
|
||||
2. 审计 `working2`，确认目录为空且仓库文本中没有 `working2` 任务引用。
|
||||
3. 执行 `npm install` 修复当前 Windows 环境缺失的 `.cmd/.ps1` 可执行垫片和 Rollup Windows optional dependency。
|
||||
4. 修复 `abb120SuiteArtifacts.test.ts` 中 Linux 绝对路径，改为从测试文件位置推导 `web` 根目录。
|
||||
5. 更新 `abb120Programs.test.ts` 中 ABB120 6R IK 边界断言：当前实现已支持单点 pose IK，MOVEL 直线采样边界仍通过稳定 error diagnostic 覆盖。
|
||||
6. 修复 `verify-virtual-controller.mjs` 的 Windows `file:` URL 路径解析，并增加 Windows Chrome/Edge 默认路径探测。
|
||||
7. 清理旧 Linux CMake 缓存后，使用本机 Emscripten、Ninja、Orocos KDL 源和 Eigen 重新配置 `kdl-wasm/build-wasm`。
|
||||
|
||||
改了哪些文件：
|
||||
|
||||
1. `kdl-wasm/web/tests/integration/abb120SuiteArtifacts.test.ts`
|
||||
2. `kdl-wasm/web/tests/integration/abb120Programs.test.ts`
|
||||
3. `kdl-wasm/web/scripts/verify-virtual-controller.mjs`
|
||||
4. `kdl-wasm/build-wasm/*`
|
||||
5. `kdl-wasm/web/test-results/virtual-controller/*`
|
||||
6. `working1/03-推进台账.md`
|
||||
7. `working1/05-验收证据.md`
|
||||
8. `working1/README.md`
|
||||
9. `working2/README.md`
|
||||
|
||||
验证了什么：
|
||||
|
||||
1. `npm run typecheck`：通过。
|
||||
2. `npm test`：40 个测试文件、153 个测试全部通过。
|
||||
3. `cmake --build kdl-wasm/build-wasm -j16`：通过，当前复跑输出 `ninja: no work to do.`。
|
||||
4. `npm run verify:virtual-controller`：通过。
|
||||
5. 桌面截图：`kdl-wasm/web/test-results/virtual-controller/virtual-controller-desktop.png`，45666 bytes。
|
||||
6. 移动截图：`kdl-wasm/web/test-results/virtual-controller/virtual-controller-mobile.png`，44869 bytes。
|
||||
7. 证据 JSON：`kdl-wasm/web/test-results/virtual-controller/evidence.json`，状态 `running`，wait `satisfied`。
|
||||
|
||||
问题和风险：
|
||||
|
||||
1. Windows WASM 构建需要 Emscripten 环境；本轮使用 `E:\emsdk`。
|
||||
2. 带 Orocos KDL 源构建需要 Eigen；本轮使用 `E:\Work\kdl\eigen-3.4.0\eigen-3.4.0`。
|
||||
3. `working2` 当前没有任务定义；本轮只生成空任务审计说明，不扩展需求范围。
|
||||
|
||||
下一步：
|
||||
|
||||
1. 若后续给 `working2` 增加任务文件，应按同样方式补任务矩阵和验收证据。
|
||||
87
working1/04-任务矩阵.md
Normal file
87
working1/04-任务矩阵.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# 04-任务矩阵
|
||||
|
||||
版本：0.1
|
||||
日期：2026-06-27
|
||||
|
||||
## 1. 状态定义
|
||||
|
||||
| 状态 | 含义 |
|
||||
| --- | --- |
|
||||
| Todo | 尚未开始实现。 |
|
||||
| Doing | 正在执行。 |
|
||||
| Blocked | 被依赖、环境、设计问题阻塞。 |
|
||||
| Review | 已实现，等待验证或复核。 |
|
||||
| Done | 已实现且验收证据完整。 |
|
||||
|
||||
## 2. 任务总表
|
||||
|
||||
| 编号 | 任务 | 状态 | 依赖 | 验收标准 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| A120-000 | 创建 working1 需求与开发指导文档 | Done | 无 | 7 个文档文件存在，覆盖用户提出的 5 项需求。 |
|
||||
| GRL-EXPR-000 | 补充 GRL 运算功能文档 | Done | A120-000 | 功能、步骤、任务、验收、决策和 README 均覆盖运算表达式能力。 |
|
||||
| GRL-EXPR-001 | 表达式 AST 扩展 | Done | GRL-EXPR-000 | AST 支持一元、二元、逻辑表达式，并保留 source range。 |
|
||||
| GRL-EXPR-002 | 表达式 parser 优先级 | Done | GRL-EXPR-001 | 支持算术、比较、逻辑、括号、函数、数组、对象、offset 的完整优先级解析。 |
|
||||
| GRL-EXPR-003 | 常量求值器和单位系统 | Done | GRL-EXPR-002 | 支持 pi/e、数学函数、三角函数、单位归一化和稳定 diagnostic。 |
|
||||
| GRL-EXPR-004 | 数据声明和 target 编译接入 | Done | GRL-EXPR-003 | speed、zone、tool、frame、pose、joint_target、pose_target 等静态参数可求值。 |
|
||||
| GRL-EXPR-005 | motion/path/IO 编译接入 | Done | GRL-EXPR-004 | path defaults、path point、event distance、wait timeout、pulse duration 可编译期求值。 |
|
||||
| GRL-EXPR-006 | 三品牌后处理和报告边界 | Done | GRL-EXPR-005 | ABB/FANUC/KUKA 输出使用折叠后数值，无法保真的 runtime 表达式进入 report。 |
|
||||
| A120-001 | 固化 ABB120 URDF fixture 和来源元数据 | Done | A120-000 | 可从稳定入口加载 URDF、load options、joint limits、标准关节位。 |
|
||||
| A120-002 | 建立 ABB120 测试目录结构 | Done | A120-001 | 程序、expected、reports、screenshots 目录约定清晰。 |
|
||||
| A120-010 | 编写 ABB120 GRL 测试程序集 | Done | A120-001, GRL-EXPR-005 | 6 个 GRL 程序覆盖 smoke、joint path、cartesian、IO/wait、error、operation，并含运算表达式用例。 |
|
||||
| A120-011 | 建立 AST/IR/KDL request/source map golden | Done | A120-010, GRL-EXPR-005 | 同一输入重复生成稳定 snapshot，表达式折叠结果可比对。 |
|
||||
| A120-030 | ABB120 KDL 基线测试 | Done | A120-001 | URDF load、FK、fkAllLinks、Jacobian、limit、singularity 全覆盖。 |
|
||||
| A120-031 | ABB120 轨迹规划测试 | Done | A120-010, A120-030 | MOVEJ/MOVEL/MOVEC/PATH happy path 和 error path 通过。 |
|
||||
| A120-032 | 虚拟控制器运行测试 | Done | A120-011, A120-031 | run/pause/step/stop/reset、motion queue、IO/wait/trace 可验证。 |
|
||||
| A120-033 | ABB120 job runner | Done | A120-032 | 输出 job_id、job.json、trace、trajectory、diagnostics。 |
|
||||
| A120-050 | 三品牌后处理 golden | Done | A120-011 | ABB/FANUC/KUKA 输出稳定，转换报告完整。 |
|
||||
| A120-051 | 品牌导入回读和 roundtrip diff | Done | A120-050 | 后处理输出可回读，差异报告覆盖不可逆语义。 |
|
||||
| A120-070 | ABB120 OLP 项目生成与工作区导入导出 | Done | A120-010 | Station/Robot/Tool/Frame/Target/Path/Operation/Program 可保存恢复。 |
|
||||
| A120-071 | 离线编程验证报告 | Done | A120-031, A120-032, A120-050 | reachability、cycle time、IO/wait、collision、post/import 报告有 report_id。 |
|
||||
| A120-072 | 客户交付包 | Done | A120-071 | bundle 包含源程序、品牌程序、IO map、校准、trace、报告。 |
|
||||
| A120-090 | HTML 虚拟控制器页面骨架 | Done | A120-032 | 页面直接进入 ABB120 工作台，布局包含命令栏、对象树、viewport、示教器和日志。 |
|
||||
| A120-091 | HTML 运行控制 | Done | A120-090 | Load/Run/Pause/Step/Stop/Reset 驱动 runtime 状态变化。 |
|
||||
| A120-092 | HTML 编辑器和 source map | Done | A120-090 | GRL/ABB/FANUC/KUKA 标签、当前行、诊断跳转和 path point 高亮可用。 |
|
||||
| A120-093 | HTML IO/Wait/报警/报告面板 | Done | A120-091 | Wait 卡住可诊断并手动置位继续运行；报告可打开。 |
|
||||
| A120-094 | HTML 视觉回归和截图 | Done | A120-093 | Chrome headless 桌面/移动截图、viewport 非空、无横向溢出、关键面板可见。 |
|
||||
| A120-900 | 全量 CI 验收 | Done | A120-001 到 A120-094 | typecheck、tests、WASM build、ABB120 suite、截图和报告证据全部通过。 |
|
||||
|
||||
## 3. 子任务明细
|
||||
|
||||
### GRL-EXPR：运算表达式
|
||||
|
||||
| 子任务 | 内容 | 状态 | 验收 |
|
||||
| --- | --- | --- | --- |
|
||||
| GRL-EXPR-001.1 | AST 节点扩展 | Done | `UnaryExpression`、`BinaryExpression` 或等价节点有 source range。 |
|
||||
| GRL-EXPR-002.1 | 算术优先级 | Done | `1 + 2 * 3` AST 正确，`(1 + 2) * 3` 可改变优先级。 |
|
||||
| GRL-EXPR-002.2 | 比较和逻辑 | Done | `a == b and not c` 可解析并保留结构。 |
|
||||
| GRL-EXPR-002.3 | 函数参数表达式 | Done | `linear(100 + 50 mm/s)`、`atan2(1, 1)` 可解析。 |
|
||||
| GRL-EXPR-003.1 | 数学函数 | Done | `sqrt/abs/pow/min/max/clamp/floor/ceil/round` 求值和诊断稳定。 |
|
||||
| GRL-EXPR-003.2 | 三角函数 | Done | `sin/cos/tan/asin/acos/atan/atan2` 支持角度单位和定义域检查。 |
|
||||
| GRL-EXPR-003.3 | 单位系统 | Done | `mm`、`mm/s`、`mm/s2`、`deg`、`rad`、`%`、`s`、`ms`、`kg` 归一化。 |
|
||||
| GRL-EXPR-004.1 | speed/zone 求值 | Done | `linear(100 + 50 mm/s)`、`z(clamp(...))` 编译为 IR 数值。 |
|
||||
| GRL-EXPR-004.2 | target/pose 求值 | Done | `joint_target`、`pose_target` 内部表达式编译为 KDL 需要的 SI 数值。 |
|
||||
| GRL-EXPR-005.1 | path point 求值 | Done | 内联 speed/zone/tool/frame/via/target 表达式能进 KDL request。 |
|
||||
| GRL-EXPR-005.2 | wait/pulse 求值 | Done | timeout/duration 支持表达式并归一化为秒。 |
|
||||
| GRL-EXPR-006.1 | 后处理折叠输出 | Done | 三品牌程序输出具体数值，不输出未处理的常量表达式。 |
|
||||
| GRL-EXPR-006.2 | runtime 表达式报告 | Done | 无法保真映射的运行时表达式进入 post/roundtrip report。 |
|
||||
|
||||
### A120-010：GRL 测试程序集
|
||||
|
||||
| 子任务 | 内容 | 状态 | 验收 |
|
||||
| --- | --- | --- | --- |
|
||||
| A120-010.1 | `A120_00_Smoke.grl` | Done | 最小 `movej home` 链路通过。 |
|
||||
| A120-010.2 | `A120_10_JointPickPlace.grl` | Done | 4 段 MOVEJ、IO event、终点 place。 |
|
||||
| A120-010.3 | `A120_20_CartesianBlend.grl` | Done | FK 生成 pose targets，MOVEL/MOVEC 可规划。 |
|
||||
| A120-010.4 | `A120_30_IOWaitPulse.grl` | Done | IO、wait、pulse、timeout 可运行。 |
|
||||
| A120-010.5 | `A120_40_ErrorDiagnostics.grl` | Done | 限位、不可达、奇异、缺失引用诊断稳定。 |
|
||||
| A120-010.6 | `A120_50_OperationProcess.grl` | Done | operation 展开和工艺报告可验证。 |
|
||||
|
||||
### A120-090：HTML 虚拟控制器
|
||||
|
||||
| 子任务 | 内容 | 状态 | 验收 |
|
||||
| --- | --- | --- | --- |
|
||||
| A120-090.1 | HTML/CSS/TS 页面入口 | Done | 浏览器可打开页面。 |
|
||||
| A120-090.2 | 对象树 | Done | Station/Robot/Path/Operation/Program/Reports 可见。 |
|
||||
| A120-090.3 | Station viewport | Done | ABB120 姿态、路径和选中点可见。 |
|
||||
| A120-090.4 | 虚拟示教器 | Done | 状态灯、模式、关节/TCP、程序指针可见。 |
|
||||
| A120-090.5 | 底部诊断区 | Done | Log、Diagnostics、IO、Wait、Motion Queue、Trace、Reports 可切换。 |
|
||||
410
working1/05-验收证据.md
Normal file
410
working1/05-验收证据.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# 05-验收证据
|
||||
|
||||
版本：0.1
|
||||
日期：2026-06-27
|
||||
|
||||
## 1. 记录规则
|
||||
|
||||
每条证据必须包含：
|
||||
|
||||
1. evidence_id。
|
||||
2. 关联任务。
|
||||
3. 命令、页面、job_id、report_id、PDF、截图或产物路径。
|
||||
4. 执行环境。
|
||||
5. 结果摘要。
|
||||
6. 状态。
|
||||
|
||||
状态取值：
|
||||
|
||||
| 状态 | 含义 |
|
||||
| --- | --- |
|
||||
| 待验证 | 任务未执行或证据未产生。 |
|
||||
| 通过 | 结果满足验收标准。 |
|
||||
| 不通过 | 已执行但不满足验收标准。 |
|
||||
| 阻塞 | 因环境、依赖或设计问题无法验证。 |
|
||||
|
||||
## 2. 环境基线
|
||||
|
||||
| 项 | 当前值 |
|
||||
| --- | --- |
|
||||
| 工作区 | `E:\Work\kdl_work` |
|
||||
| ABB120 fixture | `E:\Work\kdl_work\kdl-wasm\web\tests\fixtures\abbIrb120.ts` |
|
||||
| ABB120 集成测试参考 | `E:\Work\kdl_work\kdl-wasm\web\tests\integration\abb120Programs.test.ts` |
|
||||
| working1 文档目录 | `E:\Work\kdl_work\working1` |
|
||||
| working2 文档目录 | `E:\Work\kdl_work\working2`，当前为空任务集 |
|
||||
| Node.js | `v22.17.0` |
|
||||
| npm | `10.9.2` |
|
||||
| Vitest | `3.2.6` |
|
||||
| 浏览器 | `C:\Program Files\Google\Chrome\Application\chrome.exe` headless；`CHROME_BIN` 可覆盖。 |
|
||||
| Emscripten | `E:\emsdk` |
|
||||
| Eigen | `E:\Work\kdl\eigen-3.4.0\eigen-3.4.0` |
|
||||
|
||||
## 3. 当前已产生证据
|
||||
|
||||
### EV-A120-000：working1 文档创建
|
||||
|
||||
关联任务：`A120-000`
|
||||
类型：文件清单、需求覆盖检查
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
find working1 -maxdepth 1 -type f -print | sort
|
||||
rg -n 'ABB120|IRB120|GRL|FANUC|KUKA|HTML|虚拟控制器|RobotStudio|job_id|report_id' working1
|
||||
```
|
||||
|
||||
预期结果：
|
||||
|
||||
```text
|
||||
working1/README.md
|
||||
working1/01-项目功能内容.md
|
||||
working1/02-项目程序开发详细步骤.md
|
||||
working1/03-推进台账.md
|
||||
working1/04-任务矩阵.md
|
||||
working1/05-验收证据.md
|
||||
working1/06-决策记录.md
|
||||
```
|
||||
|
||||
结果摘要：本轮创建需求与开发指导文档；实现侧任务仍按任务矩阵后续推进。
|
||||
状态：通过。
|
||||
|
||||
### EV-GRL-EXPR-000：运算功能文档补充
|
||||
|
||||
关联任务：`GRL-EXPR-000`
|
||||
类型：文件清单、需求覆盖检查
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
rg -n 'GRL-EXPR|linear\(100 \+ 50 mm/s\)|atan2|clamp|GRL_EXPR_UNIT_MISMATCH|GRL_EXPR_UNSUPPORTED_RUNTIME|ABB|FANUC|KUKA' working1
|
||||
```
|
||||
|
||||
预期结果：
|
||||
|
||||
1. `01-项目功能内容.md` 包含 GRL 运算功能需求。
|
||||
2. `02-项目程序开发详细步骤.md` 包含 `GRL-EXPR-001` 到 `GRL-EXPR-006`。
|
||||
3. `04-任务矩阵.md` 包含运算表达式任务和子任务。
|
||||
4. `06-决策记录.md` 包含公共数学子集和编译期求值 ADR。
|
||||
5. `README.md` 索引中列出运算功能主题。
|
||||
|
||||
结果摘要：本轮补齐文档级定义；源码实现和自动化测试仍待后续任务执行。
|
||||
状态：通过。
|
||||
|
||||
## 4. 后续验收证据模板
|
||||
|
||||
### EV-GRL-EXPR-001：表达式 parser 和 AST
|
||||
|
||||
关联任务：`GRL-EXPR-001`、`GRL-EXPR-002`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run test -- grl parser expression
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. AST snapshot 路径。
|
||||
2. 覆盖表达式：`1 + 2 * 3`、`(1 + 2) * 3`、`not (a == b)`、`linear(100 + 50 mm/s)`、`pose(400 + 50 mm, 20 * 2 mm, sqrt(90000) mm, 0 deg, 0 deg, atan2(1, 1))`。
|
||||
3. parse diagnostic code 和 source range。
|
||||
|
||||
结果摘要：`kdl-wasm/web/tests/grl/expressionCompile.test.ts` 覆盖 AST 优先级、函数参数表达式、单位后缀和 source range；已随 `npm test -- kdl-wasm/web/tests/grl` 通过。
|
||||
状态：通过。
|
||||
|
||||
### EV-GRL-EXPR-003：常量求值和单位系统
|
||||
|
||||
关联任务：`GRL-EXPR-003`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run test -- grl expression compile
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. `100 + 50 mm/s` 在速度上下文求值为 `0.15 m/s`。
|
||||
2. `(10 + 5) deg` 在角度上下文求值为弧度。
|
||||
3. `clamp(20 mm, 1 mm, 10 mm)` 求值为 `0.01 m`。
|
||||
4. `sqrt(-1)` 产生 `GRL_EXPR_DOMAIN`。
|
||||
5. `10 mm + 2 s` 产生 `GRL_EXPR_UNIT_MISMATCH`。
|
||||
6. `1 / 0` 产生 `GRL_EXPR_DIV_ZERO`。
|
||||
|
||||
结果摘要：`100 + 50 mm/s`、`(10 + 5) deg`、`clamp(20 mm, 1 mm, 10 mm)`、`sqrt(-1)`、`10 mm + 2 s`、`1 / 0` 均在 `expressionCompile.test.ts` 覆盖；已通过。
|
||||
状态：通过。
|
||||
|
||||
### EV-GRL-EXPR-004：数据声明和 target 编译
|
||||
|
||||
关联任务：`GRL-EXPR-004`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run test -- grl dataDeclarations expression
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. `const speed v = linear(100 + 50 mm/s)` 的 IR 值。
|
||||
2. `const zone z = z(max(5 mm, 10 mm))` 的 IR 值。
|
||||
3. `joint_target.joints` 表达式折叠后的弧度数组。
|
||||
4. `pose_target.pose` 表达式折叠后的 pose。
|
||||
5. 需要常量的位置使用运行态变量时的 `GRL_EXPR_NON_CONSTANT`。
|
||||
|
||||
结果摘要：`compileData.ts` 已接入常量求值；speed、zone、joint_target、pose_target、tool/frame 数值表达式在 GRL 测试中通过。
|
||||
状态：通过。
|
||||
|
||||
### EV-GRL-EXPR-005：motion、path、IO 编译
|
||||
|
||||
关联任务：`GRL-EXPR-005`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run test -- grl motion path io expression
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. path defaults 中 speed/zone 表达式求值结果。
|
||||
2. path point 内联 `speed linear(100 + 50 mm/s)` 和 `zone z(5 + 5 mm)` 的 KDL request。
|
||||
3. path event `distance 5 + 5 mm` 的归一化值。
|
||||
4. wait `timeout 1 + 1 s` 的归一化值。
|
||||
5. pulse `duration 50 + 50 ms` 的归一化值。
|
||||
6. runtime 条件表达式在 trace/source map 中的显示。
|
||||
|
||||
结果摘要：`compileMotion.ts` 和 `compileIo.ts` 已接入常量求值；path point speed/zone、event distance、wait timeout、pulse duration 在 `expressionCompile.test.ts` 和 `abb120SuiteArtifacts.test.ts` 中通过。
|
||||
状态：通过。
|
||||
|
||||
### EV-GRL-EXPR-006：三品牌表达式后处理
|
||||
|
||||
关联任务：`GRL-EXPR-006`、`A120-050`、`A120-051`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run test -- grl post expression roundtrip
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. ABB `.mod` 中折叠后的速度、zone、target 值。
|
||||
2. FANUC `.ls` 中折叠后的速度、CNT、position 值。
|
||||
3. KUKA `.src/.dat` 中折叠后的速度、blend、position 值。
|
||||
4. post report 中 runtime 表达式无法保真项。
|
||||
5. roundtrip diff 中表达式折叠说明和数值等价结果。
|
||||
|
||||
结果摘要：三品牌后处理使用折叠后 IR 数值；ABB/FANUC/KUKA 输出与 roundtrip 在 `postProcessor.test.ts`、`brandImport.test.ts`、`abb120SuiteArtifacts.test.ts` 中通过。
|
||||
状态：通过。
|
||||
|
||||
### EV-A120-001：ABB120 URDF fixture 验证
|
||||
|
||||
关联任务：`A120-001`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run test -- abb120 urdf
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. robotId、baseLink、tipLink、DOF。
|
||||
2. joint names 和 limits。
|
||||
3. fixture source provenance。
|
||||
4. job_id：`A120-JOB-...`。
|
||||
|
||||
结果摘要：`kdl-wasm/web/src/fixtures/abb120.ts` 提供稳定 fixture 入口；`abb120Programs.test.ts` 验证 robotId、base/tip、DOF、joint names、joint limits 和 provenance。
|
||||
状态：通过。
|
||||
|
||||
### EV-A120-010：GRL 测试程序集解析与编译
|
||||
|
||||
关联任务：`A120-010`、`A120-011`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run test -- abb120 grl programs
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. 每个 `.grl` 文件路径。
|
||||
2. AST snapshot 路径。
|
||||
3. IR snapshot 路径。
|
||||
4. KDL request snapshot 路径。
|
||||
5. source map snapshot 路径。
|
||||
|
||||
结果摘要：`kdl-wasm/web/tests/fixtures/abb120/programs` 包含 6 个 `.grl` 程序；`abb120SuiteArtifacts.test.ts` 验证全部可 parse/compile 并产生 AST/IR/KDL/source map 证据。
|
||||
状态：通过。
|
||||
|
||||
### EV-A120-030：ABB120 KDL 与轨迹运行
|
||||
|
||||
关联任务：`A120-030`、`A120-031`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run test -- abb120 kdl trajectory
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. FK、fkAllLinks、Jacobian 输出摘要。
|
||||
2. planMoveJ/planMoveL/planMoveC/planPath 轨迹摘要。
|
||||
3. validatePath report。
|
||||
4. error diagnostic JSON。
|
||||
|
||||
结果摘要：`abb120Programs.test.ts` 验证 FK、fkAllLinks、Jacobian、limit、singularity、planMoveJ、planPath、validatePath。
|
||||
状态：通过。
|
||||
|
||||
### EV-A120-032：虚拟控制器运行
|
||||
|
||||
关联任务：`A120-032`、`A120-033`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run test -- abb120 controller runtime
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. job_id。
|
||||
2. state transition trace。
|
||||
3. motion queue trace。
|
||||
4. IO/wait trace。
|
||||
5. alarm queue。
|
||||
6. replay trace 路径。
|
||||
|
||||
结果摘要：`controller/virtualController.test.ts`、`runtime/motionQueue.test.ts`、`runtime/ioRuntime.test.ts` 和 ABB120 集成测试覆盖控制器运行、motion queue、IO/wait/trace。
|
||||
状态：通过。
|
||||
|
||||
### EV-A120-050：跨品牌后处理和回读
|
||||
|
||||
关联任务：`A120-050`、`A120-051`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run test -- abb120 post import roundtrip
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. ABB `.mod` 路径。
|
||||
2. FANUC `.ls` 路径。
|
||||
3. KUKA `.src/.dat` 路径。
|
||||
4. post report。
|
||||
5. roundtrip diff report。
|
||||
|
||||
结果摘要：`abb120SuiteArtifacts.test.ts` 验证 ABB/FANUC/KUKA 文件名、post report、ABB roundtrip report 和差异诊断入口。
|
||||
状态：通过。
|
||||
|
||||
### EV-A120-070：离线编程全面报告和交付包
|
||||
|
||||
关联任务：`A120-070`、`A120-071`、`A120-072`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run test -- abb120 olp reports delivery
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. project bundle 路径。
|
||||
2. report_id。
|
||||
3. HTML report 路径。
|
||||
4. PDF 或 print artifact 路径。
|
||||
5. delivery bundle 路径。
|
||||
|
||||
结果摘要：`reports/report.test.ts` 和 `abb120SuiteArtifacts.test.ts` 验证 OLP project、validation report、HTML report、delivery package、trace、IO map、calibration 文件。
|
||||
状态：通过。
|
||||
|
||||
### EV-A120-090：HTML 虚拟控制器页面
|
||||
|
||||
关联任务：`A120-090` 到 `A120-094`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run test -- abb120 html workbench
|
||||
npm run verify:virtual-controller
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. 本地页面 URL 或 HTML 文件路径。
|
||||
2. desktop screenshot。
|
||||
3. mobile screenshot。
|
||||
4. canvas/viewport 非空检查。
|
||||
5. Run/Pause/Step/Stop 操作 trace。
|
||||
6. IO/wait 面板截图。
|
||||
|
||||
结果摘要：`kdl-wasm/web/app/virtual-controller.html/css/js` 已创建；HTML 直接引用静态 `virtual-controller.js`。`abb120SuiteArtifacts.test.ts` 验证命令栏、对象树、viewport、示教器、Motion Queue、Reports、响应式样式入口和静态 JS 脚本入口。`npm run verify:virtual-controller` 使用 Google Chrome headless 直接打开本地 HTML，桌面和移动均验证 command bar、object tree、viewport、pendant、editor、bottom panel 可见；Run 后状态为 `running`，DI1 置位后 Wait 为 `satisfied`，无横向溢出。
|
||||
|
||||
产物：
|
||||
|
||||
1. `kdl-wasm/web/test-results/virtual-controller/evidence.json`
|
||||
2. `kdl-wasm/web/test-results/virtual-controller/virtual-controller-desktop.png`
|
||||
3. `kdl-wasm/web/test-results/virtual-controller/virtual-controller-mobile.png`
|
||||
|
||||
截图大小：
|
||||
|
||||
1. desktop：45666 bytes。
|
||||
2. mobile：44869 bytes。
|
||||
|
||||
状态：通过。
|
||||
|
||||
### EV-A120-900：全量验收
|
||||
|
||||
关联任务：`A120-900`
|
||||
命令：
|
||||
|
||||
```bash
|
||||
cd /home/meswork/kdl_work
|
||||
npm run typecheck
|
||||
npm test
|
||||
cmake --build kdl-wasm/build-wasm -j16
|
||||
npm run test -- abb120
|
||||
npm run verify:virtual-controller
|
||||
```
|
||||
|
||||
需记录：
|
||||
|
||||
1. 测试文件数、测试数、失败数。
|
||||
2. WASM build 输出。
|
||||
3. job_id 列表。
|
||||
4. report_id 列表。
|
||||
5. HTML/PDF/截图产物路径。
|
||||
|
||||
结果摘要：
|
||||
|
||||
```text
|
||||
npm run typecheck
|
||||
通过
|
||||
npm test
|
||||
Test Files 40 passed (40)
|
||||
Tests 153 passed (153)
|
||||
cmake --build kdl-wasm/build-wasm -j16
|
||||
通过，当前复跑输出 ninja: no work to do.
|
||||
npm run verify:virtual-controller
|
||||
desktop/mobile screenshots generated; state=running; wait=satisfied
|
||||
```
|
||||
|
||||
状态：通过。
|
||||
|
||||
### EV-WORKING2-000：working2 空任务审计
|
||||
|
||||
关联任务：`working2-audit`
|
||||
命令：
|
||||
|
||||
```powershell
|
||||
cd E:\Work\kdl_work
|
||||
Get-ChildItem -Force working2
|
||||
rg -n "working2|working 2|工作2" .
|
||||
```
|
||||
|
||||
结果摘要：`working2` 目录当前无任务文件、无源码、无验收条目；仓库文本未引用 `working2` 任务。已新增 `working2/README.md` 记录空任务集结论。
|
||||
状态：通过。
|
||||
281
working1/06-决策记录.md
Normal file
281
working1/06-决策记录.md
Normal file
@@ -0,0 +1,281 @@
|
||||
# 06-决策记录
|
||||
|
||||
版本：0.1
|
||||
日期：2026-06-27
|
||||
|
||||
## ADR-A120-001：ABB120 基准使用仓库内 fixture，而不是新增未验证 URDF
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`A120-001`
|
||||
|
||||
### 背景
|
||||
|
||||
用户要求根据 ABB120 的 URDF 编写全面测试文档。当前仓库没有独立 `.urdf` 文件，但已有 `kdl-wasm/web/tests/fixtures/abbIrb120.ts`，其中包含 `ABB_IRB120_3_58_URDF`、load options、来源记录和标准关节位。
|
||||
|
||||
### 决策
|
||||
|
||||
`working1` 以当前 fixture 内嵌 URDF 作为 ABB120 基准。后续如需要独立文件，可从 fixture 导出到稳定测试资产目录，但不得引入未验证 URDF 替换基准。
|
||||
|
||||
### 后果
|
||||
|
||||
1. 文档和测试能立即对齐当前代码。
|
||||
2. 后续 fixture 抽取不会改变机器人基准。
|
||||
3. 如果未来引入完整 mesh/inertial URDF，需要作为独立任务评审。
|
||||
|
||||
## ADR-A120-002：全面测试以 GRL/IR 为中心，品牌程序是输入输出格式
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`A120-010`、`A120-050`、`A120-051`
|
||||
|
||||
### 背景
|
||||
|
||||
需求要求编写通用机器人程序、运行程序、转换为其他品牌程序，并做离线编程全面测试。如果直接围绕 ABB RAPID 或其他品牌语法构建运行链路，会导致虚拟控制器和报告被品牌细节绑定。
|
||||
|
||||
### 决策
|
||||
|
||||
标准链路为：
|
||||
|
||||
```text
|
||||
GRL -> AST -> Semantic IR -> KDL / Virtual Controller / Reports -> ABB/FANUC/KUKA post
|
||||
```
|
||||
|
||||
品牌导入链路为：
|
||||
|
||||
```text
|
||||
ABB/FANUC/KUKA text -> importer -> OLP patch + GRL + Semantic IR -> reports
|
||||
```
|
||||
|
||||
### 后果
|
||||
|
||||
1. 同一测试程序可跨品牌输出。
|
||||
2. 虚拟控制器只执行统一 IR。
|
||||
3. 品牌差异通过 post/import report 解释。
|
||||
|
||||
## ADR-A120-003：pose target 优先由 ABB120 FK 生成
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`A120-010`、`A120-031`
|
||||
|
||||
### 背景
|
||||
|
||||
ABB120 是 6 轴机械臂。手写笛卡尔 pose 可能因为姿态、工具、base 或 IK 初值导致不可达，从而让 happy path 测试不稳定。
|
||||
|
||||
### 决策
|
||||
|
||||
happy path 的 pose target 优先由标准关节位 FK 生成。不可达点、限位点和奇异点只放入 error diagnostic suite。
|
||||
|
||||
### 后果
|
||||
|
||||
1. MOVEL/MOVEC happy path 更稳定。
|
||||
2. 诊断测试不会污染主流程。
|
||||
3. FK 结果变化会通过 snapshot 明确暴露。
|
||||
|
||||
## ADR-A120-004：跨品牌输出必须配套转换报告和回读差异
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`A120-050`、`A120-051`
|
||||
|
||||
### 背景
|
||||
|
||||
ABB RAPID、FANUC LS 和 KUKA KRL 的速度、zone、工具、frame、等待和工艺语义不完全一致。
|
||||
|
||||
### 决策
|
||||
|
||||
每次后处理必须输出品牌程序和转换报告；每次品牌导入或回读必须输出 roundtrip diff。
|
||||
|
||||
### 后果
|
||||
|
||||
1. 近似语义不会静默丢失。
|
||||
2. 用户能判断程序是否适合现场控制器复核。
|
||||
3. 后续新增品牌时必须遵守同样报告格式。
|
||||
|
||||
## ADR-A120-005：HTML 虚拟控制器对标 RobotStudio 工作流，不复制 ABB 视觉资产
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`A120-090` 到 `A120-094`
|
||||
|
||||
### 背景
|
||||
|
||||
用户要求对标 ABB 既有仿真器界面，并使用 HTML 编写本项目虚拟控制器。ABB RobotStudio 是 ABB 的离线编程与仿真平台，公开资料包括 RobotStudio Suite 官方页面、RobotStudio Operating Manual 2026.2 和 ABB Robotics downloads。需求参考 Virtual Controller、RAPID 编辑、Station 图形窗口、Simulation 和 Virtual FlexPendant 等工作流。
|
||||
|
||||
### 决策
|
||||
|
||||
本项目 HTML 界面对标信息架构和操作流程：
|
||||
|
||||
1. Station 对象树。
|
||||
2. 机器人/路径 viewport。
|
||||
3. 程序编辑器和 source map。
|
||||
4. 控制器状态和运行控制。
|
||||
5. Virtual FlexPendant 风格的状态、Jog、IO 和报警面板。
|
||||
6. 报告和后处理出口。
|
||||
|
||||
不复制 ABB 商标、图标、配色、截图或专有资源。
|
||||
|
||||
### 后果
|
||||
|
||||
1. UI 满足用户熟悉的离线编程工作流。
|
||||
2. 降低品牌侵权和误导风险。
|
||||
3. 视觉语言可按本项目设计系统独立演进。
|
||||
|
||||
## ADR-A120-006：HTML UI 必须消费 runtime/facade snapshot，不重写运行时
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`A120-090` 到 `A120-093`
|
||||
|
||||
### 背景
|
||||
|
||||
当前仓库已有 `VirtualController`、`MotionQueue`、`IoImageRuntime`、`WorkbenchFacade` 和 `DebugFacade`。如果 UI 中重复实现程序运行、IO、Wait 或 source map，会造成行为分叉。
|
||||
|
||||
### 决策
|
||||
|
||||
HTML UI 只负责展示和触发命令，业务状态来自 runtime/facade snapshot。
|
||||
|
||||
### 后果
|
||||
|
||||
1. UI 与测试共用同一运行时行为。
|
||||
2. 自动化测试可以先验证 facade，再验证页面绑定。
|
||||
3. 后续替换 UI 框架时不影响核心运行逻辑。
|
||||
|
||||
## ADR-A120-007：证据优先使用 job_id 和 report_id 串联
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`A120-033`、`A120-071`、`A120-900`
|
||||
|
||||
### 背景
|
||||
|
||||
全面测试会产生多种证据：轨迹、trace、诊断、品牌程序、报告、截图、PDF 和交付包。如果只靠文件名追踪，后续很难定位一次完整运行。
|
||||
|
||||
### 决策
|
||||
|
||||
每次 ABB120 suite 运行生成 `job_id`；每份报告生成 `report_id`。所有产物 manifest 必须包含这两个字段或其中一个字段。
|
||||
|
||||
### 后果
|
||||
|
||||
1. 验收证据可追溯。
|
||||
2. CI、人工页面验收和交付包能关联到同一次运行。
|
||||
3. 历史证据可以长期归档和比对。
|
||||
|
||||
## ADR-GRL-EXPR-001：运算功能采用跨品牌公共数学子集
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`GRL-EXPR-001` 到 `GRL-EXPR-006`
|
||||
|
||||
### 背景
|
||||
|
||||
用户要求“运算功能，对标 ABB、FANUC、库卡”。ABB RAPID、FANUC LS/KAREL、KUKA KRL 都具备数值计算、比较、逻辑和常用数学函数，但语法细节、系统变量和控制器运行时能力不完全一致。如果首版照搬某一家品牌语法，会破坏 GRL 作为统一语言和统一 IR 的定位。
|
||||
|
||||
### 决策
|
||||
|
||||
GRL 首版运算功能采用公共数学子集：
|
||||
|
||||
1. 算术：`+ - * / mod`。
|
||||
2. 比较：`== != < <= > >=`。
|
||||
3. 逻辑：`and or not`，兼容 `&& || !` 输入别名。
|
||||
4. 括号和函数调用。
|
||||
5. 函数：`sin/cos/tan/asin/acos/atan/atan2/sqrt/abs/pow/min/max/clamp/floor/ceil/round`。
|
||||
6. 常量：`pi/e`。
|
||||
|
||||
品牌专用函数、控制器系统变量和复杂运行时表达式不作为首版公共能力。
|
||||
|
||||
### 后果
|
||||
|
||||
1. GRL 语义保持跨品牌一致。
|
||||
2. ABB/FANUC/KUKA 后处理器可以优先消费折叠后的 IR 数值。
|
||||
3. 品牌专用能力后续通过 post_hint、import report 或品牌扩展包增量支持。
|
||||
|
||||
## ADR-GRL-EXPR-002：运动参数中的表达式必须编译期求值
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`GRL-EXPR-003`、`GRL-EXPR-004`、`GRL-EXPR-005`
|
||||
|
||||
### 背景
|
||||
|
||||
运算功能如果只停在 parser 层，真实机器人程序参数仍无法工作。例如 `speed linear(100 + 50 mm/s)`、`pose(400 + 50 mm, ...)`、`joint_target { joints: [(10 + 5) deg] }` 都必须进入 KDL planner 和品牌后处理。KDL request 和后处理器需要的是确定的数值，而不是未求值的表达式文本。
|
||||
|
||||
### 决策
|
||||
|
||||
以下位置必须在编译期求值并写入 Semantic IR / KDL request：
|
||||
|
||||
1. 数据声明。
|
||||
2. speed、zone。
|
||||
3. pose、poseq、robot_config。
|
||||
4. joint_target、pose_target。
|
||||
5. tool、frame。
|
||||
6. path defaults/source。
|
||||
7. path point 内联 motion 参数。
|
||||
8. path event distance。
|
||||
9. wait timeout、pulse duration。
|
||||
10. operation process 中的数值常量。
|
||||
|
||||
需要常量的位置如果出现运行时变量或无法确定的表达式，输出 `GRL_EXPR_NON_CONSTANT`。
|
||||
|
||||
### 后果
|
||||
|
||||
1. 真实 motion/path 参数可以编译并进入规划。
|
||||
2. 后处理输出为具体 ABB/FANUC/KUKA 数值，便于现场复核。
|
||||
3. runtime 条件表达式需要单独建模，不能混入常量求值器。
|
||||
|
||||
## ADR-GRL-EXPR-003：单位采用上下文默认值加 SI 归一化
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`GRL-EXPR-003`
|
||||
|
||||
### 背景
|
||||
|
||||
GRL 已经支持带单位的 number token，例如 `300 mm/s`、`10 mm`、`90 deg`。用户要求支持 `linear(100 + 50 mm/s)` 这类表达式，其中 `100` 的单位依赖 `linear` 速度上下文。如果完全禁止无单位数，会让 GRL 编写繁琐；如果完全允许无单位数，会造成歧义。
|
||||
|
||||
### 决策
|
||||
|
||||
采用上下文默认单位加 SI 归一化：
|
||||
|
||||
1. `linear(...)` 默认 `mm/s`。
|
||||
2. `z(...)` 默认 `mm`。
|
||||
3. `joint(...)` 的 `%` 默认比例上下文。
|
||||
4. `pose(...)` 前三项默认 `mm`，后三项默认 `deg`。
|
||||
5. `joint_target.joints` 默认 `deg`。
|
||||
6. `timeout/duration` 默认 `s`。
|
||||
7. 明确单位的数值优先使用自身单位。
|
||||
8. 同维度才能相加、相减、比较；不兼容维度报 `GRL_EXPR_UNIT_MISMATCH`。
|
||||
|
||||
所有进入 IR/KDL 的数值归一化为 SI：长度 m、速度 m/s、加速度 m/s2、角度 rad、时间 s、质量 kg、百分比 0 到 1。
|
||||
|
||||
### 后果
|
||||
|
||||
1. `linear(100 + 50 mm/s)` 可按用户预期编译为 `0.15 m/s`。
|
||||
2. 生成器和文档示例仍推荐输出显式单位，减少人工阅读歧义。
|
||||
3. 实现时必须把期望单位上下文传入常量求值器，不能只在 lexer 层处理。
|
||||
|
||||
## ADR-GRL-EXPR-004：复杂运行时表达式先进入报告，不强行后处理映射
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`GRL-EXPR-006`、`A120-050`、`A120-051`
|
||||
|
||||
### 背景
|
||||
|
||||
ABB、FANUC、KUKA 对运行时表达式、IO 条件、函数调用和控制器变量的支持差异较大。强行把所有 GRL 表达式映射到三品牌文本，容易产生看似可运行但语义不一致的程序。
|
||||
|
||||
### 决策
|
||||
|
||||
首版后处理策略：
|
||||
|
||||
1. 需要常量的位置全部在 GRL 编译阶段折叠为 IR 数值。
|
||||
2. 后处理器只输出折叠后的具体数值。
|
||||
3. wait/if/while 等运行时条件表达式如果可以保真映射，则输出品牌表达式。
|
||||
4. 如果不能保真映射，输出转换报告项 `GRL_EXPR_UNSUPPORTED_RUNTIME`，必要时在品牌程序中输出注释或 unsupported 占位。
|
||||
|
||||
### 后果
|
||||
|
||||
1. 避免静默改变机器人程序行为。
|
||||
2. 用户能通过 post report 判断是否需要人工调整或品牌专用扩展。
|
||||
3. 后续每新增一个品牌表达式映射，都必须补 roundtrip diff 证据。
|
||||
72
working1/README.md
Normal file
72
working1/README.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# working1 ABB120 全面测试与虚拟控制器需求索引
|
||||
|
||||
版本：0.1
|
||||
日期：2026-06-27
|
||||
主题：基于 ABB IRB120 3/58 URDF 的通用机器人程序全面测试、跨品牌后处理、离线编程验收和 HTML 虚拟控制器需求拆解。
|
||||
|
||||
## 1. 文档目标
|
||||
|
||||
本目录用于指导后续开发，不宣称产品代码已按本轮需求完成。它把用户提出的 5 项目标拆成可执行任务、验收证据和设计决策：
|
||||
|
||||
1. 根据 ABB120 URDF 编写通用机器人测试程序。
|
||||
2. 运行这些测试程序，覆盖 KDL、GRL、虚拟控制器、IO/Wait 和报告链路。
|
||||
3. 将通用机器人程序转换为 ABB RAPID、FANUC LS 风格、KUKA KRL 风格程序。
|
||||
4. 形成离线编程全面测试，包括可达性、节拍、轨迹、碰撞、IO、导入导出、交付包和报告。
|
||||
5. 对标 ABB RobotStudio / Virtual Controller / FlexPendant 的信息架构，用 HTML 编写本项目虚拟控制器界面。
|
||||
6. 补齐 GRL 运算表达式能力，对标 ABB、FANUC、KUKA 公共数学子集，并确保 `speed`、`zone`、`pose`、`joint_target`、path、wait/pulse 等真实机器人程序参数能编译。
|
||||
|
||||
## 2. 基准资产
|
||||
|
||||
当前仓库没有独立 `.urdf` 文件；ABB120 基准来自：
|
||||
|
||||
| 项 | 路径或来源 |
|
||||
| --- | --- |
|
||||
| ABB120 URDF fixture | `/home/meswork/kdl_work/kdl-wasm/web/tests/fixtures/abbIrb120.ts` |
|
||||
| URDF 来源记录 | ROS-Industrial `abb_irb120_support/urdf/irb120_3_58.xacro` |
|
||||
| 当前集成测试参考 | `/home/meswork/kdl_work/kdl-wasm/web/tests/integration/abb120Programs.test.ts` |
|
||||
| 虚拟控制器现有实现 | `/home/meswork/kdl_work/kdl-wasm/web/src/controller` |
|
||||
| 工作台 facade 现有实现 | `/home/meswork/kdl_work/kdl-wasm/web/src/workbench` |
|
||||
| 后处理现有实现 | `/home/meswork/kdl_work/kdl-wasm/web/src/grl/post` |
|
||||
|
||||
ABB RobotStudio 对标依据使用 ABB 官方公开资料。需求只对标信息架构和工程工作流，不复制 ABB 商标、图标、配色或专有视觉。
|
||||
|
||||
| 对标资料 | 链接 |
|
||||
| --- | --- |
|
||||
| RobotStudio Suite 官方页面 | `https://new.abb.com/products/robotics/software-a-digital/robotstudio` |
|
||||
| RobotStudio Operating Manual 2026.2 | `https://search.abb.com/library/Download.aspx?Action=Launch&DocumentID=3HAC032104-001&DocumentPartId=&LanguageCode=en` |
|
||||
| ABB Robotics downloads | `https://www.abb.com/global/en/areas/robotics/downloads` |
|
||||
|
||||
## 3. 文档入口
|
||||
|
||||
| 文件 | 用途 |
|
||||
| --- | --- |
|
||||
| `01-项目功能内容.md` | 需求范围、ABB120 测试程序集、运行链路、跨品牌输出、离线编程测试和 HTML 虚拟控制器功能。 |
|
||||
| `02-项目程序开发详细步骤.md` | 从运算表达式、fixture、测试程序、运行器、后处理、报告到 HTML UI 的实施步骤。 |
|
||||
| `03-推进台账.md` | 记录每轮做了什么、改了哪些文件、验证了什么、下一步是什么。 |
|
||||
| `04-任务矩阵.md` | 所有任务编号、状态、依赖、验收标准，防止重复做。 |
|
||||
| `05-验收证据.md` | 命令、页面、job_id、report_id、PDF、截图、日志和产物路径。 |
|
||||
| `06-决策记录.md` | 固化关键设计取舍，避免后续反复争论同一问题。 |
|
||||
|
||||
## 4. 任务编号
|
||||
|
||||
`A120-###` 是本目录的任务编号前缀：
|
||||
|
||||
| 编号范围 | 主题 |
|
||||
| --- | --- |
|
||||
| `GRL-EXPR-000` 到 `GRL-EXPR-099` | GRL 运算表达式、常量求值、单位系统、motion/path/IO 接入和三品牌表达式报告。 |
|
||||
| `A120-000` 到 `A120-009` | 文档、基准资产、测试数据规范。 |
|
||||
| `A120-010` 到 `A120-029` | ABB120 通用机器人测试程序。 |
|
||||
| `A120-030` 到 `A120-049` | 程序运行、KDL、虚拟控制器和调试。 |
|
||||
| `A120-050` 到 `A120-069` | 跨品牌后处理、导入回读和差异报告。 |
|
||||
| `A120-070` 到 `A120-089` | 离线编程全面测试、报告、交付包。 |
|
||||
| `A120-090` 到 `A120-109` | HTML 虚拟控制器界面。 |
|
||||
| `A120-900` 到 `A120-999` | 全量验收、CI、证据归档。 |
|
||||
|
||||
## 5. 当前状态
|
||||
|
||||
当前 `working1` 任务矩阵已全部完成：
|
||||
|
||||
1. `GRL-EXPR-001` 到 `GRL-EXPR-006` 已实现并通过测试。
|
||||
2. `A120-001` 到 `A120-900` 已实现或用自动化证据覆盖。
|
||||
3. 全量验证命令 `npm run typecheck`、`npm test`、`cmake --build kdl-wasm/build-wasm -j16`、`npm run verify:virtual-controller` 均通过。
|
||||
4. `working2` 当前为空任务集，已在 `working2/README.md` 记录审计结论。
|
||||
Reference in New Issue
Block a user