Praetor 系統規格 v0.1

狀態：設計稿

這份文件定義 Praetor 的核心系統模型、資料結構、治理規則、記憶架構、執行節奏、安全邊界與穩定性策略。

1. 設計目標

Praetor 的系統層要同時滿足 6 件事：

1. 使用者只需要面對一個 executive interface

2. 系統可以在內部做分層、拆任務、分配 skill

3. 記憶和成果必須可追溯、可審核、可重現

4. AI 可以主動前進，但不能越權

5. context 不可無限膨脹

6. 執行必須能暫停、恢復、歸檔

2. 核心系統原則

2.1 Agent-managed / Role-grounded

對使用者暴露的公司成員是 Agent。Role 是 Agent 的職務、責任與權限框架。

使用者定義：

系統決定：

2.2 Company-memory-first

記憶歸公司，不歸 agent。

MVP 只保留：

MVP 不做：

2.3 Governance-first

任何 AI 行為都應落在可治理範圍內。

治理必須顯式決定：

2.4 Visible accountability, hidden internals

使用者主要透過 Praetor CEO 指揮公司，但可以看見 Agent 的責任鏈。

內部實際可以是：

UI 應暴露責任、狀態、上下級、任務、權限、產出與 blocker；不暴露 personality 面板、prompt internals 或 executor prompt 控制。

3. 核心實體

3.1 Company DNA

Company DNA 是整個公司運作的頂層配置。

company_dna:
  language: zh-TW
  leadership_style: strategic
  decision_style: balanced
  organization_style: lean
  autonomy_mode: hybrid
  risk_priority: avoid_wrong_decisions
  communication_style: concise
  operating_principles:
    - default_to_action_escalate_when_uncertain
    - keep_roles_minimal_but_clear
    - avoid_unnecessary_user_interruption
    - document_important_decisions

作用：

3.2 Agent

agent:
  id: agent_filesystem_steward
  name: File System Steward
  role_id: role_workspace_stewardship
  reports_to: agent_ceo
  status: active
  current_work:
    - workspace_hygiene
    - file_placement_policy
  permission_profile: standard_operator

作用：

3.3 Role

Role 是 Agent 的職務描述與權限框架。

role:
  id: role_project_execution
  name: Project Execution
  responsibility:
    - create_project_structure
    - maintain_project_status
    - organize_related_documents
  outputs:
    - project_folder
    - project_plan
    - status_update
  constraints:
    - no_strategy_change
    - no_budget_commitment

注意：

3.4 Mission

Mission 是 Praetor 的主要工作單位。

mission:
  id: mission_build_invoice_tool
  title: Build Invoice Tool
  requested_by: owner
  owner_layer: ceo
  manager_layer: pm_auto
  status: running
  priority: high
  domains:
    - development
    - finance
  run_budget:
    max_steps: 20
    max_tokens: 100000
    max_time_minutes: 30
    max_cost_eur: 2.00

Mission 應有清楚 lifecycle，並對應實體資料夾。

3.5 Task

Task 是 mission 內部的可執行單元。

task:
  id: task_generate_project_structure
  mission_id: mission_build_invoice_tool
  title: Generate project structure
  role_owner: role_project_execution
  current_executor: codex_cli
  status: review
  checkpoint_policy:
    - before_completion
  outputs:
    - /workspace/Projects/InvoiceTool/PROJECT.md

3.6 Decision

decision:
  id: decision_budget_strategy_001
  mission_id: mission_build_invoice_tool
  summary: choose_mvp_scope
  requested_by: ceo
  impact: strategic
  status: waiting_owner
  options:
    - lean_scope
    - expanded_scope

3.7 Approval Request

Approval 是 UI 與治理之間的重要交界。

approval_request:
  id: approval_overwrite_file_002
  category: overwrite_important_file
  mission_id: mission_build_invoice_tool
  raised_by: pm
  reason: update_existing_status_document
  status: pending
  actions:
    - approve_once
    - approve_for_mission
    - reject

