lzb/agent-b4

0 Fork 0

T

lzb 60f2cfbb68 删除 B4_VERIFICATION.md

2026-07-14 21:33:28 +08:00

agent

B4模块完整代码：Agent LLM决策模块

2026-07-14 21:09:54 +08:00

.gitignore

添加 .gitignore + B4_VERIFICATION.md

2026-07-14 21:29:20 +08:00

README.md

更新 README.md

2026-07-14 21:14:57 +08:00

README.md

B4 模块 — LLM 调用与工具路由核心

1. 模块概述

1.1 模块名称

B4 — LLM 调用与指令解析模块（b4_local_agent_llm）

1.2 模块说明

B4 模块是 Agent 系统的 "智能核心"，负责将原始的 LLM（大语言模型）接入结构化的 Agent 框架。它将 B1 调度器传递的用户对话和工具定义转化为 LLM 能够理解的提示词，调用本地部署的 LLM 进行推理，并将模型输出解析为结构化的 AI_Message（含 content 或 tool_calls），供 B1 调度器决策下一步操作。

核心能力：
- 加载与管理多个本地 LLM（支持 small/large 双模型）
- 通过提示词工程约束 LLM 输出严格 JSON 格式
- 解析 LLM 输出为规范 AI_Message（最终回答 / 工具调用）
- 支持 Plan-and-Execute：复杂任务自动分解为多步执行
- 支持 Multi-tool：单轮多个工具并行调用
- 通过路由策略（auto）按任务难度自动切换模型

1.3 完成情况概览

类型	完成情况
基础要求	✅ 实现 LLM 调用、JSON 格式输出、单工具调用、输出解析容错
进阶要求	✅ 五项扩展全部完成（Multi-tool、Plan-and-Execute、模型路由、tools_schema 对比、批量评测）
可独立运行的演示	✅ 见第 4 节和第 5 节的演示命令，通过 CLI 直接运行
与团队系统集成情况	B1 调度器通过 `generate_ai_message()` 调用本模块，B4 返回 `AI_Message` 供 B1 决策

2. 环境、模型与数据依赖

2.1 运行环境

项目	要求
Python 版本	3.10
必要依赖	`torch`, `transformers`, `pyyaml`（见 `requirements.txt`）
是否需要模型	需要 — 本地部署 Qwen3.5-4B
是否需要 GPU	推荐 — 建议 16GiB+ 显存；CPU 也可运行但速度较慢
是否需要外部数据集	不需要（测试数据在 `data/messages/` 中自带）

2.2 模型依赖

模型	来源	项目内相对路径	用途
Qwen3.5-4B	ModelScope: Qwen/Qwen3.5-4B	`/root/siton-pub/assignment_B/Qwen3.5-4B`（可配置）	large 模型，复杂推理与工具调用
Qwen3-1.7B	ModelScope: Qwen/Qwen3-1.7B	需额外下载（可配置）	small 模型，简单问答

# 模型下载命令（使用 modelscope）
pip install modelscope
modelscope download --model Qwen/Qwen3.5-4B --local_dir /root/siton-pub/assignment_B/Qwen3.5-4B

2.3 数据集或样例数据依赖

数据或文件	来源	项目内相对路径	用途
test messages	自行构造	`data/messages/`	25 个测试用例覆盖 5 工具 × 5 难度
tools_schema	团队 B3 模块输出	`data/messages/tools_schema_basic.json`	工具定义描述
model.yaml	团队配置	`configs/model.yaml`	模型 profile 配置（需配置模型路径）
tools.yaml	团队配置	`configs/tools.yaml`	Plan 模式工具执行配置

2.4 安装步骤

# 1. 创建 conda 环境
conda create -n agent python=3.10 -y
conda activate agent

# 2. 进入项目目录并安装依赖
cd /root/siton-pub/assignment_B/agent
pip install -r requirements.txt

# 3. 如需下载模型（若模型尚未下载）
pip install modelscope
modelscope download --model Qwen/Qwen3.5-4B --local_dir /root/siton-pub/assignment_B/Qwen3.5-4B

