yilunjiang/AgentLab
1
0
Fork 0
mirror of https://github.com/ThearchyHelios/AgentLab.git synced 2026-11-15 14:52:02 +00:00
Code Issues Packages Projects Releases Wiki Activity
131 Commits 4 Branches 0 Tags
8059cd514748a5e80eb6221c5ef5cd00cc03dbf0
Commit Graph

15 Commits

Author SHA1 Message Date
ThearchyHelios 8059cd5147 Excel 导入改造期 1：止血与版本底座——写错的列名不再静默得 0，导入不再悄悄读错，每次上传生成不可变的版本，运行固定发起时的数据版本 
连接层
- 所有 SQLite 数据源关闭双引号字符串兼容（DQS），写错的双引号列名直接报错；设置失败就拒绝连接，启动时自检
- 连接缓存按数据源加版本快照分键、按源整体失效、最多 32 个；版本快照以 immutable 只读打开，建连接前核对文件哈希，并在借出连接时核对文件指纹，被改过就拒绝查询
- 结构探查遇到取不了列的视图时逐个对象重取，只跳过坏的那个并注明原因

解析（新 xlsx_scan + tabular）
- 先流式扫描真实边界和版式（不信 dimension），再按边界读值，不整表进内存；按 Excel 自身上限设硬上限，并发解析最多两个
- 隐藏和深度隐藏的工作表不导入；稀疏区域、无缓存值的公式、同名工作表、DTD 拒收
- 去掉空行和两侧空列；列名表名统一规范化（新 names 模块）并保留原表头，撞名不再互相覆盖
- 前导零、超长数字按文本；千分位按数字；日期不带 T；带单位的数字文本写进回执
- 数字列混入非数字、交叉表和多块结构必须由用户决定（422），可选存空值或按原样导入（未规整）；STRICT 建表，整份在一个事务里写完

版本底座（新 table_versions、raw_store）
- 每次上传写新库文件、落盘、0444，事务里写构建、导入记录、快照后才切指针；失败时旧版完整可查
- 原件按哈希存档，不提供下载，可以清除；上传源不许改连接字段、不再重新探查；手工 SQLite 源不许指向上传目录和应用自己的数据文件（按文件身份判断）
- 启动时清理半成品与孤儿文件、给老上传补初始版本；被运行引用的版本不回收，发起运行与回收互斥
- 上传接口的解析移到线程池

运行固定数据版本
- 发起时把图里（含子工作流）用到的上传源的当前快照记进运行记录和 run.started，续跑、审批恢复沿用；数据源工具按固定的快照生成描述、表结构并查询
- 固定的版本没了、源被删除后同名重建，都明确报错，不改用当前版本或同名的新源；查询快照记 data_version

证据层
- 新报告记 entity_syntax: 2，[[t:明细]]、[[c:明细.金额]] 和 SQL 里不加引号的中文表名都认得，名字按 SQLite 的口径查找；老报告按原规则复核，结果不变
- 写作规则改为中文表名、字段名一律用 [[t:]] / [[c:]]；未规整的表在工具描述、写作目录和裁判摘录里标出

前端
- 上传弹窗接上导入前的决定（混合列、交叉表）和导入回执（跳过的隐藏表、类型转换、警告、原表头对照、未规整标记），上传前告知原件会保存
- 数据源卡片按 origin 认上传的表格，显示当前版本；上传的表格不再给「探查结构」
 2026-10-01 13:42:04 +08:00
ThearchyHelios fcdcc30d4e 可点击证据第二期：取数链路打通、问数据的答案逐段可点；发布前自动修复 
一、可点击证据第二期

取数链路
- 智能体、工具节点、代码节点、知识检索取数时都记进证据台账；报告目录按台账编出 Q1… / K1…
- 报告可以引用快照里的一格（[[v:Q1.r0.gmv]]），也可以由系统从快照生成整张表（[[table:Q1 cols=… rows=0-4]]），
  表里每一格都是可点的片段；取值一律以快照为准，取回快照时复验哈希
- 口径卡表达式新增 cell(x, row, column)，lineage 精确到单元格
- 智能体开 cite_fields（配合 output_schema）后，循环结束做一次结构化抽取，每个字段标出取自哪次查询的哪一格，
  再到快照里核对：一致记 verified；不一致以快照为准并告警；查不到的记为空值，永远不兜底成 0
- 代码节点新增 evidence_role（source / compute）和 code_sha；沙箱算出来的数不能被报告直接引用，要进口径卡
- 查询快照记下列类型，文本列按文本渲染（年份 "2026" 不再显示成「2,026」）
- 升级前发起的运行（停在审批上的）一律走旧逻辑：新的 task 只追加在循环之后，恢复时不会错号

证据接口与面板
- 片段链接上查询步骤：SQL、被引用的行加前后各 2 行、高亮到格；数据源可设 mask_columns 遮罩列，
  遮罩在查询时记进快照，数据源事后改名或删除也照样遮罩（在有身份体系之前，遮罩只减少暴露，不是安全边界）
