agent

package
v0.26.0 Latest Latest
Warning

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

 Go to latest Published: Aug 22, 2026 License: Apache-2.0 Imports: 32 Imported by: 0

Documentation

Overview

Package agent 驱动「请求 → 模型发起工具调用 → 执行 → 回灌结果 → 再请求」的多轮循环。 依赖 anthropic/tools/permission/prompt。**不依赖任何 UI 框架**：进度以领域事件 Event 经 emit 回调 交出，由 tui 层翻译成界面消息。这样 agent 可脱离 bubbletea 独立测试。

Index

Constants

View Source 
const (
	NotifyPermissionPrompt = "permission_prompt" // 等用户批准一次工具调用
	NotifyQuestionPrompt   = "question_prompt"   // 等用户回答 AskUserQuestion
	NotifyIdlePrompt       = "idle_prompt"       // 回合结束后长时间无人理（对齐上游 idle_prompt）
	NotifyTaskDone         = "task_done"         // 长任务完成
	// NotifyElicitationResponse：一次 MCP elicitation 定案后发出（不管是 hook 自动答的还是人答的），
	// 供观测用（对齐上游 elicitation_response）。
	NotifyElicitationResponse = "elicitation_response"
)

通知类型（作为 Notification hook 的 matcher 值，也随 stdin JSON 交给 hook）。

View Source 
const SessionMemoryTemplate = `` /* 1167-byte string literal not displayed */

SessionMemoryTemplate 对齐上游 DEFAULT_SESSION_MEMORY_TEMPLATE（10 节，含 Worklog）。 早先 fundev 把 Worklog 节并入 Workflow（少一节），现严格对齐上游 10 节结构。

Variables

This section is empty.

Functions

func AmbientEmitFrom added in v0.24.0 

func AmbientEmitFrom(ctx context.Context) func(Event)

AmbientEmitFrom 取 ctx 里的回合外事件通道；未注册返回 nil。

func AutoCompactCircuitOpen added in v0.5.0 

func AutoCompactCircuitOpen(ctx context.Context) bool

AutoCompactCircuitOpen 报告熔断器是否已断开（连续失败达上限），供外部调用方展示/诊断。

func AutoCompactThresholdForCtx added in v0.5.0 

func AutoCompactThresholdForCtx(ctx context.Context) int

AutoCompactThresholdForCtx 返回在给定 ctx 下生效的自动压缩阈值（供外部调用方展示）。 模型与窗口都取 ctx 口径：EffectiveModel 读本会话实际生效模型，AutoCompactThresholdFor 优先用 ctx 注入的真实窗口——与 proactiveCompactIfNeeded 同一口径。

func BgTaskList 

func BgTaskList() string

BgTaskList 返回后台任务的纯文本摘要，按 id 排序；无任务时给提示。 （/tasks 现由 TUI 交互面板呈现，见 BgTaskSnapshot；此文本形式保留供非交互/程序化列举。）

func BgTaskStop 

func BgTaskStop(id string) bool

BgTaskStop 中止一个运行中的后台任务；返回是否确实中止了一个 running 任务。

func BypassPermissions 

func BypassPermissions() bool

BypassPermissions 报告是否处于「跳过权限确认」模式。

func DeleteCustomAgentFile added in v0.3.0 

func DeleteCustomAgentFile(path string) error

DeleteCustomAgentFile 删除一个 agent 文件；文件已不存在视作成功（对齐上游 deleteAgentFromFile 吞 ENOENT）。

func FireSessionEnd added in v0.24.0 

func FireSessionEnd(ctx context.Context, reason string)

FireSessionEnd 跑 SessionEnd hook（reason: exit/clear）并清掉本会话作用域注册的 hook （skill/agent frontmatter 装的），避免跨 /clear 泄漏到新会话。纯副作用、错误忽略。

func FireSessionStart added in v0.24.0 

func FireSessionStart(ctx context.Context, source string) (additionalContext, systemMessage string)

FireSessionStart 跑 SessionStart hook（source: startup/resume/clear）。返回 hook 注入的 额外上下文（调用方前缀到首条用户消息）与系统消息（展示给用户）。DisableAmbientConfig 时为 no-op。

func HasActiveGoal added in v0.9.0 

