Praetor Repo / Runtime / 部署架構 v0.2

狀態：2026-05 更新，加上 as-built 對照。

這份文件有兩層：

衝突時：用 §3 描述當前狀態，§4 是未來方向。

1. 設計目標

Praetor 的工程架構要同時滿足：

1. 使用者一鍵部署容易

2. 前端體驗完整

3. 後端執行穩定

4. executor integration 可擴展

5. 安全邊界清楚

6. 後續不會因為 MVP 選錯架構而重寫

2. 技術選型建議

2.1 推薦主架構

前端：

後端：

背景工作：

持久層：

原因：

2.2 替代方案與取捨

全 Python + server-rendered UI

優點：

缺點：

判斷：

全 Node / TypeScript

優點：

缺點：

判斷：

微服務一開始拆很細

優點：

缺點：

判斷：

3. As-built repo 形態（2026-05）

實際 repo 與 v0.1 設計稿有偏差。以下為現況：

praetor/
├── apps/
│   ├── api/                    # FastAPI (praetor_api package)
│   ├── web/                    # Vite + React SPA proxy (praetor_web + frontend/)
│   └── worker/                 # FastAPI healthcheck (praetor_worker; runtime work
│                                 actually happens via mission_worker.py in praetor_api)
├── workers/
│   └── runtime/                # bridge_client lib (praetor_runtime)
├── bridges/
│   └── praetor-execd/          # host-side subscription executor bridge (FastAPI)
├── tools/                      # smoke + import-check scripts (pixi tasks point here)
├── docs/                       # specs (zh-TW + en mix)
├── branding/                   # logo assets
├── scripts/                    # install / update / uninstall
├── .github/                    # workflows
├── compose.yaml
├── compose.production.yaml
├── compose.app.yaml
├── compose.app.production.yaml
├── pixi.toml                   # repo-local Python env baseline
├── PRAETOR_PRODUCT_BRIEF.md
├── PRAETOR_PRODUCT_BRIEF.zh-TW.md
├── PRODUCT_INTAKE.md           # raw discussion material
├── ROADMAP.md
└── README.md

差異重點：

| v0.1 設計稿 | 實際 | 備註 |

|---|---|---|

| apps/web/ = Next.js | Vite + React 19 | React Router v6 + TanStack Query (規劃中) |

| packages/{docschemas,prompts,ui} | 不存在 | schemas 在 apps/api/praetor_api/schemas.py；prompts 內嵌在 service.py / planner.py；UI primitives 待 Codex 重建時建立 |

| infra/ | 不存在 | docker compose 檔案直接放 repo root；scripts/ 是 shell installer，不是 docker config |

| workspace.example/ | 不存在 | workspace bootstrap 由 apps/api/praetor_api/workspace.py 動態建立 |

| tests/ | 名為 tools/ | smoke tests + import checks，命名沿用 |

API 內部仍是單一 Python package（praetor_api）的扁平 layout：

apps/api/praetor_api/
├── __init__.py
├── main.py                 # FastAPI app, lifespan, top-level routes
├── ui.py                   # Jinja UI routes + templates wrapper (約 1,500 行；UI 重建後會壓到 < 600 行)
├── _translations.py        # Jinja-side i18n tables (zh-TW + en)
├── service.py              # PraetorService god object (約 2,700 行；未來切分)
├── service_agents.py       # AgentsMixin
├── service_skills.py       # SkillsMixin
├── storage.py              # SQLiteIndex + AppStorage facade
├── _filesystem_store.py    # FilesystemStore + helpers (workspace markdown 寫入)
├── models.py               # Pydantic models
├── schemas.py              # JSON schema export
├── planner.py              # CEO planner (LLM + offline test variant)
├── runtime.py              # MissionRuntime (subscription_executor / api 兩條路)
├── mission_worker.py       # background MissionWorker (mission_jobs queue 消費者)
├── providers.py            # OpenAI / Anthropic SDK 包裝
├── safety_policy.py        # prompt-time safety policy 組裝
├── recommendations.py      # onboarding preview + mission complexity assessment
├── run_registry.py         # in-memory async run register
├── config.py               # env vars
├── auth.py                 # owner password / bcrypt
├── security.py             # CSRF + rate limit + setup token
├── telegram.py             # Telegram bot integration
├── workspace.py            # bootstrap_workspace
├── templates/              # Jinja templates (UI 重建後會清掉大部分)
└── static/                 # praetor.css + 圖片 (UI 重建後會大量縮減)

下一輪 refactor（已知 backlog，不在 v1 阻擋路徑上）：

1. 把 service.py 拆成 service_mission.py / service_governance.py / service_conversation.py / service_knowledge.py 等 mixin（同 §4 規劃，但搬進 mixin 而非獨立 package）。

2. 把 storage.py 拆成 storage/{missions,governance,knowledge,organization}.py repos。

3. 視 UI 重建後的維護摩擦決定要不要拉 packages/ui 共用層（v1 不做）。

4. 邏輯模組切分（未來方向，非 as-built）

後端內部建議切成：

apps/api/app/
├── api/
├── auth/
├── governance/
├── roles/
├── runtime/
├── missions/
├── memory/
├── executors/
├── models/
├── usage/
├── storage/
└── settings/

作用如下：

- HTTP / WebSocket interfaces

- local-only / remote mode

- owner login

- approval policy

- checkpoint policy

- never-allow policy

- role schema

- role evolution

- role-to-agent mapping

- core orchestration loop

- run budgets

- pause / resume

- mission lifecycle

- task state machine

- wiki

- retrieval

- mission context

- Codex / Claude / OpenClaw / API adapters

- provider abstraction

- fallback logic

- token stats

- cost stats

- per-model usage

- filesystem

- SQLite

- audit logs

- user-configurable policies

