夜雨聆风一、sessions_yield 工具
1.1 工具概述
功能：结束当前回合核心特性：
• 在 spawn 子 agent 后使用 • 接收子 agent 结果作为下一条消息 • 支持自定义消息 • 需要 onYield 回调支持
1.2 Schema 定义
位置：第 112197 行
constSessionsYieldToolSchema = Type.Object({ message: Type.Optional(Type.String()) });1.3 完整执行代码
位置：第 112199 行
functioncreateSessionsYieldTool(opts) {return {label: "Yield",name: "sessions_yield",description: "End your current turn. Use after spawning subagents to receive their results as the next message.",parameters: SessionsYieldToolSchema,execute: async (_toolCallId, args) => {// 1. 解析消息（可选）const message = readStringParam$1(args, "message") || "Turn yielded.";// 2. 检查会话上下文if (!opts?.sessionId) {returnjsonResult({status: "error",error: "No session context" }); }// 3. 检查 onYield 支持if (!opts?.onYield) {returnjsonResult({status: "error",error: "Yield not supported in this context" }); }// 4. 执行 yieldawait opts.onYield(message);// 5. 返回结果returnjsonResult({status: "yielded", message }); } };}1.4 执行流程图
sessions_yield 工具调用 ↓1. 解析消息（可选，默认"Turn yielded."） ↓2. 检查会话上下文（sessionId） ↓3. 检查 onYield 支持 ↓4. 执行 yield 回调 ↓5. 返回结果1.5 返回结果格式
成功：
{"status":"yielded","message":"Turn yielded."}失败（无会话上下文）：
{"status":"error","error":"No session context"}失败（不支持 yield）：
{"status":"error","error":"Yield not supported in this context"}1.6 使用示例
用户：创建子 agent 并等待结果
大模型操作：
// 1. 创建子 agent{"tool_call":{"name":"sessions_spawn","arguments":{"task":"分析这个文件","label":"文件分析"}}}// 2. 结束回合，等待结果{"tool_call":{"name":"sessions_yield","arguments":{"message":"等待子 agent 完成"}}}执行结果：
{"status":"yielded","message":"等待子 agent 完成"}下一条消息：子 agent 的完成结果自动作为用户的下一条消息。
二、session_status 工具
2.1 工具概述
功能：显示会话状态卡片（用量/时间/成本）核心特性：
• 等价于 /status命令• 支持模型覆盖（model=default 重置） • 显示 token 使用量、时间、成本 • 支持 A2A 会话可见性检查
2.2 Schema 定义
位置：第 107699 行
constSessionStatusToolSchema = Type.Object({sessionKey: Type.Optional(Type.String()),model: Type.Optional(Type.String())});2.3 会话解析函数
位置：第 107704 行
functionresolveSessionEntry(params) {const keyRaw = params.keyRaw.trim();if (!keyRaw) returnnull;const includeAliasFallback = params.includeAliasFallback ?? true;// 1. 解析内部会话键const internal = resolveInternalSessionKey({key: keyRaw,alias: params.alias,mainKey: params.mainKey,requesterInternalKey: params.requesterInternalKey });// 2. 构建候选键列表const candidates = [keyRaw];if (!keyRaw.startsWith("agent:")) { candidates.push(`agent:${DEFAULT_AGENT_ID}:${keyRaw}`); }if (includeAliasFallback && internal !== keyRaw) { candidates.push(internal); }if (includeAliasFallback && !keyRaw.startsWith("agent:")) {const agentInternal = `agent:${DEFAULT_AGENT_ID}:${internal}`;if (agentInternal !== `agent:main:${keyRaw}`) { candidates.push(agentInternal); } }if (includeAliasFallback && (keyRaw === "main" || keyRaw === "current")) {const defaultMainKey = buildAgentMainSessionKey({agentId: DEFAULT_AGENT_ID,mainKey: params.mainKey });if (!candidates.includes(defaultMainKey)) { candidates.push(defaultMainKey); } }// 3. 查找会话for (const key of candidates) {const entry = params.store[key];if (entry) {return { key, entry }; } }returnnull;}2.4 模型覆盖解析
位置：第 107764 行
asyncfunctionresolveModelOverride(params) {const raw = params.raw.trim();// 1. 空值或 default → 重置if (!raw) return { kind: "reset" };if (raw.toLowerCase() === "default") return { kind: "reset" };// 2. 获取当前模型配置const configDefault = resolveDefaultModelForAgent({cfg: params.cfg,agentId: params.agentId });const currentProvider = params.sessionEntry?.providerOverride?.trim() || configDefault.provider;const currentModel = params.sessionEntry?.modelOverride?.trim() || configDefault.model;// 3. 构建模型别名索引const aliasIndex = buildModelAliasIndex({cfg: params.cfg,defaultProvider: currentProvider });// 4. 加载模型目录const catalog = awaitloadModelCatalog({ config: params.cfg });// 5. 构建允许模型集合const allowed = buildAllowedModelSet({cfg: params.cfg, catalog,defaultProvider: currentProvider,defaultModel: currentModel,agentId: params.agentId });// 6. 解析模型引用const resolved = resolveModelRefFromString({ raw,defaultProvider: currentProvider, aliasIndex });if (!resolved) {thrownewError(`Unrecognized model "${raw}".`); }const key = modelKey(resolved.ref.provider, resolved.ref.model);// 7. 检查是否允许if (allowed.allowedKeys.size > 0 && !allowed.allowedKeys.has(key)) {thrownewError(`Model "${key}" is not allowed.`); }// 8. 检查是否是默认模型const isDefault = resolved.ref.provider === configDefault.provider && resolved.ref.model === configDefault.model;return {kind: "set",provider: resolved.ref.provider,model: resolved.ref.model, isDefault };}2.5 完整执行代码
位置：第 107799 行
functioncreateSessionStatusTool(opts) {return {label: "Session Status",name: "session_status",description: "Show a /status-equivalent session status card (usage + time + cost when available). Use for model-use questions (📊 session_status). Optional: set per-session model override (model=default resets overrides).",parameters: SessionStatusToolSchema,execute: async (_toolCallId, args) => {const params = args;const cfg = opts?.config ?? loadConfig();// 1. 解析会话上下文const { mainKey, alias, effectiveRequesterKey } = resolveSandboxedSessionToolContext({ cfg,agentSessionKey: opts?.agentSessionKey,sandboxed: opts?.sandboxed });const a2aPolicy = createAgentToAgentPolicy(cfg);const requesterAgentId = resolveAgentIdFromSessionKey(opts?.agentSessionKey ?? effectiveRequesterKey);const visibilityRequesterKey = effectiveRequesterKey.trim();// 2. 解析 sessionKeyconst sessionKeyParam = readStringParam$1(params, "sessionKey");const targetSessionKey = sessionKeyParam || opts?.agentSessionKey || effectiveRequesterKey;// 3. 解析会话const sessionEntry = resolveSessionEntry({keyRaw: targetSessionKey, alias, mainKey,requesterInternalKey: effectiveRequesterKey,includeAliasFallback: true,store: getSessionStore() });if (!sessionEntry) {returnjsonResult({status: "error",error: `Session not found: ${targetSessionKey}` }); }// 4. 解析模型覆盖const modelParam = readStringParam$1(params, "model");if (modelParam) {try {const modelOverride = awaitresolveModelOverride({raw: modelParam, cfg,agentId: requesterAgentId,sessionEntry: sessionEntry.entry });if (modelOverride.kind === "reset") {// 重置模型覆盖awaitclearModelOverride(sessionEntry.key); sessionEntry.entry.modelOverride = void0; sessionEntry.entry.providerOverride = void0; } else {// 设置模型覆盖awaitsetModelOverride(sessionEntry.key, {provider: modelOverride.provider,model: modelOverride.model }); sessionEntry.entry.modelOverride = modelOverride.model; sessionEntry.entry.providerOverride = modelOverride.provider; } } catch (err) {returnjsonResult({status: "error",error: err.message }); } }// 5. 构建状态卡片const entry = sessionEntry.entry;const status = {sessionKey: sessionEntry.key,agentId: requesterAgentId,model: entry.modelOverride || cfg.agents.defaults.model,provider: entry.providerOverride || cfg.agents.defaults.provider,thinking: entry.thinkingLevel || cfg.agents.defaults.thinking,verbose: entry.verboseLevel || cfg.agents.defaults.verbose,usage: {contextTokens: entry.contextTokens || 0,totalTokens: entry.totalTokens || 0,estimatedCostUsd: entry.estimatedCostUsd || 0 },timing: {startedAt: entry.startedAt,endedAt: entry.endedAt,runtimeMs: entry.runtimeMs },status: entry.status || "idle" };// 6. 格式化输出const lines = [` **Session Status**`,``,`**Session**: ${sessionEntry.key}`,`**Agent**: ${requesterAgentId}`,`**Model**: ${status.provider}/${status.model}`,`**Thinking**: ${status.thinking}`,`**Verbose**: ${status.verbose}`,``,`**Usage**:`,`- Context Tokens: ${formatTokenShort(status.usage.contextTokens) || '0'}`,`- Total Tokens: ${formatTokenShort(status.usage.totalTokens) || '0'}`,`- Estimated Cost: $${(status.usage.estimatedCostUsd || 0).toFixed(4)}`,``,`**Timing**:`,`- Started: ${status.timing.startedAt ? newDate(status.timing.startedAt).toLocaleString() : 'N/A'}`,`- Runtime: ${formatDurationCompact(status.timing.runtimeMs) || 'N/A'}`,``,`**Status**: ${status.status}` ];returnjsonResult({status: "ok",sessionKey: sessionEntry.key,card: lines.join("\n") }); } };}2.6 执行流程图
session_status 工具调用 ↓1. 解析会话上下文 ↓2. 解析 sessionKey（默认当前会话） ↓3. 解析会话条目 ├─ 构建候选键列表 ├─ 查找会话 └─ 返回会话条目 ↓4. 解析模型覆盖（如果提供） ├─ "default" → 重置 ├─ 解析模型引用 ├─ 检查是否允许 └─ 设置/重置覆盖 ↓5. 构建状态卡片 ├─ 会话信息 ├─ 模型信息 ├─ 使用量（tokens/成本） └─ 时间信息 ↓6. 格式化输出 ↓7. 返回结果2.7 返回结果格式
成功：
{"status":"ok","sessionKey":"main","card":" **Session Status**\n\n**Session**: main\n**Agent**: main\n**Model**: bailian/qwen3.5-plus\n..."}失败（会话不存在）：
{"status":"error","error":"Session not found: abc123"}失败（模型不允许）：
{"status":"error","error":"Model \"openai/gpt-4\" is not allowed."}2.8 使用示例
用户：查看当前会话状态
大模型返回：
{"tool_call":{"name":"session_status","arguments":{}}}执行结果：
{"status":"ok","sessionKey":"main","card":" **Session Status**\n\n**Session**: main\n**Agent**: main\n**Model**: bailian/qwen3.5-plus\n**Thinking**: high\n**Verbose**: false\n\n**Usage**:\n- Context Tokens: 50K\n- Total Tokens: 100K\n- Estimated Cost: $0.05\n\n**Timing**:\n- Started: 2026-03-29 21:00:00\n- Runtime: 2h\n\n**Status**: idle"}格式化输出：
**Session Status****Session**: main**Agent**: main**Model**: bailian/qwen3.5-plus**Thinking**: high**Verbose**: false**Usage**:- Context Tokens: 50K- Total Tokens: 100K- Estimated Cost: $0.05**Timing**:- Started: 2026-03-29 21:00:00- Runtime: 2h**Status**: idle三、关键机制对比
3.1 功能定位
| 用途 | ||
| 时机 | ||
| 效果 |
3.2 参数支持
| message | ||
| sessionKey | ||
| model |
3.3 依赖检查
| sessionId | ||
| onYield 回调 | ||
| 会话存在 |
四、相关工具
4.1 与 sessions_spawn 配合
// 1. 创建子 agentawaitsessions_spawn({ task: "..." });// 2. 结束回合，等待结果awaitsessions_yield({ message: "等待子 agent 完成" });// 3. 下一条消息自动是子 agent 的结果4.2 模型覆盖示例
// 切换到指定模型awaitsession_status({ model: "openai/gpt-4" });// 重置为默认模型awaitsession_status({ model: "default" });五、辅助函数
5.1 格式化时长
functionformatDurationCompact(valueMs) {if (!valueMs || !Number.isFinite(valueMs) || valueMs <= 0) return"n/a";const minutes = Math.max(1, Math.round(valueMs / 6e4));if (minutes < 60) return`${minutes}m`;const hours = Math.floor(minutes / 60);const minutesRemainder = minutes % 60;if (hours < 24) {return minutesRemainder > 0 ? `${hours}h${minutesRemainder}m` : `${hours}h`; }const days = Math.floor(hours / 24);const hoursRemainder = hours % 24;return hoursRemainder > 0 ? `${days}d${hoursRemainder}h` : `${days}d`;}5.2 格式化 token
functionformatTokenShort(value) {if (!value || !Number.isFinite(value) || value <= 0) return;const n = Math.floor(value);if (n < 1000) return`${n}`;if (n < 1e6) return`${(n / 1000).toFixed(1)}K`;if (n < 1e9) return`${(n / 1e6).toFixed(1)}M`;return`${(n / 1e9).toFixed(1)}B`;}
