wangdequan/KDL_WORK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add ABB120 demo suite and docs

Browse Source
This commit is contained in:
wangdequan
2026-06-28 20:58:18 +08:00
parent 84a5b54195
commit 65187499d6
820 changed files with 215410 additions and 211 deletions
Download Patch File Download Diff File Expand all files Collapse all files

216
working2/01-项目功能内容.md Normal file
View File

@@ -0,0 +1,216 @@
# 01-项目功能内容
版本：0.1
日期：2026-06-28
## 1. 总体需求
目标是对标 `通用机器人编程语法规范.md`，以 ABB IRB120 3/58 URDF fixture 为基础，创建一套覆盖 GRL 语法规范的机器人程序集，并全面完成虚拟控制器执行验收。
核心结果：
1. 语法规范覆盖矩阵：每个 GRL 章节都有对应程序、静态测试或后处理测试。
2. ABB120 机器人程序集：覆盖数据声明、表达式、工具/坐标、目标点、速度、zone、运动、path、operation、IO/wait、流程控制、proc/func、异常、品牌扩展和后处理。
3. 虚拟控制器执行报告：每个可执行程序都能生成 controller state、program counter、motion queue、trace、IO image、wait/alarm、source map 和 trajectory 证据。
4. 错误诊断套件：限位、不可达、表达式错误、单位错误、wait timeout、重复符号、非法控制流等故障必须稳定输出 diagnostic。
5. 三品牌输出与回读：同一 IR 输出 ABB RAPID、FANUC LS 风格、KUKA KRL 风格，并生成 post/roundtrip 差异报告。
6. 服务器演示包：把虚拟控制器网站、19 个 GRL 规范测试程序、最新 W2 job 证据包、截图和使用说明打包发布到 HTTPS 服务器，用户可通过浏览器演示虚拟控制器全部功能。
## 2. 覆盖分层
不是所有语法都应强行作为虚拟控制器 happy path 执行。覆盖分为三层：
| 层级 | 范围 | 验收方式 |
| --- | --- | --- |
| Runtime | `module/proc/main`、数据、表达式、target、speed、zone、movej/movel/movec、path、operation、IO、wait、pulse、if/while/for/switch、call/return、alarm/raise/try | 虚拟控制器加载并执行，输出 trace 和状态快照。 |
| Static | `func` 副作用限制、参数方向、scope、label/jump 合法性、switch case 常量、表达式诊断、trap/interrupt/task 语义边界 | parser/semantic diagnostic 和 source map。 |
| Post | `post_hint`、`@brand.*`、ABB/FANUC/KUKA 映射、导入回读、runtime 表达式保真边界 | post report、roundtrip report、差异报告。 |
## 3. ABB120 基准
ABB120 基准沿用仓库稳定 fixture：
| 项 | 值 |
| --- | --- |
| robotId | `abb_irb120_3_58` |
| URDF 常量 | `ABB_IRB120_3_58_URDF` |
| load options | `ABB_IRB120_LOAD_OPTIONS` |
| baseLink | `base_link` |
| tipLink | `tool0` |
| active joints | `joint_1` 到 `joint_6` |
| 标准关节位 | `home`、`approach`、`pick`、`place` |
程序中的 reachable pose target 应优先由 ABB120 FK 生成并固化为 snapshot。不可达 pose、限位和奇异姿态只进入 error suite。
## 4. 机器人程序集
程序集建议落在：
```text
kdl-wasm/web/tests/fixtures/abb120/spec-programs/
runtime/
static/
post/
error/
expected/
```
### 4.1 Runtime happy path
| 程序 | 覆盖目标 |
| --- | --- |
| `W2_00_MinimalModule.grl` | language、module、proc main、const speed/zone、movej。 |
| `W2_10_DataTargetToolFrame.grl` | tool、frame、load、joint_target、pose_target、pose、poseq、robot_config、ext_axis 边界。 |
| `W2_20_ExpressionMath.grl` | 算术、比较、逻辑、单位后缀、pi/e、三角函数、数值函数、编译期求值。 |
| `W2_30_MotionAllTypes.grl` | movej、movel、movec、set_tool、set_frame、set_speed、set_zone、inline speed/zone。 |
| `W2_40_PathEvents.grl` | path defaults/source、point、event before/after/at distance、run_path。 |
| `W2_50_OperationProcess.grl` | operation kind/process/start_action/end_action/run_operation。 |
| `W2_60_IOWaitPulse.grl` | io 地址、DO 写入、wait、timeout、on_timeout、pulse、all/any/rising/falling/changed。 |
| `W2_70_ControlFlow.grl` | if/elseif/else、while、for、switch、break、continue。 |
| `W2_80_ProcFuncCall.grl` | proc 参数、in/out/inout、call、return、func 返回值和函数调用表达式。 |
| `W2_90_ExceptionAlarm.grl` | alarm、raise、try/catch/finally 可执行边界。 |
| `W2_99_FullSpecExample.grl` | 完整示例的 tool/frame、path、operation、IO event、run_operation 和回 home。 |
### 4.2 Static/error suite
| 程序 | 覆盖目标 |
| --- | --- |
| `W2_E10_ExpressionDiagnostics.grl` | `GRL_EXPR_PARSE/DOMAIN/DIV_ZERO/UNIT_MISMATCH/NON_CONSTANT/UNKNOWN_*`。 |
| `W2_E20_SemanticDiagnostics.grl` | 重复符号、缺失引用、类型不匹配、非法 out/inout 实参。 |
| `W2_E30_MotionDiagnostics.grl` | 关节限位、不可达 pose、movec 共线、缺少 tool/frame/speed/zone。 |
| `W2_E40_ControlFlowDiagnostics.grl` | 非法 break/continue、jump 进入块、重复 case、非常量 case。 |
| `W2_E50_RuntimeTimeout.grl` | wait timeout、on_timeout alarm/call、trace 和报警 source map。 |
### 4.3 Post/import suite
| 程序 | 覆盖目标 |
| --- | --- |
| `W2_P10_BrandHints.grl` | `post_hint`、`@brand.abb/fanuc/kuka` 元数据和转换报告。 |
| `W2_P20_CrossBrandMotion.grl` | ABB/FANUC/KUKA 的 move、speed、zone、IO、wait 映射。 |
| `W2_P30_Roundtrip.grl` | post 后重新导入，比较 target/path/motion/operation 等价性。 |
## 5. 虚拟控制器执行要求
每个 runtime 程序必须执行以下控制器命令序列：
1. `loadProgram`
2. `start`
3. `stepInto`
4. `hold`
5. `resume`
6. `stepMotion`
7. `stop`
8. `resetFault`
每次运行必须输出：
| 证据 | 内容 |
| --- | --- |
| `job.json` | job_id、suite_id、program_id、robot_id、git revision、输入文件 hash。 |
| `compile.json` | AST/IR 摘要、diagnostics、source map 统计。 |
| `controller.json` | 状态机转换、mode、program pointer、scope、变量快照。 |
| `motion-queue.json` | 队列项、activeIndex、duration、blend、planner diagnostic。 |
| `trace.json` | motion、IO、wait、pulse、alarm、call/return、source map。 |
| `io.json` | DI/DO/AI/AO/GI/GO/RI/RO 初值、脚本变化和最终状态。 |
| `trajectory.json` | 采样点数、起止关节、TCP 路径、限位和奇异诊断。 |
| `report.html/json` | 汇总报告、失败摘要、可追溯链接。 |
## 6. 全面验收
验收不只看测试通过，还必须证明“覆盖了语法规范”：
1. `programs/manifest.md` 中每个规范章节至少有一项程序或测试覆盖。
2. 每个 Runtime 程序有虚拟控制器执行证据。
3. 每个 Static/error 程序有稳定 diagnostic。
4. 每个 Post/import 程序有 post report 或 roundtrip report。
5. HTML 虚拟控制器可以打开 ABB120 suite 最新 job，显示程序、队列、trace、IO、wait、报警和报告。
## 7. 服务器演示包功能要求
服务器演示包用于对外展示虚拟控制器能力，不能只发布静态 HTML。包内必须包含可被页面读取和人工检查的测试程序、运行证据和说明文档。
### 7.1 发布目标
| 项 | 值 |
| --- | --- |
| HTTPS 访问地址 | `https://82.156.24.101:8095/` |
| 服务端口 | `8095` |
| 推荐服务器目录 | `/opt/kdl-olp-demo/8095/current` |
| 发布包归档目录 | `/opt/kdl-olp-demo/8095/releases/<release_id>` |
| 回滚链接 | `/opt/kdl-olp-demo/8095/previous` 或保留上一个 release 目录 |
### 7.2 演示包内容
```text
demo-package/
app/
virtual-controller.html
virtual-controller.css
virtual-controller.js
spec-programs/
manifest.json
runtime/*.grl
static/*.grl
error/*.grl
post/*.grl
test-results/
abb120-spec/<latest-job>/
job.json
report.json
report.html
programs/<program_id>/*.json
virtual-controller/
evidence.json
virtual-controller-desktop.png
virtual-controller-mobile.png
docs/
GRL功能语法逻辑与程序创建使用手册.docx
通用机器人离线编程系统测试文档.docx
index.html
demo-manifest.json
README.md
```
### 7.3 演示能力清单
| 能力 | 演示程序或证据 |
| --- | --- |
| 最小加载和 MoveJ | `W2_00_MinimalModule.grl` |
| 数据、目标点、工具和坐标系 | `W2_10_DataTargetToolFrame.grl` |
| 表达式、单位和数学函数 | `W2_20_ExpressionMath.grl` |
| MoveJ/MoveL/MoveC | `W2_30_MotionAllTypes.grl` |
| Path 和事件 | `W2_40_PathEvents.grl` |
| Operation 工艺封装 | `W2_50_OperationProcess.grl` |
| IO、wait、pulse、边沿 | `W2_60_IOWaitPulse.grl` |
| 流程控制 | `W2_70_ControlFlow.grl` |
| proc/func/call/return | `W2_80_ProcFuncCall.grl` |
| 异常和报警 | `W2_90_ExceptionAlarm.grl` |
| 完整示例 | `W2_99_FullSpecExample.grl` |
| 表达式错误诊断 | `W2_E10_ExpressionDiagnostics.grl` |
| 语义错误诊断 | `W2_E20_SemanticDiagnostics.grl` |
| 运动错误诊断 | `W2_E30_MotionDiagnostics.grl` |
| 控制流错误诊断 | `W2_E40_ControlFlowDiagnostics.grl` |
| wait timeout | `W2_E50_RuntimeTimeout.grl` |
| 品牌 hint/post report | `W2_P10_BrandHints.grl` |
| 跨品牌 motion/IO/wait 输出 | `W2_P20_CrossBrandMotion.grl` |
| post 后导入回读 | `W2_P30_Roundtrip.grl` |
### 7.4 页面演示要求
1. 首页必须能进入虚拟控制器页面。
2. 页面必须能看到当前 suite、job_id、程序数量、通过/诊断/失败统计。
3. 页面必须列出 19 个程序，并支持查看源码或证据摘要。
4. 对 Runtime 程序，必须能展示 controller commands、trace、motion queue、IO image、trajectory。
5. 对 Static/error 程序，必须能展示 expected diagnostics 和实际 diagnostics。
6. 对 Post 程序，必须能展示 ABB/FANUC/KUKA 文件名、post report 和 roundtrip 状态。
7. 页面必须保留桌面和移动端截图证据，便于远程验收。
### 7.5 验收结论口径
只有同时满足以下条件，服务器演示包才可以标记为通过：
1. 本地 `npm run typecheck`、`npm test`、`npm run suite:abb120-spec`、`npm run verify:virtual-controller` 通过。
2. 演示包包含 19 个 `.grl` 程序和最新 `W2-JOB-*` 证据。
3. 远程 `https://82.156.24.101:8095/` 可打开，无证书阻断以外的页面错误。
4. 远程页面能访问 `demo-manifest.json`、`report.json`、`virtual-controller.html` 和截图文件。
5. 远程 smoke test 记录到 `working2/05-验收证据.md`。

