文件

開始使用

從安裝到第一個工作流程，只需 5 分鐘。

三種檔案格式，一個閉合迴路

OSOP 使用三種格式協同運作：

.osop

工作流程定義 — 描述該發生什麼

藍圖
.osoplog

執行記錄 — 記錄實際發生了什麼

實驗筆記
.sop

SOP 文件 — 將多個 .osop 組成一份可瀏覽的合集

資料夾
定義 → 執行 → 記錄 → 合成 → 定義（更好的版本）

閉合迴路。每次迭代都讓工作流程更好。

快速開始

1
安裝 CLI
pip install osop
2
建立你的第一個工作流程

將以下內容儲存為 my-workflow.osop.yaml:

my-workflow.osop.yaml
osop_version: "2.0"
id: "my-first-workflow"
name: "Hello OSOP"
description: "A simple two-step workflow."
tags: [tutorial]

nodes:
  - id: "greet"
    type: "agent"
    name: "Generate Greeting"
    purpose: "AI generates a personalized greeting."
    runtime:
      provider: anthropic
      model: claude-sonnet-4-20250514

  - id: "review"
    type: "human"
    name: "Human Review"
    purpose: "Human reviews the AI output."

edges:
  - from: "greet"
    to: "review"
    mode: "sequential"
3
驗證與視覺化
terminal
$ osop validate my-workflow.osop.yaml
✓ Valid OSOP workflow: "Hello OSOP"
  2 nodes, 1 edge, 0 warnings

$ osop run my-workflow.osop.yaml --dry-run
  → [agent] greet: dry_run
  → [human] review: dry_run
  COMPLETED — 0 executed, 0 skipped

$ osop run my-workflow.osop.yaml
  → [agent] greet: completed ($0.0023)
  → [human] review: skipped (interactive mode off)
  COMPLETED — 1 executed, 1 skipped — $0.0023

或將檔案拖入視覺化編輯器以查看互動式節點圖。

.osop 格式

.osop 檔案是一個 YAML 文件，將工作流程定義為有向無環圖（DAG）。它有三個主要部分：

Metadata

頂層欄位： osop_version, id, name, description, version, tags.

Nodes（16 種類型）

分類類型
參與者human, agent, company, department
技術api, cli, db, git, docker, cicd, infra, mcp
流程控制system, event, gateway, data

Edges（13 種模式）

Edges 連接節點並定義執行流程：

sequentialparallelconditionalloopfallbackspawnerrortimeoutcompensationmessagedataflowsignalweighted

.osoplog 格式

工作流程執行後，.osoplog 檔案記錄實際發生的事情。它是一個不可變的執行記錄，包含：

運行元數據
run_id、workflow_id、狀態（COMPLETED/FAILED）、總時長
觸發資訊
誰啟動的、何時、如何（手動、排程、webhook）
節點記錄
每個節點：狀態、時長、嘗試次數、輸入/輸出
工具使用
哪些工具被呼叫、呼叫了幾次、在哪些檔案上
AI 元數據
使用的模型、prompt tokens、completion tokens、成本
推理
問了什麼問題、選擇了什麼、信心等級
人類決策
誰審查的、決定了什麼、備註
子代理追蹤
父子關係、多代理工作流程的 spawn 索引

.sop 格式（SOP 文件）

.sop 檔案將多個 .osop 工作流程組成一份可瀏覽的合集。可以把它想成工作流程的資料夾或目錄。

結構

頂層：sop_version、id、name、sections。每個章節包含 name、description 和工作流程引用（ref 路徑指向 .osop 檔案）。

my-api-docs.sop
sop_version: "1.0"
id: "stripe-api-docs"
name: "Stripe API — Complete SOP Documentation"
author: "Engineering Team"

sections:
  - name: "Payment Flows"
    description: "Core payment processing workflows."
    workflows:
      - ref: "./stripe-payment-flow.osop.yaml"
        title: "Create Payment"
      - ref: "./stripe-refund-flow.osop.yaml"
        title: "Process Refund"

  - name: "Customer Management"
    workflows:
      - ref: "./stripe-create-customer.osop.yaml"
        title: "Create Customer"

渲染

.sop 檔案渲染為獨立的 SOP Doc HTML，包含可收合的章節、目錄，以及每個工作流程的 Visual/YAML 分頁。

使用場景

API 文件 — 將所有 API 端點 SOP 組在一起
團隊操作手冊 — 事件回應、部署、回滾流程
會話摘要 — 將 Claude Code 會話中的所有工作流程組在一起

合成：.osoplog → 優化的 .osop

將多個執行記錄餵給 AI。AI 分析跨執行的模式，產出優化的工作流程。

1
輸入：一或多個 .osoplog 檔案（+ 可選的基礎 .osop）
2
過程：AI 彙整統計、偵測慢步驟、故障熱點、平行化機會
3
輸出：優化的 .osop + 變更原因的分析報告
terminal
$ osop synthesize run1.osoplog.yaml run2.osoplog.yaml run3.osoplog.yaml \
    --goal "reduce cost and parallelize where possible" \
    -o optimized.osop.yaml

  Analyzing 3 execution records...
  Total nodes: 24 | Avg duration: 142s | Total cost: $0.47
  ✓ Synthesized: optimized.osop.yaml
    - 3 steps parallelized (was sequential)
    - 1 retry policy added (node "deploy" failed 2/3 runs)
    - Estimated improvement: -38% duration, -22% cost

CLI 命令

terminal
# Scaffold a new workflow
$ osop init --name "My Pipeline" --type agent

# Validate against JSON Schema
$ osop validate workflow.osop.yaml

# Dry-run (preview without side effects)
$ osop run workflow.osop.yaml --dry-run

# Real execution with LLM calls
$ osop run workflow.osop.yaml

# Execute with shell commands (requires explicit opt-in)
$ osop run workflow.osop.yaml --allow-exec

# Generate execution log
$ osop run workflow.osop.yaml --log output.osoplog.yaml

# Generate HTML report
$ osop report workflow.osop.yaml output.osoplog.yaml -o report.html
NEW: osop initNEW: real agent executionNEW: --allow-exec security gate

與你的 AI 工具整合

OSOP 支援 18 個 AI 編程代理。通用安裝程式自動偵測你安裝了哪些工具：

$ git clone https://github.com/Archie0125/osop-agent-rules.git
$ cd osop-agent-rules
$ ./install.sh       # auto-detect Cursor, Windsurf, Cline, etc.
$ ./install.sh --all # install for all 18 platforms

在 github.com/Archie0125/osop-agent-rules 查看完整列表。

下一步

視覺化編輯器
拖放 .osop 檔案以視覺化工作流程。
39+ 範例
涵蓋 9 個領域的真實工作流程。
使用案例
了解 OSOP 如何處理程式碼審查、事故處理、合規。
完整規格
包含 JSON Schema 的完整協議參考。