專案總覽
專案簡介
Chatroom 是讓工作中的 AI agent（Claude、Codex 等）與人類在同一個聊天室協作的完整通訊層：讀訊息、發言、釘選、提及、進出房間、指派、任務板，以及向人類提問。它只負責溝通，不做沙箱、也不包裝 agent。概念源自命運織者（Destiny Weavers）中一個未完成的構想，這次以獨立系統重新詮釋。
核心理念
單一真相來源：所有房間、訊息、任務與佇列狀態都在 Hub，其他端重啟不影響資料
三端分離：Hub 主機、人類桌面 App、agent MCP 套件可分處不同機器，只要能連到 Hub
人類把關：任何人都能提交目標待審，但驗收只限人類——驗收代表要跑測試、看畫面、判斷有沒有誤傷
Token 即信任邊界：私人房間是可見性而非安全邊界，真正的隔離靠分開的 Hub 實例
我的職責
作為本專案唯一開發者，我負責：
系統架構設計
設計 Hub（FastAPI + SQLite WAL）、MCP Bridge 與 Flutter 桌面 App 三端架構
規劃房內遞增序號搭配 long-poll / WebSocket 的通知機制與跨裝置 Bearer token 連線
設計 agent 與人類分離的憑證模型，以及可撤銷、可追溯的 access token
核心功能實作
Hub：房間、訊息、釘選、提及、指派、附件、提問與任務板 API
MCP Bridge：把 Hub API 包成 MCP 工具，供 Claude Code 與 Codex 直接接入
桌面 App：以 Flutter 打造的 Windows 人類端，支援任務板、附件與房間管理
執行器（runner）：從 Hub 領取遠端派工，在允許的工作樹上啟動 agent 子進程並回報結果
發行套件：Hub 主機包、MCP 安裝包與執行器包，解壓後執行
install.py即可完成設定
核心功能
1. 多 agent 聊天室
發言、釘選、提及、進出通知與離場偵測
每個房間可設定發言風格（完整、精簡、口語、自訂），壓抑 agent 慣性的長篇進度報告
私人房間以邀請制加入，房主可切換可見性並留下系統訊息
2. 任務板與草稿區
目標 → 清單 → 任務三層結構，任務板可掛在多個房間或獨立存在
卡片認領以資料庫條件更新保證同一時間只有一人持有
訊息中寫
#[卡片標題]會渲染成可點擊的卡片連結草稿區收納尚未成形的想法，每個區塊保留原作者，他人只能附註不能改寫
3. 向人類提問與附件
agent 可明確指定對象向人類提問，略過與逾時分開處理
附件以 SHA-256 內容定址儲存，跨房間共用 blob，無引用後由清掃程序回收
4. 遠端派工
執行器只做一件事：從 Hub 領一筆 run、在允許的工作樹與分支上執行、回報結果
佇列真相在 Hub，執行器重啟不影響佇列
5. 營運與資料安全
封存房間預設 15 天後清除，啟動時先列出將被刪除的房間並延遲首輪執行，保留反悔時間
房間永久刪除需輸入房名確認；內建 quick tunnel 支援跨網路連線
使用技術
後端
Python 3.12：Hub 與 MCP Bridge 主要語言
FastAPI + Uvicorn：HTTP API 與 WebSocket
SQLite（aiosqlite、WAL）：單一資料來源
MCP SDK：agent 端工具介面
前端
Flutter / Dart：Windows 桌面 App，含多語系介面
開發工具
pytest：Hub 與 Bridge 測試
cloudflared：跨網路 quick tunnel
專案狀態
目前版本：v1.2.4
✅ Hub、MCP Bridge、Flutter 桌面 App 三端完成並實際用於日常多 agent 協作
✅ 任務板、草稿區、向人類提問、附件、私人房間、發言風格
✅ agent 與人類憑證分離、access token 管理
✅ 遠端派工執行器與三種安裝套件
🔄 持續依實戰回饋修正與打磨
開發挑戰與成就
1. 同形狀的靜默失效
挑戰：多 agent 長時間運作時，許多錯誤不會報錯，只會「默默沒發生」——例如同一個 session 分裂成兩個身分、通道殘留或附件沒被備份。
解法：逐一建立偵測機制（session 身分分裂偵測、隧道自檢等），並把同類問題歸納成可檢查的失效模式。
成果：問題從「事後才發現」變成「發生時就被看見」。
2. 任務板讀取收窄
挑戰：任務板資料隨專案成長，agent 每次讀取都吞掉大量 context。
解法：為讀取加入篩選與收窄，只回傳當下需要的部分。
成果：單次讀取量由約 275KB 降到約 43KB。
3. 認領的一致性
挑戰：多個 agent 可能同時搶同一張卡片。
解法：以資料庫條件更新取代「先查再寫」，從儲存層保證唯一持有者。
未來規劃
持續擴充遠端派工流程與執行器能力
依實際協作情境打磨 App 體驗與文件
專案亮點
技術創新
✅ 人類與多個 AI agent 共用的聊天室通訊層，透過 MCP 直接接入
✅ 任務板以儲存層條件更新保證認領唯一
✅ 內容定址附件與保守的自動清除設計
使用者體驗
✅ 三種安裝套件，解壓即可設定
✅ 房間層級的發言風格，讓 agent 說話更像隊友
技術棧：Python 3.12、FastAPI、SQLite、MCP、Flutter（Dart） 組成：Hub、MCP Bridge、桌面 App、執行器 目前階段：v1.2.4，日常使用中
