From a53ebb65eed8fec9c637c01a04a931a36fcf16cc Mon Sep 17 00:00:00 2001 From: cflmy Date: Wed, 5 Aug 2026 10:03:54 +0800 Subject: [PATCH] Add host stdlib modules and unify view/run capabilities. Ship fs/time/sys/json/net L1 libs (plus existing text/table), default-on host caps with soft exit under view, bilingual public/stdlib docs, and design notes for deferred math/foreign. Co-authored-by: Cursor --- Cargo.lock | 277 ++++++++++++++++++++++++++++++++ Cargo.toml | 2 + doc/README.md | 3 + doc/design/stdlib-foreign.md | 207 ++++++++++++++++++++++++ doc/design/stdlib-i18n.md | 34 ++-- doc/design/stdlib-math.md | 181 +++++++++++++++++++++ doc/design/stdlib-modules.md | 227 ++++++++++++++++++++++++++ doc/design/stdlib.md | 19 ++- doc/design/view.md | 1 + doc/roadmap/next-phase.md | 2 +- lib/fs.mq.md | 41 +++++ lib/json.mq.md | 25 +++ lib/net.mq.md | 20 +++ lib/sys.mq.md | 33 ++++ lib/time.mq.md | 29 ++++ lib/文件.mq.md | 41 +++++ lib/时间.mq.md | 29 ++++ lib/系统.mq.md | 33 ++++ lib/网络.mq.md | 20 +++ public/00-welcome.mq.md | 2 +- public/00-欢迎.mq.md | 2 +- public/README.md | 20 ++- public/stdlib/00-overview.mq.md | 18 +++ public/stdlib/00-索引.mq.md | 18 +++ public/stdlib/fs.mq.md | 18 +++ public/stdlib/json.mq.md | 19 +++ public/stdlib/net.mq.md | 13 ++ public/stdlib/sys.mq.md | 18 +++ public/stdlib/table.mq.md | 24 +++ public/stdlib/text.mq.md | 19 +++ public/stdlib/time.mq.md | 19 +++ public/stdlib/文件.mq.md | 18 +++ public/stdlib/文本.mq.md | 19 +++ public/stdlib/时间.mq.md | 19 +++ public/stdlib/系统.mq.md | 18 +++ public/stdlib/网络.mq.md | 13 ++ public/stdlib/表.mq.md | 24 +++ src/aliases.rs | 3 + src/builtin.rs | 3 +- src/bytecode/compile.rs | 39 +++++ src/bytecode/mod.rs | 2 + src/bytecode/vm.rs | 39 +++++ src/host/dispatch.rs | 227 ++++++++++++++++++++++++++ src/host/fs.rs | 108 +++++++++++++ src/host/json.rs | 106 ++++++++++++ src/host/mod.rs | 126 +++++++++++++++ src/host/net.rs | 152 ++++++++++++++++++ src/host/sys.rs | 79 +++++++++ src/host/time.rs | 71 ++++++++ src/interp.rs | 24 +++ src/lib.rs | 77 ++++++++- src/main.rs | 1 + src/value.rs | 4 + src/view/mod.rs | 16 +- src/view/output.rs | 2 +- tests/gold.rs | 42 +++++ tests/lib/fixtures/hello.txt | 1 + tests/lib/fixtures/sample.json | 1 + tests/lib/fs-read.mq.md | 17 ++ tests/lib/hello.txt | 1 + tests/lib/json-roundtrip.mq.md | 23 +++ tests/lib/net-encode.mq.md | 10 ++ tests/lib/sample.json | 1 + tests/lib/sys-cwd.mq.md | 15 ++ tests/lib/time-format.mq.md | 16 ++ tests/lib/文件-读.mq.md | 17 ++ 66 files changed, 2703 insertions(+), 45 deletions(-) create mode 100644 doc/design/stdlib-foreign.md create mode 100644 doc/design/stdlib-math.md create mode 100644 doc/design/stdlib-modules.md create mode 100644 lib/fs.mq.md create mode 100644 lib/json.mq.md create mode 100644 lib/net.mq.md create mode 100644 lib/sys.mq.md create mode 100644 lib/time.mq.md create mode 100644 lib/文件.mq.md create mode 100644 lib/时间.mq.md create mode 100644 lib/系统.mq.md create mode 100644 lib/网络.mq.md create mode 100644 public/stdlib/00-overview.mq.md create mode 100644 public/stdlib/00-索引.mq.md create mode 100644 public/stdlib/fs.mq.md create mode 100644 public/stdlib/json.mq.md create mode 100644 public/stdlib/net.mq.md create mode 100644 public/stdlib/sys.mq.md create mode 100644 public/stdlib/table.mq.md create mode 100644 public/stdlib/text.mq.md create mode 100644 public/stdlib/time.mq.md create mode 100644 public/stdlib/文件.mq.md create mode 100644 public/stdlib/文本.mq.md create mode 100644 public/stdlib/时间.mq.md create mode 100644 public/stdlib/系统.mq.md create mode 100644 public/stdlib/网络.mq.md create mode 100644 public/stdlib/表.mq.md create mode 100644 src/host/dispatch.rs create mode 100644 src/host/fs.rs create mode 100644 src/host/json.rs create mode 100644 src/host/mod.rs create mode 100644 src/host/net.rs create mode 100644 src/host/sys.rs create mode 100644 src/host/time.rs create mode 100644 tests/lib/fixtures/hello.txt create mode 100644 tests/lib/fixtures/sample.json create mode 100644 tests/lib/fs-read.mq.md create mode 100644 tests/lib/hello.txt create mode 100644 tests/lib/json-roundtrip.mq.md create mode 100644 tests/lib/net-encode.mq.md create mode 100644 tests/lib/sample.json create mode 100644 tests/lib/sys-cwd.mq.md create mode 100644 tests/lib/time-format.mq.md create mode 100644 tests/lib/文件-读.mq.md diff --git a/Cargo.lock b/Cargo.lock index 76ff9ee..0de2e54 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -11,6 +11,15 @@ dependencies = [ "memchr", ] +[[package]] +name = "android_system_properties" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311" +dependencies = [ + "libc", +] + [[package]] name = "anstream" version = "0.6.21" @@ -111,6 +120,39 @@ dependencies = [ "serde_core", ] +[[package]] +name = "bumpalo" +version = "3.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" + +[[package]] +name = "cc" +version = "1.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cfg-if" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" + +[[package]] +name = "chrono" +version = "0.4.45" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327" +dependencies = [ + "iana-time-zone", + "num-traits", + "windows-link", +] + [[package]] name = "chunked_transfer" version = "1.5.0" @@ -163,6 +205,12 @@ version = "1.0.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570" +[[package]] +name = "core-foundation-sys" +version = "0.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" + [[package]] name = "difflib" version = "0.4.0" @@ -175,6 +223,12 @@ version = "0.3.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "780955b8b195a21ab8e4ac6b60dd1dbdcec1dc6c51c0617964b08c81785e12c9" +[[package]] +name = "find-msvc-tools" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582" + [[package]] name = "float-cmp" version = "0.9.0" @@ -184,6 +238,30 @@ dependencies = [ "num-traits", ] +[[package]] +name = "futures-core" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7" + +[[package]] +name = "futures-task" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109" + +[[package]] +name = "futures-util" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa" +dependencies = [ + "futures-core", + "futures-task", + "pin-project-lite", + "slab", +] + [[package]] name = "getopts" version = "0.2.24" @@ -205,12 +283,53 @@ version = "1.0.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9" +[[package]] +name = "iana-time-zone" +version = "0.1.65" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470" +dependencies = [ + "android_system_properties", + "core-foundation-sys", + "iana-time-zone-haiku", + "js-sys", + "log", + "wasm-bindgen", + "windows-core", +] + +[[package]] +name = "iana-time-zone-haiku" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f" +dependencies = [ + "cc", +] + [[package]] name = "is_terminal_polyfill" version = "1.70.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695" +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "js-sys" +version = "0.3.103" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102" +dependencies = [ + "cfg-if", + "futures-util", + "wasm-bindgen", +] + [[package]] name = "libc" version = "0.2.189" @@ -229,9 +348,11 @@ version = "0.0.3" dependencies = [ "anyhow", "assert_cmd", + "chrono", "clap", "predicates", "pulldown-cmark", + "serde_json", "thiserror", "tiny_http", ] @@ -257,12 +378,24 @@ dependencies = [ "autocfg", ] +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + [[package]] name = "once_cell_polyfill" version = "1.70.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe" +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + [[package]] name = "predicates" version = "3.1.0" @@ -359,6 +492,21 @@ version = "0.8.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", +] + [[package]] name = "serde_core" version = "1.0.229" @@ -379,6 +527,31 @@ dependencies = [ "syn 3.0.3", ] +[[package]] +name = "serde_json" +version = "1.0.151" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + [[package]] name = "strsim" version = "0.10.0" @@ -478,12 +651,110 @@ dependencies = [ "libc", ] +[[package]] +name = "wasm-bindgen" +version = "0.2.126" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4" +dependencies = [ + "cfg-if", + "once_cell", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.126" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.126" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 2.0.119", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.126" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "windows-core" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb" +dependencies = [ + "windows-implement", + "windows-interface", + "windows-link", + "windows-result", + "windows-strings", +] + +[[package]] +name = "windows-implement" +version = "0.60.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-interface" +version = "0.59.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "windows-link" version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-strings" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091" +dependencies = [ + "windows-link", +] + [[package]] name = "windows-sys" version = "0.61.2" @@ -492,3 +763,9 @@ checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" dependencies = [ "windows-link", ] + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/Cargo.toml b/Cargo.toml index 5de00d0..1d7d927 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -13,8 +13,10 @@ path = "src/main.rs" [dependencies] anyhow = "1" +chrono = { version = "0.4", default-features = false, features = ["clock", "std"] } clap = { version = "=4.4.18", features = ["derive"] } pulldown-cmark = "0.12" +serde_json = "1" thiserror = "1" tiny_http = "0.12" diff --git a/doc/README.md b/doc/README.md index a844724..f138af8 100644 --- a/doc/README.md +++ b/doc/README.md @@ -26,6 +26,9 @@ | [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** | | [design/stdlib.md](design/stdlib.md) | **P2 标准库:内置 + `lib/` + 错误约定** | | [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** | +| [design/stdlib-modules.md](design/stdlib-modules.md) | **本波 L1:文件/系统/时间/JSON/网络(JSON 中英同库)** | +| [design/stdlib-math.md](design/stdlib-math.md) | **暂缓:数学库(数值/符号/作图/`$$`)** | +| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **暂缓:外联胶水(\`\`\`lang 具名块)** | | [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** | | [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** | | [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** | diff --git a/doc/design/stdlib-foreign.md b/doc/design/stdlib-foreign.md new file mode 100644 index 0000000..0a98bb5 --- /dev/null +++ b/doc/design/stdlib-foreign.md @@ -0,0 +1,207 @@ +# 外联 / 胶水标准库(候选) + +| | | +|---|---| +| 状态 | **草案 / 暂缓**(本波不实现;五库之后再议) | +| 日期 | 2026-08-05 | +| 相关 | [stdlib-modules.md](stdlib-modules.md) · [code-vs-comment.md](code-vs-comment.md) · [markdown-mapping.md](markdown-mapping.md) · [stdlib-math.md](stdlib-math.md) | +| 灵感 | Markdown \`\`\`lang 代码块;Marqdo 作编排层 | + +--- + +## 1. 为什么值得做 + +[code-vs-comment.md](code-vs-comment.md) 已划出**外联面**:\`\`\`lang 是「其它语言」。若运行时能: + +1. **收集**本文件(或导入图)中的围栏代码块; +2. 按语言 **subprocess / 嵌入运行时**执行; +3. 把 stdout / 约定返回值 **接回 Marqdo 值**; + +则 Marqdo 成为**文学化胶水语言**:结构、叙述、分支循环用 Marqdo,重活交给 Python/JS/Shell/SQL。 + +风险:安全(任意代码)、可复现(环境漂移)、view/CI(无解释器)——故为**候选**,默认关闭。 + +--- + +## 2. 与叙述面的边界 + +| 面 | 行为 | +|----|------| +| 叙述段里的 \`\`\` | 今日:注释;**外联库启用后仍可配置为「可调用」或「仅展示」** | +| 可执行面附近的 \`\`\` | 建议:**具名块**才可调用,避免误跑文档里的示例 | + +推荐:**只有带名字的围栏**进入外联目录。 + +--- + +## 3. 命名围栏语法(草案) + +三种候选(实现前锁定一种): + +### 3.1 信息串后缀(推荐试水) + +````markdown +```python name=normalize +def normalize(s): + return s.strip().lower() +``` +```` + +或: + +````markdown +```python#normalize +… +``` +```` + +### 3.2 HTML 注释锚点 + +````markdown + +```python +… +``` +```` + +### 3.3 紧邻 Marqdo 声明 + +```markdown +*`normalize` = foreign_def lang=python * + +```python +… +``` +``` + +**倾向 3.1**:仍是合法 Markdown,多数渲染器忽略未知 info 字段;与「文档即源」一致。 + +未命名围栏:view 可语法高亮展示,**不可** `foreign_call`。 + +--- + +## 4. 导入与 API + +| 导入 | API 语言 | +|------|----------| +| `> lib/foreign.mq.md` | 英文 | +| `> lib/外联.mq.md` | 中文 | + +| 英文 | 中文 | 形参 | 结果 | +|------|------|------|------| +| `run` | `运行` | `name`, 可选 `stdin` / `名`, `标准输入` | 文本(stdout) | +| `run_lang` | `按语言运行` | `lang`, `source`, 可选 `stdin` | 文本 | +| `call` | `调用` | `name`, 可选 `args`(JSON 文本) | 文本 | +| `langs` | `语言表` | (无) | 已注册语言列表 | + +`call` 约定(v1): + +- 宿主把 `args` 经环境变量或临时 JSON 文件传给子进程; +- 被调代码打印**一行 JSON** 到 stdout 作为返回值; +- 或退出码非 0 → Marqdo 诊断。 + +更紧的 Python 嵌入(`pyo3`)列为后期优化,**v1 只用子进程**,便于推理安全边界。 + +--- + +## 5. 语言支持矩阵(v1) + +| 语言 | 探测 | 备注 | +|------|------|------| +| `python` / `python3` | `PATH` | 优先实现;服务科学计算与 [stdlib-math.md](stdlib-math.md) CAS 外置 | +| `node` / `javascript` | `PATH` | 第二 | +| `sh` / `bash` | Unix;Windows 可用 Git Bash 或跳过 | 高风险,默认更严 | +| `cmd` / `powershell` | Windows | 可选 | +| 其它 | 配置表 | `marqdo.toml` / 环境变量注册解释器路径 | + +无解释器时:清晰诊断 `foreign language not available: python`,而非静默跳过。 + +--- + +## 6. 权限模型(硬性) + +| 场景 | 默认 | +|------|------| +| `marqdo run` | **拒绝**,除非 `--allow-foreign` | +| `marqdo view` | 拒绝(或仅 `--allow-foreign` 的本地演示) | +| `view output` / CI 用户站 | **拒绝**(文档示例用录制输出或纯 Marqdo) | +| 金样例 | 用 `tests/foreign/` + 环境探测;无 Python 则 `ignore` | + +附加约束(可组合): + +- `--foreign-lang python,node` 白名单; +- 超时(默认 5–30s); +- 工作目录锁在文件所在根; +- 无网络(与 `--allow-net` 分离;子进程环境可剥 `HTTP_PROXY` 等——尽力而为)。 + +--- + +## 7. 典型胶水故事 + +```markdown +--- +title: Normalize names +> lib/foreign.mq.md +> lib/fs.mq.md +--- + +```python name=normalize +import sys +print(sys.stdin.read().strip().lower()) +``` + +# main + +*`raw` = > read_text path=names.txt * +*`clean` = > run name=normalize stdin=`raw` * +> print text=`clean` +``` + +中文轨: + +```markdown +--- +> lib/外联.mq.md +> lib/文件.mq.md +--- +``` + +叙述说明用中文;围栏内语言仍是 Python——**外联块语言 ≠ Marqdo API 语言**。 + +--- + +## 8. 与数学库的关系 + +- 厚 CAS(SymPy)**优先**走外联,而不是塞进默认 `lib/math`。 +- 官方可提供可选示例:`examples/math-sympy.mq.md`(要求 Python + `--allow-foreign`)。 +- 数值与 SVG 仍留在数学库,保证无 Python 时可教可演示。 + +--- + +## 9. 是否定为「标准库」的决策标准 + +纳入默认 `lib/foreign` 当且仅当: + +1. 权限模型在 CLI/view/CI 测全; +2. 至少一种语言金样例在 CI 稳定(或正式 `#[ignore]` 策略); +3. 文档明确「胶水能力默认关闭,不是网页 RCE」。 + +若短期内无法保证安全叙事 → 放在 `lib/experimental/foreign` 或 feature `foreign`,用户站不放可点击「运行外联」的按钮。 + +--- + +## 10. 实现分期 + +| 期 | 内容 | +|----|------| +| F0 | 词法:收集命名围栏 → 模块表(尚不执行) | +| F1 | `run` + Python 子进程 + 权限旗标 | +| F2 | `call` JSON 约定;超时与 cwd 锁 | +| F3 | Node;view 展示块与「需 CLI 权限」提示 | +| F4 | 可选嵌入运行时、与 math-cas 示例合流 | + +--- + +## 11. 一句话 + +**\`\`\`lang 是外联面的源,不是自动执行的陷阱;具名块 + 显式导入 + 默认拒绝权限,才能把 Marqdo 做成安全可讲的胶水语言。** diff --git a/doc/design/stdlib-i18n.md b/doc/design/stdlib-i18n.md index 0325211..62c5502 100644 --- a/doc/design/stdlib-i18n.md +++ b/doc/design/stdlib-i18n.md @@ -5,7 +5,7 @@ | 状态 | **草案(先文档、后实现)** | | 日期 | 2026-08-04 | | 原则 | **不指定语言**;靠**库文件名**区分中英(及日后其它语言) | -| 相关 | [stdlib.md](stdlib.md) · [keywords.md](keywords.md) · [keywords-i18n.md](keywords-i18n.md) · [user-site.md](user-site.md) | +| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [keywords.md](keywords.md) · [keywords-i18n.md](keywords-i18n.md) · [user-site.md](user-site.md) | --- @@ -76,12 +76,24 @@ --- +## 2.4 特例:JSON + +`JSON` 为专有缩写,**不强求**中文库名或中文 API 翻译。官方只提供: + +```text +lib/json.mq.md # 中英文档均 `> lib/json.mq.md`;函数 parse / stringify / get / keys +``` + +不设 `lib/数据.mq.md` 等平行文件。其余模块仍遵守 §2.1。详见 [stdlib-modules.md](stdlib-modules.md) §3.4。 + +--- + ## 3. 与「少而精内置」的边界 | 层 | 内容 | 如何获得 | |----|------|----------| | **内置(L0)** | 极少:`print` `input` `len` `str` `int`(及语言字面量关键字) | 直接调用,无需导入 | -| **标准库(L1)** | 文本/表等扩展 API;**中英各一套文件、各一套函数名** | frontmatter `> lib/…` | +| **标准库(L1)** | 文本/表等扩展 API;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `> lib/…` | | **宿主原语(实现细节)** | 若 `trim`/`split` 等暂由解释器实现 | 仅供标准库包装调用;**文档与用户站引导走 L1**,不鼓励当「关键字」堆砌 | 日后若某能力足够「核心」,可再升格为 L0;升格前先留在 L1。 @@ -92,11 +104,11 @@ ```text lib/ - text.mq.md # 英文文本库 - 文本.mq.md # 中文文本库 - table.mq.md # 英文表库 - 表.mq.md # 中文表库 - # 日后:texte.mq.md / テキスト.mq.md … + text.mq.md / 文本.mq.md + table.mq.md / 表.mq.md + # 本波:fs/文件 · sys/系统 · time/时间 · json(中英同文件)· net/网络 + # 暂缓:math/数学 · foreign/外联 + # 其它语言:texte.mq.md / テキスト.mq.md … ``` 扩展新语言时: @@ -111,9 +123,9 @@ lib/ ## 5. 文档与示例义务 -- 用户站:英文库、中文库各给一页(或同页两小节),导入路径与调用名并排出现。 -- 金样例:`tests/…` 中英导入至少各一条,避免只测中文或只测英文。 -- [keywords.md](keywords.md) 只列 L0;L1 指向本文 + [stdlib.md](stdlib.md)。 +- 用户站:英/中库各一页(或同页两小节),导入路径与调用名并排;**JSON** 可共用一页、同一导入。 +- 金样例:分文件模块中英导入至少各一条;JSON 测 `lib/json.mq.md` 即可。 +- [keywords.md](keywords.md) 只列 L0;L1 指向本文 + [stdlib.md](stdlib.md) + [stdlib-modules.md](stdlib-modules.md)。 --- @@ -131,4 +143,4 @@ lib/ ## 7. 一句话 -**标准库用文件名区分语言;英文库名进英文 API,中文库名进中文 API——导入即选择,无语言开关。** +**标准库用文件名区分语言(导入即选择);JSON 为缩写特例,中英共用 `lib/json.mq.md`——无语言开关。** diff --git a/doc/design/stdlib-math.md b/doc/design/stdlib-math.md new file mode 100644 index 0000000..91e9fb9 --- /dev/null +++ b/doc/design/stdlib-math.md @@ -0,0 +1,181 @@ +# 数学标准库(候选) + +| | | +|---|---| +| 状态 | **草案 / 暂缓**(本波不实现;五库之后再议) | +| 日期 | 2026-08-05 | +| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [view.md](view.md) · [markdown-mapping.md](markdown-mapping.md) | +| 灵感 | Markdown `$$…$$` / `$…$` 公式面;文档即计算笔记本 | + +--- + +## 1. 为什么值得做 + +Markdown 读者已习惯用 `$$` 写公式。若 Marqdo 能: + +1. **认出**文档中的公式(或显式传入 LaTeX/ASCII-math 字符串); +2. **符号整理 / 求值 / 求解**; +3. 在 **`marqdo view` 里画出**简单图像; + +则同一份 `.mq.md` 既是讲义又是可运行实验,差异化远大于「再包一层 `sin`」。 + +风险同样大:CAS、数值稳定、渲染栈都会显著增加依赖与维护面。故标为**候选**:先定分层,允许只实现「数值 + 显式字符串」,再渐进接 `$$`。 + +--- + +## 2. 产品分层(建议) + +| 层 | 能力 | 依赖量 | 建议阶段 | +|----|------|--------|----------| +| **Math-N(数值)** | 四则、幂、根、三角函数、常数;列表上的 map 式计算 | 小(可纯 Rust) | 若纳入官方库,**先做这层** | +| **Math-S(符号)** | 化简、展开、求导、代入、解方程(单变元优先) | 中–大(自研子集或嵌 CAS) | 第二期 | +| **Math-P(作图)** | 把表达式/点列渲染为 SVG(或 PNG)嵌入 view | 中(SVG 即可) | 与 view 同期 | +| **Math-D(文档公式)** | 解析正文 `$$…$$`,命名后供调用 | 中(词法/源映射) | 第三期 | + +**默认发版建议:** 官方 `lib/math` 先只承诺 **Math-N**;S/P/D 放 `experimental` 或 feature `math-cas` / `math-plot`,避免「标准库」名不副实。 + +--- + +## 3. 导入与命名 + +| 导入 | API 语言 | +|------|----------| +| `> lib/math.mq.md` | 英文 | +| `> lib/数学.mq.md` | 中文 | + +宿主原语(L0.5)示例:`math_sin`、`math_eval`、`math_solve` —— 仅供库包装。 + +--- + +## 4. 用户 API 草图 + +### 4.1 数值(Math-N) + +| 英文 | 中文 | 说明 | +|------|------|------| +| `pi` / `e` | `圆周率` / `自然底数` | 无参,返回文本或「十进制文本」——**本波仍无 float 类型时用文本十进制**,或引入 `num` 宿主类型 | +| `add` `sub` `mul` `div` `pow` `sqrt` | `加` `减` `乘` `除` `幂` `根` | | +| `sin` `cos` `tan` `ln` `exp` | `正弦` `余弦` `正切` `对数` `指数` | 弧度 | +| `round` `floor` `ceil` | `四舍` `向下` `向上` | | +| `eval_num` | `求值` | `expr` 文本 → 数值文本 | + +**类型抉择(必须先 ADR):** + +| 选项 | 优点 | 缺点 | +|------|------|------| +| A. 继续只用 `int` + 十进制 `text` | 不碰 L0 | 慢、易错 | +| B. 新增宿主 `num`(十进制或 f64) | API 干净 | 类型与字节码要跟进 | +| C. 数学库内部不透明 `handle` | 隔离好 | 与 `print`/`json` 互通差 | + +倾向:**B(`num`)**,与 JSON 的非整数数字策略一并设计。 + +### 4.2 符号(Math-S) + +| 英文 | 中文 | 形参 | 结果 | +|------|------|------|------| +| `simplify` | `化简` | `expr` | 表达式文本(或 handle) | +| `expand` | `展开` | `expr` | 同上 | +| `diff` | `求导` | `expr`, `var` | 同上 | +| `subs` | `代入` | `expr`, `var`, `value` | 同上 | +| `solve` | `求解` | `expr`, `var` | 解列表(文本) | + +表达式互换格式(草案):**ASCII 优先**(`2*x^2 + 1`),LaTeX 作为可选输入 `format=latex`。 + +单变元多项式 / 简单超越方程为 v1 目标;多变元方程组、积分:**不做承诺**。 + +### 4.3 作图(Math-P) + +| 英文 | 中文 | 说明 | +|------|------|------| +| `plot_fn` | `绘函数` | `expr`, `var`, `min`, `max`, 可选 `steps` → **SVG 文本** | +| `plot_points` | `绘点列` | `xs`, `ys` → SVG 文本 | + +view 行为: + +- 若 stdout / 返回值为「带标记的 SVG」或约定 MIME,Execution 区**内嵌渲染**(非仅 `
`)。  
+- 静态 `view output`:把 SVG 写入 HTML。  
+- CLI:默认打印 SVG 文本;`--plot-file out.svg` 可选。
+
+不引入完整浏览器 Chart 框架;**SVG 路径足够**教微积分与拟合入门。
+
+### 4.4 文档公式面(Math-D)
+
+与 [markdown-mapping.md](markdown-mapping.md) 的衔接:
+
+| 现状 | 目标 |
+|------|------|
+| `$$` 多半落入叙述/未定义 | 可选:**命名公式块**可被引用 |
+
+建议语法(草案,需进 mapping 修订):
+
+```markdown
+$$:energy
+E = mc^2
+$$
+```
+
+或 frontmatter / 标题锚定:
+
+```markdown
+## energy
+$$
+E = mc^2
+$$
+```
+
+调用:
+
+```markdown
+---`
+> lib/math.mq.md
+---`
+
+*`e2` = > simplify expr=> formula name=energy *
+```
+
+更简单的 v1:**不解析正文 `$$`**,只接受:
+
+```markdown
+*`e2` = > simplify expr=E=mc^2 format=latex *
+```
+
+正文 `$$` 仍由 view 的 Markdown 渲染(KaTeX/MathJax)负责「好看」,计算走显式字符串——**降低词法耦合**,推荐作为第一刀。
+
+---
+
+## 5. 实现策略选项
+
+| 策略 | 说明 | 建议 |
+|------|------|------|
+| **纯 Rust 数值** | `libm` / 自写 | Math-N 必选 |
+| **嵌入轻量 CAS** | 如符号子集自研,或绑 `meval`/`fasteval` 仅数值 | 求值用 |
+| **外挂 SymPy(经外联库)** | 符号交给 Python | 与 [stdlib-foreign.md](stdlib-foreign.md) 合流;标准库变薄 |
+| **WASM CAS** | 可嵌入 view | 后期 |
+
+务实路径:**Math-N 自研 → Math-P SVG → Math-S 先外联 SymPy(可选)→ 再考虑内嵌**。这样「数学标准库」在官方包里可以很瘦,重能力走外联 feature。
+
+---
+
+## 6. 安全与性能
+
+- 表达式长度、求解迭代、绘图采样点设硬上限。  
+- 禁止公式里跑任意宿主代码(与外联分离)。  
+- view 中绘图同步、限时。
+
+---
+
+## 7. 是否定为「标准库」的决策标准
+
+纳入默认 `lib/math` 当且仅当:
+
+1. Math-N API 稳定且有中英金样例;  
+2. 不强制下载数百 MB 依赖;  
+3. 无外联时文档站示例仍可跑(纯数值 + 可选 SVG)。
+
+若符号/作图依赖 SymPy 或大型引擎 → 标 **`lib/math` = 数值**,符号示例放到 `examples/math-cas` 并要求 `--allow-foreign`。
+
+---
+
+## 8. 一句话
+
+**用 Markdown 的公式习惯服务「可计算文档」;官方数学库先数值与 SVG,符号与 `$$` 引用分期,必要时借外联而非做大内核。**
diff --git a/doc/design/stdlib-modules.md b/doc/design/stdlib-modules.md
new file mode 100644
index 0000000..302b848
--- /dev/null
+++ b/doc/design/stdlib-modules.md
@@ -0,0 +1,227 @@
+# 标准库下一波(L1 扩展模块)
+
+| | |
+|---|---|
+| 状态 | **本波已落地(M1–M5)**;HTTPS 与带 `/` 的裸路径字面量仍受限 |
+| 日期 | 2026-08-05 |
+| 本波范围 | **仅前五个库**:文件 / 系统 / 时间 / JSON / 网络 |
+| 暂缓 | 数学、外联(重型;详稿保留、不排期)— [stdlib-math.md](stdlib-math.md) · [stdlib-foreign.md](stdlib-foreign.md) |
+| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
+| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [keywords-i18n.md](keywords-i18n.md) · [view.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. 分层与实现分工
+
+```text
+用户 .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` | **是**(文档与用户站只教这一层) |
+
+规则:
+
+1. **导入即选择语言**(JSON 除外):`lib/fs.mq.md` → 英文 API;`lib/文件.mq.md` → 中文 API(见 [stdlib-i18n.md](stdlib-i18n.md))。  
+2. **不设 `lang:`**。  
+3. 宿主原语保持英文;中英差异只存在于 L1 包装层(JSON 无第二套包装)。  
+4. 失败一律 `path:line:col: message`([stdlib.md](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](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. 中英路径总表(本波)
+
+```text
+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`;数学与外联暂缓。**
diff --git a/doc/design/stdlib.md b/doc/design/stdlib.md
index d8e00ca..e71fa8e 100644
--- a/doc/design/stdlib.md
+++ b/doc/design/stdlib.md
@@ -4,10 +4,10 @@
 |---|---|
 | 状态 | **S0–S3 落地** |
 | 日期 | 2026-08-04 |
-| 相关 | [keywords.md](keywords.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [roadmap/next-phase.md](../roadmap/next-phase.md) |
+| 相关 | [keywords.md](keywords.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [roadmap/next-phase.md](../roadmap/next-phase.md) |
 
-> **多语言库命名**已单独定稿方向:见 [stdlib-i18n.md](stdlib-i18n.md)。  
-> 要点:不设 `lang:`;`lib/text.mq.md`(英文函数)与 `lib/文本.mq.md`(中文函数)分文件导入。下文 §3 的单轨中文示例将在实现阶段按该草案改掉。
+> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。  
+> **下一波模块(本波:文件 / 系统 / 时间 / JSON / 网络;数学·外联暂缓)**:见 [stdlib-modules.md](stdlib-modules.md)。
 
 ---
 
@@ -60,8 +60,17 @@ Frontmatter:
 
 | 路径 | 导出函数 |
 |------|----------|
-| `lib/text.mq.md` | `去空白` `拆分` `拼接` |
-| `lib/table.mq.md` | `行数` `取行` |
+| `lib/fs.mq.md` / `lib/文件.mq.md` | `read_text`… / `读文本`… |
+| `lib/time.mq.md` / `lib/时间.mq.md` | `now_unix`… / `此刻秒`… |
+| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`… / `取环境`… |
+| `lib/json.mq.md` | `parse` `stringify` `get` `keys`(中英同文件) |
+| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`… / `获取`… |
+| `lib/text.mq.md` | `str_trim` `str_split` `str_join` |
+| `lib/文本.mq.md` | `去空白` `拆分` `拼接` |
+| `lib/table.mq.md` | `rows` `row_at` |
+| `lib/表.mq.md` | `行数` `取行` |
+
+规划中的 L1 扩展见 [stdlib-modules.md](stdlib-modules.md)。
 
 ---
 
diff --git a/doc/design/view.md b/doc/design/view.md
index 0f4ef2e..7f7e39e 100644
--- a/doc/design/view.md
+++ b/doc/design/view.md
@@ -75,6 +75,7 @@ OUT_DIR/
 
 - 页内链接一律**相对路径**,可用任意静态服务器或 `file://`(同目录结构下)打开。  
 - 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。  
+- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。  
 - 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。  
 - 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
 
diff --git a/doc/roadmap/next-phase.md b/doc/roadmap/next-phase.md
index 86a7dce..c75f170 100644
--- a/doc/roadmap/next-phase.md
+++ b/doc/roadmap/next-phase.md
@@ -17,7 +17,7 @@
 | **`input`** | CLI 双后端 + `--stdin-file`;frontmatter `stdin:`/`输入:`;live view 表单覆盖;无预置时 capture 提示补线 | **P1a + P1b 完成** |
 | **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
 | **view** | 结构 + 一次执行 + 源码;注释已 Markdown 渲染;无暂停/断点 | **文档浏览器,不是调试器** |
-| **标准库** | S0–S3:`len`/`str`/`int`/`type`/`trim`/`split`/`join`/`at` + 官方 `lib/` | **P2 完成** |
+| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
 | **模块** | `> file.mq.md` 顶层函数合并,无命名空间 | 短期可继续用 |
 
 用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
diff --git a/lib/fs.mq.md b/lib/fs.mq.md
new file mode 100644
index 0000000..c7baaa3
--- /dev/null
+++ b/lib/fs.mq.md
@@ -0,0 +1,41 @@
+---
+title: lib/fs
+description: English filesystem wrappers
+---
+
+# read_text
+    - path
+
+**> host_read_text path=`path`**
+
+# write_text
+    - path
+    - text
+
+**> host_write_text path=`path` text=`text`**
+
+# append_text
+    - path
+    - text
+
+**> host_append_text path=`path` text=`text`**
+
+# exists
+    - path
+
+**> host_exists path=`path`**
+
+# list_dir
+    - path
+
+**> host_list_dir path=`path`**
+
+# make_dir
+    - path
+
+**> host_make_dir path=`path`**
+
+# remove
+    - path
+
+**> host_remove path=`path`**
diff --git a/lib/json.mq.md b/lib/json.mq.md
new file mode 100644
index 0000000..427a485
--- /dev/null
+++ b/lib/json.mq.md
@@ -0,0 +1,25 @@
+---
+title: lib/json
+description: JSON parse/stringify (shared EN/ZH import)
+---
+
+# parse
+    - text
+
+**> host_json_parse text=`text`**
+
+# stringify
+    - value
+
+**> host_json_stringify value=`value`**
+
+# get
+    - value
+    - key
+
+**> host_json_get value=`value` key=`key`**
+
+# keys
+    - value
+
+**> host_json_keys value=`value`**
diff --git a/lib/net.mq.md b/lib/net.mq.md
new file mode 100644
index 0000000..c4e93e6
--- /dev/null
+++ b/lib/net.mq.md
@@ -0,0 +1,20 @@
+---
+title: lib/net
+description: English minimal HTTP wrappers
+---
+
+# http_get
+    - url
+
+**> host_http_get url=`url`**
+
+# http_post
+    - url
+    - body
+
+**> host_http_post url=`url` body=`body`**
+
+# url_encode
+    - text
+
+**> host_url_encode text=`text`**
diff --git a/lib/sys.mq.md b/lib/sys.mq.md
new file mode 100644
index 0000000..213e132
--- /dev/null
+++ b/lib/sys.mq.md
@@ -0,0 +1,33 @@
+---
+title: lib/sys
+description: English system wrappers
+---
+
+# env_get
+    - name
+
+**> host_env_get name=`name`**
+
+# env_set
+    - name
+    - value
+
+**> host_env_set name=`name` value=`value`**
+
+# args
+
+**> host_args**
+
+# cwd
+
+**> host_cwd**
+
+# exit
+    - code
+
+**> host_exit code=`code`**
+
+# exec
+    - cmd
+
+**> host_exec cmd=`cmd`**
diff --git a/lib/time.mq.md b/lib/time.mq.md
new file mode 100644
index 0000000..8c89b98
--- /dev/null
+++ b/lib/time.mq.md
@@ -0,0 +1,29 @@
+---
+title: lib/time
+description: English time wrappers
+---
+
+# now_unix
+
+**> host_now_unix**
+
+# now_ms
+
+**> host_now_ms**
+
+# format
+    - unix
+    - pattern
+
+**> host_format_time unix=`unix` pattern=`pattern`**
+
+# sleep_ms
+    - ms
+
+**> host_sleep_ms ms=`ms`**
+
+# parse
+    - text
+    - pattern
+
+**> host_parse_time text=`text` pattern=`pattern`**
diff --git a/lib/文件.mq.md b/lib/文件.mq.md
new file mode 100644
index 0000000..d779edb
--- /dev/null
+++ b/lib/文件.mq.md
@@ -0,0 +1,41 @@
+---
+title: lib/文件
+description: 中文文件系统包装
+---
+
+# 读文本
+    - 路径
+
+**> host_read_text path=`路径`**
+
+# 写文本
+    - 路径
+    - 内容
+
+**> host_write_text path=`路径` text=`内容`**
+
+# 追加文本
+    - 路径
+    - 内容
+
+**> host_append_text path=`路径` text=`内容`**
+
+# 存在
+    - 路径
+
+**> host_exists path=`路径`**
+
+# 列目录
+    - 路径
+
+**> host_list_dir path=`路径`**
+
+# 建目录
+    - 路径
+
+**> host_make_dir path=`路径`**
+
+# 删除
+    - 路径
+
+**> host_remove path=`路径`**
diff --git a/lib/时间.mq.md b/lib/时间.mq.md
new file mode 100644
index 0000000..93d3071
--- /dev/null
+++ b/lib/时间.mq.md
@@ -0,0 +1,29 @@
+---
+title: lib/时间
+description: 中文时间包装
+---
+
+# 此刻秒
+
+**> host_now_unix**
+
+# 此刻毫秒
+
+**> host_now_ms**
+
+# 格式化
+    - 秒
+    - 格式
+
+**> host_format_time unix=`秒` pattern=`格式`**
+
+# 睡眠毫秒
+    - 毫秒
+
+**> host_sleep_ms ms=`毫秒`**
+
+# 解析时间
+    - 内容
+    - 格式
+
+**> host_parse_time text=`内容` pattern=`格式`**
diff --git a/lib/系统.mq.md b/lib/系统.mq.md
new file mode 100644
index 0000000..cf695dd
--- /dev/null
+++ b/lib/系统.mq.md
@@ -0,0 +1,33 @@
+---
+title: lib/系统
+description: 中文系统包装
+---
+
+# 取环境
+    - 名
+
+**> host_env_get name=`名`**
+
+# 设环境
+    - 名
+    - 值
+
+**> host_env_set name=`名` value=`值`**
+
+# 参数表
+
+**> host_args**
+
+# 工作目录
+
+**> host_cwd**
+
+# 退出
+    - 码
+
+**> host_exit code=`码`**
+
+# 执行
+    - 命令
+
+**> host_exec cmd=`命令`**
diff --git a/lib/网络.mq.md b/lib/网络.mq.md
new file mode 100644
index 0000000..af79c2b
--- /dev/null
+++ b/lib/网络.mq.md
@@ -0,0 +1,20 @@
+---
+title: lib/网络
+description: 中文简易网络包装
+---
+
+# 获取
+    - 地址
+
+**> host_http_get url=`地址`**
+
+# 提交
+    - 地址
+    - 内容
+
+**> host_http_post url=`地址` body=`内容`**
+
+# 编码地址
+    - 内容
+
+**> host_url_encode text=`内容`**
diff --git a/public/00-welcome.mq.md b/public/00-welcome.mq.md
index cd99688..094948c 100644
--- a/public/00-welcome.mq.md
+++ b/public/00-welcome.mq.md
@@ -9,7 +9,7 @@ Hi — thanks for opening this site. Marqdo is a language where **code is docume
 
 AI already prefers Markdown. Marqdo asks: why keep docs and code as two worlds? A `.mq.md` file is both. The longer ambition includes OKF-style knowledge YAML and more; for now the focus is a solid interpreter and this site (yes — generated by Marqdo itself).
 
-The language is young. You get structure markers, a small bilingual core (`print` / `打印`, …), optional stdlib files (`lib/text.mq.md` vs `lib/文本.mq.md`), local `view`, and static export. Contribute on [GitHub](https://github.com/cflmy/marqdo).
+The language is young. You get structure markers, a small bilingual core (`print` / `打印`, …), optional stdlib files under `lib/` (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Contribute on [GitHub](https://github.com/cflmy/marqdo).
 
 中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
 
diff --git a/public/00-欢迎.mq.md b/public/00-欢迎.mq.md
index 54caf97..ffc2b71 100644
--- a/public/00-欢迎.mq.md
+++ b/public/00-欢迎.mq.md
@@ -9,7 +9,7 @@ description: 用户文档首页 — 代码即文档(中文版)
 
 AI 输出本就偏爱 Markdown。作者的念头是:何必再把文档和代码拆成两套?`.mq.md` 双后缀保证它仍是合法 Markdown。更长远的目标包括 OKF 式知识清单等;眼下先把解释器与本站做好——对,这个站点就是 Marqdo 生成的。
 
-语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(`lib/文本.mq.md` 与 `lib/text.mq.md`)、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
+语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(见本站 [`stdlib/`](stdlib/))、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
 
 English docs: [`00-welcome.mq.md`](00-welcome.mq.md) (English prose and English builtins).
 
diff --git a/public/README.md b/public/README.md
index 5a2bd7b..f1d8264 100644
--- a/public/README.md
+++ b/public/README.md
@@ -2,28 +2,26 @@
 
 本目录即面向访客的 Marqdo 介绍:每个 `.mq.md` 既是文稿也能 `marqdo run`,并随仓库 / 静态站一起下载。
 
-**双语约定:** 拉丁文件名 → 英文叙述与英文内置;中文文件名 → 中文叙述与中文编程(`打印`、`长度` …)。成对放在同一目录(如 `structure/01-hello.mq.md` 与 `structure/01-你好.mq.md`)。标准库按路径选 API:`lib/text.mq.md` vs `lib/文本.mq.md`。
+**双语约定:** 拉丁文件名 → 英文叙述与英文内置;中文文件名 → 中文叙述与中文编程。成对放在同一目录。标准库:拉丁路径用英文 API,中文路径用中文 API;JSON 仅 `lib/json.mq.md`。
 
 | 路径 | 内容 |
 |------|------|
 | [`00-welcome.mq.md`](00-welcome.mq.md) / [`00-欢迎.mq.md`](00-欢迎.mq.md) | 首页(英 / 中) |
-| [`structure/`](structure/) | 基本结构(英 / 中并列) |
-| [`keywords/`](keywords/) | 关键字与内置(英 / 中并列) |
-| [`features/`](features/) | 特性迭代(英 / 中并列) |
-| [`lib-import.mq.md`](lib-import.mq.md) / [`lib-导入.mq.md`](lib-导入.mq.md) | 导入 `lib/text` / `lib/文本` |
+| [`structure/`](structure/) | 基本结构 |
+| [`keywords/`](keywords/) | 关键字与 L0 内置 |
+| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络) |
+| [`features/`](features/) | 特性迭代 |
+| [`lib-import.mq.md`](lib-import.mq.md) / [`lib-导入.mq.md`](lib-导入.mq.md) | 快速导入示例(text) |
 
-**不放** `errors/`:失败样例只在 `tests/errors/`,避免用户站出现红色执行失败。
+**不放** `errors/`:失败样例只在 `tests/errors/`。
 
-开发文档(语言设计等)在 [`doc/`](../doc/),与本目录分离。
+开发文档在 [`doc/`](../doc/)。
 
 ## 浏览与生成 HTML
 
 ```bash
 cargo run -- view public
 cargo run -- view output public -o public
-# 或
-./scripts/build-public.sh
-powershell -File ./scripts/build-public.ps1
 ```
 
-生成的 `index.html` 与 `pages/` 默认被 ignore;CI 构建后推到 `gh-pages`。详见 [user-site.md](../doc/design/user-site.md)。
+详见 [user-site.md](../doc/design/user-site.md)。
diff --git a/public/stdlib/00-overview.mq.md b/public/stdlib/00-overview.mq.md
new file mode 100644
index 0000000..e968588
--- /dev/null
+++ b/public/stdlib/00-overview.mq.md
@@ -0,0 +1,18 @@
+---
+title: Standard library — overview
+description: How to import official lib modules
+---
+
+# main
+
+Official libraries live under lib/ (alias std/). Import them in YAML frontmatter with a greater-than line, for example lib/text.mq.md or lib/fs.mq.md.
+
+English-named files export English APIs; Chinese-named files export Chinese APIs. JSON is special: only lib/json.mq.md (shared by both languages).
+
+No extra allow flags: importing a module means you intend to use it. Under marqdo view or static export, exit soft-fails and long sleeps are clamped so the console stays up.
+
+Modules: text (text / 文本), table (table / 表), files (fs / 文件), time (time / 时间), system (sys / 系统), json (json only), net (net / 网络).
+
+Sibling pages in this folder document each module. Chinese overview: 00-索引.mq.md.
+
+> print text=stdlib overview ok
diff --git a/public/stdlib/00-索引.mq.md b/public/stdlib/00-索引.mq.md
new file mode 100644
index 0000000..e36ebef
--- /dev/null
+++ b/public/stdlib/00-索引.mq.md
@@ -0,0 +1,18 @@
+---
+title: 标准库 — 总览
+description: 如何导入官方 lib 模块
+---
+
+# main
+
+官方库在仓库 lib/(别名 std/)。在 YAML frontmatter 用大于号行导入,例如 lib/文本.mq.md 或 lib/文件.mq.md。
+
+拉丁文件名导出英文 API;中文文件名导出中文 API。JSON 特例:只有 lib/json.mq.md(中英共用)。
+
+导入即表示要用对应能力,无需再加允许旗标。marqdo view 或静态导出里,退出会软失败、长睡眠会被钳制,以免拖垮控制台。
+
+模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)。
+
+各模块说明见本目录其它页。English: 00-overview.mq.md.
+
+> 打印 内容=标准库总览就绪
diff --git a/public/stdlib/fs.mq.md b/public/stdlib/fs.mq.md
new file mode 100644
index 0000000..f9ad20d
--- /dev/null
+++ b/public/stdlib/fs.mq.md
@@ -0,0 +1,18 @@
+---
+title: lib/fs — files
+description: Read and write text under the sandbox
+> lib/fs.mq.md
+---
+
+# main
+
+Import lib/fs.mq.md. Functions: read_text, write_text, append_text, exists, list_dir, make_dir, remove (path / text params).
+
+Bare path words must not contain a slash character (parsed as division). Prefer a same-folder name or a variable.
+
+*`ok` = > exists path=demo.txt *
+
++ `ok`
+  > print text=demo-present
++ *
+  > print text=demo-missing
diff --git a/public/stdlib/json.mq.md b/public/stdlib/json.mq.md
new file mode 100644
index 0000000..fff8c93
--- /dev/null
+++ b/public/stdlib/json.mq.md
@@ -0,0 +1,19 @@
+---
+title: lib/json — JSON
+description: Shared EN/ZH path; parse and stringify
+> lib/json.mq.md
+---
+
+# main
+
+Import lib/json.mq.md from both English and Chinese docs (no translated twin). Functions: parse(text), stringify(value), get(value, key), keys(value). Objects become the map runtime type.
+
+*`obj` = > parse text={} *
+
+*`ty` = > type `obj` *
+
+> print text=`ty`
+
+*`out` = > stringify value=`obj` *
+
+> print text=`out`
diff --git a/public/stdlib/net.mq.md b/public/stdlib/net.mq.md
new file mode 100644
index 0000000..e1a6e8f
--- /dev/null
+++ b/public/stdlib/net.mq.md
@@ -0,0 +1,13 @@
+---
+title: lib/net — HTTP
+description: Minimal HTTP client and URL encode
+> lib/net.mq.md
+---
+
+# main
+
+Import lib/net.mq.md. Functions: http_get(url) returns map status/body, http_post(url, body), url_encode(text). v1 speaks cleartext http only.
+
+*`e` = > url_encode text=hello world *
+
+> print text=`e`
diff --git a/public/stdlib/sys.mq.md b/public/stdlib/sys.mq.md
new file mode 100644
index 0000000..a7f15e6
--- /dev/null
+++ b/public/stdlib/sys.mq.md
@@ -0,0 +1,18 @@
+---
+title: lib/sys — process
+description: Env, cwd, args, exit, exec
+> lib/sys.mq.md
+---
+
+# main
+
+Import lib/sys.mq.md. Functions: env_get, env_set, args, cwd, exit(code), exec(cmd). Under view, exit soft-fails instead of killing the process.
+
+*`d` = > cwd *
+
+*`n` = > len `d` *
+
++ `n` > 0
+  > print text=cwd-ok
++ *
+  > print text=cwd-empty
diff --git a/public/stdlib/table.mq.md b/public/stdlib/table.mq.md
new file mode 100644
index 0000000..4cb981d
--- /dev/null
+++ b/public/stdlib/table.mq.md
@@ -0,0 +1,24 @@
+---
+title: lib/table — lists
+description: Row count and index helpers
+> lib/table.mq.md
+---
+
+# main
+
+Import lib/table.mq.md. Functions: rows(xs), row_at(xs, i). Single-column Markdown tables are lists at runtime.
+
+`xs` =
+
+| v |
+|---|
+| a |
+| b |
+
+*`n` = > rows xs=`xs`*
+
+> print text=`n`
+
+*`r` = > row_at xs=`xs` i=0*
+
+> print text=`r`
diff --git a/public/stdlib/text.mq.md b/public/stdlib/text.mq.md
new file mode 100644
index 0000000..384707c
--- /dev/null
+++ b/public/stdlib/text.mq.md
@@ -0,0 +1,19 @@
+---
+title: lib/text — strings
+description: Trim, split, join wrappers
+> lib/text.mq.md
+---
+
+# main
+
+Import lib/text.mq.md. Functions: str_trim(s), str_split(s, sep), str_join(xs, sep).
+
+*`t` = > str_trim s=  marqdo  *
+
+> print text=`t`
+
+*`parts` = > str_split s=a,b,c sep=,*
+
+*`j` = > str_join xs=`parts` sep=-*
+
+> print text=`j`
diff --git a/public/stdlib/time.mq.md b/public/stdlib/time.mq.md
new file mode 100644
index 0000000..682407b
--- /dev/null
+++ b/public/stdlib/time.mq.md
@@ -0,0 +1,19 @@
+---
+title: lib/time — clock
+description: Unix time, format, parse, sleep
+> lib/time.mq.md
+---
+
+# main
+
+Import lib/time.mq.md. Functions: now_unix, now_ms, format(unix, pattern), parse(text, pattern), sleep_ms(ms). Patterns use strftime.
+
+*`s` = > format unix=0 pattern=%Y-%m-%d *
+
+> print text=`s`
+
+*`u` = > parse text=1970-01-01 00:00:00 pattern=%Y-%m-%d %H:%M:%S *
+
+> print text=`u`
+
+> sleep_ms ms=0
diff --git a/public/stdlib/文件.mq.md b/public/stdlib/文件.mq.md
new file mode 100644
index 0000000..bb529e1
--- /dev/null
+++ b/public/stdlib/文件.mq.md
@@ -0,0 +1,18 @@
+---
+title: lib/文件 — 文件系统
+description: 沙箱内读写文本
+> lib/文件.mq.md
+---
+
+# main
+
+导入 lib/文件.mq.md。函数:读文本、写文本、追加文本、存在、列目录、建目录、删除。
+
+裸路径字面量不要写斜杠(会被当成除法)。可用同目录文件名或变量。
+
+*`ok` = > 存在 路径=demo.txt *
+
++ `ok`
+  > 打印 内容=有演示文件
++ *
+  > 打印 内容=无演示文件
diff --git a/public/stdlib/文本.mq.md b/public/stdlib/文本.mq.md
new file mode 100644
index 0000000..14e0f53
--- /dev/null
+++ b/public/stdlib/文本.mq.md
@@ -0,0 +1,19 @@
+---
+title: lib/文本 — 字符串
+description: 去空白、拆分、拼接
+> lib/文本.mq.md
+---
+
+# main
+
+导入 lib/文本.mq.md。函数:去空白(s)、拆分(s, sep)、拼接(xs, sep)。
+
+*`t` = > 去空白 s=  marqdo  *
+
+> 打印 内容=`t`
+
+*`parts` = > 拆分 s=甲,乙,丙 sep=,*
+
+*`j` = > 拼接 xs=`parts` sep=-*
+
+> 打印 内容=`j`
diff --git a/public/stdlib/时间.mq.md b/public/stdlib/时间.mq.md
new file mode 100644
index 0000000..100fb0c
--- /dev/null
+++ b/public/stdlib/时间.mq.md
@@ -0,0 +1,19 @@
+---
+title: lib/时间 — 时钟
+description: Unix 时间、格式化、解析、睡眠
+> lib/时间.mq.md
+---
+
+# main
+
+导入 lib/时间.mq.md。函数:此刻秒、此刻毫秒、格式化(秒, 格式)、解析时间(内容, 格式)、睡眠毫秒(毫秒)。格式为 strftime。
+
+*`s` = > 格式化 秒=0 格式=%Y-%m-%d *
+
+> 打印 内容=`s`
+
+*`u` = > 解析时间 内容=1970-01-01 00:00:00 格式=%Y-%m-%d %H:%M:%S *
+
+> 打印 内容=`u`
+
+> 睡眠毫秒 毫秒=0
diff --git a/public/stdlib/系统.mq.md b/public/stdlib/系统.mq.md
new file mode 100644
index 0000000..b9c46ba
--- /dev/null
+++ b/public/stdlib/系统.mq.md
@@ -0,0 +1,18 @@
+---
+title: lib/系统 — 进程
+description: 环境变量、工作目录、参数、退出、执行
+> lib/系统.mq.md
+---
+
+# main
+
+导入 lib/系统.mq.md。函数:取环境、设环境、参数表、工作目录、退出(码)、执行(命令)。view 下退出会软失败,不结束进程。
+
+*`d` = > 工作目录 *
+
+*`n` = > 长度 值=`d` *
+
++ `n` > 0
+  > 打印 内容=工作目录就绪
++ *
+  > 打印 内容=工作目录空
diff --git a/public/stdlib/网络.mq.md b/public/stdlib/网络.mq.md
new file mode 100644
index 0000000..b9f89f4
--- /dev/null
+++ b/public/stdlib/网络.mq.md
@@ -0,0 +1,13 @@
+---
+title: lib/网络 — HTTP
+description: 简易 HTTP 与地址编码
+> lib/网络.mq.md
+---
+
+# main
+
+导入 lib/网络.mq.md。函数:获取(地址) 返回 map status/body、提交(地址, 内容)、编码地址(内容)。本波仅明文 http。
+
+*`e` = > 编码地址 内容=你好 *
+
+> 打印 内容=`e`
diff --git a/public/stdlib/表.mq.md b/public/stdlib/表.mq.md
new file mode 100644
index 0000000..ee67637
--- /dev/null
+++ b/public/stdlib/表.mq.md
@@ -0,0 +1,24 @@
+---
+title: lib/表 — 列表
+description: 行数与取行
+> lib/表.mq.md
+---
+
+# main
+
+导入 lib/表.mq.md。函数:行数(xs)、取行(xs, i)。单列表在运行时是列表。
+
+`xs` =
+
+| v |
+|---|
+| 甲 |
+| 乙 |
+
+*`n` = > 行数 xs=`xs`*
+
+> 打印 内容=`n`
+
+*`r` = > 取行 xs=`xs` i=0*
+
+> 打印 内容=`r`
diff --git a/src/aliases.rs b/src/aliases.rs
index b733b1d..617568f 100644
--- a/src/aliases.rs
+++ b/src/aliases.rs
@@ -22,6 +22,9 @@ pub fn is_reserved_keyword(name: &str) -> bool {
 /// Map a builtin callee (EN or ZH alias) to its English canonical name.
 /// Host primitives without ZH L0 aliases only match English.
 pub fn canonical_builtin(name: &str) -> Option<&'static str> {
+    if let Some(h) = crate::host::HostFn::from_name(name) {
+        return Some(h.name());
+    }
     match name {
         "print" | "打印" => Some("print"),
         "input" | "输入" => Some("input"),
diff --git a/src/builtin.rs b/src/builtin.rs
index cb905e6..6db2507 100644
--- a/src/builtin.rs
+++ b/src/builtin.rs
@@ -31,7 +31,7 @@ pub fn builtin_int(v: &Value) -> Result {
     }
 }
 
-/// `type`: type tag as text (`none` / `bool` / `int` / `text` / `list`).
+/// `type`: type tag as text (`none` / `bool` / `int` / `text` / `list` / `map`).
 pub fn builtin_type(v: &Value) -> Value {
     Value::Text(
         match v {
@@ -40,6 +40,7 @@ pub fn builtin_type(v: &Value) -> Value {
             Value::Int(_) => "int",
             Value::Text(_) => "text",
             Value::List(_) => "list",
+            Value::Map(_) => "map",
         }
         .into(),
     )
diff --git a/src/bytecode/compile.rs b/src/bytecode/compile.rs
index c2596ec..0dd30c2 100644
--- a/src/bytecode/compile.rs
+++ b/src/bytecode/compile.rs
@@ -427,6 +427,45 @@ impl<'a> FnCompiler<'a> {
                 }
                 return Ok(());
             }
+            other if crate::host::HostFn::from_name(other).is_some() => {
+                let hf = crate::host::HostFn::from_name(other).unwrap();
+                let params = hf.all_params();
+                let mut named: HashMap = HashMap::new();
+                let mut positionals = Vec::new();
+                for a in &call.args {
+                    match a {
+                        Arg::Positional(e) => positionals.push(e),
+                        Arg::Named { name, value } => {
+                            named.insert(name.clone(), value);
+                        }
+                    }
+                }
+                let mut pos_i = 0usize;
+                let required_n = hf.required_params().len();
+                for (i, p) in params.iter().enumerate() {
+                    if let Some(e) = named.get(*p) {
+                        self.compile_expr(e)?;
+                    } else if pos_i < positionals.len() {
+                        self.compile_expr(positionals[pos_i])?;
+                        pos_i += 1;
+                    } else if i < required_n {
+                        return Err(self.err(format!("{} requires `{p}`", hf.name())));
+                    } else {
+                        self.emit(Op::None_);
+                    }
+                }
+                if pos_i < positionals.len() {
+                    return Err(self.err(format!(
+                        "too many positional arguments ({} extra)",
+                        positionals.len() - pos_i
+                    )));
+                }
+                self.emit(Op::HostCall(hf.as_u16(), params.len() as u8));
+                if as_stmt {
+                    self.emit(Op::Pop);
+                }
+                return Ok(());
+            }
             _ => {}
         }
 
diff --git a/src/bytecode/mod.rs b/src/bytecode/mod.rs
index ab83274..0cfaf59 100644
--- a/src/bytecode/mod.rs
+++ b/src/bytecode/mod.rs
@@ -54,6 +54,8 @@ pub enum Op {
     GetIndex,
     /// Call function by index; argc values are on the stack (param order).
     Call(u16, u8),
+    /// Host primitive: pop `argc` args (param order), push result.
+    HostCall(u16, u8),
     Return,
 }
 
diff --git a/src/bytecode/vm.rs b/src/bytecode/vm.rs
index e8e1e51..03804a8 100644
--- a/src/bytecode/vm.rs
+++ b/src/bytecode/vm.rs
@@ -8,11 +8,13 @@ use crate::builtin::{
     builtin_at, builtin_int, builtin_join, builtin_len, builtin_split, builtin_str, builtin_trim,
     builtin_type,
 };
+use crate::host::{call_host, HostContext, HostFn};
 use crate::bytecode::{Op, Program};
 use crate::debug::emit_trace;
 use crate::diagnostics::{bail_at, Span};
 use crate::input_feed::InputFeed;
 use crate::value::Value;
+use std::collections::HashMap;
 
 pub struct Vm {
     path: Option,
@@ -20,6 +22,7 @@ pub struct Vm {
     pub captured_stdout: String,
     input: InputFeed,
     trace: bool,
+    host: HostContext,
 }
 
 struct Frame {
@@ -36,6 +39,7 @@ impl Vm {
             captured_stdout: String::new(),
             input: InputFeed::new(false, Vec::new()),
             trace: false,
+            host: HostContext::for_run(path, Default::default(), Vec::new()),
         }
     }
 
@@ -46,6 +50,7 @@ impl Vm {
             captured_stdout: String::new(),
             input: InputFeed::new(true, Vec::new()),
             trace: false,
+            host: HostContext::for_capture(path, Default::default()),
         }
     }
 
@@ -59,6 +64,11 @@ impl Vm {
         self
     }
 
+    pub fn with_host(mut self, host: HostContext) -> Self {
+        self.host = host;
+        self
+    }
+
     fn emit_line(&mut self, text: &str) {
         if self.capture {
             self.captured_stdout.push_str(text);
@@ -276,6 +286,35 @@ impl Vm {
                     let list = pop(&mut stack).map_err(|m| self.err_at(span, m))?;
                     stack.push(builtin_at(&list, &idx).map_err(|m| self.err_at(span, m))?);
                 }
+                Op::HostCall(id, argc) => {
+                    let hf = HostFn::from_u16(id)
+                        .ok_or_else(|| self.err_at(span, format!("unknown host id {id}")))?;
+                    let argc = argc as usize;
+                    let params = hf.all_params();
+                    if params.len() != argc {
+                        return Err(self.err_at(span, "host call argc mismatch"));
+                    }
+                    let mut vals = Vec::with_capacity(argc);
+                    for _ in 0..argc {
+                        vals.push(pop(&mut stack).map_err(|m| self.err_at(span, m))?);
+                    }
+                    vals.reverse();
+                    let mut bound = HashMap::new();
+                    for (p, v) in params.iter().zip(vals.into_iter()) {
+                        bound.insert((*p).to_string(), v);
+                    }
+                    for req in hf.required_params() {
+                        if !bound.contains_key(*req) {
+                            return Err(self.err_at(
+                                span,
+                                format!("{} requires `{req}`", hf.name()),
+                            ));
+                        }
+                    }
+                    let result =
+                        call_host(&self.host, hf, &bound).map_err(|m| self.err_at(span, m))?;
+                    stack.push(result);
+                }
                 Op::Call(fid, argc) => {
                     let fid = fid as usize;
                     let argc = argc as usize;
diff --git a/src/host/dispatch.rs b/src/host/dispatch.rs
new file mode 100644
index 0000000..e1fb06e
--- /dev/null
+++ b/src/host/dispatch.rs
@@ -0,0 +1,227 @@
+//! Host function registry and dispatch.
+
+use std::collections::HashMap;
+
+use crate::host::{fs, json, net, sys, time, HostContext};
+use crate::value::Value;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u16)]
+pub enum HostFn {
+    ReadText = 1,
+    WriteText = 2,
+    AppendText = 3,
+    Exists = 4,
+    ListDir = 5,
+    MakeDir = 6,
+    Remove = 7,
+    NowUnix = 8,
+    NowMs = 9,
+    FormatTime = 10,
+    SleepMs = 11,
+    ParseTime = 12,
+    EnvGet = 13,
+    EnvSet = 14,
+    Args = 15,
+    Cwd = 16,
+    Exit = 17,
+    Exec = 18,
+    JsonParse = 19,
+    JsonStringify = 20,
+    JsonGet = 21,
+    JsonKeys = 22,
+    HttpGet = 23,
+    HttpPost = 24,
+    UrlEncode = 25,
+}
+
+impl HostFn {
+    pub fn from_u16(id: u16) -> Option {
+        Some(match id {
+            1 => Self::ReadText,
+            2 => Self::WriteText,
+            3 => Self::AppendText,
+            4 => Self::Exists,
+            5 => Self::ListDir,
+            6 => Self::MakeDir,
+            7 => Self::Remove,
+            8 => Self::NowUnix,
+            9 => Self::NowMs,
+            10 => Self::FormatTime,
+            11 => Self::SleepMs,
+            12 => Self::ParseTime,
+            13 => Self::EnvGet,
+            14 => Self::EnvSet,
+            15 => Self::Args,
+            16 => Self::Cwd,
+            17 => Self::Exit,
+            18 => Self::Exec,
+            19 => Self::JsonParse,
+            20 => Self::JsonStringify,
+            21 => Self::JsonGet,
+            22 => Self::JsonKeys,
+            23 => Self::HttpGet,
+            24 => Self::HttpPost,
+            25 => Self::UrlEncode,
+            _ => return None,
+        })
+    }
+
+    pub fn from_name(name: &str) -> Option {
+        Some(match name {
+            "host_read_text" => Self::ReadText,
+            "host_write_text" => Self::WriteText,
+            "host_append_text" => Self::AppendText,
+            "host_exists" => Self::Exists,
+            "host_list_dir" => Self::ListDir,
+            "host_make_dir" => Self::MakeDir,
+            "host_remove" => Self::Remove,
+            "host_now_unix" => Self::NowUnix,
+            "host_now_ms" => Self::NowMs,
+            "host_format_time" => Self::FormatTime,
+            "host_sleep_ms" => Self::SleepMs,
+            "host_parse_time" => Self::ParseTime,
+            "host_env_get" => Self::EnvGet,
+            "host_env_set" => Self::EnvSet,
+            "host_args" => Self::Args,
+            "host_cwd" => Self::Cwd,
+            "host_exit" => Self::Exit,
+            "host_exec" => Self::Exec,
+            "host_json_parse" => Self::JsonParse,
+            "host_json_stringify" => Self::JsonStringify,
+            "host_json_get" => Self::JsonGet,
+            "host_json_keys" => Self::JsonKeys,
+            "host_http_get" => Self::HttpGet,
+            "host_http_post" => Self::HttpPost,
+            "host_url_encode" => Self::UrlEncode,
+            _ => return None,
+        })
+    }
+
+    pub fn as_u16(self) -> u16 {
+        self as u16
+    }
+
+    pub fn name(self) -> &'static str {
+        match self {
+            Self::ReadText => "host_read_text",
+            Self::WriteText => "host_write_text",
+            Self::AppendText => "host_append_text",
+            Self::Exists => "host_exists",
+            Self::ListDir => "host_list_dir",
+            Self::MakeDir => "host_make_dir",
+            Self::Remove => "host_remove",
+            Self::NowUnix => "host_now_unix",
+            Self::NowMs => "host_now_ms",
+            Self::FormatTime => "host_format_time",
+            Self::SleepMs => "host_sleep_ms",
+            Self::ParseTime => "host_parse_time",
+            Self::EnvGet => "host_env_get",
+            Self::EnvSet => "host_env_set",
+            Self::Args => "host_args",
+            Self::Cwd => "host_cwd",
+            Self::Exit => "host_exit",
+            Self::Exec => "host_exec",
+            Self::JsonParse => "host_json_parse",
+            Self::JsonStringify => "host_json_stringify",
+            Self::JsonGet => "host_json_get",
+            Self::JsonKeys => "host_json_keys",
+            Self::HttpGet => "host_http_get",
+            Self::HttpPost => "host_http_post",
+            Self::UrlEncode => "host_url_encode",
+        }
+    }
+
+    /// Required params first; see `optional_params` for trailing optionals.
+    pub fn required_params(self) -> &'static [&'static str] {
+        match self {
+            Self::ReadText | Self::Exists | Self::ListDir | Self::MakeDir | Self::Remove => {
+                &["path"]
+            }
+            Self::WriteText | Self::AppendText => &["path", "text"],
+            Self::NowUnix | Self::NowMs | Self::Args | Self::Cwd => &[],
+            Self::FormatTime => &["unix", "pattern"],
+            Self::ParseTime => &["text", "pattern"],
+            Self::SleepMs => &["ms"],
+            Self::EnvGet => &["name"],
+            Self::EnvSet => &["name", "value"],
+            Self::Exit => &["code"],
+            Self::Exec => &["cmd"],
+            Self::JsonParse | Self::UrlEncode => &["text"],
+            Self::JsonStringify | Self::JsonKeys => &["value"],
+            Self::JsonGet => &["value", "key"],
+            Self::HttpGet => &["url"],
+            Self::HttpPost => &["url", "body"],
+        }
+    }
+
+    pub fn optional_params(self) -> &'static [&'static str] {
+        match self {
+            Self::JsonStringify => &["indent"],
+            Self::HttpPost => &["content_type"],
+            Self::Exec => &["args"],
+            _ => &[],
+        }
+    }
+
+    pub fn all_params(self) -> Vec<&'static str> {
+        let mut v = self.required_params().to_vec();
+        v.extend_from_slice(self.optional_params());
+        v
+    }
+}
+
+pub fn call_host(
+    ctx: &HostContext,
+    fn_id: HostFn,
+    bound: &HashMap,
+) -> Result {
+    match fn_id {
+        HostFn::ReadText => fs::read_text(ctx, require(bound, "path")?),
+        HostFn::WriteText => {
+            fs::write_text(ctx, require(bound, "path")?, require(bound, "text")?)
+        }
+        HostFn::AppendText => {
+            fs::append_text(ctx, require(bound, "path")?, require(bound, "text")?)
+        }
+        HostFn::Exists => fs::exists(ctx, require(bound, "path")?),
+        HostFn::ListDir => fs::list_dir(ctx, require(bound, "path")?),
+        HostFn::MakeDir => fs::make_dir(ctx, require(bound, "path")?),
+        HostFn::Remove => fs::remove(ctx, require(bound, "path")?),
+        HostFn::NowUnix => time::now_unix(),
+        HostFn::NowMs => time::now_ms(),
+        HostFn::FormatTime => {
+            time::format_time(require(bound, "unix")?, require(bound, "pattern")?)
+        }
+        HostFn::SleepMs => time::sleep_ms(ctx, require(bound, "ms")?),
+        HostFn::ParseTime => {
+            time::parse_time(require(bound, "text")?, require(bound, "pattern")?)
+        }
+        HostFn::EnvGet => sys::env_get(require(bound, "name")?),
+        HostFn::EnvSet => sys::env_set(require(bound, "name")?, require(bound, "value")?),
+        HostFn::Args => sys::args(ctx),
+        HostFn::Cwd => sys::cwd(ctx),
+        HostFn::Exit => sys::exit(ctx, require(bound, "code")?),
+        HostFn::Exec => sys::exec(ctx, require(bound, "cmd")?, bound.get("args")),
+        HostFn::JsonParse => json::parse(require(bound, "text")?),
+        HostFn::JsonStringify => {
+            json::stringify(require(bound, "value")?, bound.get("indent"))
+        }
+        HostFn::JsonGet => json::get(require(bound, "value")?, require(bound, "key")?),
+        HostFn::JsonKeys => json::keys(require(bound, "value")?),
+        HostFn::HttpGet => net::http_get(ctx, require(bound, "url")?),
+        HostFn::HttpPost => net::http_post(
+            ctx,
+            require(bound, "url")?,
+            require(bound, "body")?,
+            bound.get("content_type"),
+        ),
+        HostFn::UrlEncode => net::url_encode(require(bound, "text")?),
+    }
+}
+
+fn require<'a>(bound: &'a HashMap, key: &str) -> Result<&'a Value, String> {
+    bound
+        .get(key)
+        .ok_or_else(|| format!("host call missing `{key}`"))
+}
diff --git a/src/host/fs.rs b/src/host/fs.rs
new file mode 100644
index 0000000..eacda34
--- /dev/null
+++ b/src/host/fs.rs
@@ -0,0 +1,108 @@
+//! Filesystem host primitives.
+
+use std::fs;
+use std::path::Path;
+
+use crate::host::HostContext;
+use crate::value::Value;
+
+pub fn path_under_root(path: &Path, root: &Path) -> bool {
+    let mut cur = path.to_path_buf();
+    loop {
+        if cur == *root {
+            return true;
+        }
+        if !cur.pop() {
+            return false;
+        }
+    }
+}
+
+fn text_path(v: &Value) -> Result<&str, String> {
+    match v {
+        Value::Text(s) => Ok(s.as_str()),
+        _ => Err("path must be text".into()),
+    }
+}
+
+fn text_body(v: &Value) -> Result<&str, String> {
+    match v {
+        Value::Text(s) => Ok(s.as_str()),
+        _ => Err("text must be text".into()),
+    }
+}
+
+pub fn read_text(ctx: &HostContext, path: &Value) -> Result {
+    let p = ctx.resolve_path(text_path(path)?)?;
+    let s = fs::read_to_string(&p).map_err(|e| format!("read_text {}: {e}", p.display()))?;
+    Ok(Value::Text(s))
+}
+
+pub fn write_text(ctx: &HostContext, path: &Value, text: &Value) -> Result {
+    if !ctx.allow_fs_write() {
+        return Err("write_text denied by host policy".into());
+    }
+    let p = ctx.resolve_path(text_path(path)?)?;
+    if let Some(parent) = p.parent() {
+        fs::create_dir_all(parent).map_err(|e| format!("write_text mkdir: {e}"))?;
+    }
+    fs::write(&p, text_body(text)?).map_err(|e| format!("write_text {}: {e}", p.display()))?;
+    Ok(Value::None)
+}
+
+pub fn append_text(ctx: &HostContext, path: &Value, text: &Value) -> Result {
+    if !ctx.allow_fs_write() {
+        return Err("append_text denied by host policy".into());
+    }
+    let p = ctx.resolve_path(text_path(path)?)?;
+    use std::io::Write;
+    let mut f = fs::OpenOptions::new()
+        .create(true)
+        .append(true)
+        .open(&p)
+        .map_err(|e| format!("append_text {}: {e}", p.display()))?;
+    f.write_all(text_body(text)?.as_bytes())
+        .map_err(|e| format!("append_text {}: {e}", p.display()))?;
+    Ok(Value::None)
+}
+
+pub fn exists(ctx: &HostContext, path: &Value) -> Result {
+    let p = ctx.resolve_path(text_path(path)?)?;
+    Ok(Value::Bool(p.exists()))
+}
+
+pub fn list_dir(ctx: &HostContext, path: &Value) -> Result {
+    let p = ctx.resolve_path(text_path(path)?)?;
+    let mut names = Vec::new();
+    let rd = fs::read_dir(&p).map_err(|e| format!("list_dir {}: {e}", p.display()))?;
+    for ent in rd {
+        let ent = ent.map_err(|e| format!("list_dir: {e}"))?;
+        names.push(Value::Text(
+            ent.file_name().to_string_lossy().into_owned(),
+        ));
+    }
+    names.sort_by(|a, b| a.as_display().cmp(&b.as_display()));
+    Ok(Value::List(names))
+}
+
+pub fn make_dir(ctx: &HostContext, path: &Value) -> Result {
+    if !ctx.allow_fs_write() {
+        return Err("make_dir denied by host policy".into());
+    }
+    let p = ctx.resolve_path(text_path(path)?)?;
+    fs::create_dir_all(&p).map_err(|e| format!("make_dir {}: {e}", p.display()))?;
+    Ok(Value::None)
+}
+
+pub fn remove(ctx: &HostContext, path: &Value) -> Result {
+    if !ctx.allow_fs_write() {
+        return Err("remove denied by host policy".into());
+    }
+    let p = ctx.resolve_path(text_path(path)?)?;
+    if p.is_dir() {
+        fs::remove_dir_all(&p).map_err(|e| format!("remove {}: {e}", p.display()))?;
+    } else {
+        fs::remove_file(&p).map_err(|e| format!("remove {}: {e}", p.display()))?;
+    }
+    Ok(Value::None)
+}
diff --git a/src/host/json.rs b/src/host/json.rs
new file mode 100644
index 0000000..6d7b714
--- /dev/null
+++ b/src/host/json.rs
@@ -0,0 +1,106 @@
+//! JSON host primitives + Value↔JSON mapping.
+
+use crate::value::Value;
+
+pub fn parse(text: &Value) -> Result {
+    let s = match text {
+        Value::Text(s) => s.as_str(),
+        _ => return Err("json parse needs text".into()),
+    };
+    let v: serde_json::Value =
+        serde_json::from_str(s).map_err(|e| format!("json parse: {e}"))?;
+    json_to_value(&v)
+}
+
+pub fn stringify(value: &Value, indent: Option<&Value>) -> Result {
+    let j = value_to_json(value)?;
+    let pretty = match indent {
+        None => false,
+        Some(Value::Int(n)) => *n > 0,
+        Some(Value::Bool(b)) => *b,
+        Some(Value::None) => false,
+        Some(_) => return Err("json stringify indent must be int or bool".into()),
+    };
+    let s = if pretty {
+        serde_json::to_string_pretty(&j).map_err(|e| format!("json stringify: {e}"))?
+    } else {
+        serde_json::to_string(&j).map_err(|e| format!("json stringify: {e}"))?
+    };
+    Ok(Value::Text(s))
+}
+
+pub fn get(value: &Value, key: &Value) -> Result {
+    let k = match key {
+        Value::Text(s) => s.as_str(),
+        _ => return Err("json get key must be text".into()),
+    };
+    match value {
+        Value::Map(entries) => Ok(entries
+            .iter()
+            .find(|(kk, _)| kk == k)
+            .map(|(_, v)| v.clone())
+            .unwrap_or(Value::None)),
+        _ => Err("json get needs map".into()),
+    }
+}
+
+pub fn keys(value: &Value) -> Result {
+    match value {
+        Value::Map(entries) => Ok(Value::List(
+            entries.iter().map(|(k, _)| Value::Text(k.clone())).collect(),
+        )),
+        _ => Err("json keys needs map".into()),
+    }
+}
+
+fn json_to_value(v: &serde_json::Value) -> Result {
+    Ok(match v {
+        serde_json::Value::Null => Value::None,
+        serde_json::Value::Bool(b) => Value::Bool(*b),
+        serde_json::Value::Number(n) => {
+            if let Some(i) = n.as_i64() {
+                Value::Int(i)
+            } else {
+                Value::Text(n.to_string())
+            }
+        }
+        serde_json::Value::String(s) => Value::Text(s.clone()),
+        serde_json::Value::Array(xs) => {
+            let mut out = Vec::with_capacity(xs.len());
+            for x in xs {
+                out.push(json_to_value(x)?);
+            }
+            Value::List(out)
+        }
+        serde_json::Value::Object(map) => {
+            let mut entries = Vec::with_capacity(map.len());
+            for (k, v) in map {
+                entries.push((k.clone(), json_to_value(v)?));
+            }
+            Value::Map(entries)
+        }
+    })
+}
+
+fn value_to_json(v: &Value) -> Result {
+    Ok(match v {
+        Value::None => serde_json::Value::Null,
+        Value::Bool(b) => serde_json::Value::Bool(*b),
+        Value::Int(n) => serde_json::Value::Number((*n).into()),
+        Value::Text(s) => serde_json::Value::String(s.clone()),
+        Value::List(xs) => {
+            let mut arr = Vec::with_capacity(xs.len());
+            for x in xs {
+                arr.push(value_to_json(x)?);
+            }
+            serde_json::Value::Array(arr)
+        }
+        Value::Map(entries) => {
+            let mut map = serde_json::Map::new();
+            for (k, v) in entries {
+                map.insert(k.clone(), value_to_json(v)?);
+            }
+            serde_json::Value::Object(map)
+        }
+    })
+}
diff --git a/src/host/mod.rs b/src/host/mod.rs
new file mode 100644
index 0000000..12bce24
--- /dev/null
+++ b/src/host/mod.rs
@@ -0,0 +1,126 @@
+//! L0.5 host primitives for official stdlib (`lib/fs`, `time`, …).
+//!
+//! User docs should import L1 wrappers; these `host_*` names are the Rust surface.
+//! Capabilities default **on** (importing a lib means you intend to use it).
+//! Soft side-effects (no process::exit; sleep clamp) apply under view / capture only.
+
+mod dispatch;
+mod fs;
+mod json;
+mod net;
+mod sys;
+mod time;
+
+pub use dispatch::{call_host, HostFn};
+pub use fs::path_under_root;
+
+use std::path::{Path, PathBuf};
+
+/// Host capability flags. Default: all enabled.
+#[derive(Debug, Clone)]
+pub struct HostCaps {
+    pub fs_write: bool,
+    pub exec: bool,
+    pub net: bool,
+}
+
+impl Default for HostCaps {
+    fn default() -> Self {
+        Self {
+            fs_write: true,
+            exec: true,
+            net: true,
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct HostContext {
+    pub caps: HostCaps,
+    pub fs_root: Option,
+    pub cwd: PathBuf,
+    pub argv: Vec,
+    /// Soft mode: do not `process::exit`; honor sleep_limit (view / capture / export).
+    pub soft_side_effects: bool,
+    pub sleep_limit_ms: Option,
+}
+
+impl Default for HostContext {
+    fn default() -> Self {
+        Self {
+            caps: HostCaps::default(),
+            fs_root: None,
+            cwd: std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")),
+            argv: Vec::new(),
+            soft_side_effects: false,
+            sleep_limit_ms: Some(30_000),
+        }
+    }
+}
+
+impl HostContext {
+    pub fn for_run(path: Option<&Path>, caps: HostCaps, argv: Vec) -> Self {
+        let mut ctx = Self::default();
+        ctx.caps = caps;
+        ctx.argv = argv;
+        if let Some(p) = path {
+            if let Some(parent) = p.parent() {
+                let parent = if parent.as_os_str().is_empty() {
+                    PathBuf::from(".")
+                } else {
+                    parent.to_path_buf()
+                };
+                ctx.cwd = parent.clone();
+                ctx.fs_root = Some(parent);
+            }
+        }
+        ctx
+    }
+
+    /// Capture stdout / view / export: soft exit + sleep clamp; same caps as CLI by default.
+    pub fn for_capture(path: Option<&Path>, caps: HostCaps) -> Self {
+        let mut ctx = Self::for_run(path, caps, Vec::new());
+        ctx.soft_side_effects = true;
+        ctx.sleep_limit_ms = Some(0);
+        ctx
+    }
+
+    pub fn allow_fs_write(&self) -> bool {
+        self.caps.fs_write
+    }
+
+    pub fn allow_exec(&self) -> bool {
+        self.caps.exec
+    }
+
+    pub fn allow_net(&self) -> bool {
+        self.caps.net
+    }
+
+    pub fn resolve_path(&self, rel: &str) -> Result {
+        let p = Path::new(rel);
+        let abs = if p.is_absolute() {
+            p.to_path_buf()
+        } else {
+            self.cwd.join(p)
+        };
+        if let Some(root) = &self.fs_root {
+            let root_canon = root.canonicalize().unwrap_or_else(|_| root.clone());
+            let check = abs.canonicalize().unwrap_or_else(|_| abs.clone());
+            if !path_under_root(&check, &root_canon) && !path_under_root(&abs, root) {
+                if let Some(parent) = abs.parent() {
+                    let parent_ok = parent
+                        .canonicalize()
+                        .map(|p| path_under_root(&p, &root_canon))
+                        .unwrap_or_else(|_| path_under_root(parent, root));
+                    if !parent_ok {
+                        return Err(format!("path escapes sandbox root: {}", abs.display()));
+                    }
+                } else {
+                    return Err(format!("path escapes sandbox root: {}", abs.display()));
+                }
+            }
+        }
+        Ok(abs)
+    }
+}
diff --git a/src/host/net.rs b/src/host/net.rs
new file mode 100644
index 0000000..a6852df
--- /dev/null
+++ b/src/host/net.rs
@@ -0,0 +1,152 @@
+//! Minimal HTTP host primitives (HTTP cleartext in v1; HTTPS deferred).
+
+use std::io::{Read, Write};
+use std::net::TcpStream;
+use std::time::Duration;
+
+use crate::host::HostContext;
+use crate::value::Value;
+
+fn as_text<'a>(v: &'a Value, label: &str) -> Result<&'a str, String> {
+    match v {
+        Value::Text(s) => Ok(s.as_str()),
+        _ => Err(format!("{label} must be text")),
+    }
+}
+
+struct UrlParts {
+    host: String,
+    port: u16,
+    path: String,
+}
+
+fn parse_http_url(url: &str) -> Result {
+    let rest = url
+        .strip_prefix("http://")
+        .ok_or_else(|| {
+            if url.starts_with("https://") {
+                "https is not supported yet (use http:// or wait for TLS)".to_string()
+            } else {
+                "url must start with http://".into()
+            }
+        })?;
+    let (hostport, path) = match rest.split_once('/') {
+        Some((h, p)) => (h, format!("/{p}")),
+        None => (rest, "/".into()),
+    };
+    let (host, port) = if let Some((h, p)) = hostport.split_once(':') {
+        let port: u16 = p
+            .parse()
+            .map_err(|_| format!("invalid port in url: {p}"))?;
+        (h.to_string(), port)
+    } else {
+        (hostport.to_string(), 80)
+    };
+    if host.is_empty() {
+        return Err("url missing host".into());
+    }
+    Ok(UrlParts { host, port, path })
+}
+
+fn http_exchange(
+    method: &str,
+    url: &str,
+    body: Option<&str>,
+    content_type: &str,
+) -> Result<(u16, String), String> {
+    let parts = parse_http_url(url)?;
+    let addr = format!("{}:{}", parts.host, parts.port);
+    let mut stream = TcpStream::connect(&addr).map_err(|e| format!("http connect {addr}: {e}"))?;
+    stream
+        .set_read_timeout(Some(Duration::from_secs(10)))
+        .ok();
+    stream
+        .set_write_timeout(Some(Duration::from_secs(10)))
+        .ok();
+
+    let body = body.unwrap_or("");
+    let mut req = format!(
+        "{method} {path} HTTP/1.0\r\nHost: {host}\r\nConnection: close\r\nUser-Agent: marqdo\r\n",
+        path = parts.path,
+        host = parts.host,
+    );
+    if method == "POST" {
+        req.push_str(&format!(
+            "Content-Type: {content_type}\r\nContent-Length: {}\r\n",
+            body.len()
+        ));
+    }
+    req.push_str("\r\n");
+    if method == "POST" {
+        req.push_str(body);
+    }
+    stream
+        .write_all(req.as_bytes())
+        .map_err(|e| format!("http write: {e}"))?;
+
+    let mut buf = Vec::new();
+    stream
+        .read_to_end(&mut buf)
+        .map_err(|e| format!("http read: {e}"))?;
+    if buf.len() > 2 * 1024 * 1024 {
+        return Err("http response exceeds 2MiB limit".into());
+    }
+    let text = String::from_utf8_lossy(&buf);
+    let (header, body) = text.split_once("\r\n\r\n").unwrap_or((text.as_ref(), ""));
+    let status = header
+        .lines()
+        .next()
+        .and_then(|line| line.split_whitespace().nth(1))
+        .and_then(|s| s.parse::().ok())
+        .unwrap_or(0);
+    Ok((status, body.to_string()))
+}
+
+pub fn http_get(ctx: &HostContext, url: &Value) -> Result {
+    if !ctx.allow_net() {
+        return Err("http_get denied by host policy".into());
+    }
+    let url = as_text(url, "url")?;
+    let (status, body) = http_exchange("GET", url, None, "")?;
+    Ok(Value::Map(vec![
+        ("status".into(), Value::Int(status as i64)),
+        ("body".into(), Value::Text(body)),
+    ]))
+}
+
+pub fn http_post(
+    ctx: &HostContext,
+    url: &Value,
+    body: &Value,
+    content_type: Option<&Value>,
+) -> Result {
+    if !ctx.allow_net() {
+        return Err("http_post denied by host policy".into());
+    }
+    let url = as_text(url, "url")?;
+    let body = as_text(body, "body")?;
+    let ct = match content_type {
+        Some(v) => as_text(v, "content_type")?,
+        None => "text/plain; charset=utf-8",
+    };
+    let (status, resp) = http_exchange("POST", url, Some(body), ct)?;
+    Ok(Value::Map(vec![
+        ("status".into(), Value::Int(status as i64)),
+        ("body".into(), Value::Text(resp)),
+    ]))
+}
+
+pub fn url_encode(text: &Value) -> Result {
+    let s = as_text(text, "text")?;
+    Ok(Value::Text(
+        s.bytes()
+            .map(|b| match b {
+                b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
+                    (b as char).to_string()
+                }
+                b' ' => "+".into(),
+                _ => format!("%{b:02X}"),
+            })
+            .collect(),
+    ))
+}
diff --git a/src/host/sys.rs b/src/host/sys.rs
new file mode 100644
index 0000000..c4d9e0c
--- /dev/null
+++ b/src/host/sys.rs
@@ -0,0 +1,79 @@
+//! System / process host primitives.
+
+use std::process::Command;
+
+use crate::host::HostContext;
+use crate::value::Value;
+
+fn as_text<'a>(v: &'a Value, label: &str) -> Result<&'a str, String> {
+    match v {
+        Value::Text(s) => Ok(s.as_str()),
+        _ => Err(format!("{label} must be text")),
+    }
+}
+
+fn as_i64(v: &Value, label: &str) -> Result {
+    match v {
+        Value::Int(n) => Ok(*n),
+        _ => Err(format!("{label} must be int")),
+    }
+}
+
+pub fn env_get(name: &Value) -> Result {
+    let key = as_text(name, "name")?;
+    Ok(match std::env::var(key) {
+        Ok(v) => Value::Text(v),
+        Err(_) => Value::None,
+    })
+}
+
+pub fn env_set(name: &Value, value: &Value) -> Result {
+    let key = as_text(name, "name")?;
+    let val = as_text(value, "value")?;
+    std::env::set_var(key, val);
+    Ok(Value::None)
+}
+
+pub fn args(ctx: &HostContext) -> Result {
+    Ok(Value::List(
+        ctx.argv.iter().map(|s| Value::Text(s.clone())).collect(),
+    ))
+}
+
+pub fn cwd(ctx: &HostContext) -> Result {
+    Ok(Value::Text(ctx.cwd.display().to_string()))
+}
+
+pub fn exit(ctx: &HostContext, code: &Value) -> Result {
+    let c = as_i64(code, "code")?;
+    if ctx.soft_side_effects {
+        return Err(format!("exit {c} (soft mode does not terminate process)"));
+    }
+    std::process::exit(c as i32);
+}
+
+pub fn exec(ctx: &HostContext, cmd: &Value, args: Option<&Value>) -> Result {
+    if !ctx.allow_exec() {
+        return Err("exec denied by host policy".into());
+    }
+    let cmd = as_text(cmd, "cmd")?;
+    let mut command = Command::new(cmd);
+    command.current_dir(&ctx.cwd);
+    if let Some(a) = args {
+        match a {
+            Value::List(xs) => {
+                for x in xs {
+                    command.arg(x.as_display());
+                }
+            }
+            Value::Text(s) => {
+                command.arg(s);
+            }
+            _ => return Err("exec args must be list or text".into()),
+        }
+    }
+    let status = command
+        .status()
+        .map_err(|e| format!("exec `{cmd}`: {e}"))?;
+    Ok(Value::Int(status.code().unwrap_or(1) as i64))
+}
diff --git a/src/host/time.rs b/src/host/time.rs
new file mode 100644
index 0000000..fdba51d
--- /dev/null
+++ b/src/host/time.rs
@@ -0,0 +1,71 @@
+//! Time host primitives.
+
+use std::thread;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+
+use chrono::{DateTime, NaiveDateTime, Utc};
+
+use crate::host::HostContext;
+use crate::value::Value;
+
+pub fn now_unix() -> Result {
+    let secs = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_err(|e| format!("now_unix: {e}"))?
+        .as_secs();
+    Ok(Value::Int(secs as i64))
+}
+
+pub fn now_ms() -> Result {
+    let ms = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_err(|e| format!("now_ms: {e}"))?
+        .as_millis();
+    Ok(Value::Int(ms as i64))
+}
+
+fn as_i64(v: &Value, label: &str) -> Result {
+    match v {
+        Value::Int(n) => Ok(*n),
+        _ => Err(format!("{label} must be int")),
+    }
+}
+
+fn as_text<'a>(v: &'a Value, label: &str) -> Result<&'a str, String> {
+    match v {
+        Value::Text(s) => Ok(s.as_str()),
+        _ => Err(format!("{label} must be text")),
+    }
+}
+
+pub fn format_time(unix: &Value, pattern: &Value) -> Result {
+    let secs = as_i64(unix, "unix")?;
+    let pat = as_text(pattern, "pattern")?;
+    let dt = DateTime::::from_timestamp(secs, 0)
+        .ok_or_else(|| format!("invalid unix timestamp: {secs}"))?;
+    Ok(Value::Text(dt.format(pat).to_string()))
+}
+
+pub fn parse_time(text: &Value, pattern: &Value) -> Result {
+    let t = as_text(text, "text")?;
+    let pat = as_text(pattern, "pattern")?;
+    let dt = NaiveDateTime::parse_from_str(t, pat).map_err(|e| format!("parse_time: {e}"))?;
+    Ok(Value::Int(dt.and_utc().timestamp()))
+}
+
+pub fn sleep_ms(ctx: &HostContext, ms: &Value) -> Result {
+    let n = as_i64(ms, "ms")?;
+    if n < 0 {
+        return Err("sleep_ms must be >= 0".into());
+    }
+    let n = n as u64;
+    if let Some(lim) = ctx.sleep_limit_ms {
+        if n > lim {
+            return Err(format!("sleep_ms {n} exceeds limit {lim}"));
+        }
+    }
+    if n > 0 {
+        thread::sleep(Duration::from_millis(n));
+    }
+    Ok(Value::None)
+}
diff --git a/src/interp.rs b/src/interp.rs
index 4e8471a..0bfbb74 100644
--- a/src/interp.rs
+++ b/src/interp.rs
@@ -13,6 +13,7 @@ use crate::builtin::{
 };
 use crate::debug::emit_trace;
 use crate::diagnostics::{bail_at, Span};
