Files
marqdo/doc/roadmap/stdlib-executable-handbook.md

61 lines
5.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 标准库:可执行手册与通用能力闭环
目标:代码即文档,文档即 SKILL,SKILL 即 tools。AI 直接阅读任务对应的 `lib/*.mq.md` 单文件,理解输入来源、输出形态、效应、失败处理和可执行示例;保持既有导入兼容。
本清单记录真实交付状态,未完成项不能因文档或接口占位而标为完成。
## 阶段与验收
- [x] A. 宿主效应作为唯一事实来源;直调、导入别名、中英文和双后端一致。
- [x] A. `call` 明确授权文件读写及根目录;会话重放保留权限范围。
- [x] A. 明确递归删除、索引基数、不可变更新、结构化可恢复错误契约。
- [x] B. 文件筛选、行/JSON/CSV 读写、目录树复制、批量改名/同步及冲突策略。
- [x] B. 原子/条件写入、临时目录与清理、路径相对化与扩展名替换。
- [x] C. 序列、投影、筛选、分组/聚合、连接、按键去重/多键排序和表形态转换。
- [x] C. 字段类型转换与记录校验;避免回调字符串求值及新集合方言。
- [x] D. 字节与分块 IO、文件哈希、网络下载、压缩归档及明确资源上限。
- [x] D. HTTP 响应头、可配置超时、一致的错误结果;保留既有入口兼容。
- [x] E. 子任务超时、并发上限、批量取消与资源回收。
- [x] E. 日期完整时区/DST、配置读写边界、规模性能。
- [x] F. 文档章节/表格/代码块/链接提取和保留叙述的受控局部修改,复用解析器。
- [x] G. 全标准库单文件手册、标题下参数表、叙述形参和遮蔽调用;叙述超过 50%;提供契约与真实示例;不以伪函数或叙述比例代替正确性。
- [x] G. 三个端到端工程:文件整理、CSV 数据处理、文档维护;示例直接提取执行。
- [x] G. 相关回归、双后端、默认/最小特性构建及平台能力矩阵。
## 实施约束
保留工作区已有的 reader 改动。通用组合优先 `.mq.md`,OS/算法边界使用小型宿主原语;
不增加第二套 Skill 编译器、字符串 eval 或应用模板语法。递归删除保留旧入口行为,
新增清晰的窄接口;每次修改都同时写清兼容性和失败语义。
## 验证记录
按用户澄清修正为 31 个模块族、61 份公开标准库单文件;撤除先前误增的 64 份目录与模块手册。648 个公开函数的名称、参数顺序和默认值 AST 与迁移前逐项一致;不再保留旧 + 形参。源码中的实际调用在 Tree 与 Bytecode 共执行 126 次,并检查操作结果。17 项标准库工程测试通过;所有函数的叙述比例均超过 50%。
先前能力实现的验证记录如下;单文件结构与遮蔽调用修正后的全量复验记录在表后追加。
| 验证 | 真实结果 |
|---|---|
| `GOFLAGS=-buildvcs=false cargo test --offline --all-targets` | 首次全量 967 通过、0 失败、2 个原有忽略项,包含千文档编译测试 |
| `GOFLAGS=-buildvcs=false cargo test --offline --all-targets -- --skip v3_corpus_1000_compile_smoke` | 结构修正前回归 968 通过、0 失败、2 个原有忽略项;跳过的千文档测试已在首次全量通过,合计覆盖 969 个不同通过项 |
| `cargo check --offline --no-default-features --features wasm-core` | 通过;保留已有未使用代码告警 |
| `cargo run --offline --quiet --example stdlib_catalog -- --check` | 0 条源码效应说明需要更新 |
| `cargo check/build --offline -p marqdo-wasm --target wasm32-unknown-unknown` | 使用临时目录内版本匹配的官方工具链通过 |
| `node tests/wasm/smoke.mjs <wasm产物>` | ABI 与桥接通过 |
| `node tests/wasm/stdlib.mjs <wasm产物>` | 集合、字节、文档、TOML、IANA/DST 与 32 位边界通过 |
| `git diff --check` | 通过 |
最终全量回归包含 17 项标准库工程测试。`GOFLAGS` 仅对本次命令关闭工作区所有权导致的 Go VCS 盖章失败,不修改全局 Git 配置。wasm 检查和运行使用同一构建产物,Node 验收不代表浏览器 DOM 布局验收。
单文件结构与遮蔽调用修正后的复验:
- `GOFLAGS=-buildvcs=false cargo test --offline --all-targets`:970 通过、0 失败、2 个原有忽略项,包含千文档编译、312 项金样例及 17 项标准库工程测试。
- 61 份公开源码包含 63 条真实命令,Tree 与 Bytecode 共执行 126 次;操作返回 Result 时同时检查其 ok。
- 648 个函数的名称、参数顺序与默认值 AST 逐项保持一致;每个函数叙述均超过 50%,标题下有完整契约,且不再保留旧形参。
- 编译器效应检查:0 条源码效应说明需要更新;--json 直接输出 648 条真实接口记录。
- 精简 wasm-core 构建通过;当前源码重新构建的 wasm32 产物通过 ABI、桥接和标准库 Node 运行验证。
- `git diff --check` 通过。保留原有 reader 工作区修改。
删除旧形参后,沿用现有叙述形参推断;修复引号内星号、分号、空格被误作默认值边界的问题,并增加扫描回归测试。宿主调用的遮蔽标签不参与执行,诊断测试继续穿过标签定位真实指令和独立调用点。
[设计与能力边界](../design/stdlib-handbook.md)记录平台能力矩阵、兼容索引基数、资源上限、CoW 限制、目录复制范围、条件写入并发边界及线程取消语义。这些边界均为明确契约,不以占位实现宣称支持。保留工作区既有 reader 改动。