Praetor 開源成功與產品化執行規格

Status: working spec

Date: 2026-04-25

這份文件整理目前 codebase 的實際狀態，並把它對照到 Praetor 作為開源專案、未來服務化與商業化的成功路線。它的用途不是重新定義 Praetor，而是讓後續產品、工程、文件、行銷可以跟著同一份現況與優先順序前進。

1. 核心判斷

Praetor 目前已經不是單純概念文件。codebase 裡已經存在一條可跑的產品縱切：

1. 使用者完成 onboarding。

2. 系統建立 owner auth、settings、workspace、company DNA、governance、roles。

3. 使用者建立 mission。

4. mission 以檔案系統作為 canonical state。

5. runtime 透過 API provider 或 host-side subscription executor bridge 執行。

6. 執行結果寫回 task log、bridge run、REPORT、DECISIONS、audit log、approvals。

7. Web UI 顯示 Praetor、Overview、Tasks、Activity、Memory、Decisions、Models、Meetings、Settings、mission detail、mobile briefing。

但目前離「能打動開源使用者」還有一段距離。主要問題不是缺更多頁面，而是：

對外定位應該保持：

> Praetor is a local-first AI company operating system for solo builders.

中文定位：

> Praetor 是給獨立開發者、創業者、研究者使用的本地優先 AI 公司作業系統。使用者只需要和 AI CEO 溝通，Praetor 負責角色、任務、記憶、執行、檢查點與回報。

2. 目前 codebase 設置

2.1 Repo 主要模組

目前實作分成幾個清楚邊界：

- 主要 FastAPI app

- Web UI templates

- auth / CSRF / setup token

- onboarding、mission、runtime、memory、approval、meeting、usage

- 目前 mission runtime 實際在這裡 inline 執行

- thin proxy web service

- 在 split stack 中代理到 API service

- worker service skeleton

- 目前提供 health/status

- 還沒有真正接管 mission queue / background execution

- host-side executor bridge

- 用 bearer token 保護

- 負責把 Docker 內 Praetor 的 run request 映射到宿主機 workspace

- 支援 codex 與 claude_code runner

- worker-side bridge client

- 負責呼叫 praetor-execd 的 health、executors、runs、events、cancel

- 產品、系統、UI、surface、repo architecture、deployment security、bridge spec

- smoke tests / import checks / fake OpenAI server

2.2 部署形態

目前有兩種主要 Docker 形態：

- 單一 app service

- 綁定 workspace 與 data

- 對使用者最容易解釋

- web / api / worker split stack

- 可連 host-side praetor-execd

- 包含 optional ollama profile

- worker 目前還不是正式 queue worker

目前推薦開源 demo 應先以 compose.app.yaml 或 Pixi local flow 為主，避免 split stack 增加初次使用成本。

2.3 設定與環境變數

核心設定來源在 apps/api/praetor_api/config.py：

- PRAETOR_STATE_DIR

- PRAETOR_BRIDGE_BASE_URL

- PRAETOR_BRIDGE_TOKEN

- OPENAI_API_KEY

- ANTHROPIC_API_KEY

- PRAETOR_OPENAI_BASE_URL

- PRAETOR_ANTHROPIC_BASE_URL

- PRAETOR_SESSION_SECRET

- PRAETOR_SETUP_TOKEN

- PRAETOR_REQUIRE_LOGIN

- PRAETOR_SECURE_COOKIE

- PRAETOR_ENV

- PRAETOR_DEBUG_ROUTES

- rate limit envs

目前 production security guard 會拒絕弱 session secret、弱 bridge token、缺失或弱 setup token。這是對開源信任很重要的基礎。

3. 目前記憶管理設計

3.1 記憶原則

目前 codebase 實作方向符合既有產品原則：

這個方向適合開源 positioning，因為它能支撐：

3.2 Workspace bootstrap

bootstrap_workspace() 目前會建立：

並建立預設 wiki：

注意：Agents 與 Agent Handbook 是目前正確的使用者語意。依照

docs/ADR-002-praetor-as-ai-company.md，使用者管理的是 AI Agent 員工；

Role 是每個 Agent 的職責、權限、匯報與能力框架，而不是取代 Agent 的

主要操作物件。後續 UI 與文件應避免回到舊版「使用者只管理 role、不管理

