 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
|
86a0928512
|
知识库页不再把"退回本地哈希"藏起来：配了语义模型却没连上时说实话，也不再劝人重建
本机配的是 LM Studio 上的 text-embedding-qwen3-embedding-4b。服务启动时它没起，
load_setting 连不上，整个进程就一直用本地哈希——它后来起了也不会自己连上，原因只在
服务端日志里留一句。页面按"配的是不是 local"判断，于是：
- 不标"没有语义能力"，看着一切正常，检索却一直是纯关键词；
- 高亮"重建索引（73 段）"——那些"对不上"的向量正是 qwen3 建好的，一点就拿哈希
覆盖掉，连上之后还得再重建一遍。
改法：
1. 后端记下保存的配置为什么没生效（embeddings.unavailable_reason），状态接口多报
fallback / fallback_reason：配的是语义模型、实际在用本地哈希。重新配置成功就清掉。
2. 页面按实际生效的 embedder（has_semantics）标"没有语义能力"。退回时说清配的是哪个、
在哪、为什么没连上，给「重新连接」——发的就是保存着的那份配置，服务起来后点它即可，
不用重启；"重建索引"收起，存量提示改口成先别重建。明确选了本地哈希的照旧：标没有
语义能力，重建按钮还在。
验证：test_kb 新增一条，走完"启动连不上 → 状态里报退回并带原因 → 重新连上后消失 →
明确选本地不算退回"。check-ui 新增一组伪造状态接口的断言（退回 / 重新连接 / 明确选
本地，写请求一律拦下）；把页面换回旧版本跑，这组挂 8 项。后端 471 passed，tsc 与
check-decode / guards / stream / ui 全绿；本机状态接口现在如实报出退回和原因。
|
2026-09-25 19:09:19 +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
|
1e9f32b869
|
embedding 能接本地端点了：维度改成探测，不再按模型名猜
在本机 LM Studio 上接 Qwen3-Embedding-4B 时撞出来的两个兼容问题。
**维度不能猜。** 原来是"名字里有 3-large 就 3072，否则一律 1536"。本地部署的
模型五花八门——bge-m3 是 1024、Qwen3-Embedding-4B 是 2560——猜错的后果不是
差一点，是所有存量向量都被判成"和当前 embedder 对不上"，检索整体退回关键词。
改成建 embedder 时实际探一次。
**langchain 默认发的是 token 数组。** 它先把文本分词，再把 token id 数组发过去，
OpenAI 官方认，LM Studio 这类本地服务只收字符串，直接 400：
'input' field must be a string or an array of strings
自定义 base_url 时关掉这个行为发原文。我们的片段都在 800 字上下，本来也用不着
那套长度保护。顺带设了 chunk_size=512——远端接口单次批量有上限，不分块的话
大文档必挂。
报错也改了：原来只说"检查 OPENAI_API_KEY"，现在带上试的是哪个地址、哪个模型
——本地服务没起的话，照着旧文案去翻 key 是白费功夫。
实测 Qwen3-Embedding-4B（2560 维）对比本地哈希向量：
hit@1 hit@5 MRR 字面 语义 入库 每查
哈希 88% 100% 0.911 100% 75% 0.2s 0.00s
Qwen3 94% 100% 0.958 100% 88% 3.4s 0.09s
涨的全在语义类，字面类没被搞坏。has_semantics() 转真后 alpha 默认从 0 自动
回到 0.5，不用手调。
一个没料到的结果：纯向量（alpha=1）只有 81%，比纯关键词（alpha=0）的 88% 还低,
混合（0.5）才是 94%。专有名词靠 BM25、换了说法靠向量，两边各管一半——混合
检索在这份语料上是真有必要，不是摆设。
样本只有 16 题，差一题就是 6 个百分点，别把 94% 当结论；方向是明确的。
|
2026-09-20 09:31:00 +08:00 |
|
|
ThearchyHelios
|
901d840b86
|
Word / PDF 真的传得进来了，表格切开也还读得懂
上一轮做了解析，但那条路在产品上够不着：
- environment.yml 装的是 [microvm,dev,db]，没有 docs——新机器起来，传 PDF
只会得到一句"要先装解析库"
- 文件选择框的 accept 里压根没有 .pdf / .docx，点上传根本选不中这些文件
两处都补上。表格类（xlsx）故意不放进 accept：它进知识库会被切成文本，
聚合算不了、数字也无法回指，那条路该走数据源。
装上依赖实测各格式：Word（含表格）、PDF（含中文，扫描件会明说要先 OCR）、
HTML、txt/md/csv/json 都通；Excel 和 PPT 不认得，报错说得清楚。
**切块对表格的处理是这次的主要工作。** 一份 60 行的 Word 表格切出来长这样：
块1 首行 | 上海 | 172151 | 13%
门店名被切没了，也没有表头——召回到这块，模型看到的是一列没有主语的数字。
两个毛病：
1. 重叠按字符切（buf[-120:]），会从行中间断开。改成只在行边界取，
整段没有换行就宁可不要重叠
2. 表格横跨多块时，除第一块外都没有列名。改成开新块时把表头补在最前面
第二条我第一版写成了 tail+header+block，表头被夹在重叠的那几行后面成了中间
一行——"表头在不在"查出来是 True，看着修好了，块的开头其实仍然是一串没有
主语的数。测试里专门有一条盯着表头必须领头，就是为这个。
端到端验过：60 行表格的 Word 传上去切成 3 段，搜"门店销售额"召回的片段
第一行就是"门店 | 城市 | 销售额 | 同比"。
|
2026-09-19 22:58:01 +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
|
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 |
|