378
working2/02-项目程序开发详细步骤.md Normal file
View File

@@ -0,0 +1,378 @@
# 02-项目程序开发详细步骤
版本：0.1
日期：2026-06-28
## 1. 开发原则
1. 以 `通用机器人编程语法规范.md` 为覆盖源，不以现有测试数量作为完成标准。
2. ABB120 URDF 使用仓库内稳定 fixture，不引入未验证机器人模型。
3. happy path 必须可执行；error path 必须可诊断；post path 必须可报告。
4. 虚拟控制器只执行 Semantic IR，不直接解释品牌文本。
5. 所有新增程序都要保留 source map，报告必须能定位到 GRL 文件行列。
## 2. 阶段 0：规范覆盖矩阵
### W2-SPEC-001：解析语法规范章节
步骤：
1. 从 `work/doc/通用机器人编程语法规范.md` 抽取章节、关键语法、示例和语义规则。
2. 建立 coverage item，字段包含 `spec_section`、`syntax`、`runtime_level`、`program_id`、`test_id`、`evidence`。
3. 把覆盖矩阵写入 `working2/programs/manifest.md`。
验收：章节 4 到 23 均有覆盖项；章节 25 的 P0 项全部映射到 runtime 或 static 测试。
### W2-SPEC-002：定义执行边界
步骤：
1. 标记虚拟控制器必须执行的 Runtime 语义。
2. 标记只做 semantic diagnostic 的 Static 语义。
3. 标记只做后处理/导入报告的 Post 语义。
4. 对 trap、interrupt、task、brand metadata 等非 P0 执行项写清楚边界。
验收：覆盖矩阵中每项都有 `Runtime/Static/Post` 分类，不允许空白。
## 3. 阶段 1：ABB120 程序集
### W2-PROG-001：建立 spec-programs 目录
建议目录：
```text
kdl-wasm/web/tests/fixtures/abb120/spec-programs/
runtime/
static/
error/
post/
expected/
```
验收：测试 helper 可以枚举所有 `.grl` 并读取 manifest。
### W2-PROG-010：Runtime 程序
步骤：
1. 创建 `W2_00` 到 `W2_90` 十个 runtime 程序，并以 `W2_99_FullSpecExample` 覆盖第 24 章完整示例。
2. 所有运动目标使用 ABB120 标准关节位或 FK 固化 pose。
3. 每个程序顶部注释写明覆盖的 spec section。
4. 每个程序必须可 parse、compile、load 到虚拟控制器。
验收：runtime 程序全部生成 AST/IR/source map snapshot。
### W2-PROG-020：Static/error 程序
步骤：
1. 创建表达式、语义、运动、控制流、runtime timeout 五类 error 程序。
2. 每个 error 程序只聚焦一类错误，避免多个错误互相遮蔽。
3. expected diagnostic 固化 `code/severity/message/sourceRange`。
验收：diagnostic snapshot 稳定，新增或消失的错误会导致测试失败。
### W2-PROG-030：Post/import 程序
步骤：
1. 创建品牌 hint 和跨品牌 motion 程序。
2. 覆盖 ABB/FANUC/KUKA speed、zone、IO、wait、operation 输出。
3. 固化 roundtrip 输入和差异报告。
验收：三品牌输出非空，近似和不支持项进入 report。
## 4. 阶段 2：编译和 KDL 验证
### W2-RUN-001：统一 suite runner
步骤：
1. 扩展或新增 `runAbb120SpecSuite`。
2. 输入：program root、suite id、ABB120 fixture、output root。
3. 输出：`job_id`、程序 manifest、每个程序的 compile/run/post 结果。
4. job id 格式：`W2-JOB-YYYYMMDD-HHMMSS-<short-hash>`。
验收：单条命令可生成完整 suite 证据目录。
### W2-RUN-010：编译链路
步骤：
1. `parseGrl` 生成 AST。
2. `compileSemanticProgram` 生成 IR。
3. 对 data/target/path/operation 建 source map 索引。
4. 保存 AST/IR 摘要，不保存过大的重复文本。
验收：每个 runtime/post 程序 compile 无 error；每个 error 程序 compile 输出预期 diagnostic。
### W2-RUN-020：ABB120 KDL 检查
步骤：
1. 加载 ABB120 URDF。
2. 对所有 joint target 做 limit check。
3. 对所有 pose target 做 IK 或记录当前实现边界 diagnostic。
4. 对每条 motion/path 生成 planner request。
验收：happy path 没有关节限位错误；不可达或不支持 IK 只能出现在 error suite。
## 5. 阶段 3：虚拟控制器执行
### W2-RUN-030：状态机命令覆盖
步骤：
1. 对每个 runtime 程序执行 `load/start/step/hold/resume/stepMotion/stop/resetFault`。
2. 记录每次命令前后状态。
3. 非法命令转移必须产生明确 diagnostic。
验收：状态机转换符合控制器规则，trace 可回放。
### W2-RUN-040：Motion Queue 和轨迹
步骤：
1. 将 `movej/movel/movec/run_path/run_operation` 展开到 motion queue。
2. 记录 queue item、activeIndex、duration、planner result。
3. 对轨迹采样点做 limit 和 singularity 检查。
验收：motion queue 与程序 source map 对齐；轨迹结果可进入报告。
### W2-RUN-050：IO、wait、pulse 和报警
步骤：
1. 为 `W2_60_IOWaitPulse` 注入 DI 脚本。
2. 覆盖 wait satisfied、waiting、timeout、on_timeout alarm/call。
3. 覆盖 pulse 自动复位。
4. 覆盖 all/any/rising/falling/changed。
验收：trace 中可看到 IO 写入、DI 变化、wait 状态、pulse reset 和 alarm。
### W2-RUN-060：流程控制和调用栈
步骤：
1. 执行 if/elseif/else、while、for、switch。
2. 记录局部变量、循环变量、call stack、return。
3. out/inout 参数回写进入变量快照。
验收：最终变量状态符合预期，source map 可定位当前执行语句。
## 6. 阶段 4：后处理和导入回读
### W2-POST-010：三品牌 post
步骤：
1. 对 runtime/post 程序调用 `postProcessAllBrands`。
2. 保存 ABB `.mod`、FANUC `.ls`、KUKA `.src/.dat`。
3. 保存 post report，记录近似和 unsupported。
验收：所有品牌输出包含对应 motion、IO、wait 和 proc 结构。
### W2-POST-020：roundtrip
步骤：
1. 将三品牌输出重新导入。
2. 对比 motion 顺序、target 数量、path/operation 结构。
3. 对差异生成 `roundtrip.json`。
验收：happy path 结构等价；不可逆项全部进入 diff。
## 7. 阶段 5：HTML 虚拟控制器验收
### W2-UI-010：加载最新 job
步骤：
1. HTML 页面支持选择或加载 `W2-JOB-*` 证据。
2. 显示程序列表、当前程序、controller snapshot、queue、trace、diagnostics。
3. 点击 trace/source map 能定位 GRL 行。
验收：页面能展示 working2 suite 证据，不只展示静态 mock 数据。
### W2-UI-020：截图验证
步骤：
1. 使用现有 `verify-virtual-controller.mjs` 或新增参数打开 working2 job。
2. 截桌面和移动视口。
3. 检查 command bar、object tree、viewport、pendant、editor、bottom panel 可见。
4. 检查无横向溢出和文字重叠。
验收：生成 desktop/mobile 截图和 `evidence.json`。
## 8. 阶段 6：全量 CI
建议命令：
```powershell
cd E:\Work\kdl_work
npm run typecheck
npm test -- grl abb120 virtual controller runtime post import
npm run verify:virtual-controller
```
如果需要 WASM native 验证：
```powershell
cmake --build kdl-wasm/build-wasm -j16
```
验收：所有命令通过，`working2/05-验收证据.md` 记录实际命令、时间、job_id、report_id 和产物路径。
## 9. 阶段 7：服务器演示包和 HTTPS 发布
### W2-DEPLOY-001：生成演示包 manifest
步骤：
1. 读取 `kdl-wasm/web/tests/fixtures/abb120/spec-programs/manifest.json`。
2. 读取最新 `kdl-wasm/web/test-results/abb120-spec/W2-JOB-*`。
3. 读取 `kdl-wasm/web/test-results/virtual-controller/evidence.json`。
4. 生成 `demo-manifest.json`，字段至少包含：
- `release_id`
- `generated_at`
- `suite_id`
- `job_id`
- `program_count`
- `programs`
- `report_json`
- `virtual_controller_entry`
- `screenshots`
- `docs`
5. manifest 中路径必须是相对发布根目录的 URL 路径，不能写本机绝对路径。
验收：`demo-manifest.json` 可被浏览器直接打开，能定位 19 个程序、最新报告和截图。
### W2-DEPLOY-010：收集演示包文件
建议目录：
```text
kdl-wasm/web/test-results/deploy/kdl-olp-demo-<release_id>/
app/
spec-programs/
test-results/
docs/
index.html
demo-manifest.json
README.md
```
步骤：
1. 复制 `kdl-wasm/web/app/virtual-controller.html/css/js` 到 `app/`。
2. 复制 `spec-programs/manifest.json` 和所有 `.grl` 程序。
3. 复制最新 W2 job 目录。
4. 复制虚拟控制器截图和 `evidence.json`。
5. 复制 Word 手册和测试文档：
- `work/doc/GRL功能语法逻辑与程序创建使用手册.docx`
- `work/doc/通用机器人离线编程系统测试文档.docx`
6. 生成 `index.html`，至少提供：
- 虚拟控制器入口
- 最新 job 报告入口
- 程序清单入口
- 截图入口
- 文档下载入口
验收：本地打开发布包根目录时，所有链接不依赖开发机绝对路径。
### W2-DEPLOY-020：打包发布归档
步骤：
1. 将演示包目录压缩为 `kdl-olp-demo-<release_id>.zip`。
2. 计算 zip 文件大小和 hash。
3. 将 zip、release_id、job_id 写入 `working2/05-验收证据.md`。
验收：zip 可解压，解压后包含 `index.html`、`demo-manifest.json`、19 个 `.grl` 和最新 job。
### W2-DEPLOY-030：上传到服务器
目标：
```text
https://82.156.24.101:8095/
/opt/kdl-olp-demo/8095/releases/<release_id>
/opt/kdl-olp-demo/8095/current -> releases/<release_id>
```
步骤：
1. 使用 `scp` 或等效方式上传 zip 到服务器临时目录。
2. 在服务器创建 release 目录并解压。
3. 更新 `current` 软链接指向新 release。
4. 确认 Web 服务根目录指向 `current`。
5. 不在仓库文档中记录服务器密码；凭据只保留在部署人员本地。
验收：服务器上存在 release 目录，`current` 指向最新 release。
### W2-DEPLOY-040：HTTPS 服务验证
步骤：
1. 打开 `https://82.156.24.101:8095/`。
2. 验证 `index.html` 能加载。
3. 验证以下 URL 可访问：
- `/demo-manifest.json`
- `/app/virtual-controller.html`
- `/test-results/abb120-spec/<job_id>/report.json`
- `/test-results/abb120-spec/<job_id>/report.html`
- `/test-results/virtual-controller/virtual-controller-desktop.png`
- `/spec-programs/manifest.json`
4. 在浏览器中进入虚拟控制器页面，检查页面显示 suite/job/program/trace/queue/IO/diagnostics。
5. 如证书为自签名，记录浏览器安全提示为环境说明，不作为功能失败；如页面资源 404 或 JS 错误，则发布失败。
验收：远程页面可演示 19 个程序和最新 job 证据。
### W2-DEPLOY-050：远程 smoke test
建议命令：
```powershell
$base = "https://82.156.24.101:8095"
curl.exe -k "$base/"
curl.exe -k "$base/demo-manifest.json"
curl.exe -k "$base/spec-programs/manifest.json"
curl.exe -k "$base/app/virtual-controller.html"
curl.exe -k "$base/test-results/abb120-spec/<job_id>/report.json"
```
检查：
1. HTTP 状态为 200。
2. `demo-manifest.json` 中 `program_count` 为 19。
3. `report.json` 中 `fail` 为 0。
4. 页面资源无 404。
验收：命令输出摘要写入 `working2/05-验收证据.md`。
### W2-DEPLOY-060：回滚
步骤：
1. 服务器保留至少最近 2 个 release。
2. 新版本验证失败时，将 `current` 重新指向上一个 release。
3. 再次访问 `https://82.156.24.101:8095/` 验证旧版本恢复。
4. 在 `working2/03-推进台账.md` 记录回滚原因和 release_id。
验收：回滚后远程页面恢复到上一个可用版本。
## 10. 后续完善程序时的固定流程
每次新增或修改虚拟测试程序，都按以下顺序推进：
1. 修改 `.grl` 程序和 `spec-programs/manifest.json`。
2. 更新 `working2/programs/manifest.md` 的覆盖矩阵。
3. 执行 `npm run typecheck`。
4. 执行 `npm test`。
5. 执行 `npm run suite:abb120-spec`，生成新 `W2-JOB-*`。
6. 执行 `npm run verify:virtual-controller`，刷新截图。
7. 重新生成 Word 测试文档和 GRL 使用手册，如内容发生变化。
8. 重新生成服务器演示包并发布到 HTTPS。
9. 更新 `working2/03-推进台账.md`、`04-任务矩阵.md`、`05-验收证据.md`。
10. 提交代码并上传云仓库。

