From e6f05c774828829bd34df2d3596f6917dea56f84 Mon Sep 17 00:00:00 2001 From: cflmy Date: Sun, 18 Oct 2026 03:15:34 +0800 Subject: [PATCH] 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. --- CHANGELOG.md | 1 + public/00-welcome.mq.md | 53 +++++++ public/00-欢迎.mq.md | 53 +++++++ public/README.md | 2 + public/features/19-foreign-notebook.mq.md | 183 ++++++++++++++++++++++ public/features/19-外联Notebook.mq.md | 183 ++++++++++++++++++++++ public/features/20-OKF与EKC.mq.md | 135 ++++++++++++++++ public/features/20-okf-ekc.mq.md | 135 ++++++++++++++++ public/stdlib/00-overview.mq.md | 2 +- public/stdlib/00-索引.mq.md | 2 +- public/stdlib/foreign.mq.md | 143 +++++++++++++++-- public/stdlib/外联.mq.md | 143 +++++++++++++++-- 12 files changed, 1015 insertions(+), 20 deletions(-) create mode 100644 public/features/19-foreign-notebook.mq.md create mode 100644 public/features/19-外联Notebook.mq.md create mode 100644 public/features/20-OKF与EKC.mq.md create mode 100644 public/features/20-okf-ekc.mq.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b240908..b2aa07e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 清理。 diff --git a/public/00-welcome.mq.md b/public/00-welcome.mq.md index fc964b7..5a7d412 100644 --- a/public/00-welcome.mq.md +++ b/public/00-welcome.mq.md @@ -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 diff --git a/public/00-欢迎.mq.md b/public/00-欢迎.mq.md index 5cbb415..0481808 100644 --- a/public/00-欢迎.mq.md +++ b/public/00-欢迎.mq.md @@ -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 吧! ## 问候 diff --git a/public/README.md b/public/README.md index f2ad747..8a5079e 100644 --- a/public/README.md +++ b/public/README.md @@ -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`。 diff --git a/public/features/19-foreign-notebook.mq.md b/public/features/19-foreign-notebook.mq.md new file mode 100644 index 0000000..a0fc819 --- /dev/null +++ b/public/features/19-foreign-notebook.mq.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). diff --git a/public/features/19-外联Notebook.mq.md b/public/features/19-外联Notebook.mq.md new file mode 100644 index 0000000..05d7adb --- /dev/null +++ b/public/features/19-外联Notebook.mq.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)。 diff --git a/public/features/20-OKF与EKC.mq.md b/public/features/20-OKF与EKC.mq.md new file mode 100644 index 0000000..ce3d3ce --- /dev/null +++ b/public/features/20-OKF与EKC.mq.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) diff --git a/public/features/20-okf-ekc.mq.md b/public/features/20-okf-ekc.mq.md new file mode 100644 index 0000000..71eb779 --- /dev/null +++ b/public/features/20-okf-ekc.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) diff --git a/public/stdlib/00-overview.mq.md b/public/stdlib/00-overview.mq.md index 0d3b428..40d4798 100644 --- a/public/stdlib/00-overview.mq.md +++ b/public/stdlib/00-overview.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. diff --git a/public/stdlib/00-索引.mq.md b/public/stdlib/00-索引.mq.md index 1e2fd4e..fabc094 100644 --- a/public/stdlib/00-索引.mq.md +++ b/public/stdlib/00-索引.mq.md @@ -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 包。 diff --git a/public/stdlib/foreign.mq.md b/public/stdlib/foreign.mq.md index 4166a65..d5f79cc 100644 --- a/public/stdlib/foreign.mq.md +++ b/public/stdlib/foreign.mq.md @@ -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). diff --git a/public/stdlib/外联.mq.md b/public/stdlib/外联.mq.md index 36bfe51..0456ac5 100644 --- a/public/stdlib/外联.mq.md +++ b/public/stdlib/外联.mq.md @@ -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)。