Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

12.9 KB
Raw Blame
package domain

import (
	"encoding/json"
	"fmt"
	"strings"
	"time"
)

type VerificationGate struct {
	ID        string   `json:"id"`
	Name      string   `json:"name"`
	Mode      string   `json:"mode"`            // command, manual, mr
	Stage     string   `json:"stage,omitempty"` // after_execution, before_publish
	Commands  []string `json:"commands,omitempty"`
	Required  bool     `json:"required"`
	OnFailure string   `json:"onFailure,omitempty"` // loop, reject, fail, human
	// ExecutionScope is required for command gates: run or repositories.
	ExecutionScope string `json:"executionScope,omitempty"`
}

type Position struct {
	X float64 `json:"x"`
	Y float64 `json:"y"`
}

// WorkflowRequirement declares an external capability a SOP needs before it can
// deliver end to end. Studio renders the list as a preflight checklist when a
// project adopts a template, so a missing Git Token or tracker MCP config
// surfaces before the first run instead of failing in the middle of a pipeline.
type WorkflowRequirement struct {
	Key    string `json:"key"`              // stable id: gongfeng-git-token, gongfeng-mcp
	NodeID string `json:"nodeId,omitempty"` // node that depends on the capability
	Label  string `json:"label"`
	Hint   string `json:"hint,omitempty"`
	Setup  string `json:"setup,omitempty"` // settings (personal credentials) | mcp (MCP management)
}

type WorkflowNode struct {
	// TaskPrompt is what an approval node asks its approver to check
	// (「需要确认什么」). Role nodes take their whole brief from the role's
	// prompt; the field is not read for them.
	TaskPrompt   string   `json:"taskPrompt,omitempty"`
	RequestedBy  string   `json:"requestedBy,omitempty"`
	RequestID    string   `json:"requestId,omitempty"`
	ClaimedFiles []string `json:"claimedFiles,omitempty"`
	PlanItemID   string   `json:"planItemId,omitempty"`
	ID           string   `json:"id"`
	Name         string   `json:"name"`
	Type         string   `json:"type"` // agent, script, approval, sop
	// MetricStage explicitly assigns this node's execution time to a Loop phase.
	// Empty means a legacy workflow without a classification; "none" opts out.
	MetricStage string `json:"metricStage,omitempty"` // clarification, development, testing, none
	AgentID     string `json:"agentId,omitempty"`
	ExecutorID  string `json:"executorId,omitempty"`
	// SOPWorkflowID is the referenced workflow when Type is "sop".
	SOPWorkflowID string `json:"sopWorkflowId,omitempty"`
	// RunOnWorkspaceRebuild replays this script when restoring an already-used environment.
	RunOnWorkspaceRebuild bool               `json:"runOnWorkspaceRebuild,omitempty"`
	ScriptLanguage        string             `json:"scriptLanguage,omitempty"` // shell, python
	Script                string             `json:"script,omitempty"`
	// CredentialEnv requests platform-managed credentials as environment
	// variables for script and verification commands: each entry maps an
	// environment variable name to a credential kind (a RunCredentials.Extra
	// key registered by the deployment). A declared credential the
	// responsible user has not saved fails the node up front; the secret
	// itself never appears in workflow definitions, node configs or logs.
	CredentialEnv  map[string]string `json:"credentialEnv,omitempty"`
	ExecutionScope string            `json:"executionScope,omitempty"` // run, repositories; empty = run
	Command               string             `json:"command,omitempty"`        // legacy command-node payload
	ArtifactOutputs       []ArtifactContract `json:"artifactOutputs,omitempty"`
	RejectTo              string             `json:"rejectTo,omitempty"`
	OnFailure             string             `json:"onFailure,omitempty"`     // fail, reject
	RetryStrategy         string             `json:"retryStrategy,omitempty"` // targeted_fix, full_redo
	CarryOver             []string           `json:"carryOver,omitempty"`
	MaxAttempts           int                `json:"maxAttempts"`
	MaxReworks            int                `json:"maxReworks"`
	Notifications         []NodeNotification `json:"notifications,omitempty"`
	Position              Position           `json:"position"`
}

// ValidateWorkflowMetricStages prevents silently dropping a mistyped stage.
func ValidateWorkflowMetricStages(workflow WorkflowDefinition) error {
	for _, node := range workflow.Nodes {
		switch node.MetricStage {
		case "", "clarification", "development", "testing", "none":
		default:
			return fmt.Errorf("workflow node %q has unsupported metricStage %q", node.ID, node.MetricStage)
		}
	}
	return nil
}

