11_02_Tool_Registry

(二) 工具调度与高风险确认

CLI（命令行）工具系统在 cli/tools.py：

• TOOL_SCHEMAS：给模型看的 JSON Schema（JSON 格式工具参数协议）。
• ToolSpec：工具元数据，包括中文展示名、是否并发安全、是否需要确认、是否后台执行。
• ToolRegistry：工具注册表，负责 provider（模型适配层）/ context（上下文）注入、确认回调、后台任务提交和实际执行。
• ToolContext：工具上下文，跨工具共享 state、provider、registry、on_progress，也是 sub-agent（子智能体）委派的桥。

CLI（命令行）当前注册 21 个工具：

类型	工具
金融分析	search_stock_by_name、analyze_stock、portfolio、get_market_overview、get_market_history、screen_stocks、generate_ai_report、generate_strategy_decision、query_history、run_backtest
数据修改	update_portfolio
后台任务	check_background_tasks
交互 / Skill（技能）	ask_user、execute_skill
Sub-agent（子智能体）委派	delegate_to_research、delegate_to_analysis、delegate_to_trading
本地工具	exec_command、read_file、write_file、web_fetch

调度策略：

• concurrency_safe=True（并发安全）的工具可在同一轮连续工具调用中并行执行，最大 ThreadPoolExecutor(max_workers=5)（5 线程线程池）。
• 非并发安全工具串行执行，避免写操作、后台任务或外部副作用互相踩踏。
• requires_approval=True（需要用户审批）的工具在 TUI 中弹确认框：允许一次、总是允许、修改后执行或拒绝。
• background=True（后台执行）且 TUI 注入了 BackgroundTaskManager（后台任务管理器）时，工具立即返回 task_id（任务编号），实际任务在 daemon thread（守护线程）中运行。

当前并发安全工具：

search_stock_by_name、analyze_stock、portfolio、get_market_overview、get_market_history、query_history、execute_skill

当前高风险确认工具：

update_portfolio、exec_command、write_file

高风险二次确认与 ask_user

为了防止模型越权执行高风险工具，系统设计了 双重确认拦截机制 ：

1. 静默拦截：若 requires_approval=True 且未配置 confirm 回调时，ToolRegistry 会直接阻断调用，告知模型必须先调用 ask_user 解释风险并获取同意。
2. 上下文确认检索：ToolRegistry.execute 会在每轮调用前扫描 messages 对话历史。只有当在历史中检索到由 ask_user 返回的“用户同意”（如 "确认"、"继续"、"yes"、"allow"）时，该高风险工具才会被放行执行。这有效防止了模型跳过询问直接操作真实仓位。

当前后台工具：

screen_stocks、generate_ai_report、generate_strategy_decision、run_backtest

---

3.3 二次确认与用户意图判定策略

• 意图匹配白名单: 当 requires_approval=True 的工具（如持仓更新 update_portfolio）被调用时，ToolRegistry 不会当场弹出确认，而是优先扫描 messages 中的最近对话。
• 正向同意词匹配列表: 系统会提取 ask_user 调用之后的用户消息，移除所有特殊标点符号和空格后进行大小写无关的判定。正向同意词（Approved List）包括：
  • 中文："确认", "是", "好的", "继续", "同意", "允许"
  • 英文："yes", "allow", "y", "continue", "ok", "go ahead" 若在此轮对话中匹配到上述词汇，该高风险工具会被立即放行；否则工具将被拦截，并向模型返回错误提示，迫使其调用 ask_user 工具对用户发起弹窗/文字说明。

---

返回 系列索引