agent」的表述。

3.3 App state

AppStorage 同時寫：

- settings.json

- auth.json

- audit.jsonl

- approvals.json

- index.sqlite3

- settings

- missions

重要現況：

3.4 Mission memory

每個 mission 會建立：

目前問題：

3.5 Memory UI

目前 UI 已有：

- 顯示 wiki pages

- 顯示 recent runs

- 從 mission DECISIONS.md 抽取 - 開頭項目

- 顯示 audit events

- 顯示 report、status、PM report、tasks file、run records、changed files、usage

這已經能展示「公司記憶屬於 workspace」的概念。下一步應把它從「檔案列表」升級成「可被 Praetor 主動維護的公司記憶」。

4. 目前使用者流程

4.1 First-time setup

入口：

若尚未初始化，/app/praetor 顯示六步 onboarding wizard：

1. owner name / email / password / company language

2. leadership style / decision style / organization style / autonomy / risk priority

3. workspace root

4. runtime mode / provider / model / executor

5. require approval categories

6. summary and initialize

完成後：

4.2 Login / protected UI

目前有：

API 與 UI 的 protected behavior：

4.3 Mission creation

使用者在 /app/praetor 或 API 建立 mission：

欄位：

系統會計算：

若 PM required，會附加 PM report：

目前 mission creation 偏表單式，還沒有真正「AI CEO 與使用者對話後生成 mission plan」。

4.4 Mission run

使用者在 mission detail 按 Run mission。

目前執行流程：

1. mission status -> active

2. 建立 MissionRuntime

3. 根據 settings runtime 選擇：

- api

- subscription_executor

4. 執行後寫 task log 與 bridge run

5. 若 API failure 且有 executor，或 executor failure 且有 provider，嘗試 fallback

6. 根據 normalized status 更新 mission status

7. append REPORT.md

8. 若 PM required，append PM_REPORT.md

9. append audit event

10. 若需要 owner action，建立 approval request

目前 status mapping：

4.5 API mode

API mode 目前支援：

API prompt 要求模型回傳 JSON：

系統會：

目前限制：

4.6 Subscription executor mode

subscription executor mode 透過 host bridge：

安全邊界：

目前限制：

4.7 Approval flow

目前 approval 可以：

但目前 approval resolution 只是狀態更新，不會：

這是產品信任敘事的最大短板之一，因為「stop at checkpoint」已經有，但「批准後可治理地繼續」還沒有。

4.8 Meeting flow

目前可以建立 review meeting：

這是一個好的雛形，但目前更像 summary generator，不是真正 decision meeting 或 planning loop。

5. 對照開源成功定位的差距

5.1 已經符合定位的部分

目前已經有幾個很適合拿來行銷的真實基礎：

這些都支撐「不是一般 chatbot，而是 AI company operating system」。

5.2 目前不應過度宣稱的部分

對外行銷應避免過早宣稱：

目前比較準確的說法：

> Praetor is an early local-first AI company command center with mission-based execution, company memory files, governance settings, and support for API models or host-side coding executors.

5.3 開源 demo 最該展示的能力

最強 demo 應該是：

> Ask Praetor to prepare this repo for an open-source v0.1 release.

展示順序：

1. 初始化公司 workspace。

2. 設定 approval boundaries。

3. 建立 mission：prepare v0.1 open-source release。

4. Praetor 讀 wiki/context。

5. 產出 release checklist / docs / project status。

6. 透過 Codex 或 API mode 寫入 workspace。

7. 顯示 changed files。

8. 顯示 report、decisions、audit、usage。

9. 遇到高風險行為時建立 approval checkpoint。

這個 demo 比「多 agent 自動工作」更可信，因為它正好展現 Praetor 現在已經有的優勢。

6. 後續產品規格

6.1 P0: 開源可信 MVP

目標：

讓一個陌生開發者 clone repo 後，在 30 分鐘內完成第一個有價值 mission，並理解 Praetor 的差異。

必須完成：

驗收：

6.2 P1: Memory 產品化

目標：

讓 company memory 成為 Praetor 的核心賣點，而不是只是 wiki file list。

需求：

驗收：

6.3 P2: Approval resume semantics

目標：

讓「停在正確檢查點」變成真的 workflow。