重要：运行前请确保 configs/model.yaml 中的 model_name_or_path 路径指向正确的模型本地路径。

3. 文件结构与接口边界

3.1 文件结构

agent/
├── code/
│   ├── b4_local_agent_llm.py    # B4 核心模块（LLM 调用、解析、Plan 引擎）
│   ├── common/
│   │   ├── io_utils.py          # JSON/JSONL 读写工具
│   │   ├── logging_utils.py     # 日志工具
│   │   └── schemas.py           # AI_Message 数据结构定义与校验
│   ├── b3_tool_layer.py         # B3 工具层（B4 在 Plan 模式下直接调用）
│   └── README.md                # 本文件
├── configs/
│   ├── model.yaml               # 模型配置（模型路径、generation 参数）
│   └── tools.yaml               # 工具注册配置
├── data/
│   └── messages/                # 测试用例消息文件
│       ├── messages_simple_task.json             # 简单任务（25+37）
│       ├── messages_complex_task.json            # 复杂任务（天平称量）
│       ├── messages_chicken_rabbit.json          # 鸡兔同笼
│       ├── messages_no_tool.json                 # 无需工具的任务
│       ├── messages_with_tool.json               # 含 tool_calls 上下文
│       ├── messages_with_error_tool.json         # 工具错误场景
│       ├── messages_with_multi_tool.json         # 多工具并行
│       ├── messages_no_tool_but_require_multi_tool.json
│       ├── messages_compare_both_modes.json
│       ├── messages_tool_test_01~05_*.json       # file_reader 5 级难度
│       ├── messages_calc_test_01~05_*.json       # calculator 5 级难度
│       ├── messages_search_test_01~05_*.json     # local_file_search 5 级难度
│       ├── messages_table_test_01~05_*.json      # table_analyzer 5 级难度
│       ├── messages_format_test_01~05_*.json     # format_converter 5 级难度
│       └── tools_schema_basic.json              # 工具 schema 定义
├── outputs/                    # 运行输出目录（自动生成）
│   └── B4_llm/
│       ├── no_tool_real/       # 基础演示 1 输出
│       ├── with_tool_real/     # 基础演示 2 输出
│       ├── error_tool_real/    # 基础演示 3 输出
│       ├── plan_demo/         # Plan-and-Execute 输出
│       ├── chicken_rabbit_*/  # 工具模式对比输出
│       ├── benchmark/         # 批量评测汇总结果
│       └── ...
├── test_tool_call.py           # 批量评测脚本（50 次测试）
├── test_plan_execute.py        # Plan-and-Execute 测试脚本
└── requirements.txt            # Python 依赖

3.2 接口边界

类型	来源 / 去向	数据格式	说明
输入	B1 调度器调用	`messages: list[dict]`（对话历史）	含 system/user/assistant/tool 角色
输入	B1 调度器调用	`tools_schema: list[dict]`	B3 生成的工具 JSON Schema
输入	B1 调度器调用	`model_config: str`	model.yaml 路径
输入	B1 调度器调用	`model_profile: str`	small / large / auto
输入	B1 调度器调用	`plan_and_execute: str`	plan / execute / None
输入	B1 调度器调用	`tools_config: str`	tools.yaml 路径（Plan 模式需要）
输入	B1 调度器调用	`use_native_tools: bool`	是否使用原生 tools 传参
输出	返回 B1 调度器	`ai_message: dict`	含 `content`（回答）或 `tool_calls`（工具调用）
输出	磁盘文件	`raw_model_output.json`	完整运行日志与调试信息
输出	磁盘文件	`plan.json`	Plan 模式下每一步的状态持久化
内部调用	B3 工具层	`tool_calls → execute_tool_calls()`	Plan 模式直接调用 B3 执行工具

4. 基础要求实现与演示

4.1 基础功能说明

基础功能实现了 LLM 调用的全链路：
1. 加载本地模型与分词器
2. 构建提示词（注入 tools_schema + 输出格式约束）
3. 调用 LLM 推理生成
4. 解析模型输出（三级容错：标准 JSON → 反引号 → 片段提取）
5. 返回规范 AI_Message