func HasActiveGoal() bool

HasActiveGoal 报告是否有活跃（未达成、未清除）的目标在驱动续轮。

func IsSessionMemoryEmpty added in v0.5.0 

func IsSessionMemoryEmpty(cwd, sessionID string) bool

IsSessionMemoryEmpty 判断 session memory 是否为空。对齐上游 isSessionMemoryEmpty： 内容 trim 后等于模板（trim 后）即视为空--模板本身没有实质信息。 早先 fundev 用"长度 ≤ 模板长度+100"近似判断，现改成精确 trim 比对，与上游一致。

func LoadSessionMemory added in v0.5.0 

func LoadSessionMemory(cwd, sessionID string) string

LoadSessionMemory 读取已有 session memory（不存在返回空串）。

func MaybeExtractSessionMemory added in v0.5.0 

func MaybeExtractSessionMemory(ctx context.Context, cwd, sessionID string, summary string)

MaybeExtractSessionMemory 在 compact 成功后触发会话记忆提炼：用一句 prompt 从 摘要 + 已有 memory（如存在）中生成更新版全文，然后落盘。提炼用**同步**只读子 agent 调模型（非后台），因为 compact 本身就有几秒延迟、多等一会儿提炼是可接受的。

提炼失败不报错：写一条日志（stderr）并静默跳过--丢了 memory 不要命，别卡住 compact。

func NeedsCompaction added in v0.5.0 

func NeedsCompaction(ctx context.Context, history []anthropic.Message) bool

NeedsCompaction 判断给定历史是否需要主动压缩（供外部调用方预判）。

func NotifyUser added in v0.8.0 

func NotifyUser(ctx context.Context, notifyType, title, message string)

NotifyUser 报告一次"需要用户注意"，跑 Notification hook。 异步执行、不等结果：调用点都在阻塞等待用户的关键路径上，通知失败/超时都不该影响主流程。

func ParseAgentToolList added in v0.8.0 

func ParseAgentToolList(raw string) []string

ParseAgentToolList 把 frontmatter 的 tools/disallowedTools 值切成工具名切片（去重、忽略空项）。 导出供 /agents 编辑器回填表单。

func PlanMode 

func PlanMode() bool

PlanMode 报告当前是否在计划模式。

func PlanModeEnabled added in v0.18.1 

func PlanModeEnabled() bool

PlanModeEnabled 报告计划模式总闸是否开启。

func RegisterAgentType added in v0.19.0 

func RegisterAgentType(spec AgentTypeSpec) error

RegisterAgentType 注册（或同名覆盖）一个内存子 agent 类型，供 Task 的 subagent_type 选用。 校验在注册期就做并报错——名字过 ValidateAgentType、description/SystemPrompt 非空、effort 非空时须为合法档位——别等运行期静默不生效（磁盘 agent 加载失败会打日志跳过，注册是显式 API，直接把错误交给宿主在 UI 上呈现）。

func Run 

func Run(ctx context.Context, history []anthropic.Message, emit func(Event))

Run 驱动整个多轮工具循环。history 是本次提交的初始历史（含最新的用户消息）。

func RunReturning 

func RunReturning(ctx context.Context, history []anthropic.Message, emit func(Event)) ([]anthropic.Message, error)

RunReturning 同 Run，但回传本回合结束时的**完整历史**（含本回合追加的 assistant / tool_result / steer / 续写提示等），可直接作为下一回合的 history 入参，无需从事件流重建。error 非 nil 表示本回合 以 Errored 收尾（同一错误也已作为 Errored 事件 emit 过）。供 SDK 的 *Session.Run 驱动；行为与 Run 一致。

func SaveNewCustomAgent added in v0.3.0 

func SaveNewCustomAgent(scope, cwd, name, description, model, systemPrompt string, extra AgentFileFields) (string, error)

SaveNewCustomAgent 在指定作用域新建一个 agent 文件；同名文件已存在则报错（对齐上游 saveAgentToFile 的 checkExists='wx'）。返回写入的文件路径。调用方应先用 ValidateAgentFields 校验。 新建时无既有字段可保留，extra 通常为空（除非调用方要写 tools 等）。

func SelectableAgentTools added in v0.8.0 

