kg-agent/docs/api-reference.md

内部接口参考

供前后端开发与排错使用；日常使用和部署见 README。

网页与 API

网页默认关闭自动确认，可在页面手动开启。API 的 auto_confirm 默认值则为 true。

接口	用途
POST /ask	收集执行结果后返回 JSON；需确认时返回 need_confirm
POST /ask/stream	SSE 流式进度、回答和确认事件
POST /threads/{thread_id}/resume	以 {"reply":"确认"} 或修改意见继续会话
GET /threads/{thread_id}/history	查看 rounds 和 messages
GET /api/runtime	查看当前 data_version、schema_version

请求示例（PowerShell）：

$body = @{
    thread_id = "user-001"
    query = "目前有多少个项目？"
    auto_confirm = $true
    reuse_check = $true
} | ConvertTo-Json
Invoke-RestMethod -Uri "http://127.0.0.1:8000/ask" -Method Post `
    -ContentType "application/json; charset=utf-8" `
    -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

同一 thread_id 共享上下文，调用方应为不同会话分配独立标识。reuse_check 默认 true，控制旧问答分支的历史答案复用；当前生产分支每次重新规划和查询，历史对话仅辅助理解。

SSE 使用 POST，可参考 html/index.html 中的 askStream 实现，通过 fetch 读取响应流：

事件	处理
progress	用 node 和中文 label 展示处理阶段
answer_chunk	将 text 增量追加到回答区
confirm	展示确认内容，再调用 resume 接口
done	使用完整结果中的 answer 更新最终回答
error	展示失败信息

数据质量

接口 GET /api/data-quality 返回总数及各文件计数；?details=true&data_version=<版本> 返回完整问题记录，版本变化返回409。明细沿用现有服务访问边界，能访问此接口的用户可看到问题记录的全部字段。

人工确认答案缓存

POST /threads/{thread_id}/answer-cache：确认该答案正确并保存缓存。 DELETE /threads/{thread_id}/answer-cache：撤销对应缓存（需entry_id）。

请求仅允许： {"answer_id":"答案ID","checkpoint_id":"该答案的checkpoint ID","entry_id":null}。 POST成功返回status、entry_id、approved_at；DELETE用该entry_id撤销。 接口从服务端checkpoint读取原答案，不接收答案、问题或查询条件正文。 记录失效、未完成、不符合缓存规则或版本变化返回409；缓存不可用返回503。 额外字段或缺失标识返回422。

/ask、/ask/stream的done和resume完整响应新增cache_review： eligible、reason、answer_id、checkpoint_id、cached、hit、entry_id、approved_at。 eligible=true时前端展示“答案正确，加入缓存”，成功后可撤销。 cached/hit=true显示历史答案来源。人工计划确认和auto_confirm不等于缓存确认。

索引仅限同一thread_id、精确问题和上下文，包含数据/Schema/模型/策略版本，永久保存，数据版本发布成功后物理删除全部旧数据版本缓存。 关闭reuse_check绕过缓存读取。缓存命中直接返回已确认答案及来源，不调用模型/Neo4j。 目前无真实鉴权，不能据此宣称具有用户身份认证或允许跨用户共享缓存。