+use crate::host::{call_host, HostContext, HostFn};
 use crate::input_feed::InputFeed;
 use crate::value::Value;
 
@@ -23,6 +24,7 @@ pub struct Interpreter {
     pub captured_stdout: String,
     current_span: Span,
     input: InputFeed,
+    host: HostContext,
 }
 
 struct Env {
@@ -59,6 +61,7 @@ impl Interpreter {
             captured_stdout: String::new(),
             current_span: Span::new(1, 1),
             input: InputFeed::new(false, Vec::new()),
+            host: HostContext::for_run(path, Default::default(), Vec::new()),
         }
     }
 
@@ -70,6 +73,7 @@ impl Interpreter {
             captured_stdout: String::new(),
             current_span: Span::new(1, 1),
             input: InputFeed::new(true, Vec::new()),
+            host: HostContext::for_capture(path, Default::default()),
         }
     }
 
@@ -78,6 +82,11 @@ impl Interpreter {
         self
     }
 
+    pub fn with_host(mut self, host: HostContext) -> Self {
+        self.host = host;
+        self
+    }
+
     fn err(&self, message: impl Into) -> anyhow::Error {
         bail_at(self.path.as_deref(), self.current_span, message)
     }
@@ -517,6 +526,21 @@ impl Interpreter {
                     .ok_or_else(|| self.err("at requires index"))?;
                 return builtin_at(value, index).map_err(|m| self.err(m));
             }
