Version: 0.9.52.dev.260428

后端： 1. 工具结果结构化切流继续推进：schedule 读工具改为“父包 adapter + 子包 view builder”，`queue_pop_head` / `queue_skip_head` 脱离 legacy wrapper，`analyze_health` / `analyze_rhythm` 补齐 `schedule.analysis_result` 诊断卡片。 2. 非 schedule 工具补齐专属结果协议：`web_search` / `web_fetch`、`upsert_task_class`、`context_tools_add` / `context_tools_remove` 全部接入结构化 `ResultView`，注册表继续去 legacy wrapper，同时保持原始 `ObservationText` 供模型链路复用。 3. 工具展示细节继续收口：参数本地化补齐 `domain` / `packs` / `mode` / `all`，deliver 阶段补发段落分隔，避免 execute 与总结正文黏连。前端： 4. `ToolCardRenderer` 升级为多协议通用渲染器，补齐 read / analysis / web / taskclass / context 卡片渲染、参数折叠区、未知协议兜底与操作明细展示。 5. `AssistantPanel` 修正 `tool_result` 结果回填与卡片布局宽度问题，并新增结构化卡片 fixture / mock 调试入口，便于整体验收。仓库： 6. 更新工具结果结构化交接文档，补记第四批切流范围、当前切流点与后续收尾建议。
2026-04-28 20:22:22 +08:00
parent 1a5b2ecd73
commit d89e2830a9
38 changed files with 9180 additions and 1577 deletions
--- a/backend/newAgent/tools/工具结果结构化交接文档.md
+++ b/backend/newAgent/tools/工具结果结构化交接文档.md
@@ -1,5 +1,100 @@
 # 工具结果结构化交接文档

+## 最新负责人验收结论
+
+本轮已经按“直接切流”完成 read 结果构造迁移：6 个 `schedule.read_result` 工具仍由父包注册入口暴露，但父包只保留薄 adapter，真实展示数据构造已经切到 `backend/newAgent/tools/schedule_read/` 子包。
+
+第三批 `schedule.analysis_result` 也已经完成直接切流：`analyze_health` / `analyze_rhythm` 仍然保留原始 JSON `ObservationText`，前端展示新增走 `ResultView`。
+
+第四批非 schedule read/analysis 主链也已经完成直接切流：`web_search`、`web_fetch`、`upsert_task_class`、`context_tools_add`、`context_tools_remove` 已经分别切到专属结构化卡片；队列尾巴 `queue_pop_head` / `queue_skip_head` 也已经脱离 `legacy_text`。
+
+第四批当前切流点：
+
+1. `registry.go`
+   - `web_search` 已切到 `NewWebSearchToolHandler()`。
+   - `web_fetch` 已切到 `NewWebFetchToolHandler()`。
+   - `upsert_task_class` 继续注册 `NewTaskClassUpsertToolHandler()`，但该入口已由 `taskclass_result_handlers.go` 承接结构化包装。
+   - `context_tools_add` / `context_tools_remove` 已在原 handler 内直接返回 `tool.context_result`。
+   - `queue_pop_head` 已切到 `NewQueuePopHeadToolHandler()`。
+   - `queue_skip_head` 已切到 `NewQueueSkipHeadToolHandler()`。
+   - `wrapLegacyToolHandler` 已删除，当前默认注册表不再依赖该 legacy wrapper。
+2. `backend/newAgent/tools/web_result/**` + `web_result_handlers.go`
+   - `web_search` 输出 `result_view.view_type = "web.search_result"`。
+   - `web_fetch` 输出 `result_view.view_type = "web.fetch_result"`。
+   - 原始 observation 继续写入 `ObservationText` / `expanded.raw_text`。
+3. `backend/newAgent/tools/taskclass_result/**` + `taskclass_result_handlers.go`
+   - `upsert_task_class` 输出 `result_view.view_type = "taskclass.write_result"`。
+   - 写库、confirm、校验、错误处理语义不变，只替换展示层。
+4. `backend/newAgent/tools/tool_context_result/**` + `context_tools.go`
+   - `context_tools_add` / `context_tools_remove` 输出 `result_view.view_type = "tool.context_result"`。
+   - 卡片展示 domain、packs、mode、all 和失败原因。
+5. `backend/newAgent/tools/schedule_queue_handlers.go`
+   - `queue_pop_head` 复用 `schedule.read_result`。
+   - `queue_skip_head` 复用 `schedule.operation_result`。
+
+第四批验收结果：
+
+1. `go test ./newAgent/tools/...` 通过。
+2. `go test ./...` 通过。
+3. 根目录 `.gocache` 已清理。
+4. 没有遗留临时 `*_test.go`。
+5. `ObservationText` 均保持原始工具 observation，不被展示层改写。
+
+analysis 当前切流点：
+
+1. `registry.go`
+   - `analyze_health` 已切到 `NewAnalyzeHealthToolHandler()`。
+   - `analyze_rhythm` 已切到 `NewAnalyzeRhythmToolHandler()`。
+2. `backend/newAgent/tools/schedule_analysis_handlers.go`
+   - 父包唯一 analysis adapter 文件。
+   - 负责执行 `schedule.AnalyzeHealth` / `schedule.AnalyzeRhythm`，保留原始 `ObservationText`，生成中文 `ArgumentView`，再调用 `schedule_analysis.BuildAnalyzeHealthView()` / `BuildAnalyzeRhythmView()`。
+3. `backend/newAgent/tools/schedule_analysis/**`
+   - 子包负责纯 analysis 展示数据构造。
+   - 不 import 父包 `newagenttools`，不返回 `ToolExecutionResult`。
+
+analysis 验收结果：
+
+1. `result_view.view_type = "schedule.analysis_result"`，`version = 1`。
+2. `expanded.raw_text` 保留原始 observation JSON。
+3. `expanded.machine_payload` 保留解析后的完整机器字段，供调试和后续交互使用。
+4. `analyze_health` 的 observation JSON 契约未改动，仍可被 `state_snapshot` / prompt 摘要消费。
+5. `go test ./newAgent/tools/...` 通过。
+6. `go test ./...` 通过。
+7. 根目录 `.gocache` 已清理。
+8. 没有遗留临时 `*_test.go`。
+
+当前切流点：
+
+1. `registry.go`
+   - 继续注册 `NewQueryAvailableSlotsToolHandler()`、`NewQueryRangeToolHandler()`、`NewQueryTargetTasksToolHandler()`、`NewGetTaskInfoToolHandler()`、`NewGetOverviewToolHandler()`、`NewQueueStatusToolHandler()`。
+2. `backend/newAgent/tools/schedule_read_handlers.go`
+   - 父包唯一 read adapter 文件。
+   - 负责执行底层 `schedule.*` 工具，保留原始 `ObservationText`，生成中文 `ArgumentView`，再调用 `schedule_read.BuildXxxView()`。
+3. `backend/newAgent/tools/schedule_read/**`
+   - 子包负责纯 read 展示数据构造。
+   - 不 import 父包 `newagenttools`，不返回 `ToolExecutionResult`。
+
+已删除旧实现：
+
+1. `schedule_read_result_types.go`
+2. `schedule_read_result_common.go`
+3. `schedule_read_slots_handlers.go`
+4. `schedule_read_tasks_handlers.go`
+5. `schedule_read_overview_queue_handlers.go`
+
+仍保留的父包能力：
+
+1. `schedule_argument_format_helpers.go`
+   - 只服务 `execution_result.go` 的参数中文展示。
+   - 不再参与 `schedule.read_result` 卡片构造。
+
+验收结果：
+
+1. `go test ./newAgent/tools/...` 通过。
+2. `go test ./...` 通过。
+3. 根目录 `.gocache` 已清理。
+4. 没有遗留临时 `*_test.go`。
+
 ## 当前状态

 本轮已经完成第二批 read 事实域工具的后端结构化结果改造。外层协议仍然是 `ToolExecutionResult`，LLM 观察文本继续走 `ObservationText`，前端展示信息走 `ResultView` / `ArgumentView`。
