82 lines
4.5 KiB
Markdown
82 lines
4.5 KiB
Markdown
|
# 工具回执系统 MVP
|
|||
|
|
|
|||
|
|
下一轮指引: 完成后→下发 PY-A04-002 记忆路由Agent后端
|
|||
|
|
仓库路径: /guanghu-self-hosted/tool-receipt/
|
|||
|
|
优先级: P0
|
|||
|
|
分支名: feat/py-tool-receipt
|
|||
|
|
创建时间: 2026年4月25日 12:36
|
|||
|
|
审核结果: ✅ 审核通过 — 霜砚·Web握手体 AG-SY-WEB-001
|
|||
|
|
审核时间: 2026-04-25T12:46 CST
|
|||
|
|
|
|||
|
|
📂 文件完整性 (8/8)
|
|||
|
|
1. http://config.py (2600B) — Pydantic配置·环境变量·PG/SQLite双模·retention_days
|
|||
|
|
2. receipt_http://manager.py (10804B) — 双后端(PgReceiptManager异步+SqliteReceiptManager同步)·CRUD四方法·Pydantic Receipt模型·ReceiptStatus枚举
|
|||
|
|
3. receipt_schema.sql (1726B) — PostgreSQL 15+ CREATE TABLE·UUID主键·JSONB字段·5索引·updated_at自动触发器
|
|||
|
|
4. receipt_http://api.py (6524B) — FastAPI四端点(POST/PATCH/GET/GET-session)·lifespan管理·自动格式化响应
|
|||
|
|
5. receipt_http://formatter.py (6501B) — 三格式输出(JSON+Text+HLDP树)·会话批量摘要·状态图标映射
|
|||
|
|
6. test_http://receipt.py (9802B) — 15条pytest测试·SQLite fallback·完整生命周期·session批量·formatter三格式
|
|||
|
|
7. requirements.txt (65B) — fastapi>=0.110+asyncpg>=0.29+pydantic>=2.5+uvicorn>=0.27
|
|||
|
|
8. http://README.md (2678B) — 项目文档(额外加分)
|
|||
|
|
|
|||
|
|
🔍 约束合规
|
|||
|
|
✅ Python 3.10+ (dict[str,Any]联合类型语法)
|
|||
|
|
✅ FastAPI + asyncpg + pydantic
|
|||
|
|
✅ PostgreSQL 15+ schema含索引+自动更新trigger
|
|||
|
|
✅ SQLite fallback本地测试
|
|||
|
|
✅ test_http://receipt.py含15条测试
|
|||
|
|
✅ receipt_http://formatter.py输出JSON(系统)+Text(前端)+HLDP(母语)
|
|||
|
|
✅ status枚举: pending/success/error/timeout
|
|||
|
|
✅ 目录隔离: 仅/guanghu-self-hosted/tool-receipt/
|
|||
|
|
✅ 参考HLDP-ARCH-001 L2设计
|
|||
|
|
|
|||
|
|
🏗️ 代码质量
|
|||
|
|
· 关注点分离清晰(config/manager/api/formatter/test)
|
|||
|
|
· 完整docstring和类型注解
|
|||
|
|
· 异步生命周期管理(lifespan)
|
|||
|
|
· Pydantic v2 请求/响应模型验证
|
|||
|
|
· ensure_ascii=False 支持中文
|
|||
|
|
· 环境变量配置覆盖
|
|||
|
|
|
|||
|
|
结论: PASS ✅
|
|||
|
|
开发内容: 开发工具回执系统（Tool Receipt System）的后端核心。
|
|||
|
|
1. 参考 HLDP-ARCH-001 中 L2 工具回执系统的设计
|
|||
|
|
2. 在 /guanghu-self-hosted/tool-receipt/ 下创建：
|
|||
|
|
- receipt_http://manager.py: 回执管理器核心类
|
|||
|
|
· record_call(tool_name, input_params) → 创建回执记录，返回receipt_id
|
|||
|
|
· update_result(receipt_id, output, status, duration) → 更新回执结果
|
|||
|
|
· get_receipt(receipt_id) → 查询单条回执
|
|||
|
|
· get_session_receipts(session_id) → 查询某次对话的所有回执
|
|||
|
|
- receipt_schema.sql: 回执表建表SQL（receipt_id, session_id, persona_id, tool_name, input_params, output, status, timestamp, duration_ms）
|
|||
|
|
- receipt_http://api.py: FastAPI路由，提供REST接口
|
|||
|
|
· POST /receipts → 创建回执
|
|||
|
|
· PATCH /receipts/{id} → 更新结果
|
|||
|
|
· GET /receipts/{id} → 查询回执
|
|||
|
|
· GET /sessions/{session_id}/receipts → 查询会话所有回执
|
|||
|
|
- receipt_http://formatter.py: 回执格式化器，将回执转为人类可读格式和HLDP母语格式
|
|||
|
|
- http://config.py: 配置（数据库连接占位、回执保留时长等）
|
|||
|
|
- test_http://receipt.py: 测试用例（创建→更新→查询完整流程）
|
|||
|
|
3. status枚举: pending/success/error/timeout
|
|||
|
|
4. 回执必须同时支持JSON输出和人类可读文本输出
|
|||
|
|
状态: 已完成
|
|||
|
|
约束: 编码: Python 3.10+ · FastAPI · UTF-8
|
|||
|
|
依赖: fastapi+asyncpg+pydantic（数据库用asyncpg异步连接）
|
|||
|
|
SQL: PostgreSQL 15+ · 与PersonaDB同一数据库实例
|
|||
|
|
测试: 必须包含test_http://receipt.py · 可用SQLite做本地测试fallback
|
|||
|
|
禁触: 不要修改仓库其他目录的任何文件
|
|||
|
|
注意: receipt_http://formatter.py输出两种格式——JSON(给系统)和可读文本(给前端)
|
|||
|
|
编号: PY-A04-20260425-002
|
|||
|
|
自检结果: ✅ 8文件齐全(config/receipt_schema.sql/receipt_manager/receipt_api/receipt_formatter/test_receipt/requirements/README)
|
|||
|
|
✅ 目录隔离: 仅/guanghu-self-hosted/tool-receipt/
|
|||
|
|
✅ 未修改仓库其他目录文件
|
|||
|
|
✅ PY-A04-前缀commit (8 commits)
|
|||
|
|
✅ Python3.10+ · FastAPI · UTF-8
|
|||
|
|
✅ 依赖: fastapi+asyncpg+pydantic+uvicorn
|
|||
|
|
✅ PostgreSQL 15+ schema含索引+自动更新trigger
|
|||
|
|
✅ SQLite fallback本地测试
|
|||
|
|
✅ test_http://receipt.py含15条测试(CRUD+完整流程+中文UTF-8+formatter)
|
|||
|
|
✅ receipt_http://formatter.py输出三格式: JSON+人类可读文本+HLDP母语
|
|||
|
|
✅ status枚举: pending/success/error/timeout
|
|||
|
|
✅ 参考HLDP-ARCH-001 L2设计
|
|||
|
|
✅ 分支: feat/py-tool-receipt (8 commits)
|
|||
|
|
负责Agent: 培园A04
|
|||
|
|
阶段编号: Phase-0-005
|