4.2 基础功能实现路径

文件 / 函数	作用
`generate_ai_message()`	对外唯一接口，接收 B1 请求并返回 AI_Message
`_prompt_json_generate()`	加载模型、构建提示词、调用推理、解析输出
`_build_prompt_messages()`	注入 tools_schema + 格式指令 + 工具结果引导
`_parse_model_output()`	三级容错解析 LLM 原始输出
`_parse_json_with_backtick_tail()`	容错处理：去除前导/尾部反引号包裹
`_parse_tool_calls_fragment()`	容错处理：从非 JSON 文本提取 tool_calls
`make_ai_message()`	构建规范 AI_Message 数据结构（common/schemas.py）
`validate_ai_message()`	校验 content 和 tool_calls 的互斥性

[用户消息 + tools_schema] → _build_prompt_messages → model.generate → _parse_model_output → AI_Message

4.3 基础功能输入格式与样例

字段 / 输入文件	类型 / 格式	是否必需	说明
`model_config`	文件路径 (str)	是	model.yaml 配置文件路径
`messages`	JSON 列表 (list[dict])	是	对话历史，至少含一条 user 消息
`tools_schema`	JSON 列表 (list[dict])	是	工具定义数组
`mode`	字符串 (str)	是	`prompt_json`（LLM）/ `mock`（模拟）
`outdir`	文件路径 (str)	是	输出目录
`model_profile`	字符串 (str)	否	默认 large，可选 small/auto

样例输入：

样例文件	用途
`data/messages/messages_simple_task.json`	简单计算，验证基础推理能力
`data/messages/messages_chicken_rabbit.json`	鸡兔同笼，验证逻辑推理能力
`data/messages/messages_no_tool.json`	需根据已有信息回答，验证无工具场景

4.4 基础功能演示命令

cd agent/code

# 基础演示 1：接收初始 messages，生成包含 tool_calls 的 AIMessage
python b4_local_agent_llm.py \
    --model_config ../configs/model.yaml \
    --messages ../data/messages/messages_no_tool.json \
    --tools_schema ../data/messages/tools_schema_basic.json \
    --mode prompt_json \
    --outdir ../outputs/B4_llm/no_tool_real

# 基础演示 2：接收已包含 ToolMessage 的 messages，生成最终回答的 AIMessage
python b4_local_agent_llm.py \
    --model_config ../configs/model.yaml \
    --messages ../data/messages/messages_with_tool.json \
    --tools_schema ../data/messages/tools_schema_basic.json \
    --mode prompt_json \
    --outdir ../outputs/B4_llm/with_tool_real

# 基础演示 3：工具调用失败后的模型回答
python b4_local_agent_llm.py \
    --model_config ../configs/model.yaml \
    --messages ../data/messages/messages_with_error_tool.json \
    --tools_schema ../data/messages/tools_schema_basic.json \
    --mode prompt_json \
    --outdir ../outputs/B4_llm/error_tool_real

观察现象：

每个命令运行后，输出目录生成 raw_model_output.json，包含模型原始输出、解析结果、状态信息
演示 1：content 非空，tool_calls 为空（无需工具）
演示 2：content 为基于已有工具结果生成的回答
演示 3：content 包含工具失败原因解释，不再重复调用工具

4.5 基础功能输出格式

输出文件 / 返回字段	格式	说明
`raw_model_output.json`	JSON	完整运行日志，含 raw_text、parsed_candidate、status、error
`ai_message.json`	JSON	规范 AI_Message：`{role, content, tool_calls}`
`llm_run_log.jsonl`	JSONL	运行时间戳日志

4.6 基础功能结果

// 演示 1 输出示例（no_tool_real/raw_model_output.json）
{
  "raw_text": "{\"content\":\"62\",\"tool_calls\":[]}",
  "parsed_candidate": {"content": "62", "tool_calls": []},
  "status": "success",
  "error": null
}