func SelectableAgentTools() (names []string, isWrite map[string]bool)

SelectableAgentTools 按固定顺序返回自定义 agent 可声明的工具名，并标出哪些是写类工具。 这份清单就是 subagentToolSet 的基础集（只读集 + 写类集），集中在此以免 UI 层另抄一份抄漏。

为什么写类工具值得在编辑器里显式标出：自定义 agent 的写能力**只由 tools: 是否列出写类工具决定** （见 typeAllowsWrite）——不勾就是只读 agent。这不是个纯过滤器，是那个开关。

func SessionID added in v0.5.0 

func SessionID(ctx context.Context) string

SessionID 取本回合的 hook 作用域 id；未注入回落 hooks.MainSession。 当 ctxFor 注入了真实 session ID（如 TUI 主循环），subagent 注入了子会话 id， 则各路径能区分本届会话与子 agent，hooks 注册/去重按正确作用域走。

func SessionMemoryPath added in v0.5.0 

func SessionMemoryPath(cwd, sessionID string) string

SessionMemoryPath 返回本届会话的 memory 文件路径。

func SetBypassPermissions 

func SetBypassPermissions(on bool)

SetBypassPermissions 开/关「跳过权限确认」模式（--dangerously-skip-permissions）。

func SetGoal added in v0.9.0 

func SetGoal(condition string)

SetGoal 设定（或替换）当前目标。条件为空时清除。设定即立即生效：下一轮收尾时开始评估。 新目标开始时清掉 lastAchieved：旧的"达成记录"不再相关，/goal 应看当前进度而非历史。

func SetPlanMode 

func SetPlanMode(on bool)

SetPlanMode 开/关计划模式。总闸关闭时忽略写入（保持恒关，防止宿主/命令绕过总闸）。

func SetPlanModeEnabled added in v0.18.1 

func SetPlanModeEnabled(on bool)

SetPlanModeEnabled 开/关计划模式总闸。默认关；宿主需要时显式开启。 关闭总闸时同步复位进程级 planMode（与 SetPlanMode 的写入互斥，杜绝交错残留）。 注意：回合态（turnPlanState，ctx 内）与 per-session 覆盖（RunOptions.PlanMode）不属于 进程级状态，这里无法复位——宿主不要在回合进行中翻转总闸；若必须翻，planModeActive 的 总闸判定会兜底（无覆盖时恒 false），但回合开头已注入的系统提示与工具表不会随之更新。

func Summarize 

func Summarize(ctx context.Context, history []anthropic.Message) (string, error)

Summarize 把一段对话历史压成摘要文本。压缩前触发 PreCompact hook：其副作用（如备份转录） 照常发生，若它返回 additionalContext（如"务必在摘要里保留 X"），就并进压缩指令一起发。

请求形态（对齐上游 services/compact/compact.ts streamCompactSummary 的缓存共享路径）：

  • **缓存共享路径**（前缀记录存在且调用方 history 与其结构一致时）：请求消息用**调用方的 history** 组装（契约：摘要的就是传入的历史，绝不静默替换成前缀记录）+ 追加摘要指令， system/tools 复用主对话的，并带 WithSkipCacheWrite（message 级断点移位到共享前缀末尾， 见 anthropic.messagesWithCacheShifted）——整段前缀命中主对话的 prompt cache，只有摘要 指令付全价，摘要请求生成的正文不写新缓存段（fire-and-forget）。
  • **拍平路径**（无前缀记录 / history 与前缀结构不一致，如进程刚起、宿主传整段历史或 自定义边界、反应式压缩传子集）：原行为——serializeHistory 拍平全史重述，全价但安全， 且摘要范围严格按调用方 history（缓存复用对不同 span 的 history 本就不成立）。 两条路径共用同一 ctx（model/thinking/max_tokens 与主对话一致，缓存 key 不漂移）。

预算门槛：usableRequestPrefix 门槛 4 保证只有「全量前缀放得进摘要预算」的前缀才走共享路径 （对齐上游 truncateHeadForPTLRetry 的意图——但用「放不进就走拍平」而不是「截头重发」： 截头后前缀与缓存不一致、全价且带全量 tools，比拍平截尾更贵）。若共享请求仍 PTL（估算偏差）， 回落拍平路径（自带 200k rune 截断）再试一次。

