# Step3 知识图谱问答 Agent

`src/step3_qa_agent/agent/` 负责问题理解、复用、接地、规划、执行审查和回答；
`retrieval/` 负责受控 Neo4j 查询。答案必须来自实际检索结果，评估报告不能充当业务事实。

## 每次提问的上下文流程

1. `understand` 每次执行时读取 `output/meta_graph_schema.json`，建立本轮快照。
   问题理解提示词包含节点、属性、主键、合并/多值规则、关系方向/连接字段/判断方法和统计，
   同时提供可用数据评估的目录；此时不放入评估正文。
2. 问题理解在原有 category/slots 之外返回：
   `data_needs: {datasets: [节点id], relations: [关系id]}`。
   LLM 结合当前问题与历史对话选择所需数据；跨节点关系自动纳入两端数据集。
   未知节点、未知或歧义关系会被排除并记录，不能扩大到全部评估。
3. 从 `data/production/analysis/qa_data_context.json` 中选取对应评估，
   核对 source_sha256 与当前生产工作簿，以及字段集合与本轮元图谱是否一致。
   只使用 Step1 精简评估；不会读取完整分析报告的原始数据，也不会临时重跑评估。
4. 将选中的字段含义、缺失率、数据粒度、候选键、查询用途及风险说明保存到
   `AgentState.qa_context`。规划、能力拓展、复用判断、审查、反思和回答均读取同一快照。
   提问间重新加载；同一轮重试或中断恢复期间不静默换版。
5. 回答历史记录 schema_build_id；当前图谱版本与历史回答不同或历史版本未知时，
   不直接复用该历史答案，进入重新查询。

问题理解未返回有效 data_needs 时，仅以本轮问题和槽位做关键词兜底并记录该状态，
不继承上次选择。有效的空选择保持为空。闲聊也带本轮元图谱，但不注入业务评估正文。

## 可用性与边界

- 元图谱缺失或无效：在调用 LLM 前明确报错，不能假装使用旧测试结构。
- 评估缺失、重复、字段不符、源文件过期或暂不可读：省略该评估，保留元图谱，
  并在上下文中明确“缺少质量参考”，不解释为业务数据不存在。
- 提示词和日志使用评估摘要；不会把 source_sha256、原始工作簿内容或完整画像直接放入提示词。
- trace 中记录 schema_build_id、selected_datasets、loaded_datasets、
  selection_source 和 assessment_issues，便于核对每轮实际使用的上下文。
- 数据评估只辅助解释和规划，不得覆盖图谱事实、编造工具、用源行数替代合并后的节点数。
- **本轮改动范围为上下文加载与路由**。旧固定查询工具仍需适配“人员信息/项目信息”
  标签和多值属性；本轮没有重构检索工具、修改数据库、重生成评估或运行真实 LLM 问答。
- 本轮更新前已中断的旧任务没有 qa_context，应重新提问以建立新快照。

## 主要文件

- `agent/question_context.py`：本轮快照、语义选择、关系端点补全和评估有效性校验。
- `agent/data_context.py`：评估摘要格式化，保留原有关键词调用兼容。
- `agent/schema_context.py`：优先从本轮状态组装提示词，保留旧独立调用入口。
- `agent/nodes.py` / `agent/state.py`：问题理解输出、状态传递及历史版本标记。

## 验证

```powershell
uv run python scripts/test_qa_question_context.py
uv run python scripts/test_data_analysis.py
uv run python scripts/test_step2_production.py
```

本轮10+3+13项本地测试通过；新测试使用模拟 LLM，并实际运行 LangGraph
“问题理解→规划”的状态传递路径。覆盖多轮隔离、同轮快照、跨图谱版本复用、
选中数据集与关系端点、缺失/过期评估、闲聊及元图谱加载失败。

真实本地文件核验：人员选择仅加载人员评估；服务于关系加载人员与项目评估，
hash和字段校验均通过。没有发送真实业务问题或评估内容到外部模型，尚不能据此
宣称真实问答准确率提高；需在查询工具适配后执行业务问题集验收。


## 简单问题快速规划与中间输出（2026-09-07）

生产 Schema v2 在一次问题理解中同时提取可选的 `simple_query`。仅支持单数据集的
节点去重计数、属性查询和明细列表，最多6个明确文本等于/包含的 AND 条件。
候选必须声明完整、与原始 data_needs 单数据集/无关系选择一致，筛选值必须来自本轮问题，
已抽取的实体及筛选槽位不能遗漏，字段和结构必须通过现有只读编译器校验。
计数、关系或字段口径不明确时应返回 null。模型对完整性的判断仍需真实问题验收。

命中时程序构造计划，省去单独规划模型调用；仍经过中文计划确认、版本检查、
实际 Neo4j 查询、空结果候选及溯源回答。跨关系、时间/数值条件、分组排序、复杂表达、
历史指代、未知字段、缺失候选、修改反馈都回退完整规划。每次理解重置候选，旧会话不继承。

理解与完整规划均要求紧凑 JSON，不输出额外分析文字；省略空数组/空槽位、默认 limit=50、
重复 fields/depends。所有实际筛选、关联、分组、排序、返回字段和统计口径必须保留。
简单计数候选最小结构为：
`{"kind":"count","dataset":"人员信息","complete":true}`。
最终答案仍按原有规则生成，不对 JSON 使用可能导致截断的硬性 token 上限。

可选环境变量（未设置时默认 true，支持 true/false/1/0）：