// ArtifactContract is the declared output contract of a workflow node. Paths are
// relative to the node workspace; Markdown is the default interchange format.
type ArtifactContract struct {
	Name      string `json:"name"`
	Path      string `json:"path"`
	MediaType string `json:"mediaType,omitempty"`
	Required  bool   `json:"required"`
}

type WorkflowEdge struct {
	ID     string `json:"id"`
	Source string `json:"source"`
	Target string `json:"target"`
	When   string `json:"when"` // success
}

// DefinitionRevision is an immutable snapshot of a workflow or agent so
// operators can diff and restore a previous version.
type DefinitionRevision struct {
	ID        string          `json:"id"`
	Kind      string          `json:"kind"` // workflow, agent
	EntityID  string          `json:"entityId"`
	Version   int             `json:"version"`
	Revision  int             `json:"revision"`
	Name      string          `json:"name"`
	Summary   string          `json:"summary,omitempty"`
	Payload   json.RawMessage `json:"payload"`
	CreatedAt time.Time       `json:"createdAt"`
}

// SOPCheckpoint is frozen in the run JSON, never in a catalog definition.
type SOPCheckpoint struct {
	Workflow WorkflowDefinition  `json:"workflow"`
	Nodes    map[string]*NodeRun `json:"nodes"`
}
type GroupTaskHistory struct {
	Node  WorkflowNode `json:"node"`
	State NodeRun      `json:"state"`
}

// GroupSOPHandoff points at immutable, archived context for resumed SOP nodes.
// It belongs to a run snapshot, never to the catalog template.
type GroupSOPHandoff struct {
	ID                   string    `json:"id"`
	NodeID               string    `json:"nodeId"`
	SummaryPath          string    `json:"summaryPath"`
	TranscriptPath       string    `json:"transcriptPath"`
	SummaryArtifactID    string    `json:"summaryArtifactId"`
	TranscriptArtifactID string    `json:"transcriptArtifactId"`
	CreatedAt            time.Time `json:"createdAt"`
}

type WorkflowDefinition struct {
	GroupSOPHandoff   *GroupSOPHandoff      `json:"groupSopHandoff,omitempty"`
	GroupCompletion   *GroupCompletion      `json:"groupCompletion,omitempty"`
	GroupMembers      []string              `json:"groupMembers,omitempty"`
	SOPCheckpoint     *SOPCheckpoint        `json:"sopCheckpoint,omitempty"`
	GroupHistory      []GroupTaskHistory    `json:"groupHistory,omitempty"`
	GroupPlan         []GroupPlanItem       `json:"groupPlan,omitempty"`
	CollaborationMode string                `json:"collaborationMode,omitempty"`
	TaskTitle         string                `json:"taskTitle,omitempty"`
	Notifications     []NotificationBinding `json:"notifications,omitempty"` // SOP completion reports
	ID                string                `json:"id"`
	Name              string                `json:"name"`
	Version           int                   `json:"version"`
	Revision          int                   `json:"revision"`
	PublishedRevision int                   `json:"publishedRevision,omitempty"`
	Status            string                `json:"status"` // draft, published, archived
	ProjectID         string                `json:"projectId,omitempty"`
	Shared            bool                  `json:"shared,omitempty"`
	Owner             string                `json:"owner,omitempty"`
	Tags              []string              `json:"tags,omitempty"`
	Description       string                `json:"description"`
	SandboxProfileID  string                `json:"sandboxProfileId"`
	// MetricCategory 是受控的统计标签(需求开发/Bug 修复/…),用于交付指标归类。
	// Run 创建时随 WorkflowSnapshot 冻结,历史执行不受后续编辑影响。
	MetricCategory string `json:"metricCategory,omitempty"`
	// SOPLane 是受控的角色链标签(产品/前端/后端/修复),一条需求上可并列多条。
	// 和 MetricCategory 正交:category 回答「需求还是 Bug」,lane 回答「哪条角色链」。
	SOPLane      string                `json:"sopLane,omitempty"`
	Generic      bool                  `json:"generic,omitempty"`
	Requirements []WorkflowRequirement `json:"requirements,omitempty"`
	// SandboxSnapshot is populated only on Run.WorkflowSnapshot. It freezes
	// the resolved profile plus Dockerfile/environment payload so retries can
	// reconstruct the original environment after catalog definitions change.
	SandboxSnapshot *RunnerSandboxSpec `json:"sandboxSnapshot,omitempty"`
	// Preview is the optional frontend delivery contract. It is frozen into
	// the run snapshot so later SOP edits cannot change an in-flight archive.
	Preview   *PreviewContract `json:"preview,omitempty"`
	Nodes     []WorkflowNode   `json:"nodes"`
	Edges     []WorkflowEdge   `json:"edges"`
	CreatedAt time.Time        `json:"createdAt"`
	UpdatedAt time.Time        `json:"updatedAt"`
}

