picoclaw/tasks/prd-tool-result-refactor.md

PRD: Tool 返回值结构化重构

Introduction

当前 picoclaw 的 Tool 接口返回 (string, error)，存在以下问题：

1. 语义不明确：返回的字符串是给 LLM 看还是给用户看，无法区分
2. 字符串匹配黑魔法：isToolConfirmationMessage 靠字符串包含判断是否发送给用户，容易误判
3. 无法支持异步任务：心跳触发长任务时会一直阻塞，影响定时器
4. 状态保存不原子：SetLastChannel 和 Save 分离，崩溃时状态不一致

本重构将 Tool 返回值改为结构化的 ToolResult，明确区分 ForLLM（给 AI 看）和 ForUser（给用户看），支持异步任务和回调通知，删除字符串匹配逻辑。

Goals

• Tool 返回结构化的 ToolResult，明确区分 LLM 内容和用户内容
• 支持异步任务执行，心跳触发后不等待完成
• 异步任务完成时通过回调通知系统
• 删除 isToolConfirmationMessage 字符串匹配黑魔法
• 状态保存原子化，防止数据不一致
• 为所有改造添加完整测试覆盖

User Stories

US-001: 新增 ToolResult 结构体和辅助函数

Description: 作为开发者，我需要定义新的 ToolResult 结构体和辅助构造函数，以便工具可以明确表达返回结果的语义。

Acceptance Criteria:

• ToolResult 包含字段：ForLLM, ForUser, Silent, IsError, Async, Err
• 提供辅助函数：NewToolResult(), SilentResult(), AsyncResult(), ErrorResult(), UserResult()
• ToolResult 支持 JSON 序列化（除 Err 字段）
• 添加完整 godoc 注释
• go test ./pkg/tools -run TestToolResult 通过

US-002: 修改 Tool 接口返回值

Description: 作为开发者，我需要将 Tool 接口的 Execute 方法返回值从 (string, error) 改为 *ToolResult，以便使用新的结构化返回值。

Acceptance Criteria:

• pkg/tools/base.go 中 Tool.Execute() 签名改为返回 *ToolResult
• 所有实现了 Tool 接口的类型更新方法签名
• go build ./... 无编译错误
• go vet ./... 通过

US-003: 修改 ToolRegistry 处理 ToolResult

Description: 作为中间层，ToolRegistry 需要处理新的 ToolResult 返回值，并调整日志逻辑以反映异步任务状态。

Acceptance Criteria:

• ExecuteWithContext() 返回值改为 *ToolResult
• 日志区分：completed / async / failed 三种状态
• 异步任务记录启动日志而非完成日志
• 错误日志包含 ToolResult.Err 内容
• go test ./pkg/tools -run TestRegistry 通过

US-004: 删除 isToolConfirmationMessage 字符串匹配

Description: 作为代码维护者，我需要删除 isToolConfirmationMessage 函数及相关调用，因为 ToolResult.Silent 字段已经解决了这个问题。

Acceptance Criteria:

• 删除 pkg/agent/loop.go 中的 isToolConfirmationMessage 函数
• runAgentLoop 中移除对该函数的调用
• 工具结果是否发送由 ToolResult.Silent 决定
• go build ./... 无编译错误

US-005: 修改 AgentLoop 工具结果处理逻辑

Description: 作为 agent 主循环，我需要根据 ToolResult 的字段决定如何处理工具执行结果。

Acceptance Criteria:

• LLM 收到的消息内容来自 ToolResult.ForLLM
• 用户收到的消息优先使用 ToolResult.ForUser，其次使用 LLM 最终回复
• ToolResult.Silent 为 true 时不发送用户消息
• 记录最后执行的工具结果以便后续判断
• go test ./pkg/agent -run TestLoop 通过

US-006: 心跳支持异步任务执行

Description: 作为心跳服务，我需要触发异步任务后立即返回，不等待任务完成，避免阻塞定时器。

Acceptance Criteria:

• ExecuteHeartbeatWithTools 检测 ToolResult.Async 标记
• 异步任务返回 "Task started in background" 给 LLM
• 异步任务不阻塞心跳流程
• 删除重复的 ProcessHeartbeat 函数
• go test ./pkg/heartbeat -run TestAsync 通过

US-007: 异步任务完成回调机制

Description: 作为系统，我需要支持异步任务完成后的回调通知，以便任务结果能正确发送给用户。

