autosnippet
Version:
Extract code patterns into a knowledge base for AI coding assistants
274 lines (273 loc) • 8.49 kB
TypeScript
/**
* Policies — Agent 执行约束 (横切关注点)
*
* Policy 不改变 Agent 做什么，而是约束 Agent 如何做。
* 多个 Policy 可叠加，形成复合约束。
*
* 三类 Policy:
* 1. BudgetPolicy — 资源预算 (迭代次数 / Token / 时间)
* 2. SafetyPolicy — 安全沙箱 (命令黑名单 / 文件范围 / 发送者鉴权)
* 3. QualityGatePolicy — 质量门控 (证据数量 / 分析深度)
*
* 这就是为什么"飞书远程执行"不需要独立 Agent:
* 它只是 Conversation + SystemInteraction + SafetyPolicy 的组合。
* SafetyPolicy 提供命令沙箱，而不是由 LarkBridgeAgent 硬编码。
*
* @module policies
*/
/** 执行前校验的上下文 */
export interface PolicyContext {
message?: {
sender?: {
id?: string;
};
};
[key: string]: unknown;
}
/** 执行步骤状态 */
export interface StepState {
iteration: number;
startTime: number;
[key: string]: unknown;
}
/** Agent 执行结果 */
export interface PolicyResult {
reply?: string;
toolCalls?: unknown[];
[key: string]: unknown;
}
/** SafetyPolicy 构造选项 */
export interface SafetyPolicyOptions {
fileScope?: string;
allowedSenders?: string[];
commandBlacklist?: RegExp[];
requireApprovalFor?: string[];
}
/** QualityGatePolicy 构造选项 */
export interface QualityGatePolicyOptions {
minEvidenceLength?: number;
minFileRefs?: number;
minToolCalls?: number;
customValidator?: (result: PolicyResult) => {
ok: boolean;
reason?: string;
};
}
/** Policy 基类 — 所有约束的抽象接口 */
export declare class Policy {
/** 策略名称 */
get name(): string;
/** 执行前校验 — 拒绝不满足条件的请求 */
validateBefore(_context: PolicyContext): {
ok: boolean;
reason?: string;
};
/** 执行中校验 — 每轮 ReAct 步骤后检查 */
validateDuring(_stepState: StepState): {
ok: boolean;
action?: string;
reason?: string;
};
/** 执行后校验 — 对最终结果质量把关 */
validateAfter(_result: PolicyResult): {
ok: boolean;
reason?: string;
};
/** 修改配置 — 在执行前注入额外约束 */
applyToConfig(config: Record<string, unknown>): Record<string, unknown>;
}
/**
* 控制 Agent 的资源消耗上限。
*
* 适用于所有场景，不同 Preset 配置不同预算:
* - 聊天: { maxIterations: 8, timeoutMs: 120_000 }
* - 深度分析: { maxIterations: 24, timeoutMs: 300_000 }
* - 冷启动: { maxIterations: 24, timeoutMs: 600_000 }
* - 远程执行: { maxIterations: 6, timeoutMs: 60_000 }
*/
export declare class BudgetPolicy extends Policy {
#private;
constructor({ maxIterations, maxTokens, timeoutMs, temperature, }?: {
maxIterations?: number | undefined;
maxTokens?: number | undefined;
timeoutMs?: number | undefined;
temperature?: number | undefined;
});
get name(): string;
get maxIterations(): number;
get maxTokens(): number;
get timeoutMs(): number;
get temperature(): number;
validateDuring(stepState: StepState): {
ok: boolean;
action: string;
reason: string;
} | {
ok: boolean;
action: string;
reason?: undefined;
};
applyToConfig(config: Record<string, unknown>): {
budget: {
maxIterations: number;
maxTokens: number;
timeoutMs: number;
temperature: number;
};
};
}
/**
* 安全约束: 命令过滤、文件范围限制、发送者鉴权。
*
* 这取代了旧 LarkBridgeAgent 中硬编码的安全逻辑:
* - SafetyPolicy 是可组合的、可配置的、可复用的
* - 任何需要安全约束的场景都可以叠加这个 Policy
* - 不局限于飞书场景 — CLI 远程执行同样适用
*/
export declare class SafetyPolicy extends Policy {
#private;
/** 危险命令正则黑名单 */
static DANGEROUS_COMMANDS: readonly RegExp[];
/** 安全命令前缀白名单 */
static SAFE_COMMANDS: readonly string[];
/**
* @param [opts.fileScope] 文件操作范围 (目录路径)
* @param [opts.allowedSenders] 允许的发送者 ID (空=不限制)
* @param [opts.commandBlacklist] 额外命令黑名单
* @param [opts.requireApprovalFor] 需要人工确认的工具名
*/
constructor({ fileScope, allowedSenders, commandBlacklist, requireApprovalFor, }?: SafetyPolicyOptions);
get name(): string;
validateBefore(context: PolicyContext): {
ok: boolean;
reason: string;
} | {
ok: boolean;
reason?: undefined;
};
/**
* 检查命令是否安全
* @returns }
*/
checkCommand(command: string): {
safe: boolean;
reason: string;
} | {
safe: boolean;
reason?: undefined;
};
/**
* 检查文件路径是否在允许范围内
* @returns }
*/
checkFilePath(filePath: string): {
safe: boolean;
reason?: undefined;
} | {
safe: boolean;
reason: string;
};
/** 是否需要人工确认 */
needsApproval(toolName: string): boolean;
applyToConfig(config: Record<string, unknown>): Record<string, unknown>;
}
/**
* 评估 Agent 输出质量，决定是否接受结果。
*
* 用于 Pipeline 的 gate 阶段，也可用于最终结果校验。
* 取代了旧 BootstrapOrchestrator 中硬编码的 qualityCheck。
*/
export declare class QualityGatePolicy extends Policy {
#private;
/**
* @param [opts.minEvidenceLength=500] 分析文本最小长度
* @param [opts.minFileRefs=3] 最少文件引用数
* @param [opts.minToolCalls=2] 最少工具调用数
* @param [opts.customValidator] 自定义校验 (result) => { ok, reason }
*/
constructor({ minEvidenceLength, minFileRefs, minToolCalls, customValidator, }?: QualityGatePolicyOptions);
get name(): string;
validateAfter(result: PolicyResult): {
ok: boolean;
reason?: undefined;
} | {
ok: boolean;
reason: string;
};
/** 导出为 PipelineStrategy gate 配置格式 */
toGateConfig(): {
minEvidenceLength: number;
minFileRefs: number;
minToolCalls: number;
custom: ((result: PolicyResult) => {
ok: boolean;
reason?: string;
}) | null;
};
}
/**
* 组合多个 Policy 并统一执行校验。
*
* @example
* const engine = new PolicyEngine([
* new BudgetPolicy({ maxIterations: 8 }),
* new SafetyPolicy({ fileScope: '/project' }),
* ]);
* engine.validateBefore(context); // 所有 policy 依次检查
*/
export declare class PolicyEngine {
#private;
constructor(policies?: Policy[]);
get policies(): Policy[];
/**
* 获取特定类型的 Policy
* @template T
*/
get<T extends Policy>(PolicyClass: abstract new (...args: never[]) => T): T | null;
validateBefore(context: PolicyContext): {
ok: boolean;
reason?: string;
};
validateDuring(stepState: StepState): {
ok: boolean;
action?: string;
reason?: string;
};
validateAfter(result: PolicyResult): {
ok: boolean;
reason?: string;
};
applyToConfig(config: Record<string, unknown>): Record<string, unknown>;
/** 获取合并后的 Budget (从 BudgetPolicy) */
getBudget(): {
maxIterations: number;
maxTokens: number;
timeoutMs: number;
temperature: number;
} | null;
/**
* 工具执行前的安全校验 — 在 reactLoop 中每次工具调用前自动触发
*
* 对有副作用的工具 (run_safe_command, write_project_file) 执行安全检查。
* 委托给 SafetyPolicy，如果没有加载 SafetyPolicy 则放行。
*
* @param toolName 工具名称
* @param args 工具参数
* @returns }
*/
validateToolCall(toolName: string, args: Record<string, unknown>): {
ok: boolean;
reason?: undefined;
} | {
ok: boolean;
reason: string;
};
}
declare const _default: {
Policy: typeof Policy;
BudgetPolicy: typeof BudgetPolicy;
SafetyPolicy: typeof SafetyPolicy;
QualityGatePolicy: typeof QualityGatePolicy;
PolicyEngine: typeof PolicyEngine;
};
export default _default;