72 lines
3.6 KiB
Markdown
72 lines
3.6 KiB
Markdown
|
# 工具回执系统 Tool Receipt System
|
|||
|
|
|
|||
|
|
下一轮指引: 暂缓 · 等光湖网站上线后统一重构
|
|||
|
|
仓库路径: /guanghu-self-hosted/tool-receipt/
|
|||
|
|
优先级: P0
|
|||
|
|
分支名: feat/yd-tool-receipt
|
|||
|
|
创建时间: 2026年4月25日 14:04
|
|||
|
|
审核结果: ⏸️ 暂缓 · 2026-04-25T15:27+08:00
|
|||
|
|
━━━━━━━━━━
|
|||
|
|
原因：与PY-A04-002工具回执系统重复 · 架构重排后统一到光湖网站平台重构
|
|||
|
|
处理人：霜砚AG-SY-01
|
|||
|
|
后续：Phase 2在光湖自有平台上统一重构工具回执层
|
|||
|
|
开发内容: 实现工具回执系统(Tool Receipt System)的运行时逻辑。
|
|||
|
|
参考 HLDP-ARCH-001 [L-2] 工具回执系统架构设计。
|
|||
|
|
|
|||
|
|
核心目标: 每次工具调用的全过程可见 · AI能看见 · 人类也能看见 · 编了会被自己的回执打脸。
|
|||
|
|
|
|||
|
|
1. 在 /guanghu-self-hosted/tool-receipt/ 下创建：
|
|||
|
|
- receipt_http://recorder.py: 回执记录器
|
|||
|
|
· 记录每次工具调用: tool_name / input / output / status(✅/❌/⏳) / timestamp / duration
|
|||
|
|
· 异步写入PostgreSQL · 不阻塞主流程
|
|||
|
|
· 支持批量记录 + 单条记录
|
|||
|
|
· record_receipt()公开接口
|
|||
|
|
- receipt_http://store.py: 回执存储层
|
|||
|
|
· PostgreSQL表结构定义(tool_receipts表)
|
|||
|
|
· 字段: id / session_id / persona_id / tool_name / input_params / output_result / status / error_message / timestamp / duration_ms
|
|||
|
|
· CRUD操作 · 按session查询 · 按persona查询 · 按时间范围查询
|
|||
|
|
· 连接池管理(asyncpg)
|
|||
|
|
- receipt_http://validator.py: 回执校验器
|
|||
|
|
· 对比AI声称的操作结果与实际回执记录
|
|||
|
|
· 检测矛盾: AI说做了X但回执显示没做/失败
|
|||
|
|
· 生成校验报告(通过/矛盾/缺失)
|
|||
|
|
- receipt_http://formatter.py: 回执格式化器
|
|||
|
|
· 将回执记录格式化为人类可读格式
|
|||
|
|
· 将回执记录格式化为AI上下文注入格式
|
|||
|
|
· 支持HLDP母语格式输出
|
|||
|
|
- init.py: 模块入口 + record_receipt()公开接口
|
|||
|
|
- requirements.txt: 依赖清单(asyncpg/pydantic)
|
|||
|
|
|
|||
|
|
2. 三层防线对齐:
|
|||
|
|
· 第一层(微调·改大脑): 不在本模块范围
|
|||
|
|
· 第二层(Boot Protocol·改规则): 灯塔公理已在Phase-0-006实现
|
|||
|
|
· 第三层(回执系统·改环境): 本模块 → 每步操作有回执 → 编了会被证据链打脸
|
|||
|
|
|
|||
|
|
3. 必须与Phase-0-006 Boot Protocol的BootResult/StepResult结构兼容
|
|||
|
|
4. 回执存储必须用PostgreSQL(与PersonaDB同一实例)
|
|||
|
|
5. 代码风格: Python 3.11+ · type hints · docstrings · snake_case
|
|||
|
|
状态: 暂缓
|
|||
|
|
约束: 编码: UTF-8
|
|||
|
|
语言: Python 3.11+
|
|||
|
|
风格: PEP 8 · type hints · docstrings
|
|||
|
|
依赖: 仅开源库 · 零商业许可
|
|||
|
|
对齐: 必须与Phase-0-006 Boot Protocol兼容 · 回执存PostgreSQL
|
|||
|
|
命名: snake_case · 文件名小写
|
|||
|
|
禁触: 不要修改boot-protocol/下的任何文件(只读引用)
|
|||
|
|
测试: 模块可独立import · 无硬编码连接串 · record_receipt()接口可被外部调用
|
|||
|
|
编号: YD-A05-20260425-005
|
|||
|
|
自检结果: ✅ 自检通过 · 2026-04-25T14:14+08:00
|
|||
|
|
文件完整性: 6/6 ✅ (init.py / receipt_http://store.py / receipt_http://recorder.py / receipt_http://validator.py / receipt_http://formatter.py / requirements.txt)
|
|||
|
|
路径: /guanghu-self-hosted/tool-receipt/ ✅
|
|||
|
|
分支: feat/yd-tool-receipt ✅
|
|||
|
|
commit: 3dec4b3
|
|||
|
|
禁触检查: boot-protocol/ 无任何修改 ✅
|
|||
|
|
编码: UTF-8 ✅
|
|||
|
|
Python 3.11+ / type hints / docstrings / snake_case / PEP 8 ✅
|
|||
|
|
依赖: 仅开源(asyncpg+pydantic) ✅
|
|||
|
|
Boot Protocol兼容: validate_step_results()接受StepResult格式 ✅
|
|||
|
|
PostgreSQL存储: tool_receipts表 + asyncpg连接池 + 环境变量配置(无硬编码) ✅
|
|||
|
|
模块可独立import ✅
|
|||
|
|
record_receipt()公开接口可外部调用 ✅
|
|||
|
|
负责Agent: 译典A05
|
|||
|
|
阶段编号: Phase-0-007
|