工具系统实践与注意事项

适用版本：4.0.8.1+

本页对应“其他事项，你补充”。

1) 输出结构建议

• 新代码统一使用：next_action + execution_commands[]
• execution_commands 内每项保留 todo_suggestion
• 避免混用历史字段（如 tool_commands）作为主输出

2) 安全边界

• 对高风险工具（Cmd、DB、外部写操作）做双层控制：
  • 参数校验
  • allowlist（命令前缀、目录、资源范围）
• 不要让模型直接拼接危险命令

3) 并发与超时

• 先保守设置：max_rounds=3~5、concurrency=1~3
• 对慢工具设置 tool.loop.timeout
• 并发提高前先确认外部依赖（API/浏览器/DB）可承受

4) 观测与排障

• 开启 runtime.show_tool_logs
• 首选检查 extra.tool_logs
• 关注每条记录的 success/error/result

5) 测试建议

• 给 plan handler 和 execution handler 各写最小回归测试
• 重点覆盖：
  • next_action=response 的短路
  • 并发执行下记录顺序与完整性
  • 工具失败时的错误记录

6) 迁移建议

• must_call() / async_must_call() 仅作软兼容；新代码使用 generate_tool_command()
• 旧逻辑升级时，优先保证规划输出结构稳定，再替换执行器

7) 与 Browse/搜索链路配合

若用于“search -> browse”链路，建议：

1. 在计划阶段强制要求引用来源 URL
2. Browse 结果只当证据，不直接当最终答案
3. 在最终输出中附上引用点，便于审计