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:
cflmy committed 2026-10-18 03:15:34 +08:00
1 parent 81f9ea0072
commit e6f05c7748
12 files changed
+1015 -20

No files matched your search

+1
View File
@@ -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 清理。
+53
View File
@@ -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
+53
View File
@@ -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 吧!
## 问候
+2
View File
@@ -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`。
+183
View File
@@ -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).
+183
View File
@@ -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)。
+135
View File
@@ -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)
+135
View File
@@ -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)
+1 -1
View File
@@ -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.
+1 -1
View File
@@ -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
View File
@@ -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
View File
@@ -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)。