yilunjiang/AgentLab
1
0
Fork 0
mirror of https://github.com/ThearchyHelios/AgentLab.git synced 2026-11-15 07:11:57 +00:00
Code Issues Packages Projects Releases Wiki Activity
95 Commits 4 Branches 0 Tags
9727c21d8dad46654ea76e763965557eabd1992c
Commit Graph

12 Commits

Author SHA1 Message Date
ThearchyHelios d071bf119f 可点击证据第三期：表名字段名和引文也点得开、可疑实体与结论句、受管门禁 G1–G5、证据审计导出 
一、表结构、实体与引文

- 数据源工具查库时顺带存一份表结构快照（schema_snapshot），和查询快照一起进台账、进封存；
  台账里的查询记下 SQL 用到的表
- 报告里的表名、字段名可以点：反引号里的名字一律核对，正文里的裸名字只在明显是标识符时才自动链接，
  常见英文单词不链接；点开看到它出现在哪次查询、类型、所属的表，快照被截断时写明
- 找不到的名字标成可疑实体：在快照、SQL、结果列里都没有的记「可能是编造的名字」并给出最接近的 3 个；
  快照被截断、核对不了的记「核对不了」，不冤枉成编造
- 检索引文 [[q:K1|原文]]：原文在检索快照的命中片段里逐字出现（空白归一化后）才算有出处，点开高亮原文位置
- 自动链接的名字不算句子的引用，只有写作者写的引用才算

二、结论句与出具

- 报告节点新增 claims：off（默认，保持原样）或 require_citation（没有引用的结论句计入缺口）
- 受管级别的正式运行里，可疑实体和没有引用的结论句按「有缺口」降档，不拦截；探索运行和已发布级别只标注
- 契约的 claims 和报告节点的设置取更严的那个；受管正式运行里写 ignore 也按降档处理，并给出警告
- 出具横幅除了数字，也写出可疑实体和没有引用的结论句

三、受管门禁 G1–G5（只看图和配置）

- G1 带契约的出口，成果字段的文字只能来自报告撰写节点
- G2 模型写的文字不绕过报告撰写节点直接流进出口
- G3 报告撰写节点写明 numbers: strict、on_violation: fail、claims: require_citation
- G4 口径卡的输入不来自计算角色的沙箱代码
- G5 给口径卡供数的 agent 配 output_schema 并开 cite_fields
- 受管级别是错误、挡住发布；已发布级别只给警告；已经发布的版本照常运行，下次发布时按新规则检查
- 每条规则都接进发布前自动修复（一键修复 / 给选项 / 交给 Copilot）；禁止的改动补上关 cite_fields、
  删 output_schema、放宽契约 claims；Copilot 兜底不许自己把代码节点标成 source、不许放宽报告节点
- 发布弹窗里选「交给 Copilot」时明确写「正在交给 Copilot」

四、旧运行与审计

- 没有契约的旧答案：数字和已封存的查询单元格、口径卡值按数值比对，每个数最多 3 个候选，
  默认折叠，写明「猜测的来源，不能当证据」
- 有契约的旧运行：候选只从已封存的口径卡里找，人为插进工件表的行不当证据
- 证据审计：GET /api/runs/{id}/evidence/audit 按「无证据 / 可疑实体 / 有出处 / 旧运行猜测」分组，
  可导出 JSON 和 CSV（带封存状态）；记录页和画布上的报告节点显示「有出处 N · 无证据 M」

五、SQL 守卫修正（安全）

- 去注释改成单遍扫描，认得字符串和各方言的引号（单引号转义、MySQL 反斜杠与 #、PostgreSQL 的 $$ 与嵌套注释、
  Oracle 的 q'[…]'、SQLite 的方括号）；以前字符串里的 -- 会被当成注释，SELECT '--'; DROP … 这类写法能骗过多语句拦截
- 看不到服务器设置时每种读法都扫一遍，读法之间切分不一致就拒绝，任何一种读法是写操作就按写操作处理
- 执行查询和工具危险判定都按数据源的方言检查

六、其他

- 修掉检查脚本里画布检查的一处竞态，并行估时按实测更新
 2026-09-29 05:26:34 +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 3e311ec551 第三波收尾：跨模块整合、全站扫尾、检查脚本整合；网页工具认得本机代理的 fake-ip 
