{"meta":{"title":"上下文清除和终端工具","intro":"当主机需要替换当前会话上下文而不替换会话时使用 session.history.clearContext 。 典型用途包括移交和主机管理的上下文生命周期策略。","product":"GitHub Copilot","breadcrumbs":[{"href":"/zh/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos","title":"操作方法"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features","title":"功能"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/context-management","title":"上下文管理"}],"documentType":"article"},"body":"# 上下文清除和终端工具\n\n当主机需要替换当前会话上下文而不替换会话时使用 session.history.clearContext 。 典型用途包括移交和主机管理的上下文生命周期策略。\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n上下文清除不同于创建新会话：删除面向模型的会话时，它会保留会话标识、系统和开发人员消息、配置和事件日志。\n\n> [!IMPORTANT]\n> `clearContext` 是工具处理程序基元。 运行时会拒绝以下调用：在没有正在进行的工具调用时发起的调用、初始提示词为空的调用，以及针对远程会话发起的调用。\n\n## 定义上下文清除工具\n\n成功的上下文清除工具应该是终端。 否则，智能体循环可能在新清除的窗口上发起另一个模型调用，然后再开始种子轮次。\n\n```typescript\nimport { approveAll, CopilotClient, defineTool } from \"@github/copilot-sdk\";\nimport type { CopilotSession } from \"@github/copilot-sdk\";\nimport { z } from \"zod\";\n\nconst client = new CopilotClient();\nlet session: CopilotSession;\n\nsession = await client.createSession({\n  onPermissionRequest: approveAll,\n  tools: [\n    defineTool(\"clear_context\", {\n      description: \"Clear the conversation and start a fresh context window\",\n      parameters: z.object({ prompt: z.string() }),\n      isTerminal: true,\n      defer: \"never\",\n      handler: async ({ prompt }) => {\n        const { messagesCleared } =\n          await session.rpc.history.clearContext({ prompt });\n        return `Cleared ${messagesCleared} messages.`;\n      },\n    }),\n  ],\n});\n```\n\n所需的 `prompt` 将成为新上下文中的第一条用户消息。 清除成功后，会发出 `session.context_cleared`，并附带已移除的消息数量和初始消息。\n\n## 终端工具的行为\n\n`isTerminal` 仅当工具成功时，才会结束当前代理轮次。 失败、拒绝、拒绝、超时或输入验证错误对模型仍可见，以便它可以恢复或重试。\n\n此选项遵循每个语言的命名约定：\n\n| SDK | 工具选项 |\n|---|---|\n| Node.js | `isTerminal` |\n| Python | `is_terminal` |\n| Go | `IsTerminal` |\n| .NET | `CopilotToolOptions.IsTerminal` |\n| Java | \n`ToolDefinition.isTerminal(true)` 或 `@CopilotTool(isTerminal = true)` |\n| Rust | `with_is_terminal(true)` |\n\n仅对那些成功完成后应结束当前轮次的工具使用终止属性。 常规工具应保持其未设置状态。"}