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.

17.1 KB
Raw Blame
package domain

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

type RuleDefinition struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	ProjectID   string `json:"projectId,omitempty"`
	Shared      bool   `json:"shared,omitempty"`
	Description string `json:"description"`
	Content     string `json:"content"`
	Priority    int    `json:"priority"`
	// Global marks the rule as a workflow-wide constraint. When true, every
	// node of a workflow listed in WorkflowIDs receives this rule at run time,
	// in addition to the rules already bound on that node's role.
	Global      bool      `json:"global,omitempty"`
	WorkflowIDs []string  `json:"workflowIds,omitempty"`
	UpdatedAt   time.Time `json:"updatedAt"`
}

type SkillDefinition struct {
	ID          string            `json:"id"`
	Name        string            `json:"name"`
	ProjectID   string            `json:"projectId,omitempty"`
	Shared      bool              `json:"shared,omitempty"`
	Description string            `json:"description"`
	Content     string            `json:"content"`
	Files       map[string]string `json:"files,omitempty"`
	// FileRefs is the manifest of binary assets stored in the skill_files
	// table (one row per file). Only metadata travels in the payload; the
	// content is loaded on demand when a run is dispatched.
	FileRefs []SkillFileRef `json:"fileRefs,omitempty"`
	// Source records where an installed skill came from. A non-nil source
	// marks the files as a read-only snapshot that only the market update
	// flow may replace.
	Source    *SkillSource `json:"source,omitempty"`
	UpdatedAt time.Time    `json:"updatedAt"`
}

// SkillSourceSkillHub is the provider of skills installed from skillhub.cn.
const SkillSourceSkillHub = "skillhub"

// SkillSource identifies the market version a skill snapshot was taken from.
// SkillHub slugs are only unique per publisher namespace, so both are kept.
type SkillSource struct {
	Provider    string    `json:"provider"`
	Namespace   string    `json:"namespace,omitempty"`
	Slug        string    `json:"slug"`
	Version     string    `json:"version"`
	Homepage    string    `json:"homepage,omitempty"`
	InstalledAt time.Time `json:"installedAt"`
	UpdatedAt   time.Time `json:"updatedAt"`
}

// SkillFileRef describes one binary file of a skill. Path is relative to the
// skill directory and validated by ValidateRelativeFilePath.
type SkillFileRef struct {
	Path   string `json:"path"`
	Size   int64  `json:"size"`
	SHA256 string `json:"sha256,omitempty"`
	// Mode is the unix permission bits (e.g. 0o755) preserved from the
	// upload so executable scripts keep their exec bit in the sandbox.
	Mode      uint32    `json:"mode,omitempty"`
	UpdatedAt time.Time `json:"updatedAt,omitempty"`
}

type MCPServerDefinition struct {
	ID               string            `json:"id"`
	Name             string            `json:"name"`
	ProjectID        string            `json:"projectId,omitempty"`
	MarketID         string            `json:"marketId,omitempty"`
	Scope            string            `json:"scope,omitempty"` // project, personal; empty is a legacy shared asset
	OwnerUserID      int64             `json:"ownerUserId,omitempty"`
	IconURL          string            `json:"iconUrl,omitempty"`
	Description      string            `json:"description"`
	Transport        string            `json:"transport"` // stdio, http
	Command          string            `json:"command,omitempty"`
	Args             []string          `json:"args,omitempty"`
	URL              string            `json:"url,omitempty"`
	Environment      map[string]string `json:"environment,omitempty"`
	Headers          map[string]string `json:"headers,omitempty"`
	InstallScript    string            `json:"installScript,omitempty"`
	WorkingDirectory string            `json:"workingDirectory,omitempty"`
	PathEntries      []string          `json:"pathEntries,omitempty"`
	FileRefs         []MCPFileRef      `json:"fileRefs,omitempty"`
	AuthType         string            `json:"authType,omitempty"` // empty, github-token, credential
	// CredentialKind names the platform-managed credential (RunCredentials.Extra
	// key) bound as the Authorization Bearer header when AuthType is
	// "credential". The stored asset never holds the secret itself.
	CredentialKind string    `json:"credentialKind,omitempty"`
	TimeoutSec     int       `json:"timeoutSec"`
	UpdatedAt      time.Time `json:"updatedAt"`
}

type MCPFileRef struct {
	Path      string    `json:"path"`
	Size      int64     `json:"size"`
	SHA256    string    `json:"sha256,omitempty"`
	Mode      uint32    `json:"mode,omitempty"`
	UpdatedAt time.Time `json:"updatedAt,omitempty"`
}

