Skip to content

Commit a7ef92e

Browse files
tt-a1itt-a1i
committed
docs: update agent framework documentation and configuration examples
- Renamed TOML file node to "TOML 配置文件" for clarity - Updated internal agent registration to use newline separator instead of HTML break tag - Replaced "LocalAgentExecutor" with "SubAgentScope" in architecture diagram - Simplified TOML configuration examples by removing redundant sections - Added markdown-based configuration format with structured fields - Enhanced remote agent documentation with clear usage instructions - Improved configuration example presentation with better formatting and explanations
1 parent 59786e6 commit a7ef92e

6 files changed

Lines changed: 408 additions & 289 deletions

File tree

‎src/pages/AgentFramework.tsx‎

Lines changed: 21 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -98,19 +98,19 @@ export function AgentFramework() {
9898

9999
const architectureChart = `flowchart TD
100100
subgraph Config["📁 配置层"]
101-
TOML[TOML 文件]
101+
TOML[TOML 配置文件]
102102
BUILTIN[内置 Agent]
103103
end
104104
105105
subgraph Registry["📋 AgentRegistry"]
106106
REG[注册与管理]
107107
REG --> |用户级| USER["~/.gemini/agents/"]
108108
REG --> |项目级| PROJ[".gemini/agents/"]
109-
REG --> |内置| BUILT[CodebaseInvestigator<br/>IntrospectionAgent]
109+
REG --> |内置| BUILT[CodebaseInvestigator\nIntrospectionAgent]
110110
end
111111
112112
subgraph Execution["⚡ 执行层"]
113-
LOCAL[LocalAgentExecutor]
113+
LOCAL[SubAgentScope]
114114
REMOTE[A2AClientManager]
115115
end
116116
@@ -274,10 +274,9 @@ export class AgentRegistry {
274274
}`;
275275

276276
const tomlConfigCode = `# ~/.gemini/agents/code-reviewer.toml
277-
278277
name = "code-reviewer"
279-
display_name = "Code Reviewer"
280278
description = "专业代码审查，检查最佳实践和潜在问题"
279+
tools = ["Read", "Grep", "Glob", "LSP"]
281280
282281
[prompts]
283282
system_prompt = """
@@ -289,34 +288,21 @@ You are a senior code reviewer. Analyze the code for:
289288
290289
Current model: \${activeModel}
291290
Today: \${today}
291+
292+
When asked to review code, focus on actionable feedback.
292293
"""
293-
query = "Review the following code: \${query}"
294294
295295
[model]
296-
model = "inherit" # 继承父级模型
297-
temperature = 0.3 # 较低温度，更精确
296+
model = "gemini-2.0-flash"
297+
temperature = 0.3
298298
299299
[run]
300-
max_turns = 10 # 最多 10 轮对话
301-
timeout_mins = 5 # 5 分钟超时
302-
303-
# 可用工具列表
304-
tools = [
305-
"Read",
306-
"Grep",
307-
"Glob",
308-
"LSP"
309-
]`;
300+
max_turns = 10
301+
timeout_mins = 5`;
310302

311-
const remoteAgentTomlCode = `# ~/.gemini/agents/remote-agents.toml
312-
313-
[[remote_agents]]
314-
name = "external-analyzer"
315-
agent_card_url = "https://example.com/.well-known/agent.json"
316-
317-
[[remote_agents]]
318-
name = "cloud-processor"
319-
agent_card_url = "https://api.example.com/agent-card"`;
303+
const remoteAgentNote = `注意：远程 Agent 通过 A2A (Agent-to-Agent) 协议调用，
304+
配置需要提供 agent_card_url 指向远程 Agent 的描述文件。
305+
详情参见 A2A 协议文档。`;
320306

321307
const executorCode = `// LocalAgentExecutor - 执行本地 Agent 的循环逻辑
322308
export class LocalAgentExecutor<TOutput> {
@@ -667,8 +653,9 @@ this.emitActivity('ERROR', { error: errorMessage, context: 'tool_call' });`;
667653

668654
<CodeBlock code={tomlConfigCode} language="toml" title="本地 Agent 配置示例" />
669655

670-
<div className="mt-6">
671-
<CodeBlock code={remoteAgentTomlCode} language="toml" title="远程 Agent 配置示例" />
656+
<div className="mt-6 bg-[var(--amber)]/10 rounded-lg p-4 border border-[var(--amber)]/30">
657+
<h4 className="text-[var(--amber)] font-bold mb-2">关于远程 Agent</h4>
658+
<p className="text-sm text-[var(--text-secondary)]">{remoteAgentNote}</p>
672659
</div>
673660

674661
<HighlightBox title="模板变量" variant="blue" className="mt-4">
@@ -693,10 +680,10 @@ this.emitActivity('ERROR', { error: errorMessage, context: 'tool_call' });`;
693680
<CodeBlock code={registryCode} language="typescript" title="registry.ts" />
694681

695682
<div className="mt-6 grid grid-cols-1 md:grid-cols-3 gap-4">
696-
<HighlightBox title="内置 Agent" variant="blue">
683+
<HighlightBox title="内置 Agent (2个)" variant="blue">
697684
<ul className="text-sm space-y-1">
698-
<li>• CodebaseInvestigator</li>
699-
<li>• IntrospectionAgent</li>
685+
<li>• <strong>CodebaseInvestigator</strong> - 代码库探索</li>
686+
<li>• <strong>IntrospectionAgent</strong> - 自省分析</li>
700687
<li>• 通过设置启用/禁用</li>
701688
</ul>
702689
</HighlightBox>
@@ -940,7 +927,7 @@ this.emitActivity('ERROR', { error: errorMessage, context: 'tool_call' });`;
940927
</tr>
941928
<tr className="border-b border-[var(--border-subtle)]/50">
942929
<td className="py-2 px-3 font-mono text-[var(--cyber-blue)] text-xs">agents/toml-loader.ts</td>
943-
<td className="py-2 px-3 text-[var(--text-secondary)]">TOML 配置解析和 Zod 验证</td>
930+
<td className="py-2 px-3 text-[var(--text-secondary)]">TOML 配置解析与验证</td>
944931
</tr>
945932
<tr className="border-b border-[var(--border-subtle)]/50">
946933
<td className="py-2 px-3 font-mono text-[var(--cyber-blue)] text-xs">agents/delegate-to-agent-tool.ts</td>
@@ -976,7 +963,7 @@ this.emitActivity('ERROR', { error: errorMessage, context: 'tool_call' });`;
976963

977964
<HighlightBox title="为什么 Agent 不能调用 delegate_to_agent?" variant="purple">
978965
<p className="text-sm">
979-
<strong>防止递归和复杂性</strong>：TOML 加载器会验证 tools 配置，
966+
<strong>防止递归和复杂性</strong>：SubagentManager 会验证 tools 配置，
980967
拒绝包含 delegate_to_agent 的 Agent 定义。这防止了 Agent 之间的递归调用，
981968
简化了执行模型和调试。
982969
</p>

‎src/pages/InteractionLoop.tsx‎

Lines changed: 47 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -413,7 +413,7 @@ const request = await prepareRequest(userParts, ideContextDelta);
413413
<div className="text-[var(--cyber-blue)] font-bold">packages/cli/src/ui/hooks/useGeminiStream.ts</div>
414414
<div className="pl-4 space-y-1 text-[var(--text-muted)]">
415415
<div>:786 - <span className="text-[var(--amber)]">submitQuery()</span> - 主循环入口</div>
416-
<div>:702 - <span className="text-[var(--amber)]">流事件处理循环</span> - 处理 13 种事件类型</div>
416+
<div>:702 - <span className="text-[var(--amber)]">流事件处理循环</span> - 处理 14 种事件类型</div>
417417
<div>:994 - <span className="text-[var(--amber)]">handleCompletedTools()</span> - Continuation 触发</div>
418418
<div>:488 - <span className="text-[var(--amber)]">getIdeContextDelta()</span> - IDE 上下文增量</div>
419419
</div>
@@ -457,7 +457,7 @@ const request = await prepareRequest(userParts, ideContextDelta);
457457
<MermaidDiagram chart={streamEventsChart} title="流事件处理流程" />
458458

459459
<div className="mt-4">
460-
<h5 className="text-[var(--text-primary)] font-semibold font-mono mb-2">13 种事件类型</h5>
460+
<h5 className="text-[var(--text-primary)] font-semibold font-mono mb-2">14 种事件类型 (GeminiEventType)</h5>
461461
<div className="overflow-x-auto">
462462
<table className="w-full text-sm">
463463
<thead>
@@ -479,29 +479,64 @@ const request = await prepareRequest(userParts, ideContextDelta);
479479
<td className="py-2 px-3">收集到队列，流结束后调度</td>
480480
</tr>
481481
<tr className="border-b border-[var(--border-subtle)]/50">
482-
<td className="py-2 px-3 font-mono text-[var(--terminal-green)]">Finished</td>
483-
<td className="py-2 px-3">响应完成</td>
484-
<td className="py-2 px-3">触发工具调度</td>
482+
<td className="py-2 px-3 font-mono text-[var(--terminal-green)]">ToolCallResponse</td>
483+
<td className="py-2 px-3">工具执行完成</td>
484+
<td className="py-2 px-3">结果进入对话历史</td>
485+
</tr>
486+
<tr className="border-b border-[var(--border-subtle)]/50">
487+
<td className="py-2 px-3 font-mono text-orange-400">ToolCallConfirmation</td>
488+
<td className="py-2 px-3">等待用户确认</td>
489+
<td className="py-2 px-3">暂停执行，显示确认 UI</td>
490+
</tr>
491+
<tr className="border-b border-[var(--border-subtle)]/50">
492+
<td className="py-2 px-3 font-mono text-[var(--text-muted)]">UserCancelled</td>
493+
<td className="py-2 px-3">用户取消操作</td>
494+
<td className="py-2 px-3">终止当前请求</td>
485495
</tr>
486496
<tr className="border-b border-[var(--border-subtle)]/50">
487497
<td className="py-2 px-3 font-mono text-red-400">Error</td>
488-
<td className="py-2 px-3">API 错误</td>
498+
<td className="py-2 px-3">API 或执行错误</td>
489499
<td className="py-2 px-3">重试或显示错误</td>
490500
</tr>
501+
<tr className="border-b border-[var(--border-subtle)]/50">
502+
<td className="py-2 px-3 font-mono text-[var(--purple)]">ChatCompressed</td>
503+
<td className="py-2 px-3">对话历史压缩</td>
504+
<td className="py-2 px-3">token 优化，保留上下文</td>
505+
</tr>
491506
<tr className="border-b border-[var(--border-subtle)]/50">
492507
<td className="py-2 px-3 font-mono text-[var(--purple)]">Thought</td>
493508
<td className="py-2 px-3">思考过程 (think mode)</td>
494509
<td className="py-2 px-3">记录但不加入历史</td>
495510
</tr>
496511
<tr className="border-b border-[var(--border-subtle)]/50">
497-
<td className="py-2 px-3 font-mono text-orange-400">TokenUsage</td>
498-
<td className="py-2 px-3">Token 使用统计</td>
499-
<td className="py-2 px-3">更新计数器</td>
512+
<td className="py-2 px-3 font-mono text-[var(--amber)]">MaxSessionTurns</td>
513+
<td className="py-2 px-3">达到会话轮次上限</td>
514+
<td className="py-2 px-3">终止会话</td>
515+
</tr>
516+
<tr className="border-b border-[var(--border-subtle)]/50">
517+
<td className="py-2 px-3 font-mono text-red-400">SessionTokenLimitExceeded</td>
518+
<td className="py-2 px-3">超过 token 上限</td>
519+
<td className="py-2 px-3">触发压缩或终止</td>
520+
</tr>
521+
<tr className="border-b border-[var(--border-subtle)]/50">
522+
<td className="py-2 px-3 font-mono text-[var(--terminal-green)]">Finished</td>
523+
<td className="py-2 px-3">响应完成</td>
524+
<td className="py-2 px-3">触发工具调度</td>
525+
</tr>
526+
<tr className="border-b border-[var(--border-subtle)]/50">
527+
<td className="py-2 px-3 font-mono text-orange-400">LoopDetected</td>
528+
<td className="py-2 px-3">检测到循环</td>
529+
<td className="py-2 px-3">中断并提示用户</td>
530+
</tr>
531+
<tr className="border-b border-[var(--border-subtle)]/50">
532+
<td className="py-2 px-3 font-mono text-[var(--cyber-blue)]">Citation</td>
533+
<td className="py-2 px-3">引用来源</td>
534+
<td className="py-2 px-3">附加到响应</td>
500535
</tr>
501536
<tr>
502-
<td className="py-2 px-3 font-mono text-[var(--text-muted)]">InputTokenCount</td>
503-
<td className="py-2 px-3">输入 token 数</td>
504-
<td className="py-2 px-3">缓存用于截断</td>
537+
<td className="py-2 px-3 font-mono text-[var(--text-muted)]">Retry</td>
538+
<td className="py-2 px-3">重试请求</td>
539+
<td className="py-2 px-3">重新发送 API 请求</td>
505540
</tr>
506541
</tbody>
507542
</table>

0 commit comments

Comments
 (0)