func SummarizeForCompact added in v0.5.1 

func SummarizeForCompact(ctx context.Context, history []anthropic.Message) (string, bool)

SummarizeForCompact 生成压缩摘要，封装 session memory 的注入与提炼，供外部压缩路径 （如 TUI 手动 /compact，它有自己的 boundary/keep 组装逻辑、不走 compactKeepLastRound）调用。 返回摘要文本与 ok；ok=false 表示生成失败（调用方照常报错/回退）。

逻辑：若有非空 session memory，用其（截断后）内容当摘要（注入，不调 API）；否则调 Summarize， 并在成功后用摘要更新 session memory（提炼）。这样 TUI 等外部路径与 agent 包内路径 （proactive/reactive）对 session memory 的处理一致--业务逻辑集中在 agent 包，UI 层不承担。

压缩成功即打开「刷新窗口」（refreshFrozenPrompts）：所有压缩路径（proactive/reactive/手动） 都经此汇聚，消息段缓存此刻已必然全断，是重读冻结注入快照的唯一免费时机。

func TruncateSessionMemoryForCompact added in v0.5.0 

func TruncateSessionMemoryForCompact(content string) (truncated string, wasTruncated bool)

TruncateSessionMemoryForCompact 截断 session memory 里超长的节，防 memory 把压缩后的 token 预算整个吃掉（对齐上游 truncateSessionMemoryForCompact）。 逐节扫描：某节内容（header 之后的行）粗估 token 超 sessionMemoryMaxSectionTokens 时， 在行边界处截断并补一行 "[... section truncated for length ...]" 标记。返回截断后内容与是否截过。

func UnregisterAgentType added in v0.19.0 

func UnregisterAgentType(name string) bool

UnregisterAgentType 注销一个内存注册的子 agent 类型，返回是否原本存在（宿主删除 agent 时调用）。

func UpdateCustomAgentFile added in v0.3.0 

func UpdateCustomAgentFile(path, name, description, model, systemPrompt string, extra AgentFileFields) error

UpdateCustomAgentFile 覆盖写一个已存在的 agent 文件（编辑保存用，路径已知）。 extra 用于保留编辑器不管理的字段（tools/disallowedTools/effort/color）；调用方应从磁盘读回这些 原始 frontmatter 行值并透传，否则保存会把它们清掉。

func ValidateAgentFields added in v0.3.0 

func ValidateAgentFields(name, description, systemPrompt string, otherNames []string) []string

ValidateAgentFields 校验新建/编辑 agent 的字段，返回所有阻断性错误（空=可保存）。 otherNames 是**除自身外**的现有 agent 名（用于查重）。对齐上游 validateAgent 的 name/description/ systemPrompt 分支；tools/disallowedTools/effort/color 由 frontmatter 透传，不做应用层校验。

func ValidateAgentType added in v0.3.0 

func ValidateAgentType(name string) string

ValidateAgentType 校验 agent 名格式，合法返回 ""，否则返回中文错误说明（对齐上游 validateAgentType）。

func WithAmbientEmit added in v0.24.0 

func WithAmbientEmit(ctx context.Context, f func(Event)) context.Context

WithAmbientEmit 注册回合外事件通道（facade Session.SetAmbientEmit 的底层接缝）。

func WithCompactFailures added in v0.5.0 

func WithCompactFailures(ctx context.Context, cf *CompactFailures) context.Context

WithCompactFailures 把跨回合失效计数器注入 ctx。

func WithManualCompact added in v0.8.0 

func WithManualCompact(ctx context.Context) context.Context

WithManualCompact 标记本次压缩由用户手动发起（/compact）。不标即视为自动压缩。 供 TUI 等外部压缩路径在调 SummarizeForCompact 前套上——这是"声明意图"，不是业务逻辑， 判断与使用都在 agent 包内（分层原则）。

func WithRunOptions 

func WithRunOptions(ctx context.Context, o RunOptions) context.Context

WithRunOptions 把 per-session 覆盖注入 ctx（随 Run 下沉）。供 SDK facade 的 *Session 构建每回合 ctx。

func WithSessionID added in v0.3.1 

func WithSessionID(ctx context.Context, id string) context.Context

