权限控制

版本要求：本文档针对 CodeBuddy Agent SDK v0.1.0 及以上版本。

本文档介绍如何在 SDK 中实现权限控制，包括权限模式、canUseTool 回调和工具白名单/黑名单。

概述

CodeBuddy Agent SDK 提供多种权限控制机制：

权限模式

通过 permissionMode（TypeScript）或 permission_mode（Python）设置全局权限行为。

可用模式

初始配置

TypeScript

Python

import { query } from '@tencent-ai/agent-sdk';

const q = query({
  prompt: '帮我重构这段代码',
  options: {
    model: 'deepseek-v3.1',
    permissionMode: 'acceptEdits'  // 自动批准编辑
  }
});

for await (const message of q) {
  console.log(message);
}

动态修改权限模式

使用 Session/Client API 可以在运行时动态修改权限模式：

TypeScript

Python

import { unstable_v2_createSession } from '@tencent-ai/agent-sdk';

const session = unstable_v2_createSession({
  model: 'deepseek-v3.1'
});

// 发送第一条消息
await session.send('分析这个项目');
for await (const msg of session.stream()) {
  console.log(msg);
}

// 动态切换到 acceptEdits 模式加速开发
// 注意：这是 unstable API

canUseTool 回调

canUseTool 回调在工具需要权限确认时触发，允许您实现自定义的权限逻辑。

回调签名

TypeScript

Python

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: CanUseToolOptions
) => Promise<PermissionResult>;

type CanUseToolOptions = {
  signal: AbortSignal;
  toolUseID: string;
  agentID?: string;
  suggestions?: PermissionUpdate[];
  blockedPath?: string;
  decisionReason?: string;
};

type PermissionResult =
  | { behavior: 'allow'; updatedInput: Record<string, unknown> }
  | { behavior: 'deny'; message: string; interrupt?: boolean };

完整示例：交互式审批

TypeScript

Python

import { query } from '@tencent-ai/agent-sdk';

const q = query({
  prompt: '帮我分析这个代码库',
  options: {
    model: 'deepseek-v3.1',
    canUseTool: async (toolName, input, options) => {
      console.log(`\n🔧 工具请求: ${toolName}`);
      console.log(`参数:`, JSON.stringify(input, null, 2));

      // 只读工具自动允许
      const readOnlyTools = ['Read', 'Glob', 'Grep'];
      if (readOnlyTools.includes(toolName)) {
        return { behavior: 'allow', updatedInput: input };
      }

      // 危险命令拒绝
      if (toolName === 'Bash') {
        const command = input.command as string;
        if (command.includes('rm -rf') || command.includes('sudo')) {
          return {
            behavior: 'deny',
            message: '危险命令被拒绝',
            interrupt: true  // 中断整个会话
          };
        }
      }

      // 其他情况：模拟用户确认
      const approved = await promptUser(`允许执行 ${toolName}?`);

      if (approved) {
        return { behavior: 'allow', updatedInput: input };
      } else {
        return { behavior: 'deny', message: '用户拒绝' };
      }
    }
  }
});

for await (const message of q) {
  console.log(message);
}

修改工具输入

可以在 canUseTool 中修改工具的输入参数：

TypeScript

Python

canUseTool: async (toolName, input) => {  if (toolName === 'Bash') {    // 在命令前添加安全检查    return {      behavior: 'allow',      updatedInput: {        ...input,        command: `set -e; ${input.command}`      }    };  }  return { behavior: 'allow', updatedInput: input };}

处理 AskUserQuestion

当 AI 需要向用户提问时，会调用 AskUserQuestion 工具。您需要在 canUseTool 中处理这个工具。

输入结构

{  questions: [    {      question: "使用哪个数据库？",      header: "数据库",      options: [        { label: "PostgreSQL", description: "关系型数据库" },        { label: "MongoDB", description: "文档数据库" }      ],      multiSelect: false    }  ]}

返回答案

TypeScript

Python

canUseTool: async (toolName, input) => {
  if (toolName === 'AskUserQuestion') {
    const questions = input.questions as any[];
    const answers: Record<string, string> = {};

    for (const q of questions) {
      console.log(`问题: ${q.question}`);
      for (let i = 0; i < q.options.length; i++) {
        console.log(`  ${i + 1}. ${q.options[i].label}`);
      }

      // 获取用户输入
      const choice = await getUserChoice();
      answers[q.question] = q.options[choice].label;
    }

    return {
      behavior: 'allow',
      updatedInput: { ...input, answers }
    };
  }

  return { behavior: 'allow', updatedInput: input };
}

工具白名单/黑名单

SDK 提供多种工具过滤机制：

tools：内置工具白名单

使用 tools 选项从根本上限制 CodeBuddy 可使用的内置工具集：

TypeScript

Python

const q = query({
  prompt: '分析项目结构',
  options: {
    model: 'deepseek-v3.1',
    // 只允许这些内置工具
    tools: ['Read', 'Glob', 'Grep']
  }
});

// 禁用所有内置工具（仅使用 MCP 工具）
const q2 = query({
  prompt: '使用 MCP 工具完成任务',
  options: {
    tools: []  // 空数组禁用所有内置工具
  }
});

allowedTools/disallowedTools：工具过滤

使用 allowedTools 和 disallowedTools 进行更细粒度的工具过滤，支持模式匹配：

TypeScript

Python

const q = query({  prompt: '分析项目结构',  options: {    model: 'deepseek-v3.1',    // 只允许这些工具    allowedTools: ['Read', 'Glob', 'Grep'],    // 或者禁止这些工具    disallowedTools: ['Bash', 'Write', 'Edit']  }});

常用工具名称

最佳实践

默认使用 default 模式：提供最完整的权限控制

只读任务使用 plan 模式：

permissionMode: 'plan'  // 只允许 Read、Glob、Grep

结合白名单精确控制：

allowedTools: ['Read', 'Glob', 'Grep'],permissionMode: 'bypassPermissions'  // 允许的工具自动执行

危险命令使用 interrupt：

return {  behavior: 'deny',  message: '危险操作',  interrupt: true  // 立即中断，不让 AI 继续尝试};

生产环境避免 bypassPermissions：该模式会跳过所有权限检查

相关文档

SDK 概览 - 快速入门和使用示例

SDK Hook 系统 - 更细粒度的工具控制

TypeScript SDK 参考 - 完整 API 参考

Python SDK 参考 - 完整 API 参考