forked from EduCraft/curriculum-project-hub
sjfhsjfh
73e9d258d6
按新文风(简洁书面中文)重写 spec/ 全部 Lean doc 注释、spec/README, 并顺根 README。核心:讲清产品逻辑、去伪术语、去 ADR 黑话、DRY。 语言:砍钉死/留痕/实现侧/将就/脑补/刻意等伪术语;短句;不复述文件系统 能看到的东西;typst 考据移出 spec 指向 ADR。 内容取舍(动结构): - System 层大改:删 can_mono 形式化定理、Capability 9 项枚举与 requiredRole 映射、RunState 6 构造子;Audit.lean 删除并入 System 顶部。 Hub 未建的部分一律 prose 占位,只留 Lock 的 owner=run 与 WellFormed。 - 澄清两个"检查":产品 checker(LLM 判不了合法性,checker 真跑工具补这块) vs 开发时 spec↔impl 一致性检查(无自动闸门)。Oracle 重新定位为 "checker 得委托外部工具才能判的事实",不是"Lean 没写形式化"。 - spec/README 补取舍判据 checklist(自顶向下逐步细化、不在 Lean 里验证实现)。 - 根 README 去 DRY:删硬编码版本号、cache 路径细节;宪法第 3 条吸收 "人/coding assistant 核对"修正;第 5 条与 spec/README 判据去重。 保留:Export/Render 执行语义、Info 的 raw→canonical 设计模式(产品语义, 只顺文风不砍结构);renderIgnoredSeverity(实现对齐依赖)。 lake build 通过(24 jobs)。 Co-Authored-By: Claude <noreply@anthropic.com>
75 lines
3.9 KiB
Markdown
75 lines
3.9 KiB
Markdown
# spec —— 语义契约
|
|
|
|
## 这个项目在解决什么
|
|
|
|
教研产出现在是一摞一次性的文档:写完就躺着,改一次要同步很多地方,没法校验、
|
|
没法复用、没法追溯。这个项目想把教研产出变成可校验、可复用、能派生多种成品
|
|
(讲义、教案、课件、归档)的工程化文件。
|
|
|
|
但光有工程文件还不够。它要变成一个能卖钱的产品,还得:
|
|
|
|
- 工程文件这种形式,正好适合现在大热的 LLM assistant 来改,从而提效;
|
|
- 但 LLM 判不了一节课合不合法(它不能真去跑 typst 编译器、不能可靠地断言数据合不合
|
|
schema),所以产品里还有一个 rule-based checker:它真跑工具、给确定性的诊断,补上
|
|
LLM 判不了的这块。LLM 提效 + checker 兜底,两者一起才是完整的产品闭环。
|
|
- 加上一些提升体验的小功能:飞书/企业微信集成、自动化提醒之类;
|
|
- 如果要做 SaaS,还要有基本的管理概念:权限、LLM API 的配置和用量、费用等。
|
|
|
|
工程文件是起点,不是终点。
|
|
|
|
## spec 是什么
|
|
|
|
spec/ 是产品语义的契约,用 Lean 写。它定义产品各部件"是什么意思"。
|
|
|
|
- 它是开发者和 coding assistant 共同的语义依据:两边对某个东西的理解,以这里为准。
|
|
- 它不进产品运行时。运行时真正做校验的那个东西用什么技术实现,还没定;但它的语义,
|
|
先在这里固定下来。
|
|
- 它精确、自洽,机器能校验它内部结构没有漏洞。它不保证实现一定符合它——
|
|
实现和它是否一致,没有自动检查,要靠人工或 coding assistant 不定期(或每次改动后)核对。
|
|
|
|
## 人机怎么一起干活
|
|
|
|
- 凭语义,不凭经验。这个领域新,coding assistant 在这里没有可靠的既有经验,
|
|
所以语义以 spec 的注释为准,不要凭训练先验臆测。
|
|
- 契约没写的,就是不存在的。遇到没定的点,提出来让开发者定,不要替它选答案。
|
|
- 改了实现或 spec 之后,两边是否还对得上,要核对一下;这一致性没有自动闸门。
|
|
|
|
## 怎么往 spec 里写
|
|
|
|
### 一条东西要不要进 spec
|
|
|
|
不写它,开发者和 coding assistant 会不会各自做出不同假设?会,就进;不会
|
|
(显然的事、纯基础设施、普通 CRUD 字段),就不进。
|
|
|
|
### 进了之后,钉到多细
|
|
|
|
- 现在想清楚的,用 Lean 固定(声明、类型、关系)。
|
|
- 没想清楚的,两三句话 prose 占位,标 `OPEN`。等讨论或业务反馈后再细化,
|
|
细化结果可以再用 Lean 固定。
|
|
- 不在 Lean 里验证实现真的做了这些事。spec 只讲"要做什么、判什么";实现有没有真做,
|
|
不形式化证明。
|
|
- 形式化定理:不用写;写了不是坏事,但现在很少有能写的定理。定理本身得是产品语义,
|
|
不是"实现该满足的性质"。
|
|
|
|
### 写的时候
|
|
|
|
- 每个顶层声明要带 doc 注释,用 `/-- ... -/` 写自然语言,说清这在领域里是什么、为什么。
|
|
注释是语义的依据,Lean 类型保证结构,两者缺一不可。
|
|
- 在注释里标这条语义的状态:
|
|
- `PINNED`:已定,契约在此处权威。
|
|
- `OPEN`:故意没定。不要假设它的解,遇到要提出来讨论。
|
|
- `ADR-NNNN`:指向 `docs/adr/` 下的决策记录。
|
|
- 不用 `sorry`。没想清楚的,用 `OPEN` 标在注释里,不要用 `sorry` 假装成立——
|
|
那会让构建通过,却在契约里埋一个谎。
|
|
- 不复述文件系统上能直接看到的东西(目录结构、文件名)。文件系统应当自描述,文档讲 context。
|
|
- 不写变更史(进 git/ADR)。不搬 ADR 内部黑话,要表达就直说。
|
|
不为设计选择辩护("刻意用 X 而非 Y"),只说是什么。
|
|
- "为什么"的背景考据(如某工具的内部机制)不进 spec,指向 ADR;但产品行为和设计模式要钉。
|
|
|
|
### 命名
|
|
|
|
- 模块/命名空间:PascalCase,按分层,如 `Spec.System.Run`。
|
|
- 类型:PascalCase。
|
|
- 谓词(`Prop`):用意图清楚的词,如 `Legal…`、`ValidTransition`、`Can…`。
|
|
- 文件粒度:一个带独立不变式的概念一个文件。
|