// 演示 2 输出示例（with_tool_real/raw_model_output.json）
{
  "raw_text": "{\"content\":\"1. Agent系统由模型、工具、记忆和执行循环组成。\\n2. 工具调用让模型能够读取文件...\",\"tool_calls\":[]}",
  "parsed_candidate": {"content": "1. Agent系统由模型、工具...", "tool_calls": []},
  "status": "success",
  "error": null
}

5. 进阶要求实现与演示

5.1 选择的进阶要求

进阶要求	是否完成	对应文件 / 函数	简要说明
单轮多 tool_calls 生成与多 ToolMessage 接收	✅ 完成	`_build_prompt_messages()`	修改提示词示例，支持并行多工具调用
Plan-and-Execute	✅ 完成	`_auto_execute_step()`, `_generate_plan()`, `_execute_plan_step()`	复杂任务自动分解、逐步执行、结果合并
多模型切换与路由	✅ 完成	`_router_classify()`, `_load_model_from_profile()`	small/large/auto 三种模式
tools_schema 对比	✅ 完成	`use_native_tools` 参数	Prompt 注入 vs 原生 tools 传参
批量评测与统计	✅ 完成	`test_tool_call.py`	50 次系统测试，量化对比两模型

5.2 进阶功能一：单轮多 tool_calls 生成与多 ToolMessage 接收

功能说明

允许 LLM 在单次输出中包含多个独立工具调用（如同时调用 file_reader 和 calculator），
减少 LLM 与调度器之间的交互轮次，提高任务执行效率。
执行多条工具后，LLM 能综合接收多条 ToolMessage 的结果并给出最终回答。

实现路径

文件 / 函数	作用
`_build_prompt_messages()`	在格式 B 的示例中增加 multi-tool 样例

# 核心改动：提示词中增加 multi-tool 示例
"If the task involves multiple independent parts (e.g. read a file and do a calculation),\n"
"you can use Multi-tool: include multiple tool_call objects in the tool_calls array.\n\n"
"Valid schema B (Multi-tool example):\n"
'{"content":"","tool_calls":[{"id":"call_001","name":"file_reader",'
'"args":{"path":"docs/1.md","max_chars":2000}},'
'{"id":"call_002","name":"calculator",'
'"args":{"expression":"12 * 12"}}]}\n'

演示命令

cd agent/code

# Multi-tool 生成
python b4_local_agent_llm.py \
    --model_config ../configs/model.yaml \
    --messages ../data/messages/messages_no_tool_but_require_multi_tool.json \
    --tools_schema ../data/messages/tools_schema_basic.json \
    --mode prompt_json \
    --outdir ../outputs/B4_llm/with_ask_multi_tool

# Multi-ToolMessage 接收（已有双工具调用结果）
python b4_local_agent_llm.py \
    --model_config ../configs/model.yaml \
    --messages ../data/messages/messages_with_multi_tool.json \
    --tools_schema ../data/messages/tools_schema_basic.json \
    --mode prompt_json \
    --outdir ../outputs/B4_llm/with_multi_tool_real

输出结果

{
  "role": "assistant",
  "content": "该文件总结了注入类攻击（SQL注入、命令注入）、跨站脚本（XSS）和身份访问控制类攻击（CSRF、权限控制失效）等Web安全风险，计算结果12 * 32 + 65 - 3 = 448。",
  "tool_calls": []
}

LLM 成功综合了文件读取和数学计算两条工具结果，合并为一个连贯的回答。

5.3 进阶功能二：tools_schema 对比（原生传参 vs Prompt 注入）

功能说明

对比 Hugging Face Transformers 原生 tools 参数传参与传统 prompt 注入两种方式的效果。
- 原生方式：通过 tokenizer.apply_chat_template(tools=...) 结构化传入
- Prompt 注入：将 tools_schema 以 JSON 文本拼入 system prompt

实现路径

文件 / 函数	作用
`_build_prompt_messages()`	`native_tool_calling` 参数控制提示词构造方式
`_parse_model_output()`	prompt 注入方式的 JSON 三级容错解析
`_parse_tool_call_xml()`	原生传参方式的 XML 解析

演示命令

cd agent/code

