流程节点完善

PIPELINE_GUIDE.md

@@ -12,9 +12,13 @@ api[main.py /generate_plan] --> gen[py_tree_generator.generate]
 gen --> orch[GenerationOrchestrator]
 orch --> s1[Stage1 TaskUnderstanding]
 orch --> s2[Stage2 ContextBinding]
-orch --> s3[Stage3 BTPlanning]
-orch --> s4[Stage4 ValidateAndPostprocess]
-s4 --> out[返回 py_tree JSON]
+orch --> s3[Stage3 MacroPlanning]
+s3 --> simple{simple?}
+simple -->|是| s6[Stage6 Validate]
+simple -->|否| s4[Stage4 Middleware]
+s4 --> s5[Stage5 MicroFilling]
+s5 --> s6
+s6 --> out[返回 py_tree JSON]
 ```
 
 对应代码：
@@ -24,6 +28,65 @@ s4 --> out[返回 py_tree JSON]
 - `backend_service/src/pipeline/orchestrator.py`
 - `backend_service/src/pipeline/stages.py`
 
+### 1.1 各 Stage 提示词模板一览
+
+| Stage | 是否调用 LLM | System 模板/片段（按组合顺序） | User 内容 |
+|-------|----------------|--------------------------------|------------|
+| Stage1 | 是 | `prompts/scene_classifier_prompt.txt` | 原始 `user_prompt` |
+| Stage2 | 否 | — | — |
+| Stage3 | 是 | **simple**：`simple_mode_prompt.txt`；**complex**：`macro_header.txt` → 裁剪的 `core_nodes.json` → `template_ground.txt` / `template_air.txt` → `common_rules.txt` → 可选 `system_extra_examples.txt` → 意图标签 | `user_prompt` + 参考知识（地点/模式/规则） |
+| Stage4 | 否 | — | — |
+| Stage5 | 是 | `micro_header.txt` → macro_tree JSON → resolved_data JSON → 裁剪的 `atomic/nodes_schema.json` | 固定句：「请直接输出完整的带有 params 参数的 JSON 树结构。」 |
+| Stage6 | 否 | — | — |
+
+各阶段模板的详细组合顺序与条件见对应小节（如 2.3、3.3、4.3、5.3、6.3、7.3）。
+
+### 1.2 提示词分配流程图
+
+下图按 Stage 标出各阶段使用的提示词模板及组合关系（仅含涉及 LLM 的 Stage）：
+
+```mermaid
+flowchart TB
+  subgraph S1["Stage1 任务理解"]
+    direction TB
+    P1_sys["system: scene_classifier_prompt.txt"]
+    P1_usr["user: user_prompt"]
+  end
+
+  subgraph S2["Stage2 上下文绑定"]
+    P2["无 LLM / 无提示词"]
+  end
+
+  subgraph S3["Stage3 宏观规划"]
+    direction TB
+    P3a["simple: system = simple_mode_prompt.txt"]
+    P3b["complex: system = macro_header → core_nodes → template_ground/air → common_rules → 可选 system_extra_examples → 意图标签"]
+    P3_usr["user: user_prompt + 参考知识"]
+  end
+
+  subgraph S4["Stage4 中间层解析"]
+    P4["无 LLM / 无提示词"]
+  end
+
+  subgraph S5["Stage5 微观填参"]
+    direction TB
+    P5_sys["system: micro_header → macro_tree JSON → resolved_data JSON → atomic/nodes_schema 裁剪"]
+    P5_usr["user: 固定句"]
+  end
+
+  subgraph S6["Stage6 校验与后处理"]
+    P6["无 LLM / 无提示词"]
+  end
+
+  S1 --> S2 --> S3
+  S3 --> S4 --> S5 --> S6
+```
+
+- **Stage1 / Stage3 / Stage5** 会调用 LLM，其 System/User 内容由上图对应框内模板或片段组合而成。
+- **Stage2 / Stage4 / Stage6** 不调用 LLM，无提示词分配。
+
+---
+
 ## 2. Stage1：任务理解（TaskUnderstanding）
 
 功能：
@@ -80,6 +143,15 @@ s4 --> out[返回 py_tree JSON]
 - `risk_flags`: 风险标记列表（如 `needs_manual_confirmation`）
 - `constraints`: 约束占位（当前为空对象）
 
+### 2.3 本阶段组合的提示词模板
+
+| 角色   | 模板文件 | 路径 | 说明 |
+|--------|----------|------|------|
+| system | 场景分类 | `prompts/scene_classifier_prompt.txt` | 唯一 system 提示词，定义 simple/scene1/scene4 判定规则与示例 |
+| user   | 用户原文 | 调用方传入的 `user_prompt` | 不做拼接，直接作为 user 消息 |
+
+组合方式：`messages = [ { "role": "system", "content": scene_classifier_prompt }, { "role": "user", "content": user_prompt } ]`。分类结果解析为 `scene_mode`，其余 `intent_type`、`risk_flags` 由本阶段规则函数从 `user_prompt` 推断，不读模板。
+
 ## 3. Stage2：上下文绑定（ContextBinding）
 
 功能：
@@ -163,29 +235,32 @@ s4 --> out[返回 py_tree JSON]
 - `relative_refs`: 相对目标结构化描述
 - `required_actions`: 后续用于节点裁剪注入的动作白名单
 
-## 4. Stage3：BT 生成（BTPlanning）
+### 3.3 本阶段组合的提示词模板
+
+本阶段**不调用 LLM**，无提示词模板。仅做检索（Location/Pattern/Rules）、规则推导（`required_actions`、`relative_refs`）、预计算航点。
+
+---
+
+## 4. Stage3：宏观规划（Macro Planning，Round 1）
 
 功能：
 
-- 组装 prompt（骨架 + 节点裁剪 + 示例 + 规则 + 检索结果）
-- 调用对应模型生成严格 JSON
+- 组装 prompt（骨架 + 节点裁剪 + 模板 + 规则 + 检索结果）
+- 调用对应模型生成宏观树（及可选的 parameter_requests）
 - 解析模型响应（含 reasoning 提取）
 
 核心代码：
 
-- `backend_service/src/prompting/composer.py::PromptComposer`
+- `backend_service/src/prompting/composer.py::PromptComposer.compose_macro()`
 - `backend_service/src/llm/gateway.py::generate_json()`
-- `backend_service/src/llm/response_parser.py`
-- `backend_service/src/pipeline/stages.py::stage3_bt_planning()`
+- `backend_service/src/pipeline/stages.py::stage3_macro_planning()`
 - 数据契约：`backend_service/src/pipeline/contracts.py::BTDraft`
 
 关键行为：
 
-- simple 模式与复杂模式使用不同客户端/模型配置
-- Stage3 强制关闭 thinking，强制 `response_format=json_object`
-- 节点定义采用裁剪注入（非全量注入）
+- simple 模式与复杂模式使用不同客户端/模型配置；Stage3 强制关闭 thinking，强制 `response_format=json_object`；节点定义采用裁剪注入（非全量注入）。
 
-### 4.1 输入格式
+### 4.1 输入格式（Stage3）
 
 该阶段接收：
 
@@ -244,7 +319,82 @@ s4 --> out[返回 py_tree JSON]
 - `reasoning_text`: 可选推理文本（若模型返回）
 - `final_prompt`: 完整组合记录（便于离线排查）
 
-## 5. Stage4：校验与后处理（ValidateAndPostprocess）
+### 4.3 本阶段组合的提示词模板
+
+**simple 模式**（单轮，直接出最终树）：
+
+| 角色   | 模板/内容 | 路径 | 说明 |
+|--------|------------|------|------|
+| system | 简单模式全文 | `prompts/simple_mode_prompt.txt` | 直接作为 system，无拼接 |
+| user   | 用户原文 + 参考知识 | 动态 | `user_prompt` + `_build_user_augmentation(context_blocks)` |
+
+**复杂模式**（scene1/scene4，宏观树 Round 1）：
+
+System 按**顺序**拼接以下内容（来自 `prompting/composer.py::compose_macro()`）：
+
+| 顺序 | 模板/内容 | 路径 | 说明 |
+|------|-----------|------|------|
+| 1 | 宏观任务头 | `prompts/partials/macro_header.txt` | 任务定义与输出要求 |
+| 2 | 节点定义（裁剪后） | `prompts/partials/core_nodes.json` | 按 `required_actions` + `risk_flags` 裁剪，最多 30 个 action/condition，格式化为「## 一、核心节点定义」+ JSON 代码块 |
+| 3 | 任务模板（二选一） | `prompts/partials/template_ground.txt` 或 `prompts/partials/template_air.txt` | 由 `drone_state`（on_ground / in_air）决定 |
+| 4 | 通用规则 | `prompts/partials/common_rules.txt` | 若文件存在则追加 |
+| 5 | 额外示例（可选） | `prompts/partials/system_extra_examples.txt` | 仅当 `intent_type == "generic_mission"` 时追加 |
+| 6 | 意图标签 | 代码生成 | 固定段落：`## 任务意图标签\n- intent_type: \`{intent_type}\`` |
+
+User 消息：
+
+- 内容 = `user_prompt` + 参考知识增强段。
+- 参考知识增强段由 `_build_user_augmentation(context_blocks)` 生成：若 `context_blocks` 中 `location` / `pattern` / `rules` 非空，则按顺序拼接为「【地点知识】…」「【任务模式】…」「【规则知识】…」，整体包在 `---\n参考知识：\n…\n---` 中。
+
+---
+
+## 5. Stage4：中间层解析（Middleware Resolution）
+
+功能：
+
+- 读取 Stage3 输出的 `parameter_requests`
+- 对含 `landmark` 等实体的请求做位置检索与航点预计算，写入 `resolved_data`
+- 其他实体透传为 `{node}_entities`，供 Stage5 使用
+
+核心代码：
+
+- `backend_service/src/pipeline/stages.py::stage4_middleware_resolution()`
+- 复用 `retriever.retrieve(scopes=["location"])` 与 `tool_runtime.build_precomputed_waypoint()`
+
+### 5.3 本阶段组合的提示词模板
+
+本阶段**不调用 LLM**，无提示词模板。仅做依赖解析与数据绑定。
+
+---
+
+## 6. Stage5：微观参数填空（Micro Parameter Filling，Round 2）
+
+功能：
+
+- 从 `prompts/atomic/nodes_schema.json` 按宏观树中用到的节点名裁剪出 `atomic_schema`
+- 调用 `PromptComposer.compose_micro()` 组装 Round 2 的 system 提示词
+- 再次调用模型，输出带完整 `params` 的 JSON 树
+
+核心代码：
+
+- `backend_service/src/prompting/composer.py::compose_micro()`
+- `backend_service/src/pipeline/stages.py::stage5_micro_filling()`
+
+### 6.3 本阶段组合的提示词模板
+
+| 角色   | 模板/内容 | 路径 | 说明 |
+|--------|------------|------|------|
+| system | 微观任务头 | `prompts/partials/micro_header.txt` | 第一段 |
+| system | 宏观骨架树 | 运行时 | `## 1. 原宏观骨架树 (macro_tree)` + `draft.macro_tree` 的 JSON |
+| system | 确切数据字典 | 运行时 | `## 2. 确切数据字典 (resolved_data)` + Stage4 输出的 `resolved_data` JSON |
+| system | 原子节点规范 | `prompts/atomic/nodes_schema.json`（按需裁剪） | `## 3. 原子节点规范 (atomic_schema)`；仅保留宏观树中出现的 action/condition 的 schema |
+| user   | 固定指令 | 代码写死 | `"请直接输出完整的带有 params 参数的 JSON 树结构。"` |
+
+组合方式：system = 上述四段用 `\n\n` 拼接；user = 固定字符串。Round 2 不再注入 RAG 检索块。
+
+---
+
+## 7. Stage6：校验与后处理（ValidateAndPostprocess）
 
 功能：
 