| 变量 | 作用 |
|---|---|
| `QA_FAST_PLAN_ENABLED` | 单数据集快速规划 |
| `QA_COMPACT_INTERMEDIATE_ENABLED` | 理解与完整规划的紧凑输出 |

两个都设为 false 可恢复原理解/规划提示词及两次调用路径。修改配置或代码后重启服务，
无需重新取数或构图。

`api_log` 中 state.trace 的 understand/production_plan 新增 duration_ms；
production_plan.mode 为 simple 或 llm，reason 说明命中或回退原因，validation_attempts
记录完整计划结构校验次数。llm_calls 每项记录一个 SDK 流的耗时、首次 chunk/文本等待、
输入/输出字符数及可用的 usage。JSON 解析重试计为不同流；SDK 内部网络重试只能计入耗时，
不能据此声称记录了精确网络请求次数。usage 缺失为 null，不把字符数当 token 数。
耗时不包含人工等待；节点耗时减去流耗时包含上下文、SDK创建等本地处理。

离线回归：
`uv run --frozen python -X utf8 -m unittest scripts.test_simple_plan scripts.test_qa_question_context scripts.test_value_clarification scripts.test_plan_presentation scripts.test_runtime_workflow -q`。

真实测试脚本 `scripts/benchmark_qa_planning.py` 交替关闭/开启两个优化，记录理解和规划耗时；
它会调用真实配置的外部模型，须取得授权后运行。加 `--execute` 执行受控只读图谱查询，
仅保存结果行数、截断标记及按字段/操作归一的结果哈希，不保存原始查询行。
输出默认在 `.runtime/qa/planning-benchmark.json`。哈希比较需确认同一 build_id、
同一口径且结果未截断；随机模型输出和无排序明细可能不同。单次样本不能代表 P95。

## 用户确认的独立问答缓存（2026-09-07）

网页版完成生产图谱回答后，在答案下显示“答案正确，加入缓存”。只有点击此按钮，
服务端才把该答案加入独立 Redis 索引；查询计划的“确认”或自动确认不会写入缓存。
保存成功后可“撤销缓存”，缓存命中显示“已复用你确认的历史答案”。

索引使用 `ka:qa:approved:v1:` 前缀的 Redis String，与上下文 checkpoint 分离。
键包含问题文本哈希、thread_id 隔离范围、最近对话摘要哈希、数据版本、Schema版本、
模型名及缓存策略版本。只去除问题两端空白，不去除否定、数字、标点或实体内部空格；
不做相似度直接复用。新提问先作一次有超时限制的 GET；未命中继续原问答流程。
同一问题连续重复时沿用原问题的上下文签名；中途问过其他问题会重新计算签名，
因此可能不命中。带明确历史指代或相对时间的问题保守地不缓存。

命中后直接复用用户确认的答案、查询计划和来源，跳过模型及图谱查询，
但仍追加本轮历史并保存新的 checkpoint；关闭页面“历史复用”可强制正常问答。
目前API没有真实鉴权，缓存仅按会话隔离，清空/新建会话不会共享已有缓存。
未来接入鉴权后须把实际用户/租户/权限版本纳入键，不能使用当前固定 user_id=api 共享。

仅接收答案ID及checkpoint ID，不接收浏览器提交的答案正文。服务端读取该会话不可变
checkpoint并校验完成状态，所以旧答案按钮也不会误确认后来的另一条回答。
过期checkpoint无法确认。错误、闲聊、不支持、截断/缺失结果、待澄清、
修改过计划/替换过候选、依赖上下文/相对时间及超过256KB的记录不入缓存。
保存查询结果与来源仅用于复用已确认内容，不把评估报告当作事实。

缓存永久保存（不设置TTL），数据版本发布成功后删除全部旧数据版本缓存。写入通过Redis原子脚本核对当前数据版本，不设置过期时间。数据或Schema更新、模型名、
策略版本变化均不再命中旧键。数据版本发布成功后，仅扫描独立问答索引并删除全部非当前数据版本记录，不影响会话上下文及其他Redis数据。清理失败记录警告，服务启动及运行期间每60秒重试；启动时将尚存的当前版本旧TTL记录转为永久。
撤销使用比较后删除，避免并发时删除另一条新确认记录。
缓存读超时/损坏时回退正常问答；写入/撤销失败会明确提示，不显示成功。
底层Redis整体不可用仍会影响原有checkpoint持久化，不承诺整个服务脱离Redis运行。

| 配置 | 默认 | 用途 |
|---|---|---|
| `QA_ANSWER_CACHE_ENABLED` | true | 独立答案缓存及确认入口开关 |
| `QA_ANSWER_CACHE_TTL_SECONDS` | 已停用 | 旧配置被忽略；问答缓存永久保存 |
| `QA_ANSWER_CACHE_POLICY_VERSION` | 1 | 提示词/权限/回答策略变化时主动递增以失效旧缓存 |

修改代码或配置后重启服务，无需取数或构图。现有缓存不会自动认定旧上下文中的答案正确，
历史答案必须由用户通过对应按钮确认。

主要实现：`src/step4_web/answer_cache.py`、`api.py`、
`html/answer_cache.js`、`html/answer_cache.css`；根页iframe版本同步更新。
离线验证：
`uv run --frozen python -X utf8 -m unittest scripts.test_answer_cache -q`；
页面：`node scripts/test_answer_cache_ui.cjs`（需Playwright和Edge）。