5. Runtime 形態

Praetor 不是單純 request-response app。

它有三種主要 runtime 路徑：

1. synchronous UI/API requests

2. background mission execution

3. streaming or polling updates to UI

5.1 API Process

API process 負責：

5.2 Worker Process

Worker process 負責：

5.3 為什麼要獨立 worker

優點：

缺點：

判斷：

6. 部署架構建議

6.1 使用者體驗目標

使用者應該只需要：

docker compose up -d

然後打開：

http://localhost:3000

但這裡要明確區分兩條安裝路線：

- 對應 api 或 local_model

- 純 Docker 路線

- 對應 subscription_executor

- Docker + host executor bridge

- 不應假裝成純 Docker 即可完成

6.2 MVP Compose 建議

雖然使用者只要一個命令，但 compose 可以是多服務。

建議：

services:
  web:
    - Next.js app
  api:
    - FastAPI app
  worker:
    - background runtime worker

可選：

不需要：

除非後續 scale 真的需要。

6.3 為什麼不是單一超大 container

單一 container 的優點是簡單，但缺點是：

因此建議：

7. Persistent Volumes

建議至少掛載：

./workspace:/app/workspace
./config:/app/config
./data:/app/data

其中：

- 公司資料、Wiki、missions、projects

- settings、governance、runtime configs

- SQLite

- usage db

- audit logs

- caches

8. 資料儲存策略

8.1 Filesystem

存：

8.2 SQLite

存：

重要限制：

8.3 JSONL / Structured Logs

存：

9. API 介面建議

不需要一開始就設計巨大 API surface，但至少應有：

9.1 Auth

9.2 Onboarding

9.3 Praetor

9.4 Missions / Tasks

9.5 Memory

9.6 Usage / Models

9.7 Settings

10. 背景工作模型

10.1 Mission Runner

每個 mission 的執行週期應大致是：

1. read relevant context

2. create or update task plan

3. choose role / executor

4. execute one batch

5. review outputs

6. checkpoint or continue

7. persist state

10.2 為什麼要 batch

因為如果 executor 每一步都回來問：

Batch 可以讓 Praetor：

10.3 Resume 機制

Resume 不應該只靠 runtime memory。

應以 mission folder 為主恢復。

SQLite 可協助：

但不應成為唯一真相來源。

11. Executor Driver 設計

每個 executor 應該是一個獨立 adapter。

推薦結構：

executors/
├── base.py
├── bridge_client.py
├── openai_api.py
├── ollama.py
├── codex_cli.py
├── claude_code.py
└── openclaw.py

共同接口建議：

class ExecutorAdapter:
    def healthcheck(self): ...
    def prepare(self, task_spec): ...
    def run(self, prepared_task): ...
    def collect_outputs(self, run_ref): ...
    def collect_usage(self, run_ref): ...
    def normalize_error(self, err): ...

補充要求：

建議再加：

class BatchExecutionResult:
    status: str  # completed | paused_budget | auth_required | failed_transient ...
    requires_owner_action: bool
    pause_reason: str | None

subscription_executor 類 adapter 應優先走：

Model routing 不應由各頁面硬編 provider model name。Praetor 內部應先使用 fast / standard / reasoning / critical profiles，再由 provider 或 executor mapping 轉成實際模型。若任務複雜度不確定，預設升級到 reasoning；高風險治理、security、privacy、legal、finance、credentials、runtime 或 final review 使用 critical。

Praetor v1 不實作自己的 subagent orchestration。開發與研究任務可允許 Codex / Claude Code 使用 executor-native subagents 或 dynamic workflows，但 bridge / adapter 必須回傳單一 normalized result 與 evidence 摘要。Praetor 管 policy、permissions、budget、audit 與 review，不管理 executor 內部 subagent lifecycle。

12. 安全工程

12.1 Browser 與 secrets 分離

API keys、executor credentials 不應該直接暴露到前端。

前端只應看到：

12.2 Workspace Scope Enforcement

不能只靠 prompt 寫「請不要超出資料夾」。

應有真正 enforcement：

12.3 Subscription Executor 特殊風險

Codex CLI / Claude Code / OpenClaw 類執行器可能有自己的權限模型。

Praetor 必須：

不能假設 external executor 自己就會完全守規矩。

12.4 Remote Self-host 安全

若啟用遠端模式，至少需要：

第一版不需要多使用者，但不能完全不做安全。

13. 穩定性工程

13.1 Health Checks

至少要檢查：

13.2 Retries

可重試類型：

不可盲目重試：

13.3 Failure Classification

錯誤至少分：

這樣 UI 才能顯示正確指引。

13.4 Audit Trail

每次重要執行應記錄：

13.5 Backups

至少要有：

14. 測試策略

Praetor 不能只測 UI，也不能只測 prompt。

至少要分 5 層：

14.1 Schema Tests

測：

14.2 Policy Tests

測：

14.3 Adapter Tests

測：

14.4 Workflow Tests

測：

14.5 UI Tests

測：

15. 開發體驗

15.1 本機開發

應支援：

15.2 為什麼 fake executor 很重要

因為真實模型與 executor：

fake executor 可用於：

16. 建議 repo 細節

推薦補這些檔案：

.env.example
compose.yaml
compose.production.yaml
workspace.example/
config.example/
README.md
Makefile

workspace.example/ 應內含：

這會大幅提升第一印象。

17. 完成度標準

Praetor 什麼時候算不是 demo，而是可用產品原型？

至少要同時做到：

18. MVP 實作順序

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

19. 最後的架構結論

Praetor 最好的技術結構不是最炫的，也不是最微服務的。

而是：

對使用者維持一個非常簡單的部署與使用入口，對內部維持清楚的模組邊界、背景執行層、權限邊界與可恢復狀態。

簡單說：