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

5.4 KiB

标准库:可执行手册与通用能力闭环

目标:代码即文档,文档即 SKILL,SKILL 即 tools。AI 直接阅读任务对应的 lib/*.mq.md 单文件,理解输入来源、输出形态、效应、失败处理和可执行示例;保持既有导入兼容。 本清单记录真实交付状态,未完成项不能因文档或接口占位而标为完成。

阶段与验收

  • A. 宿主效应作为唯一事实来源;直调、导入别名、中英文和双后端一致。
  • A. call 明确授权文件读写及根目录;会话重放保留权限范围。
  • A. 明确递归删除、索引基数、不可变更新、结构化可恢复错误契约。
  • B. 文件筛选、行/JSON/CSV 读写、目录树复制、批量改名/同步及冲突策略。
  • B. 原子/条件写入、临时目录与清理、路径相对化与扩展名替换。
  • C. 序列、投影、筛选、分组/聚合、连接、按键去重/多键排序和表形态转换。
  • C. 字段类型转换与记录校验;避免回调字符串求值及新集合方言。
  • D. 字节与分块 IO、文件哈希、网络下载、压缩归档及明确资源上限。
  • D. HTTP 响应头、可配置超时、一致的错误结果;保留既有入口兼容。
  • E. 子任务超时、并发上限、批量取消与资源回收。
  • E. 日期完整时区/DST、配置读写边界、规模性能。
  • F. 文档章节/表格/代码块/链接提取和保留叙述的受控局部修改,复用解析器。
  • G. 全标准库单文件手册、标题下参数表、叙述形参和遮蔽调用;叙述超过 50%;提供契约与真实示例;不以伪函数或叙述比例代替正确性。
  • G. 三个端到端工程:文件整理、CSV 数据处理、文档维护;示例直接提取执行。
  • 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 工作区修改。

删除旧形参后,沿用现有叙述形参推断;修复引号内星号、分号、空格被误作默认值边界的问题,并增加扫描回归测试。宿主调用的遮蔽标签不参与执行,诊断测试继续穿过标签定位真实指令和独立调用点。

设计与能力边界记录平台能力矩阵、兼容索引基数、资源上限、CoW 限制、目录复制范围、条件写入并发边界及线程取消语义。这些边界均为明确契约,不以占位实现宣称支持。保留工作区既有 reader 改动。