183
working2/03-推进台账.md Normal file
View File

@@ -0,0 +1,183 @@
# 03-推进台账
版本：0.1
日期：2026-06-28
## 轮次 001：创建 working2 任务整合包
### 本轮目标
根据用户要求，将“对标 `通用机器人编程语法规范.md`、以 ABB120 URDF 为基础创建覆盖语法规范的机器人程序集、全面完成虚拟控制器执行测试”的功能任务整合到 `working2`，并参考 `working1` 的文档组织方式。
### 已读取和确认
1. `working2` 原本只有 `README.md`，内容为“空任务集审计”。
2. `working1` 已有 ABB120 fixture、GRL 程序集、运算表达式、虚拟控制器、后处理、验收证据和决策记录的完整文档。
3. 当前语法规范已包含新增的 `## 7. 表达式与运算`，并顺延到 `## 26. 参考资料`。
4. 仓库中已有 `kdl-wasm/web/src/fixtures/abb120.ts`、`kdl-wasm/web/tests/fixtures/abb120/programs`、`kdl-wasm/web/src/suites/abb120Suite.ts`、`kdl-wasm/web/app/virtual-controller.html/css/js`。
### 本轮产出
1. 重写 `working2/README.md`。
2. 新增 `working2/01-项目功能内容.md`。
3. 新增 `working2/02-项目程序开发详细步骤.md`。
4. 新增 `working2/04-任务矩阵.md`。
5. 新增 `working2/05-验收证据.md`。
6. 新增 `working2/06-决策记录.md`。
7. 新增 `working2/programs/manifest.md`。
### 当前边界
1. 本轮只做任务整合和实施规范，不新增产品代码和 `.grl` 程序文件。
2. `working2` 的任务状态默认 `Todo`，不沿用 `working1` 的 `Done` 状态。
3. 已有 `working1` 实现可以作为依赖和参考，但 `working2` 必须按完整语法规范重新证明覆盖。
4. trap、interrupt、task、brand metadata 不强行列入虚拟控制器 happy path；使用 static/post 证据覆盖。
### 下一步
1. 创建 `kdl-wasm/web/tests/fixtures/abb120/spec-programs` 目录和首批 `W2_*.grl`。
2. 实现 `runAbb120SpecSuite` 或扩展 `runAbb120Suite` 支持 working2 manifest。
3. 添加 coverage test，确保 `manifest.md` 中每个 spec section 有对应程序和证据。
4. 执行 `npm test -- grl abb120 virtual controller runtime post import` 并记录实际结果。
## 轮次 002：实现 working2 程序集、runner 和验收证据
### 本轮目标
把轮次 001 的任务包落到仓库实现：创建 ABB120 spec-programs 程序集，新增 W2 suite runner，接入测试、HTML 页面和证据包生成命令。
### 本轮产出
1. 新增 `kdl-wasm/web/tests/fixtures/abb120/spec-programs/manifest.json`。
2. 新增 `runtime/W2_00` 到 `runtime/W2_90` 共 10 个 runtime 程序。
3. 新增 `static/error` 诊断程序 `W2_E10` 到 `W2_E50` 共 5 个，其中 `W2_E50` 作为 runtime timeout error 进入 Runtime 层级。
4. 新增 `post/W2_P10` 到 `post/W2_P30` 共 3 个 post/import 程序。
5. 新增 `kdl-wasm/web/src/suites/abb120SpecSuite.ts` 和 `kdl-wasm/web/scripts/run-abb120-spec-suite.ts`。
6. 新增 `kdl-wasm/web/tests/integration/abb120SpecSuite.test.ts`。
7. 更新 HTML 虚拟控制器显示 `working2-abb120-spec` 和 `W2-JOB-latest`。
8. 修复 `compileIo` 在 wait 无 `on_timeout` 时越界的问题；控制流 parser 对 `try` 块改为 raw boundary，由 exception parser 负责异常语义。
### 验收摘要
1. `npm run suite:abb120-spec` 通过，生成 `W2-JOB-20260628013857-19b5a2c7`。
2. `npm run typecheck` 通过。
3. `npm test` 通过，41 个测试文件、155 个测试。
4. `npm run verify:virtual-controller` 通过，生成桌面和移动截图。
### 当前边界
1. `trap`、`interrupt`、`task` 仍按 P1 unsupported/runtime boundary 记录 warning，不作为 happy path 实时执行。
2. `@brand.*` 语法尚未作为 lexer/parser 原生结构实现，本轮以后处理 `post_hint` 和 report 边界覆盖品牌扩展。
3. W2 runner 的 motion trajectory 使用同步 fixture planner 生成审计证据；真实 ABB120 KDL 规划仍由既有 `abb120Programs.test.ts` 覆盖。
## 轮次 003：补齐完整示例和 manifest 机器校验
### 本轮目标
接续轮次 002，对 working2 的“文档已 Done 但机器校验不足”部分做收口：把规范第 24 章完整示例落为实际 runtime 程序，并让 manifest 的层级、程序引用、预期诊断和 job 结果成为自动测试合同。
### 本轮产出
1. 新增 `runtime/W2_99_FullSpecExample.grl`，覆盖完整示例的 tool/frame、path、operation、IO event、run_operation 和回 home。
2. 更新 `spec-programs/manifest.json`，程序总数为 19；coverage 章节 4 到 25 缺失为空；层级统计 Runtime 12、Static 4、Post 3。
3. 强化 `abb120SpecSuite.test.ts`，检查 coverage matrix 引用存在、层级自一致、expected status 和 expected diagnostics 全部出现在 job 结果中。
4. 强化 `runAbb120SpecSuite` 静态预检，补充表达式、多 motion/KDL 边界、proc/function 和 control-flow 多诊断采集。
5. 新增最新证据包 `W2-JOB-20260628022836-51484d62`。
### 验收摘要
1. `npm test -- abb120SpecSuite` 通过。
2. `npm run typecheck` 通过。
3. `npm run suite:abb120-spec` 通过，生成 19 个程序的 job，missingSections 为空。
### 当前边界
1. `@brand.*` 仍为后续 parser 原生语法扩展边界，当前通过 `post_hint` 和 post report 覆盖。
2. suite runner 的 KDL 诊断仍使用同步 fixture planner；真实 KDL/URDF 规划由既有 ABB120 集成测试覆盖。
## 轮次 004：补充服务器演示包和 HTTPS 发布实施文档
### 本轮目标
根据“虚拟测试程序打包到服务器，能通过这些程序演示虚拟控制器全部功能”的要求，完善 `working2` 实施文档，形成后续程序完善、打包、发布、远程验收和回滚的固定流程。
### 本轮产出
1. 更新 `working2/README.md`，增加服务器演示包目标、文档入口和 `W2-DEPLOY-*` 任务范围。
2. 更新 `working2/01-项目功能内容.md`，增加服务器演示包功能要求、发布目标、包内容、演示能力清单和验收口径。
3. 更新 `working2/02-项目程序开发详细步骤.md`，增加阶段 7：演示包 manifest、文件收集、zip、上传、HTTPS 验证、远程 smoke test 和回滚。
4. 更新 `working2/04-任务矩阵.md`，新增 `W2-DEPLOY-001` 到 `W2-DEPLOY-060` 任务和子任务。
5. 更新 `working2/05-验收证据.md`，新增部署证据项、远程 smoke test 命令、发布记录模板和人工验收模板。
6. 新增 `working2/07-服务器发布与演示包实施方案.md`，作为发布实施主文档。
7. 更新 `working2/06-决策记录.md`，新增服务器发布包 ADR。
### 当前边界
1. 本轮只完善项目实施文档，没有实际上传服务器。
2. 服务器凭据不写入仓库文档；文档只记录发布地址、端口、目录规范和验收要求。
3. 后续需要新增 `build-demo-package.mjs`、`verify-demo-package.mjs`、`deploy-demo-package.ps1` 等脚本，才能把 `W2-DEPLOY-*` 推进到 Done。
4. HTTPS 证书若为自签名，浏览器安全提示记录为环境说明；资源 404、JS 错误或 report fail 非 0 才视为发布失败。
### 下一步
1. 实现演示包构建脚本，生成 `demo-manifest.json`、首页和 zip。
2. 实现本地 zip 校验脚本，检查 19 个程序、最新 job、截图和 Word 文档。
3. 上传到 `https://82.156.24.101:8095/` 对应服务器目录并执行远程 smoke test。
4. 将发布证据写入 `working2/05-验收证据.md`。
## 轮次 005：实现演示包自动化并发布 HTTPS 服务器
### 本轮目标
把轮次 004 文档中的 `W2-DEPLOY-*` 从待实现推进到可验收：生成服务器演示包、校验 zip、上传 HTTPS 服务器、切换 current、保留 previous 并完成远程 smoke test。
### 本轮产出
1. 新增 `kdl-wasm/web/scripts/build-demo-package.mjs`，收集虚拟控制器 app、19 个 `spec-programs`、最新 W2 job、截图、Word 文档和 working2 文档，生成 `demo-manifest.json`、`index.html`、README 和 zip。
2. 新增 `kdl-wasm/web/scripts/verify-demo-package.mjs`，解压 zip 并校验 19 个 `.grl`、`report.json`、截图、2 份 Word 文档、相对 URL 和 `summary.fail=0`。
3. 新增 `kdl-wasm/web/scripts/deploy-demo-package.ps1`，提供上传 zip、远程解压、切换 current、保留 previous 和 HTTPS smoke test 的可复用发布脚本。
4. 更新 `package.json`，新增 `npm run demo:build`、`npm run demo:verify`、`npm run demo:deploy`。
5. 修正演示包 zip 生成为跨平台 `/` 路径条目，避免 Windows zip 在 Linux `unzip` 后出现反斜杠路径。
6. 发布 release `20260628-120601-W2-JOB-20260628024709-51484d62` 到 `https://82.156.24.101:8095/`。
### 验收摘要
1. `npm run demo:build` 通过，生成 `kdl-wasm/web/test-results/deploy/kdl-olp-demo-20260628-120601-W2-JOB-20260628024709-51484d62.zip`。
2. `npm run demo:verify -- kdl-wasm/web/test-results/deploy/kdl-olp-demo-20260628-120601-W2-JOB-20260628024709-51484d62.zip` 通过，`program_count=19`、`.grl=19`、`summary.fail=0`。
3. 服务器 `/opt/kdl-olp-demo/8095/current` 指向 `/opt/kdl-olp-demo/8095/releases/20260628-120601-W2-JOB-20260628024709-51484d62`。
4. 服务器 `/opt/kdl-olp-demo/8095/previous` 指向 `/opt/kdl-olp-demo/8095/releases/20260628-120357-W2-JOB-20260628024709-51484d62`。
5. HTTPS smoke test 通过：`/`、`/demo-manifest.json`、`/spec-programs/manifest.json`、`/app/virtual-controller.html`、`report.json`、`report.html`、desktop/mobile png 全部返回 200。
### 当前边界
1. 8095 服务使用服务器现有自签名证书，浏览器可能提示证书风险；资源访问和报告验证已通过。
2. 发布时使用本地凭据完成服务器操作，但凭据不写入仓库脚本或 working2 文档。
## 轮次 006：补齐程序切换和逐帧 TCP/关节轨迹展示
### 本轮目标
回应远程页面验收问题：`/app/virtual-controller.html` 不能只展示静态模拟状态，必须能切换 19 个 W2 程序，并显示程序实际执行产物中的每一帧 TCP 和 6 轴关节值。
### 本轮产出
1. 更新 `runAbb120SpecSuite` 轨迹摘要，`trajectory.json` 新增 `frames[]`，每帧包含 `index`、`time`、`motion`、`segmentId/targetId`、`joints[6]`、`tcp.position[3]`、`tcp.quaternion[4]`、`sourceMap` 和 diagnostics。
2. 更新 `abb120SpecSuite.test.ts`，要求至少一个 Runtime 程序产出带 6 轴关节和 TCP 姿态的逐帧轨迹。
3. 重构 `virtual-controller.html/css/js`，页面从 `demo-manifest.json` 读取 19 个程序，通过顶部 Program 下拉切换程序；`Load/Run/Step` 操作当前程序轨迹帧；底部 `Trajectory Frames` 表格展示每帧 TCP XYZ、TCP Q 和 J1-J6。
4. 更新 `verify-demo-package.mjs`，新增 `runtime_trajectory_frames` 检查，防止发布包里的 Runtime 轨迹退化成只有摘要字段。
5. 修复 `deploy-demo-package.ps1`：函数调用顺序、远端命令拼接、服务重启、自签名 HTTPS smoke test 和 `previous` 回滚指针处理。
6. 重新生成 W2 job `W2-JOB-20260628082622-51484d62`，发布最终 release `20260628-164048-W2-JOB-20260628082622-51484d62` 到 `https://82.156.24.101:8095/`。
### 验收摘要
1. `npm run typecheck` 通过。
2. `npm test -- kdl-wasm/web/tests/integration/abb120SpecSuite.test.ts kdl-wasm/web/tests/integration/abb120SuiteArtifacts.test.ts` 通过。
3. `npm run suite:abb120-spec` 通过，生成 19 个程序的 job，missingSections 为空。
4. `npm run verify:virtual-controller` 通过；桌面/移动截图均无横向溢出，`Run` 后状态为 `running`，DI wait 为 `satisfied`。
5. `npm run demo:verify -- <final zip>` 通过，`runtime_trajectory_frames=9/12`。
6. 远程抽查通过：`W2_30_MotionAllTypes` 有 12 帧，`W2_60_IOWaitPulse` 有 4 帧，`W2_99_FullSpecExample` 有 32 帧，均包含 joints 和 TCP。
### 当前边界
1. 没有可规划运动段的 Runtime/Static/Post 程序不会伪造轨迹；页面显示 `NO_MOTION` 单帧占位，并保留编译、诊断、trace、post/roundtrip 产物。
2. 8095 HTTPS 仍使用现有自签名证书；自动 smoke test 使用不校验证书的发布验证路径。

