23 Commits

Author	SHA1	Message	Date
ThearchyHelios	2714890d0d	文档重新梳理：README 精简成介绍和索引，细节按主题拆进 docs/zh-CN 与 docs/en（17 篇一一对应），英文文档不含中文 ... README.zh-CN.md / README.md 只留：这是什么、为什么用它、主要功能（按领域一行一条，链到文档）、快速开始、部署、文档索引、 开发与测试、许可（原文不动）。原来的每一节按读者和任务分到 17 篇主题文档：ask-data、workflows、evidence、 data-sources（新增：接入数据库、只读保证、上传表格、跨库合并、遮罩列）、data-catalog、tools（新增：工具、审批档位、 能力登记、端点、网络规则——它们管所有工作流，不只应用）、apps、evaluation-and-ledger、schedules（含通知）、deployment、 configuration、postgresql-and-scaling、identity-and-security、architecture、development、upgrade-notes（按时间倒序， 每波先写要做的事）、faq。删掉的只有模块名（api/copilot_gen.py、chat/drive.py、data/schema_view.py）、重复的话和 「以前…现在…」的叙述；操作步骤、命令、配置名、限制、权限边界都有归宿。中文是原文，英文按新的中文写；英文里界面文字 只写英文名，开头注明界面目前只有简体中文，中文占位符换成英文占位符，中文数字的例子改成不依赖中文的说法。 数据剖析可以同时剖析 2–3 张表（baf23998）收进 data-catalog。 新增 scripts/check-docs.py：英文文档（README.md、docs/en/**）不许有中日韩字符和全角符号（代码块也算）， README、docs/**、deploy/README.md 的相对链接和锚点都要通，docs/zh-CN 与 docs/en 文件一一对应、标题层级相同。 中文提示里指向 README 章节的地方改指新文档：cluster/guard.py、cluster/version.py、db/base.py 两处报错， data/schema_view.py 文档串，.env.example 三处，scripts/prod.sh、scripts/test-postgres.sh，terms.ts 两处、 DataSourcesTab.tsx、check-manage.mjs 注释，deploy/README.md 三处链接。deploy/agentlab.env 未动。 验收：check-docs 0 问题（英文文档 18 个 0 处中文，相对链接 369 条 0 断链，18 对标题层级一致）；相关后端测试 117 通过、7 跳过；tsc -b、check-copy 通过。	2026-10-21 10:23:26 +08:00
ThearchyHelios	aadc8d0115	中文 README 移到 README.zh-CN.md（内容不改，顶上加语言切换），中文提示里指向 README 章节的地方改指中文版 ... git mv 保留历史；顶上一行「[English](README.md) | 简体中文」，英文版随后单独提交。 改指 README.zh-CN.md 的：报错文字（cluster/guard.py、cluster/version.py、db/base.py 两处）、.env.example 三处注释、 scripts/prod.sh 用法说明、scripts/test-postgres.sh 注释、「口径同 README「哪些角色看得到原值」」的四处代码注释 （terms.ts 两处、DataSourcesTab.tsx、check-manage.mjs），deploy/README.md 里三处「仓库 README」写成指向 ../README.zh-CN.md 对应章节的链接。 没改的：deploy/deploy.sh 四处「README 的常见问题」「README「用 PostgreSQL」」和 deploy/agentlab.env 117 行——离线包里和 deploy.sh 放在一起的 README.md 就是 deploy/README.md，那几句指的正是它的常见问题、用 PostgreSQL 两节； deploy/README.md 第 16 行文件清单说的是它自己；version.py、runner.py 文档串里「以前 README 写…」是旧事的叙述。 验收：相关后端测试 117 通过、7 跳过；tsc -b、check-copy 通过。	2026-10-21 08:13:58 +08:00
ThearchyHelios	eb9af51abb	复核 R-b14（PostgreSQL 单进程墙钟一跳就隔离自己）：取得到计入休眠的钟（SLEEP_AWARE）时 stale() 只看它，墙钟只在取不到时当后备（两只里走得多的那只）；两只钟对不上（jumped）不再直接隔离，先续一次租——续租那一句按库的时钟核对「自己的租约还没过期」，以它为准：续上了只记一条日志照常，续不上才隔离。README「多进程」补一句：库服务器自己的时钟往前跳超过一个租约时所有进程一起隔离、怎么恢复，往回跳时真没了的进程要多等，本机墙钟跳了不隔离。补测试：墙钟往前往后跳一小时不算续晚了、只算对不上，计入休眠的钟走过两个租约照样算，取不到时墙钟当后备；PostgreSQL 单进程墙钟 ±1 小时续租照常续上、不隔离，真过期仍隔离；执行到一半墙钟 ±1 小时，运行照常跑完、世代不变（改前的写法往前跳那条不过）	2026-10-19 15:07:17 +08:00
ThearchyHelios	68c1f4143e	复核 R-b13（版本拦截与零碎）：preflight 报错列出全部活着的、版本不同的进程，各标明心跳在走还是停着、等租约过期（以前只点名先看到心跳的那个，人停掉它再起还会被另一个拦下）；源码指纹把依赖锁文件 requirements.lock 的内容也算进去，只升了依赖也算版本不同，锁文件取不到时换成几个关键包的版本，Docker 镜像里留一份锁文件；存量库 run_events 撞了号时把结果记一次（settings 表 cluster:run_events_seq_duplicates，记下撞号的那几处，最多 200 处），之后启动不再整表 GROUP BY、只按索引核对那几处还撞不撞，都处理掉了才再数一遍、建唯一索引、删掉记录。隔离后换身份那几条日志写出新旧完整身份已在 R-b9 那一笔里改了。README「升级」一段跟着补一句。补测试：一个心跳在走、一个心跳停着，报错两个都列出、各标状态；锁文件变了指纹跟着变、取不到时用包版本；撞号第一次整表数、第二次只核对不扫、处理掉之后建上索引并删掉记录	2026-10-19 14:45:54 +08:00
ThearchyHelios	ed3bb943df	复核 R-b11（跨零点退回额度退到第二天那一行）：quota.take 交回占在了哪一天（本地日期），占不到交回 None；出具、按需视图发起失败时按这个日期退回——23:59:59 占、00:00:01 失败，退的是前一天那一份，第二天的不动。补测试：跨零点占了两份、退回前一天那一份，前一天归零、第二天那份不动	2026-10-19 14:40:11 +08:00
ThearchyHelios	1e6f0554fe	复核 R-b10（隔离换身份后旧身份的名额、请求没人收拾）：要名额时把当时的身份记在 holder 上，放的时候按它删，换了身份也删得到；新身份登记上之后收拾旧身份（tidy_retired）——它的执行都已停下、写不了了，不必等它的租约过期：删掉它的登记（发 gone，别的进程马上按属主不在了接手它认领的运行、任务）、它占着的运行名额和同源队的位置，交出它拿着的当班租约，发给它的请求转到新身份名下照办，照实记一条日志；停止请求对不在本进程执行的运行也照停止的规矩办（cancel 自己看属主：转给正在执行它的进程、属主不在了就接手放弃、停在断点上的收成 cancelled）。补测试：拿着名额时换了身份照样放得掉（改前的写法这条不过）；新身份登记上之后旧身份的登记、名额、队里的位置、当班租约都收拾掉，转过来的停止请求把停在断点上的那次运行收成 cancelled	2026-10-19 14:36:19 +08:00
ThearchyHelios	ba22b82b3d	复核 R-b9（Fenced 打到不该打的地方）：check() 续晚了谁问到都隔离，但只对绑定了世代的执行（运行的一段执行、后台任务）抛 Fenced，HTTP 处理、调度那一拍、进程间请求问到时只隔离不抛；调度循环、心跳、办进程间请求也接住 Fenced；续租的任务不再因为一下出错就退出——续租、隔离之后重新登记都包住，照实记日志、退避着重试（最长一个租约时长）。隔离时马上换身份（之后新建的行记新身份），新身份登记上之前心跳不争当班、不接手，新开始的运行、后台任务在 fence.ready() 上等（最多一个租约时长，等不到就不开始，那几行由别的进程按属主不在了处理，这边同时放弃这个一直没登记上的身份、再换一个）。日志写出新旧完整身份。补测试：没绑定的调用者只隔离不抛、绑定在隔离之前的抛、新身份登记上之前 ready 等着；调度循环被 Fenced 打到一拍之后照常；重新登记先被版本守卫拦、再碰上库连不上，续租任务都不退出，登记上之后照常续租	2026-10-19 14:33:45 +08:00
ThearchyHelios	7fcce90f95	复核 R-b7（休眠、时钟偏差下隔离失灵）：租约改用库的时钟——续租、登记写 lease_until = 库的 clock_timestamp() + 租约，判活、清理过期登记、版本守卫看谁活着都比库的时钟，调度当班的租约同样按库的时钟接班、续租，本地判还当不当班改看计入休眠的单调钟，机器之间墙钟差多少都不起作用；隔离改用计入休眠的钟（Linux CLOCK_BOOTTIME，macOS clock_gettime(CLOCK_MONOTONIC)，取不到退回 monotonic），并且一律同时比墙钟，两只钟里走得多的那只说过了一个租约就算续晚了；续租时两只钟差出一个租约（墙钟跳了、休眠没计）也隔离；续租那一句带上「库里自己的租约还没过期」的条件，过期了或者登记不见了就不再续这个身份、隔离换身份（以前登记不见了是用旧身份重新登记）。补测试：单调钟不走而墙钟过了两个租约、墙钟往回拨，都算续晚了；本机墙钟快一小时，别的进程照样活着、当班租约抢不走；库的时钟过了自己的租约时续租不续、隔离一次	2026-10-19 14:27:55 +08:00
ThearchyHelios	5b24480268	版本守卫拒绝启动的那句话改掉「混跑」（check-copy：「跑」不作动词）：不支持新旧版本同时运行，先停掉这些进程再启动新版本	2026-10-19 13:33:07 +08:00
ThearchyHelios	62089f2849	复核「另外两处」：评测每题的时限、算期望的时限都不算排队等运行名额的那一段（within 代替 asyncio.wait_for，作答那次运行在 slots 里还排着队时不走表；算期望的运行排着队时把截止时刻往后挪），满载时不再被记成超时、触发止损；同源队（SourceLanes）跟发名额一样，拿这个源的咨询锁之前备好「哪些别的属主确实不在了」，持锁期间只用持锁的那条连接，拿锁之后才出现的属主这一次当活着。slots 加 waiting(run_id, here=)：本进程里的直接看、不查库。补测试：排队 0.8 秒、时限 0.3 秒照样答完不记超时（改前的写法这条不过）；within 暂停的那几段不算、不暂停照样超时；同源队持锁期间不查「谁还活着」、没了的进程照样让位、拿锁之后才出现的属主不删	2026-10-19 13:31:46 +08:00
ThearchyHelios	f3ff5b9c18	复核 R-b5、R-b6：转发运行事件、读缓存失效通知都从游标往回留一小段重读（运行 64 条、缓存 200 条），按发布过的 seq / 处理过的 id 去重——号先取后提交、号大的先提交时，号小的那一条后到也照样转、照样失效，不越过回放已经发过的那一段；合成之后超长的正文增量按字切成几条（二分找每段最长的前缀，不切坏 UTF-8），不再截掉。补测试：号小的后提交照样转出来、不重复；缓存失效 id 大的先到、小的后到都处理；超长增量切开拼回来一字不少	2026-10-19 13:24:44 +08:00
ThearchyHelios	5578cf137d	复核 R-b4（prod.sh、Docker 入口读不到 .env 里的配置）：新增 python -m app.cluster workers——照后端自己的配置（环境变量和 .env 一起读）说起几个工作进程，SQLite 而大于 1 时照实报错、退出码 2；prod.sh 只在命令行给了 --workers 时写进环境变量，进程数一律问后端，Docker 的入口同样问它。补测试：SQLite 而大于 1 拒绝、PostgreSQL 照给的数	2026-10-19 13:23:02 +08:00
ThearchyHelios	5f7100906f	复核 R-b3（SQLite 单进程多出来的写库）：SQLite 时守卫已经确认只有本进程——登记只写一次、不续租约、本进程直接当班（不写库）、接手只在启动时做，心跳只做本进程自己攒着的活；运行的名额在 SQLite 下放在进程里（规矩同一套：优先级、类别上限、交互留底，只是不落库），一段运行不再为要名额多写三次库。顺带（复核「另外两处」之二）：PostgreSQL 发名额持着全站的锁时不再另取连接查「谁还活着」，拿锁之前备好，不认识的属主这一次当活着。补测试：SQLite 空闲十来拍心跳、要一次名额放一次，PRAGMA data_version 不变（名额落库的写法这条不过）；库里的名额行那两条只在 PostgreSQL 上跑	2026-10-19 13:22:05 +08:00
ThearchyHelios	35ab097b45	复核 R-b1（卡住但没死的进程被当成没了）：续租约挪到单独的任务、专用连接（不走连接池，不被同一拍别的活拖住）；进程间请求另起任务办，不在心跳里等收尾；新增 cluster/fence 自我隔离——离上次续上租约超过一个租约时长，或者这段执行属于上一次隔离之前，执行在写事件、写断点、开审批、发外部写入、后台任务写库之前就停手（Fenced 是 BaseException，节点里的 except Exception 拦不住），续租时发现续晚了就隔离：停掉手上的运行和后台任务、不写终态，换一个身份重新登记；运行收尾先占住那一行、属主不是自己就不写；别的进程按租约过期再多等一个租约时长才算不在了（两边中间留一段）；run_events 的 (run_id, seq) 改成唯一索引（存量库先数重复，有就照实记日志、这一次不建，不让启动失败）。补测试：卡住期间被接手之后不盖终态、不写事件、序号不重；被接手的那次在别处接着跑完只结束一次、后面那一步只跑一次；收尾按属主写；撞号被库拒绝；多进程端到端加 6b、6c（真 SIGSTOP / SIGCONT）	2026-10-19 13:15:56 +08:00
ThearchyHelios	75ab3678cb	代码里拦住新旧版本混跑（用户拍板）：新增 cluster/version——代码版本（包版本 + 构建号 AGENTLAB_BUILD 或 git 提交 + app/ 下源码指纹，比较按源码指纹）、库结构版本（各表各列加迁移清单的哈希），进程登记时一并记下（cluster_workers 两列，add-only 迁移）。PostgreSQL 时补列之前先看一眼（preflight）：库里还有活着的、版本不同的进程，心跳在走就拒绝启动、照实写明是哪几个进程什么版本、要先停掉再升级，心跳停着的（强杀留下的）等租约过期再起；登记那一下在事务级咨询锁里再查一遍，两个不同版本同时启动只有先登记上的起得来。Docker 镜像带上构建号；README 写明升级步骤。补测试：版本不同的活进程被点名拒绝、同版本照常加入、过期的不算、只比源码指纹；PostgreSQL 上心跳在走的拒绝、心跳停着的等过期、登记时再拦一次	2026-10-19 13:04:07 +08:00
ThearchyHelios	d68ca9774f	加直连地址 AGENTLAB_DATABASE_DIRECT_URL 和 PgBouncer 事务模式开关 AGENTLAB_DB_PGBOUNCER（用户拍板）：依赖会话状态的连接——收发进程间通知的那一条（LISTEN）、跨进程的锁（会话级咨询锁，另建一个直连的小池子）、断点库（缺省）——走直连地址，普通查询走 AGENTLAB_DATABASE_URL，不设就全用同一个；开关打开时普通地址不用客户端连接池、关掉 SQLAlchemy 和 asyncpg 的预备语句缓存、预备语句用随机名字（照 SQLAlchemy 文档），事务级咨询锁照常成立；开关打开却没给直连地址时拒绝启动。README 写三种部署（直连、PgBouncer 会话模式、事务模式加直连地址）和要配的 server_reset_query，照实说没在真的 PgBouncer 上跑过。补测试：地址解析和规范化、断点库缺省走直连、事务模式关掉的几样、LISTEN 和跨进程锁走直连、事务模式没给直连地址拒绝启动	2026-10-19 13:01:21 +08:00
ThearchyHelios	01af07b193	出具、按需视图的每日上限改成先占额度再发起（用户拍板）：新增 cluster/quota——额度记在库里（rate_counters 按名字 + 本地日期一行），占一份是一句带条件的 UPDATE（没到上限才加一），两种库上都是原子的，这一天第一次占按库里已有的记录起算，发起被拒或出错就退回。出具去掉全站一把锁，只留同一（运行、工作流、版本）的去重锁，几份不同的出具可以同时发起；按需视图的锁缩回按缓存键（视图 + 参数）去重，每日上限改用这个应用的额度。补测试：20 个协程同时占正好到上限、按已有记录起算、退回再占；两个进程同时占正好到上限；三份不同的答案同时出具正好到上限、多出来的回 429	2026-10-19 12:57:38 +08:00
ThearchyHelios	6ed782a84b	运行名额改成给交互留底、其余可借（用户拍板）：交互留底缺省全站上限的 1/4、至少 1、至多全站上限减 1，应用、定时、系统三类合起来永远用不到留底；三类各自的上限缺省 = 全站上限 − 留底（设置里可调小），没人问数据时评测能开满；交互上限缺省 = 全站上限；等名额照旧按优先级、同级先来先得。存着的设置原样存、缺省按全站上限和留底现算；留底不小于全站上限时 422。设置页「运行并发」加「给交互留底」一项，写明留底和借用是什么，README 同步。补测试：缺省值、空闲时系统类借满到 全站 − 留底、留底不借给应用类、问数据一来马上拿到留底；多进程端到端加 5b（评测借满时问数据拿留底、不等评测跑完）	2026-10-19 12:53:28 +08:00
ThearchyHelios	e6a3ee8f95	转发运行事件时跳过不认识的事件种类（回放照样读得到）；test-multiprocess.sh 不带参数时 macOS 的 bash 3.2 报 args 未定义，参数直接原样交给 pytest	2026-10-19 12:30:30 +08:00
ThearchyHelios	4e3623885b	合入 W2-a 的复核修复（nr8/a：导入的 NOT NULL 补值与孤儿行、收尾 dispose、sslmode 换算、PostgreSQL 写入去 NUL、不分大小写搜索 contains_ci、json_eq 两库同语义、JSON 守卫、用户可见列表补决胜键、bubblewrap --clearenv、部署脚本与原子写的几处、README 连接数预算） ... # Conflicts: # backend/app/api/schedules.py # backend/app/main.py	2026-10-19 12:21:38 +08:00
ThearchyHelios	1acf960312	多进程端到端验收：scripts/test-multiprocess.sh 用本机 postgres:16 起临时库，tests/test_multiprocess_e2e.py（缺省跳过，AGENTLAB_MULTIPROCESS_E2E=1）在上面起两个 uvicorn 工作进程，用演示模型跑七个场景——两个进程都登记、一个当班；运行由接到请求的进程认领，另一个进程上的流收得到实时事件和流式增量，同一个审批决定同时发给两边只执行一次，两边事件流不重不漏、封存核对得上；跨进程停止；定时只触发一次；全站一个名额时评测的作答运行排着队，后来的问数据运行先拿到名额；两个进程同时记同一本每日账不越过上限；强杀一个进程后在跑的运行被照实标中断、停在审批上的照常在另一个进程上批完、当班交接。顺带修：等名额时被停止也照实收成已取消（以前停在排队中）；当班的本地余量不超过租约的四分之一（租约调短时一直不当班）；启动清理上传半成品时没有别的活着的进程就全清；文件锁守卫的几项测试只在 SQLite 跑；问数据事件日志清理那一拍不带时刻时按现在算	2026-10-19 12:03:35 +08:00
ThearchyHelios	c768c56fd7	多进程协调补齐几处：执行时长从拿到名额算起（排队等名额不算执行，墙钟本来就从开始执行算）；蓝图留痕、蓝图助手开轮先占住那一行再取最大值往下接；问数据等别的进程接着跑的运行时回库里等封存；按配方导入的 AI 起草、知识库重建索引另取跨进程的锁（多进程时重建进度记在设置表里，别的进程读得到、属主不在了照实说没做完）；调度循环一拍的间隔可配（AGENTLAB_SCHEDULER_TICK_S）	2026-10-19 11:51:29 +08:00
ThearchyHelios	87f0d62f9b	多进程协调（W2-b）第一步：新增 app/cluster——工作进程在库里登记、心跳续租约（属主随进程，进程没了它认领的行一起到期），调度当班的租约，发给属主进程的停止 / 记事件请求，PostgreSQL 的 LISTEN/NOTIFY 叫醒，跨进程的互斥锁（咨询锁），SQLite 单进程守卫（第二个进程拒绝启动）；运行、问数据一轮、起草 / 剖析 / 探查 / 评测 / 影子起草、文档、发布单记 owner，启动整理改成只接手属主不在了的行，当班进程隔一会儿再接手一次；运行的并发名额改成库里按交互 / 应用 / 定时 / 系统四类发（各有全站上限和优先级，设置里可调），替掉进程内的信号量；同源队记在库里；运行停止、记事件跨进程交给属主；运行事件、问数据事件跨进程转发（库里按 seq 追，不落库的流式增量和保活心跳只转给在看的进程）；每日花费账先占住那一行再读写；访问密钥限流、登录失败计数在 PostgreSQL 时记在库里；登录设置、对外地址、向量模型、能力快照、数据源连接池、应用页面缓存跨进程失效；上传版本库、记录表、按需探查、出具、召回、补算、按需视图、个人刷新、定时发起的锁换成跨进程的锁	2026-10-19 11:40:33 +08:00