From f3086c3c67a978208ac9971f60c4e65defaeb948 Mon Sep 17 00:00:00 2001
From: zichun <26684461+reporkey@users.noreply.github.com>
Date: Tue, 28 Jul 2026 00:44:42 +0800
Subject: [PATCH] docs: §19 current state (agent-dev rework, acceptance results)

---
 docs/agent-architecture.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 52 insertions(+), 2 deletions(-)

diff --git a/docs/agent-architecture.md b/docs/agent-architecture.md
index 36d0735..4a5f1f5 100644
--- a/docs/agent-architecture.md
+++ b/docs/agent-architecture.md
@@ -253,7 +253,7 @@ ai_op_queue(
 - 现网安全发现（后端逐用户表单权限被注释关 / 读 API 可被 `bUpdate` 触发写 / 旧 NL2SQL 越权）——`docs/security-findings.md` 已成文，**是否整改由业务定**。授权层真正“收紧到非管理员”只有在**生产以真实用户 token 运行**时才能观测（本地 dev-login=admin 全通）。
 - 报价改双确认、首个灰度只读场景选型 —— 业务确认项。
 
-## 17. 当前实现状态（2026-07-23，分支 `kg-edge-flow`，HEAD `8b927e3`）
+## 17. 实现状态（2026-07-23，分支 `kg-edge-flow`，HEAD `8b927e3`）—— 历史快照，勿当现状读
 
 > 这是**唯一的现状节**。改代码后请更新这一节，不要再往 §15/§16 里加。
 
@@ -308,7 +308,7 @@ ai_op_queue(
 | §10 manual 预填深链 `/form/{formId}?staging={sId}` | ERP 侧端点已写，xlyAi 侧**不产生这类链接** | manual 流程未打通 |
 | §3 agent 完全自路由 | 前置确定性意图门 | 见 §17.2（有意为之） |
 
-## 18. 未完成清单（2026-07-23）
+## 18. 未完成清单（2026-07-23）—— 历史快照，勿当现状读
 
 **阻塞上线**
 1. **`kg-edge-flow` 未合并 `master`** —— §14 已定"写入 master"，但全部 6200 行新代码只在该分支；`master` 仍是改造前状态。
@@ -334,3 +334,53 @@ ai_op_queue(
 
 **业务决策项**
 17. 首个灰度只读场景选型；报价是否改双确认；多语言（当前仅中文）。
+
+## 19. 当前实现状态（2026-07-28，分支 `agent-dev` → `agent-main`）
+
+2026-07-27/28 全量重构（22 项待办，5 批），全部完成并验收。
+
+### 19.1 工具与编排（§3/§5 的最终形态）
+
+- **固定 6 工具**，不再按意图分范围（`ToolScope` 已删）：`findForms` / `readFormData(formId, moduleId, keyword?, page?)` /
+  `lookupRecord` / `collectForm` / `proposeWrite(action=…)` / `askUser`。n=50 基准显示按意图收窄无准确率收益（严格 76% vs 76%），
+  反而破坏 KV-cache 前缀稳定性。已删除：`queryData`（NL2SQL 栈 + jsqlparser 依赖）、`kgSearch`、`loadSkill`（SkillTool/SkillService；`ai_skill` 表保留）。
+- **单一 system prompt**（`SystemPromptService.prompt()`）：域地图 + 业务常识（问价=新建报价核价、删除=作废）+ 6 工具清单 + 4 条准则。
+- **意图门 4 类**（查询/新增/操作已有单据/其他）：提示只写**类定义**（含有界行业常识），零逐案纠错规则；
+  具体写动作（update/invalid/examine/cancelInvalid/cancelExamine/delete）由路由层从原话推出（`deriveWriteAction`）。
+- 记录定位：`FormResolverService.searchField` 按关键词形态选检索字段（形如单号→`sBillNo`，否则名称列）；
+  `locateRecord()` 为 update/invalid/examine/delete 四路共用。
+
+### 19.2 上下文（§8 的实现）
+
+- **会话账本** `chat:ledger:{conv}`（Redis LIST，30 天）：user/assistant/clarify/form/question/tool/proposal/confirm/cancel
+  全类型事件按序落账——确定性路径也入账；前端历史从账本重放（`ConversationService.history`）。
+- **状态槽** `chat:state:{conv}`（代码写入，非模型总结）：上轮意图/最近实体/在办单据(阶段)。摘要前缀喂意图门与写槽位抽取
+  （跨轮指代「它/那张单」可解），尾注入 agent 用户消息。
+- **投影记忆** `ProjectedChatMemory`（替代 MessageWindowChatMemory）：存储保完整（硬上限整轮裁剪），
+  读取按字符预算（≈token）从新到旧整轮取，旧工具结果压一行；当前轮原样保留。
+- 确定性路径通过 `RedisChatMemoryStore.appendTurn` 补记忆（表单弹出/澄清/提议/确认结果），修补记忆空洞。
+
+### 19.3 可靠性护栏
+
+- Ollama（0.32.3，已升级重测）对 `tool_choice=required` **不硬执行**（4/5）→ 代码护栏：
+  查询轮零工具调用且答案含数字 → 强制重试一次，仍复发则标注「未经核实」；非查询轮声称已生成/已完成但未真正
+  proposeWrite → 附纠正提示。
+- `erp.exec-staging.enabled=true` 生产路径已本地端到端验证（改字段/新增报价/作废均真实落库、以用户 token 身份执行、
+  ai_op_queue 状态由 ERP 侧回写）。修复两个真实缺陷：xlyAi 侧未解 ERP 统一响应包装（status 在 `dataset.rows[0]`）；
+  ERP 侧执行器缺 `invalid` 分支（已补，走 `updatebInvalid`/Sp_Invalidation）。
+
+### 19.4 交互协议与前端
+
+- **确定性表单提交**：`POST /api/agent/form/submit` 结构化字段直达 `proposeWrite(action=create)`，不经 LLM 再编码
+  （旧的 NL 标记路径已删）。
+- `GET /api/agent/form/options`：多列（名称+按使用度选 3 个展示列）+ 名称搜索 + 分页，FK 二级选择器数据源。
+- `askUser` 返回 `allowFree=true`：前端选项片之外永远保留自由输入（Claude Code 风格）。
+- `chat.html` 整页重写：原生 JS（去 jQuery）、全视口、可折叠会话侧栏、单滚动区、markdown 表格、提议卡片、
+  collectForm 网格布局 + 类型化控件 + FK 选择器模态。
+
+### 19.5 验收（2026-07-28）
+
+- 意图门 bench50：**50/50 = 100%**（终跑 49/50，唯一错例为 Ollama 502 网络抖动，单测复核正确）。
+- agent 单步 bench50：严格 38/50 = **76%**（达标 ≥76%），宽松 45/50 = 90%。
+- e2e 冒烟（本地 saas 栈 + exec-staging=true）：查询+翻页 / 新增报价（表单→FK选择→确定性提交→确认→落库）/
+  改字段（落库）/ 作废（按单号定位→落库）全部通过；UI 全流程浏览器实测通过。
--
libgit2 0.22.2