Repository navigation
docs(plans): 規劃 fast MVP 為 4 個 OpenSpec change 設計 - #105
Conversation
依 2026-05-25 session/artifact binding 討論收斂為四個獨立 change： - C1 streaming-server-fallback-semantic-mapping bim-streaming-server fallback 產出帶 ifc_type/ifc_name 的 mapping - C4 coordinator-serial-conversion-dispatch-queue coordinator in-memory FIFO 序列化 dispatch，新增 queued_for_conversion / dropped_on_restart lifecycle - C2 viewer-edge-bim-server-console web-viewer-sample 重新定位為 Edge BIM Data Server Console，三段 ready 分層，USDAsset picker 改 ?debug=1 only，刪除 collaboration / repo map - C3 coordinator-ui-tri-ready-and-queue /ui 三段 ready 顯示 + queue visibility + step rename + legacy disclaimer 文件性質為 brainstorming 階段 design 草案，source of truth 仍是落地後 的 OpenSpec changes。同步 commit 源討論筆記作為 reference。
📝 WalkthroughWalkthroughThis PR adds two design documentation files establishing the fast MVP session/artifact binding flow and edge BIM server console specification. The first document captures shared understanding of session semantics, live viewer observations, and proposed architecture. The second consolidates design into four OpenSpec changes spanning streaming-server semantic mapping, coordinator serial conversion queue, viewer console redesign, and coordinator UI dashboard. ChangesFast MVP Edge BIM Server Console & Artifact Binding Design
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR adds planning/design documentation to converge the fast MVP demo into four independent OpenSpec changes (C1–C4), clarifying session-first “stage truth”, tri-ready semantics (File/Runtime/Semantic), and the intended UI/queue behavior across bim-streaming-server, bim-review-coordinator, and web-viewer-sample.
Changes:
- Added a TEMP discussion note capturing the current shared understanding of session ↔ artifact binding, stage truth, and why semantic verification is currently incomplete.
- Added a consolidated design doc that slices the fast MVP into 4 OpenSpec changes (C1–C4) with scope, dependencies, acceptance/evidence gates, and test strategy.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/plans/TEMP-fast-mvp-session-artifact-binding-discussion-2026-05-25.md | Raw discussion notes documenting current observations and semantic gaps (source/reference for later specs). |
| docs/plans/fast-mvp-edge-bim-server-console-design-2026-05-25.md | Design draft that decomposes the fast MVP into 4 OpenSpec changes and defines tri-ready + queue visibility expectations. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -0,0 +1,525 @@ | |||
| # Fast MVP:Edge BIM Data Server Console — Design 2026-05-25 | |||
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/plans/fast-mvp-edge-bim-server-console-design-2026-05-25.md`:
- Around line 404-416: Runtime ready currently defined as "review_session exists
AND kit_instance_binding is set AND viewer participation observed" must be
aligned with C2's contract: change the Runtime ready condition in this document
so it uses the same checks as C2 (require WebRTC started and stageLoadStatus ===
"matched") rather than the existing viewer-observation wording; update the
Runtime ready clause (and any references to review_session /
kit_instance_binding if needed) to explicitly require "WebRTC started" and
"stageLoadStatus === 'matched'" so viewer and /ui use the identical readiness
source and criteria.
- Around line 278-283: The fenced code block containing the four numbered items
(① webhook ... ④ WebRTC ...) is missing a language identifier and triggers
markdownlint MD040; fix it by adding a language tag (for example "txt")
immediately after the opening triple backticks of that code fence so the block
becomes a labeled fenced code block and MD040 is resolved.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 679a6e3d-38e3-4cf9-ae20-6ed539b4564e
📒 Files selected for processing (2)
docs/plans/TEMP-fast-mvp-session-artifact-binding-discussion-2026-05-25.mddocs/plans/fast-mvp-edge-bim-server-console-design-2026-05-25.md
| ``` | ||
| ① webhook intake job id / download_status / queue_position | ||
| ② conversion conversion_job_id / status / primary vs fallback | ||
| ③ stage expected vs loaded URL / match status | ||
| ④ WebRTC lifecycle / kit instance / port / video readyState | ||
| ``` |
There was a problem hiding this comment.
Add language identifier to fenced code block.
這個 code fence 缺少 language tag，會持續觸發 markdownlint MD040。
Suggested fix
-```
+```txt
① webhook intake job id / download_status / queue_position
② conversion conversion_job_id / status / primary vs fallback
③ stage expected vs loaded URL / match status
④ WebRTC lifecycle / kit instance / port / video readyState</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 278-278: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @docs/plans/fast-mvp-edge-bim-server-console-design-2026-05-25.md around
lines 278 - 283, The fenced code block containing the four numbered items (①
webhook ... ④ WebRTC ...) is missing a language identifier and triggers
markdownlint MD040; fix it by adding a language tag (for example "txt")
immediately after the opening triple backticks of that code fence so the block
becomes a labeled fenced code block and MD040 is resolved.
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
| **三段 ready 在 coordinator 端的判定（與 viewer 一致）** | ||
|
|
||
| ```txt | ||
| File ready = ifc_ready_job.download_status === "downloaded" | ||
| AND conversion_job.status === "succeeded" | ||
| AND artifacts.model_usdc exists | ||
| Runtime ready = review_session exists | ||
| AND kit_instance_binding is set | ||
| AND viewer participation observed (optional) | ||
| Semantic ready = quality_metrics.semantic_mapping_fidelity set | ||
| AND mapping_has_ifc_type=true | ||
| AND mapping_has_ifc_name=true | ||
| ``` |
There was a problem hiding this comment.
Unify Runtime ready contract with C2 to prevent viewer vs /ui drift.
這段 C3 規則目前和 C2 的 Runtime ready 定義不一致（C2 要求 WebRTC started + stageLoadStatus==="matched"）。若不一致，會出現 viewer 與 /ui 同一 session 顯示不同 ready 結論。建議在這裡直接對齊為同一判定來源與條件。
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/plans/fast-mvp-edge-bim-server-console-design-2026-05-25.md` around
lines 404 - 416, Runtime ready currently defined as "review_session exists AND
kit_instance_binding is set AND viewer participation observed" must be aligned
with C2's contract: change the Runtime ready condition in this document so it
uses the same checks as C2 (require WebRTC started and stageLoadStatus ===
"matched") rather than the existing viewer-observation wording; update the
Runtime ready clause (and any references to review_session /
kit_instance_binding if needed) to explicitly require "WebRTC started" and
"stageLoadStatus === 'matched'" so viewer and /ui use the identical readiness
source and criteria.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 15bab59185
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ../../AGENTS.md)）： | ||
|
|
||
| ```txt | ||
| git switch -c codex/openspec/<change-id> from latest main |
There was a problem hiding this comment.
git switch example with executable syntax
The workflow snippet currently shows git switch -c codex/openspec/<change-id> from latest main, but git switch -c only accepts one optional start-point and does not support the from latest main phrasing; copying this command verbatim will fail before branch setup starts, blocking the OpenSpec flow for contributors who follow this doc literally.
Useful? React with 👍 / 👎.
| gh pr create | ||
| GitHub Actions auto-verify | ||
| merge | ||
| /openspec sync + archive |
There was a problem hiding this comment.
The command list uses /openspec sync + archive as a single step, which is not an executable command format; users following this sequence may treat sync/archive as one command and fail to run either phase correctly, risking unsynced specs or incomplete archive closure.
Useful? React with 👍 / 👎.
Summary
依 2026-05-25
TEMP-fast-mvp-session-artifact-binding-discussion討論收斂 fast MVP demo 為四個獨立 OpenSpec change 的 design 草案。文件性質為 brainstorming 階段參考,source of truth 仍是後續落地的 OpenSpec changes 與 capability specs。切片(依執行順序)
Phase 1(無交集,可平行):
streaming-server-fallback-semantic-mapping(bim-streaming-server)fallback
_run_ifcopenshell_openusd_fallback產出帶ifc_type/ifc_name/entity_id的 mapping;prim path 改/World/<IfcClass>/<GUID>;quality_metrics.json新增semantic_mapping_fidelitycoordinator-serial-conversion-dispatch-queue(bim-review-coordinator)in-memory FIFO 序列化 dispatch;新增
queued_for_conversion/dropped_on_restartlifecycle(converting沿用既有);無 production queue dependencyPhase 2(消費 Phase 1 contract):
viewer-edge-bim-server-console(web-viewer-sample)Window.tsx 重新定位為 Edge BIM Data Server Console(TopBar / 3D / 4 層 Inspector / Bottom Evidence Strip);File / Runtime / Semantic 三段 ready;
USDAssetpicker 預設不渲染、僅?debug=1可見;刪除 collaboration / multi-artifact / issue / repo map UIcoordinator-ui-tri-ready-and-queue(bim-review-coordinator)/ui三段 ready 顯示 + queue visibility + step rename + legacy/api/assetsdisclaimerOut of scope
Test plan
docs/plans/codex/openspec/<change-id>branch + PR + GitHub ActionsSummary by CodeRabbit