@@ -257,11 +407,11 @@ s4 --> out[返回 py_tree JSON]
 
 - `backend_service/src/validation/validator.py`
 - `backend_service/src/validation/schema_provider.py`
-- `backend_service/src/pipeline/stages.py::stage4_validate_and_postprocess()`
+- `backend_service/src/pipeline/stages.py::stage6_validate_and_postprocess()`
 - `backend_service/src/py_tree_generator.py::render_visualization()`
 - `backend_service/src/py_tree_generator.py::_save_history()`
 
-### 5.1 输入格式
+### 7.1 输入格式
 
 该阶段接收：
 
@@ -269,10 +419,9 @@ s4 --> out[返回 py_tree JSON]
 - `TaskUnderstanding`
 - `ContextBinding`
 - `BTDraft`
+- 复杂模式下还有 Stage5 的 `final_tree`；simple 模式下为 `draft.llm_raw_json`
 
-其中主载荷来自 `BTDraft.llm_raw_json`。
-
-### 5.2 输出格式（最终 API 返回）
+### 7.2 输出格式（最终 API 返回）
 
 复杂模式示例：
 
@@ -326,7 +475,13 @@ simple 模式示例：
 - `visualization_url`: 最新可视化图访问路径
 - `final_prompt`: 生成时使用的完整提示词记录
 