整合（3c-integrate）
- 公共层：跨天时长（formatSpan / formatOffset / formatLapse）、本机署名（lib/actor）、检索分类色令牌、
  数据源目录（useDatasources）收进公共层；失败说明能一次列出多个写坏的自定义工具，查询超时指到数据源的查询时限
- 管理页收尾：设置页接入统一的离开前确认；检查脚本不再把沙箱里的真实值打进输出
- 画布 ↔ 右栏：点出具印章、点节点能跳到右栏对应位置；「定位」直接聚焦到出问题的字段
- 回答流 / 问数据 / 记录页：失败信息带「去哪修」且不再被翻译两遍；协作团队的结局按执行截取；
  等审批时断流重连、而运行已在空档里跑完的，补全事件

扫尾（3c-sweep）
- 术语统一：开始运行 / 继续运行、工作流最大步数；未保存的运行统一叫「未保存的工作流」（后端新运行同步）
- 沙箱报错不再带 Python 异常类名；新增 check-tokens，未定义的 CSS 变量为 0，两个旧别名迁移后删除

检查脚本（3c-checks）
- check-ui 跟上新界面（运行列表按 data 属性找行），加上令牌与选中态的回归断言，输出里的名字打码
- 新增 check-all：按顺序跑全部检查、汇总退出码，--repeat 列出偶发项
- 单节出错只记这一节失败、不再带崩整个脚本；外壳遥测浮层「重新检测」时焦点不再掉到 body

网页工具与 fake-ip
- Clash / mihomo 一类代理开 TUN + fake-ip 时，查什么都先拿到 198.18 段的假地址，被当成内网拦截。
  新增 AGENTLAB_HTTP_TOOL_FAKE_IP_RANGES（默认空）：落在段里的解析结果改向公共 DNS（DoH）核实真实地址，
  公网放行、内网照拦、核实不了按拦截处理。DoH 默认先问境外的，境内公共 DNS 会对被封锁的域名返回污染结果
- 列表型环境变量接受逗号分隔（原来注释说逗号分隔、实际只认 JSON 数组）；域名解析改为异步，不再阻塞事件循环

验证（沙箱）：tsc 干净，pytest 866 passed（两遍），检查脚本全绿。
 2026-09-27 23:37:32 +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 a819f92903 审批只认明确的"同意"，而且每个会执行危险操作的地方都得过这道门 
三个口子，都实测复现过：

1. 回复"拒绝"，工具照样执行。四个节点四套审批解析：工具节点和代码节点对
   回复一律 bool()，"拒绝"、"no" 都是真；{"decision": "approve"} 反被当成
   拒绝；{"approved": "false"} 也是批准。现在收成一份 engine/approval.py：
   只认明确的批准，看不懂的一律按拒绝。填内容的 human input/edit 模式另算——
   裸字符串是交稿，只有结构体里明说"不"才驳回。

2. 可写数据源上的 DELETE 从来不问人。数据源工具是动态生成的，查不到
   ToolSpec，任何审批模式下都被当成安全；is_dangerous_call 写好了但全仓库
   没人调用。现在危险与否逐次判定：registry.call_is_dangerous 统一问，数据源
   工具把判定挂在 metadata["dangerous_if"] 上——同一个 db_query，查询直接
   跑，可写源上的写要先确认。工具节点、agent 节点、协作成员都走它。

   这一步以前没出事，只因为写入从不提交：run_query 走 stream，拿不到结果集就
   抛 ResourceClosedError，连接关闭时再回滚——审批通过的写也没落过库。审批接
   好之后才让写真正提交（先后不能反，反过来就是一个无审批写库的窗口）；
   RETURNING 这类带结果集的写照样返回行。工具页的"试一下"是人自己在执行，
   不设审批。

3. 协作团队的成员调工具完全不经审批。成员们并行跑在一个节点里、停不下来等
   人（恢复时节点整个重放，几个人的 interrupt 对不上号），所以需要确认的调用
   不执行，把原因交还给成员让它换做法；节点上显式设成"全部自动放行"才跑。
   前端补了这个选项。顺带修了同一处的两个老问题：成员步数不受 max_agent_steps
   约束；步数用完时把工具的原始返回当结论交上去（agent 节点在 4057cdc 修过
   同一个问题，这里没跟上）——现在补一轮不带工具的收尾。

连带修的：多条审批并存时，交给引擎的是库里存的那份回复，而它存之前被 _safe
截到了 2000 字，解包时又只留 value——人工改过的长稿被砍一截，带了内容的驳回
被当成交稿。现在存全文、只拆自己包的那层 {"value": x}。

