Use + for parameters, ordered-list branches, backtick identifiers, and quoted strings with escapes. Add writeback and subtask host libs, optional parameter defaults, narrative-bold comment fix, and defer view execution until preset stdin is submitted. Co-authored-by: Cursor <cursoragent@cursor.com>
6.5 KiB
6.5 KiB
标准库 L1 模块
| 状态 | 已落地:text/table/fs/sys/time/json/net/math/foreign/plugin |
| 日期 | 2026-08-06 |
| 原则 | 全部经 frontmatter 导入;除 JSON 外中英分文件;内核保持少而精 |
| 相关 | stdlib.md · stdlib-i18n.md · ext-abi.md · ext-llm.md · ext-agent.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 |
已有(含 load_dotenv) |
| 时间 | lib/time.mq.md |
lib/时间.mq.md |
已有 |
| JSON | lib/json.mq.md |
同文件 | 已有(含 quote) |
| 网络 | lib/net.mq.md |
lib/网络.mq.md |
已有(HTTPS + headers) |
| 数学 | lib/math.mq.md |
lib/数学.mq.md |
已有 |
| 外联 | lib/foreign.mq.md |
lib/外联.mq.md |
已有 |
| 插件 | lib/plugin.mq.md |
lib/插件.mq.md |
已有(加载 C ABI 共享库) |
| 自写回 | lib/writeback.mq.md |
lib/自写回.mq.md |
已有(Jupyter 式输出写回) |
| 子任务 | lib/subtask.mq.md |
lib/子任务.mq.md |
已有(OS 子进程 + KillOnDrop) |
官方可选扩展(非 stdlib):ext/llm · ext/agent — 见 ext-llm.md / ext-agent.md。
设计细节:stdlib-writeback.md · stdlib-subtask.md。
2. 分层与实现分工
用户 .mq.md
│ > lib/fs.mq.md / > ext/llm.mq.md
▼
L1 官方库 / 官方 ext(.mq.md)
│
▼
L0.5 宿主原语(Rust)或 原生插件(ABI v1)
│
▼
OS / HTTP / 时钟 / 共享库 …
| 层 | 谁实现 | 用户是否直接调用 |
|---|---|---|
| L0 | 解释器内置 | 是(print/len/…) |
| L0.5 宿主原语 | Rust(src/host/) |
原则上否;供 L1 包装 |
| L1 官方库 | lib/*.mq.md |
是 |
| 官方 ext | ext/*.mq.md(+ 可选 ABI 插件) |
是(需显式导入 ext/) |
3. 核心模块 API(摘要)
文件 / 系统 / 时间 / JSON / 网络 API 见下文历史草图(已实现)。补充:
3.2 系统 — 已含 dotenv
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
load_dotenv |
加载环境 |
可选 path |
新写入的键数量;缺文件 → 0;不覆盖已有环境变量 |
3.4 JSON — 已含 quote
| 函数 | 形参 | 结果 |
|---|---|---|
quote |
text |
JSON 字符串字面量(含引号) |
3.5 网络 — HTTPS
仅 HTTP / HTTPS(ureq);可选 headers=(map)、content_type=。
3.6 插件 — plugin / 插件
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
load |
加载 |
path / 路径 |
注册函数个数 |
unload |
卸载 |
(无) | None |
list |
列出 |
(无) | 已注册名列表 |
契约:ext-abi.md。路径受 cwd/fs_root 沙箱约束。
3.1–3.5 历史 API 草图
文件 — fs / 文件
| 英文 | 中文 | 形参(英 / 中) | 结果 |
|---|---|---|---|
read_text |
读文本 |
path / 路径 |
文本 |
write_text |
写文本 |
path, text / 路径, 内容 |
None |
append_text |
追加文本 |
同上 | None |
exists |
存在 |
path / 路径 |
布尔 |
list_dir |
列目录 |
path / 路径 |
文本列表 |
make_dir |
建目录 |
path / 路径 |
None |
remove |
删除 |
path / 路径 |
None |
系统 — sys / 系统
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
env_get |
取环境 |
name / 名 |
文本或 None |
env_set |
设环境 |
name, value / 名, 值 |
None |
load_dotenv |
加载环境 |
可选 path |
见上 |
args |
参数表 |
(无) | 文本列表 |
cwd |
工作目录 |
(无) | 文本 |
exit |
退出 |
code / 码 |
不返回 |
exec |
执行 |
cmd, 可选 args |
退出码 |
时间 — time / 时间
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
now_unix |
此刻秒 |
(无) | 整数(Unix 秒) |
now_ms |
此刻毫秒 |
(无) | 整数 |
format |
格式化 |
unix, pattern / 秒, 格式 |
文本 |
sleep_ms |
睡眠毫秒 |
ms / 毫秒 |
None |
parse |
解析时间 |
text, pattern / 内容, 格式 |
整数秒或诊断失败 |
JSON — json
| 函数 | 形参 | 结果 |
|---|---|---|
parse |
text |
值 |
stringify |
value, 可选 indent |
JSON 文本 |
get |
value, key |
值或 None |
keys |
value |
文本列表 |
quote |
text |
JSON 字符串字面量 |
网络 — net / 网络
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
http_get |
获取 |
url / 地址 |
响应文本 |
http_post |
提交 |
url, body, 可选 content_type / headers |
同上 |
url_encode |
编码地址 |
text / 内容 |
文本 |
路径字面量: 具名实参里 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.mq.md / 数学.mq.md
foreign.mq.md / 外联.mq.md
plugin.mq.md / 插件.mq.md
ext/ # 非 stdlib
llm.mq.md / 大模型.mq.md
agent.mq.md / 智能体.mq.md
别名:std/… ≡ lib/…。扩展解析:MARQDO_EXT / ./ext / 二进制旁 ext/。
5. 安全与 view / 静态导出
marqdo run、live view、view output 对标准库 默认同一套能力。差异仅在软退出 / sleep 钳制。相对路径落在源文件目录(或 view 根)下,防止 .. 逃逸。插件路径同沙箱。
6. 一句话
L1 含文件 / 系统 / 时间 / JSON / 网络 / 数学 / 外联 / 插件;ext/ 为可选官方扩展(llm、agent)。