Bind `lang fences like formulas, run them via local interpreters, polish live-view code cards, and refresh bilingual welcome docs. Co-authored-by: Cursor <cursoragent@cursor.com>
8.4 KiB
标准库下一波(L1 扩展模块)
| 状态 | 五库 + 数学已落地;下一波:外联(stdlib-foreign.md) |
| 日期 | 2026-08-05 |
| 本波范围 | 文件 / 系统 / 时间 / JSON / 网络 / 数学(已完成) |
| 下一波 | 外联(本机解释器 / 具名围栏) |
| 暂缓 | — |
| 原则 | 全部经 frontmatter 导入;除 JSON 外中英分文件;内核保持少而精 |
| 相关 | stdlib.md · stdlib-i18n.md · keywords-i18n.md · view.md |
1. 目标
在现有 lib/text·lib/文本、lib/table·lib/表 之上,把 Marqdo 推进到可写日常脚本。标准库必须导入才可用。
| 模块族 | 英文库 | 中文库 | 本波 |
|---|---|---|---|
| 文本(已有) | lib/text.mq.md |
lib/文本.mq.md |
已有 |
| 表(已有) | lib/table.mq.md |
lib/表.mq.md |
已有 |
| 文件 | lib/fs.mq.md |
lib/文件.mq.md |
做 |
| 系统 | lib/sys.mq.md |
lib/系统.mq.md |
做 |
| 时间 | lib/time.mq.md |
lib/时间.mq.md |
做 |
| JSON | lib/json.mq.md |
同文件(特例,§3.4) | 做 |
| 网络(简) | lib/net.mq.md |
lib/网络.mq.md |
做 |
| 数学 | lib/math.mq.md |
lib/数学.mq.md |
下一波 |
| 外联 | lib/foreign.mq.md |
lib/外联.mq.md |
做 |
2. 分层与实现分工
用户 .mq.md
│ > lib/fs.mq.md
▼
L1 官方库(.mq.md)
│
▼
L0.5 宿主原语(Rust,英文蛇形)
│
▼
OS / HTTP / 时钟 / …
| 层 | 谁实现 | 用户是否直接调用 |
|---|---|---|
| L0 | 解释器内置 | 是(print/len/…) |
| L0.5 宿主原语 | Rust(src/builtin 或 src/host/) |
原则上否;供 L1 包装;金样例可直测 |
| L1 官方库 | lib/*.mq.md |
是(文档与用户站只教这一层) |
规则:
- 导入即选择语言(JSON 除外):
lib/fs.mq.md→ 英文 API;lib/文件.mq.md→ 中文 API(见 stdlib-i18n.md)。 - 不设
lang:。 - 宿主原语保持英文;中英差异只存在于 L1 包装层(JSON 无第二套包装)。
- 失败一律
path:line:col: message(stdlib.md §4)。
3. 核心模块 API 草图(L1)
3.1 文件 — fs / 文件
| 英文 | 中文 | 形参(英 / 中) | 结果 |
|---|---|---|---|
read_text |
读文本 |
path / 路径 |
文本 |
write_text |
写文本 |
path, text / 路径, 内容 |
None |
append_text |
追加文本 |
同上 | None |
exists |
存在 |
path / 路径 |
布尔 |
list_dir |
列目录 |
path / 路径 |
文本列表 |
make_dir |
建目录 |
path / 路径 |
None |
remove |
删除 |
path / 路径 |
None |
约定:路径相对工作目录或绝对路径;二进制 I/O 本波不做;写/删默认需 --allow-fs-write(§6)。
3.2 系统 — sys / 系统
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
env_get |
取环境 |
name / 名 |
文本或 None |
env_set |
设环境 |
name, value / 名, 值 |
None |
args |
参数表 |
(无) | 文本列表 |
cwd |
工作目录 |
(无) | 文本 |
exit |
退出 |
code / 码 |
不返回 |
exec |
执行 |
cmd, 可选 args |
退出码(实现时写死语义) |
exec 默认关(--allow-exec);view / 静态站永不开放。
3.3 时间 — time / 时间
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
now_unix |
此刻秒 |
(无) | 整数(Unix 秒) |
now_ms |
此刻毫秒 |
(无) | 整数 |
format |
格式化 |
unix, pattern / 秒, 格式 |
文本 |
sleep_ms |
睡眠毫秒 |
ms / 毫秒 |
None |
parse |
解析时间 |
text, pattern / 内容, 格式 |
整数秒或诊断失败 |
view 中 sleep_ms 设上限(如 5s)。
3.4 JSON — json(中英同库特例)
JSON 是专有缩写,很难也不必要做合规中文库名/API 翻译。本波定稿:
| 项 | 约定 |
|---|---|
| 唯一路径 | lib/json.mq.md(中英文档均导入此路径) |
| 函数名 | 国际通行英文:parse / stringify / get / keys |
| 形参 | 英文:text / value / key / indent |
| 不设 | lib/数据.mq.md、音译名、中文函数双份 |
这是对 stdlib-i18n.md「一概念两文件」的显式例外;其它模块仍中英分文件。
| 函数 | 形参 | 结果 |
|---|---|---|
parse |
text |
值(见下) |
stringify |
value, 可选 indent |
JSON 文本 |
get |
value, key |
值或 None |
keys |
value |
文本列表 |
类型映射(草案):
| JSON | Marqdo Value |
|---|---|
null |
None |
| bool | bool |
| number(整数可表) | int |
| number(其余) | 文本(本波不引入 float)或诊断拒绝 |
| string | text |
| array | list |
| object | 倾向新宿主类型 map(type → map);否则体验差 |
map 为 L0.5 类型扩展,可与 json 同期或紧随;不阻塞 fs/time 先行。
3.5 网络(简)— net / 网络
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
http_get |
获取 |
url / 地址 |
响应文本(或 map:status/body) |
http_post |
提交 |
url, body, 可选 content_type |
同上 |
url_encode |
编码地址 |
text / 内容 |
文本 |
仅 HTTP 明文(HTTPS 本波未做,会诊断提示);短超时、响应体上限;默认需 --allow-net;view / 静态站默认关。
路径字面量: 具名实参里 path=a/b 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
4. 中英路径总表(本波)
lib/
text.mq.md / 文本.mq.md # 已有
table.mq.md / 表.mq.md # 已有
fs.mq.md / 文件.mq.md # 本波
sys.mq.md / 系统.mq.md
time.mq.md / 时间.mq.md
json.mq.md # 本波;中英共用,无第二文件
net.mq.md / 网络.mq.md
# 暂缓:math / 数学 · foreign / 外联
别名:std/… ≡ lib/…。
5. 落地分期(本波 = M1–M5)
| 期 | 内容 | 完成定义 |
|---|---|---|
| M1 | 宿主能力框架:权限旗标、host 分发、错误文案 |
--allow-* 可测 |
| M2 | fs + time(只读 fs + 时钟) |
中英库 + 金样例 |
| M3 | sys(env/cwd/args;exec 默认关) |
同上 |
| M4 | json(+ 可选 map) |
往返金样例;唯 lib/json.mq.md |
| M5 | net(默认关) |
本地 mock 或录制夹具 |
不做 M6/M7(数学 / 外联):详稿仅存档,待五库稳定后再议。
文档站:fs/sys/time/net 英中各一页;json 可一页双语叙述、同一导入路径。
6. 安全与 view / 静态导出
6.1 行为一致
marqdo run、live view、view output 对标准库 默认同一套能力(读/写盘、HTTP、exec 均可用)。导入库即表示要用;不再要求 --allow-*。
差异仅在 软退出:
CLI run |
view / capture / 静态导出 | |
|---|---|---|
exit |
结束进程 | 报诊断,不杀 view/构建进程 |
sleep_ms |
默认可睡(有上限) | live 有上限;导出通常为 0 |
沙箱:相对路径落在源文件目录(或 view 根)下,防止 .. 逃逸。
6.2 静态部署
访客浏览器 不再执行 Marqdo;HTML 里是构建时冻结的输出。源码中的路径/URL 访客改不了、也触发不了新的 host 调用。审 PR 时审查写死的目标即可。
勿在静态页嵌入「用户可改 URL 再请求」的浏览器脚本。
7. 与现有库的关系
text/table继续纯包装、无 IO。- JSON
stringify≠str(显示)。
8. 刻意不做(本波)
- 数学库、外联/胶水库(及其依赖、权限旗标实现)。
- 数据库、异步事件循环、WebSocket、原始 TCP。
- float/复数进 L0。
lang:或按 locale 自动选库。- 为 JSON 强造中文库名或中文 API 双份。
9. 一句话
本波只落地文件 / 系统 / 时间 / JSON / 网络;JSON 中英共用 lib/json.mq.md;数学与外联暂缓。