type AgentAssetBundle struct {
	Rules      []RuleDefinition      `json:"rules"`
	Skills     []SkillDefinition     `json:"skills"`
	MCPServers []MCPServerDefinition `json:"mcpServers"`
	// SkillFiles carries binary skill file content (skillID -> path ->
	// bytes) next to the definitions so both the local runtime and remote
	// runner machines can materialize them into the sandbox.
	SkillFiles map[string]map[string][]byte `json:"skillFiles,omitempty"`
	MCPFiles   map[string]map[string][]byte `json:"mcpFiles,omitempty"`
}

// DockerfileDefinition is a Studio-managed build recipe. Content and Files are
// stored on the catalog row in MySQL, the same way EnvironmentDefinition stores
// install.sh. Docker sandboxes select one of these; the runtime materializes a
// temporary build context from the stored payload at sandbox initialization.
type DockerfileDefinition struct {
	ID          string            `json:"id"`
	Name        string            `json:"name"`
	ProjectID   string            `json:"projectId,omitempty"`
	Shared      bool              `json:"shared,omitempty"`
	Description string            `json:"description"`
	Content     string            `json:"content"`
	Files       map[string]string `json:"files,omitempty"`
	UpdatedAt   time.Time         `json:"updatedAt"`
}

// EnvironmentDefinition is a named execution toolchain for process sandboxes.
// InstallScript is stored on the environment asset and loaded from the catalog
// at sandbox init; it runs once with PREFIX set to the isolated environment root.
type EnvironmentDefinition struct {
	ID            string            `json:"id"`
	Name          string            `json:"name"`
	ProjectID     string            `json:"projectId,omitempty"`
	Shared        bool              `json:"shared,omitempty"`
	Description   string            `json:"description"`
	Variables     map[string]string `json:"variables,omitempty"`
	PathEntries   []string          `json:"pathEntries,omitempty"`
	InstallScript string            `json:"installScript,omitempty"`
	UpdatedAt     time.Time         `json:"updatedAt"`
}

type SandboxProfile struct {
	ID             string            `json:"id"`
	Name           string            `json:"name"`
	ProjectID      string            `json:"projectId,omitempty"`
	Shared         bool              `json:"shared,omitempty"`
	Driver         string            `json:"driver"` // local, native, docker (seatbelt / bwrap are resolved native values)
	DockerfileID   string            `json:"dockerfileId,omitempty"`
	EnvironmentID  string            `json:"environmentId,omitempty"`
	ReadOnlyRootFS bool              `json:"readOnlyRootFS"`
	Environment    map[string]string `json:"environment,omitempty"`
}

// Sandbox drivers. Profiles store local, native or docker; native is the OS
// lightweight process sandbox and resolves on the executing machine to
// seatbelt (macOS) or bwrap (Linux). seatbelt / bwrap remain valid resolved
// values (runner task payloads, rows written before the native option).
const (
	SandboxDriverLocal    = "local"
	SandboxDriverNative   = "native"
	SandboxDriverDocker   = "docker"
	SandboxDriverSeatbelt = "seatbelt"
	SandboxDriverBwrap    = "bwrap"
)

// ConversationSandboxDriver reports whether a conversation workspace can run
// in a sandbox of driver: Docker, or the native lightweight sandbox (stored as
// native, or already resolved to seatbelt / bwrap).
func ConversationSandboxDriver(driver string) bool {
	switch strings.TrimSpace(driver) {
	case SandboxDriverDocker, SandboxDriverNative, SandboxDriverSeatbelt, SandboxDriverBwrap:
		return true
	default:
		return false
	}
}

// ResolveSandboxDriver maps native onto the lightweight sandbox of goos and
// returns every other driver unchanged. An empty goos (a runner that never
// reported its OS) leaves native for that machine to resolve itself.
func ResolveSandboxDriver(driver, goos string) (string, error) {
	driver = strings.TrimSpace(driver)
	if driver != SandboxDriverNative {
		return driver, nil
	}
	switch strings.ToLower(strings.TrimSpace(goos)) {
	case "darwin":
		return SandboxDriverSeatbelt, nil
	case "linux":
		return SandboxDriverBwrap, nil
	case "":
		return driver, nil
	default:
		return "", fmt.Errorf("系统轻量隔离(native)仅支持 macOS 与 Linux,当前执行机器为 %s", goos)
	}
}

func ValidateDockerfile(v DockerfileDefinition) error {
	if strings.TrimSpace(v.ID) == "" || strings.TrimSpace(v.Name) == "" {
		return fmt.Errorf("Dockerfile 需要 id 和 name")
	}
	if strings.TrimSpace(v.Content) == "" {
		return fmt.Errorf("Dockerfile 内容不能为空")
	}
	return ValidateManagedFiles(v.Files)
}

