ScenarioCapabilities

场景能力声明，定义 AI 可以使用的工具包、工作模式、上下文类型和输出格式。

interface ScenarioCapabilities {
  /** 工具包列表（引用 toolPackRegistry 中注册的工具包 id） */
  toolPacks: string[]

  /** 场景直接声明的工具名列表（用于声明式场景，无需 toolPack 注册） */
  tools?: string[]

  /** 工作模式 */
  modes: ScenarioModeDescriptor[]

  /** 上下文类型 */
  contextTypes: ContextTypeDescriptor[]

  /** 输出格式 */
  outputFormats: string[]
}

interface ScenarioModeDescriptor {
  id: WorkMode | string
  label: string
  labelZh: string
  icon: string
  description: string
  descriptionZh: string
  toolPolicy: {
    enabled: boolean
    requireApproval?: boolean
  }
}

interface ContextTypeDescriptor {
  type: string
  label: string
  labelZh: string
  icon?: string
  priority: number
}

内置工具包

工具包由 toolPackRegistry（src/shared/configuration/toolPacks.ts）注册， 场景通过 toolPacks 引用；resolveTools() 会自动带上依赖包的工具，无需重复声明。

工具包 id	名称	分类	依赖	tools（可解析、可用）	reservedTools（预留，不解析）
code	代码工具	code	—	文件读写与检索、终端、LSP、网络、记忆与知识、交互与规划（详见下表）	历史遗留名（见下表）
data	数据工具	data	code	—	sql_query、data_transform、csv_analyze、chart_generate、statistical_test、rest_api
web	网页工具	web	code	—	web_scrape、api_call、browser_automate
media	媒体工具	media	code	—	image_generate、image_edit、audio_transcribe、video_analyze
office	办公工具	office	code	—	doc_write、spreadsheet、presentation、email_send
education	教育工具	custom	code	subject_manage、topic_manage、quiz_manage、study_plan_manage、progress_manage、flashcard_manage、mistake_manage、topic_explain、practice_problems、subject_dashboard、learning_suggest	—
store-diagnosis	门店诊断工具	custom	code	store_manage、store_diagnose、report_generate、optimization_plan、benchmark_query	—

education / store-diagnosis 两个包的工具执行器由对应场景项目通过 toolRegistry.registerScenarioTool() 注册，不在编译期静态枚举范围内。

code 工具包明细

分组	工具
文件	read_file、list_directory、search_files、edit_file、write_file、create_file_or_folder、delete_file_or_folder
终端	run_command、read_terminal_output、send_terminal_input、stop_terminal
Git	git_status、git_diff、git_log、git_commit、git_branch、git_sync、git_worktree、git_audit
代码分析	get_lint_errors、find_references、go_to_definition、get_hover_info、get_document_symbols、codebase_search
网络	web_search、read_url、image_search、video_search
记忆与知识	remember、knowledge_search、apply_skill
交互与规划	ask_user、todo_write、schedule
图运行时	add_node、add_edge（graphVersion=2 执行期动态建图）
桌面伴侣	companion_control

optionalTools（需显式包含）：uiux_search、uiux_recommend。

reservedTools（预留，无工具定义亦无执行器）：get_dir_tree、read_multiple_files、 replace_file_content —— 历史遗留名，能力已分别并入 list_directory（递归模式）、 read_file（支持 paths 数组）、edit_file。

extract_document 由 getToolsForContext() 在所有模式、所有场景下无条件注入， 不属于任何工具包，因此不在上表中。

可用性说明

• 工具包只负责「按场景批量启用工具」；能否真正执行还取决于工具是否已注册到运行时工具表。
• 每个工具包区分两个字段：
  • tools：已接入内置执行器。resolveTools() 会解析，并进入 LLM 工具列表与系统提示词。
  • reservedTools：预留能力（工具描述可能已定义，但 toolExecutors.ts 尚未实现执行器， toolRegistry.has() 返回 false）。resolveTools() 会跳过它们，因此不会进入 LLM 工具列表与系统提示词 —— 这样 AI 不会去调用一个必然失败的工具。
• 当前 tools 非空的工具包只有 code、education、store-diagnosis； data、web、media、office 四个包的 tools 为空，全部工具（共 17 项）位于 reservedTools。
• 因此声明 data / web / media / office 是安全的：resolveTools() 只会返回 其依赖包 code 的工具，不会把不可用工具暴露给 AI。执行器补齐后，把工具名从 reservedTools 移入 tools 即可自动生效。
• 未注册的工具包 id 会在 resolveDependencies() 中被跳过并输出告警。 建议在加载 / 构建期用 toolPackRegistry.findUnknownPacks(packIds) 做前置校验； toolPackRegistry.resolveReservedTools(packIds) 可列出某场景下全部预留工具。
• 声明式场景的能力声明走 capabilities.builtinTools（见 声明式配置），其可选值与 内置工具 列表一一对应，与工具包是两套机制。
• ⚠️ 声明的内置工具还会经过套餐能力组白名单这一层过滤：低套餐用户可能拿不到 部分已声明的工具，详见 内置工具 · 可用性的三层过滤。

示例

const capabilities: ScenarioCapabilities = {
  toolPacks: ['code', 'data'],
  modes: [
    {
      id: 'chat',
      label: 'Quick',
      labelZh: '快速',
      icon: 'Zap',
      description: 'Suitable for most situations',
      descriptionZh: '适用于大部分情况',
      toolPolicy: { enabled: true, requireApproval: false },
    },
  ],
  contextTypes: [
    { type: 'File', label: 'File', labelZh: '文件', priority: 1 },
  ],
  outputFormats: ['text', 'markdown'],
}

详见 内置工具 与 权限声明。

详见 内置工具。