3.8 Meeting

Meeting 是結構化討論單位，不是自由聊天室。

meeting:
  id: meeting_project_review_001
  mission_id: mission_build_invoice_tool
  type: project_review
  moderator: ceo
  participants:
    - pm
    - worker
    - reviewer
  agenda:
    - current_status
    - risks
    - next_steps
  outputs:
    - summary
    - risks
    - decisions_needed
    - follow_ups

3.9 Board Briefing

BoardBriefing 是專案規劃與正式執行之間的 owner-facing artifact。

董事長可以先和 CEO 討論想法；CEO 需要時建立 mission，組成 PM-led planning team，讓 Product Manager、Marketing Lead、Design Lead、Developer、Reviewer、Legal Counsel、Security Officer 等角色各自提出結構化意見。這些 AI-to-AI 訊息不直接等於公司記憶，最後要整理成 BoardBriefing：

board_briefing:
  id: briefing_product_plan_001
  mission_id: mission_new_product
  status: ready_for_chairman
  participants:
    - Project Manager
    - Product Manager
    - Marketing Lead
    - Developer
    - Reviewer
  executive_summary: owner_visible_summary
  recommendations:
    - recommended_next_step
  assumptions:
    - unverified_market_or_product_assumption
  risks:
    - security_privacy_legal_or_execution_risk
  decisions_needed:
    - approve_direction_or_request_revision

這個設計讓 Praetor 像公司一樣運作：

3.10 New Project Discovery

當董事長對 CEO 說「我要開始開發一個新的專案」並開始討論想法、目的、規格時，Praetor 的預設反應不是立刻寫程式，而是進入 new_project_discovery 流程。

流程：

1. CEO 先和董事長做 discovery conversation，只問少量高影響問題：目的、使用者、成功標準、限制、non-goals、偏好的技術或交付形式。

2. 想法還在形成時，CEO 可以在對話中整理 draft brief；此階段不需要 mission，也不應產生 execution。

3. 當內容需要保存、分工、會議或產生檔案時，CEO 建立 MissionType = new_product 且 mode = planning_only 的 mission。

4. CEO 建立 mission-scoped Agent team。基本 team 包含 CEO、Project Manager、Product Manager、Technical Architect 或 Developer、Reviewer、File System Steward；依風險增加 Legal Counsel、Security Officer、Design Lead、Marketing Lead 或 Sales Manager。

5. File System Steward 在 workspace root 內建立可見檔案，例如：

- Projects/<slug>/PROJECT_BRIEF.md

- Projects/<slug>/PRODUCT_SPEC.md

- Projects/<slug>/TECH_SPEC.md

- Projects/<slug>/DECISIONS.md

- Projects/<slug>/OPEN_QUESTIONS.md

- Missions/<mission_id>/BOARD_BRIEFING.md

6. 如需 Agent 之間討論，CEO 或 PM 召開 Level 3 meeting：agenda、proposal、discussion、dissent、decision、action items 必須被結構化保存。

7. CEO 對董事長交付 BoardBriefing，內容包含 MVP、non-goals、建議技術路線、風險、未決問題、需要董事長決定的事項、建議下一步。

8. 只有董事長明確說「開始做」、「建立」、「scaffold」、「implement」或同等授權時，CEO 才能把 planning mission 轉成 execution mission，或建立下一個 implementation mission。

記憶邊界：brainstorm、raw meeting、未定案規格不直接進 Company Memory。低風險偏好、mission-local notes、open questions、draft playbook 可以由 CEO 自動保存，但必須保留 evidence 與 rollback。

4. 狀態機

4.1 Mission 狀態

planned
→ active
→ review
→ waiting_approval
→ resumed
→ completed
→ archived

可中途進入：

4.2 Task 狀態

planned
→ assigned
→ running
→ review
→ waiting_approval
→ done

可中途進入：

4.3 Approval 狀態

pending
→ approved_once
→ approved_for_scope
→ rejected
→ expired

5. 組織與分層規則

