配套②：自行实作 ReAct 串流迴圈，以換取对事件型別、狀态过濾与 IDE 整合的完全控制。操作見 使用者指南 §12。
系列位置
完整导读見 系列导读与产品定位。
| 順序 | 文章 | 本題 |
|---|---|---|
| 0 | 系列导读与产品定位 | 系列导读与产品定位 |
| 1–3 | Agent 时代的数据分析工作流、可治理的 Agent Memory、Prompt 与 Context 工程 | 工作流、Context |
| 4 | 本文 | Agent runtime |
| 5 | 統一查詢层 | 查詢层 |
一、为何自研 ReAct
ReAct（Reasoning + Acting，推理—行動迴路）让模型在单轮对話中交替「思考 → 呼叫工具 → 读取观察 → 再思考」。通用 Agent 框架擅长编排，但 Lantide Data 需要更細的控制：
- SSE 事件型別細分：thought、tool_call、tool_result、message、ask_user、error…
- 狀态依賴的工具白名单与 mid-turn 刷新
- UICommand 与前端 interceptor 同步开 tab、写 SQL、Source Run 完成
- IDE 整合執行：工具产出須落在真实 SQL 分页、@@PROTECT0@@、UICommand——而非仅在远端 sandbox 回传图表
- 探索预算、provider fallback、token 压缩等产品級策略
因此採用 Python @@PROTECT1@@ + 自有 @@PROTECT2@@，而非套用现成 Agent 抽象——我們要的是与 IDE 狀态、SSE 事件、工具白名单逐行对齊的執行迴路，而不是通用编排上的便利。
二、架構总览
@@PROTECT3@@@@PROTECT4@@@@PROTECT5@@
每次迭代：解析狀态 → 过濾工具 schemas → 组裝 system prompt → LLM 串流 → 執行 tool / 暫停 ask_user / 推送 UICommand；狀态转換工具執行后同轮刷新 prompt 与工具集。
三、工具註冊与 TOOL_AVAILABILITY_MATRIX
每个工具定義 Safety（safe / write）与可用 AgentState。矩陣在每次迭代开始过濾 schemas，例如：
| 狀态 | 典型差异 |
|---|---|
| NoProject / Quick | 探索工具 + @@PROTECT6@@ |
| ProjectFocused | @@PROTECT7@@、@@PROTECT8@@、HTML 條件工具 |
| PlanPlanning | 文件与探索；限量 @@PROTECT9@@ 探数允許；无 SQL Tab 工具群、无統計 @@PROTECT10@@（prompt 禁止 @@PROTECT11@@） |
| PlanExecuting | @@PROTECT12@@、@@PROTECT13@@、@@PROTECT14@@… |
| ProjectFocused / PlanPlanning / PlanExecuting | @@PROTECT15@@、@@PROTECT16@@（按需读映射、小修 Reference） |
State prompt 不列工具目录 — 名称与参数以当轮 function schemas 为准（見 Prompt 与 Context 工程）。
四、ReAct 迴圈細節
4.1 迭代上限
@@PROTECT17@@ 预设 100，防止异常迴圈耗盡资源；达上限发送 @@PROTECT18@@ 事件。
4.2 探索预算（Exploration Budget）
@@PROTECT19@@、@@PROTECT20@@、@@PROTECT21@@ 計入探索。超过 exploration_soft_cap（预设 7）后，工具呼叫被跳过并回传 @@PROTECT22@@。
續跑協議： 下一个工具呼叫必須为 @@PROTECT23@@，且問題含标記 @@PROTECT24@@，选項含 Continue exploring / Stop for now。使用者选擇繼續则重置本轮探索計数；选擇停止则 Agent 应先整理发现再決策。不应仅靠靜默注入系統字串繞过人類確认。
4.3 Auto-continuation
@@PROTECT25@@ 且仍有空间时，可追加 "Please continue..."（次数上限），避免长報告截断。
4.4 Mid-turn 狀态转換
@@PROTECT26@@、@@PROTECT27@@ 等執行后，从 session 重新解析狀态，更新 @@PROTECT28@@ system prompt 与工具集，使同轮后續迭代落在正確狀态（例如 NoProject → ProjectFocused）。
五、Provider fallback
LLM 呼叫失敗时可依设定 fallback 至备用 profile，并在 SSE 中标示，減少单点模型不可用导致整轮失敗。
六、System prompt 组裝与 mid-turn 刷新
@@PROTECT29@@ 合併 core、state、知识、catalog 提示、HTML 條件段。狀态转換或 @@PROTECT30@@ 翻转后同轮重建，与工具 schema 对齊。
6.1 Query Step Ledger 注入（Layer 3.5）
多步分析时，模型需要記住「上一步物化了哪張表、SQL 长什麼樣」。每个对話在 workspace 内维护 Query Step Ledger：@@PROTECT31@@ / @@PROTECT32@@ 成功或失敗后写入步驟索引；system prompt 附加精簡摘要（快取名 + SQL 预览，≤1500 字元），使多轮后模型仍知近期步驟。完整 SQL 靠 @@PROTECT33@@、@@PROTECT34@@ 或 registry 查閱。
与 Plan Progress 分工： Plan 執行期的 Steps UI 与 @@PROTECT35@@ 的 @@PROTECT36@@ 來自 @@PROTECT37@@ 的 @@PROTECT38@@（report 后 @@PROTECT39@@）；Ledger 仍服务对話連續性。@@PROTECT40@@ 会将來源 conv 的 ledger 全量复製到新 conv，使 fork 后 @@PROTECT41@@ 与摘要不断裂。
6.2 Ledger 相关工具
| 工具 / API | 何时用 | 用途 |
|---|---|---|
| @@PROTECT42@@ | 需審閱某快取表的原始 SQL | 等同 UI「查看 SQL」，与 @@PROTECT43@@ 同源 |
| @@PROTECT44@@ | 多步链失序或需核对 step_id | 列出本对話步驟；可选附截断 SQL |
| @@PROTECT45@@ | 读取某次 run 的结果与 SQL | 記憶体或 spill 后的 meta sidecar |
| @@PROTECT46@@ 協議 | 每次 run 成功后（assistant 正文） | 一行摘要；runner 解析后回填 @@PROTECT47@@ / @@PROTECT48@@ |
@@PROTECT49@@ 由 runner 注入，LLM 不可自传；无 conversation 时跳过 ledger，物化策略仍依 workspace 启发式运作。
批註不走 Query Step Ledger——狀态在 @@PROTECT50@@ sidecar 与正文 mark，由 @@PROTECT51@@ / @@PROTECT52@@ / @@PROTECT53@@ 處理（見 Prompt 与 Context 工程 §十一）。
6.3 專案文件与批註工具
| 工具 | Safety | 典型狀态 | 用途 |
|---|---|---|---|
| @@PROTECT54@@ / @@PROTECT55@@ | safe | Plan/Report 相关 | 磁碟正文 + sidecar + @@PROTECT56@@ |
| @@PROTECT57@@ | write | Planning（非 Executing/Executed 正文锁） | 依 open 批註原子 patch 正文与 sidecar |
| @@PROTECT58@@ | safe | ProjectFocused、PlanPlanning、PlanExecuting | 依 @@PROTECT59@@ When to read 載入 Reference 全文 |
| @@PROTECT60@@ | write | 同上 | 小範圍 find-replace；不建立新 Reference 檔 |
七、HTML 工具与契約（正文摘要）
产品動機見 Agent 时代的数据分析工作流 §五。操作見 §10。
7.1 條件註冊 @@PROTECT61@@
为真时（@@PROTECT62@@ 或 Report tab 且磁碟已有契約 HTML）：
- 常駐 @@PROTECT63@@（Generate / Re-generate）
- 追加 read_html_text、get/patch_html_chunk_by_id、get/patch_html_styles 等
- 注入 Editing HTML Reports state 段
同轮 @@PROTECT64@@ 成功后，下一 iteration 重算 flag 与 schemas，无需換 tab。
7.2 @@PROTECT65@@
当使用者不在 Report tab 卻要改 HTML 时，Agent 先呼叫此工具解锁 chunk/樣式工具，再 read → get → patch。多份 report 皆有 HTML 且未指定檔名时应追問或回 @@PROTECT66@@。无 @@PROTECT67@@ 的旧檔应 Re-generate。每轮对話需重新 activate 或回到 Report tab。
7.3 契約要点（内化敘述）
- 根元素：@@PROTECT68@@
- @@PROTECT69@@ 内恰一个 @@PROTECT70@@ 承載全域 CSS
- @@PROTECT71@@ 直下可 patch 区块：@@PROTECT72@@（regex @@PROTECT73@@）+ @@PROTECT74@@；禁止巢狀可 patch 容器
- create_html_report 做 full 驗證；chunk 工具仅驗證 body
- standard-chartjs：head 含 Chart.js CDN + @@PROTECT75@@；图表用 @@PROTECT76@@ JSON；patch 后需重新 Open Report 才重繪
八、Agent Memory 工具
| 工具 | 方向 | 說明 |
|---|---|---|
| @@PROTECT77@@ | 读 | catalog 模式下以父标籤批次載入 Rules/Info 完整條目 |
| @@PROTECT78@@ | 写佇列 | 主動提案可重用知识进 Queued Knowledge；須使用者 Apply 后才注入 |
@@PROTECT79@@ 与被動萃取共用 @@PROTECT80@@；runner 注入 @@PROTECT81@@ 供校驗。頻控：每则使用者讯息（整次 Agent stream）最多 2 條提案；每 conversation 最多 5 條 pending（Apply/Dismiss 后釋放）。@@PROTECT82@@ 須为近期 user/tool 讯息的可驗證子串；禁止 SQL、快取表名等執行态内容。詳見 可治理的 Agent Memory §4.3。
九、UICommand 与前端 interceptor
部分工具不直接回传字串结束，而发送 UICommand SSE：前端 @@PROTECT83@@ 執行 @@PROTECT84@@、@@PROTECT85@@、@@PROTECT86@@、@@PROTECT87@@、@@PROTECT88@@ 等，并以 @@PROTECT89@@ 去重。使用者看見 tab 与结果变化，形成「副駕駛」体驗。見 §12.6。
十、ask_user：暫停／恢復
- Agent 呼叫 @@PROTECT90@@
- SSE @@PROTECT91@@ → 前端互動区
- 使用者回覆 → @@PROTECT92@@
- 结果餵回 ReAct，繼續迭代
逾时約 5 分钟。探索配額、執行模式、Execute 確认等皆走此協議（Agent 时代的数据分析工作流）。
十一、Token 压缩策略
三種策略在不同时间尺度互補，可同次 ReAct 轮次内先后觸发：
- 历史截断（跨轮）：长对話保留分析语境，丟棄較早无关讯息（Prompt 与 Context 工程 §十二）。
- Mid-turn compaction（单轮内）：一轮多次 tool 后 token 逼近上限，压缩本轮 tool 结果，保留 @@PROTECT93@@、快取名等关鍵欄位（同篇 §十三）。
- Auto-continuation：模型输出因 @@PROTECT94@@ 截断时，在仍有餘量下追加續写请求（§4.3）；与 context window discovery 聯動。
十二、前端串流（可选）
@@PROTECT95@@ 将 SSE 分派为 thought / tool_call / tool_result / message 等 Segment，以 mutable draft + @@PROTECT96@@ 節流 flush，避免每 token 觸发 React re-render；结束／錯誤／abort 路徑 forceFlush。
十三、SQL 執行工具（与統一查詢层对齊）
| 工具 | 作用 |
|---|---|
| @@PROTECT97@@ | 執行持久分页，物化快取 |
| @@PROTECT98@@ | Source Run DAG |
| @@PROTECT99@@ | 读取分页快取结果（支援以分页标題解析） |
| @@PROTECT100@@ | 探索：仅驗證 |
| @@PROTECT101@@ | 预览列（≤200）；條件物化为 agent 快取（見 統一查詢层 §8.1） |
工具回传的品質讯号也会进入 runner 判定：@@PROTECT102@@ 代表需要拆小步驟；@@PROTECT103@@ 只是建議可考慮 cache，不阻擋分析。Release smoke 的 hard gate 聚焦在 plan → todo → report、无明显錯誤迴圈与報告品質讯号；DAG / Source Run 则是 soft signal，用來观察可追溯能力是否被模型自然使用。
十四、工程決策总览
| 決策 | 原因 |
|---|---|
| 自研 ReAct | SSE + 狀态 + UICommand |
| 探索 ask_user 續跑 | 人類確认而非硬停 |
| 條件 HTML 工具 | 降预设 schema 噪音 |
| max_iterations 100 | 长链分析可完成 |
| UICommand | 真实 IDE 副作用 |
| Release gate 重分析品質 | 不让快取形狀取代可信報告 |
十五、结语
Agent 架構是工作流与 Context 的執行引擎：ReAct 迴路把分层 prompt 变成 SSE 事件、工具呼叫与 IDE 副作用（UICommand），Harness 与聊天沙箱的差异在于執行綁定真实工作区。
若模型「一直 validate 卻不 run_query」，请同时檢查 Prompt 与 Context 工程 的 QEM 說明与本文探索预算；查詢物化与血緣语意見 統一查詢层。