@wwkit/freetoken 1.0.1

package/client/src/data/docs/agent.js

@@ -0,0 +1,1002 @@
+// Agent 子模块：Tool Calling 全流程详解（基于真实 opencode agent 数据）
+import { builtinTools } from './builtin-tools.js'
+
+export default {
+  id: 'agent',
+  name: 'Agent',
+  badge: 'Tool Call',
+  tagline: '大语言模型 Agent 模式：工具调用全流程',
+  description:
+    '当 Chat 接口携带 tools 参数时，大语言模型进入 Agent 模式——模型不再直接回答问题，而是决定调用哪些工具、传入什么参数，拿到工具执行结果后再生成最终回复。本节使用 opencode agent 的真实工具定义和接口数据，展示 tool 从选择到执行的完整流程。',
+
+  // ── 工具定义格式 ──
+  toolDefs: {
+    title: '工具定义格式',
+    description:
+      'tools 数组中每个元素描述一个可供模型调用的工具。模型根据工具的 name 和 description 决定是否调用，根据 parameters JSON Schema 构造调用参数。',
+    tools: [
+      {
+        type: 'function',
+        function: {
+          name: 'bash',
+          description:
+            'Executes a given bash command in a persistent shell session with optional timeout.',
+          parameters: {
+            type: 'object',
+            properties: {
+              command: {
+                type: 'string',
+                description: 'The command to execute',
+              },
+              workdir: {
+                type: 'string',
+                description: 'The working directory to run the command in',
+              },
+              timeout: {
+                type: 'integer',
+                description: 'Optional timeout in milliseconds',
+              },
+            },
+            required: ['command'],
+          },
+        },
+      },
+      {
+        type: 'function',
+        function: {
+          name: 'read',
+          description: 'Read a file or directory from the local filesystem.',
+          parameters: {
+            type: 'object',
+            properties: {
+              filePath: {
+                type: 'string',
+                description: 'The absolute path to the file to read',
+              },
+              offset: {
+                type: 'integer',
+                description: 'The line number to start reading from (1-indexed)',
+              },
+              limit: {
+                type: 'integer',
+                description: 'The maximum number of lines to read',
+              },
+            },
+            required: ['filePath'],
+          },
+        },
+      },
+      {
+        type: 'function',
+        function: {
+          name: 'edit',
+          description: 'Performs exact string replacements in files.',
+          parameters: {
+            type: 'object',
+            properties: {
+              filePath: {
+                type: 'string',
+                description: 'The absolute path to the file to modify',
+              },
+              oldString: {
+                type: 'string',
+                description: 'The text to replace',
+              },
+              newString: {
+                type: 'string',
+                description: 'The text to replace it with',
+              },
+            },
+            required: ['filePath', 'oldString', 'newString'],
+          },
+        },
+      },
+      {
+        type: 'function',
+        function: {
+          name: 'glob',
+          description: 'Fast file pattern matching tool that works with any codebase size.',
+          parameters: {
+            type: 'object',
+            properties: {
+              pattern: {
+                type: 'string',
+                description: 'The glob pattern to match files against',
+              },
+              path: {
+                type: 'string',
+                description: 'The directory to search in',
+              },
+            },
+            required: ['pattern'],
+          },
+        },
+      },
+      {
+        type: 'function',
+        function: {
+          name: 'grep',
+          description: 'Fast content search tool that works with any codebase size.',
+          parameters: {
+            type: 'object',
+            properties: {
+              pattern: {
+                type: 'string',
+                description: 'The regex pattern to search for in file contents',
+              },
+              include: {
+                type: 'string',
+                description: 'File pattern to include in the search',
+              },
+            },
+            required: ['pattern'],
+          },
+        },
+      },
+    ],
+    notes: [
+      '每个工具的 parameters 遵循 JSON Schema 规范，模型据此构造合法参数',
+      'description 是模型选择工具的核心依据——描述越清晰，工具选择越准确',
+      'required 数组标注必填参数，模型必须为这些参数生成值',
+      '当模型返回 tool_calls 时，content 字段通常为 null——模型此时不生成自然语言文本，而是表达"我需要先调用工具"。部分模型也会在 content 中附带一段思考说明（如"让我先查看文件内容"），但 content 为 null 是主流行为，客户端应兼容处理',
+      '工具结果必须以 role: "tool" 消息回传，并携带对应的 tool_call_id。如果错误地使用 role: "user" 包装工具结果，大多数 OpenAI 兼容模型会报 400 错误（消息角色序列不合法），因为模型期望在 assistant 的 tool_calls 之后紧跟 role: "tool" 消息。少数模型可能不报错但会丢失工具结果的语义关联，导致模型"看不到"执行结果而重复调用同一工具或直接胡编答案',
+      '示例 2 的并行多工具调用和示例 3 的多轮工具调用均为模型自主决策，而非客户端指令——客户端在每次请求中只传 messages + tools，不指定"请并行调用"或"请分两轮调用"。是否一次返回多个 tool_calls、是否在拿到结果后继续调用下一个工具，完全由模型根据任务语义推理决定。客户端唯一能施加的影响是 tool_choice 参数："auto"（默认，模型自主决定）、"required"（强制必须调用工具）、"none"（禁止调用），但具体调用哪个工具、几个工具、分几轮，始终是模型的决策',
+    ],
+  },
+
+  // ── 示例列表 ──
+  examples: [
+    // 示例 1：单工具调用
+    {
+      id: 'single-tool',
+      title: '示例 1：单工具调用（bash）',
+      scenario: '用户让 agent 列出当前项目的文件结构',
+      description:
+        '最基础的 Agent 交互：模型收到用户问题后，判断需要执行 shell 命令，调用 bash 工具，拿到输出后组织成自然语言回复。',
+      steps: [
+        {
+          step: 1,
+          type: 'user-message',
+          title: '用户提问',
+          label: 'User',
+          labelType: 'primary',
+          content:
+            '帮我看一下当前项目的 client 目录下有哪些文件？',
+        },
+        {
+          step: 2,
+          type: 'request',
+          title: '请求（携带 tools 定义）',
+          label: 'Request',
+          labelType: 'info',
+          description:
+            '客户端将用户消息和可用工具列表一起发送给模型。模型分析后决定调用 bash 工具。',
+          code: `POST /v1/chat/completions
+Authorization: Bearer sk-xxx
+
+{
+  "model": "maas-glm-5.1-zhipu",
+  "messages": [
+    {
+      "role": "user",
+      "content": "帮我看一下当前项目的 client 目录下有哪些文件？"
+    }
+  ],
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "bash",
+        "description": "Executes a given bash command in a persistent shell session.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "command": { "type": "string", "description": "The command to execute" }
+          },
+          "required": ["command"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "read",
+        "description": "Read a file or directory from the local filesystem.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "filePath": { "type": "string", "description": "The absolute path" }
+          },
+          "required": ["filePath"]
+        }
+      }
+    }
+  ],
+  "tool_choice": "auto"
+}`,
+          codeLang: 'json',
+        },
+        {
+          step: 3,
+          type: 'tool-call',
+          title: '模型返回 tool_calls',
+          label: 'Model',
+          labelType: 'warning',
+          description:
+            '模型没有直接回答，而是返回 tool_calls，指定调用 bash 工具，参数为 ls 命令。finish_reason 为 "tool_calls" 表示需要执行工具。',
+          code: `{
+  "id": "chatcmpl-a1b2c3d4",
+  "object": "chat.completion",
+  "model": "maas-glm-5.1-zhipu",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": null,
+        "tool_calls": [
+          {
+            "id": "call_abc123",
+            "type": "function",
+            "function": {
+              "name": "bash",
+              "arguments": "{\\"command\\": \\"ls -la client/\\"}"
+            }
+          }
+        ]
+      },
+      "finish_reason": "tool_calls"
+    }
+  ],
+  "usage": { "prompt_tokens": 156, "completion_tokens": 28, "total_tokens": 184 }
+}`,
+          codeLang: 'json',
+        },
+        {
+          step: 4,
+          type: 'execution',
+          title: '工具执行',
+          label: 'Tool',
+          labelType: 'success',
+          description:
+            '客户端解析 tool_calls，提取工具名 bash 和参数 { command: "ls -la client/" }，在本地执行该命令。',
+          toolName: 'bash',
+          toolInput: `ls -la client/`,
+          toolOutput: `total 24
+drwxr-xr-x  3 user user 4096 Sep 22 10:00 .
+drwxr-xr-x  8 user user 4096 Sep 22 10:00 ..
+-rw-r--r--  1 user user  412 Sep 22 10:00 index.html
+drwxr-xr-x  2 user user 4096 Sep 22 10:00 public/
+drwxr-xr-x  5 user user 4096 Sep 22 10:00 src/
+-rw-r--r--  1 user user  892 Sep 22 10:00 vite.config.js`,
+        },
+        {
+          step: 5,
+          type: 'tool-result',
+          title: '工具结果回传',
+          label: 'Tool Result',
+          labelType: 'success',
+          description:
+            '客户端将工具执行结果以 role: "tool" 消息追加到 messages 数组，连同之前的对话一起再次请求模型。',
+          code: `POST /v1/chat/completions
+Authorization: Bearer sk-xxx
+
+{
+  "model": "maas-glm-5.1-zhipu",
+  "messages": [
+    {
+      "role": "user",
+      "content": "帮我看一下当前项目的 client 目录下有哪些文件？"
+    },
+    {
+      "role": "assistant",
+      "content": null,
+      "tool_calls": [
+        {
+          "id": "call_abc123",
+          "type": "function",
+          "function": {
+            "name": "bash",
+            "arguments": "{\\"command\\": \\"ls -la client/\\"}"
+          }
+        }
+      ]
+    },
+    {
+      "role": "tool",
+      "tool_call_id": "call_abc123",
+      "content": "total 24\\ndrwxr-xr-x  3 user user 4096 Sep 22 10:00 .\\ndrwxr-xr-x  8 user user 4096 Sep 22 10:00 ..\\n-rw-r--r--  1 user user  412 Sep 22 10:00 index.html\\ndrwxr-xr-x  2 user user 4096 Sep 22 10:00 public/\\ndrwxr-xr-x  5 user user 4096 Sep 22 10:00 src/\\n-rw-r--r--  1 user user  892 Sep 22 10:00 vite.config.js"
+    }
+  ],
+  "tools": [ /* ... 同上 ... */ ]
+}`,
+          codeLang: 'json',
+        },
+        {
+          step: 6,
+          type: 'final-response',
+          title: '模型最终回复',
+          label: 'Final',
+          labelType: 'primary',
+          description: '模型根据工具返回的文件列表，组织成自然语言回复给用户。',
+          code: `{
+  "id": "chatcmpl-e5f6g7h8",
+  "object": "chat.completion",
+  "model": "maas-glm-5.1-zhipu",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": "client 目录下有以下文件和子目录：\\n\\n- **index.html** — HTML 入口文件\\n- **public/** — 静态资源目录\\n- **src/** — 源代码目录（包含 components、views 等）\\n- **vite.config.js** — Vite 构建配置文件"
+      },
+      "finish_reason": "stop"
+    }
+  ]
+}`,
+          codeLang: 'json',
+        },
+      ],
+    },
+
+    // 示例 2：并行多工具调用
+    {
+      id: 'parallel-tools',
+      title: '示例 2：并行多工具调用（read + glob）',
+      scenario: '用户让 agent 查看项目配置并找到所有 Vue 页面组件',
+      description:
+        '模型可以在一次响应中返回多个 tool_calls，客户端并行执行这些工具后将所有结果一起回传。这展示了 Agent 模式的并行能力。',
+      steps: [
+        {
+          step: 1,
+          type: 'user-message',
+          title: '用户提问',
+          label: 'User',
+          labelType: 'primary',
+          content:
+            '帮我看一下 package.json 的内容，并列出所有 .vue 文件。',
+        },
+        {
+          step: 2,
+          type: 'request',
+          title: '请求（携带 tools 定义）',
+          label: 'Request',
+          labelType: 'info',
+          description:
+            '请求中携带 read、glob 等工具定义。模型分析后决定同时调用 read（读 package.json）和 glob（找 .vue 文件）。',
+          code: `POST /v1/chat/completions
+Authorization: Bearer sk-xxx
+
+{
+  "model": "maas-glm-5.1-zhipu",
+  "messages": [
+    {
+      "role": "user",
+      "content": "帮我看一下 package.json 的内容，并列出所有 .vue 文件。"
+    }
+  ],
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "read",
+        "description": "Read a file from the local filesystem.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "filePath": { "type": "string", "description": "The absolute path" }
+          },
+          "required": ["filePath"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "glob",
+        "description": "Fast file pattern matching tool.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "pattern": { "type": "string", "description": "Glob pattern" }
+          },
+          "required": ["pattern"]
+        }
+      }
+    }
+  ],
+  "tool_choice": "auto"
+}`,
+          codeLang: 'json',
+        },
+        {
+          step: 3,
+          type: 'tool-call',
+          title: '模型返回多个 tool_calls（并行）',
+          label: 'Model',
+          labelType: 'warning',
+          description:
+            '模型在一次响应中返回两个 tool_calls：read 读取 package.json，glob 查找所有 .vue 文件。两个调用无依赖关系，可并行执行。',
+          code: `{
+  "id": "chatcmpl-i9j0k1l2",
+  "object": "chat.completion",
+  "model": "maas-glm-5.1-zhipu",
+  "choices": [
+    {
+      "index": 0,
+      "message": {
+        "role": "assistant",
+        "content": null,
+        "tool_calls": [
+          {
+            "id": "call_def456",
+            "type": "function",
+            "function": {
+              "name": "read",
+              "arguments": "{\\"filePath\\": \\"/usr1/wwkit-v1.0.x/packages/freetoken/package.json\\"}"
+            }
+          },
+          {
+            "id": "call_ghi789",
+            "type": "function",
+            "function": {
+              "name": "glob",
+              "arguments": "{\\"pattern\\": \\"client/src/**/*.vue\\"}"
+            }
+          }
+        ]
+      },
+      "finish_reason": "tool_calls"
+    }
+  ]
+}`,
+          codeLang: 'json',
+        },
+        {
+          step: 4,
+          type: 'execution',
+          title: '工具并行执行',
+          label: 'Tools',
+          labelType: 'success',
+          description: '客户端并行执行两个工具调用，互不阻塞。',
+          parallelTools: [
+            {
+              toolName: 'read',
+              toolInput: `filePath: /usr1/wwkit-v1.0.x/packages/freetoken/package.json`,
+              toolOutput: `{
+  "name": "freetoken",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": { "freetoken": "cli/index.js" },
+  "main": "src/index.js",
+  "dependencies": {
+    "express": "^4.18.0",
+    "vue": "^3.4.0",
+    "element-plus": "^2.7.0",
+    "axios": "^1.6.0"
+  }
+}`,
+            },
+            {
+              toolName: 'glob',
+              toolInput: `pattern: client/src/**/*.vue`,
+              toolOutput: `client/src/App.vue
+client/src/components/ChatBox.vue
+client/src/components/CodeBlock.vue
+client/src/components/DetailBlock.vue
+client/src/components/PageHeader.vue
+client/src/views/AdminModelsView.vue
+client/src/views/FreeModelsView.vue
+client/src/views/HarnessView.vue
+client/src/views/HomeView.vue
+client/src/views/ProxyView.vue
+client/src/views/TokenMarketView.vue`,
+            },
+          ],
+        },
+        {
+          step: 5,
+          type: 'tool-result',
+          title: '工具结果回传（多条）',
+          label: 'Tool Results',
+          labelType: 'success',
+          description:
+            '客户端将两个工具的结果分别以 role: "tool" 消息追加到 messages，tool_call_id 对应各自的调用 ID。',
+          code: `POST /v1/chat/completions
+Authorization: Bearer sk-xxx
+
+{
+  "model": "maas-glm-5.1-zhipu",
+  "messages": [
+    { "role": "user", "content": "帮我看一下 package.json 的内容，并列出所有 .vue 文件。" },
+    {
+      "role": "assistant",
+      "content": null,
+      "tool_calls": [
+        { "id": "call_def456", "type": "function", "function": { "name": "read", "arguments": "{\\"filePath\\": \\".../package.json\\"}" } },
+        { "id": "call_ghi789", "type": "function", "function": { "name": "glob", "arguments": "{\\"pattern\\": \\"client/src/**/*.vue\\"}" } }
+      ]
+    },
+    {
+      "role": "tool",
+      "tool_call_id": "call_def456",
+      "content": "{ \\"name\\": \\"freetoken\\", \\"version\\": \\"1.0.0\\", ... }"
+    },
+    {
+      "role": "tool",
+      "tool_call_id": "call_ghi789",
+      "content": "client/src/App.vue\\nclient/src/components/ChatBox.vue\\n...（共 11 个 .vue 文件）"
+    }
+  ],
+  "tools": [ /* ... */ ]
+}`,
+          codeLang: 'json',
+        },
+        {
+          step: 6,
+          type: 'final-response',
+          title: '模型最终回复',
+          label: 'Final',
+          labelType: 'primary',
+          description: '模型综合两个工具的结果，给出结构化回复。',
+          code: `{
+  "choices": [
+    {
+      "message": {
+        "role": "assistant",
+        "content": "## package.json 摘要\\n\\n- **包名**: freetoken v1.0.0\\n- **类型**: ESM (type: module)\\n- **入口**: src/index.js\\n- **核心依赖**: express, vue 3, element-plus, axios\\n\\n## Vue 文件列表（共 11 个）\\n\\n**页面组件 (views/)**:\\n- AdminModelsView.vue — 模型管理\\n- FreeModelsView.vue — 免费模型\\n- HarnessView.vue — Harness 工具\\n- HomeView.vue — 首页\\n- ProxyView.vue — 代理方案\\n- TokenMarketView.vue — Token 市场\\n\\n**公共组件 (components/)**:\\n- App.vue, ChatBox.vue, CodeBlock.vue, DetailBlock.vue, PageHeader.vue"
+      },
+      "finish_reason": "stop"
+    }
+  ]
+}`,
+          codeLang: 'json',
+        },
+      ],
+    },
+
+    // 示例 3：多轮工具调用
+    {
+      id: 'multi-turn',
+      title: '示例 3：多轮工具调用（read → edit）',
+      scenario: '用户让 agent 读取文件并修改其中的内容',
+      description:
+        '真实 Agent 场景中，模型经常需要先读取文件内容，基于内容决定下一步操作。本例展示 read → edit 的多轮工具调用链：第一轮模型调用 read 获取文件内容，第二轮基于内容调用 edit 完成修改。',
+      steps: [
+        {
+          step: 1,
+          type: 'user-message',
+          title: '用户提问',
+          label: 'User',
+          labelType: 'primary',
+          content:
+            '读取 client/src/router/index.js，把路由 /token-market 的组件改成 DocsView。',
+        },
+        {
+          step: 2,
+          type: 'request',
+          title: '第一轮请求',
+          label: 'Request #1',
+          labelType: 'info',
+          description: '模型收到请求后，需要先看到文件内容才能知道如何修改。',
+          code: `POST /v1/chat/completions
+Authorization: Bearer sk-xxx
+
+{
+  "model": "maas-glm-5.1-zhipu",
+  "messages": [
+    {
+      "role": "user",
+      "content": "读取 client/src/router/index.js，把路由 /token-market 的组件改成 DocsView。"
+    }
+  ],
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "read",
+        "description": "Read a file from the local filesystem.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "filePath": { "type": "string", "description": "The absolute path" }
+          },
+          "required": ["filePath"]
+        }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "edit",
+        "description": "Performs exact string replacements in files.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "filePath": { "type": "string", "description": "The file to modify" },
+            "oldString": { "type": "string", "description": "Text to replace" },
+            "newString": { "type": "string", "description": "Replacement text" }
+          },
+          "required": ["filePath", "oldString", "newString"]
+        }
+      }
+    }
+  ],
+  "tool_choice": "auto"
+}`,
+          codeLang: 'json',
+        },
+        {
+          step: 3,
+          type: 'tool-call',
+          title: '第一轮：模型调用 read',
+          label: 'Model #1',
+          labelType: 'warning',
+          description: '模型选择先调用 read 工具读取文件内容，而非直接调用 edit（因为它还不知道文件的确切内容）。',
+          code: `{
+  "choices": [
+    {
+      "message": {
+        "role": "assistant",
+        "content": null,
+        "tool_calls": [
+          {
+            "id": "call_jkl012",
+            "type": "function",
+            "function": {
+              "name": "read",
+              "arguments": "{\\"filePath\\": \\"/usr1/wwkit-v1.0.x/packages/freetoken/client/src/router/index.js\\"}"
+            }
+          }
+        ]
+      },
+      "finish_reason": "tool_calls"
+    }
+  ]
+}`,
+          codeLang: 'json',
+        },
+        {
+          step: 4,
+          type: 'execution',
+          title: '第一轮工具执行（read）',
+          label: 'Tool #1',
+          labelType: 'success',
+          toolName: 'read',
+          toolInput: `filePath: /usr1/wwkit-v1.0.x/packages/freetoken/client/src/router/index.js`,
+          toolOutput: `import { createRouter, createWebHistory } from 'vue-router'
+import HomeView from '../views/HomeView.vue'
+import TokenMarketView from '../views/TokenMarketView.vue'
+
+const routes = [
+  { path: '/', name: 'home', component: HomeView },
+  {
+    path: '/token-market',
+    name: 'token-market',
+    component: TokenMarketView,
+    meta: { titleKey: 'router.tokenMarket' },
+  },
+]`,
+        },
+        {
+          step: 5,
+          type: 'tool-result',
+          title: '第一轮结果回传',
+          label: 'Tool Result #1',
+          labelType: 'success',
+          description: '客户端将 read 结果回传给模型。模型现在知道了文件的确切内容，可以构造精确的 edit 参数。',
+          code: `POST /v1/chat/completions
+Authorization: Bearer sk-xxx
+
+{
+  "model": "maas-glm-5.1-zhipu",
+  "messages": [
+    { "role": "user", "content": "读取 client/src/router/index.js，把路由 /token-market 的组件改成 DocsView。" },
+    {
+      "role": "assistant",
+      "content": null,
+      "tool_calls": [
+        { "id": "call_jkl012", "type": "function", "function": { "name": "read", "arguments": "{\\"filePath\\": \\".../router/index.js\\"}" } }
+      ]
+    },
+    {
+      "role": "tool",
+      "tool_call_id": "call_jkl012",
+      "content": "import { createRouter, ... }\\nimport TokenMarketView from '../views/TokenMarketView.vue'\\n\\nconst routes = [\\n  { path: '/', ... },\\n  {\\n    path: '/token-market',\\n    name: 'token-market',\\n    component: TokenMarketView,\\n    ...\\n  },\\n]"
+    }
+  ],
+  "tools": [ /* ... read + edit ... */ ]
+}`,
+          codeLang: 'json',
+        },
+        {
+          step: 6,
+          type: 'tool-call',
+          title: '第二轮：模型调用 edit',
+          label: 'Model #2',
+          labelType: 'warning',
+          description:
+            '模型基于读取到的文件内容，精确构造 edit 调用：将 TokenMarketView 的 import 和 component 引用替换为 DocsView。注意模型在 arguments 中给出了精确的 oldString 和 newString。',
+          code: `{
+  "choices": [
+    {
+      "message": {
+        "role": "assistant",
+        "content": null,
+        "tool_calls": [
+          {
+            "id": "call_mno345",
+            "type": "function",
+            "function": {
+              "name": "edit",
+              "arguments": "{\\"filePath\\": \\"/usr1/wwkit-v1.0.x/packages/freetoken/client/src/router/index.js\\", \\"oldString\\": \\"import TokenMarketView from '../views/TokenMarketView.vue'\\", \\"newString\\": \\"import DocsView from '../views/DocsView.vue'\\"}"
+            }
+          },
+          {
+            "id": "call_pqr678",
+            "type": "function",
+            "function": {
+              "name": "edit",
+              "arguments": "{\\"filePath\\": \\"/usr1/wwkit-v1.0.x/packages/freetoken/client/src/router/index.js\\", \\"oldString\\": \\"component: TokenMarketView,\\", \\"newString\\": \\"component: DocsView,\\"}"
+            }
+          }
+        ]
+      },
+      "finish_reason": "tool_calls"
+    }
+  ]
+}`,
+          codeLang: 'json',
+        },
+        {
+          step: 7,
+          type: 'execution',
+          title: '第二轮工具执行（edit x2）',
+          label: 'Tool #2',
+          labelType: 'success',
+          description: '客户端执行两次 edit：替换 import 语句和 component 引用。',
+          parallelTools: [
+            {
+              toolName: 'edit',
+              toolInput: `filePath: .../router/index.js
+oldString: "import TokenMarketView from '../views/TokenMarketView.vue'"
+newString: "import DocsView from '../views/DocsView.vue'"`,
+              toolOutput: `File edited successfully. Replaced import statement.`,
+            },
+            {
+              toolName: 'edit',
+              toolInput: `filePath: .../router/index.js
+oldString: "component: TokenMarketView,"
+newString: "component: DocsView,"`,
+              toolOutput: `File edited successfully. Replaced component reference.`,
+            },
+          ],
+        },
+        {
+          step: 8,
+          type: 'final-response',
+          title: '模型最终回复',
+          label: 'Final',
+          labelType: 'primary',
+          description: '模型确认修改完成，告知用户具体做了哪些改动。',
+          code: `{
+  "choices": [
+    {
+      "message": {
+        "role": "assistant",
+        "content": "已完成修改！具体改动如下：\\n\\n1. 将 import 语句从 \`TokenMarketView\` 替换为 \`DocsView\`\\n2. 将 /token-market 路由的 component 从 \`TokenMarketView\` 替换为 \`DocsView\`\\n\\n现在访问 /token-market 路由将渲染 DocsView 组件。"
+      },
+      "finish_reason": "stop"
+    }
+  ]
+}`,
+          codeLang: 'json',
+        },
+      ],
+    },
+
+    // 示例 4：单工具流式调用
+    {
+      id: 'streaming-tool',
+      title: '示例 4：单工具流式调用（bash + stream）',
+      scenario: '用户让 agent 列出当前目录文件，请求和响应均使用流式模式',
+      description:
+        '当 stream: true 与 tools 同时启用时，tool_calls 不再一次性返回，而是通过 SSE 逐块增量推送——首个 chunk 携带工具 id 和 name，后续 chunk 携带 arguments 的部分 JSON 字符串，客户端必须拼接后才能得到完整调用参数。工具执行完毕后，第二轮请求同样以 stream: true 返回，最终回复的文本内容也逐块推送。',
+      steps: [
+        {
+          step: 1,
+          type: 'user-message',
+          title: '用户提问',
+          label: 'User',
+          labelType: 'primary',
+          content: '查看当前目录下有哪些文件？',
+        },
+        {
+          step: 2,
+          type: 'request',
+          title: '第一轮请求（stream: true + tools）',
+          label: 'Request #1',
+          labelType: 'info',
+          description: '请求同时携带 stream: true 和 tools 数组。模型将以 SSE 方式增量返回 tool_calls。',
+          code: `POST /v1/chat/completions
+Content-Type: application/json
+Authorization: Bearer sk-xxx
+
+{
+  "model": "maas-glm-5.1-zhipu",
+  "messages": [
+    {
+      "role": "user",
+      "content": "查看当前目录下有哪些文件？"
+    }
+  ],
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "bash",
+        "description": "Executes a given bash command in a persistent shell session.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "command": { "type": "string", "description": "The command to execute" }
+          },
+          "required": ["command"]
+        }
+      }
+    }
+  ],
+  "tool_choice": "auto",
+  "stream": true
+}`,
+          codeLang: 'json',
+        },
+        {
+          step: 3,
+          type: 'tool-call',
+          title: 'SSE 增量返回 tool_calls（逐块拼接）',
+          label: 'SSE Chunks',
+          labelType: 'warning',
+          description:
+            '与非流式不同，tool_calls 被拆分为多个 SSE chunk 增量推送。首个 chunk 携带 tool_call 的 id、type 和 function.name（arguments 为空字符串）；后续 chunk 只携带 arguments 的部分 JSON 文本；最后一个 chunk 的 finish_reason 为 "tool_calls"。客户端必须按 tool_calls[0].index 将所有增量片段拼接，才能得到完整的 arguments JSON。',
+          code: `data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","created":1716900000,"model":"maas-glm-5.1-zhipu","choices":[{"index":0,"delta":{"role":"assistant","tool_calls":[{"index":0,"id":"call_st001","type":"function","function":{"name":"bash","arguments":""}}]},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\\""}}]},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"command"}}]},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\\":\\""}}]},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"ls -la"}}]},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\\"}"}}]},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"tool_calls"}]}
+
+data: [DONE]`,
+          codeLang: 'json',
+        },
+        {
+          step: 4,
+          type: 'execution',
+          title: '客户端拼接 + 工具执行',
+          label: 'Accumulate + Execute',
+          labelType: 'success',
+          description:
+            '客户端按 index=0 将 6 个 chunk 的 arguments 片段拼接，得到完整 JSON：{"command":"ls -la"}。解析后执行 bash 工具。',
+          accumulate: `// 拼接过程（伪代码）
+let arguments = ''
+for (const chunk of sseChunks) {
+  if (chunk.choices[0]?.delta?.tool_calls?.[0]?.function?.arguments) {
+    arguments += chunk.choices[0].delta.tool_calls[0].function.arguments
+  }
+}
+// 拼接结果
+// arguments = '{"command":"ls -la"}'
+// 解析为对象
+const toolInput = JSON.parse(arguments)
+// { command: 'ls -la' }`,
+          toolName: 'bash',
+          toolInput: `ls -la`,
+          toolOutput: `total 48
+drwxr-xr-x  4 user user 4096 Sep 22 10:00 .
+drwxr-xr-x  8 user user 4096 Sep 22 10:00 ..
+-rw-r--r--  1 user user  412 Sep 22 10:00 index.html
+drwxr-xr-x  2 user user 4096 Sep 22 10:00 public/
+drwxr-xr-x  5 user user 4096 Sep 22 10:00 src/
+-rw-r--r--  1 user user  892 Sep 22 10:00 vite.config.js`,
+        },
+        {
+          step: 5,
+          type: 'tool-result',
+          title: '第二轮请求（工具结果回传 + stream: true）',
+          label: 'Request #2',
+          labelType: 'info',
+          description:
+            '客户端将拼接出的完整 assistant 消息（含 tool_calls）和工具结果一起回传，同样以 stream: true 请求。模型将以 SSE 逐块返回最终文本回复。',
+          code: `POST /v1/chat/completions
+Content-Type: application/json
+Authorization: Bearer sk-xxx
+
+{
+  "model": "maas-glm-5.1-zhipu",
+  "messages": [
+    {
+      "role": "user",
+      "content": "查看当前目录下有哪些文件？"
+    },
+    {
+      "role": "assistant",
+      "content": null,
+      "tool_calls": [
+        {
+          "id": "call_st001",
+          "type": "function",
+          "function": {
+            "name": "bash",
+            "arguments": "{\\"command\\": \\"ls -la\\"}"
+          }
+        }
+      ]
+    },
+    {
+      "role": "tool",
+      "tool_call_id": "call_st001",
+      "content": "total 48\\ndrwxr-xr-x  4 user user 4096 ... index.html\\n... src/\\n... vite.config.js"
+    }
+  ],
+  "tools": [ /* ... 同上 ... */ ],
+  "stream": true
+}`,
+          codeLang: 'json',
+        },
+        {
+          step: 6,
+          type: 'final-response',
+          title: 'SSE 增量返回最终回复（逐块文本）',
+          label: 'SSE Final',
+          labelType: 'primary',
+          description:
+            '第二轮的 SSE chunks 与普通流式 chat 一致——delta.content 携带增量文本片段，客户端拼接后展示给用户打字机效果。finish_reason 为 "stop" 表示回复完成。',
+          code: `data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"当前"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"目录下"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"有以下文件：\\n\\n- **index.html**"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":" — HTML 入口文件\\n"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"- **public/** — 静态资源目录\\n"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"- **src/** — 源代码目录\\n"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"- **vite.config.js** — Vite 构建配置"},"finish_reason":null}]}
+
+data: {"id":"chatcmpl-x7y8z9","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
+
+data: [DONE]`,
+          codeLang: 'json',
+        },
+      ],
+    },
+  ],
+
+  // ── Agent 循环总结 ──
+  summary: {
+    title: 'Agent 循环总结',
+    description: '从以上示例可以总结出 Agent 模式的核心循环流程：',
+    flow: [
+      { phase: '1. 用户输入', detail: '用户发送自然语言请求' },
+      { phase: '2. 模型决策', detail: '模型分析请求 + 工具列表，决定是否调用工具及调用哪个' },
+      { phase: '3. 工具调用', detail: '模型返回 tool_calls（含工具名 + 参数 JSON）' },
+      { phase: '4. 工具执行', detail: '客户端解析 tool_calls，在本地执行对应工具' },
+      { phase: '5. 结果回传', detail: '将工具执行结果以 role: "tool" 消息追加到 messages' },
+      { phase: '6. 循环 / 终止', detail: '模型根据结果决定继续调用工具（回到步骤 2）或生成最终回复（finish_reason: "stop"）' },
+    ],
+  },
+
+  // ── opencode 内置工具完整描述 ──
+  builtinTools,
+}