host

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: May 24, 2026 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	CoCreateProgressThinking = "thinking"
	CoCreateProgressReply    = "reply"
)

CoCreateProgressKind 标识流式回调的内容类型。

View Source 
const StreamClearSentinel = "\x00\x00CLEAR\x00\x00"

StreamClearSentinel 通过 streamCh 单条发送以示意"清空当前流式 round"。 不再用独立 clearCh —— 双通道无序导致 ✻ header 时常落到上一个 round 末尾。

Variables

This section is empty.

Functions

func BuildStartPrompt 

func BuildStartPrompt(prompt string) string

BuildStartPrompt 将用户需求包装为 Coordinator 的启动 prompt。

func ReplayDeltaText 

func ReplayDeltaText(item domain.RuntimeQueueItem) string

ReplayDeltaText 从运行时队列项中提取可回放的流式文本。

Types

type AgentCacheStat added in v0.3.1 

type AgentCacheStat struct {
	Role            string
	Input           int
	Output          int
	CacheRead       int
	CacheWrite      int
	Cost            float64
	Saved           float64
	CacheCapable    bool
	RecentCacheRead int
	RecentInput     int
	RecentSamples   int
}

AgentCacheStat 是单个 agent 的缓存命中累计（投影到左栏）。 HitRate = CacheRead / Input；Input 在 litellm 层已统一为"含 CacheRead"语义。

CacheCapable 用来区分两种 0% 命中：

  • true → 模型支持 prompt cache，0% 是 prompt 设计差或前缀不稳定，需要优化
  • false → 模型/provider 不支持 prompt cache，0% 是预期，不必排查

Recent* 是滑动窗（最近 N 次调用）的命中数据，对比累计可识别"前期拖累"vs"稳态低命中"。

type AgentContextSnapshot 

type AgentContextSnapshot struct {
	Tokens          int
	ContextWindow   int
	Percent         float64
	Scope           string
	Strategy        string
	ActiveMessages  int
	SummaryMessages int
	CompactedCount  int
	KeptCount       int
}

AgentContextSnapshot 是 Agent 上下文使用情况。

type AgentSnapshot 

type AgentSnapshot struct {
	Name             string
	State            string
	TaskID           string
	TaskKind         string
	Summary          string
	Tool             string
	Turn             int
	Context          AgentContextSnapshot
	RecentProjection AgentContextSnapshot
	UpdatedAt        time.Time
}

AgentSnapshot 是 Agent 状态的展示投影。

type AgentUsage added in v0.3.1 

type AgentUsage struct {
	Role            string
	Input           int
	Output          int
	CacheRead       int
	CacheWrite      int
	Cost            float64
	Saved           float64
	CacheCapable    bool
	RecentCacheRead int
	RecentInput     int
	RecentSamples   int
}

AgentUsage 是一个 agent 的累计用量快照（向 UI 暴露）。

type CoCreateMessage 

type CoCreateMessage struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

CoCreateMessage 是共创对话的消息。

type CoCreateReply 

type CoCreateReply struct {
	Message     string
	Prompt      string
	Ready       bool
	Suggestions []string
	Raw         string
}

CoCreateReply 是共创对话的 LLM 回复。Raw 保留模型完整四段原文， 用于写回 history 让下一轮模型看到自己上一轮的 [DRAFT]，从而真正在 已有草稿上累积更新（仅 Message 不含 [DRAFT]，会导致模型每轮凭对话重新归纳）。 Suggestions 是 AI 主动给的"接下来你可能想说"，用户卡壳时按数字键一键填入输入框。

type Event 

type Event struct {
	ID         string    // 同一次调用的开始/结束共用；非调用事件为空
	Time       time.Time // 首次发出时间（开始时刻）
	FinishedAt time.Time // 零值 = 进行中；非零 = 已完成
	Failed     bool      // 已完成但失败（仅完成态有意义）
	Category   string    // DISPATCH / TOOL / SYSTEM / REVIEW / CHECK / ERROR / CONTEXT
	Agent      string    // 产生事件的 agent
	Summary    string
	Level      string        // info / warn / error / success
	Depth      int           // 0 = coordinator 层, 1 = sub-agent 层
	Duration   time.Duration // 完成时的执行耗时
}

Event 是 TUI 消费的结构化事件。

对于 TOOL / DISPATCH 两类调用事件，同一次调用的开始与结束共用一个 ID： 开始时先发 FinishedAt 为零值的事件（TUI 渲染为"进行中"样式）； 结束时再发一条同 ID 的事件，填入 FinishedAt + Duration（+ Failed）， TUI 按 ID 定位原行原地更新，避免"开始一行、完成又一行"的冗余。