Acceptance Criteria:

• 定义 AsyncCallback 函数类型：func(ctx context.Context, result *ToolResult)
• Tool 添加可选接口 AsyncTool，包含 SetCallback(cb AsyncCallback)
• 执行异步工具时注入回调函数
• 工具内部 goroutine 完成后调用回调
• 回调通过 SendToChannel 发送结果给用户
• go test ./pkg/tools -run TestAsyncCallback 通过

US-008: 状态保存原子化

Description: 作为状态管理，我需要确保状态更新和保存是原子操作，防止程序崩溃时数据不一致。

Acceptance Criteria:

• SetLastChannel 合并保存逻辑，接受 workspace 参数
• 使用临时文件 + rename 实现原子写入
• rename 失败时清理临时文件
• 更新时间戳在锁内完成
• go test ./pkg/state -run TestAtomicSave 通过

US-009: 改造 MessageTool

Description: 作为消息发送工具，我需要使用新的 ToolResult 返回值，发送成功后静默不通知用户。

Acceptance Criteria:

• 发送成功返回 SilentResult("Message sent to ...")
• 发送失败返回 ErrorResult(...)
• ForLLM 包含发送状态描述
• ForUser 为空（用户已直接收到消息）
• go test ./pkg/tools -run TestMessageTool 通过

US-010: 改造 ShellTool

Description: 作为 shell 命令工具，我需要将命令结果发送给用户，失败时显示错误信息。

Acceptance Criteria:

• 成功返回包含 ForUser = 命令输出的 ToolResult
• 失败返回 IsError = true 的 ToolResult
• ForLLM 包含完整输出和退出码
• go test ./pkg/tools -run TestShellTool 通过

US-011: 改造 FilesystemTool

Description: 作为文件操作工具，我需要静默完成文件读写，不向用户发送确认消息。

Acceptance Criteria:

• 所有文件操作返回 SilentResult(...)
• 错误时返回 ErrorResult(...)
• ForLLM 包含操作摘要（如 "File updated: /path/to/file"）
• go test ./pkg/tools -run TestFilesystemTool 通过

US-012: 改造 WebTool

Description: 作为网络请求工具，我需要将抓取的内容发送给用户查看。

Acceptance Criteria:

• 成功时 ForUser 包含抓取的内容
• ForLLM 包含内容摘要和字节数
• 失败时返回 ErrorResult
• go test ./pkg/tools -run TestWebTool 通过

US-013: 改造 EditTool

Description: 作为文件编辑工具，我需要静默完成编辑，避免重复内容发送给用户。

Acceptance Criteria:

• 编辑成功返回 SilentResult("File edited: ...")
• ForLLM 包含编辑摘要
• go test ./pkg/tools -run TestEditTool 通过

US-014: 改造 CronTool

Description: 作为定时任务工具，我需要静默完成 cron 操作，不发送确认消息。

Acceptance Criteria:

• 所有 cron 操作返回 SilentResult(...)
• ForLLM 包含操作摘要（如 "Cron job added: daily-backup"）
• go test ./pkg/tools -run TestCronTool 通过

US-015: 改造 SpawnTool

Description: 作为子代理生成工具，我需要标记为异步任务，并通过回调通知完成。

Acceptance Criteria:

• 实现 AsyncTool 接口
• 返回 AsyncResult("Subagent spawned, will report back")
• 子代理完成时调用回调发送结果
• go test ./pkg/tools -run TestSpawnTool 通过

US-016: 改造 SubagentTool

Description: 作为子代理工具，我需要将子代理的执行摘要发送给用户。

Acceptance Criteria:

• ForUser 包含子代理的输出摘要
• ForLLM 包含完整执行详情
• go test ./pkg/tools -run TestSubagentTool 通过

US-017: 心跳配置默认启用

Description: 作为系统配置，心跳功能应该默认启用，因为这是核心功能。

Acceptance Criteria:

• DefaultConfig() 中 Heartbeat.Enabled 改为 true
• 可通过环境变量 PICOCLAW_HEARTBEAT_ENABLED=false 覆盖
• 配置文档更新说明默认启用
• go test ./pkg/config -run TestDefaultConfig 通过

US-018: 心跳日志写入 memory 目录

Description: 作为心跳服务，日志应该写入 memory 目录以便被 LLM 访问和纳入知识系统。

Acceptance Criteria:

• 日志路径从 workspace/heartbeat.log 改为 workspace/memory/heartbeat.log
• 目录不存在时自动创建
• 日志格式保持不变
• go test ./pkg/heartbeat -run TestLogPath 通过

US-019: 心跳调用 ExecuteHeartbeatWithTools

Description: 作为心跳服务，我需要调用支持异步的工具执行方法。

Acceptance Criteria:

• executeHeartbeat 调用 handler.ExecuteHeartbeatWithTools(...)
• 删除废弃的 ProcessHeartbeat 函数
• go build ./... 无编译错误

US-020: RecordLastChannel 调用原子化方法

Description: 作为 AgentLoop，我需要调用新的原子化状态保存方法。

Acceptance Criteria:

• RecordLastChannel 调用 st.SetLastChannel(al.workspace, lastChannel)
• 传参包含 workspace 路径
• go test ./pkg/agent -run TestRecordLastChannel 通过

Functional Requirements

• FR-1: ToolResult 结构体包含 ForLLM, ForUser, Silent, IsError, Async, Err 字段
• FR-2: 提供 5 个辅助构造函数：NewToolResult, SilentResult, AsyncResult, ErrorResult, UserResult
• FR-3: Tool 接口 Execute 方法返回 *ToolResult
• FR-4: ToolRegistry 处理 ToolResult 并记录日志（区分 async/completed/failed）
• FR-5: AgentLoop 根据 ToolResult.Silent 决定是否发送用户消息
• FR-6: 异步任务不阻塞心跳流程，返回 "Task started in background"
• FR-7: 工具可实现 AsyncTool 接口接收完成回调
• FR-8: 状态保存使用临时文件 + rename 实现原子操作
• FR-9: 心跳默认启用（Enabled: true）
• FR-10: 心跳日志写入 workspace/memory/heartbeat.log

Non-Goals (Out of Scope)

• 不支持工具返回复杂对象（仅结构化文本）
• 不实现任务队列系统（异步任务由工具自己管理）
• 不支持异步任务超时取消
• 不实现异步任务状态查询 API
• 不修改 LLMProvider 接口
• 不支持嵌套异步任务

Design Considerations

ToolResult 设计原则

• ForLLM: 给 AI 看的内容，用于推理和决策
• ForUser: 给用户看的内容，会通过 channel 发送
• Silent: 为 true 时完全不发送用户消息
• Async: 为 true 时任务在后台执行，立即返回

异步任务流程

心跳触发 → LLM 调用工具 → 工具返回 AsyncResult
                              ↓
                         工具启动 goroutine
                              ↓
                    任务完成 → 回调通知 → SendToChannel

原子写入实现

// 写入临时文件
os.WriteFile(path + ".tmp", data, 0644)
// 原子重命名
os.Rename(path + ".tmp", path)

Technical Considerations

• 破坏性变更：所有工具实现需要同步修改，不支持向后兼容
• Go 版本：需要 Go 1.21+（确保 atomic 操作支持）
• 测试覆盖：每个改造的工具需要添加测试用例
• 并发安全：State 的原子操作需要正确使用锁
• 回调设计：AsyncTool 接口可选，不强制所有工具实现

回调函数签名

type AsyncCallback func(ctx context.Context, result *ToolResult)

type AsyncTool interface {
    Tool
    SetCallback(cb AsyncCallback)
}

Success Metrics

• 删除 isToolConfirmationMessage 后无功能回归
• 心跳可以触发长任务（如邮件检查）而不阻塞
• 所有工具改造后测试覆盖率 > 80%
• 状态保存异常情况下无数据丢失

Open Questions

• 异步任务失败时如何通知用户？（通过回调发送错误消息）
• 异步任务是否需要超时机制？（暂不实现，由工具自己处理）
• 心跳日志是否需要 rotation？（暂不实现，使用外部 logrotate）

Implementation Order

1. 基础设施：ToolResult + Tool 接口 + Registry (US-001, US-002, US-003)
2. 消费者改造：AgentLoop 工具结果处理 + 删除字符串匹配 (US-004, US-005)
3. 简单工具验证：MessageTool 改造验证设计 (US-009)
4. 批量工具改造：剩余所有工具 (US-010 ~ US-016)
5. 心跳和配置：心跳异步支持 + 配置修改 (US-006, US-017, US-018, US-019)
6. 状态保存：原子化保存 (US-008, US-020)