how agent 部分推导成功 update

examples_how/overall_derivation/derivation_main.md

@@ -27,6 +27,7 @@ $system$
 | 匹配分数阈值 | `matched_score >= 0.78` 为**完全推导成功**，`matched_score < 0.78` 为**部分推导成功**；`derived_success_count` 只统计完全推导成功的选题点 |
 | 多路径择优 | 同一选题点在同一轮中若被多条路径匹配到，取 `matched_score` 最高的路径作为该轮输出 |
 | 部分推导可继续 | 部分推导成功的选题点可在后续轮次继续推导，若出现更高分路径则替换；完全推导成功的选题点不再重复推导 |
+| 部分推导输入限制 | 部分推导成功的选题点（`partial_derived_set` 中的 `matched_post_point`）**不能**作为后续推导路径的 `input.derived_nodes`，因为其尚未完全推导成功，不能作为推导前提；但其对应的 `source_node`（人设节点）可作为后续推导路径的输入 |
 
 ---
 
@@ -45,7 +46,7 @@ $system$
 - 匹配分数阈值为 **0.78**。
 - `matched_score >= 0.78`：该选题点视为**完全推导成功**，加入 `derived_success_set`。
 - `matched_score < 0.78`（但匹配成功，即工具返回了匹配结果）：该选题点视为**部分推导成功**，加入 `partial_derived_set`，不计入 `derived_success_count`，不参与提前终止条件中 85% 的计算。
-- 部分推导成功的选题点仍需加入后续轮次工具调用的 `derived_items` 参数中（与完全推导成功的选题点一样）。
+- 部分推导成功的选题点仍需加入后续轮次工具调用的 `derived_items` 参数中（与完全推导成功的选题点一样），以参与条件概率计算。但部分推导成功的选题点（`matched_post_point`）**不能**作为推导路径的输入前提（`input.derived_nodes`），因为其尚未完全推导成功，不能作为推导的 reason；其对应的 `source_node`（人设节点）可以作为推导路径的输入。
 - 部分推导成功的选题点可在后续轮次中继续推导；若后续轮次出现匹配分数更高的推导路径，则更新为更高分路径；若后续轮次中匹配分数达到 0.78 以上，则升级为完全推导成功，从 `partial_derived_set` 移入 `derived_success_set`。
 - **完全推导成功的选题点不再重复推导**。
 
@@ -62,7 +63,7 @@ $system$
 
 ### 方法使用前提
 
-- **已推导成功的选题点集合**：由主 agent 根据每轮工具返回的匹配结果判断后更新，主 agent 自行维护。首轮该集合为空。
+- **已推导成功的选题点集合**：由主 agent 根据每轮工具返回的匹配结果判断后更新，主 agent 自行维护。首轮该集合为空。完全推导成功的选题点（`derived_success_set`）可作为推导路径的输入前提（`input.derived_nodes`）；部分推导成功的选题点（`partial_derived_set`）的 `matched_post_point` 不能作为推导前提，但其 `source_node` 可作为 `input.tree_nodes` 使用。
 - **人设常量**：不依赖已推导成功选题点，首轮即可调用 `find_tree_constant_nodes`，用于广召回。
 - **人设推导**、**账号 pattern 复用**：两工具的 `derived_items` **允许为空**。非空时按已推导帖子集合计算条件概率。**首轮即可使用**（传空数组或省略即可）。
 - **信息搜索**：任意轮次可调用（通过 `derivation_search` 子 agent）。
@@ -86,12 +87,13 @@ $system$
 - `derived_items` 非空时每项格式**严格**为两个字段：`topic`（帖子选题点名称）+ `source_node`（推导该点时对应的人设树节点名称）。
 - **禁止使用 `name`、`node`、`id` 或任何其他字段名**——工具不识别这些字段，传入会导致计算结果错误。
 - **`derived_items` 包含完全推导成功和部分推导成功的所有选题点**，不因匹配分数低于阈值而排除。两者都需要参与条件概率计算，以提高后续推导的准确性。
