8b4566ad1e
Merge pull request #4 from ThearchyHelios/feat/evidence-phase1
...
Feat/evidence phase1
2026-09-28 21:21:32 +08:00
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
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
e4f2693918
可点击证据第一期：报告里的每个数字都点得开出处
...
「引用即渲染」：写报告的模型只写引用标记（[[m:指标id]]、[[i:输入字段]]、[[see:…]]），数值由系统按口径卡
填进去，每个数字都挂着一条能复算的证据链。本期是数字层闭环；实体、结论句的概率性证据放在后续几期。
内核（engine/evidence.py，口径卡、出具契约、表达式等）
- 口径卡记录每个指标的来源：原式、代入式（每个输入写成「值 ← 路径」）、复算结果、口径与版本
- 出具契约的数值匹配改为按位置标注；同一个值有几个出处时记为「出处不唯一」并列出候选，不再随便挑一个
- 证据 id 由内容派生，事后对不上就是被改过；零值、结构性数字（列表序号、代码块标签）单独处理
- 口径卡新增 on_missing：缺输入时默认仍是整个节点失败，可以改成记为空值、交给契约判档
报告撰写节点（report）与引用模式的出具契约
- 流式生成时 token 里就是真实数字，不会漏出原始标记；裸数字、不存在的引用当场判违规，交回去重写
（max_repairs，默认 1 次）；仍不过时按 on_violation 失败（正式运行默认）或把违规标在报告里（探索运行默认）
- report.checked 事件记下核对结果，落在封存范围内；fail 模式下仍不过时带 failed，运行记录里画成失败
- 出具契约写了 report_from 就按引用核对：取回文档时复验哈希，独立重算一遍，全部带引用才判完整出具
- 成果字段逐字等于报告正文时标注 _evidence；复核只能加说明，不能改写带证据的答案（前后端各拦一道）
证据接口
- GET /api/runs/{id}/evidence 返回证据图；GET …/evidence/segments/{id} 返回一个片段的证据链
- 只认封存范围内的事件能追到的工件，不读 artifacts 表；封存被改过时不把任何一项标成已封存
- 没有报告的旧运行降级为 none 或 legacy_contract
界面
- EvidenceDoc 按块、句、片段渲染报告，片段是和正文一样的按钮；整份报告只占一个 Tab 位，
←/→ 在片段间移动、↑/↓ 按句、n/N 跳到下一处「无证据」、Enter 打开面板、Esc 关闭并把焦点还回去
- EvidencePanel：宽屏侧边、窄屏底部抽屉、360px 画布右栏里栏内展开；显示指标步骤、代入式、复算结果、
封存状态。正文不是封存的那份报告时明确说出来，不拿别的报告的封存画绿
- 出具横幅多一行「N/N 数字有出处 · 无证据 M」和「定位下一处」；没有 _evidence 的旧回答渲染一字不差
- 画布认得报告撰写节点；Copilot 手册补上口径卡、报告节点、出具契约的写法；新增模板「⑨ 可追溯周报」
验证（沙箱）：tsc 干净，生产构建通过，pytest 1601 passed，check-all 16 项检查全绿（新增 check-evidence）。
2026-09-28 11:47:23 +08:00
3c16300a24
Merge pull request #3 from ThearchyHelios/feat/uiux-overhaul
...
Merge pull request #2 from ThearchyHelios/main
2026-09-28 09:20:03 +08:00
4517c9eed3
Merge pull request #2 from ThearchyHelios/main
...
Merge pull request #1 from ThearchyHelios/feat/uiux-overhaul
2026-09-28 09:19:29 +08:00
ea9889df06
Merge pull request #1 from ThearchyHelios/feat/uiux-overhaul
...
界面与交互全面翻修（前两波）：运行态有了 HUD 和时间轴，终态会收尾，全站令牌、组件、文案统一
2026-09-28 08:18:09 +08:00
b418c0d951
最终验收：148 项逐条复核（原审查 142 条 + 平台问题 6 条），返工后 145 项解决
...
四组验收员拿审查原文在沙箱里逐条复现：133 项已解决、15 项部分解决、没有未解决或回退的；
另发现 10 个新问题。按归属返工后，剩 3 项低严重度：MCP / 自定义工具的危险标记（待用户拍板）、
选中环与运行态同色（需跨三处协调改）、「接着跑」这个说法是否更换（多处引用原文，暂留）。
这次返工改了
- 右栏：老运行没有 active_ms 时执行时长改按航迹算，不再显示最后一段的「22 ms」；循环出口行不再差一；
取消在一轮中途时泳道脚注不写「0 ms」；分支、循环出口显示 case 的说明而不是 key；
展开已完成轮次不再误报「N 条新进展」；旧数据里已完成的模型调用不再一律标成「已取消」
- 后端：跳过事件带节点名和类型；restore 版本时把已发布 / 受管退回草稿；只是打开旧会话不再把它顶到最前、
标成「刚刚」；协作团队全程没有成员交付成果、调度者却判完成时按失败或降档处理，不再当成功交付
- 画布：循环体有「循环体 · 最多 N 轮」的底框，出口标签不再被自己的走线穿过；运行中校验角标退让；
768 宽下工具栏不溢出；运行被拦时点名是哪个节点；正式运行弹层写明以谁的名义发起
- 问数据：离线时能力条不把「没取回来」说成 0；窄屏下会话列表收起；check-chat 在零点前后不再误报
- 公共层：FastAPI 422 校验错误翻成中文，不再把英文原文透给用户
验证（沙箱）：tsc 干净，pytest 878 passed（两遍），check-all 15 项检查全绿。
2026-09-28 02:42:40 +08:00
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
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
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
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
e46a3f0d62
嵌套循环的内层每轮都从头数：max_iterations 是"每进来一次"的上限，不是整次运行合计
...
运行 87daca70：一个计时器，外层每一拍里内层跑两个 50ms 的子拍。5 秒该推进 50 拍，
结果推进了 138 拍。循环节点走 done 出口时计数原样留着，外层下一轮再把它带进来，就从
上次停下的地方接着往上数：内层 max_iterations 是 5，第一、二拍各跑 2 个子拍，第三拍
1 个，从第四拍起一进来就撞上限直接退出，子拍一次都不跑（撞上限的 warn 136 条）。
嵌套的 foreach 更糟：外层第二轮时内层游标已经在末尾，内层一项都不再跑，也不报错，
结果只是悄悄少了一大截。
改法：走 done 时记 finished，再被带进来时从 0 数。index 仍停在最后一轮，结束后读
loops.x.index 的照旧拿到轮数；画布上内层的"第 N/上限 轮"也随之每轮重新数起。
测试：test_nested_loops 两条——嵌套 while 合计 6 次（修复前 3 次）、嵌套 foreach 走完
3×2 项（修复前只有 1a、1b）。用 87daca70 的原图在临时库里真沙箱重跑：内层每拍都是
"跑、跑、结束"，撞上限 0 次。后端 473 passed ×2。
2026-09-25 23:14:50 +08:00
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
3b2c082743
check-ui 跟上「在画布里打开」的新行为，而且不再往库里写图
...
429398a
2026-09-25 17:04:56 +08:00
9d375f8f1c
循环跑满自己声明的轮数，不再被全局步数上限半路掐断
...
「测试 1」按校验提示改好之后仍然跑不完：while 循环配了 1005 轮，每轮是"循环节点 +
循环体"两步，而整次运行的步数上限（max_graph_steps）是 200——跑到 100 轮上下 LangGraph
抛 GraphRecursionError，报错是一段英文，叫人去调一个界面上碰不到的 recursion_limit。
图没写错，是平台自己的两个上限在打架：校验通过，跑到一半才死。
全局上限防的是没人把关的环；loop 节点的 max_iterations 是作者明说的轮数上限。现在循环
按自己的轮数另记一份预算（schema.loop_steps），加在全局上限之上，子图同理。取上界：
一个节点最多跑 Π(包住它的各层循环 max_iterations + 1) 次，嵌套相乘；done 出口之后的
节点只跑一次，不按轮数记账，否则预算虚高、等于没有上限。
没有 loop 节点把关的环（分支连回上游）照旧由全局上限拦住，报错改成中文、说清预算怎么
来的、该怎么改；子图里撞上限报子图自己的名字和步数——以前那段英文会被外层包进 NodeError
原样带出来。
实测：「测试 1」照提示改完，在真沙箱里 1000 轮跑满，25 秒，结果 501500（= 2+3+…+1001）。
测试：test_step_budget 8 条——预算的上界、嵌套相乘、done 之后不记账；全局上限压到 20 步
时循环照样跑满 30 轮；空转的环中文报错；子图里的循环有自己的预算、空转的子图报它自己的
名字。把 runner / 子图的预算换成 0，对应用例确实失败。README 补了常见问题，测试数更新为 470。
2026-09-25 17:04:49 +08:00
0997603ccf
画完先自查：条件写错在校验时就拦下，Copilot 交付前按同一套规则查一遍、查出问题先改
...
开发库里四次运行死在同一句"循环条件写错了：表达式里不允许出现 Set"。条件原文是
`{{ vars.gate }} != "ok"`——把模板写法带进了表达式：`{{ x }}` 在 Python 里是"装着
一个集合的集合"。Copilot 的提示词写着"模板语法在任意字符串里用"，模型照做而已；
校验又不看表达式，写错了只有跑到那一步才知道，前面的步骤白跑。
1. 表达式：解析和静态检查收成一个 parse_expression，运行时、校验、Copilot 自查共用，
不会出现"校验说能跑、跑起来报错"。多套的 {{ }} 意思无歧义，在语法树上剥掉（字符串
里的花括号不动），按 vars.x 理解并提示。真写错的给能照改的提示：| 过滤器 → len(x)、
集合 → 列表、不认识的函数列出能用的、= 当 ==、引号里的 {{ }} 永远不成立、推导式、
切片、私有属性。and / or 短路掉的那半边也查。
2. 校验：按节点类型和模式挑出真正求值的字段（分支条件、while 条件、整形表达式、口径卡
指标、skip_if）。写错是 error、挡住运行；漏写 vars. 的名字提示会取到空值；while 没写
条件、整形没填表达式也说出来。foreach 的 condition、模板模式的 expression 不求值，不查。
3. 代码节点：assign_to 拿的是 stdout。「测试 1」修好条件后跑通了、结果却是空的——代码
最后一行是裸表达式，那是 notebook 的行为。设了 assign_to 却找不到任何输出的 Python
代码，校验直接拦下，提示 print(json.dumps(结果))。宁可漏判不可误判：子进程、exec、
附带文件里的 print 都算有输出；整行只有一个 {{ }} 的代码是运行时才拿到的（⑤号示例
整段就是 {{ vars.code }}），看不见，不猜。库里 20 张工作流无一误拦。
4. Copilot 自查：搭完用同一套校验过一遍，error 级的问题连同图交回模型——只修这些、只
输出改动，最多两轮。改好了才自动运行；改不好照实交付、列出剩下的问题，不自动开跑。
没问题的图不多花一次调用；只是多套了 {{ }} 的不返工。提示词改成"模板只在普通文本
字段里用"，并列出表达式字段的对 / 错写法和代码节点必须 print。
5. 前端：自查这一段在 Copilot 的过程里看得见——发现几处问题、交回去改、改好了没有；
改不好标红并说明没有自动运行。"搭好了，共几步"那一行不会被挤掉。
测试：新增 test_expressions（开发库里真实死过的四条条件、静态提示、按模式挑字段、代码
输出、带 {{ }} 的循环真跑一遍）与 test_copilot_selfcheck（脚本化模型：改好 → 自动运行；
改不好 → 不运行、最多两轮；干净的图一次调用；多套 {{ }} 不返工）。test_continue_run 里
用来制造运行时失败的表达式换成 `2 ** 100000 > 1`——原来那条现在在校验阶段就被拦下了。
check-decode 补了自查的解码断言。
2026-09-25 17:04:39 +08:00
03830d4815
服务重启不再把运行记成"用户取消"；接着跑也不再替人答掉下一个审批
...
dev.sh 开着 --reload，改一个后端文件就是一次关停。三件事以前都是错的：
1. 关停时在跑的运行一律记成 cancelled、原因"用户取消"——之后 resume 和
continue 都拒绝它，尽管 checkpoint 完好。现在关停时收到的取消记成 interrupted
（和强杀后启动扫描的处理一致），留一条 server_shutdown 日志说明原委，
不发 run.cancelled。
2. 关停会打断正在收尾的运行：状态已落、封存和 run.finished 还没写完就被取消。
现在已进入收尾的运行不取消，等它写完。
3. 因重启而中断的运行没有在等人的 interrupt，resume 却照样发 Command(resume=…)：
那个值会被后面遇到的第一个 interrupt() 当成答复——一个还没轮到的人工关卡被
自动作答（审查时的实测）；当前版本的 LangGraph 则直接在内部崩掉
（UnboundLocalError: resume_is_map），运行判 failed。现在没有待答的 interrupt
时从断点接着跑（输入 None）。
运行详情页：中断了却没有待审批的运行，以前显示"等待人工介入"却没有任何可点的
东西，现在说明原因并给「接着跑」。用真实库里的中断运行看过：无待审批的出横幅，
有待审批的仍由审批卡片处理。README 加了对应的常见问题。
test_shutdown.py 3 例，修前全部失败：关停不是用户取消；重启后接着跑，前面跑完的
节点不重跑、后面的人工关卡真的停下来等人；关停不打断收尾（封存照样写完）。
分两步修、中间跑了一次，确认第二例在关停修好之后确实撞上了 resume 的崩溃。
422 → 425 passed，连跑 8 轮全绿；check-guards / decode / stream / canvas-layout 不回归。
2026-09-25 16:05:14 +08:00
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
429398a156
前端四处直接伤人的地方：输入法回车、覆盖别的图、停止不停、整站白屏
...
1. 中文输入法选词的回车被当成发送。问数据页输入框不判组字状态（Composer 判
了，这里没有）：用户每选一个词，半句问题就被送去建图、跑图。同样的漏洞还在
会话重命名、知识库搜索、{{ }} 补全、⌘Enter 运行上。收成 ui.isComposing，六处
统一——Safari 结束组字那一下 isComposing 已经是 false、keyCode 还是 229，两个
都看。
2. 「在画布里打开」后 ⌘S 覆盖上一次打开的工作流。它只调了 setGraph：换掉画布
上的节点，store 里的 workflow 还是上一张图，保存就把那张图整张覆盖了（旧版本
还在版本表里，界面上没有入口找回）；没打开过图时 ⌘S 则什么都不做。现在建成
一张新工作流（以这一轮的问题命名）、走它自己的地址，原来的图不受影响。
3. 问数据页的「停止」不停。它只关了自己这头的事件流，从不调 runs.cancel，而后端
断开订阅不会取消运行——模型和 SQL 其实还在跑、还在计费，界面上却已经显示
"已取消"。等人工审批的那一轮照旧不动。
4. Copilot 编出一个不存在的节点类型，整站白屏、没保存的编辑一起丢。三层都补：
- 后端 _apply_op 拒收未知类型，不进图、不转发，最终校验里说明跳过了哪一步；
- 前端流式加节点时再拦一道；sourceHandles、属性面板遇到未知类型不再崩；
- 全站加页面级 ErrorBoundary：导航栏留着，换一页自动恢复；编辑中的图在 store
里，点「重试」时它还在。
新增 scripts/check-guards.mjs（真浏览器，拦下所有非 GET 请求，不写库不花钱）：
组字回车与 keyCode 229 不发送、普通回车照常发送、未知类型不白屏、渲染真出错时
只坏这一页且换页恢复，连跑三次全绿。等待一律等事件，只有"不该发生"的断言用
窗口。后端补了未知类型不进图的用例，413 → 414 passed；tsc 通过，decode / stream
/ canvas-layout 三个检查不回归。
2026-09-25 15:41:30 +08:00
4559c96fdd
出具校验认得中文数字了："增长三成、客户两千五百家"不再能盖 formal 章
...
校验器只抽阿拉伯数字。strict 契约下"本周营收增长三成、客户两千五百家"一个数
都抽不出来，判 formal；同样的意思写成 2500 却会被 withheld。叙述层换一种写法
就绕过了"不许现编数字"这条地基，而"出错自动改一次"的复核回路会把模型往这条
路上推——被拦一次，它学会的是写汉字。review.check_numbers 复用同一套抽取，
同样的洞。
中文数字难在两头，规则按"这是不是在报一个量"来定（文件头有完整说明）：
- 多字且解析得通的一律抽：十二、两千五百、两千五（省略写法）、一万二、三点五万；
- 单字只在后面跟计数单位时抽：两家、五天。"一"加量词多半是冠词（一个问题），
不抽——放过一个值为 1 的现编，代价远小于满篇误杀；
- 成、倍、百分之、分之、一半单字也抽，按口语精度给容差（三成 = 30% ± 半成）；
- 余 / 多 / 来按区间回指（两千余 = [2000, 3000]），不跳过——跳过就是新的绕法；
- 不抽：序数、星期、月日、季度名（三季度 = Q3）、"从三个方面看"这种结构性列举、
几十 / 数百 / 上千这种虚指、成语（五花八门、千方百计、万一、十分重要）。
顺带修了阿拉伯数字的两处：
- 万 / 亿后缀的容差按书写精度算。3.5万 写到千位，应是 ±500，以前按 3.5 的一位
小数给 ±0.05，只认 35000 整——README 承诺的"按书写精度"对带后缀的数不成立。
- 补上千 / 百万 / 千万后缀："2千家"以前抽出来是 2，回指的是一个错的值。
出具校验以前没有一条直接测试（只经 check_numbers 间接覆盖）。新增 test_issuance.py
39 例：解析、该抽的、不该抽的两头都守，外加当初那条绕过（旧代码实测：抽不到、判
formal）。374 → 413 passed。
2026-09-25 15:30:32 +08:00
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
2026-09-25 15:21:20 +08:00
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
26ff8e1e06
只读数据源真的只读了：WITH … DELETE 不再从首关键字下面钻过去，连接本身也写不进去
...
守卫只看首关键字，而 with / pragma 都在只读白名单里。在只读的 SQLite 源上
实测：`WITH k AS (SELECT 1) DELETE FROM t` 被放行，5 行删得只剩 2 行；
`PRAGMA user_version = 7` 也写进去了。调用方只看到一个 ResourceClosedError——
pysqlite 只在 INSERT/UPDATE/DELETE 开头的语句前隐式开事务，WITH 开头的直接
自动提交，连接关闭时的回滚兜不住。Excel/CSV 上传生成的正是这种 SQLite 源。
两层一起收：
守卫：以查询开头的语句（SELECT / WITH / EXPLAIN）要把正文扫一遍，先抹掉注释
和引号里的内容，再找写关键字（DELETE、UPDATE、INTO、FOR UPDATE、EXPLAIN
ANALYZE 里的语句……），关键字后紧跟 ( 的是同名函数不算（MySQL 的 INSERT()、
TRUNCATE()）。PRAGMA 改成只读白名单，`= 值` 和 `(值)` 两种赋值写法都拦。
另收一小撮有副作用的函数，其中 set_config 必须拦：PG 真库实测，它能把连接层
的只读关掉，同一连接的下一个事务就能写。函数名加引号、dblink 另开连接这两种
绕法也补上了。is_write 与只读判定共用一份判定，免得审批那道门另有一套口径。
连接层：只读源连接时就只读（engine_args）。SQLite 以 mode=ro 打开（file: URI，
路径带空格、中文、# 都测过）；PostgreSQL 设会话默认事务只读；MySQL / MariaDB
设会话事务只读。Oracle 没有会话级开关，只剩守卫——README 写明请配只读账号。
真库验证（临时实例，已清理）：PostgreSQL 18 与 MySQL 8.0 上，DELETE、WITH … DELETE、
PG 的数据修改 CTE、nextval、EXPLAIN ANALYZE 绕过守卫直连执行，都被数据库以
只读事务拒绝；可写源不受影响。
测试：守卫新增 33 例（藏在查询里的写、会写的 PRAGMA、同名函数与引号标识符不误杀），
去掉修复重跑是 17 例失败；test_readonly_source.py 6 例（当初那条绕过、绕过守卫
直连写、中文路径、可写源不受波及、各库的会话参数）。297 → 334 passed。
顺带查到但没在这里修的：可写源上的写操作既不审批也不生效——is_dangerous_call
全仓库没人调用，而 run_query 从不 commit，写完就被回滚。两件事必须一起修
（先接审批再让写入生效，反过来就是一个无审批写库的窗口），放在审批统一那一步。
2026-09-25 14:44:56 +08:00
66cc96b463
汇合节点只跑一次：长短支路不再把它触发两遍，循环的 done 出口也不再被提前放行
...
多条边汇入同一个节点时，编译器对每条入边各 add_edge 一次。LangGraph 对这种
接法的语义是"任一上游跑完就触发一次"：两条支路一样长时，两次触发落在同一步
被合并，看不出问题；一长一短时，汇合节点先拿短支路的结果跑一次，长支路到了
再跑一次——模型调用、工具副作用、下游全部翻倍。循环体里更糟：每轮汇合两次，
循环节点就多推进一格，done 出口在循环跑到一半时就放行了，成果节点跑了 3 次。
README 写的"自动等待汇聚"只在支路等长时成立。
修法是给汇合节点加 defer（等图里其余待执行的任务都跑完再跑一次），而不是
屏障 add_edge([a, b], j)：分支之后的二选一汇合，没走的那条永远不会到，屏障
会一直等，而 LangGraph 没有可执行任务时会安静结束——汇合节点和下游就被无声
跳过。代价写在 _join_nodes 的注释和 README 里：它也会等图里无关、恰好在跑的支路。
汇合 = 两个以上前向上游，循环回边不算。回边识别因此从 layout.py 挪到
schema.back_edges，加了 roots 参数：执行语义要从入口起 DFS，否则循环体里的
前向边可能被误判成回边；排版照旧按节点顺序起算，行为不变（check-canvas-layout
全过）。
新增 test_fan_in.py 5 例：长短支路、循环体内汇合（修前分别跑了 2 次和 4 次）；
二选一汇合、被分支剪掉一路的汇合（守着别把修法做成屏障）；回边不算汇合。
292 → 297 passed。内置模板里 ③④ 的成果节点是二选一汇合，行为不变。
2026-09-25 14:33:56 +08:00
8905fe5e60
多 agent 节点在画布上展开协作矩阵，运行时的动效统一成一套语汇
...
多 agent 节点原本是个黑盒：卡片转三十秒圈，然后吐一段文本。"它同时派了三个
人"、"谁还在跑"、"并行到底省了多少"全都要点开右栏才知道，而右栏是线性的
时间线，看不出并发的形状。
现在它跑起来会在卡片里展开一块协作矩阵。三条设计上的选择：
- 花名册固定在原地，不按派单顺序重排——几轮下来眼睛知道谁在哪一行
- 条形长度按**这一轮里最慢的那个人**归一化。三个人并排三条长短不一的条，
墙钟为什么等于最长那条、而不是三条之和，不用解释就看懂了；页脚给出
并行一共省下多少
- 本轮没被派到的人不显示成"待命"，而是留着上一轮的成绩（压暗）——它已经
交回来了，说它待命是错的，看的人会以为它还没干活
矩阵和右栏泳道读的是同一份翻译：把 decodeRun 里那段攒泳道的逻辑抽成
reduceTeam（不可变，每次返回新对象，画布那份挂在 zustand 上需要新引用）。
两边各写一遍的话，同一次运行在右栏和画布上会给出不同的并行度——而"几个人
同时在跑、省了多少"正是这个节点唯一值得看的东西。抽完之后 check-decode
一条没红。
其余节点按同一套语汇动：边框上转一圈光弧 + 扫描线 = 正在跑，绿色扫一遍 =
刚跑完（只扫一次——常驻动画会让整张画布一直在动），短促抖动 = 刚失败，
琥珀呼吸 = 在等人。循环卡片显示"第 1/5 轮"；分支跑完点亮命中的出口、压暗
其余，实际走过的边留在画布上，那就是这次的执行路径。连线上的虚线换成顺着
路径跑的光点：虚线只让人觉得"在动"，光点能看出往哪走，速度按路径长度归一化
（长边上的光点走得慢会像卡住了）。
原来那个往外扩的声纳圈（pulse-ring）删掉了。同一个意思说两遍只会更吵，而且
声纳扩出去会和邻居卡片的边框糊在一起。
一个前提先验证过：offset-path 在 SVG 子元素上能不能对齐路径。测下来和
getPointAtLength 的位置差 0px，才敢用它。
排版要按**展开后**的高度给多 agent 节点留位置（layout.py 的 _height 按名册
人数算）。不留的话它一跑起来就盖住下面那张卡，而且运行结束后矩阵不会收起来
（那正是要回看的东西），重叠是永久的。
前庭敏感的人由 prefers-reduced-motion 兜住：光弧、扫描线、流光条、光点整体
不绘制，而不是把时长压到 0.01ms——那样它们会停在动画的最后一帧，光弧卡在
角落、光点全堆在起点，看着像渲染坏了。静态下"谁在跑"由实心圆点和"进行中"
三个字承担。
新增 scripts/check-canvas-fx.mjs：把脚本化的事件灌进 store（走的是页面上那一份
applyEvent / NodeCard / FlowEdge，只有事件来源是脚本），断言协作矩阵真的长出来、
并行度算对、条形长度和耗时成正比、分支命中的出口被点亮、关掉动效时光效确实不
绘制。真跑一张多 agent 的图要连模型、要等十几秒，而且撞不上"三个人同时还在跑"
那一瞬间——那样的检查会变成偶发失败。另外用仓库里 fixtures.json 那份真实导出
的事件验过一遍，含老运行那种只有中文消息串的 log（走正则兜底）。
顺手修掉检查脚本互相下绊子：check-canvas-fx 原来会留下一张没坐标的工作流
（节点全叠在原点），而 check-ui 打开 /studio 会落到"最近更新"的那张上，于是
点节点被挡住。现在落库前先让后端排好版。
292 passed（新增 2 条：展开的多 agent 卡片必须在排版里留出位置）。
2026-09-25 12:47:07 +08:00
7fb2976f29
代码节点的变量不再带着 print 的换行：一个变量不该有两种判定
...
运行 d47bfcb03dc747658c2d63f8755992b9 交出来的是自相矛盾的结果——
"已重试 2 次仍未成功，流程终止"，而最后输出是 {"ok": true, "result":
"1+1 = 2"}。看着像运行失败了，其实 status=succeeded。"已重试 2 次"是图里
写死的文案，跟实际跑了几轮、跟成败都无关。
真正的毛病在事件流里：judge 节点（code）的 vars 是 {"ok": "ok\n"}。
assign_to 拿的是**原始 stdout**，而 print() 一定补一个换行，于是
`print('ok')` 写进变量的是 "ok\n"。后果是同一个变量、同一个表达式被两个
控制节点判出相反结论：
loop retry vars.ok == 'fail' → False 循环正常退出（看着像成功）
branch check_outcome vars.ok == 'ok' → False 所有条件都不满足 → default → 失败
这不是个例，是代码节点的默认用法：print 是它唯一的产出通道，写完再比字符串
是标准套路，所以只要这么写就必然踩上，而且**静默**——没有一个地方会说
"这个值多了个换行"。
同一个函数里本来就为了"stdout 是不是 JSON"算过一次 strip()，只是没拿它当值
用。现在统一成一份：
- payload["text"] 和 assign_to 都用去掉尾部空白的文本。只削尾不削头：首行的
缩进是内容（逐行打印一段缩进文本时削掉就毁了），而尾部换行是 print 的产物
- payload["stdout"] 保留原始输出——审计"到底跑了什么"只能看它
- stdout 是 JSON 时仍解析成对象，既有约定不变
- {{ vars.x }} 和 {{ nodes.x.text }} 必须是同一个值，两种写法给不同的值比
原来的毛病更难查，所以一起改
顺带在 Copilot 的 NODE_REFERENCE 里写明代码节点的输出契约（尾换行已去掉；
stdout 是 JSON 就变对象，那时要用字段引用而不是比字符串），否则模型会继续
生成下一个变种。
新增 tests/test_code_output.py：五条，覆盖尾换行、多行内容不被削坏、JSON
仍解析成对象、text 与 vars 一致、纯空白输出归一成空串。修之前红四条。
验证做过变异：把改动还原，同一张图回到"走了失败分支"，而 print('ok',
end='') 仍是成功分支——换行就是原因。把用户那张图原样重跑，judge 的 vars
是 {"ok": "ok"}，check_outcome 命中 "vars.ok == 'ok'" 走成功出口。
290 passed。
2026-09-24 23:15:19 +08:00
75be5f485e
画布上的线不再叠在一起：排版按车道留走廊，走线不再交给 smoothstep
...
原来所有边都交给 React Flow 的 smoothstep，它的竖直段一律落在源和目标的
正中间。同一列的边于是全挤在同一个 x 上：一张"入口扇出三路 → 归并 → 分支
→ 出具/驳回"的图上，跨层的 a3→join 和 m2→join 的横段**完全压在同一条线
上**，长边还直接从"归并B"卡片中间穿过去。排版那边同样糙：同层按 id 字典序
竖排，所以 out_no 排在 out_yes 上面（"n" < "y"），分支的 yes/no 是反的；
层内没有任何减少交叉的排序；层间距写死 300。
后端 app/engine/layout.py 重写成分层布局：先剔回边再按最长路径分层（loop
的回边不参与分层，否则循环体会被压到循环节点左边）；层内中位数启发式上下扫
六轮取交叉最少的一版，分支/循环的出口再按声明顺序占位重排；y 先均匀堆叠再按
邻居重心迭代松弛，同列节点因此和上下游对齐，长边也走得直；最后按"穿过这条
走廊的连线在竖直方向最多重叠几条"给走廊留宽——区间图上的贪心染色，和前端
用的是同一套，走廊留窄了前端再聪明也只能把线叠起来。
前端 canvas/routing.ts 自己算走线：出边沿右边缘错开、入边沿左边缘错开（入边
按上游纵向位置排序），竖直段按区间染色分配车道——真叠在一起的才各占一条，
首尾相接的（同一个扇出点）共用一条，看起来就是一条总线；跨层的长边和循环的
回边在中间各列的纵向占用里找空档绕过去，不再压过卡片。边换成自定义组件后
React Flow 不再自动加动画类，实测确认 .edge-active 仍然生效。
顺带修掉"排完版看不见图"：整张图换过坐标后（自动排版 / Copilot 生成完 /
切图）自动重新取景。坐标变了视角没变，人盯着的是一片空白。
新增 scripts/check-canvas-layout.mjs：把夹具图交给真后端 /api/copilot/layout
排版，再直接 import('/src/canvas/routing.ts') 用页面上跑的那份代码算路径，
按几何断言没有两条线压在同一段上、没有线穿过别人的卡片、两端都接在节点边缘，
另有 1325 条随机坐标的 fuzz 防手拖之后算出 NaN 路径（NaN 的 path 什么都不
画，界面上就是"线没了"，一声不吭）。这条检查做过变异验证——把 laneX 改成
永远返回走廊中点，它立刻报 a3→join × m2→join，正是原图上那处重叠。
285 passed（新增 12 条排版不变量）。check-ui 69 项通过，唯一失败项"本地哈希
要标出没有语义能力"已 git stash 到基线复现，与本次无关。
2026-09-24 22:58:54 +08:00
4057cdc35f
步数用尽时先收个尾，别把半截过程当答案交出去
...
走到步数上限一定意味着最后那步**要求了工具**（不要工具的话循环早 break 了），
也就是说模型从来没拿到过"说结论"的那一轮——它只是被掐断在半路。交出去的
是它上一句中间过程的话，末尾补一句"步数不够，请调大"。
实测这条线是绷紧的：库里 116 个 agent 节点，87% 在 10 步内收口，11 步只有
1 个，**正好 12 步的有 11 个**。1 跳到 11 是被截断的特征，不是自然分布。
所以补上那一轮：不给工具，让它基于已经查到的收口，并说清哪些没查到、
结论因此有什么局限。用 base_model 而不是绑过工具的 model——收尾轮必须在
结构上发不出 tool_call，靠提示词请它别调是约束不住的。
两种收场发不同的 code：收上来了是 step_limit_settled（DEGRADED），
收不上来仍是 step_limit（BROKEN）。不复用同一个 code：库里那 8 条老事件
的含义确实是硬截断，改语义等于把历史运行重新解释成另一回事。
顺带修掉一个一直在白烧钱的 bug：chat.ts:440 的注释说自动重试能"调大最大
步数"，而 copilot.py 明确禁止模型写 max_steps。两边对不上，于是 step_limit
的重试是用同一个默认 12 再跑一遍，必然撞同一堵墙。现在那条禁令改成有条件
的——只有上一次死于步数不够时才准显式写大值。改完两条路各自成立：收尾
成功走 DEGRADED，闸门不开、不重试（对的，同配置再跑还是撞墙）；收尾失败
仍是 BROKEN，而这次 Copilot 真能把步数调大。
硬顶 25 → 100，画布滑块跟着放开，**节点默认仍是 12**：要更多的人调得动，
不知情的人不会突然多花十倍。
新增 tests/test_agent_steps.py，顺带补回 agent 循环的集成测试（原来那个
文件在脱敏那轮被整个删掉了）。两条反向断言是重点：正常收口的 agent 一次
调用都不该多花，以及收尾轮发不出工具调用。两者都做过变异验证——把收尾
结果丢弃、把收尾轮换成绑工具的 model，各自都能让对应的断言变红。
273 passed（去掉一个会真连 api.openai.com 的既有慢测试是 238 passed / 9.4s）。
2026-09-24 16:38:26 +08:00
69129bba9c
Add license section to README
...
Added licensing information and usage terms to README.
2026-09-23 16:22:44 +08:00
956c7b38e9
Add commercial licensing terms and conditions
...
This document outlines the terms for commercial licensing of the software, including conditions for obtaining a commercial license and contact information for inquiries.
2026-09-23 16:22:04 +08:00
eb332246f2
Add LICENSE file with PolyForm Noncommercial License
...
Added PolyForm Noncommercial License 1.0.0 to the project.
2026-09-23 16:21:36 +08:00
c8393c3c6b
移除仓库中的商业数据：删掉 21 个相关用例，其余标识符脱敏
...
这个仓库是公开的，而历史里带着一份客户 BI 仓的逐字转储：ANALYTICS（原
schema 名）下 53 张视图名、实测行数、字段结构表，外加一句写明取数方是谁
的注脚。还有一处把真人姓名和工作单位写进了检查脚本的断言里。这些都不是
化名，是能直接拿去对库的东西。
按"含敏感词的测试直接删"处理，共 21 个用例：
test_agent_tool_loop.py 整个文件（2 个，agent 工具循环的真图验收）
test_conversations.py 9 个（会话 CRUD、历史文本、上下文进 prompt）
test_datasource.py 5 个（探查失败的实情、候选 schema 提示）
test_copilot_context.py 3 个（数据源摘要的限定名）
test_review.py 1 个（干净运行无信号）
test_tool_args.py 1 个（call_tool 端到端）
辅助函数和产品源码不在"测试"之列，改为脱敏——否则删一个 _seeded 会连带
带走 8 个没被点名的用例。标识符一律换成中性名：shop→shop、
ANALYTICS→ANALYTICS、prod_shop→prod_shop、真人姓名→张三。
markdown 样本里那两条不是改标识符能解决的：行数、字段结构、业务域描述
整段都是客户的。换成同构的合成内容——领域换了，markdown 构造逐项对齐
（标题层级、有序/无序列表、三列表、带 inline code 的单元格、引用块），
渲染器的覆盖面没有变窄。check-stream 里那句"用的是真实输出"跟着改成实话。
286 → 265 passed，差值正好是删掉的 21 个。tsc 干净，decode / stream / ui
三个 check 不回归。
历史里的同一批内容另行用 git filter-repo 处理。
2026-09-20 22:52:28 +08:00
5641d0631f
循环变量不再被报成"未定义"：错的是分析器，不是模板
...
模板⑦「批量处理（循环）」是唯一一个装好就红着的内置模板——新用户点开第一眼
看到「1 个错误」，运行按钮还是灰的：
{{ vars.item }} 没有任何节点产出，是不是想写 {{ vars.items }}？
**但模板是对的。** 循环节点配的 item_var 就叫 item，control.py:142 每轮往
vars 里注入 vars.item 和 vars.item_index。错的是静态分析器：产出侧只登记了
input.*、vars.<assign_to>、nodes.<id>，从来没登记过循环注入的那两个。
kind="loop" 在 _KIND_ORDER 里一直占着位置，只是没人产出过——漏实现，
不是设计如此。
顺着修下来一共三处误报，都是同一类：
**一、循环变量没登记。** 补上 vars.<item_var> 和 vars.<item_var>_index，
只在 foreach 模式（while 不遍历列表，自然没有"当前项"）。
**二、顺序判定被回边搞乱。** 补上之后错误降成警告，但换了一句同样不对的话：
"{{ vars.item }} 由「逐条循环」产出，但那一步在这之后才跑"。循环体末尾有一条
回到循环节点的边，于是循环节点的拓扑深度被推高、反而排在自己的体后面。
改成先算出每个循环的"体"（从 body 出口走可达闭包，遇到循环节点自己就停），
体内引用不套先后判定。体**外面**引用它确实取不到值，那条留着，
并换成说得清的措辞："只在循环体内部有值"。
**三、表达式字段里的裸引用没扫。** transform 的 expression、branch 的
cases[].condition、skip_if 写的是裸 vars.x，没有 {{ }}，而扫描只认模板语法。
于是模板⑦里 `(vars.collected or '') + str(vars.one)` 一个引用都认不出来，
vars.one 被报成"产出了但没有任何地方引用"——它明明在用。
顺带把"没人用"这条收窄到**作者声明过的**变量：循环的 item_index 和入口字段的
vars.<name> 别名都是系统自动提供的，报它们等于噪音（内置变量没有 produced_by，
本来就不在这条路上）。而真正未引用的 assign_to 照报不误——⑤⑥⑧ 还各有一两条。
误报是 linter 最坏的失败模式：它会让人把整个校验一起无视掉。这条理由本来就
写在这个文件的注释里，只是自己没做到。
现在 8 个内置模板全部零错误。验证：后端 284 passed（test_variables.py 新增
8 条，含"体外引用仍然要警告"和"while 模式没有当前项"两条反向断言）；
三个前端 check 不回归。
2026-09-20 21:30:42 +08:00
00f8dd78a9
时间线上认得出并行分支了：3 路并行 · 合计 6.6s，实际 3.0s
...
图上一个节点连出多条边就是 fan-out，LangGraph 在同一个 superstep 里并发执行
——这一直是真并发。但在时间线上它们只是穿插出现的几行，"这三路是同时跑的、
因此省下了 3.6 秒"一个字都没说。上一轮给协作团队做了泳道，这条同样的信息
在 fan-out 这边还是缺的。
现在按时间跨度把同时跑的节点收进一个分组，标题写明几路、meta 写明省了多少：
⑂ 3 路并行 合计 6.6s，实际 3.0s
├ 查销售库 2.2s
├ 查库存库 3.0s
└ 查客户库 1.5s
**判据是"同一批出发"，不是"跨度重叠"。** 第一版按包含关系排除嵌套，结果漏掉了
先跑完的那一路：三路同时开始但先后结束时，长的那条在时间上确实"包含"短的。
实测 leg0 [0.05,2.21] / leg1 [0.05,3.01] / leg2 [0.05,1.51]，被漏掉的正是
最快的 leg2——而漏掉最快那路会让"省下多少"算少。改成看开始时刻是否落在同一批
（250ms 窗口），fan-out 的几路实测相差不到 1ms，子工作流那种真嵌套则是父节点
明显更早开始，自然分得开。
组内要求两两都同批，而不是链式传递：否则 A|B 重叠、B|C 重叠但 A|C 不重叠的
三个节点也会被串成一组，而它们并不是同时在跑。瞬时节点（<30ms）不参与——
它们谁跟谁都"重叠"，是噪音不是信息。
**误报比漏报更糟**：它会让人以为省了时间。所以断言里专门守了反向——db、human、
loop_approve 三份顺序执行的样本一个都不能被判成并行。
fixtures 里新增的 fanout 是真跑出来的，不是手写的：三路分别 sleep 1.8 / 2.6 /
1.1 秒，事件原样收进来，所以 6.6s / 3.0s 这两个数和后端量到的是同一份。
验证：check-decode 新增 6 条（含三份顺序样本的反向断言）；check-stream 新增
10 条，宽窄两栏都验了不溢出；后端 276 passed 不受影响；tsc 干净。
2026-09-20 21:09:30 +08:00
c3f7d6ffcd
协作团队真的能并行了，界面上也看得出来
...
先说一个和名字不符的事实：这个节点叫「多 Agent 协作」，但在此之前它是一条
严格的串行流水线。调度协议写死成 `next: string`——"一次只能派一个"被编进了
协议本身，模型再想并行也表达不出来。三个专家各花 10 秒，总是 30 秒。
（真并行一直在图级 fan-out：实测 3 个各 sleep 2 秒的节点连在同一个上游，
全部 +0.00s 开始、+2.37s 结束，墙钟 2.6 秒。只是协作团队走不到那条路。）
**协议改成 assignments 数组**，一轮可以派多个互不依赖的专家，asyncio.gather
并发执行，总耗时按最慢的那个算。max_parallel 可配，设成 1 即退回严格串行。
**并发只在任务真的互不依赖时才成立**，这件事的成本必须说清楚：同一轮发出去的
专家拿到的是**同一份进展快照**，谁也看不见谁这一轮干了什么。派错了不报错，
只会让两个人基于一样的旧信息重复劳动，而这在结果里很难看出来。所以判断责任
压在调度者身上，提示词里把反例写出来：
可以同时派：「查 A 的资料」和「查 B 的资料」
不能同时派：「查资料」和「根据资料写报告」
不能同时派：「写初稿」和「校对初稿」
并明确告诉它拿不准就分两轮——代价只是慢一点。
**每个人单独计时**，而不是事后拿整轮墙钟去摊。界面要显示"并行省下多少"，
那个数必须是量出来的：按 N×墙钟 推算等于假设每个人都跑满了最慢那条，
而实际上快的那个可能只花了三分之一。测试里专门有个快慢不对称的用例守这条。
**调度日志改成结构化字段**（agents / done / reason / parallel）。以前只有一句
中文消息串，解码层得拿正则去拆「调度 → X（理由）」——后端文案一改就散架，
而这次正是改了文案。老运行的事件没有这些字段，正则那条路留着兜底。
**界面加泳道。** 每个成员一行、每轮一格，条形宽度按耗时归一化，所以一眼看得出
谁和谁是同时干的、谁是这一轮的瓶颈。顶上一行汇总"3 名成员 · 3 轮 · 2 轮并行，
省下 11.8s"；点任意一格展开那个人这一轮的任务和回复。全程串行时不装作有并行，
而是说"本次任务互相依赖，逐轮进行"。
泳道排在子步骤**前面**：先给一眼看清的形状，再往下是每一步的内容。反过来的话，
得把十几行步骤读完才知道这个团队是怎么分工的。窄栏（画布右栏 360px）下隐去
"N 人同时"的文字——并行与否看条形本来就一目了然，而缩写成"并2"没人看得懂。
验证：后端 276 passed（新增 test_supervisor.py 7 条，核心那条用**墙钟**判定
并发而不是看事件顺序——顺序只能说明"发出去了"，说明不了"同时跑"）；
check-stream 新增 10 条泳道断言，含"同一轮里慢的那个条更长"和两种栏宽不溢出；
tsc 干净，三个 check 不回归。
2026-09-20 20:57:03 +08:00
4d237c3b08
重写 README：加入实机截图与架构图，改为陈述性技术文档
...
原 README 停留在 9 月 14 日，且没有任何图示。这一版补齐了此后落地的能力，
并把语气从口语转成技术文档该有的陈述式。
**图示。** 4 张实机截图 + 3 张 mermaid 图：
- 运行中的画布（主图）：已完成节点标绿、执行中节点高亮、右栏实时时间线，
一张图说清"运行时逐节点观察执行过程"这句话
- 人工审批分支、出具链路、多 Agent 协作三张流程图，按节点包围盒裁剪，
不带侧栏——README 里看流程结构不需要连带半屏 UI
- 三层编排关系、出具链路、系统架构三张 mermaid（GitHub 原生渲染，
无需图片文件），已逐块用 mermaid.parse 验证可解析
截图由一个空数据目录启动的临时实例产出（AGENTLAB_DATA_DIR 指到 /tmp），
只含内置模板和 Mock provider，不含任何真实数据——README 里的图不该把
谁的生产库名和用户邮箱印出去。这一点在文末也写明了。
**补上此后落地的能力：** 对话式取数与会话持久化、URL 寻址、断点续跑、
产出复核（规则扫描 + 不得新增数字的机械校验）、Excel/CSV 转可查的表、
PowerPoint 解析、倒排索引与模型重排、向量模型接本地端点。
**检索那段给了实测表格**而不只是一句"混合更好"：纯向量 81% 低于纯关键词 88%、
混合加 Qwen3 到 94%、再加重排 100%，并注明样本只有 16 题、单题即 6 个百分点，
方向可信而精度不可过度解读。
**语气。** 去掉"看着它跑""拍板""直接玩""照实说""纯属白花钱"这类说法，
改成陈述句。但保留原有的如实披露：Seatbelt 限不住内存、microVM 首次拉镜像
54.5 秒、以及 UDP/53 堵不上导致 DNS 隧道外泄通道始终开放——后者单独用引用块
提到显要位置。写清楚缺口是专业的一部分，不是减分项。
文中引用的数字逐条核过：271 个测试、15 个内置工具、16 种节点、8 个模板、
四个可选依赖 extra 的名字。图片路径和目录锚点全部可解析。
2026-09-20 18:43:33 +08:00
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
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
542bcb65bb
一次对话有自己的地址了：/chat/<chatID>，运行、画布、各页标签同理
...
在此之前 react-router 只管到页面一级，「页面内部在看哪个」全在 store 和
localStorage 里，全站一处 useParams / useSearchParams / useNavigate 都没有。
后果：
- 一次对话没有地址。想把「这个结论是怎么查出来的」发给同事，只能发截图。
- 刷新回到上次那个对话靠 localStorage，换台机器、换个浏览器就丢。
- 浏览器前进/后退在页面内部彻底失效——切了五个对话，后退一下直接离开问数据页。
- /settings 永远落在「模型接入」，指不到数据源那一屏。
/chat/:conversationId /studio/:workflowId /runs/:runId
/knowledge/:tab /tools/:tab /settings/:tab
每页写两条显式路由（带 id / 不带 id）而不是可选参数 `:id?`：「没带 id」是真要
单独处理的一种情况（落到上次那个、或列表第一个），藏在一个问号里下次就没人
记得它存在了。
**URL 驱动 store，不是反过来。** 两边都能写就一定会打架——点一下列表，store
改了、地址栏没动，刷新又跳回旧的。所以 useConversations.currentId 降级成 URL
的派生缓存，唯一写入口是 ChatPage 的那个同步 effect；列表里的切换、新建、删除
一律改成导航。conversations.load() 不再自作主张决定「当前看哪个」，
remove() 改成返回「接下来该去哪」交给调用方。
localStorage 留着，但它现在只回答另一个问题：**打开不带 id 的 /chat 该去哪**。
**指向不存在的东西**要优雅：等列表加载完再判（在那之前"找不到"是假的，照着它
跳会让每次深链接进入都先闪一下错误提示），落到一个真实的，并说明为什么换了
地方。RunsPage 特别一点——列表只取前 100 条，而一条老运行的链接必须也能打开，
所以详情按 id 直接取，不在列表里找。
**画布多两道闸。** 选择器里本来就有"未保存改动"的确认，但那道闸在它的 onClick
里，而前进/后退会绕过选择器直接换图——改了一半的画布就这么没了。URL→画布那个
effect 里补一道，取消就把地址退回去。
过程中实测抓到三个问题，都修了：
- 同一个坏地址弹三次"那张工作流不在了"：effect 在请求回来之前又跑了两遍，
加了在途去重（chat 那边同样的毛病弹两次）。
- 「在画布里打开」现在直接把人送去 /studio，而那是一张还没存、没有 id 的草稿图。
不带 id 就落到第一张图的逻辑会拿第一张把它盖掉，还会先弹一句莫名其妙的
"有未保存的改动"——加了 nodeCount 判断让开。这个坑其实原来就在，只是以前
要手动点导航才踩得到。
- 删掉当前打开的那张图之后地址还指着它，刷新会撞上"不在了"。
顺带：三个 tab 页共用一个 useTabRoute（放在 Tabs 旁边，tab 和它的地址是同一件
事，拆两处迟早各改各的），认不出的 tab 名回落并把地址一起纠正过来。
「在画布里打开」不再是 toast 让用户自己去点导航，直接送过去。
验证：tsc 干净；后端 249 passed（没碰后端，跑一遍确认没带坏）；
check-decode / check-stream 不回归；check-ui 新增「URL 指得到」一节 19 条，
真浏览器里验了深链接、切换改地址、刷新、后退、坏地址、tab 直达、
草稿图不被盖掉、越过列表上限的老运行。
2026-09-20 14:09:40 +08:00
c980da65d0
失败的运行能从断点接着跑了，前面跑过的节点不重来
...
库里 28 条 failed 的构成说明了为什么值得单独开这条路：
模型 id 写错（404） 7
循环条件语法错 3
401 3
工具参数名不对 3
缺必填输入 2
大半是**配置错了**，改一下就能跑。而"改一下再跑"原来意味着整张图从头来
一遍——前面花两分钟查完的表结构、跑完的 SQL 全部重跑，尽管那些结果一直
躺在 checkpoint 里。checkpointer 本来就一直开着（thread_id = run_id），
挡住这条路的只是 resume 里的一行状态判定：它只认 interrupted，failed 进不去。
**带着改过的图续。** 不让改配置的话这功能基本没用：上面那几类续下去会
立刻再撞同一个错。所以 /runs/{id}/continue 接受一张改过的图，画布上点
「接着跑」带的就是当前编辑中的那张——用户正是改完它才点的。
**但只准改配置。** checkpoint 是按节点名存的（编译时 add_node(node.id)），
而节点配置是运行时从 spec 现读的（NodeContext.cfg）。所以只改配置对得上，
增删节点或改连线就对不上——续下去会拿着错位的通道状态跑出一份似是而非的
结果，比直接报错糟得多。加了 schema.topology_of() 做这道判据：节点 id +
类型 + 边，不含任何配置；对不上就 409，让用户重新发起。
这正是 resume 那边踩过的坑的同一类：不看有没有 checkpoint 就发 Command，
LangGraph 拿空 state 从 START 重跑，最后还落成 succeeded。所以这里也先问
一次 aget_state，没有待跑节点就拒绝，而不是硬发一个 None 下去。
时间线上要说清楚是接着跑、保了几步（"从「lp」接着跑，前面 2 个节点的结果
保留"）——否则用户看到时间线又动起来，分不清这次是续的还是整张图又跑了一遍。
验证：后端 249 passed（新增 test_continue_run.py 7 条，核心那条断言的是
node.started 事件——前面的节点确实没有再出现）。端到端真跑了一遍：
第一遍 start → prep → lp 挂在 lp，改好条件后第二遍只跑 lp → out，
成果里带着 prep 那步的结果；改了结构的图被 409 拒绝；没有失败的运行时
画布上不显示这个按钮。
顺带：_drive 里 resumed 的判定漏了 payload is None 这种（从 checkpoint
直接往下走），run.started 事件会说成不是续跑。
2026-09-20 11:54:16 +08:00
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
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
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
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
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
a027261701
Copilot 会自己记该记的了；顺带让写记忆这件事看得见
...
以前只有用户明说「记住」才会写：17 轮有图的对话里只有 4 轮带记忆节点，全在
那个用户主动谈记忆的会话里。于是他说过一次「我叫张三」，换个话题再问就
谁也不知道了。
现在 answer 路径多一步判断：这句话里有没有值得长期记住的东西，有就在主链路
前面加一个 memory(write) 节点。边界比指令本身要紧，所以写死了四类不该记的：
这一轮的问题本身、查出来的数（会过期且能重查）、一次性指令、以及**用户没说过
而你推测出来的**。另外两条是从召回的实际情况倒推的——content 要脱离上下文也
成立（召回时没有这轮对话，「他说他叫张三」读起来不知道「他」是谁），以及
拿不准就不记：记错了污染以后每一次对话，漏记一条用户再说一遍就是了。
**动手前先修了一个前提**：写记忆在界面上是隐形的。memory 节点发的是 info 级
日志，而解码层明确丢弃所有 info（decode.ts），也就是说自动记忆 = 系统背着
用户往一个跨会话、长期有效的地方存关于他的信息，而他看不见。
新增 memory.end 事件，解码层按动作分开渲染：写入把**记了什么**原样显示
（只报「写入 1 条」等于没说，用户没法判断它记的是不是他想让它记的）、召回说
「想起 N 条」、清空标成警告。
真模型验过（deepseek-v4-pro）：
「我平时叫小蒋，以后报表金额用万元」
→ content='用户平时叫小蒋，他要求以后报表里的金额统一用万元作单位'
scope 未写、跑完落库、事件里带着内容
→ 换个说法召回得到：「该怎么称呼我」「金额用什么单位」都命中
三条对照确认不滥记：
shop 里有几家店 → 没记
重来 → 走 reply，连图都没建
把上一轮的结果按月份排一下 → 没记
2026-09-19 22:41:27 +08:00
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
2a1040bbfc
重排给足输出预算；失败提示分清是哪种失败
...
拿真 provider（deepseek-v4-pro，千帆网关）跑了一遍评测集，重排确实有用：
hit@1 hit@5
初筛 88% 100%
重排后 100% 100%
变动的两题都是语义类的，正好是本地哈希向量的短板——BM25 把「权限」的字面
命中排给了「数据导出」（那篇里有「export 权限」），模型读懂了问的是「谁有权
改」。字面类原本就 100%，没有被重排搞坏。
但 16 次里有 2 次退回了初筛顺序。查下来模型回的是**空字符串**，而失败那次的
out_tokens 正好等于 max_tokens——重排的输出只有一行几十字的 JSON，但模型为了
读完 20 条候选要花 800~1600 个输出 token，顶到上限后正文什么都不剩。llm.py
里对同一个现象早有记录：「思考型模型把额度全花在推理上了，正文是空的」。
所以重排改成有自己的预算（至少 4096），不跟节点上那个走。补跑 16/16 全部成功。
顺带纠正一处判断：thinking=off 救不了这个 provider。实测关思考那组照样在
out_tokens=2048 时空手——factory.py 只在 anthropic 分支里读 thinking 字段，
openai_compatible 整条路径不碰它。仍然传 off，因为对 Anthropic 有效、而且打分
任务本来不需要思考模式，但它不是这次的解药，注释里写明了。
失败提示原来四种坏法统一报「解析不出来」，会把人引去查 JSON 格式，而该调的是
token。现在分开说：空回复 → 「把最大输出 token 调大」；找不到 scores → 带上
原文前 80 字；个数不符 → 说明给了几个、候选几个；混了非数字 → 指出是哪个值。
测试里有一条专门断言空回复的提示中不出现「解析」二字。
2026-09-19 11:09:04 +08:00
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