Files
Agent-Workbench/docs/MODEL-REQUEST-LEDGER.md
T

46 lines
4.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 完整请求账本
模型中心的请求账本保存全部现有请求,支持前后页、历史连接/结果/原文筛选、刷新、完整范围导出以及原请求/响应下载。每页默认 50 条是展示分页,不是模型输出额度或保存上限。旧版本已经删去且没有原件的记录不能由迁移补造。
## 保存与原始来源
`model_attempts` 位于原 `workbench.sqlite`,用递增 `seq` 区分每一条记录。旧 `metadata.modelAttempts` 在一次事务中完整迁入;原 metadata 的文字和 SHA256 保持不变。重复的旧尝试 ID 分别保存,不因 ID 相同合并或删除。详情按序号读取;只按歧义 ID 读取时要求核对原序号。
每条保存当前 `payload`、最初 `initial_payload`、双方 SHA256 和旧数组位置。正常进度只更新所属当前尝试,未变化的记录不产生提交。连接、模型、协议、pool、项目、会话、Task、Run、request 身份不能被移到另一份记录;已有另一份保存进展时不覆盖。用量 `raw`、未报告/unknown、上游原错及原请求/响应工件引用保持原值。
重启后仅把仍为 running 的尝试记为 unknown,并保存核对原因;不重发请求、不重复工具,也不补造真实计费。初始记录继续保留重启前的状态。
账本协议版本是 1;采用它的 SQLite 数据库版本是 2。数据库版本只在账本迁移事务成功时提升,公开诊断返回实际版本。以前只支持 schema 1 的程序不能重新打开 schema 2 并把旧 metadata 误当全部历史。失败的同步处理器接续只可撤销经过核对、尚无新结果的初始化迁移;已有新增/变化记录、SHA 或归属变化时不删除账本。
旧 `ModelHub.attempts` 及 `storage.meta('modelAttempts')` 在新程序里仍可取得完整兼容视图,但普通请求不全量加载或回写数组。直接 SQL 读取原 metadata 的旧实验驱动只看到其冻结历史;不改写、重跑旧实验,新驱动应使用以下接口。正式安装的数据迁移和跨版本回退仍按 M3 单独验收。
## 查询接口
接口沿用当前工作台的连接凭据和本机来源核对,不发出模型请求。
| 路径 | 返回 |
| --- | --- |
| `GET /api/model-center/attempts` | 当前页、每条序号/当前与初始 SHA、完整保存数、范围数和下一页游标 |
| `GET /api/model-center/attempts/<sequence>` | 本条当前记录与初始记录、来源和双方 SHA |
| `GET /api/model-center/attempts/export` | 当前筛选范围的全部 NDJSON 记录 |
筛选参数为 `connectionId`、`sessionId`、`taskId`、`runId`、`status`、`model`、`protocol`、`query`。`query` 查原记录文字,百分号与下划线按文字处理。重复/无效参数会指出本机查询错误。已删除或关闭的历史连接仍可在现有账本中选择;读取失败保留所选连接、结果和搜索文字。
分页另接受正整数 `limit` 与 `cursor`,没有固定最大页额度。游标绑定本次账本身份、全部筛选和序号上界,后续新请求不会挤进原页。页上的运行中字段仍可能更新,尤其状态筛选的结果可能变化;这是序号范围分页,不是不可变字段快照。游标范围或来源变化时刷新即可取得新范围,不能跨连接/筛选混用。
`/api/model-center` 继续提供最近 100 条兼容预览,同时返回真实 `attemptCount`、是否还有历史及增量保存方式。完整账本不依赖这个预览范围。运行巡检也使用真实保存数。
## 完整导出
导出使用独立只读 SQLite 连接和读事务固定记录/字段快照,期间新请求与进度更新不影响已开始的导出。服务端逐条等待实际写入回调,不因缓冲区已清空而继续等待不存在的 `drain`。接收端关闭或写入失败时释放快照,不发送伪完成结尾;没有完整 footer 的片段不能当作完整导出。
NDJSON 每行末尾是 LF:
1. `header`:格式 `orven-model-attempts-ndjson`、协议版本、筛选、序号上界、预期条数、来源和 `includesInitialReceipts: true`。
2. 每条 `attempt`:序号/来源/SHA 引用、完整当前 `item` 和完整 `initial.item`/`initial.sha256`。
3. `footer`:`complete: true`、实际条数、所有 attempt 行**含 LF**拼接的 `recordLinesSha256`。
核对 header/实际/footer 数量、每条当前与初始 JSON 的 SHA,以及所有记录行的 SHA。原始工件正文不嵌入这个导出,继续按所保存的 session/工件 ID/SHA 从原入口下载。浏览器客户端取得完整文件后下载 Blob;Electron 使用真实 DownloadItem,验收选择自有路径,Windows 保存对话框另未验证。未以这项功能宣称大规模客户端流式落盘、总体性能或真实供应商缓存收益。
实现和验收见 [切片计划](M2-REQUEST-LEDGER-PLAN.md) 与 [阶段验收](QA-M2-REQUEST-LEDGER.md)。历史真实模型失败、网络异常、unknown 用量、重复读取和 Purge 收益 unknown 均不改变。