Bullinv Forge：MVP 完整定義
本文件為產品層的 MVP 定義，供產品與工程對齊範圍、驗收與優先級。技術實作細節見 開發規格書。
1. MVP 一句話
內部自用的 AI 工作協調層：人類與 agent 在同一套任務與執行紀錄上協作；任務可來自 Linear（或其他 adapter），執行由本機或內網 Worker 跑 CLI agent（如 codex / claude），狀態與 run log 寫回本平台與（可選）上游 issue。
2. 目標使用者與場景
2.1 主要使用者
- 工程師：建立任務、指派給自己或 agent、查看 run、送審。
- 管理者 / Tech Lead：看板與狀態、必要時審核或接手。
- 平台維運：註冊 agent、設定 workspace、排查失敗 run。
2.2 MVP 必須能跑通的場景（端到端）
- 在 Forge 或 Linear 側出現一筆「待執行」任務（兩者至少一條路徑打通）。
- 將任務 指派給已註冊的 agent（或標記為由 agent 認領）。
- Worker 拉取或收到任務，在本機隔離目錄執行 CLI agent，過程寫入 run events。
- 任務進入 完成 / 失敗 / 阻塞 / 待審核 等狀態；人類可在 Forge 內 approve / reject（placeholder 級即可）。
- 團隊在 Forge UI 能看到 任務列表、詳情、留言、run 時間線。
3. 功能範圍（必做）
3.1 Workspace
- 多 workspace 資料隔離（至少：workspace 維度篩選所有任務與 agent）。
- workspace 成員：至少支援 角色
admin/member（細粒度權限可後續擴充）。
3.2 任務（Task）
- 欄位至少包含：
id、workspace_id、title、description（可空）、status、priority、created_at、updated_at。 - 指派：
assignee_type=human|agent|unassigned，assignee_id可空。 - 狀態機（MVP 可簡化，但需前後端一致）：
| 狀態 | 說明 |
|---|---|
draft |
草稿（可選，若不做可從 queued 開始） |
queued |
待認領 / 待執行 |
claimed |
已被認領 |
running |
Worker 執行中 |
blocked |
阻塞，需人類或外部條件 |
in_review |
待審核 |
completed |
完成 |
failed |
失敗 |
cancelled |
取消（可選） |
- 留言（Comment）：任務下可新增文字留言；需記錄作者（user 或 system/agent 標記）。
- 外部關聯：任務可綁定
source_system+source_ref_id+source_url（例如 Linear issue）。
3.3 Agent 註冊（Agent Registry）
- Agent 實體：
id、workspace_id、display_name、runtime_type（MVP：cli）、cli_command（例如codex/claude）、is_active、能力描述（文字即可）、created_at。 - 同一 workspace 可多個 agent；任務可指派給其中一個。
3.4 Run 與執行紀錄
- 每次「開始執行」建立一筆 Run：
id、task_id、agent_id、status、started_at、ended_at（可空）、exit_code（可空）、error_summary（可空）。 - RunEvent（時間序）：
run_id、seq、occurred_at、type、payload（JSON）。 - MVP 最少事件類型：
run_started、log（純文字或結構化片段）、run_completed、run_failed。 - 若 CLI 輸出不易解析，可先將 stdout/stderr 分塊 以
log事件append。
3.5 Worker（執行層）
- 獨立進程，透過 API 輪詢或長輪詢 取得「指派給本機註冊之 agent」且狀態為
claimed/queued（規格書定死一種）。 - 執行前建立 隔離工作目錄（每 run 一個子目錄），將任務描述與必要上下文寫入檔案或環境變數，再 spawn CLI。
- 超時：可配置，預設建議 2h（與常見 agent 任務一致）；超時則 run
failed、task 可failed或blocked（規格書定死）。 - 並發：MVP 可限制每 worker
max_concurrent_runs=1，降低複雜度。
3.6 審核（Review，MVP 級）
- 任務可進入
in_review。 - 具
review權限之使用者可 approve →completed，或 reject → 回到queued或blocked（擇一寫死）。 - 不需完整多級審核鏈。
3.7 與 Linear 整合（MVP 強烈建議列為必做或 P0）
- 目標：Linear 仍為人類習慣的 issue 介面；Forge 為執行與 run 真相擴充層。
- MVP 至少滿足其一（規格書實作時選定並文件化）：
方案 A（推薦先做）：Forge 為主，週期性同步或 Webhook 將 Linear issue 匯入/更新為 Forge Task（單向或雙向擇一）。
方案 B：僅 Forge 內建任務，Linear 留待第二迭代（不建議若你已明確要借力 Linear）。
- 必備資料：
source_system=linear、source_ref_id、source_url。 - 回寫（可選 MVP+）：Run 完成後在 Linear issue 留言摘要連結回 Forge。
3.8 前端（Forge Web）
- 登入（email/password 或 OIDC 擇一，規格書定死）。
- 任務列表：依 workspace 篩選；狀態、優先級、assignee、來源標籤。
- 任務詳情：描述、狀態流轉按鈕（依角色）、留言、Run 列表與事件時間線。
- Agent 管理頁：列表、新增/停用、顯示「最後心跳時間」（若實作 heartbeat）。
- Workspace 設定：成員邀請可延後；至少建立 workspace 與切換。
3.9 驗收與非功能（產品級）
- 可用性：單一 workspace、10 使用者、100 任務量級下操作流暢（無硬性數字，以 demo 可接受為準）。
- 可觀測：API 與 Worker 有 request id / correlation id 寫入 log；失敗任務可追溯 run。
- 安全：Worker 使用 機器專用 API token；不將 Linear/GitHub token 下發給瀏覽器。
4. 功能範圍（不做 / 後續）
以下 明確不納入 MVP，避免範圍膨脹：
- 向量檢索、
pgvector、複雜 memory / RAG（除非另有專案需求）。 - 完整 Skill marketplace、workflow 編輯器、視覺化 DAG。
- 多租戶計費、對外公開註冊、SLA 保證。
- 雲端沙箱 runtime、瀏覽器 automation 標準品（可作為 backlog）。
- 與 GitHub / Slack 的深度整合（可作 P1，見開發規格書選配）。
5. 成功指標（MVP 結案）
- [ ] 任務可由人類建立並指派給 agent，Worker 執行後狀態與 run 在 UI 可見。
- [ ] 至少 一種 CLI agent 路徑跑通（
codex或claude擇一為主路徑）。 - [ ] Linear 關聯 至少滿足：任務可顯示 Linear 連結，或從 Linear 同步一筆 issue 成為 Forge Task（依實作選定方案）。
- [ ]
in_review→ approve/reject 可演示。 - [ ] 文件化：部署步驟、環境變數、如何啟動 Worker。