func ValidateEnvironment(v EnvironmentDefinition) error {
	if strings.TrimSpace(v.ID) == "" || strings.TrimSpace(v.Name) == "" {
		return fmt.Errorf("环境需要 id 和 name")
	}
	if err := ValidateEnvironmentVariables(v.Variables); err != nil {
		return err
	}
	for _, entry := range v.PathEntries {
		if err := ValidateRelativeFilePath(entry); err != nil {
			return fmt.Errorf("pathEntries: %w", err)
		}
	}
	if strings.ContainsRune(v.InstallScript, '\x00') {
		return fmt.Errorf("install.sh 不能包含 NUL")
	}
	return nil
}

func ValidateEnvironmentVariables(values map[string]string) error {
	for key, value := range values {
		if key == "" || strings.ContainsAny(key, "=\x00") {
			return fmt.Errorf("invalid environment variable name %q", key)
		}
		if strings.ContainsRune(value, '\x00') {
			return fmt.Errorf("environment variable %q contains NUL", key)
		}
	}
	return nil
}

func ValidateManagedFiles(files map[string]string) error {
	for name := range files {
		if err := ValidateRelativeFilePath(name); err != nil {
			return err
		}
	}
	return nil
}

// Binary skill upload limits, enforced by the HTTP API.
const (
	// SkillFileMaxBytes caps one uploaded skill file (1MB).
	SkillFileMaxBytes int64 = 1 << 20
	// SkillMaxFileCount caps the number of files per skill (text + binary).
	SkillMaxFileCount = 500
	// SkillTotalMaxBytes caps the combined size of all files per skill (64MB).
	SkillTotalMaxBytes int64 = 64 << 20
	MCPFileMaxBytes          = SkillFileMaxBytes
	MCPMaxFileCount          = SkillMaxFileCount
	MCPTotalMaxBytes         = SkillTotalMaxBytes
)

// NormalizeSkillFileMode keeps only the unix permission bits and defaults to
// 0o644 when the stored mode carries no permission bits.
func NormalizeSkillFileMode(mode uint32) uint32 {
	if mode&0o777 == 0 {
		return 0o644
	}
	return mode & 0o777
}

// ValidateSkillFileRefs checks the binary manifest paths.
func ValidateSkillFileRefs(refs []SkillFileRef) error {
	for _, ref := range refs {
		if err := ValidateRelativeFilePath(ref.Path); err != nil {
			return err
		}
		if ref.Size < 0 || ref.Size > SkillFileMaxBytes {
			return fmt.Errorf("skill file %s exceeds the 1MB limit", ref.Path)
		}
	}
	return nil
}

func ValidateRelativeFilePath(name string) error {
	clean := filepath.ToSlash(strings.TrimSpace(name))
	if clean == "" || clean == "." {
		return fmt.Errorf("invalid file path %q", name)
	}
	if filepath.IsAbs(clean) || strings.HasPrefix(clean, "/") || strings.Contains(clean, ":") {
		return fmt.Errorf("invalid file path %q", name)
	}
	for _, part := range strings.Split(clean, "/") {
		if part == "" || part == "." || part == ".." {
			return fmt.Errorf("invalid file path %q", name)
		}
	}
	return nil
}

func ValidateMCPServer(v MCPServerDefinition) error {
	if strings.TrimSpace(v.ID) == "" || strings.TrimSpace(v.Name) == "" {
		return fmt.Errorf("MCP 需要 id 和 name")
	}
	if err := validateMCPTransport(v); err != nil {
		return err
	}
	if v.TimeoutSec < 0 || v.TimeoutSec > 600 {
		return fmt.Errorf("timeoutSec 需在 0–600 之间")
	}
	if err := validateMCPScope(v); err != nil {
		return err
	}
	return validateMCPAuth(v)
}

// validateMCPTransport checks the launch settings required by v.Transport.
func validateMCPTransport(v MCPServerDefinition) error {
	switch strings.TrimSpace(v.Transport) {
	case "http":
		if !strings.HasPrefix(v.URL, "http://") && !strings.HasPrefix(v.URL, "https://") {
			return fmt.Errorf("HTTP MCP 需要有效的 url")
		}
		return nil
	case "stdio", "":
		return validateMCPStdio(v)
	default:
		return fmt.Errorf("transport 只能是 stdio 或 http")
	}
}

// validateMCPStdio checks the command, install script and workspace-relative
// paths of a stdio MCP server.
func validateMCPStdio(v MCPServerDefinition) error {
	if strings.TrimSpace(v.Command) == "" {
		return fmt.Errorf("stdio MCP 需要 command")
	}
	if strings.ContainsRune(v.InstallScript, '\x00') {
		return fmt.Errorf("MCP 安装脚本不能包含 NUL")
	}
	if cwd := strings.TrimSpace(v.WorkingDirectory); cwd != "" {
		if err := ValidateRelativeFilePath(cwd); err != nil {
			return fmt.Errorf("workingDirectory: %w", err)
		}
	}
	for _, entry := range v.PathEntries {
		if err := ValidateRelativeFilePath(entry); err != nil {
			return fmt.Errorf("pathEntries: %w", err)
		}
	}
	for _, ref := range v.FileRefs {
		if err := ValidateRelativeFilePath(ref.Path); err != nil {
			return err
		}
		if ref.Size < 0 || ref.Size > MCPFileMaxBytes {
			return fmt.Errorf("MCP file %s exceeds the 1MB limit", ref.Path)
		}
	}
	return nil
}