+            other if HostFn::from_name(other).is_some() => {
+                let hf = HostFn::from_name(other).unwrap();
+                let mut params: Vec =
+                    hf.required_params().iter().map(|s| (*s).to_string()).collect();
+                for p in hf.optional_params() {
+                    params.push((*p).to_string());
+                }
+                let bound = bind_args(¶ms, &ev_args, true).map_err(|m| self.err(m))?;
+                for req in hf.required_params() {
+                    if !bound.contains_key(*req) {
+                        return Err(self.err(format!("{} requires `{req}`", hf.name())));
+                    }
+                }
+                return call_host(&self.host, hf, &bound).map_err(|m| self.err(m));
+            }
             _ => {}
         }
 
diff --git a/src/lib.rs b/src/lib.rs
index ef412d7..87abde4 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -11,6 +11,7 @@ pub mod capture;
 pub mod catalog;
 pub mod debug;
 pub mod diagnostics;
+pub mod host;
 pub mod input_feed;
 pub mod interp;
 pub mod lex;
@@ -23,6 +24,7 @@ use std::path::Path;
 
 use anyhow::{bail, Result};
 
+use crate::host::{HostCaps, HostContext};
 use crate::ast::format_ast_dump;
 use crate::bytecode::{compile_module, Vm};
 use crate::capture::RunCapture;