- 输入来源写明核对结果（与快照一致 / 模型报的值和快照不一致 / 没查到记为空）；口径卡缺输入时也给出完整的链
- 受管出具要在契约里声明 cells 才能引用单元格；受管与否记在所钉版本上，改画布不再让受管版本的正式运行降级
- 口径卡可以用 caliber_from 钉住另一个已发布工作流里的口径卡，上游有新版本时按 upgrade_policy 处置，
  和子工作流同一套规则；子工作流节点也补上了升版处置的配置项

Copilot、校验与报错
- 问数据的答案里有数字时，搭 input → 智能体 → 报告 → 出口，报告直接引用查过的单元格
- 写 SQL 前核对数据源的表结构，SQL 里出现表结构里没有的列会被打回
- 不再搭「智能体文字 → 转换节点解析 JSON」这种图；转换节点的 JSON 报错分清是上游模型写坏了、
  模板里裸插了模型文字（给出 | json 的改法），还是模板本身写错了
- 工具节点遇到「查询失败」「SQL 被拒绝」判为失败；发起运行前检查绑定的工具是否存在，不存在时直接拒绝并给出入口

二、发布前自动修复

- 问题带上机器编号（code）和修复 id；新增只读接口 POST /api/workflows/{id}/publish-check 和 /autofix
- 修复分三类：答案唯一、不降低要求的一键修复；要人拿主意的给选项（不替人选）；结构性问题交给 Copilot
- 一律先预览，不自动保存、不自动发布；删节点、删契约、放宽审批、关掉 strict、改级别等降低要求的改动一律拒绝，
  Copilot 的方案也要过这一关；应用后重跑检查，错误必须变少且不能冒出新的
- 发布弹窗打开就先检查；问题面板新增「发布前检查」，平时就能看到、就地修掉
- 门禁修正：契约有 report_from 时不再要求 narrative（模板⑨可以发成受管）；全图默认审批为「全部放行」时同样拦下
- 修掉画布保存会抹掉全图默认（defaults）的老问题：以前任何一次保存都会把它清空，审批 always 因此被悄悄放宽

验证（沙箱）：tsc 干净，生产构建通过，pytest 2268 passed（两遍），check-all 17 项检查、3915 项全过
（新增 check-publish）；关键行为做了变异验证、全部抓到。
 2026-09-28 21:20:04 +08:00
ThearchyHelios 62aac187d8 工具审批三档、智能体护栏取代固定 12 步、检查脚本分道并行 
MCP / 自定义工具的审批三档（tools/trust.py）
- 平台看不出这两类工具做什么，以前审批关卡一律当它们安全、照跑不误。现在默认每次调用都等审批；
  工具页可以逐个改成「始终允许 · 门控把关」或「始终允许」，审批卡上的「始终允许」等于前者
- 门控把关：每次调用先由门控模型审一遍工具说明、参数和节点任务；判可疑、出错、超时、答不成格式，
  一律交还给人，不会变成放行。判定包进 checkpoint，审批恢复重放时不再问一遍
- agent 节点、工具节点、协作团队三处关卡都接上；团队成员停不下来等人，门控没放行的调用不执行
- 每次运行在发起时快照档位（runs.tool_trust），恢复和接着跑沿用同一份；正式运行不看档位，一律等审批；
  升级前发起的运行照旧不问——它们可能正停在某个审批上，多问一次答复就会对错号
- 接口：GET /api/tools 带 trust / trust_key，PUT /api/tools/trust；设置新增门控模型；新事件 tool.gated
- 界面：工具页三选一、审批卡「始终允许」、设置页门控模型、运行记录解码 tool.gated；
  顺手修了 MCP 工具详情 404、工具审批被驳回却显示成放行

智能体护栏（engine/guards.py），取代固定的「最多 12 步」
- 步数只留兜底：默认 100，设置里可改；以前画布自动写进节点的 12 按「没填」处理
- 同一个工具、同样的参数第二次不再执行，把上次的结果交还给它；连续 3 步拿不到新信息就收尾
- 每个节点的令牌预算（默认 200 万）和金额预算（默认不限），都可以在设置里改成不限
- 上下文用到窗口的 60% 先压缩早期的工具结果，到 85% 就收尾；临近任何一个上限先提醒模型一次
- 下游结构化校验失败时写明是上游哪个 agent 提前收了尾；复核信号带上收尾原因，
  问数据页只在真是步数用满时才给「放宽步数重跑」
- 上限在发起时快照（runs.agent_limits）；升级前发起的运行一字不改走旧逻辑

检查脚本
- check-all 默认 4 道并行：量时间最多的两项互不重叠；并行时没过的最后单独重跑一遍，重跑才过的
  单列成「偶发」。16 项全量从约 21 分钟降到约 7 分钟（加上一次重跑约 10 分钟）；--lanes 1 回到串行

