184 lines
12 KiB
Markdown
184 lines
12 KiB
Markdown
# 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 使用不校验证书的发布验证路径。
|