SYSTEM / ERROR / CONTEXT 等非调用类事件 ID 为空，每条独立追加。

func (Event) Running added in v0.1.2 

func (e Event) Running() bool

Running 返回事件是否处于进行中。 仅调用类事件（有 ID 的 TOOL / DISPATCH）可能进行中；其它类型总是返回 false。

type Host 

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

Host 是运行时薄外壳。 职责：启动/恢复/干预注入/事件投影/模型管理。 不做任何调度决策，不做空闲续跑。

func New 

func New(cfg bootstrap.Config, bundle assets.Bundle) (*Host, error)

New 创建 Host。

func (*Host) Abort 

func (h *Host) Abort() bool

Abort 暂停当前 coordinator。

func (*Host) AskUser 

func (h *Host) AskUser() *tools.AskUserTool

func (*Host) Close 

func (h *Host) Close()

Close 终止 coordinator 并关闭事件通道。

Usage 持久化语义：先取消 autoSaveLoop（它自行 flush 最后一次 dirty 状态）， 再补一次同步 SaveNow 收尾。已知缺口：AbortSilent 之后若仍有 in-flight LLM 调用回来，触发的 OnMessage → Record 会更新内存但**不会被持久化**。这部分 "最末几百 token" 的丢失在下次启动时会由 session jsonl replay 自动补回。

func (*Host) CoCreateStream 

func (h *Host) CoCreateStream(ctx context.Context, history []CoCreateMessage, onProgress func(kind, text string)) (CoCreateReply, error)

func (*Host) ConfiguredModels 

func (h *Host) ConfiguredModels(provider string) []string

func (*Host) ConfiguredProviders 

func (h *Host) ConfiguredProviders() []string

func (*Host) Continue 

func (h *Host) Continue(text string) error

Continue 用指定 prompt 继续。停机后用户在输入框输入时调用。

func (*Host) CurrentModelSelection 

func (h *Host) CurrentModelSelection(role string) (string, string, bool)

func (*Host) Dir 

func (h *Host) Dir() string

func (*Host) Done 

func (h *Host) Done() <-chan struct{}

func (*Host) Events 

func (h *Host) Events() <-chan Event

func (*Host) Export added in v0.4.0 

func (h *Host) Export(ctx context.Context, opts exp.Options) (*exp.Result, error)

Export 导出已完成章节为外部文件（当前仅支持 TXT）。

与 ImportFrom 不同：导出是只读操作（不动 Progress / Checkpoint）， 因此**不要求 Coordinator 空闲**——写作中途也可以随时导出"现阶段成品"。 只读到 Progress.CompletedChapters + 章节终稿 + 大纲 + premise 的一致快照。

func (*Host) ImportFrom added in v0.3.0 

func (h *Host) ImportFrom(ctx context.Context, opts imp.Options) (<-chan imp.Event, error)

ImportFrom 启动一次外部小说反推导入：切分 → 反推 foundation → 逐章分析落盘。 与 Coordinator 互斥；导入完成后调用方可立即 Resume() 续写。 返回的事件通道由 imp.Run 关闭，调用方负责消费（满则丢弃以防阻塞分析协程）。

func (*Host) ReplayQueue 

func (h *Host) ReplayQueue(afterSeq int64) ([]domain.RuntimeQueueItem, error)

func (*Host) Resume 

func (h *Host) Resume() (string, error)

Resume 恢复模式：从 checkpoint + progress 生成 resume prompt 并启动。

func (*Host) Snapshot 

func (h *Host) Snapshot() UISnapshot

func (*Host) Start 

func (h *Host) Start(prompt string) error

Start 新建模式：初始化进度并启动 coordinator 长循环。

func (*Host) StartPrepared 

func (h *Host) StartPrepared(promptText string) error

StartPrepared 使用已编排完成的启动 prompt 开始创作。

func (*Host) Steer 

func (h *Host) Steer(text string)

Steer 提交用户干预。

func (*Host) Stream 

func (h *Host) Stream() <-chan string

func (*Host) SwitchModel 

func (h *Host) SwitchModel(role, provider, model string) error

type OutlineSnapshot 

type OutlineSnapshot struct {
	Chapter   int
	Title     string
	CoreEvent string
}

OutlineSnapshot 是大纲条目的展示摘要。

type TaskSnapshot 