顺带修的
- 设置接口里的 limits 改为只读：库里存着旧版设置页写进去的一份（max_agent_steps: 25），从不生效，
  却盖住了真实上限，问数据页照着错的数许诺
- test_kb 里嵌入模型那条测试不再真连 api.openai.com（代理慢时一条要等近 4 分钟）
- check-stream 读滚动容器前先等它挂上，并行跑时不再偶发

验证（沙箱）：tsc 干净，生产构建通过，pytest 1655 passed（两遍），check-all 16 项检查、3562 项全过；
新增后端测试 53 条，关键逻辑做了 22 处变异验证、全部抓到。
 2026-09-28 11:47:45 +08:00
ThearchyHelios 587bf7e27c 第三波前两批：六个「看着成功其实没干活」的平台漏洞堵上，记录页能回放，管理页与画布收尾 
起因是一次探索运行：Copilot 改节点时把工具绑定整份抹掉，agent 没有工具只能写「假设调用」，
校验节点的自动修复编出 total_count=0 让 schema 通过，协作成员把工具调用标记当文字输出了四轮，
轮数用完后节点把原话当成功结果交出去——运行标成已完成，数据库一次都没查。

平台可信度（先写失败测试）
- Copilot 修改节点改为合并：没写的字段保留，null 才删除；协作成员按名字合并。前后端同一套规则，
  工具集合变小时自查报警、改图回执列出变化
- 新校验规则：提示词点名了某个工具而节点没有绑定它，判错误，Copilot 自查会交回去修
- 校验修复只许改格式：冒出原文没有的值就判修复无效；修复这次模型调用计入用量
- 识别模型把工具调用写成文字的情况（DSML、<tool_call> 等标记）：纠正一次，仍然如此就判失败并说明原因
- 协作团队用完轮数不再按成功交付：默认失败，可选降档，点出一次都没派到的成员
- 审批恢复后，同一节点里已经执行过的工具调用复用结果，不再重复执行

后端
- 查询时限交给数据库执行（Oracle call_timeout、PG statement_timeout、MySQL max_execution_time、
  SQLite progress handler），可按数据源配置；超时报错与实际耗时一致
- 等审批的运行可以真正取消；会话列表带最后一轮状态；测连接结果持久化；探查结构可只看不存；
  自定义工具可草稿试跑、写坏的参数定义保存时拒绝；MCP 服务改动后作废旧工具缓存；
  检索命中带贡献分解；重建索引在后台跑并报进度；报错统一收进 core/errors

前端
- 公共层：管理页共用件、失败说明（lib/explain）、健康状态进公共库；目录按表各自加载并有超时，
  一张表卡住不再拖垮整站；上传显示真实字节进度；离线横幅只播报不变的句子
- 画布：卡片只说游标所在的那一次执行；等审批时可放弃运行；团队收尾判定与未完成说清楚；
  回放用量取那一刻的值
- 编排页：Copilot 合并语义与工具变化回执；「用完轮数时」选项；正式运行期间锁住所有改图入口
- 回答流 / 问数据：新失败类型说人话并给下一步；画布与右栏互相定位；数据源范围、回收站、重新核对
- 记录页：「航迹」页签复用画布时间轴，可拖动回放、列出关键时刻；列表行带执行 / 等人 / 失败缩略条
- 外壳：统一的离开前确认（data router），导航、⌘K、快捷键、后退都会先问

验证（沙箱）：tsc 干净，pytest 838 passed（两遍），14 个检查脚本中 13 个全绿；
check-ui 余 1 项旧断言（按旧日期格式找运行行），3c 更新。
 2026-09-27 10:16:32 +08:00
ThearchyHelios e10c4f23fc 界面与交互全面翻修（前两波）：运行态有了 HUD 和时间轴，终态会收尾，全站令牌、组件、文案统一 
来自 2026-09 的 UI/UX 审查（142 条）。本提交是前两波，第三波（记录页接入时间轴、跨页互链、check-ui 更新、全站扫尾）另行提交。

地基
- 设计令牌：全局规则和 .btn/.field/.chip 放进 CSS 层，Tailwind 工具类重新生效，选中态、开启态不再被吞掉；字号阶梯；
  辅助文字在所有底色上 >= 4.5:1；状态色专用，节点类型色与之拉开色相；「跟随系统」真的跟随，首帧不闪深色；新字标与 favicon
- 基础组件：confirmDialog / promptDialog 取代原生对话框；toast 出错不自动消失、可复制、读屏可播报；离线横幅与断线恢复；
  九种剪影的状态徽标；唯一一份状态文案（lib/status）、格式化（lib/format）、术语（lib/terms）、报错人话（lib/errors）
- 运行态内核：事件折成航迹（run/trace.ts），可投影到任意时刻；取消 / 失败 / 服务重启后统一收尾，不再永远转圈；
  run.status 随事件回写；token 事件不再堆进 events