88
working2/04-任务矩阵.md Normal file
View File

@@ -0,0 +1,88 @@
# 04-任务矩阵
版本：0.1
日期：2026-06-28
## 1. 状态定义
| 状态 | 含义 |
| --- | --- |
| Todo | 尚未开始实现。 |
| Doing | 正在执行。 |
| Blocked | 被依赖、环境或设计问题阻塞。 |
| Review | 已实现，等待复核或补证据。 |
| Done | 已实现且验收证据完整。 |
## 2. 任务总表
| 编号 | 任务 | 状态 | 依赖 | 验收标准 |
| --- | --- | --- | --- | --- |
| W2-SPEC-000 | 创建 working2 任务文档 | Done | 无 | README、功能、步骤、台账、矩阵、证据、决策、manifest 均存在。 |
| W2-SPEC-001 | 语法规范覆盖矩阵 | Done | W2-SPEC-000 | 规范章节 4 到 25 已映射到 Runtime/Static/Post 覆盖项。 |
| W2-SPEC-002 | 执行边界分类 | Done | W2-SPEC-001 | 每项语义已标明虚拟执行、静态诊断或后处理验收方式。 |
| W2-PROG-001 | 建立 spec-programs 目录 | Done | W2-SPEC-001 | runtime/static/error/post/expected 目录和 `manifest.json` 可被测试读取。 |
| W2-PROG-010 | Runtime 覆盖项 12 个 | Done | W2-PROG-001 | `W2_00` 到 `W2_99` happy path 和 `W2_E50` runtime timeout 可 parse、compile、load。 |
| W2-PROG-020 | Static/error 程序 5 类 | Done | W2-PROG-001 | 4 类 static diagnostic 和 1 类 runtime timeout 输出 stable diagnostic 证据。 |
| W2-PROG-030 | Post/import 程序 3 个 | Done | W2-PROG-001 | 三品牌输出和 roundtrip 差异可验证。 |
| W2-RUN-001 | ABB120 spec suite runner | Done | W2-PROG-010 | `npm run suite:abb120-spec` 输出 `W2-JOB-*` 证据目录。 |
| W2-RUN-010 | 编译链路证据 | Done | W2-RUN-001 | AST/IR 摘要、source map、diagnostics 产物完整。 |
| W2-RUN-020 | ABB120 KDL 检查 | Done | W2-RUN-001 | limit、reachability/边界和 planner request 结果可审计；真实 KDL 由既有 ABB120 集成测试覆盖。 |
| W2-RUN-030 | 虚拟控制器状态机覆盖 | Done | W2-RUN-010 | load/start/step/hold/resume/stepMotion/stop/resetFault 均有命令记录。 |
| W2-RUN-040 | Motion Queue 和轨迹证据 | Done | W2-RUN-020, W2-RUN-030 | queue、activeIndex、duration、trajectory、planner diagnostics 完整；Runtime 轨迹产物包含逐帧 joints[6] 和 TCP position/quaternion。 |
| W2-RUN-050 | IO/wait/pulse/alarm 执行 | Done | W2-RUN-030 | wait satisfied/timeout、pulse reset、边沿检测和报警可验证。 |
| W2-RUN-060 | 流程控制和调用栈执行 | Done | W2-RUN-030 | if/while/for/switch/call/return/out/inout 有编译和 runtime trace 证据。 |
| W2-POST-010 | 三品牌后处理 | Done | W2-PROG-030, W2-RUN-010 | ABB/FANUC/KUKA 输出和 post report 完整。 |
| W2-POST-020 | 品牌导入回读 | Done | W2-POST-010 | roundtrip diff 记录等价和不可逆项。 |
| W2-UI-010 | HTML 虚拟控制器加载 W2 job | Done | W2-RUN-001 | 页面从 demo-manifest 读取 19 个 W2 程序，支持 Program 下拉切换，并展示 suite/job、program、queue、trace、IO、diagnostics、report。 |
| W2-UI-020 | HTML 截图和交互验证 | Done | W2-UI-010 | desktop/mobile 截图、evidence.json、无横向溢出。 |
| W2-UI-030 | HTML 逐帧 TCP/关节展示 | Done | W2-RUN-040, W2-UI-010 | `Trajectory Frames` 表格展示当前程序每帧 time、motion、target、TCP XYZ、TCP Q 和 J1-J6；Run/Step/Frame slider 可切换当前帧。 |
| W2-DEPLOY-001 | 服务器演示包 manifest | Done | W2-RUN-001, W2-UI-020 | 已生成 `demo-manifest.json`，包含 release_id、job_id、19 个程序、报告、截图和文档入口，路径均为相对 URL。 |
| W2-DEPLOY-010 | 演示包文件收集 | Done | W2-DEPLOY-001 | 已包含 app、spec-programs、latest job、virtual-controller screenshots、Word 手册、测试文档和首页。 |
| W2-DEPLOY-020 | 演示包 zip 和校验 | Done | W2-DEPLOY-010 | 已生成并校验 `kdl-olp-demo-20260628-164048-W2-JOB-20260628082622-51484d62.zip`，解压后 19 个 `.grl`、`report.json`、逐帧轨迹、截图、文档均存在。 |
| W2-DEPLOY-030 | 上传服务器并切换 current | Done | W2-DEPLOY-020 | 服务器 `/opt/kdl-olp-demo/8095/current` 已指向最新 release，HTTPS 服务读取新包。 |
| W2-DEPLOY-040 | HTTPS 远程页面验证 | Done | W2-DEPLOY-030 | `https://82.156.24.101:8095/`、`demo-manifest.json`、`virtual-controller.html`、`report.json`、截图均返回 200。 |
| W2-DEPLOY-050 | 远程 smoke test 证据 | Done | W2-DEPLOY-040 | 远程验证结果已写入 `working2/05-验收证据.md`，`program_count=19` 且 `fail=0`。 |
| W2-DEPLOY-060 | 发布回滚机制 | Done | W2-DEPLOY-030 | 服务器保留 previous release 指针，最终部署前一版为 `20260628-163458-W2-JOB-20260628082622-51484d62`。 |
| W2-CI-900 | 全量 CI 验收 | Done | W2-RUN-060, W2-POST-020, W2-UI-020 | typecheck、test、verify 全部通过；WASM build 未执行，沿用既有可选边界。 |
## 3. Runtime 程序子任务
| 子任务 | 程序 | 覆盖章节 | 状态 | 验收 |
| --- | --- | --- | --- | --- |
| W2-PROG-010.1 | `W2_00_MinimalModule.grl` | 4、5、6、9、10、23 | Done | 最小 movej 可执行。 |
| W2-PROG-010.2 | `W2_10_DataTargetToolFrame.grl` | 6、8、9 | Done | tool/frame/target 编译为 IR。 |
| W2-PROG-010.3 | `W2_20_ExpressionMath.grl` | 7 | Done | 表达式折叠结果进入 speed/zone/pose/wait。 |
| W2-PROG-010.4 | `W2_30_MotionAllTypes.grl` | 10 | Done | movej/movel/movec 和 set_* 执行。 |
| W2-PROG-010.5 | `W2_40_PathEvents.grl` | 11 | Done | before/after/at distance event 进入 trace。 |
| W2-PROG-010.6 | `W2_50_OperationProcess.grl` | 12 | Done | operation 展开为 start/path/end。 |
| W2-PROG-010.7 | `W2_60_IOWaitPulse.grl` | 13 | Done | IO、wait、pulse、边沿检测执行。 |
| W2-PROG-010.8 | `W2_70_ControlFlow.grl` | 14 | Done | 分支、循环、switch 状态正确。 |
| W2-PROG-010.9 | `W2_80_ProcFuncCall.grl` | 15 | Done | 参数方向、call stack、return 正确。 |
| W2-PROG-010.10 | `W2_90_ExceptionAlarm.grl` | 16 | Done | alarm/raise/try/catch/finally trace 正确；trap/task 为 P1 warning。 |
| W2-PROG-010.11 | `W2_99_FullSpecExample.grl` | 24 | Done | 完整示例 path/operation/proc/run_operation 可执行并输出 queue 证据。 |
## 4. Static/Post 子任务
| 子任务 | 程序 | 层级 | 状态 | 验收 |
| --- | --- | --- | --- | --- |
| W2-PROG-020.1 | `W2_E10_ExpressionDiagnostics.grl` | Static | Done | 表达式 diagnostic 覆盖。 |
| W2-PROG-020.2 | `W2_E20_SemanticDiagnostics.grl` | Static | Done | 语义检查 diagnostic 覆盖。 |
| W2-PROG-020.3 | `W2_E30_MotionDiagnostics.grl` | Static/KDL | Done | 限位、不可达、空 path 诊断稳定。 |
| W2-PROG-020.4 | `W2_E40_ControlFlowDiagnostics.grl` | Static | Done | 非法控制流诊断稳定。 |
| W2-PROG-020.5 | `W2_E50_RuntimeTimeout.grl` | Runtime error | Done | wait timeout 和 on_timeout 证据完整。 |
| W2-PROG-030.1 | `W2_P10_BrandHints.grl` | Post | Done | post_hint 进入 report；`@brand.*` 为后续 parser 扩展边界。 |
| W2-PROG-030.2 | `W2_P20_CrossBrandMotion.grl` | Post | Done | 三品牌 motion/IO/wait 输出完整。 |
| W2-PROG-030.3 | `W2_P30_Roundtrip.grl` | Post | Done | 导入回读结构等价或 diff 明确。 |
## 5. 服务器演示子任务
| 子任务 | 内容 | 状态 | 验收 |
| --- | --- | --- | --- |
| W2-DEPLOY-001.1 | 定义 `demo-manifest.json` schema | Done | schema 能表达 release、suite、job、program、report、screenshot、doc。 |
| W2-DEPLOY-001.2 | 生成首页 `index.html` | Done | 首页可跳转虚拟控制器、报告、程序清单、截图和文档。 |
| W2-DEPLOY-010.1 | 收集 19 个 GRL 程序 | Done | zip 内 `spec-programs` 与 manifest 数量一致。 |
| W2-DEPLOY-010.2 | 收集最新 W2 job | Done | zip 内存在 `job.json`、`report.json`、`programs/<id>/*.json`。 |
| W2-DEPLOY-010.3 | 收集截图和 Word 文档 | Done | zip 内存在 2 张截图和 2 份 Word 文档。 |
| W2-DEPLOY-040.1 | 浏览器人工验证 | Done | 远程首页、虚拟控制器入口、报告、截图和程序清单均可打开。 |
| W2-DEPLOY-050.1 | curl 自动 smoke test | Done | 关键 URL 返回 200，report fail=0。 |
| W2-DEPLOY-050.2 | 逐帧轨迹远程抽查 | Done | `W2_30_MotionAllTypes`、`W2_60_IOWaitPulse`、`W2_99_FullSpecExample` 的远程 `trajectory.json` 均返回 frames、joints 和 TCP。 |