+- **⚠️ `derived_items`（工具参数）与 `input.derived_nodes`（推导路径输入）的区别**：`derived_items` 是传给工具的参数，包含完全推导和部分推导的并集，用于条件概率计算；而推导路径中的 `input.derived_nodes` 是推导的逻辑前提，**只能引用完全推导成功的选题点（`derived_success_set` 中的 `matched_post_point`）**，不能引用部分推导成功的选题点（`partial_derived_set` 中的 `matched_post_point`）。部分推导成功的选题点对应的 `source_node`（人设节点）可以作为 `input.tree_nodes` 使用。
 
 示例：
 - 首轮（无任何已推导点）：`[]`
 - 首轮后已有匹配结果时（含完全推导和部分推导的选题点）：`[{"topic": "分享", "source_node": "分享"}, {"topic": "叙事结构", "source_node": "叙事结构"}]`
 
-主 agent 在每轮完成匹配判断并更新集合后，后续轮次可从 `derived_success_set` 和 `partial_derived_set` 的并集整理出 `derived_items`，首轮固定传 `[]`。
+主 agent 在每轮完成匹配判断并更新集合后，后续轮次可从 `derived_success_set` 和 `partial_derived_set` 的并集整理出工具参数 `derived_items`（用于条件概率计算），首轮固定传 `[]`。但推导路径的 `input.derived_nodes` 只能引用 `derived_success_set` 中的选题点。
 
 主 agent 职责：选择推导方法 → 传参调用上述工具（或搜索子 agent）→ 根据工具返回结果整理本推导路径的 `input`/`output`/`reason`，并写入推导日志。
 
@@ -116,12 +118,14 @@ $system$
 每一轮推导按以下四个步骤顺序执行，**不可跳步、不可乱序**：
 
 **步骤一：策略决策**
-执行推导前，先明确本轮方向：当前处于广召回阶段还是收敛阶段？上一轮评估结果如何，哪些方向值得延伸或放弃？本轮应选用哪些方法与参数组合？同时检查 `failed_points` 列表，确保本轮不重复已失败的推导方向。此外，检查 `partial_derived_set` 中是否有部分推导成功的选题点尚未达到完全推导阈值，本轮可尝试为其寻找更高分的推导路径。
+执行推导前，先明确本轮方向：当前处于广召回阶段还是收敛阶段？上一轮评估结果如何，哪些方向值得延伸或放弃？本轮应选用哪些方法与参数组合？同时检查 `failed_points` 列表，确保本轮不重复已失败的推导方向。此外，检查 `partial_derived_set` 中是否有部分推导成功的选题点尚未达到完全推导阈值，本轮可尝试为其寻找更高分的推导路径（注意：部分推导成功的 `matched_post_point` 不能作为推导前提，但其 `source_node` 可作为人设节点输入）。
 
 **步骤二：执行推导**
-以**已推导成功的选题点集合**（`derived_success_set` 与 `partial_derived_set` 的并集）为基础（首轮为空），按步骤一确定的方法与参数，分条执行推导路径。调用 `find_tree_constant_nodes`、`find_tree_nodes_by_conditional_ratio`、`find_pattern` 时须传入 `post_id`。**总轮次上限为 15 轮**。
+以**已推导成功的选题点集合**为基础（首轮为空），按步骤一确定的方法与参数，分条执行推导路径。调用 `find_tree_constant_nodes`、`find_tree_nodes_by_conditional_ratio`、`find_pattern` 时须传入 `post_id`。工具的 `derived_items` 参数传入 `derived_success_set` 与 `partial_derived_set` 的并集（用于条件概率计算）。**总轮次上限为 15 轮**。
 
-**注意**：完全推导成功的选题点（`derived_success_set` 中的选题点）不需要再作为推导目标输出；部分推导成功的选题点（`partial_derived_set` 中的选题点）可以继续作为推导目标——如果本轮中出现了更高匹配分数的路径，则更新其记录。
+**注意**：
+- 完全推导成功的选题点（`derived_success_set` 中的选题点）不需要再作为推导目标输出；部分推导成功的选题点（`partial_derived_set` 中的选题点）可以继续作为推导目标——如果本轮中出现了更高匹配分数的路径，则更新其记录。
+- **推导路径的 `input.derived_nodes` 只能引用完全推导成功的选题点**（`derived_success_set` 中的 `matched_post_point`），不能引用部分推导成功的选题点（`partial_derived_set` 中的 `matched_post_point`），因为后者尚未完全推导成功，不能作为推导前提。部分推导成功选题点对应的 `source_node` 可以作为 `input.tree_nodes` 使用。
 
 **推导路径的粒度原则（强制拆分规则）**：一条推导路径表示"用最小输入信息推导出哪些选题点"。**必须严格执行以下拆分规则**： 
 1. **方法一（人设常量）**：工具返回的每一个常量节点必须**单独**成为一条推导路径。例如工具返回了节点 A 和节点 B，必须拆分为两条路径：路径1 input=[A] output=[A]，路径2 input=[B] output=[B]。**禁止**将多个独立常量节点合并到同一条路径中。