- 后端：协作成员逐个完成即发事件，调度者决策有事件；时长分执行 / 墙钟 / 等人；API 时间带时区；
  中断的运行也发 stream.end；运行列表可筛选翻页；删除运行 / 工作流有保护；运行默认值接通；可测未保存的配置；
  报错说清发生了什么、为什么、怎么办

功能
- 画布：状态四重编码、固定高度遥测槽、按缩放三档、运行胶囊与 HUD、航迹时间轴与回放、执行轨迹边、
  等待闸门、跟随执行、正式运行只读、一次性时刻（开场点亮、回扫、阻断级联、出具印章）
- 编辑：撤销重做、版本历史、问题面板可定位、三栏可收起、模板与表达式字段区分、变量血缘、快捷键、带搜索的选择器
- 回答流 / 问数据：贴底才跟随滚动、工件下钻、出具横幅列出缺口、答案可复制导出、按会话的忙闲、
  答案不再在 2000 字处截断、重启后这一轮会收尾
- 记录页：待审批 / 运行中 / 失败页签、筛选翻页、实时接流、排错路径指到节点、封存凭证常驻
- 管理页：新的「数据」页、写操作失败都有反馈、弹窗里先测连接、统一持久的连接状态
- 外壳：导航改版、⌘K 命令面板、? 快捷键帮助、404、页面标题与 favicon 状态点、后台提醒

验证（沙箱）：tsc 干净，pytest 579 passed，14 个检查脚本中 13 个全绿；check-ui 剩 1 项旧断言（按旧日期格式找运行行），第三波更新。
 2026-09-26 23:11:31 +08:00
ThearchyHelios 5928cc052e 三道只配不管的护栏开始干活：运行时限、模型超时、清单核对 
显示成生效却没生效，比明说没有更危险——它让人以为有东西在兜底。

1. max_run_seconds 只存在于配置和设置接口里，没有任何代码执行它：一个挂住的
   模型或工具能把运行和它占着的并发名额一直拖着。现在 runner 用 asyncio.timeout
   强制执行，按"一段执行"计（等人工审批时 _drive 已结束，不算）；超时判 failed、
   说清是哪道上限，可以接着跑。别处抛的 TimeoutError 不冒充这道上限（看
   Timeout.expired()）。

2. 模型调用从来没设过超时：ModelSpec.timeout 从没被赋值，那条传参分支一次都没
   执行过，所有调用走 SDK 默认的 10 分钟外加重试。新增 model_timeout_seconds
   （默认 300 秒）作为缺省，节点显式配的仍优先；已确认 ChatAnthropic / ChatOpenAI
   都接这个参数。

3. manifest 哈希只写不验，而且是在 run.finished 落库之前算的——清单里恰恰少了
   宣布"跑完了、成果是什么"的那条，改成果清单照样对得上。现在终态事件落库之后
   再封存，并记下封到哪一条（manifest_seq，新列）；新增 verify_manifest 与
   GET /api/runs/{id}/verify，运行详情页加了核对按钮。封存之后追加的事件不算篡改。
   老运行没有 manifest_seq，按当时的口径还原范围——开发库里 300 条带哈希的历史
   运行全部核对通过（成功 / 失败 / 取消各类都有），没有一条误报。

设置页「运行环境」补上单次执行时限和模型调用超时两项，README 加了对应的常见问题。

顺带修了一个被 _seal 放大的老问题：_drive 的收尾被打断时（关停取消、库连接出错）
漏掉 _tasks.pop，留下的任务让下一次 shutdown 的 gather 在别的事件循环里抛
"future belongs to a different loop"——测试里表现为每八九轮一次、一出就是几十个
teardown error。pop 移进内层 finally，shutdown 只等未结束的任务并清空。修后全量
连跑 12 轮 12 轮全绿。

test_guardrails.py 8 例：超时中止（挂住的节点 1 秒后被停下）、缺省模型超时、封存覆盖
run.finished、改成果被戳穿、事后追加不误报、老运行按旧口径核、中断态未封存、接口
404。414 → 422 passed。
 2026-09-25 15:59:32 +08:00
ThearchyHelios ed83aa2fa4 并行支路一条失败时，运行不再永久卡在 running 
两条并行支路一条失败，LangGraph 会取消另一条；那一条若正在写库（节点收尾写
工件最常见），整个运行就可能永远停在 running，占着的并发名额也不还。修审批时
加的并行驳回用例约五次卡一次，才把它翻出来。

根因在两层，都是"取消打进进行中的数据库清理"：

1. aiosqlite 0.22 的 stop() 每调一次都往工作线程队列里放一个"关闭并退出"
   请求，线程处理完第一个就退出，之后的请求没人处理，等它的一方永远挂着。
   close() 的 finally 会调 stop()，SQLAlchemy 优雅关闭被取消后退回的强制
   terminate 也会直接调——同一连接上两者一碰就卡死。并发 close 两次，10 次卡
   10 次。现在同一条连接的 stop() 只真正执行一次，之后的调用拿同一个 future。

