 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
|
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
|
11780ed0b4
|
设置页能接本机的向量模型了，不用改代码
上一版只有三个写死的选项：本地哈希 / OpenAI 3-small / 3-large。想用本机起的
LM Studio、Ollama、vLLM，只能去代码里调 configure——等于没有。
现在可以填任意 base_url。配套加了一个探测接口（GET /kb/embedding/probe），
按地址列出那台服务上有哪些模型，从列表里选。模型名手填太容易错——LM Studio
里叫 text-embedding-qwen3-embedding-4b，不是 Qwen3-Embedding-4B，而填错的
表现是切换时 404，人还以为是服务没起。
base_url 跟着落库。不存的话重启后会悄悄退回本地哈希，而库里的向量是上一个
模型建的，检索整体退回关键词——用户只看到"重启之后搜得不准了"。
几处说给用户听的：
- 当前用的是什么、几维，直接显示在最上面
- 本地哈希旁边标"没有语义能力"——它是默认值，而这个缺陷不说没人会发现
- 切换成功的提示里带上新维度和"多少条存量向量需要重建"。换模型后维度多半
变了，存量全部作废，这件事要当场说，不能等人发现搜不准了再去猜
check-ui 加了一节，真浏览器里验过：展开、填地址、探测到本机的
text-embedding-qwen3-embedding-4b、出现「用它」。
|
2026-09-20 09:34:55 +08:00 |
|
|
ThearchyHelios
|
33c7c41336
|
记忆写进去读不回来：Copilot 不许自己起 scope，重建也管记忆了
查会话 cbe09f4b（「我是谁」）时发现的。用户说了「我叫张三」，下一轮问
「我是谁」答不上来——记忆在库里好好的，只是读错了地方：
写入 run 6cd33864 memory 节点 {"action":"write","scope":"user"} → write @ user
读取 run c71fa1bc memory 节点 {"action":"recall"} 没写 scope → recall @ default
同一个会话里 Copilot 生成的两张图，写的时候自己发明了一个 user 域，读的时候
忘了写、落回 default。根子在节点参考把 scope 列成了可填字段却没说该填什么：
- memory：… config: {action, query, content, scope, assign_to}
对比一下，memory_recall / memory_write 这两个**工具**压根没有 scope 参数，
一律用 ctx.memory_scope，所以走 agent 那条路从来不会错位。只有节点会。
现在从可填字段里去掉，并写明后果。节点的 scope 配置本身保留——以后接 project
时从 run.memory_scope 传进去即可，不用改节点。
顺带补上两个上一轮埋的口子。给 Chunk 和 MemoryItem 都加了 embed_model/embed_dim，
对不上就退回关键词，但**只给知识库做了 reindex**：
- store.reindex / stale_count 补齐，记忆终于有了恢复手段
- store.recall 加 on_degrade。以前退得悄无声息——知识库那边至少发一条 warn，
记忆这边只是"最近想不起事"，人根本不会想到要去重建索引
- 重建一次管两边。它们共用一个 embedder，换模型时一起失效；分成两个按钮的
结果是点了一个、以为好了，另一个还在悄悄退回关键词
- 没建倒排的片段也归这个按钮管。它们走全表扫，结果对但慢，而重建正好把倒排
一起建了；按钮只认"向量对不上"的话，这些片段永远等不到人来点
实机验证：一次重建收拾了 2 段知识 + 1 条记忆 + 2 个倒排缺口，三个计数归零。
数据侧另行清理（不在本提交里）：身份记忆从 scope=user 移到 default，删掉
zz_fix_* 等测试残留，删除前整表导出到 data/backups/。
|
2026-09-19 16:59:51 +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
|
e8ef6ff9a8
|
检索质量有数了：评测集 + 重排，alpha 不再写死
先做评测再做重排——否则重排的收益只能靠"搜两下感觉准了"。
**评测集**（test_retrieval_quality.py）：24 篇语料 + 16 个问题，问题分成字面
重叠和纯语义两类。第一版是 8 篇、主指标 hit@3，结果各档 alpha 全是 100%，
等于什么都没量——8 选 3 瞎猜都有 37%。扩语料、加干扰、主指标换成 hit@1
之后才开始能分辨。
量出来的第一个结论就推翻了我原来的猜测：
alpha hit@1 hit@5 MRR 字面 语义
0.0 88% 100% 0.911 100% 75%
0.2 81% 100% 0.880 88% 75%
0.5 81% 100% 0.880 88% 75%
1.0 81% 100% 0.880 88% 75%
本地哈希向量那一路不是"弱一点"，是**纯噪音**：给它任何权重，hit@1 都从 88%
掉到 81%。而 alpha 的默认值一直写死 0.5，等于主动把检索做差。改成跟着
embedder 能力走（default_alpha：有语义泛化才给 0.5，否则 0），节点上的
alpha 也不再写死默认值。
**重排**（memory/rerank.py）：初筛多捞一些（20 条），让模型按"对回答这个问题
有多大帮助"重排，再取 top_n。只捞 5 条的话重排最多把这 5 条换个顺序，第 6
条是对的也救不回来。
用已配置的对话模型做，不引入本地 cross-encoder——后者要下模型权重，和"零配置
能跑起来"的基线冲突。代价是每次检索多一次调用，所以默认关闭。
失败一律退回初筛顺序并说一声：解析不出分数、个数对不上、模型抛异常、没配
provider，四条路径都有测试。重排是增强，不该因为模型抽风就让整个检索挂掉。
|
2026-09-19 09:33: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
|
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 |
|