# Prompt 注入方式（默认）
python b4_local_agent_llm.py \
    --model_config ../configs/model.yaml \
    --messages ../data/messages/messages_chicken_rabbit.json \
    --tools_schema ../data/messages/tools_schema_basic.json \
    --mode prompt_json \
    --outdir ../outputs/B4_llm/chicken_rabbit_original

# 原生传参方式
python b4_local_agent_llm.py \
    --model_config ../configs/model.yaml \
    --messages ../data/messages/messages_chicken_rabbit.json \
    --tools_schema ../data/messages/tools_schema_basic.json \
    --mode prompt_json \
    --outdir ../outputs/B4_llm/chicken_rabbit_native \
    --use_native_tools

输出对比

// Prompt 注入方式 → 直接给出答案（无需工具）
{
  "role": "assistant",
  "content": "设鸡有x只，兔有y只...所以兔有12只，鸡有23只。",
  "tool_calls": []
}

// 原生传参方式 → 调用 calculator 工具
{
  "role": "assistant",
  "content": "",
  "tool_calls": [
    {
      "id": "call_001",
      "name": "calculator",
      "args": {"expression": "(94 - 35 * 2) / (4 - 2)"}
    }
  ]
}

结论：Prompt 注入方式下 LLM 倾向于直接回答（自己计算），原生传参方式下 LLM 更愿意调用工具。原生方式输出格式更规范，解析成功率更高。

5.4 进阶功能三：多模型切换与路由

功能说明

支持根据 model_profile 参数选择不同规模的模型：
- small（Qwen3-1.7B）：快速响应，适合简单问答（~2秒）
- large（Qwen3.5-4B）：高准确率，适合复杂推理与工具调用
- auto：先用 small 模型分类难度，easy 用 small，difficult 切换为 large

实现路径

文件 / 函数	作用
`_load_model_from_profile()`	按 profile 加载对应模型到全局缓存
`_router_classify()`	auto 模式：用 small 模型做二分类（easy/difficult）
`_MODEL_CACHE`	全局模型缓存，同一 profile 避免重复加载

[用户请求] → model_profile 检查
    ├─ small → 直接使用 Qwen3-1.7B
    ├─ large → 直接使用 Qwen3.5-4B
    └─ auto → small 模型分类
        ├─ "easy" → small 模型执行（如简单计算）
        └─ "difficult" → 释放缓存 → large 模型执行（如复杂推理）

演示命令

cd agent/code

# small 模型（简单任务）
python b4_local_agent_llm.py \
    --model_config ../configs/model.yaml \
    --messages ../data/messages/messages_simple_task.json \
    --tools_schema ../data/messages/tools_schema_basic.json \
    --mode prompt_json \
    --outdir ../outputs/B4_llm/simple_small \
    --model_profile small

# large 模型（简单任务）
python b4_local_agent_llm.py \
    --model_config ../configs/model.yaml \
    --messages ../data/messages/messages_simple_task.json \
    --tools_schema ../data/messages/tools_schema_basic.json \
    --mode prompt_json \
    --outdir ../outputs/B4_llm/simple_large \
    --model_profile large

# auto 模式（按任务难度自动选择）
python b4_local_agent_llm.py \
    --model_config ../configs/model.yaml \
    --messages ../data/messages/messages_simple_task.json \
    --tools_schema ../data/messages/tools_schema_basic.json \
    --mode prompt_json \
    --outdir ../outputs/B4_llm/complex_small \
    --model_profile auto

输出对比

// small 模型 → "25 + 37 = 62"
// large 模型 → "62"

// auto 模式（简单任务）→ 选择 small 模型，输出 router_result.txt = "easy"
// auto 模式（复杂任务：天平称量）→ 选择 large 模型，输出 router_result.txt = "difficult"

5.5 进阶功能四：Plan-and-Execute

功能说明

让 LLM 自主将复杂任务分解为多步计划（plan_map），并按顺序逐步执行。
每个步骤独立调用 LLM、可调用工具、可查看前面步骤的结果。
所有执行在 B4 内部完成，对外返回一个普通的 AI_Message（纯 content），
B1 模块无需修改即可兼容。

实现路径