2. 卡死解开后露出第二层：SQLAlchemy 的 _close_connection 记完日志会把
   CancelledError 原样抛出，跳过了把连接记录清空的那一行，已经关掉的连接留在
   池里，下一个取到它的人拿到 "no active connection"。主引擎开 pool_pre_ping：
   探活失败按断开处理、换新连接（aiosqlite 方言把这句判为断开，已核对源码）。

验证：test_aiosqlite_close.py 4 例是确定性的（并发 close、close 撞上强制
stop、被取消后的 close、重复 close），去掉补丁 3 例超时失败。复现脚本同一场景
连跑两批各 40 轮：修前 12 轮内必卡，修后 80 轮 0 卡、0 次坏连接抛给调用方；
SQLAlchemy 在被取消时仍会记一条"Exception terminating connection"日志，那是
它自愈过程的记录，不影响结果。334 → 338 passed。
 2026-09-25 15:20:46 +08:00
ThearchyHelios cc608f56ec 跑完先过一道复核再交给你：异常说破、数字不许现编、出错自动改一次 
「跑完了」和「答得对」之间一直没有任何一层。库里 264 条 succeeded 里，
14 条带着 warn、4 条 agent 步数用满，而交到用户手上的答案对此只字不提。
最糟的一次（run dd9927e6）交出去的干脆是「本轮只执行了第一个工具」——
一句内部管道文案冒充结论。

出具体系（issuance.py）本来就是干这个的，但它挂在输出节点的可选契约上，
还要配口径卡提供受控指标集；问数据页生成的图基本都是 input → agent → output，
走不到那条路。所以补一层轻的。

**干净的运行一次模型都不调。** 先用规则扫一遍事件流（engine/review.py:scan），
没扫出东西就到此为止。实测 15ms 返回。这是整层设计的前提，测试里用
「monkeypatch 一个会抛异常的模型，断言它没被碰过」来守。

**分类挂在 code 上，不是中文消息串。** 12 处 warn 发射点都带上 code。
这样「流式失败，回退非流式」能归成 benign 直接跳过——它对答案内容零影响，
为它叫一次模型等于每次网络抖一下就多花一笔；而「步数用满」归 broken。
原来这两者在事件流里长得一模一样。工具报错之后同一个工具又跑成了，
算 degraded 不算 broken——否则参数自愈每修一次就报一次「答案不可信」。

**复核不许现编数字。** 它手上只有原答案和一份异常清单，没有任何原始数据，
写出来的新数字只能是凭空来的。直接复用 issuance.trace_numbers，把原答案的
数字当受控指标集，对不上就整条退回原答案、只留说明。硬拦截，不是提示。

**规则管重试资格，模型只有否决权。** 一开始写成两边取并，实测 loop_limit
时模型判 retry=true——而重跑一遍循环还是会撞上限，白烧一次建图加一次跑图。
反过来之后，「检索什么都没查到」这类也不会被模型强推重跑。

**重试带着失败的那张图，不是推倒重来。** 原来传 base_graph=null，模型只看到
「原问题 + 一句失败原因」，很可能原样再建出同一张坏图。而且它连自己上次建了
什么都看不到——会话历史按 status != running 过滤，正在重试的这一轮恰好被
排除在外。现在交回去走后端的改图分支，调大步数、改正参数就是改一个字段。
上限一次。

**答案等复核完成再显示。** 端到端抓到的：答案先摆出来，十秒后说明才追上去——
这十秒里用户读的是一个没人核对过的结论，正是要修的那件事本身。改成落库立刻
（防关标签页丢结果）、显示等复核，并给复核加 25s 上限。说明排在成果上方，
broken 用报警色、degraded 用普通边框——混成一个样子用户就学会了一概忽略。

复核结论跟着轮次落库，刷新后还在；也进下一轮的对话历史，否则模型会拿一个
已知不可信的结论当事实继续往下推。

验证：后端 242 passed（新增 test_review.py 25 条）；tsc 干净；
check-decode / check-stream / check-ui 全过，check-stream 新增 9 条渲染断言。
两条端到端都在真浏览器 + 真模型上跑通：检索降级那次说明正确排在答案上方；
重试那次建图请求 2 次、第二次 base_graph 带着失败的 3 个节点、第一版没漏出去。

复核结果不是事件流，decode.ts 翻译不到它，所以渲染测试放在 check-stream。
 2026-09-20 11:18:53 +08:00
ThearchyHelios 6a46e4b55c 大文件传得进来了：分批算向量、上传转后台、边读边数大小 
压测量出来的三个问题，10MB 文本（切 7914 段）：

    上传耗时  150s（本地哈希）   换成 Qwen3-Embedding-4B 要 40 分钟以上
    而这 150 秒是压在一个 HTTP 请求里同步跑完的

浏览器和反向代理的默认超时都在 60 秒上下，也就是 5MB 以上的文件用户必然
看到超时——而后端其实还在跑，跑完文档也确实入了库。界面显示失败、数据其实
成功，比直接拒绝还糟。