test_approval.py 36 例；去掉修复重跑，引擎层 10 例全部失败，各对应一个真问题。
并行驳回那例翻出了一个运行卡死的老 bug，已在上一个提交单独修掉。
338 → 374 passed，连跑三次全绿。
 2026-09-25 15:21:20 +08:00
ThearchyHelios 71561a0133 探查失败不再伪装成"还没探查"：把实情和下一步交给 agent 
从 run 554a0f92 查出来的。那次问「userID=2 是谁」，9 次工具调用花掉 6 次、
前 29 秒没碰到一点真数据：

    + 2.1s  db_schema            → "还没有探查过结构，请在设置页里执行一次"
    + 4.9s  db_schema ×7 个猜的表名 → "没有 user / users / member / …"
    + 7.7s  SELECT 1             → 不信任前面的结果，先探一下连通性
    +12.8s  information_schema.tables   ┐
    +18.3s  information_schema.tables   ├ 自己把 schema 重建一遍
    +21.5s  information_schema.columns  ┘
    +29.2s  终于开始查真数据

根因：shop 的探查**失败过**（Lost connection to MySQL server during query），
但失败被存成了一个"成功但没表"的缓存，schema_synced_at 照常盖戳：

    {"tables": {}, "total": 0,
     "error": "OperationalError: (2013, 'Lost connection...')",
     "available_schemas": ["prod_shop", "shop_dev", "toolsdb", …10 个]}

于是三处同时说假话：界面显示"结构未探查"、工具对 agent 说"还没有探查过"、
而那 10 个候选 schema 就躺在缓存里没人交出去。**用户明明点过探查，是超时了。**

**分清"还没探查"和"探查失败了"。** introspect 的结果加 failed 标记；
失败照样把缓存存下来（候选是下一步的线索），但不盖"已同步"的戳；
界面把红字和候选列出来；探查按钮的提示也分清是超时还是 schema 填错。

**给 agent 一个它做得到的下一步。** 以前那句"请在设置页里执行一次结构探查"
——agent 进不了设置页。现在换成实情 + 候选 schema + "不要猜表名，直接查
information_schema / sqlite_master"。那条自救路线 agent 最后也走通了，
只是自己摸索了三轮才找到，直接告诉它就行。

describe_table 同样：缓存空的时候说"数据源里没有 user"是在误导，真相是我们
什么都不知道。那次一口气问了 7 个表名，收到 7 条一模一样的
"没有 X。现有的对象：（还没探查过结构）"，白花一整步。

顺带把逐表反射换成 SQLAlchemy 2.0 的 get_multi_*，但**别指望它治超时**：
实测 60 张表逐表 121 次往返、批量 122 次——反射缓存本来就把 get_columns 和
get_pk_constraint 合并了，而 MySQL 方言压根没实现 get_multi_*，落到基类还是
每表一次 SHOW CREATE TABLE。换它是因为这是 2.0 的正经接口、少三层
try/except，不是因为它快。shop 那次超时多半是偶发的，所以真正的对策
不在那儿，在"失败要如实记成失败"。

重新探查了一次 shop：153 张表、38 秒、成功。之前 agent 要花 6 次调用、
29 秒拼出来的东西，现在工具描述第一眼就给了。

验证：后端 269 passed（test_datasource.py 新增 4 条，守"失败不能被说成没探查过"
和"给 agent 的下一步它做得到"）；tsc 干净；三个 check 不回归。
 2026-09-20 18:05:11 +08:00
ThearchyHelios c02ef189bb 工具调用失败能自救；agent 改成一步一个工具 
起因是一条没人看得懂的报错：

    工具 db_query__shop 执行失败：
    _make_query_tool.<locals>._run() got an unexpected keyword argument 'query'

参数名写成了 query（它叫 sql），而 call_tool 对动态工具是裸 **args 展开的，
跳过了 args_schema —— pydantic 那句"缺少 sql 字段"漏成了只剩内部闭包名的
TypeError，既指不到是哪个工具，也说不出该填什么。同一个函数里内置工具那条
分支本来是校验的，两条路径不一致。

registry 里补上 prepare_args / describe_args，两条路径共用：

- 候选唯一时（多一个不认识的、少一个必填的）改名重试，并发一条 warn 说破
  —— 配置里那个错名还在，替它跑通一次却不吭声，下次照样踩
