docs(openspec): add-single-gpu-session-ai-review-mvp 三項使用者裁決寫回——本地小模型 LLM 分流、無 max-hold+10 秒回收倒數、BCFzip 納入本期 - #378
Conversation
… LLM 分流納入 MVP、無 max-hold+前端 10 秒回收倒數、BCFzip 納入本期 2026-07-22 使用者直接裁決 OQ-2/OQ-A(含 OQ-3)/OQ-B: - ai-review-draft-pipeline 新增「本地小模型 LLM 分流」Requirement(advisory-only、模型 id/版本標記、停用整層降級、不引入外部雲端 LLM API) - session-lifecycle 新增「回收倒數與互動保活」Requirement(無互動軟門檻第二回收路徑、前端 10 秒倒數、互動即取消;維持無 max-hold) - bcf-contract-export 新增「BCFzip(BCF-XML 3.0)」Requirement(與 JSON 同源、官方 XSD 驗證) proposal/design 補裁決紀錄(原話+解讀+落點);tasks 0.1 勾銷、新增 2.11/3.6/6.4;殘留 OQ-1/4/5/6+無主會議子題列 0.2。 deltaCount 22→25;npx openspec validate --strict 通過。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U8BiTXJtW1jPYPEtPq27Cx
|
Warning Review limit reached
Next review available in: 25 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (6)
✨ 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 is a spec-only OpenSpec documentation change that writes back three user product decisions (made 2026-07-22 on PR #377's Open Questions) into the existing add-single-gpu-session-ai-review-mvp change. It resolves OQ-2 (adopt a local small-model LLM triage layer), OQ-A/OQ-3 (keep no max-hold, add an inactivity-based second reclaim path with a front-end 10-second countdown), and OQ-B (bring the BCFzip / BCF-XML 3.0 serializer into this phase). No code, frozen files, or service behavior are touched.
Changes:
- Added three new capability Requirements (session reclaim-countdown/interaction-keepalive, local LLM triage layer, BCFzip export) with scenarios, and updated the corresponding
idle/queue/clash-review/BCF-JSONrequirement notes to cross-reference them. - Restructured
proposal.mdOpen Questions into a "resolved (2026-07-22)" section plus remaining OQ-1/4/5/6 gates, and synced What Changes / Capabilities / Non-goals. - Updated
design.mddecisions 3 & 6, added decision 9 (second reclaim path + R1.2 compatibility argument), refreshed the anti-false-green table, and updatedtasks.md(checked off 0.1, added tasks 2.11/3.6/6.4, renumbered old test task 3.6→3.7).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
specs/session-lifecycle/spec.md |
Adds "reclaim countdown & interaction keepalive" Requirement (second reclaim path, 10s countdown) plus 3 scenarios; annotates idle/queue requirements with the OQ-A/OQ-3 decision. |
specs/ai-review-draft-pipeline/spec.md |
Adds "local small-model LLM triage" Requirement (advisory-only, model id/version, no external cloud LLM, graceful full-layer disable) plus 3 scenarios; updates clash-review note for OQ-2. |
specs/bcf-contract-export/spec.md |
Adds "BCFzip (BCF-XML 3.0)" Requirement (same-source, official XSD) plus 2 scenarios; updates JSON-export note for OQ-B. |
proposal.md |
Reorganizes Open Questions into resolved vs. remaining; syncs vertical-slice acceptance, What Changes, Capabilities, and Non-goals. |
design.md |
Updates decisions 3 & 6, adds decision 9 with R1.2 compatibility reasoning, refreshes the anti-false-green table. |
tasks.md |
Checks off task 0.1, folds OQ-3 into 0.2 residuals, adds tasks 2.11/3.6/6.4, and renumbers the streaming/governance test task 3.6→3.7 with LLM assertions. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![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: d4259f37a7
ℹ️ 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".
| - [ ] 3.4（governance-service）finding ingest fail-closed 驗證：強制 GUID + 規則引用 + viewpoint + 信心值 + abstain 標記，缺任一進 abstain 桶不進佇列。 | ||
| - [ ] 3.5（governance-service）issues store 疊加 `source_type=ai_review` 與 draft 狀態（不改既有狀態機語意）；draft 不入正式 issue 清單、不觸發派發。 | ||
| - [ ] 3.6 跑 streaming pytest（服務目錄）+ governance 測試：缺 OCC fail-loud、size guard、ingest 缺欄位拒收、120 筆審查後正式 issues 淨增 0；語意測試：抽樣 viewpoint 視錐在 IFC 座標系包含目標 GUID bbox。 | ||
| - [ ] 3.6（streaming/coordinator）本地小模型 LLM 分流層（2026-07-22 裁決納入）：本地 inference 服務選型與整合（Ollama／llama.cpp 類，實作期收斂）、對通過 ingest 的 finding 產 advisory 分流註記（嚴重度／分組建議／摘要）、模型 id＋版本標記寫入 draft、僅寫 advisory 欄位（觸碰強制欄位或人審欄位 fail-loud）、停用/故障/逾時整層降級。 |
There was a problem hiding this comment.
When task 3.6 selects a local inference backend that uses the same RTX GPU as Kit, this new requirement allows that inference load while the Phase 0 hard gate still certifies only the 1 primary + k spectator VRAM/TTFF/soak path in gpu-session-baseline/spec.md. In that environment, admission SLOs can pass without the LLM contention and then regress during the vertical slice once review inference runs; either constrain the LLM to CPU/separate hardware or include representative LLM inference in the baseline and E2E gates.
Useful? React with 👍 / 👎.
|
|
||
| ### Requirement: LLM 分流層 SHALL 以本地小模型實作且僅產 advisory 欄位，停用不中斷審查 | ||
|
|
||
| MVP SHALL 落地最小 LLM 分流層：以本地部署的小型模型（local inference，如 Ollama／llama.cpp 類服務的開源小模型，選型於實作期收斂）對通過 ingest 驗證的 finding 產生分流註記（嚴重度建議、分組建議、自然語言摘要等 advisory 欄位，具體欄位實作期定案）。LLM 產出 SHALL 僅寫入 draft 的 advisory 欄位：SHALL NOT 修改證據包既有強制欄位、SHALL NOT 繞過 draft gate、SHALL NOT 觸發自動 accept／建立／關閉／指派。每筆 LLM 註記 SHALL 標註模型 id 與版本，使 `source_type=ai_review` 的 AI 版本標記具真實模型語意。推論 SHALL 於本地／內網執行，SHALL NOT 引入外部雲端 LLM API 依賴（審查資料不出域）。LLM 層停用、故障或逾時 SHALL 整層降級：finding 以無 LLM 註記形式照常入佇列，deterministic 審查閉環 SHALL 不中斷。 |
There was a problem hiding this comment.
This new requirement says the LLM writes draft advisory fields and model id/version, but human-triage-queue/spec.md and task 5.2 still restrict AI-owned writes to evidence/last_seen/occurrence-style fields. With LLM enabled, the store can therefore reject the advisory writes that this spec now requires; update the field ownership/schema to explicitly reserve AI-owned advisory/model metadata fields.
Useful? React with 👍 / 👎.
| **裁決**：自派發重定義＝自動產生 + 路由人審佇列 + 去重排序；建立/關閉/指派/reopen 一律人審 gate。AI 產出一律 draft 狀態（issues store 疊加 `source_type=ai_review`），draft 不出現在正式 issue 清單、不觸發派發。正式 issue 淨增＝人審 accept 數。 | ||
|
|
||
| **規則引擎先行、LLM 層可整層關閉**：deterministic IfcClash 承擔主審查量；LLM 分流/優化建議層設計成故障或超預算時可整層停用而不中斷核心審查閉環。MVP 不建 LLM 層，僅凍結此降級接縫（見 Open Question OQ-2：MVP 的「AI 審查」實為零模型推論的確定性 clash detector，須向使用者揭示 headline 落差）。 | ||
| **規則引擎先行、LLM 層可整層關閉**：deterministic IfcClash 承擔主審查量與正確性底線；LLM 分流層設計成故障或超預算時可整層停用而不中斷核心審查閉環。**裁決更新（2026-07-22，OQ-2 消解）**：使用者裁決 MVP 納入最小本地小模型 LLM 分流層（local inference、advisory-only、模型 id/版本標記、停用整層降級、不引入外部雲端 LLM API），取代原「僅凍結接縫不實作」方案；`source_type=ai_review` 的 AI 版本標記自此具真實模型語意。 |
There was a problem hiding this comment.
After this line makes a real local LLM part of the MVP, the SEAM-2 paragraph later in design.md still says Phase 2 has IfcClash as the only checker and that the MVP only lands IfcClash. That stale design clause directly contradicts the new spec/task requiring the LLM layer, so implementers or reviewers could drop 3.6 and still appear to follow the design; update the seam/YAGNI wording to include the LLM component.
Useful? React with 👍 / 👎.
|
|
||
| ### Requirement: session 回收倒數與互動保活 SHALL 作為第二回收路徑，前端顯示 10 秒倒數且互動即取消 | ||
|
|
||
| 除 readyState=4 peer 存在性 idle（第一回收路徑）外，SessionBroker SHALL 支援「無互動軟門檻」第二回收路徑：session 連續 T_inactivity 秒無任何使用者互動（viewer 輸入事件／DataChannel 指令）但仍有 readyState=4 peer 連線時，session SHALL 進入回收倒數。進入回收倒數時，前端 SHALL 對該 session 所有已連線 viewer 顯示 10 秒倒數；倒數期間任一 peer 的任何互動 SHALL 取消本次回收並重置 inactivity 計時；倒數歸零 SHALL teardown 回收並以 reason=inactivity 寫入 session ledger，佇列中下一位獲派。MVP SHALL 維持無 max-hold hard cap：有持續互動的會議 SHALL NOT 因持有時長被強制回收。T_inactivity SHALL 可設定，預設值 SHALL 於 Phase 0 後訂定。 |
There was a problem hiding this comment.
This requirement says the T_inactivity default is set after Phase 0, but the existing Phase 0 report/SLO schema only produces VRAM/TTFF/success/idle-timeout/leak thresholds and this commit does not add T_inactivity to that gate. Implementers can therefore reach task 2.11 with an unmeasured or arbitrary inactivity threshold; add it to the baseline schema/deployment SLO checklist, or remove the Phase 0 dependency and define another source of truth.
Useful? React with 👍 / 👎.
|
|
||
| ### Requirement: session 回收倒數與互動保活 SHALL 作為第二回收路徑，前端顯示 10 秒倒數且互動即取消 | ||
|
|
||
| 除 readyState=4 peer 存在性 idle（第一回收路徑）外，SessionBroker SHALL 支援「無互動軟門檻」第二回收路徑：session 連續 T_inactivity 秒無任何使用者互動（viewer 輸入事件／DataChannel 指令）但仍有 readyState=4 peer 連線時，session SHALL 進入回收倒數。進入回收倒數時，前端 SHALL 對該 session 所有已連線 viewer 顯示 10 秒倒數；倒數期間任一 peer 的任何互動 SHALL 取消本次回收並重置 inactivity 計時；倒數歸零 SHALL teardown 回收並以 reason=inactivity 寫入 session ledger，佇列中下一位獲派。MVP SHALL 維持無 max-hold hard cap：有持續互動的會議 SHALL NOT 因持有時長被強制回收。T_inactivity SHALL 可設定，預設值 SHALL 於 Phase 0 後訂定。 |
There was a problem hiding this comment.
Because the same spec already requires health checks to use DataChannel responses, counting DataChannel commands as user interaction here can make an abandoned viewer reset T_inactivity whenever automated probe/control traffic flows over the channel. In that scenario the forgotten-tab starvation case this requirement is meant to close remains open; define interaction as user-originated viewer input or explicitly exclude health/probe/control messages from the inactivity clock.
Useful? React with 👍 / 👎.
| ## 8. Vertical slice E2E（真實 IFC fixture，host-native Kit + RTX） | ||
|
|
||
| - [ ] 8.1 單一 vertical slice 一次跑通：轉檔 → AI 草稿（含 GUID/viewpoint/引用/信心值）→ 人審 accept 轉正式 issue → BCF 3.0 匯出 0 error → 6 人 WebRTC 會議看模型討論該 issue ≥30 分鐘不斷流 → 版本回跑產差異報告；收 E2E evidence（錄影/trace 落 `artifacts/e2e/`，PNG 需 `git add -f`）。 | ||
| - [ ] 8.1 單一 vertical slice 一次跑通：轉檔 → AI 草稿（含 GUID/viewpoint/引用/信心值）→ 人審 accept 轉正式 issue → BCF 3.0 JSON＋BCFzip 匯出 0 error → 6 人 WebRTC 會議看模型討論該 issue ≥30 分鐘不斷流 → 版本回跑產差異報告；收 E2E evidence（錄影/trace 落 `artifacts/e2e/`，PNG 需 `git add -f`）。 |
There was a problem hiding this comment.
Now that the MVP includes a real local LLM分流 layer, the end-to-end acceptance path still only requires the draft to contain GUID/viewpoint/reference/confidence. An implementation can satisfy this vertical slice with the old deterministic-only draft and never prove that advisory annotations plus model id/version survive a real run, so add those LLM fields to the E2E evidence requirement.
Useful? React with 👍 / 👎.
|
|
||
| ### Requirement: 匯出 SHALL 一併提供 BCFzip（BCF-XML 3.0）供桌面工具直接開啟 | ||
|
|
||
| 除 BCF-API 3.0 JSON 外，匯出 SHALL 提供 BCFzip serializer：依 BCF-XML 3.0 官方規格產 .bcf zip 容器（markup／viewpoint 檔案佈局依官方規格），與 JSON 匯出共享同一 topic/comment/viewpoint 邏輯模型（同源資料，SHALL NOT 出現兩面不一致）。匯出物 SHALL 以官方 BCF-XML 3.0 schema（XSD）驗證通過為準，供 BIMcollab/Solibri/Revit 等桌面 BCF 工具直接開啟。 |
There was a problem hiding this comment.
This requirement names the output as a .bcf zip container; if implementers follow that literally as a .bcf file or leave the extension ambiguous, desktop BCF tools may not recognize the export even when the XML validates. Specify .bcfzip consistently for the BCF-XML zip artifact, while keeping the internal layout/XSD requirements unchanged.
Useful? React with 👍 / 👎.
Change Classification
Why
PR #377 合入的 OpenSpec change 留有 3 項待使用者確認的產品決策(OQ-A/OQ-B/OQ-2)。使用者於 2026-07-22 直接裁決:
What(spec-only,零程式碼變更)
specs/session-lifecycle/spec.md:+「回收倒數與互動保活」Requirement(7→8);R1.2/佇列 OQ 註記同步specs/ai-review-draft-pipeline/spec.md:+「本地小模型 LLM 分流」Requirement(3→4,advisory-only/模型版本標記/停用降級/不出域)specs/bcf-contract-export/spec.md:+「BCFzip 匯出」Requirement(2→3,同源+官方 XSD 驗證)proposal.md:Open Questions 重整為「已裁決(原話+解讀+落點)」+「殘留(OQ-1/4/5/6+無主會議子題)」;What Changes/Capabilities/非目標同步design.md:決策 3/6 裁決更新+新增決策 9(第二回收路徑與 R1.2 相容性論證)+反假綠表更新tasks.md:0.1 勾銷(裁決已取得並記錄)、0.2 收殘留、新增 2.11(回收倒數)/3.6(LLM 分流)/6.4(BCFzip),原 3.6 測試改列 3.7 並補 LLM 斷言Validation
deltaCount 22→25(session-lifecycle 8/ai-review-draft-pipeline 4/bcf-contract-export 3/其餘不變)。
Known risks
🤖 Generated with Claude Code
https://claude.ai/code/session_01U8BiTXJtW1jPYPEtPq27Cx