220
working2/05-验收证据.md Normal file
View File

@@ -0,0 +1,220 @@
# 05-验收证据
版本：0.1
日期：2026-06-28
## 1. 证据状态
| 状态 | 含义 |
| --- | --- |
| 待验证 | 任务尚未执行或未产生产物。 |
| 通过 | 已执行且满足验收标准。 |
| 不通过 | 已执行但不满足验收标准。 |
| 跳过 | 因明确边界暂不执行，必须说明原因。 |
## 2. 基准证据项
| 证据 | 状态 | 目标产物 |
| --- | --- | --- |
| EV-W2-SPEC-001：语法覆盖矩阵 | 通过 | `working2/programs/manifest.md` 和 `spec-programs/manifest.json` 已覆盖章节 4 到 25。 |
| EV-W2-PROG-010：Runtime 程序创建 | 通过 | `kdl-wasm/web/tests/fixtures/abb120/spec-programs/runtime/W2_*.grl` 共 11 个；manifest Runtime 层级共 12 项。 |
| EV-W2-PROG-020：Error 程序创建 | 通过 | `static/error/W2_E*.grl` 共 5 个，其中 4 个 Static、1 个 Runtime timeout error。 |
| EV-W2-PROG-030：Post 程序创建 | 通过 | `post/W2_P*.grl` 共 3 个。 |
| EV-W2-RUN-001：suite runner | 通过 | `kdl-wasm/web/test-results/abb120-spec/W2-JOB-20260628082622-51484d62/job.json`。 |
| EV-W2-RUN-030：虚拟控制器执行 | 通过 | 每个 runtime 程序输出 `controller.json`、`trace.json`、`motion-queue.json`。 |
| EV-W2-RUN-040：逐帧轨迹 | 通过 | Runtime 轨迹 `trajectory.json` 包含 `frames[]`，每帧包含 joints[6]、TCP position[3] 和 TCP quaternion[4]。 |
| EV-W2-RUN-050：IO/wait/pulse | 通过 | `W2_60_IOWaitPulse` 和 `W2_E50_RuntimeTimeout` 输出 IO/wait/pulse/timeout trace。 |
| EV-W2-POST-010：三品牌输出 | 通过 | `post-report.json` 记录 ABB/FANUC/KUKA 文件名和 report。 |
| EV-W2-POST-020：roundtrip | 通过 | `roundtrip.json` 记录 ABB import 回读状态和 diagnostics。 |
| EV-W2-UI-020：HTML 截图 | 通过 | `kdl-wasm/web/test-results/virtual-controller/virtual-controller-desktop.png`、`virtual-controller-mobile.png`、`evidence.json`。 |
| EV-W2-CI-900：全量命令 | 通过 | `npm run typecheck`、`npm test`、`npm run verify:virtual-controller` 全部通过；WASM native build 未执行。 |
| EV-W2-DEPLOY-001：演示包 manifest | 通过 | `demo-manifest.json` 包含 release_id、job_id、19 个程序、报告、截图、文档入口。 |
| EV-W2-DEPLOY-020：演示包 zip | 通过 | `kdl-wasm/web/test-results/deploy/kdl-olp-demo-20260628-164048-W2-JOB-20260628082622-51484d62.zip`。 |
| EV-W2-DEPLOY-040：HTTPS 发布 | 通过 | `https://82.156.24.101:8095/` 可访问首页、虚拟控制器、report、截图和逐帧轨迹 JSON。 |
| EV-W2-DEPLOY-050：远程 smoke test | 通过 | `kdl-wasm/web/test-results/deploy/kdl-olp-demo-20260628-164048-W2-JOB-20260628082622-51484d62.deploy.json`，`program_count=19` 且 `summary.fail=0`。 |
## 3. 建议命令
### 3.1 文档和覆盖矩阵检查
```powershell
rg -n "W2_|通用机器人编程语法规范|Runtime|Static|Post|ABB120|虚拟控制器" working2
```
预期：能找到 README、任务矩阵、验收证据、决策记录和 manifest 中的覆盖项。
### 3.2 GRL 和 ABB120 测试
```powershell
cd E:\Work\kdl_work
npm test -- grl abb120
```
预期：GRL parser/semantic、ABB120 fixture、表达式和程序编译测试通过。
### 3.3 虚拟控制器运行测试
```powershell
npm test -- virtual controller runtime
```
预期：状态机、IR runtime、motion queue、IO runtime、workbench/debug facade 测试通过。
### 3.4 后处理和导入回读
```powershell
npm test -- post import roundtrip
```
预期：ABB/FANUC/KUKA post、brand import、roundtrip diff 测试通过。
### 3.5 HTML 虚拟控制器截图
```powershell
npm run verify:virtual-controller
```
预期：桌面和移动截图生成，状态交互、Wait 置位和无横向溢出检查通过。
### 3.6 可选 WASM native build
```powershell
cmake --build kdl-wasm/build-wasm -j16
```
预期：当前 Emscripten/Ninja 环境可用时构建通过；如环境缺失，记录为环境阻塞而不是功能通过。
### 3.7 服务器演示包生成
建议后续实现脚本：
```powershell
cd E:\Work\kdl_work
node kdl-wasm/web/scripts/build-demo-package.mjs
node kdl-wasm/web/scripts/verify-demo-package.mjs kdl-wasm/web/test-results/deploy/kdl-olp-demo-<release_id>.zip
```
预期：生成 zip；解压校验包含 `index.html`、`demo-manifest.json`、19 个 `.grl`、最新 `W2-JOB-*`、逐帧 `trajectory.frames`、2 张截图和 2 份 Word 文档。
### 3.8 HTTPS 远程 smoke test
```powershell
$base = "https://82.156.24.101:8095"
curl.exe -k "$base/"
curl.exe -k "$base/demo-manifest.json"
curl.exe -k "$base/spec-programs/manifest.json"
curl.exe -k "$base/app/virtual-controller.html"
curl.exe -k "$base/test-results/abb120-spec/<job_id>/report.json"
curl.exe -k "$base/test-results/virtual-controller/virtual-controller-desktop.png" --output NUL
curl.exe -k "$base/test-results/virtual-controller/virtual-controller-mobile.png" --output NUL
```
预期：
1. 关键 URL 返回 200。
2. `demo-manifest.json` 中 `program_count` 为 19。
3. `report.json` 中 `summary.fail` 为 0。
4. 浏览器可打开虚拟控制器页面和报告页面。
## 4. 实际产物目录
```text
kdl-wasm/web/test-results/abb120-spec/
W2-JOB-20260628022836-51484d62/
job.json
manifest.json
report.json
report.html
programs/
<program_id>/
compile.json
controller.json
motion-queue.json
trace.json
io.json
trajectory.json
post-report.json
roundtrip.json
```
每个 `job.json` 必须包含：
1. `job_id`
2. `suite_id`
3. `robot_id`
4. `spec_version`
5. `programs`
6. `commands`
7. `status`
8. `diagnostics`
9. `artifact_paths`
## 5. 当前记录
| 时间 | 命令 | 结果 |
| --- | --- | --- |
| 2026-06-28 09:38 Asia/Shanghai | `npm run suite:abb120-spec` | 通过；生成 `W2-JOB-20260628013857-19b5a2c7`，18 个程序，missingSections 为空。 |
| 2026-06-28 09:40 Asia/Shanghai | `npm run typecheck` | 通过。 |
| 2026-06-28 09:41 Asia/Shanghai | `npm test` | 通过；41 个 test files，155 个 tests。 |
| 2026-06-28 09:42 Asia/Shanghai | `npm run verify:virtual-controller` | 通过；desktop screenshot 49892 bytes，mobile screenshot 47887 bytes，wait=`satisfied`，所有主要面板可见。 |
| 2026-06-28 10:28 Asia/Shanghai | `npm test -- abb120SpecSuite` | 通过；manifest 引用、层级、expected status、expected diagnostics 和 W2_99 完整示例证据均通过。 |
| 2026-06-28 10:28 Asia/Shanghai | `npm run typecheck` | 通过。 |
| 2026-06-28 10:28 Asia/Shanghai | `npm run suite:abb120-spec` | 通过；生成 `W2-JOB-20260628022836-51484d62`，19 个程序，missingSections 为空。 |
| 2026-06-28 10:33 Asia/Shanghai | `npm test` | 通过；41 个 test files，155 个 tests。 |
| 2026-06-28 10:33 Asia/Shanghai | `npm run verify:virtual-controller` | 通过；desktop screenshot 49892 bytes，mobile screenshot 47887 bytes，wait=`satisfied`，所有主要面板可见。 |
| 2026-06-28 12:06 Asia/Shanghai | `npm run demo:build` | 通过；生成 release `20260628-120601-W2-JOB-20260628024709-51484d62`，zip 3769732 bytes，sha256=`e3d936ae5e2c813f80346363b66b82fc19c87fe61ca421ac1b2de2eb4bc1c699`。 |
| 2026-06-28 12:06 Asia/Shanghai | `npm run demo:verify -- kdl-wasm/web/test-results/deploy/kdl-olp-demo-20260628-120601-W2-JOB-20260628024709-51484d62.zip` | 通过；解压后 `program_count=19`、`.grl=19`、`summary.fail=0`、截图和 2 份 Word 文档均存在。 |
| 2026-06-28 12:07 Asia/Shanghai | 上传并切换服务器 release | 通过；`current` 指向 `/opt/kdl-olp-demo/8095/releases/20260628-120601-W2-JOB-20260628024709-51484d62`，`previous` 指向 `/opt/kdl-olp-demo/8095/releases/20260628-120357-W2-JOB-20260628024709-51484d62`，服务 `kdl-site-8095` 为 active。 |
| 2026-06-28 12:07 Asia/Shanghai | HTTPS remote smoke test | 通过；`/`、`/demo-manifest.json`、`/spec-programs/manifest.json`、`/app/virtual-controller.html`、`report.json`、`report.html`、desktop/mobile png 全部返回 200；`program_count=19`、`summary.fail=0`。 |
| 2026-06-28 12:15 Asia/Shanghai | `npm run typecheck` | 通过。 |
| 2026-06-28 12:15 Asia/Shanghai | `npm test` | 通过；41 个 test files，155 个 tests。 |
| 2026-06-28 16:25 Asia/Shanghai | `npm run typecheck` | 通过。 |
| 2026-06-28 16:25 Asia/Shanghai | `npm test -- kdl-wasm/web/tests/integration/abb120SpecSuite.test.ts kdl-wasm/web/tests/integration/abb120SuiteArtifacts.test.ts` | 通过；5 个 integration tests 通过，包含逐帧 trajectory 断言。 |
| 2026-06-28 16:26 Asia/Shanghai | `npm run suite:abb120-spec` | 通过；生成 `W2-JOB-20260628082622-51484d62`，19 个程序，missingSections 为空。 |
| 2026-06-28 16:28 Asia/Shanghai | `npm run verify:virtual-controller` | 通过；desktop screenshot 45302 bytes，mobile screenshot 40407 bytes，`Run` 后 state=`running`，DI wait=`satisfied`。 |
| 2026-06-28 16:35 Asia/Shanghai | `npm run demo:verify -- kdl-wasm/web/test-results/deploy/kdl-olp-demo-20260628-163458-W2-JOB-20260628082622-51484d62.zip` | 通过；`program_count=19`、`.grl=19`、`summary.fail=0`、`runtime_trajectory_frames=9/12`。 |
| 2026-06-28 16:38 Asia/Shanghai | `powershell -NoProfile -ExecutionPolicy Bypass -File kdl-wasm/web/scripts/deploy-demo-package.ps1 -ZipPath ... -Target abigailaw-8091` | 通过；关键 URL 全部 200，`program_count=19`、`summary.fail=0`，服务 `kdl-site-8095` 自动重启后读取新 release。 |
| 2026-06-28 16:39 Asia/Shanghai | Python HTTPS 远程逐帧轨迹抽查 | 通过；`W2_30_MotionAllTypes` 有 12 帧，`W2_60_IOWaitPulse` 有 4 帧，`W2_99_FullSpecExample` 有 32 帧，均含 joints 和 TCP。 |
### 最新 job
| 项 | 值 |
| --- | --- |
| job_id | `W2-JOB-20260628082622-51484d62` |
| suite_id | `working2-abb120-spec` |
| robot_id | `abb_irb120_3_58` |
| job.json | `kdl-wasm/web/test-results/abb120-spec/W2-JOB-20260628082622-51484d62/job.json` |
| report.html | `kdl-wasm/web/test-results/abb120-spec/W2-JOB-20260628082622-51484d62/report.html` |
| HTML screenshots | `kdl-wasm/web/test-results/virtual-controller/` |
## 6. 服务器发布证据记录模板
| 项 | 值 |
| --- | --- |
| release_id | `20260628-164048-W2-JOB-20260628082622-51484d62` |
| zip 路径 | `kdl-wasm/web/test-results/deploy/kdl-olp-demo-20260628-164048-W2-JOB-20260628082622-51484d62.zip` |
| zip hash | 见同目录 `kdl-olp-demo-20260628-164048-W2-JOB-20260628082622-51484d62.summary.json`。 |
| job_id | `W2-JOB-20260628082622-51484d62` |
| 发布地址 | `https://82.156.24.101:8095/` |
| 服务器 release 目录 | `/opt/kdl-olp-demo/8095/releases/20260628-164048-W2-JOB-20260628082622-51484d62` |
| current 指向 | `/opt/kdl-olp-demo/8095/releases/20260628-164048-W2-JOB-20260628082622-51484d62` |
| smoke test 时间 | `2026-06-28 16:40 Asia/Shanghai` |
| smoke test 结果 | 通过；关键 URL 全部 200，`program_count=19`，`summary.fail=0`。 |
| 回滚目录 | `/opt/kdl-olp-demo/8095/releases/20260628-163458-W2-JOB-20260628082622-51484d62` |
## 7. 远程页面人工验收记录模板
| 演示项 | 程序或页面 | 结果 | 备注 |
| --- | --- | --- | --- |
| 首页打开 | `/` | 通过 | HTTP 200，返回 11199 bytes。 |
| manifest 打开 | `/demo-manifest.json` | 通过 | HTTP 200，`program_count=19`。 |
| 虚拟控制器打开 | `/app/virtual-controller.html` | 通过 | HTTP 200，页面包含 Program 下拉、Frame slider 和 `Trajectory Frames` 表格。 |
| 报告打开 | `/test-results/abb120-spec/W2-JOB-20260628082622-51484d62/report.html` | 通过 | HTTP 200，返回 2266 bytes。 |
| 最小运动演示 | `W2_00_MinimalModule` | 通过 | 程序源和 compile artifact 均在 manifest 中可跳转。 |
| 三类运动演示 | `W2_30_MotionAllTypes` | 通过 | 远程 `trajectory.json` 有 12 帧，每帧包含 TCP 和 J1-J6。 |
| IO/wait/pulse 演示 | `W2_60_IOWaitPulse` | 通过 | 远程 `trajectory.json` 有 4 帧；页面 DI1 可将 wait 切到 `satisfied`。 |
| 完整示例演示 | `W2_99_FullSpecExample` | 通过 | 远程 `trajectory.json` 有 32 帧，每帧包含 TCP 和 J1-J6。 |
| 静态诊断展示 | `W2_E10` 到 `W2_E40` | 通过 | `report.json` 中保留 expected diagnostics，`summary.fail=0`。 |
| 后处理展示 | `W2_P10` 到 `W2_P30` | 通过 | post/roundtrip artifacts 均在 package 内。 |
| 桌面截图打开 | `virtual-controller-desktop.png` | 通过 | HTTP 200，45302 bytes。 |
| 移动截图打开 | `virtual-controller-mobile.png` | 通过 | HTTP 200，40407 bytes。 |