-## 6. 数据入库（RAG Ingestion）逻辑
+### 7.3 本阶段组合的提示词模板
+
+本阶段**不调用 LLM**，无提示词模板。仅做校验、注入元数据与写盘。
+
+---
+
+## 8. 数据入库（RAG Ingestion）逻辑
 
 入库脚本：
 
@@ -340,9 +495,9 @@ simple 模式示例：
   - `drone_docs`（兼容）
   - `location_kb` / `pattern_kb` / `rules_kb`（新检索路径）
 
-## 7. 可自定义修改点（推荐按优先级）
+## 9. 可自定义修改点（推荐按优先级）
 
-### 7.1 场景与意图逻辑
+### 9.1 场景与意图逻辑
 
 可改文件：
 
@@ -354,7 +509,7 @@ simple 模式示例：
 - `_extract_risk_flags()`：新增风险规则
 - `_derive_required_actions()`：调整规则推导的动作集合
 
-### 7.2 Prompt 策略
+### 9.2 Prompt 策略
 
 可改文件：
 
@@ -369,7 +524,7 @@ simple 模式示例：
 - 示例注入策略（何时注入 extra examples）
 - 用户侧检索增强格式
 
-### 7.3 模型路由与推理参数
+### 9.3 模型路由与推理参数
 
 可改文件：
 
