From 493ea6d89db95479fe6be34a95430c1c0b51bdb7 Mon Sep 17 00:00:00 2001 From: iomgaa Date: Fri, 2 Oct 2026 06:25:16 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=86=99=E6=98=8E"=E8=BE=B9=E7=95=8C"?= =?UTF-8?q?=E6=8C=87=E4=BB=80=E4=B9=88=EF=BC=9B=E5=94=AF=E4=B8=80=E7=BA=A6?= =?UTF-8?q?=E6=9D=9F=E6=94=B9=E4=B8=BA=E6=9C=89=E7=BC=96=E5=8F=B7=E3=80=81?= =?UTF-8?q?=E5=8F=AA=E5=8F=91=E7=94=9F=E4=B8=80=E6=AC=A1=E7=9A=84=E5=85=AB?= =?UTF-8?q?=E7=A7=8D=E8=AE=B0=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 用户 2026-10-02 同意：CLAUDE.md"罕见情况怎么办"第 2 条写明边界是模型的提交、用户的配置、外部服务的返回，模块之间的调用不算边界；哪些记录加唯一约束属于账本设计，写在结构.md 第四部分（阶段开关、运行登记、确认启动、运行结果、模型调用开始结束、消融结算），前后顺序由 flow 的同一入口保证。任务书 03 同步。 Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 2 +- docs/结构.md | 2 +- 任务书/03-ledger.md | 13 +++++-------- 3 files changed, 7 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9228d4b..c53d46d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -56,7 +56,7 @@ 没见过的情况不写专门处理。按顺序选： 1. 改数据的表示或格式要求，让它不可能出现。例：要求研究者的三个数严格递增，就不存在"三个数相等"。 -2. 做不到，就在数据进来的那一处检查，不满足就报错停下；真出现了，再按"遇到问题先找原因"去改。 +2. 做不到，就在系统的边界检查，不满足就报错停下。边界指模型的提交、用户的配置、外部服务的返回；模块之间的调用不算边界，不为另一个模块可能写错而加检查。真出现了，再按"遇到问题先找原因"去改。 "可能会出现"不是写分支的理由：不写的代价只是它出现时停一次，写了的代价是一段平时跑不到、坏了也没人知道的代码。审别人的提议时也只问一句：不写会怎样？答案是"会报错停下"，就不写。 diff --git a/docs/结构.md b/docs/结构.md index 6ebe658..45236ca 100644 --- a/docs/结构.md +++ b/docs/结构.md @@ -114,7 +114,7 @@ **全部只追加。** 所有记录放在同一张表里，每一行是：序号（自动递增，就是时间先后）、种类、内容（JSON）、内容的哈希。整张表禁止修改、禁止删除，由数据库触发器保证。要更正就追加一条新记录；"开"和"关"、"替换"也都写成新记录。 -恢复时只核对、不重做写入（CLAUDE.md"中断后怎么恢复"），所以记录照写就是，不需要通用的去重。只在方法要求"只能有一次"的地方加唯一约束，重复了就报错：一次运行的确认启动、一次运行的结果、一次消融的结算。运行编号由 flow 起；确认没启动、退还名额后要重试，就起一个新编号。 +恢复时只核对、不重做写入（CLAUDE.md"中断后怎么恢复"），所以记录照写就是，不需要通用的去重。有自己编号、按定义只发生一次的记录，按编号加数据库唯一约束，重复了就报错：阶段开、阶段关、运行登记、确认启动、运行结果、模型调用开始、模型调用结束、消融结算。没有这种编号的记录（提交的各个版本、事件、用量）照写。前后顺序（比如启动前要先登记）由 flow 的同一个入口保证，ledger 不查。运行编号由 flow 起；确认没启动、退还名额后要重试，就起一个新编号。 | # | 记录 | 内容 | 谁写入 | |---|---|---|---| diff --git a/任务书/03-ledger.md b/任务书/03-ledger.md index b3d7c20..8115c48 100644 --- a/任务书/03-ledger.md +++ b/任务书/03-ledger.md @@ -11,7 +11,7 @@ 第一版要求 ledger 做三件事：判断"谁在什么时候能看到什么"（快照加截止序号），给每条记录配唯一键，同样内容重写时当作已经写过。用户指出这三件都是过度设计： - "这个任务能看到哪些材料"由 materials 按任务定。第一条消息里直接给，还是等模型用查询工具去读，是同一份材料的两种给法。ledger 不判断谁能看什么，所以也没有截止序号。 -- 恢复时只核对、不重做写入（CLAUDE.md"中断后怎么恢复"），所以记录照写就是，不需要通用的去重。只在方法要求"只能有一次"的地方加唯一约束。 +- 恢复时只核对、不重做写入（CLAUDE.md"中断后怎么恢复"），所以记录照写就是，不需要通用的去重。只给有自己编号、按定义只发生一次的记录加唯一约束。 - Jev 是一个判别器，和程序检查地位相同，不单独成一种记录。 已经写好的代码里，存储、禁改触发器、提交内容检查、作者自评拆成封存，都还用得上。 @@ -22,7 +22,7 @@ - `src/ledger/visibility.ts` 和 `tests/ledger-visibility.test.ts`：整个删掉。 - `snapshot`、`Viewer`、截止序号：从代码、导出和测试里删掉。 -- 通用唯一键（`keyOf`、`joinKey` 一类）、"同样内容重写当作已经写过"的处理和它的测试：删掉，只留第一部分说的三处唯一约束。 +- 通用唯一键（`keyOf`、`joinKey` 一类）、"同样内容重写当作已经写过"的处理和它的测试：删掉，只留第一部分列出的唯一约束。 - `jev` 这种记录：删掉，改为写进"退回"和"决定"的内容里。 - 第一版之后加出来、不在第三部分四种里的写入前提检查：删掉，测试一并删掉。 - 注释里提到快照、截止序号、可见性、"同内容重写"的地方：按这一版改写或删掉。 @@ -58,12 +58,9 @@ - 内容：JSON； - 内容的哈希：用 vocab 的 `canonical` 和 `hash`。 - **整张表禁止修改、禁止删除**，用两条触发器实现。 -- **唯一约束只加在三处**，都是方法要求"只能有一次"的地方。重复了就报错，不当作已经写过： - - 一次运行的确认启动； - - 一次运行的结果； - - 一次消融的结算。 +- **唯一约束**：有自己编号、按定义只发生一次的记录，按编号加数据库唯一约束，重复了就报错，不当作已经写过（结构.md 第四部分）：阶段开、阶段关、运行登记、确认启动、运行结果、模型调用开始、模型调用结束、消融结算。 - 其余记录照写，不设唯一键。 + 其余记录照写，不设唯一键。前后顺序（启动前要先登记、结束前要先开始）由 flow 的同一个入口保证，ledger 不查。 - 打开数据库时： - 新文件就建表； - 旧文件核对一个表结构版本号，对不上就报错。 @@ -145,7 +142,7 @@ 用真实的数据库文件，放在临时目录里，每个测试自己建、自己删。重点： - 用 SQL 直接执行 UPDATE、DELETE，被触发器拒绝。 -- 三处唯一约束：同一次运行确认启动两次、写两个结果、同一次消融结算两次，都报错。 +- 八处唯一约束各有一条测试：同一个编号写第二次就报错。 - 第三部分的四种拒收各有一条测试；同时测对应的正常情况能写进去。 - 写提案时作者自评拆成封存，提案记录里不带它。 - 事务中途出错，一条都没写进去。