184
working2/06-决策记录.md Normal file
View File

@@ -0,0 +1,184 @@
# 06-决策记录
版本：0.1
日期：2026-06-28
## ADR-W2-001：working2 以当前语法规范作为覆盖源
状态：Accepted
日期：2026-06-28
关联任务：`W2-SPEC-001`
### 背景
用户要求对标 `通用机器人编程语法规范.md` 创建机器人程序集，并全面完成虚拟控制器执行情况。`working1` 已经覆盖 ABB120 基础测试和虚拟控制器，但不是逐章按最新语法规范做覆盖矩阵。
### 决策
`working2` 以 `work/doc/通用机器人编程语法规范.md` 为唯一覆盖源。任何程序或测试是否“覆盖”，必须能追溯到规范章节、语法项和验收证据。
### 后果
1. 覆盖结论可审计。
2. 语法规范更新后可以重新生成缺口清单。
3. 不再用“已有测试通过”替代规范覆盖证明。
## ADR-W2-002：ABB120 基准继续使用仓库内稳定 fixture
状态：Accepted
日期：2026-06-28
关联任务：`W2-PROG-010`、`W2-RUN-020`
### 背景
仓库已有 `kdl-wasm/web/src/fixtures/abb120.ts` 和测试导出 `abbIrb120.ts`，其中包含 ABB IRB120 3/58 URDF、load options 和标准关节位。重新引入外部 URDF 会增加模型差异和验证成本。
### 决策
working2 继续使用仓库内 ABB120 fixture。若未来需要独立 `.urdf` 文件，只能从当前 fixture 导出，不能静默替换机器人模型。
### 后果
1. working2 结果与 existing KDL/virtual controller 测试一致。
2. FK/IK/limit snapshot 可复用。
3. 外部 mesh/inertial 完整模型另列任务。
## ADR-W2-003：语法覆盖分为 Runtime、Static、Post 三层
状态：Accepted
日期：2026-06-28
关联任务：`W2-SPEC-002`
### 背景
语法规范包含流程控制、运动、IO，也包含 trap、interrupt、task、brand metadata、post_hint 等不适合全部作为虚拟控制器 happy path 执行的语义。如果强行要求所有语法都运行，会混淆实现边界。
### 决策
覆盖分三层：
1. Runtime：虚拟控制器必须执行并输出 trace。
2. Static：parser/semantic 必须诊断或验证。
3. Post：后处理、导入回读和报告必须覆盖。
### 后果
1. happy path 稳定。
2. P1/P2 语义不会被误报为已完整执行。
3. 覆盖矩阵能清楚说明每项语法的验证方式。
## ADR-W2-004：虚拟控制器验收以证据包为准
状态：Accepted
日期：2026-06-28
关联任务：`W2-RUN-001` 到 `W2-RUN-060`
### 背景
“执行情况”不能只看单元测试通过。虚拟控制器需要证明状态机、程序指针、motion queue、IO/wait、报警、source map 和轨迹结果都正确。
### 决策
每次 suite 运行生成 `W2-JOB-*` 证据包，至少包含：
1. `job.json`
2. `compile.json`
3. `controller.json`
4. `motion-queue.json`
5. `trace.json`
6. `io.json`
7. `trajectory.json`
8. `report.json/html`
### 后果
1. 运行结果可回放和审计。
2. HTML 虚拟控制器可以消费同一证据。
3. CI 失败时能定位到具体程序、source range 和 controller 状态。
## ADR-W2-005：working2 不改写 working1 完成记录
状态：Accepted
日期：2026-06-28
关联任务：`W2-SPEC-000`
### 背景
`working1` 已记录已完成的 ABB120 基础测试、表达式功能和虚拟控制器验收。用户要求任务整合到 `working2` 并参考 `working1`，不是要求重写历史记录。
### 决策
`working2` 新建独立任务包，状态从 `Todo` 开始。`working1` 仅作为参考和可复用资产来源。
### 后果
1. 避免把旧验收直接当作新目标完成。
2. working2 可以独立追踪新增覆盖缺口。
3. 后续实现可以逐项把 Todo 推进到 Done。
## ADR-W2-006：W2 runner 使用同步 fixture planner 生成审计轨迹
状态：Accepted
日期：2026-06-28
关联任务：`W2-RUN-020`、`W2-RUN-040`
### 背景
working2 的核心目标是逐章覆盖 GRL 语法规范，并为每个程序输出稳定、可审计的 controller、motion queue、trace、IO 和 trajectory 证据。仓库已有 ABB120 KDL 集成测试负责真实 URDF FK/IK/planPath 验证。
### 决策
`runAbb120SpecSuite` 在 W2 job 中使用同步 fixture planner 生成稳定 trajectory 和 planner diagnostic；真实 ABB120 URDF/KDL 检查继续由既有 `abb120Programs.test.ts` 和 KDL 测试承担。
### 后果
1. W2 证据包生成快速、稳定、可在普通 Node/Vitest 环境执行。
2. Motion queue、source map、IO/wait/alarm 和 post/roundtrip 证据可稳定归档。
3. 若后续要求 job 内嵌真实 KDL 轨迹，可在 runner 中增加 async KDL planner 模式。
## ADR-W2-007：异常和 P1 语义采用 runtime/static 边界组合
状态：Accepted
日期：2026-06-28
关联任务：`W2-RUN-060`、`W2-PROG-010.10`
### 背景
当前语法规范定义 `try/catch/finally`、`trap`、`interrupt`、`task`。现有 parser/semantic 已有异常分析器，但控制流分析器不应把 `try` 当普通控制流执行；`trap/task` 仍是 P1 runtime 边界。
### 决策
控制流分析器将 `try` 块保留为 raw boundary，由 exception semantic 负责 alarm/raise/try/catch/finally 分析。`trap/task/interrupt` 输出 `GRL_P1_UNIMPLEMENTED` warning 或 unsupported runtime trace，不作为 happy path 完整执行。
### 后果
1. `W2_90_ExceptionAlarm.grl` 可以稳定 parse、compile、load 并输出异常语义证据。
2. P1 语义不会被误报为完整 runtime 支持。
3. 后续实现 trap/interrupt/task 时可替换 raw boundary，不影响 W2 manifest 结构。
## ADR-W2-008：服务器演示采用静态发布包加证据包模式
状态：Accepted
日期：2026-06-28
关联任务：`W2-DEPLOY-001` 到 `W2-DEPLOY-060`
### 背景
用户要求把虚拟测试程序打包到服务器，并能通过这些程序演示虚拟控制器全部功能。当前虚拟控制器页面、GRL 程序、suite job、截图和 Word 文档都可以作为静态文件发布；远程演示的重点是可访问、可审计、可重复，而不是在服务器上重新执行 Node/Vitest。
### 决策
服务器发布采用静态演示包模式：
1. 本地先执行 typecheck、test、suite 和截图验证。
2. 将虚拟控制器页面、19 个 GRL 程序、最新 `W2-JOB-*`、截图、Word 文档和 `demo-manifest.json` 打成 zip。
3. 服务器仅负责 HTTPS 静态托管。
4. 远程验收通过 `demo-manifest.json`、`report.json`、程序源码、截图和页面入口验证。
5. 服务器保留 release 目录和 `current` 链接，支持回滚。
### 后果
1. 发布包可离线审计，不依赖服务器 Node 环境。
2. 演示内容与本地测试证据一致，避免远程环境差异导致结论不稳定。
3. 后续如需在线编辑和动态运行，可在当前静态包基础上增加 API 服务，不影响现有验收链路。
4. 凭据不进入仓库文档，降低泄露风险。

