AgentLab/docs/zh-CN/upgrade-notes.md

English | 简体中文

升级说明

这篇按时间倒序列出各次更新里，对使用者和运维有影响的变化，以及升级时要做的事。给运维和管理员看。功能本身的说明在各主题文档里。

2026-10 编排完善第 2 波：PostgreSQL 与多进程

要做的事：多进程部署升级前，先停掉全部工作进程；代码节点要用的值改成显式传入；别删数据目录里的 .agentlab-data。

• 缺省仍是数据目录里的 SQLite、单进程，不改配置的部署升级后行为不变。启动时自动补上这一波的新列和索引。运行事件的 (run_id, seq) 改成唯一索引；存量库里要是已有重号，记一条日志、这一次不建，不影响启动。
• 数据目录里多了一个 .agentlab-data 标记文件，deploy.sh 靠它（或 agentlab.db、.secret_key）认数据目录，别删。
• 应用库可以换成 PostgreSQL，现有数据用 python -m app.db copy-to-postgres 导入；Docker 部署可以用内置或外接的 PostgreSQL，只能选一种（见 PostgreSQL 与多进程、部署）。
• 用 PostgreSQL 时可以起多个工作进程（AGENTLAB_WORKERS）。SQLite 只支持单进程，第二个进程拒绝启动。升级要先停掉全部工作进程：库里还有活着的、版本不同的进程时，新版本拒绝启动（deploy.sh upgrade 就是这样做的）。
• 运行按类别排队：交互、应用、定时、系统。全站上限照旧是 AGENTLAB_MAX_CONCURRENT_RUNS，缺省留四分之一给交互，可在「设置 → 偏好设置 → 运行并发」调。满载时评测、召回会比以前慢，换来问数据总有名额；评测每题的时限不算排队的时间。
• deploy.sh upgrade 升级前自动备份：SQLite 拷到 backups/sqlite/，内置 PostgreSQL 用 pg_dump 存到 backups/postgres/，各留最近 5 份。restart 缺省只重启服务，restart --postgres 连库一起。
• bubblewrap 沙箱不再继承后端的环境变量：代码节点里读不到模型的 API Key、数据库地址这类变量了。代码要用的值请显式传进去。
• 子工作流放在循环里多次执行时，写外部系统的幂等键改用父运行里的全局 id：以前循环第二轮的写入会拿到第一轮的回执、不发送，现在照常发。升级前停在子工作流里的运行恢复时仍认旧的键，已经生效的不重发。
• 问数据的心跳不再落库；结束超过 14 天的轮次清掉事件日志（那一轮的问答和答案照旧在对话里）。服务重启后接手一轮时，按账号现在的角色重新核对，停用或没了权限的照实标中断。
• 多行查询没有 ORDER BY 时，引用其中一格不再算「来自口径」，召回、对账里标「行序不定」，E1 统计会跟着变。全部指标都行序不定的召回，结论写「核对不了」并开待办，不再写「没变」。对账要人选对照指标时，按逐个数核对过的列预选。
• 待办、通知、Webhook 里照实写驳回的去向（「被驳回，转到 X」「这一路到此为止」），子工作流里的写「子工作流 › x」。子工作流里一步失败时，自动复核只报一条。用户看得到的列表遇到同名、同时间的并列时按 id 排，两种库顺序一致。

2026-10 编排完善第 1 波

• 问数据的一整轮（建图、发起运行、复核、按复核重来、落库）改在服务端的后台任务里跑，页面只负责看；停止走接口 /api/chat/turns。服务重启时还在建图的那一轮标中断、可重试。同一段对话同时只跑一轮。使用者的问数据现在也会被复核；继续运行照旧只给搭建者以上（见问数据与助手）。
• 子工作流里的每一步现在进同一个运行的事件流；子工作流出口的字段带着出处回到父图（最多 3 层），子工作流里追不到原始数据的，父图照样降档（见子工作流）。
• 审批、补充输入、编辑稿件、动作确认、代码和工具审批、双盲裁决可以多接一个「驳回」出口。不接时行为不变（记「已取消 · 被驳回」）。发布检查拦下走不到结束的驳回路径（见驳回）。
• 定时任务可以选「事件触发」，跟着 AGENTLAB_SCHEDULER 开关：关着时事件留着不派发（见事件触发）。

2026-10 下一轮第 4 波

要做的事：读事件的外部系统，按 node.failed 的 reason 区分驳回和失败。

• 导航多了「评测」（搭建者以上可见，⌥0，排在「设置」前面）。
• 受管口径发布新版本后，系统在后台召回重算用过旧版的答案，数真变了才开「召回」待办；每次发布最多重算 ledger.recall_limit 组（缺省 50）。发布后自动的那一批和启动时接着做，跟着 AGENTLAB_SCHEDULER 开关（见召回）。
• 审阅改了影响数字的目录项，或者表结构删表、删列、改列类型时，用过它的答案标「依据有变」；按新目录新出现错误级问题的才开待办。
• 被驳回的那一步，node.failed 事件多带 reason: "rejected"（和 run.cancelled 同一个字段），画布、航迹、时间线、问数据过程都画「被驳回」。老运行不变。
• 问数据每一轮的建图用量改成读完模型的流再记：以前流末尾才报的输出 token 没记上，这一轮的花费会比以前多一些，多的是原来漏掉的。
• 可订阅的通知事件多了「数据源有变化要处理」和「口径升版，答案的数变了」，消息里都不放数字。
• 口径标签改成逐个数判，比对算法升到第 4 版；老的比对记录照常可读，不会自动重算。评测评分规则升到第 2 版，老评测可以在评测详情里按新规则重评（只读封存，不调模型）。
• 助手只给了思考、一个操作都没给时，问数据和评测都自动重来一次。被取消、超时的模型调用也记一次调用（标「未完成」）。
• 数据目录页起草、剖析的进度挪到一条后台任务条，页头只留入口。数据源卡片上可以设「定时维护」。链到某个数据源卡片的地址统一是 /data/databases#source-<id>。

