Files
marqdo/public/stdlib/foreign.mq.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

5.7 KiB
Executable File

markup, title, description, import, stdin
markup title description import stdin
occlusion lib/foreign — foreign kernels v2 Structured execution, JSON calls, parallel fan-out, persistent kernels and an explicit state bridge
foreign
lib/foreign.mq.md
21

main

返回 类型 说明
result any None; execute this page's documented steps in order and observe their output or stated effects

lib/foreign runs code fences and inline sources with local interpreters. v2 keeps the Markdown surface unchanged while adding structured records, JSON in/out, parallel fan-out, persistent Python/Node kernels and an explicit state bridge.

The same file is still a document: a bound fence is readable Markdown, and foreign.* turns it into an executable unit.


Probe before you run.

We first node = Compute node for the next step.

We now [Display this step's result](> print text=ok)). We now [Display this step's result](> print text=version)).

probe returns {lang, cmd, path, ok, version, error}. Omit lang to inspect every known language.


A structured record, not just stdout.

marker =

console.log(new Intl.NumberFormat("en-US", {style:"currency", currency:"CNY"}).format(950));

We first record = Compute record for the next step.

We now [Display this step's result](> print text=ok)). We now [Display this step's result](> print text=stdout)). We now [Display this step's result](> print text=code)).

invoke never throws on a process failure. Read ok, code, stdout, stderr, ms, timed_out, truncated, result and error from one record.


JSON in, JSON out.

format_money =

let input = "";
process.stdin.on("data", chunk => { input += chunk; });
process.stdin.on("end", () => {
  console.log(JSON.stringify(new Intl.NumberFormat("en-US", {style:"currency", currency:"CNY"}).format(JSON.parse(input))));
});

We first single = [Compute single](foreign.call(code=format_money, input=21)) for the next step.

We now [Display this step's result](> print text=single).

The input is encoded as JSON on stdin; the last stdout value is parsed as JSON. Use output="json" with invoke when you also want the raw record.


Parallel fan-out.

numbers =

value
1
2
3
4

This single-column bound table is a native list of numbers, ready for the batch call. We formatted_batch = [Format each amount while retaining input order](foreign.call_many(code=format_money, inputs=numbers, concurrency=4)).

We now [Display this step's result](> print text=formatted_batch).

call_many applies one program to every input, runs independently, preserves input order, and returns parsed JSON results. run_many does the same for full invoke-option maps.


A persistent kernel.

We first session = Compute session for the next step.

We first first = [Compute first](foreign.session_eval(id=session, source="var money = new Intl.NumberFormat("en-US", {style:"currency", currency:"CNY"});")) for the next step.

We first second = [Compute second](foreign.session_eval(id=session, source="money.format(21)")) for the next step.

We now [Display this step's result](> print text=result)).

Variables created in the first evaluation survive into the second. The kernel is not a shell: use session_eval, session_get, session_names, then session_close.


The explicit state bridge.

We [Copy the explicit rate into the existing kernel](foreign.session_set(id=session, name="rate", value=0.08)).

We first rate = [Compute rate](foreign.session_get(id=session, name="rate")) for the next step.

We now [Display this step's result](> print text=rate).

After reading the copied value, we Close this persistent formatting kernel.

This is a JSON copy, not shared memory. The kernel receives a value; Marqdo receives a value. There is no implicit mirroring and no hidden global namespace.


Cells in view.

foreign.session owns the document's kernel state. The kernel and cell order are ordinary tables passed as arguments; the names are free:

`分析内核` =

| 名称 | 语言 | 命令 | 说明 |
|------|------|------|------|
| 分析 | node | | shared analysis |
| 复核 | node | | isolated review |

`分析单元` =

| 单元 | 内核 | 说明 |
|------|------|------|
| 准备数据 | 分析 | write state |
| 计算指标 | 分析 | read state |
| 独立复核 | 复核 | isolated kernel |

`会话` = > foreign.session kernels=`分析内核` cells=`分析单元`

view consumes the 会话 handle and adds Run All, Step, kernel switching, a journal and per-cell state. Without 会话, view cells are stateless one-shot runs: same shell, no persistent kernel. There is no second CLI mode. See the native-first Intl workflow in features/19-foreign-view-cells.mq.md.


Safety defaults.

Boundary Default
Execution requires the host execution capability
Shell no shell; arguments are split explicitly
Output bounded, with truncated
Timeout process group killed on Unix / taskkill /T on Windows
CWD starts at the granted root; the child retains normal OS authority
Parallelism capped fan-out; each item isolated

Read the full API in ../../lib/foreign.mq.md and the design in ../../doc/design/foreign-kernel.md.