type TaskSnapshot struct {
	ID        string
	Kind      string
	Owner     string
	Title     string
	Status    string
	Chapter   int
	Volume    int
	Arc       int
	Summary   string
	Tool      string
	OutputRef string
	UpdatedAt time.Time
}

TaskSnapshot 是任务状态的展示投影（从事件流投影，非事实层）。

type UISnapshot 

type UISnapshot struct {
	Provider           string
	NovelName          string
	ModelName          string
	ModelContextWindow int // 当前默认模型的上下文窗口（随 /model 切换实时解析）
	Style              string
	RuntimeState       string // idle / running / pausing / paused / completed
	StatusLabel        string
	Phase              string
	Flow               string
	CurrentChapter     int
	TotalChapters      int
	CompletedCount     int
	TotalWordCount     int
	InProgressChapter  int
	PendingRewrites    []int
	RewriteReason      string
	PendingSteer       string
	RecoveryLabel      string
	IsRunning          bool
	Agents             []AgentSnapshot
	Tasks              []TaskSnapshot

	// 上下文
	ContextTokens         int
	ContextWindow         int
	ContextPercent        float64
	ContextScope          string
	ContextStrategy       string
	ProjectionTokens      int
	ProjectionWindow      int
	ProjectionPercent     float64
	ProjectionStrategy    string
	ProjectionCompacted   int
	ProjectionKept        int
	ContextActiveMessages int
	ContextSummaryCount   int
	ContextCompactedCount int
	ContextKeptCount      int

	// 累计用量（整个会话，跨所有 agent 与模型切换）
	TotalInputTokens      int
	TotalOutputTokens     int
	TotalCacheReadTokens  int
	TotalCacheWriteTokens int
	TotalCostUSD          float64
	TotalSavedUSD         float64 // 因 CacheRead 命中省下的美元（相对全按非缓存输入价计费）

	// 缓存诊断
	OverallCacheCapable    bool // 至少一个 role 跑过支持 prompt cache 的模型（区分"未启用"和"0% 命中"）
	OverallRecentCacheRead int  // 滑动窗最近 N 次的 cacheRead 总和
	OverallRecentInput     int  // 滑动窗最近 N 次的 input 总和
	OverallRecentSamples   int  // 滑动窗内的样本数（≤ recentSampleCap）

	// MissingAssistantUsage > 0 通常意味着上游 streaming 没按 OpenAI
	// stream_options.include_usage 协议发 final usage chunk（自建 proxy 常见），
	// 导致 UsageTracker 收不到任何累计数据。UI 据此明示用户排查 backend，
	// 不要让用户误以为是缓存模块本身坏了。
	MissingAssistantUsage int

	// 缓存 per-role 维度，按 CacheRead 降序，已过滤未消费 token 的 role
	CachePerAgent []AgentCacheStat

	// 基础设定
	Premise          string
	Outline          []OutlineSnapshot
	Characters       []string
	SupportingCount  int      // 配角名册中的次要角色总数
	RecentSupporting []string // 最近活跃的次要角色（最多 5 个，按 LastSeenChapter 倒序）
	Layered          bool
	CurrentVolumeArc string
	NextVolumeTitle  string
	CompassDirection string
	CompassScale     string

	// 详情
	LastCommitSummary  string
	LastReviewSummary  string
	LastCheckpointName string
	RecentSummaries    []string
}

UISnapshot 是 TUI 渲染所需的聚合状态快照。

type UsageTracker added in v0.1.2 

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

UsageTracker 累计整个会话所有 agent 的 LLM 输入/输出 token 与美元成本。

工作机制：

  • 每次 agent 的 OnMessage 回调触发时调用 Record(agentName, msg)
  • agentName 映射到 role（architect_* 归一为 architect），查 ModelSet 当前该 role 绑定的模型
  • 用 models.DefaultRegistry 查模型价格，按非缓存输入/输出/缓存读/缓存写四项累乘
  • 注册表无此模型时，退回 msg.Usage.Cost.Total（provider 自带，可能为 0）
  • 模型热切换（/model）后续消息自动按新模型算价，旧消息保留旧成本

同时维护 per-role 维度（writer/editor/architect/coordinator）：

  • 累计命中数据 → 整体优化效果
  • 滑动窗最近 N 次 → 区分前期拖累 vs 稳态低命中
  • CacheCapable 标记 → 区分"未启用"和"真的 0% 命中"

线程安全。

func NewUsageTracker added in v0.1.2 

func NewUsageTracker(set *bootstrap.ModelSet, store *storepkg.Store) *UsageTracker

func (*UsageTracker) LoadFromStore added in v0.4.0 

