挂钩快速入门

注意

Copilot SDK 当前处于技术预览版. 功能和可用性可能会发生更改。

挂钩允许您在会话生命周期的关键点截获和自定义 Copilot SDK 会话的行为。使用挂钩可以：

        **控制工具执行** - 批准、拒绝或修改工具调用

        **转换结果** - 在处理结果之前修改工具输出

        **添加上下文** - 在会话开始时注入其他信息

        **处理错误** - 实现自定义错误处理

        **审核和记录** - 跟踪符合性的所有交互

可用挂钩

挂钩	Trigger	用例
`onPreToolUse`	在工具执行之前	权限控制，参数验证
`onPostToolUse`	工具执行完毕后	结果转换，日志记录
`onUserPromptSubmitted`	当用户发送消息时	提示修改，筛选
`onSessionStart`	会话开始	添加上下文，配置会话
`onSessionEnd`	会话结束	清理、分析
`onErrorOccurred`	发生错误	自定义错误处理

快速入门

以下示例演示如何在 Node.js/TypeScript 中创建会话时注册挂钩。

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      console.log(`Tool called: ${input.toolName}`);
      // Allow all tools
      return { permissionDecision: "allow" };
    },
    onPostToolUse: async (input) => {
      console.log(
        `Tool result: ${JSON.stringify(input.toolResult)}`
      );
      return null; // No modifications
    },
    onSessionStart: async (input) => {
      return {
        additionalContext:
          "User prefers concise answers.",
      };
    },
  },
});

有关 Python、Go 和 .NET 中的示例，请参阅 github/copilot-sdk 存储库。

挂钩调用上下文

每个挂钩接收一个 invocation 参数，其中包含有关当前会话的上下文。

领域	类型	说明
`sessionId`	字符串	当前会话的 ID

这允许钩子维护状态或执行会话特定的逻辑。

常见模式

记录所有工具调用

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      console.log(
        `[${new Date().toISOString()}] Tool: `
        + `${input.toolName}, `
        + `Args: ${JSON.stringify(input.toolArgs)}`
      );
      return { permissionDecision: "allow" };
    },
    onPostToolUse: async (input) => {
      console.log(
        `[${new Date().toISOString()}] `
        + `Result: ${JSON.stringify(input.toolResult)}`
      );
      return null;
    },
  },
});

阻止危险工具

const BLOCKED_TOOLS = ["shell", "bash", "exec"];

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      if (BLOCKED_TOOLS.includes(input.toolName)) {
        return {
          permissionDecision: "deny",
          permissionDecisionReason:
            "Shell access is not permitted",
        };
      }
      return { permissionDecision: "allow" };
    },
  },
});

添加用户上下文

const session = await client.createSession({
  hooks: {
    onSessionStart: async () => {
      const userPrefs = await loadUserPreferences();
      return {
        additionalContext:
          `User preferences: `
          + `${JSON.stringify(userPrefs)}`,
      };
    },
  },
});

后续步骤

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/pre-tool-use)

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/post-tool-use)

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/user-prompt-submitted)

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/session-lifecycle)

        [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/error-handling)

谁可以使用此功能？

在本文中