文件 / 函数	作用
`_generate_plan()`	调用 LLM 生成 plan_map（步骤列表）
`_auto_execute_step()`	单步执行引擎：LLM → tool_calls → B3 执行 → 注入 → 继续，直到输出 content
`_execute_plan_step()`	构建 step 提示词（plan 上下文 + 全局 messages）
`_parse_plan_output()`	解析 plan_map JSON
`_parse_plan_step_output()`	解析 step 执行结果的 JSON

[用户输入] → _generate_plan → plan_map（步骤列表）
    → 遍历每个 step → _auto_execute_step
        → _execute_plan_step（提示词 + 工具）
        → 解析 → 有 tool_calls？→ B3 执行 → 循环
        → 有 content？→ step 完成 → 更新 plan.json
    → 全部完成 → 合并结果 → 返回普通 AI_Message

演示命令

cd agent/code

# 步骤 1：先生成计划（plan 模式）
python b4_local_agent_llm.py \
    --model_config ../configs/model.yaml \
    --messages ../data/messages/messages_no_tool.json \
    --tools_schema ../data/messages/tools_schema_basic.json \
    --mode prompt_json \
    --outdir ../outputs/B4_llm/plan_step \
    --plan_and_execute plan

# 步骤 2：从 plan.json 继续执行（execute 模式）
python b4_local_agent_llm.py \
    --model_config ../configs/model.yaml \
    --messages ../data/messages/messages_no_tool.json \
    --tools_schema ../data/messages/tools_schema_basic.json \
    --mode prompt_json \
    --outdir ../outputs/B4_llm/plan_step \
    --tools_config ../configs/tools.yaml \
    --plan_and_execute execute

输出结果

{
  "role": "assistant",
  "content": "步骤1: 阅读 docs/agent_intro.txt 文件\n结果: Agent 系统通常由模型、工具、记忆和执行循环组成。工具调用让模型能够读取本地文件、执行计算，并把结果用于后续回答。\n\n步骤2: 总结文件内容\n结果: Agent 系统通常由模型、工具、记忆和执行循环组成。",
  "tool_calls": []
}

5.6 进阶功能五：批量评测与统计

功能说明

通过 50 次系统化测试（5 工具 × 5 难度 × 2 模型），量化对比不同模型
在工具调用成功率和 token 使用量上的差异，为 auto 路由策略提供数据支撑。

实现路径

文件 / 函数	作用
`test_tool_call.py`	自动批量测试脚本（先模型后用例循环，每模型只加载一次）
`data/messages/messages__test_01~05_.json`	25 个测试用例文件

[脚本] → 遍历模型（small → large）→ 遍历工具（5种）→ 遍历难度（5级）
    → 调用 generate_ai_message → 记录状态、token、延迟
    → 统计：成功率、工具调用率、平均 token、平均延迟

演示命令

cd /root/siton-pub/assignment_B/agent
python test_tool_call.py

统计结果

整体统计（50 次测试）：
- 解析成功率：94%
- 工具调用率：50%
- 平均 Token：54.8
- 平均延迟：25.6秒

模型对比：
- Qwen3-1.7B (small)：92% 成功率 / 40% 工具调用率 / ~1.9秒
- Qwen3.5-4B (large)：96% 成功率 / 60% 工具调用率 / ~49.4秒

各工具调用率：
- table_analyzer：80%     （最高）
- file_reader：70%
- local_file_search：70%
- calculator：20%
- format_converter：10%   （最低）

指令难度影响（full_results 见 outputs/B4_llm/benchmark/）：
- 显式指令：90%
- 直接指令 / 中等委婉：50%
- 隐含需求 / 自然语言：30%

6. 与团队系统的集成说明

调用方式

团队完整系统中，B1 调度器通过以下方式调用 B4 模块：

from code.b4_local_agent_llm import generate_ai_message

result = generate_ai_message(
    model_config="configs/model.yaml",
    messages=[...],           # 对话历史（B5 注入记忆 + 用户输入）
    tools_schema=[...],       # 工具定义（B3 提供）
    mode="prompt_json",
    outdir="outputs/...",
    artifact_stem="...",
    model_profile="large",    # 或 "small"、"auto"
)
ai_message = result["ai_message"]
# ai_message = {"content": "...", "tool_calls": [...]}

