Update docs for latest gemini-cli changes

Author: tt-a1i

src/pages/AgentFramework.tsx

@@ -34,7 +34,7 @@ function QuickSummary({ isExpanded, onToggle }: { isExpanded: boolean; onToggle:
           <div className="bg-[var(--bg-terminal)]/50 rounded-lg p-4 border-l-4 border-[var(--cyber-blue)]">
             <p className="text-[var(--text-primary)] font-medium">
               <span className="text-[var(--cyber-blue)] font-bold">一句话：</span>
-              可配置的子代理执行框架，通过 TOML 定义 Agent，支持本地执行和远程 A2A 调用
+              可配置的子代理执行框架，通过 Markdown + YAML frontmatter 定义 Agent，支持本地执行和远程 A2A 调用
             </p>
           </div>
 
@@ -53,7 +53,7 @@ function QuickSummary({ isExpanded, onToggle }: { isExpanded: boolean; onToggle:
               <div className="text-xs text-[var(--text-muted)]">配置层级</div>
             </div>
             <div className="bg-[var(--bg-card)] rounded-lg p-3 text-center border border-[var(--border-subtle)]">
-              <div className="text-2xl font-bold text-[var(--purple)]">2</div>
+              <div className="text-2xl font-bold text-[var(--purple)]">3</div>
               <div className="text-xs text-[var(--text-muted)]">内置 Agent</div>
             </div>
           </div>
@@ -63,7 +63,7 @@ function QuickSummary({ isExpanded, onToggle }: { isExpanded: boolean; onToggle:
             <h4 className="text-sm font-semibold text-[var(--text-muted)] mb-2">Agent 执行流程</h4>
             <div className="flex items-center gap-2 flex-wrap text-sm">
               <span className="px-3 py-1.5 bg-[var(--cyber-blue)]/20 text-[var(--cyber-blue)] rounded-lg border border-[var(--cyber-blue)]/30">
-                TOML 加载
+                Markdown frontmatter 加载
               </span>
               <span className="text-[var(--text-muted)]">→</span>
               <span className="px-3 py-1.5 bg-[var(--purple)]/20 text-[var(--purple)] rounded-lg border border-[var(--purple)]/30">
@@ -98,15 +98,15 @@ export function AgentFramework() {
 
   const architectureChart = `flowchart TD
     subgraph Config["📁 配置层"]
-      TOML[TOML 配置文件]
+      TOML[Markdown 配置文件]
       BUILTIN[内置 Agent]
     end
 
     subgraph Registry["📋 AgentRegistry"]
       REG[注册与管理]
       REG --> |用户级| USER["~/.gemini/agents/"]
       REG --> |项目级| PROJ[".gemini/agents/"]
-      REG --> |内置| BUILT[CodebaseInvestigator\nIntrospectionAgent]
+      REG --> |内置| BUILT[codebase_investigator\ncli_help\ngeneralist]
     end
 
     subgraph Execution["⚡ 执行层"]
@@ -252,15 +252,28 @@ export class AgentRegistry {
   }
 
   private loadBuiltInAgents(): void {
+    const investigatorSettings = this.config.getCodebaseInvestigatorSettings();
+    const cliHelpSettings = this.config.getCliHelpAgentSettings();
+    const agentsOverrides = this.config.getAgentsSettings().overrides ?? {};
+
     // CodebaseInvestigator - 代码库探索
-    if (this.config.getCodebaseInvestigatorSettings()?.enabled) {
+    if (
+      investigatorSettings?.enabled &&
+      agentsOverrides[CodebaseInvestigatorAgent.name]?.enabled !== false
+    ) {
       this.registerLocalAgent(CodebaseInvestigatorAgent);
     }
 
-    // IntrospectionAgent - 自省分析
-    if (this.config.getIntrospectionAgentSettings().enabled) {
-      this.registerLocalAgent(IntrospectionAgent);
+    // CLI Help - 文档问答
+    if (
+      cliHelpSettings.enabled &&
+      agentsOverrides[CliHelpAgent.name]?.enabled !== false
+    ) {
+      this.registerLocalAgent(CliHelpAgent(this.config));
     }
+
+    // Generalist - 通用代理（实验特性）
+    this.registerLocalAgent(GeneralistAgent(this.config));
   }
 
   // 获取 Agent 目录上下文（注入到系统提示词）
@@ -274,14 +287,22 @@ export class AgentRegistry {
   }
 }`;
 
-  const tomlConfigCode = `# ~/.gemini/agents/code-reviewer.toml
-name = "code-reviewer"
-description = "专业代码审查，检查最佳实践和潜在问题"
-tools = ["read_file", "search_file_content", "glob", "list_directory"]
+  const markdownConfigCode = `---
+kind: local
+name: code-reviewer
+description: 专业代码审查，检查最佳实践和潜在问题
+display_name: Code Reviewer
+tools:
+  - read_file
+  - search_file_content
+  - glob
+  - list_directory
 # 说明：内置工具使用 tool name（如 read_file）；MCP 工具用 server__tool 格式
-
-[prompts]
-system_prompt = """
+model: gemini-2.5-flash
+temperature: 0.3
+max_turns: 10
+timeout_mins: 5
+---
 You are a senior code reviewer. Analyze the code for:
 - Best practices and patterns
 - Potential bugs and issues
@@ -291,16 +312,7 @@ You are a senior code reviewer. Analyze the code for:
 Current model: \${activeModel}
 Today: \${today}
 
-When asked to review code, focus on actionable feedback.
-"""
-
-[model]
-model = "gemini-2.0-flash"
-temperature = 0.3
-
-[run]
-max_turns = 10
-timeout_mins = 5`;
+When asked to review code, focus on actionable feedback.`;
 
   const remoteAgentNote = `注意：远程 Agent 通过 A2A (Agent-to-Agent) 协议调用，
 配置需要提供 agent_card_url 指向远程 Agent 的描述文件。
@@ -559,7 +571,7 @@ this.emitActivity('ERROR', { error: errorMessage, context: 'tool_call' });`;
           Agent Framework 代理框架
         </h1>
         <p className="text-xl text-[var(--text-muted)]">
-          可配置的子代理执行框架 - TOML 驱动的 Agent 定义与执行
+          可配置的子代理执行框架 - Markdown frontmatter 驱动的 Agent 定义与执行
         </p>
       </div>
 
@@ -571,7 +583,7 @@ this.emitActivity('ERROR', { error: errorMessage, context: 'tool_call' });`;
       {/* 核心架构 */}
       <Layer title="核心架构">
         <p className="text-[var(--text-secondary)] mb-6">
-          Agent Framework 提供了一套完整的子代理系统，支持通过 TOML 配置文件定义 Agent，
+          Agent Framework 提供了一套完整的子代理系统，支持通过 Markdown + YAML frontmatter 定义 Agent，
           并在隔离的执行环境中运行。支持本地执行和远程 A2A (Agent-to-Agent) 调用。
         </p>
         <MermaidDiagram chart={architectureChart} />
@@ -652,14 +664,14 @@ this.emitActivity('ERROR', { error: errorMessage, context: 'tool_call' });`;
         </div>
       </Layer>
 
-      {/* TOML 配置示例 */}
-      <Layer title="TOML 配置示例">
+      {/* Markdown 配置示例 */}
+      <Layer title="Markdown 配置示例">
         <p className="text-[var(--text-secondary)] mb-4">
-          Agent 通过 TOML 文件定义，放置在 <code>~/.gemini/agents/</code> (用户级) 或
-          <code>.gemini/agents/</code> (项目级) 目录下。
+          Agent 通过 Markdown 文件 + YAML frontmatter 定义（文件必须以 <code>---</code> 开头），放置在
+          <code>~/.gemini/agents/</code> (用户级) 或 <code>.gemini/agents/</code> (项目级) 目录下（仅加载 <code>.md</code>）。
         </p>
 
-        <CodeBlock code={tomlConfigCode} language="toml" title="本地 Agent 配置示例" />
+        <CodeBlock code={markdownConfigCode} language="markdown" title="本地 Agent 配置示例" />
 
         <div className="mt-6 bg-[var(--amber)]/10 rounded-lg p-4 border border-[var(--amber)]/30">
           <h4 className="text-[var(--amber)] font-bold mb-2">关于远程 Agent</h4>
@@ -688,11 +700,11 @@ this.emitActivity('ERROR', { error: errorMessage, context: 'tool_call' });`;
         <CodeBlock code={registryCode} language="typescript" title="registry.ts" />
 
         <div className="mt-6 grid grid-cols-1 md:grid-cols-3 gap-4">
-          <HighlightBox title="内置 Agent (2个)" variant="blue">
+          <HighlightBox title="内置 Agent (3个)" variant="blue">
             <ul className="text-sm space-y-1">
-              <li>• <strong>CodebaseInvestigator</strong> - 代码库探索</li>
-              <li>• <strong>IntrospectionAgent</strong> - 自省分析</li>
-              <li>• 通过设置启用/禁用</li>
+              <li>• <strong>codebase_investigator</strong> - 代码库探索</li>
+              <li>• <strong>cli_help</strong> - CLI 文档问答</li>
+              <li>• <strong>generalist</strong> - 通用代理（实验）</li>
             </ul>
           </HighlightBox>
 
@@ -934,8 +946,8 @@ this.emitActivity('ERROR', { error: errorMessage, context: 'tool_call' });`;
                 <td className="py-2 px-3 text-[var(--text-secondary)]">LocalAgentExecutor - 本地 Agent 执行循环</td>
               </tr>
               <tr className="border-b border-[var(--border-subtle)]/50">
-                <td className="py-2 px-3 font-mono text-[var(--cyber-blue)] text-xs">agents/toml-loader.ts</td>
-                <td className="py-2 px-3 text-[var(--text-secondary)]">TOML 配置解析与验证</td>
+                <td className="py-2 px-3 font-mono text-[var(--cyber-blue)] text-xs">agents/agentLoader.ts</td>
+                <td className="py-2 px-3 text-[var(--text-secondary)]">Markdown frontmatter 解析与验证</td>
               </tr>
               <tr className="border-b border-[var(--border-subtle)]/50">
                 <td className="py-2 px-3 font-mono text-[var(--cyber-blue)] text-xs">agents/delegate-to-agent-tool.ts</td>
@@ -949,6 +961,14 @@ this.emitActivity('ERROR', { error: errorMessage, context: 'tool_call' });`;
                 <td className="py-2 px-3 font-mono text-[var(--cyber-blue)] text-xs">agents/codebase-investigator.ts</td>
                 <td className="py-2 px-3 text-[var(--text-secondary)]">CodebaseInvestigatorAgent 内置定义</td>
               </tr>
+              <tr className="border-b border-[var(--border-subtle)]/50">
+                <td className="py-2 px-3 font-mono text-[var(--cyber-blue)] text-xs">agents/cli-help-agent.ts</td>
+                <td className="py-2 px-3 text-[var(--text-secondary)]">CliHelpAgent 内置定义</td>
+              </tr>
+              <tr className="border-b border-[var(--border-subtle)]/50">
+                <td className="py-2 px-3 font-mono text-[var(--cyber-blue)] text-xs">agents/generalist-agent.ts</td>
+                <td className="py-2 px-3 text-[var(--text-secondary)]">GeneralistAgent 内置定义（experimental）</td>
+              </tr>
               <tr className="border-b border-[var(--border-subtle)]/50">
                 <td className="py-2 px-3 font-mono text-[var(--cyber-blue)] text-xs">agents/a2a-client-manager.ts</td>
                 <td className="py-2 px-3 text-[var(--text-secondary)]">A2AClientManager - 远程 Agent 通信</td>
@@ -971,7 +991,7 @@ this.emitActivity('ERROR', { error: errorMessage, context: 'tool_call' });`;
 
           <HighlightBox title="为什么 Agent 不能调用 delegate_to_agent?" variant="purple">
             <p className="text-sm">
-              <strong>防止递归和复杂性</strong>：toml-loader 会验证 tools 配置，
+              <strong>防止递归和复杂性</strong>：agentLoader 会验证 tools 配置，
               拒绝包含 delegate_to_agent 的 Agent 定义。这防止了 Agent 之间的递归调用，
               简化了执行模型和调试。
             </p>

src/pages/AgentSkills.tsx

@@ -44,7 +44,7 @@ export function AgentSkills() {
       <Layer title="技能发现（Discovery）" icon="🗂️">
         <p className="text-gray-300 mb-4">
           skills 启用后，<code>SkillManager</code> 会扫描 <code>*/SKILL.md</code> 并汇总为“可用技能清单”。
-          覆盖优先级为：<strong>Extension（最低） → User → Project（最高）</strong>（同名以 YAML frontmatter 的 <code>name</code> 为准）。
+          覆盖优先级为：<strong>Built-in（最低） → Extension → User → Workspace（最高）</strong>（同名以 YAML frontmatter 的 <code>name</code> 为准）。
         </p>
 
         <CodeBlock
@@ -62,22 +62,25 @@ getProjectSkillsDir(): string {
         <CodeBlock
           title="发现顺序与覆盖（skillManager.ts）"
           code={`// packages/core/src/skills/skillManager.ts
-// Precedence: Extensions (lowest) -> User -> Project (highest).
+// Precedence: Built-in (lowest) -> Extensions -> User -> Workspace (highest).
 async discoverSkills(storage: Storage, extensions: GeminiCLIExtension[] = []) {
   this.clearSkills();
 
-  // 1) Extension skills (lowest)
+  // 1) Built-in skills (lowest)
+  await this.discoverBuiltinSkills();
+
+  // 2) Extension skills
   for (const extension of extensions) {
     if (extension.isActive && extension.skills) {
       this.addSkillsWithPrecedence(extension.skills);
     }
   }
 
-  // 2) User skills
+  // 3) User skills
   const userSkills = await loadSkillsFromDir(Storage.getUserSkillsDir());
   this.addSkillsWithPrecedence(userSkills);
 
-  // 3) Project skills (highest, overrides)
+  // 4) Workspace skills (highest, overrides)
   const projectSkills = await loadSkillsFromDir(storage.getProjectSkillsDir());
   this.addSkillsWithPrecedence(projectSkills);
 }`}
@@ -168,18 +171,43 @@ You have access to the following specialized skills...
       <Layer title="用户侧管理（/skills + settings）" icon="🧰">
         <p className="text-gray-300 mb-4">
           Skills 目前属于实验特性：通过 <code>experimental.skills</code> 开启；通过 <code>skills.disabled</code> 禁用特定技能。
-          CLI 也提供 <code>/skills</code> 命令用于列出与启用/禁用（修改配置后需要重启生效）。
+          CLI 也提供 <code>/skills</code> 命令用于列出与启用/禁用/刷新（禁用/启用后建议 <code>/skills reload</code> 让本会话生效）。
         </p>
         <CodeBlock
-          title="配置项（docs/get-started/configuration.md）"
+          title="配置项（docs/cli/settings.md）"
           code={`experimental.skills: boolean  # Enable Agent Skills (experimental)
 skills.disabled: string[]      # List of disabled skills (restart required)`}
         />
         <CodeBlock
           title="/skills 命令（skillsCommand.ts）"
           code={`/skills list [nodesc]
+/skills list [nodesc] [all]
 /skills disable <name>
-/skills enable <name>`}
+/skills enable <name>
+/skills reload`}
+        />
+        <p className="text-xs text-gray-400 mt-2">
+          说明：<code>/skills list --all</code> 会展示内建 skills（例如 <code>skill-creator</code>），否则默认隐藏。
+        </p>
+      </Layer>
+
+      <Layer title="终端命令（gemini skills）" icon="🧪">
+        <p className="text-gray-300 mb-4">
+          除了 Slash Commands，CLI 还提供 <code>gemini skills</code> 子命令用于安装/卸载技能包（默认 user scope）。
+        </p>
+        <CodeBlock
+          title="gemini skills 管理"
+          code={`# 列出所有技能
+gemini skills list
+
+# 安装（Git / 本地 / .skill）
+gemini skills install https://github.com/my-org/my-skills.git
+gemini skills install /path/to/skill --scope workspace
+
+# 卸载/启用/禁用
+gemini skills uninstall my-skill
+gemini skills enable my-skill
+gemini skills disable my-skill --scope workspace`}
         />
       </Layer>
 

src/pages/ErrorHandling.tsx

@@ -1119,7 +1119,7 @@ function attemptJSONFix(
                   <code className="text-green-400">AI 自动处理</code>：
                   重新读取文件后重试
                 </td>
-                <td className="py-3 px-2 text-xs font-mono text-cyan-400">packages/core/src/tools/smart-edit.ts</td>
+                <td className="py-3 px-2 text-xs font-mono text-cyan-400">packages/core/src/tools/edit.ts</td>
               </tr>
 
               {/* 配置错误 */}

src/pages/Glossary.tsx

@@ -126,7 +126,7 @@ const glossaryTerms: Term[] = [
   {
     term: 'Skill',
     definition:
-      'Agent Skills（技能系统）：启用 experimental.skills 后，CLI 会从 ~/.gemini/skills 与 .gemini/skills 扫描 */SKILL.md；模型可通过 activate_skill 激活技能并获得 <ACTIVATED_SKILL> 指令注入；用户可用 /skills 列表/启用/禁用。',
+      'Agent Skills（技能系统）：启用 experimental.skills 后，CLI 会从 Built-in/Extension/用户/工作区的 skills 目录扫描 */SKILL.md；模型可通过 activate_skill 激活技能并获得 <ACTIVATED_SKILL> 指令注入；用户可用 /skills list/enable/disable/reload 管理。',
     category: 'extension',
     relatedPage: 'agent-skills',
   },
@@ -423,14 +423,14 @@ const glossaryTerms: Term[] = [
 
   // Editing
   {
-    term: 'SmartEdit',
-    definition: '智能编辑引擎，支持模糊匹配和自动修复。当 old_string 不完全匹配时尝试智能定位。',
+    term: 'Edit Tool (replace)',
+    definition: '编辑/替换引擎，支持精确、灵活空白、正则和 LLM 修复多策略匹配。',
     category: 'tool',
     relatedPage: 'smart-edit-anim',
   },
   {
-    term: 'LLMEditFixer',
-    definition: 'AI 辅助的编辑修复器，当 Edit 工具失败时调用 AI 分析并修复匹配问题。',
+    term: 'FixLLMEditWithInstruction',
+    definition: 'LLM 辅助的编辑修复器，当 replace 工具失败时生成新的 search/replace 以修复匹配问题。',
     category: 'tool',
     relatedPage: 'smart-edit-anim',
     example: '处理缩进差异、空白字符不匹配等常见问题',

src/pages/ModelAvailability.tsx

@@ -243,6 +243,13 @@ export function classifyFailureKind(error: unknown): FailureKind {
 
   const policyChainCode = `// packages/core/src/availability/policyCatalog.ts
 
+import {
+  DEFAULT_GEMINI_MODEL,
+  DEFAULT_GEMINI_FLASH_MODEL,
+  PREVIEW_GEMINI_MODEL,
+  PREVIEW_GEMINI_FLASH_MODEL,
+} from '../config/models.js';
+
 // 降级动作
 export type FallbackAction = 'silent' | 'prompt';
 
@@ -256,14 +263,14 @@ export interface ModelPolicy {
 
 // 默认策略链: Pro → Flash
 const DEFAULT_CHAIN: ModelPolicyChain = [
-  definePolicy({ model: 'gemini-2.5-pro' }),
-  definePolicy({ model: 'gemini-2.0-flash', isLastResort: true }),
+  definePolicy({ model: DEFAULT_GEMINI_MODEL }),
+  definePolicy({ model: DEFAULT_GEMINI_FLASH_MODEL, isLastResort: true }),
 ];
 
 // Preview 策略链
 const PREVIEW_CHAIN: ModelPolicyChain = [
-  definePolicy({ model: 'gemini-2.5-pro-preview' }),
-  definePolicy({ model: 'gemini-2.0-flash-preview', isLastResort: true }),
+  definePolicy({ model: PREVIEW_GEMINI_MODEL }),
+  definePolicy({ model: PREVIEW_GEMINI_FLASH_MODEL, isLastResort: true }),
 ];
 
 // 验证策略链
@@ -486,6 +493,9 @@ export function validateModelPolicyChain(chain: ModelPolicyChain): void {
           策略链定义了模型的优先级和故障转移规则。默认链：Pro → Flash，确保至少有一个 lastResort 模型。
         </p>
         <CodeBlock code={policyChainCode} language="typescript" title="policyCatalog.ts" />
+        <p className="text-[var(--text-muted)] text-sm mt-3">
+          Preview 模式启用时，策略链会切换到 Gemini 3 的 preview 模型（Pro/Flash）。
+        </p>
 
         <HighlightBox title="策略链验证规则" variant="blue" className="mt-4">
           <ul className="text-sm space-y-1">