1# 確認 Node.js 版本 >= 20
2node --version
3
4# 確認 npm 可用
5npm --version

1npx @prmflow/openflow --help
2npx @prmflow/openflow doctor

1npm install -g @prmflow/openflow
2openflow --help
3openflow doctor

1git clone https://github.com/travisliu/openflow.git
2cd openflow
3npm install
4npm run build
5npx . --help

 1defaultProvider: mock
 2concurrency: 4
 3timeoutMs: 900000
 4
 5providers:
 6  mock:
 7    command: mock
 8    responses:
 9      default:
10        text: "mock response"
11  codex:
12    command: codex
13    args: ["exec", "--json", "--ephemeral"]
14  gemini:
15    command: gemini
16    args: ["--output-format", "json", "--approval-mode", "plan"]
17    defaultModel: gemini-3-flash-preview
18    promptMode: stdin
19
20security:
21  allowShell: false
22  allowWorkflowImports: false
23  passEnv: []
24  redactEnv:
25    - "*_KEY"
26    - "*_TOKEN"
27    - "*_SECRET"
28    - "PASSWORD"
29
30reporting:
31  mode: pretty
32  verbose: false

 1const result = await agent({
 2  id: "code-review",          // 唯一識別（可選，自動產生）
 3  provider: "codex",           // provider 名稱
 4  prompt: "Review this code.", // prompt 文字
 5  model: "o4-mini",            // 指定模型（可選）
 6  timeoutMs: 60000,            // 超時設定（可選）
 7  cwd: "./src",                // 工作目錄（可選）
 8  schema: { ... },             // JSON Schema（可選）
 9  structuredOutput: {          // 結構化輸出設定（可選）
10    transport: "auto"
11  }
12});

1{
2  ok: boolean;
3  text: string;
4  agentId: string;
5  provider: string;
6  durationMs: number;
7  error?: { code: string; message: string; };
8  structured?: unknown;  // JSON Schema 驗證後的結構化資料
9}

 1// 物件形式（具名結果）
 2const results = await parallel({
 3  codex: () => agent({ provider: "codex", prompt: "Review for bugs." }),
 4  gemini: () => agent({ provider: "gemini", prompt: "Review for design." })
 5});
 6// results.codex, results.gemini
 7
 8// 陣列形式
 9const results = await parallel([
10  () => agent({ prompt: "Task A" }),
11  () => agent({ prompt: "Task B" })
12]);
13// results[0], results[1]

1const result = await pipeline(
2  ["file1.ts", "file2.ts"],  // items
3  [
4    { name: "review", run: (ctx) => ctx.agent({ prompt: `Review ${ctx.item}` }) },
5    { name: "fix",    run: (ctx) => ctx.agent({ prompt: `Fix issues in ${ctx.item}` }) }
6  ],
7  { strategy: "item-streaming", concurrency: 2, failFast: false }
8);

1phase("review");
2// ... review 相關 agent calls
3phase("summarize");
4// ... summarize 相關 agent calls

1log("Starting review of 5 files", { fileCount: 5 });

1agent-level model
2  ↓ (若無)
3CLI --model 參數
4  ↓ (若無)
5provider config defaultModel
6  ↓ (若無)
7global config defaultModel
8  ↓ (若無)
9不傳 model 參數

 1// workflows/basic-review.ts
 2export const meta = {
 3  name: "basic-review",
 4  description: "Single agent code review",
 5  phases: ["review"]
 6};
 7
 8phase("review");
 9
10const result = await agent({
11  id: "reviewer",
12  provider: "codex",
13  prompt: "Review the changed files for correctness issues."
14});
15
16export default result;

1openflow run workflows/basic-review.ts

 1// workflows/parallel-review.ts
 2export const meta = {
 3  name: "parallel-review",
 4  description: "Review with multiple providers in parallel",
 5  phases: ["review", "summarize"]
 6};
 7
 8phase("review");
 9