5.1 Praetor / CEO 層責任

Praetor 必須負責：

Praetor 不應該負責：

5.2 PM 層責任

PM 是 mission-scoped context owner。

PM 應負責：

PM 不應負責：

5.3 Worker 層責任

Worker 應負責：

Worker 不應負責：

5.4 Reviewer 層責任

Reviewer 應負責：

Reviewer 不應負責：

6. CEO Load Management

Praetor 需要內建 overload 檢測，而不是憑感覺。

6.1 指標

建議至少納入：

6.2 基本規則

ceo_load_policy:
  context_warning_at_tokens: 70000
  context_split_at_tokens: 90000
  max_steps_without_pm: 5
  max_domains_without_pm: 1
  max_active_missions_per_ceo: 3
  create_pm_after_blocked_count: 2

6.3 建議演算法

簡化版：

def should_create_pm(mission):
    return (
        mission.context_tokens > 90000
        or mission.estimated_steps > 5
        or mission.domain_count > 1
        or mission.blocked_count >= 2
    )

進階版：

load_score = (
    context_ratio * 0.4
    + active_task_ratio * 0.2
    + domain_ratio * 0.2
    + blocked_ratio * 0.2
)

if load_score > 0.7:
    create_pm()

6.4 PM 建立原則

建立 PM 的理由應該是：

不是：

7. 記憶架構

7.1 Company Memory

長期、共享、可版本化：

7.2 Mission Memory

短中期、可歸檔：

7.3 Runtime Ephemeral Context

這一層不應長期保存成 agent 人格，而應只存在於當前運行批次：

7.4 Retrieval 規則

Praetor 和 PM 不應該每次都讀完整 workspace。

建議 retrieval pipeline：

1. 先讀 Company DNA

2. 再讀 mission summary

3. 再根據 task 類型選 relevant wiki/pages/files

4. 顯示 retrieval preview 供使用者查看

7.5 Memory Promotion

原始對話不是公司記憶。CEO 對話、AI 對 AI 的工作訊息、tool output、外部文件回覆都可以作為 audit evidence 保存，但不能直接寫入 Wiki/ 或 client knowledge。

任務 closeout 時應建立 MemoryPromotionReview：

只有經過審查的 KnowledgeUpdate 才能進入 durable company memory。

這樣做的好處：

8. 執行節奏與 Run Budget

8.1 Run Budget

每個 mission 都應有 budget：

run_budget:
  max_steps: 20
  max_tokens: 100000
  max_time_minutes: 30
  max_cost_eur: 2.00

8.2 Pause 條件

必須支援三大暫停點：

1. token / cost budget reached

2. decision checkpoint

3. risk checkpoint

加上任務完成時的正常停止。

8.3 Autonomy Policy

建議：

autonomy_policy:
  low_risk_tasks: auto_continue
  medium_risk_tasks: report_after_batch
  high_risk_tasks: require_approval

8.4 節奏哲學

Praetor 不追求「永遠不停」。

它追求的是：

在安全範圍內主動前進，然後在正確時刻停下來請人決策。

9. Executor Abstraction

Praetor 必須把執行器抽象乾淨。

9.0 Model routing 與 native subagents

Praetor 的任務分派不應直接綁定 provider-specific model name。內部先用統一的 model profile：

model_profile:
  - fast
  - standard
  - reasoning
  - critical

各 provider / executor 再把 profile 映射到實際 model 或 native setting。當任務複雜度不明確時，Praetor 應保守使用 reasoning；涉及安全、隱私、法律、財務、credentials、runtime、破壞性動作或高影響 final review 時，應使用 critical。

Praetor v1 不自建 sub-agent orchestration。對開發與研究任務，若 Codex / Claude Code 等 executor 有原生 subagent / dynamic workflow 能力，Praetor 可以透過 policy 允許 executor 自行使用。Praetor 只管理 mission scope、agent assignment、model profile、executor、permissions、budget、audit 與 final review；executor 內部 subagent lifecycle 與結果串聯由 executor 負責。

