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.8 KiB
Markdown
75 lines
3.8 KiB
Markdown
# curriculum-project-hub
|
|
|
|
教研生产的数字化解决方案。核心思路:课程像 DAW / 剪辑软件那样有一个结构化的工程文件;
|
|
LLM assistant 协助编辑它;一个 rule-based checker 校验其合法性并给出有用的诊断。
|
|
|
|
LLM 提效,但判不了一节课合不合法(它不能真去跑 typst、不能可靠地断言数据合不合
|
|
schema);checker 真跑工具、给确定性诊断,补上这块。两者一起才是完整闭环。目标是把教研
|
|
从一次性的文档,变成可累积、可校验、可复用的资产。
|
|
|
|
这是一个 monorepo。组织方式本身就表达了一条原则:`spec/` 是上游的语义母本,其余部件是
|
|
向它对齐的实现。
|
|
|
|
## 安装 `cph`
|
|
|
|
从源码安装(本仓库根目录):
|
|
|
|
```sh
|
|
cargo install --path crates/cph-cli --locked
|
|
```
|
|
|
|
`render` 包已嵌入二进制,装好后无需任何环境变量、不依赖源码树即可用。开发时可设
|
|
`CPH_RENDER_DIR` 指向 live `render/` 目录覆盖。
|
|
|
|
```sh
|
|
cph check <工程目录> # 校验合法性
|
|
cph build <工程目录> --target student -o build/student.pdf # 渲讲义 PDF
|
|
cph completions zsh > ~/.zfunc/_cph # shell 补全(可选)
|
|
```
|
|
|
|
工程文件根放一个 `.cph-version` 文件,声明它面向的 cph 版本;`cph` 加载时比对自身版本,
|
|
不相容则拒绝(版本契约,ADR-0016)。
|
|
|
|
## 仓库布局
|
|
|
|
`spec/` 是 Lean 语义母本(自包含 Lean 工程,见 `spec/README.md`);`crates/` 是实现
|
|
(rule-based checker,向 spec 对齐,见 `crates/README.md`);`render/` 是 typst 渲染包;
|
|
`examples/` 是样例工程文件;`docs/adr/` 是架构决策记录,被 spec 引用。
|
|
|
|
`spec/` 与实现部件物理分离、平级共存:谁是上游、谁向谁对齐,一眼可见。实现部件共用一个
|
|
仓库根的 cargo workspace,使基础 crate 能被未来部件复用。
|
|
|
|
## 宪法
|
|
|
|
这 5 条是 `spec/` 这份语义母本的定位与约束,是本仓库一切工作的前提。
|
|
|
|
1. **角色——Lean 是研发侧的上游参照。**
|
|
`spec/` 用 Lean 写,是开发者和 coding assistant 共用的 spec 工具,用来沉淀产品各部件
|
|
的语义。它不进产品运行时——运行时那个 checker 用什么技术实现还没定,但它的语义先在
|
|
`spec/` 里固定下来。
|
|
|
|
2. **对齐机制——Lean 只做上游参照。**
|
|
不做 extract / codegen,不派生 conformance test,CI 里没有 spec→实现的 gate。实现对齐
|
|
spec,靠开发者 review 和 agent 巡逻 diff 这个人肉环节承载。(CI 里的 spec check 只验
|
|
spec 自身能否 type-check,即契约内部良构,不是 spec↔实现对齐检查。)
|
|
|
|
3. **资产性——由核对纪律承载,无机器兜底。**
|
|
这份仓库给的是精确、自洽、机器验过内部良构的语义共识,不是实现正确性的保证。spec 与
|
|
实现是否一致,没有自动闸门,要靠人工或 coding assistant 不定期(或每次改动后)核对;
|
|
坚持核对,它就是有用的参照,否则只会变成过期的文档。
|
|
|
|
4. **形态——它是人机共识的契约。**
|
|
契约必须自包含:凡契约未明文规定的,开发者与 agent 双方都不该假设。这比"文档"严格——
|
|
type checker 会逼这份契约在结构上无洞。
|
|
|
|
5. **深度判据——只收录分歧点。**
|
|
一条语义该不该写进 Lean,取决于一句话:不写明,开发者与 agent 会不会各自做出不同
|
|
假设?会,就进契约;显然的东西、纯基础设施、普通 CRUD 字段,不进(写进去只稀释信噪比、
|
|
增加维护面)。深度上限不是 Lean 的表达力,而是你愿意在每次实现变更时手动回头同步的量。
|
|
进了之后钉到多细,见 `spec/README.md` 的取舍判据。
|
|
|
|
## CI
|
|
|
|
每次 push / PR 在 `spec/` 下跑 `lake build`,确保契约始终 type-check 通过。这是良构 gate,
|
|
见宪法第 2 条。
|