WithSessionID 把本回合的 hook 作用域 id 注入 ctx（随 Run 下沉）。宿主/子 agent 用它把会话作用域 hook（skill/agent frontmatter 注册的）绑到正确的会话；未注入时回落 hooks.MainSession（进程主会话）。

func WithSteer 

func WithSteer(ctx context.Context, q *SteerQueue) context.Context

WithSteer 把 steering 队列放进 ctx，随 agent.Run 下沉（对齐 WithModel/WithBackend 的注入方式， 故不改 Run 签名）。nil 队列 = 不启用 steering。

Types

type AgentFileFields added in v0.5.0 

type AgentFileFields struct {
	Tools           string // tools frontmatter 原始行值（逗号分隔串；空=省略该行）
	DisallowedTools string // disallowedTools frontmatter 原始行值
	Effort          string
	Color           string
	Memory          string // memory frontmatter 原始行值（user/project/local；空=省略该行）
	Skills          string // skills 原始 YAML 值；可为单行或多行列表
	MaxTurns        string
	MCPServers      string // mcpServers 原始 YAML 值；保留多行内联定义
}

AgentFileFields 是写进 agent 文件 frontmatter 的全部字段。SaveNew/Update 透传它，使 /agents 编辑器 保存时**不丢失**编辑器不管理的字段（tools/disallowedTools/effort/color/hooks）：编辑器表单只填 name/description/model/systemPrompt，其余从磁盘原样带回（仅 systemPrompt 等被改写）。

func ReadAgentExtraFields added in v0.5.0 

func ReadAgentExtraFields(path string) (AgentFileFields, error)

ReadAgentExtraFields 读回一个 agent 文件里编辑器不管理的 frontmatter 字段（tools/disallowedTools/ effort/color）的**原始行值**，供 UpdateCustomAgentFile 透传——这样 /agents 编辑器改 description/系统提示 时不会把这些字段清掉。文件读失败（例如在列出与保存之间被外部删除）返回错误；字段缺省时返回空值。

type AgentType 

type AgentType struct {
	Name        string
	Description string
	Builtin     bool
}

AgentType 是一个可用子 agent 类型的摘要（供 /agents 展示）。

func AgentTypes 

func AgentTypes(cwd string) []AgentType

AgentTypes 返回所有可用子 agent 类型：内置三种 + 内存注册（宿主经 RegisterAgentType 注入， 同名优先）+ cwd 下磁盘发现的自定义类型。

type AgentTypeSpec added in v0.19.0 

type AgentTypeSpec struct {
	Name            string
	Description     string
	SystemPrompt    string
	Model           string   // 空/inherit=随父；别名/完整 ID
	Effort          string   // 空=随父；off/low/medium/high/xhigh
	Tools           []string // nil=全部；写类工具出现其中才可写
	DisallowedTools []string
}

AgentTypeSpec 描述一个宿主注册的内存子 agent 类型。字段语义与 .claude/agents frontmatter 一致：Model 空（或 "inherit"）=随父，别名经 ResolveModelAlias 解析；Effort 空串=随父， 非空须为合法档位（off/low/medium/high/xhigh）；Tools 为 nil=完整基础集（同 frontmatter 省略 tools:），列出写类工具才可写；DisallowedTools 从结果中剔除。

type BgTaskInfo 

type BgTaskInfo struct {
	ID, Description, Status, Output string
}

BgTaskInfo 是后台任务的只读快照（供 TUI 面板展示，不暴露内部锁/cancel）。

func BgTaskSnapshot 

func BgTaskSnapshot() []BgTaskInfo

BgTaskSnapshot 返回所有后台任务的快照，按 id 排序（与 BgTaskList 同序）。

type CompactFailures added in v0.5.0 

type CompactFailures struct{ N int }

CompactFailures 是跨回合的自动压缩失败计数器（指针共享，Session 持有一份）。

type Compacted added in v0.6.0 

type Compacted struct{ Summary string }

Compacted 上下文被自动压缩（proactive 主动 / reactive 反应式）。Summary 是本次生成的**原始**摘要文本 （不含"以下是摘要…"前缀）。持 History/Transcript 的端据此把「最后一个完整回合之前」的历史标记为已由 Summary 概括（SetCompaction），使自动压缩**持久生效**——否则每个超阈值回合都会重新摘要、历史无限增长、 落盘会话不断膨胀。纯显示端可忽略。回合开始（proactive）或 prompt_too_long 重试（reactive）时发出。

