54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
|
# 工具回执系统 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
|