expert

package
v1.3.102 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 22, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package expert implements the expert bundle format (manifest + persona markdown) and the ExpertCenter layered directory sources (builtin/global/project with name shadowing) used to bind persona content packs to sessions.

Index

Constants

View Source 
const (
	// TypeAgent is a single-persona bundle (manifest agentName points at the
	// only agents/*.md persona).
	TypeAgent = "agent"
	// TypeTeam is a lead + members bundle (manifest teamInfo declares the
	// roster).
	TypeTeam = "team"
)

Supported expertType values in expert.json.

View Source 
const (
	RoleLead   = "lead"
	RoleMember = "member"
)

Member roles within a bundle.

View Source 
const (
	SourceBuiltin = "builtin"
	SourceGlobal  = "global"
	SourceProject = "project"
)

Source layer identifiers reported by Center.

View Source 
const SchemaVersion = 1

SchemaVersion is the only supported expert.json schema version.

Variables

This section is empty.

Functions

func GlobalExpertsDir 

func GlobalExpertsDir() string

GlobalExpertsDir returns the global experts directory (<platform.ConfigDir()>/experts).

Types

type AgentDef 

type AgentDef struct {
	ID          string // = frontmatter name = agents/<ID>.md file name (without .md)
	DisplayName string // manifest members[] name.zh, else name.en, else ID
	Emoji       string
	Role        string // "lead" | "member"; manifest decision first, frontmatter fallback
	Description string
	Prompt      string // markdown body (persona system prompt)
	Meta        Frontmatter
}

AgentDef is one parsed persona definition (agents/<ID>.md).

type Bundle 

type Bundle struct {
	Name          string
	Manifest      Manifest
	Defs          map[string]*AgentDef // all agents/*.md, key = ID
	Invalid       bool
	InvalidReason string
	// SkillsDir is the skills/ location when the bundle carries one. Runtime
	// resource assembly loads it through internal/skills; for OS-directory
	// loads it is a filesystem path and SkillsFS is nil, while for fs.FS loads
	// it is a slash path inside SkillsFS.
	SkillsDir string
	SkillsFS  fs.FS
}

Bundle is a loaded expert package. Validation failures are reported via Invalid/InvalidReason instead of an error; loader errors are IO failures only.

func LoadBundle 

func LoadBundle(dir string) (*Bundle, error)

LoadBundle loads and validates an expert bundle from an OS directory. Validation failures are reported via Bundle.Invalid/InvalidReason; the returned error is reserved for IO failures.

func LoadBundleFS 

func LoadBundleFS(fsys fs.FS, dir string) (*Bundle, error)

LoadBundleFS loads and validates an expert bundle from dir inside fsys, e.g. LoadBundleFS(experts.BuiltinFS, "software-company"). When dir is "." or empty the bundle name is taken from the manifest itself and the directory-name consistency check is skipped.

type Center 

type Center struct {
	// ProjectDir is the project root for the project-level source. Empty
	// means the project layer is disabled.
	ProjectDir string
}

Center resolves expert bundles from three layered sources with name shadowing: project > global > builtin. Scans are lazy (per call), so users can drop a bundle into a directory and it takes effect without a watcher.

func (*Center) Get 

func (c *Center) Get(name string) (*Bundle, error)

Get loads the highest-priority bundle with the given name. A bundle that is absent from every layer returns an error; a bundle that fails validation is returned with Invalid/InvalidReason set (no error).

func (*Center) List 

func (c *Center) List() []Summary

List lazily scans all three layers and returns summaries sorted by name. Higher-priority layers shadow lower ones with the same bundle name. A missing or unreadable directory is an empty layer, not an error. Only directories containing expert.json count as bundles.

func (*Center) ProjectExpertsDir 

func (c *Center) ProjectExpertsDir() string

ProjectExpertsDir returns the project experts directory (<ProjectDir>/.mothx/experts), or "" when the project layer is disabled.

type Frontmatter 

type Frontmatter struct {
	Name          string
	Description   string
	Role          string
	Emoji         string
	Color         string
	Vibe          string
	Mode          string // "" | plan | agent | yolo | os
	Tools         []string
	MaxIterations int
	WorkDir       string
}