@@ -377,7 +381,7 @@ $system$
 - **操作方式**：**不直接调用 `search_posts`**。应调用内置 `agent` 工具，传入 `agent_type="derivation_search"`，在 `task` 中给出本次搜索的 **query**（及简短说明）。子 agent 会在内部调用 `search_posts` 执行搜索，并将结果摘要与原始数据返回；根据返回结果整理本推导路径的 `input`/`output`/`reason` 及 `tools` 字段。
 - **搜索流程**：
   1. **搜索需求构造**：明确本次搜索希望发现什么信息。
-  2. **搜索 query 构造（闭眼搜索）**：query 中使用的关键词**只能来自以下两类来源**：① 已推导成功选题点的 `matched_post_point` 名称；② 工具曾经返回过的人设树节点名称。**禁止**使用大模型自行推测或联想出的关键词，**禁止使用账号名称**。
+  2. **搜索 query 构造（闭眼搜索）**：query 中使用的关键词**只能来自以下两类来源**：① 完全推导成功选题点的 `matched_post_point` 名称（`derived_success_set` 中的选题点）；② 工具曾经返回过的人设树节点名称（包括 `partial_derived_set` 中选题点对应的 `source_node`）。**禁止**使用部分推导成功的 `matched_post_point` 作为搜索关键词，**禁止**使用大模型自行推测或联想出的关键词，**禁止使用账号名称**。
   3. **调用搜索子 agent**：`agent(task="执行搜索，query 为：<你的 query>", agent_type="derivation_search")`。
   4. **根据子 agent 返回**：逐条分析返回的搜索结果，判断是否包含可用于推导的新选题点，整理为推导路径输出。
 - **注意事项**：每次执行信息搜索方法必须重新调用 `derivation_search` 子 agent 执行一次搜索，即使 query 相同也不得复用历史搜索结果。
@@ -427,8 +431,8 @@ $system$
 **目标**：围绕已确认的选题点，向深度方向精准延伸，挖掘与之强关联的剩余选题点。
 
 **执行要点**：
-- **账号 pattern 复用（方法二）仍是每轮首选**：传入非空 `derived_items`（包含完全推导和部分推导成功的选题点），工具会自动优先返回包含已推导选题点的 pattern；重点关注这些 pattern 中尚未推导的元素，作为下一步候选；同时利用工具返回的「帖子选题点匹配」字段，优先选取匹配成功的 pattern 元素
-- 人设推导（方法三）传入非空 `derived_items`，利用条件概率补充 pattern 未覆盖的关联节点
+- **账号 pattern 复用（方法二）仍是每轮首选**：传入非空 `derived_items`（包含完全推导和部分推导成功的选题点，用于条件概率计算），工具会自动优先返回包含已推导选题点的 pattern；重点关注这些 pattern 中尚未推导的元素，作为下一步候选；同时利用工具返回的「帖子选题点匹配」字段，优先选取匹配成功的 pattern 元素。注意：推导路径的 `input.derived_nodes` 只能填写完全推导成功的选题点名称
+- 人设推导（方法三）传入非空 `derived_items`（用于条件概率计算），利用条件概率补充 pattern 未覆盖的关联节点。注意：推导路径的 `input.derived_nodes` 只能填写完全推导成功的选题点名称
 - 每轮推导聚焦于与已推导点关联性强的维度，避免回到无目标的散点式探索
 - 若某轮内部方法（方法二、三）在严格依据工具返回数据判定后仍无法推导出新点（即全部输出点均为 `is_matched=false`），方可触发信息搜索（方法四）——不得在触发信息搜索前，先用 `point_match` 对内部方法的输出进行额外探索
 - 搜索结束后，下一轮必须回归内部方法，优先用新发现的方向再次尝试 pattern 复用与人设推导