type Done 

type Done struct{}

Done 本次提交处理完毕。

type EditableAgent added in v0.3.0 

type EditableAgent struct {
	Name            string
	Description     string
	Model           string
	Tools           []string // 透传 frontmatter `tools:`（/agents 编辑器可多选编辑，见 tui/agentseditor.go）
	DisallowedTools []string
	Effort          string
	Color           string
	Memory          string
	Skills          []string
	MaxTurns        int
	MCPServers      string
	SystemPrompt    string
	Path            string                                    // 磁盘文件绝对路径
	Scope           string                                    // "project"（.claude/agents） | "user"（~/.claude/agents） | "fundev"（~/.fundev/agents）
	Hooks           map[string][]hooks.FrontmatterHookMatcher // 解析自 frontmatter `hooks:`（只读透传；/agents 编辑器不管理它，编辑保存会丢弃手写的 hooks 行）
}

EditableAgent 是一个可编辑的自定义 agent：在 customAgent 基础上带上磁盘文件路径与作用域， 供 /agents 编辑器增删改（对齐上游 agentFileUtils 的 getActualAgentFilePath / AgentDefinition.source）。

func ListEditableAgents added in v0.3.0 

func ListEditableAgents(cwd string) []EditableAgent

ListEditableAgents 按发现顺序（项目 .claude/agents → 用户 ~/.claude/agents → ~/.fundev/agents， 项目优先、按名去重）列出可编辑的自定义 agent，每项带真实文件路径。是 listCustomAgents 与 /agents 编辑器的共同数据源。

type Errored 

type Errored struct{ Err error }

Errored 出错。

type Event 

type Event interface {
	// contains filtered or unexported methods
}

Event 是 agent 发给上层的领域事件（框架无关）。

type ExtraTool 

type ExtraTool struct {
	Name          string
	Description   string
	InputSchema   json.RawMessage
	ReadOnly      bool // true → 进只读并发白名单（与 Read/Grep/Glob 同批并发跑）
	NeedsApproval bool // true → 执行前走 PermissionRequest
	Deferred      bool // true → 属「可延迟工具」：启用 ToolSearch 时其完整 schema 撤下、按需加载（对齐上游 shouldDefer）
	// Handler 执行工具；progress 在执行中回吐进度文本（→ 宿主当 Notice 渲染）。
	Handler func(ctx context.Context, input json.RawMessage, progress func(text string)) (ExtraToolOutput, error)
}

ExtraTool 是宿主注入的自定义工具（合进工具定义、在内置分发前命中）。

type ExtraToolOutput 

type ExtraToolOutput struct {
	Text    string
	Images  []anthropic.Block // 可选：结果里的 image 块（对齐现有工具结果的 image 附件）
	IsError bool
}

ExtraToolOutput 是自定义工具的产出。

type GeneratedAgent added in v0.4.0 

type GeneratedAgent struct {
	Identifier   string
	WhenToUse    string
	SystemPrompt string
}

GeneratedAgent 是生成出的 agent 定义（对齐上游 GeneratedAgent）。

func GenerateAgent added in v0.4.0 

func GenerateAgent(ctx context.Context, userPrompt string, existingIdentifiers []string) (*GeneratedAgent, error)

GenerateAgent 用自然语言 userPrompt 生成一个 agent 定义。existingIdentifiers 是已存在的名字 （提示模型避开）。一次性回合，无工具。返回解析并校验过的定义。

type Goal added in v0.9.0 

type Goal struct {
	Condition  string    // 完成条件（用户给的原文，≤4000 字符）
	Started    time.Time // 设定时刻
	Turns      int       // 已评估的轮数
	Tokens     int       // 累计 token（评估器+主轮，粗略）
	LastReason string    // 评估器最近一次给的理由（未满足时为何不满足 / 满足时为何满足）
	LastMet    bool      // 最近一次评估结果
	Done       bool      // 已达成并收尾（Done 后保留供 /goal 查看历史，但不再驱动续轮）
	DoneAt     time.Time // 达成时刻
}