**分批算向量。** 原来 ingest 是 embed_texts(pieces) 一次全发。本地哈希只是慢，
换成远端模型就是必挂：近八千段一次请求塞不下（OpenAI 单次上限 2048）。
reindex 那边早就分批了，ingest 这条一直漏着——而我上一轮刚把"换真模型"做成
设置页里点两下的事。

**上传转后台。** create_document / process_document 拆开，上传立刻返回
status=processing，切块和算向量在后台跑，进度写回文档行，前端轮询显示
"正在切块并算向量… 4288/7914 段"。实测上传返回 0.07 秒。

进度这件事返工过一次：先用另一个 session 单独写，结果整个过程界面上都是空的、
只在结束时闪一下——SQLite 只允许一个写者，主事务开着的时候那次写被堵住了。
改成主事务自己按批提交，顺手把进度写进去。

失败要写回 failed，否则永远停在"处理中"转圈。服务重启时也把残留的
processing 收尾成 failed——和 runner 对 running 的 run 是同一个道理。

**边读边数大小。** 原来是 raw = await file.read() 读完再判断，传个 1GB 的
文件内存在报 413 之前就吃掉了——那个检查拦的是"入库"，不是"占内存"。改成
按块读、超了立刻停。上限从写死的 10MB 变成配置项，默认 50MB。

端到端验过：10MB 上传返回 0.07s，后台进度 768→1472→…→7914 实时可见，
最终 ready / 7914 段。
 2026-09-20 09:47:02 +08:00
ThearchyHelios 913380f738 倒排索引取代全表重算；PDF/Word 终于传得进来 
**倒排**：以前每次检索都 select(Chunk) 全量载入，再在 Python 里重建一遍 BM25
——不只是扫表，是对每一段重新分词、重新统计词频，每次查询都来一遍。几百段
无感，上万段就是秒级，而那正是知识库开始有用的规模。

没用 SQLite 的 FTS5。方案里写了实施前先验证，验了：trigram 分词器要求查询
至少三个字符，中文的「商家」「订单」「权限」这些两字词一个都召不回。照搬会
让召回大幅倒退。现有分词器本来就做中文单字 + 二元组，自己存一张 chunk_terms
既保住召回，也不把知识库锁死在 SQLite 上。

快是次要的，一致才是前提——所以先写了"倒排必须和全表扫给出同一个名次"的
测试。它当场抓到两个真问题：

1. BM25 被算了两次：倒排按全集统计（N、avg_len、df）算一次，hybrid_rank
   又在候选子集上重建一次，而子集的 df 和平均长度是另一套数。改成把倒排
   算好的分传下去，不再重算。
2. 原来的 BM25.score 遍历的是**带重复**的查询词表：「导出订单最多多少行」
   里「多」出现两次，贡献就加两次。倒排用 set() 去重，顶部那条差了 2.32。
   改成按查询词频加权。

还有一处是排序确定性：分数并列时稳定排序保留输入顺序，而两条路径喂进去的
顺序天生不同——同一个查询会因为走了哪条路给出不同名次。两边都按 id 定序。

倒排跟着 ingest 建、跟着删文档清、跟着 reindex 重建；没建倒排的片段（存量
数据升级上来就是这样）退回全表扫——宁可慢，也不要因为索引没建好就说"没搜到"。

**解析**：upload 以前只收 UTF-8，PDF 传上去直接 415，而 mime 字段记了却从不
参与判断。现在认 PDF / DOCX / HTML。解析库走可选依赖 [docs]（几十兆，只用
纯文本的人不该为此付出安装时间），HTML 用已在依赖里的 bs4。

几处是实际验出来的，不是想出来的：DOCX 要连表格一起取（合同和口径说明的关键
信息常常整个在表里）；PDF 每行拖着排版填充空格，不清掉会混进切块和词频统计
（实测 416 字里只有 68 字是正文）；扫描件提不出文字要明说，否则悄悄存一份
空文档，用户以为传成功了却永远搜不到。

PDF/DOCX 两条路径在临时 venv 里用真文件验过（含中文、表格、扫描件、坏文件），
没有动开发环境。
 2026-09-19 09:44:09 +08:00
ThearchyHelios df935599f2 知识库：换 embedding 模型不再 500，检索能回指了 
三件事，都是"这三个模块一条测试都没有"的后果。

**换 embedder 会让检索整体 500。** 库里是 512 维的本地向量、查询是 1536 维的
远端向量时，cosine 直接 `shapes (1536,) and (512,) not aligned`。from_blob 有
dim 参数，但 kb.py 和 memory/store.py 调用时都没传；而且存量向量属于哪个模型
代码里没有任何地方记着，所以也无从降级。

Chunk / MemoryItem 各加 embed_model + embed_dim（走现成的 _COLUMN_MIGRATIONS，
存量回填空值，正好表示"不知道是谁建的"）。检索遇到对不上的向量整体退回纯
关键词并说破，不是把它们当 0 分静默沉底——那样用户看到的是结果莫名其妙变差，
而不是"这里有一批索引该重建了"。配套 kb.reindex + POST /api/kb/reindex。