@@ -439,7 +443,7 @@ $system$
 
 - **优先内部，pattern 复用优先**：每轮推导以内部方法（方法一、二、三）为主，其中方法二（账号 pattern 复用）应在每轮都被使用，充分挖掘 pattern 数据中的共现信号；方法三（人设推导）作为补充，覆盖 pattern 之外的关联维度
 - **搜索触发时机**：内部方法连续 2 轮无法产出有效新候选点时，触发信息搜索（方法四）
-- **搜索关键词约束**：只能使用已推导成功选题点的 `matched_post_point` 名称，或工具曾返回过的人设树节点名称构造 query；**禁止**使用大模型自行推测或联想出的关键词；**禁止使用账号名称**
+- **搜索关键词约束**：只能使用完全推导成功选题点的 `matched_post_point` 名称（`derived_success_set` 中的选题点），或工具曾返回过的人设树节点名称（包括 `partial_derived_set` 中选题点对应的 `source_node`）构造 query；**禁止**使用部分推导成功的 `matched_post_point` 作为搜索关键词；**禁止**使用大模型自行推测或联想出的关键词；**禁止使用账号名称**
 - **搜索后的跟进**：每次搜索后至少安排 1~2 轮内部方法推导，将搜索发现的新方向优先在 pattern 库中验证，再结合人设树延伸
 
 #### 内部推导结果重合处理
@@ -465,7 +469,7 @@ $system$
 - **必须**切换推导策略，不得沿用上一轮失败的方法+输入组合
 - 具体调整方式（按优先级尝试）：
   1. **动态调整工具参数**：降低 `conditional_ratio_threshold`，增大 `top_n`，召回更多数据
-  2. **使用信息搜索**：构造基于已推导成功选题点的搜索 query，从搜索结果中发现新的推导线索
+  2. **使用信息搜索**：构造基于完全推导成功选题点和人设树节点名称的搜索 query，从搜索结果中发现新的推导线索
 
 #### 情况三：提前终止
 
@@ -484,7 +488,7 @@ $system$
 - **每轮多方法覆盖**：每轮推导应至少使用 2 种不同的推导方法，每种方法尝试多种输入组合，不局限于 1~2 种可能。已推导成功 ≥ 70%（此处的"已推导成功"仅统计 `derived_success_set` 即完全推导成功的选题点）后，可放宽为每轮至少使用 1 种方法，仅在未匹配时补充第 2 种，降低冗余工具调用。
 - **避免重复推导**：每轮推导前检查 `failed_points` 列表，列表中的选题点名称原则上不得再次输出；若确有必要重新推导，须换用完全不同的推导方法与输入组合。同时，**完全推导成功的选题点不得再次作为推导输出**；部分推导成功的选题点可以再次输出，以争取更高匹配分数。
 - **每一条推导路径必须包含**：输入节点、输出节点、推导方法、推导理由。
-  - **输入节点**：必须是已推导成功的选题点（帖子选题点名称），或人设树节点、pattern 节点。
+  - **输入节点**：必须是完全推导成功的选题点（`derived_success_set` 中的帖子选题点名称），或人设树节点、pattern 节点。**部分推导成功的选题点（`partial_derived_set` 中的 `matched_post_point`）不能作为输入节点**，因为其尚未完全推导成功，不能作为推导前提；但部分推导成功选题点对应的 `source_node`（人设节点）可以作为 `input.tree_nodes` 使用。
   - **输出节点**：本次推导产出的候选选题点。
   - **推导理由**：必须详细、可追溯，引用工具返回的具体数据（人设树节点的 `r`/`w` 值，或 pattern 的 `s`/`l` 值）；**禁止**牵强附会、连续多步联想或使用大模型自身世界知识推断；所有输出的选题点均须有对应推导理由。
 
@@ -492,7 +496,7 @@ $system$
 
 1. **闭眼推导（核心约束）**：
    - 工具返回的「帖子选题点匹配」字段只包含本轮匹配成功的帖子选题点，不包含匹配失败项，因此不存在"偷看未推导选题点"的风险。
-   - 只有「已推导成功的选题点」（使用帖子选题点名称）可以在推导时参考使用。
+   - 只有**完全推导成功的选题点**（`derived_success_set` 中的帖子选题点名称）可以在推导路径的 `input.derived_nodes` 中引用。部分推导成功的选题点（`partial_derived_set` 中的 `matched_post_point`）不能作为推导前提引用，因为其推导尚未完成；但其对应的 `source_node` 可以作为 `input.tree_nodes` 使用。
    - **禁止**在推导理由中引用匹配结果的反馈内容（如"匹配结果显示..."、"上一轮匹配到..."等）。
 
 2. **禁止自由联想**：