2026-10 下一轮第 3 波

要做的事：没有必须的操作。升级后第一次探查，每张表只建结构基线、不报变化。

• 探查结构时每张表记一个结构版本，和上一次比出结构变化，记进数据源的变化记录。从发布版本发起的正式运行，引用的表结构在发布之后变了时，多一条「表结构变化」提醒（schema.drift，在封存范围内）。
• 剖析多了取值观察；标了「已列全」的码值表出现新取值时，系统撤销「已列全」（见取值观察）。
• 数据源可以设定时维护；定时任务的目标也可以是评测题集。这两种目标不收 Webhook（回 422），通知走「设置 → 通知」的渠道订阅。
• 变化记录、评测、口径出具与对账在这一波只有接口（/api/datasources/{id}/changes、/api/evals/…、/api/ledger/answers/{run_id}/…），界面随第 4 波上线。
• 问数据的答案整题等价于一份已发布的受管口径时，系统按口径自动发起一次正式运行。「设置」的 ledger 一组可以关掉（auto_issue）；自动和一键合计每天最多 20 次。
• 应用视图、趋势、分享链接、视图数据接口取「最近一次封存」时，按口径出具、补算出来的运行不会顶替看板上的数（见视图与印章）。
• 开了登录时，使用者能读原始运行记录、事件和实时流的，只剩自己的问数据运行。
• 通知多了邮件（SMTP）、每天的待办汇总（notify.digest_at）和访问密钥到期提醒；关登录时后两项都不发。
• 分享链接缺省关（见分享链接）。

2026-10 下一轮第 2 波

要做的事：升级后每个数据源点一次「探查结构」，建立对象索引；超过 500 张表的库，先设「探查范围」。

• 探查结构改成后台任务，和同一个数据源的起草、剖析排队。老的表结构在探查读完之前原样保留。
• 超过 500 张表、又没设探查范围的库，第一次探查会被拒绝，并说出命中了多少张。先在「探查范围」里设规则，或调高上限（最多 2,000）。
• 正式探查不再接受 ?schema= 临时换 schema（一个数据源一个 schema），预览照旧可以。
• 运行时的 db_schema__ 不传表名时只列前 50 张；点名探查范围外的表会当场读结构、加进范围（每次运行最多 8 张，留痕）。
• 探索运行封存后，后台比对已发布的口径，追加一条封存后事件 ledger.matched，不在封存范围内。启动时补比最近 7 天的运行，跟着 AGENTLAB_SCHEDULER 开关。
• 报告导出和可验证报告下载各记一条审计 report.exported。问数据发起的运行带上所在对话和轮次（origin_ref），「在画布里打开」建的工作流记下来自哪一轮。

2026-10 下一轮第 1 波

要做的事：已经用 iframe 嵌 AgentLab 的门户，把门户地址写进 AGENTLAB_FRAME_ANCESTORS；设置里填了对外访问地址的部署，核对身份提供方登记的 OIDC 回调地址；升级后每个数据源点一次「探查结构」。

• 人工驳回的运行记为「已取消 · 被驳回」，不再算失败：通知走「实例结束」，定时任务推「未出具（被驳回）」，不能继续运行。配了失败重试或「出错时继续」的关卡，驳回不再重问、也不接着往下走。已封存的老运行不改写。
• 开了登录时，应用入口和待办表单里的选人控件按候选池核对，池外的名字回 422（principal）。
• 页面默认只能被本站嵌入（frame-ancestors 'self'，另加 X-Frame-Options）。
• 「对外访问地址」只剩一个设置（「设置 → 通用」；AGENTLAB_PUBLIC_URL 优先，写错了启动就报错）。设置里填了地址的部署，OIDC 回调改按这个地址拼，和身份提供方登记的不一致时要去改登记。开了登录时，/docs、/openapi.json 要搭建者登录。
• 探查结构时，列类型改存各数据库的完整写法（VARCHAR2(20 CHAR)、ENUM('a','b')）。新运行的表结构快照哈希会变，旧运行不受影响。MySQL / MariaDB 上，升级后第一次重新剖析时，这些表的目录各升一次版本（文字列多一句排序规则、ENUM 补上没出现的取值、日期列写明排除的无效日期）。剖析设置的「抽样键值数」改叫「核对键值数」。

应用平台

要做的事：子工作流、口径卡固定着没有正式运行凭据的老版本时，按提示改为固定一个已发布的版本；之后新建的内网 MCP 要管理员先在「工具 → 端点」登记。

升级后第一次启动会自动做这些事，都幂等：

• 存量的待审批补建成待办；自定义工具的请求头、MCP 的环境变量里的明文加密一遍；能力登记同步一遍。
• 记级别之前发布过、有正式运行凭据的老版本，补记为「已发布」。子工作流、口径卡固定的版本须已发布且未退役；固定着没有凭据的老版本时，正式运行会被拒绝。
• 指向本机或内网的 http MCP 服务，自动登记一个开了内网访问的端点（mcp-<服务名>）并绑定，写审计。
• /api/copilot/generate 改图时只出改动操作，不再是整张新图。每次运行多一条 run.origin 事件（在封存范围内）。