67 lines
5.4 KiB
Markdown
67 lines
5.4 KiB
Markdown
# 库源码叙述式重构验收
|
||
|
||
本轮以[可执行开发指南](../library-development.mq.md)为准,覆盖 lib 与 ext 的全部 mq 源码。
|
||
重构前为 117 个文件、1,258 个函数或对象单元;349 个缺少契约,956 条旧显式形参声明。
|
||
完成后为 125 个文件、1,273 个单元。其中 61 份公开标准库保持单文件结构,提供 650 个函数;
|
||
另有 lint 库单元。数据、安全、网络、线性代数和 AI 补齐工程入口,独立多文件职责由 index 组织。
|
||
原工作区阅读器改动及本轮之前的功能实现保留。
|
||
|
||
- [x] 标准库保持单文件,赋值、调用与返回融入叙述,宿主调用有动作说明。
|
||
- [x] 量子、网页的契约紧接标题,入口与叶子采用同一叙述规范。
|
||
- [x] 数据、安全、网络、线性代数补齐契约、输入来源、真实工作流与多文件索引。
|
||
- [x] AI 补齐公开与内部单元的职责说明,解释上下文、路由、工具、工作簿和失败处理。
|
||
- [x] 所有单元移除旧形参,参数与返回表对应真实接口;不以占位工具或固定通过标志验收。
|
||
- [x] 逐函数严格检查叙述超过 50%,行内表达式与绑定数据表仍计作代码。
|
||
- [x] 既有接口与实际行为回归;真实工作流和源码示例在 Tree、Bytecode 执行。
|
||
- [x] 扩展安装清单包含新入口及其源文件依赖,精简构建、WASM 与全量回归通过。
|
||
|
||
源码与工程组织
|
||
|
||
标准库不增加强制 index 或平行手册层。每个函数先给参数与返回契约,再说明输入、
|
||
调用效应、用途、边界与实现。新 table.from_pairs / 表.键值转记录将较宽的具名记录改为
|
||
可读的 key/value 行表;空列表、空值、重复键更新、键顺序与输入不可变性均有双后端验证。
|
||
|
||
拓展库入口解释任务选择、依赖、权限、结果跨步骤传递与开发归属。网页继续采用递归布局:
|
||
首页拆导航、主体、页脚;页脚与链接的双栏继续拆,直到内部只是单一 Markdown 内容职责。
|
||
父 index 只负责一层关系,叶子保留普通正文。已有双语参考站点验证真实嵌套、预览、服务与 API。
|
||
|
||
AI 中的静态提示、目录与工作簿片段改为普通表格数据,保留原字符、字段顺序和换行;
|
||
真正的传输 JSON 仍交给 JSON 库解析。复杂函数解释决策顺序、工具授权、上下文预算、
|
||
事件收集、去重账本和写回责任。中文单步的 sandbox 参数只附加配置行,实际隔离需调用
|
||
CoW 试跑;工具名解析的半角冒号边界也已如实说明。
|
||
|
||
兼容性审核
|
||
|
||
[审核器](../../examples/library_audit.rs)使用真实解析器,对比参数顺序、默认值、对象层级、
|
||
接收者、控制流与计算。遮蔽标签不参与执行;审核只对明确支持的纯常量构造做等价折叠,
|
||
重复 JSON 键、不安全数值、非常量与未知调用均不会被当作等价常量。折叠规则有独立测试。
|
||
原始源码快照保留在本次执行环境的临时目录;它不是另一套工具签名或运行时协议。
|
||
|
||
对比只有三项旧缺陷修复产生的八条 AST 差异,其余既有单元的参数、默认值与规范化执行结构一致。
|
||
[精确修复记录](library-authoring-reviewed-fixes.json)保存差异名称、修复前后摘要与原因;
|
||
审核器只接受摘要完全匹配的记录,新增差异或失效记录都会失败。
|
||
|
||
| 旧问题 | 实际修复与验证 |
|
||
|---|---|
|
||
| 中文单步说明中的斜体 map 被当作提前返回,实现错误落入构造器 | 说明恢复为文字,单步真正执行;离线模型替身验证上下文调用与最终结果 |
|
||
| 事务构造器返回未绑定的 self | 用实际 txn 与 url 构造句柄;验证提交、回滚及事务外读取,不额外开启事务 |
|
||
| 策略说明标题被误认成对象,main 返回未绑定的 routes | 恢复说明与真实 routes 工具,main 调用它;验证 lookup 和默认后端,文件后缀保持文字 |
|
||
|
||
执行证据(2026-11-08)
|
||
|
||
| 检查 | 结果 |
|
||
|---|---|
|
||
| `cargo test --offline --test library_authoring` | 5 项通过;覆盖全部 125 份源码与 1,273 单元、包工作流、旧缺陷、双语记录与安装依赖 |
|
||
| `cargo test --offline --test stdlib_tasks --test quantum_handbook --test web_handbook` | 18 + 4 + 3 项通过;源码中的真实命令与作者程序在双后端运行 |
|
||
| `cargo run --offline --quiet --example stdlib_catalog -- --check` | 650 个公开函数,0 条效应说明需要更新 |
|
||
| AST 原始快照对比及精确修复记录检查 | 8 条已审查修复差异,0 条未解释差异,0 条失效记录 |
|
||
| `GOFLAGS=-buildvcs=false cargo test --offline --all-targets` | 982 通过、0 失败、2 个原有忽略项,包含千文档编译与 312 项金样例 |
|
||
| `cargo check --offline --no-default-features --features wasm-core` | 通过;保留已有未使用代码告警 |
|
||
| 版本匹配工具链的实际 wasm32 构建与 Node 验收 | ABI、桥接、标准库、32 位边界、双语记录、转义表格及句中遮蔽计算通过 |
|
||
| `git diff --check` | 通过 |
|
||
|
||
GOFLAGS 仅用于当前命令绕过工作区所有权引起的 Go VCS 盖章问题,不修改全局配置。
|
||
WASM 使用临时目录中版本匹配的官方工具链;不以本机编译代替真实 wasm 运行。
|
||
网络和身份提供方示例使用离线数据或本机可控服务;没有把构造配置、清单或演示结果
|
||
宣称成生产服务已验证。Node 验收不代表重新完成浏览器 DOM 几何验收。
|