runner

Documentation

Index

• Constants
• func CleanStaleOutputs(paths ...string)
• func DeepFixLogFileName(round, iteration int) string
• func DeepReverifyLogFileName(round, iteration int) string
• func DeepReviewerLogFileName(round, index int) string
• func IsHardError(r *Result) bool
• func IsSoftFail(r *Result) bool
• func IterationLogFileName(round int, role string, iteration int) string
• func LogDir(ws *protocol.Workspace, featureID string) string
• func LogFileName(round int, role string) string
• func ReviewFixLogFileName(round, iteration int) string
• func StreamLogFileName(round int, role string) string
• type Factory
  • func NewFactory(ws *protocol.Workspace, cfg protocol.Config, timeoutSec int) Factory
• type Result
• type Runner
  • func NewRunner(ws *protocol.Workspace, name string, cfg protocol.RunnerConfig, ...) Runner
• type SubprocessRunner
  • func (r *SubprocessRunner) Run(ctx context.Context, prompt string) (*Result, error)

Constants

const DefaultTransientRetries = 3

DefaultTransientRetries 是暫態錯誤的預設重試上限（不含原始那次嘗試）。 命中暫態 pattern 時最多再重跑同一命令這麼多次，避免網路抖動中斷整個 batch。

const ExitHardError = 2

const ExitSoftFail = 1

Functions

func CleanStaleOutputs

func CleanStaleOutputs(paths ...string)

CleanStaleOutputs 在呼叫 runner 前刪除指定的產出檔殘留。

LLM runner 產出檔（如 gate-verdicts.json）在下一輪執行前不會自動消失；若 runner 回 nil 卻沒寫新檔，下游會靜默讀到上一輪的舊資料。先清掉這些檔，能讓「沒寫新檔」退化為明確的 讀取／parse error，而非吃到 stale data。

只刪傳入的明確清單，不觸及其他 artifact（如手動建立的 escalation.json）。每次成功刪除記一筆 slog.Debug 以利排查；檔案不存在視為正常（無聲略過），其餘刪除失敗記 slog.Warn 但不中斷。

func DeepFixLogFileName

func DeepFixLogFileName(round, iteration int) string

DeepFixLogFileName 產生 deep-reviewing 自癒循環中 mini-coder 的 log 檔名： round-<round>-deep-fix-<iteration>.log。

func DeepReverifyLogFileName

func DeepReverifyLogFileName(round, iteration int) string

DeepReverifyLogFileName 產生 deep-reviewing 自癒循環中 re-verifier 的 log 檔名： round-<round>-deep-reverify-<iteration>.log。

func DeepReviewerLogFileName

func DeepReviewerLogFileName(round, index int) string

DeepReviewerLogFileName 產生平行 deep review 模式下第 index 個 sub-reviewer 的 log 檔名： round-<round>-deep-reviewer-<index>.log（index 為 1-based）。每個 sub-reviewer 用各自的 log 檔，不與其他 sub-reviewer 共用，讓 dashboard 能分檔即時追蹤。

func IsHardError

func IsHardError(r *Result) bool

func IsSoftFail

func IsSoftFail(r *Result) bool

func IterationLogFileName

func IterationLogFileName(round int, role string, iteration int) string

IterationLogFileName 產生「同一 round 內第 iteration 次執行」的 log 檔名。 designer / design-reviewer 這類 role 在 round 不變的情況下也可能重複執行 （例如 design-reviewing FAIL 打回 designing），iteration 用來避免同名 log 檔案互相覆寫。iteration<=1 沿用既有 round-<N>-<role>.log 格式（向下相容）， iteration>1 才加上 -<iteration> 後綴。

func LogDir

func LogDir(ws *protocol.Workspace, featureID string) string

LogDir 回傳 .4x/<featureId>/logs/ 的路徑

func LogFileName

func LogFileName(round int, role string) string

LogFileName 產生 log 檔名：round-<N>-<role>.log

func ReviewFixLogFileName

func ReviewFixLogFileName(round, iteration int) string

