手動承認

manual_approval は「誰かの確認を待ってから継続する」ことをステップ修飾子としてエンコードします。実行がそれを設定したステップに到達すると一時停止し、承認後に初めてステップ本体を実行します。承認前は、システムはそのステップおよびその下流のいかなる動作も実行しません。

構成

  - step: apply_changes
    agent: executor
    input: "把已审核的变更应用到线上"
    manual_approval:
      enabled: true
      approvers:            # 平台用户 ID；留空 = 发起人 / 有执行权限者可批
        - "usr_team_lead"
      timeout: 86400        # 秒；24 小时无人批复自动拒绝
      approval_message: |
        请确认是否应用本轮变更。
        拒绝或超时不会做任何线上修改。

これは任意のステップ（agent、code、sub_workflow など）に付加でき、ステータスを表示するだけの軽量な code ステップに対して、純粋な「手動ゲート」として使用されることもよくあります。

パラメータ

承認プロセス

1. 実行が manual_approval を設定したステップに到達すると一時停止し、実行ステータスは AWAITING_APPROVAL になります
2. 承認レコードを作成し、タイムアウトのカウントを開始します。コンソールは WebSocket を通じて approval_request のリアルタイム通知を受け取り、承認者は同時に通知メールを受け取ることができます
3. 承認者は 3 つの経路のいずれかで承認します: App 内の承認一覧、メッセージ内のワンクリックリンク、API
4. 承認 → ステップ継続。却下 → ステップは失敗として処理されます（on_failure で通知の分岐につなげられます）。タイムアウト → 自動却下

経路 1: App 内の承認一覧

コンソールの承認ページには、あなたが閲覧できるすべての承認が一覧表示され、カード / テーブルの 2 つのビューとステータスフィルタに対応します。承認または却下の際にメモを添付でき、メモは承認レコードに保存されます。reviewable_actions を設定した承認は、チェック可能かつ編集可能なテーブルとして展開されます。

経路 2: メール通知とワンクリックリンク

メール通知を有効にすると、承認者（approvers を指定していない場合は実行の発起人）のアカウントメールにメールが届きます。内容には、ワークフローとステップ名、実行 ID、レビュー可能なアクション数、タイムアウトの通知（「約 N 時間後に自動却下」）、approval_message の説明文、および承認一覧へのリンクが含まれます。

メール、Slack、Telegram のようにリクエストヘッダーをカスタマイズできないメッセージには、ワンクリック承認リンクを埋め込むこともできます。

GET https://braidrun.com/api/webhook-trigger/approval/{approvalId}/approve?api_key=dyk_...
GET https://braidrun.com/api/webhook-trigger/approval/{approvalId}/reject?api_key=dyk_...

リンクは API Key で認証し（APPROVAL_RESPOND スコープ）、Key は api_key クエリパラメータに入れます。リンクプレビューボット（Slack の展開、メールクライアントの事前取得）による誤操作を防ぐため、初回に開いたときは確認ページのみをレンダリングし、いかなる動作も実行しません。確認ボタンをクリックして confirm=1 を付けて再度リクエストすることで初めて実際に承認されます。ページには no-store と noindex ヘッダーが付き、キャッシュや検索エンジンによる再実行を回避します。

経路 3: API

v1 オープン API は 5 つの承認エンドポイントを提供し、すべて APPROVAL_RESPOND 権限スコープを必要とします。

# 批准（可附备注）
curl -X POST https://braidrun.com/api/v1/approvals/<approval-id>/approve \
  -H "Authorization: Bearer dyk_..." \
  -H "Content-Type: application/json" \
  -d '{"comment": "确认执行"}'

# 拒绝
curl -X POST https://braidrun.com/api/v1/approvals/<approval-id>/reject \
  -H "Authorization: Bearer dyk_..." \
  -H "Content-Type: application/json" \
  -d '{"comment": "本轮预算已用完"}'

editedItems はグループ名ごとにチェック / 編集後のサブセットを送信し、構造は次のセクションの編集可能な承認フォームに対応します。指定しない場合は、そのまますべて承認したものとみなされます。

編集可能な承認フォーム（reviewable_actions）

一部の承認は個々の提案の粒度に落とし込まれます。一連の提案のうち一部のみを実行し、個別の行では数値を変更する必要もあります。reviewable_actions はこの種の承認をテーブル化します。承認者は実行したい行にチェックを入れ、editable: true とマークされた列を直接編集し（例えば入札額を変更）、その後承認をクリックします。

    manual_approval:
      enabled: true
      timeout: 86400
      approval_message: |
        请审核本轮调价建议：可勾选要执行的行，并直接修改建议出价。
      reviewable_actions:
        - name: raise_bid
          title: 加价建议
          source_var: raise_bid_file           # 变量值 = 建议清单 JSON 数组文件路径
          output_var: raise_bid_approved_file  # 批准后 = 勾选/编辑后的子集文件路径
          key_field: item_id
          columns:
            - { key: item_name, label: 名称, editable: false }
            - { key: current_bid, label: 当前出价, type: number, editable: false }
            - { key: proposed_bid, label: 建议出价, type: number, editable: true }
            - { key: reason, label: 理由, editable: false }

• name — グループの内部名で、出力ファイルのプレフィックスとしても使われます（承認後、エンジンは reviewed_<name>.json を書き出します）
• source_var — 変数を指し、その変数の値は上流ステップが生成した提案リスト（JSON 配列ファイルのパス）です
• output_var — 承認後に設定される変数で、値はチェック / 編集後のサブセットファイルのパスです。下流の実行ステップがこれを読むように変更すると、承認された行のみが処理されます
• key_field — 行の識別フィールドで、編集後はこれに従って照合されます。省略した場合は配列のインデックスに従って照合されます
• columns — テーブルの列定義です。editable: true の列は承認者が変更でき、type: number は数値入力としてレンダリングされます

却下とタイムアウト: 変更ゼロ

承認ゲートの中核となる約束は、承認前にシステムがいかなる動作も実行しないことです。却下またはタイムアウトの場合——

• ステップ本体は実行されず、それに依存する下流ステップもトリガーされません
• on_failure の分岐で「承認が却下された」旨の通知またはアーカイブのステップにつなげられます
• タイムアウトはシステムによって自動的に却下され、決定者は system として記録されます。各承認判断（決定者、時刻、メモを含む）はすべて監査ログに記録されます

関連ページ

• API Key と権限スコープ
• v1 API リファレンス
• サービス再起動後の自動再開