@@ -48,7 +50,7 @@ impl Backend {
 }
 
 /// Options for a single `run` / dump invocation.
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone)]
 pub struct RunOptions {
     pub dump_lines: bool,
     pub dump_tokens: bool,
@@ -59,6 +61,36 @@ pub struct RunOptions {
     pub backend: Backend,
     /// Preset lines consumed by `input` (from `--stdin-file` or view).
     pub stdin_lines: Vec,
+    pub allow_fs_write: bool,
+    pub allow_exec: bool,
+    pub allow_net: bool,
+    /// Exposed via `host_args` / `args`.
+    pub argv: Vec,
+    /// Override filesystem sandbox root (default: source file's directory).
+    pub fs_root: Option,
+    /// Sleep clamp when capturing (None = host default; view export uses `Some(0)`).
+    pub sleep_limit_ms: Option,
+}
+
+impl Default for RunOptions {
+    fn default() -> Self {
+        Self {
+            dump_lines: false,
+            dump_tokens: false,
+            dump_ast: false,
+            dump_sema: false,
+            dump_bytecode: false,
+            trace_eval: false,
+            backend: Backend::default(),
+            stdin_lines: Vec::new(),
+            allow_fs_write: true,
+            allow_exec: true,
+            allow_net: true,
+            argv: Vec::new(),
+            fs_root: None,
+            sleep_limit_ms: None,
+        }
+    }
 }
 
 impl RunOptions {
@@ -70,8 +102,7 @@ impl RunOptions {
             dump_sema: true,
             dump_bytecode: true,
             trace_eval: true,
-            backend: Backend::Tree,
-            stdin_lines: Vec::new(),
+            ..Self::default()
         }
     }
 
@@ -83,6 +114,14 @@ impl RunOptions {
             || self.dump_bytecode
             || self.trace_eval
     }
+
+    pub fn host_caps(&self) -> HostCaps {
+        HostCaps {
+            fs_write: self.allow_fs_write,
+            exec: self.allow_exec,
+            net: self.allow_net,
+        }
+    }
 }
 
 /// Run a `.mq.md` program (prints to real stdout).