238
working2/07-服务器发布与演示包实施方案.md Normal file
View File

@@ -0,0 +1,238 @@
# 07-服务器发布与演示包实施方案
版本：0.1
日期：2026-06-28
## 1. 目标
将虚拟控制器网站、GRL 规范测试程序和最新测试证据打包发布到 HTTPS 服务器，使用户可以通过浏览器演示虚拟控制器的全部功能。
发布目标：
```text
https://82.156.24.101:8095/
```
端口 `8095` 已作为演示端口使用。本文档不记录服务器密码，部署凭据由部署人员本地管理。
## 2. 演示范围
服务器演示必须覆盖以下功能：
| 功能 | 演示来源 |
| --- | --- |
| GRL 程序加载 | 19 个 `spec-programs` 程序。 |
| 语法解析和语义编译 | 每个程序的 `compile.json`。 |
| 虚拟控制器状态机 | Runtime 程序的 `controller.json`。 |
| motion queue | Runtime 程序的 `motion-queue.json`。 |
| 轨迹摘要 | Runtime 程序的 `trajectory.json`。 |
| IO、wait、pulse | `W2_60_IOWaitPulse` 和 `W2_E50_RuntimeTimeout`。 |
| 流程控制和调用 | `W2_70_ControlFlow`、`W2_80_ProcFuncCall`。 |
| 异常和报警 | `W2_90_ExceptionAlarm`、`W2_E50_RuntimeTimeout`。 |
| 静态错误诊断 | `W2_E10`、`W2_E20`、`W2_E30`、`W2_E40`。 |
| 三品牌后处理 | `W2_P10`、`W2_P20`、`W2_P30` 的 `post-report.json`。 |
| 导入回读 | `roundtrip.json`。 |
| 页面截图 | `virtual-controller-desktop.png`、`virtual-controller-mobile.png`。 |
## 3. 发布包结构
标准发布包命名：
```text
kdl-olp-demo-YYYYMMDD-HHMMSS-<job_id>.zip
```
解压后目录：
```text
kdl-olp-demo/
index.html
demo-manifest.json
README.md
app/
virtual-controller.html
virtual-controller.css
virtual-controller.js
spec-programs/
manifest.json
runtime/
static/
error/
post/
test-results/
abb120-spec/
<job_id>/
job.json
manifest.json
report.json
report.html
programs/
virtual-controller/
evidence.json
virtual-controller-desktop.png
virtual-controller-mobile.png
docs/
GRL功能语法逻辑与程序创建使用手册.docx
通用机器人离线编程系统测试文档.docx
```
## 4. demo-manifest.json 字段
`demo-manifest.json` 是远程页面和验收脚本的入口文件，字段必须稳定。
```json
{
"release_id": "20260628-112000-W2-JOB-...",
"generated_at": "2026-06-28T03:20:00.000Z",
"suite_id": "working2-abb120-spec",
"job_id": "W2-JOB-...",
"program_count": 19,
"runtime_programs": 12,
"static_programs": 4,
"post_programs": 3,
"entry": "app/virtual-controller.html",
"report_json": "test-results/abb120-spec/<job_id>/report.json",
"report_html": "test-results/abb120-spec/<job_id>/report.html",
"program_manifest": "spec-programs/manifest.json",
"screenshots": {
"desktop": "test-results/virtual-controller/virtual-controller-desktop.png",
"mobile": "test-results/virtual-controller/virtual-controller-mobile.png"
}
}
```
## 5. 本地发布前检查
发布前必须执行：
```powershell
cd E:\Work\kdl_work
npm run typecheck
npm test
npm run suite:abb120-spec
npm run verify:virtual-controller
```
预期：
1. TypeScript 无错误。
2. Vitest 全量通过。
3. `suite:abb120-spec` 生成新 `W2-JOB-*`。
4. `verify:virtual-controller` 生成桌面和移动截图。
5. `report.json` 中 `summary.fail` 为 `0`。
## 6. 服务器目录规范
推荐服务器目录：
```text
/opt/kdl-olp-demo/8095/
releases/
<release_id>/
current -> releases/<release_id>
previous -> releases/<previous_release_id>
```
发布时只切换 `current`，不要直接覆盖正在服务的目录。
## 7. 上传和发布步骤
1. 本地生成演示包 zip。
2. 上传 zip 到服务器临时目录。
3. 在服务器创建 release 目录。
4. 解压 zip 到 release 目录。
5. 检查 `index.html`、`demo-manifest.json` 和 `app/virtual-controller.html` 是否存在。
6. 将 `previous` 指向旧 `current`。
7. 将 `current` 指向新 release。
8. 重新加载或确认 HTTPS 服务读取 `current`。
9. 执行远程 smoke test。
## 8. 远程 smoke test
```powershell
$base = "https://82.156.24.101:8095"
curl.exe -k "$base/"
curl.exe -k "$base/demo-manifest.json"
curl.exe -k "$base/spec-programs/manifest.json"
curl.exe -k "$base/app/virtual-controller.html"
curl.exe -k "$base/test-results/abb120-spec/<job_id>/report.json"
```
检查项：
| URL | 预期 |
| --- | --- |
| `/` | 返回首页 HTML。 |
| `/demo-manifest.json` | `program_count` 为 19。 |
| `/spec-programs/manifest.json` | 包含 19 个 programs。 |
| `/app/virtual-controller.html` | 返回虚拟控制器页面。 |
| `/test-results/abb120-spec/<job_id>/report.json` | `summary.fail` 为 0。 |
| `/test-results/virtual-controller/virtual-controller-desktop.png` | 返回 PNG。 |
| `/test-results/virtual-controller/virtual-controller-mobile.png` | 返回 PNG。 |
## 9. 人工演示脚本
浏览器打开：
```text
https://82.156.24.101:8095/
```
演示顺序：
1. 打开首页，说明当前 release、job_id、程序数量。
2. 打开虚拟控制器页面。
3. 展示 Runtime 程序列表，重点选择：
- `W2_00_MinimalModule`
- `W2_30_MotionAllTypes`
- `W2_60_IOWaitPulse`
- `W2_99_FullSpecExample`
4. 展示 trace、motion queue、IO image 和 diagnostics。
5. 打开 `report.html`，说明 19 个程序覆盖章节 4 到 25。
6. 打开截图，说明桌面和移动端 UI 已验证。
7. 打开 Word 手册和测试文档，说明使用和测试结论。
## 10. 回滚
若远程验证失败：
1. 保留失败 release，不删除，便于排查。
2. 将 `current` 指回 `previous`。
3. 重新执行 smoke test。
4. 在 `working2/03-推进台账.md` 记录：
- 失败 release_id
- 失败原因
- 回滚到哪个 release_id
- 后续修复任务
## 11. 自动化脚本
已新增脚本：
```text
kdl-wasm/web/scripts/build-demo-package.mjs
kdl-wasm/web/scripts/verify-demo-package.mjs
kdl-wasm/web/scripts/deploy-demo-package.ps1
```
脚本职责：
| 脚本 | 职责 |
| --- | --- |
| `build-demo-package.mjs` | 收集 app、spec-programs、latest job、screenshots、docs，生成 demo manifest 和 zip。 |
| `verify-demo-package.mjs` | 解压 zip，检查 19 个程序、report fail=0、图片和文档存在。 |
| `deploy-demo-package.ps1` | 上传 zip、远程解压、切换 current、执行 smoke test。 |
当前发布 release：
```text
20260628-120601-W2-JOB-20260628024709-51484d62
```
服务器当前状态：
| 项 | 值 |
| --- | --- |
| current | `/opt/kdl-olp-demo/8095/releases/20260628-120601-W2-JOB-20260628024709-51484d62` |
| previous | `/opt/kdl-olp-demo/8095/releases/20260628-120357-W2-JOB-20260628024709-51484d62` |
| HTTPS smoke test | 通过，关键 URL 返回 200，`program_count=19`，`summary.fail=0`。 |

64
working2/README.md
View File