- 有歧义就不猜，报错改成"参数不对：query 不是它的参数；缺少必填参数 sql。
  它接受：sql（必填，字符串）— 要执行的 SQL…"，模型照着这句就能改对。
  这才是失败之后真正能自愈的重试
- 顺带堵了一类静默失败：pydantic 默认把认不出的键悄悄丢掉，全可选 schema 上
  {"tabel": "orders"} 会"成功"执行一次什么都没查的调用

agent 循环默认改成串行：一轮只调一个工具，看到结果再想下一步。并行更快，但
一批调用中间没有任何新的思考——第二个是照着"还没看到第一个结果"时的判断发出
去的。节点上留了「并行执行工具」开关。两个必须守住的点：没执行的调用绝不发
tool.start（前端靠 call_id 配对，发了没结尾的 start 会永远转圈），但必须各有
一条配对的 tool_result（少一条下次调用直接 400）。

交错思考跟着补上。4.6 起 adaptive thinking 自带交错，不需要也不该挂 beta
header（Opus 4.6 上手动模式压根没有交错）；4/4.5 那一代要手动开 thinking +
interleaved-thinking beta，光挂 header 是一条什么都不做的空设置。开了 thinking
就不能再传 temperature，这一代本来是收的，漏了就是 400。

还有两处是串行带出来的，一并治了：

- 步数用完时收尾取的是 messages[-1]，而那往往是给模型看的 ToolMessage。
  真漏到用户面前当过答案（run dd9927e6）：一句"本轮只执行了第一个工具"冒充
  结论。改成只取模型自己说过的话，并把"步数用完了、去调大最大步数"附在后面
- db_schema 一次能问多张表。一次调用就是一步，逐张问 6 张表就是 6 步——
  实测 8 步的运行里 7 步花在这上面，最后只剩一步真查数据
 2026-09-18 17:57:20 +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 a16cdf3ab1 修两条 critical：文件工具可读任意路径、并发代码节点互相覆盖 
## 文件工具可读任意文件（含加密主密钥）

sandbox_session 从请求体直接拼进工作区路径，没有任何净化。传 ".." 就能把
根目录挪出工作区，之后 _resolve 的越界检查是在这个被挪走的根下做的，等于失效：

  curl -X POST /api/tools/file_read/run -d '{"sandbox_session":"..","args":{"path":".secret_key"}}'
  → {"ok":true,"content":"8UygDbx9..."}    # 加密所有 provider Key 的 Fernet 主密钥

根因是同一段净化逻辑被抄了五遍：四个沙箱后端各一份，文件工具那份漏抄了。
所以提到 config.sanitize_session 统一一份，五处共用；RunToolIn.sandbox_session
再加 pattern 做纵深防御——畸形 session 直接 422，而不是悄悄净化成 default。

## 并发代码节点互相覆盖入口脚本

同一 run 的节点共用一个沙箱会话，而入口脚本写死 main.py。README 主打的
"连线即并行"会让并排的代码节点在同一 superstep 并发执行，都写 main.py 就
互相覆盖——后写的赢，每个节点却都拿到 ok=True 和"自己的"返回值。

  8 路并发同 session：7/8 执行了别人的代码，error 全为 None

改成每次执行生成唯一入口脚本（__entry_<uuid>.py），跑完即删。共享工作区语义
保留，跨节点传文件照常。四个后端同构改造，实测 8/16 路并发均 0 串味。

## 顺带修掉两个自己埋的坑

- conda 迁移把沙箱解释器隔离弄丢了：conda 环境 sys.prefix == sys.base_prefix，
  于是"干净解释器"挑出来的就是项目环境自己，沙箱代码能 import cryptography
  直接解密落库的 Key。改成实际探测候选解释器是否看得见敏感包，都不干净就
  退回 -S 关掉 site-packages。README 那句承诺现在重新成立了。
- -I 在 3.11+ 隐含 -P，脚本目录不进 sys.path，代码节点的 files 参数（多文件）
  在 seatbelt/bubblewrap 下一直是坏的，import helper 直接 ModuleNotFoundError。
  换成 -s -E，隔离意图不变，同目录 import 恢复。
- microvm 的 files_written 取 FsEntry.name（不存在），塞进去的是对象 repr。
  改取 path 的尾段。

沙箱回归 16 项通过（两档各 8 项）。
 2026-09-14 15:22:58 +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