Version: 0.9.51.dev.260428
后端： 1. schedule 读工具结果正式切到结构化 `schedule.read_result` 视图——`get_overview` / `query_range` / `query_available_slots` / `query_target_tasks` / `get_task_info` / `queue_status` 新增独立 handler，`ToolExecutionResult` 继续保留 `ObservationText` 给 LLM，但前端展示改走 `result_view` 的 collapsed / expanded 结构，统一输出 metrics / items / sections / machine_payload 2. `execution_result` 补齐第二批读工具参数本地化展示——扩展 `task_ids` / `task_item_ids` / `status` / `category` / `day_scope` / `week_filter` / `slot_types` / `include_pending` / `detail` / `dimensions` 等参数的排序权重、中文标签与展示格式，支持列表 / 布尔 / 周次 / 星期 / 节次等 `argument_view` 渲染 3. ToolRegistry 继续从内联注册收口到专属 handler——schedule 读工具从 `wrapLegacyToolHandler` 切到 `NewXxxToolHandler`，旧 `schedule` 子包里的 observation 生成逻辑暂时保留，当前切流点已落在 `newAgent/tools` 结构化适配层 4. 新增《工具结果结构化交接文档》，明确第二批 read 工具已迁移范围、`schedule.read_result` 协议、当前旧实现保留边界，以及下一轮建议迁移的 `schedule_analysis` 方向
This commit is contained in:
LoveLosita
258
backend/newAgent/tools/工具结果结构化交接文档.md
Normal file
258
backend/newAgent/tools/工具结果结构化交接文档.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# 工具结果结构化交接文档
|
||||
|
||||
## 当前状态
|
||||
|
||||
本轮已经完成第二批 read 事实域工具的后端结构化结果改造。外层协议仍然是 `ToolExecutionResult`，LLM 观察文本继续走 `ObservationText`，前端展示信息走 `ResultView` / `ArgumentView`。
|
||||
|
||||
已经直接切到 `result_view.view_type = "schedule.read_result"` 的工具：
|
||||
|
||||
1. `query_available_slots`
|
||||
2. `query_target_tasks`
|
||||
3. `query_range`
|
||||
4. `get_overview`
|
||||
5. `get_task_info`
|
||||
6. `queue_status`
|
||||
|
||||
尚未进入本轮的工具继续走 `LegacyResult`，不要为了“统一外观”在本轮顺手迁移其它工具。
|
||||
|
||||
当前新增/修改文件：
|
||||
|
||||
1. `backend/newAgent/tools/schedule_read_result_types.go`
|
||||
- read 结果常量、payload 结构、轻量内部结构。
|
||||
2. `backend/newAgent/tools/schedule_read_result_common.go`
|
||||
- 统一 `schedule.read_result` builder、失败卡片、中文格式化、跨工具统计 helper。
|
||||
- 当前文件偏重，约 600 行，是下一轮整理的重点。
|
||||
3. `backend/newAgent/tools/schedule_read_slots_handlers.go`
|
||||
- `query_available_slots`、`query_range`。
|
||||
4. `backend/newAgent/tools/schedule_read_tasks_handlers.go`
|
||||
- `query_target_tasks`、`get_task_info`。
|
||||
5. `backend/newAgent/tools/schedule_read_overview_queue_handlers.go`
|
||||
- `get_overview`、`queue_status`。
|
||||
6. `backend/newAgent/tools/execution_result.go`
|
||||
- 补齐 read/analyze 相关参数的中文 `argument_view` 标签和展示值。
|
||||
7. `backend/newAgent/tools/registry.go`
|
||||
- 只把 6 个 read 工具的注册入口替换成新的 `NewXxxToolHandler()`。
|
||||
|
||||
## 第二批协议
|
||||
|
||||
第二批新增的前端 view type 只有一个：
|
||||
|
||||
```json
|
||||
{
|
||||
"view_type": "schedule.read_result",
|
||||
"version": 1,
|
||||
"collapsed": {},
|
||||
"expanded": {}
|
||||
}
|
||||
```
|
||||
|
||||
`collapsed` 面向卡片折叠态：
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "找到 6 个目标任务",
|
||||
"subtitle": "建议安排任务，已入队 6 个",
|
||||
"status": "done",
|
||||
"status_label": "已完成",
|
||||
"metrics": [
|
||||
{ "label": "任务数", "value": "6 个" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`expanded` 面向卡片展开态：
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"title": "[12]英语作文",
|
||||
"subtitle": "待安排，2 节",
|
||||
"tags": ["待安排", "学习"],
|
||||
"detail_lines": ["位置：未安排"],
|
||||
"meta": {
|
||||
"task_id": 12
|
||||
}
|
||||
}
|
||||
],
|
||||
"sections": [
|
||||
{
|
||||
"type": "items",
|
||||
"title": "候选任务",
|
||||
"items": []
|
||||
}
|
||||
],
|
||||
"raw_text": "原始 observation 文本",
|
||||
"machine_payload": {}
|
||||
}
|
||||
```
|
||||
|
||||
C 端默认展示字段：
|
||||
|
||||
1. `collapsed.title`
|
||||
2. `collapsed.subtitle`
|
||||
3. `collapsed.status_label`
|
||||
4. `collapsed.metrics[].label/value`
|
||||
5. `expanded.items[].title/subtitle/tags/detail_lines`
|
||||
6. `expanded.sections[].title/summary/items`
|
||||
|
||||
默认不要展示的机器字段：
|
||||
|
||||
1. `expanded.machine_payload`
|
||||
2. `expanded.raw_text`
|
||||
3. `items[].meta`
|
||||
4. `task_id`、`day`、`slot_start`、`week_filter` 等机器参数名
|
||||
|
||||
这些字段只给调试、回传、后续交互使用。
|
||||
|
||||
## 整理任务
|
||||
|
||||
当前第二批代码虽然已经拆成多个文件，但仍然平铺在 `backend/newAgent/tools` 根包里。后续整理目标是把 read 结果构造逻辑收到子目录，避免根目录继续膨胀。
|
||||
|
||||
不要直接把现有 `.go` 文件机械移动到子目录。Go 里子目录就是新 package；当前文件依赖父包里的 `ToolHandler`、`ToolExecutionResult`、`ToolDisplayView`、`LegacyResultWithState` 等类型，直接移动会造成 import cycle。
|
||||
|
||||
推荐整理结构：
|
||||
|
||||
```text
|
||||
backend/newAgent/tools/
|
||||
registry.go
|
||||
schedule_read_handlers.go
|
||||
schedule_read/
|
||||
types.go
|
||||
common.go
|
||||
slots.go
|
||||
tasks.go
|
||||
overview_queue.go
|
||||
```
|
||||
|
||||
职责边界：
|
||||
|
||||
1. `backend/newAgent/tools/schedule_read/**`
|
||||
- 子包只做纯 read 展示数据构造。
|
||||
- 不 import 父包 `newagenttools`。
|
||||
- 不返回 `ToolExecutionResult`。
|
||||
- 返回类似 `ReadResultView` 的纯数据结构：`ViewType`、`Collapsed`、`Expanded`、`MachinePayload`。
|
||||
2. `backend/newAgent/tools/schedule_read_handlers.go`
|
||||
- 留在父包 `newagenttools`。
|
||||
- 只做薄 adapter：调用 `schedule_read` 子包构造展示数据，再包成 `ToolExecutionResult`。
|
||||
- 继续保证 `ObservationText` 原样给 LLM。
|
||||
3. `registry.go`
|
||||
- 只保留注册入口，不放业务逻辑。
|
||||
|
||||
如果整理时发现 `schedule_read_result_common.go` 里的 helper 同时被第三批 analysis 使用，再考虑抽更中性的公共包：
|
||||
|
||||
```text
|
||||
backend/newAgent/tools/toolview/
|
||||
```
|
||||
|
||||
但不要提前大抽象；只有 read 和 analysis 都真实复用同一批结构后再抽。
|
||||
|
||||
## 第三批计划
|
||||
|
||||
第三批建议处理 schedule 诊断分析域：
|
||||
|
||||
1. `analyze_health`
|
||||
2. `analyze_rhythm`
|
||||
|
||||
建议新增：
|
||||
|
||||
```text
|
||||
backend/newAgent/tools/schedule_analysis/
|
||||
```
|
||||
|
||||
建议新增 view type：
|
||||
|
||||
```text
|
||||
schedule.analysis_result
|
||||
```
|
||||
|
||||
外层协议继续不变：
|
||||
|
||||
```json
|
||||
{
|
||||
"result_view": {
|
||||
"view_type": "schedule.analysis_result",
|
||||
"version": 1,
|
||||
"collapsed": {},
|
||||
"expanded": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`schedule.analysis_result` 仍复用通用卡片结构，但语义上区别于 read：
|
||||
|
||||
1. `collapsed.title`
|
||||
- 例：`综合体检：建议继续微调`、`学习节律分析`
|
||||
2. `collapsed.subtitle`
|
||||
- 例：主问题、裁决摘要、风险摘要。
|
||||
3. `collapsed.metrics`
|
||||
- 例：高认知相邻天数、可局部移动任务数、推荐动作。
|
||||
4. `expanded.sections`
|
||||
- `裁决结论`
|
||||
- `关键指标`
|
||||
- `问题清单`
|
||||
- `候选操作`
|
||||
- `建议后续动作`
|
||||
5. `expanded.items`
|
||||
- 候选动作或风险日列表。
|
||||
6. `expanded.machine_payload`
|
||||
- 原始 JSON、候选动作参数、required_reads 等机器字段，只给调试/交互。
|
||||
|
||||
第三批不要和 read 整理同时改同一个公共 helper 文件。推荐顺序：
|
||||
|
||||
1. 先完成 read 整理，确定子包边界。
|
||||
2. 再做 `schedule_analysis` 子包。
|
||||
3. 最后只在父包 adapter 和 `registry.go` 接入 `analyze_health/analyze_rhythm`。
|
||||
|
||||
## 后续批次
|
||||
|
||||
第四批建议处理非 schedule read/analysis 主链：
|
||||
|
||||
1. `web_search`
|
||||
2. `web_fetch`
|
||||
3. `upsert_task_class`
|
||||
4. `context_tools_add`
|
||||
5. `context_tools_remove`
|
||||
|
||||
可考虑的 view type：
|
||||
|
||||
1. `web.search_result`
|
||||
2. `web.fetch_result`
|
||||
3. `taskclass.write_result`
|
||||
4. `tool.context_result`
|
||||
|
||||
这些工具不建议混入 `schedule.read_result` 或 `schedule.analysis_result`，否则前端语义会越来越模糊。
|
||||
|
||||
## 前端补丁提示
|
||||
|
||||
第二批后端已经新增 `schedule.read_result`。前端最低要求：
|
||||
|
||||
1. 头部继续优先读：
|
||||
- `result_view.collapsed.title`
|
||||
- `result_view.collapsed.subtitle`
|
||||
- `result_view.collapsed.status_label`
|
||||
- `result_view.collapsed.metrics`
|
||||
2. 展开态新增通用 sections/items renderer：
|
||||
- 支持 `expanded.items`
|
||||
- 支持 `expanded.sections`
|
||||
- section 类型至少兼容 `items`、`kv`、`callout`
|
||||
3. 默认不展示：
|
||||
- `expanded.machine_payload`
|
||||
- `items[].meta`
|
||||
- 原始英文 key/value
|
||||
4. `raw_text` 只放 debug 折叠区。
|
||||
|
||||
前端如果暂时不识别 `schedule.read_result`，至少能显示折叠态；但展开态会退回 raw text，不符合 C 端目标。
|
||||
|
||||
## 验收清单
|
||||
|
||||
后续代理继续处理前必须先确认：
|
||||
|
||||
1. 不回滚、覆盖、删除用户或其它代理的工作区改动。
|
||||
2. 不碰前端，除非用户明确要求。
|
||||
3. `ObservationText` 不能被展示层改写。
|
||||
4. 工具结果必须继续通过 `ToolExecutionResult -> SSE extra -> timeline payload` 传递。
|
||||
5. 每次跑 `go test` 后必须删除根目录 `.gocache`。
|
||||
6. 如果新增临时 `*_test.go`，跑完测试后必须删除。
|
||||
7. 结构迁移最终答复要说明：迁了什么、旧实现保留什么、切流点在哪里、下一轮建议迁什么。
|
||||
|
||||
Reference in New Issue
Block a user