// UnmarshalJSON migrates the pre-workflow-sandbox shape while the legacy node
// field is still visible. Conflicting node profiles cannot describe one shared
// workflow sandbox and are rejected instead of being silently guessed.
func (w *WorkflowDefinition) UnmarshalJSON(raw []byte) error {
	type workflowAlias WorkflowDefinition
	type legacyNode struct {
		WorkflowNode
		SandboxProfileID      string `json:"sandboxProfileId,omitempty"`
		RunOnWorkspaceRebuild *bool  `json:"runOnWorkspaceRebuild,omitempty"`
		LegacyPreparation     string `json:"workspacePreparation,omitempty"`
	}
	var value struct {
		workflowAlias
		Nodes []legacyNode `json:"nodes"`
	}
	if err := json.Unmarshal(raw, &value); err != nil {
		return err
	}
	*w = WorkflowDefinition(value.workflowAlias)
	w.Nodes = make([]WorkflowNode, len(value.Nodes))
	legacyProfile := ""
	for i, node := range value.Nodes {
		w.Nodes[i] = node.WorkflowNode
		if node.RunOnWorkspaceRebuild != nil {
			w.Nodes[i].RunOnWorkspaceRebuild = *node.RunOnWorkspaceRebuild
		} else if node.LegacyPreparation == "environment" || node.LegacyPreparation == "code" {
			// Read earlier local prototypes as the single opt-in flag. New JSON only writes the flag.
			w.Nodes[i].RunOnWorkspaceRebuild = true
		}
		profile := strings.TrimSpace(node.SandboxProfileID)
		if profile == "" {
			continue
		}
		if legacyProfile != "" && profile != legacyProfile {
			return fmt.Errorf("workflow %q has conflicting legacy node sandbox profiles %q and %q", w.ID, legacyProfile, profile)
		}
		legacyProfile = profile
	}
	if w.SandboxProfileID == "" {
		w.SandboxProfileID = legacyProfile
	} else if legacyProfile != "" && w.SandboxProfileID != legacyProfile {
		return fmt.Errorf("workflow %q sandbox profile %q conflicts with legacy node profile %q", w.ID, w.SandboxProfileID, legacyProfile)
	}
	return nil
}

type WorkflowMetrics struct {
	WorkflowID      string               `json:"workflowId"`
	TotalRuns       int                  `json:"totalRuns"`
	ActiveRuns      int                  `json:"activeRuns"`
	WaitingRuns     int                  `json:"waitingRuns"`
	SucceededRuns   int                  `json:"succeededRuns"`
	FailedRuns      int                  `json:"failedRuns"`
	CancelledRuns   int                  `json:"cancelledRuns"`
	ReworkedRuns    int                  `json:"reworkedRuns"`
	ClosureRate     float64              `json:"closureRate"`
	SuccessRate     float64              `json:"successRate"`
	ReworkRate      float64              `json:"reworkRate"`
	AverageDuration int64                `json:"averageDurationMs"`
	TotalTokens     int64                `json:"totalTokens"`
	TotalToolCalls  int                  `json:"totalToolCalls"`
	TotalArtifacts  int                  `json:"totalArtifacts"`
	LastRunAt       *time.Time           `json:"lastRunAt,omitempty"`
	LastRunStatus   string               `json:"lastRunStatus,omitempty"`
	RecentRuns      []RunSummary         `json:"recentRuns,omitempty"`
	NodeMetrics     []WorkflowNodeMetric `json:"nodeMetrics,omitempty"`
}

type RunSummary struct {
	ID          string    `json:"id"`
	Status      string    `json:"status"`
	CreatedAt   time.Time `json:"createdAt"`
	UpdatedAt   time.Time `json:"updatedAt"`
	DurationMs  int64     `json:"durationMs"`
	ReworkCount int       `json:"reworkCount"`
	TotalTokens int64     `json:"totalTokens"`
	ToolCalls   int       `json:"toolCalls"`
	Artifacts   int       `json:"artifacts"`
}

type WorkflowNodeMetric struct {
	NodeID          string  `json:"nodeId"`
	Name            string  `json:"name"`
	Executions      int     `json:"executions"`
	Succeeded       int     `json:"succeeded"`
	Failed          int     `json:"failed"`
	Waiting         int     `json:"waiting"`
	Reworks         int     `json:"reworks"`
	SuccessRate     float64 `json:"successRate"`
	AverageDuration int64   `json:"averageDurationMs"`
}