// validateMCPScope checks that project and personal servers carry exactly the
// owner fields their scope allows.
func validateMCPScope(v MCPServerDefinition) error {
	switch strings.TrimSpace(v.Scope) {
	case "":
	case "project":
		if strings.TrimSpace(v.ProjectID) == "" {
			return fmt.Errorf("项目级 MCP 需要 projectId")
		}
		if v.OwnerUserID != 0 {
			return fmt.Errorf("项目级 MCP 不能设置 ownerUserId")
		}
	case "personal":
		if v.OwnerUserID <= 0 {
			return fmt.Errorf("个人级 MCP 需要 ownerUserId")
		}
		if strings.TrimSpace(v.ProjectID) != "" {
			return fmt.Errorf("个人级 MCP 不能设置 projectId")
		}
		if strings.TrimSpace(v.MarketID) != "" {
			return fmt.Errorf("市场 MCP 只能安装到项目,个人级 MCP 必须为自定义")
		}
	default:
		return fmt.Errorf("scope 只能为空、project 或 personal")
	}
	return nil
}

// validateMCPAuth checks v.AuthType and keeps token auth on HTTP
// servers without a stored Authorization header.
func validateMCPAuth(v MCPServerDefinition) error {
	switch strings.TrimSpace(v.AuthType) {
	case "", "github-token", "credential":
	default:
		return fmt.Errorf("authType must be empty, github-token or credential")
	}
	if v.AuthType == "github-token" && strings.TrimSpace(v.Transport) != "http" {
		return fmt.Errorf("GitHub 令牌认证仅支持 HTTP MCP")
	}
	if v.AuthType == "credential" {
		if strings.TrimSpace(v.Transport) != "http" {
			return fmt.Errorf("credential authentication requires an HTTP MCP")
		}
		if strings.TrimSpace(v.CredentialKind) == "" {
			return fmt.Errorf("credential authentication requires credentialKind")
		}
	}
	if v.AuthType == "github-token" {
		for key := range v.Headers {
			if strings.EqualFold(strings.TrimSpace(key), "authorization") {
				return fmt.Errorf("GitHub 令牌认证不允许在资产 Headers 中保存 Authorization")
			}
		}
	}
	if v.AuthType == "credential" {
		for key := range v.Headers {
			if strings.EqualFold(strings.TrimSpace(key), "authorization") {
				return fmt.Errorf("credential authentication must not store an Authorization header on the asset")
			}
		}
	}
	return nil
}

// ParseMCPImport accepts one object, an array, {mcpServers|servers: ...},
// or a map keyed by server id (the on-disk store shape).
func ParseMCPImport(raw json.RawMessage) ([]MCPServerDefinition, error) {
	trimmed := strings.TrimSpace(string(raw))
	if trimmed == "" {
		return nil, fmt.Errorf("空的 MCP JSON")
	}
	raw = json.RawMessage(trimmed)
	var many []MCPServerDefinition
	if err := json.Unmarshal(raw, &many); err == nil {
		if len(many) == 0 {
			return nil, fmt.Errorf("空的 MCP 列表")
		}
		return many, nil
	}
	var one MCPServerDefinition
	if err := json.Unmarshal(raw, &one); err == nil && strings.TrimSpace(one.ID) != "" && strings.TrimSpace(one.Name) != "" {
		return []MCPServerDefinition{one}, nil
	}
	var envelope struct {
		MCPServers json.RawMessage `json:"mcpServers"`
		Servers    json.RawMessage `json:"servers"`
	}
	if err := json.Unmarshal(raw, &envelope); err == nil {
		nested := envelope.MCPServers
		if len(nested) == 0 {
			nested = envelope.Servers
		}
		if len(nested) > 0 {
			return ParseMCPImport(nested)
		}
	}
	var asMap map[string]MCPServerDefinition
	if err := json.Unmarshal(raw, &asMap); err == nil && len(asMap) > 0 {
		out := make([]MCPServerDefinition, 0, len(asMap))
		for id, v := range asMap {
			if strings.TrimSpace(v.ID) == "" {
				v.ID = id
			}
			out = append(out, v)
		}
		return out, nil
	}
	return nil, fmt.Errorf("JSON 不是 MCP 对象、数组或 mcpServers 映射")
}