docs(cyrene): cmd/cyrene 存量英文注释中文化(22 个非测试文件,仅注释)
CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled
CI / Frontend (tsc + vite build) (push) Has been cancelled

- 四组并行完成:main/wire*.go、wire_capacity|channels|runtime、channels|persona_*|emotion|observability、
  voice|plugins|stream|skills|vision|subagent_tool|extractor|mcp|sessionread_tool|terminal_tool。
- 机械校验(git diff -U0 去 // 行与空行)仅剩 wire_frontend.go:84 一处行尾注释:代码前缀
  「\ta.gw = gw 」经 cat -A 与 HEAD 逐字节比对一致(allow 清单已声明)。
- 验收:隔离 worktree(HEAD + 本批 patch)go build/vet 绿、全树 58 包 ok、
  linux/amd64 + darwin/arm64 交叉编译绿;gofmt -l 干净。
- 备注:整树两次红均为负载敏感 flake(backthink / orchestration 的 timeout 类用例单独 -count=20 全过)。
This commit is contained in:
AskaEth committed 2026-10-04 16:58:06 +08:00
1 parent 5c2189efb0
commit 52f08dc343
22 files changed
+455 -586

No files matched your search

+21 -29
View File
@@ -16,25 +16,20 @@ import (
// L3 缓存 TTL 解析与 capacity_awaken 事件出口。它从 wire_runtime.go 拆出
// (AGENTS §10 文件 ≤500 行;wire.go 拆分建议同样适用于本文件)。
// buildCapacity constructs the awakened-capacity decider when enabled, or nil
// (which keeps the loop's default all-tools behavior). It is opt-in via
// CAPACITY_ENABLED; the allowed-set mapping comes from CAPACITY_TOOL_SETS and
// falls back to built-in defaults on a parse error.
// buildCapacity 在启用时构造唤醒式能力判定器;未启用则返回 nil(loop 保持默认的
// 「全工具」行为)。它由 CAPACITY_ENABLED 显式开启;允许集映射取自
// CAPACITY_TOOL_SETS,解析失败时回落到内置默认值。
//
// The model-assisted L3 layer (裁决 14.4.4) is a second, independent switch
// (CAPACITY_L3_ENABLED, default false): even with capacity on, L3 stays silent
// unless it was explicitly asked for, and its verdict cache TTL
// (CAPACITY_L3_CACHE_TTL, default 5m) is parsed here because the config loader
// only carries scalars.
// 模型辅助的 L3 层(裁决 14.4.4)是第二个、彼此独立的开关
// (CAPACITY_L3_ENABLED,默认 false):即使能力层已开,L3 仍保持静默,除非被
// 显式要求;其判定结果的缓存 TTL(CAPACITY_L3_CACHE_TTL,默认 5m)在此解析,
// 因为配置加载器只承载标量。
//
// The persona-level awakening override (裁决 14.4.3) enters the decision layer in
// two places. This function fills the *global* fallback (Config.Awakening) from the
// current main persona's YAML block (see defaultAwakening): it is what a persona
// declaring no block inherits. The per-turn value is resolved by awakeningFor,
// which the loop calls for every turn's own role through
// loop.Options.PersonaAwakening — without it, a non-default character's
// `awakening` block would be parsed, validated and then silently ignored
// (forbidden by design/01 §2.1).
// 人格级唤醒覆盖(裁决 14.4.3)分两处进入决策层。本函数填**全局**兜底
// (Config.Awakening),取自当前主角色 YAML 里的块(见 defaultAwakening):
// 未声明该块的人格继承的就是它。每个 turn 的取值由 awakeningFor 解析,loop 经
// loop.Options.PersonaAwakening 对该 turn 自己的角色调用它——没有它,非默认
// 角色的 `awakening` 块会被解析、校验,然后被静默忽略(design/01 §2.1 禁止)。
func (a *app) buildCapacity() *capacity.Decider {
if !a.cfg.Capacity.Enabled {
return nil
@@ -64,10 +59,9 @@ func (a *app) buildCapacity() *capacity.Decider {
return capacity.New(cfg, capacity.WithLogger(a.log))
}
// parseL3CacheTTL parses the CAPACITY_L3_CACHE_TTL duration string. An empty
// value selects the code default (5m, the landing suggestion of 裁决 14.4.4); an
// unparsable value is reported and falls back to the same default rather than
// silently disabling the cache.
// parseL3CacheTTL 解析 CAPACITY_L3_CACHE_TTL 这个时长字符串。空值选代码默认
// (5m,裁决 14.4.4 的落地建议);无法解析的值会告警并回落到同一默认,而不是
// 静默关掉缓存。
func parseL3CacheTTL(raw string, log *slog.Logger) time.Duration {
raw = strings.TrimSpace(raw)
if raw == "" {
@@ -82,9 +76,8 @@ func parseL3CacheTTL(raw string, log *slog.Logger) time.Duration {
return d
}
// parseCapacityToolSets decodes the CAPACITY_TOOL_SETS JSON map of
// state→allowed tool name list. A blank string yields nil (built-in defaults); a
// null value for a state means unrestricted (all tools).
// parseCapacityToolSets 解码 CAPACITY_TOOL_SETS 的 JSON 映射:态 → 允许的工具名
// 列表。空白串产出 nil(用内置默认);某态取 null 表示不受限(全部工具)。
func parseCapacityToolSets(raw string) (map[capacity.State][]string, error) {
if strings.TrimSpace(raw) == "" {
return nil, nil
@@ -186,11 +179,10 @@ func awakeningState(raw string) capacity.State {
}
}
// onCapacity is the loop's OnCapacity sink: it observes a capacity_awaken
// transition and pushes it to the Web UI (design/14 §5) as a `capacity_awaken`
// frame. The loop only emits on a real state transition (never every round), and
// the event carries the originating session id so it routes to that session, not
// globally. The payload is the frontend AwakenPayload {fromState,toState,tool}.
// onCapacity 是 loop 的 OnCapacity 出口:它观测一次 capacity_awaken 跃迁,并以
// `capacity_awaken` 帧推给 Web UI(design/14 §5)。loop 只在真实发生状态跃迁时
// 才发(绝非每轮都发);事件携带发起会话 id,因此路由到那个会话而非全局广播。
// 载荷是前端的 AwakenPayload {fromState,toState,tool}。
func (a *app) onCapacity(ev capacity.Event) {
logger.WithSource(a.log, "cmd/cyrene").Debug("capacity event",
"type", ev.Type, "from", ev.FromState, "to", ev.ToState,