@@ -206,26 +301,29 @@ schedule.analysis_result

 ## 后续批次

-第四批建议处理非 schedule read/analysis 主链：
+当前文档计划内的四批结构化结果已经完成。默认注册表里主链工具已经不再通过 `wrapLegacyToolHandler` 接入。

-1. `web_search`
-2. `web_fetch`
-3. `upsert_task_class`
-4. `context_tools_add`
-5. `context_tools_remove`
+当前稳定 view type：

-可考虑的 view type：
+1. `schedule.operation_result`
+2. `schedule.read_result`
+3. `schedule.analysis_result`
+4. `web.search_result`
+5. `web.fetch_result`
+6. `taskclass.write_result`
+7. `tool.context_result`
+8. `legacy_text`

-1. `web.search_result`
-2. `web.fetch_result`
-3. `taskclass.write_result`
-4. `tool.context_result`
+`legacy_text` 仍作为未知工具、兜底结果或未来新增工具的保底协议保留，不建议删除。

-这些工具不建议混入 `schedule.read_result` 或 `schedule.analysis_result`，否则前端语义会越来越模糊。
+若后续继续整理，建议只做两类小收尾：
+
+1. 前端补齐 `web.search_result`、`web.fetch_result`、`taskclass.write_result`、`tool.context_result` 的专项 mock 与视觉验收。
+2. 评估是否把各子包重复的 `kv/items/callout` helper 下沉到中性公共包，例如 `backend/newAgent/tools/toolview/`；只有在确认 read、analysis、web、taskclass、context 都稳定后再抽，避免提前扩大回归面。

 ## 前端补丁提示

-第二批后端已经新增 `schedule.read_result`。前端最低要求：
+后端当前已经输出多种结构化 `result_view`。前端最低要求：

 1. 头部继续优先读：
   - `result_view.collapsed.title`
@@ -236,13 +334,23 @@ schedule.analysis_result
   - 支持 `expanded.items`
   - 支持 `expanded.sections`
   - section 类型至少兼容 `items`、`kv`、`callout`
+   - `callout` 需要兼容 `subtitle` 和 `summary`
 3. 默认不展示：
   - `expanded.machine_payload`
   - `items[].meta`
   - 原始英文 key/value
 4. `raw_text` 只放 debug 折叠区。

-前端如果暂时不识别 `schedule.read_result`，至少能显示折叠态；但展开态会退回 raw text，不符合 C 端目标。
+前端需要至少识别以下新协议：
+
+1. `schedule.read_result`
+2. `schedule.analysis_result`
+3. `web.search_result`
+4. `web.fetch_result`
+5. `taskclass.write_result`
+6. `tool.context_result`
+
+前端如果暂时不识别某个专属 view type，至少要显示折叠态；但展开态退回 raw text 不符合 C 端目标。

 ## 验收清单