ReviewFixLogFileName 產生 reviewing phase 同輪收斂循環中 mini-coder 的 log 檔名： round-<round>-review-fix-<iteration>.log。命名刻意與主 reviewer log （IterationLogFileName 產生的 round-<round>-reviewer[-<iter>].log）區隔， 避免 CONDITIONAL PASS 收斂的 mini-coder log 覆蓋主 reviewer log。

func StreamLogFileName

func StreamLogFileName(round int, role string) string

StreamLogFileName 產生 stream-json log 檔名：round-<N>-<role>.stream.jsonl。

Types

type Factory

type Factory func(name, logPath, model string) Runner

Factory 依 (name, logPath, model) 建構一個 Runner，供 run.go/evolve.go/batch.go 共用同一組「從 workspace + config + timeout 組出 runnerFactory」的邏輯。

func NewFactory

func NewFactory(ws *protocol.Workspace, cfg protocol.Config, timeoutSec int) Factory

NewFactory 回傳一個 Factory：呼叫時以 cfg.Runners[name] 解析該 runner 的設定， 搭配固定的 ws 與 timeoutSec 建構 Runner。取代原本在 run.go/evolve.go/batch.go 各自重複撰寫的 runnerFactory 閉包。

type Result

type Result struct {
	ExitCode    int
	DurationSec float64
	LogFile     string
}

Result 是 plugin 執行的結果

type Runner

type Runner interface {
	Run(ctx context.Context, prompt string) (*Result, error)
}

Runner 定義 plugin 的呼叫介面

func NewRunner

func NewRunner(ws *protocol.Workspace, name string, cfg protocol.RunnerConfig, timeout time.Duration, logPath string, model string) Runner

NewRunner 建立 SubprocessRunner，logPath 為空字串時不產生 log file，model 為空字串時不帶 --model flag。

暫態重試上限由 cfg.TransientRetries 決定：nil → 預設（DefaultTransientRetries）、 0 → 停用重試、>0 → 自訂。config 的 0（停用）會映射成 SubprocessRunner.MaxTransientRetries 的 負值，以區別於零值（零值代表「用預設」）。

type SubprocessRunner

type SubprocessRunner struct {
	Workspace     *protocol.Workspace
	Config        protocol.RunnerConfig
	Name          string
	Timeout       time.Duration
	LogPath       string
	ModelOverride string
	// MaxTransientRetries 是暫態錯誤的重試上限：0（零值）表示「用 DefaultTransientRetries」、
	// 負值表示停用重試、正值為自訂上限。實際值由 resolveMaxRetries() 解析。
	MaxTransientRetries int

	// ExtraEnv 是額外注入子程序環境變數（如 FOURX_ROLE / FOURX_REVIEW_PACKAGE）。
	// 由 orchestrator 只對 reviewer/deep-reviewer 角色的 SubprocessRunner 設定；其他角色為 nil。
	// 當 Config.Command == "claude" 且 len(ExtraEnv) > 0 時，buildArgs 額外注入 PreToolUse
	// hook settings（guard-tool），攔截 reviewer 自跑 git diff/log/show。不改任何函式簽章。
	ExtraEnv []string
	// contains filtered or unexported fields
}

SubprocessRunner 透過 config 定義的 command + args 呼叫 LLM CLI

func (*SubprocessRunner) Run

func (r *SubprocessRunner) Run(ctx context.Context, prompt string) (*Result, error)

Run 用 config 的 command/args 執行，替換 {prompt} 和 {promptFile}。

子程序因暫態 API 錯誤（socket closed、connection reset、rate limit、5xx 等）非零退出時， 會以指數退避自動重試同一命令（上限見 MaxTransientRetries / RunnerConfig.TransientRetries）， 重試成功後透明回傳 exit 0 的 Result，讓 batch 排程不因網路抖動中斷。非暫態失敗、exit 0、 context 取消 / 逾時、命令啟動失敗一律不重試，且最終一次嘗試的 Result 形狀與 exit code 語義 與不重試時完全一致。