@@ -560,7 +564,7 @@ $system$
   - `method`: 推导方法名称，必须使用「推导方法的定义」中列出的四种方法名之一
   - `input.tree_nodes`: 本路径用到的人设树节点名称列表，只需节点名称，不需要完整路径，如 `创意展示` 而非 `形式.内容风格.氛围特征.创意性.创意展示`
   - `input.patterns`: 本路径用到的 pattern 选题点拼接列表（与 `processed_edge_data.json` 中 `i` 格式一致，如 `"名称1+名称2"`）
-  - `input.derived_nodes`: 本路径用到的已推导成功选题点名称列表
+  - `input.derived_nodes`: 本路径用到的已推导成功选题点名称列表（**只能引用 `derived_success_set` 中完全推导成功的选题点名称**，不能引用 `partial_derived_set` 中部分推导成功的选题点名称）
   - `output`: 本路径产出的待评估选题点名称列表（可多个）
   - `reason`: 必须详细、可追溯，引用工具返回的具体数据；禁止牵强或凭空联想
   - `tools`: 本路径使用的工具列表；若使用搜索工具，必须包含 `query`、`result`（数据摘要或关键内容）以及 `raw_result`（原始数据）；若未使用工具则为空数组 `[]`
@@ -623,7 +627,9 @@ $system$
      - 若该 `matched_post_point` 已在 `partial_derived_set` 中，且本次 `matched_score` 高于已记录的分数，则更新为本次更高分数。
      - 若该 `matched_post_point` 不在任何集合中，则加入 `partial_derived_set`。
 2. **核心区分**：加入集合的是**帖子选题点名称**（即 `matched_post_point`），而非推导输出的节点名称（`derivation_output_point`）。两者可能不同——例如推导输出节点 `趣味道具` 匹配到帖子选题点 `夸张道具`，则加入集合的是 `夸张道具`，而非 `趣味道具`。
-3. 后续轮次推导时，`derived_items` 中的 `topic` 字段和 `input.derived_nodes` 中引用的已推导成功选题点，均应使用帖子选题点名称（`matched_post_point`），`derived_items` 需要包含 `derived_success_set` 和 `partial_derived_set` 的并集。
+3. 后续轮次推导时：
+   - **工具参数 `derived_items`**：需要包含 `derived_success_set` 和 `partial_derived_set` 的并集，`topic` 字段使用帖子选题点名称（`matched_post_point`），用于条件概率计算。
+   - **推导路径 `input.derived_nodes`**：只能引用 `derived_success_set` 中的帖子选题点名称（`matched_post_point`），**不能引用 `partial_derived_set` 中的 `matched_post_point`**。部分推导成功选题点对应的 `source_node` 可以作为 `input.tree_nodes` 使用。
 
 ---
 

examples_how/overall_derivation/generate_visualize_data.py

@@ -369,7 +369,7 @@ def build_visualize_edges(
                 best_score_by_node[mp] = max(best_score_by_node.get(mp, -1.0), score)
 
             # 节点候选：同轮同节点保留匹配分更高的
-            for mp, _reason, score, is_fully, _out_item in output_names_this_edge:
+            for mp, _reason, score, is_fully, out_item in output_names_this_edge:
                 key = (round_num, mp)
                 if key not in node_candidates or node_candidates[key].get("matched_score", 0) < score:
                     node = dict(topic_by_name.get(mp, {"name": mp, "point": "", "dimension": "", "root_source": "", "root_sources_desc": ""}))
@@ -378,6 +378,8 @@ def build_visualize_edges(
                     node["derivation_type"] = dr.get("method", "")
                     node["matched_score"] = score
                     node["is_fully_derived"] = is_fully
+                    # 对应评估中的 derivation_output_point
+                    node["derivation_output_point"] = out_item
                     node_candidates[key] = node
 
             input_data = dr.get("input") or {}
@@ -493,5 +495,5 @@ def main(account_name, post_id, log_id):
 if __name__ == "__main__":
     account_name="家有大志"
     post_id = "68fb6a5c000000000302e5de"
-    log_id="20260310220945"
+    log_id="20260311154943"
     main(account_name, post_id, log_id)