@@ -1,10 +1,64 @@
# working2 任务审计
# working2 GRL 语法规范覆盖程序集与虚拟控制器验收索引
版本：0.1
日期：2026-06-28
主题：对标 `work/doc/通用机器人编程语法规范.md`，以 ABB IRB120 3/58 URDF fixture 为机器人基准，建立覆盖语法规范的 GRL 机器人程序集，并全面验收虚拟控制器执行情况。
本目录当前没有任务文件、源码、验收矩阵或外部引用。已检查：
## 1. 目标
1. `Get-ChildItem -Force E:\Work\kdl_work\working2`：无文件。
2. `rg -n "working2|working 2|工作2" E:\Work\kdl_work`：未发现任务说明引用。
`working2` 是在 `working1` 已完成 ABB120 基础测试、运算功能和 HTML 虚拟控制器之后的专项任务包。它不重复定义 ABB120 基础能力，而是把当前语法规范转成可执行覆盖清单：
结论：`working2` 当前为空任务集，无待实现项。
1. 逐章对照 `通用机器人编程语法规范.md`，生成 ABB120 GRL 程序套件。
2. 区分虚拟控制器必须执行的语义、编译期静态验证语义、后处理/导入验证语义。
3. 用 ABB120 URDF fixture 运行 happy path、runtime path、error path 和 cross-brand path。
4. 输出可审计证据：AST、IR、KDL request、motion queue、trace、IO/wait、alarm、source map、post report、roundtrip report、HTML 截图。
5. 将结果接入当前 `kdl-wasm` 测试、suite runner 和虚拟控制器页面验证命令。
6. 将虚拟控制器页面、19 个 GRL 规范测试程序、最新 W2 job 证据包和截图打成服务器演示包，通过 HTTPS 地址演示虚拟控制器全部功能。
## 2. 基准输入
| 项 | 路径 |
| --- | --- |
| 语法规范 | `E:\Work\kdl_work\work\doc\通用机器人编程语法规范.md` |
| ABB120 fixture | `E:\Work\kdl_work\kdl-wasm\web\src\fixtures\abb120.ts` |
| ABB120 测试 fixture 导出 | `E:\Work\kdl_work\kdl-wasm\web\tests\fixtures\abbIrb120.ts` |
| 已有 ABB120 程序目录 | `E:\Work\kdl_work\kdl-wasm\web\tests\fixtures\abb120\programs` |
| 已有 suite runner | `E:\Work\kdl_work\kdl-wasm\web\src\suites\abb120Suite.ts` |
| 虚拟控制器核心 | `E:\Work\kdl_work\kdl-wasm\web\src\controller` |
| HTML 虚拟控制器 | `E:\Work\kdl_work\kdl-wasm\web\app\virtual-controller.html` |
## 3. 文档入口
| 文件 | 用途 |
| --- | --- |
| `01-项目功能内容.md` | 需求范围、语法覆盖分层、ABB120 程序集、虚拟控制器执行和报告要求。 |
| `02-项目程序开发详细步骤.md` | 从规范解析、程序创建、执行运行器、证据输出到 CI 的实施步骤。 |
| `03-推进台账.md` | 本轮任务整合记录、已发现资产、待实现边界和下一步。 |
| `04-任务矩阵.md` | 任务编号、状态、依赖、验收标准。 |
| `05-验收证据.md` | 应执行命令、产物路径、job/report/screenshot 证据要求。 |
| `06-决策记录.md` | ABB120 基准、覆盖策略、执行边界和证据格式的设计决策。 |
| `07-服务器发布与演示包实施方案.md` | HTTPS 发布目标、演示包内容、服务器目录、演示程序清单和验收步骤。 |
| `programs/manifest.md` | GRL 程序集清单和语法规范覆盖矩阵。 |
## 4. 任务编号
| 编号范围 | 主题 |
| --- | --- |
| `W2-SPEC-000` 到 `W2-SPEC-099` | 语法规范覆盖矩阵和缺口审计。 |
| `W2-PROG-000` 到 `W2-PROG-199` | ABB120 GRL 覆盖程序集。 |
| `W2-RUN-000` 到 `W2-RUN-199` | 虚拟控制器执行、KDL、IO/wait、trace 和 source map。 |
| `W2-POST-000` 到 `W2-POST-099` | ABB/FANUC/KUKA 后处理、导入回读和差异报告。 |
| `W2-UI-000` 到 `W2-UI-099` | HTML 虚拟控制器页面和截图验收。 |
| `W2-DEPLOY-000` 到 `W2-DEPLOY-099` | 服务器演示包、HTTPS 发布、远程验证和回滚。 |
| `W2-CI-900` 到 `W2-CI-999` | 全量 CI 和证据归档。 |
## 5. 当前状态
已完成 working2 首批实现和验收：
1. 新增 `kdl-wasm/web/tests/fixtures/abb120/spec-programs`，包含 11 个 runtime 目录程序、2 个 error 目录程序、3 个 static 目录程序和 3 个 Post/import 程序；按 manifest 层级统计为 12 个 Runtime 项、4 个 Static 项、3 个 Post 项。
2. 新增 `kdl-wasm/web/tests/fixtures/abb120/spec-programs/manifest.json`，覆盖规范章节 4 到 25。
3. 新增 `runAbb120SpecSuite` 和 `npm run suite:abb120-spec`，可生成 `W2-JOB-*` 证据包。
4. HTML 虚拟控制器页面已从 `demo-manifest.json` 读取 19 个 W2 程序，支持 Program 下拉切换、Load/Run/Step、Frame slider 和逐帧 TCP/J1-J6 表格，并通过桌面和移动截图验证。
5. 最新证据包：`kdl-wasm/web/test-results/abb120-spec/W2-JOB-20260628082622-51484d62`。
6. 已完成服务器演示包自动化和 HTTPS 发布，目标地址为 `https://82.156.24.101:8095/`；当前 release 为 `20260628-164048-W2-JOB-20260628082622-51484d62`，远程 smoke test 和逐帧轨迹抽查通过。

115
working2/programs/manifest.md Normal file
View File

@@ -0,0 +1,115 @@
# working2 GRL 程序集 Manifest
版本：0.1
日期：2026-06-28
## 1. 目录目标
本 manifest 将 `通用机器人编程语法规范.md` 的语法和语义要求映射到 ABB120 GRL 程序、静态诊断测试、后处理测试和虚拟控制器执行证据。
目标程序目录：
```text
kdl-wasm/web/tests/fixtures/abb120/spec-programs/
```
机器可读 manifest：
```text
kdl-wasm/web/tests/fixtures/abb120/spec-programs/manifest.json
```
## 2. 覆盖层级
| 层级 | 含义 |
| --- | --- |
| Runtime | 必须进入虚拟控制器执行，并产出 controller/trace/motion queue/IO 证据。 |
| Static | 必须由 parser/semantic/KDL diagnostic 覆盖，不要求 happy path 执行。 |
| Post | 必须由 ABB/FANUC/KUKA 后处理、导入回读或 report 覆盖。 |
## 3. 程序清单
### 3.1 Runtime
| 程序 | 覆盖章节 | 核心语法 |
| --- | --- | --- |
| `W2_00_MinimalModule.grl` | 4、5、6、9、10、23 | language、module、const、speed、zone、joint_target、movej、proc main。 |
| `W2_10_DataTargetToolFrame.grl` | 6、8、9 | bool/int/real/string/time/length/angle/percent、tool、frame、pose、poseq、joint_target、pose_target。 |
| `W2_20_ExpressionMath.grl` | 7 | 算术、比较、逻辑、括号、单位后缀、pi/e、三角函数、数值函数、编译期求值。 |
| `W2_30_MotionAllTypes.grl` | 10 | movej、movel、movec、set_tool、set_frame、set_speed、set_zone、inline 参数优先级。 |
| `W2_40_PathEvents.grl` | 11 | path defaults/source、point、event before/after/at distance、run_path。 |
| `W2_50_OperationProcess.grl` | 12 | operation kind/process/start_action/end_action、run_operation。 |
| `W2_60_IOWaitPulse.grl` | 13 | io.di/do/ai/ao/gi/go/ri/ro、wait、timeout、on_timeout、pulse、all/any/rising/falling/changed。 |
| `W2_70_ControlFlow.grl` | 14 | if/elseif/else、while、for、switch、break、continue。 |
| `W2_80_ProcFuncCall.grl` | 15 | proc、in/out/inout、call、return、func 返回值、作用域。 |
| `W2_90_ExceptionAlarm.grl` | 16 | alarm、raise、try/catch/finally。 |
| `W2_99_FullSpecExample.grl` | 24 | 规范完整示例的 tool/frame、path、operation、IO event、run_operation 和回 home。 |
### 3.2 Static/error
| 程序 | 覆盖章节 | 预期诊断 |
| --- | --- | --- |
| `W2_E10_ExpressionDiagnostics.grl` | 7、22 | `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`。 |
| `W2_E20_SemanticDiagnostics.grl` | 6、15、22 | 重复符号、类型不匹配、缺失引用、out/inout 非左值、func 缺少 return、func 副作用。 |
| `W2_E30_MotionDiagnostics.grl` | 8、9、10、11、22 | 关节限位、不可达 pose、movec 共线、缺少 motion 参数、空 path、重复 path point。 |
| `W2_E40_ControlFlowDiagnostics.grl` | 14、22 | 非法 break/continue、jump 进入块、重复 case、非常量 case、缺失 label。 |
| `W2_E50_RuntimeTimeout.grl` | 13、16 | wait timeout、on_timeout alarm/call、报警 source map。 |
### 3.3 Post/import
| 程序 | 覆盖章节 | 预期报告 |
| --- | --- | --- |
| `W2_P10_BrandHints.grl` | 18、20 | `post_hint`、`@brand.*` 消费或报告。 |
| `W2_P20_CrossBrandMotion.grl` | 20 | ABB/FANUC/KUKA motion、speed、zone、IO、wait 映射。 |
| `W2_P30_Roundtrip.grl` | 19、20、21 | post 后导入回读，motion/path/operation 等价或差异明确。 |
## 4. 语法规范覆盖矩阵
| 规范章节 | 覆盖层级 | 程序或测试 |
| --- | --- | --- |
| 4. 词法规则 | Runtime/Static | `W2_00_MinimalModule`、lexer/parser tests。 |
| 5. 顶层结构 | Runtime | `W2_00_MinimalModule`。 |
| 6. 类型系统 | Runtime/Static | `W2_10_DataTargetToolFrame`、`W2_E20_SemanticDiagnostics`。 |
| 7. 表达式与运算 | Runtime/Static/Post | `W2_20_ExpressionMath`、`W2_E10_ExpressionDiagnostics`、`W2_P20_CrossBrandMotion`。 |
| 8. 坐标、工具和目标点 | Runtime/Static | `W2_10_DataTargetToolFrame`、`W2_E30_MotionDiagnostics`。 |
| 9. 速度和过渡 | Runtime/Post | `W2_20_ExpressionMath`、`W2_30_MotionAllTypes`、`W2_P20_CrossBrandMotion`。 |
| 10. 运动指令 | Runtime/Static/Post | `W2_30_MotionAllTypes`、`W2_E30_MotionDiagnostics`、`W2_P20_CrossBrandMotion`。 |
| 11. Path 语法 | Runtime/Static | `W2_40_PathEvents`、`W2_E30_MotionDiagnostics`。 |
| 12. Operation 语法 | Runtime/Post | `W2_50_OperationProcess`、`W2_P30_Roundtrip`。 |
| 13. IO 与等待 | Runtime | `W2_60_IOWaitPulse`、`W2_E50_RuntimeTimeout`。 |
| 14. 流程控制 | Runtime/Static | `W2_70_ControlFlow`、`W2_E40_ControlFlowDiagnostics`。 |
| 15. 子程序和函数 | Runtime/Static | `W2_80_ProcFuncCall`、`W2_E20_SemanticDiagnostics`。 |
| 16. 异常、报警和中断 | Runtime/Static | `W2_90_ExceptionAlarm`；trap/interrupt 先做 static 边界。 |
| 17. 多任务 | Runtime/Static | `W2_90_ExceptionAlarm` 的 task 边界 warning。 |
| 18. 品牌扩展和后处理提示 | Post | `W2_P10_BrandHints`。 |
| 19. 自动编程生成规则 | Post | `W2_P30_Roundtrip`、generator roundtrip tests。 |
| 20. 后处理映射规则 | Post | `W2_P20_CrossBrandMotion`。 |
| 21. 编译语义和 IR | Runtime/Static | 所有 runtime/error 程序的 compile evidence。 |
| 22. 语义检查 | Runtime/Static | `W2_E10` 到 `W2_E50`。 |
| 23. EBNF 语法草案 | Runtime/Static | `W2_00_MinimalModule`、parser coverage test 和 grammar fixtures。 |
| 24. 完整示例 | Runtime/Post | `W2_99_FullSpecExample` 覆盖完整 path/operation/proc 运行结构；`W2_P30_Roundtrip` 覆盖 post 后导入回读。 |
| 25. 实施优先级 | Runtime/Static/Post | P0 全部映射到上述程序；P1 进入 static/post 边界。 |
## 5. 证据要求
每个程序必须记录：
1. `program_id`
2. `spec_sections`
3. `coverage_level`
4. `expected_status`
5. `expected_diagnostics`
6. `runtime_commands`
7. `artifact_paths`
最终 suite manifest 应生成为 JSON，供 CI 和 HTML 虚拟控制器读取。
## 6. 当前实现状态
| 项 | 状态 | 证据 |
| --- | --- | --- |
| 程序文件 | Done | `spec-programs/runtime` 11 个、`static` 3 个、`error` 2 个、`post` 3 个；manifest 层级统计 Runtime 12、Static 4、Post 3。 |
| 机器可读 manifest | Done | `spec-programs/manifest.json`。 |
| suite runner | Done | `kdl-wasm/web/src/suites/abb120SpecSuite.ts`。 |
| job 生成命令 | Done | `npm run suite:abb120-spec`。 |
| 最新 job | Done | `kdl-wasm/web/test-results/abb120-spec/W2-JOB-20260628022836-51484d62`。 |