Goal 是一个活跃目标的可观测状态。供 /goal 查看、footer 指示、评估器读写。

func ActiveGoal added in v0.9.0 

func ActiveGoal() *Goal

ActiveGoal 返回当前活跃目标的快照（nil=无）。读方拷一份，避免外部改到内部状态。

func ClearGoal added in v0.9.0 

func ClearGoal() *Goal

ClearGoal 清除当前目标（用户主动 /goal clear，或条件达成自动清）。

func LastAchievedGoal added in v0.9.0 

func LastAchievedGoal() *Goal

LastAchievedGoal 返回最近一次达成目标的快照（nil=从未达成）。达成后 currentGoal 清空， 供 /goal 在无活跃目标时查看"刚达成的那次"的条件、时长、轮数（对齐 Claude Code 文档行为）。

type Notice 

type Notice struct{ Text string }

Notice 系统提示（仅显示，不进 API 历史）。

type PermissionRequest 

type PermissionRequest struct {
	Title, Detail string
	Origin        string
	Options       []permission.Option
	Reply         chan permission.Reply
}

PermissionRequest 写类工具执行前的确认请求；用户经 Reply 通道回传选择（可含拒绝反馈）。 Origin 非空时标注请求来源（如"子 agent general-purpose"；主 agent 自己的请求为空）。

type PlanApproval added in v0.13.0 

type PlanApproval struct {
	Plan  string // 模型提交的实施计划文本
	Reply chan bool
}

PlanApproval 是模型调用 ExitPlanMode 提交计划后发给端的审批请求：端弹框展示计划、 用户批准（true）或拒绝（false）经 Reply 回传。放在 agent 包（而非 tools）： 因为要发事件并等待，tools 只返回字符串、发不了事件。

type PlanModeChanged added in v0.17.0 

type PlanModeChanged struct{ On bool }

PlanModeChanged 计划模式被模型经 EnterPlanMode 切换（On=true）时发出，供端同步 per-session 覆盖（Session.SetPlanMode）。进程级全局已同步翻转，端可只处理自己的会话状态。

type Question 

type Question struct {
	Question    string           `json:"question"`
	Header      string           `json:"header"`
	MultiSelect bool             `json:"multiSelect"`
	Options     []QuestionOption `json:"options"`
}

Question 是一道选择题。

type QuestionOption 

type QuestionOption struct {
	Label       string `json:"label"`
	Description string `json:"description"`
}

QuestionOption 是一道题的一个选项。

type QuestionRequest 

type QuestionRequest struct {
	Questions []Question
	Reply     chan []string
}

QuestionRequest 是 AskUserQuestion 发起的选择题；用户选完经 Reply 回传每题答案（nil=取消）。

type RetryScheduled 

type RetryScheduled struct {
	Attempt, Max int
	Delay        time.Duration
	Err          string
}

RetryScheduled 一次可重试的 API 错误即将退避重试（供 UI 显示"Ns 后重试(第 X/Y 次)"倒计时， 避免退避期间界面零提示、用户以为卡死）。Attempt=刚失败的第几次，Max=最大重试次数，Delay=退避时长。

type RunOptions 

