cs-note/claude-code-best/docs/features/bash-classifier.md

tags, create time

tags	create time
bash classifier LLM 权限 安全 feature-flag	2026-06-09 22:30

BASH_CLASSIFIER — Bash 命令分类器

概述

BASH_CLASSIFIER 使用 LLM 对 bash 命令进行意图分类（允许/拒绝/询问），实现自动权限决策。用户不需要逐个审批 bash 命令，分类器根据命令内容和上下文自动判断安全性。

[!info] Feature Flag: FEATURE_BASH_CLASSIFIER=1 实现状态：bashClassifier.ts 全部 Stub，yoloClassifier.ts 完整实现可参考

正文

核心特性

• LLM 驱动分类：使用 Opus 模型评估命令安全性
• 两阶段分类：快速阻止/允许 -> 深度思考链
• 自动审批：分类器判定安全的命令自动通过
• UI 集成：权限对话框显示分类器状态和审核选项

实现架构

模块状态

模块	文件	状态	说明
Bash 分类器	src/utils/permissions/bashClassifier.ts	Stub	所有函数返回空操作。注释："ANT-ONLY"
YOLO 分类器	src/utils/permissions/yoloClassifier.ts	完整	1496 行，两阶段 XML 分类器
审批信号	src/utils/classifierApprovals.ts	完整	Map + 信号管理分类器决策
权限 UI	src/components/permissions/BashPermissionRequest.tsx	布线	分类器状态显示、审核选项
权限管道	src/hooks/toolPermission/handlers/*.ts	布线	分类器结果路由到决策
API beta 标头	src/services/api/withRetry.ts	布线	启用时发送 bash_classifier beta

参考实现：yoloClassifier.ts

文件：src/utils/permissions/yoloClassifier.ts（1496 行）

这是已实现的完整分类器，可作为 bashClassifier.ts 的参考：

flowchart TD
    A["两阶段分类"] --> B["快速阶段: 构建对话记录 -> 调用 sideQuery Opus -> 快速阻止/允许"]
    A --> C["深度阶段: 思考链分析 -> 最终决策"]

特性：

• 构建完整对话记录上下文
• 调用安全系统提示的 sideQuery
• GrowthBook 配置和指标
• 错误处理和降级

分类器在权限管道中的位置

flowchart TD
    A["bash 命令到达"] --> B["bashPermissions.ts 权限检查"]
    B --> C["传统规则匹配 字符串级别"]
    B --> D{"BASH_CLASSIFIER LLM 分类"}
    D -->|"allow"| E["自动通过"]
    D -->|"deny"| F["自动拒绝"]
    D -->|"ask"| G["显示权限对话框"]
    G --> H["分类器自动审批标记"]
    G --> I["审核选项 用户可覆盖"]

需要补全的内容

函数	需要实现	说明
classifyBashCommand()	LLM 调用评估安全性	参考 yoloClassifier.ts 的两阶段模式
isClassifierPermissionsEnabled()	GrowthBook/配置检查	控制分类器是否激活
getBashPromptDenyDescriptions()	返回基于提示的拒绝规则	权限设置描述
getBashPromptAskDescriptions()	返回询问规则	需要用户确认的命令
getBashPromptAllowDescriptions()	返回允许规则	自动通过的命令
generateGenericDescription()	LLM 生成命令描述	为权限对话框提供说明
extractPromptDescription()	解析规则内容	从规则中提取描述

关键设计决策

1. ANT-ONLY 标记：bashClassifier.ts 标注为 "ANT-ONLY"，可能是 Anthropic 内部服务端分类器的客户端适配
2. 两阶段分类：快速阶段处理明确情况（减少延迟），深度阶段处理模糊情况
3. 分类器结果可审核：权限 UI 显示分类器决策，用户可覆盖
4. YOLO 分类器参考：yoloClassifier.ts 提供完整的分类器实现模式，可直接参考

使用方式

# 启用 feature
FEATURE_BASH_CLASSIFIER=1 bun run dev

# 配合 TREE_SITTER_BASH 使用（AST + LLM 双重安全）
FEATURE_BASH_CLASSIFIER=1 FEATURE_TREE_SITTER_BASH=1 bun run dev

文件索引

文件	行数	职责
src/utils/permissions/bashClassifier.ts	—	Bash 分类器（stub，ANT-ONLY）
src/utils/permissions/yoloClassifier.ts	1496	YOLO 分类器（完整参考实现）
src/utils/classifierApprovals.ts	—	分类器审批信号管理
src/components/permissions/BashPermissionRequest/BashPermissionRequest.tsx	—	分类器 UI
src/hooks/toolPermission/handlers/interactiveHandler.ts	—	交互式权限处理
src/services/api/withRetry.ts	—	API beta 标头

关联笔记

• claude-code-best/docs/features/tree-sitter-bash