docs: rename ai_op_queue; ProposeWrite writes draft only, execStaging in determi…

…nistic /op/{id}/confirm endpoint (not a tool)

docs: rename ai_op_queue; ProposeWrite writes draft only, execStaging in determi…
…nistic /op/{id}/confirm endpoint (not a tool)
zichun
1 parent 3009328f
Showing 1 changed file with 8 additions and 3 deletions
docs/agent-architecture.md
@@ -103,8 +103,13 @@
 **ProposeWrite 是单一写工具**（不拆 copyto/报价）。**agent 侧写入流程对所有写统一**：
 ```
-收集参数(FormCollect/AskUser/读行) → ProposeWrite 对话内【最终确认】 → 落暂存 sp_ai_addcommonwx
+收集参数(FormCollect/AskUser/读行) → ProposeWrite(出diff+写draft) → 用户点确认 → 确认端点执行
 ```
+
+**谁过 LLM、谁不过（关键）**：
+- **ProposeWrite（LLM 工具, immediate-return）**：授权校验 + 出 diff + 往 `ai_op_queue` 写一条 `draft`（payload 存服务端）→ 返回 `{diff, sId}` → **结束本轮，不执行**。
+- **确认端点（确定性 HTTP, 非工具/非 LLM）**：用户点【确认】→ `POST /op/{sId}/confirm` → status=confirmed → **同步调 ERP `/ai/execStaging/{sId}`** → 拿结果 → 回链接给用户 + **结果写入会话状态（供链式续跑）**。取消 → `POST /op/{sId}/cancel`。
+- **execStaging 不进任何工具、不新增工具** —— 它必须在"用户确认之后"这个独立事件里触发，塞进 immediate-return 的 ProposeWrite 会变成"确认前就执行"。工具仍是 6 个。
 - 报价即使已用 FormCollect 填完表单，**落暂存前仍要一份对话内最终确认**（确认 = 允许存起来的门）。
 - 落暂存后是 **ERP 的事、与 agent 无关**：ERP 对不同待办的策略（报价自动执行 `Sp_Ai_AddQuoQuoAfter` / copyto 让用户在 ERP 原生表单再确认→执行器执行）都在暂存之后。
 - **ProposeWrite 泛化为"提议任意变更动作"**：ERP 按钮动作（审核/过账/生成 等**写按钮**）也走这道确认门；只读按钮（查询/导出）归 Read。⚠️ 绝不给 agent 一条绕过确认门直接触发 ERP 写动作的路（后端权限只管"能不能做"，不等于"这次同意做"）。是否需要独立的"按钮调用"底层能力，待后台调查（过程是否写、读 API 会否触发写、后端是否对表单/过程/动作调用鉴权）后定。
@@ -113,9 +118,9 @@
 - **现状缺口**：现有 `sp_ai_addcommonwx`（239 行）**完全只为"生成下游单据"设计**（字段全是 源→目标 + 合并/分单模式），且**没有消费者**（`Sp_Ai_AddCommonAfterNew` 只入队从不执行）。缺 op 类型/目标记录id/payload/**用户·租户**/status/结果/自动标志/过期 → **覆盖不了 增/改/删/审核**。
-**⇒ 新建通用暂存表 `ai_write_queue`**（旧表留给存量或迁移）：
+**⇒ 新建通用暂存表 `ai_op_queue`**（旧表留给存量或迁移）：
 ```
-ai_write_queue(
+ai_op_queue(
   sId PK/深链token, sUserId, sBrandsId, sSubsidiaryId,
   sOpType,             -- create|update|delete|examine|generate
   sTargetFormId, sTargetModuleId, sTargetTable,