需求：

驗收：

6.4 P3: True CEO planning layer

目標：

讓使用者不是填 mission form，而是和 Praetor 定義目標，由 Praetor 建立 mission plan。

需求：

- objective

- roles

- tasks

- context needed

- expected outputs

- checkpoints

- risk flags

驗收：

6.5 P4: Background worker

目標：

把 mission execution 從 API request 中移出，支援長任務與 UI progress。

需求：

驗收：

6.6 P5: Open-source packaging

目標：

讓 Praetor 能被開源社群理解、安裝、展示、貢獻。

需求：

- sample workspace

- sample mission

- expected output screenshots or markdown

- quickstart

- concept guide

- architecture for contributors

- executor bridge setup

- security model

- troubleshooting

- issue templates

- contribution guide

- roadmap labels

- good first issues

驗收：

7. 行銷與產品訊息規格

7.1 首頁與 README 應強調

核心訊息：

> Stop managing many AI agents. Run work through one AI CEO.

輔助訊息：

7.2 避免使用的訊息

避免：

原因：

這些字會把 Praetor 放進過度擁擠或目前實作還無法支撐的市場敘事。

7.3 推薦 demo mission

Demo mission:

Title:

> Prepare this repository for an open-source v0.1 release

Summary:

> Review the current repository, produce a release readiness report, update the project status, identify trust/security gaps, and recommend the next three contributor-friendly issues.

Requested outputs:

展示重點：

8. 建議執行順序

Milestone A: Sharpen the demo

1. 建立 examples/praetor-release-workspace

2. 建立 demo mission template

3. 加入 fake provider / internal offline planner test mode

4. 修改 README quickstart 指向 demo

5. 錄製 3 分鐘 demo script

Milestone B: Fix memory overwrite risk

1. save_mission 不再每次覆蓋 markdown memory files

2. 初次建立與更新 mission metadata 分離

3. TASKS.md 與 task JSON log 同步 append

4. decisions 建立 structured record

Milestone C: Approval becomes real

1. approval resolution 寫入 mission decision

2. approval status 影響 next run policy

3. mission waiting approval -> approved continuation

4. UI 顯示 approved scope

Milestone D: CEO planning

1. Founder brief input

2. Praetor plan preview

3. User approves plan

4. Plan materializes into mission/tasks/context

Milestone E: Background execution

1. worker queue

2. run event polling

3. cancel/resume

4. restore from filesystem state

9. 成功指標

開源採用指標

產品價值指標

商業化指標

10. Product truth table

| 能力 | 目前狀態 | 對外可說法 | 下一步 |

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

| Local-first workspace | 已實作 | 可強調 | 補 sample workspace |

| Company memory | 基礎已實作 | 可強調但避免過度 | memory update lifecycle |

| AI CEO | UI/文案/服務雛形 | 可作定位 | CEO planning layer |

| Agents / Roles | model/onboarding 已有 | 可說 agent-managed / role-grounded | org chart、responsible agent、role-to-task orchestration |

| Hidden PM | complexity flag / PM report | 可說 early PM layer | mission-scoped PM context |

| Approvals | 建立/顯示/解決 | 可說 checkpoint tracking | approve 後 resume semantics |

| API mode | OpenAI/Anthropic 已有 | 可說 BYO API key | better JSON recovery / streaming |

| Subscription executor | Codex/Claude bridge 已有 | 可強調 | richer context + policy bridge |

| Worker | health/status stub | 不應主打 | real background queue |

| Local model | compose 有 Ollama profile | 不應主打 | runtime implementation |

| SaaS readiness | 尚未 | 不應主打 | hosted beta architecture |

11. 決策

1. Praetor 的開源 wedge 是「一個 AI CEO 管理多角色工作」，不是「更多 agent」。

2. 第一個公開 demo 必須聚焦 software repo / release readiness，因為目前 codebase 最適合這個場景。

3. v1 不應追 enterprise、多使用者、marketplace、複雜 workflow builder。

4. 記憶與 approval 是信任核心，應優先於增加更多 integrations。

5. Worker queue 是產品可用性必要條件，但在 public demo 前可以先以同步 flow 展示。

6. README 與 website 應用真實能力說話，不要用超出目前實作的 autonomy 敘事。

12. 下一步 checklist