《互联网产品的 AI 架构·模型接入与能力边界》7.2 工具调用：谁执行、谁授权

{"id":"call-17","name":"orders.lookup","arguments":{"orderId":"E20261026001","tenantId":"t-other"}}

// file: src/tools/policy.ts
// tier: L1
// verify: node --test test/tools/policy.test.ts

import type { SchemaIssue, SchemaNode } from "../structured/schema.ts";
import { validate } from "../structured/schema.ts";

export type TenantRole = "viewer" | "member" | "operator" | "admin";

/** 副作用从只读、草稿、写入到站外操作逐级升高。 */
export type SideEffect = "read" | "draft" | "write" | "external";

const ROLE_RANK: Record<TenantRole, number> = {
  viewer: 0,
  member: 1,
  operator: 2,
  admin: 3,
};

const SIDE_EFFECT_RANK: Record<SideEffect, number> = {
  read: 0,
  draft: 1,
  write: 2,
  external: 3,
};

export interface ToolSpec {
  name: string;
  sideEffect: SideEffect;
  minRole: TenantRole;
  /** 参数契约复用 7.1 的校验器，模型自述的参数不算数。 */
  parameters: SchemaNode;
  /** 单轮对话允许的最大调用次数，防止模型循环调用。 */
  maxCallsPerTurn: number;
}

export interface ToolCall {
  /** 模型生成的调用 id，用于把用户确认绑定到具体一次调用。 */
  id: string;
  name: string;
  arguments: unknown;
}

export interface ToolContext {
  /** 租户身份只来自会话，不来自模型参数。 */
  tenantId: string;
  role: TenantRole;
  /** 租户开通的工具白名单，与全局注册表取交集。 */
  allowedTools: string[];
  /** 用户已经明确确认过的调用 id。 */
  confirmedCallIds: string[];
  /** 由网关维护的本轮调用计数，模型无法修改。 */
  callCounts: Record<string, number>;
}

export type DenyReason =
  | "unknown-tool"
  | "tool-not-allowed"
  | "role-denied"
  | "tenant-override"
  | "invalid-arguments"
  | "confirmation-required"
  | "call-limit";

export type ToolDecision =
  | { allowed: true; tool: ToolSpec; args: Record<string, unknown> }
  | { allowed: false; reason: DenyReason; detail: string; issues?: SchemaIssue[] };

export type ToolExecutor = (
  args: Record<string, unknown>,
  context: ToolContext,
) => unknown | Promise<unknown>;

export interface ToolExecution {
  status: "denied" | "executed" | "failed";
  decision: ToolDecision;
  output?: unknown;
  error?: string;
}

const FORBIDDEN_ARGUMENT_KEYS = new Set(["tenantId", "tenant_id"]);

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

/** 递归查找模型试图自带的租户字段，嵌套在过滤条件里也要拦住。 */
function findTenantKey(value: unknown, path: string): string | null {
  if (Array.isArray(value)) {
    for (let index = 0; index < value.length; index += 1) {
      const found = findTenantKey(value[index], `${path}[${index}]`);
      if (found !== null) return found;
    }
    return null;
  }
  if (!isRecord(value)) return null;
  for (const key of Object.keys(value)) {
    const child = /^[A-Za-z_][A-Za-z0-9_]*$/.test(key)
      ? `${path}.${key}`
      : `${path}[${JSON.stringify(key)}]`;
    if (FORBIDDEN_ARGUMENT_KEYS.has(key)) return child;
    const found = findTenantKey(value[key], child);
    if (found !== null) return found;
  }
  return null;
}

export function needsConfirmation(sideEffect: SideEffect): boolean {
  return SIDE_EFFECT_RANK[sideEffect] >= SIDE_EFFECT_RANK.write;
}

/**
 * 模型只能提议，授权与执行都在网关侧完成。
 * 检查顺序固定：注册表 > 租户白名单 > 角色 > 租户注入 > 参数 > 确认 > 次数。
 */
export function authorizeToolCall(
  registry: Record<string, ToolSpec>,
  context: ToolContext,
  call: ToolCall,
): ToolDecision {
  const tool = registry[call.name];
  if (tool === undefined) {
    return { allowed: false, reason: "unknown-tool", detail: `tool ${call.name} is not registered` };
  }
  if (!context.allowedTools.includes(call.name)) {
    return {
      allowed: false,
      reason: "tool-not-allowed",
      detail: `tenant ${context.tenantId} has not enabled ${call.name}`,
    };
  }
  if (ROLE_RANK[context.role] < ROLE_RANK[tool.minRole]) {
    return {
      allowed: false,
      reason: "role-denied",
      detail: `role ${context.role} is below ${tool.minRole} for ${call.name}`,
    };
  }
  const tenantPath = findTenantKey(call.arguments, "$");
  if (tenantPath !== null) {
    return {
      allowed: false,
      reason: "tenant-override",
      detail: `tenant identity must come from context, not arguments (${tenantPath})`,
    };
  }

  const issues = validate(tool.parameters, call.arguments);
  if (issues.length > 0) {
    return {
      allowed: false,
      reason: "invalid-arguments",
      detail: `arguments for ${call.name} do not match the contract`,
      issues,
    };
  }

  if (needsConfirmation(tool.sideEffect) && !context.confirmedCallIds.includes(call.id)) {
    return {
      allowed: false,
      reason: "confirmation-required",
      detail: `${call.name} is a ${tool.sideEffect} operation and needs explicit confirmation`,
    };
  }

  const used = context.callCounts[call.name] ?? 0;
  if (used >= tool.maxCallsPerTurn) {
    return {
      allowed: false,
      reason: "call-limit",
      detail: `${call.name} already used ${used} times in this turn`,
    };
  }

  if (!isRecord(call.arguments)) {
    return { allowed: false, reason: "invalid-arguments", detail: "arguments must be an object" };
  }
  return { allowed: true, tool, args: call.arguments };
}

/** 只有授权通过才会触达执行器；被拒绝的调用不会产生任何业务副作用。 */
export async function executeToolCall(
  registry: Record<string, ToolSpec>,
  executors: Record<string, ToolExecutor>,
  context: ToolContext,
  call: ToolCall,
): Promise<ToolExecution> {
  const decision = authorizeToolCall(registry, context, call);
  if (!decision.allowed) {
    return { status: "denied", decision };
  }
  const executor = executors[call.name];
  if (executor === undefined) {
    return { status: "failed", decision, error: `no executor registered for ${call.name}` };
  }
  try {
    const output = await executor(decision.args, context);
    return { status: "executed", decision, output };
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    return { status: "failed", decision, error: message };
  }
}

node --test test/tools/policy.test.ts

ℹ tests 15
ℹ suites 0
ℹ pass 15
ℹ fail 0
ℹ duration_ms 172.733958