数据流

B1 调度器
  │  messages + tools_schema + model_config
  ▼
B4 generate_ai_message()
  │  model.generate → 解析输出
  ▼
AI_Message { content / tool_calls }
  │
  ├─ content 非空 → B1 返回给用户
  └─ tool_calls 非空 → B1 调用 B3 执行工具 → 追加结果 → 再次调用 B4

Plan 模式下的直接调用

在 plan_and_execute="plan" 模式下，B4 绕过 B1 直接调用 B3 的 execute_tool_calls() 执行工具：

import importlib.util
b3_path = Path(__file__).parent / "b3_tool_layer.py"
spec = importlib.util.spec_from_file_location("b3_tool_layer_mod", b3_path)
b3_mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(b3_mod)
tool_msgs = b3_mod.execute_tool_calls(tool_calls, tools_config)

配置文件依赖

B4 模块需要团队仓库中的两个配置文件：

configs/model.yaml：定义模型的路径、device_map、generation 参数
configs/tools.yaml：定义各工具的技能函数映射（Plan 模式下需要）

联调经验

在 Plan-and-Execute 开发中，最初的设计方案是新增 plan 字段到 AI_Message 中，让 B1 特判处理。但这会导致接口污染：B1 需要新增 plan 相关的调度逻辑，其他组员需要适配新的字段。

最终改为 "内部闭环、对外透明" 方案——所有 plan 逻辑在 B4 内部完成，通过 importlib 直接加载 B3 模块并调用 execute_tool_calls()，对外接口不变。这验证了团队协作中 "接口稳定比功能丰富更重要" 的原则。

7. 已知问题与后续改进

问题	当前原因	后续改进
Plan-and-Execute 中不支持嵌套计划	`_auto_execute_step` 无递归逻辑	添加递归检测，当某 step 结果仍为 plan_map 时触发嵌套执行
可调用模型有限	仅支持本地 transformers 后端	扩展后端抽象层，支持 OpenAI API、vLLM 等远程调用方式
small 模型偶尔输出不稳定（重复 tool_calls）	Qwen3-1.7B 参数量小，对工具结果理解有限	加入重复检测 + 强制引导，建议复杂任务使用 large 模型
JSON 解析容错仍有缺口	模型输出格式多变，边界情况难全覆盖	持续收集异常输出模式，扩展处理逻辑
批量评测不支持并行	50 次测试串行约需 20 分钟	引入多线程/多进程并行执行

README.md Unescape Escape

B4 模块 — LLM 调用与工具路由核心

1. 模块概述

1.1 模块名称

1.2 模块说明

1.3 完成情况概览

2. 环境、模型与数据依赖

2.1 运行环境

2.2 模型依赖

2.3 数据集或样例数据依赖

2.4 安装步骤

3. 文件结构与接口边界

3.1 文件结构

3.2 接口边界

4. 基础要求实现与演示

4.1 基础功能说明

4.2 基础功能实现路径

4.3 基础功能输入格式与样例

4.4 基础功能演示命令

4.5 基础功能输出格式

4.6 基础功能结果

5. 进阶要求实现与演示

5.1 选择的进阶要求

5.2 进阶功能一：单轮多 tool_calls 生成与多 ToolMessage 接收

功能说明

实现路径

演示命令

输出结果

5.3 进阶功能二：tools_schema 对比（原生传参 vs Prompt 注入）

功能说明

实现路径

演示命令

输出对比

5.4 进阶功能三：多模型切换与路由

功能说明

实现路径

演示命令

输出对比

5.5 进阶功能四：Plan-and-Execute

功能说明

实现路径

演示命令

输出结果

5.6 进阶功能五：批量评测与统计

功能说明

实现路径

演示命令

统计结果

6. 与团队系统的集成说明

调用方式

数据流

Plan 模式下的直接调用

配置文件依赖

联调经验

7. 已知问题与后续改进

README.md