func (t *UsageTracker) LoadFromStore() (bool, error)

LoadFromStore 从 store.Usage 读取持久化的快照并回填到内存。返回 true 表示 成功加载到了一份非空（schema 匹配）的状态；false 表示无文件或不可用，调用方 应继续走 session replay 一次性回填。

func (*UsageTracker) MissingAssistantUsage added in v0.3.1 

func (t *UsageTracker) MissingAssistantUsage() int

MissingAssistantUsage 返回累计"收到 assistant 消息但 Usage 为 nil"的次数。 大于 0 通常意味着上游 streaming 没发 OpenAI 的 final usage chunk， UI 据此显示提示而非误以为缓存模块本身坏了。

func (*UsageTracker) OverallCacheCapable added in v0.3.1 

func (t *UsageTracker) OverallCacheCapable() bool

OverallCacheCapable 整体是否至少经过一次已知支持 cache 的模型。

func (*UsageTracker) OverallRecent added in v0.3.1 

func (t *UsageTracker) OverallRecent() (cacheRead, input, samples int)

OverallRecent 返回滑动窗内（≤ recentSampleCap 次）的 cacheRead 总和、input 总和、样本数。

func (*UsageTracker) PerAgent added in v0.3.1 

func (t *UsageTracker) PerAgent() []AgentUsage

PerAgent 返回各 role 累计用量。结果按 CacheRead 数量降序，未消费过 token 的 role 跳过。

func (*UsageTracker) Record added in v0.1.2 

func (t *UsageTracker) Record(agentName string, msg agentcore.AgentMessage)

Record 把一条 agent 消息分发到累加 / 诊断两条路径。

累加只看 Usage 是否存在——"哪条消息带 Usage" 是 agentcore/litellm adapter 装配细节（上游协议把 usage 放在响应顶层），未来装配规则变了也不用动这里。 诊断要求 Role=Assistant 且 Content 非空，避免 AbortMsg / 异常恢复 / tool / user 消息污染 missingAssistantUsage 计数。

func (*UsageTracker) ReplaySessions added in v0.4.0 

func (t *UsageTracker) ReplaySessions(rootDir string) (int, error)

ReplaySessions 扫 meta/sessions/coordinator.jsonl 与 meta/sessions/agents/*.jsonl， 把每条 assistant 消息的 usage 重新累加到 tracker。返回回填条数。

调用约束：仅在 meta/usage.json 缺失（首次升级或 schema 变更）时调用一次，做 历史数据回填。日常持久化走 SaveNow / autoSaveLoop。

已知精度损失：session log 里没记"当时这条消息用的是哪个模型"。回放时只能拿 当前 ModelSet 给每个 role 反推单价；如果运行中切过模型，历史 cost 会和真实 账单有差。Token 数本身是精确的——回放后即便 cost 估算偏差，也胜过完全没有累计。

func (*UsageTracker) SaveNow added in v0.4.0 

func (t *UsageTracker) SaveNow() error

SaveNow 立刻把当前 snapshot 落盘。autoSaveLoop / Close 路径都通过它写。

func (*UsageTracker) SavedUSD added in v0.3.1 

func (t *UsageTracker) SavedUSD() float64

SavedUSD 返回因缓存命中节省的累计美元数。

func (*UsageTracker) Snapshot added in v0.4.0 

func (t *UsageTracker) Snapshot() domain.UsageState

Snapshot 拷贝当前累计状态为可序列化的 domain.UsageState。 滑动窗 samples 不进 snapshot——它是短期诊断窗口，跨进程意义不大。

func (*UsageTracker) StartAutoSave added in v0.4.0 

func (t *UsageTracker) StartAutoSave(ctx context.Context)

StartAutoSave 起一个 goroutine，监听 saveCh + debounce 落盘。ctx done 前会 把最后一次未保存的状态 flush 出去。Close 通过 cancel ctx 触发 flush + 退出。

func (*UsageTracker) Totals added in v0.1.2 

func (t *UsageTracker) Totals() (cost float64, input, output, cacheRead, cacheWrite int)

Totals 返回累计总量的快照。

Source Files

View all Source files

Directories

Path Synopsis
Package exp 实现已完成章节的导出能力。
 Package exp 实现已完成章节的导出能力。
Package flow 实现垂类路由：Host 根据事实决定下一个调哪个子代理做什么。
 Package flow 实现垂类路由：Host 根据事实决定下一个调哪个子代理做什么。
Package imp 实现外部小说章节的导入与反推。
 Package imp 实现外部小说章节的导入与反推。

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.