project-overview

# cc-office — 專案總覽 ## TL;DR **當下**：cc-office 是 Claude Code CLI 的 web 客戶端，對齊官方 VS Code extension 的 protocol — ChatPanel / PermissionModePicker / SessionContext / Storybook 覆蓋、design tokens、Tailwind scale 等。 **長期願景（roadmap）**：把 Claude Code 的使用體驗包裝成 RPG 遊戲（Code Quest / CodeLand），**此願景目前尚未實作**，相關 skill（`battle-management`、`map-system`）描述的是目標，不是現況。 做決策時以當下 client 為準；roadmap 內容當 reference，不當 spec 套用。 --- ## 當前架構（已實作） ``` ┌──────────────────────────────────────────┐ │ Client (apps/web) │ ← React + Vite │ - ChatPanel / Permission UI │ │ - SessionContext / ChannelProvider │ │ - Storybook stories, Tailwind v4 tokens │ └──────────────────┬───────────────────────┘ │ WebSocket /ws ┌──────────────────▼───────────────────────┐ │ Server (apps/server) │ ← Node + Inversify │ - WsTransport + middleware pipeline │ │ - socket handlers, ChannelManager │ │ - SessionStore (Drizzle / SQLite) │ │ - 對齊 Claude Code extension protocol │ └──────────────────┬───────────────────────┘ │ WebSocket /summoner (RPC) ┌──────────────────▼───────────────────────┐ │ Summoner (apps/summoner) │ ← 獨立 process，本地端執行 │ - Agent: 接收 server RPC 指令 │ │ - ChildProcessProvider (spawn CLI) │ │ - LocalFilesystemService / LocalGitService │ │ - createConnectionLoop 自動重連 │ └──────────────────┬───────────────────────┘ │ child_process ┌──────────────────▼───────────────────────┐ │ Claude / Gemini CLI │ └──────────────────────────────────────────┘ ``` ### 部署模式 Server 可部署在雲端或遠端主機，Summoner 在**本地端**獨立執行： ```bash # 1. 啟動 server（遠端） pnpm --filter server start # 2. 本地跑 summoner，連回 server pnpm --filter @code-quest/summoner start --server <url> --token <token> # 3. 瀏覽器開 client ``` Summoner 負責所有本地操作（檔案讀寫、git、spawn CLI），server 只做路由和狀態管理。 ### Packages | Package | 職責 | |---|---| | `apps/web` | React 19 UI，WebSocket 連線，Storybook，Tailwind v4 | | `apps/server` | Express + WsTransport，DI container，session 持久化 | | `apps/summoner` | 獨立 agent process — ws client 連回 server，本地執行 CLI / fs / git | | `packages/schemas` | 跨 package 的型別、zod schema、service interface | | `packages/transport` | 同構 WebSocket 傳輸（WsTransport, Envelope, Pipeline, resumable socket） | | `packages/broadcaster` | DataSource / CachedDataSource / Broadcaster — push snapshot 給 summoner agent | | `packages/watch` | WatchService 介面，LocalWatchService（chokidar），RemoteWatchService（RPC） | | `packages/filesystem` | LocalFilesystemService / RemoteFilesystemService | | `packages/git` | LocalGitService / RemoteGitService | | `packages/openspec` | LocalOpenspecService / OpenspecService 介面 | | `packages/diff-file` | LocalDiffFileService / DiffFileService 介面 | | `packages/utils` | 共用工具（mime type、log config、name validator） | | `packages/db-schema` | Drizzle ORM table 定義（SQLite + MySQL） | | `packages/test-kit` | 共用 test fake 和 segment builder | ### 關鍵設計原則（當前） - **Protocol alignment**：跟 Claude Code VS Code extension 的 stream JSON / control request / permission 流程對齊；以實際 CLI output 為真相來源（`docs/protocol/`） - **Multi-provider**：Claude / Gemini 透過 summoner adapter 抽象 - **Transport 解耦**：WsTransport + Envelope protocol + middleware pipeline（auth / heartbeat / resumable），handler 透過 TypedSocket 抽象不依賴具體傳輸層 - **分離式部署**：server 在雲端，summoner 在本地端，透過 WebSocket RPC 通訊 - **Session lifecycle**：spawn → channel → resume；session 可跨 window 共享、可從 DB 還原 --- ## 長期願景：Code Quest（Roadmap，**尚未實作**） 把 Claude Code 使用體驗包裝成 RPG — CodeLand 世界、11 核心系統、HP/MP/EXP/Gold、戰鬥觸發規則、pixel art 視覺 — 完整設計詳見 `rpg-roadmap` skill，相關子系統詳見 `battle-management` / `map-system`。 **為何先做 client**：RPG 層需要穩定的「跟 Claude CLI 對話」底層。先把 client ↔ server ↔ CLI 的 protocol 做紮實，RPG 才有上層可以蓋。`docs/ui-design/` 與 roadmap skill 都是設計草稿，**不是驗證過的 spec**。 --- ## 使用建議 - 問「專案現在長什麼樣、目前架構」→ 本 skill 的「當前架構」段 - 問「session / protocol / handler / UI 怎麼寫」→ 對應的 domain skill（`socket-io`、`parser-development`、`fake-summoner-*`、`tailwind-v4`…） - 問「RPG / 戰鬥 / 地圖」→ 對應 roadmap skill，但先跟使用者確認是要設計 roadmap 還是落地實作 遇到現況跟 `docs/ui-design/` 或 roadmap skill 衝突時：**現況優先**，roadmap 當參考。