长期记忆那份一起修了。判重那条更危险：维度碰巧相同但模型不同时 cosine 算出来
是随机数，会把不相关的旧记忆认成"重复"，然后把新内容丢掉。

**默认 embedder 没有语义能力，而开关藏在一个环境变量里。** LocalEmbedder 是
特征哈希 + TF，和 BM25 吃同一批词；alpha 默认 0.5 等于给了它一半权重，同义
改写一条都召不回。开启真模型的唯一开关是 AGENTLAB_USE_OPENAI_EMBEDDINGS——
没界面、没人会发现。改成设置项（照 COPILOT_SETTING_KEY 的路子），知识库页顶部
能选能看能重建。

配置失败必须响：第一版写成静默退回本地，但选了 OpenAI 却拿到哈希向量的人，
在搜不出同义表达时完全无从怀疑到这里。现在抛 EmbedderUnavailable，API 400
原样交回"检查 OPENAI_API_KEY 是否配了"，且不会把配置改掉。

**检索结果不进工件库。** db_query、工具节点、agent 工具调用都落 put_json 快照，
run_retrieve 什么都不落——于是结论只要来自知识库，"这个数是哪来的"就断在这儿，
而数字回指正是这个项目的签名能力。现在落 kind="retrieval_snapshot"，并发一条
retrieve.end 带 artifact id。解码层补了正式映射（原来会掉进"未知事件"兜底，
画成一坨原始 JSON）。

新增 test_kb.py 11 条，补上这三个模块此前的零覆盖，包括 embeddings.py 里
注释记着、但一直没有测试守的那个归一化边界（单条候选被 min_score 误杀）。

端到端在真实服务上验过：撞上存量向量返回 200 + 降级说明（以前 500）、
重建后 stale 归零、配不起来的远端模型 400 且配置不变。
 2026-09-19 09:27:07 +08:00
ThearchyHelios dcadc0c48b 对话有上下文了，左边也能选会话 
三条 run（d983c4e6 / 14103db5 / 08c3de1c）在用户看来是一次对话，系统里却
毫无关联。查下来不是哪里传漏了，是整层缺失：

- 每轮 base_graph=None 从零建图，Copilot 不知道上一轮问过什么
- 每轮 thread_id = run.id，三条独立的 checkpoint 线程
- 前端 turns 只活在 zustand 里，刷新页面就全没了——那三轮当时在界面上
  已经找不回来，只剩 runs 表里三条互不相干的记录
- 后端 13 张表里没有会话这个概念

加两张表（conversations / conversation_turns）。失败的轮次也记：只记成功的，
历史就成了一份美化过的记录，而人回来最想搞清楚的恰恰是上次卡在哪。

Copilot 的上下文带三样：前几轮问答、上一轮那张图（走 _slim 去掉坐标噪音）。
只给问答文字不够——"再按月份拆一下"会让模型重新设计一张图，实测经常接到另
一张表上，答案对不上前一轮。运行时另外注入 {{ input.history }}，管的是指代：
用户问"它们平均多少"，图里的 agent 得知道"它们"是上一轮那 12 家店。

左侧会话栏只在问数据页出现，可折叠、可改名删除，当前会话存 localStorage。
轮次按会话分桶缓存——切走再切回来要看得到原来的步骤，回源只拿得到问答。
历史轮次的执行过程不预加载，点「看执行过程」才取事件、走现成的 decodeRun。
画布右栏的 Copilot 依附工作流各有一条会话，连说两次"再加一个节点"能接上了
（base_graph 带的是图的结果，带不出"你刚才要我干什么"），但不进左侧列表。

过程中修掉的两个自己引入的坑：

- 第一版在列表为空时自动建一条会话。create 是异步的、StrictMode 把 effect
  跑两遍，于是每次进页面都留下两三条"新对话"。改成用户开口那一刻按需建
- 加了"在上一轮的图上改"这条指令之后，模型照改图协议只发 update_node，
  而问数据页这条路径的累加器从空图起步，操作全部落空，用户收到的是
  "图校验未通过：图是空的，先拖一个节点进来"（会话 f5db9809 的第二轮，
  而它的 explanation 证明上下文其实完全读懂了）。指令改成沿用 id 和 config
  但完整重发，另加一道兜底：空图且上一轮有图时把操作重放到那张图上

check-ui 多一节「会话」：切换、刷新还在、逛一圈不多出空会话。
 2026-09-18 17:58:04 +08:00
ThearchyHelios 39e7a5b014 数据源接入：MySQL / Oracle / PostgreSQL / SQLite 
阶段①。产品原先能取数的只有 http_request 和沙箱里自己写代码——面对"分析上季度
华东区销量下滑"这类需求，用户得自己知道数据在哪张表、字段叫什么，再手写 SQL 塞进
代码节点。最难的部分留给了用户。

## 连接层（app/data/）