Frontmatter holds the parsed agents/*.md frontmatter fields (persona + declarative capability overrides).

type LocalizedText 

type LocalizedText struct {
	Zh string `json:"zh"`
	En string `json:"en"`
}

LocalizedText is a bilingual zh/en text pair used by manifest metadata.

type ManagedBundle 

type ManagedBundle struct {
	Scope    Scope             `json:"scope"`
	Manifest Manifest          `json:"manifest"`
	Agents   map[string]string `json:"agents"`
}

ManagedBundle is the editable representation of an expert bundle. Agent values are complete agents/<id>.md source files (including frontmatter), so the Desktop only ever receives the same bundle format Runtime consumes.

type Manager 

type Manager struct {
	ProjectDir string
	GlobalDir  string
}

Manager owns safe CRUD for the two user-writable bundle layers. ProjectDir is required only for project scope. GlobalDir is primarily injectable for tests; production callers should leave it empty.

func NewManager 

func NewManager(projectDir string) *Manager

func (*Manager) Create 

func (m *Manager) Create(scope Scope, draft ManagedBundle) (*ManagedBundle, error)

Create validates and atomically publishes a new bundle. A name already in the selected user layer is an error even if it merely shadows a builtin.

func (*Manager) Delete 

func (m *Manager) Delete(scope Scope, name string) error

Delete removes exactly one user-owned bundle directory. A caller must name a writable scope; attempting to delete a builtin is rejected by scopeDir.

func (*Manager) Get 

func (m *Manager) Get(scope Scope, name string) (*ManagedBundle, error)

Get reads a bundle from exactly the requested writable layer. It never falls through to an identically named bundle in a lower-priority layer.

func (*Manager) List 

func (m *Manager) List() []Summary

List returns the effective, shadow-resolved catalog used by SessionRuntime.

func (*Manager) ListScope 

func (m *Manager) ListScope(scope Scope) ([]Summary, error)

ListScope returns bundles physically present in one writable layer. It is useful for management UIs that need to expose a global bundle shadowed by a project bundle without weakening the Runtime's precedence rules.

func (*Manager) Update 

func (m *Manager) Update(scope Scope, draft ManagedBundle) (*ManagedBundle, error)

Update replaces exactly one existing global/project bundle. Builtins cannot be updated because no writable scope resolves to the embedded filesystem.

type Manifest 

type Manifest struct {
	SchemaVersion     int             `json:"schemaVersion"`
	Name              string          `json:"name"`
	ExpertType        string          `json:"expertType"`          // "agent" | "team"
	AgentName         string          `json:"agentName,omitempty"` // required for agent type; kept in sync with teamInfo.leadAgent for team
	DisplayName       LocalizedText   `json:"displayName"`
	CategoryID        string          `json:"categoryId,omitempty"`
	QuickPrompts      []LocalizedText `json:"quickPrompts,omitempty"`
	DefaultInitPrompt LocalizedText   `json:"defaultInitPrompt,omitempty"`
	TeamInfo          *TeamInfo       `json:"teamInfo,omitempty"` // team 型必填
	Members           []MemberMeta    `json:"members,omitempty"`
}

Manifest is the expert.json content of a bundle.

type MemberMeta 

type MemberMeta struct {
	ID         string        `json:"id"`
	Name       LocalizedText `json:"name"`
	Profession LocalizedText `json:"profession,omitempty"`
	Avatar     string        `json:"avatar,omitempty"`
	Role       string        `json:"role"` // "lead" | "member"
}

MemberMeta is a manifest members[] entry: pure UI persona metadata that the runtime does not consume for dispatch.

type Scope 

type Scope string

Scope identifies the writable expert layer. Builtin bundles deliberately do not have a scope: they are packaged with the binary and always read-only. 

const (
	ScopeGlobal  Scope = SourceGlobal
	ScopeProject Scope = SourceProject
)

type Summary 

type Summary struct {
	Name          string        `json:"name"`
	ExpertType    string        `json:"expertType"`
	DisplayName   LocalizedText `json:"displayName"`
	Source        string        `json:"source"` // builtin | global | project
	Invalid       bool          `json:"invalid"`
	InvalidReason string        `json:"invalidReason,omitempty"`
}

Summary is a lightweight List entry built from the manifest only; persona bodies are never loaded during listing.

type TeamInfo 

type TeamInfo struct {
	LeadAgent    string   `json:"leadAgent"`
	MemberAgents []string `json:"memberAgents"`
}

TeamInfo declares the lead/member agent ids of a team bundle.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.