docs(plans): 計畫文件對齊 origin/main #224（單一正典路由表＋6 服務埠表＋官方技術棧總表） - #227
Conversation
把 docs/plans 五份文件＋兩份原型 .html 對齊 2026-06-17 的 origin/main #224 現況， 收斂三處長期會誤導 AI 的漂移源： - 路由：新增《互動規格》A.1.1「正典路由表（22 條）」為唯一事實來源； README / 設計 / 開發三份改為「指向本表」不再各自維護。 裁定 `#gpu` 為 GPU 審查室正典 route、`#review` 為別名；`#admin` 標待建。 - 服務埠：§2.0.2 更新為現況 6 服務（補 streaming-server / web-viewer / kit-manager-api / kit-manager-web），附 compose 埠號實證； `#instances`/`#runtime` 後端定為 kit-manager-api(:8010)。 - 官方件：新增《開發軌跡》§2.0.5「官方技術棧對齊總表」單一速查， 《互動規格》補 C.5（Replicator/Cosmos/Isaac）、C.6（OpenUSD schema）展開細節； 標註 Cosmos 3（2026-06 換架構/授權）鎖版風險。 - 第二原型：把 ai-bim-geo-viewer-prototype.html（3D 驗收示意，對應 #viewer/M4） 納入各文件資產盤點，並在該檔加可見浮水印「CANVAS 示意 · 非真 WebRTC 串流」。 - 設計規格導覽改三群→四群，共用 viewer 框架補官方 extension 清單。 純文件變更；衝突時仍以規格為準。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JEyNWhEmb3x8oinY3B2v9V
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (7)
📝 WalkthroughWalkthroughUpdates the AI-BIM governance docs/plans suite and HTML prototypes: corrects BCF version from 3.0 to 2.1, renumbers demo project/session IDs (899/988 → 889/990), adds a canonical 22-route table ( ChangesAI-BIM Governance Spec and Prototype Alignment
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
✨ 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 aligns five planning/spec markdown files and two HTML prototypes under docs/plans/ with the current state of origin/main (#224). It is a docs-only change with no code or API modifications. The goal is to eliminate three sources of drift that could mislead AI agents: route definitions, service port tables, and official tech stack boundaries.
Changes:
- Route convergence: Introduces a single canonical route table (A.1.1, 22 entries) in the interaction spec, and updates all other documents to point to it instead of maintaining separate route lists. Designates
#gpuas canonical,#reviewas alias,#adminas pending. - Service/port table & tech stack: Updates the service table from 3 to 6 services (§2.0.2), adds a unified official tech stack reference table (§2.0.5), and supplements A1–A10 sections with official API/capability boundaries and spec-to-done DoD checklists.
- Prototype alignment: Updates demo data project IDs from
899/988to889/990, changes BCF version references from 3.0 to 2.1, adds a watermark to the geo-viewer prototype HTML, and adds anofficialfield to 3D viewer cards in the main prototype.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
docs/plans/docs-plans-README.md |
Adds effectiveness-order clarification, mentions second prototype, updates route/service references to point to canonical tables |
docs/plans/ai-bim-governance-開發軌跡與執行計畫.md |
Adds geo-viewer prototype to asset table, expands service table to 6 services (§2.0.2), adds §2.0.5 tech stack table, adds official API/capability boundaries and DoD checklists for A1–A10, adds §2.99.1 platform page table |
docs/plans/ai-bim-governance-設計規格.md |
Updates navigation from 3 groups to 4, adds official extension list to shared viewer framework, adds geo-viewer prototype and governance-service to asset status table |
docs/plans/ai-bim-governance-實作紀律與技術債防線.md |
Adds three discipline rules (route single-source, port single-source, official-only tech), adds 2026-06-17 alignment changelog entry |
docs/plans/ai-bim-governance-互動實作規格與標準對齊.md |
Adds A.1.1 canonical route table (22 entries), adds B.5 viewer prototype reference with watermark rule, adds C.5 (Replicator/Cosmos/Isaac) and C.6 (OpenUSD schema) sections, expands IX-3D-02 DataChannel mechanism details |
docs/plans/ai-bim-governance-prototype.html |
Aligns project IDs (889/990/271), changes BCF 3.0→2.1, adds official field to 3D viewer cards, updates shared viewer callout with official extension names |
docs/plans/ai-bim-geo-viewer-prototype.html |
Adds fixed-position watermark "⚠ CANVAS 示意 · 非真 WebRTC 串流" |
Comments suppressed due to low confidence (1)
docs/plans/ai-bim-governance-互動實作規格與標準對齊.md:279
- The newly added sections C.5 and C.6 are placed before the pre-existing C.4, making the section order C.1 → C.2 → C.3 → C.5 → C.6 → C.4. This is confusing for readers and AI agents navigating by section number. Consider either renumbering (e.g., swap C.4 to come before C.5/C.6) or renaming the new sections to C.4.x to preserve alphabetical order.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| } | ||
| function convDrop(dstId){const j=CONV.jobs,s=j.findIndex(x=>x.id===CONV_DRAG),d=j.findIndex(x=>x.id===dstId);CONV_DRAG=null;if(s<0||d<0||s===d)return;if(j[s].state!=='queued'||j[d].state!=='queued')return;const[m]=j.splice(s,1);const d2=j.findIndex(x=>x.id===dstId);j.splice(d2,0,m);paintConv();} | ||
| function convAdd(){const D=['機電','消防','管線','施工','牆面'],P=['270','899','988'];CONV.jobs.push({id:'J-'+(CONV.nextId++),proj:P[Math.floor(Math.random()*3)],disc:D[Math.floor(Math.random()*5)],size:(20+Math.floor(Math.random()*100))+' MB',state:'queued',worker:null,pg:0,cov:null});} | ||
| function convAdd(){const D=['機電','消防','管線','施工','牆面'],P=['270','889','990','271'];CONV.jobs.push({id:'J-'+(CONV.nextId++),proj:P[Math.floor(Math.random()*3)],disc:D[Math.floor(Math.random()*5)],size:(20+Math.floor(Math.random()*100))+' MB',state:'queued',worker:null,pg:0,cov:null});} |
![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: fd027cf625
ℹ️ 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".
| | BC | `#issues` | Issue / BCF 中心 | 核心治理 | governance-service issues + bcf | 🟢 Issue DB + BCF 2.1 真匯出 | | ||
| | RP | `#reports` | 報表中心 | 核心治理 | governance-service excel_export | 🟡 報表骨架 | | ||
| | 3D | `#viewer` | 3D Viewer 呈現 | 核心治理 | 證據面板（不內嵌 3D）；3D 來自 streaming-server WebRTC | 🟡 證據矩陣版；openStage/focusPrim/selectPrims 真，highlightPrimsRequest P1.5 | | ||
| | 01 | `#gpu`（別名 `#review`） | GPU 審查室 / Review Room（MVP） | 核心治理 | coordinator `/ui/open` redirect → web-viewer + streaming-server | 🟡 v1＝導引既有 viewer + Tool Rail | |
There was a problem hiding this comment.
When users follow this new route contract and open #gpu, the current SPA does not render the Review Room: in web-viewer-sample/src/console/routing.ts at this commit, #gpu is recognized as an operator-console hash, but OperatorConsole.readPage() only accepts coordinator, intake, runtime, review, kit, and demo-control, so #gpu falls back to CoordinatorPage. Either alias gpu to review in the router or avoid declaring it canonical here, otherwise the documented primary route leads to the wrong page.
Useful? React with 👍 / 👎.
| | A9 | `#a9` | 設計 / 審查 Copilot | 核心治理 | usd-code-mcp :9903 | 🟡 示範頁；AI 動作預覽 | | ||
| | A10 | `#a10` | 機器人 / 巡檢模擬 | 核心治理 | Isaac Sim + Cosmos | 🟡 示範頁；核心舞台需 GPU | | ||
| | CV | `#conv` | IFC→USD 轉檔排程（P1） | OMNIVERSE RUNTIME | coordinator `/api/conversions` + streaming-server 轉檔 | 🟡 讀真 ifc-ready jobs；插隊/重試/coverage P1 | | ||
| | SS | `#sessions` | Session 管理 | OMNIVERSE RUNTIME | coordinator `/api/sessions` | 🟡 Phase1 read-only；結束 session IX-SS-04 已設計(#224)；occupied 證據鏈 P1 | |
There was a problem hiding this comment.
For any implementation generated from this canonical table, calling coordinator /api/sessions will fail: in this commit there is no /api/sessions route, while the coordinator exposes session lifecycle under /api/review-sessions... and the read-only session dashboard consumes /api/runtime/status. Please align the SS backend entry with the actual route or explicitly mark /api/sessions as a planned alias.
Useful? React with 👍 / 👎.
| | governance-service | :49102 | A1 規則引擎、Issue/BCF（**BCF 2.1 自寫**）、diff（GlobalId 鍵）、報表（CPU 即可）；**永遠 host-native，不入任何 compose；browser 不直連，一律經 coordinator proxy** | host-native | | ||
| | bim-streaming-server（Kit 本體） | 信令 :49100 · 串流 :47998 · 轉檔/控制 API :49101 · spectator 起始 :49110 | Omniverse Kit 串流（WebRTC）、IFC→USD 轉檔授權方、USD stage 組裝 | host-kit（compose.host-kit.yml） | | ||
| | web-viewer-sample | :5173 | 前端收 WebRTC frame、指令走 DataChannel（`highlightPrimsRequest`） | container | | ||
| | kit-manager-api | :8010 | `#instances`/`#runtime` 的真遙測後端：`/health` `/instances` `/runtime`；restart/release 走 audited intent | runtime-manager compose | |
There was a problem hiding this comment.
In deployments using this table to wire #instances/#runtime, these paths will 404: at this commit services/kit-manager-api/app/main.py exposes /health, /api/kit/instances/current, /api/usdc, and open/close routes, but not /instances or /runtime; the current console also reads coordinator /api/runtime/status. Please either list the implemented kit-manager paths or mark /instances and /runtime as planned so telemetry is not wired to nonexistent endpoints.
Useful? React with 👍 / 👎.
| - 解析＋規則：IfcOpenShell 0.8.x（`ifcopenshell.open(path)`；`model.by_type("IfcDoor")` 含子類；Pset/Qto 用 `ifcopenshell.util.element.get_psets(el)` / `get_pset(el, name)` / `get_psets(el, qtos_only=True)`；空間樹 `get_container(el)` / `get_decomposition(storey)`）。 | ||
| - IDS 規則：對齊 buildingSMART **IDS 1.0**（`.ids` XML；facets 僅 **Entity / Attribute / Property / Classification / Material / PartOf**；IFC 類別大寫精確比對）；執行用 **ifctester**（`ifctester specs.ids model.ifc -r Json|Html|Bcf`）。 | ||
| - **能力邊界（重要）**：IDS **只驗英數資訊（屬性/數量/分類/材質/關係），不驗幾何、不驗計算值、且假設 IFC 已 schema-valid**。幾何類（碰撞穿樑）一律走 A3 的 clash 引擎，**不要硬塞進 IDS**。 | ||
| - BCF 匯出：用 IfcOpenShell **`bcf`** 庫（`from bcf.bcfxml import load`，支援 2.1/3.0；現行交付 2.1）。`.bcfzip` 結構＝每 topic 一資料夾（GUID 命名）含 `markup.bcf` + `viewpoint.bcfv` + `snapshot.png`；component 參照必須帶 **IfcGuid**（22 字元 IFC base64，字母表 `0-9A-Za-z_$`，用 `ifcopenshell.guid.compress()/expand()`，**勿用一般 base64 庫**）。viewpoint 選取或上色超過約 **1000 構件**要提示使用者（官方效能門檻）。 |
There was a problem hiding this comment.
For A1 implementers following this new “directly follow this” section, this reverses the current repo contract: governance-service/bcf/bcf_writer.py intentionally authors BCF 2.1 with stdlib and avoids importing bcf-client because that transitive package is GPLv3, while this line instructs agents to use the official bcf library. Please keep the short-term guidance aligned with the existing GPL-safe exporter and only describe the official library as a future upgrade path.
Useful? React with 👍 / 👎.
| | 碼 | route | UI 頁名 | 群組 | 後端 / 服務 | 狀態 | | ||
| |---|---|---|---|---|---| | ||
| | ⌂ | `#home` | 今天要做什麼 | 工作台 | coordinator（彙整） | 🟢 版型+入口；跨應用待辦待接真來源 | | ||
| | A1 | `#a1` | 治理與模型檢核（P0） | 核心治理 | governance-service rule_engine（經 proxy） | 🟢 真規則/Issue/Excel/BCF2.1；五步串接、點規則展開、3D 高亮 P1.5 待建 | |
There was a problem hiding this comment.
This canonical status now says A1 has the five-step flow wired and rule rows expandable, but the same verified gap report below says the stepper is still only a layout and rule expansion is not implemented. Agents using this table as the source of truth can incorrectly declare A1 done or skip the remaining UI work, so the status should distinguish the real rule/Issue/BCF backend from the unfinished stepper and expansion interactions.
Useful? React with 👍 / 👎.
| | A8 | `#a8` | Synthetic Data | 核心治理 | Replicator + Cosmos Transfer | 🟡 示範頁；取景台 | | ||
| | A9 | `#a9` | 設計 / 審查 Copilot | 核心治理 | usd-code-mcp :9903 | 🟡 示範頁；AI 動作預覽 | | ||
| | A10 | `#a10` | 機器人 / 巡檢模擬 | 核心治理 | Isaac Sim + Cosmos | 🟡 示範頁；核心舞台需 GPU | | ||
| | CV | `#conv` | IFC→USD 轉檔排程（P1） | OMNIVERSE RUNTIME | coordinator `/api/conversions` + streaming-server 轉檔 | 🟡 讀真 ifc-ready jobs；插隊/重試/coverage P1 | |
There was a problem hiding this comment.
If the conversion queue is wired from this canonical backend entry, coordinator /api/conversions will miss the implemented routes: at this commit the coordinator exposes dev conversion proxy routes under /api/dev/conversions..., plus /api/conversions/:id/quality-metrics, while listing is read through runtime/intake summaries rather than a bare /api/conversions. Please document the actual routes or mark /api/conversions as a planned façade so the P1 queue is not built against a 404.
Useful? React with 👍 / 👎.
摘要
把
docs/plans/五份文件＋兩份原型.html對齊 2026-06-17 的 origin/main #224 現況，收斂三處長期會誤導 AI 的漂移源（路由、服務埠、官方件邊界）。純文件變更，不動任何程式碼或 API 行為。變更內容
#gpu為 GPU 審查室正典 route、#review為別名；#admin標待建。#instances/#runtime後端定為 kit-manager-api（:8010）。ai-bim-geo-viewer-prototype.html（3D 驗收示意，對應#viewer／M4）加入各文件資產表，並在該檔加可見浮水印「CANVAS 示意 · 非真 WebRTC 串流」。變更檔案（同步來源：origin/main #224）
docs/plans/docs-plans-README.mddocs/plans/ai-bim-governance-設計規格.mddocs/plans/ai-bim-governance-開發軌跡與執行計畫.mddocs/plans/ai-bim-governance-互動實作規格與標準對齊.mddocs/plans/ai-bim-governance-實作紀律與技術債防線.mddocs/plans/ai-bim-governance-prototype.htmldocs/plans/ai-bim-geo-viewer-prototype.html驗證
git diff --cached --check無 trailing whitespace（僅 LF→CRLF 警告，Windows 正常）。docs/CLAUDE.md：無自動化 link checker，PR 描述列出 doc path 與同步來源即視為 verify pass。🤖 Generated with Claude Code
https://claude.ai/code/session_01JEyNWhEmb3x8oinY3B2v9V
Summary by CodeRabbit
Documentation
New Features
Updates