@@ -128,8 +167,10 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result {
 
     match opts.backend {
         Backend::Tree => {
+            let host = HostContext::for_run(Some(path), opts.host_caps(), opts.argv.clone());
             let mut interp = Interpreter::new(Some(path), opts.trace_eval)
-                .with_stdin(stdin_lines.clone());
+                .with_stdin(stdin_lines.clone())
+                .with_host(host);
             if opts.trace_eval {
                 eprintln!("=== marqdo: trace-eval ({path_label}) ===");
             }
@@ -143,9 +184,11 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result {
             if opts.dump_bytecode {
                 print!("{}", program.disassemble());
             }
+            let host = HostContext::for_run(Some(path), opts.host_caps(), opts.argv.clone());
             let mut vm = Vm::new(Some(path))
                 .with_stdin(stdin_lines)
-                .with_trace(opts.trace_eval);
+                .with_trace(opts.trace_eval)
+                .with_host(host);
             if opts.trace_eval {
                 eprintln!("=== marqdo: trace-eval ({path_label}) ===");
             }
@@ -173,7 +216,17 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result {
     let module = load_module(path)?;
     match opts.backend {
         Backend::Tree => {
-            let mut interp = Interpreter::with_capture(Some(path), false).with_stdin(stdin_lines);
+            let mut host = HostContext::for_capture(Some(path), opts.host_caps());
+            host.argv = opts.argv.clone();
+            if let Some(root) = &opts.fs_root {
+                host.fs_root = Some(root.clone());
+            }
+            if let Some(lim) = opts.sleep_limit_ms {
+                host.sleep_limit_ms = Some(lim);
+            }
+            let mut interp = Interpreter::with_capture(Some(path), false)
+                .with_stdin(stdin_lines)
+                .with_host(host);
             let value = interp.run_module(&module)?;
             Ok(RunCapture {
                 stdout: interp.captured_stdout,
@@ -182,7 +235,17 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result {
         }
         Backend::Bytecode => {
             let program = compile_module(Some(path), &module)?;
-            let mut vm = Vm::with_capture(Some(path)).with_stdin(stdin_lines);
+            let mut host = HostContext::for_capture(Some(path), opts.host_caps());
+            host.argv = opts.argv.clone();
+            if let Some(root) = &opts.fs_root {
+                host.fs_root = Some(root.clone());
+            }
+            if let Some(lim) = opts.sleep_limit_ms {
+                host.sleep_limit_ms = Some(lim);
+            }
+            let mut vm = Vm::with_capture(Some(path))
+                .with_stdin(stdin_lines)
+                .with_host(host);
             let value = vm.run(&program)?;
             Ok(RunCapture {
                 stdout: vm.captured_stdout,
diff --git a/src/main.rs b/src/main.rs
index cc0507f..522ddd7 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -156,6 +156,7 @@ fn try_main() -> Result {
                     trace_eval,
                     backend: backend.into(),
                     stdin_lines,
+                    ..RunOptions::default()
                 }
             };
             if dump_all {
diff --git a/src/value.rs b/src/value.rs
index 2a955f2..103522b 100644
--- a/src/value.rs
+++ b/src/value.rs
@@ -10,6 +10,8 @@ pub enum Value {
     Text(String),
     /// Single-column table rows (v0); multi-column later.
     List(Vec),
+    /// JSON object / string-keyed map (insertion order).
+    Map(Vec<(String, Value)>),
 }
 
 impl Value {
@@ -20,6 +22,7 @@ impl Value {
             Value::Int(n) => *n != 0,
             Value::Text(s) => !s.is_empty(),
             Value::List(xs) => !xs.is_empty(),
+            Value::Map(xs) => !xs.is_empty(),
         }
     }
 
@@ -31,6 +34,7 @@ impl Value {
             Value::Int(n) => n.to_string(),
             Value::Text(s) => s.clone(),
             Value::List(_) => "".into(),
+            Value::Map(_) => "".into(),
         }
     }
 }
diff --git a/src/view/mod.rs b/src/view/mod.rs
index 1aff967..7e99330 100644
--- a/src/view/mod.rs
+++ b/src/view/mod.rs
@@ -130,7 +130,7 @@ fn handle(root: &ViewRoot, request: Request) -> Result<()> {
             if let Some(first) = root.files.first() {
                 let rel = first.to_string_lossy().replace('\\', "/");
                 let resolved = resolve_rel(root, &rel)?;
-                let vm = build_file_view(&resolved, &rel, &[])?;
+                let vm = build_file_view(root, &resolved, &rel, &[], true)?;
                 let body = page_file(&root.files, &rel, &vm, &LinkMode::Live);
                 respond_html(request, body)
             } else {
@@ -143,7 +143,7 @@ fn handle(root: &ViewRoot, request: Request) -> Result<()> {
             let stdin_raw = query_param(query, "stdin").unwrap_or_default();
             let stdin_lines = split_stdin_text(&stdin_raw);
             let resolved = resolve_rel(root, &rel)?;
-            let vm = build_file_view(&resolved, &rel, &stdin_lines)?;
+            let vm = build_file_view(root, &resolved, &rel, &stdin_lines, true)?;
             let body = page_file(&root.files, &rel, &vm, &LinkMode::Live);
             respond_html(request, body)
         }
@@ -160,9 +160,11 @@ fn handle(root: &ViewRoot, request: Request) -> Result<()> {
 }
 
 pub(crate) fn build_file_view(
+    root: &ViewRoot,
     abs: &Path,
     rel: &str,
     stdin_lines: &[String],
+    live: bool,
 ) -> Result {
     let source = fs::read_to_string(abs).with_context(|| format!("read {}", abs.display()))?;
     let structure = match crate::load::load_module(abs) {
@@ -173,10 +175,12 @@ pub(crate) fn build_file_view(
         ),
     };
     let effective = effective_stdin(&source, stdin_lines);
-    let opts = RunOptions {
-        stdin_lines: effective.clone(),
-        ..RunOptions::default()
-    };
+    // Same host caps as `marqdo run`. Soft exit + sleep clamp only.
+    let mut opts = RunOptions::default();
+    opts.stdin_lines = effective.clone();
+    opts.sleep_limit_ms = if live { Some(30_000) } else { Some(0) };
+    // Optional: sandbox to the whole view tree so sibling folders are reachable.
+    opts.fs_root = Some(root.root.clone());
     let (stdout, stderr, ok) = match run_file_capture(abs, &opts) {
         Ok(cap) => (cap.stdout, String::new(), true),
         Err(e) => (
diff --git a/src/view/output.rs b/src/view/output.rs
index 37e318e..2e41452 100644
--- a/src/view/output.rs
+++ b/src/view/output.rs
@@ -25,7 +25,7 @@ pub fn write_static(opts: OutputOptions) -> Result<()> {
     for rel_pb in &root.files {
         let rel = rel_pb.to_string_lossy().replace('\\', "/");
         let abs = resolve_abs(&root, &rel)?;
-        let mut vm = build_file_view(&abs, &rel, &[])?;
+        let mut vm = build_file_view(&root, &abs, &rel, &[], false)?;
         if opts.no_exec {
             vm.stdout.clear();
             vm.stderr = "execution skipped (--no-exec)".into();
diff --git a/tests/gold.rs b/tests/gold.rs
index 42683c1..06deaeb 100644
--- a/tests/gold.rs
+++ b/tests/gold.rs
@@ -546,6 +546,48 @@ fn view_output_writes_html() {
     assert!(dir.join("pages").join("hello.mq.md.html").exists());
 }
 
+#[test]
+fn lib_fs_read() {
+    assert_out("tests/lib/fs-read.mq.md", "exists\nhello-lib");
+}
+
+#[test]
+fn lib_fs_read_zh() {
+    assert_out("tests/lib/文件-读.mq.md", "存在\nhello-lib");
+}
+
+#[test]
+fn lib_time_format() {
+    assert_out("tests/lib/time-format.mq.md", "1970-01-01\n0");
+}
+
+#[test]
+fn lib_json_roundtrip() {
+    assert_out(
+        "tests/lib/json-roundtrip.mq.md",
+        "map\n1\n{\"a\":1,\"b\":\"x\"}",
+    );
+}
+
+#[test]
+fn lib_sys_cwd() {
+    assert_out("tests/lib/sys-cwd.mq.md", "cwd-ok");
+}
+
+#[test]
+fn lib_net_encode() {
+    assert_out("tests/lib/net-encode.mq.md", "a+b");
+}
+
+#[test]
+fn bytecode_lib_json() {
+    assert_out_backend(
+        "tests/lib/json-roundtrip.mq.md",
+        "bytecode",
+        "map\n1\n{\"a\":1,\"b\":\"x\"}",
+    );
+}
+
 fn tempfile_dir(prefix: &str) -> std::path::PathBuf {
     let dir = std::env::temp_dir().join(format!(
         "{prefix}-{}",
diff --git a/tests/lib/fixtures/hello.txt b/tests/lib/fixtures/hello.txt
new file mode 100644
index 0000000..6b0e869
--- /dev/null
+++ b/tests/lib/fixtures/hello.txt
@@ -0,0 +1 @@
+hello-lib
diff --git a/tests/lib/fixtures/sample.json b/tests/lib/fixtures/sample.json
new file mode 100644
index 0000000..6572184
--- /dev/null
+++ b/tests/lib/fixtures/sample.json
@@ -0,0 +1 @@
+{"a":1,"b":"x"}
diff --git a/tests/lib/fs-read.mq.md b/tests/lib/fs-read.mq.md
new file mode 100644
index 0000000..b9bfedd
--- /dev/null
+++ b/tests/lib/fs-read.mq.md
@@ -0,0 +1,17 @@
+---
+title: fs read/exists
+> lib/fs.mq.md
+---
+
+# main
+
+*`ok` = > exists path=hello.txt *
+
++ `ok`
+  > print text=exists
++ *
+  > print text=missing
+
+*`t` = > read_text path=hello.txt *
+
+> print text=`t`
diff --git a/tests/lib/hello.txt b/tests/lib/hello.txt
new file mode 100644
index 0000000..7b55f10
--- /dev/null
+++ b/tests/lib/hello.txt
@@ -0,0 +1 @@
+hello-lib
\ No newline at end of file
diff --git a/tests/lib/json-roundtrip.mq.md b/tests/lib/json-roundtrip.mq.md
new file mode 100644
index 0000000..81cbc0b
--- /dev/null
+++ b/tests/lib/json-roundtrip.mq.md
@@ -0,0 +1,23 @@
+---
+title: json roundtrip
+> lib/fs.mq.md
+> lib/json.mq.md
+---
+
+# main
+
+*`raw` = > read_text path=sample.json *
+
+*`obj` = > parse text=`raw` *
+
+*`ty` = > type `obj` *
+
+> print text=`ty`
+
+*`a` = > get value=`obj` key=a *
+
+> print text=`a`
+
+*`out` = > stringify value=`obj` *
+
+> print text=`out`
diff --git a/tests/lib/net-encode.mq.md b/tests/lib/net-encode.mq.md
new file mode 100644
index 0000000..33a11f0
--- /dev/null
+++ b/tests/lib/net-encode.mq.md
@@ -0,0 +1,10 @@
+---
+title: net url_encode
+> lib/net.mq.md
+---
+
+# main
+
+*`e` = > url_encode text=a b *
+
+> print text=`e`
diff --git a/tests/lib/sample.json b/tests/lib/sample.json
new file mode 100644
index 0000000..6572184
--- /dev/null
+++ b/tests/lib/sample.json
@@ -0,0 +1 @@
+{"a":1,"b":"x"}
diff --git a/tests/lib/sys-cwd.mq.md b/tests/lib/sys-cwd.mq.md
new file mode 100644
index 0000000..53606fb
--- /dev/null
+++ b/tests/lib/sys-cwd.mq.md
@@ -0,0 +1,15 @@
+---
+title: sys cwd
+> lib/sys.mq.md
+---
+
+# main
+
+*`d` = > cwd *
+
+*`n` = > len `d` *
+
++ `n` > 0
+  > print text=cwd-ok
++ *
+  > print text=cwd-empty
diff --git a/tests/lib/time-format.mq.md b/tests/lib/time-format.mq.md
new file mode 100644
index 0000000..71d2342
--- /dev/null
+++ b/tests/lib/time-format.mq.md
@@ -0,0 +1,16 @@
+---
+title: time format/parse
+> lib/time.mq.md
+---
+
+# main
+
+*`s` = > format unix=0 pattern=%Y-%m-%d *
+
+> print text=`s`
+
+*`u` = > parse text=1970-01-01 00:00:00 pattern=%Y-%m-%d %H:%M:%S *
+
+> print text=`u`
+
+> sleep_ms ms=0
diff --git a/tests/lib/文件-读.mq.md b/tests/lib/文件-读.mq.md
new file mode 100644
index 0000000..1634154
--- /dev/null
+++ b/tests/lib/文件-读.mq.md
@@ -0,0 +1,17 @@
+---
+title: 中文文件库
+> lib/文件.mq.md
+---
+
+# main
+
+*`有` = > 存在 路径=hello.txt *
+
++ `有`
+  > 打印 内容=存在
++ *
+  > 打印 内容=缺失
+
+*`t` = > 读文本 路径=hello.txt *
+
+> 打印 内容=`t`