type RunOptions struct {
	PlanMode             *bool                    // 非 nil 覆盖计划模式；nil 回落 planMode 全局
	BypassPermissions    *bool                    // 非 nil 覆盖跳过确认；nil 回落 bypassPermissions 全局
	SystemPrompt         func(base string) string // 非 nil 时对最终 system 做替换/追加
	ExtraTools           []ExtraTool              // 注入的自定义工具
	DisableTools         map[string]bool          // 摘掉的内置工具名（模型看不到）
	DelegatePermissions  bool                     // 委托全部权限裁决给宿主：不读 settings.json 的 permissions 规则
	DisableAmbientConfig bool                     // 不主动读 .claude/settings.json、.mcp.json、SKILL.md、.claude/agents
	// DisableCatastrophicGuard 关掉 catastrophic 命令的硬 deny 护栏。用**反向**语义（默认 false=护栏开）是
	// 为了让未注入任何覆盖的 TUI 路径（零值 RunOptions）仍保留护栏；facade 的 KeepCatastrophicGuard 会取反映射到此。
	DisableCatastrophicGuard bool
	// AutoCompact 控制本回合是否主动检查上下文 token 并自动压缩。nil → 启用（默认开启）。
	AutoCompact *bool
	// MaxTurns 限制单次提交内的工具循环轮数（对齐上游 --max-turns）。>0 精确生效，可放宽到超过
	// 默认护栏 maxIters（长链任务想多跑几轮就调大；想近似无上限就设足够大的数）；<=0 → 用默认护栏。
	MaxTurns int
	// EnableToolSearch 控制本回合是否启用「可延迟工具 + ToolSearch」机制。非 nil 覆盖；nil → 回落 env
	// FUNDEV_TOOL_SEARCH（默认关）。启用后 MCP / 标了 Deferred 的宿主工具的完整 schema 从初始工具表撤下，
	// 模型经 ToolSearch 按需加载后再调用（省上下文 token）。
	EnableToolSearch *bool
	// InteractionTimeout 是「等用户应答」类交互（权限确认 / AskUserQuestion / MCP 反问）的最大等待时长。
	// nil → 默认不超时（无限等待，defaultInteractionTimeout=0）；显式指向 0 → 同样不超时；
	// >0 → 自定义。超时后按「拒掉该次调用」收尾：拒绝/取消文本回给模型，回合不打断——无人值守宿主
	// 等不到应答时可用短超时实现快失败（而不让整条流程永久卡死）。默认不兜底：宿主漏接交互应直接暴露，
	// 而非伪装成「拒绝」误导模型（见 defaultInteractionTimeout 注释）。
	InteractionTimeout *time.Duration
}

RunOptions 是一次 Run 的 per-session 覆盖项。

type SteerQueue 

type SteerQueue struct {
	// contains filtered or unexported fields
}

SteerQueue 是 steering 消息队列。TUI（入队）与 agent 循环（取用）两个 goroutine 共享，故加锁。

func (*SteerQueue) Drain 

func (q *SteerQueue) Drain() []string

Drain 取出并清空当前所有排队消息（agent 循环每轮、以及 TUI 回合末调用）。空则返回 nil。

func (*SteerQueue) Push 

func (q *SteerQueue) Push(text string)

Push 追加一条排队消息（TUI 在流式态回车时调用）。

type TextDelta 

type TextDelta struct{ Text string }

TextDelta 助手文本增量。

type ThinkingBlock added in v0.20.0 

type ThinkingBlock struct {
	Text      string // 完整思考文本（合并全部 thinking_delta）
	Signature string // 签名（signature_delta；兼容端点常为空串，也照发）
}

ThinkingBlock 一条扩展思考块**定稿**：完整文本 + 签名。流式期间 ThinkingDelta 逐帧供展示， 本轮响应结束时（正文/工具调用定稿前）补发一条 ThinkingBlock——text/signature_delta 是独立 SSE 事件，完整块在 buildBlocks 才知道；只有拿到签名，上层才能把 thinking 随消息持久化并在 下轮原样回传（Anthropic 约定：在场 thinking 块必须带签名，兼容端点如 GLM 强制要求 reasoning 回传）。仅 thinking 无正文/工具调用的轮次（如 max_tokens 截断）不发。

type ThinkingDelta 

type ThinkingDelta struct{ Text string }

ThinkingDelta 扩展思考的增量（模型的推理过程，展示时会区分于正式回复）。

type ToolResult 

type ToolResult struct {
	ToolUseID, Content string
	Images             []anthropic.Block
}

ToolResult 一次工具执行的结果。Content 是展示文本；Images 是结果里的 image 块（如 Read 读图）， 供上层（TUI）随 item 存下、跨回合重建历史时带上，让工具结果里的图片在后续回合仍可见。

type ToolUse 

type ToolUse struct {
	ID, Name string
	Input    json.RawMessage
}

ToolUse 模型发起一次工具调用。

type Usage 

type Usage struct {
	Input, Output, CacheRead, CacheCreation, Context, Total int
}

Usage 报告刚结束的这次请求的 token 计量（供上层显示 / 驱动上下文压缩）。 Context = 喂进模型的上下文总量（输入+缓存读写）；Total 再加输出，是判断是否压缩的准确依据。

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.