docs(public): showcase foreign v2, OKF and EKC
Rewrite the public foreign reference, add bilingual complex Python notebook and OKF/EKC pages, and expand both homepages with executable foreign, notebook, knowledge and preflight examples.
This commit is contained in:
1 parent
81f9ea0072
commit
e6f05c7748
12 files changed
+1015
-20
No files matched your search
@@ -4,6 +4,7 @@
|
||||
|
||||
### Added
|
||||
|
||||
- **用户静态站(外联 / OKF / EKC)**:新增中英双语 `features/19-foreign-notebook` 与 `features/20-okf-ekc`,重写 `stdlib/foreign`,首页加入「一份文件三个面」、外联 Python 运行、Notebook 表、OKF/EKC 与 preflight 说明。
|
||||
- **`lib/foreign` F0/F1**:`invoke` 结构化记录(`ok`/`code`/`stdout`/`stderr`/`ms`/`timed_out`/`truncated`/`result`);`run`/`run_lang` 新增 `env`/`cwd`/`timeout`/`args`/`max_output`;15 个语言预设;`probe`/`register`/`unset`/`load_config`;`.marqdo/foreign.toml`。
|
||||
- **`lib/foreign` F2**:JSON 进 / JSON 出 `call`;并行 `run_many` / `call_many`(有序、单项隔离、并发上限);`invoke` 的 `input` / `output` / `result` / `result_error`。
|
||||
- **`lib/foreign` F3/F3.5**:Python / Node 持久会话 `session_open` / `session_eval` / `session_close` / `session_list`;状态桥 `session_set` / `session_get` / `session_names`;会话超时即杀、崩溃隔离、drop 清理。
|
||||
|
||||
@@ -37,6 +37,59 @@ print("hello-from-python")
|
||||
|
||||
Under Markdown this stays easy to read — which is the point: code as documentation, documentation as code.
|
||||
|
||||
One file, three surfaces.
|
||||
|
||||
| Surface | What it is |
|
||||
|---|---|
|
||||
| Document | ordinary Markdown: prose, tables, links and fenced code |
|
||||
| Program | the same markers are executable: assignments, calls, returns |
|
||||
| Knowledge | frontmatter, links and generated catalog entries an agent can query |
|
||||
|
||||
The static site you are reading is generated from these files, so the examples are not screenshots. Run the same source and you get the same page.
|
||||
|
||||
Foreign v2 is a good example. Probe Python, then run the bound fence:
|
||||
|
||||
**python = > foreign.probe lang="python"**
|
||||
|
||||
1. [ok](`python`)
|
||||
**hello = > foreign.run code=`hi`**
|
||||
> print text=`hello`
|
||||
2. *
|
||||
> print text="(python3 not found — install Python to run this cell)"
|
||||
|
||||
The same module also supports JSON calls, parallel fan-out, persistent kernels and an explicit state bridge. See [stdlib/foreign.mq.md](stdlib/foreign.mq.md) and the full Python walkthrough in [features/19-foreign-notebook.mq.md](features/19-foreign-notebook.mq.md).
|
||||
|
||||
A notebook is still a document. Named kernels and a cell order are ordinary bound tables:
|
||||
|
||||
```text
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 | 说明 |
|
||||
|------|------|------|
|
||||
| 分析 | python | shared state |
|
||||
| 复核 | python | isolated state |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | write |
|
||||
| 计算指标 | 分析 | read |
|
||||
| 独立复核 | 复核 | validate |
|
||||
```
|
||||
|
||||
Live view turns that into Run All, Step, per-cell kernels, a journal and a state panel. Program mode still runs the file as one program.
|
||||
|
||||
Documentation becomes knowledge when it can be discovered, verified and reused. OKF supplies the portable Markdown + YAML shape; EKC projects the repository into catalog layers L0–L4, a graph and an engineering preflight. The source `.mq.md` remains the only authority; generated artifacts are marked and rebuildable.
|
||||
|
||||
| Loop | Question |
|
||||
|---|---|
|
||||
| OKF | How do people and agents share a readable knowledge page? |
|
||||
| EKC | What existing capability, decision, constraint or failure should be reused before creating more? |
|
||||
| Preflight | REUSE → ADAPT → CREATE |
|
||||
|
||||
Read [features/20-okf-ekc.mq.md](features/20-okf-ekc.mq.md) for the concepts and commands.
|
||||
|
||||
Welcome again — enjoy exploring Marqdo.
|
||||
|
||||
## greet
|
||||
|
||||
@@ -37,6 +37,59 @@ print("hello-from-python")
|
||||
|
||||
这些在 Markdown 里读起来仍然像文章——这就是 marqdo 想坚持的:代码即文档,文档即代码。
|
||||
|
||||
一份文件,三个面。
|
||||
|
||||
| 面 | 是什么 |
|
||||
|---|---|
|
||||
| 文档 | 普通 Markdown:叙述、表格、链接、围栏代码 |
|
||||
| 程序 | 同一批标记可执行:赋值、调用、返回 |
|
||||
| 知识 | frontmatter、链接与生成的 catalog 条目,Agent 可查询 |
|
||||
|
||||
你正在读的静态站就是由这些文件生成的,所以示例不是截图。运行同一份源,会得到同一页。
|
||||
|
||||
外联 v2 是个好例子。先探测 Python,再运行绑定围栏:
|
||||
|
||||
**python = > 外联.探测 语言="python"**
|
||||
|
||||
1. [ok](`python`)
|
||||
**问候 = > 外联.运行 代码=`hi`**
|
||||
> 打印 内容=`问候`
|
||||
2. *
|
||||
> 打印 内容="(未找到 python3 — 安装 Python 后可运行此单元)"
|
||||
|
||||
同一个模块还支持 JSON 调用、并行扇出、持久内核与显式状态桥。见 [stdlib/外联.mq.md](stdlib/外联.mq.md) 与完整 Python 示例 [features/19-外联Notebook.mq.md](features/19-外联Notebook.mq.md)。
|
||||
|
||||
Notebook 仍然是一篇文档。命名内核与单元顺序就是普通绑定表:
|
||||
|
||||
```text
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 | 说明 |
|
||||
|------|------|------|
|
||||
| 分析 | python | 共享状态 |
|
||||
| 复核 | python | 隔离状态 |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | 写入 |
|
||||
| 计算指标 | 分析 | 读取 |
|
||||
| 独立复核 | 复核 | 校验 |
|
||||
```
|
||||
|
||||
live view 会把它变成 Run All、Step、每单元内核、journal 与状态面板;Program 模式仍然把文件当单个程序运行。
|
||||
|
||||
文档能被发现、验证和复用时,才成为知识。OKF 提供可移植的 Markdown + YAML 形态;EKC 把仓库投影成 catalog L0–L4、图与工程 preflight。源 `.mq.md` 始终是唯一权威,生成物有标记、可重建。
|
||||
|
||||
| 循环 | 问题 |
|
||||
|---|---|
|
||||
| OKF | 人和 Agent 如何共享一页可读知识? |
|
||||
| EKC | 创建之前,应该复用哪些已有能力、决策、约束与失败? |
|
||||
| Preflight | REUSE → ADAPT → CREATE |
|
||||
|
||||
概念与命令见 [features/20-OKF与EKC.mq.md](features/20-OKF与EKC.mq.md)。
|
||||
|
||||
最后,再次欢迎你,尽情体验 marqdo 吧!
|
||||
|
||||
## 问候
|
||||
|
||||
@@ -11,6 +11,8 @@
|
||||
| [`keywords/`](keywords/) | 关键字与 L0 内置 |
|
||||
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联/插件/**自写回**/**子任务**;v0.1.2+ 内置于 CLI) |
|
||||
| [`features/`](features/) | 特性迭代(含对象、官方 `ext/`) |
|
||||
| [`features/19-foreign-notebook.mq.md`](features/19-foreign-notebook.mq.md) / [`19-外联Notebook.mq.md`](features/19-外联Notebook.mq.md) | 外联 v2 完整 Python 示例:probe / JSON call / 并行 / 持久内核 / 状态桥 / notebook |
|
||||
| [`features/20-okf-ekc.mq.md`](features/20-okf-ekc.mq.md) / [`20-OKF与EKC.mq.md`](features/20-OKF与EKC.mq.md) | 代码即文档、文档即知识:OKF 形态与 EKC 工程知识编译器 |
|
||||
|
||||
官方扩展(非 stdlib):`ext/llm`、`ext/agent`、`ext/web`、`ext/quantum`、`ext/linalg` — 见 `features/05-*.mq.md`、`06-*.mq.md`、`07-linalg.mq.md` / `07-线性代数.mq.md` 与 `doc/design/ext-*.md`。
|
||||
|
||||
|
||||
@@ -0,0 +1,183 @@
|
||||
---
|
||||
title: Foreign kernels v2 — a Python analysis notebook
|
||||
description: A complete Python data walkthrough with probe, JSON calls, parallel fan-out, persistent state, an explicit bridge and document-native notebook cells
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
This page is both a readable document and a runnable program. It uses the same file to show the foreign-kernel features added in v2: language probing, structured records, JSON in/out, parallel fan-out, a persistent Python kernel, and an explicit state bridge.
|
||||
|
||||
The data is intentionally small and deterministic, so every number below can be reproduced by running the page.
|
||||
|
||||
---
|
||||
|
||||
The input.
|
||||
|
||||
`orders` =
|
||||
|
||||
| @ | region | amount |
|
||||
|---|--------|--------|
|
||||
| 1 | 华东 | 120 |
|
||||
| 2 | 华东 | 300 |
|
||||
| 3 | 华南 | 90 |
|
||||
| 4 | 华南 | 140 |
|
||||
| 5 | 华北 | 220 |
|
||||
| 6 | 西部 | 80 |
|
||||
|
||||
---
|
||||
|
||||
Probe Python before using it.
|
||||
|
||||
**python = > foreign.probe lang="python"**
|
||||
|
||||
> print text=[ok](`python`)
|
||||
> print text=[version](`python`)
|
||||
|
||||
The probe record also carries `cmd`, `path` and `error`, so a site can explain a missing interpreter instead of producing a blank cell.
|
||||
|
||||
---
|
||||
|
||||
A JSON call. Python reads the table as JSON, groups it, and writes one JSON result.
|
||||
|
||||
`analyze` =
|
||||
```python
|
||||
import json
|
||||
import statistics
|
||||
import sys
|
||||
|
||||
rows = json.load(sys.stdin)
|
||||
by_region = {}
|
||||
for row in rows:
|
||||
by_region.setdefault(row["region"], []).append(float(row["amount"]))
|
||||
|
||||
summary = []
|
||||
for region, values in sorted(by_region.items()):
|
||||
mean = statistics.mean(values)
|
||||
sd = statistics.pstdev(values) or 1.0
|
||||
summary.append({
|
||||
"region": region,
|
||||
"orders": len(values),
|
||||
"total": round(sum(values), 2),
|
||||
"mean": round(mean, 2),
|
||||
"z_span": round((max(values) - mean) / sd, 3),
|
||||
})
|
||||
|
||||
print(json.dumps({
|
||||
"regions": summary,
|
||||
"total": round(sum(float(row["amount"]) for row in rows), 2),
|
||||
"count": len(rows),
|
||||
}, ensure_ascii=False))
|
||||
```
|
||||
|
||||
**result = > foreign.call code=`analyze` input=`orders`**
|
||||
|
||||
> print text=[count](`result`)
|
||||
> print text=[total](`result`)
|
||||
> print text=[region]([1]([regions](`result`)))
|
||||
> print text=[mean]([1]([regions](`result`)))
|
||||
|
||||
A call is JSON-in / JSON-out: the table is encoded on stdin, and the final stdout value is parsed into Marqdo values.
|
||||
|
||||
---
|
||||
|
||||
The same work as a structured record. `invoke` keeps stdout, stderr, exit code and timing even when the program fails.
|
||||
|
||||
**record = > foreign.invoke code=`analyze` input=`orders` output="json"**
|
||||
|
||||
> print text=[ok](`record`)
|
||||
> print text=[code](`record`)
|
||||
> print text=[ms](`record`)
|
||||
|
||||
Here `result` is already a parsed value, while `stdout` remains available for logging.
|
||||
|
||||
---
|
||||
|
||||
Persistent Python state. The first evaluation imports a module and creates a list; the second evaluation sees both.
|
||||
|
||||
**session = > foreign.session_open lang="python"**
|
||||
|
||||
**first = > foreign.session_eval id=`session` source="import math\nvalues = [3, 4, 5]"**
|
||||
|
||||
**second = > foreign.session_eval id=`session` source="round(math.sqrt(sum(value * value for value in values)), 3)"**
|
||||
|
||||
> print text=[result](`second`)
|
||||
|
||||
The kernel is strict and serial: evaluations do not interleave, and a timeout kills the process group.
|
||||
|
||||
---
|
||||
|
||||
The explicit state bridge. Values cross as JSON copies, never as shared object references.
|
||||
|
||||
**> foreign.session_set id=`session` name="threshold" value=2.5**
|
||||
|
||||
**threshold = > foreign.session_get id=`session` name="threshold"**
|
||||
|
||||
> print text=`threshold`
|
||||
|
||||
**> foreign.session_close id=`session`**
|
||||
|
||||
No implicit mirroring: if a variable is not pushed or pulled, the other side does not see it.
|
||||
|
||||
---
|
||||
|
||||
Parallel fan-out. Every input gets its own process; failures are isolated and order is preserved.
|
||||
|
||||
`increment` =
|
||||
```python
|
||||
import json
|
||||
import sys
|
||||
|
||||
value = json.load(sys.stdin)
|
||||
print(json.dumps(value + 1))
|
||||
```
|
||||
|
||||
`numbers` =
|
||||
|
||||
| value |
|
||||
|-------|
|
||||
| 1 |
|
||||
| 2 |
|
||||
| 3 |
|
||||
| 4 |
|
||||
|
||||
**bumped = > foreign.call_many code=`increment` inputs=`numbers` concurrency=4**
|
||||
|
||||
> print text=`bumped`
|
||||
|
||||
---
|
||||
|
||||
A document-native notebook. Named kernels and a session table are ordinary bound data tables, not fence metadata or YAML config.
|
||||
|
||||
```text
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | shared analysis |
|
||||
| 复核 | python | | isolated review |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | generate orders |
|
||||
| 计算指标 | 分析 | regions and totals |
|
||||
| 独立复核 | 复核 | read the JSON report |
|
||||
```
|
||||
|
||||
Live `view` renders these as cells with Run All, Step, per-cell kernel switching, a journal, dirty reload and a state panel. The same file still runs as a single program.
|
||||
|
||||
---
|
||||
|
||||
Why this stays readable.
|
||||
|
||||
| Layer | What the reader sees |
|
||||
|---|---|
|
||||
| Markdown | headings, prose, tables and fenced code |
|
||||
| Program | assignments, calls and return values |
|
||||
| Knowledge | frontmatter, links, task pages and generated catalog entries |
|
||||
|
||||
The foreign layer does not add syntax to the language. A fence is still a fence; a table is still a table.
|
||||
|
||||
For the lower-level API and safety defaults, read [`../../lib/foreign.mq.md`](../../lib/foreign.mq.md) and [`../../doc/design/foreign-kernel.md`](../../doc/design/foreign-kernel.md).
|
||||
@@ -0,0 +1,183 @@
|
||||
---
|
||||
title: 外联内核 v2 — Python 分析 Notebook
|
||||
description: 从 probe、JSON 调用、并行扇出、持久状态到显式桥与文档原生 notebook 单元的完整 Python 示例
|
||||
导入 外联:lib/外联.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这一页既是可读文档,也是可运行程序。它用同一份文件展示 v2 的外联内核能力:语言探测、结构化记录、JSON 进出、并行扇出、持久 Python 内核,以及显式状态桥。
|
||||
|
||||
数据故意保持小而确定,因此下面每个数字都可以通过运行本页复现。
|
||||
|
||||
---
|
||||
|
||||
输入数据。
|
||||
|
||||
`订单` =
|
||||
|
||||
| @ | 区域 | 金额 |
|
||||
|---|------|------|
|
||||
| 1 | 华东 | 120 |
|
||||
| 2 | 华东 | 300 |
|
||||
| 3 | 华南 | 90 |
|
||||
| 4 | 华南 | 140 |
|
||||
| 5 | 华北 | 220 |
|
||||
| 6 | 西部 | 80 |
|
||||
|
||||
---
|
||||
|
||||
先探测 Python。
|
||||
|
||||
**python = > 外联.探测 语言="python"**
|
||||
|
||||
> 打印 内容=[ok](`python`)
|
||||
> 打印 内容=[version](`python`)
|
||||
|
||||
探测记录还带 `cmd`、`path` 与 `error`,所以站点可以解释“解释器缺失”,而不是显示一个空白单元。
|
||||
|
||||
---
|
||||
|
||||
JSON 调用。Python 把表读成 JSON,按区域聚合,再写出一个 JSON 结果。
|
||||
|
||||
`分析` =
|
||||
```python
|
||||
import json
|
||||
import statistics
|
||||
import sys
|
||||
|
||||
rows = json.load(sys.stdin)
|
||||
by_region = {}
|
||||
for row in rows:
|
||||
by_region.setdefault(row["区域"], []).append(float(row["金额"]))
|
||||
|
||||
summary = []
|
||||
for region, values in sorted(by_region.items()):
|
||||
mean = statistics.mean(values)
|
||||
sd = statistics.pstdev(values) or 1.0
|
||||
summary.append({
|
||||
"region": region,
|
||||
"orders": len(values),
|
||||
"total": round(sum(values), 2),
|
||||
"mean": round(mean, 2),
|
||||
"z_span": round((max(values) - mean) / sd, 3),
|
||||
})
|
||||
|
||||
print(json.dumps({
|
||||
"regions": summary,
|
||||
"total": round(sum(float(row["金额"]) for row in rows), 2),
|
||||
"count": len(rows),
|
||||
}, ensure_ascii=False))
|
||||
```
|
||||
|
||||
**结果 = > 外联.调用 代码=`分析` 输入=`订单`**
|
||||
|
||||
> 打印 内容=[count](`结果`)
|
||||
> 打印 内容=[total](`结果`)
|
||||
> 打印 内容=[region]([1]([regions](`结果`)))
|
||||
> 打印 内容=[mean]([1]([regions](`结果`)))
|
||||
|
||||
调用是 JSON 进 / JSON 出:表编码到 stdin,stdout 的最后一个值再解析成 Marqdo 值。
|
||||
|
||||
---
|
||||
|
||||
同样的工作也可以保留成结构化记录。`执行` 即使进程失败也保留 stdout、stderr、退出码与耗时。
|
||||
|
||||
**记录 = > 外联.执行 代码=`分析` 输入=`订单` 输出="json"**
|
||||
|
||||
> 打印 内容=[ok](`记录`)
|
||||
> 打印 内容=[code](`记录`)
|
||||
> 打印 内容=[ms](`记录`)
|
||||
|
||||
这里 `result` 已经是解析后的值,同时 `stdout` 仍可用于日志。
|
||||
|
||||
---
|
||||
|
||||
持久 Python 状态。第一次求值导入模块并创建列表;第二次求值仍能看到两者。
|
||||
|
||||
**会话 = > 外联.会话开启 语言="python"**
|
||||
|
||||
**第一次 = > 外联.会话求值 标识=`会话` 源码="import math\nvalues = [3, 4, 5]"**
|
||||
|
||||
**第二次 = > 外联.会话求值 标识=`会话` 源码="round(math.sqrt(sum(value * value for value in values)), 3)"**
|
||||
|
||||
> 打印 内容=[result](`第二次`)
|
||||
|
||||
内核严格串行:求值不会交错,超时会杀掉进程组。
|
||||
|
||||
---
|
||||
|
||||
显式状态桥。值以 JSON 拷贝跨越边界,永远不是共享对象引用。
|
||||
|
||||
**> 外联.会话设值 标识=`会话` 名称="threshold" 值=2.5**
|
||||
|
||||
**阈值 = > 外联.会话取值 标识=`会话` 名称="threshold"**
|
||||
|
||||
> 打印 内容=`阈值`
|
||||
|
||||
**> 外联.会话关闭 标识=`会话`**
|
||||
|
||||
没有隐式镜像:没有 push / pull 的变量,另一边看不到。
|
||||
|
||||
---
|
||||
|
||||
并行扇出。每个输入都有独立进程;失败互相隔离,顺序保持不变。
|
||||
|
||||
`加一` =
|
||||
```python
|
||||
import json
|
||||
import sys
|
||||
|
||||
value = json.load(sys.stdin)
|
||||
print(json.dumps(value + 1))
|
||||
```
|
||||
|
||||
`数值` =
|
||||
|
||||
| value |
|
||||
|-------|
|
||||
| 1 |
|
||||
| 2 |
|
||||
| 3 |
|
||||
| 4 |
|
||||
|
||||
**加一后 = > 外联.批量调用 代码=`加一` 输入表=`数值` 并发=4**
|
||||
|
||||
> 打印 内容=`加一后`
|
||||
|
||||
---
|
||||
|
||||
文档原生 Notebook。命名内核和会话表都是普通绑定数据表,不是 fence 元数据或 YAML 配置。
|
||||
|
||||
```text
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | 共享分析 |
|
||||
| 复核 | python | | 独立复核 |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | 生成订单 |
|
||||
| 计算指标 | 分析 | 区域与总额 |
|
||||
| 独立复核 | 复核 | 读取 JSON 报告 |
|
||||
```
|
||||
|
||||
live `view` 会把这些渲染成带 Run All、Step、切换内核、journal、dirty reload 和状态面板的单元。同一份文件仍可作为单个程序运行。
|
||||
|
||||
---
|
||||
|
||||
为什么它仍然可读。
|
||||
|
||||
| 层 | 读者看到什么 |
|
||||
|---|---|
|
||||
| Markdown | 标题、叙述、表格与围栏代码 |
|
||||
| 程序 | 赋值、调用与返回值 |
|
||||
| 知识 | frontmatter、链接、任务页与生成的 catalog 条目 |
|
||||
|
||||
外联层没有给语言新增语法。围栏还是围栏,表还是表。
|
||||
|
||||
底层 API 与安全默认值见 [`../../lib/外联.mq.md`](../../lib/外联.mq.md) 与 [`../../doc/design/foreign-kernel.md`](../../doc/design/foreign-kernel.md)。
|
||||
@@ -0,0 +1,135 @@
|
||||
---
|
||||
title: 代码即文档,文档即知识 — OKF 与 EKC
|
||||
description: Marqdo 如何以一份可执行源为唯一权威,把它投影成 OKF 风格知识与 Engineering Knowledge Compiler 制品
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Marqdo 的宪法是「代码即文档,文档即知识库」。`.mq.md` 不是程序截图:它同时是可读源码、可执行单元和知识页。
|
||||
|
||||
这个承诺只有在知识始终从源派生时才成立。OKF 提供可移植知识包的形态;EKC 提供工程化投影。二者都不成为第二份权威。
|
||||
|
||||
---
|
||||
|
||||
OKF 的形,Marqdo 的义。
|
||||
|
||||
OKF(Open Knowledge Format)用 Markdown + YAML frontmatter 表示知识:一页一概念、路径即身份、链接成图、强制面刻意保持很小。Marqdo 借用这个形态,但正文是可执行语法。
|
||||
|
||||
因此概念页可以直接指向证明它的文件:
|
||||
|
||||
```yaml
|
||||
type: Capability
|
||||
title: 持久外联内核
|
||||
description: 在命名内核中运行 Python 或 Node 并保留状态
|
||||
resource: public/features/19-外联Notebook.mq.md
|
||||
status: stable
|
||||
verified:
|
||||
by: marqdo-knowledge/verify
|
||||
tags:
|
||||
- foreign
|
||||
- notebook
|
||||
```
|
||||
|
||||
同一页可以在编辑器里读、从 catalog 链接、被 Agent 查询,也可以直接运行。未知字段保留;未知类型降级为可读正文。概念页不是源文件的复制品。
|
||||
|
||||
---
|
||||
|
||||
哪些是生成的,哪些不是。
|
||||
|
||||
| 层 | 作者 | 职责 |
|
||||
|---|---|---|
|
||||
| 源 | 人或编码 Agent | .mq.md;唯一语义权威 |
|
||||
| 目录包 | marqdo catalog | 模块、符号、能力与图投影 |
|
||||
| 任务知识 | plan 晋升 | 任务、技能与可执行资源包 |
|
||||
| 静态站 | marqdo view output | 人读 HTML,永远不是权威 |
|
||||
|
||||
生成物带 GENERATED 标记,可以删除重建;没有它们源树仍能运行。Catalog 是索引,不是语言特性。
|
||||
|
||||
---
|
||||
|
||||
EKC:Engineering Knowledge Compiler。
|
||||
|
||||
EKC 把仓库投影成工程知识系统,并在 Agent 写新代码前提供 preflight:
|
||||
|
||||
```text
|
||||
.mq.md ──► EKC ──► catalog L0–L4
|
||||
├─ graph
|
||||
├─ context pack
|
||||
└─ Agent preflight
|
||||
```
|
||||
|
||||
| 层 | 知识 | 例子 |
|
||||
|---|---|---|
|
||||
| L0 Repository | 语言、规模、根目录 | 仓库总览 |
|
||||
| L1 Module | imports、exports、职责 | 外联内核模块 |
|
||||
| L2 Symbol | 签名、调用、指纹 | Python 分析函数 |
|
||||
| L3 Capability | 工程能做什么 | 运行持久外联内核 |
|
||||
| L4 Knowledge | 决策、约束、失败 | 为什么状态桥必须显式 |
|
||||
|
||||
图记录 implements、uses、depends_on、tested_by、documented_by、constrained_by、decided_by、supersedes、conflicts_with、deprecated_by 等关系。Agent 先沿图发现已有能力,而不是重新造轮子。
|
||||
|
||||
---
|
||||
|
||||
Engineering First Information:先发现,再创建。
|
||||
|
||||
复用协议是硬顺序:
|
||||
|
||||
```text
|
||||
REUSE → ADAPT → CREATE
|
||||
```
|
||||
|
||||
preflight 可以在实现开始前返回已有能力、API、约束、决策与失败经验。知识图缺失时返回明确的 missing_knowledge,而不是静默编造。
|
||||
|
||||
五条原则:
|
||||
|
||||
| # | 原则 |
|
||||
|---|---|
|
||||
| 1 | Discover before Create |
|
||||
| 2 | Reuse before Adapt |
|
||||
| 3 | Adapt before Duplicate |
|
||||
| 4 | Verify before Promote |
|
||||
| 5 | Code changes update knowledge |
|
||||
|
||||
---
|
||||
|
||||
命令。
|
||||
|
||||
```bash
|
||||
# 把仓库投影成 catalog + EKC 制品
|
||||
marqdo catalog .
|
||||
|
||||
# 写代码前先问:已经有了什么?
|
||||
marqdo knowledge preflight "增加一个持久外联内核"
|
||||
marqdo find "外联 会话"
|
||||
marqdo reuse "实现 JSON 并行扇出"
|
||||
|
||||
# 看一次修改会影响什么
|
||||
marqdo impact public/features/19-外联Notebook.mq.md
|
||||
|
||||
# 校验知识投影
|
||||
marqdo knowledge verify
|
||||
```
|
||||
|
||||
`marqdo catalog` 保留人读的 `index.md` 与模块页;EKC 在 `.marqdo/` 下增加 L0–L4。两者都从同一棵源树生成。
|
||||
|
||||
---
|
||||
|
||||
每个声称的能力都必须有可执行资源。
|
||||
|
||||
一个知识页说“这个工程能分析订单”,就必须指向一个真正能跑的 `.mq.md` 资源。这是 OKF 形态的笔记与可执行知识系统的区别。
|
||||
|
||||
在外联示例里,页面本身就是证明:Python 调用、持久内核和状态桥都从读者正在看的同一份 Markdown 源运行。没有另一个会漂移的演示项目。
|
||||
|
||||
---
|
||||
|
||||
继续阅读。
|
||||
|
||||
OKF 设计:[OKF 设计](../../doc/design/okf.md)
|
||||
|
||||
Engineering Knowledge Compiler:[Engineering Knowledge Compiler](../../doc/design/engineering-knowledge.md)
|
||||
|
||||
Catalog CLI:[Catalog CLI](../../doc/design/catalog-cli.md)
|
||||
|
||||
OKF 与 Marqdo 调研:[OKF 与 Marqdo 调研](../../doc/research/okf-and-marqdo.md)
|
||||
|
||||
外联 Notebook 示例:[外联 Notebook 示例](19-外联Notebook.mq.md)
|
||||
@@ -0,0 +1,135 @@
|
||||
---
|
||||
title: Code as documentation, documentation as knowledge — OKF and EKC
|
||||
description: How Marqdo keeps one executable source of truth while projecting it into OKF-style knowledge and Engineering Knowledge Compiler artifacts
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Marqdo's constitution is code as documentation and documentation as knowledge. A `.mq.md` file is not a screenshot of a program: it is the readable source, the executable unit and the knowledge page at the same time.
|
||||
|
||||
That claim matters only if the knowledge stays derived from the source. OKF gives us the shape of a portable knowledge bundle; EKC gives us the engineering projection. Neither becomes a second source of truth.
|
||||
|
||||
---
|
||||
|
||||
OKF shape, Marqdo meaning.
|
||||
|
||||
OKF (Open Knowledge Format) describes knowledge as Markdown pages with YAML frontmatter: one concept per page, path as identity, links as graph, a deliberately small required surface. Marqdo borrows that shape, but its body is executable.
|
||||
|
||||
A concept page can therefore point at the exact file that proves it:
|
||||
|
||||
```yaml
|
||||
type: Capability
|
||||
title: Persistent foreign kernels
|
||||
description: Run Python or Node in a named, stateful kernel
|
||||
resource: public/features/19-foreign-notebook.mq.md
|
||||
status: stable
|
||||
verified:
|
||||
by: marqdo-knowledge/verify
|
||||
tags:
|
||||
- foreign
|
||||
- notebook
|
||||
```
|
||||
|
||||
The same page can be opened in an editor, linked from a catalog, queried by an agent, and executed. Unknown fields are preserved; unknown types degrade to readable prose. The page is a concept, not a copy of one.
|
||||
|
||||
---
|
||||
|
||||
What is generated, and what is not.
|
||||
|
||||
| Layer | Author | Role |
|
||||
|---|---|---|
|
||||
| Source | person or coding agent | .mq.md; the only semantic authority |
|
||||
| Catalog | marqdo catalog | module, symbol, capability and graph projection |
|
||||
| Task knowledge | plan promotion | task, skill and executable resource bundle |
|
||||
| Static site | marqdo view output | human-readable HTML, never an authority |
|
||||
|
||||
Generated artifacts are marked GENERATED and can be deleted and rebuilt. The source tree still runs without them. A catalog is an index, not a language feature.
|
||||
|
||||
---
|
||||
|
||||
EKC: the Engineering Knowledge Compiler.
|
||||
|
||||
EKC projects the repository into an engineering knowledge system, then exposes it through a preflight before an agent writes new code:
|
||||
|
||||
```text
|
||||
.mq.md ──► EKC ──► catalog L0–L4
|
||||
├─ graph
|
||||
├─ context pack
|
||||
└─ Agent preflight
|
||||
```
|
||||
|
||||
| Layer | Knowledge | Example |
|
||||
|---|---|---|
|
||||
| L0 Repository | language, size, roots | repository summary |
|
||||
| L1 Module | imports, exports, responsibility | a foreign kernel module |
|
||||
| L2 Symbol | signature, calls, fingerprint | a Python analysis function |
|
||||
| L3 Capability | what the project can do | run a persistent foreign kernel |
|
||||
| L4 Knowledge | decisions, constraints, failures | why the bridge is explicit |
|
||||
|
||||
The graph records relations such as implements, uses, depends_on, tested_by, documented_by, constrained_by, decided_by, supersedes, conflicts_with and deprecated_by. That graph is how an agent discovers existing capability before inventing a duplicate.
|
||||
|
||||
---
|
||||
|
||||
Engineering First Information: discover before create.
|
||||
|
||||
The reuse protocol is a hard order:
|
||||
|
||||
```text
|
||||
REUSE → ADAPT → CREATE
|
||||
```
|
||||
|
||||
A preflight can return existing capabilities, APIs, constraints, decisions and failure notes before a new implementation starts. If the knowledge graph is missing, the result is an explicit missing_knowledge state, not a silent fabrication.
|
||||
|
||||
The five principles are:
|
||||
|
||||
| # | Principle |
|
||||
|---|---|
|
||||
| 1 | Discover before Create |
|
||||
| 2 | Reuse before Adapt |
|
||||
| 3 | Adapt before Duplicate |
|
||||
| 4 | Verify before Promote |
|
||||
| 5 | Code changes update knowledge |
|
||||
|
||||
---
|
||||
|
||||
The commands.
|
||||
|
||||
```bash
|
||||
# Project the repository into catalog + EKC artifacts
|
||||
marqdo catalog .
|
||||
|
||||
# Ask what already exists before writing code
|
||||
marqdo knowledge preflight "add a persistent foreign kernel"
|
||||
marqdo find "foreign session"
|
||||
marqdo reuse "implement JSON fan-out"
|
||||
|
||||
# See what a change would touch
|
||||
marqdo impact public/features/19-foreign-notebook.mq.md
|
||||
|
||||
# Validate the knowledge projection
|
||||
marqdo knowledge verify
|
||||
```
|
||||
|
||||
`marqdo catalog` keeps the human-readable `index.md` and module pages; EKC adds L0–L4 files under `.marqdo/`. Both are generated from the same source tree.
|
||||
|
||||
---
|
||||
|
||||
Every claimed capability has an executable resource.
|
||||
|
||||
A knowledge page that says “this project can analyze orders” must point to a `.mq.md` resource that actually runs. That is the difference between an OKF-shaped note and an executable knowledge system.
|
||||
|
||||
In the foreign example, the page itself is the proof: the Python call, the persistent kernel and the state bridge all run from the same Markdown source that a reader is looking at. There is no separate demo project to drift out of sync.
|
||||
|
||||
---
|
||||
|
||||
Read more.
|
||||
|
||||
OKF design: [OKF design](../../doc/design/okf.md)
|
||||
|
||||
Engineering Knowledge Compiler: [Engineering Knowledge Compiler](../../doc/design/engineering-knowledge.md)
|
||||
|
||||
Catalog CLI: [Catalog CLI](../../doc/design/catalog-cli.md)
|
||||
|
||||
OKF and Marqdo research: [OKF and Marqdo research](../../doc/research/okf-and-marqdo.md)
|
||||
|
||||
Foreign notebook example: [Foreign notebook example](19-foreign-notebook.mq.md)
|
||||
@@ -11,7 +11,7 @@ English-named files export English APIs; Chinese-named files export Chinese APIs
|
||||
|
||||
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 / 网络), math (math / 数学), foreign (foreign / 外联), plugin (plugin / 插件), writeback (writeback / 自写回), subtask (subtask / 子任务).
|
||||
Modules: text (text / 文本), table (table / 表), files (fs / 文件), time (time / 时间), system (sys / 系统), json (json only), net (net / 网络), math (math / 数学), foreign (foreign / 外联), plugin (plugin / 插件), writeback (writeback / 自写回), subtask (subtask / 子任务). Foreign v2 adds structured invoke records, JSON calls, parallel fan-out, persistent Python/Node kernels, an explicit state bridge and document-native notebook sessions — see stdlib/foreign.mq.md and features/19-foreign-notebook.mq.md.
|
||||
|
||||
From v0.1.2, official `lib/*.mq.md` is embedded in the `marqdo` binary (disk `lib/` or `MARQDO_LIB` still overrides). Standalone `.exe` works without a separate stdlib zip.
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ description: 如何导入官方 lib 模块
|
||||
|
||||
导入即表示要用对应能力,无需再加允许旗标。marqdo view 或静态导出里,退出会软失败、长睡眠会被钳制,以免拖垮控制台。
|
||||
|
||||
模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)、数学(math / 数学)、外联(foreign / 外联)、插件(plugin / 插件)、自写回(writeback / 自写回)、子任务(subtask / 子任务)。
|
||||
模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)、数学(math / 数学)、外联(foreign / 外联)、插件(plugin / 插件)、自写回(writeback / 自写回)、子任务(subtask / 子任务)。外联 v2 新增结构化执行记录、JSON 调用、并行扇出、Python/Node 持久内核、显式状态桥与文档原生 notebook 会话 — 见 stdlib/外联.mq.md 与 features/19-外联Notebook.mq.md。
|
||||
|
||||
自 v0.1.2 起,官方 `lib/*.mq.md` 内置于 `marqdo` 二进制(磁盘 `lib/` 或 `MARQDO_LIB` 仍可覆盖)。单独下载 `.exe` 即可导入标准库,无需再解压 stdlib 包。
|
||||
|
||||
|
||||
+134
-9
@@ -1,20 +1,145 @@
|
||||
---
|
||||
title: lib/foreign — external languages
|
||||
description: Run local interpreters from Marqdo (English)
|
||||
title: lib/foreign — foreign kernels v2
|
||||
description: Structured execution, JSON calls, parallel fan-out, persistent kernels and an explicit state bridge
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Import lib/foreign.mq.md. Bind a code fence like a formula: empty-RHS assign then a ```lang block. The value type is code. Call run code=`name` to execute via your local interpreter. run_lang runs an inline source string.
|
||||
`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.
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
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.
|
||||
|
||||
**node = > foreign.probe lang="node"**
|
||||
|
||||
> print text=[ok](`node`)
|
||||
> print text=[version](`node`)
|
||||
|
||||
`probe` returns `{lang, cmd, path, ok, version, error}`. Omit `lang` to inspect every known language.
|
||||
|
||||
---
|
||||
|
||||
A structured record, not just stdout.
|
||||
|
||||
`marker` =
|
||||
```node
|
||||
console.log("hello from a foreign kernel");
|
||||
```
|
||||
|
||||
Default command is python (Windows) or python3 (Unix). Override with set_cmd, env MARQDO_FOREIGN_PYTHON, or the command box in live view. Failures ask you to check that configuration.
|
||||
**record = > foreign.invoke code=`marker`**
|
||||
|
||||
**`out` = [foreign.run] code=`hi`**
|
||||
> print text=[ok](`record`)
|
||||
> print text=[stdout](`record`)
|
||||
> print text=[code](`record`)
|
||||
|
||||
> print text=`out`
|
||||
`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.
|
||||
|
||||
`double` =
|
||||
```node
|
||||
let input = "";
|
||||
process.stdin.on("data", chunk => { input += chunk; });
|
||||
process.stdin.on("end", () => {
|
||||
console.log(JSON.stringify(JSON.parse(input) * 2));
|
||||
});
|
||||
```
|
||||
|
||||
**single = > foreign.call code=`double` input=21**
|
||||
|
||||
> 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 |
|
||||
|
||||
**doubled = > foreign.call_many code=`double` inputs=`numbers` concurrency=4**
|
||||
|
||||
> print text=`doubled`
|
||||
|
||||
`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.
|
||||
|
||||
**session = > foreign.session_open lang="node"**
|
||||
|
||||
**first = > foreign.session_eval id=`session` source="let total = 0; for (let i = 1; i <= 5; i += 1) total += i;"**
|
||||
|
||||
**second = > foreign.session_eval id=`session` source="total * 2"**
|
||||
|
||||
> print text=[result](`second`)
|
||||
|
||||
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.
|
||||
|
||||
**> foreign.session_set id=`session` name="rate" value=0.08**
|
||||
|
||||
**rate = > foreign.session_get id=`session` name="rate"**
|
||||
|
||||
> print text=`rate`
|
||||
|
||||
**> foreign.session_close id=`session`**
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
Notebook sessions.
|
||||
|
||||
A document can declare named kernels and a cell order without new Markdown markers:
|
||||
|
||||
```text
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | shared analysis |
|
||||
| 复核 | python | | isolated review |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | write state |
|
||||
| 计算指标 | 分析 | read state |
|
||||
| 独立复核 | 复核 | isolated kernel |
|
||||
```
|
||||
|
||||
Live `view` then adds Run All, Step, kernel switching, a journal and per-cell state. See the complete Python walkthrough in [`features/19-foreign-notebook.mq.md`](../features/19-foreign-notebook.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 | file sandbox root; no implicit escape |
|
||||
| Parallelism | capped fan-out; each item isolated |
|
||||
|
||||
Read the full API in [../../lib/foreign.mq.md](../../lib/foreign.mq.md) and the design in [../../doc/design/foreign-kernel.md](../../doc/design/foreign-kernel.md).
|
||||
+134
-9
@@ -1,20 +1,145 @@
|
||||
---
|
||||
title: lib/外联 — 外部语言
|
||||
description: 从 Marqdo 调用本机解释器(中文)
|
||||
title: lib/外联 — 外联内核 v2
|
||||
description: 结构化执行、JSON 调用、并行扇出、持久内核与显式状态桥
|
||||
导入 外联:lib/外联.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
导入 lib/外联.mq.md。代码围栏与公式同构:空 RHS 赋值后跟 lang 代码块,得到 code 类型。用 运行 代码=`名` 调用本机解释器。
|
||||
`lib/外联` 用本机解释器运行代码围栏和内联源码。v2 不改 Markdown 表面,新增结构化记录、JSON 进出、并行扇出、Python/Node 持久内核和显式状态桥。
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
文件仍然是一篇文档:绑定的代码围栏是可读的 Markdown,`外联.*` 把它变成可执行单元。
|
||||
|
||||
---
|
||||
|
||||
先探测,再运行。
|
||||
|
||||
**node = > 外联.探测 语言="node"**
|
||||
|
||||
> 打印 内容=[ok](`node`)
|
||||
> 打印 内容=[version](`node`)
|
||||
|
||||
`探测` 返回 `{lang, cmd, path, ok, version, error}`。省略语言时探测所有已知语言。
|
||||
|
||||
---
|
||||
|
||||
结构化记录,而不只是 stdout。
|
||||
|
||||
`标记` =
|
||||
```node
|
||||
console.log("来自外联内核的问候");
|
||||
```
|
||||
|
||||
默认命令可用 设置命令 或 MARQDO_FOREIGN_PYTHON 覆盖;live view 里可改命令框再点 Run。
|
||||
**记录 = > 外联.执行 代码=`标记`**
|
||||
|
||||
**`out` = [外联.运行] 代码=`hi`**
|
||||
> 打印 内容=[ok](`记录`)
|
||||
> 打印 内容=[stdout](`记录`)
|
||||
> 打印 内容=[code](`记录`)
|
||||
|
||||
> print text=`out`
|
||||
`执行` 在进程失败时不抛错,而是在一条记录里给出 `ok`、`code`、`stdout`、`stderr`、`ms`、`timed_out`、`truncated`、`result` 与 `error`。
|
||||
|
||||
---
|
||||
|
||||
JSON 进,JSON 出。
|
||||
|
||||
`双倍` =
|
||||
```node
|
||||
let input = "";
|
||||
process.stdin.on("data", chunk => { input += chunk; });
|
||||
process.stdin.on("end", () => {
|
||||
console.log(JSON.stringify(JSON.parse(input) * 2));
|
||||
});
|
||||
```
|
||||
|
||||
**单个 = > 外联.调用 代码=`双倍` 输入=21**
|
||||
|
||||
> 打印 内容=`单个`
|
||||
|
||||
输入编码成 JSON 写到 stdin;stdout 的最后一个值再解析成 JSON。想同时保留原始记录时,用 `执行` 的 `输出="json"`。
|
||||
|
||||
---
|
||||
|
||||
并行扇出。
|
||||
|
||||
`数值表` =
|
||||
|
||||
| 数值 |
|
||||
|------|
|
||||
| 1 |
|
||||
| 2 |
|
||||
| 3 |
|
||||
| 4 |
|
||||
|
||||
**翻倍 = > 外联.批量调用 代码=`双倍` 输入表=`数值表` 并发=4**
|
||||
|
||||
> 打印 内容=`翻倍`
|
||||
|
||||
`批量调用` 对每个输入独立运行同一程序,保持输入顺序并返回解析后的 JSON 列表;`批量运行` 对完整 invoke 选项表做同样的事。
|
||||
|
||||
---
|
||||
|
||||
持久内核。
|
||||
|
||||
**会话 = > 外联.会话开启 语言="node"**
|
||||
|
||||
**第一次 = > 外联.会话求值 标识=`会话` 源码="let total = 0; for (let i = 1; i <= 5; i += 1) total += i;"**
|
||||
|
||||
**第二次 = > 外联.会话求值 标识=`会话` 源码="total * 2"**
|
||||
|
||||
> 打印 内容=[result](`第二次`)
|
||||
|
||||
第一次求值创建的变量会保留到第二次。内核不是 shell:用 `会话求值`、`会话取值`、`会话变量`,最后 `会话关闭`。
|
||||
|
||||
---
|
||||
|
||||
显式状态桥。
|
||||
|
||||
**> 外联.会话设值 标识=`会话` 名称="rate" 值=0.08**
|
||||
|
||||
**利率 = > 外联.会话取值 标识=`会话` 名称="rate"**
|
||||
|
||||
> 打印 内容=`利率`
|
||||
|
||||
**> 外联.会话关闭 标识=`会话`**
|
||||
|
||||
这是 JSON 拷贝,不是共享内存:内核收到一个值,Marqdo 取回一个值。没有隐式镜像,也没有隐藏的全局命名空间。
|
||||
|
||||
---
|
||||
|
||||
Notebook 会话。
|
||||
|
||||
文档可以直接声明命名内核和单元顺序,不需要新增 Markdown 标记:
|
||||
|
||||
```text
|
||||
`内核表` =
|
||||
|
||||
| 名称 | 语言 | 命令 | 说明 |
|
||||
|------|------|------|------|
|
||||
| 分析 | python | | 共享分析 |
|
||||
| 复核 | python | | 独立复核 |
|
||||
|
||||
`会话表` =
|
||||
|
||||
| 单元 | 内核 | 说明 |
|
||||
|------|------|------|
|
||||
| 准备数据 | 分析 | 写入状态 |
|
||||
| 计算指标 | 分析 | 读取状态 |
|
||||
| 独立复核 | 复核 | 隔离内核 |
|
||||
```
|
||||
|
||||
live `view` 会提供 Run All、Step、切换内核、journal 和单元状态。完整 Python 示例见 [`features/19-外联Notebook.mq.md`](../features/19-外联Notebook.mq.md)。
|
||||
|
||||
---
|
||||
|
||||
安全默认值。
|
||||
|
||||
| 边界 | 默认 |
|
||||
|---|---|
|
||||
| 执行 | 需要宿主执行能力 |
|
||||
| Shell | 不经过 shell;参数显式切分 |
|
||||
| 输出 | 有界,带 truncated |
|
||||
| 超时 | Unix 杀进程组 / Windows taskkill /T |
|
||||
| 工作目录 | 文件沙箱根目录;不隐式越界 |
|
||||
| 并行 | 扇出有上限;每个任务隔离 |
|
||||
|
||||
完整 API 见 [../../lib/外联.mq.md](../../lib/外联.mq.md),设计见 [../../doc/design/foreign-kernel.md](../../doc/design/foreign-kernel.md)。
|
||||
Reference in new issue
Block a user