最小 policy：

runtime_policy:
  model_profile: fast | standard | reasoning | critical
  native_subagents: disallowed | allowed

完整決策見 ADR-003-model-routing-and-native-subagents.md。

9.1 Executor 類型

executor:
  type: codex_cli | claude_code | openai_api | ollama
  transport: builtin | host_bridge
  model_profile: fast | standard | reasoning | critical
  native_subagents: disallowed | allowed
  workspace_scope: /app/workspace
  approval_mode: delegated
  supports_file_write: true
  supports_shell: conditional
  supports_streaming: optional

9.2 必要 contract

每個 executor adapter 至少要實作：

9.3 Non-interactive batch contract

Praetor 的 executor contract 不能只是「能跑起來」。

它還必須保證：

因此每個 executor adapter 還應定義：

標準化結果至少要分成：

Praetor 的原則是：

9.4 特別注意 Subscription Executor Mode

這個模式要明確區分：

Praetor 不應嘗試「直接使用 ChatGPT 訂閱當 API」。

Praetor 應支援的是：

另外要明確限制：

10. 權限與安全模型

10.1 Workspace 邊界

所有執行都應落在受控 workspace 內。

permissions:
  allow_read:
    - /app/workspace
  allow_write:
    - /app/workspace/Projects
    - /app/workspace/Wiki
    - /app/workspace/Decisions
    - /app/workspace/Missions
  deny_write:
    - /app/workspace/Archive
    - /app/workspace/Finance/Locked

10.2 危險動作分類

高風險：

永不允許：

10.3 權限提升

重要規則：

Praetor 可以自動建立 PM，但不能自動提升風險權限。

也就是說：

11. 穩定性策略

11.1 Idempotency

重跑 mission 時，應盡量保證：

11.2 Canonical State

Praetor 必須明確定義 mission state 的真相來源。

建議：

這代表：

11.3 Resumability

Mission 暫停後，應能靠 mission folder 恢復。

至少要保留：

SQLite 可協助快速查詢，但不應成為唯一真相來源。

11.4 Auditability

任何重要動作都要可回溯：

11.5 Failure Isolation

單一 mission / executor 失敗不應拖垮整個系統。

應至少保證：

11.6 Backups

最少應有：

12. Mission 檔案建議

workspace/Missions/<mission_id>/
├── MISSION.md
├── STATUS.md
├── TASKS.md
├── DECISIONS.md
├── CONTEXT.md
├── REPORT.md
└── logs/

用途：

- 任務目標、邊界、run budget、requested outputs

- 當前狀態、完成比例、下一步

- task breakdown

- mission 級決策與批准紀錄

- 任務所需局部上下文

- 給 Praetor / owner 的摘要

- executor logs、runtime traces、review logs

13. 推薦預設政策

organization_policy:
  hidden_pm_enabled: true
  ask_owner_first_time_for_pm_creation: true
  auto_create_pm_after_trust: true
  pm_scope: mission
  pm_lifetime: until_completed

memory_policy:
  agent_personal_memory: disabled
  company_memory: enabled
  mission_memory: enabled

runtime_policy:
  default_speed_mode: balanced
  default_autonomy_mode: hybrid
  default_checkpoint_policy:
    - before_external_action
    - before_destructive_write
    - before_completion_if_high_impact

14. 主要取捨與判斷

14.1 不做 agent personal memory

優點：

缺點：

判斷：

14.2 PM hidden by default

優點：

缺點：

判斷：

14.3 Filesystem as truth + SQLite as operational state

優點：

缺點：

判斷：

14.4 多 runtime 模式

優點：

缺點：

判斷：

15. MVP 必須實作到的系統能力

MVP 至少要完成：

16. 最後的系統結論

Praetor 的系統核心不是「讓很多 agent 自由互動」。

而是：

用角色、治理、記憶、mission 邊界與執行器抽象，把 AI 變成一間可控、可追溯、可持續運作的公司。