From c8cd56c108304e9dce20a67b150f00093cf9f74f Mon Sep 17 00:00:00 2001 From: ThearchyHelios Date: Fri, 16 Oct 2026 22:33:59 +0800 Subject: [PATCH] =?UTF-8?q?README=EF=BC=9A=E7=AC=AC=204=20=E6=B3=A2?= =?UTF-8?q?=E7=9A=84=E5=8D=87=E7=BA=A7=E8=AF=B4=E6=98=8E=EF=BC=88=E5=AF=BC?= =?UTF-8?q?=E8=88=AA=E3=80=8C=E8=AF=84=E6=B5=8B=E3=80=8D=E3=80=81=E5=8F=A3?= =?UTF-8?q?=E5=BE=84=E5=8F=AC=E5=9B=9E=E3=80=81=E4=BE=9D=E6=8D=AE=E6=9C=89?= =?UTF-8?q?=E5=8F=98=E3=80=81=E8=A2=AB=E9=A9=B3=E5=9B=9E=E7=9A=84=E9=82=A3?= =?UTF-8?q?=E4=B8=80=E6=AD=A5=E3=80=81=E5=BB=BA=E5=9B=BE=E7=94=A8=E9=87=8F?= =?UTF-8?q?=E3=80=81=E4=B8=A4=E4=B8=AA=E6=96=B0=E9=80=9A=E7=9F=A5=E4=BA=8B?= =?UTF-8?q?=E4=BB=B6=E3=80=81=E5=90=8E=E5=8F=B0=E4=BB=BB=E5=8A=A1=E6=9D=A1?= =?UTF-8?q?=E4=B8=8E=E5=AE=9A=E6=97=B6=E7=BB=B4=E6=8A=A4=EF=BC=89=EF=BC=9B?= =?UTF-8?q?=E6=A0=B8=E5=BF=83=E8=83=BD=E5=8A=9B=E5=8A=A0=E3=80=8C=E5=9B=9E?= =?UTF-8?q?=E5=BD=92=E8=AF=84=E6=B5=8B=E3=80=8D=E3=80=8C=E5=8F=A3=E5=BE=84?= =?UTF-8?q?=E8=B4=A6=E6=9C=AC=E3=80=8D=E4=B8=A4=E8=A1=8C=EF=BC=9B=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=E3=80=8C=E5=9B=9E=E5=BD=92=E8=AF=84=E6=B5=8B=E4=B8=8E?= =?UTF-8?q?=E5=8F=A3=E5=BE=84=E8=B4=A6=E6=9C=AC=E3=80=8D=E4=B8=80=E8=8A=82?= =?UTF-8?q?=E5=92=8C=E6=95=B0=E6=8D=AE=E7=9B=AE=E5=BD=95=E4=B8=8B=E3=80=8C?= =?UTF-8?q?=E7=BB=93=E6=9E=84=E5=8F=98=E5=8C=96=E3=80=81=E5=8F=96=E5=80=BC?= =?UTF-8?q?=E5=8F=98=E5=8C=96=E4=B8=8E=E5=AE=9A=E6=97=B6=E7=BB=B4=E6=8A=A4?= =?UTF-8?q?=E3=80=8D=E4=B8=80=E8=8A=82=EF=BC=9B=E5=8D=95=E8=BF=9B=E7=A8=8B?= =?UTF-8?q?=E5=89=8D=E6=8F=90=E8=A1=A5=E4=B8=8A=E5=90=8E=E5=8F=B0=E4=BB=BB?= =?UTF-8?q?=E5=8A=A1=E4=B8=8E=E9=94=81=EF=BC=9B=E6=A3=80=E6=9F=A5=E6=B8=85?= =?UTF-8?q?=E5=8D=95=2043=20=E9=A1=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 74 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index cdb551fe..3bcf3543 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ ## 目录 - [快速开始](#快速开始) · [生产部署](#生产部署) · [核心能力](#核心能力) · [受限动态编排](#受限动态编排模板定骨架agent-填关节) -- [可点击证据](#可点击证据报告里的每个数都点得开出处) · [应用](#应用已发布版本的使用面) · [身份与权限](#身份与权限) · [能力登记与端点](#能力登记与端点) +- [可点击证据](#可点击证据报告里的每个数都点得开出处) · [评测与口径账本](#回归评测与口径账本) · [应用](#应用已发布版本的使用面) · [身份与权限](#身份与权限) · [能力登记与端点](#能力登记与端点) - [数据目录](#数据目录让助手和-agent-看懂业务数据) · [工作流形态](#工作流形态) · [节点类型](#节点类型) · [架构](#架构) - [关键设计决策](#关键设计决策) · [运行环境](#运行环境) · [常见问题](#常见问题) · [开发与验证](#开发与验证) @@ -64,7 +64,8 @@ Mock 不会写引用标记：探索运行里报告撰写节点照样跑完，但 http://127.0.0.1:8000 。前端产物不存在或比源码旧时才重新构建，`--build` / `--no-build` 强制构建或跳过。 `--port`（或 `AGENTLAB_PORT`）改端口；`--host` 监听所有网卡，默认同样**不开登录**，多人使用请开登录 （[身份与权限](#身份与权限)）。 -数据目录默认为仓库下的 `data/`，`AGENTLAB_DATA_DIR` 可改。只能单进程运行：运行管理器在进程内、数据库是 SQLite。 +数据目录默认为仓库下的 `data/`，`AGENTLAB_DATA_DIR` 可改。只能单进程运行：运行管理器在进程内、数据库是 SQLite；后台任务 +（探查、起草、剖析、评测、影子起草、口径比对与召回）的排队、限流和按需探查的锁也都在进程内，多进程部署要先换成库里的锁。 上传表格的版本存储同样只支持单进程运行（不要给 uvicorn 加 `--workers`）：启动时会锁住数据目录，同一个数据目录 起了第二个进程时，后起的那个不做任何清理，上传、启用版本等写操作一律返回 503。 按期累积的数据源每个历史版本是一份完整副本，磁盘占用随期数和被引用的版本数增长。除当前版本和被运行引用的 @@ -141,6 +142,23 @@ http://127.0.0.1:8000 。前端产物不存在或比源码旧时才重新构建 7 天、1 天各提醒一次。关登录时这两项都不发。 - 分享链接（只读、不用登录的视图页）缺省关，见[分享链接](#分享链接)。 +**从旧版本升级（2026-10 下一轮第 4 波）**： + +- 导航多了「评测」（搭建者以上可见，⌥0，排在「设置」前面），见[回归评测与口径账本](#回归评测与口径账本)。 +- 受管口径发布新版本后，系统在后台反查用过旧版的答案，按参数分组在同一份数据上重算两版之差（来源「口径召回」的探索运行， + 差值在召回卡里算）。只有数真变了才给答案的主人开「召回」待办、推 `ledger.recall`；没变的在原答案上记「已按 vN 核对， + 不影响」。每次发布最多重算 `ledger.recall_limit` 组（缺省 50，0 表示只列不算），超出的在版本历史里「接着算」。发布后自动 + 那一批和启动时接着做跟着 `AGENTLAB_SCHEDULER` 开关。 +- 审阅改了数据目录里影响数字的那几项（有效记录条件、去重、业务日期、关联、业务主键、度量类型），或者表结构删了表、删了列、 + 改了列类型时，用过它的答案标「依据有变」；按新目录新出现错误级问题的才开待办。 +- 被驳回的那一步，`node.failed` 事件多带 `reason: "rejected"`（和 `run.cancelled` 同一个字段），画布、航迹、时间线、问数据 + 过程都画「被驳回」，不再画成失败。读事件的外部系统按 `reason` 区分；老运行不变。 +- 问数据每一轮的建图用量改成读完模型的流再记：以前流末尾才报的输出 token 没记上，这一轮的花费会比以前多一些，多的是原来漏掉的。 +- 可订阅的通知事件多了「数据源有变化要处理」（全局渠道）和「口径升版，答案的数变了」（全局渠道、答案主人的个人渠道）， + 消息里都不放数字。 +- 数据目录页起草、剖析的进度挪到一条后台任务条（探查、起草、剖析按服务端的排队顺序列），页头只留入口。数据源卡片上可以设 + 「定时维护」。链到某个数据源卡片的地址统一是 `/data/databases#source-`。 + --- ## 核心能力 @@ -158,7 +176,7 @@ http://127.0.0.1:8000 。前端产物不存在或比源码旧时才重新构建 | **断点续跑** | 失败的运行可从失败节点继续，已完成的节点不重复执行；探索运行允许修改节点配置（拓扑必须一致），正式运行固定在发布的版本上、不能改配置后继续；继续运行不改发起人 | | **知识库** | 向量 + BM25 混合检索、倒排索引、可选模型重排；PDF / Word / PowerPoint / HTML / Markdown 解析；向量模型可接本地端点 | | **表格入库** | Excel / CSV 上传后转为可用 SQL 查询的表，自动生成 `db_query__` 工具——数字由 SQL 计算得出，而非模型读取；复杂报表按取数配方导入（CSV 同样可以），每月一份的明细能按期累积成一张表，夹在明细中间的小计核对后不进数据 | -| **数据目录** | 给数据源的每张表记下粒度、业务主键、业务日期、有效记录条件，每个字段的含义、单位、度量类型和码值，以及表与表的关联；由外键、命名推断、数据剖析和模型起草，逐项确认后生效；表详情里可以和助手对话完善一张表，审阅队列按影响排好先审哪些，目录能导出、导入到别的实例；助手建图、agent 查结构、SQL 检查都读它 | +| **数据目录** | 给数据源的每张表记下粒度、业务主键、业务日期、有效记录条件，每个字段的含义、单位、度量类型和码值，以及表与表的关联；由外键、命名推断、数据剖析和模型起草，逐项确认后生效；表详情里可以和助手对话完善一张表，审阅队列按影响排好先审哪些，目录能导出、导入到别的实例；助手建图、agent 查结构、SQL 检查都读它；结构变化、取值变化记进变化记录逐条处理，数据源可设定时维护（[详见](#结构变化取值变化与定时维护)） | | **SQL 检查** | 按数据目录检查一对多关联后重复计算、存量跨时间相加、比率被相加等七类问题；助手自查时交回修正，受管模板发布时挡住，运行时标在查询结果上、契约指标降档 | | **跨库合并** | 合并查询节点：各库先聚合到同一个键，再在库外按键合并；截断的输入拒收，证据一路追到两边的原始查询 | | **长期记忆** | 跨运行的记忆读写与自动去重；Copilot 建图时主动记录应当记住的事实 | @@ -167,6 +185,8 @@ http://127.0.0.1:8000 。前端产物不存在或比源码旧时才重新构建 | **结构化成果** | JSON Schema 校验，不合格时将错误回传模型自动返工 | | **产出复核** | 运行结束后规则扫描事件流，发现异常才调用模型复核；复核可重组答案但**不得引入原答案中不存在的数字** | | **追踪与成本** | 全量事件落库可回放；逐节点耗时、token 用量、按目录价折算的成本；问数据每一轮的花费含助手建图、挑表和复核 | +| **回归评测** | 题集与期望答案（写 SQL、选口径、从问数据运行认定，数值不许人填）；后台跑一轮和用户拿到的同一套问数据（建图、运行、复核），逐题评分，准确率带区间，按角色记用量与成本；对比、A/B、「目录贡献」对照；定时评测，退步推通知（[详见](#回归评测与口径账本)） | +| **口径账本** | 问数据答案里的数逐个标口径（等价已证明 / 助手选用 / 相关口径 / 这次的推理）；等价于受管口径的自动按口径正式出具，相关口径一键对账、三个数都点得开；反复出现的问题进认证队列、固化成口径草稿；口径升版后召回重算，数变了才通知（[详见](#回归评测与口径账本)） | | **三档出具** | 口径卡（受控指标集）+ 出具契约：叙述中每个数字回指指标集，或由报告撰写节点按引用逐段核对，formal / degraded / withheld 三档判定 | | **可点击证据** | 报告撰写节点只写引用标记，数字和表格由系统照快照填值；数字、表名字段名、知识库原话都点得开，一路指到查询结果里的那一格；结论句可要求挂依据或交给另一个模型裁判；证据清单可导出，报告导出为自包含 HTML（数字点得开口径与出处），另有封存哈希核对件「可验证报告」 | | **发布前检查** | 受管级别加证据门禁 G1–G5；问题给出一键修复 / 选项 / 交给 Copilot 三类修法，一律先预览、不许降低要求；老工作流一键升级为可追溯结构 | @@ -325,6 +345,37 @@ flowchart LR --- +## 回归评测与口径账本 + +**评测**（导航「评测」，搭建者以上）是换模型、改提示词、改目录之后的一把尺： + +- **题集**：每道题是一个问题加期望答案。期望可以是一条 SQL（选格或列，每次评测重算，不冻结数值；查到遮罩列的拒收）、一份 + 已发布口径的指标、或从某次问数据运行里认定的查询；也可以期望「没有数据」或期望反问。数值不许人填，文字要点由裁判判、单列， + 不计入准确率。口径升版后，用到它的题顶部提示，每道题三选一：改为固定新版本、新旧两版各算一份期望、或旧题归档另建新题，处置之前评测时跳过。题集能导入导出。 +- **发起**：选变体（助手模型、写作模型、裁判开关、目录用当前 / 快照 / 只用已核实的 / 关、重复几次），先给预估花费；「目录 + 贡献」预设一次跑「当前 vs 关」。评测在后台跑，每题怎么走和用户在问数据里拿到的一样，停在审批的不代批、照实记；并发、每题 + 时限、单次和每日金额都有上限（「设置 → 偏好设置 → 评测」），评测的花费单独一本账。能停、能只重试没做完的；服务重启标中断， + 不自己续跑。 +- **结果**：总览（准确率与可追溯准确率带 Wilson 区间、路径和出具档位的分布、按角色的用量与成本、耗时分位），逐题表（结论、 + 期望和答案里的数、SQL 差在哪、看了几次表、花费，点开去运行），和上一次或基线比（逐题转移与归因），A/B 配对表（精确 McNemar， + 只展示不卡门）。评测运行不进使用统计。 +- **定时**：定时任务的目标可以选题集；有一道题从通过变成不通过就推「定时评测有退步」，消息只有题集名、通过数、退步题数和链接。 + +**口径账本**把问数据的答案和已发布的口径对上： + +- **逐个数标口径**：探索运行封存后在后台和已发布的口径比对。SQL 被证明等价的标「等价已证明」，助手选用口径拼出来的标「助手 + 选用」，用到同一张表却不等价的标「相关口径」并写差在哪，都不沾边的写「这次的推理」。证据面板的出处链最上面多一步「口径」， + 问数据每一轮底下有一行摘要；比对还没出结果时写「正在比对口径」并按退避重取。 +- **出具与对账**：整题等价于一份受管口径时自动按口径发起一次正式运行（可关，每天有上限）；助手选用的给一键出具。相关口径点 + 「看差多少」发起一次只读的对账运行，这次的数、口径的数和差值各自点得开出处；对账的说明有没有用可以反馈。使用者能对账；按口径 + 正式出具只限他有权使用的应用固定着的口径版本。 +- **沉淀**：同一类问题反复出现（同一形状的查询 ≥3 次、来自 ≥2 段对话，或问题聚成一类，或答案被反复导出、做成应用）的进工作流 + 选择里的「可沉淀的问题」，可以固化成口径草稿（引用的查询变成取数节点，跨轮变化的字面量自动成为参数），审过再发布。 +- **召回**：受管口径发布新版本后，反查用过旧版的问数回答、正式运行、固定它的应用和导出，按参数分组在同一份数据上重算两版之差， + 数变了才开「召回」待办（旧值、新值、差值和原答案当时的值都点得开，可以按新版重新出具），没变的只记账。发布弹窗先预告规模。 +- **统计**：等价命中、对账、问题重复度、召回四项（E1–E4）由 `GET /api/ledger/stats` 现算，评测页的「口径命中与重复度」页签 + 画趋势。 + ## 应用：已发布版本的使用面 工作流发布出去之后，看数的人、办事的人在「应用」里用它。应用不是新引擎，也不是嵌进来的低代码平台：每个数都来自 @@ -558,6 +609,20 @@ curl -H "Authorization: Bearer agl_…" -H "Idempotency-Key: order-20261016-001" 加进范围并留痕。「表已不在」只在真删除时说，范围外、读不到结构、索引里从来没有，各自分开说。剖析得到的行数和日期范围也 交给助手和 agent，附一句「只供写查询参考，不能作为回答里的数」，遮罩按当时的设置重滤。 +### 结构变化、取值变化与定时维护 + +探查时每张表记一个结构版本，和上一次比出结构变化（加删列、改类型、改可空、改注释、键和外键的增删；疑似改名只说「可能」）； +剖析的取值观察（行数、码值分布、最新业务日期、最近 35 天每天的行数）和同一口径的历史比，比出取值变化（新码值、比例剧变、 +断档、缺天、量跌、行数大起大落），大表照实写口径（整表、窗口、块采样、前 N 行），口径不同不比。两种变化记在同一份变化记录里： + +- **在哪看**：数据目录的「变化」视图按要处理 / 提醒 / 说明分组，数据源卡片上的角标是要处理的条数，表详情里有「结构与取值 + 变化」一节。每条写影响面：说到这些列的目录项和它们的状态、写死了这一列的已发布模板、哪条 SQL 现在会报列不存在。 +- **怎么处理**：清理目录项、加入码值、重新起草、重新剖析、知道了、误报（必须写理由），动作都落到目录已有的写入上，记下目录 + 版本或建的任务。机器自己只做一件事：数据证明码值表不再列全时撤销「已列全」。 +- **定时维护**：数据源卡片上的「定时维护」，选步骤（探查结构、剖析需要的表、取值观察）和低峰时段，存成一条目标为这个数据源 + 的定时任务，缺省没有。和起草、剖析在同一个数据源上排队，没执行的步骤照实记原因。 +- **通知**：「数据源有变化要处理」只给源名、条数和链接，不放表名、列名和取值。 + ### 助手按需查看 以前每一轮开始前，服务端按库的大小把表结构塞进助手的 system：说一句「你好」也要先挑表，再带着上万字的表结构去 @@ -979,14 +1044,14 @@ loop 节点给它定轮数上限的环：用 loop 节点包住它。确实需要 ## 开发与验证 ```bash -# 后端：约 12800 个测试，-n auto 并行约 1 分钟 +# 后端：约 14300 个测试，-n auto 并行约 1–2 分钟 cd backend && env -u ANTHROPIC_API_KEY -u ANTHROPIC_BASE_URL -u ANTHROPIC_AUTH_TOKEN -u OPENAI_API_KEY \ python -m pytest -n auto # 前端类型检查 cd frontend && npx tsc -b -# 前端检查：33 项，默认 8 道并行。连 5273 / 8000，先起 ./scripts/dev.sh +# 前端检查：43 项，默认 8 道并行。连 5273 / 8000，先起 ./scripts/dev.sh node scripts/check-all.mjs # 另起 2 套只给检查用的「后端 + vite」，各用一份数据拷贝，约 6.5 分钟；边改代码边跑也不被打断 CHECK_DATA_SRC=<数据目录> node scripts/check-all.mjs --stacks 2 --lanes 12 @@ -997,16 +1062,17 @@ node scripts/check-all.mjs evidence publish pytest 前面的 `env -u` 不能省：没配 Key 的 provider 会退回环境变量里的密钥，启动时的 seed 也会拿它种一个 provider——环境里留着真密钥，测试就可能真的去调接口。 -`check-all` 的 38 项按 `scripts/check-all.mjs` 里 `ORDER` 的顺序排： +`check-all` 的 43 项按 `scripts/check-all.mjs` 里 `ORDER` 的顺序排： | 类别 | 检查 | |---|---| | 不开浏览器 | `tokens`（令牌静态扫描）`copy`（界面文案）`trace`（运行态内核的纯函数）`decode`（事件翻译层） | | 走线、组件与护栏 | `canvas-layout` `ui-kit` `guards` | | 外壳、回答流与运行态 | `shell` `stream` `evidence`（可点击证据）`run-states`（节点卡）`canvas-fx`（画布表层） | -| 各页面 | `studio` `publish`（发布前检查与自动修复）`chat` `runs` `manage` `versions`（上传表格的版本）`catalog`（数据目录）`catalog-loop`（表助手、审阅队列、导出导入）`catalog-profile`（数据剖析的逐表任务）`ui`（端到端，连真数据） | +| 各页面 | `studio` `publish`（发布前检查与自动修复）`chat` `runs` `manage` `versions`（上传表格的版本）`catalog`（数据目录）`catalog-loop`（表助手、审阅队列、导出导入）`catalog-profile`（数据剖析的逐表任务）`catalog-changes`（变化、表详情的变化一节、定时维护、后台任务条）`ui`（端到端，连真数据） | | 复核套件与导出 | `schedules`（定时任务）`compare`（运行对比）`verify`（双盲复算、反方审稿）`inquiry`（审批质询）`challenge`（反方审稿）`bundle`（可验证报告）`whatif`（数字推演）`report-export`（报告导出） | -| 应用平台 | `apps`（应用页、印章、点数字看出处、入口校验、实例页）`inbox`（会签进度、超时、动作确认的哈希卡、核实）`app-editor`（应用编辑、派生、检查、发布时选处置、助手）`capabilities`（能力、端点、身份、通知、审计）`blueprint`（新建应用、蓝图卡片、试运行、发布摘要）`personal`（个人应用）`records`（记录列表）`files`（文件控件） | +| 评测与口径账本 | `evals`（题集、加题、发起与进度、结果、对比与 A/B、口径命中与重复度）`ledger`（证据里的「口径」一步、轮次摘要、出具与对账、可沉淀的问题） | +| 应用平台 | `apps`（应用页、印章、点数字看出处、入口校验、实例页）`inbox`（会签进度、超时、动作确认的哈希卡、核实）`app-editor`（应用编辑、派生、检查、发布时选处置、助手）`capabilities`（能力、端点、身份、通知、审计）`access-keys`（访问密钥）`share`（分享链接与 /s 页）`blueprint`（新建应用、蓝图卡片、试运行、发布摘要）`personal`（个人应用）`records`（记录列表）`files`（文件控件） | 完整输出写进 `/tmp/agentlab-checks/<时间>/`，终端只给汇总；并行时没过的最后单独重跑一遍，重跑才过的单列成「偶发」。 `--stacks` 每套拷一份数据、端口自动挑空闲的，后端不热重载、vite 不监听文件，跑完、出错或被中断都收干净。