方言差异全收敛在 engine.py 一处：Oracle 要 service_name/sid、MySQL 要 charset、
各家默认端口不同。三个驱动都是 asyncio 原生且免装客户端——oracledb 走 thin 模式，
不需要 Instant Client。密码复用 app/core/crypto 的 Fernet，和 Provider 同一套；
build_url 默认把密码替换成星号，日志和错误信息里用这个版本。

introspect.py 产出两种粒度：summary()（表名+代表字段，几百 token，给 Copilot 的
system prompt 用）和 describe_table()（单表完整字段，按需取）。分两种是因为一个
中等业务库全量塞进 prompt 轻松几万 token，既贵又会把真正的需求淹掉。

## 守卫（app/data/guard.py）

这是唯一不能出错的地方：SQL 由模型生成，模型会写出什么事前无法穷举，防线不能
建立在"它应该不会这么干"上。三层：

- 只读判定用**白名单**而非黑名单——黑名单永远漏，MERGE/CALL/GRANT/各家私货写不完
- 多语句在到达驱动前就断掉，不赌驱动默认只跑第一条（MySQL 开了
  CLIENT_MULTI_STATEMENTS 就会全跑）
- 行数/字节/超时三重上限，一条 SELECT * 不该把内存和模型上下文一起打爆

刻意不引 sqlparse：完整解析 SQL 方言是无底洞，而这里的判断很窄——"首关键字是
什么"和"有没有第二条语句"。窄问题用窄解法。难点是不能误杀：`SELECT ';'` 只是
一条语句，简单 split(";") 会把它切两半然后拒掉，那比漏杀更让人无从下手。

## 工具（app/tools/datasource.py）

每个数据源动态生成一对 db_query__<源> / db_schema__<源>，而不是一个通用工具带
datasource 参数：工具名自带语义，模型不会把查销售库的 SQL 发给财务库；description
里直接塞表清单，省掉"先问有哪些表"那一轮。接进 registry.build_tools 作为第四来源
（前三个是内置/MCP/自定义）。

查询结果落 put_json(kind="query_snapshot")，把 SQL 原文 + 结果集 + 数据源一起存，
出具体系的数字回指能下钻到"这个数是哪条 SQL 查出来的"。

## 实测

真实 SQLite 业务库（600 行订单，埋了华东 6 月断崖的信号）+ 真实模型：
agent 8 轮自主查询——列表 → 查三张表结构 → 探数据时间范围 → 查地区维度 →
按月汇总 → 按地区+月份下钻，准确定位到华东 6 月从 1187 件跌到 354 件。
只读守卫在 agent 路径上同样生效（UPDATE/DROP/多语句全被拒且数据未变）。

测试 55 项：守卫 30 项（含"字符串里的分号不能误杀"）、连接与探查 15 项、
URL 构造 6 项、Copilot 流式 4 项。
 2026-09-17 10:39:23 +08:00
ThearchyHelios 2df591d05f 工件库：内容寻址存储、节点输出与工具快照落盘、运行清单哈希 
事件流里的输出是给画布看的截断预览，出具溯源需要完整证据。
新增 data/artifacts/ 内容寻址工件库（sha256 即地址，取回时复验哈希，
篡改即报错）；节点完整输出与工具调用快照（query+结果集）自动落盘，
事件只携带工件 id。运行终态对全部事件计算清单哈希存入 Run，
事后对事件流的增删改会与它对不上。

graph_hash 剔除 viewport 后计算——挪画布不改变图的身份。
Run/Workflow/WorkflowVersion/Approval 预置分级与治理列，
init_db 附带 SQLite 轻量列迁移。
 2026-09-14 10:10:20 +08:00
ThearchyHelios 964eeaa829 AgentLab：可视化 Agent 编排实验台 
在画布上拖拽编排 agent 工作流，并实时看着它执行。

后端 FastAPI + LangGraph：把画布 JSON 编译成 StateGraph，15 种节点
（模型/Agent/多Agent、工具/沙箱、分支/循环/子图、记忆/检索/整形、
人工介入/结构校验）。选 LangGraph 是因为可视化编排真正难的是暂停、
恢复和回放，而 checkpointer + interrupt() 正好把这几件事做在了底层。

前端 React + React Flow：节点元数据驱动属性面板与连接桩，运行时
节点高亮、边流动画、卡片内流式 token 全部由同一份事件流驱动。

关键实现：
- Agent 内工具审批用 @task 缓存模型调用，interrupt 重放时不重复计费
- 沙箱保持只读根文件系统，代码经 exec+base64 写入（put_archive 会被
  只读容器拒绝），断网、非 root、内存/CPU/超时限额
- 检索为向量与 BM25 混合，本地哈希 embedding 零配置可用
- 分支条件走 AST 白名单求值器；HTTP 工具逐 IP 拦截内网与元数据地址
- Mock provider 让无 API Key 也能跑通完整链路

7 个内置模板全部冒烟通过，含真实模型端到端验证。
 2026-09-13 17:27:00 +08:00