@@ -381,7 +536,7 @@ simple 模式示例：
 - `temperature`、`max_tokens`、重试次数
 - thinking 开关策略（Stage1/Stage3）
 
-### 7.4 检索策略
+### 9.4 检索策略
 
 可改文件：
 
@@ -396,7 +551,7 @@ simple 模式示例：
 - kb_type 划分方式
 - 文档切分与 metadata 设计
 
-### 7.5 相对目标解析
+### 9.5 相对目标解析
 
 可改文件：
 
@@ -409,7 +564,7 @@ simple 模式示例：
 - 静态解析能力（何时生成 `resolved_refs`）
 - 与 UAV 端协议字段兼容策略
 
-### 7.6 校验与输出协议
+### 9.6 校验与输出协议
 
 可改文件：
 
@@ -423,7 +578,7 @@ simple 模式示例：
 - 顶层 `context` 字段的可选校验
 - 失败错误信息与恢复策略
 
-## 8. 关键环境变量
+## 10. 关键环境变量
 
 - `ORIN_IP`
 - `OPENAI_API_KEY`
@@ -433,14 +588,14 @@ simple 模式示例：
 - `ENABLE_REASONING_CAPTURE`
 - `REASONING_PREVIEW_LINES`
 
-## 9. 自定义改造建议（实践顺序）
+## 11. 自定义改造建议（实践顺序）
 
 1. 先改 Stage1 规则推导（低风险，收益快）
 2. 再改 PromptComposer 的裁剪与注入（控制长度与稳定性）
 3. 再改检索策略（top_k、回退、metadata）
 4. 最后改 schema 与输出协议（需联动执行端）
 
-## 10. 变更后最小回归清单
+## 12. 变更后最小回归清单
 
 每次改造后至少验证：