 ThearchyHelios
|
8ed0bc23f7
|
数据目录阶段 2B：引入 sqlglot，SQL 检查的解析层——按数据源方言解析、认表和别名、解析不了一律跳过
|
2026-10-03 10:15:52 +08:00 |
|
|
ThearchyHelios
|
050bea4b72
|
可点击证据第五期：老工作流一键升级为可追溯结构；受管问数据图的 cells 一键选；pytest 并行
一、一键升级（只给预览，不自动保存）
- engine/upgrade.py：确定性改写，纯函数、重复执行结果不变
- R1 契约的叙述指向模型调用节点 → 换成报告撰写节点（system 和 prompt 合成写作要求，模型配置照搬），契约改成 report_from
- R2 没有契约、但模型写的文字进了出口，而且上游有取数 → 同样换成报告撰写
- R3 input → 智能体 → 出口（问数据的典型图）→ 中间插入报告撰写节点，出口字段接报告的正文；
只改直接相连的出口，经过别的节点读它的出口原样保留并写明原因
- R4 配了 output_schema 的智能体 → 打开 cite_fields
- R5 代码节点的产出被口径卡读 → 不改，只建议标成取数，等人确认
- 一个叙述里混了几个写作者的，不猜，整步不做并写明原因
- POST /api/copilot/upgrade-evidence：返回改动、说明和改完的检查结果；assist 时再交给 Copilot 把纯算术的代码节点
改写成口径卡表达式，不是纯算术的保留并给警告
- 升级和发布前修复走同一道「不许降低要求」的检查，只多两个由升级点名的例外：模型调用换成报告撰写、R3 改接的那条连线；
改完不能更糟
- 校验对符合 R1–R4 的旧结构给一条建议「可以升级为可追溯结构」，不算提示、不挡发布
- Copilot 自查：报告撰写节点上游没有任何能引用数字的来源时打回
二、界面
- 问题面板的快速修复「升级为可追溯结构（预览改动）」：逐项写「节点 · 字段：原值 → 新值」，节点类型的变化写成
「模型调用 → 报告撰写」，新插的节点和改接的连线另外写明；「应用」后走现有的保存，全图默认不丢
- 画布改过、存失败、画布被锁都有明确状态；保存失败后手动存成功会清掉「没存上」的提示，
画布和预览对不上时「重试保存」不再盲存；校验接口失败时升级块照样在
- 记录页里没有逐段证据的运行给横幅「这次的报告没有逐段证据 → 升级这张图」，跳到编排页并打开升级预览
- 修掉一处旧缺陷：应用修复时只换配置、不换节点类型，模型调用换成报告撰写后存下去的还是模型调用
三、受管门禁：cells 一键选
- 图里没有口径卡、契约又没写 cells: true 的受管图，以前能过门禁、正式运行却每次失败；现在门禁拦下，
发布弹窗给两个选项：写 cells: true，或交给 Copilot 改成口径卡指标（人亲手选的不算替人打开，Copilot 自己打开照样拦）
- 「修完要更好」的复核不再把改完才冒出来、只能由人拍板的这一处算作改坏：Copilot 补上契约、把 cells 留给人问，
这一步会被采用，不再被判「冒出新的问题」作废
四、测试
- 开发依赖加上 pytest-xdist（锁文件只多了 pytest-xdist 和 execnet）：全量后端测试 -n auto 约 16 秒，原来串行约 2 分钟
- 修掉并行下暴露的一处测试竞态：运行先落终态、再另一个事务封存，测试改成等封存完成再核对
|
2026-09-29 13:27:27 +08:00 |
|
|
ThearchyHelios
|
95ff6470d1
|
后端依赖锁到测过的那一套：pyproject 卡版本范围，requirements.lock 写精确版本
langgraph 和四个 langchain 包原来完全不写版本，fastapi、sqlalchemy、aiosqlite 只有下限，
uv.lock 还在 .gitignore 里。按旧写法今天新装，22 个包和测过的版本不同，其中 sqlalchemy
会从 2.0.52 跳到 2.1.1。
1. pyproject.toml：LangGraph / LangChain 一族放行到下一个小版本——引擎依赖它们的断点
格式、interrupt / resume、流式事件和 thinking 块，这些在小版本里也改过行为。aiosqlite
与 SQLAlchemy 同样卡小版本：db/base.py 给 aiosqlite 0.22 的 stop() 打了补丁，连接池
强制断开时会走到它。mcp 卡在大版本 1。
2. backend/requirements.lock：后端全部依赖（含间接依赖、全部 extras）的精确版本，
--universal 跨平台。锁的是 473 条测试跑过的那个 conda 环境：本机要装的 96 个包逐一
对上，另外 3 个只在 Windows / emscripten 上装。
3. environment.yml 装包时以锁文件为约束（-c），换机器装到的是同一套。
4. scripts/lock-deps.sh 重新生成锁文件：已锁的版本默认不动，升级用 --upgrade-package /
--upgrade。README 补了用法，补装 extras 的命令都带上 -c。
验证：用同版本 Python 新建空环境，照 conda 的方式按 environment.yml 的 pip 行安装——
装到的 96 个包和测过的环境完全一致，473 passed。
|
2026-09-26 09:49:16 +08:00 |
|
|
ThearchyHelios
|
7b04162540
|
Excel/CSV 变成能查的表、PPT 读得进来、跑挂了能接着跑、文档和工具有了地址
四件事，其中 Excel 那条不是"多支持一种格式"，是补一个和地基冲突的缺口。
**Excel / CSV → 可以用 SQL 查的表。**
这个项目有条不可回退的决策：叙述层无算术权限，所有算术下沉到 SQL 或口径卡，
叙述只能引用（engine/issuance.py）。表格传进知识库只能被切块检索，数字就成了
模型从片段里"读"出来的——复核层拦得住凭空多出的数字，拦不住"从一堆片段里
读错了一格"。所以表格必须变成表。
不新增数据源类型：kind='sqlite' 早就支持，build_url 拿 database 当文件路径。
落成 .db 文件再建一条 DataSource 指过去，下游一行都不用改——SQL 守卫、结构
探查、db_query__<name> 工具、查询快照进工件库、Copilot 的数据源清单，全都白拿。
建表走 sqlite3 直连而不是 run_query：guard 的 _ALWAYS_DENIED 里有 create，
那是对的（模型不该能建表），而导入是我们自己发起的可信操作。
四个语义是这块的全部分量：
- **类型要推，不能全存 TEXT。** SQLite 是动态类型，但列亲和性决定排序和比较：
整数列落成 TEXT 的话 '10' < '9'，SUM() 在混入空串时静默出错，而没有任何
地方会报。逐列扫描推断 INTEGER/REAL/TEXT，空单元格存 NULL 不存 ""，
日期存 ISO（字典序恰好等于时间序）。测试里那条 ORDER BY 要是 9<10 而不是
'10'<'9'，守的就是整块的意义。
- **表头取第 1 行，但不猜。** 不做"自动找表头"的启发式：猜错的表现是列名变成
一行数据，没有任何征兆，直到某天有人发现汇总一直少一行。改成 header_row
可填，并把推断出的列名和类型当场回显——错了一眼看见。
- **同名重传原地替换，id 和 name 都不变。** 名字会成为工具名（db_query__sales）
而工具名写进了保存过的图，另起一个 sales_2 等于悄悄让那些图失效。
- **中文原样保留。** 一开始把 sheet 名清洗成了 ASCII，结果「明细」「汇总」都变成
sheet、sheet_2，模型和用户都认不出哪张是哪张——而 SQLite 的标识符本来就允许
非 ASCII，那道清洗纯属自找麻烦。现在只替换会断句的空白和标点。
实测：两 sheet 的中文 xlsx → 两张表，金额列 INTEGER，跨表 JOIN + SUM 跑通，
Copilot 的工具清单里带着表名。CSV 按 utf-8-sig / utf-8 / gb18030 依次试——
GBK 的 CSV 是 Excel 另存为的默认行为，按 UTF-8 读会得到乱码列名，而乱码不报错。
知识库那边顺手改了指路：传 .xlsx/.csv 进去不再说"不是 UTF-8 文本"，
而是告诉你该传到数据源那边、以及为什么。
**PPT。** 文本框和表格分开取（表格的 has_text_frame 是 False），幻灯片之间
留空行当段落边界。.ppt/.doc/.xls 这些老二进制格式认出来再拒，说清楚"另存为
新格式"——以前它们会掉进"不是 UTF-8 文本"那个兜底，对着一个 .ppt 说这话，
用户根本不知道该怎么办。
**问数据页的「接着跑」。** 挂了那一轮不该只剩一行红字：断点一直在 checkpoint
里躺着。按钮挂在 approvalsFor 那个每轮插槽里（本来就托着「看执行过程」和
「跑一下」）。不带图——问数据页改不了图，这里就是"用原来的配置重试失败的
那一步"，配置本身错了要到画布上改。实测：续的是同一次运行（8→13 条事件），
只跑了 lp 往后，轨迹里有 run.resumed。
**文档 / 工具的地址。** /knowledge/kb/:docId 是新页面——文档原来连详情视图都
没有，而切块这层做了不少事（按行边界留重叠、跨块续表头），结果一处都看不见。
现在逐段列出来带字数和 token 数，还标出"这份文档里混着两个模型建的向量"
（换模型只重建了一部分时真会发生，而那会让这部分内容悄悄退回关键词检索）。
新增 GET /kb/documents/{id}。工具那边 tab key 从 tools 改成 library，
否则地址是 /tools/tools/<id>。
验证：后端 265 passed（新增 test_tabular.py 16 条）；tsc 干净；三个 check 全过，
check-ui 补了文档/工具两节；四块都在真浏览器/真后端上端到端跑过。
开发库里造的演示数据源、会话和运行已清干净。
|
2026-09-20 16:19:07 +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
|
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
|
1756476a30
|
Copilot 等待期不再是黑箱，外加项目第一组测试
从点"生成"到第一个节点落到画布上，本机实测 31.7 秒（DeepSeek V4 pro，中等
复杂度需求）。这段时间界面上只有"正在起草…"五个字一动不动——用户没法判断
是在想还是已经卡死。生成质量本身没问题，瓶颈全在这段等待的体验。
三处改动：
## 思考转发
_iter_ops 原先只取正文、丢掉其余一切，模型的 thinking 块也一并丢了。现在用
thinking_text() 抽出来单独转成 thinking 事件，前端可折叠地实时显示。
刻意不用"把非 JSON 行当成思考"这种取巧写法：那会把模型的 markdown 注释、
协议跑偏时的乱输出一并当作思考展示出来，反而误导。不支持 thinking 的模型
就只有心跳，不硬凑假的思考。
注意这条只对支持 adaptive thinking 的模型（Claude 4.6+）生效，当前默认的
DeepSeek V4 pro 不会产出——代码路径用构造的 chunk 验证过，但端到端触发需要
启用 Anthropic provider。
## 心跳与阶段
模型沉默时每 3 秒补一拍，带阶段和已用时长。必须在 _with_heartbeat 这一层做：
模型不吐 chunk 时 _iter_ops 里那个 async for 的循环体根本不执行，在里面判断
时间差轮不到。阶段跟着实际操作走（planning → building → wiring → finalizing），
阶段会变本身就是"它还活着"的信号。实测那 31.7 秒里补了 10 拍。
## 失败后不用重敲需求
生成失败只有一个 ✕，重试得重新打开 Modal 把需求再敲一遍——而失败多半跟需求
本身无关（模型抽风、协议跑偏、网断了）。store 里留住 lastInstruction，
错误浮条上直接给"用同一需求重试"。
## 顺带：项目第一组测试
这组守的是体验契约不是实现细节——thinking 和 heartbeat 两路反馈只要断了就是
回归，而这种回归在界面上表现为"又变回干等"，很难被注意到。4 个用例覆盖：
thinking 块转发、纯文本模型不伪造思考、沉默期补心跳、阶段随进度推进。
pytest 走 [dev] extra，environment.yml 一并带上。
|
2026-09-14 16:01:06 +08:00 |
|
|
ThearchyHelios
|
4e901be0ec
|
改用 conda 管理后端环境，移除 uv
environment.yml 只负责把解释器和依赖装进具名环境 agentlab，依赖清单仍以
backend/pyproject.toml 为准，不在两处各写一遍。dev.sh 通过 conda run 解析出
真实解释器路径再启动 uvicorn，环境不存在时自动按 environment.yml 创建。
uv.lock 一并删掉：留着会和 conda 装出来的环境慢慢漂移，两套锁反而更难查问题。
|
2026-09-14 14:09:51 +08:00 |
|
|
ThearchyHelios
|
dd57c12016
|
沙箱改用系统自带的隔离原语，移除 Docker 依赖
跑一段不可信代码不需要一整套容器运行时。macOS 用 Seatbelt
（sandbox-exec，系统自带），Linux 用 bubblewrap；冷启动从 ~250ms
降到 ~25ms，且不再需要装任何东西。
守住三件事：默认断网、家目录不可读、只有工作区可写。策略由内核
强制且对子进程继承——沙箱内 subprocess 出来的 cat 读家目录同样是
Operation not permitted。解释器改用 sys.base_prefix 下那个干净的
Python，沙箱代码因此 import 不到后端的 FastAPI、SQLAlchemy 和凭据
处理代码。
如实标注能力边界，不给虚假的安全感：
- macOS 不强制 RLIMIT_AS，内存限不住（实测设 256MB 仍可分配 900MB），
health 接口申报 enforced 字段，界面把限不住的项划掉
- Seatbelt 是访问控制而非虚拟化：进程表共享，以当前用户身份运行
- bubblewrap 侧多隔离 PID/IPC/挂载视图，内存限额真实生效
顺带修两个 bug：
- LocalSandbox 设 RLIMIT_NPROC=64 会误伤——macOS 上它按 uid 全局
计数，用户已有上千进程时沙箱内任何 fork 都失败，连 bash 都起不来
- 模型所属 provider 被停用时，原先静默换一家继续用原模型名，必然
404 且报错指不到原因；改为直接说清是哪个 provider 被停用了
写 SBPL 的坑记在注释里：(deny default) 会让 Python 直接 SIGABRT，
改用「默认允许 + 精确拒绝」。
7 个模板全部回归通过。
|
2026-09-13 18:04:36 +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 |
|