# 工具回执系统 Tool Receipt System

下一轮指引: 暂缓 · 等光湖网站上线后统一重构
仓库路径: /guanghu-self-hosted/tool-receipt/
优先级: P0
分支名: feat/yd-tool-receipt
创建时间: 2026年4月25日 14:05
审核结果: ⏸️ 暂缓 · 2026-04-25T15:27+08:00
━━━━━━━━━━
原因：重复工单 · 架构重排 · 光湖网站优先
处理人：霜砚AG-SY-01
开发内容: 实现工具回执系统（L2层）运行时逻辑。
参考 HLDP-ARCH-001 [L2] 工具回执系统架构设计。

核心目标：每次工具调用的全过程可见 · AI能看见 · 人类也能看见。
三层防幻觉防线的第三层：回执=证据链=编了自己打脸。

1. 在 /guanghu-self-hosted/tool-receipt/ 下创建：
   - receipt_http://logger.py: 回执记录器
     · 装饰器/上下文管理器模式，包裹任意工具调用
     · 记录完整回执：tool_name / input / output / status(✅/❌/⏳) / timestamp / duration
     · 异常捕获：工具失败时记录错误信息+堆栈摘要
     · 支持同步和异步工具调用
   - receipt_http://store.py: 回执存储层
     · PostgreSQL持久化（receipts表：id/persona_code/session_id/tool_name/input_json/output_json/status/error_msg/timestamp/duration_ms）
     · 查询接口：按persona_code/session_id/tool_name/时间范围检索
     · 回执统计：成功率/平均耗时/高频工具排行
   - receipt_http://checker.py: 回执校验器
     · 对比工具声明的输出与实际输出
     · 检测矛盾：AI声称做了X但回执显示未做或失败
     · 幻觉检测信号输出（供上层消费）
   - receipt_http://display.py: 回执展示格式化
     · 人类可读格式（类Notion处理步骤展示）
     · AI可读格式（结构化JSON供模型消费）
     · 实时流式输出支持（WebSocket事件格式）
   - init.py: 模块入口 + 公开接口
   - requirements.txt: 依赖清单(asyncpg/fastapi/pydantic)

2. 必须与Phase-0-004 PersonaDB表结构兼容（receipts为新表，需提供建表SQL）
3. 必须与Phase-0-005 记忆路由Agent兼容（回执可作为记忆写回的数据源）
4. 代码风格: Python 3.11+ · type hints · docstrings · snake_case
状态: 暂缓
约束: 编码: UTF-8
语言: Python 3.11+
风格: PEP 8 · type hints · docstrings
依赖: 仅开源库 · 零商业许可
对齐: 必须提供receipts表建表SQL(在receipt_http://store.py或单独schema文件中)
命名: snake_case · 文件名小写
禁触: 不要修改其他Phase已有文件(boot-protocol/persona-db/memory-router目录只读)
测试: 模块可独立import · 无硬编码连接串 · receipt_logger装饰器可被外部调用
回执格式: 必须包含tool_name/input/output/status/timestamp/duration六字段
编号: YD-A05-20260425-005
负责Agent: 译典A05
阶段编号: Phase-0-007