10const reviews = await parallel({
11  codex: () => agent({
12    id: "codex-review",
13    provider: "codex",
14    prompt: "Review the changed files for correctness issues."
15  }),
16  gemini: () => agent({
17    id: "gemini-review",
18    provider: "gemini",
19    prompt: "Review the changed files for API design issues."
20  })
21});
22
23phase("summarize");
24
25const summary = await agent({
26  id: "summary",
27  provider: "codex",
28  prompt: `Summarize these reviews:\n${JSON.stringify(reviews, null, 2)}`
29});
30
31export default { reviews, summary };

 1// workflows/pipeline-review.ts
 2export const meta = {
 3  name: "pipeline-review",
 4  description: "Review multiple files through a pipeline"
 5};
 6
 7const changedFiles = ["src/auth.ts", "src/api.ts", "src/db.ts"];
 8
 9const result = await pipeline(
10  changedFiles,
11  [
12    {
13      name: "review",
14      run: (ctx) => ctx.agent({
15        prompt: `Review ${ctx.item} for security and correctness.`,
16        schema: {
17          type: "object",
18          properties: {
19            file: { type: "string" },
20            findings: { type: "array", items: { type: "string" } }
21          },
22          required: ["file", "findings"]
23        },
24        structuredOutput: { transport: "auto" }
25      })
26    }
27  ],
28  { strategy: "item-streaming", concurrency: 2 }
29);
30
31export default result;

 1// workflows/ci-smoke.ts
 2export const meta = {
 3  name: "ci-smoke",
 4  description: "CI smoke test using mock provider"
 5};
 6
 7phase("test");
 8
 9const result = await agent({
10  id: "smoke",
11  provider: "mock",
12  prompt: "Verify build artifacts exist."
13});
14
15export default result;

1# CI 環境跑 mock workflow
2openflow run workflows/ci-smoke.ts --reporter json

1# 驗證工作流語法但不呼叫任何 provider
2openflow validate workflows/review.ts
3
4# 帶 mock 的 dry run
5openflow run workflows/review.ts --dry-run

 1整體資安評級：🟢 良好
 2
 3優點：
 4- 沙箱設計嚴謹（VM + AST 雙重防護）
 5- Secret 管理完善（pattern redact + streaming redactor）
 6- 無硬編碼憑證
 7- 環境變數白名單機制
 8- 最小權限原則（只暴露必要 DSL）
 9
10需關注：
11- process-runner.ts 的 spawn 是不可避免的攻擊面（但已有防護）
12- 專案非常新（建立僅 3 天），安全機制尚未經大量實戰驗證

 1// 1. metadata（必須是第一個 top-level statement）
 2export const meta = {
 3  name: "workflow-name",       // 必須：工作流名稱
 4  description: "what it does", // 必須：描述
 5  phases: ["phase1", "phase2"] // 可選：phase 清單
 6};
 7
 8// 2. 工作流邏輯（使用 DSL primitive）
 9phase("phase1");
10const result = await agent({ ... });
11
12// 3. 預設匯出（回傳結果）
13export default result;

1CLI 參數（最高優先）
2  ↓
3.openflow/config.yaml（專案層級）
4  ↓
5預設值（DEFAULT_CONFIG）

1# 指定 reporter
2openflow run workflow.ts --reporter json
3openflow run workflow.ts --reporter jsonl

 1openflow run <file> [options]
 2  --provider <name>   # 覆蓋預設 provider
 3  --model <name>      # 覆蓋預設 model
 4  --reporter <mode>   # pretty | json | jsonl
 5  --concurrency <n>   # 最大並行數
 6  --timeout-ms <ms>   # 全域超時
 7  --fail-fast         # 第一個失敗就中止
 8  --dry-run           # 不實際呼叫 provider
 9
10openflow validate <file>  # AST 驗證工作流
11openflow doctor           # 環境健康檢查

1.openflow/runs/<runId>/
2├── manifest.json          # run metadata
3├── report.json            # 最終結果
4├── events.jsonl           # 所有 event 時間線
5└── agents/
6    └── <agentId>/
7        ├── prompt.txt     # 發送的 prompt
8        ├── raw-result.json    # provider 原始輸出
9        └── normalized-result.json  # 正規化後的結果

1git clone https://github.com/travisliu/openflow.git
2cd openflow
3npm install
4npm run build
5npm test

 1openflow/
 2├── src/                    # 原始碼（16 個模組目錄）
 3│   ├── cli/                #   CLI 命令定義
 4│   ├── config/             #   設定載入 / 合併 / 驗證
 5│   ├── workflow/           #   工作流解析 / 驗證 / 沙箱 / DSL
 6│   ├── pipeline/           #   pipeline 執行器
 7│   ├── orchestration/      #   scheduler / event-bus / cancellation
 8│   ├── agents/             #   provider adapter + process-runner
 9│   ├── output/             #   reporter（pretty / json / jsonl）
10│   ├── artifacts/          #   run artifact 持久化
11│   ├── security/           #   env redaction
12│   ├── structured/         #   結構化輸出處理
13│   ├── errors/             #   錯誤碼與 exit code
14│   ├── types/              #   共用型別
15│   ├── runtime/            #   public API
16│   └── doctors/            #   health check
17├── tests/                  # 測試（89 個測試檔）
18│   ├── unit/               #   單元測試
19│   ├── integration/        #   整合測試
20│   ├── cli/                #   CLI 端對端測試
21│   └── fixtures/           #   測試 fixture
22├── skills/                 # AI agent 工作流撰寫技能
23├── examples/               # 範例工作流
24└── workflows.example.ts    # 範例工作流入口