Documentation
¶
Overview ¶
Package workspace manages agent workspace files (SOUL.md, USER.md, IDENTITY.md, etc.) that are loaded into the system prompt to give the agent personality, memory, and context.
Index ¶
- Constants
- func DetectLocale() string
- func IsGitRepositoryDir(dir string) bool
- func NormalizeDefaultTemplateToEnglish(name, content string) string
- func SharedScratchpadDir(workspaceRoot string) string
- func SharedScratchpadRelPath() string
- type BootstrapFile
- type FileTokenStat
- type GitCapability
- type Handler
- type Manager
- func (m *Manager) AppendDailyLog(content string) error
- func (m *Manager) CompleteBootstrap() error
- func (m *Manager) ContextDir() string
- func (m *Manager) DetectGitCapability(ctx context.Context) GitCapability
- func (m *Manager) Dir() string
- func (m *Manager) EnsureWorkspace() error
- func (m *Manager) InvalidateFileCache()
- func (m *Manager) IsBootstrapPending() bool
- func (m *Manager) ListDailyLogs() []string
- func (m *Manager) LoadBootstrapFiles() []BootstrapFile
- func (m *Manager) LoadContextFiles() map[string]string
- func (m *Manager) MemoryDir() string
- func (m *Manager) ReadFile(name string) (string, error)
- func (m *Manager) ReleaseContextPacks(fsys fs.FS) error
- func (m *Manager) ReleaseSkills(fsys fs.FS) error
- func (m *Manager) WriteFile(name, content string) error
Constants ¶
const ( FileSOUL = "SOUL.md" FileUSER = "USER.md" FileIDENTITY = "IDENTITY.md" FileAGENTS = "AGENTS.md" FileTOOLS = "TOOLS.md" FileMEMORY = "MEMORY.md" FileBOOTSTRAP = "BOOTSTRAP.md" )
Well-known workspace filenames.
const MaxFileSize = 1 << 20
MaxFileSize is the maximum allowed size for a workspace file (1 MB).
const (
SharedScratchpadAlias = "scratchpad"
)
Variables ¶
This section is empty.
Functions ¶
func DetectLocale ¶
func DetectLocale() string
DetectLocale returns the cached system locale (computed once per process).
func IsGitRepositoryDir ¶
IsGitRepositoryDir reports whether dir contains Git metadata. It supports both traditional repositories (.git directory) and worktrees where .git is a regular file pointing to the real gitdir.
func NormalizeDefaultTemplateToEnglish ¶
NormalizeDefaultTemplateToEnglish maps locale-specific default workspace template content to its English template equivalent. Non-default or unknown content is returned unchanged.
func SharedScratchpadDir ¶
SharedScratchpadDir resolves the shared scratchpad directory inside a workspace.
func SharedScratchpadRelPath ¶
func SharedScratchpadRelPath() string
SharedScratchpadRelPath returns the canonical workspace-relative scratchpad path.
Types ¶
type BootstrapFile ¶
type BootstrapFile struct {
Name string `json:"name"`
Content string `json:"content,omitempty"`
Missing bool `json:"missing,omitempty"`
}
BootstrapFile represents a loaded workspace file.
type FileTokenStat ¶
type FileTokenStat struct {
Name string `json:"name"`
Bytes int `json:"bytes"`
Tokens int `json:"tokens"`
}
FileTokenStat holds per-file token estimate.
type GitCapability ¶
type GitCapability struct {
WorkspaceDir string `json:"workspace_dir"`
Available bool `json:"available"`
BinaryPath string `json:"binary_path,omitempty"`
Repository bool `json:"repository"`
RepoRoot string `json:"repo_root,omitempty"`
WorkspaceRooted bool `json:"workspace_rooted"`
CanInitialize bool `json:"can_initialize"`
CanCommit bool `json:"can_commit"`
UserNameConfigured bool `json:"user_name_configured"`
UserEmailConfigured bool `json:"user_email_configured"`
Reason string `json:"reason,omitempty"`
}
GitCapability describes whether the workspace can be managed safely with Git.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler provides HTTP endpoints for workspace file management.
func NewHandler ¶
NewHandler creates a new workspace HTTP handler.
func (*Handler) RegisterRoutes ¶
RegisterRoutes registers workspace API routes on the given group.
func (*Handler) SetAllowedRootsProvider ¶
SetAllowedRootsProvider sets an optional provider for extra roots that can be scanned by getTree (for example directory whitelist roots).
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager manages workspace files on disk.
func NewManager ¶
NewManager creates a workspace manager for the given directory.
func (*Manager) AppendDailyLog ¶
AppendDailyLog appends content to today's daily log file (memory/YYYY-MM-DD.md).
func (*Manager) CompleteBootstrap ¶
CompleteBootstrap removes BOOTSTRAP.md after the first-run guide is done.
func (*Manager) ContextDir ¶
ContextDir returns the path to the local context pack registry.
func (*Manager) DetectGitCapability ¶
func (m *Manager) DetectGitCapability(ctx context.Context) GitCapability
DetectGitCapability inspects whether the workspace can use Git safely.
func (*Manager) EnsureWorkspace ¶
EnsureWorkspace creates the workspace directory and writes default template files if they don't already exist. Safe to call multiple times.
func (*Manager) InvalidateFileCache ¶
func (m *Manager) InvalidateFileCache()
InvalidateFileCache clears the file cache (call after writes).
func (*Manager) IsBootstrapPending ¶
IsBootstrapPending returns true only while first-run onboarding is actually pending.
func (*Manager) ListDailyLogs ¶
ListDailyLogs returns all daily log filenames sorted by date (newest first).
func (*Manager) LoadBootstrapFiles ¶
func (m *Manager) LoadBootstrapFiles() []BootstrapFile
LoadBootstrapFiles reads all well-known workspace files and returns them. Missing files are included with Missing=true and empty Content. Also includes BOOTSTRAP.md if it exists (first-run only). Uses mtime-based file caching to avoid redundant disk reads.
func (*Manager) LoadContextFiles ¶
LoadContextFiles returns a map of filename→content for non-empty workspace files, ready to inject into SystemPromptBuilder. This is a lightweight path that avoids the overhead of LoadBootstrapFiles (no Missing entries, no BootstrapFile structs). Uses mtime-based file caching to avoid redundant disk reads.
func (*Manager) ReadFile ¶
ReadFile reads a single workspace file by name. Returns an error if the file exceeds MaxFileSize.
func (*Manager) ReleaseContextPacks ¶
ReleaseContextPacks writes embedded context pack files to {workspace}/.blue/context/...
func (*Manager) ReleaseSkills ¶
ReleaseSkills writes embedded SKILL.md files to {workspace}/.agents/skills/{name}/SKILL.md. Content-aware: only overwrites if the embedded content differs from the on-disk content (ignoring the `enabled` field which is user-managed state). Platform-aware: skips skills whose `os` field doesn't match runtime.GOOS. Preserves the `enabled` field from the existing on-disk file across upgrades, including legacy peer copies that still live under {workspace}/.claude/skills.
Source Files